diff --git a/.all-contributorsrc b/.all-contributorsrc
index f57081a2f..a8e7fafee 100644
--- a/.all-contributorsrc
+++ b/.all-contributorsrc
@@ -628,6 +628,69 @@
       "contributions": [
         "bug"
       ]
+    },
+    {
+      "login": "ZakaryaCH",
+      "name": "ZakaryaCH",
+      "avatar_url": "https://avatars.githubusercontent.com/u/45012800?v=4",
+      "profile": "https://github.com/ZakaryaCH",
+      "contributions": [
+        "bug"
+      ]
+    },
+    {
+      "login": "jboeijenga",
+      "name": "Jasper Boeijenga",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1516438?v=4",
+      "profile": "https://github.com/jboeijenga",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "mrfelton",
+      "name": "Tom Kirkpatrick",
+      "avatar_url": "https://avatars.githubusercontent.com/u/200251?v=4",
+      "profile": "https://kirkdesigns.co.uk",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "Machul84126",
+      "name": "Machul",
+      "avatar_url": "https://avatars.githubusercontent.com/u/128227109?v=4",
+      "profile": "https://github.com/Machul84126",
+      "contributions": [
+        "bug"
+      ]
+    },
+    {
+      "login": "ugostack",
+      "name": "ugostack",
+      "avatar_url": "https://avatars.githubusercontent.com/u/81093728?v=4",
+      "profile": "https://github.com/ugostack",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "jdebarochez",
+      "name": "Jean de Barochez",
+      "avatar_url": "https://avatars.githubusercontent.com/u/3436890?v=4",
+      "profile": "https://github.com/jdebarochez",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "cog06",
+      "name": "cog06",
+      "avatar_url": "https://avatars.githubusercontent.com/u/44521955?v=4",
+      "profile": "https://github.com/cog06",
+      "contributions": [
+        "bug"
+      ]
     }
   ],
   "contributorsPerLine": 7,
diff --git a/.astro/content-assets.mjs b/.astro/content-assets.mjs
deleted file mode 100644
index 2b8b8234b..000000000
--- a/.astro/content-assets.mjs
+++ /dev/null
@@ -1 +0,0 @@
-export default new Map();
\ No newline at end of file
diff --git a/.astro/content-modules.mjs b/.astro/content-modules.mjs
deleted file mode 100644
index 2b8b8234b..000000000
--- a/.astro/content-modules.mjs
+++ /dev/null
@@ -1 +0,0 @@
-export default new Map();
\ No newline at end of file
diff --git a/.astro/content.d.ts b/.astro/content.d.ts
deleted file mode 100644
index c0082cc81..000000000
--- a/.astro/content.d.ts
+++ /dev/null
@@ -1,199 +0,0 @@
-declare module 'astro:content' {
-	export interface RenderResult {
-		Content: import('astro/runtime/server/index.js').AstroComponentFactory;
-		headings: import('astro').MarkdownHeading[];
-		remarkPluginFrontmatter: Record<string, any>;
-	}
-	interface Render {
-		'.md': Promise<RenderResult>;
-	}
-
-	export interface RenderedContent {
-		html: string;
-		metadata?: {
-			imagePaths: Array<string>;
-			[key: string]: unknown;
-		};
-	}
-}
-
-declare module 'astro:content' {
-	type Flatten<T> = T extends { [K: string]: infer U } ? U : never;
-
-	export type CollectionKey = keyof AnyEntryMap;
-	export type CollectionEntry<C extends CollectionKey> = Flatten<AnyEntryMap[C]>;
-
-	export type ContentCollectionKey = keyof ContentEntryMap;
-	export type DataCollectionKey = keyof DataEntryMap;
-
-	type AllValuesOf<T> = T extends any ? T[keyof T] : never;
-	type ValidContentEntrySlug<C extends keyof ContentEntryMap> = AllValuesOf<
-		ContentEntryMap[C]
-	>['slug'];
-
-	export type ReferenceDataEntry<
-		C extends CollectionKey,
-		E extends keyof DataEntryMap[C] = string,
-	> = {
-		collection: C;
-		id: E;
-	};
-	export type ReferenceContentEntry<
-		C extends keyof ContentEntryMap,
-		E extends ValidContentEntrySlug<C> | (string & {}) = string,
-	> = {
-		collection: C;
-		slug: E;
-	};
-	export type ReferenceLiveEntry<C extends keyof LiveContentConfig['collections']> = {
-		collection: C;
-		id: string;
-	};
-
-	/** @deprecated Use `getEntry` instead. */
-	export function getEntryBySlug<
-		C extends keyof ContentEntryMap,
-		E extends ValidContentEntrySlug<C> | (string & {}),
-	>(
-		collection: C,
-		// Note that this has to accept a regular string too, for SSR
-		entrySlug: E,
-	): E extends ValidContentEntrySlug<C>
-		? Promise<CollectionEntry<C>>
-		: Promise<CollectionEntry<C> | undefined>;
-
-	/** @deprecated Use `getEntry` instead. */
-	export function getDataEntryById<C extends keyof DataEntryMap, E extends keyof DataEntryMap[C]>(
-		collection: C,
-		entryId: E,
-	): Promise<CollectionEntry<C>>;
-
-	export function getCollection<C extends keyof AnyEntryMap, E extends CollectionEntry<C>>(
-		collection: C,
-		filter?: (entry: CollectionEntry<C>) => entry is E,
-	): Promise<E[]>;
-	export function getCollection<C extends keyof AnyEntryMap>(
-		collection: C,
-		filter?: (entry: CollectionEntry<C>) => unknown,
-	): Promise<CollectionEntry<C>[]>;
-
-	export function getLiveCollection<C extends keyof LiveContentConfig['collections']>(
-		collection: C,
-		filter?: LiveLoaderCollectionFilterType<C>,
-	): Promise<
-		import('astro').LiveDataCollectionResult<LiveLoaderDataType<C>, LiveLoaderErrorType<C>>
-	>;
-
-	export function getEntry<
-		C extends keyof ContentEntryMap,
-		E extends ValidContentEntrySlug<C> | (string & {}),
-	>(
-		entry: ReferenceContentEntry<C, E>,
-	): E extends ValidContentEntrySlug<C>
-		? Promise<CollectionEntry<C>>
-		: Promise<CollectionEntry<C> | undefined>;
-	export function getEntry<
-		C extends keyof DataEntryMap,
-		E extends keyof DataEntryMap[C] | (string & {}),
-	>(
-		entry: ReferenceDataEntry<C, E>,
-	): E extends keyof DataEntryMap[C]
-		? Promise<DataEntryMap[C][E]>
-		: Promise<CollectionEntry<C> | undefined>;
-	export function getEntry<
-		C extends keyof ContentEntryMap,
-		E extends ValidContentEntrySlug<C> | (string & {}),
-	>(
-		collection: C,
-		slug: E,
-	): E extends ValidContentEntrySlug<C>
-		? Promise<CollectionEntry<C>>
-		: Promise<CollectionEntry<C> | undefined>;
-	export function getEntry<
-		C extends keyof DataEntryMap,
-		E extends keyof DataEntryMap[C] | (string & {}),
-	>(
-		collection: C,
-		id: E,
-	): E extends keyof DataEntryMap[C]
-		? string extends keyof DataEntryMap[C]
-			? Promise<DataEntryMap[C][E]> | undefined
-			: Promise<DataEntryMap[C][E]>
-		: Promise<CollectionEntry<C> | undefined>;
-	export function getLiveEntry<C extends keyof LiveContentConfig['collections']>(
-		collection: C,
-		filter: string | LiveLoaderEntryFilterType<C>,
-	): Promise<import('astro').LiveDataEntryResult<LiveLoaderDataType<C>, LiveLoaderErrorType<C>>>;
-
-	/** Resolve an array of entry references from the same collection */
-	export function getEntries<C extends keyof ContentEntryMap>(
-		entries: ReferenceContentEntry<C, ValidContentEntrySlug<C>>[],
-	): Promise<CollectionEntry<C>[]>;
-	export function getEntries<C extends keyof DataEntryMap>(
-		entries: ReferenceDataEntry<C, keyof DataEntryMap[C]>[],
-	): Promise<CollectionEntry<C>[]>;
-
-	export function render<C extends keyof AnyEntryMap>(
-		entry: AnyEntryMap[C][string],
-	): Promise<RenderResult>;
-
-	export function reference<C extends keyof AnyEntryMap>(
-		collection: C,
-	): import('astro/zod').ZodEffects<
-		import('astro/zod').ZodString,
-		C extends keyof ContentEntryMap
-			? ReferenceContentEntry<C, ValidContentEntrySlug<C>>
-			: ReferenceDataEntry<C, keyof DataEntryMap[C]>
-	>;
-	// Allow generic `string` to avoid excessive type errors in the config
-	// if `dev` is not running to update as you edit.
-	// Invalid collection names will be caught at build time.
-	export function reference<C extends string>(
-		collection: C,
-	): import('astro/zod').ZodEffects<import('astro/zod').ZodString, never>;
-
-	type ReturnTypeOrOriginal<T> = T extends (...args: any[]) => infer R ? R : T;
-	type InferEntrySchema<C extends keyof AnyEntryMap> = import('astro/zod').infer<
-		ReturnTypeOrOriginal<Required<ContentConfig['collections'][C]>['schema']>
-	>;
-
-	type ContentEntryMap = {
-		
-	};
-
-	type DataEntryMap = {
-		
-	};
-
-	type AnyEntryMap = ContentEntryMap & DataEntryMap;
-
-	type ExtractLoaderTypes<T> = T extends import('astro/loaders').LiveLoader<
-		infer TData,
-		infer TEntryFilter,
-		infer TCollectionFilter,
-		infer TError
-	>
-		? { data: TData; entryFilter: TEntryFilter; collectionFilter: TCollectionFilter; error: TError }
-		: { data: never; entryFilter: never; collectionFilter: never; error: never };
-	type ExtractDataType<T> = ExtractLoaderTypes<T>['data'];
-	type ExtractEntryFilterType<T> = ExtractLoaderTypes<T>['entryFilter'];
-	type ExtractCollectionFilterType<T> = ExtractLoaderTypes<T>['collectionFilter'];
-	type ExtractErrorType<T> = ExtractLoaderTypes<T>['error'];
-
-	type LiveLoaderDataType<C extends keyof LiveContentConfig['collections']> =
-		LiveContentConfig['collections'][C]['schema'] extends undefined
-			? ExtractDataType<LiveContentConfig['collections'][C]['loader']>
-			: import('astro/zod').infer<
-					Exclude<LiveContentConfig['collections'][C]['schema'], undefined>
-				>;
-	type LiveLoaderEntryFilterType<C extends keyof LiveContentConfig['collections']> =
-		ExtractEntryFilterType<LiveContentConfig['collections'][C]['loader']>;
-	type LiveLoaderCollectionFilterType<C extends keyof LiveContentConfig['collections']> =
-		ExtractCollectionFilterType<LiveContentConfig['collections'][C]['loader']>;
-	type LiveLoaderErrorType<C extends keyof LiveContentConfig['collections']> = ExtractErrorType<
-		LiveContentConfig['collections'][C]['loader']
-	>;
-
-	export type ContentConfig = typeof import("../src/content.config.mjs");
-	export type LiveContentConfig = never;
-}
diff --git a/.astro/data-store.json b/.astro/data-store.json
deleted file mode 100644
index 5036073c0..000000000
--- a/.astro/data-store.json
+++ /dev/null
@@ -1 +0,0 @@
-[["Map",1,2],"meta::meta",["Map",3,4,5,6],"astro-version","5.15.3","astro-config-digest","{\"root\":{},\"srcDir\":{},\"publicDir\":{},\"outDir\":{},\"cacheDir\":{},\"compressHTML\":true,\"base\":\"/\",\"trailingSlash\":\"ignore\",\"output\":\"static\",\"scopedStyleStrategy\":\"attribute\",\"build\":{\"format\":\"directory\",\"client\":{},\"server\":{},\"assets\":\"_astro\",\"serverEntry\":\"entry.mjs\",\"redirects\":true,\"inlineStylesheets\":\"auto\",\"concurrency\":1},\"server\":{\"open\":false,\"host\":false,\"port\":4321,\"streaming\":true,\"allowedHosts\":[]},\"redirects\":{},\"image\":{\"endpoint\":{\"route\":\"/_image\"},\"service\":{\"entrypoint\":\"astro/assets/services/sharp\",\"config\":{}},\"domains\":[],\"remotePatterns\":[],\"responsiveStyles\":false},\"devToolbar\":{\"enabled\":true},\"markdown\":{\"syntaxHighlight\":{\"type\":\"shiki\",\"excludeLangs\":[\"math\"]},\"shikiConfig\":{\"langs\":[],\"langAlias\":{},\"theme\":\"github-dark\",\"themes\":{},\"wrap\":false,\"transformers\":[]},\"remarkPlugins\":[],\"rehypePlugins\":[],\"remarkRehype\":{},\"gfm\":true,\"smartypants\":true},\"security\":{\"checkOrigin\":true,\"allowedDomains\":[]},\"env\":{\"schema\":{},\"validateSecrets\":false},\"experimental\":{\"clientPrerender\":false,\"contentIntellisense\":false,\"headingIdCompat\":false,\"preserveScriptOrder\":false,\"liveContentCollections\":false,\"csp\":false,\"staticImportMetaEnv\":false,\"chromeDevtoolsWorkspace\":false,\"failOnPrerenderConflict\":false},\"legacy\":{\"collections\":false}}"]
\ No newline at end of file
diff --git a/.astro/settings.json b/.astro/settings.json
deleted file mode 100644
index 0afe29342..000000000
--- a/.astro/settings.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
-	"_variables": {
-		"lastUpdateCheck": 1763653789860
-	}
-}
\ No newline at end of file
diff --git a/.astro/types.d.ts b/.astro/types.d.ts
deleted file mode 100644
index f964fe0cf..000000000
--- a/.astro/types.d.ts
+++ /dev/null
@@ -1 +0,0 @@
-/// <reference types="astro/client" />
diff --git a/.changeset/config.json b/.changeset/config.json
index 8639ae567..46c604cd8 100644
--- a/.changeset/config.json
+++ b/.changeset/config.json
@@ -4,8 +4,12 @@
   "commit": false,
   "fixed": [],
   "linked": [],
-  "access": "restricted",
+  "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": []
+  "privatePackages": {
+    "version": false,
+    "tag": false
+  },
+  "ignore": ["@eventcatalog/dsl-playground"]
 }
diff --git a/.changeset/quiet-otters-shine.md b/.changeset/quiet-otters-shine.md
new file mode 100644
index 000000000..b43aa98f5
--- /dev/null
+++ b/.changeset/quiet-otters-shine.md
@@ -0,0 +1,5 @@
+---
+"@eventcatalog/core": patch
+---
+
+fix(core): serve proper favicons instead of the logo image
diff --git a/.claude/agents/code-review-uncommitted.md b/.claude/agents/code-review-uncommitted.md
new file mode 100644
index 000000000..4f90ff5b9
--- /dev/null
+++ b/.claude/agents/code-review-uncommitted.md
@@ -0,0 +1,103 @@
+---
+name: code-review-uncommitted
+description: "Use this agent when you want to review uncommitted changes in your working directory to ensure they follow project conventions, are maintainable, and could be simplified without changing behavior. This agent should be called before committing code to catch issues early.\\n\\nExamples:\\n\\n<example>\\nContext: The user has just finished writing a new feature and wants to ensure quality before committing.\\nuser: \"I've finished implementing the new event filtering feature, can you review my changes?\"\\nassistant: \"I'll use the code-review-uncommitted agent to review your uncommitted changes and ensure they follow project conventions.\"\\n<Task tool call to launch code-review-uncommitted agent>\\n</example>\\n\\n<example>\\nContext: The user wants a pre-commit review of their work.\\nuser: \"Review my code before I commit\"\\nassistant: \"Let me launch the code-review-uncommitted agent to analyze your uncommitted changes for convention compliance and simplification opportunities.\"\\n<Task tool call to launch code-review-uncommitted agent>\\n</example>\\n\\n<example>\\nContext: The user has been coding for a while and wants to check their work proactively.\\nuser: \"I've been working on this for a few hours, let's see if there are any issues\"\\nassistant: \"I'll use the code-review-uncommitted agent to review all your uncommitted changes and identify any convention violations or simplification opportunities.\"\\n<Task tool call to launch code-review-uncommitted agent>\\n</example>"
+model: opus
+color: purple
+---
+
+You are an expert code reviewer with deep expertise in software maintainability, clean code principles, and long-term codebase health. Your role is to review uncommitted changes and ensure they align with existing project conventions while identifying opportunities for simplification.
+
+## Your Primary Objectives
+
+1. **Convention Compliance**: Ensure all changes follow the established patterns and conventions already present in the codebase
+2. **Code Simplification**: Identify opportunities to simplify code without altering its behavior
+3. **Long-term Maintainability**: Flag code that may become problematic to maintain over time
+
+## Review Process
+
+### Step 1: Gather Context
+- Run `git diff` to see all uncommitted changes
+- Run `git diff --cached` to see staged changes
+- Examine the CLAUDE.md file and any project-specific configuration for coding standards
+- Look at surrounding code in modified files to understand existing patterns
+
+### Step 2: Convention Analysis
+For each changed file, verify:
+- **Naming conventions**: Variables, functions, classes, files follow existing patterns
+- **Code structure**: Organization matches similar code elsewhere in the project
+- **Import/export patterns**: Consistent with the codebase style
+- **Error handling**: Follows established error handling patterns
+- **TypeScript usage**: Proper typing, type guards, and strict mode compliance
+- **Theming**: Uses CSS variables instead of hardcoded colors (use `--ec-*` variables)
+- **Formatting**: Code should be formatted according to project standards
+
+### Step 3: Simplification Opportunities
+Identify code that can be simplified:
+- **Redundant code**: Duplicate logic that could be extracted
+- **Complex conditionals**: Nested if/else that could be flattened or use early returns
+- **Verbose patterns**: Code that could use more concise language features
+- **Over-engineering**: Abstractions that add complexity without clear benefit
+- **Dead code**: Unused variables, unreachable code paths, commented-out code
+
+### Step 4: Maintainability Assessment
+Evaluate long-term health:
+- **Readability**: Will another developer understand this in 6 months?
+- **Testability**: Is the code structured for easy testing?
+- **Coupling**: Are dependencies appropriate and minimal?
+- **Single Responsibility**: Does each function/component do one thing well?
+- **Documentation**: Are complex logic sections adequately commented?
+
+## Output Format
+
+Provide your review in this structure:
+
+### Summary
+Brief overview of the changes and overall assessment.
+
+### Convention Issues
+List each convention violation with:
+- File and line reference
+- Description of the issue
+- How it should be corrected (with code example if helpful)
+
+### Simplification Suggestions
+List each simplification opportunity with:
+- File and line reference
+- Current code snippet
+- Suggested simplified version
+- Explanation of why this is better
+
+### Maintainability Concerns
+List any long-term concerns with:
+- Description of the concern
+- Potential future impact
+- Recommended approach
+
+### Positive Observations
+Note things done well to reinforce good practices.
+
+## Important Guidelines
+
+- **Never suggest changes that alter behavior** - simplification must be functionally equivalent
+- **Prioritize issues by impact** - focus on significant problems, not nitpicks
+- **Provide actionable feedback** - every issue should have a clear resolution path
+- **Respect existing patterns** - even if you'd prefer different conventions, consistency matters more
+- **Consider context** - a quick fix may warrant different standards than core architecture
+- **Be constructive** - frame feedback as improvements, not criticisms
+
+## Project-Specific Context
+
+For this EventCatalog project:
+- Use `pnpm run format` for formatting
+- Follow strict TypeScript typing
+- Use CSS variables (`--ec-*`) for theming, never hardcoded colors or `dark:` variants
+- Use ES modules with explicit imports/exports
+- Follow patterns in existing codebase structure
+
+## Self-Verification
+
+Before finalizing your review:
+1. Confirm you've checked all uncommitted changes
+2. Verify each suggestion maintains identical behavior
+3. Ensure recommendations align with existing codebase conventions
+4. Check that feedback is specific and actionable
diff --git a/.claude/agents/docs.md b/.claude/agents/docs.md
new file mode 100644
index 000000000..b5184703f
--- /dev/null
+++ b/.claude/agents/docs.md
@@ -0,0 +1,150 @@
+---
+name: docs-updater
+description: Use this agent when the user asks to write, update, or generate documentation for a feature or code change. This includes requests like 'write docs for this feature', 'update the documentation', 'document these changes', or 'add docs for what I just built'. The agent analyzes recent code changes and intelligently updates or creates EventCatalog documentation pages.\n\nExamples:\n\n<example>\nContext: User has just implemented a new visualization feature for EventCatalog.\nuser: "Write docs for this feature"\nassistant: "I'll use the docs-updater agent to analyze your recent code changes and update the EventCatalog documentation accordingly."\n<commentary>\nSince the user wants documentation written for their recent feature work, use the Task tool to launch the docs-updater agent which will compare the current code against the previous commit, identify the changes, and update or create relevant documentation pages.\n</commentary>\n</example>\n\n<example>\nContext: User has added a new component to the EventCatalog codebase.\nuser: "Can you document the changes I made?"\nassistant: "I'll launch the docs-updater agent to review your changes and create appropriate documentation."\n<commentary>\nThe user is asking for documentation of their changes. Use the Task tool to launch the docs-updater agent to analyze the diff, understand what was changed, and update the relevant documentation in the EventCatalog docs.\n</commentary>\n</example>\n\n<example>\nContext: User has refactored an existing feature and needs docs updated.\nuser: "Update the docs to reflect my refactoring"\nassistant: "I'll use the docs-updater agent to identify what changed in your refactoring and update the documentation to match."\n<commentary>\nSince the user has refactored code and needs documentation updated, use the Task tool to launch the docs-updater agent which will detect the changes and modify existing documentation pages to reflect the new implementation.\n</commentary>\n</example>
+model: sonnet
+color: cyan
+---
+
+You are an expert technical documentation specialist with deep knowledge of EventCatalog's architecture, documentation patterns, and writing style. Your role is to analyze code changes and create or update documentation that seamlessly integrates with the existing EventCatalog docs.
+
+You are not verbose
+
+The title of the page should be a word or a 2-3 word phrase
+
+The description should be one short line, should not start with "The", should avoid repeating the title of the page, should be 5-10 words long
+
+Chunks of text should not be more than 3 sentences long
+
+The section titles are short with only the first letter of the word capitalized
+
+The section titles are in the imperative mood
+
+The section titles should not repeat the term used in the page title, for example, if the page title is "Models", avoid using a section title like "Add new models". This might be unavoidable in some cases, but try to avoid it.
+
+If the feature is a paid for feature use admonition to let the user that the feature is paid for, typically at the top of the page, but sometimes this is unavoidable and you should place it where it makes sense.
+
+when you reference localhost use port 3000 for the port number of running catalogs.
+
+never use em-dash.
+
+## Your Core Responsibilities
+
+1. **Analyze Code Changes**: Compare the current state against the previous commit to understand exactly what was modified, added, or removed.
+
+2. **Assess Documentation Impact**: Determine which documentation pages need updating and whether new pages should be created.
+
+3. **Maintain Consistent Voice**: Match the existing tone, style, and formatting conventions found throughout the EventCatalog documentation.
+
+4. **Strategic Page Placement**: Prefer updating existing pages when the content fits logically. Only create new pages when the feature is substantial enough to warrant its own documentation or doesn't fit naturally into existing pages.
+
+## Documentation Location
+
+All documentation lives in **`eventcatalog/website-2`** (a sibling directory to this repo, at `../../website-2` relative to the eventcatalog package, or `/Users/dboyne/Dev/eventcatalog/website-2`). Docs are Docusaurus markdown/MDX under `website-2/docs/`. **Never edit the legacy `website/` directory.**
+
+## Workflow
+
+### Step 1: Determine the Release Version
+
+The version that the new feature ships in is required for the `<AddedIn />` component. Resolve it in this order:
+
+1. If the user told you the release type (patch / minor / major) or an explicit version, use that.
+2. Otherwise read the current version from `packages/core/package.json` in this repo and bump it according to the release type the user specified. If the user did not specify, ask before writing docs — do not guess.
+3. Convention: bug fixes = patch, new feature/additive = minor, breaking = major.
+
+### Step 2: Understand the Changes
+- Use `git diff HEAD~1` to see what changed in the most recent commit
+- If more context is needed, examine additional commits with `git log --oneline -10` and `git diff <commit>..HEAD`
+- Read the changed files thoroughly to understand the feature's purpose and implementation
+- Note: only `@eventcatalog/core` changes need user-facing docs. SDK / CLI / playground / language-server changes generally do not belong in `website-2/docs`.
+
+### Step 3: Survey Existing Documentation
+- Explore `eventcatalog/website-2/docs` to understand the documentation structure
+- Read existing documentation pages to absorb the writing style, tone, and formatting patterns
+- Identify pages that cover related topics where new content might fit
+- Note the markdown conventions, heading structures, and code example patterns used
+
+### Step 4: Plan Documentation Updates
+- List which existing pages should be updated and why
+- Determine if a new page is necessary (only for substantial, standalone features)
+- Outline what content needs to be added or modified
+
+### Step 5: Write Documentation
+- Match the existing documentation's:
+  - Tone (professional but approachable, clear and concise)
+  - Heading hierarchy and structure
+  - Code example formatting
+  - Use of admonitions, tips, or warnings
+- Include practical code examples when relevant
+- Explain both the 'what' and the 'why' of features
+- Link to related documentation pages when appropriate
+- Apply the `<AddedIn />` component (see section below) to any new or changed feature
+
+### Step 6: Validate Changes
+- Ensure new content flows naturally with existing content
+- Verify all code examples are accurate and follow project conventions
+- Check that formatting is consistent with other pages
+- Confirm every documented addition is annotated with the correct `<AddedIn />` version
+
+## Documentation Location Guidelines
+
+- **Component documentation**: Look for existing component docs and add to them
+- **Configuration options**: Update relevant configuration documentation
+- **New features**: Consider if they extend an existing feature (update that page) or are entirely new (may warrant new page)
+- **Bug fixes**: Usually don't require documentation unless they change behavior
+- **API changes**: Update API reference documentation
+
+## The `<AddedIn />` Component
+
+Every new feature or notable change you document **must** be marked with `<AddedIn />` so readers know which release introduced it.
+
+### Import (once per file)
+
+```mdx
+import AddedIn from '@site/src/components/MDX/AddedIn';
+```
+
+If the page already imports it, do not duplicate the import.
+
+### Usage
+
+Place the tag directly under the feature heading it applies to, before any prose:
+
+```mdx
+## Customize the landing page
+
+<AddedIn version="2.37.1" />
+
+EventCatalog provides a landing page for...
+```
+
+- Use the full release version (e.g. `2.37.1`, `3.15.0`), never `latest` or a range.
+- For a brand new page, place a single `<AddedIn />` near the top, under the page title intro.
+- For an existing page that gains a new section/option, scope the `<AddedIn />` to that section only — do not bump the page-level marker.
+- A single page can contain multiple `<AddedIn />` tags at different versions; that is expected and correct.
+- Bug fixes generally do not need `<AddedIn />` (and usually don't need docs).
+
+## IMAGES
+
+- If you need to add an image just use the italic _PLACE_HOLDER_IMAGE_ for the image.
+
+## Quality Standards
+
+- Never use placeholder text - all content must be complete and accurate
+- Code examples must be syntactically correct and follow the project's TypeScript/Astro conventions
+- Explanations should be clear enough for developers unfamiliar with the codebase
+- Document edge cases and important considerations
+- Include any relevant CSS variable usage following the theming guidelines (use `--ec-*` variables, never hardcoded colors)
+
+## Output Format
+
+When updating documentation:
+1. Clearly state which files you're modifying and why
+2. Show the relevant changes in context
+3. Explain your reasoning for page placement decisions
+
+When creating new pages:
+1. Explain why a new page is warranted
+2. Describe where in the documentation structure it belongs
+3. Create the complete page content
+
+Remember: Your goal is to make the documentation feel like it was always there - seamlessly integrated, professionally written, and genuinely helpful to EventCatalog users.
diff --git a/.claude/commands/audit.md b/.claude/commands/audit.md
new file mode 100644
index 000000000..abcbb20d3
--- /dev/null
+++ b/.claude/commands/audit.md
@@ -0,0 +1,13 @@
+---
+description: Audit the uncommited changes in the current branch
+allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git diff --staged:*), Bash(git branch:*), Bash(git rev-parse:*), Bash(git switch:*), Bash(git checkout:*), Bash(git add:*), Bash(git commit:*), Bash(git restore:*)
+---
+
+You will audit the uncommited changes in the current branch and make sure they follow these patterns:
+
+Goal:
+- Code should be maintainable think about your future self and your team.
+- We prefer functional programming over object-oriented programming.
+- Code should be performant and efficient.
+
+User hint (may be empty): $ARGUMENTS
diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md
new file mode 100644
index 000000000..09faabf88
--- /dev/null
+++ b/.claude/commands/commit.md
@@ -0,0 +1,45 @@
+---
+description: Create a semantic commit (EventCatalog conventions), auto-branch if needed
+allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git diff --staged:*), Bash(git branch:*), Bash(git rev-parse:*), Bash(git switch:*), Bash(git checkout:*), Bash(git add:*), Bash(git commit:*), Bash(git restore:*)
+---
+
+You are in a git repository that uses EventCatalog-style semantic commit messages.
+
+Goal:
+- Create a single commit with message format: `<type>(<scope>): <subject>` where scope is optional.
+- Message must be lowercase.
+- Allowed types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `misc`.
+- Pick a scope only if it clearly applies (short, kebab-case). Examples: `core`, `content-docs`, `theme-classic`.
+
+User hint (may be empty): $ARGUMENTS
+
+Workflow:
+1) Run:
+   - `git status`
+   - `git diff`
+   - `git diff --staged`
+2) If there are both unrelated changes and the user hint clearly targets one thing, keep the commit focused:
+   - stage only the relevant files/lines
+   - leave unrelated changes unstaged
+3) Decide the semantic commit message:
+   - Choose the best `type` from the allowed list based on the actual diff
+   - Choose `scope` only if unambiguous
+   - Write a short present-tense, imperative `subject` in lowercase (no trailing period)
+4) Branch handling:
+   - Determine current branch with git
+   - If on `main` (or `master`) OR in detached HEAD, create and switch to a new branch
+   - Branch name format: `<type>/<scope-if-any>-<short-subject>`
+     - lowercase, kebab-case
+     - example: `feat/core-add-schema-registry-sidebar`
+     - if no scope: `fix-update-docs-links`
+5) Before committing:
+   - Show the exact commit message you plan to use
+   - Show the exact branch name (if creating one)
+   - Then proceed without asking follow-up questions
+6) Stage changes (only what belongs in this commit) using `git add ...`.
+7) Create the commit using the exact semantic message.
+
+Constraints:
+- Do not include “wip”.
+- Do not invent changes not present in the diff.
+- If there are no changes to commit, say so and stop.
diff --git a/.claude/commands/issue.md b/.claude/commands/issue.md
new file mode 100644
index 000000000..97ad827fa
--- /dev/null
+++ b/.claude/commands/issue.md
@@ -0,0 +1,39 @@
+---
+description: Create a GitHub issue in this project
+allowed-tools: Bash(gh issue create:*), Bash(gh label list:*)
+---
+
+You are creating a GitHub issue for the EventCatalog project using the GitHub CLI (`gh`).
+
+Goal:
+- Create a clear, concise GitHub issue based on the user's request.
+- Keep it simple and to the point.
+
+User request: $ARGUMENTS
+
+Workflow:
+1) Parse the user's request to understand:
+   - What the issue is about
+   - Whether it's a bug, feature request, enhancement, or documentation need
+2) Fetch available labels with `gh label list` to see what labels exist.
+3) Create the issue with `gh issue create`:
+   - Write a clear, concise title (imperative mood, lowercase)
+   - Write a focused body that captures the requirement without fluff
+   - Add appropriate labels based on issue type:
+     - Bug: `bug`
+     - Feature: `enhancement`
+     - Documentation: `documentation`
+     - Add other relevant labels if they exist and apply
+
+Issue format:
+- Title: Short, descriptive, imperative (e.g., "add support for X", "fix Y when Z")
+- Body:
+  - Brief description of what is needed
+  - Context if necessary (1-2 sentences max)
+  - No verbose templates or unnecessary sections
+
+Constraints:
+- Do not add sections that aren't needed (no "steps to reproduce" for features, etc.)
+- Keep the body under 200 words unless complexity requires more
+- Do not ask follow-up questions - use your judgment based on the request
+- After creating, output the issue URL
diff --git a/.claude/commands/pr-description.md b/.claude/commands/pr-description.md
new file mode 100644
index 000000000..69ede283d
--- /dev/null
+++ b/.claude/commands/pr-description.md
@@ -0,0 +1,107 @@
+---
+description: Generate a PR description markdown file summarizing branch changes
+allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git branch:*), Bash(git rev-parse:*), Bash(git merge-base:*), Bash(git show:*), Bash(mkdir:*), Read, Write, Glob
+---
+
+You are a helpful assistant that generates clear, user-friendly PR descriptions.
+
+Goal:
+- Analyze the changes in the current branch compared to the main branch
+- Generate a well-structured markdown file summarizing the PR
+- Save the file to `pr-descriptions/` folder with a descriptive filename
+
+User hint (may be empty): $ARGUMENTS
+
+Workflow:
+
+1) **Gather Information**
+   Run these commands to understand the changes:
+   - `git branch --show-current` - get current branch name
+   - `git merge-base HEAD main` - find common ancestor with main
+   - `git log main..HEAD --oneline` - list commits in this branch
+   - `git diff main...HEAD --stat` - file change summary
+   - `git diff main...HEAD` - full diff for analysis
+
+2) **Analyze the Changes**
+   Review all changes and identify:
+   - The primary purpose/feature of this PR
+   - Key files and components modified
+   - Any new dependencies or configurations
+   - Potential breaking changes (API changes, removed features, renamed exports, config changes)
+   - Testing considerations
+
+3) **Create the pr-descriptions Directory**
+   - Run `mkdir -p pr-descriptions` to ensure the folder exists
+
+4) **Generate the PR Description File**
+   Create a markdown file with this structure:
+
+   ```markdown
+   # PR: [Brief Title Based on Changes]
+
+   **Branch:** `[branch-name]`
+   **Date:** [YYYY-MM-DD]
+   **Commits:** [number of commits]
+
+   ## What This PR Does
+
+   [2-4 sentences describing the purpose and goals of this PR. Focus on the "why" - what problem does this solve or what feature does it add?]
+
+   ## Changes Overview
+
+   ### Files Changed
+   - [List key files/directories modified with brief notes]
+
+   ### Key Changes
+   - [Bullet points of the main changes, written for humans to understand]
+   - [Focus on what changed, not line-by-line diffs]
+
+   ## How It Works
+
+   [Explain the implementation approach. How does the new code work? What patterns or approaches were used? Include relevant technical details that reviewers should understand.]
+
+   ## Breaking Changes
+
+   [List any breaking changes, or state "None" if there are no breaking changes]
+
+   - **[Change]**: [Description of what broke and how to migrate]
+
+   ## Testing
+
+   - [ ] Unit tests added/updated
+   - [ ] Manual testing performed
+   - [ ] [Other relevant testing notes]
+
+   ## Screenshots/Examples
+
+   [If applicable, note where screenshots could be added or include code examples]
+
+   ## Checklist
+
+   - [ ] Code follows project conventions
+   - [ ] Documentation updated (if needed)
+   - [ ] No console errors or warnings introduced
+   - [ ] Reviewed for security implications
+
+   ## Additional Notes
+
+   [Any other context, related issues, follow-up work needed, or notes for reviewers]
+   ```
+
+5) **Filename Convention**
+   Save the file as: `pr-descriptions/[branch-name]-[YYYY-MM-DD].md`
+   - Replace `/` in branch names with `-`
+   - Example: `pr-descriptions/feat-core-add-mcp-server-2025-01-12.md`
+
+6) **Output**
+   After creating the file:
+   - Show the full path to the generated file
+   - Display a brief summary of what was documented
+
+Constraints:
+- Write in clear, simple language that non-technical stakeholders can understand
+- Be honest about breaking changes - don't hide them
+- If there are no changes compared to main, say so and stop
+- Focus on substance over formatting - the content matters more than looking pretty
+- Use present tense ("Adds feature" not "Added feature")
+- Keep bullet points concise but informative
diff --git a/.claude/commands/update-docs.md b/.claude/commands/update-docs.md
new file mode 100644
index 000000000..0c36ea859
--- /dev/null
+++ b/.claude/commands/update-docs.md
@@ -0,0 +1,57 @@
+---
+description: Update EventCatalog docs in website-2 based on uncommitted changes (or the previous commit) using the docs-updater agent
+allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git diff --staged:*), Bash(git log:*), Bash(git show:*), Bash(git rev-parse:*), Bash(git branch:*), Read, Agent
+---
+
+You are coordinating a documentation update for EventCatalog. The actual writing is delegated to the `docs-updater` agent (defined in `.claude/agents/docs.md`). Your job is to gather change context, then dispatch that agent with a complete brief.
+
+User hint (may be empty, may contain release type like "minor" / "patch" / "major" or an explicit version): $ARGUMENTS
+
+## Workflow
+
+### 1) Decide which changes to document
+
+Run `git status` and `git diff --stat` first.
+
+- If there are **uncommitted changes** (staged or unstaged) → document those.
+- If the working tree is clean → document the **previous commit** (`HEAD`). Use `git show HEAD` and `git log -1`.
+- If both apply (uncommitted + the user clearly meant the last commit), ask the user which to use before proceeding.
+
+Capture the actual diff with one of:
+- `git diff` and `git diff --staged` (uncommitted)
+- `git show HEAD` (previous commit)
+
+Only `@eventcatalog/core` (under `packages/core/`) changes need user-facing docs. If the diff is purely SDK / CLI / playground / language-server / tests / formatting, tell the user there's nothing to document and stop.
+
+### 2) Resolve the release version
+
+The `docs-updater` agent will tag new content with `<AddedIn version="..." />`, so it needs an exact version.
+
+- Read the current version from `packages/core/package.json`.
+- If the user passed a release type in `$ARGUMENTS` (patch / minor / major) or an explicit version, compute / use that.
+- If no release type was given, **ask the user** which bump to use before dispatching the agent. Do not guess.
+
+### 3) Dispatch the docs-updater agent
+
+Launch a single `Agent` call with `subagent_type: "docs-updater"`. The agent has no memory of this conversation — your prompt must be self-contained. Include:
+
+- The resolved target version (e.g. `3.33.0`) and the release type.
+- A summary of what changed (feature description, not a raw diff dump) — point at file paths and line numbers so the agent can read them itself.
+- Whether you're documenting uncommitted changes or `HEAD`, and how to reproduce the diff (the exact `git` command).
+- A reminder that docs live in `eventcatalog/website-2/docs` (never `/website`) and that every new/changed feature must carry an `<AddedIn />` marker with the resolved version.
+- Any user hint from `$ARGUMENTS` that's relevant (e.g. "this is a paid feature", "ship under the Scale plan section").
+
+Keep the brief tight — the agent will do its own exploration of `website-2`.
+
+### 4) Report back
+
+After the agent returns, summarise to the user in 2–3 lines:
+- Which doc files were created or updated.
+- The version stamped via `<AddedIn />`.
+- Anything the agent flagged as unresolved (missing screenshots, ambiguous placement, etc.).
+
+## Constraints
+
+- Never edit docs yourself in this command — always delegate to the agent so its conventions (tone, headings, `<AddedIn />` rules) are applied.
+- Never invent a version. If unsure, ask.
+- If the diff has no user-facing impact (refactor, internal tests, formatting), say so and skip the agent dispatch.
diff --git a/.claude/skills/copy-editing b/.claude/skills/copy-editing
new file mode 120000
index 000000000..b204bdb97
--- /dev/null
+++ b/.claude/skills/copy-editing
@@ -0,0 +1 @@
+../../.agents/skills/copy-editing
\ No newline at end of file
diff --git a/.claude/skills/copywriting b/.claude/skills/copywriting
new file mode 120000
index 000000000..214f2185c
--- /dev/null
+++ b/.claude/skills/copywriting
@@ -0,0 +1 @@
+../../.agents/skills/copywriting
\ No newline at end of file
diff --git a/.claude/skills/frontend-design/SKILL.md b/.claude/skills/frontend-design/SKILL.md
new file mode 100644
index 000000000..600b6db41
--- /dev/null
+++ b/.claude/skills/frontend-design/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
\ No newline at end of file
diff --git a/.claude/skills/grill-me/SKILL.md b/.claude/skills/grill-me/SKILL.md
new file mode 100644
index 000000000..f19dd749b
--- /dev/null
+++ b/.claude/skills/grill-me/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
\ No newline at end of file
diff --git a/.claude/skills/skill-creator/SKILL.md b/.claude/skills/skill-creator/SKILL.md
new file mode 100644
index 000000000..b3b699497
--- /dev/null
+++ b/.claude/skills/skill-creator/SKILL.md
@@ -0,0 +1,357 @@
+---
+name: skill-creator
+description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+license: Complete terms in LICENSE.txt
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend Claude's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
+
+**Default assumption: Claude is already very smart.** Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Set Appropriate Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability:
+
+**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
+
+**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
+
+**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
+
+Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   ├── description: (required)
+│   │   └── compatibility: (optional, rarely needed)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation intended to be loaded into context as needed
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+Every SKILL.md consists of:
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields (required), plus optional fields like `license`, `metadata`, and `compatibility`. Only `name` and `description` are read by Claude to determine when the skill triggers, so be clear and comprehensive about what the skill is and when it should be used. The `compatibility` field is for noting environment requirements (target product, system packages, etc.) but most skills don't need it.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments
+
+##### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
+
+- **When to include**: For documentation that Claude should reference while working
+- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
+- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
+- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output Claude produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
+- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
+- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context
+
+#### What to Not Include in a Skill
+
+A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
+
+- README.md
+- INSTALLATION_GUIDE.md
+- QUICK_REFERENCE.md
+- CHANGELOG.md
+- etc.
+
+The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
+
+### Progressive Disclosure Design Principle
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by Claude (Unlimited because scripts can be executed without reading into context window)
+
+#### Progressive Disclosure Patterns
+
+Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
+
+**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+
+## Quick start
+
+Extract text with pdfplumber:
+[code example]
+
+## Advanced features
+
+- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
+- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
+- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
+```
+
+Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
+
+**Pattern 2: Domain-specific organization**
+
+For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+    ├── finance.md (revenue, billing metrics)
+    ├── sales.md (opportunities, pipeline)
+    ├── product.md (API usage, features)
+    └── marketing.md (campaigns, attribution)
+```
+
+When a user asks about sales metrics, Claude only reads sales.md.
+
+Similarly, for skills supporting multiple frameworks or variants, organize by variant:
+
+```
+cloud-deploy/
+├── SKILL.md (workflow + provider selection)
+└── references/
+    ├── aws.md (AWS deployment patterns)
+    ├── gcp.md (GCP deployment patterns)
+    └── azure.md (Azure deployment patterns)
+```
+
+When the user chooses AWS, Claude only reads aws.md.
+
+**Pattern 3: Conditional details**
+
+Show basic content, link to advanced content:
+
+```markdown
+# DOCX Processing
+
+## Creating documents
+
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+
+## Editing documents
+
+For simple edits, modify the XML directly.
+
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+**For OOXML details**: See [OOXML.md](OOXML.md)
+```
+
+Claude reads REDLINING.md or OOXML.md only when the user needs those features.
+
+**Important guidelines:**
+
+- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
+- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Claude can see the full scope when previewing.
+
+## Skill Creation Process
+
+Skill creation involves these steps:
+
+1. Understand the skill with concrete examples
+2. Plan reusable skill contents (scripts, references, assets)
+3. Initialize the skill (run init_skill.py)
+4. Edit the skill (implement resources and write SKILL.md)
+5. Package the skill (run package_skill.py)
+6. Iterate based on real usage
+
+Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
+
+To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+
+For example, when building an image-editor skill, relevant questions include:
+
+- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
+- "Can you give some examples of how this skill would be used?"
+- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
+- "What would a user say that should trigger this skill?"
+
+To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+
+Conclude this step when there is a clear sense of the functionality the skill should support.
+
+### Step 2: Planning the Reusable Skill Contents
+
+To turn concrete examples into an effective skill, analyze each example by:
+
+1. Considering how to execute on the example from scratch
+2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
+
+Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
+
+1. Rotating a PDF requires re-writing the same code each time
+2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
+
+Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
+
+1. Writing a frontend webapp requires the same boilerplate HTML/React each time
+2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
+
+Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
+
+1. Querying BigQuery requires re-discovering the table schemas and relationships each time
+2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
+
+To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
+
+### Step 3: Initializing the Skill
+
+At this point, it is time to actually create the skill.
+
+Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
+
+When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
+
+Usage:
+
+```bash
+scripts/init_skill.py <skill-name> --path <output-directory>
+```
+
+The script:
+
+- Creates the skill directory at the specified path
+- Generates a SKILL.md template with proper frontmatter and TODO placeholders
+- Creates example resource directories: `scripts/`, `references/`, and `assets/`
+- Adds example files in each directory that can be customized or deleted
+
+After initialization, customize or remove the generated SKILL.md and example files as needed.
+
+### Step 4: Edit the Skill
+
+When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Include information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
+
+#### Learn Proven Design Patterns
+
+Consult these helpful guides based on your skill's needs:
+
+- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic
+- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns
+
+These files contain established best practices for effective skill design.
+
+#### Start with Reusable Skill Contents
+
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+
+Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
+
+Any example files and directories not needed for the skill should be deleted. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.
+
+#### Update SKILL.md
+
+**Writing Guidelines:** Always use imperative/infinitive form.
+
+##### Frontmatter
+
+Write the YAML frontmatter with `name` and `description`:
+
+- `name`: The skill name
+- `description`: This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill.
+  - Include both what the Skill does and specific triggers/contexts for when to use it.
+  - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Claude.
+  - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+
+Do not include any other fields in YAML frontmatter.
+
+##### Body
+
+Write instructions for using the skill and its bundled resources.
+
+### Step 5: Packaging a Skill
+
+Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder>
+```
+
+Optional output directory specification:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder> ./dist
+```
+
+The packaging script will:
+
+1. **Validate** the skill automatically, checking:
+
+   - YAML frontmatter format and required fields
+   - Skill naming conventions and directory structure
+   - Description completeness and quality
+   - File organization and resource references
+
+2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
+
+If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
+
+### Step 6: Iterate
+
+After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+
+**Iteration workflow:**
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again
\ No newline at end of file
diff --git a/.claude/skills/skill-creator/references/output-patterns.md b/.claude/skills/skill-creator/references/output-patterns.md
new file mode 100644
index 000000000..073ddda5f
--- /dev/null
+++ b/.claude/skills/skill-creator/references/output-patterns.md
@@ -0,0 +1,82 @@
+# Output Patterns
+
+Use these patterns when skills need to produce consistent, high-quality output.
+
+## Template Pattern
+
+Provide templates for output format. Match the level of strictness to your needs.
+
+**For strict requirements (like API responses or data formats):**
+
+```markdown
+## Report structure
+
+ALWAYS use this exact template structure:
+
+# [Analysis Title]
+
+## Executive summary
+[One-paragraph overview of key findings]
+
+## Key findings
+- Finding 1 with supporting data
+- Finding 2 with supporting data
+- Finding 3 with supporting data
+
+## Recommendations
+1. Specific actionable recommendation
+2. Specific actionable recommendation
+```
+
+**For flexible guidance (when adaptation is useful):**
+
+```markdown
+## Report structure
+
+Here is a sensible default format, but use your best judgment:
+
+# [Analysis Title]
+
+## Executive summary
+[Overview]
+
+## Key findings
+[Adapt sections based on what you discover]
+
+## Recommendations
+[Tailor to the specific context]
+
+Adjust sections as needed for the specific analysis type.
+```
+
+## Examples Pattern
+
+For skills where output quality depends on seeing examples, provide input/output pairs:
+
+```markdown
+## Commit message format
+
+Generate commit messages following these examples:
+
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output:
+```
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+```
+
+**Example 2:**
+Input: Fixed bug where dates displayed incorrectly in reports
+Output:
+```
+fix(reports): correct date formatting in timezone conversion
+
+Use UTC timestamps consistently across report generation
+```
+
+Follow this style: type(scope): brief description, then detailed explanation.
+```
+
+Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.
diff --git a/.claude/skills/skill-creator/references/workflows.md b/.claude/skills/skill-creator/references/workflows.md
new file mode 100644
index 000000000..a350c3cc8
--- /dev/null
+++ b/.claude/skills/skill-creator/references/workflows.md
@@ -0,0 +1,28 @@
+# Workflow Patterns
+
+## Sequential Workflows
+
+For complex tasks, break operations into clear, sequential steps. It is often helpful to give Claude an overview of the process towards the beginning of SKILL.md:
+
+```markdown
+Filling a PDF form involves these steps:
+
+1. Analyze the form (run analyze_form.py)
+2. Create field mapping (edit fields.json)
+3. Validate mapping (run validate_fields.py)
+4. Fill the form (run fill_form.py)
+5. Verify output (run verify_output.py)
+```
+
+## Conditional Workflows
+
+For tasks with branching logic, guide Claude through decision points:
+
+```markdown
+1. Determine the modification type:
+   **Creating new content?** → Follow "Creation workflow" below
+   **Editing existing content?** → Follow "Editing workflow" below
+
+2. Creation workflow: [steps]
+3. Editing workflow: [steps]
+```
\ No newline at end of file
diff --git a/.claude/skills/skill-creator/scripts/init_skill.py b/.claude/skills/skill-creator/scripts/init_skill.py
new file mode 100644
index 000000000..c544fc725
--- /dev/null
+++ b/.claude/skills/skill-creator/scripts/init_skill.py
@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+    init_skill.py <skill-name> --path <path>
+
+Examples:
+    init_skill.py my-new-skill --path skills/public
+    init_skill.py my-api-helper --path skills/private
+    init_skill.py custom-skill --path /custom/location
+"""
+
+import sys
+from pathlib import Path
+
+
+SKILL_TEMPLATE = """---
+name: {skill_name}
+description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
+---
+
+# {skill_title}
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## Structuring This Skill
+
+[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
+
+**1. Workflow-Based** (best for sequential processes)
+- Works well when there are clear step-by-step procedures
+- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
+- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...
+
+**2. Task-Based** (best for tool collections)
+- Works well when the skill offers different operations/capabilities
+- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
+- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...
+
+**3. Reference/Guidelines** (best for standards or specifications)
+- Works well for brand guidelines, coding standards, or requirements
+- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
+- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...
+
+**4. Capabilities-Based** (best for integrated systems)
+- Works well when the skill provides multiple interrelated features
+- Example: Product Management with "Core Capabilities" → numbered capability list
+- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...
+
+Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
+
+Delete this entire "Structuring This Skill" section when done - it's just guidance.]
+
+## [TODO: Replace with the first main section based on chosen structure]
+
+[TODO: Add content here. See examples in existing skills:
+- Code samples for technical skills
+- Decision trees for complex workflows
+- Concrete examples with realistic user requests
+- References to scripts/templates/references as needed]
+
+## Resources
+
+This skill includes example resource directories that demonstrate how to organize different types of bundled resources:
+
+### scripts/
+Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
+
+**Examples from other skills:**
+- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
+- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
+
+**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
+
+**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.
+
+### references/
+Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.
+
+**Examples from other skills:**
+- Product management: `communication.md`, `context_building.md` - detailed workflow guides
+- BigQuery: API reference documentation and query examples
+- Finance: Schema documentation, company policies
+
+**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.
+
+### assets/
+Files not intended to be loaded into context, but rather used within the output Claude produces.
+
+**Examples from other skills:**
+- Brand styling: PowerPoint template files (.pptx), logo files
+- Frontend builder: HTML/React boilerplate project directories
+- Typography: Font files (.ttf, .woff2)
+
+**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
+
+---
+
+**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
+"""
+
+EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
+"""
+Example helper script for {skill_name}
+
+This is a placeholder script that can be executed directly.
+Replace with actual implementation or delete if not needed.
+
+Example real scripts from other skills:
+- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
+- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
+"""
+
+def main():
+    print("This is an example script for {skill_name}")
+    # TODO: Add actual script logic here
+    # This could be data processing, file conversion, API calls, etc.
+
+if __name__ == "__main__":
+    main()
+'''
+
+EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+Example real reference docs from other skills:
+- product-management/references/communication.md - Comprehensive guide for status updates
+- product-management/references/context_building.md - Deep-dive on gathering context
+- bigquery/references/ - API references and query examples
+
+## When Reference Docs Are Useful
+
+Reference docs are ideal for:
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content that's only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+- Rate limits
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+- Best practices
+"""
+
+EXAMPLE_ASSET = """# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
+
+Asset files are NOT intended to be loaded into context, but rather used within
+the output Claude produces.
+
+Example asset files from other skills:
+- Brand guidelines: logo.png, slides_template.pptx
+- Frontend builder: hello-world/ directory with HTML/React boilerplate
+- Typography: custom-font.ttf, font-family.woff2
+- Data: sample_data.csv, test_dataset.json
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg, .gif
+- Fonts: .ttf, .otf, .woff, .woff2
+- Boilerplate code: Project directories, starter files
+- Icons: .ico, .svg
+- Data files: .csv, .json, .xml, .yaml
+
+Note: This is a text placeholder. Actual assets can be any file type.
+"""
+
+
+def title_case_skill_name(skill_name):
+    """Convert hyphenated skill name to Title Case for display."""
+    return ' '.join(word.capitalize() for word in skill_name.split('-'))
+
+
+def init_skill(skill_name, path):
+    """
+    Initialize a new skill directory with template SKILL.md.
+
+    Args:
+        skill_name: Name of the skill
+        path: Path where the skill directory should be created
+
+    Returns:
+        Path to created skill directory, or None if error
+    """
+    # Determine skill directory path
+    skill_dir = Path(path).resolve() / skill_name
+
+    # Check if directory already exists
+    if skill_dir.exists():
+        print(f"❌ Error: Skill directory already exists: {skill_dir}")
+        return None
+
+    # Create skill directory
+    try:
+        skill_dir.mkdir(parents=True, exist_ok=False)
+        print(f"✅ Created skill directory: {skill_dir}")
+    except Exception as e:
+        print(f"❌ Error creating directory: {e}")
+        return None
+
+    # Create SKILL.md from template
+    skill_title = title_case_skill_name(skill_name)
+    skill_content = SKILL_TEMPLATE.format(
+        skill_name=skill_name,
+        skill_title=skill_title
+    )
+
+    skill_md_path = skill_dir / 'SKILL.md'
+    try:
+        skill_md_path.write_text(skill_content)
+        print("✅ Created SKILL.md")
+    except Exception as e:
+        print(f"❌ Error creating SKILL.md: {e}")
+        return None
+
+    # Create resource directories with example files
+    try:
+        # Create scripts/ directory with example script
+        scripts_dir = skill_dir / 'scripts'
+        scripts_dir.mkdir(exist_ok=True)
+        example_script = scripts_dir / 'example.py'
+        example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
+        example_script.chmod(0o755)
+        print("✅ Created scripts/example.py")
+
+        # Create references/ directory with example reference doc
+        references_dir = skill_dir / 'references'
+        references_dir.mkdir(exist_ok=True)
+        example_reference = references_dir / 'api_reference.md'
+        example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
+        print("✅ Created references/api_reference.md")
+
+        # Create assets/ directory with example asset placeholder
+        assets_dir = skill_dir / 'assets'
+        assets_dir.mkdir(exist_ok=True)
+        example_asset = assets_dir / 'example_asset.txt'
+        example_asset.write_text(EXAMPLE_ASSET)
+        print("✅ Created assets/example_asset.txt")
+    except Exception as e:
+        print(f"❌ Error creating resource directories: {e}")
+        return None
+
+    # Print next steps
+    print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
+    print("\nNext steps:")
+    print("1. Edit SKILL.md to complete the TODO items and update the description")
+    print("2. Customize or delete the example files in scripts/, references/, and assets/")
+    print("3. Run the validator when ready to check the skill structure")
+
+    return skill_dir
+
+
+def main():
+    if len(sys.argv) < 4 or sys.argv[2] != '--path':
+        print("Usage: init_skill.py <skill-name> --path <path>")
+        print("\nSkill name requirements:")
+        print("  - Kebab-case identifier (e.g., 'my-data-analyzer')")
+        print("  - Lowercase letters, digits, and hyphens only")
+        print("  - Max 64 characters")
+        print("  - Must match directory name exactly")
+        print("\nExamples:")
+        print("  init_skill.py my-new-skill --path skills/public")
+        print("  init_skill.py my-api-helper --path skills/private")
+        print("  init_skill.py custom-skill --path /custom/location")
+        sys.exit(1)
+
+    skill_name = sys.argv[1]
+    path = sys.argv[3]
+
+    print(f"🚀 Initializing skill: {skill_name}")
+    print(f"   Location: {path}")
+    print()
+
+    result = init_skill(skill_name, path)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.claude/skills/skill-creator/scripts/package_skill.py b/.claude/skills/skill-creator/scripts/package_skill.py
new file mode 100644
index 000000000..5cd36cb16
--- /dev/null
+++ b/.claude/skills/skill-creator/scripts/package_skill.py
@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable .skill file of a skill folder
+
+Usage:
+    python utils/package_skill.py <path/to/skill-folder> [output-directory]
+
+Example:
+    python utils/package_skill.py skills/public/my-skill
+    python utils/package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+from quick_validate import validate_skill
+
+
+def package_skill(skill_path, output_dir=None):
+    """
+    Package a skill folder into a .skill file.
+
+    Args:
+        skill_path: Path to the skill folder
+        output_dir: Optional output directory for the .skill file (defaults to current directory)
+
+    Returns:
+        Path to the created .skill file, or None if error
+    """
+    skill_path = Path(skill_path).resolve()
+
+    # Validate skill folder exists
+    if not skill_path.exists():
+        print(f"❌ Error: Skill folder not found: {skill_path}")
+        return None
+
+    if not skill_path.is_dir():
+        print(f"❌ Error: Path is not a directory: {skill_path}")
+        return None
+
+    # Validate SKILL.md exists
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        print(f"❌ Error: SKILL.md not found in {skill_path}")
+        return None
+
+    # Run validation before packaging
+    print("🔍 Validating skill...")
+    valid, message = validate_skill(skill_path)
+    if not valid:
+        print(f"❌ Validation failed: {message}")
+        print("   Please fix the validation errors before packaging.")
+        return None
+    print(f"✅ {message}\n")
+
+    # Determine output location
+    skill_name = skill_path.name
+    if output_dir:
+        output_path = Path(output_dir).resolve()
+        output_path.mkdir(parents=True, exist_ok=True)
+    else:
+        output_path = Path.cwd()
+
+    skill_filename = output_path / f"{skill_name}.skill"
+
+    # Create the .skill file (zip format)
+    try:
+        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            # Walk through the skill directory
+            for file_path in skill_path.rglob('*'):
+                if file_path.is_file():
+                    # Calculate the relative path within the zip
+                    arcname = file_path.relative_to(skill_path.parent)
+                    zipf.write(file_path, arcname)
+                    print(f"  Added: {arcname}")
+
+        print(f"\n✅ Successfully packaged skill to: {skill_filename}")
+        return skill_filename
+
+    except Exception as e:
+        print(f"❌ Error creating .skill file: {e}")
+        return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
+        print("\nExample:")
+        print("  python utils/package_skill.py skills/public/my-skill")
+        print("  python utils/package_skill.py skills/public/my-skill ./dist")
+        sys.exit(1)
+
+    skill_path = sys.argv[1]
+    output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    print(f"📦 Packaging skill: {skill_path}")
+    if output_dir:
+        print(f"   Output directory: {output_dir}")
+    print()
+
+    result = package_skill(skill_path, output_dir)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.claude/skills/skill-creator/scripts/quick_validate.py b/.claude/skills/skill-creator/scripts/quick_validate.py
new file mode 100644
index 000000000..ed8e1dddc
--- /dev/null
+++ b/.claude/skills/skill-creator/scripts/quick_validate.py
@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import sys
+import os
+import re
+import yaml
+from pathlib import Path
+
+def validate_skill(skill_path):
+    """Basic validation of a skill"""
+    skill_path = Path(skill_path)
+
+    # Check SKILL.md exists
+    skill_md = skill_path / 'SKILL.md'
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+
+    # Read and validate frontmatter
+    content = skill_md.read_text()
+    if not content.startswith('---'):
+        return False, "No YAML frontmatter found"
+
+    # Extract frontmatter
+    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+    if not match:
+        return False, "Invalid frontmatter format"
+
+    frontmatter_text = match.group(1)
+
+    # Parse YAML frontmatter
+    try:
+        frontmatter = yaml.safe_load(frontmatter_text)
+        if not isinstance(frontmatter, dict):
+            return False, "Frontmatter must be a YAML dictionary"
+    except yaml.YAMLError as e:
+        return False, f"Invalid YAML in frontmatter: {e}"
+
+    # Define allowed properties
+    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}
+
+    # Check for unexpected properties (excluding nested keys under metadata)
+    unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
+    if unexpected_keys:
+        return False, (
+            f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
+            f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
+        )
+
+    # Check required fields
+    if 'name' not in frontmatter:
+        return False, "Missing 'name' in frontmatter"
+    if 'description' not in frontmatter:
+        return False, "Missing 'description' in frontmatter"
+
+    # Extract name for validation
+    name = frontmatter.get('name', '')
+    if not isinstance(name, str):
+        return False, f"Name must be a string, got {type(name).__name__}"
+    name = name.strip()
+    if name:
+        # Check naming convention (kebab-case: lowercase with hyphens)
+        if not re.match(r'^[a-z0-9-]+$', name):
+            return False, f"Name '{name}' should be kebab-case (lowercase letters, digits, and hyphens only)"
+        if name.startswith('-') or name.endswith('-') or '--' in name:
+            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
+        # Check name length (max 64 characters per spec)
+        if len(name) > 64:
+            return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."
+
+    # Extract and validate description
+    description = frontmatter.get('description', '')
+    if not isinstance(description, str):
+        return False, f"Description must be a string, got {type(description).__name__}"
+    description = description.strip()
+    if description:
+        # Check for angle brackets
+        if '<' in description or '>' in description:
+            return False, "Description cannot contain angle brackets (< or >)"
+        # Check description length (max 1024 characters per spec)
+        if len(description) > 1024:
+            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
+
+    # Validate compatibility field if present (optional)
+    compatibility = frontmatter.get('compatibility', '')
+    if compatibility:
+        if not isinstance(compatibility, str):
+            return False, f"Compatibility must be a string, got {type(compatibility).__name__}"
+        if len(compatibility) > 500:
+            return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 characters."
+
+    return True, "Skill is valid!"
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py <skill_directory>")
+        sys.exit(1)
+    
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    sys.exit(0 if valid else 1)
\ No newline at end of file
diff --git a/.claude/skills/spec-change/SKILL.md b/.claude/skills/spec-change/SKILL.md
new file mode 100644
index 000000000..8451a70f4
--- /dev/null
+++ b/.claude/skills/spec-change/SKILL.md
@@ -0,0 +1,87 @@
+---
+name: spec-change
+description: Update the EventCatalog DSL specification across all locations — Langium grammar, specification markdown docs, playground examples, and tests. Use when making any change to DSL syntax, adding new DSL features, modifying grammar rules, or updating DSL documentation. Triggers on requests like "add X to the DSL", "update the grammar", "change DSL syntax for Y", or "spec change".
+---
+
+# DSL Specification Change
+
+Apply a DSL specification change across all required locations. See [references/spec-files.md](references/spec-files.md) for all file paths.
+
+## Workflow
+
+### 1. Understand the change
+- Parse the user's request to identify the DSL feature being added/modified
+- Identify affected grammar rules, spec files, and examples
+
+### 2. Update the Langium grammar
+- Read `packages/language-server/src/ec.langium`
+- Locate and update the relevant grammar rules
+- Follow Langium conventions
+
+### 3. Add/update tests
+- Add tests in `packages/language-server/src/test/` (or `__tests__/`)
+- Cover: valid syntax, invalid syntax, edge cases, backwards compatibility
+- Use vitest. Test pattern:
+
+```typescript
+describe('Feature Name', () => {
+  it('should parse valid syntax', () => {
+    const dsl = `...valid DSL...`;
+    const result = parseDsl(dsl);
+    expect(result.parseErrors).toHaveLength(0);
+  });
+
+  it('should reject invalid syntax', () => {
+    const dsl = `...invalid DSL...`;
+    const result = parseDsl(dsl);
+    expect(result.parseErrors.length).toBeGreaterThan(0);
+  });
+});
+```
+
+- Run: `pnpm --filter @eventcatalog/language-server run test --run`
+
+### 4. Update specification markdown
+- See [references/spec-files.md](references/spec-files.md) for the full file list
+- Update examples, EBNF sections, syntax tables, and reference sections in all affected files
+
+### 5. Update playground examples and completions
+- Read `packages/playground/src/examples.ts`
+- Update ALL relevant examples to demonstrate the new syntax consistently
+- Add new example if the feature warrants one
+- Read `packages/playground/src/monaco/ec-completion.ts`
+- Update annotation suggestions and keyword completions to match the grammar changes
+
+### 6. Update SDK DSL functions and tests
+- Check `packages/sdk/src/dsl/` for functions that generate or parse DSL syntax
+- Check `packages/sdk/src/test/dsl.test.ts` for DSL-related tests
+- Ensure any DSL output or parsing reflects the grammar changes made above
+
+### 7. Verify the Langium grammar matches the spec
+- After any spec change, read `packages/language-server/src/ec.langium` and confirm the grammar is consistent with what the spec now describes
+- If they diverge, flag it to the user — the grammar may need updating too
+- Run: `pnpm --filter @eventcatalog/language-server run test --run`
+
+### 8. Format and verify
+- Run `pnpm run format`
+- Run tests again to confirm everything passes
+
+## Rules
+- **Grammar first** — always update grammar before markdown/examples
+- **Test coverage** — every grammar change MUST have tests
+- **Be thorough** — update ALL affected files, not just some
+- **Consistency** — ensure syntax is consistent across ALL playground examples
+- **EBNF sync** — keep EBNF notation in spec markdown in sync with Langium grammar
+- **Note breaking changes** — flag if changes break existing syntax
+
+## Output Format
+1. State what's changing and why
+2. Show grammar changes
+3. Show test additions/updates and run results
+4. List all spec files updated
+5. Show playground example updates
+6. Confirm formatting completed
+
+**IMPORTANT:** If you discover issues or inconsistencies in the specification that are outside the scope of the current change, do NOT fix them without first verifying with the user. Only make changes directly related to the requested spec change.
+
+Ask clarifying questions if you need to know more details.
diff --git a/.claude/skills/spec-change/references/spec-files.md b/.claude/skills/spec-change/references/spec-files.md
new file mode 100644
index 000000000..e016c6cea
--- /dev/null
+++ b/.claude/skills/spec-change/references/spec-files.md
@@ -0,0 +1,49 @@
+# DSL Specification File Locations
+
+## Grammar
+- `packages/language-server/src/ec.langium` — Langium grammar definition
+
+## Tests
+- `packages/language-server/src/test/` or `packages/language-server/__tests__/` — Test directory
+- Framework: vitest
+- Run: `pnpm --filter @eventcatalog/language-server run test --run`
+
+## Specification Markdown
+| File | Content |
+|------|---------|
+| `00-overview.md` | High-level overview |
+| `01-domain.md` | Domain syntax |
+| `02-service.md` | Service syntax |
+| `03-event.md` | Event syntax |
+| `04-command.md` | Command syntax |
+| `05-query.md` | Query syntax |
+| `06-channel.md` | Channel syntax |
+| `07-entity.md` | Entity syntax |
+| `08-container.md` | Container syntax |
+| `09-data-product.md` | Data product syntax |
+| `14-relationships.md` | Relationship/pointer syntax |
+| `15-versioning.md` | Version syntax |
+| `17-examples.md` | Example updates |
+| `18-grammar.md` | Grammar reference (EBNF) |
+| `19-visualizer.md` | Visualizer syntax |
+
+Path: `packages/language-server/specification/`
+
+## SDK DSL Functions
+- `packages/sdk/src/dsl/` — DSL generation/parsing functions
+- `packages/sdk/src/test/dsl.test.ts` — DSL-related tests
+
+## Playground Examples
+- `packages/playground/src/examples.ts`
+
+## Playground Monaco Completions
+- `packages/playground/src/monaco/ec-completion.ts` — Autocomplete suggestions for annotations and keywords in the playground editor
+
+## Language Server Completions
+- `packages/language-server/src/ec-completion-provider.ts` — Autocomplete suggestions for the language server (KNOWN_ANNOTATIONS, keyword sets)
+
+## DSL Conventions
+- Version syntax: `@` prefix (e.g., `resource@1.0.0`)
+- Lists: comma-separated (e.g., `to ChannelA, ChannelB`)
+- Optional blocks: `{...}` only when needed
+- Prefer inline syntax over blocks
diff --git a/.claude/skills/vercel-react-best-practices b/.claude/skills/vercel-react-best-practices
new file mode 120000
index 000000000..e567923b3
--- /dev/null
+++ b/.claude/skills/vercel-react-best-practices
@@ -0,0 +1 @@
+../../.agents/skills/vercel-react-best-practices
\ No newline at end of file
diff --git a/.claude/skills/visualiser-performance/SKILL.md b/.claude/skills/visualiser-performance/SKILL.md
new file mode 100644
index 000000000..c78c8e321
--- /dev/null
+++ b/.claude/skills/visualiser-performance/SKILL.md
@@ -0,0 +1,142 @@
+---
+name: visualiser-performance
+description: React Flow performance rules and review checklist for the @eventcatalog/visualiser package. Automatically applies when making changes to any file under packages/visualiser/. Use this skill to audit, review, or implement visualiser code with performance in mind.
+globs:
+  - packages/visualiser/**/*.tsx
+  - packages/visualiser/**/*.ts
+---
+
+# Visualiser Performance Rules
+
+When modifying any code in `packages/visualiser/`, follow these rules to avoid React Flow performance regressions. A single unoptimized line can cause all nodes to re-render on every drag tick, dropping FPS from 60 to 2.
+
+## Rule 1: Never pass unstable references to `<ReactFlow>` props
+
+All props on `<ReactFlow>` must be referentially stable:
+
+- **Objects/arrays**: Define outside the component or wrap in `useMemo` with stable deps
+- **Functions**: Wrap in `useCallback` with stable deps
+- **NEVER** pass anonymous functions (`onClick={() => {}}`) or inline objects directly
+
+```tsx
+// BAD - anonymous function causes ALL nodes to re-render on every state change
+<ReactFlow onNodeClick={() => {}} />
+
+// GOOD
+const handleNodeClick = useCallback(() => {}, []);
+<ReactFlow onNodeClick={handleNodeClick} />
+```
+
+`nodeTypes` and `edgeTypes` must be memoized with `useMemo(() => ..., [])` or defined outside the component. These are currently correct in `NodeGraph.tsx`.
+
+## Rule 2: Never depend on `nodes`/`edges` arrays for structural data
+
+The `nodes` and `edges` arrays from `useNodesState`/`useEdgesState` get new references on every position change (drag). If you put them in a `useMemo`/`useEffect` dependency array, that code runs on every drag tick.
+
+**Pattern: Use stable structural keys**
+
+When you only care about which nodes exist (not their positions), derive a stable key using `useRef`:
+
+```tsx
+// Stable key - only changes when nodes are added/removed
+const nodeIdsKeyRef = useRef("");
+const computedKey = nodes.map((n) => n.id).join(",");
+if (computedKey !== nodeIdsKeyRef.current) {
+  nodeIdsKeyRef.current = computedKey;
+}
+const nodeIdsKey = nodeIdsKeyRef.current;
+
+// Now use nodeIdsKey instead of nodes in deps
+const searchNodes = useMemo(() => nodes, [nodeIdsKey]);
+```
+
+For edges, include source/target in the key:
+```tsx
+const edgeKey = edges.map((e) => `${e.source}-${e.target}`).join(",");
+```
+
+**Never do this:**
+```tsx
+// BAD - runs on every drag tick
+useEffect(() => { /* expensive work */ }, [nodes, edges]);
+
+// BAD - filter runs on every position change
+const selected = useMemo(() => nodes.filter(n => n.selected), [nodes]);
+```
+
+## Rule 3: Always wrap custom nodes and edges in `memo()`
+
+Every custom node and edge component MUST be wrapped in `React.memo`. This is the single most impactful optimization — it prevents node content from re-rendering during drag even if parent state changes.
+
+```tsx
+// GOOD
+export default memo(function MyNode(props: NodeProps) {
+  return <div>...</div>;
+});
+```
+
+All current node components (`ServiceNode`, `EventNode`, `CommandNode`, `QueryNode`, `ChannelNode`, `DataNode`, `ViewNode`, `ActorNode`, `NoteNode`, `ExternalSystem`, `Custom`, `Entity`, `Step`, `Domain`, `Flow`, `DataProduct`, `User`) are correctly wrapped.
+
+All edge components (`AnimatedMessageEdge`, `MultilineEdgeLabel`, `FlowEdge`) are correctly wrapped.
+
+**Do not break this pattern when adding new node or edge types.**
+
+## Rule 4: Memoize heavy sub-components inside nodes
+
+If a node renders complex sub-components (data grids, forms, SVG animations), wrap those in `memo()` too. This prevents the inner content from re-rendering even when the node itself re-renders.
+
+```tsx
+// Sub-components with static or rarely-changing props should be memoized
+const GlowHandle = memo(function GlowHandle({ side }: { side: "left" | "right" }) {
+  return <div style={{...}} />;
+});
+```
+
+Currently memoized sub-components: `GlowHandle` (in ServiceNode, EventNode, CommandNode, QueryNode), `MiniEnvelope`, `ServiceMessageFlow` (in ServiceNode).
+
+## Rule 5: Avoid `useStore` selectors that return new references
+
+If using ReactFlow's `useStore` (or any Zustand store), never return arrays/objects that get recreated on every state change:
+
+```tsx
+// BAD - new array reference on every state update
+const selected = useStore(state => state.nodes.filter(n => n.selected));
+
+// GOOD - extract primitive values, or use useShallow
+const selectedIds = useStore(
+  state => state.nodes.filter(n => n.selected).map(n => n.id)
+);
+// With useShallow for object/array returns
+import { useShallow } from 'zustand/react/shallow';
+const [a, b] = useStore(useShallow(state => [state.a, state.b]));
+```
+
+## Checklist for PR review
+
+When reviewing visualiser changes, verify:
+
+- [ ] No anonymous functions or inline objects passed to `<ReactFlow>` props
+- [ ] No `useMemo`/`useEffect`/`useCallback` with `nodes` or `edges` in deps (use structural keys instead)
+- [ ] New custom nodes/edges are wrapped in `memo()`
+- [ ] Heavy sub-components inside nodes are wrapped in `memo()`
+- [ ] No `useStore` selectors returning unstable references
+- [ ] `nodeTypes`/`edgeTypes` remain memoized with empty deps
+
+## Key files
+
+| File | What to check |
+|------|--------------|
+| `src/components/NodeGraph.tsx` | ReactFlow props, structural keys, legend computation |
+| `src/components/StepWalkthrough.tsx` | Effect dependencies use stable keys |
+| `src/components/VisualiserSearch.tsx` | Search filtering uses stable node snapshot |
+| `src/components/FocusMode/FocusModeContent.tsx` | Focus graph calculation deps |
+| `src/nodes/*/` | All node components wrapped in memo() |
+| `src/edges/*/` | All edge components wrapped in memo() |
+
+## Reference
+
+Based on: "The Ultimate Guide to Optimize React Flow Project Performance" by Lukasz Jazwa. Key benchmarks from that article (100 nodes):
+- Anonymous function on ReactFlow prop: 60 FPS -> 10 FPS (default), 2 FPS (heavy)
+- Node depending on full nodes array via useStore: 60 FPS -> 12 FPS
+- Adding React.memo to nodes: recovers to 50-60 FPS even with non-optimal parent
+- Memoizing heavy node content: recovers to 60 FPS stable
diff --git a/.dockerignore b/.dockerignore
deleted file mode 100644
index 1e0b6cd75..000000000
--- a/.dockerignore
+++ /dev/null
@@ -1,7 +0,0 @@
-node_modules/
-.changeset/
-.github/
-.vscode/
-images/
-
-**/dist/
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
new file mode 100755
index 000000000..b8106cdfb
--- /dev/null
+++ b/.githooks/pre-commit
@@ -0,0 +1,5 @@
+#!/bin/sh
+set -eu
+
+node scripts/sync-core-docs.mjs
+git add packages/core/docs
diff --git a/.github/workflows/notify-discord.yml b/.github/workflows/notify-discord.yml
new file mode 100644
index 000000000..112ed5e57
--- /dev/null
+++ b/.github/workflows/notify-discord.yml
@@ -0,0 +1,53 @@
+name: Discord Release Notification
+
+on:
+  workflow_dispatch: # Allow manual triggering for testing
+  release:
+    types:
+      - published
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    # Run on manual trigger OR when a core package release is published
+    if: >
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'release' &&
+      startsWith(github.event.release.tag_name, '@eventcatalog/core@'))
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Get latest release info (manual trigger only)
+        if: github.event_name == 'workflow_dispatch'
+        id: release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Fetch the latest @eventcatalog/core release specifically
+          RELEASE_JSON=$(gh api repos/${{ github.repository }}/releases \
+            --jq '[.[] | select(.tag_name | startswith("@eventcatalog/core@"))] | first')
+
+          # Extract fields
+          echo "tag=$(echo "$RELEASE_JSON" | jq -r '.tag_name')" >> $GITHUB_OUTPUT
+          echo "name=$(echo "$RELEASE_JSON" | jq -r '.name')" >> $GITHUB_OUTPUT
+          echo "url=$(echo "$RELEASE_JSON" | jq -r '.html_url')" >> $GITHUB_OUTPUT
+
+          # Body needs special handling for multiline
+          echo "body<<EOF" >> $GITHUB_OUTPUT
+          echo "$RELEASE_JSON" | jq -r '.body' >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Send Discord notification
+        run: node packages/core/scripts/notify-discord-release.js
+        env:
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_RELEASE_WEBHOOK }}
+          RELEASE_TAG: ${{ github.event_name == 'release' && github.event.release.tag_name || steps.release.outputs.tag }}
+          RELEASE_NAME: ${{ github.event_name == 'release' && github.event.release.name || steps.release.outputs.name }}
+          RELEASE_BODY: ${{ github.event_name == 'release' && github.event.release.body || steps.release.outputs.body }}
+          RELEASE_URL: ${{ github.event_name == 'release' && github.event.release.html_url || steps.release.outputs.url }}
diff --git a/.github/workflows/redeploy-eventcatalog-examples.yml b/.github/workflows/redeploy-eventcatalog-examples.yml
new file mode 100644
index 000000000..ba613af80
--- /dev/null
+++ b/.github/workflows/redeploy-eventcatalog-examples.yml
@@ -0,0 +1,47 @@
+name: Redeploy EventCatalog Examples on core release
+on:
+  workflow_run:
+    workflows: ["Release"]
+    types:
+      - completed
+jobs:
+  redeploy-finance:
+    runs-on: ubuntu-latest
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      startsWith(github.event.workflow_run.head_commit.message, 'Version Packages')
+    steps:
+      - name: Redeploy EventCatalog Finance Example Catalog
+        run: curl -f -X POST "$VERCEL_DEPLOY_HOOK_URL"
+        env:
+          VERCEL_DEPLOY_HOOK_URL: ${{ secrets.VERCEL_DEPLOY_HOOK_FINANCE_EXAMPLE_CATALOG_URL }}
+  redeploy-healthcare:
+    runs-on: ubuntu-latest
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      startsWith(github.event.workflow_run.head_commit.message, 'Version Packages')
+    steps:
+      - name: Redeploy EventCatalog Healthcare Example Catalog
+        run: curl -f -X POST "$VERCEL_DEPLOY_HOOK_URL"
+        env:
+          VERCEL_DEPLOY_HOOK_URL: ${{ secrets.VERCEL_DEPLOY_HOOK_HEALTHCARE_EXAMPLE_CATALOG_URL }}
+  redeploy-demo:
+    runs-on: ubuntu-latest
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      startsWith(github.event.workflow_run.head_commit.message, 'Version Packages')
+    steps:
+      - name: Redeploy EventCatalog Demo (FlowMart) Example Catalog
+        run: curl -f -X POST "$VERCEL_DEPLOY_HOOK_URL"
+        env:
+          VERCEL_DEPLOY_HOOK_URL: ${{ secrets.VERCEL_DEPLOY_HOOK_DEMO_FLOWMART_CATALOG_URL }}
+  redeploy-saas:
+    runs-on: ubuntu-latest
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      startsWith(github.event.workflow_run.head_commit.message, 'Version Packages')
+    steps:
+      - name: Redeploy EventCatalog Demo (SaaS) Example Catalog
+        run: curl -f -X POST "$VERCEL_DEPLOY_HOOK_URL"
+        env:
+          VERCEL_DEPLOY_HOOK_URL: ${{ secrets.VERCEL_DEPLOY_HOOK_SAAS_EXAMPLE_CATALOG_URL }}
\ No newline at end of file
diff --git a/.github/workflows/release-vscode.yml b/.github/workflows/release-vscode.yml
new file mode 100644
index 000000000..a627d4977
--- /dev/null
+++ b/.github/workflows/release-vscode.yml
@@ -0,0 +1,60 @@
+name: Release VS Code Extension
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version bump type'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    if: github.repository == 'event-catalog/eventcatalog'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Use Node.js 24.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          cache: 'pnpm'
+
+      - name: Install deps
+        run: pnpm i
+
+      - name: Bump version
+        working-directory: packages/vscode-extension
+        run: npm version ${{ inputs.version }} --no-git-tag-version
+
+      - name: Build all packages
+        run: pnpm run build:bin
+
+      - name: Publish to VS Code Marketplace
+        working-directory: packages/vscode-extension
+        run: npx @vscode/vsce publish --no-dependencies
+        env:
+          VSCE_PAT: ${{ secrets.VSCE_PAT }}
+
+      - name: Get version
+        id: version
+        working-directory: packages/vscode-extension
+        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+
+      - name: Commit version bump
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add packages/vscode-extension/package.json
+          git commit -m "chore: release vscode extension v${{ steps.version.outputs.version }}"
+          git push
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 5b8ff674e..2150974cd 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -26,12 +26,16 @@ jobs:
         with:
           node-version: 24.x
           cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
 
       - name: Install deps
         run: pnpm i
 
+      - name: Build all packages
+        run: pnpm run build:bin
+
       - name: Create Release Pull Request or Publish to npm
-        uses: changesets/action@master
+        uses: changesets/action@v1
         with:
           publish: pnpm run release
         env:
diff --git a/.github/workflows/verify-build.yml b/.github/workflows/verify-build.yml
index dd6531e0f..7f2847d2a 100644
--- a/.github/workflows/verify-build.yml
+++ b/.github/workflows/verify-build.yml
@@ -8,8 +8,8 @@ on:
       - main
 
 jobs:
-  build-cli:
-    name: Build cli
+  build-and-test:
+    name: Build and Test All Packages
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -22,24 +22,64 @@ jobs:
           cache: 'pnpm'
       - name: Installation
         run: pnpm i
-      - name: Test
+      - name: Turbo Cache
+        uses: actions/cache@v4
+        with:
+          path: .turbo
+          key: turbo-${{ runner.os }}-${{ github.sha }}
+          restore-keys: |
+            turbo-${{ runner.os }}-
+      - name: Test All Packages
         run: pnpm run test:ci
-      - name: Build cli
+      - name: Build All Packages
         run: pnpm run build:bin
-      - name: Package
+      - name: Package SDK
+        run: pnpm pack
+        working-directory: packages/sdk
+      - name: Package CLI
+        run: pnpm pack
+        working-directory: packages/cli
+      - name: Package Core
+        run: pnpm pack
+        working-directory: packages/core
+      - name: Package Linter
         run: pnpm pack
-      - name: Rename package artifact
-        run: mv *.tgz package.tgz # Rename to a consistent name
-      - name: Upload package artifact
+        working-directory: packages/linter
+      - name: Package Connectors
+        run: pnpm pack
+        working-directory: packages/connectors
+      - name: Package Visualiser
+        run: pnpm pack
+        working-directory: packages/visualiser
+      - name: Package Language Server
+        run: pnpm pack
+        working-directory: packages/language-server
+      - name: Rename package artifacts
+        run: |
+          mv packages/sdk/*.tgz sdk-package.tgz
+          mv packages/cli/*.tgz cli-package.tgz
+          mv packages/core/*.tgz core-package.tgz
+          mv packages/linter/*.tgz linter-package.tgz
+          mv packages/connectors/*.tgz connectors-package.tgz
+          mv packages/visualiser/*.tgz visualiser-package.tgz
+          mv packages/language-server/*.tgz language-server-package.tgz
+      - name: Upload package artifacts
         uses: actions/upload-artifact@v4
         with:
-          name: eventcatalog-core-package-artifact
-          path: package.tgz
+          name: eventcatalog-packages-artifact
+          path: |
+            sdk-package.tgz
+            cli-package.tgz
+            core-package.tgz
+            linter-package.tgz
+            connectors-package.tgz
+            visualiser-package.tgz
+            language-server-package.tgz
 
   build-eventcatalog:
     name: Build EventCatalog
     timeout-minutes: 10
-    needs: build-cli
+    needs: build-and-test
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest]
@@ -50,13 +90,24 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 24.x
-      - name: Download package artifact
+      - name: Cache npm
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('examples/default/package-lock.json') }}
+          restore-keys: npm-${{ runner.os }}-
+      - name: Download package artifacts
         uses: actions/download-artifact@v4
         with:
-          name: eventcatalog-core-package-artifact
-      - name: Install @eventcatalog-core
+          name: eventcatalog-packages-artifact
+      - name: Install @eventcatalog packages
         working-directory: examples/default/
-        run: npm install ../../package.tgz
+        run: npm install ../../sdk-package.tgz ../../core-package.tgz ../../linter-package.tgz ../../connectors-package.tgz ../../visualiser-package.tgz
       - name: Build EventCatalog
         working-directory: examples/default/
         run: npx eventcatalog build
+      - name: Check build size
+        if: matrix.os == 'ubuntu-latest'
+        run: node packages/core/scripts/check-build-size.js
+        env:
+          SIZE_THRESHOLD: 5
diff --git a/.gitignore b/.gitignore
index 326a6a93e..0ada19382 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,9 @@
 # build output
 dist/
 
+# turborepo
+.turbo/
+
 # dependencies
 node_modules/
 
@@ -22,14 +25,19 @@ pnpm-debug.log*
 
 # EventCatalog files
 **/.eventcatalog-core/
+**/.eventcatalog/
 /examples/large-catalog/*
-eventcatalog/pnpm-lock.yaml
-eventcatalog/public/pagefind
+packages/core/eventcatalog/pnpm-lock.yaml
+packages/core/eventcatalog/public/pagefind
+/packages/core/eventcatalog/src/pages/api/[...auth].ts
 
 .vscode/*
 
 git-push.sh
 
+# local-only Claude skill (Discord webhook automation)
+.claude/skills/release-discord-summary/
+
 /test-results/
 /playwright-report/
 /blob-report/
@@ -37,10 +45,39 @@ git-push.sh
 
 src/__tests__/example-catalog-dependencies/dependencies
 
-eventcatalog/public/ai
+**/__tests__/catalog/
+
+packages/core/eventcatalog/public/ai
 examples/default/public/ai
+examples/default/eventcatalog.chat.js
+examples/default/exports/
 **/[...auth].ts
 
+.astro/
+
 dev-scripts/
 
-examples/e-commerce
\ No newline at end of file
+examples/e-commerce
+
+.claude/agents/eventcatalog-blog-writer.md
+pr-descriptions/
+.claude/commands/ship.md
+.claude/skills/release-discord-summary/SKILL.md
+.claude/skills/release-discord-summary/scripts/post-to-discord.sh
+
+
+PRD.md
+progress.txt
+ralph-once.sh
+terms/
+
+notes/*
+PERFORMANCE-ANALYSIS.md
+
+
+.agents/
+ec-test/
+
+docs/superpowers/*
+.worktrees/
+.pnpm-store/
\ No newline at end of file
diff --git a/.prettierignore b/.prettierignore
deleted file mode 100644
index 3686cbaff..000000000
--- a/.prettierignore
+++ /dev/null
@@ -1,7 +0,0 @@
-dist
-node_modules
-.astro/
-dist
-eventcatalog.config.js
-examples/
-
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..7e3e8ffad
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,54 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+This repository is a `pnpm` + Turborepo monorepo. Packages live in `packages/*`:
+- `packages/core`: main EventCatalog app (Astro + React) and local scripts.
+- `packages/cli`, `packages/sdk`, `packages/linter`, `packages/language-server`, `packages/visualiser`, `packages/create-eventcatalog`.
+- `packages/playground`: local DSL playground app.
+
+Examples and integration checks live in `examples/` (notably `examples/default`). Shared release metadata is in `.changeset/`.
+
+## Build, Test, and Development Commands
+Run from repo root unless noted:
+- `pnpm i`: install workspace dependencies.
+- `pnpm build:bin`: build distributable artifacts across packages.
+- `pnpm build`: run full Turbo build graph.
+- `pnpm test`: run package tests.
+- `pnpm test:ci`: CI-style test run used by GitHub Actions.
+- `pnpm format` / `pnpm format:diff`: format or check formatting.
+- `pnpm start:catalog`: run local catalog via `@eventcatalog/core`.
+- `pnpm --filter @eventcatalog/<pkg> run <script>`: work on one package (example: `pnpm --filter @eventcatalog/sdk test`).
+
+## Coding Style & Naming Conventions
+Code is primarily TypeScript. Follow package Prettier rules:
+- 2 spaces, semicolons, single quotes, trailing commas (`es5`), print width 130.
+- Astro files in core use `prettier-plugin-astro`.
+
+Naming patterns:
+- React components: `PascalCase` (for example `NodeGraph.tsx`).
+- Utility/module files: existing local style (`kebab-case` or descriptive lowercase) within that package.
+- Keep public API names explicit and package-scoped.
+
+## Testing Guidelines
+Vitest is the default test framework across packages. Tests are placed either near source (`src/test`, `test`, `tests`) or under `__tests__`.
+- Use `*.test.ts` or `*.spec.ts` to match existing suites.
+- Add/adjust tests with every behavior change.
+- For CLI tests (especially under `packages/cli/src/test/import-export`), use descriptive, rule-style test names that read in plain English, for example: `when we import a domain that does not exist in the catalog, a domain resource is created`.
+- For CLI export tests, assert exact expected outputs and errors (prefer `toBe` with full strings) instead of partial-match assertions like `toContain`.
+- For multiline CLI export DSL assertions, use the shared `dsl` template tag with `toBe(...)` so expected blocks stay readable and indented in the test file.
+- For core/UI-impacting changes, also verify catalog build paths (`pnpm verify-build:catalog`).
+
+## Commit & Pull Request Guidelines
+Recent history favors Conventional Commit style with scopes:
+- `feat(cli): add import command`
+- `fix(core): avoid first-run dev restart`
+
+Use `<type>(<scope>): <imperative summary>` when possible. For PRs:
+- Fill in the Motivation section from `.github/PULL_REQUEST_TEMPLATE.md`.
+- Link related issues.
+- Include screenshots/GIFs for UI changes.
+- Add a changeset (`pnpm changeset`) for publishable package changes unless the change is internal-only.
+
+## Important
+
+Never start the catalog, the catalog is already running.
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
deleted file mode 100644
index 1a2da8a41..000000000
--- a/CHANGELOG.md
+++ /dev/null
@@ -1,2879 +0,0 @@
-# @eventcatalog/core
-
-## 2.65.1
-
-### Patch Changes
-
-- fa47d1e: feat(core): added ability for defult homepage and turn visualizer off
-
-## 2.65.0
-
-### Minor Changes
-
-- 0392e72: fix(core): fixed bug for missing adapter on static sites
-- 1bf9a0f: feat(core): added new channel 2.0
-- 9d8e419: fix(core): fixed a bug with avro schema viewer layout
-- 81033b8: feat(core): refactored channel configuration for eventcataog
-
-### Patch Changes
-
-- 544f480: fix(plugin): fix versions of asyncapi plugin
-- 41f3637: fix(core): fixed a bug with avro schema viewer and union options
-- 682c149: feat(core): added ability to get latest schema in the schema api
-- a3e8bfe: chore(core): updated astro versions
-- 38958d2: chore(core): updated glob version of package
-- c5ec61b: fix(core): fixed minor issues with new channel updates
-
-## 2.65.0-beta.5
-
-### Patch Changes
-
-- c5ec61b: fix(core): fixed minor issues with new channel updates
-
-## 2.65.0-beta.4
-
-### Patch Changes
-
-- 544f480: fix(plugin): fix versions of asyncapi plugin
-
-## 2.65.0-beta.3
-
-### Patch Changes
-
-- 682c149: feat(core): added ability to get latest schema in the schema api
-- 38958d2: chore(core): updated glob version of package
-
-## 2.65.0-beta.2
-
-### Minor Changes
-
-- 9d8e419: fix(core): fixed a bug with avro schema viewer layout
-
-### Patch Changes
-
-- 41f3637: fix(core): fixed a bug with avro schema viewer and union options
-- a3e8bfe: chore(core): updated astro versions
-
-## 2.65.0-beta.1
-
-### Minor Changes
-
-- 0392e72: fix(core): fixed bug for missing adapter on static sites
-
-## 2.65.0-beta.0
-
-### Minor Changes
-
-- 81033b8: feat(core): refactored channel configuration for eventcataog
-
-## 2.64.4
-
-### Patch Changes
-
-- ac4cf00: fix(core): Schemaviewer required flags for Avro schemas now working
-
-## 2.64.3
-
-### Patch Changes
-
-- c0d466e: chore(core): removed unsed dependency
-
-## 2.64.2
-
-### Patch Changes
-
-- c48484f: fix(core): fixed issue fetching specifications on ssr mode for pages
-- c009458: chore(core): updated astro versions
-
-## 2.64.1
-
-### Patch Changes
-
-- ca1478d: feat(core): avro schema viewer now shows required fields
-
-## 2.64.0
-
-### Minor Changes
-
-- 4235eb3: feat(core): added schema registry page
-- f37fbad: feat(core): added schemas.txt and also schema API
-
-### Patch Changes
-
-- 5d40372: chore(core): allowed allowed host configuration for server
-
-## 2.63.0
-
-### Minor Changes
-
-- 465d8b8: feat(core): added configuration for eventcatalog tables
-
-## 2.62.1
-
-### Patch Changes
-
-- 750c983: fix(core): https proxy added for license server
-
-## 2.62.0
-
-### Minor Changes
-
-- 7b62734: fix(core): public paths to download schemas fixed
-
-### Patch Changes
-
-- 7b62734: fix(core): fixed an issue when downloading schemas with foldername and id mismatches
-
-## 2.61.9
-
-### Patch Changes
-
-- 1b7b6b1: chore(core): eventcatalog no longer compresses static output by default
-
-## 2.61.8
-
-### Patch Changes
-
-- 77c109a: feat(core): added ability to hide orphaned messages
-
-## 2.61.7
-
-### Patch Changes
-
-- ba3d4cc: fix(core): users can now hide studio on the sidebar
-
-## 2.61.6
-
-### Patch Changes
-
-- 57a1f3f: fix(core): resource versions can be strings or numbers
-- 3c1e854: fix(core): replaced commonjs imports for tailwind
-- cfb08cf: chore(core): catalog api is enabled by default
-
-## 2.61.5
-
-### Patch Changes
-
-- 44ae131: feat(core): mermaid diagrams now support ELK layout
-
-## 2.61.4
-
-### Patch Changes
-
-- a8c060a: feat(core): users can now load all resources into studio
-
-## 2.61.3
-
-### Patch Changes
-
-- f3817eb: fix(core): fixed issue with broken sidebar
-
-## 2.61.2
-
-### Patch Changes
-
-- 788b4f4: feat(core): added support for remote spec files
-
-## 2.61.1
-
-### Patch Changes
-
-- fa838a6: chore(core): updated astro to 5.14.1
-- 02d4217: chore(core): simplify eventcatalog chat
-
-## 2.61.0
-
-### Minor Changes
-
-- e32da88: chore(core): simplify eventcatalog chat
-
-## 2.60.0
-
-### Minor Changes
-
-- df59049: feat(core): services are now nested in domains for the sidebar
-
-## 2.59.1
-
-### Patch Changes
-
-- aff5ad1: fix(core): fixed changelogs for data stores
-
-## 2.59.0
-
-### Minor Changes
-
-- 1901c50: feat(core): added database containers as a resource type
-
-## 2.58.2
-
-### Patch Changes
-
-- 4d30128: fix(core): fixed code styling issues
-
-## 2.58.1
-
-### Patch Changes
-
-- dbdd4d7: fix(core): fixed small type issue with astro
-
-## 2.58.0
-
-### Minor Changes
-
-- 3ed761b: feat(core): added support for graphql specs in EventCatalog
-
-## 2.57.2
-
-### Patch Changes
-
-- ed05f34: chore(core): fixing vite issues using eventcataog with pnpm
-- 1a2ddca: feat(core): added ability to add attachments to all resources
-
-## 2.57.1
-
-### Patch Changes
-
-- def4aaf: chore(core): updated visualizer version
-
-## 2.57.0
-
-### Minor Changes
-
-- 99c2474: feat(core): added ability to open visualizer into studio
-
-## 2.56.4
-
-### Patch Changes
-
-- 068cdf6: feat(core): added new mermaid file loader component
-
-## 2.56.3
-
-### Patch Changes
-
-- d5299f2: chore(core): updated astro version
-- e378fc7: fix(core): fix copy button for trialing slash catalogs
-
-## 2.56.2
-
-### Patch Changes
-
-- 2509425: feat(core): added ability to mofidy the service label in the sidebar
-
-## 2.56.1
-
-### Patch Changes
-
-- 551a687: chore(core): updated astro versions
-
-## 2.56.0
-
-### Minor Changes
-
-- fad3998: feat(core): added support for offline license checks
-
-### Patch Changes
-
-- 9877fcb: chore(core): updated astro versions
-
-## 2.55.6
-
-### Patch Changes
-
-- 290d4d1: fix(core): SchemaViewer now display constant values
-- b0928a8: fix(core): enums and items now shown on entity properties map
-- 821fdd0: fix(core): fixed actor details now showing in visualizer
-
-## 2.55.5
-
-### Patch Changes
-
-- 1c9a4bb: fix(core): fixed architecture page for filtered messages with services
-
-## 2.55.4
-
-### Patch Changes
-
-- ba5b02a: feat(core): added ability to switch column layout for architecture pages
-
-## 2.55.3
-
-### Patch Changes
-
-- 362933f: fix(core): reduced the pagesize of the architecture/messages page
-
-## 2.55.2
-
-### Patch Changes
-
-- bf83b89: fix(core): fixed schemaviewer for array rooted schemas
-
-## 2.55.1
-
-### Patch Changes
-
-- e77e6fc: feat(viualizer): added support for webrtc in channels
-
-## 2.55.0
-
-### Minor Changes
-
-- 5ba7868: feat(core): updated visualizer and setup for designs
-  - Visualizer now pulls information from @eventcatalog/visualizer package
-  - Project now supports .ecstudio files (For EventCatalog Studio)
-  - Project now supports Designs as a Resource type (EventCatalog Studio)
-
-### Patch Changes
-
-- 4f4a911: chore(core): architecture pages now single column
-- b3e5636: feat(core): added support for avsc files in diffs
-- b3dfb93: fix(core): added data nodes from studio into eventcatalog
-- 68cbd22: feat(core): fixed type checks in build
-
-## 2.54.8
-
-### Patch Changes
-
-- f3f8f5d: fix(core): fixed issue with pagefind when users have trailingslash configured
-
-## 2.54.7
-
-### Patch Changes
-
-- 7a2cd70: fix(core): schema viewer now renders in the correct location
-- cbc8d2b: fix(core): fixed custom docs layout issues
-
-## 2.54.6
-
-### Patch Changes
-
-- 6f2f4f9: fix(core): pagefind now includes the base config param
-
-## 2.54.5
-
-### Patch Changes
-
-- 8c87054: Fix cross-platform path resolution for OpenAPI specs and schemas
-
-  Addresses issues #1652 and #1644 by improving the path resolution logic in the `resolveProjectPath` function with full cross-platform compatibility. This fix ensures that paths starting with `../` are resolved correctly on Windows, macOS, and Linux systems.
-
-  **Key improvements:**
-  - Normalizes path separators (`/` and `\`) for cross-platform compatibility
-  - Prevents `../` paths from incorrectly resolving outside the project directory
-  - Fixes OpenAPI specifications and schemas failing to load after version 2.54.4
-  - Maintains security boundaries while ensuring functionality across all operating systems
-
-  This resolves the root cause that wasn't fully addressed in version 2.54.4, ensuring that both OpenAPI specifications and AsyncAPI specifications render correctly across all platforms.
-
-## 2.54.4
-
-### Patch Changes
-
-- 2d563c9: fix(core): resolve SchemaViewer path resolution for relative paths
-
-  Fixes SchemaViewer components failing to load schema files with paths starting with "../". The issue was caused by inconsistent path resolution logic in SchemaViewerRoot.astro.
-  - Added resolveProjectPath function to handle "../" paths correctly
-  - Updated getAbsoluteFilePathForAstroFile to use the new path resolution logic
-  - SchemaViewerRoot.astro now uses resolveProjectPath for consistent path handling
-
-## 2.54.3
-
-### Patch Changes
-
-- 3f99807: chore(core): updated astro
-- 898e53f: fix(core): entities now render in services pages
-
-## 2.54.2
-
-### Patch Changes
-
-- 6b1b554: fix(core): search no longer loads every result on load
-
-## 2.54.1
-
-### Patch Changes
-
-- 44ac76f: fix(core): fixed pagefind output directory on build
-- cba92ab: fix(core): fixed entity spelling on search modal
-
-## 2.54.0
-
-### Minor Changes
-
-- 3944204: feat(core): update search to custom pagefind solution
-
-## 2.53.1
-
-### Patch Changes
-
-- f811fb0: fix(core): fixed issue with scrolling on docs and nodegraphs
-
-## 2.53.0
-
-### Minor Changes
-
-- c4074d0: feat(core): added ability to customize detail panels on all pages
-
-## 2.52.0
-
-### Minor Changes
-
-- 6c7433e: feat(core): added ability to fetch schemas from a remote url
-
-## 2.51.1
-
-### Patch Changes
-
-- 2622135: feat:(core): added ability to restrict which entities are shown on the EntityMap component
-
-## 2.51.0
-
-### Minor Changes
-
-- 560c3a8: feat(core): updated ubiquitous language page, now renders subdomains …
-
-## 2.50.3
-
-### Patch Changes
-
-- a14c3e8: feat(core): added customization (props) to nodegraphs and flow compon…
-- 34d6bfa: fix(core): mermaid and plantuml now render in accordian
-
-## 2.50.2
-
-### Patch Changes
-
-- 498b9e4: feat(core): dropdown cta for all resource pages are now shown by default
-
-## 2.50.1
-
-### Patch Changes
-
-- 7f6da53: fix(core): fixed issue loading files in SSR mode
-
-## 2.50.0
-
-### Minor Changes
-
-- fff1249: fix(core): fixed issue loading files in SSR mode
-
-## 2.49.5
-
-### Patch Changes
-
-- 789a248: fix(core): fixed domain language explorer in SSR mode
-
-## 2.49.4
-
-### Patch Changes
-
-- f9d22d8: feat(core): added edit links into resource pages
-
-## 2.49.3
-
-### Patch Changes
-
-- 7130716: fix(core): no longer compress css
-
-## 2.49.2
-
-### Patch Changes
-
-- 8b0ae38: fix(core): fixed broken sidebar styles on list view settings
-
-## 2.49.1
-
-### Patch Changes
-
-- 9e0b525: feat(core): compressing build is now optional (again)
-
-## 2.49.0
-
-### Minor Changes
-
-- 48de32d: feat(core): added domain entity map visualizer pages
-
-## 2.48.5
-
-### Patch Changes
-
-- ab83e48: feat(core): compressing build is now optional
-
-## 2.48.4
-
-### Patch Changes
-
-- 99a34cf: feat(core): added draft support for resources
-
-## 2.48.3
-
-### Patch Changes
-
-- cf4f246: feat(core): added draft support for resources
-
-## 2.48.2
-
-### Patch Changes
-
-- f0d88aa: feat(core): added environments switcher
-
-## 2.48.1
-
-### Patch Changes
-
-- b77aa3b: fix(core): fixed list view sidebar scrolling to resources
-- 49f794e: feat(core): added support for MDX snippets
-
-## 2.48.0
-
-### Minor Changes
-
-- 49d8395: feat(core): added support for MDX snippets
-
-### Patch Changes
-
-- a35c5b2: feat(core): sidebar now has collapse buttons
-
-## 2.47.1
-
-### Patch Changes
-
-- c7f7ca1: chore(core): updated width of services in architecture page
-
-## 2.47.0
-
-### Minor Changes
-
-- 66edd2e: chore(core): refactor sidebar to reduce page weights
-
-## 2.46.0
-
-### Minor Changes
-
-- 9ad51a1: feat(core): added support for plantuml code blocks
-
-## 2.45.3
-
-### Patch Changes
-
-- d9b144e: feat(core): added ability to link to headings
-
-## 2.45.2
-
-### Patch Changes
-
-- 79ec914: feat(core): added search and expand features to schema viewer
-
-## 2.45.1
-
-### Patch Changes
-
-- 59d3275: chore(core): renamed new domain feature
-
-## 2.45.0
-
-### Minor Changes
-
-- 537281e: feat(core): added domain integration visualizer
-
-## 2.44.5
-
-### Patch Changes
-
-- 125f14d: fix(core): fixing type errors
-
-## 2.44.4
-
-### Patch Changes
-
-- 3247596: feat(core): added node walkthroughs for flows
-- 5a27960: feat(core): improved search, now searched by name and id
-
-## 2.44.3
-
-### Patch Changes
-
-- 46600ff: fix(core): fix for schema viewer
-
-## 2.44.2
-
-### Patch Changes
-
-- c42518e: fix(core): fixed path matching for middleware
-- d4fd84a: fix(core): removed redundant error log
-
-## 2.44.1
-
-### Patch Changes
-
-- 885bd94: feat(core): added search on visualizer
-
-## 2.44.0
-
-### Minor Changes
-
-- e0d3efe: chore(core): added auth middleware for rbac
-
-## 2.43.5
-
-### Patch Changes
-
-- e09594b: chore(core): updated astro versions
-
-## 2.43.4
-
-### Patch Changes
-
-- a070530: chore(core): added feature logs
-
-## 2.43.3
-
-### Patch Changes
-
-- c70e610: feat(core): added google authentication options
-
-## 2.43.2
-
-### Patch Changes
-
-- 1bc6ee4: feat(core): added entra to auth providers
-
-## 2.43.1
-
-### Patch Changes
-
-- 0dbdeae: feat(core): added auth0 to list of providers for auth
-
-## 2.43.0
-
-### Minor Changes
-
-- 1b6c725: feat(core): added authentication and SSR options
-
-## 2.42.10
-
-### Patch Changes
-
-- 3b5138c: fix(core): services and domains visualizers now read the channel type
-
-## 2.42.9
-
-### Patch Changes
-
-- 6522f76: chore(core): added host configuration support for eventcatalog
-- 650cd38: fix(core): added headers and tabs into openapi render
-
-## 2.42.8
-
-### Patch Changes
-
-- 5f58157: feat(core): added new end point for producers and consumers
-- ea92c89: feat(core): Added entities and ubquitous lang, and channels to llms txt
-
-## 2.42.7
-
-### Patch Changes
-
-- de85086: feat(core): Added entities and ubquitous lang, and channels to llms txt
-
-## 2.42.6
-
-### Patch Changes
-
-- 4c635fa: feat(core): added ability to turn off changelogs
-
-## 2.42.5
-
-### Patch Changes
-
-- cb0c00a: fix(core): fixed issue with long list of messages on architecture page
-
-## 2.42.4
-
-### Patch Changes
-
-- b8e0725: fix(core): fixed broken zindex for search on asyncapi page
-- 2a5574b: fix(core): fixed a bug where schema viewer did not support ref definitions
-
-## 2.42.3
-
-### Patch Changes
-
-- c04abcd: feat(core): added ability to remove minor branding
-- 01d3db9: fix(core): deprecated dates can now be strings
-
-## 2.42.2
-
-### Patch Changes
-
-- 2e4b4f1: fix(core): fix for broken visualizer
-
-## 2.42.1
-
-### Patch Changes
-
-- ad4ece8: feat(core): added producers and consumers to channel docs
-
-## 2.42.0
-
-### Minor Changes
-
-- 1b95c70: Allow channels to be displayed as a single node (Fix #989)
-
-## 2.41.1
-
-### Patch Changes
-
-- 3d8df99: fix(core): fixed base url for llms txt endpoint
-
-## 2.41.0
-
-### Minor Changes
-
-- ab7203c: feat(core): added schemas to AI features
-
-## 2.40.1
-
-### Patch Changes
-
-- 3174cbd: fix(core): now hides glob loader warning in dev mode
-
-## 2.40.0
-
-### Minor Changes
-
-- dc6a17c: feat(core): added subdomain folder support
-
-## 2.39.2
-
-### Patch Changes
-
-- 0094562: feat(core): added ability to turn of visualizer per resource
-
-## 2.39.1
-
-### Patch Changes
-
-- 7dcd349: fix(core): fixing badges for specification files and types
-
-## 2.39.0
-
-### Minor Changes
-
-- e1578ae: feat(core): added support for multi spec files for services
-
-## 2.38.1
-
-### Patch Changes
-
-- e3374f5: feat(core): version dropdown added to visualizer
-
-## 2.38.0
-
-### Minor Changes
-
-- 7c6ad76: feat(core): added google and anthropic models to chat feature
-
-### Patch Changes
-
-- c23584e: fix(core): fix protocol icon nullability issue
-
-## 2.37.4
-
-### Patch Changes
-
-- 186b308: feat(core) added azure messaging protocols
-
-## 2.37.3
-
-### Patch Changes
-
-- c77bc89: feat(core): added ability to embed any nodegraph in your docs
-
-## 2.37.2
-
-### Patch Changes
-
-- 394537f: feat(core): added ability to copy pages and schemas to clipboard
-
-## 2.37.1
-
-### Patch Changes
-
-- 4c3cdd4: fix(core): fixed issue loading in custom landing pages
-
-## 2.37.0
-
-### Minor Changes
-
-- 76464b3: feat(core): added ability for custom landing page for EventCatalog
-
-## 2.36.1
-
-### Patch Changes
-
-- 0c0d378: feat(core): added new protocols for tibco
-
-## 2.36.0
-
-### Minor Changes
-
-- 1042621: feat(core): added entity support to eventcatalog
-
-## 2.35.10
-
-### Patch Changes
-
-- b67bd66: feat(core): badges now accept protocol icons
-
-## 2.35.9
-
-### Patch Changes
-
-- bc5c9a3: fix(core): now loads the eventcatalog stylesheet
-
-## 2.35.8
-
-### Patch Changes
-
-- e4482cc: feat(core): added openai embeddings model option for chat
-
-## 2.35.7
-
-### Patch Changes
-
-- db73875: fix(core): added queries to mention box for chat
-
-## 2.35.6
-
-### Patch Changes
-
-- e3c1b68: fix(core): fixed problem loading config in the chat feature
-
-## 2.35.5
-
-### Patch Changes
-
-- 40336a4: chore(core): generate script now reads .env files
-- 5e480cd: chore(core): removed redundant log
-
-## 2.35.4
-
-### Patch Changes
-
-- 2e78817: fix(core): fixed start command for server catalogs
-
-## 2.35.3
-
-### Patch Changes
-
-- d703b5f: feat(core): env file support and eventcatalog chat updates
-
-## 2.35.2
-
-### Patch Changes
-
-- d52166b: fix(core): fixed redirect for the chat feature
-
-## 2.35.1
-
-### Patch Changes
-
-- 51ac0a6: fix(core): style of sidebar labels
-- 8db9242: fix(core): propagate vite error in eventcatalog build correctly
-
-## 2.35.0
-
-### Minor Changes
-
-- 2cb0534: feat(core): added chat v2 - bring your own keys and server rendered EventCatalog
-
-## 2.34.7
-
-### Patch Changes
-
-- e76317c: fix(core): embedding now works with scale plan
-
-## 2.34.6
-
-### Patch Changes
-
-- 196e711: fix(core): add missing query badge
-- 196098e: feat(core): added figjam component
-
-## 2.34.5
-
-### Patch Changes
-
-- d77355c: feat(core): added support for drawio component
-
-## 2.34.4
-
-### Patch Changes
-
-- e0765c4: feat(core): added support for lucid component
-
-## 2.34.3
-
-### Patch Changes
-
-- 30ac1c7: chore(core): updated catalog sdk version
-- 2f445b2: chore(core): updated astro version
-
-## 2.34.2
-
-### Patch Changes
-
-- d0cfa4d: feat(core): allow flows to reference other flows
-
-## 2.34.1
-
-### Patch Changes
-
-- 933bafd: feat(core): added support for subdomains
-
-## 2.34.0
-
-### Minor Changes
-
-- 7d80063: feat(core): added support for subdomains
-
-### Patch Changes
-
-- fdd24d4: fix(core): consistent layout on User and Team pages
-- a5bca18: fix(core): use the node label in `simple` mode too
-
-## 2.33.12
-
-### Patch Changes
-
-- 39d9f70: fix(core): fix versions list in changelog
-
-## 2.33.11
-
-### Patch Changes
-
-- 57a3879: fix(core): update to schema viewer to support more usecases
-
-## 2.33.10
-
-### Patch Changes
-
-- cb0ce3b: feat(core): deprecation field now supports booleans
-
-## 2.33.9
-
-### Patch Changes
-
-- 80ba8c5: feat(core): added ability to deprecate resources in eventcatalog
-
-## 2.33.8
-
-### Patch Changes
-
-- ce4948d: feat(core): added customization to nodes in visualizer
-
-## 2.33.7
-
-### Patch Changes
-
-- 9a51be2: fix(core): add colors for missing types in NodeGraph legend
-- 8526a17: feat(core): added experimental api for catalog
-- 3a7ca75: feat(core): added customization to nodes in visualizer
-
-## 2.33.6
-
-### Patch Changes
-
-- 5dad823: fix(core): revert for 1340
-
-## 2.33.5
-
-### Patch Changes
-
-- ba769ab: fix(core): astro loaders no longer read node_modules
-- f8c762b: fix(core): visualizer no longer zoomes on moving nodes
-- 1f3ed45: feat(core): added miro components to eventcatalog
-- 8bca5dd: fix(core): changelogs now support EventCatalog components
-- a047db9: feat(core): added miro components to eventcatalog
-
-## 2.33.4
-
-### Patch Changes
-
-- 57dc25c: feat(core): added supported for nested custom docs
-- 9c5893c: feat(core): added ability to add custom link in docs sidebar
-
-## 2.33.3
-
-### Patch Changes
-
-- 59fae38: feat(core): fixes and improvements for ResourceLink
-- d5270b6: fix(core): prevent icon shrinking in PillListFlat.tsx
-- 7dfc047: feat(badges): enhance badge functionality with dynamic icons
-- a6b5cb5: chore(core): updated astro
-- 646f085: feat(core): added GRPC & ZMQ protocol to channels
-
-## 2.33.2
-
-### Patch Changes
-
-- f1576ac: chore(core): replaced schema viewer with new one
-
-## 2.33.1
-
-### Patch Changes
-
-- 23266b5: feat(core): added llms-txt support for custom docs
-- 5f5e81f: feat(core): embed visualizer into custom docs
-
-## 2.33.0
-
-### Minor Changes
-
-- ca07ee5: feat(core): updated custom pages logic
-
-## 2.32.2
-
-### Patch Changes
-
-- fc29b52: feat(core): added new link components
-- a384781: chore(core): updated astro
-
-## 2.32.1
-
-### Patch Changes
-
-- edda4c3: fix(core): types for resource group
-
-## 2.32.0
-
-### Minor Changes
-
-- aa2bda5: feat(core): added resource groups
-
-## 2.31.5
-
-### Patch Changes
-
-- 36291f6: fix(core): fixed highlighting in custom docs and nested docs
-
-## 2.31.4
-
-### Patch Changes
-
-- 18b7d57: fix(core): fixed missing types and removed redundant scroll code for doc pages
-
-## 2.31.3
-
-### Patch Changes
-
-- 41798fb: feat(core): added next and previous to custom docs
-
-## 2.31.2
-
-### Patch Changes
-
-- 8de6538: fix(core): custom-docs now show summaries
-
-## 2.31.1
-
-### Patch Changes
-
-- 43488cb: fix:(core): fixed issue with missing docs in catalogs
-
-## 2.31.0
-
-### Minor Changes
-
-- 145f3ba: feat(core): added custom documentation to eventcatalog
-
-## 2.30.8
-
-### Patch Changes
-
-- 33b2dc3: feat(core): collapse everything except domains in TreeView
-- 79f66a8: feat(core): improve search quality
-- cd99bd5: feat(core): added sidebar to flow resource types and changelog support for flows
-
-## 2.30.7
-
-### Patch Changes
-
-- 548580d: core(fix): update getCollection filter function to match `changelog.mdx`
-
-## 2.30.6
-
-### Patch Changes
-
-- f9fe7a5: feat(core): added ability to add custom nodes in flows
-
-## 2.30.5
-
-### Patch Changes
-
-- b59706f: fix(core): tabs now support optional title param
-
-## 2.30.4
-
-### Patch Changes
-
-- ab46611: chore(core): updated astro versions
-
-## 2.30.3
-
-### Patch Changes
-
-- 53a363a: fix(core): fixed render issue with large message names on architecture view
-
-## 2.30.2
-
-### Patch Changes
-
-- 96e3403: fix(core): fixed custom pages/index.mdx not showing in eventcatalog
-
-## 2.30.1
-
-### Patch Changes
-
-- 86a1ca3: feat(core): sidebar items can now be hidden
-- cc9ba67: feat(core): added optional language prop for Schema component
-- cc9ba67: feat(Schema): add optional language prop for code highlighting
-
-## 2.30.0
-
-### Minor Changes
-
-- 34e3cce: feat(core): moving to astro glob loaders
-
-## 2.29.4
-
-### Patch Changes
-
-- 6aec3b7: fix(core): rss pages now render OK with empty catalog
-
-## 2.29.3
-
-### Patch Changes
-
-- d63ce45: feat(core): customize sidebar labels and badge for messages
-
-## 2.29.2
-
-### Patch Changes
-
-- 9696f82: fix(core): Redirects to latest version now work correctly when basePath is used
-- ba09ab6: fix(core): fixed issue with chat not working when config has path or url in it
-
-## 2.29.1
-
-### Patch Changes
-
-- 9c94fdf: fix(core): fixed icon images which were broken when a base path was used
-
-## 2.29.0
-
-### Minor Changes
-
-- 238db19: feat(core): replaced openapi renderer with new UI
-
-## 2.28.3
-
-### Patch Changes
-
-- 14c748c: fix(core): fixed broken architecture pages when the trailing slash feature was enabled
-
-## 2.28.2
-
-### Patch Changes
-
-- 6bfab57: fix(core): fixed ui issues with architecture in docs
-
-## 2.28.1
-
-### Patch Changes
-
-- 1342032: fix(core): fixed styles in nav bar
-
-## 2.28.0
-
-### Minor Changes
-
-- 5bb6579: feat(core): new nav type and new ui features for docs
-
-### Patch Changes
-
-- dcd6274: chore(core): updated landing page
-
-## 2.27.0
-
-### Minor Changes
-
-- e408977: feat: new architecture pages and initial landing page for EventCatalog
-
-### Patch Changes
-
-- 661eee9: chore(core): added missing tests for url builder
-
-## 2.26.1
-
-### Patch Changes
-
-- b5404ef: refactor(core): migrate `users`/`teams` to Astro new content layer API
-- db9633f: fix(core): fixed broken link in AI instructions
-
-## 2.26.0
-
-### Minor Changes
-
-- c787162: feat(core): added new message table component
-
-## 2.25.1
-
-### Patch Changes
-
-- d84fa26: feat: add protocol check to tile component's href handling
-- 11eac24: fix(core): fixed long edge labels for flows
-- c7fac97: fix(core): fixed broken link on ai page
-- a1ee7da: chore(core): updated astro versions
-
-## 2.25.0
-
-### Minor Changes
-
-- 278b440: feat(core): added context menus to all nodes in visualizer
-
-### Patch Changes
-
-- 375b924: fix(core): remove empty index page to prevent blank docs page
-- 470d62f: fix(core): improved `basePathname` selection in `getTreeView` for the sidebar
-
-## 2.24.3
-
-### Patch Changes
-
-- a9aec83: feat(core): resources added to ai results
-- 2ff4d7e: fix(core): changed default model for AI chat
-
-## 2.24.2
-
-### Patch Changes
-
-- b45488f: fix(core): added browser checks for AI features
-- 0d924f8: fix(plugin): moved the generated ai file location to public dir
-
-## 2.24.1
-
-### Patch Changes
-
-- d8fdb7a: fix(plugin): moved the generated ai file location to public dir
-
-## 2.24.0
-
-### Minor Changes
-
-- 5cc528e: feat(core): added new EventCatalog AI assistant
-
-## 2.23.3
-
-### Patch Changes
-
-- bf92c1d: fix(core): fixed issue for new sidebar for windows
-
-## 2.23.2
-
-### Patch Changes
-
-- a2db8df: fix(core): messages now rendered correctly on service table
-
-## 2.23.1
-
-### Patch Changes
-
-- ec3039e: feat(core): added cli logs to let users know about updates
-- 6501081: chore(core): updated astro version
-
-## 2.23.0
-
-### Minor Changes
-
-- dc707bc: feat(core): added new sidebar type "tree_view". A new sidebar nav that matches your file system
-
-## 2.22.0
-
-### Minor Changes
-
-- 6d967ee: feat(core): added support for llms.txt
-
-## 2.21.5
-
-### Patch Changes
-
-- 5a7801c: chore(core): small ui improvements
-
-## 2.21.4
-
-### Patch Changes
-
-- ee884df: chore(core): added backstage license checks to embed eventcatalog
-
-## 2.21.3
-
-### Patch Changes
-
-- 49ede5c: chore(core): added backstage license checks to embed eventcatalog
-
-## 2.21.2
-
-### Patch Changes
-
-- eec1f5a: chore(core): added catalog update version check
-
-## 2.21.1
-
-### Patch Changes
-
-- e10da45: fix(core): rss feed now gets file dates from git
-
-## 2.21.0
-
-### Minor Changes
-
-- 67ad29f: feat(core): added rss feed for all resources
-
-### Patch Changes
-
-- 85ed55a: chore(core): updated astro versions
-
-## 2.20.3
-
-### Patch Changes
-
-- 22cf545: chore(core): removed redundant/duplicated package.json files for EventCatalog
-
-## 2.20.2
-
-### Patch Changes
-
-- 3891571: fix(core): fixed map of users and teams to owned resources
-
-## 2.20.1
-
-### Patch Changes
-
-- b2fa2ef: fix(core): removed hard coded static page for users
-
-## 2.20.0
-
-### Minor Changes
-
-- 2e0a37e: feat(core): moved users away from docs into directory
-
-## 2.19.9
-
-### Patch Changes
-
-- 577c781: feat(plugin): if apigateway schemas are empty the render-schema-viewe…
-
-## 2.19.8
-
-### Patch Changes
-
-- 21524b3: feat(core): <SchemaViewer/> visibility can be controlled by schema it…
-
-## 2.19.7
-
-### Patch Changes
-
-- e7a1cf9: fix(core): fixed issue with double scroll bars on spec pages
-
-## 2.19.6
-
-### Patch Changes
-
-- 3211cad: refactor(core): reduced amount of data the discover table needs
-
-## 2.19.5
-
-### Patch Changes
-
-- 3872726: chore(core): removed css dependency on spotlight
-
-## 2.19.4
-
-### Patch Changes
-
-- 0d035f5: feat(core): users can now filter by latest version of resources on the discover page
-- c8f86b7: fix(core): fixed dependencies frontmatter quoting when values would be interpreted as non-scalar
-- 8955521: chore(core): updated expressive code plugin for astro
-- 63b4bec: feat(core): changelog collapsed lines simplified
-
-## 2.19.3
-
-### Patch Changes
-
-- 7ffbf6f: chore(core): setup pnpm on the project
-
-## 2.19.2
-
-### Patch Changes
-
-- 0dda8b3: fix(core): removed cache from `getMessages` function as child functions already cache
-- be3a5c1: fix(core): fixed issue where changelog page would show the wrong information
-
-## 2.19.1
-
-### Patch Changes
-
-- 166b0ed: fix(core): ubiquitous language pages now render without any data
-- 475f2b0: fix(core): use slug for changelog matching
-- 1915b3e: fix(core): refactored how versions are sorted across the catalog
-
-## 2.19.0
-
-### Minor Changes
-
-- 5f8dbfe: feat(core): updated astro and also added ubiquitous lang page support
-
-### Patch Changes
-
-- 00f9c2c: fix(core): added ability to sort by semver and numbers
-- 4a710a5: fix(core): fixed the tab component rendering issues on load of page
-- 04ab91d: fix(core): fixed issue with teams/owners not showing in the UI
-
-## 2.18.7
-
-### Patch Changes
-
-- f4e8985: fix(core): visualizer now defaults to correct messages
-- 73b80ae: fix(core): ubiquitous-language matching by domains, also astro upgrade to 5.1.x
-
-## 2.18.6
-
-### Patch Changes
-
-- 1a9b102: fix(core): fixed matching for ubiquitous lang
-- efad265: feat(core): added kinesis protocol to channels
-
-## 2.18.5
-
-### Patch Changes
-
-- a60e94f: feat(core): resources across eventcatalog are now ordered by name
-- 12bbcaa: feat(core) enabled remark-gfm enabling tables in markdown
-
-## 2.18.4
-
-### Patch Changes
-
-- eb01981: fix(core): fixed issue with version ordering now uses semver
-
-## 2.18.3
-
-### Patch Changes
-
-- c8f1847: fix(core): fixing cache issues on build
-
-## 2.18.2
-
-### Patch Changes
-
-- 6f5746b: fix(core): ubiquitous lang now renders on domains
-
-## 2.18.1
-
-### Patch Changes
-
-- 2a0592e: feat(core): added icons packs for mermaid diagrams
-
-## 2.18.0
-
-### Minor Changes
-
-- 972478d: feat(core): added ability to specify dependencies for catalogs
-
-## 2.17.3
-
-### Patch Changes
-
-- f0d68f4: chore(core): updated mermaid to v11
-
-## 2.17.2
-
-### Patch Changes
-
-- 9f960c8: chore(core): cache data between build generation and added script to generate large catalogs
-- 9a61833: fix(core): fixed broken context map link in sidebar
-
-## 2.17.1
-
-### Patch Changes
-
-- 0c2f681: chore(core): removed --root and --port flags from astro preview command
-- fb6c0f2: feat(core): markdown files now support comments
-
-## 2.17.0
-
-### Minor Changes
-
-- 8746d32: chore(core): update to astro 5
-
-## 2.16.6
-
-### Patch Changes
-
-- f73eb3d: feat(core): added admonitions using markdown
-
-## 2.16.5
-
-### Patch Changes
-
-- 45da645: feat(core): forward extra args to astro cli via `--`
-- 46545ee: feat(core): added new <Tabs> component
-
-## 2.16.4
-
-### Patch Changes
-
-- 44ad73d: fix(core): fixed small fontsizes for mermaid diagrams
-
-## 2.16.3
-
-### Patch Changes
-
-- 9c84f9c: feat(core): added inital version of the domain map to visualizer
-
-## 2.16.2
-
-### Patch Changes
-
-- fb2b5c3: chore(core): removed changelog
-- 7559d42: chore(core): revert commit for workspaces
-
-## 2.16.1
-
-### Patch Changes
-
-- a907d96: feat(core): added ubiquitous language support
-- ff449d7: feat(core): added ability to filter by badges
-
-## 2.16.0
-
-### Minor Changes
-
-- ccd3a5a: feat(core): added ubiquitous language support
-
-### Patch Changes
-
-- 18b6478: feat(core): added ability to zoom out even further in visualizer
-- ec7c16c: fix(core): fixed issue rendering animated nodes with flow diagrams
-- dea456a: feat(core): services in the discover table now shows expandable sections
-- e87bb9b: feat(core): sidebar collapsed states now persisted between page loads
-- 38e6165: feat(core): schema viewer now renders yaml files
-
-## 2.15.0
-
-### Minor Changes
-
-- 8e95677: chore(core): refactor to code base moving files to new src directory
-- e260995: chore(core): refactor project files and folders
-
-### Patch Changes
-
-- 920be57: feat(core): added ability to turn channels on/off
-
-## 2.14.3
-
-### Patch Changes
-
-- eb2c620: feat(core): added support to teams chat url in users and teams pages
-- 95ed136: feat(core): added support for rendering avro schema formats in AsyncApi page
-
-## 2.14.2
-
-### Patch Changes
-
-- bb4d278: fix(core): fixed styles for links in the step component
-
-## 2.14.1
-
-### Patch Changes
-
-- a904248: Revert "fix/service-node-graph-metadata (#964)"
-
-## 2.14.0
-
-### Minor Changes
-
-- 536511e: chore(core): refactor core logic to simplify the code
-
-## 2.13.4
-
-### Patch Changes
-
-- 2ad9561: fix(core): fixed issues with node graphs for services and metadata in the nodes
-
-## 2.13.3
-
-### Patch Changes
-
-- b893559: fix(core): fixed issue with styling of schema files
-
-## 2.13.2
-
-### Patch Changes
-
-- 1c79a5f: chore(core): moved types deps to dev deps
-
-## 2.13.1
-
-### Patch Changes
-
-- 240a9d3: fix(core): fixed channel information component
-
-## 2.13.0
-
-### Minor Changes
-
-- 003c1f2: feat(core): adding channels to eventcatalog
-
-## 2.12.3
-
-### Patch Changes
-
-- d0d13c9: chore(core): fixing z-index issue with the header nav and removing the max-width
-
-## 2.12.2
-
-### Patch Changes
-
-- 93e224c: fix(core): custom defined landing page for docs now render on docs tab
-
-## 2.12.1
-
-### Patch Changes
-
-- a57282e: fix(core): new property for AsyncAPI rendering
-- d739d7b: fix(core): changelog buttons now render the correct changelog
-
-## 2.12.0
-
-### Minor Changes
-
-- a136d50: feat(core): services can now send and receive the same messages in vis…
-
-## 2.11.7
-
-### Patch Changes
-
-- 159e2d4: feat(core): added ability to embed discovery table
-
-## 2.11.6
-
-### Patch Changes
-
-- 9a531d2: feat(core): added ability to embed discovery table
-- 2352fc0: feat(core): added ability to embed catalog pages
-- 112f735: feat(core): added ability to embed visualiser without footers
-
-## 2.11.5
-
-### Patch Changes
-
-- 61e5cf1: fix(core): fixed outdir to output to users directory now
-- 6e88fcf: chore(core): moved some GitHub CI/CD to pnpm
-- b29d4f9: chore(core): removed code that copies over files twice to users catalog.
-- a283534: fix(docs): remove blank space from the version tag
-
-## 2.11.4
-
-### Patch Changes
-
-- 7749acd: feat(core): added support for outDir
-
-## 2.11.3
-
-### Patch Changes
-
-- 5442d40: fix(core): counters on homepage only include latest versions
-
-## 2.11.2
-
-### Patch Changes
-
-- 48d61f3: feat(core): added repo support for all resources
-
-## 2.11.1
-
-### Patch Changes
-
-- 214f164: chore(core): minor changes to ui
-
-## 2.11.0
-
-### Minor Changes
-
-- 597dcf2: feat(core): UI improvements to EventCatalog
-
-## 2.10.1
-
-### Patch Changes
-
-- e2c99e7: fix(core): fixed issue adding additional properties to users frontmatter on build
-
-## 2.10.0
-
-### Minor Changes
-
-- aa2090b: feat(core): added support for query message types/resources
-
-## 2.9.1
-
-### Patch Changes
-
-- 5fa9228: fix(core): moving rimraf to dep of project
-
-## 2.9.0
-
-### Minor Changes
-
-- 70d27a7: feat(core): support nested folder structures for domains, services and messages
-
-## 2.8.12
-
-### Patch Changes
-
-- e7cb5d7: chore(core): added astro file path to resources
-
-## 2.8.11
-
-### Patch Changes
-
-- b1912da: fix(core): fixed rapi-docs for large openapi files
-
-## 2.8.10
-
-### Patch Changes
-
-- 2f4b7af: fix(core): fixed issue with using tmp directories
-
-## 2.8.9
-
-### Patch Changes
-
-- 4e0823d: fix(core): fixed issue with importing users package json files
-
-## 2.8.8
-
-### Patch Changes
-
-- 3d3f56e: chore(core): changed the way eventcatalog file is now imported into the project
-
-## 2.8.7
-
-### Patch Changes
-
-- ce04693: fix(core): fixed visualization node graph for domains, reduced overlapping
-
-## 2.8.6
-
-### Patch Changes
-
-- b4c49ef: feat(core): added links to the landing page and fixed resource counter values
-
-## 2.8.5
-
-### Patch Changes
-
-- db41392: fix(core): flows now work with latest semver for services
-- 8376da8: chore(core): fixed url builder for server/client components
-
-## 2.8.4
-
-### Patch Changes
-
-- 95ca9aa: chore(core): removed type checks for consuming catalogs
-
-## 2.8.3
-
-### Patch Changes
-
-- d07a946: chore(core): updated astro versions
-
-## 2.8.2
-
-### Patch Changes
-
-- 591e06f: chore(core): fixed css issues with badges on pages
-
-## 2.8.1
-
-### Patch Changes
-
-- 16c6a28: feat(core): added api path and http verb in openapi viewer
-- c8118b7: fix(core): downloading images in visualizer now shows the whole diagram
-
-## 2.8.0
-
-### Minor Changes
-
-- 6f882b3: feat(core): added ability to focus nodes in the node graph on visualiser
-- dddb730: feat(core): added basic theming support for colors
-
-## 2.7.16
-
-### Patch Changes
-
-- 4d15fdf: fix(core): fixed windows issue for fetching config files
-
-## 2.7.15
-
-### Patch Changes
-
-- 7e63592: fix(core): user ownership on resources within a team
-
-## 2.7.14
-
-### Patch Changes
-
-- c45ebd0: feat(core): added new steps component
-
-## 2.7.13
-
-### Patch Changes
-
-- 6268155: feat(core): new styles added to header and docs sidebar
-
-## 2.7.12
-
-### Patch Changes
-
-- 3016b7f: feat(core): added tile MDX components
-
-## 2.7.11
-
-### Patch Changes
-
-- b106e34: chore(core): added logs for builds
-
-## 2.7.10
-
-### Patch Changes
-
-- d4e2013: chore(core): added ability to check and add properties on users catal…
-
-## 2.7.9
-
-### Patch Changes
-
-- 4cad2eb: fix(core): fixing generate command (again)
-
-## 2.7.8
-
-### Patch Changes
-
-- c67052f: fix(core): fixed generate command
-
-## 2.7.7
-
-### Patch Changes
-
-- f699aed: feat(core): added utils to read and write catalog files
-
-## 2.7.6
-
-### Patch Changes
-
-- bb7333d: feat(core): added protobuf support for auto diffs
-
-## 2.7.5
-
-### Patch Changes
-
-- fde6544: chore(core): updated astro versions
-
-## 2.7.4
-
-### Patch Changes
-
-- 0189ebb: fix(core): ignore trailing slash for icons
-
-## 2.7.3
-
-### Patch Changes
-
-- 1c56b8d: feat(core): added automatic diffs for changelogs for json, yml and avro files
-
-## 2.7.2
-
-### Patch Changes
-
-- ac64dc4: fix(core): only generate discover page for each collection
-
-## 2.7.1
-
-### Patch Changes
-
-- 29ccffc: fix(core): fixed changelogs path matching
-
-## 2.7.0
-
-### Minor Changes
-
-- 515b01f: feat(core): added ability to full screen visuals, new icons for messages and new landing page
-
-## 2.6.4
-
-### Patch Changes
-
-- 0459eec: chore(core): fixed styled for openapi pages
-
-## 2.6.3
-
-### Patch Changes
-
-- d35846b: chore(core): refactored the way pages are rendered reducing code
-
-## 2.6.2
-
-### Patch Changes
-
-- 498f58c: fix(core): generate command now removes any tmp files required for ge…
-
-## 2.6.1
-
-### Patch Changes
-
-- 4aecf6a: fix(core): fixed broken images for specifications on the service page
-
-## 2.6.0
-
-### Minor Changes
-
-- 76bebd7: feat(core): added AsyncAPI pages and new specifications frontmatter api. Deprecated the AsyncAPI and OpenAPI MDX components
-
-## 2.5.5
-
-### Patch Changes
-
-- 2b84b47: fix(core): moved node graphs to only load on client fixing the invalid hook call warning
-
-## 2.5.4
-
-### Patch Changes
-
-- b6052d9: fix(core): added client side url builder
-
-## 2.5.3
-
-### Patch Changes
-
-- a7f1bd0: fix(core): fixed generate script for plugins
-
-## 2.5.2
-
-### Patch Changes
-
-- deacd55: fix(core): can now add producers/consumers without required version number or latest or undefined
-- 2d8ef10: fix(core): homepage redirect status code from permanent to temporary
-
-## 2.5.1
-
-### Patch Changes
-
-- 2bbccf8: feat(core): added new MDX component for Flows
-
-## 2.5.0
-
-### Minor Changes
-
-- 067fd89: feat(core): added flows to eventcatalog
-- c336807: feat(core): only latest versions are now shown in visualizer
-- 20c2cba: fix(core): fixing search not working after builds
-- 7476fa6: fix(core): nodegraphs for domains now work with semver versions
-- 737380a: feat(core): added ability to see how many domains a team and users own
-- a1490d3: chore(core): updated astro versions
-  feat(core): visuzlier arrows stroke width increased
-- 58d6a2d: chore(core): fixing default for flows
-
-## 2.4.0
-
-### Minor Changes
-
-- 3a4b8ec: feat(c0re): add semantic version support, referencing services or messages can now be done with semver
-
-## 2.3.4
-
-### Patch Changes
-
-- a99057e: feat(core): added ability to drag nodes in visualizer
-
-## 2.3.3
-
-### Patch Changes
-
-- dad4df7: fix(core): visualiser now truncates labels on sidebar
-
-## 2.3.2
-
-### Patch Changes
-
-- 90c9219: feat(core): added page redirect to latest version when going to /{resource/{id}
-
-## 2.3.1
-
-### Patch Changes
-
-- 0de35d9: fix(core): vitest no longer added to the npm package
-
-## 2.3.0
-
-### Minor Changes
-
-- d662cb1: feat(core): added custom component support for eventcatalog
-
-## 2.2.7
-
-### Patch Changes
-
-- d7148fa: chore(core): fixed long labels on the documentation sidebar
-
-## 2.2.6
-
-### Patch Changes
-
-- 50a43e0: core(fix): removed forward slash before # to prevent double trailing slash
-- 8104078: chore(core): added windows tests and fixed watcher to work with changelogs files on windows
-
-## 2.2.5
-
-### Patch Changes
-
-- edd58a6: fix(core): enforce the leading slash to the logo
-- 269aef9: fix(core): fixed url paths for EC assets
-
-## 2.2.4
-
-### Patch Changes
-
-- 34fa215: fix(core): now word wrapping code blocks by default in markdown files so not to break the layout of the page
-
-## 2.2.3
-
-### Patch Changes
-
-- ea7302b: fix(core): fixed changelog urls on resource pages
-
-## 2.2.2
-
-### Patch Changes
-
-- 5ec8513: chore(core): added new footer component to tidy up code
-- 7a0e839: fix(core): added defaults for no pages in catalog
-
-## 2.2.1
-
-### Patch Changes
-
-- abac0a7: fix(core): fixed urls on changelogs
-
-## 2.2.0
-
-### Minor Changes
-
-- 9b92648: feat(core): added changelog support for domains, services and messages
-
-## 2.1.0
-
-### Minor Changes
-
-- 35fa4a3: feat(core): added ability to customize the landing page
-
-## 2.0.31
-
-### Patch Changes
-
-- c4f6f40: fix(core): discover table width now fixed on long summarys
-
-## 2.0.30
-
-### Patch Changes
-
-- 32f93a9: fix(core): running eventcatalog on windows (cross-compatibility between operational systems)
-- 956dd32: fix(core): updated service list to render with with name rather than id
-- 6580ff2: fix(core): fixed missing base in redirect target
-
-## 2.0.29
-
-### Patch Changes
-
-- 83d76b7: fix(core): fixed the json schema viewer require issues
-
-## 2.0.28
-
-### Patch Changes
-
-- 0bad036: feat(core): added beta version of generators
-
-## 2.0.27
-
-### Patch Changes
-
-- c6da224: feat(core): added ability to configure landing page
-
-## 2.0.26
-
-### Patch Changes
-
-- 3dc05d8: fix(core): fixed search, now set output path on build
-
-## 2.0.25
-
-### Patch Changes
-
-- 109ce19: feat(core): added optimize flag to make eventcatalog work with large catalogs
-
-## 2.0.24
-
-### Patch Changes
-
-- db66733: fix(core): favicon having invalid url with default base url configuration
-- 26a4a37: fix perf issues for discover pages in build step
-- f29d718: fix(core): sidebar configuration for section visibility is now optional
-- 3426ea8: fix(core): temp fix for domains for users
-
-## 2.0.23
-
-### Patch Changes
-
-- 66a764c: fix(core: fixed additional ts errors)
-
-## 2.0.22
-
-### Patch Changes
-
-- 58a02a1: chore(core): removed console logs
-
-## 2.0.21
-
-### Patch Changes
-
-- 22e4b6d: fix(core): fixed issues with styling
-
-## 2.0.20
-
-### Patch Changes
-
-- 5de772b: fix(core): fixed typescript errors
-
-## 2.0.19
-
-### Patch Changes
-
-- 4be2512: feat(core): added ability to configure port on EventCatlog
-
-## 2.0.18
-
-### Patch Changes
-
-- 209e428: fix(core): fixed domain nav bar in discovery page
-
-## 2.0.17
-
-### Patch Changes
-
-- 6337769: feat(core): added ability to customise header text and logo
-
-## 2.0.16
-
-### Patch Changes
-
-- cae7c0a: fix(core): added missing urls for slash support
-
-## 2.0.15
-
-### Patch Changes
-
-- 73a40b4: fix(core): added support for trailingSlash in the EventCatalog types.
-
-## 2.0.14
-
-### Patch Changes
-
-- 9d61581: feat(core): added support for base url and slashes
-
-## 2.0.13
-
-### Patch Changes
-
-- 1e4c805: feat(core): Adding <SchemaViewer /> component
-
-## 2.0.12
-
-### Patch Changes
-
-- 18f1c3d: fix(core): fixed start and preview commands
-
-## 2.0.11
-
-### Patch Changes
-
-- 45ea9f6: feat(core): added types file for eventcatalog.config.js
-
-## 2.0.10
-
-### Patch Changes
-
-- 62422dd: fix to build
-- 1c42b9f: feat(core): added ability to hide resources in sidebar
-
-## 2.0.9
-
-### Patch Changes
-
-- d4916a0: fix(core): configure width for nodes in visualiser (#560)
-
-## 2.0.8
-
-### Patch Changes
-
-- 5bde1d4: feat(core): versions now show as a dropdown
-
-## 2.0.7
-
-### Patch Changes
-
-- b82d79e: feat(core): Renders names for services side bars and also links to services from domains fixed
-
-## 2.0.6
-
-### Patch Changes
-
-- c098f12: fix(core): hydrate content before building
-
-## 2.0.5
-
-### Patch Changes
-
-- 4410826: feat(core): adding preview and start commands to eventcatalog
-
-## 2.0.4
-
-### Patch Changes
-
-- 00def6d: bug(core): now loads /docs when going to /
-
-## 2.0.3
-
-### Patch Changes
-
-- dc89208: fix(core): core folder now copied on buld
-
-## 2.0.2
-
-### Patch Changes
-
-- a4bfa8b: chore(core): update the project url to the github org
-
-## 2.0.1
-
-### Patch Changes
-
-- 20aa425: chore(misc): Testing the release of EventCatalog
-
-## 2.0.0
-
-New version launched of EventCatalog with major changes.
-
-## 1.2.7
-
-### Patch Changes
-
-- [`65aa33d`](https://github.com/boyney123/eventcatalog/commit/65aa33d618b9f415768554bb85a926c1f1913698) [#510](https://github.com/boyney123/eventcatalog/pull/510) Thanks [@boyney123](https://github.com/boyney123)! - Update mermaid version to latest
-
-## 1.2.6
-
-### Patch Changes
-
-- [`1fce9a2`](https://github.com/boyney123/eventcatalog/commit/1fce9a298ff1820056fcbc4dc75cfd6f18535f60) [#499](https://github.com/boyney123/eventcatalog/pull/499) Thanks [@marciovmartins](https://github.com/marciovmartins)! - feat: add search via query parameter for events, services and domains (#498)
-
-## 1.2.5
-
-### Patch Changes
-
-- [`56b9f0d`](https://github.com/boyney123/eventcatalog/commit/56b9f0daefde6cba75b68c4a5a33742376b540dd) [#485](https://github.com/boyney123/eventcatalog/pull/485) Thanks [@dreglad](https://github.com/dreglad)! - fix: (#484) ensure link exists before opening link in visualizer
-
-- [`56b9f0d`](https://github.com/boyney123/eventcatalog/commit/56b9f0daefde6cba75b68c4a5a33742376b540dd) [#485](https://github.com/boyney123/eventcatalog/pull/485) Thanks [@dreglad](https://github.com/dreglad)! - fix: (#484) ensure link exists before opening link in visualizer.
-
-## 1.2.4
-
-### Patch Changes
-
-- [`821a1a7`](https://github.com/boyney123/eventcatalog/commit/821a1a7553dbfebb6793923d1e49a81fee27826d) [#482](https://github.com/boyney123/eventcatalog/pull/482) Thanks [@WaYdotNET](https://github.com/WaYdotNET)! - fix: visualization of asyncapi: 3.0.0 file
-
-## 1.2.3
-
-### Patch Changes
-
-- [`c2faad3`](https://github.com/boyney123/eventcatalog/commit/c2faad32c756589f4e11e82b7a5b659257e6b98b) [#480](https://github.com/boyney123/eventcatalog/pull/480) Thanks [@boyney123](https://github.com/boyney123)! - fix: bug when copy styles over
-
-## 1.2.2
-
-### Patch Changes
-
-- [`e8846cb`](https://github.com/boyney123/eventcatalog/commit/e8846cb66620581e6cc33a0c8d36ddac912c78b9) [#477](https://github.com/boyney123/eventcatalog/pull/477) Thanks [@boyney123](https://github.com/boyney123)! - feat - fixing copy over
-
-## 1.2.1
-
-### Patch Changes
-
-- [`65a46b1`](https://github.com/boyney123/eventcatalog/commit/65a46b1ecea14837f9cbfa5e66ba3b369f36646a) [#475](https://github.com/boyney123/eventcatalog/pull/475) Thanks [@boyney123](https://github.com/boyney123)! - feat - copy over styles on dev and build
-
-## 1.2.0
-
-### Minor Changes
-
-- [`59fc853`](https://github.com/boyney123/eventcatalog/commit/59fc853878b1e3c5413f7c6fd5bf982b30165693) [#473](https://github.com/boyney123/eventcatalog/pull/473) Thanks [@boyney123](https://github.com/boyney123)! - feat - added ability to add css overrides
-
-## 1.1.2
-
-### Patch Changes
-
-- [`b08f273`](https://github.com/boyney123/eventcatalog/commit/b08f2733b8f6cfea8b89e0708f3ad88bc2e9903f) [#470](https://github.com/boyney123/eventcatalog/pull/470) Thanks [@boyney123](https://github.com/boyney123)! - fix - fixed build with swagger version
-
-## 1.1.1
-
-### Patch Changes
-
-- [`7eb8c93`](https://github.com/boyney123/eventcatalog/commit/7eb8c93a2f13088e45c725dc18699e4f66bdf2c5) [#462](https://github.com/boyney123/eventcatalog/pull/462) Thanks [@boyney123](https://github.com/boyney123)! - fix - copy config file on build
-
-## 1.1.0
-
-### Minor Changes
-
-- [`4b34273`](https://github.com/boyney123/eventcatalog/commit/4b34273931e141a651c0a56e1bc6fba5543869eb) [#447](https://github.com/boyney123/eventcatalog/pull/447) Thanks [@rberger](https://github.com/rberger)! - Force the dependency trim to be version 0.0.3 with a resolution to eliminate a high vulnerability
-
-## 1.0.7
-
-### Patch Changes
-
-- [`63abb59`](https://github.com/boyney123/eventcatalog/commit/63abb596bb2a63caad6349d93b201bac01434f79) [#445](https://github.com/boyney123/eventcatalog/pull/445) Thanks [@boyney123](https://github.com/boyney123)! - fix- build for typescript and react types
-
-## 1.0.6
-
-### Patch Changes
-
-- [`fc2dcd5`](https://github.com/boyney123/eventcatalog/commit/fc2dcd5acc09ea8e03e796537e6b8597f08d5546) [#440](https://github.com/boyney123/eventcatalog/pull/440) Thanks [@rtoro](https://github.com/rtoro)! - feat - added new page for users
-
-## 1.0.5
-
-### Patch Changes
-
-- [`4834e9f`](https://github.com/boyney123/eventcatalog/commit/4834e9f4d1761615e7e5d4740e98c66c00fdc99e) [#438](https://github.com/boyney123/eventcatalog/pull/438) Thanks [@boyney123](https://github.com/boyney123)! - fix: set key on rendered serices, no longer duplicates them
-
-## 1.0.4
-
-### Patch Changes
-
-- [`40a6221`](https://github.com/boyney123/eventcatalog/commit/40a62216f4d9a2d4bfba525bd1f9c92cbd63ecdb) [#414](https://github.com/boyney123/eventcatalog/pull/414) Thanks [@pebbz](https://github.com/pebbz)! - chore(core) - FIX-408 - upgrade typescript
-
-## 1.0.3
-
-### Patch Changes
-
-- [`9476d74`](https://github.com/boyney123/eventcatalog/commit/9476d74af8fc3af8f1aaceb4e6def77e61c5e17f) [#428](https://github.com/boyney123/eventcatalog/pull/428) Thanks [@jlee-spt](https://github.com/jlee-spt)! - feat: Allow fetching of remote asyncapi docs
-
-## 1.0.2
-
-### Patch Changes
-
-- [`69298ce`](https://github.com/boyney123/eventcatalog/commit/69298ce8b46b77c2662ab789af7c00295cb7fe06) [#432](https://github.com/boyney123/eventcatalog/pull/432) Thanks [@boyney123](https://github.com/boyney123)! - chore - locking down Asyncapi version
-
-- [`bfdd189`](https://github.com/boyney123/eventcatalog/commit/bfdd18917d3ec4e51a78dd6c4c93c445e6430e67) [#431](https://github.com/boyney123/eventcatalog/pull/431) Thanks [@jslim](https://github.com/jslim)! - Chore: including fs false by default
-
-## 1.0.1
-
-### Patch Changes
-
-- [`a83e9e5`](https://github.com/boyney123/eventcatalog/commit/a83e9e5e7922689b6ac3326c680a84b9ce582c2a) [#415](https://github.com/boyney123/eventcatalog/pull/415) Thanks [@rafaelrenanpacheco](https://github.com/rafaelrenanpacheco)! - feat: sort sidebar filters
-
-## 1.0.0
-
-### Major Changes
-
-- [`24634aa`](https://github.com/boyney123/eventcatalog/commit/24634aa00d14c05b56cf9fd6e5e7e7dcdd943b07) [#409](https://github.com/boyney123/eventcatalog/pull/409) Thanks [@pebbz](https://github.com/pebbz)! - FIX-276 - Fix bug 276 by upgrading packages
-
-## 0.6.12
-
-### Patch Changes
-
-- [`3bf1979`](https://github.com/boyney123/eventcatalog/commit/3bf19799880cb379e8fbea1bf4cdc40b0c7be7b1) [#400](https://github.com/boyney123/eventcatalog/pull/400) Thanks [@boyney123](https://github.com/boyney123)! - feat- allow props to be used in openAPI components
-
-## 0.6.11
-
-### Patch Changes
-
-- [`21c6260`](https://github.com/boyney123/eventcatalog/commit/21c6260b04bd849f93c11a571c6a6c9b55501911) [#397](https://github.com/boyney123/eventcatalog/pull/397) Thanks [@boyney123](https://github.com/boyney123)! - feta - Adding support for OpenAPI files in events.
-
-## 0.6.10
-
-### Patch Changes
-
-- [`97c0da5`](https://github.com/boyney123/eventcatalog/commit/97c0da5c2976f024286f7760cd688e93b9c53701) [#340](https://github.com/boyney123/eventcatalog/pull/340) Thanks [@michelgrootjans](https://github.com/michelgrootjans)! - - feat - added ability to show node graphs on the event and service overview pages.
-
-## 0.6.9
-
-### Patch Changes
-
-- [`264b6c8`](https://github.com/boyney123/eventcatalog/commit/264b6c8525e59c76bc28bec11d093c5740cf73bf) [#328](https://github.com/boyney123/eventcatalog/pull/328) Thanks [@dremonkey](https://github.com/dremonkey)! - fix: support spaces in projectDIR path
-
-## 0.6.8
-
-### Patch Changes
-
-- [`78945be`](https://github.com/boyney123/eventcatalog/commit/78945be651c48e9194794eff4a73566cb8a045b4) [#360](https://github.com/boyney123/eventcatalog/pull/360) Thanks [@boyney123](https://github.com/boyney123)! - (fix) - fixing 404 issues with domain page
-
-## 0.6.7
-
-### Patch Changes
-
-- [`a93ab13`](https://github.com/boyney123/eventcatalog/commit/a93ab13bf939d8ebdfc771cc6fff23167420a403) [#350](https://github.com/boyney123/eventcatalog/pull/350) Thanks [@ldiego73](https://github.com/ldiego73)! - fix to correctly display the user when there are no events associated with a domain.
-
-- [`a93ab13`](https://github.com/boyney123/eventcatalog/commit/a93ab13bf939d8ebdfc771cc6fff23167420a403) [#350](https://github.com/boyney123/eventcatalog/pull/350) Thanks [@ldiego73](https://github.com/ldiego73)! - fix: correct display of users in domain
-
-## 0.6.6
-
-### Patch Changes
-
-- [`c8b765b`](https://github.com/boyney123/eventcatalog/commit/c8b765b62446097781fd650675b04fe1d4daa287) [#354](https://github.com/boyney123/eventcatalog/pull/354) Thanks [@rafaelrenanpacheco](https://github.com/rafaelrenanpacheco)! - feat: add event tags
-
-## 0.6.5
-
-### Patch Changes
-
-- [`b63773b`](https://github.com/boyney123/eventcatalog/commit/b63773bbb774a1bbf518f3dd0195bba6c09687cd) [#348](https://github.com/boyney123/eventcatalog/pull/348) Thanks [@boyney123](https://github.com/boyney123)! - fix for 260 - nodegraphs used over mermaid graphs when writing to eve…
-
-## 0.6.4
-
-### Patch Changes
-
-- [`adeda51`](https://github.com/boyney123/eventcatalog/commit/adeda51f7f1f5c375e0b54248ac33d4dd2476054) Thanks [@boyney123](https://github.com/boyney123)! - OpenAPI component now supports remote spec files.
-
-## 0.6.3
-
-### Patch Changes
-
-- [`16e792e`](https://github.com/boyney123/eventcatalog/commit/16e792ea72ed524ac80108754a16f655ec6a2a91) [#336](https://github.com/boyney123/eventcatalog/pull/336) Thanks [@boyney123](https://github.com/boyney123)! - adding fix for 324 - domains with services edit link now correct
-
-## 0.6.2
-
-### Patch Changes
-
-- [`8f72480`](https://github.com/boyney123/eventcatalog/commit/8f724804873317940d62b2887aa8f54ced430260) [#330](https://github.com/boyney123/eventcatalog/pull/330) Thanks [@michelgrootjans](https://github.com/michelgrootjans)! - Fix to the 3D node graph
-
-## 0.6.1
-
-### Patch Changes
-
-- [`9315416`](https://github.com/boyney123/eventcatalog/commit/931541626315a753d630593083e2f1f87c7c51cc) [#320](https://github.com/boyney123/eventcatalog/pull/320) Thanks [@mikaelvesavuori](https://github.com/mikaelvesavuori)! - Mermaid component not working
-
-## 0.6.0
-
-### Minor Changes
-
-- [`34358f5`](https://github.com/boyney123/eventcatalog/commit/34358f5b55fa58a8502a81ed44fb9c4b1901bdd2) [#314](https://github.com/boyney123/eventcatalog/pull/314) Thanks [@martzcodes](https://github.com/martzcodes)! - Feature: Add Badge Filtering to Domains, Events, and Services
-
-## 0.5.2
-
-### Patch Changes
-
-- [`7372407`](https://github.com/boyney123/eventcatalog/commit/73724077d528d48d16bfffaa97231e7f63e3903f) [#312](https://github.com/boyney123/eventcatalog/pull/312) Thanks [@boyney123](https://github.com/boyney123)! - fix version for spotlight
-
-## 0.5.1
-
-### Patch Changes
-
-- [`8419a50`](https://github.com/boyney123/eventcatalog/commit/8419a506c7ffa686fb474235474261462949f888) [#308](https://github.com/boyney123/eventcatalog/pull/308) Thanks [@boyney123](https://github.com/boyney123)! - chore: updating to minify files and change cdn for font-awesome
-
-## 0.5.0
-
-### Minor Changes
-
-- [`a790134`](https://github.com/boyney123/eventcatalog/commit/a7901349fc12efce430f5aeda87d5befb03bd628) [#303](https://github.com/boyney123/eventcatalog/pull/303) Thanks [@dpwdec](https://github.com/dpwdec)! - feat: added new badges for event, services and domains
-
-## 0.4.0
-
-### Minor Changes
-
-- [`cda7105`](https://github.com/boyney123/eventcatalog/commit/cda7105b03e5d5aa6fc9451552cc89c1e88e8859) [#304](https://github.com/boyney123/eventcatalog/pull/304) Thanks [@lcsbltm](https://github.com/lcsbltm)! - feat: added support for asyncapi file in service directory. Now supports new AsyncAPI MDX component.
-
-## 0.3.4
-
-### Patch Changes
-
-- [`390f0a1`](https://github.com/boyney123/eventcatalog/commit/390f0a103ca011afbb7611f88f69daf06a930bd5) [#297](https://github.com/boyney123/eventcatalog/pull/297) Thanks [@boyney123](https://github.com/boyney123)! - fix - autoprefix warning in console
-
-## 0.3.3
-
-### Patch Changes
-
-- [`1e30f43`](https://github.com/boyney123/eventcatalog/commit/1e30f439364143022bac7094e06bfbed11e51af9) [#295](https://github.com/boyney123/eventcatalog/pull/295) Thanks [@boyney123](https://github.com/boyney123)! - chore - update mermaid package
-
-## 0.3.2
-
-### Patch Changes
-
-- [`d7368d0`](https://github.com/boyney123/eventcatalog/commit/d7368d0a5dec261e99b3f556af4c90572d4bb38c) [#293](https://github.com/boyney123/eventcatalog/pull/293) Thanks [@boyney123](https://github.com/boyney123)! - fix - allow button configuration on the homescreen
-
-## 0.3.1
-
-### Patch Changes
-
-- [`8ccc733`](https://github.com/boyney123/eventcatalog/commit/8ccc733c69b7b262c6d1d9751d331a101719de42) [#291](https://github.com/boyney123/eventcatalog/pull/291) Thanks [@boyney123](https://github.com/boyney123)! - fix - overflow issues with too many examples in the Examples MDX comp…
-
-## 0.3.0
-
-### Minor Changes
-
-- [`93db111`](https://github.com/boyney123/eventcatalog/commit/93db11169279435a762a8098c2f50014a5698504) [#286](https://github.com/boyney123/eventcatalog/pull/286) Thanks [@boyney123](https://github.com/boyney123)! - feat - users can now edit header links
-
-## 0.2.20
-
-### Patch Changes
-
-- [`3ca978a`](https://github.com/boyney123/eventcatalog/commit/3ca978a5fd16267f3479d67c54fa0f8007f94dc9) [#281](https://github.com/boyney123/eventcatalog/pull/281) Thanks [@dytyniuk](https://github.com/dytyniuk)! - Fix a broken link behind View in Visualiser button on the Event Details page
-
-## 0.2.19
-
-### Patch Changes
-
-- [`6848067`](https://github.com/boyney123/eventcatalog/commit/68480677ed079bb73c0b8e19f60e15abb3aff707) [#264](https://github.com/boyney123/eventcatalog/pull/264) Thanks [@rtoro](https://github.com/rtoro)! - feat: adding search box into service page
-
-## 0.2.18
-
-### Patch Changes
-
-- [`602f726`](https://github.com/boyney123/eventcatalog/commit/602f72693f9b4f3f9dd9838dd8cad2da6c4ff6a2) [#254](https://github.com/boyney123/eventcatalog/pull/254) Thanks [@drub0y](https://github.com/drub0y)! - fix(core): Fixes getEditUrl to build URLs w/URL vs just path.join
-
-## 0.2.17
-
-### Patch Changes
-
-- [`c5330cd`](https://github.com/boyney123/eventcatalog/commit/c5330cd9776de26389271a2bd7b0c589a59b0982) [#265](https://github.com/boyney123/eventcatalog/pull/265) Thanks [@boyney123](https://github.com/boyney123)! - fix: fixing small padding issues on various pages
-
-## 0.2.16
-
-### Patch Changes
-
-- [`6ffc4af`](https://github.com/boyney123/eventcatalog/commit/6ffc4afe7059b98c02b496349ca624c9b672dbcb) [#261](https://github.com/boyney123/eventcatalog/pull/261) Thanks [@boyney123](https://github.com/boyney123)! - fix(core): Fixes node domain service/event linking
-
-## 0.2.15
-
-### Patch Changes
-
-- [`c5cb51f`](https://github.com/boyney123/eventcatalog/commit/c5cb51f60926d2edad806de59873aadab61e0d9d) [#258](https://github.com/boyney123/eventcatalog/pull/258) Thanks [@boyney123](https://github.com/boyney123)! - fix: now checks events folder in domains before moving them to public…
-
-## 0.2.14
-
-### Patch Changes
-
-- [`17a5883`](https://github.com/boyney123/eventcatalog/commit/17a5883bcc15480872c2944296fcac503bfab8c4) [#251](https://github.com/boyney123/eventcatalog/pull/251) Thanks [@boyney123](https://github.com/boyney123)! - fix: build issues with eventcatalog core
-
-## 0.2.13
-
-### Patch Changes
-
-- [`5211140`](https://github.com/boyney123/eventcatalog/commit/5211140b254353b7aa1c5baead6be416a853cc9d) [#240](https://github.com/boyney123/eventcatalog/pull/240) Thanks [@thim81](https://github.com/thim81)! - feat: Analytics - Added Google Analytics option
-
-## 0.2.12
-
-### Patch Changes
-
-- [`4269b19`](https://github.com/boyney123/eventcatalog/commit/4269b199809807bd08968ce4f9c6e025c5d14794) [#241](https://github.com/boyney123/eventcatalog/pull/241) Thanks [@donaldpipowitch](https://github.com/donaldpipowitch)! - chore: improve typings
-
-## 0.2.11
-
-### Patch Changes
-
-- [`8c3c719`](https://github.com/boyney123/eventcatalog/commit/8c3c719b94e005921f6caec16106466da3f86992) [#244](https://github.com/boyney123/eventcatalog/pull/244) Thanks [@otbe](https://github.com/otbe)! - Fix broken links for services that have no domain on events detail page
-
-## 0.2.10
-
-### Patch Changes
-
-- [`41f6b5a`](https://github.com/boyney123/eventcatalog/commit/41f6b5a03645bfac2006f80c013ed7315cbe3add) [#229](https://github.com/boyney123/eventcatalog/pull/229) Thanks [@rtoro](https://github.com/rtoro)! - feat(core): allow the use of swagger ui in service pages
-
-## 0.2.9
-
-### Patch Changes
-
-- [`3740427`](https://github.com/boyney123/eventcatalog/commit/37404275e021c4d55ae43f5efbf12e321bf65025) [#230](https://github.com/boyney123/eventcatalog/pull/230) Thanks [@boyney123](https://github.com/boyney123)! - fix: visualiser now supports long names in diagram (again)
-
-## 0.2.8
-
-### Patch Changes
-
-- [`2985a14`](https://github.com/boyney123/eventcatalog/commit/2985a14ecdebb5f15ea0ff6512ee88f8863e676f) [#227](https://github.com/boyney123/eventcatalog/pull/227) Thanks [@boyney123](https://github.com/boyney123)! - feat: adding new node in visualiser to show all events and services
-
-## 0.2.7
-
-### Patch Changes
-
-- [`4e03a95`](https://github.com/boyney123/eventcatalog/commit/4e03a95f1420c36169232723f277e88b12c3d5f7) [#224](https://github.com/boyney123/eventcatalog/pull/224) Thanks [@boyney123](https://github.com/boyney123)! - feat: visualiser on click now sets query params
-
-## 0.2.6
-
-### Patch Changes
-
-- [`ccb524a`](https://github.com/boyney123/eventcatalog/commit/ccb524abc97ec7c58b66fd8b1fcb34b0f9a7bd02) [#217](https://github.com/boyney123/eventcatalog/pull/217) Thanks [@otbe](https://github.com/otbe)! - fix: add a stable render key for events/services in visualizer
-
-## 0.2.5
-
-### Patch Changes
-
-- [`65ee3da`](https://github.com/boyney123/eventcatalog/commit/65ee3daab667c0f8b960733c738e3fb12f683144) [#215](https://github.com/boyney123/eventcatalog/pull/215) Thanks [@otbe](https://github.com/otbe)! - add a stable render key for events
-
-## 0.2.4
-
-### Patch Changes
-
-- [`c833a2a`](https://github.com/boyney123/eventcatalog/commit/c833a2a74b049e231c804504550b942d4dc33e70) [#213](https://github.com/boyney123/eventcatalog/pull/213) Thanks [@boyney123](https://github.com/boyney123)! - chore: update to new nextjs version
-
-## 0.2.3
-
-### Patch Changes
-
-- [`a0b90f9`](https://github.com/boyney123/eventcatalog/commit/a0b90f9a4ce9bfd0409b2dff44da5f00bafdfa87) [#211](https://github.com/boyney123/eventcatalog/pull/211) Thanks [@boyney123](https://github.com/boyney123)! - fix: fixing domain mappings and change log issues with domains
-
-## 0.2.2
-
-### Patch Changes
-
-- [`7dcdd9e`](https://github.com/boyney123/eventcatalog/commit/7dcdd9efa077ab9beafcb92bf4789359f9eed02c) [#209](https://github.com/boyney123/eventcatalog/pull/209) Thanks [@boyney123](https://github.com/boyney123)! - fix: now check for events dir before moving schemas
-
-## 0.2.1
-
-### Patch Changes
-
-- [`ccefeee`](https://github.com/boyney123/eventcatalog/commit/ccefeeee93e80620c1c3755676bd0dbe448b4a8a) [#206](https://github.com/boyney123/eventcatalog/pull/206) Thanks [@boyney123](https://github.com/boyney123)! - feat: fixing domains and adding them to create package
-
-## 0.2.0
-
-### Minor Changes
-
-- [`8352416`](https://github.com/boyney123/eventcatalog/commit/835241609aa03cb8158b7a5a1c662c57f8e22505) [#204](https://github.com/boyney123/eventcatalog/pull/204) Thanks [@boyney123](https://github.com/boyney123)! - feat: adding domain support to eventcatalog
-
-## 0.1.19
-
-### Patch Changes
-
-- [`a6f5ae3`](https://github.com/boyney123/eventcatalog/commit/a6f5ae3684279b57cbb4c337e98a5373a2facabb) [#195](https://github.com/boyney123/eventcatalog/pull/195) Thanks [@donaldpipowitch](https://github.com/donaldpipowitch)! - fix(logs): break line in diff view
-
-* [`f48322a`](https://github.com/boyney123/eventcatalog/commit/f48322ab96be22a65baa4cbd5b5ce6d7a0fadd8b) [#167](https://github.com/boyney123/eventcatalog/pull/167) Thanks [@thim81](https://github.com/thim81)! - feat: set page title, description, favicon and og metadata
-
-## 0.1.18
-
-### Patch Changes
-
-- [`3eb7f3b`](https://github.com/boyney123/eventcatalog/commit/3eb7f3b98ef5061beaff4d1ebfac3874cab33c95) [#190](https://github.com/boyney123/eventcatalog/pull/190) Thanks [@boyney123](https://github.com/boyney123)! - chore: added new footer link for visualiser
-
-## 0.1.17
-
-### Patch Changes
-
-- [`d57e67b`](https://github.com/boyney123/eventcatalog/commit/d57e67bf38be9391841b3c6dee6ab360b2eb1325) [#188](https://github.com/boyney123/eventcatalog/pull/188) Thanks [@boyney123](https://github.com/boyney123)! - fixing visualiser for mobile devices
-
-## 0.1.16
-
-### Patch Changes
-
-- [`2d10847`](https://github.com/boyney123/eventcatalog/commit/2d108470af945e1cec59c114627878c56d7385dd) [#186](https://github.com/boyney123/eventcatalog/pull/186) Thanks [@boyney123](https://github.com/boyney123)! - feat: added new visualiser feature
-
-## 0.1.15
-
-### Patch Changes
-
-- [`60bea4d`](https://github.com/boyney123/eventcatalog/commit/60bea4db471bf3c63a936b86ce7ee549e73972a6) [#182](https://github.com/boyney123/eventcatalog/pull/182) Thanks [@thim81](https://github.com/thim81)! - fix: optional title for all MDX components
-
-* [`bf5bab4`](https://github.com/boyney123/eventcatalog/commit/bf5bab44b9be92c5888c6548694c42d1fa83a678) [#184](https://github.com/boyney123/eventcatalog/pull/184) Thanks [@thim81](https://github.com/thim81)! - fix: increase node width for NodeGraph
-
-## 0.1.14
-
-### Patch Changes
-
-- [`1558d17`](https://github.com/boyney123/eventcatalog/commit/1558d17b1c9f925c8e74d22b57edbfc4195a73a6) [#178](https://github.com/boyney123/eventcatalog/pull/178) Thanks [@boyney123](https://github.com/boyney123)! - feat: added better code example component
-
-## 0.1.13
-
-### Patch Changes
-
-- [`ca01bef`](https://github.com/boyney123/eventcatalog/commit/ca01bef1659b2c364210a86e0f9e916f6c1fbaa4) [#166](https://github.com/boyney123/eventcatalog/pull/166) Thanks [@thim81](https://github.com/thim81)! - feat: new nodegraph component to render services and events
-
-## 0.1.12
-
-### Patch Changes
-
-- [`5dcc188`](https://github.com/boyney123/eventcatalog/commit/5dcc188dbd68f70b867e38df91211ba077f14189) [#175](https://github.com/boyney123/eventcatalog/pull/175) Thanks [@thim81](https://github.com/thim81)! - fix: mermaid diagram with pub/sub of same service now shows correctly
-
-## 0.1.11
-
-### Patch Changes
-
-- [`0976201`](https://github.com/boyney123/eventcatalog/commit/0976201a6949f4a78934a4ddfb75e7ea4598caae) [#172](https://github.com/boyney123/eventcatalog/pull/172) Thanks [@boyney123](https://github.com/boyney123)! - fix: header logo now reads from config
-
-## 0.1.10
-
-### Patch Changes
-
-- [`b44bd6c`](https://github.com/boyney123/eventcatalog/commit/b44bd6ca73194165e6448abebd020e3d6f3007a2) [#169](https://github.com/boyney123/eventcatalog/pull/169) Thanks [@thim81](https://github.com/thim81)! - fix: logic for services publish & subscribe nodes
-
-## 0.1.9
-
-### Patch Changes
-
-- [`c4d78c7`](https://github.com/boyney123/eventcatalog/commit/c4d78c77da6bc18638c6612e865c2c8cdd596e0b) [#139](https://github.com/boyney123/eventcatalog/pull/139) Thanks [@thim81](https://github.com/thim81)! - feat: add new eventcatalog config property to set homepage url
-
-## 0.1.8
-
-### Patch Changes
-
-- [`fd9b26a`](https://github.com/boyney123/eventcatalog/commit/fd9b26a24fd94e298b79b59777f148988a7c89b1) [#151](https://github.com/boyney123/eventcatalog/pull/151) Thanks [@thim81](https://github.com/thim81)! - feat: new mdx component json schema viewer
-
-## 0.1.7
-
-### Patch Changes
-
-- [`740c504`](https://github.com/boyney123/eventcatalog/commit/740c5041f033aff975a7ce89e99b3722b271e2b3) [#154](https://github.com/boyney123/eventcatalog/pull/154) Thanks [@boyney123](https://github.com/boyney123)! - fix: trying to fix npm versions problem
-
-## 0.1.6
-
-### Patch Changes
-
-- [`00e3c89`](https://github.com/boyney123/eventcatalog/commit/00e3c898ca8bf72bd563d246d6a2ee8620dd8284) [#143](https://github.com/boyney123/eventcatalog/pull/143) Thanks [@thim81](https://github.com/thim81)! - feat: mermaid name and link
-
-* [`b4774fb`](https://github.com/boyney123/eventcatalog/commit/b4774fbf9773e66e1f85d71e99992e699833bf99) [#141](https://github.com/boyney123/eventcatalog/pull/141) Thanks [@thim81](https://github.com/thim81)! - bug: use title when setting page title
-
-## 0.1.5
-
-### Patch Changes
-
-- [`1975995`](https://github.com/boyney123/eventcatalog/commit/1975995e2a77662742e8f7d95b827ff3cb0e4ac2) [#136](https://github.com/boyney123/eventcatalog/pull/136) Thanks [@boyney123](https://github.com/boyney123)! - fix: header link now goes to landing page
-
-## 0.1.4
-
-### Patch Changes
-
-- [`71d0b85`](https://github.com/boyney123/eventcatalog/commit/71d0b85139cb057db718c10bf5f5aa6017cfe43c) [#132](https://github.com/boyney123/eventcatalog/pull/132) Thanks [@boyney123](https://github.com/boyney123)! - fix: build directory is now copied over to the users proejct dir
-
-## 0.1.3
-
-### Patch Changes
-
-- [`904c4df`](https://github.com/boyney123/eventcatalog/commit/904c4dff59bfdac681d8c18879a5840862aeb616) [#127](https://github.com/boyney123/eventcatalog/pull/127) Thanks [@boyney123](https://github.com/boyney123)! - bug: fixed issue with purging css from the admonition component
-
-## 0.1.2
-
-### Patch Changes
-
-- [`cc8eb2f`](https://github.com/boyney123/eventcatalog/commit/cc8eb2fe14501447206bdb8fe141a0575c753636) [#121](https://github.com/boyney123/eventcatalog/pull/121) Thanks [@otbe](https://github.com/otbe)! - Allow to configure "trailingSlash"
-
-* [`dacd9eb`](https://github.com/boyney123/eventcatalog/commit/dacd9eb41e3f519341f32e60c4de27df5a9137b7) [#120](https://github.com/boyney123/eventcatalog/pull/120) Thanks [@thim81](https://github.com/thim81)! - feat: Hide owners section if the events has owners defined
-
-## 0.1.1
-
-### Patch Changes
-
-- [`23930c8`](https://github.com/boyney123/eventcatalog/commit/23930c8f4f4a9234e037473aaeccae3dafdfe385) [#114](https://github.com/boyney123/eventcatalog/pull/114) Thanks [@boyney123](https://github.com/boyney123)! - feat: adding search to events page
-
-* [`e37ff4b`](https://github.com/boyney123/eventcatalog/commit/e37ff4b31c06779ae89f2b17beb14cb409d464e3) [#113](https://github.com/boyney123/eventcatalog/pull/113) Thanks [@otbe](https://github.com/otbe)! - Configure base path
-
-## 0.1.0
-
-### Minor Changes
-
-- [`688e2da`](https://github.com/boyney123/eventcatalog/commit/688e2da9ade503e4276c6710c77e45f4652e19a1) [#111](https://github.com/boyney123/eventcatalog/pull/111) Thanks [@boyney123](https://github.com/boyney123)! - feat: catalog now staticlly exports rather than using server code
-
-## 0.0.14
-
-### Patch Changes
-
-- [`7c23703`](https://github.com/boyney123/eventcatalog/commit/7c237039535d7f5d6f229396cf59eb5cbf5b0645) [#109](https://github.com/boyney123/eventcatalog/pull/109) Thanks [@boyney123](https://github.com/boyney123)! - fix: issue with long names for services and events rendering incorrectly
-
-## 0.0.13
-
-### Patch Changes
-
-- [`732dac2`](https://github.com/boyney123/eventcatalog/commit/732dac24c1de62537732083a53c2218c2794773a) [#102](https://github.com/boyney123/eventcatalog/pull/102) Thanks [@boyney123](https://github.com/boyney123)! - feat: allow default frontmatter when creating events
-
-## 0.0.12
-
-### Patch Changes
-
-- [`dd1b29f`](https://github.com/boyney123/eventcatalog/commit/dd1b29f81658a3c5bea9ed92c1cf54265c7feb0b) [#98](https://github.com/boyney123/eventcatalog/pull/98) Thanks [@boyney123](https://github.com/boyney123)! - feat: adding more mermaid support in mdx
-
-## 0.0.11
-
-### Patch Changes
-
-- [`97e447a`](https://github.com/boyney123/eventcatalog/commit/97e447aa0ec255b2c879eac7fa83d7b705230790) [#95](https://github.com/boyney123/eventcatalog/pull/95) Thanks [@boyney123](https://github.com/boyney123)! - fix: edit url is now optional in not found pages and no longer fetche…
-
-## 0.0.10
-
-### Patch Changes
-
-- [`df372c6`](https://github.com/boyney123/eventcatalog/commit/df372c675e76a4a5980740222ccf8268c0c71540) [#91](https://github.com/boyney123/eventcatalog/pull/91) Thanks [@boyney123](https://github.com/boyney123)! - feat: fix-generator
-
-## 0.0.9
-
-### Patch Changes
-
-- [`b7202dc`](https://github.com/boyney123/eventcatalog/commit/b7202dcd7548d1d0f406ce9d979182cd4c09232a) [#82](https://github.com/boyney123/eventcatalog/pull/82) Thanks [@boyney123](https://github.com/boyney123)! - fix: event log page now displays correct name
-
-## 0.0.8
-
-### Patch Changes
-
-- [`534bec1`](https://github.com/boyney123/eventcatalog/commit/534bec11f57bcabe7f79f40338ae02bef134efc2) [#78](https://github.com/boyney123/eventcatalog/pull/78) Thanks [@thim81](https://github.com/thim81)! - feat: externalLinks for services
-
-* [`b557ff8`](https://github.com/boyney123/eventcatalog/commit/b557ff8f7186b939cbe1e23f2c0e1e9a7254c907) [#79](https://github.com/boyney123/eventcatalog/pull/79) Thanks [@boyney123](https://github.com/boyney123)! - fix: adding keys on maps in react
-
-- [`407d9e0`](https://github.com/boyney123/eventcatalog/commit/407d9e0d7f8d5eab4747ce0af6d5079204b53d21) [#75](https://github.com/boyney123/eventcatalog/pull/75) Thanks [@thim81](https://github.com/thim81)! - feat: optional editUrl config
-
-* [`9eb7463`](https://github.com/boyney123/eventcatalog/commit/9eb7463b32baa09a6dd693e7f0eede63e33cd39c) [#71](https://github.com/boyney123/eventcatalog/pull/71) Thanks [@thim81](https://github.com/thim81)! - feat: link to external event documentation added
-
-## 0.0.7
-
-### Patch Changes
-
-- [`ee17db8`](https://github.com/boyney123/eventcatalog/commit/ee17db8958ac6368f7d833f0d3ebec2604722e42) [#56](https://github.com/boyney123/eventcatalog/pull/56) Thanks [@boyney123](https://github.com/boyney123)! - feat: changelog.md files now belong inside the versioned folders
-
-## 0.0.6
-
-### Patch Changes
-
-- [`ad66a66`](https://github.com/boyney123/eventcatalog/commit/ad66a66b526a167cc8da43dd2371642c9f9029f2) [#49](https://github.com/boyney123/eventcatalog/pull/49) Thanks [@boyney123](https://github.com/boyney123)! - fix: now supports any extension for event examples also added missing docs
-
-## 0.0.5
-
-### Patch Changes
-
-- [`576debd`](https://github.com/boyney123/eventcatalog/commit/576debdfc5dbc2fbbf98e2b3f4d78b84f9a07669) [#46](https://github.com/boyney123/eventcatalog/pull/46) Thanks [@boyney123](https://github.com/boyney123)! - fix: using cross-env to fix issues with windows OS
-
-## 0.0.4
-
-### Patch Changes
-
-- [`1eb4572`](https://github.com/boyney123/eventcatalog/commit/1eb4572918ac06afb64554fef2fc1a3877fbf06d) [#44](https://github.com/boyney123/eventcatalog/pull/44) Thanks [@boyney123](https://github.com/boyney123)! - feat: added more customise options and documentation for them
-
-## 0.0.3
-
-### Patch Changes
-
-- [`23a96fc`](https://github.com/boyney123/eventcatalog/commit/23a96fc651907517cee937657be14cbf9fe95fb9) [#42](https://github.com/boyney123/eventcatalog/pull/42) Thanks [@boyney123](https://github.com/boyney123)! - fix: now remove the .next folder before we start the dev server foric…
-
-## 0.0.2
-
-### Patch Changes
-
-- [`53b27cb`](https://github.com/boyney123/eventcatalog/commit/53b27cb5bb5ab7fa8d526309c6dd50e1f17f3db1) [#39](https://github.com/boyney123/eventcatalog/pull/39) Thanks [@boyney123](https://github.com/boyney123)! - feat: removed ids from services
diff --git a/CLAUDE.md b/CLAUDE.md
index 32e2adcfb..f6a0bf645 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,25 +2,350 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Build, Lint, and Test Commands
+## Project Overview
 
-- **Build**: `pnpm run verify-build:catalog`
-- **Test**: `pnpm run test`
-- **Format and lint code**: `pnpm run format`
-- **Start the catalog**: `pnpm run start:catalog`
+EventCatalog is an open-source documentation tool for Event-Driven Architectures. It helps teams document events, commands, queries, services, domains, and flows in a discoverable catalog. Built with Astro, React, and TypeScript.
 
-## Code Style Guidelines
+This is a **monorepo** managed with Turborepo and pnpm workspaces containing these packages:
+- `@eventcatalog/core` - The main EventCatalog application
+- `@eventcatalog/sdk` - SDK for programmatically interacting with EventCatalog
+- `@eventcatalog/create-eventcatalog` - CLI tool for scaffolding new EventCatalog projects
+- `@eventcatalog/visualiser` - Standalone React visualiser component (ReactFlow-based node graphs)
+- `@eventcatalog/dsl-playground` - Browser-based DSL playground for authoring EventCatalog DSL
+- `@eventcatalog/language-server` - Language server for the EventCatalog DSL (parsing, diagnostics, completion)
 
-### TypeScript
+## Quick Reference Commands
 
-- Strict typing with TypeScript
-- ES modules with explicit imports/exports
-- Error handling with proper type guards
+| Task | Command |
+|------|---------|
+| Start dev server | `pnpm run start:catalog` |
+| Start SSR server | `pnpm run start:catalog:server` |
+| Build all packages | `pnpm run build` or `pnpm run build:bin` |
+| Build catalog example | `pnpm run verify-build:catalog` |
+| Test (all packages) | `pnpm run test` |
+| Test (CI mode) | `pnpm run test:ci` |
+| Test (single file) | `pnpm run test path/to/file.test.ts --run` |
+| Format code | `pnpm run format` |
+| Check formatting | `pnpm run format:diff` |
+| E2E tests | `pnpm run test:e2e` |
+| Create changeset | `pnpm changeset` |
+| Release packages | `pnpm run release` |
 
 ## Project Structure
 
-- `/eventcatalog` - The EventCatalog codebase
-- `/examples/default` - An example of how users use EventCatalog. This is the default example that is used when you run `pnpm run start:catalog`
-- `/scripts` - Scripts to help with the development of the EventCatalog
+```
+/packages
+  /core                      # @eventcatalog/core
+    /eventcatalog            # Main application source
+      /src
+        /components          # React and Astro components
+        /pages               # Astro pages and API routes
+        /enterprise          # Scale plan features (AI Chat, MCP Server)
+        /utils               # Shared utilities
+          /collections       # Astro content collection helpers
+        /layouts             # Page layouts
+        /styles              # CSS and theme files
+        /types               # TypeScript type definitions
+        /stores              # Nanostores state management
+        /content             # Content collection definitions
+        /__tests__           # Unit tests (colocated with source)
+    /bin                     # CLI entry point
+    /scripts                 # Build and development scripts
+  /sdk                       # @eventcatalog/sdk
+    /src                     # SDK source code
+      /test                  # SDK tests (510 tests)
+    /dist                    # Built output (not committed)
+  /create-eventcatalog       # @eventcatalog/create-eventcatalog
+    /templates               # Project templates (default, asyncapi, openapi, etc.)
+    /helpers                 # Template helpers
+    /dist                    # Built output (not committed)
+  /visualiser                # @eventcatalog/visualiser
+    /src
+      /components            # NodeGraph, FocusMode, Search, etc.
+      /nodes                 # Node type components (service, event, command, etc.)
+      /edges                 # Edge type components (animated, multiline, flow)
+      /utils                 # Layout, mermaid export, clipboard utilities
+      /types                 # Shared types (including DslGraph)
+  /playground                # @eventcatalog/dsl-playground
+    /src
+      /components            # Editor, Visualizer, TabBar
+      /hooks                 # useDslParser
+      /monaco                # Monaco editor config, completions, diagnostics
+      /examples              # Built-in DSL examples
+  /language-server           # @eventcatalog/language-server
+    /src                     # DSL parser, graph builder, formatter
+/examples
+  /default                   # Default example catalog (used by start:catalog)
+  /e-commerce                # E-commerce example
+/.changeset                  # Changesets for versioning
+/.github/workflows           # CI/CD workflows
+```
+
+## Tech Stack
+
+- **Monorepo**: Turborepo + pnpm workspaces
+- **Framework**: Astro 5 with React islands
+- **Styling**: Tailwind CSS with CSS variables for theming
+- **State**: Nanostores
+- **Testing**: Vitest (unit), Playwright (E2E)
+- **Content**: Astro Content Collections with Zod schemas
+- **AI Features**: Vercel AI SDK, MCP Protocol
+- **Versioning**: Changesets
+
+## Code Conventions
+
+### Imports
+
+```typescript
+// Use node: prefix for Node.js built-ins
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Use path aliases
+import { getCollection } from 'astro:content';
+import { myUtil } from '@utils/my-util';
+import { MyComponent } from '@components/MyComponent';
+```
+
+### TypeScript
+
+- Strict typing enabled
+- Use `as const` for literal types
+- Prefer type guards over type assertions
+- Use Zod for runtime validation (especially in API routes)
+
+### Astro Content Collections
+
+Resources are stored in content collections. Key collections:
+- `events`, `commands`, `queries` (messages)
+- `services`, `domains`, `flows`, `channels`, `entities`
+- `teams`, `users` (non-versioned)
+
+The whole astro collection schemas are in the `eventcatalog/src/content.config.ts` file.
+
+
+### Getting collection information
+
+We prefer to use the utility classes we have to get collection for example:
+
+```
+import { getEvents } from '@utils/collections/events';
+import { getCommands } from '@utils/collections/commands';
+import { getQueries } from '@utils/collections/queries';
+import { getServices } from '@utils/collections/services';
+import { getDomains } from '@utils/collections/domains';
+import { getFlows } from '@utils/collections/flows';
+import { getChannels } from '@utils/collections/channels';
+import { getEntities } from '@utils/collections/entities';
+import { getTeams } from '@utils/collections/teams';
+import { getUsers } from '@utils/collections/users';
+```
+
+Where you cant do that though you may use the `getCollection` and `getEntry` functions from the `astro:content` package.
+
+```typescript
+// Getting collections
+import { getCollection, getEntry } from 'astro:content';
+
+const events = await getCollection('events');
+const event = await getEntry('events', 'OrderCreated-1.0.0');
+```
+
+### Versioning
+
+Most resources are versioned. Entry IDs follow the pattern: `{id}-{version}` (e.g., `OrderCreated-1.0.0`).
+
+When you need to get specific version or latest version you need to use the `getItemsFromCollectionByIdAndSemverOrLatest` utility function.
+
+```typescript
+// Use existing utilities for version handling
+import { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
+```
+
+### Error Handling
+
+For API routes and tools, return error objects instead of throwing:
+
+```typescript
+if (!resource) {
+  return { error: `Resource not found: ${id}` };
+}
+```
+
+### Pagination
+
+Use cursor-based pagination with the `paginate()` helper from `@enterprise/tools/catalog-tools`:
+
+```typescript
+import { paginate } from '@enterprise/tools/catalog-tools';
+
+const result = paginate(items, cursor, pageSize);
+if ('error' in result) return result;
+```
+
+## Feature Flags
+
+Check feature availability before using enterprise features:
+
+```typescript
+import { isEventCatalogScaleEnabled, isSSR } from '@utils/feature';
+
+if (!isEventCatalogScaleEnabled()) {
+  return { error: 'Feature requires Scale plan' };
+}
+```
+
+## Testing
+
+- Tests are colocated in `__tests__` directories (core) or `src/test` (SDK)
+- Test files use `.test.ts` or `.test.tsx` extension
+- Example catalogs for testing: `packages/core/eventcatalog/src/__tests__/example-catalog/`
+- SDK has 510 tests in `packages/sdk/src/test/`
+
+Don't run tests in watch mode.
+
+```bash
+# Run all tests (all packages via Turbo)
+pnpm run test
+
+# Run tests in CI mode
+pnpm run test:ci
+
+# Run specific test file
+pnpm run test packages/core/eventcatalog/src/utils/__tests__/my-util.test.ts --run
+
+# Run SDK tests only
+pnpm --filter @eventcatalog/sdk run test
+
+# Run tests matching pattern
+pnpm run test -t "getResources" --run
+```
+
+## Theming Guidelines
+
+EventCatalog uses CSS variables for theming to support light/dark mode and custom themes.
+
+### Use CSS Variables Instead of Hardcoded Colors
+
+```astro
+<!-- Correct - uses CSS variables -->
+<div class="bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text))]">
+
+<!-- Incorrect - hardcoded colors -->
+<div class="bg-white text-gray-900 dark:bg-gray-900 dark:text-white">
+```
+
+### Common CSS Variables
+
+| Variable | Usage |
+|----------|-------|
+| `--ec-page-bg` | Page/content background |
+| `--ec-page-text` | Primary text color |
+| `--ec-page-text-muted` | Secondary/muted text |
+| `--ec-page-border` | Borders and dividers |
+| `--ec-card-bg` | Card/elevated surface background |
+| `--ec-accent` | Accent/brand color |
+| `--ec-accent-subtle` | Light accent background |
+| `--ec-accent-text` | Text on accent backgrounds |
+| `--ec-button-bg` | Button background |
+| `--ec-button-text` | Button text |
+| `--ec-icon-color` | Icon default color |
+| `--ec-icon-hover` | Icon hover color |
+| `--ec-input-bg` | Input field background |
+| `--ec-input-border` | Input field border |
+| `--ec-input-text` | Input field text |
+
+### Theme Files
+
+- Base theme: `eventcatalog/src/styles/theme.css`
+- Additional themes: `eventcatalog/src/styles/themes/*.css`
+
+### Key Points
+
+1. Variables use RGB values without `rgb()` wrapper for Tailwind opacity support
+2. Use syntax `[rgb(var(--ec-variable))]` in Tailwind classes
+3. For opacity: `[rgb(var(--ec-variable)/0.5)]`
+4. Dark mode handled via `data-theme="dark"` attribute
+5. Never use `dark:` Tailwind variants for theme colors
+
+## Common Patterns
+
+### API Routes with Hono
+
+For complex API routes, use Hono inside Astro API routes:
+
+```typescript
+import type { APIRoute } from 'astro';
+import { Hono } from 'hono';
+
+const app = new Hono().basePath('/api/my-route');
+
+app.get('/', async (c) => {
+  return c.json({ message: 'Hello' });
+});
+
+export const ALL: APIRoute = async ({ request }) => {
+  return app.fetch(request);
+};
+
+export const prerender = false;
+```
+
+### Shared Tool Implementations
+
+When building features used by both AI Chat and MCP Server, add shared logic to `@enterprise/tools/catalog-tools.ts`.
+
+## Monorepo Workflow
+
+### Working with Packages
+
+- **Core** depends on **SDK** and **Visualiser** via `workspace:*` references
+- **Playground** depends on **Visualiser** and **Language Server**
+- **Visualiser** is standalone (no internal workspace dependencies)
+- Changes to workspace dependencies are automatically picked up in development
+- Build commands run via Turbo (handles dependency ordering and caching)
+- Each package has its own `package.json` with build/test/format scripts
+
+### Running Package-Specific Commands
+
+```bash
+# Run command in specific package
+pnpm --filter @eventcatalog/core run start:catalog
+pnpm --filter @eventcatalog/sdk run test
+
+# Run command in all packages (via Turbo)
+pnpm run build        # Builds all packages
+pnpm run test         # Tests all packages
+pnpm run format       # Formats all packages
+```
+
+### Versioning and Releases
+
+- Use **changesets** for versioning: `pnpm changeset`
+- Changesets go in `.changeset/` directory
+- Choose version bump: `patch`, `minor`, or `major`
+- Select which packages are affected
+- On merge to main, changesets bot creates version PR
+- Merging version PR publishes all packages to npm
+
+### CI/CD
+
+- `.github/workflows/verify-build.yml` - Builds and tests all packages
+- `.github/workflows/lint.yml` - Runs format check on all packages
+- `.github/workflows/release.yml` - Publishes packages via changesets
+- Turbo caches builds and tests (only runs what changed)
+
+## Development Tips
+
+- The example catalog at `/examples/default` is used when running `pnpm run start:catalog`
+- SSR mode is required for AI Chat and MCP Server features
+- Use `DISABLE_EVENTCATALOG_CACHE=true` env var to disable caching during development
+- When making changes in this repository, check whether the same change or a compatible follow-up is needed in the editor repository at `eventcatalog/eventcatalog-editor`. If no editor change is needed, mention that explicitly in the final response.
+- Run `pnpm run format` before committing changes
+- Never verify the build, the developer will do this themselves
+- SDK test files may get modified during test runs - restore with `git restore packages/sdk/src/test/`
+
+## Plan Mode
 
-Run linting and formatting before submitting changes. Follow existing patterns when adding new code.
+- Make the plan extremely concise. Sacrifice grammar for the sake of concision.
+- At the end of each plan, give me a list of unresolved questions to answer, if any.
diff --git a/Dockerfile.server b/Dockerfile.server
deleted file mode 100644
index f4bab595d..000000000
--- a/Dockerfile.server
+++ /dev/null
@@ -1,47 +0,0 @@
-# This docker file is used for project development only.
-# If you are looking for your Docker File for SSR you can find one in our docs: https://www.eventcatalog.dev/docs/development/deployment/hosting-options
-
-# If you want to locally reproduce any SSR / Docker bugs, use this docker file 
-
-# FOR DEVELOPMENT ONLY, DO NOT USE THIS FOR PRODUCTION
-
-FROM node:20-slim AS runtime
-WORKDIR /app
-
-# Install pnpm
-RUN corepack enable && corepack prepare pnpm@latest --activate
-
-# Copy package files
-COPY package.json pnpm-lock.yaml ./
-
-# Copy the rest of the app
-COPY eventcatalog ./eventcatalog
-COPY examples/default ./examples/default
-COPY src ./src
-COPY scripts ./scripts
-COPY tsup.config.js ./tsup.config.js
-COPY . .   
-
-ENV PNPM_HOME=/usr/local/pnpm
-ENV PATH=$PNPM_HOME:$PATH
-
-RUN mkdir -p $PNPM_HOME \
-  && pnpm config set global-bin-dir $PNPM_HOME \
-  && pnpm add -g cross-env
-
-RUN pnpm install
-RUN pnpm run build:bin
-
-# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
-ENV NODE_OPTIONS=--max_old_space_size=4096
-
-ENV HOST=0.0.0.0
-ENV PORT=3000
-EXPOSE 3000
-
-RUN echo "HELLO"
-RUN pnpm run verify-build:catalog
-
-# Start the server
-# 
-CMD cd examples/default && node ../../dist/eventcatalog.js start
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 000000000..a545d8be7
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2022-2026 boyney123
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note: Source code within `packages/core/eventcatalog/src/enterprise/` is
+licensed under the EventCatalog Commercial License and is NOT covered by the
+MIT License above. See `packages/core/eventcatalog/src/enterprise/LICENSE`
+for the full terms.
diff --git a/LICENSE.md b/LICENSE.md
deleted file mode 100644
index 47c23fbe6..000000000
--- a/LICENSE.md
+++ /dev/null
@@ -1,30 +0,0 @@
-Source code in this repository is split into two parts:
-
-* Outside the `/src/enterprise` directory, source code in a given file is licensed under MIT (see below).
-* Inside the `/src/enterprise` directory, source code in a given file is licensed under the EventCatalog Plugin/Commercial License, unless otherwise noted.
-
----
-
-All code outside of the `eventcatalog/src/enterprise` directory is licensed under the MIT license which is below.
-
-MIT License
-
-Copyright (c) 2022-2025 boyney123
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
\ No newline at end of file
diff --git a/README.md b/README.md
index ee9dd5531..a33fa3263 100644
--- a/README.md
+++ b/README.md
@@ -1,157 +1,146 @@
 <div align="center">
 
-<h1>📖 EventCatalog</h1>
-<h3>The open source tool to help you discover and document your event-driven architectures</h3>
+<img src="./images/banner.png" alt="EventCatalog overview" width="800" />
 
-[![MIT License][license-badge]][license]
-[![PRs Welcome][prs-badge]][prs]
-<img src="https://img.shields.io/github/actions/workflow/status/event-catalog/eventcatalog/verify-build.yml"/>
-[![](https://dcbadge.limes.pink/api/server/https://discord.gg/3rjaZMmrAm?style=flat)](https://discord.gg/3rjaZMmrAm) [<img src="https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white" height="20px" />](https://www.linkedin.com/in/david-boyne/) [![blog](https://img.shields.io/badge/blog-EDA--Visuals-brightgreen)](https://eda-visuals.boyney.io/?utm_source=event-catalog-gihub) 
+## The open source documentation tool for software architectures.
 
+A documentation tool designed for software architecture not generic pages.
 
+Document systems, domains, services, messages and schemas. Document your architecture they way you build it.
 
+Customize your documentation to fit your workflow. Automate it, customize it, visualize it.
 
-<!-- [![Star on GitHub][github-star-badge]][github-star] -->
-<!-- <h3>Bring discoverability to your -->
-<!-- event-driven architectures</h3> -->
-<!-- <p>Discover, Explore and Document your Event Driven Architectures.</p> -->
+[![main](https://github.com/event-catalog/eventcatalog/actions/workflows/verify-build.yml/badge.svg)](https://github.com/event-catalog/eventcatalog/actions/workflows/verify-build.yml)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/event-catalog/eventcatalog/blob/main/LICENSE)
+[![npm version](https://badge.fury.io/js/@eventcatalog%2Fcore.svg)](https://badge.fury.io/js/@eventcatalog/core)
+[![All Contributors](https://img.shields.io/badge/all_contributors-69-orange.svg?style=flat-square)](#contributors-)
 
-<!-- [![MIT License][license-badge]][license] -->
-<!-- [![PRs Welcome][prs-badge]][prs] -->
-
-
-<!-- [![Watch on GitHub][github-watch-badge]][github-watch] -->
-<!-- [![Star on GitHub][github-star-badge]][github-star] -->
-
-<!-- <hr /> -->
-
-<!-- <img width="745" alt="Screenshot 2024-12-13 at 09 56 05" src="https://github.com/user-attachments/assets/f537ec1f-54ee-4de1-996c-c6b72191be39" /> -->
-<img width="745" alt="EventCatalog" src="./images/example.png" />
+**40,000+ catalogs created**
 
+</div>
 
+<br/>
 
+<p align="center">
+  <img src="./images/visualizer-demo.gif" alt="Architecture visualiser" width="800" />
+</p>
 
-<h4>Features: Documentation for Event Driven Architectures, Integration with any broker, Generator from your OpenAPI and AsyncAPI documents, Docs and Code, Markdown driven, Document Domains/Services/Messages/Schemas and more, Content versioning, Assign Owners, Schemas, OpenAPI, MDX Components and more...</h4>
+[Documentation](https://www.eventcatalog.dev/docs) | [Live Demo](https://demo.eventcatalog.dev) | [Discord](https://discord.gg/3rjaZMmrAm)
 
-<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-67-orange.svg?style=flat-square)](#contributors-)
-<!-- ALL-CONTRIBUTORS-BADGE:END -->
 
-[Read the Docs](https://www.eventcatalog.dev/docs/development/getting-started/introduction) | [View Demo](https://demo.eventcatalog.dev)
+<br/>
 
-</div>
+## Get started in seconds
 
-<hr/>
+```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog
+```
 
-# Core Features
+That's it. Open `http://localhost:3000` and start documenting your architecture.
 
-- 📃 Document domains, services and messages ([demo](https://demo.eventcatalog.dev/docs))
-- 📊 Visualise your architecture ([demo](https://demo.eventcatalog.dev/visualiser/domains/Orders))
-- ⭐ Supports any Schema format (e.g Avro, JSON) ([demo](https://demo.eventcatalog.dev/docs/events/OrderConfirmed/0.0.1))
-- 🗂️ Document any code examples (Any code snippet)
-- 💅 Custom MDX components ([read more](https://eventcatalog.dev/docs/development/components/using-components))
-- 🗄️ Version domains, services and messages
-- ⭐ Discoverability feature (search, filter and more) ([demo](https://demo.eventcatalog.dev/discover/events))
-- ⭐ Document teams and users ([demo](https://demo.eventcatalog.dev/docs/teams/full-stack))
-- 🤖 Automate your catalogs with [generators](https://www.eventcatalog.dev/docs/development/plugins/plugin-overview) (e.g generate your catalogs from your [AsyncAPI](https://www.eventcatalog.dev/docs/asyncapi)/[OpenAPI](https://www.eventcatalog.dev/docs/openapi) documents)
-- 👨🏼‍💻 Follows [Docs as code](https://www.writethedocs.org/guide/docs-as-code/) principles
-- ⭐ And much more...
+Looking for a guided walkthrough? Check out the [Getting Started](https://www.eventcatalog.dev/docs/development/getting-started/installation) guide.
 
+---
 
-# The problem
+## Core Features
 
-Event-driven architectures are becoming more popular, giving us the ability to write decoupled architectures and use messages as away to communicate between domains/teams.
+### Document your architecture
 
-When starting with event-driven architectures you may have a handful of services and messages. As this scales with your team and organization it becomes very hard to manage and govern this.
+Document domains, services and messages across your architecture.
 
-Over a period of time more events are added to our domain, requirements change, and our architecture scales.
+<p align="center">
+  <img src="./images/overview-demo.gif" alt="EventCatalog overview" width="800" />
+</p>
 
-As more domains, services or messages get added to our architecture they can be hard for teams to discover and explore.
+### AI-powered discovery
 
-Many teams ignore documentation and governance and end up in a [sea of complexity (watch the talk here)](https://www.youtube.com/watch?v=VLUvfIm9wnQ&t=1s) .
+Ask questions about your architecture and business in natural language. The built-in AI chat and MCP server let you and your tools query your catalog.
 
-**EventCatalog was built to help document your event-driven architectures and help your teams explore and understand events, schemas and much more.**
+<p align="center">
+  <img src="./images/ai-demo.gif" alt="AI-powered discovery" width="800" />
+</p>
 
-Read more on these blogposts and videos:
+### Schema explorer
 
-- [Introducing EventCatalog v2 (2024)](https://eventcatalog.dev/blog/eventcatalog-v2)
-- [Introducing EventCatalog v1 (2022)](https://www.boyney.io/blog/2022-01-11-introducing-eventcatalog)
-- [Event-Driven Architecture: Beyond the Schema Registry (blog)](https://www.boyney.io/blog/2021-12-05-documenting-events)
-- [Complexity is the Gotcha of Event-driven Architecture (VIDEO) by David Boyne](https://www.youtube.com/watch?v=VLUvfIm9wnQ&t=1s)
+Quickly find any schema across your catalog — OpenAPI, AsyncAPI, Protobuf, JSON Schema, Avro, and more. All in one searchable place.
 
-# This solution
+<p align="center">
+  <img src="./images/schema-explorer-demo.gif" alt="Schema explorer" width="800" />
+</p>
 
-Think of EventCatalog as a website generator that allows you to document your event architectures powered by markdown.
+### Schema fields
 
-EventCatalog is focused on discovery and documentation and allows you to:
+Filter and find any property on any field across your entire catalog. See how fields are used across services and messages.
 
-- Document Domains/Services/Messages/Schemas/Code Examples and more...
-- Visually shows relationships between upstream/downstream services using your Events
-- Allows you to version your documentation and supports changelogs
-- Add owners to domains,services and messages so your teams know who owns which parts of your domain
-- And much more...
+<p align="center">
+  <img src="./images/schema-fields-demo.gif" alt="Schema fields explorer" width="800" />
+</p>
 
-EventCatalog is technology agnostic, which means you can integrate your Catalog with any EDA technology of your choice and any schema formats.
+### Bring your own docs
 
-EventCatalog supports a [Plugin Architecture](https://github.com/event-catalog/generators) which lets you generate documentation from your systems including OpenAPI, AsyncAPI, Event Brokers and more.
+Attach architecture decision records, runbooks, and any custom documentation to your domains, services, and teams. Version them alongside your architecture.
 
-You can read more on [how it works on GitHub](https://github.com/event-catalog/eventcatalog)
+<p align="center">
+  <img src="./images/bring-your-own-docs.gif" alt="Bring your own docs" width="800" />
+</p>
 
-# Getting Started
+### Document business flows
 
-You should be able to get setup within minutes if you head over to our documentation to get started 👇
+Tell the end-to-end story of your business workflows. Reference the services and messages you already have to build a higher-level picture of how everything fits together.
 
-➡️ [Get Started](https://www.eventcatalog.dev/docs/development/getting-started/installation)
+<p align="center">
+  <img src="./images/flow-demo.gif" alt="Business flow documentation" width="800" />
+</p>
 
-Or run this command to build a new catalog
+### And much more...
 
-```
-npx @eventcatalog/create-eventcatalog@latest my-catalog
-```
+- **Version your resources** — Full semantic versioning for events, commands, services, and more
+- **15+ generators** — Auto-generate from AsyncAPI, OpenAPI, Kafka, Confluent, AWS EventBridge, and more
+- **Customizable** — Themes, custom MDX components, and configurable layouts
+- **Enterprise ready** — OAuth2, RBAC, schema governance, breaking change detection
 
-# Demo
+---
 
-Here is an example of a Retail system using domains, services and messages.
+## Demos
 
-[demo.eventcatalog.dev](https://demo.eventcatalog.dev)
+See EventCatalog powering real-world architectures:
 
-You can see the markdown files that generated the website in the GitHub repo under [examples](/examples).
+| | | |
+|---|---|---|
+| [**E-Commerce**](https://demo.eventcatalog.dev/) | [**Finance**](https://eventcatalog-examples-finance.vercel.app/) | [**Healthcare**](https://eventcatalog-examples-healthcare.vercel.app/) |
+| [**SaaS**](https://eventcatalog-examples-saas.vercel.app/) | | |
 
-# Enterprise support
+---
 
-Interested in collaborating with us? Our offerings include dedicated support, priority assistance, feature development, custom integrations, and more.
+## Packages
 
-Find more details on our [services page](https://eventcatalog.dev/services).
+| Package | Description |
+|---------|-------------|
+| [@eventcatalog/core](./packages/core) | Main catalog application (Astro + React) |
+| [@eventcatalog/sdk](./packages/sdk) | Node.js SDK for programmatic catalog management |
+| [@eventcatalog/create-eventcatalog](./packages/create-eventcatalog) | CLI scaffolding tool |
+| [@eventcatalog/visualiser](./packages/visualiser) | Standalone React visualiser component |
+| [@eventcatalog/dsl-playground](./packages/playground) | Browser-based DSL playground |
 
-# Looking for v1?
+---
 
-- Documentation: https://v1.eventcatalog.dev
-- Code: https://github.com/event-catalog/eventcatalog/tree/v1
+## Documentation
 
-_Still using v1 of EventCatalog? We recommnded upgrading to the latest version. [Read more in the migration guide](https://eventcatalog.dev/docs/development/guides/upgrading-from-version-1)._
+Visit the [official docs](https://www.eventcatalog.dev/docs/development/getting-started) to learn more.
 
+---
 
-# Contributing
+## Support
 
-If you have any questions, features or issues please raise any issue or pull requests you like. We will try my best to get back to you.
+Need help? Join the [EventCatalog Discord](https://discord.gg/3rjaZMmrAm).
 
-You can find the [contributing guidelines here](https://eventcatalog.dev/docs/contributing/overview).
+---
 
-## Running the project locally
+## Contributing
 
-1. Clone the repo
-1. Install required dependencies `pnpm install`
-1. Run the command `pnpm run start:catalog`
-    - This will start the catalog found in `/examples` repo, locally on your machine
+We welcome contributions! See the [contributing guidelines](https://eventcatalog.dev/docs/contributing/overview) to get started.
 
-[license-badge]: https://img.shields.io/github/license/event-catalog/eventcatalog.svg?color=yellow
-[license]: https://github.com/event-catalog/eventcatalog/blob/main/LICENSE
-[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
-[prs]: http://makeapullrequest.com
-[github-watch-badge]: https://img.shields.io/github/watchers/event-catalog/eventcatalog.svg?style=social
-[github-watch]: https://github.com/event-catalog/eventcatalog/watchers
-[github-star-badge]: https://img.shields.io/github/stars/event-catalog/eventcatalog.svg?style=social
-[github-star]: https://github.com/event-catalog/eventcatalog/stargazers
+---
 
 ## Contributors ✨
 
@@ -248,6 +237,15 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/jbarette-rossel"><img src="https://avatars.githubusercontent.com/u/162966566?v=4?s=100" width="100px;" alt="Jonathan Barette"/><br /><sub><b>Jonathan Barette</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=jbarette-rossel" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/mumundum"><img src="https://avatars.githubusercontent.com/u/196062898?v=4?s=100" width="100px;" alt="mumundum"/><br /><sub><b>mumundum</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=mumundum" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://www.argonus.tech"><img src="https://avatars.githubusercontent.com/u/9743549?v=4?s=100" width="100px;" alt="Piotr Rybarczyk"/><br /><sub><b>Piotr Rybarczyk</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3AArgonus" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ZakaryaCH"><img src="https://avatars.githubusercontent.com/u/45012800?v=4?s=100" width="100px;" alt="ZakaryaCH"/><br /><sub><b>ZakaryaCH</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3AZakaryaCH" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/jboeijenga"><img src="https://avatars.githubusercontent.com/u/1516438?v=4?s=100" width="100px;" alt="Jasper Boeijenga"/><br /><sub><b>Jasper Boeijenga</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=jboeijenga" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://kirkdesigns.co.uk"><img src="https://avatars.githubusercontent.com/u/200251?v=4?s=100" width="100px;" alt="Tom Kirkpatrick"/><br /><sub><b>Tom Kirkpatrick</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=mrfelton" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Machul84126"><img src="https://avatars.githubusercontent.com/u/128227109?v=4?s=100" width="100px;" alt="Machul"/><br /><sub><b>Machul</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3AMachul84126" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ugostack"><img src="https://avatars.githubusercontent.com/u/81093728?v=4?s=100" width="100px;" alt="ugostack"/><br /><sub><b>ugostack</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=ugostack" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/jdebarochez"><img src="https://avatars.githubusercontent.com/u/3436890?v=4?s=100" width="100px;" alt="Jean de Barochez"/><br /><sub><b>Jean de Barochez</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=jdebarochez" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/cog06"><img src="https://avatars.githubusercontent.com/u/44521955?v=4?s=100" width="100px;" alt="cog06"/><br /><sub><b>cog06</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3Acog06" title="Bug reports">🐛</a></td>
     </tr>
   </tbody>
 </table>
@@ -259,6 +257,18 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 
 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
 
-# License
+---
+
+<div align="center">
+
+**[Website](https://eventcatalog.dev)** | **[Docs](https://www.eventcatalog.dev/docs)** | **[Discord](https://discord.gg/3rjaZMmrAm)** | **[Twitter](https://twitter.com/eventcatalog)**
+
+<sub>Made with ❤️ by the EventCatalog community</sub>
+
+</div>
+
+---
+
+## License
 
 MIT.
diff --git a/default-files-for-collections/changelogs.md b/default-files-for-collections/changelogs.md
deleted file mode 100644
index c97be0077..000000000
--- a/default-files-for-collections/changelogs.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-id: empty
----
-
-<!-- Do not delete this file, required for EC, you an ignore this file -->
diff --git a/default-files-for-collections/channels.md b/default-files-for-collections/channels.md
deleted file mode 100644
index 089fe4913..000000000
--- a/default-files-for-collections/channels.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-id: empty
-name: empty
-version: 0.0.1
-hidden: true
----
-
-<!-- Do not delete this file, required for EC, you an ignore this file -->
diff --git a/default-files-for-collections/commands.md b/default-files-for-collections/commands.md
deleted file mode 100644
index 089fe4913..000000000
--- a/default-files-for-collections/commands.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-id: empty
-name: empty
-version: 0.0.1
-hidden: true
----
-
-<!-- Do not delete this file, required for EC, you an ignore this file -->
diff --git a/default-files-for-collections/domains.md b/default-files-for-collections/domains.md
deleted file mode 100644
index 089fe4913..000000000
--- a/default-files-for-collections/domains.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-id: empty
-name: empty
-version: 0.0.1
-hidden: true
----
-
-<!-- Do not delete this file, required for EC, you an ignore this file -->
diff --git a/default-files-for-collections/events.md b/default-files-for-collections/events.md
deleted file mode 100644
index 089fe4913..000000000
--- a/default-files-for-collections/events.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-id: empty
-name: empty
-version: 0.0.1
-hidden: true
----
-
-<!-- Do not delete this file, required for EC, you an ignore this file -->
diff --git a/default-files-for-collections/flows.md b/default-files-for-collections/flows.md
deleted file mode 100644
index effd29cc4..000000000
--- a/default-files-for-collections/flows.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-id: empty
-steps:
-    - id: "empty"
-      title: "empty"
-name: empty
-version: 0.0.1
-hidden: true
----
-
-<!-- Do not delete this file, required for EC, you an ignore this file -->
diff --git a/default-files-for-collections/queries.md b/default-files-for-collections/queries.md
deleted file mode 100644
index 089fe4913..000000000
--- a/default-files-for-collections/queries.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-id: empty
-name: empty
-version: 0.0.1
-hidden: true
----
-
-<!-- Do not delete this file, required for EC, you an ignore this file -->
diff --git a/default-files-for-collections/services.md b/default-files-for-collections/services.md
deleted file mode 100644
index 089fe4913..000000000
--- a/default-files-for-collections/services.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-id: empty
-name: empty
-version: 0.0.1
-hidden: true
----
-
-<!-- Do not delete this file, required for EC, you an ignore this file -->
diff --git a/default-files-for-collections/ubiquitousLanguages.md b/default-files-for-collections/ubiquitousLanguages.md
deleted file mode 100644
index aaba1d03b..000000000
--- a/default-files-for-collections/ubiquitousLanguages.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-id: ubiquitous-language
-name: Ubiquitous Language
-summary: A shared language used by all team members to communicate about the system.
-description: A shared language used by all team members to communicate about the system.
----
-<!-- Do not delete this file, required for EC, you an ignore this file -->
\ No newline at end of file
diff --git a/eventcatalog/.gitignore b/eventcatalog/.gitignore
deleted file mode 100644
index abaae25a6..000000000
--- a/eventcatalog/.gitignore
+++ /dev/null
@@ -1,25 +0,0 @@
-# build output
-dist/
-
-# generated types
-.astro/
-
-# dependencies
-node_modules/
-
-# EventCatalog files
-src/content/*
-!src/content/config.ts
-public/generated/*
-src/catalog-files/*
-src/custom-defined-components/*
-src/snippets/*
-
-eventcatalog.config.js
-eventcatalog.styles.css
-
-src/generated-ai/*
-
-src/pages/api/server/*
-src/pages/api/chat.ts
-src/pages/api/[...auth].ts
diff --git a/eventcatalog/astro.config.mjs b/eventcatalog/astro.config.mjs
deleted file mode 100644
index 9035b1045..000000000
--- a/eventcatalog/astro.config.mjs
+++ /dev/null
@@ -1,125 +0,0 @@
-
-import { defineConfig } from 'astro/config';
-import tailwind from '@astrojs/tailwind';
-import mdx from '@astrojs/mdx';
-import react from '@astrojs/react';
-import { searchForWorkspaceRoot } from 'vite';
-import { mermaid } from "./src/remark-plugins/mermaid"
-import { plantuml } from "./src/remark-plugins/plantuml"
-import { join } from 'node:path';
-import remarkDirective from 'remark-directive';
-import { remarkDirectives } from "./src/remark-plugins/directives"
-import node from '@astrojs/node';
-import remarkComment from 'remark-comment'
-import rehypeSlug from 'rehype-slug';
-import rehypeAutolinkHeadings from 'rehype-autolink-headings';
-
-import rehypeExpressiveCode from 'rehype-expressive-code'
-
-/** @type {import('bin/eventcatalog.config').Config} */
-import config from './eventcatalog.config';
-import expressiveCode from 'astro-expressive-code';
-import ecstudioWatcher from './integrations/ecstudio-watcher.mjs';
-
-const projectDirectory = process.env.PROJECT_DIR || process.cwd();
-const base = config.base || '/';
-const host = config.host || false;
-const compress = config.compress ?? false;
-
-const expressiveCodeConfig = {
-  themes: ['andromeeda'],
-  defaultProps: {
-    wrap: true,
-  },
-};
-
-// https://astro.build/config
-export default defineConfig({
-  base,
-  server: { port: config.port || 3000, host: host },
-
-  output: config.output || 'static',
-
-  adapter: config.output === 'server' ? node({
-    mode: 'standalone'
-  }) : undefined,
-
-  outDir: config.outDir ? join(projectDirectory, config.outDir) : join(projectDirectory, 'dist'),
-
-  // https://docs.astro.build/en/reference/configuration-reference/#site
-  site: config.homepageLink || 'https://eventcatalog.dev/',
-
-  // https://docs.astro.build/en/reference/configuration-reference/#trailingslash
-  trailingSlash: config.trailingSlash === true ? "always" : "ignore",
-
-  experimental: {
-    contentIntellisense: true,
-  },
-
-
-  // just turn this off for all users (for now...)
-  devToolbar: { enabled: false },
-  integrations: [
-    react(),
-    tailwind(),
-    expressiveCode({
-      ...expressiveCodeConfig,
-    }),
-    mdx({
-      // https://docs.astro.build/en/guides/integrations-guide/mdx/#optimize
-      optimize: config.mdxOptimize || false,
-      remarkPlugins: [remarkDirective, remarkDirectives, remarkComment, mermaid, plantuml],
-      rehypePlugins: [
-        [rehypeExpressiveCode, {
-            ...expressiveCodeConfig,
-        }],
-        rehypeSlug,
-        [
-          rehypeAutolinkHeadings,
-          {
-            behavior: 'append',
-            properties: { className: ['anchor-link'] },
-          },
-        ],
-      ],
-      gfm: true,
-    }),
-    config.output !== 'server' && compress && (await import("astro-compress")).default({
-      Logger: 0,
-      CSS: false,
-    }),
-    ecstudioWatcher(),
-  ].filter(Boolean),
-  vite: {
-    define: {
-      /**
-       * Trailing slash is exposed as global variable here principally for `@utils/url-builder`.
-       * The utility is used by client components and because of that it can't direct import 
-       * the eventcatalog.config, as the config use packages that only run in node environments,
-       * such as `node:path`.
-       */
-      '__EC_TRAILING_SLASH__': config.trailingSlash || false,
-    },
-    server: {
-      fs: {
-        allow: [
-          '..', 
-          './node_modules/@fontsource',
-          searchForWorkspaceRoot(process.cwd()),
-        ]
-      },
-      ...(config.server?.allowedHosts ? { allowedHosts: config.server?.allowedHosts } : {}),
-    },
-    worker: {
-      format: 'es',
-    },
-    build: {
-      commonjsOptions: {
-        transformMixedEsModules: true,
-      }
-    },
-    ssr: {
-      external: ['eventcatalog.auth.js'],
-    }
-  }
-});
diff --git a/eventcatalog/public/favicon.ico b/eventcatalog/public/favicon.ico
deleted file mode 100644
index 6b504373e..000000000
Binary files a/eventcatalog/public/favicon.ico and /dev/null differ
diff --git a/eventcatalog/public/icons/graphql.svg b/eventcatalog/public/icons/graphql.svg
deleted file mode 100644
index 54cbb5cd5..000000000
--- a/eventcatalog/public/icons/graphql.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg viewBox="-16 0 288 288" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid" fill="#000000"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"> <g fill-rule="evenodd"> <path d="M152.575995,32.9634453 L211.722058,67.1124427 C213.387503,65.348329 215.332859,63.7907081 217.539734,62.5088708 C229.806457,55.4573413 245.452038,59.6441869 252.577021,71.9109101 C259.62855,84.1776333 255.441705,99.8232143 243.174982,106.948197 C240.984974,108.207124 238.684929,109.10784 236.343812,109.66832 L236.343812,177.99302 C238.659582,178.554683 240.934429,179.449686 243.101528,180.695443 C255.441705,187.820426 259.62855,203.466007 252.503568,215.73273 C245.452038,227.999453 229.733004,232.186299 217.46628,225.13477 C215.024105,223.730884 212.902189,221.983449 211.125456,219.988103 L152.340162,253.928803 C153.180519,256.46808 153.635248,259.18431 153.635248,262.008393 C153.635248,276.111452 142.176512,287.64364 128,287.64364 C113.823488,287.64364 102.364752,276.184905 102.364752,262.008393 C102.364752,259.488481 102.726802,257.054441 103.40181,254.755362 L44.2714887,220.615454 C42.6238257,222.34493 40.705394,223.873378 38.5337196,225.13477 C26.193543,232.186299 10.547962,227.999453 3.49643248,215.73273 C-3.55509701,203.466007 0.631748621,187.820426 12.8984718,180.695443 C15.0673397,179.448669 17.3418356,178.553222 19.6561876,177.991646 L19.6561876,109.66832 C17.3150714,109.10784 15.0150257,108.207124 12.8250184,106.948197 C0.558295189,99.8966677 -3.62855044,84.1776333 3.42297904,71.9109101 C10.4745085,59.6441869 26.193543,55.4573413 38.4602662,62.5088708 C40.6551374,63.7837361 42.5913269,65.3313931 44.2507413,67.0836756 L103.41276,32.9254664 C102.730718,30.6154532 102.364752,28.1687503 102.364752,25.6352478 C102.364752,11.4587354 113.823488,0 128,0 C142.176512,0 153.635248,11.4587354 153.635248,25.6352478 C153.635248,28.1826393 153.265258,30.6422768 152.575995,32.9634453 Z M146.413638,43.4848713 L205.700555,77.715193 C203.867899,84.1516888 204.540515,91.2885638 208.137694,97.5461579 C211.746601,103.824151 217.625783,107.985785 224.150543,109.607654 L224.150543,178.017842 C223.818032,178.099463 223.48718,178.187674 223.158201,178.282419 L145.72529,44.1686182 C145.959017,43.9450469 146.18851,43.7170876 146.413638,43.4848713 Z M110.29093,44.1841203 L32.8593279,178.295656 C32.524559,178.19844 32.1878611,178.108015 31.8494573,178.024438 L31.8494573,109.607654 C38.3742168,107.985785 44.2533992,103.824151 47.8623055,97.5461579 C51.466599,91.276189 52.1347497,84.1234583 50.2885426,77.6770157 L109.558747,43.4563434 C109.797913,43.7038019 110.042027,43.9464469 110.29093,44.1841203 Z M135.162749,50.259763 L212.576817,184.340928 C210.844241,185.99279 209.317376,187.91755 208.064241,190.097482 C206.818484,192.264581 205.923481,194.539429 205.361818,196.855198 L50.6395564,196.855198 C50.0779798,194.540846 49.1825333,192.26635 47.9357589,190.097482 C46.6776713,187.931497 45.1539248,186.017428 43.4300297,184.372667 L120.858821,50.2659993 C123.124941,50.9200822 125.520915,51.2704957 128,51.2704957 C130.486952,51.2704957 132.890265,50.9178547 135.162749,50.259763 Z M146.958084,244.737995 L205.860107,210.729899 C205.683398,210.174924 205.525483,209.614096 205.38664,209.048468 L50.6067643,209.048468 C50.5246888,209.380792 50.4360084,209.711472 50.3407792,210.040295 L109.531782,244.215239 C114.192298,239.378545 120.739739,236.373145 128,236.373145 C135.518379,236.373145 142.272352,239.596041 146.958084,244.737995 Z" fill="#E535AB"> </path> </g> </g></svg>
\ No newline at end of file
diff --git a/eventcatalog/public/logo.png b/eventcatalog/public/logo.png
deleted file mode 100644
index d65c29da2..000000000
Binary files a/eventcatalog/public/logo.png and /dev/null differ
diff --git a/eventcatalog/public/logo.svg b/eventcatalog/public/logo.svg
deleted file mode 100644
index a3b326372..000000000
--- a/eventcatalog/public/logo.svg
+++ /dev/null
@@ -1,14 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 300 200">
-  <!-- Background shape -->
-  <rect x="50" y="50" width="200" height="100" rx="20" fill="#4a86e8" />
-  
-  <!-- Flow waves -->
-  <path d="M80 90 Q100 70, 120 90 Q140 110, 160 90 Q180 70, 200 90 Q220 110, 240 90" 
-        fill="none" stroke="#ffffff" stroke-width="8" stroke-linecap="round" />
-  
-  <!-- Shopping cart icon -->
-  <circle cx="220" cy="110" r="10" fill="#ffffff" />
-  <circle cx="180" cy="110" r="10" fill="#ffffff" />
-  <path d="M160 80 L170 110 L230 110 L240 80 Z" fill="none" stroke="#ffffff" stroke-width="3" />
-  <path d="M170 80 L245 80" fill="none" stroke="#ffffff" stroke-width="3" />
-</svg>
\ No newline at end of file
diff --git a/eventcatalog/public/logo_old.png b/eventcatalog/public/logo_old.png
deleted file mode 100644
index 9df4b958f..000000000
Binary files a/eventcatalog/public/logo_old.png and /dev/null differ
diff --git a/eventcatalog/src/__tests__/api/message-schemas-api.spec.ts b/eventcatalog/src/__tests__/api/message-schemas-api.spec.ts
deleted file mode 100644
index d1ea07f30..000000000
--- a/eventcatalog/src/__tests__/api/message-schemas-api.spec.ts
+++ /dev/null
@@ -1,202 +0,0 @@
-import type { ContentCollectionKey } from 'astro:content';
-import { expect, describe, it, vi, beforeEach } from 'vitest';
-import { getStaticPaths, GET } from '../../pages/api/schemas/[collection]/[id]/[version]/index.ts';
-import path from 'path';
-
-const __dirname = path.dirname(new URL(import.meta.url).pathname);
-
-let mockEvents: any[] = [];
-let mockCommands: any[] = [];
-let mockQueries: any[] = [];
-
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    getCollection: (key: ContentCollectionKey) => {
-      switch (key) {
-        case 'events':
-          return Promise.resolve(mockEvents);
-        case 'commands':
-          return Promise.resolve(mockCommands);
-        case 'queries':
-          return Promise.resolve(mockQueries);
-        default:
-          return Promise.resolve([]);
-      }
-    },
-  };
-});
-
-describe('api/schemas/[collection]/[id]/[version]/index.ts', () => {
-  beforeEach(() => {
-    mockEvents = [
-      {
-        collection: 'events',
-        filePath: path.join(__dirname, 'schemas', 'test-schema.json'),
-        data: {
-          name: 'Order Placed',
-          id: 'OrderPlaced',
-          version: '1.0.0',
-          summary: 'Order Placed summary',
-          schemaPath: 'test-schema.json',
-        },
-      },
-    ];
-    mockCommands = [
-      {
-        collection: 'commands',
-        filePath: path.join(__dirname, 'schemas', 'test-schema.avro'),
-        data: {
-          name: 'Create Order',
-          id: 'CreateOrder',
-          version: '1.0.0',
-          summary: 'Create Order summary',
-          schemaPath: 'test-schema.avro',
-        },
-      },
-    ];
-    mockQueries = [
-      {
-        collection: 'queries',
-        filePath: path.join(__dirname, 'schemas', 'test-schema.avro'),
-        data: {
-          name: 'Get Order',
-          id: 'GetOrder',
-          version: '1.0.0',
-          summary: 'Get Order summary',
-          schemaPath: 'test-schema.avro',
-        },
-      },
-    ];
-  });
-
-  describe('getStaticPaths', () => {
-    it('returns static paths for messages (events, commands, queries) that have a schema including latest paths', async () => {
-      const staticPaths = await getStaticPaths();
-      // 3 versioned paths + 3 latest paths
-      expect(staticPaths).toHaveLength(6);
-
-      const versionedPaths = staticPaths.filter((p) => p.params.version !== 'latest');
-      const latestPaths = staticPaths.filter((p) => p.params.version === 'latest');
-
-      // Check versioned paths
-      expect(versionedPaths.map((path) => path.params.collection)).toEqual(['events', 'commands', 'queries']);
-      expect(versionedPaths.map((path) => path.params.id)).toEqual(['OrderPlaced', 'CreateOrder', 'GetOrder']);
-      expect(versionedPaths.map((path) => path.params.version)).toEqual(['1.0.0', '1.0.0', '1.0.0']);
-
-      // Check latest paths
-      expect(latestPaths.map((path) => path.params.collection)).toEqual(['events', 'commands', 'queries']);
-      expect(latestPaths.map((path) => path.params.id)).toEqual(['OrderPlaced', 'CreateOrder', 'GetOrder']);
-      expect(latestPaths.map((path) => path.params.version)).toEqual(['latest', 'latest', 'latest']);
-
-      // Check all the props
-      expect(versionedPaths.map((path) => path.props.pathToSchema)).toEqual([
-        path.join(__dirname, 'schemas', 'test-schema.json'),
-        path.join(__dirname, 'schemas', 'test-schema.avro'),
-        path.join(__dirname, 'schemas', 'test-schema.avro'),
-      ]);
-      expect(versionedPaths.map((path) => path.props.extension)).toEqual(['json', 'avro', 'avro']);
-    });
-
-    it('returns the latest version schema when multiple versions exist for the same message', async () => {
-      mockEvents = [
-        {
-          collection: 'events',
-          filePath: path.join(__dirname, 'schemas', 'test-schema.json'),
-          data: {
-            name: 'Order Placed',
-            id: 'OrderPlaced',
-            version: '1.0.0',
-            summary: 'Order Placed summary v1',
-            schemaPath: 'test-schema.json',
-          },
-        },
-        {
-          collection: 'events',
-          filePath: path.join(__dirname, 'schemas', 'test-schema.avro'),
-          data: {
-            name: 'Order Placed',
-            id: 'OrderPlaced',
-            version: '2.0.0',
-            summary: 'Order Placed summary v2',
-            schemaPath: 'test-schema.avro',
-          },
-        },
-      ];
-      mockCommands = [];
-      mockQueries = [];
-
-      const staticPaths = await getStaticPaths();
-      // 2 versioned paths + 1 latest path
-      expect(staticPaths).toHaveLength(3);
-
-      const latestPath = staticPaths.find((p) => p.params.version === 'latest');
-      expect(latestPath).toBeDefined();
-      expect(latestPath?.params.id).toEqual('OrderPlaced');
-      // Latest should point to v2.0.0's schema (test-schema.avro)
-      expect(latestPath?.props.pathToSchema).toEqual(path.join(__dirname, 'schemas', 'test-schema.avro'));
-      expect(latestPath?.props.extension).toEqual('avro');
-    });
-
-    it('handles non-semver versions and returns the latest based on string comparison', async () => {
-      mockEvents = [
-        {
-          collection: 'events',
-          filePath: path.join(__dirname, 'schemas', 'test-schema.json'),
-          data: {
-            name: 'Order Placed',
-            id: 'OrderPlaced',
-            version: 'draft',
-            summary: 'Order Placed draft',
-            schemaPath: 'test-schema.json',
-          },
-        },
-        {
-          collection: 'events',
-          filePath: path.join(__dirname, 'schemas', 'test-schema.avro'),
-          data: {
-            name: 'Order Placed',
-            id: 'OrderPlaced',
-            version: 'v2',
-            summary: 'Order Placed v2',
-            schemaPath: 'test-schema.avro',
-          },
-        },
-      ];
-      mockCommands = [];
-      mockQueries = [];
-
-      const staticPaths = await getStaticPaths();
-      // 2 versioned paths + 1 latest path
-      expect(staticPaths).toHaveLength(3);
-
-      const latestPath = staticPaths.find((p) => p.params.version === 'latest');
-      expect(latestPath).toBeDefined();
-      // "v2" > "draft" in string comparison
-      expect(latestPath?.props.pathToSchema).toEqual(path.join(__dirname, 'schemas', 'test-schema.avro'));
-    });
-  });
-
-  describe('GET', () => {
-    it('returns the given schema when EventCatalog Scale is enabled', async () => {
-      process.env.EVENTCATALOG_SCALE = 'true';
-      const response = await GET({
-        request: new Request('http://localhost:4321/api/schemas/events/OrderPlaced/1.0.0'),
-        props: { schema: 'test-schema.json' },
-      } as any);
-      expect(response.status).toBe(200);
-      expect(await response.text()).toEqual('test-schema.json');
-    });
-    it('returns an error when EventCatalog Scale is disabled', async () => {
-      process.env.EVENTCATALOG_SCALE = 'false';
-      const response = await GET({
-        request: new Request('http://localhost:4321/api/schemas/events/OrderPlaced/1.0.0'),
-        props: { schema: 'test-schema.json' },
-      } as any);
-      expect(response.status).toBe(501);
-      expect(await response.text()).toEqual(
-        '{"error":"feature_not_available_on_server","message":"Schema API is not enabled for this deployment and supported in EventCatalog Scale."}'
-      );
-    });
-  });
-});
diff --git a/eventcatalog/src/__tests__/api/schemas.txt.spec.ts b/eventcatalog/src/__tests__/api/schemas.txt.spec.ts
deleted file mode 100644
index ba73d7bf8..000000000
--- a/eventcatalog/src/__tests__/api/schemas.txt.spec.ts
+++ /dev/null
@@ -1,107 +0,0 @@
-import type { ContentCollectionKey } from 'astro:content';
-import { expect, describe, it, vi } from 'vitest';
-import { GET } from '../../pages/docs/llm/schemas.txt.ts';
-
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    getCollection: (key: ContentCollectionKey) => {
-      switch (key) {
-        case 'events':
-          return Promise.resolve([
-            {
-              data: {
-                name: 'Order Placed',
-                id: 'OrderPlaced',
-                version: '1.0.0',
-                summary: 'Order Placed summary',
-                schemaPath: 'schema.json',
-              },
-            },
-            // No schema, does not return
-            { data: { name: 'Order Confirmed', id: 'OrderConfirmed', version: '1.0.0', summary: 'Order Confirmed summary' } },
-          ]);
-        case 'commands':
-          return Promise.resolve([
-            {
-              data: {
-                name: 'Create Order',
-                id: 'CreateOrder',
-                version: '1.0.0',
-                summary: 'Create Order summary',
-                schemaPath: 'schema.json',
-              },
-            },
-          ]);
-        case 'queries':
-          return Promise.resolve([
-            {
-              data: {
-                name: 'Get Order',
-                id: 'GetOrder',
-                version: '1.0.0',
-                summary: 'Get Order summary',
-                schemaPath: 'schema.json',
-              },
-            },
-          ]);
-        case 'services':
-          return Promise.resolve([
-            {
-              data: {
-                name: 'Order Service',
-                id: 'OrderService',
-                version: '1.0.0',
-                summary: 'Order Service summary',
-                specifications: [
-                  { type: 'openapi', path: 'schema.json' },
-                  { type: 'asyncapi', path: 'schema.asyncapi.json' },
-                  { type: 'graphql', path: 'schema.graphql' },
-                ],
-              },
-            },
-            // No schema, does not return
-            {
-              data: { name: 'Inventory Service', id: 'InventoryService', version: '1.0.0', summary: 'Inventory Service summary' },
-            },
-          ]);
-        default:
-          return Promise.resolve([]);
-      }
-    },
-  };
-});
-
-describe('api/schemas.txt', () => {
-  it('returns a list of schemas for events, commands, queries, and services when EventCatalog Scale is enabled', async () => {
-    process.env.EVENTCATALOG_SCALE = 'true';
-    const response = await GET({ request: new Request('http://localhost:4321/api/schemas.txt') } as any);
-    expect(response.status).toBe(200);
-
-    const responseBody = await response.text();
-    expect(responseBody).toEqual(`# FlowMart EventCatalog Schemas
-List of schemas for events, commands, queries, and services in EventCatalog.
-
-## Events
-- [Order Placed - OrderPlaced - 1.0.0](http://localhost:4321/api/schemas/events/OrderPlaced/1.0.0)} - Order Placed summary
-
-## Commands
-- [Create Order - CreateOrder - 1.0.0](http://localhost:4321/api/schemas/commands/CreateOrder/1.0.0)} - Create Order summary
-
-## Queries
-- [Get Order - GetOrder - 1.0.0](http://localhost:4321/api/schemas/queries/GetOrder/1.0.0)} - Get Order summary
-
-## Services
-- [OrderService - 1.0.0 - openapi specification](http://localhost:4321/api/schemas/services/OrderService/1.0.0/openapi) - Specification for Order Service summary
-- [OrderService - 1.0.0 - asyncapi specification](http://localhost:4321/api/schemas/services/OrderService/1.0.0/asyncapi) - Specification for Order Service summary
-- [OrderService - 1.0.0 - graphql specification](http://localhost:4321/api/schemas/services/OrderService/1.0.0/graphql) - Specification for Order Service summary`);
-  });
-  it('returns an error when EventCatalog Scale is disabled', async () => {
-    process.env.EVENTCATALOG_SCALE = 'false';
-    const response = await GET({ request: new Request('http://localhost:4321/api/schemas.txt') } as any);
-    expect(response.status).toBe(501);
-    expect(await response.text()).toEqual(
-      '{"error":"feature_not_available_on_server","message":"Schema API is not enabled for this deployment and supported in EventCatalog Scale."}'
-    );
-  });
-});
diff --git a/eventcatalog/src/__tests__/api/services-schemas-api.spec.ts b/eventcatalog/src/__tests__/api/services-schemas-api.spec.ts
deleted file mode 100644
index 7d0c48d96..000000000
--- a/eventcatalog/src/__tests__/api/services-schemas-api.spec.ts
+++ /dev/null
@@ -1,92 +0,0 @@
-import type { ContentCollectionKey } from 'astro:content';
-import { expect, describe, it, vi } from 'vitest';
-import { getStaticPaths, GET } from '../../pages/api/schemas/services/[id]/[version]/[specification]/index.ts';
-import path from 'path';
-import fs from 'node:fs';
-
-const __dirname = path.dirname(new URL(import.meta.url).pathname);
-
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    getCollection: (key: ContentCollectionKey) => {
-      switch (key) {
-        case 'services':
-          return Promise.resolve([
-            {
-              collection: 'services',
-              filePath: path.join(__dirname, 'schemas', 'test-openapi.yml'),
-              data: {
-                name: 'Order Service',
-                id: 'OrderService',
-                version: '1.0.0',
-                summary: 'Order Service summary',
-                specifications: [
-                  { type: 'openapi', path: 'test-openapi.yml' },
-                  { type: 'asyncapi', path: 'test-asyncapi.yml' },
-                ],
-              },
-            },
-            {
-              collection: 'services',
-              filePath: path.join(__dirname, 'schemas', 'test-openapi.yml'),
-              data: {
-                name: 'Order Service',
-                id: 'OrderService',
-                version: '2.0.0',
-                summary: 'Order Service summary',
-                specifications: [{ type: 'openapi', path: 'test-openapi.yml' }],
-              },
-            },
-          ]);
-        default:
-          return Promise.resolve([]);
-      }
-    },
-  };
-});
-
-describe('api/schemas/services/[id]/[version]/[specification]/index.ts', () => {
-  describe('getStaticPaths', () => {
-    it('returns static paths for services that have a schema', async () => {
-      const staticPaths = await getStaticPaths();
-      expect(staticPaths).toHaveLength(3);
-
-      // Check all the params
-      expect(staticPaths.map((path) => path.params.collection)).toEqual(['services', 'services', 'services']);
-      expect(staticPaths.map((path) => path.params.id)).toEqual(['OrderService', 'OrderService', 'OrderService']);
-      expect(staticPaths.map((path) => path.params.version)).toEqual(['1.0.0', '1.0.0', '2.0.0']);
-      expect(staticPaths.map((path) => path.params.specification)).toEqual(['openapi', 'asyncapi', 'openapi']);
-
-      // Check all the props
-      expect(staticPaths.map((path) => path.props.schema)).toEqual([
-        fs.readFileSync(path.join(__dirname, 'schemas', 'test-openapi.yml'), 'utf8'),
-        fs.readFileSync(path.join(__dirname, 'schemas', 'test-asyncapi.yml'), 'utf8'),
-        fs.readFileSync(path.join(__dirname, 'schemas', 'test-openapi.yml'), 'utf8'),
-      ]);
-    });
-  });
-
-  describe('GET', () => {
-    it('returns the given schema when EventCatalog Scale is enabled', async () => {
-      process.env.EVENTCATALOG_SCALE = 'true';
-      const response = await GET({
-        request: new Request('http://localhost:4321/api/schemas/services/OrderService/1.0.0/openapi'),
-        props: { schema: fs.readFileSync(path.join(__dirname, 'schemas', 'test-openapi.yml'), 'utf8') },
-      } as any);
-      expect(response.status).toBe(200);
-      expect(await response.text()).toEqual(fs.readFileSync(path.join(__dirname, 'schemas', 'test-openapi.yml'), 'utf8'));
-    });
-    it('returns an error when EventCatalog Scale is disabled', async () => {
-      process.env.EVENTCATALOG_SCALE = 'false';
-      const response = await GET({
-        request: new Request('http://localhost:4321/api/schemas/services/OrderService/1.0.0/openapi'),
-        props: { schema: fs.readFileSync(path.join(__dirname, 'schemas', 'test-openapi.yml'), 'utf8') },
-      } as any);
-      expect(response.status).toBe(501);
-      expect(await response.text()).toEqual(
-        '{"error":"feature_not_available_on_server","message":"Schema API is not enabled for this deployment and supported in EventCatalog Scale."}'
-      );
-    });
-  });
-});
diff --git a/eventcatalog/src/components/CopyAsMarkdown.tsx b/eventcatalog/src/components/CopyAsMarkdown.tsx
deleted file mode 100644
index 0360c3bf4..000000000
--- a/eventcatalog/src/components/CopyAsMarkdown.tsx
+++ /dev/null
@@ -1,308 +0,0 @@
-import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
-import { Copy, FileText, MessageCircleQuestion, ChevronDownIcon, ExternalLink, PenSquareIcon } from 'lucide-react';
-import React, { useState, isValidElement } from 'react';
-import type { Schema } from '@utils/collections/schemas';
-import { buildUrl, toMarkdownUrl } from '@utils/url-builder';
-
-// Type allows either a component type (like Lucide icon) or a pre-rendered element (like <img>)
-type IconInput = React.ElementType | React.ReactElement;
-
-// Helper component for menu items
-const MenuItemContent = ({
-  icon: iconProp,
-  title,
-  description,
-  external = false,
-}: {
-  icon: IconInput;
-  title: string;
-  description: string;
-  external?: boolean;
-}) => {
-  let iconElement: React.ReactNode;
-
-  if (isValidElement(iconProp)) {
-    // It's already a React element (e.g., <img>), render it directly
-    iconElement = iconProp;
-  } else {
-    // It must be an ElementType (component constructor like Lucide icon)
-    const IconComponent = iconProp as React.ElementType;
-    iconElement = <IconComponent className="w-5 h-5 text-gray-500" />;
-  }
-
-  return (
-    <div className="flex items-center gap-3 px-3 py-2 text-sm">
-      <div className="p-1 border border-gray-200 rounded">{iconElement}</div>
-      <div className="flex-1">
-        <div className="font-medium text-gray-800">{title}</div>
-        <div className="text-xs text-gray-500">{description}</div>
-      </div>
-      {external && <ExternalLink className="w-4 h-4 text-gray-400" />}
-    </div>
-  );
-};
-
-export function CopyPageMenu({
-  schemas,
-  chatQuery,
-  chatEnabled = false,
-  editUrl,
-  markdownDownloadEnabled = false,
-}: {
-  schemas: Schema[];
-  chatQuery?: string;
-  chatEnabled: boolean;
-  editUrl: string;
-  markdownDownloadEnabled: boolean;
-}) {
-  // Define available actions
-  const availableActions = {
-    copyMarkdown: markdownDownloadEnabled,
-    editPage: !!editUrl,
-    copySchemas: schemas.length > 0,
-    viewMarkdown: markdownDownloadEnabled,
-    chat: chatEnabled,
-  };
-
-  // Check if any actions are available
-  const hasAnyActions = Object.values(availableActions).some(Boolean);
-
-  // If no actions are available, return null
-  if (!hasAnyActions) {
-    return null;
-  }
-
-  // get the url of the current page
-  const url = window.location.href;
-  const markdownUrl = toMarkdownUrl(url);
-
-  // Determine the default action based on what's available
-  const getDefaultAction = () => {
-    if (availableActions.copyMarkdown) {
-      return {
-        type: 'copyMarkdown',
-        text: 'Copy page',
-        icon: Copy,
-      };
-    }
-    if (availableActions.editPage) {
-      return {
-        type: 'editPage',
-        text: 'Edit page',
-        icon: PenSquareIcon,
-      };
-    }
-    if (availableActions.copySchemas) {
-      return {
-        type: 'copySchemas',
-        text: 'Copy schema',
-        icon: FileText,
-      };
-    }
-    if (availableActions.viewMarkdown) {
-      return {
-        type: 'viewMarkdown',
-        text: 'View Markdown',
-        icon: FileText,
-      };
-    }
-    if (availableActions.chat) {
-      return {
-        type: 'chat',
-        text: 'Open Chat',
-        icon: MessageCircleQuestion,
-      };
-    }
-    return null;
-  };
-
-  const defaultAction = getDefaultAction();
-  const [buttonText, setButtonText] = useState(defaultAction?.text || 'Action');
-
-  // Fetch the markdown from the url + .mdx
-  const copyMarkdownToClipboard = async () => {
-    console.log('Copying markdown to clipboard');
-    try {
-      setButtonText('Copied');
-      const response = await fetch(markdownUrl);
-      if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
-      }
-      const markdown = await response.text();
-      await navigator.clipboard.writeText(markdown);
-      setTimeout(() => setButtonText(defaultAction?.text || 'Action'), 3000); // Revert after 3 seconds
-    } catch (error) {
-      console.error('Failed to copy markdown:', error);
-      setButtonText('Copy failed'); // Provide feedback on failure
-      setTimeout(() => setButtonText(defaultAction?.text || 'Action'), 3000);
-    }
-  };
-
-  // Fetch the schema from the schemaURL and copy it to the clipboard
-  const copySchemaToClipboard = async (schema: Schema) => {
-    if (!schema.url) return; // Should not happen if button is hidden, but good practice
-
-    console.log('Copying schema to clipboard from:', schema.url);
-    try {
-      setButtonText('Copied Schema');
-      const response = await fetch(schema.url); // Use the provided schemaURL directly
-      if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
-      }
-      const schemaContent = await response.text(); // Or response.json() if it's always JSON
-      await navigator.clipboard.writeText(schemaContent);
-      setTimeout(() => setButtonText(defaultAction?.text || 'Action'), 3000); // Revert after 3 seconds
-    } catch (error) {
-      console.error('Failed to copy schema:', error);
-      setButtonText('Copy failed'); // Provide feedback on failure
-      setTimeout(() => setButtonText(defaultAction?.text || 'Action'), 3000);
-    }
-  };
-
-  // Handle the default action based on type
-  const handleDefaultAction = () => {
-    if (!defaultAction) return;
-
-    switch (defaultAction.type) {
-      case 'copyMarkdown':
-        copyMarkdownToClipboard();
-        break;
-      case 'editPage':
-        window.open(editUrl, '_blank');
-        break;
-      case 'copySchemas':
-        copySchemaToClipboard(schemas[0]);
-        break;
-      case 'viewMarkdown':
-        window.open(markdownUrl, '_blank');
-        break;
-      case 'chat':
-        window.open(buildUrl(`/chat?query=${chatQuery}`));
-        break;
-    }
-  };
-
-  if (!defaultAction) {
-    return null;
-  }
-
-  return (
-    <DropdownMenu.Root>
-      {/* Container for the split button */}
-      <div className="inline-flex rounded-md shadow-sm border border-gray-300">
-        {/* Left Button: Default Action */}
-        <button
-          type="button"
-          onClick={handleDefaultAction}
-          className="inline-flex items-center justify-center gap-1 px-3 py-1.5 text-sm font-medium text-gray-700 bg-white rounded-l-md hover:bg-gray-50 focus:z-10 focus:outline-none focus:ring-1 focus:ring-indigo-500"
-        >
-          <defaultAction.icon className="w-4 h-4" />
-          {buttonText}
-        </button>
-        {/* Right Button: Dropdown Trigger */}
-        <DropdownMenu.Trigger asChild>
-          <button
-            type="button"
-            className="inline-flex items-center justify-center px-1.5 py-1.5 text-sm font-medium text-gray-500 bg-white rounded-r-md border-l border-gray-300 hover:bg-gray-50 focus:z-10 focus:outline-none focus:ring-1 focus:ring-indigo-500"
-            aria-label="More options"
-          >
-            <ChevronDownIcon className="w-4 h-4" />
-          </button>
-        </DropdownMenu.Trigger>
-      </div>
-
-      {/* Adjust styling for the content dropdown */}
-      <DropdownMenu.Content
-        className="w-72 bg-white rounded-lg shadow-lg border border-gray-200 mt-1 py-1"
-        sideOffset={5}
-        align="end"
-      >
-        {availableActions.copyMarkdown && (
-          <DropdownMenu.Item
-            className="cursor-pointer hover:bg-gray-100 focus:outline-none focus:bg-gray-100"
-            onSelect={() => copyMarkdownToClipboard()}
-          >
-            <MenuItemContent icon={Copy} title="Copy page" description="Copy page as Markdown for LLMs" />
-          </DropdownMenu.Item>
-        )}
-
-        {availableActions.editPage && (
-          <DropdownMenu.Item
-            className="cursor-pointer hover:bg-gray-100 focus:outline-none focus:bg-gray-100"
-            onSelect={() => window.open(editUrl, '_blank')}
-          >
-            <MenuItemContent
-              icon={PenSquareIcon}
-              title="Edit page"
-              description="Edit the contents of this page"
-              external={true}
-            />
-          </DropdownMenu.Item>
-        )}
-
-        {availableActions.copySchemas &&
-          schemas.map((schema) => {
-            const title =
-              schema.format === 'asyncapi'
-                ? 'Copy AsyncAPI specification'
-                : schema.format === 'openapi'
-                  ? 'Copy OpenAPI specification'
-                  : 'Copy schema';
-            const type =
-              schema.format === 'asyncapi' || schema.format === 'openapi'
-                ? 'specification'
-                : `${schema.format.toUpperCase()} schema`;
-
-            const Icon =
-              schema.format === 'asyncapi' ? (
-                <img src={buildUrl('/icons/asyncapi.svg', true)} className="w-4 h-4" />
-              ) : schema.format === 'openapi' ? (
-                <img src={buildUrl('/icons/openapi.svg', true)} className="w-4 h-4" />
-              ) : (
-                FileText
-              );
-
-            return (
-              <DropdownMenu.Item
-                key={schema.url}
-                className="cursor-pointer hover:bg-gray-100 focus:outline-none focus:bg-gray-100"
-                onSelect={() => copySchemaToClipboard(schema)}
-              >
-                <MenuItemContent icon={Icon} title={title} description={`Copy ${type} to clipboard`} />
-              </DropdownMenu.Item>
-            );
-          })}
-
-        {availableActions.viewMarkdown && (
-          <DropdownMenu.Item
-            className="cursor-pointer hover:bg-gray-100 focus:outline-none focus:bg-gray-100"
-            onSelect={() => window.open(markdownUrl, '_blank')}
-          >
-            <MenuItemContent
-              icon={FileText}
-              title="View as Markdown"
-              description="View this page as plain text"
-              external={true}
-            />
-          </DropdownMenu.Item>
-        )}
-
-        {availableActions.chat && (
-          <DropdownMenu.Item
-            className="cursor-pointer hover:bg-gray-100 focus:outline-none focus:bg-gray-100"
-            onSelect={() => window.open(buildUrl(`/chat`) + `?query=${chatQuery}`)}
-          >
-            <MenuItemContent
-              icon={MessageCircleQuestion}
-              title="Open in EventCatalog Chat"
-              description="Ask questions about this page"
-              external={true}
-            />
-          </DropdownMenu.Item>
-        )}
-      </DropdownMenu.Content>
-    </DropdownMenu.Root>
-  );
-}
-
-export default CopyPageMenu;
diff --git a/eventcatalog/src/components/DiscoverInsight.astro b/eventcatalog/src/components/DiscoverInsight.astro
deleted file mode 100644
index 509d865a1..000000000
--- a/eventcatalog/src/components/DiscoverInsight.astro
+++ /dev/null
@@ -1,61 +0,0 @@
----
-import { buildUrl } from '@utils/url-builder';
-import type React from 'react';
-import config from '@config';
-import { RssIcon } from 'lucide-react';
-interface Props {
-  color: string;
-  dataTarget: number;
-  icon: React.ElementType;
-  label: 'domains' | 'services' | 'commands' | 'queries' | 'events' | 'flows';
-}
-
-const { color, dataTarget, icon: Icon, label } = Astro.props;
-const isRSSEnabled = config.rss?.enabled;
----
-
-<div class={`relative text-center ${color}`}>
-  <div class="flex justify-center mb-2">
-    <Icon className="w-8 h-8" />
-  </div>
-
-  <div class="text-2xl font-bold mb-1">
-    <span class="statistic" data-target={dataTarget}>0</span>
-  </div>
-
-  <a href={buildUrl(`/discover/${label}`)} class="static hover:underline underline-offset-8 text-sm text-gray-600 capitalize">
-    {label}
-  </a>
-  {
-    isRSSEnabled && (
-      <div class="text-center flex justify-center items-center mt-2">
-        <a href={buildUrl(`/rss/${label}/rss.xml`)} class="flex items-center space-x-2 hover:underline underline-offset-8 ">
-          <RssIcon className="h-3 w-3 text-gray-800 group-hover:text-white" strokeWidth={1} />
-          <span class="text-xs text-gray-600 capitalize">RSS Feed</span>
-        </a>
-      </div>
-    )
-  }
-</div>
-
-<script>
-  function animateStatistics() {
-    const statistics = document.querySelectorAll('.statistic');
-    statistics.forEach((statistic) => {
-      let target = parseInt(statistic.getAttribute('data-target')!);
-      let current = 0;
-      const increment = target / 50;
-      const timer = setInterval(() => {
-        current += increment;
-        if (current >= target) {
-          clearInterval(timer);
-          statistic.textContent = target.toString();
-        } else {
-          statistic.textContent = Math.round(current).toString();
-        }
-      }, 20);
-    });
-  }
-
-  window.addEventListener('load', animateStatistics);
-</script>
diff --git a/eventcatalog/src/components/EnvironmentDropdown.tsx b/eventcatalog/src/components/EnvironmentDropdown.tsx
deleted file mode 100644
index 8cb37ae5e..000000000
--- a/eventcatalog/src/components/EnvironmentDropdown.tsx
+++ /dev/null
@@ -1,135 +0,0 @@
-import React, { useState, useEffect, useRef } from 'react';
-
-interface Environment {
-  name: string;
-  url: string;
-  description?: string;
-  shortName?: string;
-}
-
-interface EnvironmentDropdownProps {
-  environments: Environment[];
-}
-
-export const EnvironmentDropdown: React.FC<EnvironmentDropdownProps> = ({ environments }) => {
-  const [isOpen, setIsOpen] = useState(false);
-  const [currentEnvironment, setCurrentEnvironment] = useState<Environment | null>(null);
-  const dropdownRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    // Check if current URL matches any environment
-    const currentUrl = window.location.origin;
-    const matchedEnv = environments.find((env) => {
-      // Normalize URLs for comparison
-      const envUrl = new URL(env.url).origin;
-      return envUrl === currentUrl;
-    });
-    setCurrentEnvironment(matchedEnv || null);
-  }, [environments]);
-
-  useEffect(() => {
-    // Handle click outside
-    const handleClickOutside = (event: MouseEvent) => {
-      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
-        setIsOpen(false);
-      }
-    };
-
-    // Handle escape key
-    const handleEscape = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        setIsOpen(false);
-      }
-    };
-
-    if (isOpen) {
-      document.addEventListener('click', handleClickOutside);
-      document.addEventListener('keydown', handleEscape);
-    }
-
-    return () => {
-      document.removeEventListener('click', handleClickOutside);
-      document.removeEventListener('keydown', handleEscape);
-    };
-  }, [isOpen]);
-
-  const toggleDropdown = (e: React.MouseEvent) => {
-    e.stopPropagation();
-    setIsOpen(!isOpen);
-  };
-
-  return (
-    <div className="relative" ref={dropdownRef}>
-      <button
-        type="button"
-        onClick={toggleDropdown}
-        className="flex items-center space-x-1 text-sm font-medium text-gray-700 hover:text-gray-900 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-purple-500 rounded-md px-3 py-2"
-        aria-expanded={isOpen}
-        aria-haspopup="true"
-      >
-        <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
-          <path
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            strokeWidth="2"
-            d="M21 12a9 9 0 01-9 9m9-9a9 9 0 00-9-9m9 9H3m9 9a9 9 0 01-9-9m9 9c1.657 0 3-4.03 3-9s-1.343-9-3-9m0 18c-1.657 0-3-4.03-3-9s1.343-9 3-9m-9 9a9 9 0 019-9"
-          />
-        </svg>
-        <span>
-          Environments
-          {currentEnvironment && (
-            <span className="font-normal"> ({currentEnvironment.shortName || currentEnvironment.name})</span>
-          )}
-        </span>
-        <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
-          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M19 9l-7 7-7-7" />
-        </svg>
-      </button>
-      <div
-        className={`${isOpen ? '' : 'hidden'} absolute right-0 mt-2 w-64 bg-white rounded-md shadow-lg py-1 z-50 border border-gray-100 overflow-hidden z-20`}
-      >
-        {environments.map((env) => {
-          const isCurrentEnv = currentEnvironment?.name === env.name;
-
-          return (
-            <a
-              key={env.name}
-              href={env.url}
-              onClick={(e) => {
-                e.preventDefault();
-                // Construct the full URL with the current path when clicked
-                const currentPath = window.location.pathname + window.location.search + window.location.hash;
-                const targetUrl = new URL(env.url);
-                targetUrl.pathname = currentPath;
-                window.location.href = targetUrl.toString();
-              }}
-              className={`block px-4 py-3 text-sm transition-colors border-b border-gray-50 last:border-b-0 ${
-                isCurrentEnv ? 'bg-purple-50 text-purple-700 hover:bg-purple-100' : 'text-gray-700 hover:bg-gray-50'
-              }`}
-            >
-              <div className="flex items-center justify-between">
-                <div>
-                  <div className={`font-medium ${isCurrentEnv ? 'text-purple-700' : ''}`}>{env.name}</div>
-                  {env.description && (
-                    <div className={`text-xs font-light mt-1 ${isCurrentEnv ? 'text-purple-600' : 'text-gray-500'}`}>
-                      {env.description}
-                    </div>
-                  )}
-                </div>
-                {isCurrentEnv && (
-                  <svg className="w-4 h-4 text-purple-600 flex-shrink-0 ml-2" fill="currentColor" viewBox="0 0 20 20">
-                    <path
-                      fillRule="evenodd"
-                      d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z"
-                      clipRule="evenodd"
-                    />
-                  </svg>
-                )}
-              </div>
-            </a>
-          );
-        })}
-      </div>
-    </div>
-  );
-};
diff --git a/eventcatalog/src/components/Grids/DomainGrid.tsx b/eventcatalog/src/components/Grids/DomainGrid.tsx
deleted file mode 100644
index e71a18fc2..000000000
--- a/eventcatalog/src/components/Grids/DomainGrid.tsx
+++ /dev/null
@@ -1,390 +0,0 @@
-import { useState, useMemo, useEffect } from 'react';
-import {
-  ServerIcon,
-  EnvelopeIcon,
-  RectangleGroupIcon,
-  Squares2X2Icon,
-  QueueListIcon,
-  CircleStackIcon,
-} from '@heroicons/react/24/outline';
-import { buildUrlWithParams, buildUrl } from '@utils/url-builder';
-import type { CollectionEntry } from 'astro:content';
-import { type CollectionMessageTypes } from '@types';
-import { getCollectionStyles } from './utils';
-import { SearchBar } from './components';
-import { BoxIcon } from 'lucide-react';
-
-export interface ExtendedDomain extends CollectionEntry<'domains'> {
-  sends: CollectionEntry<CollectionMessageTypes>[];
-  receives: CollectionEntry<CollectionMessageTypes>[];
-  services: CollectionEntry<'services'>[];
-  domains: CollectionEntry<'domains'>[];
-}
-
-interface DomainGridProps {
-  domains: ExtendedDomain[];
-  embeded: boolean;
-}
-
-export default function DomainGrid({ domains, embeded }: DomainGridProps) {
-  const [searchQuery, setSearchQuery] = useState('');
-  const [isMultiColumn, setIsMultiColumn] = useState(false);
-
-  useEffect(() => {
-    if (typeof window !== 'undefined') {
-      const saved = localStorage.getItem('EventCatalog:ArchitectureColumnLayout');
-      if (saved !== null) {
-        setIsMultiColumn(saved === 'multi');
-      }
-    }
-  }, []);
-
-  const toggleColumnLayout = () => {
-    const newValue = !isMultiColumn;
-    setIsMultiColumn(newValue);
-    if (typeof window !== 'undefined') {
-      localStorage.setItem('EventCatalog:ArchitectureColumnLayout', newValue ? 'multi' : 'single');
-    }
-  };
-
-  const filteredDomains = useMemo(() => {
-    let result = [...domains];
-
-    // Filter by search query
-    if (searchQuery) {
-      const query = searchQuery.toLowerCase();
-      result = result.filter(
-        (domain) =>
-          domain.data.name?.toLowerCase().includes(query) ||
-          domain.data.summary?.toLowerCase().includes(query) ||
-          domain.data.services?.some((service: any) => service.data.name.toLowerCase().includes(query)) ||
-          domain.sends?.some((message: any) => message.data.name.toLowerCase().includes(query)) ||
-          domain.receives?.some((message: any) => message.data.name.toLowerCase().includes(query))
-      );
-    }
-
-    // Sort by name by default
-    result.sort((a, b) => (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id));
-
-    return result;
-  }, [domains, searchQuery]);
-
-  return (
-    <div>
-      {/* Breadcrumb */}
-      <nav className="mb-4 flex items-center space-x-2 text-sm text-gray-500">
-        <div className="flex items-center gap-2">
-          <RectangleGroupIcon className="h-4 w-4" />
-          <span className="text-gray-900">Domains</span>
-        </div>
-      </nav>
-
-      <div className="relative border-b border-gray-200  mb-4 pb-4">
-        <div className="md:flex md:items-start md:justify-between">
-          <div className="min-w-0 flex-1 max-w-lg">
-            <h1 className="text-2xl font-bold leading-7 text-gray-900 sm:text-3xl sm:truncate">
-              Domains ({filteredDomains.length})
-            </h1>
-            <p className="mt-2 text-sm text-gray-500">Browse and manage domains in your event-driven architecture</p>
-          </div>
-
-          <div className="mt-6 md:mt-0 md:ml-4 flex-shrink-0 flex items-center gap-3">
-            <SearchBar
-              searchQuery={searchQuery}
-              onSearchChange={setSearchQuery}
-              placeholder="Search domains..."
-              totalResults={filteredDomains.length}
-              totalItems={domains.length}
-            />
-            <button
-              onClick={toggleColumnLayout}
-              className="flex items-center justify-center p-2 bg-white border border-gray-300 rounded-md hover:bg-gray-50 transition-colors duration-200"
-              title={isMultiColumn ? 'Switch to single column' : 'Switch to multi column'}
-            >
-              {isMultiColumn ? (
-                <QueueListIcon className="h-5 w-5 text-gray-600" />
-              ) : (
-                <Squares2X2Icon className="h-5 w-5 text-gray-600" />
-              )}
-            </button>
-          </div>
-        </div>
-      </div>
-
-      <div className={`grid gap-6 ${isMultiColumn ? 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-2 xl:grid-cols-2' : 'grid-cols-1'}`}>
-        {filteredDomains.map((domain) => (
-          <a
-            key={domain.data.id}
-            href={buildUrlWithParams('/architecture/services', {
-              serviceIds: domain.data.services?.map((s: any) => s.data.id).join(','),
-              domainId: domain.data.id,
-              domainName: domain.data.name,
-            })}
-            className="group hover:bg-orange-100  border-2 border-orange-400/50 bg-yellow-50 rounded-lg shadow-sm hover:shadow-lg transition-all duration-200 overflow-hidden"
-          >
-            <div className="p-6">
-              <div className="flex items-center justify-between mb-3">
-                <div className="flex items-center gap-2">
-                  <RectangleGroupIcon className="h-5 w-5 text-orange-500" />
-                  <h3 className="text-lg font-semibold text-gray-900 truncate group-hover:underline transition-colors duration-200">
-                    {domain.data.name || domain.data.id}
-                  </h3>
-                </div>
-                <span className="ml-2 shrink-0 inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-orange-50 text-orange-700">
-                  v{domain.data.version}
-                </span>
-              </div>
-
-              <p className="text-gray-600 text-sm line-clamp-2 min-h-[2.5rem]">
-                {domain.data.summary || <span className="italic">No summary available</span>}
-              </p>
-
-              <div className="flex gap-4 mb-4">
-                <div className="flex items-center gap-2 bg-white rounded-lg px-3 py-2 border border-orange-200">
-                  <RectangleGroupIcon className="h-4 w-4 text-yellow-500" />
-                  <div className="flex">
-                    <p className="text-sm font-medium text-gray-900">{domain.data.domains?.length || 0} Subdomains</p>
-                  </div>
-                </div>
-                <div className="flex items-center gap-2 bg-white rounded-lg px-3 py-2 border border-pink-200">
-                  <ServerIcon className="h-4 w-4 text-pink-500" />
-                  <div className="flex">
-                    <p className="text-sm font-medium text-gray-900">{domain.data.services?.length || 0} Services</p>
-                  </div>
-                </div>
-                <div className="flex items-center gap-2 bg-white rounded-lg px-3 py-2 border border-gray-200 ">
-                  <EnvelopeIcon className="h-4 w-4 text-blue-500" />
-                  <div>
-                    <p className="text-sm font-medium text-gray-900">
-                      {(domain.sends?.length || 0) + (domain.receives?.length || 0)} Messages
-                    </p>
-                  </div>
-                </div>
-                {domain.data.entities && domain.data.entities.length > 0 && (
-                  <div className="flex items-center gap-2 bg-white rounded-lg px-3 py-2 border border-gray-200 ">
-                    <BoxIcon className="h-4 w-4 text-purple-500" />
-                    <div>
-                      <p className="text-sm font-medium text-gray-900">{domain.data.entities?.length} Entities</p>
-                    </div>
-                  </div>
-                )}
-              </div>
-
-              <div className="space-y-6">
-                {/* Subdomains and there services */}
-                {domain.data.domains?.slice(0, 2).map((subdomain: any) => (
-                  <div
-                    key={subdomain.data.id}
-                    className="block space-y-2 bg-white border-2 border-dashed border-orange-400 p-4 rounded-lg transition-colors duration-200"
-                  >
-                    <div className="flex items-center justify-between">
-                      <div className="flex items-center gap-2">
-                        <RectangleGroupIcon className="h-4 w-4 text-orange-500" />
-                        <h4 className="text-sm font-medium text-gray-900">
-                          {subdomain.data.name || subdomain.data.id} (Subdomain)
-                        </h4>
-                      </div>
-                      <span className="text-xs text-gray-500">v{subdomain.data.version}</span>
-                    </div>
-
-                    <div className="flex gap-4">
-                      <div className="flex items-center gap-2 bg-white rounded-lg px-3 py-2 border border-pink-200">
-                        <ServerIcon className="h-4 w-4 text-pink-500" />
-                        <div className="flex">
-                          <p className="text-sm font-medium text-gray-900">{subdomain.data.services?.length || 0} Services</p>
-                        </div>
-                      </div>
-                      <div className="flex items-center gap-2 bg-white rounded-lg px-3 py-2 border border-gray-200">
-                        <EnvelopeIcon className="h-4 w-4 text-blue-500" />
-                        <div>
-                          <p className="text-sm font-medium text-gray-900">
-                            {(subdomain.sends?.length || 0) + (subdomain.receives?.length || 0)} Messages
-                          </p>
-                        </div>
-                      </div>
-                    </div>
-                  </div>
-                ))}
-
-                {/* Services and their messages */}
-                {domain.data.services?.slice(0, 2).map((service: any) => (
-                  <div
-                    key={service.data.id}
-                    className="block space-y-2 bg-white border-2 border-dashed border-pink-400 p-4 rounded-lg transition-colors duration-200"
-                  >
-                    <div className="flex items-center justify-between">
-                      <div className="flex items-center gap-2">
-                        <ServerIcon className="h-4 w-4 text-pink-500" />
-                        <h4 className="text-sm font-medium text-gray-900">{service.data.name || service.data.id}</h4>
-                      </div>
-                      <span className="text-xs text-gray-500">v{service.data.version}</span>
-                    </div>
-
-                    <div className="flex items-center gap-4">
-                      <div className="flex-1 h-full flex flex-col bg-blue-50  border border-blue-300 rounded-lg p-3">
-                        <div className="space-y-1.5 flex-1">
-                          {service.data.receives?.slice(0, 3).map((message: any) => {
-                            const { Icon, color } = getCollectionStyles(message.collection);
-                            return (
-                              <div
-                                key={`${message.id}-${message.version}`}
-                                className="group flex border border-gray-200 items-center gap-1 rounded-md text-[11px] font-medium bg-white"
-                              >
-                                <div className="bg-white border-r border-gray-200 px-2 py-1.5 rounded-l-md">
-                                  <Icon className={`h-3 w-3 text-${color}-500`} />
-                                </div>
-                                <span className="px-1 py-1 truncate max-w-[140px]">{message.id}</span>
-                              </div>
-                            );
-                          })}
-                          {service.data.receives && service.data.receives.length > 3 && (
-                            <div className="text-center py-1">
-                              <p className="text-gray-500 text-[10px]">+ {service.data.receives.length - 3} more</p>
-                            </div>
-                          )}
-                          {!service.data.receives?.length && (
-                            <div className="text-center py-6">
-                              <p className="text-gray-500 text-xs">No messages received</p>
-                            </div>
-                          )}
-                        </div>
-                      </div>
-
-                      <div className="flex items-center gap-2">
-                        <div className="w-4 h-[2px] bg-blue-200"></div>
-                        <div className="bg-white border-2 border-gray-300 rounded-lg p-2 shadow-sm">
-                          <div className="flex flex-col items-center gap-2">
-                            <ServerIcon className="h-6 w-6 text-pink-500" />
-                            <div className="text-center">
-                              <p className="text-xs font-medium text-gray-900">{service.data.name || service.data.id}</p>
-                              <p className="text-[10px] text-gray-500">v{service.data.version}</p>
-                            </div>
-                          </div>
-                        </div>
-                        <div className="w-4 h-[2px] bg-emerald-200"></div>
-                      </div>
-
-                      <div className="flex-1 h-full flex flex-col bg-green-100  border border-green-300 rounded-lg p-3">
-                        <div className="space-y-1.5 flex-1">
-                          {service.data.sends?.slice(0, 3).map((message: any) => {
-                            const { Icon, color } = getCollectionStyles(message.collection);
-                            return (
-                              <div
-                                key={`${message.id}-${message.version}`}
-                                className="group flex border border-gray-200 items-center gap-1 rounded-md text-[11px] font-medium bg-white"
-                              >
-                                <div className="bg-white border-r border-gray-200 px-2 py-1.5 rounded-l-md">
-                                  <Icon className={`h-3 w-3 text-${color}-500`} />
-                                </div>
-
-                                <span className="px-1 py-1 truncate max-w-[140px]">{message.id}</span>
-                              </div>
-                            );
-                          })}
-                          {service.data.sends && service.data.sends.length > 3 && (
-                            <div className="text-center py-1">
-                              <p className="text-gray-500 text-xs">+ {service.data.sends.length - 3} more</p>
-                            </div>
-                          )}
-                          {!service.data.sends?.length && (
-                            <div className="text-center py-6">
-                              <p className="text-gray-500 text-xs">No messages sent</p>
-                            </div>
-                          )}
-                        </div>
-                      </div>
-                    </div>
-
-                    {/* Container lists at the bottom */}
-                    {((service.data.readsFrom && service.data.readsFrom.length > 0) ||
-                      (service.data.writesTo && service.data.writesTo.length > 0)) && (
-                      <div className="mt-3 pt-3 border-t border-gray-200 grid grid-cols-2 gap-4">
-                        {/* Reads From */}
-                        {service.data.readsFrom && service.data.readsFrom.length > 0 && (
-                          <div className="space-y-2">
-                            <div className="flex items-center gap-2">
-                              <CircleStackIcon className="h-4 w-4 text-orange-500" />
-                              <h4 className="text-xs font-semibold text-gray-700">Reads from</h4>
-                            </div>
-                            <div className="flex flex-wrap gap-1">
-                              {service.data.readsFrom.slice(0, 3).map((container: any) => (
-                                <span
-                                  key={container.id}
-                                  className="group inline-flex items-center gap-1 px-2 py-1 bg-orange-100 border border-orange-300 rounded-md text-[11px] font-medium hover:bg-orange-200 transition-colors duration-200"
-                                >
-                                  <CircleStackIcon className="h-3 w-3 text-orange-600" />
-                                  <span className="text-orange-800">{container.id}</span>
-                                </span>
-                              ))}
-                              {service.data.readsFrom.length > 3 && (
-                                <span className="inline-flex items-center px-2 py-1 text-xs text-gray-500">
-                                  + {service.data.readsFrom.length - 3} more
-                                </span>
-                              )}
-                            </div>
-                          </div>
-                        )}
-
-                        {/* Writes To */}
-                        {service.data.writesTo && service.data.writesTo.length > 0 && (
-                          <div className="space-y-2">
-                            <div className="flex items-center gap-2">
-                              <CircleStackIcon className="h-4 w-4 text-purple-500" />
-                              <h4 className="text-xs font-semibold text-gray-700">Writes to</h4>
-                            </div>
-                            <div className="flex flex-wrap gap-1">
-                              {service.data.writesTo.slice(0, 3).map((container: any) => (
-                                <span
-                                  key={container.id}
-                                  className="group inline-flex items-center gap-1 px-2 py-1 bg-purple-100 border border-purple-300 rounded-md text-[11px] font-medium hover:bg-purple-200 transition-colors duration-200"
-                                >
-                                  <CircleStackIcon className="h-3 w-3 text-purple-600" />
-                                  <span className="text-purple-800">{container.id}</span>
-                                </span>
-                              ))}
-                              {service.data.writesTo.length > 3 && (
-                                <span className="inline-flex items-center px-2 py-1 text-xs text-gray-500">
-                                  + {service.data.writesTo.length - 3} more
-                                </span>
-                              )}
-                            </div>
-                          </div>
-                        )}
-                      </div>
-                    )}
-                  </div>
-                ))}
-                {domain.data.domains && domain.data.domains.length > 2 && (
-                  <div className="block space-y-2 bg-white border-2 border-dashed border-orange-400 p-4 rounded-lg transition-colors duration-200">
-                    <div className="flex items-center justify-between">
-                      <div className="flex items-center gap-2">
-                        <RectangleGroupIcon className="h-4 w-4 text-orange-500/70" />
-                        <h4 className="text-sm font-medium text-gray-600">+{domain.data.domains.length - 2} more subdomains</h4>
-                      </div>
-                    </div>
-                  </div>
-                )}
-                {domain.data.services && domain.data.services.length > 2 && (
-                  <div className="block space-y-2 bg-white border-2 border-dashed border-pink-400 p-4 rounded-lg transition-colors duration-200">
-                    <div className="flex items-center justify-between">
-                      <div className="flex items-center gap-2">
-                        <ServerIcon className="h-4 w-4 text-pink-500/70" />
-                        <h4 className="text-sm font-medium text-gray-600">+{domain.data.services.length - 2} more services</h4>
-                      </div>
-                    </div>
-                  </div>
-                )}
-              </div>
-            </div>
-          </a>
-        ))}
-      </div>
-
-      {filteredDomains.length === 0 && (
-        <div className="text-center py-12">
-          <p className="text-gray-500 text-lg">No domains found matching your criteria</p>
-        </div>
-      )}
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/Grids/MessageGrid.tsx b/eventcatalog/src/components/Grids/MessageGrid.tsx
deleted file mode 100644
index 97c77eab3..000000000
--- a/eventcatalog/src/components/Grids/MessageGrid.tsx
+++ /dev/null
@@ -1,577 +0,0 @@
-import { useState, useMemo, useEffect } from 'react';
-import { EnvelopeIcon, ChevronRightIcon, ServerIcon, CircleStackIcon } from '@heroicons/react/24/outline';
-import { RectangleGroupIcon } from '@heroicons/react/24/outline';
-import { buildUrl, buildUrlWithParams } from '@utils/url-builder';
-import type { CollectionEntry } from 'astro:content';
-import type { CollectionMessageTypes } from '@types';
-import { getCollectionStyles } from './utils';
-import { SearchBar, TypeFilters, Pagination } from './components';
-
-interface MessageGridProps {
-  messages: CollectionEntry<CollectionMessageTypes>[];
-  containers?: CollectionEntry<'containers'>[];
-  embeded: boolean;
-  isVisualiserEnabled: boolean;
-}
-
-interface GroupedMessages {
-  all?: CollectionEntry<CollectionMessageTypes>[];
-  sends?: CollectionEntry<CollectionMessageTypes>[];
-  receives?: CollectionEntry<CollectionMessageTypes>[];
-}
-
-export default function MessageGrid({ messages, embeded, containers, isVisualiserEnabled }: MessageGridProps) {
-  const [searchQuery, setSearchQuery] = useState('');
-  const [urlParams, setUrlParams] = useState<{
-    serviceId?: string;
-    serviceName?: string;
-    domainId?: string;
-    domainName?: string;
-  } | null>(null);
-  const [currentPage, setCurrentPage] = useState(1);
-  const [selectedTypes, setSelectedTypes] = useState<CollectionMessageTypes[]>([]);
-  const [producerConsumerFilter, setProducerConsumerFilter] = useState<'all' | 'no-producers' | 'no-consumers'>('all');
-  const ITEMS_PER_PAGE = 15;
-
-  // Effect to sync URL params with state
-  useEffect(() => {
-    const params = new URLSearchParams(window.location.search);
-    const serviceId = params.get('serviceId') || undefined;
-    const serviceName = params.get('serviceName') ? decodeURIComponent(params.get('serviceName')!) : undefined;
-    const domainId = params.get('domainId') || undefined;
-    const domainName = params.get('domainName') || undefined;
-    setUrlParams({
-      serviceId,
-      serviceName,
-      domainId,
-      domainName,
-    });
-  }, []);
-
-  const filteredAndSortedMessages = useMemo(() => {
-    if (urlParams === null) return [];
-
-    let result = [...messages];
-
-    // Filter by message type
-    if (selectedTypes.length > 0) {
-      result = result.filter((message) => selectedTypes.includes(message.collection));
-    }
-
-    // Apply producer/consumer filters
-    if (producerConsumerFilter === 'no-producers') {
-      result = result.filter((message) => !message.data.producers || message.data.producers.length === 0);
-    } else if (producerConsumerFilter === 'no-consumers') {
-      result = result.filter((message) => !message.data.consumers || message.data.consumers.length === 0);
-    }
-
-    // Filter by service ID or name if present
-    if (urlParams.serviceId) {
-      result = result.filter(
-        (message) =>
-          message.data.producers?.some(
-            (producer: any) => producer.id === urlParams.serviceId && !producer.id.includes('/versioned/')
-          ) ||
-          message.data.consumers?.some(
-            (consumer: any) => consumer.id === urlParams.serviceId && !consumer.id.includes('/versioned/')
-          )
-      );
-    }
-
-    // Filter by search query
-    if (searchQuery) {
-      const query = searchQuery.toLowerCase();
-      result = result.filter(
-        (message) =>
-          message.data.name?.toLowerCase().includes(query) ||
-          message.data.summary?.toLowerCase().includes(query) ||
-          message.data.producers?.some((producer: any) => producer.data.id?.toLowerCase().includes(query)) ||
-          message.data.consumers?.some((consumer: any) => consumer.data.id?.toLowerCase().includes(query))
-      );
-    }
-
-    // Sort by name by default
-    result.sort((a, b) => a.data.name.localeCompare(b.data.name));
-
-    return result;
-  }, [messages, searchQuery, urlParams, selectedTypes, producerConsumerFilter]);
-
-  // Add totalPages calculation
-  const totalPages = useMemo(() => {
-    if (urlParams?.serviceId || urlParams?.domainId) return 1;
-    return Math.ceil(filteredAndSortedMessages.length / ITEMS_PER_PAGE);
-  }, [filteredAndSortedMessages.length, urlParams]);
-
-  // Add paginatedMessages calculation
-  const paginatedMessages = useMemo(() => {
-    if (urlParams?.serviceId || urlParams?.domainId) {
-      return filteredAndSortedMessages;
-    }
-
-    const startIndex = (currentPage - 1) * ITEMS_PER_PAGE;
-    return filteredAndSortedMessages.slice(startIndex, startIndex + ITEMS_PER_PAGE);
-  }, [filteredAndSortedMessages, currentPage, urlParams]);
-
-  // Reset pagination when search query or filters change
-  useEffect(() => {
-    setCurrentPage(1);
-  }, [searchQuery, selectedTypes]);
-
-  // Group messages by sends/receives when a service is selected
-  const groupedMessages = useMemo<GroupedMessages>(() => {
-    if (!urlParams?.serviceId) return { all: filteredAndSortedMessages };
-
-    const serviceIdentifier = urlParams.serviceId;
-    const sends = filteredAndSortedMessages.filter((message) =>
-      message.data.producers?.some((producer: any) => producer.id === serviceIdentifier)
-    );
-    const receives = filteredAndSortedMessages.filter((message) =>
-      message.data.consumers?.some((consumer: any) => consumer.id === serviceIdentifier)
-    );
-
-    return { sends, receives };
-  }, [filteredAndSortedMessages, urlParams]);
-
-  // Get the containers that are referenced by the service
-  const serviceContainersReferenced = useMemo(() => {
-    if (!urlParams?.serviceId || !containers) return { writesTo: [], readsFrom: [] };
-    return {
-      writesTo: containers.filter((container) =>
-        container.data.servicesThatWriteToContainer?.some((service: any) => service.data.id === urlParams.serviceId)
-      ),
-      readsFrom: containers.filter((container) =>
-        container.data.servicesThatReadFromContainer?.some((service: any) => service.data.id === urlParams.serviceId)
-      ),
-    };
-  }, [containers, urlParams]);
-
-  const renderTypeFilters = () => {
-    return (
-      <div className="flex flex-col gap-4 sm:flex-row sm:items-center">
-        <div className="flex items-center gap-2">
-          <TypeFilters
-            selectedTypes={selectedTypes}
-            onTypeChange={setSelectedTypes}
-            filteredCount={filteredAndSortedMessages.filter((m) => selectedTypes.includes(m.collection)).length}
-          />
-        </div>
-
-        <div className="flex items-center gap-2 border-l border-gray-200 pl-4">
-          <div className="flex items-center gap-2">
-            <select
-              value={producerConsumerFilter}
-              onChange={(e) => setProducerConsumerFilter(e.target.value as typeof producerConsumerFilter)}
-              className="block rounded-md border-0 py-1.5 pl-3 pr-10 text-gray-900 ring-1 ring-inset ring-gray-300 focus:ring-2 focus:ring-primary sm:text-sm sm:leading-6"
-            >
-              <option value="all">All Messages</option>
-              <option value="no-producers">Without Producers</option>
-              <option value="no-consumers">Without Consumers</option>
-            </select>
-            {producerConsumerFilter !== 'all' && (
-              <button
-                onClick={() => setProducerConsumerFilter('all')}
-                className="text-xs text-gray-500 hover:text-gray-700 hover:underline"
-              >
-                Clear
-              </button>
-            )}
-          </div>
-        </div>
-      </div>
-    );
-  };
-
-  const renderMessageGrid = (messages: CollectionEntry<CollectionMessageTypes>[]) => (
-    <div
-      className={`grid ${urlParams?.serviceName ? 'grid-cols-1' : 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-3'} gap-6`}
-    >
-      {messages.map((message) => {
-        const { color, Icon } = getCollectionStyles(message.collection);
-        return (
-          <a
-            key={message.data.name}
-            href={buildUrl(`/docs/${message.collection}/${message.data.id}/${message.data.version}`)}
-            className={`group bg-white border hover:bg-${color}-100  rounded-lg shadow-sm  hover:shadow-lg transition-all duration-200 overflow-hidden border-${color}-500 `}
-          >
-            <div className="p-4 py-2 flex-1">
-              <div className="flex items-center justify-between mb-3">
-                <div className="flex items-center gap-2">
-                  {!embeded && <Icon className={`h-5 w-5 text-${color}-500`} />}
-                  <h3
-                    className={`font-semibold text-gray-900 truncate group-hover:text-${color}-500 transition-colors duration-200 ${embeded ? 'text-sm' : 'text-md'}`}
-                  >
-                    {message.data.name} (v{message.data.version})
-                  </h3>
-                </div>
-              </div>
-
-              {message.data.summary && <p className="text-gray-600 text-xs line-clamp-2 mb-4">{message.data.summary}</p>}
-
-              {/* Only show stats in non-service view */}
-              {!urlParams?.serviceName && (
-                <div className="space-y-4">
-                  <div className="grid grid-cols-2 gap-2 p-3 bg-gray-50 rounded-lg">
-                    <div className="text-center">
-                      <div className="flex items-center justify-center mb-1">
-                        <ServerIcon className={`h-5 w-5 text-pink-500`} />
-                      </div>
-                      <div className="text-sm font-medium text-gray-900">{message.data.producers?.length ?? 0}</div>
-                      <div className="text-xs text-gray-500">Producers</div>
-                    </div>
-                    <div className="text-center border-l border-gray-200">
-                      <div className="flex items-center justify-center mb-1">
-                        <ServerIcon className={`h-5 w-5 text-pink-500`} />
-                      </div>
-                      <div className="text-sm font-medium text-gray-900">{message.data.consumers?.length ?? 0}</div>
-                      <div className="text-xs text-gray-500">Consumers</div>
-                    </div>
-                  </div>
-                </div>
-              )}
-            </div>
-          </a>
-        );
-      })}
-    </div>
-  );
-
-  const renderPaginationControls = () => {
-    if (totalPages <= 1 || urlParams?.serviceName || urlParams?.domainId) return null;
-
-    return (
-      <Pagination
-        currentPage={currentPage}
-        totalPages={totalPages}
-        totalItems={filteredAndSortedMessages.length}
-        itemsPerPage={ITEMS_PER_PAGE}
-        onPageChange={setCurrentPage}
-      />
-    );
-  };
-
-  return (
-    <div>
-      {/* Breadcrumb */}
-      <nav className="mb-4 flex items-center space-x-2 text-sm text-gray-500">
-        <a href={buildUrl('/architecture/domains')} className="hover:text-gray-700 hover:underline flex items-center gap-2">
-          <RectangleGroupIcon className="h-4 w-4" />
-          Domains
-        </a>
-        <ChevronRightIcon className="h-4 w-4" />
-        <a href={buildUrl('/architecture/services')} className="hover:text-gray-700 hover:underline flex items-center gap-2">
-          <ServerIcon className="h-4 w-4" />
-          Services
-        </a>
-        <ChevronRightIcon className="h-4 w-4" />
-        <a href={buildUrl('/architecture/messages')} className="hover:text-gray-700 hover:underline flex items-center gap-2">
-          <EnvelopeIcon className="h-4 w-4" />
-          Messages
-        </a>
-        {urlParams?.domainId && (
-          <>
-            <ChevronRightIcon className="h-4 w-4" />
-            <a
-              href={buildUrlWithParams(`/architecture/services`, {
-                domainName: urlParams.domainName,
-                domainId: urlParams.domainId,
-                serviceName: urlParams.serviceName,
-                serviceId: urlParams.serviceId,
-              })}
-              className="hover:text-gray-700 hover:underline"
-            >
-              {urlParams.domainId}
-            </a>
-          </>
-        )}
-        {urlParams?.serviceName && (
-          <>
-            <ChevronRightIcon className="h-4 w-4" />
-            <span className="text-gray-900">{urlParams.serviceName}</span>
-          </>
-        )}
-      </nav>
-
-      {/* Title Section */}
-      <div className="relative border-b border-gray-200 mb-4 pb-4">
-        <div className="md:flex md:items-start md:justify-between">
-          <div className="min-w-0 flex-1 max-w-lg">
-            <div className="flex items-center gap-2">
-              <h1 className="text-2xl font-bold leading-7 text-gray-900 sm:text-3xl sm:truncate">
-                {urlParams?.domainName ? `Messages in ${urlParams.serviceName}` : 'All Messages'}
-              </h1>
-            </div>
-            <p className="mt-2 text-sm text-gray-500">
-              {urlParams?.domainName
-                ? `Browse messages in the ${urlParams.serviceName} service`
-                : 'Browse and discover messages in your event-driven architecture'}
-            </p>
-          </div>
-
-          <div className="mt-6 md:mt-0 md:ml-4 flex-shrink-0">
-            <SearchBar
-              searchQuery={searchQuery}
-              onSearchChange={setSearchQuery}
-              placeholder="Search messages by name, summary, or services..."
-              totalResults={filteredAndSortedMessages.length}
-              totalItems={messages.length}
-            />
-          </div>
-        </div>
-      </div>
-
-      <div className="mb-8">
-        {/* Results count and top pagination */}
-        <div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4">
-          {renderTypeFilters()}
-          {renderPaginationControls()}
-        </div>
-      </div>
-
-      {filteredAndSortedMessages.length > 0 && (
-        <div className={`rounded-xl overflow-hidden ${urlParams?.domainId ? 'bg-yellow-50 p-8 border-2 border-yellow-300' : ''}`}>
-          {urlParams?.domainName && (
-            <>
-              <div className="mb-6 flex items-center justify-between">
-                <div className="flex items-center gap-2">
-                  <RectangleGroupIcon className="h-5 w-5 text-yellow-500" />
-                  <a
-                    href={buildUrlWithParams(`/architecture/services`, {
-                      domainName: urlParams.domainName,
-                      domainId: urlParams.domainId,
-                    })}
-                    className="text-2xl font-semibold text-gray-900 hover:underline"
-                  >
-                    {urlParams.domainName}
-                  </a>
-                </div>
-                <div className="flex gap-2">
-                  {isVisualiserEnabled && (
-                    <a
-                      href={buildUrl(`/visualiser/domains/${urlParams.domainId}`)}
-                      className="inline-flex items-center px-3 py-2 text-sm font-medium bg-white border border-gray-300 rounded-md transition-colors duration-200"
-                    >
-                      View in visualizer
-                    </a>
-                  )}
-                  <a
-                    href={buildUrl(`/docs/domains/${urlParams.domainId}`)}
-                    className="inline-flex items-center px-3 py-2 text-sm font-medium text-black border border-gray-300 bg-white  rounded-md transition-colors duration-200"
-                  >
-                    Read documentation
-                  </a>
-                </div>
-              </div>
-            </>
-          )}
-
-          <div
-            className={`rounded-xl overflow-hidden ${urlParams?.serviceName ? 'bg-pink-50 p-8 border-2 border-dashed border-pink-300' : ''}`}
-          >
-            {urlParams?.serviceName ? (
-              <>
-                {/* <div className="h-2 bg-pink-500 -mx-8 -mt-8 mb-8"></div> */}
-                {/* Service Title */}
-                <div className="flex items-center gap-2 mb-8">
-                  <ServerIcon className="h-6 w-6 text-pink-500" />
-                  <h2 className="text-2xl font-semibold text-gray-900">{urlParams.serviceName}</h2>
-                  <div className="flex gap-2 ml-auto">
-                    {isVisualiserEnabled && (
-                      <a
-                        href={buildUrl(`/visualiser/services/${urlParams.serviceId}`)}
-                        className="inline-flex items-center px-3 py-2 text-sm font-medium bg-white border border-gray-300 rounded-md transition-colors duration-200 hover:bg-gray-50"
-                      >
-                        View in visualizer
-                      </a>
-                    )}
-                    <a
-                      href={buildUrl(`/docs/services/${urlParams.serviceId}`)}
-                      className="inline-flex items-center px-3 py-2 text-sm font-medium text-black border border-gray-300 bg-white rounded-md transition-colors duration-200 hover:bg-gray-50"
-                    >
-                      Read documentation
-                    </a>
-                  </div>
-                </div>
-                <div className="grid grid-cols-3 gap-8 relative">
-                  {/* Left Column - Receives Messages & Reads From Containers */}
-                  <div className="space-y-6">
-                    {/* Receives Messages Section */}
-                    <div className="bg-blue-50 bg-opacity-50 border border-blue-300 border-dashed rounded-lg p-4">
-                      <div className="mb-6">
-                        <h2 className={`font-semibold text-gray-900 flex items-center gap-2 ${embeded ? 'text-sm' : 'text-xl'}`}>
-                          <ServerIcon className="h-5 w-5 text-blue-500" />
-                          Receives ({groupedMessages.receives?.length || 0})
-                        </h2>
-                      </div>
-                      {groupedMessages.receives && groupedMessages.receives.length > 0 ? (
-                        renderMessageGrid(groupedMessages.receives)
-                      ) : (
-                        <div className="text-center py-12">
-                          <p className="text-gray-500 text-sm">No messages</p>
-                        </div>
-                      )}
-                    </div>
-
-                    {/* Reads From Containers - Only show if containers exist */}
-                    {serviceContainersReferenced.readsFrom && serviceContainersReferenced.readsFrom.length > 0 && (
-                      <div className="bg-orange-50 border border-orange-300 border-dashed rounded-lg p-4 relative">
-                        <div className="mb-6">
-                          <h2
-                            className={`font-semibold text-gray-900 flex items-center gap-2 ${embeded ? 'text-sm' : 'text-xl'}`}
-                          >
-                            <CircleStackIcon className="h-5 w-5 text-orange-500" />
-                            Reads from ({serviceContainersReferenced.readsFrom.length})
-                          </h2>
-                        </div>
-                        <div className="space-y-3">
-                          {serviceContainersReferenced.readsFrom.map((container: CollectionEntry<'containers'>) => (
-                            <a
-                              key={container.data.id}
-                              href={buildUrl(`/docs/containers/${container.data.id}/${container.data.version}`)}
-                              className="group bg-white border border-orange-200 hover:bg-orange-100 rounded-lg p-3 block transition-all duration-200"
-                            >
-                              <div className="flex items-center gap-2">
-                                <CircleStackIcon className="h-4 w-4 text-orange-500" />
-                                <h3 className="font-semibold text-gray-900 text-sm group-hover:text-orange-700">
-                                  {container.data.name}
-                                </h3>
-                              </div>
-                              {container.data.summary && (
-                                <p className="text-xs text-gray-600 mt-1 line-clamp-2">{container.data.summary}</p>
-                              )}
-                            </a>
-                          ))}
-                        </div>
-                        {/* Arrow from Reads From to Service */}
-                        <div className="absolute -right-8 top-1/2 -translate-y-1/2 flex items-center justify-center w-16 z-10">
-                          <div className="absolute left-0 w-4 h-4 border-b-[3px] border-l-[3px] border-orange-200 transform rotate-45 -translate-x-1 translate-y-[-1px] shadow-[-1px_1px_0_1px_rgba(0,0,0,0.1)]"></div>
-                          <div className="w-full h-[3px] bg-orange-200 shadow-[0_0_0_1px_rgba(0,0,0,0.1)]"></div>
-                        </div>
-                      </div>
-                    )}
-                  </div>
-
-                  {/* Arrow from Receives to Service */}
-                  <div className="absolute left-[30%] top-[25%] -translate-y-1/2 flex items-center justify-center w-16">
-                    <div className="w-full h-[3px] bg-blue-200 shadow-[0_0_0_1px_rgba(0,0,0,0.1)]"></div>
-                    <div className="absolute right-0 w-4 h-4 border-t-[3px] border-r-[3px] border-blue-200 transform rotate-45 translate-x-1 translate-y-[-1px] shadow-[1px_-1px_0_1px_rgba(0,0,0,0.1)]"></div>
-                  </div>
-
-                  {/* Service Information (Center) */}
-                  <div className="bg-white border-2 border-pink-100 rounded-lg p-6 flex flex-col justify-center">
-                    <div className="flex flex-col items-center gap-4">
-                      <ServerIcon className="h-12 w-12 text-pink-500" />
-                      <p className="text-xl font-semibold text-gray-900 text-center">{urlParams.serviceName}</p>
-
-                      {/* Quick Stats Grid */}
-                      <div className="w-full grid grid-cols-2 gap-3 mt-2">
-                        <div className="text-center p-3 bg-blue-50 rounded-lg border border-blue-200">
-                          <div className="text-2xl font-bold text-blue-600">{groupedMessages.receives?.length || 0}</div>
-                          <div className="text-xs text-gray-600 mt-1">Receives</div>
-                        </div>
-                        <div className="text-center p-3 bg-green-50 rounded-lg border border-green-200">
-                          <div className="text-2xl font-bold text-green-600">{groupedMessages.sends?.length || 0}</div>
-                          <div className="text-xs text-gray-600 mt-1">Sends</div>
-                        </div>
-                        {serviceContainersReferenced.readsFrom && serviceContainersReferenced.readsFrom.length > 0 && (
-                          <div className="text-center p-3 bg-orange-50 rounded-lg border border-orange-200">
-                            <div className="text-2xl font-bold text-orange-600">
-                              {serviceContainersReferenced.readsFrom.length}
-                            </div>
-                            <div className="text-xs text-gray-600 mt-1">Reads from</div>
-                          </div>
-                        )}
-                        {serviceContainersReferenced.writesTo && serviceContainersReferenced.writesTo.length > 0 && (
-                          <div className="text-center p-3 bg-purple-50 rounded-lg border border-purple-200">
-                            <div className="text-2xl font-bold text-purple-600">
-                              {serviceContainersReferenced.writesTo.length}
-                            </div>
-                            <div className="text-xs text-gray-600 mt-1">Writes to</div>
-                          </div>
-                        )}
-                      </div>
-                    </div>
-                  </div>
-
-                  {/* Arrow from Service to Sends */}
-                  <div className="absolute right-[30%] top-[25%] -translate-y-1/2 flex items-center justify-center w-16">
-                    <div className="w-full h-[3px] bg-green-200 shadow-[0_0_0_1px_rgba(0,0,0,0.1)]"></div>
-                    <div className="absolute right-0 w-4 h-4 border-t-[3px] border-r-[3px] border-green-200 transform rotate-45 translate-x-1 translate-y-[-1px] shadow-[1px_-1px_0_1px_rgba(0,0,0,0.1)]"></div>
-                  </div>
-
-                  {/* Right Column - Sends Messages & Writes To Containers */}
-                  <div className="space-y-6">
-                    {/* Sends Messages Section */}
-                    <div className="bg-green-50 border border-green-300 border-dashed rounded-lg p-4">
-                      <div className="mb-6">
-                        <h2 className={`font-semibold text-gray-900 flex items-center gap-2 ${embeded ? 'text-sm' : 'text-xl'}`}>
-                          <ServerIcon className="h-5 w-5 text-emerald-500" />
-                          Sends ({groupedMessages.sends?.length || 0})
-                        </h2>
-                      </div>
-                      {groupedMessages.sends && groupedMessages.sends.length > 0 ? (
-                        renderMessageGrid(groupedMessages.sends)
-                      ) : (
-                        <div className="text-center py-12">
-                          <p className="text-gray-500 text-sm">No messages</p>
-                        </div>
-                      )}
-                    </div>
-
-                    {/* Writes To Containers - Only show if containers exist */}
-                    {serviceContainersReferenced.writesTo && serviceContainersReferenced.writesTo.length > 0 && (
-                      <div className="bg-purple-50 border border-purple-300 border-dashed rounded-lg p-4 relative">
-                        {/* Arrow from Service to Writes To */}
-                        <div className="absolute -left-8 top-1/2 -translate-y-1/2 flex items-center justify-center w-16 z-10">
-                          <div className="w-full h-[3px] bg-purple-200 shadow-[0_0_0_1px_rgba(0,0,0,0.1)]"></div>
-                          <div className="absolute right-0 w-4 h-4 border-t-[3px] border-r-[3px] border-purple-200 transform rotate-45 translate-x-1 translate-y-[-1px] shadow-[1px_-1px_0_1px_rgba(0,0,0,0.1)]"></div>
-                        </div>
-                        <div className="mb-6">
-                          <h2
-                            className={`font-semibold text-gray-900 flex items-center gap-2 ${embeded ? 'text-sm' : 'text-xl'}`}
-                          >
-                            <CircleStackIcon className="h-5 w-5 text-purple-500" />
-                            Writes to ({serviceContainersReferenced.writesTo.length})
-                          </h2>
-                        </div>
-                        <div className="space-y-3">
-                          {serviceContainersReferenced.writesTo.map((container: CollectionEntry<'containers'>) => (
-                            <a
-                              key={container.data.id}
-                              href={buildUrl(`/docs/containers/${container.data.id}/${container.data.version}`)}
-                              className="group bg-white border border-purple-200 hover:bg-purple-100 rounded-lg p-3 block transition-all duration-200"
-                            >
-                              <div className="flex items-center gap-2">
-                                <CircleStackIcon className="h-4 w-4 text-purple-500" />
-                                <h3 className="font-semibold text-gray-900 text-sm group-hover:text-purple-700">
-                                  {container.data.name}
-                                </h3>
-                              </div>
-                              {container.data.summary && (
-                                <p className="text-xs text-gray-600 mt-1 line-clamp-2">{container.data.summary}</p>
-                              )}
-                            </a>
-                          ))}
-                        </div>
-                      </div>
-                    )}
-                  </div>
-                </div>
-              </>
-            ) : (
-              <>
-                {renderMessageGrid(paginatedMessages)}
-                <div className="mt-8 border-t border-gray-200">{renderPaginationControls()}</div>
-              </>
-            )}
-          </div>
-        </div>
-      )}
-
-      {filteredAndSortedMessages.length === 0 && (
-        <div className="text-center py-12">
-          <p className="text-gray-500 text-lg">No messages found matching your criteria</p>
-        </div>
-      )}
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/Grids/ServiceGrid.tsx b/eventcatalog/src/components/Grids/ServiceGrid.tsx
deleted file mode 100644
index 85f3b649c..000000000
--- a/eventcatalog/src/components/Grids/ServiceGrid.tsx
+++ /dev/null
@@ -1,540 +0,0 @@
-import { useState, useMemo, useEffect, memo } from 'react';
-import { ServerIcon, ChevronRightIcon, Squares2X2Icon, QueueListIcon, CircleStackIcon } from '@heroicons/react/24/outline';
-import { RectangleGroupIcon } from '@heroicons/react/24/outline';
-import { buildUrl, buildUrlWithParams } from '@utils/url-builder';
-import type { CollectionEntry } from 'astro:content';
-import type { CollectionMessageTypes } from '@types';
-import { getCollectionStyles } from './utils';
-import { SearchBar, TypeFilters, Pagination } from './components';
-import type { ExtendedDomain } from './DomainGrid';
-import { BoxIcon } from 'lucide-react';
-
-// Message component for reuse
-const Message = memo(({ message, collection }: { message: any; collection: string }) => {
-  const { Icon, color } = getCollectionStyles(message.collection);
-  return (
-    <a
-      href={buildUrl(`/docs/${message.collection}/${message.data.id}/${message.data.version}`)}
-      className="group flex border border-gray-200 items-center gap-1 rounded-md text-[11px] font-medium hover:bg-gray-50 transition-colors duration-200 bg-white"
-    >
-      <div className="bg-white border-r border-gray-200 px-2 py-1.5 rounded-l-md">
-        <Icon className={`h-3 w-3 text-${color}-500`} />
-      </div>
-      <span className="px-1 py-1 truncate max-w-[140px]">{message.data.name}</span>
-    </a>
-  );
-});
-
-// Messages Container component
-const MessagesContainer = memo(
-  ({ messages, type, selectedTypes }: { messages: any[]; type: 'receives' | 'sends'; selectedTypes: string[] }) => {
-    const bgColor = type === 'receives' ? 'blue' : 'green';
-    const MAX_MESSAGES_DISPLAYED = 4;
-
-    const filteredMessages = messages?.filter(
-      (message: any) => selectedTypes.length === 0 || selectedTypes.includes(message.collection)
-    );
-
-    const messagesToShow = filteredMessages?.slice(0, MAX_MESSAGES_DISPLAYED);
-    const remainingMessagesCount = filteredMessages ? filteredMessages.length - MAX_MESSAGES_DISPLAYED : 0;
-
-    return (
-      <div className={`flex-1 h-full flex flex-col bg-${bgColor}-100 border border-${bgColor}-300 rounded-lg p-4`}>
-        <div className="space-y-2 flex-1">
-          {messagesToShow?.map((message: any) => (
-            <Message key={message.data.name} message={message} collection={message.collection} />
-          ))}
-          {remainingMessagesCount > 0 && (
-            <div className="text-center py-1">
-              <p className="text-gray-500 text-[10px]">+ {remainingMessagesCount} more</p>
-            </div>
-          )}
-          {(!messages?.length ||
-            (selectedTypes.length > 0 && !messages?.some((message: any) => selectedTypes.includes(message.collection)))) && (
-            <div className="text-center py-4">
-              <p className="text-gray-500 text-[10px]">
-                {selectedTypes.length > 0
-                  ? `Service does not ${type} ${selectedTypes.join(' or ')}`
-                  : `Service does not ${type} any messages`}
-              </p>
-            </div>
-          )}
-        </div>
-      </div>
-    );
-  }
-);
-
-// Service Card component
-const ServiceCard = memo(({ service, urlParams, selectedTypes }: { service: any; urlParams: any; selectedTypes: string[] }) => {
-  return (
-    <a
-      href={buildUrlWithParams('/architecture/messages', {
-        serviceName: service.data.name,
-        serviceId: service.data.id,
-        domainId: urlParams?.domainId,
-        domainName: urlParams?.domainName,
-      })}
-      className="group hover:bg-pink-50 bg-white border-2 border-dashed border-pink-400 rounded-lg shadow-sm hover:shadow-lg transition-all duration-200 overflow-hidden "
-    >
-      <div className="p-6">
-        <div className="flex items-center justify-between mb-3">
-          <div className="flex items-center gap-2 w-full">
-            <ServerIcon className="h-5 w-5 text-pink-500" />
-            <h3 className="text-lg font-semibold text-gray-900 truncate group-hover:underline transition-colors duration-200 w-full max-w-[90%]">
-              {service.data.name || service.data.id} (v{service.data.version})
-            </h3>
-          </div>
-        </div>
-
-        {service.data.summary && <p className="text-gray-600 text-sm line-clamp-2 min-h-[2.5rem]">{service.data.summary}</p>}
-
-        {!urlParams?.serviceName && (
-          <div className="flex items-center gap-4 mt-4">
-            <MessagesContainer messages={service.data.receives} type="receives" selectedTypes={selectedTypes} />
-
-            <div className="flex items-center gap-2 max-w-[200px]">
-              <div className="w-4 h-[2px] bg-blue-200"></div>
-              <div className="bg-white border-2 border-pink-100 rounded-lg p-4 shadow-sm">
-                <div className="flex flex-col items-center gap-3">
-                  <ServerIcon className="h-8 w-8 text-pink-500" />
-                  <div className="text-center">
-                    <p className="text-sm font-medium text-gray-900">{service.data.name || service.data.id}</p>
-                    <p className="text-xs text-gray-500">v{service.data.version}</p>
-                  </div>
-                </div>
-              </div>
-              <div className="w-4 h-[2px] bg-emerald-200"></div>
-            </div>
-
-            <MessagesContainer messages={service.data.sends} type="sends" selectedTypes={selectedTypes} />
-          </div>
-        )}
-
-        {/* Container lists at the bottom */}
-        {((service.data.readsFrom && service.data.readsFrom.length > 0) ||
-          (service.data.writesTo && service.data.writesTo.length > 0)) && (
-          <div className="mt-4 pt-4 border-t border-gray-200 grid grid-cols-2 gap-4">
-            {/* Reads From */}
-            {service.data.readsFrom && service.data.readsFrom.length > 0 && (
-              <div className="space-y-2">
-                <div className="flex items-center gap-2">
-                  <CircleStackIcon className="h-4 w-4 text-orange-500" />
-                  <h4 className="text-xs font-semibold text-gray-700">Reads from</h4>
-                </div>
-                <div className="flex flex-wrap gap-1">
-                  {service.data.readsFrom.slice(0, 3).map((container: any) => (
-                    <a
-                      key={container.id}
-                      href={buildUrl(`/docs/containers/${container.data.id}/${container.data.version}`)}
-                      className="group inline-flex items-center gap-1 px-2 py-1 bg-orange-100 border border-orange-300 rounded-md text-[11px] font-medium hover:bg-orange-200 transition-colors duration-200"
-                    >
-                      <CircleStackIcon className="h-3 w-3 text-orange-600" />
-                      <span className="text-orange-800">{container.data.name}</span>
-                    </a>
-                  ))}
-                  {service.data.readsFrom.length > 3 && (
-                    <span className="inline-flex items-center px-2 py-1 text-xs text-gray-500">
-                      + {service.data.readsFrom.length - 3} more
-                    </span>
-                  )}
-                </div>
-              </div>
-            )}
-
-            {/* Writes To */}
-            {service.data.writesTo && service.data.writesTo.length > 0 && (
-              <div className="space-y-2">
-                <div className="flex items-center gap-2">
-                  <CircleStackIcon className="h-4 w-4 text-purple-500" />
-                  <h4 className="text-xs font-semibold text-gray-700">Writes to</h4>
-                </div>
-                <div className="flex flex-wrap gap-1">
-                  {service.data.writesTo.slice(0, 3).map((container: any) => (
-                    <a
-                      key={container.id}
-                      href={buildUrl(`/docs/containers/${container.data.id}/${container.data.version}`)}
-                      className="group inline-flex items-center gap-1 px-2 py-1 bg-purple-100 border border-purple-300 rounded-md text-[11px] font-medium hover:bg-purple-200 transition-colors duration-200"
-                    >
-                      <CircleStackIcon className="h-3 w-3 text-purple-600" />
-                      <span className="text-purple-800">{container.data.name}</span>
-                    </a>
-                  ))}
-                  {service.data.writesTo.length > 3 && (
-                    <span className="inline-flex items-center px-2 py-1 text-xs text-gray-500">
-                      + {service.data.writesTo.length - 3} more
-                    </span>
-                  )}
-                </div>
-              </div>
-            )}
-          </div>
-        )}
-      </div>
-    </a>
-  );
-});
-
-// Domain Section component
-const DomainSection = memo(
-  ({
-    domain,
-    services,
-    urlParams,
-    selectedTypes,
-    isMultiColumn,
-    isVisualiserEnabled,
-  }: {
-    domain: any;
-    services: any[];
-    urlParams: any;
-    selectedTypes: string[];
-    isMultiColumn: boolean;
-    isVisualiserEnabled: boolean;
-  }) => {
-    const subdomains = domain.data.domains || [];
-    const allSubDomainServices = subdomains.map((subdomain: any) => subdomain.data.services || []).flat();
-
-    const servicesWithoutSubdomains = services.filter((service) => {
-      return !allSubDomainServices.some((s: any) => s.id === service.data.id);
-    });
-
-    return (
-      <div className="space-y-6">
-        {servicesWithoutSubdomains.length > 0 && (
-          <div
-            className={`grid gap-6 ${isMultiColumn ? 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-2 xl:grid-cols-2' : 'grid-cols-1'}`}
-          >
-            {servicesWithoutSubdomains.map((service) => (
-              <ServiceCard key={service.data.id} service={service} urlParams={urlParams} selectedTypes={selectedTypes} />
-            ))}
-          </div>
-        )}
-
-        {subdomains.map((subdomainRef: any) => {
-          const subdomain = domain.data.domains?.find((d: any) => d.data.id === subdomainRef.data.id);
-          if (!subdomain) return null;
-
-          const subdomainServices = services.filter((service) =>
-            subdomain.data.services?.some((s: any) => s.id === service.data.id)
-          );
-
-          if (subdomainServices.length === 0) return null;
-
-          return (
-            <div key={subdomain.data.id} className="bg-orange-50 border-2 border-orange-400 rounded-lg p-6 space-y-4">
-              <div className="flex items-center justify-between">
-                <div className="flex items-center gap-2">
-                  <RectangleGroupIcon className="h-5 w-5 text-orange-500" />
-                  <h3 className="text-xl font-semibold text-gray-900">{subdomain.data.name} (Subdomain)</h3>
-                </div>
-                <div className="flex gap-2">
-                  {isVisualiserEnabled && (
-                    <a
-                      href={buildUrl(`/visualiser/domains/${subdomain.data.id}`)}
-                      className="inline-flex items-center px-3 py-2 text-sm font-medium bg-white border border-gray-300 rounded-md transition-colors duration-200"
-                    >
-                      View in visualizer
-                    </a>
-                  )}
-                  <a
-                    href={buildUrl(`/docs/domains/${subdomain.data.id}`)}
-                    className="inline-flex items-center px-3 py-2 text-sm font-medium text-black border border-gray-300 bg-white rounded-md transition-colors duration-200"
-                  >
-                    Read documentation
-                  </a>
-                </div>
-              </div>
-
-              {/* Entities */}
-              {subdomain.data.entities && subdomain.data.entities.length > 0 && (
-                <div className="space-y-2">
-                  <div className="flex items-center gap-2">
-                    <BoxIcon className="h-4 w-4 text-purple-500" />
-                    <h4 className="text-xs font-semibold text-gray-700">Entities</h4>
-                  </div>
-                  <div className="flex flex-wrap gap-1">
-                    {subdomain.data.entities.map((entity: any) => (
-                      <a
-                        key={entity.id}
-                        href={buildUrl(`/docs/entities/${entity.id}`)}
-                        className="group inline-flex items-center gap-1 px-2 py-1 bg-purple-100 border border-purple-300 rounded-md text-[11px] font-medium hover:bg-purple-200 transition-colors duration-200"
-                      >
-                        <BoxIcon className="h-3 w-3 text-purple-600" />
-                        <span className="text-purple-800">{entity.id}</span>
-                      </a>
-                    ))}
-                  </div>
-                </div>
-              )}
-
-              <div
-                className={`grid gap-6 ${isMultiColumn ? 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-2 xl:grid-cols-2' : 'grid-cols-1'}`}
-              >
-                {subdomainServices.map((service) => (
-                  <ServiceCard
-                    key={service.data.id}
-                    service={service}
-                    urlParams={{
-                      ...urlParams,
-                      domainId: subdomain.data.id,
-                      domainName: `${subdomain.data.name} (Subdomain)`,
-                    }}
-                    selectedTypes={selectedTypes}
-                  />
-                ))}
-              </div>
-            </div>
-          );
-        })}
-      </div>
-    );
-  }
-);
-
-interface ServiceGridProps {
-  services: CollectionEntry<'services'>[];
-  domains: ExtendedDomain[];
-  embeded: boolean;
-  isVisualiserEnabled: boolean;
-}
-
-// Main ServiceGrid component
-export default function ServiceGrid({ services, domains, embeded, isVisualiserEnabled }: ServiceGridProps) {
-  const [searchQuery, setSearchQuery] = useState('');
-  const [currentPage, setCurrentPage] = useState(1);
-  const [selectedTypes, setSelectedTypes] = useState<CollectionMessageTypes[]>([]);
-  const [isMultiColumn, setIsMultiColumn] = useState(false);
-  const ITEMS_PER_PAGE = 16;
-  const [urlParams, setUrlParams] = useState<{
-    serviceIds?: string[];
-    domainId?: string;
-    domainName?: string;
-    serviceName?: string;
-  } | null>(null);
-
-  useEffect(() => {
-    const params = new URLSearchParams(window.location.search);
-    setUrlParams({
-      serviceIds: params.get('serviceIds')?.split(',').filter(Boolean),
-      domainId: params.get('domainId') || undefined,
-      domainName: params.get('domainName') || undefined,
-      serviceName: params.get('serviceName') || undefined,
-    });
-  }, []);
-
-  useEffect(() => {
-    if (typeof window !== 'undefined') {
-      const saved = localStorage.getItem('EventCatalog:ServiceColumnLayout');
-      if (saved !== null) {
-        setIsMultiColumn(saved === 'multi');
-      }
-    }
-  }, []);
-
-  const toggleColumnLayout = () => {
-    const newValue = !isMultiColumn;
-    setIsMultiColumn(newValue);
-    if (typeof window !== 'undefined') {
-      localStorage.setItem('EventCatalog:ServiceColumnLayout', newValue ? 'multi' : 'single');
-    }
-  };
-
-  const filteredAndSortedServices = useMemo(() => {
-    if (urlParams === null) return [];
-
-    let result = [...services];
-
-    if (urlParams.serviceIds?.length) {
-      result = result.filter(
-        (service) => urlParams.serviceIds?.includes(service.data.id) && !service.data.id.includes('/versioned/')
-      );
-    }
-
-    if (searchQuery) {
-      const query = searchQuery.toLowerCase();
-      result = result.filter(
-        (service) =>
-          service.data.name?.toLowerCase().includes(query) ||
-          service.data.summary?.toLowerCase().includes(query) ||
-          service.data.sends?.some((message: any) => message.data.name.toLowerCase().includes(query)) ||
-          service.data.receives?.some((message: any) => message.data.name.toLowerCase().includes(query))
-      );
-    }
-
-    if (selectedTypes.length > 0) {
-      result = result.filter((service) => {
-        const hasMatchingSends = service.data.sends?.some((message: any) => selectedTypes.includes(message.collection));
-        const hasMatchingReceives = service.data.receives?.some((message: any) => selectedTypes.includes(message.collection));
-        return hasMatchingSends || hasMatchingReceives;
-      });
-    }
-
-    result.sort((a, b) => (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id));
-    return result;
-  }, [services, searchQuery, urlParams, selectedTypes]);
-
-  const paginatedServices = useMemo(() => {
-    if (urlParams?.domainId || urlParams?.serviceIds?.length) {
-      return filteredAndSortedServices;
-    }
-    const startIndex = (currentPage - 1) * ITEMS_PER_PAGE;
-    return filteredAndSortedServices.slice(startIndex, startIndex + ITEMS_PER_PAGE);
-  }, [filteredAndSortedServices, currentPage, urlParams]);
-
-  const totalPages = useMemo(() => {
-    if (urlParams?.domainId || urlParams?.serviceIds?.length) return 1;
-    return Math.ceil(filteredAndSortedServices.length / ITEMS_PER_PAGE);
-  }, [filteredAndSortedServices.length, urlParams]);
-
-  useEffect(() => {
-    setCurrentPage(1);
-  }, [searchQuery, selectedTypes]);
-
-  return (
-    <div>
-      {/* Breadcrumb */}
-      <nav className="mb-4 flex items-center space-x-2 text-sm text-gray-500">
-        <a href={buildUrl('/architecture/domains')} className="hover:text-gray-700 hover:underline flex items-center gap-2">
-          <RectangleGroupIcon className="h-4 w-4" />
-          Domains
-        </a>
-        <ChevronRightIcon className="h-4 w-4" />
-        <a href={buildUrl('/architecture/services')} className="hover:text-gray-700 hover:underline flex items-center gap-2">
-          <ServerIcon className="h-4 w-4" />
-          Services
-        </a>
-        {urlParams?.domainId && (
-          <>
-            <ChevronRightIcon className="h-4 w-4" />
-            <span className="text-gray-900">{urlParams.domainId}</span>
-          </>
-        )}
-      </nav>
-
-      {/* Title Section */}
-      <div className="relative border-b border-gray-200 mb-4 pb-4">
-        <div className="md:flex md:items-start md:justify-between">
-          <div className="min-w-0 flex-1 max-w-lg">
-            <div className="flex items-center gap-2">
-              <h1 className="text-2xl font-bold leading-7 text-gray-900 sm:text-3xl sm:truncate">
-                {urlParams?.domainId ? `${urlParams.domainName} Architecture` : 'All Services'}
-              </h1>
-            </div>
-            <p className="mt-2 text-sm text-gray-500">
-              {urlParams?.domainId
-                ? `Browse services and messages in the ${urlParams.domainId} domain`
-                : 'Browse and discover services in your event-driven architecture'}
-            </p>
-          </div>
-
-          <div className="mt-6 md:mt-0 md:ml-4 flex-shrink-0 flex items-center gap-3">
-            <SearchBar
-              searchQuery={searchQuery}
-              onSearchChange={setSearchQuery}
-              placeholder="Search services by name, summary, or messages..."
-              totalResults={filteredAndSortedServices.length}
-              totalItems={services.length}
-            />
-            <button
-              onClick={toggleColumnLayout}
-              className="flex items-center justify-center p-2 bg-white border border-gray-300 rounded-md hover:bg-gray-50 transition-colors duration-200"
-              title={isMultiColumn ? 'Switch to single column' : 'Switch to multi column'}
-            >
-              {isMultiColumn ? (
-                <QueueListIcon className="h-5 w-5 text-gray-600" />
-              ) : (
-                <Squares2X2Icon className="h-5 w-5 text-gray-600" />
-              )}
-            </button>
-          </div>
-        </div>
-      </div>
-
-      <div className="mb-8">
-        {/* Results count and pagination */}
-        <div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4">
-          <TypeFilters
-            selectedTypes={selectedTypes}
-            onTypeChange={setSelectedTypes}
-            filteredCount={filteredAndSortedServices.length}
-            totalCount={services.length}
-          />
-          <div className="text-sm text-gray-500">
-            {urlParams?.domainId || urlParams?.serviceIds?.length ? (
-              <span>
-                Showing {filteredAndSortedServices.length} services in the {urlParams.domainId} domain
-              </span>
-            ) : (
-              <span>
-                Showing {(currentPage - 1) * ITEMS_PER_PAGE + 1} to{' '}
-                {Math.min(currentPage * ITEMS_PER_PAGE, filteredAndSortedServices.length)} of {filteredAndSortedServices.length}{' '}
-                services
-              </span>
-            )}
-          </div>
-          {!(urlParams?.domainId || urlParams?.serviceIds?.length) && (
-            <Pagination
-              currentPage={currentPage}
-              totalPages={totalPages}
-              totalItems={filteredAndSortedServices.length}
-              itemsPerPage={ITEMS_PER_PAGE}
-              onPageChange={setCurrentPage}
-            />
-          )}
-        </div>
-      </div>
-
-      {filteredAndSortedServices.length > 0 && (
-        <div className={`rounded-xl overflow-hidden ${urlParams?.domainId ? 'bg-yellow-50 p-8 border-2 border-yellow-400' : ''}`}>
-          {urlParams?.domainName ? (
-            domains
-              .filter((domain: ExtendedDomain) => domain.data.id === urlParams.domainId)
-              .map((domain: ExtendedDomain) => (
-                <DomainSection
-                  key={domain.data.id}
-                  domain={domain}
-                  services={paginatedServices}
-                  urlParams={urlParams}
-                  selectedTypes={selectedTypes}
-                  isMultiColumn={isMultiColumn}
-                  isVisualiserEnabled={isVisualiserEnabled}
-                />
-              ))
-          ) : (
-            <div
-              className={`grid gap-6 ${isMultiColumn ? 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-2 xl:grid-cols-2' : 'grid-cols-1'}`}
-            >
-              {paginatedServices.map((service) => (
-                <ServiceCard key={service.data.id} service={service} urlParams={urlParams} selectedTypes={selectedTypes} />
-              ))}
-            </div>
-          )}
-        </div>
-      )}
-
-      {filteredAndSortedServices.length === 0 && (
-        <div className="text-center py-12 bg-gray-50 rounded-lg">
-          <p className="text-gray-500 text-lg">
-            {selectedTypes.length > 0
-              ? `No services found that ${selectedTypes.length > 1 ? 'handle' : 'handles'} ${selectedTypes.join(' or ')} messages`
-              : 'No services found matching your criteria'}
-          </p>
-        </div>
-      )}
-
-      {/* Bottom pagination */}
-      {!(urlParams?.domainId || urlParams?.serviceIds?.length) && (
-        <div className="mt-8 border-t border-gray-200">
-          <Pagination
-            currentPage={currentPage}
-            totalPages={totalPages}
-            totalItems={filteredAndSortedServices.length}
-            itemsPerPage={ITEMS_PER_PAGE}
-            onPageChange={setCurrentPage}
-          />
-        </div>
-      )}
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/Grids/components.tsx b/eventcatalog/src/components/Grids/components.tsx
deleted file mode 100644
index 7050fa476..000000000
--- a/eventcatalog/src/components/Grids/components.tsx
+++ /dev/null
@@ -1,170 +0,0 @@
-import React from 'react';
-import {
-  MagnifyingGlassIcon,
-  ChevronLeftIcon,
-  ChevronRightIcon,
-  ChevronDoubleLeftIcon,
-  ChevronDoubleRightIcon,
-} from '@heroicons/react/24/outline';
-import type { CollectionMessageTypes } from '@types';
-import { getCollectionStyles, type PaginationProps, type SearchBarProps, type TypeFilterProps } from './utils';
-
-export function SearchBar({ searchQuery, onSearchChange, placeholder, totalResults, totalItems }: SearchBarProps) {
-  return (
-    <div className="w-full md:w-96">
-      <div className="relative">
-        <div className="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
-          <MagnifyingGlassIcon className="h-5 w-5 text-gray-400" aria-hidden="true" />
-        </div>
-        <input
-          type="text"
-          placeholder={placeholder || 'Search...'}
-          value={searchQuery}
-          onChange={(e) => onSearchChange(e.target.value)}
-          className="block w-full rounded-lg border-0 py-2.5 pl-10 pr-4 text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 placeholder:text-gray-400 focus:ring-2 focus:ring-inset focus:ring-primary sm:text-sm sm:leading-6"
-        />
-        {searchQuery && (
-          <div className="absolute inset-y-0 right-0 flex items-center pr-3">
-            <button onClick={() => onSearchChange('')} className="text-gray-400 hover:text-gray-500 focus:outline-none">
-              <span className="sr-only">Clear search</span>
-              <svg className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor">
-                <path
-                  fillRule="evenodd"
-                  d="M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z"
-                  clipRule="evenodd"
-                />
-              </svg>
-            </button>
-          </div>
-        )}
-      </div>
-      {searchQuery && totalResults !== undefined && totalItems !== undefined && (
-        <div className="mt-2 text-sm text-gray-500 flex items-center justify-between">
-          <span>
-            Found <span className="font-medium text-gray-900">{totalResults}</span> of{' '}
-            <span className="font-medium text-gray-900">{totalItems}</span>
-          </span>
-          <span className="text-gray-400 text-xs">ESC to clear</span>
-        </div>
-      )}
-    </div>
-  );
-}
-
-export function TypeFilters({ selectedTypes, onTypeChange, filteredCount, totalCount }: TypeFilterProps) {
-  const types: CollectionMessageTypes[] = ['events', 'commands', 'queries'];
-
-  return (
-    <div className="flex items-center gap-2">
-      {types.map((type) => {
-        const { color, Icon } = getCollectionStyles(type);
-        const isSelected = selectedTypes.includes(type);
-        return (
-          <button
-            key={type}
-            onClick={() => {
-              onTypeChange(selectedTypes.includes(type) ? selectedTypes.filter((t) => t !== type) : [...selectedTypes, type]);
-            }}
-            className={`
-                            inline-flex items-center gap-2 px-3 py-1.5 rounded-md text-sm font-medium
-                            transition-colors duration-200
-                            ${
-                              isSelected
-                                ? `bg-${color}-100 text-${color}-700 ring-2 ring-${color}-500`
-                                : 'bg-gray-50 text-gray-600 hover:bg-gray-100'
-                            }
-                        `}
-          >
-            <Icon className={`h-4 w-4 ${isSelected ? `text-${color}-500` : 'text-gray-400'}`} />
-            <span className="capitalize">{type}</span>
-            {isSelected && filteredCount !== undefined && (
-              <span
-                className={`inline-flex items-center justify-center px-2 py-0.5 text-xs font-medium bg-${color}-50 text-${color}-700 rounded-full`}
-              >
-                {filteredCount}
-              </span>
-            )}
-          </button>
-        );
-      })}
-      {selectedTypes.length > 0 && (
-        <button onClick={() => onTypeChange([])} className="text-xs text-gray-500 hover:text-gray-700 hover:underline">
-          Clear filters
-        </button>
-      )}
-    </div>
-  );
-}
-
-export function Pagination({ currentPage, totalPages, totalItems, itemsPerPage, onPageChange }: PaginationProps) {
-  if (totalPages <= 1) return null;
-
-  return (
-    <div className="flex items-center justify-between border-gray-200 bg-white px-4 py-3 sm:px-6">
-      <div className="flex flex-1 justify-between sm:hidden">
-        <button
-          onClick={() => onPageChange(Math.max(1, currentPage - 1))}
-          disabled={currentPage === 1}
-          className="relative inline-flex items-center rounded-md border border-gray-300 bg-white px-4 py-2 text-sm font-medium text-gray-700 hover:bg-gray-50 disabled:opacity-50"
-        >
-          Previous
-        </button>
-        <button
-          onClick={() => onPageChange(Math.min(totalPages, currentPage + 1))}
-          disabled={currentPage === totalPages}
-          className="relative ml-3 inline-flex items-center rounded-md border border-gray-300 bg-white px-4 py-2 text-sm font-medium text-gray-700 hover:bg-gray-50 disabled:opacity-50"
-        >
-          Next
-        </button>
-      </div>
-      <div className="hidden sm:flex sm:flex-1 sm:items-center sm:justify-between">
-        <div className="pr-4">
-          <p className="text-sm text-gray-700">
-            Showing <span className="font-medium">{(currentPage - 1) * itemsPerPage + 1}</span> to{' '}
-            <span className="font-medium">{Math.min(currentPage * itemsPerPage, totalItems)}</span> of{' '}
-            <span className="font-medium">{totalItems}</span> results
-          </p>
-        </div>
-        <div>
-          <nav className="isolate inline-flex -space-x-px rounded-md shadow-sm" aria-label="Pagination">
-            <button
-              onClick={() => onPageChange(1)}
-              disabled={currentPage === 1}
-              className="relative inline-flex items-center rounded-l-md px-2 py-2 text-gray-400 ring-1 ring-inset ring-gray-300 hover:bg-gray-50 focus:z-20 focus:outline-offset-0 disabled:opacity-50"
-            >
-              <span className="sr-only">First</span>
-              <ChevronDoubleLeftIcon className="h-5 w-5" aria-hidden="true" />
-            </button>
-            <button
-              onClick={() => onPageChange(Math.max(1, currentPage - 1))}
-              disabled={currentPage === 1}
-              className="relative inline-flex items-center px-2 py-2 text-gray-400 ring-1 ring-inset ring-gray-300 hover:bg-gray-50 focus:z-20 focus:outline-offset-0 disabled:opacity-50"
-            >
-              <span className="sr-only">Previous</span>
-              <ChevronLeftIcon className="h-5 w-5" aria-hidden="true" />
-            </button>
-            <span className="relative inline-flex items-center px-4 py-2 text-sm font-semibold text-gray-900 ring-1 ring-inset ring-gray-300 focus:outline-offset-0">
-              Page {currentPage} of {totalPages}
-            </span>
-            <button
-              onClick={() => onPageChange(Math.min(totalPages, currentPage + 1))}
-              disabled={currentPage === totalPages}
-              className="relative inline-flex items-center px-2 py-2 text-gray-400 ring-1 ring-inset ring-gray-300 hover:bg-gray-50 focus:z-20 focus:outline-offset-0 disabled:opacity-50"
-            >
-              <span className="sr-only">Next</span>
-              <ChevronRightIcon className="h-5 w-5" aria-hidden="true" />
-            </button>
-            <button
-              onClick={() => onPageChange(totalPages)}
-              disabled={currentPage === totalPages}
-              className="relative inline-flex items-center rounded-r-md px-2 py-2 text-gray-400 ring-1 ring-inset ring-gray-300 hover:bg-gray-50 focus:z-20 focus:outline-offset-0 disabled:opacity-50"
-            >
-              <span className="sr-only">Last</span>
-              <ChevronDoubleRightIcon className="h-5 w-5" aria-hidden="true" />
-            </button>
-          </nav>
-        </div>
-      </div>
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/Header.astro b/eventcatalog/src/components/Header.astro
deleted file mode 100644
index eb0519b4c..000000000
--- a/eventcatalog/src/components/Header.astro
+++ /dev/null
@@ -1,234 +0,0 @@
----
-import catalog from '@utils/eventcatalog-config/catalog';
-import Search from '@components/Search/Search.astro';
-import { buildUrl } from '@utils/url-builder';
-import { showEventCatalogBranding, showCustomBranding } from '@utils/feature';
-import { getSession } from 'auth-astro/server';
-import { isAuthEnabled, isSSR } from '@utils/feature';
-import { EnvironmentDropdown } from './EnvironmentDropdown';
-
-let session = null;
-if (isAuthEnabled()) {
-  session = await getSession(Astro.request);
-}
-
-const logo = {
-  src: ('/' + (catalog?.logo?.src || 'logo.png')).replace(/^\/+/, '/'),
-  alt: catalog?.logo?.alt || 'Event Catalog',
-  text: catalog?.logo?.text || 'EventCatalog',
-};
-
-const repositoryUrl = catalog?.repositoryUrl || 'https://github.com/event-catalog/eventcatalog';
----
-
-<nav
-  id="eventcatalog-header"
-  class="fixed top-0 left-0 right-0 h-header bg-white border-b border-gray-100 py-3 font-bold text-xl bg-opacity-20 backdrop-blur-sm z-10"
->
-  <div class="px-4 sm:px-4 lg:px-4">
-    <div class="flex justify-between items-center">
-      <div class="flex-shrink-0 flex items-center w-3/12">
-        <a href={buildUrl(catalog.landingPage || '/')} class="flex space-x-2 items-center">
-          {logo.src && <img alt={logo.alt} src={buildUrl(logo.src, true)} class="w-8 h-8" />}
-          {logo.text && <span class="hidden sm:inline-block text-[1em]">{logo.text}</span>}
-        </a>
-      </div>
-
-      <div class="hidden lg:block flex-grow w-6/12 px-10">
-        <!-- Page find only works on static builds, disable for SSR builds for now -->
-        {!isSSR() && <Search />}
-      </div>
-
-      <div class="hidden md:block w-3/12">
-        {
-          session ? (
-            <div class="flex items-center space-x-4 justify-end pr-2">
-              {catalog.environments && catalog.environments.length > 0 && (
-                <EnvironmentDropdown environments={catalog.environments} client:load />
-              )}
-              <div class="relative">
-                <button
-                  id="profile-menu-button"
-                  type="button"
-                  class="flex items-center focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 rounded-full"
-                  aria-expanded="false"
-                  aria-haspopup="true"
-                >
-                  {session.user?.image && !session.user?.image?.includes('googleusercontent.com') ? (
-                    <img
-                      src={session.user.image}
-                      alt={session.user?.name || 'User'}
-                      class="h-8 w-8 rounded-full border-2 border-gray-200 hover:border-gray-300 transition-colors"
-                    />
-                  ) : (
-                    <div class="h-8 w-8 rounded-full border-2 border-gray-200 hover:border-gray-300 transition-colors bg-gray-100 flex items-center justify-center text-sm font-medium text-gray-600">
-                      {session.user?.name
-                        ? session.user.name
-                            .split(' ')
-                            .map((n) => n[0])
-                            .join('')
-                            .substring(0, 2)
-                            .toUpperCase()
-                        : 'U'}
-                    </div>
-                  )}
-                </button>
-                <div
-                  id="profile-dropdown"
-                  class="hidden absolute right-0 mt-2 w-48 bg-white rounded-md shadow-lg py-1 z-50 border border-gray-100 overflow-hidden"
-                >
-                  <div class="px-4 py-2 text-sm text-gray-700 border-b border-gray-100">
-                    <div class="font-medium">{session.user?.name || 'User'}</div>
-                    {session.user?.email && <div class="text-gray-500">{session.user.email}</div>}
-                  </div>
-                  <button
-                    id="signout-btn"
-                    class="block w-full text-left px-4 py-2 text-sm text-gray-700 hover:bg-gray-100 transition-colors"
-                  >
-                    Sign out
-                  </button>
-                </div>
-              </div>
-            </div>
-          ) : (
-            <>
-              <div class="flex items-center space-x-4 justify-end pr-2">
-                {catalog.environments && catalog.environments.length > 0 && (
-                  <EnvironmentDropdown environments={catalog.environments} client:load />
-                )}
-                {isAuthEnabled() && (
-                  <button
-                    id="okta-signin-btn"
-                    class="bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium px-4 py-2 rounded-md transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
-                  >
-                    Sign In
-                  </button>
-                )}
-                {showEventCatalogBranding() && (
-                  <ul class="flex space-x-8">
-                    <li>
-                      <a href="https://discord.com/invite/3rjaZMmrAm">
-                        <img src={buildUrl('/icons/discord.svg', true)} class="h-7 w-7" />
-                      </a>
-                    </li>
-                    <li>
-                      <a href="https://github.com/event-catalog/eventcatalog">
-                        <img src={buildUrl('/icons/github.svg', true)} class="h-7 w-7" />
-                      </a>
-                    </li>
-                  </ul>
-                )}
-                {showCustomBranding() && !showEventCatalogBranding() && (
-                  <ul class="flex space-x-8">
-                    <li>
-                      <a href={repositoryUrl} class="text-gray-500 hover:text-gray-600 focus:outline-none focus:text-gray-600">
-                        <img src={buildUrl('/icons/github.svg', true)} class="h-7 w-7" />
-                      </a>
-                    </li>
-                  </ul>
-                )}
-              </div>
-            </>
-          )
-        }
-      </div>
-
-      <div class="md:hidden">
-        <button
-          id="menu-toggle"
-          type="button"
-          class="text-gray-500 hover:text-gray-600 focus:outline-none focus:text-gray-600"
-          aria-label="Toggle menu"
-        >
-          <svg viewBox="0 0 24 24" class="h-6 w-6 fill-current">
-            <path
-              fill-rule="evenodd"
-              d="M4 5h16a1 1 0 0 1 0 2H4a1 1 0 1 1 0-2zm0 6h16a1 1 0 0 1 0 2H4a1 1 0 0 1 0-2zm0 6h16a1 1 0 0 1 0 2H4a1 1 0 0 1 0-2z"
-            ></path>
-          </svg>
-        </button>
-      </div>
-    </div>
-
-    <div id="mobile-menu" class="md:hidden hidden mt-4">
-      <ul class="flex flex-col space-y-8 my-4 mb-8">
-        <!-- {
-          navItems.map((item) => {
-            const isActive = currentPath.includes(item.href);
-            return (
-              <li class={`font-light ${isActive ? 'font-bold text-primary' : ''}`}>
-                <a href={item.href}>{item.label}</a>
-              </li>
-            );
-          })
-        } -->
-      </ul>
-    </div>
-  </div>
-</nav>
-
-<div id="eventcatalog-header-spacer" class="h-header"></div>
-<!-- Spacer to prevent content from being hidden under the fixed header -->
-
-<script>
-  const menuToggle = document.getElementById('menu-toggle');
-  const mobileMenu = document.getElementById('mobile-menu');
-  import { signOut } from 'auth-astro/client';
-
-  if (menuToggle && mobileMenu) {
-    menuToggle.addEventListener('click', () => {
-      mobileMenu.classList.toggle('hidden');
-    });
-  }
-
-  // Profile dropdown functionality
-  const profileButton = document.getElementById('profile-menu-button');
-  const profileDropdown = document.getElementById('profile-dropdown');
-
-  if (profileButton && profileDropdown) {
-    profileButton.addEventListener('click', (e) => {
-      e.stopPropagation();
-      profileDropdown.classList.toggle('hidden');
-      profileButton.setAttribute('aria-expanded', !profileDropdown.classList.contains('hidden') ? 'true' : 'false');
-    });
-
-    // Close dropdown when clicking outside
-    document.addEventListener('click', (e) => {
-      if (!profileButton.contains(e.target as Node) && !profileDropdown.contains(e.target as Node)) {
-        profileDropdown.classList.add('hidden');
-        profileButton.setAttribute('aria-expanded', 'false');
-      }
-    });
-
-    // Close dropdown on escape key
-    document.addEventListener('keydown', (e) => {
-      if (e.key === 'Escape' && !profileDropdown.classList.contains('hidden')) {
-        profileDropdown.classList.add('hidden');
-        profileButton.setAttribute('aria-expanded', 'false');
-        profileButton.focus();
-      }
-    });
-
-    document.getElementById('signout-btn')?.addEventListener('click', async () => {
-      await signOut();
-    });
-  }
-</script>
-
-<style>
-  @media (max-width: 768px) {
-    nav {
-      transition: all 0.3s ease-out;
-    }
-
-    #mobile-menu {
-      transition: all 0.3s ease-out;
-      max-height: 0;
-      overflow: hidden;
-    }
-
-    #mobile-menu:not(.hidden) {
-      max-height: 500px; /* Adjust this value as needed */
-    }
-  }
-</style>
diff --git a/eventcatalog/src/components/Lists/CustomSideBarSectionList.astro b/eventcatalog/src/components/Lists/CustomSideBarSectionList.astro
deleted file mode 100644
index 1983be736..000000000
--- a/eventcatalog/src/components/Lists/CustomSideBarSectionList.astro
+++ /dev/null
@@ -1,55 +0,0 @@
----
-import { buildUrl } from '@utils/url-builder';
-import { getCollection } from 'astro:content';
-import { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
-import PillListFlat from './PillListFlat';
-import { resourceToCollectionMap } from '@utils/collections/util';
-interface Props {
-  section?: {
-    title?: string;
-    limit?: number;
-    items: {
-      id: string;
-      type: string;
-      version?: string;
-    }[];
-  };
-}
-
-const { section } = Astro.props;
-const title = section?.title || 'Custom Section';
-const limit = section?.limit || 10;
-const sectionItems = section?.items || [];
-
-// Array to store resolved related resources
-const resolvedResources = [];
-
-// Fetch related resources
-for (const resource of sectionItems) {
-  try {
-    // Use type assertion to ensure TypeScript understands this is a valid collection name
-    const collectionName = resourceToCollectionMap[resource.type as keyof typeof resourceToCollectionMap];
-
-    // Use getEntry instead of getCollection for single item lookup by ID
-    const allItemsInCollection = await getCollection(collectionName);
-    // @ts-ignore
-    const entryToMatchVersion = getItemsFromCollectionByIdAndSemverOrLatest(allItemsInCollection, resource.id, resource.version);
-    const entry = entryToMatchVersion[0];
-
-    if (entry) {
-      resolvedResources.push(entry);
-    }
-  } catch (error) {
-    console.error(`Failed to fetch related resource: ${resource.id} of type ${resource.type}`, error);
-  }
-}
-
-const sectionList = resolvedResources.map((p: any) => ({
-  label: `${p.data.name}`,
-  tag: `v${p.data.version}`,
-  collection: p.collection,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-}));
----
-
-<PillListFlat title={`${title} (${sectionList.length})`} pills={sectionList} color="orange" limit={limit} client:load />
diff --git a/eventcatalog/src/components/Lists/OwnersList.tsx b/eventcatalog/src/components/Lists/OwnersList.tsx
deleted file mode 100644
index ffbb4cbea..000000000
--- a/eventcatalog/src/components/Lists/OwnersList.tsx
+++ /dev/null
@@ -1,65 +0,0 @@
-import { Disclosure, DisclosureButton, DisclosurePanel } from '@headlessui/react';
-import { ChevronDownIcon } from '@heroicons/react/20/solid';
-import { UserGroupIcon, UserIcon } from '@heroicons/react/24/outline';
-
-interface Props {
-  title: string;
-  owners: {
-    label: string;
-    badge?: string;
-    type: string;
-    avatarUrl?: string;
-    href: string;
-  }[];
-  emptyMessage: string;
-}
-
-const OwnersList = ({ title, owners, emptyMessage }: Props) => {
-  return (
-    <div>
-      <div className="mx-auto w-full max-w-lg divide-y divide-white/5 rounded-xl bg-white/5">
-        <Disclosure as="div" className="" defaultOpen={owners.length <= 5}>
-          <DisclosureButton className="group flex w-full items-center justify-start space-x-4">
-            <span className="text-sm text-black font-semibold group-data-[hover]:text-black/80 capitalize"> {title} </span>
-            <ChevronDownIcon className="size-5 fill-black/60 group-data-[hover]:fill-black/50 group-data-[open]:rotate-180" />
-          </DisclosureButton>
-          <DisclosurePanel className="mt-2 text-sm/5 text-black/50">
-            <ul role="list" className="space-y-2">
-              {owners.map((item) => {
-                return (
-                  <li
-                    className="has-tooltip rounded-md text-gray-600 group px-1 w-full hover:bg-gradient-to-l hover:from-purple-500 hover:to-purple-700 hover:text-white hover:font-normal  "
-                    key={item.href}
-                  >
-                    <a className={`flex items-center space-x-2`} href={item.href}>
-                      {item.type === 'users' && (
-                        <UserIcon className="h-4 w-4 text-gray-800 group-hover:text-white" strokeWidth={1} />
-                      )}
-                      {item.type === 'teams' && (
-                        <UserGroupIcon className="h-4 w-4 text-gray-800 group-hover:text-white" strokeWidth={1} />
-                      )}
-                      <span className="font-light text-sm truncate">{item.label}</span>
-                      {item.label.length > 24 && (
-                        <span className="tooltip rounded relative shadow-lg p-1 font-normal text-xs bg-white  text-black ml-[30px] mt-12">
-                          {item.label}
-                        </span>
-                      )}
-                    </a>
-                  </li>
-                );
-              })}
-              {owners.length === 0 && (
-                <li className="inline mr-2 leading-6 text-sm">
-                  <span className="text-gray-500">{emptyMessage}</span>
-                </li>
-              )}
-            </ul>
-          </DisclosurePanel>
-        </Disclosure>
-      </div>
-      <div className="border-b border-gray-100 my-4"></div>
-    </div>
-  );
-};
-
-export default OwnersList;
diff --git a/eventcatalog/src/components/Lists/PillListFlat.styles.css b/eventcatalog/src/components/Lists/PillListFlat.styles.css
deleted file mode 100644
index 81033879e..000000000
--- a/eventcatalog/src/components/Lists/PillListFlat.styles.css
+++ /dev/null
@@ -1,8 +0,0 @@
-.tooltip {
-    visibility: hidden;
-    position: absolute;
-  }
-  .has-tooltip:hover .tooltip {
-    visibility: visible;
-    z-index: 100;
-  }
\ No newline at end of file
diff --git a/eventcatalog/src/components/Lists/ProtocolList.tsx b/eventcatalog/src/components/Lists/ProtocolList.tsx
deleted file mode 100644
index 108c61acc..000000000
--- a/eventcatalog/src/components/Lists/ProtocolList.tsx
+++ /dev/null
@@ -1,74 +0,0 @@
-import { Disclosure, DisclosureButton, DisclosurePanel } from '@headlessui/react';
-import { ChevronDownIcon } from '@heroicons/react/20/solid';
-import { getIconForProtocol } from '@utils/protocols';
-
-import './PillListFlat.styles.css';
-
-interface Props {
-  title: string;
-  color: string;
-  icon?: any;
-  pills: {
-    label: string;
-    badge?: string;
-    href?: string;
-    tag?: string;
-    color?: string;
-    collection?: string;
-    description?: string;
-    icon?: string;
-  }[];
-  emptyMessage?: string;
-}
-
-const ProtocolList = ({ title, pills, emptyMessage, color = 'gray', ...props }: Props) => {
-  return (
-    <div>
-      <div className="mx-auto w-full max-w-lg divide-y divide-white/5 rounded-xl bg-white/5">
-        <Disclosure as="div" className="pb-8" defaultOpen={pills.length <= 10}>
-          <DisclosureButton className="group flex w-full items-center justify-start space-x-4">
-            <span className="text-sm text-black font-semibold group-data-[hover]:text-black/80 capitalize"> {title} </span>
-            <ChevronDownIcon className="size-5 ml-2 fill-black/60 group-data-[hover]:fill-black/50 group-data-[open]:rotate-180" />
-          </DisclosureButton>
-          <DisclosurePanel className="mt-2 text-sm/5 text-black/50">
-            <ul role="list" className="space-y-2">
-              {pills.map((item, index) => {
-                const href = item.href ?? '#';
-                const Icon = item.icon ? getIconForProtocol(item.icon) : null;
-
-                return (
-                  <li
-                    className=" has-tooltip rounded-md text-gray-600 group px-1 w-full hover:bg-gradient-to-l hover:from-purple-500 hover:to-purple-700 hover:text-white hover:font-normal  "
-                    key={`${item.href}-${index}`}
-                  >
-                    <a className={`leading-3`} href={href}>
-                      <span className="space-x-2 flex items-center">
-                        {Icon && <Icon className={`h-4 w-4`} />}
-                        <span className="font-light text-sm truncate">
-                          {item.label} {item.tag && <>({item.tag})</>}
-                        </span>
-                        {item.label.length > 24 && (
-                          <span className="tooltip rounded relative shadow-lg p-1 font-normal text-xs bg-white  text-black ml-[30px] mt-12">
-                            {item.label} ({item.tag})
-                          </span>
-                        )}
-                      </span>
-                      {item.description && <span className="text-[9px] block ml-6 mt-1 leading-0">{item.description}</span>}
-                    </a>
-                  </li>
-                );
-              })}
-              {pills.length === 0 && emptyMessage && (
-                <li className="inline mr-2 leading-tight text-xs">
-                  <span className="text-gray-400">{emptyMessage}</span>
-                </li>
-              )}
-            </ul>
-          </DisclosurePanel>
-        </Disclosure>
-      </div>
-    </div>
-  );
-};
-
-export default ProtocolList;
diff --git a/eventcatalog/src/components/Lists/RepositoryList.astro b/eventcatalog/src/components/Lists/RepositoryList.astro
deleted file mode 100644
index 282b9d854..000000000
--- a/eventcatalog/src/components/Lists/RepositoryList.astro
+++ /dev/null
@@ -1,37 +0,0 @@
----
-import { ScrollText, Workflow, FileDownIcon, Code, Link } from 'lucide-react';
-
-interface Props {
-  repository?: string;
-  language?: string;
-}
-
-const { repository, language } = Astro.props;
----
-
-<div class="mx-auto pb-4 w-full max-w-lg divide-y divide-white/5 rounded-xl bg-white/5 border-b border-gray-100 mb-4">
-  <span class="text-sm text-black font-semibold group-data-[hover]:text-black/80 capitalize">Repository </span>
-  <ul role="list" class="space-y-2 mt-2">
-    {
-      repository && (
-        <li class="has-tooltip rounded-md text-gray-600 group px-1 w-full hover:bg-gradient-to-l hover:from-purple-500 hover:to-purple-700 hover:text-white hover:font-normal  ">
-          <a class={`flex items-center space-x-2`} target="_blank" href={repository}>
-            <Link className="h-4 w-4 text-gray-800 group-hover:text-white" strokeWidth={1} />
-            <span class="font-light text-sm truncate">{repository}</span>
-          </a>
-        </li>
-      )
-    }
-    {
-      language && (
-        <li class=" rounded-md text-gray-600 group px-1 w-full  ">
-          <div class={`flex items-center space-x-2`}>
-            <Code className="h-3 w-3 text-gray-800 " strokeWidth={1} />
-            <span class="font-light text-sm truncate">{language}</span>
-          </div>
-        </li>
-      )
-    }
-  </ul>
-  <!-- <div class='border-b border-gray-100'></div> -->
-</div>
diff --git a/eventcatalog/src/components/Lists/SpecificationsList.astro b/eventcatalog/src/components/Lists/SpecificationsList.astro
deleted file mode 100644
index de23978c4..000000000
--- a/eventcatalog/src/components/Lists/SpecificationsList.astro
+++ /dev/null
@@ -1,67 +0,0 @@
----
-import type { CollectionTypes } from '@types';
-import { buildUrl } from '@utils/url-builder';
-import type { CollectionEntry } from 'astro:content';
-import { getSpecificationsForService } from '@utils/collections/services';
-import type { Service } from '@utils/collections/services';
-interface Props {
-  collectionItem: CollectionEntry<CollectionTypes>;
-}
-
-const { collectionItem } = Astro.props;
-
-const specVersions = collectionItem.data.specifications || {};
-const numberOfSpecifications = Object.keys(specVersions).length;
-
-const specs = getSpecificationsForService(collectionItem as Service);
-
-const openAPISpecifications = specs.filter((spec) => spec.type === 'openapi');
-const asyncAPISpecifications = specs.filter((spec) => spec.type === 'asyncapi');
-const graphQLSpecifications = specs.filter((spec) => spec.type === 'graphql');
----
-
-<div class="space-y-2 mb-8">
-  <span class="text-sm text-black group-data-[hover]:text-black/80 capitalize">Specifications ({numberOfSpecifications})</span>
-  {
-    openAPISpecifications.length > 0 &&
-      openAPISpecifications.map((spec) => (
-        <a
-          href={buildUrl(
-            `/docs/${collectionItem.collection}/${collectionItem.data.id}/${collectionItem.data.version}/spec/${spec.filenameWithoutExtension}`
-          )}
-          class="px-1 text-sm font-light flex items-center space-x-1 hover:underline hover:text-primary rounded-md hover:bg-gradient-to-l  hover:from-purple-500 hover:to-purple-700 hover:text-white"
-        >
-          <img src={buildUrl('/icons/openapi.svg', true)} class="h-4 w-4" />
-          <span>{spec.name}</span>
-        </a>
-      ))
-  }
-  {
-    asyncAPISpecifications.length > 0 &&
-      asyncAPISpecifications.map((spec) => (
-        <a
-          href={buildUrl(
-            `/docs/${collectionItem.collection}/${collectionItem.data.id}/${collectionItem.data.version}/asyncapi/${spec.filenameWithoutExtension}`
-          )}
-          class="px-1 text-sm font-light flex items-center space-x-1 hover:underline rounded-md hover:bg-gradient-to-l  hover:from-purple-500 hover:to-purple-700 hover:text-white"
-        >
-          <img src={buildUrl('/icons/asyncapi.svg', true)} class="h-4 w-4" />
-          <span>{spec.name}</span>
-        </a>
-      ))
-  }
-  {
-    graphQLSpecifications.length > 0 &&
-      graphQLSpecifications.map((spec) => (
-        <a
-          href={buildUrl(
-            `/docs/${collectionItem.collection}/${collectionItem.data.id}/${collectionItem.data.version}/graphql/${spec.filenameWithoutExtension}`
-          )}
-          class="px-1 text-sm font-light flex items-center space-x-1 hover:underline rounded-md hover:bg-gradient-to-l  hover:from-purple-500 hover:to-purple-700 hover:text-white"
-        >
-          <img src={buildUrl('/icons/graphql.svg', true)} class="h-4 w-4" />
-          <span>{spec.name}</span>
-        </a>
-      ))
-  }
-</div>
diff --git a/eventcatalog/src/components/Lists/VersionList.astro b/eventcatalog/src/components/Lists/VersionList.astro
deleted file mode 100644
index da7a076c9..000000000
--- a/eventcatalog/src/components/Lists/VersionList.astro
+++ /dev/null
@@ -1,50 +0,0 @@
----
-import type { CollectionTypes } from '@types';
-import { buildUrl } from '@utils/url-builder';
-import type { CollectionEntry } from 'astro:content';
-import { HistoryIcon } from 'lucide-react';
-
-interface Props {
-  title?: string;
-  versions: string[];
-  collectionItem: CollectionEntry<CollectionTypes>;
-}
-
-const { versions, collectionItem, title } = Astro.props;
-const currentPath = Astro.url.pathname;
----
-
-<div class="space-y-2 pb-4">
-  <span class="text-sm text-black font-semibold group-data-[hover]:text-black/80 capitalize">
-    {title || `Versions (${collectionItem.data.versions?.length})`}
-  </span>
-  <ul role="list" class="space-y-2">
-    {
-      versions.map((version) => {
-        const isCurrent = currentPath.includes(version);
-        return (
-          <li class="rounded-md px-1 group w-full hover:bg-gradient-to-l  hover:from-purple-500 hover:to-purple-700 hover:text-white hover:font-normal  ">
-            <a
-              class={`flex items-center space-x-2 cursor-pointer`}
-              href={buildUrl(`/docs/${collectionItem.collection}/${collectionItem.data.id}/${version}`)}
-            >
-              {/* {Icon && <Icon class={`h-4 w-4`} />} */}
-              <HistoryIcon className="h-4 w-4 text-gray-800 group-hover:text-white" strokeWidth={1} />
-              <span class={`font-light text-sm ${isCurrent ? 'underline ' : ''}`}>
-                {version === collectionItem.data.latestVersion ? `v${version} (latest)` : `v${version}`}
-              </span>
-            </a>
-          </li>
-        );
-      })
-    }
-  </ul>
-  <div class="border-b border-gray-100 pt-2"></div>
-</div>
-
-<script>
-  document.getElementById('version')?.addEventListener('change', (e: any) => {
-    if (!e.target) return;
-    window.location.href = e.target.value;
-  });
-</script>
diff --git a/eventcatalog/src/components/MDX/Accordion/Accordion.tsx b/eventcatalog/src/components/MDX/Accordion/Accordion.tsx
deleted file mode 100644
index 08442aa8a..000000000
--- a/eventcatalog/src/components/MDX/Accordion/Accordion.tsx
+++ /dev/null
@@ -1,52 +0,0 @@
-import { Disclosure, DisclosureButton, DisclosurePanel } from '@headlessui/react';
-import { MinusIcon } from '@heroicons/react/16/solid';
-import { PlusIcon } from '@heroicons/react/24/outline';
-import { useEffect } from 'react';
-
-declare global {
-  interface Window {
-    renderDiagrams?: (graphs: HTMLCollectionOf<Element>) => void;
-    renderPlantUML?: (graphs: HTMLCollectionOf<Element>) => void;
-  }
-}
-
-export default function Example({ title, children }: any) {
-  return (
-    <div className="border border-gray-200 rounded-md px-4 shadow-sm py-2 accordion">
-      <Disclosure as="div" key={title} className="">
-        {({ open }) => {
-          useEffect(() => {
-            if (open) {
-              const graphs = document.getElementsByClassName('mermaid');
-              const plantUML = document.getElementsByClassName('plantuml');
-              if (graphs.length > 0 && window.renderDiagrams) {
-                window.renderDiagrams(graphs);
-              }
-              if (plantUML.length > 0 && window.renderPlantUML) {
-                window.renderPlantUML(plantUML);
-              }
-            }
-          }, [open]);
-
-          return (
-            <div>
-              <DisclosureButton className="flex w-full items-start justify-between text-left text-gray-900">
-                <span className="text-base font-semibold leading-7">{title}</span>
-                <span className="ml-6 flex h-7 items-center">
-                  {open ? (
-                    <MinusIcon className="h-6 w-6" aria-hidden="true" />
-                  ) : (
-                    <PlusIcon className="h-6 w-6" aria-hidden="true" />
-                  )}
-                </span>
-              </DisclosureButton>
-              <DisclosurePanel as="dd" className="pr-12 py-4 prose prose-sm max-w-none">
-                <div className="text-base leading-7 text-gray-600">{children}</div>
-              </DisclosurePanel>
-            </div>
-          );
-        }}
-      </Disclosure>
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/Accordion/AccordionGroup.astro b/eventcatalog/src/components/MDX/Accordion/AccordionGroup.astro
deleted file mode 100644
index 12a8d23f4..000000000
--- a/eventcatalog/src/components/MDX/Accordion/AccordionGroup.astro
+++ /dev/null
@@ -1,14 +0,0 @@
----
-
----
-
-<div class="accordian-group border border-gray-200 rounded-md shadow-sm accordion my-2">
-  <slot />
-</div>
-
-<style is:global>
-  .accordian-group .accordion {
-    border: none;
-    border-bottom: 1px solid #e2e8f0;
-  }
-</style>
diff --git a/eventcatalog/src/components/MDX/Admonition.tsx b/eventcatalog/src/components/MDX/Admonition.tsx
deleted file mode 100644
index db9233b33..000000000
--- a/eventcatalog/src/components/MDX/Admonition.tsx
+++ /dev/null
@@ -1,38 +0,0 @@
-import { InformationCircleIcon, ExclamationTriangleIcon } from '@heroicons/react/24/outline';
-
-const getConfigurationByType = (type: string) => {
-  switch (type) {
-    case 'danger':
-      return { color: 'red', icon: ExclamationTriangleIcon, title: 'Danger' };
-    case 'alert':
-      return { color: 'red', icon: ExclamationTriangleIcon, title: 'Alert' };
-    case 'warning':
-      return { color: 'yellow', icon: ExclamationTriangleIcon, title: 'Warning' };
-    default:
-      return { color: 'indigo', icon: InformationCircleIcon, title: 'Info' };
-  }
-};
-
-interface AdmonitionProps {
-  children: React.ReactNode;
-  type?: string;
-  className?: string;
-  title?: string;
-}
-
-export default function Admonition({ children, type = 'info', className = '', title }: AdmonitionProps) {
-  const config = getConfigurationByType(type);
-  const Icon = config.icon;
-
-  return (
-    <div className={`bg-${config.color}-50 border-l-4 border-${config.color}-500 p-4 my-4 ${className} rounded-md not-prose`}>
-      <div className="flex flex-col">
-        <div className="flex items-center justify-start">
-          <Icon className={`h-6 w-6 text-${config.color}-500 stroke-2`} aria-hidden="true" />
-          <h3 className={`ml-2 text-${config.color}-600 font-bold text-md`}>{title || config.title}</h3>
-        </div>
-        <div className={`mt-2 text-${config.color}-700 text-md`}>{children}</div>
-      </div>
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/Attachments.astro b/eventcatalog/src/components/MDX/Attachments.astro
deleted file mode 100644
index 92033ecbf..000000000
--- a/eventcatalog/src/components/MDX/Attachments.astro
+++ /dev/null
@@ -1,158 +0,0 @@
----
-import type { ComponentType } from 'react';
-import * as Icons from '@heroicons/react/24/outline';
-import * as SolidIcons from '@heroicons/react/24/solid';
-import * as LucideIcons from 'lucide-react';
-
-interface AttachmentObject {
-  url: string;
-  title?: string;
-  type?: string;
-  description?: string;
-  summary?: string;
-  icon?: string;
-}
-
-type Attachment = string | AttachmentObject;
-
-interface Props {
-  title?: string;
-  description?: string;
-  columns?: number;
-  data: {
-    attachments: Attachment[];
-  };
-}
-
-const { title = 'Attachments', description, columns = 2, ...props } = Astro.props;
-const { attachments } = props.data;
-
-function getIconForAttachment(attachment: AttachmentObject): ComponentType<{ className?: string }> | null {
-  // If custom icon is provided, try to find it
-  if (attachment.icon) {
-    const customIcon =
-      (LucideIcons as any)[attachment.icon] || (Icons as any)[attachment.icon] || (SolidIcons as any)[attachment.icon];
-    if (customIcon) return customIcon;
-  }
-
-  // Default to link icon for all attachments
-  return Icons.LinkIcon;
-}
-
-function normalizeAttachment(attachment: Attachment): AttachmentObject {
-  if (typeof attachment === 'string') {
-    // Extract filename from URL for title
-    const urlParts = attachment.split('/');
-    const filename = urlParts[urlParts.length - 1];
-    const title = filename.includes('.') ? filename.split('.')[0] : filename || 'Link';
-
-    return {
-      url: attachment,
-      title: title.replace(/[-_]/g, ' ').replace(/\b\w/g, (l) => l.toUpperCase()),
-    };
-  }
-  return attachment;
-}
-
-function isExternalUrl(url: string): boolean {
-  return url.startsWith('http://') || url.startsWith('https://');
-}
-
-const normalizedAttachments = attachments.map(normalizeAttachment);
-
-// Group attachments by type
-const groupedAttachments = normalizedAttachments.reduce(
-  (groups, attachment) => {
-    const type = attachment.type || 'Other';
-    if (!groups[type]) {
-      groups[type] = [];
-    }
-    groups[type].push(attachment);
-    return groups;
-  },
-  {} as Record<string, AttachmentObject[]>
-);
-
-const sortedGroups = Object.entries(groupedAttachments).sort(([a], [b]) => {
-  if (a === 'Other') return 1;
-  if (b === 'Other') return -1;
-  return a.localeCompare(b);
-});
----
-
-<section class="not-prose my-8">
-  {title && <h3 class="flex items-center gap-2 text-3xl font-bold mb-4">{title}</h3>}
-
-  {description && <p class="text-gray-600 mb-6 prose prose-md">{description}</p>}
-
-  {
-    normalizedAttachments.length === 0 ? (
-      <div class="text-gray-500 text-sm italic">No attachments available.</div>
-    ) : (
-      <div class="space-y-6">
-        {sortedGroups.map(([groupType, groupAttachments], index) => (
-          <div>
-            <h4 class="text-sm font-medium text-gray-900 mb-3 uppercase tracking-wider">
-              {groupType} ({groupAttachments.length})
-            </h4>
-            <div class={`grid grid-cols-1 ${columns === 1 ? '' : `md:grid-cols-${Math.min(columns, 3)}`} gap-4`}>
-              {groupAttachments.map((attachment) => {
-                const IconComponent = getIconForAttachment(attachment);
-                const isExternal = isExternalUrl(attachment.url);
-
-                return (
-                  <a
-                    href={attachment.url}
-                    target={isExternal ? '_blank' : '_self'}
-                    rel={isExternal ? 'noopener noreferrer' : undefined}
-                    class="group block bg-white border border-gray-200 rounded-lg p-4 transition-all duration-200 hover:shadow-md hover:border-purple-300 hover:bg-purple-50/30 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2"
-                  >
-                    <div class="flex items-start gap-3">
-                      <div class="flex-shrink-0 p-2 bg-gray-100 rounded-lg group-hover:bg-purple-100 transition-colors duration-200">
-                        {IconComponent && <IconComponent className="w-5 h-5 text-gray-600 group-hover:text-purple-600" />}
-                      </div>
-
-                      <div class="flex-grow min-w-0">
-                        <div class="flex items-center gap-2">
-                          <h5 class="text-sm font-medium text-gray-900 group-hover:text-purple-900 truncate">
-                            {attachment.title || 'Attachment'}
-                          </h5>
-                          {isExternal && (
-                            <Icons.ArrowTopRightOnSquareIcon className="w-3 h-3 text-gray-400 group-hover:text-purple-500 flex-shrink-0" />
-                          )}
-                        </div>
-
-                        {attachment.summary && (
-                          <p class="mt-1 text-xs text-gray-600 group-hover:text-purple-700 line-clamp-2">{attachment.summary}</p>
-                        )}
-
-                        {attachment.description && (
-                          <p class="mt-1 text-xs text-gray-600 group-hover:text-purple-700 line-clamp-2">
-                            {attachment.description}
-                          </p>
-                        )}
-
-                        <div class="mt-2 text-xs text-gray-400 group-hover:text-purple-500 truncate">
-                          {attachment.url.replace(/^https?:\/\//, '')}
-                        </div>
-                      </div>
-                    </div>
-                  </a>
-                );
-              })}
-            </div>
-          </div>
-        ))}
-      </div>
-    )
-  }
-</section>
-
-<style>
-  .line-clamp-2 {
-    display: -webkit-box;
-    -webkit-line-clamp: 2;
-    -webkit-box-orient: vertical;
-    overflow: hidden;
-  }
-</style>
diff --git a/eventcatalog/src/components/MDX/ChannelInformation/ChannelInformation.tsx b/eventcatalog/src/components/MDX/ChannelInformation/ChannelInformation.tsx
deleted file mode 100644
index a48c2f3f8..000000000
--- a/eventcatalog/src/components/MDX/ChannelInformation/ChannelInformation.tsx
+++ /dev/null
@@ -1,65 +0,0 @@
-import type { CollectionEntry } from 'astro:content';
-import { getIconForProtocol } from '@utils/protocols';
-
-const ChannelParameters = (data: CollectionEntry<'channels'>['data']) => {
-  return (
-    <div className="container mx-auto py-4 not-prose space-y-4">
-      <div>
-        <h4 className="text-2xl font-bold">Channel information</h4>
-      </div>
-
-      <div>
-        <p className="text-md">
-          {data.address && (
-            <div>
-              <span className="font-semibold">Address:</span> <code className="bg-gray-100 p-1 rounded">{data.address}</code>
-            </div>
-          )}
-          {data.protocols && data.protocols.length > 0 && (
-            <div className="mt-2 flex items-center space-x-1">
-              <span className="font-semibold">{data.protocols.length > 1 ? 'Protocols:' : 'Protocol:'}</span>
-              <ul className="space-x-2 flex">
-                {data.protocols.map((protocol) => {
-                  const IconComponent = getIconForProtocol(protocol.toLowerCase());
-                  return (
-                    <li key={protocol} className=" text-sm flex items-center space-x-1  bg-gray-100 rounded-md px-1">
-                      {IconComponent && <IconComponent className="w-4 h-4" />}
-                      <span>{protocol}</span>
-                    </li>
-                  );
-                })}
-              </ul>
-            </div>
-          )}
-        </p>
-      </div>
-
-      {data.parameters && Object.keys(data.parameters).length > 0 && (
-        <div className="overflow-x-auto">
-          <table className="min-w-full bg-white border border-gray-300">
-            <thead>
-              <tr className="bg-purple-500 text-white">
-                <th className="py-2 px-4 border-b text-left">Parameter</th>
-                <th className="py-2 px-4 border-b text-left">Description</th>
-                <th className="py-2 px-4 border-b text-left">Options</th>
-                <th className="py-2 px-4 border-b text-left">Default</th>
-              </tr>
-            </thead>
-            <tbody>
-              {Object.entries(data.parameters).map(([param, details]) => (
-                <tr className="hover:bg-gray-50" key={param}>
-                  <td className="py-2 px-4 border-b">{param}</td>
-                  <td className="py-2 px-4 border-b">{details.description}</td>
-                  <td className="py-2 px-4 border-b">{details.enum ? details.enum.join(', ') : 'N/A'}</td>
-                  <td className="py-2 px-4 border-b">{details.default || 'N/A'}</td>
-                </tr>
-              ))}
-            </tbody>
-          </table>
-        </div>
-      )}
-    </div>
-  );
-};
-
-export default ChannelParameters;
diff --git a/eventcatalog/src/components/MDX/Design/Design.astro b/eventcatalog/src/components/MDX/Design/Design.astro
deleted file mode 100644
index cecb1a557..000000000
--- a/eventcatalog/src/components/MDX/Design/Design.astro
+++ /dev/null
@@ -1,70 +0,0 @@
----
-const { file: designPath, filePath, search = true, title } = Astro.props;
-import fs from 'fs';
-import { getAbsoluteFilePathForAstroFile } from '@utils/files';
-import Admonition from '@components/MDX/Admonition';
-import NodeGraph from '../NodeGraph/NodeGraph';
-
-import { isVisualiserEnabled } from '@utils/feature';
-
-let design: any;
-let id = 'design';
-let maxHeight = 30;
-
-try {
-  const fileName = designPath.endsWith('.ecstudio') ? designPath : `${designPath}.ecstudio`;
-  const pathToSpec = getAbsoluteFilePathForAstroFile(filePath, fileName);
-  const designFile = fs.readFileSync(pathToSpec, 'utf8');
-  design = JSON.parse(designFile);
-} catch (error) {
-  console.error(`Error reading design file: ${error}`);
-}
----
-
-{
-  !design && (
-    <Admonition type="warning">
-      <div>
-        <span class="block font-bold">{`<Design/>`} failed to load</span>
-        <span class="block">
-          Tried to load design file: {designPath}. Make sure you have this design file defined in your project.
-        </span>
-      </div>
-    </Admonition>
-  )
-}
-
-{
-  design && (
-    <div>
-      <div
-        class="h-[30em] my-6 mb-12 w-full relative border border-gray-200 rounded-md"
-        id={`${id}-portal`}
-        style={{
-          maxHeight: maxHeight ? `${maxHeight}em` : `30em`,
-        }}
-      />
-
-      <div>
-        <NodeGraph
-          id={id}
-          title={title ?? design.name}
-          nodes={design.nodes || []}
-          edges={design.edges || []}
-          hrefLabel={isVisualiserEnabled() ? 'View in visualizer' : undefined}
-          href={isVisualiserEnabled() ? `/visualiser/designs/${design.id}` : undefined}
-          linkTo={'visualiser'}
-          designId={design.id || id}
-          client:only="react"
-          showSearch={search}
-        />
-      </div>
-    </div>
-  )
-}
-
-<style is:global>
-  .react-flow__attribution {
-    display: none;
-  }
-</style>
diff --git a/eventcatalog/src/components/MDX/EntityMap/EntityMap.astro b/eventcatalog/src/components/MDX/EntityMap/EntityMap.astro
deleted file mode 100644
index 486aa4cbf..000000000
--- a/eventcatalog/src/components/MDX/EntityMap/EntityMap.astro
+++ /dev/null
@@ -1,81 +0,0 @@
----
-import { getDomains } from '@utils/collections/domains';
-import { getNodesAndEdges } from '@utils/node-graphs/domain-entity-map.ts';
-import Admonition from '@components/MDX/Admonition';
-import NodeGraph from '../NodeGraph/NodeGraph';
-import { getVersionFromCollection } from '@utils/collections/versions';
-import { getServices } from '@utils/collections/services';
-
-const { id, version = 'latest', maxHeight, includeKey = true, entities, collection = 'domains', ...rest } = Astro.props;
-let resource = null;
-
-let resourceId = id;
-
-// If the user did not provide an id, we need to use the id from the rest props (the collection)
-const isAstroGeneratedId = id.match(/-\d+\.\d+\.\d+$/);
-if (isAstroGeneratedId) {
-  resourceId = rest.data.id;
-}
-
-if (collection === 'domains') {
-  const domains = await getDomains();
-  const domainCollection = getVersionFromCollection(domains, resourceId, version) || [];
-  resource = domainCollection[0];
-} else if (collection === 'services') {
-  const services = await getServices();
-  const serviceCollection = getVersionFromCollection(services, resourceId, version) || [];
-  resource = serviceCollection[0];
-} else {
-  throw new Error(`Invalid collection: ${collection}`);
-}
-
-const { nodes, edges } = await getNodesAndEdges({
-  id: resourceId,
-  version: resource?.data?.version,
-  ...(entities ? { entities } : {}), // Pass entities if provided
-  type: collection,
-});
----
-
-{
-  !resource && (
-    <Admonition type="warning">
-      <div>
-        <span class="block font-bold">{`<EntityMap/>`} failed to load</span>
-        <span class="block">
-          Tried to load {collection} id: {id} with version {version}. Make sure you have this {collection} defined in your
-          project.
-        </span>
-      </div>
-    </Admonition>
-  )
-}
-
-<div
-  class="h-[30em] my-6 mb-12 w-full relative border border-gray-200 rounded-md"
-  id={`${id}-entity-map-portal`}
-  style={{
-    maxHeight: maxHeight ? `${maxHeight}em` : `30em`,
-  }}
->
-</div>
-
-<div>
-  <NodeGraph
-    id={id}
-    nodes={nodes}
-    edges={edges}
-    linkTo={'visualiser'}
-    mode="simple"
-    includeKey={includeKey}
-    footerLabel={`Entity Map - ${resource?.data?.name} - v(${resource?.data?.version})`}
-    client:only="react"
-    portalId={`${id}-entity-map-portal`}
-  />
-</div>
-
-<style is:global>
-  .react-flow__attribution {
-    display: none;
-  }
-</style>
diff --git a/eventcatalog/src/components/MDX/EntityPropertiesTable/EntityPropertiesTable.astro b/eventcatalog/src/components/MDX/EntityPropertiesTable/EntityPropertiesTable.astro
deleted file mode 100644
index 4cc865141..000000000
--- a/eventcatalog/src/components/MDX/EntityPropertiesTable/EntityPropertiesTable.astro
+++ /dev/null
@@ -1,106 +0,0 @@
----
-import type { CollectionEntry } from 'astro:content';
-import Admonition from '../Admonition';
-
-// Define the shape for a single property used in this component
-type EntityProperty = {
-  name: string;
-  type: string;
-  required?: boolean;
-  description?: string;
-  enum?: string[];
-  items?: {
-    type: string;
-  };
-};
-
-// Expects a CollectionEntry for 'entities'.
-// The actual properties structure might differ slightly from the base type,
-// so we handle it below.
-export interface Props extends CollectionEntry<'entities'> {}
-
-const { data, collection } = Astro.props;
-// Cast the properties to our expected type for use in the template
-const properties = data?.properties as EntityProperty[] | undefined;
-const isComponentEnabled = collection === 'entities';
----
-
-{
-  !isComponentEnabled && (
-    <Admonition type="warning">
-      <div>
-        <span class="font-bold">
-          {`<MessageTable/>`} component is not supported for resources of type {collection}.
-        </span>
-        <span class="block">This component is only supported for services and domains.</span>
-      </div>
-    </Admonition>
-  )
-}
-
-{
-  isComponentEnabled && properties && properties.length > 0 ? (
-    <div class="overflow-x-auto relative not-prose">
-      <table class="w-full text-sm text-left text-gray-500 border border-gray-200 rounded-lg shadow-sm">
-        <thead class="text-xs text-gray-700 uppercase bg-gray-50">
-          <tr>
-            <th scope="col" class="py-3 px-6">
-              Name
-            </th>
-            <th scope="col" class="py-3 px-6">
-              Type
-            </th>
-            <th scope="col" class="py-3 px-6">
-              Required
-            </th>
-            <th scope="col" class="py-3 px-6 min-w-[250px]">
-              Description
-            </th>
-          </tr>
-        </thead>
-        <tbody>
-          {properties.map((prop) => (
-            <tr class="bg-white border-b hover:bg-gray-50 align-top">
-              <td class="py-4 px-6 font-medium text-gray-900 whitespace-nowrap">
-                <code class="text-sm bg-gray-100 rounded px-1 py-0.5">{prop.name}</code>
-              </td>
-              <td class="py-4 px-6">
-                {prop.type === 'array' && prop.items ? (
-                  <span>
-                    array&lt;<code class="text-sm bg-gray-100 rounded px-1 py-0.5">{prop.items.type}</code>&gt;
-                  </span>
-                ) : (
-                  <code class="text-sm bg-gray-100 rounded px-1 py-0.5">{prop.type}</code>
-                )}
-                {prop.enum && (
-                  <div class="text-xs text-gray-500 mt-2">
-                    <span class="font-semibold block mb-1">Enum:</span>
-                    <ul class="list-disc list-inside ml-2 space-y-1">
-                      {prop.enum.map((enumValue: string) => (
-                        <li>
-                          <code class="text-xs bg-gray-100 rounded px-1 py-0.5">{enumValue}</code>
-                        </li>
-                      ))}
-                    </ul>
-                  </div>
-                )}
-              </td>
-              <td class="py-4 px-6">
-                {prop.required ? (
-                  <span class="bg-purple-100 text-purple-800 text-xs font-semibold mr-2 px-2.5 py-0.5 rounded">Required</span>
-                ) : (
-                  <span class="bg-gray-100 text-gray-800 text-xs font-semibold mr-2 px-2.5 py-0.5 rounded">Optional</span>
-                )}
-              </td>
-              <td class="py-4 px-6">{prop.description || <span class="text-gray-400 italic">No description provided.</span>}</td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
-    </div>
-  ) : (
-    <Admonition type="note" title="No Properties Defined">
-      <p>There are no properties defined for this entity.</p>
-    </Admonition>
-  )
-}
diff --git a/eventcatalog/src/components/MDX/File.tsx b/eventcatalog/src/components/MDX/File.tsx
deleted file mode 100644
index f5e19520f..000000000
--- a/eventcatalog/src/components/MDX/File.tsx
+++ /dev/null
@@ -1,43 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-
-const File = ({ file, catalog, title }: any) => {
-  try {
-    const exists = fs.existsSync(path.join(catalog.filePath, file));
-
-    if (exists) {
-      const text = fs.readFileSync(path.join(catalog.filePath, file), 'utf-8');
-      return (
-        <div className="not-prose">
-          <pre className="expressive-code" data-language="json">
-            <figure className="frame has-title">
-              <figcaption className="header">
-                {title && <span className="title">{title}</span>}
-                {!title && <span className="title">{file}</span>}
-              </figcaption>
-              <pre data-language="js">
-                <code>
-                  <div className="ec-line">
-                    <div className="code">{text}</div>
-                  </div>
-                </code>
-              </pre>
-              <div className="copy">
-                <button title="Copy to clipboard" data-copied="Copied!" data-code={text}>
-                  <div></div>
-                </button>
-              </div>
-            </figure>
-          </pre>
-        </div>
-      );
-    } else {
-      return <div className="italic">Tried to load file from {path.join(catalog.filePath, file)}, but no file can be found</div>;
-    }
-  } catch (error) {
-    console.log('Failed to load file', error);
-    return null;
-  }
-};
-
-export default File;
diff --git a/eventcatalog/src/components/MDX/Flow/Flow.astro b/eventcatalog/src/components/MDX/Flow/Flow.astro
deleted file mode 100644
index 50db3c17b..000000000
--- a/eventcatalog/src/components/MDX/Flow/Flow.astro
+++ /dev/null
@@ -1,67 +0,0 @@
----
-import { getFlows } from '@utils/collections/flows';
-import { getNodesAndEdges } from '@utils/node-graphs/flows-node-graph';
-import Admonition from '@components/MDX/Admonition';
-import NodeGraph from '../NodeGraph/NodeGraph';
-import { getVersionFromCollection } from '@utils/collections/versions';
-import { isVisualiserEnabled } from '@utils/feature';
-
-const { id, version = 'latest', maxHeight, includeKey = true, mode = 'simple', walkthrough = true, search = true } = Astro.props;
-
-// Find the flow for the given id and version
-const flows = await getFlows();
-const flowCollection = getVersionFromCollection(flows, id, version) || [];
-const flow = flowCollection[0];
-
-// const flow = flows.find((flow) => flow.data.id === id && flow.data.version === version);
-
-const { nodes, edges } = await getNodesAndEdges({
-  id: id,
-  version: flow.data.version,
-  mode: mode,
-});
----
-
-{
-  !flow && (
-    <Admonition type="warning">
-      <div>
-        <span class="block font-bold">{`<Flow/>`} failed to load</span>
-        <span class="block">
-          Tried to load flow id: {id} with version {version}. Make sure you have this flow defined in your project.
-        </span>
-      </div>
-    </Admonition>
-  )
-}
-
-<div
-  class="h-[30em] my-6 mb-12 w-full relative border border-gray-200 rounded-md"
-  id={`${id}-portal`}
-  style={{
-    maxHeight: maxHeight ? `${maxHeight}em` : `30em`,
-  }}
->
-</div>
-
-<div>
-  <NodeGraph
-    id={id}
-    nodes={nodes}
-    edges={edges}
-    hrefLabel={'View in visualizer'}
-    href={isVisualiserEnabled() ? `/visualiser/flows/${id}/${version}` : undefined}
-    linkTo={'visualiser'}
-    includeKey={includeKey}
-    footerLabel=`Flow diagram - ${flow.data.name} - v(${flow.data.version})`
-    client:only="react"
-    showFlowWalkthrough={walkthrough}
-    showSearch={search}
-  />
-</div>
-
-<style is:global>
-  .react-flow__attribution {
-    display: none;
-  }
-</style>
diff --git a/eventcatalog/src/components/MDX/Link/Link.astro b/eventcatalog/src/components/MDX/Link/Link.astro
deleted file mode 100644
index bdc140b1d..000000000
--- a/eventcatalog/src/components/MDX/Link/Link.astro
+++ /dev/null
@@ -1,7 +0,0 @@
----
-import { buildUrl } from '@utils/url-builder';
-
-const { href } = Astro.props;
----
-
-<a href={buildUrl(href)} class="text-purple-500 hover:text-purple-700"><slot /></a>
diff --git a/eventcatalog/src/components/MDX/NodeGraph/DownloadButton.tsx b/eventcatalog/src/components/MDX/NodeGraph/DownloadButton.tsx
deleted file mode 100644
index 2f6e07d6d..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/DownloadButton.tsx
+++ /dev/null
@@ -1,62 +0,0 @@
-import { Panel, useReactFlow, getNodesBounds, getViewportForBounds } from '@xyflow/react';
-import { toPng } from 'html-to-image';
-import { DocumentArrowDownIcon } from '@heroicons/react/24/outline';
-
-function downloadImage(dataUrl: string, filename?: string) {
-  const a = document.createElement('a');
-
-  a.setAttribute('download', `${filename || 'eventcatalog'}.png`);
-  a.setAttribute('href', dataUrl);
-  a.click();
-}
-
-const imageWidth = 1024;
-const imageHeight = 768;
-
-function DownloadButton({ filename, addPadding = true }: { filename?: string; addPadding?: boolean }) {
-  const { getNodes } = useReactFlow();
-  const onClick = () => {
-    const nodesBounds = getNodesBounds(getNodes());
-    const width = imageWidth > nodesBounds.width ? imageWidth : nodesBounds.width;
-    const height = imageHeight > nodesBounds.height ? imageHeight : nodesBounds.height;
-    const viewport = getViewportForBounds(nodesBounds, width, height, 0.5, 2, 0);
-
-    // Hide the button
-    // @ts-ignore
-    document.getElementById('download-visual').style.display = 'none';
-    // @ts-ignore
-    document.querySelector('.react-flow__controls').style.display = 'none';
-
-    // @ts-ignore
-    toPng(document.querySelector('.react-flow__viewport'), {
-      backgroundColor: '#f1f1f1',
-      width,
-      height,
-      style: {
-        width,
-        height,
-        transform: `translate(${viewport.x}px, ${viewport.y}px) scale(${viewport.zoom})`,
-      },
-    }).then((dataUrl: string) => {
-      downloadImage(dataUrl, filename);
-      // @ts-ignore
-      document.getElementById('download-visual').style.display = 'block';
-      // @ts-ignore
-      document.querySelector('.react-flow__controls').style.display = 'block';
-    });
-  };
-
-  return (
-    <div id="download-visual">
-      <button
-        className={`hidden md:flex bg-white group download-btn items-center space-x-1 text-[14px] border border-gray-200 px-1 py-0.5 rounded-md hover:bg-gray-100/50 ${addPadding ? 'mt-14' : '-mt-1'}`}
-        onClick={onClick}
-      >
-        <DocumentArrowDownIcon className="w-4 h-4 group-hover:text-primary" />
-        <span className="group-hover:text-primary">Export visual </span>
-      </button>
-    </div>
-  );
-}
-
-export default DownloadButton;
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Edges/AnimatedMessageEdge.tsx b/eventcatalog/src/components/MDX/NodeGraph/Edges/AnimatedMessageEdge.tsx
deleted file mode 100644
index 34dbc1851..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Edges/AnimatedMessageEdge.tsx
+++ /dev/null
@@ -1,97 +0,0 @@
-import { useMemo } from 'react';
-import { BaseEdge, getBezierPath } from '@xyflow/react';
-
-const AnimatedMessageEdge = ({
-  id,
-  sourceX,
-  sourceY,
-  targetX,
-  targetY,
-  sourcePosition,
-  targetPosition,
-  data,
-  label = '',
-  markerEnd,
-  markerStart,
-}: any) => {
-  const [edgePath, labelX, labelY] = getBezierPath({
-    sourceX,
-    sourceY,
-    sourcePosition,
-    targetX,
-    targetY,
-    targetPosition,
-  });
-
-  const messageColor = useMemo(
-    () => (collection: string) => {
-      switch (collection) {
-        case 'events':
-          return 'orange';
-        case 'commands':
-          return 'blue';
-        case 'queries':
-          return 'green';
-        default:
-          return 'gray';
-      }
-    },
-    []
-  );
-
-  const collection = data?.message?.collection;
-  const opacity = data?.opacity ?? 1;
-  const customColor = data?.customColor || messageColor(collection ?? 'default');
-  const warning = data?.warning;
-
-  // For each customColor (string or array of strings), we need to create the animated nodes
-  const customColors = Array.isArray(customColor) ? customColor : [customColor];
-
-  const randomDelay = useMemo(() => Math.random() * 1, []);
-
-  const animatedNodes = customColors.map((color, index) => {
-    // Stagger the animations so multiple colored nodes are visible
-    const delay = randomDelay + index * 0.3;
-    return (
-      <g className={`z-30 ${opacity === 1 ? 'opacity-100' : 'opacity-10'}`} key={`${id}-${color}-${index}`}>
-        <circle key={`${id}-${color}-${index}`} cx="0" cy="0" r="7" fill={color}>
-          <animateMotion dur="2s" repeatCount="indefinite" path={edgePath} rotate="auto" begin={`${delay}s`}>
-            <mpath href={`#${id}`} />
-          </animateMotion>
-        </circle>
-      </g>
-    );
-  });
-
-  // Label can be spit using \n to create multiple lines
-  const lines = String(label ?? '').split('\n');
-
-  return (
-    // @ts-ignore
-    <>
-      <BaseEdge
-        id={id}
-        path={edgePath}
-        markerEnd={markerEnd}
-        markerStart={markerStart}
-        style={warning ? { stroke: 'red', strokeWidth: 1 } : {}}
-      />
-      {/* Circle Icon */}
-      {animatedNodes}
-      {/* <g className={`z-30 ${opacity === 1 ? 'opacity-100' : 'opacity-10'}`}>
-      </g> */}
-      <g>
-        {/* Text element */}
-        <text x={labelX} y={labelY} textAnchor="middle" dominantBaseline="middle" fontSize="10px" pointerEvents="none">
-          {lines.map((line, i) => (
-            <tspan key={i} x={labelX} dy={i === 0 ? 0 : '1.2em'} style={{ fontStyle: i === 0 ? 'normal' : 'italic' }}>
-              {line}
-            </tspan>
-          ))}
-        </text>
-      </g>
-    </>
-  );
-};
-
-export default AnimatedMessageEdge;
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Edges/FlowEdge.tsx b/eventcatalog/src/components/MDX/NodeGraph/Edges/FlowEdge.tsx
deleted file mode 100644
index c51d27bdc..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Edges/FlowEdge.tsx
+++ /dev/null
@@ -1,96 +0,0 @@
-import { useMemo } from 'react';
-import { BaseEdge, EdgeLabelRenderer, getBezierPath, type EdgeProps as XYFlowEdgeProps } from '@xyflow/react';
-
-interface EdgeData {
-  message?: {
-    collection?: string;
-  };
-  opacity?: number;
-  animated?: boolean;
-}
-
-interface CustomEdgeProps extends Omit<XYFlowEdgeProps, 'data'> {
-  data?: EdgeData;
-}
-
-export default function CustomEdge({
-  id,
-  sourceX,
-  sourceY,
-  targetX,
-  targetY,
-  sourcePosition,
-  targetPosition,
-  style = {},
-  markerEnd,
-  label,
-  labelStyle,
-  data,
-}: CustomEdgeProps) {
-  const [edgePath, labelX, labelY] = getBezierPath({
-    sourceX,
-    sourceY,
-    sourcePosition,
-    targetX,
-    targetY,
-    targetPosition,
-  });
-
-  const randomDelay = useMemo(() => Math.random() * 1, []);
-  const collection = data?.message?.collection;
-  const opacity = data?.opacity ?? 1;
-
-  const messageColor = useMemo(
-    () => (collection: string) => {
-      switch (collection) {
-        case 'events':
-          return 'orange';
-        case 'commands':
-          return 'blue';
-        case 'queries':
-          return 'green';
-        default:
-          return 'gray';
-      }
-    },
-    []
-  );
-
-  return (
-    <>
-      <BaseEdge
-        path={edgePath}
-        markerEnd={markerEnd}
-        style={{
-          strokeWidth: 2,
-          stroke: '#fff',
-          ...style,
-        }}
-      />
-      {data?.animated && (
-        <g className={`z-30 ${opacity === 1 ? 'opacity-100' : 'opacity-10'}`}>
-          <circle cx="0" cy="0" r="7" fill={messageColor(collection || 'default')}>
-            <animateMotion dur="2s" repeatCount="indefinite" path={edgePath} rotate="auto" begin={`${randomDelay}s`}>
-              <mpath href={`#${id}`} />
-            </animateMotion>
-          </circle>
-        </g>
-      )}
-      {label && (
-        <EdgeLabelRenderer>
-          <div
-            style={{
-              position: 'absolute',
-              transform: `translate(-50%, -50%) translate(${labelX}px,${labelY}px)`,
-              zIndex: 1000,
-              ...labelStyle,
-            }}
-            className="nodrag nopan max-w-[150px] text-xs bg-white px-2 py-1 rounded border border-gray-200 text-gray-600 font-medium shadow-sm"
-          >
-            {label}
-          </div>
-        </EdgeLabelRenderer>
-      )}
-    </>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Edges/MultilineEdgeLabel.tsx b/eventcatalog/src/components/MDX/NodeGraph/Edges/MultilineEdgeLabel.tsx
deleted file mode 100644
index 71d2ad2c9..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Edges/MultilineEdgeLabel.tsx
+++ /dev/null
@@ -1,52 +0,0 @@
-import { type EdgeProps, getBezierPath } from '@xyflow/react';
-
-export default function MultilineEdgeLabel(props: EdgeProps) {
-  const {
-    id,
-    sourceX,
-    sourceY,
-    targetX,
-    targetY,
-    sourcePosition,
-    targetPosition,
-    label,
-    markerStart, // <-- forward these
-    markerEnd,
-    style,
-    selected,
-  } = props;
-
-  const [edgePath, labelX, labelY] = getBezierPath({
-    sourceX,
-    sourceY,
-    targetX,
-    targetY,
-    sourcePosition,
-    targetPosition,
-  });
-
-  const lines = String(label ?? '').split('\n');
-
-  return (
-    <>
-      <path
-        id={id}
-        d={edgePath}
-        className={`react-flow__edge-path${selected ? ' selected' : ''}`}
-        markerStart={markerStart}
-        markerEnd={markerEnd}
-        style={style}
-      />
-
-      {/* Optional: bigger hitbox for hover/selection */}
-
-      <text x={labelX} y={labelY} textAnchor="middle" dominantBaseline="middle" fontSize="10px" pointerEvents="none">
-        {lines.map((line, i) => (
-          <tspan key={i} x={labelX} dy={i === 0 ? 0 : '1.2em'} style={{ fontStyle: i === 0 ? 'normal' : 'italic' }}>
-            {line}
-          </tspan>
-        ))}
-      </text>
-    </>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/NodeGraph.astro b/eventcatalog/src/components/MDX/NodeGraph/NodeGraph.astro
deleted file mode 100644
index d87c26d2e..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/NodeGraph.astro
+++ /dev/null
@@ -1,162 +0,0 @@
----
-import NodeGraphNew from './NodeGraph';
-import { getNodesAndEdges as getNodesAndEdgesForService } from '@utils/node-graphs/services-node-graph';
-import {
-  getNodesAndEdgesForCommands,
-  getNodesAndEdgesForEvents,
-  getNodesAndEdgesForQueries,
-} from '@utils/node-graphs/message-node-graph';
-import {
-  getNodesAndEdges as getNodesAndEdgesForDomain,
-  getNodesAndEdgesForDomainContextMap,
-} from '@utils/node-graphs/domains-node-graph';
-import { getNodesAndEdges as getNodesAndEdgesForDomainEntityMap } from '@utils/node-graphs/domain-entity-map';
-import { getDomainsCanvasData } from '@utils/node-graphs/domains-canvas';
-import { getNodesAndEdges as getNodesAndEdgesForFlows } from '@utils/node-graphs/flows-node-graph';
-import { buildUrl } from '@utils/url-builder';
-import { getVersionFromCollection } from '@utils/collections/versions';
-import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
-import { getNodesAndEdges as getNodesAndEdgesForContainer } from '@utils/node-graphs/container-node-graph';
-import config from '@config';
-
-interface Props {
-  id: string;
-  collection: string;
-  title?: string;
-  version: string;
-  mode: 'full' | 'simple';
-  linkTo?: 'docs' | 'visualiser';
-  href?: {
-    label: string;
-    url: string;
-  };
-  linksToVisualiser?: boolean;
-  showSearch?: boolean;
-  showLegend?: boolean;
-  zoomOnScroll?: boolean;
-}
-
-const {
-  id,
-  collection,
-  title,
-  mode = 'simple',
-  linkTo = 'docs',
-  version,
-  href,
-  linksToVisualiser,
-  showSearch = true,
-  showLegend = true,
-  zoomOnScroll = false,
-} = Astro.props;
-
-let nodes = [],
-  edges = [];
-
-const getNodesAndEdgesFunctions = {
-  services: getNodesAndEdgesForService,
-  events: getNodesAndEdgesForEvents,
-  commands: getNodesAndEdgesForCommands,
-  queries: getNodesAndEdgesForQueries,
-  domains: getNodesAndEdgesForDomain,
-  flows: getNodesAndEdgesForFlows,
-  containers: getNodesAndEdgesForContainer,
-};
-
-let links: { label: string; url: string }[] = [];
-
-if (collection in getNodesAndEdgesFunctions) {
-  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesFunctions[
-    collection as keyof typeof getNodesAndEdgesFunctions
-  ]({
-    id,
-    version,
-    mode,
-    channelRenderMode: config.visualiser?.channels?.renderMode === 'single' ? 'single' : 'flat',
-  });
-
-  nodes = fetchedNodes;
-  edges = fetchedEdges;
-
-  if (mode === 'full') {
-    // Try and get the list of versions for the rendered item
-    try {
-      const allItems = await pageDataLoader[collection as keyof typeof pageDataLoader]();
-      const versions = getVersionFromCollection(allItems, id, version);
-
-      const item = versions[0];
-      const listOfVersions = item.data.versions || [];
-
-      // Order by version
-      listOfVersions.sort((a, b) => b.localeCompare(a));
-
-      if (listOfVersions.length > 1) {
-        links = listOfVersions.map((version) => ({
-          label: `${item.data.name} v${version}`,
-          url: buildUrl(`/visualiser/${collection}/${id}/${version}`),
-          selected: version === version,
-        }));
-      }
-    } catch (error) {
-      links = [];
-    }
-  }
-}
-
-if (collection === 'domain-context-map') {
-  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForDomainContextMap({});
-  nodes = fetchedNodes;
-  edges = fetchedEdges;
-}
-
-if (collection === 'domains-canvas') {
-  const { domainNodes, messageNodes, edges: fetchedEdges } = await getDomainsCanvasData();
-  nodes = [...domainNodes, ...messageNodes];
-  edges = fetchedEdges;
-}
-
-if (collection === 'domains-entities') {
-  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForDomainEntityMap({
-    id,
-    version,
-  });
-  nodes = fetchedNodes;
-  edges = fetchedEdges;
-}
-
-if (collection === 'services-containers') {
-  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForService({
-    id,
-    version,
-    renderMessages: false,
-    mode: 'full',
-  });
-  nodes = fetchedNodes;
-  edges = fetchedEdges;
-}
----
-
-<div>
-  <NodeGraphNew
-    id={id}
-    nodes={nodes}
-    edges={edges}
-    title={title}
-    hrefLabel={href?.label}
-    href={href?.url}
-    linkTo={linkTo}
-    client:only="react"
-    linksToVisualiser={linksToVisualiser}
-    links={links}
-    mode={mode}
-    showSearch={showSearch}
-    includeKey={showLegend}
-    zoomOnScroll={zoomOnScroll}
-  />
-</div>
-
-<style is:global>
-  .react-flow__attribution {
-    display: none;
-  }
-</style>
diff --git a/eventcatalog/src/components/MDX/NodeGraph/NodeGraph.tsx b/eventcatalog/src/components/MDX/NodeGraph/NodeGraph.tsx
deleted file mode 100644
index 337a0b589..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/NodeGraph.tsx
+++ /dev/null
@@ -1,866 +0,0 @@
-import { useEffect, useMemo, useState, useCallback, useRef } from 'react';
-import { createPortal } from 'react-dom';
-import {
-  ReactFlow,
-  Background,
-  ConnectionLineType,
-  Controls,
-  Panel,
-  ReactFlowProvider,
-  useNodesState,
-  useEdgesState,
-  type Edge,
-  type Node,
-  useReactFlow,
-  getNodesBounds,
-  getViewportForBounds,
-  type NodeTypes,
-} from '@xyflow/react';
-import '@xyflow/react/dist/style.css';
-import { ExternalLink, HistoryIcon } from 'lucide-react';
-import { toPng } from 'html-to-image';
-import { DocumentArrowDownIcon } from '@heroicons/react/24/outline';
-// Nodes and edges
-import ServiceNode from './Nodes/Service';
-import FlowNode from './Nodes/Flow';
-import EventNode from './Nodes/Event';
-import EntityNode from './Nodes/Entity';
-import QueryNode from './Nodes/Query';
-import UserNode from './Nodes/User';
-import StepNode from './Nodes/Step';
-import CommandNode from './Nodes/Command';
-import ExternalSystemNode from './Nodes/ExternalSystem';
-import DomainNode from './Nodes/Domain';
-import AnimatedMessageEdge from './Edges/AnimatedMessageEdge';
-import MultilineEdgeLabel from './Edges/MultilineEdgeLabel';
-import FlowEdge from './Edges/FlowEdge';
-import CustomNode from './Nodes/Custom';
-import DataNode from './Nodes/Data';
-import ViewNode from './Nodes/View';
-import ActorNode from './Nodes/Actor';
-import ExternalSystemNode2 from './Nodes/ExternalSystem2';
-import { Note as NoteNode } from '@eventcatalog/visualizer';
-
-import type { CollectionEntry } from 'astro:content';
-import { navigate } from 'astro:transitions/client';
-import type { CollectionTypes } from '@types';
-import { buildUrl } from '@utils/url-builder';
-import ChannelNode from './Nodes/Channel';
-import { CogIcon } from '@heroicons/react/20/solid';
-import { useEventCatalogVisualiser } from 'src/hooks/eventcatalog-visualizer';
-import VisualiserSearch, { type VisualiserSearchRef } from './VisualiserSearch';
-import StepWalkthrough from './StepWalkthrough';
-import StudioModal from './StudioModal';
-interface Props {
-  nodes: any;
-  edges: any;
-  title?: string;
-  subtitle?: string;
-  includeBackground?: boolean;
-  includeControls?: boolean;
-  linkTo: 'docs' | 'visualiser';
-  includeKey?: boolean;
-  linksToVisualiser?: boolean;
-  links?: { label: string; url: string }[];
-  mode?: 'full' | 'simple';
-  showFlowWalkthrough?: boolean;
-  showSearch?: boolean;
-  zoomOnScroll?: boolean;
-  designId?: string;
-  isStudioModalOpen?: boolean;
-  setIsStudioModalOpen?: (isOpen: boolean) => void;
-}
-
-const getVisualiserUrlForCollection = (collectionItem: CollectionEntry<CollectionTypes>) => {
-  return buildUrl(`/visualiser/${collectionItem.collection}/${collectionItem.data.id}/${collectionItem.data.version}`);
-};
-
-const NodeGraphBuilder = ({
-  nodes: initialNodes,
-  edges: initialEdges,
-  title,
-  includeBackground = true,
-  linkTo = 'docs',
-  includeKey = true,
-  linksToVisualiser = false,
-  links = [],
-  mode = 'full',
-  showFlowWalkthrough = true,
-  showSearch = true,
-  zoomOnScroll = false,
-  isStudioModalOpen,
-  setIsStudioModalOpen = () => {},
-}: Props) => {
-  const nodeTypes = useMemo(
-    () =>
-      ({
-        service: ServiceNode,
-        services: ServiceNode,
-        flow: FlowNode,
-        flows: FlowNode,
-        event: EventNode,
-        events: EventNode,
-        channel: ChannelNode,
-        channels: ChannelNode,
-        query: QueryNode,
-        queries: QueryNode,
-        command: CommandNode,
-        commands: CommandNode,
-        domain: DomainNode,
-        domains: DomainNode,
-        step: StepNode,
-        user: UserNode,
-        custom: CustomNode,
-        externalSystem: ExternalSystemNode,
-        'external-system': ExternalSystemNode2,
-        entity: EntityNode,
-        entities: EntityNode,
-        data: DataNode,
-        view: ViewNode,
-        actor: ActorNode,
-        note: (props: any) => <NoteNode {...props} readOnly={true} />,
-      }) as unknown as NodeTypes,
-    []
-  );
-  const edgeTypes = useMemo(
-    () => ({
-      animated: AnimatedMessageEdge,
-      multiline: MultilineEdgeLabel,
-      'flow-edge': FlowEdge,
-    }),
-    []
-  );
-  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
-  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);
-  const [isSettingsOpen, setIsSettingsOpen] = useState(false);
-  const [animateMessages, setAnimateMessages] = useState(false);
-  const [activeStepIndex, setActiveStepIndex] = useState<number | null>(null);
-  // const [isStudioModalOpen, setIsStudioModalOpen] = useState(false);
-
-  // Check if there are channels to determine if we need the visualizer functionality
-  const hasChannels = useMemo(() => initialNodes.some((node: any) => node.type === 'channels'), [initialNodes]);
-  const { hideChannels, toggleChannelsVisibility } = useEventCatalogVisualiser({
-    nodes,
-    edges,
-    setNodes,
-    setEdges,
-    skipProcessing: !hasChannels, // Pass flag to skip processing when no channels
-  });
-  const { fitView, getNodes, toObject } = useReactFlow();
-  const searchRef = useRef<VisualiserSearchRef>(null);
-  const reactFlowWrapperRef = useRef<HTMLDivElement>(null);
-  const scrollableContainerRef = useRef<HTMLElement | null>(null);
-
-  const resetNodesAndEdges = useCallback(() => {
-    setNodes((nds) =>
-      nds.map((node) => {
-        node.style = { ...node.style, opacity: 1 };
-        return { ...node, animated: animateMessages };
-      })
-    );
-    setEdges((eds) =>
-      eds.map((edge) => {
-        edge.style = { ...edge.style, opacity: 1 };
-        edge.labelStyle = { ...edge.labelStyle, opacity: 1 };
-        return { ...edge, data: { ...edge.data, opacity: 1, animated: animateMessages }, animated: animateMessages };
-      })
-    );
-  }, [setNodes, setEdges, animateMessages]);
-
-  const handleNodeClick = useCallback(
-    (_: any, node: Node) => {
-      if (linksToVisualiser) {
-        if (node.type === 'events' || node.type === 'commands') {
-          navigate(getVisualiserUrlForCollection(node.data.message as CollectionEntry<CollectionTypes>));
-        }
-        if (node.type === 'services') {
-          navigate(getVisualiserUrlForCollection(node.data.service as CollectionEntry<'services'>));
-        }
-        return;
-      }
-
-      resetNodesAndEdges();
-
-      const connectedNodeIds = new Set<string>();
-      connectedNodeIds.add(node.id);
-
-      const updatedEdges = edges.map((edge) => {
-        if (edge.source === node.id || edge.target === node.id) {
-          connectedNodeIds.add(edge.source);
-          connectedNodeIds.add(edge.target);
-          return {
-            ...edge,
-            data: { ...edge.data, opacity: 1, animated: animateMessages },
-            style: { ...edge.style, opacity: 1 },
-            labelStyle: { ...edge.labelStyle, opacity: 1 },
-            animated: true,
-          };
-        }
-        return {
-          ...edge,
-          data: { ...edge.data, opacity: 0.1, animated: animateMessages },
-          style: { ...edge.style, opacity: 0.1 },
-          labelStyle: { ...edge.labelStyle, opacity: 0.1 },
-          animated: animateMessages,
-        };
-      });
-
-      const updatedNodes = nodes.map((n) => {
-        if (connectedNodeIds.has(n.id)) {
-          return { ...n, style: { ...n.style, opacity: 1 } };
-        }
-        return { ...n, style: { ...n.style, opacity: 0.1 } };
-      });
-
-      setNodes(updatedNodes);
-      setEdges(updatedEdges);
-
-      // Fit the clicked node and its connected nodes into view
-      fitView({
-        padding: 0.2,
-        duration: 800,
-        nodes: updatedNodes.filter((n) => connectedNodeIds.has(n.id)),
-      });
-    },
-    [nodes, edges, setNodes, setEdges, resetNodesAndEdges, fitView]
-  );
-
-  const toggleAnimateMessages = () => {
-    setAnimateMessages(!animateMessages);
-    localStorage.setItem('EventCatalog:animateMessages', JSON.stringify(!animateMessages));
-  };
-
-  // animate messages, between views
-  useEffect(() => {
-    const storedAnimateMessages = localStorage.getItem('EventCatalog:animateMessages');
-    if (storedAnimateMessages !== null) {
-      setAnimateMessages(storedAnimateMessages === 'true');
-    }
-  }, []);
-
-  useEffect(() => {
-    setEdges((eds) =>
-      eds.map((edge) => ({
-        ...edge,
-        animated: animateMessages,
-        type: edge.type === 'flow-edge' || edge.type === 'multiline' ? edge.type : animateMessages ? 'animated' : 'default',
-        data: { ...edge.data, animateMessages, animated: animateMessages },
-      }))
-    );
-  }, [animateMessages]);
-
-  useEffect(() => {
-    setTimeout(() => {
-      fitView({ duration: 800 });
-    }, 150);
-  }, []);
-
-  // Handle scroll wheel events to forward to page when no modifier keys are pressed
-  // Only when zoomOnScroll is disabled
-  // This is a fix for when we embed node graphs into pages, and users are scrolling the documentation pages
-  // We dont want REACT FLOW to swallow the scroll events, so we forward them to the parent page
-  useEffect(() => {
-    // Skip scroll handling if zoomOnScroll is enabled
-    if (zoomOnScroll) return;
-
-    // Cache the scrollable container on mount (expensive operation done once)
-    const findScrollableContainer = (): HTMLElement | null => {
-      // Try specific known selectors first (fast)
-      const selectors = [
-        '.docs-layout .overflow-y-auto',
-        '.overflow-y-auto',
-        '[style*="overflow-y:auto"]',
-        '[style*="overflow-y: auto"]',
-      ];
-
-      for (const selector of selectors) {
-        const element = document.querySelector(selector) as HTMLElement;
-        if (element) return element;
-      }
-
-      return null;
-    };
-
-    // Find and cache the scrollable container once
-    if (!scrollableContainerRef.current) {
-      scrollableContainerRef.current = findScrollableContainer();
-    }
-
-    const handleWheel = (event: WheelEvent) => {
-      // Only forward scroll if no modifier keys are pressed
-      if (!event.ctrlKey && !event.shiftKey && !event.metaKey) {
-        event.preventDefault();
-
-        const scrollableContainer = scrollableContainerRef.current;
-
-        if (scrollableContainer) {
-          scrollableContainer.scrollBy({
-            top: event.deltaY,
-            left: event.deltaX,
-            behavior: 'instant',
-          });
-        } else {
-          // Fallback to window scroll
-          window.scrollBy({
-            top: event.deltaY,
-            left: event.deltaX,
-            behavior: 'instant',
-          });
-        }
-      }
-    };
-
-    const wrapper = reactFlowWrapperRef.current;
-    if (wrapper) {
-      wrapper.addEventListener('wheel', handleWheel, { passive: false });
-      return () => {
-        wrapper.removeEventListener('wheel', handleWheel);
-      };
-    }
-  }, [zoomOnScroll]);
-
-  const handlePaneClick = useCallback(() => {
-    setIsSettingsOpen(false);
-    searchRef.current?.hideSuggestions();
-    resetNodesAndEdges();
-    fitView({ duration: 800 });
-  }, [resetNodesAndEdges, fitView]);
-
-  const handleNodeSelect = useCallback(
-    (node: Node) => {
-      handleNodeClick(null, node);
-    },
-    [handleNodeClick]
-  );
-
-  const handleSearchClear = useCallback(() => {
-    resetNodesAndEdges();
-    fitView({ duration: 800 });
-  }, [resetNodesAndEdges, fitView]);
-
-  const downloadImage = useCallback((dataUrl: string, filename?: string) => {
-    const a = document.createElement('a');
-    a.setAttribute('download', `${filename || 'eventcatalog'}.png`);
-    a.setAttribute('href', dataUrl);
-    a.click();
-  }, []);
-
-  const openStudioModal = () => {
-    setIsStudioModalOpen(true);
-  };
-
-  const handleExportVisual = useCallback(() => {
-    const imageWidth = 1024;
-    const imageHeight = 768;
-    const nodesBounds = getNodesBounds(getNodes());
-    const width = imageWidth > nodesBounds.width ? imageWidth : nodesBounds.width;
-    const height = imageHeight > nodesBounds.height ? imageHeight : nodesBounds.height;
-    const viewport = getViewportForBounds(nodesBounds, width, height, 0.5, 2, 0);
-
-    // Hide settings panel and controls during export
-    setIsSettingsOpen(false);
-    const controls = document.querySelector('.react-flow__controls') as HTMLElement;
-    if (controls) controls.style.display = 'none';
-
-    toPng(document.querySelector('.react-flow__viewport') as HTMLElement, {
-      backgroundColor: '#f1f1f1',
-      width,
-      height,
-      style: {
-        width: width.toString(),
-        height: height.toString(),
-        transform: `translate(${viewport.x}px, ${viewport.y}px) scale(${viewport.zoom})`,
-      },
-    }).then((dataUrl: string) => {
-      downloadImage(dataUrl, title);
-      // Restore controls
-      if (controls) controls.style.display = 'block';
-    });
-  }, [getNodes, downloadImage, title]);
-
-  const handleLegendClick = useCallback(
-    (collectionType: string, groupId?: string) => {
-      const updatedNodes = nodes.map((node: Node<any>) => {
-        // Check if the groupId is set first
-        if (groupId && node.data.group && node.data.group?.id === groupId) {
-          return { ...node, style: { ...node.style, opacity: 1 } };
-        } else {
-          if (node.type === collectionType) {
-            return { ...node, style: { ...node.style, opacity: 1 } };
-          }
-        }
-        return { ...node, style: { ...node.style, opacity: 0.1 } };
-      });
-
-      const updatedEdges = edges.map((edge) => {
-        return {
-          ...edge,
-          data: { ...edge.data, opacity: 0.1 },
-          style: { ...edge.style, opacity: 0.1 },
-          labelStyle: { ...edge.labelStyle, opacity: 0.1 },
-          animated: animateMessages,
-        };
-      });
-
-      setNodes(updatedNodes);
-      setEdges(updatedEdges);
-
-      fitView({
-        padding: 0.2,
-        duration: 800,
-        nodes: updatedNodes.filter((node) => node.type === collectionType),
-      });
-    },
-    [nodes, edges, setNodes, setEdges, fitView]
-  );
-
-  const getNodesByCollectionWithColors = useCallback((nodes: Node<any>[]) => {
-    const colorClasses = {
-      events: 'bg-orange-600',
-      services: 'bg-pink-600',
-      flows: 'bg-teal-600',
-      commands: 'bg-blue-600',
-      queries: 'bg-green-600',
-      channels: 'bg-gray-600',
-      externalSystem: 'bg-pink-600',
-      actor: 'bg-yellow-500',
-      step: 'bg-gray-700',
-      data: 'bg-blue-600',
-    };
-
-    let legendForDomains: { [key: string]: { count: number; colorClass: string; groupId: string } } = {};
-
-    // Find any groups
-    const domainGroups = [
-      ...new Set(
-        nodes.filter((node) => node.data.group && node.data.group?.type === 'Domain').map((node) => node.data.group?.id)
-      ),
-    ];
-
-    domainGroups.forEach((groupId) => {
-      const group = nodes.filter((node) => node.data.group && node.data.group?.id === groupId);
-      legendForDomains[`${groupId} (Domain)`] = { count: group.length, colorClass: 'bg-yellow-600', groupId };
-    });
-
-    const legendForNodes = nodes.reduce(
-      (acc: { [key: string]: { count: number; colorClass: string; groupId?: string } }, node) => {
-        const collection = node.type;
-        if (collection) {
-          if (acc[collection]) {
-            acc[collection].count += 1;
-          } else {
-            acc[collection] = { count: 1, colorClass: colorClasses[collection as keyof typeof colorClasses] || 'bg-black' };
-          }
-        }
-        return acc;
-      },
-      {}
-    );
-
-    return { ...legendForDomains, ...legendForNodes };
-  }, []);
-
-  const legend = getNodesByCollectionWithColors(nodes);
-
-  const handleStepChange = useCallback(
-    (nodeId: string | null, highlightPaths?: string[], shouldZoomOut?: boolean) => {
-      if (nodeId === null) {
-        // Reset all nodes and edges
-        resetNodesAndEdges();
-        setActiveStepIndex(null);
-
-        // If shouldZoomOut is true, fit the entire view
-        if (shouldZoomOut) {
-          setTimeout(() => {
-            fitView({ duration: 800, padding: 0.1 });
-          }, 100);
-        }
-        return;
-      }
-
-      const activeNode = nodes.find((node: Node) => node.id === nodeId);
-      if (!activeNode) return;
-
-      // Create set of highlighted nodes and edges
-      const highlightedNodeIds = new Set<string>();
-      const highlightedEdgeIds = new Set<string>();
-
-      // Add current node
-      highlightedNodeIds.add(activeNode.id);
-
-      // Add incoming edges and their source nodes
-      edges.forEach((edge: Edge) => {
-        if (edge.target === activeNode.id) {
-          highlightedEdgeIds.add(edge.id);
-          highlightedNodeIds.add(edge.source);
-        }
-      });
-
-      // Add outgoing edges
-      if (highlightPaths) {
-        // Highlight all possible paths when at a fork
-        highlightPaths.forEach((pathId) => {
-          const [source, target] = pathId.split('-');
-          edges.forEach((edge: Edge) => {
-            if (edge.source === source && edge.target === target) {
-              highlightedEdgeIds.add(edge.id);
-              highlightedNodeIds.add(edge.target);
-            }
-          });
-        });
-      } else {
-        // Highlight all outgoing edges normally
-        edges.forEach((edge: Edge) => {
-          if (edge.source === activeNode.id) {
-            highlightedEdgeIds.add(edge.id);
-            highlightedNodeIds.add(edge.target);
-          }
-        });
-      }
-
-      // Update nodes
-      const updatedNodes = nodes.map((node: Node) => {
-        if (highlightedNodeIds.has(node.id)) {
-          return { ...node, style: { ...node.style, opacity: 1 } };
-        }
-        return { ...node, style: { ...node.style, opacity: 0.2 } };
-      });
-
-      // Update edges
-      const updatedEdges = edges.map((edge: Edge) => {
-        if (highlightedEdgeIds.has(edge.id)) {
-          return {
-            ...edge,
-            data: { ...edge.data, opacity: 1, animated: true },
-            style: { ...edge.style, opacity: 1, strokeWidth: 3 },
-            labelStyle: { ...edge.labelStyle, opacity: 1 },
-            animated: true,
-          };
-        }
-        return {
-          ...edge,
-          data: { ...edge.data, opacity: 0.2, animated: false },
-          style: { ...edge.style, opacity: 0.2, strokeWidth: 2 },
-          labelStyle: { ...edge.labelStyle, opacity: 0.2 },
-          animated: false,
-        };
-      });
-
-      setNodes(updatedNodes);
-      setEdges(updatedEdges);
-
-      // Fit view to active node
-      fitView({
-        padding: 0.4,
-        duration: 800,
-        nodes: [activeNode],
-      });
-    },
-    [nodes, edges, setNodes, setEdges, resetNodesAndEdges, fitView]
-  );
-
-  // Check if this is a flow visualization by checking if edges use flow-edge type
-  const isFlowVisualization = edges.some((edge: Edge) => edge.type === 'flow-edge');
-
-  return (
-    <div ref={reactFlowWrapperRef} className="w-full h-full">
-      <ReactFlow
-        nodeTypes={nodeTypes}
-        edgeTypes={edgeTypes}
-        minZoom={0.07}
-        nodes={nodes}
-        edges={edges}
-        fitView
-        onNodesChange={onNodesChange}
-        onEdgesChange={onEdgesChange}
-        connectionLineType={ConnectionLineType.SmoothStep}
-        nodeOrigin={[0.1, 0.1]}
-        onNodeClick={handleNodeClick}
-        onPaneClick={handlePaneClick}
-        zoomOnScroll={zoomOnScroll}
-        className="relative"
-      >
-        <Panel position="top-center" className="w-full pr-6 ">
-          <div className="flex space-x-2 justify-between items-center">
-            <div className="flex space-x-2 ml-4">
-              <div>
-                <button
-                  onClick={() => setIsSettingsOpen(!isSettingsOpen)}
-                  className="py-2.5 px-3 bg-white rounded-md shadow-md hover:bg-purple-100 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-purple-500"
-                  aria-label="Open settings"
-                >
-                  <CogIcon className="h-5 w-5 text-gray-600" />
-                </button>
-              </div>
-
-              {title && (
-                <span className="block shadow-sm bg-white text-xl z-10 text-black px-4 py-1.5 border-gray-200 rounded-md border opacity-80">
-                  {title}
-                </span>
-              )}
-            </div>
-            {mode === 'full' && showSearch && (
-              <div className="flex justify-end space-x-2 w-96">
-                <VisualiserSearch ref={searchRef} nodes={nodes} onNodeSelect={handleNodeSelect} onClear={handleSearchClear} />
-              </div>
-            )}
-          </div>
-          {links.length > 0 && (
-            <div className="flex justify-end mt-3">
-              <div className="relative flex items-center -mt-1">
-                <span className="absolute left-2 pointer-events-none flex items-center h-full">
-                  <HistoryIcon className="h-4 w-4 text-gray-600" />
-                </span>
-                <select
-                  value={links.find((link) => window.location.href.includes(link.url))?.url || links[0].url}
-                  onChange={(e) => navigate(e.target.value)}
-                  className="appearance-none pl-7 pr-6 py-0 text-[14px] bg-white rounded-md border border-gray-200 hover:bg-gray-100/50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-purple-500"
-                  style={{ minWidth: 120, height: '26px' }}
-                >
-                  {links.map((link) => (
-                    <option key={link.url} value={link.url}>
-                      {link.label}
-                    </option>
-                  ))}
-                </select>
-                <span className="absolute right-2 pointer-events-none">
-                  <svg className="w-4 h-4 text-gray-400" fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24">
-                    <path strokeLinecap="round" strokeLinejoin="round" d="M19 9l-7 7-7-7" />
-                  </svg>
-                </span>
-              </div>
-            </div>
-          )}
-        </Panel>
-
-        {isSettingsOpen && (
-          <div className="absolute top-[68px] left-5 w-72 p-4 bg-white rounded-lg shadow-lg z-30 border border-gray-200">
-            <h3 className="text-lg font-semibold mb-4">Visualizer Settings</h3>
-            <div className="space-y-4 ">
-              <div>
-                <div className="flex items-center justify-between">
-                  <label htmlFor="message-animation-toggle" className="text-sm font-medium text-gray-700">
-                    Simulate Messages
-                  </label>
-                  <button
-                    id="message-animation-toggle"
-                    onClick={toggleAnimateMessages}
-                    className={`${
-                      animateMessages ? 'bg-purple-600' : 'bg-gray-200'
-                    } relative inline-flex h-6 w-11 items-center rounded-full transition-colors focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2`}
-                  >
-                    <span
-                      className={`${
-                        animateMessages ? 'translate-x-6' : 'translate-x-1'
-                      } inline-block h-4 w-4 transform rounded-full bg-white transition-transform`}
-                    />
-                  </button>
-                </div>
-                <p className="text-[10px] text-gray-500">Animate events, queries and commands.</p>
-              </div>
-              {hasChannels && (
-                <div>
-                  <div className="flex items-center justify-between">
-                    <label htmlFor="hide-channels-toggle" className="text-sm font-medium text-gray-700">
-                      Hide Channels
-                    </label>
-                    <button
-                      id="hide-channels-toggle"
-                      onClick={toggleChannelsVisibility}
-                      className={`${
-                        hideChannels ? 'bg-purple-600' : 'bg-gray-200'
-                      } relative inline-flex h-6 w-11 items-center rounded-full transition-colors focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2`}
-                    >
-                      <span
-                        className={`${
-                          hideChannels ? 'translate-x-6' : 'translate-x-1'
-                        } inline-block h-4 w-4 transform rounded-full bg-white transition-transform`}
-                      />
-                    </button>
-                  </div>
-                  <p className="text-[10px] text-gray-500">Show or hide channels in the visualizer.</p>
-                </div>
-              )}
-              <div className="pt-4 border-t border-gray-200 space-y-2">
-                <button
-                  onClick={openStudioModal}
-                  className="w-full flex items-center justify-center space-x-2 px-4 py-2 bg-black hover:bg-gray-800 text-white text-sm font-medium rounded-md focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2 transition-colors"
-                >
-                  <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                    <path
-                      strokeLinecap="round"
-                      strokeLinejoin="round"
-                      strokeWidth="2"
-                      d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"
-                    />
-                  </svg>
-                  <span>Open in EventCatalog Studio</span>
-                </button>
-                <button
-                  onClick={handleExportVisual}
-                  className="w-full flex items-center justify-center border border-gray-200 space-x-2 px-4 py-2 bg-white text-gray-800 text-sm font-medium rounded-md hover:bg-gray-100 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2"
-                >
-                  <DocumentArrowDownIcon className="w-4 h-4" />
-                  <span>Export as png</span>
-                </button>
-              </div>
-            </div>
-          </div>
-        )}
-        {includeBackground && <Background color="#bbb" gap={16} />}
-        {includeBackground && <Controls />}
-        {isFlowVisualization && showFlowWalkthrough && (
-          <Panel position="bottom-left">
-            <StepWalkthrough
-              nodes={nodes}
-              edges={edges}
-              isFlowVisualization={isFlowVisualization}
-              onStepChange={handleStepChange}
-              mode={mode}
-            />
-          </Panel>
-        )}
-        {includeKey && (
-          <Panel position="bottom-right">
-            <div className=" bg-white font-light px-4 text-[12px] shadow-md py-1 rounded-md">
-              <ul className="m-0 p-0 ">
-                {Object.entries(legend).map(([key, { count, colorClass, groupId }]) => (
-                  <li
-                    key={key}
-                    className="flex space-x-2 items-center text-[10px] cursor-pointer hover:text-purple-600 hover:underline"
-                    onClick={() => handleLegendClick(key, groupId)}
-                  >
-                    <span className={`w-2 h-2 block ${colorClass}`} />
-                    <span className="block capitalize">
-                      {key} ({count})
-                    </span>
-                  </li>
-                ))}
-              </ul>
-            </div>
-          </Panel>
-        )}
-      </ReactFlow>
-      <StudioModal isOpen={isStudioModalOpen || false} onClose={() => setIsStudioModalOpen(false)} />
-    </div>
-  );
-};
-
-interface NodeGraphProps {
-  id: string;
-  title?: string;
-  href?: string;
-  hrefLabel?: string;
-  nodes: Node[];
-  edges: Edge[];
-  linkTo: 'docs' | 'visualiser';
-  includeKey?: boolean;
-  footerLabel?: string;
-  linksToVisualiser?: boolean;
-  links?: { label: string; url: string }[];
-  mode?: 'full' | 'simple';
-  portalId?: string;
-  showFlowWalkthrough?: boolean;
-  showSearch?: boolean;
-  zoomOnScroll?: boolean;
-  designId?: string;
-}
-
-const NodeGraph = ({
-  id,
-  nodes,
-  edges,
-  title,
-  href,
-  linkTo = 'docs',
-  hrefLabel = 'Open in visualizer',
-  includeKey = true,
-  footerLabel,
-  linksToVisualiser = false,
-  links = [],
-  mode = 'full',
-  portalId,
-  showFlowWalkthrough = true,
-  showSearch = true,
-  zoomOnScroll = false,
-  designId,
-}: NodeGraphProps) => {
-  const [elem, setElem] = useState(null);
-  const [showFooter, setShowFooter] = useState(true);
-  const [isStudioModalOpen, setIsStudioModalOpen] = useState(false);
-
-  const openStudioModal = useCallback(() => {
-    setIsStudioModalOpen(true);
-  }, []);
-
-  const containerToRenderInto = portalId || `${id}-portal`;
-
-  useEffect(() => {
-    // @ts-ignore
-    setElem(document.getElementById(containerToRenderInto));
-  }, []);
-
-  useEffect(() => {
-    const urlParams = new URLSearchParams(window.location.search);
-    const embed = urlParams.get('embed');
-    if (embed === 'true') {
-      setShowFooter(false);
-    }
-  }, []);
-
-  if (!elem) return null;
-
-  return (
-    <div>
-      {createPortal(
-        <ReactFlowProvider>
-          <NodeGraphBuilder
-            edges={edges}
-            nodes={nodes}
-            title={title}
-            linkTo={linkTo}
-            includeKey={includeKey}
-            linksToVisualiser={linksToVisualiser}
-            links={links}
-            mode={mode}
-            showFlowWalkthrough={showFlowWalkthrough}
-            showSearch={showSearch}
-            zoomOnScroll={zoomOnScroll}
-            designId={designId || id}
-            isStudioModalOpen={isStudioModalOpen}
-            setIsStudioModalOpen={setIsStudioModalOpen}
-          />
-
-          {showFooter && (
-            <div className="flex justify-between" id="visualiser-footer">
-              {footerLabel && (
-                <div className="py-2 w-full text-left ">
-                  <span className=" text-sm no-underline py-2 text-gray-500">{footerLabel}</span>
-                </div>
-              )}
-
-              {href && (
-                <div className="py-2 w-full text-right flex justify-between">
-                  {/* <span className="text-sm text-gray-500 italic">Right click a node to access documentation</span> */}
-                  <button
-                    onClick={openStudioModal}
-                    className=" text-sm underline text-gray-800 hover:text-primary flex items-center space-x-1"
-                  >
-                    <span>Open in EventCatalog Studio</span>
-                    <ExternalLink className="w-3 h-3" />
-                  </button>
-                  <a className=" text-sm underline text-gray-800 hover:text-primary" href={href}>
-                    {hrefLabel} &rarr;
-                  </a>
-                </div>
-              )}
-            </div>
-          )}
-        </ReactFlowProvider>,
-        elem
-      )}
-    </div>
-  );
-};
-
-export default NodeGraph;
diff --git a/eventcatalog/src/components/MDX/NodeGraph/NodeGraphPortal.tsx b/eventcatalog/src/components/MDX/NodeGraph/NodeGraphPortal.tsx
deleted file mode 100644
index 11fa070bb..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/NodeGraphPortal.tsx
+++ /dev/null
@@ -1,15 +0,0 @@
-const NodeGraphPortal = (props: any) => {
-  return (
-    <div
-      className="h-[30em] my-6 mb-12 w-full relative border border-gray-200 rounded-md"
-      id={`${props.id}-portal`}
-      style={{
-        maxHeight: props.maxHeight ? `${props.maxHeight}em` : `30em`,
-      }}
-    >
-      {/* <span className="absolute top-2 right-4 bg-white font-bold z-10">{props.title}</span> */}
-    </div>
-  );
-};
-
-export default NodeGraphPortal;
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Actor.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/Actor.tsx
deleted file mode 100644
index 36e67c420..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Actor.tsx
+++ /dev/null
@@ -1,46 +0,0 @@
-import { Handle, Position, type XYPosition } from '@xyflow/react';
-
-import { nodeComponents } from '@eventcatalog/visualizer';
-const ActorComponent = nodeComponents.actor;
-
-interface Data {
-  data: {
-    actor: {
-      name: string;
-      summary: string;
-    };
-    mode: 'simple' | 'full';
-  };
-  type: 'actor';
-  id: string;
-  position: XYPosition;
-}
-
-export default function ActorNode(props: Data) {
-  const componentData = {
-    ...props,
-    data: {
-      ...props.data,
-      name: props.data.actor.name,
-      summary: props.data.actor.summary,
-    },
-  };
-
-  return (
-    <div className="relative">
-      <Handle
-        type="target"
-        position={Position.Left}
-        style={{ width: 10, height: 10, background: 'orange', zIndex: 10 }}
-        className="bg-gray-500"
-      />
-      <Handle
-        type="source"
-        position={Position.Right}
-        style={{ width: 10, height: 10, background: 'orange', zIndex: 10 }}
-        className="bg-gray-500"
-      />
-      <ActorComponent {...componentData} />
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Channel.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/Channel.tsx
deleted file mode 100644
index 851c687ee..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Channel.tsx
+++ /dev/null
@@ -1,55 +0,0 @@
-import { Handle, Position } from '@xyflow/react';
-import * as ContextMenu from '@radix-ui/react-context-menu';
-import { buildUrl } from '@utils/url-builder';
-
-import { nodeComponents, type ChannelNode } from '@eventcatalog/visualizer';
-const ChannelComponent = nodeComponents.channel;
-
-export default function ChannelNode(props: ChannelNode) {
-  // @ts-ignore
-  const { id, version } = props.data.channel;
-
-  return (
-    <ContextMenu.Root>
-      <ContextMenu.Trigger>
-        <div className="relative">
-          <Handle
-            type="target"
-            position={Position.Left}
-            style={{ width: 10, height: 10, background: 'green', zIndex: 10 }}
-            className="bg-gray-500"
-          />
-          <Handle
-            type="source"
-            position={Position.Right}
-            style={{ width: 10, height: 10, background: 'green', zIndex: 10 }}
-            className="bg-gray-500"
-          />
-          <ChannelComponent {...props} />
-        </div>
-      </ContextMenu.Trigger>
-      <ContextMenu.Portal>
-        <ContextMenu.Content className="min-w-[220px] bg-white rounded-md p-1 shadow-md border border-gray-200">
-          <ContextMenu.Item
-            asChild
-            className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-          >
-            <a href={buildUrl(`/docs/channels/${id}/${version}`)}>Read documentation</a>
-          </ContextMenu.Item>
-          <ContextMenu.Separator className="h-[1px] bg-gray-200 m-1" />
-
-          <ContextMenu.Item asChild>
-            <a
-              href={buildUrl(`/docs/channels/${id}/${version}/changelog`)}
-              className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-              target="_blank"
-              rel="noopener noreferrer"
-            >
-              Read changelog
-            </a>
-          </ContextMenu.Item>
-        </ContextMenu.Content>
-      </ContextMenu.Portal>
-    </ContextMenu.Root>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Command.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/Command.tsx
deleted file mode 100644
index bbea54a67..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Command.tsx
+++ /dev/null
@@ -1,27 +0,0 @@
-import { Handle, Position } from '@xyflow/react';
-import MessageContextMenu from './MessageContextMenu';
-
-import { nodeComponents, type CommandNode } from '@eventcatalog/visualizer';
-const CommandComponent = nodeComponents.command;
-
-export default function CommandNode(props: CommandNode) {
-  return (
-    <MessageContextMenu message={props.data.message as any} messageType="commands">
-      <div className="relative">
-        <Handle
-          type="target"
-          position={Position.Left}
-          style={{ width: 10, height: 10, background: 'blue', zIndex: 10 }}
-          className="bg-blue-500"
-        />
-        <Handle
-          type="source"
-          position={Position.Right}
-          style={{ width: 10, height: 10, background: 'blue', zIndex: 10 }}
-          className="bg-blue-500"
-        />
-        <CommandComponent {...props} />
-      </div>
-    </MessageContextMenu>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Custom.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/Custom.tsx
deleted file mode 100644
index d8f15c08b..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Custom.tsx
+++ /dev/null
@@ -1,159 +0,0 @@
-import { Handle } from '@xyflow/react';
-import * as Icons from '@heroicons/react/24/solid';
-import type { ComponentType } from 'react';
-import * as ContextMenu from '@radix-ui/react-context-menu';
-import * as Tooltip from '@radix-ui/react-tooltip';
-
-type MenuItem = {
-  label: string;
-  url?: string;
-};
-
-interface Data {
-  title: string;
-  label: string;
-  bgColor: string;
-  color: string;
-  mode: 'simple' | 'full';
-  step: { id: string; title: string; summary: string; name: string; actor: { name: string } };
-  showTarget?: boolean;
-  showSource?: boolean;
-  custom: {
-    icon?: string;
-    type?: string;
-    title?: string;
-    summary?: string;
-    url?: string;
-    color?: string;
-    properties?: Record<string, string>;
-    menu?: MenuItem[];
-    height?: number;
-  };
-}
-
-function classNames(...classes: any) {
-  return classes.filter(Boolean).join(' ');
-}
-
-export default function UserNode({ data, sourcePosition, targetPosition }: any) {
-  const { mode, step, custom: customProps } = data as Data;
-
-  const {
-    color = 'blue',
-    title = 'Custom',
-    icon = 'UserIcon',
-    type = 'custom',
-    summary = '',
-    url = '',
-    properties = {},
-    menu = [],
-    height = 5,
-  } = customProps;
-
-  const IconComponent: ComponentType<{ className?: string }> | undefined = Icons[icon as keyof typeof Icons];
-
-  const { actor: { name } = {} } = step;
-
-  const isLongType = type && type.length > 10;
-  const displayType = isLongType ? `${type.substring(0, 10)}...` : type;
-
-  return (
-    <ContextMenu.Root>
-      <ContextMenu.Trigger>
-        <div
-          className={classNames(`w-full rounded-md border flex justify-start  bg-white text-black border-${color}-400`)}
-          style={{ minHeight: mode === 'full' ? `${height}em` : '2em' }}
-        >
-          <div
-            className={classNames(
-              `bg-gradient-to-b from-${color}-400 to-${color}-600 relative flex items-center w-5 justify-center rounded-l-sm text-orange-100-500`,
-              `border-r-[1px] border-${color}`
-            )}
-          >
-            <IconComponent className="w-4 h-4 opacity-90 text-white absolute top-1 " />
-            {mode === 'full' && (
-              <Tooltip.Provider>
-                <Tooltip.Root>
-                  <Tooltip.Trigger asChild>
-                    <span className="rotate -rotate-90 w-1/2 text-center absolute bottom-1 text-[9px] text-white font-bold uppercase tracking-[3px]  ">
-                      {displayType}
-                    </span>
-                  </Tooltip.Trigger>
-                  {isLongType && (
-                    <Tooltip.Portal>
-                      <Tooltip.Content
-                        className="bg-slate-800 text-white rounded px-2 py-1 text-xs shadow-md z-50"
-                        side="right"
-                        sideOffset={5}
-                      >
-                        {type}
-                        <Tooltip.Arrow className="fill-slate-800" />
-                      </Tooltip.Content>
-                    </Tooltip.Portal>
-                  )}
-                </Tooltip.Root>
-              </Tooltip.Provider>
-            )}
-          </div>
-          <div className="p-1 min-w-60 max-w-[min-content]">
-            {targetPosition && <Handle type="target" position={targetPosition} />}
-            {sourcePosition && <Handle type="source" position={sourcePosition} />}
-
-            {(!summary || mode !== 'full') && (
-              <div className="h-full ">
-                <span className="text-sm font-bold block pb-0.5 w-full">{title}</span>
-              </div>
-            )}
-
-            {summary && mode === 'full' && (
-              <div>
-                <div className={classNames(mode === 'full' ? `border-b border-gray-200` : '')}>
-                  <span className="text-xs font-bold block pb-0.5">{title}</span>
-                </div>
-                {mode === 'full' && (
-                  <div className="divide-y divide-gray-200 ">
-                    <div className="leading-3 py-1">
-                      <span className="text-[8px] font-light">{summary}</span>
-                    </div>
-                    {properties && (
-                      <div className="grid grid-cols-2 gap-x-4 py-1">
-                        {Object.entries(properties).map(([key, value]) => (
-                          <span key={key} className="text-xs" style={{ fontSize: '0.2em' }}>
-                            {key}:{' '}
-                            {typeof value === 'string' && value.startsWith('http') ? (
-                              <a href={value} target="_blank" rel="noopener noreferrer" className="text-blue-500 underline">
-                                {value}
-                              </a>
-                            ) : (
-                              value
-                            )}
-                          </span>
-                        ))}
-                      </div>
-                    )}
-                  </div>
-                )}
-              </div>
-            )}
-          </div>
-        </div>
-      </ContextMenu.Trigger>
-      {menu?.length > 0 && (
-        <ContextMenu.Portal>
-          <ContextMenu.Content className="min-w-[220px] bg-white rounded-md p-1 shadow-md border border-gray-200">
-            {menu?.map((item) => {
-              return (
-                <ContextMenu.Item
-                  asChild
-                  className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-                >
-                  <a href={item.url}>{item.label}</a>
-                </ContextMenu.Item>
-              );
-            })}
-          </ContextMenu.Content>
-        </ContextMenu.Portal>
-      )}
-    </ContextMenu.Root>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Data.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/Data.tsx
deleted file mode 100644
index a9d11fdbc..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Data.tsx
+++ /dev/null
@@ -1,63 +0,0 @@
-import { Handle, Position } from '@xyflow/react';
-
-import { nodeComponents, type DataNode } from '@eventcatalog/visualizer';
-import * as ContextMenu from '@radix-ui/react-context-menu';
-import { buildUrl } from '@utils/url-builder';
-const DataComponent = nodeComponents.data;
-
-interface Data {
-  data: {
-    data: {
-      id: string;
-      version: string;
-      name: string;
-    };
-  };
-}
-
-export default function DataNode(props: Data) {
-  const { id, version, name } = props.data.data;
-
-  return (
-    <ContextMenu.Root>
-      <ContextMenu.Trigger>
-        <div className="relative">
-          <Handle
-            type="target"
-            position={Position.Left}
-            style={{ width: 10, height: 10, background: 'blue', zIndex: 10 }}
-            className="bg-gray-500"
-          />
-          <Handle
-            type="source"
-            position={Position.Right}
-            style={{ width: 10, height: 10, background: 'blue', zIndex: 10 }}
-            className="bg-gray-500"
-          />
-          <DataComponent {...(props as any)} />
-        </div>
-      </ContextMenu.Trigger>
-      <ContextMenu.Portal>
-        <ContextMenu.Content className="min-w-[220px] bg-white rounded-md p-1 shadow-md border border-gray-200">
-          <ContextMenu.Item
-            asChild
-            className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-          >
-            <a href={buildUrl(`/docs/containers/${id}/${version}`)}>Read documentation</a>
-          </ContextMenu.Item>
-          <ContextMenu.Separator className="h-[1px] bg-gray-200 m-1" />
-          <ContextMenu.Item asChild>
-            <a
-              href={buildUrl(`/docs/containers/${id}/${version}/changelog`)}
-              className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-              target="_blank"
-              rel="noopener noreferrer"
-            >
-              Read changelog
-            </a>
-          </ContextMenu.Item>
-        </ContextMenu.Content>
-      </ContextMenu.Portal>
-    </ContextMenu.Root>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Domain.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/Domain.tsx
deleted file mode 100644
index 3bfaba453..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Domain.tsx
+++ /dev/null
@@ -1,155 +0,0 @@
-import type { CollectionEntry } from 'astro:content';
-import { Handle, useReactFlow, useOnSelectionChange, Position } from '@xyflow/react';
-import * as ContextMenu from '@radix-ui/react-context-menu';
-import { buildUrl } from '@utils/url-builder';
-import { getIcon } from '@utils/badges';
-import { useState } from 'react';
-
-interface Data {
-  mode: 'simple' | 'full';
-  domain: CollectionEntry<'domains'>;
-}
-
-export default function DomainNode({ data, id: nodeId }: any) {
-  const { mode, domain } = data as Data;
-  const reactFlow = useReactFlow();
-  const [highlightedServices, setHighlightedServices] = useState<Set<string>>(new Set());
-
-  const { id, version, name, services = [], styles } = domain.data;
-  const { icon = 'RectangleGroupIcon' } = styles || {};
-
-  const Icon = getIcon(icon);
-  const ServerIcon = getIcon('ServerIcon');
-
-  // Listen for selection changes to highlight connected services
-  useOnSelectionChange({
-    onChange: ({ nodes: selectedNodes }) => {
-      if (selectedNodes.length === 0) {
-        setHighlightedServices(new Set());
-        return;
-      }
-
-      const selectedNode = selectedNodes[0];
-      if (!selectedNode) {
-        setHighlightedServices(new Set());
-        return;
-      }
-
-      // Get all edges
-      const edges = reactFlow.getEdges();
-      const connectedServiceIds = new Set<string>();
-
-      // Find services connected to the selected node
-      edges.forEach((edge) => {
-        if (edge.source === selectedNode.id || edge.target === selectedNode.id) {
-          // Check if this edge connects to our domain
-          if (edge.source === nodeId && edge.sourceHandle) {
-            // Extract service ID from sourceHandle (format: "serviceId-source")
-            const serviceId = edge.sourceHandle.replace('-source', '');
-            connectedServiceIds.add(serviceId);
-          }
-          if (edge.target === nodeId && edge.targetHandle) {
-            // Extract service ID from targetHandle (format: "serviceId-target")
-            const serviceId = edge.targetHandle.replace('-target', '');
-            connectedServiceIds.add(serviceId);
-          }
-        }
-      });
-
-      setHighlightedServices(connectedServiceIds);
-    },
-  });
-
-  return (
-    <ContextMenu.Root>
-      <ContextMenu.Trigger>
-        <div className="w-full rounded-lg border-2 border-yellow-400 bg-white shadow-lg">
-          <div className="bg-yellow-100 px-3 py-2 flex items-center space-x-2">
-            {Icon && <Icon className="w-4 h-4 text-yellow-700" />}
-            <div>
-              <span className="text-sm font-bold text-yellow-900">{name}</span>
-              <span className="text-xs text-yellow-700 ml-2">v{version}</span>
-            </div>
-          </div>
-          {mode === 'full' && services.length > 0 && (
-            <div>
-              {services.map((service: any, index: number) => {
-                const isHighlighted = highlightedServices.has(service.data.id);
-
-                return (
-                  <ContextMenu.Root key={`${service.data.id}-${index}`}>
-                    <ContextMenu.Trigger asChild>
-                      <div
-                        className={`relative flex items-center justify-between px-3 py-2 cursor-pointer ${index !== services.length - 1 ? 'border-b border-gray-300' : ''} ${isHighlighted ? 'bg-pink-100 border-pink-300' : ''}`}
-                      >
-                        <Handle
-                          type="target"
-                          position={Position.Left}
-                          id={`${service.data.id}-target`}
-                          className="!left-[-1px] !w-2 !h-2 !bg-gray-400 !border !border-gray-500 !rounded-full !z-10"
-                          style={{ left: '-1px' }}
-                        />
-                        <Handle
-                          type="source"
-                          position={Position.Right}
-                          id={`${service.data.id}-source`}
-                          className="!right-[-1px] !w-2 !h-2 !bg-gray-400 !border !border-gray-500 !rounded-full !z-10"
-                          style={{ right: '-1px' }}
-                        />
-                        <div className="flex items-center space-x-3">
-                          <div className="flex items-center justify-center w-5 h-5 bg-pink-500 rounded">
-                            {ServerIcon && <ServerIcon className="w-3 h-3 text-white" />}
-                          </div>
-                          <span className="text-sm font-medium text-gray-900">{service.data.name || service.data.id}</span>
-                        </div>
-                        <div className="flex items-center space-x-4 text-sm text-gray-600">
-                          <span className="text-xs">v{service.data.version}</span>
-                        </div>
-                      </div>
-                    </ContextMenu.Trigger>
-                    <ContextMenu.Portal>
-                      <ContextMenu.Content className="min-w-[220px] bg-white rounded-md p-1 shadow-md border border-gray-200">
-                        <ContextMenu.Item
-                          className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-                          onClick={() =>
-                            (window.location.href = buildUrl(`/docs/services/${service.data.id}/${service.data.version}`))
-                          }
-                        >
-                          View Service Documentation
-                        </ContextMenu.Item>
-                        <ContextMenu.Item
-                          className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-                          onClick={() =>
-                            (window.location.href = buildUrl(`/visualiser/services/${service.data.id}/${service.data.version}`))
-                          }
-                        >
-                          View Service Visualizer
-                        </ContextMenu.Item>
-                      </ContextMenu.Content>
-                    </ContextMenu.Portal>
-                  </ContextMenu.Root>
-                );
-              })}
-            </div>
-          )}
-        </div>
-      </ContextMenu.Trigger>
-      <ContextMenu.Portal>
-        <ContextMenu.Content className="min-w-[220px] bg-white rounded-md p-1 shadow-md border border-gray-200">
-          <ContextMenu.Item
-            className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-            onClick={() => (window.location.href = buildUrl(`/docs/domains/${id}/${version}`))}
-          >
-            View Domain Documentation
-          </ContextMenu.Item>
-          <ContextMenu.Item
-            className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-            onClick={() => (window.location.href = buildUrl(`/visualiser/domains/${id}/${version}`))}
-          >
-            View Domain Visualizer
-          </ContextMenu.Item>
-        </ContextMenu.Content>
-      </ContextMenu.Portal>
-    </ContextMenu.Root>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Entity.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/Entity.tsx
deleted file mode 100644
index 24b5c1620..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Entity.tsx
+++ /dev/null
@@ -1,151 +0,0 @@
-import { CubeIcon } from '@heroicons/react/16/solid';
-import type { CollectionEntry } from 'astro:content';
-import { Handle, Position } from '@xyflow/react';
-import { getIcon } from '@utils/badges';
-import * as ContextMenu from '@radix-ui/react-context-menu';
-import { buildUrl } from '@utils/url-builder';
-import { useState } from 'react';
-
-interface Data {
-  title: string;
-  label: string;
-  bgColor: string;
-  color: string;
-  mode: 'simple' | 'full';
-  entity: CollectionEntry<'entities'>;
-  showTarget?: boolean;
-  showSource?: boolean;
-  externalToDomain?: boolean;
-  domainName?: string;
-  domainId?: string;
-  group?: {
-    type: string;
-    value: string;
-  };
-}
-
-function classNames(...classes: any) {
-  return classes.filter(Boolean).join(' ');
-}
-
-export default function EntityNode({ data, sourcePosition, targetPosition }: any) {
-  const { mode, entity, externalToDomain, domainName } = data as Data;
-  const { name, version, properties = [], aggregateRoot, styles, sidebar } = entity.data;
-
-  const { node: { color = 'blue', label } = {}, icon = 'CubeIcon' } = styles || {};
-
-  const Icon = getIcon(icon);
-
-  const [hoveredProperty, setHoveredProperty] = useState<string | null>(null);
-
-  return (
-    <ContextMenu.Root>
-      <ContextMenu.Trigger>
-        <div
-          className={classNames(
-            'bg-white border border-blue-300 rounded-lg shadow-sm min-w-[200px]',
-            externalToDomain ? 'border-yellow-400' : ''
-          )}
-        >
-          {/* Table Header */}
-          <div
-            className={classNames(
-              'bg-blue-100 px-4 py-2 rounded-t-lg border-b border-gray-300',
-              externalToDomain ? 'bg-yellow-400' : ''
-            )}
-          >
-            <div className="flex items-center gap-2">
-              {Icon && <Icon className="w-4 h-4 text-gray-600" />}
-              <span className="font-semibold text-gray-800 text-sm">{name}</span>
-              {aggregateRoot && <span className="text-xs bg-yellow-100 text-yellow-800 px-1.5 py-0.5 rounded">AR</span>}
-            </div>
-            {/* {externalToDomain && domainName && ( */}
-            <div className="text-xs text-yellow-800 font-medium mt-1">from {domainName} domain</div>
-            {/* )} */}
-            {mode === 'full' && <div className="text-xs text-gray-600 mt-1">v{version}</div>}
-          </div>
-
-          {/* Properties Table */}
-          {properties.length > 0 ? (
-            <div className="divide-y divide-gray-200 relative">
-              {properties.map((property: any, index: number) => {
-                const propertyKey = `${property.name}-${index}`;
-                const isHovered = hoveredProperty === propertyKey;
-                return (
-                  <div
-                    key={propertyKey}
-                    className="relative flex items-center justify-between px-4 py-2 hover:bg-gray-50"
-                    onMouseEnter={() => property.description && setHoveredProperty(propertyKey)}
-                    onMouseLeave={() => setHoveredProperty(null)}
-                  >
-                    {/* Target handle */}
-                    <Handle
-                      type="target"
-                      position={Position.Left}
-                      id={`${property.name}-target`}
-                      className="!w-3 !h-3 !bg-white !border-2 !border-gray-400 !rounded-full !left-[-0px]"
-                      style={{ left: '-6px' }}
-                    />
-
-                    {/* Source handle */}
-                    <Handle
-                      type="source"
-                      position={Position.Right}
-                      id={`${property.name}-source`}
-                      className="!w-3 !h-3 !bg-white !border-2 !border-gray-400 !rounded-full !right-[-0px]"
-                      style={{ right: '-6px' }}
-                    />
-
-                    {/* Property content */}
-                    <div className="flex-1 flex items-center justify-between">
-                      <div className="flex items-center gap-1">
-                        <span className="text-sm font-medium text-gray-900">{property.name}</span>
-                        {property.required && <span className="text-red-500 text-xs">*</span>}
-                      </div>
-                      <span className="text-sm text-gray-600 font-mono">{property.type}</span>
-                    </div>
-
-                    {/* Reference indicator */}
-                    {property.references && (
-                      <div className="absolute right-2 top-1/2 transform -translate-y-1/2">
-                        <div className="w-2 h-2 bg-blue-500 rounded-full" title={`References ${property.references}`}></div>
-                      </div>
-                    )}
-
-                    {/* Property Tooltip */}
-                    {isHovered && property.description && (
-                      <div className="absolute left-full ml-2 top-1/2 transform -translate-y-1/2 z-[9999] w-[200px] bg-gray-900 text-white text-xs rounded-lg py-2 px-3 pointer-events-none shadow-xl max-w-xl opacity-100">
-                        <div className="text-gray-200 whitespace-normal break-words">{property.description}</div>
-                        <div className="absolute right-full top-1/2 transform -translate-y-1/2 border-4 border-transparent border-r-gray-900"></div>
-                      </div>
-                    )}
-                  </div>
-                );
-              })}
-            </div>
-          ) : (
-            <div className="px-4 py-3 text-sm text-gray-500 text-center">No properties defined</div>
-          )}
-
-          {/* Main node handles (if no properties) */}
-          {properties.length === 0 && (
-            <>
-              {targetPosition && <Handle type="target" position={targetPosition} />}
-              {sourcePosition && <Handle type="source" position={sourcePosition} />}
-            </>
-          )}
-        </div>
-      </ContextMenu.Trigger>
-      <ContextMenu.Portal>
-        <ContextMenu.Content className="min-w-[220px] bg-white rounded-md p-1 shadow-md border border-gray-200">
-          <ContextMenu.Item
-            asChild
-            className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-          >
-            <a href={buildUrl(`/docs/entities/${entity.data.id}/${version}`)}>Read documentation</a>
-          </ContextMenu.Item>
-        </ContextMenu.Content>
-      </ContextMenu.Portal>
-    </ContextMenu.Root>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Event.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/Event.tsx
deleted file mode 100644
index 82209f580..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Event.tsx
+++ /dev/null
@@ -1,29 +0,0 @@
-import { Handle } from '@xyflow/react';
-import MessageContextMenu from './MessageContextMenu';
-import { Position } from '@xyflow/react';
-
-// Import from properly installed package
-import { nodeComponents, type EventNode } from '@eventcatalog/visualizer';
-const EventComponent = nodeComponents.event;
-
-export default function EventNode(props: EventNode) {
-  return (
-    <MessageContextMenu message={props.data.message as any} messageType="events">
-      <div className="relative">
-        <Handle
-          type="target"
-          position={Position.Left}
-          style={{ width: 10, height: 10, background: 'orange', zIndex: 10 }}
-          className="bg-orange-500"
-        />
-        <Handle
-          type="source"
-          position={Position.Right}
-          style={{ width: 10, height: 10, background: 'orange', zIndex: 10 }}
-          className="bg-orange-500"
-        />
-        <EventComponent {...props} />
-      </div>
-    </MessageContextMenu>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/ExternalSystem.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/ExternalSystem.tsx
deleted file mode 100644
index e642fd4f3..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/ExternalSystem.tsx
+++ /dev/null
@@ -1,79 +0,0 @@
-import { ServerIcon } from '@heroicons/react/16/solid';
-import { GlobeAmericasIcon } from '@heroicons/react/20/solid';
-import type { CollectionEntry } from 'astro:content';
-import { Handle } from '@xyflow/react';
-
-interface Data {
-  label: string;
-  bgColor: string;
-  color: string;
-  mode: 'simple' | 'full';
-  step: { id: string; title: string; summary: string; externalSystem: { name: string; summary?: string; url?: string } };
-  showTarget?: boolean;
-  showSource?: boolean;
-}
-
-function classNames(...classes: any) {
-  return classes.filter(Boolean).join(' ');
-}
-
-export default function ExternalSystemNode({ data, sourcePosition, targetPosition }: any) {
-  const { mode, step } = data as Data;
-  const { externalSystem } = step;
-  const { name, summary, url } = externalSystem;
-
-  return (
-    <div
-      className={classNames(
-        `w-full rounded-md border flex justify-start  bg-white text-black border-pink-500`,
-        mode === 'full' ? 'min-h-[7em]' : 'min-h-[2em]'
-      )}
-    >
-      <div
-        className={classNames(
-          'bg-gradient-to-b from-pink-500 to-pink-700 relative flex items-center w-5 justify-center rounded-l-sm text-red-100-500',
-          `border-r-[1px] border-pink-500`
-        )}
-      >
-        <GlobeAmericasIcon className="w-4 h-4 opacity-90 text-white absolute top-1 " />
-        {mode === 'full' && (
-          <span className="rotate -rotate-90 w-1/2 text-center absolute bottom-1 text-[9px] text-white font-bold uppercase tracking-[3px] ">
-            External
-          </span>
-        )}
-      </div>
-      <div className="p-1 min-w-60 max-w-[min-content]">
-        {targetPosition && <Handle type="target" position={targetPosition} />}
-        {sourcePosition && <Handle type="source" position={sourcePosition} />}
-        <div className={classNames(mode === 'full' ? `border-b border-gray-200` : '')}>
-          <div className="h-full ">
-            <span className="text-sm font-bold pb-0.5 block w-full">{name}</span>
-            {mode === 'simple' && (
-              <div className="w-full text-right">
-                <span className=" w-full text-[10px] text-gray-500 font-light block pt-0.5 pb-0.5 ">External System</span>
-              </div>
-            )}
-          </div>
-        </div>
-        {mode === 'full' && (
-          <div className="divide-y divide-gray-200 ">
-            <div className="leading-3 py-1">
-              <span className="text-[8px] font-light">{summary}</span>
-            </div>
-
-            {url && (
-              <div className="grid grid-cols-2 gap-x-4 py-1">
-                <span className="text-xs" style={{ fontSize: '0.2em' }}>
-                  URL:{' '}
-                  <a href={url} target="_blank" className="text-primary underline">
-                    {url}
-                  </a>
-                </span>
-              </div>
-            )}
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/ExternalSystem2.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/ExternalSystem2.tsx
deleted file mode 100644
index 02935da16..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/ExternalSystem2.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import { Handle, Position } from '@xyflow/react';
-
-import { nodeComponents, type ExternalSystemNode } from '@eventcatalog/visualizer';
-const ExternalSystemComponent = nodeComponents.externalSystem;
-
-export default function ExternalSystemNode(props: ExternalSystemNode) {
-  return (
-    <div className="relative">
-      <Handle
-        type="target"
-        position={Position.Left}
-        style={{ width: 10, height: 10, background: 'pink', zIndex: 10 }}
-        className="bg-gray-500"
-      />
-      <Handle
-        type="source"
-        position={Position.Right}
-        style={{ width: 10, height: 10, background: 'pink', zIndex: 10 }}
-        className="bg-gray-500"
-      />
-      <ExternalSystemComponent {...props} />
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Flow.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/Flow.tsx
deleted file mode 100644
index 606d4406c..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Flow.tsx
+++ /dev/null
@@ -1,107 +0,0 @@
-import type { CollectionEntry } from 'astro:content';
-import { Handle } from '@xyflow/react';
-import * as ContextMenu from '@radix-ui/react-context-menu';
-import { buildUrl } from '@utils/url-builder';
-import { getIcon } from '@utils/badges';
-
-interface Data {
-  label: string;
-  bgColor: string;
-  color: string;
-  mode: 'simple' | 'full';
-  flow: CollectionEntry<'flows'>;
-  showTarget?: boolean;
-  showSource?: boolean;
-}
-
-function classNames(...classes: any) {
-  return classes.filter(Boolean).join(' ');
-}
-
-export default function FlowNode({ data, sourcePosition, targetPosition }: any) {
-  const { mode, flow } = data as Data;
-
-  const { id, version, owners = [], name, styles } = flow.data;
-  const { node: { color = 'teal', label } = {}, icon = 'QueueListIcon' } = styles || {};
-
-  const Icon = getIcon(icon);
-  const nodeLabel = label || flow?.data?.sidebar?.badge || 'Flow';
-  const fontSize = nodeLabel.length > 10 ? '7px' : '9px';
-
-  return (
-    <ContextMenu.Root>
-      <ContextMenu.Trigger>
-        <div className={classNames(`w-full rounded-md border flex justify-start  bg-white text-black border-${color}-400`)}>
-          <div
-            className={classNames(
-              `bg-gradient-to-b from-${color}-500 to-${color}-700 relative flex items-center w-5 justify-center rounded-l-sm text-${color}-100`,
-              `border-r-[1px] border-${color}-500`
-            )}
-          >
-            {Icon && <Icon className="w-4 h-4 opacity-90 text-white absolute top-1 " />}
-            {mode === 'full' && (
-              <span
-                className={`rotate -rotate-90 w-1/2 text-center absolute bottom-1 text-[${fontSize}] text-white font-bold uppercase tracking-[3px] `}
-              >
-                {nodeLabel}
-              </span>
-            )}
-          </div>
-          <div className="p-1 min-w-60 max-w-[min-content]">
-            {targetPosition && <Handle type="target" position={targetPosition} />}
-            {sourcePosition && <Handle type="source" position={sourcePosition} />}
-            <div className={classNames(mode === 'full' ? `border-b border-gray-200` : '')}>
-              <span className="text-xs font-bold block pt-0.5 pb-0.5">{name}</span>
-              <div className="flex justify-between">
-                <span className="text-[10px] font-light block pt-0.5 pb-0.5 ">v{version}</span>
-                {mode === 'simple' && (
-                  <span className="text-[10px] text-gray-500 font-light block pt-0.5 pb-0.5 ">{nodeLabel}</span>
-                )}
-              </div>
-            </div>
-            {mode === 'full' && (
-              <div className="divide-y divide-gray-200 ">
-                <div className="leading-3 py-1">
-                  <span className="text-[8px] font-light">{flow.data.summary}</span>
-                </div>
-
-                <div className="grid grid-cols-2 gap-x-4 py-1">
-                  <span className="text-xs" style={{ fontSize: '0.2em' }}>
-                    Owners: {owners.length}
-                  </span>
-                </div>
-              </div>
-            )}
-          </div>
-        </div>
-      </ContextMenu.Trigger>
-      <ContextMenu.Portal>
-        <ContextMenu.Content className="min-w-[220px] bg-white rounded-md p-1 shadow-md border border-gray-200">
-          <ContextMenu.Item
-            asChild
-            className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-          >
-            <a href={buildUrl(`/docs/flows/${id}/${version}`)}>Read documentation</a>
-          </ContextMenu.Item>
-          <ContextMenu.Item
-            asChild
-            className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-          >
-            <a href={buildUrl(`/visualiser/flows/${id}/${version}`)}>View in visualiser</a>
-          </ContextMenu.Item>
-          <ContextMenu.Separator className="h-[1px] bg-gray-200 m-1" />
-          <ContextMenu.Item asChild>
-            <a
-              href={buildUrl(`/docs/flows/${id}/${version}/changelog`)}
-              className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-              target="_blank"
-              rel="noopener noreferrer"
-            >
-              Read changelog
-            </a>
-          </ContextMenu.Item>
-        </ContextMenu.Content>
-      </ContextMenu.Portal>
-    </ContextMenu.Root>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/MessageContextMenu.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/MessageContextMenu.tsx
deleted file mode 100644
index 2575ced29..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/MessageContextMenu.tsx
+++ /dev/null
@@ -1,60 +0,0 @@
-import * as ContextMenu from '@radix-ui/react-context-menu';
-import { buildUrl } from '@utils/url-builder';
-import type { CollectionMessageTypes } from '@types';
-interface Data {
-  message: {
-    id: string;
-    version: string;
-    name: string;
-    schemaPath: string;
-  };
-  messageType: CollectionMessageTypes;
-  children: React.ReactNode;
-}
-
-export default function MessageContextMenu(data: Data) {
-  const { message, messageType, children } = data;
-  const { id, version, name, schemaPath } = message;
-
-  if (!id) return null;
-
-  return (
-    <ContextMenu.Root>
-      <ContextMenu.Trigger>{children}</ContextMenu.Trigger>
-      <ContextMenu.Portal>
-        <ContextMenu.Content className="min-w-[220px] bg-white rounded-md p-1 shadow-md border border-gray-200">
-          <ContextMenu.Item
-            asChild
-            className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-          >
-            <a href={buildUrl(`/docs/${messageType}/${id}/${version}`)}>Read documentation</a>
-          </ContextMenu.Item>
-          <ContextMenu.Separator className="h-[1px] bg-gray-200 m-1" />
-          {schemaPath && (
-            <ContextMenu.Item asChild>
-              <a
-                href={buildUrl(`/generated/${messageType}/${id}/schema.json`)}
-                download={`${name}(${version})-${schemaPath}`}
-                className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-                target="_blank"
-                rel="noopener noreferrer"
-              >
-                Download schema
-              </a>
-            </ContextMenu.Item>
-          )}
-          <ContextMenu.Item asChild>
-            <a
-              href={buildUrl(`/docs/${messageType}/${id}/${version}/changelog`)}
-              className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-              target="_blank"
-              rel="noopener noreferrer"
-            >
-              Read changelog
-            </a>
-          </ContextMenu.Item>
-        </ContextMenu.Content>
-      </ContextMenu.Portal>
-    </ContextMenu.Root>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Query.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/Query.tsx
deleted file mode 100644
index fdd3d05ad..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Query.tsx
+++ /dev/null
@@ -1,28 +0,0 @@
-import { Handle } from '@xyflow/react';
-import MessageContextMenu from './MessageContextMenu';
-import { Position } from '@xyflow/react';
-
-import { nodeComponents, type QueryNode } from '@eventcatalog/visualizer';
-const QueryComponent = nodeComponents.query;
-
-export default function QueryNode(props: QueryNode) {
-  return (
-    <MessageContextMenu message={props.data.message as any} messageType="queries">
-      <div className="relative">
-        <Handle
-          type="target"
-          position={Position.Left}
-          style={{ width: 10, height: 10, background: 'green', zIndex: 10 }}
-          className="bg-green-500"
-        />
-        <Handle
-          type="source"
-          position={Position.Right}
-          style={{ width: 10, height: 10, background: 'green', zIndex: 10 }}
-          className="bg-green-500"
-        />
-        <QueryComponent {...props} />
-      </div>
-    </MessageContextMenu>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Service.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/Service.tsx
deleted file mode 100644
index cb33973ac..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Service.tsx
+++ /dev/null
@@ -1,124 +0,0 @@
-import { Handle } from '@xyflow/react';
-import * as ContextMenu from '@radix-ui/react-context-menu';
-import { buildUrl } from '@utils/url-builder';
-import { Position } from '@xyflow/react';
-
-import { nodeComponents, type ServiceNode } from '@eventcatalog/visualizer';
-const ServiceComponent = nodeComponents.service;
-
-export default function ServiceNode(props: ServiceNode) {
-  const { id, version, specifications, repository } = props.data.service as any;
-
-  let asyncApiFiles = Array.isArray(specifications) ? specifications?.filter((spec) => spec.type === 'asyncapi') : ([] as any);
-  let openApiFiles = Array.isArray(specifications) ? specifications?.filter((spec) => spec.type === 'openapi') : ([] as any);
-
-  if (!Array.isArray(specifications) && specifications?.asyncapiPath) {
-    asyncApiFiles.push({ path: specifications.asyncapiPath, type: 'asyncapi', name: 'AsyncAPI' });
-  }
-
-  if (!Array.isArray(specifications) && specifications?.openapiPath) {
-    openApiFiles.push({ path: specifications.openapiPath, type: 'openapi', name: 'OpenAPI' });
-  }
-
-  // Add filename on asyncApiFiles and openApiFiles
-  asyncApiFiles = asyncApiFiles.map((file: any) => {
-    return {
-      ...file,
-      filename: file.path.split('/').pop()?.split('.').shift(),
-    };
-  });
-  openApiFiles = openApiFiles.map((file: any) => {
-    return {
-      ...file,
-      filename: file.path.split('/').pop()?.split('.').shift(),
-      name: file.name,
-    };
-  });
-
-  const repositoryUrl = repository?.url;
-
-  return (
-    <ContextMenu.Root>
-      <ContextMenu.Trigger>
-        <div className="relative">
-          <Handle
-            type="target"
-            position={Position.Left}
-            style={{ width: 10, height: 10, background: 'pink', zIndex: 10 }}
-            className="bg-pink-500"
-          />
-          <Handle
-            type="source"
-            position={Position.Right}
-            style={{ width: 10, height: 10, background: 'pink', zIndex: 10 }}
-            className="bg-pink-500"
-          />
-          <ServiceComponent {...props} />
-        </div>
-      </ContextMenu.Trigger>
-      <ContextMenu.Portal>
-        <ContextMenu.Content className="min-w-[220px] bg-white rounded-md p-1 shadow-md border border-gray-200">
-          <ContextMenu.Item
-            asChild
-            className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-          >
-            <a href={buildUrl(`/docs/services/${id}/${version}`)}>Read documentation</a>
-          </ContextMenu.Item>
-          <ContextMenu.Separator className="h-[1px] bg-gray-200 m-1" />
-          {asyncApiFiles.length > 0 &&
-            asyncApiFiles.map((file: any) => (
-              <ContextMenu.Item asChild key={file.path}>
-                <a
-                  href={buildUrl(`/docs/services/${id}/${version}/asyncapi/${file.filename}`)}
-                  className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-                  target="_blank"
-                  rel="noopener noreferrer"
-                >
-                  View AsyncAPI specification {file.name ? `(${file.name})` : ''}
-                </a>
-              </ContextMenu.Item>
-            ))}
-          {openApiFiles.length > 0 &&
-            openApiFiles.map((file: any) => (
-              <ContextMenu.Item asChild key={file.path}>
-                <a
-                  href={buildUrl(`/docs/services/${id}/${version}/spec/${file.filename}`)}
-                  className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-                  target="_blank"
-                  rel="noopener noreferrer"
-                >
-                  View OpenAPI specification {file.name ? `(${file.name})` : ''}
-                </a>
-              </ContextMenu.Item>
-            ))}
-          {asyncApiFiles.length > 0 && openApiFiles.length > 0 && <ContextMenu.Separator className="h-[1px] bg-gray-200 m-1" />}
-          {repositoryUrl && (
-            <>
-              <ContextMenu.Item asChild>
-                <a
-                  href={repositoryUrl}
-                  className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-                  target="_blank"
-                  rel="noopener noreferrer"
-                >
-                  View code repository
-                </a>
-              </ContextMenu.Item>
-              <ContextMenu.Separator className="h-[1px] bg-gray-200 m-1" />
-            </>
-          )}
-          <ContextMenu.Item asChild>
-            <a
-              href={buildUrl(`/docs/services/${id}/${version}/changelog`)}
-              className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
-              target="_blank"
-              rel="noopener noreferrer"
-            >
-              Read changelog
-            </a>
-          </ContextMenu.Item>
-        </ContextMenu.Content>
-      </ContextMenu.Portal>
-    </ContextMenu.Root>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Step.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/Step.tsx
deleted file mode 100644
index 4243ed82f..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/Step.tsx
+++ /dev/null
@@ -1,64 +0,0 @@
-import { Handle } from '@xyflow/react';
-
-interface Data {
-  title: string;
-  label: string;
-  bgColor: string;
-  color: string;
-  mode: 'simple' | 'full';
-  step: { id: string; title: string; summary: string };
-  showTarget?: boolean;
-  showSource?: boolean;
-}
-
-function classNames(...classes: any) {
-  return classes.filter(Boolean).join(' ');
-}
-
-export default function StepNode({ data, sourcePosition, targetPosition }: any) {
-  const { mode, step } = data as Data;
-
-  const { title, summary } = step;
-
-  return (
-    <div className={classNames('w-full rounded-md border flex justify-start  bg-white text-black border-blue-400 min-h-[3em]')}>
-      <div
-        className={classNames(
-          'bg-gradient-to-b from-gray-700 to-gray-700 relative flex items-center w-5 justify-center rounded-l-sm text-orange-100-500',
-          `border-r-[1px] border-gray-500`
-        )}
-      >
-        {mode === 'full' && (
-          <span className="rotate -rotate-90 w-1/2 text-center absolute bottom-1 text-[9px] text-white font-bold uppercase tracking-[3px] ">
-            Step
-          </span>
-        )}
-      </div>
-      <div className="p-1 min-w-60 max-w-[min-content]">
-        {targetPosition && <Handle type="target" position={targetPosition} />}
-        {sourcePosition && <Handle type="source" position={sourcePosition} />}
-
-        {!summary && (
-          <div className="h-full flex items-center">
-            <span className="text-sm font-bold block pb-0.5">{title}</span>
-          </div>
-        )}
-
-        {summary && (
-          <div>
-            <div className={classNames(mode === 'full' ? `border-b border-gray-200` : '')}>
-              <span className="text-xs font-bold block pb-0.5">{title}</span>
-            </div>
-            {mode === 'full' && (
-              <div className="divide-y divide-gray-200 ">
-                <div className="leading-3 py-1">
-                  <span className="text-[8px] font-light">{summary}</span>
-                </div>
-              </div>
-            )}
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/User.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/User.tsx
deleted file mode 100644
index b153f36a9..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/User.tsx
+++ /dev/null
@@ -1,76 +0,0 @@
-import { UserIcon } from '@heroicons/react/20/solid';
-import { Handle } from '@xyflow/react';
-
-interface Data {
-  title: string;
-  label: string;
-  bgColor: string;
-  color: string;
-  mode: 'simple' | 'full';
-  step: { id: string; title: string; summary: string; name: string; actor: { name: string } };
-  showTarget?: boolean;
-  showSource?: boolean;
-}
-
-function classNames(...classes: any) {
-  return classes.filter(Boolean).join(' ');
-}
-
-export default function UserNode({ data, sourcePosition, targetPosition }: any) {
-  const { mode, step, showTarget = true, showSource = true } = data as Data;
-
-  const { summary, actor: { name } = {} } = step;
-
-  return (
-    <div
-      className={classNames(
-        `w-full rounded-md border flex justify-start  bg-white text-black border-yellow-400`,
-        mode === 'full' ? 'min-h-[5em]' : 'min-h-[2em]'
-      )}
-    >
-      <div
-        className={classNames(
-          'bg-gradient-to-b from-yellow-400 to-yellow-600 relative flex items-center w-5 justify-center rounded-l-sm text-orange-100-500',
-          `border-r-[1px] border-yellow-500`
-        )}
-      >
-        <UserIcon className="w-4 h-4 opacity-90 text-white absolute top-1 " />
-        {mode === 'full' && (
-          <span className="rotate -rotate-90 w-1/2 text-center absolute bottom-1 text-[9px] text-white font-bold uppercase tracking-[3px] ">
-            ACTOR
-          </span>
-        )}
-      </div>
-      <div className="p-1 min-w-60 max-w-[min-content]">
-        {targetPosition && <Handle type="target" position={targetPosition} />}
-        {sourcePosition && <Handle type="source" position={sourcePosition} />}
-
-        {(!summary || mode !== 'full') && (
-          <div className="h-full ">
-            <span className="text-sm font-bold block pb-0.5 w-full">{name}</span>
-            {mode === 'simple' && (
-              <div className="w-full text-right">
-                <span className=" w-full text-[10px] text-gray-500 font-light block pt-0.5 pb-0.5 ">Event</span>
-              </div>
-            )}
-          </div>
-        )}
-
-        {summary && mode === 'full' && (
-          <div>
-            <div className={classNames(mode === 'full' ? `border-b border-gray-200` : '')}>
-              <span className="text-xs font-bold block pb-0.5">{name}</span>
-            </div>
-            {mode === 'full' && (
-              <div className="divide-y divide-gray-200 ">
-                <div className="leading-3 py-1">
-                  <span className="text-[8px] font-light">{summary}</span>
-                </div>
-              </div>
-            )}
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/Nodes/View.tsx b/eventcatalog/src/components/MDX/NodeGraph/Nodes/View.tsx
deleted file mode 100644
index 98ff862e4..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/Nodes/View.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import { Handle, Position } from '@xyflow/react';
-
-import { nodeComponents, type ViewNode } from '@eventcatalog/visualizer';
-const ViewComponent = nodeComponents.view;
-
-export default function ViewNode(props: ViewNode) {
-  return (
-    <div className="relative">
-      <Handle
-        type="target"
-        position={Position.Left}
-        style={{ width: 10, height: 10, background: 'blue', zIndex: 10 }}
-        className="bg-gray-500"
-      />
-      <Handle
-        type="source"
-        position={Position.Right}
-        style={{ width: 10, height: 10, background: 'blue', zIndex: 10 }}
-        className="bg-gray-500"
-      />
-      <ViewComponent {...props} />
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/StepWalkthrough.tsx b/eventcatalog/src/components/MDX/NodeGraph/StepWalkthrough.tsx
deleted file mode 100644
index 21b9c1b0f..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/StepWalkthrough.tsx
+++ /dev/null
@@ -1,296 +0,0 @@
-import React, { useState, useEffect, useCallback } from 'react';
-import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline';
-import type { Node, Edge } from '@xyflow/react';
-
-interface NodeData {
-  step?: {
-    title?: string;
-    summary?: string;
-  };
-  service?: {
-    data?: {
-      name?: string;
-      summary?: string;
-    };
-  };
-  message?: {
-    data?: {
-      name?: string;
-      summary?: string;
-    };
-  };
-  flow?: {
-    data?: {
-      name?: string;
-    };
-  };
-  custom?: {
-    title?: string;
-    label?: string;
-    summary?: string;
-  };
-  actor?: {
-    label?: string;
-  };
-  externalSystem?: {
-    label?: string;
-  };
-}
-
-interface CustomNode {
-  id: string;
-  data: NodeData;
-}
-
-interface StepWalkthroughProps {
-  nodes: CustomNode[];
-  edges: Edge[];
-  isFlowVisualization: boolean;
-  onStepChange: (nodeId: string | null, highlightPaths?: string[], shouldZoomOut?: boolean) => void;
-  mode?: 'full' | 'simple';
-}
-
-interface PathOption {
-  targetId: string;
-  label?: string;
-  targetNode: CustomNode;
-}
-
-export default function StepWalkthrough({
-  nodes,
-  edges,
-  isFlowVisualization,
-  onStepChange,
-  mode = 'full',
-}: StepWalkthroughProps) {
-  const [currentNodeId, setCurrentNodeId] = useState<string | null>(null);
-  const [pathHistory, setPathHistory] = useState<string[]>([]);
-  const [currentStepIndex, setCurrentStepIndex] = useState<number>(-1); // -1 means not started
-  const [availablePaths, setAvailablePaths] = useState<PathOption[]>([]);
-  const [selectedPathIndex, setSelectedPathIndex] = useState<number>(0);
-  const [startNodeId, setStartNodeId] = useState<string | null>(null);
-
-  useEffect(() => {
-    if (isFlowVisualization && nodes.length > 0) {
-      // Find the starting node (node with no incoming edges)
-      const incomingEdgeMap = new Map<string, number>();
-      nodes.forEach((node: CustomNode) => incomingEdgeMap.set(node.id, 0));
-
-      edges.forEach((edge: Edge) => {
-        if (incomingEdgeMap.has(edge.target)) {
-          incomingEdgeMap.set(edge.target, (incomingEdgeMap.get(edge.target) || 0) + 1);
-        }
-      });
-
-      const startNodes = nodes.filter((node: CustomNode) => incomingEdgeMap.get(node.id) === 0);
-      if (startNodes.length > 0 && !startNodeId) {
-        const firstStartNode = startNodes[0];
-        setStartNodeId(firstStartNode.id);
-      }
-    }
-  }, [nodes, edges, isFlowVisualization, startNodeId]);
-
-  useEffect(() => {
-    if (currentNodeId) {
-      // Find available paths from current node
-      const outgoingEdges = edges.filter((edge: Edge) => edge.source === currentNodeId);
-      const paths: PathOption[] = outgoingEdges.map((edge: Edge) => {
-        const targetNode = nodes.find((n: CustomNode) => n.id === edge.target);
-        return {
-          targetId: edge.target,
-          label: edge.label as string | undefined,
-          targetNode: targetNode!,
-        };
-      });
-      setAvailablePaths(paths);
-      setSelectedPathIndex(0);
-    } else {
-      setAvailablePaths([]);
-    }
-  }, [currentNodeId, nodes, edges]);
-
-  const handleNextStep = useCallback(() => {
-    if (currentStepIndex === -1) {
-      // Start the walkthrough
-      if (startNodeId) {
-        setPathHistory([startNodeId]);
-        setCurrentNodeId(startNodeId);
-        setCurrentStepIndex(0);
-        onStepChange(startNodeId);
-      }
-    } else if (availablePaths.length > 0) {
-      // Move to the selected path
-      const selectedPath = availablePaths[selectedPathIndex];
-      const newHistory = [...pathHistory, selectedPath.targetId];
-      setPathHistory(newHistory);
-      setCurrentNodeId(selectedPath.targetId);
-      setCurrentStepIndex((prev) => prev + 1);
-
-      // Highlight the selected path
-      const allPaths = availablePaths.map((p) => `${currentNodeId}-${p.targetId}`);
-      onStepChange(selectedPath.targetId, allPaths);
-    }
-  }, [currentStepIndex, startNodeId, availablePaths, selectedPathIndex, currentNodeId, onStepChange]);
-
-  const handlePreviousStep = useCallback(() => {
-    if (currentStepIndex > 0) {
-      // Go back to previous step
-      const newIndex = currentStepIndex - 1;
-      const prevNodeId = pathHistory[newIndex];
-      setCurrentNodeId(prevNodeId);
-      setCurrentStepIndex(newIndex);
-      onStepChange(prevNodeId);
-    } else if (currentStepIndex === 0) {
-      // Go back to the start (no selection)
-      setCurrentNodeId(null);
-      setCurrentStepIndex(-1);
-      onStepChange(null);
-    }
-  }, [currentStepIndex, pathHistory, onStepChange]);
-
-  const handlePathSelection = useCallback((index: number) => {
-    setSelectedPathIndex(index);
-  }, []);
-
-  const handleFinish = useCallback(() => {
-    setCurrentNodeId(null);
-    setCurrentStepIndex(-1);
-    setPathHistory([]);
-    onStepChange(null, [], true); // Pass true to indicate full reset with zoom out
-  }, [onStepChange]);
-
-  if (!isFlowVisualization || nodes.length === 0 || mode !== 'full') {
-    return null;
-  }
-
-  const getCurrentStepInfo = () => {
-    if (currentStepIndex === -1) {
-      return { title: 'Walk through business flow', description: 'Step through the flow to understand the business process' };
-    }
-
-    const currentNode = nodes.find((n: CustomNode) => n.id === currentNodeId);
-    if (!currentNode) return { title: 'Unknown step', description: '' };
-
-    let stepNumber = currentStepIndex + 1;
-    let title = `Step ${stepNumber}`;
-    let description = '';
-
-    // Get node information based on type - check step data first, then type-specific data
-    if (currentNode.data.step?.title) {
-      title += `: ${currentNode.data.step.title}`;
-    } else if (currentNode.data.service?.data?.name) {
-      title += `: ${currentNode.data.service.data.name}`;
-    } else if (currentNode.data.message?.data?.name) {
-      title += `: ${currentNode.data.message.data.name}`;
-    } else if (currentNode.data.flow?.data?.name) {
-      title += `: ${currentNode.data.flow.data.name}`;
-    } else if (currentNode.data.custom?.title) {
-      title += `: ${currentNode.data.custom.title}`;
-    } else if (currentNode.data.custom?.label) {
-      title += `: ${currentNode.data.custom.label}`;
-    } else if (currentNode.data.actor?.label) {
-      title += `: ${currentNode.data.actor.label}`;
-    } else if (currentNode.data.externalSystem?.label) {
-      title += `: ${currentNode.data.externalSystem.label}`;
-    }
-
-    // Get description - check step data first, then type-specific data
-    if (currentNode.data.step?.summary) {
-      description = currentNode.data.step.summary;
-    } else if (currentNode.data.service?.data?.summary) {
-      description = currentNode.data.service.data.summary;
-    } else if (currentNode.data.message?.data?.summary) {
-      description = currentNode.data.message.data.summary;
-    } else if (currentNode.data.custom?.summary) {
-      description = currentNode.data.custom.summary;
-    }
-
-    return { title, description };
-  };
-
-  const { title, description } = getCurrentStepInfo();
-
-  return (
-    <div className="ml-8 bg-white rounded-lg shadow-sm p-[8px] z-30 border border-gray-200 w-[350px]">
-      <div className="mb-3">
-        <h3 className="text-sm font-semibold text-gray-900">{title}</h3>
-        {description && <p className="text-xs text-gray-600 mt-1">{description}</p>}
-      </div>
-
-      {/* Show path options when there are multiple paths */}
-      {currentNodeId && availablePaths.length > 1 && (
-        <div className="mb-3">
-          <label className="block text-xs font-medium text-gray-700 mb-2">Choose next path:</label>
-          <select
-            value={selectedPathIndex}
-            onChange={(e: React.ChangeEvent<HTMLSelectElement>) => handlePathSelection(parseInt(e.target.value))}
-            className="w-full px-3 py-2 text-xs border border-gray-300 rounded-md bg-white focus:outline-none focus:ring-2 focus:ring-purple-500 focus:border-purple-500"
-          >
-            {availablePaths.map((path, index) => {
-              // @ts-ignore
-              const nodeLabel =
-                path.targetNode.data.step?.title ||
-                (path.targetNode.data as any).service?.data?.name ||
-                (path.targetNode.data as any).message?.data?.name ||
-                (path.targetNode.data as any).flow?.data?.name ||
-                (path.targetNode.data as any).custom?.title ||
-                (path.targetNode.data as any).custom?.label ||
-                (path.targetNode.data as any).actor?.label ||
-                (path.targetNode.data as any).externalSystem?.label ||
-                'Unknown';
-
-              return (
-                <option key={path.targetId} value={index}>
-                  {path.label ? `${path.label}: ${nodeLabel}` : nodeLabel}
-                </option>
-              );
-            })}
-          </select>
-        </div>
-      )}
-
-      <div className="flex items-center justify-between">
-        {currentStepIndex === -1 ? (
-          // Initial state - show only Start button on the right
-          <>
-            <div className="flex-1"></div>
-            <button
-              onClick={handleNextStep}
-              className="flex items-center justify-center px-6 py-2 text-xs font-medium bg-purple-600 text-white rounded-md hover:bg-purple-700 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2 transition-colors"
-            >
-              Start
-            </button>
-          </>
-        ) : (
-          // In walkthrough - show Previous on left, Next on right (only if paths available)
-          <>
-            <button
-              onClick={handlePreviousStep}
-              className="flex items-center justify-center px-4 py-2 text-xs font-medium bg-purple-600 text-white rounded-md hover:bg-purple-700 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2 transition-colors"
-            >
-              <ChevronLeftIcon className="w-4 h-4 mr-1" />
-              Previous
-            </button>
-
-            {availablePaths.length > 0 ? (
-              <button
-                onClick={handleNextStep}
-                className="flex items-center justify-center px-4 py-2 text-xs font-medium bg-purple-600 text-white rounded-md hover:bg-purple-700 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2 transition-colors"
-              >
-                Next
-                <ChevronRightIcon className="w-4 h-4 ml-1" />
-              </button>
-            ) : (
-              <button
-                onClick={handleFinish}
-                className="flex items-center justify-center px-4 py-2 text-xs font-medium bg-green-600 text-white rounded-md hover:bg-green-700 focus:outline-none focus:ring-2 focus:ring-green-500 focus:ring-offset-2 transition-colors"
-              >
-                Finish
-              </button>
-            )}
-          </>
-        )}
-      </div>
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/MDX/NodeGraph/StudioModal.tsx b/eventcatalog/src/components/MDX/NodeGraph/StudioModal.tsx
deleted file mode 100644
index 241952f9f..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/StudioModal.tsx
+++ /dev/null
@@ -1,129 +0,0 @@
-import React, { useState, useCallback } from 'react';
-import * as Dialog from '@radix-ui/react-dialog';
-import { CheckIcon, ClipboardIcon, ExternalLinkIcon } from 'lucide-react';
-import { useReactFlow } from '@xyflow/react';
-import { exportNodeGraphForStudio } from '@utils/node-graphs/export-node-graph';
-
-interface StudioModalProps {
-  isOpen: boolean;
-  onClose: () => void;
-}
-
-const StudioModal: React.FC<StudioModalProps> = ({ isOpen, onClose }) => {
-  const [copySuccess, setCopySuccess] = useState(false);
-
-  const { toObject } = useReactFlow();
-
-  const handleCopyToClipboard = useCallback(async () => {
-    const visualizerData = toObject();
-    const studioData = exportNodeGraphForStudio(visualizerData);
-
-    try {
-      await navigator.clipboard.writeText(JSON.stringify(studioData, null, 2));
-      setCopySuccess(true);
-      setTimeout(() => setCopySuccess(false), 2000);
-    } catch (error) {
-      console.error('Failed to copy to clipboard:', error);
-      // Fallback for older browsers
-      const textarea = document.createElement('textarea');
-      textarea.value = JSON.stringify(studioData, null, 2);
-      document.body.appendChild(textarea);
-      textarea.select();
-      document.execCommand('copy');
-      document.body.removeChild(textarea);
-      setCopySuccess(true);
-      setTimeout(() => setCopySuccess(false), 2000);
-    }
-  }, []);
-
-  const handleOpenStudio = () => {
-    window.open(
-      'https://app.eventcatalog.studio/playground?import=true&utm_source=eventcatalog&utm_medium=referral&utm_campaign=playground-import',
-      '_blank'
-    );
-    onClose();
-  };
-
-  return (
-    <Dialog.Root open={isOpen} onOpenChange={onClose}>
-      <Dialog.Portal>
-        <Dialog.Overlay className="fixed inset-0 bg-black/50 data-[state=open]:animate-overlayShow z-50" />
-        <Dialog.Content className="fixed top-1/2 left-1/2 w-[90vw] max-w-md -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6 shadow-xl focus:outline-none data-[state=open]:animate-contentShow z-[100]">
-          <Dialog.Title className="text-lg font-semibold text-gray-900 mb-3">Open in EventCatalog Studio</Dialog.Title>
-
-          <Dialog.Description className="text-sm text-gray-600 mb-6">
-            Import your diagram into{' '}
-            <a
-              href="https://eventcatalog.studio"
-              className="text-purple-600 hover:text-purple-700 underline"
-              target="_blank"
-              rel="noopener noreferrer"
-            >
-              EventCatalog Studio
-            </a>{' '}
-            to create designs from your visualization of your architecture.
-          </Dialog.Description>
-
-          <div className="space-y-4">
-            <div className="bg-gray-50 rounded-lg p-4 border border-gray-200">
-              <h4 className="text-sm font-bold text-gray-900 mb-2">Step 1: Copy diagram</h4>
-              <p className="text-xs text-gray-600 mb-3">Copy your diagram data to your clipboard.</p>
-              <button
-                onClick={handleCopyToClipboard}
-                className={`w-full flex items-center justify-center space-x-2 px-4 py-2 text-sm font-medium rounded-md border transition-colors ${
-                  copySuccess
-                    ? 'bg-green-50 border-green-200 text-green-700'
-                    : 'bg-white border-gray-300 text-gray-700 hover:bg-gray-50'
-                }`}
-              >
-                {copySuccess ? (
-                  <>
-                    <CheckIcon className="w-4 h-4" />
-                    <span>Copied!</span>
-                  </>
-                ) : (
-                  <>
-                    <ClipboardIcon className="w-4 h-4" />
-                    <span>Copy diagram to clipboard</span>
-                  </>
-                )}
-              </button>
-            </div>
-
-            <div className="bg-purple-50 rounded-lg p-4 border border-purple-200">
-              <h4 className="text-sm font-bold text-gray-900 mb-2">Step 2: Open EventCatalog Studio</h4>
-              <p className="text-xs text-gray-600 mb-3">
-                Go to EventCatalog Studio and import your design using the "Import from EventCatalog" button.
-              </p>
-
-              <button
-                onClick={handleOpenStudio}
-                className="w-full flex items-center justify-center space-x-2 px-4 py-2 bg-purple-600 text-white text-sm font-medium rounded-md hover:bg-purple-700 transition-colors"
-              >
-                <ExternalLinkIcon className="w-4 h-4" />
-                <span>Open EventCatalog Studio</span>
-              </button>
-              <p className="text-[12px] text-gray-500  italic mt-4 mb-0">
-                Don't worry, none of your data is stored by EventCatalog Studio, everything is local to your browser.
-              </p>
-            </div>
-          </div>
-
-          <div className="mt-6 flex justify-end">
-            <Dialog.Close asChild>
-              <button
-                type="button"
-                className="px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2 transition-colors"
-                onClick={onClose}
-              >
-                Close
-              </button>
-            </Dialog.Close>
-          </div>
-        </Dialog.Content>
-      </Dialog.Portal>
-    </Dialog.Root>
-  );
-};
-
-export default StudioModal;
diff --git a/eventcatalog/src/components/MDX/NodeGraph/VisualiserSearch.tsx b/eventcatalog/src/components/MDX/NodeGraph/VisualiserSearch.tsx
deleted file mode 100644
index 5c71d2dbe..000000000
--- a/eventcatalog/src/components/MDX/NodeGraph/VisualiserSearch.tsx
+++ /dev/null
@@ -1,258 +0,0 @@
-import { useState, useCallback, useRef, useEffect, forwardRef, useImperativeHandle } from 'react';
-import type { Node } from '@xyflow/react';
-
-// Define interfaces for different node data structures
-interface MessageData {
-  name: string;
-  version?: string;
-}
-
-interface ServiceData {
-  name: string;
-  version?: string;
-}
-
-interface DomainData {
-  name: string;
-  version?: string;
-}
-
-interface EntityData {
-  name: string;
-  version?: string;
-}
-
-interface NodeDataContent extends Record<string, unknown> {
-  message?: {
-    data: MessageData;
-  };
-  service?: {
-    data: ServiceData;
-  };
-  domain?: {
-    data: DomainData;
-  };
-  entity?: {
-    data: EntityData;
-  };
-  name?: string;
-  version?: string;
-}
-
-// Extend the Node type with our custom data structure
-type CustomNode = Node<NodeDataContent>;
-
-interface VisualiserSearchProps {
-  nodes: CustomNode[];
-  onNodeSelect: (node: CustomNode) => void;
-  onClear: () => void;
-  onPaneClick?: () => void;
-}
-
-export interface VisualiserSearchRef {
-  hideSuggestions: () => void;
-}
-
-const VisualiserSearch = forwardRef<VisualiserSearchRef, VisualiserSearchProps>(
-  ({ nodes, onNodeSelect, onClear, onPaneClick }, ref) => {
-    const [searchQuery, setSearchQuery] = useState('');
-    const [filteredSuggestions, setFilteredSuggestions] = useState<CustomNode[]>([]);
-    const [showSuggestions, setShowSuggestions] = useState(false);
-    const [selectedSuggestionIndex, setSelectedSuggestionIndex] = useState(-1);
-    const searchInputRef = useRef<HTMLInputElement>(null);
-    const containerRef = useRef<HTMLDivElement>(null);
-
-    const hideSuggestions = useCallback(() => {
-      setShowSuggestions(false);
-      setSelectedSuggestionIndex(-1);
-    }, []);
-
-    useImperativeHandle(
-      ref,
-      () => ({
-        hideSuggestions,
-      }),
-      [hideSuggestions]
-    );
-
-    const getNodeDisplayName = useCallback((node: CustomNode) => {
-      const name =
-        node.data?.message?.data?.name ||
-        node.data?.service?.data?.name ||
-        node.data?.domain?.data?.name ||
-        node.data?.entity?.data?.name ||
-        node.data?.name ||
-        node.id;
-      const version =
-        node.data?.message?.data?.version ||
-        node.data?.service?.data?.version ||
-        node.data?.domain?.data?.version ||
-        node.data?.entity?.data?.version ||
-        node.data?.version;
-      return version ? `${name} (v${version})` : name;
-    }, []);
-
-    const getNodeTypeColorClass = useCallback((nodeType: string) => {
-      const colorClasses: { [key: string]: string } = {
-        events: 'bg-orange-600 text-white',
-        services: 'bg-pink-600 text-white',
-        flows: 'bg-teal-600 text-white',
-        commands: 'bg-blue-600 text-white',
-        queries: 'bg-green-600 text-white',
-        channels: 'bg-gray-600 text-white',
-        domains: 'bg-yellow-500 text-white',
-        externalSystem: 'bg-pink-600 text-white',
-        actor: 'bg-yellow-500 text-white',
-        step: 'bg-gray-700 text-white',
-        user: 'bg-yellow-500 text-white',
-        custom: 'bg-gray-500 text-white',
-      };
-      return colorClasses[nodeType] || 'bg-gray-100 text-gray-700';
-    }, []);
-
-    const handleSearchChange = useCallback(
-      (event: React.ChangeEvent<HTMLInputElement>) => {
-        const query = event.target.value;
-        setSearchQuery(query);
-
-        if (query.length > 0) {
-          const filtered = nodes.filter((node) => {
-            const nodeName = getNodeDisplayName(node);
-            return nodeName.toLowerCase().includes(query.toLowerCase());
-          });
-          setFilteredSuggestions(filtered);
-          setShowSuggestions(true);
-          setSelectedSuggestionIndex(-1);
-        } else {
-          setFilteredSuggestions(nodes);
-          setShowSuggestions(true);
-          setSelectedSuggestionIndex(-1);
-        }
-      },
-      [nodes, getNodeDisplayName]
-    );
-
-    const handleSearchFocus = useCallback(() => {
-      if (searchQuery.length === 0) {
-        setFilteredSuggestions(nodes);
-      }
-      setShowSuggestions(true);
-      setSelectedSuggestionIndex(-1);
-    }, [nodes, searchQuery]);
-
-    const handleSuggestionClick = useCallback(
-      (node: CustomNode) => {
-        setSearchQuery(getNodeDisplayName(node));
-        setShowSuggestions(false);
-        onNodeSelect(node);
-      },
-      [onNodeSelect, getNodeDisplayName]
-    );
-
-    const handleSearchKeyDown = useCallback(
-      (event: React.KeyboardEvent<HTMLInputElement>) => {
-        if (!showSuggestions || filteredSuggestions.length === 0) return;
-
-        switch (event.key) {
-          case 'ArrowDown':
-            event.preventDefault();
-            setSelectedSuggestionIndex((prev) => (prev < filteredSuggestions.length - 1 ? prev + 1 : 0));
-            break;
-          case 'ArrowUp':
-            event.preventDefault();
-            setSelectedSuggestionIndex((prev) => (prev > 0 ? prev - 1 : filteredSuggestions.length - 1));
-            break;
-          case 'Enter':
-            event.preventDefault();
-            if (selectedSuggestionIndex >= 0) {
-              handleSuggestionClick(filteredSuggestions[selectedSuggestionIndex]);
-            }
-            break;
-          case 'Escape':
-            setShowSuggestions(false);
-            setSelectedSuggestionIndex(-1);
-            break;
-        }
-      },
-      [showSuggestions, filteredSuggestions, selectedSuggestionIndex, handleSuggestionClick]
-    );
-
-    const clearSearch = useCallback(() => {
-      setSearchQuery('');
-      setShowSuggestions(false);
-      setFilteredSuggestions([]);
-      setSelectedSuggestionIndex(-1);
-      onClear();
-      if (searchInputRef.current) {
-        searchInputRef.current.focus();
-      }
-    }, [onClear]);
-
-    // Close suggestions when clicking outside
-    useEffect(() => {
-      const handleClickOutside = (event: MouseEvent) => {
-        if (containerRef.current && !containerRef.current.contains(event.target as any)) {
-          setShowSuggestions(false);
-          setSelectedSuggestionIndex(-1);
-        }
-      };
-
-      document.addEventListener('mousedown', handleClickOutside);
-      return () => {
-        document.removeEventListener('mousedown', handleClickOutside);
-      };
-    }, []);
-
-    return (
-      <div ref={containerRef} className="w-full max-w-md mx-auto relative">
-        <div className="relative">
-          <input
-            ref={searchInputRef}
-            type="text"
-            placeholder="Search nodes..."
-            value={searchQuery}
-            onChange={handleSearchChange}
-            onKeyDown={handleSearchKeyDown}
-            onFocus={handleSearchFocus}
-            className="w-full px-4 py-2 pr-10 bg-white border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-2 focus:ring-purple-500 focus:border-transparent"
-          />
-          {searchQuery && (
-            <button
-              onClick={clearSearch}
-              className="absolute right-2 top-1/2 transform -translate-y-1/2 text-gray-400 hover:text-gray-600"
-              aria-label="Clear search"
-            >
-              <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-              </svg>
-            </button>
-          )}
-        </div>
-        {showSuggestions && filteredSuggestions.length > 0 && (
-          <div className="absolute top-full left-0 right-0 mt-1 bg-white border border-gray-300 rounded-md shadow-lg z-50 max-h-60 overflow-y-auto">
-            {filteredSuggestions.map((node, index) => {
-              const nodeName = getNodeDisplayName(node);
-              const nodeType = node.type || 'unknown';
-              return (
-                <div
-                  key={node.id}
-                  onClick={() => handleSuggestionClick(node)}
-                  className={`px-4 py-2 cursor-pointer flex items-center justify-between hover:bg-gray-100 ${
-                    index === selectedSuggestionIndex ? 'bg-purple-50' : ''
-                  }`}
-                >
-                  <span className="text-sm font-medium text-gray-900">{nodeName}</span>
-                  <span className={`text-xs capitalize px-2 py-1 rounded ${getNodeTypeColorClass(nodeType)}`}>{nodeType}</span>
-                </div>
-              );
-            })}
-          </div>
-        )}
-      </div>
-    );
-  }
-);
-
-VisualiserSearch.displayName = 'VisualiserSearch';
-
-export default VisualiserSearch;
diff --git a/eventcatalog/src/components/MDX/ResourceGroupTable/ResourceGroupTable.client.tsx b/eventcatalog/src/components/MDX/ResourceGroupTable/ResourceGroupTable.client.tsx
deleted file mode 100644
index c7a5a1867..000000000
--- a/eventcatalog/src/components/MDX/ResourceGroupTable/ResourceGroupTable.client.tsx
+++ /dev/null
@@ -1,408 +0,0 @@
-import { getColorAndIconForCollection } from '@utils/collections/icons';
-import { buildUrl } from '@utils/url-builder';
-import { useState, useMemo, useCallback, memo } from 'react';
-
-type Resource = {
-  id: string;
-  name: string;
-  version: string;
-  collection: string;
-  type: string;
-  summary?: string;
-  description?: string;
-  owners?: any[];
-  tags?: string[];
-};
-
-type ResourceGroupTableProps = {
-  resources: Resource[];
-  limit?: number;
-  showTags?: boolean;
-  showOwners?: boolean;
-  title: string;
-  subtitle?: string;
-  description: string;
-};
-
-type ResourceType = 'service' | 'event' | 'query' | 'command' | 'domain' | 'flow' | 'channel' | 'user' | 'team' | null;
-
-const ResourceRow = memo(
-  ({ resource, showTags, showOwners }: { resource: Resource; showTags?: boolean; showOwners?: boolean }) => {
-    const { color, Icon } = getColorAndIconForCollection(resource.collection);
-    const url = buildUrl(`/docs/${resource.collection}/${resource.id}/${resource.version}`);
-    let type = resource.collection.slice(0, -1);
-    type = type === 'querie' ? 'query' : type;
-
-    const tags = resource.tags || [];
-    const owners = resource.owners || [];
-
-    return (
-      <tr className="group hover:bg-gray-100">
-        <td className="whitespace-nowrap py-4 pl-4 pr-3 text-sm font-medium text-gray-900 sm:pl-6 relative">
-          <a href={url} className="absolute inset-0 z-10" aria-label={`View details for ${resource.name}`} />
-          <div className="flex items-center gap-2 relative">
-            <Icon className={`h-5 w-5 text-${color}-500`} />
-            <span className="group-hover:text-blue-600 break-all">{resource.name}</span>
-          </div>
-        </td>
-        <td className="whitespace-nowrap px-3 py-4 text-sm text-gray-500 relative">
-          <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
-          <span>v{resource.version}</span>
-        </td>
-        <td className="whitespace-nowrap px-3 py-4 text-sm text-gray-500 relative">
-          <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
-          <span>{type}</span>
-        </td>
-        <td className="px-3 py-4 text-sm text-gray-500 relative">
-          <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
-          <span className="line-clamp-2 break-words">{resource.summary || resource.description || '-'}</span>
-        </td>
-        {showTags && (
-          <td className="px-3 py-4 text-sm text-gray-500 relative">
-            <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
-            <div className="flex flex-wrap gap-1">
-              {tags.length > 0
-                ? tags.map((tag, index) => (
-                    <span
-                      key={`${tag}-${index}`}
-                      className="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10"
-                    >
-                      {tag}
-                    </span>
-                  ))
-                : '-'}
-            </div>
-          </td>
-        )}
-        {showOwners && (
-          <td className="px-3 py-4 text-sm text-gray-500 relative">
-            <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
-            <div className="flex flex-wrap gap-1">
-              {owners.length > 0
-                ? owners.map((owner, index) => (
-                    <span
-                      key={`${owner.id || owner.name}-${index}`}
-                      className="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10"
-                    >
-                      {owner.name || owner.id}
-                    </span>
-                  ))
-                : '-'}
-            </div>
-          </td>
-        )}
-      </tr>
-    );
-  }
-);
-
-const FilterButton = memo(
-  ({
-    type,
-    label,
-    typeFilter,
-    setTypeFilter,
-    setCurrentPage,
-    count,
-  }: {
-    type: ResourceType;
-    label: string;
-    typeFilter: ResourceType;
-    setTypeFilter: (type: ResourceType) => void;
-    setCurrentPage: (page: number) => void;
-    count: number;
-  }) => (
-    <button
-      onClick={() => {
-        setTypeFilter(typeFilter === type ? null : type);
-        setCurrentPage(1);
-      }}
-      className={`px-3 py-1 rounded-md text-sm font-medium ${
-        typeFilter === type
-          ? 'bg-black text-white border border-gray-200 hover:bg-gray-900'
-          : 'bg-white text-black border border-gray-200 hover:bg-gray-100'
-      }`}
-    >
-      {label} ({count})
-    </button>
-  )
-);
-
-const ResourceGroupTable = (props: ResourceGroupTableProps) => {
-  const { resources = [], limit, showTags = false, showOwners = false, title, subtitle = 'Resources', description } = props;
-  const [searchTerm, setSearchTerm] = useState('');
-  const [currentPage, setCurrentPage] = useState(1);
-  const [typeFilter, setTypeFilter] = useState<ResourceType>(null);
-  const itemsPerPage = limit || 10;
-
-  const filterResources = useCallback((resources: Resource[], searchTerm: string, typeFilter: ResourceType) => {
-    let filtered = resources;
-
-    if (typeFilter) {
-      filtered = filtered.filter((resource) => {
-        const collectionType = resource.collection.slice(0, -1);
-        const normalizedType = collectionType === 'querie' ? 'query' : collectionType;
-        return normalizedType === typeFilter;
-      });
-    }
-
-    if (searchTerm) {
-      const lowerSearchTerm = searchTerm.toLowerCase();
-      filtered = filtered.filter((resource) => {
-        const collectionType = resource.collection.slice(0, -1);
-        const normalizedType = collectionType === 'querie' ? 'query' : collectionType;
-
-        return (
-          resource.name.toLowerCase().includes(lowerSearchTerm) ||
-          resource.summary?.toLowerCase().includes(lowerSearchTerm) ||
-          resource.description?.toLowerCase().includes(lowerSearchTerm) ||
-          normalizedType.toLowerCase().includes(lowerSearchTerm) ||
-          resource.tags?.some((tag) => tag.toLowerCase().includes(lowerSearchTerm)) ||
-          false
-        );
-      });
-    }
-
-    return filtered;
-  }, []);
-
-  const filteredResources = useMemo(
-    () => filterResources(resources, searchTerm, typeFilter),
-    [resources, searchTerm, typeFilter, filterResources]
-  );
-
-  const totalPages = Math.ceil(filteredResources.length / itemsPerPage);
-  const startIndex = (currentPage - 1) * itemsPerPage;
-  const paginatedResources = useMemo(
-    () => filteredResources.slice(startIndex, startIndex + itemsPerPage),
-    [filteredResources, startIndex, itemsPerPage]
-  );
-
-  // Get unique resource types and their counts
-  const resourceTypeCounts = useMemo(() => {
-    const counts = new Map<ResourceType, number>();
-    resources.forEach((resource) => {
-      const collectionType = resource.collection.slice(0, -1);
-      const normalizedType = (collectionType === 'querie' ? 'query' : collectionType) as ResourceType;
-      counts.set(normalizedType, (counts.get(normalizedType) || 0) + 1);
-    });
-    return counts;
-  }, [resources]);
-
-  const availableTypes = useMemo(
-    () =>
-      Array.from(
-        new Set(
-          resources.map((resource) => {
-            const collectionType = resource.collection.slice(0, -1);
-            return collectionType === 'querie' ? 'query' : collectionType;
-          })
-        )
-      ) as ResourceType[],
-    [resources]
-  );
-
-  const filterButtons = useMemo(
-    () =>
-      availableTypes
-        .filter((type): type is NonNullable<ResourceType> => type !== null)
-        .map((type) => ({
-          type,
-          // Format the label to be capitalized and pluralized if needed
-          label: type.charAt(0).toUpperCase() + type.slice(1) + (type.endsWith('s') ? '' : 's'),
-          count: resourceTypeCounts.get(type) || 0,
-        })),
-    [availableTypes, resourceTypeCounts]
-  );
-
-  return (
-    <div className="mx-auto not-prose py-4 space-y-4 my-4">
-      {title && <h2 className="text-2xl font-semibold">{title}</h2>}
-      <div className="flow-root bg-white border-gray-200 border p-4 pb-2 rounded-lg text-gray-900">
-        <div className="space-y-4">
-          <h2 className="text-xl font-semibold">
-            {subtitle} ({searchTerm || typeFilter ? `${filteredResources.length}/${resources.length}` : resources.length})
-          </h2>
-          <span className="text-sm text-gray-700">{description}</span>
-
-          {/* Type filter buttons - only shown if there are filter options */}
-          {filterButtons.length > 0 && (
-            <div className="flex gap-2 pb-2 flex-wrap">
-              {filterButtons.map((button) => (
-                <FilterButton
-                  key={button.type}
-                  type={button.type}
-                  label={button.label}
-                  count={button.count}
-                  typeFilter={typeFilter}
-                  setTypeFilter={setTypeFilter}
-                  setCurrentPage={setCurrentPage}
-                />
-              ))}
-            </div>
-          )}
-
-          <div className="relative">
-            <div className="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
-              <svg className="h-5 w-5 text-gray-400" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
-                <path
-                  fillRule="evenodd"
-                  d="M9 3.5a5.5 5.5 0 100 11 5.5 5.5 0 000-11zM2 9a7 7 0 1112.452 4.391l3.328 3.329a.75.75 0 11-1.06 1.06l-3.329-3.328A7 7 0 012 9z"
-                  clipRule="evenodd"
-                />
-              </svg>
-            </div>
-            <input
-              type="text"
-              value={searchTerm}
-              onChange={(e) => {
-                setSearchTerm(e.target.value);
-                setCurrentPage(1); // Reset to first page when searching
-              }}
-              placeholder="Search by name, type, description, or tags..."
-              className="block w-full rounded-md border-0 py-1.5 pl-10 pr-10 text-gray-900 ring-1 ring-inset ring-gray-300 placeholder:text-gray-400 focus:ring-2 focus:ring-inset focus:ring-blue-600 sm:text-sm sm:leading-6"
-            />
-            {searchTerm && (
-              <button
-                onClick={() => {
-                  setSearchTerm('');
-                  setCurrentPage(1); // Reset to first page when clearing search
-                }}
-                className="absolute inset-y-0 right-0 flex items-center pr-3"
-                aria-label="Clear search"
-              >
-                <svg className="h-5 w-5 text-gray-400 hover:text-gray-500" viewBox="0 0 20 20" fill="currentColor">
-                  <path d="M6.28 5.22a.75.75 0 00-1.06 1.06L8.94 10l-3.72 3.72a.75.75 0 101.06 1.06L10 11.06l3.72 3.72a.75.75 0 101.06-1.06L11.06 10l3.72-3.72a.75.75 0 00-1.06-1.06L10 8.94 6.28 5.22z" />
-                </svg>
-              </button>
-            )}
-          </div>
-        </div>
-        <div className="overflow-x-auto">
-          <div className="inline-block min-w-full py-2 align-middle">
-            <div className="max-w-full overflow-hidden">
-              <table className="min-w-full table-fixed divide-y divide-gray-300 rounded-sm bg-white">
-                <thead>
-                  <tr>
-                    <th
-                      scope="col"
-                      className={`${showTags || showOwners ? 'w-1/5' : 'w-1/4'} py-3.5 pl-4 pr-3 text-left text-sm font-semibold text-gray-900 sm:pl-6`}
-                    >
-                      Name
-                    </th>
-                    <th scope="col" className="w-[100px] px-3 py-3.5 text-left text-sm font-semibold text-gray-900">
-                      Version
-                    </th>
-                    <th scope="col" className="w-[100px] py-3.5 pl-3.5 pr-3 text-left text-sm font-semibold text-gray-900">
-                      Type
-                    </th>
-                    <th
-                      scope="col"
-                      className={`${showTags && showOwners ? 'w-1/4' : showTags || showOwners ? 'w-1/3' : 'w-1/2'} px-3 py-3.5 text-left text-sm font-semibold text-gray-900`}
-                    >
-                      Description
-                    </th>
-                    {showTags && (
-                      <th scope="col" className="w-1/6 px-3 py-3.5 text-left text-sm font-semibold text-gray-900">
-                        Tags
-                      </th>
-                    )}
-                    {showOwners && (
-                      <th scope="col" className="w-1/6 px-3 py-3.5 text-left text-sm font-semibold text-gray-900">
-                        Owners
-                      </th>
-                    )}
-                  </tr>
-                </thead>
-                <tbody className="divide-y divide-gray-200">
-                  {paginatedResources.length > 0 ? (
-                    paginatedResources.map((resource) => (
-                      <ResourceRow
-                        key={`${resource.collection}-${resource.id}-${resource.version}`}
-                        resource={resource}
-                        showTags={showTags}
-                        showOwners={showOwners}
-                      />
-                    ))
-                  ) : (
-                    <tr>
-                      <td
-                        colSpan={showTags && showOwners ? 6 : showTags || showOwners ? 5 : 4}
-                        className="text-center py-4 text-sm text-gray-500"
-                      >
-                        No resources found
-                      </td>
-                    </tr>
-                  )}
-                </tbody>
-              </table>
-            </div>
-          </div>
-        </div>
-        {totalPages > 1 && (
-          <div className="flex items-center justify-between border-t border-gray-200 bg-white px-4 py-3 sm:px-6 -mt-2">
-            <div className="flex flex-1 justify-between sm:hidden">
-              <button
-                onClick={() => setCurrentPage(currentPage - 1)}
-                disabled={currentPage === 1}
-                className={`relative inline-flex items-center rounded-md border border-gray-300 bg-white px-4 py-2 text-sm font-medium ${currentPage === 1 ? 'text-gray-300' : 'text-gray-700 hover:bg-gray-50'}`}
-              >
-                Previous
-              </button>
-              <button
-                onClick={() => setCurrentPage(currentPage + 1)}
-                disabled={currentPage === totalPages}
-                className={`relative ml-3 inline-flex items-center rounded-md border border-gray-300 bg-white px-4 py-2 text-sm font-medium ${currentPage === totalPages ? 'text-gray-300' : 'text-gray-700 hover:bg-gray-50'}`}
-              >
-                Next
-              </button>
-            </div>
-            <div className="hidden sm:flex sm:flex-1 sm:items-center sm:justify-between">
-              <div>
-                <p className="text-sm text-gray-700">
-                  Showing <span className="font-medium">{startIndex + 1}</span> to{' '}
-                  <span className="font-medium">{Math.min(startIndex + itemsPerPage, filteredResources.length)}</span> of{' '}
-                  <span className="font-medium">{filteredResources.length}</span> results
-                </p>
-              </div>
-              <div>
-                <nav className="isolate inline-flex -space-x-px rounded-md shadow-sm" aria-label="Pagination">
-                  <button
-                    onClick={() => setCurrentPage(currentPage - 1)}
-                    disabled={currentPage === 1}
-                    className={`relative inline-flex items-center rounded-l-md px-2 py-2 ${currentPage === 1 ? 'text-gray-300' : 'text-gray-400 hover:bg-gray-50'} ring-1 ring-inset ring-gray-300`}
-                  >
-                    <span className="sr-only">Previous</span>
-                    <svg className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
-                      <path
-                        fillRule="evenodd"
-                        d="M12.79 5.23a.75.75 0 01-.02 1.06L8.832 10l3.938 3.71a.75.75 0 11-1.04 1.08l-4.5-4.25a.75.75 0 010-1.08l4.5-4.25a.75.75 0 011.06.02z"
-                        clipRule="evenodd"
-                      />
-                    </svg>
-                  </button>
-                  <button
-                    onClick={() => setCurrentPage(currentPage + 1)}
-                    disabled={currentPage === totalPages}
-                    className={`relative inline-flex items-center rounded-r-md px-2 py-2 ${currentPage === totalPages ? 'text-gray-300' : 'text-gray-400 hover:bg-gray-50'} ring-1 ring-inset ring-gray-300`}
-                  >
-                    <span className="sr-only">Next</span>
-                    <svg className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
-                      <path
-                        fillRule="evenodd"
-                        d="M7.21 14.77a.75.75 0 01.02-1.06L11.168 10 7.23 6.29a.75.75 0 111.04-1.08l4.5 4.25a.75.75 0 010 1.08l-4.5 4.25a.75.75 0 01-1.06-.02z"
-                        clipRule="evenodd"
-                      />
-                    </svg>
-                  </button>
-                </nav>
-              </div>
-            </div>
-          </div>
-        )}
-      </div>
-    </div>
-  );
-};
-
-export default ResourceGroupTable;
diff --git a/eventcatalog/src/components/MDX/Schema.astro b/eventcatalog/src/components/MDX/Schema.astro
deleted file mode 100644
index 7187d8893..000000000
--- a/eventcatalog/src/components/MDX/Schema.astro
+++ /dev/null
@@ -1,37 +0,0 @@
----
-import fs from 'fs';
-import path from 'path';
-import { Code } from 'astro-expressive-code/components';
-import { getAbsoluteFilePathForAstroFile } from '@utils/files';
-
-interface Props {
-  file?: string;
-  catalog: {
-    filePath: string;
-  };
-  title?: string;
-  filePath: string;
-  lang?: string;
-}
-
-const { file = 'schema.json', catalog, title, filePath, lang = 'json' } = Astro.props;
-
-let code: string | null = null;
-
-const absoluteFilePath = getAbsoluteFilePathForAstroFile(filePath, file);
-
-const exists = fs.existsSync(absoluteFilePath);
-if (exists) {
-  code = fs.readFileSync(absoluteFilePath, 'utf-8');
-}
----
-
-{
-  code ? (
-    <div class="not-prose max-w-4xl overflow-x-auto">
-      <Code code={code} title={title || file} lang={lang} />
-    </div>
-  ) : (
-    <div class="italic">Tried to load schema from {path.join(catalog.filePath, file)}, but no schema can be found</div>
-  )
-}
diff --git a/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerRoot.astro b/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerRoot.astro
deleted file mode 100644
index 3a2a42931..000000000
--- a/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerRoot.astro
+++ /dev/null
@@ -1,164 +0,0 @@
----
-const { id, filePath } = Astro.props;
-import fs from 'node:fs/promises';
-import { existsSync } from 'fs';
-import yaml from 'js-yaml';
-import JSONSchemaViewer from '@components/SchemaExplorer/JSONSchemaViewer';
-import AvroSchemaViewer from '@components/SchemaExplorer/AvroSchemaViewer';
-import Admonition from '../Admonition';
-import { getMDXComponentsByName } from '@utils/markdown';
-import { getAbsoluteFilePathForAstroFile, resolveProjectPath, isAvroSchema } from '@utils/files';
-
-let schemas = [];
-
-try {
-  const absoluteFilePath = resolveProjectPath(filePath);
-  const file = await fs.readFile(absoluteFilePath, 'utf-8');
-  const schemaViewers = getMDXComponentsByName(file, 'SchemaViewer');
-
-  // Loop around all the possible SchemaViewers in the file.
-  const getAllComponents = schemaViewers.map(async (schemaViewerProps: any, index: number) => {
-    const schemaPath = getAbsoluteFilePathForAstroFile(filePath, schemaViewerProps.file);
-    const exists = existsSync(schemaPath);
-    let schema;
-    let render = true;
-    let isAvro = false;
-
-    if (exists) {
-      // Check if this is an Avro schema file
-      isAvro = isAvroSchema(schemaPath);
-
-      // Load the schema for the component
-      schema = await fs.readFile(schemaPath, 'utf-8');
-
-      if (schemaPath.endsWith('.yml') || schemaPath.endsWith('.yaml')) {
-        schema = yaml.load(schema);
-      } else {
-        schema = JSON.parse(schema);
-
-        // For non-Avro schemas, let JSON schema control if the component should be rendered
-        if (!isAvro && schema['x-eventcatalog-render-schema-viewer'] !== undefined) {
-          render = schema['x-eventcatalog-render-schema-viewer'];
-        }
-      }
-    }
-
-    return {
-      id: schemaViewerProps.id || id,
-      exists,
-      schema,
-      schemaPath,
-      isAvroSchema: isAvro,
-      ...schemaViewerProps,
-      render,
-      index,
-    };
-  });
-
-  schemas = await Promise.all(getAllComponents);
-} catch (error) {
-  console.log('Failed to process schemas');
-  console.log(error);
-}
----
-
-<section class="space-y-4">
-  {
-    schemas.length > 0 &&
-      schemas.map((schema) => {
-        if (!schema.render) return null;
-        return (
-          <div>
-            {schema.exists && (
-              <div
-                id={`${schema.id}-${schema.file}-SchemaViewer-client`}
-                class="not-prose my-4"
-                data-expand={schema.expand ? 'true' : 'false'}
-                data-search={schema.search !== false ? 'true' : 'false'}
-              >
-                {schema.title && <h2 class="text-2xl font-bold mb-2 !mt-0">{schema.title}</h2>}
-
-                {/* Render AvroSchemaViewer for Avro schemas */}
-                {schema.isAvroSchema ? (
-                  <AvroSchemaViewer
-                    client:load
-                    schema={schema.schema}
-                    maxHeight={schema.maxHeight}
-                    expand={schema.expand}
-                    search={schema.search}
-                    showRequired={schema.showRequired}
-                  />
-                ) : (
-                  <JSONSchemaViewer
-                    client:load
-                    schema={schema.schema}
-                    maxHeight={schema.maxHeight}
-                    expand={schema.expand}
-                    search={schema.search}
-                  />
-                )}
-              </div>
-            )}
-
-            {/* User has tried to load the schema, but it was not found on file system */}
-            {!schema.exists && (
-              <Admonition type="warning">
-                <div>
-                  <span class="block font-bold">{`<SchemaViewer/>`} failed to load</span>
-                  <span class="block">Tried to load schema from {schema.schemaPath}, but no schema can be found</span>
-                </div>
-              </Admonition>
-            )}
-          </div>
-        );
-      })
-  }
-</section>
-
-<script is:inline define:vars={{ schemas }}>
-  // Can we move the SchemaViewerClient to another container? example container with the id "my-schema-viewer-container"
-  // and then we can move the SchemaViewerClient to that container?
-
-  function moveSchemaViewerToPortal(schema) {
-    const portalId = `${schema.id}-${schema.file}-SchemaViewer-portal`;
-    const schemaViewerContainer = document.getElementById(portalId);
-    const schemaViewerClient = document.getElementById(`${schema.id}-${schema.file}-SchemaViewer-client`);
-
-    if (schemaViewerContainer && schemaViewerClient) {
-      // Get attributes from the portal
-      const expand = schemaViewerContainer.getAttribute('data-expand') === 'true';
-      const maxHeight = schemaViewerContainer.getAttribute('data-max-height');
-      const search = schemaViewerContainer.getAttribute('data-search');
-
-      // Set the expand attribute on the schema viewer client
-      if (expand) {
-        schemaViewerClient.setAttribute('data-expand', 'true');
-      }
-
-      // Set the search attribute on the schema viewer client
-      if (search) {
-        schemaViewerClient.setAttribute('data-search', search);
-      }
-
-      // Set the maxHeight on the schema viewer element
-      if (maxHeight) {
-        const schemaViewerElement = schemaViewerClient.querySelector('.schema-viewer');
-        if (schemaViewerElement) {
-          schemaViewerElement.style.maxHeight = `${maxHeight}px`;
-        }
-      }
-
-      schemaViewerContainer.appendChild(schemaViewerClient);
-    }
-  }
-
-  // on DOM ready, move the SchemaViewerClient to the portal
-  document.addEventListener('DOMContentLoaded', () => {
-    schemas.forEach(moveSchemaViewerToPortal);
-  });
-
-  // on DOM ready, move the SchemaViewerClient to the portal
-  document.addEventListener('astro:page-load', () => {
-    schemas.forEach(moveSchemaViewerToPortal);
-  });
-</script>
diff --git a/eventcatalog/src/components/MDX/Tiles/Tile.astro b/eventcatalog/src/components/MDX/Tiles/Tile.astro
deleted file mode 100644
index a9a02f333..000000000
--- a/eventcatalog/src/components/MDX/Tiles/Tile.astro
+++ /dev/null
@@ -1,58 +0,0 @@
----
-import type { ComponentType } from 'react';
-import * as Icons from '@heroicons/react/24/solid';
-import { buildUrl } from '@utils/url-builder';
-
-interface Props {
-  href: string;
-  icon: keyof typeof Icons;
-  iconColor?: string;
-  title: string;
-  openWindow?: boolean;
-  description: string;
-}
-
-const { href, icon, title, description, openWindow, iconColor = 'text-primary' } = Astro.props;
-
-const IconComponent: ComponentType<{ className?: string }> | undefined = Icons[icon];
-
-function startsWithProtocol(str: string) {
-  // Regular expression to match common protocols (http, https, ftp, ws, etc.)
-  const regex = /^[a-zA-Z][a-zA-Z\d+\-.]*:\/\//;
-  return regex.test(str);
-}
----
-
-<div class="group">
-  <!-- Card with just the icon -->
-  <a
-    href={startsWithProtocol(href) ? href : buildUrl(href)}
-    target={openWindow ? '_blank' : '_self'}
-    class="block relative bg-white border border-gray-200 rounded-xl p-8 h-48 transition-all duration-300 ease-out hover:border-purple-300 hover:shadow-lg hover:shadow-purple-500/10 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2 overflow-hidden"
-  >
-    <!-- Icon centered in card with grid background -->
-    <div class="relative h-full flex items-center justify-center">
-      <!-- Squared paper grid behind icon -->
-      <div
-        class="absolute inset-0 opacity-15"
-        style="background-image:
-        linear-gradient(rgba(147, 51, 234, 0.2) 1px, transparent 1px),
-        linear-gradient(90deg, rgba(147, 51, 234, 0.2) 1px, transparent 1px);
-        background-size: 16px 16px;"
-      >
-      </div>
-
-      {IconComponent && <IconComponent className="relative w-16 h-16 text-purple-600 stroke-1" />}
-    </div>
-  </a>
-
-  <!-- Title and description outside card -->
-  <div class="mt-4 space-y-0">
-    <h2 class="text-gray-900 text-lg font-semibold">
-      {title}
-    </h2>
-    <p class="text-gray-600 text-sm leading-relaxed">
-      {description}
-    </p>
-  </div>
-</div>
diff --git a/eventcatalog/src/components/MDX/Tiles/Tiles.astro b/eventcatalog/src/components/MDX/Tiles/Tiles.astro
deleted file mode 100644
index 31ab25801..000000000
--- a/eventcatalog/src/components/MDX/Tiles/Tiles.astro
+++ /dev/null
@@ -1,10 +0,0 @@
----
-const { title, columns = 2 } = Astro.props;
----
-
-<section class="not-prose my-8">
-  {title && <h2 class="text-2xl font-bold text-gray-800 mb-6">{title}</h2>}
-  <div class={`grid grid-cols-1 md:grid-cols-${columns} gap-6 w-full not-prose`}>
-    <slot />
-  </div>
-</section>
diff --git a/eventcatalog/src/components/MDX/components.tsx b/eventcatalog/src/components/MDX/components.tsx
deleted file mode 100644
index 81d850edc..000000000
--- a/eventcatalog/src/components/MDX/components.tsx
+++ /dev/null
@@ -1,72 +0,0 @@
-// React components
-import Schema from '@components/MDX/Schema.astro';
-import File from '@components/MDX/File';
-import Accordion from '@components/MDX/Accordion/Accordion.astro';
-import AccordionGroup from '@components/MDX/Accordion/AccordionGroup.astro';
-import Flow from '@components/MDX/Flow/Flow.astro';
-import EntityMap from '@components/MDX/EntityMap/EntityMap.astro';
-import Tiles from '@components/MDX/Tiles/Tiles.astro';
-import Tile from '@components/MDX/Tiles/Tile.astro';
-import Steps from '@components/MDX/Steps/Steps.astro';
-import Step from '@components/MDX/Steps/Step.astro';
-import Admonition from '@components/MDX/Admonition';
-import OpenAPI from '@components/MDX/OpenAPI/OpenAPI.astro';
-import AsyncAPI from '@components/MDX/AsyncAPI/AsyncAPI.astro';
-import ChannelInformation from '@components/MDX/ChannelInformation/ChannelInformation';
-import Attachments from '@components/MDX/Attachments.astro';
-import MessageTable from '@components/MDX/MessageTable/MessageTable.astro';
-import ResourceGroupTable from '@components/MDX/ResourceGroupTable/ResourceGroupTable.astro';
-import EntityPropertiesTable from '@components/MDX/EntityPropertiesTable/EntityPropertiesTable.astro';
-import Tabs from '@components/MDX/Tabs/Tabs.astro';
-import TabItem from '@components/MDX/Tabs/TabItem.astro';
-import ResourceLink from '@components/MDX/ResourceLink/ResourceLink.astro';
-import Link from '@components/MDX/Link/Link.astro';
-import Miro from '@components/MDX/Miro/Miro.astro';
-import Lucid from '@components/MDX/Lucid/Lucid.astro';
-import DrawIO from '@components/MDX/DrawIO/DrawIO.astro';
-import FigJam from '@components/MDX/FigJam/FigJam.astro';
-import Design from '@components/MDX/Design/Design.astro';
-import MermaidFileLoader from '@components/MDX/MermaidFileLoader/MermaidFileLoader.astro';
-//  Portals: required for server/client components
-import NodeGraphPortal from '@components/MDX/NodeGraph/NodeGraphPortal';
-import SchemaViewerPortal from '@components/MDX/SchemaViewer/SchemaViewerPortal';
-import { jsx } from 'astro/jsx-runtime';
-import RemoteSchema from '@components/MDX/RemoteSchema.astro';
-
-const components = (props: any) => {
-  return {
-    Attachments: (mdxProp: any) => jsx(Attachments, { ...props, ...mdxProp }),
-    Accordion,
-    AccordionGroup,
-    Admonition,
-    AsyncAPI,
-    ChannelInformation: (mdxProp: any) => ChannelInformation({ ...props.data, ...mdxProp }),
-    Design: (mdxProp: any) => jsx(Design, { ...props, ...mdxProp }),
-    File: (mdxProp: any) => File({ ...props, ...mdxProp }),
-    RemoteSchema,
-    Flow,
-    Link: (mdxProp: any) => jsx(Link, { ...props, ...mdxProp }),
-    MessageTable: (mdxProp: any) => jsx(MessageTable, { ...props, ...mdxProp }),
-    EntityPropertiesTable: (mdxProp: any) => jsx(EntityPropertiesTable, { ...props, ...mdxProp }),
-    NodeGraph: (mdxProp: any) => jsx(NodeGraphPortal, { ...props.data, ...mdxProp, props, mdxProp }),
-    EntityMap: (mdxProp: any) => jsx(EntityMap, { ...props, ...mdxProp }),
-    OpenAPI,
-    ResourceGroupTable: (mdxProp: any) => jsx(ResourceGroupTable, { ...props, ...mdxProp }),
-    ResourceLink: (mdxProp: any) => jsx(ResourceLink, { ...props, ...mdxProp }),
-    Schema: (mdxProp: any) => jsx(Schema, { ...props, ...mdxProp }),
-    SchemaViewer: (mdxProp: any) => SchemaViewerPortal({ ...props.data, ...mdxProp }),
-    Step,
-    Steps,
-    TabItem,
-    Tabs,
-    Tile,
-    Tiles,
-    Miro: (mdxProp: any) => jsx(Miro, { ...props, ...mdxProp }),
-    Lucid: (mdxProp: any) => jsx(Lucid, { ...props, ...mdxProp }),
-    DrawIO: (mdxProp: any) => jsx(DrawIO, { ...props, ...mdxProp }),
-    FigJam: (mdxProp: any) => jsx(FigJam, { ...props, ...mdxProp }),
-    MermaidFileLoader: (mdxProp: any) => jsx(MermaidFileLoader, { ...props, ...mdxProp }),
-  };
-};
-
-export default components;
diff --git a/eventcatalog/src/components/SchemaExplorer/ApiAccessSection.tsx b/eventcatalog/src/components/SchemaExplorer/ApiAccessSection.tsx
deleted file mode 100644
index 29feb0e35..000000000
--- a/eventcatalog/src/components/SchemaExplorer/ApiAccessSection.tsx
+++ /dev/null
@@ -1,139 +0,0 @@
-import { ChevronUpIcon, ChevronDownIcon, ClipboardDocumentIcon } from '@heroicons/react/24/outline';
-import type { SchemaItem } from './types';
-
-interface ApiAccessSectionProps {
-  message: SchemaItem;
-  isExpanded: boolean;
-  onToggle: () => void;
-  onCopy: (content: string, id: string) => void;
-  copiedId: string | null;
-  apiAccessEnabled?: boolean;
-}
-
-export default function ApiAccessSection({
-  message,
-  isExpanded,
-  onToggle,
-  onCopy,
-  copiedId,
-  apiAccessEnabled = false,
-}: ApiAccessSectionProps) {
-  // Generate API path based on collection type
-  let apiPath = '';
-  if (message.collection === 'services') {
-    const specType = message.specType || 'openapi';
-    apiPath = `/api/schemas/services/${message.data.id}/${message.data.version}/${specType}`;
-  } else {
-    apiPath = `/api/schemas/${message.collection}/${message.data.id}/${message.data.version}`;
-  }
-
-  const curlCommand = typeof window !== 'undefined' ? `curl -X GET "${window.location.origin}${apiPath}"` : '';
-
-  return (
-    <div className="flex-shrink-0 border-b border-gray-200">
-      <button
-        onClick={onToggle}
-        className="w-full flex items-center justify-between px-4 py-1.5 text-left hover:bg-gray-50 transition-colors"
-      >
-        <div className="flex items-center gap-2">
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            className="h-4 w-4 text-gray-600"
-            fill="none"
-            viewBox="0 0 24 24"
-            stroke="currentColor"
-          >
-            <path
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              strokeWidth={2}
-              d="M8 9l3 3-3 3m5 0h3M5 20h14a2 2 0 002-2V6a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z"
-            />
-          </svg>
-          <span className="text-xs font-semibold text-gray-900">API Access</span>
-          <span className="inline-flex items-center rounded-full bg-purple-100 px-2 py-0.5 text-xs font-medium text-purple-800">
-            Scale
-          </span>
-        </div>
-        {isExpanded ? <ChevronUpIcon className="h-4 w-4 text-gray-600" /> : <ChevronDownIcon className="h-4 w-4 text-gray-600" />}
-      </button>
-
-      {isExpanded && (
-        <div className="px-4 pb-2 bg-gray-50">
-          {apiAccessEnabled ? (
-            <>
-              <p className="text-xs text-gray-600 mb-2">Access this schema programmatically via API</p>
-              <div className="bg-gray-900 rounded-md p-3">
-                <div className="flex items-start justify-between mb-2">
-                  <span className="text-xs text-gray-400 font-mono">GET</span>
-                  <button
-                    onClick={() => onCopy(curlCommand, `${message.data.id}-api`)}
-                    className="inline-flex items-center gap-1 px-2 py-1 text-xs font-medium text-gray-300 hover:text-white transition-colors"
-                    title="Copy curl command"
-                  >
-                    <ClipboardDocumentIcon className="h-3.5 w-3.5" />
-                    {copiedId === `${message.data.id}-api` ? 'Copied!' : 'Copy'}
-                  </button>
-                </div>
-                <code className="block text-xs text-green-400 font-mono break-all">{apiPath}</code>
-                <div className="mt-3 pt-3 border-t border-gray-700">
-                  <p className="text-xs text-gray-400 mb-2">Example:</p>
-                  <code className="block text-xs text-gray-300 font-mono whitespace-pre-wrap break-all">{curlCommand}</code>
-                </div>
-              </div>
-            </>
-          ) : (
-            <div className="bg-white border border-purple-200 rounded-md p-4">
-              <div className="flex items-start gap-3">
-                <div className="flex-shrink-0">
-                  <svg
-                    xmlns="http://www.w3.org/2000/svg"
-                    className="h-5 w-5 text-purple-600"
-                    fill="none"
-                    viewBox="0 0 24 24"
-                    stroke="currentColor"
-                  >
-                    <path
-                      strokeLinecap="round"
-                      strokeLinejoin="round"
-                      strokeWidth={2}
-                      d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z"
-                    />
-                  </svg>
-                </div>
-                <div className="flex-1">
-                  <h4 className="text-sm font-semibold text-gray-900 mb-1">Upgrade to Scale</h4>
-                  <p className="text-xs text-gray-600 mb-3">
-                    Access your schemas programmatically via API. Perfect for CI/CD pipelines, automation, and integrations.
-                  </p>
-                  <a
-                    href="https://eventcatalog.cloud"
-                    target="_blank"
-                    rel="noopener noreferrer"
-                    className="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium text-white bg-purple-600 rounded-md hover:bg-purple-700 transition-colors"
-                  >
-                    Start 14-day free trial
-                    <svg
-                      xmlns="http://www.w3.org/2000/svg"
-                      className="h-3.5 w-3.5"
-                      fill="none"
-                      viewBox="0 0 24 24"
-                      stroke="currentColor"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={2}
-                        d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"
-                      />
-                    </svg>
-                  </a>
-                </div>
-              </div>
-            </div>
-          )}
-        </div>
-      )}
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/DiffViewer.tsx b/eventcatalog/src/components/SchemaExplorer/DiffViewer.tsx
deleted file mode 100644
index 7c6f7cd2a..000000000
--- a/eventcatalog/src/components/SchemaExplorer/DiffViewer.tsx
+++ /dev/null
@@ -1,102 +0,0 @@
-import { ArrowsPointingOutIcon } from '@heroicons/react/24/outline';
-import type { VersionDiff } from './types';
-
-interface DiffViewerProps {
-  diffs: VersionDiff[];
-  onOpenFullscreen?: () => void;
-  apiAccessEnabled?: boolean;
-}
-
-export default function DiffViewer({ diffs, onOpenFullscreen, apiAccessEnabled = false }: DiffViewerProps) {
-  if (diffs.length === 0) return null;
-
-  return (
-    <div className="h-full overflow-auto p-4">
-      <div className="mb-4 flex items-start justify-between">
-        <div className="flex-1">
-          <h3 className="text-lg font-semibold text-gray-900 mb-2">Version History</h3>
-          <p className="text-sm text-gray-600">
-            {apiAccessEnabled
-              ? `Showing ${diffs.length} version comparison${diffs.length !== 1 ? 's' : ''}`
-              : 'Compare schema versions side-by-side'}
-          </p>
-        </div>
-        {onOpenFullscreen && apiAccessEnabled && (
-          <button
-            onClick={onOpenFullscreen}
-            className="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 transition-colors"
-            title="Open in fullscreen"
-          >
-            <ArrowsPointingOutIcon className="h-4 w-4" />
-            Fullscreen
-          </button>
-        )}
-      </div>
-      {apiAccessEnabled ? (
-        <div className="space-y-8">
-          {diffs.map((diff, index) => (
-            <div key={`${diff.newerVersion}-${diff.olderVersion}`} className="border border-gray-200 rounded-lg overflow-hidden">
-              <div className="bg-gray-50 border-b border-gray-200 px-4 py-3">
-                <div className="flex items-center justify-between">
-                  <div className="text-sm">
-                    <span className="font-semibold text-gray-900">v{diff.newerVersion}</span>
-                    <span className="text-gray-500 mx-2">→</span>
-                    <span className="font-semibold text-gray-900">v{diff.olderVersion}</span>
-                  </div>
-                  <span className="text-xs text-gray-500">
-                    {index === 0 ? 'Latest change' : `${index + 1} version${index + 1 !== 1 ? 's' : ''} ago`}
-                  </span>
-                </div>
-              </div>
-              <div className="bg-white relative">
-                <div dangerouslySetInnerHTML={{ __html: diff.diffHtml }} />
-              </div>
-            </div>
-          ))}
-        </div>
-      ) : (
-        <div className="bg-white border border-purple-200 rounded-lg p-8">
-          <div className="flex flex-col items-center text-center max-w-md mx-auto">
-            <div className="flex-shrink-0 mb-4">
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                className="h-16 w-16 text-purple-600"
-                fill="none"
-                viewBox="0 0 24 24"
-                stroke="currentColor"
-              >
-                <path
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  strokeWidth={2}
-                  d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
-                />
-              </svg>
-            </div>
-            <h4 className="text-xl font-semibold text-gray-900 mb-2">Upgrade to Scale</h4>
-            <p className="text-sm text-gray-600 mb-6">
-              Compare schema versions side-by-side with visual diffs. Track breaking changes, see exactly what changed between
-              versions, and maintain better schema governance.
-            </p>
-            <a
-              href="https://eventcatalog.cloud"
-              target="_blank"
-              rel="noopener noreferrer"
-              className="inline-flex items-center gap-2 px-4 py-2 text-sm font-medium text-white bg-purple-600 rounded-md hover:bg-purple-700 transition-colors"
-            >
-              Start 14-day free trial
-              <svg xmlns="http://www.w3.org/2000/svg" className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                <path
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  strokeWidth={2}
-                  d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"
-                />
-              </svg>
-            </a>
-          </div>
-        </div>
-      )}
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/JSONSchemaViewer.tsx b/eventcatalog/src/components/SchemaExplorer/JSONSchemaViewer.tsx
deleted file mode 100644
index 833e65838..000000000
--- a/eventcatalog/src/components/SchemaExplorer/JSONSchemaViewer.tsx
+++ /dev/null
@@ -1,740 +0,0 @@
-import { useState, useEffect, useRef, useMemo } from 'react';
-
-interface JSONSchemaViewerProps {
-  schema: any;
-  title?: string;
-  maxHeight?: string;
-  expand?: boolean | string;
-  search?: boolean | string;
-  id?: string;
-  onOpenFullscreen?: () => void;
-}
-
-interface SchemaPropertyProps {
-  name: string;
-  details: any;
-  isRequired: boolean;
-  level: number;
-  isListItem?: boolean;
-  expand: boolean;
-}
-
-// Helper function to count properties recursively
-function countProperties(obj: any): number {
-  if (!obj || typeof obj !== 'object') return 0;
-
-  let count = 0;
-  if (obj.properties) {
-    count += Object.keys(obj.properties).length;
-    Object.values(obj.properties).forEach((prop: any) => {
-      count += countProperties(prop);
-    });
-  }
-  if (obj.items) {
-    count += countProperties(obj.items);
-  }
-  if (obj._isRootArrayItem && obj._rootArraySchema?.items) {
-    // Don't double count
-  }
-  return count;
-}
-
-// Schema processing functions
-function mergeAllOfSchemas(schemaWithProcessor: any): any {
-  const { processSchema: processor, ...schema } = schemaWithProcessor;
-  if (!schema.allOf) return schema;
-
-  const mergedSchema: {
-    type: string;
-    properties: Record<string, any>;
-    required: string[];
-    description?: string;
-    [key: string]: any;
-  } = {
-    type: schema.type || 'object',
-    properties: {},
-    required: [],
-    description: schema.description,
-  };
-
-  // Copy base schema properties first (excluding allOf)
-  Object.keys(schema).forEach((key) => {
-    if (key !== 'allOf' && key !== 'properties' && key !== 'required' && key !== 'description') {
-      mergedSchema[key] = schema[key];
-    }
-  });
-
-  // Copy base properties if they exist
-  if (schema.properties) {
-    mergedSchema.properties = { ...schema.properties };
-  }
-  if (schema.required) {
-    mergedSchema.required = [...schema.required];
-  }
-
-  schema.allOf.forEach((subSchema: any) => {
-    const processedSubSchema = processor ? processor(subSchema) : subSchema;
-
-    if (processedSubSchema.properties) {
-      mergedSchema.properties = {
-        ...mergedSchema.properties,
-        ...processedSubSchema.properties,
-      };
-    }
-    if (processedSubSchema.required) {
-      mergedSchema.required = [...new Set([...mergedSchema.required, ...processedSubSchema.required])];
-    }
-    if (processedSubSchema.description && !mergedSchema.description) {
-      mergedSchema.description = processedSubSchema.description;
-    }
-
-    Object.keys(processedSubSchema).forEach((key) => {
-      if (key !== 'properties' && key !== 'required' && key !== 'description' && key !== 'type') {
-        if (!mergedSchema[key]) {
-          mergedSchema[key] = processedSubSchema[key];
-        }
-      }
-    });
-  });
-
-  return mergedSchema;
-}
-
-function processSchema(schema: any, rootSchema?: any): any {
-  if (!schema) return schema;
-
-  const root = rootSchema || schema;
-
-  // Handle $ref
-  if (schema.$ref) {
-    const refPath = schema.$ref;
-    let resolvedSchema = null;
-    let defName = '';
-
-    // Try draft-7 style first: #/definitions/
-    if (refPath.startsWith('#/definitions/')) {
-      defName = refPath.replace('#/definitions/', '');
-      if (root.definitions && root.definitions[defName]) {
-        resolvedSchema = root.definitions[defName];
-      }
-    }
-    // Try 2020-12 style: #/$defs/
-    else if (refPath.startsWith('#/$defs/')) {
-      defName = refPath.replace('#/$defs/', '');
-      if (root.$defs && root.$defs[defName]) {
-        resolvedSchema = root.$defs[defName];
-      }
-    }
-    // Try other common patterns
-    else if (refPath.startsWith('#/components/schemas/')) {
-      defName = refPath.replace('#/components/schemas/', '');
-      if (root.components && root.components.schemas && root.components.schemas[defName]) {
-        resolvedSchema = root.components.schemas[defName];
-      }
-    }
-
-    if (resolvedSchema) {
-      const processedSchema = processSchema(resolvedSchema, root);
-      return {
-        ...processedSchema,
-        _refPath: refPath,
-        _refName: defName,
-        _originalRef: schema.$ref,
-      };
-    }
-
-    return {
-      type: 'string',
-      description: `Reference to ${refPath} (definition not found in root schema)`,
-      title: defName || refPath.split('/').pop(),
-      _refPath: refPath,
-      _refName: defName,
-      _refNotFound: true,
-    };
-  }
-
-  if (schema.allOf) {
-    return mergeAllOfSchemas({ ...schema, processSchema: (s: any) => processSchema(s, root) });
-  }
-
-  if (schema.oneOf) {
-    const processedVariants = schema.oneOf.map((variant: any) => {
-      const processedVariant = processSchema(variant, root);
-      return {
-        title: processedVariant.title || variant.title || 'Unnamed Variant',
-        required: processedVariant.required || variant.required || [],
-        properties: processedVariant.properties || {},
-        ...processedVariant,
-      };
-    });
-
-    const allProperties: Record<string, any> = {};
-    processedVariants.forEach((variant: any) => {
-      if (variant.properties) {
-        Object.assign(allProperties, variant.properties);
-      }
-    });
-
-    return {
-      ...schema,
-      type: schema.type || 'object',
-      properties: {
-        ...(schema.properties || {}),
-        ...allProperties,
-      },
-      variants: processedVariants,
-    };
-  }
-
-  // Process nested schemas in properties
-  if (schema.properties) {
-    const processedProperties: Record<string, any> = {};
-    Object.entries(schema.properties).forEach(([key, prop]: [string, any]) => {
-      processedProperties[key] = processSchema(prop, root);
-    });
-    schema = { ...schema, properties: processedProperties };
-  }
-
-  // Process array items
-  if (schema.type === 'array' && schema.items) {
-    schema = { ...schema, items: processSchema(schema.items, root) };
-  }
-
-  return schema;
-}
-
-// SchemaProperty component
-const SchemaProperty = ({ name, details, isRequired, level, isListItem = false, expand }: SchemaPropertyProps) => {
-  const [isExpanded, setIsExpanded] = useState(expand);
-  const contentId = useRef(`prop-${name}-${level}-${Math.random().toString(36).substring(2, 7)}`).current;
-
-  useEffect(() => {
-    setIsExpanded(expand);
-  }, [expand]);
-
-  const hasNestedProperties = details.type === 'object' && details.properties && Object.keys(details.properties).length > 0;
-  const hasArrayItems = details.type === 'array' && details.items;
-  const hasArrayItemProperties =
-    hasArrayItems &&
-    ((details.items.type === 'object' && details.items.properties) ||
-      details.items.allOf ||
-      details.items.oneOf ||
-      details.items.$ref);
-  const isCollapsible = hasNestedProperties || hasArrayItemProperties;
-
-  const indentationClass = `pl-${level * 3}`;
-
-  return (
-    <div className={`property-container mb-1.5 border-l border-gray-100 relative ${indentationClass}`}>
-      <div className="flex items-start space-x-1.5">
-        {isCollapsible ? (
-          <button
-            type="button"
-            aria-expanded={isExpanded}
-            aria-controls={contentId}
-            onClick={() => setIsExpanded(!isExpanded)}
-            className="property-toggle text-gray-500 hover:text-gray-700 pt-0.5 focus:outline-none w-3 text-center flex-shrink-0"
-          >
-            <span className={`icon-collapsed font-mono text-xs ${isExpanded ? 'hidden' : ''}`}>&gt;</span>
-            <span className={`icon-expanded font-mono text-xs ${!isExpanded ? 'hidden' : ''}`}>v</span>
-          </button>
-        ) : (
-          <div className="w-3 h-4 flex-shrink-0" />
-        )}
-
-        <div className="flex-grow">
-          <div className="flex justify-between items-baseline">
-            <div>
-              <span className="font-semibold text-gray-800 text-sm">{name}</span>
-              <span className="ml-1.5 text-purple-600 font-mono text-xs">
-                {details.type}
-                {details.type === 'array' && details.items?.type ? `[${details.items.type}]` : ''}
-                {details.format ? `<${details.format}>` : ''}
-                {details._refPath && <span className="text-blue-600 ml-1">→ {details._refName || details._refPath}</span>}
-                {details._refNotFound && <span className="text-red-600 ml-1">❌ ref not found</span>}
-                {details.const !== undefined && (
-                  <span>
-                    constant: <code>{details.const}</code>
-                  </span>
-                )}
-              </span>
-            </div>
-            {isRequired && <span className="text-red-600 text-xs ml-3 flex-shrink-0">required</span>}
-          </div>
-
-          {details.description && <p className="text-gray-500 text-xs mt-0.5">{details.description}</p>}
-          {details.title && details.title !== details.description && (
-            <p className="text-gray-500 text-xs mt-0.5 italic">Title: {details.title}</p>
-          )}
-
-          <div className="text-xs text-gray-500 mt-0.5 space-y-0">
-            {details.pattern && (
-              <div>
-                Match pattern: <code className="bg-gray-100 px-1 rounded text-gray-800 font-thin py-0.5">{details.pattern}</code>
-              </div>
-            )}
-            {details.minimum !== undefined && (
-              <div>
-                Minimum: <code className="bg-gray-100 px-1 rounded text-gray-800 font-thin py-0.5">{details.minimum}</code>
-              </div>
-            )}
-            {details.maximum !== undefined && (
-              <div>
-                Maximum: <code className="bg-gray-100 px-1 rounded text-gray-800 font-thin py-0.5">{details.maximum}</code>
-              </div>
-            )}
-            {details.minLength !== undefined && (
-              <div>
-                Min length: <code className="bg-gray-100 px-1 rounded text-gray-800 font-thin py-0.5">{details.minLength}</code>
-              </div>
-            )}
-            {details.maxLength !== undefined && (
-              <div>
-                Max length: <code className="bg-gray-100 px-1 rounded text-gray-800 font-thin py-0.5">{details.maxLength}</code>
-              </div>
-            )}
-            {details.enum && (
-              <div>
-                <span className="text-xs inline-block">Allowed values:</span>
-                {details.enum.map((val: any, idx: number) => (
-                  <span key={idx} className="text-xs">
-                    {' '}
-                    <code className="bg-gray-100 px-1 rounded text-gray-800 font-thin py-0.5">{val}</code>
-                  </span>
-                ))}
-              </div>
-            )}
-          </div>
-
-          {(hasNestedProperties || hasArrayItems) && (
-            <div id={contentId} className={`nested-content mt-1 ${isCollapsible && !isExpanded ? 'hidden' : ''}`}>
-              {hasNestedProperties &&
-                details.properties &&
-                Object.entries(details.properties).map(([nestedName, nestedDetails]: [string, any]) => (
-                  <SchemaProperty
-                    key={nestedName}
-                    name={nestedName}
-                    details={nestedDetails}
-                    isRequired={details.required?.includes(nestedName) ?? false}
-                    level={level + 1}
-                    expand={expand}
-                  />
-                ))}
-
-              {hasArrayItemProperties && (
-                <div className="mt-1 border-l border-dashed border-gray-400 pl-3 ml-1.5">
-                  <span className="text-xs italic text-gray-500 block mb-1">Item Details:</span>
-                  {details.items.properties &&
-                    Object.entries(details.items.properties).map(([itemPropName, itemPropDetails]: [string, any]) => (
-                      <SchemaProperty
-                        key={itemPropName}
-                        name={itemPropName}
-                        details={itemPropDetails}
-                        isRequired={details.items.required?.includes(itemPropName) ?? false}
-                        level={level + 1}
-                        isListItem={true}
-                        expand={expand}
-                      />
-                    ))}
-                  {(details.items.allOf || details.items.oneOf || details.items.$ref) && !details.items.properties && (
-                    <div className="text-xs text-gray-500 mt-1">
-                      Complex array item schema detected. The properties should be processed by the parent SchemaViewer.
-                    </div>
-                  )}
-                </div>
-              )}
-            </div>
-          )}
-        </div>
-      </div>
-    </div>
-  );
-};
-
-// Main JSONSchemaViewer component
-export default function JSONSchemaViewer({
-  schema,
-  title,
-  maxHeight,
-  expand = false,
-  search = true,
-  id,
-  onOpenFullscreen,
-}: JSONSchemaViewerProps) {
-  // Convert string props to booleans (MDX passes strings)
-  const expandBool = expand === true || expand === 'true';
-  const searchBool = search !== false && search !== 'false';
-
-  const [searchQuery, setSearchQuery] = useState('');
-  const [expandAll, setExpandAll] = useState(expandBool);
-  const [selectedVariantIndex, setSelectedVariantIndex] = useState(0);
-  const [currentMatches, setCurrentMatches] = useState<HTMLElement[]>([]);
-  const [currentMatchIndex, setCurrentMatchIndex] = useState(-1);
-  const searchInputRef = useRef<HTMLInputElement>(null);
-  const propertiesContainerRef = useRef<HTMLDivElement>(null);
-
-  const processedSchema = useMemo(() => processSchema(schema), [schema]);
-
-  // Handle root-level array schemas
-  const { displaySchema, isRootArray } = useMemo(() => {
-    let display = processedSchema;
-    let isArray = false;
-
-    if (processedSchema.type === 'array' && processedSchema.items) {
-      isArray = true;
-      if (processedSchema.items.type === 'object' && processedSchema.items.properties) {
-        display = {
-          ...processedSchema.items,
-          description: processedSchema.description || processedSchema.items.description,
-          _isRootArrayItem: true,
-          _rootArraySchema: processedSchema,
-        };
-      } else if (processedSchema.items.allOf || processedSchema.items.oneOf || processedSchema.items.$ref) {
-        display = {
-          ...processSchema(processedSchema.items),
-          description: processedSchema.description || processedSchema.items.description,
-          _isRootArrayItem: true,
-          _rootArraySchema: processedSchema,
-        };
-      }
-    }
-
-    return { displaySchema: display, isRootArray: isArray };
-  }, [processedSchema]);
-
-  const { description, properties, required = [], variants } = displaySchema;
-  const totalProperties = useMemo(() => countProperties(displaySchema), [displaySchema]);
-
-  // Search functionality
-  useEffect(() => {
-    if (!propertiesContainerRef.current) return;
-
-    const propertyContainers = propertiesContainerRef.current.querySelectorAll('.property-container');
-    const matches: HTMLElement[] = [];
-
-    if (searchQuery === '') {
-      // Reset search
-      propertyContainers.forEach((container) => {
-        container.classList.remove('search-match', 'search-no-match', 'search-current-match', 'search-dimmed');
-        const nameEl = container.querySelector('.font-semibold');
-        if (nameEl) {
-          nameEl.innerHTML = nameEl.textContent || '';
-        }
-      });
-      setCurrentMatches([]);
-      setCurrentMatchIndex(-1);
-      return;
-    }
-
-    const query = searchQuery.toLowerCase().trim();
-
-    propertyContainers.forEach((container) => {
-      const nameEl = container.querySelector('.font-semibold');
-      if (!nameEl) return;
-
-      const propName = (nameEl.textContent || '').toLowerCase();
-
-      if (propName.includes(query)) {
-        container.classList.add('search-match');
-        container.classList.remove('search-dimmed');
-        matches.push(container as HTMLElement);
-
-        // Highlight the search term
-        const regex = new RegExp(`(${query})`, 'gi');
-        nameEl.innerHTML = (nameEl.textContent || '').replace(regex, '<mark class="bg-yellow-200 rounded px-0.5">$1</mark>');
-
-        // Expand parent containers and remove dimming from them
-        let parent = container.parentElement;
-        while (parent && parent !== propertiesContainerRef.current) {
-          if (parent.classList.contains('nested-content') && parent.classList.contains('hidden')) {
-            const parentPropertyContainer = parent.closest('.property-container');
-            if (parentPropertyContainer) {
-              const toggleBtn = parentPropertyContainer.querySelector('.property-toggle');
-              if (toggleBtn && toggleBtn.getAttribute('aria-expanded') === 'false') {
-                (toggleBtn as HTMLButtonElement).click();
-              }
-            }
-          }
-          // Remove dimming from parent property containers so they're fully visible
-          if (parent.classList.contains('property-container')) {
-            parent.classList.remove('search-dimmed');
-          }
-          parent = parent.parentElement;
-        }
-      } else {
-        container.classList.remove('search-match', 'search-current-match');
-        container.classList.add('search-dimmed');
-        nameEl.innerHTML = nameEl.textContent || '';
-      }
-    });
-
-    setCurrentMatches(matches);
-    if (matches.length > 0) {
-      setCurrentMatchIndex(0);
-      matches[0].scrollIntoView({ behavior: 'smooth', block: 'center' });
-    } else {
-      setCurrentMatchIndex(-1);
-    }
-  }, [searchQuery]);
-
-  // Update match highlighting
-  useEffect(() => {
-    currentMatches.forEach((match, index) => {
-      if (index === currentMatchIndex) {
-        match.classList.add('search-current-match');
-      } else {
-        match.classList.remove('search-current-match');
-      }
-    });
-
-    if (currentMatchIndex >= 0 && currentMatches[currentMatchIndex]) {
-      currentMatches[currentMatchIndex].scrollIntoView({ behavior: 'smooth', block: 'center' });
-    }
-  }, [currentMatchIndex, currentMatches]);
-
-  const handleExpandAll = () => {
-    setExpandAll(true);
-  };
-
-  const handleCollapseAll = () => {
-    setExpandAll(false);
-  };
-
-  const handlePrevMatch = () => {
-    if (currentMatchIndex > 0) {
-      setCurrentMatchIndex(currentMatchIndex - 1);
-    }
-  };
-
-  const handleNextMatch = () => {
-    if (currentMatchIndex < currentMatches.length - 1) {
-      setCurrentMatchIndex(currentMatchIndex + 1);
-    }
-  };
-
-  if (!schema) {
-    return (
-      <div className="flex items-center justify-center h-full text-gray-500 p-8">
-        <p className="text-sm">Unable to parse JSON schema</p>
-      </div>
-    );
-  }
-
-  const containerStyle = maxHeight
-    ? {
-        maxHeight: maxHeight.includes('px') ? maxHeight : `${maxHeight}px`,
-        minHeight: '15em',
-      }
-    : {};
-
-  // Use h-full when no maxHeight (SchemaExplorer context), otherwise size based on content (MDX context)
-  const heightClass = maxHeight ? '' : 'h-full';
-  const overflowClass = maxHeight ? 'overflow-hidden' : '';
-
-  return (
-    <div
-      id={id}
-      className={`${heightClass} ${overflowClass} flex flex-col bg-white border border-gray-100 rounded-md shadow-sm`}
-      style={containerStyle}
-    >
-      {/* Toolbar */}
-      {searchBool && (
-        <div className="flex-shrink-0 bg-white pt-4 px-4 mb-4 pb-3 border-b border-gray-100 shadow-sm">
-          <div className="flex flex-col sm:flex-row gap-3">
-            <div className="flex-1 relative">
-              <input
-                ref={searchInputRef}
-                type="text"
-                value={searchQuery}
-                onChange={(e) => setSearchQuery(e.target.value)}
-                placeholder="Search properties..."
-                className="w-full px-3 py-1.5 pr-20 text-sm border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
-                onKeyDown={(e) => {
-                  if (e.key === 'Enter') {
-                    e.preventDefault();
-                    if (e.shiftKey) {
-                      handlePrevMatch();
-                    } else {
-                      handleNextMatch();
-                    }
-                  }
-                }}
-              />
-              <div className="absolute right-2 top-1/2 transform -translate-y-1/2 flex items-center gap-1">
-                <button
-                  onClick={handlePrevMatch}
-                  disabled={currentMatches.length === 0 || currentMatchIndex <= 0}
-                  className="p-1 text-gray-400 hover:text-gray-600 disabled:opacity-30 disabled:cursor-not-allowed"
-                  title="Previous match"
-                >
-                  <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M15 19l-7-7 7-7" />
-                  </svg>
-                </button>
-                <button
-                  onClick={handleNextMatch}
-                  disabled={currentMatches.length === 0 || currentMatchIndex >= currentMatches.length - 1}
-                  className="p-1 text-gray-400 hover:text-gray-600 disabled:opacity-30 disabled:cursor-not-allowed"
-                  title="Next match"
-                >
-                  <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M9 5l7 7-7 7" />
-                  </svg>
-                </button>
-              </div>
-            </div>
-            <div className="flex items-center gap-2">
-              {onOpenFullscreen && (
-                <button
-                  onClick={onOpenFullscreen}
-                  className="px-3 py-1.5 text-xs font-medium text-gray-700 bg-gray-100 rounded-md hover:bg-gray-200 focus:outline-none focus:ring-2 focus:ring-gray-500"
-                  title="Open in fullscreen"
-                >
-                  <svg
-                    xmlns="http://www.w3.org/2000/svg"
-                    className="h-3.5 w-3.5 inline-block"
-                    fill="none"
-                    viewBox="0 0 24 24"
-                    stroke="currentColor"
-                  >
-                    <path
-                      strokeLinecap="round"
-                      strokeLinejoin="round"
-                      strokeWidth={2}
-                      d="M4 8V4m0 0h4M4 4l5 5m11-1V4m0 0h-4m4 0l-5 5M4 16v4m0 0h4m-4 0l5-5m11 5l-5-5m5 5v-4m0 4h-4"
-                    />
-                  </svg>
-                </button>
-              )}
-              <button
-                onClick={handleExpandAll}
-                className="px-3 py-1.5 text-xs font-medium text-gray-700 bg-gray-100 rounded-md hover:bg-gray-200 focus:outline-none focus:ring-2 focus:ring-gray-500"
-              >
-                Expand All
-              </button>
-              <button
-                onClick={handleCollapseAll}
-                className="px-3 py-1.5 text-xs font-medium text-gray-700 bg-gray-100 rounded-md hover:bg-gray-200 focus:outline-none focus:ring-2 focus:ring-gray-500"
-              >
-                Collapse All
-              </button>
-              <div className="text-xs text-gray-500">
-                {totalProperties} {totalProperties === 1 ? 'property' : 'properties'}
-              </div>
-            </div>
-          </div>
-          {searchQuery && (
-            <div className="mt-2 text-xs text-gray-600">
-              {currentMatches.length > 0
-                ? `${currentMatchIndex + 1} of ${currentMatches.length} ${currentMatches.length === 1 ? 'match' : 'matches'}`
-                : 'No properties found'}
-            </div>
-          )}
-        </div>
-      )}
-
-      {/* Content */}
-      <div className="flex-1 px-4 pb-4 overflow-auto">
-        {isRootArray && (
-          <div className="mb-4 p-3 bg-blue-50 border border-blue-200 rounded-md">
-            <div className="flex items-center space-x-2">
-              <span className="text-blue-600 font-medium text-sm">Array Schema</span>
-              <span className="text-blue-500 font-mono text-xs">array[object]</span>
-            </div>
-            <p className="text-blue-700 text-xs mt-1">
-              This schema defines an array of objects. Each item in the array has the properties shown below.
-            </p>
-          </div>
-        )}
-        {description && <p className="text-gray-600 text-xs mb-5">{description}</p>}
-
-        {variants && (
-          <div className="mb-4">
-            <div className="flex items-center space-x-2">
-              <span className="text-sm text-gray-600">(one of)</span>
-              <select
-                value={selectedVariantIndex}
-                onChange={(e) => setSelectedVariantIndex(parseInt(e.target.value))}
-                className="form-select text-sm border-gray-300 rounded-md shadow-sm focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50"
-              >
-                {variants.map((variant: any, index: number) => (
-                  <option key={index} value={index}>
-                    {variant.title}
-                  </option>
-                ))}
-              </select>
-            </div>
-          </div>
-        )}
-
-        {properties ? (
-          <div ref={propertiesContainerRef}>
-            {Object.entries(properties).map(([name, details]: [string, any]) => (
-              <SchemaProperty
-                key={name}
-                name={name}
-                details={details}
-                isRequired={
-                  variants ? variants[selectedVariantIndex]?.required?.includes(name) || false : required.includes(name)
-                }
-                level={0}
-                expand={expandAll}
-              />
-            ))}
-          </div>
-        ) : !isRootArray ? (
-          <p className="text-gray-500 text-sm">Schema does not contain any properties.</p>
-        ) : (
-          <div className="text-center py-8">
-            <div className="text-gray-500 text-sm">
-              <p>
-                This array contains items of type:{' '}
-                <span className="font-mono text-blue-600">{processedSchema.items?.type || 'unknown'}</span>
-              </p>
-              {processedSchema.items?.description && (
-                <p className="text-xs mt-2 text-gray-600">{processedSchema.items.description}</p>
-              )}
-            </div>
-          </div>
-        )}
-
-        {searchQuery && currentMatches.length === 0 && (
-          <div className="text-center py-8">
-            <div className="text-gray-400 text-sm">
-              <svg className="mx-auto h-12 w-12 mb-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                <path
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  strokeWidth="2"
-                  d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
-                />
-              </svg>
-              <p>No properties match your search</p>
-              <p className="text-xs mt-1">Try a different search term or clear the search to see all properties</p>
-            </div>
-          </div>
-        )}
-      </div>
-
-      <style>{`
-        .search-dimmed {
-          opacity: 0.4;
-          transition: opacity 0.2s ease;
-        }
-
-        .search-match {
-          opacity: 1;
-          transition: opacity 0.2s ease;
-        }
-
-        .search-current-match {
-          background-color: rgba(59, 130, 246, 0.1);
-          border-left: 3px solid #3b82f6;
-          padding-left: 8px;
-          margin-left: -11px;
-          transition: all 0.2s ease;
-        }
-      `}</style>
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/OwnersSection.tsx b/eventcatalog/src/components/SchemaExplorer/OwnersSection.tsx
deleted file mode 100644
index 77d7e3ab3..000000000
--- a/eventcatalog/src/components/SchemaExplorer/OwnersSection.tsx
+++ /dev/null
@@ -1,56 +0,0 @@
-import { ChevronUpIcon, ChevronDownIcon } from '@heroicons/react/24/outline';
-import { UserIcon, UserGroupIcon } from '@heroicons/react/20/solid';
-import type { SchemaItem, Owner } from './types';
-
-interface OwnersSectionProps {
-  message: SchemaItem;
-  isExpanded: boolean;
-  onToggle: () => void;
-}
-
-export default function OwnersSection({ message, isExpanded, onToggle }: OwnersSectionProps) {
-  const owners = message.data.owners || [];
-
-  if (owners.length === 0) return null;
-
-  return (
-    <div className="flex-shrink-0 border-b border-gray-200">
-      <button
-        onClick={onToggle}
-        className="w-full flex items-center justify-between px-4 py-1.5 text-left hover:bg-gray-50 transition-colors"
-      >
-        <div className="flex items-center gap-2">
-          <UserIcon className="h-4 w-4 text-gray-600" />
-          <span className="text-xs font-semibold text-gray-900">Owners</span>
-          <span className="inline-flex items-center rounded-full bg-gray-100 px-2 py-0.5 text-xs font-medium text-gray-700">
-            {owners.length}
-          </span>
-        </div>
-        {isExpanded ? <ChevronUpIcon className="h-4 w-4 text-gray-600" /> : <ChevronDownIcon className="h-4 w-4 text-gray-600" />}
-      </button>
-
-      {isExpanded && (
-        <div className="px-4 pb-2 bg-gray-50">
-          <div className="flex flex-wrap gap-2">
-            {owners.map((owner: Owner, idx: number) => {
-              const Icon = owner.type === 'users' ? UserIcon : UserGroupIcon;
-              return (
-                <a
-                  key={`${owner.id}-${idx}`}
-                  href={owner.href}
-                  className="inline-flex items-center gap-1.5 pl-1 pr-3 py-1 text-xs font-medium text-gray-700 bg-white border border-gray-200 rounded-full hover:border-gray-300 hover:shadow-sm transition-all"
-                  title={owner.name}
-                >
-                  <div className="flex items-center justify-center w-5 h-5 bg-gradient-to-b from-purple-500 to-purple-600 rounded-full">
-                    <Icon className="h-3 w-3 text-white" />
-                  </div>
-                  <span className="font-medium">{owner.name}</span>
-                </a>
-              );
-            })}
-          </div>
-        </div>
-      )}
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/Pagination.tsx b/eventcatalog/src/components/SchemaExplorer/Pagination.tsx
deleted file mode 100644
index 3e8a8ecbb..000000000
--- a/eventcatalog/src/components/SchemaExplorer/Pagination.tsx
+++ /dev/null
@@ -1,33 +0,0 @@
-interface PaginationProps {
-  currentPage: number;
-  totalPages: number;
-  onPageChange: (page: number) => void;
-}
-
-export default function Pagination({ currentPage, totalPages, onPageChange }: PaginationProps) {
-  if (totalPages <= 1) return null;
-
-  return (
-    <div className="flex-shrink-0 border-t border-gray-200 p-3 bg-gray-50">
-      <div className="flex items-center justify-between text-xs">
-        <button
-          onClick={() => onPageChange(Math.max(1, currentPage - 1))}
-          disabled={currentPage === 1}
-          className="px-3 py-1.5 text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 disabled:opacity-50 disabled:cursor-not-allowed"
-        >
-          Previous
-        </button>
-        <span className="text-gray-600">
-          Page {currentPage} of {totalPages}
-        </span>
-        <button
-          onClick={() => onPageChange(Math.min(totalPages, currentPage + 1))}
-          disabled={currentPage === totalPages}
-          className="px-3 py-1.5 text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 disabled:opacity-50 disabled:cursor-not-allowed"
-        >
-          Next
-        </button>
-      </div>
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/ProducersConsumersSection.tsx b/eventcatalog/src/components/SchemaExplorer/ProducersConsumersSection.tsx
deleted file mode 100644
index 0312eb88a..000000000
--- a/eventcatalog/src/components/SchemaExplorer/ProducersConsumersSection.tsx
+++ /dev/null
@@ -1,91 +0,0 @@
-import { ChevronUpIcon, ChevronDownIcon } from '@heroicons/react/24/outline';
-import { ServerIcon } from '@heroicons/react/20/solid';
-import { buildUrl } from '@utils/url-builder';
-import type { SchemaItem, Producer, Consumer } from './types';
-
-interface ProducersConsumersSectionProps {
-  message: SchemaItem;
-  isExpanded: boolean;
-  onToggle: () => void;
-}
-
-export default function ProducersConsumersSection({ message, isExpanded, onToggle }: ProducersConsumersSectionProps) {
-  const producers = message.data.producers || [];
-  const consumers = message.data.consumers || [];
-  const totalCount = producers.length + consumers.length;
-
-  if (totalCount === 0) return null;
-
-  return (
-    <div className="flex-shrink-0 border-b border-gray-200">
-      <button
-        onClick={onToggle}
-        className="w-full flex items-center justify-between px-4 py-1.5 text-left hover:bg-gray-50 transition-colors"
-      >
-        <div className="flex items-center gap-2">
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            className="h-4 w-4 text-gray-600"
-            fill="none"
-            viewBox="0 0 24 24"
-            stroke="currentColor"
-          >
-            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 10V3L4 14h7v7l9-11h-7z" />
-          </svg>
-          <span className="text-xs font-semibold text-gray-900">Producers & Consumers</span>
-          <span className="inline-flex items-center rounded-full bg-gray-100 px-2 py-0.5 text-xs font-medium text-gray-700">
-            {totalCount} services
-          </span>
-        </div>
-        {isExpanded ? <ChevronUpIcon className="h-4 w-4 text-gray-600" /> : <ChevronDownIcon className="h-4 w-4 text-gray-600" />}
-      </button>
-
-      {isExpanded && (
-        <div className="px-4 pb-2 bg-gray-50">
-          {producers.length > 0 && (
-            <div className="mb-3">
-              <h4 className="text-xs font-semibold text-gray-900 mb-2">Producers ({producers.length})</h4>
-              <div className="flex flex-wrap gap-2">
-                {producers.map((producer: Producer, idx: number) => (
-                  <a
-                    key={`${producer.id}-${idx}`}
-                    href={buildUrl(`/docs/services/${producer.id}/${producer.version}`)}
-                    className="inline-flex items-center gap-1.5 pl-1 pr-3 py-1 text-xs font-medium text-gray-700 bg-white border border-gray-200 rounded-full hover:border-gray-300 hover:shadow-sm transition-all"
-                    title={`View ${producer.id}`}
-                  >
-                    <div className="flex items-center justify-center w-5 h-5 bg-gradient-to-b from-pink-500 to-pink-600 rounded-full">
-                      <ServerIcon className="h-3 w-3 text-white" />
-                    </div>
-                    <span className="font-medium">{producer.id}</span>
-                    <span className="text-gray-500 text-[11px]">v{producer.version}</span>
-                  </a>
-                ))}
-              </div>
-            </div>
-          )}
-          {consumers.length > 0 && (
-            <div>
-              <h4 className="text-xs font-semibold text-gray-900 mb-2">Consumers ({consumers.length})</h4>
-              <div className="flex flex-wrap gap-2">
-                {consumers.map((consumer: Consumer, idx: number) => (
-                  <a
-                    key={`${consumer.id}-${idx}`}
-                    href={buildUrl(`/docs/services/${consumer.id}/${consumer.version}`)}
-                    className="inline-flex items-center gap-1.5 pl-1 pr-3 py-1 text-xs font-medium text-gray-700 bg-white border border-gray-200 rounded-full hover:border-gray-300 hover:shadow-sm transition-all"
-                    title={`View ${consumer.id}`}
-                  >
-                    <div className="flex items-center justify-center w-5 h-5 bg-gradient-to-b from-pink-500 to-pink-600 rounded-full">
-                      <ServerIcon className="h-3 w-3 text-white" />
-                    </div>
-                    <span className="font-medium">{consumer.id}</span>
-                    <span className="text-gray-500 text-[11px]">v{consumer.version}</span>
-                  </a>
-                ))}
-              </div>
-            </div>
-          )}
-        </div>
-      )}
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/SchemaCodeModal.tsx b/eventcatalog/src/components/SchemaExplorer/SchemaCodeModal.tsx
deleted file mode 100644
index 87efe2759..000000000
--- a/eventcatalog/src/components/SchemaExplorer/SchemaCodeModal.tsx
+++ /dev/null
@@ -1,93 +0,0 @@
-import * as Dialog from '@radix-ui/react-dialog';
-import { XMarkIcon, ArrowsPointingOutIcon, ClipboardDocumentIcon } from '@heroicons/react/24/outline';
-import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
-import { oneLight as syntaxHighlighterStyle } from 'react-syntax-highlighter/dist/cjs/styles/prism';
-import { getLanguageForHighlight } from './utils';
-import type { SchemaItem } from './types';
-
-interface SchemaCodeModalProps {
-  isOpen: boolean;
-  onOpenChange: (open: boolean) => void;
-  message: SchemaItem;
-  onCopy: () => void;
-  isCopied: boolean;
-}
-
-export default function SchemaCodeModal({ isOpen, onOpenChange, message, onCopy, isCopied }: SchemaCodeModalProps) {
-  if (!message.schemaContent) return null;
-
-  return (
-    <Dialog.Root open={isOpen} onOpenChange={onOpenChange}>
-      <Dialog.Portal>
-        <Dialog.Overlay className="fixed inset-0 bg-black/50 data-[state=open]:animate-overlayShow z-50" />
-        <Dialog.Content className="fixed inset-4 md:inset-8 rounded-lg bg-white shadow-xl focus:outline-none data-[state=open]:animate-contentShow z-[100] flex flex-col">
-          {/* Header */}
-          <div className="flex items-center justify-between p-6 border-b border-gray-200 flex-shrink-0">
-            <div className="flex items-center gap-3">
-              <ArrowsPointingOutIcon className="h-6 w-6 text-gray-500" />
-              <div>
-                <Dialog.Title className="text-xl font-semibold text-gray-900">{message.data.name}</Dialog.Title>
-                <Dialog.Description className="text-sm text-gray-600 mt-1">
-                  v{message.data.version} · {getLanguageForHighlight(message.schemaExtension).toUpperCase()}
-                </Dialog.Description>
-              </div>
-            </div>
-            <div className="flex items-center gap-2">
-              <button
-                onClick={onCopy}
-                className="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium text-gray-700 bg-white border border-gray-300 hover:bg-gray-50 rounded-md transition-colors"
-                title="Copy code"
-              >
-                <ClipboardDocumentIcon className="h-4 w-4" />
-                {isCopied ? 'Copied!' : 'Copy'}
-              </button>
-              <Dialog.Close asChild>
-                <button
-                  type="button"
-                  className="p-2 text-gray-400 hover:text-gray-600 hover:bg-gray-100 rounded-md transition-colors"
-                  aria-label="Close"
-                >
-                  <XMarkIcon className="h-6 w-6" />
-                </button>
-              </Dialog.Close>
-            </div>
-          </div>
-
-          {/* Content */}
-          <div className="flex-1 overflow-auto p-6">
-            <SyntaxHighlighter
-              language={getLanguageForHighlight(message.schemaExtension)}
-              style={syntaxHighlighterStyle}
-              customStyle={{
-                margin: 0,
-                padding: '1rem',
-                borderRadius: '0.5rem',
-                fontSize: '0.875rem',
-                lineHeight: '1.6',
-                height: '100%',
-              }}
-              className="bg-white border border-gray-200 rounded-lg"
-              showLineNumbers={true}
-              wrapLines={true}
-              wrapLongLines={true}
-            >
-              {message.schemaContent}
-            </SyntaxHighlighter>
-          </div>
-
-          {/* Footer */}
-          <div className="flex justify-end p-4 border-t border-gray-200 flex-shrink-0">
-            <Dialog.Close asChild>
-              <button
-                type="button"
-                className="px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-500 focus:ring-offset-2 transition-colors"
-              >
-                Close
-              </button>
-            </Dialog.Close>
-          </div>
-        </Dialog.Content>
-      </Dialog.Portal>
-    </Dialog.Root>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/SchemaContentViewer.tsx b/eventcatalog/src/components/SchemaExplorer/SchemaContentViewer.tsx
deleted file mode 100644
index bf6b6086a..000000000
--- a/eventcatalog/src/components/SchemaExplorer/SchemaContentViewer.tsx
+++ /dev/null
@@ -1,132 +0,0 @@
-import { ClipboardDocumentIcon, ArrowsPointingOutIcon } from '@heroicons/react/24/outline';
-import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
-import { oneLight as syntaxHighlighterStyle } from 'react-syntax-highlighter/dist/cjs/styles/prism';
-import { buildUrl } from '@utils/url-builder';
-import JSONSchemaViewer from './JSONSchemaViewer';
-import AvroSchemaViewer from './AvroSchemaViewer';
-import { getLanguageForHighlight } from './utils';
-import type { SchemaItem } from './types';
-
-interface SchemaContentViewerProps {
-  message: SchemaItem;
-  onCopy: () => void;
-  isCopied: boolean;
-  viewMode: 'code' | 'schema' | 'diff';
-  parsedSchema: any;
-  parsedAvroSchema?: any;
-  onOpenFullscreen?: () => void;
-  showRequired?: boolean;
-}
-
-export default function SchemaContentViewer({
-  message,
-  onCopy,
-  isCopied,
-  viewMode,
-  parsedSchema,
-  parsedAvroSchema,
-  showRequired = false,
-  onOpenFullscreen,
-}: SchemaContentViewerProps) {
-  if (!message.schemaContent) {
-    return (
-      <div className="flex items-center justify-center h-full text-gray-500">
-        <p className="text-sm">No schema content available</p>
-      </div>
-    );
-  }
-
-  // Render schema viewer based on schema type
-  if (viewMode === 'schema') {
-    if (parsedAvroSchema) {
-      return <AvroSchemaViewer schema={parsedAvroSchema} onOpenFullscreen={onOpenFullscreen} showRequired={showRequired} />;
-    }
-    if (parsedSchema) {
-      return <JSONSchemaViewer schema={parsedSchema} onOpenFullscreen={onOpenFullscreen} />;
-    }
-  }
-
-  return (
-    <div className="h-full overflow-auto p-3 relative bg-white border border-gray-200 rounded-lg">
-      <div className="absolute top-5 right-5 z-10 flex items-center gap-2">
-        {message.collection === 'services' &&
-          (() => {
-            const specType = message.specType || 'openapi';
-            const specFilename = message.specFilenameWithoutExtension || 'schema';
-
-            // Determine the URL path segment based on spec type
-            let urlSegment = 'spec';
-            if (specType === 'asyncapi') {
-              urlSegment = 'asyncapi';
-            } else if (specType === 'graphql') {
-              urlSegment = 'graphql';
-            }
-
-            const specUrl = buildUrl(`/docs/services/${message.data.id}/${message.data.version}/${urlSegment}/${specFilename}`);
-
-            return (
-              <a
-                href={specUrl}
-                className="inline-flex items-center gap-1.5 px-2.5 py-1.5 text-xs font-medium text-gray-700 bg-white border border-gray-300 hover:bg-gray-50 rounded-md transition-colors shadow-sm"
-                title="View full specification"
-              >
-                <svg
-                  xmlns="http://www.w3.org/2000/svg"
-                  className="h-3.5 w-3.5"
-                  fill="none"
-                  viewBox="0 0 24 24"
-                  stroke="currentColor"
-                >
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    strokeWidth={2}
-                    d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"
-                  />
-                </svg>
-                View Spec
-              </a>
-            );
-          })()}
-        {onOpenFullscreen && (
-          <button
-            onClick={onOpenFullscreen}
-            className="inline-flex items-center gap-1.5 px-2.5 py-1.5 text-xs font-medium text-gray-700 bg-white border border-gray-300 hover:bg-gray-50 rounded-md transition-colors shadow-sm"
-            title="Open in fullscreen"
-          >
-            <ArrowsPointingOutIcon className="h-3.5 w-3.5" />
-            Fullscreen
-          </button>
-        )}
-        <button
-          onClick={onCopy}
-          className="inline-flex items-center gap-1.5 px-2.5 py-1.5 text-xs font-medium text-gray-700 bg-white border border-gray-300 hover:bg-gray-50 rounded-md transition-colors shadow-sm"
-          title="Copy code"
-        >
-          <ClipboardDocumentIcon className="h-3.5 w-3.5" />
-          {isCopied ? 'Copied!' : 'Copy'}
-        </button>
-      </div>
-      <SyntaxHighlighter
-        language={getLanguageForHighlight(message.schemaExtension)}
-        style={syntaxHighlighterStyle}
-        customStyle={{
-          margin: 0,
-          padding: '0.75rem',
-          paddingTop: '2.5rem',
-          borderRadius: '0.5rem',
-          fontSize: '0.875rem',
-          lineHeight: '1.6',
-          height: '100%',
-          overflow: 'auto',
-        }}
-        className="bg-white border border-gray-200 rounded-lg"
-        showLineNumbers={true}
-        wrapLines={true}
-        wrapLongLines={true}
-      >
-        {message.schemaContent}
-      </SyntaxHighlighter>
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/SchemaDetailsHeader.tsx b/eventcatalog/src/components/SchemaExplorer/SchemaDetailsHeader.tsx
deleted file mode 100644
index badcb44ec..000000000
--- a/eventcatalog/src/components/SchemaExplorer/SchemaDetailsHeader.tsx
+++ /dev/null
@@ -1,181 +0,0 @@
-import { ClipboardDocumentIcon, ArrowDownTrayIcon, CodeBracketIcon, TableCellsIcon } from '@heroicons/react/24/outline';
-import { buildUrl } from '@utils/url-builder';
-import { getCollectionStyles } from '@components/Grids/utils';
-import { getSchemaTypeLabel } from './utils';
-import type { SchemaItem } from './types';
-
-interface SchemaDetailsHeaderProps {
-  message: SchemaItem;
-  availableVersions: SchemaItem[];
-  selectedVersion: string | null;
-  onVersionChange: (version: string) => void;
-  onCopy: () => void;
-  onDownload: () => void;
-  isCopied: boolean;
-  schemaViewMode: 'code' | 'schema' | 'diff';
-  onViewModeChange: (mode: 'code' | 'schema' | 'diff') => void;
-  hasParsedSchema: boolean;
-  hasDiffs: boolean;
-  diffCount: number;
-}
-
-export default function SchemaDetailsHeader({
-  message,
-  availableVersions,
-  selectedVersion,
-  onVersionChange,
-  onCopy,
-  onDownload,
-  isCopied,
-  schemaViewMode,
-  onViewModeChange,
-  hasParsedSchema,
-  hasDiffs,
-  diffCount,
-}: SchemaDetailsHeaderProps) {
-  const { color, Icon } = getCollectionStyles(message.collection);
-  const hasMultipleVersions = availableVersions.length > 1;
-
-  return (
-    <div className="flex-shrink-0 border-b border-gray-200 p-3">
-      <div className="flex items-start justify-between mb-3">
-        <div className="flex-1 min-w-0">
-          <div className="flex items-center gap-2 mb-1.5">
-            <Icon className={`h-5 w-5 text-${color}-500 flex-shrink-0`} />
-            <a
-              href={buildUrl(`/docs/${message.collection}/${message.data.id}/${message.data.version}`)}
-              className={`text-lg font-semibold text-gray-900 hover:text-${color}-600 hover:underline truncate`}
-            >
-              {message.data.name}
-            </a>
-            {hasMultipleVersions ? (
-              <select
-                value={selectedVersion || message.data.version}
-                onChange={(e) => onVersionChange(e.target.value)}
-                className="text-xs text-gray-700 bg-white border border-gray-300 rounded px-2 py-1 focus:outline-none focus:ring-2 focus:ring-primary focus:border-transparent"
-              >
-                {availableVersions.map((v) => (
-                  <option key={v.data.version} value={v.data.version}>
-                    v{v.data.version}
-                  </option>
-                ))}
-              </select>
-            ) : (
-              <span className="text-xs text-gray-500 flex-shrink-0">v{message.data.version}</span>
-            )}
-          </div>
-          <div className="flex items-center gap-1 mb-2">
-            <span
-              className={`inline-flex items-center rounded-full bg-${color}-100 px-1.5 py-0.5 text-xs font-medium text-${color}-800`}
-            >
-              {message.collection}
-            </span>
-            <span className="inline-flex items-center gap-1 rounded-full bg-gray-100 px-1.5 py-0.5 text-xs font-medium text-gray-800">
-              {(() => {
-                const ext = message.schemaExtension?.toLowerCase();
-                if (
-                  ext === 'openapi' ||
-                  ext === 'asyncapi' ||
-                  ext === 'graphql' ||
-                  ext === 'avro' ||
-                  ext === 'json' ||
-                  ext === 'proto'
-                ) {
-                  // Map json extension to json-schema icon
-                  const iconName = ext === 'json' ? 'json-schema' : ext;
-                  const iconPath = buildUrl(`/icons/${iconName}.svg`, true);
-                  return (
-                    <>
-                      <img src={iconPath} alt={`${ext} icon`} className="h-3 w-3" />
-                      {getSchemaTypeLabel(message.schemaExtension)}
-                    </>
-                  );
-                }
-                return getSchemaTypeLabel(message.schemaExtension);
-              })()}
-            </span>
-          </div>
-          {message.data.summary && <p className="text-xs text-gray-600 line-clamp-2">{message.data.summary}</p>}
-        </div>
-      </div>
-
-      {/* Action Buttons */}
-      <div className="flex items-center gap-2">
-        {/* View Mode Toggle */}
-        <div className="flex items-center gap-1 mr-2 border-r border-gray-300 pr-2">
-          <button
-            onClick={() => onViewModeChange('code')}
-            className={`inline-flex items-center gap-1 px-2 py-1 text-xs font-medium rounded transition-colors ${
-              schemaViewMode === 'code' ? 'bg-primary text-white' : 'text-gray-600 hover:bg-gray-100'
-            }`}
-            title="Code view"
-          >
-            <CodeBracketIcon className="h-3.5 w-3.5" />
-            Code
-          </button>
-          {hasParsedSchema && (
-            <button
-              onClick={() => onViewModeChange('schema')}
-              className={`inline-flex items-center gap-1 px-2 py-1 text-xs font-medium rounded transition-colors ${
-                schemaViewMode === 'schema' ? 'bg-primary text-white' : 'text-gray-600 hover:bg-gray-100'
-              }`}
-              title="Schema view"
-            >
-              <TableCellsIcon className="h-3.5 w-3.5" />
-              Schema
-            </button>
-          )}
-          {hasDiffs && (
-            <button
-              onClick={() => onViewModeChange('diff')}
-              className={`inline-flex items-center gap-1 px-2 py-1 text-xs font-medium rounded transition-colors ${
-                schemaViewMode === 'diff' ? 'bg-primary text-white' : 'text-gray-600 hover:bg-gray-100'
-              }`}
-              title="View version history diffs"
-            >
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                className="h-3.5 w-3.5"
-                fill="none"
-                viewBox="0 0 24 24"
-                stroke="currentColor"
-              >
-                <path
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  strokeWidth={2}
-                  d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
-                />
-              </svg>
-              Diff ({diffCount})
-            </button>
-          )}
-        </div>
-
-        <button
-          onClick={onCopy}
-          className="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 transition-colors"
-          title="Copy schema to clipboard"
-        >
-          <ClipboardDocumentIcon className="h-4 w-4" />
-          {isCopied ? 'Copied!' : 'Copy'}
-        </button>
-        <button
-          onClick={onDownload}
-          className="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 transition-colors"
-          title="Download schema file"
-        >
-          <ArrowDownTrayIcon className="h-4 w-4" />
-          Download
-        </button>
-        <a
-          href={buildUrl(`/docs/${message.collection}/${message.data.id}/${message.data.version}`)}
-          className="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 transition-colors ml-auto"
-          title="View full documentation"
-        >
-          View Docs →
-        </a>
-      </div>
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/SchemaDetailsPanel.tsx b/eventcatalog/src/components/SchemaExplorer/SchemaDetailsPanel.tsx
deleted file mode 100644
index 6f120afd0..000000000
--- a/eventcatalog/src/components/SchemaExplorer/SchemaDetailsPanel.tsx
+++ /dev/null
@@ -1,233 +0,0 @@
-import { useState, useMemo } from 'react';
-import * as Diff from 'diff';
-import { html } from 'diff2html';
-import 'diff2html/bundles/css/diff2html.min.css';
-import SchemaDetailsHeader from './SchemaDetailsHeader';
-import ApiAccessSection from './ApiAccessSection';
-import OwnersSection from './OwnersSection';
-import ProducersConsumersSection from './ProducersConsumersSection';
-import SchemaContentViewer from './SchemaContentViewer';
-import DiffViewer from './DiffViewer';
-import VersionHistoryModal from './VersionHistoryModal';
-import SchemaCodeModal from './SchemaCodeModal';
-import SchemaViewerModal from './SchemaViewerModal';
-import { copyToClipboard, downloadSchema } from './utils';
-import type { SchemaItem, VersionDiff } from './types';
-
-interface SchemaDetailsPanelProps {
-  message: SchemaItem;
-  availableVersions: SchemaItem[];
-  selectedVersion: string | null;
-  onVersionChange: (version: string) => void;
-  apiAccessEnabled?: boolean;
-}
-
-export default function SchemaDetailsPanel({
-  message,
-  availableVersions,
-  selectedVersion,
-  onVersionChange,
-  apiAccessEnabled = false,
-}: SchemaDetailsPanelProps) {
-  const [copiedId, setCopiedId] = useState<string | null>(null);
-  const [schemaViewMode, setSchemaViewMode] = useState<'code' | 'schema' | 'diff'>('code');
-  const [apiAccessExpanded, setApiAccessExpanded] = useState(false);
-  const [ownersExpanded, setOwnersExpanded] = useState(false);
-  const [producersConsumersExpanded, setProducersConsumersExpanded] = useState(false);
-  const [isDiffModalOpen, setIsDiffModalOpen] = useState(false);
-  const [isCodeModalOpen, setIsCodeModalOpen] = useState(false);
-  const [isSchemaViewerModalOpen, setIsSchemaViewerModalOpen] = useState(false);
-
-  const hasMultipleVersions = availableVersions.length > 1;
-
-  // Generate diffs between all consecutive versions
-  const allDiffs: VersionDiff[] = useMemo(() => {
-    const diffs: VersionDiff[] = [];
-    if (!hasMultipleVersions) return diffs;
-
-    for (let i = 0; i < availableVersions.length - 1; i++) {
-      const newerVersion = availableVersions[i];
-      const olderVersion = availableVersions[i + 1];
-
-      if (newerVersion.schemaContent && olderVersion.schemaContent) {
-        const diff = Diff.createTwoFilesPatch(
-          `v${olderVersion.data.version}`,
-          `v${newerVersion.data.version}`,
-          olderVersion.schemaContent,
-          newerVersion.schemaContent,
-          '',
-          '',
-          { context: 3 }
-        );
-
-        const diffHtml = html(diff, {
-          drawFileList: false,
-          matching: 'lines',
-          outputFormat: 'side-by-side',
-        });
-
-        diffs.push({
-          newerVersion: newerVersion.data.version,
-          olderVersion: olderVersion.data.version,
-          diffHtml,
-          newerContent: newerVersion.schemaContent,
-          olderContent: olderVersion.schemaContent,
-        });
-      }
-    }
-    return diffs;
-  }, [availableVersions, hasMultipleVersions]);
-
-  // Check if this is a JSON schema
-  const parsedSchema = useMemo(() => {
-    const isJSONSchema =
-      message.schemaExtension?.toLowerCase() === 'json' && message.schemaContent && message.schemaContent.trim() !== '';
-    if (!isJSONSchema) return null;
-
-    try {
-      const parsed = JSON.parse(message.schemaContent ?? '');
-      // Check if it's actually a JSON Schema (has properties or $schema field)
-      if (!parsed.properties && !parsed.$schema && !parsed.type) {
-        return null;
-      }
-      return parsed;
-    } catch {
-      return null;
-    }
-  }, [message.schemaContent, message.schemaExtension]);
-
-  // Check if this is an Avro schema
-  const parsedAvroSchema = useMemo(() => {
-    const ext = message.schemaExtension?.toLowerCase();
-    const isAvroSchema = (ext === 'avro' || ext === 'avsc') && message.schemaContent && message.schemaContent.trim() !== '';
-    if (!isAvroSchema) return null;
-
-    try {
-      const parsed = JSON.parse(message.schemaContent ?? '');
-      // Check if it's actually an Avro Schema (has type field, typically "record")
-      if (!parsed.type) {
-        return null;
-      }
-      return parsed;
-    } catch {
-      return null;
-    }
-  }, [message.schemaContent, message.schemaExtension]);
-
-  const handleCopy = async () => {
-    if (!message.schemaContent) return;
-    const success = await copyToClipboard(message.schemaContent);
-    if (success) {
-      setCopiedId(message.data.id);
-      setTimeout(() => setCopiedId(null), 2000);
-    }
-  };
-
-  const handleCopyCustom = async (content: string, id: string) => {
-    const success = await copyToClipboard(content);
-    if (success) {
-      setCopiedId(id);
-      setTimeout(() => setCopiedId(null), 2000);
-    }
-  };
-
-  const handleDownload = () => {
-    if (!message.schemaContent) return;
-    downloadSchema(message.schemaContent, message.data.id, message.schemaExtension || 'json');
-  };
-
-  const isCopied = copiedId === message.data.id;
-
-  return (
-    <div className="h-full flex flex-col bg-white overflow-hidden">
-      {/* Header */}
-      <SchemaDetailsHeader
-        message={message}
-        availableVersions={availableVersions}
-        selectedVersion={selectedVersion}
-        onVersionChange={onVersionChange}
-        onCopy={handleCopy}
-        onDownload={handleDownload}
-        isCopied={isCopied}
-        schemaViewMode={schemaViewMode}
-        onViewModeChange={setSchemaViewMode}
-        hasParsedSchema={!!parsedSchema || !!parsedAvroSchema}
-        hasDiffs={allDiffs.length > 0}
-        diffCount={allDiffs.length}
-      />
-
-      {/* API Access Section - Always show, but content changes based on Scale access */}
-      <ApiAccessSection
-        message={message}
-        isExpanded={apiAccessExpanded}
-        onToggle={() => setApiAccessExpanded(!apiAccessExpanded)}
-        onCopy={handleCopyCustom}
-        copiedId={copiedId}
-        apiAccessEnabled={apiAccessEnabled}
-      />
-
-      {/* Producers and Consumers Section - Only show for messages (not services) */}
-      {message.collection !== 'services' && (
-        <ProducersConsumersSection
-          message={message}
-          isExpanded={producersConsumersExpanded}
-          onToggle={() => setProducersConsumersExpanded(!producersConsumersExpanded)}
-        />
-      )}
-
-      {/* Owners Section */}
-      <OwnersSection message={message} isExpanded={ownersExpanded} onToggle={() => setOwnersExpanded(!ownersExpanded)} />
-
-      {/* Schema Content - Takes full remaining height */}
-      <div className="flex-1 overflow-hidden">
-        {schemaViewMode === 'diff' && allDiffs.length > 0 ? (
-          <DiffViewer diffs={allDiffs} onOpenFullscreen={() => setIsDiffModalOpen(true)} apiAccessEnabled={apiAccessEnabled} />
-        ) : (
-          <SchemaContentViewer
-            message={message}
-            onCopy={handleCopy}
-            isCopied={isCopied}
-            viewMode={schemaViewMode}
-            parsedSchema={parsedSchema}
-            parsedAvroSchema={parsedAvroSchema}
-            showRequired={true}
-            onOpenFullscreen={
-              schemaViewMode === 'code'
-                ? () => setIsCodeModalOpen(true)
-                : schemaViewMode === 'schema' && (parsedSchema || parsedAvroSchema)
-                  ? () => setIsSchemaViewerModalOpen(true)
-                  : undefined
-            }
-          />
-        )}
-      </div>
-
-      {/* Version History Modal */}
-      <VersionHistoryModal
-        isOpen={isDiffModalOpen}
-        onOpenChange={setIsDiffModalOpen}
-        diffs={allDiffs}
-        messageName={message.data.name}
-        apiAccessEnabled={apiAccessEnabled}
-      />
-
-      {/* Schema Code Modal */}
-      <SchemaCodeModal
-        isOpen={isCodeModalOpen}
-        onOpenChange={setIsCodeModalOpen}
-        message={message}
-        onCopy={handleCopy}
-        isCopied={isCopied}
-      />
-
-      {/* Schema Viewer Modal */}
-      <SchemaViewerModal
-        isOpen={isSchemaViewerModalOpen}
-        onOpenChange={setIsSchemaViewerModalOpen}
-        message={message}
-        parsedSchema={parsedSchema}
-        parsedAvroSchema={parsedAvroSchema}
-      />
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/SchemaExplorer.tsx b/eventcatalog/src/components/SchemaExplorer/SchemaExplorer.tsx
deleted file mode 100644
index 7cbb4cdcc..000000000
--- a/eventcatalog/src/components/SchemaExplorer/SchemaExplorer.tsx
+++ /dev/null
@@ -1,415 +0,0 @@
-import { useState, useMemo, useEffect, useRef } from 'react';
-import { DocumentTextIcon, FunnelIcon } from '@heroicons/react/24/outline';
-import type { CollectionMessageTypes } from '@types';
-import semver from 'semver';
-import SchemaFilters from './SchemaFilters';
-import SchemaListItem from './SchemaListItem';
-import SchemaDetailsPanel from './SchemaDetailsPanel';
-import Pagination from './Pagination';
-import type { SchemaItem } from './types';
-
-interface SchemaExplorerProps {
-  schemas: SchemaItem[];
-  apiAccessEnabled?: boolean;
-}
-
-export default function SchemaExplorer({ schemas, apiAccessEnabled = false }: SchemaExplorerProps) {
-  const [searchQuery, setSearchQuery] = useState(() => {
-    // Load from localStorage
-    if (typeof window !== 'undefined') {
-      const stored = localStorage.getItem('schemaRegistrySearchQuery');
-      return stored !== null ? stored : '';
-    }
-    return '';
-  });
-  const [selectedType, setSelectedType] = useState<'all' | CollectionMessageTypes | 'services'>(() => {
-    // Load from localStorage
-    if (typeof window !== 'undefined') {
-      const stored = localStorage.getItem('schemaRegistrySelectedType');
-      return stored !== null ? (stored as 'all' | CollectionMessageTypes | 'services') : 'all';
-    }
-    return 'all';
-  });
-  const [selectedSchemaType, setSelectedSchemaType] = useState<'all' | string>(() => {
-    // Load from localStorage
-    if (typeof window !== 'undefined') {
-      const stored = localStorage.getItem('schemaRegistrySelectedSchemaType');
-      return stored !== null ? stored : 'all';
-    }
-    return 'all';
-  });
-  const [selectedMessage, setSelectedMessage] = useState<SchemaItem | null>(null);
-  const [selectedVersion, setSelectedVersion] = useState<string | null>(null);
-  const [currentPage, setCurrentPage] = useState(1);
-  const [filtersExpanded, setFiltersExpanded] = useState(() => {
-    if (typeof window !== 'undefined') {
-      const stored = localStorage.getItem('schemaRegistryFiltersExpanded');
-      return stored !== null ? stored === 'true' : true;
-    }
-    return true;
-  });
-  const [isMounted, setIsMounted] = useState(false);
-  const searchInputRef = useRef<HTMLInputElement>(null);
-  const selectedItemRef = useRef<HTMLButtonElement>(null);
-  const ITEMS_PER_PAGE = 50;
-
-  // Set mounted state after hydration to prevent FOUC
-  useEffect(() => {
-    setIsMounted(true);
-  }, []);
-
-  // Function to update URL with query params
-  const updateUrlParams = (message: SchemaItem) => {
-    if (typeof window === 'undefined') return;
-
-    const params = new URLSearchParams();
-    params.set('id', message.data.id);
-    params.set('version', message.data.version);
-    params.set('collection', message.collection);
-
-    // For services, add spec type
-    if (message.collection === 'services') {
-      params.set('specType', message.specType || 'unknown');
-    }
-
-    const newUrl = `${window.location.pathname}?${params.toString()}`;
-    window.history.pushState({}, '', newUrl);
-  };
-
-  // Group messages by ID (and spec type for services) and get all versions
-  const messagesByIdAndVersions = useMemo(() => {
-    const grouped = new Map<string, SchemaItem[]>();
-    schemas.forEach((message) => {
-      // For services, group by ID + spec type to keep different specs separate
-      const groupKey =
-        message.collection === 'services' ? `${message.data.id}__${message.specType || 'unknown'}` : message.data.id;
-
-      const existingVersions = grouped.get(groupKey) || [];
-      grouped.set(groupKey, [...existingVersions, message]);
-    });
-
-    // Sort versions for each ID (descending - latest first)
-    grouped.forEach((versions, id) => {
-      versions.sort((a, b) => {
-        const aVersion = a.data.version;
-        const bVersion = b.data.version;
-
-        // Try to use semver for comparison
-        const aValid = semver.valid(semver.coerce(aVersion));
-        const bValid = semver.valid(semver.coerce(bVersion));
-
-        if (aValid && bValid) {
-          return semver.rcompare(aValid, bValid); // descending order
-        }
-
-        // Fall back to numeric comparison
-        const aNum = parseFloat(aVersion);
-        const bNum = parseFloat(bVersion);
-        if (!isNaN(aNum) && !isNaN(bNum)) {
-          return bNum - aNum;
-        }
-
-        // Final fallback to string comparison
-        return bVersion.localeCompare(aVersion);
-      });
-      grouped.set(id, versions);
-    });
-
-    return grouped;
-  }, [schemas]);
-
-  // Get latest version for each message (for sidebar display)
-  const latestMessages = useMemo(() => {
-    return Array.from(messagesByIdAndVersions.values()).map((versions) => versions[0]);
-  }, [messagesByIdAndVersions]);
-
-  // Get unique schema types
-  const schemaTypes = useMemo(() => {
-    const types = new Set<string>();
-    latestMessages.forEach((msg) => {
-      if (msg.schemaExtension) {
-        types.add(msg.schemaExtension.toLowerCase());
-      }
-    });
-    return Array.from(types).sort();
-  }, [latestMessages]);
-
-  // Filter messages (using latest versions only)
-  const filteredMessages = useMemo(() => {
-    let result = [...latestMessages];
-
-    // Filter by message type
-    if (selectedType !== 'all') {
-      result = result.filter((msg) => msg.collection === selectedType);
-    }
-
-    // Filter by schema type
-    if (selectedSchemaType !== 'all') {
-      result = result.filter((msg) => msg.schemaExtension?.toLowerCase() === selectedSchemaType);
-    }
-
-    // Filter by search query
-    if (searchQuery) {
-      const query = searchQuery.toLowerCase();
-      result = result.filter(
-        (msg) =>
-          msg.data.name?.toLowerCase().includes(query) ||
-          msg.data.summary?.toLowerCase().includes(query) ||
-          msg.data.id?.toLowerCase().includes(query)
-      );
-    }
-
-    // Sort by name alphabetically
-    result.sort((a, b) => {
-      const nameA = a.data.name?.toLowerCase() || '';
-      const nameB = b.data.name?.toLowerCase() || '';
-      return nameA.localeCompare(nameB);
-    });
-
-    return result;
-  }, [latestMessages, searchQuery, selectedType, selectedSchemaType]);
-
-  // Pagination
-  const totalPages = Math.ceil(filteredMessages.length / ITEMS_PER_PAGE);
-  const paginatedMessages = useMemo(() => {
-    const startIndex = (currentPage - 1) * ITEMS_PER_PAGE;
-    return filteredMessages.slice(startIndex, startIndex + ITEMS_PER_PAGE);
-  }, [filteredMessages, currentPage]);
-
-  useEffect(() => {
-    setCurrentPage(1);
-  }, [searchQuery, selectedType, selectedSchemaType]);
-
-  // Load from query string on mount
-  useEffect(() => {
-    if (typeof window === 'undefined') return;
-
-    const params = new URLSearchParams(window.location.search);
-    const id = params.get('id');
-    const version = params.get('version');
-    const collection = params.get('collection');
-    const specType = params.get('specType');
-
-    if (id && version) {
-      // Find the matching message
-      const matchingMessage = schemas.find((msg) => {
-        const idMatch = msg.data.id === id;
-        const versionMatch = msg.data.version === version;
-        const collectionMatch = !collection || msg.collection === collection;
-
-        // For services, also match spec type
-        if (msg.collection === 'services') {
-          const specTypeMatch = !specType || msg.specType === specType;
-          return idMatch && versionMatch && collectionMatch && specTypeMatch;
-        }
-
-        return idMatch && versionMatch && collectionMatch;
-      });
-
-      if (matchingMessage) {
-        setSelectedMessage(matchingMessage);
-        setSelectedVersion(matchingMessage.data.version);
-
-        // Scroll to the selected item after a brief delay to ensure DOM is ready
-        setTimeout(() => {
-          if (selectedItemRef.current) {
-            selectedItemRef.current.scrollIntoView({ behavior: 'smooth', block: 'center' });
-          }
-        }, 100);
-      }
-    }
-  }, [schemas]);
-
-  // Auto-select first message when filters change (only if no query params)
-  useEffect(() => {
-    if (typeof window === 'undefined') return;
-
-    const params = new URLSearchParams(window.location.search);
-    const hasQueryParams = params.has('id');
-
-    if (filteredMessages.length > 0 && !selectedMessage && !hasQueryParams) {
-      const firstMessage = filteredMessages[0];
-      setSelectedMessage(firstMessage);
-      setSelectedVersion(firstMessage.data.version);
-    }
-  }, [filteredMessages, selectedMessage]);
-
-  // Get the message to display (based on selected version)
-  const displayMessage = useMemo(() => {
-    if (!selectedMessage) return null;
-
-    // For services, use compound key (ID + spec type), otherwise just ID
-    const groupKey =
-      selectedMessage.collection === 'services'
-        ? `${selectedMessage.data.id}__${selectedMessage.specType || 'unknown'}`
-        : selectedMessage.data.id;
-
-    const versions = messagesByIdAndVersions.get(groupKey);
-    if (!versions) return selectedMessage;
-
-    // If no version selected, use the latest (which is the first in the sorted array)
-    if (!selectedVersion) return versions[0];
-
-    // Find the message with the selected version
-    const versionedMessage = versions.find((v) => v.data.version === selectedVersion);
-    return versionedMessage || versions[0];
-  }, [selectedMessage, selectedVersion, messagesByIdAndVersions]);
-
-  // Save filter expanded state to localStorage
-  useEffect(() => {
-    if (typeof window !== 'undefined') {
-      localStorage.setItem('schemaRegistryFiltersExpanded', filtersExpanded.toString());
-    }
-  }, [filtersExpanded]);
-
-  // Save filter states to localStorage
-  useEffect(() => {
-    if (typeof window !== 'undefined') {
-      localStorage.setItem('schemaRegistrySearchQuery', searchQuery);
-    }
-  }, [searchQuery]);
-
-  useEffect(() => {
-    if (typeof window !== 'undefined') {
-      localStorage.setItem('schemaRegistrySelectedType', selectedType);
-    }
-  }, [selectedType]);
-
-  useEffect(() => {
-    if (typeof window !== 'undefined') {
-      localStorage.setItem('schemaRegistrySelectedSchemaType', selectedSchemaType);
-    }
-  }, [selectedSchemaType]);
-
-  // Keyboard shortcut for search (Cmd+K or Ctrl+K)
-  useEffect(() => {
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
-        e.preventDefault();
-        searchInputRef.current?.focus();
-      }
-    };
-    window.addEventListener('keydown', handleKeyDown);
-    return () => window.removeEventListener('keydown', handleKeyDown);
-  }, []);
-
-  // Get available versions for the selected message
-  const availableVersions = useMemo(() => {
-    if (!displayMessage) return [];
-    const groupKey =
-      displayMessage.collection === 'services'
-        ? `${displayMessage.data.id}__${displayMessage.specType || 'unknown'}`
-        : displayMessage.data.id;
-    return messagesByIdAndVersions.get(groupKey) || [displayMessage];
-  }, [displayMessage, messagesByIdAndVersions]);
-
-  const handleVersionChange = (newVersion: string) => {
-    setSelectedVersion(newVersion);
-    // Update URL with new version
-    const versionedMessage = availableVersions.find((v) => v.data.version === newVersion);
-    if (versionedMessage) {
-      updateUrlParams(versionedMessage);
-    }
-  };
-
-  return (
-    <div className="h-full flex flex-col overflow-hidden">
-      {/* Compact Header */}
-      <div className="flex-shrink-0 border-b border-gray-200 pb-2 mb-3">
-        <div>
-          <h1 className="text-2xl font-bold text-gray-900">Schema Explorer</h1>
-          <p className="mt-0.5 text-xs text-gray-600">
-            {filteredMessages.length} schema{filteredMessages.length !== 1 ? 's' : ''} available
-          </p>
-        </div>
-      </div>
-
-      {/* Split View */}
-      <div className="flex-1 flex gap-4 overflow-hidden">
-        {/* Left: Filters + Schema List */}
-        <div className="w-1/3 flex flex-col bg-white border border-gray-200 rounded-lg overflow-hidden">
-          {/* Filters */}
-          <SchemaFilters
-            searchQuery={searchQuery}
-            onSearchChange={setSearchQuery}
-            selectedType={selectedType}
-            onTypeChange={setSelectedType}
-            selectedSchemaType={selectedSchemaType}
-            onSchemaTypeChange={setSelectedSchemaType}
-            schemaTypes={schemaTypes}
-            latestMessages={latestMessages}
-            filtersExpanded={filtersExpanded}
-            onToggleExpanded={() => setFiltersExpanded(!filtersExpanded)}
-            searchInputRef={searchInputRef}
-            isMounted={isMounted}
-          />
-
-          {/* Schema List - Independently Scrollable */}
-          <div className="flex-1 overflow-y-auto">
-            {paginatedMessages.length > 0 ? (
-              <div className="divide-y divide-gray-200">
-                {paginatedMessages.map((message) => {
-                  // For services, also check spec type to determine if selected
-                  const isSelected =
-                    message.collection === 'services'
-                      ? selectedMessage?.data.id === message.data.id && selectedMessage?.specType === message.specType
-                      : selectedMessage?.data.id === message.data.id;
-
-                  // Get versions using compound key for services
-                  const groupKey =
-                    message.collection === 'services' ? `${message.data.id}__${message.specType || 'unknown'}` : message.data.id;
-
-                  const versions = messagesByIdAndVersions.get(groupKey) || [message];
-
-                  return (
-                    <SchemaListItem
-                      key={groupKey}
-                      message={message}
-                      isSelected={isSelected}
-                      versions={versions}
-                      onClick={() => {
-                        setSelectedMessage(message);
-                        setSelectedVersion(message.data.version);
-                        updateUrlParams(message);
-                      }}
-                      itemRef={isSelected ? selectedItemRef : undefined}
-                    />
-                  );
-                })}
-              </div>
-            ) : (
-              <div className="flex flex-col items-center justify-center h-full p-8 text-center">
-                <FunnelIcon className="h-12 w-12 text-gray-400 mb-3" />
-                <h3 className="text-sm font-semibold text-gray-900 mb-1">No schemas found</h3>
-                <p className="text-xs text-gray-500">Try adjusting your filters</p>
-              </div>
-            )}
-          </div>
-
-          {/* Pagination */}
-          <Pagination currentPage={currentPage} totalPages={totalPages} onPageChange={setCurrentPage} />
-        </div>
-
-        {/* Right: Schema Details */}
-        <div className="flex-1 bg-white border border-gray-200 rounded-lg overflow-hidden">
-          {displayMessage ? (
-            <SchemaDetailsPanel
-              message={displayMessage}
-              availableVersions={availableVersions}
-              selectedVersion={selectedVersion}
-              onVersionChange={handleVersionChange}
-              apiAccessEnabled={apiAccessEnabled}
-            />
-          ) : (
-            <div className="h-full flex items-center justify-center text-gray-500">
-              <div className="text-center">
-                <DocumentTextIcon className="h-12 w-12 mx-auto mb-3 text-gray-400" />
-                <p>Select a schema to view details</p>
-              </div>
-            </div>
-          )}
-        </div>
-      </div>
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/SchemaFilters.tsx b/eventcatalog/src/components/SchemaExplorer/SchemaFilters.tsx
deleted file mode 100644
index 323674b1c..000000000
--- a/eventcatalog/src/components/SchemaExplorer/SchemaFilters.tsx
+++ /dev/null
@@ -1,174 +0,0 @@
-import { MagnifyingGlassIcon, XMarkIcon, FunnelIcon, ChevronUpIcon, ChevronDownIcon } from '@heroicons/react/24/outline';
-import type { CollectionMessageTypes } from '@types';
-import { getSchemaTypeLabel } from './utils';
-import type { SchemaItem } from './types';
-
-interface SchemaFiltersProps {
-  searchQuery: string;
-  onSearchChange: (query: string) => void;
-  selectedType: 'all' | CollectionMessageTypes | 'services';
-  onTypeChange: (type: 'all' | CollectionMessageTypes | 'services') => void;
-  selectedSchemaType: string;
-  onSchemaTypeChange: (type: string) => void;
-  schemaTypes: string[];
-  latestMessages: SchemaItem[];
-  filtersExpanded: boolean;
-  onToggleExpanded: () => void;
-  searchInputRef: React.RefObject<HTMLInputElement>;
-  isMounted: boolean;
-}
-
-export default function SchemaFilters({
-  searchQuery,
-  onSearchChange,
-  selectedType,
-  onTypeChange,
-  selectedSchemaType,
-  onSchemaTypeChange,
-  schemaTypes,
-  latestMessages,
-  filtersExpanded,
-  onToggleExpanded,
-  searchInputRef,
-  isMounted,
-}: SchemaFiltersProps) {
-  const activeFilterCount = [searchQuery, selectedType !== 'all', selectedSchemaType !== 'all'].filter(Boolean).length;
-
-  return (
-    <div className="flex-shrink-0 border-b border-gray-200 bg-gray-50">
-      {/* Filter Header */}
-      <button
-        onClick={onToggleExpanded}
-        className="w-full flex items-center justify-between p-3 hover:bg-gray-100 transition-colors"
-      >
-        <div className="flex items-center gap-2">
-          <FunnelIcon className="h-4 w-4 text-gray-600" />
-          <span className="text-xs font-semibold text-gray-900">Filters</span>
-          {activeFilterCount > 0 && (
-            <span className="inline-flex items-center rounded-full bg-primary px-2 py-0.5 text-xs font-medium text-white">
-              {activeFilterCount}
-            </span>
-          )}
-        </div>
-        {filtersExpanded ? (
-          <ChevronUpIcon className="h-4 w-4 text-gray-600" />
-        ) : (
-          <ChevronDownIcon className="h-4 w-4 text-gray-600" />
-        )}
-      </button>
-
-      {/* Collapsible Filter Content - Only render after mount to prevent FOUC */}
-      {isMounted && filtersExpanded && (
-        <div className="p-3 pt-0">
-          {/* Search */}
-          <div className="mb-3">
-            <label htmlFor="search" className="block text-xs font-medium text-gray-700 mb-1.5">
-              Search
-            </label>
-            <div className="relative">
-              <div className="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-2.5">
-                <MagnifyingGlassIcon className="h-4 w-4 text-gray-400" />
-              </div>
-              <input
-                ref={searchInputRef}
-                type="text"
-                id="search"
-                placeholder="Search schemas..."
-                value={searchQuery}
-                onChange={(e) => onSearchChange(e.target.value)}
-                className="w-full rounded-md border-gray-300 shadow-sm focus:border-primary focus:ring-primary text-xs pl-8 pr-8 py-1.5 border"
-              />
-              {searchQuery && (
-                <button onClick={() => onSearchChange('')} className="absolute inset-y-0 right-0 flex items-center pr-2.5">
-                  <XMarkIcon className="h-4 w-4 text-gray-400 hover:text-gray-600" />
-                </button>
-              )}
-            </div>
-          </div>
-
-          {/* Message Type Filter */}
-          <div className="mb-3">
-            <label htmlFor="messageType" className="block text-xs font-medium text-gray-700 mb-1.5">
-              Message Type
-            </label>
-            <select
-              id="messageType"
-              value={selectedType}
-              onChange={(e) => onTypeChange(e.target.value as typeof selectedType)}
-              className="w-full rounded-md border-gray-300 shadow-sm focus:border-primary focus:ring-primary text-xs px-2.5 py-1.5 border"
-            >
-              <option value="all">All ({latestMessages.length})</option>
-              <option value="events">Events ({latestMessages.filter((m) => m.collection === 'events').length})</option>
-              <option value="commands">Commands ({latestMessages.filter((m) => m.collection === 'commands').length})</option>
-              <option value="queries">Queries ({latestMessages.filter((m) => m.collection === 'queries').length})</option>
-              <option value="services">Services ({latestMessages.filter((m) => m.collection === 'services').length})</option>
-            </select>
-          </div>
-
-          {/* Schema Type Filter */}
-          <div className="mb-3">
-            <label htmlFor="schemaType" className="block text-xs font-medium text-gray-700 mb-1.5">
-              Schema Format
-            </label>
-            <select
-              id="schemaType"
-              value={selectedSchemaType}
-              onChange={(e) => onSchemaTypeChange(e.target.value)}
-              className="w-full rounded-md border-gray-300 shadow-sm focus:border-primary focus:ring-primary text-xs px-2.5 py-1.5 border"
-            >
-              <option value="all">All Formats</option>
-              {schemaTypes.map((type) => (
-                <option key={type} value={type}>
-                  {getSchemaTypeLabel(type)} ({latestMessages.filter((m) => m.schemaExtension?.toLowerCase() === type).length})
-                </option>
-              ))}
-            </select>
-          </div>
-
-          {/* Active filters */}
-          {activeFilterCount > 0 && (
-            <div className="pt-2 border-t border-gray-200">
-              <div className="flex flex-wrap items-center gap-1.5">
-                {searchQuery && (
-                  <span className="inline-flex items-center gap-1 px-1.5 py-0.5 text-xs bg-blue-100 text-blue-800 rounded">
-                    {searchQuery.substring(0, 15)}
-                    {searchQuery.length > 15 ? '...' : ''}
-                    <button onClick={() => onSearchChange('')}>
-                      <XMarkIcon className="h-3 w-3" />
-                    </button>
-                  </span>
-                )}
-                {selectedType !== 'all' && (
-                  <span className="inline-flex items-center gap-1 px-1.5 py-0.5 text-xs bg-blue-100 text-blue-800 rounded">
-                    {selectedType}
-                    <button onClick={() => onTypeChange('all')}>
-                      <XMarkIcon className="h-3 w-3" />
-                    </button>
-                  </span>
-                )}
-                {selectedSchemaType !== 'all' && (
-                  <span className="inline-flex items-center gap-1 px-1.5 py-0.5 text-xs bg-blue-100 text-blue-800 rounded">
-                    {getSchemaTypeLabel(selectedSchemaType)}
-                    <button onClick={() => onSchemaTypeChange('all')}>
-                      <XMarkIcon className="h-3 w-3" />
-                    </button>
-                  </span>
-                )}
-                <button
-                  onClick={() => {
-                    onSearchChange('');
-                    onTypeChange('all');
-                    onSchemaTypeChange('all');
-                  }}
-                  className="text-xs text-gray-600 hover:text-gray-900 underline"
-                >
-                  Clear
-                </button>
-              </div>
-            </div>
-          )}
-        </div>
-      )}
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/SchemaListItem.tsx b/eventcatalog/src/components/SchemaExplorer/SchemaListItem.tsx
deleted file mode 100644
index e2e7c1283..000000000
--- a/eventcatalog/src/components/SchemaExplorer/SchemaListItem.tsx
+++ /dev/null
@@ -1,73 +0,0 @@
-import { buildUrl } from '@utils/url-builder';
-import { getCollectionStyles } from '@components/Grids/utils';
-import { getSchemaTypeLabel } from './utils';
-import type { SchemaItem } from './types';
-
-interface SchemaListItemProps {
-  message: SchemaItem;
-  isSelected: boolean;
-  versions: SchemaItem[];
-  onClick: () => void;
-  itemRef?: React.RefObject<HTMLButtonElement>;
-}
-
-export default function SchemaListItem({ message, isSelected, versions, onClick, itemRef }: SchemaListItemProps) {
-  const { color, Icon } = getCollectionStyles(message.collection);
-  const hasMultipleVersions = versions.length > 1;
-
-  return (
-    <button
-      ref={itemRef}
-      onClick={onClick}
-      className={`w-full text-left p-4 hover:bg-gray-50 transition-colors ${
-        isSelected ? `bg-${color}-50 border-l-4 border-${color}-500` : 'border-l-4 border-transparent'
-      }`}
-    >
-      <div className="flex items-start gap-3">
-        <Icon className={`h-5 w-5 mt-0.5 flex-shrink-0 ${isSelected ? `text-${color}-600` : `text-${color}-500`}`} />
-        <div className="flex-1 min-w-0">
-          <div className="flex items-center justify-between gap-2 mb-1.5">
-            <div className="flex items-center gap-2 min-w-0">
-              <h3 className={`text-sm font-semibold truncate ${isSelected ? `text-${color}-900` : 'text-gray-900'}`}>
-                {message.data.name}
-              </h3>
-              <span className="text-xs text-gray-500 flex-shrink-0">v{message.data.version}</span>
-            </div>
-            <div className="flex items-center gap-1 flex-shrink-0">
-              <span className="inline-flex items-center gap-1 rounded-full bg-gray-100 px-1.5 py-0.5 text-xs font-medium text-gray-800">
-                {(() => {
-                  const ext = message.schemaExtension?.toLowerCase();
-                  if (
-                    ext === 'openapi' ||
-                    ext === 'asyncapi' ||
-                    ext === 'graphql' ||
-                    ext === 'avro' ||
-                    ext === 'json' ||
-                    ext === 'proto'
-                  ) {
-                    // Map json extension to json-schema icon
-                    const iconName = ext === 'json' ? 'json-schema' : ext;
-                    const iconPath = buildUrl(`/icons/${iconName}.svg`, true);
-                    return (
-                      <>
-                        <img src={iconPath} alt={`${ext} icon`} className="h-3 w-3" />
-                        {getSchemaTypeLabel(message.schemaExtension)}
-                      </>
-                    );
-                  }
-                  return getSchemaTypeLabel(message.schemaExtension);
-                })()}
-              </span>
-              {hasMultipleVersions && (
-                <span className="inline-flex items-center rounded-full bg-blue-100 px-1 py-0.5 text-xs font-medium text-blue-700">
-                  {versions.length} versions
-                </span>
-              )}
-            </div>
-          </div>
-          {message.data.summary && <p className="text-xs text-gray-600 line-clamp-2">{message.data.summary}</p>}
-        </div>
-      </div>
-    </button>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/SchemaViewerModal.tsx b/eventcatalog/src/components/SchemaExplorer/SchemaViewerModal.tsx
deleted file mode 100644
index d696e3a57..000000000
--- a/eventcatalog/src/components/SchemaExplorer/SchemaViewerModal.tsx
+++ /dev/null
@@ -1,77 +0,0 @@
-import * as Dialog from '@radix-ui/react-dialog';
-import { XMarkIcon, ArrowsPointingOutIcon } from '@heroicons/react/24/outline';
-import JSONSchemaViewer from './JSONSchemaViewer';
-import AvroSchemaViewer from './AvroSchemaViewer';
-import type { SchemaItem } from './types';
-
-interface SchemaViewerModalProps {
-  isOpen: boolean;
-  onOpenChange: (open: boolean) => void;
-  message: SchemaItem;
-  parsedSchema: any;
-  parsedAvroSchema?: any;
-}
-
-export default function SchemaViewerModal({
-  isOpen,
-  onOpenChange,
-  message,
-  parsedSchema,
-  parsedAvroSchema,
-}: SchemaViewerModalProps) {
-  if (!parsedSchema && !parsedAvroSchema) return null;
-
-  const isAvro = !!parsedAvroSchema;
-
-  return (
-    <Dialog.Root open={isOpen} onOpenChange={onOpenChange}>
-      <Dialog.Portal>
-        <Dialog.Overlay className="fixed inset-0 bg-black/50 data-[state=open]:animate-overlayShow z-50" />
-        <Dialog.Content className="fixed inset-4 md:inset-8 rounded-lg bg-white shadow-xl focus:outline-none data-[state=open]:animate-contentShow z-[100] flex flex-col">
-          {/* Header */}
-          <div className="flex items-center justify-between p-6 border-b border-gray-200 flex-shrink-0">
-            <div className="flex items-center gap-3">
-              <ArrowsPointingOutIcon className="h-6 w-6 text-gray-500" />
-              <div>
-                <Dialog.Title className="text-xl font-semibold text-gray-900">{message.data.name}</Dialog.Title>
-                <Dialog.Description className="text-sm text-gray-600 mt-1">
-                  v{message.data.version} · {isAvro ? 'Avro' : 'JSON'} Schema
-                </Dialog.Description>
-              </div>
-            </div>
-            <Dialog.Close asChild>
-              <button
-                type="button"
-                className="p-2 text-gray-400 hover:text-gray-600 hover:bg-gray-100 rounded-md transition-colors"
-                aria-label="Close"
-              >
-                <XMarkIcon className="h-6 w-6" />
-              </button>
-            </Dialog.Close>
-          </div>
-
-          {/* Content */}
-          <div className="flex-1 overflow-hidden p-6">
-            {isAvro ? (
-              <AvroSchemaViewer schema={parsedAvroSchema} expand={true} search={true} />
-            ) : (
-              <JSONSchemaViewer schema={parsedSchema} expand={true} search={true} />
-            )}
-          </div>
-
-          {/* Footer */}
-          <div className="flex justify-end p-4 border-t border-gray-200 flex-shrink-0">
-            <Dialog.Close asChild>
-              <button
-                type="button"
-                className="px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-500 focus:ring-offset-2 transition-colors"
-              >
-                Close
-              </button>
-            </Dialog.Close>
-          </div>
-        </Dialog.Content>
-      </Dialog.Portal>
-    </Dialog.Root>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/VersionHistoryModal.tsx b/eventcatalog/src/components/SchemaExplorer/VersionHistoryModal.tsx
deleted file mode 100644
index b09900512..000000000
--- a/eventcatalog/src/components/SchemaExplorer/VersionHistoryModal.tsx
+++ /dev/null
@@ -1,72 +0,0 @@
-import * as Dialog from '@radix-ui/react-dialog';
-import { XMarkIcon, ArrowsPointingOutIcon } from '@heroicons/react/24/outline';
-import DiffViewer from './DiffViewer';
-import type { VersionDiff } from './types';
-
-interface VersionHistoryModalProps {
-  isOpen: boolean;
-  onOpenChange: (open: boolean) => void;
-  diffs: VersionDiff[];
-  messageName: string;
-  apiAccessEnabled?: boolean;
-}
-
-export default function VersionHistoryModal({
-  isOpen,
-  onOpenChange,
-  diffs,
-  messageName,
-  apiAccessEnabled = false,
-}: VersionHistoryModalProps) {
-  return (
-    <Dialog.Root open={isOpen} onOpenChange={onOpenChange}>
-      <Dialog.Portal>
-        <Dialog.Overlay className="fixed inset-0 bg-black/50 data-[state=open]:animate-overlayShow z-50" />
-        <Dialog.Content className="fixed inset-4 md:inset-8 rounded-lg bg-white shadow-xl focus:outline-none data-[state=open]:animate-contentShow z-[100] flex flex-col">
-          {/* Header */}
-          <div className="flex items-center justify-between p-6 border-b border-gray-200 flex-shrink-0">
-            <div className="flex items-center gap-3">
-              <ArrowsPointingOutIcon className="h-6 w-6 text-gray-500" />
-              <div>
-                <Dialog.Title className="text-xl font-semibold text-gray-900">Version History</Dialog.Title>
-                <Dialog.Description className="text-sm text-gray-600 mt-1">{messageName}</Dialog.Description>
-              </div>
-            </div>
-            <Dialog.Close asChild>
-              <button
-                type="button"
-                className="p-2 text-gray-400 hover:text-gray-600 hover:bg-gray-100 rounded-md transition-colors"
-                aria-label="Close"
-              >
-                <XMarkIcon className="h-6 w-6" />
-              </button>
-            </Dialog.Close>
-          </div>
-
-          {/* Content */}
-          <div className="flex-1 overflow-y-auto p-6">
-            {diffs.length > 0 ? (
-              <DiffViewer diffs={diffs} apiAccessEnabled={apiAccessEnabled} />
-            ) : (
-              <div className="flex items-center justify-center h-full">
-                <p className="text-gray-500 text-center">No version history available</p>
-              </div>
-            )}
-          </div>
-
-          {/* Footer */}
-          <div className="flex justify-end p-4 border-t border-gray-200 flex-shrink-0">
-            <Dialog.Close asChild>
-              <button
-                type="button"
-                className="px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-500 focus:ring-offset-2 transition-colors"
-              >
-                Close
-              </button>
-            </Dialog.Close>
-          </div>
-        </Dialog.Content>
-      </Dialog.Portal>
-    </Dialog.Root>
-  );
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/types.ts b/eventcatalog/src/components/SchemaExplorer/types.ts
deleted file mode 100644
index f05b13cbf..000000000
--- a/eventcatalog/src/components/SchemaExplorer/types.ts
+++ /dev/null
@@ -1,45 +0,0 @@
-import type { CollectionMessageTypes } from '@types';
-
-export interface Producer {
-  id: string;
-  version: string;
-}
-
-export interface Consumer {
-  id: string;
-  version: string;
-}
-
-export interface Owner {
-  id: string;
-  name: string;
-  type: 'users' | 'teams';
-  href: string;
-}
-
-export interface SchemaItem {
-  collection: CollectionMessageTypes | 'services';
-  data: {
-    id: string;
-    name: string;
-    version: string;
-    summary?: string;
-    schemaPath?: string;
-    producers?: Producer[];
-    consumers?: Consumer[];
-    owners?: Owner[];
-  };
-  schemaContent?: string;
-  schemaExtension?: string;
-  specType?: string;
-  specName?: string;
-  specFilenameWithoutExtension?: string;
-}
-
-export interface VersionDiff {
-  newerVersion: string;
-  olderVersion: string;
-  diffHtml: string;
-  newerContent: string;
-  olderContent: string;
-}
diff --git a/eventcatalog/src/components/SchemaExplorer/utils.ts b/eventcatalog/src/components/SchemaExplorer/utils.ts
deleted file mode 100644
index 4da542898..000000000
--- a/eventcatalog/src/components/SchemaExplorer/utils.ts
+++ /dev/null
@@ -1,81 +0,0 @@
-export const getLanguageForHighlight = (extension?: string): string => {
-  if (!extension) return 'json';
-  const ext = extension.toLowerCase();
-  switch (ext) {
-    case 'avro':
-    case 'avsc':
-    case 'json':
-      return 'json';
-    case 'proto':
-      return 'protobuf';
-    case 'xsd':
-    case 'xml':
-      return 'xml';
-    case 'graphql':
-    case 'gql':
-      return 'graphql';
-    case 'yaml':
-    case 'yml':
-    case 'openapi':
-    case 'asyncapi':
-      return 'yaml';
-    case 'ts':
-    case 'typescript':
-      return 'typescript';
-    case 'js':
-    case 'javascript':
-      return 'javascript';
-    default:
-      return 'json';
-  }
-};
-
-export const getSchemaTypeLabel = (extension?: string): string => {
-  if (!extension) return 'JSON';
-  const ext = extension.toLowerCase();
-  switch (ext) {
-    case 'avro':
-    case 'avsc':
-      return 'Avro';
-    case 'proto':
-      return 'Protobuf';
-    case 'xsd':
-      return 'XML Schema';
-    case 'graphql':
-    case 'gql':
-      return 'GraphQL';
-    case 'yaml':
-    case 'yml':
-      return 'YAML';
-    case 'json':
-      return 'JSON Schema';
-    case 'openapi':
-      return 'OpenAPI';
-    case 'asyncapi':
-      return 'AsyncAPI';
-    default:
-      return ext.toUpperCase();
-  }
-};
-
-export const copyToClipboard = async (content: string): Promise<boolean> => {
-  try {
-    await navigator.clipboard.writeText(content);
-    return true;
-  } catch (err) {
-    console.error('Failed to copy:', err);
-    return false;
-  }
-};
-
-export const downloadSchema = (content: string, filename: string, extension: string) => {
-  const blob = new Blob([content], { type: 'text/plain' });
-  const url = URL.createObjectURL(blob);
-  const a = document.createElement('a');
-  a.href = url;
-  a.download = `${filename}.${extension}`;
-  document.body.appendChild(a);
-  a.click();
-  document.body.removeChild(a);
-  URL.revokeObjectURL(url);
-};
diff --git a/eventcatalog/src/components/Search/Search.astro b/eventcatalog/src/components/Search/Search.astro
deleted file mode 100644
index b7f59bde1..000000000
--- a/eventcatalog/src/components/Search/Search.astro
+++ /dev/null
@@ -1,109 +0,0 @@
----
-import MagnifyingGlassIcon from '@heroicons/react/24/outline/MagnifyingGlassIcon';
-import SearchModal from './SearchModal.tsx';
-import { buildUrl } from '@utils/url-builder.ts';
-
-const pagefindJsUrl = buildUrl('/pagefind/pagefind.js', true);
-const pagefindCssUrl = buildUrl('/pagefind/pagefind-ui.css', true);
----
-
-<link href={pagefindCssUrl} rel="stylesheet" />
-<script type="module" define:vars={{ pagefindJsUrl }}>
-  // Load Pagefind and expose it globally
-  try {
-    const pagefind = await import(pagefindJsUrl);
-    window.pagefind = pagefind;
-    window.dispatchEvent(new CustomEvent('pagefindLoaded'));
-  } catch (error) {
-    console.error('Failed to load pagefind:', error);
-  }
-</script>
-
-<div>
-  <div class="relative flex items-center">
-    <input
-      id="search-dummy-input"
-      type="text"
-      name="search"
-      placeholder="Search EventCatalog"
-      class="block w-full rounded-md caret-transparent border-0 py-1.5 pr-14 pl-10 text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 placeholder:text-gray-400 font-light sm:text-sm sm:leading-6 px-4"
-    />
-    <MagnifyingGlassIcon className="absolute inset-y-0 -left-1 h-9 w-8 flex items-center pl-4 text-gray-400" />
-    <div class="absolute inset-y-0 right-0 flex py-1.5 pr-1.5">
-      <kbd class="inline-flex items-center rounded px-1 font-sans text-xs text-gray-400">⌘K</kbd>
-    </div>
-  </div>
-</div>
-
-<SearchModal client:only />
-
-<script>
-  // Create a global state for the search modal
-  (window as any).searchModalState = {
-    isOpen: false,
-    toggle: function () {
-      this.isOpen = !this.isOpen;
-      this.render();
-    },
-    close: function () {
-      this.isOpen = false;
-      this.render();
-    },
-    render: function () {
-      // This will be handled by React component
-      const event = new CustomEvent('searchModalToggle', {
-        detail: { isOpen: this.isOpen },
-      });
-      window.dispatchEvent(event);
-    },
-  };
-
-  const dummyInput = document.getElementById('search-dummy-input');
-  const header = document.getElementById('eventcatalog-header');
-  const verticalNav = document.getElementById('eventcatalog-vertical-nav');
-
-  // Event listeners
-  window.addEventListener('keydown', (event) => {
-    if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
-      event.preventDefault();
-      dummyInput?.click();
-    }
-  });
-
-  dummyInput?.addEventListener('click', function (e) {
-    e.preventDefault();
-    this.blur();
-    (window as any).searchModalState.toggle();
-  });
-
-  // Listen for modal state changes to update page elements
-  window.addEventListener('searchModalToggle', (event) => {
-    // Handle custom docs sidebars
-    const customDocsSidebars = document.querySelectorAll('aside[class*="fixed"][class*="z-10"]');
-
-    if ((event as any).detail.isOpen) {
-      if (header) header.classList.remove('backdrop-blur-sm');
-      if (verticalNav) verticalNav.style.zIndex = '-100';
-      // Hide custom docs sidebars when modal opens
-      customDocsSidebars.forEach((sidebar: any) => {
-        sidebar.style.zIndex = '-100';
-      });
-    } else {
-      if (header) header.classList.add('backdrop-blur-sm');
-      if (verticalNav) verticalNav.style.zIndex = '10';
-      // Restore custom docs sidebars when modal closes
-      customDocsSidebars.forEach((sidebar: any) => {
-        sidebar.style.zIndex = '10';
-      });
-    }
-  });
-</script>
-
-<style>
-  .line-clamp-2 {
-    display: -webkit-box;
-    -webkit-line-clamp: 2;
-    -webkit-box-orient: vertical;
-    overflow: hidden;
-  }
-</style>
diff --git a/eventcatalog/src/components/Search/SearchModal.tsx b/eventcatalog/src/components/Search/SearchModal.tsx
deleted file mode 100644
index 87f165bc9..000000000
--- a/eventcatalog/src/components/Search/SearchModal.tsx
+++ /dev/null
@@ -1,766 +0,0 @@
-import React, { useState, useEffect, useCallback, useMemo } from 'react';
-import {
-  MagnifyingGlassIcon,
-  QueueListIcon,
-  RectangleGroupIcon,
-  BoltIcon,
-  ChatBubbleLeftIcon,
-  ServerIcon,
-  UserGroupIcon,
-  UserIcon,
-  BookOpenIcon,
-  DocumentTextIcon,
-  CubeIcon,
-} from '@heroicons/react/24/outline';
-
-interface SearchResult {
-  id: string;
-  name: string;
-  type: string;
-  description: string;
-  url: string;
-  tags: string[];
-}
-
-// Memoized SearchResult component for better performance
-const SearchResultItem = React.memo<{
-  item: SearchResult;
-  typeConfig: any;
-  currentSearch: string;
-}>(({ item, typeConfig, currentSearch }) => {
-  const config = typeConfig[item.type as keyof typeof typeConfig] || typeConfig.other;
-  const getDisplayType = (type: string) => {
-    if (type === 'other') return 'Page';
-    if (type === 'asyncapi') return 'AsyncAPI';
-    if (type === 'openapi') return 'OpenAPI';
-    if (type === 'language') return 'Language';
-    if (type === 'entities') return 'Entity';
-    if (type === 'queries') return 'Query';
-    // For plurals, remove 's' at the end, otherwise just capitalize
-    if (type.endsWith('s')) {
-      return type.charAt(0).toUpperCase() + type.slice(1, -1);
-    }
-    return type.charAt(0).toUpperCase() + type.slice(1);
-  };
-  const displayType = getDisplayType(item.type);
-  const IconComponent = config.icon;
-
-  return (
-    <a href={item.url} className="block group">
-      <div
-        className={`bg-gradient-to-br ${config.bg} to-white border rounded-lg p-3 hover:border-purple-300 hover:shadow-md transition-all duration-200 group-hover:shadow-lg ${config.border}`}
-      >
-        <div className="flex items-start justify-between mb-2">
-          <h3 className="text-base font-semibold text-gray-900 group-hover:text-purple-700 transition-colors">{item.name}</h3>
-          <span
-            className={`inline-flex items-center gap-1 px-2 py-0.5 rounded-full text-xs font-medium ${config.badgeBg} ${config.text} ${config.border} border`}
-          >
-            <IconComponent className="h-3 w-3" />
-            {displayType}
-          </span>
-        </div>
-        {item.description && (
-          <div className="text-xs text-gray-500 mb-2 line-clamp-2 opacity-80">
-            {currentSearch.trim() ? (
-              <span dangerouslySetInnerHTML={{ __html: item.description }} />
-            ) : (
-              <span>{item.description.replace(/<[^>]*>/g, '')}</span>
-            )}
-          </div>
-        )}
-        {item.tags.length > 0 && (
-          <div className="flex flex-wrap gap-1">
-            {item.tags.map((tag, index) => (
-              <span
-                key={index}
-                className="inline-flex items-center px-1.5 py-0.5 rounded-md text-xs font-medium bg-gray-100 text-gray-700"
-              >
-                {tag}
-              </span>
-            ))}
-          </div>
-        )}
-      </div>
-    </a>
-  );
-});
-
-// Memoized SearchResults component
-const SearchResults = React.memo<{
-  results: SearchResult[];
-  typeConfig: any;
-  currentSearch: string;
-}>(({ results, typeConfig, currentSearch }) => {
-  return (
-    <>
-      {results.map((item) => (
-        <SearchResultItem key={item.id} item={item} typeConfig={typeConfig} currentSearch={currentSearch} />
-      ))}
-    </>
-  );
-});
-
-const SearchModal: React.FC = () => {
-  const [isOpen, setIsOpen] = useState(false);
-  const [pagefind, setPagefind] = useState<any>(null);
-  const [pagefindLoadError, setPagefindLoadError] = useState(false);
-  const [currentSearch, setCurrentSearch] = useState('');
-  const [currentFilter, setCurrentFilter] = useState('all');
-  const [allResults, setAllResults] = useState<SearchResult[]>([]);
-  const [isLoading, setIsLoading] = useState(false);
-  const [exactMatch, setExactMatch] = useState(false);
-
-  // Listen for modal state changes from Astro component
-  useEffect(() => {
-    const handleModalToggle = (event: CustomEvent) => {
-      setIsOpen(event.detail.isOpen);
-    };
-
-    window.addEventListener('searchModalToggle', handleModalToggle as EventListener);
-    return () => window.removeEventListener('searchModalToggle', handleModalToggle as EventListener);
-  }, []);
-
-  const onClose = () => {
-    if ((window as any).searchModalState) {
-      (window as any).searchModalState.close();
-    }
-  };
-
-  // Type colors and icons - memoized to prevent recreating on every render
-  const typeConfig = useMemo(
-    () => ({
-      domains: {
-        bg: 'bg-orange-50/10',
-        badgeBg: 'bg-orange-500/20',
-        text: 'text-orange-800',
-        border: 'border-orange-200',
-        icon: RectangleGroupIcon,
-      },
-      services: {
-        bg: 'bg-pink-50/10',
-        badgeBg: 'bg-pink-500/20',
-        text: 'text-pink-800',
-        border: 'border-pink-200',
-        icon: ServerIcon,
-      },
-      events: {
-        bg: 'bg-orange-50/10',
-        badgeBg: 'bg-orange-500/20',
-        text: 'text-orange-800',
-        border: 'border-orange-200',
-        icon: BoltIcon,
-      },
-      commands: {
-        bg: 'bg-blue-50/10',
-        badgeBg: 'bg-blue-500/20',
-        text: 'text-blue-800',
-        border: 'border-blue-200',
-        icon: ChatBubbleLeftIcon,
-      },
-      queries: {
-        bg: 'bg-green-50/10',
-        badgeBg: 'bg-green-500/20',
-        text: 'text-green-800',
-        border: 'border-green-200',
-        icon: MagnifyingGlassIcon,
-      },
-      entities: {
-        bg: 'bg-purple-50/10',
-        badgeBg: 'bg-purple-500/20',
-        text: 'text-purple-800',
-        border: 'border-purple-200',
-        icon: CubeIcon,
-      },
-      channels: {
-        bg: 'bg-indigo-50/10',
-        badgeBg: 'bg-indigo-500/20',
-        text: 'text-indigo-800',
-        border: 'border-indigo-200',
-        icon: QueueListIcon,
-      },
-      teams: {
-        bg: 'bg-teal-50/10',
-        badgeBg: 'bg-teal-500/20',
-        text: 'text-teal-800',
-        border: 'border-teal-200',
-        icon: UserGroupIcon,
-      },
-      users: {
-        bg: 'bg-cyan-50/10',
-        badgeBg: 'bg-cyan-500/20',
-        text: 'text-cyan-800',
-        border: 'border-cyan-200',
-        icon: UserIcon,
-      },
-      language: {
-        bg: 'bg-amber-50/10',
-        badgeBg: 'bg-amber-500/20',
-        text: 'text-amber-800',
-        border: 'border-amber-200',
-        icon: BookOpenIcon,
-      },
-      openapi: {
-        bg: 'bg-emerald-50/10',
-        badgeBg: 'bg-emerald-500/20',
-        text: 'text-emerald-800',
-        border: 'border-emerald-200',
-        icon: DocumentTextIcon,
-      },
-      asyncapi: {
-        bg: 'bg-violet-50/10',
-        badgeBg: 'bg-violet-500/20',
-        text: 'text-violet-800',
-        border: 'border-violet-200',
-        icon: DocumentTextIcon,
-      },
-      other: {
-        bg: 'bg-gray-50/10',
-        badgeBg: 'bg-gray-500/20',
-        text: 'text-gray-800',
-        border: 'border-gray-200',
-        icon: DocumentTextIcon,
-      },
-    }),
-    []
-  );
-
-  // Initialize Pagefind
-  useEffect(() => {
-    if (typeof window !== 'undefined') {
-      const initPagefind = async () => {
-        try {
-          // Wait for Pagefind to be loaded by the Astro script
-          const waitForPagefind = () =>
-            new Promise<any>((resolve, reject) => {
-              if ((window as any).pagefind) {
-                resolve((window as any).pagefind);
-              } else {
-                const handler = () => {
-                  window.removeEventListener('pagefindLoaded', handler);
-                  resolve((window as any).pagefind);
-                };
-
-                // Set a timeout to detect if pagefind fails to load
-                const timeout = setTimeout(() => {
-                  window.removeEventListener('pagefindLoaded', handler);
-                  reject(new Error('Pagefind failed to load - catalog may not be indexed'));
-                }, 2000); // 5 second timeout
-
-                window.addEventListener('pagefindLoaded', () => {
-                  clearTimeout(timeout);
-                  handler();
-                });
-              }
-            });
-
-          const pagefindModule = await waitForPagefind();
-          await pagefindModule.init();
-          setPagefind(pagefindModule);
-        } catch (error) {
-          console.error('Failed to initialize Pagefind:', error);
-          setPagefindLoadError(true);
-        }
-      };
-
-      initPagefind();
-    }
-  }, []);
-
-  // Type mapping based on URL patterns - memoized callback
-  const getTypeFromUrl = useCallback((url: string): string => {
-    // Check for language first since it can be nested under other paths
-    if (url.includes('/language/')) return 'language';
-    // Check for spec types after language but before other types since they can be nested
-    if (url.includes('/spec/')) return 'openapi';
-    if (url.includes('/asyncapi')) return 'asyncapi';
-    if (url.includes('/domains/')) return 'domains';
-    if (url.includes('/services/')) return 'services';
-    if (url.includes('/events/')) return 'events';
-    if (url.includes('/commands/')) return 'commands';
-    if (url.includes('/queries/')) return 'queries';
-    if (url.includes('/entities/')) return 'entities';
-    if (url.includes('/channels/')) return 'channels';
-    if (url.includes('/teams/')) return 'teams';
-    if (url.includes('/users/')) return 'users';
-    return 'other';
-  }, []);
-
-  // Perform search
-  const performSearch = useCallback(
-    async (searchTerm: string): Promise<SearchResult[]> => {
-      if (!pagefind || !searchTerm.trim()) {
-        return [];
-      }
-
-      setIsLoading(true);
-
-      try {
-        const search = await pagefind.debouncedSearch(searchTerm);
-        if (!search || !search.results) {
-          return [];
-        }
-        const processedResults: SearchResult[] = [];
-
-        for (const result of search.results) {
-          const data = await result.data();
-          const type = getTypeFromUrl(data.url);
-
-          // Clean the title by removing any "Type | " prefix if it exists
-          let cleanTitle = data.meta?.title || 'Untitled';
-
-          // Use regex for more efficient prefix removal
-          cleanTitle = cleanTitle.replace(
-            /^(Domains?|Services?|Events?|Commands?|Queries?|Entities?|Channels?|Teams?|Users?|Language) \| /,
-            ''
-          );
-
-          processedResults.push({
-            id: result.id,
-            name: cleanTitle,
-            type: type,
-            description: data.excerpt || '',
-            url: data.url,
-            tags: data.meta?.tags ? data.meta.tags.split(',').map((tag: string) => tag.trim()) : [],
-          });
-        }
-
-        return processedResults;
-      } catch (error) {
-        console.error('Search error:', error);
-        return [];
-      } finally {
-        setIsLoading(false);
-      }
-    },
-    [pagefind]
-  );
-
-  // Filter results - memoized callback
-  const filterResults = useCallback(
-    (results: SearchResult[], filterType: string): SearchResult[] => {
-      let filteredResults = results;
-
-      // Apply type filter
-      if (filterType !== 'all') {
-        filteredResults = filteredResults.filter((item) => item.type === filterType);
-      }
-
-      // Apply exact match filter if enabled
-      if (exactMatch && currentSearch.trim()) {
-        filteredResults = filteredResults.filter((item) => item.name.toLowerCase().includes(currentSearch.toLowerCase()));
-      }
-
-      return filteredResults;
-    },
-    [exactMatch, currentSearch]
-  );
-
-  // Update results with debouncing
-  const updateResults = useCallback(async () => {
-    if (currentSearch.trim()) {
-      const results = await performSearch(currentSearch);
-      setAllResults(results);
-    } else {
-      setAllResults([]);
-    }
-  }, [currentSearch, performSearch]);
-
-  // Search on input change with debouncing
-  useEffect(() => {
-    if (!currentSearch.trim()) {
-      setAllResults([]);
-      return;
-    }
-
-    const debounceTimer = setTimeout(() => {
-      updateResults();
-    }, 300); // 300ms debounce
-
-    return () => clearTimeout(debounceTimer);
-  }, [currentSearch, updateResults]);
-
-  // Handle input change
-  const handleSearchChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    setCurrentSearch(e.target.value);
-  };
-
-  // Handle filter change
-  const handleFilterChange = (filter: string) => {
-    setCurrentFilter(filter);
-  };
-
-  // Get filtered results - memoized to prevent recalculation
-  const filteredResults = useMemo(() => {
-    return filterResults(allResults, currentFilter);
-  }, [allResults, currentFilter, exactMatch, currentSearch]);
-
-  // Get filter counts - memoized to prevent recalculation on every render
-  const getFilterCounts = useMemo(() => {
-    return {
-      all: allResults.length,
-      domains: allResults.filter((r) => r.type === 'domains').length,
-      services: allResults.filter((r) => r.type === 'services').length,
-      events: allResults.filter((r) => r.type === 'events').length,
-      commands: allResults.filter((r) => r.type === 'commands').length,
-      queries: allResults.filter((r) => r.type === 'queries').length,
-      entities: allResults.filter((r) => r.type === 'entities').length,
-      channels: allResults.filter((r) => r.type === 'channels').length,
-      teams: allResults.filter((r) => r.type === 'teams').length,
-      users: allResults.filter((r) => r.type === 'users').length,
-      language: allResults.filter((r) => r.type === 'language').length,
-      openapi: allResults.filter((r) => r.type === 'openapi').length,
-      asyncapi: allResults.filter((r) => r.type === 'asyncapi').length,
-    };
-  }, [allResults]);
-
-  const counts = getFilterCounts;
-
-  // Handle escape key
-  useEffect(() => {
-    const handleEscape = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') {
-        onClose();
-      }
-    };
-
-    if (isOpen) {
-      document.addEventListener('keydown', handleEscape);
-      return () => document.removeEventListener('keydown', handleEscape);
-    }
-  }, [isOpen, onClose]);
-
-  if (!isOpen) return null;
-
-  return (
-    <div>
-      <style>{`
-        .search-results mark {
-          background-color: #fef3c7;
-          color: #92400e;
-          padding: 0.125rem 0.25rem;
-          border-radius: 0.25rem;
-          font-weight: 500;
-        }
-      `}</style>
-      <div className="fixed inset-0 z-[9999] overflow-y-auto" role="dialog" aria-modal="true">
-        <div
-          className="fixed inset-0 bg-gray-500 bg-opacity-25 transition-opacity backdrop-blur-sm bg-black/10 z-[9998]"
-          onClick={onClose}
-        ></div>
-        <div className="fixed inset-0 z-[10000] w-screen overflow-y-auto p-4 sm:p-6 md:p-10" onClick={onClose}>
-          <div
-            className="mx-auto max-w-6xl divide-y divide-gray-100 overflow-hidden rounded-xl bg-white shadow-2xl ring-1 ring-black ring-opacity-5 transition-all"
-            onClick={(e) => e.stopPropagation()}
-          >
-            {pagefindLoadError ? (
-              // Show indexing required message when Pagefind fails to load - full modal content
-              <div className="flex items-center justify-center py-10 px-8">
-                <div className="text-left max-w-lg">
-                  <div className="mb-8">
-                    <h2 className="text-2xl font-bold text-gray-900 mb-3">Search Index Not Found</h2>
-                    <p className="text-gray-600 mb-8 leading-relaxed text-sm">
-                      Your EventCatalog needs to be built to generate the search index. This enables fast searching across all
-                      your domains, services, events, and documentation.
-                    </p>
-                  </div>
-
-                  <div className="bg-gradient-to-r from-gray-50 to-gray-100 rounded-xl p-6 mb-6 border border-gray-200">
-                    <h3 className="text-lg font-semibold text-gray-900 mb-4 flex items-center justify-center">
-                      <svg className="h-5 w-5 text-green-600 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M13 10V3L4 14h7v7l9-11h-7z" />
-                      </svg>
-                      Build Your Catalog
-                    </h3>
-                    <div className="bg-gray-900 rounded-lg p-4 mb-4">
-                      <code className="text-green-400 font-mono text-sm">npm run build</code>
-                    </div>
-                    <p className="text-sm text-gray-600">This will generate your catalog and create the search index</p>
-                  </div>
-
-                  <div className="flex items-start text-left bg-blue-50 rounded-lg p-4 border border-blue-200">
-                    <svg
-                      className="h-5 w-5 text-blue-600 mr-3 mt-0.5 flex-shrink-0"
-                      fill="none"
-                      stroke="currentColor"
-                      viewBox="0 0 24 24"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth="2"
-                        d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
-                      />
-                    </svg>
-                    <div>
-                      <h4 className="font-medium text-blue-900 mb-1">Need to update search results?</h4>
-                      <p className="text-sm text-blue-700">
-                        Run <code className="bg-blue-100 px-1 py-0.5 rounded text-xs font-mono">npm run build</code> again after
-                        making changes to your catalog content.
-                      </p>
-                    </div>
-                  </div>
-                </div>
-              </div>
-            ) : (
-              <>
-                {/* Search Input */}
-                <div className="relative px-6 pt-4 pb-2">
-                  <MagnifyingGlassIcon className="pointer-events-none absolute left-10 top-[25px] h-5 w-5 text-gray-400" />
-                  <input
-                    type="text"
-                    placeholder="Search for domains, services, events..."
-                    className="w-full border border-gray-200 rounded-lg bg-white pl-12 pr-4 py-2 text-gray-900 placeholder:text-gray-400 focus:ring-2 focus:ring-purple-500 focus:border-purple-500 text-sm"
-                    value={currentSearch}
-                    onChange={handleSearchChange}
-                    autoFocus
-                  />
-                </div>
-
-                {/* Main Content Area */}
-                <div className="flex h-[500px]">
-                  {/* Left Filters */}
-                  <div className="w-56 p-3 border-r border-gray-200 bg-gray-50 overflow-y-auto">
-                    {/* All Resources */}
-                    <div className="mb-4">
-                      <div className="space-y-1">
-                        <button
-                          className={`w-full px-2 py-1 text-xs rounded-md transition-colors ${
-                            currentFilter === 'all'
-                              ? 'bg-purple-200 text-purple-900 font-semibold'
-                              : 'hover:bg-purple-100 text-gray-700 hover:text-purple-800'
-                          }`}
-                          onClick={() => handleFilterChange('all')}
-                        >
-                          <div className="flex items-center justify-between">
-                            <div className="flex items-center gap-1.5">
-                              <span>All Resources</span>
-                            </div>
-                            <span className="text-xs text-gray-700 font-thin">{counts.all}</span>
-                          </div>
-                        </button>
-                      </div>
-                    </div>
-
-                    {/* Resources Section */}
-                    <div className="mb-4">
-                      <h3 className="text-xs font-bold text-gray-600 mb-2">Resources</h3>
-                      <div className="space-y-1">
-                        {Object.entries({
-                          domains: 'Domains',
-                          services: 'Services',
-                          entities: 'Entities',
-                          language: 'Ubiquitous Language',
-                        }).map(([key, label]) => {
-                          const config = typeConfig[key as keyof typeof typeConfig];
-                          const IconComponent = config?.icon;
-
-                          return (
-                            <button
-                              key={key}
-                              className={`w-full px-2 py-1 text-xs rounded-md transition-colors ${
-                                currentFilter === key
-                                  ? 'bg-purple-200 text-purple-900 font-semibold'
-                                  : 'hover:bg-purple-100 text-gray-700 hover:text-purple-800'
-                              }`}
-                              onClick={() => handleFilterChange(key)}
-                            >
-                              <div className="flex items-center justify-between">
-                                <div className="flex items-center gap-1.5">
-                                  {IconComponent && <IconComponent className="h-3 w-3" />}
-                                  <span className="font-thin">{label}</span>
-                                </div>
-                                <span className="text-xs text-gray-700 font-thin">{counts[key as keyof typeof counts]}</span>
-                              </div>
-                            </button>
-                          );
-                        })}
-                      </div>
-                    </div>
-
-                    {/* Messages Section */}
-                    <div className="mb-4">
-                      <h3 className="text-xs font-bold text-gray-600 mb-2">Messages</h3>
-                      <div className="space-y-1">
-                        {Object.entries({
-                          events: 'Events',
-                          commands: 'Commands',
-                          queries: 'Queries',
-                          channels: 'Channels',
-                        }).map(([key, label]) => {
-                          const config = typeConfig[key as keyof typeof typeConfig];
-                          const IconComponent = config?.icon;
-
-                          return (
-                            <button
-                              key={key}
-                              className={`w-full px-2 py-1 text-xs rounded-md transition-colors ${
-                                currentFilter === key
-                                  ? 'bg-purple-200 text-purple-900 font-semibold'
-                                  : 'hover:bg-purple-100 text-gray-700 hover:text-purple-800'
-                              }`}
-                              onClick={() => handleFilterChange(key)}
-                            >
-                              <div className="flex items-center justify-between">
-                                <div className="flex items-center gap-1.5">
-                                  {IconComponent && <IconComponent className="h-3 w-3" />}
-                                  <span className="font-thin">{label}</span>
-                                </div>
-                                <span className="text-xs text-gray-700 font-thin">{counts[key as keyof typeof counts]}</span>
-                              </div>
-                            </button>
-                          );
-                        })}
-                      </div>
-                    </div>
-
-                    {/* Organization Section */}
-                    <div className="mb-4">
-                      <h3 className="text-xs font-bold text-gray-600 mb-2">Organization</h3>
-                      <div className="space-y-1">
-                        {Object.entries({
-                          teams: 'Teams',
-                          users: 'Users',
-                        }).map(([key, label]) => {
-                          const config = typeConfig[key as keyof typeof typeConfig];
-                          const IconComponent = config?.icon;
-
-                          return (
-                            <button
-                              key={key}
-                              className={`w-full px-2 py-1 text-xs rounded-md transition-colors ${
-                                currentFilter === key
-                                  ? 'bg-purple-200 text-purple-900 font-semibold'
-                                  : 'hover:bg-purple-100 text-gray-700 hover:text-purple-800'
-                              }`}
-                              onClick={() => handleFilterChange(key)}
-                            >
-                              <div className="flex items-center justify-between">
-                                <div className="flex items-center gap-1.5">
-                                  {IconComponent && <IconComponent className="h-3 w-3" />}
-                                  <span className="font-thin">{label}</span>
-                                </div>
-                                <span className="text-xs text-gray-700 font-thin">{counts[key as keyof typeof counts]}</span>
-                              </div>
-                            </button>
-                          );
-                        })}
-                      </div>
-                    </div>
-
-                    {/* Specifications Section */}
-                    <div className="mb-4">
-                      <h3 className="text-xs font-bold text-gray-600 mb-2">Specifications</h3>
-                      <div className="space-y-1">
-                        {Object.entries({
-                          openapi: 'OpenAPI Specification',
-                          asyncapi: 'AsyncAPI Specification',
-                        }).map(([key, label]) => {
-                          const config = typeConfig[key as keyof typeof typeConfig];
-                          const IconComponent = config.icon;
-
-                          return (
-                            <button
-                              key={key}
-                              className={`w-full px-2 py-1 text-xs rounded-md transition-colors ${
-                                currentFilter === key
-                                  ? 'bg-purple-200 text-purple-900 font-semibold'
-                                  : 'hover:bg-purple-100 text-gray-700 hover:text-purple-800'
-                              }`}
-                              onClick={() => handleFilterChange(key)}
-                            >
-                              <div className="flex items-center justify-between">
-                                <div className="flex items-center gap-1.5">
-                                  <IconComponent className="h-3 w-3" />
-                                  <span className="font-thin">{label}</span>
-                                </div>
-                                <span className="text-xs text-gray-700 font-thin">{counts[key as keyof typeof counts]}</span>
-                              </div>
-                            </button>
-                          );
-                        })}
-                      </div>
-                    </div>
-                  </div>
-
-                  {/* Right Results */}
-                  <div className="flex-1 flex flex-col overflow-hidden">
-                    {/* Show stats and exact match toggle - only when there are results or search term */}
-                    {currentSearch.trim() && (filteredResults.length > 0 || isLoading) && (
-                      <div className="p-4 pb-2 flex items-center justify-between border-b border-gray-100">
-                        <div className="text-sm text-gray-500 font-thin">
-                          <span>{filteredResults.length} results</span> for "{currentSearch}"
-                          {isLoading && <span className="ml-2">Loading...</span>}
-                        </div>
-
-                        {/* Exact Match Checkbox */}
-                        <div className="flex items-center">
-                          <input
-                            id="exact-match-results"
-                            type="checkbox"
-                            checked={exactMatch}
-                            onChange={(e) => setExactMatch(e.target.checked)}
-                            className="h-4 w-4 text-purple-600 focus:ring-purple-500 border-gray-300 rounded"
-                          />
-                          <label htmlFor="exact-match-results" className="ml-2 text-sm text-gray-600">
-                            Exact match in title
-                          </label>
-                        </div>
-                      </div>
-                    )}
-
-                    {/* Main content area */}
-                    <div className="flex-1 overflow-y-auto">
-                      {!currentSearch.trim() ? (
-                        // Show when no search term is entered - centered
-                        <div className="h-full flex items-center justify-center">
-                          <div className="text-center">
-                            <MagnifyingGlassIcon className="mx-auto h-8 w-8 text-gray-300" />
-                            <h3 className="mt-4 text-lg font-medium text-gray-900">Discover your EventCatalog</h3>
-                            <p className="mt-2 text-sm text-gray-500 font-thin">
-                              Start typing to search for domains, services, events, and more.
-                            </p>
-                          </div>
-                        </div>
-                      ) : filteredResults.length === 0 && !isLoading ? (
-                        // Show when search term exists but no results and not loading - centered
-                        <div className="h-full flex items-center justify-center">
-                          <div className="text-center">
-                            <MagnifyingGlassIcon className="mx-auto h-8 w-8 text-gray-300" />
-                            <h3 className="mt-2 text-sm font-bold text-gray-900">No results found</h3>
-                            <p className="mt-1 text-sm text-gray-500 font-thin">
-                              No results found for "<span className="font-medium">{currentSearch}</span>".
-                            </p>
-                          </div>
-                        </div>
-                      ) : isLoading ? (
-                        // Show loading state - centered
-                        <div className="h-full flex items-center justify-center">
-                          <div className="text-center">
-                            <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-purple-600 mx-auto"></div>
-                            <h3 className="mt-4 text-sm font-medium text-gray-900">Searching...</h3>
-                            <p className="mt-2 text-sm text-gray-500 font-thin">
-                              Finding results for "<span className="font-medium">{currentSearch}</span>"
-                            </p>
-                          </div>
-                        </div>
-                      ) : (
-                        // Show results in a grid with padding
-                        <div className="p-4">
-                          <div className="search-results grid grid-cols-1 lg:grid-cols-2 gap-3">
-                            <SearchResults results={filteredResults} typeConfig={typeConfig} currentSearch={currentSearch} />
-                          </div>
-                        </div>
-                      )}
-                    </div>
-                  </div>
-                </div>
-              </>
-            )}
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-};
-
-export default SearchModal;
diff --git a/eventcatalog/src/components/SideBars/ChannelSideBar.astro b/eventcatalog/src/components/SideBars/ChannelSideBar.astro
deleted file mode 100644
index e99685d3e..000000000
--- a/eventcatalog/src/components/SideBars/ChannelSideBar.astro
+++ /dev/null
@@ -1,204 +0,0 @@
----
-import type { CollectionEntry } from 'astro:content';
-import PillListFlat from '@components/Lists/PillListFlat';
-import ProtocolList from '@components/Lists/ProtocolList';
-import OwnersList from '@components/Lists/OwnersList';
-import VersionList from '@components/Lists/VersionList.astro';
-import { buildUrl } from '@utils/url-builder';
-import { ScrollText } from 'lucide-react';
-import RepositoryList from '@components/Lists/RepositoryList.astro';
-import { getOwner } from '@utils/collections/owners';
-import { getProducersAndConsumersForChannel } from '@utils/collections/services';
-import { isChangelogEnabled } from '@utils/feature';
-interface Props {
-  channel: CollectionEntry<'channels'>;
-}
-
-const { channel } = Astro.props;
-
-const ownersRaw = channel.data?.owners || [];
-const owners = await Promise.all<ReturnType<typeof getOwner>>(ownersRaw.map(getOwner));
-const filteredOwners = owners.filter((o) => o !== undefined);
-const { producers, consumers } = await getProducersAndConsumersForChannel(channel);
-
-const channelParameters: Record<string, { enum?: string[]; description?: string }> = channel.data.parameters || {};
-const parameters = Object.keys(channelParameters).map((key) => ({
-  key,
-  ...channelParameters[key],
-}));
-
-const attachments = channel.data.attachments || [];
-
-const attachmentsList = attachments.map((a) => {
-  const attachmentIsURL = typeof a === 'string';
-  return {
-    label: attachmentIsURL ? a : (a.title ?? a.url),
-    href: attachmentIsURL ? a : a.url,
-    icon: attachmentIsURL ? 'ExternalLinkIcon' : (a.icon ?? 'ExternalLinkIcon'),
-    target: '_blank' as const,
-    subgroup: attachmentIsURL ? undefined : (a.type ?? ''),
-  };
-});
-
-const paramsList = parameters.map((param) => ({
-  label: param.key,
-  description: param?.description,
-  collection: 'channels-parameter',
-}));
-
-const protocols = channel.data.protocols || [];
-const protocolList = protocols.map((p) => ({
-  label: p,
-  collection: 'channels-protocol',
-  // icon: p,
-  icon: p,
-}));
-
-const ownersList = filteredOwners.map((o) => ({
-  label: o.data.name,
-  type: o.collection,
-  badge: o.collection === 'users' ? o.data.role : 'Team',
-  avatarUrl: o.collection === 'users' ? o.data.avatarUrl : '',
-  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
-}));
-
-const messageList = (channel.data.messages ?? []).map((p) => ({
-  label: p.name,
-  badge: p.collection,
-  color: p.collection === 'events' ? 'orange' : 'blue',
-  collection: p.collection,
-  tag: `v${p.version}`,
-  href: buildUrl(`/docs/${p.collection}/${p.id}/${p.version}`),
-}));
-
-const producersList = producers.map((p) => ({
-  label: p.data.name,
-  badge: p.collection,
-  color: 'pink',
-  collection: p.collection,
-  tag: `v${p.data.version}`,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-}));
-
-const consumersList = consumers.map((c) => ({
-  label: c.data.name,
-  badge: c.collection,
-  color: 'blue',
-  collection: c.collection,
-  tag: `v${c.data.version}`,
-  href: buildUrl(`/docs/${c.collection}/${c.data.id}/${c.data.version}`),
-}));
-
-const shouldRenderSideBarSection = (section: string) => {
-  if (!channel.data.detailsPanel) {
-    return true;
-  }
-  // @ts-ignore
-  return channel.data.detailsPanel[section]?.visible ?? true;
-};
----
-
-<aside class="sticky top-28 left-0 space-y-8 h-full overflow-y-auto py-4">
-  <div class="">
-    {
-      producersList.length > 0 && shouldRenderSideBarSection('producers') && (
-        <PillListFlat
-          title={`Producers (${producersList.length})`}
-          pills={producersList}
-          emptyMessage={`This channel does not have any producers.`}
-          color="pink"
-          client:load
-        />
-      )
-    }
-
-    {
-      consumersList.length > 0 && shouldRenderSideBarSection('consumers') && (
-        <PillListFlat
-          title={`Consumers (${consumersList.length})`}
-          pills={consumersList}
-          emptyMessage={`This channel does not have any consumers.`}
-          color="blue"
-          client:load
-        />
-      )
-    }
-
-    {
-      messageList.length > 0 && shouldRenderSideBarSection('messages') && (
-        <PillListFlat
-          title={`Messages using channel (${messageList.length})`}
-          pills={messageList}
-          emptyMessage={`This channel does not have any messages.`}
-          color="orange"
-          client:load
-        />
-      )
-    }
-
-    {
-      protocolList.length > 0 && shouldRenderSideBarSection('protocols') && (
-        <ProtocolList color="pink" title={`Protocols (${protocolList.length})`} pills={protocolList} client:load />
-      )
-    }
-
-    {
-      channel.data.versions && shouldRenderSideBarSection('versions') && (
-        <VersionList
-          title={`Versions (${channel.data.versions?.length})`}
-          versions={channel.data.versions}
-          collectionItem={channel}
-        />
-      )
-    }
-
-    {
-      channel.data.attachments && shouldRenderSideBarSection('attachments') && (
-        <PillListFlat
-          title={`Attachments (${attachmentsList.length})`}
-          pills={attachmentsList}
-          emptyMessage={`This channel does not have any attachments.`}
-          color="pink"
-          client:load
-        />
-      )
-    }
-
-    {
-      ownersList.length > 0 && shouldRenderSideBarSection('owners') && (
-        <OwnersList
-          title={`Owners (${filteredOwners.length})`}
-          owners={ownersList}
-          emptyMessage={`This channel does not have any documented owners.`}
-          client:load
-        />
-      )
-    }
-
-    {
-      channel.data.repository && shouldRenderSideBarSection('repository') && (
-        <RepositoryList repository={channel.data.repository?.url} language={channel.data.repository?.language} />
-      )
-    }
-
-    {
-      paramsList.length > 0 && shouldRenderSideBarSection('parameters') && (
-        <PillListFlat color="pink" title={`Parameters (${paramsList.length})`} pills={paramsList} client:load />
-      )
-    }
-
-    {
-      isChangelogEnabled() && shouldRenderSideBarSection('changelog') && (
-        <div class="space-y-2">
-          <a
-            href={buildUrl(`/docs/${channel.collection}/${channel.data.id}/${channel.data.latestVersion}/changelog`)}
-            class="flex items-center space-x-2 justify-center text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <ScrollText strokeWidth={2} size={16} />
-            <span class="block">Read changelog</span>
-          </a>
-        </div>
-      )
-    }
-  </div>
-</aside>
diff --git a/eventcatalog/src/components/SideBars/ContainerSideBar.astro b/eventcatalog/src/components/SideBars/ContainerSideBar.astro
deleted file mode 100644
index 0ece9ed9e..000000000
--- a/eventcatalog/src/components/SideBars/ContainerSideBar.astro
+++ /dev/null
@@ -1,183 +0,0 @@
----
-import type { CollectionEntry } from 'astro:content';
-import PillListFlat from '@components/Lists/PillListFlat';
-import OwnersList from '@components/Lists/OwnersList';
-import VersionList from '@components/Lists/VersionList.astro';
-import { buildUrl } from '@utils/url-builder';
-import { ScrollText, Workflow, RssIcon } from 'lucide-react';
-import RepositoryList from '@components/Lists/RepositoryList.astro';
-import { getOwner } from '@utils/collections/owners';
-import CustomSideBarSectionList from '@components/Lists/CustomSideBarSectionList.astro';
-import { isChangelogEnabled, isVisualiserEnabled } from '@utils/feature';
-import config from '@config';
-
-interface Props {
-  container: CollectionEntry<'containers'>;
-}
-
-const { container } = Astro.props;
-
-const servicesThatWriteToContainer = (container.data.servicesThatWriteToContainer as CollectionEntry<'services'>[]) || [];
-const servicesThatReadFromContainer = (container.data.servicesThatReadFromContainer as CollectionEntry<'services'>[]) || [];
-const ownersRaw = container.data?.owners || [];
-
-const owners = await Promise.all<ReturnType<typeof getOwner>>(ownersRaw.map(getOwner));
-const filteredOwners = owners.filter((o) => o !== undefined);
-const resourceGroups = container.data?.resourceGroups || [];
-const attachments = container.data.attachments || [];
-
-const attachmentsList = attachments.map((a) => {
-  const attachmentIsURL = typeof a === 'string';
-  return {
-    label: attachmentIsURL ? a : (a.title ?? a.url),
-    href: attachmentIsURL ? a : a.url,
-    icon: attachmentIsURL ? 'ExternalLinkIcon' : (a.icon ?? 'ExternalLinkIcon'),
-    target: '_blank' as const,
-    subgroup: attachmentIsURL ? undefined : (a.type ?? ''),
-  };
-});
-
-const writesToList = servicesThatWriteToContainer?.map((p) => ({
-  label: p.data.name,
-  tag: `v${p.data.version}`,
-  collection: p.collection,
-  href: buildUrl(`/docs/services/${p.data.id}/${p.data.version}`),
-}));
-
-const readsFromList = servicesThatReadFromContainer?.map((p) => ({
-  label: p.data.name,
-  tag: `v${p.data.version}`,
-  collection: p.collection,
-  href: buildUrl(`/docs/services/${p.data.id}/${p.data.version}`),
-}));
-
-const ownersList = filteredOwners.map((o) => ({
-  label: o.data.name,
-  type: o.collection,
-  badge: o.collection === 'users' ? o.data.role : 'Team',
-  avatarUrl: o.collection === 'users' ? o.data.avatarUrl : '',
-  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
-}));
-
-const shouldRenderSideBarSection = (section: string) => {
-  if (!container.data.detailsPanel) {
-    return true;
-  }
-  // @ts-ignore
-  return container.data.detailsPanel[section]?.visible ?? true;
-};
-
-const isRSSEnabled = config.rss?.enabled;
----
-
-<aside class="sticky top-28 left-0 space-y-8 h-full overflow-y-auto py-4">
-  <div class="">
-    {
-      resourceGroups
-        .filter((section) => section.items.length > 0 && section.sidebar)
-        .map((section) => <CustomSideBarSectionList section={section} />)
-    }
-    {
-      writesToList.length > 0 && shouldRenderSideBarSection('services') && (
-        <PillListFlat
-          color="pink"
-          title={`Services (writes) (${writesToList.length})`}
-          pills={writesToList}
-          emptyMessage={'No services are using this resource.'}
-          client:load
-        />
-      )
-    }
-    {
-      readsFromList.length > 0 && shouldRenderSideBarSection('services') && (
-        <PillListFlat
-          color="pink"
-          title={`Services (reads) (${readsFromList.length})`}
-          pills={readsFromList}
-          emptyMessage={'No services are using this resource.'}
-          client:load
-        />
-      )
-    }
-
-    {
-      container.data.versions && shouldRenderSideBarSection('versions') && (
-        <VersionList
-          title={`Versions (${container.data.versions?.length})`}
-          versions={container.data.versions}
-          collectionItem={container}
-        />
-      )
-    }
-
-    {
-      container.data.attachments && shouldRenderSideBarSection('attachments') && (
-        <PillListFlat
-          title={`Attachments (${attachmentsList.length})`}
-          pills={attachmentsList}
-          emptyMessage={`This resource does not have any attachments.`}
-          color="pink"
-          client:load
-        />
-      )
-    }
-
-    {
-      ownersList.length > 0 && shouldRenderSideBarSection('owners') && (
-        <OwnersList
-          title={`Owners (${ownersList.length})`}
-          owners={ownersList}
-          emptyMessage={`This resource does not have any documented owners.`}
-          client:load
-        />
-      )
-    }
-
-    {
-      container.data.repository && shouldRenderSideBarSection('repository') && (
-        <RepositoryList repository={container.data.repository?.url} language={container.data.repository?.language} />
-      )
-    }
-
-    {
-      isRSSEnabled && (
-        <div class="mx-auto pb-8 w-full max-w-lg divide-y divide-white/5 rounded-xl bg-white/5">
-          <span class="text-sm text-black font-semibold group-data-[hover]:text-black/80 capitalize">Container RSS Feed</span>
-          <ul role="list" class="space-y-2 mt-2">
-            <li class="has-tooltip rounded-md text-gray-600 group px-1 w-full hover:bg-gradient-to-l hover:from-purple-500 hover:to-purple-700 hover:text-white hover:font-normal  ">
-              <a class={`flex items-center space-x-2`} target="_blank" href={buildUrl(`/rss/${container.collection}/rss.xml`)}>
-                <RssIcon className="h-4 w-4 text-gray-800 group-hover:text-white" strokeWidth={1} />
-                <span class="font-light text-sm truncate">RSS Feed</span>
-              </a>
-            </li>
-          </ul>
-        </div>
-      )
-    }
-
-    <div class="space-y-2">
-      {
-        isVisualiserEnabled() && (
-          <a
-            href={buildUrl(`/visualiser/${container.collection}/${container.data.id}/${container.data.version}`)}
-            class="flex items-center justify-center space-x-2 text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <Workflow strokeWidth={2} size={16} />
-            <span class="block">View in visualiser</span>
-          </a>
-        )
-      }
-      {
-        isChangelogEnabled() && shouldRenderSideBarSection('changelog') && (
-          <a
-            href={buildUrl(`/docs/${container.collection}/${container.data.id}/${container.data.latestVersion}/changelog`)}
-            class="flex items-center space-x-2 justify-center text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <ScrollText strokeWidth={2} size={16} />
-            <span class="block">Read changelog</span>
-          </a>
-        )
-      }
-    </div>
-  </div>
-</aside>
diff --git a/eventcatalog/src/components/SideBars/DomainSideBar.astro b/eventcatalog/src/components/SideBars/DomainSideBar.astro
deleted file mode 100644
index f43b16359..000000000
--- a/eventcatalog/src/components/SideBars/DomainSideBar.astro
+++ /dev/null
@@ -1,277 +0,0 @@
----
-import OwnersList from '@components/Lists/OwnersList';
-import PillListFlat from '@components/Lists/PillListFlat';
-import RepositoryList from '@components/Lists/RepositoryList.astro';
-import VersionList from '@components/Lists/VersionList.astro';
-import { getUbiquitousLanguage, getMessagesForDomain, getParentDomains } from '@utils/collections/domains';
-import CustomSideBarSectionList from '@components/Lists/CustomSideBarSectionList.astro';
-import { getOwner } from '@utils/collections/owners';
-import { buildUrl } from '@utils/url-builder';
-import type { CollectionEntry } from 'astro:content';
-import { ScrollText, Workflow } from 'lucide-react';
-import { isChangelogEnabled, isVisualiserEnabled } from '@utils/feature';
-
-interface Props {
-  domain: CollectionEntry<'domains'>;
-}
-
-const { domain } = Astro.props;
-
-// @ts-ignore
-const services = (domain.data.services as CollectionEntry<'services'>[]) || [];
-// @ts-ignore
-const subDomains = (domain.data.domains as CollectionEntry<'domains'>[]) || [];
-
-// @ts-ignore
-const entities = (domain.data.entities as CollectionEntry<'entities'>[]) || [];
-
-const attachments = domain.data.attachments || [];
-
-const ubiquitousLanguage = await getUbiquitousLanguage(domain);
-const hasUbiquitousLanguage = ubiquitousLanguage.length > 0;
-const ubiquitousLanguageDictionary = hasUbiquitousLanguage ? ubiquitousLanguage[0].data.dictionary : [];
-
-const ownersRaw = domain.data?.owners || [];
-const owners = await Promise.all<ReturnType<typeof getOwner>>(ownersRaw.map(getOwner));
-const filteredOwners = owners.filter((o) => o !== undefined);
-
-const messagesForDomain = await getMessagesForDomain(domain);
-
-const resourceGroups = domain.data?.resourceGroups || [];
-
-const parentDomains = await getParentDomains(domain);
-
-const serviceList = services.map((p) => ({
-  label: p.data.name,
-  badge: p.collection,
-  tag: `v${p.data.version}`,
-  collection: p.collection,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-}));
-
-const subDomainList = subDomains.map((p) => ({
-  label: p.data.name,
-  badge: p.collection,
-  tag: `v${p.data.version}`,
-  collection: p.collection,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-}));
-
-const parentDomainList = parentDomains.map((p) => ({
-  label: p.data.name,
-  badge: p.collection,
-  tag: `v${p.data.version}`,
-  collection: p.collection,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-}));
-
-const sendsList = messagesForDomain.sends
-  .sort((a, b) => a.collection.localeCompare(b.collection))
-  .map((p) => ({
-    label: p.data.name,
-    badge: p.collection,
-    tag: `v${p.data.version}`,
-    collection: p.collection,
-    href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-  }));
-
-const receivesList = messagesForDomain.receives
-  .sort((a, b) => a.collection.localeCompare(b.collection))
-  .map((p) => ({
-    label: p.data.name,
-    badge: p.collection,
-    tag: `v${p.data.version}`,
-    collection: p.collection,
-    href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-  }));
-
-const ubiquitousLanguageList = ubiquitousLanguageDictionary?.map((l) => ({
-  label: l.name,
-  badge: 'Ubiquitous Language',
-  collection: 'ubiquitousLanguages',
-  href: buildUrl(`/docs/${domain.collection}/${domain.data.id}/language?id=${l.id}`),
-}));
-
-const entityList = entities.map((p) => ({
-  label: p.data.name,
-  badge: p.collection,
-  tag: `v${p.data.version}`,
-  collection: p.collection,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-}));
-
-const ownersList = filteredOwners.map((o) => ({
-  label: o.data.name,
-  type: o.collection,
-  badge: o.collection === 'users' ? o.data.role : 'Team',
-  avatarUrl: o.collection === 'users' ? o.data.avatarUrl : '',
-  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
-}));
-
-const attachmentsList = attachments.map((a) => {
-  const attachmentIsURL = typeof a === 'string';
-
-  return {
-    label: attachmentIsURL ? a : (a.title ?? a.url),
-    href: attachmentIsURL ? a : a.url,
-    icon: attachmentIsURL ? 'ExternalLinkIcon' : (a.icon ?? 'ExternalLinkIcon'),
-    target: '_blank' as const,
-    subgroup: attachmentIsURL ? undefined : (a.type ?? ''),
-  };
-});
-
-const shouldRenderSideBarSection = (section: string) => {
-  if (!domain.data.detailsPanel) {
-    return true;
-  }
-  // @ts-ignore
-  return domain.data.detailsPanel[section]?.visible ?? true;
-};
----
-
-<aside class="sticky top-28 left-0 space-y-8 h-full overflow-y-auto py-4">
-  <div>
-    {
-      parentDomains.length > 0 && shouldRenderSideBarSection('parentDomains') && (
-        <PillListFlat
-          title={`Parent domains (${parentDomains.length})`}
-          pills={parentDomainList}
-          emptyMessage={`This domain does not have any parent domains.`}
-          color="pink"
-          icon="ServerIcon"
-          client:load
-        />
-      )
-    }
-
-    {
-      subDomains.length > 0 && shouldRenderSideBarSection('subdomains') && (
-        <PillListFlat
-          title={`Subdomains (${subDomains.length})`}
-          pills={subDomainList}
-          emptyMessage={`This domain does not contain any subdomains.`}
-          color="pink"
-          icon="ServerIcon"
-          client:load
-        />
-      )
-    }
-    {
-      resourceGroups
-        .filter((section) => section.items.length > 0 && section.sidebar)
-        .map((section) => <CustomSideBarSectionList section={section} />)
-    }
-    {
-      shouldRenderSideBarSection('services') && (
-        <PillListFlat
-          title={`Services (${services.length})`}
-          pills={serviceList}
-          emptyMessage={`This domain does not contain any services.`}
-          color="pink"
-          client:load
-        />
-      )
-    }
-    {
-      shouldRenderSideBarSection('messages') && (
-        <PillListFlat
-          title={`Sends messages (${sendsList.length})`}
-          pills={sendsList}
-          emptyMessage={`This domain does not send any messages.`}
-          color="orange"
-          client:load
-        />
-      )
-    }
-    {
-      shouldRenderSideBarSection('messages') && (
-        <PillListFlat
-          title={`Receives messages (${receivesList.length})`}
-          pills={receivesList}
-          emptyMessage={`This domain does not receive any messages.`}
-          color="orange"
-          client:load
-        />
-      )
-    }
-    {
-      ubiquitousLanguageList && hasUbiquitousLanguage && shouldRenderSideBarSection('ubiquitousLanguage') && (
-        <PillListFlat
-          title={`Ubiquitous Language Dictionary (${ubiquitousLanguageDictionary?.length})`}
-          pills={ubiquitousLanguageList}
-          color="pink"
-          limit={4}
-          emptyMessage={`This domain does not have any documented ubiquitous language.`}
-          client:load
-        />
-      )
-    }
-    {
-      entities.length > 0 && shouldRenderSideBarSection('entities') && (
-        <PillListFlat
-          title={`Entities (${entities.length})`}
-          pills={entityList}
-          emptyMessage={`This domain does not contain any entities.`}
-          color="pink"
-          client:load
-        />
-      )
-    }
-    {
-      domain.data.versions && shouldRenderSideBarSection('versions') && (
-        <VersionList versions={domain.data.versions} collectionItem={domain} />
-      )
-    }
-    {
-      domain.data.attachments && shouldRenderSideBarSection('attachments') && (
-        <PillListFlat
-          title={`Attachments (${attachmentsList.length})`}
-          pills={attachmentsList}
-          emptyMessage={`This domain does not have any attachments.`}
-          color="pink"
-          client:load
-        />
-      )
-    }
-    {
-      domain.data.repository && shouldRenderSideBarSection('repository') && (
-        <RepositoryList repository={domain.data.repository?.url} language={domain.data.repository?.language} />
-      )
-    }
-    {
-      shouldRenderSideBarSection('owners') && (
-        <OwnersList
-          title={`Owners (${ownersList.length})`}
-          owners={ownersList}
-          emptyMessage={`This domain does not have any documented owners.`}
-          client:load
-        />
-      )
-    }
-
-    <div class="space-y-2">
-      {
-        isVisualiserEnabled() && (
-          <a
-            href={buildUrl(`/visualiser/${domain.collection}/${domain.data.id}/${domain.data.version}`)}
-            class="flex items-center justify-center space-x-2 text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <Workflow strokeWidth={2} size={16} />
-            <span class="block">View in visualiser</span>
-          </a>
-        )
-      }
-      {
-        isChangelogEnabled() && shouldRenderSideBarSection('changelog') && (
-          <a
-            href={buildUrl(`/docs/${domain.collection}/${domain.data.id}/${domain.data.latestVersion}/changelog`)}
-            class="flex items-center space-x-2 justify-center text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <ScrollText strokeWidth={2} size={16} />
-            <span class="block">Read changelog</span>
-          </a>
-        )
-      }
-    </div>
-  </div>
-</aside>
diff --git a/eventcatalog/src/components/SideBars/EntitySideBar.astro b/eventcatalog/src/components/SideBars/EntitySideBar.astro
deleted file mode 100644
index ceba00f68..000000000
--- a/eventcatalog/src/components/SideBars/EntitySideBar.astro
+++ /dev/null
@@ -1,139 +0,0 @@
----
-import type { CollectionEntry } from 'astro:content';
-import PillListFlat from '@components/Lists/PillListFlat';
-import OwnersList from '@components/Lists/OwnersList';
-import VersionList from '@components/Lists/VersionList.astro';
-import { buildUrl } from '@utils/url-builder';
-import { ScrollText } from 'lucide-react';
-import { getOwner } from '@utils/collections/owners';
-import { isChangelogEnabled } from '@utils/feature';
-
-interface Props {
-  entity: CollectionEntry<'entities'>;
-}
-
-const { entity } = Astro.props;
-
-const ownersRaw = entity.data?.owners || [];
-const owners = await Promise.all<ReturnType<typeof getOwner>>(ownersRaw.map(getOwner));
-const filteredOwners = owners.filter((o) => o !== undefined);
-
-// @ts-ignore
-const services = (entity.data.services as CollectionEntry<'services'>[]) || [];
-// @ts-ignore
-const domains = (entity.data.domains as CollectionEntry<'domains'>[]) || [];
-
-const attachments = entity.data.attachments || [];
-
-const attachmentsList = attachments.map((a) => {
-  const attachmentIsURL = typeof a === 'string';
-  return {
-    label: attachmentIsURL ? a : (a.title ?? a.url),
-    href: attachmentIsURL ? a : a.url,
-    icon: attachmentIsURL ? 'ExternalLinkIcon' : (a.icon ?? 'ExternalLinkIcon'),
-    target: '_blank' as const,
-    subgroup: attachmentIsURL ? undefined : (a.type ?? ''),
-  };
-});
-
-const ownersList = filteredOwners.map((o) => ({
-  label: o.data.name,
-  type: o.collection,
-  badge: o.collection === 'users' ? o.data.role : 'Team',
-  avatarUrl: o.collection === 'users' ? o.data.avatarUrl : '',
-  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
-}));
-
-const servicesList = services.map((p) => ({
-  label: p.data.name,
-  badge: p.collection,
-  color: 'pink',
-  collection: p.collection,
-  tag: `v${p.data.version}`,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-}));
-
-const domainsList = domains.map((p) => ({
-  label: p.data.name,
-  badge: p.collection,
-  color: 'blue',
-  collection: p.collection,
-  tag: `v${p.data.version}`,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-}));
-
-const shouldRenderSideBarSection = (section: string) => {
-  if (!entity.data.detailsPanel) {
-    return true;
-  }
-  // @ts-ignore
-  return entity.data.detailsPanel[section]?.visible ?? true;
-};
----
-
-<aside class="sticky top-28 left-0 space-y-8 h-full overflow-y-auto py-4">
-  <div class="">
-    {
-      shouldRenderSideBarSection('domains') && (
-        <PillListFlat
-          title={`Domains (${domainsList.length})`}
-          pills={domainsList}
-          emptyMessage={`This entity is not used in any domains.`}
-          color="blue"
-          client:load
-        />
-      )
-    }
-    {
-      servicesList.length > 0 && shouldRenderSideBarSection('services') && (
-        <PillListFlat
-          title={`Services (${servicesList.length})`}
-          pills={servicesList}
-          emptyMessage={`This entity is not used in any services.`}
-          color="pink"
-          client:load
-        />
-      )
-    }
-    {
-      entity.data.versions && shouldRenderSideBarSection('versions') && (
-        <VersionList versions={entity.data.versions} collectionItem={entity} />
-      )
-    }
-    {
-      entity.data.attachments && shouldRenderSideBarSection('attachments') && (
-        <PillListFlat
-          title={`Attachments (${attachmentsList.length})`}
-          pills={attachmentsList}
-          emptyMessage={`This entity does not have any attachments.`}
-          color="pink"
-          client:load
-        />
-      )
-    }
-    {
-      filteredOwners.length > 0 && shouldRenderSideBarSection('owners') && (
-        <OwnersList
-          title={`Owners (${filteredOwners.length})`}
-          owners={ownersList}
-          emptyMessage={`This entity does not have any documented owners.`}
-          client:load
-        />
-      )
-    }
-
-    {
-      isChangelogEnabled() && shouldRenderSideBarSection('changelog') && (
-        <div class="space-y-2">
-          <a
-            href={buildUrl(`/docs/${entity.collection}/${entity.data.id}/${entity.data.latestVersion}/changelog`)}
-            class="flex items-center space-x-2 justify-center text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <ScrollText strokeWidth={2} size={16} />
-            <span class="block">Read changelog</span>
-          </a>
-        </div>
-      )
-    }
-  </div>
-</aside>
diff --git a/eventcatalog/src/components/SideBars/FlowSideBar.astro b/eventcatalog/src/components/SideBars/FlowSideBar.astro
deleted file mode 100644
index 0bcaf45d4..000000000
--- a/eventcatalog/src/components/SideBars/FlowSideBar.astro
+++ /dev/null
@@ -1,132 +0,0 @@
----
-import OwnersList from '@components/Lists/OwnersList';
-import VersionList from '@components/Lists/VersionList.astro';
-import PillListFlat from '@components/Lists/PillListFlat';
-import { buildUrl } from '@utils/url-builder';
-import { getOwner } from '@utils/collections/owners';
-import type { CollectionEntry } from 'astro:content';
-import { ScrollText, Workflow, RssIcon } from 'lucide-react';
-import config from '@config';
-import { isChangelogEnabled, isVisualiserEnabled } from '@utils/feature';
-import CustomSideBarSectionList from '@components/Lists/CustomSideBarSectionList.astro';
-interface Props {
-  flow: CollectionEntry<'flows'>;
-}
-
-const { flow } = Astro.props;
-
-const ownersRaw = flow.data?.owners || [];
-const owners = await Promise.all<ReturnType<typeof getOwner>>(ownersRaw.map(getOwner));
-const filteredOwners = owners.filter((o) => o !== undefined);
-
-const resourceGroups = flow.data?.resourceGroups || [];
-
-const ownersList = filteredOwners.map((o) => ({
-  label: o.data.name,
-  type: o.collection,
-  badge: o.collection === 'users' ? o.data.role : 'Team',
-  avatarUrl: o.collection === 'users' ? o.data.avatarUrl : '',
-  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
-}));
-
-const isRSSEnabled = config.rss?.enabled;
-
-const attachments = flow.data.attachments || [];
-
-const attachmentsList = attachments.map((a) => {
-  const attachmentIsURL = typeof a === 'string';
-  return {
-    label: attachmentIsURL ? a : (a.title ?? a.url),
-    href: attachmentIsURL ? a : a.url,
-    icon: attachmentIsURL ? 'ExternalLinkIcon' : (a.icon ?? 'ExternalLinkIcon'),
-    target: '_blank' as const,
-    subgroup: attachmentIsURL ? undefined : (a.type ?? ''),
-  };
-});
-
-const shouldRenderSideBarSection = (section: string) => {
-  if (!flow.data.detailsPanel) {
-    return true;
-  }
-  // @ts-ignore
-  return flow.data.detailsPanel[section]?.visible ?? true;
-};
----
-
-<aside class="sticky top-28 left-0 h-full overflow-y-auto pr-6 py-4">
-  <div id="sidebar-cta-portal" class="">
-    {
-      resourceGroups
-        .filter((section) => section.items.length > 0 && section.sidebar)
-        .map((section) => <CustomSideBarSectionList section={section} />)
-    }
-    {
-      flow.data.versions && shouldRenderSideBarSection('versions') && (
-        <VersionList versions={flow.data.versions} collectionItem={flow} />
-      )
-    }
-    {
-      flow.data.attachments && shouldRenderSideBarSection('attachments') && (
-        <PillListFlat
-          title={`Attachments (${attachmentsList.length})`}
-          pills={attachmentsList}
-          emptyMessage={`This flow does not have any attachments.`}
-          color="pink"
-          client:load
-        />
-      )
-    }
-
-    {
-      shouldRenderSideBarSection('owners') && (
-        <OwnersList
-          title={`Owners (${ownersList.length})`}
-          owners={ownersList}
-          emptyMessage={`This flow does not have any documented owners.`}
-          client:load
-        />
-      )
-    }
-
-    {
-      isRSSEnabled && (
-        <div class="mx-auto pb-4 w-full max-w-lg divide-y divide-white/5 rounded-xl bg-white/5 border-b border-gray-100 mb-4">
-          <span class="text-sm text-black font-semibold group-data-[hover]:text-black/80 capitalize">Flow RSS Feed</span>
-          <ul role="list" class="space-y-2 mt-2">
-            <li class="has-tooltip rounded-md text-gray-600 group px-1 w-full hover:bg-gradient-to-l hover:from-purple-500 hover:to-purple-700 hover:text-white hover:font-normal  ">
-              <a class={`flex items-center space-x-2`} target="_blank" href={buildUrl(`/rss/flows/rss.xml`)}>
-                <RssIcon className="h-4 w-4 text-gray-800 group-hover:text-white" strokeWidth={1} />
-                <span class="font-light text-sm truncate">RSS</span>
-              </a>
-            </li>
-          </ul>
-        </div>
-      )
-    }
-
-    <div class="space-y-2">
-      {
-        isVisualiserEnabled() && (
-          <a
-            href={buildUrl(`/visualiser/${flow.collection}/${flow.data.id}/${flow.data.version}`)}
-            class="flex items-center justify-center space-x-2 text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <Workflow strokeWidth={2} size={16} />
-            <span class="block">View in visualiser</span>
-          </a>
-        )
-      }
-      {
-        isChangelogEnabled() && shouldRenderSideBarSection('changelog') && (
-          <a
-            href={buildUrl(`/docs/${flow.collection}/${flow.data.id}/${flow.data.latestVersion}/changelog`)}
-            class="flex items-center space-x-2 justify-center text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <ScrollText strokeWidth={2} size={16} />
-            <span class="block">Read changelog</span>
-          </a>
-        )
-      }
-    </div>
-  </div>
-</aside>
diff --git a/eventcatalog/src/components/SideBars/MessageSideBar.astro b/eventcatalog/src/components/SideBars/MessageSideBar.astro
deleted file mode 100644
index a75ac0297..000000000
--- a/eventcatalog/src/components/SideBars/MessageSideBar.astro
+++ /dev/null
@@ -1,251 +0,0 @@
----
-import type { CollectionEntry } from 'astro:content';
-import PillListFlat from '@components/Lists/PillListFlat';
-import OwnersList from '@components/Lists/OwnersList';
-import type { CollectionMessageTypes } from '@types';
-import * as path from 'path';
-import VersionList from '@components/Lists/VersionList.astro';
-import { buildUrl } from '@utils/url-builder';
-import { FileDownIcon, ScrollText, Workflow, RssIcon } from 'lucide-react';
-import RepositoryList from '@components/Lists/RepositoryList.astro';
-import { getOwner } from '@utils/collections/owners';
-import CustomSideBarSectionList from '@components/Lists/CustomSideBarSectionList.astro';
-import config from '@config';
-import { getSchemaFormatFromURL } from '@utils/collections/schemas';
-import { isChangelogEnabled, isVisualiserEnabled } from '@utils/feature';
-interface Props {
-  message: CollectionEntry<CollectionMessageTypes>;
-}
-
-const { message } = Astro.props;
-
-const producers = (message.data.producers as CollectionEntry<'services'>[]) || [];
-const consumers = (message.data.consumers as CollectionEntry<'services'>[]) || [];
-const channels = (message.data.messageChannels as CollectionEntry<'channels'>[]) || [];
-
-const ownersRaw = message.data?.owners || [];
-const owners = await Promise.all<ReturnType<typeof getOwner>>(ownersRaw.map(getOwner));
-const filteredOwners = owners.filter((o) => o !== undefined);
-
-const resourceGroups = message.data?.resourceGroups || [];
-
-const attachments = message.data.attachments || [];
-
-const attachmentsList = attachments.map((a) => {
-  const attachmentIsURL = typeof a === 'string';
-  return {
-    label: attachmentIsURL ? a : (a.title ?? a.url),
-    href: attachmentIsURL ? a : a.url,
-    icon: attachmentIsURL ? 'ExternalLinkIcon' : (a.icon ?? 'ExternalLinkIcon'),
-    target: '_blank' as const,
-    subgroup: attachmentIsURL ? undefined : (a.type ?? ''),
-  };
-});
-
-const producerList = producers.map((p) => ({
-  label: `${p.data.name}`,
-  tag: `v${p.data.version}`,
-  collection: p.collection,
-  href: buildUrl(`/docs/services/${p.data.id}/${p.data.version}`),
-}));
-
-const consumerList = consumers.map((p) => ({
-  label: `${p.data.name}`,
-  tag: `v${p.data.version}`,
-  collection: p.collection,
-  href: buildUrl(`/docs/services/${p.data.id}/${p.data.version}`),
-}));
-
-const ownersList = filteredOwners.map((o) => ({
-  label: o.data.name,
-  type: o.collection,
-  badge: o.collection === 'users' ? o.data.role : 'Team',
-  avatarUrl: o.collection === 'users' ? o.data.avatarUrl : '',
-  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
-}));
-
-const channelList = channels.map((c) => ({
-  label: `${c.data.name}`,
-  tag: `v${c.data.version}`,
-  collection: c.collection,
-  href: buildUrl(`/docs/channels/${c.data.id}/${c.data.version}`),
-}));
-
-const getType = (type: string) => {
-  switch (type) {
-    case 'queries':
-      return 'Query';
-    default:
-      return message.collection.slice(0, -1);
-  }
-};
-
-const getProducerEmptyMessage = (type: string) => {
-  const value = type.toLowerCase();
-  switch (value) {
-    case 'query':
-    case 'command':
-      return `This ${value} does not get invoked by any services.`;
-    default:
-      return `This ${value} does not get produced by any services.`;
-  }
-};
-
-const getConsumerEmptyMessage = (type: string) => {
-  const value = type.toLowerCase();
-  switch (value) {
-    case 'query':
-    case 'command':
-      return `This ${value} does not invoke any service.`;
-    default:
-      return `This ${value} does not get consumed by any services.`;
-  }
-};
-
-const type = getType(message.collection);
-
-const isRSSEnabled = config.rss?.enabled;
-
-// @ts-ignore
-const publicPath = message?.catalog?.publicPath;
-
-const schemaFilePath = message?.data?.schemaPath;
-const schemaURL = path.join(publicPath, schemaFilePath || '');
-
-const shouldRenderSideBarSection = (section: string) => {
-  if (!message.data.detailsPanel) {
-    return true;
-  }
-  // @ts-ignore
-  return message.data.detailsPanel[section]?.visible ?? true;
-};
----
-
-<aside class="sticky top-28 left-0 space-y-8 h-full overflow-y-auto py-4">
-  <div class="">
-    {
-      resourceGroups
-        .filter((section) => section.items.length > 0 && section.sidebar)
-        .map((section) => <CustomSideBarSectionList section={section} />)
-    }
-    {
-      producerList.length > 0 && shouldRenderSideBarSection('producers') && (
-        <PillListFlat
-          color="pink"
-          title={`Producers (${producerList.length})`}
-          pills={producerList}
-          emptyMessage={getProducerEmptyMessage(type)}
-          client:load
-        />
-      )
-    }
-    {
-      consumerList.length > 0 && shouldRenderSideBarSection('consumers') && (
-        <PillListFlat
-          color="pink"
-          title={`Consumers (${consumerList.length})`}
-          pills={consumerList}
-          emptyMessage={getConsumerEmptyMessage(type)}
-          client:load
-        />
-      )
-    }
-    {
-      channelList.length > 0 && shouldRenderSideBarSection('channels') && (
-        <PillListFlat color="pink" title={`Channels (${channelList.length})`} pills={channelList} client:load />
-      )
-    }
-
-    {
-      message.data.versions && shouldRenderSideBarSection('versions') && (
-        <VersionList
-          title={`Versions (${message.data.versions?.length})`}
-          versions={message.data.versions}
-          collectionItem={message}
-        />
-      )
-    }
-
-    {
-      message.data.attachments && shouldRenderSideBarSection('attachments') && (
-        <PillListFlat
-          title={`Attachments (${attachmentsList.length})`}
-          pills={attachmentsList}
-          emptyMessage={`This ${type} does not have any attachments.`}
-          color="pink"
-          client:load
-        />
-      )
-    }
-
-    {
-      ownersList.length > 0 && shouldRenderSideBarSection('owners') && (
-        <OwnersList
-          title={`Owners (${ownersList.length})`}
-          owners={ownersList}
-          emptyMessage={`This ${type} does not have any documented owners.`}
-          client:load
-        />
-      )
-    }
-
-    {
-      message.data.repository && shouldRenderSideBarSection('repository') && (
-        <RepositoryList repository={message.data.repository?.url} language={message.data.repository?.language} />
-      )
-    }
-
-    {
-      isRSSEnabled && (
-        <div class="mx-auto pb-8 w-full max-w-lg divide-y divide-white/5 rounded-xl bg-white/5">
-          <span class="text-sm text-black font-semibold group-data-[hover]:text-black/80 capitalize">{type} RSS Feed</span>
-          <ul role="list" class="space-y-2 mt-2">
-            <li class="has-tooltip rounded-md text-gray-600 group px-1 w-full hover:bg-gradient-to-l hover:from-purple-500 hover:to-purple-700 hover:text-white hover:font-normal  ">
-              <a class={`flex items-center space-x-2`} target="_blank" href={buildUrl(`/rss/${message.collection}/rss.xml`)}>
-                <RssIcon className="h-4 w-4 text-gray-800 group-hover:text-white" strokeWidth={1} />
-                <span class="font-light text-sm truncate">RSS Feed</span>
-              </a>
-            </li>
-          </ul>
-        </div>
-      )
-    }
-
-    <div class="space-y-2">
-      {
-        message?.data?.schemaPath && (
-          <a
-            href={buildUrl(schemaURL, true)}
-            download={`${message.data.name}(${message.data.version})-${schemaFilePath}`}
-            class="flex items-center justify-center space-x-2 text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <FileDownIcon strokeWidth={2} size={16} />
-            <span>Download {getSchemaFormatFromURL(schemaURL)?.toUpperCase()} schema</span>
-          </a>
-        )
-      }
-      {
-        isVisualiserEnabled() && (
-          <a
-            href={buildUrl(`/visualiser/${message.collection}/${message.data.id}/${message.data.version}`)}
-            class="flex items-center justify-center space-x-2 text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <Workflow strokeWidth={2} size={16} />
-            <span class="block">View in visualiser</span>
-          </a>
-        )
-      }
-      {
-        isChangelogEnabled() && shouldRenderSideBarSection('changelog') && (
-          <a
-            href={buildUrl(`/docs/${message.collection}/${message.data.id}/${message.data.latestVersion}/changelog`)}
-            class="flex items-center space-x-2 justify-center text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <ScrollText strokeWidth={2} size={16} />
-            <span class="block">Read changelog</span>
-          </a>
-        )
-      }
-    </div>
-  </div>
-</aside>
diff --git a/eventcatalog/src/components/SideBars/ServiceSideBar.astro b/eventcatalog/src/components/SideBars/ServiceSideBar.astro
deleted file mode 100644
index 9f9231522..000000000
--- a/eventcatalog/src/components/SideBars/ServiceSideBar.astro
+++ /dev/null
@@ -1,298 +0,0 @@
----
-import OwnersList from '@components/Lists/OwnersList';
-import PillListFlat from '@components/Lists/PillListFlat';
-import RepositoryList from '@components/Lists/RepositoryList.astro';
-import SpecificationsList from '@components/Lists/SpecificationsList.astro';
-import CustomSideBarSectionList from '@components/Lists/CustomSideBarSectionList.astro';
-import VersionList from '@components/Lists/VersionList.astro';
-import { buildUrl } from '@utils/url-builder';
-import { getOwner } from '@utils/collections/owners';
-import type { CollectionEntry } from 'astro:content';
-import { ScrollText, Workflow, FileDownIcon, Code, Link, RssIcon } from 'lucide-react';
-import { join } from 'node:path';
-import config from '@config';
-import { getDomainsForService } from '@utils/collections/domains';
-import { isChangelogEnabled, isVisualiserEnabled } from '@utils/feature';
-interface Props {
-  service: CollectionEntry<'services'>;
-}
-
-const { service } = Astro.props;
-
-// @ts-ignore
-const sends = (service.data.sends as CollectionEntry<'events'>[]) || [];
-// @ts-ignore
-const receives = (service.data.receives as CollectionEntry<'events'>[]) || [];
-
-// @ts-ignore
-const writesTo = (service.data.writesTo as CollectionEntry<'containers'>[]) || [];
-// @ts-ignore
-const readsFrom = (service.data.readsFrom as CollectionEntry<'containers'>[]) || [];
-
-// @ts-ignore
-const entities = (service.data.entities as CollectionEntry<'entities'>[]) || [];
-
-const ownersRaw = service.data?.owners || [];
-const owners = await Promise.all<ReturnType<typeof getOwner>>(ownersRaw.map(getOwner));
-const filteredOwners = owners.filter((o) => o !== undefined);
-
-const resourceGroups = service.data?.resourceGroups || [];
-
-const domainsServiceBelongsTo = await getDomainsForService(service);
-
-const attachments = service.data.attachments || [];
-
-const attachmentsList = attachments.map((a) => {
-  const attachmentIsURL = typeof a === 'string';
-  return {
-    label: attachmentIsURL ? a : (a.title ?? a.url),
-    href: attachmentIsURL ? a : a.url,
-    icon: attachmentIsURL ? 'ExternalLinkIcon' : (a.icon ?? 'ExternalLinkIcon'),
-    target: '_blank' as const,
-    subgroup: attachmentIsURL ? undefined : (a.type ?? ''),
-  };
-});
-
-const sendsList = sends
-  .sort((a, b) => a.collection.localeCompare(b.collection))
-  .map((p) => ({
-    label: p.data.name,
-    badge: p.collection,
-    color: p.collection === 'events' ? 'orange' : 'blue',
-    collection: p.collection,
-    tag: `v${p.data.version}`,
-    href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-  }));
-
-const receivesList = receives
-  .sort((a, b) => a.collection.localeCompare(b.collection))
-  .map((p) => ({
-    label: p.data.name,
-    badge: p.collection,
-    color: p.collection === 'events' ? 'orange' : 'blue',
-    tag: `v${p.data.version}`,
-    collection: p.collection,
-    href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-  }));
-
-const writesToList = writesTo.map((p) => ({
-  label: p.data.name,
-  badge: p.collection,
-  color: p.collection === 'containers' ? 'green' : 'blue',
-  collection: p.collection,
-  tag: `v${p.data.version}`,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-}));
-
-const readsFromList = readsFrom.map((p) => ({
-  label: p.data.name,
-  badge: p.collection,
-  color: p.collection === 'containers' ? 'green' : 'blue',
-  collection: p.collection,
-  tag: `v${p.data.version}`,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-}));
-
-const ownersList = filteredOwners.map((o) => ({
-  label: o.data.name,
-  type: o.collection,
-  badge: o.collection === 'users' ? o.data.role : 'Team',
-  avatarUrl: o.collection === 'users' ? o.data.avatarUrl : '',
-  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
-}));
-
-const domainList = domainsServiceBelongsTo.map((d) => ({
-  label: d.data.name,
-  badge: d.collection,
-  tag: `v${d.data.version}`,
-  collection: d.collection,
-  href: buildUrl(`/docs/${d.collection}/${d.data.id}/${d.data.version}`),
-}));
-
-const entityList = entities.map((p) => ({
-  label: p.data.name,
-  badge: p.collection,
-  tag: `v${p.data.version}`,
-  collection: p.collection,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-}));
-
-const isRSSEnabled = config.rss?.enabled;
-
-// @ts-ignore
-const publicPath = service?.catalog?.publicPath;
-const schemaFilePath = service?.data?.schemaPath;
-const schemaURL = join(publicPath, schemaFilePath || '');
-
-const shouldRenderSideBarSection = (section: string) => {
-  if (!service.data.detailsPanel) {
-    return true;
-  }
-  // @ts-ignore
-  return service.data.detailsPanel[section]?.visible ?? true;
-};
----
-
-<aside class="sticky top-28 left-0 h-full overflow-y-auto pr-6 py-4">
-  <div id="sidebar-cta-portal" class="">
-    {
-      resourceGroups
-        .filter((section) => section.items.length > 0 && section.sidebar)
-        .map((section) => <CustomSideBarSectionList section={section} />)
-    }
-    {
-      domainList.length > 0 && shouldRenderSideBarSection('domains') && (
-        <PillListFlat
-          title={`Domains (${domainList.length})`}
-          pills={domainList}
-          emptyMessage={`This service does not belong to any domains.`}
-          color="orange"
-          client:load
-        />
-      )
-    }
-    {
-      shouldRenderSideBarSection('messages') && (
-        <>
-          <PillListFlat
-            title={`Receives Messages (${receivesList.length})`}
-            pills={receivesList}
-            emptyMessage={`This service does not receive any messages.`}
-            color="orange"
-            client:load
-          />
-          <PillListFlat
-            title={`Sends Messages (${sendsList.length})`}
-            pills={sendsList}
-            emptyMessage={`This service does not send any messages.`}
-            color="orange"
-            client:load
-          />
-        </>
-      )
-    }
-    <>
-      <PillListFlat
-        title={`Writes to (${writesToList.length})`}
-        pills={writesToList}
-        emptyMessage={`This service does not receive any messages.`}
-        color="orange"
-        client:load
-      />
-    </>
-    <>
-      <PillListFlat
-        title={`Reads from (${readsFromList.length})`}
-        pills={readsFromList}
-        emptyMessage={`This service does not read from any containers.`}
-        color="orange"
-        client:load
-      />
-    </>
-    {
-      service.data.versions && shouldRenderSideBarSection('versions') && (
-        <VersionList versions={service.data.versions} collectionItem={service} />
-      )
-    }
-
-    {
-      service.data.attachments && shouldRenderSideBarSection('attachments') && (
-        <PillListFlat
-          title={`Attachments (${attachmentsList.length})`}
-          pills={attachmentsList}
-          emptyMessage={`This service does not have any attachments.`}
-          color="pink"
-          client:load
-        />
-      )
-    }
-
-    {
-      service.data.specifications && shouldRenderSideBarSection('specifications') && (
-        <SpecificationsList collectionItem={service} />
-      )
-    }
-
-    {
-      entities.length > 0 && shouldRenderSideBarSection('entities') && (
-        <PillListFlat
-          title={`Entities (${entities.length})`}
-          pills={entityList}
-          emptyMessage={`This service does not contain any entities.`}
-          color="pink"
-          client:load
-        />
-      )
-    }
-
-    {
-      shouldRenderSideBarSection('owners') && (
-        <OwnersList
-          title={`Owners (${ownersList.length})`}
-          owners={ownersList}
-          emptyMessage={`This service does not have any documented owners.`}
-          client:load
-        />
-      )
-    }
-
-    {
-      service.data.repository && shouldRenderSideBarSection('repository') && (
-        <RepositoryList repository={service.data.repository?.url} language={service.data.repository?.language} />
-      )
-    }
-
-    {
-      isRSSEnabled && (
-        <div class="mx-auto pb-4 w-full max-w-lg divide-y divide-white/5 rounded-xl bg-white/5 border-b border-gray-100 mb-4">
-          <span class="text-sm text-black font-semibold group-data-[hover]:text-black/80 capitalize">Services RSS Feed</span>
-          <ul role="list" class="space-y-2 mt-2">
-            <li class="has-tooltip rounded-md text-gray-600 group px-1 w-full hover:bg-gradient-to-l hover:from-purple-500 hover:to-purple-700 hover:text-white hover:font-normal  ">
-              <a class={`flex items-center space-x-2`} target="_blank" href={buildUrl(`/rss/services/rss.xml`)}>
-                <RssIcon className="h-4 w-4 text-gray-800 group-hover:text-white" strokeWidth={1} />
-                <span class="font-light text-sm truncate">RSS</span>
-              </a>
-            </li>
-          </ul>
-        </div>
-      )
-    }
-
-    <div class="space-y-2">
-      {
-        service?.data?.schemaPath && (
-          <a
-            href={buildUrl(schemaURL, true)}
-            download={`${service.data.name}(${service.data.version})-${schemaFilePath}`}
-            class="flex items-center justify-center space-x-2 text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <FileDownIcon strokeWidth={2} size={16} />
-            <span>Download schema</span>
-          </a>
-        )
-      }
-      {
-        isVisualiserEnabled() && (
-          <a
-            href={buildUrl(`/visualiser/${service.collection}/${service.data.id}/${service.data.version}`)}
-            class="flex items-center justify-center space-x-2 text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <Workflow strokeWidth={2} size={16} />
-            <span class="block">View in visualiser</span>
-          </a>
-        )
-      }
-      {
-        isChangelogEnabled() && shouldRenderSideBarSection('changelog') && (
-          <a
-            href={buildUrl(`/docs/${service.collection}/${service.data.id}/${service.data.latestVersion}/changelog`)}
-            class="flex items-center space-x-2 justify-center text-center rounded-md w-full bg-white px-3.5 py-2.5 text-sm font-semibold text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-100/60 hover:text-primary"
-          >
-            <ScrollText strokeWidth={2} size={16} />
-            <span class="block">Read changelog</span>
-          </a>
-        )
-      }
-    </div>
-  </div>
-</aside>
diff --git a/eventcatalog/src/components/SideNav/ListViewSideBar/components/CollapsibleGroup.tsx b/eventcatalog/src/components/SideNav/ListViewSideBar/components/CollapsibleGroup.tsx
deleted file mode 100644
index a661bb9a2..000000000
--- a/eventcatalog/src/components/SideNav/ListViewSideBar/components/CollapsibleGroup.tsx
+++ /dev/null
@@ -1,46 +0,0 @@
-import React from 'react';
-import { ChevronDownIcon } from '@heroicons/react/24/outline';
-
-interface CollapsibleGroupProps {
-  isCollapsed: boolean;
-  onToggle: () => void;
-  title: React.ReactNode;
-  children: React.ReactNode;
-  className?: string;
-}
-
-const CollapsibleGroup: React.FC<CollapsibleGroupProps> = ({ isCollapsed, onToggle, title, children, className = '' }) => (
-  <div className={className}>
-    <div className="flex items-center">
-      <button
-        onClick={(e) => {
-          e.stopPropagation();
-          onToggle();
-        }}
-        className="p-1 hover:bg-gray-100 rounded-md"
-      >
-        <div className={`transition-transform duration-150 ${isCollapsed ? '' : 'rotate-180'}`}>
-          <ChevronDownIcon className="h-3 w-3 text-gray-500" />
-        </div>
-      </button>
-      {typeof title === 'string' ? (
-        <button
-          onClick={(e) => {
-            e.stopPropagation();
-            onToggle();
-          }}
-          className="flex-grow flex items-center justify-between px-2 py-0.5 text-xs font-bold rounded-md"
-        >
-          {title}
-        </button>
-      ) : (
-        title
-      )}
-    </div>
-    <div className={`overflow-hidden transition-[height] duration-150 ease-out ${isCollapsed ? 'h-0' : 'h-auto'}`}>
-      {children}
-    </div>
-  </div>
-);
-
-export default CollapsibleGroup;
diff --git a/eventcatalog/src/components/SideNav/ListViewSideBar/components/MessageList.tsx b/eventcatalog/src/components/SideNav/ListViewSideBar/components/MessageList.tsx
deleted file mode 100644
index 3c955b29e..000000000
--- a/eventcatalog/src/components/SideNav/ListViewSideBar/components/MessageList.tsx
+++ /dev/null
@@ -1,78 +0,0 @@
-import React from 'react';
-import { getMessageColorByCollection, getMessageCollectionName } from '../index';
-
-interface MessageListProps {
-  messages: any[];
-  decodedCurrentPath: string;
-  searchTerm?: string;
-}
-
-const HighlightedText = React.memo(({ text, searchTerm }: { text: string; searchTerm?: string }) => {
-  if (!searchTerm) return <>{text}</>;
-
-  const regex = new RegExp(`(${searchTerm})`, 'gi');
-  const parts = text.split(regex);
-
-  return (
-    <>
-      {parts.map((part, index) =>
-        regex.test(part) ? (
-          <span key={index} className="bg-yellow-200 text-gray-900 font-semibold">
-            {part}
-          </span>
-        ) : (
-          <span key={index}>{part}</span>
-        )
-      )}
-    </>
-  );
-});
-
-const getMessageColorByLabelOrCollection = (collection: string, badge?: string) => {
-  if (!badge) {
-    return getMessageColorByCollection(collection);
-  }
-
-  // Will try and match the label against HTTP verbs
-  const httpVerbs = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT'];
-  if (badge && httpVerbs.includes(badge.toUpperCase())) {
-    if (badge.toUpperCase() === 'GET') return 'bg-blue-50 text-blue-600';
-    if (badge.toUpperCase() === 'POST') return 'bg-green-50 text-green-600';
-    if (badge.toUpperCase() === 'PUT') return 'bg-yellow-50 text-yellow-600';
-    if (badge.toUpperCase() === 'DELETE') return 'bg-red-50 text-red-600';
-    if (badge.toUpperCase() === 'PATCH') return 'bg-purple-50 text-purple-600';
-    if (badge.toUpperCase() === 'HEAD') return 'bg-gray-50 text-gray-600';
-    if (badge.toUpperCase() === 'OPTIONS') return 'bg-orange-50 text-orange-600';
-  }
-
-  return getMessageColorByCollection(collection);
-};
-
-const MessageList: React.FC<MessageListProps> = ({ messages, decodedCurrentPath, searchTerm }) => (
-  <ul className="space-y-0.5 border-l border-gray-200/80 ml-[9px] pl-4">
-    {messages.map((message: any) => (
-      <li key={message.id} data-active={decodedCurrentPath === message.href}>
-        <a
-          href={message.href}
-          data-active={decodedCurrentPath === message.href}
-          className={`flex items-center justify-between px-2 py-1.5 text-xs text-gray-600 hover:bg-purple-100 rounded-md ${
-            decodedCurrentPath.includes(message.href) ? 'bg-purple-100 ' : 'hover:bg-purple-100'
-          }`}
-          title={message.data?.sidebar?.label || message.data.name}
-        >
-          <span className="truncate">
-            <HighlightedText text={message.data?.sidebar?.label || message.data.name} searchTerm={searchTerm} />
-            <span className="text-xs text-gray-400">{message.data.draft ? ' (DRAFT)' : ''}</span>
-          </span>
-          <span
-            className={`ml-2 text-[10px]  flex items-center gap-1 font-medium px-2 uppercase py-0.5 rounded ${getMessageColorByLabelOrCollection(message.collection, message.data?.sidebar?.badge)} ${message.data?.sidebar?.backgroundColor}`}
-          >
-            {message.data?.sidebar?.badge || getMessageCollectionName(message.collection, message)}
-          </span>
-        </a>
-      </li>
-    ))}
-  </ul>
-);
-
-export default MessageList;
diff --git a/eventcatalog/src/components/SideNav/ListViewSideBar/components/SpecificationList.tsx b/eventcatalog/src/components/SideNav/ListViewSideBar/components/SpecificationList.tsx
deleted file mode 100644
index fd51c0908..000000000
--- a/eventcatalog/src/components/SideNav/ListViewSideBar/components/SpecificationList.tsx
+++ /dev/null
@@ -1,83 +0,0 @@
-import React from 'react';
-import { buildUrl } from '@utils/url-builder';
-import type { ServiceItem } from '../types';
-
-interface SpecificationListProps {
-  specifications: {
-    type: string;
-    path: string;
-    name?: string;
-    filename?: string;
-    filenameWithoutExtension?: string;
-  }[];
-  id: string;
-  version: string;
-}
-
-const SpecificationList: React.FC<SpecificationListProps> = ({ specifications, id, version }) => {
-  const asyncAPISpecifications = specifications.filter((spec) => spec.type === 'asyncapi');
-  const openAPISpecifications = specifications.filter((spec) => spec.type === 'openapi');
-  const graphQLSpecifications = specifications.filter((spec) => spec.type === 'graphql');
-
-  return (
-    <ul className="space-y-0.5 border-l border-gray-200/80 ml-[9px] pl-4">
-      {asyncAPISpecifications &&
-        asyncAPISpecifications.length > 0 &&
-        asyncAPISpecifications.map((spec) => (
-          <a
-            key={`${spec.name}-asyncapi`}
-            href={buildUrl(`/docs/services/${id}/${version}/asyncapi/${spec.filenameWithoutExtension}`)}
-            data-active={window.location.href.includes(`docs/services/${id}/${version}/asyncapi`)}
-            className={`flex items-center px-2 py-1.5 text-xs text-gray-600 hover:bg-purple-100 rounded-md justify-between ${
-              window.location.href.includes(`docs/services/${id}/${version}/asyncapi`) ? 'bg-purple-100' : 'hover:bg-purple-100'
-            }`}
-          >
-            <span className="truncate flex items-center gap-1">{spec.name}</span>
-            <span className="text-purple-600 ml-2 text-[10px] uppercase font-medium bg-gray-50 px-4 py-0.5 rounded">
-              <img src={buildUrl('/icons/asyncapi.svg', true)} className="w-4 h-4" alt="AsyncAPI" />
-            </span>
-          </a>
-        ))}
-      {openAPISpecifications &&
-        openAPISpecifications.length > 0 &&
-        openAPISpecifications.map((spec) => (
-          <a
-            key={`${spec.name}-openapi`}
-            href={buildUrl(`/docs/services/${id}/${version}/spec/${spec.filenameWithoutExtension}`)}
-            data-active={window.location.href.includes(`docs/services/${id}/${version}/spec/${spec.filenameWithoutExtension}`)}
-            className={`items-center px-2 py-1.5 text-xs text-gray-600 hover:bg-purple-100 rounded-md flex justify-between ${
-              window.location.href.includes(`docs/services/${id}/${version}/spec/${spec.filenameWithoutExtension}`)
-                ? 'bg-purple-100'
-                : 'hover:bg-purple-100'
-            }`}
-          >
-            <span className="truncate flex items-center gap-1">{spec.name}</span>
-            <span className="text-green-600 ml-2 text-[10px] uppercase font-medium bg-gray-50 px-4 py-0.5 rounded">
-              <img src={buildUrl('/icons/openapi.svg', true)} className="w-4 h-4" alt="OpenAPI" />
-            </span>
-          </a>
-        ))}
-      {graphQLSpecifications &&
-        graphQLSpecifications.length > 0 &&
-        graphQLSpecifications.map((spec) => (
-          <a
-            key={`${spec.name}-openapi`}
-            href={buildUrl(`/docs/services/${id}/${version}/graphql/${spec.filenameWithoutExtension}`)}
-            data-active={window.location.href.includes(`docs/services/${id}/${version}/graphql/${spec.filenameWithoutExtension}`)}
-            className={`items-center px-2 py-1.5 text-xs text-gray-600 hover:bg-purple-100 rounded-md flex justify-between ${
-              window.location.href.includes(`docs/services/${id}/${version}/graphql/${spec.filenameWithoutExtension}`)
-                ? 'bg-purple-100'
-                : 'hover:bg-purple-100'
-            }`}
-          >
-            <span className="truncate flex items-center gap-1">{spec.name}</span>
-            <span className="text-green-600 ml-2 text-[10px] uppercase font-medium bg-gray-50 px-4 py-0.5 rounded">
-              <img src={buildUrl('/icons/graphql.svg', true)} className="w-4 h-4" alt="GraphQL" />
-            </span>
-          </a>
-        ))}
-    </ul>
-  );
-};
-
-export default SpecificationList;
diff --git a/eventcatalog/src/components/SideNav/ListViewSideBar/index.tsx b/eventcatalog/src/components/SideNav/ListViewSideBar/index.tsx
deleted file mode 100644
index 797860f42..000000000
--- a/eventcatalog/src/components/SideNav/ListViewSideBar/index.tsx
+++ /dev/null
@@ -1,1250 +0,0 @@
-import React, { useState, useEffect, useRef, useMemo, useCallback } from 'react';
-import { ChevronDownIcon, ChevronDoubleDownIcon, ChevronDoubleUpIcon, XMarkIcon } from '@heroicons/react/24/outline';
-import { buildUrl, buildUrlWithParams } from '@utils/url-builder';
-import CollapsibleGroup from './components/CollapsibleGroup';
-import MessageList from './components/MessageList';
-import SpecificationsList from './components/SpecificationList';
-import type { MessageItem, ServiceItem, ListViewSideBarProps, DomainItem, FlowItem, Resources } from './types';
-import { PanelLeft } from 'lucide-react';
-const STORAGE_KEY = 'EventCatalog:catalogSidebarCollapsedGroups';
-const DEBOUNCE_DELAY = 300; // 300ms debounce delay
-
-const HighlightedText = React.memo(({ text, searchTerm }: { text: string; searchTerm: string }) => {
-  if (!searchTerm) return <>{text}</>;
-
-  const regex = new RegExp(`(${searchTerm})`, 'gi');
-  const parts = text.split(regex);
-
-  return (
-    <>
-      {parts.map((part, index) =>
-        regex.test(part) ? (
-          <span key={index} className="bg-yellow-200 text-gray-900 font-semibold">
-            {part}
-          </span>
-        ) : (
-          <span key={index}>{part}</span>
-        )
-      )}
-    </>
-  );
-});
-
-export const getMessageColorByCollection = (collection: string) => {
-  if (collection === 'commands') return 'bg-blue-50 text-blue-600';
-  if (collection === 'queries') return 'bg-green-50 text-green-600';
-  if (collection === 'events') return 'bg-orange-50 text-orange-600';
-  if (collection === 'entities') return 'bg-purple-50 text-purple-600';
-  return 'text-gray-600';
-};
-
-export const getMessageCollectionName = (collection: string, item: any) => {
-  if (collection === 'commands') return 'Command';
-  if (collection === 'queries') return 'Query';
-  if (collection === 'events') return 'Event';
-  if (collection === 'entities' && item.data.aggregateRoot) return 'Entity (Root)';
-  if (collection === 'entities') return 'Entity';
-  return collection.slice(0, collection.length - 1).toUpperCase();
-};
-
-const NoResultsFound = React.memo(({ searchTerm }: { searchTerm: string }) => (
-  <div className="px-4 py-6 text-center">
-    <div className="text-gray-400 text-sm mb-2">No results found for "{searchTerm}"</div>
-    <div className="text-gray-400 text-xs">
-      Try:
-      <ul className="mt-2 space-y-1 text-left list-disc pl-4">
-        <li>Checking for typos</li>
-        <li>Using fewer keywords</li>
-        <li>Using more general terms</li>
-      </ul>
-    </div>
-  </div>
-));
-
-const ServiceItem = React.memo(
-  ({
-    item,
-    decodedCurrentPath,
-    collapsedGroups,
-    toggleGroupCollapse,
-    isVisualizer,
-    searchTerm,
-  }: {
-    item: ServiceItem;
-    decodedCurrentPath: string;
-    collapsedGroups: { [key: string]: boolean };
-    toggleGroupCollapse: (group: string) => void;
-    isVisualizer: boolean;
-    searchTerm: string;
-  }) => {
-    const readsAndWritesTo = item.writesTo.filter((writeTo) => item.readsFrom.some((readFrom) => readFrom.id === writeTo.id));
-    const resourceReads = item.readsFrom.filter((readFrom) => !readsAndWritesTo.some((writeTo) => writeTo.id === readFrom.id));
-    const resourceWrites = item.writesTo.filter((writeTo) => !readsAndWritesTo.some((readFrom) => readFrom.id === writeTo.id));
-    const hasData = item.writesTo.length > 0 || item.readsFrom.length > 0;
-
-    const sendsMessages = item.sends && item.sends.length > 0;
-    const receivesMessages = item.receives && item.receives.length > 0;
-
-    return (
-      <CollapsibleGroup
-        isCollapsed={collapsedGroups[item.href]}
-        onToggle={() => toggleGroupCollapse(item.href)}
-        title={
-          <button
-            onClick={(e) => {
-              e.stopPropagation();
-              toggleGroupCollapse(item.href);
-            }}
-            className="flex justify-between items-center pl-2 w-full text-xs"
-            title={item.label}
-          >
-            <span className="truncate text-xs font-bold">
-              <HighlightedText text={item.label} searchTerm={searchTerm} />
-              <span className="text-xs text-gray-400">{item.draft ? ' (DRAFT)' : ''}</span>
-            </span>
-            <span
-              style={{
-                color: item.sidebar?.color || '#9333ea',
-                backgroundColor: item.sidebar?.backgroundColor || '#faf5ff',
-              }}
-              className="ml-2 rounded bg-purple-50 px-2 py-0.5 text-[10px] font-medium text-purple-600"
-            >
-              {item.sidebar?.badge ? item.sidebar.badge?.toUpperCase() : 'SERVICE'}
-            </span>
-          </button>
-        }
-      >
-        <div className="space-y-0.5 border-gray-200/80 border-l pl-3 ml-[9px] mt-1">
-          <a
-            href={`${item.href}`}
-            data-active={decodedCurrentPath === item.href}
-            className={`flex items-center px-2 py-1.5 text-xs text-gray-600 hover:bg-purple-100 rounded-md ${
-              decodedCurrentPath === item.href ? 'bg-purple-100' : 'hover:bg-purple-100'
-            }`}
-          >
-            <span className="truncate">Overview</span>
-          </a>
-          {isVisualizer && hasData && (
-            <a
-              href={buildUrl(`/${item.href}/data`)}
-              data-active={decodedCurrentPath === `${item.href}/data`}
-              className={`flex items-center px-2 py-1.5 text-xs text-gray-600 hover:bg-purple-100 rounded-md ${
-                decodedCurrentPath === `${item.href}/data` ? 'bg-purple-100 ' : 'hover:bg-purple-100'
-              }`}
-            >
-              <span className="truncate">Data Diagram</span>
-            </a>
-          )}
-          {!isVisualizer && (
-            <a
-              href={buildUrlWithParams('/architecture/docs/messages', {
-                serviceName: item.name,
-                serviceId: item.id,
-              })}
-              data-active={window.location.href.includes(`serviceId=${item.id}`)}
-              className={`flex items-center px-2 py-1.5 text-xs text-gray-600 hover:bg-purple-100 rounded-md ${
-                window.location.href.includes(`serviceId=${item.id}`) ? 'bg-purple-100' : 'hover:bg-purple-100'
-              }`}
-            >
-              <span className="truncate flex items-center gap-1">Architecture</span>
-            </a>
-          )}
-
-          {!isVisualizer && item.specifications && item.specifications.length > 0 && (
-            <CollapsibleGroup
-              isCollapsed={collapsedGroups[`${item.href}-specifications`]}
-              onToggle={() => toggleGroupCollapse(`${item.href}-specifications`)}
-              title={
-                <button
-                  onClick={(e) => {
-                    e.stopPropagation();
-                    toggleGroupCollapse(`${item.href}-specifications`);
-                  }}
-                  className="truncate underline ml-2 text-xs mb-1 py-1"
-                >
-                  Specifications ({item.specifications?.length})
-                </button>
-              }
-            >
-              <SpecificationsList specifications={item.specifications} id={item.id} version={item.version} />
-            </CollapsibleGroup>
-          )}
-
-          {receivesMessages && (
-            <CollapsibleGroup
-              isCollapsed={collapsedGroups[`${item.href}-receives`]}
-              onToggle={() => toggleGroupCollapse(`${item.href}-receives`)}
-              title={
-                <button
-                  onClick={(e) => {
-                    e.stopPropagation();
-                    toggleGroupCollapse(`${item.href}-receives`);
-                  }}
-                  className="truncate underline ml-2 text-xs mb-1 py-1"
-                >
-                  Receives messages ({item.receives.length})
-                </button>
-              }
-            >
-              <MessageList messages={item.receives} decodedCurrentPath={decodedCurrentPath} searchTerm={searchTerm} />
-            </CollapsibleGroup>
-          )}
-          {sendsMessages && (
-            <CollapsibleGroup
-              isCollapsed={collapsedGroups[`${item.href}-sends`]}
-              onToggle={() => toggleGroupCollapse(`${item.href}-sends`)}
-              title={
-                <button
-                  onClick={(e) => {
-                    e.stopPropagation();
-                    toggleGroupCollapse(`${item.href}-sends`);
-                  }}
-                  className="truncate underline ml-2 text-xs mb-1 py-1"
-                >
-                  Sends messages ({item.sends.length})
-                </button>
-              }
-            >
-              <MessageList messages={item.sends} decodedCurrentPath={decodedCurrentPath} searchTerm={searchTerm} />
-            </CollapsibleGroup>
-          )}
-          {!isVisualizer && hasData && (
-            <CollapsibleGroup
-              isCollapsed={collapsedGroups[`${item.href}-data`]}
-              onToggle={() => toggleGroupCollapse(`${item.href}-data`)}
-              title={
-                <button
-                  onClick={(e) => {
-                    e.stopPropagation();
-                    toggleGroupCollapse(`${item.href}-data`);
-                  }}
-                  className="truncate underline ml-2 text-xs mb-1 py-1"
-                >
-                  Data Stores ({readsAndWritesTo.length + resourceWrites.length + resourceReads.length})
-                </button>
-              }
-            >
-              {readsAndWritesTo.length > 0 && (
-                <CollapsibleGroup
-                  className="ml-4"
-                  isCollapsed={collapsedGroups[`${item.href}-writesTo-data`]}
-                  onToggle={() => toggleGroupCollapse(`${item.href}-writesTo-data`)}
-                  title={
-                    <button
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        toggleGroupCollapse(`${item.href}-writesTo-data`);
-                      }}
-                      className="truncate underline ml-2 text-xs mb-1 py-1"
-                    >
-                      Reads and writes to
-                    </button>
-                  }
-                >
-                  <MessageList messages={readsAndWritesTo} decodedCurrentPath={decodedCurrentPath} searchTerm={searchTerm} />
-                </CollapsibleGroup>
-              )}
-              {resourceWrites.length > 0 && (
-                <CollapsibleGroup
-                  className="ml-4"
-                  isCollapsed={collapsedGroups[`${item.href}-writesTo-data`]}
-                  onToggle={() => toggleGroupCollapse(`${item.href}-writesTo-data`)}
-                  title={
-                    <button
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        toggleGroupCollapse(`${item.href}-writesTo-data`);
-                      }}
-                      className="truncate underline ml-2 text-xs mb-1 py-1"
-                    >
-                      Writes to
-                    </button>
-                  }
-                >
-                  <MessageList messages={resourceWrites} decodedCurrentPath={decodedCurrentPath} searchTerm={searchTerm} />
-                </CollapsibleGroup>
-              )}
-              {resourceReads.length > 0 && (
-                <CollapsibleGroup
-                  className="ml-4"
-                  isCollapsed={collapsedGroups[`${item.href}-readsFrom-data`]}
-                  onToggle={() => toggleGroupCollapse(`${item.href}-readsFrom-data`)}
-                  title={
-                    <button
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        toggleGroupCollapse(`${item.href}-readsFrom-data`);
-                      }}
-                      className="truncate underline ml-2 text-xs mb-1 py-1"
-                    >
-                      Reads From
-                    </button>
-                  }
-                >
-                  <MessageList messages={resourceReads} decodedCurrentPath={decodedCurrentPath} searchTerm={searchTerm} />
-                </CollapsibleGroup>
-              )}
-            </CollapsibleGroup>
-          )}
-          {!isVisualizer && item.entities.length > 0 && (
-            <CollapsibleGroup
-              isCollapsed={collapsedGroups[`${item.href}-entities`]}
-              onToggle={() => toggleGroupCollapse(`${item.href}-entities`)}
-              title={
-                <button
-                  onClick={(e) => {
-                    e.stopPropagation();
-                    toggleGroupCollapse(`${item.href}-entities`);
-                  }}
-                  className="truncate underline ml-2 text-xs mb-1 py-1"
-                >
-                  Entities ({item.entities.length})
-                </button>
-              }
-            >
-              <MessageList messages={item.entities} decodedCurrentPath={decodedCurrentPath} searchTerm={searchTerm} />
-            </CollapsibleGroup>
-          )}
-        </div>
-      </CollapsibleGroup>
-    );
-  }
-);
-
-const ListViewSideBar: React.FC<ListViewSideBarProps> = ({ resources, currentPath, showOrphanedMessages }) => {
-  const navRef = useRef<HTMLElement>(null);
-  const [data] = useState(resources);
-  const [searchTerm, setSearchTerm] = useState('');
-  const [debouncedSearchTerm, setDebouncedSearchTerm] = useState('');
-  const [isInitialized, setIsInitialized] = useState(false);
-  const [isExpanded, setIsExpanded] = useState(true);
-  const [isSearchPinned, setIsSearchPinned] = useState(false);
-  const [lastScrollTop, setLastScrollTop] = useState(0);
-  const [collapsedGroups, setCollapsedGroups] = useState<{ [key: string]: boolean }>(() => {
-    if (typeof window !== 'undefined') {
-      const saved = window.localStorage.getItem(STORAGE_KEY);
-      const savedState = saved ? JSON.parse(saved) : {};
-      const currentPath = window.location.pathname;
-
-      // Default all sections to collapsed
-      const defaultCollapsedState: { [key: string]: boolean } = {
-        'all-services-group': true,
-        'flows-group': true,
-        'data-group': true,
-        'designs-group': true,
-        'messagesNotInService-group': true,
-      };
-
-      // Default all domains, services, and their subsections to collapsed
-      resources.domains?.forEach((domain: any) => {
-        const isDomainActive = currentPath.includes(domain.href);
-        defaultCollapsedState[domain.href] = !isDomainActive;
-        defaultCollapsedState[`${domain.href}-entities`] = true;
-        defaultCollapsedState[`${domain.href}-subdomains`] = true;
-        defaultCollapsedState[`${domain.href}-services`] = true;
-      });
-
-      resources.services?.forEach((service: any) => {
-        const isServiceActive = currentPath.includes(service.href);
-        defaultCollapsedState[service.href] = !isServiceActive;
-        defaultCollapsedState[`${service.href}-specifications`] = true;
-        defaultCollapsedState[`${service.href}-receives`] = true;
-        defaultCollapsedState[`${service.href}-sends`] = true;
-        defaultCollapsedState[`${service.href}-entities`] = true;
-        defaultCollapsedState[`${service.href}-data`] = true;
-        defaultCollapsedState[`${service.href}-writesTo-data`] = true;
-        defaultCollapsedState[`${service.href}-readsFrom-data`] = true;
-      });
-
-      setIsInitialized(true);
-      return { ...defaultCollapsedState, ...savedState };
-    }
-    return {};
-  });
-
-  const decodedCurrentPath = window.location.pathname;
-  const isVisualizer = window.location.pathname.includes('/visualiser/');
-
-  useEffect(() => {
-    const timer = setTimeout(() => {
-      setDebouncedSearchTerm(searchTerm.toLowerCase());
-    }, DEBOUNCE_DELAY);
-
-    return () => clearTimeout(timer);
-  }, [searchTerm]);
-
-  // Filter data based on search term
-  const filteredData: Resources = useMemo(() => {
-    if (!debouncedSearchTerm) return data;
-
-    const filterItem = (item: { label: string; id?: string }) => {
-      return (
-        item.label.toLowerCase().includes(debouncedSearchTerm) || (item.id && item.id.toLowerCase().includes(debouncedSearchTerm))
-      );
-    };
-
-    const filterMessages = (messages: MessageItem[]) => {
-      return messages.filter(
-        (message) =>
-          message.data.name.toLowerCase().includes(debouncedSearchTerm) || message.id.toLowerCase().includes(debouncedSearchTerm)
-      );
-    };
-
-    // Enhanced domain filtering that considers parent-subdomain relationships
-    const filterDomains = (domains: any[]) => {
-      const filteredDomains: any[] = [];
-
-      domains.forEach((domain: any) => {
-        const domainMatches = filterItem(domain);
-
-        // Check if this domain is a subdomain of another domain
-        const isSubdomain = domains.some((parentDomain: any) => {
-          const subdomains = parentDomain.domains || [];
-          return subdomains.some((subdomain: any) => subdomain.data.id === domain.id);
-        });
-
-        // If this is a parent domain, check if any of its subdomains match
-        let hasMatchingSubdomains = false;
-        if (!isSubdomain) {
-          const subdomains = domain.domains || [];
-          hasMatchingSubdomains = domains.some((potentialSubdomain: any) =>
-            subdomains.some((subdomain: any) => subdomain.data.id === potentialSubdomain.id && filterItem(potentialSubdomain))
-          );
-        }
-
-        // Include domain if:
-        // 1. The domain itself matches the search
-        // 2. It's a parent domain and has matching subdomains
-        // 3. It's a subdomain and matches the search
-        if (domainMatches || hasMatchingSubdomains || (isSubdomain && domainMatches)) {
-          filteredDomains.push(domain);
-        }
-
-        // If this is a subdomain that matches, also include its parent domain
-        if (isSubdomain && domainMatches) {
-          const parentDomain = domains.find((parentDomain: any) => {
-            const subdomains = parentDomain.domains || [];
-            return subdomains.some((subdomain: any) => subdomain.data.id === domain.id);
-          });
-
-          if (parentDomain && !filteredDomains.some((d: any) => d.id === parentDomain.id)) {
-            filteredDomains.push(parentDomain);
-          }
-        }
-      });
-
-      return filteredDomains;
-    };
-
-    return {
-      'context-map': data['context-map']?.filter(filterItem) || [],
-      domains: data.domains ? filterDomains(data.domains) : [],
-      services:
-        data.services
-          ?.map((service: ServiceItem) => ({
-            ...service,
-            sends: filterMessages(service.sends),
-            receives: filterMessages(service.receives),
-            isVisible:
-              filterItem(service) ||
-              service.sends.some(
-                (msg: MessageItem) =>
-                  msg.data.name.toLowerCase().includes(debouncedSearchTerm) || msg.id.toLowerCase().includes(debouncedSearchTerm)
-              ) ||
-              service.receives.some(
-                (msg: MessageItem) =>
-                  msg.data.name.toLowerCase().includes(debouncedSearchTerm) || msg.id.toLowerCase().includes(debouncedSearchTerm)
-              ),
-          }))
-          .filter((service: ServiceItem & { isVisible: boolean }) => service.isVisible) || [],
-      flows: data.flows?.filter(filterItem) || [],
-      designs: data.designs?.filter(filterItem) || [],
-      messagesNotInService:
-        data.messagesNotInService?.filter(
-          (msg: MessageItem) =>
-            msg.label.toLowerCase().includes(debouncedSearchTerm) || msg.id.toLowerCase().includes(debouncedSearchTerm)
-        ) || [],
-    };
-  }, [data, debouncedSearchTerm]);
-
-  // Auto-expand groups when searching
-  useEffect(() => {
-    if (debouncedSearchTerm) {
-      // Expand all groups when searching
-      const newCollapsedState = { ...collapsedGroups };
-      Object.keys(newCollapsedState).forEach((key) => {
-        newCollapsedState[key] = false;
-      });
-      setCollapsedGroups(newCollapsedState);
-    }
-  }, [debouncedSearchTerm]);
-
-  // Handle scroll for sticky search bar
-  useEffect(() => {
-    const nav = navRef.current;
-    if (!nav) return;
-
-    const handleScroll = () => {
-      const scrollTop = nav.scrollTop;
-      const scrollThreshold = 50; // Pin after scrolling 50px
-
-      // Scrolling down past threshold
-      if (scrollTop > scrollThreshold && scrollTop > lastScrollTop) {
-        setIsSearchPinned(true);
-      }
-      // Scrolling up near the top
-      else if (scrollTop <= scrollThreshold) {
-        setIsSearchPinned(false);
-      }
-
-      setLastScrollTop(scrollTop);
-    };
-
-    nav.addEventListener('scroll', handleScroll);
-    return () => nav.removeEventListener('scroll', handleScroll);
-  }, [lastScrollTop]);
-
-  // Store collapsed groups in local storage
-  useEffect(() => {
-    if (typeof window !== 'undefined') {
-      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(collapsedGroups));
-    }
-  }, [collapsedGroups]);
-
-  // If we find a data-active element, scroll to it on mount and open its section
-  useEffect(() => {
-    const activeElement = document.querySelector('[data-active="true"]');
-    if (activeElement) {
-      // Add y offset to the scroll position
-      activeElement.scrollIntoView({ behavior: 'instant', block: 'center' });
-
-      // Check which section the active element belongs to and open it
-      const newCollapsedState = { ...collapsedGroups };
-
-      // Check if active page is in a domain
-      data.domains?.forEach((domain: any) => {
-        if (decodedCurrentPath.includes(domain.href)) {
-          newCollapsedState[domain.href] = false;
-
-          // Check if it's in domain entities
-          const isInDomainEntities = domain.entities?.some((entity: any) => decodedCurrentPath.includes(entity.href));
-          if (isInDomainEntities) {
-            newCollapsedState[`${domain.href}-entities`] = false;
-          }
-
-          // Check if it's in domain services
-          const isInDomainServices = domain.services?.some((service: any) => decodedCurrentPath.includes(service.data.id));
-          if (isInDomainServices) {
-            newCollapsedState[`${domain.href}-services`] = false;
-          }
-
-          // Check if it's in a subdomain
-          const subdomains = domain.domains || [];
-          subdomains.forEach((subdomain: any) => {
-            const actualSubdomain = data.domains?.find((d: any) => d.id === subdomain.data.id);
-            if (actualSubdomain && decodedCurrentPath.includes(actualSubdomain.href)) {
-              newCollapsedState[`${domain.href}-subdomains`] = false;
-              newCollapsedState[actualSubdomain.href] = false;
-
-              // Check subdomain entities
-              const isInSubdomainEntities = actualSubdomain.entities?.some((entity: any) =>
-                decodedCurrentPath.includes(entity.href)
-              );
-              if (isInSubdomainEntities) {
-                newCollapsedState[`${actualSubdomain.href}-entities`] = false;
-              }
-
-              // Check subdomain services
-              const isInSubdomainServices = actualSubdomain.services?.some((service: any) =>
-                decodedCurrentPath.includes(service.data.id)
-              );
-              if (isInSubdomainServices) {
-                newCollapsedState[`${actualSubdomain.href}-services`] = false;
-              }
-            }
-          });
-        }
-      });
-
-      // Check if active page is a service
-      data.services?.forEach((service: ServiceItem) => {
-        if (decodedCurrentPath.includes(service.href)) {
-          newCollapsedState['all-services-group'] = false;
-          newCollapsedState[service.href] = false;
-
-          // Open specific service sections if active
-          if (decodedCurrentPath.includes('/data')) {
-            newCollapsedState[`${service.href}-data`] = false;
-          }
-        }
-      });
-
-      // Check if active page is a flow
-      const isFlow = data.flows?.some((flow: FlowItem) => decodedCurrentPath === flow.href);
-      if (isFlow) {
-        newCollapsedState['flows-group'] = false;
-      }
-
-      // Check if active page is a container/data store
-      const isContainer = data.containers?.some((container: any) => decodedCurrentPath === container.href);
-      if (isContainer) {
-        newCollapsedState['data-group'] = false;
-      }
-
-      // Check if active page is a design
-      const isDesign = data.designs?.some((design: any) => decodedCurrentPath === design.href);
-      if (isDesign) {
-        newCollapsedState['designs-group'] = false;
-      }
-
-      // Check if active page is an orphaned message
-      const isOrphanedMessage = data.messagesNotInService?.some((msg: MessageItem) => decodedCurrentPath === msg.href);
-      if (isOrphanedMessage) {
-        newCollapsedState['messagesNotInService-group'] = false;
-      }
-
-      setCollapsedGroups(newCollapsedState);
-    }
-  }, []);
-
-  const toggleGroupCollapse = useCallback((group: string) => {
-    setCollapsedGroups((prev) => ({
-      ...prev,
-      [group]: !prev[group],
-    }));
-  }, []);
-
-  const handleSearchChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
-    setSearchTerm(e.target.value);
-  }, []);
-
-  const collapseAll = useCallback(() => {
-    const newCollapsedState: { [key: string]: boolean } = {};
-
-    // Collapse all domains
-    filteredData.domains?.forEach((domain: any) => {
-      newCollapsedState[domain.href] = true;
-      newCollapsedState[`${domain.href}-entities`] = true;
-      newCollapsedState[`${domain.href}-subdomains`] = true;
-      newCollapsedState[`${domain.href}-services`] = true;
-    });
-
-    // Collapse all services
-    filteredData.services?.forEach((service: any) => {
-      newCollapsedState[service.href] = true;
-      newCollapsedState[`${service.href}-specifications`] = true;
-      newCollapsedState[`${service.href}-receives`] = true;
-      newCollapsedState[`${service.href}-sends`] = true;
-      newCollapsedState[`${service.href}-entities`] = true;
-    });
-
-    setCollapsedGroups(newCollapsedState);
-    setIsExpanded(false);
-  }, [filteredData]);
-
-  const expandAll = useCallback(() => {
-    const newCollapsedState: { [key: string]: boolean } = {};
-
-    // Expand all domains
-    filteredData.domains?.forEach((domain: any) => {
-      newCollapsedState[domain.href] = false;
-      newCollapsedState[`${domain.href}-entities`] = false;
-      newCollapsedState[`${domain.href}-subdomains`] = false;
-      newCollapsedState[`${domain.href}-services`] = false;
-    });
-
-    // Expand all services
-    filteredData.services?.forEach((service: any) => {
-      newCollapsedState[service.href] = false;
-      newCollapsedState[`${service.href}-specifications`] = false;
-      newCollapsedState[`${service.href}-receives`] = false;
-      newCollapsedState[`${service.href}-sends`] = false;
-      newCollapsedState[`${service.href}-entities`] = false;
-    });
-
-    setCollapsedGroups(newCollapsedState);
-    setIsExpanded(true);
-  }, [filteredData]);
-
-  const toggleExpandCollapse = useCallback(() => {
-    if (isExpanded) {
-      collapseAll();
-    } else {
-      expandAll();
-    }
-  }, [isExpanded, collapseAll, expandAll]);
-
-  const hideSidebar = useCallback(() => {
-    // Dispatch custom event that the Astro layout will listen for
-    window.dispatchEvent(new CustomEvent('sidebarToggle', { detail: { action: 'hide' } }));
-  }, []);
-
-  const isDomainSubDomain = useMemo(() => {
-    return (domain: any) => {
-      const domains = data.domains || [];
-      return domains.some((d: any) => {
-        const subdomains = d.domains || [];
-        return subdomains.some((subdomain: any) => subdomain.data.id === domain.id);
-      });
-    };
-  }, [data.domains]);
-
-  // Helper function to get parent domains (domains that are not subdomains)
-  const getParentDomains = useMemo(() => {
-    return (domains: any[]) => {
-      return domains.filter((domain: any) => !isDomainSubDomain(domain));
-    };
-  }, [isDomainSubDomain]);
-
-  // Helper function to get subdomains for a specific parent domain
-  const getSubdomainsForParent = useMemo(() => {
-    return (parentDomain: any, allDomains: any[]) => {
-      const subdomains = parentDomain.domains || [];
-      return allDomains.filter((domain: any) => subdomains.some((subdomain: any) => subdomain.data.id === domain.id));
-    };
-  }, []);
-
-  // Helper function to get services for a specific domain (only direct services, not from subdomains)
-  const getServicesForDomain = useMemo(() => {
-    return (domain: any, allServices: ServiceItem[], allDomains: any[]) => {
-      const domainServices = domain.services || [];
-      const subdomains = getSubdomainsForParent(domain, allDomains);
-
-      // Get all service IDs from subdomains
-      const subdomainServiceIds = subdomains.flatMap((subdomain: any) => (subdomain.services || []).map((s: any) => s.data.id));
-
-      // Filter services that belong to this domain but NOT to any of its subdomains
-      return allServices.filter(
-        (service: ServiceItem) =>
-          domainServices.some((domainService: any) => domainService.data.id === service.id) &&
-          !subdomainServiceIds.includes(service.id)
-      );
-    };
-  }, [getSubdomainsForParent]);
-
-  // Component to render a single domain item
-  const DomainItem = React.memo(
-    ({ item, isSubdomain = false, nestingLevel = 0 }: { item: any; isSubdomain?: boolean; nestingLevel?: number }) => {
-      const marginLeft = nestingLevel > 0 ? `ml-${nestingLevel * 4}` : '';
-
-      return (
-        <div className={`flex items-center ${marginLeft}`}>
-          <button
-            onClick={(e) => {
-              e.stopPropagation();
-              toggleGroupCollapse(item.href);
-            }}
-            className="p-1 hover:bg-gray-100 rounded-md"
-            title={item.label}
-          >
-            <div className={`transition-transform duration-150 ${collapsedGroups[item.href] ? '' : 'rotate-180'}`}>
-              <ChevronDownIcon className="h-3 w-3 text-gray-500" />
-            </div>
-          </button>
-          <button
-            onClick={(e) => {
-              e.stopPropagation();
-              toggleGroupCollapse(item.href);
-            }}
-            className={`flex-grow flex items-center justify-between px-2 py-0.5 text-xs font-bold rounded-md ${
-              decodedCurrentPath === item.href ? 'bg-purple-100' : 'hover:bg-purple-100'
-            }`}
-            title={item.label}
-          >
-            <span className="truncate">
-              <HighlightedText text={item.label} searchTerm={debouncedSearchTerm} />
-            </span>
-            <span className="text-yellow-600 ml-2 text-[10px] font-medium bg-yellow-50 px-2 py-0.5 rounded">
-              {isSubdomain ? 'SUBDOMAIN' : 'DOMAIN'}
-            </span>
-          </button>
-        </div>
-      );
-    }
-  );
-
-  // Component to render domain content (Overview, Architecture, etc.)
-  const DomainContent = React.memo(
-    ({
-      item,
-      nestingLevel = 0,
-      className = '',
-      isSubdomain = false,
-    }: {
-      item: any;
-      nestingLevel?: number;
-      className?: string;
-      isSubdomain?: boolean;
-    }) => {
-      const marginLeft = nestingLevel > 0 ? `ml-${nestingLevel * 4}` : '';
-      const hasEntities = item.entities && item.entities.length > 0;
-
-      // Get services for this domain
-      const domainServices = getServicesForDomain(item, filteredData['services'] || [], filteredData['domains'] || []);
-
-      return (
-        <div
-          className={`overflow-hidden transition-[height] duration-150 ease-out ${collapsedGroups[item.href] ? 'h-0' : 'h-auto'} ${className}`}
-        >
-          <div className={`space-y-0.5 border-gray-200/80 border-l pl-4  mt-1 ${marginLeft ? marginLeft : 'ml-[9px]'}`}>
-            <a
-              href={`${item.href}`}
-              data-active={decodedCurrentPath === item.href}
-              className={`flex items-center px-2 py-1.5 text-xs text-gray-600 hover:bg-purple-100 rounded-md ${
-                decodedCurrentPath === item.href ? 'bg-purple-100 ' : 'hover:bg-purple-100'
-              }`}
-              title={`${item.label} - Overview`}
-            >
-              <span className="truncate">Overview</span>
-            </a>
-
-            {isVisualizer && hasEntities && (
-              <a
-                href={buildUrl(`/${item.href}/entity-map`)}
-                data-active={decodedCurrentPath === `${item.href}/entity-map`}
-                className={`flex items-center px-2 py-1.5 text-xs text-gray-600 hover:bg-purple-100 rounded-md ${
-                  decodedCurrentPath === `${item.href}/entity-map` ? 'bg-purple-100 ' : 'hover:bg-purple-100'
-                }`}
-              >
-                <span className="truncate">Entity Map</span>
-              </a>
-            )}
-            {!isVisualizer && (
-              <a
-                href={buildUrlWithParams('/architecture/docs/services', {
-                  serviceIds: item.services.map((service: any) => service.data.id).join(','),
-                  domainId: item.id,
-                  domainName: item.name,
-                })}
-                data-active={window.location.href.includes(`domainId=${item.id}`)}
-                className={`flex items-center px-2 py-1.5 text-xs text-gray-600 hover:bg-purple-100 rounded-md ${
-                  window.location.href.includes(`domainId=${item.id}`) ? 'bg-purple-100 ' : 'hover:bg-purple-100'
-                }`}
-              >
-                <span className="truncate">Architecture</span>
-              </a>
-            )}
-            {!isVisualizer && (
-              <a
-                href={buildUrl(`/docs/domains/${item.id}/language`)}
-                data-active={decodedCurrentPath.includes(`/docs/domains/${item.id}/language`)}
-                className={`flex items-center px-2 py-1.5 text-xs text-gray-600 hover:bg-purple-100 rounded-md ${
-                  decodedCurrentPath.includes(`/docs/domains/${item.id}/language`) ? 'bg-purple-100 ' : 'hover:bg-purple-100'
-                }`}
-              >
-                <span className="truncate">Ubiquitous Language</span>
-              </a>
-            )}
-
-            {/* Render services before entities */}
-            {domainServices.length > 0 && (
-              <CollapsibleGroup
-                isCollapsed={collapsedGroups[`${item.href}-services`]}
-                onToggle={() => toggleGroupCollapse(`${item.href}-services`)}
-                title={
-                  <button
-                    onClick={(e) => {
-                      e.stopPropagation();
-                      toggleGroupCollapse(`${item.href}-services`);
-                    }}
-                    className="truncate underline ml-2 text-xs mb-1 py-1"
-                  >
-                    Services ({domainServices.length})
-                  </button>
-                }
-              >
-                <div className="space-y-2 pl-4">
-                  {domainServices.map((service: ServiceItem) => (
-                    <ServiceItem
-                      key={service.href}
-                      item={service}
-                      decodedCurrentPath={decodedCurrentPath}
-                      collapsedGroups={collapsedGroups}
-                      toggleGroupCollapse={toggleGroupCollapse}
-                      isVisualizer={isVisualizer}
-                      searchTerm={debouncedSearchTerm}
-                    />
-                  ))}
-                </div>
-              </CollapsibleGroup>
-            )}
-
-            {item.entities.length > 0 && !isVisualizer && (
-              <CollapsibleGroup
-                isCollapsed={collapsedGroups[`${item.href}-entities`]}
-                onToggle={() => toggleGroupCollapse(`${item.href}-entities`)}
-                title={
-                  <button
-                    onClick={(e) => {
-                      e.stopPropagation();
-                      toggleGroupCollapse(`${item.href}-entities`);
-                    }}
-                    className="truncate underline ml-2 text-xs mb-1 py-1"
-                  >
-                    Entities ({item.entities.length})
-                  </button>
-                }
-              >
-                <MessageList messages={item.entities} decodedCurrentPath={decodedCurrentPath} searchTerm={debouncedSearchTerm} />
-              </CollapsibleGroup>
-            )}
-          </div>
-        </div>
-      );
-    }
-  );
-
-  if (!isInitialized) return null;
-
-  const hasNoResults =
-    debouncedSearchTerm &&
-    !filteredData['context-map']?.length &&
-    !filteredData.domains?.length &&
-    !filteredData.services?.length &&
-    !filteredData.flows?.length &&
-    !filteredData.messagesNotInService?.length;
-
-  return (
-    <nav ref={navRef} className="space-y-4 text-gray-800 px-3 py-4 overflow-auto h-full">
-      <div
-        className={`flex gap-2 transition-all duration-200 ${
-          isSearchPinned ? 'sticky -top-5 z-10 bg-white shadow-md -mx-3 px-3 py-2 border-b border-gray-200' : ''
-        }`}
-      >
-        <input
-          type="text"
-          value={searchTerm}
-          onChange={handleSearchChange}
-          placeholder="Quick search..."
-          className="flex-1 p-2 text-sm rounded-md border border-gray-200 h-[30px]"
-        />
-        <div className="flex gap-1">
-          <button
-            onClick={toggleExpandCollapse}
-            title={isExpanded ? 'Collapse All' : 'Expand All'}
-            className="px-2 py-1 bg-gray-100 hover:bg-gray-200 rounded-md border border-gray-200 h-[30px] flex items-center justify-center"
-          >
-            {isExpanded ? (
-              <ChevronDoubleUpIcon className="h-4 w-4 text-gray-600" />
-            ) : (
-              <ChevronDoubleDownIcon className="h-4 w-4 text-gray-600" />
-            )}
-          </button>
-          <button
-            onClick={hideSidebar}
-            title="Hide Sidebar"
-            className="px-2 py-1 bg-gray-100 hover:bg-gray-200 rounded-md border border-gray-200 h-[30px] flex items-center justify-center"
-          >
-            <PanelLeft className="h-4 w-4 text-gray-600" />
-          </button>
-        </div>
-      </div>
-      <div className="space-y-2 divide-y divide-gray-200/80">
-        {hasNoResults ? (
-          <NoResultsFound searchTerm={debouncedSearchTerm} />
-        ) : (
-          <>
-            {/* Bounded Context Map (Visualiser only) */}
-            {filteredData['context-map'] && filteredData.domains && filteredData.domains.length > 0 && (
-              <div className="pt-0">
-                <ul className="space-y-1">
-                  {filteredData['context-map'].map((item: any) => (
-                    <li key={item.href}>
-                      <a
-                        href={item.href}
-                        data-active={decodedCurrentPath === item.href}
-                        className={`flex items-center justify-between px-2 py-0.5 text-xs font-bold rounded-md ${
-                          decodedCurrentPath === item.href ? 'bg-purple-100 text-purple-900' : 'hover:bg-purple-100'
-                        }`}
-                      >
-                        <span className="truncate flex flex-col items-start">
-                          <HighlightedText text={item.label} searchTerm={debouncedSearchTerm} />
-                          <span className="text-[10px] text-gray-500 font-light">Explore integrations between domains</span>
-                        </span>
-                        <span className="text-blue-600 ml-2 text-[10px] font-medium bg-blue-50 px-2 py-0.5 rounded">DOMAINS</span>
-                      </a>
-                    </li>
-                  ))}
-                </ul>
-              </div>
-            )}
-
-            {/* Domains */}
-            {filteredData['domains'] && (
-              <div className={`${isVisualizer ? 'pt-4 pb-2' : 'p-0'}`}>
-                <ul className="space-y-2">
-                  {getParentDomains(filteredData['domains'] || []).map((parentDomain: any) => {
-                    const subdomains = getSubdomainsForParent(parentDomain, filteredData['domains'] || []);
-
-                    return (
-                      <li key={parentDomain.href} className="space-y-0" data-active={decodedCurrentPath === parentDomain.href}>
-                        <DomainItem item={parentDomain} isSubdomain={false} />
-                        <DomainContent item={parentDomain} />
-
-                        {/* Render nested subdomains */}
-                        {subdomains.length > 0 && !collapsedGroups[parentDomain.href] && (
-                          <div className="space-y-0.5 border-gray-200/80 border-l pl-4 ml-[9px] mt-2">
-                            <CollapsibleGroup
-                              isCollapsed={collapsedGroups[`${parentDomain.href}-subdomains`]}
-                              onToggle={() => toggleGroupCollapse(`${parentDomain.href}-subdomains`)}
-                              title={
-                                <button
-                                  onClick={(e) => {
-                                    e.stopPropagation();
-                                    toggleGroupCollapse(`${parentDomain.href}-subdomains`);
-                                  }}
-                                  className="truncate underline ml-2 text-xs mb-1 py-1"
-                                >
-                                  Subdomains ({subdomains.length})
-                                </button>
-                              }
-                            >
-                              <div className="space-y-2">
-                                {subdomains.map((subdomain: any) => (
-                                  <div
-                                    key={subdomain.href}
-                                    className="space-y-0"
-                                    data-active={decodedCurrentPath === subdomain.href}
-                                  >
-                                    <DomainItem item={subdomain} isSubdomain={true} nestingLevel={1} />
-                                    <DomainContent item={subdomain} nestingLevel={3} className="ml-6" isSubdomain={true} />
-                                  </div>
-                                ))}
-                              </div>
-                            </CollapsibleGroup>
-                          </div>
-                        )}
-                      </li>
-                    );
-                  })}
-                </ul>
-              </div>
-            )}
-
-            {/* All Services Group */}
-            {filteredData['services'] && filteredData['services'].length > 0 && (
-              <div className="pt-4 pb-2">
-                <CollapsibleGroup
-                  isCollapsed={collapsedGroups['all-services-group']}
-                  onToggle={() => toggleGroupCollapse('all-services-group')}
-                  title={
-                    <button
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        toggleGroupCollapse('all-services-group');
-                      }}
-                      className="flex justify-between items-center pl-2 w-full text-xs"
-                    >
-                      <span className="truncate text-xs font-bold">All Services ({filteredData['services'].length})</span>
-                      <span className="ml-2 rounded bg-purple-50 px-2 py-0.5 text-[10px] font-medium text-purple-600">
-                        SERVICES
-                      </span>
-                    </button>
-                  }
-                >
-                  <div className="space-y-4 border-gray-200/80 border-l pl-3 ml-[9px] mt-3">
-                    {filteredData['services'].map((item: any) => {
-                      // Ensure service is collapsed by default if not in collapsedGroups
-                      if (collapsedGroups[item.href] === undefined) {
-                        collapsedGroups[item.href] = true;
-                      }
-
-                      return (
-                        <ServiceItem
-                          key={item.href}
-                          item={item}
-                          decodedCurrentPath={decodedCurrentPath}
-                          collapsedGroups={collapsedGroups}
-                          toggleGroupCollapse={toggleGroupCollapse}
-                          isVisualizer={isVisualizer}
-                          searchTerm={debouncedSearchTerm}
-                        />
-                      );
-                    })}
-                  </div>
-                </CollapsibleGroup>
-              </div>
-            )}
-
-            {/* Flows Group */}
-            {filteredData['flows'] && filteredData['flows'].length > 0 && (
-              <div className="pt-4 pb-2">
-                <CollapsibleGroup
-                  isCollapsed={collapsedGroups['flows-group']}
-                  onToggle={() => toggleGroupCollapse('flows-group')}
-                  title={
-                    <button
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        toggleGroupCollapse('flows-group');
-                      }}
-                      className="flex justify-between items-center pl-2 w-full text-xs"
-                    >
-                      <span className="truncate text-xs font-bold">All Flows ({filteredData['flows'].length})</span>
-                      <span className="ml-2 rounded bg-teal-50 px-2 py-0.5 text-[10px] font-medium text-teal-600">FLOWS</span>
-                    </button>
-                  }
-                >
-                  <div className="space-y-2 border-gray-200/80 border-l pl-3 ml-[9px] mt-3">
-                    {filteredData['flows'].map((item: any) => (
-                      <div key={item.href} data-active={decodedCurrentPath === item.href}>
-                        <a
-                          href={item.href}
-                          data-active={decodedCurrentPath === item.href}
-                          className={`flex items-center justify-between px-2 py-0.5 text-xs font-thin rounded-md ${
-                            decodedCurrentPath === item.href ? 'bg-purple-100 text-purple-900' : 'hover:bg-purple-100'
-                          }`}
-                          title={item.label}
-                        >
-                          <span className="truncate">
-                            <HighlightedText text={item.label} searchTerm={debouncedSearchTerm} />
-                          </span>
-                          <span className={`ml-2 text-[10px] font-medium px-2 uppercase py-0.5 rounded bg-teal-50 text-teal-600`}>
-                            FLOW
-                          </span>
-                        </a>
-                      </div>
-                    ))}
-                  </div>
-                </CollapsibleGroup>
-              </div>
-            )}
-
-            {/* Data Group */}
-            {filteredData['containers'] && filteredData['containers'].length > 0 && (
-              <div className="pt-4 pb-2">
-                <CollapsibleGroup
-                  isCollapsed={collapsedGroups['data-group']}
-                  onToggle={() => toggleGroupCollapse('data-group')}
-                  title={
-                    <button
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        toggleGroupCollapse('data-group');
-                      }}
-                      className="flex justify-between items-center pl-2 w-full text-xs"
-                    >
-                      <span className="truncate text-xs font-bold">All Data Stores ({filteredData['containers'].length})</span>
-                      <span className="ml-2 rounded bg-blue-50 px-2 py-0.5 text-[10px] font-medium text-blue-600">DATA</span>
-                    </button>
-                  }
-                >
-                  <div className="space-y-2 border-gray-200/80 border-l pl-3 ml-[9px] mt-3">
-                    {filteredData['containers'].map((item: any) => (
-                      <div key={item.href} data-active={decodedCurrentPath === item.href}>
-                        <a
-                          href={item.href}
-                          data-active={decodedCurrentPath === item.href}
-                          className={`flex items-center justify-between px-2 py-0.5 text-xs font-thin rounded-md ${
-                            decodedCurrentPath === item.href ? 'bg-purple-100 text-purple-900' : 'hover:bg-purple-100'
-                          }`}
-                          title={item.label}
-                        >
-                          <span className="truncate">
-                            <HighlightedText text={item.label} searchTerm={debouncedSearchTerm} />
-                          </span>
-                          <span className={`ml-2 text-[10px] font-medium px-2 uppercase py-0.5 rounded bg-blue-50 text-blue-600`}>
-                            DATA
-                          </span>
-                        </a>
-                      </div>
-                    ))}
-                  </div>
-                </CollapsibleGroup>
-              </div>
-            )}
-
-            {filteredData['designs'] && filteredData['designs'].length > 0 && (
-              <div className="pt-4 pb-2">
-                <CollapsibleGroup
-                  isCollapsed={collapsedGroups['designs-group']}
-                  onToggle={() => toggleGroupCollapse('designs-group')}
-                  title={
-                    <button
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        toggleGroupCollapse('designs-group');
-                      }}
-                      className="flex justify-between items-center pl-2 w-full text-xs"
-                    >
-                      <span className="truncate text-xs font-bold">All Designs ({filteredData['designs'].length})</span>
-                      <span className="ml-2 rounded bg-teal-50 px-2 py-0.5 text-[10px] font-medium text-teal-600">DESIGNS</span>
-                    </button>
-                  }
-                >
-                  <div className="space-y-2 border-gray-200/80 border-l pl-3 ml-[9px] mt-3">
-                    {filteredData['designs'].map((item: any) => (
-                      <div key={item.href} data-active={decodedCurrentPath === item.href}>
-                        <a
-                          href={item.href}
-                          data-active={decodedCurrentPath === item.href}
-                          className={`flex items-center justify-between px-2 py-0.5 text-xs font-thin rounded-md ${
-                            decodedCurrentPath === item.href ? 'bg-purple-100 text-purple-900' : 'hover:bg-purple-100'
-                          }`}
-                          title={item.label}
-                        >
-                          <span className="truncate">
-                            <HighlightedText text={item.label} searchTerm={debouncedSearchTerm} />
-                          </span>
-                          <span className={`ml-2 text-[10px] font-medium px-2 uppercase py-0.5 rounded bg-teal-50 text-teal-600`}>
-                            DESIGN
-                          </span>
-                        </a>
-                      </div>
-                    ))}
-                  </div>
-                </CollapsibleGroup>
-              </div>
-            )}
-
-            {filteredData['messagesNotInService'] && filteredData['messagesNotInService'].length > 0 && showOrphanedMessages && (
-              <div className="pt-4 pb-2">
-                <CollapsibleGroup
-                  isCollapsed={collapsedGroups['messagesNotInService-group']}
-                  onToggle={() => toggleGroupCollapse('messagesNotInService-group')}
-                  title={
-                    <button
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        toggleGroupCollapse('messagesNotInService-group');
-                      }}
-                      className="flex justify-between items-center pl-2 w-full text-xs"
-                    >
-                      <span className="truncate text-xs font-bold">Orphaned Messages</span>
-                    </button>
-                  }
-                >
-                  <div className="space-y-2 border-gray-200/80 border-l pl-3 ml-[9px] mt-3">
-                    {filteredData['messagesNotInService'].map((item: any) => (
-                      <div key={item.href} data-active={decodedCurrentPath === item.href}>
-                        <a
-                          href={item.href}
-                          data-active={decodedCurrentPath === item.href}
-                          className={`flex items-center justify-between px-2 py-0.5 text-xs font-thin rounded-md ${
-                            decodedCurrentPath === item.href ? 'bg-purple-100 text-purple-900' : 'hover:bg-purple-100'
-                          }`}
-                          title={item.label}
-                        >
-                          <span className="truncate">
-                            <HighlightedText text={item.label} searchTerm={debouncedSearchTerm} />
-                          </span>
-                          <span
-                            className={`ml-2 text-[10px] font-medium px-2 uppercase py-0.5 rounded ${getMessageColorByCollection(item.collection)}`}
-                          >
-                            {getMessageCollectionName(item.collection, item)}
-                          </span>
-                        </a>
-                      </div>
-                    ))}
-                  </div>
-                </CollapsibleGroup>
-              </div>
-            )}
-          </>
-        )}
-      </div>
-    </nav>
-  );
-};
-
-export default React.memo(ListViewSideBar);
diff --git a/eventcatalog/src/components/SideNav/ListViewSideBar/types.ts b/eventcatalog/src/components/SideNav/ListViewSideBar/types.ts
deleted file mode 100644
index f38199905..000000000
--- a/eventcatalog/src/components/SideNav/ListViewSideBar/types.ts
+++ /dev/null
@@ -1,91 +0,0 @@
-export interface MessageItem {
-  href: string;
-  label: string;
-  service: string;
-  id: string;
-  direction: 'sends' | 'receives';
-  type: 'command' | 'query' | 'event';
-  collection: string;
-  data: {
-    name: string;
-  };
-}
-
-export interface EntityItem {
-  href: string;
-  label: string;
-  id: string;
-  name: string;
-}
-
-export interface ServiceItem {
-  href: string;
-  label: string;
-  name: string;
-  id: string;
-  version: string;
-  sidebar?: {
-    badge?: string;
-    color?: string;
-    backgroundColor?: string;
-  };
-  draft: boolean | { title?: string; message: string };
-  sends: MessageItem[];
-  receives: MessageItem[];
-  entities: EntityItem[];
-  writesTo: MessageItem[];
-  readsFrom: MessageItem[];
-  specifications?: {
-    type: string;
-    path: string;
-    name?: string;
-    filename?: string;
-    filenameWithoutExtension?: string;
-  }[];
-}
-
-export interface DomainItem {
-  href: string;
-  label: string;
-  id: string;
-  name: string;
-  services: any[];
-  domains: any[];
-  entities: EntityItem[];
-}
-
-export interface FlowItem {
-  href: string;
-  label: string;
-}
-
-export interface DesignItem {
-  href: string;
-  label: string;
-  id: string;
-  name: string;
-}
-
-export interface Resources {
-  'context-map'?: Array<{
-    href: string;
-    label: string;
-    id: string;
-    name: string;
-  }>;
-  domains?: DomainItem[];
-  services?: ServiceItem[];
-  flows?: FlowItem[];
-  designs?: DesignItem[];
-  messagesNotInService?: MessageItem[];
-  commands?: MessageItem[];
-  queries?: MessageItem[];
-  events?: MessageItem[];
-  containers?: MessageItem[];
-}
-
-export interface ListViewSideBarProps {
-  resources: Resources;
-  currentPath: string;
-  showOrphanedMessages: boolean;
-}
diff --git a/eventcatalog/src/components/SideNav/ListViewSideBar/utils.ts b/eventcatalog/src/components/SideNav/ListViewSideBar/utils.ts
deleted file mode 100644
index 693e57aaa..000000000
--- a/eventcatalog/src/components/SideNav/ListViewSideBar/utils.ts
+++ /dev/null
@@ -1,201 +0,0 @@
-import { isCollectionVisibleInCatalog } from '@eventcatalog';
-import { buildUrl } from '@utils/url-builder';
-import { getChannels } from '@utils/channels';
-import { getDomains } from '@utils/collections/domains';
-import { getFlows } from '@utils/collections/flows';
-import { getServices, getSpecificationsForService } from '@utils/collections/services';
-import { getCommands } from '@utils/commands';
-import { getEvents } from '@utils/events';
-import { getQueries } from '@utils/queries';
-import { getDesigns } from '@utils/collections/designs';
-import { getContainers } from '@utils/collections/containers';
-
-const stripCollection = (collection: any) => {
-  return collection.map((item: any) => ({
-    data: {
-      id: item.data.id,
-      version: item.data.version,
-    },
-  }));
-};
-
-export async function getResourcesForNavigation({ currentPath }: { currentPath: string }) {
-  const events = await getEvents({ getAllVersions: false });
-  const commands = await getCommands({ getAllVersions: false });
-  const queries = await getQueries({ getAllVersions: false });
-  const services = await getServices({ getAllVersions: false });
-  const domains = await getDomains({ getAllVersions: false });
-  const channels = await getChannels({ getAllVersions: false });
-  const flows = await getFlows({ getAllVersions: false });
-  const containers = await getContainers({ getAllVersions: false });
-  const designs = await getDesigns({ getAllVersions: false });
-
-  const messages = [...events, ...commands, ...queries];
-
-  // messages that are not in a service (sends or receives)
-  const messagesNotInService = messages.filter(
-    (message) =>
-      !services.some(
-        (service) =>
-          service.data?.sends?.some((send: any) => send.data.id === message.data.id) ||
-          service.data?.receives?.some((receive: any) => receive.data.id === message.data.id)
-      )
-  );
-
-  const route = currentPath.includes('visualiser') ? 'visualiser' : 'docs';
-
-  // Just the domains for now.
-  const allDataAsSideNav = [...domains, ...services, ...flows, ...channels, ...containers].reduce((acc, item) => {
-    const title = item.collection;
-    const group = acc[title] || [];
-
-    const isCollectionDomain = item.collection === 'domains';
-    const isCollectionService = item.collection === 'services';
-
-    const servicesCount = isCollectionDomain ? item.data.services?.length || 0 : 0;
-    const sends = isCollectionService ? item.data.sends || null : null;
-    const receives = isCollectionService ? item.data.receives || null : null;
-    const entities = isCollectionDomain || isCollectionService ? item.data.entities || null : null;
-
-    const writesTo = isCollectionService ? item.data.writesTo || null : null;
-    const readsFrom = isCollectionService ? item.data.readsFrom || null : null;
-
-    // Add href to the sends and receives
-    const sendsWithHref = sends?.map((send: any) => ({
-      id: send.data.id,
-      data: {
-        name: send.data.name,
-        sidebar: send.data.sidebar,
-        aggregateRoot: send?.data?.aggregateRoot,
-        draft: send.data.draft,
-      },
-      collection: send.collection,
-      href: buildUrl(`/${route}/${send.collection}/${send.data.id}/${send.data.version}`),
-    }));
-    const receivesWithHref = receives?.map((receive: any) => ({
-      id: receive.data.id,
-      data: {
-        name: receive.data.name,
-        sidebar: receive.data.sidebar,
-        aggregateRoot: receive?.data?.aggregateRoot,
-        draft: receive.data.draft,
-      },
-      collection: receive.collection,
-      href: buildUrl(`/${route}/${receive.collection}/${receive.data.id}/${receive.data.version}`),
-    }));
-    const entitiesWithHref = entities?.map((entity: any) => ({
-      id: entity.data.id,
-      data: {
-        name: entity.data.name,
-        sidebar: entity.data.sidebar,
-        aggregateRoot: entity?.data?.aggregateRoot,
-        draft: entity.data.draft,
-      },
-      collection: entity.collection,
-      href: buildUrl(`/${route}/${entity.collection}/${entity.data.id}/${entity.data.version}`),
-    }));
-
-    const writesToWithHref = writesTo?.map((writeTo: any) => ({
-      id: writeTo.data.id,
-      data: {
-        name: writeTo.data.name,
-        sidebar: {
-          badge: writeTo.data.container_type || writeTo.collection,
-          backgroundColor: 'bg-blue-100 text-blue-600',
-        },
-      },
-      collection: writeTo.collection,
-      href: buildUrl(`/${route}/${writeTo.collection}/${writeTo.data.id}/${writeTo.data.version}`),
-    }));
-
-    const readsFromWithHref = readsFrom?.map((readFrom: any) => ({
-      id: readFrom.data.id,
-      data: {
-        name: readFrom.data.name,
-        sidebar: {
-          badge: readFrom.data.container_type || readFrom.collection,
-          backgroundColor: 'bg-blue-100 text-indigo-600',
-        },
-      },
-      collection: readFrom.collection,
-      href: buildUrl(`/${route}/${readFrom.collection}/${readFrom.data.id}/${readFrom.data.version}`),
-    }));
-
-    // don't render items if we are in the visualiser and the item has visualiser set to false
-    if (currentPath.includes('visualiser') && item.data.visualiser === false) {
-      return acc;
-    }
-
-    const navigationItem = {
-      label: item.data.name,
-      version: item.data.version,
-      // items: item.collection === 'users' ? [] : item.headings,
-      visible: isCollectionVisibleInCatalog(item.collection),
-      // @ts-ignore
-      href: item.data.version
-        ? // @ts-ignore
-          buildUrl(`/${route}/${item.collection}/${item.data.id}/${item.data.version}`)
-        : buildUrl(`/${route}/${item.collection}/${item.data.id}`),
-      collection: item.collection,
-      servicesCount,
-      id: item.data.id,
-      name: item.data.name,
-      draft: item.data.draft,
-      services: isCollectionDomain ? stripCollection(item.data.services) : null,
-      domains: isCollectionDomain ? stripCollection(item.data.domains) : null,
-      sends: sendsWithHref,
-      receives: receivesWithHref,
-      entities: entitiesWithHref,
-      specifications: isCollectionService ? getSpecificationsForService(item) : null,
-      writesTo: writesToWithHref,
-      readsFrom: readsFromWithHref,
-      sidebar: item.data?.sidebar,
-      renderInVisualiser: item.data?.visualiser ?? true,
-    };
-
-    group.push(navigationItem);
-
-    return {
-      ...acc,
-      [title]: group,
-    };
-  }, {} as any);
-
-  // Add messagesNotInService
-  const messagesNotInServiceAsSideNav = messagesNotInService.map((item) => ({
-    label: item.data.name,
-    version: item.data.version,
-    id: item.data.id,
-    name: item.data.name,
-    draft: item.data.draft,
-    href: buildUrl(`/${route}/${item.collection}/${item.data.id}/${item.data.version}`),
-    collection: item.collection,
-  }));
-
-  const sideNav = {
-    ...(currentPath.includes('visualiser')
-      ? {
-          'context-map': [
-            {
-              label: 'Domain Integration Map',
-              href: buildUrl('/visualiser/domain-integrations'),
-              collection: 'domain-integrations',
-            },
-          ],
-        }
-      : {}),
-    ...allDataAsSideNav,
-    messagesNotInService: messagesNotInServiceAsSideNav,
-  };
-
-  // Add designs?
-  if (designs.length > 0) {
-    sideNav['designs'] = designs.map((design) => ({
-      label: design.data.name,
-      href: buildUrl(`/visualiser/designs/${design.data.id}`),
-      collection: 'designs',
-    }));
-  }
-
-  return sideNav;
-}
diff --git a/eventcatalog/src/components/SideNav/SideNav.astro b/eventcatalog/src/components/SideNav/SideNav.astro
deleted file mode 100644
index 427f8c361..000000000
--- a/eventcatalog/src/components/SideNav/SideNav.astro
+++ /dev/null
@@ -1,37 +0,0 @@
----
-import type { HTMLAttributes } from 'astro/types';
-import config from '@config';
-
-// FlatView
-import { getResourcesForNavigation as getListViewResources } from './ListViewSideBar/utils';
-
-// TreeView
-import { SideNavTreeView } from './TreeView';
-import { getTreeView } from './TreeView/getTreeView';
-
-import ListViewSideBar from './ListViewSideBar';
-
-interface Props extends Omit<HTMLAttributes<'div'>, 'children'> {}
-
-const currentPath = Astro.url.pathname;
-
-let props;
-
-const SIDENAV_TYPE = config?.docs?.sidebar?.type ?? 'LIST_VIEW';
-const SHOW_ORPHANED_MESSAGES = config?.docs?.sidebar?.showOrphanedMessages ?? true;
-
-if (SIDENAV_TYPE === 'LIST_VIEW') {
-  props = await getListViewResources({ currentPath });
-} else if (SIDENAV_TYPE === 'TREE_VIEW') {
-  props = getTreeView({ projectDir: process.env.PROJECT_DIR!, currentPath });
-}
----
-
-<div {...Astro.props}>
-  {
-    SIDENAV_TYPE === 'LIST_VIEW' && (
-      <ListViewSideBar resources={props} currentPath={currentPath} client:only showOrphanedMessages={SHOW_ORPHANED_MESSAGES} />
-    )
-  }
-  {SIDENAV_TYPE === 'TREE_VIEW' && <SideNavTreeView client:only transition:persist tree={props} />}
-</div>
diff --git a/eventcatalog/src/components/SideNav/TreeView/getTreeView.ts b/eventcatalog/src/components/SideNav/TreeView/getTreeView.ts
deleted file mode 100644
index b82868382..000000000
--- a/eventcatalog/src/components/SideNav/TreeView/getTreeView.ts
+++ /dev/null
@@ -1,190 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import os from 'node:os';
-import gm from 'gray-matter';
-import { globSync } from 'glob';
-import type { CollectionKey } from 'astro:content';
-import { buildUrl } from '@utils/url-builder';
-
-export type TreeNode = {
-  id: string;
-  name: string;
-  version: string;
-  href?: string;
-  type: CollectionKey | null;
-  children: TreeNode[];
-};
-
-/**
- * Resource types that should be in the sidenav
- */
-const RESOURCE_TYPES = ['domains', 'entities', 'services', 'events', 'commands', 'queries', 'flows', 'channels', 'containers'];
-// const RESOURCE_TYPES = ['domains', 'services', 'events', 'commands', 'queries', 'flows', 'channels'];
-
-/**
- * Check if the path has a RESOURCE_TYPE on path
- */
-function canBeResource(dirPath: string) {
-  const parts = dirPath.split(path.sep);
-  for (let i = parts.length - 1; i >= 0; i--) {
-    if (RESOURCE_TYPES.includes(parts[i])) return true;
-  }
-  return false;
-}
-
-function isNotVersioned(dirPath: string) {
-  const parts = dirPath.split(path.sep);
-  return parts.every((p) => p !== 'versioned');
-}
-
-function getResourceType(filePath: string): CollectionKey | null {
-  const parts = filePath.split(path.sep);
-  for (let i = parts.length - 1; i >= 0; i--) {
-    if (RESOURCE_TYPES.includes(parts[i])) return parts[i] as CollectionKey;
-  }
-  return null;
-}
-
-function buildTreeOfDir(directory: string, parentNode: TreeNode, options: { ignore?: CollectionKey[] }) {
-  let node: TreeNode | null = null;
-
-  const resourceType = getResourceType(directory);
-
-  const markdownFiles = globSync(path.join(directory, '/*.mdx'), { windowsPathsNoEscape: os.platform() === 'win32' });
-  const isResourceIgnored = options?.ignore && resourceType && options.ignore.includes(resourceType);
-
-  if (markdownFiles.length > 0 && !isResourceIgnored) {
-    const resourceFilePath = markdownFiles.find((md) => md.endsWith('index.mdx'));
-    if (resourceFilePath) {
-      const resourceDef = gm.read(resourceFilePath);
-      node = {
-        id: resourceDef.data.id,
-        name: resourceDef.data.name,
-        type: resourceType,
-        version: resourceDef.data.version,
-        children: [],
-      };
-      parentNode.children.push(node);
-    }
-  }
-
-  const directories = fs.readdirSync(directory).filter((name) => {
-    const dirPath = path.join(directory, name);
-    return fs.statSync(dirPath).isDirectory() && isNotVersioned(dirPath) && canBeResource(dirPath);
-  });
-  for (const dir of directories) {
-    buildTreeOfDir(path.join(directory, dir), node || parentNode, options);
-  }
-}
-
-function forEachTreeNodeOf(node: TreeNode, ...callbacks: Array<(node: TreeNode) => void>) {
-  const next = node.children;
-
-  callbacks.forEach((cb) => cb(node));
-
-  // Go to next level
-  next.forEach((n) => {
-    forEachTreeNodeOf(n, ...callbacks);
-  });
-}
-
-function addHrefToNode(basePathname: 'docs' | 'visualiser') {
-  return (node: TreeNode) => {
-    node.href = encodeURI(
-      buildUrl(
-        `/${basePathname}/${node.type}/${node.id}${node.type === 'teams' || node.type === 'users' ? '' : `/${node.version}`}`
-      )
-    );
-  };
-}
-
-function orderChildrenByName(parentNode: TreeNode) {
-  parentNode.children.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-function groupChildrenByType(parentNode: TreeNode) {
-  if (parentNode.children.length === 0) return; // Only group if there are children
-
-  const acc: Record<string, TreeNode[]> = {};
-
-  // Flows and messages are collapsed by default
-
-  parentNode.children.forEach((n) => {
-    if (n.type === null) return; // TODO: Just ignore or remove the type null???
-    if (!(n.type in acc)) acc[n.type] = [];
-    acc[n.type].push(n);
-  });
-
-  // Collapse everything except domains
-  const AUTO_EXPANDED_TYPES = ['domains'];
-
-  parentNode.children = Object.entries(acc)
-    // Order label nodes by RESOURCE_TYPES
-    .sort(([aType], [bType]) => RESOURCE_TYPES.indexOf(aType) - RESOURCE_TYPES.indexOf(bType))
-    // Construct the label nodes
-    .map(([type, nodes]) => {
-      return {
-        id: `${parentNode.id}/${type}`,
-        name: type === 'containers' ? 'Data' : type,
-        type: type as CollectionKey,
-        version: '0',
-        children: nodes,
-        isExpanded: AUTO_EXPANDED_TYPES.includes(type),
-        isLabel: true,
-      };
-    });
-}
-
-const treeViewCache = new Map<string, TreeNode>();
-
-export function getTreeView({ projectDir, currentPath }: { projectDir: string; currentPath: string }): TreeNode {
-  const basePathname = currentPath.split('/').find((p) => p === 'docs' || p === 'visualiser') || 'docs';
-
-  const cacheKey = `${projectDir}:${basePathname}`;
-  if (treeViewCache.has(cacheKey)) return treeViewCache.get(cacheKey)!;
-
-  const rootNode: TreeNode = {
-    id: '/',
-    name: 'root',
-    type: null,
-    version: '0',
-    children: [],
-  };
-
-  buildTreeOfDir(projectDir, rootNode, {
-    ignore: basePathname === 'visualiser' ? ['teams', 'users', 'channels'] : undefined,
-  });
-
-  // prettier-ignore
-  forEachTreeNodeOf(
-    rootNode,
-    addHrefToNode(basePathname),
-    orderChildrenByName,
-    groupChildrenByType,
-  );
-
-  if (basePathname === 'visualiser') {
-    rootNode.children.unshift({
-      id: '/bounded-context-map',
-      name: 'bounded context map',
-      type: 'bounded-context-map' as any,
-      version: '0',
-      isLabel: true,
-      children: [
-        {
-          id: '/domain-map',
-          name: 'Domain map',
-          href: buildUrl('/visualiser/context-map'),
-          type: 'bounded-context-map' as any,
-          version: '',
-          children: [],
-        },
-      ],
-    } as TreeNode);
-  }
-
-  // Store in cache before returning
-  treeViewCache.set(cacheKey, rootNode);
-
-  return rootNode;
-}
diff --git a/eventcatalog/src/components/SideNav/TreeView/index.tsx b/eventcatalog/src/components/SideNav/TreeView/index.tsx
deleted file mode 100644
index fbe6a7f08..000000000
--- a/eventcatalog/src/components/SideNav/TreeView/index.tsx
+++ /dev/null
@@ -1,94 +0,0 @@
-import { gray } from 'tailwindcss/colors';
-import { TreeView } from '@components/TreeView';
-import { navigate } from 'astro:transitions/client';
-import type { TreeNode as RawTreeNode } from './getTreeView';
-import { getIconForCollection } from '@utils/collections/icons';
-import { useEffect, useState } from 'react';
-
-type TreeNode = RawTreeNode & { isLabel?: true; isDefaultExpanded?: boolean; isExpanded?: boolean };
-
-function isCurrentNode(node: TreeNode, currentPathname: string) {
-  return currentPathname === node.href;
-}
-
-function TreeNode({ node }: { node: TreeNode }) {
-  const Icon = getIconForCollection(node.type ?? '');
-  const [isCurrent, setIsCurrent] = useState(document.location.pathname === node.href);
-
-  useEffect(() => {
-    const abortCtrl = new AbortController();
-    // prettier-ignore
-    document.addEventListener(
-      'astro:page-load', 
-      () => setIsCurrent(document.location.pathname === node.href), 
-      { signal: abortCtrl.signal },
-    );
-    return () => abortCtrl.abort();
-  }, [document, node]);
-
-  return (
-    <TreeView.Item
-      key={node.id}
-      id={node.id}
-      current={isCurrent}
-      defaultExpanded={node?.isExpanded || node?.isDefaultExpanded}
-      onSelect={node?.isLabel || !node?.href ? undefined : () => navigate(node.href!)}
-    >
-      {!node?.isLabel && (
-        <TreeView.LeadingVisual>
-          <Icon className="w-3 -ml-1" />
-        </TreeView.LeadingVisual>
-      )}
-      <span
-        className={node?.isLabel ? ' capitalize  text-[13px]  text-purple-900 font-extrabold' : 'font-light text-[14px] -ml-0.5'}
-      >
-        {node.name} {node.isLabel ? `(${node.children.length})` : ''}
-      </span>
-      {(node.children || []).length > 0 && (
-        <TreeView.SubTree>
-          {node.children!.map((childNode) => (
-            <TreeNode key={childNode.id} node={childNode} />
-          ))}
-        </TreeView.SubTree>
-      )}
-    </TreeView.Item>
-  );
-}
-
-export function SideNavTreeView({ tree }: { tree: TreeNode }) {
-  function bubbleUpExpanded(parentNode: TreeNode) {
-    if (isCurrentNode(parentNode, document.location.pathname)) return true;
-    return (parentNode.isDefaultExpanded = parentNode.children.some(bubbleUpExpanded));
-  }
-  bubbleUpExpanded(tree);
-
-  return (
-    <nav id="resources-tree" className="px-2 py-2">
-      <TreeView
-        truncate={false}
-        style={{
-          // @ts-expect-error inline css var
-          '--base-size-8': '0.5rem',
-          '--base-size-12': '0.75rem',
-          '--borderColor-muted': '#fff',
-          '--borderRadius-medium': '0.375rem',
-          '--borderWidth-thick': '0.125rem',
-          '--borderWidth-thin': '0.0625rem',
-          '--boxShadow-thick': 'inset 0 0 0 var(--borderWidth-thick)',
-          '--control-transparent-bgColor-hover': '#656c7626',
-          '--control-transparent-bgColor-selected': '#656c761a',
-          // '--fgColor-accent': purple[700],
-          '--fgColor-default': gray[600],
-          '--fgColor-muted': gray[600],
-          '--text-body-size-medium': '0.875rem',
-          '--stack-gap-condensed': '0.5rem',
-          '--treeViewItem-leadingVisual-iconColor-rest': 'var(--fgColor-muted)',
-        }}
-      >
-        {tree.children.map((n) => (
-          <TreeNode key={n.id} node={n} />
-        ))}
-      </TreeView>
-    </nav>
-  );
-}
diff --git a/eventcatalog/src/components/Tables/Table.tsx b/eventcatalog/src/components/Tables/Table.tsx
deleted file mode 100644
index e1a905ace..000000000
--- a/eventcatalog/src/components/Tables/Table.tsx
+++ /dev/null
@@ -1,416 +0,0 @@
-import {
-  flexRender,
-  getCoreRowModel,
-  getFacetedMinMaxValues,
-  getFacetedRowModel,
-  getFacetedUniqueValues,
-  getFilteredRowModel,
-  getPaginationRowModel,
-  useReactTable,
-  type Column,
-  type ColumnFiltersState,
-} from '@tanstack/react-table';
-import DebouncedInput from './DebouncedInput';
-
-import { getColumnsByCollection } from './columns';
-import { useEffect, useMemo, useState } from 'react';
-import type { CollectionMessageTypes, TableConfiguration } from '@types';
-import { isSameVersion } from '@utils/collections/util';
-
-declare module '@tanstack/react-table' {
-  // @ts-ignore
-  interface ColumnMeta<TData extends RowData, TValue> {
-    filterVariant?: 'collection' | 'name' | 'badges' | 'text';
-    collectionFilterKey?:
-      | 'producers'
-      | 'consumers'
-      | 'sends'
-      | 'receives'
-      | 'services'
-      | 'ownedCommands'
-      | 'ownedQueries'
-      | 'ownedEvents'
-      | 'ownedServices'
-      | 'associatedTeams'
-      | 'servicesThatWriteToContainer'
-      | 'servicesThatReadFromContainer';
-    filteredItemHasVersion?: boolean;
-    showFilter?: boolean;
-    className?: string;
-  }
-}
-
-export type TCollectionTypes = 'domains' | 'services' | CollectionMessageTypes | 'flows' | 'users' | 'teams' | 'containers';
-
-export type TData<T extends TCollectionTypes> = {
-  collection: T;
-  data: {
-    id: string;
-    name: string;
-    summary: string;
-    version: string;
-    latestVersion?: string; // Defined on getter collection utility
-    draft?: boolean | { title?: string; message: string }; // Draft property from base schema
-    badges?: Array<{
-      id: string; // Where is it defined?
-      content: string;
-      backgroundColor: string;
-      textColor: string;
-      icon: any; // Where is it defined?
-    }>;
-    // ---------------------------------------------------------------------------
-    // Domains
-    services?: Array<{
-      collection: string; // Be more specific;
-      data: {
-        id: string;
-        name: string;
-        version: string;
-      };
-    }>;
-    // ---------------------------------------------------------------------------
-    // Services
-    receives?: Array<{
-      collection: string; // Be more specific;
-      data: {
-        id: string;
-        name: string;
-        version: string;
-      };
-    }>;
-    sends?: Array<{
-      collection: string; // Be more specific;
-      data: {
-        id: string;
-        name: string;
-        version: string;
-      };
-    }>;
-    // ---------------------------------------------------------------------------
-    // Messages
-    producers?: Array<{
-      collection: string; // Specify only 'services'?
-      data: {
-        id: string;
-        name: string;
-        version: string;
-      };
-    }>;
-    // Only for messages
-    consumers?: Array<{
-      collection: string; // Specify only 'services'?
-      data: {
-        id: string;
-        name: string;
-        version: string;
-      };
-    }>;
-    // Only for containers
-    servicesThatWriteToContainer?: Array<{
-      collection: string; // Specify only 'services'?
-      data: {
-        id: string;
-        name: string;
-        version: string;
-      };
-    }>;
-    // Only for containers
-    servicesThatReadFromContainer?: Array<{
-      collection: string; // Specify only 'services'?
-      data: {
-        id: string;
-        name: string;
-        version: string;
-      };
-    }>;
-    // ---------------------------------------------------------------------------
-    // Users
-    avatarUrl?: string;
-    email?: string;
-    slackDirectMessageUrl?: string;
-    msTeamsDirectMessageUrl?: string;
-    role?: string;
-    ownedCommands: any;
-    ownedEvents: any;
-    ownedServices: any;
-    associatedTeams: any;
-    ownedQueries: any;
-    // Teams
-    members: any;
-  };
-};
-
-export const Table = <T extends TCollectionTypes>({
-  data: initialData,
-  collection,
-  mode = 'simple',
-  checkboxLatestId,
-  checkboxDraftsId,
-  tableConfiguration,
-}: {
-  data: TData<T>[];
-  collection: T;
-  checkboxLatestId: string;
-  checkboxDraftsId: string;
-  mode?: 'simple' | 'full';
-  tableConfiguration?: TableConfiguration;
-}) => {
-  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
-
-  useEffect(() => {
-    const urlParams = new URLSearchParams(window.location.search);
-    const id = urlParams.get('id');
-    if (id) {
-      setColumnFilters([{ id: 'name', value: id }]);
-    }
-  }, []);
-
-  const [showOnlyLatest, setShowOnlyLatest] = useState(true);
-  const [onlyShowDrafts, setOnlyShowDrafts] = useState(false);
-
-  useEffect(() => {
-    const checkbox = document.getElementById(checkboxLatestId);
-    function handleChange(evt: Event) {
-      const checked = (evt.target as HTMLInputElement).checked;
-      setShowOnlyLatest(checked);
-    }
-
-    checkbox?.addEventListener('change', handleChange);
-
-    return () => checkbox?.removeEventListener('change', handleChange);
-  }, [checkboxLatestId]);
-
-  useEffect(() => {
-    const checkbox = document.getElementById(checkboxDraftsId);
-    function handleChange(evt: Event) {
-      const checked = (evt.target as HTMLInputElement).checked;
-      setOnlyShowDrafts(checked);
-    }
-
-    checkbox?.addEventListener('change', handleChange);
-
-    return () => checkbox?.removeEventListener('change', handleChange);
-  }, [checkboxDraftsId]);
-
-  // Filter data based on checkbox states
-  const filteredData = useMemo(() => {
-    return initialData.filter((row) => {
-      // Check if item is a draft
-      const isDraft = row.data.draft === true || (typeof row.data.draft === 'object' && row.data.draft !== null);
-
-      // If "Only show drafts" is enabled, show only drafts
-      if (onlyShowDrafts && !isDraft) {
-        return false;
-      }
-
-      // If "Only show drafts" is enabled, don't apply other filters
-      if (onlyShowDrafts) {
-        return true;
-      }
-
-      // Check latest version filter (only when not showing only drafts)
-      if (showOnlyLatest) {
-        return isSameVersion(row.data.version, row.data.latestVersion);
-      }
-
-      return true;
-    });
-  }, [initialData, showOnlyLatest, onlyShowDrafts]);
-
-  const columns = useMemo(
-    () => getColumnsByCollection(collection, tableConfiguration ?? ({ columns: {} } as TableConfiguration)),
-    [collection, tableConfiguration]
-  );
-
-  const table = useReactTable({
-    data: filteredData,
-    columns,
-    onColumnFiltersChange: setColumnFilters,
-    getCoreRowModel: getCoreRowModel(),
-    getFilteredRowModel: getFilteredRowModel(),
-    getFacetedRowModel: getFacetedRowModel(), // client-side faceting
-    getFacetedUniqueValues: getFacetedUniqueValues(), // generate unique values for select filter/autocomplete
-    getFacetedMinMaxValues: getFacetedMinMaxValues(), // generate min/max values for range filter
-    getPaginationRowModel: getPaginationRowModel(),
-    state: {
-      columnFilters,
-      columnVisibility: Object.fromEntries(
-        Object.entries(tableConfiguration?.columns ?? {}).map(([key, value]) => [key, value.visible ?? true])
-      ),
-    },
-  });
-
-  return (
-    <div>
-      {/* <div className='text-right text-gray-400'>{table.getPrePaginationRowModel().rows.length} results</div> */}
-      <div className=" bg-gray-100/20 rounded-md border-2 border-gray-200 shadow-sm ">
-        <table className="min-w-full divide-y divide-gray-200 rounded-md ">
-          <thead className="bg-gray-200/50">
-            {table.getHeaderGroups().map((headerGroup, index) => (
-              <tr key={`${headerGroup}-${index}`} className="rounded-tl-lg">
-                {headerGroup.headers.map((header) => (
-                  <th key={`${header.id}`} className="pl-4 pr-3 text-left text-sm font-semibold text-gray-800 sm:pl-0  ">
-                    <div className="flex flex-col justify-start px-2 py-2 space-y-2">
-                      <div className="text-md">
-                        {header.isPlaceholder ? null : flexRender(header.column.columnDef.header, header.getContext())}
-                      </div>
-                      <div className="">
-                        {header.column.columnDef.meta?.showFilter !== false && <Filter column={header.column} />}
-                        {header.column.columnDef.meta?.showFilter == false && <div className="h-10" />}
-                      </div>
-                    </div>
-                  </th>
-                ))}
-              </tr>
-            ))}
-          </thead>
-
-          <tbody className="divide-y divide-gray-300 ">
-            {table.getRowModel().rows.map((row, index) => (
-              <tr key={`${row.id}-${index}`}>
-                {row.getVisibleCells().map((cell) => (
-                  <td
-                    key={cell.id}
-                    className={` py-4 pl-4 pr-3 text-sm font-medium text-gray-900  ${cell.column.columnDef.meta?.className}`}
-                  >
-                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
-                  </td>
-                ))}
-              </tr>
-            ))}
-          </tbody>
-        </table>
-      </div>
-      <div>
-        <div className="h-8" />
-        <div className="flex items-center gap-2 justify-end px-4  ">
-          <button
-            className="relative inline-flex items-center rounded-l-md bg-white px-2 py-1 text-gray-400 ring-1 ring-inset ring-gray-300 hover:bg-gray-50 focus:z-10"
-            onClick={() => table.setPageIndex(0)}
-            disabled={!table.getCanPreviousPage()}
-          >
-            {'<<'}
-          </button>
-          <button
-            className="relative inline-flex items-center  bg-white px-2 py-1 text-gray-400 ring-1 ring-inset ring-gray-300 hover:bg-gray-50 focus:z-10"
-            onClick={() => table.previousPage()}
-            disabled={!table.getCanPreviousPage()}
-          >
-            {'<'}
-          </button>
-          <button
-            className="relative inline-flex items-center  bg-white px-2 py-1 text-gray-400 ring-1 ring-inset ring-gray-300 hover:bg-gray-50 focus:z-10"
-            onClick={() => table.nextPage()}
-            disabled={!table.getCanNextPage()}
-          >
-            {'>'}
-          </button>
-          <button
-            className="relative inline-flex items-center rounded-r-md bg-white px-2 py-1 text-gray-400 ring-1 ring-inset ring-gray-300 hover:bg-gray-50 focus:z-10"
-            onClick={() => table.setPageIndex(table.getPageCount() - 1)}
-            disabled={!table.getCanNextPage()}
-          >
-            {'>>'}
-          </button>
-          <span className="flex items-center gap-1">
-            <div>Page</div>
-            <strong>
-              {table.getState().pagination.pageIndex + 1} of {table.getPageCount()}
-            </strong>
-          </span>
-          <span className="flex items-center gap-1">
-            | Go to page:
-            <input
-              type="number"
-              defaultValue={table.getState().pagination.pageIndex + 1}
-              onChange={(e) => {
-                const page = e.target.value ? Number(e.target.value) - 1 : 0;
-                table.setPageIndex(page);
-              }}
-              className="border border-gray-300 p-1 rounded w-16"
-            />
-          </span>
-          <select
-            value={table.getState().pagination.pageSize}
-            onChange={(e) => {
-              table.setPageSize(Number(e.target.value));
-            }}
-          >
-            {[10, 20, 30, 40, 50].map((pageSize) => (
-              <option key={pageSize} value={pageSize}>
-                Show {pageSize}
-              </option>
-            ))}
-          </select>
-        </div>
-      </div>
-    </div>
-  );
-};
-
-function Filter<T extends TCollectionTypes>({ column }: { column: Column<TData<T>, unknown> }) {
-  const { filterVariant, collectionFilterKey, filteredItemHasVersion = true } = column.columnDef.meta ?? {};
-
-  const columnFilterValue = column.getFilterValue();
-
-  const sortedUniqueValues = useMemo(() => {
-    if (filterVariant === 'collection' && collectionFilterKey) {
-      const rows = column.getFacetedRowModel().rows;
-      const data = rows.map((row) => row.original.data?.[collectionFilterKey] ?? []).flat();
-
-      const allItems = data.map((item) =>
-        filteredItemHasVersion ? `${item?.data.name} (v${item?.data.version})` : `${item?.data.name}`
-      );
-      const uniqueItemsInList = Array.from(new Set(allItems));
-
-      return uniqueItemsInList.sort().slice(0, 2000);
-    }
-    if (filterVariant === 'name') {
-      const rows = column.getFacetedRowModel().rows;
-      const data = rows
-        .map((row) => {
-          const data = row.original;
-          return data;
-        })
-        .flat();
-
-      const allItems = data.map((item) =>
-        filteredItemHasVersion ? `${item.data.name} (v${item.data.version})` : `${item.data.name}`
-      );
-      const uniqueItemsInList = Array.from(new Set(allItems));
-
-      return uniqueItemsInList.sort().slice(0, 2000);
-    }
-    if (filterVariant === 'badges') {
-      const allBadges = column.getFacetedUniqueValues().keys();
-      // join all badges into a single array
-      const allBadgesArray = Array.from(allBadges)
-        .flat()
-        .filter((b) => !!b);
-      const allBadgesString = allBadgesArray.map((badge) => badge.content);
-      const uniqueBadges = Array.from(new Set(allBadgesString));
-      return uniqueBadges.sort().slice(0, 2000);
-    }
-    return Array.from(column.getFacetedUniqueValues().keys()).sort().slice(0, 2000);
-  }, [column.getFacetedUniqueValues(), filterVariant]);
-
-  return (
-    <div>
-      {/* Autocomplete suggestions from faceted values feature */}
-      <datalist id={column.id + 'list'}>
-        {sortedUniqueValues.map((value: any, index) => (
-          <option value={value} key={`${value}-${index}`} />
-        ))}
-      </datalist>
-      <DebouncedInput
-        type="text"
-        value={(columnFilterValue ?? '') as string}
-        onChange={(value) => column.setFilterValue(value)}
-        placeholder={`Search... ${!column?.columnDef?.meta?.filterVariant ? `(${column.getFacetedUniqueValues().size})` : ''}`}
-        className="w-full p-2 border shadow rounded"
-        list={column.id + 'list'}
-      />
-      <div className="h-1" />
-    </div>
-  );
-}
diff --git a/eventcatalog/src/components/Tables/columns/ContainersTableColumns.tsx b/eventcatalog/src/components/Tables/columns/ContainersTableColumns.tsx
deleted file mode 100644
index b3a810866..000000000
--- a/eventcatalog/src/components/Tables/columns/ContainersTableColumns.tsx
+++ /dev/null
@@ -1,154 +0,0 @@
-import { createColumnHelper } from '@tanstack/react-table';
-import { filterByName } from '../filters/custom-filters';
-import { buildUrl } from '@utils/url-builder';
-import { ServerIcon } from '@heroicons/react/24/solid';
-import { DatabaseIcon } from 'lucide-react';
-import { createBadgesColumn } from './SharedColumns';
-import type { TData } from '../Table';
-import { filterCollectionByName } from '../filters/custom-filters';
-import type { TableConfiguration } from '@types';
-const columnHelper = createColumnHelper<TData<'containers'>>();
-
-export const columns = (tableConfiguration: TableConfiguration) => [
-  columnHelper.accessor('data.name', {
-    id: 'name',
-    header: () => <span>{tableConfiguration.columns?.name?.label || 'Storage'}</span>,
-    cell: (info) => {
-      const containerRaw = info.row.original;
-      const color = 'blue';
-      return (
-        <div className=" group ">
-          <a
-            href={buildUrl(`/docs/${containerRaw.collection}/${containerRaw.data.id}/${containerRaw.data.version}`)}
-            className={`group-hover:text-${color}-500 flex space-x-1 items-center`}
-          >
-            <div className={`flex items-center border border-gray-300 shadow-sm rounded-md group-hover:border-${color}-400`}>
-              <span className="flex items-center">
-                <span className={`bg-${color}-500 group-hover:bg-${color}-600 h-full rounded-tl rounded-bl p-1`}>
-                  <DatabaseIcon className="h-4 w-4 text-white" />
-                </span>
-                <span className="leading-none px-2 group-hover:underline group-hover:text-primary font-light">
-                  {containerRaw.data.name} (v{containerRaw.data.version})
-                </span>
-              </span>
-            </div>
-          </a>
-        </div>
-      );
-    },
-    footer: (info) => info.column.id,
-    meta: {
-      filterVariant: 'name',
-    },
-    filterFn: filterByName,
-  }),
-  columnHelper.accessor('data.summary', {
-    id: 'summary',
-    header: () => <span>{tableConfiguration.columns?.summary?.label || 'Summary'}</span>,
-    cell: (info) => <span className="font-light ">{info.renderValue()}</span>,
-    footer: (info) => info.column.id,
-    meta: {
-      showFilter: false,
-      className: 'max-w-md',
-    },
-  }),
-  columnHelper.accessor('data.servicesThatWriteToContainer', {
-    id: 'writes',
-    header: () => <span>{tableConfiguration.columns?.writes?.label || 'Writes'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'servicesThatWriteToContainer',
-    },
-    cell: (info) => {
-      const services = info.getValue();
-      if (services?.length === 0 || !services)
-        return <div className="font-light text-sm text-gray-400/60 text-left italic">No services documented</div>;
-      return (
-        <ul className="">
-          {services.map((service, index) => {
-            return (
-              <li className="py-2 group flex items-center space-x-2" key={`${service.data.id}-${index}`}>
-                <a
-                  href={buildUrl(`/docs/${service.collection}/${service.data.id}/${service.data.version}`)}
-                  className="group-hover:text-primary flex space-x-1 items-center "
-                >
-                  <div className="flex items-center border border-gray-300 shadow-sm rounded-md">
-                    <span className="flex items-center">
-                      <span className="bg-pink-500 h-full rounded-tl rounded-bl p-1">
-                        <ServerIcon className="h-4 w-4 text-white" />
-                      </span>
-                      <span className="font-light leading-none px-2 group-hover:underline">
-                        {service.data.name} (v{service.data.version})
-                      </span>
-                    </span>{' '}
-                  </div>
-                </a>
-              </li>
-            );
-          })}
-        </ul>
-      );
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('servicesThatWriteToContainer'),
-  }),
-  columnHelper.accessor('data.servicesThatReadFromContainer', {
-    id: 'reads',
-    header: () => <span>{tableConfiguration.columns?.reads?.label || 'Reads'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'servicesThatReadFromContainer',
-    },
-    cell: (info) => {
-      const services = info.getValue();
-      if (services?.length === 0 || !services)
-        return <div className="font-light text-sm text-gray-400/60 text-left italic">No services documented</div>;
-      return (
-        <ul className="">
-          {services.map((service, index) => {
-            return (
-              <li className="py-2 group flex items-center space-x-2" key={`${service.data.id}-${index}`}>
-                <a
-                  href={buildUrl(`/docs/${service.collection}/${service.data.id}/${service.data.version}`)}
-                  className="group-hover:text-primary flex space-x-1 items-center "
-                >
-                  <div className="flex items-center border border-gray-300 shadow-sm rounded-md">
-                    <span className="flex items-center">
-                      <span className="bg-pink-500 h-full rounded-tl rounded-bl p-1">
-                        <ServerIcon className="h-4 w-4 text-white" />
-                      </span>
-                      <span className="font-light leading-none px-2 group-hover:underline">
-                        {service.data.name} (v{service.data.version})
-                      </span>
-                    </span>{' '}
-                  </div>
-                </a>
-              </li>
-            );
-          })}
-        </ul>
-      );
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('servicesThatReadFromContainer'),
-  }),
-  createBadgesColumn(columnHelper, tableConfiguration),
-  columnHelper.accessor('data.name', {
-    header: () => <span>{tableConfiguration.columns?.actions?.label || 'Actions'}</span>,
-    cell: (info) => {
-      const container = info.row.original;
-      return (
-        <a
-          className="hover:text-primary hover:underline px-4 font-light"
-          href={buildUrl(`/visualiser/${container.collection}/${container.data.id}/${container.data.version}`)}
-        >
-          Visualiser &rarr;
-        </a>
-      );
-    },
-    id: 'actions',
-    meta: {
-      showFilter: false,
-    },
-  }),
-];
diff --git a/eventcatalog/src/components/Tables/columns/DomainTableColumns.tsx b/eventcatalog/src/components/Tables/columns/DomainTableColumns.tsx
deleted file mode 100644
index 790e7af1e..000000000
--- a/eventcatalog/src/components/Tables/columns/DomainTableColumns.tsx
+++ /dev/null
@@ -1,118 +0,0 @@
-import { ServerIcon, RectangleGroupIcon } from '@heroicons/react/20/solid';
-import { createColumnHelper } from '@tanstack/react-table';
-import { filterByName, filterCollectionByName } from '../filters/custom-filters';
-import { buildUrl } from '@utils/url-builder';
-import { createBadgesColumn } from './SharedColumns';
-import type { TData } from '../Table';
-import type { TableConfiguration } from '@types';
-
-const columnHelper = createColumnHelper<TData<'domains'>>();
-
-export const columns = (tableConfiguration: TableConfiguration) => [
-  columnHelper.accessor('data.name', {
-    id: 'name',
-    header: () => <span>{tableConfiguration.columns?.name?.label || 'Domain'}</span>,
-    cell: (info) => {
-      const messageRaw = info.row.original;
-      const color = 'yellow';
-      return (
-        <div className=" group ">
-          <a
-            href={buildUrl(`/docs/${messageRaw.collection}/${messageRaw.data.id}/${messageRaw.data.version}`)}
-            className={`group-hover:text-${color}-500 flex space-x-1 items-center`}
-          >
-            <div className={`flex items-center border border-gray-300 shadow-sm rounded-md group-hover:border-${color}-400`}>
-              <span className="flex items-center">
-                <span className={`bg-${color}-500 group-hover:bg-${color}-600 h-full rounded-tl rounded-bl p-1`}>
-                  <RectangleGroupIcon className="h-4 w-4 text-white" />
-                </span>
-                <span className="leading-none px-2 group-hover:underline group-hover:text-primary font-light">
-                  {messageRaw.data.name} (v{messageRaw.data.version})
-                </span>
-              </span>
-            </div>
-          </a>
-        </div>
-      );
-    },
-    footer: (info) => info.column.id,
-    meta: {
-      filterVariant: 'name',
-    },
-    filterFn: filterByName,
-  }),
-  columnHelper.accessor('data.summary', {
-    id: 'summary',
-    header: () => <span>{tableConfiguration.columns?.summary?.label || 'Summary'}</span>,
-    cell: (info) => (
-      <span className="font-light ">
-        {info.renderValue()} {info.row.original.data.draft ? ' (Draft)' : ''}
-      </span>
-    ),
-    footer: (info) => info.column.id,
-    meta: {
-      showFilter: false,
-      className: 'max-w-md',
-    },
-  }),
-  columnHelper.accessor('data.services', {
-    id: 'services',
-    header: () => <span>Services</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'services',
-    },
-    cell: (info) => {
-      const services = info.getValue();
-      if (services?.length === 0 || !services)
-        return <div className="text-sm text-gray-400/80 text-left italic">Domain has no services.</div>;
-
-      return (
-        <ul>
-          {services.map((consumer) => {
-            const color = 'pink';
-            return (
-              <li key={consumer.data.id} className="py-1 group ">
-                <a
-                  href={buildUrl(`/docs/${consumer.collection}/${consumer.data.id}/${consumer.data.version}`)}
-                  className="group-hover:text-primary flex space-x-1 items-center "
-                >
-                  <div className={`flex items-center border border-gray-300 rounded-md`}>
-                    <span className="flex items-center">
-                      <span className={`bg-${color}-500 h-full rounded-tl rounded-bl p-1`}>
-                        <ServerIcon className="h-4 w-4 text-white" />
-                      </span>
-                      <span className="leading-none px-2 group-hover:underline font-light  ">
-                        {consumer.data.name} (v{consumer.data.version})
-                      </span>
-                    </span>
-                  </div>
-                </a>
-              </li>
-            );
-          })}
-        </ul>
-      );
-    },
-    filterFn: filterCollectionByName('services'),
-  }),
-  createBadgesColumn(columnHelper, tableConfiguration),
-  columnHelper.accessor('data.name', {
-    id: 'actions',
-    header: () => <span>{tableConfiguration.columns?.actions?.label || 'Actions'}</span>,
-    cell: (info) => {
-      const domain = info.row.original;
-      return (
-        <a
-          className="hover:text-primary hover:underline px-4 font-light"
-          href={buildUrl(`/visualiser/${domain.collection}/${domain.data.id}/${domain.data.version}`)}
-        >
-          Visualiser &rarr;
-        </a>
-      );
-    },
-    meta: {
-      showFilter: false,
-    },
-  }),
-];
diff --git a/eventcatalog/src/components/Tables/columns/FlowTableColumns.tsx b/eventcatalog/src/components/Tables/columns/FlowTableColumns.tsx
deleted file mode 100644
index d46fab1a2..000000000
--- a/eventcatalog/src/components/Tables/columns/FlowTableColumns.tsx
+++ /dev/null
@@ -1,84 +0,0 @@
-import { createColumnHelper } from '@tanstack/react-table';
-import { filterByName } from '../filters/custom-filters';
-import { buildUrl } from '@utils/url-builder';
-import { QueueListIcon } from '@heroicons/react/24/solid';
-import { createBadgesColumn } from './SharedColumns';
-import type { TData } from '../Table';
-import type { TableConfiguration } from '@types';
-
-const columnHelper = createColumnHelper<TData<'flows'>>();
-
-export const columns = (tableConfiguration: TableConfiguration) => [
-  columnHelper.accessor('data.name', {
-    id: 'name',
-    header: () => <span>{tableConfiguration.columns?.name?.label || 'Flow'}</span>,
-    cell: (info) => {
-      const flowRaw = info.row.original;
-      const color = 'teal';
-      return (
-        <div className=" group ">
-          <a
-            href={buildUrl(`/docs/${flowRaw.collection}/${flowRaw.data.id}/${flowRaw.data.version}`)}
-            className={`group-hover:text-${color}-500 flex space-x-1 items-center`}
-          >
-            <div className={`flex items-center border border-gray-300 shadow-sm rounded-md group-hover:border-${color}-400`}>
-              <span className="flex items-center">
-                <span className={`bg-${color}-500 group-hover:bg-${color}-600 h-full rounded-tl rounded-bl p-1`}>
-                  <QueueListIcon className="h-4 w-4 text-white" />
-                </span>
-                <span className="leading-none px-2 group-hover:underline group-hover:text-primary font-light">
-                  {flowRaw.data.name} (v{flowRaw.data.version})
-                </span>
-              </span>
-            </div>
-          </a>
-        </div>
-      );
-    },
-    footer: (info) => info.column.id,
-    meta: {
-      filterVariant: 'name',
-    },
-    filterFn: filterByName,
-  }),
-  columnHelper.accessor('data.version', {
-    id: 'version',
-    header: () => <span>{tableConfiguration.columns?.version?.label || 'Version'}</span>,
-    cell: (info) => {
-      const service = info.row.original;
-      return (
-        <div className="text-left font-light">{`v${info.getValue()} ${service.data.latestVersion === service.data.version ? '(latest)' : ''}`}</div>
-      );
-    },
-    footer: (info) => info.column.id,
-  }),
-  columnHelper.accessor('data.summary', {
-    id: 'summary',
-    header: () => <span>{tableConfiguration.columns?.summary?.label || 'Summary'}</span>,
-    cell: (info) => <span className="font-light ">{info.renderValue()}</span>,
-    footer: (info) => info.column.id,
-    meta: {
-      showFilter: false,
-      className: 'max-w-md',
-    },
-  }),
-  createBadgesColumn(columnHelper, tableConfiguration),
-  columnHelper.accessor('data.name', {
-    id: 'actions',
-    header: () => <span>{tableConfiguration.columns?.actions?.label || 'Actions'}</span>,
-    cell: (info) => {
-      const domain = info.row.original;
-      return (
-        <a
-          className="hover:text-primary hover:underline px-4 font-light"
-          href={buildUrl(`/visualiser/${domain.collection}/${domain.data.id}/${domain.data.version}`)}
-        >
-          Visualiser &rarr;
-        </a>
-      );
-    },
-    meta: {
-      showFilter: false,
-    },
-  }),
-];
diff --git a/eventcatalog/src/components/Tables/columns/MessageTableColumns.tsx b/eventcatalog/src/components/Tables/columns/MessageTableColumns.tsx
deleted file mode 100644
index ad8ed307b..000000000
--- a/eventcatalog/src/components/Tables/columns/MessageTableColumns.tsx
+++ /dev/null
@@ -1,175 +0,0 @@
-import { ServerIcon, BoltIcon, ChatBubbleLeftIcon, MagnifyingGlassIcon } from '@heroicons/react/24/solid';
-import { createColumnHelper } from '@tanstack/react-table';
-import { useMemo } from 'react';
-import { filterByName, filterCollectionByName } from '../filters/custom-filters';
-import { buildUrl } from '@utils/url-builder';
-import { createBadgesColumn } from './SharedColumns';
-import type { TData } from '../Table';
-import type { CollectionMessageTypes, TableConfiguration } from '@types';
-
-const columnHelper = createColumnHelper<TData<CollectionMessageTypes>>();
-
-export const getColorAndIconForMessageType = (type: string) => {
-  switch (type) {
-    case 'event':
-      return { color: 'orange', Icon: BoltIcon };
-    case 'command':
-      return { color: 'blue', Icon: ChatBubbleLeftIcon };
-    case 'querie':
-    case 'query':
-      return { color: 'green', Icon: MagnifyingGlassIcon };
-    default:
-      return { color: 'gray', Icon: ChatBubbleLeftIcon };
-  }
-};
-
-export const columns = (tableConfiguration: TableConfiguration) => [
-  columnHelper.accessor('data.name', {
-    id: 'name',
-    header: () => <span>{tableConfiguration.columns?.name?.label || 'Name'}</span>,
-    cell: (info) => {
-      const messageRaw = info.row.original;
-      const type = useMemo(() => messageRaw.collection.slice(0, -1), [messageRaw.collection]);
-      const { color, Icon } = getColorAndIconForMessageType(type);
-      return (
-        <div className=" group ">
-          <a
-            href={buildUrl(`/docs/${messageRaw.collection}/${messageRaw.data.id}/${messageRaw.data.version}`)}
-            className={`group-hover:text-${color}-500 flex space-x-1 items-center`}
-          >
-            <div className={`flex items-center border border-gray-300 shadow-sm rounded-md group-hover:border-${color}-400`}>
-              <span className="flex items-center">
-                <span className={`bg-${color}-500 group-hover:bg-${color}-600 h-full rounded-tl rounded-bl p-1`}>
-                  <Icon className="h-4 w-4 text-white" />
-                </span>
-                <span className="leading-none px-2 group-hover:underline group-hover:text-primary font-light">
-                  {messageRaw.data.name} (v{messageRaw.data.version})
-                </span>
-              </span>
-            </div>
-          </a>
-        </div>
-      );
-    },
-    meta: {
-      filterVariant: 'name',
-    },
-    filterFn: filterByName,
-  }),
-
-  columnHelper.accessor('data.summary', {
-    id: 'summary',
-    header: () => <span>{tableConfiguration.columns?.summary?.label || 'Summary'}</span>,
-    cell: (info) => (
-      <span className="font-light ">
-        {info.renderValue()} {info.row.original.data.draft ? ' (Draft)' : ''}
-      </span>
-    ),
-    footer: (info) => info.column.id,
-    meta: {
-      showFilter: false,
-      className: 'max-w-[200px]',
-    },
-  }),
-
-  columnHelper.accessor('data.producers', {
-    id: 'producers',
-    header: () => <span>{tableConfiguration.columns?.producers?.label || 'Producers'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'producers',
-    },
-    cell: (info) => {
-      const producers = info.getValue();
-      if (producers?.length === 0 || !producers)
-        return <div className="font-light text-sm text-gray-400/60 text-left italic">No producers documented</div>;
-      return (
-        <ul className="">
-          {producers.map((producer, index) => {
-            return (
-              <li className="py-2 group flex items-center space-x-2" key={`${producer.data.id}-${index}`}>
-                <a
-                  href={buildUrl(`/docs/${producer.collection}/${producer.data.id}/${producer.data.version}`)}
-                  className="group-hover:text-primary flex space-x-1 items-center "
-                >
-                  <div className="flex items-center border border-gray-300 shadow-sm rounded-md">
-                    <span className="flex items-center">
-                      <span className="bg-pink-500 h-full rounded-tl rounded-bl p-1">
-                        <ServerIcon className="h-4 w-4 text-white" />
-                      </span>
-                      <span className="font-light leading-none px-2 group-hover:underline">
-                        {producer.data.name} (v{producer.data.version})
-                      </span>
-                    </span>{' '}
-                  </div>
-                </a>
-              </li>
-            );
-          })}
-        </ul>
-      );
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('producers'),
-  }),
-  columnHelper.accessor('data.consumers', {
-    id: 'consumers',
-    header: () => <span>{tableConfiguration.columns?.consumers?.label || 'Consumers'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'consumers',
-    },
-    cell: (info) => {
-      const consumers = info.getValue();
-      if (consumers?.length === 0 || !consumers)
-        return <div className="font-light text-sm text-gray-400/80 text-left italic">No consumers documented</div>;
-
-      return (
-        <ul>
-          {consumers.map((consumer, index) => {
-            return (
-              <li key={`${consumer.data.id}-${index}`} className="py-1 group font-light ">
-                <a
-                  href={buildUrl(`/docs/${consumer.collection}/${consumer.data.id}/${consumer.data.version}`)}
-                  className="group-hover:text-primary flex space-x-1 items-center "
-                >
-                  <div className="flex items-center border border-gray-300 shadow-sm rounded-md">
-                    <span className="flex items-center">
-                      <span className="bg-pink-500 h-full rounded-tl rounded-bl p-1">
-                        <ServerIcon className="h-4 w-4 text-white" />
-                      </span>
-                      <span className="leading-none px-2 group-hover:underline ">
-                        {consumer.data.name} (v{consumer.data.version})
-                      </span>
-                    </span>
-                  </div>
-                </a>
-              </li>
-            );
-          })}
-        </ul>
-      );
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('consumers'),
-  }),
-  createBadgesColumn(columnHelper, tableConfiguration),
-  columnHelper.accessor('data.name', {
-    id: 'actions',
-    header: () => <span>{tableConfiguration.columns?.actions?.label || 'Actions'}</span>,
-    cell: (info) => {
-      const domain = info.row.original;
-      return (
-        <a
-          className="hover:text-primary hover:underline px-4 font-light"
-          href={buildUrl(`/visualiser/${domain.collection}/${domain.data.id}/${domain.data.version}`)}
-        >
-          Visualiser &rarr;
-        </a>
-      );
-    },
-    meta: {
-      showFilter: false,
-    },
-  }),
-];
diff --git a/eventcatalog/src/components/Tables/columns/ServiceTableColumns.tsx b/eventcatalog/src/components/Tables/columns/ServiceTableColumns.tsx
deleted file mode 100644
index ffe2f32a6..000000000
--- a/eventcatalog/src/components/Tables/columns/ServiceTableColumns.tsx
+++ /dev/null
@@ -1,201 +0,0 @@
-import { ServerIcon } from '@heroicons/react/24/solid';
-import { createColumnHelper } from '@tanstack/react-table';
-import { useMemo, useState } from 'react';
-import { filterByName, filterCollectionByName } from '../filters/custom-filters';
-import { buildUrl } from '@utils/url-builder';
-import { getColorAndIconForCollection } from '@utils/collections/icons';
-import { createBadgesColumn } from './SharedColumns';
-import type { TData } from '../Table';
-import type { TableConfiguration } from '@types';
-const columnHelper = createColumnHelper<TData<'services'>>();
-
-export const columns = (tableConfiguration: TableConfiguration) => [
-  columnHelper.accessor('data.name', {
-    id: 'name',
-    header: () => <span>{tableConfiguration.columns?.name?.label || 'Service'}</span>,
-    cell: (info) => {
-      const messageRaw = info.row.original;
-      const color = 'pink';
-      return (
-        <div className="group font-light">
-          <a
-            href={buildUrl(`/docs/${messageRaw.collection}/${messageRaw.data.id}/${messageRaw.data.version}`)}
-            className={`group-hover:text-${color}-500 flex space-x-1 items-center`}
-          >
-            <div className={`flex items-center border border-gray-300 shadow-sm rounded-md group-hover:border-${color}-400`}>
-              <span className="flex items-center">
-                <span className={`bg-${color}-500 group-hover:bg-${color}-600 h-full rounded-tl rounded-bl p-1`}>
-                  <ServerIcon className="h-4 w-4 text-white" />
-                </span>
-                <span className="leading-none px-2 group-hover:underline group-hover:text-primary">
-                  {messageRaw.data.name} (v{messageRaw.data.version})
-                </span>
-              </span>
-            </div>
-          </a>
-        </div>
-      );
-    },
-    meta: {
-      filterVariant: 'name',
-    },
-    filterFn: filterByName,
-  }),
-  columnHelper.accessor('data.summary', {
-    id: 'summary',
-    header: () => <span>{tableConfiguration.columns?.summary?.label || 'Summary'}</span>,
-    cell: (info) => (
-      <span className="font-light ">
-        {info.renderValue()} {info.row.original.data.draft ? ' (Draft)' : ''}
-      </span>
-    ),
-    footer: (info) => info.column.id,
-    meta: {
-      showFilter: false,
-      className: 'max-w-md',
-    },
-  }),
-  columnHelper.accessor('data.receives', {
-    id: 'receives',
-    header: () => <span>Receives</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'receives',
-    },
-    cell: (info) => {
-      const receives = info.getValue() || [];
-      const isExpandable = receives?.length > 10;
-      const isOpen = isExpandable ? receives?.length < 10 : true;
-      const [isExpanded, setIsExpanded] = useState(isOpen);
-
-      const receiversWithIcons = useMemo(
-        () =>
-          receives?.map((consumer) => {
-            return {
-              ...consumer,
-              ...getColorAndIconForCollection(consumer.collection),
-            };
-          }) || [],
-        [receives]
-      );
-
-      if (receives?.length === 0 || !receives)
-        return <div className="text-sm text-gray-400/80 text-left italic">Service receives no messages.</div>;
-
-      return (
-        <div>
-          {isExpandable && (
-            <button onClick={() => setIsExpanded(!isExpanded)} className="mb-2 text-sm text-gray-600 hover:text-gray-900">
-              {isExpanded ? '▼' : '▶'} {receives.length} message{receives.length !== 1 ? 's' : ''}
-            </button>
-          )}
-          {isExpanded && (
-            <ul>
-              {receiversWithIcons.map((consumer, index: number) => (
-                <li key={`${consumer.data.id}-${index}`} className="py-1 group font-light ">
-                  <a
-                    href={buildUrl(`/docs/${consumer.collection}/${consumer.data.id}/${consumer.data.version}`)}
-                    className="group-hover:text-primary flex space-x-1 items-center "
-                  >
-                    <div className={`flex items-center border border-gray-300 shadow-sm rounded-md`}>
-                      <span className="flex items-center">
-                        <span className={`bg-${consumer.color}-500 h-full rounded-tl rounded-bl p-1`}>
-                          <consumer.Icon className="h-4 w-4 text-white" />
-                        </span>
-                        <span className="leading-none px-2 group-hover:underline ">
-                          {consumer.data.name} (v{consumer.data.version})
-                        </span>
-                      </span>
-                    </div>
-                  </a>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-      );
-    },
-    filterFn: filterCollectionByName('receives'),
-  }),
-  columnHelper.accessor('data.sends', {
-    id: 'sends',
-    header: () => <span>Sends</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'sends',
-    },
-    cell: (info) => {
-      const sends = info.getValue() || [];
-      const isExpandable = sends?.length > 10;
-      const isOpen = isExpandable ? sends?.length < 10 : true;
-      const [isExpanded, setIsExpanded] = useState(isOpen);
-
-      if (sends?.length === 0 || !sends)
-        return <div className="text-sm text-gray-400/80 text-left italic">Service sends no messages.</div>;
-
-      const sendersWithIcons = useMemo(
-        () =>
-          sends?.map((sender) => {
-            return {
-              ...sender,
-              ...getColorAndIconForCollection(sender.collection),
-            };
-          }) || [],
-        [sends]
-      );
-
-      return (
-        <div>
-          {isExpandable && (
-            <button onClick={() => setIsExpanded(!isExpanded)} className="mb-2 text-sm text-gray-600 hover:text-gray-900">
-              {isExpanded ? '▼' : '▶'} {sends.length} message{sends.length !== 1 ? 's' : ''}
-            </button>
-          )}
-          {isExpanded && (
-            <ul>
-              {sendersWithIcons.map((sender, index) => (
-                <li key={`${sender.data.id}-${index}`} className="py-1 group font-light">
-                  <a
-                    href={buildUrl(`/docs/${sender.collection}/${sender.data.id}/${sender.data.version}`)}
-                    className="group-hover:text-primary flex space-x-1 items-center "
-                  >
-                    <div className={`flex items-center border border-gray-300 shadow-sm rounded-md`}>
-                      <span className="flex items-center">
-                        <span className={`bg-${sender.color}-500 h-full rounded-tl rounded-bl p-1`}>
-                          <sender.Icon className="h-4 w-4 text-white" />
-                        </span>
-                        <span className="leading-none px-2 group-hover:underline ">
-                          {sender.data.name} (v{sender.data.version})
-                        </span>
-                      </span>
-                    </div>
-                  </a>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-      );
-    },
-    filterFn: filterCollectionByName('sends'),
-  }),
-  createBadgesColumn(columnHelper, tableConfiguration),
-  columnHelper.accessor('data.name', {
-    id: 'actions',
-    header: () => <span>{tableConfiguration.columns?.actions?.label || 'Actions'}</span>,
-    cell: (info) => {
-      const domain = info.row.original;
-      return (
-        <a
-          className="hover:text-primary hover:underline px-4 font-light"
-          href={buildUrl(`/visualiser/${domain.collection}/${domain.data.id}/${domain.data.version}`)}
-        >
-          Visualiser &rarr;
-        </a>
-      );
-    },
-    meta: {
-      showFilter: false,
-    },
-  }),
-];
diff --git a/eventcatalog/src/components/Tables/columns/SharedColumns.tsx b/eventcatalog/src/components/Tables/columns/SharedColumns.tsx
deleted file mode 100644
index deea4bcb2..000000000
--- a/eventcatalog/src/components/Tables/columns/SharedColumns.tsx
+++ /dev/null
@@ -1,58 +0,0 @@
-import { createColumnHelper } from '@tanstack/react-table';
-import { Tag } from 'lucide-react';
-import { filterByBadge } from '../filters/custom-filters';
-import type { TCollectionTypes, TData } from '../Table';
-import { getIcon } from '@utils/badges';
-import type { TableConfiguration } from '@types';
-
-export const createBadgesColumn = <T extends { data: Pick<TData<U>['data'], 'badges'> }, U extends TCollectionTypes>(
-  columnHelper: ReturnType<typeof createColumnHelper<T>>,
-  tableConfiguration: TableConfiguration
-) => {
-  return columnHelper.accessor((row) => row.data.badges, {
-    id: 'badges',
-    header: () => <span>{tableConfiguration.columns?.badges?.label || 'Badges'}</span>,
-    cell: (info) => {
-      const item = info.row.original;
-      const badges = item.data.badges || [];
-
-      if (badges?.length === 0 || !badges)
-        return <div className="font-light text-sm text-gray-400/60 text-left italic">No badges documented</div>;
-
-      return (
-        <ul>
-          {badges.map((badge, index) => {
-            return (
-              <li key={`${badge.id}-${index}`} className="py-1 group font-light ">
-                <div className="group-hover:text-primary flex space-x-1 items-center ">
-                  <div className="flex items-center border border-gray-300 shadow-sm rounded-md">
-                    <span className="flex items-center">
-                      <span className={`bg-${badge.backgroundColor}-500 h-full rounded-tl rounded-bl p-1`}>
-                        {(() => {
-                          if (badge.icon) {
-                            const IconComponent = getIcon(badge.icon);
-                            return IconComponent ? (
-                              <IconComponent className="h-4 w-4 text-white" />
-                            ) : (
-                              <Tag className="h-4 w-4 text-white" />
-                            );
-                          }
-                          return <Tag className="h-4 w-4 text-white" />;
-                        })()}
-                      </span>
-                      <span className="leading-none px-2 group-hover:underline ">{badge.content}</span>
-                    </span>
-                  </div>
-                </div>
-              </li>
-            );
-          })}
-        </ul>
-      );
-    },
-    meta: {
-      filterVariant: 'badges',
-    },
-    filterFn: filterByBadge,
-  });
-};
diff --git a/eventcatalog/src/components/Tables/columns/TeamsTableColumns.tsx b/eventcatalog/src/components/Tables/columns/TeamsTableColumns.tsx
deleted file mode 100644
index d025046de..000000000
--- a/eventcatalog/src/components/Tables/columns/TeamsTableColumns.tsx
+++ /dev/null
@@ -1,278 +0,0 @@
-import { MagnifyingGlassIcon } from '@heroicons/react/24/solid';
-import { createColumnHelper } from '@tanstack/react-table';
-import { useMemo, useState } from 'react';
-import { filterByName, filterCollectionByName } from '../filters/custom-filters';
-import { buildUrl } from '@utils/url-builder';
-import type { TData } from '../Table';
-import type { CollectionUserTypes } from '@types';
-import type { CollectionEntry } from 'astro:content';
-import { ServerIcon, BoltIcon, ChatBubbleLeftIcon } from '@heroicons/react/24/solid';
-import type { TableConfiguration } from '@types';
-const columnHelper = createColumnHelper<TData<CollectionUserTypes>>();
-
-export const columns = (tableConfiguration: TableConfiguration) => [
-  columnHelper.accessor('data.name', {
-    id: 'name',
-    header: () => <span>{tableConfiguration.columns?.name?.label || 'Name'}</span>,
-    cell: (info) => {
-      const messageRaw = info.row.original;
-      const type = useMemo(() => messageRaw.collection.slice(0, -1), [messageRaw.collection]);
-      return (
-        <div className=" group ">
-          <a
-            href={buildUrl(`/docs/${messageRaw.collection}/${messageRaw.data.id}`)}
-            className={`group-hover:text-pink-500 flex space-x-1 items-center`}
-          >
-            <div className={`flex items-center  rounded-md group-hover:border-pink-400`}>
-              <span className="flex items-center">
-                <span className="flex flex-col leading-none px-2 group-hover:underline group-hover:text-primary font-light">
-                  <span className="font-semibold">{messageRaw.data.name}</span>
-                </span>
-              </span>
-            </div>
-          </a>
-        </div>
-      );
-    },
-    meta: {
-      filterVariant: 'name',
-      filteredItemHasVersion: false,
-    },
-    filterFn: filterByName,
-  }),
-
-  columnHelper.accessor('data.ownedEvents', {
-    id: 'ownedEvents',
-    header: () => <span>{tableConfiguration.columns?.ownedEvents?.label || 'Owned events'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'ownedEvents',
-    },
-    cell: (info) => {
-      const events = info.getValue();
-      if (events?.length === 0 || !events)
-        return <div className="font-light text-sm text-gray-400/80 text-left italic">Team owns no events</div>;
-
-      const isExpandable = events?.length > 10;
-      const isOpen = isExpandable ? events?.length < 10 : true;
-      const [isExpanded, setIsExpanded] = useState(isOpen);
-
-      return (
-        <div>
-          {isExpandable && (
-            <button onClick={() => setIsExpanded(!isExpanded)} className="mb-2 text-sm text-gray-600 hover:text-gray-900">
-              {isExpanded ? '▼' : '▶'} {events.length} event{events.length !== 1 ? 's' : ''}
-            </button>
-          )}
-          {isExpanded && (
-            <ul>
-              {events.map((event: CollectionEntry<'events'>, index: number) => (
-                <li key={`${event.data.id}-${index}`} className="py-1 group font-light ">
-                  <a
-                    href={buildUrl(`/docs/${event.collection}/${event.data.id}/${event.data.version}`)}
-                    className="group-hover:text-primary flex space-x-1 items-center "
-                  >
-                    <div className={`flex items-center border border-gray-300 shadow-sm rounded-md`}>
-                      <span className="flex items-center">
-                        <span className={`bg-orange-500 h-full rounded-tl rounded-bl p-1`}>
-                          <BoltIcon className="h-4 w-4 text-white" />
-                        </span>
-                        <span className="leading-none px-2 group-hover:underline ">
-                          {event.data.name} (v{event.data.version})
-                        </span>
-                      </span>
-                    </div>
-                  </a>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-      );
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('ownedEvents'),
-  }),
-
-  columnHelper.accessor('data.ownedCommands', {
-    id: 'ownedCommands',
-    header: () => <span>{tableConfiguration.columns?.ownedCommands?.label || 'Owned commands'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'ownedCommands',
-    },
-    cell: (info) => {
-      const commands = info.getValue();
-      if (commands?.length === 0 || !commands)
-        return <div className="font-light text-sm text-gray-400/60 text-left italic">Team owns no commands</div>;
-
-      const isExpandable = commands?.length > 10;
-      const isOpen = isExpandable ? commands?.length < 10 : true;
-      const [isExpanded, setIsExpanded] = useState(isOpen);
-
-      return (
-        <div>
-          {isExpandable && (
-            <button onClick={() => setIsExpanded(!isExpanded)} className="mb-2 text-sm text-gray-600 hover:text-gray-900">
-              {isExpanded ? '▼' : '▶'} {commands.length} command{commands.length !== 1 ? 's' : ''}
-            </button>
-          )}
-          {isExpanded && (
-            <ul>
-              {commands.map((command: CollectionEntry<'commands'>, index: number) => (
-                <li key={`${command.data.id}-${index}`} className="py-1 group font-light ">
-                  <a
-                    href={buildUrl(`/docs/${command.collection}/${command.data.id}/${command.data.version}`)}
-                    className="group-hover:text-primary flex space-x-1 items-center "
-                  >
-                    <div className={`flex items-center border border-gray-300 shadow-sm rounded-md`}>
-                      <span className="flex items-center">
-                        <span className={`bg-blue-500 h-full rounded-tl rounded-bl p-1`}>
-                          <ChatBubbleLeftIcon className="h-4 w-4 text-white" />
-                        </span>
-                        <span className="leading-none px-2 group-hover:underline ">
-                          {command.data.name} (v{command.data.version})
-                        </span>
-                      </span>
-                    </div>
-                  </a>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-      );
-
-      // return commands.length;
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('ownedCommands'),
-  }),
-
-  columnHelper.accessor('data.ownedQueries', {
-    id: 'ownedQueries',
-    header: () => <span>{tableConfiguration.columns?.ownedQueries?.label || 'Owned queries'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'ownedQueries',
-    },
-    cell: (info) => {
-      const queries = info.getValue();
-      if (queries?.length === 0 || !queries)
-        return <div className="font-light text-sm text-gray-400/60 text-left italic">Team owns no queries</div>;
-
-      const isExpandable = queries?.length > 10;
-      const isOpen = isExpandable ? queries?.length < 10 : true;
-      const [isExpanded, setIsExpanded] = useState(isOpen);
-
-      return (
-        <div>
-          {isExpandable && (
-            <button onClick={() => setIsExpanded(!isExpanded)} className="mb-2 text-sm text-gray-600 hover:text-gray-900">
-              {isExpanded ? '▼' : '▶'} {queries.length} query{queries.length !== 1 ? 's' : ''}
-            </button>
-          )}
-          {isExpanded && (
-            <ul>
-              {queries.map((query: CollectionEntry<'queries'>, index: number) => (
-                <li key={`${query.data.id}-${index}`} className="py-1 group font-light ">
-                  <a
-                    href={buildUrl(`/docs/${query.collection}/${query.data.id}/${query.data.version}`)}
-                    className="group-hover:text-primary flex space-x-1 items-center "
-                  >
-                    <div className={`flex items-center border border-gray-300 shadow-sm rounded-md`}>
-                      <span className="flex items-center">
-                        <span className={`bg-blue-500 h-full rounded-tl rounded-bl p-1`}>
-                          <ChatBubbleLeftIcon className="h-4 w-4 text-white" />
-                        </span>
-                        <span className="leading-none px-2 group-hover:underline ">
-                          {query.data.name} (v{query.data.version})
-                        </span>
-                      </span>
-                    </div>
-                  </a>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-      );
-
-      // return commands.length;
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('ownedCommands'),
-  }),
-
-  columnHelper.accessor('data.ownedServices', {
-    id: 'ownedServices',
-    header: () => <span>{tableConfiguration.columns?.ownedServices?.label || 'Owned Services'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'ownedServices',
-    },
-    cell: (info) => {
-      const services = info.getValue();
-      if (services?.length === 0 || !services)
-        return <div className="font-light text-sm text-gray-400/80 text-left italic">Team owns no services</div>;
-
-      const isExpandable = services?.length > 10;
-      const isOpen = isExpandable ? services?.length < 10 : true;
-      const [isExpanded, setIsExpanded] = useState(isOpen);
-
-      return (
-        <div>
-          {isExpandable && (
-            <button onClick={() => setIsExpanded(!isExpanded)} className="mb-2 text-sm text-gray-600 hover:text-gray-900">
-              {isExpanded ? '▼' : '▶'} {services.length} service{services.length !== 1 ? 's' : ''}
-            </button>
-          )}
-          {isExpanded && (
-            <ul>
-              {services.map((service: CollectionEntry<'services'>, index: number) => (
-                <li key={`${service.data.id}-${index}`} className="py-1 group font-light ">
-                  <a
-                    href={buildUrl(`/docs/${service.collection}/${service.data.id}/${service.data.version}`)}
-                    className="group-hover:text-primary flex space-x-1 items-center "
-                  >
-                    <div className={`flex items-center border border-gray-300 shadow-sm rounded-md`}>
-                      <span className="flex items-center">
-                        <span className={`bg-green-500 h-full rounded-tl rounded-bl p-1`}>
-                          <ServerIcon className="h-4 w-4 text-white" />
-                        </span>
-                        <span className="leading-none px-2 group-hover:underline ">
-                          {service.data.name} (v{service.data.version})
-                        </span>
-                      </span>
-                    </div>
-                  </a>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-      );
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('ownedServices'),
-  }),
-
-  columnHelper.accessor('data.name', {
-    header: () => <span>{tableConfiguration.columns?.actions?.label || 'Actions'}</span>,
-    cell: (info) => {
-      const domain = info.row.original;
-      return (
-        <a
-          className="hover:text-primary hover:underline px-4 font-light"
-          href={buildUrl(`/docs/${domain.collection}/${domain.data.id}`)}
-        >
-          View &rarr;
-        </a>
-      );
-    },
-    id: 'actions',
-    meta: {
-      showFilter: false,
-    },
-  }),
-];
diff --git a/eventcatalog/src/components/Tables/columns/UserTableColumns.tsx b/eventcatalog/src/components/Tables/columns/UserTableColumns.tsx
deleted file mode 100644
index fa7243331..000000000
--- a/eventcatalog/src/components/Tables/columns/UserTableColumns.tsx
+++ /dev/null
@@ -1,329 +0,0 @@
-import { createColumnHelper } from '@tanstack/react-table';
-import { useMemo, useState } from 'react';
-import { filterByName, filterCollectionByName } from '../filters/custom-filters';
-import { buildUrl } from '@utils/url-builder';
-import type { TData } from '../Table';
-import type { CollectionUserTypes } from '@types';
-import { User, Users } from 'lucide-react';
-import type { CollectionEntry } from 'astro:content';
-import { ServerIcon, BoltIcon, ChatBubbleLeftIcon, MagnifyingGlassIcon } from '@heroicons/react/24/solid';
-import type { TableConfiguration } from '@types';
-const columnHelper = createColumnHelper<TData<CollectionUserTypes>>();
-
-export const columns = (tableConfiguration: TableConfiguration) => [
-  columnHelper.accessor('data.name', {
-    id: 'name',
-    header: () => <span>{tableConfiguration.columns?.name?.label || 'Name'}</span>,
-    cell: (info) => {
-      const messageRaw = info.row.original;
-      const type = useMemo(() => messageRaw.collection.slice(0, -1), [messageRaw.collection]);
-      return (
-        <div className=" group ">
-          <a
-            href={buildUrl(`/docs/${messageRaw.collection}/${messageRaw.data.id}`)}
-            className={`group-hover:text-gray-500 flex space-x-1 items-center`}
-          >
-            <div className={`flex items-center  rounded-md group-hover:border-gray-400`}>
-              <span className="flex items-center">
-                <span className="flex flex-col leading-none px-2 group-hover:underline group-hover:text-primary font-light">
-                  <span className="font-semibold">{messageRaw.data.name}</span>
-                </span>
-              </span>
-            </div>
-          </a>
-        </div>
-      );
-    },
-    meta: {
-      filterVariant: 'name',
-      filteredItemHasVersion: false,
-    },
-    filterFn: filterByName,
-  }),
-
-  columnHelper.accessor('data.ownedEvents', {
-    id: 'ownedEvents',
-    header: () => <span>{tableConfiguration.columns?.ownedEvents?.label || 'Owned events'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'ownedEvents',
-    },
-    cell: (info) => {
-      const events = info.getValue();
-      if (events?.length === 0 || !events)
-        return <div className="font-light text-sm text-gray-400/80 text-left italic">User owns no events</div>;
-
-      const isExpandable = events?.length > 10;
-      const isOpen = isExpandable ? events?.length < 10 : true;
-      const [isExpanded, setIsExpanded] = useState(isOpen);
-
-      return (
-        <div>
-          {isExpandable && (
-            <button onClick={() => setIsExpanded(!isExpanded)} className="mb-2 text-sm text-gray-600 hover:text-gray-900">
-              {isExpanded ? '▼' : '▶'} {events.length} event{events.length !== 1 ? 's' : ''}
-            </button>
-          )}
-          {isExpanded && (
-            <ul>
-              {events.map((event: CollectionEntry<'events'>, index: number) => (
-                <li key={`${event.data.id}-${index}`} className="py-1 group font-light ">
-                  <a
-                    href={buildUrl(`/docs/${event.collection}/${event.data.id}/${event.data.version}`)}
-                    className="group-hover:text-primary flex space-x-1 items-center "
-                  >
-                    <div className={`flex items-center border border-gray-300 shadow-sm rounded-md`}>
-                      <span className="flex items-center">
-                        <span className={`bg-orange-500 h-full rounded-tl rounded-bl p-1`}>
-                          <BoltIcon className="h-4 w-4 text-white" />
-                        </span>
-                        <span className="leading-none px-2 group-hover:underline ">
-                          {event.data.name} (v{event.data.version})
-                        </span>
-                      </span>
-                    </div>
-                  </a>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-      );
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('ownedEvents'),
-  }),
-
-  columnHelper.accessor('data.ownedCommands', {
-    id: 'ownedCommands',
-    header: () => <span>{tableConfiguration.columns?.ownedCommands?.label || 'Owned commands'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'ownedCommands',
-    },
-    cell: (info) => {
-      const commands = info.getValue();
-      if (commands?.length === 0 || !commands)
-        return <div className="font-light text-sm text-gray-400/60 text-left italic">User owns no commands</div>;
-
-      const isExpandable = commands?.length > 10;
-      const isOpen = isExpandable ? commands?.length < 10 : true;
-      const [isExpanded, setIsExpanded] = useState(isOpen);
-
-      return (
-        <div>
-          {isExpandable && (
-            <button onClick={() => setIsExpanded(!isExpanded)} className="mb-2 text-sm text-gray-600 hover:text-gray-900">
-              {isExpanded ? '▼' : '▶'} {commands.length} command{commands.length !== 1 ? 's' : ''}
-            </button>
-          )}
-          {isExpanded && (
-            <ul>
-              {commands.map((command: CollectionEntry<'commands'>, index: number) => (
-                <li key={`${command.data.id}-${index}`} className="py-1 group font-light ">
-                  <a
-                    href={buildUrl(`/docs/${command.collection}/${command.data.id}/${command.data.version}`)}
-                    className="group-hover:text-primary flex space-x-1 items-center "
-                  >
-                    <div className={`flex items-center border border-gray-300 shadow-sm rounded-md`}>
-                      <span className="flex items-center">
-                        <span className={`bg-blue-500 h-full rounded-tl rounded-bl p-1`}>
-                          <ChatBubbleLeftIcon className="h-4 w-4 text-white" />
-                        </span>
-                        <span className="leading-none px-2 group-hover:underline ">
-                          {command.data.name} (v{command.data.version})
-                        </span>
-                      </span>
-                    </div>
-                  </a>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-      );
-
-      // return commands.length;
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('ownedCommands'),
-  }),
-
-  columnHelper.accessor('data.ownedQueries', {
-    id: 'ownedQueries',
-    header: () => <span>{tableConfiguration.columns?.ownedQueries?.label || 'Owned queries'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'ownedQueries',
-    },
-    cell: (info) => {
-      const queries = info.getValue();
-      if (queries?.length === 0 || !queries)
-        return <div className="font-light text-sm text-gray-400/60 text-left italic">User owns no queries</div>;
-
-      const isExpandable = queries?.length > 10;
-      const isOpen = isExpandable ? queries?.length < 10 : true;
-      const [isExpanded, setIsExpanded] = useState(isOpen);
-
-      return (
-        <div>
-          {isExpandable && (
-            <button onClick={() => setIsExpanded(!isExpanded)} className="mb-2 text-sm text-gray-600 hover:text-gray-900">
-              {isExpanded ? '▼' : '▶'} {queries.length} query{queries.length !== 1 ? 's' : ''}
-            </button>
-          )}
-          {isExpanded && (
-            <ul>
-              {queries.map((query: CollectionEntry<'queries'>, index: number) => (
-                <li key={`${query.data.id}-${index}`} className="py-1 group font-light ">
-                  <a
-                    href={buildUrl(`/docs/${query.collection}/${query.data.id}/${query.data.version}`)}
-                    className="group-hover:text-primary flex space-x-1 items-center "
-                  >
-                    <div className={`flex items-center border border-gray-300 shadow-sm rounded-md h-full`}>
-                      <span className="flex items-center">
-                        <span className={`bg-green-500 flex rounded-tl rounded-bl p-1 h-full`}>
-                          <MagnifyingGlassIcon className="h-4 w-4 text-white" />
-                        </span>
-                        <span className="leading-none px-2 group-hover:underline ">
-                          {query.data.name} (v{query.data.version})
-                        </span>
-                      </span>
-                    </div>
-                  </a>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-      );
-
-      // return commands.length;
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('ownedCommands'),
-  }),
-
-  columnHelper.accessor('data.ownedServices', {
-    id: 'ownedServices',
-    header: () => <span>{tableConfiguration.columns?.ownedServices?.label || 'Owned Services'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'ownedServices',
-    },
-    cell: (info) => {
-      const services = info.getValue();
-      if (services?.length === 0 || !services)
-        return <div className="font-light text-sm text-gray-400/80 text-left italic">User owns no services</div>;
-
-      const isExpandable = services?.length > 10;
-      const isOpen = isExpandable ? services?.length < 10 : true;
-      const [isExpanded, setIsExpanded] = useState(isOpen);
-
-      return (
-        <div>
-          {isExpandable && (
-            <button onClick={() => setIsExpanded(!isExpanded)} className="mb-2 text-sm text-gray-600 hover:text-gray-900">
-              {isExpanded ? '▼' : '▶'} {services.length} service{services.length !== 1 ? 's' : ''}
-            </button>
-          )}
-          {isExpanded && (
-            <ul>
-              {services.map((service: CollectionEntry<'services'>, index: number) => (
-                <li key={`${service.data.id}-${index}`} className="py-1 group font-light ">
-                  <a
-                    href={buildUrl(`/docs/${service.collection}/${service.data.id}/${service.data.version}`)}
-                    className="group-hover:text-primary flex space-x-1 items-center "
-                  >
-                    <div className={`flex items-center border border-gray-300 shadow-sm rounded-md`}>
-                      <span className="flex items-center">
-                        <span className={`bg-green-500 h-full rounded-tl rounded-bl p-1`}>
-                          <ServerIcon className="h-4 w-4 text-white" />
-                        </span>
-                        <span className="leading-none px-2 group-hover:underline ">
-                          {service.data.name} (v{service.data.version})
-                        </span>
-                      </span>
-                    </div>
-                  </a>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-      );
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('ownedServices'),
-  }),
-  columnHelper.accessor('data.associatedTeams', {
-    id: 'associatedTeams',
-    header: () => <span>{tableConfiguration.columns?.associatedTeams?.label || 'Teams'}</span>,
-    meta: {
-      filterVariant: 'collection',
-      collectionFilterKey: 'associatedTeams',
-      filteredItemHasVersion: false,
-    },
-    cell: (info) => {
-      const teams = info.getValue();
-
-      const isExpandable = teams?.length > 10;
-      const isOpen = isExpandable ? teams?.length < 10 : true;
-      const [isExpanded, setIsExpanded] = useState(isOpen);
-
-      if (teams?.length === 0 || !teams)
-        return <div className="font-light text-sm text-gray-400/80 text-left italic">User is not associated with any teams</div>;
-
-      return (
-        <div>
-          {isExpandable && (
-            <button onClick={() => setIsExpanded(!isExpanded)} className="mb-2 text-sm text-gray-600 hover:text-gray-900">
-              {isExpanded ? '▼' : '▶'} {teams.length} team{teams.length !== 1 ? 's' : ''}
-            </button>
-          )}
-          {isExpanded && (
-            <ul>
-              {teams.map((team: CollectionEntry<'teams'>, index: number) => (
-                <li key={`${team.data.id}-${index}`} className="py-1 group font-light ">
-                  <a
-                    href={buildUrl(`/docs/teams/${team.data.id}`)}
-                    className="group-hover:text-primary flex space-x-1 items-center "
-                  >
-                    <div className={`flex items-center border border-gray-300 shadow-sm rounded-md`}>
-                      <span className="flex items-center">
-                        <span className={`bg-pink-500 h-full rounded-tl rounded-bl p-1`}>
-                          <Users className="h-4 w-4 text-white" />
-                        </span>
-                        <span className="leading-none px-2 group-hover:underline ">{team.data.name}</span>
-                      </span>
-                    </div>
-                  </a>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-      );
-    },
-    footer: (info) => info.column.id,
-    filterFn: filterCollectionByName('associatedTeams'),
-  }),
-  columnHelper.accessor('data.name', {
-    header: () => <span>{tableConfiguration.columns?.actions?.label || 'Actions'}</span>,
-    cell: (info) => {
-      const domain = info.row.original;
-      return (
-        <a
-          className="hover:text-primary hover:underline px-4 font-light"
-          href={buildUrl(`/docs/${domain.collection}/${domain.data.id}`)}
-        >
-          View &rarr;
-        </a>
-      );
-    },
-    id: 'actions',
-    meta: {
-      showFilter: false,
-    },
-  }),
-];
diff --git a/eventcatalog/src/components/TreeView/index.tsx b/eventcatalog/src/components/TreeView/index.tsx
deleted file mode 100644
index 570b724b1..000000000
--- a/eventcatalog/src/components/TreeView/index.tsx
+++ /dev/null
@@ -1,328 +0,0 @@
-import React, { useCallback, useEffect } from 'react';
-import classes from './styles.module.css';
-import { useSlots } from './useSlots';
-import { ChevronDownIcon, ChevronRightIcon } from 'lucide-react';
-
-// ----------------------------------------------------------------------------
-// Context
-
-const RootContext = React.createContext<{
-  // We cache the expanded state of tree items so we can preserve the state
-  // across remounts. This is necessary because we unmount tree items
-  // when their parent is collapsed.
-  expandedStateCache: React.RefObject<Map<string, boolean> | null>;
-}>({
-  expandedStateCache: { current: new Map() },
-});
-
-const ItemContext = React.createContext<{
-  level: number;
-  isExpanded: boolean;
-}>({
-  level: 1,
-  isExpanded: false,
-});
-
-// ----------------------------------------------------------------------------
-// TreeView
-
-export type TreeViewProps = {
-  'aria-label'?: React.AriaAttributes['aria-label'];
-  'aria-labelledby'?: React.AriaAttributes['aria-labelledby'];
-  children: React.ReactNode;
-  flat?: boolean;
-  truncate?: boolean;
-  style?: React.CSSProperties;
-};
-
-/* Size of toggle icon in pixels. */
-const TOGGLE_ICON_SIZE = 12;
-
-const Root: React.FC<TreeViewProps> = ({
-  'aria-label': ariaLabel,
-  'aria-labelledby': ariaLabelledby,
-  children,
-  flat,
-  truncate = true,
-  style,
-}) => {
-  const containerRef = React.useRef<HTMLUListElement>(null);
-  const mouseDownRef = React.useRef<boolean>(false);
-
-  const onMouseDown = useCallback(() => {
-    mouseDownRef.current = true;
-  }, []);
-
-  useEffect(() => {
-    function onMouseUp() {
-      mouseDownRef.current = false;
-    }
-    document.addEventListener('mouseup', onMouseUp);
-    return () => {
-      document.removeEventListener('mouseup', onMouseUp);
-    };
-  }, []);
-
-  const expandedStateCache = React.useRef<Map<string, boolean> | null>(null);
-
-  if (expandedStateCache.current === null) {
-    expandedStateCache.current = new Map();
-  }
-
-  return (
-    <RootContext.Provider
-      value={{
-        expandedStateCache,
-      }}
-    >
-      <ul
-        ref={containerRef}
-        role="tree"
-        aria-label={ariaLabel}
-        aria-labelledby={ariaLabelledby}
-        data-omit-spacer={flat}
-        data-truncate-text={truncate || false}
-        onMouseDown={onMouseDown}
-        className={classes.TreeViewRootUlStyles}
-        style={style}
-      >
-        {children}
-      </ul>
-    </RootContext.Provider>
-  );
-};
-
-Root.displayName = 'TreeView';
-
-// ----------------------------------------------------------------------------
-// TreeView.Item
-
-export type TreeViewItemProps = {
-  id: string;
-  children: React.ReactNode;
-  current?: boolean;
-  defaultExpanded?: boolean;
-  onSelect?: (event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>) => void;
-};
-
-const Item = React.forwardRef<HTMLElement, TreeViewItemProps>(
-  ({ id: itemId, current: isCurrentItem = false, defaultExpanded, onSelect, children }, ref) => {
-    const [slots, rest] = useSlots(children, {
-      leadingVisual: LeadingVisual,
-    });
-    const { expandedStateCache } = React.useContext(RootContext);
-
-    const [isExpanded, setIsExpanded] = React.useState(
-      expandedStateCache.current?.get(itemId) ?? defaultExpanded ?? isCurrentItem
-    );
-    const { level } = React.useContext(ItemContext);
-    const { hasSubTree, subTree, childrenWithoutSubTree } = useSubTree(rest);
-    const [isFocused, setIsFocused] = React.useState(false);
-
-    // Set the expanded state and cache it
-    const setIsExpandedWithCache = React.useCallback(
-      (newIsExpanded: boolean) => {
-        setIsExpanded(newIsExpanded);
-        expandedStateCache.current?.set(itemId, newIsExpanded);
-      },
-      [itemId, setIsExpanded, expandedStateCache]
-    );
-
-    // Expand or collapse the subtree
-    const toggle = React.useCallback(
-      (event?: React.MouseEvent | React.KeyboardEvent) => {
-        setIsExpandedWithCache(!isExpanded);
-        event?.stopPropagation();
-      },
-      [isExpanded, setIsExpandedWithCache]
-    );
-
-    const handleKeyDown = React.useCallback(
-      (event: React.KeyboardEvent<HTMLElement>) => {
-        switch (event.key) {
-          case 'Enter':
-          case ' ':
-            if (onSelect) {
-              onSelect(event);
-            } else {
-              toggle(event);
-            }
-            event.stopPropagation();
-            break;
-          case 'ArrowRight':
-            // Ignore if modifier keys are pressed
-            if (event.altKey || event.metaKey) return;
-            event.preventDefault();
-            event.stopPropagation();
-            setIsExpandedWithCache(true);
-            break;
-          case 'ArrowLeft':
-            // Ignore if modifier keys are pressed
-            if (event.altKey || event.metaKey) return;
-            event.preventDefault();
-            event.stopPropagation();
-            setIsExpandedWithCache(false);
-            break;
-        }
-      },
-      [onSelect, setIsExpandedWithCache, toggle]
-    );
-
-    return (
-      <ItemContext.Provider
-        value={{
-          level: level + 1,
-          isExpanded,
-        }}
-      >
-        <li
-          className={classes.TreeViewItem}
-          ref={ref as React.ForwardedRef<HTMLLIElement>}
-          tabIndex={0}
-          id={itemId}
-          role="treeitem"
-          aria-level={level}
-          aria-expanded={isExpanded}
-          aria-current={isCurrentItem ? 'true' : undefined}
-          aria-selected={isFocused ? 'true' : 'false'}
-          onKeyDown={handleKeyDown}
-          onFocus={(event) => {
-            // Scroll the first child into view when the item receives focus
-            event.currentTarget.firstElementChild?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
-
-            // Set the focused state
-            setIsFocused(true);
-
-            // Prevent focus event from bubbling up to parent items
-            event.stopPropagation();
-          }}
-          onBlur={() => setIsFocused(false)}
-          onClick={(event) => {
-            if (onSelect) {
-              onSelect(event);
-              // if has children open them too
-              if (hasSubTree) {
-                toggle(event);
-              }
-            } else {
-              toggle(event);
-            }
-            event.stopPropagation();
-          }}
-          onAuxClick={(event) => {
-            if (onSelect && event.button === 1) {
-              onSelect(event);
-            }
-            event.stopPropagation();
-          }}
-        >
-          <div
-            className={classes.TreeViewItemContainer}
-            style={{
-              // @ts-ignore CSS custom property
-              '--level': level,
-            }}
-          >
-            <div style={{ gridArea: 'spacer', display: 'flex' }}>{/* <LevelIndicatorLines level={level} /> */}</div>
-
-            <div className={classes.TreeViewItemContent}>
-              {slots.leadingVisual}
-              <span className={classes.TreeViewItemContentText}>{childrenWithoutSubTree}</span>
-            </div>
-            {hasSubTree ? (
-              <div
-                className={[classes.TreeViewItemToggle, classes.TreeViewItemToggleHover, classes.TreeViewItemToggleEnd].join(' ')}
-                onClick={(event) => {
-                  if (onSelect) {
-                    toggle(event);
-                  }
-                }}
-              >
-                {isExpanded ? <ChevronDownIcon size={TOGGLE_ICON_SIZE} /> : <ChevronRightIcon size={TOGGLE_ICON_SIZE} />}
-              </div>
-            ) : null}
-          </div>
-          {subTree}
-        </li>
-      </ItemContext.Provider>
-    );
-  }
-);
-
-Item.displayName = 'TreeView.Item';
-
-// ----------------------------------------------------------------------------
-// TreeView.SubTree
-
-export type TreeViewSubTreeProps = {
-  children?: React.ReactNode;
-};
-
-const SubTree: React.FC<TreeViewSubTreeProps> = ({ children }) => {
-  const { isExpanded } = React.useContext(ItemContext);
-  const ref = React.useRef<HTMLUListElement>(null);
-
-  if (!isExpanded) {
-    return null;
-  }
-
-  return (
-    <ul
-      role="group"
-      style={{
-        listStyle: 'none',
-        padding: 0,
-        margin: 0,
-      }}
-      ref={ref}
-    >
-      {children}
-    </ul>
-  );
-};
-
-SubTree.displayName = 'TreeView.SubTree';
-
-function useSubTree(children: React.ReactNode) {
-  return React.useMemo(() => {
-    const subTree = React.Children.toArray(children).find((child) => React.isValidElement(child) && child.type === SubTree);
-
-    const childrenWithoutSubTree = React.Children.toArray(children).filter(
-      (child) => !(React.isValidElement(child) && child.type === SubTree)
-    );
-
-    return {
-      subTree,
-      childrenWithoutSubTree,
-      hasSubTree: Boolean(subTree),
-    };
-  }, [children]);
-}
-
-// ----------------------------------------------------------------------------
-// TreeView.LeadingVisual
-
-export type TreeViewLeadingVisualProps = {
-  children: React.ReactNode | ((props: { isExpanded: boolean }) => React.ReactNode);
-};
-
-const LeadingVisual: React.FC<TreeViewLeadingVisualProps> = (props) => {
-  const { isExpanded } = React.useContext(ItemContext);
-  const children = typeof props.children === 'function' ? props.children({ isExpanded }) : props.children;
-  return (
-    <div className={classes.TreeViewItemVisual} aria-hidden={true}>
-      {children}
-    </div>
-  );
-};
-
-LeadingVisual.displayName = 'TreeView.LeadingVisual';
-
-// ----------------------------------------------------------------------------
-// Export
-
-export const TreeView = Object.assign(Root, {
-  Item,
-  SubTree,
-  LeadingVisual,
-});
diff --git a/eventcatalog/src/components/TreeView/styles.module.css b/eventcatalog/src/components/TreeView/styles.module.css
deleted file mode 100644
index e4b19dd34..000000000
--- a/eventcatalog/src/components/TreeView/styles.module.css
+++ /dev/null
@@ -1,264 +0,0 @@
-.TreeViewRootUlStyles {
-  padding: 0;
-  margin: 0;
-  list-style: none;
-
-  /*
-   * WARNING: This is a performance optimization.
-   *
-   * We define styles for the tree items at the root level of the tree
-   * to avoid recomputing the styles for each item when the tree updates.
-   * We're sacrificing maintainability for performance because TreeView
-   * needs to be performant enough to handle large trees (thousands of items).
-   *
-   * This is intended to be a temporary solution until we can improve the
-   * performance of our styling patterns.
-   *
-   * Do NOT copy this pattern without understanding the tradeoffs.
-   */
-  .TreeViewItem {
-    outline: none;
-
-    &:focus-visible > div,
-    &.focus-visible > div {
-      box-shadow: var(--boxShadow-thick) /* var(--fgColor-accent) */ slategray;
-
-      @media (forced-colors: active) {
-        outline: 2px solid HighlightText;
-        outline-offset: -2;
-      }
-    }
-
-    &[data-has-leading-action] {
-      --has-leading-action: 1;
-    }
-  }
-
-  .TreeViewItemContainer {
-    --level: 1;
-    --toggle-width: 1rem;
-    --min-item-height: 2rem;
-
-    position: relative;
-    display: grid;
-    width: 100%;
-    font-size: var(--text-body-size-medium);
-    color: var(--fgColor-default);
-    cursor: pointer;
-    border-radius: var(--borderRadius-medium);
-    grid-template-columns: var(--spacer-width) var(--leading-action-width) 1fr var(--toggle-width);
-    grid-template-areas: 'spacer leadingAction content toggle';
-
-    --leading-action-width: calc(var(--has-leading-action, 0) * 1.5rem);
-    --spacer-width: calc(calc(var(--level) - 1) * (var(--toggle-width) / 2));
-
-    &:hover {
-      background-color: var(--control-transparent-bgColor-hover);
-
-      @media (forced-colors: active) {
-        outline: 2px solid transparent;
-        outline-offset: -2px;
-      }
-    }
-
-    @media (pointer: coarse) {
-      --toggle-width: 1.5rem;
-      --min-item-height: 2.75rem;
-    }
-
-    &:has(.TreeViewItemSkeleton):hover {
-      cursor: default;
-      background-color: transparent;
-
-      @media (forced-colors: active) {
-        outline: none;
-      }
-    }
-  }
-
-  &:where([data-omit-spacer='true']) .TreeViewItemContainer {
-    grid-template-columns: 0 0 1fr 0;
-  }
-
-  .TreeViewItem[aria-current='true'] > .TreeViewItemContainer {
-    background-color: var(--control-transparent-bgColor-selected);
-
-    /* Current item indicator */
-    /* stylelint-disable-next-line selector-max-specificity */
-    &::after {
-      position: absolute;
-      top: calc(50% - var(--base-size-12));
-      left: calc(-1 * var(--base-size-8));
-      width: 0.25rem;
-      height: 1.5rem;
-      content: '';
-
-      /*
-       * Use fgColor accent for consistency across all themes. Using the "correct" variable,
-       * --bgColor-accent-emphasis, causes vrt failures for dark high contrast mode
-       */
-      /* stylelint-disable-next-line primer/colors */
-      background-color: var(--fgColor-accent);
-      border-radius: var(--borderRadius-medium);
-
-      @media (forced-colors: active) {
-        background-color: HighlightText;
-      }
-    }
-  }
-
-  .TreeViewItemToggle {
-    display: flex;
-    height: 100%;
-
-    /* The toggle should appear vertically centered for single-line items, but remain at the top for items that wrap
-    across more lines. */
-    /* stylelint-disable-next-line primer/spacing */
-    padding-top: calc(var(--min-item-height) / 2 - var(--base-size-12) / 2);
-    color: var(--fgColor-muted);
-    grid-area: toggle;
-    justify-content: center;
-    align-items: flex-start;
-  }
-
-  .TreeViewItemToggleHover:hover {
-    background-color: var(--control-transparent-bgColor-hover);
-  }
-
-  .TreeViewItemToggleEnd {
-    border-top-left-radius: var(--borderRadius-medium);
-    border-bottom-left-radius: var(--borderRadius-medium);
-  }
-
-  .TreeViewItemContent {
-    display: flex;
-    height: 100%;
-    padding: 0 var(--base-size-8);
-
-    /* The dynamic top and bottom padding to maintain the minimum item height for single line items */
-    /* stylelint-disable-next-line primer/spacing */
-    padding-top: calc((var(--min-item-height) - var(--custom-line-height, 1.3rem)) / 2);
-    /* stylelint-disable-next-line primer/spacing */
-    padding-bottom: calc((var(--min-item-height) - var(--custom-line-height, 1.3rem)) / 2);
-    line-height: var(--custom-line-height, var(--text-body-lineHeight-medium, 1.4285));
-    grid-area: content;
-    gap: var(--stack-gap-condensed);
-  }
-
-  .TreeViewItemContentText {
-    flex: 1 1 auto;
-    width: 0;
-  }
-
-  &:where([data-truncate-text='true']) .TreeViewItemContentText {
-    overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
-  }
-
-  &:where([data-truncate-text='false']) .TreeViewItemContentText {
-    word-break: break-word;
-  }
-
-  .TreeViewItemVisual {
-    display: flex;
-
-    /* The visual icons should appear vertically centered for single-line items, but remain at the top for items that wrap
-    across more lines. */
-    height: var(--custom-line-height, 1.3rem);
-    color: var(--fgColor-muted);
-    align-items: center;
-  }
-
-  .TreeViewItemLeadingAction {
-    display: flex;
-    color: var(--fgColor-muted);
-    grid-area: leadingAction;
-
-    & > button {
-      flex-shrink: 1;
-    }
-  }
-
-  .TreeViewItemLevelLine {
-    width: 100%;
-    height: 100%;
-
-    /*
-     * On devices without hover, the nesting indicator lines
-     * appear at all times.
-     */
-    border-color: var(--borderColor-muted);
-    border-right: var(--borderWidth-thin) solid;
-  }
-
-  /*
-   * On devices with :hover support, the nesting indicator lines
-   * fade in when the user mouses over the entire component,
-   * or when there's focus inside the component. This makes
-   * sure the component remains simple when not in use.
-   */
-  @media (hover: hover) {
-    .TreeViewItemLevelLine {
-      border-color: transparent;
-    }
-
-    &:hover .TreeViewItemLevelLine,
-    &:focus-within .TreeViewItemLevelLine {
-      border-color: var(--borderColor-muted);
-    }
-  }
-
-  .TreeViewDirectoryIcon {
-    display: grid;
-    color: var(--treeViewItem-leadingVisual-iconColor-rest);
-  }
-
-  .TreeViewVisuallyHidden {
-    position: absolute;
-    width: 1px;
-    height: 1px;
-    padding: 0;
-    /* stylelint-disable-next-line primer/spacing */
-    margin: -1px;
-    overflow: hidden;
-    clip: rect(0, 0, 0, 0);
-    white-space: nowrap;
-    border-width: 0;
-  }
-}
-
-.TreeViewSkeletonItemContainerStyle {
-  display: flex;
-  align-items: center;
-  column-gap: 0.5rem;
-  height: 2rem;
-
-  @media (pointer: coarse) {
-    height: 2.75rem;
-  }
-
-  &:nth-of-type(5n + 1) {
-    --tree-item-loading-width: 67%;
-  }
-
-  &:nth-of-type(5n + 2) {
-    --tree-item-loading-width: 47%;
-  }
-
-  &:nth-of-type(5n + 3) {
-    --tree-item-loading-width: 73%;
-  }
-
-  &:nth-of-type(5n + 4) {
-    --tree-item-loading-width: 64%;
-  }
-
-  &:nth-of-type(5n + 5) {
-    --tree-item-loading-width: 50%;
-  }
-}
-
-.TreeItemSkeletonTextStyles {
-  width: var(--tree-item-loading-width, 67%);
-}
diff --git a/eventcatalog/src/components/TreeView/useSlots.ts b/eventcatalog/src/components/TreeView/useSlots.ts
deleted file mode 100644
index 7f00b0b94..000000000
--- a/eventcatalog/src/components/TreeView/useSlots.ts
+++ /dev/null
@@ -1,95 +0,0 @@
-import React from 'react';
-// import {warning} from '../utils/warning'
-
-// slot config allows 2 options:
-// 1. Component to match, example: { leadingVisual: LeadingVisual }
-type ComponentMatcher = React.ElementType<Props>;
-// 2. Component to match + a test function, example: { blockDescription: [Description, props => props.variant === 'block'] }
-type ComponentAndPropsMatcher = [ComponentMatcher, (props: Props) => boolean];
-
-export type SlotConfig = Record<string, ComponentMatcher | ComponentAndPropsMatcher>;
-
-// We don't know what the props are yet, we set them later based on slot config
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type Props = any;
-
-type SlotElements<Config extends SlotConfig> = {
-  [Property in keyof Config]: SlotValue<Config, Property>;
-};
-
-type SlotValue<Config, Property extends keyof Config> = Config[Property] extends React.ElementType // config option 1
-  ? React.ReactElement<React.ComponentPropsWithoutRef<Config[Property]>, Config[Property]>
-  : Config[Property] extends readonly [
-        infer ElementType extends React.ElementType, // config option 2, infer array[0] as component
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        infer _testFn, // even though we don't use testFn, we need to infer it to support types for slots.*.props
-      ]
-    ? React.ReactElement<React.ComponentPropsWithoutRef<ElementType>, ElementType>
-    : never; // useful for narrowing types, third option is not possible
-
-/**
- * Extract components from `children` so we can render them in different places,
- * allowing us to implement components with SSR-compatible slot APIs.
- * Note: We can only extract direct children, not nested ones.
- */
-export function useSlots<Config extends SlotConfig>(
-  children: React.ReactNode,
-  config: Config
-): [Partial<SlotElements<Config>>, React.ReactNode[]] {
-  // Object mapping slot names to their elements
-  const slots: Partial<SlotElements<Config>> = mapValues(config, () => undefined);
-
-  // Array of elements that are not slots
-  const rest: React.ReactNode[] = [];
-
-  const keys = Object.keys(config) as Array<keyof Config>;
-  const values = Object.values(config);
-
-  // eslint-disable-next-line github/array-foreach
-  React.Children.forEach(children, (child) => {
-    if (!React.isValidElement(child)) {
-      rest.push(child);
-      return;
-    }
-
-    const index = values.findIndex((value) => {
-      if (Array.isArray(value)) {
-        const [component, testFn] = value;
-        return child.type === component && testFn(child.props);
-      } else {
-        return child.type === value;
-      }
-    });
-
-    // If the child is not a slot, add it to the `rest` array
-    if (index === -1) {
-      rest.push(child);
-      return;
-    }
-
-    const slotKey = keys[index];
-
-    // If slot is already filled, ignore duplicates
-    if (slots[slotKey]) {
-      // warning(true, `Found duplicate "${String(slotKey)}" slot. Only the first will be rendered.`)
-      return;
-    }
-
-    // If the child is a slot, add it to the `slots` object
-
-    slots[slotKey] = child as SlotValue<Config, keyof Config>;
-  });
-
-  return [slots, rest];
-}
-
-/** Map the values of an object */
-function mapValues<T extends Record<string, unknown>, V>(obj: T, fn: (value: T[keyof T]) => V) {
-  return Object.keys(obj).reduce(
-    (result, key: keyof T) => {
-      result[key] = fn(obj[key]);
-      return result;
-    },
-    {} as Record<keyof T, V>
-  );
-}
diff --git a/eventcatalog/src/content.config.ts b/eventcatalog/src/content.config.ts
deleted file mode 100644
index b7d6c55db..000000000
--- a/eventcatalog/src/content.config.ts
+++ /dev/null
@@ -1,727 +0,0 @@
-import { z, defineCollection, reference } from 'astro:content';
-import { glob } from 'astro/loaders';
-import { glob as globPackage } from 'glob';
-import { v4 as uuidv4 } from 'uuid';
-import { badge, ownerReference } from './content.config-shared-collections';
-import fs from 'fs';
-import path from 'path';
-
-// Enterprise Collections
-import { chatPromptsSchema, customPagesSchema } from './enterprise/collections';
-
-export const projectDirBase = (() => {
-  if (process.platform === 'win32') {
-    const projectDirPath = process.env.PROJECT_DIR!.replace(/\\/g, '/');
-    return projectDirPath.startsWith('/') ? projectDirPath : `/${projectDirPath}`;
-  }
-  return process.env.PROJECT_DIR;
-})();
-
-const pages = defineCollection({
-  loader: glob({
-    pattern: ['**/pages/*.(md|mdx)'],
-    base: projectDirBase,
-  }),
-  schema: z
-    .object({
-      id: z.string(),
-    })
-    .optional(),
-});
-
-const pointer = z.object({
-  id: z.string(),
-  version: z.string().optional().default('latest'),
-});
-
-const detailPanelPropertySchema = z.object({
-  visible: z.boolean().optional(),
-});
-
-const channelPointer = z
-  .object({
-    parameters: z.record(z.string()).optional(),
-  })
-  .merge(pointer);
-
-const sendsPointer = z.object({
-  id: z.string(),
-  version: z.string().optional().default('latest'),
-  to: z
-    .array(
-      z.object({
-        ...channelPointer.shape,
-        delivery_mode: z.enum(['push', 'pull', 'push-pull']).optional().default('push'),
-      })
-    )
-    .optional(),
-});
-
-const receivesPointer = z.object({
-  id: z.string(),
-  version: z.string().optional().default('latest'),
-  from: z
-    .array(
-      z.object({
-        ...channelPointer.shape,
-        delivery_mode: z.enum(['push', 'pull', 'push-pull']).optional().default('push'),
-      })
-    )
-    .optional(),
-});
-
-const resourcePointer = z.object({
-  id: z.string(),
-  version: z.string().optional().default('latest'),
-  type: z.enum(['service', 'event', 'command', 'query', 'flow', 'channel', 'domain', 'user', 'team', 'container']),
-});
-
-const changelogs = defineCollection({
-  loader: glob({
-    pattern: ['**/changelog.(md|mdx)'],
-    base: projectDirBase,
-  }),
-  schema: z.object({
-    createdAt: z.date().optional(),
-    badges: z.array(badge).optional(),
-    // Used by eventcatalog
-    version: z.string().optional(),
-    versions: z.array(z.string()).optional(),
-    latestVersion: z.string().optional(),
-    catalog: z
-      .object({
-        path: z.string(),
-        absoluteFilePath: z.string(),
-        astroContentFilePath: z.string(),
-        filePath: z.string(),
-        publicPath: z.string(),
-        type: z.string(),
-      })
-      .optional(),
-  }),
-});
-
-const baseSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  summary: z.string().optional(),
-  // version: z.union([z.string(), z.number()]),
-  version: z.string(),
-  draft: z.union([z.boolean(), z.object({ title: z.string().optional(), message: z.string() })]).optional(),
-  badges: z.array(badge).optional(),
-  owners: z.array(ownerReference).optional(),
-  schemaPath: z.string().optional(),
-  sidebar: z
-    .object({
-      label: z.string().optional(),
-      badge: z.string().optional(),
-      color: z.string().optional(),
-      backgroundColor: z.string().optional(),
-    })
-    .optional(),
-  repository: z
-    .object({
-      language: z.string().optional(),
-      url: z.string().optional(),
-    })
-    .optional(),
-  specifications: z
-    .union([
-      z.object({
-        openapiPath: z.string().optional(),
-        asyncapiPath: z.string().optional(),
-        graphqlPath: z.string().optional(),
-      }),
-      z.array(
-        z.object({
-          type: z.enum(['openapi', 'asyncapi', 'graphql']),
-          path: z.string(),
-          name: z.string().optional(),
-        })
-      ),
-    ])
-    .optional(),
-  hidden: z.boolean().optional(),
-  editUrl: z.string().optional(),
-  resourceGroups: z
-    .array(
-      z.object({
-        id: z.string().optional(),
-        title: z.string().optional(),
-        items: z.array(resourcePointer),
-        limit: z.number().optional().default(10),
-        sidebar: z.boolean().optional().default(true),
-      })
-    )
-    .optional(),
-  styles: z
-    .object({
-      icon: z.string().optional(),
-      node: z
-        .object({
-          color: z.string().optional(),
-          label: z.string().optional(),
-        })
-        .optional(),
-    })
-    .optional(),
-  deprecated: z
-    .union([
-      z.object({
-        message: z.string().optional(),
-        date: z.union([z.string(), z.date()]).optional(),
-      }),
-      z.boolean().optional(),
-    ])
-    .optional(),
-  visualiser: z.boolean().optional(),
-  attachments: z
-    .array(
-      z.union([
-        z.string().url(), // simple case
-        z.object({
-          url: z.string().url(),
-          title: z.string().optional(),
-          type: z.string().optional(), // e.g. "architecture-record", "diagram"
-          description: z.string().optional(),
-          icon: z.string().optional(),
-        }),
-      ])
-    )
-    .optional(),
-  // Used by eventcatalog
-  versions: z.array(z.string()).optional(),
-  latestVersion: z.string().optional(),
-  catalog: z
-    .object({
-      path: z.string(),
-      filePath: z.string(),
-      astroContentFilePath: z.string(),
-      publicPath: z.string(),
-      type: z.string(),
-    })
-    .optional(),
-});
-
-const flowStep = z
-  .union([
-    // Can be a string or a number just to reference a step
-    z.union([z.string(), z.number()]),
-    z
-      .object({
-        id: z.union([z.string(), z.number()]),
-        label: z.string().optional(),
-      })
-      .optional(),
-  ])
-  .optional();
-
-const flows = defineCollection({
-  loader: glob({
-    pattern: ['**/flows/*/index.(md|mdx)', '**/flows/*/versioned/*/index.(md|mdx)'],
-    base: projectDirBase,
-    generateId: ({ data }) => {
-      return `${data.id}-${data.version}`;
-    },
-  }),
-  schema: z
-    .object({
-      detailsPanel: z
-        .object({
-          owners: detailPanelPropertySchema.optional(),
-          versions: detailPanelPropertySchema.optional(),
-          changelog: detailPanelPropertySchema.optional(),
-        })
-        .optional(),
-      steps: z.array(
-        z
-          .object({
-            id: z.union([z.string(), z.number()]),
-            type: z.enum(['node', 'message', 'user', 'actor']).optional(),
-            title: z.string(),
-            summary: z.string().optional(),
-            message: pointer.optional(),
-            service: pointer.optional(),
-            flow: pointer.optional(),
-
-            actor: z
-              .object({
-                name: z.string(),
-                summary: z.string().optional(),
-              })
-              .optional(),
-            custom: z
-              .object({
-                title: z.string(),
-                icon: z.string().optional(),
-                type: z.string().optional(),
-                summary: z.string().optional(),
-                url: z.string().url().optional(),
-                color: z.string().optional(),
-                properties: z.record(z.union([z.string(), z.number()])).optional(),
-                height: z.number().optional(),
-                menu: z
-                  .array(
-                    z.object({
-                      label: z.string(),
-                      url: z.string().url().optional(),
-                    })
-                  )
-                  .optional(),
-              })
-              .optional(),
-            externalSystem: z
-              .object({
-                name: z.string(),
-                summary: z.string().optional(),
-                url: z.string().url().optional(),
-              })
-              .optional(),
-            next_step: flowStep,
-            next_steps: z.array(flowStep).optional(),
-          })
-          .refine((data) => {
-            // Cant have both next_steps and next_steps
-            if (data.next_step && data.next_steps) return false;
-
-            // Either one or non types can be present
-            const typesUsed = [data.message, data.service, data.flow, data.actor, data.custom].filter((v) => v).length;
-            return typesUsed === 0 || typesUsed === 1;
-          })
-      ),
-    })
-    .merge(baseSchema),
-});
-
-const messageDetailsPanelPropertySchema = z.object({
-  producers: detailPanelPropertySchema.optional(),
-  consumers: detailPanelPropertySchema.optional(),
-  channels: detailPanelPropertySchema.optional(),
-  versions: detailPanelPropertySchema.optional(),
-  repository: detailPanelPropertySchema.optional(),
-  owners: detailPanelPropertySchema.optional(),
-  changelog: detailPanelPropertySchema.optional(),
-  attachments: detailPanelPropertySchema.optional(),
-});
-
-const events = defineCollection({
-  loader: glob({
-    pattern: ['**/events/*/index.(md|mdx)', '**/events/*/versioned/*/index.(md|mdx)'],
-    base: projectDirBase,
-    generateId: ({ data, ...rest }) => {
-      return `${data.id}-${data.version}`;
-    },
-  }),
-  schema: z
-    .object({
-      producers: z.array(reference('services')).optional(),
-      consumers: z.array(reference('services')).optional(),
-      channels: z.array(channelPointer).optional(),
-      // Used by eventcatalog
-      messageChannels: z.array(reference('channels')).optional(),
-      detailsPanel: messageDetailsPanelPropertySchema.optional(),
-    })
-    .merge(baseSchema),
-});
-
-const commands = defineCollection({
-  loader: glob({
-    pattern: ['**/commands/*/index.(md|mdx)', '**/commands/*/versioned/*/index.(md|mdx)'],
-    base: projectDirBase,
-    generateId: ({ data }) => {
-      return `${data.id}-${data.version}`;
-    },
-  }),
-  schema: z
-    .object({
-      producers: z.array(reference('services')).optional(),
-      consumers: z.array(reference('services')).optional(),
-      channels: z.array(channelPointer).optional(),
-      detailsPanel: messageDetailsPanelPropertySchema.optional(),
-      // Used by eventcatalog
-      messageChannels: z.array(reference('channels')).optional(),
-    })
-    .merge(baseSchema),
-});
-
-const queries = defineCollection({
-  loader: glob({
-    pattern: ['**/queries/*/index.(md|mdx)', '**/queries/*/versioned/*/index.(md|mdx)'],
-    base: projectDirBase,
-    generateId: ({ data }) => {
-      return `${data.id}-${data.version}`;
-    },
-  }),
-  schema: z
-    .object({
-      producers: z.array(reference('services')).optional(),
-      consumers: z.array(reference('services')).optional(),
-      channels: z.array(channelPointer).optional(),
-      detailsPanel: messageDetailsPanelPropertySchema.optional(),
-      // Used by eventcatalog
-      messageChannels: z.array(reference('channels')).optional(),
-    })
-    .merge(baseSchema),
-});
-
-const services = defineCollection({
-  loader: glob({
-    pattern: [
-      'domains/*/services/*/index.(md|mdx)',
-      'domains/*/services/*/versioned/*/index.(md|mdx)',
-
-      // Capture subdomain folders
-      'domains/*/subdomains/*/services/*/index.(md|mdx)',
-      'domains/*/subdomains/*/services/*/versioned/*/index.(md|mdx)',
-
-      // Capture services in the root
-      'services/*/index.(md|mdx)', // ✅ Capture only services markdown files
-      'services/*/versioned/*/index.(md|mdx)', // ✅ Capture versioned files inside services
-    ],
-    base: projectDirBase,
-    generateId: ({ data, ...rest }) => {
-      return `${data.id}-${data.version}`;
-    },
-  }),
-  schema: z
-    .object({
-      sends: z.array(sendsPointer).optional(),
-      receives: z.array(receivesPointer).optional(),
-      entities: z.array(pointer).optional(),
-      writesTo: z.array(pointer).optional(),
-      readsFrom: z.array(pointer).optional(),
-      detailsPanel: z
-        .object({
-          domains: detailPanelPropertySchema.optional(),
-          messages: detailPanelPropertySchema.optional(),
-          versions: detailPanelPropertySchema.optional(),
-          specifications: detailPanelPropertySchema.optional(),
-          entities: detailPanelPropertySchema.optional(),
-          repository: detailPanelPropertySchema.optional(),
-          owners: detailPanelPropertySchema.optional(),
-          changelog: detailPanelPropertySchema.optional(),
-          containers: detailPanelPropertySchema.optional(),
-        })
-        .optional(),
-    })
-    .merge(baseSchema),
-});
-
-// 1) Put this near your other enums/utilities
-const containerTypeEnum = z.enum([
-  // Core
-  'database',
-  'cache',
-  'objectStore',
-  'searchIndex',
-  'dataWarehouse',
-  'dataLake',
-  'externalSaaS',
-  // Fallback
-  'other',
-]);
-
-const accessModeEnum = z.enum(['read', 'write', 'readWrite', 'appendOnly']);
-const dataClassificationEnum = z.enum(['public', 'internal', 'confidential', 'regulated']);
-
-const containers = defineCollection({
-  loader: glob({
-    pattern: ['**/containers/*/index.(md|mdx)', '**/containers/*/versioned/*/index.(md|mdx)'],
-    base: projectDirBase,
-    generateId: ({ data }) => {
-      return `${data.id}-${data.version}`;
-    },
-  }),
-  schema: z
-    .object({
-      container_type: containerTypeEnum, // <— the important discriminator inside DataContainer
-      technology: z.string().optional(), // e.g. "postgres@14", "kafka", "s3"
-      authoritative: z.boolean().optional().default(false),
-      access_mode: accessModeEnum.optional(), // read/write/readWrite/appendOnly
-      classification: dataClassificationEnum.optional(),
-      residency: z.string().optional(),
-      retention: z.string().optional(),
-      // details panel toggles (aligns with your pattern)
-      detailsPanel: z
-        .object({
-          versions: detailPanelPropertySchema.optional(),
-          repository: detailPanelPropertySchema.optional(),
-          owners: detailPanelPropertySchema.optional(),
-          changelog: detailPanelPropertySchema.optional(),
-          attachments: detailPanelPropertySchema.optional(),
-        })
-        .optional(),
-      services: z.array(reference('services')).optional(),
-
-      servicesThatWriteToContainer: z.array(reference('services')).optional(),
-      servicesThatReadFromContainer: z.array(reference('services')).optional(),
-    })
-    .merge(baseSchema),
-});
-
-const customPages = defineCollection({
-  loader: glob({
-    // any number of child folders
-    pattern: ['docs/*.(md|mdx)', 'docs/**/*.@(md|mdx)'],
-    base: projectDirBase,
-  }),
-  schema: customPagesSchema,
-});
-
-const chatPrompts = defineCollection({
-  loader: glob({
-    pattern: ['chat-prompts/*.(md|mdx)', 'chat-prompts/**/*.@(md|mdx)'],
-    base: projectDirBase,
-  }),
-  schema: chatPromptsSchema,
-});
-
-const domains = defineCollection({
-  loader: glob({
-    pattern: [
-      // ✅ Strictly include only index.md at the expected levels
-      'domains/*/index.(md|mdx)',
-      'domains/*/versioned/*/index.(md|mdx)',
-
-      // Capture subdomain folders
-      'domains/*/subdomains/*/index.(md|mdx)',
-      'domains/*/subdomains/*/versioned/*/index.(md|mdx)',
-    ],
-    base: projectDirBase,
-    generateId: ({ data, ...rest }) => {
-      return `${data.id}-${data.version}`;
-    },
-  }),
-  schema: z
-    .object({
-      services: z.array(pointer).optional(),
-      domains: z.array(pointer).optional(),
-      entities: z.array(pointer).optional(),
-      detailsPanel: z
-        .object({
-          parentDomains: detailPanelPropertySchema.optional(),
-          subdomains: detailPanelPropertySchema.optional(),
-          services: detailPanelPropertySchema.optional(),
-          entities: detailPanelPropertySchema.optional(),
-          messages: detailPanelPropertySchema.optional(),
-          ubiquitousLanguage: detailPanelPropertySchema.optional(),
-          repository: detailPanelPropertySchema.optional(),
-          versions: detailPanelPropertySchema.optional(),
-          owners: detailPanelPropertySchema.optional(),
-          changelog: detailPanelPropertySchema.optional(),
-          attachments: detailPanelPropertySchema.optional(),
-        })
-        .optional(),
-    })
-    .merge(baseSchema),
-});
-
-const channels = defineCollection({
-  loader: glob({
-    pattern: ['**/channels/**/index.(md|mdx)', '**/channels/**/versioned/*/index.(md|mdx)'],
-    base: projectDirBase,
-    generateId: ({ data }) => {
-      return `${data.id}-${data.version}`;
-    },
-  }),
-  schema: z
-    .object({
-      channels: z.array(channelPointer).optional(),
-      address: z.string().optional(),
-      protocols: z.array(z.string()).optional(),
-      routes: z.array(channelPointer).optional(),
-      parameters: z
-        .record(
-          z.object({
-            enum: z.array(z.string()).optional(),
-            default: z.string().optional(),
-            examples: z.array(z.string()).optional(),
-            description: z.string().optional(),
-          })
-        )
-        .optional(),
-      messages: z.array(z.object({ collection: z.string(), name: z.string(), ...pointer.shape })).optional(),
-      detailsPanel: z
-        .object({
-          producers: detailPanelPropertySchema.optional(),
-          consumers: detailPanelPropertySchema.optional(),
-          messages: detailPanelPropertySchema.optional(),
-          protocols: detailPanelPropertySchema.optional(),
-          parameters: detailPanelPropertySchema.optional(),
-          versions: detailPanelPropertySchema.optional(),
-          repository: detailPanelPropertySchema.optional(),
-          owners: detailPanelPropertySchema.optional(),
-          changelog: detailPanelPropertySchema.optional(),
-          attachments: detailPanelPropertySchema.optional(),
-        })
-        .optional(),
-    })
-    .merge(baseSchema),
-});
-
-const ubiquitousLanguages = defineCollection({
-  loader: glob({
-    pattern: ['domains/*/ubiquitous-language.(md|mdx)', 'domains/*/subdomains/*/ubiquitous-language.(md|mdx)'],
-    base: projectDirBase,
-    generateId: ({ data }) => {
-      // File has no id, so we need to generate one
-      return uuidv4();
-    },
-  }),
-  schema: z.object({
-    dictionary: z
-      .array(
-        z.object({
-          id: z.string(),
-          name: z.string(),
-          summary: z.string().optional(),
-          description: z.string().optional(),
-          icon: z.string().optional(),
-        })
-      )
-      .optional(),
-  }),
-});
-
-const entities = defineCollection({
-  loader: glob({
-    pattern: ['**/entities/*/index.(md|mdx)', '**/entities/*/versioned/*/index.(md|mdx)'],
-    base: projectDirBase,
-    generateId: ({ data, ...rest }) => {
-      return `${data.id}-${data.version}`;
-    },
-  }),
-  schema: z
-    .object({
-      aggregateRoot: z.boolean().optional(),
-      identifier: z.string().optional(),
-      properties: z
-        .array(
-          z.object({
-            name: z.string(),
-            type: z.string(),
-            required: z.boolean().optional(),
-            description: z.string().optional(),
-            references: z.string().optional(),
-            referencesIdentifier: z.string().optional(),
-            relationType: z.string().optional(),
-            enum: z.array(z.string()).optional(),
-            items: z
-              .object({
-                type: z.string(),
-              })
-              .optional(),
-          })
-        )
-        .optional(),
-      services: z.array(reference('services')).optional(),
-      domains: z.array(reference('domains')).optional(),
-      detailsPanel: z
-        .object({
-          domains: detailPanelPropertySchema.optional(),
-          services: detailPanelPropertySchema.optional(),
-          messages: detailPanelPropertySchema.optional(),
-          versions: detailPanelPropertySchema.optional(),
-          owners: detailPanelPropertySchema.optional(),
-          changelog: detailPanelPropertySchema.optional(),
-          attachments: detailPanelPropertySchema.optional(),
-        })
-        .optional(),
-    })
-
-    .merge(baseSchema),
-});
-
-const users = defineCollection({
-  loader: glob({ pattern: 'users/*.(md|mdx)', base: projectDirBase, generateId: ({ data }) => data.id as string }),
-  schema: z.object({
-    id: z.string(),
-    name: z.string(),
-    avatarUrl: z.string(),
-    role: z.string().optional(),
-    hidden: z.boolean().optional(),
-    email: z.string().optional(),
-    slackDirectMessageUrl: z.string().optional(),
-    msTeamsDirectMessageUrl: z.string().optional(),
-    ownedDomains: z.array(reference('domains')).optional(),
-    ownedServices: z.array(reference('services')).optional(),
-    ownedEvents: z.array(reference('events')).optional(),
-    ownedCommands: z.array(reference('commands')).optional(),
-    ownedQueries: z.array(reference('queries')).optional(),
-    associatedTeams: z.array(reference('teams')).optional(),
-  }),
-});
-
-const teams = defineCollection({
-  loader: glob({ pattern: 'teams/*.(md|mdx)', base: projectDirBase, generateId: ({ data }) => data.id as string }),
-  schema: z.object({
-    id: z.string(),
-    name: z.string(),
-    summary: z.string().optional(),
-    email: z.string().optional(),
-    hidden: z.boolean().optional(),
-    slackDirectMessageUrl: z.string().optional(),
-    msTeamsDirectMessageUrl: z.string().optional(),
-    members: z.array(reference('users')).optional(),
-    ownedCommands: z.array(reference('commands')).optional(),
-    ownedQueries: z.array(reference('queries')).optional(),
-    ownedDomains: z.array(reference('domains')).optional(),
-    ownedServices: z.array(reference('services')).optional(),
-    ownedEvents: z.array(reference('events')).optional(),
-  }),
-});
-
-const designs = defineCollection({
-  loader: async () => {
-    const data = await globPackage('**/**/*.ecstudio', { cwd: projectDirBase });
-    // File all the files in the designs folder
-    // Limit 3 designs community edition?
-    const files = data.reduce<{ id: string; name: string }[]>((acc, filePath) => {
-      try {
-        const data = fs.readFileSync(path.join(projectDirBase!, filePath), 'utf-8');
-        const json = JSON.parse(data);
-        return [...acc, { ...json }];
-      } catch (error) {
-        console.error('Error loading design', error);
-        return acc;
-      }
-    }, []);
-    return files;
-  },
-  schema: z.object({
-    id: z.string(),
-    name: z.string(),
-    creationDate: z.string(),
-    source: z.string(),
-    nodes: z.any(),
-    edges: z.any(),
-    viewport: z.any(),
-    version: z.string(),
-  }),
-});
-
-export const collections = {
-  events,
-  commands,
-  queries,
-  services,
-  channels,
-  users,
-  teams,
-  domains,
-  flows,
-  pages,
-  changelogs,
-  containers,
-
-  // DDD Collections
-  ubiquitousLanguages,
-  entities,
-
-  // EventCatalog Pro Collections
-  customPages,
-  chatPrompts,
-
-  // EventCatalog Studio Collections
-  designs,
-};
diff --git a/eventcatalog/src/enterprise/LICENSE.txt b/eventcatalog/src/enterprise/LICENSE.txt
deleted file mode 100644
index c869e966c..000000000
--- a/eventcatalog/src/enterprise/LICENSE.txt
+++ /dev/null
@@ -1,4 +0,0 @@
-Usage of files in this directory and its subdirectories, and of EventCatalog Plugin / Enterprise features, is subject to
-the EventCatalog Plugin Licenses (https://www.eventcatalog.dev), and conditional on having a
-valid plugin license from EventCatalog. Access to files in this directory and its subdirectories does not constitute
-permission to use this code or EventCatalog Plugin / Enterprise features.
\ No newline at end of file
diff --git a/eventcatalog/src/enterprise/collections/chat-prompts.ts b/eventcatalog/src/enterprise/collections/chat-prompts.ts
deleted file mode 100644
index e170a62f4..000000000
--- a/eventcatalog/src/enterprise/collections/chat-prompts.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import { z } from 'astro:content';
-
-export const chatPromptsSchema = z.object({
-  title: z.string(),
-  type: z.enum(['text', 'code']).default('text'),
-  inputs: z
-    .array(
-      z.object({
-        id: z.string(),
-        label: z.string(),
-        type: z
-          .enum([
-            'text',
-            'resource-list-events',
-            'resource-list-services',
-            'resource-list-commands',
-            'resource-list-queries',
-            'code',
-            'text-area',
-            'select',
-          ])
-          .default('text'),
-        options: z.array(z.string()).optional(),
-      })
-    )
-    .optional(),
-  category: z.object({
-    id: z.string(),
-    label: z.string(),
-    icon: z.string().optional(),
-  }),
-});
diff --git a/eventcatalog/src/enterprise/collections/custom-pages.ts b/eventcatalog/src/enterprise/collections/custom-pages.ts
deleted file mode 100644
index e51294d03..000000000
--- a/eventcatalog/src/enterprise/collections/custom-pages.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-import { z } from 'astro:content';
-import { badge, ownerReference } from '../../content.config-shared-collections';
-
-export const customPagesSchema = z.object({
-  title: z.string(),
-  summary: z.string(),
-  slug: z.string().optional(),
-  sidebar: z
-    .object({
-      label: z.string(),
-      order: z.number(),
-    })
-    .optional(),
-  owners: z.array(ownerReference).optional(),
-  badges: z.array(badge).optional(),
-});
diff --git a/eventcatalog/src/enterprise/collections/index.ts b/eventcatalog/src/enterprise/collections/index.ts
deleted file mode 100644
index 076aabf01..000000000
--- a/eventcatalog/src/enterprise/collections/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export { customPagesSchema } from './custom-pages';
-export { chatPromptsSchema } from './chat-prompts';
diff --git a/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/mocks.ts b/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/mocks.ts
deleted file mode 100644
index 174c77ad8..000000000
--- a/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/mocks.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-export const mockDocs = [
-  {
-    id: 'docs/auto-generated/01-introduction',
-    collection: 'docs',
-    data: {
-      title: 'Introduction',
-      description: 'Introduction example',
-    },
-  },
-  {
-    id: 'docs/auto-generated/02-hello-world',
-    collection: 'docs',
-    data: {
-      title: 'Hello World',
-      description: 'Hello World example',
-    },
-  },
-];
diff --git a/eventcatalog/src/enterprise/custom-documentation/collection.ts b/eventcatalog/src/enterprise/custom-documentation/collection.ts
deleted file mode 100644
index e51294d03..000000000
--- a/eventcatalog/src/enterprise/custom-documentation/collection.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-import { z } from 'astro:content';
-import { badge, ownerReference } from '../../content.config-shared-collections';
-
-export const customPagesSchema = z.object({
-  title: z.string(),
-  summary: z.string(),
-  slug: z.string().optional(),
-  sidebar: z
-    .object({
-      label: z.string(),
-      order: z.number(),
-    })
-    .optional(),
-  owners: z.array(ownerReference).optional(),
-  badges: z.array(badge).optional(),
-});
diff --git a/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNavWrapper.tsx b/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNavWrapper.tsx
deleted file mode 100644
index d8abb388d..000000000
--- a/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNavWrapper.tsx
+++ /dev/null
@@ -1,11 +0,0 @@
-import CustomDocsNav from './';
-import type { SidebarSection } from './types';
-
-interface CustomDocsNavWrapperProps {
-  sidebarItems: SidebarSection[];
-  currentPath: string;
-}
-
-export default function CustomDocsNavWrapper(props: CustomDocsNavWrapperProps) {
-  return <CustomDocsNav {...props} />;
-}
diff --git a/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/components/NestedItem.tsx b/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/components/NestedItem.tsx
deleted file mode 100644
index 2d7f28e53..000000000
--- a/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/components/NestedItem.tsx
+++ /dev/null
@@ -1,143 +0,0 @@
-import React from 'react';
-import { buildUrl } from '@utils/url-builder';
-import type { SidebarItem } from '../types';
-import { ExternalLinkIcon } from 'lucide-react';
-
-interface NestedItemProps {
-  item: SidebarItem;
-  currentPath: string;
-  parentId: string;
-  itemIndex: number;
-  collapsedGroups: { [key: string]: boolean };
-  toggleGroupCollapse: (group: string) => void;
-}
-
-const NestedItem: React.FC<NestedItemProps> = ({
-  item,
-  currentPath,
-  parentId,
-  itemIndex,
-  collapsedGroups,
-  toggleGroupCollapse,
-}) => {
-  const hasNestedItems = item.items && item.items.length > 0;
-  const itemId = `${parentId}-${itemIndex}`;
-
-  if (hasNestedItems && item.items) {
-    return (
-      <div className="py-1">
-        <div className="flex items-center">
-          <button
-            className="p-1 hover:bg-gray-100 rounded-md flex-shrink-0"
-            onClick={(e) => {
-              e.stopPropagation();
-              toggleGroupCollapse(`nested-${itemId}`);
-            }}
-          >
-            <div className={`transition-transform duration-150 ${collapsedGroups[`nested-${itemId}`] ? '' : 'rotate-180'}`}>
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                fill="none"
-                viewBox="0 0 24 24"
-                strokeWidth="1.5"
-                stroke="currentColor"
-                aria-hidden="true"
-                data-slot="icon"
-                className="h-3 w-3 text-gray-500"
-              >
-                <path strokeLinecap="round" strokeLinejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"></path>
-              </svg>
-            </div>
-          </button>
-          <button
-            className="flex items-center px-2 py-1 text-xs font-medium text-gray-700 rounded-md hover:bg-purple-50 min-w-0 flex-1"
-            onClick={(e) => {
-              e.stopPropagation();
-              toggleGroupCollapse(`nested-${itemId}`);
-            }}
-          >
-            <span className="truncate">{item.label}</span>
-            {item.badge && item?.badge?.text && (
-              <span
-                className={`text-${item.badge.color || 'purple'}-600 ml-2 text-[10px] font-medium bg-${item.badge.color || 'purple'}-50 px-2 py-0.5 rounded uppercase`}
-              >
-                {item.badge.text}
-              </span>
-            )}
-          </button>
-        </div>
-
-        <div
-          className={`overflow-hidden transition-[height] duration-150 ease-out ${
-            collapsedGroups[`nested-${itemId}`] ? 'h-0' : 'h-auto'
-          }`}
-        >
-          <div className="space-y-0.5 border-gray-200/80 border-l pl-4 ml-[9px] mt-1">
-            {item.items.map((nestedItem: SidebarItem, nestedIndex: number) => (
-              <NestedItem
-                key={`nested-${itemId}-${nestedIndex}`}
-                item={nestedItem}
-                currentPath={currentPath}
-                parentId={itemId}
-                itemIndex={nestedIndex}
-                collapsedGroups={collapsedGroups}
-                toggleGroupCollapse={toggleGroupCollapse}
-              />
-            ))}
-          </div>
-        </div>
-      </div>
-    );
-  }
-
-  let itemPath = item.slug ? buildUrl(`/docs/custom/${item.slug}`) : '#';
-  const isActive = currentPath === itemPath || currentPath.endsWith(`/${item.slug}`);
-
-  // Convert string style to React CSSProperties if needed
-  const attrs = item.attrs
-    ? {
-        ...item.attrs,
-        style:
-          typeof item.attrs.style === 'string'
-            ? item.attrs.style
-                .split(';')
-                .filter((style) => style.trim())
-                .reduce((acc, style) => {
-                  const [key, value] = style.split(':').map((s) => s.trim());
-                  const camelKey = key.replace(/-([a-z])/g, (g) => g[1].toUpperCase());
-                  return { ...acc, [camelKey]: value };
-                }, {})
-            : item.attrs.style,
-      }
-    : null;
-
-  const isExternalLink = item.slug?.startsWith('http');
-
-  if (isExternalLink && item.slug) {
-    itemPath = item.slug;
-  }
-
-  return (
-    <a
-      href={itemPath}
-      {...(attrs || {})}
-      className={`flex items-center px-2 py-1.5 text-xs ${isActive ? 'bg-purple-100 text-purple-900 font-medium' : 'text-gray-600 hover:bg-purple-100'} rounded-md`}
-      data-active={isActive}
-      target={isExternalLink ? '_blank' : undefined}
-    >
-      <span className="truncate flex items-center gap-1.5">
-        {item.label}
-        {isExternalLink && <ExternalLinkIcon className="w-3 -mt-0.5 h-3" />}
-      </span>
-      {item.badge && item?.badge?.text && (
-        <span
-          className={`text-${item.badge.color || 'purple'}-600 ml-2 text-[10px] font-medium bg-${item.badge.color || 'purple'}-50 px-2 py-0.5 rounded uppercase`}
-        >
-          {item.badge.text}
-        </span>
-      )}
-    </a>
-  );
-};
-
-export default React.memo(NestedItem);
diff --git a/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/components/NoResultsFound.tsx b/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/components/NoResultsFound.tsx
deleted file mode 100644
index 5e5104bc5..000000000
--- a/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/components/NoResultsFound.tsx
+++ /dev/null
@@ -1,21 +0,0 @@
-import React from 'react';
-
-interface NoResultsFoundProps {
-  searchTerm: string;
-}
-
-const NoResultsFound: React.FC<NoResultsFoundProps> = ({ searchTerm }) => (
-  <div className="px-4 py-6 text-center">
-    <div className="text-gray-400 text-sm mb-2">No results found for "{searchTerm}"</div>
-    <div className="text-gray-400 text-xs">
-      Try:
-      <ul className="mt-2 space-y-1 text-left list-disc pl-4">
-        <li>Checking for typos</li>
-        <li>Using fewer keywords</li>
-        <li>Using more general terms</li>
-      </ul>
-    </div>
-  </div>
-);
-
-export default React.memo(NoResultsFound);
diff --git a/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/index.tsx b/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/index.tsx
deleted file mode 100644
index 41da5407e..000000000
--- a/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/index.tsx
+++ /dev/null
@@ -1,329 +0,0 @@
-import React, { useState, useRef, useEffect, useCallback, useMemo } from 'react';
-import { ChevronDoubleDownIcon, ChevronDoubleUpIcon } from '@heroicons/react/24/outline';
-import { buildUrl } from '@utils/url-builder';
-import type { CustomDocsNavProps, SidebarSection, SidebarItem } from './types';
-import NestedItem from './components/NestedItem';
-import NoResultsFound from './components/NoResultsFound';
-
-const STORAGE_KEY = 'EventCatalog:customDocsSidebarCollapsedGroups';
-const DEBOUNCE_DELAY = 300; // 300ms debounce delay
-
-const CustomDocsNav: React.FC<CustomDocsNavProps> = ({ sidebarItems }) => {
-  const navRef = useRef<HTMLElement>(null);
-  const [searchTerm, setSearchTerm] = useState('');
-  const [debouncedSearchTerm, setDebouncedSearchTerm] = useState('');
-  const [isInitialized, setIsInitialized] = useState(false);
-  const [isExpanded, setIsExpanded] = useState(true);
-  const [collapsedGroups, setCollapsedGroups] = useState<{ [key: string]: boolean }>(() => {
-    if (typeof window !== 'undefined') {
-      const saved = window.localStorage.getItem(STORAGE_KEY);
-      setIsInitialized(true);
-      return saved ? JSON.parse(saved) : {};
-    }
-    return {};
-  });
-
-  const currentPath = window.location.pathname;
-
-  // Set up debounced search
-  useEffect(() => {
-    const timer = setTimeout(() => {
-      setDebouncedSearchTerm(searchTerm.toLowerCase());
-    }, DEBOUNCE_DELAY);
-
-    return () => clearTimeout(timer);
-  }, [searchTerm]);
-
-  // Filter sidebar items based on search term
-  const filteredSidebarItems = useMemo(() => {
-    if (!debouncedSearchTerm) return sidebarItems;
-
-    const matchesSearchTerm = (text: string) => text.toLowerCase().includes(debouncedSearchTerm);
-
-    // Helper function to check if an item or any of its nested items match the search term
-    const itemContainsSearchTerm = (item: SidebarItem): boolean => {
-      if (matchesSearchTerm(item.label)) return true;
-
-      if (item.items && item.items.length > 0) {
-        return item.items.some(itemContainsSearchTerm);
-      }
-
-      return false;
-    };
-
-    return sidebarItems
-      .map((section) => {
-        if (!section.items) {
-          return matchesSearchTerm(section.label) ? section : null;
-        }
-
-        const filteredItems = section.items.filter(itemContainsSearchTerm);
-
-        if (filteredItems.length > 0 || matchesSearchTerm(section.label)) {
-          return {
-            ...section,
-            items: filteredItems,
-          };
-        }
-
-        return null;
-      })
-      .filter(Boolean) as SidebarSection[];
-  }, [sidebarItems, debouncedSearchTerm]);
-
-  // Auto-expand groups when searching
-  useEffect(() => {
-    if (debouncedSearchTerm) {
-      // Expand all groups when searching
-      const newCollapsedState = { ...collapsedGroups };
-      Object.keys(newCollapsedState).forEach((key) => {
-        newCollapsedState[key] = false;
-      });
-      setCollapsedGroups(newCollapsedState);
-    }
-  }, [debouncedSearchTerm]);
-
-  // Store collapsed groups in local storage
-  useEffect(() => {
-    if (typeof window !== 'undefined' && isInitialized) {
-      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(collapsedGroups));
-    }
-  }, [collapsedGroups, isInitialized]);
-
-  // Initialize collapsed state from section config
-  useEffect(() => {
-    if (isInitialized && sidebarItems && sidebarItems.length > 0) {
-      const initialState = { ...collapsedGroups };
-
-      sidebarItems.forEach((section, index) => {
-        const sectionKey = `section-${index}`;
-        if (section.collapsed !== undefined && initialState[sectionKey] === undefined) {
-          initialState[sectionKey] = section.collapsed;
-        }
-      });
-
-      setCollapsedGroups(initialState);
-    }
-  }, [sidebarItems, isInitialized]);
-
-  // If we find a data-active element, scroll to it on mount
-  useEffect(() => {
-    const activeElement = document.querySelector('[data-active="true"]');
-    if (activeElement) {
-      // Add y offset to the scroll position
-      setTimeout(() => {
-        activeElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
-      }, 300);
-    }
-  }, []);
-
-  const toggleGroupCollapse = useCallback((group: string) => {
-    setCollapsedGroups((prev) => ({
-      ...prev,
-      [group]: !prev[group],
-    }));
-  }, []);
-
-  const handleSearchChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
-    setSearchTerm(e.target.value);
-  }, []);
-
-  const collapseAll = useCallback(() => {
-    const newCollapsedState: { [key: string]: boolean } = {};
-
-    // Collapse all sections
-    filteredSidebarItems.forEach((section, index) => {
-      const sectionKey = `section-${index}`;
-      newCollapsedState[sectionKey] = true;
-
-      // Collapse all nested items in the section
-      const collapseNestedItems = (items: SidebarItem[], parentId: string) => {
-        items.forEach((item, itemIndex) => {
-          if (item.items && item.items.length > 0) {
-            const itemKey = `${parentId}-${itemIndex}`;
-            newCollapsedState[itemKey] = true;
-            collapseNestedItems(item.items, itemKey);
-          }
-        });
-      };
-
-      if (section.items) {
-        collapseNestedItems(section.items, sectionKey);
-      }
-    });
-
-    setCollapsedGroups(newCollapsedState);
-    setIsExpanded(false);
-  }, [filteredSidebarItems]);
-
-  const expandAll = useCallback(() => {
-    const newCollapsedState: { [key: string]: boolean } = {};
-
-    // Expand all sections
-    filteredSidebarItems.forEach((section, index) => {
-      const sectionKey = `section-${index}`;
-      newCollapsedState[sectionKey] = false;
-
-      // Expand all nested items in the section
-      const expandNestedItems = (items: SidebarItem[], parentId: string) => {
-        items.forEach((item, itemIndex) => {
-          if (item.items && item.items.length > 0) {
-            const itemKey = `${parentId}-${itemIndex}`;
-            newCollapsedState[itemKey] = false;
-            expandNestedItems(item.items, itemKey);
-          }
-        });
-      };
-
-      if (section.items) {
-        expandNestedItems(section.items, sectionKey);
-      }
-    });
-
-    setCollapsedGroups(newCollapsedState);
-    setIsExpanded(true);
-  }, [filteredSidebarItems]);
-
-  const toggleExpandCollapse = useCallback(() => {
-    if (isExpanded) {
-      collapseAll();
-    } else {
-      expandAll();
-    }
-  }, [isExpanded, collapseAll, expandAll]);
-
-  if (!isInitialized) return null;
-
-  const hasNoResults = debouncedSearchTerm && filteredSidebarItems.length === 0;
-
-  return (
-    <nav ref={navRef} className="h-full text-gray-800 pt-4 overflow-y-auto">
-      <div className="mb-2 px-3 bg-white z-10">
-        <div className="flex gap-2">
-          <input
-            type="text"
-            value={searchTerm}
-            onChange={handleSearchChange}
-            placeholder="Quick search..."
-            className="flex-1 p-2 px-2 text-sm rounded-md border border-gray-200 h-[30px]"
-          />
-          <button
-            onClick={toggleExpandCollapse}
-            title={isExpanded ? 'Collapse All' : 'Expand All'}
-            className="px-2 py-1 bg-gray-100 hover:bg-gray-200 rounded-md border border-gray-200 h-[30px] flex items-center justify-center"
-          >
-            {isExpanded ? (
-              <ChevronDoubleUpIcon className="h-4 w-4 text-gray-600" />
-            ) : (
-              <ChevronDoubleDownIcon className="h-4 w-4 text-gray-600" />
-            )}
-          </button>
-        </div>
-      </div>
-
-      <div className="space-y-2 divide-y divide-gray-100/40 pb-4">
-        {hasNoResults ? (
-          <NoResultsFound searchTerm={debouncedSearchTerm} />
-        ) : (
-          filteredSidebarItems.map((section: SidebarSection, index: number) => (
-            <div className="pt-2 pb-2 px-3" key={`section-${index}`}>
-              <div className="space-y-0" data-section={`section-${index}`}>
-                {section.items ? (
-                  <div className="flex items-center">
-                    <button
-                      className="p-1 hover:bg-gray-100 rounded-md flex-shrink-0"
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        toggleGroupCollapse(`section-${index}`);
-                      }}
-                    >
-                      <div
-                        className={`transition-transform duration-150 ${collapsedGroups[`section-${index}`] ? '' : 'rotate-180'}`}
-                      >
-                        <svg
-                          xmlns="http://www.w3.org/2000/svg"
-                          fill="none"
-                          viewBox="0 0 24 24"
-                          strokeWidth="1.5"
-                          stroke="currentColor"
-                          aria-hidden="true"
-                          data-slot="icon"
-                          className="h-3 w-3 text-gray-500"
-                        >
-                          <path strokeLinecap="round" strokeLinejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"></path>
-                        </svg>
-                      </div>
-                    </button>
-                    <button
-                      className="flex items-center justify-between px-2 py-0.5 text-xs font-bold rounded-md hover:bg-purple-50 min-w-0 flex-1"
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        toggleGroupCollapse(`section-${index}`);
-                      }}
-                    >
-                      <span className="truncate">{section.label}</span>
-                      {section.badge && section?.badge?.text && (
-                        <span
-                          className={`text-${section.badge.color || 'purple'}-600 ml-2 text-[10px] font-medium bg-${section.badge.color || 'purple'}-50 px-2 py-0.5 rounded uppercase`}
-                        >
-                          {section.badge.text}
-                        </span>
-                      )}
-                    </button>
-                  </div>
-                ) : (
-                  <div className="flex items-center">
-                    <span className="flex-grow flex items-center justify-between px-2 py-0.5 text-xs font-bold rounded-md">
-                      <span className="truncate">{section.label}</span>
-                      <span className="text-purple-600 ml-2 text-[10px] font-medium bg-purple-50 px-2 py-0.5 rounded uppercase">
-                        Section
-                      </span>
-                    </span>
-                  </div>
-                )}
-
-                {section.items && (
-                  <div
-                    className={`overflow-hidden transition-[height] duration-150 ease-out ${
-                      collapsedGroups[`section-${index}`] ? 'h-0' : 'h-auto'
-                    }`}
-                  >
-                    <div className="space-y-0.5 border-gray-200/80 border-l pl-4 ml-[9px] mt-1">
-                      {section.items.map((item: SidebarItem, itemIndex: number) => (
-                        <NestedItem
-                          key={`item-${index}-${itemIndex}`}
-                          item={item}
-                          currentPath={currentPath}
-                          parentId={`${index}`}
-                          itemIndex={itemIndex}
-                          collapsedGroups={collapsedGroups}
-                          toggleGroupCollapse={toggleGroupCollapse}
-                        />
-                      ))}
-                    </div>
-                  </div>
-                )}
-
-                {section.slug && !section.items && (
-                  <a
-                    href={buildUrl(`/docs/custom/${section.slug}`)}
-                    className={`flex items-center px-2 py-1.5 text-xs ${
-                      currentPath.endsWith(`/${section.slug}`)
-                        ? 'bg-purple-100 text-purple-900 font-medium'
-                        : 'text-gray-600 hover:bg-purple-100'
-                    } rounded-md ml-6`}
-                    data-active={currentPath.endsWith(`/${section.slug}`)}
-                  >
-                    <span className="truncate">{section.label}</span>
-                  </a>
-                )}
-              </div>
-            </div>
-          ))
-        )}
-      </div>
-    </nav>
-  );
-};
-
-export default React.memo(CustomDocsNav);
diff --git a/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/types.ts b/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/types.ts
deleted file mode 100644
index f94c502d7..000000000
--- a/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/types.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-export interface SidebarItem {
-  label: string;
-  slug?: string;
-  link?: string;
-  attrs?: Record<string, string>;
-  items?: SidebarItem[];
-  badge?: {
-    text: string;
-    color: string;
-  };
-  collapsed?: boolean;
-}
-
-export interface SidebarSection {
-  label: string;
-  items?: SidebarItem[];
-  slug?: string;
-  autogenerated?: {
-    directory: string;
-    collapsed?: boolean;
-  };
-  badge?: {
-    text: string;
-    color: string;
-  };
-  collapsed?: boolean;
-}
-
-export interface CustomDocsNavProps {
-  sidebarItems: SidebarSection[];
-  currentPath: string;
-}
diff --git a/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/index.astro b/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/index.astro
deleted file mode 100644
index 863d5c859..000000000
--- a/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/index.astro
+++ /dev/null
@@ -1,490 +0,0 @@
----
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { render } from 'astro:content';
-import config from '@config';
-import { AlignLeftIcon } from 'lucide-react';
-
-import mdxComponents from '@components/MDX/components';
-import OwnersList from '@components/Lists/OwnersList';
-
-import { getOwner } from '@utils/collections/owners';
-import { buildUrl } from '@utils/url-builder';
-import { resourceToCollectionMap } from '@utils/collections/util';
-import { getMDXComponentsByName } from '@utils/markdown';
-import { getAdjacentPages } from '@enterprise/custom-documentation/utils/custom-docs';
-
-import CustomDocsNav from '@enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNav.astro';
-import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
-
-import { isVisualiserEnabled } from '@utils/feature';
-
-const props = Astro.props;
-const doc = props.data;
-const { Content, headings } = await render(props as any);
-const currentSlug = props.id;
-
-const nodeGraphs = getMDXComponentsByName(props.body, 'NodeGraph') || [];
-// Get sidebar data
-const sidebar = config?.customDocs?.sidebar || [];
-
-// Flatten the sidebar to find previous and next pages
-type FlatItem = {
-  label: string;
-  slug: string;
-};
-
-// Define sidebar section type
-type SidebarSection = {
-  label: string;
-  slug?: string;
-  items?: Array<{
-    label: string;
-    slug: string;
-  }>;
-};
-
-const flattenedItems: FlatItem[] = [];
-
-// Process all sidebar sections to create a flattened array
-sidebar.forEach((section: SidebarSection) => {
-  if (section.slug && !section.items) {
-    flattenedItems.push({
-      label: section.label,
-      slug: section.slug,
-    });
-  }
-  if (section.items) {
-    section.items.forEach((item: { label: string; slug: string }) => {
-      flattenedItems.push({
-        label: item.label,
-        slug: item.slug,
-      });
-    });
-  }
-});
-
-const { prev, next } = await getAdjacentPages(currentSlug.replace());
-
-const ownersRaw = doc?.owners || [];
-const owners = await Promise.all<ReturnType<typeof getOwner>>(ownersRaw.map(getOwner));
-const filteredOwners = owners.filter((o) => o !== undefined);
-
-const ownersList = filteredOwners.map((o) => ({
-  label: o.data.name,
-  type: o.collection,
-  badge: o.collection === 'users' ? o.data.role : 'Team',
-  avatarUrl: o.collection === 'users' ? o.data.avatarUrl : '',
-  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
-}));
-
-const badges = doc?.badges || [];
----
-
-<VerticalSideBarLayout title={doc.title || 'Documentation'}>
-  <div class="flex w-full" data-pagefind-body data-pagefind-meta={`title:${doc.title}`}>
-    <!-- Left Sidebar Navigation -->
-    <aside class="sidebar-transition overflow-y-auto bg-white border-r border-gray-100 w-80 fixed top-16 bottom-0 z-10">
-      <CustomDocsNav />
-    </aside>
-
-    <!-- Main Content Area - Independent scrolling -->
-    <main
-      class="sidebar-transition w-full max-h-content ml-[22em] md:ml-[21em] lg:mr-2 2xl:mr-2 2xl:ml-[22em] pr-2 overflow-y-auto"
-    >
-      <div class="max-w-none mx-auto px-4 py-10">
-        <div class="border-b border-gray-200 flex justify-between items-start md:pb-6">
-          <div>
-            <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-black">{doc.title}</h2>
-            <p class="text-lg pt-2 text-gray-500 font-light">{doc.summary}</p>
-            {
-              badges && (
-                <div class="flex flex-wrap pt-4">
-                  {badges.map((badge: any) => {
-                    return (
-                      <a href={badge.url || '#'} class="pb-2">
-                        <span
-                          id={badge.id || ''}
-                          class={`text-sm font-light text-gray-500 px-2 py-1 rounded-md mr-2  bg-gradient-to-b  from-${badge.backgroundColor}-100 to-${badge.backgroundColor}-200 space-x-1 border border-${badge.backgroundColor}-200 text-${badge.textColor}-800 flex items-center ${badge.class ? badge.class : ''} `}
-                        >
-                          {badge.icon && <badge.icon className="w-4 h-4 inline-block mr-1 " />}
-                          {badge.iconURL && <img src={badge.iconURL} class="w-5 h-5 inline-block " />}
-                          <span>{badge.content}</span>
-                        </span>
-                      </a>
-                    );
-                  })}
-                </div>
-              )
-            }
-          </div>
-        </div>
-        <div class="flex-auto prose py-8 max-w-none">
-          <Content components={{ ...mdxComponents(props) }} />
-        </div>
-
-        {
-          nodeGraphs.length > 0 &&
-            nodeGraphs.map((nodeGraph: any) => {
-              const collection = resourceToCollectionMap[nodeGraph.type as keyof typeof resourceToCollectionMap];
-              return (
-                <NodeGraph
-                  id={nodeGraph.id}
-                  version={nodeGraph.version}
-                  collection={collection}
-                  title={nodeGraph.title}
-                  mode="simple"
-                  linksToVisualiser={true}
-                  href={
-                    isVisualiserEnabled()
-                      ? {
-                          label: 'Open in Visualiser',
-                          url: buildUrl(`/visualiser/${collection}/${nodeGraph.id}/${nodeGraph.version}`),
-                        }
-                      : undefined
-                  }
-                />
-              );
-            })
-        }
-
-        <!-- Previous / Next Navigation -->
-        <div class="py-8 border-t border-gray-200 mt-8">
-          <div class="flex flex-col sm:flex-row justify-between w-full gap-4">
-            {
-              prev && (
-                <a
-                  href={buildUrl(`/docs/custom/${prev.slug}`)}
-                  class="group flex flex-col border border-gray-200 rounded-lg p-4 hover:border-gray-300 hover:bg-gray-50 transition-colors w-full sm:w-1/2"
-                >
-                  <span class="text-sm text-gray-500 mb-1">Previous</span>
-                  <span class="font-medium group-hover:text-primary-600 transition-colors">{prev.label}</span>
-                </a>
-              )
-            }
-
-            {!prev && <div class="w-full sm:w-1/2" />}
-
-            {
-              next && (
-                <a
-                  href={buildUrl(`/docs/custom/${next.slug}`)}
-                  class="group flex flex-col items-end text-right border border-gray-200 rounded-lg p-4 hover:border-gray-300 hover:bg-gray-50 transition-colors w-full sm:w-1/2"
-                >
-                  <span class="text-sm text-gray-500 mb-1">Next</span>
-                  <span class="font-medium group-hover:text-primary-600 transition-colors">{next.label}</span>
-                </a>
-              )
-            }
-          </div>
-        </div>
-      </div>
-    </main>
-
-    <!-- Right Sidebar TOC -->
-    <aside
-      class="hidden lg:block sticky top-0 pb-10 w-80 overflow-y-auto border-l border-gray-100 bg-white p-6 flex-shrink-0 py-2"
-    >
-      <div class="py-4">
-        <div>
-          {
-            ownersList.length > 0 && (
-              <OwnersList
-                title={`Document Owners (${ownersList.length})`}
-                emptyMessage={`This page does not have any documented owners.`}
-                owners={ownersList}
-                client:load
-              />
-            )
-          }
-        </div>
-        <h3 class="text-sm text-black font-semibold group-data-[hover]:text-black/80 capitalize flex items-center gap-2">
-          <AlignLeftIcon className="w-4 h-4" />
-          On this page
-        </h3>
-        <nav class="space-y-1 text-sm py-4">
-          {
-            headings.map((heading) => {
-              if (heading.depth > 3) {
-                return null;
-              }
-              return (
-                <a
-                  href={`#${heading.slug}`}
-                  class={`block text-[12px] py-0.5 ${heading.depth === 1 ? 'font-light' : ''} text-gray-400 hover:text-primary-600`}
-                  style={`padding-left: ${(heading.depth - 1) * 8}px`}
-                >
-                  {heading.text}
-                </a>
-              );
-            })
-          }
-        </nav>
-      </div>
-    </aside>
-  </div>
-</VerticalSideBarLayout>
-
-<style is:global>
-  .mermaid svg {
-    margin: 1em auto 2em;
-  }
-
-  /* Fix for architecture diagrams */
-  .mermaid[data-content*='architecture'] svg {
-    max-width: 350px !important;
-    margin: 0;
-    /* width: 100px !important; */
-  }
-</style>
-
-<script define:vars={{ props, config }}>
-  // Fix to pass information to componets that are client side only
-  // and require catalog information
-  window.eventcatalog = {};
-  // @ts-ignore
-
-  window.eventcatalog.mermaid = config.mermaid;
-</script>
-
-<script>
-  // @ts-nocheck
-  function setupObserver() {
-    try {
-      const observerOptions = {
-        rootMargin: '0px 0px -40% 0px',
-        threshold: 0.1,
-      };
-
-      // Flag to temporarily disable observer after click
-      let observerPaused = false;
-
-      // Function to highlight a TOC item
-      function highlightTocItem(id: string) {
-        // Remove active class from all links
-        document.querySelectorAll('.active-toc-item').forEach((link) => {
-          link.classList.remove('active-toc-item', 'text-purple-600', 'font-light');
-          link.classList.add('text-gray-400');
-        });
-
-        // Add active class to current link
-        const tocLink = document.querySelector(`nav a[href="#${id}"]`);
-        if (tocLink) {
-          tocLink.classList.add('active-toc-item', 'text-purple-600', 'font-light');
-          tocLink.classList.remove('text-gray-400');
-
-          // Scroll the highlighted item into view with a small delay to ensure DOM updates first
-          setTimeout(() => {
-            tocLink.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' });
-          }, 10);
-        }
-      }
-
-      // Set up the intersection observer for scrolling
-      const observer = new IntersectionObserver((entries) => {
-        // If observer is paused, don't process entries
-        if (observerPaused) return;
-
-        entries.forEach((entry) => {
-          try {
-            const id = entry.target.getAttribute('id');
-            if (entry.isIntersecting && id) {
-              highlightTocItem(id);
-            }
-          } catch (entryError) {
-            console.error('Error processing intersection entry:', entryError);
-          }
-        });
-      }, observerOptions);
-
-      // Find all headings in the content area within the .prose container to observe
-      const prose = document.querySelector('.prose');
-      if (!prose) {
-        console.warn('No .prose container found for TOC highlighting');
-        return;
-      }
-
-      // First try to find headings with IDs
-      const headings = prose.querySelectorAll('h1[id], h2[id], h3[id]');
-
-      if (headings.length > 0) {
-        headings.forEach((heading) => {
-          observer.observe(heading);
-        });
-      } else {
-        // Fallback: If no headings with IDs found, attach IDs to them
-        const allHeadings = prose.querySelectorAll('h1, h2, h3');
-
-        allHeadings.forEach((heading) => {
-          // Only add ID if it doesn't exist
-          if (!heading.id) {
-            const text = heading.textContent || '';
-            const slug = text
-              .toLowerCase()
-              .replace(/[^\w\s-]/g, '')
-              .replace(/\s+/g, '-');
-            heading.id = slug;
-          }
-          observer.observe(heading);
-        });
-      }
-
-      // Add click event listeners to all TOC links
-      const tocLinks = document.querySelectorAll('nav a[href^="#"]');
-      tocLinks.forEach((link) => {
-        link.addEventListener('click', (e) => {
-          // Get the ID from the href attribute
-          const hrefAttr = link.getAttribute('href');
-          if (!hrefAttr) return;
-
-          const id = hrefAttr.substring(1);
-
-          // Highlight the clicked item
-          highlightTocItem(id);
-
-          // Temporarily pause the observer to prevent immediate highlighting changes
-          observerPaused = true;
-
-          // Resume the observer after a delay (1.5 seconds)
-          setTimeout(() => {
-            observerPaused = false;
-          }, 500);
-        });
-      });
-    } catch (error) {
-      console.error('Error setting up TOC highlighting:', error);
-    }
-  }
-
-  setupObserver();
-
-  document.addEventListener('astro:page-load', () => {
-    const graphs = document.getElementsByClassName('mermaid');
-    if (document.getElementsByClassName('mermaid').length > 0) {
-      renderDiagrams(graphs);
-    }
-  });
-
-  async function renderDiagrams(graphs: any) {
-    const { default: mermaid } = await import('mermaid');
-
-    if (window.eventcatalog.mermaid) {
-      const { icons } = await import('@iconify-json/logos');
-      const { iconPacks = [], enableSupportForElkLayout = false } = window.eventcatalog.mermaid ?? {};
-
-      if (iconPacks.length > 0) {
-        const iconPacksToRegister = iconPacks.map((name: string) => {
-          return {
-            name,
-            icons,
-          };
-        });
-
-        mermaid.registerIconPacks(iconPacksToRegister);
-      }
-
-      if (enableSupportForElkLayout) {
-        // @ts-ignore
-        const { default: elkLayouts } = await import('@mermaid-js/layout-elk/dist/mermaid-layout-elk.core.mjs');
-        mermaid.registerLayoutLoaders(elkLayouts);
-      }
-    }
-
-    mermaid.initialize({
-      // fontSize: 2,
-      flowchart: {
-        curve: 'linear',
-        rankSpacing: 0,
-        nodeSpacing: 0,
-      },
-      startOnLoad: false,
-      fontFamily: 'var(--sans-font)',
-      // @ts-ignore This works, but TS expects a enum for some reason
-      theme: 'light',
-      architecture: {
-        useMaxWidth: true,
-      },
-    });
-
-    for (const graph of graphs) {
-      const content = graph.getAttribute('data-content');
-      if (!content) continue;
-      let svg = document.createElement('svg');
-      const id = (svg.id = 'mermaid-' + Math.round(Math.random() * 100000));
-      graph.appendChild(svg);
-      mermaid.render(id, content).then((result) => {
-        graph.innerHTML = result.svg;
-      });
-    }
-  }
-
-  const graphs = document.getElementsByClassName('mermaid');
-  if (document.getElementsByClassName('mermaid').length > 0) {
-    renderDiagrams(graphs);
-  }
-
-  // Make renderDiagrams available globally for accordion component
-  window.renderDiagrams = renderDiagrams;
-
-  document.addEventListener('astro:page-load', setupObserver);
-</script>
-
-<script>
-  import('pako').then(({ deflate }: any) => {
-    document.addEventListener('astro:page-load', () => {
-      const blocks = document.getElementsByClassName('plantuml');
-      if (blocks.length > 0) {
-        renderPlantUML(blocks, deflate);
-      }
-    });
-
-    function renderPlantUML(blocks: any, deflate: any) {
-      for (const block of blocks) {
-        const content = block.getAttribute('data-content');
-        if (!content) continue;
-
-        const encoded = encodePlantUML(content, deflate);
-        const img = document.createElement('img');
-        img.src = `https://www.plantuml.com/plantuml/svg/~1${encoded}`;
-        img.alt = 'PlantUML diagram';
-        img.loading = 'lazy';
-        block.innerHTML = '';
-        img.classList.add('mx-auto');
-        block.appendChild(img);
-      }
-    }
-
-    function encodePlantUML(text: any, deflate: any) {
-      const utf8encoded = new TextEncoder().encode(text);
-      const compressed = deflate(utf8encoded, { level: 9 });
-      return encode64(compressed);
-    }
-
-    const encode64 = (data: any) => {
-      const chars = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_';
-      let str = '';
-      let i = 0;
-      while (i < data.length) {
-        let b1 = data[i++];
-        let b2 = i < data.length ? data[i++] : 0;
-        let b3 = i < data.length ? data[i++] : 0;
-
-        let c1 = b1 >> 2;
-        let c2 = ((b1 & 0x3) << 4) | (b2 >> 4);
-        let c3 = ((b2 & 0xf) << 2) | (b3 >> 6);
-        let c4 = b3 & 0x3f;
-
-        str += chars[c1] + chars[c2] + chars[c3] + chars[c4];
-      }
-      return str;
-    };
-
-    const graphs = document.getElementsByClassName('plantuml');
-    if (document.getElementsByClassName('plantuml').length > 0) {
-      renderPlantUML(graphs, deflate);
-    }
-
-    window.renderPlantUML = (graphs: any) => {
-      renderPlantUML(graphs, deflate);
-    };
-  });
-</script>
diff --git a/eventcatalog/src/enterprise/custom-documentation/utils/custom-docs.ts b/eventcatalog/src/enterprise/custom-documentation/utils/custom-docs.ts
deleted file mode 100644
index a2ef7ff56..000000000
--- a/eventcatalog/src/enterprise/custom-documentation/utils/custom-docs.ts
+++ /dev/null
@@ -1,215 +0,0 @@
-import config from '@config';
-import fs from 'node:fs';
-import path from 'node:path';
-import { getEntry } from 'astro:content';
-import matter from 'gray-matter';
-
-type Badge = {
-  text: string;
-  color: string;
-};
-
-type SidebarItem = {
-  label: string;
-  slug?: string;
-  items?: SidebarItem[];
-  badge?: Badge;
-  collapsed?: boolean;
-  link?: string;
-  attrs?: Record<string, string>;
-};
-
-type SideBarConfigurationItem = {
-  label: string;
-  items?: SideBarConfigurationItem[];
-  slug?: string;
-  autogenerated?: {
-    directory: string;
-    collapsed?: boolean;
-  };
-  badge?: Badge;
-  collapsed?: boolean;
-  link?: string;
-  attrs?: Record<string, string>;
-};
-
-type AdjacentPage = {
-  label: string;
-  slug: string;
-};
-
-type AdjacentPages = {
-  prev: AdjacentPage | null;
-  next: AdjacentPage | null;
-};
-
-const DOCS_DIR = 'docs';
-
-/**
- * Processes auto-generated directory and returns navigation items
- */
-const processAutoGeneratedDirectory = async (
-  directory: string,
-  label: string,
-  badge?: Badge,
-  collapsed?: boolean
-): Promise<SidebarItem> => {
-  // @ts-ignore
-  const items = fs.readdirSync(path.join(process.env.PROJECT_DIR || '', DOCS_DIR, directory));
-
-  const allItems: SidebarItem[] = [];
-
-  for (const item of items) {
-    const fullPath = path.join(process.env.PROJECT_DIR || '', DOCS_DIR, directory, item);
-    const isDirectory = fs.statSync(fullPath).isDirectory();
-
-    if (isDirectory) {
-      // Recursively process subdirectory
-      const subdirResult = await processAutoGeneratedDirectory(
-        path.join(directory, item),
-        item, // Use directory name as label
-        undefined, // No badge for subdirectories
-        collapsed // Inherit collapsed state
-      );
-      allItems.push(subdirResult);
-    } else {
-      // Process file
-      const content = fs.readFileSync(fullPath, 'utf8');
-      const { data } = matter(content);
-
-      const astroId = data.slug || path.join(DOCS_DIR, directory, item).replace('.mdx', '');
-      const entry = await getEntry('customPages', astroId.toLowerCase());
-
-      if (entry) {
-        allItems.push({
-          label: entry.data.title,
-          slug: entry.data.slug || entry.id.replace(DOCS_DIR, ''),
-        });
-      }
-    }
-  }
-
-  return {
-    label,
-    badge,
-    collapsed,
-    items: allItems,
-  };
-};
-
-/**
- * Recursively process sidebar items to handle auto-generated content at any nesting level
- */
-const processSidebarItems = async (items: SideBarConfigurationItem[]): Promise<SidebarItem[]> => {
-  const processedItems: SidebarItem[] = [];
-
-  for (const item of items) {
-    // If item has autogenerated property, process it
-    if (item.autogenerated) {
-      const processedItem = await processAutoGeneratedDirectory(
-        item.autogenerated.directory,
-        item.label,
-        item.badge,
-        item.autogenerated.collapsed !== undefined ? item.autogenerated.collapsed : item.collapsed
-      );
-      processedItems.push(processedItem);
-    }
-    // If item has nested items, process them recursively
-    else if (item.items && item.items.length > 0) {
-      const processedNestedItems = await processSidebarItems(item.items);
-      processedItems.push({
-        label: item.label,
-        slug: item.slug,
-        items: processedNestedItems,
-        badge: item.badge,
-        collapsed: item.collapsed,
-      });
-    }
-    // Otherwise, it's a regular item
-    else {
-      // if its a link, add it to the processedItems
-      if (item.link) {
-        processedItems.push({
-          label: item.label,
-          slug: item.link,
-          attrs: item.attrs,
-        });
-      } else {
-        processedItems.push(item as SidebarItem);
-      }
-    }
-  }
-
-  return processedItems;
-};
-
-/**
- * Flatten all navigation items into a single array of pages with slugs
- * This is used to find previous and next pages for navigation
- */
-const flattenNavigationItems = (items: SidebarItem[]): AdjacentPage[] => {
-  const flatPages: AdjacentPage[] = [];
-
-  const processItem = (item: SidebarItem) => {
-    // Add the current item if it has a slug
-    if (item.slug) {
-      flatPages.push({
-        label: item.label,
-        slug: item.slug,
-      });
-    }
-
-    // Process nested items if they exist
-    if (item.items && item.items.length > 0) {
-      item.items.forEach(processItem);
-    }
-  };
-
-  items.forEach(processItem);
-  return flatPages;
-};
-
-/**
- * Get the previous and next pages for a given slug
- * Returns null for prev if it's the first page, and null for next if it's the last page
- */
-export const getAdjacentPages = async (slug: string): Promise<AdjacentPages> => {
-  const navigationItems = await getNavigationItems();
-  const flatPages = flattenNavigationItems(navigationItems);
-
-  // Normalize the slug by removing 'docs/' prefix if it exists
-  // and ensure consistent formatting with or without leading slash
-  let normalizedSlug = slug;
-  if (normalizedSlug.startsWith('docs/')) {
-    normalizedSlug = normalizedSlug.substring(5); // Remove 'docs/' prefix
-  }
-
-  // Find the current page by comparing normalized slugs
-  const currentIndex = flatPages.findIndex((page) => {
-    // Normalize page slug for comparison
-    let pageSlug = page.slug;
-    if (pageSlug.startsWith('/')) {
-      pageSlug = pageSlug.substring(1);
-    }
-
-    return pageSlug === normalizedSlug;
-  });
-
-  // If page not found, return null for both prev and next
-  if (currentIndex === -1) {
-    return { prev: null, next: null };
-  }
-
-  // Get previous page if it exists
-  const prev = currentIndex > 0 ? flatPages[currentIndex - 1] : null;
-
-  // Get next page if it exists
-  const next = currentIndex < flatPages.length - 1 ? flatPages[currentIndex + 1] : null;
-
-  return { prev, next };
-};
-
-export const getNavigationItems = async (): Promise<SidebarItem[]> => {
-  const configuredSidebar = config.customDocs.sidebar;
-  return processSidebarItems(configuredSidebar as SideBarConfigurationItem[]);
-};
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/__tests__/utils/chat-prompts.spec.ts b/eventcatalog/src/enterprise/eventcatalog-chat/__tests__/utils/chat-prompts.spec.ts
deleted file mode 100644
index 303d6c760..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/__tests__/utils/chat-prompts.spec.ts
+++ /dev/null
@@ -1,94 +0,0 @@
-import type { ContentCollectionKey } from 'astro:content';
-import { expect, describe, it, vi, beforeEach } from 'vitest';
-import type { ChatPrompt } from '../../utils/chat-prompts';
-
-// Mock data for chat prompts
-const mockChatPrompts: ChatPrompt[] = [
-  {
-    id: 'prompt1.md',
-    body: 'Prompt 1 body',
-    collection: 'chatPrompts',
-    data: {
-      title: 'Prompt 1',
-      type: 'text',
-      category: { id: 'cat1', label: 'Category 1', icon: '💡' },
-    },
-  },
-  {
-    id: 'prompt2.md',
-    body: 'Prompt 2 body',
-    collection: 'chatPrompts',
-    data: {
-      title: 'Prompt 2',
-      type: 'text',
-      category: { id: 'cat1', label: 'Category 1', icon: '💡' },
-    },
-  },
-  {
-    id: 'prompt3.md',
-    body: 'Prompt 3 body',
-    collection: 'chatPrompts',
-    data: {
-      title: 'Prompt 3',
-      type: 'text',
-      category: { id: 'cat2', label: 'Category 2' },
-    },
-  },
-];
-
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    getCollection: (key: ContentCollectionKey) => {
-      switch (key) {
-        case 'chatPrompts':
-          return Promise.resolve(mockChatPrompts);
-        default:
-          return Promise.resolve([]);
-      }
-    },
-  };
-});
-
-// Clear cache before each test
-beforeEach(() => {
-  vi.resetModules();
-});
-
-describe('Chat Prompts Utilities', () => {
-  describe('getChatPrompts', () => {
-    it('should return an array of chat prompts', async () => {
-      // Need to re-import after vi.resetModules()
-      const { getChatPrompts } = await import('../../utils/chat-prompts');
-      const prompts = await getChatPrompts();
-      expect(prompts).toEqual(mockChatPrompts);
-    });
-  });
-
-  describe('getChatPromptsGroupedByCategory', () => {
-    it('should group chat prompts by category', async () => {
-      // Re-import after reset
-      const { getChatPromptsGroupedByCategory } = await import('../../utils/chat-prompts');
-      const groupedPrompts = await getChatPromptsGroupedByCategory();
-
-      const expectedGrouping = [
-        {
-          label: 'Category 1',
-          icon: '💡',
-          items: [mockChatPrompts[0], mockChatPrompts[1]],
-        },
-        {
-          label: 'Category 2',
-          icon: undefined, // No icon provided for cat2 in mock data
-          items: [mockChatPrompts[2]],
-        },
-      ];
-
-      // Use expect.arrayContaining because the order of categories is not guaranteed
-      expect(groupedPrompts).toEqual(
-        expect.arrayContaining([expect.objectContaining(expectedGrouping[0]), expect.objectContaining(expectedGrouping[1])])
-      );
-      expect(groupedPrompts.length).toBe(expectedGrouping.length); // Ensure no extra categories
-    });
-  });
-});
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/components/Chat.tsx b/eventcatalog/src/enterprise/eventcatalog-chat/components/Chat.tsx
deleted file mode 100644
index 35ac96c41..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/components/Chat.tsx
+++ /dev/null
@@ -1,60 +0,0 @@
-import Sidebar from './ChatSidebar';
-import { ChatProvider } from './hooks/ChatProvider';
-import ChatWindowServer from './windows/ChatWindow.server';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import type { ChatPromptCategoryGroup } from '@enterprise/eventcatalog-chat/utils/chat-prompts';
-interface Resource {
-  id: string;
-  type: string;
-  name: string;
-}
-
-/**
- * Chat component has two modes:
- * - Server: ChatWindow.server.tsx (uses server-side code, bring your own API key)
- *
- * The mode is determined by the config.output property in the eventcatalog.config.js file.
- */
-
-const Chat = ({
-  chatConfig,
-  resources,
-  chatPrompts,
-  output,
-}: {
-  chatConfig: any;
-  resources: Resource[];
-  chatPrompts: ChatPromptCategoryGroup[];
-  output: 'static' | 'server';
-}) => {
-  const queryClient = new QueryClient();
-
-  if (output !== 'server') {
-    return (
-      // Message to turn on server side
-      <div className="flex justify-center items-center h-full bg-gray-100 p-4 rounded-lg text-center">
-        <div className="space-y-4">
-          <h1 className="text-3xl font-semibold text-gray-800">Chat is only supported on server side</h1>
-          <p className="text-sm text-gray-500">
-            Please switch to server side by setting the <code className="font-mono bg-gray-100 p-0.5 rounded">output</code>{' '}
-            property to <code className="font-mono bg-gray-100 p-0.5 rounded">server</code> in your{' '}
-            <code className="font-mono bg-gray-100 p-0.5 rounded">eventcatalog.config.js</code> file.
-          </p>
-        </div>
-      </div>
-    );
-  }
-
-  return (
-    <ChatProvider>
-      <div className="flex overflow-hidden w-full">
-        <Sidebar />
-        <QueryClientProvider client={queryClient}>
-          <ChatWindowServer {...chatConfig} resources={resources} chatPrompts={chatPrompts} />
-        </QueryClientProvider>
-      </div>
-    </ChatProvider>
-  );
-};
-
-export default Chat;
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/components/ChatMessage.tsx b/eventcatalog/src/enterprise/eventcatalog-chat/components/ChatMessage.tsx
deleted file mode 100644
index 8bb5c581d..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/components/ChatMessage.tsx
+++ /dev/null
@@ -1,414 +0,0 @@
-import React, { useState } from 'react';
-import ReactMarkdown, { type ExtraProps } from 'react-markdown';
-import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
-import { vscDarkPlus } from 'react-syntax-highlighter/dist/esm/styles/prism';
-import type { Message } from '@enterprise/eventcatalog-chat/components/hooks/ChatProvider';
-import * as Dialog from '@radix-ui/react-dialog';
-import { Fullscreen, X, Clipboard, Check, ChevronDown, ChevronRight } from 'lucide-react'; // Add Clipboard, Check, ChevronDown, ChevronRight icons
-
-// Define Resource type locally
-interface Resource {
-  id: string;
-  type: string;
-  url: string;
-  title?: string;
-  name?: string | null; // Allow null for name
-}
-
-interface ChatMessageProps {
-  message: Message;
-}
-
-// Function to escape special characters for regex
-function escapeRegex(string: string): string {
-  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-// Function to parse and render content with iframes
-function parseContentWithIframes(content: string): React.ReactNode[] {
-  const iframeRegex = /<iframe[^>]*>.*?<\/iframe>/gi;
-  const parts: React.ReactNode[] = [];
-  let lastIndex = 0;
-  let match;
-
-  while ((match = iframeRegex.exec(content)) !== null) {
-    // Add text before iframe as markdown
-    if (match.index > lastIndex) {
-      const textBefore = content.slice(lastIndex, match.index);
-      if (textBefore.trim()) {
-        parts.push(
-          <ReactMarkdown
-            key={`text-${lastIndex}`}
-            components={{
-              code({ node, className, children, ...props }: CodeComponentProps) {
-                const inline = props.inline;
-                const match = /language-(\w+)/.exec(className || '');
-                const codeString = String(children);
-                const language = match ? match[1] : 'text';
-                const codeBlockId = `code-${React.useId()}`;
-                const isCopied = false; // We'll handle this in the parent component
-
-                const treatAsInline = inline || !codeString.includes('\n');
-
-                return !treatAsInline ? (
-                  <div className="code-block bg-[#1e1e1e] rounded-md overflow-hidden my-4 relative group">
-                    <div className="flex justify-between items-center px-4 py-1.5 bg-gray-700 text-gray-300 text-xs">
-                      <span>{language}</span>
-                    </div>
-                    <SyntaxHighlighter
-                      style={vscDarkPlus as any}
-                      language={language}
-                      PreTag="div"
-                      showLineNumbers
-                      wrapLines={true}
-                      customStyle={{ margin: 0, borderRadius: '0 0 0.375rem 0.375rem', padding: '1rem' }}
-                    >
-                      {codeString.replace(/\n$/, '')}
-                    </SyntaxHighlighter>
-                  </div>
-                ) : (
-                  <code
-                    className={`px-1 py-0.5 rounded text-xs font-mono bg-gray-300/70 text-gray-900 ${className || ''}`}
-                    {...props}
-                  >
-                    {codeString.trim()}
-                  </code>
-                );
-              },
-              a: ({ node, ...props }) => (
-                <a {...props} target="_blank" rel="noopener noreferrer" className="text-purple-600 hover:text-purple-800" />
-              ),
-              p: ({ node, ...props }) => <p {...props} className="mb-2 last:mb-0" />,
-            }}
-          >
-            {textBefore}
-          </ReactMarkdown>
-        );
-      }
-    }
-
-    // Parse iframe attributes
-    const iframeHtml = match[0];
-    const srcMatch = iframeHtml.match(/src=["']([^"']+)["']/i);
-    const widthMatch = iframeHtml.match(/width=["']([^"']+)["']/i);
-    const heightMatch = iframeHtml.match(/height=["']([^"']+)["']/i);
-    const titleMatch = iframeHtml.match(/title=["']([^"']+)["']/i);
-
-    if (srcMatch) {
-      parts.push(
-        <iframe
-          key={`iframe-${match.index}`}
-          src={srcMatch[1]}
-          width={widthMatch ? widthMatch[1] : '100%'}
-          height={heightMatch ? heightMatch[1] : '400'}
-          title={titleMatch ? titleMatch[1] : 'Embedded content'}
-          className="w-full h-96 border rounded-lg my-4"
-          sandbox="allow-scripts allow-same-origin allow-popups allow-forms"
-          loading="lazy"
-        />
-      );
-    }
-
-    lastIndex = match.index + match[0].length;
-  }
-
-  // Add remaining text after last iframe
-  if (lastIndex < content.length) {
-    const textAfter = content.slice(lastIndex);
-    if (textAfter.trim()) {
-      parts.push(
-        <ReactMarkdown
-          key={`text-${lastIndex}`}
-          components={{
-            code({ node, className, children, ...props }: CodeComponentProps) {
-              const inline = props.inline;
-              const match = /language-(\w+)/.exec(className || '');
-              const codeString = String(children);
-              const language = match ? match[1] : 'text';
-              const codeBlockId = `code-${React.useId()}`;
-              const isCopied = false;
-
-              const treatAsInline = inline || !codeString.includes('\n');
-
-              return !treatAsInline ? (
-                <div className="code-block bg-[#1e1e1e] rounded-md overflow-hidden my-4 relative group">
-                  <div className="flex justify-between items-center px-4 py-1.5 bg-gray-700 text-gray-300 text-xs">
-                    <span>{language}</span>
-                  </div>
-                  <SyntaxHighlighter
-                    style={vscDarkPlus as any}
-                    language={language}
-                    PreTag="div"
-                    showLineNumbers
-                    wrapLines={true}
-                    customStyle={{ margin: 0, borderRadius: '0 0 0.375rem 0.375rem', padding: '1rem' }}
-                  >
-                    {codeString.replace(/\n$/, '')}
-                  </SyntaxHighlighter>
-                </div>
-              ) : (
-                <code
-                  className={`px-1 py-0.5 rounded text-xs font-mono bg-gray-300/70 text-gray-900 ${className || ''}`}
-                  {...props}
-                >
-                  {codeString.trim()}
-                </code>
-              );
-            },
-            a: ({ node, ...props }) => (
-              <a {...props} target="_blank" rel="noopener noreferrer" className="text-purple-600 hover:text-purple-800" />
-            ),
-            p: ({ node, ...props }) => <p {...props} className="mb-2 last:mb-0" />,
-          }}
-        >
-          {textAfter}
-        </ReactMarkdown>
-      );
-    }
-  }
-
-  return parts;
-}
-
-// Define props for the code component explicitly
-interface CodeComponentProps extends React.HTMLAttributes<HTMLElement>, ExtraProps {
-  inline?: boolean;
-}
-
-const ChatMessage = React.memo(({ message }: ChatMessageProps) => {
-  const [isModalOpen, setIsModalOpen] = useState(false);
-  const [modalContent, setModalContent] = useState<{ language: string; code: string } | null>(null);
-  const [copiedStates, setCopiedStates] = useState<Record<string, boolean>>({}); // State for copy feedback
-  const [isResourcesCollapsed, setIsResourcesCollapsed] = useState(true); // State for resource section collapse
-  const [isContextCollapsed, setIsContextCollapsed] = useState(true); // State for additional context collapse
-
-  // Helper to get display name for resource, ensuring a fallback
-  const getResourceDisplayName = (resource: Resource): string => {
-    return resource.title || resource.name || resource.id || 'Resource'; // Added fallback
-  };
-
-  const handleCopy = (codeToCopy: string, id: string) => {
-    navigator.clipboard
-      .writeText(codeToCopy)
-      .then(() => {
-        setCopiedStates((prev) => ({ ...prev, [id]: true }));
-        setTimeout(() => {
-          setCopiedStates((prev) => ({ ...prev, [id]: false }));
-        }, 1500); // Reset after 1.5 seconds
-      })
-      .catch((err) => {
-        console.error('Failed to copy code: ', err);
-      });
-  };
-
-  return (
-    <div className={`flex ${message.isUser ? 'justify-end' : 'justify-start'} mb-4`}>
-      <div
-        className={`max-w-[80%] rounded-lg p-3 ${message.isUser ? 'bg-purple-600 text-white rounded-br-none' : 'bg-gray-100 text-gray-800 rounded-bl-none'}`}
-      >
-        {/* Apply prose styles, including prose-invert for user messages for better text contrast */}
-        <div className={`prose prose-sm max-w-none ${message.isUser ? 'prose-invert' : ''}`}>
-          {(() => {
-            const content = message.content || '';
-            const iframeRegex = /<iframe[^>]*>.*?<\/iframe>/gi;
-
-            // If content contains iframes, use custom parser
-            if (iframeRegex.test(content)) {
-              return parseContentWithIframes(content);
-            }
-
-            // Otherwise, use regular ReactMarkdown
-            return (
-              <ReactMarkdown
-                components={{
-                  code({ node, className, children, ...props }: CodeComponentProps) {
-                    const inline = props.inline;
-                    const match = /language-(\w+)/.exec(className || '');
-                    const codeString = String(children);
-                    const language = match ? match[1] : 'text';
-                    const codeBlockId = `code-${React.useId()}`;
-                    const isCopied = copiedStates[codeBlockId];
-
-                    const handleOpenModal = () => {
-                      setModalContent({ language, code: codeString.replace(/\n$/, '') });
-                      setIsModalOpen(true);
-                    };
-
-                    // Heuristic: Treat as inline if it doesn't contain newlines OR if explicitly inline.
-                    // This handles parser quirks with single-line snippets in lists, etc.
-                    const treatAsInline = inline || !codeString.includes('\n');
-
-                    return !treatAsInline ? (
-                      <div className="code-block bg-[#1e1e1e] rounded-md overflow-hidden my-4 relative group">
-                        <div className="flex justify-between items-center px-4 py-1.5 bg-gray-700 text-gray-300 text-xs">
-                          <span>{language}</span>
-                          <div className="flex items-center gap-2">
-                            <button
-                              onClick={() => handleCopy(codeString.replace(/\n$/, ''), codeBlockId)}
-                              className="text-gray-300 hover:text-white flex items-center"
-                              aria-label={isCopied ? 'Copied' : 'Copy code'}
-                            >
-                              {isCopied ? <Check size={14} className="text-green-400" /> : <Clipboard size={14} />}
-                            </button>
-                            <button
-                              onClick={handleOpenModal}
-                              className="text-gray-300 hover:text-white"
-                              aria-label="View code fullscreen"
-                            >
-                              <Fullscreen size={14} />
-                            </button>
-                          </div>
-                        </div>
-                        <SyntaxHighlighter
-                          style={vscDarkPlus as any}
-                          language={language}
-                          PreTag="div"
-                          showLineNumbers
-                          wrapLines={true}
-                          customStyle={{ margin: 0, borderRadius: '0 0 0.375rem 0.375rem', padding: '1rem' }}
-                        >
-                          {codeString.replace(/\n$/, '')}
-                        </SyntaxHighlighter>
-                      </div>
-                    ) : (
-                      <code
-                        className={`px-1 py-0.5 rounded text-xs font-mono ${
-                          message.isUser
-                            ? 'bg-purple-800/70 text-purple-100' // Darker purple bg, light text for user
-                            : 'bg-gray-300/70 text-gray-900' // Darker gray bg, dark text for assistant
-                        } ${className || ''}`}
-                        {...props}
-                      >
-                        {/* Render trimmed version for inline code */}
-                        {codeString.trim()}
-                      </code>
-                    );
-                  },
-                  a: ({ node, ...props }) => (
-                    <a {...props} target="_blank" rel="noopener noreferrer" className="text-purple-600 hover:text-purple-800" />
-                  ),
-                  p: ({ node, ...props }) => <p {...props} className="mb-2 last:mb-0" />,
-                }}
-              >
-                {content}
-              </ReactMarkdown>
-            );
-          })()}
-        </div>
-
-        {/* Additional Context section (for user messages) */}
-        {message.isUser && message.additionalContext && (
-          <div className="mt-3 pt-3 border-t border-purple-700/50">
-            {' '}
-            {/* Adjusted border color for subtlety */}
-            <button
-              className="flex items-center text-xs text-purple-300 mb-1 w-full text-left focus:outline-none" // Adjusted text color for subtlety
-              onClick={() => setIsContextCollapsed(!isContextCollapsed)}
-              aria-expanded={!isContextCollapsed}
-              aria-controls="additional-context-content"
-            >
-              {isContextCollapsed ? <ChevronRight size={14} className="mr-1" /> : <ChevronDown size={14} className="mr-1" />}
-              Prompt used:
-            </button>
-            {!isContextCollapsed && (
-              <div className="text-[10px] mt-1 pl-5 prose prose-sm prose-invert" id="additional-context-content">
-                {' '}
-                {/* Removed max-w-none */}
-                <pre className="whitespace-pre-wrap break-words">{message.additionalContext}</pre> {/* Use pre for formatting */}
-              </div>
-            )}
-          </div>
-        )}
-
-        {/* Resource section */}
-        {!message.isUser && message.resources && message.resources.length > 0 && (
-          <div className="mt-3 pt-3 border-t border-gray-200">
-            {/* Make the title clickable to toggle collapse */}
-            <button
-              className="flex items-center text-xs text-gray-500 mb-1 w-full text-left focus:outline-none"
-              onClick={() => setIsResourcesCollapsed(!isResourcesCollapsed)}
-              aria-expanded={!isResourcesCollapsed}
-              aria-controls="resource-list"
-            >
-              {isResourcesCollapsed ? <ChevronRight size={14} className="mr-1" /> : <ChevronDown size={14} className="mr-1" />}
-              Referenced Resources:
-            </button>
-            {/* Conditionally render the list based on the collapsed state */}
-            {!isResourcesCollapsed && (
-              <div className="text-[10px] mt-1 pl-5" id="resource-list">
-                {' '}
-                {/* Added pl-5 for indentation */}
-                {(message.resources as Resource[]).map((resource: Resource, idx: number) => (
-                  <span key={resource.id || `res-${idx}`}>
-                    <a
-                      href={resource.url}
-                      className="text-purple-600 hover:text-purple-800"
-                      target="_blank"
-                      rel="noopener noreferrer"
-                    >
-                      {/* Use helper function for clarity and add parentheses for operator precedence */}
-                      {getResourceDisplayName(resource)} ({resource.type})
-                    </a>
-                    {idx < (message.resources?.length || 0) - 1 ? ', ' : ''}
-                  </span>
-                ))}
-              </div>
-            )}
-          </div>
-        )}
-      </div>
-
-      {/* Fullscreen Code Modal */}
-      <Dialog.Root open={isModalOpen} onOpenChange={setIsModalOpen}>
-        <Dialog.Portal>
-          {/* Add z-index and animations to Overlay */}
-          {/* NOTE: Define overlayShow/overlayHide keyframes in CSS/Tailwind config */}
-          <Dialog.Overlay className="fixed inset-0 bg-black/60 z-50 data-[state=open]:animate-overlayShow data-[state=closed]:animate-overlayHide" />
-          {/* Add z-index and animations to Content */}
-          {/* NOTE: Define contentShow/contentHide keyframes in CSS/Tailwind config */}
-          <Dialog.Content className="fixed left-1/2 top-1/2 z-[100] w-[90vw] max-w-4xl max-h-[85vh] -translate-x-1/2 -translate-y-1/2 rounded-lg bg-[#1e1e1e] p-0 shadow-lg focus:outline-none data-[state=open]:animate-contentShow data-[state=closed]:animate-contentHide overflow-hidden flex flex-col">
-            {/* Modal Header with Copy Button */}
-            <div className="flex justify-between items-center px-4 py-2.5 bg-gray-700 text-gray-300 text-sm flex-shrink-0 border-b border-gray-600">
-              <Dialog.Title className="font-medium">{modalContent?.language}</Dialog.Title>
-              <div className="flex items-center gap-3">
-                {modalContent && (
-                  <button
-                    onClick={() => handleCopy(modalContent.code, 'modal-copy')}
-                    className="text-gray-300 hover:text-white flex items-center gap-1 text-xs"
-                    aria-label={copiedStates['modal-copy'] ? 'Copied' : 'Copy code'}
-                  >
-                    {copiedStates['modal-copy'] ? <Check size={14} className="text-green-400" /> : <Clipboard size={14} />}
-                    {copiedStates['modal-copy'] ? 'Copied!' : 'Copy'}
-                  </button>
-                )}
-                <Dialog.Close asChild>
-                  <button className="text-gray-300 hover:text-white" aria-label="Close">
-                    <X size={18} />
-                  </button>
-                </Dialog.Close>
-              </div>
-            </div>
-            <div className="flex-grow overflow-auto">
-              {modalContent && (
-                <SyntaxHighlighter
-                  style={vscDarkPlus as any}
-                  language={modalContent.language}
-                  PreTag="div"
-                  showLineNumbers
-                  wrapLines={true}
-                  customStyle={{ margin: 0, height: '100%', padding: '1rem' }} // Ensure it fills height and has padding
-                >
-                  {modalContent.code}
-                </SyntaxHighlighter>
-              )}
-            </div>
-          </Dialog.Content>
-        </Dialog.Portal>
-      </Dialog.Root>
-    </div>
-  );
-});
-
-ChatMessage.displayName = 'ChatMessage';
-
-export default ChatMessage;
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/components/ChatSidebar.tsx b/eventcatalog/src/enterprise/eventcatalog-chat/components/ChatSidebar.tsx
deleted file mode 100644
index c626b2345..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/components/ChatSidebar.tsx
+++ /dev/null
@@ -1,169 +0,0 @@
-import React, { useEffect } from 'react';
-import { format } from 'date-fns';
-import { useChat } from './hooks/ChatProvider';
-import * as Dialog from '@radix-ui/react-dialog';
-
-const Sidebar: React.FC<{}> = () => {
-  const { sessions = [], currentSession, createSession, deleteSession, setCurrentSession, isStreaming } = useChat();
-  const [showHelp, setShowHelp] = React.useState(false);
-
-  useEffect(() => {
-    // Check if this is the first visit after component mounts
-    const hasVisited = localStorage.getItem('eventCatalogAIVisited');
-    if (!hasVisited || hasVisited === 'false') {
-      localStorage.setItem('eventCatalogAIVisited', 'true');
-      setShowHelp(true);
-    }
-  }, []);
-
-  useEffect(() => {
-    if (sessions.length === 0) {
-      createSession();
-    }
-  }, [sessions]);
-
-  return (
-    <div className="h-[calc(100vh-64px)] bg-gray-50 flex-shrink-0 border-r border-gray-200">
-      <div className="w-64 bg-gray-50 border-r border-gray-200 flex flex-col h-full">
-        {/* New Chat Button */}
-        <div className="p-4 border-b border-gray-200">
-          <div className="flex items-center justify-between gap-2">
-            <button
-              onClick={createSession}
-              disabled={isStreaming}
-              className={`flex-1 flex items-center justify-between px-3 py-2 text-sm bg-white hover:bg-gray-100 rounded-lg border border-gray-200 text-gray-700 ${isStreaming ? 'opacity-50 cursor-not-allowed' : ''}`}
-            >
-              <span>New chat</span>
-              <svg xmlns="http://www.w3.org/2000/svg" className="h-4 w-4" viewBox="0 0 20 20" fill="currentColor">
-                <path
-                  fillRule="evenodd"
-                  d="M10 3a1 1 0 011 1v5h5a1 1 0 110 2h-5v5a1 1 0 11-2 0v-5H4a1 1 0 110-2h5V4a1 1 0 011-1z"
-                  clipRule="evenodd"
-                />
-              </svg>
-            </button>
-          </div>
-        </div>
-
-        {/* Chat History */}
-        <div className="flex-1 overflow-y-auto">
-          <div className="p-2 space-y-2">
-            <div className="text-xs text-gray-500 px-2 py-1">Your chats</div>
-            <div className="space-y-1">
-              {sessions.map((session) => (
-                <div
-                  key={session.id}
-                  className={`group relative flex flex-col ${
-                    currentSession?.id === session.id ? 'bg-gray-100' : 'hover:bg-gray-50'
-                  } rounded-lg`}
-                >
-                  <button
-                    onClick={(e) => deleteSession(session.id)}
-                    disabled={isStreaming}
-                    className={`absolute right-1 top-1 p-1.5 opacity-0 group-hover:opacity-100 transition-opacity duration-200 text-gray-400 hover:text-gray-600 ${currentSession?.id === session.id ? 'opacity-100' : ''} ${isStreaming ? 'opacity-50 cursor-not-allowed' : ''}`}
-                    title="Delete chat"
-                  >
-                    <svg xmlns="http://www.w3.org/2000/svg" className="h-3.5 w-3.5" viewBox="0 0 20 20" fill="currentColor">
-                      <path
-                        fillRule="evenodd"
-                        d="M9 2a1 1 0 00-.894.553L7.382 4H4a1 1 0 000 2v10a2 2 0 002 2h8a2 2 0 002-2V6a1 1 0 100-2h-3.382l-.724-1.447A1 1 0 0011 2H9zM7 8a1 1 0 012 0v6a1 1 0 11-2 0V8zm5-1a1 1 0 00-1 1v6a1 1 0 102 0V8a1 1 0 00-1-1z"
-                        clipRule="evenodd"
-                      />
-                    </svg>
-                  </button>
-                  <button
-                    onClick={() => setCurrentSession(session)}
-                    disabled={isStreaming}
-                    className={`flex-1 text-left px-3 py-2 text-sm ${isStreaming ? 'opacity-50 cursor-not-allowed' : ''}`}
-                  >
-                    <div className="font-medium text-gray-700 pr-7">{session.title}</div>
-                    <div className="flex justify-between items-center mt-1 text-xs text-gray-400">
-                      <span>{session.messages.length} messages</span>
-                      <span>{format(session.lastUpdated, 'dd/MM/yyyy, HH:mm:ss')}</span>
-                    </div>
-                  </button>
-                </div>
-              ))}
-            </div>
-          </div>
-        </div>
-
-        {/* Beta Message */}
-        <div className="p-4 text-xs text-gray-500 border-t border-gray-200">
-          <div>
-            Have issues or ideas? Let us know on{' '}
-            <a
-              href="https://discord.com/channels/918092420338569216/1342473496957288581"
-              className="text-blue-600 hover:text-blue-800 underline"
-              target="_blank"
-              rel="noopener noreferrer"
-            >
-              Discord
-            </a>
-            <div className="inline-block">
-              <Dialog.Root open={showHelp} onOpenChange={setShowHelp}>
-                <Dialog.Trigger asChild>
-                  <button title="Help" className="p-1.5 text-gray-500 hover:text-gray-700 hover:bg-gray-100 rounded-lg">
-                    <svg xmlns="http://www.w3.org/2000/svg" className="h-3 w-3" viewBox="0 0 20 20" fill="currentColor">
-                      <path
-                        fillRule="evenodd"
-                        d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-8-3a1 1 0 00-.867.5 1 1 0 11-1.731-1A3 3 0 0113 8a3.001 3.001 0 01-2 2.83V11a1 1 0 11-2 0v-1a1 1 0 011-1 1 1 0 100-2zm0 8a1 1 0 100-2 1 1 0 000 2z"
-                        clipRule="evenodd"
-                      />
-                    </svg>
-                  </button>
-                </Dialog.Trigger>
-                <Dialog.Portal>
-                  <Dialog.Overlay className="fixed inset-0 bg-black/50 z-40" />
-                  <Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white rounded-lg z-50 p-6 w-[600px] max-h-[85vh] overflow-y-auto">
-                    <Dialog.Title className="text-lg font-semibold text-gray-900 mb-4">
-                      Welcome to the EventCatalog AI Assistant
-                    </Dialog.Title>
-                    <div className="text-sm text-gray-600 space-y-4">
-                      <p>
-                        This is your private AI assistant for EventCatalog. All conversations are stored locally and your data
-                        remains completely private.
-                      </p>
-                      <p>Key features:</p>
-                      <ul className="list-disc pl-4 space-y-2">
-                        <li>Local-first: All conversations are stored on your device only</li>
-                        <li>Privacy-focused: Your data is never shared with external servers</li>
-                        <li>Persistent chat history: Access your previous conversations anytime</li>
-                        <li>Multiple sessions: Organize different topics in separate chats</li>
-                      </ul>
-
-                      <div className="mt-6">
-                        <p className="font-medium mb-2">Example prompts you can try:</p>
-                        <ul className="list-disc pl-4 space-y-2 bg-gray-50 p-4 rounded-lg">
-                          <li>"I want to create a new feature, what events do we have related to Payments?"</li>
-                          <li>"What domains do we have and who owns them?"</li>
-                          <li>"What are the events for the X domain?"</li>
-                          <li>"Create me a code snippet for this event"</li>
-                        </ul>
-                      </div>
-
-                      <p className="mt-4">For additional support or feature requests, please join our Discord community.</p>
-                    </div>
-                    <Dialog.Close asChild>
-                      <button className="absolute top-4 right-4 text-gray-400 hover:text-gray-600" aria-label="Close">
-                        <svg xmlns="http://www.w3.org/2000/svg" className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor">
-                          <path
-                            fillRule="evenodd"
-                            d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z"
-                            clipRule="evenodd"
-                          />
-                        </svg>
-                      </button>
-                    </Dialog.Close>
-                  </Dialog.Content>
-                </Dialog.Portal>
-              </Dialog.Root>
-            </div>
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-};
-
-export default Sidebar;
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/components/InputModal.tsx b/eventcatalog/src/enterprise/eventcatalog-chat/components/InputModal.tsx
deleted file mode 100644
index bbc9380fe..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/components/InputModal.tsx
+++ /dev/null
@@ -1,244 +0,0 @@
-import React, { useEffect, useState, useMemo } from 'react';
-import * as Dialog from '@radix-ui/react-dialog';
-import { Wand2 } from 'lucide-react';
-// TODO: Import ChatPrompt and ChatPromptInput from a central types location
-import type { ChatPrompt } from '@enterprise/eventcatalog-chat/utils/chat-prompts';
-
-// Define the possible resource list types
-type ResourceListType = 'resource-list-events' | 'resource-list-commands' | 'resource-list-services' | 'resource-list-queries';
-
-// Define ChatPromptInput type based on usage
-// NOTE: This should ideally match the schema defined for Astro content collections
-interface ChatPromptInput {
-  id: string;
-  label: string;
-  type: 'text' | ResourceListType | 'select' | 'code' | 'text-area'; // Use the union type, add 'select', 'code', 'text-area'
-  options?: string[]; // Add optional options for select type
-}
-
-// Define Resource type based on usage in ChatWindow
-interface Resource {
-  id: string;
-  type: string; // e.g., 'event', 'command', 'service', 'query'
-  url: string;
-  title?: string;
-  name?: string;
-}
-
-// --- Input Modal Component ---
-interface InputModalProps {
-  isOpen: boolean;
-  onClose: () => void;
-  prompt: ChatPrompt | null;
-  onSubmit: (prompt: ChatPrompt, inputValues: Record<string, string>) => void;
-  resources: Resource[]; // Add resources prop
-}
-
-// Helper to extract resource type from input type string
-const getResourceTypeFromInputType = (inputType: ResourceListType): string => {
-  return inputType.replace('resource-list-', '');
-};
-
-const InputModal: React.FC<InputModalProps> = ({ isOpen, onClose, prompt, onSubmit, resources }) => {
-  const [inputValues, setInputValues] = useState<Record<string, string>>({});
-
-  // Memoize resource filtering based on prompt inputs
-  const filteredResourcesByType = useMemo(() => {
-    const resourceMap: Record<string, Resource[]> = {};
-    prompt?.data?.inputs?.forEach((input) => {
-      if (input.type.startsWith('resource-list-')) {
-        const resourceType = getResourceTypeFromInputType(input.type as ResourceListType);
-        const filtered = resources.filter((r) => r.type === resourceType);
-        resourceMap[input.id] = filtered;
-      }
-    });
-    return resourceMap;
-  }, [prompt, resources]);
-
-  // Reset input values when the prompt or resources change
-  useEffect(() => {
-    if (prompt?.data?.inputs) {
-      const initialValues: Record<string, string> = {};
-      prompt.data.inputs.forEach((input) => {
-        const relevantResources = filteredResourcesByType[input.id];
-        if (input.type.startsWith('resource-list-') && relevantResources?.length > 0) {
-          initialValues[input.id] = relevantResources[0].id; // Pre-select the first available resource
-        } else {
-          initialValues[input.id] = ''; // Initialize others with empty strings
-        }
-      });
-      setInputValues(initialValues);
-    } else {
-      setInputValues({}); // Clear if no inputs
-    }
-  }, [prompt, filteredResourcesByType]); // Depend on memoized filtered resources
-
-  if (!prompt || !prompt.data?.inputs) {
-    return null; // Don't render if no prompt or inputs
-  }
-
-  const handleInputChange = (id: string, value: string) => {
-    setInputValues((prev) => ({ ...prev, [id]: value }));
-  };
-
-  const handleSubmit = (e: React.FormEvent) => {
-    e.preventDefault();
-    // Basic validation: Check if all required fields are filled
-    const allFilled = prompt?.data?.inputs?.every((input) => {
-      if (input.type.startsWith('resource-list-')) {
-        return inputValues[input.id] && inputValues[input.id] !== '';
-      }
-      return inputValues[input.id]?.trim();
-    });
-
-    if (allFilled) {
-      // Pass the selected resource NAME for resource lists, not the ID
-      const processedValues = { ...inputValues };
-      prompt.data.inputs?.forEach((input) => {
-        if (input.type.startsWith('resource-list-')) {
-          const relevantResources = filteredResourcesByType[input.id] || [];
-          const selectedResource = relevantResources.find((r) => r.id === processedValues[input.id]);
-          // Use resource name if available, otherwise fallback to the submitted ID (which might be name if no resource found)
-          processedValues[input.id] = selectedResource?.name || processedValues[input.id];
-        }
-      });
-      onSubmit(prompt, processedValues);
-    } else {
-      alert('Please fill in all required fields.');
-    }
-  };
-
-  return (
-    <Dialog.Root open={isOpen} onOpenChange={onClose}>
-      <Dialog.Portal>
-        <Dialog.Overlay className="fixed inset-0 bg-black/50 data-[state=open]:animate-overlayShow z-50" />
-        <Dialog.Content className="fixed top-1/2 left-1/2 w-[90vw] max-w-lg -translate-x-1/2 -translate-y-1/2 rounded-lg bg-gray-50 p-8 shadow-xl focus:outline-none data-[state=open]:animate-contentShow z-[100]">
-          <Dialog.Title className="text-lg font-semibold text-gray-800 mb-3">{prompt.data.title}</Dialog.Title>
-          <Dialog.Description className="mt-1 mb-6 text-sm text-gray-600">
-            Please provide the following details:
-          </Dialog.Description>
-          <form onSubmit={handleSubmit} className="space-y-4">
-            {prompt.data.inputs.map((input: ChatPromptInput) => {
-              const isResourceList = input.type.startsWith('resource-list-');
-              const isSelect = input.type === 'select';
-              const isCode = input.type === 'code';
-              const isTextArea = input.type === 'text-area'; // Added for potential future use or consistency
-              const resourceType = isResourceList ? getResourceTypeFromInputType(input.type as ResourceListType) : '';
-              const relevantResources = filteredResourcesByType[input.id] || [];
-
-              return (
-                <div key={input.id}>
-                  <label htmlFor={input.id} className="block text-sm font-medium text-gray-700 mb-1.5">
-                    {input.label}
-                  </label>
-                  {isResourceList ? (
-                    <select
-                      id={input.id}
-                      name={input.id}
-                      value={inputValues[input.id] || ''}
-                      onChange={(e) => handleInputChange(input.id, e.target.value)}
-                      required
-                      className="w-full rounded-md border border-gray-300 bg-white px-3 py-2 shadow-sm focus:border-purple-500 focus:outline-none focus:ring-2 focus:ring-purple-300 focus:ring-offset-1 sm:text-sm transition duration-150 ease-in-out"
-                    >
-                      <option value="" disabled>
-                        Select a {resourceType}...
-                      </option>
-                      {relevantResources.map((resource) => (
-                        <option key={resource.id} value={resource.id}>
-                          {resource.name || resource.id} {/* Display name or ID as fallback */}
-                        </option>
-                      ))}
-                      {relevantResources.length === 0 && (
-                        <option value="" disabled>
-                          No {resourceType}s found
-                        </option>
-                      )}
-                    </select>
-                  ) : isSelect ? (
-                    <select
-                      id={input.id}
-                      name={input.id}
-                      value={inputValues[input.id] || ''}
-                      onChange={(e) => handleInputChange(input.id, e.target.value)}
-                      required
-                      className="w-full rounded-md border border-gray-300 bg-white px-3 py-2 shadow-sm focus:border-purple-500 focus:outline-none focus:ring-2 focus:ring-purple-300 focus:ring-offset-1 sm:text-sm transition duration-150 ease-in-out"
-                    >
-                      <option value="" disabled>
-                        Select an option...
-                      </option>
-                      {input.options?.map((option) => (
-                        <option key={option} value={option}>
-                          {option}
-                        </option>
-                      ))}
-                      {(!input.options || input.options.length === 0) && (
-                        <option value="" disabled>
-                          No options available
-                        </option>
-                      )}
-                    </select>
-                  ) : (
-                    <>
-                      {isCode || isTextArea ? (
-                        <textarea
-                          id={input.id}
-                          name={input.id}
-                          value={inputValues[input.id] || ''}
-                          onChange={(e) => handleInputChange(input.id, e.target.value)}
-                          onKeyDown={(e) => {
-                            // Prevent form submission on Enter key press unless Shift is held
-                            if (e.key === 'Enter' && !e.shiftKey) {
-                              e.preventDefault();
-                              // Optionally, you could trigger submission here if needed,
-                              // but the default behavior is just to prevent it.
-                              handleSubmit(e); // Example: trigger submit manually
-                            }
-                          }}
-                          required
-                          rows={isCode ? 6 : 3} // More rows for code input
-                          className={`w-full rounded-md border border-gray-300 bg-white px-3 py-2 shadow-sm focus:border-purple-500 focus:outline-none focus:ring-2 focus:ring-purple-300 focus:ring-offset-1 sm:text-sm transition duration-150 ease-in-out ${isCode ? 'font-mono text-sm' : ''}`}
-                          placeholder={isCode ? 'Paste your code here...' : ''}
-                        />
-                      ) : (
-                        <input
-                          type="text"
-                          id={input.id}
-                          name={input.id}
-                          value={inputValues[input.id] || ''}
-                          onChange={(e) => handleInputChange(input.id, e.target.value)}
-                          required
-                          className="w-full rounded-md border border-gray-300 bg-white px-3 py-2 shadow-sm focus:border-purple-500 focus:outline-none focus:ring-2 focus:ring-purple-300 focus:ring-offset-1 sm:text-sm transition duration-150 ease-in-out"
-                        />
-                      )}
-                    </>
-                  )}
-                </div>
-              );
-            })}
-            <div className="mt-6 flex justify-end space-x-2">
-              <Dialog.Close asChild>
-                <button
-                  type="button"
-                  className="rounded-md border border-gray-300 bg-white px-4 py-2 text-sm font-medium text-gray-700 shadow-sm hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2"
-                  onClick={onClose} // Ensure onClose is called when Cancel is clicked
-                >
-                  Cancel
-                </button>
-              </Dialog.Close>
-              <button
-                type="submit"
-                className="inline-flex items-center justify-center gap-1.5 rounded-md border border-transparent bg-purple-600 px-4 py-2 text-sm font-medium text-white shadow-sm hover:bg-purple-700 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2"
-              >
-                <Wand2 size={16} />
-                Submit
-              </button>
-            </div>
-          </form>
-        </Dialog.Content>
-      </Dialog.Portal>
-    </Dialog.Root>
-  );
-};
-// --- End Input Modal Component ---
-
-export default InputModal;
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/components/MentionInput.tsx b/eventcatalog/src/enterprise/eventcatalog-chat/components/MentionInput.tsx
deleted file mode 100644
index a0dea060b..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/components/MentionInput.tsx
+++ /dev/null
@@ -1,211 +0,0 @@
-import React, { useState, useRef, useEffect, useCallback } from 'react';
-
-// Define the structure for suggestions with types
-interface MentionSuggestion {
-  id: string; // Unique ID for the key prop
-  name: string; // The suggestion text (e.g., 'PaymentProcessed')
-  type: string; // The group type (e.g., 'event', 'service')
-}
-
-interface MentionInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'onChange'> {
-  suggestions: MentionSuggestion[]; // Use the new type
-  trigger?: string;
-  onChange: (value: string) => void;
-  value: string;
-}
-
-const MentionInput: React.FC<MentionInputProps> = ({ suggestions, trigger = '@', onChange, value, ...inputProps }) => {
-  const [showSuggestions, setShowSuggestions] = useState(false);
-  const [filteredSuggestions, setFilteredSuggestions] = useState<MentionSuggestion[]>([]); // Use the new type
-  const [activeSuggestionIndex, setActiveSuggestionIndex] = useState(0);
-  const [currentQuery, setCurrentQuery] = useState('');
-  const inputRef = useRef<HTMLInputElement>(null);
-  const suggestionsRef = useRef<HTMLUListElement>(null);
-
-  const updateSuggestions = useCallback(
-    (inputValue: string, cursorPosition: number | null) => {
-      if (cursorPosition === null) {
-        setShowSuggestions(false);
-        return;
-      }
-
-      // Find the start of the potential mention query
-      let queryStartIndex = -1;
-      for (let i = cursorPosition - 1; i >= 0; i--) {
-        const char = inputValue[i];
-        if (char === trigger) {
-          queryStartIndex = i;
-          break;
-        }
-        // Stop if we hit whitespace before the trigger
-        if (/\s/.test(char)) {
-          break;
-        }
-      }
-
-      if (queryStartIndex !== -1) {
-        const query = inputValue.substring(queryStartIndex + 1, cursorPosition).toLowerCase();
-        setCurrentQuery(query);
-
-        const filtered = suggestions.filter((s) => s.name.toLowerCase().includes(query));
-
-        // Update the filtered list and reset index
-        setFilteredSuggestions(filtered);
-        setActiveSuggestionIndex(0);
-        // Keep suggestions open as long as the trigger character is active
-        setShowSuggestions(true);
-      } else {
-        // Only hide suggestions if the trigger character sequence is broken
-        setShowSuggestions(false);
-      }
-    },
-    [suggestions, trigger]
-  );
-
-  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
-    const newValue = event.target.value;
-    onChange(newValue);
-    updateSuggestions(newValue, event.target.selectionStart);
-  };
-
-  // Modify handleSuggestionClick to accept the suggestion object
-  const handleSuggestionClick = (suggestion: MentionSuggestion) => {
-    if (inputRef.current) {
-      const cursorPosition = inputRef.current.selectionStart;
-      if (cursorPosition !== null) {
-        // Find the start of the @mention query relative to the cursor
-        let queryStartIndex = -1;
-        for (let i = cursorPosition - 1; i >= 0; i--) {
-          if (value[i] === trigger) {
-            queryStartIndex = i;
-            break;
-          }
-          if (/\s/.test(value[i])) {
-            break;
-          }
-        }
-
-        if (queryStartIndex !== -1) {
-          // Use suggestion.name for the inserted text
-          const newValue =
-            value.substring(0, queryStartIndex) +
-            suggestion.name +
-            ' ' + // Insert selected suggestion name and a space
-            value.substring(cursorPosition);
-
-          onChange(newValue);
-          setShowSuggestions(false);
-          setTimeout(() => {
-            if (inputRef.current) {
-              inputRef.current.focus();
-              const newCursorPos = queryStartIndex + suggestion.name.length + 1;
-              inputRef.current.setSelectionRange(newCursorPos, newCursorPos);
-            }
-          }, 0);
-        } else {
-          // Fallback: Use suggestion.name
-          onChange(value + suggestion.name + ' ');
-          setShowSuggestions(false);
-          inputRef.current.focus();
-        }
-      }
-    }
-  };
-
-  const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
-    if (showSuggestions && filteredSuggestions.length > 0) {
-      if (event.key === 'ArrowDown') {
-        event.preventDefault();
-        setActiveSuggestionIndex((prevIndex) => (prevIndex + 1) % filteredSuggestions.length);
-      } else if (event.key === 'ArrowUp') {
-        event.preventDefault();
-        setActiveSuggestionIndex((prevIndex) => (prevIndex - 1 + filteredSuggestions.length) % filteredSuggestions.length);
-      } else if (event.key === 'Enter' || event.key === 'Tab') {
-        event.preventDefault();
-        // Pass the selected suggestion object
-        handleSuggestionClick(filteredSuggestions[activeSuggestionIndex]);
-      } else if (event.key === 'Escape') {
-        setShowSuggestions(false);
-      }
-    }
-
-    // Propagate other keydown events if needed (e.g., for parent's Enter key handling)
-    // Check if the event is Enter and if we are NOT showing suggestions before calling parent's submit
-    // This prevents submitting the form when selecting a suggestion with Enter
-    if (inputProps.onKeyDown && !(showSuggestions && event.key === 'Enter')) {
-      inputProps.onKeyDown(event);
-    }
-  };
-
-  // Scroll active suggestion into view
-  useEffect(() => {
-    if (showSuggestions && suggestionsRef.current) {
-      const activeItem = suggestionsRef.current.children[activeSuggestionIndex] as HTMLLIElement;
-      if (activeItem) {
-        activeItem.scrollIntoView({ block: 'nearest', inline: 'nearest' });
-      }
-    }
-  }, [activeSuggestionIndex, showSuggestions]);
-
-  // Handle clicks outside the input/suggestions list to close it
-  useEffect(() => {
-    const handleClickOutside = (event: MouseEvent) => {
-      if (
-        inputRef.current &&
-        !inputRef.current.contains(event.target as Node) &&
-        suggestionsRef.current &&
-        !suggestionsRef.current.contains(event.target as Node)
-      ) {
-        setShowSuggestions(false);
-      }
-    };
-
-    document.addEventListener('mousedown', handleClickOutside);
-    return () => {
-      document.removeEventListener('mousedown', handleClickOutside);
-    };
-  }, []);
-
-  return (
-    <div className="relative w-full">
-      <input
-        ref={inputRef}
-        {...inputProps}
-        value={value}
-        onChange={handleChange}
-        onKeyDown={handleKeyDown} // Use onKeyDown for better event control
-        onClick={(e) => updateSuggestions(value, e.currentTarget.selectionStart)} // Update suggestions on click too
-      />
-      {/* Keep the suggestions box open if showSuggestions is true */}
-      {showSuggestions && (
-        <ul
-          ref={suggestionsRef}
-          className="absolute bottom-full mb-2 left-0 right-0 bg-white border border-gray-300 rounded-md shadow-lg max-h-40 overflow-y-auto z-10"
-          style={{ minWidth: inputRef.current?.offsetWidth }}
-        >
-          {/* Conditionally render suggestions or 'No results' message */}
-          {filteredSuggestions.length > 0 ? (
-            filteredSuggestions.map((suggestion, index) => (
-              <li
-                key={suggestion.id + '-' + index}
-                className={`px-4 py-2 text-sm cursor-pointer flex justify-between items-center ${
-                  index === activeSuggestionIndex ? 'bg-purple-100 text-purple-800' : 'text-gray-700 hover:bg-gray-100'
-                }`}
-                onClick={() => handleSuggestionClick(suggestion)}
-                onMouseEnter={() => setActiveSuggestionIndex(index)}
-              >
-                <span>{suggestion.name}</span>
-                <span className="text-xs text-gray-500 ml-2">({suggestion.type})</span>
-              </li>
-            ))
-          ) : (
-            /* Render this list item when no suggestions match */
-            <li className="px-4 py-2 text-sm text-gray-500 italic">No matching items found</li>
-          )}
-        </ul>
-      )}
-    </div>
-  );
-};
-
-export default MentionInput;
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/components/WelcomePromptArea.tsx b/eventcatalog/src/enterprise/eventcatalog-chat/components/WelcomePromptArea.tsx
deleted file mode 100644
index 6f12f46ce..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/components/WelcomePromptArea.tsx
+++ /dev/null
@@ -1,176 +0,0 @@
-import React, { useState, useMemo } from 'react';
-import * as icons from 'lucide-react'; // Import all icons
-import type { ChatPromptCategoryGroup, ChatPrompt } from '@enterprise/eventcatalog-chat/utils/chat-prompts';
-import { defaultPrompts } from './default-prompts';
-
-// Removed the static iconMap
-
-const getCategoryIcon = (iconName?: string): React.ReactNode => {
-  // Default icon component
-  const DefaultIcon = icons.HelpCircle;
-  const IconComponent = iconName ? (icons as any)[iconName] : DefaultIcon;
-
-  // Render the found icon or the default one
-  return IconComponent ? (
-    <IconComponent size={16} className="mr-1 md:mr-2" />
-  ) : (
-    <DefaultIcon size={16} className="mr-1 md:mr-2" /> // Fallback just in case
-  );
-};
-
-interface WelcomePromptAreaProps {
-  chatPrompts: ChatPromptCategoryGroup[];
-  activeCategory: string;
-  setActiveCategory: (category: string) => void;
-  onPromptClick: (prompt: ChatPrompt) => void;
-  isProcessing: boolean; // Combined thinking/streaming state
-}
-
-// Helper function to group default prompts by category label
-const groupDefaultPrompts = (prompts: ChatPrompt[]): ChatPromptCategoryGroup[] => {
-  const groups: { [key: string]: { label: string; icon?: string; items: ChatPrompt[] } } = {};
-
-  prompts.forEach((prompt) => {
-    const categoryLabel = prompt.data.category.label;
-    const categoryIcon = prompt.data.category.icon; // Get icon from prompt data
-
-    if (!groups[categoryLabel]) {
-      groups[categoryLabel] = { label: categoryLabel, icon: categoryIcon, items: [] };
-    }
-    groups[categoryLabel].items.push(prompt);
-  });
-
-  // Convert the groups object into an array matching ChatPromptCategoryGroup structure
-  return Object.values(groups);
-};
-
-const WelcomePromptArea: React.FC<WelcomePromptAreaProps> = ({
-  chatPrompts,
-  activeCategory: activeCustomCategory, // Rename to avoid conflict
-  setActiveCategory: setActiveCustomCategory, // Rename to avoid conflict
-  onPromptClick,
-  isProcessing,
-}) => {
-  // Group default prompts and derive initial state only once
-  const defaultPromptGroups = useMemo(() => groupDefaultPrompts(defaultPrompts), []);
-  const [activeDefaultCategory, setActiveDefaultCategory] = useState<string>(() => defaultPromptGroups[0]?.label || '');
-
-  // Find the currently active category's questions from chatPrompts
-  const activeCustomQuestions: ChatPrompt[] = useMemo(() => {
-    if (!chatPrompts || chatPrompts.length === 0) return [];
-    const activeGroup = chatPrompts.find((group) => group.label === activeCustomCategory);
-    return activeGroup?.items || (chatPrompts[0]?.items ?? []);
-  }, [activeCustomCategory, chatPrompts]);
-
-  // Find the currently active category's default questions
-  const activeDefaultQuestions: ChatPrompt[] = useMemo(() => {
-    if (!defaultPromptGroups || defaultPromptGroups.length === 0) return [];
-    const activeGroup = defaultPromptGroups.find((group) => group.label === activeDefaultCategory);
-    return activeGroup?.items || [];
-  }, [activeDefaultCategory, defaultPromptGroups]);
-
-  return (
-    <div className="h-full flex flex-col justify-center items-center px-4 pb-4 pt-0">
-      <div className="max-w-2xl w-full text-left">
-        <h2 className="text-2xl font-semibold mb-6 text-gray-800">How can I help you?</h2>
-
-        {/* Conditional Rendering: Custom Prompts OR Default Prompts */}
-        {chatPrompts && chatPrompts.length > 0 ? (
-          /* --- CUSTOM PROMPTS UI --- */
-          <>
-            {/* Category Tabs - Use chatPrompts */}
-            <div className="flex flex-wrap justify-left gap-2 mb-6 border-b border-gray-200 pb-4">
-              {chatPrompts.map((categoryGroup) => (
-                <button
-                  key={categoryGroup.label}
-                  onClick={() => setActiveCustomCategory(categoryGroup.label)}
-                  disabled={isProcessing}
-                  className={`flex items-center px-3 py-2 rounded-md text-sm font-medium transition-colors duration-150 focus:outline-none focus:ring-2 focus:ring-purple-400 focus:ring-offset-2 focus:ring-offset-white disabled:opacity-50 ${
-                    activeCustomCategory === categoryGroup.label
-                      ? 'bg-purple-600 text-white'
-                      : 'bg-gray-100 text-gray-700 hover:bg-gray-200'
-                  }`}
-                >
-                  {getCategoryIcon(categoryGroup.icon)}
-                  {categoryGroup.label}
-                </button>
-              ))}
-            </div>
-            {/* Questions List - Use activeCustomQuestions */}
-            <div className="space-y-2 text-left">
-              {activeCustomQuestions.map((item) => (
-                <button
-                  key={item.id}
-                  onClick={() => onPromptClick(item)}
-                  className="block w-full text-left px-3 py-2 text-gray-700 hover:bg-gray-100 rounded-md text-sm transition-colors duration-150 focus:outline-none focus:ring-1 focus:ring-purple-400 disabled:opacity-50"
-                  disabled={isProcessing}
-                >
-                  {item.data.title}
-                </button>
-              ))}
-            </div>
-          </>
-        ) : (
-          /* --- DEFAULT PROMPTS UI (Grouped) --- */
-          <>
-            {/* Default Category Tabs - Use defaultPromptGroups */}
-            <div className="flex flex-wrap justify-left gap-2 mb-6 border-b border-gray-200 pb-4">
-              {defaultPromptGroups.map((categoryGroup) => (
-                <button
-                  key={categoryGroup.label} // Use label as key
-                  onClick={() => setActiveDefaultCategory(categoryGroup.label)}
-                  disabled={isProcessing}
-                  className={`flex items-center px-3 py-2 rounded-md text-sm font-medium transition-colors duration-150 focus:outline-none focus:ring-2 focus:ring-purple-400 focus:ring-offset-2 focus:ring-offset-white disabled:opacity-50 ${
-                    activeDefaultCategory === categoryGroup.label
-                      ? 'bg-purple-600 text-white'
-                      : 'bg-gray-100 text-gray-700 hover:bg-gray-200'
-                  }`}
-                >
-                  {/* Use the icon mapping function */}
-                  {getCategoryIcon(categoryGroup.icon)}
-                  {categoryGroup.label}
-                </button>
-              ))}
-            </div>
-            {/* Default Questions List - Use activeDefaultQuestions */}
-            <div className="space-y-2 text-left">
-              {activeDefaultQuestions.map((item) => (
-                <button
-                  key={item.id}
-                  onClick={() => onPromptClick(item)}
-                  className="block w-full text-left px-3 py-2 text-gray-700 hover:bg-gray-100 rounded-md text-sm transition-colors duration-150 focus:outline-none focus:ring-1 focus:ring-purple-400 disabled:opacity-50"
-                  disabled={isProcessing}
-                >
-                  {item.data.title}
-                </button>
-              ))}
-            </div>
-
-            {/* Enhanced Bring Your Own Prompts section */}
-            <div className="bg-purple-50 border border-purple-200 rounded-lg p-4 mt-6 text-gray-700 text-sm">
-              <p className="flex items-center">
-                <icons.Wand2 size={18} className="text-purple-600 mr-2 flex-shrink-0" /> {/* Added Icon */}
-                <span>
-                  Want to tailor these suggestions?{' '}
-                  <a
-                    href="https://www.eventcatalog.dev/docs/development/guides/eventcatlaog-chat/what-is-eventcatalog-chat"
-                    target="_blank"
-                    rel="noopener noreferrer"
-                    className="text-purple-700 hover:underline font-semibold"
-                  >
-                    {' '}
-                    {/* Added target and rel */}
-                    Bring your own prompts!
-                  </a>{' '}
-                  Easily configure this list with relevant questions for your teams and organization.
-                </span>
-              </p>
-            </div>
-          </>
-        )}
-      </div>
-    </div>
-  );
-};
-
-export default WelcomePromptArea;
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/components/default-prompts.ts b/eventcatalog/src/enterprise/eventcatalog-chat/components/default-prompts.ts
deleted file mode 100644
index 2cb5c1689..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/components/default-prompts.ts
+++ /dev/null
@@ -1,93 +0,0 @@
-import type { ChatPrompt } from '@enterprise/eventcatalog-chat/utils/chat-prompts';
-
-export const defaultPrompts: ChatPrompt[] = [
-  {
-    id: 'default-events',
-    collection: 'chatPrompts', // Required field
-    body: 'List all events.', // The actual prompt text
-    data: {
-      title: 'What events do we have in our architecture?', // Text displayed on the button
-      type: 'text', // Default type
-      category: { id: 'general', label: 'General', icon: 'HelpCircle' },
-    },
-  },
-  {
-    id: 'default-events-by-domain-feature',
-    collection: 'chatPrompts',
-    body: 'What events are relevant to this feature {{feature-description}}?',
-    data: {
-      title: 'Im building a new feature, what events are relevant to this feature?',
-      type: 'text',
-      inputs: [
-        {
-          id: 'feature-description',
-          label: 'Feature Description',
-          type: 'text-area',
-        },
-      ],
-      category: { id: 'general', label: 'General', icon: 'HelpCircle' },
-    },
-  },
-  {
-    id: 'default-events-by-domain-service',
-    collection: 'chatPrompts',
-    body: 'Review the given service {{service-name}}, and let me know how it works? You are an expert in the domain and architecture of the service.',
-    data: {
-      title: 'Review the given service, and let me know how it works?',
-      type: 'text',
-      inputs: [
-        {
-          id: 'service-name',
-          label: 'Service Name',
-          type: 'resource-list-services',
-        },
-      ],
-      category: { id: 'general', label: 'General', icon: 'HelpCircle' },
-    },
-  },
-  {
-    id: 'default-services',
-    collection: 'chatPrompts',
-    body: 'List all services.',
-    data: {
-      title: 'What services do we have in our architecture?',
-      type: 'text',
-      category: { id: 'general', label: 'General', icon: 'HelpCircle' },
-    },
-  },
-  // Example of another category
-  {
-    id: 'default-schema-json',
-    collection: 'chatPrompts',
-    body: 'Generate a JSON schema for {{event-name}}.',
-    data: {
-      title: 'Generate a JSON schema for the given event',
-      type: 'text',
-      inputs: [
-        {
-          id: 'event-name',
-          label: 'Event Name',
-          type: 'resource-list-events',
-        },
-      ],
-      category: { id: 'code', label: 'Code Generation', icon: 'Code' },
-    },
-  },
-  {
-    id: 'default-schema-avro',
-    collection: 'chatPrompts',
-    body: 'Generate a Avro schema for {{event-name}}.',
-    data: {
-      title: 'Generate a Avro schema for the given event',
-      type: 'text',
-      inputs: [
-        {
-          id: 'event-name',
-          label: 'Event Name',
-          type: 'resource-list-events',
-        },
-      ],
-      category: { id: 'code', label: 'Code Generation', icon: 'Code' },
-    },
-  },
-];
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/components/hooks/ChatProvider.tsx b/eventcatalog/src/enterprise/eventcatalog-chat/components/hooks/ChatProvider.tsx
deleted file mode 100644
index c2b218141..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/components/hooks/ChatProvider.tsx
+++ /dev/null
@@ -1,143 +0,0 @@
-import type { UIMessage } from '@ai-sdk/react';
-import React, { createContext, useContext, useEffect, useState } from 'react';
-import type { ReactNode } from 'react';
-
-export interface Message {
-  content: string;
-  additionalContext?: string;
-  isUser: boolean;
-  timestamp: number;
-  resources?: Array<{
-    id: string;
-    type: string;
-    url: string;
-    title?: string;
-  }>;
-}
-
-export interface ChatSession {
-  id: string;
-  title: string;
-  messages: Message[];
-  lastUpdated: number;
-  createdAt: number;
-}
-
-interface ChatContextType {
-  sessions: ChatSession[];
-  currentSession: ChatSession | null;
-  createSession: () => void;
-  updateSession: (session: ChatSession) => void;
-  deleteSession: (id: string) => void;
-  setCurrentSession: (session: ChatSession | null) => void;
-  isStreaming: boolean;
-  setIsStreaming: (isStreaming: boolean) => void;
-  storeMessagesToSession: (sessionId: string, messages: UIMessage[]) => void;
-}
-
-const ChatContext = createContext<ChatContextType | undefined>(undefined);
-
-const STORAGE_KEY = 'chat_sessions';
-
-export function ChatProvider({ children }: { children: ReactNode }) {
-  const [sessions, setSessions] = useState<ChatSession[]>(() => {
-    if (typeof window !== 'undefined') {
-      const stored = localStorage.getItem(STORAGE_KEY);
-      return stored ? JSON.parse(stored) : [];
-    }
-    return [];
-  });
-  const [currentSession, setCurrentSession] = useState<ChatSession | null>(null);
-  const [isStreaming, setIsStreaming] = useState(false);
-
-  const createSession = () => {
-    const newSession: ChatSession = {
-      id: crypto.randomUUID(),
-      title: `Chat ${sessions.length + 1}`,
-      messages: [],
-      lastUpdated: Date.now(),
-      createdAt: Date.now(),
-    };
-
-    setSessions((prev) => {
-      const updated = [newSession, ...prev];
-      localStorage.setItem(STORAGE_KEY, JSON.stringify(updated));
-      return updated;
-    });
-    setCurrentSession(newSession);
-  };
-
-  const updateSession = (session: ChatSession) => {
-    setSessions((prev) => {
-      const index = prev.findIndex((s) => s.id === session.id);
-      if (index === -1) return prev;
-
-      const updated = [...prev];
-      updated[index] = {
-        ...session,
-        lastUpdated: Date.now(),
-      };
-      localStorage.setItem(STORAGE_KEY, JSON.stringify(updated));
-      return updated;
-    });
-  };
-
-  const deleteSession = (id: string) => {
-    setSessions((prev) => {
-      const updated = prev.filter((session) => session.id !== id);
-      localStorage.setItem(STORAGE_KEY, JSON.stringify(updated));
-      return updated;
-    });
-    if (currentSession?.id === id) {
-      setCurrentSession(null);
-    }
-  };
-
-  // Set all messages to the session
-  const storeMessagesToSession = (sessionId: string, messages: UIMessage[]) => {
-    setSessions((prev) => {
-      const index = prev.findIndex((s) => s.id === sessionId);
-      if (index === -1) return prev;
-
-      const updated = [...prev];
-      updated[index].messages = messages as unknown as Message[];
-      updated[index].lastUpdated = Date.now();
-      localStorage.setItem(STORAGE_KEY, JSON.stringify(updated));
-      return updated;
-    });
-  };
-
-  useEffect(() => {
-    if (sessions.length > 0) {
-      setCurrentSession(sessions[0]);
-    } else {
-      createSession();
-    }
-  }, []);
-
-  return (
-    <ChatContext.Provider
-      value={{
-        sessions,
-        currentSession,
-        createSession,
-        updateSession,
-        deleteSession,
-        setCurrentSession,
-        isStreaming,
-        setIsStreaming,
-        storeMessagesToSession,
-      }}
-    >
-      {children}
-    </ChatContext.Provider>
-  );
-}
-
-export function useChat() {
-  const context = useContext(ChatContext);
-  if (context === undefined) {
-    throw new Error('useChat must be used within a ChatProvider');
-  }
-  return context;
-}
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/components/windows/ChatWindow.server.tsx b/eventcatalog/src/enterprise/eventcatalog-chat/components/windows/ChatWindow.server.tsx
deleted file mode 100644
index 2e3f0fb2f..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/components/windows/ChatWindow.server.tsx
+++ /dev/null
@@ -1,387 +0,0 @@
-import { useEffect, useState, useRef, useCallback, useMemo } from 'react';
-import { Send } from 'lucide-react';
-import { useChat, type Message } from '../hooks/ChatProvider';
-import React from 'react';
-import MentionInput from '../MentionInput';
-import InputModal from '../InputModal';
-import type { ChatPromptCategoryGroup, ChatPrompt } from '@enterprise/eventcatalog-chat/utils/chat-prompts';
-import WelcomePromptArea from '../WelcomePromptArea';
-import ChatMessage from '../ChatMessage'; // Import the new component
-import { useChat as useAiChat, type UIMessage } from '@ai-sdk/react';
-
-// Update Message type to include resources
-interface Resource {
-  id: string;
-  type: string;
-  url: string;
-  title?: string;
-  name?: string;
-}
-
-interface ChatWindowProps {
-  model?: string;
-  provider?: string;
-  embeddingModel?: string;
-  max_tokens?: number;
-  similarityResults?: number;
-  resources: Resource[];
-  chatPrompts: ChatPromptCategoryGroup[];
-}
-
-const ChatWindow = ({
-  model = 'o4-mini',
-  embeddingModel = 'text-embedding-3-large',
-  provider = 'openai',
-  max_tokens = 4096,
-  similarityResults = 50,
-  resources: mentionInputResources = [],
-  chatPrompts,
-}: ChatWindowProps) => {
-  // const [messages] = useState<Array<Message>>([]);
-  const [inputValue, setInputValue] = useState('');
-  const outputRef = useRef<HTMLDivElement>(null);
-  const inputRef = useRef<HTMLInputElement>(null);
-  const [activeCategory, setActiveCategory] = useState<string>(chatPrompts?.[0]?.label || '');
-
-  const { messages, sendMessage, stop, status, setMessages: setAiMessages } = useAiChat();
-  const isStreaming = status === 'streaming' && messages.length > 0;
-  const isThinking = status === 'submitted' || (status === 'streaming' && messages.length === 0);
-
-  // --- New state for input modal ---
-  const [promptForInput, setPromptForInput] = useState<ChatPrompt | null>(null);
-  const [isInputModalOpen, setIsInputModalOpen] = useState(false);
-  // --- End new state ---
-
-  const { currentSession, storeMessagesToSession, updateSession, createSession } = useChat();
-
-  // If the messages change add them to the session
-  useEffect(() => {
-    if (currentSession) {
-      storeMessagesToSession(currentSession.id, messages);
-    }
-  }, [messages]);
-
-  // Load messages when session changes
-  useEffect(() => {
-    if (currentSession) {
-      setAiMessages(currentSession.messages as unknown as UIMessage[]);
-    }
-  }, [currentSession]);
-
-  // Add effect to focus input when streaming stops
-  useEffect(() => {
-    if (!isStreaming && inputRef.current) {
-      inputRef.current.focus();
-    }
-  }, [isStreaming]);
-
-  // New function to handle submitting a question (user input or predefined)
-  const submitQuestion = useCallback(
-    async (question: string, additionalContext?: string) => {
-      if (!question.trim() || isStreaming || isThinking) return;
-
-      const userMessage: Message = { content: question, isUser: true, timestamp: Date.now(), additionalContext };
-      const isFirstMessage = messages.length === 0;
-
-      // setMessages((prev) => [...prev, userMessage]);
-      // setShowWelcome(false);
-      setInputValue('');
-
-      // Scroll to bottom immediately after adding user message and setting thinking state
-      requestAnimationFrame(() => scrollToBottom(false));
-
-      if (currentSession && isFirstMessage) {
-        updateSession({
-          ...currentSession,
-          // Use the submitted question (potentially the prompt title) for the session title
-          title: question.length > 25 ? `${question.substring(0, 22)}...` : question,
-        });
-      }
-
-      sendMessage({ text: additionalContext || question });
-
-      // mutation.mutate({ question, additionalContext });
-    },
-    [
-      currentSession,
-      updateSession,
-      // setMessages,
-      setInputValue,
-      messages.length,
-      isStreaming,
-      isThinking,
-      messages,
-    ]
-  );
-
-  // --- New handler for submitting from the modal ---
-  const handleSubmitWithInputs = useCallback(
-    (prompt: ChatPrompt, inputValues: Record<string, string>) => {
-      let finalBody = prompt.body || ''; // Start with the original body
-      // Ensure prompt and prompt.data exist before accessing properties
-      if (!prompt || !prompt.data) {
-        console.error('handleSubmitWithInputs called without a valid prompt.');
-        setIsInputModalOpen(false); // Close modal even on error
-        setPromptForInput(null);
-        return;
-      }
-
-      for (const [key, value] of Object.entries(inputValues)) {
-        const placeholder = `{{${key}}}`;
-        // Replace all occurrences of the placeholder in the body
-        finalBody = finalBody.replaceAll(placeholder, `"${value}"`);
-      }
-
-      // Submit the processed title and the processed body as additional context
-      submitQuestion(prompt.data.title, finalBody);
-
-      setIsInputModalOpen(false); // Close modal
-      setPromptForInput(null); // Clear stored prompt
-    },
-    [submitQuestion]
-  );
-
-  // --- Modified handler for clicking a predefined question ---
-  const handlePredefinedQuestionClick = useCallback(
-    (prompt: ChatPrompt) => {
-      // Ensure prompt and prompt.data exist
-      if (!prompt || !prompt.data) {
-        console.error('handlePredefinedQuestionClick called with invalid prompt:', prompt);
-        return;
-      }
-      // Check if prompt.data and prompt.data.inputs exist and have length > 0
-      if (prompt.data?.inputs && prompt.data.inputs.length > 0) {
-        setPromptForInput(prompt); // Store the prompt
-        setIsInputModalOpen(true); // Open the modal
-      } else {
-        // No inputs needed, submit directly using title and body
-        submitQuestion(prompt.data.title, prompt.body);
-      }
-    },
-    [submitQuestion]
-  );
-
-  // Handler for standard input submission
-  const handleSubmit = useCallback(
-    (e?: React.FormEvent) => {
-      e?.preventDefault();
-      // sendMessage({ text: inputValue });
-      submitQuestion(inputValue); // Use standard input value, no additional context here
-    },
-    [inputValue, sendMessage]
-  );
-
-  // Add new function to handle smooth scrolling
-  const scrollToBottom = useCallback((smooth = true) => {
-    if (outputRef.current) {
-      outputRef.current.scrollTo({
-        top: outputRef.current.scrollHeight,
-        behavior: smooth ? 'smooth' : 'auto',
-      });
-    }
-  }, []);
-
-  // Add effect to scroll when messages change or thinking state changes
-  useEffect(() => {
-    // Scroll immediately for new messages or when thinking starts/stops
-    requestAnimationFrame(() => scrollToBottom(messages.length > 0 && !isThinking));
-  }, [messages, isThinking, scrollToBottom]);
-
-  // Memoize the messages list with the new ChatMessage component
-  const messagesList = useMemo(
-    () => (
-      <div className="space-y-4 max-w-[900px] mx-auto pb-6">
-        {messages.map((message, index) => (
-          <ChatMessage
-            key={message.id}
-            message={{
-              isUser: message.role === 'user',
-              content: message.parts.map((part) => (part.type === 'text' ? part.text : '')).join(''),
-              timestamp: Date.now(),
-            }}
-          />
-        ))}
-        {isThinking && (
-          <div className="flex justify-start mb-4">
-            <div className="flex items-center space-x-2 max-w-[80%] rounded-lg p-3 bg-gray-100 text-gray-800 rounded-bl-none">
-              <div className="flex space-x-1">
-                <div className="w-2 h-2 bg-gray-500 rounded-full animate-bounce" style={{ animationDelay: '0ms' }}></div>
-                <div className="w-2 h-2 bg-gray-500 rounded-full animate-bounce" style={{ animationDelay: '150ms' }}></div>
-                <div className="w-2 h-2 bg-gray-500 rounded-full animate-bounce" style={{ animationDelay: '300ms' }}></div>
-              </div>
-            </div>
-          </div>
-        )}
-      </div>
-    ),
-    [messages, isThinking]
-  );
-
-  // Memoize the input change handler
-  const handleInputChange = useCallback((newValue: string) => {
-    setInputValue(newValue);
-  }, []);
-
-  // Memoize the key press handler for MentionInput
-  const handleInputKeyPress = useCallback(
-    (e: React.KeyboardEvent<HTMLInputElement>) => {
-      // Submit only if Enter is pressed WITHOUT Shift and suggestions are NOT shown
-      if (e.key === 'Enter' && !e.shiftKey) {
-        // The MentionInput's internal onKeyDown will handle preventDefault
-        // if suggestions are shown and Enter is pressed for selection.
-        // We check here if it *wasn't* handled for selection, meaning we should submit.
-        if (!e.defaultPrevented) {
-          handleSubmit();
-        }
-      }
-    },
-    [handleSubmit]
-  ); // Include handleSubmit in dependencies
-
-  // Effect to update activeCategory if chatPrompts load after initial render
-  useEffect(() => {
-    if (!activeCategory && chatPrompts && chatPrompts.length > 0) {
-      setActiveCategory(chatPrompts[0].label);
-    }
-  }, [chatPrompts, activeCategory]);
-
-  // Add Effect for clipboard copy functionality
-  useEffect(() => {
-    const outputElement = outputRef.current;
-    if (!outputElement) return;
-
-    const handleClick = async (event: MouseEvent) => {
-      const button = (event.target as Element).closest<HTMLButtonElement>('[data-copy-button="true"]');
-      if (!button) return;
-
-      const codeToCopy = button.dataset.code;
-      if (!codeToCopy) return;
-
-      try {
-        await navigator.clipboard.writeText(codeToCopy);
-        // Visual feedback: change icon to Check for a short time
-        const originalIcon = button.innerHTML;
-        button.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-check"><polyline points="20 6 9 17 4 12"></polyline></svg>`;
-        button.disabled = true;
-
-        setTimeout(() => {
-          button.innerHTML = originalIcon;
-          button.disabled = false;
-        }, 1500); // Reset after 1.5 seconds
-      } catch (err) {
-        console.error('Failed to copy code: ', err);
-        // Optional: Provide error feedback to the user
-        const originalTitle = button.title;
-        button.title = 'Failed to copy!';
-        setTimeout(() => {
-          button.title = originalTitle;
-        }, 1500);
-      }
-    };
-
-    outputElement.addEventListener('click', handleClick);
-
-    // Cleanup listener on component unmount
-    return () => {
-      outputElement.removeEventListener('click', handleClick);
-    };
-  }, []); // Empty dependency array ensures this runs only once on mount
-
-  // Handle the query from the url
-  useEffect(() => {
-    const urlParams = new URLSearchParams(window.location.search);
-    const query = urlParams.get('query');
-    if (query) {
-      setTimeout(() => {
-        createSession();
-        setInputValue(query);
-      }, 250);
-    }
-  }, []);
-
-  return (
-    <div className="flex-1 flex flex-col overflow-hidden h-[calc(100vh-60px)] w-full bg-white">
-      {messages.length === 0 && (
-        <WelcomePromptArea
-          chatPrompts={chatPrompts}
-          activeCategory={activeCategory}
-          setActiveCategory={setActiveCategory}
-          onPromptClick={handlePredefinedQuestionClick}
-          isProcessing={isStreaming || isThinking}
-        />
-      )}
-
-      {messages.length > 0 && (
-        <div ref={outputRef} className="flex-1 overflow-y-auto">
-          {messages.length > 0 && (
-            <div id="output" className="p-4 space-y-4 w-full max-w-[900px] mx-auto h-full pb-16">
-              {messagesList}
-            </div>
-          )}
-          ;
-        </div>
-      )}
-
-      {/* Input Area (remains at the bottom) */}
-      <div className="border-t border-gray-200 p-4 bg-white">
-        <div className="max-w-[900px] mx-auto relative">
-          {/* Replace standard input with MentionInput */}
-          <MentionInput
-            suggestions={mentionInputResources.map((resource) => ({
-              id: resource.id,
-              name: resource.name || '',
-              type: resource.type,
-            }))}
-            trigger="@"
-            type="text"
-            value={inputValue}
-            onChange={handleInputChange}
-            onKeyDown={handleInputKeyPress}
-            placeholder="Type your message or '@' for events..."
-            className="w-full px-4 py-3 bg-white text-gray-800 rounded-lg border border-gray-200 focus:outline-none focus:border-purple-500 focus:ring-1 focus:ring-purple-500 disabled:bg-gray-50 disabled:cursor-not-allowed pr-24"
-            disabled={isStreaming || isThinking} // Disable input while streaming/thinking
-          />
-          <div className="absolute right-3 top-1/2 -translate-y-1/2">
-            {isStreaming ? (
-              <button
-                onClick={() => stop()}
-                className="px-4 py-2 bg-red-600 text-white rounded-lg hover:bg-red-700 text-sm font-medium"
-              >
-                Stop
-              </button>
-            ) : (
-              <button
-                onClick={handleSubmit}
-                disabled={!inputValue.trim() || isThinking} // Disable send if input empty or thinking
-                className="px-4 py-2 flex items-center bg-purple-600 text-white rounded-lg hover:bg-purple-700 disabled:bg-gray-200 disabled:cursor-not-allowed text-sm font-medium"
-              >
-                {/* Add icon */}
-                <Send size={16} strokeWidth={1.5} className="mr-2" />
-                Send
-              </button>
-            )}
-          </div>
-        </div>
-        <div className="max-w-[900px] mx-auto flex justify-between">
-          {/* show what model is loaded */}
-          <p className="text-[10px] text-gray-400 mt-2">
-            Provider: {provider.charAt(0).toUpperCase() + provider.slice(1)} | Model: {model}
-            {/* Embedding Model: {embeddingModel} */}
-          </p>
-          <p className="text-xs text-gray-500 mt-2">EventCatalog Chat can make mistakes. Check important info.</p>
-        </div>
-      </div>
-
-      {/* --- Render Input Modal --- */}
-      <InputModal
-        isOpen={isInputModalOpen}
-        onClose={() => setIsInputModalOpen(false)} // Allow closing the modal
-        prompt={promptForInput}
-        onSubmit={handleSubmitWithInputs}
-        resources={mentionInputResources} // Pass resources here
-      />
-    </div>
-  );
-};
-
-export default ChatWindow;
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/pages/api/chat.ts b/eventcatalog/src/enterprise/eventcatalog-chat/pages/api/chat.ts
deleted file mode 100644
index dbfc9aea6..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/pages/api/chat.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-import type { APIContext } from 'astro';
-import { type UIMessage } from 'ai';
-import config from '@config';
-import { getProvider } from '@enterprise/eventcatalog-chat/providers';
-
-// Map the Keys to use in the SDK, astro exports as import.meta.env
-process.env.OPENAI_API_KEY = import.meta.env.OPENAI_API_KEY || '';
-
-const baseSystemPrompt = `You are an expert in event-driven architecture and domain-driven design, specializing in documentation for EventCatalog.
-
-You assist developers, architects, and business stakeholders who need information about their event-driven system catalog. You help with questions about:
-- Events (asynchronous messages that notify about something that has happened)
-- Commands (requests to perform an action)
-- Queries (requests for information)
-- Services (bounded contexts or applications that produce/consume events)
-- Domains (business capabilities or functional areas)
-
-Your primary goal is to help users understand their event-driven system through accurate documentation interpretation.
-
-When responding:
-2. Explain connections between resources when relevant.
-3. Use appropriate technical terminology.
-4. Use clear formatting with headings and bullet points when helpful.
-5. State clearly when information is missing rather than making assumptions.
-6. Don't provide code examples unless specifically requested.
-
-Your primary goal is to help users understand their event-driven system through accurate documentation interpretation.
-
-If you have additional context, use it to answer the question.`;
-
-interface Message {
-  content: string;
-}
-
-export const GET = async ({ request }: APIContext<{ question: string; messages: Message[]; additionalContext?: string }>) => {
-  // return 404
-  return new Response(JSON.stringify({ error: 'Not found' }), {
-    status: 404,
-    headers: { 'Content-Type': 'application/json' },
-  });
-};
-
-export const POST = async ({ request }: APIContext<{ question: string; messages: Message[]; additionalContext?: string }>) => {
-  const { messages }: { messages: UIMessage[] } = await request.json();
-
-  const provider = getProvider(config?.chat?.provider || 'openai', {
-    modelId: config?.chat?.model || 'gpt-3.5-turbo-0125',
-    temperature: config?.chat?.temperature,
-    topP: config?.chat?.topP,
-    topK: config?.chat?.topK,
-    frequencyPenalty: config?.chat?.frequencyPenalty,
-    presencePenalty: config?.chat?.presencePenalty,
-  });
-
-  const result = await provider.streamText(baseSystemPrompt, messages);
-  return result.toUIMessageStreamResponse();
-};
-
-export const prerender = false;
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/pages/chat/index.astro b/eventcatalog/src/enterprise/eventcatalog-chat/pages/chat/index.astro
deleted file mode 100644
index 62d156525..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/pages/chat/index.astro
+++ /dev/null
@@ -1,104 +0,0 @@
----
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import Chat from '@enterprise/eventcatalog-chat/components/Chat';
-import { getChatPromptsGroupedByCategory } from '@enterprise/eventcatalog-chat/utils/chat-prompts';
-import config from '@config';
-import { Code } from 'astro-expressive-code/components';
-import { getDomains } from '@utils/collections/domains';
-import { getEvents } from '@utils/events';
-import { getCommands } from '@utils/commands';
-import { getServices } from '@utils/collections/services';
-import { getQueries } from '@utils/queries';
-
-const isEnabled = config.chat?.enabled || false;
-const chatConfig = config.chat || {};
-const output = config.output || 'static';
-
-// Get all information for the mention input
-const [events, commands, queries, services, domains] = await Promise.all([
-  getEvents({ getAllVersions: false }),
-  getCommands({ getAllVersions: false }),
-  getQueries({ getAllVersions: false }),
-  getServices({ getAllVersions: false }),
-  getDomains({ getAllVersions: false }),
-]);
-const allItems = [...events, ...commands, ...queries, ...services, ...domains];
-
-const chatPrompts = await getChatPromptsGroupedByCategory();
-
-const resources = allItems.map((item) => ({ id: item.data.id, type: item.collection, name: item.data.name }));
----
-
-<VerticalSideBarLayout title="AI Chat">
-  <div class="flex h-[calc(100vh-60px)] bg-white">
-    {
-      isEnabled ? (
-        <>
-          <div id="chatContainer" class="w-full">
-            <Chat
-              client:only="react"
-              chatConfig={{
-                ...chatConfig,
-              }}
-              resources={resources}
-              chatPrompts={chatPrompts}
-              output={output as 'static' | 'server'}
-            />
-          </div>
-        </>
-      ) : (
-        <div class="flex items-center justify-center w-full p-4 sm:p-8">
-          <div class="max-w-6xl flex flex-col md:flex-row gap-8 md:gap-12 items-center">
-            {/* Left side - Illustration */}
-            <div class="flex-1">
-              <img
-                src="/images/ai-placeholder.png"
-                alt="AI Assistant Illustration"
-                class="w-full max-w-sm md:max-w-md mx-auto  rounded-lg shadow-lg"
-              />
-            </div>
-
-            {/* Right side - Content */}
-            <div class="flex-1">
-              <h2 class="text-2xl md:text-3xl font-bold text-gray-900 mb-4">EventCatalog AI Assistant</h2>
-              <p class="text-gray-600 mb-6 text-base md:text-lg">
-                Chat with your catalog to quickly find information, understand relationships, and get instant answers about your
-                architecture. Our AI-powered assistant makes exploring your event catalog faster and more intuitive than ever.
-              </p>
-
-              <div class="bg-gray-700 rounded-lg p-4 md:p-6 mb-4">
-                <h3 class="text-lg text-white font-semibold mb-3">Quick Setup</h3>
-                <Code code={`npm install @eventcatalog/generator-ai`} lang="bash" frame="none" />
-                <a
-                  href="https://www.eventcatalog.dev/features/ai-assistant"
-                  class="inline-flex items-center text-sm text-white mt-4"
-                >
-                  Learn more about setup →
-                </a>
-              </div>
-              <p class="text-gray-600 mb-6 text-sm">
-                Your data stays private and secure - all processing happens locally on your machine.
-              </p>
-            </div>
-          </div>
-        </div>
-      )
-    }
-  </div>
-</VerticalSideBarLayout>
-
-<style>
-  .loading-status.ready {
-    background-color: rgb(240 253 244); /* light green bg */
-    color: rgb(22 163 74); /* green text */
-  }
-
-  .loading-status.hidden {
-    display: none;
-  }
-
-  /* Add smooth scrolling behavior */
-  .scroll-smooth {
-    scroll-behavior: smooth;
-  }
-</style>
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/providers/ai-provider.ts b/eventcatalog/src/enterprise/eventcatalog-chat/providers/ai-provider.ts
deleted file mode 100644
index b98189ed2..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/providers/ai-provider.ts
+++ /dev/null
@@ -1,140 +0,0 @@
-import { streamText, tool, type LanguageModel, type UIMessage, stepCountIs, convertToModelMessages } from 'ai';
-import { z } from 'astro/zod';
-import config from '@config';
-
-const getBaseURL = () => {
-  if (import.meta.env.MODE === 'development') {
-    return `http://localhost:${config.port || 3000}`;
-  }
-  return config.homepageLink || 'https://eventcatalog.dev/';
-};
-
-export const getEventCatalogResources = async () => {
-  const baseUrl = process.env.EVENTCATALOG_URL || getBaseURL();
-  const url = new URL('/docs/llm/llms.txt', baseUrl);
-  const response = await fetch(url.toString());
-  const text = await response.text();
-  return text;
-};
-
-export const getResourceInformation = async (type: string, id: string, version: string) => {
-  const baseUrl = process.env.EVENTCATALOG_URL || getBaseURL();
-  const url = new URL(`/docs/${type}/${id}/${version}.mdx`, baseUrl);
-  const response = await fetch(url.toString());
-  const text = await response.text();
-  return text;
-};
-
-// base class for AI providers
-export interface AIProviderOptions {
-  modelId: string;
-  model?: LanguageModel;
-  temperature?: number;
-  topP?: number | undefined;
-  topK?: number | undefined;
-  frequencyPenalty?: number | undefined;
-  presencePenalty?: number | undefined;
-}
-
-export class AIProvider {
-  private model?: string | LanguageModel;
-  private modelId: string;
-  private temperature: number;
-  private topP: number | undefined;
-  private topK: number | undefined;
-  private frequencyPenalty: number | undefined;
-  private presencePenalty: number | undefined;
-  public models: string[];
-
-  constructor({ modelId, model, temperature, topP, topK, frequencyPenalty, presencePenalty }: AIProviderOptions) {
-    this.modelId = modelId;
-    this.temperature = temperature ?? 0.2;
-    this.topP = topP;
-    this.topK = topK;
-    this.frequencyPenalty = frequencyPenalty;
-    this.presencePenalty = presencePenalty;
-    this.models = [];
-
-    if (model) {
-      this.model = model;
-    }
-  }
-
-  async validateModel(model: string): Promise<{ isValidModel: boolean; listOfModels: string[] }> {
-    const isValidModel = this.models.includes(model);
-    return { isValidModel, listOfModels: this.models };
-  }
-
-  async streamText(system: string, messages: Array<UIMessage> | Array<Omit<UIMessage, 'id'>>) {
-    if (!this.model) {
-      throw new Error('Model not set');
-    }
-
-    return await streamText({
-      model: this.model,
-      system: system ?? '',
-      messages: convertToModelMessages(messages),
-      stopWhen: stepCountIs(5),
-      temperature: this.temperature,
-      ...(this.topP && { topP: this.topP }),
-      ...(this.topK && { topK: this.topK }),
-      ...(this.frequencyPenalty && { frequencyPenalty: this.frequencyPenalty }),
-      ...(this.presencePenalty && { presencePenalty: this.presencePenalty }),
-      tools: {
-        findResources: tool({
-          description: [
-            'Find resources that are available in EventCatalog',
-            '',
-            'Use this tool when you need to:',
-            '- Get a list of resources in EventCatalog including services, domains, events, commands, queries and flows, ubiquitous language terms and entities',
-            "- Find a resource's id and version to aid other tool requests",
-            '- Just return the list of matched resources in EventCatalog with a short description of each resource',
-            "- Don't return bullet points, just return the list of resources in a readable format",
-            '- Include the resource name, description, and a link to the resource',
-            '- When you return a link, remove the .mdx from the end of the url',
-            '- Return a list of messages the resource produces and consumes, these are marked as sends and receives',
-            '- If the resource has a domain, include it in the response',
-            '- Ask the user if they would like more information about a specific resource',
-            '- When you return a message, in brackets let me know if its a query, command or event',
-            `- The host URL is ${process.env.EVENTCATALOG_URL}`,
-          ].join('\n'),
-          inputSchema: z.object({}),
-          execute: async () => {
-            const text = await getEventCatalogResources();
-            return text;
-          },
-        }),
-        findResource: tool({
-          description: [
-            'Get more information about a service, domain, event, command, query or flow in EventCatalog using its id and version',
-            'Use this tool when you need to:',
-            '- Get more details/information about a service, domain, event, command, query, flow or entity in EventCatalog',
-            '- Use the id to find more information about a service, domain, event, command, query, flow or entity',
-            '- Return everything you know about this resource',
-            '- If the resource has a specification return links to the specification file',
-            '- When you find owners the url would look something like /docs/users/{id} if its a user or /docs/teams/{id} if its a team',
-            '- When you return the producers and consumers (the messages the service produces and consumes) make sure they include the url to the documentation, the url would look something like /docs/{type}/{id}, e.g /docs/events/MyEvent/1.0.0 or /docs/commands/MyCommand/1.0.0',
-            '- When you return owners make sure they include the url to the documentation',
-            '- If the resource has a domain, include it in the response',
-            '- Ask the user if they would like more information about a specific resource',
-            '- When you return a message, in brackets let me know if its a query, command or event',
-            `- If you are returning a flow (state machine) try and return the result in mermaid to the user, visualizing how the business logic flows`,
-            `- If you return any URLS make sure to include the host URL ${process.env.EVENTCATALOG_URL}`,
-            '- You will ALWAYS return the visualizer URL in an IFRAME in the given response - example <iframe src="http://localhost:3000/visualiser/{type}/{id}/{version}?embed=true"></iframe>',
-          ].join('\n'),
-          inputSchema: z.object({
-            id: z.string().describe('The id of the resource to find'),
-            version: z.string().describe('The version of the resource to find'),
-            type: z
-              .enum(['services', 'domains', 'events', 'commands', 'queries', 'flows', 'entities'])
-              .describe('The type of resource to find'),
-          }),
-          execute: async ({ id, version, type }) => {
-            const text = await getResourceInformation(type, id, version);
-            return text;
-          },
-        }),
-      },
-    });
-  }
-}
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/providers/anthropic.ts b/eventcatalog/src/enterprise/eventcatalog-chat/providers/anthropic.ts
deleted file mode 100644
index 710e137dd..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/providers/anthropic.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import { anthropic } from '@ai-sdk/anthropic';
-import { AIProvider, type AIProviderOptions } from './ai-provider';
-
-const AVAILABLE_GOOGLE_MODELS = [
-  'claude-3-7-sonnet-20250219',
-  'claude-3-5-sonnet-latest',
-  'claude-3-5-sonnet-20241022',
-  'claude-3-5-sonnet-20240620',
-  'claude-3-5-haiku-latest',
-  'claude-3-5-haiku-20241022',
-  'claude-3-opus-latest',
-  'claude-3-opus-20240229',
-  'claude-3-sonnet-20240229',
-  'claude-3-haiku-20240307',
-] as const;
-
-export class AnthropicProvider extends AIProvider {
-  public models: string[] = [...AVAILABLE_GOOGLE_MODELS];
-
-  constructor(options: AIProviderOptions) {
-    const languageModel = anthropic(options.modelId || 'claude-3-7-sonnet-20250219');
-
-    super({
-      ...options,
-      model: languageModel,
-    });
-  }
-}
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/providers/google.ts b/eventcatalog/src/enterprise/eventcatalog-chat/providers/google.ts
deleted file mode 100644
index 0c794465d..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/providers/google.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import { google } from '@ai-sdk/google';
-import { AIProvider, type AIProviderOptions } from './ai-provider';
-
-const AVAILABLE_GOOGLE_MODELS = [
-  'gemini-1.5-flash',
-  'gemini-1.5-flash-latest',
-  'gemini-1.5-flash-001',
-  'gemini-1.5-flash-002',
-  'gemini-1.5-flash-8b',
-  'gemini-1.5-flash-8b-latest',
-  'gemini-1.5-flash-8b-001',
-  'gemini-1.5-pro',
-  'gemini-1.5-pro-latest',
-  'gemini-1.5-pro-001',
-  'gemini-1.5-pro-002',
-  'gemini-2.0-flash',
-  'gemini-2.0-flash-001',
-  'gemini-2.0-flash-live-001',
-  'gemini-2.0-flash-lite',
-  'gemini-2.0-pro-exp-02-05',
-  'gemini-2.0-flash-thinking-exp-01-21',
-  'gemini-2.0-flash-exp',
-  'gemini-2.5-pro-exp-03-25',
-  'gemini-2.5-pro-preview-05-06',
-  'gemini-2.5-flash-preview-04-17',
-  'gemini-exp-1206',
-  'gemma-3-27b-it',
-  'learnlm-1.5-pro-experimental',
-] as const;
-
-export class GoogleProvider extends AIProvider {
-  public models: string[] = [...AVAILABLE_GOOGLE_MODELS];
-
-  constructor(options: AIProviderOptions) {
-    const languageModel = google(options.modelId || 'gemini-1.5-flash');
-    super({
-      ...options,
-      model: languageModel,
-    });
-  }
-}
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/providers/index.ts b/eventcatalog/src/enterprise/eventcatalog-chat/providers/index.ts
deleted file mode 100644
index ac7781c2d..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/providers/index.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { OpenAIProvider } from './openai';
-import { GoogleProvider } from './google';
-import { AnthropicProvider } from './anthropic';
-import type { AIProviderOptions } from './ai-provider';
-
-export function getProvider(provider: string, options: AIProviderOptions) {
-  switch (provider) {
-    case 'openai':
-      return new OpenAIProvider({
-        ...options,
-        modelId: options.modelId,
-      });
-    case 'google':
-      return new GoogleProvider({
-        ...options,
-        modelId: options.modelId,
-      });
-    case 'anthropic':
-      return new AnthropicProvider({
-        ...options,
-        modelId: options.modelId,
-      });
-    default:
-      throw new Error(`Provider ${provider} not supported`);
-  }
-}
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/providers/openai.ts b/eventcatalog/src/enterprise/eventcatalog-chat/providers/openai.ts
deleted file mode 100644
index f2ade1d8f..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/providers/openai.ts
+++ /dev/null
@@ -1,61 +0,0 @@
-import { openai } from '@ai-sdk/openai';
-import { AIProvider, type AIProviderOptions } from './ai-provider';
-
-const AVAILABLE_OPENAI_MODELS = [
-  'o1',
-  'o1-2024-12-17',
-  'o1-mini',
-  'o1-mini-2024-09-12',
-  'o1-preview',
-  'o1-preview-2024-09-12',
-  'o3-mini',
-  'o3-mini-2025-01-31',
-  'o3',
-  'o3-2025-04-16',
-  'o4-mini',
-  'o4-mini-2025-04-16',
-  'gpt-4.1',
-  'gpt-4.1-2025-04-14',
-  'gpt-4.1-mini',
-  'gpt-4.1-mini-2025-04-14',
-  'gpt-4.1-nano',
-  'gpt-4.1-nano-2025-04-14',
-  'gpt-4o',
-  'gpt-4o-2024-05-13',
-  'gpt-4o-2024-08-06',
-  'gpt-4o-2024-11-20',
-  'gpt-4o-audio-preview',
-  'gpt-4o-audio-preview-2024-10-01',
-  'gpt-4o-audio-preview-2024-12-17',
-  'gpt-4o-search-preview',
-  'gpt-4o-search-preview-2025-03-11',
-  'gpt-4o-mini-search-preview',
-  'gpt-4o-mini-search-preview-2025-03-11',
-  'gpt-4o-mini',
-  'gpt-4o-mini-2024-07-18',
-  'gpt-4-turbo',
-  'gpt-4-turbo-2024-04-09',
-  'gpt-4-turbo-preview',
-  'gpt-4-0125-preview',
-  'gpt-4-1106-preview',
-  'gpt-4',
-  'gpt-4-0613',
-  'gpt-4.5-preview',
-  'gpt-4.5-preview-2025-02-27',
-  'gpt-3.5-turbo-0125',
-  'gpt-3.5-turbo',
-  'gpt-3.5-turbo-1106',
-  'chatgpt-4o-latest',
-] as const;
-
-export class OpenAIProvider extends AIProvider {
-  public models: string[] = [...AVAILABLE_OPENAI_MODELS];
-
-  constructor(options: AIProviderOptions) {
-    const languageModel = openai(options.modelId || 'o4-mini');
-    super({
-      ...options,
-      model: languageModel,
-    });
-  }
-}
diff --git a/eventcatalog/src/enterprise/eventcatalog-chat/utils/chat-prompts.ts b/eventcatalog/src/enterprise/eventcatalog-chat/utils/chat-prompts.ts
deleted file mode 100644
index ccfaa7ff9..000000000
--- a/eventcatalog/src/enterprise/eventcatalog-chat/utils/chat-prompts.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-import { getCollection } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-
-export type ChatPrompt = CollectionEntry<'chatPrompts'>;
-
-// Update cache to store both versions
-let cachedChatPrompts: Record<string, ChatPrompt[]> = {
-  allVersions: [],
-  currentVersions: [],
-};
-
-export const getChatPrompts = async (): Promise<ChatPrompt[]> => {
-  const cacheKey = 'allVersions';
-
-  // Check if we have cached domains for this specific getAllVersions value
-  if (cachedChatPrompts[cacheKey].length > 0) {
-    return cachedChatPrompts[cacheKey];
-  }
-
-  const prompts = await getCollection('chatPrompts');
-
-  return prompts;
-};
-
-export type ChatPromptCategoryGroup = {
-  label: string;
-  icon?: string;
-  items: ChatPrompt[];
-};
-
-export const getChatPromptsGroupedByCategory = async (): Promise<ChatPromptCategoryGroup[]> => {
-  const prompts = await getChatPrompts();
-
-  const grouped = prompts.reduce(
-    (acc, prompt) => {
-      const { id, label, icon } = prompt.data.category;
-
-      if (!acc[id]) {
-        acc[id] = { label, icon, items: [] };
-      }
-
-      acc[id].items.push(prompt);
-      return acc;
-    },
-    {} as Record<string, { label: string; icon?: string; items: ChatPrompt[] }>
-  );
-
-  // Convert the grouped object into the desired array format
-  return Object.values(grouped);
-};
diff --git a/eventcatalog/src/env.d.ts b/eventcatalog/src/env.d.ts
deleted file mode 100644
index b6af1f927..000000000
--- a/eventcatalog/src/env.d.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-/// <reference path="../.astro/types.d.ts" />
-/// <reference types="astro/client" />
-
-declare const __EC_TRAILING_SLASH__: boolean;
diff --git a/eventcatalog/src/layouts/DirectoryLayout.astro b/eventcatalog/src/layouts/DirectoryLayout.astro
deleted file mode 100644
index 96020c528..000000000
--- a/eventcatalog/src/layouts/DirectoryLayout.astro
+++ /dev/null
@@ -1,116 +0,0 @@
----
-import { Table, type TData, type TCollectionTypes } from '@components/Tables/Table';
-import { buildUrl } from '@utils/url-builder';
-import VerticalSideBarLayout from './VerticalSideBarLayout.astro';
-import { User, Users } from 'lucide-react';
-import { getUsers } from '@utils/users';
-import { getTeams } from '@utils/teams';
-import config from '@config';
-
-const users = await getUsers();
-const teams = await getTeams();
-
-export interface Props<T extends TCollectionTypes> {
-  title: string;
-  subtitle: string;
-  data: TData<T>[];
-  type: T;
-}
-
-const { title, subtitle, data, type } = Astro.props;
-const currentPath = Astro.url.pathname;
-
-const checkboxLatestId = 'latest-only';
-const checkboxDraftsId = 'drafts-only';
-
-// @ts-ignore
-const tableConfiguration = config[type as keyof typeof config]?.tableConfiguration ?? { columns: {} };
-
-const tabs = [
-  {
-    label: `Users (${users.length})`,
-    href: buildUrl('/directory/users'),
-    isActive: currentPath === '/directory/users',
-    icon: User,
-    activeColor: 'orange',
-    enabled: users.length > 0,
-    visible: users.length > 0,
-  },
-  {
-    label: `Teams (${teams.length})`,
-    href: buildUrl('/directory/teams'),
-    isActive: currentPath === '/directory/teams',
-    icon: Users,
-    activeColor: 'blue',
-    enabled: teams.length > 0,
-    visible: teams.length > 0,
-  },
-];
----
-
-<VerticalSideBarLayout title={`Explore | ${title}`}>
-  <main class="ml-0">
-    <div id="discover-collection-tabs">
-      <div class="hidden sm:block">
-        <div class="border-b border-gray-200">
-          <nav class="flex space-x-8 -mb-0.5 pl-6" aria-label="Tabs">
-            {
-              tabs
-                .filter((tab) => tab.visible)
-                .map((tab) => (
-                  <a
-                    href={tab.href}
-                    class={` text-black  group inline-flex items-center py-4 px-1 text-sm font-light ${tab.isActive ? `border-${tab.activeColor}-500 border-b-[2px] text-${tab.activeColor}-500` : 'opacity-80'} ${!tab.enabled ? 'disabled' : ''}`}
-                    aria-current="page"
-                  >
-                    <tab.icon
-                      className={`w-6 h-6 -ml-0.5 mr-2  ${tab.isActive ? `text-${tab.activeColor}-500` : 'text-gray-500'}`}
-                    />
-                    <span>{tab.label}</span>
-                  </a>
-                ))
-            }
-          </nav>
-        </div>
-      </div>
-    </div>
-
-    <!-- Table -->
-    <div class="pb-20 ml-6 md:pr-10">
-      <div>
-        <div class="sm:flex sm:items-end py-4 pb-4" id="discover-title">
-          <div class="sm:flex-auto space-y-2">
-            <h1 class="text-4xl font-semibold text-gray-900 capitalize">{title}</h1>
-            <p class="text-md text-gray-700">{subtitle}</p>
-          </div>
-        </div>
-        <div class="mt-4 flow-root">
-          <div class="-mx-4 -my-2 overflow-x-auto sm:-mx-6 lg:-mx-8">
-            <div class="inline-block min-w-full align-middle sm:px-6 lg:px-8">
-              <Table
-                checkboxLatestId={checkboxLatestId}
-                checkboxDraftsId={checkboxDraftsId}
-                data={data}
-                collection={type}
-                tableConfiguration={tableConfiguration}
-                client:load
-              />
-            </div>
-          </div>
-        </div>
-      </div>
-    </div>
-  </main>
-</VerticalSideBarLayout>
-
-<style>
-  .ec-align-top {
-    vertical-align: top !important;
-  }
-
-  a.disabled {
-    pointer-events: none;
-    cursor: default;
-    opacity: 0.25;
-  }
-</style>
diff --git a/eventcatalog/src/layouts/DiscoverLayout.astro b/eventcatalog/src/layouts/DiscoverLayout.astro
deleted file mode 100644
index d176398ba..000000000
--- a/eventcatalog/src/layouts/DiscoverLayout.astro
+++ /dev/null
@@ -1,182 +0,0 @@
----
-import { Table, type TData, type TCollectionTypes } from '@components/Tables/Table';
-import { QueueListIcon, RectangleGroupIcon, BoltIcon, ChatBubbleLeftIcon } from '@heroicons/react/24/outline';
-import ServerIcon from '@heroicons/react/24/outline/ServerIcon';
-import { getCommands } from '@utils/commands';
-import { getDomains } from '@utils/collections/domains';
-import { getFlows } from '@utils/collections/flows';
-import { getEvents } from '@utils/events';
-import { getServices } from '@utils/collections/services';
-import { buildUrl } from '@utils/url-builder';
-import { getQueries } from '@utils/queries';
-import { getContainers } from '@utils/collections/containers';
-import { DatabaseIcon } from 'lucide-react';
-import { MagnifyingGlassIcon } from '@heroicons/react/20/solid';
-import VerticalSideBarLayout from './VerticalSideBarLayout.astro';
-import Checkbox from '@components/Checkbox.astro';
-import config from '@config';
-
-const events = await getEvents();
-const queries = await getQueries();
-const commands = await getCommands();
-const services = await getServices();
-const domains = await getDomains();
-const flows = await getFlows();
-const containers = await getContainers();
-export interface Props<T extends TCollectionTypes> {
-  title: string;
-  subtitle: string;
-  data: TData<T>[];
-  type: T;
-}
-
-const { title, subtitle, data, type } = Astro.props;
-const currentPath = Astro.url.pathname;
-
-const checkboxLatestId = 'latest-only';
-const checkboxDraftsId = 'show-drafts';
-
-// @ts-ignore
-const tableConfiguration = config[type as keyof typeof config]?.tableConfiguration ?? { columns: {} };
-
-const tabs = [
-  {
-    label: `Events (${events.length})`,
-    href: buildUrl('/discover/events'),
-    isActive: currentPath === '/discover/events',
-    icon: BoltIcon,
-    activeColor: 'orange',
-    enabled: events.length > 0,
-    visible: events.length > 0,
-  },
-  {
-    label: `Commands (${commands.length})`,
-    href: buildUrl('/discover/commands'),
-    isActive: currentPath === '/discover/commands',
-    icon: ChatBubbleLeftIcon,
-    activeColor: 'blue',
-    enabled: commands.length > 0,
-    visible: commands.length > 0,
-  },
-  {
-    label: `Queries (${queries.length})`,
-    href: buildUrl('/discover/queries'),
-    isActive: currentPath === '/discover/queries',
-    icon: MagnifyingGlassIcon,
-    activeColor: 'green',
-    enabled: queries.length > 0,
-    visible: queries.length > 0,
-  },
-  {
-    label: `Services (${services.length})`,
-    href: buildUrl('/discover/services'),
-    isActive: currentPath === '/discover/services',
-    icon: ServerIcon,
-    activeColor: 'pink',
-    enabled: services.length > 0,
-    visible: services.length > 0,
-  },
-  {
-    label: `Domains (${domains.length})`,
-    href: buildUrl('/discover/domains'),
-    isActive: currentPath === '/discover/domains',
-    icon: RectangleGroupIcon,
-    activeColor: 'yellow',
-    enabled: domains.length > 0,
-    visible: domains.length > 0,
-  },
-  {
-    label: `Data (${containers.length})`,
-    href: buildUrl('/discover/containers'),
-    isActive: currentPath === '/discover/containers',
-    icon: DatabaseIcon,
-    activeColor: 'blue',
-    enabled: containers.length > 0,
-    visible: containers.length > 0,
-  },
-  {
-    label: `Flows (${flows.length})`,
-    href: buildUrl('/discover/flows'),
-    isActive: currentPath === '/discover/flows',
-    icon: QueueListIcon,
-    activeColor: 'teal',
-    enabled: flows.length > 0,
-    visible: flows.length > 0,
-  },
-];
----
-
-<VerticalSideBarLayout title={`Explore | ${title}`}>
-  <main class="ml-0">
-    <div id="discover-collection-tabs">
-      <div class="hidden sm:block">
-        <div class="border-b border-gray-200">
-          <nav class="flex space-x-8 -mb-0.5 pl-6" aria-label="Tabs">
-            {
-              tabs
-                .filter((tab) => tab.visible)
-                .map((tab) => (
-                  <a
-                    href={tab.href}
-                    class={` text-black  group inline-flex items-center py-4 px-1 text-sm font-light ${tab.isActive ? `border-${tab.activeColor}-500 border-b-[2px] text-${tab.activeColor}-500` : 'opacity-80'} ${!tab.enabled ? 'disabled' : ''}`}
-                    aria-current="page"
-                  >
-                    <tab.icon
-                      className={`w-6 h-6 -ml-0.5 mr-2  ${tab.isActive ? `text-${tab.activeColor}-500` : 'text-gray-500'}`}
-                    />
-                    <span>{tab.label}</span>
-                  </a>
-                ))
-            }
-          </nav>
-        </div>
-      </div>
-    </div>
-
-    <!-- Table -->
-    <div class="pb-20 ml-6 md:pr-10">
-      <div>
-        <div class="sm:flex sm:items-end py-4 pb-4" id="discover-title">
-          <div class="sm:flex-auto space-y-2">
-            <h1 class="text-4xl font-semibold text-gray-900 capitalize">{title}</h1>
-            <p class="text-md text-gray-700">{subtitle}</p>
-          </div>
-          <div class="flex gap-4">
-            <div class="p-4 border border-gray-200 rounded-md">
-              <Checkbox id={checkboxLatestId} name={checkboxLatestId} label="Show latest version only" checked />
-            </div>
-            <div class="p-4 border border-gray-200 rounded-md">
-              <Checkbox id={checkboxDraftsId} name={checkboxDraftsId} label="Show drafts only" />
-            </div>
-          </div>
-        </div>
-        <div class="mt-4 flow-root">
-          <div class="-mx-4 -my-2 overflow-x-auto sm:-mx-6 lg:-mx-8">
-            <div class="inline-block min-w-full align-middle sm:px-6 lg:px-8">
-              <Table
-                checkboxLatestId={checkboxLatestId}
-                checkboxDraftsId={checkboxDraftsId}
-                data={data}
-                collection={type}
-                tableConfiguration={tableConfiguration}
-                client:load
-              />
-            </div>
-          </div>
-        </div>
-      </div>
-    </div>
-  </main>
-</VerticalSideBarLayout>
-
-<style>
-  .ec-align-top {
-    vertical-align: top !important;
-  }
-
-  a.disabled {
-    pointer-events: none;
-    cursor: default;
-    opacity: 0.25;
-  }
-</style>
diff --git a/eventcatalog/src/layouts/Footer.astro b/eventcatalog/src/layouts/Footer.astro
deleted file mode 100644
index d1811df8b..000000000
--- a/eventcatalog/src/layouts/Footer.astro
+++ /dev/null
@@ -1,43 +0,0 @@
----
-import { buildUrl } from '@utils/url-builder';
-import { showEventCatalogBranding } from '@utils/feature';
-const { className } = Astro.props;
----
-
-<footer class={`relative py-4 space-y-8 border-t border-gray-300 ${className}`}>
-  {
-    showEventCatalogBranding() && (
-      <div class="flex justify-between items-center py-8 text-gray-500 text-sm font-light">
-        <div class="flex space-x-5">
-          <a href="https://github.com/event-catalog/eventcatalog" target="_blank">
-            <svg
-              class="w-5 h-5 bg-gray-400 hover:bg-primary dark:hover:bg-gray-400"
-              style={`mask-image: url("${buildUrl('/icons/github.svg', true)}"); mask-repeat: no-repeat; mask-position: center center;`}
-            />
-          </a>
-          <a href="https://x.com/event_catalog" target="_blank">
-            <span class="sr-only">x</span>
-            <svg
-              class="w-5 h-5 bg-gray-400 hover:bg-primary dark:hover:bg-gray-400"
-              style={`mask-image: url("${buildUrl('/icons/x-twitter.svg', true)}"); mask-repeat: no-repeat; mask-position: center center;`}
-            />
-          </a>
-          <a href="https://www.youtube.com/@event-catalog" target="_blank">
-            <span class="sr-only">x</span>
-            <svg
-              class="w-5 h-5 bg-gray-400 hover:bg-primary dark:hover:bg-gray-400"
-              style={`mask-image: url("${buildUrl('/icons/youtube.svg', true)}"); mask-repeat: no-repeat; mask-position: center center;`}
-            />
-          </a>
-        </div>
-        <a
-          target="_blank"
-          class="hover:text-primary hover:underline text-gray-400 font-light not-prose"
-          href="https://eventcatalog.dev"
-        >
-          Powered by EventCatalog
-        </a>
-      </div>
-    )
-  }
-</footer>
diff --git a/eventcatalog/src/layouts/VerticalSideBarLayout.astro b/eventcatalog/src/layouts/VerticalSideBarLayout.astro
deleted file mode 100644
index 8bce236b9..000000000
--- a/eventcatalog/src/layouts/VerticalSideBarLayout.astro
+++ /dev/null
@@ -1,518 +0,0 @@
----
-interface Props {
-  title: string;
-  sidebar?: boolean;
-  description?: string;
-}
-
-import {
-  BookOpenText,
-  Workflow,
-  TableProperties,
-  House,
-  BookUser,
-  BotMessageSquare,
-  Users,
-  Sparkles,
-  Rocket,
-  FileText,
-  SquareDashedMousePointerIcon,
-  PackageSearch,
-  FileJson,
-} from 'lucide-react';
-import Header from '../components/Header.astro';
-import SEO from '../components/Seo.astro';
-import SideNav from '../components/SideNav/SideNav.astro';
-import config from '@config';
-import { getCollection } from 'astro:content';
-import '@fontsource/inter';
-import '@fontsource/inter/400.css'; // Specify weight
-import '@fontsource/inter/700.css'; // Specify weight
-
-import { getCommands } from '@utils/commands';
-import { getDomains } from '@utils/collections/domains';
-import { getEvents } from '@utils/events';
-import { getServices } from '@utils/collections/services';
-import { getFlows } from '@utils/collections/flows';
-import { isCollectionVisibleInCatalog } from '@eventcatalog';
-import { buildUrl } from '@utils/url-builder';
-import { getQueries } from '@utils/queries';
-import { hasLandingPageForDocs } from '@utils/pages';
-
-const events = await getEvents({ getAllVersions: false });
-const commands = await getCommands({ getAllVersions: false });
-const queries = await getQueries({ getAllVersions: false });
-const services = await getServices({ getAllVersions: false });
-const domains = await getDomains({ getAllVersions: false });
-const flows = await getFlows({ getAllVersions: false });
-const customDocs = await getCollection('customPages');
-
-import { isEventCatalogUpgradeEnabled, isVisualiserEnabled } from '@utils/feature';
-
-// Try and load any custom styles if they exist
-try {
-  await import('../../eventcatalog.styles.css');
-} catch (error) {}
-
-const currentPath = Astro.url.pathname;
-
-const catalogHasDefaultLandingPageForDocs = await hasLandingPageForDocs();
-
-const getDefaultUrl = (route: string, defaultValue: string) => {
-  if (route === 'docs/custom') {
-    return customDocs.length > 0 ? buildUrl(`/${route}/${customDocs[0].id.replace('docs', '')}`) : buildUrl(defaultValue);
-  }
-
-  const collections = [
-    { data: domains, key: 'domains' },
-    { data: services, key: 'services' },
-    { data: events, key: 'events' },
-    { data: commands, key: 'commands' },
-    { data: queries, key: 'queries' },
-    { data: flows, key: 'flows' },
-  ];
-
-  for (const { data, key } of collections) {
-    if (data.length > 0 && isCollectionVisibleInCatalog(key)) {
-      // find the first item that has visualiser set to true
-      const item = data.find((item) => item.data.visualiser !== false);
-      if (item) {
-        return buildUrl(`/${route}/${key}/${item.data.id}/${item.data.latestVersion}`);
-      } else {
-        continue;
-      }
-    }
-  }
-
-  return buildUrl(defaultValue);
-};
-
-const userSideBarConfiguration = config.sidebar || [];
-
-const navigationItems = [
-  {
-    id: '/',
-    label: 'Home',
-    icon: House,
-    href: buildUrl('/'),
-    current: currentPath === '/',
-    sidebar: false,
-    hidden: !!config.landingPage,
-  },
-  {
-    id: '/docs',
-    label: 'Architecture Documentation',
-    icon: BookOpenText,
-    href: catalogHasDefaultLandingPageForDocs ? buildUrl('/docs') : getDefaultUrl('docs', '/docs'),
-    current:
-      (currentPath.includes('/docs') && !currentPath.includes('/docs/custom')) || currentPath.includes('/architecture/docs/'),
-    sidebar: true,
-  },
-  {
-    id: '/visualiser',
-    label: 'Visualiser',
-    icon: Workflow,
-    href: getDefaultUrl('visualiser', '/visualiser'),
-    current: currentPath.includes('/visualiser'),
-    sidebar: true,
-    hidden: !isVisualiserEnabled(),
-  },
-
-  {
-    id: '/discover',
-    label: 'Explore',
-    icon: TableProperties,
-    href: buildUrl('/discover/events'),
-    current: currentPath.includes('/discover/'),
-    sidebar: false,
-  },
-  {
-    id: '/schemas',
-    label: 'Schema Explorer',
-    icon: FileJson,
-    href: buildUrl('/schemas'),
-    current: currentPath.includes('/schemas'),
-    sidebar: false,
-  },
-  {
-    id: '/directory',
-    label: 'Users & Teams',
-    icon: Users,
-    href: buildUrl('/directory/users'),
-    current: currentPath.includes('/directory'),
-    sidebar: false,
-  },
-  {
-    id: '/architecture',
-    label: 'Architecture',
-    icon: BookUser,
-    href: buildUrl('/architecture/domains'),
-    current: currentPath.includes('/architecture/'),
-    sidebar: false,
-    hidden: true,
-  },
-].filter((item) => {
-  const userSideBarOption = userSideBarConfiguration.find((config: { id: string; visible: boolean }) => config.id === item.id);
-  return userSideBarOption ? userSideBarOption.visible : true;
-});
-
-const studioNavigationItem = [
-  {
-    id: '/studio',
-    label: 'EventCatalog Studio',
-    icon: SquareDashedMousePointerIcon,
-    href: buildUrl('/studio'),
-    current: currentPath.includes('/studio'),
-    sidebar: false,
-  },
-].filter((item) => {
-  const userSideBarOption = userSideBarConfiguration.find((config: { id: string; visible: boolean }) => config.id === item.id);
-  return userSideBarOption ? userSideBarOption.visible : true;
-});
-
-const premiumFeatures = [
-  {
-    id: '/docs/custom',
-    label: 'Custom Documentation',
-    icon: FileText,
-    href: getDefaultUrl('docs/custom', '/docs/custom'),
-    current: currentPath.includes('/docs/custom'),
-    sidebar: false,
-    isPremium: true,
-  },
-  {
-    id: '/chat',
-    label: 'EventCatalog Chat',
-    icon: BotMessageSquare,
-    href: buildUrl('/chat'),
-    current: currentPath.includes('/chat'),
-    isPremium: true,
-  },
-].filter((item) => {
-  const userSideBarOption = userSideBarConfiguration.find((config: { id: string; visible: boolean }) => config.id === item.id);
-  return userSideBarOption ? userSideBarOption.visible : true;
-});
-
-const currentNavigationItem = [...navigationItems, ...studioNavigationItem, ...premiumFeatures].find((item) => item.current);
-const { title, description } = Astro.props;
-
-const showSideBarOnLoad = currentNavigationItem?.sidebar;
-
-const canPageBeEmbedded = process.env.ENABLE_EMBED === 'true';
----
-
-<!doctype html>
-<html lang="en">
-  <head>
-    <SEO title={`EventCatalog | ${title}`} description={description} ogTitle={title} />
-    <style is:global>
-      .sidebar-transition {
-        transition-property: width, transform;
-        transition-duration: 300ms;
-        transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
-      }
-      .tooltip {
-        visibility: hidden;
-        position: absolute;
-      }
-      .has-tooltip:hover .tooltip {
-        visibility: visible;
-        z-index: 100;
-      }
-
-      /* Hide anchor link by default */
-      .anchor-link {
-        display: inline-block;
-        width: 1em;
-        height: 1em;
-        margin-left: 0.5rem;
-        margin-top: 0.25rem;
-        background-image: url('data:image/svg+xml,%3Csvg%20width%3D%2216%22%20height%3D%2216%22%20viewBox%3D%220%200%2024%2024%22%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%3E%3Cpath%20fill%3D%22currentColor%22%20d%3D%22m12.11%2015.39-3.88%203.88a2.52%202.52%200%200%201-3.5%200%202.47%202.47%200%200%201%200-3.5l3.88-3.88a1%201%200%200%200-1.42-1.42l-3.88%203.89a4.48%204.48%200%200%200%206.33%206.33l3.89-3.88a1%201%200%201%200-1.42-1.42Zm8.58-12.08a4.49%204.49%200%200%200-6.33%200l-3.89%203.88a1%201%200%200%200%201.42%201.42l3.88-3.88a2.52%202.52%200%200%201%203.5%200%202.47%202.47%200%200%201%200%203.5l-3.88%203.88a1%201%200%201%200%201.42%201.42l3.88-3.89a4.49%204.49%200%200%200%200-6.33ZM8.83%2015.17a1%201%200%200%200%201.1.22%201%201%200%200%200%20.32-.22l4.92-4.92a1%201%200%200%200-1.42-1.42l-4.92%204.92a1%201%200%200%200%200%201.42Z%22/%3E%3C/svg%3E');
-        background-repeat: no-repeat;
-        background-position: center;
-        background-size: 1em 1em;
-        opacity: 0;
-        transition: opacity 0.2s ease-in-out;
-        text-decoration: none;
-        vertical-align: -2px;
-      }
-
-      /* Show icon on heading hover */
-      h1:hover .anchor-link,
-      h2:hover .anchor-link,
-      h3:hover .anchor-link,
-      h4:hover .anchor-link,
-      h5:hover .anchor-link,
-      h6:hover .anchor-link {
-        opacity: 1;
-      }
-
-      /* Show on keyboard focus */
-      .anchor-link:focus {
-        opacity: 1;
-        outline: none;
-      }
-    </style>
-  </head>
-  <body>
-    <Header />
-    <div class="flex">
-      <aside class="flex" id="eventcatalog-vertical-nav">
-        <div
-          class="fixed flex flex-col items-center w-16 h-screen py-4 bg-white bg-gradient-to-b from-white to-gray-100 border-r border-gray-200 z-20 shadow-md justify-between"
-        >
-          <nav class="flex flex-col h-[calc(100vh-70px)] justify-between">
-            <div class="flex flex-col items-center flex-1 space-y-6">
-              {
-                navigationItems
-                  .filter((item) => !item.hidden)
-                  .map((item) => {
-                    return (
-                      <a
-                        id={item.id}
-                        data-role="nav-item"
-                        href={item.href}
-                        class={`p-1.5 inline-block transition-colors duration-200 rounded-lg ${
-                          item.current
-                            ? 'text-white bg-gradient-to-b from-purple-500 to-purple-700'
-                            : 'hover:bg-gradient-to-r hover:from-purple-500 hover:to-purple-700 hover:text-white text-gray-700'
-                        }`}
-                      >
-                        <div class="has-tooltip">
-                          <span class="tooltip rounded shadow-lg p-1 text-xs bg-gradient-to-l from-purple-500 to-purple-700 text-white ml-10">
-                            {item.label}
-                          </span>
-                          <item.icon className="h-6 w-6" />
-                        </div>
-                      </a>
-                    );
-                  })
-              }
-
-              <hr class="w-8 border-t border-gray-200" />
-
-              {
-                studioNavigationItem.length > 0 && (
-                  <a
-                    id={studioNavigationItem[0].id}
-                    data-role="nav-item"
-                    href={studioNavigationItem[0].href}
-                    class={`p-1.5 inline-block pt-1 pb-1 mt-0 mb-0 transition-colors duration-200 rounded-lg relative ${studioNavigationItem[0].current ? 'text-white bg-gradient-to-b from-purple-500 to-purple-700' : 'hover:bg-gradient-to-r hover:from-purple-500 hover:to-purple-700 hover:text-white text-gray-700'}`}
-                  >
-                    <div class="has-tooltip">
-                      <span class="tooltip rounded shadow-lg p-1 text-xs bg-gradient-to-l from-purple-500 to-purple-700 text-white ml-10">
-                        {studioNavigationItem[0].label}
-                      </span>
-                      <SquareDashedMousePointerIcon className="h-6 w-6" />
-                    </div>
-                  </a>
-                )
-              }
-
-              {studioNavigationItem.length > 0 && <hr class="w-8 border-t border-gray-200" />}
-
-              {
-                premiumFeatures.map((item) => (
-                  <a
-                    id={item.id}
-                    data-role="nav-item"
-                    href={item.href}
-                    class={`p-1.5 inline-block transition-colors duration-200 rounded-lg mb-8 relative ${
-                      item.current
-                        ? 'text-white bg-gradient-to-b from-purple-500 to-purple-700'
-                        : 'hover:bg-gradient-to-r hover:from-purple-500 hover:to-purple-700 hover:text-white text-gray-700'
-                    }`}
-                  >
-                    <div class="has-tooltip">
-                      <span class="tooltip rounded shadow-lg p-1 text-xs bg-gradient-to-l from-indigo-500 to-indigo-700 text-white ml-10 flex items-center gap-1">
-                        <Sparkles className="h-3 w-3" /> {item.label}
-                      </span>
-                      <item.icon className="h-6 w-6" />
-                      <div class="absolute -top-1 -right-1 bg-gradient-to-r from-amber-400 to-amber-500 rounded-full p-0.5 shadow-lg">
-                        <Sparkles className="h-2 w-2 text-white" />
-                      </div>
-                    </div>
-                  </a>
-                ))
-              }
-            </div>
-
-            {
-              isEventCatalogUpgradeEnabled() && (
-                <div class="mb-4">
-                  <a
-                    id="/pro"
-                    data-role="nav-item"
-                    href={buildUrl('/plans')}
-                    class={`p-1.5 inline-block transition-colors duration-200 rounded-lg ${currentPath.includes('/pro') ? 'text-white bg-gradient-to-b from-purple-500 to-purple-700' : 'bg-gradient-to-r from-purple-100 to-indigo-100 hover:from-purple-500 hover:to-purple-700 hover:text-white text-purple-700'}`}
-                  >
-                    <div class="has-tooltip">
-                      <span class="tooltip rounded shadow-lg p-1 text-xs bg-gradient-to-l from-purple-500 to-purple-700 text-white ml-10">
-                        Upgrade EventCatalog
-                      </span>
-                      <Rocket className="h-6 w-6" />
-                    </div>
-                  </a>
-                </div>
-              )
-            }
-          </nav>
-        </div>
-
-        <SideNav
-          id="sidebar"
-          class={`sidebar-transition h-content  overflow-y-auto bg-white  border-r border-gray-100 w-[22em] ml-16 ${showSideBarOnLoad ? 'block' : 'hidden'}`}
-        />
-      </aside>
-      <main
-        class={`sidebar-transition w-full max-h-content overflow-y-auto ${showSideBarOnLoad ? 'ml-0' : 'ml-16'}`}
-        id="content"
-      >
-        <slot />
-      </main>
-
-      <!-- Create a overlay that tells people to purchase backstage plugin if they want to embed the page -->
-      <div class="absolute inset-0 bg-black items-center justify-center z-50 hidden" id="embed-overlay">
-        <div class="text-white text-center space-y-4">
-          <div>
-            <h1 class="text-2xl font-bold">EventCatalog Backstage Integration</h1>
-            <p class="text-md text-red-500">Missing license key for backstage integration.</p>
-          </div>
-          <div>
-            <p class="text-sm text-gray-500">Please configure the backstage plugin to embed this page into Backstage.</p>
-            <a href="https://www.eventcatalog.dev/integrations/backstage" class="text-blue-500 text-xs"
-              >Configure backstage plugin &rarr;</a
-            >
-          </div>
-        </div>
-      </div>
-    </div>
-  </body>
-</html>
-<script define:vars={{ navigationItems, currentNavigationItem, showSideBarOnLoad, canPageBeEmbedded }}>
-  // Listen for Astro transititions
-  document.addEventListener('astro:page-load', () => {
-    document.dispatchEvent(new CustomEvent('contentLoaded'));
-  });
-
-  // Listen for DOM loaded
-  document.addEventListener('DOMContentLoaded', () => {
-    document.dispatchEvent(new CustomEvent('contentLoaded'));
-  });
-
-  document.addEventListener('contentLoaded', () => {
-    // Users can add ?embed=true to the URL to hide the navigation
-    const urlSearchParams = new URLSearchParams(window.location.search);
-    const params = Object.fromEntries(urlSearchParams.entries());
-    const embeded = params.embed === 'true' ? true : false;
-    const content = document.getElementById('content');
-
-    if (embeded && !canPageBeEmbedded) {
-      const overlay = document.getElementById('embed-overlay');
-      overlay.style.display = 'flex';
-      return;
-    }
-
-    if (embeded) {
-      const elementsToHide = [
-        'eventcatalog-vertical-nav',
-        'eventcatalog-header',
-        'eventcatalog-header-spacer',
-        'visualiser-footer',
-        // /discover page elements
-        'discover-collection-tabs',
-        'discover-title',
-      ];
-
-      elementsToHide.forEach((id) => {
-        const element = document.getElementById(id);
-        if (element) element.style.display = 'none';
-      });
-
-      content.classList.remove('ml-16');
-      return;
-    }
-
-    const sidebar = document.getElementById('sidebar');
-    const currentPath = window.location.href;
-
-    // Hide the sidebar if the current navigation item is not a sidebar item
-    if (!currentNavigationItem?.sidebar) {
-      sidebar.style.display = 'none';
-      content.style.width = '100%';
-      content.classList.add('ml-16');
-    } else {
-      sidebar.style.display = 'block';
-    }
-
-    const navItems = document.querySelectorAll('[data-role="nav-item"]');
-    let isOpen = showSideBarOnLoad;
-
-    navItems.forEach((item) => {
-      item.addEventListener('click', (e) => {
-        const currentPath = window.location.href;
-        const id = item.getAttribute('id');
-
-        const navItem = navigationItems.find((navItem) => navItem.id === id);
-
-        if (!navItem.sidebar || !currentPath.includes(navItem.id) || currentPath.includes('/docs/custom')) {
-          window.location.href = navItem.href;
-          return;
-        }
-
-        // not on the target page then just go to it.
-        if (!currentPath.includes(navItem.id)) return;
-
-        if (currentPath.includes(navItem.id)) {
-          e.preventDefault();
-          if (isOpen) {
-            hideSidebar();
-          } else {
-            showSidebar();
-          }
-        }
-      });
-    });
-
-    function showSidebar() {
-      if (!sidebar || !content) return;
-      isOpen = true;
-      localStorage.setItem('sidebarState', 'open');
-      sidebar.style.display = 'block';
-      setTimeout(() => {
-        sidebar.style.transform = 'translateX(0)';
-        content.style.transform = 'translateX(0)';
-        content.classList.remove('ml-16');
-        content.style.width = 'calc(100% - 240px)';
-      }, 10);
-    }
-
-    function hideSidebar() {
-      if (!sidebar || !content) return;
-      isOpen = false;
-      sidebar.style.transform = 'translateX(-100%)';
-      content.style.transform = 'translateX(0px)';
-      content.style.width = '100%';
-      content.classList.add('ml-16');
-    }
-
-    if (sidebar) {
-      sidebar.addEventListener('transitionend', () => {
-        if (!isOpen && sidebar && content) {
-          sidebar.style.display = 'none';
-          content.style.transform = 'translateX(0px)';
-        }
-      });
-    }
-
-    // Listen for custom sidebar toggle event from React components
-    window.addEventListener('sidebarToggle', (event) => {
-      const { action } = event.detail;
-      if (action === 'hide') {
-        hideSidebar();
-      } else if (action === 'show') {
-        showSidebar();
-      }
-    });
-  });
-</script>
diff --git a/eventcatalog/src/layouts/VisualiserLayout.astro b/eventcatalog/src/layouts/VisualiserLayout.astro
deleted file mode 100644
index a54e65ea2..000000000
--- a/eventcatalog/src/layouts/VisualiserLayout.astro
+++ /dev/null
@@ -1,167 +0,0 @@
----
-import { getCommands } from '@utils/commands';
-import { getDomains } from '@utils/collections/domains';
-import { getEvents } from '@utils/events';
-import { getFlows } from '@utils/collections/flows';
-import { getQueries } from '@utils/queries';
-import { getServices } from '@utils/collections/services';
-import VerticalSideBarLayout from './VerticalSideBarLayout.astro';
-
-const [services, events, commands, queries, domains, flows] = await Promise.all([
-  getServices(),
-  getEvents(),
-  getCommands(),
-  getQueries(),
-  getDomains(),
-  getFlows(),
-]);
-
-// @ts-ignore for large catalogs https://github.com/event-catalog/eventcatalog/issues/552
-const navItems = [...domains, ...services, ...events, ...commands, ...queries, ...flows];
-
-const navigation = navItems
-  .filter((item) => item.data.version === item.data.latestVersion)
-  .reduce((acc, item) => {
-    //  @ts-ignore
-    const group = acc[item.collection] || [];
-
-    return {
-      ...acc,
-      [item.collection]: [...group, item],
-    };
-  }, {}) as any;
-
-const currentPath = Astro.url.pathname;
-const { title, description } = Astro.props;
-
-const getColor = (collection: string) => {
-  switch (collection) {
-    case 'services':
-      return 'green';
-    case 'events':
-      return 'red';
-    case 'queries':
-      return 'green';
-    case 'commands':
-      return 'yellow';
-    case 'domains':
-      return 'blue';
-    default:
-      return 'gray';
-  }
-};
----
-
-<VerticalSideBarLayout title={title} description={description}>
-  <div class="">
-    <div class="">
-      <!-- <div class="hidden md:block">
-        <aside class="sm:fixed grow w-56 xl:w-[19em] overflow-y-auto h-full z-10 pb-20" id="visualiser-navigation">
-          <div class="w-full">
-            <div class="sticky top-0 z-10 h-8 pointer-events-none -mt-7">
-              <div class="h-full bg-gradient-to-b from-white to-transparent"></div>
-            </div>
-            {
-              Object.keys(navigation).map((key: any) => {
-                const items = navigation[key]
-                  .map((item: any) => {
-                    const isCurrent = currentPath.includes(`${item.collection}/${item.data.id}/${item.data.version}`);
-                    const isLatest = item.data.version === item.data.latestVersion;
-                    if (!isLatest) return null;
-                    return {
-                      label: item.data.name,
-                      version: item.data.version,
-                      color: getColor(item.collection),
-                      href: buildUrl(`/visualiser/${item.collection}/${item.data.id}/${item.data.version}`),
-                      active: isCurrent,
-                    };
-                  })
-                  .filter((n: any) => n !== null);
-                return (
-                  <BasicList
-                    title={`${key} (${navigation[key].length})`}
-                    items={items}
-                    emptyMessage="Nothing to show"
-                    color="gray"
-                    client:load
-                  />
-                );
-              })
-            }
-          </div>
-        </aside>
-      </div> -->
-
-      <main class="flex-1 h-full w-full relative">
-        <!-- <button
-          id="fullscreen-toggle"
-          class="absolute top-[1em] z-40 left-5 bg-white hover:bg-gray-100/50 border border-gray-200 hover:text-primary text-gray-800 font-semibold py-2 px-4 rounded-lg transition duration-300 ease-in-out flex items-center space-x-2 focus:outline-none focus:ring-2 focus:ring-blue-400 focus:ring-opacity-75"
-        >
-          <svg xmlns="http://www.w3.org/2000/svg" class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-            <path
-              stroke-linecap="round"
-              stroke-linejoin="round"
-              stroke-width="2"
-              d="M4 8V4m0 0h4M4 4l5 5m11-1V4m0 0h-4m4 0l-5 5M4 16v4m0 0h4m-4 0l5-5m11 5l-5-5m5 5v-4m0 4h-4"></path>
-          </svg>
-          <span>Toggle Fullscreen</span>
-        </button> -->
-        <slot />
-      </main>
-    </div>
-  </div>
-</VerticalSideBarLayout>
-
-<script>
-  function setupSidebarToggle() {
-    const sidebar = document.getElementById('visualiser-navigation');
-    const toggleButton = document.getElementById('fullscreen-toggle');
-    const eventCatalogHeader = document.getElementById('eventcatalog-header');
-    const eventCatalogHeaderSpacer = document.getElementById('eventcatalog-header-spacer');
-    let isSidebarVisible = true;
-
-    if (!sidebar || !toggleButton) return;
-
-    function toggleSidebar() {
-      isSidebarVisible = !isSidebarVisible;
-      if (sidebar) sidebar.style.display = isSidebarVisible ? 'block' : 'none';
-      if (eventCatalogHeader) eventCatalogHeader.style.display = isSidebarVisible ? 'block' : 'none';
-      if (eventCatalogHeaderSpacer) eventCatalogHeaderSpacer.style.display = isSidebarVisible ? 'block' : 'none';
-    }
-
-    // Remove existing event listener if it exists
-    toggleButton.removeEventListener('click', toggleSidebar);
-
-    // Add the event listener
-    toggleButton.addEventListener('click', toggleSidebar);
-  }
-
-  // Run the setup immediately
-  setupSidebarToggle();
-
-  // Re-run the setup after each navigation
-  document.addEventListener('astro:page-load', setupSidebarToggle);
-</script>
-
-<style>
-  #visualiser-navigation {
-    transform: translateX(0);
-  }
-</style>
-
-<style>
-  #visualiser-navigation {
-    transition:
-      transform 0.3s ease-in-out,
-      opacity 0.3s ease-in-out;
-    transform: translateX(0);
-    opacity: 1;
-  }
-  #visualiser-navigation.hidden {
-    transform: translateX(-100%);
-    opacity: 0;
-  }
-  main {
-    transition: margin-left 0.3s ease-in-out;
-  }
-</style>
diff --git a/eventcatalog/src/middleware.ts b/eventcatalog/src/middleware.ts
deleted file mode 100644
index 481b96763..000000000
--- a/eventcatalog/src/middleware.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import type { MiddlewareHandler } from 'astro';
-import { authMiddleware } from './middleware-auth.ts';
-import { sequence } from 'astro:middleware';
-import { join } from 'node:path';
-import { isSSR } from '@utils/feature';
-
-// Try to load customer's custom RBAC middleware
-let customerRbacMiddleware: MiddlewareHandler | null = null;
-
-try {
-  const catalogDirectory = process.env.PROJECT_DIR || process.cwd();
-  const customerMiddleware = await import(/* @vite-ignore */ join(catalogDirectory, 'middleware.ts'));
-  customerRbacMiddleware = customerMiddleware.rbacMiddleware;
-
-  if (!isSSR()) {
-    // Tell user they need to build in SSR mode
-    console.log(
-      '🔴 Found custom middleware.ts file. To use RBAC, you need to build in SSR mode, by setting output: "server" in your eventcatalog.config.js file.'
-    );
-  } else {
-    console.log('✅ Loaded custom RBAC middleware');
-  }
-} catch (error) {
-  // Just silently fail, we don't want to block the app
-}
-
-const errorHandlingMiddleware: MiddlewareHandler = async (context, next) => {
-  const response = await next();
-
-  if (response.status === 403) {
-    const params = new URLSearchParams({
-      path: context.url.pathname,
-      returnTo: context.url.pathname + context.url.search,
-    });
-
-    return context.redirect(`/unauthorized?${params.toString()}`);
-  }
-
-  return response;
-};
-
-const middlewareChain = customerRbacMiddleware
-  ? [errorHandlingMiddleware, authMiddleware, customerRbacMiddleware]
-  : [errorHandlingMiddleware, authMiddleware];
-
-export const onRequest = isSSR() ? sequence(...middlewareChain) : undefined;
diff --git a/eventcatalog/src/pages/_index.astro b/eventcatalog/src/pages/_index.astro
deleted file mode 100644
index 7749c6cf0..000000000
--- a/eventcatalog/src/pages/_index.astro
+++ /dev/null
@@ -1,278 +0,0 @@
----
-import { buildUrl } from '@utils/url-builder';
-import { ChatBubbleLeftIcon, RectangleGroupIcon, ServerIcon } from '@heroicons/react/24/outline';
-import config from '@config';
-
-import { getMessages } from '@utils/messages';
-import { getDomains } from '@utils/collections/domains';
-import { getServices } from '@utils/collections/services';
-import { getFlows } from '@utils/collections/flows';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { BookOpenText, Workflow, TableProperties, House, BookUser, MessageSquare, BotMessageSquare, Users } from 'lucide-react';
-
-const { commands = [], events = [], queries = [] } = await getMessages({ getAllVersions: false });
-const messages = [...events, ...queries, ...commands];
-const domains = await getDomains({ getAllVersions: false });
-const services = await getServices({ getAllVersions: false });
-const flows = await getFlows({ getAllVersions: false });
-
-const gettingStartedItems = [
-  {
-    title: 'Add a New Message',
-    icon: ChatBubbleLeftIcon,
-    iconBg: 'blue',
-    description: 'Document a new message in your system with schemas, examples, and relationships.',
-    links: [
-      {
-        text: 'How to add a message',
-        href: 'https://www.eventcatalog.dev/docs/messages',
-      },
-      {
-        text: 'Versioning guide',
-        href: 'https://www.eventcatalog.dev/docs/development/guides/messages/events/versioning',
-      },
-      {
-        text: 'Adding schemas',
-        href: 'https://www.eventcatalog.dev/docs/development/guides/messages/events/adding-schemas',
-      },
-    ],
-  },
-  {
-    title: 'Document a Service',
-    icon: ServerIcon,
-    iconBg: 'green',
-    description: 'Add details about a service, including its events, APIs, and dependencies.',
-    links: [
-      {
-        text: 'How to add a service',
-        href: 'https://www.eventcatalog.dev/docs/services',
-      },
-      {
-        text: 'Service ownership',
-        href: 'https://www.eventcatalog.dev/docs/development/guides/services/owners',
-      },
-      {
-        text: 'Assign specifications to services',
-        href: 'https://www.eventcatalog.dev/docs/development/guides/services/adding-spec-files-to-services',
-      },
-    ],
-  },
-  {
-    title: 'Create a Domain',
-    icon: RectangleGroupIcon,
-    iconBg: 'purple',
-    description: 'Organize your services and events into logical business domains.',
-    links: [
-      {
-        text: 'How to add a domain',
-        href: 'https://www.eventcatalog.dev/docs/domains',
-      },
-      {
-        text: 'Adding services to domains',
-        href: 'https://www.eventcatalog.dev/docs/development/guides/domains/adding-services-to-domains',
-      },
-      {
-        text: 'Creating a ubiquitous language',
-        href: 'https://www.eventcatalog.dev/docs/development/guides/domains/adding-ubiquitous-language',
-      },
-    ],
-  },
-];
-
-const getDefaultUrl = (route: string, defaultValue: string) => {
-  if (domains.length > 0) return buildUrl(`/${route}/domains/${domains[0].data.id}/${domains[0].data.latestVersion}`);
-  if (services.length > 0) return buildUrl(`/${route}/services/${services[0].data.id}/${services[0].data.latestVersion}`);
-  if (flows.length > 0) return buildUrl(`/${route}/flows/${flows[0].data.id}/${flows[0].data.latestVersion}`);
-  return buildUrl(defaultValue);
-};
-
-const topTiles = [
-  {
-    title: 'Domains',
-    count: domains.length,
-    description: 'Business domains defined',
-    href: buildUrl('/architecture/domains'),
-    icon: RectangleGroupIcon,
-    bgColor: 'bg-yellow-100',
-    textColor: 'text-yellow-600',
-    arrowColor: 'text-yellow-600',
-  },
-  {
-    title: 'Services',
-    count: services.length,
-    description: 'Services documented in the catalog',
-    href: buildUrl('/architecture/services'),
-    icon: ServerIcon,
-    bgColor: 'bg-pink-100',
-    textColor: 'text-pink-600',
-    arrowColor: 'text-pink-600',
-  },
-  {
-    title: 'Messages',
-    count: messages.length,
-    description: 'Messages documented in the catalog',
-    href: buildUrl('/architecture/messages'),
-    icon: ChatBubbleLeftIcon,
-    bgColor: 'bg-blue-100',
-    textColor: 'text-blue-600',
-    arrowColor: 'text-blue-600',
-  },
-];
----
-
-<VerticalSideBarLayout title="EventCatalog">
-  <body class="min-h-screen bg-gray-50 font-inter">
-    <main class="container px-8 lg:px-8 mx-auto py-8 max-w-[80em]">
-      <div class="mb-12">
-        <h1 class="text-4xl font-semibold mb-4 text-gray-900 font-inter">
-          {config?.organizationName || 'EventCatalog'}
-        </h1>
-        <p class="text-base mb-0 text-gray-600 max-w-3xl">
-          {config.tagline || 'Comprehensive event-driven architecture documentation covering events, services, domains.'}
-        </p>
-      </div>
-
-      <h2 class="text-2xl font-semibold mb-8 text-gray-900">Architecture overview</h2>
-      <div class="grid grid-cols-1 md:grid-cols-3 gap-4 mb-12">
-        {
-          topTiles.map((tile) => (
-            <a
-              href={tile.href}
-              class="bg-white p-5 rounded-lg shadow-sm border border-gray-200 hover:shadow-md transition-all duration-200"
-            >
-              <div class="flex items-center justify-between mb-2">
-                <div class="flex items-center gap-3">
-                  <div class={`p-1.5 ${tile.bgColor} rounded-lg`}>
-                    <tile.icon className={`w-4 h-4 ${tile.textColor}`} />
-                  </div>
-                  <h3 class="text-lg font-semibold text-gray-900">
-                    {tile.count} {tile.title}
-                  </h3>
-                </div>
-                <span class={`text-sm font-medium ${tile.arrowColor}`}>View all →</span>
-              </div>
-              <p class="text-sm text-gray-600">{tile.description}</p>
-            </a>
-          ))
-        }
-      </div>
-
-      <div class="mb-12">
-        <h2 class="text-2xl font-semibold mb-8 text-gray-900">Explore EventCatalog</h2>
-        <div class="grid grid-cols-12 gap-4">
-          <a
-            href={getDefaultUrl('docs', 'domains')}
-            class="col-span-6 row-span-2 group bg-white rounded-lg shadow-sm hover:shadow-md transition-all duration-300 border border-gray-200 overflow-hidden"
-          >
-            <div class="h-24 bg-gradient-to-br from-blue-50 to-blue-100 border-b border-gray-200"></div>
-            <div class="p-4">
-              <div class="flex items-center gap-3 mb-3">
-                <div class="p-2 bg-blue-100 rounded-lg group-hover:scale-105 transition-transform">
-                  <BookOpenText className="w-5 h-5 text-blue-600" />
-                </div>
-                <h3 class="text-lg font-semibold text-gray-900 group-hover:text-blue-600">Documentation</h3>
-              </div>
-              <p class="text-sm text-gray-600">
-                Read documentation for {config.organizationName || 'EventCatalog'} messages, services and domains.
-              </p>
-            </div>
-          </a>
-
-          <a
-            href={getDefaultUrl('visualiser', 'domains')}
-            class="col-span-6 row-span-2 group bg-white rounded-lg shadow-sm hover:shadow-md transition-all duration-300 border border-gray-200 overflow-hidden"
-          >
-            <div class="h-24 bg-gradient-to-br from-purple-50 to-purple-100 border-b border-gray-200"></div>
-            <div class="p-4">
-              <div class="flex items-center gap-3 mb-3">
-                <div class="p-2 bg-purple-100 rounded-lg group-hover:scale-105 transition-transform">
-                  <Workflow className="w-5 h-5 text-purple-600" />
-                </div>
-                <h3 class="text-base font-semibold text-gray-900 group-hover:text-purple-600">Visualizer</h3>
-              </div>
-              <p class="text-sm text-gray-600">Explore interactive visualizations of your architecture.</p>
-            </div>
-          </a>
-
-          <a
-            href={buildUrl('/discover/events')}
-            class="col-span-4 row-span-2 group bg-white rounded-lg shadow-sm hover:shadow-md transition-all duration-300 border border-gray-200 overflow-hidden"
-          >
-            <div class="h-24 bg-gradient-to-br from-teal-50 to-teal-100 border-b border-gray-200"></div>
-            <div class="p-4">
-              <div class="flex items-center gap-3 mb-3">
-                <div class="p-2 bg-teal-100 rounded-lg group-hover:scale-105 transition-transform">
-                  <TableProperties className="w-5 h-5 text-teal-600" />
-                </div>
-                <h3 class="text-base font-semibold text-gray-900 group-hover:text-teal-600">Explore</h3>
-              </div>
-              <p class="text-sm text-gray-600">Navigate through your events and services</p>
-            </div>
-          </a>
-
-          <a
-            href={buildUrl('/chat')}
-            class="col-span-4 row-span-2 group bg-white rounded-lg shadow-sm hover:shadow-md transition-all duration-300 border border-gray-200 overflow-hidden"
-          >
-            <div class="h-24 bg-gradient-to-br from-green-50 to-green-100 border-b border-gray-200"></div>
-            <div class="p-4">
-              <div class="flex items-center gap-3 mb-3">
-                <div class="p-2 bg-green-100 rounded-lg group-hover:scale-105 transition-transform">
-                  <BotMessageSquare className="w-5 h-5 text-green-600" />
-                </div>
-                <h3 class="text-base font-semibold text-gray-900 group-hover:text-green-600">Chat</h3>
-              </div>
-              <p class="text-sm text-gray-600">Ask questions about your architecture</p>
-            </div>
-          </a>
-
-          <a
-            href={buildUrl('/directory/users')}
-            class="col-span-4 row-span-2 group bg-white rounded-lg shadow-sm hover:shadow-md transition-all duration-300 border border-gray-200 overflow-hidden"
-          >
-            <div class="h-24 bg-gradient-to-br from-orange-50 to-orange-100 border-b border-gray-200"></div>
-            <div class="p-4">
-              <div class="flex items-center gap-3 mb-3">
-                <div class="p-2 bg-orange-100 rounded-lg group-hover:scale-105 transition-transform">
-                  <BookUser className="w-5 h-5 text-orange-600" />
-                </div>
-                <h3 class="text-base font-semibold text-gray-900 group-hover:text-orange-600">Users & Teams</h3>
-              </div>
-              <p class="text-sm text-gray-600">Discover service and message ownership</p>
-            </div>
-          </a>
-        </div>
-      </div>
-
-      <section class="mb-12">
-        <h2 class="text-2xl font-semibold mb-8 text-gray-900">Getting Started</h2>
-        <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
-          {
-            gettingStartedItems.map((item) => (
-              <div class="bg-white rounded-xl shadow-sm border border-gray-200 p-6">
-                <div class="flex items-center gap-3 mb-4">
-                  <div class={`p-2 bg-${item.iconBg}-100 rounded-lg`}>
-                    <item.icon className={`w-6 h-6 text-${item.iconBg}-600`} />
-                  </div>
-                  <h3 class="text-lg font-semibold text-gray-900">{item.title}</h3>
-                </div>
-                <p class="text-gray-600 text-sm mb-4">{item.description}</p>
-                <div class="space-y-2">
-                  {item.links.map((link) => (
-                    <a
-                      href={link.href}
-                      target="_blank"
-                      class={`block text-sm text-${item.iconBg}-600 hover:text-${item.iconBg}-700`}
-                    >
-                      → {link.text}
-                    </a>
-                  ))}
-                </div>
-              </div>
-            ))
-          }
-        </div>
-      </section>
-    </main>
-  </body>
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/api/catalog.ts b/eventcatalog/src/pages/api/catalog.ts
deleted file mode 100644
index 58f504d68..000000000
--- a/eventcatalog/src/pages/api/catalog.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import type { APIRoute } from 'astro';
-import utils from '@eventcatalog/sdk';
-import config from '@config';
-
-/**
- * Route the will dump the whole catalog as JSON (without markdown)
- * Experimental API
- * @param param0
- * @returns
- */
-export const GET: APIRoute = async ({ params, request }) => {
-  const isFullCatalogAPIEnabled = config.api?.fullCatalogAPIEnabled ?? true;
-
-  if (!isFullCatalogAPIEnabled) {
-    return new Response(JSON.stringify({ error: 'Full catalog API is not enabled' }), {
-      status: 404,
-    });
-  }
-
-  const { dumpCatalog } = utils(process.env.PROJECT_DIR || '');
-  const catalog = await dumpCatalog({ includeMarkdown: false });
-
-  return new Response(JSON.stringify(catalog), {
-    headers: {
-      'Content-Type': 'application/json',
-    },
-  });
-};
diff --git a/eventcatalog/src/pages/api/schemas/[collection]/[id]/[version]/index.ts b/eventcatalog/src/pages/api/schemas/[collection]/[id]/[version]/index.ts
deleted file mode 100644
index f34c3105e..000000000
--- a/eventcatalog/src/pages/api/schemas/[collection]/[id]/[version]/index.ts
+++ /dev/null
@@ -1,82 +0,0 @@
-import type { APIRoute } from 'astro';
-import { getCollection } from 'astro:content';
-import path from 'node:path';
-import fs from 'node:fs';
-import { isEventCatalogScaleEnabled } from '@utils/feature';
-import { sortVersioned } from '@utils/collections/util';
-
-export async function getStaticPaths() {
-  const events = await getCollection('events');
-  const commands = await getCollection('commands');
-  const queries = await getCollection('queries');
-  const messages = [...events, ...commands, ...queries];
-
-  const messagesWithSchemas = messages
-    .filter((message) => message.data.schemaPath)
-    .filter((message) => fs.existsSync(path.join(path.dirname(message.filePath ?? ''), message.data.schemaPath ?? '')));
-
-  // Generate paths for specific versions
-  const versionedPaths = messagesWithSchemas.map((message) => ({
-    params: { collection: message.collection, id: message.data.id, version: message.data.version },
-    props: {
-      pathToSchema: path.join(path.dirname(message.filePath ?? ''), message.data.schemaPath ?? ''),
-      schema: fs.readFileSync(path.join(path.dirname(message.filePath ?? ''), message.data.schemaPath ?? ''), 'utf8'),
-      extension: message.data.schemaPath?.split('.').pop(),
-    },
-  }));
-
-  // Group messages by collection and id to find latest versions
-  const groupedMessages = messagesWithSchemas.reduce(
-    (acc, message) => {
-      const key = `${message.collection}:${message.data.id}`;
-      if (!acc[key]) {
-        acc[key] = [];
-      }
-      acc[key].push(message);
-      return acc;
-    },
-    {} as Record<string, typeof messagesWithSchemas>
-  );
-
-  // Generate "latest" paths for each unique collection/id combination
-  const latestPaths = Object.values(groupedMessages).map((group) => {
-    // Sort by version (descending) and get the latest
-    const sorted = sortVersioned(group, (m) => m.data.version);
-    const latestMessage = sorted[0];
-    return {
-      params: { collection: latestMessage.collection, id: latestMessage.data.id, version: 'latest' },
-      props: {
-        pathToSchema: path.join(path.dirname(latestMessage.filePath ?? ''), latestMessage.data.schemaPath ?? ''),
-        schema: fs.readFileSync(
-          path.join(path.dirname(latestMessage.filePath ?? ''), latestMessage.data.schemaPath ?? ''),
-          'utf8'
-        ),
-        extension: latestMessage.data.schemaPath?.split('.').pop(),
-      },
-    };
-  });
-
-  return [...versionedPaths, ...latestPaths];
-}
-
-export const GET: APIRoute = async ({ props }) => {
-  if (!isEventCatalogScaleEnabled()) {
-    return new Response(
-      JSON.stringify({
-        error: 'feature_not_available_on_server',
-        message: 'Schema API is not enabled for this deployment and supported in EventCatalog Scale.',
-      }),
-      {
-        status: 501,
-        headers: {
-          'Content-Type': 'application/json',
-          'Cache-Control': 'no-store',
-        },
-      }
-    );
-  }
-
-  return new Response(props.schema, {
-    headers: { 'Content-Type': 'text/plain' },
-  });
-};
diff --git a/eventcatalog/src/pages/api/schemas/services/[id]/[version]/[specification]/index.ts b/eventcatalog/src/pages/api/schemas/services/[id]/[version]/[specification]/index.ts
deleted file mode 100644
index 23bfbf285..000000000
--- a/eventcatalog/src/pages/api/schemas/services/[id]/[version]/[specification]/index.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-import type { APIRoute } from 'astro';
-import { getCollection } from 'astro:content';
-import path from 'node:path';
-import fs from 'node:fs';
-import { getSpecificationsForService } from '@utils/collections/services';
-import { isEventCatalogScaleEnabled } from '@utils/feature';
-
-export async function getStaticPaths() {
-  const services = await getCollection('services');
-  const servicesWithSpecifications = services.filter((service) => getSpecificationsForService(service).length > 0);
-  return servicesWithSpecifications.reduce<
-    { params: { collection: string; id: string; version: string; specification: string }; props: { schema: string } }[]
-  >(
-    (acc, service) => {
-      const specifications = getSpecificationsForService(service);
-      return [
-        ...acc,
-        ...specifications.map((specification) => ({
-          params: {
-            collection: service.collection,
-            id: service.data.id,
-            version: service.data.version,
-            specification: specification.type,
-          },
-          props: {
-            schema: fs.readFileSync(path.join(path.dirname(service.filePath ?? ''), specification.path ?? ''), 'utf8'),
-          },
-        })),
-      ];
-    },
-    [] as { params: { collection: string; id: string; version: string; specification: string }; props: { schema: string } }[]
-  );
-}
-
-export const GET: APIRoute = async ({ props }) => {
-  if (!isEventCatalogScaleEnabled()) {
-    return new Response(
-      JSON.stringify({
-        error: 'feature_not_available_on_server',
-        message: 'Schema API is not enabled for this deployment and supported in EventCatalog Scale.',
-      }),
-      {
-        status: 501,
-        headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' },
-      }
-    );
-  }
-  return new Response(props.schema, {
-    headers: { 'Content-Type': 'text/plain' },
-  });
-};
diff --git a/eventcatalog/src/pages/architecture/[type]/index.astro b/eventcatalog/src/pages/architecture/[type]/index.astro
deleted file mode 100644
index bed361c36..000000000
--- a/eventcatalog/src/pages/architecture/[type]/index.astro
+++ /dev/null
@@ -1,14 +0,0 @@
----
-import Architecture from '../architecture.astro';
-
-export async function getStaticPaths() {
-  const VALID_TYPES = ['domains', 'services', 'messages'] as const;
-  return VALID_TYPES.map((type) => ({
-    params: { type },
-  }));
-}
-
-const { type } = Astro.params;
----
-
-<Architecture type={type} />
diff --git a/eventcatalog/src/pages/architecture/architecture.astro b/eventcatalog/src/pages/architecture/architecture.astro
deleted file mode 100644
index 3eef231d3..000000000
--- a/eventcatalog/src/pages/architecture/architecture.astro
+++ /dev/null
@@ -1,110 +0,0 @@
----
-import { getDomains, getMessagesForDomain } from '@utils/collections/domains';
-import { getServices } from '@utils/collections/services';
-import { getContainers } from '@utils/collections/containers';
-import { getMessages } from '@utils/messages';
-import type { ExtendedDomain } from '@components/Grids/DomainGrid';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import DomainGrid from '@components/Grids/DomainGrid';
-import ServiceGrid from '@components/Grids/ServiceGrid';
-import MessageGrid from '@components/Grids/MessageGrid';
-import { removeContentFromCollection } from '@utils/collections/util';
-
-import type { CollectionEntry } from 'astro:content';
-import type { CollectionMessageTypes } from '@types';
-
-import { isVisualiserEnabled } from '@utils/feature';
-
-import { ClientRouter, fade } from 'astro:transitions';
-// Define valid types and their corresponding data fetchers
-const VALID_TYPES = ['domains', 'services', 'messages'] as const;
-type ValidType = (typeof VALID_TYPES)[number];
-
-interface Service extends CollectionEntry<'services'> {
-  sends: CollectionEntry<'events' | 'commands' | 'queries'>[];
-  receives: CollectionEntry<'events' | 'commands' | 'queries'>[];
-}
-
-const { type, embeded = false } = Astro.props as { type: ValidType; embeded: boolean };
-
-// Get data based on type
-let items: Service[] | CollectionEntry<'commands'>[] | CollectionEntry<CollectionMessageTypes>[] = [];
-let domains: ExtendedDomain[] = [];
-let containers: CollectionEntry<'containers'>[] = [];
-
-const getDomainsForArchitecturePages = async () => {
-  const domains = await getDomains({ getAllVersions: false });
-
-  // Get messages for each domain
-  return Promise.all(
-    domains.map(async (domain) => {
-      const messages = await getMessagesForDomain(domain);
-      // @ts-ignore we have to remove markdown information, as it's all send to the astro components. This reduced the page size.
-      return {
-        ...domain,
-        sends: messages.sends.map((s) => ({ ...s, body: undefined, catalog: undefined })),
-        receives: messages.receives.map((r) => ({ ...r, body: undefined, catalog: undefined })),
-        catalog: undefined,
-        body: undefined,
-      } as ExtendedDomain;
-    })
-  );
-};
-
-if (type === 'domains' || type === 'services') {
-  domains = await getDomainsForArchitecturePages();
-}
-
-if (type === 'services') {
-  const services = await getServices({ getAllVersions: false });
-  let filteredServices = services.map((s) => {
-    // @ts-ignore we have to remove markdown information, as it's all send to the astro components. This reduced the page size.
-    return {
-      ...s,
-      sends: (s.data.sends || []).map((s) => ({ ...s, body: undefined, catalog: undefined })),
-      receives: (s.data.receives || []).map((r) => ({ ...r, body: undefined, catalog: undefined })),
-      catalog: undefined,
-      body: undefined,
-    } as Service;
-  }) as unknown as Service[];
-  items = filteredServices;
-} else if (type === 'messages') {
-  const { events, commands, queries } = await getMessages({ getAllVersions: false, hydrateServices: false });
-  const messages = [...events, ...commands, ...queries];
-  items = removeContentFromCollection(messages) as unknown as CollectionEntry<CollectionMessageTypes>[];
-  containers = await getContainers({ getAllVersions: false });
-}
----
-
-<VerticalSideBarLayout title={'EventCatalog'}>
-  <div class="bg-white min-h-screen">
-    <div class="max-w-[90em] mx-auto">
-      <div class="px-6 py-6" transition:animate={fade({ duration: '0.4s' })}>
-        {type === 'domains' && <DomainGrid domains={domains} embeded={embeded} client:load />}
-        {
-          type === 'services' && (
-            <ServiceGrid
-              domains={domains}
-              services={items as unknown as Service[]}
-              embeded={embeded}
-              isVisualiserEnabled={isVisualiserEnabled()}
-              client:load
-            />
-          )
-        }
-        {
-          type === 'messages' && (
-            <MessageGrid
-              messages={items as CollectionEntry<CollectionMessageTypes>[]}
-              embeded={embeded}
-              containers={containers}
-              isVisualiserEnabled={isVisualiserEnabled()}
-              client:load
-            />
-          )
-        }
-      </div>
-    </div>
-    <ClientRouter />
-  </div>
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/architecture/docs/[type]/index.astro b/eventcatalog/src/pages/architecture/docs/[type]/index.astro
deleted file mode 100644
index f71565e2d..000000000
--- a/eventcatalog/src/pages/architecture/docs/[type]/index.astro
+++ /dev/null
@@ -1,14 +0,0 @@
----
-import Architecture from '../../architecture.astro';
-
-export async function getStaticPaths() {
-  const VALID_TYPES = ['domains', 'services', 'messages'] as const;
-  return VALID_TYPES.map((type) => ({
-    params: { type },
-  }));
-}
-
-const { type } = Astro.params;
----
-
-<Architecture type={type} embeded={true} />
diff --git a/eventcatalog/src/pages/auth/login.astro b/eventcatalog/src/pages/auth/login.astro
deleted file mode 100644
index fa1745c66..000000000
--- a/eventcatalog/src/pages/auth/login.astro
+++ /dev/null
@@ -1,280 +0,0 @@
----
-import config from '@config';
-const { title, logo } = config;
-import { join } from 'node:path';
-import { isAuthEnabled, isSSR } from '@utils/feature';
-
-const catalogDirectory = process.env.PROJECT_DIR || process.cwd();
-
-let hasAuthConfigurationFile = false;
-let providers: string[] = [];
-
-try {
-  const authConfig = await import(/* @vite-ignore */ join(catalogDirectory, 'eventcatalog.auth.js'));
-  providers = Object.keys(authConfig.default.providers);
-  hasAuthConfigurationFile = true;
-} catch (error) {
-  hasAuthConfigurationFile = false;
-}
-
-// Check if we should show login (auth file exists, SSR enabled, auth enabled, and has providers)
-const shouldShowLogin = hasAuthConfigurationFile && isSSR() && isAuthEnabled() && providers.length > 0;
-
-// Check if configuration exists but no providers are set up
-const hasConfigButNoProviders = hasAuthConfigurationFile && isSSR() && isAuthEnabled() && providers.length === 0;
-
-// If we are not in SSR mode, redirect to home
-if (!isSSR() || !isAuthEnabled()) {
-  return Astro.redirect('/');
-}
-
-// If we are in SSR mode, check if the user is already logged in
-if (isSSR() && isAuthEnabled()) {
-  const { getSession } = await import(/* @vite-ignore */ 'auth-astro/server');
-  const session = await getSession(Astro.request);
-  if (session) {
-    return Astro.redirect('/');
-  }
-}
-
-// Provider configurations
-const providerConfig = {
-  github: {
-    name: 'GitHub',
-    icon: `<svg class="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
-      <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"></path>
-    </svg>`,
-  },
-  google: {
-    name: 'Google',
-    icon: `<svg class="w-5 h-5" viewBox="0 0 24 24">
-      <path fill="#4285F4" d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"/>
-      <path fill="#34A853" d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"/>
-      <path fill="#FBBC05" d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"/>
-      <path fill="#EA4335" d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"/>
-    </svg>`,
-  },
-  okta: {
-    name: 'Okta',
-    icon: `<svg class="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
-      <path d="M12 2C6.477 2 2 6.477 2 12s4.477 10 10 10 10-4.477 10-10S17.523 2 12 2zm0 18c-4.418 0-8-3.582-8-8s3.582-8 8-8 8 3.582 8 8-3.582 8-8 8zm-1-13h2v6h-2V7zm0 8h2v2h-2v-2z"></path>
-    </svg>`,
-  },
-  auth0: {
-    name: 'Auth0',
-    icon: `<svg class="w-5 h-5" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" fill="none"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"><path fill="#000000" d="M12.549 1h-4.55l1.407 4.38h4.548l-3.68 2.61 1.406 4.405c2.37-1.725 3.143-4.336 2.274-7.016L12.55 1zM2.045 5.38h4.55L8 1H3.45L2.045 5.38c-.868 2.68-.094 5.29 2.275 7.015L5.725 7.99l-3.68-2.612zm2.275 7.015L8 15l3.68-2.605L8 9.745l-3.68 2.65z"></path></g></svg>`,
-  },
-  entra: {
-    name: 'Microsoft',
-    icon: `<svg class="w-5 h-5" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" fill="none"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"><path fill="#F35325" d="M1 1h6.5v6.5H1V1z"></path><path fill="#81BC06" d="M8.5 1H15v6.5H8.5V1z"></path><path fill="#05A6F0" d="M1 8.5h6.5V15H1V8.5z"></path><path fill="#FFBA08" d="M8.5 8.5H15V15H8.5V8.5z"></path></g></svg>`,
-  },
-};
----
-
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-    <meta name="generator" content={Astro.generator} />
-    <title>Sign In | {title}</title>
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
-    <style>
-      body {
-        font-family: 'Inter', sans-serif;
-        background: linear-gradient(135deg, #f8fafc 0%, #f1f5f9 100%);
-      }
-    </style>
-  </head>
-  <body class="min-h-screen">
-    <div class="flex min-h-screen flex-col items-center justify-center py-12 px-4 sm:px-6 lg:px-8">
-      <!-- Logo at the top -->
-      <div class="mb-8">
-        {
-          logo && (
-            <div class="flex flex-col items-center space-y-4">
-              <img alt={logo.alt} src={logo.src} class="w-12 h-12" />
-              <h1 class="text-2xl font-bold text-gray-900">{title}</h1>
-            </div>
-          )
-        }
-      </div>
-
-      {
-        shouldShowLogin ? (
-          <div class="w-full max-w-md">
-            <div class="bg-white rounded-xl shadow-lg border border-gray-100 p-8 space-y-6">
-              <div class="text-center">
-                <h2 class="text-2xl font-bold text-gray-900">Sign in to your account</h2>
-              </div>
-
-              <div class="space-y-4">
-                {providers.map((provider) => {
-                  const config = providerConfig[provider as keyof typeof providerConfig];
-                  if (!config) return null;
-
-                  return (
-                    <button
-                      data-provider={provider}
-                      class="provider-login-btn flex w-full items-center justify-center rounded-lg border border-gray-200 bg-white px-4 py-3 text-sm font-medium text-gray-700 shadow-sm hover:bg-purple-50 hover:border-purple-200 focus:outline-none focus:ring-2 focus:ring-purple-500 focus:ring-offset-2 transition-all duration-200"
-                    >
-                      <span class="mr-3" set:html={config.icon} />
-                      Sign in with {config.name}
-                    </button>
-                  );
-                })}
-              </div>
-            </div>
-
-            <div class="mt-6 text-center">
-              <p class="text-gray-600 text-sm">
-                Missing integration?
-                <a
-                  href="https://github.com/event-catalog/eventcatalog/issues"
-                  target="_blank"
-                  class="text-purple-600 hover:text-purple-700 underline font-medium"
-                >
-                  Let us know
-                </a>
-              </p>
-            </div>
-          </div>
-        ) : hasConfigButNoProviders ? (
-          <div class="w-full max-w-2xl">
-            <div class="bg-white rounded-xl shadow-lg border border-gray-100 p-8 space-y-6">
-              <div class="text-center">
-                <h2 class="text-2xl font-bold text-gray-900">No Authentication Providers Configured</h2>
-                <p class="mt-4 text-gray-600">
-                  Authentication is enabled but no providers are configured in your auth configuration file.
-                </p>
-              </div>
-
-              <div class="bg-purple-50 border border-purple-100 rounded-lg p-6 space-y-4">
-                <h3 class="text-lg font-semibold text-gray-900">To add authentication providers:</h3>
-                <ol class="list-decimal list-inside space-y-2 text-gray-700">
-                  <li>
-                    Update your{' '}
-                    <code class="bg-purple-100 text-purple-800 px-2 py-1 rounded text-sm font-mono">eventcatalog.auth.js</code>{' '}
-                    file to include at least one provider (GitHub, Google, Okta, etc.)
-                  </li>
-                  <li>Configure the provider with the necessary credentials and settings</li>
-                  <li>Restart your EventCatalog server to apply the changes</li>
-                </ol>
-              </div>
-
-              <div class="text-center">
-                <a
-                  href="#"
-                  class="inline-flex items-center px-6 py-3 border border-transparent text-sm font-medium rounded-lg text-white bg-purple-600 hover:bg-purple-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-purple-500 transition-colors duration-200"
-                >
-                  Read Authentication Documentation
-                </a>
-              </div>
-            </div>
-
-            <div class="mt-6 text-center">
-              <p class="text-gray-600 text-sm">
-                Missing integration?
-                <a
-                  href="https://github.com/event-catalog/eventcatalog/issues"
-                  target="_blank"
-                  class="text-purple-600 hover:text-purple-700 underline font-medium"
-                >
-                  Let us know
-                </a>
-              </p>
-            </div>
-          </div>
-        ) : (
-          <div class="w-full max-w-2xl">
-            <div class="bg-white rounded-xl shadow-lg border border-gray-100 p-8 space-y-6">
-              <div class="text-center">
-                <h2 class="text-2xl font-bold text-gray-900">Authentication Not Configured</h2>
-                <p class="mt-4 text-gray-600">
-                  {!hasAuthConfigurationFile
-                    ? 'No authentication configuration file found.'
-                    : 'Authentication is not properly enabled.'}
-                </p>
-              </div>
-
-              <div class="bg-purple-50 border border-purple-100 rounded-lg p-6 space-y-4">
-                <h3 class="text-lg font-semibold text-gray-900">To enable authentication:</h3>
-                <ol class="list-decimal list-inside space-y-2 text-gray-700">
-                  {!hasAuthConfigurationFile && (
-                    <li>
-                      Create an{' '}
-                      <code class="bg-purple-100 text-purple-800 px-2 py-1 rounded text-sm font-mono">eventcatalog.auth.js</code>{' '}
-                      configuration file in your project root
-                    </li>
-                  )}
-                  {!isSSR() && (
-                    <li>
-                      Enable SSR (Server-Side Rendering) in your{' '}
-                      <code class="bg-purple-100 text-purple-800 px-2 py-1 rounded text-sm font-mono">
-                        eventcatalog.config.js
-                      </code>{' '}
-                      file by setting{' '}
-                      <code class="bg-purple-100 text-purple-800 px-2 py-1 rounded text-sm font-mono">output: 'server'</code>
-                    </li>
-                  )}
-                  {!isAuthEnabled() && (
-                    <li>
-                      Enable authentication in your{' '}
-                      <code class="bg-purple-100 text-purple-800 px-2 py-1 rounded text-sm font-mono">
-                        eventcatalog.config.js
-                      </code>{' '}
-                      file by setting{' '}
-                      <code class="bg-purple-100 text-purple-800 px-2 py-1 rounded text-sm font-mono">
-                        auth: {`{ enabled: true }`}
-                      </code>
-                    </li>
-                  )}
-                </ol>
-              </div>
-
-              <div class="text-center">
-                <a
-                  href="#"
-                  class="inline-flex items-center px-6 py-3 border border-transparent text-sm font-medium rounded-lg text-white bg-purple-600 hover:bg-purple-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-purple-500 transition-colors duration-200"
-                >
-                  Read Authentication Documentation
-                </a>
-              </div>
-            </div>
-
-            <div class="mt-6 text-center">
-              <p class="text-gray-600 text-sm">
-                Missing integration?
-                <a
-                  href="https://github.com/event-catalog/eventcatalog/issues"
-                  target="_blank"
-                  class="text-purple-600 hover:text-purple-700 underline font-medium"
-                >
-                  Let us know
-                </a>
-              </p>
-            </div>
-          </div>
-        )
-      }
-    </div>
-  </body>
-</html>
-
-<script>
-  import { signIn } from 'auth-astro/client';
-
-  // Add event listeners to all provider login buttons
-  const providerButtons = document.querySelectorAll('.provider-login-btn');
-
-  providerButtons.forEach((button) => {
-    const provider = button.getAttribute('data-provider');
-    if (provider) {
-      let providerId = provider === 'entra' ? 'microsoft-entra-id' : provider;
-      button.addEventListener('click', () => signIn(providerId));
-    }
-  });
-</script>
diff --git a/eventcatalog/src/pages/chat/feature.astro b/eventcatalog/src/pages/chat/feature.astro
deleted file mode 100644
index cf8a0d167..000000000
--- a/eventcatalog/src/pages/chat/feature.astro
+++ /dev/null
@@ -1,179 +0,0 @@
----
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { isEventCatalogChatEnabled as hasEventCatlaogChatLicense, isSSR } from '@utils/feature';
-import { BotMessageSquare } from 'lucide-react';
-const hasChatLicense = hasEventCatlaogChatLicense();
-
-if (hasChatLicense) {
-  return Astro.redirect('/chat');
-}
----
-
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-    <meta name="generator" content={Astro.generator} />
-    <title>EventCatalog chat?</title>
-  </head>
-  <body>
-    <VerticalSideBarLayout title="AI Chat">
-      <div class="min-h-[calc(100vh-60px)] bg-white">
-        <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-16">
-          {/* Hero Section */}
-          <div class="grid grid-cols-1 lg:grid-cols-2 gap-12 items-center mb-16">
-            <div>
-              <div class="inline-flex items-center px-4 py-2 rounded-full bg-purple-100 text-purple-700 font-medium text-sm mb-6">
-                <BotMessageSquare className="w-4 h-4 mr-2" />
-                EventCatalog: Agent
-              </div>
-              <h1 class="text-4xl font-bold text-gray-900 tracking-tight mb-4">Ask. Understand. Ship faster.</h1>
-              <p class="text-xl text-gray-600 mb-8">
-                Get answers about your architecture — instantly. Connect to your own AI models and data.
-              </p>
-              <div class="flex flex-col sm:flex-row gap-4 mb-2">
-                <a
-                  href="https://www.eventcatalog.dev/docs/development/guides/eventcatlaog-chat/what-is-eventcatalog-chat"
-                  target="_blank"
-                  class="inline-flex items-center juNot ready for AI chat? You castify-center px-6 py-3 border border-transparent text-base font-medium rounded-lg text-white bg-purple-600 hover:bg-purple-700 transition-colors duration-150"
-                >
-                  Get Started
-                  <svg class="ml-2 w-4 h-4" viewBox="0 0 20 20" fill="currentColor">
-                    <path
-                      fill-rule="evenodd"
-                      d="M10.293 3.293a1 1 0 011.414 0l6 6a1 1 0 010 1.414l-6 6a1 1 0 01-1.414-1.414L14.586 11H3a1 1 0 110-2h11.586l-4.293-4.293a1 1 0 010-1.414z"
-                      clip-rule="evenodd"></path>
-                  </svg>
-                </a>
-                <a
-                  href="https://www.eventcatalog.cloud"
-                  target="_blank"
-                  class="inline-flex items-center justify-center px-6 py-3 border border-gray-300 text-base font-medium rounded-lg text-gray-700 bg-white hover:bg-gray-50 transition-colors duration-150"
-                >
-                  Try for free
-                </a>
-              </div>
-
-              <p class="text-sm text-gray-500 italic mb-6">Available with EventCatalog Starter or Scale plans</p>
-
-              {
-                !isSSR() && (
-                  <p class="text-sm text-gray-500 my-4 bg-yellow-50 p-4 rounded-lg">
-                    <span class="font-bold">This feature is only available on server side.</span> You can switch to server side by
-                    setting the <code class="font-mono bg-gray-100 p-0.5 rounded">output</code> property to{' '}
-                    <code class="font-mono bg-gray-100 p-0.5 rounded">server</code> in your{' '}
-                    <code class="font-mono bg-gray-100 p-0.5 rounded">eventcatalog.config.js</code> file.
-                  </p>
-                )
-              }
-            </div>
-
-            <div class="relative">
-              <div class="absolute -inset-4">
-                <div
-                  class="w-full h-full max-w-full mx-auto opacity-30 blur-lg filter"
-                  style="background: linear-gradient(90deg, #C084FC 0%, #818CF8 100%);"
-                >
-                </div>
-              </div>
-              <div class="relative">
-                <div class="bg-white rounded-xl shadow-xl border border-gray-200 overflow-hidden">
-                  <div class="bg-gray-50 px-4 py-3 border-b border-gray-200">
-                    <div class="flex items-center space-x-2">
-                      <div class="w-3 h-3 bg-red-400 rounded-full"></div>
-                      <div class="w-3 h-3 bg-yellow-400 rounded-full"></div>
-                      <div class="w-3 h-3 bg-green-400 rounded-full"></div>
-                    </div>
-                  </div>
-                  <div class="p-4 space-y-4">
-                    <div class="flex justify-end">
-                      <div class="bg-purple-600 text-white rounded-2xl rounded-tr-sm px-4 py-2 max-w-md text-sm">
-                        What services publish order.created?
-                      </div>
-                    </div>
-
-                    <div class="flex justify-start">
-                      <div class="bg-gray-50 rounded-2xl rounded-tl-sm px-4 py-3 max-w-md shadow-sm">
-                        <p class="text-gray-700 text-sm">
-                          The <span class="font-semibold">Order Service</span> publishes the order.created event.
-                        </p>
-                        <p class="text-gray-700 text-sm mt-2 mb-1">This event is consumed by:</p>
-                        <ul class="space-y-1 text-gray-600 text-sm">
-                          <li>• Payment Service - Initiates payment processing</li>
-                          <li>• Inventory Service - Updates stock levels</li>
-                          <li>• Notification Service - Sends order confirmations</li>
-                        </ul>
-                      </div>
-                    </div>
-                  </div>
-                </div>
-              </div>
-            </div>
-          </div>
-
-          {/* Features Section */}
-          <div class="grid grid-cols-1 md:grid-cols-3 gap-8">
-            <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-              <div class="w-12 h-12 bg-purple-100 rounded-lg flex items-center justify-center mb-4">
-                <svg class="w-6 h-6 text-purple-600" viewBox="0 0 24 24" fill="currentColor">
-                  <path
-                    d="M13 7h-2v4H7v2h4v4h2v-4h4v-2h-4V7zm-1-5C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8z"
-                  ></path>
-                </svg>
-              </div>
-              <h3 class="text-lg font-semibold text-gray-900 mb-2">Direct Answers</h3>
-              <p class="text-gray-600">
-                Ask questions about your catalog and get direct answers, using your own models and API keys.
-              </p>
-            </div>
-
-            <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-              <div class="w-12 h-12 bg-purple-100 rounded-lg flex items-center justify-center mb-4">
-                <svg class="w-6 h-6 text-purple-600" viewBox="0 0 24 24" fill="currentColor">
-                  <path
-                    d="M9 21c0 .55.45 1 1 1h4c.55 0 1-.45 1-1v-1H9v1zm3-19C8.14 2 5 5.14 5 9c0 2.38 1.19 4.47 3 5.74V17c0 .55.45 1 1 1h6c.55 0 1-.45 1-1v-2.26c1.81-1.27 3-3.36 3-5.74 0-3.86-3.14-7-7-7zm2.85 11.1l-.85.6V16h-4v-2.3l-.85-.6C7.8 12.16 7 10.63 7 9c0-2.76 2.24-5 5-5s5 2.24 5 5c0 1.63-.8 3.16-2.15 4.1z"
-                  ></path>
-                </svg>
-              </div>
-              <h3 class="text-lg font-semibold text-gray-900 mb-2">Smart Insights</h3>
-              <p class="text-gray-600">Get intelligent suggestions and insights about your architecture automatically.</p>
-            </div>
-
-            <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-              <div class="w-12 h-12 bg-purple-100 rounded-lg flex items-center justify-center mb-4">
-                <svg class="w-6 h-6 text-purple-600" viewBox="0 0 24 24" fill="currentColor">
-                  <path
-                    d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-1 17.93c-3.95-.49-7-3.85-7-7.93 0-.62.08-1.21.21-1.79L9 15v1c0 1.1.9 2 2 2v1.93zm6.9-2.54c-.26-.81-1-1.39-1.9-1.39h-1v-3c0-.55-.45-1-1-1H8v-2h2c.55 0 1-.45 1-1V7h2c1.1 0 2-.9 2-2v-.41c2.93 1.19 5 4.06 5 7.41 0 2.08-.8 3.97-2.1 5.39z"
-                  ></path>
-                </svg>
-              </div>
-              <h3 class="text-lg font-semibold text-gray-900 mb-2">Privacy First</h3>
-              <p class="text-gray-600">
-                Runs on your own infrastructure, and your own models. Provide your own API keys to get started.
-              </p>
-            </div>
-          </div>
-
-          {/* Bottom Link */}
-          <div class="mt-16 text-center">
-            <a
-              href="https://www.eventcatalog.dev/docs/development/guides/customize-sidebars/application-sidebar"
-              target="_blank"
-              class="text-sm text-gray-400 hover:text-gray-500 transition-colors duration-150"
-            >
-              Not ready for AI chat? You can hide this feature in settings
-            </a>
-          </div>
-        </div>
-      </div>
-    </VerticalSideBarLayout>
-  </body>
-</html>
-
-<style>
-  .scroll-smooth {
-    scroll-behavior: smooth;
-  }
-</style>
diff --git a/eventcatalog/src/pages/chat/index.astro b/eventcatalog/src/pages/chat/index.astro
deleted file mode 100644
index d8b049a98..000000000
--- a/eventcatalog/src/pages/chat/index.astro
+++ /dev/null
@@ -1,10 +0,0 @@
----
-import ChatPage from '@enterprise/eventcatalog-chat/pages/chat/index.astro';
-import { isEventCatalogChatEnabled } from '@utils/feature';
-import { buildUrl } from '@utils/url-builder';
-if (!isEventCatalogChatEnabled()) {
-  return Astro.redirect(buildUrl('/chat/feature'));
-}
----
-
-<ChatPage />
diff --git a/eventcatalog/src/pages/directory/[type]/_index.data.ts b/eventcatalog/src/pages/directory/[type]/_index.data.ts
deleted file mode 100644
index d75e8a0c7..000000000
--- a/eventcatalog/src/pages/directory/[type]/_index.data.ts
+++ /dev/null
@@ -1,63 +0,0 @@
-// pages/directory/[type]/index.page.ts
-import { isSSR } from '@utils/feature';
-import { HybridPage } from '@utils/page-loaders/hybrid-page';
-
-export class Page extends HybridPage {
-  static get prerender(): boolean {
-    return !isSSR();
-  }
-
-  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
-    const { getUsers } = await import('@utils/users');
-    const { getTeams } = await import('@utils/teams');
-
-    const loaders = {
-      users: getUsers,
-      teams: getTeams,
-    };
-
-    const itemTypes = ['users', 'teams'] as const;
-    const allItems = await Promise.all(itemTypes.map((type) => loaders[type]()));
-
-    return allItems.flatMap((items, index) => ({
-      params: {
-        type: itemTypes[index],
-      },
-      props: {
-        data: items,
-        type: itemTypes[index],
-      },
-    }));
-  }
-
-  protected static async fetchData(params: any) {
-    const { type } = params;
-
-    if (!type) {
-      return null;
-    }
-
-    const { getUsers } = await import('@utils/users');
-    const { getTeams } = await import('@utils/teams');
-
-    const loaders = {
-      users: getUsers,
-      teams: getTeams,
-    };
-
-    // Get all items of the specified type
-    const items = await loaders[type as keyof typeof loaders]();
-
-    return {
-      type,
-      data: items,
-    };
-  }
-
-  protected static createNotFoundResponse(): Response {
-    return new Response(null, {
-      status: 404,
-      statusText: 'Directory type not found',
-    });
-  }
-}
diff --git a/eventcatalog/src/pages/directory/[type]/index.astro b/eventcatalog/src/pages/directory/[type]/index.astro
deleted file mode 100644
index a25253bf8..000000000
--- a/eventcatalog/src/pages/directory/[type]/index.astro
+++ /dev/null
@@ -1,55 +0,0 @@
----
-import type { CollectionEntry } from 'astro:content';
-
-import DirectoryLayout, { type Props as DirectoryLayoutProps } from '@layouts/DirectoryLayout.astro';
-import { Page } from './_index.data';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-const { type, data } = await Page.getData(Astro);
-
-function mapToItem(i: any) {
-  return {
-    collection: i.collection,
-    data: {
-      id: i.data.id,
-      name: i.data.name,
-      version: i.data.version,
-    },
-  };
-}
----
-
-<DirectoryLayout
-  title={`${type} (${data.length})`}
-  subtitle={`Find, filter and search for any ${type} in your system.`}
-  data={data.map(
-    (d: CollectionEntry<'users' | 'teams'>) =>
-      ({
-        collection: d.collection,
-        data: {
-          // @ts-ignore
-          id: d.data.id,
-          name: d.data.name,
-          // @ts-ignore
-          role: d.data?.role,
-          // @ts-ignore
-          avatarUrl: d.data?.avatarUrl,
-          // @ts-ignore
-          associatedTeams: d.data?.associatedTeams?.map(mapToItem) ?? [],
-          // @ts-ignore
-          ownedCommands: d.data?.ownedCommands?.map(mapToItem) ?? [],
-          // @ts-ignore
-          ownedQueries: d.data?.ownedQueries?.map(mapToItem) ?? [],
-          // @ts-ignore
-          ownedEvents: d.data?.ownedEvents?.map(mapToItem) ?? [],
-          // @ts-ignore
-          ownedServices: d.data?.ownedServices?.map(mapToItem) ?? [],
-          // @ts-ignore
-          members: d.data?.members,
-        },
-      }) as DirectoryLayoutProps<typeof type>['data'][0]
-  )}
-  type={type}
-/>
diff --git a/eventcatalog/src/pages/discover/[type]/_index.data.ts b/eventcatalog/src/pages/discover/[type]/_index.data.ts
deleted file mode 100644
index a37659f1c..000000000
--- a/eventcatalog/src/pages/discover/[type]/_index.data.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-// pages/discover/[type]/index.page.ts
-import { isSSR } from '@utils/feature';
-import { HybridPage } from '@utils/page-loaders/hybrid-page';
-import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
-
-export class Page extends HybridPage {
-  static get prerender(): boolean {
-    return !isSSR();
-  }
-
-  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
-    const { getFlows } = await import('@utils/collections/flows');
-
-    const loaders = {
-      ...pageDataLoader,
-      flows: getFlows,
-    };
-
-    const itemTypes = ['events', 'commands', 'queries', 'services', 'domains', 'flows', 'containers'] as const;
-    const allItems = await Promise.all(itemTypes.map((type) => loaders[type]()));
-
-    return allItems.flatMap((items, index) => ({
-      params: {
-        type: itemTypes[index],
-      },
-      props: {
-        data: items,
-        type: itemTypes[index],
-      },
-    }));
-  }
-
-  protected static async fetchData(params: any) {
-    const { type } = params;
-
-    if (!type) {
-      return null;
-    }
-
-    const { getFlows } = await import('@utils/collections/flows');
-
-    const loaders = {
-      ...pageDataLoader,
-      flows: getFlows,
-    };
-
-    // @ts-ignore
-    const items = await loaders[type]();
-
-    return {
-      type,
-      data: items,
-    };
-  }
-
-  protected static createNotFoundResponse(): Response {
-    return new Response(null, {
-      status: 404,
-      statusText: 'Collection type not found',
-    });
-  }
-}
diff --git a/eventcatalog/src/pages/discover/[type]/index.astro b/eventcatalog/src/pages/discover/[type]/index.astro
deleted file mode 100644
index 120235973..000000000
--- a/eventcatalog/src/pages/discover/[type]/index.astro
+++ /dev/null
@@ -1,63 +0,0 @@
----
-import type { CollectionEntry } from 'astro:content';
-import type { CollectionTypes } from '@types';
-import DiscoverLayout, { type Props as DiscoverLayoutProps } from '@layouts/DiscoverLayout.astro';
-import { Page } from './_index.data';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-const { type, data } = await Page.getData(Astro);
-
-let title = `${type} (${data.length})`;
-
-if (type === 'containers') {
-  title = `Data (${data.length})`;
-}
-
-function mapToItem(i: any) {
-  return {
-    collection: i.collection,
-    data: {
-      id: i.data.id,
-      name: i.data.name,
-      version: i.data.version,
-    },
-  };
-}
----
-
-<DiscoverLayout
-  title={title}
-  subtitle={`Find, filter and search for any ${type} in your system.`}
-  data={data.map(
-    (d: CollectionEntry<CollectionTypes>) =>
-      ({
-        collection: d.collection,
-        data: {
-          id: d.data.id,
-          name: d.data.name,
-          summary: d.data?.summary,
-          version: d.data.version,
-          latestVersion: d.data?.latestVersion,
-          draft: d.data?.draft,
-          badges: d.data?.badges,
-          // @ts-ignore
-          consumers: d.data?.consumers?.map(mapToItem) ?? [],
-          // @ts-ignore
-          producers: d.data?.producers?.map(mapToItem) ?? [],
-          // @ts-ignore
-          receives: d.data?.receives?.map(mapToItem) ?? [],
-          // @ts-ignore
-          sends: d.data?.sends?.map(mapToItem) ?? [],
-          // @ts-ignore
-          services: d.data?.services?.map(mapToItem) ?? [],
-          // @ts-ignore
-          servicesThatWriteToContainer: d.data?.servicesThatWriteToContainer?.map(mapToItem) ?? [],
-          // @ts-ignore
-          servicesThatReadFromContainer: d.data?.servicesThatReadFromContainer?.map(mapToItem) ?? [],
-        },
-      }) as DiscoverLayoutProps<typeof type>['data'][0]
-  )}
-  type={type}
-/>
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version].md.ts b/eventcatalog/src/pages/docs/[type]/[id]/[version].md.ts
deleted file mode 100644
index 43bb00f1c..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/[version].md.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-// This file exposes the markdown for EventCatalog in the Url
-// For example http://localhost:3000/docs/events/OrderAmended/0.0.1 loads the Page and http://localhost:3000/docs/events/OrderAmended/0.0.1.md loads the markdown
-// This is used for the LLMs to load the markdown for the given item (llms.txt);
-
-import type { APIRoute } from 'astro';
-import { getCollection } from 'astro:content';
-import { getEntities } from '@utils/entities';
-import config from '@config';
-import fs from 'fs';
-
-const events = await getCollection('events');
-const commands = await getCollection('commands');
-const queries = await getCollection('queries');
-const services = await getCollection('services');
-const domains = await getCollection('domains');
-const flows = await getCollection('flows');
-const channels = await getCollection('channels');
-const containers = await getCollection('containers');
-const entities = await getEntities();
-export async function getStaticPaths() {
-  // Just return empty array if LLMs are not enabled
-  if (!config.llmsTxt?.enabled) {
-    return [];
-  }
-
-  const collections = {
-    events,
-    commands,
-    queries,
-    services,
-    domains,
-    flows,
-    channels,
-    containers,
-    entities,
-  };
-  const paths = Object.keys(collections).map((type) => {
-    return collections[type as keyof typeof collections].map((item: { data: { id: string; version: string } }) => ({
-      params: { type, id: item.data.id, version: item.data.version },
-      props: { content: item },
-    }));
-  });
-
-  return paths.flat();
-}
-
-export const GET: APIRoute = async ({ params, props }) => {
-  // Just return empty array if LLMs are not enabled
-  if (!config.llmsTxt?.enabled) {
-    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
-  }
-
-  if (props?.content?.filePath) {
-    const file = fs.readFileSync(props.content.filePath, 'utf8');
-    return new Response(file, { status: 200 });
-  }
-
-  return new Response('Not found', { status: 404 });
-};
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version].mdx.ts b/eventcatalog/src/pages/docs/[type]/[id]/[version].mdx.ts
deleted file mode 100644
index c4f12d1a2..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/[version].mdx.ts
+++ /dev/null
@@ -1,76 +0,0 @@
-// This file exposes the markdown for EventCatalog in the Url
-// For example http://localhost:3000/docs/events/OrderAmended/0.0.1 loads the Page and http://localhost:3000/docs/events/OrderAmended/0.0.1.md loads the markdown
-// This is used for the LLMs to load the markdown for the given item (llms.txt);
-
-import type { APIRoute } from 'astro';
-import { getCollection } from 'astro:content';
-import config from '@config';
-import fs from 'fs';
-import { addSchemaToMarkdown } from '@utils/llms';
-import { isLLMSTxtEnabled, isSSR } from '@utils/feature';
-const events = await getCollection('events');
-const commands = await getCollection('commands');
-const queries = await getCollection('queries');
-const services = await getCollection('services');
-const domains = await getCollection('domains');
-const flows = await getCollection('flows');
-const channels = await getCollection('channels');
-const entities = await getCollection('entities');
-
-import utils from '@eventcatalog/sdk';
-
-export async function getStaticPaths() {
-  // Just return empty array if LLMs are not enabled
-  if (!config.llmsTxt?.enabled) {
-    return [];
-  }
-  const collections = {
-    events,
-    commands,
-    queries,
-    services,
-    domains,
-    flows,
-    channels,
-    entities,
-  };
-  const paths = Object.keys(collections).map((type) => {
-    return collections[type as keyof typeof collections].map((item: { data: { id: string; version: string } }) => ({
-      params: { type, id: item.data.id, version: item.data.version },
-      props: { content: item },
-    }));
-  });
-
-  return paths.flat();
-}
-
-export const GET: APIRoute = async ({ params, props }) => {
-  // Just return empty array if LLMs are not enabled
-  if (!isLLMSTxtEnabled()) {
-    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
-  }
-
-  if (isSSR()) {
-    const { getResourcePath } = utils(process.env.PROJECT_DIR ?? '');
-    const filePath = await getResourcePath(process.env.PROJECT_DIR ?? '', params.id ?? '', params.version ?? '');
-    if (!filePath) {
-      return new Response('Not found', { status: 404 });
-    }
-    const file = fs.readFileSync(filePath.fullPath, 'utf8');
-    return new Response(file, { status: 200 });
-  } else {
-    if (props?.content?.filePath) {
-      let file = fs.readFileSync(props.content.filePath, 'utf8');
-
-      try {
-        file = addSchemaToMarkdown(props.content, file);
-      } catch (error) {
-        console.log('Warning: Cant find the schema for', props.content.data.id, props.content.data.version);
-      }
-
-      return new Response(file, { status: 200 });
-    }
-  }
-
-  return new Response('Not found', { status: 404 });
-};
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version]/_index.data.ts b/eventcatalog/src/pages/docs/[type]/[id]/[version]/_index.data.ts
deleted file mode 100644
index 9f2eecdd7..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/[version]/_index.data.ts
+++ /dev/null
@@ -1,72 +0,0 @@
-import { isSSR } from '@utils/feature';
-import { HybridPage } from '@utils/page-loaders/hybrid-page';
-import type { PageTypes } from '@types';
-import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
-
-/**
- * Documentation page class for all collection types with versioning
- */
-export class Page extends HybridPage {
-  static async getStaticPaths() {
-    if (isSSR()) {
-      return [];
-    }
-
-    const itemTypes: PageTypes[] = [
-      'events',
-      'commands',
-      'queries',
-      'services',
-      'domains',
-      'flows',
-      'channels',
-      'entities',
-      'containers',
-    ];
-    const allItems = await Promise.all(itemTypes.map((type) => pageDataLoader[type]()));
-
-    return allItems.flatMap((items, index) =>
-      items.map((item) => ({
-        params: {
-          type: itemTypes[index],
-          id: item.data.id,
-          version: item.data.version,
-        },
-        props: {
-          type: itemTypes[index],
-          ...item,
-        },
-      }))
-    );
-  }
-
-  protected static async fetchData(params: any) {
-    const { type, id, version } = params;
-
-    if (!type || !id || !version) {
-      return null;
-    }
-
-    // Get all items of the specified type
-    const items = await pageDataLoader[type as PageTypes]();
-
-    // Find the specific item by id and version
-    const item = items.find((i) => i.data.id === id && i.data.version === version);
-
-    if (!item) {
-      return null;
-    }
-
-    return {
-      type,
-      ...item,
-    };
-  }
-
-  protected static createNotFoundResponse(): Response {
-    return new Response(null, {
-      status: 404,
-      statusText: 'Documentation not found',
-    });
-  }
-}
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version]/asyncapi/[filename].astro b/eventcatalog/src/pages/docs/[type]/[id]/[version]/asyncapi/[filename].astro
deleted file mode 100644
index ad0c285c7..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/[version]/asyncapi/[filename].astro
+++ /dev/null
@@ -1,89 +0,0 @@
----
-import { createElement } from 'react';
-import { renderToString } from 'react-dom/server';
-import { Parser } from '@asyncapi/parser';
-import { AvroSchemaParser } from '@asyncapi/avro-schema-parser';
-import fs from 'fs';
-
-import '@asyncapi/react-component/styles/default.min.css';
-import js from '@asyncapi/react-component/browser/standalone/without-parser.js?url';
-import { AsyncApiComponentWP, type ConfigInterface } from '@asyncapi/react-component';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import Config from '@utils/eventcatalog-config/catalog';
-import { Page } from './_[filename].data';
-import { getAbsoluteFilePathForAstroFile } from '@utils/files';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-// Get data
-const { collection, data, filePath, filename, path: relativeSpecPath } = await Page.getData(Astro);
-
-const fileName = filename || 'asyncapi.yaml';
-const pathToSpec = getAbsoluteFilePathForAstroFile(filePath, fileName);
-const fileExists = fs.existsSync(pathToSpec);
-const isRemote = relativeSpecPath.includes('https://');
-let content = '';
-
-if (fileExists && !isRemote) {
-  content = fs.readFileSync(pathToSpec, 'utf8');
-}
-
-if (isRemote) {
-  // Fetch the content from the remote path
-  content = await fetch(relativeSpecPath).then((res) => res.text());
-}
-
-// AsyncAPI parser will parser schemas for users, they can turn this off.
-const parseSchemas = Config?.asyncAPI?.renderParsedSchemas ?? true;
-const parsed = await new Parser({ schemaParsers: [AvroSchemaParser()] }).parse(content, { parseSchemas });
-const stringified = parsed.document?.json();
-const config: ConfigInterface = { show: { sidebar: true, errors: true } };
-
-const component = createElement(AsyncApiComponentWP, { schema: { stringified }, config });
-const renderedComponent = renderToString(component);
-
-// Capitalize the first letter of a string
-const pageTitle = `${collection} | ${data.name} | AsyncApi Spec`.replace(/^\w/, (c) => c.toUpperCase());
-
-// Index only the latest version
-const pagefindAttributes =
-  data.version === data.latestVersion
-    ? {
-        'data-pagefind-body': '',
-        'data-pagefind-meta': `title:${pageTitle}`,
-      }
-    : {};
----
-
-<VerticalSideBarLayout title={pageTitle}>
-  <div {...pagefindAttributes}>
-    {
-      // Currently, Pagefind does not index metadata (such as the title),
-      // so we need to ensure it is included as text on the page.
-      // https://github.com/CloudCannon/pagefind/issues/437
-    }
-    <h2 class="hidden">{pageTitle}</h2>
-    <div id="asyncapi" class="md:pr-14" set:html={renderedComponent} />
-  </div>
-</VerticalSideBarLayout>
-
-<script is:inline src={js}></script>
-<script define:vars={{ schema: stringified, config }}>
-  const root = document.getElementById('asyncapi');
-  AsyncApiStandalone.hydrate({ schema, config }, root);
-</script>
-
-<style>
-  #asyncapi {
-    @media screen and (min-width: 1417px) {
-      .sidebar {
-        z-index: 1 !important;
-      }
-    }
-
-    .aui-root .z-10 {
-      z-index: 8;
-    }
-  }
-</style>
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/_index.data.ts b/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/_index.data.ts
deleted file mode 100644
index 6acd48456..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/_index.data.ts
+++ /dev/null
@@ -1,68 +0,0 @@
-import { isSSR } from '@utils/feature';
-import { HybridPage } from '@utils/page-loaders/hybrid-page';
-import type { PageTypes } from '@types';
-
-export class Page extends HybridPage {
-  static get prerender(): boolean {
-    return !isSSR();
-  }
-
-  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
-    if (isSSR()) {
-      return [];
-    }
-
-    const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
-
-    const itemTypes: PageTypes[] = ['events', 'commands', 'queries', 'services', 'domains', 'flows', 'containers'];
-    const allItems = await Promise.all(itemTypes.map((type) => pageDataLoader[type]()));
-
-    return allItems.flatMap((items, index) =>
-      items.map((item) => ({
-        params: {
-          type: itemTypes[index],
-          id: item.data.id,
-          version: item.data.version,
-        },
-        props: {
-          type: itemTypes[index],
-          allCollectionItems: items,
-          ...item,
-        },
-      }))
-    );
-  }
-
-  protected static async fetchData(params: any) {
-    const { type, id, version } = params;
-
-    if (!type || !id || !version) {
-      return null;
-    }
-
-    const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
-
-    // Get all items of the specified type
-    const items = await pageDataLoader[type as PageTypes]();
-
-    // Find the specific item by id and version
-    const item = items.find((i) => i.data.id === id && i.data.version === version);
-
-    if (!item) {
-      return null;
-    }
-
-    return {
-      type,
-      allCollectionItems: items,
-      ...item,
-    };
-  }
-
-  protected static createNotFoundResponse(): Response {
-    return new Response(null, {
-      status: 404,
-      statusText: 'Changelog not found',
-    });
-  }
-}
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/index.astro b/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/index.astro
deleted file mode 100644
index 1f9af4f40..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/index.astro
+++ /dev/null
@@ -1,225 +0,0 @@
----
-import Footer from '@layouts/Footer.astro';
-import { getChangeLogs } from '@utils/collections/changelogs';
-import {
-  RectangleGroupIcon,
-  ServerIcon,
-  BoltIcon,
-  ChatBubbleLeftIcon,
-  MagnifyingGlassIcon,
-  QueueListIcon,
-} from '@heroicons/react/24/outline';
-import { DatabaseIcon } from 'lucide-react';
-import { render, getEntry } from 'astro:content';
-import mdxComponents from '@components/MDX/components';
-import 'diff2html/bundles/css/diff2html.min.css';
-
-import { buildUrl } from '@utils/url-builder';
-import { getPreviousVersion } from '@utils/collections/util';
-import { getDiffsForCurrentAndPreviousVersion } from '@utils/collections/file-diffs';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { ClientRouter } from 'astro:transitions';
-import { isChangelogEnabled } from '@utils/feature';
-
-import { Page } from './_index.data';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-// Get data
-const props = await Page.getData(Astro);
-
-if (!isChangelogEnabled()) {
-  return Astro.redirect('/docs');
-}
-
-let collectionItem = props;
-const logs = await getChangeLogs(props);
-
-const { data } = props;
-const latestVersion = data.latestVersion;
-
-const renderedLogs = logs.map(async (log) => {
-  const logEntry = await getEntry('changelogs', log.id);
-  const { Content } = await render(logEntry as any);
-  return {
-    Content,
-    ...log,
-  };
-});
-
-const logsToRender = await Promise.all(renderedLogs);
-
-const logListPromise = logsToRender.map(async (log, index) => {
-  const currentLogVersion = log.data.version;
-  const previousLogVersion = log.data.version ? getPreviousVersion(log.data.version, data.versions || []) : '';
-  return {
-    id: log.id,
-    url: buildUrl(`/docs/${props.collection}/${props.data.id}`),
-    isLatest: log.data.version === latestVersion,
-    version: log.data.version,
-    createdAt: log.data.createdAt,
-    badges: log.data.badges || [],
-    Content: log.Content,
-    diffs:
-      currentLogVersion && previousLogVersion
-        ? await getDiffsForCurrentAndPreviousVersion(
-            currentLogVersion,
-            previousLogVersion,
-            collectionItem.data.id,
-            props.allCollectionItems
-          )
-        : [],
-  };
-});
-
-const logList = await Promise.all(logListPromise);
-
-const getBadge = () => {
-  if (props.collection === 'services') {
-    return { backgroundColor: 'pink', textColor: 'pink', content: 'Service', icon: ServerIcon, class: 'text-pink-400' };
-  }
-  if (props.collection === 'events') {
-    return { backgroundColor: 'orange', textColor: 'orange', content: 'Event', icon: BoltIcon, class: 'text-orange-400' };
-  }
-  if (props.collection === 'commands') {
-    return { backgroundColor: 'blue', textColor: 'blue', content: 'Command', icon: ChatBubbleLeftIcon, class: 'text-blue-400' };
-  }
-  if (props.collection === 'queries') {
-    return { backgroundColor: 'green', textColor: 'green', content: 'Query', icon: MagnifyingGlassIcon, class: 'text-blue-400' };
-  }
-  if (props.collection === 'domains') {
-    return {
-      backgroundColor: 'yellow',
-      textColor: 'yellow',
-      content: 'Domain',
-      icon: RectangleGroupIcon,
-      class: 'text-yellow-400',
-    };
-  }
-  if (props.collection === 'containers') {
-    return { backgroundColor: 'blue', textColor: 'blue', content: 'Container', icon: DatabaseIcon, class: 'text-blue-400' };
-  }
-  if (props.collection === 'flows') {
-    return { backgroundColor: 'teal', textColor: 'teal', content: 'Flow', icon: QueueListIcon, class: 'text-teal-400' };
-  }
-};
-
-const badges = [getBadge()];
----
-
-<VerticalSideBarLayout title="ChangeLog">
-  <main class="w-full md:pt-4 px-8 overflow-y-auto h-full max-w-[95%]">
-    <nav aria-label="Breadcrumb" class="flex">
-      <ol role="list" class="flex items-center space-x-2">
-        <li>
-          <div>
-            <a
-              href={buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.version}`)}
-              class="text-sm font-medium text-gray-500 hover:text-gray-700"
-            >
-              {props.data.name}
-            </a>
-          </div>
-        </li>
-        <li>
-          <div class="flex items-center">
-            <svg fill="currentColor" viewBox="0 0 20 20" aria-hidden="true" class="h-5 w-5 flex-shrink-0 text-gray-300">
-              <path d="M5.555 17.776l8-16 .894.448-8 16-.894-.448z"></path>
-            </svg>
-            <a
-              href={buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.version}`)}
-              class="text-sm font-medium text-gray-500 hover:text-gray-700"
-            >
-              Changelog
-            </a>
-          </div>
-        </li>
-      </ol>
-    </nav>
-    <div class="border-b border-gray-200 flex justify-between items-start py-4 w-full">
-      <div>
-        <h2 class="text-2xl md:text-4xl font-bold">{props.data.name} (Changelog)</h2>
-        <h2 class="text-lg pt-2 text-gray-500 font-light">{props.data.summary}</h2>
-        {
-          badges && (
-            <div class="flex flex-wrap py-2 pt-4">
-              {badges.map((badge: any) => (
-                <span
-                  class={`text-sm font-light text-gray-500 px-2 py-1 rounded-md mr-2 bg-${badge.backgroundColor}-100 space-x-1 border border-${badge.backgroundColor}-200 text-${badge.textColor}-800 flex items-center ${badge.class ? badge.class : ''} `}
-                >
-                  {badge.icon && <badge.icon className="w-4 h-4 inline-block mr-1 " />}
-                  <span>{badge.content}</span>
-                </span>
-              ))}
-            </div>
-          )
-        }
-      </div>
-    </div>
-    {
-      logList.length === 0 && (
-        <div class="py-4 text-gray-400 prose prose-md">
-          <p>No changelogs found.</p>
-        </div>
-      )
-    }
-    <div class="flow-root py-8 w-full">
-      <ul role="list" class="-mb-8">
-        {
-          logList.map((log, index) => (
-            <li>
-              <div class="relative pb-8">
-                {index !== logList.length - 1 ? (
-                  <span aria-hidden="true" class="absolute left-6 top-4 -ml-px h-full w-0.5 bg-gray-200" />
-                ) : null}
-                <div class="relative flex space-x-3">
-                  <div>
-                    <a
-                      href={buildUrl(`${log.url}/${log.version}`)}
-                      class={
-                        'bg-primary hover:bg-primary/80 text-white flex h-8 w-14 items-center justify-center rounded-full ring-8 ring-white'
-                      }
-                    >
-                      {log.version}
-                      {/* <DocumentTextIcon aria-hidden="true" className="h-5 w-5 text-white" /> */}
-                    </a>
-                  </div>
-                </div>
-                <div class="pl-[70px] py-2 -mt-10">
-                  {log.createdAt && (
-                    <div class="pb-2">
-                      <h3 class="text-2xl text-gray-800 font-bold">
-                        <span>
-                          {log.createdAt.toISOString().split('T')[0]} {`${log.isLatest ? '(latest)' : ''}`}
-                        </span>
-                      </h3>
-                    </div>
-                  )}
-                  {log.badges && (
-                    <div class="flex flex-wrap">
-                      {log.badges.map((badge: any) => (
-                        <span
-                          class={`text-sm font-light text-gray-500 px-2 py-1 rounded-md mr-2 bg-${badge.backgroundColor}-100 space-x-1 border border-${badge.backgroundColor}-200 text-${badge.textColor}-800 flex items-center ${badge.class ? badge.class : ''} `}
-                        >
-                          {badge.icon && <badge.icon className="w-4 h-4 inline-block mr-1 " />}
-                          <span>{badge.content}</span>
-                        </span>
-                      ))}
-                    </div>
-                  )}
-                  <div class="prose prose-md !max-w-none py-2">
-                    <log.Content components={mdxComponents(props)} />
-                  </div>
-                  {log.diffs && log.diffs.map((diff) => <div id="diff-container" set:html={diff} />)}
-                </div>
-              </div>
-            </li>
-          ))
-        }
-      </ul>
-    </div>
-    <Footer />
-  </main>
-  <ClientRouter />
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/[filename].astro b/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/[filename].astro
deleted file mode 100644
index 2aa5b7fdc..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/[filename].astro
+++ /dev/null
@@ -1,183 +0,0 @@
----
-import { Code } from 'astro-expressive-code/components';
-import fs from 'fs';
-
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import Footer from '@layouts/Footer.astro';
-import { Page } from './_[filename].data';
-import { getAbsoluteFilePathForAstroFile } from '@utils/files';
-import { buildUrl, buildEditUrlForResource } from '@utils/url-builder';
-import Admonition from '@components/MDX/Admonition';
-
-import { ServerIcon } from '@heroicons/react/24/outline';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-// Get data
-const { collection, data, filePath, filename, path: relativeSpecPath } = await Page.getData(Astro);
-
-const fileName = filename || 'schema.graphql';
-const pathToSpec = getAbsoluteFilePathForAstroFile(filePath, fileName);
-const fileExists = fs.existsSync(pathToSpec);
-const isRemote = relativeSpecPath.includes('https://');
-let content = '';
-
-if (fileExists && !isRemote) {
-  content = fs.readFileSync(pathToSpec, 'utf8');
-}
-
-if (isRemote) {
-  // Fetch the content from the remote path
-  content = await fetch(relativeSpecPath).then((res) => res.text());
-}
-
-// Create comprehensive page title
-const pageTitle = `${collection} | ${data.name} | GraphQL Schema`.replace(/^\w/, (c) => c.toUpperCase());
-
-const getServiceBadge = () => {
-  return [{ backgroundColor: 'pink', textColor: 'pink', content: 'Service', icon: ServerIcon, class: 'text-pink-400' }];
-};
-
-const getGraphQLBadge = () => {
-  return [
-    {
-      backgroundColor: 'white',
-      textColor: 'gray',
-      content: 'GraphQL Schema',
-      iconURL: buildUrl('/icons/graphql.svg', true),
-      class: 'text-black',
-      id: 'graphql-schema-badge',
-    },
-  ];
-};
-
-const badges = [...getServiceBadge(), ...getGraphQLBadge()];
-
-// Index only the latest version
-const pagefindAttributes =
-  data.version === data.latestVersion
-    ? {
-        'data-pagefind-body': '',
-        'data-pagefind-meta': `title:${pageTitle}`,
-      }
-    : {};
----
-
-<VerticalSideBarLayout title={pageTitle} description={`GraphQL schema for ${data.name}`}>
-  <main class="flex sm:px-8 docs-layout h-full" {...pagefindAttributes}>
-    <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-8 overflow-y-auto py-8">
-        <div class="border-b border-gray-200 md:pb-4">
-          <div>
-            <div class="flex justify-between items-start">
-              <div class="flex-1">
-                <h1 class="text-2xl md:text-4xl font-bold text-black mb-2">
-                  {data.name}
-                  <span class="text-gray-900">(v{data.version})</span>
-                </h1>
-                <h2 class="text-lg text-gray-600 font-medium mb-1">GraphQL Schema</h2>
-              </div>
-            </div>
-
-            {
-              badges && (
-                <div class="flex flex-wrap gap-3 py-4">
-                  {badges.map((badge: any) => (
-                    <span
-                      id={badge.id || ''}
-                      class={`
-                        inline-flex items-center gap-2 px-3 py-1.5 rounded-lg text-sm font-medium
-                        bg-${badge.backgroundColor || 'white'}-50 border border-${badge.backgroundColor || 'gray'}-200
-                        text-${badge.textColor || 'gray'}-700 shadow-sm
-                        transition-all duration-200 ease-out
-                        ${badge.class ? badge.class : ''}
-                      `}
-                    >
-                      {badge.icon && <badge.icon className={`w-4 h-4 flex-shrink-0 text-${badge.textColor || 'gray'}-600`} />}
-                      {badge.iconURL && <img src={badge.iconURL} class="w-4 h-4 flex-shrink-0 opacity-80" alt="" />}
-                      <span>{badge.content}</span>
-                    </span>
-                  ))}
-                </div>
-              )
-            }
-          </div>
-        </div>
-
-        <div data-pagefind-ignore>
-          {
-            data.version !== data.latestVersion && (
-              <div class="rounded-md bg-gradient-to-r from-purple-50 to-purple-100 p-4 not-prose my-4">
-                <div class="flex">
-                  <div class="flex-shrink-0">
-                    <svg class="h-5 w-5 text-purple-400" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
-                      <path
-                        fill-rule="evenodd"
-                        d="M8.485 2.495c.673-1.167 2.357-1.167 3.03 0l6.28 10.875c.673 1.167-.17 2.625-1.516 2.625H3.72c-1.347 0-2.189-1.458-1.515-2.625L8.485 2.495zM10 5a.75.75 0 01.75.75v3.5a.75.75 0 01-1.5 0v-3.5A.75.75 0 0110 5zm0 9a1 1 0 100-2 1 1 0 000 2z"
-                        clip-rule="evenodd"
-                      />
-                    </svg>
-                  </div>
-                  <div class="ml-3">
-                    <h3 class="text-sm font-medium text-purple-800">New version found</h3>
-                    <div class="mt-2 text-sm text-purple-700">
-                      <p>
-                        You are looking at a previous version of the service <strong>{data.name}</strong>.{' '}
-                        <a
-                          class="underline hover:text-primary block pt-2"
-                          href={buildUrl(`/docs/${collection}/${data.id}/${data.latestVersion}/graphql/${filename}`)}
-                        >
-                          The latest version of this GraphQL schema is
-                          <span>v{data.latestVersion}</span> &rarr;
-                        </a>
-                      </p>
-                    </div>
-                  </div>
-                </div>
-              </div>
-            )
-          }
-        </div>
-
-        {
-          !fileExists && (
-            <Admonition type="warning" title="Schema not found">
-              <p>The GraphQL schema file could not be found at the expected location.</p>
-            </Admonition>
-          )
-        }
-
-        {
-          fileExists && content && (
-            <div class="mt-6">
-              <div class="bg-gray-50 rounded-lg p-4 mb-4">
-                <div class="flex items-center gap-2 mb-2">
-                  <img src={buildUrl('/icons/graphql.svg', true)} class="w-5 h-5" alt="GraphQL" />
-                  <h3 class="text-lg font-semibold text-gray-800">GraphQL Schema</h3>
-                </div>
-                <p class="text-sm text-gray-600">
-                  This schema defines the GraphQL API structure including types, queries, mutations, and subscriptions for{' '}
-                  {data.name}.
-                </p>
-              </div>
-
-              <div class="not-prose overflow-x-auto">
-                <Code code={content} title={`${data.name} v${data.version} - Schema`} lang="graphql" />
-              </div>
-            </div>
-          )
-        }
-
-        <Footer />
-      </div>
-    </div>
-  </main>
-
-  <style is:global>
-    .docs-layout .prose {
-      max-width: none;
-      overflow: auto;
-    }
-  </style>
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version]/index.astro b/eventcatalog/src/pages/docs/[type]/[id]/[version]/index.astro
deleted file mode 100644
index 59cf81312..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/[version]/index.astro
+++ /dev/null
@@ -1,659 +0,0 @@
----
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import Footer from '@layouts/Footer.astro';
-import { marked } from 'marked';
-
-import components from '@components/MDX/components';
-import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
-import SchemaViewer from '@components/MDX/SchemaViewer/SchemaViewerRoot.astro';
-import Admonition from '@components/MDX/Admonition';
-
-import { getSpecificationsForService } from '@utils/collections/services';
-
-import { resourceToCollectionMap, collectionToResourceMap } from '@utils/collections/util';
-
-// SideBars
-import ServiceSideBar from '@components/SideBars/ServiceSideBar.astro';
-import MessageSideBar from '@components/SideBars/MessageSideBar.astro';
-import DomainSideBar from '@components/SideBars/DomainSideBar.astro';
-import ChannelSideBar from '@components/SideBars/ChannelSideBar.astro';
-import FlowSideBar from '@components/SideBars/FlowSideBar.astro';
-import EntitySideBar from '@components/SideBars/EntitySideBar.astro';
-import ContainerSideBar from '@components/SideBars/ContainerSideBar.astro';
-import CopyAsMarkdown from '@components/CopyAsMarkdown';
-
-import {
-  QueueListIcon,
-  RectangleGroupIcon,
-  ServerIcon,
-  BoltIcon,
-  ChatBubbleLeftIcon,
-  MagnifyingGlassIcon,
-  MapIcon,
-  ClockIcon,
-} from '@heroicons/react/24/outline';
-import { ArrowsRightLeftIcon } from '@heroicons/react/20/solid';
-import { Box, Boxes, SquarePenIcon, DatabaseIcon, DatabaseZapIcon, ShieldCheckIcon } from 'lucide-react';
-import type { CollectionTypes } from '@types';
-
-import { render } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-
-import { getIcon } from '@utils/badges';
-import { getDeprecatedDetails } from '@utils/collections/util';
-import { buildUrl, buildEditUrlForResource } from '@utils/url-builder';
-import { getSchemasFromResource } from '@utils/collections/schemas';
-import { isEventCatalogChatEnabled, isMarkdownDownloadEnabled, isVisualiserEnabled } from '@utils/feature';
-
-import { getMDXComponentsByName } from '@utils/markdown';
-
-import config from '@config';
-import { Page } from './_index.data';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-// Get data
-const props = await Page.getData(Astro);
-
-const { Content } = await render(props);
-
-const pageTitle = `${props.collection} | ${props.data.name}`.replace(/^\w/, (c) => c.toUpperCase());
-const contentBadges = props.data.badges || [];
-const editUrl =
-  props.data.editUrl || (config.editUrl && props?.filePath ? buildEditUrlForResource(config.editUrl, props?.filePath) : '');
-
-const getContentBadges = () =>
-  contentBadges.map((badge: any) => ({
-    ...badge,
-    icon: badge.icon ? getIcon(badge.icon) : null,
-  }));
-
-const getBadge = () => {
-  if (props.collection === 'services') {
-    return [{ backgroundColor: 'pink', textColor: 'pink', content: 'Service', icon: ServerIcon, class: 'text-pink-400' }];
-  }
-  if (props.collection === 'events') {
-    return [{ backgroundColor: 'orange', textColor: 'orange', content: 'Event', icon: BoltIcon, class: 'text-orange-400' }];
-  }
-  if (props.collection === 'commands') {
-    return [{ backgroundColor: 'blue', textColor: 'blue', content: 'Command', icon: ChatBubbleLeftIcon, class: 'text-blue-400' }];
-  }
-  if (props.collection === 'queries') {
-    return [
-      { backgroundColor: 'green', textColor: 'green', content: 'Query', icon: MagnifyingGlassIcon, class: 'text-green-400' },
-    ];
-  }
-  if (props.collection === 'domains') {
-    return [
-      {
-        backgroundColor: 'yellow',
-        textColor: 'yellow',
-        content: 'Domain',
-        icon: RectangleGroupIcon,
-        class: 'text-yellow-400',
-      },
-    ];
-  }
-
-  if (props.collection === 'flows') {
-    return [{ backgroundColor: 'teal', textColor: 'teal', content: 'Flow', icon: QueueListIcon, class: 'text-gray' }];
-  }
-
-  if (props.collection === 'channels') {
-    return [{ backgroundColor: 'teal', textColor: 'teal', content: 'Channel', icon: ArrowsRightLeftIcon, class: 'text-gray' }];
-  }
-
-  if (props.collection === 'containers') {
-    const badges = [];
-    const content = props.data.container_type?.charAt(0).toUpperCase() + props.data.container_type?.slice(1) || 'Database';
-
-    badges.push({ backgroundColor: 'blue', textColor: 'blue', content: content, icon: DatabaseIcon, class: 'text-gray' });
-
-    if (props.data?.technology) {
-      badges.push({
-        backgroundColor: 'indigo',
-        textColor: 'indigo',
-        content: `${props.data.technology}`,
-        icon: DatabaseZapIcon,
-      });
-    }
-
-    if (props.data?.residency) {
-      badges.push({
-        backgroundColor: 'red',
-        textColor: 'red',
-        content: `Residency: ${props.data.residency}`,
-        icon: MapIcon,
-      });
-    }
-
-    if (props.data?.retention) {
-      badges.push({
-        backgroundColor: 'green',
-        textColor: 'green',
-        content: `Retention: ${props.data.retention}`,
-        icon: ClockIcon,
-      });
-    }
-
-    if (props.data?.access_mode) {
-      badges.push({
-        backgroundColor: 'green',
-        textColor: 'green',
-        content: `Access Mode: ${props.data.access_mode}`,
-        icon: ShieldCheckIcon,
-      });
-    }
-
-    return badges;
-  }
-
-  if (props.collection === 'entities') {
-    const entityBadges = [{ backgroundColor: 'purple', textColor: 'purple', content: 'Entity', icon: Box, class: 'text-gray' }];
-    if (props.data.aggregateRoot) {
-      entityBadges.push({
-        backgroundColor: 'purple',
-        textColor: 'purple',
-        content: '(Aggregate Root)',
-        icon: Boxes,
-        class: 'text-gray',
-      });
-    }
-    return entityBadges;
-  }
-
-  return [{ backgroundColor: 'teal', textColor: 'teal', content: '', icon: QueueListIcon, class: 'text-gray' }];
-};
-
-const getSpecificationBadges = () => {
-  const badges = [];
-
-  const specifications = getSpecificationsForService(props);
-
-  const asyncapiSpecs = specifications.filter((spec) => spec.type === 'asyncapi');
-  const openapiSpecs = specifications.filter((spec) => spec.type === 'openapi');
-  const graphQLSpecs = specifications.filter((spec) => spec.type === 'graphql');
-
-  if (openapiSpecs.length > 0) {
-    for (const spec of openapiSpecs) {
-      badges.push({
-        backgroundColor: 'white',
-        textColor: 'gray',
-        content: spec.name || 'OpenAPI Spec',
-        iconURL: buildUrl('/icons/openapi.svg', true),
-        class: 'text-black hover:underline',
-        id: 'open-api-badge',
-        url: buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.version}/spec/${spec.filenameWithoutExtension}`),
-      });
-    }
-  }
-
-  if (asyncapiSpecs.length > 0) {
-    for (const spec of asyncapiSpecs) {
-      badges.push({
-        backgroundColor: 'white',
-        textColor: 'gray',
-        content: spec.name || 'AsyncAPI Spec',
-        iconURL: buildUrl('/icons/asyncapi.svg', true),
-        class: 'text-black hover:underline',
-        id: 'asyncapi-badge',
-        url: buildUrl(
-          `/docs/${props.collection}/${props.data.id}/${props.data.version}/asyncapi/${spec.filenameWithoutExtension}`
-        ),
-      });
-    }
-  }
-
-  if (graphQLSpecs.length > 0) {
-    for (const spec of graphQLSpecs) {
-      badges.push({
-        backgroundColor: 'white',
-        textColor: 'gray',
-        content: spec.name || 'GraphQL Spec',
-        iconURL: buildUrl('/icons/graphql.svg', true),
-        class: 'text-black hover:underline',
-        id: 'graphql-badge',
-        url: buildUrl(
-          `/docs/${props.collection}/${props.data.id}/${props.data.version}/graphql/${spec.filenameWithoutExtension}`
-        ),
-      });
-    }
-  }
-
-  return badges;
-};
-
-const badges = [...getBadge(), ...getContentBadges(), ...getSpecificationBadges()];
-
-// Index only the latest version
-const pagefindAttributes =
-  props.data.version === props.data.latestVersion
-    ? {
-        'data-pagefind-body': '',
-        'data-pagefind-meta': `title:${pageTitle}`,
-      }
-    : {};
-
-const {
-  hasDeprecated,
-  message: deprecatedMessage,
-  isMarkedAsDeprecated,
-  deprecatedDate: formattedDate,
-} = getDeprecatedDetails(props as unknown as CollectionEntry<CollectionTypes>);
-
-let friendlyCollectionName = props.collection.slice(0, props.collection.length - 1);
-friendlyCollectionName = friendlyCollectionName === 'querie' ? 'query' : friendlyCollectionName;
-
-const schemasForResource = getSchemasFromResource(props);
-
-const generatePromptForResource = (props: any) => {
-  return `
-    Please tell me more about the ${props.collection.slice(0, props.collection.length - 1)} -  ${props.data.name} v${props.data.version} in this catalog.
-  `;
-};
-
-// Handle node graphs in the markdown
-let nodeGraphs = getMDXComponentsByName(props.body || '', 'NodeGraph') || [];
-
-// Get props for the node graph (when no id is passed, we assume its the current page)
-const nodeGraphPropsForPage = nodeGraphs.find((nodeGraph: any) => nodeGraph.id === undefined) || ({} as any);
-
-// This will render the graph for this page
-nodeGraphs.push({
-  id: props.data.id,
-  version: props.data.version,
-  type: collectionToResourceMap[props.collection as keyof typeof collectionToResourceMap],
-  ...nodeGraphPropsForPage,
-  search: nodeGraphPropsForPage?.search ? nodeGraphPropsForPage.search === 'true' : true,
-  legend: nodeGraphPropsForPage?.legend ? nodeGraphPropsForPage.legend === 'true' : true,
-});
----
-
-<VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
-  <main class="flex sm:px-8 docs-layout h-full" {...pagefindAttributes}>
-    <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-8 overflow-y-auto py-8">
-        <div class="border-b border-gray-200 md:pb-2">
-          <div>
-            <div class="flex justify-between items-center">
-              <h2
-                id="doc-page-header"
-                class={`text-2xl md:text-4xl font-bold text-black ${props.data.deprecated && hasDeprecated ? 'text-red-500' : ''}`}
-              >
-                {props.data.name}
-                <span class="">(v{props.data.version})</span>
-              </h2>
-              <div class="hidden lg:block">
-                <CopyAsMarkdown
-                  client:only="react"
-                  schemas={schemasForResource}
-                  chatQuery={generatePromptForResource(props)}
-                  chatEnabled={isEventCatalogChatEnabled()}
-                  markdownDownloadEnabled={isMarkdownDownloadEnabled()}
-                  editUrl={editUrl}
-                />
-              </div>
-            </div>
-            {
-              isMarkedAsDeprecated && hasDeprecated && (
-                <Admonition
-                  className="w-full"
-                  type="alert"
-                  title={formattedDate ? `This ${friendlyCollectionName} was deprecated on ${formattedDate}` : `Deprecated`}
-                >
-                  <div>
-                    {!deprecatedMessage && (
-                      <p>
-                        The {friendlyCollectionName} has been marked as deprecated
-                        {formattedDate && ` on ${formattedDate}`}.
-                      </p>
-                    )}
-                    {deprecatedMessage && <div class="prose prose-sm max-w-none" set:html={marked.parse(deprecatedMessage)} />}
-                  </div>
-                </Admonition>
-              )
-            }
-            {
-              isMarkedAsDeprecated && !hasDeprecated && (
-                <Admonition type="warning" title={`This ${friendlyCollectionName} will be deprecated on ${formattedDate}`}>
-                  <div>
-                    {!deprecatedMessage && (
-                      <p>
-                        The {friendlyCollectionName} will be deprecated on {formattedDate}.
-                      </p>
-                    )}
-                    {deprecatedMessage && <div class="prose prose-sm max-w-none" set:html={marked.parse(deprecatedMessage)} />}
-                  </div>
-                </Admonition>
-              )
-            }
-
-            <h2 class="text-lg pt-2 text-gray-500 font-light">{props.data.summary}</h2>
-            {
-              badges && (
-                <div class="flex flex-wrap gap-3 py-4">
-                  {badges.map((badge: any) => {
-                    return (
-                      <a href={badge.url || '#'} class="group transition-all duration-200 hover:scale-105">
-                        <span
-                          id={badge.id || ''}
-                          class={`
-                            inline-flex items-center gap-2 px-3 py-1.5 rounded-lg text-sm font-medium
-                            bg-${badge.backgroundColor || 'white'}-50 border border-${badge.backgroundColor || 'gray'}-200
-                            text-${badge.textColor || 'gray'}-700 shadow-sm
-                            hover:bg-${badge.backgroundColor || 'purple'}-100 hover:border-${badge.backgroundColor || 'purple'}-300
-                            hover:shadow-md hover:text-${badge.textColor || 'purple'}-800
-                            transition-all duration-200 ease-out
-                            ${badge.class ? badge.class : ''}
-                          `}
-                        >
-                          {badge.icon && (
-                            <badge.icon
-                              className={`w-4 h-4 flex-shrink-0 text-${badge.textColor || 'gray'}-600 group-hover:text-${badge.textColor || 'purple'}-700 transition-colors duration-200`}
-                            />
-                          )}
-                          {badge.iconURL && (
-                            <img
-                              src={badge.iconURL}
-                              class="w-4 h-4 flex-shrink-0 opacity-80 group-hover:opacity-100 transition-opacity duration-200"
-                              alt=""
-                            />
-                          )}
-                          <span class={`group-hover:text-${badge.textColor || 'purple'}-800 transition-colors duration-200`}>
-                            {badge.content}
-                          </span>
-                        </span>
-                      </a>
-                    );
-                  })}
-                </div>
-              )
-            }
-
-            {
-              props.data.draft && (
-                <Admonition type="warning" title={props.data?.draft?.title || `Draft ${friendlyCollectionName}`}>
-                  <div>
-                    {!props.data.draft.message && (
-                      <p>This resource has been marked as a draft and may still be under development.</p>
-                    )}
-                    {props.data.draft.message && (
-                      <div class="prose prose-sm max-w-none" set:html={marked.parse(props.data.draft.message)} />
-                    )}
-                  </div>
-                </Admonition>
-              )
-            }
-          </div>
-        </div>
-
-        <div data-pagefind-ignore>
-          {
-            props.data.version !== props.data.latestVersion && (
-              <div class="rounded-md bg-gradient-to-r from-purple-50 to-purple-100 p-4 not-prose my-4">
-                <div class="flex">
-                  <div class="flex-shrink-0">
-                    <svg class="h-5 w-5 text-purple-400" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
-                      <path
-                        fill-rule="evenodd"
-                        d="M8.485 2.495c.673-1.167 2.357-1.167 3.03 0l6.28 10.875c.673 1.167-.17 2.625-1.516 2.625H3.72c-1.347 0-2.189-1.458-1.515-2.625L8.485 2.495zM10 5a.75.75 0 01.75.75v3.5a.75.75 0 01-1.5 0v-3.5A.75.75 0 0110 5zm0 9a1 1 0 100-2 1 1 0 000 2z"
-                        clip-rule="evenodd"
-                      />
-                    </svg>
-                  </div>
-                  <div class="ml-3">
-                    <h3 class="text-sm font-medium text-purple-800">New version found</h3>
-                    <div class="mt-2 text-sm text-purple-700">
-                      <p>
-                        You are looking at a previous version of the {props.collection.slice(0, props.collection.length - 1)}{' '}
-                        <strong>{props.data.name}</strong>.{' '}
-                        <a
-                          class="underline hover:text-primary block pt-2"
-                          href={buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.latestVersion}`)}
-                        >
-                          The latest version of this {props.collection.slice(0, props.collection.length - 1)} is
-                          <span>v{props.data.latestVersion}</span> &rarr;
-                        </a>
-                      </p>
-                    </div>
-                  </div>
-                </div>
-              </div>
-            )
-          }
-        </div>
-
-        <div class="prose prose-md py-4 w-full">
-          <Content components={components(props)} />
-        </div>
-        <div data-pagefind-ignore>
-          <!-- @ts-ignore -->
-          <!-- <SchemaViewer id={props.data.id} catalog={props.catalog} filePath={props.filePath} /> -->
-          <SchemaViewer id={props.data.id} filePath={props.filePath} />
-
-          {
-            nodeGraphs.length > 0 &&
-              nodeGraphs.map((nodeGraph: any) => {
-                const collection = resourceToCollectionMap[nodeGraph.type as keyof typeof resourceToCollectionMap];
-                return (
-                  <NodeGraph
-                    id={nodeGraph.id}
-                    version={nodeGraph.version}
-                    collection={collection}
-                    title={nodeGraph.title}
-                    mode={nodeGraph.mode || 'simple'}
-                    linksToVisualiser={true}
-                    showSearch={nodeGraph.search ?? true}
-                    showLegend={nodeGraph.legend ?? true}
-                    href={
-                      isVisualiserEnabled()
-                        ? {
-                            label: 'Open in Visualiser',
-                            url: buildUrl(`/visualiser/${collection}/${nodeGraph.id}/${nodeGraph.version}`),
-                          }
-                        : undefined
-                    }
-                  />
-                );
-              })
-          }
-        </div>
-        <Footer />
-        <!-- Add edit this page button  with icon and text-->
-        <div class="flex justify-end">
-          <!-- Built with EventCatalog -->
-          {
-            editUrl && (
-              <div class="flex justify-end">
-                <a href={editUrl} class="text-sm text-gray-700 hover:text-gray-700 border border-gray-200 rounded-md p-2">
-                  <SquarePenIcon className="w-4 h-4 inline-block mr-1" />
-                  Edit this page
-                </a>
-              </div>
-            )
-          }
-        </div>
-      </div>
-      <aside class="hidden lg:block sticky top-0 pb-10 w-96 overflow-y-auto py-2" data-pagefind-ignore>
-        <!-- @ts-ignore -->
-        {
-          (props?.collection === 'events' || props.collection === 'commands' || props.collection === 'queries') && (
-            <MessageSideBar message={props} />
-          )
-        }
-        {props?.collection === 'services' && <ServiceSideBar service={props} />}
-        {props?.collection === 'domains' && <DomainSideBar domain={props} />}
-        {props?.collection === 'channels' && <ChannelSideBar channel={props} />}
-        {props?.collection === 'flows' && <FlowSideBar flow={props} />}
-        {props?.collection === 'entities' && <EntitySideBar entity={props} />}
-        {props?.collection === 'containers' && <ContainerSideBar container={props} />}
-      </aside>
-    </div>
-  </main>
-
-  <style is:global>
-    .docs-layout .prose {
-      max-width: none;
-      overflow: auto;
-    }
-
-    .mermaid svg {
-      margin: 1em auto 2em;
-    }
-
-    /* Fix for architecture diagrams */
-    .mermaid[data-content*='architecture'] svg {
-      max-width: 350px !important;
-      margin: 0;
-      /* width: 100px !important; */
-    }
-  </style>
-
-  <script define:vars={{ props, config }}>
-    // Fix to pass information to componets that are client side only
-    // and require catalog information
-    window.eventcatalog = {};
-    // @ts-ignore
-    window.eventcatalog[`${props.collection}-${props.data.id}`] = props.catalog;
-
-    window.eventcatalog.mermaid = config.mermaid;
-  </script>
-
-  <script>
-    // Listen for Astro transititions
-    document.addEventListener('astro:page-load', () => {
-      const graphs = document.getElementsByClassName('mermaid');
-      if (document.getElementsByClassName('mermaid').length > 0) {
-        renderDiagrams(graphs);
-      }
-    });
-
-    /**
-     * Renders mermaid diagrams in the page
-     * @param {HTMLCollectionOf<HTMLElement>} graphs - The collection of mermaid graph elements
-     */
-    async function renderDiagrams(graphs: any) {
-      const { default: mermaid } = await import('mermaid');
-
-      if (window.eventcatalog.mermaid) {
-        const { icons } = await import('@iconify-json/logos');
-        const { iconPacks = [], enableSupportForElkLayout = false } = window.eventcatalog.mermaid ?? {};
-
-        if (iconPacks.length > 0) {
-          const iconPacksToRegister = iconPacks.map((name: any) => {
-            return {
-              name,
-              icons,
-            };
-          });
-
-          mermaid.registerIconPacks(iconPacksToRegister);
-        }
-
-        if (enableSupportForElkLayout) {
-          // @ts-ignore
-          const { default: elkLayouts } = await import('@mermaid-js/layout-elk/dist/mermaid-layout-elk.core.mjs');
-          mermaid.registerLayoutLoaders(elkLayouts);
-        }
-      }
-
-      mermaid.initialize({
-        // fontSize: 2,
-        flowchart: {
-          curve: 'linear',
-          rankSpacing: 0,
-          nodeSpacing: 0,
-        },
-        startOnLoad: false,
-        fontFamily: 'var(--sans-font)',
-        // @ts-ignore This works, but TS expects a enum for some reason
-        theme: 'light',
-        architecture: {
-          useMaxWidth: true,
-        },
-      });
-
-      for (const graph of graphs) {
-        const content = graph.getAttribute('data-content');
-        if (!content) continue;
-        let svg = document.createElement('svg');
-        const id = (svg.id = 'mermaid-' + Math.round(Math.random() * 100000));
-        graph.appendChild(svg);
-        mermaid.render(id, content).then((result) => {
-          graph.innerHTML = result.svg;
-        });
-      }
-    }
-
-    const graphs = document.getElementsByClassName('mermaid');
-    if (document.getElementsByClassName('mermaid').length > 0) {
-      renderDiagrams(graphs);
-    }
-
-    // Make renderDiagrams available globally for accordion component
-    window.renderDiagrams = renderDiagrams;
-  </script>
-
-  <script>
-    import('pako').then(({ deflate }: any) => {
-      document.addEventListener('astro:page-load', () => {
-        const blocks = document.getElementsByClassName('plantuml');
-        if (blocks.length > 0) {
-          renderPlantUML(blocks, deflate);
-        }
-      });
-
-      function renderPlantUML(blocks: any, deflate: any) {
-        for (const block of blocks) {
-          const content = block.getAttribute('data-content');
-          if (!content) continue;
-
-          const encoded = encodePlantUML(content, deflate);
-          const img = document.createElement('img');
-          img.src = `https://www.plantuml.com/plantuml/svg/~1${encoded}`;
-          img.alt = 'PlantUML diagram';
-          img.loading = 'lazy';
-          block.innerHTML = '';
-          // Add class to the img
-          img.classList.add('mx-auto');
-          block.appendChild(img);
-        }
-      }
-
-      function encodePlantUML(text: any, deflate: any) {
-        const utf8encoded = new TextEncoder().encode(text);
-        const compressed = deflate(utf8encoded, { level: 9 });
-        return encode64(compressed);
-      }
-
-      const encode64 = (data: any) => {
-        const chars = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_';
-        let str = '';
-        let i = 0;
-        while (i < data.length) {
-          let b1 = data[i++];
-          let b2 = i < data.length ? data[i++] : 0;
-          let b3 = i < data.length ? data[i++] : 0;
-
-          let c1 = b1 >> 2;
-          let c2 = ((b1 & 0x3) << 4) | (b2 >> 4);
-          let c3 = ((b2 & 0xf) << 2) | (b3 >> 6);
-          let c4 = b3 & 0x3f;
-
-          str += chars[c1] + chars[c2] + chars[c3] + chars[c4];
-        }
-        return str;
-      };
-
-      const graphs = document.getElementsByClassName('plantuml');
-      if (document.getElementsByClassName('plantuml').length > 0) {
-        renderPlantUML(graphs, deflate);
-      }
-
-      window.renderPlantUML = (graphs: any) => {
-        renderPlantUML(graphs, deflate);
-      };
-    });
-  </script>
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/[filename].astro b/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/[filename].astro
deleted file mode 100644
index ffdab2071..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/[filename].astro
+++ /dev/null
@@ -1,71 +0,0 @@
----
-import fs from 'node:fs';
-import OpenAPISpec from './_OpenAPI.tsx';
-
-import { DocumentMinusIcon } from '@heroicons/react/24/outline';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import './_styles.css';
-import { Page } from './_[filename].data.ts';
-import { getAbsoluteFilePathForAstroFile } from '@utils/files';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-// Get data
-const props = await Page.getData(Astro);
-
-// @ts-ignore
-const { collection, data, catalog, filePath, filename, path: relativeSpecPath } = props;
-const fileName = filename || 'openapi.yml';
-
-const pathToSpec = getAbsoluteFilePathForAstroFile(filePath, fileName);
-const fileExists = fs.existsSync(pathToSpec);
-const isRemote = relativeSpecPath.includes('https://');
-
-let content = '';
-
-// Capitalize the first letter of a string
-const pageTitle = `${collection} | ${data.name} | OpenAPI Spec`.replace(/^\w/, (c) => c.toUpperCase());
-
-// Index only the latest version
-const pagefindAttributes =
-  data.version === data.latestVersion
-    ? {
-        'data-pagefind-body': '',
-        'data-pagefind-meta': `title:${pageTitle}`,
-      }
-    : {};
-
-if (fileExists && !isRemote) {
-  content = fs.readFileSync(pathToSpec, 'utf8');
-}
-
-if (isRemote) {
-  // Fetch the content from the remote path
-  content = await fetch(relativeSpecPath).then((res) => res.text());
-}
----
-
-<VerticalSideBarLayout title={pageTitle}>
-  {
-    !fileExists && !isRemote ? (
-      <div class="text-center h-screen  flex flex-col justify-center ">
-        <DocumentMinusIcon className="mx-auto h-12 w-12 text-gray-400" />
-        <h3 class="mt-2 text-sm font-semibold text-gray-900">No OpenAPI spec file found</h3>
-        <p class="mt-1 text-xs text-gray-400">
-          Could not find OpenAPI file for {data.name} in {`/${catalog.path}`}
-        </p>
-      </div>
-    ) : (
-      <div {...pagefindAttributes}>
-        {
-          // Currently, Pagefind does not index metadata (such as the title),
-          // so we need to ensure it is included as text on the page.
-          // https://github.com/CloudCannon/pagefind/issues/437
-        }
-        <h2 class="hidden">{pageTitle}</h2>
-        <OpenAPISpec client:only="react" spec={content} />
-      </div>
-    )
-  }
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_OpenAPI.tsx b/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_OpenAPI.tsx
deleted file mode 100644
index 0b55c26e6..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_OpenAPI.tsx
+++ /dev/null
@@ -1,33 +0,0 @@
-import { useState } from 'react';
-import { ApiReferenceReact } from '@scalar/api-reference-react';
-import '@scalar/api-reference-react/style.css';
-import './_styles.css';
-const OpenAPISpec = ({ spec }: { spec: string }) => {
-  const [loaded, setLoaded] = useState(false);
-  return (
-    <div>
-      {!loaded && <div>Loading...</div>}
-      <ApiReferenceReact
-        configuration={{
-          spec: {
-            content: spec,
-          },
-          theme: 'fastify',
-          hideClientButton: true,
-          onLoaded: () => {
-            setLoaded(true);
-          },
-          forceDarkModeState: 'light',
-          darkMode: false,
-          defaultOpenAllTags: true,
-          hideDarkModeToggle: true,
-          searchHotKey: 'p',
-          showSidebar: true,
-          customCss: 'bg-red-500',
-        }}
-      />
-    </div>
-  );
-};
-
-export default OpenAPISpec;
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/index.astro b/eventcatalog/src/pages/docs/[type]/[id]/index.astro
deleted file mode 100644
index 251fbe6bd..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/index.astro
+++ /dev/null
@@ -1,70 +0,0 @@
----
-import Seo from '@components/Seo.astro';
-import { buildUrl } from '@utils/url-builder';
-import { getEvents } from '@utils/events';
-import { getEntities } from '@utils/entities';
-import { getCommands } from '@utils/commands';
-import { getServices } from '@utils/collections/services';
-import { getDomains } from '@utils/collections/domains';
-import type { CollectionEntry } from 'astro:content';
-import type { CollectionTypes } from '@types';
-import { getChannels } from '@utils/channels';
-
-export async function getStaticPaths() {
-  const [events, commands, services, domains, channels, entities] = await Promise.all([
-    getEvents(),
-    getCommands(),
-    getServices(),
-    getDomains(),
-    getChannels(),
-    getEntities(),
-  ]);
-
-  const buildPages = (collection: CollectionEntry<CollectionTypes>[]) => {
-    return collection.map((item) => ({
-      params: {
-        type: item.collection,
-        id: item.data.id,
-      },
-      props: {
-        type: item.collection,
-        ...item,
-      },
-    }));
-  };
-
-  return [
-    ...buildPages(domains),
-    ...buildPages(events),
-    ...buildPages(services),
-    ...buildPages(commands),
-    ...buildPages(channels),
-    ...buildPages(entities),
-  ];
-}
-
-const props = Astro.props;
-
-const pageTitle = `${props.collection} | ${props.data.name}`.replace(/^\w/, (c) => c.toUpperCase());
-
-const { pathname } = Astro.url;
-const redirectUrl = buildUrl(pathname + '/' + props.data.latestVersion, false, true);
----
-
-<!doctype html>
-<html lang="en">
-  <head>
-    <Seo title={`EventCatalog | ${pageTitle}`} ogTitle={pageTitle} />
-  </head>
-  <body>
-    <p>You are being redirected to <a href={redirectUrl}>{redirectUrl}</a></p>
-  </body>
-</html>
-
-<script define:vars={{ redirectUrl }}>
-  document.addEventListener('DOMContentLoaded', () => {
-    const searchParams = window.location.search;
-    const fullRedirectUrl = redirectUrl + searchParams;
-    window.location.href = fullRedirectUrl;
-  });
-</script>
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/language.mdx.ts b/eventcatalog/src/pages/docs/[type]/[id]/language.mdx.ts
deleted file mode 100644
index b6305223a..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/language.mdx.ts
+++ /dev/null
@@ -1,42 +0,0 @@
-import { getDomains, getUbiquitousLanguage } from '@utils/collections/domains';
-import type { CollectionEntry } from 'astro:content';
-import type { APIRoute } from 'astro';
-import config from '@config';
-import fs from 'fs';
-
-export async function getStaticPaths() {
-  const domains = await getDomains({ getAllVersions: false });
-
-  const buildPages = (collection: CollectionEntry<'domains'>[]) => {
-    return collection.map((item) => ({
-      params: {
-        type: item.collection,
-        id: item.data.id,
-      },
-      props: {
-        type: item.collection,
-        ...item,
-      },
-    }));
-  };
-
-  return [...buildPages(domains)];
-}
-
-export const GET: APIRoute = async ({ params, props }) => {
-  // Just return empty array if LLMs are not enabled
-  if (!config.llmsTxt?.enabled) {
-    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
-  }
-
-  const ubiquitousLanguages = await getUbiquitousLanguage(props as CollectionEntry<'domains'>);
-  const ubiquitousLanguage = ubiquitousLanguages[0];
-
-  if (ubiquitousLanguage?.filePath) {
-    let file = fs.readFileSync(ubiquitousLanguage.filePath, 'utf8');
-
-    return new Response(file, { status: 200 });
-  }
-
-  return new Response('Not found', { status: 404 });
-};
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/language/[dictionaryId]/index.astro b/eventcatalog/src/pages/docs/[type]/[id]/language/[dictionaryId]/index.astro
deleted file mode 100644
index 2328ebb5b..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/language/[dictionaryId]/index.astro
+++ /dev/null
@@ -1,206 +0,0 @@
----
-import RectangleGroupIcon from '@heroicons/react/24/outline/RectangleGroupIcon';
-import Footer from '@layouts/Footer.astro';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { buildUrl } from '@utils/url-builder';
-import { ClientRouter } from 'astro:transitions';
-import { marked } from 'marked';
-import * as LucideIcons from 'lucide-react';
-
-import { Page } from './_index.data';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-const props = await Page.getData(Astro);
-
-const { ubiquitousLanguage } = props;
-const pageTitle = `${props.type} | ${ubiquitousLanguage.name}`.replace(/^\w/, (c) => c.toUpperCase());
-
-marked.setOptions({
-  breaks: true,
-  gfm: true,
-});
-
-const badges = [
-  {
-    backgroundColor: 'yellow',
-    textColor: 'yellow',
-    content: props.domain.name,
-    icon: RectangleGroupIcon,
-    class: 'text-yellow-400',
-    href: buildUrl(`/docs/${props.type}/${props.domainId}`),
-  },
-];
----
-
-<VerticalSideBarLayout title={pageTitle} description={ubiquitousLanguage.summary}>
-  <main class="flex sm:px-8 docs-layout h-full max-w-7xl" data-pagefind-body data-pagefind-meta={`title:${pageTitle}`}>
-    <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-8 overflow-y-auto py-8 min-h-[50em]">
-        {/* Breadcrumb */}
-        <nav class="mb-4 flex items-center space-x-2 text-sm text-gray-500" aria-label="Breadcrumb">
-          <a
-            href={buildUrl(`/docs/${props.type}/${props.domainId}/${props.domain.latestVersion}`)}
-            class="hover:text-gray-700 hover:underline flex items-center gap-2"
-          >
-            <RectangleGroupIcon className="h-4 w-4" />
-            {props.domain.name}
-          </a>
-          <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
-            <path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7"></path>
-          </svg>
-          <a
-            href={buildUrl(`/docs/${props.type}/${props.domainId}/language`)}
-            class="hover:text-gray-700 hover:underline flex items-center gap-2"
-          >
-            {
-              (() => {
-                const BookOpen = LucideIcons.BookOpen;
-                //@ts-ignore
-                return <BookOpen className="h-4 w-4" />;
-              })()
-            }
-            Ubiquitous Language Explorer
-          </a>
-          <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
-            <path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7"></path>
-          </svg>
-          <span class="text-gray-900">{ubiquitousLanguage.name}</span>
-        </nav>
-
-        <div class="border-b border-gray-200 flex justify-between items-start md:pb-2">
-          <div>
-            <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-black">
-              {ubiquitousLanguage.name}
-            </h2>
-            <p class="text-lg pt-2 text-gray-500 font-light">{ubiquitousLanguage.summary}</p>
-            <!-- Add bage -->
-            {
-              badges && (
-                <div class="flex flex-wrap py-2 pt-4">
-                  {badges.map((badge: any) => {
-                    return (
-                      <a href={badge.href || '#'} class="pb-2">
-                        <span
-                          id={badge.id || ''}
-                          class={`text-sm font-light text-gray-500 px-2 py-1 rounded-md mr-2  bg-gradient-to-b  from-${badge.backgroundColor}-100 to-${badge.backgroundColor}-200 space-x-1 border border-${badge.backgroundColor}-200 text-${badge.textColor}-800 flex items-center ${badge.class ? badge.class : ''} `}
-                        >
-                          {badge.icon && <badge.icon className="w-4 h-4 inline-block mr-1 " />}
-                          {badge.iconURL && <img src={badge.iconURL} class="w-5 h-5 inline-block " />}
-                          <span>{badge.content}</span>
-                        </span>
-                      </a>
-                    );
-                  })}
-                </div>
-              )
-            }
-          </div>
-        </div>
-
-        {
-          ubiquitousLanguage.description && (
-            <div class="prose prose-md py-4 max-w-none" set:html={marked.parse(ubiquitousLanguage.description)} />
-          )
-        }
-
-        {
-          !ubiquitousLanguage.description && (
-            <div class="prose prose-md py-4 max-w-none">
-              <p>No description for {ubiquitousLanguage.name} available.</p>
-            </div>
-          )
-        }
-
-        <Footer />
-      </div>
-    </div>
-    <ClientRouter />
-  </main>
-
-  <script>
-    function initializeSearch() {
-      const searchInput = document.getElementById('searchInput');
-      const termCards = document.querySelectorAll('.term-card');
-      const noSearchResults = document.getElementById('noSearchResults');
-
-      searchInput?.addEventListener('input', (e) => {
-        const searchTerm = (e.target as HTMLInputElement).value.toLowerCase();
-        let visibleCount = 0;
-
-        termCards.forEach((card) => {
-          const title = card.querySelector('h3')?.textContent?.toLowerCase() || '';
-          const description = card.querySelector('p')?.textContent?.toLowerCase() || '';
-          const matches = title.includes(searchTerm) || description.includes(searchTerm);
-
-          card.classList.toggle('hidden', !matches);
-          if (matches) visibleCount++;
-        });
-
-        // Show/hide no results message
-        if (noSearchResults) {
-          noSearchResults.classList.toggle('hidden', visibleCount > 0);
-        }
-      });
-    }
-
-    function initializeShowMore() {
-      const cards = document.querySelectorAll('.term-card');
-
-      cards.forEach((card) => {
-        const newCard = card.cloneNode(true);
-        if (card.parentNode) {
-          card.parentNode.replaceChild(newCard, card);
-          // Initially show summary
-          const summary = (newCard as Element).querySelector('.summary-text');
-          summary?.classList.add('visible');
-        }
-        newCard.addEventListener('click', () => {
-          const description = (newCard as Element).querySelector('.description-text');
-          const summary = (newCard as Element).querySelector('.summary-text');
-          const showMoreText = (newCard as Element).querySelector('.show-more-text');
-
-          if (description && summary && showMoreText) {
-            (newCard as Element).classList.toggle('expanded');
-            description.classList.toggle('visible');
-            summary.classList.toggle('visible');
-            showMoreText.textContent = description.classList.contains('visible') ? 'Show less' : 'Show more';
-          }
-        });
-      });
-    }
-
-    function highlightMatchingTerm() {
-      const urlParams = new URLSearchParams(window.location.search);
-      const termId = urlParams.get('id');
-
-      if (termId) {
-        const cards = document.querySelectorAll('.term-card');
-        cards.forEach((card) => {
-          const termName = card.querySelector('h3')?.textContent?.trim();
-          if (termName?.toLowerCase() === termId.toLowerCase()) {
-            // Add highlight class
-            card.classList.add('highlighted');
-            (card as HTMLElement).click();
-
-            setTimeout(() => {
-              // Scroll into view
-              card.scrollIntoView({ behavior: 'smooth', block: 'center' });
-            }, 300);
-          }
-        });
-      }
-    }
-
-    document.addEventListener('astro:page-load', () => {
-      initializeShowMore();
-      initializeSearch();
-      highlightMatchingTerm();
-    });
-
-    initializeShowMore();
-    initializeSearch();
-    highlightMatchingTerm();
-  </script>
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/language/_index.data.ts b/eventcatalog/src/pages/docs/[type]/[id]/language/_index.data.ts
deleted file mode 100644
index 4b26f4ec2..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/language/_index.data.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import { isSSR } from '@utils/feature';
-import { HybridPage } from '@utils/page-loaders/hybrid-page';
-
-/**
- * Domain page class with static methods
- */
-export class Page extends HybridPage {
-  static async getStaticPaths() {
-    if (isSSR()) {
-      return [];
-    }
-
-    const { getDomains } = await import('@utils/collections/domains');
-    const domains = await getDomains({ getAllVersions: false });
-
-    return domains.map((item) => ({
-      params: {
-        type: item.collection,
-        id: item.data.id,
-      },
-      props: {
-        type: item.collection,
-        ...item,
-      },
-    }));
-  }
-
-  protected static async fetchData(params: any) {
-    const { getDomains } = await import('@utils/collections/domains');
-    const domains = await getDomains({ getAllVersions: false });
-    return domains.find((d) => d.data.id === params.id && d.collection === params.type) || null;
-  }
-
-  protected static createNotFoundResponse(): Response {
-    return new Response(null, {
-      status: 404,
-      statusText: 'Domain not found',
-    });
-  }
-}
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/language/index.astro b/eventcatalog/src/pages/docs/[type]/[id]/language/index.astro
deleted file mode 100644
index 75b9ab99e..000000000
--- a/eventcatalog/src/pages/docs/[type]/[id]/language/index.astro
+++ /dev/null
@@ -1,382 +0,0 @@
----
-import Footer from '@layouts/Footer.astro';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { getUbiquitousLanguageWithSubdomains } from '@utils/collections/domains';
-import { buildUrl } from '@utils/url-builder';
-import { ClientRouter } from 'astro:transitions';
-import * as LucideIcons from 'lucide-react';
-import { RectangleGroupIcon } from '@heroicons/react/24/outline';
-
-import { Page } from './_index.data';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-// Get data
-const props = await Page.getData(Astro);
-
-const pageTitle = `${props.collection} | ${props.data.name}`.replace(/^\w/, (c) => c.toUpperCase());
-const ubiquitousLanguageData = await getUbiquitousLanguageWithSubdomains(props);
-const ubiquitousLanguage = ubiquitousLanguageData.domain;
-const { subdomains, duplicateTerms } = ubiquitousLanguageData;
----
-
-<VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
-  <main class="flex sm:px-6 docs-layout h-full" data-pagefind-body data-pagefind-meta={`title:${pageTitle}`}>
-    <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-8 overflow-y-auto pt-6 pb-8 min-h-[50em]">
-        {/* Breadcrumb */}
-        <nav class="mb-4 flex items-center space-x-2 text-sm text-gray-500" aria-label="Breadcrumb">
-          <a
-            href={buildUrl(`/docs/${props.type}/${props.data.id}/${props.data.latestVersion}`)}
-            class="hover:text-gray-700 hover:underline flex items-center gap-2"
-          >
-            <RectangleGroupIcon className="h-4 w-4" />
-            {props.data.name}
-          </a>
-          <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
-            <path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7"></path>
-          </svg>
-          <span class="text-gray-900 flex items-center gap-2">
-            {
-              (() => {
-                const BookOpen = LucideIcons.BookOpen;
-                //@ts-ignore
-                return <BookOpen className="h-4 w-4" />;
-              })()
-            }
-            Ubiquitous Language Explorer
-          </span>
-        </nav>
-
-        {/* Title Section */}
-        <div class="relative border-b border-gray-200 mb-4 pb-4">
-          <div class="xl:flex xl:items-start xl:justify-between">
-            <div class="min-w-0 flex-1">
-              <div class="flex items-center gap-2">
-                <h1 class="text-xl font-bold leading-7 text-gray-900 sm:text-2xl xl:text-3xl">Ubiquitous Language Explorer</h1>
-              </div>
-              <p class="mt-2 text-sm text-gray-500">
-                Browse and discover ubiquitous language terms in the {props.data.name} domain{
-                  subdomains.length > 0 ? ' and its subdomains' : ''
-                }
-              </p>
-            </div>
-
-            <div class="mt-4 xl:mt-0 xl:ml-4 xl:flex-shrink-0">
-              <div class="relative w-full xl:w-96">
-                <input
-                  type="text"
-                  id="searchInput"
-                  placeholder="Search terms across domains..."
-                  class="w-full px-4 py-3 pl-10 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-blue-500 text-sm xl:px-5 xl:py-3.5 xl:pl-12"
-                />
-                <div class="absolute inset-y-0 left-0 pl-3 xl:pl-4 flex items-center pointer-events-none">
-                  <svg class="h-5 w-5 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                    <path
-                      stroke-linecap="round"
-                      stroke-linejoin="round"
-                      stroke-width="2"
-                      d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path>
-                  </svg>
-                </div>
-              </div>
-              <div class="mt-2 text-right">
-                <div class="text-sm text-gray-500" id="resultsCount">
-                  {/* This will be updated by JavaScript */}
-                </div>
-              </div>
-            </div>
-          </div>
-        </div>
-
-        {
-          !ubiquitousLanguage && subdomains.length === 0 && (
-            <div class="bg-yellow-50 border-l-4 border-yellow-400 p-4 my-4">
-              <p class="text-yellow-700">
-                This domain does not have any defined ubiquitous language terms yet. Consider adding some terms to help establish
-                a common vocabulary for your domain.
-              </p>
-            </div>
-          )
-        }
-
-        <div class="py-4 w-full min-h-[calc(100vh-10em)]">
-          {
-            (ubiquitousLanguage || subdomains.some((s) => s.ubiquitousLanguage)) && (
-              <div>
-                {/* Domain Language Section */}
-                {ubiquitousLanguage && (
-                  <div class="mb-8" data-domain-section="main">
-                    <h3 class="text-xl font-semibold text-gray-900 mb-4 border-b border-gray-200 pb-2">
-                      {props.data.name} Domain Language
-                    </h3>
-                    <div class="grid grid-cols-1 md:grid-cols-3 gap-4" data-terms-grid="main">
-                      {ubiquitousLanguage?.data?.dictionary?.map((term) => (
-                        <div
-                          class={`term-card block bg-white border rounded-lg p-6 transition-all duration-300 ease-in-out hover:shadow-md hover:border-primary focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-offset-primary focus:ring-white min-h-[12em] ${duplicateTerms.has(term.name.toLowerCase()) ? 'border-orange-300 bg-orange-50' : 'border-gray-200'}`}
-                          data-domain="main"
-                        >
-                          <div class="flex flex-col h-full space-y-8">
-                            {term.icon && (
-                              <div>
-                                {(() => {
-                                  const Icon = LucideIcons[term.icon as keyof typeof LucideIcons];
-                                  //@ts-ignore
-                                  return Icon ? <Icon className="w-6 h-6 text-primary" /> : null;
-                                })()}
-                              </div>
-                            )}
-                            <div>
-                              <h4
-                                class={`text-lg font-semibold transition-colors duration-300 ease-in-out group-hover:text-gray-300 ${duplicateTerms.has(term.name.toLowerCase()) ? 'text-orange-800' : 'text-gray-800'}`}
-                              >
-                                {term.name}
-                                {duplicateTerms.has(term.name.toLowerCase()) && (
-                                  <span class="ml-2 inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-orange-100 text-orange-800">
-                                    Duplicate
-                                  </span>
-                                )}
-                              </h4>
-                              <div class="term-content">
-                                <p class="summary-text text-gray-600 transition-colors duration-300 ease-in-out group-hover:text-gray-200 m-0 font-light text-sm mb-4">
-                                  {term.summary}
-                                </p>
-                                {term.description && (
-                                  <div class="prose prose-sm prose-p:my-3">
-                                    <a
-                                      href={buildUrl(`/docs/${props.type}/${props.data.id}/language/${term.id}`)}
-                                      class="show-more-text text-sm text-primary font-medium hover:underline"
-                                    >
-                                      Read more
-                                    </a>
-                                  </div>
-                                )}
-                              </div>
-                            </div>
-                          </div>
-                        </div>
-                      ))}
-                    </div>
-                    <div class="hidden domain-no-results text-center py-8 bg-gray-50 rounded-lg" data-domain-no-results="main">
-                      <h4 class="text-md font-medium text-gray-900">No matching terms in {props.data.name} domain</h4>
-                      <p class="mt-1 text-sm text-gray-500">Try adjusting your search terms.</p>
-                    </div>
-                  </div>
-                )}
-
-                {/* Subdomain Language Sections */}
-                {subdomains
-                  .filter((s) => s.ubiquitousLanguage)
-                  .map(({ subdomain, ubiquitousLanguage: subdomainUL }) => (
-                    <div class="mb-8" data-domain-section={subdomain.data.id}>
-                      <div class="flex justify-between items-center mb-4 border-b border-gray-200 pb-2">
-                        <h3 class="text-xl font-semibold text-gray-900">{subdomain.data.name} Subdomain Language</h3>
-                        <a
-                          href={buildUrl(`/docs/domains/${subdomain.data.id}/${subdomain.data.version}`)}
-                          class="text-sm text-primary hover:underline font-medium"
-                        >
-                          View Domain →
-                        </a>
-                      </div>
-                      <div class="grid grid-cols-1 md:grid-cols-3 gap-4" data-terms-grid={subdomain.data.id}>
-                        {subdomainUL?.data?.dictionary?.map((term) => (
-                          <div
-                            class={`term-card block bg-white border rounded-lg p-6 transition-all duration-300 ease-in-out hover:shadow-md hover:border-primary focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-offset-primary focus:ring-white min-h-[12em] ${duplicateTerms.has(term.name.toLowerCase()) ? 'border-orange-300 bg-orange-50' : 'border-gray-200'}`}
-                            data-domain={subdomain.data.id}
-                          >
-                            <div class="flex flex-col h-full space-y-8">
-                              {term.icon && (
-                                <div>
-                                  {(() => {
-                                    const Icon = LucideIcons[term.icon as keyof typeof LucideIcons];
-                                    //@ts-ignore
-                                    return Icon ? <Icon className="w-6 h-6 text-primary" /> : null;
-                                  })()}
-                                </div>
-                              )}
-                              <div>
-                                <h4
-                                  class={`text-lg font-semibold transition-colors duration-300 ease-in-out group-hover:text-gray-300 ${duplicateTerms.has(term.name.toLowerCase()) ? 'text-orange-800' : 'text-gray-800'}`}
-                                >
-                                  {term.name}
-                                  {duplicateTerms.has(term.name.toLowerCase()) && (
-                                    <span class="ml-2 inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-orange-100 text-orange-800">
-                                      Duplicate
-                                    </span>
-                                  )}
-                                </h4>
-                                <div class="term-content">
-                                  <p class="summary-text text-gray-600 transition-colors duration-300 ease-in-out group-hover:text-gray-200 m-0 font-light text-sm mb-4">
-                                    {term.summary}
-                                  </p>
-                                  {term.description && (
-                                    <div class="prose prose-sm prose-p:my-3">
-                                      <a
-                                        href={buildUrl(`/docs/${props.type}/${subdomain.data.id}/language/${term.id}`)}
-                                        class="show-more-text text-sm text-primary font-medium hover:underline"
-                                      >
-                                        Read more
-                                      </a>
-                                    </div>
-                                  )}
-                                </div>
-                              </div>
-                            </div>
-                          </div>
-                        ))}
-                      </div>
-                      <div
-                        class="hidden domain-no-results text-center py-8 bg-gray-50 rounded-lg"
-                        data-domain-no-results={subdomain.data.id}
-                      >
-                        <h4 class="text-md font-medium text-gray-900">No matching terms in {subdomain.data.name} subdomain</h4>
-                        <p class="mt-1 text-sm text-gray-500">Try adjusting your search terms.</p>
-                      </div>
-                    </div>
-                  ))}
-              </div>
-            )
-          }
-        </div>
-
-        <Footer />
-      </div>
-    </div>
-    <ClientRouter />
-  </main>
-
-  <script>
-    function initializeSearch() {
-      const searchInput = document.getElementById('searchInput');
-      const domainSections = document.querySelectorAll('[data-domain-section]');
-      const resultsCount = document.getElementById('resultsCount');
-
-      function updateResults() {
-        //@ts-ignore
-        const searchTerm = searchInput?.value.toLowerCase() || '';
-        let totalVisibleTerms = 0;
-        let totalTerms = 0;
-
-        // Handle search for each domain section
-        domainSections.forEach((section) => {
-          const domainId = section.getAttribute('data-domain-section');
-          const domainCards = section.querySelectorAll('.term-card');
-          const domainNoResults = section.querySelector(`[data-domain-no-results="${domainId}"]`);
-          let domainVisibleCount = 0;
-
-          domainCards.forEach((card) => {
-            totalTerms++;
-            const title = card.querySelector('h4')?.textContent?.toLowerCase() || '';
-            const description = card.querySelector('p')?.textContent?.toLowerCase() || '';
-            const matches = searchTerm === '' || title.includes(searchTerm) || description.includes(searchTerm);
-
-            card.classList.toggle('hidden', !matches);
-            if (matches) {
-              domainVisibleCount++;
-              totalVisibleTerms++;
-            }
-          });
-
-          // Show/hide domain-specific no results message
-          if (domainNoResults) {
-            if (searchTerm.trim() === '') {
-              domainNoResults.classList.add('hidden');
-            } else {
-              domainNoResults.classList.toggle('hidden', domainVisibleCount > 0);
-            }
-          }
-        });
-
-        // Update results count
-        if (resultsCount) {
-          resultsCount.textContent = `Showing ${totalVisibleTerms} terms`;
-        }
-      }
-
-      searchInput?.addEventListener('input', updateResults);
-
-      // Initialize results count
-      updateResults();
-    }
-
-    function initializeShowMore() {
-      const cards = document.querySelectorAll('.term-card');
-      cards.forEach((card) => {
-        const summary = card.querySelector('.summary-text');
-        if (summary) {
-          summary.classList.add('visible');
-        }
-      });
-    }
-
-    function highlightMatchingTerm() {
-      const urlParams = new URLSearchParams(window.location.search);
-      const termId = urlParams.get('id');
-
-      if (termId) {
-        const cards = document.querySelectorAll('.term-card');
-        cards.forEach((card) => {
-          const termName = card.querySelector('h3')?.textContent?.trim();
-          if (termName?.toLowerCase() === termId.toLowerCase()) {
-            // Add highlight class
-            card.classList.add('highlighted');
-            (card as HTMLElement).click();
-
-            setTimeout(() => {
-              // Scroll into view
-              card.scrollIntoView({ behavior: 'smooth', block: 'center' });
-            }, 300);
-          }
-        });
-      }
-    }
-
-    document.addEventListener('astro:page-load', () => {
-      initializeShowMore();
-      initializeSearch();
-      highlightMatchingTerm();
-    });
-
-    initializeShowMore();
-    initializeSearch();
-    highlightMatchingTerm();
-  </script>
-
-  <style is:global>
-    .term-card {
-      transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
-      min-height: 12em;
-    }
-
-    .summary-text {
-      opacity: 1;
-      max-height: unset;
-      display: block;
-    }
-
-    .description-text,
-    .term-card.expanded,
-    .term-card.expanded .show-more-text {
-      display: none;
-    }
-
-    .term-card.highlighted {
-      border-color: var(--color-primary);
-      box-shadow: 0 0 0 2px var(--color-primary);
-      animation: pulse 1s;
-    }
-
-    @keyframes pulse {
-      0%,
-      100% {
-        transform: scale(1);
-        box-shadow: 0 0 0 2px var(--color-primary);
-      }
-      50% {
-        transform: scale(1.01);
-        box-shadow: 0 0 0 4px var(--color-primary);
-      }
-    }
-  </style>
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/docs/_default-docs.mdx b/eventcatalog/src/pages/docs/_default-docs.mdx
deleted file mode 100644
index 403bb3633..000000000
--- a/eventcatalog/src/pages/docs/_default-docs.mdx
+++ /dev/null
@@ -1,25 +0,0 @@
-# **Welcome to EventCatalog**
-
-This open-source project is designed to help you and your teams bring discoverability and clarity to your event-driven architectures (EDA).
-
-This page can be replaced with your own content, but to help you get started, we have created a few guides and resources.
-
-<Tiles columns={3}>
-  <Tile icon="BookOpenIcon" href="https://eventcatalog.dev/docs/development/getting-started/introduction" title="Getting started with EventCatalog" description="How to get started with EventCatalog" />
-  <Tile icon="RectangleGroupIcon" href="https://eventcatalog.dev/docs/development/guides/domains/adding-domains" title="Creating domains" description="Learn how to create domains in your event catalog" />
-  <Tile icon="ServerIcon" href="https://eventcatalog.dev/docs/development/guides/services/adding-services" title="Creating services" description="Learn how to create services in your event catalog" />
-  <Tile icon="ChatBubbleLeftIcon" iconColor="text-blue-500" href="https://eventcatalog.dev/docs/development/guides/messages/commands/introduction" title="Creating commands" description="Learn how to create commands in your event catalog" />
-  <Tile icon="BoltIcon" iconColor="text-orange-500" href="https://eventcatalog.dev/docs/development/guides/messages/events/introduction" title="Creating events" description="Learn how to create events in your event catalog" />
-  <Tile icon="UserGroupIcon" iconColor="text-green-500" href="https://eventcatalog.dev/docs/owners" title="Assigning owners to resources" description="Learn how to assign owners to resources in your event catalog" />
-</Tiles>
-
-### **Join the community**
-
-Our project and community is growing fast. We have over 1000+ members in our [Discord community](https://discord.gg/3rjaZMmrAm).
-
-<Tiles columns={2}>
-  <Tile icon="UserGroupIcon" iconColor="text-green-500" href="https://discord.gg/3rjaZMmrAm" title="Join the Discord community" description="Join the community to get help and support" />
-  <Tile icon="StarIcon"  iconColor="text-yellow-500" href="https://github.com/event-catalog/eventcatalog/stargazers" title="Star EventCatalog on GitHub" description="If you like the project, please star it on GitHub to show your support ❤️" />
-</Tiles>
-
----
\ No newline at end of file
diff --git a/eventcatalog/src/pages/docs/custom/[...path].mdx.ts b/eventcatalog/src/pages/docs/custom/[...path].mdx.ts
deleted file mode 100644
index 29eee0097..000000000
--- a/eventcatalog/src/pages/docs/custom/[...path].mdx.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-// This file exposes the markdown for EventCatalog in the Url
-// For example http://localhost:3000/docs/events/OrderAmended/0.0.1 loads the Page and http://localhost:3000/docs/events/OrderAmended/0.0.1.md loads the markdown
-// This is used for the LLMs to load the markdown for the given item (llms.txt);
-
-import type { APIRoute, GetStaticPaths } from 'astro';
-import { getCollection } from 'astro:content';
-import config from '@config';
-import fs from 'fs';
-
-export const getStaticPaths = (async () => {
-  const docs = await getCollection('customPages');
-  const paths = docs.map((doc) => ({
-    params: { path: doc.id.replace('docs/', '') },
-    props: doc,
-    type: 'custom',
-  }));
-  return paths;
-}) satisfies GetStaticPaths;
-
-export const GET: APIRoute = async ({ params, props }) => {
-  // Just return empty array if LLMs are not enabled
-  if (!config.llmsTxt?.enabled) {
-    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
-  }
-
-  if (props.filePath) {
-    const file = fs.readFileSync(props.filePath, 'utf8');
-    return new Response(file, { status: 200 });
-  }
-
-  return new Response('Not found', { status: 404 });
-};
diff --git a/eventcatalog/src/pages/docs/custom/feature.astro b/eventcatalog/src/pages/docs/custom/feature.astro
deleted file mode 100644
index d9e18ac60..000000000
--- a/eventcatalog/src/pages/docs/custom/feature.astro
+++ /dev/null
@@ -1,165 +0,0 @@
----
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { BookOpenIcon, FileText } from 'lucide-react';
----
-
-<VerticalSideBarLayout title="Custom Documentation">
-  <div class="min-h-[calc(100vh-60px)] bg-white">
-    <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-16">
-      {/* Hero Section */}
-      <div class="grid grid-cols-1 lg:grid-cols-2 gap-12 items-center mb-16">
-        <div>
-          <div class="inline-flex items-center px-4 py-2 rounded-full bg-blue-100 text-blue-700 font-medium text-sm mb-6">
-            <FileText className="w-4 h-4 mr-2" />
-            New: Bring your documentation into EventCatalog
-          </div>
-          <h1 class="text-4xl font-bold text-gray-900 tracking-tight mb-4">
-            Document Everything. Share Knowledge. Build Better.
-          </h1>
-          <p class="text-xl text-gray-600 mb-8">
-            Add your own documentation to EventCatalog — from ADRs and system guides to runbooks and onboarding material. Connect
-            your knowledge to your architecture.
-          </p>
-          <div class="flex flex-col sm:flex-row gap-4 mb-8">
-            <a
-              href="https://demo.eventcatalog.dev/docs/custom/guides/creating-new-microservices/01-index"
-              target="_blank"
-              class="inline-flex items-center justify-center px-6 py-3 border border-transparent text-base font-medium rounded-lg text-white bg-blue-600 hover:bg-blue-700 transition-colors duration-150"
-            >
-              View the demo
-              <svg class="ml-2 w-4 h-4" viewBox="0 0 20 20" fill="currentColor">
-                <path
-                  fill-rule="evenodd"
-                  d="M10.293 3.293a1 1 0 011.414 0l6 6a1 1 0 010 1.414l-6 6a1 1 0 01-1.414-1.414L14.586 11H3a1 1 0 110-2h11.586l-4.293-4.293a1 1 0 010-1.414z"
-                  clip-rule="evenodd"></path>
-              </svg>
-            </a>
-            <a
-              href="https://www.eventcatalog.cloud"
-              target="_blank"
-              class="inline-flex items-center justify-center px-6 py-3 border border-gray-300 text-base font-medium rounded-lg text-gray-700 bg-white hover:bg-gray-50 transition-colors duration-150"
-            >
-              Try for free
-            </a>
-          </div>
-          <p class="text-sm text-gray-500">
-            Available with EventCatalog Starter or Scale plans
-            <a href="https://www.eventcatalog.dev/pricing" class="text-blue-600 font-medium block"
-              >Try free for 14 days, no credit card required</a
-            >
-          </p>
-        </div>
-
-        <div class="relative">
-          <div class="absolute -inset-4">
-            <div
-              class="w-full h-full max-w-full mx-auto opacity-30 blur-lg filter"
-              style="background: linear-gradient(90deg, #60A5FA 0%, #3B82F6 100%);"
-            >
-            </div>
-          </div>
-          <div class="relative">
-            <img
-              src="/images/custom-docs-placeholder.png"
-              alt="Custom Documentation Preview"
-              class="rounded-xl shadow-xl border border-gray-200"
-            />
-          </div>
-        </div>
-      </div>
-
-      {/* Features Section */}
-      <div class="grid grid-cols-1 md:grid-cols-3 gap-8">
-        <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-          <div class="w-12 h-12 bg-blue-100 rounded-lg flex items-center justify-center mb-4">
-            <svg class="w-6 h-6 text-blue-600" viewBox="0 0 24 24" fill="currentColor">
-              <path d="M14 2H6c-1.1 0-1.99.9-1.99 2L4 20c0 1.1.89 2 1.99 2H18c1.1 0 2-.9 2-2V8l-6-6zM6 20V4h7v5h5v11H6z"></path>
-            </svg>
-          </div>
-          <h3 class="text-lg font-semibold text-gray-900 mb-2">Centralized Knowledge</h3>
-          <p class="text-gray-600">
-            Keep architecture decisions, system guides, and runbooks in one place — easy to access, easy to trust.
-          </p>
-        </div>
-
-        <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-          <div class="w-12 h-12 bg-blue-100 rounded-lg flex items-center justify-center mb-4">
-            <svg class="w-6 h-6 text-blue-600" viewBox="0 0 24 24" fill="currentColor">
-              <path
-                d="M19 3H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm-5 14H7v-2h7v2zm3-4H7v-2h10v2zm0-4H7V7h10v2z"
-              ></path>
-            </svg>
-          </div>
-          <h3 class="text-lg font-semibold text-gray-900 mb-2">Rich Formatting</h3>
-          <p class="text-gray-600">
-            Use Markdown, diagrams, code blocks, and EventCatalog components to create structured, useful documentation.
-          </p>
-        </div>
-
-        <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-          <div class="w-12 h-12 bg-blue-100 rounded-lg flex items-center justify-center mb-4">
-            <svg class="w-6 h-6 text-blue-600" viewBox="0 0 24 24" fill="currentColor">
-              <path d="M18 2H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2zM6 4h5v8l-2.5-1.5L6 12V4z"
-              ></path>
-            </svg>
-          </div>
-          <h3 class="text-lg font-semibold text-gray-900 mb-2">Version Control</h3>
-          <p class="text-gray-600">Track changes and ensure your documentation grows alongside your system.</p>
-        </div>
-
-        <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-          <div class="w-12 h-12 bg-blue-100 rounded-lg flex items-center justify-center mb-4">
-            <svg class="w-6 h-6 text-blue-600" viewBox="0 0 24 24" fill="currentColor">
-              <path
-                d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z"
-              ></path>
-            </svg>
-          </div>
-          <h3 class="text-lg font-semibold text-gray-900 mb-2">Documentation Ownership</h3>
-          <p class="text-gray-600">Assign and track document owners, making it easy to find the right person in seconds.</p>
-        </div>
-
-        <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-          <div class="w-12 h-12 bg-blue-100 rounded-lg flex items-center justify-center mb-4">
-            <svg class="w-6 h-6 text-blue-600" viewBox="0 0 24 24" fill="currentColor">
-              <path d="M3 9h14V7H3v2zm0 4h14v-2H3v2zm0 4h14v-2H3v2zm16 0h2v-2h-2v2zm0-10v2h2V7h-2zm0 6h2v-2h-2v2z"></path>
-            </svg>
-          </div>
-          <h3 class="text-lg font-semibold text-gray-900 mb-2">Customizable Sidebars</h3>
-          <p class="text-gray-600">
-            Auto-generated and fully customizable navigation sidebars to organize your documentation perfectly.
-          </p>
-        </div>
-
-        <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-          <div class="w-12 h-12 bg-blue-100 rounded-lg flex items-center justify-center mb-4">
-            <svg class="w-6 h-6 text-blue-600" viewBox="0 0 24 24" fill="currentColor">
-              <path d="M20 2H4c-1.1 0-2 .9-2 2v18l4-4h14c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2zm0 14H6l-2 2V4h16v12z"></path>
-            </svg>
-          </div>
-          <h3 class="text-lg font-semibold text-gray-900 mb-2">EventCatalog Chat</h3>
-          <p class="text-gray-600">
-            Interact with your documentation using AI-powered chat to find answers quickly and efficiently.
-          </p>
-        </div>
-      </div>
-
-      {/* Bottom Link */}
-      <div class="mt-16 text-center">
-        <a
-          href="https://www.eventcatalog.dev/docs/development/guides/customize-sidebars/application-sidebar"
-          target="_blank"
-          class="text-sm text-gray-400 hover:text-gray-500 transition-colors duration-150"
-        >
-          Not ready for custom documentation? You can hide this feature in settings
-        </a>
-      </div>
-    </div>
-  </div>
-</VerticalSideBarLayout>
-
-<style>
-  .scroll-smooth {
-    scroll-behavior: smooth;
-  }
-</style>
diff --git a/eventcatalog/src/pages/docs/custom/index.astro b/eventcatalog/src/pages/docs/custom/index.astro
deleted file mode 100644
index 69453f315..000000000
--- a/eventcatalog/src/pages/docs/custom/index.astro
+++ /dev/null
@@ -1,241 +0,0 @@
----
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { Code } from 'astro-expressive-code/components';
-import { isCustomDocsEnabled } from '@utils/feature';
-
-// Example for folder structure
-const folderStructureExample = `my-catalog/
-  └── docs/
-      ├── getting-started/
-      │   ├── 01-introduction.mdx
-      │   └── 02-quick-start.mdx
-      ├── architecture-decisions/
-      │   ├── 01-what-are-architecture-decisions.mdx
-      │   ├── 02-how-to-create-architecture-decisions.mdx
-      │   ├── published/
-      │   │   ├── 01-adr-001-event-driven.mdx
-      │   │   └── 02-adr-002-api-first.mdx
-      │   └── drafts/
-      │       ├── 01-adr-003-microservices.mdx
-      │       └── 02-adr-004-monolith.mdx
-      └`;
-// Example MDX file content
-const mdxFileExample = `---
-title: Getting Started
-summary: How to get started with our event-driven architecture
----
-
-# Getting Started with our Event-Driven Architecture
-
-This guide will help you understand how our services communicate using events.
-
-## Prerequisites
-
-- Understanding of basic messaging patterns
-- Node.js installed on your machine
-
-## Key Concepts
-
-Events are the backbone of our architecture. They represent facts that have happened in our system.
-`;
-
-// Example config file
-const configExample = `// eventcatalog.config.js
-  
-module.exports = {
-  // Your existing config...
-  
-  customDocs: {
-    sidebar: [
-      {
-        label: 'Getting Started',
-        badge: {
-          text: 'New', color: 'green'
-        },
-        collapsed: false,
-        items: [
-          { label: 'Introduction', slug: 'getting-started/01-introduction' },
-          { label: 'Quick Start', slug: 'getting-started/02-quick-start' }
-        ]
-      },
-      {
-        label: 'Architecture Decisions',
-        badge: {
-          text: 'New', color: 'green'
-        },
-        collapsed: true,
-        items: [
-          { 
-            label: 'What are Architecture Decisions?', 
-            slug: 'architecture-decisions/01-what-are-architecture-decisions' 
-          },
-          { 
-            label: 'How to Create Architecture Decisions', 
-            slug: 'architecture-decisions/02-how-to-create-architecture-decisions' 
-          },
-          {
-            label: 'Published ADRs',
-            autogenerated: { 
-              directory: 'architecture-decisions/published', 
-              collapsed: true 
-            }
-          },
-          {
-            label: 'Draft ADRs',
-            autogenerated: { 
-              directory: 'architecture-decisions/drafts', 
-              collapsed: true 
-            }
-          }
-        ]
-      }
-    ]
-  }
-}`;
-
-if (!isCustomDocsEnabled()) {
-  return Astro.redirect('/docs/custom/feature');
-}
----
-
-<VerticalSideBarLayout title="Custom Documentation">
-  <body class="min-h-screen font-inter">
-    <main class="container px-8 lg:px-8 mx-auto py-8 max-w-[80em]">
-      <div class="mb-12">
-        <div class="flex flex-col md:flex-row md:items-center md:justify-between gap-6">
-          <div>
-            <div class="flex flex-wrap items-center gap-3 mb-3">
-              <h1 class="text-4xl font-semibold text-gray-900 font-inter">Custom Documentation</h1>
-              <div
-                class="inline-flex items-center px-3 py-1.5 rounded-full text-xs font-medium bg-purple-100 text-purple-800 border border-purple-200 shadow-sm"
-              >
-                Pro feature
-              </div>
-            </div>
-            <p class="text-base mb-0 text-gray-600 max-w-3xl">
-              Add custom documentation to EventCatalog to create a unified source of truth for your team. Document your
-              architecture decisions, patterns, and guidelines.
-            </p>
-          </div>
-          <div class="flex space-x-4 shrink-0">
-            <a
-              href="https://www.eventcatalog.dev/docs/custom-documentation"
-              class="inline-flex items-center justify-center px-5 py-2 border border-gray-300 text-sm font-medium rounded-md text-gray-700 bg-white hover:bg-gray-50"
-            >
-              Read documentation &rarr;
-            </a>
-            {
-              !isCustomDocsEnabled() && (
-                <a
-                  href="https://www.eventcatalog.dev/pro/trial"
-                  class="inline-flex items-center justify-center px-5 py-2 border border-transparent text-sm font-medium rounded-md text-white bg-gradient-to-r from-purple-500 to-purple-700 hover:from-purple-600 hover:to-purple-800 shadow-sm"
-                >
-                  Start 14-day trial
-                </a>
-              )
-            }
-          </div>
-        </div>
-      </div>
-
-      <h2 class="text-2xl font-semibold mb-2 text-gray-900">Setup Guide</h2>
-      <p class="text-gray-600 mb-8 max-w-3xl">
-        Custom documentation let's you bring any documentation into EventCatalog. This is useful for documenting your architecture
-        decisions, patterns, and guidelines. Follow these steps to get started:
-      </p>
-
-      <div class="space-y-10 mb-12">
-        <div class="bg-white p-6 rounded-lg shadow-sm border border-gray-200">
-          <div class="flex items-start gap-4">
-            <div
-              class="inline-flex items-center justify-center w-8 h-8 rounded-full bg-blue-100 text-blue-600 text-lg font-medium shrink-0 mt-1"
-            >
-              1
-            </div>
-            <div class="w-full">
-              <h3 class="text-xl font-semibold text-gray-900 mb-3">Create the content structure</h3>
-              <p class="text-gray-600 mb-4">Create a folder structure in your directory to organize your documentation.</p>
-              <Code code={folderStructureExample} lang="bash" frame="terminal" />
-            </div>
-          </div>
-        </div>
-
-        <div class="bg-white p-6 rounded-lg shadow-sm border border-gray-200">
-          <div class="flex items-start gap-4">
-            <div
-              class="inline-flex items-center justify-center w-8 h-8 rounded-full bg-blue-100 text-blue-600 text-lg font-medium shrink-0 mt-1"
-            >
-              2
-            </div>
-            <div class="w-full">
-              <h3 class="text-xl font-semibold text-gray-900 mb-3">Add MDX files</h3>
-              <p class="text-gray-600 mb-4">Create MDX files with frontmatter and markdown content.</p>
-              <Code code={mdxFileExample} lang="mdx" frame="terminal" />
-            </div>
-          </div>
-        </div>
-
-        <div class="bg-white p-6 rounded-lg shadow-sm border border-gray-200">
-          <div class="flex items-start gap-4">
-            <div
-              class="inline-flex items-center justify-center w-8 h-8 rounded-full bg-blue-100 text-blue-600 text-lg font-medium shrink-0 mt-1"
-            >
-              3
-            </div>
-            <div class="w-full">
-              <h3 class="text-xl font-semibold text-gray-900 mb-3">Update your eventcatalog.config.js file</h3>
-              <p class="text-gray-600 mb-4">
-                Add the customDocs configuration to your eventcatalog.config.js file to define your sidebar structure.
-              </p>
-              <Code code={configExample} lang="js" frame="terminal" />
-              <p class="text-gray-600 mt-4">This configuration defines the sidebar structure for your custom documentation:</p>
-              <ul class="list-disc list-inside text-gray-600 mt-2 ml-2 space-y-1">
-                <li>
-                  <strong>label</strong>: The display name for each sidebar section
-                </li>
-                <li>
-                  <strong>badge</strong>: Optional badge to highlight new sections
-                </li>
-                <li>
-                  <strong>collapsed</strong>: Whether the section is collapsed by default
-                </li>
-                <li>
-                  <strong>autogenerated</strong>: Automatically generate sidebar items from a directory
-                </li>
-                <li>
-                  <strong>slug</strong>: Direct link to a specific page
-                </li>
-              </ul>
-            </div>
-          </div>
-        </div>
-
-        <div class="bg-white p-6 rounded-lg shadow-sm border border-gray-200">
-          <div class="flex items-start gap-4">
-            <div
-              class="inline-flex items-center justify-center w-8 h-8 rounded-full bg-blue-100 text-blue-600 text-lg font-medium shrink-0 mt-1"
-            >
-              4
-            </div>
-            <div class="w-full">
-              <h3 class="text-xl font-semibold text-gray-900 mb-3">Restart EventCatalog</h3>
-              <p class="text-gray-600 mb-4">
-                After configuring your documentation, restart EventCatalog to see your custom documentation.
-              </p>
-              <div class="mb-4">
-                <Code code="npm run dev" lang="bash" frame="terminal" />
-              </div>
-              <p class="text-gray-600 mb-4">
-                Once restarted, you'll see your custom documentation displayed with the sidebar structure you defined:
-              </p>
-              <div class="border border-gray-200 rounded-lg overflow-hidden">
-                <img src="/images/custom-docs-placeholder.png" alt="Example of custom documentation interface" class="w-full" />
-              </div>
-            </div>
-          </div>
-        </div>
-      </div>
-    </main>
-  </body>
-</VerticalSideBarLayout>
-)
diff --git a/eventcatalog/src/pages/docs/index.astro b/eventcatalog/src/pages/docs/index.astro
deleted file mode 100644
index 63b648833..000000000
--- a/eventcatalog/src/pages/docs/index.astro
+++ /dev/null
@@ -1,33 +0,0 @@
----
-import Footer from '@layouts/Footer.astro';
-import components from '@components/MDX/page-components';
-import mdxComponents from '@components/MDX/components';
-import { getIndexPage } from '@utils/pages';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { render } from 'astro:content';
-
-const page = await getIndexPage();
-let CustomContent = null;
-
-const props = Astro.props;
-
-if (page) {
-  const { Content } = await render(page);
-  CustomContent = Content;
-} else {
-  CustomContent = await import('./_default-docs.mdx').then((mod) => mod.default);
-}
----
-
-<VerticalSideBarLayout title="EventCatalog">
-  <main class="flex sm:px-8 docs-layout h-full">
-    <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-8 overflow-y-auto py-8">
-        <div class="prose prose-md w-full !max-w-none">
-          <CustomContent components={{ ...components, ...mdxComponents(props) }} />
-        </div>
-        <Footer />
-      </div>
-    </div>
-  </main>
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/docs/llm/llms-full.txt.ts b/eventcatalog/src/pages/docs/llm/llms-full.txt.ts
deleted file mode 100644
index 60f12507b..000000000
--- a/eventcatalog/src/pages/docs/llm/llms-full.txt.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import { getCollection, type CollectionEntry } from 'astro:content';
-import type { APIRoute } from 'astro';
-import fs from 'fs';
-import { isCustomDocsEnabled } from '@utils/feature';
-import { addSchemaToMarkdown } from '@utils/llms';
-
-type AllowedCollections =
-  | 'events'
-  | 'commands'
-  | 'queries'
-  | 'services'
-  | 'domains'
-  | 'teams'
-  | 'users'
-  | 'customPages'
-  | 'channels'
-  | 'entities'
-  | 'flows'
-  | 'containers';
-
-const events = await getCollection('events');
-const commands = await getCollection('commands');
-const queries = await getCollection('queries');
-const services = await getCollection('services');
-const domains = await getCollection('domains');
-const teams = await getCollection('teams');
-const users = await getCollection('users');
-const entities = await getCollection('entities');
-const channels = await getCollection('channels');
-const flows = await getCollection('flows');
-const containers = await getCollection('containers');
-const customDocs = await getCollection('customPages');
-
-import { isLLMSTxtEnabled } from '@utils/feature';
-
-export const GET: APIRoute = async ({ params, request }) => {
-  if (!isLLMSTxtEnabled()) {
-    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
-  }
-
-  const resources: CollectionEntry<AllowedCollections>[] = [
-    ...events,
-    ...commands,
-    ...queries,
-    ...services,
-    ...domains,
-    ...teams,
-    ...users,
-    ...entities,
-    ...channels,
-    ...containers,
-    ...flows,
-  ];
-
-  if (isCustomDocsEnabled()) {
-    resources.push(...(customDocs as CollectionEntry<AllowedCollections>[]));
-  }
-
-  const content = resources
-    .map((item) => {
-      if (!item.filePath) return '';
-
-      let file = fs.readFileSync(item.filePath, 'utf8');
-
-      try {
-        // Try and add the schemas to the resource
-        // @ts-ignore
-        file = addSchemaToMarkdown(item, file);
-      } catch (error) {
-        // just skip the resource if it has no schema
-      }
-
-      return file;
-    })
-    .join('\n');
-
-  return new Response(content, {
-    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-  });
-};
diff --git a/eventcatalog/src/pages/docs/llm/llms-services.txt.ts b/eventcatalog/src/pages/docs/llm/llms-services.txt.ts
deleted file mode 100644
index 91c458983..000000000
--- a/eventcatalog/src/pages/docs/llm/llms-services.txt.ts
+++ /dev/null
@@ -1,81 +0,0 @@
-import { type CollectionEntry } from 'astro:content';
-import type { APIRoute } from 'astro';
-
-import { getServices } from '@utils/collections/services';
-
-const services = await getServices();
-
-export const GET: APIRoute = async ({ params, request }) => {
-  const url = new URL(request.url);
-  const baseUrl = process.env.LLMS_TXT_BASE_URL || `${url.origin}`;
-
-  const formatServiceWithLinks = (service: CollectionEntry<'services'>) => {
-    const sends = service.data.sends as unknown as CollectionEntry<'events'>[];
-    const receives = service.data.receives as unknown as CollectionEntry<'events'>[];
-    const writesTo = service.data.writesTo as unknown as CollectionEntry<'containers'>[];
-    const readsFrom = service.data.readsFrom as unknown as CollectionEntry<'containers'>[];
-
-    const sendsList =
-      sends.length > 0
-        ? sends
-            .map(
-              (send) =>
-                `- [${send.data.name} - ${send.data.version}](${baseUrl}/docs/events/${send.data.id}/${send.data.version}.mdx) - ${send.data.summary?.trim() || ''}`
-            )
-            .join('\n')
-        : '- Does not send any messages';
-
-    const receivesList =
-      receives.length > 0
-        ? receives
-            .map(
-              (receive) =>
-                `- [${receive.data.name} - ${receive.data.version}](${baseUrl}/docs/events/${receive.data.id}/${receive.data.version}.mdx) - ${receive.data.summary?.trim() || ''}`
-            )
-            .join('\n')
-        : '- Does not receive any messages';
-
-    const writesToList =
-      writesTo.length > 0
-        ? writesTo
-            .map(
-              (write) =>
-                `- [${write.data.name} - ${write.data.version}](${baseUrl}/docs/containers/${write.data.id}/${write.data.version}.mdx) - ${write.data.summary?.trim() || ''}`
-            )
-            .join('\n')
-        : '- Does not write to any containers';
-
-    const readsFromList =
-      readsFrom.length > 0
-        ? readsFrom
-            .map(
-              (read) =>
-                `- [${read.data.name} - ${read.data.version}](${baseUrl}/docs/containers/${read.data.id}/${read.data.version}.mdx) - ${read.data.summary?.trim() || ''}`
-            )
-            .join('\n')
-        : '- Does not read from any containers';
-
-    return `## [${service.data.name} - ${service.data.version}](${baseUrl}/docs/services/${service.data.id}/${service.data.version}.mdx)
-
-${service.data.summary?.trim() || ''}
-
-### Sends
-${sendsList}
-
-### Receives
-${receivesList}
-
-### Writes to
-${writesToList}
-
-### Reads from
-${readsFromList}
-`;
-  };
-
-  const content = ['# Services\n', services.map((item) => formatServiceWithLinks(item)).join('\n')].join('\n');
-
-  return new Response(content, {
-    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-  });
-};
diff --git a/eventcatalog/src/pages/docs/llm/llms.txt.ts b/eventcatalog/src/pages/docs/llm/llms.txt.ts
deleted file mode 100644
index b53289a73..000000000
--- a/eventcatalog/src/pages/docs/llm/llms.txt.ts
+++ /dev/null
@@ -1,135 +0,0 @@
-import { getCollection } from 'astro:content';
-import config from '@config';
-import type { APIRoute } from 'astro';
-
-import { isCustomDocsEnabled } from '@utils/feature';
-import { getUbiquitousLanguage } from '@utils/collections/domains';
-
-const events = await getCollection('events');
-const commands = await getCollection('commands');
-const queries = await getCollection('queries');
-
-const services = await getCollection('services');
-const domains = await getCollection('domains');
-
-const teams = await getCollection('teams');
-const users = await getCollection('users');
-
-const flows = await getCollection('flows');
-const channels = await getCollection('channels');
-const containers = await getCollection('containers');
-
-const entities = await getCollection('entities');
-
-const customDocs = await getCollection('customPages');
-
-const ubiquitousLanguages: Record<string, { id: string; version: string; properties: any }[]> = {};
-
-for (const domain of domains) {
-  const ubiquitousLanguagesForDomain = await getUbiquitousLanguage(domain);
-  if (ubiquitousLanguagesForDomain.length > 0) {
-    ubiquitousLanguages[domain.id] = ubiquitousLanguagesForDomain.map((item) => ({
-      id: domain.id,
-      version: domain.data.version,
-      properties: item.data.dictionary,
-    }));
-  }
-}
-
-// Render the Ubiquitous Languages section
-const renderUbiquitousLanguages = (baseUrl: string) => {
-  return Object.entries(ubiquitousLanguages)
-    .map(([domainId, items]) => {
-      const domainName = domains.find((domain) => domain.id === domainId)?.data.name || domainId;
-      const itemsList = items
-        .map((item) => {
-          // @ts-ignore
-          const propertiesList = Object.entries(item.properties)
-            .map(
-              ([key, value]: any) =>
-                `    - [${value.name}: - ${value.summary}](${baseUrl}/docs/domains/${domainId.split('-')[0]}/language.mdx)`
-            )
-            .join('\n');
-          return propertiesList;
-        })
-        .join('\n');
-      return `- ${domainName} Domain\n${itemsList}`;
-    })
-    .join('\n');
-};
-
-// render the entities from the domain list
-const renderEntities = (baseUrl: string) => {
-  const domainsWithEntities = domains.filter((domain) => domain.data.entities?.length && domain.data.entities.length > 0);
-
-  if (domainsWithEntities.length === 0) {
-    return '';
-  }
-
-  return domainsWithEntities
-    .map((domain) => {
-      const entitiesList = domain.data.entities
-        ?.map((entity) => {
-          const entityItem = entities.find((e) => e.data.id === entity.id);
-          return `    - [${entityItem?.data.name}](${baseUrl}/docs/entities/${entityItem?.data.id}/${entityItem?.data.version}.mdx) - ${entityItem?.data.summary}`;
-        })
-        .join('\n');
-      return `- ${domain.data.name} Domain\n${entitiesList || ''}`;
-    })
-    .join('\n');
-};
-
-export const GET: APIRoute = async ({ params, request }) => {
-  const url = new URL(request.url);
-  const baseUrl = process.env.LLMS_TXT_BASE_URL || `${url.origin}`;
-
-  const formatVersionedItem = (item: any, type: string, extraParams?: string | string[]) => {
-    const params = Array.isArray(extraParams) ? extraParams.join('&') : extraParams || '';
-    return `- [${item.data.name} - ${item.data.id} - ${item.data.version} ${params ? `- ${params}` : ''}](${baseUrl}/docs/${type}/${item.data.id}/${item.data.version}.mdx) ${item.data.summary ? `- ${item.data.summary}` : ''}`;
-  };
-
-  const formatSimpleItem = (item: any, type: string) =>
-    `- [${item.id.replace('.mdx', '')}](${baseUrl}/docs/${type}/${item.data.id}.mdx) - ${item.data.name}`;
-
-  const formatCustomDoc = (item: any, route: string) =>
-    `- [${item.data.title}](${baseUrl}/${route}/${item.id.replace('docs\/', '')}.mdx) - ${item.data.summary || ''}`;
-
-  const content = [
-    `# ${config.organizationName} EventCatalog Documentation\n`,
-    `> ${config.tagline}\n`,
-    '## Events',
-    events.map((item) => formatVersionedItem(item, 'events')).join(''),
-    '\n## Commands',
-    commands.map((item) => formatVersionedItem(item, 'commands')).join(''),
-    '\n## Queries',
-    queries.map((item) => formatVersionedItem(item, 'queries')).join(''),
-    '\n## Services',
-    services.map((item) => formatVersionedItem(item, 'services')).join(''),
-    '\n## Domains',
-    domains.map((item) => formatVersionedItem(item, 'domains')).join(''),
-    '\n## Flows',
-    flows.map((item) => formatVersionedItem(item, 'flows')).join('\n'),
-    '\n## Channels',
-    channels
-      .map((item) =>
-        formatVersionedItem(item, 'channels', item.data.protocols?.map((protocol) => `protocol - ${protocol}`).join('&'))
-      )
-      .join(''),
-    ...(Object.keys(ubiquitousLanguages).length > 0 ? ['## Ubiquitous Language', renderUbiquitousLanguages(baseUrl)] : []),
-    '\n## Containers (Databases, External Systems)',
-    containers.map((item) => formatVersionedItem(item, 'containers')).join('\n'),
-    '\n## Entities',
-    renderEntities(baseUrl),
-    '\n## Teams',
-    teams.map((item) => formatSimpleItem(item, 'teams')).join('\n'),
-    '\n## Users',
-    users.map((item) => formatSimpleItem(item, 'users')).join('\n'),
-    ...(isCustomDocsEnabled()
-      ? ['\n## Custom Docs', customDocs.map((item) => formatCustomDoc(item, 'docs/custom')).join('\n')]
-      : []),
-  ].join('\n');
-
-  return new Response(content, {
-    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-  });
-};
diff --git a/eventcatalog/src/pages/docs/llm/schemas.txt.ts b/eventcatalog/src/pages/docs/llm/schemas.txt.ts
deleted file mode 100644
index 4323b98c9..000000000
--- a/eventcatalog/src/pages/docs/llm/schemas.txt.ts
+++ /dev/null
@@ -1,86 +0,0 @@
-import { getCollection } from 'astro:content';
-import config from '@config';
-import type { APIRoute } from 'astro';
-import type { CollectionEntry } from 'astro:content';
-import { getSpecificationsForService } from '@utils/collections/services';
-import { isEventCatalogScaleEnabled } from '@utils/feature';
-
-const events = await getCollection('events');
-const commands = await getCollection('commands');
-const queries = await getCollection('queries');
-const services = await getCollection('services');
-
-type ServiceWithSchema = {
-  collection: string;
-  id: string;
-  version: string;
-  specification: string;
-  summary: string;
-};
-
-const servicesWithSchemas = services.filter((service) => getSpecificationsForService(service).length > 0);
-
-const servicesWithSchemasFlat = servicesWithSchemas.reduce<ServiceWithSchema[]>((acc, service) => {
-  return [
-    ...acc,
-    ...getSpecificationsForService(service).map((specification) => ({
-      collection: 'services',
-      id: service.data.id,
-      version: service.data.version,
-      specification: specification.type,
-      summary: service.data.summary?.trim() || '',
-    })),
-  ];
-}, []) as ServiceWithSchema[];
-
-const messageHasSchema = (message: CollectionEntry<'events' | 'commands' | 'queries'>) => {
-  return message.data.schemaPath;
-};
-
-export const GET: APIRoute = async ({ params, request }) => {
-  if (!isEventCatalogScaleEnabled()) {
-    return new Response(
-      JSON.stringify({
-        error: 'feature_not_available_on_server',
-        message: 'Schema API is not enabled for this deployment and supported in EventCatalog Scale.',
-      }),
-      { status: 501, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' } }
-    );
-  }
-
-  const url = new URL(request.url);
-  const baseUrl = process.env.LLMS_TXT_BASE_URL || `${url.origin}`;
-
-  const formatVersionedItem = (item: any, type: string, extraParams?: string | string[]) => {
-    return `- [${item.data.name} - ${item.data.id} - ${item.data.version}](${baseUrl}/api/schemas/${type}/${item.data.id}/${item.data.version})} ${item.data.summary ? `- ${item.data.summary.trim()}` : ''}`;
-  };
-
-  const formatServiceWithSchema = (item: ServiceWithSchema) => {
-    return `- [${item.id} - ${item.version} - ${item.specification} specification](${baseUrl}/api/schemas/${item.collection}/${item.id}/${item.version}/${item.specification}) ${item.summary ? `- Specification for ${item.summary}` : ''}`;
-  };
-
-  const content = [
-    `# ${config.organizationName} EventCatalog Schemas`,
-    `List of schemas for events, commands, queries, and services in EventCatalog.`,
-    '',
-    `## Events\n${events
-      .filter(messageHasSchema)
-      .map((item) => formatVersionedItem(item, 'events'))
-      .join('\n')}`,
-    '',
-    `## Commands\n${commands
-      .filter(messageHasSchema)
-      .map((item) => formatVersionedItem(item, 'commands'))
-      .join('\n')}`,
-    '',
-    `## Queries\n${queries
-      .filter(messageHasSchema)
-      .map((item) => formatVersionedItem(item, 'queries'))
-      .join('\n')}`,
-    '',
-    `## Services\n${servicesWithSchemasFlat.map((item: any) => formatServiceWithSchema(item)).join('\n')}`,
-  ].join('\n');
-  return new Response(content, {
-    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-  });
-};
diff --git a/eventcatalog/src/pages/docs/teams/[id].md.ts b/eventcatalog/src/pages/docs/teams/[id].md.ts
deleted file mode 100644
index 7ad407f04..000000000
--- a/eventcatalog/src/pages/docs/teams/[id].md.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-// This file exposes the markdown for EventCatalog in the Url
-// For example http://localhost:3000/docs/events/OrderAmended/0.0.1 loads the Page and http://localhost:3000/docs/events/OrderAmended/0.0.1.md loads the markdown
-// This is used for the LLMs to load the markdown for the given item (llms.txt);
-
-import type { APIRoute } from 'astro';
-import { getCollection } from 'astro:content';
-import config from '@config';
-import fs from 'fs';
-
-const teams = await getCollection('teams');
-
-export async function getStaticPaths() {
-  // Just return empty array if LLMs are not enabled
-  if (!config.llmsTxt?.enabled) {
-    return [];
-  }
-
-  return teams.map((team) => ({
-    params: { type: 'teams', id: team.data.id },
-    props: { content: team },
-  }));
-}
-
-export const GET: APIRoute = async ({ params, props }) => {
-  // Just return empty array if LLMs are not enabled
-  if (!config.llmsTxt?.enabled) {
-    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
-  }
-
-  if (props?.content?.filePath) {
-    const file = fs.readFileSync(props.content.filePath, 'utf8');
-    return new Response(file, { status: 200 });
-  }
-
-  return new Response('Not found', { status: 404 });
-};
diff --git a/eventcatalog/src/pages/docs/teams/[id]/_index.data.ts b/eventcatalog/src/pages/docs/teams/[id]/_index.data.ts
deleted file mode 100644
index 9246a5168..000000000
--- a/eventcatalog/src/pages/docs/teams/[id]/_index.data.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-// pages/teams/[id]/index.page.ts
-import { isSSR } from '@utils/feature';
-import { HybridPage } from '@utils/page-loaders/hybrid-page';
-
-export class Page extends HybridPage {
-  static get prerender(): boolean {
-    return !isSSR();
-  }
-
-  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
-    if (isSSR()) {
-      return [];
-    }
-
-    const { getTeams } = await import('@utils/teams');
-    const teams = await getTeams();
-
-    return teams.map((team) => ({
-      params: { id: team.data.id },
-      props: team,
-    }));
-  }
-
-  protected static async fetchData(params: any) {
-    const { id } = params;
-
-    if (!id) {
-      return null;
-    }
-
-    const { getTeams } = await import('@utils/teams');
-    const teams = await getTeams();
-
-    // Find the specific team by id
-    const team = teams.find((t) => t.data.id === id);
-
-    return team || null;
-  }
-
-  protected static createNotFoundResponse(): Response {
-    return new Response(null, {
-      status: 404,
-      statusText: 'Team not found',
-    });
-  }
-}
diff --git a/eventcatalog/src/pages/docs/teams/[id]/index.astro b/eventcatalog/src/pages/docs/teams/[id]/index.astro
deleted file mode 100644
index d1ee91083..000000000
--- a/eventcatalog/src/pages/docs/teams/[id]/index.astro
+++ /dev/null
@@ -1,176 +0,0 @@
----
-import components from '@components/MDX/components';
-
-// SideBars
-import { getEntry, render } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import OwnersList from '@components/Lists/OwnersList';
-import PillListFlat from '@components/Lists/PillListFlat';
-import EnvelopeIcon from '@heroicons/react/16/solid/EnvelopeIcon';
-import { buildUrl } from '@utils/url-builder';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { Page } from './_index.data';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-// Get data
-const props = await Page.getData(Astro);
-
-const { Content } = await render(props);
-
-const membersRaw = props.data.members || [];
-const members = (await Promise.all(membersRaw.map((m: CollectionEntry<'teams'>) => getEntry(m)))).filter(Boolean);
-
-const domains = props.data.ownedDomains as CollectionEntry<'domains'>[];
-const services = props.data.ownedServices as CollectionEntry<'services'>[];
-const events = props.data.ownedEvents as CollectionEntry<'events'>[];
-const commands = props.data.ownedCommands as CollectionEntry<'commands'>[];
-const queries = props.data.ownedQueries as CollectionEntry<'queries'>[];
-
-const membersList = members.map((o) => ({
-  label: o.data.name,
-  type: o.collection,
-  badge: o.collection === 'users' ? o.data.role : 'Team',
-  collection: o.collection,
-  avatarUrl: o.collection === 'users' ? o.data.avatarUrl : '',
-  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
-}));
-
-const ownedDomainsList = domains.map((p) => ({
-  label: `${p.data.name}`,
-  collection: p.collection,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-  tag: `v${p.data.version}`,
-}));
-
-const ownedServicesList = services.map((p) => ({
-  label: `${p.data.name}`,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-  collection: p.collection,
-  tag: `v${p.data.version}`,
-}));
-
-const ownedMessagesList = [...events, ...commands, ...queries].map((p) => ({
-  label: `${p.data.name}`,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-  color: p.collection === 'events' ? 'orange' : 'blue',
-  collection: p.collection,
-  tag: `v${p.data.version}`,
-}));
-
-const pageTitle = `Team | ${props.data.name}`;
----
-
-<VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
-  <main class="flex sm:px-8 docs-layout h-full" data-pagefind-body data-pagefind-meta={`title:${pageTitle}`}>
-    <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-8 overflow-y-auto py-8">
-        <div class="border-b border-gray-200 pb-4">
-          <div class="flex justify-start">
-            <div class="flex flex-col justify-between space-y-2">
-              <div>
-                <h2 class="text-4xl font-bold">{props.data.name} <span class="text-gray-300">(Team)</span></h2>
-              </div>
-              <div class="space-y-2">
-                {
-                  props.data.email && (
-                    <div class="flex space-x-1 items-center text-xs text-gray-500 font-bold hover:underline hover:text-primary">
-                      <EnvelopeIcon className="w-4 h-4 text-purple-400" />
-                      <a href={`mailto:${props.data.email}`}>Email</a>
-                    </div>
-                  )
-                }
-                {
-                  props.data.slackDirectMessageUrl && (
-                    <div class="flex space-x-1 items-center text-xs text-gray-500 font-bold hover:underline hover:text-primary">
-                      <img src={buildUrl('/slack-icon.svg', true)} class="w-4 h-3" />
-                      <a href={`${props.data.slackDirectMessageUrl}`}>Send DM on Slack</a>
-                    </div>
-                  )
-                }
-                {
-                  props.data.msTeamsDirectMessageUrl && (
-                    <div class="flex space-x-1 items-center text-xs text-gray-500 font-bold hover:underline hover:text-primary">
-                      <img src={buildUrl('/icons/ms-teams.svg', true)} class="w-4 h-4" />
-                      <a href={`${props.data.msTeamsDirectMessageUrl}`} target="_blank" rel="noopener noreferrer">
-                        Send DM on Teams
-                      </a>
-                    </div>
-                  )
-                }
-              </div>
-            </div>
-          </div>
-          <h2 class="text-xl py-2 text-gray-500">{props.data.summary}</h2>
-        </div>
-        <div class="border-b border-gray-200" data-pagefind-ignore>
-          <div class="mx-auto max-w-7xl px-6 lg:px-8">
-            <div class="mx-auto max-w-2xl lg:max-w-none">
-              <dl
-                class="hidden lg:grid grid-cols-1 gap-0.5 overflow-hidden rounded-2xl text-center sm:grid-cols-4 lg:grid-cols-4"
-              >
-                <div class="flex flex-col p-8">
-                  <dt class="text-sm font-semibold leading-6 text-gray-600"># owned domains</dt>
-                  <dd class="order-first text-3xl font-semibold tracking-tight text-gray-900">{ownedDomainsList.length}</dd>
-                </div>
-                <div class="flex flex-col p-8">
-                  <dt class="text-sm font-semibold leading-6 text-gray-600"># owned services</dt>
-                  <dd class="order-first text-3xl font-semibold tracking-tight text-gray-900">{ownedServicesList.length}</dd>
-                </div>
-                <div class="flex flex-col p-8">
-                  <dt class="text-sm font-semibold leading-6 text-gray-600"># owned messages</dt>
-                  <dd class="order-first text-3xl font-semibold tracking-tight text-gray-900">{ownedMessagesList.length}</dd>
-                </div>
-                <div class="flex flex-col p-8">
-                  <dt class="text-sm font-semibold leading-6 text-gray-600"># team members</dt>
-                  <dd class="order-first text-3xl font-semibold tracking-tight text-gray-900">{membersList.length}</dd>
-                </div>
-              </dl>
-            </div>
-          </div>
-        </div>
-        <div class="prose prose-md py-4 w-full">
-          <Content components={components(props)} />
-        </div>
-      </div>
-      <aside class="hidden lg:block sticky top-0 pb-10 w-96 overflow-y-auto py-2" data-pagefind-ignore>
-        <div class="sticky top-28 left-0 h-full overflow-y-auto pr-6 py-4">
-          <PillListFlat
-            color="pink"
-            title={`Owned domains (${ownedDomainsList.length})`}
-            pills={ownedDomainsList}
-            emptyMessage={`${props.data.name} does not own any domains.`}
-            client:load
-          />
-          <PillListFlat
-            color="blue"
-            title={`Owned services (${ownedServicesList.length})`}
-            pills={ownedServicesList}
-            emptyMessage={`This team does not own any services .`}
-            client:load
-          />
-          <PillListFlat
-            color="red"
-            title={`Owned messages (${ownedMessagesList.length})`}
-            pills={ownedMessagesList}
-            emptyMessage={`This team does not own any messages .`}
-            client:load
-          />
-          <OwnersList
-            title={`Team members (${membersList.length})`}
-            owners={membersList}
-            emptyMessage={`This team does not have any members.`}
-            client:load
-          />
-        </div>
-      </aside>
-    </div>
-  </main>
-</VerticalSideBarLayout>
-
-<style>
-  .docs-layout .prose {
-    max-width: none;
-  }
-</style>
diff --git a/eventcatalog/src/pages/docs/users/[id].md.ts b/eventcatalog/src/pages/docs/users/[id].md.ts
deleted file mode 100644
index 4a4544358..000000000
--- a/eventcatalog/src/pages/docs/users/[id].md.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-// This file exposes the markdown for EventCatalog in the Url
-// For example http://localhost:3000/docs/events/OrderAmended/0.0.1 loads the Page and http://localhost:3000/docs/events/OrderAmended/0.0.1.md loads the markdown
-// This is used for the LLMs to load the markdown for the given item (llms.txt);
-
-import type { APIRoute } from 'astro';
-import { getCollection } from 'astro:content';
-import config from '@config';
-import fs from 'fs';
-
-const users = await getCollection('users');
-
-export async function getStaticPaths() {
-  // Just return empty array if LLMs are not enabled
-  if (!config.llmsTxt?.enabled) {
-    return [];
-  }
-
-  return users.map((user) => ({
-    params: { type: 'users', id: user.data.id },
-    props: { content: user },
-  }));
-}
-
-export const GET: APIRoute = async ({ params, props }) => {
-  // Just return empty array if LLMs are not enabled
-  if (!config.llmsTxt?.enabled) {
-    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
-  }
-
-  if (props?.content?.filePath) {
-    const file = fs.readFileSync(props.content?.filePath, 'utf8');
-    return new Response(file, { status: 200 });
-  }
-
-  return new Response('Not found', { status: 404 });
-};
diff --git a/eventcatalog/src/pages/docs/users/[id]/_index.data.ts b/eventcatalog/src/pages/docs/users/[id]/_index.data.ts
deleted file mode 100644
index 14dee2b2d..000000000
--- a/eventcatalog/src/pages/docs/users/[id]/_index.data.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-// pages/teams/[id]/index.page.ts
-import { isSSR } from '@utils/feature';
-import { HybridPage } from '@utils/page-loaders/hybrid-page';
-
-export class Page extends HybridPage {
-  static get prerender(): boolean {
-    return !isSSR();
-  }
-
-  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
-    if (isSSR()) {
-      return [];
-    }
-
-    const { getUsers } = await import('@utils/users');
-    const users = await getUsers();
-
-    return users.map((user) => ({
-      params: { id: user.data.id },
-      props: user,
-    }));
-  }
-
-  protected static async fetchData(params: any) {
-    const { id } = params;
-
-    if (!id) {
-      return null;
-    }
-
-    const { getUsers } = await import('@utils/users');
-    const users = await getUsers();
-
-    // Find the specific team by id
-    const user = users.find((u) => u.data.id === id);
-
-    return user || null;
-  }
-
-  protected static createNotFoundResponse(): Response {
-    return new Response(null, {
-      status: 404,
-      statusText: 'User not found',
-    });
-  }
-}
diff --git a/eventcatalog/src/pages/docs/users/[id]/index.astro b/eventcatalog/src/pages/docs/users/[id]/index.astro
deleted file mode 100644
index 01596a276..000000000
--- a/eventcatalog/src/pages/docs/users/[id]/index.astro
+++ /dev/null
@@ -1,191 +0,0 @@
----
-import components from '@components/MDX/components';
-
-// SideBars
-import { render } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import OwnersList from '@components/Lists/OwnersList';
-import PillListFlat from '@components/Lists/PillListFlat';
-import EnvelopeIcon from '@heroicons/react/16/solid/EnvelopeIcon';
-import { buildUrl } from '@utils/url-builder';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { Page } from './_index.data';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-// Get data
-const props = await Page.getData(Astro);
-
-const { Content } = await render(props);
-
-const domains = props.data.ownedDomains as CollectionEntry<'domains'>[];
-const services = props.data.ownedServices as CollectionEntry<'services'>[];
-const events = props.data.ownedEvents as CollectionEntry<'events'>[];
-const commands = props.data.ownedCommands as CollectionEntry<'commands'>[];
-const queries = props.data.ownedQueries as CollectionEntry<'queries'>[];
-const teams = props.data.associatedTeams as CollectionEntry<'teams'>[];
-
-const ownedDomainsList = domains.map((p) => ({
-  label: `${p.data.name}`,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-  collection: p.collection,
-  tag: `v${p.data.version}`,
-}));
-
-const ownedServicesList = services.map((p) => ({
-  label: `${p.data.name}`,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-  collection: p.collection,
-  tag: `v${p.data.version}`,
-}));
-
-const ownedMessageList = [...events, ...commands, ...queries].map((p) => ({
-  label: `${p.data.name}`,
-  badge: p.collection,
-  color: p.collection === 'events' ? 'orange' : 'blue',
-  collection: p.collection,
-  tag: `v${p.data.version}`,
-  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
-}));
-
-const associatedTeams = teams.map((o) => ({
-  label: o.data.name,
-  type: o.collection,
-  badge: 'Team',
-  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
-}));
-
-const pageTitle = `User | ${props.data.name}`;
----
-
-<VerticalSideBarLayout title={pageTitle}>
-  <main class="flex sm:px-8 docs-layout h-full" data-pagefind-body data-pagefind-meta={`title:${pageTitle}`}>
-    <div class="flex docs-layout w-full">
-      <div class="w-full lg:mr-2 pr-8 overflow-y-auto py-8">
-        <div class="border-b border-gray-200 pb-4">
-          <div class="flex justify-start space-x-8">
-            <img src={props.data.avatarUrl} alt="Profile picture" class="shadow-md w-28 rounded-md" />
-            <div class="flex flex-col justify-between">
-              <div>
-                <h2 class="text-4xl font-bold">{props.data.name}</h2>
-                <span class="text-xl font-bold text-gray-500">{props.data.role}</span>
-              </div>
-              <div class="space-y-1">
-                {
-                  props.data.email && (
-                    <div class="flex space-x-1 items-center text-xs text-gray-500 font-bold hover:underline hover:text-primary">
-                      <EnvelopeIcon className="w-4 h-4 text-purple-400" />
-                      <a href={`mailto:${props.data.email}`}>Email</a>
-                    </div>
-                  )
-                }
-                {
-                  props.data.slackDirectMessageUrl && (
-                    <div class="flex space-x-1 items-center text-xs text-gray-500 font-bold hover:underline hover:text-primary">
-                      <img src={buildUrl('/slack-icon.svg', true)} class="w-4 h-3" />
-                      <a href={`${props.data.slackDirectMessageUrl}`}>Send DM on Slack</a>
-                    </div>
-                  )
-                }
-                {
-                  props.data.msTeamsDirectMessageUrl && (
-                    <div class="flex space-x-1 items-center text-xs text-gray-500 font-bold hover:underline hover:text-primary">
-                      <img src={buildUrl('/icons/ms-teams.svg', true)} class="w-4 h-4" />
-                      <a href={`${props.data.msTeamsDirectMessageUrl}`} target="_blank" rel="noopener noreferrer">
-                        Send DM on Teams
-                      </a>
-                    </div>
-                  )
-                }
-              </div>
-            </div>
-          </div>
-        </div>
-        <div class="border-b border-gray-200" data-pagefind-ignore>
-          <div class="mx-auto max-w-7xl px-6 lg:px-8">
-            <div class="mx-auto max-w-2xl lg:max-w-none">
-              <dl
-                class="hidden lg:grid grid-cols-1 gap-0.5 overflow-hidden rounded-2xl text-center sm:grid-cols-4 lg:grid-cols-4"
-              >
-                <div class="flex flex-col p-8">
-                  <dt class="text-sm font-semibold leading-6 text-gray-600"># owned domains</dt>
-                  <dd class="order-first text-3xl font-semibold tracking-tight text-gray-900">{ownedDomainsList.length}</dd>
-                </div>
-                <div class="flex flex-col p-8">
-                  <dt class="text-sm font-semibold leading-6 text-gray-600"># owned services</dt>
-                  <dd class="order-first text-3xl font-semibold tracking-tight text-gray-900">{ownedServicesList.length}</dd>
-                </div>
-                <div class="flex flex-col p-8">
-                  <dt class="text-sm font-semibold leading-6 text-gray-600"># owned messages</dt>
-                  <dd class="order-first text-3xl font-semibold tracking-tight text-gray-900">{ownedMessageList.length}</dd>
-                </div>
-                <div class="flex flex-col p-8">
-                  <dt class="text-sm font-semibold leading-6 text-gray-600"># teams joined</dt>
-                  <dd class="order-first text-3xl font-semibold tracking-tight text-gray-900">{associatedTeams.length}</dd>
-                </div>
-              </dl>
-            </div>
-          </div>
-        </div>
-        <div class="prose prose-md py-4 w-full">
-          <Content components={components(props)} />
-        </div>
-      </div>
-      <aside class="hidden lg:block sticky top-0 pb-10 w-96 overflow-y-auto py-2" data-pagefind-ignore>
-        <div class="sticky top-28 left-0 h-full overflow-y-auto pr-6 py-4">
-          {
-            ownedDomainsList.length > 0 && (
-              <PillListFlat
-                color="pink"
-                title={`Owned domains (${ownedDomainsList.length})`}
-                pills={ownedDomainsList}
-                emptyMessage={`${props.data.name} does not own any domains.`}
-                client:load
-              />
-            )
-          }
-          {
-            ownedServicesList.length > 0 && (
-              <PillListFlat
-                color="pink"
-                title={`Owned services (${ownedServicesList.length})`}
-                pills={ownedServicesList}
-                emptyMessage={`${props.data.name} does not own any services.`}
-                client:load
-              />
-            )
-          }
-          {
-            ownedMessageList.length > 0 && (
-              <PillListFlat
-                color="orange"
-                title={`Owned messages (${ownedMessageList.length})`}
-                pills={ownedMessageList}
-                emptyMessage={`${props.data.name} does not own any messages.`}
-                client:load
-              />
-            )
-          }
-          {
-            associatedTeams.length > 0 && (
-              <OwnersList
-                title={`Member of team (${associatedTeams.length})`}
-                owners={associatedTeams}
-                emptyMessage={`${props.data.name} is not part of any documented team.`}
-                client:load
-              />
-            )
-          }
-        </div>
-      </aside>
-    </div>
-  </main>
-</VerticalSideBarLayout>
-
-<style>
-  .docs-layout .prose {
-    max-width: none;
-    overflow: auto;
-  }
-</style>
diff --git a/eventcatalog/src/pages/index.astro b/eventcatalog/src/pages/index.astro
deleted file mode 100644
index 4666f4d3c..000000000
--- a/eventcatalog/src/pages/index.astro
+++ /dev/null
@@ -1,77 +0,0 @@
----
-import Footer from '@layouts/Footer.astro';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import components from '@components/MDX/page-components';
-import mdxComponents from '@components/MDX/components';
-import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
-import { getMDXComponentsByName } from '@utils/markdown';
-import { resourceToCollectionMap } from '@utils/collections/util';
-import { buildUrl } from '@utils/url-builder';
-import { isCustomLandingPageEnabled, isVisualiserEnabled } from '@utils/feature';
-import DefaultAstroLandingPage from './_index.astro';
-import config from '@config';
-
-let nodeGraphs: any[] = [];
-let CustomContent = null;
-
-import path from 'path';
-import { existsSync, readFileSync } from 'fs';
-
-const props = Astro.props;
-
-const pathToUserDefinedLandingPage = path.join(process.env.PROJECT_DIR || '', 'pages/homepage.astro');
-
-if (existsSync(pathToUserDefinedLandingPage) && isCustomLandingPageEnabled()) {
-  const customPages = import.meta.glob('/**/homepage.astro', { eager: true });
-  // @ts-ignore
-  CustomContent = Object.values(customPages)[0]?.default || null;
-
-  const rawContent = readFileSync(pathToUserDefinedLandingPage, 'utf-8');
-  nodeGraphs = getMDXComponentsByName(rawContent, 'NodeGraph') || [];
-}
-
-if (config.landingPage) {
-  return Astro.redirect(buildUrl(config.landingPage));
-}
----
-
-{
-  CustomContent ? (
-    <VerticalSideBarLayout title="EventCatalog">
-      <main class="flex sm:px-8 docs-layout h-full">
-        <div class="flex docs-layout w-full">
-          <div class="w-full lg:mr-2 pr-8 overflow-y-auto py-8">
-            <div class="w-full !max-w-none">
-              <CustomContent components={{ ...components, ...mdxComponents(props) }} />
-            </div>
-            <Footer />
-          </div>
-        </div>
-        {nodeGraphs.length > 0 &&
-          nodeGraphs.map((nodeGraph: any) => {
-            const collection = resourceToCollectionMap[nodeGraph.type as keyof typeof resourceToCollectionMap];
-            return (
-              <NodeGraph
-                id={nodeGraph.id}
-                version={nodeGraph.version}
-                collection={collection}
-                title={nodeGraph.title}
-                mode="simple"
-                linksToVisualiser={true}
-                href={
-                  isVisualiserEnabled()
-                    ? {
-                        label: 'Open in Visualiser',
-                        url: buildUrl(`/visualiser/${collection}/${nodeGraph.id}/${nodeGraph.version}`),
-                      }
-                    : undefined
-                }
-              />
-            );
-          })}
-      </main>
-    </VerticalSideBarLayout>
-  ) : (
-    <DefaultAstroLandingPage />
-  )
-}
diff --git a/eventcatalog/src/pages/plans/index.astro b/eventcatalog/src/pages/plans/index.astro
deleted file mode 100644
index dc9bb7111..000000000
--- a/eventcatalog/src/pages/plans/index.astro
+++ /dev/null
@@ -1,292 +0,0 @@
----
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import {
-  Rocket,
-  Users,
-  Bot,
-  ScrollText,
-  Component,
-  Cpu,
-  Code,
-  LifeBuoy,
-  ExternalLink,
-  Network,
-  Github,
-  Flag,
-} from 'lucide-react';
----
-
-<VerticalSideBarLayout title="EventCatalog Pro">
-  <div class="min-h-[calc(100vh-60px)] bg-white">
-    <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-16">
-      {/* Hero Section */}
-      <div class="grid grid-cols-1 lg:grid-cols-2 gap-12 items-center mb-16">
-        <div>
-          <div class="inline-flex items-center px-4 py-2 rounded-full bg-purple-100 text-purple-700 font-medium text-sm mb-6">
-            <Rocket className="w-4 h-4 mr-2" />
-            Upgrade your Catalog
-          </div>
-          <h1 class="text-4xl font-bold text-gray-900 tracking-tight mb-4">Supercharge your EventCatalog</h1>
-          <p class="text-xl text-gray-600 mb-8">
-            Unlock advanced features like automated docs (e.g OpenAPI, AsyncAPI), Custom documentation, AI assistant, and catalog
-            federation — all designed to help you scale without complexity.
-          </p>
-
-          {/* Integration Sources */}
-          <div class="mb-8">
-            <p class="text-sm font-medium text-gray-500 mb-4">Generate documentation from:</p>
-            <div class="grid grid-cols-2 md:grid-cols-3 gap-4">
-              <a
-                href="https://www.eventcatalog.dev/integrations/openapi"
-                class="flex items-center space-x-2 bg-gray-50 rounded-lg px-4 py-2 hover:bg-gray-100 transition-colors duration-150"
-              >
-                <img src="/icons/openapi.svg" alt="OpenAPI" class="w-6 h-6" />
-                <span class="text-sm font-medium">OpenAPI</span>
-              </a>
-              <a
-                href="https://www.eventcatalog.dev/integrations/asyncapi"
-                class="flex items-center space-x-2 bg-gray-50 rounded-lg px-4 py-2 hover:bg-gray-100 transition-colors duration-150"
-              >
-                <img src="/icons/asyncapi.svg" alt="AsyncAPI" class="w-6 h-6" />
-                <span class="text-sm font-medium">AsyncAPI</span>
-              </a>
-              <a
-                href="https://www.eventcatalog.dev/integrations"
-                class="flex items-center space-x-2 bg-gray-50 rounded-lg px-4 py-2 hover:bg-gray-100 transition-colors duration-150"
-              >
-                <Component className="w-6 h-6 text-purple-600" />
-                <span class="text-sm font-medium">And more...</span>
-              </a>
-            </div>
-          </div>
-
-          <div class="flex flex-col sm:flex-row gap-4 mb-8">
-            <a
-              href="https://www.eventcatalog.cloud"
-              target="_blank"
-              class="inline-flex items-center justify-center px-6 py-3 border border-transparent text-base font-medium rounded-lg text-white bg-purple-600 hover:bg-purple-700 transition-colors duration-150"
-            >
-              Try for free
-              <svg class="ml-2 w-4 h-4" viewBox="0 0 20 20" fill="currentColor">
-                <path
-                  fill-rule="evenodd"
-                  d="M10.293 3.293a1 1 0 011.414 0l6 6a1 1 0 010 1.414l-6 6a1 1 0 01-1.414-1.414L14.586 11H3a1 1 0 110-2h11.586l-4.293-4.293a1 1 0 010-1.414z"
-                  clip-rule="evenodd"></path>
-              </svg>
-            </a>
-            <a
-              href="https://www.eventcatalog.dev"
-              target="_blank"
-              class="inline-flex items-center justify-center px-6 py-3 border border-gray-300 text-base font-medium rounded-lg text-gray-700 bg-white hover:bg-gray-50 transition-colors duration-150"
-            >
-              View documentation
-            </a>
-          </div>
-          <p class="text-sm text-gray-500">Try free for 14 days, no credit card required</p>
-        </div>
-
-        <div class="relative">
-          <img
-            src="/images/eventcatalog-upgrade.png"
-            alt="EventCatalog Pro"
-            class="w-full rounded-xl shadow-lg border border-gray-200"
-          />
-        </div>
-      </div>
-
-      {/* Why upgrade section */}
-      <div class="mb-16">
-        <h2 class="text-2xl font-semibold text-gray-900 mb-8">Why upgrade EventCatalog?</h2>
-        <div class="grid grid-cols-1 md:grid-cols-3 gap-8">
-          <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-            <div class="w-12 h-12 bg-purple-100 rounded-lg flex items-center justify-center mb-4">
-              <ScrollText className="w-6 h-6 text-purple-600" />
-            </div>
-            <h3 class="text-lg font-semibold text-gray-900 mb-2">A living source of truth</h3>
-            <p class="text-gray-600">Keep docs in sync with your systems, ensuring your team always has accurate information.</p>
-          </div>
-
-          <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-            <div class="w-12 h-12 bg-purple-100 rounded-lg flex items-center justify-center mb-4">
-              <Users className="w-6 h-6 text-purple-600" />
-            </div>
-            <h3 class="text-lg font-semibold text-gray-900 mb-2">Shared system understanding</h3>
-            <p class="text-gray-600">Align teams and reduce tribal knowledge with centralized architecture documentation.</p>
-          </div>
-
-          <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-            <div class="w-12 h-12 bg-purple-100 rounded-lg flex items-center justify-center mb-4">
-              <Component className="w-6 h-6 text-purple-600" />
-            </div>
-            <h3 class="text-lg font-semibold text-gray-900 mb-2">Architecture that scales</h3>
-            <p class="text-gray-600">Grow without losing context of complexity, making architectural decisions easy to find.</p>
-          </div>
-        </div>
-      </div>
-
-      {/* Documentation Journey Section */}
-      <div class="mb-16">
-        <h2 class="text-2xl font-semibold text-gray-900 mb-4">Scales with your team and architecture</h2>
-        <p class="text-gray-600 mb-8 max-w-3xl">
-          From scattered documentation to a well-governed system, EventCatalog helps you control complexity with well governed
-          documentation for your teams. Choose the plan that fits your needs.
-        </p>
-
-        <div class="relative py-8">
-          {/* Journey Line */}
-          <div class="absolute top-1/2 left-0 w-full h-1 bg-purple-200 transform -translate-y-1/2 hidden md:block"></div>
-
-          <div class="grid grid-cols-1 md:grid-cols-4 gap-8 relative">
-            {/* Stage 1 */}
-            <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200 relative">
-              <div
-                class="w-12 h-12 bg-purple-100 rounded-full flex items-center justify-center mb-4 mx-auto md:absolute md:-top-6 md:left-1/2 md:transform md:-translate-x-1/2"
-              >
-                <Github className="w-6 h-6 text-purple-600" />
-              </div>
-              <h3 class="text-lg font-semibold text-gray-900 mb-2 text-center">Community Edition</h3>
-              <p class="text-gray-600 text-sm text-center">You're just beginning to document services, domains, and events.</p>
-            </div>
-
-            {/* Stage 2 */}
-            <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200 relative">
-              <div
-                class="w-12 h-12 bg-purple-100 rounded-full flex items-center justify-center mb-4 mx-auto md:absolute md:-top-6 md:left-1/2 md:transform md:-translate-x-1/2"
-              >
-                <Flag className="w-6 h-6 text-purple-600" />
-              </div>
-              <h3 class="text-lg font-semibold text-gray-900 mb-2 text-center">Starter Plan</h3>
-              <p class="text-gray-600 text-sm text-center">For teams formalizing their architecture documentation</p>
-            </div>
-
-            {/* Stage 3 */}
-            <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200 relative">
-              <div
-                class="w-12 h-12 bg-purple-100 rounded-full flex items-center justify-center mb-4 mx-auto md:absolute md:-top-6 md:left-1/2 md:transform md:-translate-x-1/2"
-              >
-                <Network className="w-6 h-6 text-purple-600" />
-              </div>
-              <h3 class="text-lg font-semibold text-gray-900 mb-2 text-center">Scale Plan</h3>
-              <p class="text-gray-600 text-sm text-center">
-                Built for teams scaling across domains and integrating with external systems
-              </p>
-            </div>
-
-            {/* Stage 4 */}
-            <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200 relative">
-              <div
-                class="w-12 h-12 bg-purple-100 rounded-full flex items-center justify-center mb-4 mx-auto md:absolute md:-top-6 md:left-1/2 md:transform md:-translate-x-1/2"
-              >
-                <Rocket className="w-6 h-6 text-purple-600" />
-              </div>
-              <h3 class="text-lg font-semibold text-gray-900 mb-2 text-center">Enterprise Plan</h3>
-              <p class="text-gray-600 text-sm text-center">
-                Designed for organizations building and governing complex event platforms
-              </p>
-            </div>
-          </div>
-
-          {/* Mobile Progress Indicators */}
-          <div class="flex justify-center items-center space-x-2 mt-4 md:hidden">
-            <div class="w-2 h-2 rounded-full bg-purple-600"></div>
-            <div class="w-2 h-2 rounded-full bg-purple-400"></div>
-            <div class="w-2 h-2 rounded-full bg-purple-300"></div>
-            <div class="w-2 h-2 rounded-full bg-purple-200"></div>
-          </div>
-        </div>
-      </div>
-
-      {/* Features Section */}
-      <div class="mb-16">
-        <h2 class="text-2xl font-semibold text-gray-900 mb-8">Save time with EventCatalog</h2>
-        <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
-          <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-            <div class="w-12 h-12 bg-blue-100 rounded-lg flex items-center justify-center mb-4">
-              <ScrollText className="w-6 h-6 text-blue-600" />
-            </div>
-            <h3 class="text-lg font-semibold text-gray-900 mb-2">Custom Documentation</h3>
-            <p class="text-gray-600">Add ADRs, runbooks, and technical guidelines to create a centralized knowledge hub.</p>
-          </div>
-
-          <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-            <div class="w-12 h-12 bg-green-100 rounded-lg flex items-center justify-center mb-4">
-              <Bot className="w-6 h-6 text-green-600" />
-            </div>
-            <h3 class="text-lg font-semibold text-gray-900 mb-2">AI Assistant</h3>
-            <p class="text-gray-600">Chat with your catalog to quickly find information about your architecture.</p>
-          </div>
-
-          <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-            <div class="w-12 h-12 bg-purple-100 rounded-lg flex items-center justify-center mb-4">
-              <Component className="w-6 h-6 text-purple-600" />
-            </div>
-            <h3 class="text-lg font-semibold text-gray-900 mb-2">Federation</h3>
-            <p class="text-gray-600">Connect multiple catalogs into a unified view for centralized visibility across teams.</p>
-          </div>
-
-          <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-            <div class="w-12 h-12 bg-indigo-100 rounded-lg flex items-center justify-center mb-4">
-              <Code className="w-6 h-6 text-indigo-600" />
-            </div>
-            <h3 class="text-lg font-semibold text-gray-900 mb-2">IDE Integration</h3>
-            <p class="text-gray-600">Access EventCatalog directly from your IDE for seamless documentation while coding.</p>
-          </div>
-
-          <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-            <div class="w-12 h-12 bg-yellow-100 rounded-lg flex items-center justify-center mb-4">
-              <Cpu className="w-6 h-6 text-yellow-600" />
-            </div>
-            <h3 class="text-lg font-semibold text-gray-900 mb-2">Automated Documentation</h3>
-            <p class="text-gray-600">
-              Generate and maintain documentation automatically with integrations for AsyncAPI and OpenAPI.
-            </p>
-          </div>
-
-          <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-            <div class="w-12 h-12 bg-red-100 rounded-lg flex items-center justify-center mb-4">
-              <LifeBuoy className="w-6 h-6 text-red-600" />
-            </div>
-            <h3 class="text-lg font-semibold text-gray-900 mb-2">Priority Support</h3>
-            <p class="text-gray-600">Get priority email support and assistance from the EventCatalog team.</p>
-          </div>
-        </div>
-      </div>
-
-      {/* Questions Section */}
-      <div class="mt-16">
-        <h2 class="text-2xl font-semibold text-gray-900 mb-8">Questions about EventCatalog?</h2>
-        <div class="grid grid-cols-1 md:grid-cols-2 gap-8">
-          <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-            <h3 class="text-lg font-semibold text-gray-900 mb-2">Request a Demo</h3>
-            <p class="text-gray-600 mb-4">See EventCatalog in action with a personalized demo from our team.</p>
-            <a
-              href="mailto:hello@eventcatalog.dev"
-              class="text-purple-600 hover:text-purple-700 font-medium inline-flex items-center"
-            >
-              Schedule a demo
-              <ExternalLink className="w-4 h-4 ml-1.5" />
-            </a>
-          </div>
-
-          <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-            <h3 class="text-lg font-semibold text-gray-900 mb-2">Join the community</h3>
-            <p class="text-gray-600 mb-4">Join our growing community on Discord. Over 1000+ members.</p>
-            <a
-              href="https://discord.gg/3rjaZMmrAm"
-              class="text-purple-600 hover:text-purple-700 font-medium inline-flex items-center"
-            >
-              Join the community
-              <ExternalLink className="w-4 h-4 ml-1.5" />
-            </a>
-          </div>
-        </div>
-      </div>
-    </div>
-  </div>
-</VerticalSideBarLayout>
-
-<style>
-  .scroll-smooth {
-    scroll-behavior: smooth;
-  }
-</style>
diff --git a/eventcatalog/src/pages/schemas/index.astro b/eventcatalog/src/pages/schemas/index.astro
deleted file mode 100644
index c0e761b40..000000000
--- a/eventcatalog/src/pages/schemas/index.astro
+++ /dev/null
@@ -1,175 +0,0 @@
----
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { getEvents } from '@utils/events';
-import { getCommands } from '@utils/commands';
-import { getQueries } from '@utils/queries';
-import { getServices, getSpecificationsForService } from '@utils/collections/services';
-import SchemaExplorer from '@components/SchemaExplorer/SchemaExplorer';
-import { isEventCatalogScaleEnabled } from '@utils/feature';
-import { getOwner } from '@utils/collections/owners';
-import { buildUrl } from '@utils/url-builder';
-import fs from 'fs';
-import path from 'path';
-
-// Fetch all messages
-const events = await getEvents({ getAllVersions: true });
-const commands = await getCommands({ getAllVersions: true });
-const queries = await getQueries({ getAllVersions: true });
-
-// Fetch all services
-const services = await getServices({ getAllVersions: true });
-
-// Combine all messages
-const allMessages = [...events, ...commands, ...queries];
-
-// Helper function to enrich owners with full details
-async function enrichOwners(ownersRaw: any[]) {
-  if (!ownersRaw || ownersRaw.length === 0) return [];
-
-  const owners = await Promise.all(ownersRaw.map(getOwner));
-  const filteredOwners = owners.filter((o) => o !== undefined);
-
-  return filteredOwners.map((o) => ({
-    id: o.data.id,
-    name: o.data.name,
-    type: o.collection,
-    href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
-  }));
-}
-
-// Filter messages with schemas and read schema content - only keep essential data
-const messagesWithSchemas = await Promise.all(
-  allMessages
-    .filter((message) => message.data.schemaPath)
-    // Make sure the file exists
-    .filter((message) => fs.existsSync(path.join(path.dirname(message.filePath ?? ''), message.data.schemaPath ?? '')))
-    .map(async (message) => {
-      try {
-        // Get the schema file path
-        const schemaPath = message.data.schemaPath;
-        const fullSchemaPath = path.join(path.dirname(message.filePath ?? ''), schemaPath ?? '');
-
-        // Read the schema content
-        let schemaContent = '';
-        if (fs.existsSync(fullSchemaPath)) {
-          schemaContent = fs.readFileSync(fullSchemaPath, 'utf-8');
-        }
-
-        // Get schema file extension
-        const schemaExtension = path.extname(schemaPath ?? '').slice(1);
-
-        // Enrich owners with full details
-        const enrichedOwners = await enrichOwners(message.data.owners || []);
-
-        // Only return essential data - strip out markdown, full data objects, etc.
-        return {
-          collection: message.collection,
-          data: {
-            id: message.data.id,
-            name: message.data.name,
-            version: message.data.version,
-            summary: message.data.summary,
-            schemaPath: message.data.schemaPath,
-            producers: message.data.producers || [],
-            consumers: message.data.consumers || [],
-            owners: enrichedOwners,
-          },
-          schemaContent,
-          schemaExtension,
-        };
-      } catch (error) {
-        console.error(`Error reading schema for ${message.data.id}:`, error);
-        const enrichedOwners = await enrichOwners(message.data.owners || []);
-        return {
-          collection: message.collection,
-          data: {
-            id: message.data.id,
-            name: message.data.name,
-            version: message.data.version,
-            summary: message.data.summary,
-            schemaPath: message.data.schemaPath,
-            producers: message.data.producers || [],
-            consumers: message.data.consumers || [],
-            owners: enrichedOwners,
-          },
-          schemaContent: '',
-          schemaExtension: 'json',
-        };
-      }
-    })
-);
-
-// Filter services with specifications and read spec content - only keep essential data
-const servicesWithSpecs = await Promise.all(
-  services.map(async (service) => {
-    try {
-      const specifications = getSpecificationsForService(service);
-
-      // Only include services that have specifications
-      if (specifications.length === 0) {
-        return null;
-      }
-
-      // Process each specification file for this service
-      return await Promise.all(
-        specifications.map(async (spec) => {
-          const specPath = path.join(path.dirname(service.filePath ?? ''), spec.path);
-
-          // Only include if the spec file exists
-          if (!fs.existsSync(specPath)) {
-            return null;
-          }
-
-          const schemaContent = fs.readFileSync(specPath, 'utf-8');
-          // Use spec type (openapi, asyncapi) as the extension for proper labeling
-          const schemaExtension = spec.type;
-
-          // Enrich owners with full details
-          const enrichedOwners = await enrichOwners(service.data.owners || []);
-
-          // Only return essential data - strip out markdown, sends/receives, entities, etc.
-          return {
-            collection: 'services',
-            data: {
-              id: `${service.data.id}`,
-              name: `${service.data.name} - ${spec.name}`,
-              version: service.data.version,
-              summary: service.data.summary,
-              schemaPath: spec.path,
-              owners: enrichedOwners,
-            },
-            schemaContent,
-            schemaExtension,
-            specType: spec.type,
-            specName: spec.name,
-            specFilenameWithoutExtension: spec.filenameWithoutExtension,
-          };
-        })
-      );
-    } catch (error) {
-      console.error(`Error reading specifications for service ${service.data.id}:`, error);
-      return null;
-    }
-  })
-);
-
-// Flatten and filter out null values
-const flatServicesWithSpecs = servicesWithSpecs.flat().filter((service) => service !== null);
-
-// Combine messages and services
-const allSchemas = [...messagesWithSchemas, ...flatServicesWithSpecs];
-
-const apiAccessEnabled = isEventCatalogScaleEnabled();
----
-
-<VerticalSideBarLayout title="Schema Explorer - EventCatalog">
-  <main class="flex sm:px-8 docs-layout h-[calc(100vh-var(--header-height,0px)-64px)]">
-    <div class="flex docs-layout w-full h-full">
-      <div class="w-full lg:mr-2 pr-8 py-6 flex flex-col h-full">
-        <div class="w-full !max-w-none h-full flex flex-col overflow-hidden">
-          <SchemaExplorer client:load schemas={allSchemas as any} apiAccessEnabled={apiAccessEnabled} />
-        </div>
-      </div>
-    </div>
-  </main>
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/studio.astro b/eventcatalog/src/pages/studio.astro
deleted file mode 100644
index 9623e8b1f..000000000
--- a/eventcatalog/src/pages/studio.astro
+++ /dev/null
@@ -1,234 +0,0 @@
----
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-import { getEvents } from '@utils/events';
-import { getCommands } from '@utils/commands';
-import { getServices } from '@utils/collections/services';
-import { BoltIcon, ServerIcon, RectangleGroupIcon } from '@heroicons/react/24/outline';
-import { SquareDashedMousePointerIcon, ArrowLeftRightIcon } from 'lucide-react';
-import StudioPageModal from '@components/Studio/StudioPageModal';
-import { getChannels } from '@utils/channels';
-
-const [events, commands, services, channels] = await Promise.all([
-  getEvents().catch(() => []),
-  getCommands().catch(() => []),
-  getServices().catch(() => []),
-  getChannels().catch(() => []),
-]);
-
-// Get counts
-const eventCount = events.length;
-const serviceCount = services.length;
-const commandCount = commands.length;
-const channelCount = channels.length;
-
-// Get a few sample resources to display
-const sampleEvents = events.slice(0, 2);
-const sampleServices = services.slice(0, 2);
-const sampleChannels = channels.slice(0, 1);
-
-// Determine which resources to show (fallback if some are missing)
-const resourcesToShow = [
-  ...sampleEvents.map((event, index) => ({ type: 'event', data: event, index })),
-  ...sampleServices.map((service, index) => ({ type: 'service', data: service, index: index + 2 })),
-  ...sampleChannels.map((channel, index) => ({ type: 'channel', data: channel, index: index + 4 })),
-].slice(0, 5); // Max 5 resources
----
-
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-    <meta name="generator" content={Astro.generator} />
-    <title>EventCatalog Studio</title>
-  </head>
-  <body>
-    <VerticalSideBarLayout title="EventCatalog Studio">
-      <div class="min-h-[calc(100vh-60px)] bg-white">
-        <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-16">
-          {/* Hero Section */}
-          <div class="grid grid-cols-1 lg:grid-cols-2 gap-12 items-center mb-16">
-            <div>
-              <div class="inline-flex items-center px-4 py-2 rounded-full bg-gray-100 text-gray-900 font-medium text-sm mb-6">
-                <SquareDashedMousePointerIcon className="w-4 h-4 mr-2" />
-                EventCatalog Studio
-              </div>
-              <h1 class="text-4xl font-bold text-gray-900 tracking-tight mb-4">Turn your resources into designs</h1>
-              <p class="text-xl text-gray-600 mb-8">
-                Transform your documented messages, services, and domains into architecture diagrams. Drag, drop, and design with
-                what you already have.
-              </p>
-              <div class="flex flex-col sm:flex-row gap-4 mb-2">
-                <button
-                  id="design-button"
-                  class="inline-flex items-center justify-center px-6 py-3 border border-transparent text-base font-medium rounded-lg text-white bg-gray-900 hover:bg-gray-800 transition-colors duration-150"
-                >
-                  <SquareDashedMousePointerIcon className="w-4 h-4 mr-2" />
-                  Open EventCatalog Studio
-                </button>
-              </div>
-
-              <p class="text-sm text-gray-500 italic mb-6">
-                {eventCount + serviceCount + channelCount + commandCount} resources ready to design with
-              </p>
-            </div>
-
-            <div class="relative">
-              <div class="relative">
-                {/* Animation container */}
-                <div class="relative h-[400px] flex items-center justify-center">
-                  {/* Resource cards that animate in */}
-                  <div class="absolute left-0 top-1/2 -translate-y-1/2 space-y-3">
-                    {
-                      resourcesToShow.map((resource) => {
-                        if (resource.type === 'event') {
-                          return (
-                            <div
-                              class="animate-float-in flex items-center gap-2 text-sm text-gray-700 px-4 py-3 bg-orange-50 rounded-lg border border-orange-200 shadow-sm"
-                              style={`animation-delay: ${resource.index * 0.4}s;`}
-                            >
-                              <BoltIcon className="w-4 h-4 text-orange-600" />
-                              {resource.data.data.name}
-                            </div>
-                          );
-                        } else if (resource.type === 'service') {
-                          return (
-                            <div
-                              class="animate-float-in flex items-center gap-2 text-sm text-gray-700 px-4 py-3 bg-pink-50 rounded-lg border border-pink-200 shadow-sm"
-                              style={`animation-delay: ${resource.index * 0.4}s;`}
-                            >
-                              <ServerIcon className="w-4 h-4 text-gray-600" />
-                              {resource.data.data.name}
-                            </div>
-                          );
-                        } else if (resource.type === 'channel') {
-                          return (
-                            <div
-                              class="animate-float-in flex items-center gap-2 text-sm text-gray-700 px-4 py-3 bg-gray-50 rounded-lg border border-gray-200 shadow-sm"
-                              style={`animation-delay: ${resource.index * 0.4}s;`}
-                            >
-                              <ArrowLeftRightIcon className="w-4 h-4 text-gray-600" />
-                              {resource.data.data.name}
-                            </div>
-                          );
-                        }
-                      })
-                    }
-                  </div>
-
-                  {/* Arrow indicator */}
-                  <div class="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 animate-pulse">
-                    <svg class="w-12 h-12 text-gray-400" viewBox="0 0 24 24" fill="none" stroke="currentColor">
-                      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 7l5 5m0 0l-5 5m5-5H6"></path>
-                    </svg>
-                  </div>
-
-                  {/* Design preview */}
-                  <div class="absolute right-0 top-1/2 -translate-y-1/2 animate-fade-in-scale" style="animation-delay: 2s;">
-                    <img
-                      src="/studio-bg.png"
-                      alt="Studio Design Preview"
-                      class="rounded-xl shadow-xl border border-gray-200 w-64 h-auto"
-                    />
-                  </div>
-                </div>
-              </div>
-            </div>
-          </div>
-
-          {/* Features Section */}
-          <div class="grid grid-cols-1 md:grid-cols-3 gap-8">
-            <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-              <div class="w-12 h-12 bg-gray-100 rounded-lg flex items-center justify-center mb-4">
-                <svg class="w-6 h-6 text-gray-900" viewBox="0 0 24 24" fill="none" stroke="currentColor">
-                  <rect width="8" height="8" x="3" y="3" rx="2"></rect>
-                  <path d="M7 11v4a2 2 0 0 0 2 2h4"></path>
-                  <rect width="8" height="8" x="13" y="13" rx="2"></rect>
-                </svg>
-              </div>
-              <h3 class="text-lg font-semibold text-gray-900 mb-2">Real Resources</h3>
-              <p class="text-gray-600">
-                Drag and drop messages, services, and domains from your catalog. No more copying names or keeping things manually
-                in sync.
-              </p>
-            </div>
-
-            <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-              <div class="w-12 h-12 bg-gray-100 rounded-lg flex items-center justify-center mb-4">
-                <svg class="w-6 h-6 text-gray-900" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-                  <path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z"></path>
-                  <polyline points="17 21 17 13 7 13 7 21"></polyline>
-                  <polyline points="7 3 7 8 15 8"></polyline>
-                </svg>
-              </div>
-              <h3 class="text-lg font-semibold text-gray-900 mb-2">Save & Version</h3>
-              <p class="text-gray-600">Save designs locally and store in Git. All designs and data is owned by you.</p>
-            </div>
-
-            <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
-              <div class="w-12 h-12 bg-gray-100 rounded-lg flex items-center justify-center mb-4">
-                <svg class="w-6 h-6 text-gray-900" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-                  <polyline points="16 18 22 12 16 6"></polyline>
-                  <polyline points="8 6 2 12 8 18"></polyline>
-                </svg>
-              </div>
-              <h3 class="text-lg font-semibold text-gray-900 mb-2">Embed Anywhere</h3>
-              <p class="text-gray-600">
-                Drop diagrams directly into documentation pages. One source of truth for your architecture.
-              </p>
-            </div>
-          </div>
-        </div>
-      </div>
-
-      {/* Studio Modal */}
-      <StudioPageModal client:only="react" />
-    </VerticalSideBarLayout>
-
-    <script>
-      // Handle opening the studio modal
-      const button = document.getElementById('design-button');
-      if (button) {
-        button.addEventListener('click', () => {
-          // Trigger the modal to open
-          window.dispatchEvent(new CustomEvent('openStudioModal'));
-        });
-      }
-    </script>
-
-    <style>
-      @keyframes float-in {
-        0% {
-          opacity: 0;
-          transform: translateX(-30px);
-        }
-        100% {
-          opacity: 1;
-          transform: translateX(0);
-        }
-      }
-
-      @keyframes fade-in-scale {
-        0% {
-          opacity: 0;
-          transform: translateY(-50%) scale(0.9);
-        }
-        100% {
-          opacity: 1;
-          transform: translateY(-50%) scale(1);
-        }
-      }
-
-      .animate-float-in {
-        animation: float-in 0.6s ease-out forwards;
-        opacity: 0;
-      }
-
-      .animate-fade-in-scale {
-        animation: fade-in-scale 0.8s ease-out forwards;
-        opacity: 0;
-      }
-    </style>
-  </body>
-</html>
diff --git a/eventcatalog/src/pages/unauthorized/index.astro b/eventcatalog/src/pages/unauthorized/index.astro
deleted file mode 100644
index 360e15f7e..000000000
--- a/eventcatalog/src/pages/unauthorized/index.astro
+++ /dev/null
@@ -1,84 +0,0 @@
----
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
----
-
-<VerticalSideBarLayout title="Unauthorized - EventCatalog">
-  <div class="flex h-[calc(100vh-120px)] bg-white">
-    <main class="flex w-full items-center justify-center bg-white text-center sm:p-12">
-      <div class="w-full max-w-xl text-center">
-        <div class="mb-6 inline-flex h-16 w-16 items-center justify-center rounded-2xl bg-red-100">
-          <svg
-            class="h-9 w-9 text-red-600"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            stroke-width="2"
-            stroke-linecap="round"
-            stroke-linejoin="round"
-          >
-            <rect x="3" y="11" width="18" height="11" rx="2" ry="2"></rect>
-            <path d="M7 11V7a5 5 0 0 1 10 0v4"></path>
-          </svg>
-        </div>
-
-        <h1 class="text-3xl font-bold text-gray-800 mb-4">Access Denied</h1>
-
-        <p class="max-w-md mx-auto text-base text-gray-500 mb-8">You don't have permission to access this resource.</p>
-
-        <!-- Client-side path display -->
-        <div
-          id="path-container"
-          class="hidden mb-8 w-full max-w-lg mx-auto rounded-lg border border-gray-200 bg-gray-100 p-4 text-left"
-        >
-          <p class="mb-2 text-sm font-medium text-gray-600">Requested path:</p>
-          <code id="requested-path" class="break-all font-mono text-sm text-gray-800"></code>
-        </div>
-
-        <div class="flex flex-col sm:flex-row gap-4 justify-center">
-          <button
-            onclick="history.back()"
-            class="inline-flex items-center justify-center px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md shadow-sm hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
-          >
-            <svg class="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 19l-7-7m0 0l7-7m-7 7h18"></path>
-            </svg>
-            Go Back
-          </button>
-
-          <a
-            href="/dashboard"
-            class="inline-flex items-center justify-center px-4 py-2 text-sm font-medium text-white bg-blue-600 border border-transparent rounded-md shadow-sm hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
-          >
-            <svg class="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-              <path
-                stroke-linecap="round"
-                stroke-linejoin="round"
-                stroke-width="2"
-                d="M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2H5a2 2 0 00-2-2z"></path>
-            </svg>
-            Go to Dashboard
-          </a>
-        </div>
-      </div>
-    </main>
-  </div>
-
-  <!-- Client-side script -->
-  <script>
-    document.addEventListener('DOMContentLoaded', () => {
-      // Get query parameters on the client side
-      const url = new URL(window.location.href);
-      const path = url.searchParams.get('path');
-
-      if (path) {
-        const pathContainer = document.getElementById('path-container');
-        const requestedPath = document.getElementById('requested-path');
-
-        if (pathContainer && requestedPath) {
-          requestedPath.textContent = path;
-          pathContainer.classList.remove('hidden');
-        }
-      }
-    });
-  </script>
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/_index.data.ts b/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/_index.data.ts
deleted file mode 100644
index 3a4ded125..000000000
--- a/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/_index.data.ts
+++ /dev/null
@@ -1,100 +0,0 @@
-// pages/visualiser/[type]/[id]/[version]/index.page.ts
-import { HybridPage } from '@utils/page-loaders/hybrid-page';
-import { isAuthEnabled } from '@utils/feature';
-import type { PageTypes } from '@types';
-import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
-import { isVisualiserEnabled } from '@utils/feature';
-
-type PageTypesWithFlows = PageTypes | 'flows';
-
-export class Page extends HybridPage {
-  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
-    if (isAuthEnabled() || !isVisualiserEnabled()) {
-      return [];
-    }
-
-    const { getFlows } = await import('@utils/collections/flows');
-
-    const loaders = {
-      ...pageDataLoader,
-      flows: getFlows,
-    };
-
-    const itemTypes: PageTypesWithFlows[] = ['events', 'commands', 'queries', 'services', 'domains', 'flows', 'containers'];
-    const allItems = await Promise.all(itemTypes.map((type) => loaders[type]()));
-
-    return allItems.flatMap((items, index) =>
-      items
-        .filter((item) => item.data.visualiser !== false)
-        .map((item) => ({
-          params: {
-            type: itemTypes[index],
-            id: item.data.id,
-            version: item.data.version,
-          },
-          props: {
-            type: itemTypes[index],
-            ...item,
-          },
-        }))
-    );
-  }
-
-  protected static async fetchData(params: any) {
-    const { type, id, version } = params;
-
-    if (!type || !id || !version || !isVisualiserEnabled()) {
-      return null;
-    }
-
-    const { getFlows } = await import('@utils/collections/flows');
-
-    const loaders = {
-      ...pageDataLoader,
-      flows: getFlows,
-    };
-
-    // Get all items of the specified type
-    const items = await loaders[type as PageTypesWithFlows]();
-
-    // Find the specific item by id and version
-    const item = items.find((i) => i.data.id === id && i.data.version === version && i.data.visualiser !== false);
-
-    if (!item) {
-      return null;
-    }
-
-    return {
-      type,
-      ...item,
-    };
-  }
-
-  protected static createNotFoundResponse(): Response {
-    return new Response(null, {
-      status: 404,
-      statusText: 'Visualiser page not found',
-    });
-  }
-
-  static get clientAuthScript(): string {
-    if (!isAuthEnabled() || !isVisualiserEnabled()) {
-      return '';
-    }
-
-    return `
-      if (typeof window !== 'undefined' && !import.meta.env.SSR) {
-        fetch('/api/auth/session')
-          .then(res => res.json())
-          .then(session => {
-            if (!session?.user) {
-              window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
-            }
-          })
-          .catch(() => {
-            window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
-          });
-      }
-    `;
-  }
-}
diff --git a/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/data/_index.data.ts b/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/data/_index.data.ts
deleted file mode 100644
index 931c216a3..000000000
--- a/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/data/_index.data.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import { HybridPage } from '@utils/page-loaders/hybrid-page';
-import { isAuthEnabled } from '@utils/feature';
-import { getServices, type Service } from '@utils/collections/services';
-
-const serviceHasData = (service: Service) => {
-  return service.data.writesTo?.length || 0 > 0 || service.data.readsFrom?.length || 0 > 0;
-};
-
-export class Page extends HybridPage {
-  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
-    if (isAuthEnabled()) {
-      return [];
-    }
-
-    const services = await getServices();
-    const servicesWithData = services.filter((service) => serviceHasData(service));
-
-    return servicesWithData.flatMap((service) => {
-      return {
-        params: {
-          type: 'services',
-          id: service.data.id,
-          version: service.data.version,
-        },
-        props: {
-          type: 'service',
-          ...service,
-        },
-      };
-    });
-  }
-
-  protected static async fetchData(params: any) {
-    const { id, version } = params;
-
-    if (!id || !version) {
-      return null;
-    }
-
-    // Get all items of the specified type
-    const items = await getServices();
-
-    // Find the specific item by id and version, and only if it has entities
-    const item = items.find((i) => i.data.id === id && i.data.version === version && serviceHasData(i));
-
-    if (!item) {
-      return null;
-    }
-
-    return item;
-  }
-
-  protected static createNotFoundResponse(): Response {
-    return new Response(null, {
-      status: 404,
-      statusText: 'Service data page not found',
-    });
-  }
-
-  static get clientAuthScript(): string {
-    if (!isAuthEnabled()) {
-      return '';
-    }
-
-    return `
-      if (typeof window !== 'undefined' && !import.meta.env.SSR) {
-        fetch('/api/auth/session')
-          .then(res => res.json())
-          .then(session => {
-            if (!session?.user) {
-              window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
-            }
-          })
-          .catch(() => {
-            window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
-          });
-      }
-    `;
-  }
-}
diff --git a/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/data/index.astro b/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/data/index.astro
deleted file mode 100644
index 7a69986aa..000000000
--- a/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/data/index.astro
+++ /dev/null
@@ -1,52 +0,0 @@
----
-import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
-import VisualiserLayout from '@layouts/VisualiserLayout.astro';
-import { buildUrl } from '@utils/url-builder';
-import { ClientRouter } from 'astro:transitions';
-
-import { Page } from './_index.data';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-// Get data
-const props = await Page.getData(Astro);
-
-const {
-  data: { id },
-  collection,
-} = props;
----
-
-<VisualiserLayout title={`Visualiser | ${props.data.name} (${props.collection})`} description={props.data.summary}>
-  <div class="bg-gray-100/50 m-4">
-    <div class="h-[calc(100vh-130px)] w-full relative border border-gray-200" id={`${id}-portal`} transition:animate="fade"></div>
-    <NodeGraph
-      id={id}
-      collection={`${collection}-containers`}
-      title={`${props.data.name} (v${props.data.version}) - Data`}
-      mode="full"
-      linkTo="visualiser"
-      version={props.data.version}
-      linksToVisualiser={false}
-      href={{
-        label: `Open documentation for ${props.data.name} v${props.data.version}`,
-        url: buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.version}`),
-      }}
-    />
-  </div>
-  <ClientRouter />
-</VisualiserLayout>
-
-<script define:vars={{ id }}>
-  document.addEventListener('DOMContentLoaded', () => {
-    const urlSearchParams = new URLSearchParams(window.location.search);
-    const params = Object.fromEntries(urlSearchParams.entries());
-    const embeded = params.embed === 'true' ? true : false;
-    const viewport = document.getElementById(`${id}-portal`);
-
-    if (embeded) {
-      viewport.style.height = 'calc(100vh - 30px)';
-    }
-  });
-</script>
diff --git a/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/index.astro b/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/index.astro
deleted file mode 100644
index ded83521c..000000000
--- a/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/index.astro
+++ /dev/null
@@ -1,54 +0,0 @@
----
-import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
-import VisualiserLayout from '@layouts/VisualiserLayout.astro';
-import type { PageTypes } from '@types';
-import { buildUrl } from '@utils/url-builder';
-import { ClientRouter } from 'astro:transitions';
-
-import { Page } from './_index.data';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-// Get data
-const props = await Page.getData(Astro);
-
-const {
-  data: { id },
-  collection,
-} = props;
----
-
-<VisualiserLayout title={`Visualiser | ${props.data.name} (${props.collection})`} description={props.data.summary}>
-  <div class="bg-gray-100/50 m-4">
-    <div class="h-[calc(100vh-130px)] w-full relative border border-gray-200" id={`${id}-portal`} transition:animate="fade"></div>
-    <NodeGraph
-      id={id}
-      collection={collection}
-      title={`${props.data.name} (v${props.data.version})`}
-      mode="full"
-      linkTo="visualiser"
-      version={props.data.version}
-      linksToVisualiser={false}
-      zoomOnScroll={true}
-      href={{
-        label: `Open documentation for ${props.data.name} v${props.data.version}`,
-        url: buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.version}`),
-      }}
-    />
-  </div>
-  <ClientRouter />
-</VisualiserLayout>
-
-<script define:vars={{ id }}>
-  document.addEventListener('DOMContentLoaded', () => {
-    const urlSearchParams = new URLSearchParams(window.location.search);
-    const params = Object.fromEntries(urlSearchParams.entries());
-    const embeded = params.embed === 'true' ? true : false;
-    const viewport = document.getElementById(`${id}-portal`);
-
-    if (embeded) {
-      viewport.style.height = 'calc(100vh - 30px)';
-    }
-  });
-</script>
diff --git a/eventcatalog/src/pages/visualiser/[type]/[id]/index.astro b/eventcatalog/src/pages/visualiser/[type]/[id]/index.astro
deleted file mode 100644
index b0c1156a7..000000000
--- a/eventcatalog/src/pages/visualiser/[type]/[id]/index.astro
+++ /dev/null
@@ -1,65 +0,0 @@
----
-import Seo from '@components/Seo.astro';
-import { buildUrl } from '@utils/url-builder';
-import { getEvents } from '@utils/events';
-import { getCommands } from '@utils/commands';
-import { getServices } from '@utils/collections/services';
-import { getDomains } from '@utils/collections/domains';
-import { getContainers } from '@utils/collections/containers';
-import type { CollectionEntry } from 'astro:content';
-import type { CollectionTypes } from '@types';
-
-export async function getStaticPaths() {
-  const [events, commands, services, domains, containers] = await Promise.all([
-    getEvents(),
-    getCommands(),
-    getServices(),
-    getDomains(),
-    getContainers(),
-  ]);
-
-  const resources = [...domains, ...events, ...services, ...commands, ...containers];
-  const resourcesWithVisualiserEnabled = resources.filter((resource) => resource.data.visualiser !== false);
-
-  const buildPages = (collection: CollectionEntry<CollectionTypes>[]) => {
-    return collection.map((item) => ({
-      params: {
-        type: item.collection,
-        id: item.data.id,
-      },
-      props: {
-        type: item.collection,
-        ...item,
-      },
-    }));
-  };
-
-  return [...buildPages(resourcesWithVisualiserEnabled)];
-}
-
-const props = Astro.props;
-const pageTitle = `${props.collection} | ${props.data.name}`.replace(/^\w/, (c) => c.toUpperCase());
-
-const { pathname } = Astro.url;
-
-const redirectUrl = buildUrl(pathname + '/' + props.data.latestVersion, false, true);
----
-
-<!doctype html>
-<html lang="en">
-  <head>
-    <Seo title={`EventCatalog | ${pageTitle}`} ogTitle={pageTitle} />
-  </head>
-  <body>
-    <p>You are being redirected to <a href={redirectUrl}>{redirectUrl}</a></p>
-  </body>
-</html>
-
-<script define:vars={{ redirectUrl }}>
-  document.addEventListener('DOMContentLoaded', () => {
-    // redirect with any search params too
-    const searchParams = window.location.search;
-    const fullRedirectUrl = redirectUrl + searchParams;
-    window.location.href = fullRedirectUrl;
-  });
-</script>
diff --git a/eventcatalog/src/pages/visualiser/context-map/index.astro b/eventcatalog/src/pages/visualiser/context-map/index.astro
deleted file mode 100644
index 42de5dbaa..000000000
--- a/eventcatalog/src/pages/visualiser/context-map/index.astro
+++ /dev/null
@@ -1,30 +0,0 @@
----
-import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
-import { ClientRouter } from 'astro:transitions';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
----
-
-<VerticalSideBarLayout title={`Visualiser | Bounded context map`}>
-  <div class="bg-gray-100/50 m-4">
-    <div
-      class="h-[calc(100vh-130px)] w-full relative border border-gray-200"
-      id={`domain-context-map-portal`}
-      transition:animate="fade"
-    >
-    </div>
-    <NodeGraph
-      id="domain-context-map"
-      collection="domain-context-map"
-      title="Bounded context map"
-      mode="full"
-      linkTo="visualiser"
-      version="1.0.0"
-      linksToVisualiser={false}
-      href={{
-        label: ``,
-        url: '/',
-      }}
-    />
-  </div>
-  <ClientRouter />
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/visualiser/designs/[id]/_index.data.ts b/eventcatalog/src/pages/visualiser/designs/[id]/_index.data.ts
deleted file mode 100644
index c7eb16096..000000000
--- a/eventcatalog/src/pages/visualiser/designs/[id]/_index.data.ts
+++ /dev/null
@@ -1,75 +0,0 @@
-import { HybridPage } from '@utils/page-loaders/hybrid-page';
-import { isAuthEnabled } from '@utils/feature';
-
-export class Page extends HybridPage {
-  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
-    if (isAuthEnabled()) {
-      return [];
-    }
-
-    const { getDesigns } = await import('@utils/collections/designs');
-
-    const designs = await getDesigns();
-
-    return designs.map((item) => ({
-      params: {
-        type: 'designs',
-        id: item.data.id,
-      },
-      props: {
-        type: 'designs',
-        ...item,
-      },
-    }));
-  }
-
-  protected static async fetchData(params: any) {
-    const { id } = params;
-
-    if (!id) {
-      return null;
-    }
-
-    const { getDesigns } = await import('@utils/collections/designs');
-    const designs = await getDesigns();
-
-    const design = designs.find((design) => design.data.id === id);
-
-    if (!design) {
-      return null;
-    }
-
-    return {
-      type: 'designs',
-      ...design,
-    };
-  }
-
-  protected static createNotFoundResponse(): Response {
-    return new Response(null, {
-      status: 404,
-      statusText: 'Design not found',
-    });
-  }
-
-  static get clientAuthScript(): string {
-    if (!isAuthEnabled()) {
-      return '';
-    }
-
-    return `
-      if (typeof window !== 'undefined' && !import.meta.env.SSR) {
-        fetch('/api/auth/session')
-          .then(res => res.json())
-          .then(session => {
-            if (!session?.user) {
-              window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
-            }
-          })
-          .catch(() => {
-            window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
-          });
-      }
-    `;
-  }
-}
diff --git a/eventcatalog/src/pages/visualiser/designs/[id]/index.astro b/eventcatalog/src/pages/visualiser/designs/[id]/index.astro
deleted file mode 100644
index f150250a7..000000000
--- a/eventcatalog/src/pages/visualiser/designs/[id]/index.astro
+++ /dev/null
@@ -1,31 +0,0 @@
----
-import NodeGraph from '@components/MDX/NodeGraph/NodeGraph';
-import { ClientRouter } from 'astro:transitions';
-import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
-
-import { Page } from './_index.data';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-const props = Astro.props;
-
-const { data } = props;
----
-
-<VerticalSideBarLayout title={`Visualiser | Bounded context map`}>
-  <div class="bg-gray-100/50 m-4">
-    <div class="h-[calc(100vh-130px)] w-full relative border border-gray-200" id={`${data.id}-portal`} transition:animate="fade">
-    </div>
-    <NodeGraph
-      id={data.id}
-      nodes={data.nodes}
-      edges={data.edges}
-      title={data.name}
-      client:only="react"
-      mode="full"
-      linkTo="visualiser"
-    />
-  </div>
-  <ClientRouter />
-</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/visualiser/domain-integrations/index.astro b/eventcatalog/src/pages/visualiser/domain-integrations/index.astro
deleted file mode 100644
index 04aa7236c..000000000
--- a/eventcatalog/src/pages/visualiser/domain-integrations/index.astro
+++ /dev/null
@@ -1,31 +0,0 @@
----
-import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
-import VisualiserLayout from '@layouts/VisualiserLayout.astro';
-import { buildUrl } from '@utils/url-builder';
-import { ClientRouter } from 'astro:transitions';
----
-
-<VisualiserLayout title={`Visualiser | Domain Architecture`} description="High-level view of all domains and their relationships">
-  <div class="bg-gray-100/50 m-4">
-    <div
-      class="h-[calc(100vh-130px)] w-full relative border border-gray-200"
-      id="domains-canvas-portal"
-      transition:animate="fade"
-    >
-    </div>
-    <NodeGraph
-      id="domains-canvas"
-      collection="domains-canvas"
-      title="Domain Integration Map"
-      mode="full"
-      linkTo="visualiser"
-      version="1.0.0"
-      linksToVisualiser={false}
-      href={{
-        label: 'View Documentation',
-        url: buildUrl('/docs'),
-      }}
-    />
-  </div>
-  <ClientRouter />
-</VisualiserLayout>
diff --git a/eventcatalog/src/pages/visualiser/domains/[id]/[version]/entity-map/index.astro b/eventcatalog/src/pages/visualiser/domains/[id]/[version]/entity-map/index.astro
deleted file mode 100644
index 90d913f77..000000000
--- a/eventcatalog/src/pages/visualiser/domains/[id]/[version]/entity-map/index.astro
+++ /dev/null
@@ -1,52 +0,0 @@
----
-import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
-import VisualiserLayout from '@layouts/VisualiserLayout.astro';
-import { buildUrl } from '@utils/url-builder';
-import { ClientRouter } from 'astro:transitions';
-
-import { Page } from './_index.data';
-
-export const prerender = Page.prerender;
-export const getStaticPaths = Page.getStaticPaths;
-
-// Get data
-const props = await Page.getData(Astro);
-
-const {
-  data: { id },
-  collection,
-} = props;
----
-
-<VisualiserLayout title={`Visualiser | ${props.data.name} (${props.collection})`} description={props.data.summary}>
-  <div class="bg-gray-100/50 m-4">
-    <div class="h-[calc(100vh-130px)] w-full relative border border-gray-200" id={`${id}-portal`} transition:animate="fade"></div>
-    <NodeGraph
-      id={id}
-      collection={`${collection}-entities`}
-      title={`${props.data.name} (v${props.data.version}) - Entity Map`}
-      mode="full"
-      linkTo="visualiser"
-      version={props.data.version}
-      linksToVisualiser={false}
-      href={{
-        label: `Open documentation for ${props.data.name} v${props.data.version}`,
-        url: buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.version}`),
-      }}
-    />
-  </div>
-  <ClientRouter />
-</VisualiserLayout>
-
-<script define:vars={{ id }}>
-  document.addEventListener('DOMContentLoaded', () => {
-    const urlSearchParams = new URLSearchParams(window.location.search);
-    const params = Object.fromEntries(urlSearchParams.entries());
-    const embeded = params.embed === 'true' ? true : false;
-    const viewport = document.getElementById(`${id}-portal`);
-
-    if (embeded) {
-      viewport.style.height = 'calc(100vh - 30px)';
-    }
-  });
-</script>
diff --git a/eventcatalog/src/remark-plugins/directives.ts b/eventcatalog/src/remark-plugins/directives.ts
deleted file mode 100644
index 848136eb8..000000000
--- a/eventcatalog/src/remark-plugins/directives.ts
+++ /dev/null
@@ -1,109 +0,0 @@
-// src/remark-plugins/directives.js
-import { visit } from 'unist-util-visit';
-
-export function remarkDirectives() {
-  return (tree: any) => {
-    visit(tree, (node) => {
-      if (node.type === 'containerDirective') {
-        const blockTypes = {
-          info: 'bg-blue-50 border-l-4 border-blue-500',
-          warning: 'bg-yellow-50 border-l-4 border-yellow-500',
-          danger: 'bg-red-50 border-l-4 border-red-500',
-          tip: 'bg-green-50 border-l-4 border-green-500',
-          note: 'bg-gray-50 border-l-4 border-gray-500',
-        };
-
-        // Lucide icon paths
-        const iconPaths = {
-          info: 'M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z',
-          warning:
-            'M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z',
-          danger:
-            'M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z',
-          tip: 'M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z',
-          note: 'M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z',
-        };
-
-        node.data = node.data || {};
-        node.data.hName = 'div';
-        node.data.hProperties = {
-          class: `rounded-lg p-4 my-4 ${blockTypes[node.name as keyof typeof blockTypes] || ''}`,
-        };
-
-        // Create header div that will contain icon and type
-        const headerNode = {
-          type: 'element',
-          data: {
-            hName: 'div',
-            hProperties: {
-              class: 'flex items-center gap-2 font-semibold mb-2',
-            },
-          },
-          children: [
-            // Lucide Icon SVG
-            {
-              type: 'element',
-              data: {
-                hName: 'svg',
-                hProperties: {
-                  xmlns: 'http://www.w3.org/2000/svg',
-                  width: '26',
-                  height: '26',
-                  viewBox: '0 0 24 24',
-                  fill: 'none',
-                  stroke: 'currentColor',
-                  strokeWidth: '2',
-                  strokeLinecap: 'round',
-                  strokeLinejoin: 'round',
-                  class: 'lucide',
-                },
-              },
-              children: [
-                {
-                  type: 'element',
-                  data: {
-                    hName: 'path',
-                    hProperties: {
-                      d: iconPaths[node.name as keyof typeof iconPaths] || '',
-                    },
-                  },
-                },
-              ],
-            },
-            // Type label
-            {
-              type: 'element',
-              data: {
-                hName: 'span',
-                hProperties: {
-                  class: '',
-                },
-              },
-              children: [
-                {
-                  type: 'text',
-                  value: node.name.charAt(0).toUpperCase() + node.name.slice(1),
-                },
-              ],
-            },
-          ],
-        };
-
-        // Create content div for the rest of the children
-        const contentNode = {
-          type: 'element',
-          data: {
-            hName: 'div',
-            hProperties: {
-              class: 'prose prose-md w-full !max-w-none ',
-            },
-          },
-          children: node.children,
-        };
-
-        // Replace node's children with header and content
-        node.children = [headerNode, contentNode];
-      }
-    });
-  };
-}
diff --git a/eventcatalog/src/remark-plugins/mermaid.ts b/eventcatalog/src/remark-plugins/mermaid.ts
deleted file mode 100644
index 53892912b..000000000
--- a/eventcatalog/src/remark-plugins/mermaid.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import type { RemarkPlugin } from '@astrojs/markdown-remark';
-import { visit } from 'unist-util-visit';
-
-const escapeMap: Record<string, string> = {
-  '&': '&amp;',
-  '<': '&lt;',
-  '>': '&gt;',
-  '"': '&quot;',
-  "'": '&#39;',
-};
-
-const escapeHtml = (str: string) => str.replace(/[&<>"']/g, (c) => escapeMap[c]);
-
-export const mermaid: RemarkPlugin<[]> = () => (tree) => {
-  visit(tree, 'code', (node) => {
-    if (node.lang !== 'mermaid') return;
-
-    // @ts-ignore test
-    node.type = 'html';
-    node.value = `
-    <div class="mermaid-block pb-4">
-      <div class="mermaid border border-gray-200 rounded-lg p-1" data-content="${escapeHtml(node.value)}">
-        <p>Loading graph...</p>
-      </div>
-    </div>
-    `;
-  });
-};
diff --git a/eventcatalog/src/types/index.ts b/eventcatalog/src/types/index.ts
deleted file mode 100644
index ee37f197e..000000000
--- a/eventcatalog/src/types/index.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-export type CollectionTypes =
-  | 'commands'
-  | 'events'
-  | 'queries'
-  | 'domains'
-  | 'services'
-  | 'flows'
-  | 'channels'
-  | 'entities'
-  | 'containers';
-export type CollectionMessageTypes = 'commands' | 'events' | 'queries';
-export type CollectionUserTypes = 'users';
-export type PageTypes =
-  | 'events'
-  | 'commands'
-  | 'queries'
-  | 'services'
-  | 'domains'
-  | 'channels'
-  | 'flows'
-  | 'entities'
-  | 'containers';
-
-export type TableConfiguration = {
-  columns: {
-    [key: string]: {
-      label?: string;
-      visible?: boolean;
-    };
-  };
-};
diff --git a/eventcatalog/src/types/react-syntax-highlighter.d.ts b/eventcatalog/src/types/react-syntax-highlighter.d.ts
deleted file mode 100644
index 1ffa9de38..000000000
--- a/eventcatalog/src/types/react-syntax-highlighter.d.ts
+++ /dev/null
@@ -1 +0,0 @@
-declare module 'react-syntax-highlighter/dist/esm/styles/prism/material-light';
diff --git a/eventcatalog/src/utils/__tests__/collections/util.spec.ts b/eventcatalog/src/utils/__tests__/collections/util.spec.ts
deleted file mode 100644
index e8623d71a..000000000
--- a/eventcatalog/src/utils/__tests__/collections/util.spec.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import type { CollectionTypes } from '@types';
-import { getDeprecatedDetails, isSameVersion, satisfies, sortStringVersions } from '@utils/collections/util';
-import type { CollectionEntry } from 'astro:content';
-import { describe, it, expect } from 'vitest';
-
-describe('Collections - utils', () => {
-  describe('satisfies', () => {
-    it.each([
-      [{ version: '1.0.0', range: '1.0.0', expected: true }],
-      [{ version: '1.0.0', range: '^1', expected: true }],
-      [{ version: '1.0.0', range: '1', expected: true }],
-      [{ version: '1.0.0', range: 'v1', expected: true }],
-      [{ version: '1.0.0', range: '>1', expected: false }],
-      [{ version: '1', range: '1', expected: true }],
-      [{ version: '1', range: '^1', expected: true }],
-      [{ version: '1', range: '1.0.0', expected: true }],
-      [{ version: '1', range: 'v1', expected: true }],
-      [{ version: '1', range: '<1', expected: false }],
-      [{ version: '2', range: 'v1', expected: false }],
-      [{ version: 'v1', range: 'v1', expected: true }],
-      [{ version: 'v1', range: '1', expected: true }],
-      [{ version: 'v1', range: '1.0.0', expected: true }],
-      [{ version: 'v1', range: '^1', expected: true }],
-      [{ version: 'v1', range: '2', expected: false }],
-      [{ version: 'v1', range: '>1', expected: false }],
-    ])('should returns $expected to version as $version and range as $range', ({ expected, version, range }) => {
-      expect(satisfies(version, range)).toBe(expected);
-    });
-  });
-
-  describe('sortStringVersions', () => {
-    it.each([
-      [{ versions: ['1', '3', '2'], result: ['3', '2', '1'], latest: '3' }],
-      [{ versions: ['10', '1', '2', '3'], result: ['10', '3', '2', '1'], latest: '10' }],
-      [{ versions: ['1.0.1', '1.1.0', '1.0.2'], result: ['1.1.0', '1.0.2', '1.0.1'], latest: '1.1.0' }],
-      [{ versions: ['a', 'c', 'b'], result: ['c', 'b', 'a'], latest: 'c' }],
-      [{ versions: [], result: [], latest: undefined }],
-    ])('should returns $latest as latest version of $versions', ({ versions, result, latest }) => {
-      expect(sortStringVersions(versions)).toEqual({ versions: result, latestVersion: latest });
-    });
-  });
-
-  describe('isSameVersion', () => {
-    it.each([
-      [{ versions: ['1', '2'], result: false }],
-      [{ versions: ['1', '1'], result: true }],
-      [{ versions: ['2.0.0', '1.1.0'], result: false }],
-      [{ versions: ['2.0.0', '2.0.0'], result: true }],
-      [{ versions: ['a', 'b'], result: false }],
-      [{ versions: ['a', 'a'], result: true }],
-      [{ versions: ['1.0.0', undefined], result: false }],
-    ])('should returns $result when versions is $versions', ({ versions, result }) => {
-      expect(isSameVersion(versions[0], versions[1])).toBe(result);
-    });
-  });
-
-  describe('getDeprecatedDetails', () => {
-    it('returns false when deprecated is false', () => {
-      const result = getDeprecatedDetails({ data: { deprecated: false } } as unknown as CollectionEntry<CollectionTypes>);
-      expect(result).toEqual({ hasDeprecated: false, isMarkedAsDeprecated: false, message: '', deprecatedDate: '' });
-    });
-
-    it('returns true when deprecated is true (boolean)', () => {
-      const result = getDeprecatedDetails({ data: { deprecated: true } } as unknown as CollectionEntry<CollectionTypes>);
-      expect(result).toEqual({ hasDeprecated: true, isMarkedAsDeprecated: true, message: '', deprecatedDate: '' });
-    });
-
-    it('returns true when deprecated is true (object)', () => {
-      const result = getDeprecatedDetails({
-        data: { deprecated: { date: '2021-01-01', message: 'This is a test message' } },
-      } as unknown as CollectionEntry<CollectionTypes>);
-      expect(result).toEqual({
-        hasDeprecated: true,
-        isMarkedAsDeprecated: true,
-        message: 'This is a test message',
-        deprecatedDate: 'January 1, 2021',
-      });
-    });
-  });
-});
diff --git a/eventcatalog/src/utils/__tests__/commands/mocks.ts b/eventcatalog/src/utils/__tests__/commands/mocks.ts
deleted file mode 100644
index 2bb0cdfbf..000000000
--- a/eventcatalog/src/utils/__tests__/commands/mocks.ts
+++ /dev/null
@@ -1,170 +0,0 @@
-export const mockServices = [
-  {
-    id: 'OrderService',
-    slug: 'OrderService',
-    collection: 'services',
-    data: {
-      id: 'OrderService',
-      version: '0.0.1',
-      sends: [
-        {
-          id: 'AdjustOrder',
-          version: '0.0.1',
-        },
-      ],
-      receives: [
-        {
-          id: 'PlaceOrder',
-          version: '>1.5.0',
-        },
-        {
-          id: 'GetOrder',
-          version: '0.0.1',
-          from: [
-            {
-              id: 'EmailChannel',
-              version: '1.0.0',
-            },
-          ],
-        },
-      ],
-    },
-  },
-  {
-    id: 'PaymentService',
-    slug: 'PaymentService',
-    collection: 'services',
-    data: {
-      id: 'PaymentService',
-      version: '0.0.1',
-      sends: [
-        {
-          id: 'PlaceOrder',
-          version: '0.0.1',
-          to: [
-            {
-              id: 'EmailChannel',
-              version: '1.0.0',
-            },
-          ],
-        },
-        {
-          id: 'GetOrder',
-          version: '0.0.1',
-          to: [
-            {
-              id: 'EmailChannel',
-              version: '1.0.0',
-            },
-          ],
-        },
-      ],
-      receives: [
-        {
-          id: 'AdjustOrder',
-          version: '0.0.1',
-        },
-      ],
-    },
-  },
-  {
-    id: 'InventoryService',
-    slug: 'InventoryService',
-    collection: 'services',
-    data: {
-      id: 'InventoryService',
-      version: '0.0.1',
-      sends: [{ id: 'NotifyLowStock' }],
-    },
-  },
-  {
-    id: 'NotificationService',
-    slug: 'NotificationService',
-    collection: 'services',
-    data: {
-      id: 'NotificationService',
-      version: '0.0.1',
-      receives: [{ id: 'NotifyLowStock', version: 'latest' }],
-    },
-  },
-  {
-    id: 'LegacyOrderService',
-    slug: 'LegacyOrderService',
-    collection: 'services',
-    data: {
-      id: 'LegacyOrderService',
-      version: '0.0.1',
-      receives: [{ id: 'GetOrder', version: 'latest' }],
-      sends: [{ id: 'GetOrder', version: 'latest' }],
-    },
-  },
-];
-
-export const mockCommands = [
-  {
-    id: 'AdjustOrder',
-    slug: 'AdjustOrder',
-    collection: 'commands',
-    data: {
-      id: 'AdjustOrder',
-      version: '0.0.1',
-    },
-  },
-  {
-    id: 'PlaceOrder',
-    slug: 'PlaceOrder',
-    collection: 'commands',
-    data: {
-      id: 'PlaceOrder',
-      version: '1.5.1',
-    },
-  },
-  {
-    id: 'PlaceOrder',
-    slug: 'PlaceOrder',
-    collection: 'commands',
-    data: {
-      id: 'PlaceOrder',
-      version: '2.0.1',
-    },
-  },
-  {
-    id: 'NotifyLowStock',
-    slug: 'NotifyLowStock',
-    collection: 'commands',
-    data: {
-      id: 'NotifyLowStock',
-      version: '2.0.0',
-    },
-  },
-  {
-    id: 'NotifyLowStock',
-    slug: 'NotifyLowStock',
-    collection: 'commands',
-    data: {
-      id: 'NotifyLowStock',
-      version: '2.0.1',
-    },
-  },
-  {
-    id: 'GetOrder',
-    slug: 'GetOrder',
-    collection: 'commands',
-    data: {
-      id: 'GetOrder',
-      version: '0.0.1',
-    },
-  },
-];
-
-export const mockChannels = [
-  {
-    id: 'EmailChannel',
-    slug: 'EmailChannel',
-    collection: 'channels',
-    data: {
-      id: 'EmailChannel',
-      version: '1.0.0',
-    },
-  },
-];
diff --git a/eventcatalog/src/utils/__tests__/commands/node-graph.spec.ts b/eventcatalog/src/utils/__tests__/commands/node-graph.spec.ts
deleted file mode 100644
index b2b8567f6..000000000
--- a/eventcatalog/src/utils/__tests__/commands/node-graph.spec.ts
+++ /dev/null
@@ -1,343 +0,0 @@
-import { MarkerType } from '@xyflow/react';
-import { getNodesAndEdgesForCommands as getNodesAndEdges } from '../../node-graphs/message-node-graph';
-import { expect, describe, it, vi } from 'vitest';
-import { mockCommands, mockServices, mockChannels } from './mocks';
-
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    // this will only affect "foo" outside of the original module
-    getCollection: (key: string) => {
-      if (key === 'services') {
-        return Promise.resolve(mockServices);
-      }
-      if (key === 'commands') {
-        return Promise.resolve(mockCommands);
-      }
-      if (key === 'channels') {
-        return Promise.resolve(mockChannels);
-      }
-      return Promise.resolve([]);
-    },
-  };
-});
-
-describe('Commands NodeGraph', () => {
-  describe('getNodesAndEdges', () => {
-    it('should return nodes and edges for a given command', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'AdjustOrder', version: '0.0.1' });
-
-      // The middle node itself, the service
-      const expectedCommandNode = {
-        id: 'AdjustOrder-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        type: 'commands',
-      };
-
-      const expectedProducerNode = {
-        id: 'OrderService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[0].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedConsumerNode = {
-        id: 'PaymentService-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: {
-          title: 'PaymentService',
-          mode: 'simple',
-          service: { ...mockServices[1].data },
-        },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        expect.objectContaining({
-          id: 'OrderService-0.0.1-AdjustOrder-0.0.1',
-          source: 'OrderService-0.0.1',
-          target: 'AdjustOrder-0.0.1',
-          label: 'invokes',
-        }),
-        expect.objectContaining({
-          id: 'AdjustOrder-0.0.1-PaymentService-0.0.1',
-          source: 'AdjustOrder-0.0.1',
-          target: 'PaymentService-0.0.1',
-          label: 'accepts',
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedConsumerNode),
-
-          // The command node itself
-          expect.objectContaining(expectedCommandNode),
-
-          // Nodes on the right
-          expect.objectContaining(expectedProducerNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('if the command is produced and consumed by a service it will render a custom edge', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'GetOrder', version: '0.0.1' });
-
-      // The middle node itself, the service
-      const expectedCommandNode = {
-        id: 'GetOrder-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', message: expect.anything() },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'commands',
-      };
-
-      const expectedProducerNode = {
-        id: 'LegacyOrderService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[4].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedConsumerNode = {
-        id: 'LegacyOrderService-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: {
-          title: 'LegacyOrderService',
-          mode: 'simple',
-          service: { ...mockServices[4].data },
-        },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        expect.objectContaining({
-          id: 'LegacyOrderService-0.0.1-GetOrder-0.0.1',
-          source: 'LegacyOrderService-0.0.1',
-          target: 'GetOrder-0.0.1',
-          label: 'invokes',
-          animated: false,
-        }),
-        expect.objectContaining({
-          id: 'GetOrder-0.0.1-LegacyOrderService-0.0.1',
-          source: 'GetOrder-0.0.1',
-          target: 'LegacyOrderService-0.0.1',
-          label: 'accepts',
-          animated: false,
-        }),
-        expect.objectContaining({
-          id: 'GetOrder-0.0.1-LegacyOrderService-0.0.1-both',
-          source: 'GetOrder-0.0.1',
-          target: 'LegacyOrderService-0.0.1',
-          label: 'publishes and subscribes',
-          animated: false,
-          markerEnd: {
-            type: MarkerType.ArrowClosed,
-            width: 40,
-            height: 40,
-          },
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedConsumerNode),
-
-          // The event node itself
-          expect.objectContaining(expectedCommandNode),
-
-          // Nodes on the right
-          expect.objectContaining(expectedProducerNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('if the consumer of a command has defined a channel, it will render the channel node and edges', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'GetOrder', version: '0.0.1' });
-
-      const expectedConsumerNode = {
-        id: 'OrderService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[0].data }, title: 'OrderService' },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedChannelNode = {
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        id: 'EmailChannel-1.0.0',
-        type: 'channels',
-      };
-
-      const expectedCommandNode = {
-        id: 'GetOrder-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        type: 'commands',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        // Message to the channel
-        expect.objectContaining({
-          id: 'GetOrder-0.0.1-EmailChannel-1.0.0',
-          source: 'GetOrder-0.0.1',
-          target: 'EmailChannel-1.0.0',
-        }),
-        // Channel to the consumer
-        expect.objectContaining({
-          id: 'EmailChannel-1.0.0-OrderService-0.0.1',
-          source: 'EmailChannel-1.0.0',
-          target: 'OrderService-0.0.1',
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedConsumerNode),
-
-          // channel
-          expect.objectContaining(expectedChannelNode),
-
-          // The command node itself
-          expect.objectContaining(expectedCommandNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('if the producer of an event has defined a channel, it will render the channel node and edges', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'GetOrder', version: '0.0.1' });
-
-      const expectedProducerNode = {
-        id: 'PaymentService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedChannelNode = {
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        id: 'EmailChannel-1.0.0',
-        type: 'channels',
-      };
-
-      const expectedCommandNode = {
-        id: 'GetOrder-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        type: 'commands',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        // Producer to the message
-        expect.objectContaining({
-          id: 'PaymentService-0.0.1-GetOrder-0.0.1',
-          source: 'PaymentService-0.0.1',
-          target: 'GetOrder-0.0.1',
-          label: 'invokes',
-          animated: false,
-        }),
-        // Message to the channel
-        expect.objectContaining({
-          id: 'GetOrder-0.0.1-EmailChannel-1.0.0',
-          source: 'GetOrder-0.0.1',
-          target: 'EmailChannel-1.0.0',
-          label: 'routes to',
-          animated: false,
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedProducerNode),
-
-          // channel
-          expect.objectContaining(expectedChannelNode),
-
-          // The command node itself
-          expect.objectContaining(expectedCommandNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('returns an empty array if no commands are found', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownCommand', version: '1.0.0' });
-
-      expect(nodes).toEqual([]);
-      expect(edges).toEqual([]);
-    });
-
-    it('should return nodes and edges for a given event using semver range', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'PlaceOrder', version: '2.0.1' });
-
-      // The middle node itself, the service
-      const expectedCommandNode = {
-        id: 'PlaceOrder-2.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', message: expect.anything() },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'commands',
-      };
-
-      const expectedConsumerNode = {
-        id: 'OrderService-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: {
-          title: 'OrderService',
-          mode: 'simple',
-          service: { ...mockServices[0].data },
-        },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        expect.objectContaining({
-          id: 'PlaceOrder-2.0.1-OrderService-0.0.1',
-          source: 'PlaceOrder-2.0.1',
-          target: 'OrderService-0.0.1',
-          label: 'accepts',
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // The command node itself
-          expect.objectContaining(expectedCommandNode),
-
-          // Nodes on the Right
-          expect.objectContaining(expectedConsumerNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-  });
-});
diff --git a/eventcatalog/src/utils/__tests__/containers/mocks.ts b/eventcatalog/src/utils/__tests__/containers/mocks.ts
deleted file mode 100644
index a15a3879d..000000000
--- a/eventcatalog/src/utils/__tests__/containers/mocks.ts
+++ /dev/null
@@ -1,240 +0,0 @@
-export const mockEvents = [
-  {
-    slug: 'PaymentInitiated',
-    collection: 'events',
-    data: {
-      id: 'PaymentInitiated',
-      version: '0.0.1',
-    },
-  },
-  {
-    slug: 'PaymentProcessed',
-    collection: 'events',
-    data: {
-      id: 'PaymentProcessed',
-      version: '0.0.1',
-    },
-  },
-];
-
-export const mockServices = [
-  {
-    slug: 'SubscriptionService',
-    collection: 'services',
-    data: {
-      id: 'SubscriptionService',
-      version: '0.0.1',
-    },
-  },
-  {
-    slug: 'PaymentService',
-    collection: 'services',
-    data: {
-      id: 'PaymentService',
-      version: '0.0.1',
-    },
-  },
-];
-
-export const mockContainers = [
-  {
-    id: 'OrderDatabase',
-    collection: 'containers',
-    data: {
-      id: 'OrderDatabase',
-      version: '1.0.0',
-      servicesThatWriteToContainer: [
-        {
-          id: 'SubscriptionService',
-          version: '0.0.1',
-          data: {
-            id: 'SubscriptionService',
-            version: '0.0.1',
-          },
-        },
-      ],
-      servicesThatReadFromContainer: [
-        {
-          id: 'SubscriptionService',
-          version: '0.0.1',
-          data: {
-            id: 'SubscriptionService',
-            version: '0.0.1',
-          },
-        },
-      ],
-    },
-  },
-];
-
-export const mockFlow = [
-  {
-    id: 'Payment/PaymentProcessed/index.mdx',
-    slug: 'payment/paymentprocessed',
-    body: '',
-    collection: 'flows',
-    data: {
-      steps: [
-        {
-          id: 1,
-          type: 'node',
-          title: 'Order Placed',
-          next_step: {
-            id: 2,
-            label: 'Proceed to payment',
-          },
-        },
-        {
-          id: 2,
-          title: 'Payment Initiated',
-          message: {
-            id: 'PaymentInitiated',
-            version: '0.0.1',
-          },
-          next_steps: [
-            {
-              id: 3,
-              label: 'Payment successful',
-            },
-            {
-              id: 4,
-              label: 'Payment failed',
-            },
-          ],
-        },
-        {
-          id: 3,
-          title: 'Payment Processed',
-          message: {
-            id: 'PaymentProcessed',
-            version: '0.0.1',
-          },
-        },
-        {
-          id: 4,
-          type: 'node',
-          title: 'Payment Failed',
-        },
-      ],
-      id: 'PaymentFlow',
-      name: 'Payment Flow for E-commerce',
-      summary: 'Business flow for processing payments in an e-commerce platform',
-      version: '1.0.0',
-      type: 'node',
-    },
-  },
-];
-
-export const mockFlowByIds = [
-  {
-    id: 'Payment/PaymentProcessed/index.mdx',
-    slug: 'payment/paymentprocessed',
-    body: '',
-    collection: 'flows',
-    data: {
-      steps: [
-        {
-          id: 1,
-          type: 'node',
-          title: 'Order Placed',
-          next_step: 2,
-        },
-        {
-          id: 2,
-          title: 'Payment Initiated',
-          message: {
-            id: 'PaymentInitiated',
-            version: '0.0.1',
-          },
-          next_steps: [3, 4],
-        },
-        {
-          id: 3,
-          title: 'Payment Processed',
-          message: {
-            id: 'PaymentProcessed',
-            version: '0.0.1',
-          },
-        },
-        {
-          id: 4,
-          type: 'node',
-          title: 'Payment Failed',
-        },
-      ],
-      id: 'PaymentFlow',
-      name: 'Payment Flow for E-commerce',
-      summary: 'Business flow for processing payments in an e-commerce platform',
-      version: '1.0.0',
-      type: 'node',
-    },
-  },
-  {
-    id: 'Subscriptions/CancelSubscription/index.mdx',
-    slug: 'subscriptions/CancelSubscription',
-    body: '',
-    collection: 'flows',
-    data: {
-      steps: [
-        {
-          id: 'cancel_subscription_initiated',
-          title: 'Cancels Subscription',
-          actor: {
-            name: 'User',
-          },
-          next_step: {
-            id: 'cancel_subscription_request',
-            label: 'Initiate subscription cancellation',
-          },
-        },
-        {
-          id: 'cancel_subscription_request',
-          title: 'Cancel Subscription',
-          message: {
-            id: 'CancelSubscription',
-            version: '0.0.1',
-          },
-          next_step: {
-            id: 'subscription_service',
-            label: 'Proceed to subscription service',
-          },
-        },
-        {
-          id: 'subscription_service',
-          title: 'Subscription Service',
-          service: {
-            id: 'SubscriptionService',
-            version: 'latest',
-          },
-          next_steps: [
-            {
-              id: 'subscription_cancelled',
-              label: 'Successful cancellation',
-            },
-            {
-              id: 'subscription_rejected',
-              label: 'Failed cancellation',
-            },
-          ],
-        },
-        {
-          id: 'subscription_cancelled',
-          title: 'Subscription has been cancelled',
-          message: {
-            id: 'UserSubscriptionCancelled',
-            version: '0.0.1',
-          },
-        },
-        {
-          id: 'subscription_rejected',
-          title: 'Subscription cancellation has been rejected',
-        },
-      ],
-      id: 'CancelSubscription',
-      name: 'User Cancels Subscription',
-      summary: 'Flow for when a user has cancelled a subscription',
-      version: '1.0.0',
-      // type: 'node',
-    },
-  },
-];
diff --git a/eventcatalog/src/utils/__tests__/containers/node-graph.spec.ts b/eventcatalog/src/utils/__tests__/containers/node-graph.spec.ts
deleted file mode 100644
index c2e8fe2bd..000000000
--- a/eventcatalog/src/utils/__tests__/containers/node-graph.spec.ts
+++ /dev/null
@@ -1,106 +0,0 @@
-import { getNodesAndEdges } from '../../node-graphs/container-node-graph';
-import { expect, describe, it, vi, beforeEach } from 'vitest';
-import { mockContainers, mockServices } from './mocks';
-
-vi.mock('@utils/collections/containers', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('@utils/collections/containers')>()),
-    getContainers: () => Promise.resolve(mockContainers),
-  };
-});
-
-describe('Containers NodeGraph', () => {
-  beforeEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  describe('getNodesAndEdges', () => {
-    it('should return the correct nodes and edges for a given container', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'OrderDatabase', version: '1.0.0' });
-
-      expect(nodes).toEqual([
-        {
-          id: 'SubscriptionService-0.0.1',
-          type: undefined,
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          data: { mode: 'simple', service: { ...mockServices[0].data } },
-          position: { x: 75, y: 50 },
-        },
-        {
-          id: 'OrderDatabase-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          data: { mode: 'simple', data: { ...mockContainers[0].data } },
-          position: { x: 525, y: 50 },
-          type: 'data',
-        },
-        {
-          id: 'SubscriptionService-0.0.1',
-          sourcePosition: 'left',
-          targetPosition: 'right',
-          data: { title: 'SubscriptionService', mode: 'simple', service: { ...mockServices[0].data } },
-          position: { x: 75, y: 50 },
-          type: undefined,
-        },
-      ]);
-
-      expect(edges).toEqual([
-        {
-          label: 'reads from \n (undefined)',
-          animated: false,
-          style: {
-            strokeWidth: 1,
-          },
-          id: 'SubscriptionService-0.0.1-OrderDatabase-1.0.0',
-          source: 'OrderDatabase-1.0.0',
-          target: 'SubscriptionService-0.0.1',
-          data: {
-            service: {
-              id: 'SubscriptionService',
-              version: '0.0.1',
-              data: {
-                id: 'SubscriptionService',
-                version: '0.0.1',
-              },
-            },
-          },
-          type: 'multiline',
-          markerStart: {
-            type: 'arrowclosed',
-            width: 40,
-            height: 40,
-          },
-        },
-        {
-          label: 'read and writes to \n (undefined)',
-          animated: false,
-          markerEnd: {
-            type: 'arrowclosed',
-            width: 40,
-            height: 40,
-          },
-          style: {
-            strokeWidth: 1,
-          },
-          id: 'OrderDatabase-1.0.0-SubscriptionService-0.0.1-both',
-          source: 'SubscriptionService-0.0.1',
-          target: 'OrderDatabase-1.0.0',
-          type: 'multiline',
-          markerStart: {
-            type: 'arrowclosed',
-            width: 40,
-            height: 40,
-          },
-        },
-      ]);
-    });
-
-    it('returns empty nodes and edges if no container is found', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownContainer', version: '1.0.0' });
-
-      expect(nodes).toEqual([]);
-      expect(edges).toEqual([]);
-    });
-  });
-});
diff --git a/eventcatalog/src/utils/__tests__/domains/domains.spec.ts b/eventcatalog/src/utils/__tests__/domains/domains.spec.ts
deleted file mode 100644
index 41a379521..000000000
--- a/eventcatalog/src/utils/__tests__/domains/domains.spec.ts
+++ /dev/null
@@ -1,254 +0,0 @@
-import type { ContentCollectionKey } from 'astro:content';
-import { expect, describe, it, vi } from 'vitest';
-import { mockDomains, mockServices, mockEvents, mockCommands, mockUbiquitousLanguages } from './mocks';
-import {
-  domainHasEntities,
-  getDomains,
-  getDomainsForService,
-  getParentDomains,
-  getUbiquitousLanguage,
-  getUbiquitousLanguageWithSubdomains,
-} from '../../collections/domains';
-import type { Service } from '@utils/collections/services';
-import type { Domain } from '@utils/collections/domains';
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    // this will only affect "foo" outside of the original module
-    getCollection: (key: ContentCollectionKey, filter?: any) => {
-      switch (key) {
-        case 'domains':
-          return Promise.resolve(mockDomains);
-        case 'services':
-          return Promise.resolve(mockServices);
-        case 'events':
-          return Promise.resolve(mockEvents);
-        case 'commands':
-          return Promise.resolve(mockCommands);
-        case 'ubiquitousLanguages':
-          let result = mockUbiquitousLanguages;
-          if (filter) {
-            result = mockUbiquitousLanguages.filter(filter);
-          }
-          return Promise.resolve(result);
-        default:
-          return Promise.resolve([]);
-      }
-    },
-  };
-});
-
-describe('Domains', () => {
-  describe('getDomains', () => {
-    it('should returns an array of domains with services using semver or latest', async () => {
-      const domains = await getDomains();
-
-      const expectedDomains = [
-        // Checkout
-        {
-          ...mockDomains[1],
-          data: expect.objectContaining({ services: [mockServices[2], mockServices[3]] }),
-        },
-        // Notification
-        {
-          ...mockDomains[2],
-          data: expect.objectContaining({ services: [] }),
-        },
-      ];
-
-      expect(domains).toEqual(expect.arrayContaining(expectedDomains.map((d) => expect.objectContaining(d))));
-    });
-  });
-
-  describe('ubiquitous-language', () => {
-    it('should return the ubiquitous-language for a domain', async () => {
-      const domains = await getDomains();
-      const shippingDomain = domains.find((d) => d.data.id === 'Shipping');
-      const ubiquitousLanguages = await getUbiquitousLanguage(shippingDomain!);
-      expect(ubiquitousLanguages).toEqual([
-        {
-          id: 'domains/Shipping/ubiquitous-language.mdx',
-          slug: 'domains/Shipping/ubiquitous-language',
-          collection: 'ubiquitousLanguages',
-          filePath: 'domains/Shipping/ubiquitous-language.mdx',
-          data: {
-            id: 'Shipping',
-            dictionary: [
-              {
-                id: 'Payment',
-                name: 'Payment',
-                summary: 'A financial transaction',
-              },
-              {
-                id: 'Order',
-                name: 'Order',
-                summary: 'A customer purchase request',
-              },
-            ],
-          },
-        },
-      ]);
-    });
-  });
-
-  describe('getDomainsForService', () => {
-    it('should return the domains for a service', async () => {
-      const domains = await getDomainsForService(mockServices[0] as unknown as Service);
-      const expectedDomain = mockDomains[0];
-      expect(domains[0].data.id).toEqual(expectedDomain.data.id);
-      expect(domains[0].data.services).toEqual(expect.arrayContaining([mockServices[0]]));
-    });
-
-    it('returns an empty array if the service is not found', async () => {
-      const domains = await getDomainsForService(mockServices[4] as unknown as Service);
-      expect(domains).toEqual([]);
-    });
-  });
-
-  describe('getParentDomains', () => {
-    it('should return the parent domains for a domain', async () => {
-      const checkoutDomain = mockDomains.find((d) => d.data.id === 'Checkout');
-      const domains = await getParentDomains(checkoutDomain as unknown as Domain);
-      const expectedDomain = mockDomains.find((d) => d.data.id === 'Shipping');
-      expect(domains.length).toBeGreaterThan(0);
-      expect(domains[0].data.id).toEqual(expectedDomain!.data.id);
-      // The domains array will contain the processed subdomain objects, not the original mock
-      //@ts-ignore
-      expect(domains[0].data.domains.some((d: any) => d.data.id === 'Checkout')).toBe(true);
-    });
-
-    it('returns an empty array if the domain is not found', async () => {
-      const notificationDomain = mockDomains.find((d) => d.data.id === 'Notification');
-      const domains = await getParentDomains(notificationDomain as unknown as Domain);
-      expect(domains).toEqual([]);
-    });
-  });
-
-  describe('getUbiquitousLanguageWithSubdomains', () => {
-    it('should return domain ubiquitous language with subdomain languages', async () => {
-      const domains = await getDomains();
-      const shippingDomain = domains.find((d) => d.data.id === 'Shipping');
-
-      const result = await getUbiquitousLanguageWithSubdomains(shippingDomain as Domain);
-
-      expect(result.domain).toEqual({
-        id: 'domains/Shipping/ubiquitous-language.mdx',
-        slug: 'domains/Shipping/ubiquitous-language',
-        collection: 'ubiquitousLanguages',
-        filePath: 'domains/Shipping/ubiquitous-language.mdx',
-        data: {
-          id: 'Shipping',
-          dictionary: [
-            { id: 'Payment', name: 'Payment', summary: 'A financial transaction' },
-            { id: 'Order', name: 'Order', summary: 'A customer purchase request' },
-          ],
-        },
-      });
-
-      expect(result.subdomains).toHaveLength(1);
-      expect(result.subdomains[0].subdomain.data.id).toBe('Checkout');
-      expect(result.subdomains[0].ubiquitousLanguage).toEqual({
-        id: 'domains/Checkout/ubiquitous-language.mdx',
-        slug: 'domains/Checkout/ubiquitous-language',
-        collection: 'ubiquitousLanguages',
-        filePath: 'domains/Checkout/ubiquitous-language.mdx',
-        data: {
-          id: 'Checkout',
-          dictionary: [
-            { id: 'Payment', name: 'Payment', summary: 'Processing customer payment' },
-            { id: 'Cart', name: 'Cart', summary: 'Shopping cart items' },
-          ],
-        },
-      });
-    });
-
-    it('should detect duplicate terms across domain and subdomains', async () => {
-      const domains = await getDomains();
-      const shippingDomain = domains.find((d) => d.data.id === 'Shipping');
-
-      const result = await getUbiquitousLanguageWithSubdomains(shippingDomain as Domain);
-
-      // Payment appears in both Shipping domain and Checkout subdomain, so should be a duplicate
-      expect(result.duplicateTerms).toContain('payment');
-      // Order only appears in Shipping domain, Cart only in Checkout - neither should be duplicates
-      expect(result.duplicateTerms).not.toContain('order');
-      expect(result.duplicateTerms).not.toContain('cart');
-    });
-
-    it('should handle domain with no ubiquitous language', async () => {
-      const domains = await getDomains();
-      const notificationDomain = domains.find((d) => d.data.id === 'Notification');
-
-      const result = await getUbiquitousLanguageWithSubdomains(notificationDomain as Domain);
-
-      expect(result.domain).toEqual({
-        id: 'domains/Notification/ubiquitous-language.mdx',
-        slug: 'domains/Notification/ubiquitous-language',
-        collection: 'ubiquitousLanguages',
-        filePath: 'domains/Notification/ubiquitous-language.mdx',
-        data: {
-          id: 'Notification',
-          dictionary: [{ id: 'Email', name: 'Email', summary: 'Electronic mail notification' }],
-        },
-      });
-      expect(result.subdomains).toHaveLength(0);
-      expect(result.duplicateTerms.size).toBe(0);
-    });
-
-    it('should handle domain with subdomains but no ubiquitous language for subdomains', async () => {
-      const domains = await getDomains();
-      const checkoutDomain = domains.find((d) => d.data.id === 'Checkout');
-
-      const result = await getUbiquitousLanguageWithSubdomains(checkoutDomain as Domain);
-
-      expect(result.domain).toEqual({
-        id: 'domains/Checkout/ubiquitous-language.mdx',
-        slug: 'domains/Checkout/ubiquitous-language',
-        collection: 'ubiquitousLanguages',
-        filePath: 'domains/Checkout/ubiquitous-language.mdx',
-        data: {
-          id: 'Checkout',
-          dictionary: [
-            { id: 'Payment', name: 'Payment', summary: 'Processing customer payment' },
-            { id: 'Cart', name: 'Cart', summary: 'Shopping cart items' },
-          ],
-        },
-      });
-      expect(result.subdomains).toHaveLength(0);
-      expect(result.duplicateTerms.size).toBe(0);
-    });
-
-    it('should return empty result when domain has no ubiquitous language and no subdomains', async () => {
-      const mockDomainWithoutLanguage = {
-        id: 'domains/Empty/index.mdx',
-        filePath: 'domains/Empty/index.mdx',
-        data: {
-          id: 'Empty',
-          name: 'Empty',
-          version: '0.0.1',
-          domains: [],
-        },
-      };
-
-      //@ts-ignore
-      const result = await getUbiquitousLanguageWithSubdomains(mockDomainWithoutLanguage as Domain);
-
-      expect(result.domain).toBeNull();
-      expect(result.subdomains).toHaveLength(0);
-      expect(result.duplicateTerms.size).toBe(0);
-    });
-  });
-
-  describe('domainHasEntities', () => {
-    it('should return true if the domain has entities', async () => {
-      const domains = await getDomains();
-      domains[0].data.entities = [{ id: 'Order', version: '1.0.0' }];
-      expect(domainHasEntities(domains[0])).toBe(true);
-    });
-
-    it('should return false if the domain has no entities', async () => {
-      const domains = await getDomains();
-      expect(domainHasEntities(domains[1])).toBe(false);
-    });
-  });
-});
diff --git a/eventcatalog/src/utils/__tests__/domains/mocks.ts b/eventcatalog/src/utils/__tests__/domains/mocks.ts
deleted file mode 100644
index 10a4bf998..000000000
--- a/eventcatalog/src/utils/__tests__/domains/mocks.ts
+++ /dev/null
@@ -1,247 +0,0 @@
-export const mockDomains = [
-  {
-    id: 'domains/Shipping/index.mdx',
-    slug: 'domains/Shipping',
-    collection: 'domains',
-    filePath: 'domains/Shipping/index.mdx',
-    data: {
-      id: 'Shipping',
-      name: 'Shipping',
-      version: '0.0.1',
-      services: [{ id: 'LocationService', version: '0.0.1' }],
-      domains: [{ id: 'Checkout', version: '0.0.1' }],
-      entities: [{ id: 'Shipment', version: '0.0.1' }],
-    },
-  },
-  {
-    id: 'domains/Checkout/index.mdx',
-    slug: 'domains/Checkout',
-    collection: 'domains',
-    filePath: 'domains/Checkout/index.mdx',
-    data: {
-      id: 'Checkout',
-      name: 'Checkout',
-      version: '0.0.1',
-      services: [{ id: 'OrderService' /* version: latest */ }, { id: 'PaymentService', version: '0.0.1' }],
-    },
-  },
-  {
-    id: 'domains/Notification/index.mdx',
-    slug: 'domains/Notification',
-    collection: 'domains',
-    filePath: 'domains/Notification/index.mdx',
-    data: {
-      id: 'Notification',
-      name: 'Notification',
-      version: '0.0.1',
-      services: [{ id: 'MailService' }],
-    },
-  },
-];
-
-export const mockServices = [
-  {
-    id: 'services/LocationService/index.mdx',
-    slug: 'services/LocationService',
-    collection: 'services',
-    data: {
-      id: 'LocationService',
-      version: '0.0.1',
-      receives: [{ id: 'OrderPlaced', version: '0.0.1' }],
-    },
-  },
-  {
-    id: 'services/OrderService/versioned/001/index.mdx',
-    slug: 'services/OrderService/versioned/001',
-    collection: 'services',
-    data: {
-      id: 'OrderService',
-      version: '0.0.1',
-      receives: [{ id: 'PlaceOrder', version: '>1.5.0' }],
-      sends: [{ id: 'OrderPlaced', version: '0.0.1' }],
-    },
-  },
-  {
-    id: 'services/OrderService/index.mdx',
-    slug: 'services/OrderService',
-    collection: 'services',
-    data: {
-      id: 'OrderService',
-      version: '1.0.0',
-      receives: [{ id: 'PlaceOrder', version: '>1.5.0' }],
-      sends: [{ id: 'OrderPlaced', version: '0.0.1' }],
-    },
-  },
-  {
-    id: 'services/PaymentService/index.mdx',
-    slug: 'services/PaymentService',
-    collection: 'services',
-    data: {
-      id: 'PaymentService',
-      version: '0.0.1',
-      receives: [{ id: 'OrderPlaced' }],
-      sends: [{ id: 'PaymentPaid', version: 'x' }, { id: 'PaymentRefunded' }, { id: 'PaymentFailed', version: '^1.0.0' }],
-    },
-  },
-  {
-    id: 'services/ServiceWithoutDomains/index.mdx',
-    slug: 'services/ServiceWithoutDomains',
-    collection: 'services',
-    data: {
-      id: 'ServiceWithoutDomains',
-      version: '0.0.1',
-    },
-  },
-];
-
-export const mockCommands = [
-  // PlaceOrder
-  {
-    id: 'commands/PlaceOrder/versioned/100/index.mdx',
-    slug: 'commands/PlaceOrder/versoined/100',
-    collection: 'commands',
-    data: {
-      id: 'PlaceOrder',
-      version: '1.0.0',
-    },
-  },
-  {
-    id: 'commands/PlaceOrder/versioned/150/index.mdx',
-    slug: 'commands/PlaceOrder/versoined/150',
-    collection: 'commands',
-    data: {
-      id: 'PlaceOrder',
-      version: '1.5.0',
-    },
-  },
-  {
-    id: 'commands/PlaceOrder/versioned/177/index.mdx',
-    slug: 'commands/PlaceOrder/versoined/177',
-    collection: 'commands',
-    data: {
-      id: 'PlaceOrder',
-      version: '1.7.7',
-    },
-  },
-];
-
-export const mockEvents = [
-  // OrderPlaced
-  {
-    id: 'events/OrderPlaced/index.mdx',
-    slug: 'events/OrderPlaced',
-    collection: 'events',
-    data: {
-      id: 'OrderPlaced',
-      version: '0.0.1',
-    },
-  },
-
-  // PaymentPaid
-  {
-    id: 'events/PaymentPaid/versioned/001/index.mdx',
-    slug: 'events/PaymentPaid/versioned/001',
-    collection: 'events',
-    data: {
-      id: 'PaymentPaid',
-      version: '0.0.1',
-    },
-  },
-  {
-    id: 'events/PaymentPaid/index.mdx',
-    slug: 'events/PaymentPaid',
-    collection: 'events',
-    data: {
-      id: 'PaymentPaid',
-      version: '0.0.2',
-    },
-  },
-
-  // PaymentRefunded
-  {
-    id: 'events/PaymentRefunded/index.mdx',
-    slug: 'events/PaymentRefunded',
-    collection: 'events',
-    data: {
-      id: 'PaymentRefunded',
-      version: '0.0.1',
-    },
-  },
-  {
-    id: 'events/PaymentRefunded/index.mdx',
-    slug: 'events/PaymentRefunded',
-    collection: 'events',
-    data: {
-      id: 'PaymentRefunded',
-      version: '1.0.0',
-    },
-  },
-
-  // PaymentFailed
-  {
-    id: 'events/PaymentFailed/index.mdx',
-    slug: 'events/PaymentFailed',
-    collection: 'events',
-    data: {
-      id: 'PaymentFailed',
-      version: '0.0.1',
-    },
-  },
-  {
-    id: 'events/PaymentFailed/index.mdx',
-    slug: 'events/PaymentFailed',
-    collection: 'events',
-    data: {
-      id: 'PaymentFailed',
-      version: '1.0.0',
-    },
-  },
-  {
-    id: 'events/PaymentFailed/index.mdx',
-    slug: 'events/PaymentFailed',
-    collection: 'events',
-    data: {
-      id: 'PaymentFailed',
-      version: '2.0.0',
-    },
-  },
-];
-
-export const mockUbiquitousLanguages = [
-  {
-    id: 'domains/Shipping/ubiquitous-language.mdx',
-    slug: 'domains/Shipping/ubiquitous-language',
-    collection: 'ubiquitousLanguages',
-    filePath: 'domains/Shipping/ubiquitous-language.mdx',
-    data: {
-      id: 'Shipping',
-      dictionary: [
-        { id: 'Payment', name: 'Payment', summary: 'A financial transaction' },
-        { id: 'Order', name: 'Order', summary: 'A customer purchase request' },
-      ],
-    },
-  },
-  {
-    id: 'domains/Checkout/ubiquitous-language.mdx',
-    slug: 'domains/Checkout/ubiquitous-language',
-    collection: 'ubiquitousLanguages',
-    filePath: 'domains/Checkout/ubiquitous-language.mdx',
-    data: {
-      id: 'Checkout',
-      dictionary: [
-        { id: 'Payment', name: 'Payment', summary: 'Processing customer payment' },
-        { id: 'Cart', name: 'Cart', summary: 'Shopping cart items' },
-      ],
-    },
-  },
-  {
-    id: 'domains/Notification/ubiquitous-language.mdx',
-    slug: 'domains/Notification/ubiquitous-language',
-    collection: 'ubiquitousLanguages',
-    filePath: 'domains/Notification/ubiquitous-language.mdx',
-    data: {
-      id: 'Notification',
-      dictionary: [{ id: 'Email', name: 'Email', summary: 'Electronic mail notification' }],
-    },
-  },
-];
diff --git a/eventcatalog/src/utils/__tests__/domains/node-graph.spec.ts b/eventcatalog/src/utils/__tests__/domains/node-graph.spec.ts
deleted file mode 100644
index 60729bbaa..000000000
--- a/eventcatalog/src/utils/__tests__/domains/node-graph.spec.ts
+++ /dev/null
@@ -1,202 +0,0 @@
-import type { ContentCollectionKey } from 'astro:content';
-import { expect, describe, it, vi } from 'vitest';
-import { mockDomains, mockServices, mockEvents, mockCommands } from './mocks';
-import { getNodesAndEdges } from '@utils/node-graphs/domains-node-graph';
-
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    // this will only affect "foo" outside of the original module
-    getCollection: (key: ContentCollectionKey) => {
-      switch (key) {
-        case 'domains':
-          return Promise.resolve(mockDomains);
-        case 'services':
-          return Promise.resolve(mockServices);
-        case 'events':
-          return Promise.resolve(mockEvents);
-        case 'commands':
-          return Promise.resolve(mockCommands);
-        default:
-          return Promise.resolve([]);
-      }
-    },
-  };
-});
-
-describe('Domains NodeGraph', () => {
-  describe('getNodesAndEdges', () => {
-    it('returns an empty array if no domains are found', async () => {
-      // @ts-ignore
-      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownDomain', version: '1.0.0' });
-
-      expect(nodes).toEqual([]);
-      expect(edges).toEqual([]);
-    });
-
-    it('should return nodes and edges for a given domain', async () => {
-      // @ts-ignore
-      const { nodes, edges } = await getNodesAndEdges({ id: 'Shipping', version: '0.0.1' });
-
-      const expectedServiceNode = {
-        id: 'LocationService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[0].data }, group: expect.anything() },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedEventNode = {
-        id: 'OrderPlaced-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: {
-          mode: 'simple',
-          message: { ...mockEvents[0].data },
-          group: {
-            type: 'Domain',
-            value: 'Checkout',
-            id: 'Checkout',
-          },
-        },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'events',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        expect.objectContaining({
-          id: 'OrderPlaced-0.0.1-LocationService-0.0.1',
-          source: 'OrderPlaced-0.0.1',
-          target: 'LocationService-0.0.1',
-          label: 'subscribed by',
-          animated: false,
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedEventNode),
-
-          // The command node itself
-          expect.objectContaining(expectedServiceNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('should return a list of nodes and edges with a domain has subdomains', async () => {
-      // @ts-ignore
-      const { nodes, edges } = await getNodesAndEdges({ id: 'Shipping', version: '0.0.1' });
-
-      // Expect the orders service to be rendered (it's a service in a subdomain)
-      const expectedEventNode = {
-        id: 'OrderService-1.0.0',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: {
-          mode: 'simple',
-          service: expect.objectContaining({
-            id: 'OrderService',
-            version: '1.0.0',
-          }),
-          group: {
-            type: 'Domain',
-            value: 'Checkout',
-            id: 'Checkout',
-          },
-        },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      expect(nodes).toEqual(expect.arrayContaining([expect.objectContaining(expectedEventNode)]));
-
-      expect(nodes.length).toEqual(10);
-      expect(edges.length).toEqual(9);
-    });
-
-    it('should return nodes and edges for a given domain with services using semver range or latest version (version undefind)', async () => {
-      // @ts-ignore
-      const { nodes, edges } = await getNodesAndEdges({ id: 'Checkout', version: '0.0.1' });
-
-      const expectedNodes = [
-        {
-          id: 'PlaceOrder-1.7.7',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          data: { mode: 'simple', message: { ...mockCommands[2].data } },
-          position: { x: expect.any(Number), y: expect.any(Number) },
-          type: 'commands',
-        },
-        {
-          id: 'OrderService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          data: {
-            mode: 'simple',
-            service: { ...mockServices[2].data },
-          },
-          position: { x: expect.any(Number), y: expect.any(Number) },
-          type: 'services',
-        },
-        {
-          id: 'OrderPlaced-0.0.1',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          data: { mode: 'simple', message: { ...mockEvents[0].data } },
-          position: { x: expect.any(Number), y: expect.any(Number) },
-          type: 'events',
-        },
-        /** PAYMENT SERVICE */
-        {
-          id: 'PaymentService-0.0.1',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          data: {
-            mode: 'simple',
-            service: { ...mockServices[3].data },
-          },
-          position: { x: expect.any(Number), y: expect.any(Number) },
-          type: 'services',
-        },
-        {
-          id: 'PaymentPaid-0.0.1',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          data: { mode: 'simple', message: { ...mockEvents[1].data } },
-          position: { x: expect.any(Number), y: expect.any(Number) },
-          type: 'events',
-        },
-        {
-          id: 'PaymentPaid-0.0.2',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          data: { mode: 'simple', message: { ...mockEvents[2].data } },
-          position: { x: expect.any(Number), y: expect.any(Number) },
-          type: 'events',
-        },
-        {
-          id: 'PaymentRefunded-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          data: { mode: 'simple', message: { ...mockEvents[4].data } },
-          position: { x: expect.any(Number), y: expect.any(Number) },
-          type: 'events',
-        },
-        {
-          id: 'PaymentFailed-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          data: { mode: 'simple', message: { ...mockEvents[6].data } },
-          position: { x: expect.any(Number), y: expect.any(Number) },
-          type: 'events',
-        },
-      ];
-
-      expect(nodes).toStrictEqual(expect.arrayContaining(expectedNodes.map((n) => expect.objectContaining(n))));
-    });
-  });
-});
diff --git a/eventcatalog/src/utils/__tests__/events/mocks.ts b/eventcatalog/src/utils/__tests__/events/mocks.ts
deleted file mode 100644
index 1d178cd42..000000000
--- a/eventcatalog/src/utils/__tests__/events/mocks.ts
+++ /dev/null
@@ -1,184 +0,0 @@
-export const mockServices = [
-  {
-    id: 'OrderService',
-    slug: 'OrderService',
-    collection: 'services',
-    data: {
-      id: 'OrderService',
-      version: '0.0.1',
-      sends: [
-        {
-          id: 'OrderCreatedEvent',
-          version: '0.0.1',
-          to: [
-            {
-              id: 'EmailChannel',
-              version: '1.0.0',
-            },
-          ],
-        },
-      ],
-    },
-  },
-  {
-    id: 'PaymentService',
-    slug: 'PaymentService',
-    collection: 'services',
-    data: {
-      id: 'PaymentService',
-      version: '0.0.1',
-      receives: [
-        {
-          id: 'OrderCreatedEvent',
-          version: '0.0.1',
-        },
-      ],
-    },
-  },
-  {
-    id: 'InventoryService',
-    slug: 'InventoryService',
-    collection: 'services',
-    data: {
-      id: 'InventoryService',
-      version: '0.0.1',
-      sends: [
-        {
-          id: 'InventoryAdjusted',
-          version: '>1.2.0',
-        },
-        {
-          id: 'ProductOutOfStock',
-        },
-        {
-          id: 'ProductDiscontinued',
-          version: 'latest',
-        },
-      ],
-    },
-  },
-  {
-    id: 'CatalogService',
-    slug: 'CatalogService',
-    collection: 'services',
-    data: {
-      id: 'CatalogService',
-      version: '0.0.1',
-      receives: [
-        {
-          id: 'InventoryAdjusted',
-        },
-        {
-          id: 'ProductDiscontinued',
-          version: '*',
-        },
-      ],
-    },
-  },
-  {
-    id: 'NotificationsService',
-    slug: 'NotificationsService',
-    collection: 'services',
-    data: {
-      id: 'NotificationsService',
-      version: '0.0.1',
-      receives: [
-        {
-          id: 'EmailSent',
-          from: [
-            {
-              id: 'EmailChannel',
-              version: '1.0.0',
-            },
-          ],
-        },
-      ],
-      sends: [
-        {
-          id: 'EmailSent',
-        },
-        {
-          id: 'EmailVerified',
-        },
-      ],
-    },
-  },
-];
-
-export const mockChannels = [
-  {
-    id: 'EmailChannel',
-    slug: 'EmailChannel',
-    collection: 'channels',
-    data: {
-      id: 'EmailChannel',
-      version: '1.0.0',
-    },
-  },
-];
-
-export const mockEvents = [
-  {
-    id: 'OrderCreatedEvent',
-    slug: 'OrderCreatedEvent',
-    collection: 'events',
-    data: {
-      id: 'OrderCreatedEvent',
-      version: '0.0.1',
-    },
-  },
-  {
-    id: 'InventoryAdjusted',
-    slug: 'InventoryAdjusted',
-    collection: 'events',
-    data: {
-      id: 'InventoryAdjusted',
-      version: '1.5.1',
-    },
-  },
-  {
-    id: 'ProductOutOfStock',
-    slug: 'ProductOutOfStock',
-    collection: 'events',
-    data: {
-      id: 'ProductOutOfStock',
-      version: '1.0.0',
-    },
-  },
-  {
-    id: 'ProductDiscontinued',
-    slug: 'ProductDiscontinued',
-    collection: 'events',
-    data: {
-      id: 'ProductDiscontinued',
-      version: '0.0.1',
-    },
-  },
-  {
-    id: 'ProductDiscontinued',
-    slug: 'ProductDiscontinued',
-    collection: 'events',
-    data: {
-      id: 'ProductDiscontinued',
-      version: '1.0.0',
-    },
-  },
-  {
-    id: 'EmailSent',
-    slug: 'EmailSent',
-    collection: 'events',
-    data: {
-      id: 'EmailSent',
-      version: '1.0.0',
-    },
-  },
-  {
-    id: 'EmailVerified',
-    slug: 'EmailVerified',
-    collection: 'events',
-    data: {
-      id: 'EmailVerified',
-      version: '1.0.0',
-    },
-  },
-];
diff --git a/eventcatalog/src/utils/__tests__/events/node-graph.spec.ts b/eventcatalog/src/utils/__tests__/events/node-graph.spec.ts
deleted file mode 100644
index a59689482..000000000
--- a/eventcatalog/src/utils/__tests__/events/node-graph.spec.ts
+++ /dev/null
@@ -1,372 +0,0 @@
-import { getNodesAndEdgesForEvents as getNodesAndEdges } from '../../node-graphs/message-node-graph';
-import { expect, describe, it, vi, beforeEach } from 'vitest';
-import { mockEvents, mockServices, mockChannels } from './mocks';
-
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    // this will only affect "foo" outside of the original module
-    getCollection: (key: string) => {
-      if (key === 'services') {
-        return Promise.resolve(mockServices);
-      }
-      if (key === 'channels') {
-        return Promise.resolve(mockChannels);
-      }
-      if (key === 'events') {
-        return Promise.resolve(mockEvents);
-      }
-      return Promise.resolve([]);
-    },
-  };
-});
-
-describe('Events NodeGraph', () => {
-  beforeEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  describe('getNodesAndEdges', () => {
-    it('should return nodes and edges for a given event', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'OrderCreatedEvent', version: '0.0.1' });
-
-      // The middle node itself, the service
-      const expectedEventNode = {
-        id: 'OrderCreatedEvent-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        // data: { mode: 'simple', message: expect.anything(), showSource: false },
-        data: expect.anything(),
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'events',
-      };
-
-      const expectedProducerNode = {
-        id: 'OrderService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[0].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedConsumerNode = {
-        id: 'PaymentService-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: {
-          title: 'PaymentService',
-          mode: 'simple',
-          service: { ...mockServices[1].data },
-        },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        expect.objectContaining({
-          id: 'OrderService-0.0.1-OrderCreatedEvent-0.0.1',
-          source: 'OrderService-0.0.1',
-          target: 'OrderCreatedEvent-0.0.1',
-          label: 'publishes \nevent',
-          animated: false,
-        }),
-        // The channel to the event
-        expect.objectContaining({
-          id: 'OrderCreatedEvent-0.0.1-EmailChannel-1.0.0',
-          source: 'OrderCreatedEvent-0.0.1',
-          target: 'EmailChannel-1.0.0',
-          label: 'routes to',
-          animated: false,
-        }),
-        // The event to the consumer
-        expect.objectContaining({
-          id: 'OrderCreatedEvent-0.0.1-PaymentService-0.0.1',
-          source: 'OrderCreatedEvent-0.0.1',
-          target: 'PaymentService-0.0.1',
-          label: 'subscribed by',
-          animated: false,
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedConsumerNode),
-
-          // The event node itself
-          expect.objectContaining(expectedEventNode),
-
-          // Nodes on the right
-          expect.objectContaining(expectedProducerNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('if the event is produced and consumed by a service it will render a custom edge', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'EmailSent', version: '1.0.0' });
-
-      // The middle node itself, the service
-      const expectedEventNode = {
-        id: 'EmailSent-1.0.0',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        // data: { mode: 'simple', message: expect.anything(), showSource: false },
-        data: expect.anything(),
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'events',
-      };
-
-      const expectedProducerNode = {
-        id: 'NotificationsService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[4].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedConsumerNode = {
-        id: 'NotificationsService-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: {
-          title: 'NotificationsService',
-          mode: 'simple',
-          service: { ...mockServices[4].data },
-        },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        // Producer to the event
-        expect.objectContaining({
-          id: 'NotificationsService-0.0.1-EmailSent-1.0.0',
-          source: 'NotificationsService-0.0.1',
-          target: 'EmailSent-1.0.0',
-          label: 'publishes \nevent',
-        }),
-        // Event to the channel
-        expect.objectContaining({
-          id: 'EmailSent-1.0.0-EmailChannel-1.0.0',
-          source: 'EmailSent-1.0.0',
-          target: 'EmailChannel-1.0.0',
-          label: 'routes to',
-          animated: false,
-        }),
-        expect.objectContaining({
-          id: 'EmailSent-1.0.0-NotificationsService-0.0.1-both',
-          source: 'EmailSent-1.0.0',
-          target: 'NotificationsService-0.0.1',
-          label: 'publishes and subscribes',
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedConsumerNode),
-
-          // The event node itself
-          expect.objectContaining(expectedEventNode),
-
-          // Nodes on the right
-          expect.objectContaining(expectedProducerNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('if the consumer of an event has defined a channel, it will render the channel node and edges', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'EmailSent', version: '1.0.0' });
-
-      const expectedConsumerNode = {
-        id: 'NotificationsService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[4].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedChannelNode = {
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        id: 'EmailChannel-1.0.0',
-        type: 'channels',
-      };
-
-      const expectedEventNode = {
-        id: 'EmailSent-1.0.0',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        type: 'events',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        // Message to the channel
-        expect.objectContaining({
-          id: 'EmailSent-1.0.0-EmailChannel-1.0.0',
-          source: 'EmailSent-1.0.0',
-          target: 'EmailChannel-1.0.0',
-        }),
-        // Channel to the consumer
-        expect.objectContaining({
-          id: 'EmailChannel-1.0.0-NotificationsService-0.0.1',
-          source: 'EmailChannel-1.0.0',
-          target: 'NotificationsService-0.0.1',
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedConsumerNode),
-
-          // channel
-          expect.objectContaining(expectedChannelNode),
-
-          // The event node itself
-          expect.objectContaining(expectedEventNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('if the producer of an event has defined a channel, it will render the channel node and edges', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'OrderCreatedEvent', version: '0.0.1' });
-
-      const expectedProducerNode = {
-        id: 'OrderService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedChannelNode = {
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        id: 'EmailChannel-1.0.0',
-        type: 'channels',
-      };
-
-      const expectedEventNode = {
-        id: 'OrderCreatedEvent-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        type: 'events',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        // Producer to the message
-        expect.objectContaining({
-          id: 'OrderService-0.0.1-OrderCreatedEvent-0.0.1',
-          source: 'OrderService-0.0.1',
-          target: 'OrderCreatedEvent-0.0.1',
-          label: 'publishes \nevent',
-          animated: false,
-        }),
-        // Message to the channel
-        expect.objectContaining({
-          id: 'OrderCreatedEvent-0.0.1-EmailChannel-1.0.0',
-          source: 'OrderCreatedEvent-0.0.1',
-          target: 'EmailChannel-1.0.0',
-          label: 'routes to',
-          animated: false,
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedProducerNode),
-
-          // channel
-          expect.objectContaining(expectedChannelNode),
-
-          // The event node itself
-          expect.objectContaining(expectedEventNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('returns empty nodes and edges if no event is found', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownEvent', version: '1.0.0' });
-
-      expect(nodes).toEqual([]);
-      expect(edges).toEqual([]);
-    });
-
-    it('should return nodes and edges for a given event using semver range', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'InventoryAdjusted', version: '1.5.1' });
-
-      // The middle node itself, the service
-      const expectedEventNode = {
-        id: 'InventoryAdjusted-1.5.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: expect.anything(),
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'events',
-      };
-
-      const expectedProducerNode = {
-        id: 'InventoryService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[2].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedConsumerNode = {
-        id: 'CatalogService-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { title: 'CatalogService', mode: 'simple', service: { ...mockServices[3].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        expect.objectContaining({
-          id: 'InventoryService-0.0.1-InventoryAdjusted-1.5.1',
-          source: 'InventoryService-0.0.1',
-          target: 'InventoryAdjusted-1.5.1',
-          label: 'publishes \nevent',
-          animated: false,
-        }),
-        expect.objectContaining({
-          id: 'InventoryAdjusted-1.5.1-CatalogService-0.0.1',
-          source: 'InventoryAdjusted-1.5.1',
-          target: 'CatalogService-0.0.1',
-          label: 'subscribed by',
-          animated: false,
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedProducerNode),
-
-          // The event node itself
-          expect.objectContaining(expectedEventNode),
-
-          // Nodes on the right
-          expect.objectContaining(expectedConsumerNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-  });
-});
diff --git a/eventcatalog/src/utils/__tests__/flows/mocks.ts b/eventcatalog/src/utils/__tests__/flows/mocks.ts
deleted file mode 100644
index 813626732..000000000
--- a/eventcatalog/src/utils/__tests__/flows/mocks.ts
+++ /dev/null
@@ -1,201 +0,0 @@
-export const mockEvents = [
-  {
-    slug: 'PaymentInitiated',
-    collection: 'events',
-    data: {
-      id: 'PaymentInitiated',
-      version: '0.0.1',
-    },
-  },
-  {
-    slug: 'PaymentProcessed',
-    collection: 'events',
-    data: {
-      id: 'PaymentProcessed',
-      version: '0.0.1',
-    },
-  },
-];
-
-export const mockServices = [
-  {
-    slug: 'SubscriptionService',
-    collection: 'services',
-    data: {
-      id: 'SubscriptionService',
-      version: '0.0.1',
-    },
-  },
-];
-
-export const mockFlow = [
-  {
-    id: 'Payment/PaymentProcessed/index.mdx',
-    slug: 'payment/paymentprocessed',
-    body: '',
-    collection: 'flows',
-    data: {
-      steps: [
-        {
-          id: 1,
-          type: 'node',
-          title: 'Order Placed',
-          next_step: {
-            id: 2,
-            label: 'Proceed to payment',
-          },
-        },
-        {
-          id: 2,
-          title: 'Payment Initiated',
-          message: {
-            id: 'PaymentInitiated',
-            version: '0.0.1',
-          },
-          next_steps: [
-            {
-              id: 3,
-              label: 'Payment successful',
-            },
-            {
-              id: 4,
-              label: 'Payment failed',
-            },
-          ],
-        },
-        {
-          id: 3,
-          title: 'Payment Processed',
-          message: {
-            id: 'PaymentProcessed',
-            version: '0.0.1',
-          },
-        },
-        {
-          id: 4,
-          type: 'node',
-          title: 'Payment Failed',
-        },
-      ],
-      id: 'PaymentFlow',
-      name: 'Payment Flow for E-commerce',
-      summary: 'Business flow for processing payments in an e-commerce platform',
-      version: '1.0.0',
-      type: 'node',
-    },
-  },
-];
-
-export const mockFlowByIds = [
-  {
-    id: 'Payment/PaymentProcessed/index.mdx',
-    slug: 'payment/paymentprocessed',
-    body: '',
-    collection: 'flows',
-    data: {
-      steps: [
-        {
-          id: 1,
-          type: 'node',
-          title: 'Order Placed',
-          next_step: 2,
-        },
-        {
-          id: 2,
-          title: 'Payment Initiated',
-          message: {
-            id: 'PaymentInitiated',
-            version: '0.0.1',
-          },
-          next_steps: [3, 4],
-        },
-        {
-          id: 3,
-          title: 'Payment Processed',
-          message: {
-            id: 'PaymentProcessed',
-            version: '0.0.1',
-          },
-        },
-        {
-          id: 4,
-          type: 'node',
-          title: 'Payment Failed',
-        },
-      ],
-      id: 'PaymentFlow',
-      name: 'Payment Flow for E-commerce',
-      summary: 'Business flow for processing payments in an e-commerce platform',
-      version: '1.0.0',
-      type: 'node',
-    },
-  },
-  {
-    id: 'Subscriptions/CancelSubscription/index.mdx',
-    slug: 'subscriptions/CancelSubscription',
-    body: '',
-    collection: 'flows',
-    data: {
-      steps: [
-        {
-          id: 'cancel_subscription_initiated',
-          title: 'Cancels Subscription',
-          actor: {
-            name: 'User',
-          },
-          next_step: {
-            id: 'cancel_subscription_request',
-            label: 'Initiate subscription cancellation',
-          },
-        },
-        {
-          id: 'cancel_subscription_request',
-          title: 'Cancel Subscription',
-          message: {
-            id: 'CancelSubscription',
-            version: '0.0.1',
-          },
-          next_step: {
-            id: 'subscription_service',
-            label: 'Proceed to subscription service',
-          },
-        },
-        {
-          id: 'subscription_service',
-          title: 'Subscription Service',
-          service: {
-            id: 'SubscriptionService',
-            version: 'latest',
-          },
-          next_steps: [
-            {
-              id: 'subscription_cancelled',
-              label: 'Successful cancellation',
-            },
-            {
-              id: 'subscription_rejected',
-              label: 'Failed cancellation',
-            },
-          ],
-        },
-        {
-          id: 'subscription_cancelled',
-          title: 'Subscription has been cancelled',
-          message: {
-            id: 'UserSubscriptionCancelled',
-            version: '0.0.1',
-          },
-        },
-        {
-          id: 'subscription_rejected',
-          title: 'Subscription cancellation has been rejected',
-        },
-      ],
-      id: 'CancelSubscription',
-      name: 'User Cancels Subscription',
-      summary: 'Flow for when a user has cancelled a subscription',
-      version: '1.0.0',
-      // type: 'node',
-    },
-  },
-];
diff --git a/eventcatalog/src/utils/__tests__/flows/node-graph.spec.ts b/eventcatalog/src/utils/__tests__/flows/node-graph.spec.ts
deleted file mode 100644
index 37fcbe317..000000000
--- a/eventcatalog/src/utils/__tests__/flows/node-graph.spec.ts
+++ /dev/null
@@ -1,262 +0,0 @@
-import { getNodesAndEdges } from '../../node-graphs/flows-node-graph';
-import { expect, describe, it, vi, beforeEach } from 'vitest';
-import { mockEvents, mockFlow, mockFlowByIds, mockServices } from './mocks';
-import { getCollection } from 'astro:content';
-let expectedNodes: any;
-
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    // this will only affect "foo" outside of the original module
-    getCollection: (key: string) => {
-      if (key === 'flows') {
-        return Promise.resolve(mockFlow);
-      }
-      if (key === 'events') {
-        return Promise.resolve(mockEvents);
-      }
-      if (key === 'services') {
-        return Promise.resolve(mockServices);
-      }
-      return Promise.resolve([]);
-    },
-  };
-});
-
-describe('Flows NodeGraph', () => {
-  beforeEach(() => {
-    vi.restoreAllMocks();
-    expectedNodes = [
-      {
-        id: 'step-1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: expect.anything(),
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'step',
-      },
-      {
-        id: 'step-2',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: expect.anything(),
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'events',
-      },
-      {
-        id: 'step-3',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: {
-          mode: 'simple',
-          step: {
-            id: 3,
-            title: 'Payment Processed',
-            message: {
-              slug: 'PaymentProcessed',
-              collection: 'events',
-              data: {
-                id: 'PaymentProcessed',
-                version: '0.0.1',
-              },
-            },
-            type: 'events',
-          },
-          showTarget: true,
-          showSource: true,
-          message: {
-            slug: 'PaymentProcessed',
-            collection: 'events',
-            data: {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-            },
-            id: 'PaymentProcessed',
-            version: '0.0.1',
-          },
-        },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'events',
-      },
-      {
-        id: 'step-4',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: {
-          mode: 'simple',
-          step: {
-            id: 4,
-            type: 'step',
-            title: 'Payment Failed',
-          },
-          showTarget: true,
-          showSource: true,
-        },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'step',
-      },
-    ];
-  });
-
-  describe('getNodesAndEdges', () => {
-    it('should return the correct nodes and edges for a given flow', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'PaymentFlow', version: '1.0.0' });
-
-      const expectedEdges = [
-        {
-          id: 'step-1-step-2',
-          source: 'step-1',
-          target: 'step-2',
-          type: 'flow-edge',
-          animated: true,
-          markerEnd: expect.objectContaining({ type: 'arrowclosed' }),
-          style: expect.any(Object),
-        },
-      ];
-
-      expect(nodes).toEqual(expect.arrayContaining(expectedNodes));
-
-      expect(edges).toEqual(expect.arrayContaining([expect.objectContaining(expectedEdges[0])]));
-    });
-
-    it('should resolves the correct node when it is a service with version as latest', async () => {
-      const { nodes } = await getNodesAndEdges({ id: 'CancelSubscription', version: '1.0.0' });
-
-      expect(nodes).toContainEqual(
-        expect.objectContaining({
-          data: expect.objectContaining({
-            step: expect.objectContaining({
-              type: 'services',
-              service: expect.objectContaining({
-                data: {
-                  id: 'SubscriptionService',
-                  version: '0.0.1',
-                },
-              }),
-            }),
-          }),
-        })
-      );
-    });
-
-    describe('when steps are referenced only by id', () => {
-      it('should return the correct nodes and edges', async () => {
-        // TODO: This mock seems to be overriding the first mock...
-        // Mock
-        vi.mock('astro:content', async (importOriginal) => {
-          return {
-            ...(await importOriginal<typeof import('astro:content')>()),
-            // this will only affect "foo" outside of the original module
-            getCollection: (key: string) => {
-              if (key === 'flows') {
-                return Promise.resolve(mockFlowByIds);
-              }
-              if (key === 'events') {
-                return Promise.resolve(mockEvents);
-              }
-              if (key === 'services') {
-                return Promise.resolve(mockServices);
-              }
-              return Promise.resolve([]);
-            },
-          };
-        });
-
-        const { nodes, edges } = await getNodesAndEdges({ id: 'PaymentFlow', version: '1.0.0' });
-
-        const expectedNodes = [
-          {
-            id: 'step-1',
-            sourcePosition: 'right',
-            targetPosition: 'left',
-            data: expect.anything(),
-            position: { x: expect.any(Number), y: expect.any(Number) },
-            type: 'step',
-          },
-          {
-            id: 'step-2',
-            sourcePosition: 'right',
-            targetPosition: 'left',
-            data: expect.anything(),
-            position: { x: expect.any(Number), y: expect.any(Number) },
-            type: 'events',
-          },
-          {
-            id: 'step-3',
-            sourcePosition: 'right',
-            targetPosition: 'left',
-            data: {
-              mode: 'simple',
-              step: {
-                id: 3,
-                title: 'Payment Processed',
-                message: {
-                  slug: 'PaymentProcessed',
-                  collection: 'events',
-                  data: {
-                    id: 'PaymentProcessed',
-                    version: '0.0.1',
-                  },
-                },
-                type: 'events',
-              },
-              showTarget: true,
-              showSource: true,
-              message: {
-                slug: 'PaymentProcessed',
-                collection: 'events',
-                data: {
-                  id: 'PaymentProcessed',
-                  version: '0.0.1',
-                },
-                id: 'PaymentProcessed',
-                version: '0.0.1',
-              },
-            },
-            position: { x: expect.any(Number), y: expect.any(Number) },
-            type: 'events',
-          },
-          {
-            id: 'step-4',
-            sourcePosition: 'right',
-            targetPosition: 'left',
-            data: {
-              mode: 'simple',
-              step: {
-                id: 4,
-                type: 'step',
-                title: 'Payment Failed',
-              },
-              showTarget: true,
-              showSource: true,
-            },
-            position: { x: expect.any(Number), y: expect.any(Number) },
-            type: 'step',
-          },
-        ];
-
-        const expectedEdges = [
-          {
-            id: 'step-1-step-2',
-            source: 'step-1',
-            target: 'step-2',
-            type: 'flow-edge',
-            animated: true,
-            markerEnd: expect.objectContaining({ type: 'arrowclosed' }),
-            style: expect.any(Object),
-          },
-        ];
-
-        expect(nodes).toEqual(expect.arrayContaining(expectedNodes));
-        expect(edges).toEqual(expect.arrayContaining([expect.objectContaining(expectedEdges[0])]));
-      });
-    });
-
-    it('returns empty nodes and edges if no flow is found', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownFlow', version: '1.0.0' });
-
-      expect(nodes).toEqual([]);
-      expect(edges).toEqual([]);
-    });
-  });
-});
diff --git a/eventcatalog/src/utils/__tests__/markdown.spec.ts b/eventcatalog/src/utils/__tests__/markdown.spec.ts
deleted file mode 100644
index bbcadad81..000000000
--- a/eventcatalog/src/utils/__tests__/markdown.spec.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { getMDXComponentsByName } from '@utils/markdown';
-
-describe('markdown', () => {
-  describe('getMDXComponentsByName', () => {
-    it('takes given markdown and returns the components and their props', () => {
-      const markdown = `
-        <SchemaViewer id="test" />
-        <SchemaViewer id="test2" />
-        `;
-      const components = getMDXComponentsByName(markdown, 'SchemaViewer');
-      expect(components).toEqual([{ id: 'test' }, { id: 'test2' }]);
-    });
-  });
-});
diff --git a/eventcatalog/src/utils/__tests__/messages/catalog/channels/EventBridgeChannel/index.mdx b/eventcatalog/src/utils/__tests__/messages/catalog/channels/EventBridgeChannel/index.mdx
deleted file mode 100644
index 4f2f4a44c..000000000
--- a/eventcatalog/src/utils/__tests__/messages/catalog/channels/EventBridgeChannel/index.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
----
-id: EventBridgeChannel
-name: EventBridge Channel
-version: 1.0.0
-routes:
-  - id: SQSChannel
-    version: 1.0.0
----
-## EventBridge Channel
diff --git a/eventcatalog/src/utils/__tests__/messages/catalog/channels/SNSChannel/index.mdx b/eventcatalog/src/utils/__tests__/messages/catalog/channels/SNSChannel/index.mdx
deleted file mode 100644
index 567b79c63..000000000
--- a/eventcatalog/src/utils/__tests__/messages/catalog/channels/SNSChannel/index.mdx
+++ /dev/null
@@ -1,6 +0,0 @@
----
-id: SNSChannel
-name: SNS Channel
-version: 1.0.0
----
-## SNS Channel
diff --git a/eventcatalog/src/utils/__tests__/messages/catalog/channels/SQSChannel/index.mdx b/eventcatalog/src/utils/__tests__/messages/catalog/channels/SQSChannel/index.mdx
deleted file mode 100644
index b620b6e0a..000000000
--- a/eventcatalog/src/utils/__tests__/messages/catalog/channels/SQSChannel/index.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
----
-id: SQSChannel
-name: SQS Channel
-version: 1.0.0
-routes:
-  - id: SNSChannel
-    version: 1.0.0
----
-## SQS Channel
diff --git a/eventcatalog/src/utils/__tests__/messages/catalog/events/PaymentProcessed/index.mdx b/eventcatalog/src/utils/__tests__/messages/catalog/events/PaymentProcessed/index.mdx
deleted file mode 100644
index f96042c6a..000000000
--- a/eventcatalog/src/utils/__tests__/messages/catalog/events/PaymentProcessed/index.mdx
+++ /dev/null
@@ -1,6 +0,0 @@
----
-id: PaymentProcessed
-name: Payment Processed
-version: 0.0.1
----
-## Payment Processed
diff --git a/eventcatalog/src/utils/__tests__/messages/catalog/services/OrderService/index.mdx b/eventcatalog/src/utils/__tests__/messages/catalog/services/OrderService/index.mdx
deleted file mode 100644
index edaf0f2b7..000000000
--- a/eventcatalog/src/utils/__tests__/messages/catalog/services/OrderService/index.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-id: OrderService
-name: Order Service
-version: 1.0.0
-receives:
-  - id: PaymentProcessed
-    version: 0.0.1
-    from:
-      - id: SNSChannel
-        version: 1.0.0
----
-## Order Service
diff --git a/eventcatalog/src/utils/__tests__/messages/catalog/services/PaymentService/index.mdx b/eventcatalog/src/utils/__tests__/messages/catalog/services/PaymentService/index.mdx
deleted file mode 100644
index 1a2f21672..000000000
--- a/eventcatalog/src/utils/__tests__/messages/catalog/services/PaymentService/index.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-id: PaymentService
-name: Payment Service
-version: 1.0.0
-sends:
-  - id: PaymentProcessed
-    version: 0.0.1
-    to:
-      - id: EventBridgeChannel
-        version: 1.0.0
----
-## Payment Service
diff --git a/eventcatalog/src/utils/__tests__/messages/messages.spec.ts b/eventcatalog/src/utils/__tests__/messages/messages.spec.ts
deleted file mode 100644
index d26084d47..000000000
--- a/eventcatalog/src/utils/__tests__/messages/messages.spec.ts
+++ /dev/null
@@ -1,145 +0,0 @@
-import type { CollectionEntry, ContentCollectionKey } from 'astro:content';
-import { expect, describe, it, vi } from 'vitest';
-import { mockCommands, mockEvents, mockQueries, mockServices, mockChannels } from './mocks';
-import { getMessages } from '@utils/messages';
-
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    async getCollection<T extends ContentCollectionKey>(key: T, filterFn: (entry: CollectionEntry<T>) => boolean = () => true) {
-      switch (key) {
-        case 'services':
-          return mockServices.filter(filterFn as any);
-        case 'events':
-          return mockEvents.filter(filterFn as any);
-        case 'commands':
-          return mockCommands.filter(filterFn as any);
-        case 'channels':
-          return mockChannels.filter(filterFn as any);
-        case 'queries':
-          return mockQueries.filter(filterFn);
-      }
-    },
-  };
-});
-
-describe('getMessages', () => {
-  it('should return all versions of messages', async () => {
-    await expect(getMessages({ getAllVersions: true })).resolves.toEqual(
-      expect.objectContaining({
-        events: expect.arrayContaining([
-          expect.objectContaining({
-            collection: 'events',
-            data: expect.objectContaining({
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-            }),
-          }),
-          expect.objectContaining({
-            collection: 'events',
-            data: expect.objectContaining({
-              id: 'PaymentProcessed',
-              version: '0.0.2',
-            }),
-          }),
-          expect.objectContaining({
-            collection: 'events',
-            data: expect.objectContaining({
-              id: 'PaymentProcessed',
-              version: '0.1.0',
-            }),
-          }),
-        ]),
-      })
-    );
-  });
-
-  it('should return current versions of messages', async () => {
-    await expect(getMessages({ getAllVersions: false })).resolves.toEqual(
-      expect.objectContaining({
-        commands: expect.arrayContaining([
-          expect.objectContaining({
-            collection: 'commands',
-            data: expect.objectContaining({
-              id: 'ProcessPayment',
-              version: '0.1.0',
-            }),
-          }),
-        ]),
-        events: expect.arrayContaining([
-          expect.objectContaining({
-            collection: 'events',
-            data: expect.objectContaining({
-              id: 'PaymentProcessed',
-              version: '0.1.0',
-            }),
-          }),
-        ]),
-      })
-    );
-  });
-
-  it('should return current versions even if the first call is to get all versions', async () => {
-    await getMessages({ getAllVersions: true });
-
-    const messages = await getMessages({ getAllVersions: false });
-
-    expect(messages).toEqual(
-      expect.objectContaining({
-        queries: [],
-        commands: expect.arrayContaining([
-          expect.objectContaining({
-            collection: 'commands',
-            data: expect.objectContaining({
-              id: 'ProcessPayment',
-              version: '0.1.0',
-            }),
-          }),
-        ]),
-        events: expect.arrayContaining([
-          expect.objectContaining({
-            collection: 'events',
-            data: expect.objectContaining({
-              id: 'PaymentProcessed',
-              version: '0.1.0',
-            }),
-          }),
-        ]),
-      })
-    );
-  });
-
-  it('should return all version even if the first call is to get current versions', async () => {
-    await getMessages({ getAllVersions: false });
-
-    const messages = await getMessages({ getAllVersions: true });
-
-    expect(messages).toEqual(
-      expect.objectContaining({
-        commands: expect.arrayContaining([
-          expect.objectContaining({
-            collection: 'commands',
-            data: expect.objectContaining({
-              id: 'ProcessPayment',
-              version: '0.0.1',
-            }),
-          }),
-          expect.objectContaining({
-            collection: 'commands',
-            data: expect.objectContaining({
-              id: 'ProcessPayment',
-              version: '0.0.2',
-            }),
-          }),
-          expect.objectContaining({
-            collection: 'commands',
-            data: expect.objectContaining({
-              id: 'ProcessPayment',
-              version: '0.1.0',
-            }),
-          }),
-        ]),
-      })
-    );
-  });
-});
diff --git a/eventcatalog/src/utils/__tests__/messages/mocks.ts b/eventcatalog/src/utils/__tests__/messages/mocks.ts
deleted file mode 100644
index b054cf957..000000000
--- a/eventcatalog/src/utils/__tests__/messages/mocks.ts
+++ /dev/null
@@ -1,160 +0,0 @@
-export const mockCommands = [
-  {
-    id: 'ProcessPayment',
-    collection: 'commands',
-    data: {
-      id: 'ProcessPayment',
-      version: '0.0.1',
-      pathToFile: 'commands/ProcessPayment/versioned/0.0.1/index.md',
-    },
-  },
-  {
-    id: 'ProcessPayment',
-    collection: 'commands',
-    data: {
-      id: 'ProcessPayment',
-      version: '0.0.2',
-      pathToFile: 'commands/ProcessPayment/versioned/0.0.2/index.md',
-    },
-  },
-  {
-    id: 'ProcessPayment',
-    collection: 'commands',
-    data: {
-      id: 'ProcessPayment',
-      version: '0.1.0',
-      pathToFile: 'commands/ProcessPayment/index.md',
-    },
-  },
-];
-
-export const mockEvents = [
-  {
-    id: 'PaymentProcessed',
-    collection: 'events',
-    data: {
-      id: 'PaymentProcessed',
-      version: '0.0.1',
-      pathToFile: 'events/PaymentProcessed/versioned/0.0.1/index.md',
-    },
-  },
-  {
-    id: 'PaymentProcessed',
-    collection: 'events',
-    data: {
-      id: 'PaymentProcessed',
-      version: '0.0.2',
-      pathToFile: 'events/PaymentProcessed/versioned/0.0.2/index.md',
-    },
-  },
-  {
-    id: 'PaymentProcessed',
-    collection: 'events',
-    data: {
-      id: 'PaymentProcessed',
-      version: '0.1.0',
-      pathToFile: 'events/PaymentProcessed/index.md',
-    },
-  },
-];
-
-export const mockQueries = [];
-
-export const mockServices = [
-  {
-    id: 'OrdersService',
-    collection: 'services',
-    data: {
-      id: 'OrdersService',
-      version: '1.0.0',
-      pathToFile: 'services/OrdersService/index.md',
-      receives: [
-        {
-          id: 'PaymentProcessed',
-          version: '0.0.1',
-        },
-      ],
-    },
-  },
-  {
-    id: 'ServiceThatReceivesMessagesFromAChannel',
-    collection: 'services',
-    data: {
-      id: 'ServiceThatReceivesMessagesFromAChannel',
-      version: '1.0.0',
-      pathToFile: 'services/OrdersService/index.md',
-      receives: [
-        {
-          id: 'PaymentProcessed',
-          version: '0.0.1',
-          from: [{ id: 'EmailChannel', version: '1.0.0' }],
-        },
-      ],
-    },
-  },
-  {
-    id: 'ServiceThatProducesMessages',
-    collection: 'services',
-    data: {
-      id: 'ServiceThatProducesMessages',
-      version: '1.0.0',
-      pathToFile: 'services/ServiceThatProducesMessages/index.md',
-      sends: [
-        {
-          id: 'PaymentProcessed',
-          version: '0.0.1',
-        },
-      ],
-    },
-  },
-  {
-    id: 'ServiceThatProducesMessagesOverManyChannels',
-    collection: 'services',
-    data: {
-      id: 'ServiceThatProducesMessagesOverManyChannels',
-      version: '1.0.0',
-      pathToFile: 'services/ServiceThatProducesMessagesOverManyChannels/index.md',
-      sends: [
-        {
-          id: 'PaymentProcessed',
-          version: '0.0.1',
-          to: [
-            { id: 'EmailChannel', version: '1.0.0' },
-            { id: 'SNSChannel', version: '1.0.0' },
-            { id: 'SQSChannel', version: '1.0.0' },
-          ],
-        },
-      ],
-    },
-  },
-];
-
-export const mockChannels = [
-  {
-    id: 'EmailChannel',
-    collection: 'channels',
-    data: {
-      id: 'EmailChannel',
-      version: '1.0.0',
-      pathToFile: 'channels/EmailChannel/index.md',
-    },
-  },
-  {
-    id: 'SNSChannel',
-    collection: 'channels',
-    data: {
-      id: 'SNSChannel',
-      version: '1.0.0',
-      pathToFile: 'channels/SmsChannel/index.md',
-    },
-  },
-  {
-    id: 'SQSChannel',
-    collection: 'channels',
-    data: {
-      id: 'SQSChannel',
-      version: '1.0.0',
-      pathToFile: 'channels/SQSChannel/index.md',
-    },
-  },
-];
diff --git a/eventcatalog/src/utils/__tests__/messages/node-graph.spec.ts b/eventcatalog/src/utils/__tests__/messages/node-graph.spec.ts
deleted file mode 100644
index 97feeb054..000000000
--- a/eventcatalog/src/utils/__tests__/messages/node-graph.spec.ts
+++ /dev/null
@@ -1,1476 +0,0 @@
-import { getNodesAndEdgesForConsumedMessage, getNodesAndEdgesForProducedMessage } from '../../node-graphs/message-node-graph';
-import { expect, describe, it, vi, beforeEach } from 'vitest';
-import { mockEvents, mockServices, mockChannels } from './mocks';
-import type { CollectionMessageTypes } from '@types';
-import type { CollectionEntry } from 'astro:content';
-import utils from '@eventcatalog/sdk';
-import path from 'path';
-import fs from 'fs';
-
-const CATALOG_FOLDER = path.join(__dirname, 'catalog');
-
-const toAstroCollection = (item: any, collection: string) => {
-  return {
-    id: item.id,
-    collection: collection,
-    data: item,
-  };
-};
-
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    // this will only affect "foo" outside of the original module
-    getCollection: (key: string) => {
-      if (key === 'services') {
-        return Promise.resolve(mockServices);
-      }
-      if (key === 'channels') {
-        return Promise.resolve(mockChannels);
-      }
-      if (key === 'events') {
-        return Promise.resolve(mockEvents);
-      }
-      return Promise.resolve([]);
-    },
-  };
-});
-
-describe('Message NodeGraph', () => {
-  beforeEach(() => {
-    vi.restoreAllMocks();
-    // Clear the catalog folder but not the folder itself
-    fs.rmSync(CATALOG_FOLDER, { recursive: true, force: true });
-    fs.mkdirSync(CATALOG_FOLDER, { recursive: true });
-  });
-
-  describe('getNodesAndEdgesForConsumedMessage', () => {
-    describe('when the message is consumed by the consumer and the producer and consumer have no channels defined', () => {
-      it('takes a given message, renders the producer and connects the message to the consumer directly', async () => {
-        const message = mockEvents[0] as unknown as CollectionEntry<CollectionMessageTypes>;
-
-        const { nodes, edges } = await getNodesAndEdgesForConsumedMessage({
-          message,
-          services: mockServices as any,
-          channels: mockChannels as any,
-          currentNodes: [],
-          target: mockServices[0] as any,
-          targetChannels: [],
-        });
-
-        // The message node itself
-        const expectedEventNode = {
-          id: 'PaymentProcessed-0.0.1',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          data: expect.anything(),
-          position: { x: expect.any(Number), y: expect.any(Number) },
-          type: 'events',
-        };
-
-        // The producer node itself
-        const expectedProducerNode = {
-          id: 'ServiceThatProducesMessages-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          data: expect.anything(),
-          position: { x: expect.any(Number), y: expect.any(Number) },
-          type: 'services',
-        };
-
-        // The message should be connected to the given target directly
-        const expectedEdges = expect.arrayContaining([
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-OrdersService-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'OrdersService-1.0.0',
-          }),
-          expect.objectContaining({
-            id: 'ServiceThatProducesMessages-1.0.0-PaymentProcessed-0.0.1',
-            source: 'ServiceThatProducesMessages-1.0.0',
-            target: 'PaymentProcessed-0.0.1',
-          }),
-        ]);
-
-        expect(nodes).toEqual(
-          expect.arrayContaining([
-            // The producer that produces the message
-            expect.objectContaining(expectedProducerNode),
-            // The message node itself
-            expect.objectContaining(expectedEventNode),
-          ])
-        );
-        expect(edges).toEqual(expectedEdges);
-      });
-    });
-
-    describe('producer with a channel defined', () => {
-      it('when the producer sends a message over a channel but the consumer does not read from that channel, no channel nodes are created, and the message is connected to the consumer directly', async () => {
-        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
-
-        // The message itself
-        await writeEvent({
-          id: 'PaymentProcessed',
-          name: 'Payment Processed',
-          version: '0.0.1',
-          markdown: '## Payment Processed',
-        });
-
-        // Email Channel
-        await writeChannel({
-          id: 'SQSChannel',
-          name: 'SQS Channel',
-          version: '1.0.0',
-          markdown: '## SQS Channel',
-        });
-
-        // The Producer
-        await writeService({
-          id: 'OrderService',
-          name: 'Order Service',
-          version: '1.0.0',
-          markdown: '## Order Service',
-          sends: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              to: [{ id: 'SQSChannel', version: '1.0.0' }],
-            },
-          ],
-        });
-
-        // The Consumer
-        await writeService({
-          id: 'PaymentService',
-          name: 'Service That Receives Messages Without Channels',
-          version: '1.0.0',
-          markdown: '## Service That Receives Messages Without Channels',
-          receives: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-            },
-          ],
-        });
-
-        const message = toAstroCollection(
-          await getEvent('PaymentProcessed'),
-          'events'
-        ) as unknown as CollectionEntry<CollectionMessageTypes>;
-        const services = await getServices().then(
-          (services) =>
-            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
-        );
-        const channels = await getChannels().then(
-          (channels) =>
-            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
-        );
-
-        const target = toAstroCollection(
-          await getService('PaymentService'),
-          'services'
-        ) as unknown as CollectionEntry<'services'>;
-
-        const { nodes, edges } = await getNodesAndEdgesForConsumedMessage({
-          message,
-          services: services,
-          channels: channels,
-          currentNodes: [],
-          target,
-        });
-
-        const channelNodes = nodes.filter((node) => node.type === 'channels');
-
-        expect(channelNodes).toEqual([]);
-
-        const expectedEdges = expect.arrayContaining([
-          expect.objectContaining({
-            id: 'OrderService-1.0.0-PaymentProcessed-0.0.1',
-            source: 'OrderService-1.0.0',
-            target: 'PaymentProcessed-0.0.1',
-          }),
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-PaymentService-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'PaymentService-1.0.0',
-          }),
-        ]);
-
-        expect(edges).toEqual(expectedEdges);
-      });
-
-      it('when the producer sends a message over many channels only the matching channels are rendered', async () => {
-        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
-
-        // The message itself
-        await writeEvent({
-          id: 'PaymentProcessed',
-          name: 'Payment Processed',
-          version: '0.0.1',
-          markdown: '## Payment Processed',
-        });
-
-        // SQS Channel
-        await writeChannel({
-          id: 'SQSChannel',
-          name: 'SQS Channel',
-          version: '1.0.0',
-          markdown: '## SQS Channel',
-        });
-
-        // SNS Channel
-        await writeChannel({
-          id: 'SNSChannel',
-          name: 'SNS Channel',
-          version: '1.0.0',
-          markdown: '## SNS Channel',
-        });
-
-        // The Producer
-        await writeService({
-          id: 'OrderService',
-          name: 'Order Service',
-          version: '1.0.0',
-          markdown: '## Order Service',
-          sends: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              to: [
-                { id: 'SQSChannel', version: '1.0.0' },
-                { id: 'SNSChannel', version: '1.0.0' },
-              ],
-            },
-          ],
-        });
-
-        // The Consumer
-        await writeService({
-          id: 'PaymentService',
-          name: 'Service That Receives Messages Without Channels',
-          version: '1.0.0',
-          markdown: '## Service That Receives Messages Without Channels',
-          receives: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              from: [{ id: 'SQSChannel', version: '1.0.0' }],
-            },
-          ],
-        });
-
-        const message = toAstroCollection(
-          await getEvent('PaymentProcessed'),
-          'events'
-        ) as unknown as CollectionEntry<CollectionMessageTypes>;
-        const services = await getServices().then(
-          (services) =>
-            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
-        );
-        const channels = await getChannels().then(
-          (channels) =>
-            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
-        );
-
-        const target = toAstroCollection(
-          await getService('PaymentService'),
-          'services'
-        ) as unknown as CollectionEntry<'services'>;
-
-        const { nodes, edges } = await getNodesAndEdgesForConsumedMessage({
-          message,
-          services: services,
-          channels: channels,
-          currentNodes: [],
-          target,
-        });
-
-        const expectedChannelNode = expect.objectContaining({
-          id: 'SQSChannel-1.0.0',
-          type: 'channels',
-          position: { x: expect.any(Number), y: expect.any(Number) },
-          data: expect.anything(),
-          sourcePosition: 'right',
-          targetPosition: 'left',
-        });
-
-        const expectedEdges = expect.arrayContaining([
-          // Producer to the message
-          expect.objectContaining({
-            id: 'OrderService-1.0.0-PaymentProcessed-0.0.1',
-            source: 'OrderService-1.0.0',
-            target: 'PaymentProcessed-0.0.1',
-          }),
-          // Message to the channel
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-SQSChannel-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'SQSChannel-1.0.0',
-          }),
-          // Channel to the consumer
-          expect.objectContaining({
-            id: 'SQSChannel-1.0.0-PaymentService-1.0.0',
-            source: 'SQSChannel-1.0.0',
-            target: 'PaymentService-1.0.0',
-          }),
-        ]);
-
-        expect(nodes).toEqual(expect.arrayContaining([expectedChannelNode]));
-
-        const allChannelNodes = nodes.filter((node) => node.type === 'channels');
-        expect(allChannelNodes).toHaveLength(1);
-
-        expect(edges).toEqual(expectedEdges);
-      });
-
-      it('when the producer sends a message over a channel and the channel chains to the target channel, the channel chain is rendered', async () => {
-        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
-
-        // The message itself
-        await writeEvent({
-          id: 'PaymentProcessed',
-          name: 'Payment Processed',
-          version: '0.0.1',
-          markdown: '## Payment Processed',
-        });
-
-        // EventBridge Channel
-        await writeChannel({
-          id: 'EventBridgeChannel',
-          name: 'EventBridge Channel',
-          version: '1.0.0',
-          markdown: '## EventBridge Channel',
-          routes: [
-            {
-              id: 'SNSChannel',
-              version: '1.0.0',
-            },
-          ],
-        });
-
-        // SNS Channel
-        await writeChannel({
-          id: 'SNSChannel',
-          name: 'SNS Channel',
-          version: '1.0.0',
-          markdown: '## SNS Channel',
-          routes: [
-            {
-              id: 'SQSChannel',
-              version: '1.0.0',
-            },
-          ],
-        });
-
-        // SQS Channel
-        await writeChannel({
-          id: 'SQSChannel',
-          name: 'SQS Channel',
-          version: '1.0.0',
-          markdown: '## SQS Channel',
-        });
-
-        // The Producer
-        await writeService({
-          id: 'OrderService',
-          name: 'Order Service',
-          version: '1.0.0',
-          markdown: '## Order Service',
-          sends: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              to: [{ id: 'EventBridgeChannel', version: '1.0.0' }],
-            },
-          ],
-        });
-
-        // The Consumer
-        await writeService({
-          id: 'PaymentService',
-          name: 'Service That Receives Messages Without Channels',
-          version: '1.0.0',
-          markdown: '## Service That Receives Messages Without Channels',
-          receives: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              from: [{ id: 'SQSChannel', version: '1.0.0' }],
-            },
-          ],
-        });
-
-        const message = toAstroCollection(
-          await getEvent('PaymentProcessed'),
-          'events'
-        ) as unknown as CollectionEntry<CollectionMessageTypes>;
-        const services = await getServices().then(
-          (services) =>
-            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
-        );
-        const channels = await getChannels().then(
-          (channels) =>
-            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
-        );
-
-        const target = toAstroCollection(
-          await getService('PaymentService'),
-          'services'
-        ) as unknown as CollectionEntry<'services'>;
-
-        const { nodes, edges } = await getNodesAndEdgesForConsumedMessage({
-          message,
-          services: services,
-          channels: channels,
-          currentNodes: [],
-          target,
-        });
-
-        const channelNodes = nodes.filter((node) => node.type === 'channels');
-        expect(channelNodes).toHaveLength(3);
-
-        const expectedEventBusChannelNode = expect.objectContaining({
-          id: 'EventBridgeChannel-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'channels',
-        });
-
-        const expectedSNSChannelNode = expect.objectContaining({
-          id: 'SNSChannel-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'channels',
-        });
-
-        const expectedSQSChannelNode = expect.objectContaining({
-          id: 'SQSChannel-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'channels',
-        });
-
-        const expectedEdges = expect.arrayContaining([
-          // Producer to the event first....
-          expect.objectContaining({
-            id: 'OrderService-1.0.0-PaymentProcessed-0.0.1',
-            source: 'OrderService-1.0.0',
-            target: 'PaymentProcessed-0.0.1',
-          }),
-          // The message to the first channel
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-EventBridgeChannel-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'EventBridgeChannel-1.0.0',
-          }),
-          // // The next channel in the chain
-          expect.objectContaining({
-            id: 'EventBridgeChannel-1.0.0-SNSChannel-1.0.0',
-            source: 'EventBridgeChannel-1.0.0',
-            target: 'SNSChannel-1.0.0',
-          }),
-          // The next channel in the chain
-          expect.objectContaining({
-            id: 'SNSChannel-1.0.0-SQSChannel-1.0.0',
-            source: 'SNSChannel-1.0.0',
-            target: 'SQSChannel-1.0.0',
-          }),
-          // Final channel to the consumer
-          expect.objectContaining({
-            id: 'SQSChannel-1.0.0-PaymentService-1.0.0',
-            source: 'SQSChannel-1.0.0',
-            target: 'PaymentService-1.0.0',
-          }),
-        ]);
-
-        expect(nodes).toEqual(
-          expect.arrayContaining([
-            // Expected channel nodes
-            expectedEventBusChannelNode,
-            expectedSNSChannelNode,
-            expectedSQSChannelNode,
-          ])
-        );
-
-        expect(edges).toEqual(expectedEdges);
-      });
-    });
-
-    describe('target with channel defined', () => {
-      it('when the producer does not send the message to a channel, but the target has a channel defined, the message is connected to the channel node and the channel node to the target directly', async () => {
-        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
-
-        // The message itself
-        await writeEvent({
-          id: 'PaymentProcessed',
-          name: 'Payment Processed',
-          version: '0.0.1',
-          markdown: '## Payment Processed',
-        });
-
-        // Producer
-        await writeService({
-          id: 'OrderService',
-          name: 'Order Service',
-          version: '1.0.0',
-          markdown: '## Order Service',
-          sends: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-            },
-          ],
-        });
-
-        // Target
-        await writeService({
-          id: 'PaymentService',
-          name: 'Payment Service',
-          version: '1.0.0',
-          markdown: '## Payment Service',
-          receives: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              from: [{ id: 'SQSChannel', version: '1.0.0' }],
-            },
-          ],
-        });
-
-        await writeChannel({
-          id: 'SQSChannel',
-          name: 'SQS Channel',
-          version: '1.0.0',
-          markdown: '## SQS Channel',
-        });
-
-        const message = toAstroCollection(
-          await getEvent('PaymentProcessed'),
-          'events'
-        ) as unknown as CollectionEntry<CollectionMessageTypes>;
-        const services = await getServices().then(
-          (services) =>
-            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
-        );
-        const channels = await getChannels().then(
-          (channels) =>
-            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
-        );
-
-        const target = toAstroCollection(
-          await getService('PaymentService'),
-          'services'
-        ) as unknown as CollectionEntry<'services'>;
-
-        const { nodes, edges } = await getNodesAndEdgesForConsumedMessage({
-          message,
-          services: services,
-          channels: channels,
-          currentNodes: [],
-          target,
-          targetChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
-        });
-
-        const expectedChannelNode = expect.objectContaining({
-          id: 'SQSChannel-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'channels',
-        });
-
-        const expectedEdges = expect.arrayContaining([
-          // Producer to the message
-          expect.objectContaining({
-            id: 'OrderService-1.0.0-PaymentProcessed-0.0.1',
-            source: 'OrderService-1.0.0',
-            target: 'PaymentProcessed-0.0.1',
-          }),
-          // Message to the channel
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-SQSChannel-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'SQSChannel-1.0.0',
-          }),
-          // // Channel to the target
-          // expect.objectContaining({
-          //     id: 'SQSChannel-1.0.0-PaymentService-1.0.0',
-          //     source: 'SQSChannel-1.0.0',
-          //     target: 'PaymentService-1.0.0',
-          // }),
-        ]);
-
-        expect(nodes).toEqual(expect.arrayContaining([expectedChannelNode]));
-
-        expect(edges).toEqual(expectedEdges);
-      });
-    });
-  });
-
-  describe('getNodesAndEdgesForProducedMessage', () => {
-    describe('when the message is produced by the producer and the producer and consumer have no channels defined', () => {
-      it('renders the producer publishing the message directly to the consumer', async () => {
-        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
-
-        // The message itself
-        await writeEvent({
-          id: 'PaymentProcessed',
-          name: 'Payment Processed',
-          version: '0.0.1',
-          markdown: '## Payment Processed',
-        });
-
-        // The producer
-        await writeService({
-          id: 'PaymentService',
-          name: 'Payment Service',
-          version: '1.0.0',
-          markdown: '## Payment Service',
-          sends: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-            },
-          ],
-        });
-
-        // The Consumer
-        await writeService({
-          id: 'OrderService',
-          name: 'Order Service',
-          version: '1.0.0',
-          markdown: '## Order Service',
-          receives: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-            },
-          ],
-        });
-
-        const message = toAstroCollection(
-          await getEvent('PaymentProcessed'),
-          'events'
-        ) as unknown as CollectionEntry<CollectionMessageTypes>;
-        const services = await getServices().then(
-          (services) =>
-            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
-        );
-
-        const source = toAstroCollection(
-          await getService('PaymentService'),
-          'services'
-        ) as unknown as CollectionEntry<'services'>;
-
-        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
-          message,
-          services: services,
-          channels: [],
-          currentNodes: [],
-          source,
-          currentEdges: [],
-        });
-
-        const expectedProducerNode = expect.objectContaining({
-          id: 'PaymentService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedMessageNode = expect.objectContaining({
-          id: 'PaymentProcessed-0.0.1',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'events',
-        });
-
-        const expectedConsumerNode = expect.objectContaining({
-          id: 'OrderService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedEdges = expect.arrayContaining([
-          // Producer to the message
-          expect.objectContaining({
-            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
-            source: 'PaymentService-1.0.0',
-            target: 'PaymentProcessed-0.0.1',
-          }),
-          // Message to the consumer
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-OrderService-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'OrderService-1.0.0',
-          }),
-        ]);
-
-        expect(edges).toEqual(expectedEdges);
-
-        expect(nodes).toEqual(expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedConsumerNode]));
-
-        expect(edges).toEqual(expectedEdges);
-      });
-    });
-
-    describe('when the message is produced by the producer and the producer defines a channel', () => {
-      it('renders the producer publishing the message to the channel', async () => {
-        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
-
-        // The message itself
-        await writeEvent({
-          id: 'PaymentProcessed',
-          name: 'Payment Processed',
-          version: '0.0.1',
-          markdown: '## Payment Processed',
-        });
-
-        // The producer
-        await writeService({
-          id: 'PaymentService',
-          name: 'Payment Service',
-          version: '1.0.0',
-          markdown: '## Payment Service',
-          sends: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              to: [{ id: 'SQSChannel', version: '1.0.0' }],
-            },
-          ],
-        });
-
-        // The channel
-        await writeChannel({
-          id: 'SQSChannel',
-          name: 'SQS Channel',
-          version: '1.0.0',
-          markdown: '## SQS Channel',
-        });
-
-        const message = toAstroCollection(
-          await getEvent('PaymentProcessed'),
-          'events'
-        ) as unknown as CollectionEntry<CollectionMessageTypes>;
-        const services = await getServices().then(
-          (services) =>
-            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
-        );
-        const channels = await getChannels().then(
-          (channels) =>
-            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
-        );
-
-        const source = toAstroCollection(
-          await getService('PaymentService'),
-          'services'
-        ) as unknown as CollectionEntry<'services'>;
-
-        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
-          message,
-          services: services,
-          channels: channels,
-          currentNodes: [],
-          sourceChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
-          source,
-          currentEdges: [],
-        });
-
-        const expectedProducerNode = expect.objectContaining({
-          id: 'PaymentService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedMessageNode = expect.objectContaining({
-          id: 'PaymentProcessed-0.0.1',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'events',
-        });
-
-        const expectedChannelNode = expect.objectContaining({
-          id: 'SQSChannel-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'channels',
-        });
-
-        const expectedEdges = expect.arrayContaining([
-          // Producer to the message
-          expect.objectContaining({
-            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
-            source: 'PaymentService-1.0.0',
-            target: 'PaymentProcessed-0.0.1',
-          }),
-          // Message to the channel
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-SQSChannel-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'SQSChannel-1.0.0',
-          }),
-        ]);
-
-        expect(nodes).toEqual(expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedChannelNode]));
-
-        expect(edges).toEqual(expectedEdges);
-      });
-    });
-
-    describe('when the message is produced by the producer without a channel, but the consumer defines a channel', () => {
-      it('renders the producer publishing the message to the consumers channel', async () => {
-        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
-
-        // The message itself
-        await writeEvent({
-          id: 'PaymentProcessed',
-          name: 'Payment Processed',
-          version: '0.0.1',
-          markdown: '## Payment Processed',
-        });
-
-        // The producer
-        await writeService({
-          id: 'PaymentService',
-          name: 'Payment Service',
-          version: '1.0.0',
-          markdown: '## Payment Service',
-        });
-
-        // The channel
-        await writeChannel({
-          id: 'SQSChannel',
-          name: 'SQS Channel',
-          version: '1.0.0',
-          markdown: '## SQS Channel',
-        });
-
-        // The consumer
-        await writeService({
-          id: 'OrderService',
-          name: 'Order Service',
-          version: '1.0.0',
-          markdown: '## Order Service',
-          receives: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              from: [{ id: 'SQSChannel', version: '1.0.0' }],
-            },
-          ],
-        });
-
-        const message = toAstroCollection(
-          await getEvent('PaymentProcessed'),
-          'events'
-        ) as unknown as CollectionEntry<CollectionMessageTypes>;
-        const services = await getServices().then(
-          (services) =>
-            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
-        );
-        const channels = await getChannels().then(
-          (channels) =>
-            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
-        );
-
-        const source = toAstroCollection(
-          await getService('PaymentService'),
-          'services'
-        ) as unknown as CollectionEntry<'services'>;
-
-        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
-          message,
-          services: services,
-          channels: channels,
-          currentNodes: [],
-          sourceChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
-          source,
-          currentEdges: [],
-        });
-
-        const expectedProducerNode = expect.objectContaining({
-          id: 'PaymentService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedMessageNode = expect.objectContaining({
-          id: 'PaymentProcessed-0.0.1',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'events',
-        });
-
-        const expectedChannelNode = expect.objectContaining({
-          id: 'SQSChannel-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'channels',
-        });
-
-        const expectedConsumerNode = expect.objectContaining({
-          id: 'OrderService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedEdges = expect.arrayContaining([
-          // Producer to the message
-          expect.objectContaining({
-            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
-            source: 'PaymentService-1.0.0',
-            target: 'PaymentProcessed-0.0.1',
-          }),
-          // Message to the channel
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-SQSChannel-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'SQSChannel-1.0.0',
-          }),
-          // Channel to the consumer
-          expect.objectContaining({
-            id: 'SQSChannel-1.0.0-OrderService-1.0.0',
-            source: 'SQSChannel-1.0.0',
-            target: 'OrderService-1.0.0',
-          }),
-        ]);
-
-        expect(nodes).toEqual(
-          expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedChannelNode, expectedConsumerNode])
-        );
-
-        expect(edges).toEqual(expectedEdges);
-      });
-
-      it('if the consumer defines a channel that does not exist in EventCatalog, the message is connected to the consumer directly', async () => {
-        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
-
-        // The message itself
-        await writeEvent({
-          id: 'PaymentProcessed',
-          name: 'Payment Processed',
-          version: '0.0.1',
-          markdown: '## Payment Processed',
-        });
-
-        // The producer
-        await writeService({
-          id: 'PaymentService',
-          name: 'Payment Service',
-          version: '1.0.0',
-          markdown: '## Payment Service',
-        });
-
-        // The consumer
-        await writeService({
-          id: 'OrderService',
-          name: 'Order Service',
-          version: '1.0.0',
-          markdown: '## Order Service',
-          receives: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              from: [{ id: 'NonExistentChannel', version: '1.0.0' }],
-            },
-          ],
-        });
-
-        const message = toAstroCollection(
-          await getEvent('PaymentProcessed'),
-          'events'
-        ) as unknown as CollectionEntry<CollectionMessageTypes>;
-        const services = await getServices().then(
-          (services) =>
-            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
-        );
-
-        const source = toAstroCollection(
-          await getService('PaymentService'),
-          'services'
-        ) as unknown as CollectionEntry<'services'>;
-
-        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
-          message,
-          services: services,
-          channels: [],
-          currentNodes: [],
-          sourceChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
-          source,
-          currentEdges: [],
-        });
-
-        const expectedProducerNode = expect.objectContaining({
-          id: 'PaymentService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedMessageNode = expect.objectContaining({
-          id: 'PaymentProcessed-0.0.1',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'events',
-        });
-
-        const expectedConsumerNode = expect.objectContaining({
-          id: 'OrderService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedEdges = expect.arrayContaining([
-          // Producer to the message
-          expect.objectContaining({
-            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
-            source: 'PaymentService-1.0.0',
-            target: 'PaymentProcessed-0.0.1',
-          }),
-          // Message to the consumer directly
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-OrderService-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'OrderService-1.0.0',
-          }),
-        ]);
-
-        expect(nodes).toEqual(expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedConsumerNode]));
-
-        expect(edges).toEqual(expectedEdges);
-      });
-    });
-
-    describe('When the message is produced with a channel, but the consumer does not define a channel?', () => {
-      it('renders the producer publishing the message to the channel, but the consumer consumes the message directly from the producer', async () => {
-        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
-
-        // The message itself
-        await writeEvent({
-          id: 'PaymentProcessed',
-          name: 'Payment Processed',
-          version: '0.0.1',
-          markdown: '## Payment Processed',
-        });
-
-        // The producer
-        await writeService({
-          id: 'PaymentService',
-          name: 'Payment Service',
-          version: '1.0.0',
-          markdown: '## Payment Service',
-        });
-
-        // The channel
-        await writeChannel({
-          id: 'SQSChannel',
-          name: 'SQS Channel',
-          version: '1.0.0',
-          markdown: '## SQS Channel',
-        });
-
-        // The consumer
-        await writeService({
-          id: 'OrderService',
-          name: 'Order Service',
-          version: '1.0.0',
-          markdown: '## Order Service',
-          receives: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-            },
-          ],
-        });
-
-        const message = toAstroCollection(
-          await getEvent('PaymentProcessed'),
-          'events'
-        ) as unknown as CollectionEntry<CollectionMessageTypes>;
-        const services = await getServices().then(
-          (services) =>
-            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
-        );
-        const channels = await getChannels().then(
-          (channels) =>
-            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
-        );
-
-        const source = toAstroCollection(
-          await getService('PaymentService'),
-          'services'
-        ) as unknown as CollectionEntry<'services'>;
-
-        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
-          message,
-          services: services,
-          channels: channels,
-          currentNodes: [],
-          sourceChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
-          source,
-          currentEdges: [],
-        });
-
-        const expectedProducerNode = expect.objectContaining({
-          id: 'PaymentService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedMessageNode = expect.objectContaining({
-          id: 'PaymentProcessed-0.0.1',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'events',
-        });
-
-        const expectedChannelNode = expect.objectContaining({
-          id: 'SQSChannel-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'channels',
-        });
-
-        const expectedConsumerNode = expect.objectContaining({
-          id: 'OrderService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedEdges = expect.arrayContaining([
-          // Producer to the message
-          expect.objectContaining({
-            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
-            source: 'PaymentService-1.0.0',
-            target: 'PaymentProcessed-0.0.1',
-          }),
-          // Message to the channel
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-SQSChannel-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'SQSChannel-1.0.0',
-          }),
-          // Message to the consumer directly
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-OrderService-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'OrderService-1.0.0',
-          }),
-        ]);
-
-        expect(nodes).toEqual(
-          expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedChannelNode, expectedConsumerNode])
-        );
-
-        expect(edges).toEqual(expectedEdges);
-      });
-    });
-
-    describe('when the message is produced by the producer and the producer defines a channel and the consumer also defines the same channel (consuming from the channel)', () => {
-      it('renders the producer publishing the message to the channel and the consumer consuming the message from the channel', async () => {
-        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
-
-        // The message itself
-        await writeEvent({
-          id: 'PaymentProcessed',
-          name: 'Payment Processed',
-          version: '0.0.1',
-          markdown: '## Payment Processed',
-        });
-
-        // The producer
-        await writeService({
-          id: 'PaymentService',
-          name: 'Payment Service',
-          version: '1.0.0',
-          markdown: '## Payment Service',
-          sends: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              to: [{ id: 'SQSChannel', version: '1.0.0' }],
-            },
-          ],
-        });
-
-        // The channel
-        await writeChannel({
-          id: 'SQSChannel',
-          name: 'SQS Channel',
-          version: '1.0.0',
-          markdown: '## SQS Channel',
-        });
-
-        // The consumer
-        await writeService({
-          id: 'OrderService',
-          name: 'Order Service',
-          version: '1.0.0',
-          markdown: '## Order Service',
-          receives: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              from: [{ id: 'SQSChannel', version: '1.0.0' }],
-            },
-          ],
-        });
-
-        const message = toAstroCollection(
-          await getEvent('PaymentProcessed'),
-          'events'
-        ) as unknown as CollectionEntry<CollectionMessageTypes>;
-        const services = await getServices().then(
-          (services) =>
-            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
-        );
-        const channels = await getChannels().then(
-          (channels) =>
-            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
-        );
-
-        const source = toAstroCollection(
-          await getService('PaymentService'),
-          'services'
-        ) as unknown as CollectionEntry<'services'>;
-
-        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
-          message,
-          services: services,
-          channels: channels,
-          currentNodes: [],
-          sourceChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
-          source,
-          currentEdges: [],
-        });
-
-        const expectedProducerNode = expect.objectContaining({
-          id: 'PaymentService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedMessageNode = expect.objectContaining({
-          id: 'PaymentProcessed-0.0.1',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'events',
-        });
-
-        const expectedChannelNode = expect.objectContaining({
-          id: 'SQSChannel-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'channels',
-        });
-
-        const expectedConsumerNode = expect.objectContaining({
-          id: 'OrderService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedEdges = expect.arrayContaining([
-          // Producer to the message
-          expect.objectContaining({
-            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
-            source: 'PaymentService-1.0.0',
-            target: 'PaymentProcessed-0.0.1',
-          }),
-          // Message to the channel
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-SQSChannel-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'SQSChannel-1.0.0',
-          }),
-          // Channel to the consumer
-          expect.objectContaining({
-            id: 'SQSChannel-1.0.0-OrderService-1.0.0',
-            source: 'SQSChannel-1.0.0',
-            target: 'OrderService-1.0.0',
-          }),
-        ]);
-
-        expect(nodes).toEqual(
-          expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedChannelNode, expectedConsumerNode])
-        );
-
-        expect(edges).toEqual(expectedEdges);
-      });
-    });
-
-    describe('when the message is produced by the producer and the producer defines a channel and the consumer also defines a channel but its a chain of channels', () => {
-      it('renders the producer publishing the message to the channel and the consumer consuming the message from the channel chain', async () => {
-        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
-
-        // The message itself
-        await writeEvent({
-          id: 'PaymentProcessed',
-          name: 'Payment Processed',
-          version: '0.0.1',
-          markdown: '## Payment Processed',
-        });
-
-        // The producer
-        await writeService({
-          id: 'PaymentService',
-          name: 'Payment Service',
-          version: '1.0.0',
-          markdown: '## Payment Service',
-          sends: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              to: [{ id: 'EventBridgeChannel', version: '1.0.0' }],
-            },
-          ],
-        });
-
-        // The first channel
-        await writeChannel({
-          id: 'EventBridgeChannel',
-          name: 'EventBridge Channel',
-          version: '1.0.0',
-          markdown: '## EventBridge Channel',
-          routes: [{ id: 'SQSChannel', version: '1.0.0' }],
-        });
-
-        // The second channel
-        await writeChannel({
-          id: 'SQSChannel',
-          name: 'SQS Channel',
-          version: '1.0.0',
-          markdown: '## SQS Channel',
-          routes: [{ id: 'SNSChannel', version: '1.0.0' }],
-        });
-
-        // The third channel
-        await writeChannel({
-          id: 'SNSChannel',
-          name: 'SNS Channel',
-          version: '1.0.0',
-          markdown: '## SNS Channel',
-        });
-
-        // The consumer
-        await writeService({
-          id: 'OrderService',
-          name: 'Order Service',
-          version: '1.0.0',
-          markdown: '## Order Service',
-          receives: [
-            {
-              id: 'PaymentProcessed',
-              version: '0.0.1',
-              from: [{ id: 'SNSChannel', version: '1.0.0' }],
-            },
-          ],
-        });
-
-        const message = toAstroCollection(
-          await getEvent('PaymentProcessed'),
-          'events'
-        ) as unknown as CollectionEntry<CollectionMessageTypes>;
-        const services = await getServices().then(
-          (services) =>
-            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
-        );
-        const channels = await getChannels().then(
-          (channels) =>
-            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
-        );
-
-        const source = toAstroCollection(
-          await getService('PaymentService'),
-          'services'
-        ) as unknown as CollectionEntry<'services'>;
-
-        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
-          message,
-          services: services,
-          channels: channels,
-          currentNodes: [],
-          sourceChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
-          source,
-          currentEdges: [],
-        });
-
-        const expectedProducerNode = expect.objectContaining({
-          id: 'PaymentService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedMessageNode = expect.objectContaining({
-          id: 'PaymentProcessed-0.0.1',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'events',
-        });
-
-        const expectedChannelNode = expect.objectContaining({
-          id: 'SQSChannel-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'channels',
-        });
-
-        const expectedConsumerNode = expect.objectContaining({
-          id: 'OrderService-1.0.0',
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-        });
-
-        const expectedEdges = expect.arrayContaining([
-          // Producer to the message
-          expect.objectContaining({
-            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
-            source: 'PaymentService-1.0.0',
-            target: 'PaymentProcessed-0.0.1',
-          }),
-          // Message to the first channel
-          expect.objectContaining({
-            id: 'PaymentProcessed-0.0.1-EventBridgeChannel-1.0.0',
-            source: 'PaymentProcessed-0.0.1',
-            target: 'EventBridgeChannel-1.0.0',
-          }),
-          // First channel to the second channel
-          expect.objectContaining({
-            id: 'EventBridgeChannel-1.0.0-SQSChannel-1.0.0',
-            source: 'EventBridgeChannel-1.0.0',
-            target: 'SQSChannel-1.0.0',
-          }),
-          // Second channel to the third channel
-          expect.objectContaining({
-            id: 'SQSChannel-1.0.0-SNSChannel-1.0.0',
-            source: 'SQSChannel-1.0.0',
-            target: 'SNSChannel-1.0.0',
-          }),
-          // Third channel to the consumer
-          expect.objectContaining({
-            id: 'SNSChannel-1.0.0-OrderService-1.0.0',
-            source: 'SNSChannel-1.0.0',
-            target: 'OrderService-1.0.0',
-          }),
-        ]);
-
-        expect(nodes).toEqual(
-          expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedChannelNode, expectedConsumerNode])
-        );
-
-        expect(edges).toEqual(expectedEdges);
-      });
-    });
-  });
-});
diff --git a/eventcatalog/src/utils/__tests__/queries/mocks.ts b/eventcatalog/src/utils/__tests__/queries/mocks.ts
deleted file mode 100644
index aadf023ab..000000000
--- a/eventcatalog/src/utils/__tests__/queries/mocks.ts
+++ /dev/null
@@ -1,179 +0,0 @@
-export const mockServices = [
-  {
-    id: 'OrderService',
-    slug: 'OrderService',
-    collection: 'services',
-    data: {
-      id: 'OrderService',
-      version: '0.0.1',
-      sends: [
-        {
-          id: 'GetLatestOrder',
-          version: '0.0.1',
-        },
-      ],
-      receives: [
-        {
-          id: 'GetProductStatus',
-          version: '0.0.1',
-          from: [
-            {
-              id: 'EmailChannel',
-              version: '1.0.0',
-            },
-          ],
-        },
-      ],
-    },
-  },
-  {
-    id: 'PaymentService',
-    slug: 'PaymentService',
-    collection: 'services',
-    data: {
-      id: 'PaymentService',
-      version: '0.0.1',
-      receives: [
-        {
-          id: 'GetLatestOrder',
-          version: '0.0.1',
-        },
-      ],
-    },
-  },
-  {
-    id: 'InventoryService',
-    slug: 'InventoryService',
-    collection: 'services',
-    data: {
-      id: 'InventoryService',
-      version: '0.0.1',
-      sends: [
-        {
-          id: 'GetInventoryItem',
-          version: '>1.2.0',
-        },
-        {
-          id: 'GetProductStatus',
-          version: '0.0.1',
-          from: [
-            {
-              id: 'EmailChannel',
-              version: '1.0.0',
-            },
-          ],
-        },
-        {
-          id: 'GetStockStatus',
-          version: 'latest',
-        },
-      ],
-    },
-  },
-  {
-    id: 'CatalogService',
-    slug: 'CatalogService',
-    collection: 'services',
-    data: {
-      id: 'CatalogService',
-      version: '0.0.1',
-      receives: [
-        {
-          id: 'GetInventoryItem',
-        },
-        {
-          id: 'GetStockStatus',
-          version: '*',
-        },
-      ],
-    },
-  },
-  {
-    id: 'LegacyOrderService',
-    slug: 'LegacyOrderService',
-    collection: 'services',
-    data: {
-      id: 'LegacyOrderService',
-      version: '0.0.1',
-      receives: [
-        {
-          id: 'GetOrderLegacy',
-        },
-      ],
-      sends: [
-        {
-          id: 'GetOrderLegacy',
-        },
-      ],
-    },
-  },
-];
-
-export const mockQueries = [
-  {
-    id: 'GetLatestOrder',
-    slug: 'GetLatestOrder',
-    collection: 'queries',
-    data: {
-      id: 'GetLatestOrder',
-      version: '0.0.1',
-    },
-  },
-  {
-    id: 'GetInventoryItem',
-    slug: 'GetInventoryItem',
-    collection: 'queries',
-    data: {
-      id: 'GetInventoryItem',
-      version: '1.5.1',
-    },
-  },
-  {
-    id: 'GetStockStatus',
-    slug: 'GetStockStatus',
-    collection: 'queries',
-    data: {
-      id: 'GetStockStatus',
-      version: '0.0.1',
-    },
-  },
-  {
-    id: 'GetStockStatus',
-    slug: 'GetStockStatus',
-    collection: 'queries',
-    data: {
-      id: 'GetStockStatus',
-      version: '1.0.0',
-    },
-  },
-  {
-    id: 'GetProductStatus',
-    slug: 'GetProductStatus',
-    collection: 'queries',
-    data: {
-      id: 'GetProductStatus',
-      version: '0.0.1',
-    },
-  },
-  {
-    id: 'GetOrderLegacy',
-    slug: 'GetOrderLegacy',
-    collection: 'queries',
-    data: {
-      id: 'GetOrderLegacy',
-      version: '0.0.1',
-    },
-  },
-];
-
-export const mockChannels = [
-  {
-    id: 'EmailChannel',
-    slug: 'EmailChannel',
-    collection: 'channels',
-    data: {
-      id: 'EmailChannel',
-      version: '1.0.0',
-    },
-  },
-];
diff --git a/eventcatalog/src/utils/__tests__/queries/node-graph.spec.ts b/eventcatalog/src/utils/__tests__/queries/node-graph.spec.ts
deleted file mode 100644
index 5466cd1a6..000000000
--- a/eventcatalog/src/utils/__tests__/queries/node-graph.spec.ts
+++ /dev/null
@@ -1,362 +0,0 @@
-import { MarkerType } from '@xyflow/react';
-import { getNodesAndEdgesForQueries as getNodesAndEdges } from '../../node-graphs/message-node-graph';
-import { expect, describe, it, vi, beforeEach } from 'vitest';
-import { mockQueries, mockServices, mockChannels } from './mocks';
-
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    // this will only affect "foo" outside of the original module
-    getCollection: (key: string) => {
-      if (key === 'services') {
-        return Promise.resolve(mockServices);
-      }
-      if (key === 'queries') {
-        return Promise.resolve(mockQueries);
-      }
-      if (key === 'channels') {
-        return Promise.resolve(mockChannels);
-      }
-      return Promise.resolve([]);
-    },
-  };
-});
-
-describe('Queries NodeGraph', () => {
-  beforeEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  describe('getNodesAndEdges', () => {
-    it('should return nodes and edges for a given query', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'GetLatestOrder', version: '0.0.1' });
-
-      // The middle node itself, the service
-      const expectedQueryNode = {
-        id: 'GetLatestOrder-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        // data: { mode: 'simple', message: expect.anything(), showTarget: false, showSource: false },
-        data: expect.anything(),
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'queries',
-      };
-
-      const expectedProducerNode = {
-        id: 'OrderService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[0].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedConsumerNode = {
-        id: 'PaymentService-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: {
-          title: 'PaymentService',
-          mode: 'simple',
-          service: { ...mockServices[1].data },
-        },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        expect.objectContaining({
-          id: 'OrderService-0.0.1-GetLatestOrder-0.0.1',
-          source: 'OrderService-0.0.1',
-          target: 'GetLatestOrder-0.0.1',
-          label: 'requests',
-        }),
-        expect.objectContaining({
-          id: 'GetLatestOrder-0.0.1-PaymentService-0.0.1',
-          source: 'GetLatestOrder-0.0.1',
-          target: 'PaymentService-0.0.1',
-          label: 'accepts',
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedConsumerNode),
-
-          // The event node itself
-          expect.objectContaining(expectedQueryNode),
-
-          // Nodes on the right
-          expect.objectContaining(expectedProducerNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('if the query is produced and consumed by a service it will render a custom edge', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'GetOrderLegacy', version: '0.0.1' });
-
-      // The middle node itself, the service
-      const expectedQueryNode = {
-        id: 'GetOrderLegacy-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', message: expect.anything() },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'queries',
-      };
-
-      const expectedProducerNode = {
-        id: 'LegacyOrderService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[4].data }, title: 'LegacyOrderService' },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedConsumerNode = {
-        id: 'LegacyOrderService-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: {
-          title: 'LegacyOrderService',
-          mode: 'simple',
-          service: { ...mockServices[4].data },
-        },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        expect.objectContaining({
-          id: 'LegacyOrderService-0.0.1-GetOrderLegacy-0.0.1',
-          source: 'LegacyOrderService-0.0.1',
-          target: 'GetOrderLegacy-0.0.1',
-          label: 'requests',
-        }),
-        expect.objectContaining({
-          id: 'GetOrderLegacy-0.0.1-LegacyOrderService-0.0.1',
-          source: 'GetOrderLegacy-0.0.1',
-          target: 'LegacyOrderService-0.0.1',
-          label: 'accepts',
-        }),
-        expect.objectContaining({
-          id: 'GetOrderLegacy-0.0.1-LegacyOrderService-0.0.1-both',
-          source: 'GetOrderLegacy-0.0.1',
-          target: 'LegacyOrderService-0.0.1',
-          label: 'publishes and subscribes',
-          animated: false,
-          markerEnd: {
-            type: MarkerType.ArrowClosed,
-            width: 40,
-            height: 40,
-          },
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedConsumerNode),
-
-          // The query node itself
-          expect.objectContaining(expectedQueryNode),
-
-          // Nodes on the right
-          expect.objectContaining(expectedProducerNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('if the consumer of a query has defined a channel, it will render the channel node and edges', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'GetProductStatus', version: '0.0.1' });
-
-      const expectedConsumerNode = {
-        id: 'OrderService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[0].data }, title: 'OrderService' },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedChannelNode = {
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        id: 'EmailChannel-1.0.0',
-        type: 'channels',
-      };
-
-      const expectedQueryNode = {
-        id: 'GetProductStatus-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        type: 'queries',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        // Message to the channel
-        expect.objectContaining({
-          id: 'GetProductStatus-0.0.1-EmailChannel-1.0.0',
-          source: 'GetProductStatus-0.0.1',
-          target: 'EmailChannel-1.0.0',
-        }),
-        // Channel to the consumer
-        expect.objectContaining({
-          id: 'EmailChannel-1.0.0-OrderService-0.0.1',
-          source: 'EmailChannel-1.0.0',
-          target: 'OrderService-0.0.1',
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedConsumerNode),
-
-          // channel
-          expect.objectContaining(expectedChannelNode),
-
-          // The query node itself
-          expect.objectContaining(expectedQueryNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('if the producer of a query has defined a channel, it will render the channel node and edges', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'GetProductStatus', version: '0.0.1' });
-
-      const expectedProducerNode = {
-        id: 'InventoryService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedChannelNode = {
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        id: 'EmailChannel-1.0.0',
-        type: 'channels',
-      };
-
-      const expectedQueryNode = {
-        id: 'GetProductStatus-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        type: 'queries',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        // Producer to the message
-        expect.objectContaining({
-          id: 'InventoryService-0.0.1-GetProductStatus-0.0.1',
-          source: 'InventoryService-0.0.1',
-          target: 'GetProductStatus-0.0.1',
-          label: 'requests',
-          animated: false,
-        }),
-        // Message to the channel
-        expect.objectContaining({
-          id: 'GetProductStatus-0.0.1-EmailChannel-1.0.0',
-          source: 'GetProductStatus-0.0.1',
-          target: 'EmailChannel-1.0.0',
-          label: 'routes to',
-          animated: false,
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedProducerNode),
-
-          // channel
-          expect.objectContaining(expectedChannelNode),
-
-          // The query node itself
-          expect.objectContaining(expectedQueryNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('returns empty nodes and edges if no query is found', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownQuery', version: '1.0.0' });
-
-      expect(nodes).toEqual([]);
-      expect(edges).toEqual([]);
-    });
-
-    it('should return nodes and edges for a given query using semver range', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'GetInventoryItem', version: '1.5.1' });
-
-      // The middle node itself, the service
-      const expectedQueryNode = {
-        id: 'GetInventoryItem-1.5.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: expect.anything(),
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'queries',
-      };
-
-      const expectedProducerNode = {
-        id: 'InventoryService-0.0.1',
-        type: 'services',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[2].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedConsumerNode = {
-        id: 'CatalogService-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { title: 'CatalogService', mode: 'simple', service: { ...mockServices[3].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        expect.objectContaining({
-          id: 'InventoryService-0.0.1-GetInventoryItem-1.5.1',
-          source: 'InventoryService-0.0.1',
-          target: 'GetInventoryItem-1.5.1',
-          label: 'requests',
-        }),
-        expect.objectContaining({
-          id: 'GetInventoryItem-1.5.1-CatalogService-0.0.1',
-          source: 'GetInventoryItem-1.5.1',
-          target: 'CatalogService-0.0.1',
-          label: 'accepts',
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedProducerNode),
-
-          // The event node itself
-          expect.objectContaining(expectedQueryNode),
-
-          // Nodes on the right
-          expect.objectContaining(expectedConsumerNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-  });
-});
diff --git a/eventcatalog/src/utils/__tests__/schemas/schemas.spec.ts b/eventcatalog/src/utils/__tests__/schemas/schemas.spec.ts
deleted file mode 100644
index 22580bbac..000000000
--- a/eventcatalog/src/utils/__tests__/schemas/schemas.spec.ts
+++ /dev/null
@@ -1,148 +0,0 @@
-import { getSchemasFromResource } from '@utils/collections/schemas';
-
-import { getSchemaURL, getSchemaFormatFromURL } from '@utils/collections/schemas';
-
-describe('schemas', () => {
-  const originalEnv = process.env;
-
-  beforeEach(() => {
-    // Reset the environment before each test
-    // @ts-ignore
-    global.__EC_TRAILING_SLASH__ = false;
-    process.env = { ...originalEnv };
-  });
-
-  describe('getSchemaURL', () => {
-    it('returns the schema URL for a given resource', () => {
-      const schemaURL = getSchemaURL({
-        collection: 'services',
-        data: {
-          id: 'MyService',
-          version: '1.0.0',
-          name: 'MyService',
-          schemaPath: 'schemas/service',
-        },
-        // @ts-ignore
-        catalog: {
-          publicPath: '/catalog/services/MyService',
-        },
-      });
-      expect(schemaURL).toEqual('/catalog/services/MyService/schemas/service');
-    });
-  });
-
-  describe('getSchemaFormatFromURL', () => {
-    it('returns the format of a given schema URL', () => {
-      const format = getSchemaFormatFromURL('random-url.com/schemas/service.json');
-      expect(format).toEqual('json');
-    });
-  });
-
-  describe('getSchemasFromResource', () => {
-    describe('services', () => {
-      it('returns an openapi, and asyncapi schema if both are present', () => {
-        const schemas = getSchemasFromResource({
-          collection: 'services',
-          data: {
-            id: 'MyService',
-            version: '1.0.0',
-            name: 'MyService',
-            schemaPath: 'schemas/service',
-            specifications: {
-              asyncapiPath: 'schemas/service.asyncapi.json',
-              openapiPath: 'schemas/service.openapi.json',
-            },
-          },
-          // @ts-ignore
-          catalog: { publicPath: '/catalog/services/MyService' },
-        });
-        expect(schemas).toEqual([
-          { url: '/catalog/services/MyService/schemas/service.asyncapi.json', format: 'asyncapi' },
-          { url: '/catalog/services/MyService/schemas/service.openapi.json', format: 'openapi' },
-        ]);
-      });
-
-      it('returns an asyncapi schema if only asyncapi is present', () => {
-        const schemas = getSchemasFromResource({
-          collection: 'services',
-          data: {
-            id: 'MyService',
-            version: '1.0.0',
-            name: 'MyService',
-            schemaPath: 'schemas/service',
-            specifications: {
-              asyncapiPath: 'schemas/service.asyncapi.json',
-            },
-          },
-          // @ts-ignore
-          catalog: { publicPath: '/catalog/services/MyService' },
-        });
-        expect(schemas).toEqual([{ url: '/catalog/services/MyService/schemas/service.asyncapi.json', format: 'asyncapi' }]);
-      });
-
-      it('returns an openapi schema if only openapi is present', () => {
-        const schemas = getSchemasFromResource({
-          collection: 'services',
-          data: {
-            id: 'MyService',
-            version: '1.0.0',
-            name: 'MyService',
-            schemaPath: 'schemas/service',
-            specifications: {
-              openapiPath: 'schemas/service.openapi.json',
-            },
-          },
-          // @ts-ignore
-          catalog: { publicPath: '/catalog/services/MyService' },
-        });
-        expect(schemas).toEqual([{ url: '/catalog/services/MyService/schemas/service.openapi.json', format: 'openapi' }]);
-      });
-
-      it('returns an empty array if no schemas are present', () => {
-        const schemas = getSchemasFromResource({
-          collection: 'services',
-          data: {
-            id: 'MyService',
-            version: '1.0.0',
-            name: 'MyService',
-            schemaPath: 'schemas/service',
-          },
-          // @ts-ignore
-          catalog: { publicPath: '/catalog/services/MyService' },
-        });
-        expect(schemas).toEqual([]);
-      });
-    });
-
-    describe('all resources (excluding services)', () => {
-      it('returns a single schema if only one is present', () => {
-        const schemas = getSchemasFromResource({
-          collection: 'events',
-          data: {
-            id: 'MyEvent',
-            version: '1.0.0',
-            name: 'MyEvent',
-            schemaPath: 'schemas/event.json',
-          },
-          // @ts-ignore
-          catalog: { publicPath: '/catalog/events/MyEvent' },
-        });
-        expect(schemas).toEqual([{ url: '/catalog/events/MyEvent/schemas/event.json', format: 'json' }]);
-      });
-
-      it('returns an empty array if no schemas are present', () => {
-        const schemas = getSchemasFromResource({
-          collection: 'events',
-          data: {
-            id: 'MyEvent',
-            version: '1.0.0',
-            name: 'MyEvent',
-          },
-          // @ts-ignore
-          catalog: { publicPath: '/catalog/events/MyEvent' },
-        });
-        expect(schemas).toEqual([]);
-      });
-    });
-  });
-});
diff --git a/eventcatalog/src/utils/__tests__/services/mocks.ts b/eventcatalog/src/utils/__tests__/services/mocks.ts
deleted file mode 100644
index 2a24ae5b3..000000000
--- a/eventcatalog/src/utils/__tests__/services/mocks.ts
+++ /dev/null
@@ -1,325 +0,0 @@
-export const mockServices = [
-  {
-    id: 'services/Order/OrderService/index.mdx',
-    slug: 'services/Order/OrderService',
-    collection: 'services',
-    data: {
-      id: 'OrderService',
-      version: '1.0.0',
-      specifications: [
-        {
-          type: 'asyncapi',
-          path: 'asyncapi.yml',
-          name: 'AsyncAPI Custom Name',
-        },
-        {
-          type: 'openapi',
-          path: 'openapi.yml',
-          name: 'OpenAPI Custom Name',
-        },
-      ],
-      sends: [
-        {
-          id: 'OrderCreatedEvent',
-          version: '0.0.1',
-        },
-      ],
-      receives: [
-        {
-          id: 'PaymentProcessed',
-          version: '0.0.1',
-        },
-      ],
-      writesTo: [
-        {
-          id: 'OrderDatabase',
-          version: '1.0.0',
-        },
-      ],
-      readsFrom: [
-        {
-          id: 'PaymentDatabase',
-          version: '1.0.0',
-        },
-      ],
-    },
-  },
-  {
-    id: 'services/Inventory/InventoryService/index.mdx',
-    slug: 'services/Inventory/InventoryService',
-    collection: 'services',
-    data: {
-      id: 'InventoryService',
-      version: '1.0.0',
-      specifications: {
-        asyncapiPath: 'asyncapi.yml',
-        openapiPath: 'openapi.yml',
-      },
-      receives: [
-        {
-          id: 'OrderCreatedEvent',
-          version: '^1.3.0',
-        },
-      ],
-      sends: [
-        {
-          id: 'InventoryAdjusted',
-          version: '~2',
-        },
-      ],
-    },
-  },
-  {
-    id: 'services/Payment/PaymentService/index.mdx',
-    slug: 'services/Payment/PaymentService',
-    collection: 'services',
-    data: {
-      id: 'PaymentService',
-      version: '1.0.0',
-      receives: [
-        {
-          id: 'OrderCreatedEvent',
-        },
-        {
-          id: 'OrderDeletedEvent',
-          from: [
-            {
-              id: 'EmailChannel',
-              version: '1.0.0',
-            },
-          ],
-        },
-      ],
-      sends: [
-        {
-          id: 'PaymentPaid',
-          to: [
-            {
-              id: 'EmailChannel',
-              version: '1.0.0',
-            },
-          ],
-        },
-        {
-          id: 'PaymentFailed',
-          version: 'latest',
-        },
-        {
-          id: 'EmailVerified',
-          version: '1.0.0',
-        },
-      ],
-    },
-  },
-  {
-    id: 'services/Notifications/NotificationsService/index.mdx',
-    slug: 'services/Notifications/NotificationsService',
-    collection: 'services',
-    data: {
-      id: 'NotificationsService',
-      version: '1.0.0',
-      receives: [
-        {
-          id: 'OrderCreatedEvent',
-        },
-      ],
-      sends: [
-        {
-          id: 'OrderCreatedEvent',
-        },
-      ],
-    },
-  },
-];
-
-export const mockEvents = [
-  {
-    slug: 'OrderCreatedEvent',
-    collection: 'events',
-    data: {
-      id: 'OrderCreatedEvent',
-      version: '0.0.1',
-    },
-  },
-  {
-    slug: 'OrderCreatedEvent',
-    collection: 'events',
-    data: {
-      id: 'OrderCreatedEvent',
-      version: '1.0.0',
-    },
-  },
-  {
-    slug: 'OrderCreatedEvent',
-    collection: 'events',
-    data: {
-      id: 'OrderCreatedEvent',
-      version: '1.3.9',
-    },
-  },
-  {
-    slug: 'OrderCreatedEvent',
-    collection: 'events',
-    data: {
-      id: 'OrderCreatedEvent',
-      version: '2.0.0',
-    },
-  },
-  {
-    slug: 'OrderDeletedEvent',
-    collection: 'events',
-    data: {
-      id: 'OrderDeletedEvent',
-      version: '2.0.0',
-      channels: [
-        {
-          id: 'OrderChannel',
-          version: '1.0.0',
-        },
-      ],
-    },
-  },
-  {
-    slug: 'InventoryAdjusted',
-    collection: 'events',
-    data: {
-      id: 'InventoryAdjusted',
-      version: '0.0.1',
-    },
-  },
-  {
-    slug: 'InventoryAdjusted',
-    collection: 'events',
-    data: {
-      id: 'InventoryAdjusted',
-      version: '1.0.0',
-    },
-  },
-  {
-    slug: 'InventoryAdjusted',
-    collection: 'events',
-    data: {
-      id: 'InventoryAdjusted',
-      version: '2.0.0',
-    },
-  },
-  // 7
-  {
-    slug: 'PaymentPaid',
-    collection: 'events',
-    data: {
-      id: 'PaymentPaid',
-      version: '1.0.0',
-    },
-  },
-  // 9
-  {
-    slug: 'PaymentPaid',
-    collection: 'events',
-    data: {
-      id: 'PaymentPaid',
-      version: '2.0.0',
-    },
-  },
-  // 10
-  {
-    slug: 'PaymentFailed',
-    collection: 'events',
-    data: {
-      id: 'PaymentFailed',
-      version: '1.0.0',
-    },
-  },
-  // 11
-  {
-    slug: 'PaymentFailed',
-    collection: 'events',
-    data: {
-      id: 'PaymentFailed',
-      version: '1.2.3',
-    },
-  },
-  // 12
-  {
-    id: 'EmailVerified',
-    slug: 'EmailVerified',
-    collection: 'events',
-    data: {
-      id: 'EmailVerified',
-      version: '1.0.0',
-      channels: [
-        {
-          id: 'EmailChannel',
-          version: '1.0.0',
-        },
-      ],
-    },
-  },
-];
-
-export const mockCommands = [
-  {
-    slug: 'PaymentProcessed',
-    collection: 'commands',
-    data: {
-      id: 'PaymentProcessed',
-      version: '0.0.1',
-    },
-  },
-];
-export const mockQueries = [
-  {
-    slug: 'GetOrder',
-    collection: 'queries',
-    data: {
-      id: 'GetOrder',
-      version: '0.0.1',
-    },
-  },
-];
-
-export const mockContainers = [
-  {
-    id: 'OrderDatabase',
-    collection: 'containers',
-    data: {
-      id: 'OrderDatabase',
-      version: '1.0.0',
-    },
-  },
-  {
-    id: 'PaymentDatabase',
-    collection: 'containers',
-    data: {
-      id: 'PaymentDatabase',
-      version: '1.0.0',
-    },
-  },
-];
-
-export const mockChannels = [
-  {
-    id: 'EmailChannel',
-    slug: 'EmailChannel',
-    collection: 'channels',
-    data: {
-      id: 'EmailChannel',
-      version: '1.0.0',
-      messages: [
-        {
-          id: 'OrderCreatedEvent',
-          version: '0.0.1',
-        },
-      ],
-    },
-  },
-  {
-    id: 'OrderChannel',
-    slug: 'OrderChannel',
-    collection: 'channels',
-    data: {
-      id: 'OrderChannel',
-      version: '1.0.0',
-    },
-  },
-];
diff --git a/eventcatalog/src/utils/__tests__/services/node-graph.spec.ts b/eventcatalog/src/utils/__tests__/services/node-graph.spec.ts
deleted file mode 100644
index 4a28aa44f..000000000
--- a/eventcatalog/src/utils/__tests__/services/node-graph.spec.ts
+++ /dev/null
@@ -1,404 +0,0 @@
-import { MarkerType } from '@xyflow/react';
-import { getNodesAndEdges } from '../../node-graphs/services-node-graph';
-import { expect, describe, it, vi, beforeEach } from 'vitest';
-import { mockCommands, mockEvents, mockQueries, mockServices, mockChannels, mockContainers } from './mocks';
-import type { ContentCollectionKey } from 'astro:content';
-
-vi.mock('astro:content', async (importOriginal) => {
-  return {
-    ...(await importOriginal<typeof import('astro:content')>()),
-    // this will only affect "foo" outside of the original module
-    getCollection: (key: ContentCollectionKey) => {
-      switch (key) {
-        case 'services':
-          return Promise.resolve(mockServices);
-        case 'channels':
-          return Promise.resolve(mockChannels);
-        case 'events':
-          return Promise.resolve(mockEvents);
-        case 'commands':
-          return Promise.resolve(mockCommands);
-        case 'queries':
-          return Promise.resolve(mockQueries);
-        case 'containers':
-          return Promise.resolve(mockContainers);
-      }
-    },
-  };
-});
-
-describe('Services NodeGraph', () => {
-  beforeEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  describe('getNodesAndEdges', () => {
-    it('should return nodes and edges for a given service', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'OrderService', version: '1.0.0' });
-
-      // The middle node itself, the service
-      const expectedServiceNode = {
-        id: 'OrderService-1.0.0',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[0].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      // Nodes coming into the service (left)
-      const expectedRecivesNode = {
-        id: 'PaymentProcessed-0.0.1',
-        type: 'commands',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', message: { ...mockCommands[0].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      // Nodes going out of the service (right)
-      const expectedSendsNode = {
-        id: 'OrderCreatedEvent-0.0.1',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', message: { ...mockEvents[0].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'events',
-      };
-
-      const expectedOrderDatabaseNode = {
-        id: 'OrderDatabase-1.0.0',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', data: { ...mockContainers[0].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'data',
-      };
-
-      const expectedPaymentDatabaseNode = {
-        id: 'PaymentDatabase-1.0.0',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', data: { ...mockContainers[1].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'data',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        expect.objectContaining({
-          label: 'accepts',
-          animated: false,
-          id: 'PaymentProcessed-0.0.1-OrderService-1.0.0-warning',
-          source: 'PaymentProcessed-0.0.1',
-          target: 'OrderService-1.0.0',
-        }),
-        expect.objectContaining({
-          id: 'OrderService-1.0.0-OrderDatabase-1.0.0',
-          source: 'OrderService-1.0.0',
-          target: 'OrderDatabase-1.0.0',
-          type: 'multiline',
-        }),
-        expect.objectContaining({
-          label: 'reads from \n (undefined)',
-          id: 'OrderService-1.0.0-PaymentDatabase-1.0.0',
-          source: 'PaymentDatabase-1.0.0',
-          target: 'OrderService-1.0.0',
-          type: 'multiline',
-        }),
-        expect.objectContaining({
-          label: 'publishes \nevent',
-          animated: false,
-          id: 'OrderService-1.0.0-OrderCreatedEvent-0.0.1',
-          source: 'OrderService-1.0.0',
-          target: 'OrderCreatedEvent-0.0.1',
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedRecivesNode),
-
-          // The data node
-          expect.objectContaining(expectedOrderDatabaseNode),
-          expect.objectContaining(expectedPaymentDatabaseNode),
-
-          // The service node itself
-          expect.objectContaining(expectedServiceNode),
-
-          // Nodes on the right
-          expect.objectContaining(expectedSendsNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('if a message is sent and received by the same service it will render a custom edge', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'NotificationsService', version: '1.0.0' });
-
-      // The middle node itself, the service
-      const expectedServiceNode = {
-        id: 'NotificationsService-1.0.0',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[3].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      // Nodes coming into the service (left)
-      const expectedRecivesNode = {
-        id: 'OrderCreatedEvent-2.0.0',
-        type: 'events',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', message: { ...mockEvents[3].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      // Nodes going out of the service (right)
-      const expectedSendsNode = {
-        id: 'OrderCreatedEvent-2.0.0',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', message: { ...mockEvents[3].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'events',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        expect.objectContaining({
-          id: 'OrderCreatedEvent-2.0.0-NotificationsService-1.0.0',
-          source: 'OrderCreatedEvent-2.0.0',
-          target: 'NotificationsService-1.0.0',
-        }),
-        expect.objectContaining({
-          id: 'NotificationsService-1.0.0-OrderCreatedEvent-2.0.0',
-          source: 'NotificationsService-1.0.0',
-          target: 'OrderCreatedEvent-2.0.0',
-        }),
-        expect.objectContaining({
-          id: 'NotificationsService-1.0.0-OrderCreatedEvent-2.0.0-both',
-          source: 'NotificationsService-1.0.0',
-          target: 'OrderCreatedEvent-2.0.0',
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedRecivesNode),
-
-          // The service node itself
-          expect.objectContaining(expectedServiceNode),
-
-          // Nodes on the right
-          expect.objectContaining(expectedSendsNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('returns empty nodes and edges if no service is found', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownService', version: '1.0.0' });
-
-      expect(nodes).toEqual([]);
-      expect(edges).toEqual([]);
-    });
-
-    it('should return nodes and edges for a given service using semver range', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'InventoryService', version: '1.0.0' });
-
-      // The middle node itself, the service
-      const expectedServiceNode = {
-        id: 'InventoryService-1.0.0',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[1].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      // Nodes coming into the service (left)
-      const expectedRecivesNode = {
-        id: 'OrderCreatedEvent-1.3.9',
-        type: 'events',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', message: { ...mockEvents[2].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      // Nodes going out of the service (right)
-      const expectedSendsNode = {
-        id: 'InventoryAdjusted-2.0.0',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', message: { ...mockEvents[7].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'events',
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        expect.objectContaining({
-          id: 'OrderCreatedEvent-1.3.9-InventoryService-1.0.0',
-          source: 'OrderCreatedEvent-1.3.9',
-          target: 'InventoryService-1.0.0',
-        }),
-        expect.objectContaining({
-          id: 'InventoryService-1.0.0-InventoryAdjusted-2.0.0',
-          source: 'InventoryService-1.0.0',
-          target: 'InventoryAdjusted-2.0.0',
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // Nodes on the left
-          expect.objectContaining(expectedRecivesNode),
-
-          // The service node itself
-          expect.objectContaining(expectedServiceNode),
-
-          // Nodes on the right
-          expect.objectContaining(expectedSendsNode),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('creates a channel node between the service and message if the service defined a channel', async () => {
-      const { nodes, edges } = await getNodesAndEdges({ id: 'PaymentService', version: '1.0.0' });
-
-      // The middle node itself, the service
-      const expectedServiceNode = {
-        id: 'PaymentService-1.0.0',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', service: { ...mockServices[2].data } },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-        type: 'services',
-      };
-
-      const expectedConsumedMessageWithoutChannel = {
-        id: 'OrderCreatedEvent-2.0.0',
-        type: 'events',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', message: expect.anything() },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedConsumedMessageWithChannel = {
-        id: 'OrderDeletedEvent-2.0.0',
-        type: 'events',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', message: expect.anything() },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedChannelNode = {
-        id: 'EmailChannel-1.0.0',
-        type: 'channels',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', channel: expect.anything() },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      // Message coming into the service with a channel
-      const expectedProducedMessage = {
-        id: 'PaymentPaid-2.0.0',
-        type: 'events',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', message: expect.anything() },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      // Message coming into the service with a channel
-      const expectedChannelAfterProducedMessage = {
-        id: 'EmailChannel-1.0.0',
-        type: 'channels',
-        sourcePosition: 'right',
-        targetPosition: 'left',
-        data: { mode: 'simple', channel: expect.anything() },
-        position: { x: expect.any(Number), y: expect.any(Number) },
-      };
-
-      const expectedEdges = expect.arrayContaining([
-        // The service to the message (it publishes)
-        expect.objectContaining({
-          id: 'PaymentService-1.0.0-PaymentPaid-2.0.0',
-          source: 'PaymentService-1.0.0',
-          target: 'PaymentPaid-2.0.0',
-        }),
-        // The Message to the channel defined by the producing service
-        expect.objectContaining({
-          id: 'PaymentPaid-2.0.0-EmailChannel-1.0.0',
-          source: 'PaymentPaid-2.0.0',
-          target: 'EmailChannel-1.0.0',
-        }),
-
-        // The consumed message with no channel defined
-        // We expect to to connect to the service
-        expect.objectContaining({
-          id: 'OrderCreatedEvent-2.0.0-PaymentService-1.0.0',
-          source: 'OrderCreatedEvent-2.0.0',
-          target: 'PaymentService-1.0.0',
-        }),
-
-        // The consume message with a channel defined
-        expect.objectContaining({
-          id: 'OrderDeletedEvent-2.0.0-EmailChannel-1.0.0',
-          source: 'OrderDeletedEvent-2.0.0',
-          target: 'EmailChannel-1.0.0',
-        }),
-      ]);
-
-      expect(nodes).toEqual(
-        expect.arrayContaining([
-          // message the service consumes
-          expect.objectContaining(expectedConsumedMessageWithoutChannel),
-
-          // message the service consumes with a channel
-          expect.objectContaining(expectedConsumedMessageWithChannel),
-
-          // The channel node
-          expect.objectContaining(expectedChannelNode),
-
-          // The service node itself
-          expect.objectContaining(expectedServiceNode),
-
-          // message on the right of the service
-          expect.objectContaining(expectedProducedMessage),
-
-          expect.objectContaining(expectedChannelAfterProducedMessage),
-        ])
-      );
-
-      expect(edges).toEqual(expectedEdges);
-    });
-
-    it('when `renderMessages` is false it should not render any messages or channels', async () => {
-      const { nodes } = await getNodesAndEdges({ id: 'PaymentService', version: '1.0.0', renderMessages: false });
-
-      const hasMessages = nodes.some((node) => node.type === 'events' || node.type === 'commands' || node.type === 'queries');
-      const hasChannels = nodes.some((node) => node.type === 'channels');
-
-      expect(hasMessages).toBe(false);
-      expect(hasChannels).toBe(false);
-    });
-
-    it('will render any container (data) that the service writes to or reads from', async () => {
-      const { nodes } = await getNodesAndEdges({ id: 'OrderService', version: '1.0.0' });
-
-      const hasContainers = nodes.some((node) => node.type === 'data');
-      expect(hasContainers).toBe(true);
-    });
-  });
-});
diff --git a/eventcatalog/src/utils/channels.ts b/eventcatalog/src/utils/channels.ts
deleted file mode 100644
index 04e9de0d2..000000000
--- a/eventcatalog/src/utils/channels.ts
+++ /dev/null
@@ -1,166 +0,0 @@
-import { getCollection } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import path from 'path';
-import { getItemsFromCollectionByIdAndSemverOrLatest, getVersionForCollectionItem, satisfies } from './collections/util';
-import { getMessages } from './messages';
-import type { CollectionMessageTypes } from '@types';
-import utils from '@eventcatalog/sdk';
-
-const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd();
-
-type Channel = CollectionEntry<'channels'> & {
-  catalog: {
-    path: string;
-    filePath: string;
-    type: string;
-  };
-};
-
-interface Props {
-  getAllVersions?: boolean;
-}
-
-// cache for build time
-let cachedChannels: Record<string, Channel[]> = {
-  allVersions: [],
-  currentVersions: [],
-};
-
-export const getChannels = async ({ getAllVersions = true }: Props = {}): Promise<Channel[]> => {
-  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
-
-  if (cachedChannels[cacheKey].length > 0) {
-    return cachedChannels[cacheKey];
-  }
-
-  const channels = await getCollection('channels', (query) => {
-    return (getAllVersions || !query.filePath?.includes('versioned')) && query.data.hidden !== true;
-  });
-
-  const { commands, events, queries } = await getMessages();
-  const allMessages = [...commands, ...events, ...queries];
-
-  cachedChannels[cacheKey] = await Promise.all(
-    channels.map(async (channel) => {
-      const { latestVersion, versions } = getVersionForCollectionItem(channel, channels);
-
-      const messagesForChannel = allMessages.filter((message) => {
-        return message.data.channels?.some((messageChannel) => {
-          if (messageChannel.id != channel.data.id) return false;
-          if (messageChannel.version == 'latest' || messageChannel.version == undefined)
-            return channel.data.version == latestVersion;
-          return satisfies(channel.data.version, messageChannel.version);
-        });
-      });
-
-      const messages = messagesForChannel.map((message: CollectionEntry<CollectionMessageTypes>) => {
-        return { id: message.data.id, name: message.data.name, version: message.data.version, collection: message.collection };
-      });
-
-      const { getResourceFolderName } = utils(process.env.PROJECT_DIR ?? '');
-      const folderName = await getResourceFolderName(
-        process.env.PROJECT_DIR ?? '',
-        channel.data.id,
-        channel.data.version.toString()
-      );
-      const channelFolderName = folderName ?? channel.id.replace(`-${channel.data.version}`, '');
-
-      return {
-        ...channel,
-        data: {
-          ...channel.data,
-          versions,
-          latestVersion,
-          messages,
-        },
-        catalog: {
-          path: path.join(channel.collection, channel.id.replace('/index.mdx', '')),
-          absoluteFilePath: path.join(PROJECT_DIR, channel.collection, channel.id.replace('/index.mdx', '/index.md')),
-          astroContentFilePath: path.join(process.cwd(), 'src', 'content', channel.collection, channel.id),
-          filePath: path.join(process.cwd(), 'src', 'catalog-files', channel.collection, channel.id.replace('/index.mdx', '')),
-          publicPath: path.join('/generated', channel.collection, channelFolderName),
-          type: 'event',
-        },
-      };
-    })
-  );
-
-  // order them by the name of the channel
-  cachedChannels[cacheKey].sort((a, b) => {
-    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
-  });
-
-  return cachedChannels[cacheKey];
-};
-
-// Could be recursive, we need to keep going until we find a loop or until we reach the target channel
-export const isChannelsConnected = (
-  sourceChannel: CollectionEntry<'channels'>,
-  targetChannel: CollectionEntry<'channels'>,
-  channels: CollectionEntry<'channels'>[],
-  visited: Set<string> = new Set()
-) => {
-  // Create a unique key for this channel (id + version to handle multiple versions)
-  const channelKey = `${sourceChannel.data.id}:${sourceChannel.data.version}`;
-
-  // Base case: we've reached the target channel
-  if (sourceChannel.data.id === targetChannel.data.id) {
-    return true;
-  }
-
-  // Prevent infinite loops by tracking visited channels
-  if (visited.has(channelKey)) {
-    return false;
-  }
-
-  // Mark this channel as visited
-  visited.add(channelKey);
-
-  const routes = sourceChannel.data.routes ?? [];
-  for (const route of routes) {
-    const routeChannel = getItemsFromCollectionByIdAndSemverOrLatest(
-      channels,
-      route.id,
-      route.version
-    )[0] as CollectionEntry<'channels'>;
-
-    if (routeChannel) {
-      // Pass the visited set to the recursive call
-      if (isChannelsConnected(routeChannel, targetChannel, channels, visited)) {
-        return true;
-      }
-    }
-  }
-  return false;
-};
-
-// Go from the source to the target channel and return the channel chain
-export const getChannelChain = (
-  sourceChannel: CollectionEntry<'channels'>,
-  targetChannel: CollectionEntry<'channels'>,
-  channels: CollectionEntry<'channels'>[]
-): CollectionEntry<'channels'>[] => {
-  // Base case: we've reached the target channel
-  if (sourceChannel.data.id === targetChannel.data.id && sourceChannel.data.version === targetChannel.data.version) {
-    return [sourceChannel];
-  }
-
-  const routes = sourceChannel.data.routes ?? [];
-
-  if (routes.length > 0 && isChannelsConnected(sourceChannel, targetChannel, channels)) {
-    // Need to check every route and see if any of them are connected to the target channel
-    for (const route of routes) {
-      const routeChannel = getItemsFromCollectionByIdAndSemverOrLatest(
-        channels,
-        route.id,
-        route.version
-      )[0] as CollectionEntry<'channels'>;
-      if (routeChannel) {
-        if (isChannelsConnected(routeChannel, targetChannel, channels)) {
-          return [sourceChannel, ...getChannelChain(routeChannel, targetChannel, channels)];
-        }
-      }
-    }
-  }
-  return [];
-};
diff --git a/eventcatalog/src/utils/collections/changelogs.ts b/eventcatalog/src/utils/collections/changelogs.ts
deleted file mode 100644
index 84b3a9570..000000000
--- a/eventcatalog/src/utils/collections/changelogs.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import type { CollectionTypes } from '@types';
-import { getCollection, type CollectionEntry } from 'astro:content';
-import path from 'node:path';
-
-export type ChangeLog = CollectionEntry<'changelogs'>;
-
-export const getChangeLogs = async (item: CollectionEntry<CollectionTypes>): Promise<ChangeLog[]> => {
-  const { collection, data, filePath } = item;
-
-  // Get all logs for collection type and filter by given collection
-  const logs = await getCollection('changelogs', (log) => {
-    const collectionDirectory = path.dirname(item?.filePath || '');
-    const isRootChangeLog = path.join(collectionDirectory, 'changelog.mdx') === log.filePath;
-    // Ensure the path follows <collectionDirectory>/versioned/<version>/changelog.mdx
-    const versionedPathPattern = new RegExp(`${collectionDirectory}/versioned/[^/]+/changelog\\.mdx$`);
-    const isVersionedChangeLog = versionedPathPattern.test(log.filePath!);
-    return log.id.includes(`${collection}/`) && (isRootChangeLog || isVersionedChangeLog);
-  });
-
-  const hydratedLogs = logs.map((log) => {
-    // Check if there is a version in the url
-    const isVersioned = log.id.includes('versioned');
-
-    const parts = log.filePath!.split('/');
-    // hack to get the version of the id (url)
-    const version = parts[parts.length - 2];
-    return {
-      ...log,
-      data: {
-        ...log.data,
-        version: isVersioned ? version : data.latestVersion || 'latest',
-      },
-    };
-  });
-
-  // Order by version string
-  return hydratedLogs.sort((a, b) => {
-    return b.data.version.localeCompare(a.data.version);
-  });
-};
diff --git a/eventcatalog/src/utils/collections/containers.ts b/eventcatalog/src/utils/collections/containers.ts
deleted file mode 100644
index 5956765cc..000000000
--- a/eventcatalog/src/utils/collections/containers.ts
+++ /dev/null
@@ -1,111 +0,0 @@
-import { getCollection } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import path from 'path';
-import { getVersionForCollectionItem, satisfies } from './util';
-import utils from '@eventcatalog/sdk';
-
-const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd();
-
-export type Entity = CollectionEntry<'containers'> & {
-  catalog: {
-    path: string;
-    filePath: string;
-    type: string;
-  };
-};
-
-interface Props {
-  getAllVersions?: boolean;
-}
-
-// cache for build time
-let cachedEntities: Record<string, Entity[]> = {
-  allVersions: [],
-  currentVersions: [],
-};
-
-export const getContainers = async ({ getAllVersions = true }: Props = {}): Promise<Entity[]> => {
-  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
-
-  if (cachedEntities[cacheKey].length > 0) {
-    return cachedEntities[cacheKey];
-  }
-
-  const containers = await getCollection('containers', (container) => {
-    return (getAllVersions || !container.filePath?.includes('versioned')) && container.data.hidden !== true;
-  });
-
-  const services = await getCollection('services');
-
-  cachedEntities[cacheKey] = await Promise.all(
-    containers.map(async (container) => {
-      const { latestVersion, versions } = getVersionForCollectionItem(container, containers);
-
-      const servicesThatReferenceContainer = services.filter((service) => {
-        const references = [...(service.data.writesTo || []), ...(service.data.readsFrom || [])];
-        return references.some((item) => {
-          if (item.id != container.data.id) return false;
-          if (item.version == 'latest' || item.version == undefined) return container.data.version == latestVersion;
-          return satisfies(container.data.version, item.version);
-        });
-      });
-
-      const servicesThatWriteToContainer = services.filter((service) => {
-        return service.data?.writesTo?.some((item) => {
-          if (item.id != container.data.id) return false;
-          if (item.version == 'latest' || item.version == undefined) return container.data.version == latestVersion;
-          return satisfies(container.data.version, item.version);
-        });
-      });
-
-      const servicesThatReadFromContainer = services.filter((service) => {
-        return service.data?.readsFrom?.some((item) => {
-          if (item.id != container.data.id) return false;
-          if (item.version == 'latest' || item.version == undefined) return container.data.version == latestVersion;
-          return satisfies(container.data.version, item.version);
-        });
-      });
-
-      const { getResourceFolderName } = utils(process.env.PROJECT_DIR ?? '');
-      const folderName = await getResourceFolderName(
-        process.env.PROJECT_DIR ?? '',
-        container.data.id,
-        container.data.version.toString()
-      );
-      const containerFolderName = folderName ?? container.id.replace(`-${container.data.version}`, '');
-
-      return {
-        ...container,
-        data: {
-          ...container.data,
-          versions,
-          latestVersion,
-          services: servicesThatReferenceContainer,
-          servicesThatWriteToContainer,
-          servicesThatReadFromContainer,
-        },
-        catalog: {
-          path: path.join(container.collection, container.id.replace('/index.mdx', '')),
-          absoluteFilePath: path.join(PROJECT_DIR, container.collection, container.id.replace('/index.mdx', '/index.md')),
-          astroContentFilePath: path.join(process.cwd(), 'src', 'content', container.collection, container.id),
-          filePath: path.join(
-            process.cwd(),
-            'src',
-            'catalog-files',
-            container.collection,
-            container.id.replace('/index.mdx', '')
-          ),
-          publicPath: path.join('/generated', container.collection, containerFolderName),
-          type: 'container',
-        },
-      };
-    })
-  );
-
-  // order them by the name of the event
-  cachedEntities[cacheKey].sort((a, b) => {
-    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
-  });
-
-  return cachedEntities[cacheKey];
-};
diff --git a/eventcatalog/src/utils/collections/domains.ts b/eventcatalog/src/utils/collections/domains.ts
deleted file mode 100644
index d9fcef801..000000000
--- a/eventcatalog/src/utils/collections/domains.ts
+++ /dev/null
@@ -1,225 +0,0 @@
-import { getItemsFromCollectionByIdAndSemverOrLatest, getVersionForCollectionItem } from '@utils/collections/util';
-import { getCollection } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import path from 'path';
-import type { CollectionMessageTypes } from '@types';
-import type { Service } from './services';
-import utils from '@eventcatalog/sdk';
-
-const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd();
-
-export type Domain = CollectionEntry<'domains'>;
-export type UbiquitousLanguage = CollectionEntry<'ubiquitousLanguages'>;
-interface Props {
-  getAllVersions?: boolean;
-}
-
-// Update cache to store both versions
-let cachedDomains: Record<string, Domain[]> = {
-  allVersions: [],
-  currentVersions: [],
-};
-
-export const getDomains = async ({ getAllVersions = true }: Props = {}): Promise<Domain[]> => {
-  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
-
-  // Check if we have cached domains for this specific getAllVersions value
-  if (cachedDomains[cacheKey].length > 0) {
-    return cachedDomains[cacheKey];
-  }
-
-  // Get all the domains that are not versioned
-  const domains = await getCollection('domains', (domain) => {
-    return (getAllVersions || !domain.filePath?.includes('versioned')) && domain.data.hidden !== true;
-  });
-
-  // Get all the services that are not versioned
-  const servicesCollection = await getCollection('services');
-  const entitiesCollection = await getCollection('entities');
-
-  // @ts-ignore // TODO: Fix this type
-  cachedDomains[cacheKey] = await Promise.all(
-    domains.map(async (domain) => {
-      const { latestVersion, versions } = getVersionForCollectionItem(domain, domains);
-
-      // const receives = service.data.receives || [];
-      const servicesInDomain = domain.data.services || [];
-      const subDomainsInDomain = domain.data.domains || [];
-      const entitiesInDomain = domain.data.entities || [];
-      const subDomains = subDomainsInDomain
-        .map((_subDomain: { id: string; version: string | undefined }) =>
-          getItemsFromCollectionByIdAndSemverOrLatest(domains, _subDomain.id, _subDomain.version)
-        )
-        .flat()
-        // Stop circular references
-        .filter((subDomain) => subDomain.data.id !== domain.data.id);
-
-      // Services in the sub domains
-      const subdomainServices = subDomains.flatMap((subDomain) => subDomain.data.services || []);
-
-      const services = [...servicesInDomain, ...subdomainServices]
-        .map((_service: { id: string; version: string | undefined }) =>
-          getItemsFromCollectionByIdAndSemverOrLatest(servicesCollection, _service.id, _service.version)
-        )
-        .flat();
-
-      const entities = [...entitiesInDomain]
-        .map((_entity: { id: string; version: string | undefined }) =>
-          getItemsFromCollectionByIdAndSemverOrLatest(entitiesCollection, _entity.id, _entity.version)
-        )
-        .flat();
-
-      const { getResourceFolderName } = utils(process.env.PROJECT_DIR ?? '');
-      const folderName = await getResourceFolderName(
-        process.env.PROJECT_DIR ?? '',
-        domain.data.id,
-        domain.data.version.toString()
-      );
-      const domainFolderName = folderName ?? domain.id.replace(`-${domain.data.version}`, '');
-
-      return {
-        ...domain,
-        data: {
-          ...domain.data,
-          services: services,
-          domains: subDomains,
-          entities: entities,
-          latestVersion,
-          versions,
-        },
-        catalog: {
-          path: path.join(domain.collection, domain.id.replace('/index.mdx', '')),
-          absoluteFilePath: path.join(PROJECT_DIR, domain.collection, domain.id.replace('/index.mdx', '/index.md')),
-          astroContentFilePath: path.join(process.cwd(), 'src', 'content', domain.collection, domain.id),
-          filePath: path.join(process.cwd(), 'src', 'catalog-files', domain.collection, domain.id.replace('/index.mdx', '')),
-          publicPath: path.join('/generated', domain.collection, domainFolderName),
-          type: 'service',
-        },
-      };
-    })
-  );
-
-  // order them by the name of the domain
-  cachedDomains[cacheKey].sort((a, b) => {
-    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
-  });
-
-  return cachedDomains[cacheKey];
-};
-
-export const getMessagesForDomain = async (
-  domain: Domain
-): Promise<{ sends: CollectionEntry<CollectionMessageTypes>[]; receives: CollectionEntry<CollectionMessageTypes>[] }> => {
-  // We already have the services from the domain
-  const services = domain.data.services as unknown as CollectionEntry<'services'>[];
-
-  const events = await getCollection('events');
-  const commands = await getCollection('commands');
-  const queries = await getCollection('queries');
-
-  const allMessages = [...events, ...commands, ...queries];
-
-  const sends = services.flatMap((service) => service.data.sends || []);
-  const receives = services.flatMap((service) => service.data.receives || []);
-
-  const sendsMessages = sends.map((send) => getItemsFromCollectionByIdAndSemverOrLatest(allMessages, send.id, send.version));
-  const receivesMessages = receives.map((receive) =>
-    getItemsFromCollectionByIdAndSemverOrLatest(allMessages, receive.id, receive.version)
-  );
-
-  return {
-    sends: sendsMessages.flat(),
-    receives: receivesMessages.flat(),
-  };
-};
-
-export const getUbiquitousLanguage = async (domain: Domain): Promise<UbiquitousLanguage[]> => {
-  const ubiquitousLanguages = await getCollection('ubiquitousLanguages', (ubiquitousLanguage: UbiquitousLanguage) => {
-    const domainFolder = path.dirname(domain.filePath || '');
-    const ubiquitousLanguageFolder = path.dirname(ubiquitousLanguage.filePath || '');
-    return domainFolder === ubiquitousLanguageFolder;
-  });
-
-  return ubiquitousLanguages;
-};
-
-export const getUbiquitousLanguageWithSubdomains = async (
-  domain: Domain
-): Promise<{
-  domain: UbiquitousLanguage | null;
-  subdomains: Array<{ subdomain: Domain; ubiquitousLanguage: UbiquitousLanguage | null }>;
-  duplicateTerms: Set<string>;
-}> => {
-  // Get domain's own ubiquitous language
-  const domainUbiquitousLanguage = await getUbiquitousLanguage(domain);
-  const domainUL = domainUbiquitousLanguage[0] || null;
-
-  // Get all subdomains
-  const subdomains = (domain.data.domains as unknown as Domain[]) || [];
-
-  // Get ubiquitous language for each subdomain
-  const subdomainULs = await Promise.all(
-    subdomains.map(async (subdomain) => {
-      const subdomainUL = await getUbiquitousLanguage(subdomain);
-      return {
-        subdomain,
-        ubiquitousLanguage: subdomainUL[0] || null,
-      };
-    })
-  );
-
-  // Find duplicate terms across domain and subdomains
-  const duplicateTerms = new Set<string>();
-  const termCounts = new Map<string, number>();
-
-  // Count terms from domain
-  if (domainUL?.data?.dictionary) {
-    domainUL.data.dictionary.forEach((term) => {
-      const termName = term.name.toLowerCase();
-      termCounts.set(termName, (termCounts.get(termName) || 0) + 1);
-    });
-  }
-
-  // Count terms from subdomains
-  subdomainULs.forEach(({ ubiquitousLanguage }) => {
-    if (ubiquitousLanguage?.data?.dictionary) {
-      ubiquitousLanguage.data.dictionary.forEach((term) => {
-        const termName = term.name.toLowerCase();
-        termCounts.set(termName, (termCounts.get(termName) || 0) + 1);
-      });
-    }
-  });
-
-  // Identify duplicates
-  termCounts.forEach((count, termName) => {
-    if (count > 1) {
-      duplicateTerms.add(termName);
-    }
-  });
-
-  return {
-    domain: domainUL,
-    subdomains: subdomainULs,
-    duplicateTerms,
-  };
-};
-
-export const getParentDomains = async (domain: Domain): Promise<Domain[]> => {
-  const domains = await getDomains({ getAllVersions: false });
-  return domains.filter((d) => {
-    const subDomains = (d.data.domains as unknown as Domain[]) || [];
-    return subDomains.some((d) => d.data.id === domain.data.id);
-  });
-};
-
-export const getDomainsForService = async (service: Service): Promise<Domain[]> => {
-  const domains = await getDomains({ getAllVersions: false });
-  return domains.filter((d) => {
-    const services = d.data.services as unknown as Service[];
-    return services.some((s) => s.data.id === service.data.id);
-  });
-};
-
-export const domainHasEntities = (domain: Domain): boolean => {
-  return (domain.data.entities && domain.data.entities.length > 0) || false;
-};
diff --git a/eventcatalog/src/utils/collections/flows.ts b/eventcatalog/src/utils/collections/flows.ts
deleted file mode 100644
index d70553c83..000000000
--- a/eventcatalog/src/utils/collections/flows.ts
+++ /dev/null
@@ -1,78 +0,0 @@
-import { getItemsFromCollectionByIdAndSemverOrLatest, getVersionForCollectionItem } from '@utils/collections/util';
-import { getCollection } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import path from 'path';
-
-const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd();
-
-export type Flow = CollectionEntry<'flows'>;
-
-interface Props {
-  getAllVersions?: boolean;
-}
-
-// Cache for build time
-let cachedFlows: Record<string, Flow[]> = {
-  allVersions: [],
-  currentVersions: [],
-};
-
-export const getFlows = async ({ getAllVersions = true }: Props = {}): Promise<Flow[]> => {
-  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
-
-  if (cachedFlows[cacheKey].length > 0) {
-    return cachedFlows[cacheKey];
-  }
-
-  // Get flows that are not versioned
-  const flows = await getCollection('flows', (flow) => {
-    return (getAllVersions || !flow.filePath?.includes('versioned')) && flow.data.hidden !== true;
-  });
-
-  const events = await getCollection('events');
-  const commands = await getCollection('commands');
-
-  const allMessages = [...events, ...commands];
-
-  // @ts-ignore // TODO: Fix this type
-  cachedFlows[cacheKey] = flows.map((flow) => {
-    // @ts-ignore
-    const { latestVersion, versions } = getVersionForCollectionItem(flow, flows);
-    const steps = flow.data.steps || [];
-
-    const hydrateSteps = steps.map((step) => {
-      if (!step.message) return { ...flow, data: { ...flow.data, type: 'node' } };
-      const message = getItemsFromCollectionByIdAndSemverOrLatest(allMessages, step.message.id, step.message.version);
-      return {
-        ...step,
-        type: 'message',
-        message: message,
-      };
-    });
-
-    return {
-      ...flow,
-      data: {
-        ...flow.data,
-        steps: hydrateSteps,
-        versions,
-        latestVersion,
-      },
-      catalog: {
-        path: path.join(flow.collection, flow.id.replace('/index.mdx', '')),
-        absoluteFilePath: path.join(PROJECT_DIR, flow.collection, flow.id.replace('/index.mdx', '/index.md')),
-        astroContentFilePath: path.join(process.cwd(), 'src', 'content', flow.collection, flow.id),
-        filePath: path.join(process.cwd(), 'src', 'catalog-files', flow.collection, flow.id.replace('/index.mdx', '')),
-        publicPath: path.join('/generated', flow.collection),
-        type: 'flow',
-      },
-    };
-  });
-
-  // order them by the name of the flow
-  cachedFlows[cacheKey].sort((a, b) => {
-    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
-  });
-
-  return cachedFlows[cacheKey];
-};
diff --git a/eventcatalog/src/utils/collections/icons.ts b/eventcatalog/src/utils/collections/icons.ts
deleted file mode 100644
index a31e8dbd2..000000000
--- a/eventcatalog/src/utils/collections/icons.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import {
-  ServerIcon,
-  RectangleGroupIcon,
-  BoltIcon,
-  ChatBubbleLeftIcon,
-  MagnifyingGlassIcon,
-  QueueListIcon,
-  UserGroupIcon,
-  UserIcon,
-  ArrowsRightLeftIcon,
-  VariableIcon,
-  MapIcon,
-} from '@heroicons/react/24/outline';
-import { BookText, Box, DatabaseIcon } from 'lucide-react';
-
-export const getIconForCollection = (collection: string) => {
-  switch (collection) {
-    case 'domains':
-      return RectangleGroupIcon;
-    case 'services':
-      return ServerIcon;
-    case 'events':
-      return BoltIcon;
-    case 'commands':
-      return ChatBubbleLeftIcon;
-    case 'queries':
-      return MagnifyingGlassIcon;
-    case 'flows':
-      return QueueListIcon;
-    case 'teams':
-      return UserGroupIcon;
-    case 'users':
-      return UserIcon;
-    case 'channels':
-      return ArrowsRightLeftIcon;
-    case 'channels-parameter':
-      return VariableIcon;
-    case 'ubiquitousLanguages':
-      return BookText;
-    case 'bounded-context-map':
-      return MapIcon;
-    case 'entities':
-      return Box;
-    case 'containers':
-      return DatabaseIcon;
-    default:
-      return ServerIcon;
-  }
-};
-
-export const getColorAndIconForCollection = (collection: string) => {
-  const icon = getIconForCollection(collection);
-
-  switch (collection) {
-    case 'events':
-      return { color: 'orange', Icon: icon };
-    case 'commands':
-      return { color: 'blue', Icon: icon };
-    case 'queries':
-      return { color: 'green', Icon: icon };
-    case 'flows':
-      return { color: 'teal', Icon: icon };
-    case 'teams':
-      return { color: 'red', Icon: icon };
-    case 'users':
-      return { color: 'gray', Icon: icon };
-    case 'channels':
-      return { color: 'purple', Icon: icon };
-    case 'ubiquitousLanguages':
-      return { color: 'green', Icon: icon };
-    case 'entities':
-      return { color: 'purple', Icon: icon };
-    case 'domains':
-      return { color: 'yellow', Icon: icon };
-    case 'services':
-      return { color: 'pink', Icon: icon };
-    default:
-      return { color: 'gray', Icon: icon };
-  }
-};
diff --git a/eventcatalog/src/utils/collections/owners.ts b/eventcatalog/src/utils/collections/owners.ts
deleted file mode 100644
index 7b88f8ff0..000000000
--- a/eventcatalog/src/utils/collections/owners.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import { getCollection, type CollectionEntry } from 'astro:content';
-
-const getOwners = (function () {
-  type Owners = CollectionEntry<'users' | 'teams'>;
-  let cachedOwners: Map<string, Owners> | null = null;
-  let initializingPromise: Promise<Map<string, Owners>> | null = null;
-
-  /**
-   * Initializes and caches the owners by fetching from the 'users' and 'teams' collections.
-   */
-  async function init() {
-    const ownersMap = new Map<string, CollectionEntry<'users' | 'teams'>>();
-
-    const owners = await Promise.all([
-      getCollection('users', (entry) => entry.data.hidden !== true),
-      getCollection('teams', (entry) => entry.data.hidden !== true),
-    ]);
-
-    for (const owner of owners.flat()) {
-      ownersMap.set(owner.data.id, owner);
-    }
-
-    cachedOwners = ownersMap;
-    initializingPromise = null;
-
-    return cachedOwners;
-  }
-
-  return () =>
-    cachedOwners || // Return cached owners if already initialized
-    initializingPromise || // Return the promise if initialization is in progress
-    (initializingPromise = init()); // Initialize if neither cache nor promise exists
-})();
-
-export async function getOwner(lookup: { id: string }): Promise<CollectionEntry<'users' | 'teams'> | undefined> {
-  const lookupId = typeof lookup === 'string' ? lookup : lookup.id;
-
-  const owner = (await getOwners()).get(lookupId);
-
-  if (!owner) console.warn(`Entry ${lookupId} not found in "teams"/"users" collections.`);
-
-  return owner;
-}
diff --git a/eventcatalog/src/utils/collections/schemas.ts b/eventcatalog/src/utils/collections/schemas.ts
deleted file mode 100644
index d20c64cd7..000000000
--- a/eventcatalog/src/utils/collections/schemas.ts
+++ /dev/null
@@ -1,65 +0,0 @@
-import type { CollectionEntry } from 'astro:content';
-import type { PageTypes } from '@types';
-import path from 'path';
-import { buildUrl } from '@utils/url-builder';
-
-export type Schema = {
-  url: string;
-  format: string;
-};
-
-export const getSchemaURL = (resource: CollectionEntry<PageTypes>) => {
-  // @ts-ignore
-  const publicPath = resource?.catalog?.publicPath;
-  const schemaFilePath = resource?.data?.schemaPath;
-
-  if (!publicPath || !schemaFilePath) {
-    return;
-  }
-
-  // new URL
-  return path.join(publicPath, schemaFilePath);
-};
-
-export const getSchemaFormatFromURL = (url: string) => {
-  const pathParts = url.split('.');
-  const format = pathParts[pathParts.length - 1];
-  return format;
-};
-
-export const getSchemasFromResource = (resource: CollectionEntry<PageTypes>): Schema[] => {
-  const schemaPublicPath = getSchemaURL(resource);
-
-  if (!schemaPublicPath) {
-    return [];
-  }
-
-  if (resource.collection === 'services') {
-    const specifications = resource?.data?.specifications;
-    const asyncapiPath = Array.isArray(specifications)
-      ? specifications.find((spec) => spec.type === 'asyncapi')?.path
-      : specifications?.asyncapiPath;
-    const openapiPath = Array.isArray(specifications)
-      ? specifications.find((spec) => spec.type === 'openapi')?.path
-      : specifications?.openapiPath;
-    // @ts-ignore
-    const publicPath = resource?.catalog?.publicPath;
-    const schemas = [];
-
-    if (asyncapiPath) {
-      const asyncapiUrl = path.join(publicPath, asyncapiPath);
-      schemas.push({ url: buildUrl(asyncapiUrl), format: 'asyncapi' });
-    }
-
-    if (openapiPath) {
-      const openapiUrl = path.join(publicPath, openapiPath);
-      schemas.push({ url: buildUrl(openapiUrl), format: 'openapi' });
-    }
-
-    return schemas;
-  } else {
-    const pathParts = schemaPublicPath.split('.');
-    const format = pathParts[pathParts.length - 1];
-    return [{ url: buildUrl(schemaPublicPath), format }];
-  }
-};
diff --git a/eventcatalog/src/utils/collections/services.ts b/eventcatalog/src/utils/collections/services.ts
deleted file mode 100644
index 58e3bbcaf..000000000
--- a/eventcatalog/src/utils/collections/services.ts
+++ /dev/null
@@ -1,211 +0,0 @@
-import { getItemsFromCollectionByIdAndSemverOrLatest, getVersionForCollectionItem } from '@utils/collections/util';
-import { getCollection } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import path from 'path';
-import semver from 'semver';
-import type { CollectionTypes } from '@types';
-const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd();
-import utils from '@eventcatalog/sdk';
-
-export type Service = CollectionEntry<'services'>;
-
-interface Props {
-  getAllVersions?: boolean;
-}
-
-// Cache for build time
-let cachedServices: Record<string, Service[]> = {
-  allVersions: [],
-  currentVersions: [],
-};
-
-export const getServices = async ({ getAllVersions = true }: Props = {}): Promise<Service[]> => {
-  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
-
-  // Check if we have cached domains for this specific getAllVersions value
-  if (cachedServices[cacheKey].length > 0) {
-    return cachedServices[cacheKey];
-  }
-
-  // Get services that are not versioned
-  const services = await getCollection('services', (service) => {
-    return (getAllVersions || !service.filePath?.includes('versioned')) && service.data.hidden !== true;
-  });
-
-  const events = await getCollection('events');
-  const commands = await getCollection('commands');
-  const queries = await getCollection('queries');
-  const entities = await getCollection('entities');
-  const containers = await getCollection('containers');
-  const allMessages = [...events, ...commands, ...queries];
-
-  // @ts-ignore // TODO: Fix this type
-  cachedServices[cacheKey] = await Promise.all(
-    services.map(async (service) => {
-      const { latestVersion, versions } = getVersionForCollectionItem(service, services);
-
-      const sendsMessages = service.data.sends || [];
-      const receivesMessages = service.data.receives || [];
-      const serviceEntities = service.data.entities || [];
-      const serviceWritesTo = service.data.writesTo || [];
-      const serviceReadsFrom = service.data.readsFrom || [];
-
-      const sends = sendsMessages
-        .map((message: any) => getItemsFromCollectionByIdAndSemverOrLatest(allMessages, message.id, message.version))
-        .flat()
-        .filter((e: any) => e !== undefined);
-
-      const receives = receivesMessages
-        .map((message: any) => getItemsFromCollectionByIdAndSemverOrLatest(allMessages, message.id, message.version))
-        .flat()
-        .filter((e: any) => e !== undefined);
-
-      const mappedEntities = serviceEntities
-        .map((entity: any) => getItemsFromCollectionByIdAndSemverOrLatest(entities, entity.id, entity.version))
-        .flat()
-        .filter((e: any) => e !== undefined);
-
-      const mappedWritesTo = serviceWritesTo
-        .map((container: any) => getItemsFromCollectionByIdAndSemverOrLatest(containers, container.id, container.version))
-        .flat()
-        .filter((e: any) => e !== undefined);
-
-      const mappedReadsFrom = serviceReadsFrom
-        .map((container: any) => getItemsFromCollectionByIdAndSemverOrLatest(containers, container.id, container.version))
-        .flat()
-        .filter((e: any) => e !== undefined);
-
-      const { getResourceFolderName } = utils(process.env.PROJECT_DIR ?? '');
-      const folderName = await getResourceFolderName(
-        process.env.PROJECT_DIR ?? '',
-        service.data.id,
-        service.data.version.toString()
-      );
-      const serviceFolderName = folderName ?? service.id.replace(`-${service.data.version}`, '');
-
-      return {
-        ...service,
-        data: {
-          ...service.data,
-          writesTo: mappedWritesTo,
-          readsFrom: mappedReadsFrom,
-          receives,
-          sends,
-          versions,
-          latestVersion,
-          entities: mappedEntities,
-        },
-        // TODO: verify if it could be deleted.
-        nodes: {
-          receives,
-          sends,
-        },
-        catalog: {
-          // TODO: avoid use string replace at path due to win32
-          path: path.join(service.collection, service.id.replace('/index.mdx', '')),
-          absoluteFilePath: path.join(PROJECT_DIR, service.collection, service.id.replace('/index.mdx', '/index.md')),
-          astroContentFilePath: path.join(process.cwd(), 'src', 'content', service.collection, service.id),
-          filePath: path.join(process.cwd(), 'src', 'catalog-files', service.collection, service.id.replace('/index.mdx', '')),
-          // service will be MySerive-0.0.1 remove the version
-          publicPath: path.join('/generated', service.collection, serviceFolderName),
-          type: 'service',
-        },
-      };
-    })
-  );
-
-  // order them by the name of the service
-  cachedServices[cacheKey].sort((a, b) => {
-    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
-  });
-
-  return cachedServices[cacheKey];
-};
-
-export const getProducersOfMessage = (services: Service[], message: CollectionEntry<'events' | 'commands' | 'queries'>) => {
-  return services.filter((service) => {
-    return service.data.sends?.some((send) => {
-      const idMatch = send.id === message.data.id;
-
-      // If no version specified in send, treat as 'latest'
-      if (!send.version) return idMatch;
-
-      // If version is 'latest', match any version
-      if (send.version === 'latest') return idMatch;
-
-      // Use semver to compare versions
-      return idMatch && semver.satisfies(message.data.version, send.version);
-    });
-  });
-};
-
-export const getConsumersOfMessage = (services: Service[], message: CollectionEntry<'events' | 'commands' | 'queries'>) => {
-  return services.filter((service) => {
-    return service.data.receives?.some((receive) => {
-      const idMatch = receive.id === message.data.id;
-
-      // If no version specified in send, treat as 'latest'
-      if (!receive.version) return idMatch;
-
-      // If version is 'latest', match any version
-      if (receive.version === 'latest') return idMatch;
-
-      // Use semver to compare versions
-      return idMatch && semver.satisfies(message.data.version, receive.version);
-    });
-  });
-};
-
-export const getSpecificationsForService = (service: CollectionEntry<CollectionTypes>) => {
-  const specifications = Array.isArray(service.data.specifications) ? service.data.specifications : [];
-
-  if (service.data.specifications && !Array.isArray(service.data.specifications)) {
-    if (service.data.specifications.asyncapiPath) {
-      specifications.push({
-        type: 'asyncapi',
-        path: service.data.specifications.asyncapiPath,
-        name: 'AsyncAPI',
-      });
-    }
-    if (service.data.specifications.openapiPath) {
-      specifications.push({
-        type: 'openapi',
-        path: service.data.specifications.openapiPath,
-        name: 'OpenAPI',
-      });
-    }
-  }
-
-  return specifications.map((spec) => ({
-    ...spec,
-    name: spec.name || (spec.type === 'asyncapi' ? 'AsyncAPI' : 'OpenAPI'),
-    filename: path.basename(spec.path),
-    filenameWithoutExtension: path.basename(spec.path, path.extname(spec.path)),
-  }));
-};
-// Get services for channel
-export const getProducersAndConsumersForChannel = async (channel: CollectionEntry<'channels'>) => {
-  const messages = channel.data.messages ?? [];
-  const services = await getServices({ getAllVersions: false });
-
-  const producers = services.filter((service) => {
-    const sends = service.data.sends ?? [];
-    return sends.some((send) => {
-      // @ts-ignore
-      return messages.some((m) => m.id === send.data.id);
-    });
-  });
-
-  const consumers = services.filter((service) => {
-    const receives = service.data.receives ?? [];
-    return receives.some((receive) => {
-      // @ts-ignore
-      return messages.some((m) => m.id === receive.data.id);
-    });
-  });
-
-  return {
-    producers: producers ?? [],
-    consumers: consumers ?? [],
-  };
-};
diff --git a/eventcatalog/src/utils/collections/util.ts b/eventcatalog/src/utils/collections/util.ts
deleted file mode 100644
index d8699af3e..000000000
--- a/eventcatalog/src/utils/collections/util.ts
+++ /dev/null
@@ -1,167 +0,0 @@
-import type { CollectionTypes } from '@types';
-import type { CollectionEntry } from 'astro:content';
-import { coerce, compare, eq, satisfies as satisfiesRange } from 'semver';
-
-export const getPreviousVersion = (version: string, versions: string[]) => {
-  const index = versions.indexOf(version);
-  return index === -1 ? null : versions[index + 1];
-};
-
-export const getVersions = (data: CollectionEntry<CollectionTypes>[]) => {
-  const allVersions = data.map((item) => item.data.version);
-  const versions = [...new Set(allVersions)];
-  return sortStringVersions(versions);
-};
-
-export function isSameVersion(v1: string | undefined, v2: string | undefined) {
-  const semverV1 = coerce(v1);
-  const semverV2 = coerce(v2);
-
-  if (semverV1 != null && semverV2 != null) {
-    return eq(semverV1, semverV2);
-  }
-
-  return v1 === v2;
-}
-
-/**
- * Sorts versioned items. Latest version first.
- */
-export function sortVersioned<T>(versioned: T[], versionExtractor: (e: T) => string): T[] {
-  // try to coerce semver versions from input version
-  const semverVersions = versioned.map((v) => ({ original: v, semver: coerce(versionExtractor(v)) }));
-
-  // if all versions are semver'ish, use semver to sort them
-  if (semverVersions.every((v) => v.semver != null)) {
-    const sorted = semverVersions.sort((a, b) => compare(b.semver!, a.semver!));
-
-    return sorted.map((v) => v.original);
-  } else {
-    // fallback to default sort
-    return versioned.sort((a, b) => versionExtractor(b).localeCompare(versionExtractor(a)));
-  }
-}
-
-// Takes a collection and a id of a resource, and checks if the version is the latest version in the collection
-export const getLatestVersionInCollectionById = (collection: CollectionEntry<CollectionTypes>[], id: string) => {
-  const items = collection.filter((i) => i.data.id === id);
-  const sortedVersions = sortVersioned(items, (v) => v.data.version);
-  return sortedVersions[0]?.data.version ?? id;
-};
-
-export const getVersionForCollectionItem = (
-  item: CollectionEntry<CollectionTypes>,
-  collection: CollectionEntry<CollectionTypes>[]
-) => {
-  const allVersionsForItem = collection.filter((i) => i.data.id === item.data.id);
-
-  return getVersions(allVersionsForItem);
-};
-
-export function sortStringVersions(versions: string[]) {
-  const sorted = sortVersioned(versions, (v) => v);
-
-  return { latestVersion: sorted[0], versions: sorted };
-}
-
-/**
- * @param {string} version A valid version (number | v{\d+} | semver)
- * @param {string} range A semver range or exact version to compare
- * @returns {boolean} Returns true if the version satisfies the range.
- */
-export const satisfies = (version: string, range: string): boolean => {
-  const coercedVersion = coerce(version);
-  if (!coercedVersion) return false;
-  return satisfiesRange(coercedVersion, range);
-};
-
-export const getItemsFromCollectionByIdAndSemverOrLatest = <T extends { data: { id: string; version: string } }>(
-  collection: T[],
-  id: string,
-  version?: string
-): T[] => {
-  const filteredCollection = collection.filter((c) => c.data.id == id);
-
-  if (version && version != 'latest') {
-    return filteredCollection.filter((c) => satisfies(c.data.version, version));
-  }
-
-  // Order by version
-  const sorted = sortVersioned(filteredCollection, (item) => item.data.version);
-
-  // latest version
-  return sorted[0] != null ? [sorted[0]] : [];
-};
-
-export const findMatchingNodes = (
-  nodesA: CollectionEntry<'events' | 'commands' | 'queries' | 'services' | 'containers'>[],
-  nodesB: CollectionEntry<'events' | 'commands' | 'queries' | 'services' | 'containers'>[]
-) => {
-  // Track messages that are both sent and received
-  return nodesA.filter((nodeA) => {
-    return nodesB.some((nodeB) => {
-      return nodeB.data.id === nodeA.data.id && nodeB.data.version === nodeA.data.version;
-    });
-  });
-};
-
-export const resourceToCollectionMap = {
-  service: 'services',
-  event: 'events',
-  command: 'commands',
-  query: 'queries',
-  domain: 'domains',
-  flow: 'flows',
-  channel: 'channels',
-  user: 'users',
-  team: 'teams',
-  container: 'containers',
-} as const;
-
-export const collectionToResourceMap = {
-  services: 'service',
-  events: 'event',
-  commands: 'command',
-  queries: 'query',
-  domains: 'domain',
-  flows: 'flow',
-  channels: 'channel',
-  users: 'user',
-  teams: 'team',
-  containers: 'container',
-} as const;
-
-export const getDeprecatedDetails = (item: CollectionEntry<CollectionTypes>) => {
-  let options = {
-    isMarkedAsDeprecated: false,
-    hasDeprecated: false,
-    message: '',
-    deprecatedDate: '',
-  };
-
-  if (!item.data?.deprecated) return options;
-
-  if (typeof item.data.deprecated === 'boolean') {
-    options.hasDeprecated = item.data.deprecated;
-    options.isMarkedAsDeprecated = item.data.deprecated;
-  }
-
-  if (typeof item.data.deprecated === 'object') {
-    options.isMarkedAsDeprecated = true;
-    options.hasDeprecated = item.data.deprecated.date ? new Date(item.data.deprecated.date) < new Date() : false;
-    options.message = item.data.deprecated.message ?? '';
-    options.deprecatedDate = item.data.deprecated.date
-      ? new Date(item.data.deprecated.date).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })
-      : '';
-  }
-
-  return options;
-};
-
-export const removeContentFromCollection = (collection: CollectionEntry<CollectionTypes>[]) => {
-  return collection.map((item) => ({
-    ...item,
-    body: undefined,
-    catalog: undefined,
-  }));
-};
diff --git a/eventcatalog/src/utils/collections/versions.ts b/eventcatalog/src/utils/collections/versions.ts
deleted file mode 100644
index f5d072a92..000000000
--- a/eventcatalog/src/utils/collections/versions.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import type { CollectionTypes } from '@types';
-import type { CollectionEntry } from 'astro:content';
-import { satisfies, validRange } from 'semver';
-
-export const getVersionFromCollection = (
-  collection: CollectionEntry<CollectionTypes>[],
-  id: string,
-  version?: string
-): CollectionEntry<CollectionTypes>[] => {
-  const data = collection;
-  const semverRange = validRange(version);
-
-  if (semverRange) {
-    return data.filter((msg) => msg.data.id == id).filter((msg) => satisfies(msg.data.version, semverRange));
-  }
-
-  const filteredEvents = data.filter((event) => event.data.id === id);
-
-  // Order by version
-  const sorted = filteredEvents.sort((a, b) => {
-    return a.data.version.localeCompare(b.data.version);
-  });
-
-  // latest version
-  return [sorted[sorted.length - 1]];
-};
diff --git a/eventcatalog/src/utils/commands.ts b/eventcatalog/src/utils/commands.ts
deleted file mode 100644
index 1ce0c2344..000000000
--- a/eventcatalog/src/utils/commands.ts
+++ /dev/null
@@ -1,112 +0,0 @@
-import { getCollection } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import path from 'path';
-import { getVersionForCollectionItem, satisfies } from './collections/util';
-import utils from '@eventcatalog/sdk';
-
-const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd();
-
-type Command = CollectionEntry<'commands'> & {
-  catalog: {
-    path: string;
-    filePath: string;
-    type: string;
-  };
-};
-
-interface Props {
-  getAllVersions?: boolean;
-  hydrateServices?: boolean;
-}
-
-// cache for build time
-let cachedCommands: Record<string, Command[]> = {
-  allVersions: [],
-  currentVersions: [],
-};
-
-export const getCommands = async ({ getAllVersions = true, hydrateServices = true }: Props = {}): Promise<Command[]> => {
-  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
-
-  if (cachedCommands[cacheKey].length > 0 && hydrateServices) {
-    return cachedCommands[cacheKey];
-  }
-
-  const commands = await getCollection('commands', (command) => {
-    return (getAllVersions || !command.filePath?.includes('versioned')) && command.data.hidden !== true;
-  });
-
-  const services = await getCollection('services');
-  const allChannels = await getCollection('channels');
-
-  // @ts-ignore
-  cachedCommands[cacheKey] = await Promise.all(
-    commands.map(async (command) => {
-      const { latestVersion, versions } = getVersionForCollectionItem(command, commands);
-
-      const producers = services
-        .filter((service) => {
-          return service.data.sends?.some((item) => {
-            if (item.id != command.data.id) return false;
-            if (item.version == 'latest' || item.version == undefined) return command.data.version == latestVersion;
-            return satisfies(command.data.version, item.version);
-          });
-        })
-        .map((service) => {
-          if (!hydrateServices) return { id: service.data.id, version: service.data.version };
-          return service;
-        });
-
-      const consumers = services
-        .filter((service) => {
-          return service.data.receives?.some((item) => {
-            if (item.id != command.data.id) return false;
-            if (item.version == 'latest' || item.version == undefined) return command.data.version == latestVersion;
-            return satisfies(command.data.version, item.version);
-          });
-        })
-        .map((service) => {
-          if (!hydrateServices) return { id: service.data.id, version: service.data.version };
-          return service;
-        });
-
-      const messageChannels = command.data.channels || [];
-      const channelsForCommand = allChannels.filter((c) => messageChannels.some((channel) => c.data.id === channel.id));
-
-      const { getResourceFolderName } = utils(process.env.PROJECT_DIR ?? '');
-      const folderName = await getResourceFolderName(
-        process.env.PROJECT_DIR ?? '',
-        command.data.id,
-        command.data.version.toString()
-      );
-      const commandFolderName = folderName ?? command.id.replace(`-${command.data.version}`, '');
-
-      return {
-        ...command,
-        data: {
-          ...command.data,
-          messageChannels: channelsForCommand,
-          producers,
-          consumers,
-          versions,
-          latestVersion,
-        },
-        catalog: {
-          path: path.join(command.collection, command.id.replace('/index.mdx', '')),
-          absoluteFilePath: path.join(PROJECT_DIR, command.collection, command.id.replace('/index.mdx', '/index.md')),
-          astroContentFilePath: path.join(process.cwd(), 'src', 'content', command.collection, command.id),
-          filePath: path.join(process.cwd(), 'src', 'catalog-files', command.collection, command.id.replace('/index.mdx', '')),
-          publicPath: path.join('/generated', command.collection, commandFolderName),
-          type: 'command',
-        },
-      };
-    })
-  );
-
-  // order them by the name of the command
-  cachedCommands[cacheKey].sort((a, b) => {
-    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
-  });
-
-  return cachedCommands[cacheKey];
-};
diff --git a/eventcatalog/src/utils/entities.ts b/eventcatalog/src/utils/entities.ts
deleted file mode 100644
index 36a421e62..000000000
--- a/eventcatalog/src/utils/entities.ts
+++ /dev/null
@@ -1,96 +0,0 @@
-import { getCollection } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import path from 'path';
-import { getVersionForCollectionItem, satisfies } from './collections/util';
-import utils from '@eventcatalog/sdk';
-
-const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd();
-
-export type Entity = CollectionEntry<'entities'> & {
-  catalog: {
-    path: string;
-    filePath: string;
-    type: string;
-  };
-};
-
-interface Props {
-  getAllVersions?: boolean;
-}
-
-// cache for build time
-let cachedEntities: Record<string, Entity[]> = {
-  allVersions: [],
-  currentVersions: [],
-};
-
-export const getEntities = async ({ getAllVersions = true }: Props = {}): Promise<Entity[]> => {
-  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
-
-  if (cachedEntities[cacheKey].length > 0) {
-    return cachedEntities[cacheKey];
-  }
-
-  const entities = await getCollection('entities', (entity) => {
-    return (getAllVersions || !entity.filePath?.includes('versioned')) && entity.data.hidden !== true;
-  });
-
-  const services = await getCollection('services');
-  const domains = await getCollection('domains');
-
-  cachedEntities[cacheKey] = await Promise.all(
-    entities.map(async (entity) => {
-      const { latestVersion, versions } = getVersionForCollectionItem(entity, entities);
-
-      const servicesThatReferenceEntity = services.filter((service) =>
-        service.data.entities?.some((item) => {
-          if (item.id != entity.data.id) return false;
-          if (item.version == 'latest' || item.version == undefined) return entity.data.version == latestVersion;
-          return satisfies(entity.data.version, item.version);
-        })
-      );
-
-      const domainsThatReferenceEntity = domains.filter((domain) =>
-        domain.data.entities?.some((item) => {
-          if (item.id != entity.data.id) return false;
-          if (item.version == 'latest' || item.version == undefined) return entity.data.version == latestVersion;
-          return satisfies(entity.data.version, item.version);
-        })
-      );
-
-      const { getResourceFolderName } = utils(process.env.PROJECT_DIR ?? '');
-      const folderName = await getResourceFolderName(
-        process.env.PROJECT_DIR ?? '',
-        entity.data.id,
-        entity.data.version.toString()
-      );
-      const entityFolderName = folderName ?? entity.id.replace(`-${entity.data.version}`, '');
-
-      return {
-        ...entity,
-        data: {
-          ...entity.data,
-          versions,
-          latestVersion,
-          services: servicesThatReferenceEntity,
-          domains: domainsThatReferenceEntity,
-        },
-        catalog: {
-          path: path.join(entity.collection, entity.id.replace('/index.mdx', '')),
-          absoluteFilePath: path.join(PROJECT_DIR, entity.collection, entity.id.replace('/index.mdx', '/index.md')),
-          astroContentFilePath: path.join(process.cwd(), 'src', 'content', entity.collection, entity.id),
-          filePath: path.join(process.cwd(), 'src', 'catalog-files', entity.collection, entity.id.replace('/index.mdx', '')),
-          publicPath: path.join('/generated', entity.collection, entityFolderName),
-          type: 'entity',
-        },
-      };
-    })
-  );
-
-  // order them by the name of the event
-  cachedEntities[cacheKey].sort((a, b) => {
-    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
-  });
-
-  return cachedEntities[cacheKey];
-};
diff --git a/eventcatalog/src/utils/eventcatalog-config/catalog.ts b/eventcatalog/src/utils/eventcatalog-config/catalog.ts
deleted file mode 100644
index 584c130f7..000000000
--- a/eventcatalog/src/utils/eventcatalog-config/catalog.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import * as config from '@config';
-
-type SideBarItemConfig = {
-  visible?: boolean;
-};
-
-export type CatalogConfig = {
-  docs: {
-    sidebar: {
-      showPageHeadings?: boolean;
-      domains?: SideBarItemConfig;
-      flows?: SideBarItemConfig;
-      services?: SideBarItemConfig;
-      messages?: SideBarItemConfig;
-      teams?: SideBarItemConfig;
-      users?: SideBarItemConfig;
-    };
-  };
-};
-
-const getConfigValue = (obj: any, key: string, defaultValue: any) => {
-  return obj?.[key] ?? defaultValue;
-};
-
-export const isCollectionVisibleInCatalog = (collection: string) => {
-  const sidebarConfig = config?.default?.docs?.sidebar || {};
-  const collections = [
-    'events',
-    'commands',
-    'queries',
-    'domains',
-    'channels',
-    'flows',
-    'services',
-    'teams',
-    'users',
-    'customDocs',
-  ];
-
-  if (!collections.includes(collection)) return false;
-
-  const collectionConfig =
-    sidebarConfig[collection === 'events' || collection === 'commands' || collection === 'queries' ? 'messages' : collection];
-  return getConfigValue(collectionConfig, 'visible', true);
-};
-
-export default config.default;
diff --git a/eventcatalog/src/utils/events.ts b/eventcatalog/src/utils/events.ts
deleted file mode 100644
index 5f8951ea1..000000000
--- a/eventcatalog/src/utils/events.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-import { getCollection } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import path from 'path';
-import { getVersionForCollectionItem, satisfies } from './collections/util';
-import utils from '@eventcatalog/sdk';
-
-const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd();
-
-type Event = CollectionEntry<'events'> & {
-  catalog: {
-    path: string;
-    filePath: string;
-    type: string;
-  };
-};
-
-interface Props {
-  getAllVersions?: boolean;
-  hydrateServices?: boolean;
-}
-
-// cache for build time
-let cachedEvents: Record<string, Event[]> = {
-  allVersions: [],
-  currentVersions: [],
-};
-
-export const getEvents = async ({ getAllVersions = true, hydrateServices = true }: Props = {}): Promise<Event[]> => {
-  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
-
-  if (cachedEvents[cacheKey].length > 0 && hydrateServices) {
-    return cachedEvents[cacheKey];
-  }
-
-  const events = await getCollection('events', (event) => {
-    return (getAllVersions || !event.filePath?.includes('versioned')) && event.data.hidden !== true;
-  });
-
-  const services = await getCollection('services');
-  const allChannels = await getCollection('channels');
-
-  // @ts-ignore
-  cachedEvents[cacheKey] = await Promise.all(
-    events.map(async (event) => {
-      const { latestVersion, versions } = getVersionForCollectionItem(event, events);
-
-      const producers = services
-        .filter((service) =>
-          service.data.sends?.some((item) => {
-            if (item.id != event.data.id) return false;
-            if (item.version == 'latest' || item.version == undefined) return event.data.version == latestVersion;
-            return satisfies(event.data.version, item.version);
-          })
-        )
-        .map((service) => {
-          if (!hydrateServices) return { id: service.data.id, version: service.data.version };
-          return service;
-        });
-
-      const consumers = services
-        .filter((service) =>
-          service.data.receives?.some((item) => {
-            if (item.id != event.data.id) return false;
-            if (item.version == 'latest' || item.version == undefined) return event.data.version == latestVersion;
-            return satisfies(event.data.version, item.version);
-          })
-        )
-        .map((service) => {
-          if (!hydrateServices) return { id: service.data.id, version: service.data.version };
-          return service;
-        });
-
-      const messageChannels = event.data.channels || [];
-      const channelsForEvent = allChannels.filter((c) => messageChannels.some((channel) => c.data.id === channel.id));
-
-      const { getResourceFolderName } = utils(process.env.PROJECT_DIR ?? '');
-      const folderName = await getResourceFolderName(process.env.PROJECT_DIR ?? '', event.data.id, event.data.version.toString());
-      const eventFolderName = folderName ?? event.id.replace(`-${event.data.version}`, '');
-
-      return {
-        ...event,
-        data: {
-          ...event.data,
-          messageChannels: channelsForEvent,
-          producers,
-          consumers,
-          versions,
-          latestVersion,
-        },
-        catalog: {
-          path: path.join(event.collection, event.id.replace('/index.mdx', '')),
-          absoluteFilePath: path.join(PROJECT_DIR, event.collection, event.id.replace('/index.mdx', '/index.md')),
-          astroContentFilePath: path.join(process.cwd(), 'src', 'content', event.collection, event.id),
-          filePath: path.join(process.cwd(), 'src', 'catalog-files', event.collection, event.id.replace('/index.mdx', '')),
-          publicPath: path.join('/generated', event.collection, eventFolderName),
-          type: 'event',
-        },
-      };
-    })
-  );
-
-  // order them by the name of the event
-  cachedEvents[cacheKey].sort((a, b) => {
-    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
-  });
-
-  return cachedEvents[cacheKey];
-};
diff --git a/eventcatalog/src/utils/feature.ts b/eventcatalog/src/utils/feature.ts
deleted file mode 100644
index 45a0e605f..000000000
--- a/eventcatalog/src/utils/feature.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-/**
- * ⚠️ WARNING: IMPORTANT LICENSE NOTICE ⚠️
- *
- * Manually setting environment variables (EVENTCATALOG_STARTER or EVENTCATALOG_SCALE) to 'true'
- * or modifying these functions without a valid license is strictly prohibited and constitutes
- * a violation of EventCatalog's terms of use and license agreement.
- *
- * To access premium features legally:
- * 1. Visit https://www.eventcatalog.dev/pricing
- * 2. Purchase an appropriate license
- * 3. Follow the official activation instructions
- */
-
-import config from '@config';
-import fs from 'fs';
-import { join } from 'path';
-
-// These functions check for valid, legally obtained access to premium features
-export const isEventCatalogStarterEnabled = () => process.env.EVENTCATALOG_STARTER === 'true';
-export const isEventCatalogScaleEnabled = () => process.env.EVENTCATALOG_SCALE === 'true';
-
-export const isPrivateRemoteSchemaEnabled = () => isEventCatalogScaleEnabled() || isEventCatalogStarterEnabled();
-
-export const showEventCatalogBranding = () => {
-  const override = process.env.EVENTCATALOG_SHOW_BRANDING;
-  // if any value we return true
-  if (override) {
-    return true;
-  }
-  return !isEventCatalogStarterEnabled() && !isEventCatalogScaleEnabled();
-};
-
-export const showCustomBranding = () => {
-  return isEventCatalogStarterEnabled() || isEventCatalogScaleEnabled();
-};
-
-export const isChangelogEnabled = () => config?.changelog?.enabled ?? true;
-
-export const isCustomDocsEnabled = () => isEventCatalogStarterEnabled() || isEventCatalogScaleEnabled();
-export const isEventCatalogChatEnabled = () => {
-  const isFeatureEnabledFromPlan = isEventCatalogStarterEnabled() || isEventCatalogScaleEnabled();
-  return isFeatureEnabledFromPlan && config?.chat?.enabled && isSSR();
-};
-
-export const isEventCatalogUpgradeEnabled = () => !isEventCatalogStarterEnabled() && !isEventCatalogScaleEnabled();
-export const isCustomLandingPageEnabled = () => isEventCatalogStarterEnabled() || isEventCatalogScaleEnabled();
-
-export const isMarkdownDownloadEnabled = () => config?.llmsTxt?.enabled ?? false;
-export const isLLMSTxtEnabled = () => (config?.llmsTxt?.enabled || isEventCatalogChatEnabled()) ?? false;
-
-export const isAuthEnabled = () => {
-  const directory = process.env.PROJECT_DIR || process.cwd();
-  const hasAuthConfig = fs.existsSync(join(directory, 'eventcatalog.auth.js'));
-  return (hasAuthConfig && isSSR() && isEventCatalogScaleEnabled()) || false;
-};
-
-export const isSSR = () => config?.output === 'server';
-
-export const isVisualiserEnabled = () => config?.visualiser?.enabled ?? true;
diff --git a/eventcatalog/src/utils/generators/index.ts b/eventcatalog/src/utils/generators/index.ts
deleted file mode 100644
index 918e129b4..000000000
--- a/eventcatalog/src/utils/generators/index.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-// Should really only be used on the server side
-// If users are using path or fs in the eventcatalog.config.js file, it will break the build (for now)
-
-import config from '@config';
-
-export const getConfigurationForGivenGenerator = (generator: string) => {
-  const generators = config.generators ?? [];
-  const generatorConfig = generators.find((g: any) => g[0] === generator);
-  return generatorConfig?.[1];
-};
diff --git a/eventcatalog/src/utils/llms.ts b/eventcatalog/src/utils/llms.ts
deleted file mode 100644
index 4b08a860c..000000000
--- a/eventcatalog/src/utils/llms.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import type { CollectionTypes } from '@types';
-import type { CollectionEntry } from 'astro:content';
-import { dirname } from 'path';
-import { join } from 'path';
-import fs from 'fs';
-
-export const addSchemaToMarkdown = (collection: CollectionEntry<CollectionTypes>, file: string) => {
-  const resourceData = collection?.data;
-  const fileToResource = collection.filePath ?? '';
-  let schemas: string[] = [];
-
-  if (!resourceData?.specifications && !resourceData?.schemaPath) {
-    return file;
-  }
-
-  if (Array.isArray(resourceData?.specifications)) {
-    schemas = resourceData?.specifications.map((specification: any) => specification.path);
-  } else {
-    schemas = [resourceData?.schemaPath ?? ''];
-  }
-
-  const filteredSchemas = schemas.filter((schema: any) => schema !== undefined);
-
-  // attach the schema if it has it
-  if (filteredSchemas.length > 0) {
-    for (const pathToSchema of filteredSchemas) {
-      const directory = dirname(fileToResource);
-      const schemaPath = join(directory, pathToSchema);
-      const schemaFile = fs.readFileSync(schemaPath, 'utf8');
-      file = `${file}\n\n ## Raw Schema:${pathToSchema}\n\n${schemaFile}`;
-    }
-  }
-
-  return file;
-};
diff --git a/eventcatalog/src/utils/markdown.ts b/eventcatalog/src/utils/markdown.ts
deleted file mode 100644
index 408ba1317..000000000
--- a/eventcatalog/src/utils/markdown.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-// Method returns MDX components and there props in markdown files
-// rarely used, but useful for components that need to know how many times
-// the user wants to render a component in a markdown file
-export const getMDXComponentsByName = (document: string, componentName: string) => {
-  // Define regex pattern to match <SchemaViewer ... />
-  const pattern = new RegExp(`<${componentName}\\s+([^>]*)\\/>`, 'g');
-
-  // Find all matches of the pattern
-  const matches = [...document.matchAll(pattern)];
-
-  // Extract the properties of each SchemaViewer
-  const components = matches.map((match) => {
-    const propsString = match[1];
-    const props = {};
-
-    // Use regex to extract key-value pairs from propsString
-    const propsPattern = /(\w+)=["']([^"']+)["']/g;
-    let propMatch;
-    while ((propMatch = propsPattern.exec(propsString)) !== null) {
-      const key = propMatch[1];
-      const value = propMatch[2];
-      // @ts-ignore
-      props[key] = value;
-    }
-
-    return props;
-  });
-
-  return components;
-};
diff --git a/eventcatalog/src/utils/messages.ts b/eventcatalog/src/utils/messages.ts
deleted file mode 100644
index 5c8984bda..000000000
--- a/eventcatalog/src/utils/messages.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-// Exporting getCommands and getEvents directly
-import { getCommands } from '@utils/commands';
-import { getEvents } from '@utils/events';
-import { getQueries } from './queries';
-import type { CollectionEntry } from 'astro:content';
-export { getCommands } from '@utils/commands';
-export { getEvents } from '@utils/events';
-
-interface Props {
-  getAllVersions?: boolean;
-  hydrateServices?: boolean;
-}
-
-type Messages = {
-  commands: CollectionEntry<'commands'>[];
-  events: CollectionEntry<'events'>[];
-  queries: CollectionEntry<'queries'>[];
-};
-
-// Main function that uses the imported functions
-export const getMessages = async ({ getAllVersions = true, hydrateServices = true }: Props = {}): Promise<Messages> => {
-  const [commands, events, queries] = await Promise.all([
-    getCommands({ getAllVersions, hydrateServices }),
-    getEvents({ getAllVersions, hydrateServices }),
-    getQueries({ getAllVersions, hydrateServices }),
-  ]);
-
-  return {
-    commands,
-    events,
-    queries,
-  };
-};
diff --git a/eventcatalog/src/utils/node-graphs/container-node-graph.ts b/eventcatalog/src/utils/node-graphs/container-node-graph.ts
deleted file mode 100644
index a7ccc9b14..000000000
--- a/eventcatalog/src/utils/node-graphs/container-node-graph.ts
+++ /dev/null
@@ -1,155 +0,0 @@
-import type { CollectionEntry } from 'astro:content';
-import dagre from 'dagre';
-import { calculatedNodes, createDagreGraph, createEdge, generatedIdForEdge, generateIdForNode } from './utils/utils';
-import { MarkerType } from '@xyflow/react';
-import { findMatchingNodes } from '@utils/collections/util';
-import { getContainers } from '@utils/collections/containers';
-
-type DagreGraph = any;
-
-interface Props {
-  id: string;
-  version: string;
-  defaultFlow?: DagreGraph;
-  mode?: 'simple' | 'full';
-  channelRenderMode?: 'flat' | 'single';
-  collection?: CollectionEntry<'containers'>[];
-}
-
-export const getNodesAndEdges = async ({ id, version, defaultFlow, mode = 'simple', channelRenderMode = 'flat' }: Props) => {
-  const containers = await getContainers();
-
-  const flow = defaultFlow || createDagreGraph({ ranksep: 300, nodesep: 50 });
-  const nodes = [] as any,
-    edges = [] as any;
-
-  const container = containers.find((container) => container.data.id === id && container.data.version === version);
-
-  // Nothing found...
-  if (!container) {
-    return {
-      nodes: [],
-      edges: [],
-    };
-  }
-
-  const servicesThatWriteToContainer = (container.data.servicesThatWriteToContainer as CollectionEntry<'services'>[]) || [];
-  const servicesThatReadFromContainer = (container.data.servicesThatReadFromContainer as CollectionEntry<'services'>[]) || [];
-
-  // Track nodes that are bth sent and received
-  const bothSentAndReceived = findMatchingNodes(servicesThatWriteToContainer, servicesThatReadFromContainer);
-
-  servicesThatWriteToContainer.forEach((service) => {
-    nodes.push({
-      id: generateIdForNode(service),
-      type: service?.collection,
-      sourcePosition: 'right',
-      targetPosition: 'left',
-      data: { mode, service: { ...service.data } },
-      position: { x: 250, y: 0 },
-    });
-
-    if (!bothSentAndReceived.includes(service)) {
-      edges.push({
-        id: generatedIdForEdge(service, container),
-        source: generateIdForNode(service),
-        target: generateIdForNode(container),
-        label: 'writes to',
-        data: { service },
-        animated: false,
-        type: 'default',
-        style: {
-          strokeWidth: 1,
-        },
-      });
-    }
-  });
-
-  // The message itself
-  nodes.push({
-    id: generateIdForNode(container),
-    sourcePosition: 'right',
-    targetPosition: 'left',
-    data: {
-      mode,
-      data: {
-        ...container.data,
-      },
-    },
-    position: { x: 0, y: 0 },
-    type: 'data',
-  });
-
-  //   // The messages the service sends
-  servicesThatReadFromContainer.forEach((service) => {
-    nodes.push({
-      id: generateIdForNode(service),
-      sourcePosition: 'left',
-      targetPosition: 'right',
-      data: { title: service?.data.id, mode, service: { ...service.data } },
-      position: { x: 0, y: 0 },
-      type: service?.collection,
-    });
-
-    if (!bothSentAndReceived.includes(service)) {
-      edges.push(
-        createEdge({
-          id: generatedIdForEdge(service, container),
-          source: generateIdForNode(container),
-          target: generateIdForNode(service),
-          label: `reads from \n (${container.data.technology})`,
-          data: { service },
-          type: 'multiline',
-          // type: 'animatedData',
-          markerStart: {
-            type: MarkerType.ArrowClosed,
-            width: 40,
-            height: 40,
-          },
-          markerEnd: undefined,
-        })
-      );
-    }
-  });
-
-  // Handle messages that are both sent and received
-  bothSentAndReceived.forEach((_service) => {
-    if (container) {
-      edges.push(
-        createEdge({
-          id: generatedIdForEdge(container, _service) + '-both',
-          source: generateIdForNode(_service),
-          target: generateIdForNode(container),
-          label: `read and writes to \n (${container.data.technology})`,
-          type: 'multiline',
-          markerStart: {
-            type: MarkerType.ArrowClosed,
-            width: 40,
-            height: 40,
-          },
-          markerEnd: {
-            type: MarkerType.ArrowClosed,
-            width: 40,
-            height: 40,
-          },
-        })
-      );
-    }
-  });
-
-  nodes.forEach((node: any) => {
-    flow.setNode(node.id, { width: 150, height: 100 });
-  });
-
-  edges.forEach((edge: any) => {
-    flow.setEdge(edge.source, edge.target);
-  });
-
-  // Render the diagram in memory getting hte X and Y
-  dagre.layout(flow);
-
-  return {
-    nodes: calculatedNodes(flow, nodes),
-    edges,
-  };
-};
diff --git a/eventcatalog/src/utils/node-graphs/domains-node-graph.ts b/eventcatalog/src/utils/node-graphs/domains-node-graph.ts
deleted file mode 100644
index 469f3ebe9..000000000
--- a/eventcatalog/src/utils/node-graphs/domains-node-graph.ts
+++ /dev/null
@@ -1,314 +0,0 @@
-import { getCollection } from 'astro:content';
-import {
-  createDagreGraph,
-  calculatedNodes,
-  generateIdForNode,
-  getEdgeLabelForServiceAsTarget,
-  generatedIdForEdge,
-  createEdge,
-} from '@utils/node-graphs/utils/utils';
-import { getNodesAndEdges as getServicesNodeAndEdges } from './services-node-graph';
-import merge from 'lodash.merge';
-import { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
-import type { Node } from '@xyflow/react';
-import { getProducersOfMessage } from '@utils/collections/services';
-
-type DagreGraph = any;
-
-interface Props {
-  defaultFlow?: DagreGraph;
-  channelRenderMode?: 'single' | 'flat';
-}
-
-export const getNodesAndEdgesForDomainContextMap = async ({ defaultFlow = null }: Props) => {
-  const flow = defaultFlow ?? createDagreGraph({ ranksep: 360, nodesep: 50, edgesep: 50 });
-  let nodes = [] as any,
-    edges = [] as any;
-
-  const allDomains = await getCollection('domains');
-  const domains = allDomains.filter((domain) => !domain.id.includes('/versioned'));
-  const services = await getCollection('services');
-
-  const events = await getCollection('events');
-  const commands = await getCollection('commands');
-  const queries = await getCollection('queries');
-
-  const messages = [...events, ...commands, ...queries];
-
-  domains.forEach((domain, index) => {
-    const nodeId = generateIdForNode(domain);
-    const rawServices = domain.data.services ?? [];
-    const domainServices = rawServices
-      .map((service) => getItemsFromCollectionByIdAndSemverOrLatest(services, service.id, service.version))
-      .flat()
-      .filter((e) => e !== undefined);
-
-    // Calculate domain node size based on services
-    const servicesCount = domainServices.length;
-    const SERVICES_PER_ROW = 1;
-    const SERVICE_WIDTH = 330;
-    const SERVICE_HEIGHT = 100;
-    const PADDING = 40;
-    const TITLE_HEIGHT = 20;
-
-    const rows = Math.ceil(servicesCount / SERVICES_PER_ROW);
-    const domainWidth = SERVICE_WIDTH * SERVICES_PER_ROW;
-    const domainHeight = SERVICE_HEIGHT * rows + PADDING * 4;
-
-    // Position domains in a grid layout
-    const DOMAINS_PER_ROW = 2;
-    const rowIndex = Math.floor(index / DOMAINS_PER_ROW);
-    const colIndex = index % DOMAINS_PER_ROW;
-
-    const test = servicesCount * SERVICE_HEIGHT + PADDING * 2;
-
-    nodes.push({
-      id: nodeId,
-      type: 'group',
-      position: {
-        x: colIndex * (domainWidth + 400), // Increased from 100 to 400px gap between domains
-        y: rowIndex * (domainHeight + 300), // Increased from 100 to 300px gap between rows
-      },
-      style: {
-        width: domainWidth,
-        height: domainHeight,
-        backgroundColor: 'transparent',
-        borderRadius: '8px',
-        border: '1px solid #ddd',
-        'box-shadow': '0 0 10px 0 rgba(0, 0, 0, 0.1)',
-      },
-      data: {
-        label: domain.data.name,
-        domain,
-      },
-    });
-
-    nodes.push({
-      id: `domain-context-map-title-${domain.data.name}`,
-      data: { label: `Bounded Context: ${domain.data.name}` },
-      position: { x: 0, y: 0 },
-      style: {
-        height: 40,
-        backgroundColor: 'transparent',
-        border: 'none',
-        color: 'black',
-        width: domainWidth,
-      },
-      extent: 'parent',
-      parentId: nodeId,
-      connectable: false,
-      sourcePosition: 'left',
-      targetPosition: 'right',
-      draggable: false,
-    } as Node);
-
-    // Position services in a grid within the domain
-    if (domainServices) {
-      domainServices.forEach((service, serviceIndex) => {
-        const row = Math.floor(serviceIndex / SERVICES_PER_ROW);
-        const col = serviceIndex % SERVICES_PER_ROW;
-        const serviceNodeId = `service-${domain.id}-${service.id}`;
-
-        // Add spacing between services
-        const SERVICE_MARGIN = 25;
-        const xPosition = PADDING + col * (SERVICE_WIDTH + SERVICE_MARGIN) + 20;
-        const yPosition = PADDING + row * (SERVICE_HEIGHT + SERVICE_MARGIN) + TITLE_HEIGHT;
-
-        nodes.push({
-          id: generateIdForNode(service),
-          sourcePosition: 'right',
-          targetPosition: 'left',
-          type: 'services',
-          position: {
-            x: xPosition,
-            y: yPosition,
-          },
-          parentId: nodeId,
-          extent: 'parent',
-          draggable: false,
-          data: {
-            mode: 'full',
-            service,
-          },
-        });
-
-        // Edges
-        const rawReceives = service.data.receives ?? [];
-        const rawSends = service.data.sends ?? [];
-
-        const receives = rawReceives
-          .map((receive) => getItemsFromCollectionByIdAndSemverOrLatest(messages, receive.id, receive.version))
-          .flat();
-        const sends = rawSends.map((send) => getItemsFromCollectionByIdAndSemverOrLatest(messages, send.id, send.version)).flat();
-
-        for (const receive of receives) {
-          const producers = getProducersOfMessage(services, receive);
-
-          for (const producer of producers) {
-            const isSameDomain = domainServices.some((domainService) => domainService.data.id === producer.data.id);
-
-            if (!isSameDomain) {
-              // WIP... adding messages?
-              // edges.push(createEdge({
-              //   id: generatedIdForEdge(receive, service),
-              //   source: generateIdForNode(receive),
-              //   target: generateIdForNode(service),
-              //   label: getEdgeLabelForServiceAsTarget(receive),
-              //   zIndex: 1000,
-              // }));
-
-              // Find the producer and consumer nodes to get their positions
-              // const producerNode = nodes.find(n => n.id === generateIdForNode(producer));
-              // const consumerNode = nodes.find(n => n.id === generateIdForNode(service));
-
-              edges.push(
-                createEdge({
-                  id: generatedIdForEdge(producer, service),
-                  source: generateIdForNode(producer),
-                  target: generateIdForNode(service),
-                  label: getEdgeLabelForServiceAsTarget(receive),
-                  zIndex: 1000,
-                })
-              );
-
-              // // Calculate middle position between producer and consumer
-              // const messageX = (producerNode?.position?.x ?? 0) +
-              //   ((consumerNode?.position?.x ?? 0) - (producerNode?.position?.x ?? 0)) / 2;
-              // const messageY = (producerNode?.position?.y ?? 0) +
-              //   ((consumerNode?.position?.y ?? 0) - (producerNode?.position?.y ?? 0)) / 2;
-
-              // nodes.push({
-              //   id: generateIdForNode(receive),
-              //   type: receive.collection,
-              //   sourcePosition: 'right',
-              //   targetPosition: 'left',
-              //   data: {
-              //     message: receive,
-              //     mode: 'full',
-              //   },
-              //   position: { x: messageX, y: messageY },
-              // });
-
-              // edges.push(createEdge({
-              //   id: generatedIdForEdge(producer, receive),
-              //   source: generateIdForNode(producer),
-              //   target: generateIdForNode(receive),
-              //   label: getEdgeLabelForServiceAsTarget(receive),
-              //   zIndex: 1000,
-              // }));
-            }
-          }
-        }
-      });
-    }
-  });
-
-  return {
-    nodes,
-    edges,
-  };
-};
-
-interface NodesAndEdgesProps {
-  id: string;
-  version: string;
-  defaultFlow?: DagreGraph;
-  mode: 'simple' | 'full';
-  group?: boolean;
-  channelRenderMode?: 'single' | 'flat';
-}
-
-export const getNodesAndEdges = async ({
-  id,
-  version,
-  defaultFlow,
-  mode = 'simple',
-  group = false,
-  channelRenderMode = 'flat',
-}: NodesAndEdgesProps) => {
-  const flow = defaultFlow || createDagreGraph({ ranksep: 360, nodesep: 50, edgesep: 50 });
-  let nodes = new Map(),
-    edges = new Map();
-
-  const domains = await getCollection('domains');
-
-  const domain = domains.find((service) => service.data.id === id && service.data.version === version);
-
-  // Nothing found...
-  if (!domain) {
-    return {
-      nodes: [],
-      edges: [],
-    };
-  }
-
-  const rawServices = domain?.data.services || [];
-  const rawSubDomains = domain?.data.domains || [];
-
-  const servicesCollection = await getCollection('services');
-
-  const domainServicesWithVersion = rawServices
-    .map((service) => getItemsFromCollectionByIdAndSemverOrLatest(servicesCollection, service.id, service.version))
-    .flat()
-    .map((svc) => ({ id: svc.data.id, version: svc.data.version }));
-
-  const domainSubDomainsWithVersion = rawSubDomains
-    .map((subDomain) => getItemsFromCollectionByIdAndSemverOrLatest(domains, subDomain.id, subDomain.version))
-    .flat()
-    .map((svc) => ({ id: svc.data.id, version: svc.data.version }));
-
-  // Get all the nodes for everyhing
-
-  for (const service of domainServicesWithVersion) {
-    const { nodes: serviceNodes, edges: serviceEdges } = await getServicesNodeAndEdges({
-      id: service.id,
-      version: service.version,
-      defaultFlow: flow,
-      mode,
-      renderAllEdges: true,
-      channelRenderMode,
-    });
-    serviceNodes.forEach((n) => {
-      /**
-       * A message could be sent by one service and received by another service on the same domain.
-       * So, we need deep merge the message to keep the `showSource` and `showTarget` as true.
-       *
-       * Let's see an example:
-       *  Take an `OrderPlaced` event sent by the `OrderService` `{ showSource: true }` and
-       *  received by `PaymentService` `{ showTarget: true }`.
-       */
-      nodes.set(n.id, nodes.has(n.id) ? merge(nodes.get(n.id), n) : n);
-    });
-    // @ts-ignore
-    serviceEdges.forEach((e) => edges.set(e.id, e));
-  }
-
-  for (const subDomain of domainSubDomainsWithVersion) {
-    const { nodes: subDomainNodes, edges: subDomainEdges } = await getNodesAndEdges({
-      id: subDomain.id,
-      version: subDomain.version,
-      defaultFlow: flow,
-      mode,
-      group: true,
-      channelRenderMode,
-    });
-    subDomainNodes.forEach((n) => {
-      nodes.set(n.id, nodes.has(n.id) ? merge(nodes.get(n.id), n) : n);
-    });
-
-    subDomainEdges.forEach((e) => edges.set(e.id, e));
-  }
-
-  // Add group node to the graph first before calculating positions
-  if (group) {
-    // Update the data of the node to add the group name and color
-    nodes.forEach((n) => {
-      nodes.set(n.id, { ...n, data: { ...n.data, group: { type: 'Domain', value: domain?.data.name, id: domain?.data.id } } });
-    });
-  }
-
-  return {
-    nodes: calculatedNodes(flow, Array.from(nodes.values())),
-    edges: [...edges.values()],
-  };
-};
diff --git a/eventcatalog/src/utils/node-graphs/export-node-graph.ts b/eventcatalog/src/utils/node-graphs/export-node-graph.ts
deleted file mode 100644
index a11427b9c..000000000
--- a/eventcatalog/src/utils/node-graphs/export-node-graph.ts
+++ /dev/null
@@ -1,87 +0,0 @@
-import type { ReactFlowInstance, Node, ReactFlowJsonObject, Edge } from '@xyflow/react';
-
-// Define the structure of resource data that can be found in nodes
-interface ResourceData {
-  id?: string;
-  name?: string;
-  summary?: string;
-  version?: string;
-}
-
-// Define the possible node data structure
-interface NodeDataWithResources {
-  [key: string]: any;
-  channel?: ResourceData;
-  custom?: ResourceData;
-  data?: ResourceData;
-  domain?: ResourceData;
-  entity?: ResourceData;
-  message?: ResourceData;
-  flow?: ResourceData;
-  service?: ResourceData;
-  step?: ResourceData;
-  user?: ResourceData;
-}
-
-export const exportNodeGraphForStudio = (data: ReactFlowJsonObject) => {
-  const dataTypes: (keyof NodeDataWithResources)[] = [
-    'channel',
-    'custom',
-    'data',
-    'domain',
-    'entity',
-    'message',
-    'flow',
-    'service',
-    'step',
-    'user',
-  ];
-
-  // try and remove unwanted data for studio
-  const nodes = data.nodes.map((node: Node) => {
-    let nodeData = node.data as NodeDataWithResources;
-    const dataProperties = Object.keys(nodeData) as (keyof NodeDataWithResources)[];
-
-    // If we find a match.....
-    const hasCustomDataType = dataProperties.find((property) => dataTypes.includes(property));
-
-    if (hasCustomDataType && nodeData[hasCustomDataType]) {
-      const resourceData = nodeData[hasCustomDataType] as ResourceData;
-      nodeData = {
-        ...nodeData,
-        [hasCustomDataType]: {
-          id: resourceData?.id,
-          name: resourceData?.name,
-          summary: resourceData?.summary,
-          version: resourceData?.version,
-        },
-      };
-    }
-
-    return {
-      ...node,
-      data: {
-        ...nodeData,
-        // We dont need these for studio
-        source: undefined,
-        target: undefined,
-        // Studio wants all nodes in full mode
-        mode: 'full',
-      },
-    };
-  });
-
-  const edges = data.edges.map((edge: Edge) => {
-    return {
-      ...edge,
-      data: undefined,
-      type: 'animatedMessage',
-    };
-  });
-
-  return {
-    ...data,
-    nodes,
-    edges,
-  };
-};
diff --git a/eventcatalog/src/utils/node-graphs/flows-node-graph.ts b/eventcatalog/src/utils/node-graphs/flows-node-graph.ts
deleted file mode 100644
index 3a5a39513..000000000
--- a/eventcatalog/src/utils/node-graphs/flows-node-graph.ts
+++ /dev/null
@@ -1,166 +0,0 @@
-import { getCollection, type CollectionEntry } from 'astro:content';
-import dagre from 'dagre';
-import { createDagreGraph, calculatedNodes } from '@utils/node-graphs/utils/utils';
-import { MarkerType } from '@xyflow/react';
-import type { Node as NodeType } from '@xyflow/react';
-import { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
-
-type DagreGraph = any;
-
-interface Props {
-  id: string;
-  version: string;
-  defaultFlow?: DagreGraph;
-  mode?: 'simple' | 'full';
-  renderAllEdges?: boolean;
-}
-
-const getServiceNode = (step: any, services: CollectionEntry<'services'>[]) => {
-  const servicesForVersion = getItemsFromCollectionByIdAndSemverOrLatest(services, step.service.id, step.service.version);
-  const service = servicesForVersion?.[0];
-  return {
-    ...step,
-    type: service ? service.collection : 'step',
-    service,
-  };
-};
-
-const getFlowNode = (step: any, flows: CollectionEntry<'flows'>[]) => {
-  const flowsForVersion = getItemsFromCollectionByIdAndSemverOrLatest(flows, step.flow.id, step.flow.version);
-  const flow = flowsForVersion?.[0];
-  return {
-    ...step,
-    type: flow ? flow.collection : 'step',
-    flow,
-  };
-};
-
-const getMessageNode = (step: any, messages: CollectionEntry<'events' | 'commands' | 'queries'>[]) => {
-  const messagesForVersion = getItemsFromCollectionByIdAndSemverOrLatest(messages, step.message.id, step.message.version);
-  const message = messagesForVersion[0];
-  return {
-    ...step,
-    type: message ? message.collection : 'step',
-    message,
-  };
-};
-
-export const getNodesAndEdges = async ({ id, defaultFlow, version, mode = 'simple', renderAllEdges = false }: Props) => {
-  const graph = defaultFlow || createDagreGraph({ ranksep: 360, nodesep: 200 });
-  const nodes = [] as any,
-    edges = [] as any;
-
-  const flows = await getCollection('flows');
-  const flow = flows.find((flow) => flow.data.id === id && flow.data.version === version);
-
-  // Nothing found...
-  if (!flow) {
-    return {
-      nodes: [],
-      edges: [],
-    };
-  }
-
-  const events = await getCollection('events');
-  const commands = await getCollection('commands');
-  const queries = await getCollection('queries');
-  const services = await getCollection('services');
-
-  const messages = [...events, ...commands, ...queries];
-
-  const steps = flow?.data.steps || [];
-
-  //  Hydrate the steps with information they may need.
-  const hydratedSteps = steps.map((step: any) => {
-    if (step.service) return getServiceNode(step, services);
-    if (step.flow) return getFlowNode(step, flows);
-    if (step.message) return getMessageNode(step, messages);
-    if (step.actor) return { ...step, type: 'actor', actor: step.actor };
-    if (step.custom) return { ...step, type: 'custom', custom: step.custom };
-    if (step.externalSystem) return { ...step, type: 'externalSystem', externalSystem: step.externalSystem };
-    return { ...step, type: 'step' };
-  });
-
-  // Create nodes
-  hydratedSteps.forEach((step: any, index: number) => {
-    const node = {
-      id: `step-${step.id}`,
-      sourcePosition: 'right',
-      targetPosition: 'left',
-      data: {
-        mode,
-        step: { ...step, ...step.data },
-        showTarget: true,
-        showSource: true,
-      },
-      position: { x: 250, y: index * 150 },
-      type: step.type,
-    } as NodeType;
-
-    if (step.service) node.data.service = { ...step.service, ...step.service.data };
-    if (step.flow) node.data.flow = { ...step.flow, ...step.flow.data };
-    if (step.message) node.data.message = { ...step.message, ...step.message.data };
-    if (step.actor) node.data.actor = { ...step.actor, ...step.actor.data };
-    if (step.externalSystem) node.data.externalSystem = { ...step.externalSystem, ...step.externalSystem.data };
-    if (step.custom) node.data.custom = { ...step.custom, ...step.custom.data };
-    nodes.push(node);
-  });
-
-  // Create Edges
-  hydratedSteps.forEach((step: any, index: number) => {
-    let paths = step.next_steps || [];
-
-    if (step.next_step) {
-      // If its a string or number
-      if (!step.next_step?.id) {
-        paths = [{ id: step.next_step }];
-      } else {
-        paths = [step.next_step];
-      }
-    }
-
-    paths = paths.map((path: any) => {
-      if (typeof path === 'string') {
-        return { id: path };
-      }
-      return path;
-    });
-
-    paths.forEach((path: any) => {
-      edges.push({
-        id: `step-${step.id}-step-${path.id}`,
-        source: `step-${step.id}`,
-        target: `step-${path.id}`,
-        type: 'flow-edge',
-        label: path.label,
-        animated: true,
-        markerEnd: {
-          type: MarkerType.ArrowClosed,
-          width: 20,
-          height: 20,
-          color: '#666',
-        },
-        style: {
-          strokeWidth: 2,
-          stroke: '#ccc',
-        },
-      });
-    });
-  });
-
-  nodes.forEach((node: any) => {
-    graph.setNode(node.id, { width: 150, height: 100 });
-  });
-
-  edges.forEach((edge: any) => {
-    graph.setEdge(edge.source, edge.target);
-  });
-
-  // Render the diagram in memory getting hte X and Y
-  dagre.layout(graph);
-
-  return {
-    nodes: calculatedNodes(graph, nodes),
-    edges: edges,
-  };
-};
diff --git a/eventcatalog/src/utils/node-graphs/message-node-graph.ts b/eventcatalog/src/utils/node-graphs/message-node-graph.ts
deleted file mode 100644
index cff002722..000000000
--- a/eventcatalog/src/utils/node-graphs/message-node-graph.ts
+++ /dev/null
@@ -1,1009 +0,0 @@
-// import { getColor } from '@utils/colors';
-import { getEvents } from '@utils/events';
-import type { CollectionEntry } from 'astro:content';
-import dagre from 'dagre';
-import {
-  calculatedNodes,
-  createDagreGraph,
-  createEdge,
-  generatedIdForEdge,
-  generateIdForNode,
-  getColorFromString,
-  getEdgeLabelForMessageAsSource,
-  getEdgeLabelForServiceAsTarget,
-} from './utils/utils';
-import { MarkerType, type Node, type Edge } from '@xyflow/react';
-import {
-  findMatchingNodes,
-  getItemsFromCollectionByIdAndSemverOrLatest,
-  getLatestVersionInCollectionById,
-} from '@utils/collections/util';
-import type { CollectionMessageTypes } from '@types';
-import { getCommands } from '@utils/commands';
-import { getQueries } from '@utils/queries';
-import { createNode } from './utils/utils';
-import { getConsumersOfMessage, getProducersOfMessage } from '@utils/collections/services';
-import { getNodesAndEdgesForChannelChain } from './channel-node-graph';
-import { getChannelChain, isChannelsConnected } from '@utils/channels';
-import { getChannels } from '@utils/channels';
-
-type DagreGraph = any;
-
-interface Props {
-  id: string;
-  version: string;
-  defaultFlow?: DagreGraph;
-  mode?: 'simple' | 'full';
-  channelRenderMode?: 'flat' | 'single';
-  collection?: CollectionEntry<CollectionMessageTypes>[];
-  channels?: CollectionEntry<'channels'>[];
-}
-
-const getNodesAndEdges = async ({
-  id,
-  version,
-  defaultFlow,
-  mode = 'simple',
-  channelRenderMode = 'flat',
-  collection = [],
-  channels = [],
-}: Props) => {
-  const flow = defaultFlow || createDagreGraph({ ranksep: 300, nodesep: 50 });
-  const nodes = [] as any,
-    edges = [] as any;
-
-  const message = collection.find((message) => {
-    return message.data.id === id && message.data.version === version;
-  });
-
-  // Nothing found...
-  if (!message) {
-    return {
-      nodes: [],
-      edges: [],
-    };
-  }
-
-  // We always render the message itself
-  nodes.push({
-    id: generateIdForNode(message),
-    sourcePosition: 'right',
-    targetPosition: 'left',
-    data: {
-      mode,
-      message: {
-        ...message.data,
-      },
-    },
-    position: { x: 0, y: 0 },
-    type: message.collection,
-  });
-
-  const producers = (message.data.producers as CollectionEntry<'services'>[]) || [];
-  const consumers = (message.data.consumers as CollectionEntry<'services'>[]) || [];
-
-  // Track nodes that are both sent and received
-  const bothSentAndReceived = findMatchingNodes(producers, consumers);
-
-  for (const producer of producers) {
-    // Create the producer node
-    nodes.push({
-      id: generateIdForNode(producer),
-      type: producer?.collection,
-      sourcePosition: 'right',
-      targetPosition: 'left',
-      data: { mode, service: { ...producer.data } },
-      position: { x: 250, y: 0 },
-    });
-
-    // Is the producer sending this message to a channel?
-    const producerConfigurationForMessage = producer.data.sends?.find((send) => send.id === message.data.id);
-    const producerChannelConfiguration = producerConfigurationForMessage?.to ?? [];
-
-    const producerHasChannels = producerChannelConfiguration?.length > 0;
-
-    const rootSourceAndTarget = {
-      source: { id: generateIdForNode(producer), collection: producer.collection },
-      target: { id: generateIdForNode(message), collection: message.collection },
-    };
-
-    // If the producer does not have any channels defined, then we just connect the producer to the event directly
-    if (!producerHasChannels) {
-      edges.push({
-        id: generatedIdForEdge(producer, message),
-        source: generateIdForNode(producer),
-        target: generateIdForNode(message),
-        label: getEdgeLabelForServiceAsTarget(message),
-        data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-        animated: false,
-        markerEnd: {
-          type: MarkerType.ArrowClosed,
-          width: 40,
-          height: 40,
-        },
-      });
-      continue;
-    }
-
-    // If the producer has channels defined, we need to render them
-    for (const producerChannel of producerChannelConfiguration) {
-      const channel = getItemsFromCollectionByIdAndSemverOrLatest(
-        channels,
-        producerChannel.id,
-        producerChannel.version
-      )[0] as CollectionEntry<'channels'>;
-
-      // If we cannot find the channel in EventCatalog, we just connect the producer to the event directly
-      if (!channel) {
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(producer, message),
-            source: generateIdForNode(producer),
-            target: generateIdForNode(message),
-            label: getEdgeLabelForMessageAsSource(message),
-            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-          })
-        );
-        continue;
-      }
-
-      // We render the channel node
-      nodes.push(
-        createNode({
-          id: generateIdForNode(channel),
-          type: channel.collection,
-          data: { mode, channel: { ...channel.data } },
-          position: { x: 0, y: 0 },
-        })
-      );
-
-      // Connect the producer to the message
-      edges.push(
-        createEdge({
-          id: generatedIdForEdge(producer, message),
-          source: generateIdForNode(producer),
-          target: generateIdForNode(message),
-          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-          label: getEdgeLabelForServiceAsTarget(message),
-        })
-      );
-
-      // Connect the message to the channel
-      edges.push(
-        createEdge({
-          id: generatedIdForEdge(message, channel),
-          source: generateIdForNode(message),
-          target: generateIdForNode(channel),
-          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-          label: 'routes to',
-        })
-      );
-    }
-  }
-
-  // The messages the service sends
-  for (const consumer of consumers) {
-    // Render the consumer node
-    nodes.push({
-      id: generateIdForNode(consumer),
-      sourcePosition: 'right',
-      targetPosition: 'left',
-      data: { title: consumer?.data.id, mode, service: { ...consumer.data } },
-      position: { x: 0, y: 0 },
-      type: consumer?.collection,
-    });
-
-    // Is the consumer receiving this message from a channel?
-    const consumerConfigurationForMessage = consumer.data.receives?.find((receive) => receive.id === message.data.id);
-    const consumerChannelConfiguration = consumerConfigurationForMessage?.from ?? [];
-
-    const consumerHasChannels = consumerChannelConfiguration.length > 0;
-
-    const rootSourceAndTarget = {
-      source: { id: generateIdForNode(message), collection: message.collection },
-      target: { id: generateIdForNode(consumer), collection: consumer.collection },
-    };
-
-    // If the consumer does not have any channels defined, connect the consumer to the event directly
-    if (!consumerHasChannels) {
-      edges.push(
-        createEdge({
-          id: generatedIdForEdge(message, consumer),
-          source: generateIdForNode(message),
-          target: generateIdForNode(consumer),
-          label: getEdgeLabelForMessageAsSource(message),
-          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-        })
-      );
-    }
-
-    // If the consumer has channels defined, we try and render them
-    for (const consumerChannel of consumerChannelConfiguration) {
-      const channel = getItemsFromCollectionByIdAndSemverOrLatest(
-        channels,
-        consumerChannel.id,
-        consumerChannel.version
-      )[0] as CollectionEntry<'channels'>;
-
-      // If we cannot find the channel in EventCatalog, we connect the message directly to the consumer
-      if (!channel) {
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(message, consumer),
-            source: generateIdForNode(message),
-            target: generateIdForNode(consumer),
-            label: getEdgeLabelForMessageAsSource(message),
-            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-          })
-        );
-        continue;
-      }
-
-      // Can any of the consumer channels be linked to any of the producer channels?
-      const producerChannels = producers
-        .map((producer) => producer.data.sends?.find((send) => send.id === message.data.id)?.to ?? [])
-        .flat();
-      const consumerChannels = consumer.data.receives?.find((receive) => receive.id === message.data.id)?.from ?? [];
-
-      for (const producerChannel of producerChannels) {
-        const producerChannelValue = getItemsFromCollectionByIdAndSemverOrLatest(
-          channels,
-          producerChannel.id,
-          producerChannel.version
-        )[0] as CollectionEntry<'channels'>;
-
-        for (const consumerChannel of consumerChannels) {
-          const consumerChannelValue = getItemsFromCollectionByIdAndSemverOrLatest(
-            channels,
-            consumerChannel.id,
-            consumerChannel.version
-          )[0] as CollectionEntry<'channels'>;
-          const channelChainToRender = getChannelChain(producerChannelValue, consumerChannelValue, channels);
-
-          // If there is a chain between them we need to render them al
-          if (channelChainToRender.length > 0) {
-            const { nodes: channelNodes, edges: channelEdges } = getNodesAndEdgesForChannelChain({
-              source: message,
-              target: consumer,
-              channelChain: channelChainToRender,
-              mode,
-            });
-
-            nodes.push(...channelNodes);
-            edges.push(...channelEdges);
-          } else {
-            // There is no chain found, we need to render the channel between message and the consumers
-            nodes.push(
-              createNode({
-                id: generateIdForNode(channel),
-                type: channel.collection,
-                data: { mode, channel: { ...channel.data } },
-                position: { x: 0, y: 0 },
-              })
-            );
-            edges.push(
-              createEdge({
-                id: generatedIdForEdge(message, channel),
-                source: generateIdForNode(message),
-                target: generateIdForNode(channel),
-                label: 'routes to',
-                data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-              })
-            );
-            edges.push(
-              createEdge({
-                id: generatedIdForEdge(channel, consumer),
-                source: generateIdForNode(channel),
-                target: generateIdForNode(consumer),
-                label: getEdgeLabelForMessageAsSource(message),
-                data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-              })
-            );
-          }
-        }
-      }
-
-      // If producer does not have a any channels defined, we need to connect the message to the consumer directly
-      if (producerChannels.length === 0 && channel) {
-        // Create the channel node
-        nodes.push(
-          createNode({
-            id: generateIdForNode(channel),
-            type: channel.collection,
-            data: { mode, channel: { ...channel.data } },
-            position: { x: 0, y: 0 },
-          })
-        );
-
-        // Connect the message to the channel
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(message, channel),
-            source: generateIdForNode(message),
-            target: generateIdForNode(channel),
-            label: 'routes to',
-            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-          })
-        );
-
-        // Connect the channel to the consumer
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(channel, consumer),
-            source: generateIdForNode(channel),
-            target: generateIdForNode(consumer),
-            label: getEdgeLabelForMessageAsSource(message),
-            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-          })
-        );
-      }
-    }
-  }
-
-  // Handle messages that are both sent and received
-  bothSentAndReceived.forEach((_message) => {
-    if (message) {
-      edges.push(
-        createEdge({
-          id: generatedIdForEdge(message, _message) + '-both',
-          source: generateIdForNode(message),
-          target: generateIdForNode(_message),
-          label: 'publishes and subscribes',
-          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget: { source: message, target: _message } },
-        })
-      );
-    }
-  });
-
-  nodes.forEach((node: any) => {
-    flow.setNode(node.id, { width: 150, height: 100 });
-  });
-
-  edges.forEach((edge: any) => {
-    flow.setEdge(edge.source, edge.target);
-  });
-
-  // Render the diagram in memory getting hte X and Y
-  dagre.layout(flow);
-
-  return {
-    nodes: calculatedNodes(flow, nodes),
-    edges,
-  };
-};
-
-export const getNodesAndEdgesForQueries = async ({
-  id,
-  version,
-  defaultFlow,
-  mode = 'simple',
-  channelRenderMode = 'flat',
-}: Props) => {
-  const queries = await getQueries();
-  const channels = await getChannels();
-  return getNodesAndEdges({ id, version, defaultFlow, mode, channelRenderMode, collection: queries, channels });
-};
-
-export const getNodesAndEdgesForCommands = async ({
-  id,
-  version,
-  defaultFlow,
-  mode = 'simple',
-  channelRenderMode = 'flat',
-}: Props) => {
-  const commands = await getCommands();
-  const channels = await getChannels();
-  return getNodesAndEdges({ id, version, defaultFlow, mode, channelRenderMode, collection: commands, channels });
-};
-
-export const getNodesAndEdgesForEvents = async ({
-  id,
-  version,
-  defaultFlow,
-  mode = 'simple',
-  channelRenderMode = 'flat',
-}: Props) => {
-  const events = await getEvents();
-  const channels = await getChannels();
-  return getNodesAndEdges({ id, version, defaultFlow, mode, channelRenderMode, collection: events, channels });
-};
-
-export const getNodesAndEdgesForConsumedMessage = ({
-  message,
-  targetChannels = [],
-  services,
-  channels,
-  currentNodes = [],
-  target,
-  mode = 'simple',
-}: {
-  message: CollectionEntry<CollectionMessageTypes>;
-  targetChannels?: { id: string; version: string }[];
-  services: CollectionEntry<'services'>[];
-  channels: CollectionEntry<'channels'>[];
-  currentNodes: Node[];
-  target: CollectionEntry<'services'>;
-  mode?: 'simple' | 'full';
-}) => {
-  let nodes = [] as Node[],
-    edges = [] as any;
-
-  const messageId = generateIdForNode(message);
-
-  const rootSourceAndTarget = {
-    source: { id: generateIdForNode(message), collection: message.collection },
-    target: { id: generateIdForNode(target), collection: target.collection },
-  };
-
-  // Render the message node
-  nodes.push(
-    createNode({
-      id: messageId,
-      type: message.collection,
-      data: { mode, message: { ...message.data } },
-      position: { x: 0, y: 0 },
-    })
-  );
-
-  // Render the target node
-  nodes.push(
-    createNode({
-      id: generateIdForNode(target),
-      type: target.collection,
-      data: { mode, service: { ...target.data } },
-      position: { x: 0, y: 0 },
-    })
-  );
-
-  const targetMessageConfiguration = target.data.receives?.find((receive) => receive.id === message.data.id);
-  const channelsFromMessageToTarget = targetMessageConfiguration?.from ?? [];
-  const hydratedChannelsFromMessageToTarget = channelsFromMessageToTarget
-    .map((channel) => getItemsFromCollectionByIdAndSemverOrLatest(channels, channel.id, channel.version)[0])
-    .filter((channel) => channel !== undefined);
-
-  // Now we get the producers of the message and create nodes and edges for them
-  const producers = getProducersOfMessage(services, message);
-
-  const hasProducers = producers.length > 0;
-  const targetHasDefinedChannels = targetChannels.length > 0;
-
-  const isMessageEvent = message.collection === 'events';
-
-  // Warning edge if no producers or target channels are defined
-  if (!hasProducers && !targetHasDefinedChannels) {
-    edges.push(
-      createEdge({
-        id: generatedIdForEdge(message, target) + '-warning',
-        source: messageId,
-        target: generateIdForNode(target),
-        label: getEdgeLabelForMessageAsSource(message),
-        data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-      })
-    );
-  }
-
-  // If the target defined channels they consume the message from, we need to create the channel nodes and edges
-  if (targetHasDefinedChannels) {
-    for (const targetChannel of targetChannels) {
-      const channel = getItemsFromCollectionByIdAndSemverOrLatest(
-        channels,
-        targetChannel.id,
-        targetChannel.version
-      )[0] as CollectionEntry<'channels'>;
-
-      if (!channel) {
-        // No channe found, we just connect the message to the target directly
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(message, target),
-            source: messageId,
-            target: generateIdForNode(target),
-            label: getEdgeLabelForMessageAsSource(message),
-            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-          })
-        );
-        continue;
-      }
-
-      const channelId = generateIdForNode(channel);
-
-      // Create the channel node
-      nodes.push(
-        createNode({
-          id: channelId,
-          type: channel.collection,
-          data: { mode, channel: { ...channel.data, ...channel, id: channel.data.id } },
-          position: { x: 0, y: 0 },
-        })
-      );
-
-      // Connect the channel to the target
-      edges.push(
-        createEdge({
-          id: generatedIdForEdge(channel, target),
-          source: channelId,
-          target: generateIdForNode(target),
-          label: getEdgeLabelForMessageAsSource(message),
-          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-        })
-      );
-
-      // If we dont have any producers, we will connect the message to the channel directly
-      if (producers.length === 0) {
-        const isEvent = message.collection === 'events';
-
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(message, channel),
-            source: messageId,
-            target: channelId,
-            label: 'routes to',
-            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-          })
-        );
-      }
-    }
-  }
-
-  // Process the producers for the message
-  for (const producer of producers) {
-    const producerId = generateIdForNode(producer);
-
-    // Create the producer node
-    nodes.push(
-      createNode({
-        id: producerId,
-        type: producer.collection,
-        data: { mode, service: { ...producer.data } },
-        position: { x: 0, y: 0 },
-      })
-    );
-
-    // The message is always connected directly to the producer
-    edges.push(
-      createEdge({
-        id: generatedIdForEdge(producer, message),
-        source: producerId,
-        target: messageId,
-        label: getEdgeLabelForServiceAsTarget(message),
-        data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-      })
-    );
-
-    // Check if the producer is sending the message to a channel
-    const producerConfigurationForMessage = producer.data.sends?.find((send) => send.id === message.data.id);
-    const producerChannelConfiguration = producerConfigurationForMessage?.to ?? [];
-
-    const producerHasChannels = producerChannelConfiguration.length > 0;
-    const targetHasChannels = hydratedChannelsFromMessageToTarget.length > 0;
-
-    // If the producer or target (consumer) has no channels defined, we just connect the message to the consumer directly
-    // of the target has no channels defined, we just connect the message to the target directly
-    if ((!producerHasChannels && !targetHasChannels) || !targetHasChannels) {
-      edges.push(
-        createEdge({
-          id: generatedIdForEdge(message, target),
-          source: messageId,
-          target: generateIdForNode(target),
-          label: getEdgeLabelForMessageAsSource(message),
-          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-        })
-      );
-      continue;
-    }
-
-    // If the target has channels but the producer does not
-    // We then connect the message to the channels directly
-    if (targetHasChannels && !producerHasChannels) {
-      for (const targetChannel of hydratedChannelsFromMessageToTarget) {
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(message, targetChannel),
-            source: messageId,
-            target: generateIdForNode(targetChannel),
-            label: 'routes to',
-            data: {
-              customColor: getColorFromString(message.data.id),
-              rootSourceAndTarget: {
-                source: { id: generateIdForNode(message), collection: message.collection },
-                target: { id: generateIdForNode(target), collection: target.collection },
-              },
-            },
-          })
-        );
-      }
-      continue;
-    }
-
-    // Process each producer channel configuration
-    for (const producerChannel of producerChannelConfiguration) {
-      const channel = getItemsFromCollectionByIdAndSemverOrLatest(
-        channels,
-        producerChannel.id,
-        producerChannel.version
-      )[0] as CollectionEntry<'channels'>;
-
-      // If we cannot find the channel in EventCatalog, we just connect the message to the target directly
-      if (!channel) {
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(message, target),
-            source: messageId,
-            target: generateIdForNode(target),
-            label: getEdgeLabelForMessageAsSource(message),
-            data: {
-              customColor: getColorFromString(message.data.id),
-              rootSourceAndTarget: {
-                source: { id: generateIdForNode(message), collection: message.collection },
-                target: { id: generateIdForNode(target), collection: target.collection },
-              },
-            },
-          })
-        );
-        continue;
-      }
-
-      // Does the producer have any channels defined? If not, we just connect the message to the target directly
-      if (!producerHasChannels) {
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(message, target),
-            source: messageId,
-            target: generateIdForNode(target),
-            label: getEdgeLabelForMessageAsSource(message),
-            data: {
-              customColor: getColorFromString(message.data.id),
-              rootSourceAndTarget: {
-                source: { id: generateIdForNode(message), collection: message.collection },
-                target: { id: generateIdForNode(target), collection: target.collection },
-              },
-            },
-          })
-        );
-        continue;
-      }
-
-      // The producer does have channels defined, we need to try and work out the path the message takes to the target
-      for (const targetChannel of hydratedChannelsFromMessageToTarget) {
-        const channelChainToRender = getChannelChain(channel, targetChannel, channels);
-        if (channelChainToRender.length > 0) {
-          const { nodes: channelNodes, edges: channelEdges } = getNodesAndEdgesForChannelChain({
-            source: message,
-            target: target,
-            channelChain: channelChainToRender,
-            mode,
-          });
-
-          nodes.push(...channelNodes);
-          edges.push(...channelEdges);
-
-          break;
-        } else {
-          // No chain found create the channel, and connect the message to the target channel directly
-          nodes.push(
-            createNode({
-              id: generateIdForNode(targetChannel),
-              type: targetChannel.collection,
-              data: { mode, channel: { ...targetChannel.data, ...targetChannel } },
-              position: { x: 0, y: 0 },
-            })
-          );
-          edges.push(
-            createEdge({
-              id: generatedIdForEdge(message, targetChannel),
-              source: messageId,
-              target: generateIdForNode(targetChannel),
-              label: 'routes to',
-              data: {
-                rootSourceAndTarget: {
-                  source: { id: generateIdForNode(message), collection: message.collection },
-                  target: { id: generateIdForNode(targetChannel), collection: targetChannel.collection },
-                },
-              },
-            })
-          );
-        }
-      }
-    }
-  }
-
-  // Remove any nodes that are already in the current nodes (already on the UI)
-  nodes = nodes.filter((node) => !currentNodes.find((n) => n.id === node.id));
-
-  //  Make sure all nodes are unique
-  const uniqueNodes = nodes.filter((node, index, self) => index === self.findIndex((t) => t.id === node.id));
-
-  const uniqueEdges = edges.filter(
-    (edge: any, index: number, self: any[]) => index === self.findIndex((t: any) => t.id === edge.id)
-  );
-
-  return { nodes: uniqueNodes, edges: uniqueEdges };
-};
-
-export const getNodesAndEdgesForProducedMessage = ({
-  message,
-  sourceChannels,
-  services,
-  channels,
-  currentNodes = [],
-  currentEdges = [],
-  source,
-  mode = 'simple',
-}: {
-  message: CollectionEntry<CollectionMessageTypes>;
-  sourceChannels?: { id: string; version: string }[];
-  services: CollectionEntry<'services'>[];
-  channels: CollectionEntry<'channels'>[];
-  currentNodes: Node[];
-  currentEdges: Edge[];
-  source: CollectionEntry<'services'>;
-  mode?: 'simple' | 'full';
-}) => {
-  let nodes = [] as Node[],
-    edges = [] as any;
-
-  const messageId = generateIdForNode(message);
-
-  const rootSourceAndTarget = {
-    source: { id: generateIdForNode(source), collection: source.collection },
-    target: { id: generateIdForNode(message), collection: message.collection },
-  };
-
-  // Render the message node
-  nodes.push(
-    createNode({
-      id: messageId,
-      type: message.collection,
-      data: { mode, message: { ...message.data } },
-      position: { x: 0, y: 0 },
-    })
-  );
-
-  // Render the producer node
-  nodes.push(
-    createNode({
-      id: generateIdForNode(source),
-      type: source.collection,
-      data: { mode, service: { ...source.data } },
-      position: { x: 0, y: 0 },
-    })
-  );
-
-  // Render the edge from the producer to the message
-  edges.push(
-    createEdge({
-      id: generatedIdForEdge(source, message),
-      source: generateIdForNode(source),
-      target: messageId,
-      label: getEdgeLabelForServiceAsTarget(message),
-      data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-    })
-  );
-
-  const sourceMessageConfiguration = source.data.sends?.find((send) => send.id === message.data.id);
-  const channelsFromSourceToMessage = sourceMessageConfiguration?.to ?? [];
-
-  const hydratedChannelsFromSourceToMessage = channelsFromSourceToMessage
-    .map((channel) => getItemsFromCollectionByIdAndSemverOrLatest(channels, channel.id, channel.version)[0])
-    .filter((channel) => channel !== undefined);
-
-  // If the source defined channels they send the message to, we need to create the channel nodes and edges
-  if (sourceChannels && sourceChannels.length > 0) {
-    for (const sourceChannel of sourceChannels) {
-      const channel = getItemsFromCollectionByIdAndSemverOrLatest(
-        channels,
-        sourceChannel.id,
-        sourceChannel.version
-      )[0] as CollectionEntry<'channels'>;
-
-      if (!channel) {
-        // No channel found, we just connect the message to the source directly
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(message, source),
-            source: messageId,
-            target: generateIdForNode(source),
-            label: getEdgeLabelForMessageAsSource(message),
-            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-          })
-        );
-        continue;
-      }
-
-      const channelId = generateIdForNode(channel);
-
-      // Create the channel node
-      nodes.push(
-        createNode({
-          id: channelId,
-          type: channel.collection,
-          data: { mode, channel: { ...channel.data, ...channel, mode, id: channel.data.id } },
-          position: { x: 0, y: 0 },
-        })
-      );
-
-      // Connect the produced message to the channel
-      edges.push(
-        createEdge({
-          id: generatedIdForEdge(message, channel),
-          source: messageId,
-          target: channelId,
-          label: 'routes to',
-          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-        })
-      );
-    }
-  }
-
-  // Now we get the producers of the message and create nodes and edges for them
-  const consumers = getConsumersOfMessage(services, message);
-
-  // TODO: Make this a UI Switch in the future....
-  const latestConsumers = consumers.filter(
-    (consumer) => getLatestVersionInCollectionById(services, consumer.data.id) === consumer.data.version
-  );
-
-  // Process the consumers for the message
-  for (const consumer of latestConsumers) {
-    const consumerId = generateIdForNode(consumer);
-
-    // Create the consumer node
-    nodes.push(
-      createNode({
-        id: consumerId,
-        type: consumer.collection,
-        data: { mode, service: { ...consumer.data } },
-        position: { x: 0, y: 0 },
-      })
-    );
-
-    // Check if the consumer is consuming the message from a channel
-    const consumerConfigurationForMessage = consumer.data.receives?.find((receive) => receive.id === message.data.id);
-    const consumerChannelConfiguration = consumerConfigurationForMessage?.from ?? [];
-
-    const consumerHasChannels = consumerChannelConfiguration.length > 0;
-    const producerHasChannels = hydratedChannelsFromSourceToMessage.length > 0;
-
-    // If the consumer and producer have no channels defined,
-    // or the consumer has no channels defined, we just connect the message to the consumer directly
-    if ((!consumerHasChannels && !producerHasChannels) || !consumerHasChannels) {
-      edges.push(
-        createEdge({
-          id: generatedIdForEdge(message, consumer),
-          source: messageId,
-          target: consumerId,
-          label: getEdgeLabelForMessageAsSource(message),
-          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
-        })
-      );
-      continue;
-    }
-
-    // Process each consumer channel configuration
-    for (const consumerChannel of consumerChannelConfiguration) {
-      const channel = getItemsFromCollectionByIdAndSemverOrLatest(
-        channels,
-        consumerChannel.id,
-        consumerChannel.version
-      )[0] as CollectionEntry<'channels'>;
-
-      const edgeProps = { customColor: getColorFromString(message.data.id), rootSourceAndTarget };
-
-      // If the channel cannot be found in EventCatalog, we just connect the message to the consumer directly
-      // as a fallback, rather than just an empty node floating around
-      if (!channel) {
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(message, consumer),
-            source: messageId,
-            target: consumerId,
-            label: 'consumes',
-            data: edgeProps,
-          })
-        );
-        continue;
-      }
-
-      // We always add the consumer channel to be rendered
-      nodes.push(
-        createNode({
-          id: generateIdForNode(channel),
-          type: channel.collection,
-          data: { mode, channel: { ...channel.data, ...channel } },
-          position: { x: 0, y: 0 },
-        })
-      );
-
-      // If the producer does not have any channels defined, we connect the message to the consumers channel directly
-      if (!producerHasChannels) {
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(message, channel),
-            source: messageId,
-            target: generateIdForNode(channel),
-            label: 'routes to',
-            data: edgeProps,
-          })
-        );
-        edges.push(
-          createEdge({
-            id: generatedIdForEdge(channel, consumer),
-            source: generateIdForNode(channel),
-            target: generateIdForNode(consumer),
-            label: getEdgeLabelForMessageAsSource(message),
-            data: {
-              ...edgeProps,
-              rootSourceAndTarget: {
-                source: { id: generateIdForNode(message), collection: message.collection },
-                target: { id: generateIdForNode(consumer), collection: consumer.collection },
-              },
-            },
-          })
-        );
-        continue;
-      }
-
-      // The producer has channels defined, we need to try and work out the path the message takes to the consumer
-      for (const sourceChannel of hydratedChannelsFromSourceToMessage) {
-        const channelChainToRender = getChannelChain(sourceChannel, channel, channels);
-
-        if (channelChainToRender.length > 0) {
-          const { nodes: channelNodes, edges: channelEdges } = getNodesAndEdgesForChannelChain({
-            source: message,
-            target: consumer,
-            channelChain: channelChainToRender,
-            mode,
-          });
-
-          nodes.push(...channelNodes);
-          edges.push(...channelEdges);
-        } else {
-          // No chain found, we need to connect to the message to the channel
-          // And the channel to the consumer
-          edges.push(
-            createEdge({
-              id: generatedIdForEdge(message, channel),
-              source: messageId,
-              target: generateIdForNode(channel),
-              label: 'routes to',
-              data: {
-                ...edgeProps,
-                rootSourceAndTarget: {
-                  source: { id: generateIdForNode(message), collection: message.collection },
-                  target: { id: generateIdForNode(consumer), collection: consumer.collection },
-                },
-              },
-            })
-          );
-          edges.push(
-            createEdge({
-              id: generatedIdForEdge(channel, consumer),
-              source: generateIdForNode(channel),
-              target: generateIdForNode(consumer),
-              label: `${getEdgeLabelForMessageAsSource(message, true)} \n ${message.data.name}`,
-              data: {
-                ...edgeProps,
-                rootSourceAndTarget: {
-                  source: { id: generateIdForNode(message), collection: message.collection },
-                  target: { id: generateIdForNode(consumer), collection: consumer.collection },
-                },
-              },
-            })
-          );
-        }
-      }
-    }
-  }
-
-  // Remove any nodes that are already in the current nodes (already on the UI)
-  nodes = nodes.filter((node) => !currentNodes.find((n) => n.id === node.id));
-
-  //  Make sure all nodes are unique
-  const uniqueNodes = nodes.filter((node, index, self) => index === self.findIndex((t) => t.id === node.id));
-
-  const uniqueEdges = edges.filter(
-    (edge: any, index: number, self: any[]) => index === self.findIndex((t: any) => t.id === edge.id)
-  );
-
-  return { nodes: uniqueNodes, edges: uniqueEdges };
-};
diff --git a/eventcatalog/src/utils/node-graphs/services-node-graph.ts b/eventcatalog/src/utils/node-graphs/services-node-graph.ts
deleted file mode 100644
index a01ce1d1a..000000000
--- a/eventcatalog/src/utils/node-graphs/services-node-graph.ts
+++ /dev/null
@@ -1,308 +0,0 @@
-import { getCollection, type CollectionEntry } from 'astro:content';
-import dagre from 'dagre';
-import {
-  createDagreGraph,
-  generateIdForNode,
-  generatedIdForEdge,
-  calculatedNodes,
-  createEdge,
-} from '@utils/node-graphs/utils/utils';
-
-import { findMatchingNodes, getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
-import { MarkerType } from '@xyflow/react';
-import type { CollectionMessageTypes } from '@types';
-import { getNodesAndEdgesForConsumedMessage, getNodesAndEdgesForProducedMessage } from './message-node-graph';
-
-type DagreGraph = any;
-
-interface Props {
-  id: string;
-  version: string;
-  defaultFlow?: DagreGraph;
-  mode?: 'simple' | 'full';
-  renderAllEdges?: boolean;
-  channelRenderMode?: 'single' | 'flat';
-  renderMessages?: boolean;
-}
-
-const getSendsMessageByMessageType = (messageType: string) => {
-  switch (messageType) {
-    case 'events':
-      return 'publishes event';
-    case 'commands':
-      return 'invokes command';
-    case 'queries':
-      return 'requests';
-    default:
-      return 'invokes message';
-  }
-};
-
-const getReceivesMessageByMessageType = (messageType: string) => {
-  switch (messageType) {
-    case 'events':
-      return 'receives event';
-    case 'commands':
-    case 'queries':
-      return 'accepts';
-    default:
-      return 'accepts message';
-  }
-};
-
-export const getNodesAndEdges = async ({
-  id,
-  defaultFlow,
-  version,
-  mode = 'simple',
-  renderAllEdges = false,
-  channelRenderMode = 'flat',
-  renderMessages = true,
-}: Props) => {
-  const flow = defaultFlow || createDagreGraph({ ranksep: 300, nodesep: 50 });
-  let nodes = [] as any,
-    edges = [] as any;
-
-  const services = await getCollection('services');
-
-  const service = services.find((service) => service.data.id === id && service.data.version === version);
-
-  // Nothing found...
-  if (!service) {
-    return {
-      nodes: [],
-      edges: [],
-    };
-  }
-
-  const receivesRaw = service?.data.receives || [];
-  const sendsRaw = service?.data.sends || [];
-  const writesToRaw = service?.data.writesTo || [];
-  const readsFromRaw = service?.data.readsFrom || [];
-
-  const events = await getCollection('events');
-  const commands = await getCollection('commands');
-  const queries = await getCollection('queries');
-  const channels = await getCollection('channels');
-  const containers = await getCollection('containers');
-
-  const messages = [...events, ...commands, ...queries];
-
-  const receivesHydrated = receivesRaw
-    .map((message) => getItemsFromCollectionByIdAndSemverOrLatest(messages, message.id, message.version))
-    .flat()
-    .filter((e) => e !== undefined);
-
-  const sendsHydrated = sendsRaw
-    .map((message) => getItemsFromCollectionByIdAndSemverOrLatest(messages, message.id, message.version))
-    .flat()
-    .filter((e) => e !== undefined);
-
-  const writesToHydrated = writesToRaw
-    .map((container) => getItemsFromCollectionByIdAndSemverOrLatest(containers, container.id, container.version))
-    .flat()
-    .filter((e) => e !== undefined);
-
-  const readsFromHydrated = readsFromRaw
-    .map((container) => getItemsFromCollectionByIdAndSemverOrLatest(containers, container.id, container.version))
-    .flat()
-    .filter((e) => e !== undefined);
-
-  const receives = (receivesHydrated as CollectionEntry<CollectionMessageTypes>[]) || [];
-  const sends = (sendsHydrated as CollectionEntry<CollectionMessageTypes>[]) || [];
-  const writesTo = (writesToHydrated as CollectionEntry<'containers'>[]) || [];
-  const readsFrom = (readsFromHydrated as CollectionEntry<'containers'>[]) || [];
-
-  // Track messages that are both sent and received
-  const bothSentAndReceived = findMatchingNodes(receives, sends);
-  const bothReadsAndWrites = findMatchingNodes(readsFrom, writesTo);
-
-  if (renderMessages) {
-    // All the messages the service receives
-    receives.forEach((receive) => {
-      const targetChannels = receivesRaw.find((receiveRaw) => receiveRaw.id === receive.data.id)?.from;
-
-      const { nodes: consumedMessageNodes, edges: consumedMessageEdges } = getNodesAndEdgesForConsumedMessage({
-        message: receive,
-        targetChannels: targetChannels,
-        services,
-        currentNodes: nodes,
-        target: service,
-        mode,
-        channels,
-      });
-
-      nodes.push(...consumedMessageNodes);
-      edges.push(...consumedMessageEdges);
-    });
-  }
-
-  // The service itself
-  nodes.push({
-    id: generateIdForNode(service),
-    sourcePosition: 'right',
-    targetPosition: 'left',
-    // data: { mode, service: { ...service, ...service.data } },
-    data: { mode, service: { ...service.data } },
-    type: service.collection,
-  });
-
-  // Any containers the service writes to
-  writesTo.forEach((writeTo) => {
-    nodes.push({
-      id: generateIdForNode(writeTo),
-      sourcePosition: 'right',
-      targetPosition: 'left',
-      data: { mode, data: { ...writeTo.data } },
-      type: 'data',
-    });
-
-    // If its not in the reads/and writes to, we need to add the edge
-    if (!bothReadsAndWrites.includes(writeTo)) {
-      edges.push(
-        createEdge({
-          id: generatedIdForEdge(service, writeTo),
-          source: generateIdForNode(service),
-          target: generateIdForNode(writeTo),
-          label: `writes to \n (${writeTo.data?.technology})`,
-          type: 'multiline',
-          markerEnd: {
-            type: MarkerType.ArrowClosed,
-            color: '#666',
-            width: 40,
-            height: 40,
-          },
-        })
-      );
-    }
-  });
-
-  // Any containers the service reads from
-  readsFrom.forEach((readFrom) => {
-    nodes.push({
-      id: generateIdForNode(readFrom),
-      sourcePosition: 'right',
-      targetPosition: 'left',
-      data: { mode, data: { ...readFrom.data } },
-      type: 'data',
-    });
-
-    // If its not in the reads/and writes to, we need to add the edge
-    if (!bothReadsAndWrites.includes(readFrom)) {
-      edges.push(
-        createEdge({
-          id: generatedIdForEdge(service, readFrom),
-          source: generateIdForNode(readFrom),
-          target: generateIdForNode(service),
-          label: `reads from \n (${readFrom.data?.technology})`,
-          type: 'multiline',
-          markerStart: {
-            type: MarkerType.ArrowClosed,
-            color: '#666',
-            width: 40,
-            height: 40,
-          },
-          markerEnd: undefined,
-        })
-      );
-    }
-  });
-
-  if (renderMessages) {
-    sends.forEach((send) => {
-      const sourceChannels = sendsRaw.find((sendRaw) => sendRaw.id === send.data.id)?.to;
-
-      const { nodes: producedMessageNodes, edges: producedMessageEdges } = getNodesAndEdgesForProducedMessage({
-        message: send,
-        sourceChannels: sourceChannels,
-        services,
-        currentNodes: nodes,
-        source: service,
-        currentEdges: edges,
-        mode,
-        channels,
-      });
-
-      nodes.push(...producedMessageNodes);
-      edges.push(...producedMessageEdges);
-    });
-
-    // Handle messages that are both sent and received
-    bothSentAndReceived.forEach((message) => {
-      if (message) {
-        edges.push({
-          id: generatedIdForEdge(service, message) + '-both',
-          source: generateIdForNode(service),
-          target: generateIdForNode(message),
-          label: `${getSendsMessageByMessageType(message?.collection)} & ${getReceivesMessageByMessageType(message?.collection)}`,
-          animated: false,
-          data: { message: { ...message.data } },
-          markerEnd: {
-            type: MarkerType.ArrowClosed,
-            width: 40,
-            height: 40,
-          },
-          style: {
-            strokeWidth: 1,
-          },
-        });
-      }
-    });
-  }
-
-  bothReadsAndWrites.forEach((container) => {
-    edges.push({
-      id: generatedIdForEdge(service, container) + '-both',
-      source: generateIdForNode(service),
-      target: generateIdForNode(container),
-      type: 'multiline',
-      // @ts-ignore
-      label: `reads from \n and writes to \n (${container.data.technology})`,
-      markerStart: {
-        type: MarkerType.ArrowClosed,
-        color: '#666',
-        width: 40,
-        height: 40,
-      },
-      markerEnd: {
-        type: MarkerType.ArrowClosed,
-        color: '#666',
-        width: 40,
-        height: 40,
-      },
-    });
-  });
-
-  nodes.forEach((node: any) => {
-    flow.setNode(node.id, { width: 150, height: 100 });
-  });
-
-  edges.forEach((edge: any) => {
-    flow.setEdge(edge.source, edge.target);
-  });
-
-  // Render the diagram in memory getting the X and Y
-  dagre.layout(flow);
-
-  // Find any duplicated edges, and merge them into one edge
-  const uniqueEdges = edges.reduce((acc: any[], edge: any) => {
-    const existingEdge = acc.find((e: any) => e.id === edge.id);
-    if (existingEdge) {
-      existingEdge.label = `${existingEdge.label} & ${edge.label}`;
-      // Add the custom colors to the existing edge which can be an array of strings
-      const value = Array.isArray(edge.data.customColor) ? edge.data.customColor : [edge.data.customColor];
-      const existingValue = Array.isArray(existingEdge.data.customColor)
-        ? existingEdge.data.customColor
-        : [existingEdge.data.customColor];
-      existingEdge.data.customColor = [...value, ...existingValue];
-    } else {
-      acc.push(edge);
-    }
-    return acc;
-  }, []);
-
-  return {
-    nodes: calculatedNodes(flow, nodes),
-    edges: uniqueEdges,
-  };
-};
diff --git a/eventcatalog/src/utils/node-graphs/utils/utils.ts b/eventcatalog/src/utils/node-graphs/utils/utils.ts
deleted file mode 100644
index ecde5b3a8..000000000
--- a/eventcatalog/src/utils/node-graphs/utils/utils.ts
+++ /dev/null
@@ -1,147 +0,0 @@
-// Can't use the CollectionEntry type from astro:content  because a client component is using this util
-
-import { MarkerType, Position, type Edge, type Node } from '@xyflow/react';
-import dagre from 'dagre';
-import { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
-interface BaseCollectionData {
-  id: string;
-  version: string;
-}
-
-interface CollectionItem {
-  collection: string;
-  data: BaseCollectionData;
-}
-
-interface MessageCollectionItem extends CollectionItem {
-  collection: 'commands' | 'events' | 'queries';
-}
-
-export const generateIdForNode = (node: CollectionItem) => {
-  return `${node.data.id}-${node.data.version}`;
-};
-export const generateIdForNodes = (nodes: any) => {
-  return nodes.map((node: any) => `${node.data.id}-${node.data.version}`).join('-');
-};
-export const generatedIdForEdge = (source: CollectionItem, target: CollectionItem) => {
-  return `${source.data.id}-${source.data.version}-${target.data.id}-${target.data.version}`;
-};
-
-export const getColorFromString = (id: string) => {
-  // Takes the given id (string) and returns a custom hex color based on the id
-  // Create a hash from the string
-  let hash = 0;
-  for (let i = 0; i < id.length; i++) {
-    hash = id.charCodeAt(i) + ((hash << 5) - hash);
-  }
-
-  // Convert the hash into a hex color
-  let color = '#';
-  for (let i = 0; i < 3; i++) {
-    const value = (hash >> (i * 8)) & 0xff;
-    color += value.toString(16).padStart(2, '0');
-  }
-
-  return color;
-};
-
-export const getEdgeLabelForServiceAsTarget = (data: MessageCollectionItem) => {
-  const type = data.collection;
-  switch (type) {
-    case 'commands':
-      return 'invokes';
-    case 'events':
-      return 'publishes \nevent';
-    case 'queries':
-      return 'requests';
-    default:
-      return 'sends to';
-  }
-};
-export const getEdgeLabelForMessageAsSource = (data: MessageCollectionItem, throughChannel = false) => {
-  const type = data.collection;
-  switch (type) {
-    case 'commands':
-      return 'accepts';
-    case 'events':
-      return throughChannel ? 'subscribed to' : 'subscribed by';
-    case 'queries':
-      return 'accepts';
-    default:
-      return 'sends to';
-  }
-};
-
-export const calculatedNodes = (flow: dagre.graphlib.Graph, nodes: Node[]) => {
-  return nodes.map((node: any) => {
-    const { x, y } = flow.node(node.id);
-    return { ...node, position: { x, y } };
-  });
-};
-
-// Creates a new dagre graph
-export const createDagreGraph = ({ ranksep = 180, nodesep = 50, ...rest }: any) => {
-  const graph = new dagre.graphlib.Graph({ compound: true });
-  graph.setGraph({ rankdir: 'LR', ranksep, nodesep, ...rest });
-  graph.setDefaultEdgeLabel(() => ({}));
-  return graph;
-};
-
-export const createEdge = (edgeOptions: Edge) => {
-  return {
-    label: 'subscribed by',
-    animated: false,
-    // markerStart: {
-    //   type: MarkerType.Arrow,
-    //   width: 40,
-    //   height: 40,
-    // },
-    markerEnd: {
-      type: MarkerType.ArrowClosed,
-      width: 40,
-      height: 40,
-    },
-    style: {
-      strokeWidth: 1,
-    },
-    ...edgeOptions,
-  };
-};
-
-export const createNode = (values: Node): Node => {
-  return {
-    sourcePosition: Position.Right,
-    targetPosition: Position.Left,
-    ...values,
-  };
-};
-
-type DagreGraph = any;
-
-export const getNodesAndEdgesFromDagre = ({
-  nodes,
-  edges,
-  defaultFlow,
-}: {
-  nodes: Node[];
-  edges: Edge[];
-  defaultFlow?: DagreGraph;
-}) => {
-  const flow = defaultFlow || createDagreGraph({ ranksep: 300, nodesep: 50 });
-
-  nodes.forEach((node: any) => {
-    flow.setNode(node.id, { width: 150, height: 100 });
-  });
-
-  edges.forEach((edge: any) => {
-    flow.setEdge(edge.source, edge.target);
-  });
-
-  // Render the diagram in memory getting hte X and Y
-  dagre.layout(flow);
-
-  return {
-    nodes: calculatedNodes(flow, nodes),
-    edges,
-  };
-};
diff --git a/eventcatalog/src/utils/page-loaders/page-data-loader.ts b/eventcatalog/src/utils/page-loaders/page-data-loader.ts
deleted file mode 100644
index 31b1aff58..000000000
--- a/eventcatalog/src/utils/page-loaders/page-data-loader.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-import type { CollectionTypes, PageTypes } from '@types';
-import { getChannels } from '@utils/channels';
-import { getDomains } from '@utils/collections/domains';
-import { getCommands, getEvents } from '@utils/messages';
-import { getQueries } from '@utils/queries';
-import { getServices } from '@utils/collections/services';
-import { getFlows } from '@utils/collections/flows';
-import { getEntities } from '@utils/entities';
-import { getContainers } from '@utils/collections/containers';
-import type { CollectionEntry } from 'astro:content';
-
-export const pageDataLoader: Record<PageTypes, () => Promise<CollectionEntry<CollectionTypes>[]>> = {
-  events: getEvents,
-  commands: getCommands,
-  queries: getQueries,
-  services: getServices,
-  domains: getDomains,
-  channels: getChannels,
-  flows: getFlows,
-  entities: getEntities,
-  containers: getContainers,
-};
diff --git a/eventcatalog/src/utils/queries.ts b/eventcatalog/src/utils/queries.ts
deleted file mode 100644
index 6a8c62594..000000000
--- a/eventcatalog/src/utils/queries.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-import { getCollection } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import path from 'path';
-import utils from '@eventcatalog/sdk';
-import { getVersionForCollectionItem, satisfies } from './collections/util';
-
-const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd();
-
-type Query = CollectionEntry<'queries'> & {
-  catalog: {
-    path: string;
-    filePath: string;
-    type: string;
-  };
-};
-
-interface Props {
-  getAllVersions?: boolean;
-  hydrateServices?: boolean;
-}
-
-// Cache for build time
-let cachedQueries: Record<string, Query[]> = {
-  allVersions: [],
-  currentVersions: [],
-};
-
-export const getQueries = async ({ getAllVersions = true, hydrateServices = true }: Props = {}): Promise<Query[]> => {
-  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
-
-  if (cachedQueries[cacheKey].length > 0 && hydrateServices) {
-    return cachedQueries[cacheKey];
-  }
-
-  const queries = await getCollection('queries', (query) => {
-    return (getAllVersions || !query.filePath?.includes('versioned')) && query.data.hidden !== true;
-  });
-
-  const services = await getCollection('services');
-  const allChannels = await getCollection('channels');
-
-  // @ts-ignore
-  cachedQueries[cacheKey] = await Promise.all(
-    queries.map(async (query) => {
-      const { latestVersion, versions } = getVersionForCollectionItem(query, queries);
-
-      const producers = services
-        .filter((service) =>
-          service.data.sends?.some((item) => {
-            if (item.id != query.data.id) return false;
-            if (item.version == 'latest' || item.version == undefined) return query.data.version == latestVersion;
-            return satisfies(query.data.version, item.version);
-          })
-        )
-        .map((service) => {
-          if (!hydrateServices) return { id: service.data.id, version: service.data.version };
-          return service;
-        });
-
-      const consumers = services
-        .filter((service) =>
-          service.data.receives?.some((item) => {
-            if (item.id != query.data.id) return false;
-            if (item.version == 'latest' || item.version == undefined) return query.data.version == latestVersion;
-            return satisfies(query.data.version, item.version);
-          })
-        )
-        .map((service) => {
-          if (!hydrateServices) return { id: service.data.id, version: service.data.version };
-          return service;
-        });
-
-      const messageChannels = query.data.channels || [];
-      const channelsForQuery = allChannels.filter((c) => messageChannels.some((channel) => c.data.id === channel.id));
-
-      const { getResourceFolderName } = utils(process.env.PROJECT_DIR ?? '');
-      const folderName = await getResourceFolderName(process.env.PROJECT_DIR ?? '', query.data.id, query.data.version.toString());
-      const queryFolderName = folderName ?? query.id.replace(`-${query.data.version}`, '');
-
-      return {
-        ...query,
-        data: {
-          ...query.data,
-          messageChannels: channelsForQuery,
-          producers,
-          consumers,
-          versions,
-          latestVersion,
-        },
-        catalog: {
-          path: path.join(query.collection, query.id.replace('/index.mdx', '')),
-          absoluteFilePath: path.join(PROJECT_DIR, query.collection, query.id.replace('/index.mdx', '/index.md')),
-          astroContentFilePath: path.join(process.cwd(), 'src', 'content', query.collection, query.id),
-          filePath: path.join(process.cwd(), 'src', 'catalog-files', query.collection, query.id.replace('/index.mdx', '')),
-          publicPath: path.join('/generated', query.collection, queryFolderName),
-          type: 'event',
-        },
-      };
-    })
-  );
-
-  // order them by the name of the query
-  cachedQueries[cacheKey].sort((a, b) => {
-    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
-  });
-
-  return cachedQueries[cacheKey];
-};
diff --git a/eventcatalog/src/utils/teams.ts b/eventcatalog/src/utils/teams.ts
deleted file mode 100644
index ce844bba3..000000000
--- a/eventcatalog/src/utils/teams.ts
+++ /dev/null
@@ -1,72 +0,0 @@
-import { getCollection } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import path from 'path';
-
-export type Team = CollectionEntry<'teams'>;
-
-// Cache for build time
-let cachedTeams: Team[] = [];
-
-export const getTeams = async (): Promise<Team[]> => {
-  if (cachedTeams.length > 0) {
-    return cachedTeams;
-  }
-
-  // Get services that are not versioned
-  const teams = await getCollection('teams', (team) => {
-    return team.data.hidden !== true;
-  });
-  // What do they own?
-  const domains = await getCollection('domains');
-  // What do they own?
-  const services = await getCollection('services');
-  // What do they own?
-  const events = await getCollection('events');
-  const commands = await getCollection('commands');
-  const queries = await getCollection('queries');
-  cachedTeams = teams.map((team) => {
-    const ownedDomains = domains.filter((domain) => {
-      return domain.data.owners?.find((owner) => owner.id === team.data.id);
-    });
-
-    const ownedServices = services.filter((service) => {
-      return service.data.owners?.find((owner) => owner.id === team.data.id);
-    });
-
-    const ownedEvents = events.filter((event) => {
-      return event.data.owners?.find((owner) => owner.id === team.data.id);
-    });
-
-    const ownedCommands = commands.filter((command) => {
-      return command.data.owners?.find((owner) => owner.id === team.data.id);
-    });
-
-    const ownedQueries = queries.filter((query) => {
-      return query.data.owners?.find((owner) => owner.id === team.data.id);
-    });
-
-    return {
-      ...team,
-      data: {
-        ...team.data,
-        ownedDomains,
-        ownedServices,
-        ownedCommands,
-        ownedQueries,
-        ownedEvents,
-      },
-      catalog: {
-        path: path.join(team.collection, team.id.replace('/index.mdx', '')),
-        filePath: path.join(process.cwd(), 'src', 'catalog-files', team.collection, team.id.replace('/index.mdx', '')),
-        type: 'team',
-      },
-    };
-  });
-
-  // order them by the name of the team
-  cachedTeams.sort((a, b) => {
-    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
-  });
-
-  return cachedTeams;
-};
diff --git a/eventcatalog/src/utils/url-builder.ts b/eventcatalog/src/utils/url-builder.ts
deleted file mode 100644
index 7a52d2800..000000000
--- a/eventcatalog/src/utils/url-builder.ts
+++ /dev/null
@@ -1,64 +0,0 @@
-// Don't import config here, as it breaks in the client, as path cannot be resolved.
-
-const cleanUrl = (url: string) => {
-  return url.replace(/\/+/g, '/');
-};
-
-// Custom URL builder as Astro does not support this stuff out the box
-export const buildUrl = (url: string, ignoreTrailingSlash = false, urlAlreadyIncludesBaseUrl = false) => {
-  // Should a trailingSlash be added to urls?
-  const trailingSlash = __EC_TRAILING_SLASH__;
-
-  let newUrl = url;
-
-  // If the base URL is not the root, we need to append it
-  if (import.meta.env.BASE_URL !== '/' && !urlAlreadyIncludesBaseUrl) {
-    newUrl = `${import.meta.env.BASE_URL}${url}`;
-  }
-
-  // Should we add a trailing slash to the url?
-  if (trailingSlash && !ignoreTrailingSlash) {
-    if (url.endsWith('/')) return newUrl;
-    return cleanUrl(`${newUrl}/`);
-  }
-
-  return cleanUrl(newUrl);
-};
-
-// Helper function to build URLs with query parameters
-export const buildUrlWithParams = (baseUrl: string, params: Record<string, string | undefined>) => {
-  // Filter out undefined values and empty strings
-  const validParams = Object.entries(params)
-    .filter(([_, value]) => value !== undefined && value !== '')
-    .reduce<Record<string, string>>((acc, [key, value]) => ({ ...acc, [key]: value as string }), {});
-
-  // If no valid params, just return the base URL
-  if (Object.keys(validParams).length === 0) {
-    return buildUrl(baseUrl);
-  }
-
-  // Build query string with encoded values
-  const queryString = Object.entries(validParams)
-    .map(([key, value]) => `${key}=${value}`)
-    .join('&');
-
-  return `${buildUrl(baseUrl)}?${queryString}`;
-};
-
-export const buildEditUrlForResource = (editUrl: string, filePath: string) => {
-  // filepath may have ../ or ./ in it, so we need to remove it
-  const cleanFilePath = filePath.replace(/^\.\.?\//g, '');
-  return `${editUrl}/${cleanFilePath}`;
-};
-
-// Takes a given url and returns the .mdx url
-export const toMarkdownUrl = (url: string) => {
-  const trailingSlash = __EC_TRAILING_SLASH__;
-
-  if (trailingSlash) {
-    const urlWithoutTrailingSlash = url.replace(/\/$/, '');
-    return urlWithoutTrailingSlash + '.mdx/';
-  }
-
-  return url + '.mdx';
-};
diff --git a/eventcatalog/src/utils/users.ts b/eventcatalog/src/utils/users.ts
deleted file mode 100644
index 49eaa783a..000000000
--- a/eventcatalog/src/utils/users.ts
+++ /dev/null
@@ -1,72 +0,0 @@
-import type { CollectionTypes } from '@types';
-import { getCollection } from 'astro:content';
-import type { CollectionEntry } from 'astro:content';
-import path from 'path';
-
-export type User = CollectionEntry<'users'>;
-
-export const getUsers = async (): Promise<User[]> => {
-  // Get services that are not versioned
-  const users = await getCollection('users', (user) => {
-    return user.data.hidden !== true;
-  });
-
-  // What do they own?
-  const domains = await getCollection('domains');
-  const services = await getCollection('services');
-  const events = await getCollection('events');
-  const commands = await getCollection('commands');
-  const queries = await getCollection('queries');
-
-  const teams = await getCollection('teams', (team) => {
-    return team.data.hidden !== true;
-  });
-
-  const mappedUsers = users.map((user) => {
-    const associatedTeams = teams.filter((team) => {
-      return team.data.members?.some((member) => member.id === user.data.id);
-    });
-
-    const ownedDomains = domains.filter((domain) => {
-      return domain.data.owners?.find((owner) => owner.id === user.data.id);
-    });
-
-    const isOwnedByUserOrAssociatedTeam = (item: CollectionEntry<CollectionTypes>) => {
-      const associatedTeamsId: string[] = associatedTeams.map((team) => team.data.id);
-      return item.data.owners?.some((owner) => owner.id === user.data.id || associatedTeamsId.includes(owner.id));
-    };
-
-    const ownedServices = services.filter(isOwnedByUserOrAssociatedTeam);
-
-    const ownedEvents = events.filter(isOwnedByUserOrAssociatedTeam);
-
-    const ownedCommands = commands.filter(isOwnedByUserOrAssociatedTeam);
-
-    const ownedQueries = queries.filter(isOwnedByUserOrAssociatedTeam);
-
-    return {
-      ...user,
-      data: {
-        ...user.data,
-        ownedDomains,
-        ownedServices,
-        ownedEvents,
-        ownedCommands,
-        ownedQueries,
-        associatedTeams,
-      },
-      catalog: {
-        path: path.join(user.collection, user.id.replace('/index.mdx', '')),
-        filePath: path.join(process.cwd(), 'src', 'catalog-files', user.collection, user.id.replace('/index.mdx', '')),
-        type: 'user',
-      },
-    };
-  });
-
-  // order them by the name of the user
-  mappedUsers.sort((a, b) => {
-    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
-  });
-
-  return mappedUsers;
-};
diff --git a/eventcatalog/tailwind.config.mjs b/eventcatalog/tailwind.config.mjs
deleted file mode 100644
index b498e6254..000000000
--- a/eventcatalog/tailwind.config.mjs
+++ /dev/null
@@ -1,69 +0,0 @@
-import config from './eventcatalog.config.js';
-import typography from '@tailwindcss/typography';
-
-const HEADER_HEIGHT = '4rem';
-const theme = config.theme || {};
-
-/** @type {import('tailwindcss').Config} */
-export default {
-  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
-  theme: {
-    extend: {
-      fontFamily: {
-        sans: ['Inter', 'sans-serif'],
-      },
-      height: {
-        header: HEADER_HEIGHT,
-        content: `calc(100vh - ${HEADER_HEIGHT})`,
-      },
-      spacing: {
-        header: HEADER_HEIGHT,
-        content: `calc(100vh - ${HEADER_HEIGHT})`,
-      },
-      screens: {
-        xxl: '1990px',
-      },
-      colors: {
-        primary: {
-          DEFAULT: '#a855f7',
-        },
-        secondary: {
-          light: '#ff9980',
-          DEFAULT: '#ff6633',
-          dark: '#cc3300',
-        },
-        ...theme,
-      },
-    },
-  },
-  safelist: [
-    { pattern: /border-.*-(200|400|500)/ },
-    { pattern: /bg-.*-(100|200|400|500)/ },
-    { pattern: /from-.*-(100|200|300|400|500|600|700)/ },
-    { pattern: /to-.*-(100|200|300|400|500|600|700)/ },
-    { pattern: /text-.*-(400|500|800)/ },
-    'border-blue-200',
-    'border-green-300',
-    'bg-blue-600',
-    'bg-orange-600',
-    'bg-red-50',
-    'bg-yellow-50',
-    'bg-pink-50',
-    'bg-green-50',
-    'bg-blue-50',
-    'bg-indigo-50',
-    'border-l-red-500',
-    'border-l-yellow-500',
-    'border-l-blue-500',
-    'bg-yellow-100',
-    'bg-pink-100',
-    'bg-green-100',
-    'bg-blue-100',
-    'bg-indigo-100',
-    'text-[5px]',
-    'text-[9px]',
-    'min-h-[100px]',
-  ],
-
-  plugins: [typography],
-};
diff --git a/eventcatalog/tsconfig.json b/eventcatalog/tsconfig.json
deleted file mode 100644
index 602a1429d..000000000
--- a/eventcatalog/tsconfig.json
+++ /dev/null
@@ -1,24 +0,0 @@
-{
-  "extends": "astro/tsconfigs/strict",
-  "compilerOptions": {
-    "strict": true,
-    "baseUrl": ".",
-    "paths": {
-      "@config": ["./eventcatalog.config.js"],
-      "@eventcatalog": ["src/utils/eventcatalog-config/catalog.ts"],
-      "@icons/*": ["src/icons/*"],
-      "@components/*": ["src/components/*"],
-      "@catalog/components/*": ["src/custom-defined-components/*"],
-      "@catalog/snippets/*": ["src/snippets/*"],
-      "@types": ["src/types/index.ts"],
-      "@utils/*": ["src/utils/*"],
-      "@layouts/*": ["src/layouts/*"],
-      "@enterprise/*": ["src/enterprise/*"],
-      "@ai/*": ["src/generated-ai/*"],
-      "auth:config": ["./auth.config.ts"]
-    },
-    "jsx": "react-jsx",
-    "jsxImportSource": "react",
-    "types": ["vitest/globals"]
-  }
-}
diff --git a/examples/default/.env-example b/examples/default/.env-example
index e69de29bb..4f37f2873 100644
--- a/examples/default/.env-example
+++ b/examples/default/.env-example
@@ -0,0 +1,12 @@
+# EventCatalog Scale (optional) — enables Scale plan features
+# EVENTCATALOG_SCALE=true
+# EVENTCATALOG_SCALE_LICENSE_KEY=
+
+# AI Chat (optional)
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+
+# Auth (optional)
+# AUTH_SECRET=
+# GITHUB_CLIENT_ID=
+# GITHUB_CLIENT_SECRET=
diff --git a/examples/default/.gitignore b/examples/default/.gitignore
index 3739f8846..4250cb55b 100644
--- a/examples/default/.gitignore
+++ b/examples/default/.gitignore
@@ -1,4 +1,4 @@
 
 generated-ai/
 public/ai/
-public/pagefind/
\ No newline at end of file
+public/pagefind/
diff --git a/examples/default/_data/visualizer-layouts/domains-systems-context/catalog/1.0.0.json b/examples/default/_data/visualizer-layouts/domains-systems-context/catalog/1.0.0.json
new file mode 100644
index 000000000..9f7b5070d
--- /dev/null
+++ b/examples/default/_data/visualizer-layouts/domains-systems-context/catalog/1.0.0.json
@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "savedAt": "2026-06-29T11:03:00.194Z",
+  "resourceKey": "domains-systems-context/catalog/1.0.0",
+  "positions": {
+    "product-catalog-system-1.0.0": {
+      "x": 654.4139077853363,
+      "y": 77.21012849584278
+    },
+    "search-system-1.0.0": {
+      "x": 1145,
+      "y": 335
+    },
+    "actor-merchandiser": {
+      "x": 90,
+      "y": 60
+    },
+    "actor-catalog-admin": {
+      "x": 90,
+      "y": 260
+    },
+    "actor-shopper": {
+      "x": 595,
+      "y": 360
+    },
+    "actor-storefront-team": {
+      "x": 595,
+      "y": 560
+    }
+  }
+}
\ No newline at end of file
diff --git a/examples/default/_data/visualizer-layouts/domains-systems-context/customer/1.0.0.json b/examples/default/_data/visualizer-layouts/domains-systems-context/customer/1.0.0.json
new file mode 100644
index 000000000..e39d05811
--- /dev/null
+++ b/examples/default/_data/visualizer-layouts/domains-systems-context/customer/1.0.0.json
@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "savedAt": "2026-06-26T12:15:29.856Z",
+  "resourceKey": "domains-systems-context/customer/1.0.0",
+  "positions": {
+    "customer-management-system-1.0.0": {
+      "x": 652.3279365079366,
+      "y": 338.73238095238094
+    },
+    "identity-provider-1.0.0": {
+      "x": 745.6812698412698,
+      "y": 71.1025396825397
+    },
+    "actor-customer": {
+      "x": 90,
+      "y": 122.5
+    },
+    "actor-support-agent": {
+      "x": 90,
+      "y": 322.5
+    }
+  }
+}
\ No newline at end of file
diff --git a/examples/default/_data/visualizer-layouts/system-context-map/system-context-map/1.0.0.json b/examples/default/_data/visualizer-layouts/system-context-map/system-context-map/1.0.0.json
new file mode 100644
index 000000000..1248cc73b
--- /dev/null
+++ b/examples/default/_data/visualizer-layouts/system-context-map/system-context-map/1.0.0.json
@@ -0,0 +1,91 @@
+{
+  "version": 1,
+  "savedAt": "2026-06-29T08:55:18.430Z",
+  "resourceKey": "system-context-map/system-context-map/1.0.0",
+  "positions": {
+    "carrier-1.0.0": {
+      "x": 1423.6053719008264,
+      "y": 1259.6570247933885
+    },
+    "shipping-system-1.0.0": {
+      "x": 1622.4194214876034,
+      "y": 1702.4814049586778
+    },
+    "cart-system-1.0.0": {
+      "x": 595,
+      "y": 60
+    },
+    "promotion-system-1.0.0": {
+      "x": 1145,
+      "y": 60
+    },
+    "actor-shopper": {
+      "x": 56.553719008264444,
+      "y": 178.41322314049586
+    },
+    "checkout-system-1.0.0": {
+      "x": 595,
+      "y": 260
+    },
+    "order-management-system-1.0.0": {
+      "x": 1145,
+      "y": 260
+    },
+    "customer-management-system-1.0.0": {
+      "x": 812.667132867133,
+      "y": 836.9146853146854
+    },
+    "identity-provider-1.0.0": {
+      "x": 1145,
+      "y": 1085
+    },
+    "actor-customer": {
+      "x": 90,
+      "y": 910
+    },
+    "actor-support-agent": {
+      "x": 90,
+      "y": 1110
+    },
+    "fraud-detection-1.0.0": {
+      "x": -664.9235537190083,
+      "y": 1282.7169421487602
+    },
+    "payment-processing-system-1.0.0": {
+      "x": -145.58264462809922,
+      "y": 1486.1818181818182
+    },
+    "inventory-system-1.0.0": {
+      "x": 366.3367768595041,
+      "y": 1716.0785123966941
+    },
+    "warehouse-system-1.0.0": {
+      "x": 955.3574380165288,
+      "y": 1529.3367768595042
+    },
+    "stripe-1.0.0": {
+      "x": 318.0144628099173,
+      "y": 1260.4194214876034
+    },
+    "product-catalog-system-1.0.0": {
+      "x": 1145,
+      "y": 497.5
+    },
+    "search-system-1.0.0": {
+      "x": 440.8853146853147,
+      "y": 723.5524475524476
+    },
+    "actor-merchandiser": {
+      "x": 447.2405594405594,
+      "y": 530.0979020979021
+    },
+    "actor-catalog-admin": {
+      "x": 561.634965034965,
+      "y": 418.6909090909091
+    },
+    "actor-storefront-team": {
+      "x": -349.5522886204704,
+      "y": 775.1666878575969
+    }
+  }
+}
\ No newline at end of file
diff --git a/examples/default/_data/visualizer-layouts/systems-context/customer-management-system/1.0.0.json b/examples/default/_data/visualizer-layouts/systems-context/customer-management-system/1.0.0.json
new file mode 100644
index 000000000..0d4b87545
--- /dev/null
+++ b/examples/default/_data/visualizer-layouts/systems-context/customer-management-system/1.0.0.json
@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "savedAt": "2026-06-29T11:26:03.901Z",
+  "resourceKey": "systems-context/customer-management-system/1.0.0",
+  "positions": {
+    "customer-management-system-1.0.0": {
+      "x": 593.5226571767497,
+      "y": -13.867141162514821
+    },
+    "identity-provider-1.0.0": {
+      "x": 1145,
+      "y": 85
+    },
+    "actor-customer": {
+      "x": 90,
+      "y": 60
+    },
+    "actor-support-agent": {
+      "x": 90,
+      "y": 260
+    }
+  }
+}
\ No newline at end of file
diff --git a/examples/default/channels/event-buses/cross-account-bus/index.mdx b/examples/default/channels/event-buses/cross-account-bus/index.mdx
deleted file mode 100644
index 45413d6e0..000000000
--- a/examples/default/channels/event-buses/cross-account-bus/index.mdx
+++ /dev/null
@@ -1,23 +0,0 @@
----
-id: cross-account-bus
-name: Organization Cross Account Bus
-version: 1.0.0
-summary: |
-  Amazon Organization Cross Account Bus
-owners:
-  - dboyne
-address: cross-account-bus.amazonaws.com
-protocols: 
-  - aws-cross-account-bus
-parameters:
-  accountId:
-    description: 'The AWS account ID to use'
-routes:
-  - id: registrations-domain-eventbus
-  - id: shipping-domain-eventbus
-  # - id: orders-domain-eventbus
----
-
-{/* Information about the AWS cross account eventbridge bus */}
-
-Full this....
diff --git a/examples/default/channels/event-buses/inventory-eventbus/index.mdx b/examples/default/channels/event-buses/inventory-eventbus/index.mdx
deleted file mode 100644
index 802dd8cd7..000000000
--- a/examples/default/channels/event-buses/inventory-eventbus/index.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-id: inventory-domain-eventbus
-name: Inventory Domain EventBus
-version: 1.0.0
-summary: |
-  The event bus for the Inventory domain. It is used to send events to and from the Inventory domain. Also events can be consumed from this bus by other domains.
-owners:
-  - dboyne
-routes:
-  - id: cross-account-bus
----
-
-
diff --git a/examples/default/channels/event-buses/registrations-domain-eventbus/index.mdx b/examples/default/channels/event-buses/registrations-domain-eventbus/index.mdx
deleted file mode 100644
index 2aa6f3e0d..000000000
--- a/examples/default/channels/event-buses/registrations-domain-eventbus/index.mdx
+++ /dev/null
@@ -1,10 +0,0 @@
----
-id: registrations-domain-eventbus
-name: Registrations Domain EventBus
-version: 1.0.0
-summary: |
-  Amazon Registrations Domain EventBus
-owners:
-  - dboyne
----
-
diff --git a/examples/default/channels/event-buses/shipping-domain-eventbus/index.mdx b/examples/default/channels/event-buses/shipping-domain-eventbus/index.mdx
deleted file mode 100644
index 956b2f43f..000000000
--- a/examples/default/channels/event-buses/shipping-domain-eventbus/index.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
----
-id: shipping-domain-eventbus
-name: Shipping Domain EventBus
-version: 1.0.0
-summary: |
-  Amazon Shipping Domain EventBus
-owners:
-  - dboyne
-routes:
-  - id: cross-account-bus
----
diff --git a/examples/default/channels/inventory.{env}.events/index.mdx b/examples/default/channels/inventory.{env}.events/index.mdx
deleted file mode 100644
index f95bc8ba2..000000000
--- a/examples/default/channels/inventory.{env}.events/index.mdx
+++ /dev/null
@@ -1,157 +0,0 @@
----
-id: inventory.{env}.events
-name: Inventory Events Channel
-version: 1.0.0
-summary: |
-  Central event stream for all inventory-related events including stock updates, allocations, and adjustments
-owners:
-  - dboyne
-address: inventory.{env}.events
-protocols: 
-  - kafka
-
-parameters:
-  env:
-    enum:
-      - dev
-      - sit
-      - prod
-    description: 'Environment to use'
----
-
-### Overview
-The Inventory Events channel is the central stream for all inventory-related events across the system. This includes stock level changes, inventory allocations, adjustments, and stocktake events. Events for a specific SKU are guaranteed to be processed in sequence when using productId as the partition key.
-
-<ChannelInformation />
-
-### Publishing and Subscribing to Events
-
-#### Publishing Example
-```python
-from kafka import KafkaProducer
-import json
-from datetime import datetime
-
-# Kafka configuration
-bootstrap_servers = ['localhost:9092']
-topic = f'inventory.{env}.events'
-
-# Create a Kafka producer
-producer = KafkaProducer(
-    bootstrap_servers=bootstrap_servers,
-    value_serializer=lambda v: json.dumps(v).encode('utf-8')
-)
-
-# Example inventory update event
-inventory_event = {
-    "eventType": "STOCK_LEVEL_CHANGED",
-    "timestamp": datetime.utcnow().isoformat(),
-    "version": "1.0",
-    "payload": {
-        "productId": "PROD-456",
-        "locationId": "WH-123",
-        "previousQuantity": 100,
-        "newQuantity": 95,
-        "changeReason": "ORDER_FULFILLED",
-        "unitOfMeasure": "EACH",
-        "batchInfo": {
-            "batchId": "BATCH-789",
-            "expiryDate": "2025-12-31"
-        }
-    },
-    "metadata": {
-        "source": "warehouse_system",
-        "correlationId": "inv-xyz-123",
-        "userId": "john.doe"
-    }
-}
-
-# Send the message - using productId as key for partitioning
-producer.send(
-    topic, 
-    key=inventory_event['payload']['productId'].encode('utf-8'),
-    value=inventory_event
-)
-producer.flush()
-
-print(f"Inventory event sent to topic {topic}")
-
-```
-
-### Subscription example
-
-```python
-from kafka import KafkaConsumer
-import json
-from datetime import datetime
-
-class InventoryEventConsumer:
-    def __init__(self):
-        # Kafka configuration
-        self.topic = f'inventory.{env}.events'
-        self.consumer = KafkaConsumer(
-            self.topic,
-            bootstrap_servers=['localhost:9092'],
-            group_id='inventory-processor-group',
-            auto_offset_reset='earliest',
-            enable_auto_commit=False,
-            value_deserializer=lambda x: json.loads(x.decode('utf-8')),
-            key_deserializer=lambda x: x.decode('utf-8') if x else None
-        )
-
-    def process_event(self, event):
-        """Process individual inventory events based on type"""
-        event_type = event.get('eventType')
-        
-        if event_type == 'STOCK_LEVEL_CHANGED':
-            self.handle_stock_level_change(event)
-        elif event_type == 'LOW_STOCK_ALERT':
-            self.handle_low_stock_alert(event)
-        # Add more event type handlers as needed
-
-    def handle_stock_level_change(self, event):
-        """Handle stock level change events"""
-        payload = event['payload']
-        print(f"Stock level change detected for product {payload['productId']}")
-        print(f"New quantity: {payload['newQuantity']}")
-        # Add your business logic here
-
-    def handle_low_stock_alert(self, event):
-        """Handle low stock alert events"""
-        payload = event['payload']
-        print(f"Low stock alert for product {payload['productId']}")
-        print(f"Current quantity: {payload['currentQuantity']}")
-        # Add your business logic here
-
-    def start_consuming(self):
-        """Start consuming messages from the topic"""
-        try:
-            print(f"Starting consumption from topic: {self.topic}")
-            for message in self.consumer:
-                try:
-                    # Process the message
-                    event = message.value
-                    print(f"Received event: {event['eventType']} for product: {event['payload']['productId']}")
-                    
-                    # Process the event
-                    self.process_event(event)
-                    
-                    # Commit the offset after successful processing
-                    self.consumer.commit()
-                    
-                except Exception as e:
-                    print(f"Error processing message: {str(e)}")
-                    # Implement your error handling logic here
-                    # You might want to send to a DLQ (Dead Letter Queue)
-        
-        except Exception as e:
-            print(f"Consumer error: {str(e)}")
-        finally:
-            # Clean up
-            self.consumer.close()
-
-if __name__ == "__main__":
-    # Create and start the consumer
-    consumer = InventoryEventConsumer()
-    consumer.start_consuming()
-  ```
\ No newline at end of file
diff --git a/examples/default/channels/orders.{env}.events/index.mdx b/examples/default/channels/orders.{env}.events/index.mdx
deleted file mode 100644
index 4cfd70802..000000000
--- a/examples/default/channels/orders.{env}.events/index.mdx
+++ /dev/null
@@ -1,108 +0,0 @@
----
-id: orders.{env}.events
-name: Order Events Channel
-version: 1.0.1
-summary: |
-  Central event stream for all order-related events in the order processing lifecycle
-owners:
-  - dboyne
-address: orders.{env}.events
-protocols: 
-  - azure-servicebus
-sidebar:
-  badge: 'ServiceBus'
-routes:
-  - id: sns-channel
-parameters:
-  env:
-    enum:
-      - dev
-      - sit
-      - prod
-    description: 'Environment to use'
----
-
-### Overview
-The Orders Events channel is the central stream for all order-related events across the order processing lifecycle. This includes order creation, updates, payment status, fulfillment status, and customer communications. All events related to a specific order are guaranteed to be processed in sequence when using orderId as the partition key.
-
-<ChannelInformation />
-
-### Publishing a message using Azure Service Bus
-
-Here is an example of how to publish an order event using Azure Service Bus:
-
-```python
-import json
-from datetime import datetime
-from azure.servicebus import ServiceBusClient, ServiceBusMessage
-
-# --- Azure Service Bus Configuration ---
-# Replace with your actual connection string and queue/topic name
-CONNECTION_STR = "YOUR_AZURE_SERVICE_BUS_CONNECTION_STRING"
-QUEUE_NAME = "orders"  # Or your specific queue/topic name e.g., f"orders.{env}.events"
-
-# --- Example Order Event Data ---
-# This is the same event structure as before
-order_event_data = {
-    "eventType": "ORDER_CREATED",
-    "timestamp": datetime.utcnow().isoformat() + "Z", # ISO 8601 format with Z for UTC
-    "version": "1.0",
-    "payload": {
-        "orderId": "12345",
-        "customerId": "CUST-789",
-        "items": [
-            {
-                "productId": "PROD-456",
-                "quantity": 2,
-                "price": 29.99
-            }
-        ],
-        "totalAmount": 59.98,
-        "shippingAddress": {
-            "street": "123 Main St",
-            "city": "Springfield",
-            "country": "US"
-        }
-    },
-    "metadata": {
-        "source": "web_checkout",
-        "correlationId": "abc-xyz-123"
-        # Potentially add a message ID if not automatically handled or for specific tracking
-        # "messageId": str(uuid.uuid4()) # Requires import uuid
-    }
-}
-
-def send_order_event_to_service_bus(connection_string, queue_name, event_data):
-    # Create a ServiceBusClient object
-    with ServiceBusClient.from_connection_string(conn_str=connection_string) as servicebus_client:
-        # Create a sender for the queue
-        # For a topic, use: servicebus_client.get_topic_sender(topic_name=queue_name)
-        sender = servicebus_client.get_queue_sender(queue_name=queue_name)
-        with sender:
-            # Serialize the event data to a JSON string
-            event_json = json.dumps(event_data)
-            # Create a ServiceBusMessage object
-            message = ServiceBusMessage(event_json)
-            
-            # Set properties if needed, e.g., message_id or correlation_id
-            # message.message_id = event_data["metadata"].get("messageId")
-            message.correlation_id = event_data["metadata"]["correlationId"]
-            
-            # Send the message
-            sender.send_messages(message)
-            print(f"Sent order event (ID: {event_data['payload']['orderId']}) to Azure Service Bus queue: {queue_name}")
-
-if __name__ == "__main__":
-    # Example of how to call the function
-    # Ensure azure-servicebus package is installed: pip install azure-servicebus
-    
-    # Basic error handling for placeholders
-    if CONNECTION_STR == "YOUR_AZURE_SERVICE_BUS_CONNECTION_STRING" or QUEUE_NAME == "YOUR_QUEUE_NAME":
-        print("Please update CONNECTION_STR and QUEUE_NAME with your actual Azure Service Bus details.")
-    else:
-        try:
-            send_order_event_to_service_bus(CONNECTION_STR, QUEUE_NAME, order_event_data)
-        except Exception as e:
-            print(f"An error occurred: {e}")
-            print("Ensure your Azure Service Bus connection string and queue name are correct,")
-            print("and the 'azure-servicebus' package is installed ('pip install azure-servicebus').")
\ No newline at end of file
diff --git a/examples/default/channels/payment.{env}.events/index.mdx b/examples/default/channels/payment.{env}.events/index.mdx
deleted file mode 100644
index 2aa739645..000000000
--- a/examples/default/channels/payment.{env}.events/index.mdx
+++ /dev/null
@@ -1,88 +0,0 @@
----
-id: payments.{env}.events
-name: Payment Events Channel
-version: 1.0.0
-summary: |
- All events contain payment ID for traceability and ordered processing.
-owners:
- - dboyne
-address: payments.{env}.events
-protocols: 
- - kafka
-
-parameters:
- env:
-   enum:
-     - dev
-     - sit
-     - prod
-   description: 'Environment to use for payment events'
----
-
-### Overview
-The Payments Events channel is the central stream for all payment lifecycle events. This includes payment initiation, authorization, capture, completion and failure scenarios. Events for a specific payment are guaranteed to be processed in sequence when using paymentId as the partition key.
-
-<ChannelInformation />
-
-### Publishing Events Using Kafka
-
-Here's an example of publishing a payment event:
-
-```python
-from kafka import KafkaProducer
-import json
-from datetime import datetime
-
-# Kafka configuration
-bootstrap_servers = ['localhost:9092']
-topic = f'payments.{env}.events'
-
-# Create Kafka producer
-producer = KafkaProducer(
-   bootstrap_servers=bootstrap_servers,
-   value_serializer=lambda v: json.dumps(v).encode('utf-8')
-)
-
-# Example payment processed event
-payment_event = {
-   "eventType": "PAYMENT_PROCESSED",
-   "timestamp": datetime.utcnow().isoformat(),
-   "version": "1.0",
-   "payload": {
-       "paymentId": "PAY-123-456", 
-       "orderId": "ORD-789",
-       "amount": {
-           "value": 99.99,
-           "currency": "USD"
-       },
-       "status": "SUCCESS",
-       "paymentMethod": {
-           "type": "CREDIT_CARD",
-           "last4": "4242",
-           "expiryMonth": "12",
-           "expiryYear": "2025",
-           "network": "VISA"
-       },
-       "transactionDetails": {
-           "processorId": "stripe_123xyz",
-           "authorizationCode": "AUTH123",
-           "captureId": "CAP456"
-       }
-   },
-   "metadata": {
-       "correlationId": "corr-123-abc",
-       "merchantId": "MERCH-456", 
-       "source": "payment_service",
-       "environment": "prod",
-       "idempotencyKey": "PAY-123-456-2024-11-11-99.99"
-   }
-}
-
-# Send message - using paymentId as key for partitioning
-producer.send(
-   topic,
-   key=payment_event['payload']['paymentId'].encode('utf-8'),
-   value=payment_event
-)
-producer.flush()
-```
\ No newline at end of file
diff --git a/examples/default/chat-prompts/code/create-an-example-schema.mdx b/examples/default/chat-prompts/code/create-an-example-schema.mdx
deleted file mode 100644
index 274161ace..000000000
--- a/examples/default/chat-prompts/code/create-an-example-schema.mdx
+++ /dev/null
@@ -1,67 +0,0 @@
----
-title: Generate a JSON Schema Following FlowMart Standards
-category:
-  id: Code
-  label: Code
-  icon: Code
-inputs:
-  - id: event-name
-    label: What is the name of the event?
-    type: text
----
-
-Generate a JSON schema for an event called `{{event-name}}`. This schema must follow FlowMart's payload standards.
-
-**FlowMart Payload Standards:**
-
-*   Every payload MUST include a top-level `metadata` field.
-*   The `metadata` field MUST contain:
-    *   `correlationId`: A string, preferably in UUID format.
-    *   `createdDate`: A string in ISO 8601 format (e.g., "2023-11-02T14:29:55Z").
-*   The main event details should be within a top-level `data` field.
-
-**Example `UserSignedUp` Event Payload:**
-
-```json
-{
-  "metadata": {
-     "correlationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-     "createdDate": "2023-11-02T14:29:55Z"
-  },
-  "data": {
-    "userId": "user-789",
-    "email": "test@example.com",
-    "signUpMethod": "Google"
-  }
-}
-```
-
-**Invalid Example (Missing `metadata`):**
-```json
-{
-  "data": {
-    "userId": "user-123",
-    "email": "invalid@example.com"
-  }
-}
-```
-
-**Invalid Example (Missing `correlationId` in `metadata`):**
-```json
-{
-  "metadata": {
-     "createdDate": "2023-11-01T10:00:00Z"
-  },
-  "data": {
-     "userId": "user-456",
-     "email": "incomplete@example.com"
-  }
-}
-```
-
-**Task:**
-
-Create the JSON schema definition for the `UserSignedUp` event described above, ensuring it enforces the FlowMart payload standards.
-
-
-
diff --git a/examples/default/chat-prompts/code/create-consumer-code-for-event.mdx b/examples/default/chat-prompts/code/create-consumer-code-for-event.mdx
deleted file mode 100644
index 964d8de8c..000000000
--- a/examples/default/chat-prompts/code/create-consumer-code-for-event.mdx
+++ /dev/null
@@ -1,48 +0,0 @@
----
-title: Create Kafka Consumer Code for Event
-category:
-  id: Code
-  label: Code
-  icon: Code
-inputs:
-  - id: event-name
-    label: Select the event you want to create a consumer for
-    type: resource-list-events
-  - id: code-language
-    label: What is the programming language of the code?
-    type: select
-    options:
-      - Python
-      - Java
-      - TypeScript
-      - Go
-      - Ruby
----
-
-Generate Kafka consumer code in `{{code-language}}` that consumes the event `{{event-name}}`.
-
-**Kafka Cluster Details:**
-
-*   **Bootstrap Servers:** `kafka-prod-1.flowmart.internal:9092,kafka-prod-2.flowmart.internal:9092,kafka-prod-3.flowmart.internal:9092`
-*   **Topic Name:** The topic name follows the pattern `fm.events.<event-name>` (e.g., `fm.events.UserSignedUp` for the `UserSignedUp` event).
-*   **Consumer Group ID:** Use a descriptive consumer group ID, like `consumer-{{event-name}}-service`.
-*   **Security Protocol:** SASL_SSL
-*   **SASL Mechanism:** PLAIN
-
-**Best Practices to Follow:**
-
-1.  **Deserialization:** Assume the event payload is JSON and follows FlowMart's payload standards (with `metadata` and `data` fields). Deserialize the message payload into an appropriate data structure or class.
-2.  **Error Handling:** Implement robust error handling for connection issues, deserialization failures, and message processing errors. Use a dead-letter queue (DLQ) pattern for messages that cannot be processed after retries. The DLQ topic name is `dlq.fm.events.<event-name>`.
-3.  **Configuration:** Externalize Kafka connection details and consumer group ID (don't hardcode them directly in the main logic).
-4.  **Logging:** Add basic logging for successful message consumption and any errors encountered.
-5.  **Commit Strategy:** Use manual commits (`enable.auto.commit=false`) to ensure messages are only marked as processed after successful handling.
-6.  **Idempotency:** Briefly mention how the consumer logic should handle potential duplicate messages (e.g., by checking a database record based on `metadata.correlationId` before processing).
-
-**Task:**
-
-Provide the complete, runnable Kafka consumer code snippet in `{{code-language}}` for the `{{event-name}}` event, incorporating the cluster details and best practices mentioned above. Include necessary imports and basic setup.
-
-If you use any external libraries, please include the import statements and how to install them, step by step, make sure dependencies are listed first.
-
-
-
diff --git a/examples/default/chat-prompts/code/create-consumer-code-for-eventbridge-event.mdx b/examples/default/chat-prompts/code/create-consumer-code-for-eventbridge-event.mdx
deleted file mode 100644
index 981cfc65b..000000000
--- a/examples/default/chat-prompts/code/create-consumer-code-for-eventbridge-event.mdx
+++ /dev/null
@@ -1,38 +0,0 @@
----
-title: Create EventBridge Rule for an Event
-category:
-  id: CloudFormation
-  label: CloudFormation
-  icon: CloudFormation
-inputs:
-  - id: event-name
-    label: Select the event you want to create a rule for
-    type: resource-list-events
-  - id: rule-name
-    label: Enter a name for the EventBridge rule
-    type: text
----
-
-Generate an AWS CloudFormation template snippet (YAML) to create an EventBridge rule. This rule should trigger based on the selected event `{{event-name}}` from the default EventBus and invoke the specified Lambda function `{{target-lambda-arn}}`.
-
-**Rule Details:**
-
-*   **Rule Name:** `{{rule-name}}` (e.g., `trigger-lambda-on-{{event-name}}`)
-*   **Event Bus:** Use the `default` event bus.
-*   **Event Pattern:** The rule should match events where the `detail-type` is exactly `{{event-name}}`.
-*   **Target:** The primary target is the Lambda function with ARN `{{target-lambda-arn}}`.
-*   **Permissions:** Ensure the necessary permissions are granted for EventBridge to invoke the target Lambda function.
-
-**Best Practices to Follow:**
-
-1.  **Clarity:** Use clear and descriptive names for resources.
-2.  **Specificity:** Define the event pattern precisely to avoid unintended triggers.
-3.  **Permissions:** Include the `AWS::Lambda::Permission` resource to grant invocation rights.
-4.  **Least Privilege:** Grant only the necessary permissions.
-
-**Task:**
-
-Provide the complete, runnable CloudFormation YAML snippet for the `{{rule-name}}` EventBridge rule, incorporating the details and best practices mentioned above. Include the `AWSTemplateFormatVersion` and `Resources` sections.
-
-
-
diff --git a/examples/default/chat-prompts/code/create-lambda-function-to-consume-event.mdx b/examples/default/chat-prompts/code/create-lambda-function-to-consume-event.mdx
deleted file mode 100644
index 7d9561480..000000000
--- a/examples/default/chat-prompts/code/create-lambda-function-to-consume-event.mdx
+++ /dev/null
@@ -1,58 +0,0 @@
----
-title: Create AWS Lambda Function to Consume EventBridge Event
-category:
-  id: Code
-  label: Code
-  icon: Code
-inputs:
-  - id: event-name
-    label: Select the EventBridge event the Lambda will consume
-    type: resource-list-events
-  - id: code-language
-    label: What is the programming language for the Lambda function?
-    type: select
-    options:
-      - Python
-      - Java
-      - TypeScript
-      - Go
-      - Ruby
-      # Add other languages supported by Powertools/Lambda as needed
----
-
-Generate an AWS Lambda function handler in `{{code-language}}` that consumes the EventBridge event `{{event-name}}`.
-
-**Event Details:**
-
-*   **Event Source:** AWS EventBridge
-*   **Event Name:** `{{event-name}}`
-*   **Payload Location:** The actual event payload (`{{event-name}}`) is located within the `detail` field of the incoming EventBridge event object.
-*   **Payload Format:** Assume the event payload within `detail` is JSON and follows FlowMart's payload standards (containing `metadata` and `data` fields).
-
-**Best Practices to Follow:**
-
-1.  **Parsing & Validation:** Safely parse the incoming EventBridge event object. Extract and validate the `detail` field. Deserialize the JSON payload within `detail` into an appropriate data structure or class.
-2.  **AWS Lambda Powertools:** Utilize AWS Lambda Powertools for `{{code-language}}` to enhance observability and implement best practices:
-    *   **Logging:** Implement structured logging. Include key information like the EventBridge event ID and `metadata.correlationId` in logs.
-    *   **Tracing:** Enable AWS X-Ray tracing integration for request tracing across services.
-    *   **Metrics:** Emit custom business or operational metrics (e.g., successful processing count, processing latency).
-    *   **(Optional) Event Handler:** Consider using Powertools' Event Handler utility (if available for `{{code-language}}`) for simplified event parsing, validation, and routing based on event content.
-    *   **(Optional) Idempotency:** Implement idempotency using Powertools' Idempotency utility to safely handle potential duplicate event deliveries from EventBridge. Use the EventBridge event `id` or `detail.metadata.correlationId` as the idempotency key.
-3.  **Error Handling:** Implement robust error handling within the function code. For transient errors, allow the function to error out to leverage Lambda's built-in retry mechanism. Configure a Dead-Letter Queue (DLQ) on the Lambda function itself (via AWS console, CLI, or IaC) to capture events that fail permanently after retries. *Do not implement DLQ logic within the function code.*
-4.  **Configuration:** Use environment variables for any external configuration (e.g., API endpoints, table names). Do not hardcode configuration values.
-5.  **Permissions:** Note the essential IAM permissions required for the Lambda execution role (e.g., `logs:CreateLogGroup`, `logs:CreateLogStream`, `logs:PutLogEvents`, `xray:PutTraceSegments`, permissions for any AWS services the function interacts with, and potentially KMS permissions if using encryption).
-6.  **Dependencies:** Clearly list all external dependencies (like AWS Lambda Powertools) and provide instructions on how to install and package them with the Lambda function (e.g., using requirements.txt for Python, package.json for TypeScript, pom.xml/build.gradle for Java).
-
-**Task:**
-
-Provide the complete, runnable AWS Lambda function handler code snippet in `{{code-language}}` for the `{{event-name}}` event. The code should:
-*   Include necessary imports and initialization for AWS SDK and Powertools.
-*   Demonstrate parsing the EventBridge event and deserializing the `detail` payload.
-*   Incorporate Powertools for logging, tracing, and metrics as described.
-*   Include basic error handling.
-*   Be ready to be deployed as an AWS Lambda function.
-
-Also, provide the necessary dependency management file content (e.g., `requirements.txt`, `package.json`) and brief packaging instructions.
-
-
-
diff --git a/examples/default/chat-prompts/code/create-producer-code-for-event.mdx b/examples/default/chat-prompts/code/create-producer-code-for-event.mdx
deleted file mode 100644
index 6222fd334..000000000
--- a/examples/default/chat-prompts/code/create-producer-code-for-event.mdx
+++ /dev/null
@@ -1,48 +0,0 @@
----
-title: Create Kafka Producer Code for Event
-category:
-  id: Code
-  label: Code
-  icon: Code
-inputs:
-  - id: event-name
-    label: Select the event you want to create a producer for
-    type: resource-list-events
-  - id: code-language
-    label: What is the programming language of the code?
-    type: select
-    options:
-      - Python
-      - Java
-      - TypeScript
-      - Go
-      - Ruby
----
-
-Generate Kafka producer code in `{{code-language}}` that produces the event `{{event-name}}`.
-
-**Kafka Cluster Details:**
-
-*   **Bootstrap Servers:** `kafka-prod-1.flowmart.internal:9092,kafka-prod-2.flowmart.internal:9092,kafka-prod-3.flowmart.internal:9092`
-*   **Topic Name:** The topic name follows the pattern `fm.events.<event-name>` (e.g., `fm.events.UserSignedUp` for the `UserSignedUp` event).
-*   **Security Protocol:** SASL_SSL
-*   **SASL Mechanism:** PLAIN
-*   **Required Acknowledgements (acks):** `all` (Ensure highest durability).
-
-**Best Practices to Follow:**
-
-1.  **Serialization:** Assume the event payload needs to be serialized to JSON and follow FlowMart's payload standards (with `metadata` and `data` fields). The `metadata` should include a unique `eventId` (UUID) and `timestamp` (ISO 8601).
-2.  **Error Handling:** Implement robust error handling for connection issues, serialization failures, and send failures. Consider retry mechanisms with backoff for transient errors.
-3.  **Configuration:** Externalize Kafka connection details (don't hardcode them directly in the main logic).
-4.  **Logging:** Add basic logging for successful message production and any errors encountered.
-5.  **Asynchronous Sending:** Use asynchronous send calls for better performance, but ensure proper handling of send callbacks/futures for error checking and logging.
-6.  **Partitioning:** Briefly mention how to set a message key (e.g., using `metadata.correlationId` or a relevant business ID) if specific partitioning is desired for ordering guarantees within a partition.
-
-**Task:**
-
-Provide the complete, runnable Kafka producer code snippet in `{{code-language}}` for the `{{event-name}}` event, incorporating the cluster details and best practices mentioned above. Include necessary imports, basic setup, and an example of how to construct and send an event message.
-
-If you use any external libraries, please include the import statements and how to install them, step by step, make sure dependencies are listed first.
-
-
-
diff --git a/examples/default/chat-prompts/learning/tell-me-more-about-this-event.mdx b/examples/default/chat-prompts/learning/tell-me-more-about-this-event.mdx
deleted file mode 100644
index fc1e37834..000000000
--- a/examples/default/chat-prompts/learning/tell-me-more-about-this-event.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Tell me more about the given event
-category:
-  id: Learning
-  label: Learning
-  icon: GraduationCap
-inputs:
-  - id: event-name
-    label: Select the event you want to know more about
-    type: resource-list-events
----
-
-Tell me more about the given event `{{event-name}}`.
diff --git a/examples/default/chat-prompts/learning/tell-me-more-about-this-service.mdx b/examples/default/chat-prompts/learning/tell-me-more-about-this-service.mdx
deleted file mode 100644
index c9ce404d3..000000000
--- a/examples/default/chat-prompts/learning/tell-me-more-about-this-service.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Tell me more about the given service
-category:
-  id: Learning
-  label: Learning
-  icon: GraduationCap
-inputs:
-  - id: service-name
-    label: Select the service you want to know more about
-    type: resource-list-services
----
-
-Tell me more about the given service `{{service-name}}`.
diff --git a/examples/default/chat-prompts/learning/validate-this-schema.mdx b/examples/default/chat-prompts/learning/validate-this-schema.mdx
deleted file mode 100644
index ee7e74732..000000000
--- a/examples/default/chat-prompts/learning/validate-this-schema.mdx
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Validate schema against best practices
-category:
-  id: Learning
-  label: Learning
-  icon: GraduationCap
-inputs:
-  - id: schema
-    label: Schema
-    type: code
----
-
-Please review the following event schema:
-
-```json
-{{schema}}
-```
-
-Validate this schema against the FlowMart EDA best practices listed below and provide feedback on any areas where the schema does not align or could be improved based on these guidelines.
-
---- 
-
-## FlowMart EDA Best Practices for Reference:
-
-### Event Naming and Structure
-
-*   **Past Tense Naming:** All event names MUST be in the past tense (e.g., `OrderCreated`, `UserLoggedIn`, `PaymentProcessed`). This reflects that an event represents something that has already occurred.
-*   **Correlation IDs:** Every event MUST include a `correlationId`. This allows us to track related events across different services and flows, which is crucial for debugging and observability.
-*   **Clear Event Payloads:** Event payloads should be well-defined, documented, and contain only the necessary information relevant to the event itself. Avoid overly large or generic payloads.
-
-### Contract Management and Ownership
-
-*   **Producer Ownership:** The service that produces an event owns its contract (schema). Consumers should rely on this defined contract.
-*   **Public vs. Private Events:** Events MUST be explicitly marked as either `public` or `private`.
-    *   `Public` events have strong backward compatibility guarantees.
-    *   `Private` events are typically for internal service use and may have less stringent compatibility requirements, but changes should still be coordinated.
-*   **No Breaking Changes (Public Events):** We strive to avoid breaking changes in `public` event contracts. If a change is necessary, it must be additive or managed through versioning.
-*   **Semantic Versioning (SemVer):** Event schemas SHOULD follow Semantic Versioning (e.g., `1.0.0`, `1.1.0`, `2.0.0`).
-    *   MAJOR version bumps indicate breaking changes (avoided for public events).
-    *   MINOR version bumps indicate backward-compatible additions.
-    *   PATCH version bumps indicate backward-compatible fixes.
-
-### Design Principles
-
-*   **Idempotent Consumers:** Consumers should be designed to be idempotent, meaning they can safely process the same event multiple times without unintended side effects. This handles scenarios like message replays or network issues.
-*   **Asynchronous Communication:** Favor asynchronous communication patterns. Events decouple services, allowing them to operate independently.
-*   **Domain-Driven Design (DDD):** Align events with bounded contexts and domain concepts from DDD. This helps create meaningful, cohesive events.
-*   **Schema Registry:** Utilize a schema registry (like the one provided by EventCatalog!) to manage, validate, and evolve event schemas centrally.
-
-### Documentation and Discovery
-
-*   **EventCatalog:** All events, schemas, producers, and consumers MUST be documented in our EventCatalog. This serves as the single source of truth for our EDA landscape.
-*   **Clear Descriptions:** Provide clear, concise descriptions for each event, explaining its purpose and context.
-
-By following these practices, we aim to build a resilient and understandable event-driven ecosystem at FlowMart.
diff --git a/examples/default/chat-prompts/learning/what-are-the-best-practices-for-eda-in-the-company.mdx b/examples/default/chat-prompts/learning/what-are-the-best-practices-for-eda-in-the-company.mdx
deleted file mode 100644
index 3b35a364d..000000000
--- a/examples/default/chat-prompts/learning/what-are-the-best-practices-for-eda-in-the-company.mdx
+++ /dev/null
@@ -1,43 +0,0 @@
----
-title: What are the best practices for EDA in the company?
-category:
-  id: Learning
-  label: Learning
-  icon: GraduationCap
----
-
-
-
-At FlowMart, we adhere to several best practices to ensure our Event-Driven Architecture (EDA) is robust, scalable, and maintainable. Here are the key guidelines:
-
-### Event Naming and Structure
-
-*   **Past Tense Naming:** All event names MUST be in the past tense (e.g., `OrderCreated`, `UserLoggedIn`, `PaymentProcessed`). This reflects that an event represents something that has already occurred.
-*   **Correlation IDs:** Every event MUST include a `correlationId`. This allows us to track related events across different services and flows, which is crucial for debugging and observability.
-*   **Clear Event Payloads:** Event payloads should be well-defined, documented, and contain only the necessary information relevant to the event itself. Avoid overly large or generic payloads.
-
-### Contract Management and Ownership
-
-*   **Producer Ownership:** The service that produces an event owns its contract (schema). Consumers should rely on this defined contract.
-*   **Public vs. Private Events:** Events MUST be explicitly marked as either `public` or `private`.
-    *   `Public` events have strong backward compatibility guarantees.
-    *   `Private` events are typically for internal service use and may have less stringent compatibility requirements, but changes should still be coordinated.
-*   **No Breaking Changes (Public Events):** We strive to avoid breaking changes in `public` event contracts. If a change is necessary, it must be additive or managed through versioning.
-*   **Semantic Versioning (SemVer):** Event schemas SHOULD follow Semantic Versioning (e.g., `1.0.0`, `1.1.0`, `2.0.0`).
-    *   MAJOR version bumps indicate breaking changes (avoided for public events).
-    *   MINOR version bumps indicate backward-compatible additions.
-    *   PATCH version bumps indicate backward-compatible fixes.
-
-### Design Principles
-
-*   **Idempotent Consumers:** Consumers should be designed to be idempotent, meaning they can safely process the same event multiple times without unintended side effects. This handles scenarios like message replays or network issues.
-*   **Asynchronous Communication:** Favor asynchronous communication patterns. Events decouple services, allowing them to operate independently.
-*   **Domain-Driven Design (DDD):** Align events with bounded contexts and domain concepts from DDD. This helps create meaningful, cohesive events.
-*   **Schema Registry:** Utilize a schema registry (like the one provided by EventCatalog!) to manage, validate, and evolve event schemas centrally.
-
-### Documentation and Discovery
-
-*   **EventCatalog:** All events, schemas, producers, and consumers MUST be documented in our EventCatalog. This serves as the single source of truth for our EDA landscape.
-*   **Clear Descriptions:** Provide clear, concise descriptions for each event, explaining its purpose and context.
-
-By following these practices, we aim to build a resilient and understandable event-driven ecosystem at FlowMart.
diff --git a/examples/default/chat-prompts/learning/what-events-are-relevant-to-this-feature.mdx b/examples/default/chat-prompts/learning/what-events-are-relevant-to-this-feature.mdx
deleted file mode 100644
index 6f6328e28..000000000
--- a/examples/default/chat-prompts/learning/what-events-are-relevant-to-this-feature.mdx
+++ /dev/null
@@ -1,14 +0,0 @@
----
-title: What events are relevant to this feature?
-category:
-  id: Learning
-  label: Learning
-  icon: GraduationCap
-inputs: 
-  - id: feature-description
-    label: Feature Description
-    type: text-area
----
-
-
-What events are relevant to this feature `{{feature-description}}`?
\ No newline at end of file
diff --git a/examples/default/chat-prompts/quick-feedback/validate-this-schema.mdx b/examples/default/chat-prompts/quick-feedback/validate-this-schema.mdx
deleted file mode 100644
index f002950b3..000000000
--- a/examples/default/chat-prompts/quick-feedback/validate-this-schema.mdx
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Validate schema against FlowMart EDA best practices
-category:
-  id: Code Review
-  label: Code Review
-  icon: MessageSquareText
-inputs:
-  - id: schema
-    label: Schema
-    type: code
----
-
-Please review the following event schema:
-
-```json
-{{schema}}
-```
-
-Validate this schema against the FlowMart EDA best practices listed below and provide feedback on any areas where the schema does not align or could be improved based on these guidelines.
-
---- 
-
-## FlowMart EDA Best Practices for Reference:
-
-### Event Naming and Structure
-
-*   **Past Tense Naming:** All event names MUST be in the past tense (e.g., `OrderCreated`, `UserLoggedIn`, `PaymentProcessed`). This reflects that an event represents something that has already occurred.
-*   **Correlation IDs:** Every event MUST include a `correlationId`. This allows us to track related events across different services and flows, which is crucial for debugging and observability.
-*   **Clear Event Payloads:** Event payloads should be well-defined, documented, and contain only the necessary information relevant to the event itself. Avoid overly large or generic payloads.
-
-### Contract Management and Ownership
-
-*   **Producer Ownership:** The service that produces an event owns its contract (schema). Consumers should rely on this defined contract.
-*   **Public vs. Private Events:** Events MUST be explicitly marked as either `public` or `private`.
-    *   `Public` events have strong backward compatibility guarantees.
-    *   `Private` events are typically for internal service use and may have less stringent compatibility requirements, but changes should still be coordinated.
-*   **No Breaking Changes (Public Events):** We strive to avoid breaking changes in `public` event contracts. If a change is necessary, it must be additive or managed through versioning.
-*   **Semantic Versioning (SemVer):** Event schemas SHOULD follow Semantic Versioning (e.g., `1.0.0`, `1.1.0`, `2.0.0`).
-    *   MAJOR version bumps indicate breaking changes (avoided for public events).
-    *   MINOR version bumps indicate backward-compatible additions.
-    *   PATCH version bumps indicate backward-compatible fixes.
-
-### Design Principles
-
-*   **Idempotent Consumers:** Consumers should be designed to be idempotent, meaning they can safely process the same event multiple times without unintended side effects. This handles scenarios like message replays or network issues.
-*   **Asynchronous Communication:** Favor asynchronous communication patterns. Events decouple services, allowing them to operate independently.
-*   **Domain-Driven Design (DDD):** Align events with bounded contexts and domain concepts from DDD. This helps create meaningful, cohesive events.
-*   **Schema Registry:** Utilize a schema registry (like the one provided by EventCatalog!) to manage, validate, and evolve event schemas centrally.
-
-### Documentation and Discovery
-
-*   **EventCatalog:** All events, schemas, producers, and consumers MUST be documented in our EventCatalog. This serves as the single source of truth for our EDA landscape.
-*   **Clear Descriptions:** Provide clear, concise descriptions for each event, explaining its purpose and context.
-
-By following these practices, we aim to build a resilient and understandable event-driven ecosystem at FlowMart.
diff --git a/examples/default/components/footer.astro b/examples/default/components/footer.astro
index 680e6c1b4..7284e2724 100644
--- a/examples/default/components/footer.astro
+++ b/examples/default/components/footer.astro
@@ -3,6 +3,5 @@ import config from '@config';
 ---
 
 <div class="w-full text-right">
-  <span class="italic text-gray-800">Event-driven architecture documentation: {config.organizationName}</span>
+  <span class="italic text-[rgb(var(--ec-page-text-muted))]">Event-driven architecture documentation: {config.organizationName}</span>
 </div>
-
diff --git a/examples/default/docs/domains/01-catalog-and-search.mdx b/examples/default/docs/domains/01-catalog-and-search.mdx
new file mode 100644
index 000000000..4ccfb3ed3
--- /dev/null
+++ b/examples/default/docs/domains/01-catalog-and-search.mdx
@@ -0,0 +1,46 @@
+---
+title: Catalog and search
+summary: How product data is owned by the Product Catalog System and projected into Search for customer discovery.
+owners:
+  - product-platform
+badges:
+  - content: Domain guide
+    backgroundColor: blue
+    textColor: blue
+---
+
+[[domain|catalog]] owns the product information that customers browse and buy. It is split into two systems with different consistency needs.
+
+## System context map
+
+<NodeGraph id="catalog" version="1.0.0" type="domain" maxHeight={34} mode="simple" />
+
+## Product Catalog System
+
+[[system|product-catalog-system]] is the source of truth. [[service|product-api]] handles product commands and reads from [[container|product-database]]. Product changes are captured through an outbox and published by [[service|product-search-publisher]].
+
+Key contracts:
+
+- [[command|create-product]]
+- [[command|update-product]]
+- [[command|delete-product]]
+- [[query|get-product]]
+- [[event|product-created]]
+- [[event|product-updated]]
+- [[event|product-deleted]]
+
+## Search System
+
+[[system|search-system]] serves product discovery through [[service|search-api]] and [[query|search-products]]. It maintains [[container|search-index]] from product events.
+
+The Search System should be treated as eventually consistent with the Product Catalog System. If a merchandiser updates a product, the product database is immediately authoritative; search visibility follows after indexing.
+
+## Decision context
+
+The product catalog has several architecture decisions documented directly on the system:
+
+- [[adr|adr-001-use-transactional-outbox]]
+- [[adr|adr-002-postgres-as-system-of-record]]
+- [[adr|adr-003-offload-async-work-to-worker]]
+
+These decisions explain why product events are published asynchronously and why Postgres remains the system of record.
diff --git a/examples/default/docs/domains/02-shopping-and-promotions.mdx b/examples/default/docs/domains/02-shopping-and-promotions.mdx
new file mode 100644
index 000000000..442e045a1
--- /dev/null
+++ b/examples/default/docs/domains/02-shopping-and-promotions.mdx
@@ -0,0 +1,38 @@
+---
+title: Shopping and promotions
+summary: How carts, checkout intent and discount calculation are modelled in the Shopping domain.
+owners:
+  - shopping-platform
+badges:
+  - content: Domain guide
+    backgroundColor: blue
+    textColor: blue
+---
+
+[[domain|shopping]] owns the customer's active path to purchase before an order exists. The core state is the cart, not the order.
+
+## System context map
+
+<NodeGraph id="shopping" version="1.0.0" type="domain" maxHeight={34} mode="simple" />
+
+## Cart System
+
+[[system|cart-system]] owns cart state in [[container|cart-database]]. [[service|cart-api]] handles:
+
+- [[command|add-item-to-cart]]
+- [[command|remove-item-from-cart]]
+- [[command|checkout-cart]]
+
+When a cart is checked out, it publishes [[event|cart-checked-out]]. That event is the handoff from Shopping to Ordering.
+
+## Promotion System
+
+[[system|promotion-system]] owns promotion rules in [[container|promotion-database]]. It handles [[command|calculate-discount]] and publishes [[event|discount-calculated]].
+
+Discount calculation is deliberately separate from cart persistence. The Cart System owns what the customer is buying; the Promotion System owns how discounts are evaluated.
+
+## Boundary with Ordering
+
+Shopping does not create orders. Once [[event|cart-checked-out]] is published, [[system|checkout-system]] takes responsibility for coordinating inventory, payment and order creation.
+
+This boundary keeps cart behavior and order lifecycle behavior independent. It also gives checkout a clear recovery point if inventory or payment fails.
diff --git a/examples/default/docs/domains/03-ordering-and-checkout.mdx b/examples/default/docs/domains/03-ordering-and-checkout.mdx
new file mode 100644
index 000000000..8d14abc88
--- /dev/null
+++ b/examples/default/docs/domains/03-ordering-and-checkout.mdx
@@ -0,0 +1,52 @@
+---
+title: Ordering and checkout
+summary: How the Ordering domain coordinates checkout and owns the order lifecycle.
+owners:
+  - ordering-platform
+badges:
+  - content: Domain guide
+    backgroundColor: red
+    textColor: red
+---
+
+[[domain|ordering]] is the core revenue domain. It turns a checked-out cart into a durable order and owns that order through completion or cancellation.
+
+## System context map
+
+<NodeGraph id="ordering" version="1.0.0" type="domain" maxHeight={36} mode="simple" />
+
+## Checkout System
+
+[[system|checkout-system]] owns orchestration. [[service|checkout-api]] receives checkout intent, and [[service|checkout-orchestrator]] runs the [[flow|checkout-saga]].
+
+The saga coordinates:
+
+1. [[command|reserve-inventory]]
+2. [[command|authorize-payment]]
+3. [[command|create-order]]
+
+If a step fails, the orchestrator compensates rather than leaving partial work behind.
+
+<Flow id="checkout-saga" version="1.0.0" maxHeight={34} />
+
+## Order Management System
+
+[[system|order-management-system]] owns order state in [[container|order-database]]. [[service|order-service]] handles [[command|create-order]], [[command|cancel-order]] and [[query|get-order]].
+
+It publishes:
+
+- [[event|order-created]]
+- [[event|order-completed]]
+- [[event|order-cancelled]]
+
+## Operating guidance
+
+Do not add payment or inventory state directly to orders unless it is a snapshot needed for audit or customer support. The owning systems remain [[system|payment-processing-system]] and [[system|inventory-system]].
+
+When checkout behavior changes, update the [[flow|place-an-order]] and [[flow|checkout-saga]] pages as well as the command schemas.
+
+<Prompt description="Assess an Ordering domain change" actions={['copy', 'cursor']} icon="clipboard-check">
+  Review a proposed Ordering domain change for Acme Inc. Identify whether it changes checkout orchestration, order state, payment
+  or inventory boundaries, customer-visible status, command schemas, event schemas or downstream fulfilment behavior. Return the
+  affected catalog resources and the teams that should review the change.
+</Prompt>
diff --git a/examples/default/docs/domains/04-payments-and-fraud.mdx b/examples/default/docs/domains/04-payments-and-fraud.mdx
new file mode 100644
index 000000000..cda063532
--- /dev/null
+++ b/examples/default/docs/domains/04-payments-and-fraud.mdx
@@ -0,0 +1,39 @@
+---
+title: Payments and fraud
+summary: How payment authorization, Stripe integration, refunds and fraud screening are represented in the Payments domain.
+owners:
+  - payments-platform
+badges:
+  - content: Domain guide
+    backgroundColor: red
+    textColor: red
+---
+
+[[domain|payments]] owns payment intent and payment outcomes. It integrates with external providers but keeps Acme's internal payment state in [[container|payment-database]].
+
+## System context map
+
+<NodeGraph id="payments" version="1.0.0" type="domain" maxHeight={34} mode="simple" />
+
+## Payment Processing System
+
+[[system|payment-processing-system]] is composed of [[service|payment-api]] and [[service|payment-worker]].
+
+[[service|payment-api]] receives [[command|authorize-payment]] from checkout and records the intent. [[service|payment-worker]] drives the external charge/refund process and records outcomes.
+
+Important events:
+
+- [[event|payment-requested]]
+- [[event|payment-succeeded]]
+- [[event|payment-failed]]
+- [[event|refund-requested]]
+
+## External providers
+
+[[system|stripe]] is the external payment processor. It reports outcomes through [[service|stripe-webhook-endpoint]] events such as [[event|payment-succeeded]], [[event|payment-failed]] and [[event|refund-processed]].
+
+[[system|fraud-detection]] screens payment attempts and reports [[event|fraud-check-passed]] or [[event|fraud-check-failed]].
+
+## Failure handling
+
+Payments cross external boundaries, so every step should be durable and retryable. Do not assume webhook delivery order. Payment state transitions should be idempotent and traceable through the payment database.
diff --git a/examples/default/docs/domains/05-fulfilment-and-shipping.mdx b/examples/default/docs/domains/05-fulfilment-and-shipping.mdx
new file mode 100644
index 000000000..758489dab
--- /dev/null
+++ b/examples/default/docs/domains/05-fulfilment-and-shipping.mdx
@@ -0,0 +1,36 @@
+---
+title: Fulfilment and shipping
+summary: How stock reservation, warehouse packing and carrier handoff work after an order is completed.
+owners:
+  - fulfilment-platform
+badges:
+  - content: Domain guide
+    backgroundColor: blue
+    textColor: blue
+---
+
+[[domain|fulfilment]] gets confirmed orders to customers. It owns the operational handoff from stock reservation through warehouse work and carrier delivery.
+
+## System context map
+
+<NodeGraph id="fulfilment" version="1.0.0" type="domain" maxHeight={36} mode="simple" />
+
+## Inventory System
+
+[[system|inventory-system]] owns [[container|inventory-database]]. [[service|inventory-service]] handles [[command|reserve-inventory]], [[command|release-inventory]] and [[query|get-stock-level]].
+
+It publishes [[event|inventory-reserved]] or [[event|inventory-unavailable]] during checkout.
+
+## Warehouse System
+
+[[system|warehouse-system]] owns picking and packing in [[container|warehouse-database]]. [[service|warehouse-service]] reacts to [[event|order-completed]] and publishes [[event|order-ready-for-shipping]].
+
+[[service|picking-worker]] handles packing work and publishes [[event|order-packed]].
+
+## Shipping System and Carrier
+
+[[system|shipping-system]] creates shipments through [[command|create-shipment]]. [[system|carrier]] is the external delivery provider and reports [[event|shipment-created]], [[event|shipment-delivered]] or [[event|shipment-failed]].
+
+## Boundary with Ordering
+
+Ordering decides that an order exists. Fulfilment decides whether and how it can be delivered. Keep these lifecycles separate so cancellation, refunds and shipment exceptions can be handled independently.
diff --git a/examples/default/docs/domains/06-customer-and-identity.mdx b/examples/default/docs/domains/06-customer-and-identity.mdx
new file mode 100644
index 000000000..f805771ec
--- /dev/null
+++ b/examples/default/docs/domains/06-customer-and-identity.mdx
@@ -0,0 +1,36 @@
+---
+title: Customer and identity
+summary: How customer profiles and authentication are separated across Customer Management and Identity Provider systems.
+owners:
+  - customer-platform
+badges:
+  - content: Domain guide
+    backgroundColor: blue
+    textColor: blue
+---
+
+[[domain|customer]] owns customer profile data and customer authentication. The catalog separates profile management from identity management so customer details and credentials have different operational boundaries.
+
+## System context map
+
+<NodeGraph id="customer" version="1.0.0" type="domain" maxHeight={34} mode="simple" />
+
+## Customer Management System
+
+[[system|customer-management-system]] owns [[container|customer-database]]. [[service|customer-api]] handles:
+
+- [[command|register-customer]]
+- [[command|update-customer]]
+- [[query|get-customer]]
+
+It publishes [[event|customer-registered]] and [[event|customer-updated]] so other capabilities can react to profile changes.
+
+## Identity Provider
+
+[[system|identity-provider]] owns authentication state in [[container|user-directory]]. [[service|oauth-api]] handles [[command|authenticate-customer]] and emits [[event|customer-authenticated]].
+
+## Integration guidance
+
+Services that need customer profile details should use [[query|get-customer]] or consume customer events where a local read model is appropriate. Services that need authentication should integrate with the identity boundary, not the profile database.
+
+This split prevents order, review and payment systems from accidentally depending on credential storage.
diff --git a/examples/default/docs/domains/07-reviews-and-ratings.mdx b/examples/default/docs/domains/07-reviews-and-ratings.mdx
new file mode 100644
index 000000000..ae27ac277
--- /dev/null
+++ b/examples/default/docs/domains/07-reviews-and-ratings.mdx
@@ -0,0 +1,43 @@
+---
+title: Reviews and ratings
+summary: How the Reviews domain accepts, moderates, publishes and aggregates product feedback.
+owners:
+  - reviews-platform
+badges:
+  - content: Domain guide
+    backgroundColor: purple
+    textColor: purple
+---
+
+[[domain|reviews]] owns customer feedback on products. Unlike the other domains, it is modelled directly with services and data stores rather than nested systems.
+
+## Domain map
+
+<NodeGraph id="reviews" version="1.0.0" type="domain" maxHeight={34} mode="simple" />
+
+## Services
+
+[[service|review-api]] accepts review commands and serves product reviews. It writes to [[container|review-database]] and reads aggregate data from [[container|rating-cache]].
+
+[[service|review-moderation-worker]] consumes [[event|review-submitted]] and publishes either [[event|review-published]] or [[event|review-rejected]].
+
+[[service|rating-aggregator]] reacts to published reviews and updates the product rating model, publishing [[event|rating-updated]].
+
+## Core entity
+
+[[entity|review]] is the central aggregate. It moves from submitted to moderated to published or rejected.
+
+<EntityMap id="reviews" version="1.0.0" title="Reviews entity map" maxHeight={28} />
+
+## Customer interactions
+
+Customers can submit, flag and vote on reviews:
+
+- [[command|submit-review]]
+- [[command|flag-review]]
+- [[command|vote-review-helpful]]
+- [[query|get-product-reviews]]
+
+## Product impact
+
+Reviews influence product discovery and conversion, but they do not own product data. Product identity remains in [[domain|catalog]], while review state remains in Reviews.
diff --git a/examples/default/docs/flows/01-place-an-order.mdx b/examples/default/docs/flows/01-place-an-order.mdx
new file mode 100644
index 000000000..1b7396811
--- /dev/null
+++ b/examples/default/docs/flows/01-place-an-order.mdx
@@ -0,0 +1,43 @@
+---
+title: Place an order
+summary: The end-to-end customer purchase journey from cart checkout to confirmed order and downstream fulfilment.
+owners:
+  - ordering-platform
+badges:
+  - content: Flow
+    backgroundColor: orange
+    textColor: orange
+---
+
+[[flow|place-an-order]] is the highest-value customer journey in the catalog. It spans [[domain|shopping]], [[domain|ordering]], [[domain|payments]] and [[domain|fulfilment]].
+
+## Flow map
+
+<Flow id="place-an-order" version="1.0.0" maxHeight={36} />
+
+## Happy path
+
+1. The customer checks out through [[service|cart-api]] using [[command|checkout-cart]].
+2. [[service|cart-api]] publishes [[event|cart-checked-out]].
+3. [[service|checkout-api]] and [[service|checkout-orchestrator]] start checkout orchestration.
+4. [[service|checkout-orchestrator]] reserves inventory with [[command|reserve-inventory]].
+5. It authorizes payment with [[command|authorize-payment]].
+6. It creates the order with [[command|create-order]].
+7. [[service|order-service]] publishes [[event|order-created]] and eventually [[event|order-completed]].
+8. Fulfilment consumes completed orders and prepares shipment.
+
+## Important boundaries
+
+The flow crosses several ownership boundaries. Shopping owns the cart, Ordering owns the order, Payments owns payment outcome, and Fulfilment owns stock and shipping. Each handoff is a contract boundary.
+
+## Failure points
+
+The two most important failure points are inventory and payment. If [[command|reserve-inventory]] or [[command|authorize-payment]] fails, checkout must compensate and avoid creating an order.
+
+<Prompt description="Analyze checkout impact" actions={["copy", "cursor"]} icon="route">
+  Review the Acme place-an-order flow and identify the operational impact of a checkout change. Focus on cart checkout,
+  inventory reservation, payment authorization, order creation, fulfilment handoff, compensation behavior and teams that
+  need to review the change. Return a concise impact checklist with risks and required catalog updates.
+</Prompt>
+
+Use [[flow|checkout-saga]] for the detailed orchestration view.
diff --git a/examples/default/docs/flows/02-checkout-saga.mdx b/examples/default/docs/flows/02-checkout-saga.mdx
new file mode 100644
index 000000000..18a2df3c8
--- /dev/null
+++ b/examples/default/docs/flows/02-checkout-saga.mdx
@@ -0,0 +1,48 @@
+---
+title: Checkout saga
+summary: The orchestration pattern used by checkout to coordinate inventory reservation, payment authorization and order creation.
+owners:
+  - ordering-platform
+badges:
+  - content: Flow
+    backgroundColor: orange
+    textColor: orange
+---
+
+[[flow|checkout-saga]] is the detailed orchestration inside [[system|checkout-system]]. It exists because checkout cannot be a single local transaction: inventory, payment and order state are owned by different systems.
+
+## Flow map
+
+<Flow id="checkout-saga" version="1.0.0" maxHeight={36} />
+
+## Saga steps
+
+| Step | Contract | Owner |
+|------|----------|-------|
+| Reserve inventory | [[command\|reserve-inventory]] | [[system\|inventory-system]] |
+| Authorize payment | [[command\|authorize-payment]] | [[system\|payment-processing-system]] |
+| Create order | [[command\|create-order]] | [[system\|order-management-system]] |
+
+## Success condition
+
+Checkout succeeds only when inventory is reserved, payment is authorized and an order is created. The durable outcome is an order in [[container|order-database]] and subsequent [[event|order-created]] publication.
+
+## Compensation
+
+If inventory is unavailable or payment is declined, checkout should not create an order. The orchestrator should release any previous reservation or void any authorization as needed.
+
+## Change guidance
+
+Adding a checkout step means updating:
+
+- the flow definition,
+- the orchestrator implementation,
+- the command/event contracts,
+- failure and compensation behavior,
+- customer-facing status semantics.
+
+<Prompt description="Review saga compensation" actions={["copy", "cursor"]} icon="shield-check">
+  Review this checkout saga change as a senior distributed systems engineer. Check whether every step has a clear owner,
+  success condition, failure condition, retry policy, compensation action and customer-visible status. Call out any
+  missing contracts or catalog pages that should be updated before release.
+</Prompt>
diff --git a/examples/default/docs/flows/03-product-search-indexing.mdx b/examples/default/docs/flows/03-product-search-indexing.mdx
new file mode 100644
index 000000000..850e9d796
--- /dev/null
+++ b/examples/default/docs/flows/03-product-search-indexing.mdx
@@ -0,0 +1,38 @@
+---
+title: Product search indexing
+summary: How product catalog changes are projected into the Search System for customer-facing search.
+owners:
+  - search-platform
+badges:
+  - content: Flow
+    backgroundColor: orange
+    textColor: orange
+---
+
+[[flow|product-search-indexing]] keeps product search aligned with catalog changes. It is intentionally asynchronous: product writes should not wait for search indexing to complete.
+
+## Flow map
+
+<Flow id="product-search-indexing" version="1.0.0" maxHeight={36} />
+
+## Producers
+
+[[system|product-catalog-system]] owns product data. Product changes are represented by:
+
+- [[event|product-created]]
+- [[event|product-updated]]
+- [[event|product-deleted]]
+
+These events are published by services inside the Product Catalog System, including [[service|product-search-publisher]].
+
+## Consumers
+
+[[system|search-system]] consumes product change events and updates [[container|search-index]]. [[service|search-api]] then serves [[query|search-products]] against that index.
+
+## Consistency model
+
+The product database is immediately authoritative. The search index is eventually consistent. User interfaces should tolerate a short delay between product update and search result update.
+
+## Operational signals
+
+Watch for indexing lag, failed event handling and search query errors. A stale search index affects product discovery even when product writes are healthy.
diff --git a/examples/default/docs/flows/04-review-submission.mdx b/examples/default/docs/flows/04-review-submission.mdx
new file mode 100644
index 000000000..e9c3f54e5
--- /dev/null
+++ b/examples/default/docs/flows/04-review-submission.mdx
@@ -0,0 +1,37 @@
+---
+title: Review submission
+summary: How product reviews are submitted, moderated, published and aggregated into ratings.
+owners:
+  - reviews-platform
+badges:
+  - content: Flow
+    backgroundColor: orange
+    textColor: orange
+---
+
+[[flow|review-submission]] captures the lifecycle of customer product feedback.
+
+## Flow map
+
+<Flow id="review-submission" version="1.0.0" maxHeight={36} />
+
+## Flow stages
+
+1. A customer submits a review through [[service|review-api]] using [[command|submit-review]].
+2. [[service|review-api]] stores the review in [[container|review-database]] and publishes [[event|review-submitted]].
+3. [[service|review-moderation-worker]] evaluates the review.
+4. The worker publishes [[event|review-published]] or [[event|review-rejected]].
+5. [[service|rating-aggregator]] consumes published reviews and updates [[container|rating-cache]].
+6. [[service|review-api]] serves [[query|get-product-reviews]] for storefront reads.
+
+## Moderation boundary
+
+Moderation is asynchronous so submission remains responsive and moderation rules can evolve independently.
+
+## Rating boundary
+
+Ratings are a read model. [[container|rating-cache]] is optimised for product pages, while [[container|review-database]] remains the durable review store.
+
+## Follow-up interactions
+
+After publication, customers can use [[command|vote-review-helpful]] or [[command|flag-review]]. These interactions publish [[event|review-helpful-voted]] and [[event|review-flagged]].
diff --git a/examples/default/docs/guides/creating-new-microservices/01-index.mdx b/examples/default/docs/guides/creating-new-microservices/01-index.mdx
deleted file mode 100644
index e06518e50..000000000
--- a/examples/default/docs/guides/creating-new-microservices/01-index.mdx
+++ /dev/null
@@ -1,95 +0,0 @@
----
-title: Creating new microservices
-summary: A comprehensive guide to creating new microservices at FlowMart following our best practices and standards
-sidebar:
-    label: Introduction
-    order: 1
-owners: 
-  - dboyne
-badges:
-  - content: 'Guide'
-    backgroundColor: 'teal'
-    textColor: 'teal'
----
-
-Welcome to the FlowMart microservices creation guide. This documentation will help you understand our microservices architecture and guide you through the process of creating, deploying, and maintaining new services that align with our architectural standards and best practices.
-
-## FlowMart's Microservices Architecture
-
-At FlowMart, we've adopted an [Event-**Driven** Architecture (EDA)](/docs/architecture-records/published/02-eda-adoption) for our e-commerce platform. Our architecture consists of domain-oriented microservices that communicate primarily through events, with Apache Kafka serving as our event backbone.
-
-Key architectural principles we follow:
-
-- **Domain-Driven Design**: **Services** are organized around business domains with clear bounded contexts
-- **Service Autonomy**: Each service owns its data and can be independently deployed
-- **Event-First Communication**: Services publish events when state changes and subscribe to events from other domains
-- **Eventual Consistency**: We prioritize availability and partition tolerance over immediate consistency
-- **API-First Development**: All services expose well-defined APIs using standardized patterns
-
-## Example service in our architecture (InventoryService)
-<NodeGraph id="InventoryService" version="0.0.2" type="service"  />
-
-## Example of event stream in our architecture
-
-If you look at the example service in our architecture, you can see that it has a single event stream. This is a simple example of how we use event streams to communicate between services.
-
-<Design file="event-stream-example" search={false} />
-
-
-## Getting Started
-
-Before creating a new microservice, please familiarize yourself with our architectural decisions:
-
-1. [Event-Driven Architecture Adoption](/docs/architecture-records/published/02-eda-adoption)
-2. [API Gateway Pattern Adoption](/docs/architecture-records/published/01-api-gateway-pattern)
-3. [CI/CD and Deployment Strategy](/docs/architecture-records/drafts/02-cicd-deployment-strategy)
-4. [API Management and Governance](/docs/architecture-records/drafts/03-api-management-governance)
-
-## Service Creation Process
-
-The following steps outline our microservice creation process:
-
-1. **Domain Analysis**: Identify the business domain and define the bounded context
-2. **Service Definition**: Create service specification using our templating tools
-3. **Infrastructure Provisioning**: Use our Terraform modules to provision required infrastructure
-4. **Service Implementation**: Develop the service following our technological standards
-5. **CI/CD Pipeline Setup**: Configure the service pipeline for continuous integration and deployment
-6. **Testing**: Implement comprehensive testing (unit, integration, contract, end-to-end)
-7. **Documentation**: Document API contracts, event schemas, and service behaviors
-8. **Deployment**: Deploy to production using our GitOps workflow
-
-## Available Service Templates
-
-We provide several starter templates for new microservices:
-
-- [Node.js Service Template](/docs/guides/creating-new-microservices/node-service)
-- [TypeScript Service Template](/docs/guides/creating-new-microservices/typescript-service)
-- [Java Spring Boot Template](/docs/guides/creating-new-microservices/java-spring-boot)
-- [Python FastAPI Template](/docs/guides/creating-new-microservices/python-fastapi)
-
-## Infrastructure as Code
-
-All FlowMart infrastructure is managed using [Terraform](/docs/guides/creating-new-microservices/terraform-modules). We maintain a set of reusable modules for common infrastructure components, which you should leverage when creating new services.
-
-## Development Workflow
-
-1. **Engage with the Platform Team**: Discuss your new service requirements with the platform team
-2. **Create Service Repository**: Use our GitLab template to create a new service repository
-3. **Setup Local Environment**: Configure your local development environment
-4. **Implement Core Functionality**: Develop the service capabilities
-5. **Review and Testing**: Submit for architecture and code review
-6. **Deploy to Production**: Use our deployment pipeline for production rollout
-
-## Support
-
-If you need assistance creating a new microservice, please reach out to:
-
-- **Platform Engineering Team**: For infrastructure and deployment questions
-- **Architecture Team**: For design and architecture guidance
-- **DevOps Team**: For CI/CD and operational support
-
-## Next Steps
-
-- Continue to [Service Design Principles](/docs/guides/creating-new-microservices/service-design-principles)
-- Learn about [Node.js Service Creation](/docs/guides/creating-new-microservices/node-service)
-- Explore our [Terraform Modules](/docs/guides/creating-new-microservices/terraform-modules) 
\ No newline at end of file
diff --git a/examples/default/docs/guides/creating-new-microservices/02-service-design-principles.mdx b/examples/default/docs/guides/creating-new-microservices/02-service-design-principles.mdx
deleted file mode 100644
index b1346ab84..000000000
--- a/examples/default/docs/guides/creating-new-microservices/02-service-design-principles.mdx
+++ /dev/null
@@ -1,143 +0,0 @@
----
-title: Microservice Design Principles
-summary: Core design principles and best practices for creating well-structured microservices at FlowMart
-sidebar:
-    label: Design Principles
-    order: 2
----
-
-At FlowMart, we follow a set of design principles that guide the creation of new microservices. These principles help ensure our services are maintainable, scalable, and aligned with our overall architectural vision.
-
-## 1. Domain-Driven Design
-
-Each microservice should be aligned with a specific business domain or subdomain. We follow Domain-Driven Design (DDD) principles to identify service boundaries:
-
-### Bounded Contexts
-
-- Define clear bounded contexts for each service
-- Maintain a separate ubiquitous language within each context
-- Document domain models and context maps
-
-### Example Domains at FlowMart
-
-| Domain | Description | Example Services |
-|--------|-------------|------------------|
-| Order | Order processing and management | order-service, order-history-service |
-| Inventory | Product inventory management | inventory-service, stock-management-service |
-| Customer | Customer accounts and profiles | customer-service, authentication-service |
-| Payment | Payment processing and refunds | payment-service, refund-service |
-| Shipping | Shipping and logistics | shipping-service, tracking-service |
-| Catalog | Product information management | product-service, search-service |
-
-## 2. Single Responsibility
-
-Each microservice should have a single responsibility and a clear purpose:
-
-- **Focus on one business capability**: Services should do one thing well
-- **Right-sized services**: Not too large (mini-monolith) or too small (nano-service)
-- **Cohesive functionality**: Related functions should be grouped together
-
-## 3. Data Ownership
-
-Microservices should own their data and maintain data autonomy:
-
-- Each service has its own database or data store
-- No direct data sharing between services
-- Data is exposed through well-defined APIs
-- Services should be the single source of truth for their domain data
-
-## 4. API Design
-
-All FlowMart microservices must follow our [API Management and Governance Strategy](/docs/architecture-records/drafts/03-api-management-governance):
-
-### RESTful APIs
-
-- Use consistent resource naming conventions
-- Follow standard HTTP methods and status codes
-- Implement proper error handling and validation
-- Design for backward compatibility
-
-### Event-Driven Interfaces
-
-- Define clear event schemas using AsyncAPI
-- Document event ownership and responsibilities
-- Follow event versioning standards
-- Implement idempotent event consumers
-
-## 5. Resilience and Fault Tolerance
-
-Microservices must be designed to handle failures gracefully:
-
-- Implement circuit breakers for downstream dependencies
-- Use timeouts and retries with exponential backoff
-- Design for graceful degradation of functionality
-- Implement health checks and readiness probes
-
-## 6. Observability
-
-All services must expose monitoring and observability data:
-
-- Structured logging (using our ELK stack)
-- Metrics exposure (Prometheus format)
-- Distributed tracing support (Jaeger)
-- Health check endpoints
-
-## 7. Security by Design
-
-Security must be integrated into every service:
-
-- Authentication using OAuth 2.0 / OpenID Connect
-- Authorization using role-based access control
-- TLS encryption for all communications
-- Input validation and output encoding
-- No sensitive data in logs or traces
-
-## 8. Testability
-
-Services should be designed with testing in mind:
-
-- High unit test coverage (minimum 80%)
-- Integration tests for all critical paths
-- Contract tests for API interfaces
-- Easy local testing setup
-- Simulated dependencies for development
-
-## 9. Configuration Management
-
-Services should follow our configuration management approach:
-
-- Environment-specific configuration via Kubernetes ConfigMaps
-- Secrets management via HashiCorp Vault
-- Feature flags for conditional functionality
-- No hardcoded configuration values
-
-## 10. Independence and Deployability
-
-Services should be independently deployable:
-
-- No deployment coupling with other services
-- Infrastructure as Code for all resources
-- Self-contained CI/CD pipelines
-- Blue/green or canary deployment capabilities
-
-## Microservice Checklist
-
-Use this checklist when designing a new service:
-
-- [ ] Service aligns with a specific business domain
-- [ ] Clear bounded context defined
-- [ ] Service owns its data
-- [ ] APIs follow company standards
-- [ ] Event schemas are documented
-- [ ] Resilience patterns implemented
-- [ ] Observability instrumentation added
-- [ ] Security controls integrated
-- [ ] Comprehensive test suite created
-- [ ] Configuration externalized
-- [ ] Independent deployment pipeline configured
-
-## Next Steps
-
-- Learn how to [create a Node.js microservice](/docs/guides/creating-new-microservices/node-service)
-- Explore [TypeScript service implementation](/docs/guides/creating-new-microservices/typescript-service)
-- Understand our [Terraform infrastructure modules](/docs/guides/creating-new-microservices/terraform-modules) 
\ No newline at end of file
diff --git a/examples/default/docs/guides/creating-new-microservices/03-database-patterns.mdx b/examples/default/docs/guides/creating-new-microservices/03-database-patterns.mdx
deleted file mode 100644
index d6841d246..000000000
--- a/examples/default/docs/guides/creating-new-microservices/03-database-patterns.mdx
+++ /dev/null
@@ -1,516 +0,0 @@
----
-title: Database Patterns for Microservices
-summary: Best practices and patterns for managing data in FlowMart microservices
-sidebar:
-    label: Database Patterns
-    order: 5
----
-
-This guide outlines the database patterns and best practices for managing data in FlowMart's microservices architecture.
-
-## Database Per Service Pattern
-
-At FlowMart, we follow the **Database Per Service** pattern as our primary data management strategy:
-
-- **Definition**: Each microservice owns and manages its database exclusively
-- **Access Pattern**: Only the service that owns the database can perform direct read/write operations
-- **Purpose**: Ensures loose coupling, independent scaling, and domain isolation
-
-![Database Per Service Diagram](/docs/images/database-per-service.png)
-
-### Why This Pattern?
-
-1. **Service Independence**: Services can be developed, deployed, and scaled independently
-2. **Technology Freedom**: Teams can choose the most appropriate database technology for their service needs
-3. **Resilience**: Database failures are isolated to individual services
-4. **Security**: Clear data ownership boundaries limit the blast radius of security incidents
-5. **Performance**: Database schemas and indexes can be optimized for specific service requirements
-
-## Supported Database Technologies
-
-FlowMart supports the following database technologies for microservices:
-
-| Database Type | Technology | Best For | Support Level |
-|--------------|------------|----------|---------------|
-| Document | MongoDB | Flexible schemas, rapid development | Primary |
-| Relational | PostgreSQL | Complex transactions, structured data | Primary |
-| Key-Value | Redis | Caching, session management, rate limiting | Primary |
-| Search | Elasticsearch | Full-text search, analytics | Secondary |
-| Graph | Neptune | Relationship-heavy domains (e.g., recommendations) | Secondary |
-| Time-Series | InfluxDB | Metrics, monitoring data | Secondary |
-
-> **Primary**: Fully supported with managed services, infrastructure modules, and dedicated support
-> 
-> **Secondary**: Available but with limited tooling and support
-
-## Data Modeling Principles
-
-### 1. Model Around Bounded Contexts
-
-- Define clear domain boundaries based on business capabilities
-- Avoid modeling your database around UI needs
-- Focus on the core domain model within each service
-
-### 2. Design for Access Patterns
-
-- Consider query patterns when designing the schema
-- Optimize for the most frequent queries
-- Plan for future data growth and access needs
-
-### 3. Denormalization When Appropriate
-
-- Strategic denormalization is often necessary in distributed systems
-- Consider composite keys for efficient lookups
-- Use materialized views for read-heavy scenarios
-
-### Example: Product Service Data Model (MongoDB)
-
-```javascript
-// Product Collection
-{
-  "_id": ObjectId("5f8d0f3e1c9d440000c9a1f5"),
-  "name": "Ultra HD Smart TV",
-  "description": "55-inch Ultra HD Smart TV with voice control",
-  "sku": "TV-55UHD-2023",
-  "price": {
-    "amount": 699.99,
-    "currency": "USD"
-  },
-  "category": "electronics",
-  "subcategory": "televisions",
-  "attributes": {
-    "brand": "TechVision",
-    "model": "UHD-55X",
-    "screenSize": "55",
-    "resolution": "3840x2160",
-    "smartFeatures": true,
-    "voiceControl": true,
-    "energyRating": "A+"
-  },
-  "images": [
-    {
-      "url": "https://storage.flowmart.com/products/tv-55uhd-2023-main.jpg",
-      "isPrimary": true,
-      "alt": "TechVision 55-inch Smart TV front view"
-    },
-    {
-      "url": "https://storage.flowmart.com/products/tv-55uhd-2023-side.jpg",
-      "isPrimary": false,
-      "alt": "TechVision 55-inch Smart TV side view"
-    }
-  ],
-  "inventory": {
-    "inStock": 127,
-    "reserved": 13,
-    "available": 114,
-    "lowStockThreshold": 25,
-    "lastUpdated": ISODate("2023-09-15T14:23:45.000Z")
-  },
-  "status": "active",
-  "createdAt": ISODate("2023-05-01T09:30:00.000Z"),
-  "updatedAt": ISODate("2023-09-15T14:23:45.000Z")
-}
-
-// Review Collection
-{
-  "_id": ObjectId("5f8d0f3e1c9d440000c9a1f9"),
-  "productId": ObjectId("5f8d0f3e1c9d440000c9a1f5"),
-  "customerId": "cust-12345",
-  "rating": 4.5,
-  "title": "Great TV for the price",
-  "content": "The picture quality is excellent and setup was easy...",
-  "verified": true,
-  "helpfulVotes": 27,
-  "createdAt": ISODate("2023-06-15T18:22:10.000Z")
-}
-```
-
-### Example: Order Service Data Model (PostgreSQL)
-
-```sql
--- Orders Table
-CREATE TABLE orders (
-  id UUID PRIMARY KEY,
-  customer_id VARCHAR(255) NOT NULL,
-  order_number VARCHAR(50) NOT NULL UNIQUE,
-  status VARCHAR(50) NOT NULL,
-  total_amount DECIMAL(10, 2) NOT NULL,
-  currency VARCHAR(3) NOT NULL,
-  shipping_address_id UUID NOT NULL,
-  billing_address_id UUID NOT NULL,
-  payment_method_id UUID,
-  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-
--- Order Items Table
-CREATE TABLE order_items (
-  id UUID PRIMARY KEY,
-  order_id UUID NOT NULL REFERENCES orders(id),
-  product_id VARCHAR(255) NOT NULL,
-  product_sku VARCHAR(100) NOT NULL,
-  product_name VARCHAR(255) NOT NULL,
-  quantity INTEGER NOT NULL,
-  unit_price DECIMAL(10, 2) NOT NULL,
-  subtotal DECIMAL(10, 2) NOT NULL,
-  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-
--- Indexes
-CREATE INDEX idx_orders_customer_id ON orders(customer_id);
-CREATE INDEX idx_orders_status ON orders(status);
-CREATE INDEX idx_order_items_order_id ON order_items(order_id);
-CREATE INDEX idx_order_items_product_id ON order_items(product_id);
-```
-
-## Data Consistency Patterns
-
-### 1. Eventual Consistency with Event-Driven Updates
-
-At FlowMart, we embrace eventual consistency for most inter-service data coordination:
-
-```mermaid
-sequenceDiagram
-    participant Order Service
-    participant Kafka
-    participant Inventory Service
-    participant Notification Service
-    
-    Order Service->>Order Service: Create Order
-    Order Service->>Kafka: Publish OrderCreated
-    Kafka->>Inventory Service: Consume OrderCreated
-    Inventory Service->>Inventory Service: Update Inventory
-    Kafka->>Notification Service: Consume OrderCreated
-    Notification Service->>Notification Service: Send Notification
-```
-
-### 2. Saga Pattern for Distributed Transactions
-
-For operations that span multiple services and require transactional semantics:
-
-```mermaid
-sequenceDiagram
-    participant Order Service
-    participant Payment Service
-    participant Inventory Service
-    participant Shipping Service
-    
-    Order Service->>Payment Service: Process Payment
-    Payment Service-->>Order Service: Payment Processed
-    Order Service->>Inventory Service: Reserve Inventory
-    Inventory Service-->>Order Service: Inventory Reserved
-    Order Service->>Shipping Service: Create Shipment
-    Shipping Service-->>Order Service: Shipment Created
-    
-    alt Failure at any step
-        Note over Order Service,Shipping Service: Begin compensating transactions
-        Order Service->>Payment Service: Refund Payment
-        Order Service->>Inventory Service: Release Inventory
-        Order Service->>Shipping Service: Cancel Shipment
-    end
-```
-
-### 3. CQRS (Command Query Responsibility Segregation)
-
-For services with complex read patterns or high read-to-write ratios:
-
-```
-┌───────────────┐     Commands     ┌───────────────┐
-│               │ ──────────────▶  │               │
-│   API Layer   │                  │ Command Model │
-│               │ ◀──────────────  │               │
-└───────────────┘                  └───────────────┘
-        │                                  │
-        │                                  │
-        │                                  ▼
-        │                          ┌───────────────┐
-        │                          │               │
-        │                          │  Event Store  │
-        │                          │               │
-        │                          └───────────────┘
-        │                                  │
-        │                                  │
-        ▼                                  ▼
-┌───────────────┐                  ┌───────────────┐
-│               │                  │               │
-│  Query Model  │ ◀──────────────  │ Event Handler │
-│               │                  │               │
-└───────────────┘                  └───────────────┘
-```
-
-## Data Migration Patterns
-
-### 1. Schema Evolution
-
-For incremental changes to a service's schema:
-
-- Add new fields with default values
-- Make changes backward compatible
-- Use database migration tools (e.g., Flyway, Liquibase, MongoDB migrations)
-
-Example migration script (Flyway):
-
-```sql
--- V2023.09.15.1__Add_Order_Tracking.sql
-ALTER TABLE orders ADD COLUMN tracking_number VARCHAR(100);
-ALTER TABLE orders ADD COLUMN shipping_carrier VARCHAR(50);
-```
-
-### 2. Expand-Contract Pattern (Parallel Change)
-
-For significant schema changes:
-
-1. **Expand**: Add new fields/tables while maintaining old ones
-2. **Migrate**: Copy/transform data from old to new structure
-3. **Contract**: Remove old fields/tables after migration is complete
-
-### 3. Service Decomposition
-
-When splitting a monolithic database:
-
-1. Identify bounded contexts
-2. Create new service databases
-3. Implement dual-write mechanism temporarily
-4. Migrate historical data
-5. Switch reads to the new database
-6. Remove old tables after migration completes
-
-## Database Access Patterns
-
-### Repository Pattern
-
-Our standard approach for database access:
-
-```typescript
-// Product Repository Interface
-export interface ProductRepository {
-  findById(id: string): Promise<Product | null>;
-  findByCategory(category: string, limit?: number, offset?: number): Promise<Product[]>;
-  findByQuery(query: ProductQuery): Promise<Product[]>;
-  save(product: Product): Promise<Product>;
-  update(id: string, updates: Partial<Product>): Promise<Product | null>;
-  delete(id: string): Promise<boolean>;
-}
-
-// MongoDB Implementation
-export class MongoProductRepository implements ProductRepository {
-  constructor(private readonly db: Db) {}
-  
-  async findById(id: string): Promise<Product | null> {
-    const result = await this.db.collection('products').findOne({ _id: new ObjectId(id) });
-    return result ? this.mapToProduct(result) : null;
-  }
-  
-  // Additional implementation methods...
-}
-
-// PostgreSQL Implementation
-export class PostgresProductRepository implements ProductRepository {
-  constructor(private readonly pool: Pool) {}
-  
-  async findById(id: string): Promise<Product | null> {
-    const result = await this.pool.query(
-      'SELECT * FROM products WHERE id = $1',
-      [id]
-    );
-    return result.rows.length ? this.mapToProduct(result.rows[0]) : null;
-  }
-  
-  // Additional implementation methods...
-}
-```
-
-## Connection Management
-
-### Connection Pooling
-
-```javascript
-// MongoDB Connection Pool (Node.js)
-const { MongoClient } = require('mongodb');
-
-class MongoDbClient {
-  constructor(config) {
-    this.client = new MongoClient(config.uri, {
-      maxPoolSize: config.maxPoolSize || 10,
-      minPoolSize: config.minPoolSize || 5,
-      maxIdleTimeMS: config.maxIdleTimeMS || 30000,
-      connectTimeoutMS: config.connectTimeoutMS || 5000
-    });
-  }
-  
-  async connect() {
-    await this.client.connect();
-    this.db = this.client.db(config.dbName);
-    console.log('Connected to MongoDB');
-    return this.db;
-  }
-  
-  async disconnect() {
-    await this.client.close();
-    console.log('Disconnected from MongoDB');
-  }
-}
-```
-
-### Health Checks
-
-```typescript
-// Database Health Check (TypeScript)
-export class DatabaseHealthCheck {
-  constructor(private readonly dbClient: DbClient) {}
-  
-  async check(): Promise<HealthStatus> {
-    try {
-      const startTime = Date.now();
-      await this.dbClient.ping();
-      const responseTime = Date.now() - startTime;
-      
-      return {
-        status: 'UP',
-        responseTime,
-        details: {
-          database: this.dbClient.getDatabaseName(),
-          connections: await this.dbClient.getConnectionStats()
-        }
-      };
-    } catch (error) {
-      return {
-        status: 'DOWN',
-        error: error.message,
-        details: {
-          database: this.dbClient.getDatabaseName()
-        }
-      };
-    }
-  }
-}
-```
-
-## Database Security Practices
-
-1. **Use IAM Roles/Service Accounts**: Avoid hardcoded credentials
-2. **Encryption**: Enable at-rest and in-transit encryption
-3. **No Direct Public Access**: Databases should never be directly exposed to the internet
-4. **Least Privilege**: Grant minimal required permissions to service accounts
-5. **Data Classification**: Tag data according to sensitivity
-6. **Audit Logging**: Enable database auditing for sensitive operations
-7. **Regular Backups**: Implement automated backup strategies
-8. **Secure Connection Strings**: Store connection information in secure vaults
-
-## Technology-Specific Guidelines
-
-### MongoDB Best Practices
-
-- Use document validation for schema enforcement
-- Create indexes for frequent query patterns
-- Limit document size (< 16MB)
-- Use aggregation pipelines for complex queries
-- Implement TTL indexes for expiring data
-
-### PostgreSQL Best Practices
-
-- Use connection pooling
-- Implement database partitioning for large tables
-- Create appropriate indexes based on query patterns
-- Use prepared statements to prevent SQL injection
-- Implement row-level security for multi-tenant data
-
-### Redis Best Practices
-
-- Set appropriate key expiration times
-- Use Redis data structures (not just key-value)
-- Implement Redis Cluster for high availability
-- Monitor memory usage
-- Use Redis for its strengths: caching, rate limiting, session storage
-
-## Infrastructure as Code for Databases
-
-FlowMart provides Terraform modules for common database setups:
-
-```hcl
-# MongoDB Atlas Cluster
-module "mongodb_cluster" {
-  source = "git::https://gitlab.flowmart.com/platform/terraform-modules//mongodb-atlas"
-  
-  project_id      = var.atlas_project_id
-  cluster_name    = "${var.service_name}-${var.environment}"
-  environment     = var.environment
-  instance_size   = var.environment == "production" ? "M10" : "M0"
-  region          = var.region
-  
-  backup_enabled = var.environment == "production" ? true : false
-  
-  teams = {
-    owner     = "team-product",
-    developer = "team-product-dev"
-  }
-  
-  tags = {
-    Service     = var.service_name
-    Environment = var.environment
-    ManagedBy   = "terraform"
-  }
-}
-
-# PostgreSQL RDS Instance
-module "postgres_db" {
-  source = "git::https://gitlab.flowmart.com/platform/terraform-modules//aws-rds-postgres"
-  
-  identifier          = "${var.service_name}-${var.environment}"
-  allocated_storage   = var.environment == "production" ? 100 : 20
-  storage_type        = "gp2"
-  engine_version      = "13.4"
-  instance_class      = var.environment == "production" ? "db.m5.large" : "db.t3.small"
-  database_name       = replace(var.service_name, "-", "_")
-  vpc_id              = var.vpc_id
-  subnet_ids          = var.database_subnet_ids
-  multi_az            = var.environment == "production" ? true : false
-  deletion_protection = var.environment == "production" ? true : false
-  
-  backup_retention_period = var.environment == "production" ? 7 : 1
-  
-  tags = {
-    Service     = var.service_name
-    Environment = var.environment
-    ManagedBy   = "terraform"
-  }
-}
-```
-
-## Data Governance
-
-### Practices for Maintaining Data Integrity
-
-1. **Schema Registry**: Register and validate event schemas
-2. **Data Catalogs**: Document available data and owners
-3. **Data Lineage**: Track how data flows between services
-4. **Data Quality Checks**: Implement validation and integrity checks
-5. **Master Data Management**: Establish source-of-truth services
-
-### GDPR and Compliance
-
-1. **Data Minimization**: Collect only necessary data
-2. **Right to Erasure**: Implement mechanisms to delete customer data
-3. **Data Portability**: Support data export in common formats
-4. **Consent Management**: Track and honor user consent
-5. **Purpose Limitation**: Use data only for its intended purpose
-
-## Recommended Resources
-
-- **Books**:
-  - "Database Internals" by Alex Petrov
-  - "Designing Data-Intensive Applications" by Martin Kleppmann
-
-- **Courses**:
-  - MongoDB University
-  - PostgreSQL Administration by EnterpriseDB
-
-- **FlowMart Resources**:
-  - Internal Database Patterns Playbook
-  - Monthly Database Office Hours
-
-## Next Steps
-
-- Learn about [Event schema design](/docs/guides/creating-new-microservices/event-schemas)
-- Explore [API design best practices](/docs/guides/creating-new-microservices/api-design)
-- Understand [Observability in microservices](/docs/guides/creating-new-microservices/observability) 
\ No newline at end of file
diff --git a/examples/default/docs/guides/creating-new-microservices/04-event-schemas.mdx b/examples/default/docs/guides/creating-new-microservices/04-event-schemas.mdx
deleted file mode 100644
index 9e6807d42..000000000
--- a/examples/default/docs/guides/creating-new-microservices/04-event-schemas.mdx
+++ /dev/null
@@ -1,894 +0,0 @@
----
-title: Event Schema Design
-summary: Best practices for designing and managing event schemas in FlowMart's event-driven architecture
-sidebar:
-    label: Event Schema Design
-    order: 6
----
-
-This guide outlines best practices for designing, evolving, and managing event schemas in FlowMart's event-driven architecture.
-
-## Introduction to Events in Our Architecture
-
-Events are the backbone of FlowMart's microservices ecosystem. They enable:
-
-- **Loose coupling** between services
-- **Asynchronous communication**
-- **Eventual consistency** across service boundaries
-- **Event sourcing** for critical business processes
-- **Audit trails** of system changes
-
-## Event Schema Fundamentals
-
-### What Is an Event Schema?
-
-An event schema defines the structure and validation rules for events flowing through our system. Properly designed schemas ensure events can be:
-
-- **Produced** consistently by services 
-- **Consumed** reliably by other services
-- **Evolved** over time without breaking consumers
-- **Validated** to prevent invalid data from propagating
-- **Documented** for developers to understand and use
-
-### Event Schema Registry
-
-FlowMart uses a centralized **Schema Registry** to:
-
-1. Store all event schemas
-2. Validate events at publish time
-3. Provide a browsable catalog of events
-4. Track schema versions and compatibility
-5. Generate client libraries and documentation
-
-All services must register their event schemas in the central registry before publishing events.
-
-## Schema Design Principles
-
-### 1. Design for Evolution
-
-Events should be designed to evolve over time:
-
-- **Additive Changes Only**: Add optional fields rather than modifying existing ones
-- **Required Minimal Core**: Keep required fields to essential business data
-- **Meaningful Defaults**: Provide sensible defaults for optional fields
-- **Version Awareness**: Include schema version information
-
-### 2. Event Ownership
-
-Each event type has a single owner:
-
-- The **producing service** owns the event schema
-- Only the owner can make changes to the schema
-- The owner is responsible for schema compatibility
-
-### 3. Semantic Versioning
-
-Follow semantic versioning for event schemas:
-
-- **Major Version**: Breaking changes (consumers must update)
-- **Minor Version**: Backward-compatible feature additions
-- **Patch Version**: Backward-compatible bug fixes
-
-### 4. Business-Oriented Event Naming
-
-Events should be named using business terminology:
-
-- Use past tense verbs (e.g., `OrderPlaced`, not `CreateOrder`)
-- Follow the pattern: `[Entity][Event]` (e.g., `ProductCreated`, `PaymentProcessed`)
-- Use domain-specific terminology consistent with our ubiquitous language
-
-## Event Schema Format (JSON Schema)
-
-FlowMart uses JSON Schema as the standard format for defining event schemas:
-
-```json
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://schemas.flowmart.com/events/product/ProductCreated/1.0.0",
-  "title": "ProductCreated",
-  "description": "Represents the creation of a new product in the catalog",
-  "type": "object",
-  "required": ["eventId", "eventType", "eventVersion", "timestamp", "data"],
-  "properties": {
-    "eventId": {
-      "type": "string",
-      "format": "uuid",
-      "description": "Unique identifier for this event instance"
-    },
-    "eventType": {
-      "type": "string",
-      "enum": ["ProductCreated"],
-      "description": "Type of the event"
-    },
-    "eventVersion": {
-      "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$",
-      "description": "Semantic version of the event schema"
-    },
-    "timestamp": {
-      "type": "string",
-      "format": "date-time",
-      "description": "ISO-8601 timestamp when the event was created"
-    },
-    "source": {
-      "type": "string",
-      "description": "Service that produced the event"
-    },
-    "data": {
-      "type": "object",
-      "required": ["productId", "name", "sku", "price"],
-      "properties": {
-        "productId": {
-          "type": "string",
-          "format": "uuid",
-          "description": "Unique identifier for the product"
-        },
-        "name": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 255,
-          "description": "Name of the product"
-        },
-        "description": {
-          "type": "string",
-          "maxLength": 2000,
-          "description": "Description of the product"
-        },
-        "sku": {
-          "type": "string",
-          "pattern": "^[A-Z0-9-]{5,20}$",
-          "description": "Stock keeping unit - unique product identifier"
-        },
-        "price": {
-          "type": "object",
-          "required": ["amount", "currency"],
-          "properties": {
-            "amount": {
-              "type": "number",
-              "exclusiveMinimum": 0,
-              "description": "Price amount"
-            },
-            "currency": {
-              "type": "string",
-              "enum": ["USD", "EUR", "GBP", "CAD"],
-              "description": "Price currency code"
-            }
-          }
-        },
-        "categories": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Categories the product belongs to"
-        },
-        "attributes": {
-          "type": "object",
-          "additionalProperties": {
-            "type": ["string", "number", "boolean"]
-          },
-          "description": "Additional product attributes as key-value pairs"
-        }
-      }
-    },
-    "metadata": {
-      "type": "object",
-      "additionalProperties": true,
-      "description": "Additional contextual information about the event"
-    },
-    "correlationId": {
-      "type": "string",
-      "format": "uuid",
-      "description": "ID for correlating related events"
-    },
-    "causationId": {
-      "type": "string",
-      "format": "uuid",
-      "description": "ID of the event that caused this event"
-    }
-  },
-  "additionalProperties": false
-}
-```
-
-## Standard Event Envelope
-
-All FlowMart events follow a standard envelope structure:
-
-```json
-{
-  "eventId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-  "eventType": "ProductCreated",
-  "eventVersion": "1.0.0",
-  "timestamp": "2023-09-15T13:25:47.803Z",
-  "source": "product-service",
-  "data": {
-    // Event-specific payload
-  },
-  "metadata": {
-    // Optional contextual information
-  },
-  "correlationId": "7f8d0e3c-d5f9-42e1-a11b-78ad6c0c380a",
-  "causationId": "3e4f5d6c-7b8a-9c0d-1e2f-3a4b5c6d7e8f"
-}
-```
-
-### Required Envelope Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| eventId | UUID | Unique identifier for the event instance |
-| eventType | String | Name of the event (e.g., `ProductCreated`) |
-| eventVersion | String | Semantic version of the event schema |
-| timestamp | ISO-8601 | When the event occurred |
-| data | Object | Event-specific payload |
-
-### Optional Envelope Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| source | String | Service that produced the event |
-| metadata | Object | Additional context about the event |
-| correlationId | UUID | ID for correlating related events in a flow |
-| causationId | UUID | ID of the event that caused this event |
-
-## Event Data Types
-
-### Primitive Types
-
-- **String**: Use for text data
-- **Number**: Use for numeric values (integers or decimals)
-- **Boolean**: Use for true/false flags
-- **Array**: Use for collections of the same type
-- **Object**: Use for nested structures
-
-### Specialized Formats
-
-- **UUID**: Use for unique identifiers (format: `uuid`)
-- **ISO Date-Time**: Use for timestamps (format: `date-time`)
-- **Email**: Use for email addresses (format: `email`)
-- **URI**: Use for web addresses (format: `uri`)
-- **Decimal**: Use for currency amounts (type: `number`)
-
-### Complex Types
-
-For complex or reusable types, create separate schema definitions:
-
-```json
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://schemas.flowmart.com/common/Address/1.0.0",
-  "title": "Address",
-  "type": "object",
-  "required": ["line1", "city", "postalCode", "country"],
-  "properties": {
-    "line1": {
-      "type": "string",
-      "maxLength": 100
-    },
-    "line2": {
-      "type": "string",
-      "maxLength": 100
-    },
-    "city": {
-      "type": "string",
-      "maxLength": 100
-    },
-    "region": {
-      "type": "string",
-      "maxLength": 100
-    },
-    "postalCode": {
-      "type": "string",
-      "maxLength": 20
-    },
-    "country": {
-      "type": "string",
-      "maxLength": 2,
-      "pattern": "^[A-Z]{2}$"
-    }
-  }
-}
-```
-
-Then reference them in your event schemas:
-
-```json
-{
-  "properties": {
-    "shippingAddress": {
-      "$ref": "https://schemas.flowmart.com/common/Address/1.0.0"
-    }
-  }
-}
-```
-
-## Common Event Patterns
-
-### State Change Events
-
-Represent changes to an entity's state:
-
-```json
-{
-  "eventType": "OrderStatusChanged",
-  "data": {
-    "orderId": "61fea0a1-2ac4-4e8c-a851-d38f7c8c06f9",
-    "previousStatus": "PAYMENT_PENDING",
-    "newStatus": "PAYMENT_COMPLETED",
-    "reason": "Payment successful",
-    "changedBy": "payment-service"
-  }
-}
-```
-
-### Resource Creation Events
-
-Represent the creation of a new entity:
-
-```json
-{
-  "eventType": "CustomerCreated",
-  "data": {
-    "customerId": "cust-12345",
-    "email": "john.doe@example.com",
-    "firstName": "John",
-    "lastName": "Doe",
-    "createdAt": "2023-09-15T10:30:00Z"
-  }
-}
-```
-
-### Resource Update Events
-
-Represent updates to an existing entity:
-
-```json
-{
-  "eventType": "ProductUpdated",
-  "data": {
-    "productId": "b3c631a5-f7c8-4d89-a57f-dd2f069b5730",
-    "changes": {
-      "price": {
-        "amount": 24.99,
-        "currency": "USD"
-      },
-      "inventory": {
-        "inStock": 250
-      }
-    },
-    "updatedAt": "2023-09-15T14:22:36Z"
-  }
-}
-```
-
-### Action Events
-
-Represent business actions that occurred:
-
-```json
-{
-  "eventType": "PaymentProcessed",
-  "data": {
-    "paymentId": "pay-67890",
-    "orderId": "ord-12345",
-    "amount": 99.99,
-    "currency": "USD",
-    "status": "SUCCESSFUL",
-    "paymentMethod": "CREDIT_CARD",
-    "processedAt": "2023-09-15T13:45:22Z"
-  }
-}
-```
-
-## Schema Evolution
-
-### Compatibility Types
-
-We support the following compatibility modes for schema evolution:
-
-- **Backward**: New schema can read data produced with previous schema
-- **Forward**: Previous schema can read data produced with new schema
-- **Full**: Both backward and forward compatibility
-- **None**: No compatibility guarantees (use with caution)
-
-### Backward Compatibility Rules
-
-1. **Adding optional fields** is safe
-2. **Removing optional fields** is safe
-3. **Making a required field optional** is safe
-4. **Adding new enum values** is safe
-5. **Widening numeric ranges** is safe (e.g., int to float)
-
-### Breaking Changes to Avoid
-
-1. ❌ **Removing required fields**
-2. ❌ **Adding required fields**
-3. ❌ **Changing field types**
-4. ❌ **Renaming fields**
-5. ❌ **Restricting enum values**
-
-### Handling Breaking Changes
-
-If you must make a breaking change:
-
-1. Create a new major version of the schema
-2. Maintain both versions for a transition period
-3. Implement dual publishing for critical events
-4. Help consumers migrate to the new version
-5. Deprecate the old version with advance notice
-
-## Consuming Events
-
-### Consumer Best Practices
-
-1. **Be tolerant in what you accept**:
-   - Ignore unknown fields
-   - Provide defaults for missing optional fields
-   - Handle enum values gracefully, including unknown values
-
-2. **Validate incoming events**:
-   - Verify events against their schema
-   - Check required fields
-   - Validate business rules before processing
-
-3. **Handle versioning gracefully**:
-   - Check event version before processing
-   - Implement version-specific handlers if needed
-   - Subscribe to schema registry updates
-
-### Consumer Code Example (TypeScript)
-
-```typescript
-import { KafkaConsumer } from '@flowmart/kafka-client';
-import { SchemaRegistry } from '@flowmart/schema-registry';
-import { OrderProcessingService } from './services';
-
-// Initialize schema registry client
-const schemaRegistry = new SchemaRegistry({
-  baseUrl: 'https://schema-registry.flowmart.com',
-});
-
-// Define event interface
-interface OrderPlacedEvent {
-  eventId: string;
-  eventType: 'OrderPlaced';
-  eventVersion: string;
-  timestamp: string;
-  data: {
-    orderId: string;
-    customerId: string;
-    items: Array<{
-      productId: string;
-      quantity: number;
-      unitPrice: number;
-    }>;
-    totalAmount: number;
-    currency: string;
-    shippingAddress: {
-      // Address fields...
-    };
-  };
-  // Other envelope fields...
-}
-
-// Initialize consumer
-const orderConsumer = new KafkaConsumer({
-  groupId: 'inventory-service',
-  brokers: ['kafka-1:9092', 'kafka-2:9092', 'kafka-3:9092'],
-});
-
-// Initialize service
-const orderProcessor = new OrderProcessingService();
-
-// Start consuming events
-async function startConsumer() {
-  await orderConsumer.subscribe('order-events');
-  
-  orderConsumer.on('message', async (message) => {
-    try {
-      // Parse the message
-      const rawEvent = JSON.parse(message.value.toString());
-      
-      // Skip if not the event we're interested in
-      if (rawEvent.eventType !== 'OrderPlaced') {
-        return;
-      }
-      
-      // Validate against schema
-      const isValid = await schemaRegistry.validate(
-        rawEvent, 
-        'OrderPlaced', 
-        rawEvent.eventVersion
-      );
-      
-      if (!isValid) {
-        console.error('Invalid event schema', rawEvent);
-        return;
-      }
-      
-      // Type-safe processing
-      const event = rawEvent as OrderPlacedEvent;
-      
-      // Process the order
-      await orderProcessor.processNewOrder(event.data);
-      
-      // Commit the offset
-      await orderConsumer.commitOffset(message);
-      
-    } catch (error) {
-      console.error('Error processing order event', error);
-      // Implement retry/dead-letter logic
-    }
-  });
-}
-
-startConsumer().catch(console.error);
-```
-
-## Publishing Events
-
-### Producer Best Practices
-
-1. **Validate before publishing**:
-   - Ensure events comply with their schema
-   - Verify business rules and data integrity
-   - Set appropriate event headers
-
-2. **Include essential metadata**:
-   - Generate a unique event ID
-   - Set the correct event type and version
-   - Include accurate timestamp
-   - Set correlation and causation IDs
-
-3. **Handle publishing failures**:
-   - Implement retry mechanisms with backoff
-   - Store events temporarily if Kafka is unavailable
-   - Log failed events for troubleshooting
-
-### Producer Code Example (TypeScript)
-
-```typescript
-import { v4 as uuid } from 'uuid';
-import { KafkaProducer } from '@flowmart/kafka-client';
-import { SchemaRegistry } from '@flowmart/schema-registry';
-import { Product } from './models';
-
-// Initialize schema registry client
-const schemaRegistry = new SchemaRegistry({
-  baseUrl: 'https://schema-registry.flowmart.com',
-});
-
-// Initialize producer
-const producer = new KafkaProducer({
-  clientId: 'product-service',
-  brokers: ['kafka-1:9092', 'kafka-2:9092', 'kafka-3:9092'],
-});
-
-export class ProductEventService {
-  async publishProductCreated(product: Product, correlationId?: string): Promise<void> {
-    const eventId = uuid();
-    
-    const event = {
-      eventId,
-      eventType: 'ProductCreated',
-      eventVersion: '1.0.0',
-      timestamp: new Date().toISOString(),
-      source: 'product-service',
-      data: {
-        productId: product.id,
-        name: product.name,
-        summary: product.description || null,
-        sku: product.sku,
-        price: {
-          amount: product.price,
-          currency: 'USD'  // Default to USD
-        },
-        categories: product.categories || [],
-        attributes: product.attributes || {}
-      },
-      metadata: {
-        // Add any additional metadata
-      },
-      correlationId: correlationId || eventId,
-      causationId: null  // No previous event caused this
-    };
-    
-    // Validate against schema
-    const isValid = await schemaRegistry.validate(
-      event, 
-      'ProductCreated', 
-      '1.0.0'
-    );
-    
-    if (!isValid) {
-      const errors = await schemaRegistry.getValidationErrors(
-        event, 
-        'ProductCreated', 
-        '1.0.0'
-      );
-      throw new Error(`Invalid event schema: ${JSON.stringify(errors)}`);
-    }
-    
-    // Publish event
-    await producer.send({
-      topic: 'product-events',
-      messages: [
-        {
-          key: product.id,
-          value: JSON.stringify(event),
-          headers: {
-            'eventType': 'ProductCreated',
-            'contentType': 'application/json'
-          }
-        }
-      ]
-    });
-    
-    console.log(`Published ProductCreated event: ${eventId}`);
-  }
-}
-```
-
-## Schema Registry Integration
-
-### Registering a New Schema
-
-```bash
-# Using CLI tool
-flowmart-schema register \
-  --file ./schemas/ProductCreated.json \
-  --compatibility BACKWARD
-
-# API endpoint
-curl -X POST https://schema-registry.flowmart.com/subjects/ProductCreated/versions \
-  -H "Content-Type: application/json" \
-  -d @./schemas/ProductCreated.json
-```
-
-### Retrieving a Schema
-
-```javascript
-// Using JavaScript client
-const schema = await schemaRegistry.getSchema('ProductCreated', '1.0.0');
-
-// API endpoint
-curl https://schema-registry.flowmart.com/subjects/ProductCreated/versions/latest
-```
-
-### Checking Compatibility
-
-```javascript
-// Using JavaScript client
-const isCompatible = await schemaRegistry.checkCompatibility(
-  newSchema, 
-  'ProductCreated'
-);
-
-// API endpoint
-curl -X POST https://schema-registry.flowmart.com/compatibility/subjects/ProductCreated/versions/latest \
-  -H "Content-Type: application/json" \
-  -d @./schemas/ProductCreated.v2.json
-```
-
-## Schema Registry UI
-
-Our Schema Registry includes a web interface at [https://schema-registry.flowmart.com/ui](https://schema-registry.flowmart.com/ui) that provides:
-
-- Browsable catalog of all event schemas
-- Schema versioning history
-- Compatibility information
-- Schema validation tools
-- Documentation generation
-
-## Testing Event Schemas
-
-### Unit Testing Schemas
-
-```javascript
-import { validateAgainstSchema } from '@flowmart/schema-validator';
-import productCreatedSchema from './schemas/ProductCreated.json';
-
-describe('ProductCreated schema', () => {
-  it('validates valid events', () => {
-    const validEvent = {
-      eventId: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
-      eventType: 'ProductCreated',
-      eventVersion: '1.0.0',
-      timestamp: '2023-09-15T13:25:47.803Z',
-      data: {
-        productId: 'b3c631a5-f7c8-4d89-a57f-dd2f069b5730',
-        name: 'Smartphone X Pro',
-        sku: 'SP-XPRO-2023',
-        price: {
-          amount: 999.99,
-          currency: 'USD'
-        }
-      }
-    };
-    
-    const result = validateAgainstSchema(validEvent, productCreatedSchema);
-    expect(result.valid).toBe(true);
-  });
-  
-  it('rejects events with missing required fields', () => {
-    const invalidEvent = {
-      eventId: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
-      eventType: 'ProductCreated',
-      eventVersion: '1.0.0',
-      timestamp: '2023-09-15T13:25:47.803Z',
-      data: {
-        // Missing required productId
-        name: 'Smartphone X Pro',
-        // Missing required sku
-        price: {
-          amount: 999.99,
-          currency: 'USD'
-        }
-      }
-    };
-    
-    const result = validateAgainstSchema(invalidEvent, productCreatedSchema);
-    expect(result.valid).toBe(false);
-    expect(result.errors.length).toBeGreaterThan(0);
-  });
-});
-```
-
-### Integration Testing with Schema Registry
-
-```javascript
-describe('Schema Registry Integration', () => {
-  it('registers and validates schema', async () => {
-    // Register test schema
-    await schemaRegistry.registerSchema(
-      'TestEvent',
-      testEventSchema,
-      'BACKWARD'
-    );
-    
-    // Create test event
-    const testEvent = {
-      eventId: uuid(),
-      eventType: 'TestEvent',
-      eventVersion: '1.0.0',
-      timestamp: new Date().toISOString(),
-      data: {
-        // Test data...
-      }
-    };
-    
-    // Validate against registered schema
-    const isValid = await schemaRegistry.validate(
-      testEvent,
-      'TestEvent',
-      '1.0.0'
-    );
-    
-    expect(isValid).toBe(true);
-  });
-});
-```
-
-## Event Documentation
-
-### Self-Documenting Schemas
-
-Use descriptive fields in your JSON Schema to auto-generate documentation:
-
-```json
-{
-  "title": "ProductCreated",
-  "description": "Published when a new product is created in the catalog",
-  "properties": {
-    "data": {
-      "properties": {
-        "productId": {
-          "description": "Unique identifier for the product",
-          "examples": ["p-12345"]
-        }
-      }
-    }
-  }
-}
-```
-
-### Documentation in Code
-
-Document event handling with clear comments:
-
-```typescript
-/**
- * Handles the ProductCreated event
- * This event is triggered when a new product is added to the catalog.
- * It updates the inventory service with the new product information.
- * 
- * @param event The ProductCreated event
- * @see https://schema-registry.flowmart.com/ui/schemas/ProductCreated/1.0.0
- */
-async function handleProductCreated(event: ProductCreatedEvent): Promise<void> {
-  // Implementation...
-}
-```
-
-## Event Tracing and Debugging
-
-### Correlation IDs
-
-Use correlation IDs to trace requests across services:
-
-```typescript
-// When handling an API request
-const correlationId = req.headers['x-correlation-id'] || uuid();
-
-// Include in all events
-const event = {
-  // Other event fields...
-  correlationId,
-  // If this event was caused by another event
-  causationId: previousEvent?.eventId
-};
-```
-
-### Event Logging
-
-Log event publishing and consumption with consistent format:
-
-```typescript
-// Producer logging
-logger.info('Publishing event', {
-  eventId: event.eventId,
-  eventType: event.eventType,
-  correlationId: event.correlationId
-});
-
-// Consumer logging
-logger.info('Consuming event', {
-  eventId: event.eventId,
-  eventType: event.eventType,
-  correlationId: event.correlationId,
-  consumer: 'inventory-service'
-});
-```
-
-## Event Monitoring
-
-Monitor your event streams using our standard observability stack:
-
-1. **Kafka Metrics**: Lag, throughput, errors
-2. **Schema Registry Metrics**: Validation failures, compatibility checks
-3. **Service Metrics**: Event processing times, failure rates
-4. **Custom Dashboards**: Domain-specific event flows
-
-Access dashboards at [https://grafana.flowmart.com/d/events](https://grafana.flowmart.com/d/events)
-
-## Event Schema Governance
-
-### Change Management
-
-1. **Proposal**: Document the schema change with rationale
-2. **Review**: Domain experts review for business requirements
-3. **Compatibility Check**: Verify with schema registry
-4. **Approval**: Get sign-off from service team leads
-5. **Publication**: Register schema and announce change
-
-### Schema Review Checklist
-
-✅ Schema follows naming conventions  
-✅ Required fields are truly necessary  
-✅ Field types are appropriate  
-✅ Enums have complete value lists  
-✅ Constraints (min, max, etc.) are appropriate  
-✅ Documentation is complete  
-✅ Versioning follows semantic versioning  
-✅ Compatibility type is specified  
-
-## Conclusion
-
-Well-designed event schemas are foundational to reliable event-driven systems. Following FlowMart's event schema guidelines ensures our services can communicate reliably today and evolve confidently tomorrow.
-
-## Next Steps
-
-- Explore [API design best practices](/docs/guides/creating-new-microservices/api-design)
-- Understand [Observability in microservices](/docs/guides/creating-new-microservices/observability)
-- Learn about [CI/CD for microservices](/docs/guides/creating-new-microservices/cicd-pipeline) 
\ No newline at end of file
diff --git a/examples/default/docs/guides/creating-new-microservices/06-typescript-service.mdx b/examples/default/docs/guides/creating-new-microservices/06-typescript-service.mdx
deleted file mode 100644
index 1a7400907..000000000
--- a/examples/default/docs/guides/creating-new-microservices/06-typescript-service.mdx
+++ /dev/null
@@ -1,959 +0,0 @@
----
-title: New TypeScript service
-summary: Guide to implementing microservices using TypeScript at FlowMart
-sidebar:
-    label: TypeScript Service
-    order: 4
----
-
-This guide details the recommended patterns, practices, and tools for implementing TypeScript-based microservices at FlowMart.
-
-
-## Why TypeScript?
-
-At FlowMart, we recommend TypeScript for new microservices because it offers:
-
-- **Type Safety**: Catch errors during development instead of at runtime
-- **Better IDE Support**: Enhanced auto-completion, navigation, and refactoring
-- **Self-Documenting Code**: Types serve as documentation for your codebase
-- **Enterprise-Ready**: Better maintainability for large codebases and teams
-- **Ecosystem Compatibility**: Full access to the Node.js ecosystem
-
-## Prerequisites
-
-Before you begin:
-
-- Install Node.js (v18 or later)
-- Familiarize yourself with [our Node.js service guide](/docs/guides/creating-new-microservices/node-service)
-- Have basic TypeScript knowledge
-
-## Scaffolding a TypeScript Service
-
-Use our service generator to create a TypeScript service:
-
-```bash
-# Install the FlowMart service generator
-npm install -g @flowmart/service-generator
-
-# Create a new TypeScript service
-flowmart-create-service my-service --type typescript
-```
-
-## TypeScript Project Structure
-
-The generated service follows our standard TypeScript structure:
-
-```
-my-service/
-├── src/
-│   ├── api/                 # API definition and controllers
-│   ├── config/              # Configuration management
-│   ├── domain/              # Domain models and business logic
-│   │   ├── models/          # Domain entities and value objects
-│   │   └── services/        # Domain services
-│   ├── events/              # Event producers and consumers
-│   ├── infrastructure/      # External dependencies and adapters
-│   ├── repositories/        # Data access layer
-│   ├── types/               # TypeScript type definitions
-│   ├── utils/               # Utility functions
-│   └── app.ts               # Application entry point
-├── test/
-│   ├── unit/                # Unit tests
-│   ├── integration/         # Integration tests
-│   └── contract/            # Contract tests
-├── terraform/               # Infrastructure as code
-├── .github/                 # GitHub Actions workflows
-├── Dockerfile               # Container definition
-├── docker-compose.yml       # Local development setup
-├── tsconfig.json            # TypeScript configuration
-├── package.json             # Dependencies and scripts
-└── README.md                # Service documentation
-```
-
-## TypeScript Configuration
-
-Our template includes a pre-configured `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "lib": ["ES2020"],
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "sourceMap": true,
-    "declaration": true,
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "test"]
-}
-```
-
-## Domain Modeling with TypeScript
-
-TypeScript enables us to model our domain with strong types:
-
-### Example Domain Model
-
-```typescript
-// src/domain/models/product.ts
-export enum ProductCategory {
-  ELECTRONICS = 'electronics',
-  CLOTHING = 'clothing',
-  GROCERY = 'grocery',
-  HOME = 'home',
-  BEAUTY = 'beauty'
-}
-
-export interface ProductAttributes {
-  [key: string]: string | number | boolean;
-}
-
-export class Product {
-  constructor(
-    public readonly id: string,
-    public name: string,
-    public summary: string,
-    public price: number,
-    public category: ProductCategory,
-    public sku: string,
-    public inventoryCount: number,
-    public attributes: ProductAttributes = {},
-    public isActive: boolean = true,
-    public createdAt: Date = new Date(),
-    public updatedAt: Date = new Date()
-  ) {}
-
-  updateInventory(count: number): void {
-    if (count < 0) {
-      throw new Error('Inventory count cannot be negative');
-    }
-    this.inventoryCount = count;
-    this.updatedAt = new Date();
-  }
-
-  updatePrice(price: number): void {
-    if (price < 0) {
-      throw new Error('Price cannot be negative');
-    }
-    this.price = price;
-    this.updatedAt = new Date();
-  }
-
-  deactivate(): void {
-    this.isActive = false;
-    this.updatedAt = new Date();
-  }
-
-  activate(): void {
-    this.isActive = true;
-    this.updatedAt = new Date();
-  }
-
-  isInStock(): boolean {
-    return this.inventoryCount > 0;
-  }
-}
-```
-
-## Repository Pattern with TypeScript
-
-Use interfaces to define repositories:
-
-```typescript
-// src/repositories/product-repository.ts
-import { Product } from '../domain/models/product';
-
-export interface ProductRepository {
-  findById(id: string): Promise<Product | null>;
-  findAll(limit?: number, offset?: number): Promise<Product[]>;
-  findByCategory(category: string, limit?: number, offset?: number): Promise<Product[]>;
-  save(product: Product): Promise<Product>;
-  update(product: Product): Promise<Product>;
-  delete(id: string): Promise<boolean>;
-}
-
-// src/repositories/mongodb-product-repository.ts
-import { Collection, MongoClient, ObjectId } from 'mongodb';
-import { Product, ProductCategory } from '../domain/models/product';
-import { ProductRepository } from './product-repository';
-import { logger } from '../infrastructure/observability';
-
-export class MongoDBProductRepository implements ProductRepository {
-  private collection: Collection;
-
-  constructor(client: MongoClient) {
-    this.collection = client.db('ecommerce').collection('products');
-  }
-
-  async findById(id: string): Promise<Product | null> {
-    try {
-      const result = await this.collection.findOne({ _id: new ObjectId(id) });
-      if (!result) return null;
-      return this.mapToProduct(result);
-    } catch (error) {
-      logger.error('Error finding product by id', { error, id });
-      throw error;
-    }
-  }
-
-  async findAll(limit = 100, offset = 0): Promise<Product[]> {
-    try {
-      const results = await this.collection
-        .find({})
-        .skip(offset)
-        .limit(limit)
-        .toArray();
-      return results.map(this.mapToProduct);
-    } catch (error) {
-      logger.error('Error finding all products', { error });
-      throw error;
-    }
-  }
-
-  async findByCategory(category: string, limit = 100, offset = 0): Promise<Product[]> {
-    try {
-      const results = await this.collection
-        .find({ category })
-        .skip(offset)
-        .limit(limit)
-        .toArray();
-      return results.map(this.mapToProduct);
-    } catch (error) {
-      logger.error('Error finding products by category', { error, category });
-      throw error;
-    }
-  }
-
-  async save(product: Product): Promise<Product> {
-    try {
-      const productDoc = {
-        name: product.name,
-        summary: product.description,
-        price: product.price,
-        category: product.category,
-        sku: product.sku,
-        inventoryCount: product.inventoryCount,
-        attributes: product.attributes,
-        isActive: product.isActive,
-        createdAt: product.createdAt,
-        updatedAt: product.updatedAt
-      };
-      
-      const result = await this.collection.insertOne(productDoc);
-      return {
-        ...product,
-        id: result.insertedId.toString()
-      };
-    } catch (error) {
-      logger.error('Error saving product', { error, product });
-      throw error;
-    }
-  }
-
-  async update(product: Product): Promise<Product> {
-    try {
-      const result = await this.collection.updateOne(
-        { _id: new ObjectId(product.id) },
-        {
-          $set: {
-            name: product.name,
-            summary: product.description,
-            price: product.price,
-            category: product.category,
-            sku: product.sku,
-            inventoryCount: product.inventoryCount,
-            attributes: product.attributes,
-            isActive: product.isActive,
-            updatedAt: product.updatedAt
-          }
-        }
-      );
-      
-      if (result.matchedCount === 0) {
-        throw new Error(`Product with id ${product.id} not found`);
-      }
-      
-      return product;
-    } catch (error) {
-      logger.error('Error updating product', { error, productId: product.id });
-      throw error;
-    }
-  }
-
-  async delete(id: string): Promise<boolean> {
-    try {
-      const result = await this.collection.deleteOne({ _id: new ObjectId(id) });
-      return result.deletedCount === 1;
-    } catch (error) {
-      logger.error('Error deleting product', { error, id });
-      throw error;
-    }
-  }
-
-  private mapToProduct(doc: any): Product {
-    return new Product(
-      doc._id.toString(),
-      doc.name,
-      doc.description,
-      doc.price,
-      doc.category as ProductCategory,
-      doc.sku,
-      doc.inventoryCount,
-      doc.attributes,
-      doc.isActive,
-      new Date(doc.createdAt),
-      new Date(doc.updatedAt)
-    );
-  }
-}
-```
-
-## Type-safe API Controllers
-
-TypeScript enables type-safe API controllers with Express:
-
-```typescript
-// src/api/controllers/product-controller.ts
-import { Router, Request, Response, NextFunction } from 'express';
-import { ProductService } from '../../domain/services/product-service';
-import { validateProduct } from '../middleware/product-validator';
-import { tracing } from '../../infrastructure/observability';
-import { Product, ProductCategory } from '../../domain/models/product';
-
-export interface CreateProductRequest {
-  name: string;
-  summary: string;
-  price: number;
-  category: ProductCategory;
-  sku: string;
-  inventoryCount: number;
-  attributes?: { [key: string]: string | number | boolean };
-}
-
-export interface UpdateProductRequest {
-  name?: string;
-  description?: string;
-  price?: number;
-  category?: ProductCategory;
-  sku?: string;
-  inventoryCount?: number;
-  attributes?: { [key: string]: string | number | boolean };
-  isActive?: boolean;
-}
-
-export class ProductController {
-  private router: Router;
-  
-  constructor(private productService: ProductService) {
-    this.router = Router();
-    this.setupRoutes();
-  }
-  
-  private setupRoutes(): void {
-    this.router.get('/', tracing.middleware('get-all-products'), this.getAllProducts.bind(this));
-    this.router.get('/:id', tracing.middleware('get-product'), this.getProductById.bind(this));
-    this.router.post('/', tracing.middleware('create-product'), validateProduct, this.createProduct.bind(this));
-    this.router.put('/:id', tracing.middleware('update-product'), this.updateProduct.bind(this));
-    this.router.delete('/:id', tracing.middleware('delete-product'), this.deleteProduct.bind(this));
-  }
-  
-  getRouter(): Router {
-    return this.router;
-  }
-  
-  private async getAllProducts(req: Request, res: Response, next: NextFunction): Promise<void> {
-    try {
-      const limit = req.query.limit ? parseInt(req.query.limit as string, 10) : 100;
-      const offset = req.query.offset ? parseInt(req.query.offset as string, 10) : 0;
-      const products = await this.productService.getAllProducts(limit, offset);
-      res.json(products);
-    } catch (error) {
-      next(error);
-    }
-  }
-  
-  private async getProductById(req: Request, res: Response, next: NextFunction): Promise<void> {
-    try {
-      const product = await this.productService.getProductById(req.params.id);
-      if (!product) {
-        res.status(404).json({ error: 'Product not found' });
-        return;
-      }
-      res.json(product);
-    } catch (error) {
-      next(error);
-    }
-  }
-  
-  private async createProduct(req: Request, res: Response, next: NextFunction): Promise<void> {
-    try {
-      const productData = req.body as CreateProductRequest;
-      const product = await this.productService.createProduct(productData);
-      res.status(201).json(product);
-    } catch (error) {
-      next(error);
-    }
-  }
-  
-  private async updateProduct(req: Request, res: Response, next: NextFunction): Promise<void> {
-    try {
-      const productData = req.body as UpdateProductRequest;
-      const product = await this.productService.updateProduct(req.params.id, productData);
-      if (!product) {
-        res.status(404).json({ error: 'Product not found' });
-        return;
-      }
-      res.json(product);
-    } catch (error) {
-      next(error);
-    }
-  }
-  
-  private async deleteProduct(req: Request, res: Response, next: NextFunction): Promise<void> {
-    try {
-      const success = await this.productService.deleteProduct(req.params.id);
-      if (!success) {
-        res.status(404).json({ error: 'Product not found' });
-        return;
-      }
-      res.status(204).send();
-    } catch (error) {
-      next(error);
-    }
-  }
-}
-```
-
-## Strongly Typed Event Handling
-
-Create strongly typed event producers and consumers:
-
-```typescript
-// src/events/types/event-types.ts
-export interface EventMetadata {
-  eventId: string;
-  timestamp: string;
-  service: string;
-  correlationId?: string;
-  causationId?: string;
-}
-
-export interface Event<T> {
-  type: string;
-  data: T;
-  metadata: EventMetadata;
-}
-
-export interface ProductCreatedEvent extends Event<{
-  id: string;
-  name: string;
-  price: number;
-  category: string;
-  sku: string;
-  inventoryCount: number;
-}> {
-  type: 'PRODUCT_CREATED';
-}
-
-export interface ProductUpdatedEvent extends Event<{
-  id: string;
-  changes: {
-    name?: string;
-    price?: number;
-    category?: string;
-    inventoryCount?: number;
-  };
-}> {
-  type: 'PRODUCT_UPDATED';
-}
-
-export interface InventoryUpdatedEvent extends Event<{
-  productId: string;
-  quantity: number;
-  warehouseId: string;
-}> {
-  type: 'INVENTORY_UPDATED';
-}
-
-// src/events/producers/product-event-producer.ts
-import { v4 as uuidv4 } from 'uuid';
-import { KafkaClient } from '../../infrastructure/kafka';
-import { Product } from '../../domain/models/product';
-import { ProductCreatedEvent, ProductUpdatedEvent } from '../types/event-types';
-
-export class ProductEventProducer {
-  private readonly topic = 'product-events';
-  
-  constructor(private kafkaClient: KafkaClient) {}
-
-  async productCreated(product: Product): Promise<void> {
-    const event: ProductCreatedEvent = {
-      type: 'PRODUCT_CREATED',
-      data: {
-        id: product.id,
-        name: product.name,
-        price: product.price,
-        category: product.category,
-        sku: product.sku,
-        inventoryCount: product.inventoryCount
-      },
-      metadata: {
-        eventId: uuidv4(),
-        timestamp: new Date().toISOString(),
-        service: 'product-service'
-      }
-    };
-
-    await this.kafkaClient.produce({
-      topic: this.topic,
-      key: product.id,
-      value: JSON.stringify(event)
-    });
-  }
-
-  async productUpdated(product: Product, changes: Partial<Product>): Promise<void> {
-    const event: ProductUpdatedEvent = {
-      type: 'PRODUCT_UPDATED',
-      data: {
-        id: product.id,
-        changes: {
-          name: changes.name,
-          price: changes.price,
-          category: changes.category,
-          inventoryCount: changes.inventoryCount
-        }
-      },
-      metadata: {
-        eventId: uuidv4(),
-        timestamp: new Date().toISOString(),
-        service: 'product-service'
-      }
-    };
-
-    await this.kafkaClient.produce({
-      topic: this.topic,
-      key: product.id,
-      value: JSON.stringify(event)
-    });
-  }
-}
-```
-
-## Dependency Injection with TypeScript
-
-We use the `inversify` library for dependency injection:
-
-```typescript
-// src/infrastructure/ioc/container.ts
-import { Container } from 'inversify';
-import { MongoClient } from 'mongodb';
-import { KafkaClient } from '../kafka';
-import { ProductRepository } from '../../repositories/product-repository';
-import { MongoDBProductRepository } from '../../repositories/mongodb-product-repository';
-import { ProductService } from '../../domain/services/product-service';
-import { ProductEventProducer } from '../../events/producers/product-event-producer';
-import { ProductController } from '../../api/controllers/product-controller';
-import { AppConfig } from '../../config/app-config';
-import TYPES from './types';
-
-const container = new Container();
-
-// Config
-container.bind<AppConfig>(TYPES.AppConfig).to(AppConfig).inSingletonScope();
-
-// Infrastructure
-container.bind<MongoClient>(TYPES.MongoClient).toDynamicValue((context) => {
-  const config = context.container.get<AppConfig>(TYPES.AppConfig);
-  return new MongoClient(config.mongoDbUri);
-}).inSingletonScope();
-
-container.bind<KafkaClient>(TYPES.KafkaClient).toDynamicValue((context) => {
-  const config = context.container.get<AppConfig>(TYPES.AppConfig);
-  return new KafkaClient(config.kafkaBrokers);
-}).inSingletonScope();
-
-// Repositories
-container.bind<ProductRepository>(TYPES.ProductRepository).toDynamicValue((context) => {
-  const mongoClient = context.container.get<MongoClient>(TYPES.MongoClient);
-  return new MongoDBProductRepository(mongoClient);
-}).inSingletonScope();
-
-// Event Producers
-container.bind<ProductEventProducer>(TYPES.ProductEventProducer).toDynamicValue((context) => {
-  const kafkaClient = context.container.get<KafkaClient>(TYPES.KafkaClient);
-  return new ProductEventProducer(kafkaClient);
-}).inSingletonScope();
-
-// Services
-container.bind<ProductService>(TYPES.ProductService).toDynamicValue((context) => {
-  const repository = context.container.get<ProductRepository>(TYPES.ProductRepository);
-  const eventProducer = context.container.get<ProductEventProducer>(TYPES.ProductEventProducer);
-  return new ProductService(repository, eventProducer);
-}).inSingletonScope();
-
-// Controllers
-container.bind<ProductController>(TYPES.ProductController).toDynamicValue((context) => {
-  const service = context.container.get<ProductService>(TYPES.ProductService);
-  return new ProductController(service);
-}).inSingletonScope();
-
-export default container;
-
-// src/infrastructure/ioc/types.ts
-const TYPES = {
-  AppConfig: Symbol.for('AppConfig'),
-  MongoClient: Symbol.for('MongoClient'),
-  KafkaClient: Symbol.for('KafkaClient'),
-  ProductRepository: Symbol.for('ProductRepository'),
-  ProductEventProducer: Symbol.for('ProductEventProducer'),
-  ProductService: Symbol.for('ProductService'),
-  ProductController: Symbol.for('ProductController')
-};
-
-export default TYPES;
-```
-
-## Error Handling with TypeScript
-
-Use custom error classes:
-
-```typescript
-// src/utils/errors.ts
-export class AppError extends Error {
-  constructor(
-    public readonly message: string,
-    public readonly statusCode: number = 500,
-    public readonly code: string = 'INTERNAL_ERROR',
-    public readonly details?: any
-  ) {
-    super(message);
-    this.name = this.constructor.name;
-    Error.captureStackTrace(this, this.constructor);
-  }
-}
-
-export class NotFoundError extends AppError {
-  constructor(resource: string, id: string) {
-    super(`${resource} with id ${id} not found`, 404, 'NOT_FOUND');
-    this.name = this.constructor.name;
-  }
-}
-
-export class ValidationError extends AppError {
-  constructor(message: string, details?: any) {
-    super(message, 400, 'VALIDATION_ERROR', details);
-    this.name = this.constructor.name;
-  }
-}
-
-export class ConflictError extends AppError {
-  constructor(message: string) {
-    super(message, 409, 'CONFLICT_ERROR');
-    this.name = this.constructor.name;
-  }
-}
-
-export class AuthorizationError extends AppError {
-  constructor(message: string = 'Unauthorized') {
-    super(message, 401, 'UNAUTHORIZED');
-    this.name = this.constructor.name;
-  }
-}
-
-// src/api/middleware/error-handler.ts
-import { Request, Response, NextFunction } from 'express';
-import { AppError } from '../../utils/errors';
-import { logger } from '../../infrastructure/observability';
-
-export function errorHandler(
-  error: Error, 
-  req: Request, 
-  res: Response, 
-  next: NextFunction
-): void {
-  logger.error('Request error', {
-    error: error.message,
-    stack: error.stack,
-    path: req.path,
-    method: req.method
-  });
-
-  if (error instanceof AppError) {
-    res.status(error.statusCode).json({
-      error: {
-        code: error.code,
-        message: error.message,
-        details: error.details
-      }
-    });
-    return;
-  }
-
-  res.status(500).json({
-    error: {
-      code: 'INTERNAL_SERVER_ERROR',
-      message: 'An unexpected error occurred'
-    }
-  });
-}
-```
-
-## Testing TypeScript Services
-
-We use Jest for testing TypeScript services:
-
-```typescript
-// test/unit/domain/services/product-service.test.ts
-import { ProductService } from '../../../../src/domain/services/product-service';
-import { Product, ProductCategory } from '../../../../src/domain/models/product';
-import { NotFoundError } from '../../../../src/utils/errors';
-
-describe('ProductService', () => {
-  const mockProduct = new Product(
-    '1',
-    'Test Product',
-    'Test Description',
-    9.99,
-    ProductCategory.ELECTRONICS,
-    'TEST-123',
-    100
-  );
-
-  const mockRepository = {
-    findById: jest.fn(),
-    findAll: jest.fn(),
-    findByCategory: jest.fn(),
-    save: jest.fn(),
-    update: jest.fn(),
-    delete: jest.fn()
-  };
-
-  const mockEventProducer = {
-    productCreated: jest.fn(),
-    productUpdated: jest.fn()
-  };
-
-  const productService = new ProductService(mockRepository, mockEventProducer);
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
-
-  describe('getProductById', () => {
-    it('should return a product when found', async () => {
-      mockRepository.findById.mockResolvedValue(mockProduct);
-      
-      const result = await productService.getProductById('1');
-      
-      expect(result).toEqual(mockProduct);
-      expect(mockRepository.findById).toHaveBeenCalledWith('1');
-    });
-
-    it('should return null when product not found', async () => {
-      mockRepository.findById.mockResolvedValue(null);
-      
-      const result = await productService.getProductById('999');
-      
-      expect(result).toBeNull();
-      expect(mockRepository.findById).toHaveBeenCalledWith('999');
-    });
-  });
-
-  describe('createProduct', () => {
-    it('should create and return a new product', async () => {
-      const productData = {
-        name: 'New Product',
-        summary: 'New Description',
-        price: 19.99,
-        category: ProductCategory.CLOTHING,
-        sku: 'NEW-123',
-        inventoryCount: 50
-      };
-      
-      mockRepository.save.mockImplementation(product => Promise.resolve(product));
-      
-      const result = await productService.createProduct(productData);
-      
-      expect(result).toMatchObject(productData);
-      expect(mockRepository.save).toHaveBeenCalledTimes(1);
-      expect(mockEventProducer.productCreated).toHaveBeenCalledWith(expect.objectContaining(productData));
-    });
-  });
-
-  describe('updateProduct', () => {
-    it('should update and return the product', async () => {
-      const changes = { price: 29.99, inventoryCount: 75 };
-      const updatedProduct = { ...mockProduct, ...changes };
-      
-      mockRepository.findById.mockResolvedValue(mockProduct);
-      mockRepository.update.mockResolvedValue(updatedProduct);
-      
-      const result = await productService.updateProduct('1', changes);
-      
-      expect(result).toEqual(updatedProduct);
-      expect(mockRepository.findById).toHaveBeenCalledWith('1');
-      expect(mockRepository.update).toHaveBeenCalledWith(expect.objectContaining(changes));
-      expect(mockEventProducer.productUpdated).toHaveBeenCalledWith(
-        expect.anything(),
-        expect.objectContaining(changes)
-      );
-    });
-
-    it('should throw NotFoundError when product not found', async () => {
-      mockRepository.findById.mockResolvedValue(null);
-      
-      await expect(productService.updateProduct('999', { price: 29.99 }))
-        .rejects
-        .toThrow(NotFoundError);
-      
-      expect(mockRepository.update).not.toHaveBeenCalled();
-      expect(mockEventProducer.productUpdated).not.toHaveBeenCalled();
-    });
-  });
-});
-```
-
-## Building and Packaging TypeScript Services
-
-Our template includes optimized build scripts:
-
-```json
-// package.json (excerpt)
-{
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/app.js",
-    "dev": "ts-node-dev --respawn --transpile-only src/app.ts",
-    "lint": "eslint src --ext .ts",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage"
-  }
-}
-```
-
-## Dockerizing TypeScript Services
-
-Our Docker setup uses multi-stage builds for optimal container size:
-
-```dockerfile
-# Dockerfile
-FROM node:18-alpine AS builder
-
-WORKDIR /app
-
-COPY package*.json ./
-RUN npm ci
-
-COPY tsconfig.json ./
-COPY src/ ./src/
-
-RUN npm run build
-
-FROM node:18-alpine
-
-WORKDIR /app
-
-COPY package*.json ./
-RUN npm ci --production
-
-COPY --from=builder /app/dist ./dist
-
-ENV NODE_ENV=production
-EXPOSE 3000
-
-HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
-  CMD wget -qO- http://localhost:3000/health || exit 1
-
-CMD ["node", "dist/app.js"]
-```
-
-## CI/CD for TypeScript Services
-
-Our CI/CD workflow ensures proper TypeScript builds:
-
-```yaml
-# .github/workflows/main.yml (excerpt)
-jobs:
-  test:
-    name: Test
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-          cache: 'npm'
-      - run: npm ci
-      - run: npm run lint
-      - run: npm test
-      
-  build:
-    name: Build and Push
-    needs: test
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-          cache: 'npm'
-      - run: npm ci
-      - run: npm run build
-      # Then Docker build and push steps...
-```
-
-## TypeScript Best Practices at FlowMart
-
-1. **Use Interfaces for Public APIs**: Define interfaces for repositories, services, and controllers.
-
-2. **Embrace Type Inference**: Let TypeScript infer types where it makes sense to reduce verbosity.
-
-3. **Use Discriminated Unions**: For handling different event types or command patterns.
-
-4. **Leverage Utility Types**: Use built-in utility types like `Partial<T>`, `Readonly<T>`, `Pick<T>`, etc.
-
-5. **Strict Null Checks**: Always enable `strictNullChecks` to prevent null/undefined errors.
-
-6. **Immutability**: Use `readonly` properties and `const` variables to enforce immutability.
-
-7. **Error Handling**: Use custom error classes with type information.
-
-8. **Asynchronous Code**: Use `async/await` consistently with proper error handling.
-
-9. **Use Enums for Constants**: Define related constants as TypeScript enums.
-
-10. **Module Structure**: Organize code into cohesive modules with clear interfaces.
-
-## Recommended Libraries
-
-- **Express.js**: Web framework
-- **inversify**: Dependency injection
-- **zod**: Runtime validation
-- **winston**: Logging
-- **prom-client**: Prometheus metrics
-- **jaeger-client**: Distributed tracing
-- **mongodb**: Database driver
-- **kafkajs**: Kafka client
-- **jest**: Testing framework
-- **supertest**: API testing
-- **ts-node-dev**: Development server
-
-## Next Steps
-
-- Learn about [Database patterns for microservices](/docs/guides/creating-new-microservices/database-patterns)
-- Understand [Event schema design](/docs/guides/creating-new-microservices/event-schemas)
-- Explore [API design best practices](/docs/guides/creating-new-microservices/api-design) 
\ No newline at end of file
diff --git a/examples/default/docs/guides/creating-new-microservices/event-stream-example.ecstudio b/examples/default/docs/guides/creating-new-microservices/event-stream-example.ecstudio
deleted file mode 100644
index 0b20eba0d..000000000
--- a/examples/default/docs/guides/creating-new-microservices/event-stream-example.ecstudio
+++ /dev/null
@@ -1,354 +0,0 @@
-{
-  "nodes": [
-    {
-      "id": "service-producer1",
-      "type": "service",
-      "position": {
-        "x": 12,
-        "y": 348.3333333333333
-      },
-      "data": {
-        "mode": "full",
-        "service": {
-          "id": "order-producer",
-          "name": "Order Producer",
-          "owners": [
-            "order-team"
-          ],
-          "sends": [
-            "OrderCreated",
-            "OrderUpdated"
-          ],
-          "receives": [],
-          "version": "1.0.0",
-          "summary": "Produces order events to the stream"
-        }
-      },
-      "measured": {
-        "width": 262,
-        "height": 98
-      }
-    },
-    {
-      "id": "service-producer2",
-      "type": "service",
-      "position": {
-        "x": 394,
-        "y": 526.3333333333333
-      },
-      "data": {
-        "mode": "full",
-        "service": {
-          "id": "user-producer",
-          "name": "User Producer",
-          "owners": [
-            "user-team"
-          ],
-          "sends": [
-            "UserCreated",
-            "UserUpdated"
-          ],
-          "receives": [],
-          "version": "1.0.0",
-          "summary": "Produces user events to the stream"
-        }
-      },
-      "measured": {
-        "width": 262,
-        "height": 98
-      }
-    },
-    {
-      "id": "channel-event-stream",
-      "type": "channel",
-      "position": {
-        "x": 776,
-        "y": 364
-      },
-      "data": {
-        "mode": "full",
-        "channel": {
-          "id": "event-stream",
-          "name": "event-stream",
-          "version": "1.0.0",
-          "summary": "High-throughput Kafka stream for real-time event processing"
-        }
-      },
-      "measured": {
-        "width": 262,
-        "height": 100
-      }
-    },
-    {
-      "id": "service-stream-processor",
-      "type": "service",
-      "position": {
-        "x": 1158,
-        "y": 348.3333333333333
-      },
-      "data": {
-        "mode": "full",
-        "service": {
-          "id": "stream-processor",
-          "name": "Stream Processor",
-          "owners": [
-            "analytics-team"
-          ],
-          "sends": [
-            "MetricsCalculated",
-            "AlertTriggered"
-          ],
-          "receives": [
-            "OrderCreated",
-            "UserCreated"
-          ],
-          "version": "1.0.0",
-          "summary": "Real-time stream processing with Kafka Streams"
-        }
-      },
-      "measured": {
-        "width": 262,
-        "height": 98
-      }
-    },
-    {
-      "id": "service-consumer1",
-      "type": "service",
-      "position": {
-        "x": 1158,
-        "y": 526.3333333333333
-      },
-      "data": {
-        "mode": "full",
-        "service": {
-          "id": "notification-consumer",
-          "name": "Notification Consumer",
-          "owners": [
-            "notification-team"
-          ],
-          "sends": [
-            "NotificationSent"
-          ],
-          "receives": [
-            "OrderCreated",
-            "AlertTriggered"
-          ],
-          "version": "1.0.0",
-          "summary": "Consumes events to send real-time notifications"
-        }
-      },
-      "measured": {
-        "width": 262,
-        "height": 98
-      }
-    },
-    {
-      "id": "data-stream-store",
-      "type": "data",
-      "position": {
-        "x": 1540,
-        "y": 332
-      },
-      "data": {
-        "mode": "full",
-        "data": {
-          "id": "stream-store",
-          "name": "Stream State Store",
-          "owners": [
-            "analytics-team"
-          ],
-          "version": "1.0.0",
-          "summary": "Local state store for stream processing aggregations",
-          "type": "Database"
-        }
-      },
-      "measured": {
-        "width": 262,
-        "height": 98
-      }
-    },
-    {
-      "id": "service-consumer2",
-      "type": "service",
-      "position": {
-        "x": 1540,
-        "y": 510
-      },
-      "data": {
-        "mode": "full",
-        "service": {
-          "id": "analytics-consumer",
-          "name": "Analytics Consumer",
-          "owners": [
-            "analytics-team"
-          ],
-          "sends": [],
-          "receives": [
-            "MetricsCalculated"
-          ],
-          "version": "1.0.0",
-          "summary": "Consumes processed metrics for dashboard updates"
-        }
-      },
-      "measured": {
-        "width": 262,
-        "height": 98
-      }
-    },
-    {
-      "id": "data-analytics-db",
-      "type": "data",
-      "position": {
-        "x": 1922,
-        "y": 510
-      },
-      "data": {
-        "mode": "full",
-        "data": {
-          "id": "analytics-database",
-          "name": "Analytics Database",
-          "owners": [
-            "analytics-team"
-          ],
-          "version": "1.0.0",
-          "summary": "Time-series database for storing processed stream data",
-          "type": "Database"
-        }
-      },
-      "measured": {
-        "width": 262,
-        "height": 98
-      }
-    },
-    {
-      "id": "event-order-created",
-      "type": "event",
-      "position": {
-        "x": 394,
-        "y": 348.3333333333333
-      },
-      "data": {
-        "mode": "full",
-        "message": {
-          "id": "order-created-stream",
-          "name": "OrderCreated",
-          "version": "1.0.0",
-          "summary": "Order creation event in the stream"
-        }
-      },
-      "measured": {
-        "width": 262,
-        "height": 98
-      }
-    }
-  ],
-  "edges": [
-    {
-      "source": "service-producer1",
-      "target": "event-order-created",
-      "label": "Produces",
-      "markerEnd": {
-        "type": "arrowclosed",
-        "color": "#000000"
-      },
-      "animated": true,
-      "type": "animatedMessage",
-      "id": "xy-edge__service-producer1-event-order-created"
-    },
-    {
-      "source": "service-producer2",
-      "target": "channel-event-stream",
-      "label": "Produces",
-      "markerEnd": {
-        "type": "arrowclosed",
-        "color": "#000000"
-      },
-      "animated": true,
-      "type": "animatedMessage",
-      "id": "xy-edge__service-producer2-channel-event-stream"
-    },
-    {
-      "source": "event-order-created",
-      "target": "channel-event-stream",
-      "label": "Flows to",
-      "markerEnd": {
-        "type": "arrowclosed",
-        "color": "#000000"
-      },
-      "animated": true,
-      "type": "animatedMessage",
-      "id": "xy-edge__event-order-created-channel-event-stream"
-    },
-    {
-      "source": "channel-event-stream",
-      "target": "service-stream-processor",
-      "label": "Stream Processing",
-      "markerEnd": {
-        "type": "arrowclosed",
-        "color": "#000000"
-      },
-      "animated": true,
-      "type": "animatedMessage",
-      "id": "xy-edge__channel-event-stream-service-stream-processor"
-    },
-    {
-      "source": "channel-event-stream",
-      "target": "service-consumer1",
-      "label": "Consumes",
-      "markerEnd": {
-        "type": "arrowclosed",
-        "color": "#000000"
-      },
-      "animated": true,
-      "type": "animatedMessage",
-      "id": "xy-edge__channel-event-stream-service-consumer1"
-    },
-    {
-      "source": "service-stream-processor",
-      "target": "data-stream-store",
-      "label": "Maintains State",
-      "markerEnd": {
-        "type": "arrowclosed",
-        "color": "#000000"
-      },
-      "animated": false,
-      "type": "default",
-      "id": "xy-edge__service-stream-processor-data-stream-store"
-    },
-    {
-      "source": "service-stream-processor",
-      "target": "service-consumer2",
-      "label": "Processed Events",
-      "markerEnd": {
-        "type": "arrowclosed",
-        "color": "#000000"
-      },
-      "animated": true,
-      "type": "animatedMessage",
-      "id": "xy-edge__service-stream-processor-service-consumer2"
-    },
-    {
-      "source": "service-consumer2",
-      "target": "data-analytics-db",
-      "label": "Stores Metrics",
-      "markerEnd": {
-        "type": "arrowclosed",
-        "color": "#000000"
-      },
-      "animated": false,
-      "type": "default",
-      "id": "xy-edge__service-consumer2-data-analytics-db"
-    }
-  ],
-  "viewport": {
-    "x": 154,
-    "y": 41,
-    "zoom": 0.6
-  },
-  "creationDate": "2025-08-12T09:12:34.680Z",
-  "name": "Event Streaming Pattern",
-  "version": "1.0",
-  "source": "https://app.eventcatalog.dev",
-  "appState": {},
-  "id": "event-streaming-pattern"
-}
\ No newline at end of file
diff --git a/examples/default/docs/guides/event-storming/01-index.mdx b/examples/default/docs/guides/event-storming/01-index.mdx
deleted file mode 100644
index 580ed6477..000000000
--- a/examples/default/docs/guides/event-storming/01-index.mdx
+++ /dev/null
@@ -1,105 +0,0 @@
----
-title: Getting Started with Event Storming
-summary: Learn how to use Event Storming to discover and model your business domain effectively
-sidebar:
-    label: Introduction
-    order: 1
-owners: 
-  - dboyne
-badges:
-  - content: 'Guide'
-    backgroundColor: 'teal'
-    textColor: 'teal'
----
-
-# Introduction to Event Storming
-
-Event Storming is a collaborative modeling technique that helps teams explore complex business domains. It was introduced by Alberto Brandolini and has become a valuable tool in Domain-Driven Design (DDD) and Event-Driven Architecture (EDA).
-
-## Why Event Storming?
-
-At FlowMart, we use Event Storming because it:
-
-- Brings together domain experts and technical teams
-- Helps identify domain events, commands, and aggregates
-- Aligns perfectly with our event-driven architecture
-- Facilitates better understanding of business processes
-- Helps in defining service boundaries and responsibilities
-
-## Example Event Storming Session
-
-Here is an example of an event storming session for the Orders domain.
-
-<Miro boardId="uXjVIHCImos=/" moveToWidget="3074457347671667709" edit={false} />
-
-## Event Storming Example in Lucid Chart
-
-<Lucid diagramId="e29f42a0-67e2-4f80-b0d7-6922bb7dd9c5" />
-
-## Git workflow 
-
-<DrawIO url="https://viewer.diagrams.net/?border=0&tags=%7B%7D&lightbox=1&highlight=0000ff&edit=_blank&layers=1&nav=1&title=Untitled%20Diagram.drawio&dark=auto#R%3Cmxfile%3E%3Cdiagram%20id%3D%22yPxyJZ8AM_hMuL3Unpa9%22%20name%3D%22complex%20gitflow%22%3E7V1dm6I2FP41c6kP4ZvL0dHd7bbbbWf7tNubPhmJSheIhTjj7K9vwoeiiRgREGfZi1kJECDvez5yzoHcaeNg8y6Cq%2BUv2EX%2Bnaq4mzvt4U5VgaIq9D%2FW8pq2mEBLGxaR52YH7Roeve8oPzNrXXsuivcOJBj7xFvtN85wGKIZ2WuDUYRf9g%2BbY3%2F%2Fqiu4QFzD4wz6fOufnkuWWStQlN2O98hbLLNL20a2I4D5wVlDvIQufik0aZM7bRxhTNJfwWaMfDZ4%2Bbik502P7N3eWIRCInPC%2Bs8%2Fwk%2BTB%2FP9xFfhR2Puwg9PAyvt5Rn66%2ByB32My9za0bYyDwCPZvZPXfEAI2tDLjZYk8GkDoD9jEuFvaIx9HNGWEIf0yNHc8%2F2DJuh7i5BuzugNI9o%2BekYR8ehQ32c7As912WVGL0uPoMcVnLFrvlBi0TZMj577yQAu6XGInjDihyAbFdYz2hSasiF5h3CASPRKD8n26qo1VI30rIyilKTp9ssOcDsDcVmAWsvaYEaxxbbzHQr0RwbEGaDYHCgcCsilLM02cUSWeIFD6E92raMIr0MXscso%2B3D9iwh5zQQNrglmY7vt4WeMV9lxKx964eApuYcRCt17Jk07NGnL1GPPlfSfciCXEJ1jxR0dreRfciYdpL%2ByE5ONr2xjaOSbD5vizofX4tZnFHl0lBl%2FksajFIjxOpqhklHONQyB0QJl5zrL0cfPD9%2BxR15WH0bu9%2BnDb9YAZHRgYy5DKdVROUoBcJwrWUefsUcfYUdM%2FXQv6a1nJx6Qbntf1XnoVKDdbB09J6wDZRxEG4%2F8VfhdIADdOsT4JGH4E8rZKisCPKvnOCTZicConX7iAw1J%2BkXIh8R73jdctSun%2FL7LtFOu2H%2BGT8j%2FjGOPeJgp%2BCdMCA4Emp%2BwIedtyp4%2BWcIV6z7YLJinMWS2YLaEERnicMCs8D8RmiOKAxv1feVFT3A9ClCJiaL6aWRMtCkq1Vw12BvV5MQaOLy90Vq1NxKQXiT5QuESCGFRQ5xtcLpiVnIv9aRcK07dgi22JJamD3Vn9%2B%2B6RgUoxvXJVWp%2BdjxhG6%2BFjbMN0zmUO5%2FxzBhNYeD5rN8xJaZHO1OVT%2Bgl27mnwxynXIfVyWy9WyYr19I3b7KOmyaRMZvUY7JMtXsma6s83yCmGkUV3DeLqW2C7mGq1uGGXDzvFXkW5Zr5KB4SmlJSUeag1jK1BHmM6lgXqSlozgXQOKADKicc2F0KNRUnftuJYHar4JQtrkNgtQNhVThhNQTCqqtNCaterxd3QXDgBub6hqw%2BsLrlOBm3Y2RX62jl1%2BE6PRgTO7mLGqRW05yhdaCvbXBlM2t2RnLfYljPkhX12mf%2Fl7GCzwT1on5WIkk3uyfqdi%2FqDYq6IyvqoFuifkNT506KuqF3z6qrfAwfDMFQGVBOIRijBiZXPpqTNzG1snk0%2BVCIqgvgVJuC05IIWZ4bC2klC1NdnZqy6tSSDZq0o06tKvmMGpDJLOp2o9XUw56T0ALmHUuCOzVHP%2FocVks5LGnC2WqnCGf2PtuF0zPATc8088o%2Bm1VLod%2B16y6qC6MlWwJldSssat1QCVQnhdEAeueEMc9%2B3rYwtmxOLdlop9Mt%2F83qo50XSrDTPQkGSs3hzkumZT%2BEN%2B1I5zUV2Rr6luZvfWLzwpowp4PuNG%2FBXfSMfApLH%2Fw8Gvy0eBx1DkcH8Dg2FvvMQ%2Bk%2FUOwzjzacDkt0q7I2v%2B9ej1b1oxTlUP50nS%2FtancmZF3fjeqDm1W0iC6pRTo2G8vvu9ciVb0xADqnRWzeG%2Fvpw%2B%2F3A80YDNAGBmwUVWWOIFlHfXa61EE7RNbgkG03OW3z0ZMvS4Zm5m4HKKk2x2wc4lWU1p4%2FRTCcLW8UaKWKvj4DY4Nzwm3eCW8ZZD458ZWyuyizPaZnYaqbVxdcPouYCu62SKiHtPSlKU5MlWsXCjl8LiqFNH2jZoun6bPRf6Lyay7Idjh6hLlSMO5jMLwfBQqlvu2ALBMR2c1OZj6MY29W5v6e9FzOHuSTc4kTbyrlbRe%2B7E4lktO7hp67UCdecOM%2FwmIIejvoq%2BmPsEiEWHrs0xMECtrSqyGvWaf7ahp5%2FjXJHnkxWipf3aPmCf1zkVf51AbXV%2BPfyOAV%2Fhe4uNPuaVtS1t2A%2BW7uXdkaDLPhKNz76pbAMoM2fS%2Bg8BJagEn58WBS%2BY%2BWiWCy2kVJotijr%2Bw59g2Xm8vtb%2B%2B8DydXlGJBcv%2Fq7zcBUOU1i7645xINYEprgI69y6xI1HL2GqBEA1j8TKoDGoBHteBtqT%2Bet2UD3tsy7Ws7xTJfEmhp2pqXEexKB77eFSoHhGUEUgpz%2Fhj%2BbTyHX7%2FE%2Ftj4BKOPQfTPQDap3s6U2ALcF75MzagaCBP0piuNhUOEw9vHQGWhtxWuHECzKgIv6kttLAIqBF7kzqfpjHgFwz0GmP%2Bt2ef0R0zxDzIdzsxDpsa3%2B%2FMsyBQlyxXMI8RSJtTfow%2FluvRviAmKE3SSRCd8wms2KCRJrawiPEMx243n9E%2BAooUXLthjhEkXRJhTG4qSMGkLHZb0UW4qN6PK5Gbq%2B3KyJYrI8hlVYGpbTVWULdM8LkayBq9M7Qvo6XrPQnbyPNwndCPcPMzao3h4lH7b5uQJelKW1W%2BqQ3P%2F03y6zZNSB7aQlFpTpJR4XbiFEmoRMHWuCFHdV8u8ZImprSZp2i%2FNYAg%2Bsmsf%2BOhH7Cx1eeBr4bAVOyCudKmjOZGTp9Af6X3UavpFL0hXM%2F2MLArj3yBOCJlMGsFqI1THE8hKJig7FgmwqwjFKBlSBaYq1l3PknDB1sof16U3oTVBu1rT0Q9qGoEhmLaqouiCfbbC%2FCNG0a9P%2F7LFoVTFZ9Ge9NTJtgjV9eAigkFCkCgD%2BQVH35IRo%2Bh5dH4Ao9wI7%2BjyziOD9JgdgZSEWuwWfS%2F8ll5pSQhbreqe3aE6DZ89NJxhernpCseMVVM4iNczZrbna3%2BwoL2mJpoa7kGQrqg1TfvMhUW4To1aGPNMuHjiidhxqLEPqltzkpg1RS04VSL4li1blqmmEhu6WaBAKSVyIWYEWEZovqdY6kHxUNXU1Guue%2BC%2B4mmdg1oNHKyBY9tswevBdjF4abTOr0eErqcerG5Aw4u%2FEBy1QfHnfA%2Fxsl8SacQ%2B4JRiavGL6B06r9IBJ0FfupwjXMHrFCN%2FfEr%2FViJOfQyqmvIy%2BPUXBHkxYIq9F7tEsmSn%2B2LXrxuvTB9%2BW%2FcWFvEqXfLxCp%2F2FWtFw%2BTq3xpcuKt0TG4hqX5kxR2qDSb35sg0Oe3FltexDd0Q5NWn9ngyHtejP3Ref7S57I4QV5PXHXtFjIBD%2BY2n1XXVPgxPNFfDSDd3S0CnorpbSFub%2FA8%3D%3C%2Fdiagram%3E%3C%2Fmxfile%3E" />
-
-## Key Concepts
-
-### Domain Events
-- Represent something significant that has happened in the business domain
-- Written in past tense (e.g., "Order Placed", "Payment Received")
-- Captured on orange sticky notes during the session
-
-### Commands
-- Triggers that cause domain events
-- Written in imperative form (e.g., "Place Order", "Process Payment")
-- Captured on blue sticky notes
-
-### Aggregates
-- Business entities that ensure consistency
-- Group related events and commands
-- Captured on yellow sticky notes
-
-### Policies
-- Business rules that react to events
-- Automated processes or human workflows
-- Captured on purple sticky notes
-
-## Event Storming Levels
-
-1. **Big Picture Event Storming**
-   - High-level view of the entire business domain
-   - Focuses on major events and workflows
-   - Helps identify bounded contexts
-
-2. **Process Level Event Storming**
-   - Detailed view of specific processes
-   - Includes commands, policies, and external systems
-   - Helps design individual services
-
-3. **Software Design Level Event Storming**
-   - Technical perspective of the domain
-   - Includes aggregates, entities, and value objects
-   - Leads to implementation decisions
-
-## Benefits for FlowMart
-
-Event Storming has helped us:
-- Design our microservices architecture
-- Identify service boundaries
-- Define event contracts between services
-- Improve collaboration between teams
-- Reduce misunderstandings and rework
-
-## Prerequisites for Event Storming
-
-To conduct an effective Event Storming session, you'll need:
-
-- A large modeling space (physical or virtual)
-- Sticky notes in different colors
-- Domain experts and technical team members
-- A skilled facilitator
-- 2-4 hours of uninterrupted time
-
-## Next Steps
-
-Continue reading to learn:
-- [How to Facilitate an Event Storming Session](/docs/guides/event-storming/02-facilitation)
-- [From Event Storming to Implementation](/docs/guides/event-storming/03-implementation) 
\ No newline at end of file
diff --git a/examples/default/docs/guides/event-storming/02-facilitation.mdx b/examples/default/docs/guides/event-storming/02-facilitation.mdx
deleted file mode 100644
index 13f9be89d..000000000
--- a/examples/default/docs/guides/event-storming/02-facilitation.mdx
+++ /dev/null
@@ -1,131 +0,0 @@
----
-title: Facilitating an Event Storming Session
-summary: A comprehensive guide on how to run effective Event Storming workshops at FlowMart
-sidebar:
-    label: Facilitation Guide
-    order: 2
-owners: 
-  - dboyne
-badges:
-  - content: 'Guide'
-    backgroundColor: 'teal'
-    textColor: 'teal'
----
-
-# Facilitating an Event Storming Session
-
-This guide will help you run effective Event Storming sessions at FlowMart, ensuring you get the most value from this collaborative modeling technique.
-
-## Pre-Session Preparation
-
-### 1. Define the Scope
-- Identify the business domain or process to explore
-- Set clear objectives for the session
-- Determine the appropriate level (Big Picture, Process, or Design)
-
-### 2. Invite the Right People
-- Domain experts who understand the business processes
-- Technical team members who will implement the solution
-- Product owners and stakeholders
-- Limit to 8-12 participants for optimal interaction
-
-### 3. Prepare the Space
-- Large continuous wall space or virtual whiteboard
-- Sticky notes in different colors:
-  - Orange: Domain Events
-  - Blue: Commands
-  - Yellow: Aggregates
-  - Purple: Policies
-  - Pink: External Systems
-  - Red: Problems/Questions
-
-## Running the Session
-
-### 1. Introduction (15 minutes)
-- Explain Event Storming concepts and notation
-- Set ground rules:
-  - No laptops/phones unless necessary
-  - Everyone participates
-  - No wrong answers
-  - Focus on the business process
-
-### 2. Event Discovery (45-60 minutes)
-- Start with "What happens in this domain?"
-- Let participants write domain events on orange stickies
-- Place events on the timeline (left to right)
-- Don't worry about order initially
-
-### 3. Timeline Organization (30 minutes)
-- Review all events as a group
-- Organize events chronologically
-- Identify missing events
-- Group related events together
-
-### 4. Adding Detail (60-90 minutes)
-- Add commands (blue) that trigger events
-- Identify external systems (pink)
-- Mark problem areas (red)
-- Add policies and reactions (purple)
-
-### 5. Identifying Boundaries (45 minutes)
-- Group related concepts
-- Look for natural service boundaries
-- Discuss integration points
-- Identify aggregates (yellow)
-
-## Common Challenges and Solutions
-
-### Challenge: Dominant Participants
-- Actively engage quieter participants
-- Use round-robin techniques
-- Split into smaller groups temporarily
-
-### Challenge: Too Much Detail
-- Keep focus on relevant abstraction level
-- Park detailed discussions for later
-- Use "parking lot" for important but off-topic items
-
-### Challenge: Losing Focus
-- Take regular breaks (10 minutes every hour)
-- Use timeboxing for each activity
-- Keep referring back to session goals
-
-## Remote Facilitation Tips
-
-When running remote Event Storming sessions:
-
-- Use tools like Miro or Mural
-- Pre-create templates and sticky note colors
-- Use breakout rooms for small group discussions
-- Schedule more frequent but shorter sessions
-- Use video to maintain engagement
-
-## Post-Session Activities
-
-1. **Documentation**
-   - Photograph or export the board
-   - Capture key insights and decisions
-   - Document identified bounded contexts
-
-2. **Follow-up**
-   - Schedule deep-dive sessions for specific areas
-   - Create action items and assign owners
-   - Plan next steps for implementation
-
-3. **Review and Refine**
-   - Review findings with stakeholders
-   - Validate assumptions
-   - Plan additional sessions if needed
-
-## Measuring Success
-
-A successful Event Storming session should:
-- Create shared understanding
-- Identify key domain events and processes
-- Highlight potential problems and solutions
-- Generate actionable next steps
-- Engage all participants effectively
-
-## Next Steps
-
-Continue to [From Event Storming to Implementation](/docs/guides/event-storming/03-implementation) to learn how to turn your Event Storming insights into working software. 
\ No newline at end of file
diff --git a/examples/default/docs/guides/event-storming/03-implementation.mdx b/examples/default/docs/guides/event-storming/03-implementation.mdx
deleted file mode 100644
index 83e93197f..000000000
--- a/examples/default/docs/guides/event-storming/03-implementation.mdx
+++ /dev/null
@@ -1,207 +0,0 @@
----
-title: From Event Storming to Implementation
-summary: Learn how to transform Event Storming outcomes into concrete microservice implementations at FlowMart
-sidebar:
-    label: Implementation
-    order: 3
-owners: 
-  - dboyne
-badges:
-  - content: 'Guide'
-    backgroundColor: 'teal'
-    textColor: 'teal'
----
-
-# From Event Storming to Implementation
-
-This guide will help you transform the insights gained from Event Storming sessions into concrete microservice implementations at FlowMart.
-
-## Translating Event Storming Artifacts
-
-### Domain Events to Event Schema
-Convert orange sticky notes (domain events) into event schemas:
-
-```typescript
-// Example Event Schema for "OrderPlaced"
-interface OrderPlacedEvent {
-  eventType: 'OrderPlaced';
-  orderId: string;
-  customerId: string;
-  orderItems: OrderItem[];
-  totalAmount: number;
-  timestamp: string;
-}
-```
-
-### Commands to API Endpoints
-Transform blue sticky notes (commands) into API endpoints:
-
-```typescript
-// Example API endpoint for "PlaceOrder"
-@POST
-@Path("/orders")
-async placeOrder(orderRequest: OrderRequest): Promise<OrderResponse> {
-  // Implementation
-}
-```
-
-### Aggregates to Service Boundaries
-Convert yellow sticky notes (aggregates) into service definitions:
-
-```typescript
-// Example Order Service
-@Service
-class OrderService {
-  private readonly orderRepository: OrderRepository;
-  private readonly eventPublisher: EventPublisher;
-  
-  async createOrder(order: Order): Promise<Order> {
-    // Implementation
-  }
-}
-```
-
-## Implementation Steps
-
-### 1. Define Service Boundaries
-- Use bounded contexts identified during Event Storming
-- Create new service repositories using our [templates](/docs/guides/creating-new-microservices)
-- Define service interfaces and contracts
-
-### 2. Design Event Schemas
-- Create event schemas for all domain events
-- Use our [schema registry](/docs/technical-architecture-design/schema-registry)
-- Version schemas appropriately
-- Document event ownership and consumers
-
-### 3. Implement Commands
-- Create API endpoints for commands
-- Implement command handlers
-- Add validation and error handling
-- Document API contracts using OpenAPI
-
-### 4. Set Up Event Publishing
-- Implement event publishers
-- Configure Kafka topics
-- Set up dead letter queues
-- Implement retry mechanisms
-
-### 5. Create Event Subscribers
-- Implement event handlers
-- Set up consumer groups
-- Handle failure scenarios
-- Implement idempotency
-
-## Example Implementation Flow
-
-Here's a typical flow from Event Storming to implementation:
-
-1. **Event Storming Identifies**:
-   - Domain Event: "OrderPlaced"
-   - Command: "PlaceOrder"
-   - Aggregate: "Order"
-
-2. **Create Service Structure**:
-```typescript
-// Service structure based on Event Storming
-src/
-  ├── domain/
-  │   ├── Order.ts
-  │   └── OrderItem.ts
-  ├── commands/
-  │   └── PlaceOrderCommand.ts
-  ├── events/
-  │   └── OrderPlacedEvent.ts
-  └── api/
-      └── OrderController.ts
-```
-
-3. **Implement Domain Model**:
-```typescript
-class Order {
-  private readonly items: OrderItem[];
-  private status: OrderStatus;
-
-  placeOrder(): OrderPlacedEvent {
-    // Implementation
-    return new OrderPlacedEvent(this);
-  }
-}
-```
-
-## Best Practices
-
-### Event Design
-- Use past tense for event names
-- Include all necessary context
-- Follow our [event naming conventions](/docs/technical-architecture-design/event-naming)
-- Version events appropriately
-
-### Service Design
-- Keep services focused on single bounded context
-- Implement proper error handling
-- Add comprehensive logging
-- Include monitoring and metrics
-
-### Testing Strategy
-- Unit test domain logic
-- Integration test event flows
-- Contract test event schemas
-- End-to-end test critical paths
-
-## Common Pitfalls
-
-1. **Too Many Events**
-   - Solution: Focus on meaningful state changes
-   - Combine related events when appropriate
-
-2. **Tight Coupling**
-   - Solution: Use event-driven communication
-   - Avoid direct service-to-service calls
-
-3. **Missing Context**
-   - Solution: Include necessary data in events
-   - Document event purpose and usage
-
-## Monitoring and Observability
-
-Implement proper monitoring for:
-- Event processing metrics
-- Command execution times
-- Error rates and types
-- Service health indicators
-
-## Example: Order Processing Flow
-
-Here's a complete example of implementing an order processing flow:
-
-1. **Event Storming Identified**:
-   - Command: "PlaceOrder"
-   - Event: "OrderPlaced"
-   - Event: "PaymentProcessed"
-   - Policy: "Send Order Confirmation"
-
-2. **Implementation**:
-```typescript
-// Command Handler
-async function handlePlaceOrder(command: PlaceOrderCommand) {
-  const order = new Order(command.orderDetails);
-  const event = order.placeOrder();
-  await eventPublisher.publish('order-events', event);
-  return order;
-}
-
-// Event Handler
-async function handleOrderPlaced(event: OrderPlacedEvent) {
-  await paymentService.processPayment(event.orderId);
-  await notificationService.sendConfirmation(event.orderId);
-}
-```
-
-## Next Steps
-
-1. Review our [service templates](/docs/guides/creating-new-microservices)
-2. Study our [event schema guidelines](/docs/technical-architecture-design/event-schemas)
-3. Explore our [monitoring setup](/docs/operations-and-support/monitoring)
-
-Remember: Event Storming is an iterative process. As you implement and learn more about the domain, you may need to revisit and refine your model. Keep the dialogue open between domain experts and developers throughout the implementation phase. 
\ No newline at end of file
diff --git a/examples/default/docs/operations-and-support/runbooks/inventory-service-runbook.mdx b/examples/default/docs/operations-and-support/runbooks/inventory-service-runbook.mdx
deleted file mode 100644
index fe86f1d58..000000000
--- a/examples/default/docs/operations-and-support/runbooks/inventory-service-runbook.mdx
+++ /dev/null
@@ -1,349 +0,0 @@
----
-title: Inventory Service - Runbook
-summary: Operational runbook for troubleshooting and maintaining the InventoryService
-sidebar:
-    label: InventoryService
-    order: 2
-owners:
-    - order-management
-badges:
-   - content: 🚀 Operational Procedures
-     textColor: white
-     backgroundColor: blue
-   - content: 🚨 Troubleshooting Guide
-     textColor: white
-     backgroundColor: red
-   - content: 🔄 Maintenance Schedule
-     textColor: white
-     backgroundColor: yellow
----
-
-This runbook provides operational procedures for the InventoryService, which is responsible for managing product inventory and stock levels across the FlowMart e-commerce platform.
-
-## Architecture
-
-The InventoryService is responsible for:
-- Managing product inventory and stock levels
-- Reserving inventory for pending orders
-- Tracking inventory across warehouses and locations
-- Providing real-time availability information
-- Triggering restock notifications
-
-### Service Dependencies
-
-```mermaid
-flowchart TD
-    InventoryService --> PostgresDB[(PostgreSQL Database)]
-    InventoryService --> Redis[(Redis Cache)]
-    InventoryService --> EventBus[Event Bus]
-    InventoryService --> WarehouseSystem[Warehouse Management System]
-```
-
-## Monitoring and Alerting
-
-### Key Metrics
-
-| Metric | Description | Warning Threshold | Critical Threshold |
-|--------|-------------|-------------------|-------------------|
-| `inventory_check_rate` | Inventory availability checks per minute | > 1000 | > 5000 |
-| `inventory_check_latency` | Time to check inventory availability | > 100ms | > 500ms |
-| `inventory_update_latency` | Time to update inventory levels | > 200ms | > 1s |
-| `low_stock_items` | Number of items with low stock | > 50 | > 100 |
-| `connection_pool_usage` | Database connection pool utilization | > 70% | > 90% |
-| `redis_hit_rate` | Cache hit rate | < 80% | < 60% |
-
-### Dashboards
-
-- [InventoryService Overview](https://grafana.flowmart.com/d/inventory-overview)
-- [Stock Level Alerts](https://grafana.flowmart.com/d/inventory-stock-alerts)
-- [Database Performance](https://grafana.flowmart.com/d/inventory-database)
-
-### Common Alerts
-
-| Alert | Description | Troubleshooting Steps |
-|-------|-------------|----------------------|
-| `InventoryServiceHighLatency` | API latency exceeds thresholds | See [High Latency](#high-latency) |
-| `InventoryServiceDatabaseIssues` | Database connection or performance issues | See [Database Issues](#database-issues) |
-| `InventoryServiceCacheFailure` | Redis cache unavailable or performance degraded | See [Cache Issues](#cache-issues) |
-| `InventoryServiceOutOfStock` | Critical products out of stock | See [Stock Management](#stock-management) |
-
-## Troubleshooting Guides
-
-### High Latency
-
-If the service is experiencing high latency:
-
-1. **Check system resource usage**:
-   ```bash
-   kubectl top pods -n inventory
-   ```
-
-2. **Check database connection pool**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=inventory-service -n inventory -o jsonpath='{.items[0].metadata.name}') -n inventory -- curl localhost:8080/actuator/metrics/hikaricp.connections.usage
-   ```
-
-3. **Check cache hit rate**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=inventory-service -n inventory -o jsonpath='{.items[0].metadata.name}') -n inventory -- curl localhost:8080/actuator/metrics/cache.gets | grep "hit_ratio"
-   ```
-
-4. **Check for slow queries** in the database:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql -n data -o jsonpath='{.items[0].metadata.name}') -n data -- psql -U postgres -c "SELECT query, calls, mean_exec_time FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;"
-   ```
-
-5. **Scale the service** if needed:
-   ```bash
-   kubectl scale deployment inventory-service -n inventory --replicas=5
-   ```
-
-### Database Issues
-
-If there are database connection or performance issues:
-
-1. **Check PostgreSQL status**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql -n data -o jsonpath='{.items[0].metadata.name}') -n data -- pg_isready -U postgres
-   ```
-
-2. **Check for long-running transactions**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql -n data -o jsonpath='{.items[0].metadata.name}') -n data -- psql -U postgres -c "SELECT pid, now() - xact_start AS duration, state, query FROM pg_stat_activity WHERE state != 'idle' ORDER BY duration DESC;"
-   ```
-
-3. **Check for table bloat**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql -n data -o jsonpath='{.items[0].metadata.name}') -n data -- psql -U postgres -c "SELECT schemaname, relname, n_live_tup, n_dead_tup, (n_dead_tup::float / n_live_tup::float) AS dead_ratio FROM pg_stat_user_tables WHERE n_live_tup > 1000 ORDER BY dead_ratio DESC;"
-   ```
-
-4. **Restart database connections** in the application if needed:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=inventory-service -n inventory -o jsonpath='{.items[0].metadata.name}') -n inventory -- curl -X POST localhost:8080/actuator/restart-db-connections
-   ```
-
-### Cache Issues
-
-If there are Redis cache issues:
-
-1. **Check Redis status**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=redis -n data -o jsonpath='{.items[0].metadata.name}') -n data -- redis-cli ping
-   ```
-
-2. **Check Redis memory usage**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=redis -n data -o jsonpath='{.items[0].metadata.name}') -n data -- redis-cli info memory
-   ```
-
-3. **Check cache hit rate**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=redis -n data -o jsonpath='{.items[0].metadata.name}') -n data -- redis-cli info stats | grep hit_rate
-   ```
-
-4. **Clear cache** if necessary:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=inventory-service -n inventory -o jsonpath='{.items[0].metadata.name}') -n inventory -- curl -X POST localhost:8080/actuator/caches/clearAll
-   ```
-
-### Stock Management
-
-For critical stock issues:
-
-1. **Identify products with low or no stock**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=inventory-service -n inventory -o jsonpath='{.items[0].metadata.name}') -n inventory -- curl localhost:8080/internal/api/inventory/low-stock
-   ```
-
-2. **Check for stuck inventory reservations**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=inventory-service -n inventory -o jsonpath='{.items[0].metadata.name}') -n inventory -- curl localhost:8080/internal/api/inventory/stuck-reservations
-   ```
-
-3. **Release expired reservations** if necessary:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=inventory-service -n inventory -o jsonpath='{.items[0].metadata.name}') -n inventory -- curl -X POST localhost:8080/internal/api/inventory/release-expired-reservations
-   ```
-
-4. **Manually update inventory levels** for emergency corrections:
-   ```bash
-   curl -X PUT https://api.internal.flowmart.com/inventory/products/{productId}/stock \
-     -H "Authorization: Bearer $ADMIN_TOKEN" \
-     -H "Content-Type: application/json" \
-     -d '{"warehouseId": "WAREHOUSE_ID", "quantity": 100, "reason": "Manual correction"}'
-   ```
-
-## Common Operational Tasks
-
-### Scaling the Service
-
-To scale the service horizontally:
-
-```bash
-kubectl scale deployment inventory-service -n inventory --replicas=<number>
-```
-
-### Restarting the Service
-
-To restart all pods:
-
-```bash
-kubectl rollout restart deployment inventory-service -n inventory
-```
-
-### Database Maintenance
-
-For routine database maintenance:
-
-1. **Run VACUUM ANALYZE to optimize tables**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql -n data -o jsonpath='{.items[0].metadata.name}') -n data -- psql -U postgres -c "VACUUM ANALYZE inventory_items;"
-   ```
-
-2. **Update database statistics**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql -n data -o jsonpath='{.items[0].metadata.name}') -n data -- psql -U postgres -c "ANALYZE;"
-   ```
-
-### Reconcile Inventory
-
-To reconcile inventory with the warehouse management system:
-
-```bash
-kubectl exec -it $(kubectl get pods -l app=inventory-service -n inventory -o jsonpath='{.items[0].metadata.name}') -n inventory -- curl -X POST localhost:8080/internal/api/inventory/reconcile
-```
-
-### Manually Trigger Restock Notifications
-
-To trigger restock notifications for low stock items:
-
-```bash
-kubectl exec -it $(kubectl get pods -l app=inventory-service -n inventory -o jsonpath='{.items[0].metadata.name}') -n inventory -- curl -X POST localhost:8080/internal/api/inventory/trigger-restock-notifications
-```
-
-## Recovery Procedures
-
-### Database Failure Recovery
-
-If the PostgreSQL database becomes unavailable:
-
-1. Verify the status of the PostgreSQL cluster:
-   ```bash
-   kubectl get pods -l app=postgresql -n data
-   ```
-
-2. If the primary instance is down, check if automatic failover has occurred:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql-patroni -n data -o jsonpath='{.items[0].metadata.name}') -n data -- patronictl list
-   ```
-
-3. If automatic failover has not occurred, initiate manual failover:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql-patroni -n data -o jsonpath='{.items[0].metadata.name}') -n data -- patronictl failover
-   ```
-
-4. Once database availability is restored, validate the InventoryService functionality:
-   ```bash
-   curl -X GET https://api.internal.flowmart.com/inventory/health
-   ```
-
-### Cache Failure Recovery
-
-If the Redis cache becomes unavailable:
-
-1. Verify Redis cluster status:
-   ```bash
-   kubectl get pods -l app=redis -n data
-   ```
-
-2. If needed, restart the Redis cluster:
-   ```bash
-   kubectl rollout restart statefulset redis -n data
-   ```
-
-3. The InventoryService will fall back to database queries when the cache is unavailable.
-
-4. When the cache is restored, you can warm it up:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=inventory-service -n inventory -o jsonpath='{.items[0].metadata.name}') -n inventory -- curl -X POST localhost:8080/internal/api/inventory/warm-cache
-   ```
-
-## Disaster Recovery
-
-### Complete Service Failure
-
-In case of a complete service failure:
-
-1. Initiate incident response by notifying the on-call team through PagerDuty.
-
-2. Verify the deployment status:
-   ```bash
-   kubectl describe deployment inventory-service -n inventory
-   ```
-
-3. If necessary, restore from a previous version:
-   ```bash
-   kubectl rollout undo deployment inventory-service -n inventory
-   ```
-
-4. If the primary region is experiencing issues, fail over to the secondary region:
-   ```bash
-   ./scripts/dr-failover.sh inventory-service
-   ```
-
-5. Verify the service is functioning in the secondary region:
-   ```bash
-   curl -X GET https://api-dr.internal.flowmart.com/inventory/health
-   ```
-
-## Maintenance Tasks
-
-### Deploying New Versions
-
-```bash
-kubectl set image deployment/inventory-service -n inventory inventory-service=ecr.aws/flowmart/inventory-service:$VERSION
-```
-
-### Database Schema Updates
-
-For database schema updates:
-
-1. Notify stakeholders through the #maintenance Slack channel.
-
-2. Set InventoryService to maintenance mode:
-   ```bash
-   curl -X POST https://api.internal.flowmart.com/inventory/admin/maintenance -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" -d '{"maintenanceMode": true, "message": "Database schema update"}'
-   ```
-
-3. Apply the database migrations:
-   ```bash
-   kubectl apply -f inventory-flyway-job.yaml
-   ```
-
-4. Verify migration completion:
-   ```bash
-   kubectl logs -l job-name=inventory-flyway-migration -n inventory
-   ```
-
-5. Turn off maintenance mode:
-   ```bash
-   curl -X POST https://api.internal.flowmart.com/inventory/admin/maintenance -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" -d '{"maintenanceMode": false}'
-   ```
-
-## Contact Information
-
-**Primary On-Call:** Inventory Team (rotating schedule)  
-**Secondary On-Call:** Platform Team  
-**Escalation Path:** Inventory Team Lead > Engineering Manager > CTO
-
-**Slack Channels:**
-- #inventory-support (primary support channel)
-- #inventory-alerts (automated alerts)
-- #incident-response (for major incidents)
-
-## Reference Information
-
-- [InventoryService API Documentation](https://docs.internal.flowmart.com/inventory/api)
-- [Architecture Diagram](https://docs.internal.flowmart.com/architecture/inventory)
-- [Service Level Objectives (SLOs)](https://docs.internal.flowmart.com/slo/inventory)
-- [Database Schema](https://docs.internal.flowmart.com/inventory/database-schema) 
\ No newline at end of file
diff --git a/examples/default/docs/operations-and-support/runbooks/orders-service-runbook.mdx b/examples/default/docs/operations-and-support/runbooks/orders-service-runbook.mdx
deleted file mode 100644
index 4799ddca9..000000000
--- a/examples/default/docs/operations-and-support/runbooks/orders-service-runbook.mdx
+++ /dev/null
@@ -1,279 +0,0 @@
----
-title: OrdersService Runbook
-summary: Operational runbook for troubleshooting and maintaining the OrdersService
-sidebar:
-    label: OrdersService
-    order: 1
----
-
-This runbook provides operational procedures for the OrdersService, which is responsible for managing the entire lifecycle of customer orders in the FlowMart e-commerce platform.
-
-
-## Architecture
-
-The OrdersService is responsible for:
-- Creating and processing customer orders
-- Tracking order status throughout fulfillment
-- Coordinating with other services (Inventory, Payment, Shipping)
-- Managing order history and amendments
-
-### Service Dependencies
-
-```mermaid
-flowchart TD
-    OrdersService --> InventoryService[Inventory Service]
-    OrdersService --> PaymentService[Payment Service]
-    OrdersService --> ShippingService[Shipping Service]
-    OrdersService --> NotificationService[Notification Service]
-    OrdersService --> OrdersDB[(Orders Database)]
-    OrdersService --> EventBus[Event Bus]
-```
-
-## Monitoring and Alerting
-
-### Key Metrics
-
-| Metric | Description | Warning Threshold | Critical Threshold |
-|--------|-------------|-------------------|-------------------|
-| `order_creation_rate` | Orders created per minute | < 5 | < 1 |
-| `order_creation_latency` | Time to create an order | > 2s | > 5s |
-| `order_error_rate` | Percentage of failed orders | > 1% | > 5% |
-| `database_connection_pool` | Database connection pool utilization | > 70% | > 90% |
-| `memory_usage` | Container memory usage | > 80% | > 90% |
-| `cpu_usage` | Container CPU usage | > 70% | > 85% |
-
-### Dashboards
-
-- [OrdersService Overview](https://grafana.flowmart.com/d/orders-overview)
-- [OrdersService API Metrics](https://grafana.flowmart.com/d/orders-api)
-- [OrdersService Error Tracking](https://grafana.flowmart.com/d/orders-errors)
-
-### Common Alerts
-
-| Alert | Description | Troubleshooting Steps |
-|-------|-------------|----------------------|
-| `OrdersServiceHighLatency` | API latency exceeds thresholds | See [High Latency](#high-latency) |
-| `OrdersServiceHighErrorRate` | Error rate exceeds thresholds | See [High Error Rate](#high-error-rate) |
-| `OrdersServiceDatabaseConnectionIssues` | Database connection issues | See [Database Issues](#database-issues) |
-
-## Troubleshooting Guides
-
-### High Latency
-
-If the service is experiencing high latency:
-
-1. **Check system metrics**:
-   ```bash
-   kubectl top pods -n orders
-   ```
-
-2. **Check database metrics** in the MongoDB dashboard to identify slow queries.
-
-3. **Check dependent services** to see if delays are caused by downstream systems:
-   ```bash
-   curl -X GET https://api.internal.flowmart.com/inventory/health
-   curl -X GET https://api.internal.flowmart.com/payment/health
-   ```
-
-4. **Analyze recent changes** that might have impacted performance.
-
-5. **Scale the service** if needed:
-   ```bash
-   kubectl scale deployment orders-service -n orders --replicas=5
-   ```
-
-### High Error Rate
-
-If the service is experiencing a high error rate:
-
-1. **Check application logs**:
-   ```bash
-   kubectl logs -l app=orders-service -n orders --tail=100
-   ```
-
-2. **Check for recent deployments** that might have introduced issues:
-   ```bash
-   kubectl rollout history deployment/orders-service -n orders
-   ```
-
-3. **Verify database connectivity**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=orders-service -n orders -o jsonpath='{.items[0].metadata.name}') -n orders -- node -e "const mongoose = require('mongoose'); mongoose.connect(process.env.MONGODB_URI).then(() => console.log('Connected!')).catch(err => console.error('Connection error', err));"
-   ```
-
-4. **Check dependent services** for failures:
-   ```bash
-   curl -X GET https://api.internal.flowmart.com/inventory/health
-   curl -X GET https://api.internal.flowmart.com/payment/health
-   ```
-
-5. **Consider rolling back** if issues persist:
-   ```bash
-   kubectl rollout undo deployment/orders-service -n orders
-   ```
-
-### Database Issues
-
-If there are database connection issues:
-
-1. **Check MongoDB status**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=mongodb -n data -o jsonpath='{.items[0].metadata.name}') -n data -- mongo admin -u admin -p $MONGODB_PASSWORD --eval "db.serverStatus()"
-   ```
-
-2. **Verify network connectivity**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=orders-service -n orders -o jsonpath='{.items[0].metadata.name}') -n orders -- ping mongodb.data.svc.cluster.local
-   ```
-
-3. **Check MongoDB resource usage**:
-   ```bash
-   kubectl top pods -l app=mongodb -n data
-   ```
-
-4. **Review MongoDB logs**:
-   ```bash
-   kubectl logs -l app=mongodb -n data --tail=100
-   ```
-
-## Common Operational Tasks
-
-### Scaling the Service
-
-To scale the service horizontally:
-
-```bash
-kubectl scale deployment orders-service -n orders --replicas=<number>
-```
-
-### Restarting the Service
-
-To restart all pods:
-
-```bash
-kubectl rollout restart deployment orders-service -n orders
-```
-
-### Viewing Recent Orders
-
-To view recent orders in the database:
-
-```bash
-kubectl exec -it $(kubectl get pods -l app=orders-service -n orders -o jsonpath='{.items[0].metadata.name}') -n orders -- node -e "const mongoose = require('mongoose'); const Order = require('./models/order'); mongoose.connect(process.env.MONGODB_URI).then(async () => { const orders = await Order.find().sort({createdAt: -1}).limit(10); console.log(JSON.stringify(orders, null, 2)); process.exit(0); });"
-```
-
-### Manually Processing Stuck Orders
-
-If orders are stuck in a particular state:
-
-1. Identify stuck orders:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=orders-service -n orders -o jsonpath='{.items[0].metadata.name}') -n orders -- node -e "const mongoose = require('mongoose'); const Order = require('./models/order'); mongoose.connect(process.env.MONGODB_URI).then(async () => { const stuckOrders = await Order.find({status: 'PROCESSING', updatedAt: {$lt: new Date(Date.now() - 30*60*1000)}}); console.log(JSON.stringify(stuckOrders, null, 2)); process.exit(0); });"
-   ```
-
-2. Manually trigger processing for a specific order:
-   ```bash
-   curl -X POST https://api.internal.flowmart.com/orders/process -H "Content-Type: application/json" -d '{"orderId": "ORDER_ID", "force": true}'
-   ```
-
-## Recovery Procedures
-
-### Database Failure Recovery
-
-If the MongoDB database becomes unavailable:
-
-1. Verify the status of the MongoDB cluster:
-   ```bash
-   kubectl get pods -l app=mongodb -n data
-   ```
-
-2. If the primary node is down, initiate a manual failover if necessary:
-   ```bash
-   kubectl exec -it mongodb-0 -n data -- mongo admin -u admin -p $MONGODB_PASSWORD --eval "rs.stepDown()"
-   ```
-
-3. If the entire cluster is unavailable, create an incident and notify the Database Team.
-
-4. Once database availability is restored, validate the OrdersService functionality:
-   ```bash
-   curl -X GET https://api.internal.flowmart.com/orders/health
-   ```
-
-### Event Bus Failure Recovery
-
-If the Event Bus is unavailable:
-
-1. The OrdersService implements the Circuit Breaker pattern and will queue messages locally.
-
-2. When the Event Bus is restored, check the backlog of events:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=orders-service -n orders -o jsonpath='{.items[0].metadata.name}') -n orders -- curl localhost:9090/metrics | grep event_queue
-   ```
-
-3. Manually trigger event processing if necessary:
-   ```bash
-   curl -X POST https://api.internal.flowmart.com/orders/admin/process-event-queue -H "Authorization: Bearer $ADMIN_TOKEN"
-   ```
-
-## Disaster Recovery
-
-### Complete Service Failure
-
-In case of a complete service failure:
-
-1. Initiate incident response by notifying the on-call team through PagerDuty.
-
-2. Check for region-wide AWS issues on the AWS Status page.
-
-3. If necessary, trigger the DR plan to fail over to the secondary region:
-   ```bash
-   ./scripts/dr-failover.sh orders-service
-   ```
-
-4. Update Route53 DNS to point to the secondary region if global failover is needed:
-   ```bash
-   aws route53 change-resource-record-sets --hosted-zone-id $HOSTED_ZONE_ID --change-batch file://dr-dns-change.json
-   ```
-
-## Maintenance Tasks
-
-### Deploying New Versions
-
-```bash
-kubectl set image deployment/orders-service -n orders orders-service=ecr.aws/flowmart/orders-service:$VERSION
-```
-
-### Database Maintenance
-
-Scheduled database maintenance should be performed during off-peak hours:
-
-1. Notify stakeholders through the #maintenance Slack channel.
-
-2. Set OrdersService to maintenance mode:
-   ```bash
-   curl -X POST https://api.internal.flowmart.com/orders/admin/maintenance -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" -d '{"maintenanceMode": true, "message": "Scheduled maintenance"}'
-   ```
-
-3. Perform database maintenance operations.
-
-4. Turn off maintenance mode:
-   ```bash
-   curl -X POST https://api.internal.flowmart.com/orders/admin/maintenance -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" -d '{"maintenanceMode": false}'
-   ```
-
-## Contact Information
-
-**Primary On-Call:** Orders Team (rotating schedule)  
-**Secondary On-Call:** Platform Team  
-**Escalation Path:** Orders Team Lead > Engineering Manager > CTO
-
-**Slack Channels:**
-- #orders-support (primary support channel)
-- #orders-alerts (automated alerts)
-- #incident-response (for major incidents)
-
-## Reference Information
-
-- [OrdersService API Documentation](https://docs.internal.flowmart.com/orders/api)
-- [Architecture Diagram](https://docs.internal.flowmart.com/architecture/orders)
-- [Service Level Objectives (SLOs)](https://docs.internal.flowmart.com/slo/orders) 
\ No newline at end of file
diff --git a/examples/default/docs/operations-and-support/runbooks/payment-service-runbook.mdx b/examples/default/docs/operations-and-support/runbooks/payment-service-runbook.mdx
deleted file mode 100644
index 1bc27f5cf..000000000
--- a/examples/default/docs/operations-and-support/runbooks/payment-service-runbook.mdx
+++ /dev/null
@@ -1,376 +0,0 @@
----
-title: PaymentService Runbook
-summary: Operational runbook for troubleshooting and maintaining the PaymentService
-sidebar:
-    label: PaymentService
-    order: 3
----
-
-This runbook provides operational procedures for the PaymentService, which is responsible for processing payments, refunds, and managing financial transactions in the FlowMart e-commerce platform.
-
-## Architecture
-
-The PaymentService is responsible for:
-- Processing customer payments
-- Managing refunds and chargebacks
-- Integrating with external payment gateways
-- Storing payment transactions
-- Handling subscription billing
-
-### Service Dependencies
-
-```mermaid
-flowchart TD
-    PaymentService --> PostgresDB[(PostgreSQL Database)]
-    PaymentService --> EventBus[Event Bus]
-    PaymentService --> StripeGateway[Stripe Payment Gateway]
-    PaymentService --> PayPalGateway[PayPal Gateway]
-    PaymentService --> VaultService[Vault - Secret Management]
-```
-
-## Monitoring and Alerting
-
-### Key Metrics
-
-| Metric | Description | Warning Threshold | Critical Threshold |
-|--------|-------------|-------------------|-------------------|
-| `payment_processing_rate` | Payments processed per minute | < 5 | < 1 |
-| `payment_success_rate` | Percentage of successful payments | < 95% | < 90% |
-| `payment_processing_latency` | Time to process a payment | > 3s | > 8s |
-| `refund_processing_latency` | Time to process a refund | > 5s | > 15s |
-| `gateway_error_rate` | Payment gateway errors | > 2% | > 5% |
-| `fraud_detection_latency` | Time for fraud checks | > 1s | > 3s |
-
-### Dashboards
-
-- [PaymentService Overview](https://grafana.flowmart.com/d/payment-overview)
-- [Payment Gateway Status](https://grafana.flowmart.com/d/payment-gateways)
-- [Transaction Success Rates](https://grafana.flowmart.com/d/payment-success-rates)
-
-### Common Alerts
-
-| Alert | Description | Troubleshooting Steps |
-|-------|-------------|----------------------|
-| `PaymentServiceHighErrorRate` | Payment failure rate above threshold | See [High Error Rate](#high-error-rate) |
-| `PaymentServiceGatewayFailure` | Payment gateway connection issues | See [Gateway Issues](#payment-gateway-issues) |
-| `PaymentServiceHighLatency` | Payment processing latency issues | See [High Latency](#high-latency) |
-| `PaymentServiceDatabaseIssues` | Database connection issues | See [Database Issues](#database-issues) |
-
-## Troubleshooting Guides
-
-### High Error Rate
-
-If the service is experiencing a high payment error rate:
-
-1. **Check application logs** for error patterns:
-   ```bash
-   kubectl logs -l app=payment-service -n payment --tail=100
-   ```
-
-2. **Check payment gateway status** on their status pages:
-   - [Stripe Status](https://status.stripe.com/)
-   - [PayPal Status](https://status.paypal.com/)
-
-3. **Check for patterns in failed transactions**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/query-failed-transactions.js --last-hour
-   ```
-
-4. **Check for recent deployments** that might have introduced issues:
-   ```bash
-   kubectl rollout history deployment/payment-service -n payment
-   ```
-
-5. **Verify if the issue is specific to a payment method** (credit card, PayPal, etc.):
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/payment-method-success-rates.js
-   ```
-
-### Payment Gateway Issues
-
-If there are issues with payment gateways:
-
-1. **Check gateway connectivity**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- curl -o /dev/null -s -w "%{http_code}\n" https://api.stripe.com/v1/charges -H "Authorization: Bearer $STRIPE_TEST_KEY"
-   ```
-
-2. **Check payment gateway API keys** rotation status:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/check-api-key-rotation.js
-   ```
-
-3. **Check gateway timeouts** in application logs:
-   ```bash
-   kubectl logs -l app=payment-service -n payment | grep "gateway timeout"
-   ```
-
-4. **Verify if the issue is isolated to a specific gateway**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/gateway-health-check.js
-   ```
-
-5. **Switch to backup payment gateway** if primary is down:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- curl -X POST localhost:3000/internal/api/payment/switch-gateway -H "Content-Type: application/json" -d '{"primaryGateway": "paypal", "reason": "Stripe outage"}'
-   ```
-
-### High Latency
-
-If the service is experiencing high latency:
-
-1. **Check system metrics**:
-   ```bash
-   kubectl top pods -n payment
-   ```
-
-2. **Check database connection pool**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/db-pool-stats.js
-   ```
-
-3. **Check slow queries** in the payment database:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql -n data -o jsonpath='{.items[0].metadata.name}') -n data -- psql -U postgres -d payments -c "SELECT query, calls, mean_exec_time, max_exec_time FROM pg_stat_statements WHERE mean_exec_time > 100 ORDER BY mean_exec_time DESC LIMIT 10;"
-   ```
-
-4. **Check payment gateway response times**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/gateway-latency-check.js
-   ```
-
-5. **Scale the service** if needed:
-   ```bash
-   kubectl scale deployment payment-service -n payment --replicas=5
-   ```
-
-### Database Issues
-
-If there are database issues:
-
-1. **Check PostgreSQL status**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql -n data -o jsonpath='{.items[0].metadata.name}') -n data -- pg_isready -U postgres -d payments
-   ```
-
-2. **Check for long-running transactions**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql -n data -o jsonpath='{.items[0].metadata.name}') -n data -- psql -U postgres -d payments -c "SELECT pid, now() - xact_start AS duration, state, query FROM pg_stat_activity WHERE state != 'idle' ORDER BY duration DESC LIMIT 10;"
-   ```
-
-3. **Check for database locks**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql -n data -o jsonpath='{.items[0].metadata.name}') -n data -- psql -U postgres -d payments -c "SELECT relation::regclass, mode, pid, granted FROM pg_locks l JOIN pg_stat_activity a ON l.pid = a.pid WHERE relation = 'payments.transactions'::regclass;"
-   ```
-
-4. **Restart database connections** if needed:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- curl -X POST localhost:3000/internal/api/system/refresh-db-connections
-   ```
-
-## Common Operational Tasks
-
-### Managing API Keys
-
-#### Rotating Payment Gateway API Keys
-
-1. **Generate new API keys** in the payment gateway admin portal.
-
-2. **Store the new keys** in AWS Secrets Manager:
-   ```bash
-   aws secretsmanager update-secret --secret-id flowmart/payment/stripe-api-key --secret-string '{"api_key": "sk_live_NEW_KEY", "webhook_secret": "whsec_NEW_SECRET"}'
-   ```
-
-3. **Trigger key rotation** in the service:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- curl -X POST localhost:3000/internal/api/system/reload-api-keys
-   ```
-
-4. **Verify the new keys are active**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/verify-api-keys.js
-   ```
-
-### Managing Refunds
-
-#### Processing Manual Refunds
-
-For special cases requiring manual intervention:
-
-```bash
-curl -X POST https://api.internal.flowmart.com/payment/transactions/{transactionId}/refund \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"amount": 1999, "reason": "Customer service request", "refundToOriginalMethod": true}'
-```
-
-#### Finding Failed Refunds
-
-To identify and retry failed refunds:
-
-```bash
-kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/list-failed-refunds.js --last-24h
-```
-
-### Handling Chargebacks
-
-To record and process a new chargeback:
-
-```bash
-curl -X POST https://api.internal.flowmart.com/payment/transactions/{transactionId}/chargeback \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"chargebackReference": "CB12345", "amount": 1999, "reason": "Unauthorized transaction"}'
-```
-
-### Payment Reconciliation
-
-To trigger payment reconciliation with payment gateway:
-
-```bash
-kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/reconcile-payments.js --gateway=stripe --date=2023-05-15
-```
-
-## Recovery Procedures
-
-### Failed Transactions Recovery
-
-If transactions are stuck or failed:
-
-1. **Identify stuck transactions**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/find-stuck-transactions.js
-   ```
-
-2. **Check transaction status** with the payment gateway:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/check-gateway-transaction.js --transaction-id=TXN123456
-   ```
-
-3. **Resolve transactions** that completed at gateway but failed in our system:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/resolve-stuck-transaction.js --transaction-id=TXN123456 --status=completed
-   ```
-
-### Payment Gateway Failure Recovery
-
-If a payment gateway is unavailable:
-
-1. **Enable fallback gateway** mode:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- curl -X POST localhost:3000/internal/api/system/enable-fallback-gateway
-   ```
-
-2. **Monitor gateway status** for recovery:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/monitor-gateway-health.js --gateway=stripe
-   ```
-
-3. **Disable fallback mode** once the primary gateway is restored:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- curl -X POST localhost:3000/internal/api/system/disable-fallback-gateway
-   ```
-
-### Database Failure Recovery
-
-If the PostgreSQL database becomes unavailable:
-
-1. Verify the status of the PostgreSQL cluster:
-   ```bash
-   kubectl get pods -l app=postgresql -n data
-   ```
-
-2. Check if automatic failover has occurred:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql-patroni -n data -o jsonpath='{.items[0].metadata.name}') -n data -- patronictl list
-   ```
-
-3. Once database availability is restored, validate the PaymentService functionality:
-   ```bash
-   curl -X GET https://api.internal.flowmart.com/payment/health
-   ```
-
-## Disaster Recovery
-
-### Complete Service Failure
-
-In case of a complete service failure:
-
-1. Initiate incident response by notifying the on-call team through PagerDuty.
-
-2. If necessary, deploy to the disaster recovery environment:
-   ```bash
-   ./scripts/dr-failover.sh payment-service
-   ```
-
-3. Update DNS records to point to the DR environment:
-   ```bash
-   aws route53 change-resource-record-sets --hosted-zone-id $HOSTED_ZONE_ID --change-batch file://dr-dns-change.json
-   ```
-
-4. Enable simplified payment flow (if necessary):
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- curl -X POST localhost:3000/internal/api/system/enable-simplified-flow
-   ```
-
-5. Regularly check primary environment recovery status.
-
-## Maintenance Tasks
-
-### Deploying New Versions
-
-```bash
-kubectl set image deployment/payment-service -n payment payment-service=ecr.aws/flowmart/payment-service:$VERSION
-```
-
-### Database Migrations
-
-For database schema updates:
-
-1. Notify stakeholders through the #maintenance Slack channel.
-
-2. Create a migration plan and backup the database:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=postgresql -n data -o jsonpath='{.items[0].metadata.name}') -n data -- pg_dump -U postgres -d payments > payments_backup_$(date +%Y%m%d).sql
-   ```
-
-3. Apply database migrations:
-   ```bash
-   kubectl apply -f payment-migration-job.yaml
-   ```
-
-4. Verify migration completion:
-   ```bash
-   kubectl logs -l job-name=payment-db-migration -n payment
-   ```
-
-### Compliance and Auditing
-
-To generate PCI compliance reports:
-
-```bash
-kubectl exec -it $(kubectl get pods -l app=payment-service -n payment -o jsonpath='{.items[0].metadata.name}') -n payment -- node scripts/generate-pci-audit-report.js --month=2023-05
-```
-
-## Contact Information
-
-**Primary On-Call:** Payments Team (rotating schedule)  
-**Secondary On-Call:** Platform Team  
-**Escalation Path:** Payments Team Lead > Engineering Manager > CTO
-
-**Slack Channels:**
-- #payments-support (primary support channel)
-- #payments-alerts (automated alerts)
-- #incident-response (for major incidents)
-
-**External Contacts:**
-- Stripe Support: support@stripe.com, 1-888-555-1234
-- PayPal Support: merchant-support@paypal.com, 1-888-555-5678
-
-## Reference Information
-
-- [PaymentService API Documentation](https://docs.internal.flowmart.com/payment/api)
-- [Architecture Diagram](https://docs.internal.flowmart.com/architecture/payment)
-- [Service Level Objectives (SLOs)](https://docs.internal.flowmart.com/slo/payment)
-- [PCI Compliance Documentation](https://docs.internal.flowmart.com/security/payment-pci)
-- [Payment Gateway Integration Guides](https://docs.internal.flowmart.com/payment/gateway-integration) 
\ No newline at end of file
diff --git a/examples/default/docs/operations-and-support/runbooks/shipping-service-runbook.mdx b/examples/default/docs/operations-and-support/runbooks/shipping-service-runbook.mdx
deleted file mode 100644
index 95a79438c..000000000
--- a/examples/default/docs/operations-and-support/runbooks/shipping-service-runbook.mdx
+++ /dev/null
@@ -1,434 +0,0 @@
----
-title: ShippingService Runbook
-summary: Operational runbook for troubleshooting and maintaining the ShippingService
-sidebar:
-    label: ShippingService
-    order: 4
----
-
-This runbook provides operational procedures for the ShippingService, which is responsible for managing shipping options, carrier integration, and delivery tracking in the FlowMart e-commerce platform.
-
-
-## Architecture
-
-The ShippingService is responsible for:
-- Calculating shipping costs and delivery estimates
-- Managing shipping carriers and integration
-- Generating shipping labels
-- Tracking shipments
-- Handling delivery exceptions and returns
-
-### Service Dependencies
-
-```mermaid
-flowchart TD
-    ShippingService --> MongoDB[(MongoDB Database)]
-    ShippingService --> EventBus[Event Bus]
-    ShippingService --> Redis[(Redis Cache)]
-    ShippingService --> FedExAPI[FedEx API]
-    ShippingService --> UPSApi[UPS API]
-    ShippingService --> USPSApi[USPS API]
-    ShippingService --> DHLApi[DHL API]
-    ShippingService --> VaultService[Vault - Secret Management]
-```
-
-## Monitoring and Alerting
-
-### Key Metrics
-
-| Metric | Description | Warning Threshold | Critical Threshold |
-|--------|-------------|-------------------|-------------------|
-| `shipping_rate_calculation_rate` | Rate calculations per minute | < 10 | < 2 |
-| `shipping_label_generation_success` | Label generation success % | < 98% | < 95% |
-| `carrier_api_response_time` | Carrier API response time | > 2s | > 5s |
-| `carrier_api_error_rate` | Carrier API errors % | > 2% | > 5% |
-| `tracking_update_processing_rate` | Tracking updates processed per minute | < 50 | < 10 |
-| `shipment_tracking_lag` | Delay in tracking information | > 15m | > 1h |
-
-### Dashboards
-
-- [Shipping Service Overview](https://grafana.flowmart.com/d/shipping-overview)
-- [Carrier API Status](https://grafana.flowmart.com/d/shipping-carriers)
-- [Delivery Performance](https://grafana.flowmart.com/d/shipping-delivery-performance)
-
-### Common Alerts
-
-| Alert | Description | Troubleshooting Steps |
-|-------|-------------|----------------------|
-| `ShippingServiceHighErrorRate` | Shipping API error rate above threshold | See [High Error Rate](#high-error-rate) |
-| `ShippingCarrierAPIDown` | Carrier API connection issues | See [Carrier API Issues](#carrier-api-issues) |
-| `ShippingServiceHighLatency` | Shipping service latency issues | See [High Latency](#high-latency) |
-| `ShippingServiceDatabaseIssues` | Database connection issues | See [Database Issues](#database-issues) |
-
-## Troubleshooting Guides
-
-### High Error Rate
-
-If the service is experiencing a high error rate:
-
-1. **Check application logs** for error patterns:
-   ```bash
-   kubectl logs -l app=shipping-service -n shipping --tail=100
-   ```
-
-2. **Check specific error types**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/error-analyzer.jar --last-hour
-   ```
-
-3. **Check for patterns in failed shipments**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/failed-shipments-analyzer.jar
-   ```
-
-4. **Check for recent deployments** that might have introduced issues:
-   ```bash
-   kubectl rollout history deployment/shipping-service -n shipping
-   ```
-
-5. **Verify if the issue is specific to a carrier** (FedEx, UPS, etc.):
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/carrier-success-rates.jar
-   ```
-
-### Carrier API Issues
-
-If there are issues with carrier APIs:
-
-1. **Check carrier API connectivity**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/carrier-health-check.jar
-   ```
-
-2. **Check carrier API credentials** and rotation status:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/check-carrier-credentials.jar
-   ```
-
-3. **Check carrier status pages** for announced outages:
-   - [FedEx Status](https://www.fedex.com/en-us/service-alerts.html)
-   - [UPS Status](https://www.ups.com/service-alerts)
-   - [USPS Status](https://about.usps.com/newsroom/service-alerts/)
-
-4. **Check carrier timeouts** in application logs:
-   ```bash
-   kubectl logs -l app=shipping-service -n shipping | grep "carrier timeout"
-   ```
-
-5. **Enable fallback shipping carrier**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- curl -X POST localhost:8080/internal/api/shipping/enable-fallback-carrier -H "Content-Type: application/json" -d '{"primaryCarrier": "fedex", "fallbackCarrier": "ups", "reason": "FedEx API outage"}'
-   ```
-
-### High Latency
-
-If the service is experiencing high latency:
-
-1. **Check system metrics**:
-   ```bash
-   kubectl top pods -n shipping
-   ```
-
-2. **Check JVM memory and GC metrics**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/jvm-metrics.jar
-   ```
-
-3. **Check MongoDB performance**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=mongodb -n data -o jsonpath='{.items[0].metadata.name}') -n data -- mongo --eval "db.currentOp()"
-   ```
-
-4. **Check carrier API response times**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/carrier-response-times.jar
-   ```
-
-5. **Scale the service** if needed:
-   ```bash
-   kubectl scale deployment shipping-service -n shipping --replicas=5
-   ```
-
-### Database Issues
-
-If there are MongoDB issues:
-
-1. **Check MongoDB status**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=mongodb -n data -o jsonpath='{.items[0].metadata.name}') -n data -- mongo --eval "rs.status()"
-   ```
-
-2. **Check for slow queries**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=mongodb -n data -o jsonpath='{.items[0].metadata.name}') -n data -- mongo --eval "db.currentOp({ 'active': true, 'secs_running': { '$gt': 5 } })"
-   ```
-
-3. **Check database connection pool**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/db-pool-stats.jar
-   ```
-
-4. **Restart database connections** if needed:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- curl -X POST localhost:8080/internal/api/system/refresh-db-connections
-   ```
-
-## Common Operational Tasks
-
-### Managing Carrier API Credentials
-
-#### Rotating Carrier API Keys
-
-1. **Generate new API keys** in the carrier portal:
-   - FedEx Developer Portal: [https://developer.fedex.com](https://developer.fedex.com)
-   - UPS Developer Portal: [https://developer.ups.com](https://developer.ups.com)
-   - USPS Web Tools: [https://www.usps.com/business/web-tools-apis](https://www.usps.com/business/web-tools-apis)
-
-2. **Store the new keys** in AWS Secrets Manager:
-   ```bash
-   aws secretsmanager update-secret --secret-id flowmart/shipping/fedex-api-key --secret-string '{"api_key": "NEW_KEY", "password": "NEW_PASSWORD", "account_number": "ACCOUNT_NUMBER"}'
-   ```
-
-3. **Trigger key rotation** in the service:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- curl -X POST localhost:8080/internal/api/system/reload-carrier-credentials
-   ```
-
-4. **Verify the new keys are working** by testing label generation:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/test-label-generation.jar --carrier=fedex
-   ```
-
-### Managing Shipping Rates
-
-#### Updating Shipping Rate Tables
-
-When carrier rates change:
-
-1. **Prepare the new rate table** in the required JSON format.
-
-2. **Upload the rate table** to S3:
-   ```bash
-   aws s3 cp new-fedex-rates.json s3://flowmart-configs/shipping/rates/
-   ```
-
-3. **Trigger rate table reload**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- curl -X POST localhost:8080/internal/api/shipping/reload-rate-tables -H "Content-Type: application/json" -d '{"carrier": "fedex"}'
-   ```
-
-4. **Verify rate calculations** with test scenarios:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/test-rate-calculation.jar
-   ```
-
-### Shipping Label Generation Troubleshooting
-
-#### Debugging Failed Label Generation
-
-If labels are failing to generate:
-
-```bash
-# Find recent failed label generation attempts
-kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/find-failed-labels.jar --hours=2
-
-# Get detailed error for a specific shipment
-kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/label-error-details.jar --shipment-id=SHIP123456
-```
-
-#### Manual Label Generation
-
-For special cases requiring manual intervention:
-
-```bash
-curl -X POST https://api.internal.flowmart.com/shipping/shipments/{shipmentId}/generate-label \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"carrier": "fedex", "service": "PRIORITY_OVERNIGHT", "forceGeneration": true}'
-```
-
-### Tracking Updates
-
-#### Triggering Manual Tracking Updates
-
-To manually trigger tracking updates:
-
-```bash
-kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/sync-tracking.jar --shipment-id=SHIP123456
-
-# For bulk tracking updates
-kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/sync-tracking.jar --status=in_transit --hours=24
-```
-
-#### Tracking Webhook Troubleshooting
-
-If tracking webhooks from carriers are failing:
-
-```bash
-# Check recent webhook failures
-kubectl logs -l app=shipping-webhook-service -n shipping | grep "Webhook failure"
-
-# Replay failed webhooks
-kubectl exec -it $(kubectl get pods -l app=shipping-webhook-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/replay-webhooks.jar --hours=2
-```
-
-## Recovery Procedures
-
-### Failed Shipment Recovery
-
-If shipments are stuck or failed:
-
-1. **Identify stuck shipments**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/find-stuck-shipments.jar
-   ```
-
-2. **Check shipment status** with the carrier:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/check-carrier-shipment.jar --shipment-id=SHIP123456
-   ```
-
-3. **Resolve shipments** that completed at carrier but failed in our system:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/resolve-shipment.jar --shipment-id=SHIP123456 --tracking-number=1Z999AA10123456784 --status=label_created
-   ```
-
-### Carrier API Failure Recovery
-
-If a carrier API is unavailable:
-
-1. **Enable automatic carrier fallback**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- curl -X POST localhost:8080/internal/api/system/enable-carrier-fallback
-   ```
-
-2. **Monitor carrier API status** for recovery:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/monitor-carrier-health.jar --carrier=fedex
-   ```
-
-3. **Switch back to primary carrier** once it's restored:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- curl -X POST localhost:8080/internal/api/system/disable-carrier-fallback
-   ```
-
-### Database Failure Recovery
-
-If the MongoDB database becomes unavailable:
-
-1. **Verify the status of the MongoDB cluster**:
-   ```bash
-   kubectl get pods -l app=mongodb -n data
-   ```
-
-2. **Check if automatic failover has occurred**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=mongodb -n data -o jsonpath='{.items[0].metadata.name}') -n data -- mongo --eval "rs.status()"
-   ```
-
-3. **Once database availability is restored, validate ShippingService functionality**:
-   ```bash
-   curl -X GET https://api.internal.flowmart.com/shipping/health
-   ```
-
-## Disaster Recovery
-
-### Complete Service Failure
-
-In case of a complete service failure:
-
-1. **Initiate incident response** by notifying the on-call team through PagerDuty.
-
-2. **Deploy to the disaster recovery environment** if necessary:
-   ```bash
-   ./scripts/dr-failover.sh shipping-service
-   ```
-
-3. **Update DNS records** to point to the DR environment:
-   ```bash
-   aws route53 change-resource-record-sets --hosted-zone-id $HOSTED_ZONE_ID --change-batch file://dr-dns-change.json
-   ```
-
-4. **Enable simplified shipping flow** (if necessary):
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- curl -X POST localhost:8080/internal/api/system/enable-simplified-flow
-   ```
-
-5. **Regularly check primary environment recovery status**.
-
-## Maintenance Tasks
-
-### Deploying New Versions
-
-```bash
-kubectl set image deployment/shipping-service -n shipping shipping-service=ecr.aws/flowmart/shipping-service:$VERSION
-```
-
-### Database Maintenance
-
-#### MongoDB Index Maintenance
-
-Periodically verify and optimize MongoDB indexes:
-
-```bash
-# Check current indexes
-kubectl exec -it $(kubectl get pods -l app=mongodb -n data -o jsonpath='{.items[0].metadata.name}') -n data -- mongo --eval "db.shipments.getIndexes()"
-
-# Add new index (example)
-kubectl exec -it $(kubectl get pods -l app=mongodb -n data -o jsonpath='{.items[0].metadata.name}') -n data -- mongo --eval "db.shipments.createIndex({carrier: 1, status: 1, createdAt: -1})"
-```
-
-#### Database Backups
-
-Verify scheduled MongoDB backups:
-
-```bash
-# Check recent backups
-aws s3 ls s3://flowmart-mongodb-backups/shipping/ --human-readable
-
-# Trigger manual backup if needed
-kubectl apply -f shipping-db-backup-job.yaml
-```
-
-### Carrier Integration Updates
-
-When a carrier updates their API:
-
-1. **Test the API changes** in the staging environment:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service-staging -n shipping-staging -o jsonpath='{.items[0].metadata.name}') -n shipping-staging -- java -jar /app/tools/test-carrier-integration.jar --carrier=fedex --mode=new
-   ```
-
-2. **Update integration configuration** if needed:
-   ```bash
-   kubectl apply -f updated-fedex-integration-config.yaml
-   ```
-
-3. **Validate the updated integration**:
-   ```bash
-   kubectl exec -it $(kubectl get pods -l app=shipping-service -n shipping -o jsonpath='{.items[0].metadata.name}') -n shipping -- java -jar /app/tools/validate-carrier-integration.jar --carrier=fedex
-   ```
-
-## Contact Information
-
-**Primary On-Call:** Logistics Team (rotating schedule)  
-**Secondary On-Call:** Platform Team  
-**Escalation Path:** Logistics Team Lead > Engineering Manager > CTO
-
-**Slack Channels:**
-- #shipping-support (primary support channel)
-- #shipping-alerts (automated alerts)
-- #incident-response (for major incidents)
-
-**External Contacts:**
-- FedEx API Support: apisupport@fedex.com, 1-800-555-1234
-- UPS Developer Support: developer@ups.com, 1-800-555-5678
-- USPS Web Tools Support: uspstechsupport@usps.gov, 1-800-555-9012
-
-## Reference Information
-
-- [ShippingService API Documentation](https://docs.internal.flowmart.com/shipping/api)
-- [Architecture Diagram](https://docs.internal.flowmart.com/architecture/shipping)
-- [Service Level Objectives (SLOs)](https://docs.internal.flowmart.com/slo/shipping)
-- [Carrier Integration Guides](https://docs.internal.flowmart.com/shipping/carrier-integration)
-- [Rate Calculation Documentation](https://docs.internal.flowmart.com/shipping/rate-calculation) 
\ No newline at end of file
diff --git a/examples/default/docs/operations/01-team-ownership.mdx b/examples/default/docs/operations/01-team-ownership.mdx
new file mode 100644
index 000000000..d261d9ae6
--- /dev/null
+++ b/examples/default/docs/operations/01-team-ownership.mdx
@@ -0,0 +1,35 @@
+---
+title: Team ownership
+summary: Which platform teams own the major Acme Inc domains and systems documented in the default catalog.
+owners:
+  - dboyne
+badges:
+  - content: Operations
+    backgroundColor: gray
+    textColor: gray
+---
+
+Ownership in the default catalog is modelled with team resources. The owning team is responsible for contract changes, service reliability and documentation freshness for its resources.
+
+## Teams by capability
+
+| Team | Owns |
+|------|------|
+| [[team\|product-platform]] | [[domain\|catalog]], [[system\|product-catalog-system]] and product APIs/workers. |
+| [[team\|search-platform]] | [[system\|search-system]], search indexing and search query contracts. |
+| [[team\|shopping-platform]] | [[domain\|shopping]], [[system\|cart-system]] and [[system\|promotion-system]]. |
+| [[team\|ordering-platform]] | [[domain\|ordering]], [[system\|checkout-system]] and [[system\|order-management-system]]. |
+| [[team\|payments-platform]] | [[domain\|payments]] and [[system\|payment-processing-system]]. |
+| [[team\|fulfilment-platform]] | [[domain\|fulfilment]], inventory, warehouse and shipping systems. |
+| [[team\|customer-platform]] | [[domain\|customer]], customer profile and identity systems. |
+| [[team\|reviews-platform]] | [[domain\|reviews]], review moderation and rating aggregation. |
+
+## Ownership rules
+
+The owner listed on the producing resource owns the contract. Consumers can request changes, but producers decide versioning and rollout.
+
+When a flow spans multiple teams, the team owning the orchestrator is responsible for keeping the flow page current. For checkout, that is [[team|ordering-platform]].
+
+## Documentation expectations
+
+Every resource page should explain responsibility, owners and major contracts. These custom docs should explain cross-resource narratives that do not belong to one resource.
diff --git a/examples/default/docs/operations/02-change-management.mdx b/examples/default/docs/operations/02-change-management.mdx
new file mode 100644
index 000000000..8fd032958
--- /dev/null
+++ b/examples/default/docs/operations/02-change-management.mdx
@@ -0,0 +1,36 @@
+---
+title: Change management
+summary: How to safely change contracts, schemas, systems and cross-domain flows in the Acme Inc catalog.
+owners:
+  - dboyne
+badges:
+  - content: Operations
+    backgroundColor: gray
+    textColor: gray
+---
+
+Changes should start with ownership and blast radius. A small service implementation change may not affect the catalog. A schema or flow change usually does.
+
+## Contract changes
+
+Before changing a command, event or query:
+
+1. Identify the producer and all consumers.
+2. Check whether the change is backward compatible.
+3. Update the schema and resource summary.
+4. Update affected flow pages.
+5. Coordinate rollout with consumer owners.
+
+High-risk contracts include [[event|cart-checked-out]], [[command|reserve-inventory]], [[command|authorize-payment]], [[command|create-order]], [[event|order-created]] and [[event|review-published]].
+
+## System changes
+
+When a system adds a service or data store, update the system page and any domain page that lists that system. If the change alters ownership of data, update the data ownership page too.
+
+## Flow changes
+
+For flows such as [[flow|place-an-order]], [[flow|checkout-saga]], [[flow|product-search-indexing]] and [[flow|review-submission]], update the diagram and the narrative together. A diagram without the operating rules is not enough for on-call or onboarding.
+
+## Decision records
+
+Use ADRs when a decision changes a long-lived pattern. The Product Catalog System already documents key decisions such as [[adr|adr-001-use-transactional-outbox]], [[adr|adr-002-postgres-as-system-of-record]] and [[adr|adr-003-offload-async-work-to-worker]].
diff --git a/examples/default/docs/operations/03-governance-model.mdx b/examples/default/docs/operations/03-governance-model.mdx
new file mode 100644
index 000000000..d057c399b
--- /dev/null
+++ b/examples/default/docs/operations/03-governance-model.mdx
@@ -0,0 +1,47 @@
+---
+title: Governance model
+summary: The operating model Acme teams use to keep domain ownership, catalog quality and cross-team decisions clear.
+owners:
+  - platform-governance
+badges:
+  - content: Standard
+    backgroundColor: gray
+    textColor: gray
+---
+
+Governance at Acme is lightweight but explicit. Teams own the catalog entries for their domains, systems, services, messages and flows, while the Platform Governance group maintains the standards that keep those entries consistent.
+
+## Ownership rules
+
+Every production resource must have:
+
+- a clear owning team,
+- a business capability or system boundary,
+- documented upstream and downstream dependencies,
+- a current version where the resource has versioned contracts,
+- enough context for another team to assess impact without asking in chat first.
+
+Domain teams own business meaning. Platform teams own shared tooling and catalog hygiene. Integration decisions are shared when a change crosses domain boundaries.
+
+## Governance forums
+
+| Forum | Cadence | Purpose |
+|-------|---------|---------|
+| Architecture review | Weekly | Review cross-domain changes, new systems and integration risks. |
+| Contract review | On demand | Review breaking command, query and event changes before implementation. |
+| Operations review | Weekly | Review incidents, SLO misses and catalog gaps found during support. |
+| Catalog health review | Monthly | Remove stale resources and improve ownership metadata. |
+
+## Decision records
+
+Use ADRs when the decision changes a system boundary, persistence model, integration pattern or team operating model. The Catalog domain shows the expected level of detail with [[adr|adr-001-use-transactional-outbox]], [[adr|adr-002-postgres-as-system-of-record]] and [[adr|adr-003-offload-async-work-to-worker]].
+
+<Prompt description="Find governance gaps" actions={["copy", "cursor"]} icon="sparkles">
+  Review this catalog area for governance gaps. Check for missing owners, unclear domain boundaries, undocumented
+  dependencies, stale decision records, unreviewed cross-domain contracts and missing operational notes. Return the gaps as
+  a prioritized checklist with suggested updates to EventCatalog pages.
+</Prompt>
+
+## Escalation path
+
+If two teams disagree on a contract or boundary, the owning domain proposes the default path, affected consuming teams document the impact, and the architecture review makes the final call.
diff --git a/examples/default/docs/operations/04-contract-standards.mdx b/examples/default/docs/operations/04-contract-standards.mdx
new file mode 100644
index 000000000..84e1e383d
--- /dev/null
+++ b/examples/default/docs/operations/04-contract-standards.mdx
@@ -0,0 +1,48 @@
+---
+title: Contract standards
+summary: The rules Acme teams follow when defining, versioning and changing commands, events and queries.
+owners:
+  - platform-governance
+badges:
+  - content: Standard
+    backgroundColor: orange
+    textColor: orange
+---
+
+Commands, events and queries are the public language between Acme systems. A contract is not ready until it is understandable by a team that does not own the implementation.
+
+## Contract types
+
+| Type | Meaning | Example |
+|------|---------|---------|
+| Command | A request for an owner to do work. | [[command\|reserve-inventory]], [[command\|authorize-payment]], [[command\|create-order]] |
+| Event | A fact that already happened. | [[event\|order-created]], [[event\|payment-succeeded]], [[event\|inventory-reserved]] |
+| Query | A read contract owned by one capability. | [[query\|get-order]], [[query\|search-products]], [[query\|get-product-reviews]] |
+
+## Required fields
+
+Every contract page should document:
+
+- business purpose,
+- producer or handler,
+- consumers where known,
+- schema or payload reference,
+- version and compatibility policy,
+- failure semantics for commands and queries,
+- replay and ordering assumptions for events.
+
+## Versioning rules
+
+Additive fields are allowed when consumers can ignore them. Removing fields, changing meaning, tightening validation or changing delivery semantics is breaking and requires a new version or a migration plan.
+
+Use deprecation before removal. Keep the old contract documented until all consumers have moved.
+
+## Review checklist
+
+Before changing a contract, teams must identify all known consumers, confirm whether the change is additive or breaking, update flow pages that depend on the contract, and add an ADR when the change introduces a new integration pattern.
+
+<Prompt description="Check contract compatibility" actions={["copy", "cursor"]} icon="file-warning">
+  Review a proposed command, event or query contract change for Acme Inc. Decide whether it is additive or breaking, list
+  known consumer risks, identify missing schema or payload details, and suggest a migration plan if the change is not
+  backward compatible. Include the catalog pages that need updates.
+</Prompt>
diff --git a/examples/default/docs/operations/05-event-design-standards.mdx b/examples/default/docs/operations/05-event-design-standards.mdx
new file mode 100644
index 000000000..a6232ddaa
--- /dev/null
+++ b/examples/default/docs/operations/05-event-design-standards.mdx
@@ -0,0 +1,47 @@
+---
+title: Event design standards
+summary: How Acme teams name, publish, consume and operate business events across the commerce platform.
+owners:
+  - platform-governance
+badges:
+  - content: Standard
+    backgroundColor: blue
+    textColor: blue
+---
+
+Events represent business facts, not instructions. The publishing team owns the meaning of the event and the state transition that produced it.
+
+## Naming
+
+Event names should be past tense and business-readable:
+
+- [[event|cart-checked-out]]
+- [[event|order-created]]
+- [[event|payment-succeeded]]
+- [[event|review-published]]
+
+Avoid names that describe infrastructure actions, implementation classes or subscriber intent.
+
+## Publishing
+
+Publish events from the system that owns the state change. For product changes, [[system|product-catalog-system]] publishes product events because [[container|product-database]] is authoritative. For order lifecycle changes, [[system|order-management-system]] publishes order events because [[container|order-database]] is authoritative.
+
+Use an outbox or equivalent durable handoff for events that represent committed business state.
+
+## Consumption
+
+Consumers must be idempotent. Delivery can be retried, delayed or observed out of order across independent streams. Consumers should store processed event identifiers when duplicate handling would otherwise create side effects.
+
+## Event payloads
+
+Payloads should carry enough information for consumers to decide whether they care, but not a full copy of another domain's private data model. Include stable identifiers, timestamps and business status fields. Keep sensitive customer and payment data out of broad event payloads.
+
+<Prompt description="Review an event design" actions={["copy", "cursor"]} icon="radio">
+  Review this event design against Acme's event standards. Check that the event name is a past-tense business fact, the
+  publisher owns the state change, the payload avoids private data models, consumers can process it idempotently, and the
+  related flow documentation is updated. Return specific recommendations.
+</Prompt>
+
+## Flow impact
+
+When an event is added to a critical journey, update the related flow page. Checkout-related event changes should be reflected in [[flow|place-an-order]] or [[flow|checkout-saga]].
diff --git a/examples/default/docs/operations/06-operational-readiness.mdx b/examples/default/docs/operations/06-operational-readiness.mdx
new file mode 100644
index 000000000..c246a290e
--- /dev/null
+++ b/examples/default/docs/operations/06-operational-readiness.mdx
@@ -0,0 +1,50 @@
+---
+title: Operational readiness
+summary: The launch and support standards Acme applies before a system or contract is considered production-ready.
+owners:
+  - platform-governance
+badges:
+  - content: Standard
+    backgroundColor: green
+    textColor: green
+---
+
+A system is production-ready when another team can understand ownership, dependencies and failure behavior from the catalog before an incident starts.
+
+## Required catalog coverage
+
+Before production launch, each system must document:
+
+- owning team and escalation path,
+- services and containers,
+- commands, queries and events,
+- critical flows that include the system,
+- external dependencies,
+- operational dashboards or runbooks where available,
+- known failure modes and recovery expectations.
+
+## Critical system map
+
+Checkout is the reference standard for operational coverage because it crosses Shopping, Ordering, Payments and Fulfilment.
+
+<NodeGraph id="checkout-system" version="1.0.0" type="system" maxHeight={34} mode="simple" />
+
+## Launch gates
+
+| Gate | Required evidence |
+|------|-------------------|
+| Ownership | Team and escalation path are present in the catalog. |
+| Contracts | Public commands, events and queries have schemas or payload notes. |
+| Observability | Error, latency and throughput signals exist for customer-facing paths. |
+| Recovery | Retry, compensation or manual recovery behavior is documented. |
+| Dependencies | Upstream and downstream systems are linked in the catalog. |
+
+<Prompt description="Run an operational readiness review" actions={["copy", "cursor"]} icon="radar">
+  Review this system for production readiness at Acme Inc. Check ownership, escalation, contracts, observability,
+  dependency mapping, failure modes, recovery behavior and customer impact. Return launch blockers, follow-up tasks and
+  catalog pages that should be updated before release.
+</Prompt>
+
+## Incident updates
+
+After an incident, update the catalog when the incident reveals a missing dependency, stale owner, unclear contract, undocumented failure mode or misleading flow.
diff --git a/examples/default/docs/operations/07-review-and-change-workflow.mdx b/examples/default/docs/operations/07-review-and-change-workflow.mdx
new file mode 100644
index 000000000..3c480af77
--- /dev/null
+++ b/examples/default/docs/operations/07-review-and-change-workflow.mdx
@@ -0,0 +1,56 @@
+---
+title: Review and change workflow
+summary: The standard workflow Acme teams use to make catalog-backed architecture and integration changes.
+owners:
+  - platform-governance
+badges:
+  - content: Standard
+    backgroundColor: purple
+    textColor: purple
+---
+
+Catalog updates should land with the system change they describe. The catalog is part of the delivery artifact, not an after-the-fact diagram store.
+
+## Change categories
+
+| Change | Required review |
+|--------|-----------------|
+| Local service implementation only | Owning team review. |
+| New command, event or query | Owning team plus known consumers. |
+| Breaking contract change | Contract review and migration plan. |
+| New system or external dependency | Architecture review. |
+| Critical flow behavior change | Owning teams for every domain in the flow. |
+
+## Standard workflow
+
+<Steps>
+  <Step title="Describe the intent">
+    Update the affected domain, system or flow page with the business reason for the change.
+  </Step>
+  <Step title="Update contracts">
+    Add or revise command, event and query pages before consumers integrate with them.
+  </Step>
+  <Step title="Assess impact">
+    Check system maps and flow pages for upstream and downstream dependencies.
+  </Step>
+  <Step title="Record decisions">
+    Add an ADR when the change affects ownership, persistence, integration style or operational recovery.
+  </Step>
+  <Step title="Close the loop">
+    After release, confirm the catalog matches the deployed behavior and remove stale notes.
+  </Step>
+</Steps>
+
+<Prompt description="Create a catalog-backed change checklist" actions={["copy", "cursor"]} icon="list-checks">
+  Create a review checklist for a proposed Acme architecture change. Include affected domains, systems, services,
+  commands, events, queries, flows, owners, operational risks, decision records and release follow-up. Keep the output
+  practical enough to paste into a pull request description.
+</Prompt>
+
+## Flow review
+
+For checkout changes, review both the customer journey and the internal saga before implementation.
+
+<Flow id="place-an-order" version="1.0.0" maxHeight={34} />
+
+<Flow id="checkout-saga" version="1.0.0" maxHeight={34} />
diff --git a/examples/default/docs/platform/01-architecture-overview.mdx b/examples/default/docs/platform/01-architecture-overview.mdx
new file mode 100644
index 000000000..4ce014361
--- /dev/null
+++ b/examples/default/docs/platform/01-architecture-overview.mdx
@@ -0,0 +1,50 @@
+---
+title: Architecture overview
+summary: How Acme Inc's commerce platform is organised across domains, systems, services, messages, data stores and teams.
+owners:
+  - dboyne
+badges:
+  - content: Overview
+    backgroundColor: blue
+    textColor: blue
+---
+
+Acme Inc runs a commerce platform that takes a customer from product discovery through cart, checkout, payment, fulfilment, delivery and post-purchase feedback. The catalog is organised around business capabilities rather than deployment topology.
+
+The main business domains are [[domain|catalog]], [[domain|shopping]], [[domain|ordering]], [[domain|payments]], [[domain|fulfilment]], [[domain|customer]] and [[domain|reviews]]. Each domain owns the services, messages and data stores that support its business language.
+
+## Core checkout map
+
+The checkout capability is the best compact view of how Acme's platform is connected. It shows the orchestration boundary between cart checkout, inventory reservation, payment authorization and durable order creation.
+
+<NodeGraph id="checkout-system" version="1.0.0" type="system" maxHeight={36} mode="simple" />
+
+## Platform shape
+
+| Area | Primary capability | Core systems |
+|------|--------------------|--------------|
+| [[domain\|catalog]] | Product data and search | [[system\|product-catalog-system]], [[system\|search-system]] |
+| [[domain\|shopping]] | Cart and promotions | [[system\|cart-system]], [[system\|promotion-system]] |
+| [[domain\|ordering]] | Checkout and order lifecycle | [[system\|checkout-system]], [[system\|order-management-system]] |
+| [[domain\|payments]] | Payment authorization, capture and refunds | [[system\|payment-processing-system]], [[system\|stripe]], [[system\|fraud-detection]] |
+| [[domain\|fulfilment]] | Stock, warehouse and shipment | [[system\|inventory-system]], [[system\|warehouse-system]], [[system\|shipping-system]], [[system\|carrier]] |
+| [[domain\|customer]] | Customer profile and authentication | [[system\|customer-management-system]], [[system\|identity-provider]] |
+| [[domain\|reviews]] | Product feedback and ratings | [[service\|review-api]], [[service\|review-moderation-worker]], [[service\|rating-aggregator]] |
+
+## Architectural style
+
+The platform is event-driven where state changes matter to another capability. Commands are used to request work from an owning capability, queries are used for explicit read access, and events announce facts that have already happened.
+
+The most important chain is the order journey:
+
+1. [[service|cart-api]] publishes [[event|cart-checked-out]].
+2. [[service|checkout-orchestrator]] coordinates [[command|reserve-inventory]], [[command|authorize-payment]] and [[command|create-order]].
+3. [[service|order-service]] publishes [[event|order-created]] and [[event|order-completed]].
+4. [[service|warehouse-service]] reacts to completed orders and publishes [[event|order-ready-for-shipping]].
+5. Shipment and carrier events track delivery progress.
+
+## Reading the catalog
+
+Use resource pages when you need the authoritative contract for a single component. Use these custom docs when you need the operating narrative: why a capability exists, how systems collaborate, and where ownership boundaries sit.
+
+Start with the domain pages when orienting around business capability. Start with flow pages when diagnosing an end-to-end customer journey.
diff --git a/examples/default/docs/platform/02-domain-map.mdx b/examples/default/docs/platform/02-domain-map.mdx
new file mode 100644
index 000000000..99fe1dabf
--- /dev/null
+++ b/examples/default/docs/platform/02-domain-map.mdx
@@ -0,0 +1,37 @@
+---
+title: Domain map
+summary: The bounded contexts in the Acme Inc catalog and how their responsibilities connect across the commerce journey.
+owners:
+  - dboyne
+badges:
+  - content: Architecture
+    backgroundColor: purple
+    textColor: purple
+---
+
+The domain map shows where business language changes. A cart, an order, a payment and a shipment are different concepts with different owners, lifecycles and consistency rules.
+
+## Core domains
+
+[[domain|shopping]], [[domain|ordering]], [[domain|payments]] and [[domain|fulfilment]] form the core purchase path. A failure in any of these domains can block revenue or customer delivery, so their contracts should be reviewed together when changing checkout behavior.
+
+| Domain | Owns | Publishes or handles |
+|--------|------|----------------------|
+| [[domain\|shopping]] | Cart contents, checkout intent and discounts | [[command\|checkout-cart]], [[event\|cart-checked-out]], [[command\|calculate-discount]] |
+| [[domain\|ordering]] | Checkout orchestration and order state | [[command\|reserve-inventory]], [[command\|authorize-payment]], [[command\|create-order]], [[event\|order-created]] |
+| [[domain\|payments]] | Payment intent, payment outcome and refunds | [[event\|payment-requested]], [[event\|payment-succeeded]], [[event\|payment-failed]], [[event\|refund-requested]] |
+| [[domain\|fulfilment]] | Stock reservation, warehouse packing and shipping | [[event\|inventory-reserved]], [[event\|order-ready-for-shipping]], [[command\|create-shipment]] |
+
+## Supporting domains
+
+[[domain|catalog]], [[domain|customer]] and [[domain|reviews]] support the buying experience. They are still product-critical, but their change cadence and runtime failure modes are different from checkout orchestration.
+
+Catalog and Search keep product data discoverable. Customer and Identity keep profiles and authentication separate from order state. Reviews and Ratings feed product trust signals back into the storefront.
+
+## Integration boundaries
+
+External systems are modelled explicitly so ownership and failure handling are visible. [[system|stripe]], [[system|fraud-detection]] and [[system|carrier]] are outside Acme's control. Internal services should treat these integrations as unreliable boundaries and persist enough state to retry safely.
+
+## Change guidance
+
+When a change crosses a domain boundary, update both sides of the contract. For example, changing checkout payloads requires reviewing [[event|cart-checked-out]], the [[flow|checkout-saga]], and any commands sent by [[service|checkout-orchestrator]].
diff --git a/examples/default/docs/platform/03-systems-map.mdx b/examples/default/docs/platform/03-systems-map.mdx
new file mode 100644
index 000000000..e5ebcf48e
--- /dev/null
+++ b/examples/default/docs/platform/03-systems-map.mdx
@@ -0,0 +1,51 @@
+---
+title: Systems map
+summary: The system-level view of Acme Inc's commerce platform and the responsibilities of each major system.
+owners:
+  - dboyne
+badges:
+  - content: Systems
+    backgroundColor: gray
+    textColor: gray
+---
+
+Systems group services and data stores around a stable business capability. They are the best unit for understanding runtime ownership, operational dashboards and integration boundaries.
+
+## Checkout and payment maps
+
+The checkout and payment systems are the highest-coupling parts of the platform. Use these maps when assessing checkout changes, payment incident impact or ownership questions across Ordering and Payments.
+
+<NodeGraph id="checkout-system" version="1.0.0" type="system" maxHeight={34} mode="simple" />
+
+<NodeGraph id="payment-processing-system" version="1.0.0" type="system" maxHeight={34} mode="simple" />
+
+## Internal systems
+
+| System | Domain | Role |
+|--------|--------|------|
+| [[system\|product-catalog-system]] | [[domain\|catalog]] | Source of truth for product data and product change events. |
+| [[system\|search-system]] | [[domain\|catalog]] | Maintains a search index and serves product search queries. |
+| [[system\|cart-system]] | [[domain\|shopping]] | Owns carts and emits checkout intent. |
+| [[system\|promotion-system]] | [[domain\|shopping]] | Calculates discounts for carts. |
+| [[system\|checkout-system]] | [[domain\|ordering]] | Coordinates checkout as a saga. |
+| [[system\|order-management-system]] | [[domain\|ordering]] | Owns order state and order lifecycle events. |
+| [[system\|payment-processing-system]] | [[domain\|payments]] | Records payment intent and drives payment/refund processing. |
+| [[system\|inventory-system]] | [[domain\|fulfilment]] | Owns stock and reservations. |
+| [[system\|warehouse-system]] | [[domain\|fulfilment]] | Picks and packs completed orders. |
+| [[system\|shipping-system]] | [[domain\|fulfilment]] | Creates shipments and tracks delivery handoff. |
+| [[system\|customer-management-system]] | [[domain\|customer]] | Owns customer profile data. |
+| [[system\|identity-provider]] | [[domain\|customer]] | Authenticates customers and manages user credentials. |
+
+## External systems
+
+The catalog also documents external dependencies:
+
+- [[system|stripe]] processes charges and refunds.
+- [[system|fraud-detection]] screens payments.
+- [[system|carrier]] creates and tracks shipments.
+
+## Why systems matter
+
+Services can change implementation technology, but system responsibilities should stay stable. For example, [[service|payment-api]] and [[service|payment-worker]] can evolve independently, but both remain inside [[system|payment-processing-system]] and share the same payment data ownership boundary.
+
+Use system pages for impact analysis when a change affects multiple services or a shared data store.
diff --git a/examples/default/docs/platform/04-data-ownership.mdx b/examples/default/docs/platform/04-data-ownership.mdx
new file mode 100644
index 000000000..aa3c42b87
--- /dev/null
+++ b/examples/default/docs/platform/04-data-ownership.mdx
@@ -0,0 +1,40 @@
+---
+title: Data ownership
+summary: The source-of-truth data stores in the default catalog and the rules for reading and writing business state.
+owners:
+  - dboyne
+badges:
+  - content: Data
+    backgroundColor: green
+    textColor: green
+---
+
+Every durable business concept has an owning system and a source-of-truth store. Other systems should depend on published contracts instead of reaching into another system's data store.
+
+## Source-of-truth stores
+
+| Data store | Owner | Business data |
+|------------|-------|---------------|
+| [[container\|product-database]] | [[system\|product-catalog-system]] | Products, product attributes and catalog change outbox. |
+| [[container\|search-index]] | [[system\|search-system]] | Search-optimised product documents. |
+| [[container\|cart-database]] | [[system\|cart-system]] | Active shopping carts and checkout state. |
+| [[container\|promotion-database]] | [[system\|promotion-system]] | Promotion rules and discount configuration. |
+| [[container\|order-database]] | [[system\|order-management-system]] | Orders and order lifecycle state. |
+| [[container\|payment-database]] | [[system\|payment-processing-system]] | Payment intents, charge outcomes and refunds. |
+| [[container\|inventory-database]] | [[system\|inventory-system]] | Stock levels and reservations. |
+| [[container\|warehouse-database]] | [[system\|warehouse-system]] | Picking and packing work. |
+| [[container\|customer-database]] | [[system\|customer-management-system]] | Customer profiles. |
+| [[container\|review-database]] | [[domain\|reviews]] | Reviews and moderation state. |
+| [[container\|rating-cache]] | [[domain\|reviews]] | Product rating read model. |
+
+## Read model pattern
+
+[[system|search-system]] and [[container|rating-cache]] are read models. They do not own the original facts. They rebuild their state from events such as [[event|product-created]], [[event|product-updated]], [[event|review-published]] and [[event|rating-updated]].
+
+## Write rule
+
+Only the owning system writes its source-of-truth store. Cross-system updates should be commands or events. For example, checkout asks fulfilment to reserve stock with [[command|reserve-inventory]] rather than writing [[container|inventory-database]] directly.
+
+## Consistency rule
+
+User-facing flows should make the consistency model explicit. Checkout needs coordinated confirmation across inventory, payment and order creation, so it uses the [[flow|checkout-saga]]. Search indexing can lag product writes, so it uses asynchronous product events.
diff --git a/examples/default/docs/platform/05-eventing-model.mdx b/examples/default/docs/platform/05-eventing-model.mdx
new file mode 100644
index 000000000..858dc3c79
--- /dev/null
+++ b/examples/default/docs/platform/05-eventing-model.mdx
@@ -0,0 +1,48 @@
+---
+title: Eventing model
+summary: How commands, events and queries are used across Acme Inc's event-driven commerce platform.
+owners:
+  - dboyne
+badges:
+  - content: Contracts
+    backgroundColor: orange
+    textColor: orange
+---
+
+The catalog separates messages by intent.
+
+- **Commands** ask another capability to do something.
+- **Events** announce that something has already happened.
+- **Queries** request information without changing state.
+
+## Commands
+
+Commands are named in the imperative and should have one clear handler. Examples:
+
+- [[command|checkout-cart]] asks [[service|cart-api]] to check out a cart.
+- [[command|reserve-inventory]] asks [[service|inventory-service]] to hold stock.
+- [[command|authorize-payment]] asks [[service|payment-api]] to authorize payment.
+- [[command|create-order]] asks [[service|order-service]] to create an order.
+- [[command|submit-review]] asks [[service|review-api]] to accept a product review.
+
+## Events
+
+Events are facts and should be safe for multiple consumers. Examples:
+
+- [[event|cart-checked-out]] starts the checkout process.
+- [[event|order-created]] signals that an order exists.
+- [[event|payment-succeeded]] and [[event|payment-failed]] report external processor outcomes.
+- [[event|order-ready-for-shipping]] hands fulfilment to shipping.
+- [[event|review-published]] updates review read models and product trust signals.
+
+## Queries
+
+Queries are explicit read contracts. Examples include [[query|get-product]], [[query|search-products]], [[query|get-order]], [[query|get-customer]], [[query|get-stock-level]] and [[query|get-product-reviews]].
+
+## Versioning expectations
+
+Backward-compatible additions are preferred. Removing fields or changing semantics requires a versioned contract and a migration plan. For customer-critical flows, review the flow page and all participating messages before changing a schema.
+
+## Failure expectations
+
+Consumers should be idempotent. Producers should publish facts after durable state changes. Long-running processes should persist their progress, especially [[flow|checkout-saga]], payment processing, search indexing and review moderation.
diff --git a/examples/default/docs/technical-architecture-design/architecture-decision-records/01-architecture-desicion-record.mdx b/examples/default/docs/technical-architecture-design/architecture-decision-records/01-architecture-desicion-record.mdx
deleted file mode 100644
index 5d2b3b6ec..000000000
--- a/examples/default/docs/technical-architecture-design/architecture-decision-records/01-architecture-desicion-record.mdx
+++ /dev/null
@@ -1,62 +0,0 @@
----
-title: Architecture Decision Records (ADR)
-summary: A document that captures important architectural decisions and their context
-sidebar:
-    label: ADR Template
-    order: 1
----
-
-
-
-## What is an Architecture Decision Record (ADR)?
-
-<Tiles columns={2}>
-    <Tile icon="CommandLineIcon" iconColor="black" href="/docs" title="Explore examples on GitHub" description="Delve into our documentation for more insights." />
-    <Tile icon="UsersIcon" iconColor="black" href="/docs" title="Request a review" description="Request a review from the team. Reviews for ADRs are from the design authority, and can take a week." />
-</Tiles>
-
-Architecture Decision Records (ADRs) are documents that capture important architectural decisions made during the development of a software system. Each ADR describes a choice the team has made, the context in which it was made, and the consequences of that choice.
-
-## Why ADRs are Important
-
-:::tip
-Use this template to create your own ADRs. Once you read this page you can submit new ADRs to the [Architecture Decision Records](https://github.com/eventcatalog/eventcatalog/issues/new?assignees=&labels=architecture&template=architecture-decision-record.mdx&title=ADR%3A+) repository.
-:::
-
-ADRs help teams:
-- Document decisions for future reference
-- Communicate architectural choices across the organization
-- Onboard new team members by providing insight into past decisions
-- Track the evolution of the system architecture over time
-- Establish a process for making and documenting significant technical decisions
-
-## ADR Format
-
-Our ADRs follow this structure:
-- **Title**: A descriptive name for the decision
-- **Status**: Current status (Proposed, Accepted, Superseded, etc.)
-- **Context**: The factors that influenced the decision
-- **Decision**: The choice that was made
-- **Consequences**: The resulting outcomes, both positive and negative
-- **Compliance Requirements**: Any regulatory or policy requirements that must be met
-- **Implementation Details**: How and when the decision will be implemented
-- **Alternatives**: Other options that were considered
-- **References**: Resources that support or provide more information
-- **Decision History**: The record of changes to the ADR
-
-```mermaid
-flowchart TD
-    A[Identify Architectural Decision Point] --> B[Discuss Options]
-    B --> C[Draft ADR]
-    C --> D[Review with Stakeholders]
-    D --> E{Approved?}
-    E -->|Yes| F[Update Status to Approved]
-    E -->|No| G[Revise ADR]
-    G --> D
-    F --> H[Implement Decision]
-    H --> I[Monitor & Evaluate]
-    I --> J{Changes Needed?}
-    J -->|Yes| K[Create New or Update ADR]
-    K --> B
-    J -->|No| L[Document Learnings]
-```
diff --git a/examples/default/docs/technical-architecture-design/architecture-decision-records/drafts/01-cloud-infrastructure-strategy.mdx b/examples/default/docs/technical-architecture-design/architecture-decision-records/drafts/01-cloud-infrastructure-strategy.mdx
deleted file mode 100644
index 264533d6a..000000000
--- a/examples/default/docs/technical-architecture-design/architecture-decision-records/drafts/01-cloud-infrastructure-strategy.mdx
+++ /dev/null
@@ -1,441 +0,0 @@
----
-title: Cloud Infrastructure Strategy
-summary: Architectural decision record for cloud infrastructure approach for the FlowMart e-commerce platform
-sidebar:
-    label: Cloud Infrastructure Strategy
-    order: 1
----
-
-# DRAFT - NOT YET APPROVED
-
-:::warning
-This is a draft ADR. It is not yet approved and should not be used as a reference.
-:::
-
-## ADR-007: Cloud Infrastructure Strategy for FlowMart E-commerce Platform
-
-### Status
-
-Draft (Last Updated: 2024-09-25)
-
-<Flow id="PaymentFlow" version="latest" includeKey={false} />
-<Flow id="PaymentFlow" version="latest" includeKey={false} />
-<Flow id="PaymentFlow" version="latest" includeKey={false} />
-
-### Context
-
-As part of our transition to a microservices architecture, we need to define our cloud infrastructure strategy to support the new FlowMart e-commerce platform. Our current infrastructure consists primarily of on-premises data centers with some workloads in AWS, creating operational and scaling challenges:
-
-1. **Infrastructure Provisioning**: Manual processes for provisioning infrastructure lead to long lead times for new environments and services.
-
-2. **Scaling Limitations**: Physical hardware constraints prevent rapid scaling during peak shopping periods.
-
-3. **High Operational Overhead**: Significant effort required for hardware maintenance, patching, and capacity management.
-
-4. **Disaster Recovery Challenges**: Limited geographic redundancy and complex DR procedures.
-
-5. **Cloud Fragmentation**: Ad-hoc adoption of cloud services has created inconsistent practices and tooling.
-
-6. **Developer Experience**: Complex local development setup and environment inconsistencies slow down development cycles.
-
-7. **Cost Management**: Difficult to attribute infrastructure costs to specific business capabilities or teams.
-
-8. **Security Compliance**: Maintaining compliance across hybrid infrastructure requires duplicate controls and auditing.
-
-We need a cohesive infrastructure strategy that enables rapid delivery, scalability, and operational efficiency for our new e-commerce platform.
-
-### Decision
-
-We will adopt a **cloud-native infrastructure strategy** with a **multi-cloud capability** but **AWS-primary approach**. Key aspects of this strategy include:
-
-1. **Primary Cloud Platform**:
-   - AWS will be our primary cloud provider for all new workloads
-   - Azure will be maintained as a secondary provider for specific use cases (e.g., Microsoft-ecosystem services)
-   - GCP may be selectively used for specialized AI/ML workloads
-
-2. **Infrastructure as Code (IaC)**:
-   - Terraform as primary IaC tool for provisioning cloud resources
-   - AWS CDK for complex, AWS-specific resource configurations
-   - GitOps-based deployment workflows with infrastructure CI/CD pipelines
-
-3. **Containerization Strategy**:
-   - Containerize all new microservices using Docker
-   - Amazon EKS (Kubernetes) as primary container orchestration platform
-   - Amazon ECR for container registry with cross-region replication
-
-4. **Platform Services Over Custom Infrastructure**:
-   - Prefer managed services over self-managed infrastructure where possible
-   - AWS RDS, DocumentDB, ElastiCache for database needs
-   - AWS MSK (Managed Kafka) for event streaming
-   - CloudFront for CDN and edge caching
-
-5. **Multi-Region Architecture**:
-   - Primary operations in AWS US-East-1 and US-West-2
-   - Active-active configuration for critical services
-   - Region-specific deployments for EU and APAC markets to address data residency
-
-6. **Landing Zone and Account Structure**:
-   - Hub-and-spoke model with centralized security and governance
-   - Separate AWS accounts for production, staging, development, and sandbox environments
-   - Service-oriented account structure within each environment category
-   - Centralized logging, monitoring, and security controls
-
-7. **Network Architecture**:
-   - Transit Gateway for interconnecting VPCs and on-premises
-   - VPC design aligned with microservice domains
-   - AWS PrivateLink for service-to-service connectivity
-   - AWS Shield and WAF for DDoS protection and application security
-
-8. **Cost Optimization**:
-   - Tagging strategy for cost allocation and tracking
-   - Automated cost monitoring and anomaly detection
-   - Leverage Savings Plans and Reserved Instances strategically
-   - Implemented auto-scaling for elastic workloads
-
-### Infrastructure Architecture by Domain
-
-| Domain | Primary Services | Scaling Strategy | Special Requirements |
-|--------|------------------|------------------|----------------------|
-| Product Catalog | EKS, ElastiCache, DocumentDB | Horizontal pod scaling, Read replicas | High read throughput, Global availability |
-| Order Processing | EKS, RDS (PostgreSQL), MSK | Horizontal pod scaling, DB connection pooling | Strong consistency, Transaction support |
-| Payment | EKS, RDS (PostgreSQL), KMS | Fixed scaling with headroom | PCI-DSS compliance, Encryption requirements |
-| Inventory | EKS, DocumentDB, Lambda | Horizontal auto-scaling | Event-sourcing patterns, Eventual consistency |
-| User Authentication | Cognito, Lambda, DynamoDB | Regional deployments | Multi-factor auth, Token management |
-| Content Delivery | S3, CloudFront, Lambda@Edge | Edge caching, Regional replication | Image optimization, Low latency delivery |
-| Search | OpenSearch, Lambda, EKS | Search domain scaling, Query throttling | High cardinality, Complex query support |
-| Analytics | Redshift, Kinesis, EMR | Workload-based scaling | Batch processing, Data lake integration |
-
-### Consequences
-
-#### Positive
-
-1. **Improved Scalability**: Elastic infrastructure that scales with demand without manual intervention.
-
-2. **Faster Time-to-Market**: Automated provisioning and deployment enable rapid delivery of new features.
-
-3. **Enhanced Resilience**: Multi-region architecture improves availability and disaster recovery capabilities.
-
-4. **Cost Efficiency**: Pay-for-use model and automated scaling optimize infrastructure costs.
-
-5. **Developer Productivity**: Consistent environments and self-service capabilities improve developer experience.
-
-6. **Security Improvements**: Standardized security controls and automated compliance checks.
-
-7. **Operational Efficiency**: Reduced operational overhead through managed services and automation.
-
-8. **Global Reach**: Ability to deploy services closer to customers in different geographic regions.
-
-#### Negative
-
-1. **Cloud Vendor Dependency**: While designed for multi-cloud, primary workloads will have AWS dependencies.
-
-2. **Cost Management Complexity**: Cloud costs can escalate without proper governance and monitoring.
-
-3. **Skill Set Transition**: Team needs to develop new skills in cloud-native technologies and practices.
-
-4. **Increased Architectural Complexity**: Distributed cloud architecture is more complex to design and troubleshoot.
-
-5. **Security Model Changes**: Cloud security requires different approaches and tools than on-premises.
-
-6. **Data Transfer Costs**: Cross-region and internet data transfer can become a significant cost factor.
-
-7. **Service Maturity Variations**: Some AWS services are more mature and reliable than others.
-
-### Mitigation Strategies
-
-1. **Cloud Platform Team**:
-   - Create a dedicated platform engineering team for cloud infrastructure
-   - Develop reusable infrastructure modules and patterns
-   - Provide internal consultation and support to service teams
-
-2. **Cloud Center of Excellence (CCoE)**:
-   - Establish cloud best practices and governance
-   - Regular architecture reviews and guidance
-   - Develop certification and training program for engineering teams
-
-3. **Cloud Financial Management**:
-   - Implement FinOps practices and tooling
-   - Regular cost reviews and optimization cycles
-   - Showback/chargeback mechanisms to drive accountability
-
-4. **Abstraction Layers**:
-   - Create service abstractions to minimize direct cloud provider coupling
-   - Develop infrastructure interfaces that could support multiple providers
-   - Use cloud-agnostic tools and practices where practical
-
-5. **Hybrid Transition Strategy**:
-   - Phased migration from on-premises to cloud
-   - Maintain hybrid capabilities during transition period
-   - Clear exit criteria for legacy infrastructure decommissioning
-
-### Implementation Details
-
-#### Phase 1: Foundation (Q4 2024)
-
-1. Establish AWS Landing Zone and account structure
-2. Implement core networking and security controls
-3. Set up CI/CD pipelines for infrastructure
-4. Deploy EKS clusters for development and staging
-5. Migrate first non-critical workloads
-
-#### Phase 2: Production Migration (Q1-Q2 2025)
-
-1. Deploy production EKS clusters and platform services
-2. Migrate core services to cloud infrastructure
-3. Implement multi-region capabilities for critical services
-4. Establish cloud cost management and optimization
-5. Complete developer tooling and self-service capabilities
-
-#### Phase 3: Advanced Capabilities (Q3-Q4 2025)
-
-1. Implement advanced security and compliance controls
-2. Deploy cross-region data synchronization
-3. Optimize for global performance and availability
-4. Enhance disaster recovery capabilities
-5. Begin decommissioning legacy infrastructure
-
-### Considered Alternatives
-
-#### 1. Maintain and Expand On-Premises Infrastructure
-
-**Pros**: Full control, potentially lower ongoing costs for stable workloads, no data sovereignty concerns  
-**Cons**: Limited agility, high capital expenditure, scaling limitations, operational overhead
-
-This approach would not provide the agility and scalability needed for our strategic growth and would perpetuate our current limitations.
-
-#### 2. Single Cloud Provider (AWS Only)
-
-**Pros**: Simplified operations, deeper integration between services, volume discounts, focused expertise  
-**Cons**: Vendor lock-in, limited negotiating leverage, regional provider limitations
-
-While simpler operationally, this approach would increase our dependency on a single provider and limit flexibility.
-
-#### 3. Multi-Cloud with Equal Workload Distribution
-
-**Pros**: Maximize negotiating leverage, no single provider dependency, best-of-breed services  
-**Cons**: Significantly increased complexity, higher operations costs, fragmented expertise, integration challenges
-
-The operational complexity and cost of maintaining equal capabilities across multiple cloud providers outweighs the benefits for our current needs.
-
-#### 4. Cloud Service Provider (CSP) Abstraction Layer
-
-**Pros**: Provider independence, standardized interfaces, easier migration between providers  
-**Cons**: Significant development overhead, lowest common denominator functionality, performance impacts
-
-Building comprehensive abstractions across cloud providers would create substantial engineering overhead and limit access to valuable provider-specific capabilities.
-
-### References
-
-1. AWS Well-Architected Framework ([AWS Documentation](https://aws.amazon.com/architecture/well-architected/))
-2. "Cloud Strategy Leadership" (Gartner)
-3. "Architecting for the Cloud: AWS Best Practices" ([AWS Whitepaper](https://d1.awsstatic.com/whitepapers/AWS_Cloud_Best_Practices.pdf))
-4. "Multi-cloud: The good, the bad and the ugly" (ThoughtWorks Technology Radar)
-5. Terraform Documentation ([Terraform.io](https://www.terraform.io/docs/))
-6. "Cloud Native Infrastructure" by Justin Garrison and Kris Nova
-
-### Decision Record History
-
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2024-09-10 | 0.1 | Initial draft | Marcus Johnson |
-| 2024-09-18 | 0.2 | Added implementation phases and domain details | Patricia Lopez |
-| 2024-09-25 | 0.3 | Incorporated feedback from architecture review | David Boyne |
-| TBD | 1.0 | Pending approval | Architecture Board |
-
-## Appendix A: Cloud Infrastructure Architecture
-
-```mermaid
-flowchart TB
-    subgraph "AWS Global"
-        subgraph "AWS Organizations"
-            org[Management Account]
-            security[Security Account]
-            shared[Shared Services Account]
-            log[Logging Account]
-            net[Network Account]
-            
-            subgraph "Production"
-                prod1[Product Domain]
-                prod2[Order Domain]
-                prod3[Customer Domain]
-                prod4[Payment Domain]
-            end
-            
-            subgraph "Non-Production"
-                dev[Development]
-                stage[Staging]
-                test[Testing]
-                sandbox[Sandbox]
-            end
-        end
-    end
-    
-    subgraph "On-Premises"
-        dc[Data Center]
-        legacy[Legacy Systems]
-    end
-    
-    subgraph "Network Fabric"
-        dx[Direct Connect]
-        tgw[Transit Gateway]
-        vpn[VPN]
-        cf[CloudFront]
-    end
-    
-    org --> security
-    org --> shared
-    org --> log
-    org --> net
-    org --> prod1
-    org --> prod2
-    org --> prod3
-    org --> prod4
-    org --> dev
-    org --> stage
-    org --> test
-    org --> sandbox
-    
-    dc --> dx
-    dc --> vpn
-    legacy --> dx
-    
-    dx --> tgw
-    vpn --> tgw
-    
-    tgw --> net
-    net --> prod1
-    net --> prod2
-    net --> prod3
-    net --> prod4
-    net --> dev
-    net --> stage
-    
-    cf --> prod1
-    cf --> prod2
-    cf --> prod3
-    cf --> prod4
-```
-
-## Appendix B: Deployment Architecture
-
-```mermaid
-flowchart LR
-    subgraph "Developer Experience"
-        ide[IDE Plugins]
-        cli[CLI Tools]
-        local[Local Dev Environment]
-    end
-    
-    subgraph "CI/CD Pipeline"
-        git[Git Repository]
-        build[Build System]
-        test[Automated Tests]
-        scan[Security Scans]
-        artifact[Artifact Repository]
-    end
-    
-    subgraph "GitOps Deployment"
-        config[Config Repository]
-        argocd[ArgoCD]
-        flux[Flux]
-    end
-    
-    subgraph "AWS EKS Clusters"
-        subgraph "Development"
-            devNS1[Team 1 Namespace]
-            devNS2[Team 2 Namespace]
-        end
-        
-        subgraph "Staging"
-            stageNS1[Team 1 Namespace]
-            stageNS2[Team 2 Namespace]
-        end
-        
-        subgraph "Production"
-            prodNS1[Team 1 Namespace]
-            prodNS2[Team 2 Namespace]
-        end
-    end
-    
-    ide --> git
-    cli --> git
-    local --> git
-    
-    git --> build
-    build --> test
-    test --> scan
-    scan --> artifact
-    
-    artifact --> config
-    config --> argocd
-    config --> flux
-    
-    argocd --> devNS1
-    argocd --> devNS2
-    argocd --> stageNS1
-    argocd --> stageNS2
-    argocd --> prodNS1
-    argocd --> prodNS2
-    
-    flux --> devNS1
-    flux --> devNS2
-    flux --> stageNS1
-    flux --> stageNS2
-    flux --> prodNS1
-    flux --> prodNS2
-```
-
-## Appendix C: AWS Account Structure
-
-```mermaid
-flowchart TB
-    subgraph "Management & Governance"
-        mgmt[Management Account]
-        style mgmt fill:#f9f,stroke:#333,stroke-width:2px
-        
-        security[Security Account]
-        audit[Audit Account]
-        shared[Shared Services]
-        network[Network Account]
-        
-        mgmt --> security
-        mgmt --> audit
-        mgmt --> shared
-        mgmt --> network
-    end
-    
-    subgraph "Production OU"
-        prodOU[Production]
-        
-        payment[Payment Services]
-        order[Order Services]
-        product[Product Catalog]
-        identity[Identity Services]
-        content[Content Services]
-        analytics[Analytics]
-        
-        prodOU --> payment
-        prodOU --> order
-        prodOU --> product
-        prodOU --> identity
-        prodOU --> content
-        prodOU --> analytics
-    end
-    
-    subgraph "Non-Production OU"
-        nonProdOU[Non-Production]
-        
-        dev[Development]
-        stage[Staging]
-        test[Testing]
-        sandbox[Sandbox]
-        
-        nonProdOU --> dev
-        nonProdOU --> stage
-        nonProdOU --> test
-        nonProdOU --> sandbox
-    end
-    
-    mgmt --> prodOU
-    mgmt --> nonProdOU
-``` 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/architecture-decision-records/drafts/02-cicd-deployment-strategy.mdx b/examples/default/docs/technical-architecture-design/architecture-decision-records/drafts/02-cicd-deployment-strategy.mdx
deleted file mode 100644
index a3a1a283d..000000000
--- a/examples/default/docs/technical-architecture-design/architecture-decision-records/drafts/02-cicd-deployment-strategy.mdx
+++ /dev/null
@@ -1,471 +0,0 @@
----
-title: CI/CD and Deployment Strategy
-summary: Architectural decision record for continuous integration, delivery and deployment approach for the FlowMart e-commerce platform
-sidebar:
-    label: CI/CD Strategy
-    order: 2
----
-
-# DRAFT - NOT YET APPROVED
-
-:::warning
-This is a draft ADR. It is not yet approved and should not be used as a reference.
-:::
-
-## ADR-008: CI/CD and Deployment Strategy for FlowMart E-commerce Platform
-
-### Status
-
-Draft (Last Updated: 2024-10-05)
-
-### Context
-
-As we transition to a microservices architecture with dozens of independently deployable services, our current deployment approach presents several challenges:
-
-1. **Manual Deployment Processes**: Deployments are largely manual, requiring significant coordination and causing deployment anxiety.
-
-2. **Environment Inconsistency**: Configuration differences between environments lead to environment-specific bugs and "works on my machine" issues.
-
-3. **Long Lead Times**: The process from code commit to production deployment takes days or weeks due to manual testing and approval gates.
-
-4. **Deployment Coupling**: Services must be deployed together in coordinated releases, slowing down the delivery of all features.
-
-5. **Limited Testing Automation**: Insufficient automated testing leads to quality issues discovered late in the delivery process.
-
-6. **Configuration Management**: Configuration is managed inconsistently across environments and services.
-
-7. **Deployment Visibility**: Limited visibility into deployment status, history, and metrics.
-
-8. **Rollback Challenges**: Rolling back problematic deployments is difficult and error-prone.
-
-Our current approach does not support the rapid, independent delivery of microservices that is essential for our new architecture. We need a comprehensive CI/CD and deployment strategy that enables teams to deliver high-quality services with velocity and confidence.
-
-### Decision
-
-We will implement a **GitOps-based CI/CD and deployment strategy** with **continuous deployment to production** for our microservices architecture. Key aspects of this strategy include:
-
-1. **Trunk-Based Development Model**:
-   - Short-lived feature branches merged frequently to main/trunk
-   - Feature toggles for in-progress work
-   - Automated code quality checks and linting on pull requests
-   - Main branch always deployable
-
-2. **Continuous Integration Pipeline**:
-   - Automated builds triggered on every commit
-   - Comprehensive automated testing suite
-   - Security scanning (SAST, SCA, secrets scanning)
-   - Container image building and signing
-   - Test environments provisioned on demand for PR validation
-
-3. **GitOps Deployment Approach**:
-   - Declarative infrastructure and application configuration in Git
-   - ArgoCD as primary GitOps operator
-   - Environment-specific configuration via Kustomize overlays
-   - Git as single source of truth for deployed state
-   - Automatic drift detection and remediation
-
-4. **Deployment Progression Strategy**:
-   - Automated deployments through dev and test environments
-   - Production deployments with optional approval (human in the loop)
-   - Environment promotion rather than rebuilding artifacts
-   - Canary deployments for high-risk services
-   - Blue/green deployments for critical components
-
-5. **Configuration Management**:
-   - Externalized configuration in Git repositories
-   - Kubernetes ConfigMaps and Secrets for application configuration
-   - Sealed Secrets for sensitive information
-   - HashiCorp Vault for secrets rotation and dynamic credentials
-   - Environment-specific configuration via layered overlays
-
-6. **Deployment Safety Mechanisms**:
-   - Progressive delivery with canary deployments
-   - Automated pre-deployment validation
-   - Automated post-deployment testing
-   - Automated rollback on failure
-   - Circuit breakers for dependent services
-
-7. **Release Coordination**:
-   - API versioning and backwards compatibility requirements
-   - Service-level dependency management
-   - Deployment sequencing for interdependent services
-   - Deployment windows for critical services
-
-8. **Deployment Metrics and Observability**:
-   - Deployment frequency tracking
-   - Change lead time measurement
-   - Mean time to recovery monitoring
-   - Change failure rate tracking
-   - Deployment health dashboards
-
-### Technology Stack
-
-| Component | Primary Technology | Alternative/Backup | Purpose |
-|-----------|-------------------|-------------------|---------|
-| Source Control | GitHub | GitLab | Version control and collaboration |
-| CI Pipeline | GitHub Actions | Jenkins | Build, test, and validation |
-| Artifact Registry | AWS ECR | GitHub Packages | Container image storage |
-| GitOps Operator | ArgoCD | Flux | Kubernetes-based deployment automation |
-| Secrets Management | Sealed Secrets + Vault | AWS Secrets Manager | Secure configuration management |
-| Deployment Orchestration | ArgoCD + Argo Rollouts | Spinnaker | Controlled deployment progression |
-| Feature Flags | LaunchDarkly | Flagsmith | Runtime feature enablement/disablement |
-| Testing Framework | Jest, Cypress, k6 | Various | Automated testing across layers |
-| Deployment Monitoring | Prometheus + Grafana | Datadog | Deployment metrics and alerting |
-
-### Consequences
-
-#### Positive
-
-1. **Accelerated Delivery**: Reduced lead time from commit to production deployment.
-
-2. **Improved Quality**: Comprehensive automated testing and validation.
-
-3. **Increased Deployment Frequency**: Teams can deploy independently at their own pace.
-
-4. **Enhanced Reliability**: Consistent, repeatable deployment processes with automated rollbacks.
-
-5. **Better Visibility**: Clear audit trail and status of all deployments.
-
-6. **Reduced Coordination Overhead**: Less need for cross-team deployment coordination.
-
-7. **Improved Developer Experience**: Self-service deployments with rapid feedback.
-
-8. **Environment Consistency**: Reproducible environments with minimal drift.
-
-#### Negative
-
-1. **Learning Curve**: Teams need to adapt to new tools and processes.
-
-2. **Initial Setup Complexity**: Significant effort to establish the complete CI/CD pipeline.
-
-3. **Infrastructure Requirements**: Additional infrastructure to support the CI/CD toolchain.
-
-4. **Potential Deployment Sprawl**: Multiple services deploying independently can create coordination challenges.
-
-5. **Testing Complexity**: Comprehensive testing across distributed services is challenging.
-
-6. **Feature Flag Management**: Complexity of managing feature flags across services.
-
-7. **Observability Requirements**: Need for sophisticated monitoring to detect deployment issues.
-
-### Mitigation Strategies
-
-1. **Platform Team Support**:
-   - Create a dedicated platform engineering team focused on CI/CD
-   - Provide standardized pipeline templates and documentation
-   - Enable self-service capabilities with guardrails
-
-2. **Phased Implementation**:
-   - Start with less critical services
-   - Gradually increase automation and reduce manual gates
-   - Measure and demonstrate improved outcomes
-
-3. **Developer Enablement**:
-   - Comprehensive documentation and examples
-   - Regular training sessions and office hours
-   - Inner-source model for pipeline improvements
-
-4. **Testing Strategy**:
-   - Standard test libraries and frameworks
-   - Service virtualization for dependencies
-   - Comprehensive end-to-end testing strategy
-
-5. **Change Management**:
-   - Clear communication about process changes
-   - Regular retrospectives and continuous improvement
-   - Celebrate success stories and share lessons learned
-
-### Implementation Details
-
-#### Phase 1: Foundation (Q4 2024)
-
-1. Establish CI pipeline standardization
-2. Implement container build and security scanning
-3. Set up artifact repositories and image signing
-4. Deploy ArgoCD and initial GitOps workflows
-5. Implement trunk-based development practices
-
-#### Phase 2: Advanced Delivery (Q1 2025)
-
-1. Enable canary and blue/green deployments
-2. Implement comprehensive automated testing
-3. Set up feature flag management
-4. Deploy secrets management solution
-5. Create deployment metrics dashboards
-
-#### Phase 3: Continuous Deployment (Q2 2025)
-
-1. Implement continuous deployment to production
-2. Enable automated rollbacks and circuit breakers
-3. Set up deployment SLOs and monitoring
-4. Implement sophisticated deployment strategies
-5. Optimize deployment performance and efficiency
-
-### Deployment Process Flow
-
-The following outlines our target deployment process flow from code commit to production:
-
-1. **Code Commit & PR**:
-   - Developer creates branch and commits changes
-   - Pull request created with automated linting and checks
-   - CI pipeline validates build, tests, and security
-
-2. **CI Verification**:
-   - Automated unit and integration tests
-   - Security scanning (SAST, SCA, container scanning)
-   - Code quality metrics and coverage checks
-   - On-demand test environment provisioning
-
-3. **Artifact Creation**:
-   - Container images built and tagged
-   - Images signed and pushed to registry
-   - Deployment manifests generated
-   - Configuration updates prepared
-
-4. **Development Deployment**:
-   - Automatic deployment to development environment
-   - Post-deployment testing and validation
-   - Integration testing with other services
-   - Performance and security validation
-
-5. **Staging Deployment**:
-   - Promotion of verified artifacts to staging
-   - Environment-specific configuration applied
-   - System-level testing and validation
-   - Performance testing against production-like load
-
-6. **Production Deployment**:
-   - Optional approval gate for high-risk services
-   - Canary or blue/green deployment strategy
-   - Incremental traffic shifting
-   - Health check verification at each step
-
-7. **Post-Deployment Validation**:
-   - Automated smoke tests
-   - Synthetic transaction monitoring
-   - Key metric monitoring and alerting
-   - Automated rollback if metrics deviate
-
-### Considered Alternatives
-
-#### 1. Traditional Release-Based Deployment Model
-
-**Pros**: Familiar approach, coordinated releases, comprehensive testing cycles  
-**Cons**: Slow delivery, limited independence, large batch sizes increasing risk
-
-This approach would not provide the delivery velocity required for our business needs and would limit the benefits of our microservices architecture.
-
-#### 2. Pure Environment Promotion Model
-
-**Pros**: Artifact consistency, simplified promotion process, reduced build time  
-**Cons**: Limited environment-specific customization, potential configuration complexity
-
-While we adopt aspects of this approach, we need the flexibility of environment-specific configuration that a pure promotion model limits.
-
-#### 3. Central Deployment Team
-
-**Pros**: Standardized processes, specialized expertise, controlled deployments  
-**Cons**: Potential bottleneck, reduced team autonomy, slower feedback loops
-
-This approach would create a deployment bottleneck and reduce the ownership and autonomy of our product teams.
-
-#### 4. Fully Automated No-Approval Deployments
-
-**Pros**: Maximum velocity, reduced human intervention, forced quality automation  
-**Cons**: Increased risk for critical systems, cultural resistance, advanced testing requirements
-
-While this is our long-term goal, we need to balance velocity with appropriate controls, especially for critical payment and order processing systems.
-
-### References
-
-1. Forsgren, N., Humble, J., & Kim, G. "Accelerate: The Science of Lean Software and DevOps" (IT Revolution Press)
-2. Humble, J. & Farley, D. "Continuous Delivery" (Addison-Wesley)
-3. [GitOps Working Group](https://github.com/gitops-working-group/gitops-working-group)
-4. [Argo CD Documentation](https://argo-cd.readthedocs.io/)
-5. [Kubernetes Deployment Strategies](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy)
-6. [Trunk Based Development](https://trunkbaseddevelopment.com/)
-
-### Decision Record History
-
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2024-09-28 | 0.1 | Initial draft | Jason Miller |
-| 2024-10-03 | 0.2 | Added implementation phases and deployment flow | Thomas Wong |
-| 2024-10-05 | 0.3 | Incorporated feedback from DevOps and development teams | David Boyne |
-| TBD | 1.0 | Pending approval | Architecture Board |
-
-## Appendix A: CI/CD Pipeline Architecture
-
-```mermaid
-flowchart TB
-    subgraph "Developer Workflow"
-        dev[Developer]
-        ide[IDE]
-        local[Local Testing]
-        
-        dev --> ide
-        ide --> local
-    end
-    
-    subgraph "Source Control"
-        branch[Feature Branch]
-        pr[Pull Request]
-        trunk[Main Branch]
-        
-        local --> branch
-        branch --> pr
-        pr --> trunk
-    end
-    
-    subgraph "Continuous Integration"
-        build[Build & Test]
-        security[Security Scan]
-        quality[Quality Gates]
-        artifact[Create Artifacts]
-        
-        trunk --> build
-        build --> security
-        security --> quality
-        quality --> artifact
-    end
-    
-    subgraph "Artifact Management"
-        registry[Container Registry]
-        config[Config Repository]
-        
-        artifact --> registry
-        artifact --> config
-    end
-    
-    subgraph "GitOps Deployment"
-        argo[ArgoCD]
-        dev_env[Development]
-        stage_env[Staging]
-        prod_env[Production]
-        
-        config --> argo
-        argo --> dev_env
-        argo --> stage_env
-        argo --> prod_env
-    end
-    
-    subgraph "Deployment Strategies"
-        canary[Canary]
-        blue_green[Blue/Green]
-        
-        prod_env --> canary
-        prod_env --> blue_green
-    end
-    
-    subgraph "Observability"
-        metrics[Deployment Metrics]
-        alerts[Deployment Alerts]
-        dash[Deployment Dashboard]
-        
-        canary --> metrics
-        blue_green --> metrics
-        metrics --> alerts
-        metrics --> dash
-    end
-```
-
-## Appendix B: Deployment Pipeline Flow
-
-```mermaid
-sequenceDiagram
-    participant Dev as Developer
-    participant Git as GitHub
-    participant CI as CI Pipeline
-    participant Reg as Container Registry
-    participant Config as Config Repository
-    participant ArgoCD as ArgoCD
-    participant Env as Environments
-    participant Monitor as Monitoring
-    
-    Dev->>Git: Commit Code
-    Git->>CI: Trigger Pipeline
-    
-    CI->>CI: Build & Test
-    CI->>CI: Security Scan
-    CI->>CI: Quality Gates
-    
-    CI->>Reg: Push Image
-    CI->>Config: Update Manifests
-    
-    Config->>ArgoCD: Detected Changes
-    ArgoCD->>Env: Deploy to Dev
-    
-    ArgoCD->>Env: Post-Deployment Tests
-    Env->>Monitor: Collect Metrics
-    
-    alt Tests Pass
-        ArgoCD->>Env: Deploy to Staging
-        Env->>Monitor: Collect Metrics
-        
-        alt Staging Healthy
-            ArgoCD->>Env: Deploy Canary to Production
-            Env->>Monitor: Collect Metrics
-            
-            alt Canary Healthy
-                ArgoCD->>Env: Complete Production Rollout
-            else Canary Unhealthy
-                ArgoCD->>Env: Rollback Canary
-            end
-        else Staging Unhealthy
-            ArgoCD->>Env: Rollback Staging
-        end
-    else Tests Fail
-        ArgoCD->>Env: Rollback Dev
-    end
-    
-    Monitor->>Dev: Deployment Status & Metrics
-```
-
-## Appendix C: Environment Configuration Strategy
-
-```mermaid
-flowchart LR
-    subgraph "Git Repositories"
-        app[Application Code]
-        infra[Infrastructure Code]
-        config[Configuration]
-    end
-    
-    subgraph "Configuration Layers"
-        base[Base Configuration]
-        env[Environment Overlays]
-        service[Service-Specific Config]
-    end
-    
-    subgraph "Secret Management"
-        sealed[Sealed Secrets]
-        vault[HashiCorp Vault]
-        esm[External Secrets Manager]
-    end
-    
-    subgraph "Kubernetes Resources"
-        cm[ConfigMaps]
-        secrets[Secrets]
-        pods[Deployments]
-    end
-    
-    app --> build{Build Process}
-    infra --> terraform{Terraform}
-    
-    config --> base
-    base --> kustomize{Kustomize}
-    env --> kustomize
-    service --> kustomize
-    
-    sealed --> kustomize
-    vault --> esm
-    esm --> secrets
-    
-    kustomize --> cm
-    kustomize --> secrets
-    
-    build --> pods
-    terraform --> platform[Platform Resources]
-    cm --> pods
-    secrets --> pods
-``` 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/architecture-decision-records/drafts/03-api-management-governance.mdx b/examples/default/docs/technical-architecture-design/architecture-decision-records/drafts/03-api-management-governance.mdx
deleted file mode 100644
index 5f56ff38a..000000000
--- a/examples/default/docs/technical-architecture-design/architecture-decision-records/drafts/03-api-management-governance.mdx
+++ /dev/null
@@ -1,480 +0,0 @@
----
-title: API Management and Governance
-summary: Architectural decision record for our API management and governance approach for the FlowMart e-commerce platform
-sidebar:
-    label: API Management
-    order: 3
----
-
-# DRAFT - NOT YET APPROVED
-
-## ADR-009: API Management and Governance Strategy
-
-### Status
-
-Draft (Last Updated: 2024-10-07)
-
-### Context
-
-As we expand our microservices architecture for the FlowMart e-commerce platform, we need a comprehensive approach to API management and governance. We are facing several challenges with our current approach to APIs:
-
-1. **Proliferation of APIs**: With our transition to microservices, we anticipate having 50+ internal APIs and multiple external-facing APIs within the next year.
-
-2. **Inconsistent Design Patterns**: Teams are implementing APIs with inconsistent patterns, naming conventions, error handling, and response formats.
-
-3. **Documentation Gaps**: API documentation is inconsistent, often outdated, and frequently exists only in code comments or team wikis.
-
-4. **Discoverability Issues**: Developers struggle to find existing APIs, leading to duplication of functionality.
-
-5. **Security Concerns**: APIs lack consistent security controls, authentication mechanisms, and authorization models.
-
-6. **Version Management**: No clear strategy for versioning APIs, handling breaking changes, or maintaining backward compatibility.
-
-7. **Performance Visibility**: Limited visibility into API performance, usage patterns, and availability.
-
-8. **Cross-Cutting Concerns**: Features like rate limiting, caching, and observability are implemented inconsistently across services.
-
-9. **Developer Experience**: Onboarding to consume APIs is complex and time-consuming, both for internal teams and external partners.
-
-FlowMart is transitioning from a monolithic architecture to microservices, with a growing ecosystem of APIs. We need a cohesive approach to ensure these APIs are secure, discoverable, consistent, and manageable at scale.
-
-### Decision
-
-We will implement a comprehensive **API Management and Governance Strategy** with the following key components:
-
-1. **API Gateway Architecture**:
-   - Implement Kong as our primary API gateway for both internal and external APIs
-   - Deploy separate gateway instances for external, internal, and partner traffic
-   - Utilize a mesh pattern for internal service-to-service communication
-   - Implement a Backend for Frontend (BFF) pattern for frontend-specific aggregation
-
-2. **API Design Standards**:
-   - Adopt OpenAPI (formerly Swagger) as our API specification standard
-   - Establish comprehensive REST API design guidelines
-   - Implement a design-first approach for all new APIs
-   - Define standard patterns for resource naming, query parameters, pagination, filtering, and error responses
-   - Standardize on JSON:API specification for response formatting
-
-3. **API Lifecycle Management**:
-   - Define clear stages: Design → Review → Development → Testing → Deployment → Deprecation → Retirement
-   - Implement automated API contract testing in CI/CD pipelines
-   - Require specification update for any API changes
-   - Establish deprecation and sunsetting policies with clear timelines
-
-4. **API Governance Model**:
-   - Create an API Guild with representatives from each team
-   - Establish an API review process for all new APIs and significant changes
-   - Implement automated linting and compliance checking against standards
-   - Define metrics for API quality and compliance
-   - Regular review of API portfolio for duplication and consolidation opportunities
-
-5. **API Documentation and Discovery**:
-   - Deploy a central API developer portal using Backstage
-   - Ensure all APIs have OpenAPI specifications
-   - Implement automated documentation generation from OpenAPI specs
-   - Create a searchable API catalog with metadata, ownership, and usage examples
-   - Develop interactive API playground environments
-
-6. **API Security Framework**:
-   - Standardize on OAuth 2.0 and OpenID Connect for authentication
-   - Implement role-based and attribute-based access control
-   - Deploy centralized API key management
-   - Establish security scanning and penetration testing for APIs
-   - Implement API request validation based on schemas
-
-7. **API Monitoring and Analytics**:
-   - Deploy comprehensive API metrics collection
-   - Create dashboards for performance, availability, and usage
-   - Implement distributed tracing for end-to-end request flows
-   - Set up alerting on API SLOs and error rates
-   - Establish usage analytics for product and developer experience improvement
-
-8. **API Versioning Strategy**:
-   - Adopt semantic versioning (major.minor.patch) for all APIs
-   - Support at least one previous major version for backward compatibility
-   - Use URI versioning for major versions (/v1/, /v2/)
-   - Implement feature flags for progressive rollout of API changes
-   - Establish clear communication channels for API changes
-
-### Technology Stack
-
-| Component | Primary Technology | Alternative/Backup | Purpose |
-|-----------|-------------------|-------------------|---------|
-| API Gateway | Kong | Apigee, Amazon API Gateway | Traffic management, routing, policies |
-| API Specification | OpenAPI 3.0 | AsyncAPI (for event-driven) | API contract and documentation |
-| Developer Portal | Backstage | SwaggerHub, Readme.io | Discovery, documentation, onboarding |
-| Identity Provider | Auth0 | Keycloak, AWS Cognito | Authentication and authorization |
-| API Testing | Postman + Newman | SoapUI, Karate | Automated API testing |
-| API Monitoring | Datadog | New Relic, Prometheus | Observability and analytics |
-| Contract Testing | Pact | Spring Cloud Contract | Consumer-driven contract testing |
-| GraphQL Federation | Apollo Federation | Netflix DGS | GraphQL implementation |
-| API Design Tooling | Stoplight Studio | SwaggerHub, Insomnia | Design-first workflow |
-
-### Consequences
-
-#### Positive
-
-1. **Improved Developer Experience**: Consistent, well-documented APIs accelerate development.
-
-2. **Enhanced Security**: Standardized authentication and authorization patterns.
-
-3. **Better Visibility**: Comprehensive monitoring and analytics of API usage and performance.
-
-4. **Reduced Duplication**: Central catalog prevents redundant API implementations.
-
-5. **Faster Integration**: Partners and internal teams can onboard more quickly.
-
-6. **Higher Quality**: Standardized design patterns and automated testing improve quality.
-
-7. **Future-Proofing**: Versioning strategy ensures backward compatibility.
-
-8. **Operational Efficiency**: Centralized management of cross-cutting concerns.
-
-#### Negative
-
-1. **Initial Overhead**: Additional processes and governance may slow initial development.
-
-2. **Learning Curve**: Teams need to adapt to new standards and practices.
-
-3. **Migration Effort**: Existing APIs need to be refactored to meet new standards.
-
-4. **Tooling Investment**: Significant investment in API management infrastructure.
-
-5. **Governance Challenges**: Maintaining compliance across teams requires persistent effort.
-
-6. **Potential Bottlenecks**: API review processes could become a bottleneck if not well-designed.
-
-7. **Operational Complexity**: Additional infrastructure components to maintain.
-
-### Mitigation Strategies
-
-1. **Phased Implementation**:
-   - Start with high-priority, externally facing APIs
-   - Gradually implement standards for internal APIs
-   - Provide flexible transition periods for existing APIs
-
-2. **Developer Enablement**:
-   - Create comprehensive training materials and workshops
-   - Develop starter templates and code generators
-   - Provide API design consultation services
-   - Create self-service tools for standards compliance
-
-3. **Governance Optimization**:
-   - Implement automated compliance checking
-   - Create lightweight review processes for low-risk changes
-   - Empower teams with self-service validation tools
-   - Focus governance on enablement rather than control
-
-4. **Migration Support**:
-   - Develop clear migration guidelines and timelines
-   - Provide tooling to assist with API migrations
-   - Allow grandfathering of legacy APIs with clear deprecation plans
-   - Prioritize high-value, high-impact APIs for migration
-
-5. **Platform Team Support**:
-   - Create a dedicated API platform team
-   - Offer consulting services to teams implementing or consuming APIs
-   - Develop reusable components for common API patterns
-   - Continuously evolve standards based on feedback
-
-### Implementation Details
-
-#### Phase 1: Foundation (Q4 2024)
-
-1. Establish API design standards and guidelines
-2. Deploy API gateway for external-facing services
-3. Implement initial developer portal
-4. Create API governance process and guild
-5. Define API security standards
-
-#### Phase 2: Expansion (Q1 2025)
-
-1. Extend API gateway to internal services
-2. Implement comprehensive monitoring and analytics
-3. Deploy automated compliance checking
-4. Develop API versioning framework
-5. Create self-service API documentation tooling
-
-#### Phase 3: Optimization (Q2 2025)
-
-1. Implement advanced BFF patterns
-2. Deploy GraphQL federation for complex client needs
-3. Establish API performance optimization framework
-4. Create advanced analytics and business insights
-5. Develop partner API developer experiences
-
-### API Design Principles
-
-Our API design will adhere to the following principles:
-
-1. **Resource-Oriented Design**: Model APIs around business resources rather than operations.
-
-2. **Consistency**: APIs should behave consistently across the platform.
-
-3. **Least Privilege**: APIs should request only the permissions they need.
-
-4. **Robustness**: APIs should handle error cases gracefully and provide clear error messages.
-
-5. **Forward Compatibility**: Design APIs to be extended without breaking existing clients.
-
-6. **Discoverability**: APIs should be self-documenting and easily discoverable.
-
-7. **Performance**: APIs should be designed with performance considerations in mind.
-
-8. **Security by Design**: Security should be considered at every stage of the API lifecycle.
-
-### API Governance Model
-
-Our API governance model follows these principles:
-
-1. **Federated Ownership**: Teams own their APIs but follow central standards.
-
-2. **Standards over Rules**: Prefer guidance and patterns over strict enforcement.
-
-3. **Automated Compliance**: Automate standards checking wherever possible.
-
-4. **Continuous Improvement**: Regularly review and refine standards based on feedback.
-
-5. **Value-Driven**: Focus governance efforts on high-value, high-risk APIs.
-
-6. **Developer Experience**: Prioritize developer experience in governance decisions.
-
-7. **Transparency**: Make governance processes and decisions transparent to all teams.
-
-### Considered Alternatives
-
-#### 1. Decentralized API Management
-
-**Pros**: Maximum team autonomy, reduced coordination overhead  
-**Cons**: Inconsistent developer experience, potential security gaps, duplicated effort
-
-This approach would give teams complete freedom but would result in an inconsistent and potentially insecure API landscape that would be difficult to navigate and maintain.
-
-#### 2. Centralized API Development Team
-
-**Pros**: Maximum consistency, specialized expertise, controlled quality  
-**Cons**: Development bottleneck, reduced team ownership, slower delivery
-
-While this would ensure consistency, it would create bottlenecks and reduce the autonomy and ownership of our product teams, contradicting our microservices philosophy.
-
-#### 3. Multiple API Gateways by Domain
-
-**Pros**: Domain isolation, reduced blast radius, team autonomy  
-**Cons**: Management complexity, potential inconsistencies, higher operational overhead
-
-This approach offers benefits for large organizations but introduces unnecessary complexity for our current scale. We may revisit this approach as we grow.
-
-#### 4. GraphQL-First Approach
-
-**Pros**: Flexible client queries, reduced over-fetching, schema registry  
-**Cons**: Learning curve, performance concerns for some use cases, security complexity
-
-GraphQL offers benefits for certain use cases, but we believe a REST-first approach with GraphQL for specific complex client needs provides a better balance for our organization.
-
-### References
-
-1. "Web API Design: The Missing Link" by API Academy
-2. "REST API Design Rulebook" by Mark Masse
-3. [Google API Design Guide](https://cloud.google.com/apis/design)
-4. [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md)
-5. [JSON:API Specification](https://jsonapi.org/)
-6. [API Governance: What, Why, and How](https://swagger.io/resources/articles/api-governance-what-why-how/)
-
-### Decision Record History
-
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2024-09-30 | 0.1 | Initial draft | Sarah Johnson |
-| 2024-10-04 | 0.2 | Added governance model and phasing | Michael Chen |
-| 2024-10-07 | 0.3 | Incorporated feedback from API Guild | David Boyne |
-| TBD | 1.0 | Pending approval | Architecture Board |
-
-## Appendix A: API Governance Process
-
-```mermaid
-flowchart TB
-    subgraph "API Lifecycle"
-        design[Design Phase]
-        review[Review Phase]
-        develop[Development Phase]
-        test[Testing Phase]
-        deploy[Deployment Phase]
-        monitor[Monitoring Phase]
-        deprecate[Deprecation Phase]
-        
-        design --> review
-        review --> develop
-        develop --> test
-        test --> deploy
-        deploy --> monitor
-        monitor --> deprecate
-    end
-    
-    subgraph "Governance Touchpoints"
-        standards[Standards & Guidelines]
-        templates[API Templates]
-        linting[Automated Linting]
-        reviews[Peer Reviews]
-        testing[Contract Testing]
-        security[Security Scanning]
-        analytics[Usage Analytics]
-        
-        standards --> design
-        templates --> design
-        linting --> review
-        reviews --> review
-        testing --> test
-        security --> test
-        analytics --> monitor
-    end
-    
-    subgraph "Key Roles"
-        guild[API Guild]
-        owners[API Owners]
-        platform[Platform Team]
-        consumers[API Consumers]
-        
-        guild --> standards
-        owners --> design
-        platform --> templates
-        consumers --> analytics
-    end
-    
-    subgraph "Artifacts"
-        spec[OpenAPI Specification]
-        docs[Documentation]
-        portal[Developer Portal]
-        metrics[Metrics Dashboard]
-        
-        design --> spec
-        spec --> docs
-        docs --> portal
-        monitor --> metrics
-    end
-```
-
-## Appendix B: API Management Architecture
-
-```mermaid
-flowchart TB
-    subgraph "Clients"
-        web[Web Clients]
-        mobile[Mobile Clients]
-        partners[Partner Systems]
-        internal[Internal Services]
-    end
-    
-    subgraph "API Gateways"
-        public[Public API Gateway]
-        partner[Partner API Gateway]
-        internal_gw[Internal API Gateway]
-    end
-    
-    subgraph "BFF Layer"
-        web_bff[Web BFF]
-        mobile_bff[Mobile BFF]
-    end
-    
-    subgraph "API Services"
-        products[Product APIs]
-        orders[Order APIs]
-        customers[Customer APIs]
-        payments[Payment APIs]
-        inventory[Inventory APIs]
-    end
-    
-    subgraph "Cross-Cutting Concerns"
-        auth[Authentication]
-        rate[Rate Limiting]
-        cache[Caching]
-        logging[Logging]
-        analytics[Analytics]
-    end
-    
-    web --> web_bff
-    mobile --> mobile_bff
-    partners --> partner
-    internal --> internal_gw
-    
-    web_bff --> public
-    mobile_bff --> public
-    
-    public --> products
-    public --> orders
-    public --> customers
-    partner --> products
-    partner --> orders
-    internal_gw --> products
-    internal_gw --> orders
-    internal_gw --> customers
-    internal_gw --> payments
-    internal_gw --> inventory
-    
-    auth --> public
-    auth --> partner
-    auth --> internal_gw
-    rate --> public
-    rate --> partner
-    cache --> public
-    cache --> partner
-    cache --> internal_gw
-    logging --> public
-    logging --> partner
-    logging --> internal_gw
-    analytics --> public
-    analytics --> partner
-    analytics --> internal_gw
-```
-
-## Appendix C: API Developer Portal Architecture
-
-```mermaid
-flowchart LR
-    subgraph "API Developer Portal"
-        catalog[API Catalog]
-        docs[API Documentation]
-        playground[API Playground]
-        analytics[Usage Analytics]
-        sandbox[Sandbox Environment]
-        support[Developer Support]
-    end
-    
-    subgraph "API Sources"
-        openapi[OpenAPI Specifications]
-        asyncapi[AsyncAPI Specifications]
-        graphql[GraphQL Schemas]
-        code[Source Code]
-    end
-    
-    subgraph "Developer Tools"
-        cli[CLI Tools]
-        sdks[Client SDKs]
-        ci[CI/CD Integration]
-        codegen[Code Generators]
-    end
-    
-    subgraph "Governance Tools"
-        standards[Standards Library]
-        linting[Linting Tools]
-        testing[Testing Framework]
-        workflow[Approval Workflows]
-    end
-    
-    openapi --> catalog
-    asyncapi --> catalog
-    graphql --> catalog
-    code --> docs
-    
-    catalog --> playground
-    catalog --> analytics
-    catalog --> sdks
-    catalog --> codegen
-    
-    playground --> sandbox
-    sandbox --> support
-    
-    standards --> linting
-    linting --> ci
-    testing --> ci
-    workflow --> ci
-``` 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/architecture-decision-records/examples/01-microservice-mesh-adoption.mdx b/examples/default/docs/technical-architecture-design/architecture-decision-records/examples/01-microservice-mesh-adoption.mdx
deleted file mode 100644
index 4e5df73f0..000000000
--- a/examples/default/docs/technical-architecture-design/architecture-decision-records/examples/01-microservice-mesh-adoption.mdx
+++ /dev/null
@@ -1,313 +0,0 @@
----
-title: Service Mesh Adoption
-summary: Architectural decision record for adopting a service mesh for TechNova's cloud platform
-sidebar:
-    label: Service Mesh Adoption
-    order: 1
----
-
-## ADR-2023-05: Service Mesh Adoption for TechNova Cloud Platform
-
-### Status
-
-Approved (2023-08-15)
-
-### Context
-
-TechNova's cloud platform has grown to include over 75 microservices developed and maintained by 12 different teams. As our platform has scaled, we've encountered several challenges:
-
-1. **Service-to-Service Communication Complexity**: Managing service-to-service communication has become increasingly complex, with inconsistent implementation of patterns like circuit breaking, retries, and timeout handling.
-
-2. **Security Concerns**: Service-to-service authentication and authorization is implemented inconsistently, creating potential security vulnerabilities.
-
-3. **Observability Gaps**: Tracking request flows across services is difficult, making troubleshooting and performance optimization challenging.
-
-4. **Traffic Management Challenges**: We lack sophisticated traffic control capabilities such as traffic splitting, canary deployments, and blue/green releases.
-
-5. **Certificate Management**: Managing and rotating TLS certificates for service-to-service communication has become an operational burden.
-
-6. **Network Policy Enforcement**: Network access controls are difficult to implement and maintain consistently across services.
-
-Our engineering teams currently spend approximately 25% of their development effort on these cross-cutting concerns, diverting resources from building business functionality.
-
-### Decision
-
-We will adopt **Istio** as our service mesh solution for the TechNova Cloud Platform. Specifically:
-
-1. **Sidecar Deployment Model**: We will deploy Istio using the sidecar proxy architecture to minimize disruption to existing services.
-
-2. **Gradual Implementation**: We will introduce the service mesh incrementally, starting with non-critical services and gradually expanding to include all services.
-
-3. **Standardized Patterns**: We will establish company-wide standards for:
-   - Circuit breaking configurations
-   - Retry policies
-   - Timeout configurations
-   - Mutual TLS implementation
-   - Traffic management patterns
-   - Observability integrations
-
-4. **Platform Team Ownership**: A dedicated platform team will own the service mesh infrastructure, including:
-   - Istio version management and upgrades
-   - Performance monitoring and optimization
-   - Security policy definition and enforcement
-   - Training and documentation
-
-5. **Integration with Existing Tooling**:
-   - Prometheus and Grafana for metrics and dashboarding
-   - Jaeger for distributed tracing
-   - Kiali for service mesh visualization
-   - Cert-Manager for certificate management
-
-6. **Control Plane Configuration**: We will deploy Istio with:
-   - High availability control plane (3 replicas)
-   - Split along environment boundaries (separate control planes for production and non-production)
-   - Regular automated backups of control plane configuration
-
-### Consequences
-
-#### Positive
-
-1. **Simplified Service Code**: Application developers can focus on business logic rather than communication concerns.
-
-2. **Enhanced Security**: Consistent mTLS implementation will improve our security posture.
-
-3. **Improved Observability**: End-to-end request tracing and detailed service metrics will enhance troubleshooting.
-
-4. **Advanced Traffic Management**: Capabilities for canary deployments and traffic steering will reduce deployment risk.
-
-5. **Certificate Automation**: Automated certificate management will reduce operational overhead.
-
-6. **Standardized Networking Policies**: Centralized network policy enforcement will improve security and compliance.
-
-#### Negative
-
-1. **Increased Complexity**: Service mesh adds architectural complexity and new failure modes.
-
-2. **Resource Overhead**: Sidecar proxies consume additional CPU and memory resources (~10-15% based on POC testing).
-
-3. **Learning Curve**: Teams will need to learn new concepts, tooling, and debugging approaches.
-
-4. **Deployment Changes**: CI/CD pipelines will need updates to accommodate service mesh configuration.
-
-5. **Potential Performance Impact**: Additional network hops may increase latency (observed ~5-10ms per hop in testing).
-
-6. **Operational Changes**: Incident response and troubleshooting procedures will need updates.
-
-### Mitigation Strategies
-
-1. **Comprehensive Education Program**:
-   - Create internal training curriculum for all engineering teams
-   - Schedule hands-on workshops focusing on practical use cases
-   - Develop troubleshooting playbooks and runbooks
-
-2. **Gradual Rollout Plan**:
-   - Phase 1 (Q3 2023): Deploy to non-critical services and gather metrics
-   - Phase 2 (Q4 2023): Expand to backend services with low customer impact
-   - Phase 3 (Q1 2024): Roll out to critical customer-facing services
-
-3. **Resource Optimization**:
-   - Tune proxy resource requests based on actual usage patterns
-   - Implement horizontal pod autoscaling for proxies
-   - Monitor and optimize control plane resource utilization
-
-4. **Performance Monitoring**:
-   - Establish baseline performance metrics before service mesh adoption
-   - Implement detailed performance monitoring dashboards
-   - Set alerting on latency increases beyond acceptable thresholds
-
-5. **Escape Hatch Mechanisms**:
-   - Document procedures for temporarily bypassing the service mesh if issues arise
-   - Create fast rollback capabilities for service mesh configurations
-
-### Implementation Details
-
-#### Phase 1: Foundation (Q3 2023)
-
-1. Deploy Istio control plane in non-production environments
-2. Implement mTLS for a subset of non-critical services
-3. Set up integration with observability stack
-4. Develop initial training materials and documentation
-5. Create standard Istio configuration templates
-
-#### Phase 2: Expansion (Q4 2023)
-
-1. Deploy production control plane
-2. Expand to backend services
-3. Implement traffic management capabilities
-4. Develop automated testing for service mesh configurations
-5. Integrate service mesh configurations into CI/CD pipelines
-
-#### Phase 3: Completion (Q1 2024)
-
-1. Roll out to remaining services
-2. Implement advanced security policies
-3. Complete comprehensive monitoring and alerting
-4. Finalize operational procedures and runbooks
-5. Document lessons learned and best practices
-
-### Considered Alternatives
-
-#### 1. Linkerd
-
-**Pros**: Lighter weight, simpler operations, lower resource overhead  
-**Cons**: Fewer features, smaller community, less integration with enterprise tools
-
-While Linkerd offers a more lightweight approach, we found that its limited feature set would not address all our requirements, particularly around sophisticated traffic management and extensibility.
-
-#### 2. AWS App Mesh
-
-**Pros**: Native AWS integration, managed control plane, simplified operations  
-**Cons**: AWS-specific, limited feature set compared to Istio, less community support
-
-AWS App Mesh would align well with our AWS infrastructure but lacks some advanced features we require and would limit our multi-cloud flexibility.
-
-#### 3. Custom Solution with Envoy
-
-**Pros**: Tailored to our exact needs, potentially lower overhead  
-**Cons**: High development and maintenance cost, lack of community support, reinventing the wheel
-
-Building our own solution would require significant engineering resources and ongoing maintenance, which would outweigh the benefits of customization.
-
-#### 4. No Service Mesh (Status Quo)
-
-**Pros**: No additional complexity or overhead, familiar patterns  
-**Cons**: Continued inconsistency across services, growing technical debt, security risks
-
-Maintaining the status quo would fail to address our current challenges and would further increase technical debt as our platform continues to grow.
-
-### References
-
-1. [Istio Documentation](https://istio.io/latest/docs/)
-2. "The Service Mesh Era" - Cloud Native Computing Foundation Whitepaper
-3. Internal POC Report: "Service Mesh Performance and Compatibility Testing" (TechNova Engineering, June 2023)
-4. [CNCF Service Mesh Comparison](https://servicemesh.es/)
-5. [Envoy Proxy Documentation](https://www.envoyproxy.io/docs/envoy/latest/)
-6. "Production Istio" - O'Reilly Media, 2022
-
-### Decision Record History
-
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2023-05-10 | 0.1 | Initial draft | Alexander Chen, Principal Architect |
-| 2023-06-22 | 0.2 | Updated based on POC results | Sophia Rodriguez, Platform Engineering |
-| 2023-07-15 | 0.3 | Added phased implementation plan | Marcus Johnson, Engineering Director |
-| 2023-08-15 | 1.0 | Approved by Architecture Review Board | TechNova ARB |
-
-## Appendix A: Service Mesh Architecture
-
-```mermaid
-flowchart TB
-    subgraph "Control Plane"
-        istiod[Istiod]
-        config[Configuration API]
-        certs[Certificate Authority]
-    end
-    
-    subgraph "Ingress/Egress"
-        ingress[Ingress Gateway]
-        egress[Egress Gateway]
-    end
-    
-    subgraph "Observability"
-        prom[Prometheus]
-        grafana[Grafana]
-        jaeger[Jaeger]
-        kiali[Kiali]
-    end
-    
-    subgraph "Kubernetes Cluster"
-        subgraph "Service A"
-            svcA[Service A]
-            proxyA[Envoy Proxy]
-        end
-        
-        subgraph "Service B"
-            svcB[Service B]
-            proxyB[Envoy Proxy]
-        end
-        
-        subgraph "Service C"
-            svcC[Service C]
-            proxyC[Envoy Proxy]
-        end
-    end
-    
-    client[Client] --> ingress
-    ingress --> proxyA
-    proxyA --> svcA
-    proxyA --> proxyB
-    proxyB --> svcB
-    proxyB --> proxyC
-    proxyC --> svcC
-    proxyC --> egress
-    egress --> external[External Services]
-    
-    istiod --> proxyA
-    istiod --> proxyB
-    istiod --> proxyC
-    istiod --> ingress
-    istiod --> egress
-    
-    config --> istiod
-    certs --> istiod
-    
-    proxyA --> prom
-    proxyB --> prom
-    proxyC --> prom
-    prom --> grafana
-    proxyA --> jaeger
-    proxyB --> jaeger
-    proxyC --> jaeger
-    prom --> kiali
-    jaeger --> kiali
-    config --> kiali
-```
-
-## Appendix B: Service Mesh Implementation Timeline
-
-```mermaid
-gantt
-    title TechNova Service Mesh Implementation
-    dateFormat  YYYY-MM-DD
-    
-    section Planning
-    Initial Research           :done, 2023-03-01, 2023-04-15
-    Proof of Concept           :done, 2023-04-16, 2023-06-15
-    Architecture Decision      :done, 2023-06-16, 2023-08-15
-    
-    section Phase 1: Foundation
-    Control Plane Setup        :active, 2023-08-16, 2023-09-15
-    Observability Integration  :active, 2023-09-01, 2023-09-30
-    Initial Service Onboarding :2023-09-15, 2023-10-15
-    Training & Documentation   :2023-09-01, 2023-10-31
-    
-    section Phase 2: Expansion
-    Production Control Plane   :2023-11-01, 2023-11-30
-    Backend Service Onboarding :2023-11-15, 2024-01-15
-    CI/CD Integration          :2023-12-01, 2024-01-31
-    Advanced Traffic Management:2024-01-01, 2024-02-15
-    
-    section Phase 3: Completion
-    Remaining Service Onboarding :2024-02-01, 2024-03-31
-    Security Policy Implementation:2024-02-15, 2024-03-31
-    Finalize Operations Procedures:2024-03-01, 2024-04-15
-    Performance Optimization     :2024-03-15, 2024-04-30
-    Project Completion          :milestone, 2024-04-30
-```
-
-## Appendix C: Estimated Resource Requirements
-
-| Component | CPU Request | Memory Request | Replicas | Environment | Notes |
-|-----------|-------------|---------------|----------|-------------|-------|
-| Istiod | 500m | 2Gi | 3 | Production | HA configuration |
-| Istiod | 500m | 2Gi | 1 | Non-Production | Single replica |
-| Ingress Gateway | 500m | 1Gi | 3 | Production | External traffic entry |
-| Ingress Gateway | 200m | 512Mi | 1 | Non-Production | Development testing |
-| Egress Gateway | 500m | 1Gi | 2 | Production | External service access |
-| Envoy Proxy | 100m | 256Mi | 1 per pod | All | Sidecar containers |
-| Prometheus | 1000m | 8Gi | 2 | Production | Metric collection |
-| Grafana | 200m | 1Gi | 2 | Production | Dashboarding |
-| Jaeger | 500m | 4Gi | 2 | Production | Distributed tracing |
-| Kiali | 200m | 1Gi | 2 | Production | Mesh visualization |
-
-*Note: These values are initial estimates based on our proof of concept and may be adjusted based on actual usage patterns.* 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/architecture-decision-records/examples/02-data-platform-strategy.mdx b/examples/default/docs/technical-architecture-design/architecture-decision-records/examples/02-data-platform-strategy.mdx
deleted file mode 100644
index 81632af66..000000000
--- a/examples/default/docs/technical-architecture-design/architecture-decision-records/examples/02-data-platform-strategy.mdx
+++ /dev/null
@@ -1,415 +0,0 @@
----
-title: Data Platform Strategy
-summary: Architectural decision record for adopting a modern data platform at FinSecure
-sidebar:
-    label: Data Platform Strategy
-    order: 2
----
-
-## ADR-2023-12: Modern Data Platform Strategy for FinSecure
-
-### Status
-
-Approved (2023-12-18)
-
-### Context
-
-FinSecure is experiencing significant challenges with our current data architecture:
-
-1. **Data Silos**: Customer, transaction, and risk data are siloed across multiple legacy systems with inconsistent data models.
-
-2. **Limited Analytics Capabilities**: Rigid data warehousing solutions limit our ability to perform advanced analytics and machine learning.
-
-3. **Scalability Constraints**: Current data processing infrastructure is struggling to handle increasing data volumes (now exceeding 5TB daily).
-
-4. **Compliance Complexity**: Meeting GDPR, CCPA, and financial regulatory requirements across fragmented data systems is increasingly difficult.
-
-5. **Slow Time-to-Insight**: Business teams wait 2-3 weeks for new analytics dashboards or data models to be developed.
-
-6. **Technical Debt**: Legacy ETL processes are complex, brittle, and expensive to maintain.
-
-7. **Limited Real-time Capabilities**: Current architecture is primarily batch-oriented with limited ability to process streaming data for fraud detection and real-time decisioning.
-
-8. **Data Quality Issues**: Inconsistent data quality across systems impacts business decisions and customer experience.
-
-These challenges are limiting our ability to leverage data as a strategic asset and inhibiting our digital transformation initiatives aimed at enhancing customer experiences and operational efficiency.
-
-### Decision
-
-We will implement a **modern, cloud-based data platform** with a **lakehouse architecture**. Key components include:
-
-1. **Data Lake Foundation**:
-   - Azure Data Lake Storage Gen2 as the foundation for our data lake
-   - Databricks Delta Lake for ACID transactions and data reliability
-   - Structured organization with bronze (raw), silver (refined), and gold (business) layers
-
-2. **Data Ingestion and Processing**:
-   - Azure Data Factory for orchestration and batch data movement
-   - Kafka and Azure Event Hubs for real-time data ingestion
-   - Databricks for large-scale data processing
-   - Stream processing with Spark Structured Streaming
-
-3. **Semantic Layer and Data Serving**:
-   - Databricks SQL Warehouses for analytics workloads
-   - Azure Synapse Analytics for enterprise data warehousing needs
-   - Power BI as primary business intelligence tool
-   - REST APIs for serving data to applications
-
-4. **Data Governance and Security**:
-   - Azure Purview for data catalog and lineage
-   - Column-level encryption for sensitive data
-   - Role-based access control aligned with data classification
-   - Automated data retention and purging based on policies
-
-5. **Machine Learning Platform**:
-   - MLflow for experiment tracking and model registry
-   - Databricks ML for model development and deployment
-   - Model monitoring and retraining pipelines
-   - Feature store for reusable feature engineering
-
-6. **DataOps and Automation**:
-   - Infrastructure as Code using Terraform
-   - CI/CD pipelines for data pipelines and transformations
-   - Automated testing for data quality and pipeline integrity
-   - Comprehensive monitoring and alerting
-
-### Platform Architecture by Domain
-
-| Domain | Data Types | Primary Tools | Access Patterns | Special Requirements |
-|--------|------------|--------------|-----------------|----------------------|
-| Customer 360 | Customer profiles, interactions, preferences | Delta Lake, Databricks SQL | Batch analytics, Real-time lookups | GDPR compliance, Entity resolution |
-| Transaction Processing | Payment transactions, transfers, statements | Kafka, Delta Lake, Azure Synapse | Real-time streaming, Batch reporting | PCI-DSS compliance, 7-year retention |
-| Risk Management | Credit scores, market data, exposure calculations | Databricks, Delta Lake, ML models | Batch processing, Model inference | Auditability, Model governance |
-| Fraud Detection | Transaction patterns, behavioral signals | Kafka, Spark Streaming, ML models | Real-time streaming, Low-latency scoring | Sub-second latency, High availability |
-| Regulatory Reporting | Aggregated financial data, compliance metrics | Azure Synapse, Power BI | Scheduled batch, Ad-hoc analysis | Immutability, Approval workflows |
-| Marketing Analytics | Campaign data, customer segments, attribution | Databricks, Delta Lake, Power BI | Interactive queries, ML-based segmentation | Identity resolution, Attribution models |
-
-### Consequences
-
-#### Positive
-
-1. **Unified Data Access**: Single platform for accessing enterprise data with consistent governance.
-
-2. **Enhanced Analytical Capabilities**: Support for advanced analytics, machine learning, and AI initiatives.
-
-3. **Improved Scalability**: Cloud-native architecture can scale to handle growing data volumes.
-
-4. **Reduced Time-to-Insight**: Self-service capabilities and streamlined data pipelines reduce time to deliver insights.
-
-5. **Better Data Governance**: Centralized data catalog, lineage tracking, and security controls.
-
-6. **Real-time Capabilities**: Support for both batch and real-time processing using the same platform.
-
-7. **Cost Optimization**: Pay-for-use cloud model with ability to scale resources as needed.
-
-8. **Regulatory Compliance**: Improved ability to implement and demonstrate regulatory compliance.
-
-#### Negative
-
-1. **Implementation Complexity**: Significant effort required to migrate from legacy systems.
-
-2. **Skills Gap**: New technologies require reskilling of existing teams.
-
-3. **Initial Cost Increase**: Short-term investment in new technology and parallel running of systems.
-
-4. **Data Migration Challenges**: Data quality and mapping issues during migration.
-
-5. **Operational Changes**: New operational procedures and support models needed.
-
-6. **Integration Complexity**: Connecting legacy systems to new platform requires careful planning.
-
-7. **Organization Change Management**: New workflows and responsibilities across business and technical teams.
-
-### Mitigation Strategies
-
-1. **Phased Implementation Approach**:
-   - Start with highest-value, least-critical data domains
-   - Implement foundational capabilities before complex use cases
-   - Run legacy and new systems in parallel during transition
-   - Create clear success criteria for each phase
-
-2. **Talent and Skill Development**:
-   - Develop comprehensive training program for existing staff
-   - Strategic hiring for key specialized roles
-   - Partner with platform vendors for enablement
-   - Create centers of excellence for key technologies
-
-3. **Modern Data Governance**:
-   - Establish data governance council with cross-functional representation
-   - Define clear data ownership and stewardship model
-   - Implement automated data quality monitoring
-   - Create comprehensive data classification framework
-
-4. **Financial Management**:
-   - Detailed cloud cost monitoring and optimization
-   - Business-aligned chargeback model
-   - Clear ROI tracking for data initiatives
-   - Regular cost optimization reviews
-
-5. **Change Management Program**:
-   - Executive sponsorship and visible leadership
-   - Regular communication and success stories
-   - Early involvement of business stakeholders
-   - Incentives aligned with adoption goals
-
-### Implementation Details
-
-#### Phase 1: Foundation (Q1-Q2 2024)
-
-1. Establish cloud environment and core infrastructure
-2. Implement data lake foundation with initial data domains
-3. Deploy data catalog and basic governance tools
-4. Migrate first non-critical data workloads
-5. Establish DataOps practices and pipelines
-
-#### Phase 2: Expansion (Q3-Q4 2024)
-
-1. Migrate core analytical workloads to the platform
-2. Implement real-time data processing capabilities
-3. Deploy self-service analytics for business users
-4. Enhance data quality frameworks and monitoring
-5. Develop initial ML use cases on the platform
-
-#### Phase 3: Advanced Capabilities (Q1-Q2 2025)
-
-1. Full enterprise adoption across all data domains
-2. Advanced ML capabilities and feature store
-3. Comprehensive data governance implementation
-4. Legacy system decommissioning
-5. Advanced real-time analytics and decisioning
-
-### Considered Alternatives
-
-#### 1. Modernize Existing Data Warehouse
-
-**Pros**: Lower initial disruption, familiar technology, focused scope  
-**Cons**: Limited flexibility, higher long-term costs, limited real-time capabilities
-
-This approach would not address our fundamental needs for real-time processing, advanced analytics, and managing unstructured data.
-
-#### 2. Traditional Data Lake Architecture
-
-**Pros**: Lower cost storage, support for varied data types, scalability  
-**Cons**: Complexity in ensuring data quality, limited transactional support, governance challenges
-
-A traditional data lake without the lakehouse capabilities would create significant challenges for data reliability, performance, and governance.
-
-#### 3. Multiple Purpose-Built Systems
-
-**Pros**: Optimized solutions for specific use cases, potentially best-in-class capabilities  
-**Cons**: Increased integration complexity, data duplication, inconsistent governance
-
-This approach would perpetuate our data silo issues and create ongoing integration and consistency challenges.
-
-#### 4. Maintain and Incrementally Improve Current Systems
-
-**Pros**: Minimal disruption, lower initial investment, familiar technology  
-**Cons**: Perpetuates technical debt, limited capability improvement, increasing maintenance costs
-
-This would fail to address our fundamental challenges and put us at a competitive disadvantage as data volumes and complexity increase.
-
-### References
-
-1. "Designing Data-Intensive Applications" by Martin Kleppmann
-2. [Databricks Lakehouse Platform Documentation](https://docs.databricks.com/lakehouse/index.html)
-3. [Azure Data Factory Documentation](https://docs.microsoft.com/en-us/azure/data-factory/)
-4. "Data Mesh: Delivering Data-Driven Value at Scale" by Zhamak Dehghani
-5. FinSecure Internal Report: "Data Platform Requirements Analysis" (October 2023)
-6. [DAMA Data Management Body of Knowledge](https://www.dama.org/cpages/body-of-knowledge)
-
-### Decision Record History
-
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2023-10-15 | 0.1 | Initial draft | Jennifer Wu, Chief Data Officer |
-| 2023-11-08 | 0.2 | Updated based on technical review | Raj Patel, Data Engineering Lead |
-| 2023-12-02 | 0.3 | Added implementation phases and cost estimates | Michael Torres, Enterprise Architect |
-| 2023-12-18 | 1.0 | Approved by Executive Technology Committee | FinSecure ETC |
-
-## Appendix A: Data Platform Architecture
-
-```mermaid
-flowchart TB
-    subgraph "Data Sources"
-        core[Core Banking Systems]
-        crm[CRM Systems]
-        channels[Digital Channels]
-        market[Market Data Feeds]
-        apps[Applications]
-        ext[External Partners]
-    end
-    
-    subgraph "Data Ingestion"
-        batch[Batch Processing]
-        stream[Stream Processing]
-        cdc[Change Data Capture]
-        api[API Integration]
-    end
-    
-    subgraph "Data Storage"
-        subgraph "Data Lake"
-            bronze[Bronze Layer<br>Raw Data]
-            silver[Silver Layer<br>Cleansed & Conformed]
-            gold[Gold Layer<br>Business Aggregates]
-        end
-        
-        dw[Enterprise Data Warehouse]
-        fs[Feature Store]
-    end
-    
-    subgraph "Processing & Analytics"
-        etl[ETL/ELT Processes]
-        bi[Business Intelligence]
-        ml[Machine Learning]
-        ad[Advanced Analytics]
-        realtime[Real-time Analytics]
-    end
-    
-    subgraph "Data Consumption"
-        reports[Reports & Dashboards]
-        apps2[Applications]
-        apis[APIs & Services]
-        exports[Exports & Feeds]
-        ml_svc[ML Services]
-    end
-    
-    subgraph "Governance & Operations"
-        catalog[Data Catalog]
-        quality[Data Quality]
-        lineage[Data Lineage]
-        security[Security & Privacy]
-        lifecycle[Data Lifecycle]
-    end
-    
-    core --> batch
-    crm --> batch
-    channels --> stream
-    market --> stream
-    apps --> cdc
-    ext --> api
-    
-    batch --> bronze
-    stream --> bronze
-    cdc --> bronze
-    api --> bronze
-    
-    bronze --> etl
-    etl --> silver
-    silver --> etl
-    etl --> gold
-    etl --> dw
-    gold --> dw
-    silver --> fs
-    
-    dw --> bi
-    gold --> bi
-    silver --> ml
-    gold --> ml
-    fs --> ml
-    silver --> ad
-    bronze --> realtime
-    silver --> realtime
-    
-    bi --> reports
-    ml --> ml_svc
-    ad --> apis
-    realtime --> apps2
-    dw --> exports
-    
-    catalog --> bronze
-    catalog --> silver
-    catalog --> gold
-    catalog --> dw
-    
-    quality --> silver
-    lineage --> etl
-    security --> dw
-    lifecycle --> bronze
-```
-
-## Appendix B: Data Platform Implementation Timeline
-
-```mermaid
-gantt
-    title FinSecure Data Platform Implementation
-    dateFormat  YYYY-MM-DD
-    
-    section Strategy & Planning
-    Requirements Analysis       :done, 2023-08-01, 2023-10-15
-    Vendor Evaluation           :done, 2023-09-15, 2023-11-15
-    Architecture Design         :done, 2023-10-01, 2023-12-15
-    
-    section Phase 1: Foundation
-    Core Infrastructure Setup   :active, 2024-01-15, 2024-02-28
-    Data Lake Implementation    :2024-02-01, 2024-03-31
-    Governance Framework        :2024-02-15, 2024-04-15
-    Initial Data Migration      :2024-03-01, 2024-05-31
-    DataOps Implementation      :2024-04-01, 2024-06-30
-    
-    section Phase 2: Expansion
-    Advanced Analytics Platform :2024-07-01, 2024-09-30
-    Streaming Data Processing   :2024-08-01, 2024-10-31
-    Self-service Analytics      :2024-09-01, 2024-11-30
-    Data Quality Framework      :2024-10-01, 2024-12-15
-    ML Platform Deployment      :2024-10-15, 2025-01-31
-    
-    section Phase 3: Advanced
-    Enterprise-wide Adoption    :2025-02-01, 2025-04-30
-    Legacy System Decomm        :2025-03-01, 2025-06-30
-    Advanced Governance         :2025-04-01, 2025-06-30
-    Real-time Decisioning       :2025-05-01, 2025-07-31
-    Program Completion          :milestone, 2025-07-31
-```
-
-## Appendix C: Target State Data Flow - Customer 360 Example
-
-```mermaid
-sequenceDiagram
-    participant Source as Source Systems
-    participant Ingest as Data Ingestion
-    participant Bronze as Bronze Layer
-    participant Process as Data Processing
-    participant Silver as Silver Layer
-    participant Gold as Gold Layer
-    participant Consume as Data Consumption
-    
-    Source->>Ingest: Customer Data<br>(Core Banking, CRM, Channels)
-    Ingest->>Bronze: Raw Data Ingestion<br>(Batch & Streaming)
-    
-    Bronze->>Process: Validation & Cleansing
-    Process->>Process: Data Quality Checks
-    Process->>Process: Deduplication
-    Process->>Process: Standardization
-    Process->>Silver: Refined Customer Records
-    
-    Silver->>Process: Entity Resolution
-    Process->>Process: Customer Attribute Generation
-    Process->>Process: Relationship Mapping
-    Process->>Process: History Processing
-    Process->>Gold: Unified Customer Profiles
-    
-    Gold->>Consume: Customer 360 Views
-    Gold->>Consume: Segmentation Models
-    Gold->>Consume: Marketing Analytics
-    Gold->>Consume: Risk Assessment
-    Gold->>Consume: Real-time Personalization
-    
-    Note over Bronze,Gold: Data Governance<br>- Lineage Tracking<br>- Privacy Controls<br>- Data Classification<br>- Quality Monitoring
-```
-
-## Appendix D: Key Performance Indicators
-
-| KPI | Current State | Target (2025) | Measurement Method |
-|-----|---------------|---------------|-------------------|
-| Data Integration Cycle Time | 7-14 days | &lt;24 hours | Average time from source change to data availability |
-| Self-service BI Adoption | 15% of business users | &gt;60% of business users | Monthly active users in self-service tools |
-| Data Quality Score | ~75% | &gt;95% | Composite score from automated quality checks |
-| Cost per TB of Analytics Storage | $2,500/TB | &lt;$500/TB | Total cost of ownership / storage volume |
-| Time to New Analytics | 2-3 weeks | &lt;3 days | Time from request to dashboard availability |
-| Data Platform Availability | 99.5% | 99.95% | Measured service uptime |
-| Regulatory Report Production Time | 10-15 days | 1-2 days | Time to produce monthly regulatory reports |
-| Real-time Decision Latency | Not available | &lt;250ms | Response time for real-time decision APIs |
-| ML Model Deployment Time | 4-6 weeks | &lt;1 week | Time from model approval to production deployment |
-| Data Engineer Productivity | ~30% on new features | &gt;70% on new features | Time allocation analysis |
-
-*Note: Metrics will be tracked quarterly and reported to the Data Governance Council.* 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/architecture-decision-records/published/01-api-gateway-pattern.mdx b/examples/default/docs/technical-architecture-design/architecture-decision-records/published/01-api-gateway-pattern.mdx
deleted file mode 100644
index bfa97bf35..000000000
--- a/examples/default/docs/technical-architecture-design/architecture-decision-records/published/01-api-gateway-pattern.mdx
+++ /dev/null
@@ -1,250 +0,0 @@
----
-title: API Gateway Pattern Adoption
-summary: Architectural decision record for implementing an API Gateway for the FlowMart e-commerce platform
-sidebar:
-    label: API Gateway Pattern
-    order: 1
----
-
-## ADR-001: Adoption of API Gateway Pattern for FlowMart E-commerce Platform
-
-### Status
-
-Approved (2024-06-10)
-
-### Context
-
-As we migrate to a microservices-based architecture for our e-commerce platform, we face several challenges in managing API endpoints:
-
-1. **API Proliferation**: Each microservice exposes its own APIs, leading to a large number of endpoints that clients need to interact with.
-2. **Cross-cutting Concerns**: Common functionality like authentication, logging, and rate limiting needs to be implemented consistently across all services.
-3. **Client Complexity**: Mobile apps, web frontends, and third-party integrations would need to understand the topology of our microservices ecosystem.
-4. **Protocol Diversity**: Some internal services may use protocols (gRPC, AMQP) that aren't suitable for direct client consumption.
-5. **Network Performance**: Multiple direct client-to-service calls increase network overhead, especially on mobile networks.
-6. **Security Exposure**: Direct exposure of microservices increases the attack surface of our platform.
-
-We need a solution that simplifies our API landscape while maintaining the benefits of our microservices architecture.
-
-### Decision
-
-We will implement an **API Gateway Pattern** as the primary entry point for all client applications interacting with the FlowMart e-commerce platform. Specifically:
-
-1. **Gateway Implementation**: We will use **Kong API Gateway** as our primary implementation due to its robust plugin ecosystem, performance characteristics, and open-source foundation.
-
-2. **Gateway Responsibilities**:
-   - **Request Routing**: Directing requests to appropriate backend services
-   - **Authentication & Authorization**: Validating user identity and permissions
-   - **Rate Limiting**: Protecting services from excessive load
-   - **Request/Response Transformation**: Adapting data formats between clients and services
-   - **Caching**: Reducing backend load for frequently requested data
-   - **Logging & Monitoring**: Centralized request tracking
-   - **Circuit Breaking**: Preventing cascading failures
-   - **Protocol Translation**: Supporting REST, GraphQL, and gRPC as needed
-
-3. **Gateway Topology**:
-   - **Edge Gateway**: A public-facing gateway for all external clients
-   - **Internal Gateway**: For service-to-service communication within our private network
-
-4. **API Composition**: The gateway will aggregate responses from multiple services when needed to reduce client-side complexity.
-
-5. **Backend-for-Frontend (BFF) Pattern**: We will implement specific gateway configurations for different client platforms (web, mobile iOS, mobile Android) to optimize payloads and calls.
-
-6. **API Versioning**: The gateway will support multiple API versions to enable graceful evolution of our services.
-
-### Consequences
-
-#### Positive
-
-1. **Simplified Client Development**: Clients only need to know about a single entry point rather than multiple service endpoints.
-
-2. **Consistent Security Enforcement**: Authentication, authorization, and other security controls can be implemented uniformly.
-
-3. **Operational Visibility**: Centralized logging and monitoring of all API traffic.
-
-4. **Performance Optimization**: Opportunity for response caching, request collapsing, and other optimizations.
-
-5. **Flexible Evolution**: Backend services can be refactored, replaced, or decomposed without changing client implementations.
-
-6. **Traffic Control**: Ability to throttle, prioritize, or redirect traffic based on various conditions.
-
-#### Negative
-
-1. **Potential Single Point of Failure**: The gateway becomes critical infrastructure that must be highly available.
-
-2. **Increased Latency**: Adding another network hop introduces some additional latency.
-
-3. **Gateway Complexity**: The gateway configuration grows in complexity as the number of services increases.
-
-4. **Operational Overhead**: Additional infrastructure to monitor, maintain, and scale.
-
-5. **Deployment Coupling**: Gateway configuration changes may need coordination with service deployments.
-
-6. **Performance Bottleneck Risk**: Without proper scaling, the gateway could become a bottleneck under high load.
-
-### Mitigation Strategies
-
-1. **High Availability**: Deploy the API Gateway in a redundant, auto-scaling configuration across multiple availability zones.
-
-2. **Performance Optimization**: Implement efficient caching strategies and regular performance testing.
-
-3. **Circuit Breakers**: Implement circuit breakers to prevent cascading failures if backend services are unavailable.
-
-4. **Automated Configuration**: Use infrastructure as code to manage gateway configuration, with automated testing.
-
-5. **API Governance**: Establish clear ownership and review processes for gateway configuration changes.
-
-6. **Observability**: Implement comprehensive monitoring and alerting specifically for the gateway.
-
-### Implementation Details
-
-#### Phase 1: Core Infrastructure (Q2 2024)
-
-1. Deploy Kong API Gateway in development and staging environments
-2. Implement basic routing for 2-3 core services
-3. Set up authentication and authorization
-4. Establish monitoring and logging
-5. Create CI/CD pipeline for gateway configuration
-
-#### Phase 2: Feature Expansion (Q3 2024)
-
-1. Migrate all existing APIs to the gateway
-2. Implement rate limiting and circuit breaking
-3. Add response caching for appropriate endpoints
-4. Develop BFF configurations for web and mobile
-5. Implement comprehensive end-to-end testing
-
-#### Phase 3: Advanced Capabilities (Q4 2024)
-
-1. Implement GraphQL support for specific use cases
-2. Add advanced analytics and API usage dashboards
-3. Integrate with service mesh for internal service communication
-4. Implement advanced security features (WAF, etc.)
-5. Optimize for global performance
-
-### Considered Alternatives
-
-#### 1. Direct Client-to-Microservice Communication
-
-**Pros**: Simplicity, no additional network hop, no central bottleneck  
-**Cons**: Client complexity, inconsistent policy enforcement, security challenges
-
-This approach would expose our internal service architecture directly to clients, creating significant complexity and security concerns.
-
-#### 2. Service Mesh Only (no API Gateway)
-
-**Pros**: Great for service-to-service communication, built-in resilience  
-**Cons**: Not designed for edge traffic, less focus on client-specific concerns
-
-While we plan to use a service mesh for internal communication, it doesn't address the client-facing concerns that an API Gateway solves.
-
-#### 3. Bespoke API Gateway
-
-**Pros**: Custom-built for our exact needs, no license costs  
-**Cons**: Development and maintenance overhead, feature gaps, opportunity cost
-
-Building our own gateway would divert significant resources from our core business and likely result in a less robust solution than established products.
-
-#### 4. Alternative Gateway Products (Apigee, AWS API Gateway)
-
-**Pros**: Managed services (reduced operational burden), rich feature sets  
-**Cons**: Higher costs, potential vendor lock-in, less customization
-
-These were viable alternatives, but Kong offered the best balance of features, flexibility, and cost for our requirements.
-
-### References
-
-1. Richardson, Chris. "Pattern: API Gateway / Backends for Frontends." [Microservices.io](https://microservices.io/patterns/apigateway.html)
-2. Fowler, Martin. "BFF: Backend for Frontend." [martinfowler.com](https://martinfowler.com/articles/gateway-pattern.html)
-3. [Kong API Gateway Documentation](https://docs.konghq.com/)
-4. Newman, Sam. Building Microservices (O'Reilly)
-5. API Gateway Pattern, Microsoft Azure Architecture Center. [Microsoft Docs](https://docs.microsoft.com/en-us/azure/architecture/microservices/design/gateway)
-
-### Decision Record History
-
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2024-05-15 | 0.1 | Initial draft | James Wilson |
-| 2024-05-25 | 0.2 | Added implementation phases and alternatives | Sarah Chen |
-| 2024-06-05 | 0.3 | Incorporated feedback from architecture review | David Boyne |
-| 2024-06-10 | 1.0 | Approved by Architecture Board | Architecture Board |
-
-## Appendix A: API Gateway Architecture
-
-```mermaid
-flowchart TB
-    subgraph "External Clients"
-        web[Web Application]
-        mobile[Mobile Apps]
-        partners[Partner Systems]
-    end
-
-    subgraph "API Layer"
-        gateway[Kong API Gateway]
-        style gateway fill:#b9e0a5,stroke:#333,stroke-width:2px
-        auth[Auth Service]
-        gateway <--> auth
-    end
-
-    subgraph "Backend Services"
-        products[Product Service]
-        orders[Order Service]
-        inventory[Inventory Service]
-        pricing[Pricing Service]
-        users[User Service]
-        recommendations[Recommendation Service]
-    end
-
-    web --> gateway
-    mobile --> gateway
-    partners --> gateway
-    
-    gateway --> products
-    gateway --> orders
-    gateway --> inventory
-    gateway --> pricing
-    gateway --> users
-    gateway --> recommendations
-```
-
-## Appendix B: Gateway Policy Application Flow
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant Gateway as API Gateway
-    participant Auth as Authentication Service
-    participant Service as Backend Service
-    
-    Client->>Gateway: API Request
-    
-    Gateway->>Gateway: Apply Rate Limiting
-    Note over Gateway: Check quota and rate limits
-    
-    Gateway->>Auth: Validate Token
-    Auth-->>Gateway: Token Valid/Invalid
-    
-    alt Token Valid
-        Gateway->>Gateway: Apply Request Transformation
-        Gateway->>Service: Forward Request
-        Service-->>Gateway: Service Response
-        Gateway->>Gateway: Apply Response Transformation
-        Gateway->>Gateway: Apply Caching Headers
-        Gateway-->>Client: Transformed Response
-    else Token Invalid
-        Gateway-->>Client: 401 Unauthorized
-    end
-```
-
-## Appendix C: Gateway Feature Rollout
-
-| Feature | Target Date | Priority | Dependencies | Owner |
-|---------|-------------|----------|--------------|-------|
-| Basic Routing | Q2 2024 | Critical | Gateway Infrastructure | DevOps Team |
-| Authentication | Q2 2024 | Critical | Auth Service | Security Team |
-| Monitoring & Logging | Q2 2024 | High | Observability Platform | DevOps Team |
-| Rate Limiting | Q3 2024 | High | None | Platform Team |
-| Request/Response Transformation | Q3 2024 | Medium | API Standards | API Team |
-| Circuit Breaking | Q3 2024 | Medium | Service Health Metrics | Platform Team |
-| Caching | Q3 2024 | Medium | Cache Invalidation Strategy | Performance Team |
-| GraphQL Support | Q4 2024 | Low | GraphQL Schema | API Team |
-| Advanced Analytics | Q4 2024 | Low | Data Platform | Data Team | 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/architecture-decision-records/published/02-eda-adoption.mdx b/examples/default/docs/technical-architecture-design/architecture-decision-records/published/02-eda-adoption.mdx
deleted file mode 100644
index 187a322e7..000000000
--- a/examples/default/docs/technical-architecture-design/architecture-decision-records/published/02-eda-adoption.mdx
+++ /dev/null
@@ -1,290 +0,0 @@
----
-title: Event-driven architecture adoption
-summary: A document that captures important architectural decisions and their context
-sidebar:
-    label: EDA Adoption
-    order: 2
----
-
-## ADR-001: Adoption of Event-Driven Architecture for FlowMart E-commerce Platform
-
-### Status
-
-Approved (2024-07-15)
-
-### Context
-
-FlowMart is building a new e-commerce platform to replace our legacy monolithic application. The current system faces several challenges:
-
-1. **Scalability Issues**: During peak shopping periods (e.g., Black Friday, holiday season), the system struggles to handle increased traffic, resulting in degraded performance and occasional outages.
-2. **Maintenance Complexity**: Adding new features or modifying existing ones requires extensive regression testing and often leads to unexpected side effects.
-3. **Technology Constraints**: The monolithic architecture limits our ability to adopt new technologies or update components independently.
-4. **Data Consistency**: Ensuring data consistency across different parts of the application has become increasingly difficult.
-5. **Team Independence**: Multiple development teams working on different aspects of the application frequently block each other.
-
-We need an architecture that addresses these challenges while enabling rapid innovation and scaling to meet our projected growth over the next 3-5 years.
-
-### Decision
-
-We will adopt an **Event-Driven Architecture (EDA)** using a microservices approach for the new FlowMart e-commerce platform. Specifically:
-
-1. **Domain-Driven Design (DDD)**: We will organize our services around business domains (Orders, Inventory, Payment, Shipping, etc.) with clearly defined bounded contexts.
-
-2. **Event Sourcing**: Critical business transactions will be stored as a sequence of immutable events that can be used to reconstruct the system state at any point in time.
-
-3. **Command Query Responsibility Segregation (CQRS)**: We will separate read and write operations where appropriate to optimize for different performance and scaling requirements.
-
-4. **Apache Kafka** will serve as our primary event streaming platform for asynchronous communication between services.
-
-5. **Eventual Consistency Model**: We acknowledge that the system will prioritize availability and partition tolerance over immediate consistency (following the CAP theorem), with mechanisms to ensure eventual consistency.
-
-6. **Service Autonomy**: Each service will:
-   - Have its own database
-   - Be independently deployable
-   - Have well-defined APIs and event contracts
-   - Be responsible for publishing domain events when state changes occur
-
-7. **Choreography Over Orchestration**: Services will primarily react to events rather than being orchestrated by a central coordinator, though we will use orchestration for complex workflows when necessary.
-
-### Consequences
-
-#### Positive
-
-1. **Improved Scalability**: Individual services can scale independently based on demand, allowing us to allocate resources more efficiently.
-
-2. **Better Fault Isolation**: Failures in one service are less likely to cascade across the entire system, improving overall reliability.
-
-3. **Technology Flexibility**: Teams can choose the most appropriate technologies for their specific domains, allowing for incremental adoption of new technologies.
-
-4. **Team Autonomy**: Domain-aligned teams can develop, test, and deploy their services independently, reducing cross-team dependencies.
-
-5. **Enhanced Auditability**: Event sourcing provides a complete audit trail of all system changes, which is valuable for debugging, compliance, and business analytics.
-
-6. **Improved Extensibility**: New capabilities can be added by creating new consumers of existing events without modifying the original producers.
-
-#### Negative
-
-1. **Increased Complexity**: Distributed systems are inherently more complex to develop, test, debug, and operate compared to monolithic applications.
-
-2. **Learning Curve**: The team will need to learn new patterns, technologies, and operational practices, which may slow initial development.
-
-3. **Eventual Consistency Challenges**: Business operations and UI design must account for data that might not be immediately consistent across services.
-
-4. **Operational Overhead**: Managing multiple services, event streams, and databases requires more sophisticated monitoring, deployment, and operational tools.
-
-5. **Transaction Management**: Ensuring transactional integrity across service boundaries requires careful design and implementation of compensation patterns.
-
-6. **Testing Complexity**: End-to-end testing becomes more challenging, requiring new testing strategies and tools.
-
-### Compliance Requirements
-
-Our implementation must adhere to the following requirements:
-
-1. **Data Privacy**: Personal customer data must be handled in compliance with GDPR, CCPA, and other applicable regulations.
-
-2. **PCI DSS**: Payment processing components must comply with Payment Card Industry Data Security Standards.
-
-3. **Audit Trail**: All critical business transactions must be traceable and auditable for a minimum of 7 years.
-
-4. **Security**: Authentication, authorization, and data encryption standards must be consistently applied across all services.
-
-### Implementation Details
-
-#### Phase 1: Core Domain Decomposition (Q3 2024)
-
-1. Identify and define core domain boundaries
-2. Establish event schemas and contracts
-3. Implement Kafka infrastructure and operational tooling
-4. Migrate the first domain (Orders) to the new architecture
-5. Set up CI/CD pipelines and monitoring
-
-#### Phase 2: Domain Expansion (Q4 2024)
-
-1. Migrate Inventory and Payment domains
-2. Implement event sourcing for critical domains
-3. Develop read models for reporting and analytics
-4. Establish cross-domain consistency patterns
-
-#### Phase 3: Legacy Decommissioning (Q1-Q2 2025)
-
-1. Migrate remaining domains
-2. Implement advanced monitoring and alerting
-3. Gradually decommission legacy system components
-4. Complete performance tuning and optimization
-
-### Considered Alternatives
-
-#### 1. Modular Monolith
-
-**Pros**: Simpler development model, transactional integrity, easier testing  
-**Cons**: Limited independent scaling, technology constraints, deployment coupling
-
-This approach would address some concerns (maintainability, modularity) but would not solve our scalability and team independence challenges.
-
-#### 2. Microservices with REST-only Communication
-
-**Pros**: Well-understood patterns, synchronous communication simplicity  
-**Cons**: Tighter coupling, limited resilience, cascading failures
-
-This approach would improve modularity but would not adequately address resilience and scalability concerns.
-
-#### 3. Serverless Architecture
-
-**Pros**: Minimal infrastructure management, high elasticity, pay-per-use model  
-**Cons**: Vendor lock-in, cold start latency, limited control over infrastructure
-
-While appealing for certain scenarios, this approach would not provide the control and predictability needed for our core business functions.
-
-### References
-
-1. Building Event-Driven Microservices (Adam Bellemare, O'Reilly)
-2. Domain-Driven Design (Eric Evans, Addison-Wesley)
-3. Enterprise Integration Patterns (Gregor Hohpe, Bobby Woolf, Addison-Wesley)
-4. [Kafka Documentation](https://kafka.apache.org/documentation/)
-5. [CQRS Pattern](https://martinfowler.com/bliki/CQRS.html) (Martin Fowler)
-6. [Event Sourcing Pattern](https://martinfowler.com/eaaDev/EventSourcing.html) (Martin Fowler)
-
-### Decision Record History
-
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2024-06-22 | 0.1 | Initial draft | David Boyne |
-| 2024-06-30 | 0.2 | Incorporate feedback from architecture review | Amy Smith |
-| 2024-07-10 | 0.3 | Added implementation phasing and compliance requirements | Kiran Patel |
-| 2024-07-15 | 1.0 | Approved by Architecture Board | Architecture Board |
-
-## Appendix A: High-Level Architecture Diagram
-
-```mermaid
-flowchart TB
-    subgraph "API Gateway"
-        gw[API Gateway]
-    end
-
-    subgraph "Customer Domain"
-        cust[Customer Service]
-        auth[Authentication Service]
-    end
-
-    subgraph "Order Domain"
-        order[Order Service]
-        orderhist[Order History Service]
-    end
-
-    subgraph "Inventory Domain"
-        inv[Inventory Service]
-        stock[Stock Management]
-    end
-
-    subgraph "Payment Domain"
-        payment[Payment Service]
-        refund[Refund Service]
-    end
-
-    subgraph "Shipping Domain"
-        ship[Shipping Service]
-        track[Tracking Service]
-    end
-
-    subgraph "Event Backbone"
-        kafka[Apache Kafka]
-    end
-
-    gw --> order
-    gw --> cust
-    gw --> auth
-    gw --> inv
-    gw --> payment
-    gw --> ship
-    gw --> track
-
-    order --> kafka
-    cust --> kafka
-    inv --> kafka
-    payment --> kafka
-    ship --> kafka
-    track --> kafka
-
-    kafka --> orderhist
-    kafka --> stock
-    kafka --> refund
-```
-
-## Appendix B: Key Event Flows
-
-### Order Placement Flow
-
-```mermaid
-sequenceDiagram
-    participant C as Customer
-    participant OS as Order Service
-    participant IS as Inventory Service
-    participant PS as Payment Service
-    participant SS as Shipping Service
-    participant NS as Notification Service
-
-    C->>OS: Place Order
-    OS->>IS: Check Inventory
-    IS-->>OS: Inventory Available
-    OS->>PS: Process Payment
-    PS-->>OS: Payment Approved
-    OS->>OS: Create Order
-    OS->>+kafka: Publish OrderCreated
-    kafka->>IS: OrderCreated
-    IS->>IS: Reserve Inventory
-    IS->>kafka: Publish InventoryReserved
-    kafka->>SS: InventoryReserved
-    SS->>SS: Create Shipment
-    SS->>kafka: Publish ShipmentCreated
-    kafka->>NS: ShipmentCreated
-    NS->>C: Send Order Confirmation
-```
-
-### Out-of-Stock Handling Flow
-
-```mermaid
-sequenceDiagram
-    participant IS as Inventory Service
-    participant K as Kafka
-    participant NS as Notification Service
-    participant RS as Replenishment Service
-    participant OS as Order Service
-    participant CS as Customer
-
-    IS->>IS: Stock level check
-    IS->>+K: Publish OutOfStockEvent
-    K->>NS: OutOfStockEvent
-    K->>RS: OutOfStockEvent
-    K->>OS: OutOfStockEvent
-    
-    NS->>CS: Send out-of-stock notification
-    RS->>RS: Create replenishment order
-    RS->>+K: Publish ReplenishmentOrderedEvent
-    OS->>OS: Update product availability
-    OS->>CS: Show "Notify when available" option
-
-    note over RS,IS: After stock is replenished
-    RS->>IS: Restock inventory
-    IS->>+K: Publish InventoryRestockedEvent
-    K->>NS: InventoryRestockedEvent
-    K->>OS: InventoryRestockedEvent
-    
-    NS->>CS: Send back-in-stock notification
-    OS->>OS: Update product availability
-```
-
-## Appendix C: Service Ownership
-
-| Domain | Service | Team |
-|--------|---------|------|
-| Customer | Customer Service | Full Stack Team |
-| Customer | Authentication Service | Security Team |
-| Order | Order Service | Order Management Team |
-| Order | Order History Service | Order Management Team |
-| Inventory | Inventory Service | Full Stack Team |
-| Inventory | Stock Management | Full Stack Team |
-| Payment | Payment Service | Payment Team |
-| Payment | Refund Service | Payment Team |
-| Shipping | Shipping Service | Logistics Team |
-| Shipping | Tracking Service | Logistics Team |
-
diff --git a/examples/default/docs/technical-architecture-design/architecture-decision-records/published/03-auth-strategy.mdx b/examples/default/docs/technical-architecture-design/architecture-decision-records/published/03-auth-strategy.mdx
deleted file mode 100644
index 20c916065..000000000
--- a/examples/default/docs/technical-architecture-design/architecture-decision-records/published/03-auth-strategy.mdx
+++ /dev/null
@@ -1,296 +0,0 @@
----
-title: Authentication and Authorization Strategy
-summary: Architectural decision record for implementing authentication and authorization for the FlowMart e-commerce platform
-sidebar:
-    label: Auth Strategy
-    order: 3
----
-
-## ADR-003: Authentication and Authorization Strategy for FlowMart E-commerce Platform
-
-### Status
-
-Approved (2024-08-01)
-
-### Context
-
-As we move to a microservices architecture for our e-commerce platform, we need a robust, scalable, and secure approach to authentication and authorization. The current monolithic application uses a custom auth solution with session-based authentication, which presents several challenges in a distributed environment:
-
-1. **Session Stickiness**: Requires load balancer configuration to route users to the same server.
-2. **Scalability Constraints**: Session state storage becomes challenging as we scale horizontally.
-3. **Cross-Service Authentication**: No standardized way for services to validate user identity and permissions.
-4. **Partner and Third-Party Integration**: Difficult to securely expose APIs to external systems.
-5. **Multiple Authentication Factors**: Need to support various authentication methods (passwords, social logins, biometrics).
-6. **Varying Authorization Requirements**: Different resources require different permission models.
-7. **Compliance Requirements**: GDPR, PCI-DSS, and industry regulations impose strict requirements on handling authentication data.
-
-We need an authentication and authorization strategy that works effectively in a distributed microservices environment while maintaining high security standards.
-
-### Decision
-
-We will implement a token-based authentication and authorization strategy using **OAuth 2.0** and **OpenID Connect (OIDC)** standards with **Auth0** as our identity provider. Specifically:
-
-1. **Authentication Pattern**:
-   - **JWT (JSON Web Tokens)** for representing claims between parties
-   - **Stateless authentication** where possible to improve scalability
-   - **OAuth 2.0 Authorization Code Flow with PKCE** for web applications
-   - **OAuth 2.0 Resource Owner Password Grant** (limited to legacy/internal applications)
-   - **OAuth 2.0 Client Credentials Grant** for service-to-service communication
-
-2. **Authorization Pattern**:
-   - **Role-Based Access Control (RBAC)** as the primary mechanism for coarse-grained permissions
-   - **Attribute-Based Access Control (ABAC)** for fine-grained access decisions
-   - **Policy Enforcement Points (PEP)** implemented at the API Gateway level for common policies
-   - **Service-level authorization** for domain-specific access control
-
-3. **User Management**:
-   - Centralized user directory in Auth0
-   - Self-service user registration and profile management
-   - Admin-managed role assignments and permissions
-   - Progressive profiling to collect user information gradually
-
-4. **Multi-Factor Authentication (MFA)**:
-   - Required for administrative accounts and sensitive operations
-   - Optional but encouraged for standard user accounts
-   - Risk-based authentication triggers (unusual location, device, behavior)
-
-5. **Service-to-Service Authentication**:
-   - Mutual TLS (mTLS) for service mesh communication
-   - Client credentials OAuth flow with short-lived tokens for cross-boundary requests
-
-6. **API Security**:
-   - Token validation at the API Gateway
-   - Scoped access tokens for limiting API permissions
-   - Token introspection for high-security operations
-
-### Consequences
-
-#### Positive
-
-1. **Improved Scalability**: Stateless authentication allows for better horizontal scaling without session replication.
-
-2. **Standardized Security**: Using established security protocols (OAuth 2.0/OIDC) provides well-tested security patterns.
-
-3. **Reduced Development Burden**: Auth0 handles many security concerns (token issuance, validation, revocation, etc.).
-
-4. **Flexible Integration**: Easier to integrate with third-party systems and identity providers.
-
-5. **Centralized Policy Management**: Authorization policies can be managed centrally and applied consistently.
-
-6. **Enhanced User Experience**: Support for modern authentication patterns (social login, passwordless, etc.).
-
-7. **Compliance Support**: Built-in features for consent management, audit logging, and other compliance requirements.
-
-#### Negative
-
-1. **Increased Complexity**: More moving parts in the authentication flow compared to simple session-based auth.
-
-2. **Token Management Overhead**: Need to handle token lifecycle, refresh, and invalidation carefully.
-
-3. **External Dependency**: Reliance on Auth0 as a critical service and potential single point of failure.
-
-4. **Performance Considerations**: Token validation and policy evaluation add some latency to requests.
-
-5. **Cost**: Subscription fees for Auth0 based on active users and features used.
-
-6. **Learning Curve**: Team needs to understand OAuth 2.0 flows and token-based authentication patterns.
-
-### Mitigation Strategies
-
-1. **Caching and Performance Optimization**:
-   - Implement efficient token validation with local caching
-   - Use token introspection only when necessary
-   - Optimize policy evaluation paths
-
-2. **Resilience Planning**:
-   - Implement graceful degradation if Auth0 is temporarily unavailable
-   - Consider a multi-region Auth0 deployment for critical workloads
-   - Regular disaster recovery testing
-
-3. **Security Hardening**:
-   - Set appropriate token lifetimes (shorter for sensitive operations)
-   - Implement proper token storage in clients (secure cookies, encrypted storage)
-   - Regular security reviews and penetration testing
-
-4. **Developer Experience**:
-   - Create SDKs and libraries to abstract authentication complexity
-   - Comprehensive documentation and training
-   - Authentication dev sandbox environment
-
-### Implementation Details
-
-#### Phase 1: Core Authentication Infrastructure (Q3 2024)
-
-1. Set up Auth0 tenant and configure core settings
-2. Implement login, registration, and password reset flows
-3. Migrate existing user accounts (passwords securely hashed)
-4. Integrate with API Gateway for token validation
-5. Set up basic roles and permissions
-
-#### Phase 2: Advanced Authorization (Q4 2024)
-
-1. Implement fine-grained ABAC policies
-2. Develop centralized policy management tools
-3. Set up delegated administration capabilities
-4. Implement audit logging and monitoring
-5. Configure MFA for administrative accounts
-
-#### Phase 3: Partner and Integration Capabilities (Q1 2025)
-
-1. Implement client credentials for service-to-service
-2. Set up partner authentication portal
-3. Configure rate limiting and throttling
-4. Implement token exchange capabilities
-5. Set up public developer documentation
-
-### Considered Alternatives
-
-#### 1. Custom Authentication Solution
-
-**Pros**: Complete control, no external dependencies, potentially lower direct costs  
-**Cons**: Development time, security risks, maintenance burden, limited features
-
-Building our own solution would require significant security expertise and ongoing maintenance, with higher risk of vulnerabilities.
-
-#### 2. Keycloak (Open Source Identity Provider)
-
-**Pros**: Open source, flexible, no subscription fees, self-hosted control  
-**Cons**: Operational overhead, scalability challenges, fewer integrations
-
-Keycloak would reduce subscription costs but increase operational complexity and require more internal expertise.
-
-#### 3. AWS Cognito
-
-**Pros**: Tight AWS integration, managed service, good scalability  
-**Cons**: Less flexible than Auth0, fewer enterprise features, AWS lock-in
-
-Cognito would be suitable if we were fully committed to AWS, but we needed more flexibility for our multi-cloud strategy.
-
-#### 4. Session-Based Authentication with Distributed Cache
-
-**Pros**: Simpler architecture, familiar pattern, less paradigm shift  
-**Cons**: Scalability challenges, higher operational complexity, less standardized
-
-This would maintain our current approach but with scalability improvements, though it wouldn't address many of our requirements.
-
-### Standards Compliance
-
-Our implementation will comply with the following standards and regulations:
-
-1. **OAuth 2.0 (RFC 6749)**: The authorization framework
-2. **OpenID Connect 1.0**: Identity layer on top of OAuth 2.0
-3. **JWT (RFC 7519)**: Compact token format
-4. **GDPR**: For EU user data protection
-5. **PCI-DSS**: For payment-related authentication
-6. **NIST 800-63B**: Digital Identity Guidelines
-
-### References
-
-1. [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749)
-2. [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
-3. [Auth0 Architecture Scenarios](https://auth0.com/docs/architecture-scenarios)
-4. [JWT Introduction](https://jwt.io/introduction)
-5. Nate Barbettini, "OAuth 2.0 and OpenID Connect in Plain English" ([YouTube](https://www.youtube.com/watch?v=996OiexHze0))
-6. "API Security in Action" by Neil Madden (Manning Publications)
-
-### Decision Record History
-
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2024-07-01 | 0.1 | Initial draft | Elena Rodriguez |
-| 2024-07-15 | 0.2 | Added implementation phases and alternatives | Michael Chang |
-| 2024-07-25 | 0.3 | Incorporated security team feedback | Sarah Chen |
-| 2024-08-01 | 1.0 | Approved by Architecture and Security Boards | Architecture Board |
-
-## Appendix A: Authentication Flows
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant Client as Web/Mobile App
-    participant API as API Gateway
-    participant Auth0 as Auth0
-    participant Service as Microservice
-
-    %% Login Flow
-    User->>Client: Initiates Login
-    Client->>Auth0: Redirect to Auth0 (/authorize)
-    Auth0->>User: Present Login UI
-    User->>Auth0: Enter Credentials
-    opt MFA Triggered
-        Auth0->>User: Request Second Factor
-        User->>Auth0: Provide Second Factor
-    end
-    Auth0->>Client: Authorization Code
-    Client->>Auth0: Exchange Code for Tokens
-    Auth0->>Client: Access Token, ID Token, Refresh Token
-    
-    %% API Access Flow
-    Client->>API: Request with Access Token
-    API->>API: Validate Token
-    API->>Service: Forward Request + Claims
-    Service->>Service: Check Authorization
-    Service->>API: Response
-    API->>Client: Response
-    
-    %% Token Refresh
-    Note over Client: When Access Token Expires
-    Client->>Auth0: Request with Refresh Token
-    Auth0->>Client: New Access Token
-```
-
-## Appendix B: Authorization Model
-
-```mermaid
-flowchart TB
-    subgraph "Authorization Layers"
-        direction TB
-        
-        subgraph "Layer 1: Authentication"
-            auth[User Authentication]
-            token[Token Issuance]
-        end
-        
-        subgraph "Layer 2: Coarse Authorization"
-            rbac[Role-Based Access Control]
-            scopes[OAuth Scopes]
-        end
-        
-        subgraph "Layer 3: Fine Authorization"
-            abac[Attribute-Based Policies]
-            biz[Business Rules]
-        end
-    end
-    
-    subgraph "Enforcement Points"
-        gateway[API Gateway]
-        services[Microservices]
-    end
-    
-    auth --> token
-    token --> rbac
-    token --> scopes
-    rbac --> abac
-    scopes --> abac
-    abac --> biz
-    
-    rbac --> gateway
-    scopes --> gateway
-    abac --> gateway
-    biz --> services
-    
-    gateway --> services
-```
-
-## Appendix C: Role and Permission Mapping
-
-| Role | Description | Permissions | MFA Required |
-|------|-------------|------------|--------------|
-| Anonymous | Unauthenticated user | Browse catalog, View public content | No |
-| Customer | Registered shopper | Place orders, Manage profile, Write reviews | Optional |
-| Premium Customer | Paid tier customer | Customer + Early access, Special discounts | Optional |
-| Customer Service | Support staff | View orders, Issue refunds, Update customer info | Yes |
-| Store Manager | Retail location manager | Customer Service + Inventory management, Staff management | Yes |
-| Admin | System administrator | All permissions | Yes |
-| API Partner | External system | Specific API access based on agreement | No (mTLS) |
-| Service Account | Internal service | Specific service-to-service communication | No (mTLS) | 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/architecture-decision-records/published/04-database-strategy.mdx b/examples/default/docs/technical-architecture-design/architecture-decision-records/published/04-database-strategy.mdx
deleted file mode 100644
index 4dc39480c..000000000
--- a/examples/default/docs/technical-architecture-design/architecture-decision-records/published/04-database-strategy.mdx
+++ /dev/null
@@ -1,363 +0,0 @@
----
-title: Database Strategy for Microservices
-summary: Architectural decision record for database selection and data management in the FlowMart e-commerce platform
-sidebar:
-    label: Database Strategy
-    order: 4
----
-
-## ADR-004: Database Strategy for Microservices in FlowMart E-commerce Platform
-
-### Status
-
-Approved (2024-08-20)
-
-### Context
-
-Our transition from a monolithic architecture to microservices necessitates a reassessment of our database strategy. The existing monolithic application uses a centralized Oracle database with hundreds of tables spanning multiple business domains. This approach has created several challenges:
-
-1. **Schema Coupling**: Changes to database schemas require careful coordination across teams to avoid breaking dependent services.
-2. **Scalability Limitations**: The relational database becomes a bottleneck during high-traffic periods, affecting all application features.
-3. **One-Size-Fits-All Approach**: Different data access patterns are all forced into the same relational model, leading to suboptimal performance.
-4. **Operational Overhead**: Database administration is complex due to competing requirements from different application components.
-5. **Development Bottlenecks**: Teams must coordinate database changes, slowing down development velocity.
-6. **Cost Efficiency**: The enterprise database licensing model is expensive and doesn't scale cost-effectively with our varying workloads.
-
-As we decompose our application into microservices, we need a database strategy that promotes service autonomy while ensuring data consistency, performance, and operational efficiency.
-
-### Decision
-
-We will adopt a **polyglot persistence strategy** for our microservices architecture, following the principle of "right database for the right job." Key aspects of this strategy include:
-
-1. **Database-per-Service Pattern**:
-   - Each microservice will own and exclusively manage its database
-   - No direct database access from other services
-   - Services interact via well-defined APIs, not shared databases
-
-2. **Primary Database Technologies**:
-   - **PostgreSQL**: Primary relational database for services with complex transactional requirements
-   - **MongoDB**: Document database for services with flexible schema requirements and read-heavy workloads
-   - **Redis**: In-memory data store for caching, session management, and real-time features
-   - **Elasticsearch**: Search engine for product catalog and content search
-   - **Apache Cassandra**: Wide-column store for high-volume time-series data and analytics
-   - **Amazon DynamoDB**: Managed NoSQL for highly scalable microservices with predictable access patterns
-
-3. **Data Consistency Patterns**:
-   - **Saga Pattern**: For coordinating transactions across multiple services
-   - **Event Sourcing**: For critical business domains requiring complete audit trails
-   - **CQRS**: For services with asymmetric read/write loads
-   - **Outbox Pattern**: For reliable event publishing during state changes
-
-4. **Data Migration and Evolution**:
-   - Versioned database schemas
-   - Backward-compatible schema changes
-   - Blue/green deployment for database changes
-   - Incremental data migration approach
-
-5. **Data Governance**:
-   - Centralized data catalog and lineage tracking
-   - Common data models for shared business entities
-   - Standard approach to master data management
-   - Automated data quality monitoring
-
-6. **Operational Excellence**:
-   - Infrastructure as Code (IaC) for all database resources
-   - Automated backup and recovery procedures
-   - Standardized monitoring and alerting
-   - Database reliability engineering practices
-
-### Database Selection Criteria by Domain
-
-| Domain | Database Type | Primary Factors | Secondary Considerations |
-|--------|---------------|-----------------|--------------------------|
-| Product Catalog | MongoDB + Elasticsearch | Schema flexibility, Search capabilities | High read-to-write ratio, Caching |
-| Order Management | PostgreSQL | ACID transactions, Complex queries | Event sourcing for audit trail |
-| Customer Profile | PostgreSQL | Data consistency, Relational integrity | Privacy compliance, Scalable reads |
-| Inventory | MongoDB | Frequent schema evolution, High write throughput | Eventual consistency model |
-| Cart & Checkout | Redis + PostgreSQL | Low latency, High availability | Transaction support for checkout |
-| Payment Processing | PostgreSQL | Strong consistency, Transaction support | Compliance requirements, Security |
-| Analytics | Cassandra | High write throughput, Time-series data | Analytical query patterns |
-| Recommendations | Redis + MongoDB | Low latency reads, Flexible data model | Machine learning feature support |
-| User Sessions | Redis | Ultra-low latency, Expiration support | High availability, Cross-region replication |
-| Content Management | MongoDB | Flexible schema, Document structure | Full-text search capability |
-
-### Consequences
-
-#### Positive
-
-1. **Service Autonomy**: Teams can independently select, optimize, and evolve their databases without cross-team coordination.
-
-2. **Optimized Performance**: Each service can use a database technology optimized for its specific data access patterns.
-
-3. **Independent Scaling**: Database resources can be scaled according to the specific needs of each service.
-
-4. **Improved Resilience**: Database failures are isolated to specific services rather than affecting the entire system.
-
-5. **Fit-for-Purpose Solutions**: Different data models (relational, document, key-value, etc.) can be applied where most appropriate.
-
-6. **Cost Optimization**: Resources can be allocated based on the specific needs of each service.
-
-7. **Incremental Adoption**: New database technologies can be introduced for new services without migrating legacy data.
-
-#### Negative
-
-1. **Increased Operational Complexity**: Managing multiple database technologies requires broader expertise and more sophisticated tooling.
-
-2. **Data Consistency Challenges**: Maintaining consistency across service boundaries requires careful design and implementation.
-
-3. **Learning Curve**: Development teams need to learn multiple database technologies and data access patterns.
-
-4. **Distributed Transactions**: Business processes spanning multiple services require more complex transaction management.
-
-5. **Increased Infrastructure Costs**: Running and maintaining multiple database systems may increase overall infrastructure costs.
-
-6. **Data Duplication**: Some data may need to be duplicated across services, creating synchronization challenges.
-
-7. **Monitoring and Troubleshooting Complexity**: Different databases require different monitoring approaches and expertise.
-
-### Mitigation Strategies
-
-1. **Platform Database Service**:
-   - Create an internal platform team that provides database-as-a-service capabilities
-   - Standardize on a limited set of supported database technologies
-   - Provide automated provisioning, backup, and monitoring
-
-2. **Data Access Layer Pattern**:
-   - Create standardized libraries for common database access patterns
-   - Abstract database-specific details behind consistent interfaces
-   - Implement retry logic, circuit breakers, and observability
-
-3. **Data Synchronization Framework**:
-   - Implement a standardized approach to CDC (Change Data Capture)
-   - Create reusable components for the Outbox Pattern
-   - Develop standard data synchronization workflows
-
-4. **Database Reliability Engineering**:
-   - Establish dedicated database reliability engineers
-   - Create runbooks for common database operations
-   - Implement chaos engineering practices for database failure testing
-
-5. **Developer Training and Support**:
-   - Comprehensive training program for supported database technologies
-   - Internal knowledge base and best practice documentation
-   - Database design review process for new services
-
-### Implementation Details
-
-#### Phase 1: Foundation (Q3-Q4 2024)
-
-1. Establish database platform team and core services
-2. Set up standard PostgreSQL and MongoDB offerings
-3. Implement database CI/CD pipelines
-4. Develop initial monitoring and alerting
-5. Create database provisioning automation
-
-#### Phase 2: Expansion (Q1-Q2 2025)
-
-1. Add Redis and Elasticsearch to supported offerings
-2. Implement data synchronization framework
-3. Develop CQRS and Event Sourcing patterns
-4. Create data governance tooling
-5. Expand monitoring capabilities
-
-#### Phase 3: Advanced Capabilities (Q3-Q4 2025)
-
-1. Add Cassandra and specialized databases
-2. Implement advanced high availability features
-3. Develop cross-region replication capabilities
-4. Create advanced analytics integration
-5. Implement predictive scaling and optimization
-
-### Considered Alternatives
-
-#### 1. Shared Database Approach
-
-**Pros**: Simplicity, familiar model, transactional integrity, easier reporting  
-**Cons**: Tight coupling, scalability limitations, schema coordination challenges
-
-This approach would minimize short-term changes but would recreate many of the current issues in our new architecture.
-
-#### 2. Single Database Technology (PostgreSQL Only)
-
-**Pros**: Operational simplicity, consistent expertise, familiar tooling  
-**Cons**: Not optimal for all workloads, potential performance compromises
-
-While PostgreSQL is versatile, it isn't the best choice for all our diverse data requirements.
-
-#### 3. Database-as-a-Service Only (e.g., AWS RDS/DynamoDB)
-
-**Pros**: Reduced operational overhead, managed scaling, built-in high availability  
-**Cons**: Vendor lock-in, potential cost concerns, less flexibility
-
-While we'll use managed services where appropriate, we need the flexibility to run certain databases on our own infrastructure.
-
-#### 4. Fully Centralized Data Lake Approach
-
-**Pros**: Centralized analytics, simplified data governance, consistent data model  
-**Cons**: Complex real-time synchronization, potential performance issues, development overhead
-
-This approach works well for analytics but isn't suitable for operational data needs.
-
-### References
-
-1. Kleppmann, Martin. "Designing Data-Intensive Applications" (O'Reilly Media)
-2. Vernon, Vaughn. "Implementing Domain-Driven Design" (Addison-Wesley)
-3. Fowler, Martin. "PolyglotPersistence" [martinfowler.com](https://martinfowler.com/bliki/PolyglotPersistence.html)
-4. Richardson, Chris. "Microservices Patterns" (Manning Publications)
-5. [Database per Service Pattern](https://microservices.io/patterns/data/database-per-service.html)
-6. [Saga Pattern](https://microservices.io/patterns/data/saga.html)
-
-### Decision Record History
-
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2024-07-20 | 0.1 | Initial draft | Robert Kim |
-| 2024-08-02 | 0.2 | Added domain-specific database recommendations | Maria Garcia |
-| 2024-08-15 | 0.3 | Incorporated feedback from architecture review | David Boyne |
-| 2024-08-20 | 1.0 | Approved by Architecture Board | Architecture Board |
-
-## Appendix A: Database Architecture Overview
-
-```mermaid
-flowchart TB
-    subgraph "Service Domains"
-        subgraph "Product Domain"
-            pc[Product Catalog]
-            ps[Product Search]
-            pc --- MongoDB
-            ps --- Elasticsearch
-        end
-        
-        subgraph "Order Domain"
-            om[Order Management]
-            oh[Order History]
-            om --- PostgreSQL
-            oh --- MongoDB
-        end
-        
-        subgraph "Customer Domain"
-            cp[Customer Profile]
-            auth[Authentication]
-            sess[Sessions]
-            cp --- PostgreSQL
-            auth --- PostgreSQL
-            sess --- Redis
-        end
-        
-        subgraph "Inventory Domain"
-            inv[Inventory Management]
-            stk[Stock Tracking]
-            inv --- MongoDB
-            stk --- MongoDB
-        end
-        
-        subgraph "Payment Domain"
-            pay[Payment Processing]
-            tx[Transaction Ledger]
-            pay --- PostgreSQL
-            tx --- PostgreSQL
-        end
-        
-        subgraph "Analytics Domain"
-            metrics[Metrics Collection]
-            reports[Reporting]
-            metrics --- Cassandra
-            reports --- Elasticsearch
-        end
-    end
-    
-    subgraph "Data Integration"
-        ksql[KSQL]
-        cdc[CDC Connectors]
-        etl[ETL Processes]
-        
-        Kafka --> ksql
-        cdc --> Kafka
-        ksql --> etl
-    end
-    
-    MongoDB --> cdc
-    PostgreSQL --> cdc
-    Cassandra --> cdc
-    
-    etl --> DataLake
-```
-
-## Appendix B: Data Consistency Patterns by Service Type
-
-```mermaid
-flowchart TB
-    subgraph "Data Consistency Patterns"
-        direction TB
-        
-        subgraph "Transactional Services"
-            saga[Saga Pattern]
-            tcc[Try-Confirm/Cancel Pattern]
-            2pc[Two-Phase Commit]
-        end
-        
-        subgraph "Event-Driven Services"
-            es[Event Sourcing]
-            cqrs[CQRS]
-            outbox[Outbox Pattern]
-        end
-        
-        subgraph "Caching Patterns"
-            cache[Cache-Aside]
-            writeBehind[Write-Behind]
-            readThrough[Read-Through]
-        end
-    end
-    
-    subgraph "Service Examples"
-        checkout[Checkout Service]
-        inventory[Inventory Service]
-        catalog[Product Catalog]
-        recommendations[Recommendations]
-    end
-    
-    checkout --> saga
-    checkout --> 2pc
-    inventory --> es
-    inventory --> outbox
-    catalog --> cqrs
-    catalog --> cache
-    recommendations --> readThrough
-```
-
-## Appendix C: Database Migration Strategy
-
-```mermaid
-sequenceDiagram
-    participant Legacy as Legacy Database
-    participant Middleware as Migration Middleware
-    participant New as New Service Databases
-    participant CDC as Change Data Capture
-    participant Events as Event Bus
-    
-    Note over Legacy, Events: Phase 1: Shadow Reading
-    
-    Legacy->>Middleware: Original Data Access
-    Middleware->>New: Shadow Writes
-    
-    Note over Legacy, Events: Phase 2: Dual Write
-    
-    Legacy->>Middleware: Original Data Access
-    Middleware->>Legacy: Write to Legacy
-    Middleware->>New: Write to New System
-    
-    Note over Legacy, Events: Phase 3: CDC Migration
-    
-    Legacy->>CDC: Capture Changes
-    CDC->>Events: Publish Change Events
-    Events->>New: Update New System
-    
-    Note over Legacy, Events: Phase 4: Reverse Flow
-    
-    New->>Middleware: Primary Data Access
-    Middleware->>Legacy: Synchronize for Legacy Systems
-    
-    Note over Legacy, Events: Phase 5: Legacy Retirement
-    
-    New->>New: Fully Migrated Operations
-``` 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/architecture-decision-records/published/05-frontend-architecture.mdx b/examples/default/docs/technical-architecture-design/architecture-decision-records/published/05-frontend-architecture.mdx
deleted file mode 100644
index 89d36d343..000000000
--- a/examples/default/docs/technical-architecture-design/architecture-decision-records/published/05-frontend-architecture.mdx
+++ /dev/null
@@ -1,373 +0,0 @@
----
-title: Frontend Architecture
-summary: Architectural decision record for frontend architecture of the FlowMart e-commerce platform
-sidebar:
-    label: Frontend Architecture
-    order: 5
----
-
-## ADR-005: Frontend Architecture for FlowMart E-commerce Platform
-
-### Status
-
-Approved (2024-09-05)
-
-### Context
-
-The frontend of our current monolithic e-commerce application faces numerous challenges:
-
-1. **Performance Issues**: The current server-rendered application has slow page loads and poor mobile performance.
-2. **Developer Productivity**: Shared frontend codebase creates development bottlenecks and team dependencies.
-3. **Inconsistent User Experience**: Different parts of the application have divergent design patterns and interaction models.
-4. **Limited Reusability**: Components are tightly coupled to specific pages, making code reuse difficult.
-5. **Testing Challenges**: The current codebase has limited test coverage and is difficult to test effectively.
-6. **Technology Constraints**: Outdated technology stack limits our ability to leverage modern frontend capabilities.
-7. **Scalability Concerns**: Our current approach doesn't scale well with increasing development team size.
-8. **Mobile Experience**: The responsive web approach doesn't deliver optimal mobile experiences.
-
-As we transition to a microservices backend architecture, we need a complementary frontend strategy that addresses these challenges while supporting our business goals of improved customer experience, faster time-to-market, and technical agility.
-
-### Decision
-
-We will adopt a **modern, component-based frontend architecture** with the following key characteristics:
-
-1. **Micro-Frontend Approach**:
-   - Decompose the frontend into domain-aligned micro-frontends
-   - Enable independent development and deployment of frontend components
-   - Provide clear ownership boundaries aligned with backend microservices
-
-2. **Core Technology Stack**:
-   - **React**: Primary UI library for component development
-   - **Next.js**: Framework for server-rendering and static generation
-   - **TypeScript**: For type safety and improved developer experience
-   - **Styled Components**: For component-scoped styling
-   - **React Query**: For data fetching and state management
-   - **Cypress & React Testing Library**: For testing
-
-3. **Design System**:
-   - Create a comprehensive design system with reusable UI components
-   - Implement a living style guide and component documentation
-   - Establish design tokens for consistent theming
-   - Support multiple brands and white-labeling capabilities
-
-4. **Architecture Patterns**:
-   - **Module Federation**: For sharing components between micro-frontends
-   - **Composition Layer**: Shell application for integrating micro-frontends
-   - **BFF Pattern**: Backend-for-Frontend APIs for optimized data access
-   - **State Management**: Local state when possible, shared state when necessary
-   - **Feature Flags**: For controlled feature rollout and A/B testing
-
-5. **Performance Optimization**:
-   - Server-side rendering for initial page load performance
-   - Client-side rendering for rich interactive experiences
-   - Code splitting and lazy loading for optimized bundle sizes
-   - Aggressive caching strategies for static assets
-   - Optimized media delivery with responsive images and lazy loading
-
-6. **Mobile Strategy**:
-   - Progressive Web App (PWA) capabilities for mobile web
-   - Responsive design with mobile-first approach
-   - Native app shell with React Native for iOS/Android applications
-   - Shared business logic between web and native through abstraction layers
-
-### Frontend Domain Decomposition
-
-| Domain | Micro-Frontend | Primary Responsibilities | Team |
-|--------|---------------|--------------------------|------|
-| Product Discovery | product-browser | Product listing, search, filtering, recommendations | Catalog Team |
-| Product Details | product-details | Product information, options, reviews, related items | Catalog Team |
-| Shopping Cart | cart-experience | Cart management, saved items, quick checkout | Checkout Team |
-| Checkout | checkout-flow | Multi-step checkout, address management, payment | Checkout Team |
-| User Account | account-portal | Profile management, preferences, order history | Customer Team |
-| Content | content-pages | CMS-managed content, landing pages, promotional content | Marketing Team |
-| Store Locator | store-finder | Store search, maps integration, store details | Location Team |
-| Order Management | order-tracker | Order status, tracking, returns management | Order Team |
-
-### Consequences
-
-#### Positive
-
-1. **Improved Development Velocity**: Teams can work independently on their domains without blocking each other.
-
-2. **Better Performance**: Optimized loading strategies and modern frontend practices will improve user experience.
-
-3. **Enhanced Reusability**: Shared component library and design system enable consistent, reusable UI elements.
-
-4. **Independent Deployments**: Micro-frontends can be deployed independently, reducing release coordination.
-
-5. **Technology Flexibility**: Different domains can adopt new technologies at their own pace.
-
-6. **Better Testing**: Smaller, more focused codebases are easier to test thoroughly.
-
-7. **Improved User Experience**: Consistent design language and optimized interactions improve customer satisfaction.
-
-8. **Team Autonomy**: Clear ownership boundaries enable teams to take full responsibility for their domains.
-
-#### Negative
-
-1. **Increased Complexity**: Micro-frontend architectures add operational and integration complexity.
-
-2. **Learning Curve**: Teams need to adapt to new patterns and technologies.
-
-3. **Potential Duplication**: Without careful governance, similar solutions may be implemented multiple times.
-
-4. **Integration Challenges**: Ensuring consistent behavior across micro-frontends requires careful coordination.
-
-5. **Performance Overhead**: Micro-frontend composition can introduce additional runtime overhead if not carefully managed.
-
-6. **Increased Infrastructure Needs**: More sophisticated build, deployment, and monitoring infrastructure required.
-
-7. **Governance Challenges**: Balancing team autonomy with architectural consistency requires active governance.
-
-### Mitigation Strategies
-
-1. **Frontend Platform Team**:
-   - Create a dedicated platform team to provide shared infrastructure and tools
-   - Develop reusable patterns and documentation for micro-frontend implementation
-   - Provide developer tooling and simplified local development experience
-
-2. **Comprehensive Design System**:
-   - Invest in a robust design system with clear guidelines and components
-   - Create automated tools for design compliance checking
-   - Regular design system sessions to ensure alignment across teams
-
-3. **Performance Budgeting**:
-   - Establish clear performance metrics and budgets for each micro-frontend
-   - Automated performance testing in CI/CD pipeline
-   - Regular performance reviews and optimization workshops
-
-4. **Developer Experience**:
-   - Create standardized templates and generators for new micro-frontends
-   - Provide comprehensive documentation and internal training
-   - Establish frontend community of practice for knowledge sharing
-
-5. **Governance Model**:
-   - Create a frontend architecture council with representatives from each team
-   - Regular architecture reviews and pattern sharing
-   - Clear guidelines for when to share vs. create new components
-
-### Implementation Details
-
-#### Phase 1: Foundation (Q4 2024)
-
-1. Create core design system and component library
-2. Establish micro-frontend shell architecture
-3. Develop initial build and deployment pipeline
-4. Implement authentication and session management
-5. Create developer documentation and examples
-
-#### Phase 2: Domain Migration (Q1-Q2 2025)
-
-1. Migrate high-priority domains to micro-frontend architecture
-2. Implement analytics and monitoring strategy
-3. Develop advanced patterns for cross-domain interaction
-4. Enhance performance optimization capabilities
-5. Create specialized mobile experiences
-
-#### Phase 3: Advanced Capabilities (Q3-Q4 2025)
-
-1. Implement personalization framework
-2. Develop advanced A/B testing capabilities
-3. Enhance internationalization and localization
-4. Create specialized native experiences
-5. Implement advanced analytics and behavior tracking
-
-### Considered Alternatives
-
-#### 1. Monolithic Single-Page Application (SPA)
-
-**Pros**: Simpler architecture, unified codebase, shared state management  
-**Cons**: Development bottlenecks, scaling challenges, larger bundle sizes
-
-This approach would be simpler initially but would recreate many of our current scaling challenges.
-
-#### 2. Server-Side Rendering Only
-
-**Pros**: Simpler technology stack, better SEO by default, reduced client-side JavaScript  
-**Cons**: Limited interactivity, slower subsequent navigation, poorer offline capabilities
-
-While this would improve initial load performance, it would limit our ability to create rich interactive experiences.
-
-#### 3. Native Mobile Apps Only for Mobile
-
-**Pros**: Optimal mobile experience, full native capabilities, offline functionality  
-**Cons**: Development cost, platform duplication, release friction
-
-This would deliver better mobile experiences but at significantly higher development and maintenance costs.
-
-#### 4. Framework-Agnostic Approach
-
-**Pros**: Maximum team autonomy, best-tool-for-job flexibility  
-**Cons**: Duplication of efforts, inconsistent experiences, integration challenges
-
-While offering maximum flexibility, this would lead to significant inconsistency and integration challenges.
-
-### References
-
-1. [Micro Frontends](https://martinfowler.com/articles/micro-frontends.html) (Martin Fowler)
-2. [Module Federation](https://webpack.js.org/concepts/module-federation/) (Webpack Documentation)
-3. ["Building Micro-Frontends" by Luca Mezzalira](https://www.oreilly.com/library/view/building-micro-frontends/9781492082989/)
-4. [Frontend Design Systems](https://designsystemsrepo.com/design-systems)
-5. [Atomic Design](https://atomicdesign.bradfrost.com/) by Brad Frost
-6. [React Documentation](https://reactjs.org/docs/getting-started.html)
-7. [Next.js Documentation](https://nextjs.org/docs)
-
-### Decision Record History
-
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2024-08-10 | 0.1 | Initial draft | Jennifer Lee |
-| 2024-08-20 | 0.2 | Added implementation phases and domain decomposition | Alex Johnson |
-| 2024-08-30 | 0.3 | Incorporated feedback from UX and frontend teams | Sarah Chen |
-| 2024-09-05 | 1.0 | Approved by Architecture and UX Boards | Architecture Board |
-
-## Appendix A: Frontend Architecture Overview
-
-```mermaid
-flowchart TB
-    subgraph "Client Applications"
-        web[Web Browser]
-        ios[iOS App]
-        android[Android App]
-    end
-    
-    subgraph "Micro-Frontend Shell"
-        shell[Shell Application]
-        router[Routing Layer]
-        auth[Auth Module]
-    end
-    
-    subgraph "Micro-Frontends"
-        product[Product Experience]
-        cart[Cart & Checkout]
-        account[User Account]
-        content[Content Pages]
-        order[Order Management]
-    end
-    
-    subgraph "Shared Foundation"
-        design[Design System]
-        core[Core Components]
-        utils[Utility Functions]
-        hooks[React Hooks]
-    end
-    
-    subgraph "Backend Integration"
-        bff[BFF Layer]
-        api[API Gateway]
-    end
-    
-    web --> shell
-    ios --> shell
-    android --> shell
-    
-    shell --> router
-    shell --> auth
-    
-    router --> product
-    router --> cart
-    router --> account
-    router --> content
-    router --> order
-    
-    product --> design
-    cart --> design
-    account --> design
-    content --> design
-    order --> design
-    
-    product --> core
-    cart --> core
-    account --> core
-    content --> core
-    order --> core
-    
-    product --> bff
-    cart --> bff
-    account --> bff
-    content --> bff
-    order --> bff
-    
-    bff --> api
-```
-
-## Appendix B: Component Development Workflow
-
-```mermaid
-sequenceDiagram
-    participant Designer
-    participant Dev as Developer
-    participant PR as Pull Request
-    participant CI as CI/CD Pipeline
-    participant DS as Design System
-    participant App as Application
-    
-    Designer->>Designer: Create Component Design
-    Designer->>Dev: Handoff Design Specs
-    
-    Dev->>Dev: Develop Component
-    Dev->>Dev: Write Component Tests
-    Dev->>Dev: Document Component
-    
-    Dev->>PR: Submit Pull Request
-    PR->>CI: Trigger CI Pipeline
-    
-    CI->>CI: Lint Check
-    CI->>CI: Type Check
-    CI->>CI: Unit Tests
-    CI->>CI: Visual Regression Tests
-    CI->>CI: Bundle Size Analysis
-    CI->>CI: Accessibility Tests
-    
-    CI->>PR: Report Results
-    PR->>DS: Merge to Design System
-    
-    DS->>App: Component Available for Use
-    App->>App: Integrate Component
-```
-
-## Appendix C: Micro-Frontend Integration Patterns
-
-```mermaid
-flowchart TB
-    subgraph "Integration Approaches"
-        direction TB
-        
-        subgraph "Build-Time Integration"
-            npm[NPM Dependencies]
-            mono[Monorepo Packages]
-        end
-        
-        subgraph "Run-Time Integration"
-            fed[Module Federation]
-            iframes[IFrames]
-            web[Web Components]
-        end
-        
-        subgraph "Edge-Side Integration"
-            esi[Edge Side Includes]
-            ssi[Server Side Includes]
-        end
-    end
-    
-    subgraph "Implementation Patterns"
-        direction TB
-        
-        subgraph "Horizontal Split"
-            domains[By Domain/Business Function]
-        end
-        
-        subgraph "Vertical Split"
-            pages[Page-Based Composition]
-        end
-        
-        subgraph "Hybrid Approach"
-            shell[Shell + Domain Modules]
-        end
-    end
-    
-    fed --> shell
-    domains --> fed
-    pages --> iframes
-    shell --> web
-``` 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/architecture-decision-records/published/06-observability-strategy.mdx b/examples/default/docs/technical-architecture-design/architecture-decision-records/published/06-observability-strategy.mdx
deleted file mode 100644
index 419ebdeea..000000000
--- a/examples/default/docs/technical-architecture-design/architecture-decision-records/published/06-observability-strategy.mdx
+++ /dev/null
@@ -1,439 +0,0 @@
----
-title: Observability Strategy
-summary: Architectural decision record for implementing observability in the FlowMart e-commerce platform
-sidebar:
-    label: Observability Strategy
-    order: 6
----
-
-## ADR-006: Observability Strategy for FlowMart E-commerce Platform
-
-### Status
-
-Approved (2024-09-15)
-
-### Context
-
-As we transition from a monolithic architecture to a distributed microservices-based e-commerce platform, traditional monitoring approaches are no longer sufficient. The increased complexity of our architecture introduces several challenges:
-
-1. **Distributed Systems Complexity**: With dozens of microservices communicating asynchronously, understanding system behavior becomes significantly more difficult.
-
-2. **Increased Failure Points**: A distributed architecture introduces more potential failure points and complex failure modes.
-
-3. **Service Interdependencies**: Issues in one service can cascade to others, making root cause analysis challenging.
-
-4. **Multiple Technologies**: Different services use different languages, frameworks, and datastores, requiring diverse instrumentation approaches.
-
-5. **Deployment Frequency**: With continuous deployment across multiple services, correlating issues with specific changes becomes more complex.
-
-6. **Performance Bottlenecks**: Identifying performance bottlenecks in a distributed system requires end-to-end visibility.
-
-7. **Cross-Team Collaboration**: Multiple teams own different services, requiring a common observability approach and shared understanding.
-
-8. **Business Impact Correlation**: Need to connect technical metrics with business outcomes to prioritize improvements.
-
-Our current monitoring strategy is primarily focused on infrastructure metrics and basic application health checks, which is insufficient for effectively operating our new architecture.
-
-### Decision
-
-We will implement a comprehensive **observability strategy** based on the "three pillars" approach (metrics, logs, and traces) with distributed tracing as a foundational element. Key components of this strategy include:
-
-1. **Observability Stack**:
-   - **Metrics**: Prometheus for metrics collection and alerting
-   - **Logs**: Elasticsearch, Logstash, and Kibana (ELK) for log aggregation and analysis
-   - **Traces**: Jaeger for distributed tracing
-   - **Dashboard**: Grafana for unified visualization and dashboarding
-   - **Alerting**: Prometheus Alertmanager with PagerDuty integration
-
-2. **Instrumentation Standards**:
-   - **Distributed Tracing**: OpenTelemetry as the standard instrumentation framework
-   - **Structured Logging**: JSON-formatted logs with standardized fields across all services
-   - **Metrics Naming**: Consistent metrics naming convention following Prometheus best practices
-   - **Service Level Objectives (SLOs)**: Defined for all critical user journeys
-   - **Error Budgets**: Established for each service and user journey
-
-3. **Core Observability Capabilities**:
-   - **Request Tracing**: End-to-end tracing for all user-initiated actions
-   - **Dependency Monitoring**: Monitoring of all external dependencies and services
-   - **Business Metrics**: Tracking of key business metrics alongside technical metrics
-   - **Synthetic Monitoring**: Regular testing of critical user journeys
-   - **Real User Monitoring (RUM)**: Frontend performance and error tracking
-   - **Anomaly Detection**: Automated detection of abnormal system behavior
-   - **Correlation Engine**: Tools to correlate metrics, logs, and traces during investigation
-
-4. **Data Retention and Sampling**:
-   - Critical business transaction traces retained for 30 days
-   - High-cardinality metrics sampled at appropriate rates
-   - Error logs retained for 90 days
-   - Regular logs retained for 30 days
-   - Aggregated metrics retained for 13 months for year-over-year analysis
-
-5. **Implementation Approach**:
-   - Platform team creates and maintains observability infrastructure
-   - Standardized libraries and SDKs for each supported language/framework
-   - Observability as code, with instrumentation verified in CI/CD pipelines
-   - Service templates with pre-configured observability components
-   - Progressive enhancement of observability capabilities
-
-### Observability Requirements by Domain
-
-| Domain | Key Metrics | Special Requirements | SLO Targets |
-|--------|------------|----------------------|-------------|
-| Product Catalog | Search latency, Cache hit rate | High cardinality data handling | 99.9% availability, p95 < 300ms |
-| Order Processing | Order volume, Processing time, Error rate | Comprehensive transaction tracing | 99.95% availability, p95 < 500ms |
-| Payment | Transaction volume, Success rate, Fraud detection rate | PCI compliance in logging | 99.99% availability, p95 < 800ms |
-| Inventory | Stock level changes, Reservation rate, Stockout events | Event-sourcing visibility | 99.9% availability, p95 < 400ms |
-| User Authentication | Login volume, Success rate, MFA usage | Security-focused monitoring | 99.99% availability, p95 < 250ms |
-| Checkout | Cart conversion rate, Abandonment points, Session duration | User journey analysis | 99.95% availability, p95 < 600ms |
-| Shipping | Fulfillment time, Carrier performance, Tracking accuracy | Third-party integration monitoring | 99.9% availability, p95 < 350ms |
-| Content Delivery | Cache hit ratio, Origin fetch time, Asset size | CDN performance visibility | 99.9% availability, p95 < 200ms |
-
-### Consequences
-
-#### Positive
-
-1. **Improved Troubleshooting**: Faster identification and resolution of issues through correlated observability data.
-
-2. **Proactive Detection**: Ability to detect potential issues before they impact users through anomaly detection and trend analysis.
-
-3. **Enhanced Understanding**: Better understanding of system behavior, dependencies, and performance characteristics.
-
-4. **Data-Driven Optimization**: Ability to make targeted performance improvements based on actual usage patterns.
-
-5. **Cross-Team Collaboration**: Common observability platform enables better collaboration during incident response.
-
-6. **Business Alignment**: Correlation between technical metrics and business outcomes helps prioritize technical work.
-
-7. **Resilience Verification**: Ability to verify that resilience mechanisms (circuit breakers, retries, etc.) function properly.
-
-8. **Capacity Planning**: Better data for capacity planning and scaling decisions.
-
-#### Negative
-
-1. **Implementation Overhead**: Adding comprehensive instrumentation requires additional development effort.
-
-2. **Data Volume Challenges**: Managing the volume of observability data requires careful planning and potential sampling.
-
-3. **Performance Impact**: Instrumentation adds some overhead to application performance, which must be managed.
-
-4. **Complexity**: A sophisticated observability stack adds operational complexity and maintenance requirements.
-
-5. **Learning Curve**: Teams need to learn new tools, concepts, and practices for effective use of observability data.
-
-6. **Cost Considerations**: Storage and processing of observability data has significant cost implications at scale.
-
-7. **Privacy and Security**: Observability data may contain sensitive information requiring appropriate controls.
-
-### Mitigation Strategies
-
-1. **Automated Instrumentation**:
-   - Use auto-instrumentation agents where possible
-   - Create starter templates with instrumentation pre-configured
-   - Build instrumentation verification into CI/CD pipelines
-
-2. **Data Management**:
-   - Implement appropriate sampling strategies for high-volume data
-   - Utilize data compression and aggregation techniques
-   - Define appropriate retention policies based on data criticality
-
-3. **Operating Model**:
-   - Create an observability platform team to manage the core infrastructure
-   - Establish observability champions within each service team
-   - Regular observability review and enhancement sessions
-
-4. **Knowledge Sharing**:
-   - Comprehensive documentation and training on observability tools
-   - Regular workshops on effective use of observability data
-   - Shared dashboards and runbooks for common scenarios
-
-5. **Security and Privacy**:
-   - Automated PII detection and redaction in logs and traces
-   - Role-based access control for observability data
-   - Regular audits of observability data for sensitive information
-
-### Implementation Details
-
-#### Phase 1: Foundation (Q4 2024)
-
-1. Deploy core observability infrastructure (Prometheus, ELK, Jaeger, Grafana)
-2. Implement standardized logging format and collection pipeline
-3. Create initial service dashboards and alerting
-4. Develop instrumentation libraries for primary service frameworks
-5. Establish basic SLOs for critical services
-
-#### Phase 2: Enhanced Capabilities (Q1 2025)
-
-1. Implement distributed tracing across all critical user journeys
-2. Create business metrics dashboards correlated with technical metrics
-3. Develop anomaly detection for key system behaviors
-4. Implement synthetic monitoring for critical paths
-5. Create runbooks integrated with observability tools
-
-#### Phase 3: Advanced Observability (Q2-Q3 2025)
-
-1. Implement ML-based anomaly detection and prediction
-2. Create self-service observability platform capabilities
-3. Develop advanced correlation between metrics, logs, and traces
-4. Implement automated performance testing with observability verification
-5. Develop capacity planning and forecasting based on observability data
-
-### Considered Alternatives
-
-#### 1. Commercial APM Solution Only (e.g., Dynatrace, New Relic)
-
-**Pros**: Comprehensive out-of-the-box capabilities, reduced implementation effort, integrated platform  
-**Cons**: High cost at scale, reduced flexibility, potential vendor lock-in
-
-While commercial APM tools provide excellent capabilities, we chose an open-source approach for cost flexibility and customization ability. We will reevaluate this decision as our needs evolve.
-
-#### 2. Minimal Custom Instrumentation
-
-**Pros**: Reduced development overhead, simplicity, lower initial investment  
-**Cons**: Limited visibility, reactive troubleshooting, challenges scaling observability with system growth
-
-This approach would not provide the depth of insight needed for effective operation of our distributed system.
-
-#### 3. Service Mesh-Based Observability
-
-**Pros**: Reduced application instrumentation, consistent approach, network-level visibility  
-**Cons**: Limited application-level context, additional infrastructure complexity, potential performance impact
-
-While we will leverage service mesh observability capabilities, we need application-level instrumentation for complete visibility.
-
-#### 4. Multiple Independent Monitoring Systems
-
-**Pros**: Specialized tools for each domain, team autonomy in tooling decisions  
-**Cons**: Fragmented visibility, integration challenges, inconsistent practices
-
-This approach would create silos and make cross-service troubleshooting significantly more difficult.
-
-### References
-
-1. Charity Majors, Liz Fong-Jones, George Miranda, "Observability Engineering" (O'Reilly)
-2. Cindy Sridharan, "Distributed Systems Observability" (O'Reilly)
-3. [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
-4. [Google SRE Book - Monitoring Distributed Systems](https://sre.google/sre-book/monitoring-distributed-systems/)
-5. [Prometheus Best Practices](https://prometheus.io/docs/practices/naming/)
-6. [Grafana Observability Strategy](https://grafana.com/blog/2019/10/21/whats-next-for-observability/)
-
-### Decision Record History
-
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2024-08-20 | 0.1 | Initial draft | Kevin Zhang |
-| 2024-09-01 | 0.2 | Added implementation phases and domain details | Rachel Williams |
-| 2024-09-10 | 0.3 | Incorporated feedback from SRE and platform teams | David Boyne |
-| 2024-09-15 | 1.0 | Approved by Architecture and Operations Boards | Architecture Board |
-
-## Appendix A: Observability Architecture
-
-```mermaid
-flowchart TB
-    subgraph "Data Sources"
-        apps[Applications]
-        infra[Infrastructure]
-        db[Databases]
-        net[Network]
-        fe[Frontend]
-    end
-    
-    subgraph "Collection Layer"
-        prom[Prometheus]
-        fluent[FluentBit]
-        otel[OpenTelemetry Collector]
-        beats[Beats]
-    end
-    
-    subgraph "Storage Layer"
-        tsdb[Prometheus TSDB]
-        es[Elasticsearch]
-        jaeger_db[Jaeger Storage]
-        loki[Loki]
-    end
-    
-    subgraph "Processing Layer"
-        alerts[Alertmanager]
-        anom[Anomaly Detection]
-        corr[Correlation Engine]
-        agg[Log Aggregation]
-    end
-    
-    subgraph "Visualization Layer"
-        grafana[Grafana]
-        kibana[Kibana]
-        jaeger_ui[Jaeger UI]
-        dashboards[Custom Dashboards]
-    end
-    
-    subgraph "Notification Layer"
-        pd[PagerDuty]
-        slack[Slack]
-        email[Email]
-        webhook[Webhooks]
-    end
-    
-    apps --> otel
-    apps --> fluent
-    apps --> prom
-    infra --> beats
-    infra --> prom
-    db --> prom
-    db --> beats
-    net --> prom
-    net --> beats
-    fe --> otel
-    
-    otel --> jaeger_db
-    otel --> loki
-    otel --> tsdb
-    fluent --> es
-    beats --> es
-    prom --> tsdb
-    
-    tsdb --> alerts
-    tsdb --> anom
-    es --> agg
-    es --> corr
-    jaeger_db --> corr
-    loki --> corr
-    
-    tsdb --> grafana
-    es --> kibana
-    es --> grafana
-    jaeger_db --> jaeger_ui
-    jaeger_db --> grafana
-    corr --> dashboards
-    agg --> dashboards
-    
-    alerts --> pd
-    alerts --> slack
-    alerts --> email
-    alerts --> webhook
-```
-
-## Appendix B: Observability Data Flow
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant Service1 as Service A
-    participant Service2 as Service B
-    participant Service3 as Service C
-    participant OTel as OpenTelemetry
-    participant Logs as Log System
-    participant Metrics as Metrics System
-    participant Traces as Tracing System
-    participant Dashboard as Dashboard
-    participant Alerts as Alert System
-    
-    User->>Service1: Request
-    
-    Service1->>OTel: Generate Span 1
-    Service1->>Logs: Log Request Details
-    Service1->>Metrics: Update Request Counter
-    
-    Service1->>Service2: Internal Request
-    Service2->>OTel: Generate Span 2 (child of Span 1)
-    Service2->>Logs: Log Processing Details
-    Service2->>Metrics: Update Processing Metrics
-    
-    Service2->>Service3: Database Query
-    Service3->>OTel: Generate Span 3 (child of Span 2)
-    Service3->>Logs: Log Query Details
-    Service3->>Metrics: Update Query Metrics
-    
-    Service3-->>Service2: Query Result
-    Service2-->>Service1: Internal Response
-    Service1-->>User: Response
-    
-    Service1->>OTel: Complete Span 1
-    Service1->>Metrics: Update Response Time
-    
-    OTel->>Traces: Store Complete Trace
-    
-    Logs->>Dashboard: Visualize Logs
-    Metrics->>Dashboard: Visualize Metrics
-    Traces->>Dashboard: Visualize Traces
-    
-    Metrics->>Alerts: Trigger Alerts (if threshold exceeded)
-    Alerts->>Dashboard: Display Alert Status
-```
-
-## Appendix C: Service Level Objectives (SLOs) Framework
-
-```mermaid
-flowchart TB
-    subgraph "SLO Definition Process"
-        direction TB
-        
-        subgraph "1. Identify Critical User Journeys"
-            journey1[Product Search]
-            journey2[Add to Cart]
-            journey3[Checkout]
-            journey4[Order Status]
-        end
-        
-        subgraph "2. Define Service Level Indicators (SLIs)"
-            availability[Availability %]
-            latency[Latency (p50, p95, p99)]
-            errors[Error Rate %]
-            saturation[Resource Saturation]
-        end
-        
-        subgraph "3. Set Target Objectives"
-            slo1[99.9% Availability]
-            slo2[p95 < 300ms]
-            slo3[Error Rate < 0.1%]
-        end
-        
-        subgraph "4. Establish Error Budgets"
-            monthly[Monthly Budget]
-            quarterly[Quarterly Budget]
-            policy[Error Budget Policy]
-        end
-    end
-    
-    subgraph "SLO Monitoring & Reporting"
-        direction TB
-        
-        subgraph "Real-time Dashboards"
-            current[Current Status]
-            trends[Burn Rate]
-            history[Historical Performance]
-        end
-        
-        subgraph "Alerting Strategy"
-            warning[Budget Warning (50%)]
-            critical[Budget Critical (75%)]
-            depleted[Budget Depleted (90%)]
-        end
-        
-        subgraph "Continuous Improvement"
-            retro[SLO Reviews]
-            adjust[Target Adjustments]
-            prioritize[Reliability Work]
-        end
-    end
-    
-    journey1 --> availability
-    journey1 --> latency
-    journey2 --> availability
-    journey2 --> latency
-    journey3 --> errors
-    journey3 --> availability
-    journey4 --> latency
-    
-    availability --> slo1
-    latency --> slo2
-    errors --> slo3
-    
-    slo1 --> monthly
-    slo2 --> monthly
-    slo3 --> monthly
-    
-    monthly --> current
-    monthly --> warning
-    
-    current --> retro
-    warning --> prioritize
-``` 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/infrastructure-as-code/01-iac-overview.mdx b/examples/default/docs/technical-architecture-design/infrastructure-as-code/01-iac-overview.mdx
deleted file mode 100644
index ed1f79350..000000000
--- a/examples/default/docs/technical-architecture-design/infrastructure-as-code/01-iac-overview.mdx
+++ /dev/null
@@ -1,175 +0,0 @@
----
-title: Infrastructure as Code (IaC) Overview
-summary: An overview of the infrastructure-as-code approach used in the FlowMart e-commerce platform
-sidebar:
-    label: 01 - IaC Overview
-    order: 1
----
-
-# Infrastructure as Code (IaC) Overview
-
-This document provides an overview of the Infrastructure as Code (IaC) approach used to manage and provision the infrastructure for the FlowMart e-commerce platform.
-
-## What is Infrastructure as Code?
-
-Infrastructure as Code (IaC) is an approach to infrastructure management where infrastructure resources are defined and provisioned through machine-readable definition files, rather than through manual processes or interactive configuration tools. This approach allows us to:
-
-- **Version control** our infrastructure definitions alongside our application code
-- **Automate** the provisioning and management of infrastructure
-- **Standardize** configurations across different environments
-- **Document** our infrastructure setup as living code rather than static documentation
-- **Test** infrastructure changes before deploying to production
-
-## Our IaC Tech Stack
-
-For the FlowMart e-commerce platform, we use the following technologies for our infrastructure management:
-
-### Primary Tools
-
-| Tool | Purpose |
-|------|---------|
-| **Terraform** | Infrastructure provisioning across cloud providers (primary tool) |
-| **Kubernetes (K8s)** | Container orchestration |
-| **Helm Charts** | Kubernetes application deployment packaging |
-| **GitHub Actions** | CI/CD pipeline automation |
-| **AWS CloudFormation** | Specific AWS infrastructure components |
-
-### Additional Supporting Tools
-
-| Tool | Purpose |
-|------|---------|
-| **Terragrunt** | Terraform code organization and management |
-| **Packer** | Virtual machine image building |
-| **Ansible** | Configuration management |
-| **Prometheus & Grafana** | Monitoring and alerting |
-| **ELK Stack** | Logging |
-
-## Infrastructure Architecture
-
-Our infrastructure is organized into the following logical components:
-
-```mermaid
-flowchart TD
-    classDef networkInfra fill:#e1d5e7,stroke:#9673a6,stroke-width:2px
-    classDef computeInfra fill:#d5e8d4,stroke:#82b366,stroke-width:2px
-    classDef datastoreInfra fill:#dae8fc,stroke:#6c8ebf,stroke-width:2px
-    classDef securityInfra fill:#f8cecc,stroke:#b85450,stroke-width:2px
-    classDef monitoringInfra fill:#fff2cc,stroke:#d6b656,stroke-width:2px
-
-    subgraph "Networking Infrastructure"
-        VPC[VPC & Subnets]
-        IGW[Internet Gateway]
-        NLB[Network Load Balancer]
-        Route53[DNS - Route53]
-    end
-    
-    subgraph "Compute Infrastructure"
-        EKS[EKS Cluster]
-        EC2[EC2 Instances]
-        Lambda[Lambda Functions]
-    end
-    
-    subgraph "Data Storage"
-        RDS[RDS Databases]
-        DynamoDB[DynamoDB Tables]
-        S3[S3 Buckets]
-        ElastiCache[ElastiCache Redis]
-    end
-    
-    subgraph "Security"
-        IAM[IAM Roles & Policies]
-        SG[Security Groups]
-        WAF[WAF & Shield]
-        Secrets[Secrets Manager]
-    end
-    
-    subgraph "Monitoring & Logging"
-        CloudWatch[CloudWatch]
-        Prometheus[Prometheus]
-        Grafana[Grafana Dashboards]
-        ELK[ELK Stack]
-    end
-    
-    %% Connections
-    VPC --> IGW
-    IGW --> NLB
-    NLB --> EKS
-    Route53 --> NLB
-    
-    EKS --> SG
-    EC2 --> SG
-    Lambda --> SG
-    
-    EKS --> RDS
-    EKS --> DynamoDB
-    EKS --> S3
-    EKS --> ElastiCache
-    
-    IAM --> EKS
-    IAM --> Lambda
-    IAM --> RDS
-    
-    CloudWatch --> EKS
-    CloudWatch --> RDS
-    CloudWatch --> Lambda
-    Prometheus --> EKS
-    Grafana --> Prometheus
-    ELK --> EKS
-    
-    %% Apply styles
-    class VPC,IGW,NLB,Route53 networkInfra
-    class EKS,EC2,Lambda computeInfra
-    class RDS,DynamoDB,S3,ElastiCache datastoreInfra
-    class IAM,SG,WAF,Secrets securityInfra
-    class CloudWatch,Prometheus,Grafana,ELK monitoringInfra
-```
-
-## Repository Structure
-
-Our infrastructure code is organized as follows:
-
-```
-infrastructure/
-│
-├── terraform/                  # Terraform configuration
-│   ├── environments/           # Environment-specific configurations
-│   │   ├── dev/
-│   │   ├── staging/
-│   │   └── production/
-│   ├── modules/                # Reusable Terraform modules
-│   │   ├── networking/
-│   │   ├── compute/
-│   │   ├── database/
-│   │   └── monitoring/
-│   └── global/                 # Global resources (e.g., Route53)
-│
-├── kubernetes/                 # Kubernetes manifests
-│   ├── base/                   # Base configurations
-│   └── overlays/               # Environment-specific overlays (Kustomize)
-│
-├── helm-charts/                # Helm charts for application deployment
-│
-├── scripts/                    # Utility scripts
-│
-└── packer/                     # Packer templates for image building
-```
-
-## Deployment Principles
-
-1. **Infrastructure Changes via Pull Requests**: All infrastructure changes must go through a pull request process, with automated testing and reviews.
-
-2. **Environment Promotion**: Changes are first deployed to development, then staging, and finally production, with appropriate testing at each stage.
-
-3. **Immutable Infrastructure**: We prefer to replace rather than modify infrastructure components.
-
-4. **Least Privilege**: We follow the principle of least privilege for all IAM roles and security groups.
-
-5. **Automated Rollbacks**: Our CI/CD pipelines include automated rollback capabilities if deployments fail.
-
-## Next Steps
-
-For more detailed information about our infrastructure as code setup, please refer to the following documents:
-
-- [Terraform Implementation](./02-terraform-implementation.mdx)
-- [Environment Setups](./03-environment-setups.mdx)
-- [CI/CD Pipelines](./04-cicd-pipelines.mdx) 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/infrastructure-as-code/02-terraform-implementation.mdx b/examples/default/docs/technical-architecture-design/infrastructure-as-code/02-terraform-implementation.mdx
deleted file mode 100644
index e20441bba..000000000
--- a/examples/default/docs/technical-architecture-design/infrastructure-as-code/02-terraform-implementation.mdx
+++ /dev/null
@@ -1,332 +0,0 @@
----
-title: Terraform Implementation
-summary: Details of how Terraform is used to provision and manage the FlowMart infrastructure
-sidebar:
-    label: 02 - Terraform Implementation
-    order: 2
----
-
-# Terraform Implementation
-
-This document describes how we use Terraform to manage and provision the infrastructure for the FlowMart e-commerce platform.
-
-## Why Terraform?
-
-We chose Terraform as our primary IaC tool for the following reasons:
-
-- **Cloud-agnostic**: While we primarily use AWS, Terraform gives us the flexibility to work with multiple cloud providers if needed
-- **Declarative syntax**: Define what you want, not how to get there
-- **State management**: Tracks the current state of infrastructure to plan changes
-- **Modular approach**: Supports reusable components through modules
-- **Strong community support**: Wide adoption means better documentation and resources
-- **Extensible**: Can be extended through providers and modules
-
-## Terraform Structure
-
-Our Terraform code follows a structured approach:
-
-### Directory Structure
-
-```
-terraform/
-│
-├── environments/                 # Environment-specific configurations
-│   ├── dev/
-│   │   ├── main.tf              # Main configuration file
-│   │   ├── variables.tf         # Input variables
-│   │   ├── outputs.tf           # Output variables
-│   │   └── terraform.tfvars     # Variable values
-│   ├── staging/
-│   │   └── ...
-│   └── production/
-│       └── ...
-│
-├── modules/                      # Reusable Terraform modules
-│   ├── networking/               # VPC, subnets, routing
-│   │   ├── main.tf
-│   │   ├── variables.tf
-│   │   └── outputs.tf
-│   ├── eks/                      # EKS cluster configuration
-│   │   └── ...
-│   ├── rds/                      # Database configurations
-│   │   └── ...
-│   ├── lambda/                   # Serverless functions
-│   │   └── ...
-│   └── monitoring/               # Monitoring resources
-│       └── ...
-│
-└── global/                       # Global resources
-    ├── iam/                      # IAM roles and policies
-    │   └── ...
-    └── route53/                  # DNS configurations
-        └── ...
-```
-
-### Module Design
-
-Each module follows a consistent pattern:
-
-- **Inputs**: Defined in `variables.tf`
-- **Resources**: Defined in `main.tf`
-- **Outputs**: Defined in `outputs.tf`
-
-## Core Infrastructure Components
-
-Here's an overview of our main Terraform modules and what they provision:
-
-### Networking Module
-
-The networking module provisions our VPC infrastructure:
-
-```hcl
-module "vpc" {
-  source = "../../modules/networking"
-
-  name                 = "flowmart-${var.environment}"
-  cidr                 = "10.0.0.0/16"
-  azs                  = ["us-west-2a", "us-west-2b", "us-west-2c"]
-  private_subnets      = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
-  public_subnets       = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]
-  database_subnets     = ["10.0.201.0/24", "10.0.202.0/24", "10.0.203.0/24"]
-  
-  enable_nat_gateway   = true
-  single_nat_gateway   = var.environment != "production"
-  
-  tags = {
-    Environment = var.environment
-    Project     = "FlowMart"
-    ManagedBy   = "Terraform"
-  }
-}
-```
-
-### EKS Module
-
-The EKS module provisions our Kubernetes cluster:
-
-```hcl
-module "eks" {
-  source = "../../modules/eks"
-
-  cluster_name    = "flowmart-${var.environment}"
-  cluster_version = "1.23"
-  
-  vpc_id          = module.vpc.vpc_id
-  subnet_ids      = module.vpc.private_subnets
-  
-  node_groups = {
-    application = {
-      desired_capacity = 3
-      max_capacity     = 10
-      min_capacity     = 2
-      instance_types   = ["t3.large"]
-      disk_size        = 50
-    }
-    
-    system = {
-      desired_capacity = 2
-      max_capacity     = 4
-      min_capacity     = 2
-      instance_types   = ["t3.medium"]
-      disk_size        = 20
-    }
-  }
-  
-  tags = {
-    Environment = var.environment
-    Project     = "FlowMart"
-    ManagedBy   = "Terraform"
-  }
-}
-```
-
-### Database Module
-
-The database module provisions our RDS instances:
-
-```hcl
-module "database" {
-  source = "../../modules/rds"
-
-  identifier           = "flowmart-${var.environment}"
-  engine               = "postgres"
-  engine_version       = "13.4"
-  instance_class       = var.environment == "production" ? "db.r5.large" : "db.t3.medium"
-  allocated_storage    = 100
-  
-  name                 = "flowmart"
-  username             = "flowmart_admin"
-  password             = var.db_password
-  
-  vpc_security_group_ids = [module.security_groups.database_sg_id]
-  subnet_ids             = module.vpc.database_subnets
-  
-  backup_retention_period = var.environment == "production" ? 30 : 7
-  
-  tags = {
-    Environment = var.environment
-    Project     = "FlowMart"
-    ManagedBy   = "Terraform"
-  }
-}
-```
-
-### DynamoDB Module
-
-For NoSQL database needs, we use DynamoDB:
-
-```hcl
-module "dynamodb" {
-  source = "../../modules/dynamodb"
-
-  tables = {
-    inventory = {
-      name           = "inventory-${var.environment}"
-      billing_mode   = "PROVISIONED"
-      read_capacity  = var.environment == "production" ? 20 : 5
-      write_capacity = var.environment == "production" ? 20 : 5
-      hash_key       = "productId"
-      attributes = [
-        {
-          name = "productId"
-          type = "S"
-        }
-      ]
-    },
-    
-    shopping_cart = {
-      name           = "shopping-cart-${var.environment}"
-      billing_mode   = "PROVISIONED"
-      read_capacity  = var.environment == "production" ? 20 : 5
-      write_capacity = var.environment == "production" ? 20 : 5
-      hash_key       = "sessionId"
-      attributes = [
-        {
-          name = "sessionId"
-          type = "S"
-        }
-      ]
-    }
-  }
-  
-  tags = {
-    Environment = var.environment
-    Project     = "FlowMart"
-    ManagedBy   = "Terraform"
-  }
-}
-```
-
-## Terraform Workflows
-
-We follow these workflows when making infrastructure changes:
-
-### Development Workflow
-
-```mermaid
-flowchart LR
-    classDef highlightStep fill:#d5e8d4,stroke:#82b366,stroke-width:2px
-
-    Init[terraform init] --> Plan[terraform plan]
-    Plan --> Review[Review plan]
-    Review --> Apply[terraform apply]
-    Apply --> Validate[Validate changes]
-    
-    class Plan,Review highlightStep
-```
-
-### Terraform in CI/CD Pipeline
-
-```mermaid
-flowchart TD
-    Code[Code changes pushed] --> PR[Pull request created]
-    PR --> Init[terraform init]
-    Init --> Plan[terraform plan]
-    Plan --> AutoReview[Automated plan review]
-    AutoReview --> HumanReview[Human review]
-    HumanReview --> Approved{Approved?}
-    Approved -->|Yes| Merge[Merge PR]
-    Approved -->|No| Revise[Revise changes]
-    Revise --> PR
-    Merge --> CI[CI/CD pipeline]
-    CI --> Apply[terraform apply]
-    Apply --> PostCheck[Post-apply validation]
-```
-
-## Terraform State Management
-
-We manage Terraform state using a remote backend with the following characteristics:
-
-- **S3 Bucket**: For state storage
-- **DynamoDB Table**: For state locking
-- **IAM Roles**: For secure access to state files
-- **State Encryption**: For security of sensitive data
-
-Example remote backend configuration:
-
-```hcl
-terraform {
-  backend "s3" {
-    bucket         = "flowmart-terraform-state"
-    key            = "environments/${var.environment}/terraform.tfstate"
-    region         = "us-west-2"
-    dynamodb_table = "terraform-lock"
-    encrypt        = true
-    role_arn       = "arn:aws:iam::ACCOUNT_ID:role/TerraformStateManager"
-  }
-}
-```
-
-## Terraform Best Practices
-
-We follow these best practices for our Terraform codebase:
-
-1. **Version Pinning**: Lock provider and module versions to ensure reproducibility
-
-```hcl
-terraform {
-  required_providers {
-    aws = {
-      source  = "hashicorp/aws"
-      version = "~> 4.16.0"
-    }
-  }
-  required_version = ">= 1.2.0"
-}
-```
-
-2. **Resource Tagging**: All resources are tagged for billing and management purposes
-
-```hcl
-tags = {
-  Environment = var.environment
-  Project     = "FlowMart"
-  ManagedBy   = "Terraform"
-  Service     = "Orders"
-}
-```
-
-3. **Variable Validation**: Validate inputs to prevent errors
-
-```hcl
-variable "environment" {
-  description = "The deployment environment (e.g., dev, staging, production)"
-  type        = string
-  
-  validation {
-    condition     = contains(["dev", "staging", "production"], var.environment)
-    error_message = "Environment must be one of: dev, staging, production."
-  }
-}
-```
-
-4. **Modular Design**: Use modules for reusable components
-
-5. **Minimal Permissions**: Follow the principle of least privilege for IAM roles
-
-## Next Steps
-
-For more information about our IaC implementation, please refer to:
-
-- [Environment Setups](./03-environment-setups.mdx)
-- [CI/CD Pipelines](./04-cicd-pipelines.mdx) 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/infrastructure-as-code/03-environment-setups.mdx b/examples/default/docs/technical-architecture-design/infrastructure-as-code/03-environment-setups.mdx
deleted file mode 100644
index 9eb0bf558..000000000
--- a/examples/default/docs/technical-architecture-design/infrastructure-as-code/03-environment-setups.mdx
+++ /dev/null
@@ -1,264 +0,0 @@
----
-title: Environment Setups
-summary: Detailed information about the different environments for the FlowMart e-commerce platform
-sidebar:
-    label: 03 - Environment Setups
-    order: 3
----
-
-# Environment Setups
-
-This document describes the different environments used in the FlowMart e-commerce platform, their purposes, configurations, and the promotion process between them.
-
-## Environment Strategy
-
-We follow a multi-environment strategy with clear separation and purposes:
-
-```mermaid
-flowchart TD
-    classDef devEnv fill:#dae8fc,stroke:#6c8ebf,stroke-width:2px
-    classDef stagingEnv fill:#d5e8d4,stroke:#82b366,stroke-width:2px
-    classDef prodEnv fill:#f8cecc,stroke:#b85450,stroke-width:2px
-    classDef dataEnv fill:#fff2cc,stroke:#d6b656,stroke-width:2px
-
-    Dev[Development Environment] --> Staging[Staging Environment]
-    Staging --> Production[Production Environment]
-    
-    Dev --- Sandbox[Sandbox Environments]
-    Production --- DR[Disaster Recovery]
-    
-    class Dev,Sandbox devEnv
-    class Staging stagingEnv
-    class Production,DR prodEnv
-    class Data dataEnv
-```
-
-## Environment Descriptions
-
-### Development Environment
-
-The development environment is used by developers to test changes and new features.
-
-- **Purpose**: Development, testing, and integration
-- **Access**: Development team
-- **Data**: Subset of anonymized production data or synthetic data
-- **Infrastructure Scale**: Minimal, cost-optimized
-- **Deployment Frequency**: Multiple times per day
-- **Automated Testing**: Unit tests, API tests
-
-**Key Characteristics**:
-- Shared development environment
-- Reduced redundancy (e.g., single NAT gateway, smaller instances)
-- Feature flags enabled for work-in-progress features
-- Debug and verbose logging enabled
-- Daily database refresh from anonymized production data
-
-### Staging Environment
-
-The staging environment is a pre-production environment that closely mirrors production.
-
-- **Purpose**: System testing, performance testing, UAT
-- **Access**: Development team, QA, selected stakeholders
-- **Data**: Full anonymized copy of production data
-- **Infrastructure Scale**: Nearly identical to production, but smaller scale
-- **Deployment Frequency**: Once per release (multiple times per week)
-- **Automated Testing**: Integration tests, performance tests, security scans
-
-**Key Characteristics**:
-- Configuration as close to production as possible
-- Full feature set enabled
-- Production-level logging
-- Staged rollout of new features
-- Regular (weekly) database refresh from anonymized production data
-
-### Production Environment
-
-The production environment serves real customers and processes real transactions.
-
-- **Purpose**: Serving end-users
-- **Access**: Limited access via break-glass procedures
-- **Data**: Real customer data
-- **Infrastructure Scale**: Full scale, highly available
-- **Deployment Frequency**: Multiple times per week, during designated windows
-- **Automated Testing**: Smoke tests, canary tests
-
-**Key Characteristics**:
-- High availability across multiple availability zones
-- Auto-scaling based on demand
-- Enhanced security controls
-- Full monitoring and alerting
-- Regular backups
-- Blue/green deployment strategy
-
-### Sandbox Environments
-
-Ephemeral environments for developers to test specific features or changes.
-
-- **Purpose**: Feature development, experimentation
-- **Access**: Individual developers or teams
-- **Data**: Synthetic data
-- **Infrastructure Scale**: Minimal
-- **Deployment Frequency**: On-demand
-- **Lifetime**: Temporary (hours to days)
-
-### Disaster Recovery Environment
-
-A standby environment that can be activated in case of a major outage in the production environment.
-
-- **Purpose**: Business continuity
-- **State**: Warm standby
-- **Data**: Regular replication from production
-- **Region**: Different from primary production region
-- **Activation**: Automated with manual approval
-
-## Environment Configuration
-
-We manage environment-specific configurations through:
-
-1. **Terraform Variables**: Each environment has its own `terraform.tfvars` file
-2. **Kubernetes ConfigMaps**: Environment-specific Kubernetes configurations
-3. **Environment Variables**: Set at the pod or container level
-4. **Feature Flags**: Application-level feature toggles
-
-Example Terraform Variable Differences:
-
-| Variable | Dev | Staging | Production |
-|----------|-----|---------|------------|
-| `vpc_cidr` | 10.0.0.0/16 | 10.1.0.0/16 | 10.2.0.0/16 |
-| `eks_node_count` | 2 | 3 | 5-10 (auto-scaling) |
-| `rds_instance_type` | db.t3.medium | db.r5.large | db.r5.2xlarge |
-| `rds_multi_az` | false | true | true |
-| `enable_waf` | false | true | true |
-
-## Environment Promotion Process
-
-We follow a structured promotion process for changes moving through environments:
-
-```mermaid
-sequenceDiagram
-    participant Dev as Development
-    participant Staging as Staging
-    participant Prod as Production
-    
-    Note over Dev: Feature development complete
-    Dev->>Staging: Promote code
-    Note over Staging: Run integration tests
-    Note over Staging: Performance testing
-    Note over Staging: Security scanning
-    Note over Staging: UAT approval
-    Staging->>Prod: Promote code
-    Note over Prod: Canary deployment
-    Note over Prod: Monitoring
-    Note over Prod: Full rollout
-```
-
-### Promotion Guidelines
-
-1. **Development to Staging**:
-   - All unit tests pass
-   - Code review completed
-   - Feature implementation verified in development
-   - Feature documentation completed
-
-2. **Staging to Production**:
-   - All integration tests pass
-   - Performance tests meet SLAs
-   - Security scans show no critical or high vulnerabilities
-   - UAT completed and signed off
-   - Release notes prepared
-
-## Environment Variables Management
-
-We manage environment variables securely using:
-
-1. **AWS Parameter Store**: For non-secret configuration
-2. **AWS Secrets Manager**: For sensitive values
-3. **Kubernetes Secrets**: Mounted into containers at runtime
-
-Example parameter naming convention:
-```
-/flowmart/{environment}/{service}/{parameter-name}
-```
-
-Example secret access in application code:
-```javascript
-const AWS = require('aws-sdk');
-const ssm = new AWS.SSM();
-
-async function getDatabaseConfig() {
-  const params = {
-    Name: `/flowmart/${process.env.ENVIRONMENT}/orders-service/db-connection-string`,
-    WithDecryption: true
-  };
-  
-  const result = await ssm.getParameter(params).promise();
-  return result.Parameter.Value;
-}
-```
-
-## Network Isolation
-
-Our environments are isolated from each other:
-
-```mermaid
-flowchart TB
-    subgraph "AWS Account: Production"
-        ProdVPC[Production VPC]
-    end
-    
-    subgraph "AWS Account: Non-Production"
-        StagingVPC[Staging VPC]
-        DevVPC[Development VPC]
-    end
-    
-    Internet[Internet] --> PVPN[Production VPN]
-    Internet --> NPVPN[Non-Production VPN]
-    
-    PVPN --> ProdVPC
-    NPVPN --> StagingVPC
-    NPVPN --> DevVPC
-```
-
-Key security controls:
-- Separate AWS accounts for production and non-production
-- VPC isolation for each environment
-- Separate VPN access for production and non-production
-- Restricted traffic between environments
-- Different IAM roles for each environment
-
-## Data Management Across Environments
-
-We handle data carefully across environments:
-
-1. **Production**: Real customer data with full security controls
-2. **Staging**: Anonymized production data, refreshed weekly
-3. **Development**: Subset of anonymized data or synthetic data
-4. **Sandbox**: Synthetic data only
-
-Data anonymization process:
-```mermaid
-flowchart LR
-    ProdDB[(Production Database)] --> Extract[Extract Data]
-    Extract --> Anonymize[Anonymize Sensitive Data]
-    Anonymize --> Load[Load to Non-Prod Environments]
-    Load --> StageDB[(Staging Database)]
-    Load --> DevDB[(Development Database)]
-```
-
-## Monitoring and Observability
-
-Each environment has appropriate monitoring:
-
-| Monitoring Aspect | Development | Staging | Production |
-|-------------------|-------------|---------|------------|
-| Metrics Collection | Basic | Full | Full |
-| Logs Retention | 7 days | 14 days | 90 days |
-| Alerting | Critical only | High and Critical | All severities |
-| Dashboards | Basic | Full | Full with extended |
-| Tracing | Sampled (50%) | Sampled (75%) | Sampled (10%) |
-
-## Next Steps
-
-For more information about our environment management and deployment processes, please refer to:
-
-- [CI/CD Pipelines](./04-cicd-pipelines.mdx) 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/infrastructure-as-code/04-cicd-pipelines.mdx b/examples/default/docs/technical-architecture-design/infrastructure-as-code/04-cicd-pipelines.mdx
deleted file mode 100644
index 5105ca406..000000000
--- a/examples/default/docs/technical-architecture-design/infrastructure-as-code/04-cicd-pipelines.mdx
+++ /dev/null
@@ -1,364 +0,0 @@
----
-title: CI/CD Pipelines
-summary: Detailed overview of the CI/CD pipelines used to deploy and maintain the FlowMart e-commerce platform
-sidebar:
-    label: 04 - CI/CD Pipelines
-    order: 4
----
-
-# CI/CD Pipelines
-
-This document provides an overview of the Continuous Integration (CI) and Continuous Deployment (CD) pipelines used to build, test, and deploy the FlowMart e-commerce platform.
-
-## CI/CD Philosophy
-
-Our CI/CD approach follows these key principles:
-
-1. **Automation First**: Automate everything that can be automated
-2. **Fast Feedback**: Provide developers with quick feedback on their changes
-3. **Consistency**: Ensure consistent builds and deployments across all environments
-4. **Security**: Integrate security testing throughout the pipeline
-5. **Observability**: Monitor and track all deployments and their impacts
-6. **Self-service**: Enable teams to deploy independently, but safely
-
-## CI/CD Technology Stack
-
-Our CI/CD pipeline utilizes the following key technologies:
-
-| Technology | Purpose |
-|------------|---------|
-| GitHub Actions | Main CI/CD orchestration platform |
-| ArgoCD | Kubernetes GitOps deployment tool |
-| Helm | Kubernetes package management |
-| Docker | Container building and registry |
-| Terraform | Infrastructure as Code deployment |
-| SonarQube | Code quality and security analysis |
-| Jest, JUnit, pytest | Unit testing frameworks |
-| Playwright | End-to-end testing |
-| K6 | Performance testing |
-| OWASP ZAP | Security scanning |
-| Snyk | Dependency vulnerability scanning |
-| AWS ECR | Container registry |
-
-## CI/CD Pipeline Overview
-
-Our CI/CD pipeline consists of multiple stages with specific responsibilities:
-
-```mermaid
-flowchart TD
-    classDef build fill:#dae8fc,stroke:#6c8ebf,stroke-width:2px
-    classDef test fill:#d5e8d4,stroke:#82b366,stroke-width:2px
-    classDef deploy fill:#ffe6cc,stroke:#d79b00,stroke-width:2px
-    classDef release fill:#f8cecc,stroke:#b85450,stroke-width:2px
-
-    CodePush[Code Push] --> Build[Build & Package]
-    Build --> UnitTest[Unit Tests]
-    UnitTest --> CodeQuality[Code Quality Analysis]
-    CodeQuality --> SecurityScan[Security Scanning]
-    SecurityScan --> DockerBuild[Docker Build]
-    DockerBuild --> PushRegistry[Push to Registry]
-    PushRegistry --> DeployDev[Deploy to Dev]
-    DeployDev --> IntegrationTest[Integration Tests]
-    IntegrationTest --> DeployStaging[Deploy to Staging]
-    DeployStaging --> PerformanceTest[Performance Tests]
-    DeployStaging --> E2ETest[End-to-End Tests]
-    PerformanceTest --> Approval{Approval}
-    E2ETest --> Approval
-    Approval -->|Approved| DeployProd[Deploy to Production]
-    Approval -->|Rejected| Feedback[Feedback Loop]
-    DeployProd --> SmokeTest[Smoke Tests]
-    SmokeTest --> Monitoring[Monitoring & Observability]
-    
-    class Build,DockerBuild build
-    class UnitTest,CodeQuality,SecurityScan,IntegrationTest,PerformanceTest,E2ETest,SmokeTest test
-    class DeployDev,DeployStaging,DeployProd deploy
-    class Approval,Monitoring release
-```
-
-## Pipeline Stages in Detail
-
-### 1. Build & Package
-
-- Triggered by code push or pull request
-- Compiles application code
-- Installs dependencies using package managers (npm, Maven, pip)
-- Generates build artifacts
-- Built in isolated environments with cached dependencies
-
-```yaml
-# Example GitHub Actions code snippet
-build:
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v3
-    - name: Set up Node.js
-      uses: actions/setup-node@v3
-      with:
-        node-version: '16'
-        cache: 'npm'
-    - name: Install dependencies
-      run: npm ci
-    - name: Build
-      run: npm run build
-    - name: Upload build artifacts
-      uses: actions/upload-artifact@v3
-      with:
-        name: build-artifacts
-        path: build/
-```
-
-### 2. Test
-
-Multiple types of tests run in parallel to provide rapid feedback:
-
-- **Unit Tests**: Test individual components in isolation
-- **Integration Tests**: Test component interactions
-- **End-to-End Tests**: Test complete user flows
-- **Performance Tests**: Test application performance under load
-- **Security Tests**: Scan for vulnerabilities in code and dependencies
-
-```mermaid
-flowchart LR
-    subgraph "Test Phase"
-        direction TB
-        Unit[Unit Tests]
-        Integration[Integration Tests]
-        E2E[End-to-End Tests]
-        Performance[Performance Tests]
-        Security[Security Tests]
-    end
-    
-    CodeBase[Code Base] --> Unit
-    CodeBase --> Integration
-    CodeBase --> E2E
-    CodeBase --> Performance
-    CodeBase --> Security
-    
-    Unit --> Results[Test Results]
-    Integration --> Results
-    E2E --> Results
-    Performance --> Results
-    Security --> Results
-```
-
-### 3. Docker Build & Registry Push
-
-- Builds Docker images for all services
-- Tags images with git commit SHA and environment
-- Pushes images to AWS ECR
-- Scans images for vulnerabilities before pushing
-
-```yaml
-# Example GitHub Actions code snippet
-docker-build:
-  runs-on: ubuntu-latest
-  needs: [build, test]
-  steps:
-    - uses: actions/checkout@v3
-    - name: Configure AWS credentials
-      uses: aws-actions/configure-aws-credentials@v1
-      with:
-        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
-        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-        aws-region: us-west-2
-    - name: Login to Amazon ECR
-      id: login-ecr
-      uses: aws-actions/amazon-ecr-login@v1
-    - name: Build and push Docker image
-      uses: docker/build-push-action@v4
-      with:
-        context: .
-        push: true
-        tags: ${{ steps.login-ecr.outputs.registry }}/flowmart-orders-service:${{ github.sha }}
-```
-
-### 4. Deployment
-
-We use GitOps with ArgoCD for managing deployments:
-
-- **Development**: Automatic deployment on successful build
-- **Staging**: Automatic deployment after integration tests pass
-- **Production**: Manual approval required, then automated deployment
-
-```mermaid
-sequenceDiagram
-    participant Dev as Developer
-    participant GH as GitHub Actions
-    participant Reg as Container Registry
-    participant Git as Git Repo (Manifests)
-    participant Argo as ArgoCD
-    participant K8s as Kubernetes Cluster
-    
-    Dev->>GH: Push Code
-    GH->>GH: Build & Test
-    GH->>Reg: Push Container Image
-    GH->>Git: Update Image Tag in Manifests
-    Git->>Argo: Sync (Automatic or Manual)
-    Argo->>K8s: Apply Manifests
-    K8s->>K8s: Deploy Application
-    K8s->>Argo: Report Status
-    Argo->>Git: Update Deployment Status
-```
-
-### 5. Post-Deployment Verification
-
-- **Smoke Tests**: Quick tests to verify basic functionality
-- **Canary Deployment**: Rolling deployment with traffic shifting
-- **Monitoring**: Performance and error tracking during and after deployment
-
-## Infrastructure Pipeline
-
-For infrastructure changes, we have a separate pipeline:
-
-```mermaid
-flowchart TD
-    InfraChange[Infrastructure Change] --> TerraformPlan[Terraform Plan]
-    TerraformPlan --> AutoReview[Automated Review]
-    AutoReview --> HumanReview[Human Review]
-    HumanReview --> Approval{Approved?}
-    Approval -->|Yes| TerraformApply[Terraform Apply]
-    Approval -->|No| Feedback[Feedback Loop]
-    TerraformApply --> Verification[Infrastructure Verification]
-    Verification --> Documentation[Update Documentation]
-```
-
-## Feature Branch Workflow
-
-We follow a feature branch workflow for development:
-
-```mermaid
-gitGraph
-    commit
-    commit
-    branch feature/order-tracking
-    checkout feature/order-tracking
-    commit
-    commit
-    commit
-    checkout main
-    merge feature/order-tracking
-    branch feature/payment-gateway
-    checkout feature/payment-gateway
-    commit
-    commit
-    checkout main
-    merge feature/payment-gateway
-    commit
-```
-
-## Deployment to Multiple Environments
-
-Our pipeline handles deployments to multiple environments:
-
-```mermaid
-flowchart TD
-    Build[Build & Test] --> DevDeploy[Deploy to Dev]
-    
-    DevDeploy --> IntegrationTest[Run Integration Tests]
-    IntegrationTest -->|Pass| StagingDeploy[Deploy to Staging]
-    IntegrationTest -->|Fail| FixIssues[Fix Issues]
-    FixIssues --> Build
-    
-    StagingDeploy --> StagingTests[Run E2E & Performance Tests]
-    StagingTests -->|Pass| ApprovalGate{Approval Gate}
-    StagingTests -->|Fail| FixIssues
-    
-    ApprovalGate -->|Approved| ProdDeploy[Deploy to Production]
-    ApprovalGate -->|Rejected| FixIssues
-    
-    ProdDeploy --> CanaryDeploy[Canary Deployment]
-    CanaryDeploy --> Monitor[Monitor]
-    Monitor -->|Healthy| FullRollout[Full Rollout]
-    Monitor -->|Issues| Rollback[Rollback]
-```
-
-## Rollback Strategy
-
-In case of deployment issues, we have an automated rollback strategy:
-
-1. **Immediate Automated Rollback**: Triggered by health checks or error rate spikes
-2. **One-Click Manual Rollback**: Available through the deployment dashboard
-3. **Previous Version Restoration**: Reverts to the last known good state
-
-```mermaid
-sequenceDiagram
-    participant Metrics as Metrics System
-    participant CD as CD Pipeline
-    participant Git as Git Repository
-    participant K8s as Kubernetes
-    
-    Note over Metrics,K8s: New deployment shows issues
-    Metrics->>CD: Alert on error threshold exceeded
-    CD->>CD: Trigger rollback process
-    CD->>Git: Revert to previous manifest version
-    Git->>K8s: Apply previous manifests
-    K8s->>K8s: Restore previous deployment
-    K8s->>CD: Report successful rollback
-    CD->>Metrics: Verify metrics returning to normal
-```
-
-## Pipeline Security
-
-Security is integrated throughout our pipeline:
-
-- **Secrets Management**: Secrets stored in AWS Secrets Manager and injected at runtime
-- **SAST**: Static Application Security Testing integrated in build phase
-- **DAST**: Dynamic Application Security Testing during staging deployment
-- **Dependency Scanning**: Checks for vulnerable dependencies
-- **Container Scanning**: Scans container images for vulnerabilities
-- **Infrastructure Scanning**: Checks IaC for security misconfigurations
-
-## Observability
-
-Our pipeline provides comprehensive observability:
-
-- **Deployment Tracking**: Each deployment is traced from commit to production
-- **Metrics Collection**: Performance metrics before and after deployment
-- **Log Aggregation**: Centralized logging for all pipeline stages
-- **Alerting**: Automated alerts for pipeline failures or anomalies
-- **Dashboards**: Visual representation of pipeline health and history
-
-Example deployment dashboard:
-
-```mermaid
-gantt
-    title Recent Deployments Timeline
-    dateFormat  YYYY-MM-DD HH:mm
-    axisFormat %H:%M
-    
-    section Orders Service
-    Build #452           :a1, 2023-05-10 09:00, 5m
-    Deploy to Dev        :a2, after a1, 10m
-    Integration Tests    :a3, after a2, 15m
-    Deploy to Staging    :a4, after a3, 10m
-    E2E Tests            :a5, after a4, 30m
-    Deploy to Prod       :a6, after a5, 15m
-    
-    section Inventory Service
-    Build #389           :b1, 2023-05-10 10:00, 5m
-    Deploy to Dev        :b2, after b1, 10m
-    Integration Tests    :b3, after b2, 15m
-    Deploy to Staging    :b4, after b3, 10m
-    E2E Tests            :b5, after b4, 30m
-    
-    section Payment Service
-    Build #421           :c1, 2023-05-10 08:30, 5m
-    Deploy to Dev        :c2, after c1, 10m
-    Integration Tests    :c3, after c2, 15m
-    Deploy to Staging    :c4, after c3, 10m
-    E2E Tests            :c5, after c4, 30m
-    Deploy to Prod       :c6, after c5, 15m
-```
-
-## Continuous Improvement
-
-We continuously improve our pipeline through:
-
-1. **Pipeline Metrics**: Track build times, success rates, and deployment frequency
-2. **Postmortems**: Document and learn from deployment failures
-3. **Automation Improvements**: Regularly identify manual steps for automation
-4. **Cross-team Learning**: Share best practices across development teams
-
-## Conclusion
-
-Our CI/CD pipeline provides a robust, secure, and efficient process for deploying changes to the FlowMart platform. By automating the build, test, and deployment processes, we can deliver new features and bug fixes to users quickly and reliably while maintaining high quality standards. 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/system-architecture-diagrams/01-high-level-system-overview.mdx b/examples/default/docs/technical-architecture-design/system-architecture-diagrams/01-high-level-system-overview.mdx
deleted file mode 100644
index ebca398a1..000000000
--- a/examples/default/docs/technical-architecture-design/system-architecture-diagrams/01-high-level-system-overview.mdx
+++ /dev/null
@@ -1,120 +0,0 @@
----
-title: High-Level FlowMart System Architecture Overview
-summary: A high-level overview of the FlowMart e-commerce system architecture
-sidebar:
-    label: 01 - High-Level Overview
-    order: 1
----
-
-# FlowMart System Architecture: High-Level Overview
-
-This diagram provides a high-level overview of the FlowMart e-commerce platform architecture. It illustrates the main components and how they interact to deliver our online shopping experience.
-
-## Business Context
-
-FlowMart is an e-commerce platform that enables customers to browse products, place orders, make payments, and track shipments. The architecture is designed to be scalable, resilient, and maintainable, following domain-driven design and event-driven architecture principles.
-
-## High-Level Architecture Diagram
-
-```mermaid
-flowchart TB
-    subgraph "Customer Channels"
-        Web["Web Application"]
-        Mobile["Mobile Apps"]
-        ThirdParty["Third-Party Integrations"]
-    end
-
-    subgraph "API Gateway Layer"
-        APIGateway["API Gateway / BFF"]
-    end
-
-    subgraph "Core Business Domains"
-        Orders["Orders Domain"]
-        Inventory["Inventory Domain"]
-        Payment["Payment Domain"]
-        Shipping["Shipping Domain"]
-        Subscription["Subscription Domain"]
-        Notification["Notification Domain"]
-    end
-
-    subgraph "Data Stores"
-        OrdersDB[(Orders Database)]
-        InventoryDB[(Inventory Database)]
-        PaymentDB[(Payment Database)]
-        ShippingDB[(Shipping Database)]
-        SubscriptionDB[(Subscription Database)]
-    end
-
-    subgraph "External Systems"
-        PaymentGateways["Payment Gateways"]
-        LogisticsProviders["Logistics Providers"]
-        EmailSMS["Email/SMS Providers"]
-    end
-
-    Web --> APIGateway
-    Mobile --> APIGateway
-    ThirdParty --> APIGateway
-    
-    APIGateway --> Orders
-    APIGateway --> Inventory
-    APIGateway --> Payment
-    APIGateway --> Shipping
-    APIGateway --> Subscription
-    
-    Orders <--> OrdersDB
-    Inventory <--> InventoryDB
-    Payment <--> PaymentDB
-    Shipping <--> ShippingDB
-    Subscription <--> SubscriptionDB
-    
-    Orders <--> Inventory
-    Orders <--> Payment
-    Orders <--> Shipping
-    Orders <--> Notification
-    Payment <--> Subscription
-    
-    Payment <--> PaymentGateways
-    Shipping <--> LogisticsProviders
-    Notification <--> EmailSMS
-```
-
-## Component Descriptions
-
-### Customer Channels
-- **Web Application**: A responsive web interface for customers to browse products and place orders
-- **Mobile Apps**: Native iOS and Android applications for mobile shopping
-- **Third-Party Integrations**: External platforms that integrate with our services
-
-### API Gateway Layer
-- **API Gateway / BFF**: Backend for Frontend that routes requests, handles authentication, and optimizes responses for different clients
-
-### Core Business Domains
-- **Orders Domain**: Manages the order lifecycle from creation to fulfillment
-- **Inventory Domain**: Tracks product availability and stock levels
-- **Payment Domain**: Processes payments and manages financial transactions
-- **Shipping Domain**: Handles order delivery and shipment tracking
-- **Subscription Domain**: Manages recurring subscriptions and memberships
-- **Notification Domain**: Delivers notifications to customers across different channels
-
-### Data Stores
-- Each domain has its dedicated database to ensure domain isolation and independent scalability
-
-### External Systems
-- **Payment Gateways**: Third-party services for processing credit card payments
-- **Logistics Providers**: External shipping and delivery services
-- **Email/SMS Providers**: Services for sending notifications to customers
-
-## Key Architectural Principles
-
-1. **Domain-Driven Design**: Our system is organized around business domains and their bounded contexts
-2. **Event-Driven Architecture**: Services communicate primarily through events, enhancing decoupling and scalability
-3. **Microservices**: Each domain is implemented as one or more microservices with clear boundaries
-4. **API-First Approach**: All functionality is exposed through well-defined APIs
-5. **Polyglot Persistence**: Each domain can choose the most appropriate database technology
-
-## Next Steps
-
-For a more detailed view of our architecture, refer to the following documents:
-- [Domain-Level Architecture](./02-domain-level-architecture.mdx)
-- [Service-Level Architecture](./03-service-level-architecture.mdx)
-- [Data Flow Architecture](./04-data-flow-architecture.mdx) 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/system-architecture-diagrams/02-domain-level-architecture.mdx b/examples/default/docs/technical-architecture-design/system-architecture-diagrams/02-domain-level-architecture.mdx
deleted file mode 100644
index 4fd27b0ed..000000000
--- a/examples/default/docs/technical-architecture-design/system-architecture-diagrams/02-domain-level-architecture.mdx
+++ /dev/null
@@ -1,253 +0,0 @@
----
-title: FlowMart Domain-Level Architecture
-summary: A detailed view of FlowMart's domain architecture showing bounded contexts and domain interactions
-sidebar:
-    label: 02 - Domain Architecture
-    order: 2
----
-
-# FlowMart Domain-Level Architecture
-
-This document describes the domain-level architecture of the FlowMart e-commerce platform, showing how different domains interact with each other through well-defined interfaces and events.
-
-## Domain Architecture Diagram
-
-The following diagram illustrates the bounded contexts of each domain and how they communicate with each other:
-
-```mermaid
-flowchart TD
-    classDef domainStyle fill:#f9f9f9,stroke:#333,stroke-width:2px
-    classDef eventStyle fill:#e1f5fe,stroke:#0288d1,stroke-width:1px,color:#01579b
-    classDef commandStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px,color:#4a148c
-    classDef queryStyle fill:#e8f5e9,stroke:#388e3c,stroke-width:1px,color:#1b5e20
-
-    subgraph Orders["Orders Domain"]
-        class Orders domainStyle
-        OrdersService["Orders Service"]
-        
-        subgraph OrderEvents[" "]
-            OrderConfirmed["OrderConfirmed Event"]
-            OrderCancelled["OrderCancelled Event"]
-            OrderAmended["OrderAmended Event"]
-        end
-        
-        subgraph OrderCommands[" "]
-            PlaceOrder["PlaceOrder Command"]
-        end
-        
-        subgraph OrderQueries[" "]
-            GetOrder["GetOrder Query"]
-        end
-    end
-    
-    subgraph Inventory["Inventory Domain"]
-        class Inventory domainStyle
-        InventoryService["Inventory Service"]
-        
-        subgraph InventoryEvents[" "]
-            InventoryAdjusted["InventoryAdjusted Event"]
-            OutOfStock["OutOfStock Event"]
-        end
-        
-        subgraph InventoryCommands[" "]
-            AddInventory["AddInventory Command"]
-            UpdateInventory["UpdateInventory Command"]
-            DeleteInventory["DeleteInventory Command"]
-        end
-        
-        subgraph InventoryQueries[" "]
-            GetInventoryStatus["GetInventoryStatus Query"]
-            GetInventoryList["GetInventoryList Query"]
-        end
-    end
-    
-    subgraph Payment["Payment Domain"]
-        class Payment domainStyle
-        PaymentService["Payment Service"]
-        
-        subgraph PaymentEvents[" "]
-            PaymentProcessed["PaymentProcessed Event"]
-        end
-        
-        subgraph PaymentCommands[" "]
-            PaymentInitiated["PaymentInitiated Command"]
-        end
-        
-        subgraph PaymentQueries[" "]
-            GetPaymentStatus["GetPaymentStatus Query"]
-        end
-    end
-    
-    subgraph Shipping["Shipping Domain"]
-        class Shipping domainStyle
-        ShippingService["Shipping Service"]
-        
-        subgraph ShippingEvents[" "]
-            ShipmentCreated["ShipmentCreated Event"]
-            ShipmentDispatched["ShipmentDispatched Event"]
-            ShipmentInTransit["ShipmentInTransit Event"]
-            ShipmentDelivered["ShipmentDelivered Event"]
-            DeliveryFailed["DeliveryFailed Event"]
-            ReturnInitiated["ReturnInitiated Event"]
-        end
-        
-        subgraph ShippingCommands[" "]
-            CreateShipment["CreateShipment Command"]
-            UpdateShipmentStatus["UpdateShipmentStatus Command"]
-            CancelShipment["CancelShipment Command"]
-            CreateReturnLabel["CreateReturnLabel Command"]
-        end
-    end
-    
-    subgraph Subscription["Subscription Domain"]
-        class Subscription domainStyle
-        SubscriptionService["Subscription Service"]
-        
-        subgraph SubscriptionEvents[" "]
-            UserSubscriptionStarted["UserSubscriptionStarted Event"]
-            UserSubscriptionCancelled["UserSubscriptionCancelled Event"]
-        end
-        
-        subgraph SubscriptionCommands[" "]
-            SubscribeUser["SubscribeUser Command"]
-            CancelSubscription["CancelSubscription Command"]
-        end
-        
-        subgraph SubscriptionQueries[" "]
-            GetSubscriptionStatus["GetSubscriptionStatus Query"]
-        end
-    end
-    
-    subgraph Notification["Notification Domain"]
-        class Notification domainStyle
-        NotificationService["Notification Service"]
-        
-        subgraph NotificationQueries[" "]
-            GetUserNotifications["GetUserNotifications Query"]
-            GetNotificationDetails["GetNotificationDetails Query"]
-        end
-    end
-
-    %% Domain Interactions through Events
-    OrderConfirmed -->|Consumed by| InventoryService
-    OrderConfirmed -->|Consumed by| ShippingService
-    OrderCancelled -->|Consumed by| InventoryService
-    OrderAmended -->|Consumed by| InventoryService
-    
-    InventoryAdjusted -->|Consumed by| OrdersService
-    InventoryAdjusted -->|Consumed by| NotificationService
-    OutOfStock -->|Consumed by| NotificationService
-    
-    PaymentProcessed -->|Consumed by| OrdersService
-    PaymentProcessed -->|Consumed by| ShippingService
-    PaymentProcessed -->|Consumed by| SubscriptionService
-    
-    UserSubscriptionCancelled -->|Consumed by| OrdersService
-
-    %% Apply styles to events, commands and queries
-    class OrderConfirmed,OrderCancelled,OrderAmended,InventoryAdjusted,OutOfStock,PaymentProcessed,ShipmentCreated,ShipmentDispatched,ShipmentInTransit,ShipmentDelivered,DeliveryFailed,ReturnInitiated,UserSubscriptionStarted,UserSubscriptionCancelled eventStyle
-    
-    class PlaceOrder,AddInventory,UpdateInventory,DeleteInventory,PaymentInitiated,CreateShipment,UpdateShipmentStatus,CancelShipment,CreateReturnLabel,SubscribeUser,CancelSubscription commandStyle
-    
-    class GetOrder,GetInventoryStatus,GetInventoryList,GetPaymentStatus,GetSubscriptionStatus,GetUserNotifications,GetNotificationDetails queryStyle
-```
-
-## Domain Descriptions
-
-### Orders Domain
-The Orders Domain is the central domain of our e-commerce platform. It manages the entire lifecycle of customer orders, from creation to fulfillment. It communicates with other domains to check inventory availability, process payments, and arrange shipping.
-
-**Key Events Published:**
-- OrderConfirmed
-- OrderCancelled 
-- OrderAmended
-
-**Commands:**
-- PlaceOrder
-
-**Queries:**
-- GetOrder
-
-### Inventory Domain
-The Inventory Domain manages product stock levels across all warehouses. It ensures accurate inventory tracking and provides real-time stock information to other domains.
-
-**Key Events Published:**
-- InventoryAdjusted
-- OutOfStock
-
-**Commands:**
-- AddInventory
-- UpdateInventory
-- DeleteInventory
-
-**Queries:**
-- GetInventoryStatus
-- GetInventoryList
-
-### Payment Domain
-The Payment Domain handles all financial transactions within the platform. It processes customer payments, manages refunds, and communicates with external payment gateways.
-
-**Key Events Published:**
-- PaymentProcessed
-
-**Commands:**
-- PaymentInitiated
-
-**Queries:**
-- GetPaymentStatus
-
-### Shipping Domain
-The Shipping Domain manages order delivery to customers. It tracks shipment status, handles returns, and integrates with external logistics providers.
-
-**Key Events Published:**
-- ShipmentCreated
-- ShipmentDispatched
-- ShipmentInTransit
-- ShipmentDelivered
-- DeliveryFailed
-- ReturnInitiated
-
-**Commands:**
-- CreateShipment
-- UpdateShipmentStatus
-- CancelShipment
-- CreateReturnLabel
-
-### Subscription Domain
-The Subscription Domain manages recurring customer subscriptions. It handles subscription lifecycle, billing cycles, and renewal processes.
-
-**Key Events Published:**
-- UserSubscriptionStarted
-- UserSubscriptionCancelled
-
-**Commands:**
-- SubscribeUser
-- CancelSubscription
-
-**Queries:**
-- GetSubscriptionStatus
-
-### Notification Domain
-The Notification Domain is responsible for sending notifications to customers through various channels like email, SMS, and push notifications.
-
-**Queries:**
-- GetUserNotifications
-- GetNotificationDetails
-
-## Domain Integration Patterns
-
-The domains in FlowMart's architecture interact using several integration patterns:
-
-1. **Event-Driven Communication**: Most domain interactions occur through asynchronous events published to a message broker, promoting loose coupling.
-
-2. **Synchronous API Calls**: For operations requiring immediate responses, domains expose REST APIs that can be called synchronously.
-
-3. **Saga Pattern**: For complex workflows spanning multiple domains, we use choreography-based sagas where services respond to events to maintain data consistency.
-
-4. **CQRS**: We separate command (write) and query (read) operations, allowing for optimization of each path.
-
-## Next Steps
-
-For more detailed architectural information, see:
-- [Service-Level Architecture](./03-service-level-architecture.mdx)
-- [Data Flow Architecture](./04-data-flow-architecture.mdx) 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/system-architecture-diagrams/03-service-level-architecture.mdx b/examples/default/docs/technical-architecture-design/system-architecture-diagrams/03-service-level-architecture.mdx
deleted file mode 100644
index 0adc493f6..000000000
--- a/examples/default/docs/technical-architecture-design/system-architecture-diagrams/03-service-level-architecture.mdx
+++ /dev/null
@@ -1,253 +0,0 @@
----
-title: FlowMart Service-Level Architecture
-summary: A detailed view of the services within each domain and their interactions
-sidebar:
-    label: 03 - Service Architecture
-    order: 3
----
-
-# FlowMart Service-Level Architecture
-
-This document provides a detailed view of the individual services within FlowMart's e-commerce platform, their responsibilities, and how they interact.
-
-## Service Architecture Overview
-
-The following diagram illustrates the services that make up our platform and how they communicate:
-
-```mermaid
-flowchart TD
-    classDef apiGateway fill:#f8cecc,stroke:#b85450,stroke-width:2px
-    classDef orderService fill:#dae8fc,stroke:#6c8ebf,stroke-width:2px
-    classDef inventoryService fill:#d5e8d4,stroke:#82b366,stroke-width:2px
-    classDef paymentService fill:#ffe6cc,stroke:#d79b00,stroke-width:2px
-    classDef shippingService fill:#e1d5e7,stroke:#9673a6,stroke-width:2px
-    classDef notificationService fill:#fff2cc,stroke:#d6b656,stroke-width:2px
-    classDef subscriptionService fill:#f8cecc,stroke:#b85450,stroke-width:2px
-    classDef datastore fill:#f5f5f5,stroke:#666666,stroke-width:1px
-    classDef messagebroker fill:#e6ffcc,stroke:#36b37e,stroke-width:2px
-    classDef externalSystem fill:#f5f5f5,stroke:#666666,stroke-width:1px,stroke-dasharray: 5 5
-
-    APIGateway[API Gateway]
-    EventBus[Event Bus / Message Broker]
-    
-    subgraph OrdersDomain["Orders Domain"]
-        OrdersService[Orders Service]
-        OrdersDB[(Orders Database)]
-    end
-    
-    subgraph InventoryDomain["Inventory Domain"]
-        InventoryService[Inventory Service]
-        InventoryDB[(Inventory Database)]
-    end
-    
-    subgraph PaymentDomain["Payment Domain"]
-        PaymentService[Payment Service]
-        PaymentDB[(Payment Database)]
-    end
-    
-    subgraph ShippingDomain["Shipping Domain"]
-        ShippingService[Shipping Service]
-        ShippingDB[(Shipping Database)]
-    end
-    
-    subgraph NotificationDomain["Notification Domain"]
-        NotificationService[Notification Service]
-    end
-    
-    subgraph SubscriptionDomain["Subscription Domain"]
-        SubscriptionService[Subscription Service]
-        SubscriptionDB[(Subscription Database)]
-    end
-    
-    subgraph ExternalSystems["External Systems"]
-        PaymentGateway[Payment Gateway]
-        EmailProvider[Email Provider]
-        SMSProvider[SMS Provider]
-        LogisticsPartner[Logistics Partner]
-    end
-    
-    %% API Gateway connections
-    APIGateway --> OrdersService
-    APIGateway --> InventoryService
-    APIGateway --> PaymentService
-    APIGateway --> ShippingService
-    APIGateway --> SubscriptionService
-    
-    %% Database connections
-    OrdersService <--> OrdersDB
-    InventoryService <--> InventoryDB
-    PaymentService <--> PaymentDB
-    ShippingService <--> ShippingDB
-    SubscriptionService <--> SubscriptionDB
-    
-    %% Event bus connections
-    OrdersService <--> EventBus
-    InventoryService <--> EventBus
-    PaymentService <--> EventBus
-    ShippingService <--> EventBus
-    NotificationService <--> EventBus
-    SubscriptionService <--> EventBus
-    
-    %% External system connections
-    PaymentService --> PaymentGateway
-    NotificationService --> EmailProvider
-    NotificationService --> SMSProvider
-    ShippingService --> LogisticsPartner
-    
-    %% Apply styles
-    class APIGateway apiGateway
-    class OrdersService orderService
-    class InventoryService inventoryService
-    class PaymentService paymentService
-    class ShippingService shippingService
-    class NotificationService notificationService
-    class SubscriptionService subscriptionService
-    class OrdersDB,InventoryDB,PaymentDB,ShippingDB,SubscriptionDB datastore
-    class EventBus messagebroker
-    class PaymentGateway,EmailProvider,SMSProvider,LogisticsPartner externalSystem
-```
-
-## Service Component Details
-
-### API Gateway
-- **Description**: Entry point for all client requests, handles routing, authentication, and load balancing
-- **Technologies**: AWS API Gateway, Kong, or Nginx
-- **Key Responsibilities**:
-  - Route requests to appropriate services
-  - Handle authentication and authorization
-  - API rate limiting and throttling
-  - Request validation
-  - Response caching
-
-### Orders Service
-- **Description**: Manages the entire lifecycle of customer orders
-- **Technologies**: Node.js, Express, MongoDB
-- **Key Responsibilities**:
-  - Create and manage orders
-  - Process order amendments and cancellations
-  - Coordinate with other services for order fulfillment
-  - Maintain order history and status
-- **Key Events**:
-  - Publishes: OrderConfirmed, OrderCancelled, OrderAmended
-  - Consumes: InventoryAdjusted, PaymentProcessed, UserSubscriptionCancelled
-
-### Inventory Service
-- **Description**: Tracks and manages product inventory across warehouses
-- **Technologies**: Java, Spring Boot, PostgreSQL
-- **Key Responsibilities**:
-  - Maintain accurate inventory levels
-  - Process inventory adjustments
-  - Monitor stock levels and trigger alerts
-  - Support inventory queries
-- **Key Events**:
-  - Publishes: InventoryAdjusted, OutOfStock
-  - Consumes: OrderConfirmed, OrderCancelled, OrderAmended
-
-### Payment Service
-- **Description**: Handles all payment processing and financial transactions
-- **Technologies**: Node.js, Express, PostgreSQL
-- **Key Responsibilities**:
-  - Process customer payments
-  - Manage refunds and chargebacks
-  - Integrate with payment gateways
-  - Track payment status
-- **Key Events**:
-  - Publishes: PaymentProcessed
-  - Consumes: PaymentInitiated, UserSubscriptionStarted, InventoryAdjusted
-
-### Shipping Service
-- **Description**: Manages logistics and shipment of orders
-- **Technologies**: Python, Flask, MongoDB
-- **Key Responsibilities**:
-  - Create and track shipments
-  - Integrate with logistics providers
-  - Process returns and exchanges
-  - Calculate shipping costs
-- **Key Events**:
-  - Publishes: ShipmentCreated, ShipmentDispatched, ShipmentInTransit, ShipmentDelivered, DeliveryFailed, ReturnInitiated
-  - Consumes: OrderConfirmed, PaymentProcessed
-
-### Notification Service
-- **Description**: Delivers notifications to customers through various channels
-- **Technologies**: Node.js, Express, Redis
-- **Key Responsibilities**:
-  - Send transactional emails
-  - Deliver SMS notifications
-  - Push mobile app notifications
-  - Store notification history
-- **Key Events**:
-  - Consumes: InventoryAdjusted, OutOfStock, PaymentProcessed
-
-### Subscription Service
-- **Description**: Manages recurring subscriptions and memberships
-- **Technologies**: Java, Spring Boot, MySQL
-- **Key Responsibilities**:
-  - Handle subscription lifecycle
-  - Process recurring billing
-  - Manage subscription plans and tiers
-  - Track subscription status
-- **Key Events**:
-  - Publishes: UserSubscriptionStarted, UserSubscriptionCancelled
-  - Consumes: PaymentProcessed
-
-### Event Bus / Message Broker
-- **Description**: Central messaging system that enables asynchronous communication between services
-- **Technologies**: Apache Kafka, RabbitMQ, or AWS SNS/SQS
-- **Key Responsibilities**:
-  - Reliable event delivery
-  - Support for event persistence
-  - Message routing
-  - Scalable message throughput
-
-## Service Interaction Patterns
-
-### Synchronous Communication
-Services communicate directly with each other through REST APIs for operations that require immediate responses.
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant OrdersService
-    participant InventoryService
-    participant PaymentService
-    
-    Client->>OrdersService: Place Order
-    OrdersService->>InventoryService: Check Inventory Availability
-    InventoryService-->>OrdersService: Inventory Available
-    OrdersService->>PaymentService: Process Payment
-    PaymentService-->>OrdersService: Payment Successful
-    OrdersService-->>Client: Order Confirmation
-```
-
-### Asynchronous Communication
-Services communicate through events published to the event bus, allowing for loose coupling.
-
-```mermaid
-sequenceDiagram
-    participant OrdersService
-    participant EventBus
-    participant InventoryService
-    participant ShippingService
-    participant NotificationService
-    
-    OrdersService->>EventBus: Publish OrderConfirmed Event
-    EventBus->>InventoryService: OrderConfirmed Event
-    InventoryService->>EventBus: Publish InventoryAdjusted Event
-    EventBus->>ShippingService: OrderConfirmed Event
-    ShippingService->>EventBus: Publish ShipmentCreated Event
-    EventBus->>NotificationService: ShipmentCreated Event
-    NotificationService->>Customer: Send Shipment Notification
-```
-
-## Infrastructure Considerations
-
-- All services are containerized using Docker and orchestrated with Kubernetes
-- Services are deployed across multiple availability zones for high availability
-- Auto-scaling is configured based on CPU and memory metrics
-- Database replication and backups are implemented for data durability
-- Centralized logging and monitoring using Prometheus and Grafana
-
-## Next Steps
-
-For more information about data flows within the system, refer to:
-- [Data Flow Architecture](./04-data-flow-architecture.mdx) 
\ No newline at end of file
diff --git a/examples/default/docs/technical-architecture-design/system-architecture-diagrams/04-data-flow-architecture.mdx b/examples/default/docs/technical-architecture-design/system-architecture-diagrams/04-data-flow-architecture.mdx
deleted file mode 100644
index 8e26fd5d2..000000000
--- a/examples/default/docs/technical-architecture-design/system-architecture-diagrams/04-data-flow-architecture.mdx
+++ /dev/null
@@ -1,460 +0,0 @@
----
-title: FlowMart Data Flow Architecture
-summary: A detailed view of key data flows and business processes within the FlowMart e-commerce platform
-sidebar:
-    label: 04 - Data Flow Architecture
-    order: 4
----
-
-# FlowMart Data Flow Architecture
-
-This document illustrates the key data flows within the FlowMart e-commerce platform, focusing on the most important business processes and how data moves through the system.
-
-## Key Business Process Flows
-
-### Order Placement and Fulfillment Flow
-
-This diagram shows the complete flow from order placement to order fulfillment:
-
-```mermaid
-flowchart TD
-    classDef customerAction fill:#ffcccc,stroke:#ff0000
-    classDef systemProcess fill:#ccffcc,stroke:#00aa00
-    classDef decisionPoint fill:#ffffcc,stroke:#ffcc00
-    classDef externalSystem fill:#ccccff,stroke:#0000ff
-    classDef dataStore fill:#f5f5f5,stroke:#333333
-
-    Start([Customer starts checkout]) --> ValidateCart[Validate Shopping Cart]
-    class Start customerAction
-    
-    ValidateCart --> CartValid{Is cart valid?}
-    class ValidateCart systemProcess
-    class CartValid decisionPoint
-    
-    CartValid -->|No| UpdateCart[Customer updates cart]
-    class UpdateCart customerAction
-    
-    UpdateCart --> ValidateCart
-    
-    CartValid -->|Yes| CheckInventory[Check Inventory Availability]
-    class CheckInventory systemProcess
-    
-    CheckInventory --> InventoryAvailable{Inventory available?}
-    class InventoryAvailable decisionPoint
-    
-    InventoryAvailable -->|No| NotifyCustomer[Notify Customer of Unavailability]
-    class NotifyCustomer systemProcess
-    
-    NotifyCustomer --> UpdateCart
-    
-    InventoryAvailable -->|Yes| ProcessPayment[Process Payment]
-    class ProcessPayment systemProcess
-    
-    ProcessPayment --> PaymentGateway[Payment Gateway]
-    class PaymentGateway externalSystem
-    
-    PaymentGateway --> PaymentSuccessful{Payment successful?}
-    class PaymentSuccessful decisionPoint
-    
-    PaymentSuccessful -->|No| NotifyPaymentFailure[Notify Payment Failure]
-    class NotifyPaymentFailure systemProcess
-    
-    NotifyPaymentFailure --> UpdatePayment[Customer updates payment]
-    class UpdatePayment customerAction
-    
-    UpdatePayment --> ProcessPayment
-    
-    PaymentSuccessful -->|Yes| CreateOrder[Create Order]
-    class CreateOrder systemProcess
-    
-    CreateOrder --> OrderDB[(Orders Database)]
-    class OrderDB dataStore
-    
-    CreateOrder --> ReserveInventory[Reserve Inventory]
-    class ReserveInventory systemProcess
-    
-    ReserveInventory --> InventoryDB[(Inventory Database)]
-    class InventoryDB dataStore
-    
-    ReserveInventory --> CreateShipment[Create Shipment]
-    class CreateShipment systemProcess
-    
-    CreateShipment --> ShipmentDB[(Shipment Database)]
-    class ShipmentDB dataStore
-    
-    CreateShipment --> NotifyCustomerOrder[Send Order Confirmation]
-    class NotifyCustomerOrder systemProcess
-    
-    NotifyCustomerOrder --> End([Order Placement Complete])
-    class End customerAction
-```
-
-### Payment Processing Flow
-
-This diagram details the payment processing flow:
-
-```mermaid
-sequenceDiagram
-    participant Customer
-    participant OrdersService
-    participant PaymentService
-    participant PaymentGateway
-    participant PaymentDB
-    participant EventBus
-    participant NotificationService
-
-    Customer->>OrdersService: Place Order
-    OrdersService->>PaymentService: Request Payment
-    PaymentService->>PaymentGateway: Process Payment
-    
-    alt Payment Successful
-        PaymentGateway->>PaymentService: Confirm Payment
-        PaymentService->>PaymentDB: Store Payment Information
-        PaymentService->>EventBus: Publish PaymentProcessed Event
-        EventBus->>OrdersService: PaymentProcessed Event
-        EventBus->>NotificationService: PaymentProcessed Event
-        NotificationService->>Customer: Send Payment Confirmation
-        OrdersService->>Customer: Complete Order
-    else Payment Failed
-        PaymentGateway->>PaymentService: Payment Failure
-        PaymentService->>PaymentDB: Log Failed Transaction
-        PaymentService->>OrdersService: Payment Failed Response
-        OrdersService->>Customer: Request Different Payment Method
-    end
-```
-
-### Inventory Management Flow
-
-This diagram shows how inventory is managed across the system:
-
-```mermaid
-stateDiagram-v2
-    [*] --> Available: Initial Stock
-    
-    Available --> Reserved: Customer Places Order
-    Reserved --> Allocated: Order Confirmed
-    Reserved --> Available: Order Cancelled
-    
-    Allocated --> Shipped: Order Shipped
-    Shipped --> Delivered: Order Delivered
-    Delivered --> [*]
-    
-    Available --> Replenished: Inventory Low
-    Replenished --> Available: Stock Received
-    
-    Available --> OutOfStock: All Units Reserved
-    OutOfStock --> Available: Replenishment
-```
-
-### Subscription Processing Flow
-
-This diagram illustrates the subscription management flow:
-
-```mermaid
-flowchart TD
-    classDef process fill:#d5e8d4,stroke:#82b366
-    classDef event fill:#dae8fc,stroke:#6c8ebf
-    classDef externalSystem fill:#f5f5f5,stroke:#666666,stroke-width:1px
-    classDef decision fill:#fff2cc,stroke:#d6b656
-
-    Start([Start Subscription Process]) --> NewSubscription[Create Subscription]
-    class NewSubscription process
-
-    NewSubscription --> InitialPayment[Process Initial Payment]
-    class InitialPayment process
-    
-    InitialPayment --> PaymentSystem[Payment Gateway]
-    class PaymentSystem externalSystem
-    
-    PaymentSystem --> PaymentSuccessful{Payment Successful?}
-    class PaymentSuccessful decision
-    
-    PaymentSuccessful -->|Yes| ActivateSubscription[Activate Subscription]
-    class ActivateSubscription process
-    
-    PaymentSuccessful -->|No| FailedSubscription[Failed Subscription]
-    class FailedSubscription process
-    
-    FailedSubscription --> NotifyFailure[Notify Customer of Failure]
-    class NotifyFailure process
-    
-    ActivateSubscription --> UserSubscriptionStarted[Publish UserSubscriptionStarted Event]
-    class UserSubscriptionStarted event
-    
-    UserSubscriptionStarted --> ScheduleRenewal[Schedule Next Renewal]
-    class ScheduleRenewal process
-    
-    ScheduleRenewal --> TimeForRenewal{Time for Renewal?}
-    class TimeForRenewal decision
-    
-    TimeForRenewal -->|Yes| ProcessRenewalPayment[Process Renewal Payment]
-    class ProcessRenewalPayment process
-    
-    TimeForRenewal -->|No| Wait[Wait for Renewal Date]
-    class Wait process
-    
-    Wait --> TimeForRenewal
-    
-    ProcessRenewalPayment --> PaymentSystem
-    
-    PaymentSystem --> RenewalSuccessful{Renewal Successful?}
-    class RenewalSuccessful decision
-    
-    RenewalSuccessful -->|Yes| ExtendSubscription[Extend Subscription]
-    class ExtendSubscription process
-    
-    RenewalSuccessful -->|No, after retries| CancelSubscription[Cancel Subscription]
-    class CancelSubscription process
-    
-    ExtendSubscription --> ScheduleRenewal
-    
-    CancelSubscription --> UserSubscriptionCancelled[Publish UserSubscriptionCancelled Event]
-    class UserSubscriptionCancelled event
-    
-    UserSubscriptionCancelled --> End([End Subscription Process])
-```
-
-## Detailed Data Flow Examples
-
-### Customer Order Flow
-
-The following diagram shows the data flow when a customer places an order:
-
-```mermaid
-sequenceDiagram
-    participant Customer
-    participant Web/Mobile App
-    participant API Gateway
-    participant OrdersService
-    participant InventoryService
-    participant PaymentService
-    participant ShippingService
-    participant NotificationService
-    participant EventBus
-
-    Customer->>Web/Mobile App: Add items to cart
-    Customer->>Web/Mobile App: Proceed to checkout
-    Web/Mobile App->>API Gateway: POST /orders
-    API Gateway->>OrdersService: Create order request
-    
-    OrdersService->>InventoryService: Check inventory availability
-    InventoryService-->>OrdersService: Inventory status
-    
-    OrdersService->>PaymentService: Process payment
-    PaymentService-->>OrdersService: Payment result
-    
-    alt Order Successful
-        OrdersService->>EventBus: Publish OrderConfirmed
-        EventBus->>InventoryService: OrderConfirmed
-        InventoryService->>EventBus: Publish InventoryAdjusted
-        EventBus->>ShippingService: OrderConfirmed
-        ShippingService->>EventBus: Publish ShipmentCreated
-        EventBus->>NotificationService: OrderConfirmed
-        NotificationService->>Customer: Send order confirmation
-    else Order Failed
-        OrdersService->>EventBus: Publish OrderFailed
-        EventBus->>NotificationService: OrderFailed
-        NotificationService->>Customer: Send failure notification
-    end
-```
-
-### Product Return Flow
-
-The following diagram shows the data flow when a customer returns a product:
-
-```mermaid
-sequenceDiagram
-    participant Customer
-    participant Web/Mobile App
-    participant API Gateway
-    participant OrdersService
-    participant ShippingService
-    participant InventoryService
-    participant PaymentService
-    participant NotificationService
-    participant EventBus
-
-    Customer->>Web/Mobile App: Request return
-    Web/Mobile App->>API Gateway: POST /returns
-    API Gateway->>OrdersService: Create return request
-    OrdersService->>ShippingService: Generate return label
-    
-    ShippingService->>EventBus: Publish ReturnInitiated
-    EventBus->>NotificationService: ReturnInitiated
-    NotificationService->>Customer: Send return instructions
-    
-    Note over Customer,ShippingService: Customer ships the item back
-    
-    ShippingService->>EventBus: Publish ReturnReceived
-    EventBus->>InventoryService: ReturnReceived
-    InventoryService->>EventBus: Publish InventoryAdjusted
-    
-    EventBus->>PaymentService: ReturnReceived
-    PaymentService->>EventBus: Publish RefundIssued
-    
-    EventBus->>NotificationService: RefundIssued
-    NotificationService->>Customer: Send refund confirmation
-```
-
-## Data Storage Overview
-
-The following diagram provides a high-level overview of the data storage architecture:
-
-```mermaid
-erDiagram
-    CUSTOMER ||--o{ ORDER : places
-    CUSTOMER ||--o{ SUBSCRIPTION : subscribes
-    ORDER ||--|{ ORDER_ITEM : contains
-    ORDER ||--|| SHIPMENT : fulfilled-by
-    ORDER ||--|| PAYMENT : paid-by
-    PRODUCT ||--o{ ORDER_ITEM : included-in
-    PRODUCT ||--o{ INVENTORY : stocked-as
-    WAREHOUSE ||--o{ INVENTORY : holds
-    SUBSCRIPTION ||--o{ SUBSCRIPTION_PAYMENT : generates
-    
-    CUSTOMER {
-        string id PK
-        string firstName
-        string lastName
-        string email
-        string phone
-        datetime createdAt
-    }
-    
-    ORDER {
-        string id PK
-        string customerId FK
-        string status
-        decimal totalAmount
-        datetime orderDate
-    }
-    
-    ORDER_ITEM {
-        string id PK
-        string orderId FK
-        string productId FK
-        int quantity
-        decimal unitPrice
-    }
-    
-    PRODUCT {
-        string id PK
-        string name
-        string description
-        decimal price
-        string category
-    }
-    
-    INVENTORY {
-        string id PK
-        string productId FK
-        string warehouseId FK
-        int quantity
-        int reserved
-    }
-    
-    WAREHOUSE {
-        string id PK
-        string name
-        string location
-    }
-    
-    SHIPMENT {
-        string id PK
-        string orderId FK
-        string status
-        string trackingNumber
-        datetime shippedDate
-    }
-    
-    PAYMENT {
-        string id PK
-        string orderId FK
-        decimal amount
-        string paymentMethod
-        string status
-        datetime paymentDate
-    }
-    
-    SUBSCRIPTION {
-        string id PK
-        string customerId FK
-        string status
-        string plan
-        date startDate
-        date endDate
-        string billingCycle
-    }
-    
-    SUBSCRIPTION_PAYMENT {
-        string id PK
-        string subscriptionId FK
-        decimal amount
-        datetime paymentDate
-        string status
-    }
-```
-
-## Event Flow and Message Schema
-
-The following diagram shows a sample of our event structure and flow:
-
-```mermaid
-graph TD
-    classDef publisher fill:#d1e0f0,stroke:#6c8ebf
-    classDef event fill:#f8cecc,stroke:#b85450
-    classDef consumer fill:#d5e8d4,stroke:#82b366
-
-    OrdersService[Orders Service]:::publisher --> OrderConfirmed[OrderConfirmed Event]:::event
-    
-    subgraph OrderConfirmedSchema[ ]
-        direction TB
-        OrderConfirmedMessage["OrderConfirmed Schema
-        {
-          orderId: string,
-          userId: string,
-          orderItems: [
-            {
-              productId: string,
-              quantity: number,
-              unitPrice: number
-            }
-          ],
-          totalAmount: number,
-          timestamp: datetime
-        }"]
-    end
-    
-    OrderConfirmed --- OrderConfirmedSchema
-    
-    OrderConfirmed --> InventoryService[Inventory Service]:::consumer
-    OrderConfirmed --> ShippingService[Shipping Service]:::consumer
-    
-    InventoryService --> InventoryAdjusted[InventoryAdjusted Event]:::event
-    
-    subgraph InventoryAdjustedSchema[ ]
-        direction TB
-        InventoryAdjustedMessage["InventoryAdjusted Schema
-        {
-          productId: string,
-          warehouseId: string,
-          quantityChanged: number,
-          newQuantity: number,
-          timestamp: datetime
-        }"]
-    end
-    
-    InventoryAdjusted --- InventoryAdjustedSchema
-    
-    InventoryAdjusted --> OrdersService:::consumer
-    InventoryAdjusted --> NotificationService[Notification Service]:::consumer
-```
-
-## Conclusion
-
-This document has provided an in-depth view of the data flows within the FlowMart e-commerce platform. By understanding these flows, developers and stakeholders can better comprehend how data moves through the system and how different components interact with each other.
-
-For more details on specific architecture components, refer to:
-- [High-Level System Overview](./01-high-level-system-overview.mdx)
-- [Domain-Level Architecture](./02-domain-level-architecture.mdx)
-- [Service-Level Architecture](./03-service-level-architecture.mdx) 
\ No newline at end of file
diff --git a/examples/default/domains/Catalog/entities/category/index.mdx b/examples/default/domains/Catalog/entities/category/index.mdx
new file mode 100644
index 000000000..0bfb7a052
--- /dev/null
+++ b/examples/default/domains/Catalog/entities/category/index.mdx
@@ -0,0 +1,36 @@
+---
+id: category
+name: Category
+version: 1.0.0
+identifier: categoryId
+aggregateRoot: true
+summary: A merchandising grouping used to organize products for discovery.
+owners:
+  - product-platform
+properties:
+  - name: categoryId
+    type: UUID
+    required: true
+    description: Unique category identifier.
+  - name: slug
+    type: string
+    required: true
+    description: Stable URL-safe category key.
+  - name: displayName
+    type: string
+    required: true
+    description: Customer-facing category name.
+  - name: parentCategoryId
+    type: UUID
+    required: false
+    description: Parent category for hierarchy navigation.
+    references: category
+    relationType: belongsTo
+    referencesIdentifier: categoryId
+---
+
+## Overview
+
+Category defines how products are grouped for browsing. It is owned by the Catalog domain and projected into the Search System for discovery.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Catalog/entities/product-variant/index.mdx b/examples/default/domains/Catalog/entities/product-variant/index.mdx
new file mode 100644
index 000000000..365dcd43a
--- /dev/null
+++ b/examples/default/domains/Catalog/entities/product-variant/index.mdx
@@ -0,0 +1,35 @@
+---
+id: product-variant
+name: Product Variant
+version: 1.0.0
+identifier: variantId
+summary: A purchasable variation of a product, such as size or color.
+owners:
+  - product-platform
+properties:
+  - name: variantId
+    type: UUID
+    required: true
+    description: Unique variant identifier.
+  - name: productId
+    type: UUID
+    required: true
+    description: Product this variant belongs to.
+    references: product
+    relationType: belongsTo
+    referencesIdentifier: productId
+  - name: sku
+    type: string
+    required: true
+    description: Variant-level SKU.
+  - name: attributes
+    type: object
+    required: true
+    description: Variant dimensions such as size, color or material.
+---
+
+## Overview
+
+Product Variant captures the concrete option a customer can buy. It belongs to a [[entity|product]] and is indexed into search when product data changes.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Catalog/entities/product/index.mdx b/examples/default/domains/Catalog/entities/product/index.mdx
new file mode 100644
index 000000000..91826fc3b
--- /dev/null
+++ b/examples/default/domains/Catalog/entities/product/index.mdx
@@ -0,0 +1,37 @@
+---
+id: product
+name: Product
+version: 1.0.0
+identifier: productId
+aggregateRoot: true
+summary: The sellable item Acme manages in the product catalog.
+owners:
+  - product-platform
+properties:
+  - name: productId
+    type: UUID
+    required: true
+    description: Unique product identifier.
+  - name: sku
+    type: string
+    required: true
+    description: Primary merchandising SKU.
+  - name: name
+    type: string
+    required: true
+    description: Customer-facing product name.
+  - name: status
+    type: string
+    required: true
+    description: Product publication state.
+    enum:
+      - draft
+      - active
+      - archived
+---
+
+## Overview
+
+The Product is the Catalog domain's core aggregate. It is created and maintained by [[service|product-api]] and published to downstream consumers through product events.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Catalog/entities/search-document/index.mdx b/examples/default/domains/Catalog/entities/search-document/index.mdx
new file mode 100644
index 000000000..d9818c4e9
--- /dev/null
+++ b/examples/default/domains/Catalog/entities/search-document/index.mdx
@@ -0,0 +1,35 @@
+---
+id: search-document
+name: Search Document
+version: 1.0.0
+identifier: documentId
+summary: The denormalized representation of product data indexed by Search.
+owners:
+  - search-platform
+properties:
+  - name: documentId
+    type: string
+    required: true
+    description: Search index document identifier.
+  - name: productId
+    type: UUID
+    required: true
+    description: Product represented by the document.
+    references: product
+    relationType: represents
+    referencesIdentifier: productId
+  - name: searchableText
+    type: string
+    required: true
+    description: Text used for matching and ranking.
+  - name: indexedAt
+    type: datetime
+    required: true
+    description: Time the document was last indexed.
+---
+
+## Overview
+
+Search Document is the read model maintained by [[system|search-system]]. It is eventually consistent with the Product Catalog System.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Catalog/index.mdx b/examples/default/domains/Catalog/index.mdx
new file mode 100644
index 000000000..0ea42b1e0
--- /dev/null
+++ b/examples/default/domains/Catalog/index.mdx
@@ -0,0 +1,65 @@
+---
+id: catalog
+name: Catalog
+version: 1.0.0
+summary: |
+  The Catalog domain owns everything about products — how they are created, maintained and made discoverable across Acme Inc. It is the source of truth for product data and powers product search across the business.
+owners:
+  - product-platform
+systems:
+  - id: product-catalog-system
+    version: 1.0.0
+  - id: search-system
+    version: 1.0.0
+entities:
+  - id: product
+    version: 1.0.0
+  - id: product-variant
+    version: 1.0.0
+  - id: category
+    version: 1.0.0
+  - id: search-document
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Catalog** domain is responsible for the lifecycle of every product Acme Inc sells, and for making those products discoverable. It is split into two internal systems that work together:
+
+<Tiles>
+  <Tile
+    icon="RectangleGroupIcon"
+    href="/docs/systems/product-catalog-system/1.0.0"
+    title="Product Catalog System"
+    description="System of record for product data — create, update, delete and read products."
+  />
+  <Tile
+    icon="MagnifyingGlassIcon"
+    href="/docs/systems/search-system/1.0.0"
+    title="Search System"
+    description="Indexes product changes and serves fast, relevant product search to the rest of the business."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Product Catalog System** is the authoritative source of product data. Whenever a product is created, updated or deleted it publishes a domain event. The **Search System** subscribes to those events, keeps its search index in sync, and exposes a search API so other teams never have to query the catalog database directly.
+
+The diagram below shows the domain's systems, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Component map
+
+These are the components that are part of this domain (parts of the systems in this domain)
+
+<NodeGraph />
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/adrs/adr-001-use-transactional-outbox/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/adrs/adr-001-use-transactional-outbox/index.mdx
new file mode 100644
index 000000000..2cd394fde
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/adrs/adr-001-use-transactional-outbox/index.mdx
@@ -0,0 +1,43 @@
+---
+id: adr-001-use-transactional-outbox
+name: 'ADR-001: Publish product events via a transactional outbox'
+summary: Product change events are written to an outbox table in the same transaction as the change, then relayed to the broker, so an event is never lost or published for a rolled-back change.
+version: 1.0.0
+status: accepted
+date: 2026-02-10
+owners:
+  - product-platform
+decisionMakers:
+  - product-platform
+appliesTo:
+  - type: system
+    id: product-catalog-system
+  - type: service
+    id: product-search-publisher
+  - type: container
+    id: product-database
+badges:
+  - content: Messaging
+    backgroundColor: blue
+    textColor: blue
+  - content: Reliability
+    backgroundColor: green
+    textColor: green
+---
+
+## Context
+
+The Product Catalog System is the source of truth for products, and other systems — notably the [[system|search-system]] — depend on a reliable stream of `product-created`, `product-updated` and `product-deleted` events. Publishing to the broker directly from the [[service|product-api]] request path creates a dual-write problem: if the database commit succeeds but the broker publish fails (or vice versa), the catalog and its consumers drift out of sync. Lost or phantom events are hard to detect and expensive to reconcile.
+
+## Decision
+
+The Product API writes every product change **and** a corresponding row in an `outbox` table inside a single database transaction in the [[container|product-database]]. A separate relay, the [[service|product-search-publisher]], reads unpublished outbox rows in order and publishes them to the broker with at-least-once delivery, marking each row published once acknowledged.
+
+This decouples persistence from publishing: the request path only touches the database, and event delivery becomes an independent, retryable concern.
+
+## Consequences
+
+- Events are never lost and never published for a change that rolled back — the change and its event share a transaction boundary.
+- Consumers must be **idempotent**, since at-least-once delivery means an event can be redelivered.
+- There is a small publish latency between the commit and the relay draining the outbox.
+- The outbox table needs a retention/cleanup policy so it doesn't grow unbounded.
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/adrs/adr-002-postgres-as-system-of-record/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/adrs/adr-002-postgres-as-system-of-record/index.mdx
new file mode 100644
index 000000000..a7d5077cb
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/adrs/adr-002-postgres-as-system-of-record/index.mdx
@@ -0,0 +1,40 @@
+---
+id: adr-002-postgres-as-system-of-record
+name: 'ADR-002: Use PostgreSQL as the product system of record'
+summary: Product data is stored in a single PostgreSQL database that acts as the authoritative system of record, with derived stores (like the search index) rebuilt from it.
+version: 1.0.0
+status: accepted
+date: 2026-02-12
+owners:
+  - product-platform
+decisionMakers:
+  - product-platform
+appliesTo:
+  - type: system
+    id: product-catalog-system
+  - type: container
+    id: product-database
+related:
+  - id: adr-001-use-transactional-outbox
+badges:
+  - content: Data
+    backgroundColor: purple
+    textColor: purple
+---
+
+## Context
+
+Products are a small-to-medium, strongly relational dataset (products, categories, pricing, lifecycle status) that needs transactional integrity, an enforceable schema, and the ability to write a change and its outbox event atomically. We also want a single, unambiguous source of truth so that derived stores — such as the [[system|search-system]]'s index — can be treated as disposable and rebuilt at any time.
+
+## Decision
+
+The Product Catalog System uses a single **PostgreSQL** database, the [[container|product-database]], as the authoritative system of record. It holds the `products` table and the outbox table (see [[adr|adr-001-use-transactional-outbox]]). The [[service|product-api]] is the only writer on the request path; the [[service|product-worker]] performs asynchronous enrichment.
+
+Any other representation of product data elsewhere in the business is a **derived read model**, not a source of truth, and must be rebuildable by replaying product events.
+
+## Consequences
+
+- Strong consistency and transactional outbox writes are straightforward with a single relational store.
+- The search index and any future read models can be rebuilt from the catalog, keeping them disposable.
+- The database is a scaling focal point; heavy read traffic should be served from read replicas or downstream read models rather than the primary.
+- Schema changes need migrations and care, since this is the authoritative store.
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/adrs/adr-003-offload-async-work-to-worker/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/adrs/adr-003-offload-async-work-to-worker/index.mdx
new file mode 100644
index 000000000..941e73038
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/adrs/adr-003-offload-async-work-to-worker/index.mdx
@@ -0,0 +1,41 @@
+---
+id: adr-003-offload-async-work-to-worker
+name: 'ADR-003: Offload long-running catalog work to a dedicated worker'
+summary: Slow and asynchronous catalog tasks (enrichment, image processing, bulk imports) run in a separate Product Worker so the Product API stays fast and predictable.
+version: 1.0.0
+status: accepted
+date: 2026-02-18
+owners:
+  - product-platform
+decisionMakers:
+  - product-platform
+appliesTo:
+  - type: system
+    id: product-catalog-system
+  - type: service
+    id: product-worker
+  - type: service
+    id: product-api
+badges:
+  - content: Architecture
+    backgroundColor: blue
+    textColor: blue
+  - content: Performance
+    backgroundColor: green
+    textColor: green
+---
+
+## Context
+
+Some catalog operations are slow or bursty: enriching products with derived attributes, processing and optimising images, and ingesting large supplier feeds. Running this work inline in the [[service|product-api]] request path would make API latency unpredictable and couple the responsiveness of create/update/read operations to whatever heavy job happens to be running.
+
+## Decision
+
+The Product Catalog System runs a dedicated [[service|product-worker]] for long-running and asynchronous tasks. The [[service|product-api]] handles validation, persistence and the outbox write synchronously, then returns; the worker picks up enrichment, media processing and bulk imports independently, reading from and writing back to the [[container|product-database]].
+
+## Consequences
+
+- The Product API has a small, predictable surface and stays fast under load.
+- Heavy work can be scaled, retried and scheduled independently of the API.
+- Some product attributes are **eventually** populated after creation, so consumers must not assume every derived field is present immediately.
+- There are now two services writing to the [[container|product-database]], so write paths must respect the same invariants and avoid conflicting updates.
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/containers/product-database/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/containers/product-database/index.mdx
new file mode 100644
index 000000000..2e3a3ef5e
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/containers/product-database/index.mdx
@@ -0,0 +1,45 @@
+---
+id: product-database
+name: Product Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for all product data.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for products, plus the change outbox used to publish events
+classification: internal
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Product Database** is the authoritative store for every product in the catalog. The [[service|product-api]] reads from and writes to it, and the [[service|product-worker]] uses it for asynchronous enrichment. It also holds the **outbox** table that the [[service|product-search-publisher]] reads to publish product change events.
+
+### What does it store?
+
+- **Products** — one row per product: SKU, name, description, price, currency, category and lifecycle status.
+- **Outbox** — one row per product change, used to reliably publish [[event|product-created]], [[event|product-updated]] and [[event|product-deleted]] events.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Product Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Access patterns
+
+- The [[service|product-api]] is the only writer to the `products` table on the request path.
+- The [[service|product-search-publisher]] is a read-only consumer of the `outbox` table.
+- The [[service|product-worker]] reads and writes for asynchronous enrichment jobs.
+
+### Why an outbox?
+
+Writing the product change and the event in the **same transaction** guarantees we never persist a change without an event, or publish an event for a change that rolled back. The publisher reads the outbox and emits events with at-least-once delivery.
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/containers/product-database/schema.sql b/examples/default/domains/Catalog/systems/product-catalog-system/containers/product-database/schema.sql
new file mode 100644
index 000000000..ad212c2fe
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/containers/product-database/schema.sql
@@ -0,0 +1,33 @@
+-- Product Database — system of record for the product catalog
+
+CREATE TABLE products (
+    product_id   UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    sku          TEXT NOT NULL UNIQUE,
+    name         TEXT NOT NULL,
+    description  TEXT,
+    price_cents  INTEGER NOT NULL CHECK (price_cents >= 0),
+    currency     CHAR(3) NOT NULL,
+    category     TEXT,
+    status       TEXT NOT NULL DEFAULT 'DRAFT'
+                   CHECK (status IN ('DRAFT', 'ACTIVE', 'ARCHIVED')),
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_products_category ON products (category);
+CREATE INDEX idx_products_status   ON products (status);
+
+-- Transactional outbox — change events are written here in the same
+-- transaction as the product change, then drained by the Product Search Publisher.
+CREATE TABLE outbox (
+    id            BIGSERIAL PRIMARY KEY,
+    product_id    UUID NOT NULL REFERENCES products (product_id),
+    event_type    TEXT NOT NULL
+                    CHECK (event_type IN ('ProductCreated', 'ProductUpdated', 'ProductDeleted')),
+    payload       JSONB NOT NULL,
+    occurred_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    published_at  TIMESTAMPTZ
+);
+
+-- Index used by the publisher to find unpublished changes in order.
+CREATE INDEX idx_outbox_unpublished ON outbox (id) WHERE published_at IS NULL;
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/index.mdx
new file mode 100644
index 000000000..d1edaeea2
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/index.mdx
@@ -0,0 +1,72 @@
+---
+id: product-catalog-system
+name: Product Catalog System
+version: 1.0.0
+summary: |
+  Internal system that is the source of truth for product data. Owns the product database and publishes product change events for the rest of the business to consume.
+owners:
+  - product-platform
+services:
+  - id: product-api
+  - id: product-worker
+  - id: product-search-publisher
+containers:
+  - id: product-database
+relationships:
+  - id: search-system
+    label: notifies of product changes
+actors:
+  - id: merchandiser
+    name: Merchandiser
+    label: creates and updates products
+    direction: inbound
+  - id: catalog-admin
+    name: Catalog Admin
+    label: manages categories and pricing
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Product Catalog System** is the system of record for products at Acme Inc. It accepts commands to create, update and delete products, persists them in the [[container|product-database]], and emits domain events whenever product data changes so downstream systems — like the [[system|search-system]] — can react.
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<ComponentDiagram />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|product-api]] | Service | Public-facing API. Handles create/update/delete commands and product reads. |
+| [[service\|product-worker]] | Service | Processes long-running and asynchronous catalog work off the request path. |
+| [[service\|product-search-publisher]] | Service | Publishes product change events for the Search System to consume. |
+| [[container\|product-database]] | Data store | PostgreSQL system of record for all product data. |
+
+## Messages this system publishes
+
+When product data changes, the system emits these events:
+
+- [[event|product-created]] — a new product has been added to the catalog.
+- [[event|product-updated]] — an existing product's data has changed.
+- [[event|product-deleted]] — a product has been removed from the catalog.
+- [[adr|adr-001-use-transactional-outbox]] — a product has been removed from the catalog.
+
+## Architecture decisions
+
+The key decisions that shaped this system. Search, filter by status, or sort by clicking a column.
+
+<ADRTable />
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/CreateProduct/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/CreateProduct/index.mdx
new file mode 100644
index 000000000..d2b7eff42
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/CreateProduct/index.mdx
@@ -0,0 +1,32 @@
+---
+id: create-product
+name: Create Product
+version: 1.0.0
+summary: |
+  Command to add a new product to the catalog.
+owners:
+  - product-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /products
+  statusCodes: ['201', '400', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CreateProduct` is handled by the [[service|product-api]]. It validates the incoming product, writes it to the [[container|product-database]], and on success publishes a [[event|product-created]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/CreateProduct/schema.json b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/CreateProduct/schema.json
new file mode 100644
index 000000000..e363e2ea2
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/CreateProduct/schema.json
@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CreateProduct",
+  "description": "Command to add a new product to the catalog",
+  "type": "object",
+  "properties": {
+    "sku": {
+      "description": "Stock keeping unit — must be unique",
+      "type": "string"
+    },
+    "name": {
+      "description": "Display name of the product",
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "description": "Long-form product description",
+      "type": "string"
+    },
+    "price": {
+      "description": "Price in minor units (e.g. cents)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "currency": {
+      "description": "ISO 4217 currency code",
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "category": {
+      "description": "Category the product belongs to",
+      "type": "string"
+    },
+    "status": {
+      "description": "Initial lifecycle status — defaults to DRAFT",
+      "type": "string",
+      "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+    }
+  },
+  "required": ["sku", "name", "price", "currency"]
+}
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/DeleteProduct/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/DeleteProduct/index.mdx
new file mode 100644
index 000000000..9188d64e6
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/DeleteProduct/index.mdx
@@ -0,0 +1,32 @@
+---
+id: delete-product
+name: Delete Product
+version: 1.0.0
+summary: |
+  Command to remove a product from the catalog.
+owners:
+  - product-platform
+schemaPath: schema.json
+operation:
+  method: DELETE
+  path: /products/{productId}
+  statusCodes: ['204', '404']
+sidebar:
+  badge: 'DELETE'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`DeleteProduct` is handled by the [[service|product-api]]. It removes a product from the [[container|product-database]] and, on success, publishes a [[event|product-deleted]] event so downstream systems can clean up.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/DeleteProduct/schema.json b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/DeleteProduct/schema.json
new file mode 100644
index 000000000..97efc7c2d
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/DeleteProduct/schema.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "DeleteProduct",
+  "description": "Command to remove a product from the catalog",
+  "type": "object",
+  "properties": {
+    "productId": {
+      "description": "Unique identifier of the product to delete",
+      "type": "string",
+      "format": "uuid"
+    },
+    "reason": {
+      "description": "Optional reason the product is being removed",
+      "type": "string",
+      "enum": ["DISCONTINUED", "DUPLICATE", "MERCHANT_REQUEST", "OTHER"]
+    }
+  },
+  "required": ["productId"]
+}
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/UpdateProduct/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/UpdateProduct/index.mdx
new file mode 100644
index 000000000..abb07e52f
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/UpdateProduct/index.mdx
@@ -0,0 +1,32 @@
+---
+id: update-product
+name: Update Product
+version: 1.0.0
+summary: |
+  Command to update an existing product in the catalog.
+owners:
+  - product-platform
+schemaPath: schema.json
+operation:
+  method: PATCH
+  path: /products/{productId}
+  statusCodes: ['200', '400', '404']
+sidebar:
+  badge: 'PATCH'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`UpdateProduct` is handled by the [[service|product-api]]. It applies a partial update to an existing product in the [[container|product-database]] and, on success, publishes a [[event|product-updated]] event describing what changed.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/UpdateProduct/schema.json b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/UpdateProduct/schema.json
new file mode 100644
index 000000000..5fcfac505
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/UpdateProduct/schema.json
@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "UpdateProduct",
+  "description": "Command to update an existing product. Only the fields supplied are changed.",
+  "type": "object",
+  "properties": {
+    "productId": {
+      "description": "Unique identifier of the product to update",
+      "type": "string",
+      "format": "uuid"
+    },
+    "name": {
+      "description": "New display name",
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "description": "New long-form description",
+      "type": "string"
+    },
+    "price": {
+      "description": "New price in minor units (e.g. cents)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "currency": {
+      "description": "ISO 4217 currency code",
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "category": {
+      "description": "New category",
+      "type": "string"
+    },
+    "status": {
+      "description": "New lifecycle status",
+      "type": "string",
+      "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+    }
+  },
+  "required": ["productId"]
+}
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/index.mdx
new file mode 100644
index 000000000..088514800
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: product-created
+name: Product Created
+version: 1.0.0
+summary: |
+  Published when a new product has been added to the catalog.
+owners:
+  - product-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ProductCreated` is published by the [[service|product-search-publisher]] whenever a new product is successfully added to the catalog by the [[service|product-api]]. The [[system|search-system]] consumes this event to index the new product so it becomes discoverable.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/schema.json b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/schema.json
new file mode 100644
index 000000000..25a1f8cd6
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/schema.json
@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ProductCreated",
+  "description": "Emitted when a new product is added to the catalog",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the product was created",
+      "type": "string",
+      "format": "date-time"
+    },
+    "product": {
+      "description": "The product that was created",
+      "type": "object",
+      "properties": {
+        "productId": {
+          "description": "Unique identifier for the product",
+          "type": "string",
+          "format": "uuid"
+        },
+        "sku": {
+          "description": "Stock keeping unit",
+          "type": "string"
+        },
+        "name": {
+          "description": "Display name of the product",
+          "type": "string"
+        },
+        "description": {
+          "description": "Long-form product description",
+          "type": "string"
+        },
+        "price": {
+          "description": "Price in minor units (e.g. cents)",
+          "type": "integer",
+          "minimum": 0
+        },
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "category": {
+          "description": "Category the product belongs to",
+          "type": "string"
+        },
+        "status": {
+          "description": "Lifecycle status of the product",
+          "type": "string",
+          "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+        }
+      },
+      "required": ["productId", "sku", "name", "price", "currency", "status"]
+    }
+  },
+  "required": ["eventId", "occurredAt", "product"]
+}
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/index.mdx
new file mode 100644
index 000000000..30473458e
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/index.mdx
@@ -0,0 +1,29 @@
+---
+id: product-deleted
+name: Product Deleted
+version: 1.0.0
+summary: |
+  Published when a product has been removed from the catalog.
+owners:
+  - product-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ProductDeleted` is published by the [[service|product-search-publisher]] when a product is removed from the catalog via the [[service|product-api]]. The [[system|search-system]] consumes this event to remove the product from the search index.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/schema.json b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/schema.json
new file mode 100644
index 000000000..26cc9a5dc
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/schema.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ProductDeleted",
+  "description": "Emitted when a product is removed from the catalog",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the product was deleted",
+      "type": "string",
+      "format": "date-time"
+    },
+    "productId": {
+      "description": "Unique identifier for the product that was deleted",
+      "type": "string",
+      "format": "uuid"
+    },
+    "reason": {
+      "description": "Optional reason the product was removed",
+      "type": "string",
+      "enum": ["DISCONTINUED", "DUPLICATE", "MERCHANT_REQUEST", "OTHER"]
+    }
+  },
+  "required": ["eventId", "occurredAt", "productId"]
+}
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/index.mdx
new file mode 100644
index 000000000..44e563b74
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: product-updated
+name: Product Updated
+version: 1.0.0
+summary: |
+  Published when an existing product's data has changed.
+owners:
+  - product-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ProductUpdated` is published by the [[service|product-search-publisher]] whenever an existing product is changed via the [[service|product-api]]. The [[system|search-system]] consumes this event to re-index the product so search results stay accurate.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/schema.json b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/schema.json
new file mode 100644
index 000000000..ce744bcb8
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/schema.json
@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ProductUpdated",
+  "description": "Emitted when an existing product's data changes",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the product was updated",
+      "type": "string",
+      "format": "date-time"
+    },
+    "productId": {
+      "description": "Unique identifier for the product that changed",
+      "type": "string",
+      "format": "uuid"
+    },
+    "changes": {
+      "description": "The fields that changed and their new values",
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "price": {
+          "description": "Price in minor units (e.g. cents)",
+          "type": "integer",
+          "minimum": 0
+        },
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "category": {
+          "type": "string"
+        },
+        "status": {
+          "description": "Lifecycle status of the product",
+          "type": "string",
+          "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+        }
+      },
+      "minProperties": 1
+    }
+  },
+  "required": ["eventId", "occurredAt", "productId", "changes"]
+}
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/index.mdx
new file mode 100644
index 000000000..fa787bcd0
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/index.mdx
@@ -0,0 +1,59 @@
+---
+id: product-api
+version: 1.0.0
+name: Product API
+summary: |
+  The public-facing API for the product catalog. Handles commands to create, update and delete products, serves product reads, and is the entry point into the Product Catalog System.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - product-platform
+receives:
+  - id: create-product
+    version: 1.0.0
+  - id: update-product
+    version: 1.0.0
+  - id: delete-product
+    version: 1.0.0
+  - id: get-product
+    version: 1.0.0
+writesTo:
+  - id: product-database
+readsFrom:
+  - id: product-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/product-api'
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Product API
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Product API** is the front door to the Product Catalog System. It validates incoming commands, persists product data to the [[container|product-database]], and records every change to the outbox. The [[service|product-search-publisher]] then turns those changes into the domain events the rest of the business consumes.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="Commands and queries handled by this service" />
+  <Tile icon="CircleStackIcon" href="/docs/services/product-api/1.0.0" title="System of record" description="Reads from and writes to the product database" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Command handling | Validates and applies [[command\|create-product]], [[command\|update-product]] and [[command\|delete-product]]. |
+| Reads | Serves [[query\|get-product]] directly from the product database. |
+| Change capture | Records every product change to the outbox in the [[container\|product-database]] for the [[service\|product-search-publisher]] to publish. |
+| Persistence | Reads from and writes to the [[container\|product-database]] (system of record). |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/openapi.yml b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/openapi.yml
new file mode 100644
index 000000000..695bebdd9
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/openapi.yml
@@ -0,0 +1,219 @@
+openapi: 3.0.3
+info:
+  title: Product API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Product Catalog System. It is the entry point for
+    creating, updating, deleting and reading products. Every change is persisted
+    to the product database and recorded in the outbox so product change events
+    can be published to the rest of the business.
+  contact:
+    name: Product Platform
+    email: product-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+tags:
+  - name: Products
+    description: Manage and read products in the catalog.
+paths:
+  /products:
+    post:
+      operationId: createProduct
+      summary: Create a product
+      description: Adds a new product to the catalog. On success a `ProductCreated` event is published.
+      tags:
+        - Products
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateProductRequest'
+      responses:
+        '201':
+          description: The product was created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Product'
+        '400':
+          description: The request body was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: A product with the same SKU already exists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /products/{productId}:
+    parameters:
+      - $ref: '#/components/parameters/ProductId'
+    get:
+      operationId: getProduct
+      summary: Get a product
+      description: Returns the current state of a single product by its identifier.
+      tags:
+        - Products
+      responses:
+        '200':
+          description: The product was found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Product'
+        '404':
+          description: No product exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    patch:
+      operationId: updateProduct
+      summary: Update a product
+      description: Applies a partial update to an existing product. On success a `ProductUpdated` event is published.
+      tags:
+        - Products
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateProductRequest'
+      responses:
+        '200':
+          description: The product was updated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Product'
+        '400':
+          description: The request body was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: No product exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    delete:
+      operationId: deleteProduct
+      summary: Delete a product
+      description: Removes a product from the catalog. On success a `ProductDeleted` event is published.
+      tags:
+        - Products
+      parameters:
+        - name: reason
+          in: query
+          required: false
+          description: Optional reason the product is being removed.
+          schema:
+            type: string
+            enum: [DISCONTINUED, DUPLICATE, MERCHANT_REQUEST, OTHER]
+      responses:
+        '204':
+          description: The product was deleted.
+        '404':
+          description: No product exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  parameters:
+    ProductId:
+      name: productId
+      in: path
+      required: true
+      description: Unique identifier of the product.
+      schema:
+        type: string
+        format: uuid
+  schemas:
+    Product:
+      type: object
+      required: [productId, sku, name, price, currency, status]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        sku:
+          type: string
+          description: Stock keeping unit.
+        name:
+          type: string
+        description:
+          type: string
+        price:
+          type: integer
+          description: Price in minor units (e.g. cents).
+          minimum: 0
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        category:
+          type: string
+        status:
+          type: string
+          enum: [DRAFT, ACTIVE, ARCHIVED]
+    CreateProductRequest:
+      type: object
+      required: [sku, name, price, currency]
+      properties:
+        sku:
+          type: string
+          description: Stock keeping unit — must be unique.
+        name:
+          type: string
+          minLength: 1
+        description:
+          type: string
+        price:
+          type: integer
+          description: Price in minor units (e.g. cents).
+          minimum: 0
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        category:
+          type: string
+        status:
+          type: string
+          description: Initial lifecycle status — defaults to DRAFT.
+          enum: [DRAFT, ACTIVE, ARCHIVED]
+    UpdateProductRequest:
+      type: object
+      description: Only the fields supplied are changed.
+      minProperties: 1
+      properties:
+        name:
+          type: string
+          minLength: 1
+        description:
+          type: string
+        price:
+          type: integer
+          description: Price in minor units (e.g. cents).
+          minimum: 0
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        category:
+          type: string
+        status:
+          type: string
+          enum: [DRAFT, ACTIVE, ARCHIVED]
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/index.mdx
new file mode 100644
index 000000000..8fec5b3d7
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/index.mdx
@@ -0,0 +1,32 @@
+---
+id: get-product
+name: Get Product
+version: 1.0.0
+summary: |
+  Query to fetch a single product by its identifier.
+owners:
+  - product-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /products/{productId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetProduct` is handled by the [[service|product-api]]. It returns the current state of a single product, read directly from the [[container|product-database]]. Use the [[system|search-system]] when you need to search across many products instead.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/schema.json b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/schema.json
new file mode 100644
index 000000000..651038708
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/schema.json
@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetProduct",
+  "description": "Query to fetch a single product by its identifier, and the product returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "Parameters used to look up the product",
+      "type": "object",
+      "properties": {
+        "productId": {
+          "description": "Unique identifier of the product to fetch",
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "required": ["productId"]
+    },
+    "response": {
+      "description": "The product returned by the query",
+      "type": "object",
+      "properties": {
+        "productId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "sku": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "price": {
+          "description": "Price in minor units (e.g. cents)",
+          "type": "integer"
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "category": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+        }
+      },
+      "required": ["productId", "sku", "name", "price", "currency", "status"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductSearchPublisher/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductSearchPublisher/index.mdx
new file mode 100644
index 000000000..548200ad1
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductSearchPublisher/index.mdx
@@ -0,0 +1,51 @@
+---
+id: product-search-publisher
+version: 1.0.0
+name: Product Search Publisher
+summary: |
+  Reads product changes from the product database (outbox) and reliably publishes product-created, product-updated and product-deleted events for the Search System to consume.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - product-platform
+readsFrom:
+  - id: product-database
+sends:
+  - id: product-created
+    version: 1.0.0
+  - id: product-updated
+    version: 1.0.0
+  - id: product-deleted
+    version: 1.0.0
+repository:
+  language: Go
+  url: 'https://github.com/acme/product-search-publisher'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Product Search Publisher** is the bridge between the Product Catalog System and the rest of the business. It uses the [transactional outbox pattern](https://microservices.io/patterns/data/transactional-outbox.html): the [[service|product-api]] records every product change in the [[container|product-database]], and this service reliably reads those changes and publishes them as [[event|product-created]], [[event|product-updated]] and [[event|product-deleted]] events.
+
+This guarantees that product changes are never lost and are delivered to the [[system|search-system]] in order.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="Product change events published for downstream systems" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Outbox polling | Reads unpublished product changes from the [[container\|product-database]]. |
+| Reliable publishing | Publishes [[event\|product-created]], [[event\|product-updated]] and [[event\|product-deleted]] with at-least-once delivery. |
+| Ordering | Preserves per-product ordering of change events. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductWorker/index.mdx b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductWorker/index.mdx
new file mode 100644
index 000000000..647b2bb30
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/product-catalog-system/services/ProductWorker/index.mdx
@@ -0,0 +1,43 @@
+---
+id: product-worker
+version: 1.0.0
+name: Product Worker
+summary: |
+  Background worker that handles long-running and asynchronous catalog work off the request path, such as enrichment, image processing and bulk imports.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - product-platform
+readsFrom:
+  - id: product-database
+writesTo:
+  - id: product-database
+repository:
+  language: Go
+  url: 'https://github.com/acme/product-worker'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Product Worker** keeps the [[service|product-api]] fast by taking slow or asynchronous work off the request path. It reads from and writes back to the [[container|product-database]], handling jobs like data enrichment, image processing and bulk catalog imports.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title="View in visualiser" description="See how the Product Worker fits into the system" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Enrichment | Augments product records with derived data after they are created or updated. |
+| Media | Processes and optimises product images asynchronously. |
+| Bulk imports | Ingests large product feeds without blocking the API. |
+| Persistence | Reads from and writes to the [[container\|product-database]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/systems/search-system/containers/search-index/index.mdx b/examples/default/domains/Catalog/systems/search-system/containers/search-index/index.mdx
new file mode 100644
index 000000000..7efe54a0c
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/search-system/containers/search-index/index.mdx
@@ -0,0 +1,39 @@
+---
+id: search-index
+name: Search Index
+version: 1.0.0
+summary: The denormalised, search-optimised index of products that powers product search.
+container_type: searchIndex
+technology: opensearch@2
+authoritative: false
+access_mode: readWrite
+purpose: Serve fast, relevant product search
+classification: internal
+retention: rebuildable
+residency: eu-west-1
+styles:
+  icon: /icons/analytics/clickhouse.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Search Index** is a denormalised, search-optimised copy of the catalog. It is **not** a source of truth — it can be rebuilt at any time by replaying product events from the [[system|product-catalog-system]]. The [[service|search-indexer]] keeps it up to date, and the [[service|search-api]] reads from it to answer [[query|search-products]] queries.
+
+### What does it store?
+
+One document per product, optimised for search:
+
+- Searchable text — name and description, analysed for full-text matching.
+- Filterable fields — category, status, price, currency.
+- A relevance signal used to rank results.
+
+### Why is it not authoritative?
+
+The system of record is the [[container|product-database]]. The index is a derived read model: if it is ever lost or corrupted, we rebuild it by replaying [[event|product-created]], [[event|product-updated]] and [[event|product-deleted]] events. This keeps search fast without coupling other teams to the catalog database.
+
+### Operational notes
+
+- **Rebuildable**: a full reindex is a supported, routine operation.
+- **Eventually consistent**: changes appear in search shortly after the [[service|search-indexer]] processes the corresponding event.
diff --git a/examples/default/domains/Catalog/systems/search-system/flows/ProductSearchIndexing/index.mdx b/examples/default/domains/Catalog/systems/search-system/flows/ProductSearchIndexing/index.mdx
new file mode 100644
index 000000000..1e282fa6f
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/search-system/flows/ProductSearchIndexing/index.mdx
@@ -0,0 +1,130 @@
+---
+id: product-search-indexing
+name: Product Search Indexing
+version: 1.0.0
+summary: |
+  How a change to a product in the catalog reliably flows into the search index — via the outbox, product events and the indexer — so search stays in sync without coupling to the catalog database.
+owners:
+  - search-platform
+steps:
+  - id: merchant_edits_product
+    title: Merchant edits a product
+    actor:
+      name: Merchant
+      summary: A merchant creates or updates a product in the catalog.
+    next_step:
+      id: product_api
+      label: Apply change
+
+  - id: product_api
+    title: Product API
+    service:
+      id: product-api
+      version: 1.0.0
+    next_step:
+      id: product_database
+      label: Write change + outbox row
+
+  - id: product_database
+    title: Product Database
+    container:
+      id: product-database
+    next_step:
+      id: outbox_note
+      label: Outbox row committed
+
+  - id: outbox_note
+    title: Outbox pattern
+    custom:
+      title: Transactional outbox
+      color: blue
+      icon: InboxStackIcon
+      type: Pattern
+      summary: The product change and an outbox row are written in the same transaction, so the event can never be lost or out of sync with the data.
+      properties:
+        guarantee: 'change and event are atomic'
+    next_step:
+      id: product_search_publisher
+      label: Drain outbox
+
+  - id: product_search_publisher
+    title: Product Search Publisher
+    service:
+      id: product-search-publisher
+      version: 1.0.0
+    next_steps:
+      - id: product_created
+        label: Created
+      - id: product_updated
+        label: Updated
+      - id: product_deleted
+        label: Deleted
+
+  - id: product_created
+    title: Product Created
+    message:
+      id: product-created
+      version: 1.0.0
+    next_step:
+      id: search_indexer
+      label: Index product
+
+  - id: product_updated
+    title: Product Updated
+    message:
+      id: product-updated
+      version: 1.0.0
+    next_step:
+      id: search_indexer
+      label: Re-index product
+
+  - id: product_deleted
+    title: Product Deleted
+    message:
+      id: product-deleted
+      version: 1.0.0
+    next_step:
+      id: search_indexer
+      label: Remove from index
+
+  - id: search_indexer
+    title: Search Indexer
+    service:
+      id: search-indexer
+      version: 1.0.0
+    next_step:
+      id: search_index
+      label: Apply to index
+
+  - id: search_index
+    title: Search Index
+    container:
+      id: search-index
+    next_step:
+      id: searchable
+      label: Available to search
+
+  - id: searchable
+    title: Product is searchable
+    custom:
+      title: Product is searchable
+      color: green
+      icon: MagnifyingGlassIcon
+      type: Outcome
+      summary: The change is reflected in the search index and immediately available to customers via the Search API.
+      properties:
+        read_model: 'derived, rebuildable from events'
+---
+
+## Overview
+
+**Product Search Indexing** documents how the [[system|search-system]] keeps its index in sync with the catalog. The search index is a derived read model — never a source of truth — so it can be rebuilt at any time by replaying product events.
+
+<NodeGraph />
+
+## How it works
+
+1. A merchant changes a product via the [[service|product-api]], which writes the change and an outbox row to the [[container|product-database]] in one transaction.
+2. The [[service|product-search-publisher]] reliably drains the outbox and publishes [[event|product-created]], [[event|product-updated]] or [[event|product-deleted]].
+3. The [[service|search-indexer]] consumes those events and applies them to the [[container|search-index]].
+4. The change is now searchable via the Search API — with no direct coupling between search and the catalog database.
diff --git a/examples/default/domains/Catalog/systems/search-system/index.mdx b/examples/default/domains/Catalog/systems/search-system/index.mdx
new file mode 100644
index 000000000..ff89df792
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/search-system/index.mdx
@@ -0,0 +1,66 @@
+---
+id: search-system
+name: Search System
+version: 1.0.0
+summary: |
+  Internal system that keeps product data searchable. Consumes product change events from the Product Catalog System, maintains a search index, and serves fast product search to the rest of the business.
+owners:
+  - search-platform
+services:
+  - id: search-api
+  - id: search-indexer
+containers:
+  - id: search-index
+flows:
+  - id: product-search-indexing
+    version: 1.0.0
+relationships:
+  - id: product-catalog-system
+    label: indexes product changes from
+actors:
+  - id: shopper
+    name: Shopper
+    label: searches for products
+    direction: inbound
+  - id: storefront-team
+    name: Storefront Team
+    label: integrates product search
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Search System** makes the catalog discoverable. It subscribes to product change events published by the [[system|product-catalog-system]], updates its [[container|search-index]], and exposes a search API so other teams can find products without ever touching the catalog database directly.
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|search-api]] | Service | Public-facing API. Serves product search queries from the index. |
+| [[service\|search-indexer]] | Service | Consumes product change events and keeps the search index up to date. |
+| [[container\|search-index]] | Data store | The index that powers product search. |
+
+## Messages this system consumes
+
+The Search System reacts to product changes published by the Product Catalog System:
+
+- [[event|product-created]] — index the new product.
+- [[event|product-updated]] — re-index the changed product.
+- [[event|product-deleted]] — remove the product from the index.
diff --git a/examples/default/domains/Catalog/systems/search-system/services/SearchAPI/index.mdx b/examples/default/domains/Catalog/systems/search-system/services/SearchAPI/index.mdx
new file mode 100644
index 000000000..24898ef4c
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/search-system/services/SearchAPI/index.mdx
@@ -0,0 +1,44 @@
+---
+id: search-api
+version: 1.0.0
+name: Search API
+summary: |
+  Public-facing API that serves fast, relevant product search to the rest of the business, reading from the search index.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - search-platform
+receives:
+  - id: search-products
+    version: 1.0.0
+readsFrom:
+  - id: search-index
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/search-api'
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Search API
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Search API** is the front door to the Search System. It answers [[query|search-products]] queries by reading from the [[container|search-index]], which is kept current by the [[service|search-indexer]]. Other teams use this API so they never have to query the catalog database directly.
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Search | Serves [[query\|search-products]] with full-text matching, filtering and pagination. |
+| Reads | Queries the [[container\|search-index]] — never the catalog database. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/systems/search-system/services/SearchAPI/openapi.yml b/examples/default/domains/Catalog/systems/search-system/services/SearchAPI/openapi.yml
new file mode 100644
index 000000000..d90532519
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/search-system/services/SearchAPI/openapi.yml
@@ -0,0 +1,138 @@
+openapi: 3.0.3
+info:
+  title: Search API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Search System. Serves fast, relevant product
+    search by reading from the search index, which is kept in sync with the
+    product catalog.
+  contact:
+    name: Search Platform
+    email: search-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+paths:
+  /search/products:
+    get:
+      operationId: searchProducts
+      summary: Search the catalog for products
+      description: |
+        Runs a full-text search over the product index and returns a paginated
+        list of matching products. Supports optional filters and pagination.
+      tags:
+        - Search
+      parameters:
+        - name: query
+          in: query
+          required: true
+          description: Free-text search term.
+          schema:
+            type: string
+            minLength: 1
+          example: wireless headphones
+        - name: category
+          in: query
+          required: false
+          description: Restrict results to a single category.
+          schema:
+            type: string
+          example: audio
+        - name: status
+          in: query
+          required: false
+          description: Restrict results to products with this lifecycle status.
+          schema:
+            type: string
+            enum: [DRAFT, ACTIVE, ARCHIVED]
+        - name: minPrice
+          in: query
+          required: false
+          description: Minimum price in minor units (e.g. cents).
+          schema:
+            type: integer
+            minimum: 0
+        - name: maxPrice
+          in: query
+          required: false
+          description: Maximum price in minor units (e.g. cents).
+          schema:
+            type: integer
+            minimum: 0
+        - name: page
+          in: query
+          required: false
+          description: 1-based page number.
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - name: pageSize
+          in: query
+          required: false
+          description: Number of results per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        '200':
+          description: A paginated list of matching products.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SearchResults'
+        '400':
+          description: The request was invalid (e.g. a missing or empty query).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  schemas:
+    SearchResults:
+      type: object
+      required: [total, page, pageSize, results]
+      properties:
+        total:
+          type: integer
+          description: Total number of products matching the query.
+        page:
+          type: integer
+        pageSize:
+          type: integer
+        results:
+          type: array
+          items:
+            $ref: '#/components/schemas/ProductSearchResult'
+    ProductSearchResult:
+      type: object
+      required: [productId, sku, name]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        sku:
+          type: string
+        name:
+          type: string
+        category:
+          type: string
+        price:
+          type: integer
+          description: Price in minor units (e.g. cents).
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        score:
+          type: number
+          description: Relevance score for this result.
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string
diff --git a/examples/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/index.mdx b/examples/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/index.mdx
new file mode 100644
index 000000000..49184611b
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/index.mdx
@@ -0,0 +1,32 @@
+---
+id: search-products
+name: Search Products
+version: 1.0.0
+summary: |
+  Query to search the catalog for products matching a term, with optional filters and pagination.
+owners:
+  - search-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /search/products
+  statusCodes: ['200', '400']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`SearchProducts` is handled by the [[service|search-api]]. It runs a full-text search over the [[container|search-index]] and returns a paginated list of matching products. Use this whenever you need to find products across the catalog, rather than fetching a single product by id with [[query|get-product]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/schema.json b/examples/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/schema.json
new file mode 100644
index 000000000..d9eea41f8
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/schema.json
@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SearchProducts",
+  "description": "Query to search the catalog for products, and the paginated result returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "Search parameters",
+      "type": "object",
+      "properties": {
+        "query": {
+          "description": "Free-text search term",
+          "type": "string",
+          "minLength": 1
+        },
+        "filters": {
+          "description": "Optional filters applied to the search",
+          "type": "object",
+          "properties": {
+            "category": {
+              "type": "string"
+            },
+            "status": {
+              "type": "string",
+              "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+            },
+            "minPrice": {
+              "description": "Minimum price in minor units (e.g. cents)",
+              "type": "integer",
+              "minimum": 0
+            },
+            "maxPrice": {
+              "description": "Maximum price in minor units (e.g. cents)",
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "page": {
+          "description": "1-based page number",
+          "type": "integer",
+          "minimum": 1,
+          "default": 1
+        },
+        "pageSize": {
+          "description": "Number of results per page",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "default": 20
+        }
+      },
+      "required": ["query"]
+    },
+    "response": {
+      "description": "Paginated search results",
+      "type": "object",
+      "properties": {
+        "total": {
+          "description": "Total number of products matching the query",
+          "type": "integer"
+        },
+        "page": {
+          "type": "integer"
+        },
+        "pageSize": {
+          "type": "integer"
+        },
+        "results": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "productId": {
+                "type": "string",
+                "format": "uuid"
+              },
+              "sku": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              },
+              "category": {
+                "type": "string"
+              },
+              "price": {
+                "description": "Price in minor units (e.g. cents)",
+                "type": "integer"
+              },
+              "currency": {
+                "type": "string",
+                "pattern": "^[A-Z]{3}$"
+              },
+              "score": {
+                "description": "Relevance score for this result",
+                "type": "number"
+              }
+            },
+            "required": ["productId", "sku", "name"]
+          }
+        }
+      },
+      "required": ["total", "page", "pageSize", "results"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/examples/default/domains/Catalog/systems/search-system/services/SearchIndexer/index.mdx b/examples/default/domains/Catalog/systems/search-system/services/SearchIndexer/index.mdx
new file mode 100644
index 000000000..3c2a7f859
--- /dev/null
+++ b/examples/default/domains/Catalog/systems/search-system/services/SearchIndexer/index.mdx
@@ -0,0 +1,49 @@
+---
+id: search-indexer
+version: 1.0.0
+name: Search Indexer
+summary: |
+  Consumes product change events from the Product Catalog System and keeps the search index up to date so products are discoverable.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - search-platform
+receives:
+  - id: product-created
+    version: 1.0.0
+  - id: product-updated
+    version: 1.0.0
+  - id: product-deleted
+    version: 1.0.0
+writesTo:
+  - id: search-index
+repository:
+  language: Go
+  url: 'https://github.com/acme/search-indexer'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Search Indexer** is how the Search System stays in sync with the catalog. It subscribes to [[event|product-created]], [[event|product-updated]] and [[event|product-deleted]] events published by the [[system|product-catalog-system]] and applies each change to the [[container|search-index]].
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="Product change events consumed from the catalog" />
+</Tiles>
+
+### Responsibilities
+
+| Event | Action |
+|-------|--------|
+| [[event\|product-created]] | Add the new product to the [[container\|search-index]]. |
+| [[event\|product-updated]] | Re-index the changed product. |
+| [[event\|product-deleted]] | Remove the product from the index. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />
diff --git a/examples/default/domains/Catalog/ubiquitous-language.mdx b/examples/default/domains/Catalog/ubiquitous-language.mdx
new file mode 100644
index 000000000..60b5ae7d4
--- /dev/null
+++ b/examples/default/domains/Catalog/ubiquitous-language.mdx
@@ -0,0 +1,54 @@
+---
+dictionary:
+  - id: Product
+    name: Product
+    summary: "A single item Acme Inc sells, with a name, price, category and lifecycle status."
+    description: |
+      A product is the central concept of the Catalog domain. It is owned and maintained by the
+      Product Catalog System, which is the source of truth for all product data. A product carries:
+
+      - A unique product id and a unique SKU
+      - Display name, description and category
+      - Price (in minor units) and currency
+      - A lifecycle status (DRAFT, ACTIVE or ARCHIVED)
+
+      Every change to a product publishes a domain event so the rest of the business — including
+      search — can react.
+    icon: Package
+  - id: SKU
+    name: SKU
+    summary: "Stock Keeping Unit — the unique, human-meaningful code that identifies a product."
+    description: |
+      A SKU uniquely identifies a product in the catalog and must be unique across all products.
+      Unlike the internal product id (a UUID), the SKU is the code teams and merchants use day to day.
+    icon: Tag
+  - id: Catalog
+    name: Catalog
+    summary: "The complete, authoritative collection of products Acme Inc offers."
+    icon: BookOpen
+  - id: Search Index
+    name: Search Index
+    summary: "A denormalised, search-optimised copy of the catalog that powers product search."
+    description: |
+      The search index is a derived read model, not a source of truth. It is kept in sync by the
+      Search System consuming product change events, and can be rebuilt at any time by replaying
+      those events. It exists to serve fast, relevant search without coupling consumers to the
+      catalog database.
+    icon: Search
+  - id: Lifecycle Status
+    name: Lifecycle Status
+    summary: "Where a product sits in its life: DRAFT, ACTIVE or ARCHIVED."
+    description: |
+      - DRAFT — being prepared, not yet visible to customers.
+      - ACTIVE — live and discoverable.
+      - ARCHIVED — withdrawn from sale but retained for history.
+    icon: Workflow
+  - id: Outbox
+    name: Outbox
+    summary: "A table where product changes are recorded in the same transaction, then published as events."
+    description: |
+      The outbox is how the Product Catalog System guarantees that a product change and its event
+      are never out of sync. The Product API writes the change and an outbox row in one transaction;
+      the Product Search Publisher reliably drains the outbox to the broker.
+    icon: Mail
+---
diff --git a/examples/default/domains/Customer/entities/authentication-session/index.mdx b/examples/default/domains/Customer/entities/authentication-session/index.mdx
new file mode 100644
index 000000000..967bdbf94
--- /dev/null
+++ b/examples/default/domains/Customer/entities/authentication-session/index.mdx
@@ -0,0 +1,35 @@
+---
+id: authentication-session
+name: Authentication Session
+version: 1.0.0
+identifier: sessionId
+summary: A successful customer authentication session.
+owners:
+  - customer-platform
+properties:
+  - name: sessionId
+    type: UUID
+    required: true
+    description: Unique authentication session identifier.
+  - name: accountId
+    type: UUID
+    required: true
+    description: Account authenticated in the session.
+    references: customer-account
+    relationType: belongsTo
+    referencesIdentifier: accountId
+  - name: authenticatedAt
+    type: datetime
+    required: true
+    description: Time authentication succeeded.
+  - name: expiresAt
+    type: datetime
+    required: true
+    description: Time the session expires.
+---
+
+## Overview
+
+Authentication Session represents successful login behavior emitted by [[event|customer-authenticated]].
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Customer/entities/customer-account/index.mdx b/examples/default/domains/Customer/entities/customer-account/index.mdx
new file mode 100644
index 000000000..032cd7b1a
--- /dev/null
+++ b/examples/default/domains/Customer/entities/customer-account/index.mdx
@@ -0,0 +1,36 @@
+---
+id: customer-account
+name: Customer Account
+version: 1.0.0
+identifier: accountId
+aggregateRoot: true
+summary: The identity account used to authenticate a customer.
+owners:
+  - customer-platform
+properties:
+  - name: accountId
+    type: UUID
+    required: true
+    description: Unique account identifier.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer profile linked to this account.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: provider
+    type: string
+    required: true
+    description: Identity provider name.
+  - name: status
+    type: string
+    required: true
+    description: Account lifecycle state.
+---
+
+## Overview
+
+Customer Account belongs to the Identity Provider boundary and should not be queried directly by order, payment or review services.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Customer/entities/customer-address/index.mdx b/examples/default/domains/Customer/entities/customer-address/index.mdx
new file mode 100644
index 000000000..cc2b0fa83
--- /dev/null
+++ b/examples/default/domains/Customer/entities/customer-address/index.mdx
@@ -0,0 +1,35 @@
+---
+id: customer-address
+name: Customer Address
+version: 1.0.0
+identifier: addressId
+summary: A saved address attached to a customer profile.
+owners:
+  - customer-platform
+properties:
+  - name: addressId
+    type: UUID
+    required: true
+    description: Unique address identifier.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer who owns the address.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: countryCode
+    type: string
+    required: true
+    description: ISO country code.
+  - name: postalCode
+    type: string
+    required: true
+    description: Postal or ZIP code.
+---
+
+## Overview
+
+Customer Address supports checkout and fulfilment while remaining owned by the Customer domain.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Customer/entities/customer-profile/index.mdx b/examples/default/domains/Customer/entities/customer-profile/index.mdx
new file mode 100644
index 000000000..6cf87760e
--- /dev/null
+++ b/examples/default/domains/Customer/entities/customer-profile/index.mdx
@@ -0,0 +1,33 @@
+---
+id: customer-profile
+name: Customer Profile
+version: 1.0.0
+identifier: customerId
+aggregateRoot: true
+summary: The customer details Acme uses for commerce interactions.
+owners:
+  - customer-platform
+properties:
+  - name: customerId
+    type: UUID
+    required: true
+    description: Unique customer identifier.
+  - name: email
+    type: string
+    required: true
+    description: Customer email address.
+  - name: displayName
+    type: string
+    required: false
+    description: Preferred customer display name.
+  - name: status
+    type: string
+    required: true
+    description: Customer profile state.
+---
+
+## Overview
+
+Customer Profile is owned by [[system|customer-management-system]] and is separate from authentication credentials.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Customer/index.mdx b/examples/default/domains/Customer/index.mdx
new file mode 100644
index 000000000..ba85455db
--- /dev/null
+++ b/examples/default/domains/Customer/index.mdx
@@ -0,0 +1,67 @@
+---
+id: customer
+name: Customer
+version: 1.0.0
+summary: |
+  The Customer domain owns who our customers are — how they register, how their profile is maintained, and how they are authenticated across Acme Inc. It is the source of truth for customer identity and profile data.
+owners:
+  - customer-platform
+systems:
+  - id: customer-management-system
+    version: 1.0.0
+  - id: identity-provider
+    version: 1.0.0
+entities:
+  - id: customer-profile
+    version: 1.0.0
+  - id: customer-account
+    version: 1.0.0
+  - id: authentication-session
+    version: 1.0.0
+  - id: customer-address
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Customer** domain is responsible for the lifecycle of every customer account at Acme Inc — registration, profile updates, and authentication. It is split into two systems:
+
+<Tiles>
+  <Tile
+    icon="RectangleGroupIcon"
+    href="/docs/systems/customer-management-system/1.0.0"
+    title="Customer Management System"
+    description="System of record for customer profiles — register, update and read customers."
+  />
+  <Tile
+    icon="LockClosedIcon"
+    href="/docs/systems/identity-provider/1.0.0"
+    title="Identity Provider"
+    description="Authenticates customers and is the source of truth for credentials and login."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Customer Management System** owns customer profile data — it accepts registration and update commands and publishes events when customers change. The **Identity Provider** handles authentication: it verifies credentials and emits an event when a customer successfully authenticates, which the rest of the business can react to.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The components that make up this domain.
+
+<NodeGraph />
diff --git a/examples/default/domains/Customer/systems/customer-management-system/containers/customer-database/index.mdx b/examples/default/domains/Customer/systems/customer-management-system/containers/customer-database/index.mdx
new file mode 100644
index 000000000..f080e0dce
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/containers/customer-database/index.mdx
@@ -0,0 +1,43 @@
+---
+id: customer-database
+name: Customer Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for all customer profile data.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for customer profiles
+classification: confidential
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Customer Database** is the authoritative store for every customer profile at Acme Inc. The [[service|customer-api]] reads from and writes to it. It stores profile data only — credentials and authentication live in the [[system|identity-provider]]'s [[container|user-directory]], not here.
+
+### What does it store?
+
+- **Customers** — one row per customer: id, email, name and account status.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Customer Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Access patterns
+
+- The [[service|customer-api]] is the only writer on the request path.
+- No credentials or passwords are stored here — only profile data. Authentication is owned by the [[system|identity-provider]].
+
+### Classification
+
+Customer profile data is **confidential**. Access is role-based and least-privilege; PII handling follows Acme's data policies.
diff --git a/examples/default/domains/Customer/systems/customer-management-system/containers/customer-database/schema.sql b/examples/default/domains/Customer/systems/customer-management-system/containers/customer-database/schema.sql
new file mode 100644
index 000000000..dc7cb2851
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/containers/customer-database/schema.sql
@@ -0,0 +1,14 @@
+-- Customer Database — system of record for customer profiles
+-- Note: credentials/authentication are owned by the Identity Provider, not stored here.
+
+CREATE TABLE customers (
+    customer_id  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email        TEXT NOT NULL UNIQUE,
+    name         TEXT,
+    status       TEXT NOT NULL DEFAULT 'ACTIVE'
+                   CHECK (status IN ('ACTIVE', 'SUSPENDED', 'CLOSED')),
+    registered_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_customers_status ON customers (status);
diff --git a/examples/default/domains/Customer/systems/customer-management-system/index.mdx b/examples/default/domains/Customer/systems/customer-management-system/index.mdx
new file mode 100644
index 000000000..1ac794923
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/index.mdx
@@ -0,0 +1,60 @@
+---
+id: customer-management-system
+name: Customer Management System
+version: 1.0.0
+summary: |
+  Internal system that is the source of truth for customer profile data. Owns the customer database and publishes customer change events for the rest of the business to consume.
+owners:
+  - customer-platform
+services:
+  - id: customer-api
+containers:
+  - id: customer-database
+relationships:
+  - id: identity-provider
+    label: delegates authentication to
+actors:
+  - id: customer
+    name: Customer
+    label: registers and updates their profile
+    direction: inbound
+  - id: support-agent
+    name: Support Agent
+    label: looks up customer details
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Customer Management System** is the system of record for customer profiles at Acme Inc. It accepts commands to register and update customers, persists them in the [[container|customer-database]], and emits domain events whenever customer data changes so downstream systems can react. It delegates authentication to the [[system|identity-provider]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|customer-api]] | Service | Public-facing API. Handles register/update commands and customer reads, and publishes customer change events. |
+| [[container\|customer-database]] | Data store | PostgreSQL system of record for all customer profile data. |
+
+## Messages this system publishes
+
+When customer data changes, the system emits these events:
+
+- [[event|customer-registered]] — a new customer has registered.
+- [[event|customer-updated]] — an existing customer's profile has changed.
diff --git a/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/RegisterCustomer/index.mdx b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/RegisterCustomer/index.mdx
new file mode 100644
index 000000000..e63124576
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/RegisterCustomer/index.mdx
@@ -0,0 +1,32 @@
+---
+id: register-customer
+name: Register Customer
+version: 1.0.0
+summary: |
+  Command to register a new customer.
+owners:
+  - customer-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /customers
+  statusCodes: ['201', '400', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RegisterCustomer` is handled by the [[service|customer-api]]. It validates the new customer, writes it to the [[container|customer-database]], and on success publishes a [[event|customer-registered]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/RegisterCustomer/schema.json b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/RegisterCustomer/schema.json
new file mode 100644
index 000000000..91d5fc594
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/RegisterCustomer/schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RegisterCustomer",
+  "description": "Command to register a new customer",
+  "type": "object",
+  "properties": {
+    "email": {
+      "description": "Customer's email address — must be unique",
+      "type": "string",
+      "format": "email"
+    },
+    "name": {
+      "description": "Customer's full name",
+      "type": "string",
+      "minLength": 1
+    },
+    "password": {
+      "description": "Initial password for the customer's credentials",
+      "type": "string",
+      "minLength": 8
+    }
+  },
+  "required": ["email", "password"]
+}
diff --git a/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/UpdateCustomer/index.mdx b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/UpdateCustomer/index.mdx
new file mode 100644
index 000000000..136714bb2
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/UpdateCustomer/index.mdx
@@ -0,0 +1,32 @@
+---
+id: update-customer
+name: Update Customer
+version: 1.0.0
+summary: |
+  Command to update an existing customer's profile.
+owners:
+  - customer-platform
+schemaPath: schema.json
+operation:
+  method: PATCH
+  path: /customers/{customerId}
+  statusCodes: ['200', '400', '404']
+sidebar:
+  badge: 'PATCH'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`UpdateCustomer` is handled by the [[service|customer-api]]. It applies a partial update to an existing customer in the [[container|customer-database]] and, on success, publishes a [[event|customer-updated]] event describing what changed.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/UpdateCustomer/schema.json b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/UpdateCustomer/schema.json
new file mode 100644
index 000000000..a9360cea1
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/UpdateCustomer/schema.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "UpdateCustomer",
+  "description": "Command to update an existing customer. Only the fields supplied are changed.",
+  "type": "object",
+  "properties": {
+    "customerId": {
+      "description": "Unique identifier of the customer to update",
+      "type": "string",
+      "format": "uuid"
+    },
+    "email": {
+      "description": "New email address",
+      "type": "string",
+      "format": "email"
+    },
+    "name": {
+      "description": "New full name",
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "description": "New account status",
+      "type": "string",
+      "enum": ["ACTIVE", "SUSPENDED", "CLOSED"]
+    }
+  },
+  "required": ["customerId"]
+}
diff --git a/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerRegistered/index.mdx b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerRegistered/index.mdx
new file mode 100644
index 000000000..b2b9adf91
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerRegistered/index.mdx
@@ -0,0 +1,29 @@
+---
+id: customer-registered
+name: Customer Registered
+version: 1.0.0
+summary: |
+  Published when a new customer has registered.
+owners:
+  - customer-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CustomerRegistered` is published by the [[service|customer-api]] whenever a new customer successfully registers. Downstream systems consume this event to onboard the customer.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerRegistered/schema.json b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerRegistered/schema.json
new file mode 100644
index 000000000..b9e1d6503
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerRegistered/schema.json
@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CustomerRegistered",
+  "description": "Emitted when a new customer registers",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the customer registered",
+      "type": "string",
+      "format": "date-time"
+    },
+    "customer": {
+      "description": "The customer that registered",
+      "type": "object",
+      "properties": {
+        "customerId": {
+          "description": "Unique identifier for the customer",
+          "type": "string",
+          "format": "uuid"
+        },
+        "email": {
+          "description": "Customer's email address",
+          "type": "string",
+          "format": "email"
+        },
+        "name": {
+          "description": "Customer's full name",
+          "type": "string"
+        },
+        "status": {
+          "description": "Lifecycle status of the customer account",
+          "type": "string",
+          "enum": ["ACTIVE", "SUSPENDED", "CLOSED"]
+        }
+      },
+      "required": ["customerId", "email", "status"]
+    }
+  },
+  "required": ["eventId", "occurredAt", "customer"]
+}
diff --git a/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/index.mdx b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/index.mdx
new file mode 100644
index 000000000..fee2d39e7
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: customer-updated
+name: Customer Updated
+version: 1.0.0
+summary: |
+  Published when an existing customer's profile has changed.
+owners:
+  - customer-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CustomerUpdated` is published by the [[service|customer-api]] whenever an existing customer's profile changes. Downstream systems consume this event to keep their copy of customer data in sync.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/schema.json b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/schema.json
new file mode 100644
index 000000000..40069594f
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/schema.json
@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CustomerUpdated",
+  "description": "Emitted when an existing customer's profile changes",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the customer was updated",
+      "type": "string",
+      "format": "date-time"
+    },
+    "customerId": {
+      "description": "Unique identifier for the customer that changed",
+      "type": "string",
+      "format": "uuid"
+    },
+    "changes": {
+      "description": "The fields that changed and their new values",
+      "type": "object",
+      "properties": {
+        "email": {
+          "type": "string",
+          "format": "email"
+        },
+        "name": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["ACTIVE", "SUSPENDED", "CLOSED"]
+        }
+      },
+      "minProperties": 1
+    }
+  },
+  "required": ["eventId", "occurredAt", "customerId", "changes"]
+}
diff --git a/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/index.mdx b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/index.mdx
new file mode 100644
index 000000000..7c4831bd0
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/index.mdx
@@ -0,0 +1,62 @@
+---
+id: customer-api
+version: 1.0.0
+name: Customer API
+summary: |
+  The public-facing API for customer profiles. Handles commands to register and update customers, serves customer reads, and publishes customer change events.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - customer-platform
+receives:
+  - id: register-customer
+    version: 1.0.0
+  - id: update-customer
+    version: 1.0.0
+  - id: get-customer
+    version: 1.0.0
+sends:
+  - id: customer-registered
+    version: 1.0.0
+  - id: customer-updated
+    version: 1.0.0
+writesTo:
+  - id: customer-database
+readsFrom:
+  - id: customer-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/customer-api'
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Customer API
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Customer API** is the front door to the Customer Management System. It validates incoming commands, persists customer data to the [[container|customer-database]], and publishes domain events (<ResourceLink id="customer-registered" type="event">CustomerRegistered</ResourceLink>, <ResourceLink id="customer-updated" type="event">CustomerUpdated</ResourceLink>) so the rest of the business can react to changes.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="Domain events published when customer data changes" />
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="Commands and queries handled by this service" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Command handling | Validates and applies [[command\|register-customer]] and [[command\|update-customer]]. |
+| Reads | Serves [[query\|get-customer]] directly from the customer database. |
+| Event publishing | Emits [[event\|customer-registered]] and [[event\|customer-updated]] on every change. |
+| Persistence | Reads from and writes to the [[container\|customer-database]] (system of record). |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/openapi.yml b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/openapi.yml
new file mode 100644
index 000000000..40f6aeb04
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/openapi.yml
@@ -0,0 +1,164 @@
+openapi: 3.0.3
+info:
+  title: Customer API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Customer Management System. It is the entry point
+    for registering, updating and reading customers. Every change is persisted
+    to the customer database and published as a customer change event.
+  contact:
+    name: Customer Platform
+    email: customer-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+tags:
+  - name: Customers
+    description: Manage and read customer profiles.
+paths:
+  /customers:
+    post:
+      operationId: registerCustomer
+      summary: Register a customer
+      description: Registers a new customer. On success a `CustomerRegistered` event is published.
+      tags:
+        - Customers
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegisterCustomerRequest'
+      responses:
+        '201':
+          description: The customer was registered.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Customer'
+        '400':
+          description: The request body was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: A customer with the same email already exists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /customers/{customerId}:
+    parameters:
+      - name: customerId
+        in: path
+        required: true
+        description: Unique identifier of the customer.
+        schema:
+          type: string
+          format: uuid
+    get:
+      operationId: getCustomer
+      summary: Get a customer
+      description: Returns the current state of a single customer by their identifier.
+      tags:
+        - Customers
+      responses:
+        '200':
+          description: The customer was found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Customer'
+        '404':
+          description: No customer exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    patch:
+      operationId: updateCustomer
+      summary: Update a customer
+      description: Applies a partial update to an existing customer. On success a `CustomerUpdated` event is published.
+      tags:
+        - Customers
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateCustomerRequest'
+      responses:
+        '200':
+          description: The customer was updated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Customer'
+        '400':
+          description: The request body was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: No customer exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  schemas:
+    Customer:
+      type: object
+      required: [customerId, email, status]
+      properties:
+        customerId:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+        status:
+          type: string
+          enum: [ACTIVE, SUSPENDED, CLOSED]
+        registeredAt:
+          type: string
+          format: date-time
+    RegisterCustomerRequest:
+      type: object
+      required: [email, password]
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          minLength: 1
+        password:
+          type: string
+          minLength: 8
+    UpdateCustomerRequest:
+      type: object
+      description: Only the fields supplied are changed.
+      minProperties: 1
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          minLength: 1
+        status:
+          type: string
+          enum: [ACTIVE, SUSPENDED, CLOSED]
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string
diff --git a/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/index.mdx b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/index.mdx
new file mode 100644
index 000000000..02094e07d
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/index.mdx
@@ -0,0 +1,32 @@
+---
+id: get-customer
+name: Get Customer
+version: 1.0.0
+summary: |
+  Query to fetch a single customer by their identifier.
+owners:
+  - customer-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /customers/{customerId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetCustomer` is handled by the [[service|customer-api]]. It returns the current state of a single customer, read directly from the [[container|customer-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/schema.json b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/schema.json
new file mode 100644
index 000000000..f42128b64
--- /dev/null
+++ b/examples/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/schema.json
@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetCustomer",
+  "description": "Query to fetch a single customer by their identifier, and the customer returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "Parameters used to look up the customer",
+      "type": "object",
+      "properties": {
+        "customerId": {
+          "description": "Unique identifier of the customer to fetch",
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "required": ["customerId"]
+    },
+    "response": {
+      "description": "The customer returned by the query",
+      "type": "object",
+      "properties": {
+        "customerId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "email": {
+          "type": "string",
+          "format": "email"
+        },
+        "name": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["ACTIVE", "SUSPENDED", "CLOSED"]
+        },
+        "registeredAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "required": ["customerId", "email", "status"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/examples/default/domains/Customer/systems/identity-provider/containers/user-directory/index.mdx b/examples/default/domains/Customer/systems/identity-provider/containers/user-directory/index.mdx
new file mode 100644
index 000000000..30932eb03
--- /dev/null
+++ b/examples/default/domains/Customer/systems/identity-provider/containers/user-directory/index.mdx
@@ -0,0 +1,36 @@
+---
+id: user-directory
+name: User Directory
+version: 1.0.0
+summary: The directory of customer credentials and identities — the source of truth for authentication.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for credentials and login identities
+classification: regulated
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **User Directory** is the authoritative store for customer credentials and login identities. The [[service|oauth-api]] reads from it to verify sign-in attempts. It holds **only** authentication data — customer profile data lives separately in the [[system|customer-management-system]]'s [[container|customer-database]].
+
+### What does it store?
+
+- **Identities** — one record per customer: the login email and a securely hashed credential.
+- **Login metadata** — last login time, multi-factor settings, lockout state.
+
+### Why is it separate from the customer profile?
+
+Keeping credentials in a dedicated, **regulated**-classification store isolates the most sensitive data from general profile data. Authentication is owned by the Identity Provider; the Customer Management System never sees raw credentials.
+
+### Security
+
+- Credentials are stored only as salted, hashed values — never in plaintext.
+- Access is tightly restricted to the [[service|oauth-api]] under least-privilege roles.
diff --git a/examples/default/domains/Customer/systems/identity-provider/index.mdx b/examples/default/domains/Customer/systems/identity-provider/index.mdx
new file mode 100644
index 000000000..346da9d0a
--- /dev/null
+++ b/examples/default/domains/Customer/systems/identity-provider/index.mdx
@@ -0,0 +1,54 @@
+---
+id: identity-provider
+name: Identity Provider
+version: 1.0.0
+summary: |
+  The identity system that authenticates customers. It is the source of truth for credentials and login, verifies sign-in attempts, and emits an event when a customer successfully authenticates.
+scope: external
+owners:
+  - customer-platform
+services:
+  - id: oauth-api
+containers:
+  - id: user-directory
+relationships:
+  - id: customer-management-system
+    label: provides authentication for
+actors:
+  - id: customer
+    name: Customer
+    label: signs in
+    direction: inbound
+badges:
+  - content: Identity
+    backgroundColor: purple
+    textColor: purple
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Identity Provider** authenticates customers for Acme Inc. It exposes an OAuth-style API, verifies credentials against the [[container|user-directory]], and emits a [[event|customer-authenticated]] event on a successful sign-in so other systems can react. It provides authentication for the [[system|customer-management-system]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|oauth-api]] | Service | OAuth-style authentication API. Handles authentication requests and publishes authentication events. |
+| [[container\|user-directory]] | Data store | The directory of customer credentials and identities. |
+
+## Messages this system publishes
+
+- [[event|customer-authenticated]] — a customer has successfully authenticated.
diff --git a/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/index.mdx b/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/index.mdx
new file mode 100644
index 000000000..b888ded2c
--- /dev/null
+++ b/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/index.mdx
@@ -0,0 +1,32 @@
+---
+id: authenticate-customer
+name: Authenticate Customer
+version: 1.0.0
+summary: |
+  Command to authenticate a customer with their credentials.
+owners:
+  - customer-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /oauth/token
+  statusCodes: ['200', '400', '401']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`AuthenticateCustomer` is handled by the [[service|oauth-api]]. It verifies the supplied credentials against the [[container|user-directory]] and, on success, returns an access token and publishes a [[event|customer-authenticated]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/schema.json b/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/schema.json
new file mode 100644
index 000000000..c39e22350
--- /dev/null
+++ b/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/schema.json
@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AuthenticateCustomer",
+  "description": "Command to authenticate a customer with their credentials, and the token returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "The credentials to authenticate",
+      "type": "object",
+      "properties": {
+        "email": {
+          "type": "string",
+          "format": "email"
+        },
+        "password": {
+          "type": "string"
+        }
+      },
+      "required": ["email", "password"]
+    },
+    "response": {
+      "description": "The access token issued on a successful sign-in",
+      "type": "object",
+      "properties": {
+        "accessToken": {
+          "type": "string"
+        },
+        "tokenType": {
+          "type": "string",
+          "enum": ["Bearer"]
+        },
+        "expiresIn": {
+          "description": "Token lifetime in seconds",
+          "type": "integer"
+        }
+      },
+      "required": ["accessToken", "tokenType", "expiresIn"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/index.mdx b/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/index.mdx
new file mode 100644
index 000000000..9da6701dd
--- /dev/null
+++ b/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: customer-authenticated
+name: Customer Authenticated
+version: 1.0.0
+summary: |
+  Published when a customer has successfully authenticated.
+owners:
+  - customer-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CustomerAuthenticated` is published by the [[service|oauth-api]] whenever a customer successfully signs in. Other systems consume this event for auditing, session tracking, and security monitoring.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/schema.json b/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/schema.json
new file mode 100644
index 000000000..d9d341b7a
--- /dev/null
+++ b/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/schema.json
@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CustomerAuthenticated",
+  "description": "Emitted when a customer successfully authenticates",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the customer authenticated",
+      "type": "string",
+      "format": "date-time"
+    },
+    "customerId": {
+      "description": "Unique identifier of the customer that authenticated",
+      "type": "string",
+      "format": "uuid"
+    },
+    "method": {
+      "description": "How the customer authenticated",
+      "type": "string",
+      "enum": ["PASSWORD", "SSO", "MFA"]
+    },
+    "ipAddress": {
+      "description": "IP address the sign-in came from",
+      "type": "string"
+    }
+  },
+  "required": ["eventId", "occurredAt", "customerId", "method"]
+}
diff --git a/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/index.mdx b/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/index.mdx
new file mode 100644
index 000000000..e8f3b3371
--- /dev/null
+++ b/examples/default/domains/Customer/systems/identity-provider/services/OAuthAPI/index.mdx
@@ -0,0 +1,49 @@
+---
+id: oauth-api
+version: 1.0.0
+name: OAuth API
+summary: |
+  OAuth-style authentication API for the Identity Provider. Verifies customer credentials and publishes an event when a customer successfully authenticates.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - customer-platform
+receives:
+  - id: authenticate-customer
+    version: 1.0.0
+sends:
+  - id: customer-authenticated
+    version: 1.0.0
+readsFrom:
+  - id: user-directory
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/oauth-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **OAuth API** is the authentication entry point for Acme Inc. It verifies credentials against the [[container|user-directory]] and, on a successful sign-in, publishes a [[event|customer-authenticated]] event so other systems can react.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} message`} description="Authentication events published on successful sign-in" />
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} message`} description="Authentication requests handled by this service" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Authentication | Handles [[command\|authenticate-customer]] and verifies credentials. |
+| Event publishing | Emits [[event\|customer-authenticated]] on a successful sign-in. |
+| Credentials | Reads from the [[container\|user-directory]] — the source of truth for credentials. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />
diff --git a/examples/default/domains/Customer/ubiquitous-language.mdx b/examples/default/domains/Customer/ubiquitous-language.mdx
new file mode 100644
index 000000000..ae4de1b54
--- /dev/null
+++ b/examples/default/domains/Customer/ubiquitous-language.mdx
@@ -0,0 +1,48 @@
+---
+dictionary:
+  - id: Customer
+    name: Customer
+    summary: "A person with an account at Acme Inc, identified by a unique customer id and email."
+    description: |
+      The customer is the central concept of the Customer domain. Their profile is owned by the
+      Customer Management System, which is the source of truth for who a customer is. A customer has:
+
+      - A unique customer id and a unique email
+      - A display name
+      - An account status (ACTIVE, SUSPENDED or CLOSED)
+
+      A customer's profile data is kept deliberately separate from their credentials, which live in
+      the Identity Provider.
+    icon: User
+  - id: Identity
+    name: Identity
+    summary: "The credentials and login information used to prove a customer is who they say they are."
+    description: |
+      An identity is distinct from a customer profile. It lives in the Identity Provider's user
+      directory and holds the login email and a securely hashed credential. Keeping identity separate
+      from profile data isolates the most sensitive information.
+    icon: Fingerprint
+  - id: Authentication
+    name: Authentication
+    summary: "Verifying that a sign-in attempt belongs to a real customer."
+    description: |
+      Authentication is owned by the Identity Provider. It verifies credentials against the user
+      directory and, on success, issues an access token and publishes a CustomerAuthenticated event.
+    icon: LockKeyhole
+  - id: Credential
+    name: Credential
+    summary: "A secret (such as a password) a customer uses to authenticate. Never stored in plain text."
+    icon: KeyRound
+  - id: Account Status
+    name: Account Status
+    summary: "Where a customer account sits: ACTIVE, SUSPENDED or CLOSED."
+    description: |
+      - ACTIVE — the account is in good standing and can be used.
+      - SUSPENDED — temporarily blocked (e.g. for review).
+      - CLOSED — permanently deactivated.
+    icon: Workflow
+  - id: User Directory
+    name: User Directory
+    summary: "The authoritative store of customer credentials and login identities."
+    icon: Users
+---
diff --git a/examples/default/domains/E-Commerce/index.mdx b/examples/default/domains/E-Commerce/index.mdx
deleted file mode 100644
index b2c265bb9..000000000
--- a/examples/default/domains/E-Commerce/index.mdx
+++ /dev/null
@@ -1,277 +0,0 @@
----
-id: E-Commerce
-name: E-Commerce
-version: 1.0.0
-owners:
-  - dboyne
-  - full-stack
-domains:
-  - id: Orders
-  - id: Payment
-  - id: Subscriptions
-  - id: MySubdomain
-badges:
-  - content: Core domain
-    backgroundColor: blue
-    textColor: blue
-    icon: RectangleGroupIcon
-  - content: Business Critical
-    backgroundColor: yellow
-    textColor: yellow
-    icon: ShieldCheckIcon
-resourceGroups:
-  - id: related-resources
-    title: Core FlowMart Services
-    items:
-      - id: InventoryService
-        type: service
-      - id: OrdersService
-        type: service
-      - id: NotificationService
-        type: service
-      - id: ShippingService
-        type: service
-      - id: CustomerService
-        type: service
-      - id: PaymentService
-        type: service
-      - id: AnalyticsService
-        type: service
-attachments:
-  - url: https://example.com/adr/001
-    title: ADR-001 - Use Kafka for asynchronous messaging
-    description: Learn more about why we chose Kafka for asynchronous messaging in this architecture decision record.
-    type: 'architecture-decisions'
-    icon: FileTextIcon
-  - url: https://example.com/adr/001
-    title: ADR-002 - Database per service
-    description: Learn more about why we chose to use a database per service in this architecture decision record.
-    icon: FileTextIcon
-    type: 'architecture-decisions'
-  - url: https://example.com/c4/e-commerce-system-context.png
-    title: E-Commerce System Context (C4)
-    description: The C4 diagram context of the E-Commerce system
-    type: 'diagrams'
-    icon: FileBoxIcon
----
-
-import Footer from '@catalog/components/footer.astro';
-
-The E-Commerce domain is the core business domain of FlowMart, our modern digital marketplace. This domain orchestrates all critical business operations from product discovery to order fulfillment, handling millions of transactions monthly across our global customer base.
-
-<Tiles>
-    <Tile 
-        icon="UserGroupIcon" 
-        href="/docs/teams/full-stack" 
-        title="Engineering Support" 
-        description="Questions? Contact our full-stack team for technical support" 
-    />
-    <Tile 
-        icon="RectangleGroupIcon" 
-        href={`/visualiser/domains/${frontmatter.id}/${frontmatter.version}`} 
-        title="Domain Architecture" 
-        description="Explore our domain structure and service interactions" 
-    />
-    <Tile 
-        icon="CircleStackIcon" 
-        href={`#flowmart-e-commerce-database-schema`} 
-        title="Database Schema" 
-        description="Explore our database schema for the E-Commerce domain" 
-    />
-    <Tile 
-        icon="RectangleGroupIcon" 
-        href={`#target-architecture-event-storming-results`} 
-        title="Target Architecture" 
-        description="Explore our target architecture for the E-Commerce domain" 
-    />
-</Tiles>
-
-## Domain Overview
-
-The E-Commerce domain encapsulates all the core business logic for the FlowMart e-commerce platform. It is built on event-driven microservices architecture.
-
-<NodeGraph mode="full" search="false" legend="false" />
-
-FlowMart's E-Commerce domain is built on event-driven microservices architecture, enabling:
-- Real-time inventory management across multiple warehouses
-- Seamless payment processing with multiple providers
-- Smart order routing and fulfillment
-- Personalized customer notifications
-- Subscription-based shopping experiences
-- Advanced fraud detection and prevention
-
-## Core Domains for E-Commerce
-
-The <ResourceLink id="Orders" type="domain">Orders</ResourceLink> and <ResourceLink id="Subscriptions" type="domain">Subscription</ResourceLink> domains are core domains for the E-Commerce domain.
-
-<span class="not-prose">They are used to manage the orders and subscriptions for the E-Commerce domain.</span>
-
-<div class="grid grid-cols-2 gap-4 not-prose">
-  <NodeGraph id="Orders" version="0.0.3" type="domain" />
-  <NodeGraph id="Subscriptions" version="0.0.1" type="domain" />
-</div>
-
-The E-Commerce domain is built on the following sub domains:
-
-- <ResourceLink id="Orders" type="domain">Orders</ResourceLink> - Core domain for order management
-- <ResourceLink id="Payment" type="domain">Payment</ResourceLink> - A generic domain for payment processing using Stripe as a payment provider
-- <ResourceLink id="Subscriptions" type="domain">Subscription</ResourceLink> - Generic subscription domain handling users subscriptions
-
-
-### FlowMart E-Commerce Database Schema
-
-This diagram represents the core relational data model behind FlowMart, a fictional event-driven e-commerce platform. It captures the main business entities and their relationships, including customers, orders, products, inventory events, and payments.
-
-The schema is designed to support a distributed microservices architecture with event-sourced patterns, enabling services like OrderService, InventoryService, and PaymentService to operate independently while maintaining data consistency through asynchronous events.
-
-```plantuml
-@startuml
-!define Table(name,desc) class name as "desc" << (T,#E5E7EB) >>
-!define PK(x) <u>x</u>
-!define FK(x) <i>x</i>
-
-' ===== Core Tables =====
-
-Table(Customers, "Customers") {
-  PK(customerId): UUID
-  firstName: VARCHAR
-  lastName: VARCHAR
-  email: VARCHAR
-  phone: VARCHAR
-  dateRegistered: TIMESTAMP
-}
-
-Table(Orders, "Orders") {
-  PK(orderId): UUID
-  FK(customerId): UUID
-  orderDate: TIMESTAMP
-  status: VARCHAR
-  totalAmount: DECIMAL
-}
-
-Table(Products, "Products") {
-  PK(productId): UUID
-  name: VARCHAR
-  description: TEXT
-  price: DECIMAL
-  stockQuantity: INT
-}
-
-Table(OrderItems, "Order Items") {
-  PK(id): UUID
-  FK(orderId): UUID
-  FK(productId): UUID
-  quantity: INT
-  unitPrice: DECIMAL
-}
-
-Table(Payments, "Payments") {
-  PK(paymentId): UUID
-  FK(orderId): UUID
-  amount: DECIMAL
-  method: VARCHAR
-  status: VARCHAR
-  paidAt: TIMESTAMP
-}
-
-Table(InventoryEvents, "Inventory Events") {
-  PK(eventId): UUID
-  FK(productId): UUID
-  eventType: VARCHAR
-  quantityChange: INT
-  eventTime: TIMESTAMP
-}
-
-Table(Subscription, "Subscriptions") {
-  PK(subscriptionId): UUID
-  FK(customerId): UUID
-  plan: VARCHAR
-  status: VARCHAR
-  startDate: TIMESTAMP
-  endDate: TIMESTAMP
-}
-
-' ===== Relationships =====
-
-Customers ||--o{ Orders : places
-Orders ||--o{ OrderItems : contains
-Products ||--o{ OrderItems : includes
-Orders ||--o{ Payments : paid_by
-Products ||--o{ InventoryEvents : logs
-Customers ||--o{ Subscription : subscribes
-
-@enduml
-
-```
-
-## Target Architecture (Event Storming Results)
-
-Our target architecture was defined through collaborative event storming sessions with product, engineering, and business stakeholders. This represents our vision for FlowMart's commerce capabilities.
-
-<Miro boardId="uXjVIHCImos=/" moveToWidget="3074457347671667709" edit={false} />
-
-
-### Order Processing Flow
-
-```mermaid
-sequenceDiagram
-    participant Customer
-    participant OrdersService
-    participant InventoryService
-    participant PaymentService
-    participant NotificationService
-    participant ShippingService
-
-    Customer->>OrdersService: Place Order
-    OrdersService->>InventoryService: Check Stock Availability
-    InventoryService-->>OrdersService: Stock Confirmed
-    OrdersService->>PaymentService: Process Payment
-    PaymentService-->>OrdersService: Payment Successful
-    OrdersService->>InventoryService: Reserve Inventory
-    OrdersService->>ShippingService: Create Shipping Label
-    ShippingService-->>OrdersService: Shipping Label Generated
-    OrdersService->>NotificationService: Send Order Confirmation
-    NotificationService-->>Customer: Order & Tracking Details
-```
-
-## Key Business Flows
-
-### Subscription Management
-Our subscription service powers FlowMart's popular "Subscribe & Save" feature:
-
-<Flow id="CancelSubscription" version="latest" includeKey={false} mode="full" walkthrough={false} search={false} />
-
-### Payment Processing
-Secure, multi-provider payment processing with fraud detection:
-
-<Flow id="PaymentFlow" version="latest" includeKey={false} />
-
-## Core Services
-
-These services form the backbone of FlowMart's e-commerce operations:
-
-<ResourceGroupTable 
-    id="related-resources" 
-    limit={7} 
-    showOwners={true} 
-    description="Essential services powering our e-commerce platform" 
-/>
-
-## Performance SLAs
-
-- Order Processing: < 2 seconds
-- Payment Processing: < 3 seconds
-- Inventory Updates: Real-time
-- Notification Delivery: < 30 seconds
-
-## Monitoring & Alerts
-
-- Real-time order volume monitoring
-- Payment gateway health checks
-- Inventory level alerts
-- Customer experience metrics
-- System performance dashboards
-
-<Attachments title="External Attachments" />
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/changelog.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/changelog.mdx
deleted file mode 100644
index 3f9852aa9..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/changelog.mdx
+++ /dev/null
@@ -1,7 +0,0 @@
----
-createdAt: 2024-08-01
----
-
-### Service added to domain
-
-Added the InventoryService to the domain.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/channels/orders-domain-eventbus/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/channels/orders-domain-eventbus/index.mdx
deleted file mode 100644
index d91047ec8..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/channels/orders-domain-eventbus/index.mdx
+++ /dev/null
@@ -1,16 +0,0 @@
----
-id: orders-domain-eventbus
-name: Orders Domain EventBus
-version: 1.0.0
-summary: |
-  Amazon Orders Domain EventBus
-owners:
-  - dboyne
-routes:
-  - id: cross-account-bus
-  - id: notifications-queue
----
-
-{/* Information about the Orders Domain EventBus */}
-
-Full this....
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/entities/CartItem/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/entities/CartItem/index.mdx
deleted file mode 100644
index b7cbfa44b..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/entities/CartItem/index.mdx
+++ /dev/null
@@ -1,121 +0,0 @@
----
-id: CartItem
-name: CartItem
-version: 1.0.0
-identifier: cartItemId
-summary: Represents an individual item within a shopping cart.
-properties:
-  - name: cartItemId
-    type: UUID
-    required: true
-    description: Unique identifier for the cart item
-  - name: cartId
-    type: UUID
-    required: true
-    description: Shopping cart this item belongs to
-    references: ShoppingCart
-    referencesIdentifier: cartId
-    relationType: hasOne
-  - name: productId
-    type: UUID
-    required: true
-    description: Product being added to cart
-    references: Product
-    referencesIdentifier: productId
-    relationType: hasOne
-  - name: sku
-    type: string
-    required: true
-    description: Product SKU at time of adding to cart
-  - name: productName
-    type: string
-    required: true
-    description: Product name snapshot at time of adding to cart
-  - name: productImage
-    type: string
-    required: false
-    description: Product image URL snapshot
-  - name: quantity
-    type: integer
-    required: true
-    description: Quantity of this product in the cart
-  - name: unitPrice
-    type: decimal
-    required: true
-    description: Unit price at time of adding to cart
-  - name: totalPrice
-    type: decimal
-    required: true
-    description: Total price for this line item (quantity × unit price)
-  - name: originalPrice
-    type: decimal
-    required: false
-    description: Original product price before any discounts
-  - name: discountAmount
-    type: decimal
-    required: false
-    description: Discount applied to this line item
-  - name: productVariant
-    type: object
-    required: false
-    description: Product variant details (size, color, etc.)
-    properties:
-      - name: size
-        type: string
-        description: Product size if applicable
-      - name: color
-        type: string
-        description: Product color if applicable
-      - name: style
-        type: string
-        description: Product style if applicable
-  - name: isAvailable
-    type: boolean
-    required: true
-    description: Whether the product is still available
-  - name: notes
-    type: string
-    required: false
-    description: Customer notes for this item
-  - name: addedAt
-    type: DateTime
-    required: true
-    description: Date and time when item was added to cart
-  - name: updatedAt
-    type: DateTime
-    required: false
-    description: Date and time when item was last updated
----
-
-## Overview
-
-The CartItem entity represents individual products within a customer's shopping cart. It maintains snapshots of product information and pricing to ensure consistency during the shopping session.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-* **ShoppingCart:** Each cart item belongs to one `ShoppingCart` (identified by `cartId`).
-* **Product:** Each cart item references one `Product` (identified by `productId`).
-
-## Price Calculations
-
-* **Total Price** = Quantity × Unit Price - Discount Amount
-* **Savings** = Original Price - Unit Price (if applicable)
-
-## Examples
-
-* **CartItem #1:** iPhone 15 Pro, quantity 1, $999.99 unit price, no discount.
-* **CartItem #2:** Running Shoes Size 9, quantity 2, $64.99 unit price (was $129.99).
-* **CartItem #3:** T-Shirt Large/Blue, quantity 3, $19.99 unit price.
-
-## Business Rules
-
-* Quantity must be greater than zero
-* Unit price is captured at time of adding to maintain consistency
-* Product availability is checked when cart is accessed
-* Unavailable items are marked but not automatically removed
-* Total price is recalculated when quantity changes
-* Product snapshots prevent price changes from affecting active carts
-* Maximum quantity limits may apply per product type
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/entities/Customer/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/entities/Customer/index.mdx
deleted file mode 100644
index 2627174ea..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/entities/Customer/index.mdx
+++ /dev/null
@@ -1,56 +0,0 @@
----
-id: Customer
-name: Customer
-version: 1.0.0
-identifier: customerId
-summary: Represents an individual or organization that places orders.
-
-properties:
-  - name: customerId
-    type: UUID
-    required: true
-    description: Unique identifier for the customer
-  - name: firstName
-    type: string
-    required: true
-    description: Customer's first name
-  - name: lastName
-    type: string
-    required: true
-    description: Customer's last name
-  - name: email
-    type: string
-    required: true
-    description: Customer's primary email address (unique)
-  - name: phone
-    type: string
-    required: false
-    description: Customer's phone number
-  - name: addresses
-    type: array
-    items:
-      type: Address # Assuming an Address value object or entity exists
-    required: false
-    description: List of addresses associated with the customer (e.g., shipping, billing)
-  - name: dateRegistered
-    type: DateTime
-    required: true
-    description: Date and time when the customer registered
----
-## Overview
-
-The Customer entity holds information about the individuals or organizations who interact with the system, primarily by placing orders. It stores contact details, addresses, and other relevant personal or business information.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-*   **Order:** A customer can have multiple `Order` entities. The `Order` entity holds a reference (`customerId`) back to the `Customer`.
-*   **Address:** A customer can have multiple associated `Address` value objects or entities.
-
-## Examples
-
-*   **Customer A:** Jane Doe, registered on 2023-01-15, with a primary shipping address and a billing address.
-*   **Customer B:** John Smith, a long-time customer with multiple past orders.
-
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/entities/Order/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/entities/Order/index.mdx
deleted file mode 100644
index bd7845ac2..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/entities/Order/index.mdx
+++ /dev/null
@@ -1,96 +0,0 @@
----
-id: Order
-name: Order
-version: 1.0.0
-identifier: orderId
-aggregateRoot: true
-summary: Represents a customer's request to purchase products or services.
-properties:
-  - name: orderId
-    type: UUID
-    required: true
-    description: Unique identifier for the order
-  - name: orderNumber
-    type: string
-    required: true
-    description: Unique identifier for the order
-  - name: customerId
-    type: UUID
-    required: false
-    description: Identifier for the customer placing the order test
-    references: Customer
-    referencesIdentifier: customerId
-    relationType: hasOne
-  - name: orderDate
-    type: DateTime
-    required: true
-    description: Date and time when the order was placed
-  - name: status
-    type: string
-    required: true
-    description: Current status of the order (e.g., Pending, Processing, Shipped, Delivered, Cancelled)
-    enum: ['Pending', 'Processing', 'Shipped', 'Delivered', 'Cancelled']
-  - name: orderItems
-    type: array
-    items:
-      type: OrderItem # Assuming an OrderItem entity exists
-    required: true
-    references: OrderItem
-    referencesIdentifier: orderItemId
-    relationType: hasMany
-    description: List of items included in the order
-  - name: totalAmount
-    type: decimal
-    required: true
-    description: Total monetary value of the order
-  - name: shippingAddress
-    type: Address
-    required: true
-    description: Address where the order should be shipped
-    references: Address
-    referencesIdentifier: addressId
-    relationType: hasOne
-  - name: billingAddress
-    type: Address
-    required: true
-    description: Address for billing purposes
-    references: Address
-    referencesIdentifier: addressId
-    relationType: hasOne
-  - name: payment
-    type: Payment
-    required: false
-    description: Payment associated with this order
-    references: Payment
-    referencesIdentifier: orderId
-    relationType: hasOne
-  - name: convertedFromCartId
-    type: UUID
-    required: false
-    description: Shopping cart that was converted to this order
-    references: ShoppingCart
-    referencesIdentifier: cartId
-    relationType: hasOne
----
-
-## Overview
-
-The Order entity captures all details related to a customer's purchase request. It serves as the central aggregate root within the Orders domain, coordinating information about the customer, products ordered, payment, and shipping.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-*   **Customer:** Each order belongs to one `Customer` (identified by `customerId`).
-*   **OrderItem:** An order contains one or more `OrderItem` entities detailing the specific products and quantities.
-*   **Address:** Each order has shipping and billing `Address` entities (identified by `shippingAddress` and `billingAddress`).
-*   **Payment:** An order is associated with one `Payment` entity for transaction processing.
-*   **ShoppingCart:** An order can be converted from a `ShoppingCart` (identified by `convertedFromCartId`).
-*   **Shipment:** An order may lead to one or more `Shipment` entities (not detailed here).
-
-## Examples
-
-*   **Order #12345:** A customer orders 2 units of Product A and 1 unit of Product B, to be shipped to their home address. Status is 'Processing'.
-*   **Order #67890:** A customer places a large order for multiple items, requiring special shipping arrangements. Status is 'Pending' until payment confirmation.
-
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/entities/OrderItem/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/entities/OrderItem/index.mdx
deleted file mode 100644
index 67523921f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/entities/OrderItem/index.mdx
+++ /dev/null
@@ -1,59 +0,0 @@
----
-id: OrderItem
-name: OrderItem
-version: 1.0.0
-identifier: orderItemId
-summary: Represents a single item within a customer's order.
-
-properties:
-  - name: orderItemId
-    type: UUID
-    required: true
-    description: Unique identifier for the order item
-  - name: orderId
-    type: UUID
-    required: true
-    description: Identifier for the parent Order
-    references: Order
-    relationType: hasOne
-  - name: productId
-    type: UUID
-    required: true
-    description: Identifier for the product being ordered
-    references: Product
-    referencesIdentifier: productId
-    relationType: hasOne 
-  - name: productName
-    type: string
-    required: false # Often denormalized for performance/display
-    description: Name of the product at the time of order
-  - name: quantity
-    type: integer
-    required: true
-    description: Number of units of the product ordered
-  - name: unitPrice
-    type: decimal
-    required: true
-    description: Price per unit of the product at the time of order
-  - name: totalPrice
-    type: decimal
-    required: true
-    description: Total price for this item line (quantity * unitPrice)
----
-
-## Overview
-
-The OrderItem entity details a specific product and its quantity requested within an `Order`. It holds information about the product, the quantity ordered, and the price calculation for that line item. OrderItems are part of the `Order` aggregate.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-*   **Order:** Each `OrderItem` belongs to exactly one `Order` (identified by `orderId`). It is a constituent part of the Order aggregate.
-*   **Product:** Each `OrderItem` refers to one `Product` (identified by `productId`).
-
-## Examples
-
-*   **OrderItem A (for Order #12345):** Product ID: P001, Quantity: 2, Unit Price: $50.00, Total Price: $100.00
-*   **OrderItem B (for Order #12345):** Product ID: P002, Quantity: 1, Unit Price: $75.00, Total Price: $75.00
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/entities/ShoppingCart/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/entities/ShoppingCart/index.mdx
deleted file mode 100644
index 2a7cae974..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/entities/ShoppingCart/index.mdx
+++ /dev/null
@@ -1,148 +0,0 @@
----
-id: ShoppingCart
-name: ShoppingCart
-version: 1.0.0
-identifier: cartId
-aggregateRoot: true
-summary: Represents a customer's shopping cart containing products before checkout.
-properties:
-  - name: cartId
-    type: UUID
-    required: true
-    description: Unique identifier for the shopping cart
-  - name: customerId
-    type: UUID
-    required: false
-    description: Customer who owns this cart (null for guest carts)
-    references: Customer
-    referencesIdentifier: customerId
-    relationType: hasOne
-  - name: sessionId
-    type: string
-    required: false
-    description: Session identifier for guest carts
-  - name: status
-    type: string
-    required: true
-    description: Current status of the cart
-    enum: ['active', 'abandoned', 'converted', 'expired']
-  - name: cartItems
-    type: array
-    items:
-      type: CartItem
-    required: false
-    description: Items in the shopping cart
-    references: CartItem
-    referencesIdentifier: cartId
-    relationType: hasMany
-  - name: subtotal
-    type: decimal
-    required: true
-    description: Subtotal amount before taxes and shipping
-  - name: taxAmount
-    type: decimal
-    required: false
-    description: Calculated tax amount
-  - name: shippingAmount
-    type: decimal
-    required: false
-    description: Calculated shipping amount
-  - name: discountAmount
-    type: decimal
-    required: false
-    description: Total discount amount applied
-  - name: totalAmount
-    type: decimal
-    required: true
-    description: Final total amount including taxes and shipping
-  - name: currency
-    type: string
-    required: true
-    description: Currency code for all amounts
-  - name: appliedCoupons
-    type: array
-    items:
-      type: string
-    required: false
-    description: Coupon codes applied to this cart
-  - name: shippingAddress
-    type: Address
-    required: false
-    description: Selected shipping address
-    references: Address
-    referencesIdentifier: addressId
-    relationType: hasOne
-  - name: billingAddress
-    type: Address
-    required: false
-    description: Selected billing address
-    references: Address
-    referencesIdentifier: addressId
-    relationType: hasOne
-  - name: notes
-    type: string
-    required: false
-    description: Customer notes or special instructions
-  - name: abandonedAt
-    type: DateTime
-    required: false
-    description: Date and time when cart was abandoned
-  - name: convertedToOrderId
-    type: UUID
-    required: false
-    description: Order ID if cart was successfully converted
-    references: Order
-    referencesIdentifier: orderId
-    relationType: hasOne
-  - name: expiresAt
-    type: DateTime
-    required: false
-    description: Date and time when cart expires
-  - name: createdAt
-    type: DateTime
-    required: true
-    description: Date and time when the cart was created
-  - name: updatedAt
-    type: DateTime
-    required: false
-    description: Date and time when the cart was last updated
----
-
-## Overview
-
-The ShoppingCart entity manages the customer's shopping experience before checkout. It tracks selected products, quantities, pricing, and supports both registered customer and guest shopping scenarios.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-* **Customer:** A cart can belong to one `Customer` (identified by `customerId`).
-* **CartItem:** A cart contains multiple `CartItem` entities with product details.
-* **Address:** A cart can reference shipping and billing `Address` entities.
-* **Order:** A cart can be converted to one `Order` (identified by `convertedToOrderId`).
-
-## Cart States
-
-```
-active → abandoned
-   ↓       ↓
-converted  expired
-```
-
-## Examples
-
-* **Cart #1:** Customer cart with 3 items, $299.99 total, active status.
-* **Cart #2:** Guest cart abandoned after 24 hours, contains 1 high-value item.
-* **Cart #3:** Converted cart that became Order #12345, marked as converted.
-
-## Business Rules
-
-* Guest carts are identified by session ID when customer ID is null
-* Cart totals are recalculated when items are added/removed
-* Abandoned carts trigger marketing automation after configured time
-* Expired carts are cleaned up after retention period
-* Cart conversion creates an order and marks cart as converted
-* Inventory is not reserved until checkout begins
-* Applied coupons are validated on each cart update
-* Cart items maintain snapshot of product prices at time of addition
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/index.mdx
deleted file mode 100644
index 992dcbf07..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/index.mdx
+++ /dev/null
@@ -1,99 +0,0 @@
----
-id: Orders
-name: Orders
-version: 0.0.3
-owners:
-  - dboyne
-  - full-stack
-services:
-  - id: InventoryService
-  - id: OrdersService
-  - id: NotificationService
-  - id: ShippingService
-badges:
-  - content: Subdomain
-    backgroundColor: blue
-    textColor: blue
-    icon: RectangleGroupIcon
-entities:
-  - id: Order
-  - id: OrderItem
-  - id: Customer
-  - id: ShoppingCart
-  - id: CartItem
-resourceGroups:
-  - id: related-resources
-    title: Core resources
-    items:
-      - id: InventoryService
-        type: service
-      - id: OrdersService
-        type: service
-      - id: NotificationService
-        type: service
-      - id: ShippingService
-        type: service
----
-
-import Footer from '@catalog/components/footer.astro';
-
-
-
-:::warning
-
-Please ensure all services are **updated** to the latest version for compatibility and performance improvements.
-:::
-
-The Orders domain handles all operations related to customer orders, from creation to fulfillment. This documentation provides an overview of the events and services involved in the Orders domain, helping developers and stakeholders understand the event-driven architecture
-
-<Tiles >
-    <Tile icon="UserGroupIcon" href="/docs/teams/full-stack" title="Contact the team" description="Any questions? Feel free to contact the owners" />
-    <Tile icon="RectangleGroupIcon" href={`/visualiser/domains/${frontmatter.id}/${frontmatter.version}`} title={`${frontmatter.services.length} services`} description="This domain contains the following services." />
-</Tiles>
-
-### Architecture for the Orders domain
-
-<NodeGraph />
-
-### Entity Map
-
-This is an entity map for the Orders domain. It shows the entities and their relationships with external entities in this domain.
-
-<EntityMap title="Orders Entity Map"/>
-
-<MessageTable format="all" limit={4} showChannels={true} title="Messages in/out of the domain" />
-
-### Order example (sequence diagram)
-
-```mermaid
-sequenceDiagram
-    participant Customer
-    participant OrdersService
-    participant InventoryService
-    participant NotificationService
-
-    Customer->>OrdersService: Place Order
-    OrdersService->>InventoryService: Check Inventory
-    InventoryService-->>OrdersService: Inventory Available
-    OrdersService->>InventoryService: Reserve Inventory
-    OrdersService->>NotificationService: Send Order Confirmation
-    NotificationService-->>Customer: Order Confirmation
-    OrdersService->>Customer: Order Placed Successfully
-    OrdersService->>InventoryService: Update Inventory
-```
-
-## Flows
-
-### Cancel Subscription flow
-Documented flow when a user cancels their subscription.
-
-<Flow id="CancelSubscription" version="latest" includeKey={false} />
-
-### Payment processing flow
-Documented flow when a user makes a payment within the order domain
-
-<Flow id="PaymentFlow" version="latest" includeKey={false} />
-
-<ResourceGroupTable id="related-resources" limit={4} showOwners={true} title="Core resources for the Orders domain" description="Resources that are related to the Orders domain, you may find them useful" />
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/changelog.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/changelog.mdx
deleted file mode 100644
index b917110e9..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/changelog.mdx
+++ /dev/null
@@ -1,7 +0,0 @@
----
-createdAt: 2024-08-01
----
-
-### Service receives additional events
-
-Service now receives [OrderAmended](/docs/events/OrderAmended/0.0.1) and [UpdateInventory](/docs/commands/UpdateInventory/0.0.3) events.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/channels/fiter-by-orders-over-100/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/channels/fiter-by-orders-over-100/index.mdx
deleted file mode 100644
index 5cf4e076f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/channels/fiter-by-orders-over-100/index.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
----
-id: inventory-service-filter-by-orders-over-100
-name: Filter by Orders over 100
-version: 0.0.1
-summary: |
-  Custom channel that filters by orders over $100.
----
-
-This channel is used to filter by orders over $100.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/AddInventory/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/AddInventory/index.mdx
deleted file mode 100644
index a6d00078e..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/AddInventory/index.mdx
+++ /dev/null
@@ -1,49 +0,0 @@
----
-id: AddInventory
-name: Add inventory
-version: 0.0.3
-summary: |
-  Command that will add item to a given inventory id
-owners:
-  - dboyne
-  - asmith
-  - full-stack
-  - mobile-devs
-badges:
-  - content: Recently updated!
-    backgroundColor: green
-    textColor: green
-schemaPath: schema.json
-sidebar:
-  badge: POST
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The AddInventory command is issued to add new stock to the inventory. This command is used by the inventory management system to update the quantity of products available in the warehouse or store.
-
-## Architecture diagram
-
-<NodeGraph/>
-
-## Payload example
-
-```json 
-{
-  "productId": "789e1234-b56c-78d9-e012-3456789fghij",
-  "quantity": 50,
-  "warehouseId": "456e7891-c23d-45f6-b78a-123456789abc",
-  "timestamp": "2024-07-04T14:48:00Z"
-}
-
-```
-
-## Schema
-
-<Schema file="schema.json"/>
-
-<Footer />
-
-
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/AddInventory/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/AddInventory/schema.json
deleted file mode 100644
index bf7b6cc19..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/AddInventory/schema.json
+++ /dev/null
@@ -1,29 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "title": "AddInventoryCommand",
-    "type": "object",
-    "properties": {
-      "productId": {
-        "type": "string",
-        "format": "uuid",
-        "description": "The unique identifier of the product being added to the inventory."
-      },
-      "quantity": {
-        "type": "integer",
-        "description": "The quantity of the product being added to the inventory."
-      },
-      "warehouseId": {
-        "type": "string",
-        "format": "uuid",
-        "description": "The unique identifier of the warehouse where the inventory is being added."
-      },
-      "timestamp": {
-        "type": "string",
-        "format": "date-time",
-        "description": "The date and time when the inventory was added."
-      }
-    },
-    "required": ["productId", "quantity", "warehouseId", "timestamp"],
-    "additionalProperties": false
-  }
-  
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/DeleteInventory/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/DeleteInventory/index.mdx
deleted file mode 100644
index dc253a711..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/DeleteInventory/index.mdx
+++ /dev/null
@@ -1,32 +0,0 @@
----
-id: DeleteInventory
-name: Delete Inventory
-version: 0.0.3
-summary: |
-  Command that will delete a given inventory item from the system
-owners:
-  - dboyne
-  - msmith
-  - asmith
-  - full-stack
-  - mobile-devs
-badges:
-  - content: Recently updated!
-    backgroundColor: green
-    textColor: green
-schemaPath: schema.json
-sidebar:
-  badge: DELETE
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The DeleteInventory command is issued to remove a product from the inventory system. This command is used by the inventory management system when a product needs to be completely removed from the warehouse or store catalog, typically due to discontinuation or permanent removal of the item.
-
-## Architecture diagram
-
-<NodeGraph />
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/UpdateInventory/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/UpdateInventory/index.mdx
deleted file mode 100644
index 90374bb0f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/UpdateInventory/index.mdx
+++ /dev/null
@@ -1,49 +0,0 @@
----
-id: UpdateInventory
-name: Update inventory
-version: 0.0.3
-summary: |
-  Command that will update a given inventory item
-owners:
-  - dboyne
-  - msmith
-  - asmith
-  - full-stack
-  - mobile-devs
-badges:
-  - content: Recently updated!
-    backgroundColor: green
-    textColor: green
-schemaPath: schema.json
-sidebar:
-  badge: PUT
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The UpdateInventory command is issued to update the existing stock levels of a product in the inventory. This command is used by the inventory management system to adjust the quantity of products available in the warehouse or store, either by increasing or decreasing the current stock levels.
-
-## Architecture diagram
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
-
-## Payload example
-
-```json 
-{
-  "productId": "789e1234-b56c-78d9-e012-3456789fghij",
-  "quantityChange": -10,
-  "warehouseId": "456e7891-c23d-45f6-b78a-123456789abc",
-  "timestamp": "2024-07-04T14:48:00Z"
-}
-```
-
-## Schema (JSON schema)
-
-<Schema file="schema.json"/>
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/containers/inventory-db/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/containers/inventory-db/index.mdx
deleted file mode 100644
index 0974eafbf..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/containers/inventory-db/index.mdx
+++ /dev/null
@@ -1,195 +0,0 @@
----
-id: inventory-db
-name: Inventory DB
-version: 0.0.1
-container_type: database
-technology: postgres@14
-authoritative: true
-access_mode: readWrite
-classification: internal
-retention: 5y
-residency: eu-west-1
-summary: Authoritative database for product inventory levels, warehouse stock, and inventory movements
----
-
-<NodeGraph />
-
-### What is this?
-Inventory DB is the system of record for real-time inventory tracking across multiple warehouses and fulfillment centers. It maintains accurate stock levels, handles inventory reservations, and tracks all inventory movements (receipts, shipments, adjustments).
-
-### What does it store?
-- **Inventory Levels**: Current stock quantities by product and warehouse
-- **Inventory Reservations**: Temporary holds on inventory for pending orders
-- **Stock Movements**: Audit trail of all inventory transactions (in, out, adjustments)
-- **Reorder Points**: Low-stock thresholds and automatic reorder triggers
-- **Warehouse Locations**: Bin/shelf locations for physical inventory management
-
-### Who writes to it?
-- **InventoryService** manages stock levels, reservations, and adjustments
-- **OrdersService** creates reservations when orders are placed
-- **Warehouse Management System** updates physical inventory counts
-- **Receiving System** adds stock when shipments arrive
-
-### Who reads from it?
-- **OrdersService** checks stock availability before order confirmation
-- **Inventory Service** monitors low-stock alerts and reorder points
-- **Analytics** tracks inventory turnover and stock-out rates
-- **Warehouse Operations** for pick/pack workflows
-- **Finance** for inventory valuation reports
-
-### High-level data model
-- `inventory_levels`: Current quantities by product and warehouse (frequently updated)
-- `inventory_reservations`: Temporary allocations for pending orders (auto-expire)
-- `stock_movements`: Immutable log of all inventory changes
-- `reorder_rules`: Automated replenishment configuration
-
-### Common queries
-```sql
--- Check available inventory for a product (excluding reservations)
-SELECT
-  il.warehouse_id,
-  il.quantity_on_hand,
-  COALESCE(SUM(ir.quantity), 0) AS quantity_reserved,
-  il.quantity_on_hand - COALESCE(SUM(ir.quantity), 0) AS quantity_available
-FROM inventory_levels il
-LEFT JOIN inventory_reservations ir
-  ON ir.product_id = il.product_id
-  AND ir.warehouse_id = il.warehouse_id
-  AND ir.expires_at > NOW()
-WHERE il.product_id = $1
-GROUP BY il.warehouse_id, il.quantity_on_hand;
-
--- Find low-stock items needing reorder
-SELECT
-  il.product_id,
-  il.warehouse_id,
-  il.quantity_on_hand,
-  rr.reorder_point,
-  rr.reorder_quantity
-FROM inventory_levels il
-JOIN reorder_rules rr
-  ON rr.product_id = il.product_id
-  AND rr.warehouse_id = il.warehouse_id
-WHERE il.quantity_on_hand <= rr.reorder_point
-  AND rr.enabled = true;
-
--- Track inventory movements for audit (last 30 days)
-SELECT
-  sm.movement_id,
-  sm.product_id,
-  sm.warehouse_id,
-  sm.movement_type, -- 'RECEIPT', 'SHIPMENT', 'ADJUSTMENT', 'RETURN'
-  sm.quantity_change,
-  sm.reason,
-  sm.created_at,
-  sm.created_by
-FROM stock_movements sm
-WHERE sm.product_id = $1
-  AND sm.created_at >= NOW() - INTERVAL '30 days'
-ORDER BY sm.created_at DESC;
-
--- Calculate inventory turnover rate
-SELECT
-  p.product_id,
-  p.product_name,
-  SUM(CASE WHEN sm.movement_type = 'SHIPMENT' THEN ABS(sm.quantity_change) ELSE 0 END) AS units_sold_30d,
-  AVG(il.quantity_on_hand) AS avg_inventory_level,
-  (SUM(CASE WHEN sm.movement_type = 'SHIPMENT' THEN ABS(sm.quantity_change) ELSE 0 END) /
-   NULLIF(AVG(il.quantity_on_hand), 0)) AS turnover_ratio
-FROM stock_movements sm
-JOIN inventory_levels il USING (product_id, warehouse_id)
-JOIN products p USING (product_id)
-WHERE sm.created_at >= NOW() - INTERVAL '30 days'
-GROUP BY p.product_id, p.product_name
-ORDER BY turnover_ratio DESC;
-```
-
-### Inventory reservation flow
-1. Customer adds item to cart → soft reservation (not written to DB yet)
-2. Customer proceeds to checkout → `OrdersService` creates reservation with 15-minute expiry
-3. Payment successful → reservation converted to stock movement (`SHIPMENT` type)
-4. Payment failed or timeout → reservation auto-expires, stock released
-5. Order cancelled → reservation deleted, stock released immediately
-
-### Access patterns and guidance
-- Use indexed lookups by `product_id` and `warehouse_id`
-- Reservations have TTL; expired reservations cleaned up hourly
-- Stock movements are append-only for audit compliance
-- Use pessimistic locking for concurrent inventory updates
-- Read replicas for analytics to avoid impacting operational queries
-
-### Concurrency and consistency
-- **Row-level locking**: `SELECT FOR UPDATE` on inventory_levels during reservations
-- **Atomic updates**: All inventory changes in transactions (reserve + deduct + log)
-- **Idempotency**: Movement records include idempotency keys to prevent duplicates
-- **Eventual consistency**: Read model (inventory-readmodel container) synced asynchronously
-
-### Security and compliance
-- Inventory adjustments logged with user identity for audit trail
-- Role-based access: warehouse staff vs. system services
-- Financial impact tracked for high-value inventory movements
-- Historical data retained for 5 years (tax/audit requirements)
-
-### Requesting access
-To request access to Inventory DB:
-
-1. **Read-only access** (for reporting):
-   - Submit request via [ServiceNow](https://company.service-now.com)
-   - Select "Database Access" → "Inventory DB (Read-Only)"
-   - Approval from inventory team lead
-   - Access granted within 24 hours
-
-2. **Write access** (for services):
-   - Restricted to InventoryService and authorized systems only
-   - New service integration requires architecture review
-   - Contact #inventory-team for integration onboarding
-
-3. **Warehouse operations access**:
-   - Access via Warehouse Management System only (no direct DB access)
-   - Contact #warehouse-operations for WMS training
-
-**Contact**:
-- Slack: #inventory-team
-- Email: inventory-team@company.com
-- On-call: PagerDuty #inventory-oncall
-
-### Monitoring and alerts
-- Stock-out alerts (inventory level = 0 for critical products)
-- Negative inventory alerts (data integrity issue)
-- Reservation expiry rate (high rate indicates checkout abandonment)
-- Database lock contention (alert if wait time > 100ms)
-- Replication lag (alert at > 5 seconds)
-
-### Backup and disaster recovery
-- Continuous backups with 5-minute RPO
-- Point-in-time recovery window: 35 days
-- Cross-region backup replication for DR
-- Daily backup validation
-
-### Performance characteristics
-- **Read latency**: p99 < 20ms
-- **Write latency**: p99 < 50ms (includes locking)
-- **Reservation throughput**: 1,000+ reservations/second
-- **Concurrent updates**: Supports high concurrency with row-level locking
-
-### Local development
-- Connection string: `INVENTORY_DB_URL` environment variable
-- Docker setup: `docker-compose up inventory-db`
-- Seed data: `npm run seed:inventory`
-- Test data includes multiple warehouses and stock levels
-
-### Common issues and troubleshooting
-- **Negative inventory**: Check for missing rollback on failed reservations
-- **Stuck reservations**: Run cleanup job for expired reservations
-- **Lock contention**: Reduce transaction duration, consider optimistic locking
-- **Inventory drift**: Reconcile with physical counts, investigate stock movement gaps
-- **Replication lag**: Check network latency, increase replication capacity
-
-### Integration with read model
-Inventory DB is the write-side (source of truth). The `inventory-readmodel` container provides optimized read queries:
-- Real-time sync via change data capture (CDC)
-- Denormalized views for fast lookups
-- Eventually consistent (typically < 1 second lag)
-- Used by high-traffic read operations (product pages, search)
-
-For more information, see InventoryService documentation and Inventory Management Playbook.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/containers/inventory-readmodel/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/containers/inventory-readmodel/index.mdx
deleted file mode 100644
index 46ddaaca8..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/containers/inventory-readmodel/index.mdx
+++ /dev/null
@@ -1,122 +0,0 @@
----
-id: inventory-readmodel
-name: Inventory Read Model
-version: 0.0.1
-container_type: database
-technology: postgres@14
-authoritative: false
-access_mode: read
-summary: Projection of stock levels from Inventory domain
----
-
-<NodeGraph />
-
-The Inventory Read Model is a PostgreSQL database that serves as an optimized projection of inventory data for high-performance read operations. This read model is specifically designed to support fast queries for stock levels, product availability, and inventory reporting across our e-commerce platform.
-
-## Overview
-
-This read model is maintained by the Inventory Service and provides denormalized views of inventory data that are optimized for query performance. It serves as the primary data source for:
-
-- Real-time stock level checks during order processing
-- Inventory reporting and analytics
-- Product availability displays on the storefront
-- Low stock alerts and notifications
-
-## Database Schema
-
-### Core Tables
-
-#### `inventory_projection`
-- **product_id** (UUID) - Primary key, references the product
-- **sku** (VARCHAR) - Stock keeping unit identifier
-- **available_quantity** (INTEGER) - Current available stock
-- **reserved_quantity** (INTEGER) - Stock reserved for pending orders
-- **total_quantity** (INTEGER) - Total physical stock
-- **reorder_point** (INTEGER) - Minimum stock threshold
-- **last_updated** (TIMESTAMP) - When this record was last updated
-- **version** (BIGINT) - Event sourcing version number
-
-#### `product_locations`
-- **product_id** (UUID) - Foreign key to inventory_projection
-- **warehouse_id** (UUID) - Warehouse identifier
-- **location_code** (VARCHAR) - Specific location within warehouse
-- **quantity** (INTEGER) - Quantity at this location
-- **last_counted** (TIMESTAMP) - Last physical count date
-
-#### `stock_movements_summary`
-- **product_id** (UUID) - Product identifier
-- **movement_date** (DATE) - Date of movement
-- **inbound_quantity** (INTEGER) - Total items received
-- **outbound_quantity** (INTEGER) - Total items shipped
-- **adjustment_quantity** (INTEGER) - Manual adjustments
-- **ending_balance** (INTEGER) - End of day balance
-
-## Data Sources
-
-This read model is populated from the following event streams:
-
-- **InventoryReceived** - Updates available quantity when new stock arrives
-- **InventoryReserved** - Increases reserved quantity for orders
-- **InventoryReleased** - Decreases reserved quantity when reservations expire
-- **InventoryAdjusted** - Manual stock adjustments from warehouse operations
-- **InventoryTransferred** - Stock movements between locations
-
-## Performance Characteristics
-
-- **Read Latency**: < 5ms for single product queries
-- **Throughput**: 50,000+ queries per second
-- **Data Freshness**: Near real-time (< 100ms from event occurrence)
-- **Availability**: 99.95% uptime SLA
-
-## Usage Patterns
-
-### High-Frequency Operations
-- Stock availability checks during checkout
-- Real-time inventory displays on product pages
-- Order validation and reservation
-
-### Reporting Operations
-- Daily inventory reports
-- Low stock alerts
-- Inventory turnover analysis
-- Warehouse utilization metrics
-
-## Maintenance
-
-### Data Retention
-- Transaction-level data: 2 years
-- Summary data: 7 years
-- Archived data moved to cold storage after retention period
-
-### Backup Strategy
-- Full backups: Daily at 2 AM EST
-- Incremental backups: Every 4 hours
-- Point-in-time recovery available for 30 days
-- Cross-region replication for disaster recovery
-
-### Monitoring
-- Stock level discrepancy alerts
-- Query performance monitoring
-- Event processing lag alerts
-- Database health checks every 5 minutes
-
-## Security
-
-- **Access Control**: Role-based access with principle of least privilege
-- **Encryption**: Data encrypted at rest using AES-256
-- **Network Security**: VPC isolation with private subnets
-- **Audit Logging**: All data access logged for compliance
-
-## Dependencies
-
-- **Event Store**: Primary source of inventory events
-- **Message Bus**: RabbitMQ for event consumption
-- **Cache Layer**: Redis for frequently accessed data
-- **Monitoring**: Prometheus and Grafana for metrics
-
-## Contact Information
-
-For questions about this read model, please contact:
-- **Primary**: Inventory Team (inventory@acmecorp.com)
-- **On-call**: Use PagerDuty escalation policy "Inventory-ReadModel"
-- **Architecture Questions**: Sarah Mitchell (s.mitchell@acmecorp.com)
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/changelog.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/changelog.mdx
deleted file mode 100644
index 691a1ed67..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/changelog.mdx
+++ /dev/null
@@ -1,68 +0,0 @@
----
-createdAt: 2024-08-01
-badges:
-    - content: ⭐️ JSON Schema
-      backgroundColor: purple
-      textColor: purple
----
-
-### Added support for JSON Schema
-
-InventoryAdjusted uses Avro but now also supports JSON Draft 7.
-
-```json title="Employee JSON Draft"
-// labeled-line-markers.jsx
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "title": "Employee",
-  "properties": {
-    "Name": {
-      "type": "string"
-    },
-    "Age": {
-      "type": "integer"
-    },
-    "Town": {
-      "type": "string"
-    }
-  },
-  "required": ["Name", "Age", "Town"]
-}
-
-```
-
-Using it with our Kafka Cluster
-
-## 1. Create a new topic
-
-```sh
-# Create a topic named 'employee_topic'
-kafka-topics.sh --create --topic employee_topic --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1
-```
-
-## Step 2: Prepare the JSON Message
-
-Create a JSON file named `employee.json` with the following content:
-
-```json
-{
-  "Name": "John Doe",
-  "Age": 30,
-  "Town": "Springfield"
-}
-```
-
-## Step 3: Produce the Message to Kafka Topic
-
-Use the Kafka producer CLI to send the JSON message:
-
-```sh
-cat employee.json | kafka-console-producer.sh --topic employee_topic --bootstrap-server localhost:9092
-```
-
-## Step 4: Verify the Message (Optional)
-
-```sh
-kafka-console-consumer.sh --topic employee_topic --from-beginning --bootstrap-server localhost:9092
-```
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/index.mdx
deleted file mode 100644
index bd72ba4ee..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/index.mdx
+++ /dev/null
@@ -1,245 +0,0 @@
----
-id: InventoryAdjusted
-name: Inventory adjusted
-version: 1.0.1
-summary: |
-  Indicates a change in inventory level
-owners:
-  - dboyne
-  - msmith
-  - asmith
-  - full-stack
-  - mobile-devs
-badges:
-  - content: Recently updated!
-    backgroundColor: green
-    textColor: green
-  - content: 'Broker:Apache Kafka'
-    backgroundColor: yellow
-    textColor: yellow
-    icon: kafka
-schemaPath: schema.avro
-draft:
-  title: Inventory Adjusted 1.0.1 is in draft
-  message: >
-    ### New version of Inventory Adjusted is in draft
-
-
-    This is a new version of the Inventory Adjusted event. It is not yet ready
-    for production. We are still working on it and collecting feedback from the
-    team.
-
-
-    You can use this version in lower environments, **but please be aware that
-    it is still in draft and may change.**
-
-
-    You can still use a previous version of the event, [Inventory Adjusted
-    1.0.0](/docs/events/InventoryAdjusted/1.0.0), until that version is
-    deprecated.
-
-
-    _If you would like to provide feedback, please contact us at
-    [feedback@eventcatalog.io](mailto:feedback@eventcatalog.io) or our slack
-    channel [Order
-    Management](https://join.slack.com/t/eventcatalog/shared_invite/zt-1q900000000000000000000000000000)_
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `Inventory Adjusted` event is triggered whenever there is a change in the inventory levels of a product. This could occur due to various reasons such as receiving new stock, sales, returns, or manual adjustments by the inventory management team. The event ensures that all parts of the system that rely on inventory data are kept up-to-date with the latest inventory levels.
-
-<Tiles >
-    <Tile icon="UserGroupIcon" href="/docs/teams/full-stack" title="Contact the team" description="Any questions? Feel free to contact the owners" />
-    <Tile icon="DocumentIcon" href={`/generated/events/Inventory/${frontmatter.id}/schema.avro`} title="View the schema" description="View the schema directly in your browser" />
-</Tiles>
-
-## Architecture diagram
-
-<NodeGraph />
-
-
-<SchemaViewer file="schema.yml" title="JSON Schema" maxHeight="500" />
-
-## Payload example
-
-Event example you my see being published.
-
-```json 
-{
-  "Name": "John Doe",
-  "Age": 30,
-  "Department": "Engineering",
-  "Position": "Software Engineer",
-  "Salary": 85000.50,
-  "JoinDate": "2024-01-15"
-}
-```
-
-## Schema (avro)
-
-<SchemaViewer file="schema.avro" title="Avro schema" maxHeight="500" showRequired="true" />
-
-<Schema file="schema.avro" title="Inventory Adjusted Schema (avro)" />
-
-## Producing the Event
-
-Select the language you want to produce the event in to see an example.
-
-<Tabs>
-  <TabItem title="Python">
-
-    ```python title="Produce event in Python" frame="terminal"
-    from kafka import KafkaProducer
-    import json
-    from datetime import datetime
-
-    # Kafka configuration
-    producer = KafkaProducer(
-        bootstrap_servers=['localhost:9092'],
-        value_serializer=lambda v: json.dumps(v).encode('utf-8')
-    )
-
-    # Event data
-    event_data = {
-      "event_id": "abc123",
-      "timestamp": datetime.utcnow().isoformat() + 'Z',
-      "product_id": "prod987",
-      "adjusted_quantity": 10,
-      "new_quantity": 150,
-      "adjustment_reason": "restock",
-      "adjusted_by": "user123"
-    }
-
-    # Send event to Kafka topic
-    producer.send('inventory.adjusted', event_data)
-    producer.flush()
-    ```
-  </TabItem>
-  <TabItem title="TypeScript">
-
-    ```typescript title="Produce event in TypeScript" frame="terminal"
-    import { Kafka } from 'kafkajs';
-
-    // Kafka configuration
-    const kafka = new Kafka({
-      clientId: 'inventory-producer',
-      brokers: ['localhost:9092']
-    });
-
-    const producer = kafka.producer();
-
-    // Event data
-    const eventData = {
-      event_id: "abc123",
-      timestamp: new Date().toISOString(),
-      product_id: "prod987", 
-      adjusted_quantity: 10,
-      new_quantity: 150,
-      adjustment_reason: "restock",
-      adjusted_by: "user123"
-    };
-
-    // Send event to Kafka topic
-    async function produceEvent() {
-      await producer.connect();
-      await producer.send({
-        topic: 'inventory.adjusted',
-        messages: [
-          { value: JSON.stringify(eventData) }
-        ],
-      });
-      await producer.disconnect();
-    }
-
-    produceEvent().catch(console.error);
-    ```
-  </TabItem>
-  <TabItem title="Java">
-
-    ```java title="Produce event in Java" frame="terminal"
-    import org.apache.kafka.clients.producer.*;
-    import org.apache.kafka.common.serialization.StringSerializer;
-    import com.fasterxml.jackson.databind.ObjectMapper;
-    import java.util.Properties;
-    import java.util.HashMap;
-    import java.util.Map;
-    import java.time.Instant;
-
-    public class InventoryProducer {
-        public static void main(String[] args) {
-            // Kafka configuration
-            Properties props = new Properties();
-            props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
-            props.put(ProducerConfig.CLIENT_ID_CONFIG, "inventory-producer");
-            props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
-            props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
-
-            Producer<String, String> producer = new KafkaProducer<>(props);
-            ObjectMapper mapper = new ObjectMapper();
-
-            try {
-                // Event data
-                Map<String, Object> eventData = new HashMap<>();
-                eventData.put("event_id", "abc123");
-                eventData.put("timestamp", Instant.now().toString());
-                eventData.put("product_id", "prod987");
-                eventData.put("adjusted_quantity", 10);
-                eventData.put("new_quantity", 150);
-                eventData.put("adjustment_reason", "restock");
-                eventData.put("adjusted_by", "user123");
-
-                // Create producer record
-                ProducerRecord<String, String> record = new ProducerRecord<>(
-                    "inventory.adjusted",
-                    mapper.writeValueAsString(eventData)
-                );
-
-                // Send event to Kafka topic
-                producer.send(record, (metadata, exception) -> {
-                    if (exception != null) {
-                        System.err.println("Error producing message: " + exception);
-                    }
-                });
-
-            } catch (Exception e) {
-                e.printStackTrace();
-            } finally {
-                producer.flush();
-                producer.close();
-            }
-        }
-    }
-    ```
-  </TabItem>
-</Tabs>
-
-
-
-### Consuming the Event
-
-To consume an Inventory Adjusted event, use the following example Kafka consumer configuration in Python:
-
-```python title="Consuming the event with python" frame="terminal"
-from kafka import KafkaConsumer
-import json
-
-# Kafka configuration
-consumer = KafkaConsumer(
-    'inventory.adjusted',
-    bootstrap_servers=['localhost:9092'],
-    auto_offset_reset='earliest',
-    enable_auto_commit=True,
-    group_id='inventory_group',
-    value_serializer=lambda v: json.dumps(v).encode('utf-8')
-)
-
-# Consume events
-for message in consumer:
-    event_data = json.loads(message.value)
-    print(f"Received Inventory Adjusted event: {event_data}")
-```
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro
deleted file mode 100644
index ea0986272..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro
+++ /dev/null
@@ -1,14 +0,0 @@
-{
-  "type": "record",
-  "namespace": "Tutorialspoint",
-  "name": "Employee",
-  "doc": "Represents an employee in the organisation HR system.",
-  "fields": [
-    { "name": "Name", "type": "string", "doc": "Full name of the employee." },
-    { "name": "Age", "type": "int", "doc": "Age in years at time of record creation.", "default": 0 },
-    { "name": "Department", "type": "string", "doc": "The department the employee belongs to.", "default": "Unknown" },
-    { "name": "Position", "type": "string", "doc": "The employee's job title or role.", "default": "Unknown" },
-    { "name": "Salary", "type": "double", "doc": "Annual salary in the company currency.", "default": 0.0 },
-    { "name": "JoinDate", "type": "string", "logicalType": "date", "doc": "Date employee joined the company. Format: YYYY-MM-DD.", "default": "" }
-  ]
-}
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/changelog.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/changelog.mdx
deleted file mode 100644
index c200336dc..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/changelog.mdx
+++ /dev/null
@@ -1,30 +0,0 @@
----
-createdAt: 2024-07-01
-badges:
-    - content: Breaking change
-      backgroundColor: red
-      textColor: red
----
-
-### Removed fields from schema, added new owners
-
-`Gender` property has been removed from the Schema of the event
-
-Also added the [full stackers](/docs/teams/full-stack) team as owners of this event
-
-```diff lang="json"
-  {
-    "type" : "record",
-    "namespace" : "Tutorialspoint",
-    "name" : "Employee",
-    "fields" : [
-      { "name" : "Name" , "type" : "string" },
-      { "name" : "Age" , "type" : "int" },
--     { "name" : "Gender" , "type" : "string" },
-    ]
-  }
-```
-
-
-
-
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/index.mdx
deleted file mode 100644
index ed4c64034..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/index.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-id: InventoryAdjusted
-name: Inventory adjusted
-version: 0.0.1
-summary: |
-  Indicates a change in inventory level
-owners:
-    - dboyne
-schemaPath: 'schema.avro'
-badges:
-    - content: Recently updated!
-      backgroundColor: green
-      textColor: green
----
-
-:::warning
-When firing this event make sure you set the `correlation-id` in the headers. Our schemas have standard metadata make sure you read and follow it.
-:::
-
-### Details
-
-<NodeGraph />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/changelog.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/changelog.mdx
deleted file mode 100644
index aa47fdc7a..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/changelog.mdx
+++ /dev/null
@@ -1,26 +0,0 @@
----
-createdAt: 2024-07-11
-badges:
-    - content: New field
-      backgroundColor: green
-      textColor: green
----
-
-### Added new field to schema
-
-We added the new town property to the schema for downstream consumers. 
-
-```json ins={"New: Added new Town property to schema:":9-10}
-// labeled-line-markers.jsx
-{
-  "type" : "record",
-  "namespace" : "Tutorialspoint",
-  "name" : "Employee",
-  "fields" : [
-     { "name" : "Name" , "type" : "string" },
-     { "name" : "Age" , "type" : "int" },
-
-     { "name" : "Town" , "type" : "string" },
-  ]
-}
-```
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/index.mdx
deleted file mode 100644
index f5211107f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/index.mdx
+++ /dev/null
@@ -1,106 +0,0 @@
----
-id: InventoryAdjusted
-name: Inventory adjusted
-version: 1.0.0
-summary: |
-  Indicates a change in inventory level
-owners:
-    - dboyne
-    - msmith
-    - asmith
-    - full-stack
-    - mobile-devs
-schemaPath: 'schema.avro'
-badges:
-    - content: Recently updated!
-      backgroundColor: green
-      textColor: green
-    - content: Broker:Apache Kafka
-      backgroundColor: yellow
-      textColor: yellow
-      icon: kafka
----
-
-## Overview
-
-The `Inventory Adjusted` event is triggered whenever there is a change in the inventory levels of a product. This could occur due to various reasons such as receiving new stock, sales, returns, or manual adjustments by the inventory management team. The event ensures that all parts of the system that rely on inventory data are kept up-to-date with the latest inventory levels.
-
-<NodeGraph />
-
-## Event Details
-
-### Event Name
-`inventory.adjusted`
-
-### Description
-This event indicates that the inventory count for one or more products has been adjusted. The event carries the updated inventory details including the product ID, the new quantity, and the reason for the adjustment.
-
-### Payload
-The payload of the `Inventory Adjusted` event includes the following fields:
-
-```json title="Example of payload" frame="terminal"
-{
-  "event_id": "string",
-  "timestamp": "ISO 8601 date-time",
-  "product_id": "string",
-  "adjusted_quantity": "integer",
-  "new_quantity": "integer",
-  "adjustment_reason": "string",
-  "adjusted_by": "string"
-}
-```
-
-### Producing the Event
-
-To produce an Inventory Adjusted event, use the following example Kafka producer configuration in Python:
-
-```python title="Produce event in Python" frame="terminal"
-from kafka import KafkaProducer
-import json
-from datetime import datetime
-
-# Kafka configuration
-producer = KafkaProducer(
-    bootstrap_servers=['localhost:9092'],
-    value_serializer=lambda v: json.dumps(v).encode('utf-8')
-)
-
-# Event data
-event_data = {
-  "event_id": "abc123",
-  "timestamp": datetime.utcnow().isoformat() + 'Z',
-  "product_id": "prod987",
-  "adjusted_quantity": 10,
-  "new_quantity": 150,
-  "adjustment_reason": "restock",
-  "adjusted_by": "user123"
-}
-
-# Send event to Kafka topic
-producer.send('inventory.adjusted', event_data)
-producer.flush()
-```
-
-### Consuming the Event
-
-To consume an Inventory Adjusted event, use the following example Kafka consumer configuration in Python:
-
-```python title="Consuming the event with python" frame="terminal"
-from kafka import KafkaConsumer
-import json
-
-# Kafka configuration
-consumer = KafkaConsumer(
-    'inventory.adjusted',
-    bootstrap_servers=['localhost:9092'],
-    auto_offset_reset='earliest',
-    enable_auto_commit=True,
-    group_id='inventory_group',
-    value_serializer=lambda v: json.dumps(v).encode('utf-8')
-)
-
-# Consume events
-for message in consumer:
-    event_data = json.loads(message.value)
-    print(f"Received Inventory Adjusted event: {event_data}")
-```
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryGenerated/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryGenerated/index.mdx
deleted file mode 100644
index 3a443a80b..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryGenerated/index.mdx
+++ /dev/null
@@ -1,84 +0,0 @@
----
-id: InventoryGenerated
-version: 0.0.1
-name: Inventory Generated
-summary: Emitted when new inventory is generated or created for a product
-tags:
-  - inventory
-  - stock
-  - warehouse
-badges:
-  - content: New Event
-    backgroundColor: blue
-    textColor: white
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro'
-
-## Overview
-
-The `InventoryGenerated` event is emitted by the Inventory Service when new inventory is created or generated for a product. This event is typically triggered when products are received from suppliers, restocked, or when new inventory records are initialized in the system.
-
-## Event Flow
-
-1. InventoryService receives new stock from supplier or warehouse
-2. System validates product information and quantities
-3. Inventory record is created in the database
-4. `InventoryGenerated` event is emitted
-5. Downstream services (OrdersService, AnalyticsService) receive the event
-6. Product availability is updated across the system
-
-## Schema
-
-<SchemaViewer title="InventoryGenerated Schema" file={frontmatter.schemaPath} />
-
-## Example Payload
-
-```json
-{
-  "eventId": "evt_inv_20240215_001",
-  "timestamp": "2024-02-15T10:30:00Z",
-  "inventoryId": "inv_ABC123XYZ",
-  "productId": "prod_789456",
-  "sku": "SKU-2024-WIDGET-BLUE",
-  "productName": "Premium Widget - Blue",
-  "quantity": 500,
-  "unitCost": 12.50,
-  "totalValue": 6250.00,
-  "currency": "USD",
-  "warehouseId": "wh_MAIN_001",
-  "warehouseName": "Main Distribution Center",
-  "warehouseLocation": "Aisle 12, Shelf 3, Bin 7",
-  "supplierId": "supp_ACME_CORP",
-  "supplierName": "ACME Corporation",
-  "purchaseOrderId": "PO-2024-0123",
-  "batchNumber": "BATCH-2024-02-15-001",
-  "expirationDate": "2025-12-31",
-  "receivedBy": "user_john_doe",
-  "receivedAt": "2024-02-15T09:45:00Z",
-  "status": "active",
-  "metadata": {
-    "source": "manual_entry",
-    "qualityCheck": true,
-    "temperature": 22.5,
-    "humidity": 45
-  }
-}
-```
-
-## Use Cases
-
-- **Stock Replenishment**: Triggered when new stock arrives from suppliers
-- **Initial Setup**: When setting up inventory for new products
-- **Bulk Import**: When importing inventory from external systems
-- **Warehouse Transfer**: When inventory is transferred between warehouses
-
-## Related Events
-
-- `InventoryAdjusted` - When inventory levels are modified
-- `OutOfStock` - When inventory reaches zero
-- `LowStockAlert` - When inventory falls below threshold
-
-<Footer />
-
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/OutOfStock/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/OutOfStock/index.mdx
deleted file mode 100644
index cb1512f5f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/OutOfStock/index.mdx
+++ /dev/null
@@ -1,100 +0,0 @@
----
-id: OutOfStock
-name: Inventory out of stock
-version: 0.0.4
-summary: |
-  Indicates inventory is out of stock
-owners:
-  - dboyne
-  - msmith
-  - asmith
-  - full-stack
-  - mobile-devs
-badges:
-  - content: Recently updated!
-    backgroundColor: green
-    textColor: green
-  - content: 'Broker:Apache Kafka'
-    backgroundColor: yellow
-    textColor: yellow
-    icon: kafka
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `Inventory Adjusted` event is triggered whenever there is a change in the inventory levels of a product. This could occur due to various reasons such as receiving new stock, sales, returns, or manual adjustments by the inventory management team. The event ensures that all parts of the system that rely on inventory data are kept up-to-date with the latest inventory levels.
-
-<NodeGraph />
-
-### Payload
-The payload of the `Inventory Adjusted` event includes the following fields:
-
-```json title="Example of payload" frame="terminal"
-{
-  "event_id": "string",
-  "timestamp": "ISO 8601 date-time",
-  "product_id": "string",
-  "adjusted_quantity": "integer",
-  "new_quantity": "integer",
-  "adjustment_reason": "string"
-}
-```
-
-### Producing the Event
-
-To produce an Inventory Adjusted event, use the following example Kafka producer configuration in Python:
-
-```python title="Produce event in Python" frame="terminal"
-from kafka import KafkaProducer
-import json
-from datetime import datetime
-
-# Kafka configuration
-producer = KafkaProducer(
-    bootstrap_servers=['localhost:9092'],
-    value_serializer=lambda v: json.dumps(v).encode('utf-8')
-)
-
-# Event data
-event_data = {
-  "event_id": "abc123",
-  "timestamp": datetime.utcnow().isoformat() + 'Z',
-  "product_id": "prod987",
-  "adjusted_quantity": 10,
-  "new_quantity": 150,
-  "adjustment_reason": "restock",
-  "adjusted_by": "user123"
-}
-
-# Send event to Kafka topic
-producer.send('inventory.adjusted', event_data)
-producer.flush()
-```
-
-### Consuming the Event
-
-To consume an Inventory Adjusted event, use the following example Kafka consumer configuration in Python:
-
-```python title="Consuming the event with python" frame="terminal"
-from kafka import KafkaConsumer
-import json
-
-# Kafka configuration
-consumer = KafkaConsumer(
-    'inventory.adjusted',
-    bootstrap_servers=['localhost:9092'],
-    auto_offset_reset='earliest',
-    enable_auto_commit=True,
-    group_id='inventory_group',
-    value_serializer=lambda v: json.dumps(v).encode('utf-8')
-)
-
-# Consume events
-for message in consumer:
-    event_data = json.loads(message.value)
-    print(f"Received Inventory Adjusted event: {event_data}")
-```
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/OutOfStock/versioned/0.0.1/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/OutOfStock/versioned/0.0.1/index.mdx
deleted file mode 100644
index 579aafddd..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/OutOfStock/versioned/0.0.1/index.mdx
+++ /dev/null
@@ -1,97 +0,0 @@
----
-id: OutOfStock
-name: Inventory out of stock
-version: 0.0.1
-summary: |
-  Indicates inventory is out of stock
-owners:
-    - dboyne
-    - msmith
-    - asmith
-    - full-stack
-    - mobile-devs
-badges:
-    - content: Recently updated!
-      backgroundColor: green
-      textColor: green
-    - content: Broker:Apache Kafka
-      backgroundColor: yellow
-      textColor: yellow
-      icon: kafka
----
-
-## Overview
-
-The `Inventory Adjusted` event is triggered whenever there is a change in the inventory levels of a product. This could occur due to various reasons such as receiving new stock, sales, returns, or manual adjustments by the inventory management team. The event ensures that all parts of the system that rely on inventory data are kept up-to-date with the latest inventory levels.
-
-<NodeGraph />
-
-### Payload
-The payload of the `Inventory Adjusted` event includes the following fields:
-
-```json title="Example of payload" frame="terminal"
-{
-  "event_id": "string",
-  "timestamp": "ISO 8601 date-time",
-  "product_id": "string",
-  "adjusted_quantity": "integer",
-  "new_quantity": "integer",
-  "adjustment_reason": "string",
-  "adjusted_by": "string"
-}
-```
-
-### Producing the Event
-
-To produce an Inventory Adjusted event, use the following example Kafka producer configuration in Python:
-
-```python title="Produce event in Python" frame="terminal"
-from kafka import KafkaProducer
-import json
-from datetime import datetime
-
-# Kafka configuration
-producer = KafkaProducer(
-    bootstrap_servers=['localhost:9092'],
-    value_serializer=lambda v: json.dumps(v).encode('utf-8')
-)
-
-# Event data
-event_data = {
-  "event_id": "abc123",
-  "timestamp": datetime.utcnow().isoformat() + 'Z',
-  "product_id": "prod987",
-  "adjusted_quantity": 10,
-  "new_quantity": 150,
-  "adjustment_reason": "restock",
-  "adjusted_by": "user123"
-}
-
-# Send event to Kafka topic
-producer.send('inventory.adjusted', event_data)
-producer.flush()
-```
-
-### Consuming the Event
-
-To consume an Inventory Adjusted event, use the following example Kafka consumer configuration in Python:
-
-```python title="Consuming the event with python" frame="terminal"
-from kafka import KafkaConsumer
-import json
-
-# Kafka configuration
-consumer = KafkaConsumer(
-    'inventory.adjusted',
-    bootstrap_servers=['localhost:9092'],
-    auto_offset_reset='earliest',
-    enable_auto_commit=True,
-    group_id='inventory_group',
-    value_serializer=lambda v: json.dumps(v).encode('utf-8')
-)
-
-# Consume events
-for message in consumer:
-    event_data = json.loads(message.value)
-    print(f"Received Inventory Adjusted event: {event_data}")
-```
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/index.mdx
deleted file mode 100644
index 39034ab90..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/index.mdx
+++ /dev/null
@@ -1,141 +0,0 @@
----
-id: InventoryService
-version: 0.0.2
-name: Inventory Service
-summary: |
-  Service that handles the inventory
-owners:
-  - order-management
-receives:
-  - id: UserSignedUp
-  - id: OrderConfirmed
-    from:
-      - id: inventory-service-filter-by-orders-over-100
-  - id: OrderAmended
-    from:
-      - id: orders-domain-eventbus
-  - id: UpdateInventory
-    from:
-      - id: inventory-domain-eventbus
-  - id: AddInventory
-    from:
-      - id: inventory-domain-eventbus
-  - id: DeleteInventory
-    from:
-      - id: inventory-domain-eventbus
-sends:
-  - id: InventoryAdjusted
-    to:
-      - id: orders-domain-eventbus
-  - id: OutOfStock
-    to:
-      - id: orders-domain-eventbus 
-writesTo:
-  - id: inventory-db
-    version: 0.0.1
-  - id: inventory-readmodel
-    version: 0.0.1
-readsFrom:
-  - id: inventory-db
-    version: 0.0.1
-  - id: inventory-readmodel
-    version: 0.0.1
-repository:
-  language: JavaScript
-  url: 'https://github.com/event-catalog/pretend-shipping-service'
-deprecated:
-  date: 2026-05-01T00:00:00.000Z
-  message: >
-    This service is **being deprecated** and replaced by the new service
-    **InventoryServiceV2**.
-
-    Please contact the [team for more
-    information](mailto:inventory-team@example.com) or visit our
-    [website](https://eventcatalog.dev).
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The Inventory Service is a critical component of the system responsible for managing product stock levels, tracking inventory movements, and ensuring product availability. It interacts with other services to maintain accurate inventory records and supports operations such as order fulfillment, restocking, and inventory audits.
-
-<Tiles >
-    <Tile icon="DocumentIcon" href={`/docs/services/${frontmatter.id}/${frontmatter.version}/changelog`}  title="View the changelog" description="Want to know the history of this service? View the change logs" />
-    <Tile icon="UserGroupIcon" href="/docs/teams/full-stack" title="Contact the team" description="Any questions? Feel free to contact the owners" />
-    <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="This service sends messages to downstream consumers" />
-    <Tile icon="BoltIcon"  href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="This service receives messages from other services" />
-</Tiles>
-
-## Core features
-
-| Feature | Description |
-|---------|-------------|
-| Real-time Stock Tracking | Monitors inventory levels across all warehouses in real-time |
-| Automated Reordering | Triggers purchase orders when stock levels fall below defined thresholds |
-| Multi-warehouse Support | Manages inventory across multiple warehouse locations |
-| Batch Processing | Handles bulk inventory updates and adjustments efficiently |
-
-## Architecture diagram
-
-<NodeGraph title="Hello world" />
-
-<MessageTable format="all" limit={4} />
-
-# Infrastructure
-
-The Inventory Service is hosted on AWS.
-
-The diagram below shows the infrastructure of the Inventory Service. The service is hosted on AWS and uses AWS Lambda to handle the inventory requests. The inventory is stored in an AWS Aurora database and the inventory metadata is stored in an AWS S3 bucket.
-
-```mermaid
-architecture-beta
-    group api(logos:aws)
-
-    service db(logos:aws-aurora)[Inventory DB] in api
-    service disk1(logos:aws-s3)[Inventory Metadata] in api
-    service server(logos:aws-lambda)[Inventory Handler] in api
-
-    db:L -- R:server
-    disk1:T -- B:server
-```
-
-You can find more information about the Inventory Service infrastructure in the [Inventory Service documentation](https://github.com/event-catalog/pretend-shipping-service/blob/main/README.md).
-
-
-
-<Steps title="How to connect to Inventory Service">
-  <Step title="Obtain API credentials">
-    Request API credentials from the Inventory Service team.
-  </Step>
-  <Step title="Install the SDK">
-    Run the following command in your project directory:
-    ```bash
-    npm install inventory-service-sdk
-    ```
-  </Step>
-  <Step title="Initialize the client">
-  Use the following code to initialize the Inventory Service client:
-
-  ```js
-  const InventoryService = require('inventory-service-sdk');
-  const client = new InventoryService.Client({
-    clientId: 'YOUR_CLIENT_ID',
-    clientSecret: 'YOUR_CLIENT_SECRET',
-    apiUrl: 'https://api.inventoryservice.com/v1'
-  });
-```
-  </Step>
-  <Step title="Make API calls">
-  
-  You can now use the client to make API calls. For example, to get all products:
-
-  ```js
-  client.getProducts()
-    .then(products => console.log(products))
-    .catch(error => console.error(error));
-  ```
-  </Step>
-</Steps>
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/queries/GetInventoryList/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/queries/GetInventoryList/index.mdx
deleted file mode 100644
index edd9c42fd..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/queries/GetInventoryList/index.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-id: GetInventoryList
-name: List inventory list
-version: 0.0.1
-summary: |
-  GET request that will return inventory list
-owners:
-    - dboyne
-badges:
-    - content: Recently updated!
-      backgroundColor: green
-      textColor: green
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The GetInventoryList message is a query used to retrieve a comprehensive list of all available inventory items within a system. It is designed to return detailed information about each item, such as product names, quantities, availability status, and potentially additional metadata like categories or locations. This query is typically utilized by systems or services that require a real-time view of current stock, ensuring that downstream applications or users have accurate and up-to-date information for decision-making or operational purposes. The GetInventoryList is ideal for use cases such as order processing, stock management, or reporting, providing visibility into the full range of inventory data.
-
-<NodeGraph />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/queries/GetInventoryList/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/queries/GetInventoryList/schema.json
deleted file mode 100644
index da58b2da5..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/queries/GetInventoryList/schema.json
+++ /dev/null
@@ -1,53 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "title": "GetInventoryList",
-    "description": "A query to retrieve a list of all available inventory items with their details.",
-    "type": "object",
-    "properties": {
-      "filters": {
-        "type": "object",
-        "description": "Optional filters to narrow down the inventory search.",
-        "properties": {
-          "category": {
-            "type": "string",
-            "description": "Filter items by category (e.g., electronics, clothing, etc.)."
-          },
-          "location": {
-            "type": "string",
-            "description": "Filter items by storage location or warehouse."
-          },
-          "minStockLevel": {
-            "type": "integer",
-            "description": "Filter items with a stock level greater than or equal to this value."
-          },
-          "inStock": {
-            "type": "boolean",
-            "description": "Filter items that are currently in stock (true) or out of stock (false)."
-          }
-        },
-        "additionalProperties": false
-      },
-      "pagination": {
-        "type": "object",
-        "description": "Pagination options for the query.",
-        "properties": {
-          "page": {
-            "type": "integer",
-            "description": "The current page of results.",
-            "minimum": 1,
-            "default": 1
-          },
-          "pageSize": {
-            "type": "integer",
-            "description": "The number of items per page.",
-            "minimum": 1,
-            "default": 10
-          }
-        },
-        "required": ["page", "pageSize"]
-      }
-    },
-    "required": [],
-    "additionalProperties": false
-  }
-  
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/queries/GetInventoryStatus/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/queries/GetInventoryStatus/index.mdx
deleted file mode 100644
index 8c1a5289c..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/queries/GetInventoryStatus/index.mdx
+++ /dev/null
@@ -1,41 +0,0 @@
----
-id: GetInventoryStatus
-name: Get inventory status
-version: 0.0.1
-summary: |
-  GET request that will return the current stock status for a specific product.
-owners:
-    - dboyne
-badges:
-    - content: GET Request
-      backgroundColor: green
-      textColor: green
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The GetInventoryStatus message is a query designed to retrieve the current stock status for a specific product. 
-
-This query provides detailed information about the available quantity, reserved quantity, and the warehouse location where the product is stored. It is typically used by systems or services that need to determine the real-time availability of a product, enabling efficient stock management, order fulfillment, and inventory tracking processes. 
-
-This query is essential for ensuring accurate stock levels are reported to downstream systems, including e-commerce platforms, warehouse management systems, and sales channels.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="Schema" expand="true" maxHeight="500" search="true" />
-
-
-### Query using CURL
-
-Use this snippet to query the inventory status
-
-```sh title="Example CURL command"
-curl -X GET "https://api.yourdomain.com/inventory/status" \
--H "Content-Type: application/json" \
--d '{
-  "productId": "12345"
-}'
-```
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/queries/GetInventoryStatus/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/queries/GetInventoryStatus/schema.json
deleted file mode 100644
index fcf09a10a..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/queries/GetInventoryStatus/schema.json
+++ /dev/null
@@ -1,447 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "GetInventoryStatusResponse",
-  "type": "object",
-  "definitions": {
-    "Coordinates": {
-      "type": "object",
-      "properties": {
-        "latitude": {
-          "type": "number",
-          "minimum": -90,
-          "maximum": 90,
-          "description": "Latitude coordinate"
-        },
-        "longitude": {
-          "type": "number",
-          "minimum": -180,
-          "maximum": 180,
-          "description": "Longitude coordinate"
-        }
-      },
-      "required": ["latitude", "longitude"],
-      "additionalProperties": false
-    },
-    "LocationDetails": {
-      "type": "object",
-      "properties": {
-        "facilityId": {
-          "type": "string",
-          "pattern": "^[A-Z]{2}[0-9]{4}$",
-          "description": "Facility identifier in format CC0000"
-        },
-        "name": {
-          "type": "string",
-          "description": "Facility name"
-        },
-        "zone": {
-          "type": "string",
-          "enum": ["north", "south", "east", "west", "central"],
-          "description": "Geographic zone"
-        },
-        "coordinates": {
-          "$ref": "#/definitions/Coordinates"
-        },
-        "operatingHours": {
-          "type": "object",
-          "properties": {
-            "openTime": {
-              "type": "string",
-              "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$",
-              "description": "Opening time in HH:MM format"
-            },
-            "closeTime": {
-              "type": "string",
-              "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$",
-              "description": "Closing time in HH:MM format"
-            },
-            "timeZone": {
-              "type": "string",
-              "description": "Time zone identifier"
-            }
-          },
-          "required": ["openTime", "closeTime", "timeZone"],
-          "additionalProperties": false
-        }
-      },
-      "required": ["facilityId", "name", "zone", "coordinates", "operatingHours"],
-      "additionalProperties": false
-    },
-    "SupplierInfo": {
-      "type": "object",
-      "properties": {
-        "supplierId": {
-          "type": "string",
-          "description": "Unique supplier identifier"
-        },
-        "companyName": {
-          "type": "string",
-          "description": "Supplier company name"
-        },
-        "tier": {
-          "type": "string",
-          "enum": ["primary", "secondary", "backup"],
-          "description": "Supplier tier level"
-        },
-        "performance": {
-          "type": "object",
-          "properties": {
-            "onTimeDelivery": {
-              "type": "number",
-              "minimum": 0,
-              "maximum": 100,
-              "description": "On-time delivery percentage"
-            },
-            "qualityRating": {
-              "type": "number",
-              "minimum": 1,
-              "maximum": 5,
-              "description": "Quality rating (1-5 stars)"
-            },
-            "lastDeliveryDate": {
-              "type": "string",
-              "format": "date",
-              "description": "Date of last delivery"
-            }
-          },
-          "required": ["onTimeDelivery", "qualityRating"],
-          "additionalProperties": false
-        },
-        "contractTerms": {
-          "type": "object",
-          "properties": {
-            "minimumOrderQuantity": {
-              "type": "integer",
-              "minimum": 1,
-              "description": "Minimum order quantity"
-            },
-            "pricePerUnit": {
-              "type": "number",
-              "minimum": 0,
-              "description": "Price per unit in USD"
-            },
-            "currency": {
-              "type": "string",
-              "enum": ["USD", "EUR", "GBP", "CAD", "JPY"],
-              "description": "Currency code"
-            }
-          },
-          "required": ["minimumOrderQuantity", "pricePerUnit", "currency"],
-          "additionalProperties": false
-        }
-      },
-      "required": ["supplierId", "companyName", "tier", "performance", "contractTerms"],
-      "additionalProperties": false
-    },
-    "InventoryMovement": {
-      "type": "object",
-      "properties": {
-        "movementId": {
-          "type": "string",
-          "description": "Unique movement identifier"
-        },
-        "type": {
-          "type": "string",
-          "enum": ["inbound", "outbound", "transfer", "adjustment"],
-          "description": "Type of inventory movement"
-        },
-        "quantity": {
-          "type": "integer",
-          "description": "Quantity moved (positive for inbound, negative for outbound)"
-        },
-        "timestamp": {
-          "type": "string",
-          "format": "date-time",
-          "description": "When the movement occurred"
-        },
-        "reason": {
-          "type": "string",
-          "description": "Reason for the movement"
-        },
-        "reference": {
-          "type": "object",
-          "properties": {
-            "orderId": {
-              "type": "string",
-              "description": "Related order ID if applicable"
-            },
-            "transferId": {
-              "type": "string",
-              "description": "Related transfer ID if applicable"
-            },
-            "userId": {
-              "type": "string",
-              "description": "User who initiated the movement"
-            }
-          },
-          "additionalProperties": false
-        }
-      },
-      "required": ["movementId", "type", "quantity", "timestamp", "reason"],
-      "additionalProperties": false
-    },
-    "QualityMetrics": {
-      "type": "object",
-      "properties": {
-        "inspectionDate": {
-          "type": "string",
-          "format": "date",
-          "description": "Date of last quality inspection"
-        },
-        "grade": {
-          "type": "string",
-          "enum": ["A", "B", "C", "D", "F"],
-          "description": "Quality grade"
-        },
-        "defectRate": {
-          "type": "number",
-          "minimum": 0,
-          "maximum": 100,
-          "description": "Defect rate percentage"
-        },
-        "expirationTracking": {
-          "type": "object",
-          "properties": {
-            "hasExpiration": {
-              "type": "boolean",
-              "description": "Whether product has expiration date"
-            },
-            "nearExpiryCount": {
-              "type": "integer",
-              "minimum": 0,
-              "description": "Count of items near expiration"
-            },
-            "expiredCount": {
-              "type": "integer",
-              "minimum": 0,
-              "description": "Count of expired items"
-            }
-          },
-          "required": ["hasExpiration"],
-          "additionalProperties": false
-        }
-      },
-      "required": ["inspectionDate", "grade", "defectRate", "expirationTracking"],
-      "additionalProperties": false
-    }
-  },
-  "properties": {
-    "productId": {
-      "type": "string",
-      "description": "The unique identifier for the product"
-    },
-    "productMetadata": {
-      "type": "object",
-      "properties": {
-        "sku": {
-          "type": "string",
-          "description": "Stock keeping unit"
-        },
-        "barcode": {
-          "type": "string",
-          "pattern": "^[0-9]{12,13}$",
-          "description": "Product barcode (UPC/EAN)"
-        },
-        "category": {
-          "type": "object",
-          "properties": {
-            "primary": {
-              "type": "string",
-              "description": "Primary category"
-            },
-            "secondary": {
-              "type": "string",
-              "description": "Secondary category"
-            },
-            "tags": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              },
-              "description": "Category tags"
-            }
-          },
-          "required": ["primary"],
-          "additionalProperties": false
-        },
-        "dimensions": {
-          "type": "object",
-          "properties": {
-            "length": {
-              "type": "number",
-              "minimum": 0,
-              "description": "Length in centimeters"
-            },
-            "width": {
-              "type": "number",
-              "minimum": 0,
-              "description": "Width in centimeters"
-            },
-            "height": {
-              "type": "number",
-              "minimum": 0,
-              "description": "Height in centimeters"
-            },
-            "weight": {
-              "type": "number",
-              "minimum": 0,
-              "description": "Weight in grams"
-            }
-          },
-          "required": ["length", "width", "height", "weight"],
-          "additionalProperties": false
-        }
-      },
-      "required": ["sku", "barcode", "category", "dimensions"],
-      "additionalProperties": false
-    },
-    "aggregatedInventory": {
-      "type": "object",
-      "properties": {
-        "totalAvailable": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Total available quantity across all locations"
-        },
-        "totalReserved": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Total reserved quantity across all locations"
-        },
-        "totalInTransit": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Total quantity in transit between locations"
-        },
-        "safetyStock": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Safety stock level"
-        },
-        "reorderLevel": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Reorder point threshold"
-        }
-      },
-      "required": ["totalAvailable", "totalReserved", "totalInTransit", "safetyStock", "reorderLevel"],
-      "additionalProperties": false
-    },
-    "locationBreakdown": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "properties": {
-          "location": {
-            "$ref": "#/definitions/LocationDetails"
-          },
-          "inventory": {
-            "type": "object",
-            "properties": {
-              "availableQuantity": {
-                "type": "integer",
-                "minimum": 0,
-                "description": "Available quantity at this location"
-              },
-              "reservedQuantity": {
-                "type": "integer",
-                "minimum": 0,
-                "description": "Reserved quantity at this location"
-              },
-              "lastCountDate": {
-                "type": "string",
-                "format": "date",
-                "description": "Date of last physical count"
-              }
-            },
-            "required": ["availableQuantity", "reservedQuantity", "lastCountDate"],
-            "additionalProperties": false
-          },
-          "qualityMetrics": {
-            "$ref": "#/definitions/QualityMetrics"
-          }
-        },
-        "required": ["location", "inventory", "qualityMetrics"],
-        "additionalProperties": false
-      },
-      "minItems": 1,
-      "description": "Inventory breakdown by location"
-    },
-    "supplierInformation": {
-      "type": "array",
-      "items": {
-        "$ref": "#/definitions/SupplierInfo"
-      },
-      "description": "Information about suppliers for this product"
-    },
-    "recentMovements": {
-      "type": "array",
-      "items": {
-        "$ref": "#/definitions/InventoryMovement"
-      },
-      "maxItems": 10,
-      "description": "Recent inventory movements (last 10)"
-    },
-    "alerts": {
-      "type": "object",
-      "properties": {
-        "lowStock": {
-          "type": "boolean",
-          "description": "Whether product is below reorder level"
-        },
-        "qualityIssues": {
-          "type": "boolean",
-          "description": "Whether there are quality concerns"
-        },
-        "supplierDelays": {
-          "type": "boolean",
-          "description": "Whether there are supplier delivery delays"
-        },
-        "messages": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "properties": {
-              "severity": {
-                "type": "string",
-                "enum": ["info", "warning", "error", "critical"],
-                "description": "Alert severity level"
-              },
-              "message": {
-                "type": "string",
-                "description": "Alert message"
-              },
-              "timestamp": {
-                "type": "string",
-                "format": "date-time",
-                "description": "When the alert was generated"
-              }
-            },
-            "required": ["severity", "message", "timestamp"],
-            "additionalProperties": false
-          },
-          "description": "Alert messages"
-        }
-      },
-      "required": ["lowStock", "qualityIssues", "supplierDelays", "messages"],
-      "additionalProperties": false
-    },
-    "lastUpdated": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Timestamp when this data was last updated"
-    }
-  },
-  "required": [
-    "productId",
-    "productMetadata",
-    "aggregatedInventory",
-    "locationBreakdown",
-    "supplierInformation",
-    "recentMovements",
-    "alerts",
-    "lastUpdated"
-  ],
-  "additionalProperties": false
-}
-  
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/versioned/0.0.1/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/versioned/0.0.1/index.mdx
deleted file mode 100644
index 6ee3b58fa..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/versioned/0.0.1/index.mdx
+++ /dev/null
@@ -1,46 +0,0 @@
----
-id: InventoryService
-version: 0.0.1
-name: Inventory Service
-summary: |
-  Service that handles the inventory
-owners:
-  - dboyne
-  - full-stack
-  - mobile-devs
-receives:
-  - id: OrderConfirmed
-    from:
-      - id: 'orders.{env}.events'
-  - id: OrderCancelled
-    from:
-      - id: 'orders.{env}.events'
-  - id: OrderAmended
-    from:
-      - id: 'orders.{env}.events'
-        parameters:
-          env: staging
-  - id: UpdateInventory
-    from:
-      - id: 'inventory.{env}.events'
-        parameters:
-          env: staging
-sends:
-  - id: InventoryAdjusted
-    to:
-      - id: 'inventory.{env}.events'
-  - id: OutOfStock
-    to:
-      - id: 'inventory.{env}.events'
-repository:
-  language: JavaScript
-  url: 'https://github.com/event-catalog/pretend-shipping-service'
----
-
-## Overview
-
-The Inventory Service is a critical component of the system responsible for managing product stock levels, tracking inventory movements, and ensuring product availability. It interacts with other services to maintain accurate inventory records and supports operations such as order fulfillment, restocking, and inventory audits.
-
-## Architecture diagram
-
-<NodeGraph title="Hello world" />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/channels/notifications-queue/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/channels/notifications-queue/index.mdx
deleted file mode 100644
index 7fed04bfd..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/channels/notifications-queue/index.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-id: notifications-queue
-name: Notifications Queue
-version: 0.0.1
-summary: |
-  Queue for notifications
-owners:
-  - order-management
----
-
-## Overview
-
-The Notifications Queue is a queue for notifications. It is used to store notifications that need to be sent to users.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/containers/notifications-queue/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/containers/notifications-queue/index.mdx
deleted file mode 100644
index 8e6616505..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/containers/notifications-queue/index.mdx
+++ /dev/null
@@ -1,186 +0,0 @@
----
-id: notifications-queue
-name: Notifications Queue
-version: 0.0.1
-container_type: other
-technology: sqs
-access_mode: readWrite
-classification: internal
-retention: 14d
-residency: eu-west-1
-summary: Message queue for asynchronous notification delivery across email, SMS, and push channels
----
-
-<NodeGraph />
-
-### What is this?
-Notifications Queue is an AWS SQS FIFO queue that buffers notification requests for asynchronous processing. It ensures reliable, ordered delivery of notifications while decoupling notification producers from delivery channels.
-
-### What does it store?
-- **Notification Messages**: Structured notification payloads with recipient, channel, template, and data
-- **Delivery Metadata**: Priority, retry count, scheduled delivery time
-- **Batch Groups**: Related notifications grouped for efficient batch processing
-- **Dead Letter Queue Messages**: Failed notifications after max retry attempts
-
-### Queue structure
-```
-notifications-queue (Primary Queue)
-├── High Priority (MessageGroupId: priority-high)
-├── Normal Priority (MessageGroupId: priority-normal)
-└── Low Priority (MessageGroupId: priority-low)
-
-notifications-dlq (Dead Letter Queue)
-└── Failed messages after 3 retry attempts
-```
-
-### Message format
-```json
-{
-  "notification_id": "uuid",
-  "recipient": {
-    "customer_id": "uuid",
-    "email": "customer@example.com",
-    "phone": "+1234567890",
-    "device_tokens": ["fcm_token_123"]
-  },
-  "channel": "EMAIL | SMS | PUSH | IN_APP",
-  "template_id": "order_confirmation",
-  "template_data": {
-    "order_id": "12345",
-    "order_total": "$99.99",
-    "items_count": 3
-  },
-  "priority": "HIGH | NORMAL | LOW",
-  "scheduled_at": "2024-01-15T10:30:00Z",
-  "metadata": {
-    "source_service": "OrdersService",
-    "event_type": "OrderConfirmed",
-    "idempotency_key": "uuid"
-  }
-}
-```
-
-### Who writes to it?
-- **OrdersService** sends order-related notifications (confirmations, updates, cancellations)
-- **PaymentService** sends payment status notifications
-- **SubscriptionService** sends subscription lifecycle notifications
-- **InventoryService** sends low-stock alerts to internal teams
-- **Fraud DetectionService** sends fraud alert notifications
-
-### Who reads from it?
-- **NotificationService Workers** consume messages and dispatch to delivery channels
-- **Email Worker**: Processes EMAIL channel notifications via SendGrid/SES
-- **SMS Worker**: Processes SMS notifications via Twilio
-- **Push Worker**: Processes mobile push notifications via FCM/APNs
-- **In-App Worker**: Writes in-app notifications to database
-
-### Message processing flow
-1. Service publishes notification to queue with appropriate priority
-2. NotificationService worker polls queue (long polling, 20s)
-3. Worker validates message and loads template
-4. Renders template with provided data
-5. Dispatches to delivery channel (email provider, SMS gateway, etc.)
-6. On success: delete message from queue
-7. On failure: message returned to queue (visibility timeout) for retry
-8. After 3 failures: message moved to DLQ for manual review
-
-### Queue configuration
-- **Queue type**: FIFO (First-In-First-Out) for ordered delivery
-- **Message retention**: 14 days
-- **Visibility timeout**: 60 seconds (time for worker to process)
-- **Delivery delay**: 0 seconds (immediate)
-- **Max message size**: 256 KB
-- **Dead letter queue**: After 3 receive attempts
-- **Throughput**: 3,000 messages/second per message group
-
-### Priority handling
-- **HIGH**: Immediate delivery (fraud alerts, payment failures, security notifications)
-- **NORMAL**: Standard delivery (order confirmations, shipping updates)
-- **LOW**: Batch delivery (marketing emails, digest notifications)
-
-Priority implemented via message group IDs - high priority workers process high-priority groups first.
-
-### Access patterns and guidance
-- Use message group IDs to maintain order within notification types
-- Include idempotency keys to prevent duplicate notifications
-- Set appropriate visibility timeout based on channel latency
-- Monitor DLQ and investigate failures
-- Use batch sends for multiple notifications to same recipient
-
-### Monitoring and alerts
-- Queue depth monitoring (alert if > 10,000 messages)
-- DLQ message count (alert on any messages)
-- Message age monitoring (alert if oldest message > 5 minutes)
-- Consumer lag (alert if lag > 30 seconds)
-- Channel-specific delivery failure rates
-
-### Security and access control
-- **IAM policies**: Service-specific roles for send/receive permissions
-- **Encryption**: Messages encrypted at rest with AWS KMS
-- **Encryption in transit**: TLS for all queue operations
-- **Access logs**: CloudTrail logs all API calls
-- **PII protection**: Sensitive data in messages should be references, not full values
-
-### Requesting access
-To request access to Notifications Queue:
-
-1. **Publish access** (for services sending notifications):
-   - Submit request via [AWS Access Portal](https://company.awsapps.com)
-   - Select "SQS Send Permission" → "notifications-queue"
-   - Requires notification team approval
-   - IAM policy attached within 1 business day
-
-2. **Consume access** (for worker services):
-   - Restricted to NotificationService worker roles only
-   - New worker setup requires architecture review
-   - Contact #notifications-team for onboarding
-
-3. **DLQ access** (for troubleshooting):
-   - Read-only access via #notifications-oncall
-   - Write access requires incident ticket
-
-**Contact**:
-- Slack: #notifications-team
-- Email: notifications-team@company.com
-- On-call: PagerDuty #notifications-oncall
-
-### Retry and failure handling
-- **Transient failures**: Automatic retry via SQS (exponential backoff)
-- **Delivery failures**: Logged with error details, retried up to 3 times
-- **DLQ messages**: Daily review, manual retry or discard after investigation
-- **Circuit breaker**: If channel failure rate > 50%, pause and alert
-
-### Rate limiting
-- **Email**: 100 emails/second (provider limit)
-- **SMS**: 10 SMS/second (cost control)
-- **Push**: 1,000 push/second
-- Per-recipient limits to prevent spam: max 10 notifications/hour
-
-### Local development
-- LocalStack SQS emulation: `docker-compose up localstack`
-- Connection: `AWS_ENDPOINT_URL=http://localhost:4566`
-- Create queue: `npm run setup:local-queues`
-- Send test message: `npm run test:send-notification`
-
-### Performance characteristics
-- **Delivery latency**: p99 < 5 seconds from queue to delivery
-- **Throughput**: 10,000+ notifications/minute
-- **Message processing time**: p95 < 2 seconds
-- **DLQ rate**: < 0.1% of messages
-
-### Common issues and troubleshooting
-- **High queue depth**: Scale up worker instances or check for processing errors
-- **Messages in DLQ**: Check worker logs, validate template IDs, verify channel credentials
-- **Duplicate notifications**: Ensure idempotency keys are unique and properly checked
-- **Slow processing**: Check channel API latencies, may need to increase visibility timeout
-- **Message loss**: Verify IAM permissions, check for queue purge events in CloudTrail
-
-### Best practices
-- Always include idempotency key to prevent duplicates
-- Use structured logging to correlate queue messages with delivery outcomes
-- Set appropriate message retention based on business requirements
-- Monitor DLQ regularly and investigate root causes
-- Test notification templates before deploying to production
-- Use message attributes for filtering and routing
-
-For more information, see NotificationService documentation and SQS Best Practices Guide.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/index.mdx
deleted file mode 100644
index 4ea658534..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/index.mdx
+++ /dev/null
@@ -1,99 +0,0 @@
----
-id: NotificationService
-version: 0.0.2
-name: Notifications
-summary: |
-  Service that handles notifications across multiple channels (email, SMS, push)
-owners:
-  - order-management
-sends: 
-  - id: NotificationSent
-receives:
-  - id: InventoryAdjusted
-    from:
-      - id: notifications-queue
-  - id: PaymentProcessed
-    from:
-      - id: notifications-queue
-  - id: InvoiceGenerated
-    from:
-      - id: notifications-queue
-  - id: OutOfStock
-    from:
-      - id: notifications-queue
-readsFrom:
-  - id: notifications-queue
-    version: 0.0.1
-repository:
-  language: JavaScript
-  url: 'https://github.com/event-catalog/pretend-shipping-service'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The Notification Service is responsible for managing and delivering notifications to users and other services. It supports various notification channels such as email, SMS, push notifications, and in-app notifications. The service ensures reliable and timely delivery of messages and integrates with other services to trigger notifications based on specific events.
-
-<Tiles >
-    <Tile icon="DocumentIcon" href={`/docs/services/${frontmatter.id}/${frontmatter.version}/changelog`}  title="View the changelog" description="Want to know the history of this service? View the change logs" />
-    <Tile icon="UserGroupIcon" href="/docs/teams/full-stack" title="Contact the team" description="Any questions? Feel free to contact the owners" />
-    <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="This service sends messages to downstream consumers" />
-    <Tile icon="BoltIcon"  href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="This service receives messages from other services" />
-</Tiles>
-
-### Core features
-
-| Feature | Description |
-|---------|-------------|
-| Multi-Channel Delivery | Supports notifications via email, SMS, push notifications, and in-app messages |
-| Template Management | Customizable notification templates with dynamic content placeholders |
-| Delivery Status Tracking | Real-time tracking and monitoring of notification delivery status |
-| Rate Limiting | Prevents notification flooding through configurable rate limits |
-| Priority Queue | Handles urgent notifications with priority delivery mechanisms |
-| Batch Processing | Efficiently processes and sends bulk notifications |
-| Retry Mechanism | Automatic retry logic for failed notification deliveries |
-| Event-Driven Notifications | Triggers notifications based on system events and user actions |
-
-
-
-## Architecture diagram
-
-<NodeGraph />
-
-<MessageTable format="all" limit={4} />
-
-## Core Concepts
-
-<AccordionGroup>
-  <Accordion title="Notification">
-    - Description: A message that is sent to a user or a service.
-    - Attributes: notificationId, type, recipient, content, channel, status, timestamp
-  </Accordion>
-  <Accordion title="Channel">
-    - Description: The medium through which the notification is delivered (e.g., email, SMS, push notification).
-    - Attributes: channelId, name, provider, configuration 
-  </Accordion>
-</AccordionGroup>
-
-## Infrastructure
-
-The Notification Service is hosted on AWS.
-
-The diagram below shows the infrastructure of the Notification Service. The service is hosted on AWS and uses AWS Lambda to handle the notification requests. The notification is stored in an AWS Aurora database and the notification metadata is stored in an AWS S3 bucket.
-
-```mermaid
-architecture-beta
-    group api(logos:aws)
-
-    service db(logos:aws-aurora)[Notification DB] in api
-    service disk1(logos:aws-s3)[Notification Metadata] in api
-    service server(logos:aws-lambda)[Notification Handler] in api
-
-    db:L -- R:server
-    disk1:T -- B:server
-```
-
-You can find more information about the Notification Service infrastructure in the [Notification Service documentation](https://github.com/event-catalog/pretend-shipping-service/blob/main/README.md).
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/queries/GetNotificationDetails/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/queries/GetNotificationDetails/index.mdx
deleted file mode 100644
index 48fceec00..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/queries/GetNotificationDetails/index.mdx
+++ /dev/null
@@ -1,28 +0,0 @@
----
-id: GetNotificationDetails
-name: Get notification details
-version: 0.0.1
-summary: |
-  GET request that will return detailed information about a specific notification, identified by its notificationId.
-owners:
-    - dboyne
-badges:
-    - content: Recently updated!
-      backgroundColor: green
-      textColor: green
-schemaPath: schema.json
-sidebar:
-  badge: 'GET'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `GetNotificationDetails` message is a query used to retrieve detailed information about a specific notification identified by its `notificationId`. It provides a comprehensive overview of the notification, including the title, message content, status (read/unread), the date it was created, and any additional metadata related to the notification, such as associated orders or system events. This query is helpful in scenarios where users or systems need detailed insights into a particular notification, such as retrieving full messages or auditing notifications sent to users.
-
-Use cases include viewing detailed information about order updates, system notifications, or promotional messages, allowing users to view their full notification history and details.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/queries/GetNotificationDetails/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/queries/GetNotificationDetails/schema.json
deleted file mode 100644
index 4aafa54b1..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/queries/GetNotificationDetails/schema.json
+++ /dev/null
@@ -1,56 +0,0 @@
-
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "GetNotificationDetailsResponse",
-  "type": "object",
-  "properties": {
-    "notificationId": {
-      "type": "string",
-      "description": "The unique identifier for the notification."
-    },
-    "title": {
-      "type": "string",
-      "description": "The title or subject of the notification."
-    },
-    "message": {
-      "type": "string",
-      "description": "The content or message body of the notification."
-    },
-    "status": {
-      "type": "string",
-      "enum": ["unread", "read"],
-      "description": "The read status of the notification."
-    },
-    "userId": {
-      "type": "string",
-      "description": "The unique identifier for the user who received the notification."
-    },
-    "createdAt": {
-      "type": "string",
-      "format": "date-time",
-      "description": "The date and time when the notification was created."
-    },
-    "type": {
-      "type": "string",
-      "description": "The type of the notification, such as order or system."
-    },
-    "metadata": {
-      "type": "object",
-      "description": "Additional metadata related to the notification, such as order details.",
-      "properties": {
-        "orderId": {
-          "type": "string",
-          "description": "The associated order ID, if applicable."
-        },
-        "shippingProvider": {
-          "type": "string",
-          "description": "The shipping provider for the associated order, if applicable."
-        }
-      },
-      "required": ["orderId"],
-      "additionalProperties": false
-    }
-  },
-  "required": ["notificationId", "title", "message", "status", "userId", "createdAt", "type"],
-  "additionalProperties": false
-}
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/queries/GetUserNotifications/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/queries/GetUserNotifications/index.mdx
deleted file mode 100644
index 0b4d0a2f3..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/queries/GetUserNotifications/index.mdx
+++ /dev/null
@@ -1,29 +0,0 @@
----
-id: GetUserNotifications
-name: Get user notifications
-version: 0.0.1
-summary: |
-  GET request that will return a list of notifications for a specific user, with options to filter by status (unread or all).
-owners:
-    - dboyne
-badges:
-    - content: Recently updated!
-      backgroundColor: green
-      textColor: green
-schemaPath: schema.json
-sidebar:
-  badge: 'GET'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `GetUserNotifications` message is a query used to retrieve a list of notifications for a specific user. It allows filtering by notification status, such as unread or all notifications. This query is typically utilized by notification services to display user-specific messages, such as order updates, promotional offers, or system notifications. It supports pagination through `limit` and `offset` parameters, ensuring that only a manageable number of notifications are retrieved at once. This query helps users stay informed about important events or updates related to their account, orders, or the platform.
-
-Use cases include delivering notifications for order updates, promotional campaigns, or general system messages to keep the user informed.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
-
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/queries/GetUserNotifications/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/queries/GetUserNotifications/schema.json
deleted file mode 100644
index 033b654de..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/NotificationService/queries/GetUserNotifications/schema.json
+++ /dev/null
@@ -1,47 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "title": "GetUserNotificationsResponse",
-    "type": "object",
-    "properties": {
-      "userId": {
-        "type": "string",
-        "description": "The unique identifier for the user."
-      },
-      "notifications": {
-        "type": "array",
-        "description": "A list of notifications for the user.",
-        "items": {
-          "type": "object",
-          "properties": {
-            "notificationId": {
-              "type": "string",
-              "description": "The unique identifier for the notification."
-            },
-            "title": {
-              "type": "string",
-              "description": "The title or subject of the notification."
-            },
-            "message": {
-              "type": "string",
-              "description": "The message body of the notification."
-            },
-            "status": {
-              "type": "string",
-              "enum": ["unread", "read"],
-              "description": "The read status of the notification."
-            },
-            "createdAt": {
-              "type": "string",
-              "format": "date-time",
-              "description": "The date and time when the notification was created."
-            }
-          },
-          "required": ["notificationId", "title", "message", "status", "createdAt"],
-          "additionalProperties": false
-        }
-      }
-    },
-    "required": ["userId", "notifications"],
-    "additionalProperties": false
-  }
-  
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/changelog.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/changelog.mdx
deleted file mode 100644
index 111462129..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/changelog.mdx
+++ /dev/null
@@ -1,5 +0,0 @@
----
-createdAt: 2024-08-01
----
-
-This is my entry
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/channels/sqs-channel/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/channels/sqs-channel/index.mdx
deleted file mode 100644
index 41ae41734..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/channels/sqs-channel/index.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
----
-id: orders-service-sqs-channel
-name: Orders Service SQS Channel
-version: 1.0.0
-summary: |
-  SQS channel for the Orders Service
-owners:
-  - dboyne
----
-
-The Orders Service SQS Channel is used to process messages from the Orders Service.
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/commands/PlaceOrder/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/commands/PlaceOrder/index.mdx
deleted file mode 100644
index 5b5c30377..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/commands/PlaceOrder/index.mdx
+++ /dev/null
@@ -1,38 +0,0 @@
----
-id: PlaceOrder
-name: Place Order
-version: 0.0.1
-summary: |
-  Command that will place an order
-owners:
-    - dboyne
-    - msmith
-    - asmith
-    - full-stack
-    - mobile-devs
-badges:
-    - content: Recently updated!
-      backgroundColor: green
-      textColor: green
-schemaPath: 'schema.json'
-sidebar:
-  badge: 'POST'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The Order Placement Command is a versatile and robust system designed to streamline the process of placing an order. This command takes care of all the essential details needed to complete a purchase, ensuring a smooth and efficient transaction from start to finish.
-
-## Architecture diagram
-
-<NodeGraph/>
-
-## Schema
-
-<SchemaViewer file="schema.json"/>
-
-<Footer />
-
-
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/containers/order-metadata-store/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/containers/order-metadata-store/index.mdx
deleted file mode 100644
index 16424189a..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/containers/order-metadata-store/index.mdx
+++ /dev/null
@@ -1,210 +0,0 @@
----
-id: order-metadata-store
-name: Order Metadata Store
-version: 0.0.1
-container_type: objectStore
-technology: aws-s3
-summary: Long-term storage of order documents, receipts, and metadata files
-access_mode: read
-residency: eu-west-1
-retention: 7y
----
-
-<NodeGraph />
-
-The Order Metadata Store is an AWS S3 bucket that provides scalable, durable object storage for order-related documents and metadata. This storage system handles large files and documents that are associated with orders but don't require real-time database access.
-
-## Overview
-
-This S3-based object store serves as the primary repository for:
-
-- Order confirmation PDFs and receipts
-- Customer upload documents (delivery instructions, custom specifications)
-- Order processing audit trails and logs
-- Large metadata files that exceed database field limits
-- Invoice documents and tax records
-- Shipping labels and tracking documents
-
-## Bucket Configuration
-
-### Structure
-- **Bucket Name**: `acmecorp-order-metadata-prod`
-- **Region**: `us-east-1`
-- **Storage Classes**:
-  - Standard (first 30 days)
-  - Standard-IA (30-90 days)
-  - Glacier (90+ days)
-- **Versioning**: Enabled
-- **Cross-Region Replication**: Enabled to `us-west-2`
-
-### Folder Organization
-```
-/orders/
-  /{year}/
-    /{month}/
-      /{order-id}/
-        /receipts/
-          - order-confirmation.pdf
-          - payment-receipt.pdf
-        /documents/
-          - delivery-instructions.txt
-          - custom-specifications.json
-        /audit/
-          - processing-log.json
-          - status-changes.json
-        /invoices/
-          - invoice.pdf
-          - tax-document.pdf
-        /shipping/
-          - shipping-label.pdf
-          - tracking-info.json
-```
-
-## Data Types and Formats
-
-### Order Receipts
-- **Format**: PDF
-- **Size Range**: 50KB - 2MB
-- **Retention**: 7 years (regulatory compliance)
-- **Access Pattern**: High read frequency first 30 days, then infrequent
-
-### Customer Documents
-- **Formats**: PDF, TXT, JSON, JPG, PNG
-- **Size Range**: 10KB - 50MB
-- **Retention**: 2 years
-- **Access Pattern**: Infrequent reads after order completion
-
-### Audit Trails
-- **Format**: JSON, CSV
-- **Size Range**: 1KB - 10MB
-- **Retention**: 5 years
-- **Access Pattern**: Rare access, compliance queries only
-
-### Invoice Documents
-- **Format**: PDF, XML
-- **Size Range**: 100KB - 5MB
-- **Retention**: 7 years (tax compliance)
-- **Access Pattern**: Medium frequency during tax season
-
-## Performance Characteristics
-
-- **Upload Throughput**: 1,000+ objects per second
-- **Download Latency**: < 100ms for Standard storage
-- **Availability**: 99.999999999% (11 9's) durability
-- **Consistency**: Strong read-after-write consistency
-- **Multi-part Upload**: Enabled for files > 100MB
-
-## Security and Access Control
-
-### IAM Policies
-- **OrderService Role**: Full read/write access to order folders
-- **ReportingService Role**: Read-only access for analytics
-- **CustomerService Role**: Read access to customer documents
-- **Compliance Role**: Full access for audit purposes
-
-### Encryption
-- **At Rest**: AES-256 with AWS KMS
-- **In Transit**: TLS 1.2+
-- **Key Management**: Customer-managed KMS keys with automatic rotation
-
-### Access Logging
-- **CloudTrail**: All API calls logged
-- **S3 Access Logs**: Detailed request logging
-- **Monitoring**: CloudWatch metrics and alarms
-- **Audit**: Quarterly access reviews
-
-## Lifecycle Management
-
-### Automated Transitions
-1. **0-30 days**: Standard storage class
-2. **30-90 days**: Standard-IA (Infrequent Access)
-3. **90-365 days**: Glacier storage class
-4. **1+ years**: Glacier Deep Archive
-
-### Data Retention Policies
-- **Order receipts**: 7 years (regulatory)
-- **Customer documents**: 2 years (business requirement)
-- **Audit trails**: 5 years (compliance)
-- **Invoice documents**: 7 years (tax law)
-- **Automated deletion**: After retention period expires
-
-## Integration Patterns
-
-### Write Operations
-- Orders Service uploads receipts and confirmations
-- Customer portal uploads delivery instructions
-- Payment Service stores transaction receipts
-- Shipping Service uploads tracking labels
-
-### Read Operations
-- Customer Service retrieves order documents for support
-- Reporting Service accesses historical data
-- Compliance Service performs audit queries
-- External systems via pre-signed URLs
-
-## Monitoring and Alerting
-
-### Key Metrics
-- **Upload Success Rate**: > 99.9%
-- **Download Latency**: < 100ms (95th percentile)
-- **Storage Utilization**: Tracked per folder structure
-- **Cost Optimization**: Storage class distribution
-
-### Alerts
-- Upload failure rate > 0.1%
-- Unusual access patterns (security)
-- Storage cost increases > 20% month-over-month
-- Lifecycle policy failures
-
-## Backup and Disaster Recovery
-
-### Backup Strategy
-- **Cross-Region Replication**: Real-time to us-west-2
-- **Versioning**: 30 previous versions retained
-- **MFA Delete**: Required for permanent deletion
-- **Point-in-Time Recovery**: Via object versioning
-
-### Disaster Recovery
-- **RTO**: 2 hours (switch to backup region)
-- **RPO**: < 15 minutes (replication lag)
-- **Testing**: Monthly failover tests
-- **Documentation**: Runbooks for recovery scenarios
-
-## Cost Optimization
-
-### Current Usage (Monthly)
-- **Standard Storage**: ~500GB ($11.50)
-- **Standard-IA**: ~2TB ($25.60)
-- **Glacier**: ~10TB ($40.00)
-- **Requests**: ~1M PUT/GET ($4.00)
-- **Data Transfer**: ~100GB ($9.00)
-- **Total**: ~$90/month
-
-### Optimization Strategies
-- Automated lifecycle transitions
-- Regular cleanup of expired objects
-- Compression for text-based files
-- Cost allocation tags per business unit
-
-## Dependencies
-
-- **AWS KMS**: Encryption key management
-- **CloudWatch**: Monitoring and metrics
-- **CloudTrail**: API call auditing
-- **Lambda**: Automated cleanup functions
-- **SNS**: Alert notifications
-
-## Compliance
-
-- **SOX**: Financial record retention
-- **PCI DSS**: Payment card data storage
-- **GDPR**: Customer data handling
-- **HIPAA**: Healthcare order compliance (when applicable)
-
-## Contact Information
-
-For questions about the Order Metadata Store:
-- **Primary**: Orders Team (orders@acmecorp.com)
-- **Infrastructure**: Michael Chen (m.chen@acmecorp.com)
-- **Security**: security@acmecorp.com
-- **On-call**: Use PagerDuty escalation policy "Orders-Infrastructure"
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/containers/orders-db/db.sql b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/containers/orders-db/db.sql
deleted file mode 100644
index 1aaec2623..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/containers/orders-db/db.sql
+++ /dev/null
@@ -1,45 +0,0 @@
--- Orders Database - Simple orders table for documentation
--- This is fake data for documentation purposes
-
--- Drop table if it exists (for clean re-runs)
-DROP TABLE IF EXISTS orders;
-
--- Create orders table
-CREATE TABLE orders (
-    order_id SERIAL PRIMARY KEY,
-    order_number VARCHAR(50) UNIQUE NOT NULL,
-    customer_name VARCHAR(100) NOT NULL,
-    customer_email VARCHAR(100) NOT NULL,
-    order_status VARCHAR(20) DEFAULT 'pending',
-    order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    product_name VARCHAR(200) NOT NULL,
-    quantity INTEGER NOT NULL,
-    unit_price DECIMAL(10,2) NOT NULL,
-    total_amount DECIMAL(10,2) NOT NULL,
-    payment_method VARCHAR(50),
-    payment_status VARCHAR(20) DEFAULT 'pending',
-    shipping_address VARCHAR(200),
-    notes TEXT,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-
--- Insert sample orders
-INSERT INTO orders (order_number, customer_name, customer_email, order_status, product_name, quantity, unit_price, total_amount, payment_method, payment_status, shipping_address) VALUES
-('ORD-2024-001', 'John Doe', 'john.doe@email.com', 'delivered', 'MacBook Pro 14"', 1, 1999.99, 1999.99, 'credit_card', 'completed', '123 Main St, New York, NY 10001'),
-('ORD-2024-002', 'Jane Smith', 'jane.smith@email.com', 'shipped', 'iPhone 15 Pro', 1, 999.99, 999.99, 'paypal', 'completed', '456 Oak Ave, Los Angeles, CA 90210'),
-('ORD-2024-003', 'Michael Johnson', 'michael.johnson@email.com', 'processing', 'AirPods Pro', 2, 249.99, 499.98, 'credit_card', 'completed', '789 Pine Rd, Chicago, IL 60601'),
-('ORD-2024-004', 'Emily Davis', 'emily.davis@email.com', 'pending', 'Cotton T-Shirt', 3, 19.99, 59.97, 'debit_card', 'pending', '321 Elm St, Houston, TX 77001'),
-('ORD-2024-005', 'David Wilson', 'david.wilson@email.com', 'delivered', 'Smart Watch', 1, 299.99, 299.99, 'credit_card', 'completed', '654 Maple Dr, Phoenix, AZ 85001'),
-('ORD-2024-006', 'Sarah Brown', 'sarah.brown@email.com', 'cancelled', 'Travel Backpack', 1, 79.99, 79.99, 'paypal', 'refunded', '987 Cedar Ln, Philadelphia, PA 19101'),
-('ORD-2024-007', 'James Miller', 'james.miller@email.com', 'shipped', 'Premium Coffee Beans', 5, 24.99, 124.95, 'credit_card', 'completed', '147 Birch Way, San Antonio, TX 78201'),
-('ORD-2024-008', 'Lisa Garcia', 'lisa.garcia@email.com', 'delivered', 'Running Sneakers', 1, 89.99, 89.99, 'apple_pay', 'completed', '258 Spruce St, San Diego, CA 92101'),
-('ORD-2024-009', 'Robert Martinez', 'robert.martinez@email.com', 'processing', 'iPad Air', 1, 599.99, 599.99, 'google_pay', 'completed', '369 Willow Ave, Dallas, TX 75201'),
-('ORD-2024-010', 'Jennifer Anderson', 'jennifer.anderson@email.com', 'pending', 'The Great Gatsby', 2, 12.99, 25.98, 'credit_card', 'pending', '741 Poplar Rd, San Jose, CA 95101'),
-('ORD-2024-011', 'Mark Thompson', 'mark.thompson@email.com', 'delivered', 'Wireless Headphones', 1, 149.99, 149.99, 'paypal', 'completed', '852 Oak Street, Seattle, WA 98101'),
-('ORD-2024-012', 'Amanda White', 'amanda.white@email.com', 'shipped', 'Gaming Mouse', 2, 79.99, 159.98, 'credit_card', 'completed', '963 Pine Avenue, Denver, CO 80201');
-
--- Create indexes for better performance
-CREATE INDEX idx_orders_status ON orders(order_status);
-CREATE INDEX idx_orders_date ON orders(order_date);
-CREATE INDEX idx_orders_customer_email ON orders(customer_email);
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/containers/orders-db/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/containers/orders-db/index.mdx
deleted file mode 100644
index c20b53e32..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/containers/orders-db/index.mdx
+++ /dev/null
@@ -1,104 +0,0 @@
----
-id: orders-db
-name: Orders DB
-version: 0.0.1
-container_type: database
-technology: postgres@14
-authoritative: true
-access_mode: readWrite
-purpose: System of record for Orders and OrderLines
-classification: internal
-retention: 7y
-residency: eu-west-1
----
-
-<NodeGraph />
-
-### What is this?
-Orders DB is the primary database for the Orders domain. It is a PostgreSQL 14 database and acts as the system of record for orders and their line items. If you are looking for where an order lives, how to query it, or how order state changes are persisted, you are in the right place.
-
-### What does it store?
-- **Orders**: One row per customer order. Includes status, totals, currency, timestamps.
-- **Order Lines**: One row per item inside an order. Includes product, quantities, and pricing.
-- **Relationships**: `order_lines` are linked to `orders` by `order_id` (cascading deletes are enabled).
-
-## Schema and test data for Orders DB
-<AccordionGroup>
-  <Accordion title="Orders DB Schema">
-    <Schema file="db.sql" lang="sql" title="Orders DB Schema.sql" />
-  </Accordion>
-  <Accordion title="Test data for Orders DB">
-    <Schema file="test-data.sql" lang="sql" title="Test data for Orders DB.sql" />
-  </Accordion>
-</AccordionGroup>
-
-### High-level data model
-- An `order` has many `order_lines`.
-- Order lifecycle is tracked via the `status` column. Common statuses: `PENDING`, `PAID`, `CANCELLED`, `FULFILLED`, `REFUNDED`.
-- Monetary values are stored as integer cents; currency is 3-letter ISO (e.g. `USD`).
-
-
-### Common queries
-```sql
--- Fetch a single order with its lines
-SELECT o.*, l.*
-FROM orders o
-LEFT JOIN order_lines l USING (order_id)
-WHERE o.order_id = $1;
-
--- List recent orders for a customer (paged)
-SELECT *
-FROM orders
-WHERE customer_id = $1
-ORDER BY created_at DESC
-LIMIT $2 OFFSET $3;
-
--- Daily revenue (rounded to dollars) for the last 30 days
-SELECT date_trunc('day', created_at) AS day,
-       SUM(total_amount_cents)/100.0 AS revenue
-FROM orders
-WHERE created_at >= now() - interval '30 days'
-  AND status IN ('PAID','FULFILLED','REFUNDED')
-GROUP BY 1
-ORDER BY 1;
-```
-
-### How data gets here (lifecycle)
-1. A user places an order → `OrdersService` validates input and writes to `orders` and `order_lines` in a single transaction.
-2. Payment success updates the order `status` to `PAID`.
-3. Fulfillment updates the order `status` to `FULFILLED`.
-4. Cancellations and refunds update `status` accordingly.
-5. Each change emits a domain event that other services consume.
-
-### Access patterns and guidance
-- Use the `order_id` for point lookups; most queries should be indexed by this or `customer_id`.
-- Prefer reading from read replicas for analytics/reporting workloads when available.
-- Treat `status` as the source of truth for order lifecycle; avoid inferring state from timestamps alone.
-- Do not store PII beyond `customer_id` here; card data never resides in this database.
-
-### Retention and residency
-- Retention: 7 years (see frontmatter). Archival or partitioning may be used to keep hot data smaller.
-- Residency: `eu-west-1` (see frontmatter). Ensure cross-region access complies with data policies.
-
-### Backups and recovery
-- Automated daily snapshots, plus point-in-time recovery retained per platform policy.
-- Test restores should be performed regularly to validate RPO/RTO.
-
-### Security
-- Access is role-based. `OrdersService` has read/write. Downstream services typically have read-only.
-- Enforce least privilege at the database role level. Avoid ad-hoc superuser connections.
-
-### Operational notes
-- Consider time-based partitioning on `orders.created_at` for very large datasets.
-- Monitor bloat and autovacuum; ensure `vacuum_analyze` runs regularly.
-- Keep indexes targeted; avoid over-indexing write-heavy columns.
-
-### Local development
-- Connection string: provided via `ORDERS_DB_URL` environment variable.
-- Seed data: use project seed scripts to create sample orders and lines.
-
-### Gotchas
-- Deleting an order cascades to `order_lines` due to `ON DELETE CASCADE`. Prefer status changes over deletes in most cases.
-- Monetary math should be done in integer cents to avoid float rounding issues.
-
-If you’re unsure which table to use or how to fetch something, start with the `orders` table by `order_id`, then join `order_lines` as needed. For more, see the `OrdersService` documentation and related domain events.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/containers/orders-db/test-data.sql b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/containers/orders-db/test-data.sql
deleted file mode 100644
index 91d5a5462..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/containers/orders-db/test-data.sql
+++ /dev/null
@@ -1,14 +0,0 @@
--- Insert sample orders
-INSERT INTO orders (order_number, customer_name, customer_email, order_status, product_name, quantity, unit_price, total_amount, payment_method, payment_status, shipping_address) VALUES
-('ORD-2024-001', 'John Doe', 'john.doe@email.com', 'delivered', 'MacBook Pro 14"', 1, 1999.99, 1999.99, 'credit_card', 'completed', '123 Main St, New York, NY 10001'),
-('ORD-2024-002', 'Jane Smith', 'jane.smith@email.com', 'shipped', 'iPhone 15 Pro', 1, 999.99, 999.99, 'paypal', 'completed', '456 Oak Ave, Los Angeles, CA 90210'),
-('ORD-2024-003', 'Michael Johnson', 'michael.johnson@email.com', 'processing', 'AirPods Pro', 2, 249.99, 499.98, 'credit_card', 'completed', '789 Pine Rd, Chicago, IL 60601'),
-('ORD-2024-004', 'Emily Davis', 'emily.davis@email.com', 'pending', 'Cotton T-Shirt', 3, 19.99, 59.97, 'debit_card', 'pending', '321 Elm St, Houston, TX 77001'),
-('ORD-2024-005', 'David Wilson', 'david.wilson@email.com', 'delivered', 'Smart Watch', 1, 299.99, 299.99, 'credit_card', 'completed', '654 Maple Dr, Phoenix, AZ 85001'),
-('ORD-2024-006', 'Sarah Brown', 'sarah.brown@email.com', 'cancelled', 'Travel Backpack', 1, 79.99, 79.99, 'paypal', 'refunded', '987 Cedar Ln, Philadelphia, PA 19101'),
-('ORD-2024-007', 'James Miller', 'james.miller@email.com', 'shipped', 'Premium Coffee Beans', 5, 24.99, 124.95, 'credit_card', 'completed', '147 Birch Way, San Antonio, TX 78201'),
-('ORD-2024-008', 'Lisa Garcia', 'lisa.garcia@email.com', 'delivered', 'Running Sneakers', 1, 89.99, 89.99, 'apple_pay', 'completed', '258 Spruce St, San Diego, CA 92101'),
-('ORD-2024-009', 'Robert Martinez', 'robert.martinez@email.com', 'processing', 'iPad Air', 1, 599.99, 599.99, 'google_pay', 'completed', '369 Willow Ave, Dallas, TX 75201'),
-('ORD-2024-010', 'Jennifer Anderson', 'jennifer.anderson@email.com', 'pending', 'The Great Gatsby', 2, 12.99, 25.98, 'credit_card', 'pending', '741 Poplar Rd, San Jose, CA 95101'),
-('ORD-2024-011', 'Mark Thompson', 'mark.thompson@email.com', 'delivered', 'Wireless Headphones', 1, 149.99, 149.99, 'paypal', 'completed', '852 Oak Street, Seattle, WA 98101'),
-('ORD-2024-012', 'Amanda White', 'amanda.white@email.com', 'shipped', 'Gaming Mouse', 2, 79.99, 159.98, 'credit_card', 'completed', '963 Pine Avenue, Denver, CO 80201');
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderAmended/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderAmended/index.mdx
deleted file mode 100644
index 6fde47bfb..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderAmended/index.mdx
+++ /dev/null
@@ -1,79 +0,0 @@
----
-id: OrderAmended
-name: Order amended
-version: 0.0.1
-summary: |
-  Indicates an order has been changed
-owners:
-  - order-management
-badges:
-  - content: Recently updated!
-    backgroundColor: green
-    textColor: green
-  - content: 'Broker:Apache Kafka'
-    backgroundColor: yellow
-    textColor: yellow
-    icon: kafka
-schemaPath: schema.avro
-draft:
-  title: In draft awaiting feedback
-  message: >
-    ### Use with caution, still in draft
-
-    This event is still in draft. It is not yet ready for production. We are
-    still working on it and collecting feedback from the team.
-
-    If you would like to provide feedback, please contact us at
-    [feedback@eventcatalog.io](mailto:feedback@eventcatalog.io) or our slack
-    channel [Order
-    Management](https://join.slack.com/t/eventcatalog/shared_invite/zt-1q900000000000000000000000000000).
-
-
-    If you are looking for a similar event, you can still use the
-    [OrderConfirmed](/docs/events/OrderConfirmed/0.0.1) event, until it is
-    deprecated.
-
-
-    If you want to use this event in lower environments, you can. We are looking
-    for feedback on the event and how it is used in the team.
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The OrderAmended event is triggered whenever an existing order is modified. This event ensures that all relevant services are notified of changes to an order, such as updates to order items, quantities, shipping information, or status. The event allows the system to maintain consistency and ensure that all dependent services can react appropriately to the amendments.
-
-<NodeGraph />
-
-## Example payload
-
-```json title="Example Payload"
-{
-  "orderId": "123e4567-e89b-12d3-a456-426614174000",
-  "userId": "123e4567-e89b-12d3-a456-426614174000",
-  "amendedItems": [
-    {
-      "productId": "789e1234-b56c-78d9-e012-3456789fghij",
-      "productName": "Example Product",
-      "oldQuantity": 2,
-      "newQuantity": 3,
-      "unitPrice": 29.99,
-      "totalPrice": 89.97
-    }
-  ],
-  "orderStatus": "confirmed",
-  "totalAmount": 150.75,
-  "timestamp": "2024-07-04T14:48:00Z"
-}
-```
-
-## Schema (Avro)s
-
-<SchemaViewer file="schema.avro" />
-
-## Schema (JSON)
-
-<SchemaViewer file="schema.json" />
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderAmended/schema.avro b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderAmended/schema.avro
deleted file mode 100644
index 60827559d..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderAmended/schema.avro
+++ /dev/null
@@ -1,296 +0,0 @@
- {
-    "name": "OrderEvent",
-    "doc": "Complex order event with nested records, unions, and various Avro types",
-    "namespace": "com.example.ecommerce",
-    "type": "record",
-    "fields": [
-      {
-        "name": "orderId",
-        "doc": "Unique order identifier",
-        "type": "string"
-      },
-      {
-        "name": "timestamp",
-        "doc": "When the order was created",
-        "type": {
-          "type": "long",
-          "logicalType": "timestamp-millis"
-        }
-      },
-      {
-        "name": "customer",
-        "doc": "Customer information - nested record",
-        "type": {
-          "type": "record",
-          "name": "Customer",
-          "fields": [
-            {
-              "name": "customerId",
-              "type": "string"
-            },
-            {
-              "name": "email",
-              "type": "string"
-            },
-            {
-              "name": "registrationDate",
-              "type": {
-                "type": "long",
-                "logicalType": "timestamp-millis"
-              }
-            },
-            {
-              "name": "loyaltyTier",
-              "doc": "Customer loyalty status",
-              "type": {
-                "type": "enum",
-                "name": "LoyaltyTier",
-                "symbols": ["BRONZE", "SILVER", "GOLD", "PLATINUM"]
-              }
-            }
-          ]
-        }
-      },
-      {
-        "name": "items",
-        "doc": "Array of order line items",
-        "type": {
-          "type": "array",
-          "items": {
-            "type": "record",
-            "name": "LineItem",
-            "fields": [
-              {
-                "name": "sku",
-                "type": "string"
-              },
-              {
-                "name": "quantity",
-                "type": "int"
-              },
-              {
-                "name": "price",
-                "doc": "Price in cents",
-                "type": {
-                  "type": "long",
-                  "logicalType": "decimal",
-                  "precision": 10,
-                  "scale": 2
-                }
-              },
-              {
-                "name": "discount",
-                "doc": "Optional discount - union with null",
-                "type": ["null", {
-                  "type": "record",
-                  "name": "Discount",
-                  "fields": [
-                    {
-                      "name": "code",
-                      "type": "string"
-                    },
-                    {
-                      "name": "percentage",
-                      "type": "float"
-                    }
-                  ]
-                }],
-                "default": null
-              }
-            ]
-          }
-        }
-      },
-      {
-        "name": "shippingAddress",
-        "doc": "Shipping address - union with multiple record types",
-        "type": [
-          "null",
-          {
-            "type": "record",
-            "name": "USAddress",
-            "fields": [
-              {
-                "name": "street",
-                "type": "string"
-              },
-              {
-                "name": "city",
-                "type": "string"
-              },
-              {
-                "name": "state",
-                "type": "string"
-              },
-              {
-                "name": "zipCode",
-                "type": "string"
-              }
-            ]
-          },
-          {
-            "type": "record",
-            "name": "InternationalAddress",
-            "fields": [
-              {
-                "name": "street",
-                "type": "string"
-              },
-              {
-                "name": "city",
-                "type": "string"
-              },
-              {
-                "name": "country",
-                "type": "string"
-              },
-              {
-                "name": "postalCode",
-                "type": "string"
-              }
-            ]
-          }
-        ],
-        "default": null
-      },
-      {
-        "name": "payment",
-        "doc": "Payment information - union of different payment types",
-        "type": [
-          {
-            "type": "record",
-            "name": "CreditCard",
-            "fields": [
-              {
-                "name": "lastFour",
-                "type": "string"
-              },
-              {
-                "name": "expiration",
-                "type": "string"
-              },
-              {
-                "name": "issuer",
-                "type": {
-                  "type": "enum",
-                  "name": "CardIssuer",
-                  "symbols": ["VISA", "MASTERCARD", "AMEX", "DISCOVER"]
-                }
-              }
-            ]
-          },
-          {
-            "type": "record",
-            "name": "PayPal",
-            "fields": [
-              {
-                "name": "accountEmail",
-                "type": "string"
-              },
-              {
-                "name": "transactionId",
-                "type": "string"
-              }
-            ]
-          },
-          "null"
-        ],
-        "default": null
-      },
-      {
-        "name": "metadata",
-        "doc": "Key-value metadata - map type",
-        "type": {
-          "type": "map",
-          "values": "string"
-        },
-        "default": {}
-      },
-      {
-        "name": "tags",
-        "doc": "Order tags - array of strings",
-        "type": {
-          "type": "array",
-          "items": "string"
-        },
-        "default": []
-      },
-      {
-        "name": "orderStatus",
-        "doc": "Current order status",
-        "type": {
-          "type": "enum",
-          "name": "OrderStatus",
-          "symbols": ["PENDING", "CONFIRMED", "SHIPPED", "DELIVERED", "CANCELLED",
-  "RETURNED"]
-        }
-      },
-      {
-        "name": "notes",
-        "doc": "Optional order notes",
-        "type": ["null", "string"],
-        "default": null
-      },
-      {
-        "name": "trackingInfo",
-        "doc": "Shipping tracking - complex union with nested record",
-        "type": [
-          "null",
-          {
-            "type": "record",
-            "name": "TrackingInfo",
-            "fields": [
-              {
-                "name": "carrier",
-                "type": {
-                  "type": "enum",
-                  "name": "ShippingCarrier",
-                  "symbols": ["FEDEX", "UPS", "USPS", "DHL"]
-                }
-              },
-              {
-                "name": "trackingNumber",
-                "type": "string"
-              },
-              {
-                "name": "estimatedDelivery",
-                "type": {
-                  "type": "long",
-                  "logicalType": "timestamp-millis"
-                }
-              },
-              {
-                "name": "events",
-                "doc": "Tracking events history",
-                "type": {
-                  "type": "array",
-                  "items": {
-                    "type": "record",
-                    "name": "TrackingEvent",
-                    "fields": [
-                      {
-                        "name": "status",
-                        "type": "string"
-                      },
-                      {
-                        "name": "location",
-                        "type": "string"
-                      },
-                      {
-                        "name": "timestamp",
-                        "type": {
-                          "type": "long",
-                          "logicalType": "timestamp-millis"
-                        }
-                      }
-                    ]
-                  }
-                }
-              }
-            ]
-          }
-        ],
-        "default": null
-      }
-    ]
-  }
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderAmended/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderAmended/schema.json
deleted file mode 100644
index 5ddbc679d..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderAmended/schema.json
+++ /dev/null
@@ -1,71 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "title": "OrderAmendedEvent",
-    "type": "object",
-    "properties": {
-      "orderId": {
-        "type": "string",
-        "format": "uuid",
-        "description": "The unique identifier of the order that was amended."
-      },
-      "userId": {
-        "type": "string",
-        "format": "uuid",
-        "description": "The unique identifier of the user who placed the order."
-      },
-      "amendedItems": {
-        "type": "array",
-        "description": "A list of items that were amended in the order, each containing product details and updated quantities.",
-        "items": {
-          "type": "object",
-          "properties": {
-            "productId": {
-              "type": "string",
-              "format": "uuid",
-              "description": "The unique identifier of the product."
-            },
-            "productName": {
-              "type": "string",
-              "description": "The name of the product."
-            },
-            "oldQuantity": {
-              "type": "integer",
-              "description": "The original quantity of the product ordered."
-            },
-            "newQuantity": {
-              "type": "integer",
-              "description": "The new quantity of the product ordered."
-            },
-            "unitPrice": {
-              "type": "number",
-              "format": "float",
-              "description": "The price per unit of the product."
-            },
-            "totalPrice": {
-              "type": "number",
-              "format": "float",
-              "description": "The total price for this order item (newQuantity * unitPrice)."
-            }
-          },
-          "required": ["productId", "productName", "oldQuantity", "newQuantity", "unitPrice", "totalPrice"]
-        }
-      },
-      "orderStatus": {
-        "type": "string",
-        "description": "The current status of the order after the amendment."
-      },
-      "totalAmount": {
-        "type": "number",
-        "format": "float",
-        "description": "The total amount of the order after the amendment."
-      },
-      "timestamp": {
-        "type": "string",
-        "format": "date-time",
-        "description": "The date and time when the order was amended, in ISO 8601 format."
-      }
-    },
-    "required": ["orderId", "userId", "amendedItems", "orderStatus", "totalAmount", "timestamp"],
-    "additionalProperties": false
-  }
-  
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderCancelled/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderCancelled/index.mdx
deleted file mode 100644
index b28c53b1d..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderCancelled/index.mdx
+++ /dev/null
@@ -1,55 +0,0 @@
----
-id: OrderCancelled
-name: Order cancelled
-version: 0.0.1
-summary: |
-  Indicates an order has been canceled
-owners:
-  - order-management
-badges:
-  - content: Recently updated!
-    backgroundColor: green
-    textColor: green
-  - content: 'Broker:Apache Kafka'
-    backgroundColor: yellow
-    textColor: yellow
-    icon: kafka
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The OrderCancelled event is triggered whenever an existing order is cancelled. This event ensures that all relevant services are notified of the cancellation, allowing them to take appropriate actions such as updating inventory levels, refunding payments, and notifying the user. The event helps maintain consistency across the system by ensuring all dependent services are aware of the order cancellation.
-
-## Example payload
-
-```json title="Example payload"
-{
-  "orderId": "123e4567-e89b-12d3-a456-426614174000",
-  "userId": "123e4567-e89b-12d3-a456-426614174000",
-  "orderItems": [
-    {
-      "productId": "789e1234-b56c-78d9-e012-3456789fghij",
-      "productName": "Example Product",
-      "quantity": 2,
-      "unitPrice": 29.99,
-      "totalPrice": 59.98
-    }
-  ],
-  "orderStatus": "cancelled",
-  "totalAmount": 59.98,
-  "cancellationReason": "Customer requested cancellation",
-  "timestamp": "2024-07-04T14:48:00Z"
-}
-
-```
-
-## Schema
-
-JSON schema for the event.
-
-<Schema title="JSON Schema" file="schema.json"/>
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderCancelled/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderCancelled/schema.json
deleted file mode 100644
index 52158ad34..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderCancelled/schema.json
+++ /dev/null
@@ -1,72 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "title": "OrderCancelledEvent",
-    "type": "object",
-    "properties": {
-      "orderId": {
-        "type": "string",
-        "format": "uuid",
-        "description": "The unique identifier of the order that was cancelled."
-      },
-      "userId": {
-        "type": "string",
-        "format": "uuid",
-        "description": "The unique identifier of the user who placed the order."
-      },
-      "orderItems": {
-        "type": "array",
-        "description": "A list of items included in the cancelled order, each containing product details and quantities.",
-        "items": {
-          "type": "object",
-          "properties": {
-            "productId": {
-              "type": "string",
-              "format": "uuid",
-              "description": "The unique identifier of the product."
-            },
-            "productName": {
-              "type": "string",
-              "description": "The name of the product."
-            },
-            "quantity": {
-              "type": "integer",
-              "description": "The quantity of the product ordered."
-            },
-            "unitPrice": {
-              "type": "number",
-              "format": "float",
-              "description": "The price per unit of the product."
-            },
-            "totalPrice": {
-              "type": "number",
-              "format": "float",
-              "description": "The total price for this order item (quantity * unit price)."
-            }
-          },
-          "required": ["productId", "productName", "quantity", "unitPrice", "totalPrice"]
-        }
-      },
-      "orderStatus": {
-        "type": "string",
-        "description": "The current status of the order after cancellation.",
-        "enum": ["cancelled"]
-      },
-      "totalAmount": {
-        "type": "number",
-        "format": "float",
-        "description": "The total amount of the order that was cancelled."
-      },
-      "cancellationReason": {
-        "type": "string",
-        "description": "The reason for the order cancellation, if provided."
-      },
-      "timestamp": {
-        "type": "string",
-        "format": "date-time",
-        "description": "The date and time when the order was cancelled."
-      }
-    },
-    "required": ["orderId", "userId", "orderItems", "orderStatus", "totalAmount", "timestamp"],
-    "additionalProperties": false
-  }
-  
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderConfirmed/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderConfirmed/index.mdx
deleted file mode 100644
index 62ed64f18..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderConfirmed/index.mdx
+++ /dev/null
@@ -1,34 +0,0 @@
----
-id: OrderConfirmed
-name: Order confirmed
-version: 0.0.1
-summary: |
-  Indicates an order has been confirmed
-owners:
-  - order-management
-badges:
-  - content: Recently updated!
-    backgroundColor: green
-    textColor: green
-    icon: StarIcon
-  - content: 'Broker:Apache Kafka'
-    backgroundColor: yellow
-    textColor: yellow
-    icon: kafka
-schemaPath: schema.avro
-draft: true
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The OrderConfirmed event is triggered when an order has been successfully confirmed. This event notifies relevant services that the order is ready for further processing, such as inventory adjustment, payment finalization, and preparation for shipping.
-
-<SchemaViewer file="schema.avro" title="Avro Schema" maxHeight="500" />
-
-## Architecture Diagram
-
-<NodeGraph />
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderConfirmed/schema.avro b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderConfirmed/schema.avro
deleted file mode 100644
index d0d68ef4f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/events/OrderConfirmed/schema.avro
+++ /dev/null
@@ -1,74 +0,0 @@
-{
-  "type": "record",
-  "name": "OrderConfirmedEvent",
-  "namespace": "com.example.events",
-  "doc": "Event emitted when an order has been confirmed.",
-  "fields": [
-    {
-      "name": "orderId",
-      "type": "string",
-      "doc": "The unique identifier of the confirmed order."
-    },
-    {
-      "name": "userId",
-      "type": "string",
-      "doc": "The unique identifier of the user who placed the order."
-    },
-    {
-      "name": "orderItems",
-      "type": {
-        "type": "array",
-        "items": {
-          "type": "record",
-          "name": "OrderItem",
-          "fields": [
-            {
-              "name": "productId",
-              "type": "string",
-              "doc": "The unique identifier of the product."
-            },
-            {
-              "name": "productName",
-              "type": "string",
-              "doc": "The name of the product."
-            },
-            {
-              "name": "quantity",
-              "type": "int",
-              "doc": "The quantity of the product ordered."
-            },
-            {
-              "name": "unitPrice",
-              "type": "double",
-              "doc": "The price per unit of the product."
-            },
-            {
-              "name": "totalPrice",
-              "type": "double",
-              "doc": "The total price for this order item (quantity * unitPrice)."
-            }
-          ]
-        }
-      },
-      "doc": "A list of items included in the confirmed order."
-    },
-    {
-      "name": "orderStatus",
-      "type": "string",
-      "doc": "The current status of the order after confirmation."
-    },
-    {
-      "name": "totalAmount",
-      "type": "double",
-      "doc": "The total amount of the confirmed order."
-    },
-    {
-      "name": "confirmationTimestamp",
-      "type": {
-        "type": "long",
-        "logicalType": "timestamp-millis"
-      },
-      "doc": "The date and time when the order was confirmed."
-    }
-  ]
-}
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/index.mdx
deleted file mode 100644
index 5caf463e2..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/index.mdx
+++ /dev/null
@@ -1,95 +0,0 @@
----
-id: OrdersService
-version: 0.0.3
-name: Orders Service
-summary: |
-  Service that handles orders
-owners:
-  - order-management
-receives:
-  - id: InventoryAdjusted
-    from:
-      - id: orders-service-sqs-channel
-writesTo:
-  - id: orders-db
-    version: 0.0.1
-  - id: order-metadata-store
-    version: 0.0.1
-readsFrom:
-  - id: orders-db
-  - id: inventory-readmodel
-  - id: order-metadata-store
-sends:
-  - id: OrderAmended
-    to:
-      - id: orders-domain-eventbus
-  - id: OrderCancelled
-    to:
-      - id: orders-domain-eventbus
-  - id: OrderConfirmed
-    to:
-      - id: orders-domain-eventbus
-repository:
-  language: JavaScript
-  url: 'https://github.com/event-catalog/pretend-shipping-service'
-schemaPath: openapi-v1.yml
-specifications:
-  - type: asyncapi
-    path: order-service-asyncapi.yaml
-  - type: openapi
-    path: openapi-v1.yml
-    name: v1 API
-  - type: openapi
-    path: openapi-v2.yml
-    name: v2 API
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The Orders Service is responsible for managing customer orders within the system. It handles order creation, updating, status tracking, and interactions with other services such as Inventory, Payment, and Notification services to ensure smooth order processing and fulfillment.
-
-<Tiles >
-    <Tile icon="DocumentIcon" href={`/docs/services/${frontmatter.id}/${frontmatter.version}/changelog`}  title="View the changelog" description="Want to know the history of this service? View the change logs" />
-    <Tile icon="UserGroupIcon" href="/docs/teams/full-stack" title="Contact the team" description="Any questions? Feel free to contact the owners" />
-    <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="This service sends messages to downstream consumers" />
-    <Tile icon="BoltIcon"  href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="This service receives messages from other services" />
-</Tiles>
-
-### Core features
-
-| Feature | Description |
-|---------|-------------|
-| Order Management | Handles order creation, updates, and status tracking |
-| Inventory Integration | Validates and processes inventory for incoming orders |
-| Payment Processing | Integrates with payment gateways to handle payment transactions |
-| Notification Integration | Sends notifications to users and other services |
-
-## Architecture diagram 
-
-<NodeGraph />
-
-<MessageTable format="all" limit={4} />
-
-## Infrastructure
-
-The Orders Service is hosted on AWS.
-
-The diagram below shows the infrastructure of the Orders Service. The service is hosted on AWS and uses AWS Lambda to handle the order requests. The order is stored in an AWS Aurora database and the order metadata is stored in an AWS S3 bucket.
-
-```mermaid
-architecture-beta
-    group api(logos:aws)
-
-    service db(logos:aws-aurora)[Order DB] in api
-    service disk1(logos:aws-s3)[Order Metadata] in api
-    service server(logos:aws-lambda)[Order Handler] in api
-
-    db:L -- R:server
-    disk1:T -- B:server
-```
-
-You can find more information about the Orders Service infrastructure in the [Orders Service documentation](https://github.com/event-catalog/pretend-shipping-service/blob/main/README.md).
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/openapi-v1.yml b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/openapi-v1.yml
deleted file mode 100644
index cee9b9c1a..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/openapi-v1.yml
+++ /dev/null
@@ -1,290 +0,0 @@
-openapi: 3.0.3
-info:
-  title: Orders Service API
-  description: API for managing customer orders
-  version: 1.0.0
-
-servers:
-  - url: https://api.example.com/v1
-    description: Production server
-  - url: https://staging-api.example.com/v1
-    description: Staging server
-
-paths:
-  /orders:
-    get:
-      summary: List all orders
-      description: Retrieve a list of orders with optional filtering
-      parameters:
-        - name: status
-          in: query
-          description: Filter orders by status
-          schema:
-            type: string
-            enum: [pending, processing, completed, cancelled]
-        - name: customerId
-          in: query
-          description: Filter orders by customer ID
-          schema:
-            type: string
-        - name: page
-          in: query
-          description: Page number for pagination
-          schema:
-            type: integer
-            minimum: 1
-            default: 1
-        - name: limit
-          in: query
-          description: Number of items per page
-          schema:
-            type: integer
-            minimum: 1
-            maximum: 100
-            default: 20
-      responses:
-        '200':
-          description: Successfully retrieved orders
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/OrderList'
-        '400':
-          $ref: '#/components/responses/BadRequest'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-
-    post:
-      summary: Create a new order
-      description: Create a new order for a customer
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/OrderCreate'
-      responses:
-        '201':
-          description: Order created successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Order'
-        '400':
-          $ref: '#/components/responses/BadRequest'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-
-  /orders/{orderId}:
-    get:
-      summary: Get order by ID
-      description: Retrieve detailed information about a specific order
-      parameters:
-        - name: orderId
-          in: path
-          required: true
-          description: Unique identifier of the order
-          schema:
-            type: string
-      responses:
-        '200':
-          description: Order found
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Order'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-
-    patch:
-      summary: Update order status
-      description: Update the status of an existing order
-      parameters:
-        - name: orderId
-          in: path
-          required: true
-          description: Unique identifier of the order
-          schema:
-            type: string
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/OrderUpdate'
-      responses:
-        '200':
-          description: Order updated successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Order'
-        '400':
-          $ref: '#/components/responses/BadRequest'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-
-components:
-  schemas:
-    OrderCreate:
-      type: object
-      required:
-        - customerId
-        - items
-      properties:
-        customerId:
-          type: string
-          description: Unique identifier of the customer
-        items:
-          type: array
-          items:
-            $ref: '#/components/schemas/OrderItem'
-        shippingAddress:
-          $ref: '#/components/schemas/Address'
-        billingAddress:
-          $ref: '#/components/schemas/Address'
-
-    OrderUpdate:
-      type: object
-      required:
-        - status
-      properties:
-        status:
-          type: string
-          enum: [pending, processing, completed, cancelled]
-          description: New status of the order
-
-    Order:
-      type: object
-      properties:
-        id:
-          type: string
-          description: Unique identifier of the order
-        customerId:
-          type: string
-          description: Unique identifier of the customer
-        status:
-          type: string
-          enum: [pending, processing, completed, cancelled]
-        items:
-          type: array
-          items:
-            $ref: '#/components/schemas/OrderItem'
-        totalAmount:
-          type: number
-          format: float
-        shippingAddress:
-          $ref: '#/components/schemas/Address'
-        billingAddress:
-          $ref: '#/components/schemas/Address'
-        createdAt:
-          type: string
-          format: date-time
-        updatedAt:
-          type: string
-          format: date-time
-
-    OrderList:
-      type: object
-      properties:
-        items:
-          type: array
-          items:
-            $ref: '#/components/schemas/Order'
-        pagination:
-          $ref: '#/components/schemas/Pagination'
-
-    OrderItem:
-      type: object
-      required:
-        - productId
-        - quantity
-      properties:
-        productId:
-          type: string
-        quantity:
-          type: integer
-          minimum: 1
-        price:
-          type: number
-          format: float
-        name:
-          type: string
-
-    Address:
-      type: object
-      required:
-        - street
-        - city
-        - country
-        - postalCode
-      properties:
-        street:
-          type: string
-        city:
-          type: string
-        state:
-          type: string
-        country:
-          type: string
-        postalCode:
-          type: string
-
-    Pagination:
-      type: object
-      properties:
-        totalItems:
-          type: integer
-        totalPages:
-          type: integer
-        currentPage:
-          type: integer
-        itemsPerPage:
-          type: integer
-
-    Error:
-      type: object
-      properties:
-        code:
-          type: string
-        message:
-          type: string
-        details:
-          type: array
-          items:
-            type: string
-
-  responses:
-    BadRequest:
-      description: Invalid request
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/Error'
-
-    Unauthorized:
-      description: Authentication required
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/Error'
-
-    NotFound:
-      description: Resource not found
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/Error'
-
-  securitySchemes:
-    BearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
-
-security:
-  - BearerAuth: []
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/openapi-v2.yml b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/openapi-v2.yml
deleted file mode 100644
index 0abbeac83..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/openapi-v2.yml
+++ /dev/null
@@ -1,248 +0,0 @@
-openapi: 3.0.3
-info:
-  title: Orders Service API
-  description: API for managing customer orders
-  version: 2.0.0
-
-servers:
-  - url: https://api.example.com/v1
-    description: Production server
-  - url: https://staging-api.example.com/v1
-    description: Staging server
-
-paths:
-  /orders:
-    post:
-      summary: Create a new order
-      description: Create a new order for a customer
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/OrderCreate'
-      responses:
-        '201':
-          description: Order created successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Order'
-        '400':
-          $ref: '#/components/responses/BadRequest'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-
-  /orders/{orderId}:
-    get:
-      summary: Get order by ID
-      description: Retrieve detailed information about a specific order
-      parameters:
-        - name: orderId
-          in: path
-          required: true
-          description: Unique identifier of the order
-          schema:
-            type: string
-      responses:
-        '200':
-          description: Order found
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Order'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-
-    patch:
-      summary: Update order status
-      description: Update the status of an existing order
-      parameters:
-        - name: orderId
-          in: path
-          required: true
-          description: Unique identifier of the order
-          schema:
-            type: string
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/OrderUpdate'
-      responses:
-        '200':
-          description: Order updated successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Order'
-        '400':
-          $ref: '#/components/responses/BadRequest'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-
-components:
-  schemas:
-    OrderCreate:
-      type: object
-      required:
-        - customerId
-        - items
-      properties:
-        customerId:
-          type: string
-          description: Unique identifier of the customer
-        items:
-          type: array
-          items:
-            $ref: '#/components/schemas/OrderItem'
-        shippingAddress:
-          $ref: '#/components/schemas/Address'
-        billingAddress:
-          $ref: '#/components/schemas/Address'
-
-    OrderUpdate:
-      type: object
-      required:
-        - status
-      properties:
-        status:
-          type: string
-          enum: [pending, processing, completed, cancelled]
-          description: New status of the order
-
-    Order:
-      type: object
-      properties:
-        id:
-          type: string
-          description: Unique identifier of the order
-        customerId:
-          type: string
-          description: Unique identifier of the customer
-        status:
-          type: string
-          enum: [pending, processing, completed, cancelled]
-        items:
-          type: array
-          items:
-            $ref: '#/components/schemas/OrderItem'
-        totalAmount:
-          type: number
-          format: float
-        shippingAddress:
-          $ref: '#/components/schemas/Address'
-        billingAddress:
-          $ref: '#/components/schemas/Address'
-        createdAt:
-          type: string
-          format: date-time
-        updatedAt:
-          type: string
-          format: date-time
-
-    OrderList:
-      type: object
-      properties:
-        items:
-          type: array
-          items:
-            $ref: '#/components/schemas/Order'
-        pagination:
-          $ref: '#/components/schemas/Pagination'
-
-    OrderItem:
-      type: object
-      required:
-        - productId
-        - quantity
-      properties:
-        productId:
-          type: string
-        quantity:
-          type: integer
-          minimum: 1
-        price:
-          type: number
-          format: float
-        name:
-          type: string
-
-    Address:
-      type: object
-      required:
-        - street
-        - city
-        - country
-        - postalCode
-      properties:
-        street:
-          type: string
-        city:
-          type: string
-        state:
-          type: string
-        country:
-          type: string
-        postalCode:
-          type: string
-
-    Pagination:
-      type: object
-      properties:
-        totalItems:
-          type: integer
-        totalPages:
-          type: integer
-        currentPage:
-          type: integer
-        itemsPerPage:
-          type: integer
-
-    Error:
-      type: object
-      properties:
-        code:
-          type: string
-        message:
-          type: string
-        details:
-          type: array
-          items:
-            type: string
-
-  responses:
-    BadRequest:
-      description: Invalid request
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/Error'
-
-    Unauthorized:
-      description: Authentication required
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/Error'
-
-    NotFound:
-      description: Resource not found
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/Error'
-
-  securitySchemes:
-    BearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
-
-security:
-  - BearerAuth: []
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/order-service-asyncapi.yaml b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/order-service-asyncapi.yaml
deleted file mode 100644
index 180ee9a75..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/order-service-asyncapi.yaml
+++ /dev/null
@@ -1,148 +0,0 @@
-asyncapi: 3.0.0
-
-info:
-  title: Order service
-  description: | 
-    This service is in charge of processing order events.
-  version: '2.0.0'
-
-servers: 
-  topic:
-    host: https://mytopic.com
-    description: Custom Topic.
-    protocol: HTTPS
-
-defaultContentType: application/json
-
-channels:
-  orderEventsChannel:
-    address: 'orders.{orderId}'
-    description: All Order related events are distributed and broadcasted for the interested consumers.
-    title: Order events channel
-    messages:
-      OrderConfirmed:
-        summary: Order confirmed event
-        $ref: '#/components/messages/OrderConfirmed'
-      OrderPlaced:
-        summary: Order placed event
-        $ref: '#/components/messages/OrderPlaced'
-
-operations: 
-  onOrderConfirmation:
-    summary: Action to confirm an order.
-    description: The product availability of an order will lead to the confirmation of the order.
-    title: Order Confirmed
-    channel:
-      $ref: '#/channels/orderEventsChannel'
-    action: send
-  onOrderPlacement:
-    summary: Action to place an order.
-    description: The reception and validation of an order will lead to the placement of the order.
-    title: Order Placed
-    channel:
-      $ref: '#/channels/orderEventsChannel'
-    action: send
-
-components:
-  messages:
-    OrderConfirmed:
-      payload:
-        $ref: '#/components/schemas/OrderConfirmed'
-
-    OrderPlaced:
-      payload:
-        $ref: '#/components/schemas/OrderPlaced'
-
-  schemas:
-    orderId:
-      description: The unique identifier of an order
-      type: string
-      pattern: ^([A-Za-z0-9_-]{21})$
-
-    userId:
-      description: The unique identifier of a user
-      type: string
-      pattern: ^([A-Za-z0-9_-]{21})$
-
-    productId:
-      description: The product unique identifier
-      type: string
-      pattern: ^([A-Za-z0-9_-]{21})$
-
-    Order:
-      required:
-        - orderId
-        - userId
-        - productId
-        - price
-        - quantity
-        - orderDate
-      type: object
-      description: order model
-      properties:
-        orderId:
-          "$ref": "#/components/schemas/orderId"
-        orderDate:
-          description: Date of order submition.
-          type: string
-          format: date-time
-        userId:
-          "$ref": "#/components/schemas/userId"
-        productId:
-          "$ref": "#/components/schemas/productId"
-        price:
-          type: number
-        quantity:
-          type: integer
-      title: Order
-
-    EventEnvelope:
-      type: object
-      allOf:
-      - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/v1.0.1/spec.json'
-      properties:
-        id:
-          type: string
-          format: uuid
-        idempotencykey:
-          type: string
-          format: uuid
-        correlationid:
-          type: string
-          format: uuid
-        causationid:
-          type: string
-          format: uuid
-
-    EventType:
-      type: string
-      enum: 
-        - "order.placed" 
-        - "order.confirmed"
-
-    OrderConfirmed:
-      type: object
-      additionalProperties: false
-      allOf:
-        - $ref: '#/components/schemas/EventEnvelope'  
-      properties:
-        data:
-          $ref: '#/components/schemas/Order'
-        type:
-          $ref: '#/components/schemas/EventType'
-
-      required:
-        - data
-
-    OrderPlaced:
-      type: object
-      additionalProperties: false
-      allOf:
-        - $ref: '#/components/schemas/EventEnvelope'
-      properties:
-        data:
-          $ref: '#/components/schemas/Order'
-        type:
-          $ref: '#/components/schemas/EventType'
-      required:
-        - data
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/queries/GetOrder/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/queries/GetOrder/index.mdx
deleted file mode 100644
index ea665e62c..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/queries/GetOrder/index.mdx
+++ /dev/null
@@ -1,28 +0,0 @@
----
-id: GetOrder
-name: Get order details
-version: 0.0.1
-summary: |
-  GET request that will return detailed information about a specific order, identified by its orderId.
-owners:
-    - order-management
-badges:
-    - content: Recently updated!
-      backgroundColor: green
-      textColor: green
-schemaPath: schema.json
-sidebar:
-  badge: 'GET'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `GetOrder` message is a query used to retrieve detailed information about a specific order, identified by its `orderId`. It provides information such as the order status (e.g., pending, completed, shipped), the items within the order, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This query can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time order data for tracking, auditing, or managing customer purchases.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/queries/GetOrder/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/queries/GetOrder/schema.json
deleted file mode 100644
index e7336cd96..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/queries/GetOrder/schema.json
+++ /dev/null
@@ -1,15 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "title": "GetOrderQuery",
-    "type": "object",
-    "properties": {
-      "orderId": {
-        "type": "string",
-        "format": "uuid",
-        "description": "The unique identifier of the order being retrieved."
-      }
-    },
-    "required": ["orderId"],
-    "additionalProperties": false
-  }
-  
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/versioned/0.0.2/changelog.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/versioned/0.0.2/changelog.mdx
deleted file mode 100644
index 28c6a1f55..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/versioned/0.0.2/changelog.mdx
+++ /dev/null
@@ -1,5 +0,0 @@
----
-createdAt: 2024-08-01
----
-
-Something changed
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/versioned/0.0.2/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/versioned/0.0.2/index.mdx
deleted file mode 100644
index c9a61bf9f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/versioned/0.0.2/index.mdx
+++ /dev/null
@@ -1,31 +0,0 @@
----
-id: OrdersService
-version: 0.0.2
-name: Orders Service
-summary: |
-  Service that handles orders
-owners:
-  - dboyne
-sends:
-  - id: AddInventory
-    version: 0.0.3
-repository:
-  language: JavaScript
-  url: 'https://github.com/event-catalog/pretend-shipping-service'
-schemaPath: openapi.yml
-specifications:
-  asyncapiPath: order-service-asyncapi.yaml
-  openapiPath: openapi.yml
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The Orders Service is responsible for managing customer orders within the system. It handles order creation, updating, status tracking, and interactions with other services such as Inventory, Payment, and Notification services to ensure smooth order processing and fulfillment.
-
-## Architecture diagram 
-
-<NodeGraph />
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/versioned/0.0.2/openapi.yml b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/versioned/0.0.2/openapi.yml
deleted file mode 100644
index 4aca8898f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/versioned/0.0.2/openapi.yml
+++ /dev/null
@@ -1,96 +0,0 @@
-openapi: 3.1.0
-info:
-  title: Simple Task - API
-  version: 1.0.0
-  description: Simple Api
-  contact: {}
-  license:
-    name: apache 2.0
-    identifier: apache-2.0
-    url: https://www.apache.org/licenses/LICENSE-2.0.html
-
-servers:
-  - url: https://example.com/
-    
-paths:
-  /v1/task/{id}:
-    put:
-      summary: Do Simple Task
-      operationId: DoSimpleTask
-      responses:
-        '200':
-          description: do a task by id
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Task'
-        '204':
-          description: No content
-        '400':
-          description: Problem with data
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-        '403':
-          description: Not Authorized
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Unauthorized'
-        '404':
-          description: not found
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-        '500':
-          description: Internal server error
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-      description: Allows to do a simple task
-      security:
-        - authorization: []
-      parameters:
-        - in: path
-          name: id
-          required: true
-          schema:
-            type: string
-
-components:
-  schemas:
-    Task:
-      properties:
-        comments:
-          type: string
-        creationDate:
-          type: string
-        taskId:
-          type: string
-        description:
-          type: string
-        lastUpdate:
-          type: string
-      type: object
-      additionalProperties: false
-    Error:
-      properties:
-        error:
-          type: string
-      required:
-        - error
-      type: object
-    Unauthorized:
-      properties:
-        message:
-          type: string
-      required:
-        - message
-      type: object
-  securitySchemes:
-    authorization:
-      type: http
-      scheme: bearer
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/versioned/0.0.2/order-service-asyncapi.yaml b/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/versioned/0.0.2/order-service-asyncapi.yaml
deleted file mode 100644
index e561ec461..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/versioned/0.0.2/order-service-asyncapi.yaml
+++ /dev/null
@@ -1,148 +0,0 @@
-asyncapi: 3.0.0
-
-info:
-  title: Order service
-  description: | 
-    This service is in charge of processing order events.
-  version: '1.0.0'
-
-servers: 
-  topic:
-    host: https://mytopic.com
-    description: Custom Topic.
-    protocol: HTTPS
-
-defaultContentType: application/json
-
-channels:
-  orderEventsChannel:
-    address: 'orders.{orderId}'
-    description: All Order related events are distributed and broadcasted for the interested consumers.
-    title: Order events channel
-    messages:
-      OrderConfirmed:
-        summary: Order confirmed event
-        $ref: '#/components/messages/OrderConfirmed'
-      OrderPlaced:
-        summary: Order placed event
-        $ref: '#/components/messages/OrderPlaced'
-
-operations: 
-  onOrderConfirmation:
-    summary: Action to confirm an order.
-    description: The product availability of an order will lead to the confirmation of the order.
-    title: Order Confirmed
-    channel:
-      $ref: '#/channels/orderEventsChannel'
-    action: send
-  onOrderPlacement:
-    summary: Action to place an order.
-    description: The reception and validation of an order will lead to the placement of the order.
-    title: Order Placed
-    channel:
-      $ref: '#/channels/orderEventsChannel'
-    action: send
-
-components:
-  messages:
-    OrderConfirmed:
-      payload:
-        $ref: '#/components/schemas/OrderConfirmed'
-
-    OrderPlaced:
-      payload:
-        $ref: '#/components/schemas/OrderPlaced'
-
-  schemas:
-    orderId:
-      description: The unique identifier of an order
-      type: string
-      pattern: ^([A-Za-z0-9_-]{21})$
-
-    userId:
-      description: The unique identifier of a user
-      type: string
-      pattern: ^([A-Za-z0-9_-]{21})$
-
-    productId:
-      description: The product unique identifier
-      type: string
-      pattern: ^([A-Za-z0-9_-]{21})$
-
-    Order:
-      required:
-        - orderId
-        - userId
-        - productId
-        - price
-        - quantity
-        - orderDate
-      type: object
-      description: order model
-      properties:
-        orderId:
-          "$ref": "#/components/schemas/orderId"
-        orderDate:
-          description: Date of order submition.
-          type: string
-          format: date-time
-        userId:
-          "$ref": "#/components/schemas/userId"
-        productId:
-          "$ref": "#/components/schemas/productId"
-        price:
-          type: number
-        quantity:
-          type: integer
-      title: Order
-
-    EventEnvelope:
-      type: object
-      allOf:
-      - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/v1.0.1/spec.json'
-      properties:
-        id:
-          type: string
-          format: uuid
-        idempotencykey:
-          type: string
-          format: uuid
-        correlationid:
-          type: string
-          format: uuid
-        causationid:
-          type: string
-          format: uuid
-
-    EventType:
-      type: string
-      enum: 
-        - "order.placed" 
-        - "order.confirmed"
-
-    OrderConfirmed:
-      type: object
-      additionalProperties: false
-      allOf:
-        - $ref: '#/components/schemas/EventEnvelope'  
-      properties:
-        data:
-          $ref: '#/components/schemas/Order'
-        type:
-          $ref: '#/components/schemas/EventType'
-
-      required:
-        - data
-
-    OrderPlaced:
-      type: object
-      additionalProperties: false
-      allOf:
-        - $ref: '#/components/schemas/EventEnvelope'
-      properties:
-        data:
-          $ref: '#/components/schemas/Order'
-        type:
-          $ref: '#/components/schemas/EventType'
-      required:
-        - data
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/RegistrationService/events/UserForgotPassword/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/RegistrationService/events/UserForgotPassword/index.mdx
deleted file mode 100644
index 22d3b8fbf..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/RegistrationService/events/UserForgotPassword/index.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
----
-id: UserForgotPasswordEvent
-version: 0.0.1
-name: User Forgot Password
-summary: |
-  Event that is sent when a user forgets their password
-owners:
-    - dboyne
----
-
-This is a user forgot password event that is sent when a user forgets their password. 
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/RegistrationService/events/UserSignedUpEvent/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/RegistrationService/events/UserSignedUpEvent/index.mdx
deleted file mode 100644
index 3f00f001a..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/RegistrationService/events/UserSignedUpEvent/index.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
----
-id: UserSignedUpEvent
-version: 0.0.1
-name: User Signed Up
-summary: |
-  Event that is sent when a user is signed up
-owners:
-    - dboyne
----
-
-This is a user signed up event that is sent when a user is signed up.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/RegistrationService/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/RegistrationService/index.mdx
deleted file mode 100644
index 2924cd14d..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/RegistrationService/index.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-id: RegistrationService
-version: 0.0.1
-name: Registration Service
-summary: |
-  Service that handles registration operations
-owners:
-    - dboyne
-sends:
-  - id: UserSignedUpEvent
-    to:
-      - id: registrations-domain-eventbus
-  - id: UserForgotPasswordEvent
-    to:
-      - id: registrations-domain-eventbus
-receives:
-  - id: DeliveryFailed
-    from:
-      - id: registrations-domain-eventbus
----
-
-This is a registration service that sends a registration event.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CancelShipment/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CancelShipment/index.mdx
deleted file mode 100644
index 15d952bae..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CancelShipment/index.mdx
+++ /dev/null
@@ -1,25 +0,0 @@
----
-id: CancelShipment
-name: Cancel shipment
-version: 0.0.1
-summary: |
-  POST request that will cancel a shipment, identified by its shipmentId.
-owners:
-    - dboyne
-schemaPath: schema.json
-sidebar:
-  badge: 'POST'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `CancelShipment` message is a command used to cancel a shipment, identified by its `shipmentId`. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This command can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
-
-<SchemaViewer file="schema.json" title="Schema" maxHeight="500" />
-
-<NodeGraph />
-
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CancelShipment/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CancelShipment/schema.json
deleted file mode 100644
index d6d6d2745..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CancelShipment/schema.json
+++ /dev/null
@@ -1,13 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "type": "object",
-    "title": "CancelShipment",
-    "description": "Schema for cancelling a shipment",
-    "properties": {
-        "shipmentId": {
-            "type": "string",
-            "description": "Unique identifier for the shipment"
-        }
-    },
-    "required": ["shipmentId"]
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CreateReturnLabel/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CreateReturnLabel/index.mdx
deleted file mode 100644
index 6c2a91cae..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CreateReturnLabel/index.mdx
+++ /dev/null
@@ -1,24 +0,0 @@
----
-id: CreateReturnLabel
-name: Create return label
-version: 0.0.1
-summary: |
-  POST request that will create a return label for a specific shipment, identified by its shipmentId.
-owners:
-    - dboyne
-schemaPath: schema.json
-sidebar:
-  badge: 'POST'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `CreateReturnLabel` message is a command used to create a return label for a specific shipment, identified by its `shipmentId`. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This command can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CreateReturnLabel/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CreateReturnLabel/schema.json
deleted file mode 100644
index 933b175e6..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CreateReturnLabel/schema.json
+++ /dev/null
@@ -1,19 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "type": "object",
-    "title": "CreateReturnLabel",
-    "description": "Schema for creating a return shipping label",
-    "properties": {
-        "CreateReturnLabel": {
-            "type": "object",
-            "properties": {
-                "shipmentId": {
-                    "type": "string",
-                    "description": "Unique identifier for the shipment"
-                }
-            },
-            "required": ["shipmentId"]
-        }
-    },
-    "required": ["CreateReturnLabel"]
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CreateShipment/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CreateShipment/index.mdx
deleted file mode 100644
index 6bdacee49..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CreateShipment/index.mdx
+++ /dev/null
@@ -1,24 +0,0 @@
----
-id: CreateShipment
-name: Create shipment
-version: 0.0.1
-summary: |
-  POST request that will create a shipment for a specific order, identified by its orderId.
-owners:
-    - dboyne
-schemaPath: schema.json
-sidebar:
-  badge: 'POST'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `CreateShipment` message is a command used to create a shipment for a specific order, identified by its `orderId`. It provides information such as the order status (e.g., pending, completed, shipped), the items within the order, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This command can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time order data for tracking, auditing, or managing customer purchases.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/UpdateShipmentStatus/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/UpdateShipmentStatus/index.mdx
deleted file mode 100644
index b1764a31f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/UpdateShipmentStatus/index.mdx
+++ /dev/null
@@ -1,24 +0,0 @@
----
-id: UpdateShipmentStatus
-name: Update shipment status
-version: 0.0.1
-summary: |
-  POST request that will update the status of a shipment, identified by its shipmentId.
-owners:
-    - dboyne
-schemaPath: schema.json
-sidebar:
-  badge: 'POST'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `UpdateShipmentStatus` message is a command used to update the status of a shipment, identified by its `shipmentId`. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This command can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/UpdateShipmentStatus/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/UpdateShipmentStatus/schema.json
deleted file mode 100644
index f95a1b0cd..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/UpdateShipmentStatus/schema.json
+++ /dev/null
@@ -1,29 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "type": "object",
-    "title": "UpdateShipmentStatus",
-    "description": "Schema for updating a shipment's status",
-    "properties": {
-        "UpdateShipmentStatus": {
-            "type": "object",
-            "properties": {
-                "shipmentId": {
-                    "type": "string",
-                    "description": "Unique identifier for the shipment"
-                },
-                "status": {
-                    "type": "string",
-                    "enum": ["pending", "shipped", "delivered", "returned"],
-                    "description": "Current status of the shipment"
-                },
-                "updatedAt": {
-                    "type": "string",
-                    "format": "date-time",
-                    "description": "Timestamp when the status was last updated"
-                }
-            },
-            "required": ["shipmentId", "status"]
-        }
-    },
-    "required": ["UpdateShipmentStatus"]
-}
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/index.mdx
deleted file mode 100644
index 998242391..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/index.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-id: DeliveryFailed
-name: Delivery failed
-version: 1.0.0
-summary: |
-  Event that is emitted when a shipment delivery fails.
-owners:
-    - dboyne
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `DeliveryFailed` event is emitted when a shipment delivery fails. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/schema.json
deleted file mode 100644
index d8998d9ce..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/schema.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "type": "object",
-    "title": "DeliveryFailed",
-    "description": "Schema for delivery failed event",
-    "properties": {
-        "shipmentId": {
-            "type": "number",
-            "description": "Unique identifier for the shipment"
-        },
-        "orderId": {
-            "type": "string",
-            "description": "Identifier for the associated order"
-        },
-        "failureReason": {
-            "type": "string",
-            "description": "Reason for the delivery failure"
-        }
-    },
-    "required": ["shipmentId", "orderId", "failureReason"]
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/versioned/0.0.1/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/versioned/0.0.1/index.mdx
deleted file mode 100644
index 3c1c81f92..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/versioned/0.0.1/index.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-id: DeliveryFailed
-name: Delivery failed
-version: 0.0.1
-summary: |
-  Event that is emitted when a shipment delivery fails.
-owners:
-    - dboyne
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `DeliveryFailed` event is emitted when a shipment delivery fails. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/versioned/0.0.1/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/versioned/0.0.1/schema.json
deleted file mode 100644
index 81fc9a244..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/versioned/0.0.1/schema.json
+++ /dev/null
@@ -1,13 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "type": "object",
-    "title": "DeliveryFailed",
-    "description": "Schema for delivery failed event",
-    "properties": {
-        "shipmentId": {
-            "type": "string",
-            "description": "Unique identifier for the shipment"
-        }
-    },
-    "required": ["shipmentId", "orderId"]
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/versioned/0.0.2/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/versioned/0.0.2/index.mdx
deleted file mode 100644
index 768e8a3f9..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/versioned/0.0.2/index.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-id: DeliveryFailed
-name: Delivery failed
-version: 0.0.2
-summary: |
-  Event that is emitted when a shipment delivery fails.
-owners:
-    - dboyne
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `DeliveryFailed` event is emitted when a shipment delivery fails. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/versioned/0.0.2/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/versioned/0.0.2/schema.json
deleted file mode 100644
index 92371d9e2..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/DeliveryFailed/versioned/0.0.2/schema.json
+++ /dev/null
@@ -1,13 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "type": "object",
-    "title": "DeliveryFailed",
-    "description": "Schema for delivery failed event",
-    "properties": {
-        "shipmentId": {
-            "type": "number",
-            "description": "Unique identifier for the shipment"
-        }
-    },
-    "required": ["shipmentId", "orderId"]
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ReturnInitiated/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ReturnInitiated/index.mdx
deleted file mode 100644
index cb7b5ecce..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ReturnInitiated/index.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-id: ReturnInitiated
-name: Return initiated
-version: 0.0.1
-summary: |
-  Event that is emitted when a return is initiated.
-owners:
-    - dboyne
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `ReturnInitiated` event is emitted when a return is initiated. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time return data for tracking, auditing, or managing customer purchases.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ReturnInitiated/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ReturnInitiated/schema.json
deleted file mode 100644
index 6382f8279..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ReturnInitiated/schema.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "type": "object",
-    "title": "ReturnInitiated",
-    "description": "Schema for return initiated event",
-    "properties": {
-        "shipmentId": {
-            "type": "string",
-            "description": "Unique identifier for the shipment"
-        },
-        "orderId": {
-            "type": "string",
-            "description": "Identifier for the associated order"
-        }
-    },
-    "required": ["shipmentId", "orderId"]
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentCreated/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentCreated/index.mdx
deleted file mode 100644
index ba7e68a53..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentCreated/index.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-id: ShipmentCreated
-name: Shipment created
-version: 0.0.1
-summary: |
-  Event that is emitted when a shipment is created.
-owners:
-    - dboyne
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `ShipmentCreated` event is emitted when a shipment is created. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentCreated/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentCreated/schema.json
deleted file mode 100644
index a42f2b617..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentCreated/schema.json
+++ /dev/null
@@ -1,65 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "title": "ShipmentCreated",
-  "description": "Schema for shipment created event",
-  "properties": {
-    "shipmentId": {
-      "type": "string",
-      "description": "Unique identifier for the shipment"
-    },
-    "orderId": {
-      "type": "string",
-      "description": "Identifier for the associated order"
-    },
-    "address": {
-      "type": "object",
-      "properties": {
-        "street": {
-          "type": "string",
-          "description": "Street address for the shipment"
-        },
-        "city": {
-          "type": "string",
-          "description": "City for the shipment"
-        },
-        "state": {
-          "type": "string",
-          "description": "State for the shipment"
-        },
-        "postalCode": {
-          "type": "string",
-          "description": "Postal code for the shipment"
-        },
-        "country": {
-          "type": "string",
-          "description": "Country for the shipment"
-        }
-      },
-      "required": ["street", "city", "state", "postalCode", "country"]
-    },
-    "items": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "properties": {
-          "itemId": {
-            "type": "string",
-            "description": "Identifier for the item"
-          },
-          "quantity": {
-            "type": "integer",
-            "description": "Quantity of the item"
-          }
-        },
-        "required": ["itemId", "quantity"]
-      }
-    },
-    "shippingMethod": {
-      "type": "string",
-      "description": "Method of shipping (e.g., standard, express)"
-    }
-  },
-  "required": ["shipmentId", "orderId", "address", "items", "shippingMethod"]
-}
-
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentDelivered/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentDelivered/index.mdx
deleted file mode 100644
index 511af6793..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentDelivered/index.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-id: ShipmentDelivered
-name: Shipment delivered
-version: 0.0.1
-summary: |
-  Event that is emitted when a shipment is delivered.
-owners:
-    - dboyne
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `ShipmentDelivered` event is emitted when a shipment is delivered. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentDelivered/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentDelivered/schema.json
deleted file mode 100644
index e0fe1211c..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentDelivered/schema.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "type": "object",
-    "title": "ShipmentDelivered",
-    "description": "Schema for shipment delivered event",
-    "properties": {
-        "shipmentId": {
-            "type": "string",
-            "description": "Unique identifier for the shipment"
-        },
-        "orderId": {
-            "type": "string",
-            "description": "Identifier for the associated order"
-        }
-    },
-    "required": ["shipmentId", "orderId"]
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentDispatched/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentDispatched/index.mdx
deleted file mode 100644
index fad0802d8..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentDispatched/index.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-id: ShipmentDispatched
-name: Shipment dispatched
-version: 0.0.1
-summary: |
-  Event that is emitted when a shipment is dispatched.
-owners:
-    - dboyne
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `ShipmentDispatched` event is emitted when a shipment is dispatched. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentDispatched/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentDispatched/schema.json
deleted file mode 100644
index 31f82e379..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentDispatched/schema.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "type": "object",
-    "title": "ShipmentDispatched",
-    "description": "Schema for shipment dispatched event",
-    "properties": {
-        "shipmentId": {
-            "type": "string",
-            "description": "Unique identifier for the shipment"
-        },
-        "orderId": {
-            "type": "string",
-            "description": "Identifier for the associated order"
-        }
-    },
-    "required": ["shipmentId", "orderId"]
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentInTransit/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentInTransit/index.mdx
deleted file mode 100644
index 73c8a58a5..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentInTransit/index.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-id: ShipmentInTransit
-name: Shipment in transit
-version: 0.0.1
-summary: |
-  Event that is emitted when a shipment is in transit.
-owners:
-    - dboyne
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `ShipmentInTransit` event is emitted when a shipment is in transit. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
-
-This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentInTransit/schema.json b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentInTransit/schema.json
deleted file mode 100644
index 59a728888..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/events/ShipmentInTransit/schema.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "type": "object",
-    "title": "ShipmentInTransit",
-    "description": "Schema for shipment in transit event",
-    "properties": {
-        "shipmentId": {
-            "type": "string",
-            "description": "Unique identifier for the shipment"
-        },
-        "orderId": {
-            "type": "string",
-            "description": "Identifier for the associated order"
-        }
-    },
-    "required": ["shipmentId", "orderId"]
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/index.mdx
deleted file mode 100644
index 8c78b44e6..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/index.mdx
+++ /dev/null
@@ -1,59 +0,0 @@
----
-id: ShippingService
-version: 0.0.1
-name: Shipping Service
-summary: |
-  Service that handles shipping
-owners:
-  - dboyne
-receives:
-  - id: PaymentProcessed
-    from:
-      - id: orders-domain-eventbus
-sends:
-  - id: ShipmentCreated
-    to:
-      - id: orders-domain-eventbus
-  - id: ReturnInitiated
-    to:
-      - id: orders-domain-eventbus
-  - id: ShipmentDispatched
-    to:
-      - id: orders-domain-eventbus
-  - id: ShipmentInTransit
-    to:
-      - id: orders-domain-eventbus
-  - id: ShipmentDelivered
-    to:
-      - id: orders-domain-eventbus
-  - id: DeliveryFailed
-    to:
-      - id: orders-domain-eventbus
-repository:
-  language: JavaScript
-  url: 'https://github.com/event-catalog/pretend-shipping-service'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The Shipping Service is responsible for managing shipping within the system. It handles order creation, updating, status tracking, and interactions with other services such as Inventory, Payment, and Notification services to ensure smooth order processing and fulfillment.
-
-<Tiles >
-    <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="This service sends messages to downstream consumers" />
-    <Tile icon="BoltIcon"  href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="This service receives messages from other services" />
-</Tiles>
-
-### Core features
-
-The Shipping Service is responsible for managing shipping within the system. It handles order creation, updating, status tracking, and interactions with other services such as Inventory, Payment, and Notification services to ensure smooth order processing and fulfillment.
-
-
-## Architecture diagram 
-
-<NodeGraph />
-
-<MessageTable format="all" limit={4} />
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/ubiquitous-language.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/ubiquitous-language.mdx
deleted file mode 100644
index 05859cc15..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/ubiquitous-language.mdx
+++ /dev/null
@@ -1,126 +0,0 @@
----
-dictionary:
-  - id: Payment
-    name: Payment
-    summary: "The act of paying for magical goods or services."
-    icon: Wand2
-  - id: Purchase Order
-    name: Purchase Order
-    summary: "A mystical document issued by a buyer to a seller indicating the types, quantities, and agreed prices for enchanted products or services."
-    description: |
-      A purchase order (PO) is a magical document that initiates the buying process between mystical entities. It protects both buyer and seller by clearly documenting the transaction details. Key components include:
-
-      - Unique PO number for tracking
-      - Detailed item specifications and quantities
-      - Agreed prices and payment terms
-      - Delivery requirements and timelines
-      - Terms and conditions of the purchase
-
-    icon: FileText
-  - id: Order Line
-    name: Order Line
-    summary: "An individual enchanted item within a purchase order, representing a specific magical product or service being ordered."
-    description: |
-      Order lines are the fundamental building blocks of any purchase order. Each line represents a distinct item or service and contains critical information for order fulfillment:
-
-      - Product identifier (SKU or part number)
-      - Quantity ordered
-      - Unit price and total line value
-      - Special handling instructions
-      - Required delivery date
-
-      Order lines drive warehouse picking operations, shipping processes, and financial calculations. They are essential for tracking partial shipments and managing order modifications.
-    icon: ListOrdered
-  - id: SKU
-    name: SKU
-    summary: "Sorcery Keeping Unit - A unique identifier for distinct magical products and their variants in inventory."
-    description: |
-      SKUs are the cornerstone of effective inventory management systems. Each SKU represents a unique combination of product attributes:
-
-      - Product variations (size, color, style)
-      - Storage location identifiers
-      - Supplier information
-      - Reorder points and quantities
-
-      SKUs enable precise inventory tracking, automated reordering, and detailed sales analytics. They are crucial for maintaining optimal stock levels and preventing stockouts or overstock situations.
-    icon: Tag
-  - id: Consignment
-    name: Consignment
-    summary: "A batch of enchanted goods destined for or delivered to someone."
-    description: |
-      A consignment represents the physical movement of goods through the supply chain. It encompasses all aspects of the shipping process:
-
-      - Packaging and labeling requirements
-      - Transportation method and routing
-      - Customs documentation for international shipments
-      - Tracking and proof of delivery
-
-      Consignments may combine multiple orders for efficient shipping and can be tracked as a single unit throughout the delivery process. They are crucial for managing logistics costs and ensuring timely delivery to customers.
-    icon: Package
-  - id: Invoice
-    name: Invoice
-    summary: "A document issued by a seller to a buyer, listing enchanted goods or services provided and the amount due."
-    description: |
-      Invoices are critical for financial transactions, serving as a request for payment from the buyer. They include:
-
-      - Invoice number for tracking
-      - List of products or services provided
-      - Total amount due and payment terms
-      - Seller and buyer contact information
-      - Due date for payment
-
-      Invoices are essential for accounting, tax purposes, and maintaining cash flow.
-    icon: Receipt
-  - id: Supplier
-    name: Supplier
-    summary: "An entity that provides enchanted goods or services to another organization."
-    description: |
-      Suppliers are key partners in the supply chain, responsible for delivering the necessary products or services. Key aspects include:
-
-      - Supplier identification and contact details
-      - Product or service offerings
-      - Pricing and payment terms
-      - Delivery schedules and reliability
-
-      Effective supplier management ensures quality, cost-effectiveness, and timely delivery.
-    icon: Truck
-  - id: Inventory
-    name: Inventory
-    summary: "The complete list of enchanted items held in stock by a business."
-    description: |
-      Inventory management is crucial for balancing supply and demand. It involves:
-
-      - Tracking stock levels and locations
-      - Managing reorder points and quantities
-      - Conducting regular stock audits
-      - Analyzing inventory turnover rates
-
-      Proper inventory management minimizes costs and maximizes service levels.
-    icon: Warehouse
-  - id: Fulfillment
-    name: Fulfillment
-    summary: "The process of completing an order and delivering it to the customer."
-    description: |
-      Fulfillment encompasses all steps from order receipt to delivery, including:
-
-      - Order processing and picking
-      - Packaging and shipping
-      - Delivery tracking and confirmation
-      - Handling returns and exchanges
-
-      Efficient fulfillment is key to customer satisfaction and operational efficiency.
-    icon: PackageCheck
-  - id: Return
-    name: Return
-    summary: "The process of sending back enchanted goods to the seller for a refund or exchange."
-    description: |
-      Returns management is an important aspect of customer service and inventory control. It involves:
-
-      - Processing return requests and authorizations
-      - Inspecting returned items for quality
-      - Restocking or disposing of returned goods
-      - Issuing refunds or exchanges
-
-      A streamlined returns process enhances customer loyalty and operational efficiency.
-    icon: PackageX
----
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/versioned/0.0.1/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/versioned/0.0.1/index.mdx
deleted file mode 100644
index 62330c95f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/versioned/0.0.1/index.mdx
+++ /dev/null
@@ -1,21 +0,0 @@
----
-id: Orders
-name: Orders
-version: 0.0.1
-summary: |
-  Domain for everything shopping
-owners:
-    - dboyne
-    - full-stack
-services:
-    - id: InventoryService
-      version: 0.0.2
-badges:
-    - content: New domain
-      backgroundColor: blue
-      textColor: blue
----
-
-## Overview
-
-<NodeGraph />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/versioned/0.0.2/index.mdx b/examples/default/domains/E-Commerce/subdomains/Orders/versioned/0.0.2/index.mdx
deleted file mode 100644
index 7a93c8ce7..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Orders/versioned/0.0.2/index.mdx
+++ /dev/null
@@ -1,51 +0,0 @@
----
-id: Orders
-name: Orders
-version: 0.0.2
-owners:
-  - dboyne
-services:
-  - id: InventoryService
-    version: 0.0.2
-  - id: NotificationService
-    version: 0.0.2
-  - id: OrdersService
-    version: 0.0.2
-badges:
-  - content: New domain
-    backgroundColor: blue
-    textColor: blue
----
-
-## Overview
-
-The Orders domain handles all operations related to customer orders, from creation to fulfillment. This documentation provides an overview of the events and services involved in the Orders domain, helping developers and stakeholders understand the event-driven architecture.
-
-:::warning
-Please ensure all services are updated to the latest version for compatibility and performance improvements.
-:::
-
-## Bounded context
-
-<NodeGraph />
-
-### Order example (sequence diagram)
-
-```mermaid
-sequenceDiagram
-    participant Customer
-    participant OrdersService
-    participant InventoryService
-    participant NotificationService
-
-    Customer->>OrdersService: Place Order
-    OrdersService->>InventoryService: Check Inventory
-    InventoryService-->>OrdersService: Inventory Available
-    OrdersService->>InventoryService: Reserve Inventory
-    OrdersService->>NotificationService: Send Order Confirmation
-    NotificationService-->>Customer: Order Confirmation
-    OrdersService->>Customer: Order Placed Successfully
-    OrdersService->>InventoryService: Update Inventory
-```
-
- 
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/channels/payment-domain-eventbus/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/channels/payment-domain-eventbus/index.mdx
deleted file mode 100644
index 147e90be1..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/channels/payment-domain-eventbus/index.mdx
+++ /dev/null
@@ -1,15 +0,0 @@
----
-id: payment-domain-eventbus
-name: Payment Domain EventBus
-version: 1.0.0
-summary: |
-  Amazon Payment Domain EventBus
-owners:
-  - dboyne
-routes:
-  - id: cross-account-bus
----
-
-{/* Information about the Orders Domain EventBus */}
-
-Full this....
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/entities/Address/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/entities/Address/index.mdx
deleted file mode 100644
index cb17bf85d..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/entities/Address/index.mdx
+++ /dev/null
@@ -1,162 +0,0 @@
----
-id: Address
-name: Address
-version: 1.0.0
-identifier: addressId
-summary: Represents shipping and billing addresses for customers and orders.
-properties:
-  - name: addressId
-    type: UUID
-    required: true
-    description: Unique identifier for the address
-  - name: customerId
-    type: UUID
-    required: false
-    description: Customer this address belongs to
-    references: Customer
-    referencesIdentifier: customerId
-    relationType: hasOne
-  - name: type
-    type: string
-    required: true
-    description: Type of address
-    enum: ['billing', 'shipping', 'both']
-  - name: firstName
-    type: string
-    required: true
-    description: First name of the recipient
-  - name: lastName
-    type: string
-    required: true
-    description: Last name of the recipient
-  - name: company
-    type: string
-    required: false
-    description: Company name if applicable
-  - name: addressLine1
-    type: string
-    required: true
-    description: Primary address line (street address)
-  - name: addressLine2
-    type: string
-    required: false
-    description: Secondary address line (apartment, suite, etc.)
-  - name: city
-    type: string
-    required: true
-    description: City name
-  - name: state
-    type: string
-    required: true
-    description: State or province
-  - name: postalCode
-    type: string
-    required: true
-    description: Postal or ZIP code
-  - name: country
-    type: string
-    required: true
-    description: Country code (ISO 3166-1 alpha-2)
-  - name: phone
-    type: string
-    required: false
-    description: Phone number for delivery contact
-  - name: isDefault
-    type: boolean
-    required: true
-    description: Whether this is the default address for the customer
-  - name: isValidated
-    type: boolean
-    required: true
-    description: Whether the address has been validated
-  - name: validationDetails
-    type: object
-    required: false
-    description: Address validation details
-    properties:
-      - name: validatedAt
-        type: DateTime
-        description: When the address was validated
-      - name: validationService
-        type: string
-        description: Service used for validation
-      - name: confidence
-        type: decimal
-        description: Validation confidence score
-  - name: geocoordinates
-    type: object
-    required: false
-    description: Geographic coordinates for the address
-    properties:
-      - name: latitude
-        type: decimal
-        description: Latitude coordinate
-      - name: longitude
-        type: decimal
-        description: Longitude coordinate
-  - name: deliveryInstructions
-    type: string
-    required: false
-    description: Special delivery instructions
-  - name: orders
-    type: array
-    items:
-      type: Order
-    required: false
-    description: Orders using this address
-    references: Order
-    referencesIdentifier: shippingAddress
-    relationType: hasMany
-  - name: payments
-    type: array
-    items:
-      type: Payment
-    required: false
-    description: Payments using this as billing address
-    references: Payment
-    referencesIdentifier: billingAddress
-    relationType: hasMany
-  - name: createdAt
-    type: DateTime
-    required: true
-    description: Date and time when the address was created
-  - name: updatedAt
-    type: DateTime
-    required: false
-    description: Date and time when the address was last updated
----
-
-## Overview
-
-The Address entity stores shipping and billing addresses for customers, orders, and payments. It supports address validation, geocoding, and delivery instructions to ensure accurate order fulfillment.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-* **Customer:** An address can belong to one `Customer` (identified by `customerId`).
-* **Order:** An address can be used by multiple `Order` entities for shipping.
-* **Payment:** An address can be used by multiple `Payment` entities for billing.
-
-## Address Types
-
-* **Billing:** Used for payment processing and invoicing
-* **Shipping:** Used for order delivery
-* **Both:** Can be used for both billing and shipping
-
-## Examples
-
-* **Address #1:** John Doe's home address - default shipping and billing address.
-* **Address #2:** Corporate office address - billing only, validated with high confidence.
-* **Address #3:** Gift recipient address - shipping only, with special delivery instructions.
-
-## Business Rules
-
-* Each customer can have only one default address per type
-* Addresses must be validated before being marked as default
-* International addresses require country-specific validation
-* Geocoordinates are automatically populated when available
-* Address changes should create new versions for audit trail
-* PO Box addresses may have shipping restrictions
-* Address validation improves delivery success rates
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/entities/Invoice/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/entities/Invoice/index.mdx
deleted file mode 100644
index ea2277e64..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/entities/Invoice/index.mdx
+++ /dev/null
@@ -1,89 +0,0 @@
----
-id: Invoice
-name: Invoice
-version: 1.0.0
-identifier: invoiceId
-summary: Represents a bill issued to a customer, detailing charges for products or services.
-
-properties:
-  - name: invoiceId
-    type: UUID
-    required: true
-    description: Unique identifier for the invoice.
-  - name: customerId
-    type: UUID
-    required: true
-    description: Identifier of the customer being invoiced
-    references: Customer
-    relationType: hasOne
-  - name: orderId # Optional, if invoice is directly tied to a single order
-    type: UUID
-    required: false
-    description: Identifier of the associated order, if applicable.
-  - name: subscriptionId # Optional, if invoice is for a subscription period
-    type: UUID
-    required: false
-    description: Identifier of the associated subscription, if applicable.
-  - name: invoiceNumber
-    type: string
-    required: true
-    description: Human-readable, sequential identifier for the invoice (may have specific format).
-  - name: issueDate
-    type: Date
-    required: true
-    description: Date the invoice was generated and issued.
-  - name: dueDate
-    type: Date
-    required: true
-    description: Date by which the payment for the invoice is due.
-  - name: totalAmount
-    type: decimal
-    required: true
-    description: The total amount due on the invoice.
-  - name: currency
-    type: string # ISO 4217 code
-    required: true
-    description: Currency of the invoice amount.
-  - name: status
-    type: string # (e.g., Draft, Sent, Paid, Overdue, Void)
-    required: true
-    description: Current status of the invoice.
-  - name: billingAddressId # Address used for this specific invoice
-    type: UUID
-    required: true
-    description: Identifier for the billing address used on this invoice.
-  - name: lineItems
-    type: array
-    items:
-      type: InvoiceLineItem # Assuming a value object or separate entity for line items
-    required: true
-    description: List of individual items or services being charged on the invoice.
-  - name: createdAt
-    type: DateTime
-    required: true
-    description: Timestamp when the invoice record was created.
-  - name: paidAt # Timestamp when payment was confirmed
-    type: DateTime
-    required: false
-    description: Timestamp when the invoice was marked as paid.
----
-
-## Overview
-
-The Invoice entity represents a formal request for payment issued by the business to a customer. It details the products, services, quantities, prices, taxes, and total amount due, along with payment terms.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-*   **Customer:** An invoice is issued to one `Customer`.
-*   **Order/Subscription:** An invoice may be related to one or more `Order`s or a specific `Subscription` period.
-*   **Payment:** An invoice is settled by one or more `Payment` transactions.
-*   **InvoiceLineItem:** An invoice contains multiple `InvoiceLineItem`s detailing the charges.
-*   **BillingProfile:** Invoice generation often uses details from the customer's `BillingProfile`.
-
-## Examples
-
-*   Invoice #INV-00123 issued to Jane Doe for her monthly subscription renewal, due in 15 days.
-*   Invoice #INV-00124 issued to Acme Corp for consulting services rendered in the previous month, status Paid. 
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/entities/Payment/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/entities/Payment/index.mdx
deleted file mode 100644
index e906c87d4..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/entities/Payment/index.mdx
+++ /dev/null
@@ -1,140 +0,0 @@
----
-id: Payment
-name: Payment
-version: 1.0.0
-identifier: paymentId
-aggregateRoot: true
-summary: Represents payment transactions for orders in the e-commerce system.
-properties:
-  - name: paymentId
-    type: UUID
-    required: true
-    description: Unique identifier for the payment
-  - name: orderId
-    type: UUID
-    required: true
-    description: Order this payment is associated with
-    references: Order
-    referencesIdentifier: orderId
-    relationType: hasOne
-  - name: customerId
-    type: UUID
-    required: true
-    description: Customer who made the payment
-    references: Customer
-    referencesIdentifier: customerId
-    relationType: hasOne
-  - name: amount
-    type: decimal
-    required: true
-    description: Payment amount
-  - name: currency
-    type: string
-    required: true
-    description: Currency code (e.g., USD, EUR, GBP)
-  - name: paymentMethod
-    type: string
-    required: true
-    description: Payment method used
-    enum: ['credit_card', 'debit_card', 'paypal', 'stripe', 'bank_transfer', 'apple_pay', 'google_pay']
-  - name: paymentMethodDetails
-    type: object
-    required: false
-    description: Additional payment method specific details
-    properties:
-      - name: cardLast4
-        type: string
-        description: Last 4 digits of card number
-      - name: cardType
-        type: string
-        description: Card type (Visa, MasterCard, etc.)
-      - name: expiryMonth
-        type: integer
-        description: Card expiry month
-      - name: expiryYear
-        type: integer
-        description: Card expiry year
-  - name: status
-    type: string
-    required: true
-    description: Current payment status
-    enum: ['pending', 'processing', 'completed', 'failed', 'cancelled', 'refunded', 'partially_refunded']
-  - name: transactionId
-    type: string
-    required: false
-    description: External payment processor transaction ID
-  - name: gatewayResponse
-    type: object
-    required: false
-    description: Raw response from payment gateway
-  - name: billingAddress
-    type: Address
-    required: true
-    description: Billing address for the payment
-    references: Address
-    referencesIdentifier: addressId
-    relationType: hasOne
-  - name: processedAt
-    type: DateTime
-    required: false
-    description: Date and time when payment was processed
-  - name: failureReason
-    type: string
-    required: false
-    description: Reason for payment failure if applicable
-  - name: refunds
-    type: array
-    items:
-      type: PaymentRefund
-    required: false
-    description: Refunds associated with this payment
-    references: PaymentRefund
-    referencesIdentifier: paymentId
-    relationType: hasMany
-  - name: createdAt
-    type: DateTime
-    required: true
-    description: Date and time when the payment record was created
-  - name: updatedAt
-    type: DateTime
-    required: false
-    description: Date and time when the payment record was last updated
----
-
-## Overview
-
-The Payment entity manages all payment transactions in the e-commerce system. It tracks payment details, status, and relationships with orders and customers, supporting various payment methods and refund scenarios.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-* **Order:** Each payment belongs to one `Order` (identified by `orderId`).
-* **Customer:** Each payment is made by one `Customer` (identified by `customerId`).
-* **Address:** Each payment has a billing `Address` (identified by `billingAddress`).
-* **PaymentRefund:** A payment can have multiple `PaymentRefund` entities for partial or full refunds.
-
-## Payment States
-
-```
-pending → processing → completed
-    ↓         ↓           ↓
-cancelled  failed    refunded/partially_refunded
-```
-
-## Examples
-
-* **Payment #1:** $299.99 credit card payment for Order #12345, completed successfully.
-* **Payment #2:** $150.00 PayPal payment for Order #67890, failed due to insufficient funds.
-* **Payment #3:** $500.00 bank transfer, completed with $50.00 partial refund.
-
-## Business Rules
-
-* Payment amount must match the order total
-* Payment status transitions must follow valid state machine
-* Failed payments should include failure reason
-* Completed payments cannot be cancelled
-* Refunds cannot exceed the original payment amount
-* Payment method details are encrypted and PCI compliant
-* Transaction IDs from payment gateways must be stored for reconciliation
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/entities/PaymentMethod/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/entities/PaymentMethod/index.mdx
deleted file mode 100644
index feec5ece3..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/entities/PaymentMethod/index.mdx
+++ /dev/null
@@ -1,77 +0,0 @@
----
-id: PaymentMethod
-name: PaymentMethod
-version: 1.0.0
-identifier: paymentMethodId
-summary: Represents a payment instrument a customer can use, like a credit card or bank account.
-
-properties:
-  - name: paymentMethodId
-    type: UUID
-    required: true
-    description: Unique identifier for the payment method.
-  - name: customerId
-    type: UUID
-    required: true
-    description: Identifier of the customer who owns this payment method.
-    references: Customer
-    relationType: hasOne
-  - name: type
-    type: string # (e.g., CreditCard, BankAccount, PayPal, ApplePay)
-    required: true
-    description: The type of payment method.
-  - name: details # Contains type-specific details (masked, tokenized)
-    type: object
-    required: true
-    description: Contains type-specific, often sensitive details (e.g., last 4 digits of card, card brand, bank name, account type, token). **Never store raw PANs or sensitive data.**
-    # Example structure for CreditCard:
-    # details:
-    #   brand: "Visa"
-    #   last4: "1234"
-    #   expiryMonth: 12
-    #   expiryYear: 2025
-    #   cardholderName: "Jane Doe"
-    #   gatewayToken: "tok_abc123xyz"
-  - name: isDefault
-    type: boolean
-    required: true
-    description: Indicates if this is the customer's default payment method.
-  - name: billingAddressId # Link to the billing address associated with this method
-    type: UUID
-    required: true
-    description: Identifier for the billing address verified for this payment method.
-  - name: status
-    type: string # (e.g., Active, Expired, Invalid, Removed)
-    required: true
-    description: Current status of the payment method.
-  - name: createdAt
-    type: DateTime
-    required: true
-    description: Timestamp when the payment method was added.
-  - name: updatedAt
-    type: DateTime
-    required: true
-    description: Timestamp when the payment method was last updated.
----
-
-## Overview
-
-The PaymentMethod entity represents a specific payment instrument registered by a customer, such as a credit card or a linked bank account. It stores necessary (non-sensitive) details required to initiate payments and links to the associated customer and billing address.
-
-**Security Note:** Sensitive details like full card numbers or bank account numbers should **never** be stored directly. Rely on tokenization provided by payment gateways.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-*   **Customer:** A payment method belongs to one `Customer`.
-*   **Address:** Linked to a specific billing `Address`.
-*   **Payment:** Used to make `Payment` transactions.
-*   **Subscription:** May be designated as the payment method for a `Subscription`.
-
-## Examples
-
-*   Jane Doe's default Visa card ending in 1234, expiring 12/2025, status Active.
-*   John Smith's linked bank account (Chase, Checking), status Active.
-*   An old MasterCard ending in 5678 belonging to Jane Doe, status Expired. 
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/entities/PaymentRefund/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/entities/PaymentRefund/index.mdx
deleted file mode 100644
index c5a203533..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/entities/PaymentRefund/index.mdx
+++ /dev/null
@@ -1,80 +0,0 @@
----
-id: PaymentRefunded
-name: PaymentRefunded
-version: 1.0.0
-identifier: refundId
-aggregateRoot: true
-summary: Represents refunded payment transactions for orders in the e-commerce system.
-properties:
-  - name: refundId
-    type: UUID
-    required: true
-    description: Unique identifier for the refund
-  - name: paymentId
-    type: UUID
-    required: true
-    description: Payment this refund is associated with
-    references: Payment
-    referencesIdentifier: paymentId
-    relationType: hasOne
-  - name: amount
-    type: decimal
-    required: true
-    description: Refund amount
-  - name: currency
-    type: string
-    required: true
-    description: Currency code (e.g., USD, EUR, GBP)
-  - name: status
-    type: string
-    required: true
-    description: Current refund status
-    enum: ['pending', 'processing', 'completed', 'failed', 'cancelled']
-  - name: processedAt
-    type: DateTime
-    required: false
-    description: Date and time when refund was processed
-  - name: failureReason
-    type: string
-    required: false
-    description: Reason for refund failure if applicable
-  - name: createdAt
-    type: DateTime
-    required: true
-    description: Date and time when the refund record was created
-  - name: updatedAt
-    type: DateTime
-    required: false
-    description: Date and time when the refund record was last updated
----
-
-## Overview
-
-The PaymentRefunded entity manages all refund transactions in the e-commerce system. It tracks refund details, status, and relationships with payments, supporting various refund scenarios.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-* **Payment:** Each refund belongs to one `Payment` (identified by `paymentId`).
-
-## Refund States
-
-```
-pending → processing → completed
-    ↓         ↓           ↓
-cancelled  failed
-```
-
-## Examples
-
-* **Refund #1:** $50.00 refund for Payment #12345, completed successfully.
-* **Refund #2:** $20.00 refund for Payment #67890, failed due to processing error.
-
-## Business Rules
-
-* Refund amount cannot exceed the original payment amount
-* Refund status transitions must follow valid state machine
-* Failed refunds should include failure reason
-* Completed refunds cannot be cancelled
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/entities/Transaction/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/entities/Transaction/index.mdx
deleted file mode 100644
index f13ac5fa6..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/entities/Transaction/index.mdx
+++ /dev/null
@@ -1,77 +0,0 @@
----
-id: Transaction
-name: Transaction
-version: 1.0.0
-identifier: transactionId
-summary: Represents a low-level interaction with a payment gateway or processor (e.g., authorize, capture, refund, void).
-
-properties:
-  - name: transactionId
-    type: UUID
-    required: true
-    description: Unique identifier for this specific gateway transaction.
-  - name: paymentId
-    type: UUID
-    required: true
-    references: Payment
-    relationType: hasOne
-    description: Identifier of the parent Payment this transaction belongs to.
-  - name: type
-    type: string # (e.g., Authorize, Capture, Sale, Refund, Void, Verify)
-    required: true
-    description: The type of operation performed with the payment gateway.
-  - name: gatewayReferenceId
-    type: string
-    required: true
-    description: Unique transaction ID provided by the external payment gateway.
-  - name: amount
-    type: decimal
-    required: true
-    description: The amount associated with this specific transaction operation.
-  - name: currency
-    type: string # ISO 4217 code
-    required: true
-    description: Currency of the transaction amount.
-  - name: status
-    type: string # (e.g., Success, Failure, Pending)
-    required: true
-    description: Status reported by the gateway for this specific operation.
-  - name: responseCode # Gateway-specific code
-    type: string
-    required: false
-    description: Response code returned by the payment gateway.
-  - name: responseMessage # Gateway-specific message
-    type: string
-    required: false
-    description: Detailed message or reason returned by the gateway.
-  - name: processedAt
-    type: DateTime
-    required: true
-    description: Timestamp when the transaction was processed by the gateway.
-  - name: rawRequest # Optional, for debugging - consider security implications
-    type: text
-    required: false
-    description: Raw request payload sent to the gateway (use with caution).
-  - name: rawResponse # Optional, for debugging - consider security implications
-    type: text
-    required: false
-    description: Raw response payload received from the gateway (use with caution).
----
-
-## Overview
-
-The Transaction entity logs the individual interactions with an external payment processor (like Stripe, PayPal, Adyen) that occur as part of processing a `Payment`. This provides a detailed audit trail of gateway operations, including authorizations, captures, refunds, and any associated success or failure responses.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-*   **Payment:** A transaction is part of one `Payment`.
-
-## Examples
-
-*   **Authorization Success:** Type: Authorize, PaymentID: PAY-98765, GatewayRef: auth_abc, Amount: $19.99, Status: Success.
-*   **Capture Success:** Type: Capture, PaymentID: PAY-98765, GatewayRef: ch_def, Amount: $19.99, Status: Success (following the authorization).
-*   **Authorization Failure:** Type: Authorize, PaymentID: PAY-98766, GatewayRef: auth_ghi, Amount: $50.00, Status: Failure, ResponseCode: 'declined', ResponseMessage: 'Insufficient Funds'.
-*   **Refund Success:** Type: Refund, PaymentID: PAY-98760, GatewayRef: re_jkl, Amount: $25.00, Status: Success. 
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/flows/PaymentProcessed/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/flows/PaymentProcessed/index.mdx
deleted file mode 100644
index 8721977be..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/flows/PaymentProcessed/index.mdx
+++ /dev/null
@@ -1,86 +0,0 @@
----
-id: PaymentFlow
-name: Payment Flow for customers
-version: 1.0.0
-summary: Business flow for processing payments in an e-commerce platform
-owners:
-    - dboyne
-steps:
-    - id: "flow_step"
-      title: "Flow Step"
-      flow:
-        id: SubscriptionRenewed
-      next_step: 
-        id: "place_order_request"  
-        label: "Subscription Renewed, New Order Placed"
-    - id: "place_order_request"
-      title: Place order
-      message:
-        id: PlaceOrder
-        version: 0.0.1
-      next_step:
-        id: "payment_initiated"
-        label: Initiate payment
-    - id: "payment_initiated"
-      title: Payment Initiated
-      message:
-        id: PaymentInitiated
-        version: 0.0.1
-      next_steps:
-        - "payment_processed"
-        - "payment_failed"
-    - id: "payment_processed"
-      title: Payment Processed
-      message:
-        id: PaymentProcessed
-        version: 0.0.1
-      next_steps:
-        - id: "adjust_inventory"
-          label: Adjust inventory
-        - id: "send_custom_notification"
-          label: Notify customer
-    - id: "payment_failed"
-      title: Payment Failed
-      type: node
-      next_steps:
-        - id: "failure_notification"
-          label: Notify customer of failure
-        - id: "retry_payment"
-          label: Retry payment
-    - id: "adjust_inventory"
-      title: Inventory Adjusted
-      message:
-        id: InventoryAdjusted
-        version: 1.0.1
-      next_step:
-        id: "payment_complete"
-        label: Complete order
-    - id: "send_custom_notification"
-      title: Customer Notified of Payment
-      type: node
-      next_step:
-        id: "payment_complete"
-        label: Complete order
-    - id: "failure_notification"
-      title: Customer Notified of Failure
-      type: node
-    - id: "retry_payment"
-      title: Retry Payment
-      type: node
-      next_step:
-        id: "payment_initiated"
-        label: Retry payment process
-    - id: "payment_complete"
-      title: Payment Complete
-      message:
-        id: PaymentComplete
-      next_step:
-        id: "order-complete"
-        label: Order completed
-    - id: "order-complete"
-      title: Order Completed
-      type: node
----
-
-### Flow of feature
-<NodeGraph />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/index.mdx
deleted file mode 100644
index d17da70e7..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/index.mdx
+++ /dev/null
@@ -1,56 +0,0 @@
----
-id: Payment
-name: Payment
-version: 0.0.1
-summary: |
-  Domain that contains payment related services and messages for processing financial transactions.
-owners:
-    - dboyne
-services:
-  - id: PaymentService
-    version: 0.0.1
-  - id: FraudDetectionService
-    version: 0.0.1
-  - id: PaymentGatewayService
-    version: 0.0.1
-entities:
-  - id: Invoice
-  - id: Payment
-  - id: PaymentMethod
-  - id: Transaction
-  - id: Address
-badges:
-    - content: Subdomain
-      backgroundColor: blue
-      textColor: blue
-      icon: BoltIcon
----
-
-## Overview
-
-The Payment Domain encompasses all services and components related to handling financial transactions within the system. It is responsible for managing payments, transactions, billing, fraud detection, and financial records. The domain ensures secure, reliable, and efficient processing of all payment-related activities.
-
-## Services
-
-### PaymentService
-Core payment orchestration service that coordinates payment workflows and maintains payment state.
-
-### FraudDetectionService
-Analyzes transactions in real-time to detect fraudulent activity using machine learning models and rule-based systems.
-
-### PaymentGatewayService
-Manages integrations with external payment processors (Stripe, PayPal, etc.) and provides a unified interface for payment operations.
-
-## Cross-Domain Integration
-
-The Payment domain integrates with:
-
-- **Subscriptions Domain**: Processes recurring payments for subscriptions
-- **Orders Domain**: Handles payments for customer orders
-- **Inventory Domain**: Updates based on successful payments
-
-## Bounded context
-
-<NodeGraph mode="full" />
-
-<MessageTable format="all" limit={6} />
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/containers/fraud-analytics-db/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/containers/fraud-analytics-db/index.mdx
deleted file mode 100644
index 49f18a04f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/containers/fraud-analytics-db/index.mdx
+++ /dev/null
@@ -1,163 +0,0 @@
----
-id: fraud-analytics-db
-name: Fraud Analytics DB
-version: 0.0.1
-container_type: dataWarehouse
-technology: clickhouse@23
-access_mode: readWrite
-classification: confidential
-retention: 5y
-residency: eu-west-1
-summary: Analytics database for fraud detection patterns, risk scoring, and transaction analysis
----
-
-<NodeGraph />
-
-### What is this?
-Fraud Analytics DB is a ClickHouse columnar database optimized for high-speed analytics on transaction patterns, fraud signals, and risk assessment. It stores historical fraud data and real-time transaction features used by machine learning models.
-
-### What does it store?
-- **Transaction Features**: Extracted features from payment transactions for ML model scoring
-- **Fraud Signals**: Device fingerprints, IP addresses, velocity metrics, behavioral patterns
-- **Risk Scores**: Historical risk scores and fraud decisions for model training
-- **Fraud Cases**: Confirmed fraud incidents with investigation notes
-- **Model Predictions**: ML model outputs and confidence scores for analysis
-
-### Who writes to it?
-- **FraudDetectionService** writes real-time transaction features and risk scores
-- **Data Pipeline** ingests historical fraud data from payment systems
-- **Manual Review Team** updates fraud case outcomes and labels
-
-### Who reads from it?
-- **FraudDetectionService** queries historical patterns for real-time scoring
-- **ML Training Pipeline** extracts training data for model retraining
-- **Data Science Team** analyzes fraud trends and model performance
-- **Business Intelligence** generates fraud metrics and dashboards
-- **Compliance Team** audits fraud detection decisions
-
-### High-level data model
-- `transaction_features`: Real-time extracted features (device, location, amount patterns)
-- `fraud_signals`: Aggregated signals (velocity, anomaly scores)
-- `risk_decisions`: Historical risk decisions and outcomes
-- `fraud_labels`: Ground truth labels for confirmed fraud cases
-- Time-series data partitioned by day for optimal query performance
-
-### Common queries
-```sql
--- Calculate fraud rate by country (last 30 days)
-SELECT
-  country_code,
-  COUNT(*) as total_transactions,
-  SUM(is_fraud) as fraud_count,
-  (SUM(is_fraud) * 100.0 / COUNT(*)) as fraud_rate
-FROM transaction_features
-WHERE event_date >= today() - 30
-GROUP BY country_code
-ORDER BY fraud_rate DESC;
-
--- Get high-risk transaction patterns
-SELECT
-  customer_id,
-  COUNT(*) as transaction_count,
-  AVG(risk_score) as avg_risk_score,
-  MAX(risk_score) as max_risk_score
-FROM risk_decisions
-WHERE event_date = today()
-  AND risk_score > 80
-GROUP BY customer_id
-HAVING transaction_count > 5;
-
--- Analyze model performance over time
-SELECT
-  toStartOfHour(created_at) as hour,
-  model_version,
-  AVG(risk_score) as avg_score,
-  SUM(is_fraud) as actual_fraud_count,
-  COUNT(*) as total_predictions
-FROM risk_decisions
-WHERE created_at >= now() - INTERVAL 7 DAY
-GROUP BY hour, model_version
-ORDER BY hour DESC;
-
--- Find velocity anomalies (multiple transactions same customer)
-SELECT
-  customer_id,
-  COUNT(*) as tx_count,
-  SUM(amount_cents) as total_amount,
-  arrayDistinct(groupArray(ip_address)) as unique_ips,
-  arrayDistinct(groupArray(device_fingerprint)) as unique_devices
-FROM transaction_features
-WHERE event_date = today()
-  AND created_at >= now() - INTERVAL 1 HOUR
-GROUP BY customer_id
-HAVING tx_count > 5 OR length(unique_ips) > 3;
-```
-
-### Access patterns and guidance
-- Queries are highly parallelized across columns for fast analytics
-- Use `event_date` partition key in WHERE clauses for optimal performance
-- Aggregate queries benefit from ClickHouse's native aggregation functions
-- Avoid SELECT * on large tables; specify needed columns
-- Use materialized views for frequently accessed aggregations
-
-### Data retention and archiving
-- **Hot data**: Last 90 days on high-performance SSD storage
-- **Warm data**: 91 days to 2 years on standard storage
-- **Cold archive**: 2-5 years on object storage (S3)
-- Automated archival jobs run monthly
-
-### Security and compliance
-- Contains sensitive fraud signals and PII (IP addresses, device IDs)
-- Access requires security clearance and fraud team membership
-- All queries logged for audit trail
-- Data anonymized for ML training datasets shared outside fraud team
-- GDPR right-to-deletion supported via customer_id purge jobs
-
-### Requesting access
-To request access to Fraud Analytics DB:
-
-1. **Analyst access** (read-only):
-   - Submit request via [ServiceNow](https://company.service-now.com)
-   - Select "Data Analytics Access" → "Fraud Analytics DB"
-   - Requires fraud team manager approval + security clearance
-   - Access granted within 2-3 business days
-
-2. **Data Science access** (read + export):
-   - Additional approval from Chief Data Officer required
-   - Data export must be to secure workbench environment only
-   - Training data exports require anonymization review
-
-3. **Production write access**:
-   - Restricted to FraudDetectionService automated processes
-   - Manual writes require incident ticket and fraud team lead approval
-
-**Contact**: For access questions:
-- Slack: #fraud-detection-team
-- Email: fraud-team@company.com
-- Data governance: data-governance@company.com
-
-### Performance characteristics
-- **Query latency**: p95 < 500ms for point queries, < 5s for complex aggregations
-- **Insert throughput**: 100,000+ events/second
-- **Compression ratio**: ~10x (columnar storage)
-- **Data freshness**: Near real-time (< 10 second delay)
-
-### Monitoring and alerts
-- Query performance monitoring (slow queries > 10s)
-- Data freshness lag alerts
-- Storage capacity monitoring (alert at 80%)
-- Replication lag alerts for distributed tables
-
-### Local development
-- Local ClickHouse via Docker: `docker-compose up fraud-analytics-db`
-- Connection string: `FRAUD_ANALYTICS_DB_URL` environment variable
-- Sample dataset available: `npm run seed:fraud-analytics`
-- Use ClickHouse client: `clickhouse-client --host localhost --port 9000`
-
-### Common issues and troubleshooting
-- **Slow aggregation queries**: Ensure event_date partition key is used in WHERE clause
-- **Out of memory errors**: Reduce query complexity or increase max_memory_usage setting
-- **Data duplication**: Use ReplacingMergeTree for deduplication on insert
-- **Query timeout**: Increase max_execution_time or optimize query with EXPLAIN
-
-For more information, see FraudDetectionService documentation and ClickHouse best practices guide.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/containers/ml-model-store/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/containers/ml-model-store/index.mdx
deleted file mode 100644
index f27850f19..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/containers/ml-model-store/index.mdx
+++ /dev/null
@@ -1,182 +0,0 @@
----
-id: ml-model-store
-name: ML Model Store
-version: 0.0.1
-container_type: objectStore
-technology: s3
-access_mode: read
-classification: internal
-retention: 3y
-residency: eu-west-1
-summary: Object storage for trained ML models, model artifacts, and versioned fraud detection models
----
-
-<NodeGraph />
-
-### What is this?
-ML Model Store is an S3 bucket that stores trained machine learning models, feature extractors, and model artifacts used by the Fraud Detection Service. It provides versioned storage for model rollback and A/B testing.
-
-### What does it store?
-- **Trained Models**: Serialized fraud detection models (TensorFlow SavedModel, ONNX, pickle)
-- **Model Metadata**: Model version, training date, performance metrics, feature schema
-- **Feature Extractors**: Preprocessing pipelines and feature engineering code
-- **Model Configs**: Hyperparameters, training configuration, deployment settings
-- **Experiment Results**: Training logs, validation metrics, confusion matrices
-
-### Storage structure
-```
-ml-models/
-├── fraud-detection/
-│   ├── production/
-│   │   ├── v2.3.1/
-│   │   │   ├── model.onnx
-│   │   │   ├── metadata.json
-│   │   │   ├── feature_schema.json
-│   │   │   └── performance_metrics.json
-│   │   └── current -> v2.3.1 (symlink)
-│   ├── staging/
-│   │   └── v2.4.0-rc1/
-│   └── experiments/
-│       └── exp-2024-01-15-xgboost/
-├── feature-extractors/
-│   └── v1.2.0/
-│       ├── preprocessor.pkl
-│       └── feature_config.yaml
-└── archived/
-    └── deprecated-models/
-```
-
-### Who writes to it?
-- **ML Training Pipeline** uploads newly trained models after validation
-- **Data Science Team** uploads experimental models and feature extractors
-- **CI/CD Pipeline** promotes models from staging to production
-
-### Who reads from it?
-- **FraudDetectionService** loads production models on startup and refresh
-- **Model Serving Infrastructure** fetches models for deployment
-- **A/B Testing Framework** loads multiple model versions for comparison
-- **Model Monitoring Service** reads metadata for drift detection
-
-### Object lifecycle
-1. Models trained in ML platform → uploaded to `experiments/` folder
-2. Validated models promoted to `staging/` with metadata
-3. Approved models moved to `production/` with version tag
-4. Old production models archived after 90 days in `archived/`
-5. Archived models deleted after 3 years
-
-### Model metadata format
-```json
-{
-  "model_id": "fraud-detection-v2.3.1",
-  "version": "2.3.1",
-  "trained_at": "2024-01-15T10:30:00Z",
-  "framework": "tensorflow",
-  "format": "onnx",
-  "training_dataset": {
-    "date_range": "2023-10-01 to 2024-01-01",
-    "total_samples": 5000000,
-    "fraud_rate": 0.023
-  },
-  "performance": {
-    "auc_roc": 0.94,
-    "precision": 0.89,
-    "recall": 0.87,
-    "f1_score": 0.88,
-    "false_positive_rate": 0.02
-  },
-  "features": ["transaction_amount", "device_fingerprint", "ip_country", "..."],
-  "deployment": {
-    "min_memory_mb": 512,
-    "inference_latency_p99_ms": 50,
-    "deployed_at": "2024-01-16T08:00:00Z"
-  }
-}
-```
-
-### Access patterns
-- Models loaded on FraudDetectionService startup (cold start)
-- Periodic refresh every 6 hours to pick up new model versions
-- Blue-green deployment: new version tested in parallel before full rollout
-- Model download cached locally on service instances to reduce S3 calls
-
-### Versioning strategy
-- **Semantic versioning**: major.minor.patch (e.g., 2.3.1)
-- **Major**: Breaking changes to feature schema or model API
-- **Minor**: Model improvements without breaking changes
-- **Patch**: Bug fixes, retraining with same architecture
-- Git tags linked to model versions for traceability
-
-### Security and access control
-- **Read access**: FraudDetectionService IAM role only
-- **Write access**: ML training pipeline CI/CD role only
-- **Encryption**: AES-256 server-side encryption enabled
-- **Versioning**: S3 versioning enabled for rollback capability
-- **Access logs**: All S3 access logged to audit bucket
-
-### Requesting access
-To request access to ML Model Store:
-
-1. **Read access** (for service integration):
-   - Create IAM role request via [AWS Access Portal](https://company.awsapps.com)
-   - Select "S3 Read Access" → "ml-model-store"
-   - Requires fraud team lead approval
-   - Access granted within 1 business day
-
-2. **Write access** (for ML engineers):
-   - Submit request via #ml-platform Slack channel
-   - Requires senior ML engineer approval + security review
-   - Write access limited to `experiments/` and `staging/` folders
-   - Production writes restricted to CI/CD pipeline only
-
-3. **Data Science exploration**:
-   - Use ML Platform workbench with pre-configured read access
-   - Contact #ml-platform for workspace setup
-
-**Contact**:
-- ML Platform: #ml-platform
-- Fraud ML Team: #fraud-ml-team
-- Model governance: ml-governance@company.com
-
-### Model deployment workflow
-1. Train model in ML platform environment
-2. Upload to `experiments/` with metadata and performance metrics
-3. Validation tests run automatically (schema check, performance baseline)
-4. If validated, promote to `staging/` for canary deployment
-5. Monitor staging metrics for 24 hours
-6. Approve production promotion via deployment ticket
-7. CI/CD pipeline moves model to `production/` and updates symlink
-8. FraudDetectionService auto-refreshes and loads new model
-
-### Monitoring and alerts
-- **Model staleness**: Alert if production model > 30 days old
-- **Download failures**: Alert on 5xx errors from S3
-- **Storage costs**: Monitor bucket size (alert at $500/month)
-- **Performance drift**: Compare new model metrics vs. baseline
-
-### Backup and disaster recovery
-- **S3 versioning**: Enabled for accidental deletion protection
-- **Cross-region replication**: Models replicated to us-east-1 for DR
-- **Backup frequency**: Automatic with S3 durability (99.999999999%)
-- **Recovery time**: < 5 minutes (point production symlink to previous version)
-
-### Local development
-- Local MinIO S3-compatible storage: `docker-compose up minio`
-- Connection: `AWS_ENDPOINT_URL=http://localhost:9000`
-- Seed models: `npm run seed:ml-models`
-- CLI access: `aws s3 ls s3://ml-model-store/ --endpoint-url http://localhost:9000`
-
-### Common issues and troubleshooting
-- **Model load timeout**: Increase service timeout, check S3 connectivity
-- **Version mismatch**: Ensure feature schema matches model version in metadata
-- **Cold start latency**: Pre-warm model cache on service startup
-- **S3 rate limits**: Use CloudFront or S3 acceleration for high-traffic models
-- **Model size too large**: Compress models with ONNX optimization or quantization
-
-### Best practices
-- Always include metadata.json with model performance metrics
-- Test models in staging before production deployment
-- Keep last 3 production versions for quick rollback
-- Document breaking changes in model version release notes
-- Monitor inference latency in production after deployment
-
-For more information, see ML Platform documentation and Model Deployment Playbook.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/events/FraudCheckCompleted/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/events/FraudCheckCompleted/index.mdx
deleted file mode 100644
index 450d99711..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/events/FraudCheckCompleted/index.mdx
+++ /dev/null
@@ -1,48 +0,0 @@
----
-id: FraudCheckCompleted
-version: 0.0.1
-name: Fraud Check Completed
-summary: Emitted when a fraud check has been completed for a transaction
-tags:
-  - payment
-  - fraud
-  - security
-badges:
-  - content: New
-    backgroundColor: green
-    textColor: white
-schemaPath: schema.proto
----
-
-import Footer from '@catalog/components/footer.astro'
-
-## Overview
-
-The `FraudCheckCompleted` event is emitted when the fraud detection service has completed its analysis of a payment transaction. This event contains the risk assessment results and recommendations.
-
-## Schema
-
-<SchemaViewer title="FraudCheckCompleted Schema" file="schema.json" />
-
-## Event Details
-
-- **Risk Score**: A numerical score from 0-100 indicating fraud risk
-- **Decision**: APPROVED, DECLINED, or MANUAL_REVIEW
-- **Reasons**: Array of reasons for the decision
-- **Confidence**: Confidence level of the fraud detection
-
-## Example Payload
-
-```json
-{
-  "transactionId": "txn_1234567890",
-  "paymentId": "pay_9876543210",
-  "riskScore": 25,
-  "decision": "APPROVED",
-  "reasons": ["Low risk merchant", "Customer history positive"],
-  "confidence": 0.92,
-  "timestamp": "2024-01-15T10:30:00Z"
-}
-```
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/events/FraudCheckCompleted/schema.proto b/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/events/FraudCheckCompleted/schema.proto
deleted file mode 100644
index 6926bdd95..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/events/FraudCheckCompleted/schema.proto
+++ /dev/null
@@ -1,17 +0,0 @@
-syntax = "proto3";
-
-package com.example.frauddetection;
-
-message FraudCheckCompleted {
-  string transactionId = 1;
-  string paymentId = 2;
-  int32 riskScore = 3;
-  string decision = 4;
-  repeated string reasons = 5;
-  double confidence = 6;
-  string timestamp = 7;
-}
-
-message FraudCheckCompletedEvent {
-  FraudCheckCompleted fraudCheckCompleted = 1;
-}
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/events/FraudDetected/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/events/FraudDetected/index.mdx
deleted file mode 100644
index 7176bd6a1..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/events/FraudDetected/index.mdx
+++ /dev/null
@@ -1,43 +0,0 @@
----
-id: FraudDetected
-version: 0.0.1
-name: Fraud Detected
-summary: Emitted when a fraud is detected in a transaction
-tags:
-  - payment
-  - fraud
-  - security
-badges:
-  - content: New
-    backgroundColor: green
-    textColor: white
----
-
-import Footer from '@catalog/components/footer.astro'
-
-## Overview
-
-The `FraudDetected` event is emitted when the fraud detection service identifies a potential fraud in a payment transaction. This event contains the details of the detected fraud.
-
-## Event Details
-
-- **Fraud Type**: Type of fraud detected
-- **Severity**: LOW, MEDIUM, or HIGH
-- **Indicators**: Array of indicators that led to the detection
-- **Confidence**: Confidence level of the fraud detection
-
-## Example Payload
-
-```json
-{
-  "transactionId": "txn_1234567890",
-  "paymentId": "pay_9876543210",
-  "fraudType": "Stolen Card",
-  "severity": "HIGH",
-  "indicators": ["Unusual location", "High transaction amount"],
-  "confidence": 0.95,
-  "timestamp": "2024-01-15T10:30:00Z"
-}
-```
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/events/RiskScoreCalculated/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/events/RiskScoreCalculated/index.mdx
deleted file mode 100644
index 5b0431977..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/events/RiskScoreCalculated/index.mdx
+++ /dev/null
@@ -1,43 +0,0 @@
----
-id: RiskScoreCalculated
-version: 0.0.1
-name: Risk Score Calculated
-summary: Emitted when a risk score is calculated for a transaction
-tags:
-  - payment
-  - fraud
-  - security
-badges:
-  - content: New
-    backgroundColor: green
-    textColor: white
----
-
-import Footer from '@catalog/components/footer.astro'
-
-## Overview
-
-The `RiskScoreCalculated` event is emitted when the fraud detection service calculates a risk score for a payment transaction. This event contains the details of the calculated risk score.
-
-## Event Details
-
-- **Risk Score**: Calculated risk score for the transaction
-- **Severity**: LOW, MEDIUM, or HIGH
-- **Indicators**: Array of indicators used in the calculation
-- **Confidence**: Confidence level of the risk score calculation
-
-## Example Payload
-
-```json
-{
-  "transactionId": "txn_1234567890",
-  "paymentId": "pay_9876543210",
-  "riskScore": 85,
-  "severity": "MEDIUM",
-  "indicators": ["Unusual location", "High transaction amount"],
-  "confidence": 0.85,
-  "timestamp": "2024-01-15T10:30:00Z"
-}
-```
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/index.mdx
deleted file mode 100644
index 57cc044bb..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/FraudDetectionService/index.mdx
+++ /dev/null
@@ -1,71 +0,0 @@
----
-id: FraudDetectionService
-version: 0.0.1
-name: Fraud Detection Service
-summary: Analyzes payment transactions for fraudulent activity and risk assessment
-repository:
-  url: 'https://github.com/eventcatalog/fraud-detection-service'
-receives:
-  - id: PaymentInitiated
-    version: 0.0.1
-    from:
-      - id: 'payments.{env}.events'
-        parameters:
-          env: staging
-sends:
-  - id: FraudCheckCompleted
-    version: 0.0.1
-  - id: FraudDetected
-    version: 0.0.1
-  - id: RiskScoreCalculated
-    version: 0.0.1
-writesTo:
-  - id: fraud-analytics-db
-    version: 0.0.1
-readsFrom:
-  - id: fraud-analytics-db
-    version: 0.0.1
-  - id: ml-model-store
-    version: 0.0.1
-  - id: payment-cache
-    version: 0.0.1
-owners:
-  - dboyne
----
-
-import Footer from '@catalog/components/footer.astro'
-
-## Overview
-
-The Fraud Detection Service is responsible for analyzing payment transactions in real-time to detect potential fraudulent activity. It uses machine learning models and rule-based systems to assess risk and prevent financial losses.
-
-<NodeGraph />
-
-## Key Features
-
-- **Real-time Transaction Analysis**: Analyzes transactions as they occur
-- **Machine Learning Models**: Uses ML to identify suspicious patterns
-- **Risk Scoring**: Calculates risk scores for each transaction
-- **Automated Blocking**: Can automatically block high-risk transactions
-- **Manual Review Queue**: Flags medium-risk transactions for manual review
-
-## API Endpoints
-
-### REST API
-- `POST /api/fraud/check` - Submit transaction for fraud check
-- `GET /api/fraud/risk-score/{transactionId}` - Get risk score for transaction
-- `PUT /api/fraud/override/{transactionId}` - Manual override of fraud decision
-
-## Configuration
-
-```yaml
-fraud_detection:
-  risk_thresholds:
-    high: 80
-    medium: 50
-    low: 20
-  auto_block_threshold: 90
-  ml_model_version: "2.3.1"
-```
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/commands/ProcessPayment/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/commands/ProcessPayment/index.mdx
deleted file mode 100644
index 5dc3b66fb..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/commands/ProcessPayment/index.mdx
+++ /dev/null
@@ -1,72 +0,0 @@
----
-id: ProcessPayment
-version: 0.0.1
-name: Process Payment
-summary: Command to process a payment through the payment gateway
-tags:
-  - payment
-  - command
-  - cross-domain
-badges:
-  - content: Command
-    backgroundColor: blue
-    textColor: white
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro'
-
-## Overview
-
-The `ProcessPayment` command is used to initiate payment processing through the payment gateway. This command can be triggered by various sources including the Billing Service for subscription payments.
-
-## Command Sources
-
-This command can be triggered by:
-- **BillingService** (Subscriptions Domain) - For recurring subscription payments
-- **OrdersService** (Orders Domain) - For one-time order payments
-- **PaymentService** (Payment Domain) - For payment retries
-
-## Command Flow
-
-```mermaid
-sequenceDiagram
-    participant BS as BillingService
-    participant PGS as PaymentGatewayService
-    participant FDS as FraudDetectionService
-    participant EXT as External Gateway
-    
-    BS->>PGS: ProcessPayment
-    PGS->>FDS: Check Fraud
-    FDS-->>PGS: Risk Assessment
-    PGS->>EXT: Process Payment
-    EXT-->>PGS: Payment Result
-    PGS-->>BS: PaymentProcessed/Failed
-```
-
-## Schema
-
-<SchemaViewer title="ProcessPayment Schema" file={frontmatter.schemaPath} />
-
-## Example Request
-
-```json
-{
-  "paymentId": "pay_123456",
-  "amount": 49.99,
-  "currency": "USD",
-  "paymentMethod": {
-    "type": "card",
-    "token": "tok_visa_4242"
-  },
-  "metadata": {
-    "subscriptionId": "sub_ABC123",
-    "invoiceId": "inv_123456",
-    "customerId": "cust_XYZ789"
-  },
-  "idempotencyKey": "sub_ABC123_2024_02",
-  "captureImmediately": true
-}
-```
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/commands/ProcessPayment/schema.json b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/commands/ProcessPayment/schema.json
deleted file mode 100644
index 04ba14cdd..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/commands/ProcessPayment/schema.json
+++ /dev/null
@@ -1,58 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "paymentId": {
-      "type": "string",
-      "description": "Unique identifier for this payment"
-    },
-    "amount": {
-      "type": "number",
-      "description": "Payment amount"
-    },
-    "currency": {
-      "type": "string",
-      "description": "Currency code (ISO 4217)"
-    },
-    "paymentMethod": {
-      "type": "object",
-      "properties": {
-        "type": {
-          "type": "string",
-          "enum": ["card", "bank_transfer", "paypal", "digital_wallet"]
-        },
-        "token": {
-          "type": "string",
-          "description": "Payment method token"
-        }
-      },
-      "required": ["type", "token"]
-    },
-    "metadata": {
-      "type": "object",
-      "properties": {
-        "subscriptionId": {
-          "type": "string"
-        },
-        "invoiceId": {
-          "type": "string"
-        },
-        "customerId": {
-          "type": "string"
-        },
-        "orderId": {
-          "type": "string"
-        }
-      }
-    },
-    "idempotencyKey": {
-      "type": "string",
-      "description": "Key to prevent duplicate payments"
-    },
-    "captureImmediately": {
-      "type": "boolean",
-      "description": "Whether to capture payment immediately or just authorize"
-    }
-  },
-  "required": ["paymentId", "amount", "currency", "paymentMethod", "idempotencyKey"]
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/events/PaymentFailed/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/events/PaymentFailed/index.mdx
deleted file mode 100644
index 3b0739721..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/events/PaymentFailed/index.mdx
+++ /dev/null
@@ -1,60 +0,0 @@
----
-id: PaymentFailed
-version: 0.0.1
-name: Payment Failed
-summary: Emitted when a payment attempt fails
-badges:
-  - content: Error Event
-    backgroundColor: red
-    textColor: white
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro'
-
-## Overview
-
-The `PaymentFailed` event is emitted when a payment attempt fails for any reason. This event is consumed by various services to handle payment failures appropriately.
-
-## Consumers
-
-This event is consumed by:
-- **BillingService** (Subscriptions Domain) - To handle subscription payment failures
-- **OrdersService** (Orders Domain) - To handle order payment failures
-- **NotificationService** (Orders Domain) - To notify customers of payment failures
-
-## Failure Reasons
-
-Common failure reasons include:
-- **insufficient_funds** - Card has insufficient funds
-- **card_declined** - Card was declined by issuer
-- **expired_card** - Card has expired
-- **fraud_suspected** - Payment flagged as potentially fraudulent
-- **network_error** - Payment gateway network error
-- **invalid_payment_method** - Payment method is invalid
-
-## Schema
-
-<SchemaViewer title="PaymentFailed Schema" file="schema.json" />
-
-## Example Payload
-
-```json
-{
-  "paymentId": "pay_123456",
-  "amount": 49.99,
-  "currency": "USD",
-  "failureReason": "insufficient_funds",
-  "failureMessage": "Your card has insufficient funds",
-  "metadata": {
-    "subscriptionId": "sub_ABC123",
-    "invoiceId": "inv_123456",
-    "customerId": "cust_XYZ789"
-  },
-  "canRetry": true,
-  "nextRetryAt": "2024-02-02T00:00:00Z",
-  "timestamp": "2024-02-01T10:30:00Z"
-}
-```
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/events/PaymentFailed/schema.json b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/events/PaymentFailed/schema.json
deleted file mode 100644
index c807c58ca..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/events/PaymentFailed/schema.json
+++ /dev/null
@@ -1,68 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "paymentId": {
-      "type": "string",
-      "description": "Unique identifier for the failed payment"
-    },
-    "amount": {
-      "type": "number",
-      "description": "Payment amount that failed"
-    },
-    "currency": {
-      "type": "string",
-      "description": "Currency code (ISO 4217)"
-    },
-    "failureReason": {
-      "type": "string",
-      "enum": [
-        "insufficient_funds",
-        "card_declined",
-        "expired_card",
-        "fraud_suspected",
-        "network_error",
-        "invalid_payment_method",
-        "authentication_required",
-        "other"
-      ],
-      "description": "Reason for payment failure"
-    },
-    "failureMessage": {
-      "type": "string",
-      "description": "Human-readable failure message"
-    },
-    "metadata": {
-      "type": "object",
-      "properties": {
-        "subscriptionId": {
-          "type": "string"
-        },
-        "invoiceId": {
-          "type": "string"
-        },
-        "customerId": {
-          "type": "string"
-        },
-        "orderId": {
-          "type": "string"
-        }
-      }
-    },
-    "canRetry": {
-      "type": "boolean",
-      "description": "Whether this payment can be retried"
-    },
-    "nextRetryAt": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Suggested time for next retry attempt"
-    },
-    "timestamp": {
-      "type": "string",
-      "format": "date-time",
-      "description": "When the failure occurred"
-    }
-  },
-  "required": ["paymentId", "amount", "currency", "failureReason", "timestamp"]
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/index.mdx
deleted file mode 100644
index 7affca0bf..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentGatewayService/index.mdx
+++ /dev/null
@@ -1,74 +0,0 @@
----
-id: PaymentGatewayService
-version: 0.0.1
-name: Payment Gateway Service
-summary: Manages integration with external payment processors (Stripe, PayPal, etc.)
-tags:
-  - payment
-  - gateway
-  - integration
-repository:
-  url: https://github.com/eventcatalog/payment-gateway-service
-receives:
-  - id: ProcessPayment
-    version: 0.0.1
-    from:
-      - id: 'payment-domain-eventbus'
-  - id: FraudCheckCompleted
-    version: 0.0.1
-sends:
-  - id: PaymentFailed
-    version: 0.0.1
-owners:
-  - dboyne
----
-
-import Footer from '@catalog/components/footer.astro'
-
-## Overview
-
-The Payment Gateway Service acts as an abstraction layer between our payment system and external payment processors. It handles the complexity of integrating with multiple payment providers and provides a unified interface for payment operations.
-
-<NodeGraph />
-
-## Supported Payment Providers
-
-- **Stripe**: Credit/debit cards, digital wallets
-- **PayPal**: PayPal accounts, PayPal Credit
-- **Square**: In-person and online payments
-- **Adyen**: Global payment processing
-- **Braintree**: Multiple payment methods
-
-## Key Features
-
-- **Multi-provider Support**: Switch between providers seamlessly
-- **Retry Logic**: Automatic retry for failed transactions
-- **Tokenization**: Secure card data handling
-- **Webhook Management**: Handles provider webhooks
-- **Currency Conversion**: Support for 150+ currencies
-
-## API Endpoints
-
-### REST API
-- `POST /api/gateway/authorize` - Authorize a payment
-- `POST /api/gateway/capture` - Capture an authorized payment
-- `POST /api/gateway/refund` - Process a refund
-- `GET /api/gateway/status/{transactionId}` - Get transaction status
-
-## Configuration
-
-```yaml
-payment_gateway:
-  providers:
-    stripe:
-      api_key: ${STRIPE_API_KEY}
-      webhook_secret: ${STRIPE_WEBHOOK_SECRET}
-    paypal:
-      client_id: ${PAYPAL_CLIENT_ID}
-      client_secret: ${PAYPAL_CLIENT_SECRET}
-  retry:
-    max_attempts: 3
-    backoff_ms: 1000
-```
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/containers/payment-cache/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/containers/payment-cache/index.mdx
deleted file mode 100644
index 2aa046201..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/containers/payment-cache/index.mdx
+++ /dev/null
@@ -1,158 +0,0 @@
----
-id: payment-cache
-name: Payment Cache
-version: 0.0.1
-container_type: cache
-technology: redis@7
-access_mode: readWrite
-classification: internal
-retention: 24h
-residency: eu-west-1
-summary: High-performance cache for payment session data and idempotency checks
----
-
-<NodeGraph />
-
-### What is this?
-Payment Cache is a Redis 7 cluster used for caching payment session data, rate limiting, and idempotency key tracking. It provides sub-millisecond latency for payment processing flows and reduces load on the primary database.
-
-### What does it store?
-- **Payment Sessions**: Temporary payment context during checkout (15-minute TTL)
-- **Idempotency Keys**: Fast duplicate payment prevention (24-hour TTL)
-- **Rate Limiting Counters**: Per-customer payment attempt limits
-- **Payment Method Cache**: Recently used payment methods (1-hour TTL)
-- **Gateway Status**: Payment gateway health check results (5-minute TTL)
-
-### Who writes to it?
-- **PaymentService** writes session data, idempotency keys, and cached payment methods
-- **PaymentGatewayService** updates gateway health status
-- **FraudDetectionService** writes rate limiting counters
-
-### Who reads from it?
-- **PaymentService** reads session data and checks idempotency keys before processing
-- **FraudDetectionService** reads rate limiting counters for risk assessment
-- **Frontend APIs** check payment session validity
-
-### Key patterns and structure
-```redis
-# Payment session keys (TTL: 15 minutes)
-payment:session:{session_id} -> {
-  "customer_id": "uuid",
-  "order_id": "uuid",
-  "amount_cents": 9999,
-  "currency": "USD",
-  "payment_method_id": "uuid",
-  "created_at": "2024-01-15T10:30:00Z"
-}
-
-# Idempotency keys (TTL: 24 hours)
-payment:idempotency:{idempotency_key} -> {payment_id}
-
-# Rate limiting (TTL: 1 hour)
-payment:ratelimit:{customer_id}:hour -> count
-payment:ratelimit:{customer_id}:day -> count
-
-# Payment method cache (TTL: 1 hour)
-payment:method:{payment_method_id} -> {
-  "type": "CARD",
-  "last_four": "4242",
-  "brand": "VISA",
-  "customer_id": "uuid"
-}
-
-# Gateway health status (TTL: 5 minutes)
-payment:gateway:{gateway_name}:status -> "UP" | "DOWN" | "DEGRADED"
-```
-
-### Common operations
-```javascript
-// Create payment session
-await redis.setex(
-  `payment:session:${sessionId}`,
-  900, // 15 minutes
-  JSON.stringify(sessionData)
-);
-
-// Check idempotency key
-const existingPaymentId = await redis.get(`payment:idempotency:${key}`);
-if (existingPaymentId) {
-  return { duplicate: true, paymentId: existingPaymentId };
-}
-
-// Set idempotency key
-await redis.setex(`payment:idempotency:${key}`, 86400, paymentId);
-
-// Increment rate limit counter
-const attempts = await redis.incr(`payment:ratelimit:${customerId}:hour`);
-if (attempts === 1) {
-  await redis.expire(`payment:ratelimit:${customerId}:hour`, 3600);
-}
-if (attempts > 10) {
-  throw new RateLimitError('Too many payment attempts');
-}
-
-// Cache payment method
-await redis.setex(
-  `payment:method:${methodId}`,
-  3600,
-  JSON.stringify(paymentMethod)
-);
-```
-
-### Configuration
-- **Cluster mode**: Enabled for high availability (3 primary + 3 replica nodes)
-- **Eviction policy**: `allkeys-lru` (automatically evict least recently used keys)
-- **Max memory**: 4GB per node
-- **Persistence**: AOF disabled (cache data is ephemeral)
-- **Connection pooling**: Min 10, Max 50 connections per service instance
-
-### Access patterns and guidance
-- Always set appropriate TTLs to prevent memory bloat
-- Use Redis Cluster key hashing for scalability
-- Idempotency checks must be atomic (use `SETNX` or Lua scripts)
-- Rate limiting uses `INCR` with `EXPIRE` for atomic counters
-- Payment sessions should be invalidated on completion or expiry
-
-### Monitoring and alerts
-- Cache hit rate monitored (target: > 85%)
-- Memory usage alerts at 80% capacity
-- Connection pool exhaustion alerts
-- Slow command alerts (> 10ms)
-- Replication lag monitoring (target: < 1 second)
-
-### High availability
-- Multi-AZ deployment across 3 availability zones
-- Automatic failover with Redis Sentinel
-- Read replicas for read-heavy operations
-- Connection retry logic in application code
-
-### Security
-- Redis AUTH enabled with strong password rotation
-- TLS encryption for all connections
-- VPC isolation - no public internet access
-- Network ACLs restrict access to payment services only
-
-### Backup and disaster recovery
-- No persistent backups (cache data is ephemeral and can be rebuilt)
-- Cluster configuration backed up for rapid rebuild
-- Runbooks for cache warmup after total failure
-
-### Local development
-- Connection string: `PAYMENT_CACHE_URL` environment variable
-- Local Redis via Docker: `docker run -d -p 6379:6379 redis:7-alpine`
-- Test data can be seeded via `npm run seed:payment-cache`
-
-### Common issues and troubleshooting
-- **Cache misses on payment sessions**: Check TTL configuration, may need adjustment for slow checkouts
-- **Idempotency key collisions**: Ensure clients generate unique keys (recommend UUID v4)
-- **Rate limiting false positives**: Review rate limit thresholds, may need per-tier limits
-- **Memory pressure**: Monitor eviction rates, consider increasing cluster size
-- **Connection timeouts**: Check connection pool settings and network latency
-
-### Performance characteristics
-- **Read latency**: p99 < 5ms
-- **Write latency**: p99 < 10ms
-- **Throughput**: 50,000+ ops/sec per node
-- **TTL precision**: 1-second granularity
-
-For more information, see the PaymentService caching strategy documentation.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/containers/payments-db/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/containers/payments-db/index.mdx
deleted file mode 100644
index 356191794..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/containers/payments-db/index.mdx
+++ /dev/null
@@ -1,155 +0,0 @@
----
-id: payments-db
-name: Payments DB
-version: 0.0.1
-container_type: database
-technology: postgres@15
-authoritative: true
-access_mode: readWrite
-classification: regulated
-retention: 10y
-residency: eu-west-1
-summary: Primary database for payment transactions and payment method records
----
-
-<NodeGraph />
-
-### What is this?
-Payments DB is the authoritative database for all payment transactions, payment methods, and related financial data. It uses PostgreSQL 15 and serves as the system of record for payment processing, refunds, and transaction history.
-
-### What does it store?
-- **Payments**: Transaction records including amount, currency, status, timestamps, and gateway references
-- **Payment Methods**: Tokenized payment method details (cards, bank accounts) with PCI-compliant storage
-- **Refunds**: Refund records linked to original payment transactions
-- **Payment Attempts**: Historical record of all payment attempts for debugging and analytics
-- **Relationships**: Payment methods belong to customers, payments reference orders and payment methods
-
-### Who writes to it?
-- **PaymentService** creates payment records, processes transactions, and manages payment methods
-- **PaymentGatewayService** updates payment status based on gateway responses
-- Transaction records are immutable after settlement for audit compliance
-
-### Who reads from it?
-- **FraudDetectionService** analyzes payment patterns and transaction history
-- **BillingService** retrieves payment history for invoice generation
-- **OrdersService** checks payment status for order fulfillment
-- **SubscriptionService** validates payment methods for recurring charges
-- **Finance/Analytics** teams for reconciliation and reporting
-
-### High-level data model
-- A `payment` belongs to an `order` and uses a `payment_method`
-- Payment lifecycle tracked via `status`: `INITIATED`, `AUTHORIZED`, `CAPTURED`, `FAILED`, `REFUNDED`, `CANCELLED`
-- Monetary values stored as integer cents to avoid floating-point issues
-- All transactions are idempotent using `idempotency_key`
-- Tables: `payments`, `payment_methods`, `refunds`
-
-### Common queries
-```sql
--- Get payment details with method info
-SELECT p.*, pm.type AS payment_method_type, pm.last_four, pm.brand
-FROM payments p
-LEFT JOIN payment_methods pm USING (payment_method_id)
-WHERE p.payment_id = $1;
-
--- List customer payments (for payment history)
-SELECT *
-FROM payments
-WHERE customer_id = $1
-ORDER BY created_at DESC
-LIMIT $2 OFFSET $3;
-
--- Find failed payments for retry analysis
-SELECT payment_id, order_id, failure_reason, created_at
-FROM payments
-WHERE status = 'FAILED'
-  AND created_at >= now() - interval '24 hours'
-ORDER BY created_at DESC;
-
--- Calculate daily payment volume
-SELECT date_trunc('day', captured_at) AS day,
-       COUNT(*) AS transaction_count,
-       SUM(amount_cents)/100.0 AS total_amount
-FROM payments
-WHERE status = 'CAPTURED'
-  AND captured_at >= now() - interval '30 days'
-GROUP BY 1
-ORDER BY 1;
-```
-
-### Lifecycle and data flow
-1. Customer initiates payment → `PaymentService` creates record with status `INITIATED`
-2. Payment gateway authorization → status updated to `AUTHORIZED`
-3. Capture after order fulfillment → status updated to `CAPTURED`
-4. Refunds create separate `refunds` record linked to original payment
-5. All state changes emit domain events for downstream consumers
-
-### Security and compliance
-- **PCI DSS Level 1 compliance**: Card data tokenized via payment gateway, no raw card numbers stored
-- **Encryption at rest**: Database encrypted using AWS KMS
-- **Encryption in transit**: TLS 1.3 for all connections
-- **Access control**: Role-based access, audit logging enabled
-- **PII handling**: Customer PII encrypted, access logged for GDPR compliance
-
-### Access patterns and guidance
-- Use `payment_id` for point lookups; indexed by `order_id` and `customer_id`
-- Query by `idempotency_key` to prevent duplicate charges
-- Payments are immutable after `CAPTURED` status - use refunds for reversals
-- Never store raw card numbers - always use gateway tokens
-- Use read replicas for analytics queries to avoid impacting transaction processing
-
-### Retention and residency
-- **Retention**: 10 years (regulatory requirement for financial records)
-- **Residency**: `eu-west-1` (GDPR compliance, data localization)
-- Archived records older than 3 years moved to cold storage
-
-### Backups and recovery
-- Automated continuous backups with 35-day retention
-- Point-in-time recovery with 5-minute RPO
-- Cross-region backup replication for disaster recovery
-- Monthly restore testing to validate RTO objectives
-
-### Monitoring and alerts
-- Transaction latency monitored (p99 < 200ms)
-- Failed payment rate alerts (threshold: > 5%)
-- Database connection pool monitoring
-- Slow query alerts for queries > 1 second
-
-### Requesting access
-To request access to the Payments DB:
-
-1. **Development/Staging access**:
-   - Submit an access request via [ServiceNow](https://company.service-now.com)
-   - Select "Database Access Request" → "Payments DB (Non-Production)"
-   - Specify read-only or read-write access level
-   - Approval required from Payment Service team lead
-   - Access granted within 24 hours
-
-2. **Production access**:
-   - Production read access requires manager approval + security review
-   - Production write access is restricted to PaymentService automated deployments only
-   - For emergency production access, contact on-call via PagerDuty
-   - All production queries are logged and audited for compliance
-
-3. **Analytics/Reporting access**:
-   - Use the read-replica endpoint for reporting queries
-   - Request access via #payments-data Slack channel
-   - Data export requests require data governance approval due to PCI/GDPR
-
-**Contact**: For questions, contact the Payment Service team:
-- Slack: #payments-team
-- Email: payments-team@company.com
-- Team lead: @dboyne
-
-### Local development
-- Connection string: `PAYMENTS_DB_URL` environment variable
-- Seed data available via `npm run seed:payments`
-- Test payment methods use gateway test tokens
-- Local development uses Docker: `docker-compose up payments-db`
-
-### Common issues and troubleshooting
-- **Duplicate payments**: Always include `idempotency_key` in payment creation
-- **Stuck authorizations**: Run daily job to release authorizations older than 7 days
-- **Gateway timeouts**: Implement retry logic with exponential backoff
-- **Currency mismatches**: Validate order currency matches payment currency
-
-For more information, see the PaymentService documentation and PCI compliance guidelines.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/events/PaymentComplete/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/events/PaymentComplete/index.mdx
deleted file mode 100644
index 1f72d1fe0..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/events/PaymentComplete/index.mdx
+++ /dev/null
@@ -1,37 +0,0 @@
----
-id: PaymentComplete
-name: Payment Complete
-version: 0.0.2
-summary: Event is triggered when a user completes a payment through the Payment Service
-owners:
-  - dboyne
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The Payment Complete event is triggered when a user successfully completes a payment through the Payment Service. This event signifies the end of the payment process and confirms that the payment has been processed successfully.
-
-<NodeGraph />
-
-### Payload Example
-
-```json 
-{
-  "userId": "123e4567-e89b-12d3-a456-426614174000",
-  "orderId": "789e1234-b56c-78d9-e012-3456789fghij",
-  "amount": 100.50,
-  "paymentMethod": "CreditCard",
-  "timestamp": "2024-07-04T14:48:00Z",
-  "status": "Completed"
-}
-```
-
-### Security Considerations
-
-- **Authentication**: Ensure that only authenticated users can complete a payment, and the userId in the payload matches the authenticated user.
-- **Data Validation**: Validate all input data to prevent injection attacks or other malicious input.
-- **Sensitive Data Handling**: Avoid including sensitive information (e.g., credit card numbers) in the event payload. Use secure channels and encryption for such data.
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/events/PaymentInitiated/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/events/PaymentInitiated/index.mdx
deleted file mode 100644
index 63cbb32f2..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/events/PaymentInitiated/index.mdx
+++ /dev/null
@@ -1,36 +0,0 @@
----
-id: PaymentInitiated
-name: Payment Initiated
-version: 0.0.1
-summary: Event is triggered when a user initiates a payment through the Payment Service
-owners:
-  - dboyne
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The Payment Initiated event is triggered when a user initiates a payment through the Payment Service. This event signifies the beginning of the payment process and contains all necessary information to process the payment.
-
-<NodeGraph />
-
-### Payload Example
-
-```json 
-{
-  "userId": "123e4567-e89b-12d3-a456-426614174000",
-  "orderId": "789e1234-b56c-78d9-e012-3456789fghij",
-  "amount": 100.50,
-  "paymentMethod": "CreditCard",
-  "timestamp": "2024-07-04T14:48:00Z"
-}
-```
-
-### Security Considerations
-
-- **Authentication**: Ensure that only authenticated users can initiate a payment, and the userId in the payload matches the authenticated user.
-- **Data Validation**: Validate all input data to prevent injection attacks or other malicious input.
-- **Sensitive Data Handling**: Avoid including sensitive information (e.g., credit card numbers) in the event payload. Use secure channels and encryption for such data.
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/events/PaymentProcessed/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/events/PaymentProcessed/index.mdx
deleted file mode 100644
index 26998397f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/events/PaymentProcessed/index.mdx
+++ /dev/null
@@ -1,42 +0,0 @@
----
-id: PaymentProcessed
-name: Payment Processed
-version: 1.0.0
-summary: Event is triggered after the payment has been successfully processed
-owners:
-  - dboyne
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The PaymentProcessed event is triggered after the payment has been successfully processed by the Payment Service. This event signifies that a payment has been confirmed, and it communicates the outcome to other services and components within the system.
-
-<NodeGraph />
-
-### Payload Example
-
-```json 
-{
-  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
-  "userId": "123e4567-e89b-12d3-a456-426614174000",
-  "orderId": "789e1234-b56c-78d9-e012-3456789fghij",
-  "amount": 100.50,
-  "paymentMethod": "CreditCard",
-  "status": "confirmed",
-  "confirmationDetails": {
-    "gatewayResponse": "Approved",
-    "transactionId": "abc123"
-  },
-  "timestamp": "2024-07-04T14:48:00Z"
-}
-```
-
-### Security Considerations
-
-- **Data Validation**: Ensure that all data in the event payload is validated before publishing to prevent injection attacks or other malicious activities.
-- **Sensitive Data Handling**: Avoid including sensitive information (e.g., full credit card numbers) in the event payload. Use secure channels and encryption for such data.
-- **Authentication and Authorization**: Ensure that only authorized services can publish or consume PaymentProcessed events.
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/events/PaymentProcessed/versioned/0.0.1/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/events/PaymentProcessed/versioned/0.0.1/index.mdx
deleted file mode 100644
index 7c7eeed7c..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/events/PaymentProcessed/versioned/0.0.1/index.mdx
+++ /dev/null
@@ -1,42 +0,0 @@
----
-id: PaymentProcessed
-name: Payment Processed
-version: 0.0.1
-summary: Event is triggered after the payment has been successfully processed
-owners:
-    - dboyne
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The PaymentProcessed event is triggered after the payment has been successfully processed by the Payment Service. This event signifies that a payment has been confirmed, and it communicates the outcome to other services and components within the system.
-
-<NodeGraph />
-
-### Payload Example
-
-```json 
-{
-  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
-  "userId": "123e4567-e89b-12d3-a456-426614174000",
-  "orderId": "789e1234-b56c-78d9-e012-3456789fghij",
-  "amount": 100.50,
-  "paymentMethod": "CreditCard",
-  "status": "confirmed",
-  "confirmationDetails": {
-    "gatewayResponse": "Approved",
-    "transactionId": "abc123"
-  },
-  "timestamp": "2024-07-04T14:48:00Z"
-}
-```
-
-### Security Considerations
-
-- **Data Validation**: Ensure that all data in the event payload is validated before publishing to prevent injection attacks or other malicious activities.
-- **Sensitive Data Handling**: Avoid including sensitive information (e.g., full credit card numbers) in the event payload. Use secure channels and encryption for such data.
-- **Authentication and Authorization**: Ensure that only authorized services can publish or consume PaymentProcessed events.
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/index.mdx
deleted file mode 100644
index b8dfa43d2..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/index.mdx
+++ /dev/null
@@ -1,76 +0,0 @@
----
-id: PaymentService
-name: Payment Service
-version: 0.0.1
-summary: |
-  Service that handles payments
-owners:
-  - dboyne
-receives:
-  - id: PaymentInitiated
-    version: 0.0.1
-    from:
-      - id: 'payments.{env}.events'
-        parameters:
-          env: staging
-sends:
-  - id: PaymentProcessed
-writesTo:
-  - id: payments-db
-    version: 0.0.1
-  - id: payment-cache
-    version: 0.0.1
-readsFrom:
-  - id: order-metadata-store
-    version: 0.0.1
-  - id: payments-db
-    version: 0.0.1
-  - id: payment-cache
-    version: 0.0.1
-repository:
-  language: JavaScript
-  url: 'https://github.com/event-catalog/pretend-shipping-service'
----
-
-The Payment Service is a crucial component of our system that handles all payment-related operations. It processes payments, manages transactions, and communicates with other services through events. Using an event-driven architecture, it ensures that all actions are asynchronous, decoupled, and scalable.
-
-### Core features
-
-| Feature | Description |
-|---------|-------------|
-| Payment Processing | Processes payments and manages transactions |
-| Event-Driven Architecture | Ensures asynchronous, decoupled, and scalable operations |
-| Integration with Payment Gateways | Interfaces with external payment providers |
-
-<NodeGraph />
-
-<MessageTable format="all" limit={4} />
-
-## Infrastructure
-
-The Payment Service is hosted on AWS.
-
-The diagram below shows the infrastructure of the Payment Service. The service is hosted on AWS and uses AWS Lambda to handle the payment requests. The payment is stored in an AWS Aurora database and the payment metadata is stored in an AWS S3 bucket.
-
-```mermaid
-architecture-beta
-    group api(logos:aws)
-
-    service db(logos:aws-aurora)[Payment DB] in api
-    service disk1(logos:aws-s3)[Payment Metadata] in api
-    service server(logos:aws-lambda)[Payment Handler] in api
-
-    db:L -- R:server
-    disk1:T -- B:server
-```
-
-You can find more information about the Payment Service infrastructure in the [Payment Service documentation](https://github.com/event-catalog/pretend-payment-service/blob/main/README.md).
-
-### Key Components
-- Payment API: Exposes endpoints for initiating payments and querying payment status.
-- Payment Processor: Handles the core payment processing logic.
-- Event Bus: Manages the communication between services using events.
-- Payment Gateway: Interfaces with external payment providers.
-- Transaction Service: Manages transaction records and states.
-- Notification Service: Sends notifications related to payment status changes.
-- Database: Stores transaction data and payment status.
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/queries/GetPaymentStatus/index.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/queries/GetPaymentStatus/index.mdx
deleted file mode 100644
index 8d1679a97..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/queries/GetPaymentStatus/index.mdx
+++ /dev/null
@@ -1,28 +0,0 @@
----
-id: GetPaymentStatus
-name: Get payment status
-version: 0.0.1
-summary: |
-  GET request that will return the payment status for a specific order, identified by its orderId.
-owners:
-    - dboyne
-badges:
-    - content: Recently updated!
-      backgroundColor: green
-      textColor: green
-schemaPath: schema.json
-sidebar:
-  badge: 'GET'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `GetPaymentStatus` message is a query used to retrieve the payment status for a specific order, identified by its `orderId`. This query returns the current status of the payment, such as whether it is pending, completed, failed, or refunded. It is used by systems that need to track the lifecycle of payments associated with orders, ensuring that the payment has been successfully processed or identifying if any issues occurred during the transaction.
-
-This query is useful in scenarios such as order management, refund processing, or payment auditing, ensuring that users or systems have real-time visibility into the payment status for a given order.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/queries/GetPaymentStatus/schema.json b/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/queries/GetPaymentStatus/schema.json
deleted file mode 100644
index 3ee0a321e..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/services/PaymentService/queries/GetPaymentStatus/schema.json
+++ /dev/null
@@ -1,40 +0,0 @@
-
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "GetPaymentStatusResponse",
-  "type": "object",
-  "properties": {
-    "orderId": {
-      "type": "string",
-      "description": "The unique identifier for the order."
-    },
-    "paymentStatus": {
-      "type": "string",
-      "enum": ["pending", "completed", "failed", "refunded"],
-      "description": "The current payment status of the order."
-    },
-    "amount": {
-      "type": "number",
-      "description": "The amount paid for the order."
-    },
-    "currency": {
-      "type": "string",
-      "description": "The currency in which the payment was made (e.g., USD, EUR)."
-    },
-    "paymentMethod": {
-      "type": "string",
-      "description": "The payment method used for the transaction (e.g., Credit Card, PayPal)."
-    },
-    "transactionId": {
-      "type": "string",
-      "description": "The unique identifier for the payment transaction."
-    },
-    "paymentDate": {
-      "type": "string",
-      "format": "date-time",
-      "description": "The date and time when the payment was processed."
-    }
-  },
-  "required": ["orderId", "paymentStatus", "amount", "currency", "paymentMethod", "transactionId", "paymentDate"],
-  "additionalProperties": false
-}
diff --git a/examples/default/domains/E-Commerce/subdomains/Payment/ubiquitous-language.mdx b/examples/default/domains/E-Commerce/subdomains/Payment/ubiquitous-language.mdx
deleted file mode 100644
index 85eec09bf..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Payment/ubiquitous-language.mdx
+++ /dev/null
@@ -1,96 +0,0 @@
----
-dictionary:
-  - id: Transaction
-    name: Transaction
-    summary: "The process of transferring funds from one party to another."
-    icon: CreditCard
-  - id: Invoice
-    name: Invoice
-    summary: "A document issued by a seller to a buyer, listing goods or services provided and the amount due."
-    description: |
-      Invoices are critical for financial transactions, serving as a request for payment from the buyer. They include:
-
-      - Invoice number for tracking
-      - List of products or services provided
-      - Total amount due and payment terms
-      - Seller and buyer contact information
-      - Due date for payment
-
-      Invoices are essential for accounting, tax purposes, and maintaining cash flow.
-    icon: CreditCard
-  - id: Payment Method
-    name: Payment Method
-    summary: "The means by which a payment is made, such as credit card or bank transfer."
-    description: |
-      Payment methods are the various ways customers can pay for goods or services. Common methods include:
-
-      - Credit and debit cards
-      - Bank transfers
-      - Digital wallets
-      - Cash on delivery
-
-      Offering multiple payment methods can enhance customer satisfaction and increase sales.
-    icon: Wallet
-  - id: Receipt
-    name: Receipt
-    summary: "A document acknowledging that a payment has been made."
-    description: |
-      Receipts serve as proof of payment and are important for record-keeping. They typically include:
-
-      - Receipt number
-      - Date and time of payment
-      - Amount paid
-      - Payment method used
-      - Details of the transaction
-
-      Receipts are essential for both customers and businesses to track financial transactions.
-    icon: Receipt
-  - id: Refund
-    name: Refund
-    summary: "The process of returning funds to a customer for a returned product or service."
-    description: |
-      Refunds are issued when a customer returns a product or cancels a service. The process involves:
-
-      - Verifying the return or cancellation
-      - Processing the refund through the original payment method
-      - Updating financial records
-
-      Efficient refund processes can improve customer satisfaction and loyalty.
-    icon: RotateCcw
-  - id: Currency
-    name: Currency
-    summary: "The system of money in general use in a particular country."
-    description: |
-      Currency is the medium of exchange for goods and services. Key aspects include:
-
-      - Currency code (e.g., USD, EUR)
-      - Exchange rates
-      - Currency symbols
-
-      Understanding currency is crucial for international transactions and financial reporting.
-    icon: DollarSign
-  - id: Payment Gateway
-    name: Payment Gateway
-    summary: "A service that authorizes and processes payments for online and offline transactions."
-    description: |
-      Payment gateways facilitate the transfer of payment information between the customer and the merchant. They ensure secure and efficient transactions by:
-
-      - Encrypting sensitive data
-      - Authorizing payments
-      - Providing transaction reports
-
-      Choosing a reliable payment gateway is essential for business operations.
-    icon: Server
-  - id: Chargeback
-    name: Chargeback
-    summary: "A demand by a credit card provider for a retailer to make good the loss on a fraudulent or disputed transaction."
-    description: |
-      Chargebacks occur when a customer disputes a transaction, and the funds are returned to their account. The process involves:
-
-      - Investigating the dispute
-      - Providing evidence to the payment processor
-      - Resolving the issue with the customer
-
-      Managing chargebacks effectively can prevent financial losses and maintain customer trust.
-    icon: AlertCircle
----
diff --git a/examples/default/domains/E-Commerce/subdomains/ProductCatalog/entities/Category/index.mdx b/examples/default/domains/E-Commerce/subdomains/ProductCatalog/entities/Category/index.mdx
deleted file mode 100644
index c6691a44f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/ProductCatalog/entities/Category/index.mdx
+++ /dev/null
@@ -1,124 +0,0 @@
----
-id: Category
-name: Category
-version: 1.0.0
-identifier: categoryId
-aggregateRoot: true
-summary: Represents a product category with hierarchical structure support.
-properties:
-  - name: categoryId
-    type: UUID
-    required: true
-    description: Unique identifier for the category
-  - name: name
-    type: string
-    required: true
-    description: Name of the category
-  - name: description
-    type: string
-    required: false
-    description: Description of the category
-  - name: slug
-    type: string
-    required: true
-    description: URL-friendly identifier for the category
-  - name: parentCategoryId
-    type: UUID
-    required: false
-    description: Parent category for hierarchical structure
-    references: Category
-    referencesIdentifier: categoryId
-    relationType: hasOne
-  - name: childCategories
-    type: array
-    items:
-      type: Category
-    required: false
-    description: Subcategories under this category
-    references: Category
-    referencesIdentifier: parentCategoryId
-    relationType: hasMany
-  - name: level
-    type: integer
-    required: true
-    description: Depth level in the category hierarchy (0 = root)
-  - name: isActive
-    type: boolean
-    required: true
-    description: Whether the category is currently active
-  - name: sortOrder
-    type: integer
-    required: false
-    description: Display order within the same level
-  - name: icon
-    type: string
-    required: false
-    description: Icon URL or identifier for the category
-  - name: imageUrl
-    type: string
-    required: false
-    description: Category banner or thumbnail image
-  - name: seoTitle
-    type: string
-    required: false
-    description: SEO-optimized title for the category page
-  - name: seoDescription
-    type: string
-    required: false
-    description: SEO meta description for the category page
-  - name: products
-    type: array
-    items:
-      type: Product
-    required: false
-    description: Products belonging to this category
-    references: Product
-    referencesIdentifier: categoryId
-    relationType: hasMany
-  - name: createdAt
-    type: DateTime
-    required: true
-    description: Date and time when the category was created
-  - name: updatedAt
-    type: DateTime
-    required: false
-    description: Date and time when the category was last updated
----
-
-## Overview
-
-The Category entity organizes products into a hierarchical structure, supporting multi-level categorization. It enables efficient product discovery and navigation through the e-commerce catalog.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-* **Parent Category:** Each category can have one parent `Category` (identified by `parentCategoryId`).
-* **Child Categories:** A category can have multiple child `Category` entities creating a hierarchy.
-* **Products:** A category contains multiple `Product` entities (identified by `categoryId`).
-
-## Hierarchy Examples
-
-```
-Electronics (Level 0)
-├── Computers (Level 1)
-│   ├── Laptops (Level 2)
-│   ├── Desktops (Level 2)
-│   └── Tablets (Level 2)
-├── Mobile Phones (Level 1)
-│   ├── Smartphones (Level 2)
-│   └── Feature Phones (Level 2)
-└── Audio (Level 1)
-    ├── Headphones (Level 2)
-    └── Speakers (Level 2)
-```
-
-## Business Rules
-
-* Root categories have `parentCategoryId` as null and `level` as 0
-* Child categories must have a valid `parentCategoryId`
-* Category slugs must be unique across the entire catalog
-* Categories cannot be deleted if they contain products or subcategories
-* Inactive categories should hide all associated products from public view
-* Maximum hierarchy depth should be limited (e.g., 5 levels)
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/ProductCatalog/entities/Inventory/index.mdx b/examples/default/domains/E-Commerce/subdomains/ProductCatalog/entities/Inventory/index.mdx
deleted file mode 100644
index 6c7707db9..000000000
--- a/examples/default/domains/E-Commerce/subdomains/ProductCatalog/entities/Inventory/index.mdx
+++ /dev/null
@@ -1,116 +0,0 @@
----
-id: Inventory
-name: Inventory
-version: 1.0.0
-identifier: inventoryId
-summary: Tracks stock levels and availability for products.
-properties:
-  - name: inventoryId
-    type: UUID
-    required: true
-    description: Unique identifier for the inventory record
-  - name: productId
-    type: UUID
-    required: true
-    description: Product this inventory record tracks
-    references: Product
-    referencesIdentifier: productId
-    relationType: hasOne
-  - name: sku
-    type: string
-    required: true
-    description: Stock Keeping Unit matching the product SKU
-  - name: quantityOnHand
-    type: integer
-    required: true
-    description: Current available stock quantity
-  - name: quantityReserved
-    type: integer
-    required: true
-    description: Quantity reserved for pending orders
-  - name: quantityAvailable
-    type: integer
-    required: true
-    description: Calculated available quantity (onHand - reserved)
-  - name: minimumStockLevel
-    type: integer
-    required: true
-    description: Minimum stock level before reorder alert
-  - name: maximumStockLevel
-    type: integer
-    required: false
-    description: Maximum stock level for inventory management
-  - name: reorderPoint
-    type: integer
-    required: true
-    description: Stock level that triggers reorder process
-  - name: reorderQuantity
-    type: integer
-    required: true
-    description: Quantity to order when restocking
-  - name: unitCost
-    type: decimal
-    required: false
-    description: Cost per unit for inventory valuation
-  - name: warehouseLocation
-    type: string
-    required: false
-    description: Physical location or bin where item is stored
-  - name: lastRestockedAt
-    type: DateTime
-    required: false
-    description: Date and time of last restock
-  - name: lastSoldAt
-    type: DateTime
-    required: false
-    description: Date and time of last sale
-  - name: isTrackingEnabled
-    type: boolean
-    required: true
-    description: Whether inventory tracking is enabled for this product
-  - name: backorderAllowed
-    type: boolean
-    required: true
-    description: Whether backorders are allowed when out of stock
-  - name: createdAt
-    type: DateTime
-    required: true
-    description: Date and time when the inventory record was created
-  - name: updatedAt
-    type: DateTime
-    required: false
-    description: Date and time when the inventory record was last updated
----
-
-## Overview
-
-The Inventory entity manages stock levels and availability for products in the e-commerce system. It tracks current quantities, reserved stock, and provides reorder management capabilities.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-* **Product:** Each inventory record belongs to one `Product` (identified by `productId`).
-* **OrderItem:** Inventory quantities are affected by `OrderItem` entities when orders are placed.
-
-## Stock Calculations
-
-* **Available Quantity** = Quantity On Hand - Quantity Reserved
-* **Reorder Needed** = Quantity Available &lt;= Reorder Point
-* **Stock Value** = Quantity On Hand × Unit Cost
-
-## Examples
-
-* **Inventory #1:** iPhone 15 Pro - 25 on hand, 5 reserved, 20 available, reorder at 10 units.
-* **Inventory #2:** Running Shoes Size 9 - 0 on hand, 2 reserved, backorder allowed.
-
-## Business Rules
-
-* Quantity on hand cannot be negative
-* Quantity reserved cannot exceed quantity on hand
-* Available quantity is automatically calculated
-* Reorder alerts are triggered when available = reorder point
-* Stock reservations are created when orders are placed
-* Stock is decremented when orders are shipped
-* Inventory adjustments must be logged for audit trail
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/ProductCatalog/entities/Product/index.mdx b/examples/default/domains/E-Commerce/subdomains/ProductCatalog/entities/Product/index.mdx
deleted file mode 100644
index 59738ca8f..000000000
--- a/examples/default/domains/E-Commerce/subdomains/ProductCatalog/entities/Product/index.mdx
+++ /dev/null
@@ -1,115 +0,0 @@
----
-id: Product
-name: Product
-version: 1.0.0
-identifier: productId
-aggregateRoot: true
-summary: Represents a product or service available for purchase in the e-commerce system.
-properties:
-  - name: productId
-    type: UUID
-    required: true
-    description: Unique identifier for the product
-  - name: name
-    type: string
-    required: true
-    description: Name of the product
-  - name: description
-    type: string
-    required: false
-    description: Detailed description of the product
-  - name: sku
-    type: string
-    required: true
-    description: Stock Keeping Unit - unique product identifier
-  - name: price
-    type: decimal
-    required: true
-    description: Current selling price of the product
-  - name: categoryId
-    type: UUID
-    required: true
-    description: Category this product belongs to
-    references: Category
-    referencesIdentifier: categoryId
-    relationType: hasOne
-  - name: brand
-    type: string
-    required: false
-    description: Brand name of the product
-  - name: weight
-    type: decimal
-    required: false
-    description: Weight of the product in kilograms
-  - name: dimensions
-    type: object
-    required: false
-    description: Product dimensions (length, width, height)
-    properties:
-      - name: length
-        type: decimal
-      - name: width
-        type: decimal
-      - name: height
-        type: decimal
-  - name: isActive
-    type: boolean
-    required: true
-    description: Whether the product is currently available for sale
-  - name: createdAt
-    type: DateTime
-    required: true
-    description: Date and time when the product was created
-  - name: updatedAt
-    type: DateTime
-    required: false
-    description: Date and time when the product was last updated
-  - name: images
-    type: array
-    items:
-      type: string
-    required: false
-    description: URLs of product images
-  - name: inventory
-    type: Inventory
-    required: false
-    description: Inventory information for this product
-    references: Inventory
-    referencesIdentifier: productId
-    relationType: hasOne
-  - name: reviews
-    type: array
-    items:
-      type: Review
-    required: false
-    description: Customer reviews for this product
-    references: Review
-    referencesIdentifier: productId
-    relationType: hasMany
----
-
-## Overview
-
-The Product entity represents items or services available for purchase in the e-commerce system. It serves as an aggregate root containing all product-related information including pricing, categorization, inventory details, and customer reviews.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-* **Category:** Each product belongs to one `Category` (identified by `categoryId`).
-* **Inventory:** Each product has one `Inventory` record tracking stock levels.
-* **Review:** A product can have multiple `Review` entities from customers.
-* **OrderItem:** Products are referenced in `OrderItem` entities when included in orders.
-
-## Examples
-
-* **Product #1:** "iPhone 15 Pro" - Electronics category, $999.99, with 50 units in stock and 4.5-star reviews.
-* **Product #2:** "Running Shoes" - Sports category, $129.99, various sizes available, with detailed size chart.
-
-## Business Rules
-
-* Products must have a unique SKU across the entire catalog
-* Products cannot be deleted if they have associated order items
-* Price changes should be tracked for audit purposes
-* Products must belong to an active category to be purchasable
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/ProductCatalog/entities/Review/index.mdx b/examples/default/domains/E-Commerce/subdomains/ProductCatalog/entities/Review/index.mdx
deleted file mode 100644
index 4b5d0b2f2..000000000
--- a/examples/default/domains/E-Commerce/subdomains/ProductCatalog/entities/Review/index.mdx
+++ /dev/null
@@ -1,154 +0,0 @@
----
-id: Review
-name: Review
-version: 1.0.0
-identifier: reviewId
-summary: Represents customer reviews and ratings for products.
-properties:
-  - name: reviewId
-    type: UUID
-    required: true
-    description: Unique identifier for the review
-  - name: productId
-    type: UUID
-    required: true
-    description: Product being reviewed
-    references: Product
-    referencesIdentifier: productId
-    relationType: hasOne
-  - name: customerId
-    type: UUID
-    required: true
-    description: Customer who wrote the review
-    references: Customer
-    referencesIdentifier: customerId
-    relationType: hasOne
-  - name: orderId
-    type: UUID
-    required: false
-    description: Order associated with this review (for verified purchases)
-    references: Order
-    referencesIdentifier: orderId
-    relationType: hasOne
-  - name: rating
-    type: integer
-    required: true
-    description: Rating given by customer (1-5 stars)
-    minimum: 1
-    maximum: 5
-  - name: title
-    type: string
-    required: false
-    description: Review title or headline
-  - name: content
-    type: string
-    required: true
-    description: Review content and comments
-  - name: isVerifiedPurchase
-    type: boolean
-    required: true
-    description: Whether this review is from a verified purchase
-  - name: isRecommended
-    type: boolean
-    required: false
-    description: Whether customer recommends this product
-  - name: helpfulVotes
-    type: integer
-    required: true
-    description: Number of helpful votes received
-  - name: totalVotes
-    type: integer
-    required: true
-    description: Total number of votes received
-  - name: status
-    type: string
-    required: true
-    description: Current review status
-    enum: ['pending', 'approved', 'rejected', 'flagged']
-  - name: moderationNotes
-    type: string
-    required: false
-    description: Internal moderation notes
-  - name: images
-    type: array
-    items:
-      type: string
-    required: false
-    description: URLs of images uploaded with the review
-  - name: pros
-    type: array
-    items:
-      type: string
-    required: false
-    description: List of positive aspects mentioned
-  - name: cons
-    type: array
-    items:
-      type: string
-    required: false
-    description: List of negative aspects mentioned
-  - name: merchantResponse
-    type: object
-    required: false
-    description: Response from merchant to this review
-    properties:
-      - name: content
-        type: string
-        description: Merchant response content
-      - name: respondedAt
-        type: DateTime
-        description: When merchant responded
-      - name: respondedBy
-        type: string
-        description: Who responded for the merchant
-  - name: createdAt
-    type: DateTime
-    required: true
-    description: Date and time when the review was created
-  - name: updatedAt
-    type: DateTime
-    required: false
-    description: Date and time when the review was last updated
-  - name: moderatedAt
-    type: DateTime
-    required: false
-    description: Date and time when the review was moderated
----
-
-## Overview
-
-The Review entity captures customer feedback and ratings for products. It supports verified purchase validation, content moderation, community voting, and merchant responses to build trust and provide valuable product insights.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-* **Product:** Each review belongs to one `Product` (identified by `productId`).
-* **Customer:** Each review is written by one `Customer` (identified by `customerId`).
-* **Order:** Each review can be linked to one `Order` for purchase verification (identified by `orderId`).
-
-## Review Lifecycle
-
-```
-submitted → pending → approved → published
-              ↓         ↓
-           rejected   flagged
-```
-
-## Examples
-
-* **Review #1:** 5-star review for iPhone 15 Pro, verified purchase, "Excellent camera quality!"
-* **Review #2:** 3-star review for Running Shoes, helpful votes: 15/20, includes photos
-* **Review #3:** 1-star review flagged for inappropriate content, pending moderation
-
-## Business Rules
-
-* Reviews can only be submitted by customers who purchased the product
-* Rating must be between 1-5 stars
-* Verified purchase reviews are given higher weight in calculations
-* Inappropriate content is flagged and requires moderation
-* Customers can only review the same product once per purchase
-* Helpful votes help surface most valuable reviews
-* Merchant responses are limited to one per review
-* Reviews older than 2 years may have reduced weight in calculations
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/ProductCatalog/index.mdx b/examples/default/domains/E-Commerce/subdomains/ProductCatalog/index.mdx
deleted file mode 100644
index b5ab60b69..000000000
--- a/examples/default/domains/E-Commerce/subdomains/ProductCatalog/index.mdx
+++ /dev/null
@@ -1,59 +0,0 @@
----
-id: ProductCatalog
-name: Product Catalog
-version: 0.0.1
-summary: Manages product information, categories, inventory, and customer reviews in the e-commerce system.
-owners:
-  - dboyne
-entities:
-  - id: Product
-  - id: Category
-  - id: Inventory
-  - id: Review
-services:
-  - id: InventoryService
----
-
-## Overview
-
-The Product Catalog subdomain is responsible for managing all product-related information in the e-commerce system. This includes product details, hierarchical categorization, inventory tracking, and customer reviews.
-
-## Core Responsibilities
-
-### Product Management
-- Maintain product information including pricing, descriptions, and specifications
-- Support product variants (size, color, style)
-- Handle product lifecycle (active, discontinued, draft)
-- Manage product relationships and cross-selling
-
-### Category Management  
-- Organize products into hierarchical categories
-- Support multi-level category structures
-- Maintain category metadata and SEO information
-- Handle category navigation and filtering
-
-### Inventory Management
-- Track stock levels and availability
-- Manage reorder points and stock alerts  
-- Handle inventory reservations and allocations
-- Support warehouse and location management
-
-### Review Management
-- Collect and manage customer product reviews
-- Calculate review metrics and ratings
-- Moderate review content
-- Support review helpfulness and responses
-
-## Key Entities
-
-- **Product**: Central aggregate containing all product information
-- **Category**: Hierarchical product categorization system
-- **Inventory**: Stock tracking and availability management  
-- **Review**: Customer feedback and rating system
-
-## Business Rules
-
-- Products must belong to an active category
-- Inventory levels affect product availability
-- Reviews require verified purchases
-- Category hierarchies have maximum depth limits
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/channels/domain-eventbus/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/channels/domain-eventbus/index.mdx
deleted file mode 100644
index 6a168e1b4..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/channels/domain-eventbus/index.mdx
+++ /dev/null
@@ -1,15 +0,0 @@
----
-id: subscription-domain-eventbus
-name: Subscription Domain EventBus
-version: 1.0.0
-summary: |
-  Amazon Subscription Domain EventBus
-owners:
-  - dboyne
-routes:
-  - id: cross-account-bus
----
-
-{/* Information about the Orders Domain EventBus */}
-
-Full this....
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/entities/BillingProfile/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/entities/BillingProfile/index.mdx
deleted file mode 100644
index 460bcbc68..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/entities/BillingProfile/index.mdx
+++ /dev/null
@@ -1,68 +0,0 @@
----
-id: BillingProfile
-name: BillingProfile
-version: 1.0.0
-identifier: billingProfileId
-summary: Stores billing-related contact information and preferences for a customer, often used for invoices and communication.
-
-properties:
-  - name: billingProfileId
-    type: UUID
-    required: true
-    description: Unique identifier for the billing profile.
-  - name: customerId
-    type: UUID
-    required: true
-    description: Identifier of the customer this billing profile belongs to.
-    references: Customer
-    referencesIdentifier: customerId
-    relationType: hasOne
-  - name: billingEmail
-    type: string
-    required: false # May default to customer's primary email
-    description: Specific email address for sending invoices and billing notifications
-  - name: companyName # Optional, for B2B
-    type: string
-    required: false
-    description: Company name for billing purposes.
-  - name: taxId # Optional, for B2B or specific regions
-    type: string
-    required: false
-    description: Tax identification number (e.g., VAT ID, EIN).
-  - name: billingAddressId
-    type: UUID
-    required: true
-    description: Identifier for the primary billing address associated with this profile.
-  - name: preferredPaymentMethodId # Optional default for invoices/subscriptions
-    type: UUID
-    required: false
-    description: Customer's preferred payment method for charges related to this profile.
-  - name: createdAt
-    type: DateTime
-    required: true
-    description: Timestamp when the billing profile was created.
-  - name: updatedAt
-    type: DateTime
-    required: true
-    description: Timestamp when the billing profile was last updated.
----
-
-## Overview
-
-The BillingProfile entity consolidates billing-specific details for a customer, such as the billing address, contact email for invoices, tax information, and potentially preferred payment methods. This might be distinct from the customer's general contact information or shipping addresses.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-*   **Customer:** A billing profile belongs to one `Customer`. A customer might potentially have multiple profiles in complex scenarios, but often just one.
-*   **Address:** Linked to a primary billing `Address`.
-*   **PaymentMethod:** May specify a preferred `PaymentMethod`.
-*   **Invoice:** Invoices are typically generated using information from the BillingProfile.
-*   **Subscription:** Subscriptions may use the associated customer's BillingProfile for charging.
-
-## Examples
-
-*   Jane Doe's personal billing profile with her home address and primary email.
-*   Acme Corp's billing profile with their HQ address, VAT ID, and accounts payable email address. 
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/entities/SubscriptionPeriod/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/entities/SubscriptionPeriod/index.mdx
deleted file mode 100644
index 21c9f1f05..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/entities/SubscriptionPeriod/index.mdx
+++ /dev/null
@@ -1,73 +0,0 @@
----
-id: SubscriptionPeriod
-name: SubscriptionPeriod
-version: 1.0.0
-identifier: subscriptionPeriodId
-summary: Represents a single billing cycle or interval within a subscription's lifetime.
-
-properties:
-  - name: subscriptionPeriodId
-    type: UUID
-    required: true
-    description: Unique identifier for this specific subscription period.
-  - name: subscriptionId
-    type: UUID
-    required: true
-    description: Identifier of the parent Subscription this period belongs to.
-  - name: planId # Denormalized for easier lookup?
-    type: UUID
-    required: true
-    description: Identifier of the Plan active during this period
-  - name: startDate
-    type: Date
-    required: true
-    description: The start date of this billing period.
-  - name: endDate
-    type: Date
-    required: true
-    description: The end date of this billing period.
-  - name: invoiceId # Optional, links to the invoice generated for this period
-    type: UUID
-    required: false
-    description: Identifier of the invoice created for this period's charge.
-  - name: paymentId # Optional, links to the payment made for this period's invoice
-    type: UUID
-    required: false
-    description: Identifier of the payment that settled the invoice for this period.
-  - name: status
-    type: string # (e.g., Active, Billed, Paid, Unpaid, PastDue)
-    required: true
-    description: Status specific to this period (reflects invoicing/payment state).
-  - name: amountBilled
-    type: decimal
-    required: false # May only be set once invoiced
-    description: The actual amount billed for this period (could differ from plan due to promotions, usage, etc.).
-  - name: currency
-    type: string # ISO 4217 code
-    required: false
-    description: Currency of the billed amount.
-  - name: createdAt
-    type: DateTime
-    required: true
-    description: Timestamp when this period record was created (often at the start of the period).
----
-
-## Overview
-
-The SubscriptionPeriod entity tracks the state and details of a specific billing cycle within a `Subscription`. It links the subscription to the relevant invoice and payment for that interval and records the exact dates and amount billed.
-
-### Entity Properties
-<EntityPropertiesTable />
-
-## Relationships
-
-*   **Subscription:** A subscription period belongs to one `Subscription`.
-*   **Plan:** Reflects the `Plan` active during this period.
-*   **Invoice:** May be associated with one `Invoice` generated for this period.
-*   **Payment:** May be associated with one `Payment` that settled the period's invoice.
-
-## Examples
-
-*   Period for Jane Doe's 'Pro Plan' from 2024-05-01 to 2024-05-31, invoiced via #INV-00123, status Paid.
-*   Period for Acme Corp's 'Enterprise Plan' from 2024-04-15 to 2024-05-14, status Billed, awaiting payment.
-*   The first period (trial) for a new subscription from 2024-05-20 to 2024-06-19, status Active, amountBilled $0.00. 
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/flows/CancelSubscription/changelog.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/flows/CancelSubscription/changelog.mdx
deleted file mode 100644
index c8eb76e22..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/flows/CancelSubscription/changelog.mdx
+++ /dev/null
@@ -1,5 +0,0 @@
----
-createdAt: 2024-08-20
----
-
-Send an email to the customer confirming the successful cancellation.
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/flows/CancelSubscription/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/flows/CancelSubscription/index.mdx
deleted file mode 100644
index 772757393..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/flows/CancelSubscription/index.mdx
+++ /dev/null
@@ -1,70 +0,0 @@
----
-id: "CancelSubscription"
-name: "User Cancels Subscription"
-version: "1.0.0"
-summary: "Flow for when a user has cancelled a subscription"
-owners:
-  - subscriptions-management
-steps:
-  - id: "cancel_subscription_initiated"
-    title: "Cancels Subscription"
-    summary: "User cancels their subscription"
-    actor:
-      name: "User"
-    next_step:
-      id: "cancel_subscription_request"
-      label: "Initiate subscription cancellation"
-
-  - id: "cancel_subscription_request"
-    title: "Cancel Subscription"
-    message:
-      id: "CancelSubscription"
-      version: "0.0.1"
-    next_step:
-      id: "subscription_service"
-      label: "Proceed to subscription service"
-
-  - id: "stripe_integration"
-    title: "Stripe"
-    externalSystem:
-      name: "Stripe"
-      summary: "3rd party payment system"
-      url: "https://stripe.com/"
-    next_step:
-      id: "subscription_service"
-      label: "Return to subscription service"
-
-  - id: "subscription_service"
-    title: "Subscription Service"
-    service:
-      id: "SubscriptionService"
-      version: "0.0.1"
-    next_steps:
-      - id: "stripe_integration"
-        label: "Cancel subscription via Stripe"
-      - id: "subscription_cancelled"
-        label: "Successful cancellation"
-      - id: "subscription_rejected"
-        label: "Failed cancellation"
-
-  - id: "subscription_cancelled"
-    title: "Subscription has been Cancelled"
-    message:
-      id: "UserSubscriptionCancelled"
-      version: "0.0.1"
-    next_step:
-      id: "notification_service"
-      label: "Email customer"
-
-  - id: "subscription_rejected"
-    title: "Subscription cancellation has been rejected"
-
-  - id: "notification_service"
-    title: "Notifications Service"
-    service:
-      id: "NotificationService"
-      version: "0.0.2"
-
----
-
-<NodeGraph />
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/flows/CancelSubscription/versioned/0.0.1/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/flows/CancelSubscription/versioned/0.0.1/index.mdx
deleted file mode 100644
index 53cc9f7d5..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/flows/CancelSubscription/versioned/0.0.1/index.mdx
+++ /dev/null
@@ -1,51 +0,0 @@
----
-id: "CancelSubscription"
-name: "User Cancels Subscription"
-version: "0.0.1"
-summary: "Flow for when a user has cancelled a subscription"
-owners:
-  - subscriptions-management
-steps:
-  - id: "cancel_subscription_initiated"
-    title: "Cancels Subscription"
-    summary: "User cancels their subscription"
-    actor:
-      name: "User"
-    next_step:
-      id: "cancel_subscription_request"
-      label: "Initiate subscription cancellation"
-
-  - id: "cancel_subscription_request"
-    title: "Cancel Subscription"
-    message:
-      id: "CancelSubscription"
-      version: "0.0.1"
-    next_step:
-      id: "subscription_service"
-      label: "Proceed to subscription service"
-
-  - id: "stripe_integration"
-    title: "Stripe"
-    externalSystem:
-      name: "Stripe"
-      summary: "3rd party payment system"
-      url: "https://stripe.com/"
-    next_step:
-      id: "subscription_service"
-      label: "Return to subscription service"
-
-  - id: "subscription_service"
-    title: "Subscription Service"
-    service:
-      id: "SubscriptionService"
-      version: "0.0.1"
-    next_steps:
-      - id: "stripe_integration"
-        label: "Cancel subscription via Stripe"
-      - id: "subscription_cancelled"
-        label: "Successful cancellation"
-      - id: "subscription_rejected"
-        label: "Failed cancellation"
----
-
-<NodeGraph />
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/flows/SubscriptionRenewed/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/flows/SubscriptionRenewed/index.mdx
deleted file mode 100644
index 568329293..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/flows/SubscriptionRenewed/index.mdx
+++ /dev/null
@@ -1,304 +0,0 @@
----
-id: "SubscriptionRenewed"
-name: "Subscription Renewal Flow"
-version: "1.0.0"
-summary: "Business flow for automatic subscription renewals and related processes"
-owners:
-  - subscriptions-management
-steps:
-  - id: "renewal_timer_triggered"
-    title: "Renewal Period Reached"
-    custom:
-      title: "Renewal Timer"
-      color: "orange"
-      icon: "ClockIcon"
-      type: "Scheduler"
-      summary: "Automated timer triggers the subscription renewal process"
-      height: 8
-      properties:
-        subscription_id: "sub_12345678"
-        renewal_type: "Automatic"
-        billing_cycle: "Monthly"
-        next_billing_date: "2024-08-01"
-      menu:
-        - label: "View scheduler configuration"
-          url: "https://docs.example.com/scheduler"
-        - label: "Subscription timing documentation"
-          url: "https://docs.example.com/subscription-timing"
-    next_step:
-      id: "check_subscription_status"
-      label: "Verify subscription status"
-
-  - id: "check_subscription_status"
-    title: "Check Subscription Status"
-    service:
-      id: "SubscriptionService"
-      version: "0.0.1"
-    next_steps:
-      - id: "payment_approval_check"
-        label: "Subscription active, proceed to payment"
-      - id: "subscription_expired"
-        label: "Subscription has expired"
-      - id: "subscription_canceled"
-        label: "Subscription was canceled"
-
-  - id: "subscription_expired"
-    title: "Subscription Expired"
-    type: "node"
-    next_step:
-      id: "send_renewal_notification"
-      label: "Notify customer to renew"
-
-  - id: "subscription_canceled"
-    title: "Subscription Canceled"
-    type: "node"
-    next_step:
-      id: "send_reactivation_offer"
-      label: "Send special reactivation offer"
-
-  - id: "send_renewal_notification"
-    title: "Send Renewal Notification"
-    service:
-      id: "NotificationService"
-      version: "0.0.2"
-    next_step:
-      id: "await_customer_action"
-      label: "Wait for customer response"
-
-  - id: "send_reactivation_offer"
-    title: "Send Reactivation Offer"
-    service:
-      id: "NotificationService"
-      version: "0.0.2"
-    next_step:
-      id: "await_customer_action"
-      label: "Wait for customer response"
-
-  - id: "await_customer_action"
-    title: "Await Customer Action"
-    custom:
-      title: "Customer Decision Point"
-      color: "purple"
-      icon: "UserIcon"
-      type: "Decision"
-      height: 8
-      summary: "Waiting period for customer to take action on notification"
-      properties:
-        timeout_period: "7 days"
-        options: "Renew, Upgrade, Cancel, Ignore"
-    next_steps:
-      - id: "manual_renewal_flow"
-        label: "Customer manually renews"
-      - id: "flow_ends"
-        label: "No action taken"
-
-  - id: "manual_renewal_flow"
-    title: "Manual Renewal Flow"
-    type: "node"
-    next_step:
-      id: "payment_initiated"
-      label: "Process payment"
-
-  - id: "payment_approval_check"
-    title: "Check Payment Approval"
-    message:
-      id: "GetPaymentStatus"
-      version: "0.0.1"
-    next_steps:
-      - id: "payment_initiated"
-        label: "Payment approved, proceed with billing"
-      - id: "payment_method_invalid"
-        label: "Invalid payment method"
-
-  - id: "payment_method_invalid"
-    title: "Invalid Payment Method"
-    type: "node"
-    next_step:
-      id: "request_payment_update"
-      label: "Request updated payment method"
-
-  - id: "request_payment_update"
-    title: "Request Payment Update"
-    service:
-      id: "NotificationService"
-      version: "0.0.2"
-    next_step:
-      id: "await_updated_payment"
-      label: "Wait for payment update"
-
-  - id: "await_updated_payment"
-    title: "Await Updated Payment Method"
-    actor:
-      name: "Customer"
-      summary: "Customer is waiting for payment update"
-    next_steps:
-      - id: "payment_initiated"
-        label: "Payment method updated"
-      - id: "subscription_grace_period"
-        label: "No update received"
-
-  - id: "subscription_grace_period"
-    title: "Grace Period"
-    custom:
-      title: "Subscription Grace Period"
-      color: "yellow"
-      icon: "ShieldExclamationIcon"
-      type: "Timer"
-      summary: "Limited period where subscription remains active despite payment failure"
-      properties:
-        duration: "7 days"
-        status: "At risk"
-    next_steps:
-      - id: "payment_initiated"
-        label: "Payment updated during grace period"
-      - id: "subscription_suspended"
-        label: "Grace period expired"
-
-  - id: "subscription_suspended"
-    title: "Subscription Suspended"
-    message:
-      id: "UserSubscriptionCancelled"
-      version: "0.0.1"
-    next_step:
-      id: "send_suspension_notification"
-      label: "Notify customer of suspension"
-
-  - id: "send_suspension_notification"
-    title: "Send Suspension Notification"
-    service:
-      id: "NotificationService"
-      version: "0.0.2"
-    next_step:
-      id: "flow_ends"
-      label: "Flow ends"
-
-  - id: "payment_initiated"
-    title: "Process Payment"
-    message:
-      id: "PaymentInitiated"
-      version: "0.0.1"
-    next_step:
-      id: "payment_gateway"
-      label: "Send to payment gateway"
-
-  - id: "payment_gateway"
-    title: "Payment Gateway"
-    externalSystem:
-      name: "Stripe"
-      summary: "3rd party payment processor"
-      url: "https://stripe.com/"
-    next_steps:
-      - id: "payment_processed"
-        label: "Payment successful"
-      - id: "payment_failed"
-        label: "Payment failed"
-
-  - id: "payment_failed"
-    title: "Payment Failed"
-    type: "node"
-    next_step:
-      id: "retry_payment"
-      label: "Retry payment"
-
-  - id: "retry_payment"
-    title: "Retry Payment"
-    custom:
-      title: "Payment Retry Logic"
-      color: "red"
-      icon: "ArrowPathIcon"
-      type: "Processor"
-      summary: "Automated retry logic for failed payments"
-      properties:
-        max_attempts: 3
-        backoff_interval: "24 hours"
-        current_attempt: 1
-    next_steps:
-      - id: "payment_initiated"
-        label: "Retry payment"
-      - id: "subscription_grace_period"
-        label: "Max retries exceeded"
-
-  - id: "payment_processed"
-    title: "Payment Processed"
-    message:
-      id: "PaymentProcessed"
-      version: "1.0.0"
-    next_step:
-      id: "update_subscription_status"
-      label: "Update subscription"
-
-  - id: "update_subscription_status"
-    title: "Update Subscription"
-    service:
-      id: "SubscriptionService"
-      version: "0.0.1"
-    next_step:
-      id: "send_renewal_confirmation"
-      label: "Confirm renewal to customer"
-
-  - id: "send_renewal_confirmation"
-    title: "Send Renewal Confirmation"
-    service:
-      id: "NotificationService"
-      version: "0.0.2"
-    next_step:
-      id: "analyze_customer_usage"
-      label: "Analyze customer usage patterns"
-
-  - id: "analyze_customer_usage"
-    title: "Analyze Usage Patterns"
-    custom:
-      title: "Usage Analytics"
-      color: "blue"
-      icon: "ChartBarIcon"
-      type: "Analytics"
-      summary: "Analyze customer usage patterns to identify upsell opportunities"
-      properties:
-        metrics_analyzed: "Feature usage, Resource consumption, Access patterns"
-        lookback_period: "90 days"
-      menu:
-        - label: "View analytics dashboard"
-          url: "https://analytics.example.com/subscriptions"
-        - label: "Documentation"
-          url: "https://docs.example.com/analytics"
-    next_steps:
-      - id: "send_upgrade_recommendation"
-        label: "Usage suggests upgrade opportunity"
-      - id: "flow_ends"
-        label: "No upgrade opportunity identified"
-
-  - id: "send_upgrade_recommendation"
-    title: "Send Upgrade Recommendation"
-    service:
-      id: "NotificationService"
-      version: "0.0.2"
-    next_step:
-      id: "flow_ends"
-      label: "Flow completed"
-
-  - id: "flow_ends"
-    title: "Flow Completed"
-    type: "node"
-
----
-
-## Subscription Renewal Flow
-
-This flow documents the process of automatic subscription renewals, including handling various edge cases such as payment failures, expired subscriptions, and customer interactions.
-
-<NodeGraph />
-
-### Key Components
-
-* **Automatic Renewal Process**: Triggered by a scheduled timer when the subscription renewal period is reached
-* **Payment Processing**: Integration with payment gateway and handling of payment failures
-* **Customer Notifications**: Various notifications sent throughout the process
-* **Grace Period Handling**: Special handling when payments fail with a grace period before subscription suspension
-* **Usage Analytics**: Analysis of customer usage patterns to identify upgrade opportunities
-
-### Business Rules
-
-1. Subscriptions are renewed automatically unless explicitly canceled
-2. Failed payments trigger a retry process (up to 3 attempts)
-3. Customers receive a 7-day grace period before subscription suspension
-4. Usage patterns are analyzed to provide personalized upgrade recommendations
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/index.mdx
deleted file mode 100644
index ce7d3ae19..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/index.mdx
+++ /dev/null
@@ -1,58 +0,0 @@
----
-id: Subscriptions
-name: Subscriptions
-version: 0.0.1
-summary: |
-  Manages subscription lifecycle, billing cycles, and plan management for recurring revenue streams.
-owners:
-    - subscriptions-management
-services:
-    - id: BillingService
-      version: 0.0.1
-entities:
-    - id: BillingProfile
-    - id: SubscriptionPeriod
-badges:
-    - content: Subdomain
-      backgroundColor: blue
-      textColor: blue
-
----
-
-## Overview
-
-The Subscriptions Domain is responsible for managing all aspects of subscription-based services within our e-commerce platform. This includes subscription lifecycle management, recurring billing, plan management, and integration with payment systems.
-
-## Core Capabilities
-
-- **Subscription Lifecycle**: Create, update, pause, resume, and cancel subscriptions
-- **Billing Cycles**: Manage monthly, quarterly, and annual billing cycles
-- **Plan Management**: Define and manage subscription plans and pricing
-- **Trial Periods**: Support free trials and promotional periods
-- **Usage-based Billing**: Track and bill based on usage metrics
-
-## Services
-
-### BillingService
-Handles billing cycle calculations, invoice generation, and payment scheduling. Coordinates with the Payment domain for processing recurring payments.
-
-
-## Cross-Domain Integration
-
-The Subscriptions domain integrates closely with:
-
-- **Payment Domain**: For processing recurring payments and handling payment failures
-- **Orders Domain**: For managing subscription-based product orders
-- **Customer Domain**: For customer account and profile management
-
-## Domain Events
-
-Key events in the Subscriptions domain:
-- `SubscriptionPaymentDue` - Triggers payment collection
-- `PlanMigrationCompleted` - Subscription plan changed
-
-## Bounded context
-
-<NodeGraph />
-
-<MessageTable format="all" limit={6} />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/events/InvoiceGenerated/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/events/InvoiceGenerated/index.mdx
deleted file mode 100644
index ccaa824e3..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/events/InvoiceGenerated/index.mdx
+++ /dev/null
@@ -1,33 +0,0 @@
----
-id: InvoiceGenerated
-version: 0.0.1
-name: Invoice Generated
-summary: Emitted when an invoice is generated for a subscription
-tags:
-  - billing
-  - payment
-  - cross-domain
-badges:
-  - content: Cross-Domain
-    backgroundColor: purple
-    textColor: white
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro'
-
-## Overview
-
-The `InvoiceGenerated` event is emitted by the Billing Service when an invoice has been successfully generated for a subscription. This event notifies other services that a new invoice is available and ready for payment processing.
-
-## Cross-Domain Communication
-
-This event facilitates communication between:
-- **Source**: Subscriptions Domain (BillingService)
-- **Target**: Payment Domain (PaymentService), Notification Services, Accounting Systems
-
-## Schema
-
-<SchemaViewer title="InvoiceGenerated Schema" file="schema.json" />
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/events/InvoiceGenerated/schema.json b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/events/InvoiceGenerated/schema.json
deleted file mode 100644
index 83c1e9120..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/events/InvoiceGenerated/schema.json
+++ /dev/null
@@ -1,119 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "title": "InvoiceGenerated",
-  "description": "Schema for invoice generated event",
-  "properties": {
-    "invoiceId": {
-      "type": "string",
-      "description": "Unique identifier for the invoice"
-    },
-    "invoiceNumber": {
-      "type": "string",
-      "description": "Human-readable invoice number"
-    },
-    "subscriptionId": {
-      "type": "string",
-      "description": "Unique identifier for the subscription"
-    },
-    "customerId": {
-      "type": "string",
-      "description": "Unique identifier for the customer"
-    },
-    "invoiceDate": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Date and time when the invoice was generated"
-    },
-    "dueDate": {
-      "type": "string",
-      "format": "date-time",
-      "description": "Date and time when the invoice payment is due"
-    },
-    "status": {
-      "type": "string",
-      "enum": ["generated", "sent", "paid", "overdue", "cancelled"],
-      "description": "Current status of the invoice"
-    },
-    "lineItems": {
-      "type": "array",
-      "description": "List of items on the invoice",
-      "items": {
-        "type": "object",
-        "properties": {
-          "description": {
-            "type": "string",
-            "description": "Description of the line item"
-          },
-          "quantity": {
-            "type": "number",
-            "description": "Quantity of the item"
-          },
-          "unitPrice": {
-            "type": "number",
-            "description": "Price per unit"
-          },
-          "total": {
-            "type": "number",
-            "description": "Total price for this line item (quantity * unitPrice)"
-          }
-        },
-        "required": ["description", "quantity", "unitPrice", "total"]
-      }
-    },
-    "subtotal": {
-      "type": "number",
-      "description": "Subtotal amount before taxes"
-    },
-    "tax": {
-      "type": "number",
-      "description": "Tax amount applied to the invoice"
-    },
-    "total": {
-      "type": "number",
-      "description": "Total amount including taxes"
-    },
-    "currency": {
-      "type": "string",
-      "description": "Currency code (ISO 4217)"
-    },
-    "billingPeriod": {
-      "type": "object",
-      "description": "Billing period covered by this invoice",
-      "properties": {
-        "start": {
-          "type": "string",
-          "format": "date",
-          "description": "Start date of the billing period"
-        },
-        "end": {
-          "type": "string",
-          "format": "date",
-          "description": "End date of the billing period"
-        }
-      },
-      "required": ["start", "end"]
-    },
-    "planId": {
-      "type": "string",
-      "description": "Subscription plan identifier"
-    }
-  },
-  "required": [
-    "invoiceId",
-    "invoiceNumber",
-    "subscriptionId",
-    "customerId",
-    "invoiceDate",
-    "dueDate",
-    "status",
-    "lineItems",
-    "subtotal",
-    "tax",
-    "total",
-    "currency",
-    "billingPeriod",
-    "planId"
-  ]
-}
-
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/events/SubscriptionPaymentDue/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/events/SubscriptionPaymentDue/index.mdx
deleted file mode 100644
index d1cc3e02d..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/events/SubscriptionPaymentDue/index.mdx
+++ /dev/null
@@ -1,60 +0,0 @@
----
-id: SubscriptionPaymentDue
-version: 0.0.1
-name: Subscription Payment Due
-summary: Emitted when a subscription payment is due for collection
-tags:
-  - billing
-  - payment
-  - cross-domain
-badges:
-  - content: Cross-Domain
-    backgroundColor: purple
-    textColor: white
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro'
-
-## Overview
-
-The `SubscriptionPaymentDue` event is emitted by the Billing Service when a subscription's billing cycle is due for payment. This event triggers the payment collection process in the Payment domain.
-
-## Cross-Domain Communication
-
-This event facilitates communication between:
-- **Source**: Subscriptions Domain (BillingService)
-- **Target**: Payment Domain (PaymentService, FraudDetectionService)
-
-## Schema
-
-<SchemaViewer title="SubscriptionPaymentDue Schema" file={frontmatter.schemaPath} />
-
-## Event Flow
-
-1. BillingService calculates when payment is due
-2. Emits `SubscriptionPaymentDue` event
-3. PaymentService receives and initiates payment
-4. FraudDetectionService performs risk assessment
-5. Payment is processed through PaymentGatewayService
-
-## Example Payload
-
-```json
-{
-  "subscriptionId": "sub_ABC123",
-  "customerId": "cust_XYZ789",
-  "invoiceId": "inv_123456",
-  "amount": 49.99,
-  "currency": "USD",
-  "dueDate": "2024-02-01T00:00:00Z",
-  "billingPeriod": {
-    "start": "2024-02-01",
-    "end": "2024-02-29"
-  },
-  "planId": "pro-monthly",
-  "retryAttempt": 0
-}
-```
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/events/SubscriptionPaymentDue/schema.json b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/events/SubscriptionPaymentDue/schema.json
deleted file mode 100644
index d1ed1aba9..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/events/SubscriptionPaymentDue/schema.json
+++ /dev/null
@@ -1,54 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "subscriptionId": {
-      "type": "string",
-      "description": "Unique identifier for the subscription"
-    },
-    "customerId": {
-      "type": "string",
-      "description": "Unique identifier for the customer"
-    },
-    "invoiceId": {
-      "type": "string",
-      "description": "Unique identifier for the invoice"
-    },
-    "amount": {
-      "type": "number",
-      "description": "Amount due for payment"
-    },
-    "currency": {
-      "type": "string",
-      "description": "Currency code (ISO 4217)"
-    },
-    "dueDate": {
-      "type": "string",
-      "format": "date-time",
-      "description": "When the payment is due"
-    },
-    "billingPeriod": {
-      "type": "object",
-      "properties": {
-        "start": {
-          "type": "string",
-          "format": "date"
-        },
-        "end": {
-          "type": "string",
-          "format": "date"
-        }
-      },
-      "required": ["start", "end"]
-    },
-    "planId": {
-      "type": "string",
-      "description": "Subscription plan identifier"
-    },
-    "retryAttempt": {
-      "type": "integer",
-      "description": "Number of retry attempts for failed payments"
-    }
-  },
-  "required": ["subscriptionId", "customerId", "invoiceId", "amount", "currency", "dueDate"]
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/index.mdx
deleted file mode 100644
index 82e3eebdb..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/index.mdx
+++ /dev/null
@@ -1,90 +0,0 @@
----
-id: BillingService
-version: 0.0.1
-name: Billing Service
-summary: >-
-  Manages billing cycles, invoice generation, and payment scheduling for
-  subscriptions
-tags:
-  - billing
-  - subscriptions
-  - invoicing
-repository:
-  url: 'https://github.com/eventcatalog/billing-service'
-receives:
-  - id: PaymentProcessed
-sends:
-  - id: InvoiceGenerated
-  - id: SubscriptionPaymentDue
-owners:
-  - dboyne
-attachments:
-  - url: 'https://example.com/adr/001'
-    title: ADR-001 - Use Kafka for asynchronous messaging
-    type: architecture-decisions
-    icon: FileTextIcon
-  - url: 'https://example.com/adr/001'
-    title: ADR-002 - Database per service
-    icon: FileTextIcon
-    type: architecture-decisions
-specifications:
-  - type: graphql
-    path: schema.graphql
-    name: GraphQL API
-readsFrom:
-  - id: order-metadata-store
----
-
-import Footer from '@catalog/components/footer.astro'
-
-## Overview
-
-The Billing Service is responsible for managing all billing-related operations for subscriptions. It calculates billing cycles, generates invoices, and coordinates with payment services to ensure timely payment collection.
-
-## Key Features
-
-- **Billing Cycle Management**: Handles daily, weekly, monthly, quarterly, and annual billing cycles
-- **Invoice Generation**: Creates detailed invoices with line items and tax calculations
-- **Payment Scheduling**: Schedules recurring payments based on billing cycles
-- **Proration**: Calculates prorated charges for mid-cycle changes
-- **Dunning Management**: Handles failed payment retry logic
-
-## API Endpoints
-
-### REST API
-- `GET /api/billing/invoice/{subscriptionId}` - Get current invoice
-- `GET /api/billing/history/{subscriptionId}` - Get billing history
-- `POST /api/billing/preview` - Preview upcoming charges
-- `PUT /api/billing/retry/{invoiceId}` - Retry failed payment
-
-## Billing Cycle States
-
-```mermaid
-stateDiagram-v2
-    [*] --> Scheduled
-    Scheduled --> Processing
-    Processing --> Paid
-    Processing --> Failed
-    Failed --> Retrying
-    Retrying --> Paid
-    Retrying --> Suspended
-    Paid --> [*]
-    Suspended --> [*]
-```
-
-## Configuration
-
-```yaml
-billing_service:
-  cycles:
-    - daily
-    - weekly
-    - monthly
-    - quarterly
-    - annual
-  retry_attempts: 3
-  retry_interval_days: [1, 3, 7]
-  invoice_generation_lead_days: 7
-```
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/schema.graphql b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/schema.graphql
deleted file mode 100644
index ee85bbb50..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/BillingService/schema.graphql
+++ /dev/null
@@ -1,191 +0,0 @@
-scalar DateTime
-scalar Money
-
-enum BillingCycle {
-  DAILY
-  WEEKLY
-  MONTHLY
-  QUARTERLY
-  ANNUAL
-}
-
-enum InvoiceStatus {
-  DRAFT
-  PENDING
-  PAID
-  FAILED
-  CANCELLED
-  REFUNDED
-}
-
-enum PaymentStatus {
-  SCHEDULED
-  PROCESSING
-  PAID
-  FAILED
-  RETRYING
-  SUSPENDED
-}
-
-type Subscription {
-  id: ID!
-  customerId: ID!
-  planId: ID!
-  status: String!
-  billingCycle: BillingCycle!
-  currentPeriodStart: DateTime!
-  currentPeriodEnd: DateTime!
-  cancelAtPeriodEnd: Boolean!
-  createdAt: DateTime!
-  updatedAt: DateTime!
-}
-
-type LineItem {
-  id: ID!
-  description: String!
-  quantity: Int!
-  unitPrice: Money!
-  totalAmount: Money!
-  taxAmount: Money!
-  proratedDays: Int
-}
-
-type Invoice {
-  id: ID!
-  subscriptionId: ID!
-  invoiceNumber: String!
-  status: InvoiceStatus!
-  subtotal: Money!
-  taxAmount: Money!
-  totalAmount: Money!
-  dueDate: DateTime!
-  paidAt: DateTime
-  lineItems: [LineItem!]!
-  billingPeriodStart: DateTime!
-  billingPeriodEnd: DateTime!
-  createdAt: DateTime!
-  updatedAt: DateTime!
-}
-
-type Payment {
-  id: ID!
-  invoiceId: ID!
-  amount: Money!
-  status: PaymentStatus!
-  attemptCount: Int!
-  nextRetryAt: DateTime
-  failureReason: String
-  processedAt: DateTime
-  createdAt: DateTime!
-}
-
-type BillingHistory {
-  subscriptionId: ID!
-  invoices: [Invoice!]!
-  totalPages: Int!
-  currentPage: Int!
-}
-
-type ChargePreview {
-  subscriptionId: ID!
-  nextBillingDate: DateTime!
-  upcomingCharges: [LineItem!]!
-  proratedCredits: [LineItem!]!
-  totalAmount: Money!
-}
-
-type RetryResult {
-  success: Boolean!
-  payment: Payment
-  errorMessage: String
-}
-
-input ChargePreviewInput {
-  subscriptionId: ID!
-  planChanges: [PlanChangeInput!]
-  addons: [AddonInput!]
-}
-
-input PlanChangeInput {
-  newPlanId: ID!
-  effectiveDate: DateTime
-}
-
-input AddonInput {
-  addonId: ID!
-  quantity: Int!
-}
-
-type Query {
-  """Get current invoice for a subscription"""
-  currentInvoice(subscriptionId: ID!): Invoice
-
-  """Get billing history for a subscription with pagination"""
-  billingHistory(
-    subscriptionId: ID!
-    page: Int = 1
-    limit: Int = 10
-  ): BillingHistory!
-
-  """Preview upcoming charges for a subscription"""
-  previewCharges(input: ChargePreviewInput!): ChargePreview!
-
-  """Get invoice by ID"""
-  invoice(id: ID!): Invoice
-
-  """Get payment details"""
-  payment(id: ID!): Payment
-
-  """Get all failed payments for retry"""
-  failedPayments(subscriptionId: ID!): [Payment!]!
-}
-
-type Mutation {
-  """Retry a failed payment"""
-  retryPayment(invoiceId: ID!): RetryResult!
-
-  """Generate invoice for subscription"""
-  generateInvoice(subscriptionId: ID!): Invoice!
-
-  """Process immediate payment"""
-  processPayment(invoiceId: ID!): Payment!
-
-  """Cancel invoice"""
-  cancelInvoice(invoiceId: ID!): Invoice!
-
-  """Apply credit to subscription"""
-  applyCredit(
-    subscriptionId: ID!
-    amount: Money!
-    reason: String!
-  ): Invoice!
-}
-
-type Subscription {
-  """Real-time updates for billing events"""
-  billingEvents(subscriptionId: ID!): BillingEvent!
-}
-
-union BillingEvent = InvoiceGenerated | PaymentProcessed | PaymentFailed | PaymentRetrying
-
-type InvoiceGenerated {
-  invoice: Invoice!
-  subscription: Subscription!
-}
-
-type PaymentProcessed {
-  payment: Payment!
-  invoice: Invoice!
-}
-
-type PaymentFailed {
-  payment: Payment!
-  invoice: Invoice!
-  retryScheduledAt: DateTime
-}
-
-type PaymentRetrying {
-  payment: Payment!
-  attemptNumber: Int!
-  nextRetryAt: DateTime!
-}
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/commands/CancelSubscription/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/commands/CancelSubscription/index.mdx
deleted file mode 100644
index 019154688..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/commands/CancelSubscription/index.mdx
+++ /dev/null
@@ -1,27 +0,0 @@
----
-id: CancelSubscription
-name: Cancel subscription
-version: 0.0.1
-summary: |
-  Command that will try and cancel a users subscription
-owners:
-    - subscriptions-management
-badges:
-    - content: New!
-      backgroundColor: green
-      textColor: green
-sidebar:
-  badge: 'POST'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `CancelSubscription` command will try and cancel a subscription for the user.
-
-## Architecture diagram
-
-<NodeGraph />
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/commands/SubscribeUser/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/commands/SubscribeUser/index.mdx
deleted file mode 100644
index d99c9f821..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/commands/SubscribeUser/index.mdx
+++ /dev/null
@@ -1,27 +0,0 @@
----
-id: SubscribeUser
-name: Subscribe user
-version: 0.0.1
-summary: |
-  Command that will try and subscribe a given user
-owners:
-    - subscriptions-management
-badges:
-    - content: New!
-      backgroundColor: green
-      textColor: green
-sidebar:
-  badge: 'POST'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `SubscribeUser` command represents when a new user wants to subscribe to our service.
-
-## Architecture diagram
-
-<NodeGraph />
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/containers/subscriptions-db/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/containers/subscriptions-db/index.mdx
deleted file mode 100644
index a89615252..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/containers/subscriptions-db/index.mdx
+++ /dev/null
@@ -1,167 +0,0 @@
----
-id: subscriptions-db
-name: Subscriptions DB
-version: 0.0.1
-container_type: database
-technology: postgres@15
-authoritative: true
-access_mode: readWrite
-classification: internal
-retention: 7y
-residency: eu-west-1
-summary: Primary database for subscription plans, user subscriptions, and recurring billing cycles
----
-
-<NodeGraph />
-
-### What is this?
-Subscriptions DB is the system of record for all subscription-related data including subscription plans, customer subscriptions, billing cycles, and subscription lifecycle events. It uses PostgreSQL 15 with specialized extensions for time-series billing data.
-
-### What does it store?
-- **Subscription Plans**: Available plans with pricing, billing frequency, and features
-- **Customer Subscriptions**: Active and historical subscriptions with status tracking
-- **Billing Cycles**: Recurring billing periods, next billing dates, and payment status
-- **Subscription Changes**: Audit trail of plan changes, upgrades, downgrades, cancellations
-- **Usage Tracking**: For metered billing features and overage calculations
-
-### Who writes to it?
-- **SubscriptionService** manages subscription lifecycle (create, update, cancel, renew)
-- **BillingService** updates billing cycle status and payment attempts
-- **PaymentService** updates payment method associations
-
-### Who reads from it?
-- **BillingService** reads upcoming billing cycles for charge processing
-- **PaymentService** checks subscription status for payment validation
-- **OrdersService** validates subscription benefits for order processing
-- **Analytics** tracks subscription metrics (churn, MRR, LTV)
-- **Customer Support** views subscription history and status
-
-### High-level data model
-- `subscription_plans`: Catalog of available plans and pricing tiers
-- `subscriptions`: Customer subscriptions linked to plans and payment methods
-- `billing_cycles`: Time-based records of billing periods
-- Subscription status: `TRIAL`, `ACTIVE`, `PAST_DUE`, `CANCELLED`, `EXPIRED`
-
-### Common queries
-```sql
--- Get active subscriptions with next billing date
-SELECT s.subscription_id, s.customer_id, sp.name AS plan_name,
-       bc.next_billing_date, bc.amount_cents
-FROM subscriptions s
-JOIN subscription_plans sp USING (plan_id)
-JOIN billing_cycles bc ON bc.subscription_id = s.subscription_id
-WHERE s.status = 'ACTIVE'
-  AND bc.next_billing_date BETWEEN CURRENT_DATE AND CURRENT_DATE + INTERVAL '7 days';
-
--- Calculate Monthly Recurring Revenue (MRR)
-SELECT
-  sp.name AS plan_name,
-  COUNT(*) AS active_subscriptions,
-  SUM(bc.amount_cents)/100.0 AS monthly_revenue
-FROM subscriptions s
-JOIN subscription_plans sp USING (plan_id)
-JOIN billing_cycles bc ON bc.subscription_id = s.subscription_id
-WHERE s.status = 'ACTIVE'
-  AND sp.billing_frequency = 'MONTHLY'
-GROUP BY sp.name;
-
--- Find subscriptions due for renewal today
-SELECT s.subscription_id, s.customer_id, s.payment_method_id,
-       bc.amount_cents, bc.currency
-FROM subscriptions s
-JOIN billing_cycles bc ON bc.subscription_id = s.subscription_id
-WHERE bc.next_billing_date = CURRENT_DATE
-  AND s.status = 'ACTIVE'
-  AND bc.status = 'PENDING';
-
--- Customer subscription history (for support)
-SELECT s.subscription_id, sp.name, s.status,
-       s.started_at, s.cancelled_at,
-       CASE WHEN s.status = 'ACTIVE'
-            THEN DATE_PART('day', NOW() - s.started_at)
-            ELSE DATE_PART('day', s.cancelled_at - s.started_at)
-       END AS subscription_days
-FROM subscriptions s
-JOIN subscription_plans sp USING (plan_id)
-WHERE s.customer_id = $1
-ORDER BY s.started_at DESC;
-```
-
-### Subscription lifecycle
-1. Customer selects plan → `SubscriptionService` creates subscription with `TRIAL` or `ACTIVE` status
-2. Billing cycle created with `next_billing_date`
-3. BillingService processes payment on billing date
-4. On success: cycle renewed, `next_billing_date` updated
-5. On failure: subscription status → `PAST_DUE`, retry logic triggered
-6. Cancellation: status → `CANCELLED`, billing cycles stop
-7. Expiration: status → `EXPIRED` after grace period
-
-### Access patterns and guidance
-- Use indexed lookups by `customer_id` and `subscription_id`
-- Billing date queries use `next_billing_date` index for daily batch processing
-- Status filtering is common; maintain composite index on `(status, next_billing_date)`
-- Subscription changes are append-only for audit trail
-- Use read replicas for analytics and reporting queries
-
-### Security and compliance
-- Payment method tokens stored, not raw card data
-- Customer PII encrypted at rest
-- Access logged for compliance audits
-- GDPR right-to-deletion supported via customer_id purge
-- Financial data retention: 7 years for tax/regulatory requirements
-
-### Requesting access
-To request access to Subscriptions DB:
-
-1. **Development access** (read-only):
-   - Submit ticket via [ServiceNow](https://company.service-now.com)
-   - Select "Database Access" → "Subscriptions DB (Dev)"
-   - Approval from subscriptions team lead required
-   - Access granted within 24 hours
-
-2. **Analytics access** (read-replica):
-   - Request via #subscriptions-data Slack channel
-   - Use read-replica endpoint for reporting queries
-   - No approval needed for read-only analytics access
-
-3. **Production write access**:
-   - Restricted to SubscriptionService and BillingService only
-   - Manual production writes require incident ticket + approval
-   - Emergency access via on-call: PagerDuty #subscriptions-oncall
-
-**Contact**:
-- Slack: #subscriptions-team
-- Email: subscriptions-team@company.com
-- Team lead: subscriptions-management team
-
-### Monitoring and alerts
-- Failed billing cycle alerts (> 5% failure rate)
-- Subscription churn rate monitoring (weekly)
-- Database replication lag (alert at > 10 seconds)
-- Past-due subscription count (daily alert if > threshold)
-
-### Backup and disaster recovery
-- Automated daily snapshots with 35-day retention
-- Point-in-time recovery with 5-minute RPO
-- Cross-region backup replication
-- Monthly restore drills
-
-### Performance characteristics
-- **Read latency**: p99 < 50ms
-- **Write latency**: p99 < 100ms
-- **Daily billing batch**: processes 50,000+ subscriptions in < 1 hour
-- **Connection pool**: 20-100 connections depending on load
-
-### Local development
-- Connection string: `SUBSCRIPTIONS_DB_URL` environment variable
-- Docker setup: `docker-compose up subscriptions-db`
-- Seed data: `npm run seed:subscriptions`
-- Test data includes trial, active, and cancelled subscriptions
-
-### Common issues and troubleshooting
-- **Duplicate billing cycles**: Check idempotency in billing cycle creation
-- **Missed renewals**: Verify cron job schedule and timezone handling
-- **Past-due stuck subscriptions**: Run retry job, check payment method validity
-- **Timezone issues**: All dates stored in UTC, convert for display only
-
-For more information, see SubscriptionService documentation and Billing Runbooks.
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/events/UserSubscriptionCancelled/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/events/UserSubscriptionCancelled/index.mdx
deleted file mode 100644
index 8c976ebe2..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/events/UserSubscriptionCancelled/index.mdx
+++ /dev/null
@@ -1,25 +0,0 @@
----
-id: UserSubscriptionCancelled
-name: User subscription cancelled
-version: 0.0.1
-summary: |
-  An event that is triggered when a users subscription has been cancelled
-owners:
-    - subscriptions-management
-badges:
-    - content: New!
-      backgroundColor: green
-      textColor: green
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `UserSubscriptionCancelled` event is triggered when a users subscription has been cancelled.
-
-## Architecture diagram
-
-<NodeGraph />
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/events/UserSubscriptionStarted/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/events/UserSubscriptionStarted/index.mdx
deleted file mode 100644
index ba1b28edb..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/events/UserSubscriptionStarted/index.mdx
+++ /dev/null
@@ -1,25 +0,0 @@
----
-id: UserSubscriptionStarted
-name: User subscription started
-version: 0.0.1
-summary: |
-  An event that is triggered when a new user subscription has started
-owners:
-    - subscriptions-management
-badges:
-    - content: New!
-      backgroundColor: green
-      textColor: green
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `UserSubscriptionStarted` event is triggered when a user starts a new subscription with our service.
-
-## Architecture diagram
-
-<NodeGraph />
-
-<Footer />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/index.mdx
deleted file mode 100644
index af199ddaf..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/index.mdx
+++ /dev/null
@@ -1,86 +0,0 @@
----
-id: SubscriptionService
-version: 0.0.1
-name: Subscription Service
-summary: |
-  Service that handles subscriptions
-owners:
-  - subscriptions-management
-receives:
-  - id: PaymentProcessed
-    version: 0.0.1
-    from:
-      - id: 'payments.{env}.events'
-        parameters:
-          env: staging
-sends:
-  - id: UserSubscriptionStarted
-    version: 0.0.1
-    to:
-      - id: 'subscription-domain-eventbus'
-  - id: UserSubscriptionCancelled
-    version: 0.0.1
-    to:
-      - id: 'subscription-domain-eventbus'
-writesTo:
-  - id: subscriptions-db
-    version: 0.0.1
-readsFrom:
-  - id: subscriptions-db
-    version: 0.0.1
-  - id: payments-db
-    version: 0.0.1
-repository:
-  language: JavaScript
-  url: 'https://github.com/event-catalog/pretend-subscription-service'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The subscription Service is responsible for handling customer subscriptions in our system. It handles new subscriptions, cancelling subscriptions and updating them.
-
-<Tiles >
-    <Tile icon="DocumentIcon" href={`/docs/services/${frontmatter.id}/${frontmatter.version}/changelog`}  title="View the changelog" description="Want to know the history of this service? View the change logs" />
-    <Tile icon="UserGroupIcon" href="/docs/teams/full-stack" title="Contact the team" description="Any questions? Feel free to contact the owners" />
-    <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="This service sends messages to downstream consumers" />
-    <Tile icon="BoltIcon"  href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="This service receives messages from other services" />
-</Tiles>
-
-### Core features
-
-| Feature | Description |
-|---------|-------------|
-| Subscription Management | Handles subscription creation, updates, and status tracking |
-| Payment Processing | Integrates with payment gateways to handle payment transactions |
-| Notification Integration | Sends notifications to users and other services |
-| Multi-Channel Fulfillment | Supports multiple fulfillment channels (e.g., shipping, in-store pickup) |
-
-## Architecture diagram 
-
-<NodeGraph />
-
-<MessageTable format="all" limit={4} />
-
-## Infrastructure
-
-The Subscription Service is hosted on AWS.
-
-The diagram below shows the infrastructure of the Subscription Service. The service is hosted on AWS and uses AWS Lambda to handle the subscription requests. The subscription is stored in an AWS Aurora database and the subscription metadata is stored in an AWS S3 bucket.
-
-```mermaid
-architecture-beta
-    group api(logos:aws)
-
-    service db(logos:aws-aurora)[Subscription DB] in api
-    service disk1(logos:aws-s3)[Subscription Metadata] in api
-    service server(logos:aws-lambda)[Subscription Handler] in api
-
-    db:L -- R:server
-    disk1:T -- B:server
-```
-
-You can find more information about the Subscription Service infrastructure in the [Subscription Service documentation](https://github.com/event-catalog/pretend-subscription-service/blob/main/README.md).
-
-<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/queries/GetSubscriptionStatus/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/queries/GetSubscriptionStatus/index.mdx
deleted file mode 100644
index b6c969c18..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/queries/GetSubscriptionStatus/index.mdx
+++ /dev/null
@@ -1,28 +0,0 @@
----
-id: GetSubscriptionStatus
-name: Get subscription status
-version: 0.0.2
-summary: |
-  GET request that will return the current subscription status for a specific user, identified by their userId.
-owners:
-    - subscriptions-management
-badges:
-    - content: Recently updated!
-      backgroundColor: green
-      textColor: green
-schemaPath: schema.json
-sidebar:
-  badge: 'GET'
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `GetSubscriptionStatus` message is a query used to retrieve the current subscription status for a specific user, identified by their `userId`. This query returns detailed information about the user's subscription, such as its current status (active, canceled, expired), the subscription tier or plan, and the next billing date. It is typically used by systems that manage user subscriptions, billing, and renewal processes to ensure that users are aware of their subscription details and any upcoming renewals.
-
-This query is particularly useful in managing subscriptions for SaaS products, media services, or any recurring payment-based services where users need to manage and view their subscription information.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/queries/GetSubscriptionStatus/schema.json b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/queries/GetSubscriptionStatus/schema.json
deleted file mode 100644
index eab69d297..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/queries/GetSubscriptionStatus/schema.json
+++ /dev/null
@@ -1,46 +0,0 @@
-
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "GetSubscriptionStatusResponse",
-  "type": "object",
-  "properties": {
-    "userId": {
-      "type": "string",
-      "description": "The unique identifier for the user."
-    },
-    "subscriptionStatus": {
-      "type": "string",
-      "enum": ["active", "canceled", "expired", "pending"],
-      "description": "The current status of the user's subscription."
-    },
-    "subscriptionPlan": {
-      "type": "string",
-      "description": "The name or tier of the subscription plan."
-    },
-    "nextBillingDate": {
-      "type": "string",
-      "format": "date-time",
-      "description": "The date and time of the next billing or renewal."
-    },
-    "billingFrequency": {
-      "type": "string",
-      "enum": ["monthly", "yearly"],
-      "description": "The frequency of the billing cycle."
-    },
-    "amount": {
-      "type": "number",
-      "description": "The amount to be billed for the subscription."
-    },
-    "currency": {
-      "type": "string",
-      "description": "The currency in which the subscription is billed (e.g., USD, EUR)."
-    },
-    "lastPaymentDate": {
-      "type": "string",
-      "format": "date-time",
-      "description": "The date and time when the last payment was processed."
-    }
-  },
-  "required": ["userId", "subscriptionStatus", "subscriptionPlan", "nextBillingDate", "billingFrequency", "amount", "currency", "lastPaymentDate"],
-  "additionalProperties": false
-}
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/queries/GetSubscriptionStatus/versioned/0.0.1/index.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/queries/GetSubscriptionStatus/versioned/0.0.1/index.mdx
deleted file mode 100644
index b46ab0e33..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/queries/GetSubscriptionStatus/versioned/0.0.1/index.mdx
+++ /dev/null
@@ -1,26 +0,0 @@
----
-id: GetSubscriptionStatus
-name: Get subscription status
-version: 0.0.1
-summary: |
-  GET request that will return the current subscription status for a specific user, identified by their userId.
-owners:
-    - dboyne
-badges:
-    - content: Recently updated!
-      backgroundColor: green
-      textColor: green
-schemaPath: schema.json
----
-
-import Footer from '@catalog/components/footer.astro';
-
-## Overview
-
-The `GetSubscriptionStatus` message is a query used to retrieve the current subscription status for a specific user, identified by their `userId`. This query returns detailed information about the user's subscription, such as its current status (active, canceled, expired), the subscription tier or plan, and the next billing date. It is typically used by systems that manage user subscriptions, billing, and renewal processes to ensure that users are aware of their subscription details and any upcoming renewals.
-
-This query is particularly useful in managing subscriptions for SaaS products, media services, or any recurring payment-based services where users need to manage and view their subscription information.
-
-<NodeGraph />
-
-<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
\ No newline at end of file
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/queries/GetSubscriptionStatus/versioned/0.0.1/schema.json b/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/queries/GetSubscriptionStatus/versioned/0.0.1/schema.json
deleted file mode 100644
index eab69d297..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/services/SubscriptionService/queries/GetSubscriptionStatus/versioned/0.0.1/schema.json
+++ /dev/null
@@ -1,46 +0,0 @@
-
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "GetSubscriptionStatusResponse",
-  "type": "object",
-  "properties": {
-    "userId": {
-      "type": "string",
-      "description": "The unique identifier for the user."
-    },
-    "subscriptionStatus": {
-      "type": "string",
-      "enum": ["active", "canceled", "expired", "pending"],
-      "description": "The current status of the user's subscription."
-    },
-    "subscriptionPlan": {
-      "type": "string",
-      "description": "The name or tier of the subscription plan."
-    },
-    "nextBillingDate": {
-      "type": "string",
-      "format": "date-time",
-      "description": "The date and time of the next billing or renewal."
-    },
-    "billingFrequency": {
-      "type": "string",
-      "enum": ["monthly", "yearly"],
-      "description": "The frequency of the billing cycle."
-    },
-    "amount": {
-      "type": "number",
-      "description": "The amount to be billed for the subscription."
-    },
-    "currency": {
-      "type": "string",
-      "description": "The currency in which the subscription is billed (e.g., USD, EUR)."
-    },
-    "lastPaymentDate": {
-      "type": "string",
-      "format": "date-time",
-      "description": "The date and time when the last payment was processed."
-    }
-  },
-  "required": ["userId", "subscriptionStatus", "subscriptionPlan", "nextBillingDate", "billingFrequency", "amount", "currency", "lastPaymentDate"],
-  "additionalProperties": false
-}
diff --git a/examples/default/domains/E-Commerce/subdomains/Subscriptions/ubiquitous-language.mdx b/examples/default/domains/E-Commerce/subdomains/Subscriptions/ubiquitous-language.mdx
deleted file mode 100644
index b594f4dbe..000000000
--- a/examples/default/domains/E-Commerce/subdomains/Subscriptions/ubiquitous-language.mdx
+++ /dev/null
@@ -1,129 +0,0 @@
----
-dictionary:
-  - id: Subscription
-    name: Subscription
-    summary: "A recurring agreement where a customer pays for access to a product or service at regular intervals."
-    description: |
-      A subscription represents an ongoing relationship between customer and provider. Key aspects include:
-
-      - Subscription plan details
-      - Billing frequency
-      - Access rights and limitations
-      - Start and end dates
-      - Auto-renewal settings
-
-      Subscriptions provide predictable revenue for businesses and convenient access for customers.
-    icon: Repeat
-  - id: Billing Cycle
-    name: Billing Cycle
-    summary: "The recurring period for which a subscription is billed."
-    description: |
-      Billing cycles define when payments are collected and services are provided. They include:
-
-      - Cycle duration (monthly, annually, etc.)
-      - Billing date
-      - Payment due dates
-      - Pro-ration rules
-      - Grace periods
-
-      Clear billing cycles help manage customer expectations and cash flow.
-    icon: Calendar
-  - id: Plan
-    name: Plan
-    summary: "A specific subscription offering with defined features, pricing, and terms."
-    description: |
-      Subscription plans define the service levels available to customers. They specify:
-
-      - Feature sets and limitations
-      - Pricing structure
-      - Billing frequency options
-      - Usage allowances
-      - Additional benefits
-
-      Well-designed plans cater to different customer segments and needs.
-    icon: Layout
-  - id: Trial Period
-    name: Trial Period
-    summary: "A promotional period allowing customers to test a subscription service before committing."
-    description: |
-      Trial periods help customers evaluate the service risk-free. They include:
-
-      - Duration of trial
-      - Available features
-      - Conversion process
-      - Payment information requirements
-      - Trial end notifications
-
-      Effective trials can increase conversion rates to paid subscriptions.
-    icon: Clock
-  - id: Auto-Renewal
-    name: Auto-Renewal
-    summary: "Automatic continuation of a subscription at the end of each billing period."
-    description: |
-      Auto-renewal ensures service continuity for customers. The process includes:
-
-      - Renewal notifications
-      - Payment processing
-      - Service extension
-      - Failed payment handling
-      - Cancellation options
-
-      Auto-renewal reduces churn and maintains steady revenue streams.
-    icon: RefreshCw
-  - id: Upgrade
-    name: Upgrade
-    summary: "The process of moving to a higher-tier subscription plan."
-    description: |
-      Upgrades allow customers to access more features or capacity. This involves:
-
-      - Plan comparison
-      - Pro-rated billing adjustments
-      - Feature activation
-      - Data migration if needed
-      - Service level changes
-
-      Smooth upgrade processes encourage customer growth.
-    icon: ArrowUpCircle
-  - id: Downgrade
-    name: Downgrade
-    summary: "The process of moving to a lower-tier subscription plan."
-    description: |
-      Downgrades adjust service levels to match customer needs. This includes:
-
-      - Feature reduction
-      - Billing adjustments
-      - Data retention policies
-      - Service level changes
-      - Customer retention strategies
-
-      Flexible downgrade options can prevent complete cancellations.
-    icon: ArrowDownCircle
-  - id: Cancellation
-    name: Cancellation
-    summary: "The termination of a subscription service."
-    description: |
-      Cancellation processes handle the end of subscription relationships. They cover:
-
-      - Notice periods
-      - Final billing
-      - Data retention/export
-      - Service access termination
-      - Reactivation options
-
-      Clear cancellation policies protect both customer and provider interests.
-    icon: XCircle
-  - id: Usage Limit
-    name: Usage Limit
-    summary: "Restrictions on service usage within a subscription plan."
-    description: |
-      Usage limits define the boundaries of service consumption. They include:
-
-      - Quantitative restrictions
-      - Monitoring systems
-      - Overage handling
-      - Alert mechanisms
-      - Upgrade triggers
-
-      Well-defined limits help manage resources and encourage appropriate plan selection.
-    icon: Gauge
----
diff --git a/examples/default/domains/Fulfilment/entities/inventory-reservation/index.mdx b/examples/default/domains/Fulfilment/entities/inventory-reservation/index.mdx
new file mode 100644
index 000000000..90be074fc
--- /dev/null
+++ b/examples/default/domains/Fulfilment/entities/inventory-reservation/index.mdx
@@ -0,0 +1,39 @@
+---
+id: inventory-reservation
+name: Inventory Reservation
+version: 1.0.0
+identifier: reservationId
+aggregateRoot: true
+summary: Stock held for a checkout or order before fulfilment.
+owners:
+  - fulfilment-platform
+properties:
+  - name: reservationId
+    type: UUID
+    required: true
+    description: Unique reservation identifier.
+  - name: orderId
+    type: UUID
+    required: false
+    description: Order associated with the reservation once created.
+    references: order
+    relationType: reservedFor
+    referencesIdentifier: orderId
+  - name: productId
+    type: UUID
+    required: true
+    description: Product being reserved.
+    references: product
+    relationType: reserves
+    referencesIdentifier: productId
+  - name: expiresAt
+    type: datetime
+    required: true
+    description: Time the reservation expires if not committed.
+---
+
+## Overview
+
+Inventory Reservation is created during checkout by [[command|reserve-inventory]] and released if the saga fails.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Fulfilment/entities/shipment/index.mdx b/examples/default/domains/Fulfilment/entities/shipment/index.mdx
new file mode 100644
index 000000000..112fc465e
--- /dev/null
+++ b/examples/default/domains/Fulfilment/entities/shipment/index.mdx
@@ -0,0 +1,36 @@
+---
+id: shipment
+name: Shipment
+version: 1.0.0
+identifier: shipmentId
+aggregateRoot: true
+summary: A carrier delivery for a packed customer order.
+owners:
+  - fulfilment-platform
+properties:
+  - name: shipmentId
+    type: UUID
+    required: true
+    description: Unique shipment identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order being shipped.
+    references: order
+    relationType: ships
+    referencesIdentifier: orderId
+  - name: carrierReference
+    type: string
+    required: false
+    description: External carrier tracking reference.
+  - name: status
+    type: string
+    required: true
+    description: Shipment delivery status.
+---
+
+## Overview
+
+Shipment is created by the Shipping System and updated from carrier events such as [[event|shipment-created]] and [[event|shipment-delivered]].
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Fulfilment/entities/stock-item/index.mdx b/examples/default/domains/Fulfilment/entities/stock-item/index.mdx
new file mode 100644
index 000000000..5fc776df4
--- /dev/null
+++ b/examples/default/domains/Fulfilment/entities/stock-item/index.mdx
@@ -0,0 +1,36 @@
+---
+id: stock-item
+name: Stock Item
+version: 1.0.0
+identifier: stockItemId
+aggregateRoot: true
+summary: The inventory record for a product variant at a location.
+owners:
+  - fulfilment-platform
+properties:
+  - name: stockItemId
+    type: UUID
+    required: true
+    description: Unique stock item identifier.
+  - name: productId
+    type: UUID
+    required: true
+    description: Product held in stock.
+    references: product
+    relationType: stocks
+    referencesIdentifier: productId
+  - name: locationId
+    type: string
+    required: true
+    description: Warehouse or fulfilment location.
+  - name: availableQuantity
+    type: integer
+    required: true
+    description: Quantity available to reserve.
+---
+
+## Overview
+
+Stock Item is the Inventory System's view of available stock for a product at a fulfilment location.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Fulfilment/entities/warehouse-pick/index.mdx b/examples/default/domains/Fulfilment/entities/warehouse-pick/index.mdx
new file mode 100644
index 000000000..8629f8403
--- /dev/null
+++ b/examples/default/domains/Fulfilment/entities/warehouse-pick/index.mdx
@@ -0,0 +1,35 @@
+---
+id: warehouse-pick
+name: Warehouse Pick
+version: 1.0.0
+identifier: pickId
+summary: A warehouse task to pick items for a completed order.
+owners:
+  - fulfilment-platform
+properties:
+  - name: pickId
+    type: UUID
+    required: true
+    description: Unique warehouse pick identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order being picked.
+    references: order
+    relationType: fulfils
+    referencesIdentifier: orderId
+  - name: assignedTo
+    type: string
+    required: false
+    description: Warehouse worker or automation lane assigned.
+  - name: status
+    type: string
+    required: true
+    description: Pick task status.
+---
+
+## Overview
+
+Warehouse Pick represents the operational task handled by the Warehouse System before an order can be packed and shipped.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Fulfilment/index.mdx b/examples/default/domains/Fulfilment/index.mdx
new file mode 100644
index 000000000..804091abb
--- /dev/null
+++ b/examples/default/domains/Fulfilment/index.mdx
@@ -0,0 +1,83 @@
+---
+id: fulfilment
+name: Fulfilment
+version: 1.0.0
+summary: |
+  The Fulfilment domain gets a confirmed order to the customer. It reserves stock, picks and packs orders in the warehouse, and hands them to carriers for delivery.
+owners:
+  - fulfilment-platform
+systems:
+  - id: inventory-system
+    version: 1.0.0
+  - id: warehouse-system
+    version: 1.0.0
+  - id: shipping-system
+    version: 1.0.0
+  - id: carrier
+    version: 1.0.0
+entities:
+  - id: stock-item
+    version: 1.0.0
+  - id: inventory-reservation
+    version: 1.0.0
+  - id: warehouse-pick
+    version: 1.0.0
+  - id: shipment
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Fulfilment** domain is responsible for the physical side of an order — making sure stock is available, picking and packing it, and shipping it to the customer. It owns three internal systems and integrates with external carriers:
+
+<Tiles>
+  <Tile
+    icon="ArchiveBoxIcon"
+    href="/docs/systems/inventory-system/1.0.0"
+    title="Inventory System"
+    description="Tracks and reserves stock for orders."
+  />
+  <Tile
+    icon="BuildingStorefrontIcon"
+    href="/docs/systems/warehouse-system/1.0.0"
+    title="Warehouse System"
+    description="Picks and packs orders ready for shipping."
+  />
+  <Tile
+    icon="TruckIcon"
+    href="/docs/systems/shipping-system/1.0.0"
+    title="Shipping System"
+    description="Hands packed orders to carriers for delivery."
+  />
+  <Tile
+    icon="GlobeAltIcon"
+    href="/docs/systems/carrier/1.0.0"
+    title="Carrier"
+    description="External carrier that delivers shipments to customers."
+  />
+</Tiles>
+
+### How the systems work together
+
+When an order is completed, the **Warehouse System** picks and packs it, having relied on the **Inventory System** to reserve stock earlier in checkout. Once packed, the **Shipping System** creates a shipment with an external **Carrier**, which delivers it to the customer and reports progress back.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The components that make up this domain.
+
+<NodeGraph />
diff --git a/examples/default/domains/Fulfilment/systems/carrier/index.mdx b/examples/default/domains/Fulfilment/systems/carrier/index.mdx
new file mode 100644
index 000000000..5b67f43b0
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/carrier/index.mdx
@@ -0,0 +1,52 @@
+---
+id: carrier
+name: Carrier
+version: 1.0.0
+scope: external
+summary: |
+  External carrier that delivers shipments to customers. It accepts shipment requests and reports delivery progress back.
+owners:
+  - fulfilment-platform
+services:
+  - id: carrier-shipping-api
+  - id: carrier-tracking-api
+relationships:
+  - id: shipping-system
+    label: delivers shipments for
+badges:
+  - content: External
+    backgroundColor: yellow
+    textColor: yellow
+    icon: GlobeAltIcon
+---
+
+## Overview
+
+The **Carrier** is the external delivery company Acme Inc uses to ship orders to customers. It is owned and operated by a third party — modelled here as an **external system** so the catalog shows how the [[system|shipping-system]] integrates with it.
+
+It receives [[command|create-shipment]] and reports progress back via [[event|shipment-created]], [[event|shipment-delivered]] and [[event|shipment-failed]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|carrier-shipping-api]] | Service | Accepts shipment requests and dispatches parcels. |
+| [[service\|carrier-tracking-api]] | Service | Reports delivery progress back to Acme Inc. |
+
+## Messages this system publishes
+
+- [[event\|shipment-created]] — a shipment has been created and dispatched.
+- [[event\|shipment-delivered]] — a shipment was delivered to the customer.
+- [[event\|shipment-failed]] — a shipment could not be delivered.
diff --git a/examples/default/domains/Fulfilment/systems/carrier/services/CarrierShippingAPI/index.mdx b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierShippingAPI/index.mdx
new file mode 100644
index 000000000..569692358
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierShippingAPI/index.mdx
@@ -0,0 +1,35 @@
+---
+id: carrier-shipping-api
+version: 1.0.0
+name: Shipping API
+summary: |
+  The carrier's API for creating shipments. Acme Inc's Shipping System calls it to dispatch packed orders.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: create-shipment
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/acme/carrier-integration'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Shipping API** is the carrier's external interface for creating shipments. The [[system|shipping-system]] sends [[command|create-shipment]], and the carrier dispatches the parcel and begins reporting progress through its [[service|carrier-tracking-api]].
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} message`} description="Shipment creation requests" />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/index.mdx b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/index.mdx
new file mode 100644
index 000000000..70f90f5de
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: shipment-created
+name: Shipment Created
+version: 1.0.0
+summary: |
+  Published by the carrier when a shipment has been created and dispatched.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ShipmentCreated` is published by the carrier's [[service|carrier-tracking-api]] when a shipment has been created and dispatched. Acme Inc consumes it to give the customer a tracking number and expected delivery date.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/schema.json b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/schema.json
new file mode 100644
index 000000000..872fd4173
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/schema.json
@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ShipmentCreated",
+  "description": "Published when a shipment has been created and dispatched",
+  "type": "object",
+  "properties": {
+    "shipmentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "trackingNumber": { "type": "string" },
+    "carrier": { "type": "string" },
+    "estimatedDelivery": { "type": "string", "format": "date" },
+    "createdAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["shipmentId", "orderId", "trackingNumber", "createdAt"]
+}
diff --git a/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/index.mdx b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/index.mdx
new file mode 100644
index 000000000..9ff7eb04f
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/index.mdx
@@ -0,0 +1,29 @@
+---
+id: shipment-delivered
+name: Shipment Delivered
+version: 1.0.0
+summary: |
+  Published by the carrier when a shipment has been delivered to the customer.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ShipmentDelivered` is published by the carrier's [[service|carrier-tracking-api]] when a shipment reaches the customer. This is the happy-path end of the fulfilment journey — Acme Inc consumes it to close out the order and prompt the customer for feedback.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/schema.json b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/schema.json
new file mode 100644
index 000000000..d8966a5d4
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/schema.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ShipmentDelivered",
+  "description": "Published when a shipment has been delivered to the customer",
+  "type": "object",
+  "properties": {
+    "shipmentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "deliveredAt": { "type": "string", "format": "date-time" },
+    "signedBy": { "type": "string", "description": "Name of the person who accepted delivery, if captured" }
+  },
+  "required": ["shipmentId", "orderId", "deliveredAt"]
+}
diff --git a/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/index.mdx b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/index.mdx
new file mode 100644
index 000000000..a008409c5
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/index.mdx
@@ -0,0 +1,29 @@
+---
+id: shipment-failed
+name: Shipment Failed
+version: 1.0.0
+summary: |
+  Published by the carrier when a shipment could not be delivered.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ShipmentFailed` is published by the carrier's [[service|carrier-tracking-api]] when a shipment cannot be delivered — for example a failed delivery attempt or a lost parcel. Acme Inc consumes it to trigger a redelivery, refund, or customer follow-up.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/schema.json b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/schema.json
new file mode 100644
index 000000000..56691ec17
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/schema.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ShipmentFailed",
+  "description": "Published when a shipment could not be delivered",
+  "type": "object",
+  "properties": {
+    "shipmentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "reason": {
+      "type": "string",
+      "enum": ["FAILED_DELIVERY", "LOST", "DAMAGED", "RETURNED_TO_SENDER"]
+    },
+    "failedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["shipmentId", "orderId", "reason", "failedAt"]
+}
diff --git a/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/index.mdx b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/index.mdx
new file mode 100644
index 000000000..727f92185
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/index.mdx
@@ -0,0 +1,39 @@
+---
+id: carrier-tracking-api
+version: 1.0.0
+name: Tracking API
+summary: |
+  The carrier's API for reporting delivery progress. It notifies Acme Inc when a shipment is created, delivered, or fails.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - fulfilment-platform
+sends:
+  - id: shipment-created
+    version: 1.0.0
+  - id: shipment-delivered
+    version: 1.0.0
+  - id: shipment-failed
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/acme/carrier-integration'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Tracking API** is how the carrier reports delivery progress back to Acme Inc. After a shipment is created via the [[service|carrier-shipping-api]], it emits [[event|shipment-created]], then [[event|shipment-delivered]] on success or [[event|shipment-failed]] if delivery cannot be completed.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="Shipment lifecycle events" />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/index.mdx b/examples/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/index.mdx
new file mode 100644
index 000000000..bd2a00b8b
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/index.mdx
@@ -0,0 +1,35 @@
+---
+id: inventory-database
+name: Inventory Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for stock levels and reservations.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for stock levels and reservations
+classification: internal
+retention: 3y
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Inventory Database** is the authoritative store for stock levels at Acme Inc. The [[service|inventory-service]] reads from and writes to it as stock is reserved and released.
+
+### What does it store?
+
+- **Stock** — one row per product: available quantity and reserved quantity.
+- **Reservations** — one row per reservation: id, order, items and status.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Inventory Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
diff --git a/examples/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/schema.sql b/examples/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/schema.sql
new file mode 100644
index 000000000..ff2a97fbb
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/schema.sql
@@ -0,0 +1,26 @@
+-- Inventory Database — system of record for stock levels and reservations
+
+CREATE TABLE stock (
+    product_id  UUID PRIMARY KEY,
+    available   INTEGER NOT NULL DEFAULT 0 CHECK (available >= 0),
+    reserved    INTEGER NOT NULL DEFAULT 0 CHECK (reserved >= 0),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE reservations (
+    reservation_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    order_id       UUID,
+    cart_id        UUID,
+    status         TEXT NOT NULL DEFAULT 'HELD'
+                     CHECK (status IN ('HELD', 'RELEASED', 'CONSUMED')),
+    created_at     TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE reservation_items (
+    reservation_id UUID NOT NULL REFERENCES reservations (reservation_id) ON DELETE CASCADE,
+    product_id     UUID NOT NULL,
+    quantity       INTEGER NOT NULL CHECK (quantity > 0),
+    PRIMARY KEY (reservation_id, product_id)
+);
+
+CREATE INDEX idx_reservations_order ON reservations (order_id);
diff --git a/examples/default/domains/Fulfilment/systems/inventory-system/index.mdx b/examples/default/domains/Fulfilment/systems/inventory-system/index.mdx
new file mode 100644
index 000000000..3419079bc
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/inventory-system/index.mdx
@@ -0,0 +1,49 @@
+---
+id: inventory-system
+name: Inventory System
+version: 1.0.0
+summary: |
+  Internal system that tracks stock and reserves it for orders. It is the source of truth for available inventory and confirms whether stock can be reserved.
+owners:
+  - fulfilment-platform
+services:
+  - id: inventory-service
+containers:
+  - id: inventory-database
+relationships:
+  - id: warehouse-system
+    label: provides stock for
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Inventory System** owns stock levels at Acme Inc. During checkout it receives [[command|reserve-inventory]] and confirms whether stock is available — replying with [[event|inventory-reserved]] or [[event|inventory-unavailable]]. It also handles [[command|release-inventory]] (when a reservation is no longer needed) and serves [[query|get-stock-level]] lookups from the [[container|inventory-database]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|inventory-service]] | Service | Reserves and releases stock, serves stock-level queries, and publishes inventory events. |
+| [[container\|inventory-database]] | Data store | PostgreSQL system of record for stock levels and reservations. |
+
+## Messages this system publishes
+
+- [[event\|inventory-reserved]] — stock was successfully reserved for an order.
+- [[event\|inventory-unavailable]] — stock could not be reserved.
diff --git a/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/index.mdx b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/index.mdx
new file mode 100644
index 000000000..38112a099
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/index.mdx
@@ -0,0 +1,32 @@
+---
+id: release-inventory
+name: Release Inventory
+version: 1.0.0
+summary: |
+  Command to release a previously held inventory reservation.
+owners:
+  - fulfilment-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /reservations/{reservationId}/release
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReleaseInventory` is handled by the [[service|inventory-service]]. It releases a reservation that is no longer needed — for example when checkout fails after stock was reserved, or an order is cancelled.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/schema.json b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/schema.json
new file mode 100644
index 000000000..6cdf190e5
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/schema.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReleaseInventory",
+  "description": "Command to release a previously held inventory reservation",
+  "type": "object",
+  "properties": {
+    "reservationId": { "type": "string", "format": "uuid" },
+    "reason": {
+      "type": "string",
+      "enum": ["CHECKOUT_FAILED", "ORDER_CANCELLED", "EXPIRED"]
+    }
+  },
+  "required": ["reservationId"]
+}
diff --git a/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/index.mdx b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/index.mdx
new file mode 100644
index 000000000..eb43f0380
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/index.mdx
@@ -0,0 +1,29 @@
+---
+id: inventory-reserved
+name: Inventory Reserved
+version: 1.0.0
+summary: |
+  Published when stock has been successfully reserved for an order.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`InventoryReserved` is published by the [[service|inventory-service]] when stock for an order has been successfully reserved. The Ordering domain's checkout saga relies on this to continue placing the order.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/schema.json b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/schema.json
new file mode 100644
index 000000000..c659aa8ad
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "InventoryReserved",
+  "description": "Published when stock has been successfully reserved for an order",
+  "type": "object",
+  "properties": {
+    "reservationId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "cartId": { "type": "string", "format": "uuid" },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": { "type": "string", "format": "uuid" },
+          "quantity": { "type": "integer", "minimum": 1 }
+        },
+        "required": ["productId", "quantity"]
+      }
+    },
+    "reservedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reservationId", "items", "reservedAt"]
+}
diff --git a/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/index.mdx b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/index.mdx
new file mode 100644
index 000000000..a9adad0c0
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/index.mdx
@@ -0,0 +1,29 @@
+---
+id: inventory-unavailable
+name: Inventory Unavailable
+version: 1.0.0
+summary: |
+  Published when stock could not be reserved for an order.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`InventoryUnavailable` is published by the [[service|inventory-service]] when stock for an order cannot be reserved. The Ordering domain's checkout saga uses it to fail checkout and cancel the order.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/schema.json b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/schema.json
new file mode 100644
index 000000000..f57559daf
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "InventoryUnavailable",
+  "description": "Published when stock could not be reserved for an order",
+  "type": "object",
+  "properties": {
+    "orderId": { "type": "string", "format": "uuid" },
+    "cartId": { "type": "string", "format": "uuid" },
+    "unavailableItems": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": { "type": "string", "format": "uuid" },
+          "requested": { "type": "integer", "minimum": 1 },
+          "available": { "type": "integer", "minimum": 0 }
+        },
+        "required": ["productId", "requested", "available"]
+      }
+    },
+    "checkedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["unavailableItems", "checkedAt"]
+}
diff --git a/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/index.mdx b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/index.mdx
new file mode 100644
index 000000000..7a3a43ff1
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/index.mdx
@@ -0,0 +1,57 @@
+---
+id: inventory-service
+version: 1.0.0
+name: Inventory Service
+summary: |
+  The system of record for stock. Reserves and releases inventory, serves stock-level queries, and publishes events when stock is reserved or unavailable.
+styles:
+  icon: /icons/languages/java.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: reserve-inventory
+    version: 1.0.0
+  - id: release-inventory
+    version: 1.0.0
+  - id: get-stock-level
+    version: 1.0.0
+sends:
+  - id: inventory-reserved
+    version: 1.0.0
+  - id: inventory-unavailable
+    version: 1.0.0
+writesTo:
+  - id: inventory-database
+readsFrom:
+  - id: inventory-database
+repository:
+  language: Java
+  url: 'https://github.com/acme/inventory-service'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Inventory Service** is the heart of the Inventory System. It receives [[command|reserve-inventory]] during checkout and replies with [[event|inventory-reserved]] or [[event|inventory-unavailable]]. It also handles [[command|release-inventory]] and serves [[query|get-stock-level]] reads, all backed by the [[container|inventory-database]].
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="Inventory outcomes" />
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="Inventory commands and queries" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Reservations | Handles [[command\|reserve-inventory]] and [[command\|release-inventory]]. |
+| Lookups | Serves [[query\|get-stock-level]] from the [[container\|inventory-database]]. |
+| Event publishing | Emits [[event\|inventory-reserved]] and [[event\|inventory-unavailable]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/index.mdx b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/index.mdx
new file mode 100644
index 000000000..67c740a7a
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/index.mdx
@@ -0,0 +1,32 @@
+---
+id: get-stock-level
+name: Get Stock Level
+version: 1.0.0
+summary: |
+  Query to fetch the current available stock level for a product.
+owners:
+  - fulfilment-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /stock/{productId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetStockLevel` is handled by the [[service|inventory-service]]. It returns the current available stock for a product, read directly from the [[container|inventory-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/schema.json b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/schema.json
new file mode 100644
index 000000000..3e947c58e
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/schema.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetStockLevel",
+  "description": "Query to fetch the current available stock level for a product, and the level returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "type": "object",
+      "properties": {
+        "productId": { "type": "string", "format": "uuid" }
+      },
+      "required": ["productId"]
+    },
+    "response": {
+      "type": "object",
+      "properties": {
+        "productId": { "type": "string", "format": "uuid" },
+        "available": { "type": "integer", "minimum": 0 },
+        "reserved": { "type": "integer", "minimum": 0 }
+      },
+      "required": ["productId", "available"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/examples/default/domains/Fulfilment/systems/shipping-system/index.mdx b/examples/default/domains/Fulfilment/systems/shipping-system/index.mdx
new file mode 100644
index 000000000..9e37f5fda
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/shipping-system/index.mdx
@@ -0,0 +1,47 @@
+---
+id: shipping-system
+name: Shipping System
+version: 1.0.0
+summary: |
+  Internal system that hands packed orders to carriers. It reacts to ready-for-shipping orders and creates shipments with an external carrier.
+owners:
+  - fulfilment-platform
+services:
+  - id: shipping-api
+  - id: carrier-adapter
+relationships:
+  - id: carrier
+    label: creates shipments with
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Shipping System** connects Acme Inc to its carriers. When the [[system|warehouse-system]] publishes [[event|order-ready-for-shipping]], the [[service|shipping-api]] selects a carrier and the [[service|carrier-adapter]] sends a [[command|create-shipment]] to the external [[system|carrier]] to dispatch the parcel.
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|shipping-api]] | Service | Receives ready-for-shipping orders and selects a carrier. |
+| [[service\|carrier-adapter]] | Service | Translates and sends shipment requests to the external carrier. |
+
+## Messages this system sends
+
+- [[command\|create-shipment]] — create a shipment with the carrier.
diff --git a/examples/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/index.mdx b/examples/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/index.mdx
new file mode 100644
index 000000000..ec50cdffd
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/index.mdx
@@ -0,0 +1,32 @@
+---
+id: create-shipment
+name: Create Shipment
+version: 1.0.0
+summary: |
+  Command to create a shipment with a carrier for a packed order.
+owners:
+  - fulfilment-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /shipments
+  statusCodes: ['201', '400', '422']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CreateShipment` is sent by the [[service|carrier-adapter]] to the external [[system|carrier]] to dispatch a packed order. The carrier responds asynchronously with [[event|shipment-created]] and later [[event|shipment-delivered]] or [[event|shipment-failed]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/schema.json b/examples/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/schema.json
new file mode 100644
index 000000000..7e111d8dd
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/schema.json
@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CreateShipment",
+  "description": "Command to create a shipment with a carrier for a packed order",
+  "type": "object",
+  "properties": {
+    "orderId": { "type": "string", "format": "uuid" },
+    "carrier": { "type": "string", "description": "The carrier to ship with" },
+    "service": {
+      "type": "string",
+      "enum": ["STANDARD", "EXPRESS", "NEXT_DAY"]
+    },
+    "parcelCount": { "type": "integer", "minimum": 1 },
+    "destination": {
+      "type": "object",
+      "properties": {
+        "line1": { "type": "string" },
+        "city": { "type": "string" },
+        "postcode": { "type": "string" },
+        "country": { "type": "string", "pattern": "^[A-Z]{2}$" }
+      },
+      "required": ["line1", "city", "postcode", "country"]
+    }
+  },
+  "required": ["orderId", "destination"]
+}
diff --git a/examples/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/index.mdx b/examples/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/index.mdx
new file mode 100644
index 000000000..1d39e421c
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/index.mdx
@@ -0,0 +1,35 @@
+---
+id: carrier-adapter
+version: 1.0.0
+name: Carrier Adapter
+summary: |
+  Translates Acme Inc shipment requests into the external carrier's format and sends them to create a shipment.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - fulfilment-platform
+sends:
+  - id: create-shipment
+    version: 1.0.0
+repository:
+  language: Go
+  url: 'https://github.com/acme/carrier-adapter'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Carrier Adapter** is the anti-corruption layer between Acme Inc and its carriers. It takes a shipment request from the [[service|shipping-api]], maps it to the external [[system|carrier]]'s API, and sends a [[command|create-shipment]] to dispatch the parcel.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} message`} description="The create-shipment command" />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/shipping-system/services/ShippingAPI/index.mdx b/examples/default/domains/Fulfilment/systems/shipping-system/services/ShippingAPI/index.mdx
new file mode 100644
index 000000000..cfb8f2f9d
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/shipping-system/services/ShippingAPI/index.mdx
@@ -0,0 +1,35 @@
+---
+id: shipping-api
+version: 1.0.0
+name: Shipping API
+summary: |
+  Receives ready-for-shipping orders, selects a carrier, and kicks off shipment creation.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: order-ready-for-shipping
+    version: 1.0.0
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/shipping-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Shipping API** is the entry point to the Shipping System. It consumes [[event|order-ready-for-shipping]] from the [[system|warehouse-system]], selects an appropriate carrier, and hands off to the [[service|carrier-adapter]] to create the shipment.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} message`} description="Ready-for-shipping orders" />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/warehouse-system/containers/warehouse-database/index.mdx b/examples/default/domains/Fulfilment/systems/warehouse-system/containers/warehouse-database/index.mdx
new file mode 100644
index 000000000..8386572f5
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/warehouse-system/containers/warehouse-database/index.mdx
@@ -0,0 +1,35 @@
+---
+id: warehouse-database
+name: Warehouse Database
+version: 1.0.0
+summary: PostgreSQL database that stores picking jobs and their status.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for picking and packing jobs
+classification: internal
+retention: 1y
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Warehouse Database** stores the picking and packing jobs for the warehouse. The [[service|warehouse-service]] creates jobs and the [[service|picking-worker]] updates them as orders are picked.
+
+### What does it store?
+
+- **Picking Jobs** — one row per order being fulfilled: order, status and timestamps.
+- **Picking Job Items** — the items to pick for each job.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Warehouse Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
diff --git a/examples/default/domains/Fulfilment/systems/warehouse-system/containers/warehouse-database/schema.sql b/examples/default/domains/Fulfilment/systems/warehouse-system/containers/warehouse-database/schema.sql
new file mode 100644
index 000000000..742b44d30
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/warehouse-system/containers/warehouse-database/schema.sql
@@ -0,0 +1,21 @@
+-- Warehouse Database — picking and packing jobs
+
+CREATE TABLE picking_jobs (
+    job_id      UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    order_id    UUID NOT NULL,
+    status      TEXT NOT NULL DEFAULT 'CREATED'
+                  CHECK (status IN ('CREATED', 'PICKING', 'PACKED')),
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE picking_job_items (
+    job_id      UUID NOT NULL REFERENCES picking_jobs (job_id) ON DELETE CASCADE,
+    product_id  UUID NOT NULL,
+    quantity    INTEGER NOT NULL CHECK (quantity > 0),
+    picked      BOOLEAN NOT NULL DEFAULT false,
+    PRIMARY KEY (job_id, product_id)
+);
+
+CREATE INDEX idx_picking_jobs_order  ON picking_jobs (order_id);
+CREATE INDEX idx_picking_jobs_status ON picking_jobs (status);
diff --git a/examples/default/domains/Fulfilment/systems/warehouse-system/index.mdx b/examples/default/domains/Fulfilment/systems/warehouse-system/index.mdx
new file mode 100644
index 000000000..d99b11b04
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/warehouse-system/index.mdx
@@ -0,0 +1,53 @@
+---
+id: warehouse-system
+name: Warehouse System
+version: 1.0.0
+summary: |
+  Internal system that picks and packs orders in the warehouse. It reacts to completed orders, organises picking, and signals when an order is packed and ready to ship.
+owners:
+  - fulfilment-platform
+services:
+  - id: warehouse-service
+  - id: picking-worker
+containers:
+  - id: warehouse-database
+relationships:
+  - id: shipping-system
+    label: hands packed orders to
+  - id: inventory-system
+    label: consumes reserved stock from
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Warehouse System** turns a completed order into a packed parcel. When the Ordering domain publishes [[event|order-completed]], the [[service|warehouse-service]] creates a picking job, the [[service|picking-worker]] works through it, and the system publishes [[event|order-packed]] and then [[event|order-ready-for-shipping]] for the [[system|shipping-system]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|warehouse-service]] | Service | Receives completed orders and orchestrates picking and packing. |
+| [[service\|picking-worker]] | Service | Works through picking jobs on the warehouse floor. |
+| [[container\|warehouse-database]] | Data store | PostgreSQL store of picking jobs and their status. |
+
+## Messages this system publishes
+
+- [[event\|order-packed]] — an order has been picked and packed.
+- [[event\|order-ready-for-shipping]] — a packed order is ready to be shipped.
diff --git a/examples/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/index.mdx b/examples/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/index.mdx
new file mode 100644
index 000000000..5036db236
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/index.mdx
@@ -0,0 +1,29 @@
+---
+id: order-packed
+name: Order Packed
+version: 1.0.0
+summary: |
+  Published when an order has been picked and packed in the warehouse.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderPacked` is published by the [[service|picking-worker]] when an order has been fully picked and packed. The [[service|warehouse-service]] consumes it to mark the order ready and publish [[event|order-ready-for-shipping]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/schema.json b/examples/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/schema.json
new file mode 100644
index 000000000..f588ac7f7
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/schema.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderPacked",
+  "description": "Published when an order has been picked and packed in the warehouse",
+  "type": "object",
+  "properties": {
+    "orderId": { "type": "string", "format": "uuid" },
+    "pickingJobId": { "type": "string", "format": "uuid" },
+    "parcelCount": { "type": "integer", "minimum": 1 },
+    "packedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["orderId", "packedAt"]
+}
diff --git a/examples/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/index.mdx b/examples/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/index.mdx
new file mode 100644
index 000000000..c6033c8be
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/index.mdx
@@ -0,0 +1,39 @@
+---
+id: picking-worker
+version: 1.0.0
+name: Picking Worker
+summary: |
+  Works through picking jobs on the warehouse floor and signals when an order has been picked and packed.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - fulfilment-platform
+sends:
+  - id: order-packed
+    version: 1.0.0
+readsFrom:
+  - id: warehouse-database
+writesTo:
+  - id: warehouse-database
+repository:
+  language: Go
+  url: 'https://github.com/acme/picking-worker'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Picking Worker** processes picking jobs created by the [[service|warehouse-service]]. As warehouse staff pick and pack each order, the worker updates the job in the [[container|warehouse-database]] and publishes [[event|order-packed]] when the order is complete.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} message`} description="The order-packed event" />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/index.mdx b/examples/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/index.mdx
new file mode 100644
index 000000000..58a86231c
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/index.mdx
@@ -0,0 +1,29 @@
+---
+id: order-ready-for-shipping
+name: Order Ready For Shipping
+version: 1.0.0
+summary: |
+  Published when a packed order is ready to be handed to a carrier for shipping.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderReadyForShipping` is published by the [[service|warehouse-service]] once an order has been packed. The [[system|shipping-system]] consumes it to create a shipment with a carrier.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/schema.json b/examples/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/schema.json
new file mode 100644
index 000000000..f903e40aa
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/schema.json
@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderReadyForShipping",
+  "description": "Published when a packed order is ready to be handed to a carrier",
+  "type": "object",
+  "properties": {
+    "orderId": { "type": "string", "format": "uuid" },
+    "customerId": { "type": "string", "format": "uuid" },
+    "parcelCount": { "type": "integer", "minimum": 1 },
+    "shippingAddress": {
+      "type": "object",
+      "properties": {
+        "line1": { "type": "string" },
+        "city": { "type": "string" },
+        "postcode": { "type": "string" },
+        "country": { "type": "string", "pattern": "^[A-Z]{2}$" }
+      },
+      "required": ["line1", "city", "postcode", "country"]
+    },
+    "readyAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["orderId", "shippingAddress", "readyAt"]
+}
diff --git a/examples/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/index.mdx b/examples/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/index.mdx
new file mode 100644
index 000000000..b08b802f5
--- /dev/null
+++ b/examples/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/index.mdx
@@ -0,0 +1,43 @@
+---
+id: warehouse-service
+version: 1.0.0
+name: Warehouse Service
+summary: |
+  Orchestrates picking and packing in the warehouse. It reacts to completed orders, creates picking jobs, and signals when an order is ready to ship.
+styles:
+  icon: /icons/languages/java.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: order-completed
+    version: 1.0.0
+sends:
+  - id: order-ready-for-shipping
+    version: 1.0.0
+writesTo:
+  - id: warehouse-database
+readsFrom:
+  - id: warehouse-database
+repository:
+  language: Java
+  url: 'https://github.com/acme/warehouse-service'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Warehouse Service** runs warehousing. When the Ordering domain publishes [[event|order-completed]], it creates a picking job in the [[container|warehouse-database]] for the [[service|picking-worker]] to work through. Once the order is packed it publishes [[event|order-ready-for-shipping]] for the [[system|shipping-system]].
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} message`} description="Ready-for-shipping signal" />
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} message`} description="Completed orders to fulfil" />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Fulfilment/ubiquitous-language.mdx b/examples/default/domains/Fulfilment/ubiquitous-language.mdx
new file mode 100644
index 000000000..880e4c151
--- /dev/null
+++ b/examples/default/domains/Fulfilment/ubiquitous-language.mdx
@@ -0,0 +1,44 @@
+---
+dictionary:
+  - id: Fulfilment
+    name: Fulfilment
+    summary: "Everything that gets a confirmed order physically to the customer — stock, packing and shipping."
+    icon: PackageCheck
+  - id: Stock
+    name: Stock
+    summary: "The quantity of a product physically available to sell."
+    description: |
+      Stock is owned by the Inventory System. Each product has an available quantity and a reserved
+      quantity. Stock is the source of truth for whether an order can be fulfilled.
+    icon: Boxes
+  - id: Reservation
+    name: Reservation
+    summary: "A temporary hold on stock for a specific order, taken during checkout."
+    description: |
+      A reservation guarantees stock is set aside for an order while payment is taken. It is held,
+      then either consumed when the order ships or released if checkout fails.
+    icon: BookmarkCheck
+  - id: Picking
+    name: Picking
+    summary: "Collecting an order's items from the warehouse shelves."
+    icon: Hand
+  - id: Packing
+    name: Packing
+    summary: "Boxing up a picked order into one or more parcels ready for shipping."
+    icon: Package
+  - id: Shipment
+    name: Shipment
+    summary: "A packed order handed to a carrier for delivery, tracked from dispatch to delivery."
+    description: |
+      A shipment is created with an external carrier once an order is packed. Its lifecycle —
+      created, delivered or failed — is reported back by the carrier.
+    icon: Truck
+  - id: Carrier
+    name: Carrier
+    summary: "The external delivery company that transports shipments to customers."
+    icon: Globe
+  - id: Tracking Number
+    name: Tracking Number
+    summary: "A code from the carrier that lets the customer follow a shipment's progress."
+    icon: ScanBarcode
+---
diff --git a/examples/default/domains/Ordering/entities/checkout-session/index.mdx b/examples/default/domains/Ordering/entities/checkout-session/index.mdx
new file mode 100644
index 000000000..b247c6c8a
--- /dev/null
+++ b/examples/default/domains/Ordering/entities/checkout-session/index.mdx
@@ -0,0 +1,36 @@
+---
+id: checkout-session
+name: Checkout Session
+version: 1.0.0
+identifier: checkoutSessionId
+aggregateRoot: true
+summary: The orchestration state for turning a checked-out cart into an order.
+owners:
+  - ordering-platform
+properties:
+  - name: checkoutSessionId
+    type: UUID
+    required: true
+    description: Unique checkout session identifier.
+  - name: cartId
+    type: UUID
+    required: true
+    description: Cart being checked out.
+    references: cart
+    relationType: startsFrom
+    referencesIdentifier: cartId
+  - name: status
+    type: string
+    required: true
+    description: Current checkout state.
+  - name: startedAt
+    type: datetime
+    required: true
+    description: Time checkout orchestration started.
+---
+
+## Overview
+
+Checkout Session tracks the saga managed by [[service|checkout-orchestrator]] across inventory reservation, payment authorization and order creation.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Ordering/entities/order-line/index.mdx b/examples/default/domains/Ordering/entities/order-line/index.mdx
new file mode 100644
index 000000000..f0159af8d
--- /dev/null
+++ b/examples/default/domains/Ordering/entities/order-line/index.mdx
@@ -0,0 +1,38 @@
+---
+id: order-line
+name: Order Line
+version: 1.0.0
+identifier: orderLineId
+summary: A purchased product and quantity within an order.
+owners:
+  - ordering-platform
+properties:
+  - name: orderLineId
+    type: UUID
+    required: true
+    description: Unique order line identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order this line belongs to.
+    references: order
+    relationType: belongsTo
+    referencesIdentifier: orderId
+  - name: productId
+    type: UUID
+    required: true
+    description: Product purchased.
+    references: product
+    relationType: references
+    referencesIdentifier: productId
+  - name: quantity
+    type: integer
+    required: true
+    description: Quantity purchased.
+---
+
+## Overview
+
+Order Line snapshots the products bought at checkout. It should not replace the Catalog domain's authoritative product data.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Ordering/entities/order-status-history/index.mdx b/examples/default/domains/Ordering/entities/order-status-history/index.mdx
new file mode 100644
index 000000000..384955a68
--- /dev/null
+++ b/examples/default/domains/Ordering/entities/order-status-history/index.mdx
@@ -0,0 +1,35 @@
+---
+id: order-status-history
+name: Order Status History
+version: 1.0.0
+identifier: orderStatusHistoryId
+summary: Audit history of order lifecycle state changes.
+owners:
+  - ordering-platform
+properties:
+  - name: orderStatusHistoryId
+    type: UUID
+    required: true
+    description: Unique status history record.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order whose status changed.
+    references: order
+    relationType: belongsTo
+    referencesIdentifier: orderId
+  - name: status
+    type: string
+    required: true
+    description: New order status.
+  - name: changedAt
+    type: datetime
+    required: true
+    description: Time the status changed.
+---
+
+## Overview
+
+Order Status History provides an audit trail for customer support, fulfilment exceptions and order lifecycle debugging.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Ordering/entities/order/index.mdx b/examples/default/domains/Ordering/entities/order/index.mdx
new file mode 100644
index 000000000..685a479ca
--- /dev/null
+++ b/examples/default/domains/Ordering/entities/order/index.mdx
@@ -0,0 +1,36 @@
+---
+id: order
+name: Order
+version: 1.0.0
+identifier: orderId
+aggregateRoot: true
+summary: The durable customer order created after successful checkout.
+owners:
+  - ordering-platform
+properties:
+  - name: orderId
+    type: UUID
+    required: true
+    description: Unique order identifier.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer who placed the order.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: status
+    type: string
+    required: true
+    description: Current order lifecycle state.
+  - name: totalAmount
+    type: decimal
+    required: true
+    description: Total order value at creation.
+---
+
+## Overview
+
+Order is the main aggregate in [[system|order-management-system]]. It emits order lifecycle events used by Fulfilment and support workflows.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Ordering/flows/PlaceAnOrder/index.mdx b/examples/default/domains/Ordering/flows/PlaceAnOrder/index.mdx
new file mode 100644
index 000000000..97eaca900
--- /dev/null
+++ b/examples/default/domains/Ordering/flows/PlaceAnOrder/index.mdx
@@ -0,0 +1,158 @@
+---
+id: place-an-order
+name: Place an Order
+version: 1.0.0
+summary: |
+  The end-to-end journey from a customer checking out their cart to a confirmed order — spanning the Shopping and Ordering domains, including the checkout saga and its failure path.
+owners:
+  - ordering-platform
+steps:
+  - id: shopper_checks_out
+    title: Shopper checks out
+    actor:
+      name: Shopper
+      summary: The customer confirms their cart and starts checkout.
+    next_step:
+      id: checkout_cart_command
+      label: Check out cart
+
+  - id: checkout_cart_command
+    title: Checkout Cart
+    message:
+      id: checkout-cart
+      version: 1.0.0
+    next_step:
+      id: cart_api
+      label: Price and finalise cart
+
+  - id: cart_api
+    title: Cart API
+    service:
+      id: cart-api
+      version: 1.0.0
+    next_step:
+      id: cart_checked_out
+      label: Publish checkout
+
+  - id: cart_checked_out
+    title: Cart Checked Out
+    message:
+      id: cart-checked-out
+      version: 1.0.0
+    next_step:
+      id: checkout_api
+      label: Start checkout flow
+
+  - id: checkout_api
+    title: Checkout API
+    service:
+      id: checkout-api
+      version: 1.0.0
+    next_step:
+      id: checkout_orchestrator
+      label: Run checkout saga
+
+  - id: checkout_orchestrator
+    title: Checkout Orchestrator
+    service:
+      id: checkout-orchestrator
+      version: 1.0.0
+    next_steps:
+      - id: reserve_inventory
+        label: Reserve inventory
+      - id: authorize_payment
+        label: Authorize payment
+
+  - id: reserve_inventory
+    title: Reserve Inventory
+    message:
+      id: reserve-inventory
+      version: 1.0.0
+    next_step:
+      id: authorize_payment
+      label: Inventory held
+
+  - id: authorize_payment
+    title: Authorize Payment
+    message:
+      id: authorize-payment
+      version: 1.0.0
+    next_steps:
+      - id: create_order
+        label: Payment authorized
+      - id: checkout_failed
+        label: Authorization declined
+
+  - id: create_order
+    title: Create Order
+    message:
+      id: create-order
+      version: 1.0.0
+    next_step:
+      id: order_service
+      label: Persist order
+
+  - id: order_service
+    title: Order Service
+    service:
+      id: order-service
+      version: 1.0.0
+    next_step:
+      id: order_created
+      label: Publish order created
+
+  - id: order_created
+    title: Order Created
+    message:
+      id: order-created
+      version: 1.0.0
+    next_step:
+      id: order_confirmed
+      label: Confirm to customer
+
+  - id: order_confirmed
+    title: Order confirmed
+    custom:
+      title: Order confirmed
+      color: green
+      icon: CheckCircleIcon
+      type: Outcome
+      summary: The customer's order is placed and confirmed. Fulfilment begins.
+      properties:
+        happy_path: 'true'
+
+  - id: checkout_failed
+    title: Checkout failed
+    custom:
+      title: Checkout failed
+      color: red
+      icon: ExclamationTriangleIcon
+      type: Exception
+      summary: A checkout step failed (e.g. payment declined). The orchestrator compensates earlier steps and cancels the order.
+      properties:
+        common_causes: 'payment declined, out of stock'
+        next_action: 'release reservation, void authorization, cancel order'
+    next_step:
+      id: order_cancelled
+      label: Cancel order
+
+  - id: order_cancelled
+    title: Order Cancelled
+    message:
+      id: order-cancelled
+      version: 1.0.0
+---
+
+## Overview
+
+**Place an Order** is the headline business flow at Acme Inc. It begins in the [[domain|shopping]] domain, when a shopper checks out their cart, and finishes in the [[domain|ordering]] domain, with a confirmed order — or a compensated, cancelled one if a step fails.
+
+<NodeGraph />
+
+## How it works
+
+1. The shopper checks out — the [[service|cart-api]] prices the cart and publishes [[event|cart-checked-out]].
+2. The [[service|checkout-api]] picks this up and hands it to the [[service|checkout-orchestrator]].
+3. The orchestrator runs the saga: [[command|reserve-inventory]] then [[command|authorize-payment]].
+4. On success it sends [[command|create-order]] to the [[service|order-service]], which publishes [[event|order-created]].
+5. If any step fails, the orchestrator compensates the earlier steps and the order is cancelled via [[event|order-cancelled]].
diff --git a/examples/default/domains/Ordering/index.mdx b/examples/default/domains/Ordering/index.mdx
new file mode 100644
index 000000000..3c7418b90
--- /dev/null
+++ b/examples/default/domains/Ordering/index.mdx
@@ -0,0 +1,70 @@
+---
+id: ordering
+name: Ordering
+version: 1.0.0
+summary: |
+  The Ordering domain turns a checked-out cart into a confirmed order. It orchestrates checkout — reserving inventory, authorizing payment and creating the order — and owns the lifecycle of every order.
+owners:
+  - ordering-platform
+systems:
+  - id: checkout-system
+    version: 1.0.0
+  - id: order-management-system
+    version: 1.0.0
+flows:
+  - id: place-an-order
+    version: 1.0.0
+entities:
+  - id: checkout-session
+    version: 1.0.0
+  - id: order
+    version: 1.0.0
+  - id: order-line
+    version: 1.0.0
+  - id: order-status-history
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Ordering** domain is responsible for everything that happens once a customer commits to buy — from the moment their cart is checked out to a confirmed, fulfilled order. It is split into two systems:
+
+<Tiles>
+  <Tile
+    icon="CreditCardIcon"
+    href="/docs/systems/checkout-system/1.0.0"
+    title="Checkout System"
+    description="Orchestrates checkout — reserves inventory, authorizes payment and creates the order."
+  />
+  <Tile
+    icon="ClipboardDocumentListIcon"
+    href="/docs/systems/order-management-system/1.0.0"
+    title="Order Management System"
+    description="System of record for orders and their lifecycle."
+  />
+</Tiles>
+
+### How the systems work together
+
+When the [[domain|shopping]] domain checks out a cart, the **Checkout System** takes over. It orchestrates the steps needed to place an order — reserving inventory, authorizing payment, and finally asking the **Order Management System** to create the order. The Order Management System then owns that order for the rest of its life, publishing events as it is created, completed or cancelled.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The components that make up this domain.
+
+<NodeGraph />
diff --git a/examples/default/domains/Ordering/systems/checkout-system/flows/CheckoutSaga/index.mdx b/examples/default/domains/Ordering/systems/checkout-system/flows/CheckoutSaga/index.mdx
new file mode 100644
index 000000000..90fa12e5d
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/checkout-system/flows/CheckoutSaga/index.mdx
@@ -0,0 +1,101 @@
+---
+id: checkout-saga
+name: Checkout Saga
+version: 1.0.0
+summary: |
+  How the Checkout Orchestrator turns a checked-out cart into an order — reserving inventory, authorizing payment and creating the order, with compensation when a step fails.
+owners:
+  - ordering-platform
+steps:
+  - id: cart_checked_out
+    title: Cart Checked Out
+    message:
+      id: cart-checked-out
+      version: 1.0.0
+    next_step:
+      id: checkout_api
+      label: Receive checkout
+
+  - id: checkout_api
+    title: Checkout API
+    service:
+      id: checkout-api
+      version: 1.0.0
+    next_step:
+      id: orchestrator
+      label: Start saga
+
+  - id: orchestrator
+    title: Checkout Orchestrator
+    service:
+      id: checkout-orchestrator
+      version: 1.0.0
+    next_step:
+      id: reserve_inventory
+      label: Step 1 — reserve inventory
+
+  - id: reserve_inventory
+    title: Reserve Inventory
+    message:
+      id: reserve-inventory
+      version: 1.0.0
+    next_steps:
+      - id: authorize_payment
+        label: Reserved
+      - id: compensate_release
+        label: Out of stock
+
+  - id: authorize_payment
+    title: Authorize Payment
+    message:
+      id: authorize-payment
+      version: 1.0.0
+    next_steps:
+      - id: create_order
+        label: Authorized
+      - id: compensate_release
+        label: Declined
+
+  - id: create_order
+    title: Create Order
+    message:
+      id: create-order
+      version: 1.0.0
+    next_step:
+      id: saga_complete
+      label: Order created
+
+  - id: saga_complete
+    title: Saga complete
+    custom:
+      title: Saga complete
+      color: green
+      icon: CheckCircleIcon
+      type: Outcome
+      summary: Inventory reserved, payment authorized and order created. The saga succeeds.
+
+  - id: compensate_release
+    title: Compensate
+    custom:
+      title: Compensate and abort
+      color: red
+      icon: ArrowUturnLeftIcon
+      type: Compensation
+      summary: A step failed. The orchestrator releases any reservation and voids any authorization, then aborts the saga without creating an order.
+      properties:
+        actions: 'release reservation, void authorization'
+---
+
+## Overview
+
+The **Checkout Saga** is the heart of the [[system|checkout-system]]. It coordinates the steps that turn a checked-out cart into a confirmed order. Each step has a compensating action so a failure never leaves the customer in an inconsistent state.
+
+<NodeGraph />
+
+## Steps
+
+1. **Reserve inventory** — [[command|reserve-inventory]] holds stock for the cart's items.
+2. **Authorize payment** — [[command|authorize-payment]] places a hold on the order total.
+3. **Create order** — [[command|create-order]] persists the order in the [[system|order-management-system]].
+
+If reservation or authorization fails, the orchestrator **compensates** — releasing the reservation and voiding the authorization — and aborts without creating an order.
diff --git a/examples/default/domains/Ordering/systems/checkout-system/index.mdx b/examples/default/domains/Ordering/systems/checkout-system/index.mdx
new file mode 100644
index 000000000..b1332cd8a
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/checkout-system/index.mdx
@@ -0,0 +1,57 @@
+---
+id: checkout-system
+name: Checkout System
+version: 1.0.0
+summary: |
+  Internal system that orchestrates checkout. When a cart is checked out it reserves inventory, authorizes payment, and asks the Order Management System to create the order.
+owners:
+  - ordering-platform
+services:
+  - id: checkout-api
+  - id: checkout-orchestrator
+flows:
+  - id: checkout-saga
+    version: 1.0.0
+relationships:
+  - id: order-management-system
+    label: creates orders via
+actors:
+  - id: shopper
+    name: Shopper
+    label: confirms checkout
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Checkout System** drives the checkout flow at Acme Inc. When the [[domain|shopping]] domain checks out a cart, the [[service|checkout-api]] receives the [[command|checkout-cart]] command and hands it to the [[service|checkout-orchestrator]]. The orchestrator runs the checkout saga — reserving inventory via [[command|reserve-inventory]], authorizing payment via [[command|authorize-payment]], and finally creating the order via [[command|create-order]] against the [[system|order-management-system]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|checkout-api]] | Service | Entry point for checkout. Receives the checkout command and starts the flow. |
+| [[service\|checkout-orchestrator]] | Service | Runs the checkout saga — reserve inventory, authorize payment, create order. |
+
+## Messages this system sends
+
+- [[command\|reserve-inventory]] — reserve stock for the items in the cart.
+- [[command\|authorize-payment]] — authorize payment for the order total.
+- [[command\|create-order]] — create the order in the Order Management System.
diff --git a/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutAPI/index.mdx b/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutAPI/index.mdx
new file mode 100644
index 000000000..96fd384bc
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutAPI/index.mdx
@@ -0,0 +1,43 @@
+---
+id: checkout-api
+version: 1.0.0
+name: Checkout API
+summary: |
+  The entry point to the Checkout System. Receives the checkout command from the Shopping domain and starts the checkout flow.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - ordering-platform
+receives:
+  - id: checkout-cart
+    version: 1.0.0
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/checkout-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Checkout API** is the front door to the Checkout System. When the [[domain|shopping]] domain checks out a cart, this service receives the [[command|checkout-cart]] command, validates it, and hands the work to the [[service|checkout-orchestrator]] to run the checkout saga.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} message`} description="The checkout command from Shopping" />
+  <Tile icon="RectangleGroupIcon" href="/docs/services/checkout-orchestrator/1.0.0" title="Delegates to the Orchestrator" description="The saga that runs checkout" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Checkout entry | Receives and validates [[command\|checkout-cart]] from the Shopping domain. |
+| Orchestration handoff | Starts a checkout saga in the [[service\|checkout-orchestrator]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/index.mdx b/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/index.mdx
new file mode 100644
index 000000000..d0489ec1e
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/index.mdx
@@ -0,0 +1,32 @@
+---
+id: authorize-payment
+name: Authorize Payment
+version: 1.0.0
+summary: |
+  Command to authorize payment for the total of a checked-out cart.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /payments/authorize
+  statusCodes: ['201', '400', '402', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`AuthorizePayment` is sent by the [[service|checkout-orchestrator]] to authorize payment for the order total. Authorization places a hold on the customer's payment method; the funds are captured once the order is created. If a later step fails, the authorization is voided.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/schema.json b/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/schema.json
new file mode 100644
index 000000000..f6cc128e4
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/schema.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AuthorizePayment",
+  "description": "Command to authorize payment for the total of a checked-out cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Identifier of the cart being checked out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "description": "Identifier of the customer paying",
+      "type": "string",
+      "format": "uuid"
+    },
+    "amount": {
+      "description": "Amount to authorize, in minor units (e.g. cents)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "currency": {
+      "description": "ISO 4217 currency code",
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    }
+  },
+  "required": ["cartId", "amount", "currency"]
+}
diff --git a/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/index.mdx b/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/index.mdx
new file mode 100644
index 000000000..a713a0228
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/index.mdx
@@ -0,0 +1,32 @@
+---
+id: reserve-inventory
+name: Reserve Inventory
+version: 1.0.0
+summary: |
+  Command to reserve stock for the items in a checked-out cart.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /reservations
+  statusCodes: ['201', '400', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReserveInventory` is sent by the [[service|checkout-orchestrator]] to hold stock for the items in a checked-out cart. A successful reservation guarantees the inventory is available while payment is authorized. If a later checkout step fails, the reservation is released.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/schema.json b/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/schema.json
new file mode 100644
index 000000000..c7702c1df
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/schema.json
@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReserveInventory",
+  "description": "Command to reserve stock for the items in a checked-out cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Identifier of the cart being checked out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "description": "Identifier of the customer checking out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "items": {
+      "description": "The items to reserve",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "quantity": {
+            "type": "integer",
+            "minimum": 1
+          }
+        },
+        "required": ["productId", "quantity"]
+      }
+    }
+  },
+  "required": ["cartId", "items"]
+}
diff --git a/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/index.mdx b/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/index.mdx
new file mode 100644
index 000000000..8f2904c56
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/index.mdx
@@ -0,0 +1,54 @@
+---
+id: checkout-orchestrator
+version: 1.0.0
+name: Checkout Orchestrator
+summary: |
+  Runs the checkout saga. Reserves inventory, authorizes payment and creates the order, coordinating the steps that turn a checked-out cart into a confirmed order.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - ordering-platform
+sends:
+  - id: reserve-inventory
+    version: 1.0.0
+  - id: authorize-payment
+    version: 1.0.0
+  - id: create-order
+    version: 1.0.0
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/checkout-orchestrator'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Checkout Orchestrator** is the brain of the Checkout System. Once the [[service|checkout-api]] hands it a checkout, it runs the checkout saga step by step:
+
+1. **Reserve inventory** — sends [[command|reserve-inventory]] to hold stock for the cart's items.
+2. **Authorize payment** — sends [[command|authorize-payment]] to authorize the order total.
+3. **Create the order** — sends [[command|create-order]] to the [[system|order-management-system]].
+
+If any step fails, the orchestrator compensates the earlier steps (releasing the reservation, voiding the authorization) so the customer is never left in an inconsistent state.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="Reserve inventory, authorize payment, create order" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Inventory | Reserves stock via [[command\|reserve-inventory]]. |
+| Payment | Authorizes the order total via [[command\|authorize-payment]]. |
+| Order creation | Creates the order via [[command\|create-order]] against the [[system\|order-management-system]]. |
+| Compensation | Rolls back earlier steps if a later step fails. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/order-management-system/containers/order-database/index.mdx b/examples/default/domains/Ordering/systems/order-management-system/containers/order-database/index.mdx
new file mode 100644
index 000000000..11dd5802d
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/containers/order-database/index.mdx
@@ -0,0 +1,39 @@
+---
+id: order-database
+name: Order Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for orders and their items.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for orders
+classification: confidential
+retention: 7y
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Order Database** is the authoritative store for orders at Acme Inc. The [[service|order-service]] reads from and writes to it as orders are created, cancelled and completed.
+
+### What does it store?
+
+- **Orders** — one row per order: id, customer, status, total and timestamps.
+- **Order Items** — one row per item in an order: product, quantity and unit price.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Order Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Retention
+
+Orders are financial records and are retained for **7 years** (see frontmatter) to meet accounting and audit requirements.
diff --git a/examples/default/domains/Ordering/systems/order-management-system/containers/order-database/schema.sql b/examples/default/domains/Ordering/systems/order-management-system/containers/order-database/schema.sql
new file mode 100644
index 000000000..554b70834
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/containers/order-database/schema.sql
@@ -0,0 +1,24 @@
+-- Order Database — system of record for orders
+
+CREATE TABLE orders (
+    order_id     UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    cart_id      UUID,
+    customer_id  UUID NOT NULL,
+    status       TEXT NOT NULL DEFAULT 'CREATED'
+                   CHECK (status IN ('CREATED', 'COMPLETED', 'CANCELLED')),
+    total_cents  INTEGER NOT NULL CHECK (total_cents >= 0),
+    currency     CHAR(3) NOT NULL DEFAULT 'USD',
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE order_items (
+    order_id         UUID NOT NULL REFERENCES orders (order_id) ON DELETE CASCADE,
+    product_id       UUID NOT NULL,
+    quantity         INTEGER NOT NULL CHECK (quantity > 0),
+    unit_price_cents INTEGER NOT NULL CHECK (unit_price_cents >= 0),
+    PRIMARY KEY (order_id, product_id)
+);
+
+CREATE INDEX idx_orders_customer ON orders (customer_id);
+CREATE INDEX idx_orders_status   ON orders (status);
diff --git a/examples/default/domains/Ordering/systems/order-management-system/flows/OrderCancellation/index.mdx b/examples/default/domains/Ordering/systems/order-management-system/flows/OrderCancellation/index.mdx
new file mode 100644
index 000000000..b13d842b2
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/flows/OrderCancellation/index.mdx
@@ -0,0 +1,105 @@
+---
+id: order-cancellation
+name: Order Cancellation
+version: 1.0.0
+summary: |
+  How an order is cancelled — whether requested by the customer or triggered by a failure — and the events that tell the rest of the business to unwind it.
+owners:
+  - ordering-platform
+steps:
+  - id: cancellation_trigger
+    title: Cancellation requested
+    actor:
+      name: Shopper or System
+      summary: A customer asks to cancel, or a downstream failure (payment, inventory) forces a cancellation.
+    next_step:
+      id: cancel_order_command
+      label: Cancel order
+
+  - id: cancel_order_command
+    title: Cancel Order
+    message:
+      id: cancel-order
+      version: 1.0.0
+    next_step:
+      id: order_service
+      label: Handle cancellation
+
+  - id: order_service
+    title: Order Service
+    service:
+      id: order-service
+      version: 1.0.0
+    next_steps:
+      - id: eligibility_check
+        label: Check eligibility
+      - id: not_cancellable
+        label: Already completed
+
+  - id: eligibility_check
+    title: Cancellation policy check
+    custom:
+      title: Cancellation policy
+      color: blue
+      icon: ClipboardDocumentCheckIcon
+      type: Policy
+      summary: An order can only be cancelled before it is completed. Completed orders must go through returns instead.
+      properties:
+        rule: 'status must be CREATED'
+    next_step:
+      id: order_database
+      label: Mark cancelled
+
+  - id: order_database
+    title: Order Database
+    container:
+      id: order-database
+    next_step:
+      id: order_cancelled
+      label: Persist + publish
+
+  - id: order_cancelled
+    title: Order Cancelled
+    message:
+      id: order-cancelled
+      version: 1.0.0
+    next_step:
+      id: downstream_unwind
+      label: Unwind downstream
+
+  - id: downstream_unwind
+    title: Downstream unwind
+    custom:
+      title: Release and refund
+      color: orange
+      icon: ArrowUturnLeftIcon
+      type: Compensation
+      summary: Consumers of OrderCancelled release reserved inventory, void or refund the payment, and stop fulfilment.
+      properties:
+        consumers: 'inventory, payment, fulfilment'
+
+  - id: not_cancellable
+    title: Cannot cancel
+    custom:
+      title: Cannot cancel
+      color: red
+      icon: ExclamationTriangleIcon
+      type: Exception
+      summary: The order has already been completed and cannot be cancelled. The customer is directed to the returns process.
+      properties:
+        next_action: 'start a return'
+---
+
+## Overview
+
+**Order Cancellation** documents how the [[system|order-management-system]] cancels an order. Cancellation can be requested by a shopper or forced by a downstream failure during checkout. Only orders that have not yet completed can be cancelled.
+
+<NodeGraph />
+
+## How it works
+
+1. A [[command|cancel-order]] command reaches the [[service|order-service]].
+2. The service checks the cancellation policy — only `CREATED` orders are cancellable.
+3. If eligible, the order is marked cancelled in the [[container|order-database]] and [[event|order-cancelled]] is published.
+4. Downstream consumers react to [[event|order-cancelled]] to release inventory, refund payment and stop fulfilment.
+5. If the order is already completed, cancellation is rejected and the customer is sent to the returns process.
diff --git a/examples/default/domains/Ordering/systems/order-management-system/index.mdx b/examples/default/domains/Ordering/systems/order-management-system/index.mdx
new file mode 100644
index 000000000..58fda2096
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/index.mdx
@@ -0,0 +1,53 @@
+---
+id: order-management-system
+name: Order Management System
+version: 1.0.0
+summary: |
+  Internal system that is the source of truth for orders. It creates orders, tracks their lifecycle, and publishes events as orders are created, completed and cancelled.
+owners:
+  - ordering-platform
+services:
+  - id: order-service
+containers:
+  - id: order-database
+flows:
+  - id: order-cancellation
+    version: 1.0.0
+relationships:
+  - id: checkout-system
+    label: receives orders from
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Order Management System** owns the order at Acme Inc. It accepts the [[command|create-order]] command from the [[system|checkout-system]], persists orders in the [[container|order-database]], and serves order lookups via [[query|get-order]]. As an order moves through its lifecycle it publishes [[event|order-created]], [[event|order-completed]] and [[event|order-cancelled]] events for the rest of the business to react to.
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|order-service]] | Service | Creates, cancels and serves orders, and publishes order lifecycle events. |
+| [[container\|order-database]] | Data store | PostgreSQL system of record for orders and their items. |
+
+## Messages this system publishes
+
+- [[event\|order-created]] — a new order has been created.
+- [[event\|order-completed]] — an order has been fulfilled and completed.
+- [[event\|order-cancelled]] — an order has been cancelled.
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/asyncapi.yml b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/asyncapi.yml
new file mode 100644
index 000000000..ff77c2538
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/asyncapi.yml
@@ -0,0 +1,233 @@
+asyncapi: 3.0.0
+
+info:
+  title: Order Service
+  version: 1.0.0
+  description: |
+    The event-driven interface of the Order Service — the system of record for orders.
+
+    The service consumes commands to create and cancel orders, and publishes events as
+    orders move through their lifecycle (created, completed, cancelled). Query access
+    (`GetOrder`) is served over the REST API and is not part of this AsyncAPI document.
+  contact:
+    name: Ordering Platform
+    email: ordering-platform@acme.test
+
+defaultContentType: application/json
+
+servers:
+  production:
+    host: broker.acme.test:9092
+    protocol: kafka
+    description: Production Kafka cluster.
+
+channels:
+  orderCommands:
+    address: ordering.commands
+    title: Order commands
+    description: Commands the Order Service consumes to create and cancel orders.
+    messages:
+      CreateOrder:
+        $ref: '#/components/messages/CreateOrder'
+      CancelOrder:
+        $ref: '#/components/messages/CancelOrder'
+
+  orderEvents:
+    address: ordering.orders
+    title: Order lifecycle events
+    description: Events the Order Service publishes as orders move through their lifecycle.
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+      OrderCompleted:
+        $ref: '#/components/messages/OrderCompleted'
+      OrderCancelled:
+        $ref: '#/components/messages/OrderCancelled'
+
+operations:
+  receiveCreateOrder:
+    action: receive
+    title: Create Order
+    summary: Create a new order from a checked-out cart.
+    channel:
+      $ref: '#/channels/orderCommands'
+    messages:
+      - $ref: '#/channels/orderCommands/messages/CreateOrder'
+
+  receiveCancelOrder:
+    action: receive
+    title: Cancel Order
+    summary: Cancel an existing order.
+    channel:
+      $ref: '#/channels/orderCommands'
+    messages:
+      - $ref: '#/channels/orderCommands/messages/CancelOrder'
+
+  publishOrderCreated:
+    action: send
+    title: Order Created
+    summary: Published when a new order has been created.
+    channel:
+      $ref: '#/channels/orderEvents'
+    messages:
+      - $ref: '#/channels/orderEvents/messages/OrderCreated'
+
+  publishOrderCompleted:
+    action: send
+    title: Order Completed
+    summary: Published when an order has been fulfilled and completed.
+    channel:
+      $ref: '#/channels/orderEvents'
+    messages:
+      - $ref: '#/channels/orderEvents/messages/OrderCompleted'
+
+  publishOrderCancelled:
+    action: send
+    title: Order Cancelled
+    summary: Published when an order has been cancelled.
+    channel:
+      $ref: '#/channels/orderEvents'
+    messages:
+      - $ref: '#/channels/orderEvents/messages/OrderCancelled'
+
+components:
+  messages:
+    CreateOrder:
+      name: CreateOrder
+      title: Create Order
+      summary: Command to create a new order from a checked-out cart.
+      payload:
+        $ref: '#/components/schemas/CreateOrder'
+    CancelOrder:
+      name: CancelOrder
+      title: Cancel Order
+      summary: Command to cancel an existing order.
+      payload:
+        $ref: '#/components/schemas/CancelOrder'
+    OrderCreated:
+      name: OrderCreated
+      title: Order Created
+      summary: Published when a new order has been created.
+      payload:
+        $ref: '#/components/schemas/OrderCreated'
+    OrderCompleted:
+      name: OrderCompleted
+      title: Order Completed
+      summary: Published when an order has been fulfilled and completed.
+      payload:
+        $ref: '#/components/schemas/OrderCompleted'
+    OrderCancelled:
+      name: OrderCancelled
+      title: Order Cancelled
+      summary: Published when an order has been cancelled.
+      payload:
+        $ref: '#/components/schemas/OrderCancelled'
+
+  schemas:
+    OrderItem:
+      type: object
+      required: [productId, quantity, unitPrice]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        quantity:
+          type: integer
+          minimum: 1
+        unitPrice:
+          type: integer
+          description: Price per unit in minor units (e.g. cents).
+
+    CancellationReason:
+      type: string
+      enum: [CUSTOMER_REQUESTED, PAYMENT_FAILED, OUT_OF_STOCK, FRAUD]
+
+    CreateOrder:
+      type: object
+      description: Command to create a new order from a checked-out cart.
+      required: [cartId, customerId, items, total, currency]
+      properties:
+        cartId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/OrderItem'
+        total:
+          type: integer
+          minimum: 0
+          description: Order total in minor units (e.g. cents).
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        paymentAuthorizationId:
+          type: string
+          description: Identifier of the payment authorization for this order.
+
+    CancelOrder:
+      type: object
+      description: Command to cancel an existing order.
+      required: [orderId, reason]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        reason:
+          $ref: '#/components/schemas/CancellationReason'
+
+    OrderCreated:
+      type: object
+      description: Published when a new order has been created.
+      required: [orderId, customerId, total, currency, createdAt]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        total:
+          type: integer
+          description: Order total in minor units (e.g. cents).
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        createdAt:
+          type: string
+          format: date-time
+
+    OrderCompleted:
+      type: object
+      description: Published when an order has been fulfilled and completed.
+      required: [orderId, customerId, completedAt]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        completedAt:
+          type: string
+          format: date-time
+
+    OrderCancelled:
+      type: object
+      description: Published when an order has been cancelled.
+      required: [orderId, reason, cancelledAt]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        reason:
+          $ref: '#/components/schemas/CancellationReason'
+        cancelledAt:
+          type: string
+          format: date-time
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/index.mdx b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/index.mdx
new file mode 100644
index 000000000..3d109146a
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/index.mdx
@@ -0,0 +1,32 @@
+---
+id: cancel-order
+name: Cancel Order
+version: 1.0.0
+summary: |
+  Command to cancel an existing order.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /orders/{orderId}/cancel
+  statusCodes: ['200', '404', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CancelOrder` is handled by the [[service|order-service]]. It cancels an order that has not yet been completed — releasing any reservations and voiding the payment authorization where needed. On success the Order Service publishes an [[event|order-cancelled]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/schema.json b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/schema.json
new file mode 100644
index 000000000..a67eede17
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/schema.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CancelOrder",
+  "description": "Command to cancel an existing order",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "description": "Identifier of the order to cancel",
+      "type": "string",
+      "format": "uuid"
+    },
+    "reason": {
+      "description": "Why the order is being cancelled",
+      "type": "string",
+      "enum": ["CUSTOMER_REQUESTED", "PAYMENT_FAILED", "OUT_OF_STOCK", "FRAUD"]
+    }
+  },
+  "required": ["orderId", "reason"]
+}
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/index.mdx b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/index.mdx
new file mode 100644
index 000000000..86eaff6b9
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/index.mdx
@@ -0,0 +1,32 @@
+---
+id: create-order
+name: Create Order
+version: 1.0.0
+summary: |
+  Command to create a new order from a checked-out cart.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /orders
+  statusCodes: ['201', '400', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CreateOrder` is sent by the [[service|checkout-orchestrator]] and handled by the [[service|order-service]]. It is the final step of the checkout saga — once inventory is reserved and payment is authorized, this command creates the order. On success the Order Service publishes an [[event|order-created]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/schema.json b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/schema.json
new file mode 100644
index 000000000..796d29dc7
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/schema.json
@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CreateOrder",
+  "description": "Command to create a new order from a checked-out cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Identifier of the cart this order was created from",
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "description": "Identifier of the customer placing the order",
+      "type": "string",
+      "format": "uuid"
+    },
+    "items": {
+      "description": "The items in the order",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "quantity": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "unitPrice": {
+            "type": "integer",
+            "description": "Price per unit in minor units (e.g. cents)"
+          }
+        },
+        "required": ["productId", "quantity", "unitPrice"]
+      }
+    },
+    "total": {
+      "description": "Order total in minor units (e.g. cents)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "currency": {
+      "description": "ISO 4217 currency code",
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "paymentAuthorizationId": {
+      "description": "Identifier of the payment authorization for this order",
+      "type": "string"
+    }
+  },
+  "required": ["cartId", "customerId", "items", "total", "currency"]
+}
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/index.mdx b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/index.mdx
new file mode 100644
index 000000000..6a5c9fb4e
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/index.mdx
@@ -0,0 +1,29 @@
+---
+id: order-cancelled
+name: Order Cancelled
+version: 1.0.0
+summary: |
+  Published when an order has been cancelled.
+owners:
+  - ordering-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderCancelled` is published by the [[service|order-service]] when an order is cancelled — whether at the customer's request or because a downstream step (payment, inventory) failed. Downstream systems consume it to release inventory, refund or void payment, and stop fulfilment.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/schema.json b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/schema.json
new file mode 100644
index 000000000..d01f5531a
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/schema.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderCancelled",
+  "description": "Published when an order has been cancelled",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "reason": {
+      "type": "string",
+      "enum": ["CUSTOMER_REQUESTED", "PAYMENT_FAILED", "OUT_OF_STOCK", "FRAUD"]
+    },
+    "cancelledAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": ["orderId", "reason", "cancelledAt"]
+}
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/index.mdx b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/index.mdx
new file mode 100644
index 000000000..e78b1611e
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/index.mdx
@@ -0,0 +1,29 @@
+---
+id: order-completed
+name: Order Completed
+version: 1.0.0
+summary: |
+  Published when an order has been fulfilled and completed.
+owners:
+  - ordering-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderCompleted` is published by the [[service|order-service]] when an order has been fully fulfilled. It marks the end of the happy path for an order. Downstream systems consume it to close out fulfilment, capture payment, and update reporting.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/schema.json b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/schema.json
new file mode 100644
index 000000000..9fc2b0049
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/schema.json
@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderCompleted",
+  "description": "Published when an order has been fulfilled and completed",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "completedAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": ["orderId", "customerId", "completedAt"]
+}
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/index.mdx b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/index.mdx
new file mode 100644
index 000000000..b87b1e969
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: order-created
+name: Order Created
+version: 1.0.0
+summary: |
+  Published when a new order has been created.
+owners:
+  - ordering-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderCreated` is published by the [[service|order-service]] when a new order is created from a checked-out cart. Downstream systems consume this event to begin fulfilment, send confirmation to the customer, and update reporting.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/schema.json b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/schema.json
new file mode 100644
index 000000000..8d4cf1f43
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/schema.json
@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderCreated",
+  "description": "Published when a new order has been created",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "total": {
+      "type": "integer",
+      "description": "Order total in minor units (e.g. cents)"
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["created"],
+      "description": "Initial lifecycle status for the order"
+    },
+    "items": {
+      "type": "array",
+      "description": "Line items captured at order creation time",
+      "items": {
+        "type": "object",
+        "properties": {
+          "sku": {
+            "type": "string"
+          },
+          "quantity": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "unitPrice": {
+            "type": "integer",
+            "description": "Unit price in minor units (e.g. cents)"
+          }
+        },
+        "required": ["sku", "quantity", "unitPrice"]
+      }
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": ["orderId", "customerId", "total", "currency", "status", "items", "createdAt"]
+}
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/versioned/0.3.0/index.mdx b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/versioned/0.3.0/index.mdx
new file mode 100644
index 000000000..ecd02be6f
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/versioned/0.3.0/index.mdx
@@ -0,0 +1,25 @@
+---
+id: order-created
+name: Order Created
+version: 0.3.0
+summary: |
+  Published when a new order has been created. This early contract only included identifiers and the creation timestamp.
+owners:
+  - ordering-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderCreated` version `0.3.0` was the first stable order creation event contract used by downstream fulfilment consumers.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/versioned/0.3.0/schema.json b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/versioned/0.3.0/schema.json
new file mode 100644
index 000000000..c3aa1344f
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/versioned/0.3.0/schema.json
@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderCreated",
+  "description": "Published when a new order has been created",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": ["orderId", "customerId", "createdAt"]
+}
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/versioned/0.6.0/index.mdx b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/versioned/0.6.0/index.mdx
new file mode 100644
index 000000000..ce5332e0b
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/versioned/0.6.0/index.mdx
@@ -0,0 +1,25 @@
+---
+id: order-created
+name: Order Created
+version: 0.6.0
+summary: |
+  Published when a new order has been created. This version added the order total and currency for payment reconciliation.
+owners:
+  - ordering-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderCreated` version `0.6.0` added monetary fields so consumers could reconcile order totals without calling the Order API.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/versioned/0.6.0/schema.json b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/versioned/0.6.0/schema.json
new file mode 100644
index 000000000..44c4686ca
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/versioned/0.6.0/schema.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderCreated",
+  "description": "Published when a new order has been created",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "total": {
+      "type": "integer",
+      "description": "Order total in minor units (e.g. cents)"
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": ["orderId", "customerId", "total", "currency", "createdAt"]
+}
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/index.mdx b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/index.mdx
new file mode 100644
index 000000000..84c0e168f
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/index.mdx
@@ -0,0 +1,64 @@
+---
+id: order-service
+version: 1.0.0
+name: Order Service
+summary: |
+  The system of record for orders. Creates and cancels orders, serves order lookups, and publishes events as orders move through their lifecycle.
+styles:
+  icon: /icons/languages/java.svg
+owners:
+  - ordering-platform
+receives:
+  - id: create-order
+    version: 1.0.0
+  - id: cancel-order
+    version: 1.0.0
+  - id: get-order
+    version: 1.0.0
+sends:
+  - id: order-created
+    version: 1.0.0
+  - id: order-completed
+    version: 1.0.0
+  - id: order-cancelled
+    version: 1.0.0
+writesTo:
+  - id: order-database
+readsFrom:
+  - id: order-database
+repository:
+  language: Java
+  url: 'https://github.com/acme/order-service'
+specifications:
+  - type: asyncapi
+    path: asyncapi.yml
+    name: Order Service AsyncAPI
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Order Service** is the heart of the Order Management System. It receives [[command|create-order]] from the [[system|checkout-system]], persists orders to the [[container|order-database]], and serves order lookups via [[query|get-order]]. It also handles [[command|cancel-order]]. As orders move through their lifecycle it publishes [[event|order-created]], [[event|order-completed]] and [[event|order-cancelled]] events.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="Order lifecycle events" />
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="Order commands and queries" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Order creation | Handles [[command\|create-order]] from the Checkout System and persists the order. |
+| Order cancellation | Handles [[command\|cancel-order]] and compensates downstream where needed. |
+| Order lookups | Serves [[query\|get-order]] from the [[container\|order-database]]. |
+| Event publishing | Emits [[event\|order-created]], [[event\|order-completed]] and [[event\|order-cancelled]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/queries/GetOrder/index.mdx b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/queries/GetOrder/index.mdx
new file mode 100644
index 000000000..7659bac71
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/queries/GetOrder/index.mdx
@@ -0,0 +1,32 @@
+---
+id: get-order
+name: Get Order
+version: 1.0.0
+summary: |
+  Query to fetch a single order by its identifier.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /orders/{orderId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetOrder` is handled by the [[service|order-service]]. It returns the current state of a single order, read directly from the [[container|order-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/queries/GetOrder/schema.json b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/queries/GetOrder/schema.json
new file mode 100644
index 000000000..40582a9be
--- /dev/null
+++ b/examples/default/domains/Ordering/systems/order-management-system/services/OrderService/queries/GetOrder/schema.json
@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetOrder",
+  "description": "Query to fetch a single order by its identifier, and the order returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "Parameters used to look up the order",
+      "type": "object",
+      "properties": {
+        "orderId": {
+          "description": "Unique identifier of the order to fetch",
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "required": ["orderId"]
+    },
+    "response": {
+      "description": "The order returned by the query",
+      "type": "object",
+      "properties": {
+        "orderId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "customerId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["CREATED", "COMPLETED", "CANCELLED"]
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "productId": { "type": "string", "format": "uuid" },
+              "quantity": { "type": "integer", "minimum": 1 },
+              "unitPrice": { "type": "integer" }
+            },
+            "required": ["productId", "quantity", "unitPrice"]
+          }
+        },
+        "total": {
+          "type": "integer",
+          "description": "Order total in minor units (e.g. cents)"
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "required": ["orderId", "customerId", "status", "items", "total", "currency"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/examples/default/domains/Ordering/ubiquitous-language.mdx b/examples/default/domains/Ordering/ubiquitous-language.mdx
new file mode 100644
index 000000000..ee2ace336
--- /dev/null
+++ b/examples/default/domains/Ordering/ubiquitous-language.mdx
@@ -0,0 +1,53 @@
+---
+dictionary:
+  - id: Order
+    name: Order
+    summary: "A confirmed intent to purchase, created from a checked-out cart and owned for its whole lifecycle."
+    description: |
+      The order is the central concept of the Ordering domain. It is owned by the Order Management
+      System, which is the source of truth for orders. An order has:
+
+      - A unique order id and the customer it belongs to
+      - A set of order items (product, quantity and unit price)
+      - A total and currency
+      - A status (CREATED, COMPLETED or CANCELLED)
+
+      An order is immutable in its essentials once created — its lifecycle is expressed through events,
+      not by editing it in place.
+    icon: ClipboardList
+  - id: Checkout
+    name: Checkout
+    summary: "The flow that turns a checked-out cart into a confirmed order."
+    description: |
+      Checkout is owned by the Checkout System. It is the orchestration that runs after the Shopping
+      domain checks out a cart — reserving inventory, authorizing payment and creating the order.
+    icon: CreditCard
+  - id: Saga
+    name: Saga
+    summary: "A multi-step process with compensating actions, used to coordinate checkout across systems."
+    description: |
+      The Checkout Orchestrator runs checkout as a saga: a sequence of steps (reserve inventory,
+      authorize payment, create order) where each step has a compensating action that undoes it if a
+      later step fails. This keeps the customer consistent without distributed transactions.
+    icon: Workflow
+  - id: Reservation
+    name: Reservation
+    summary: "A temporary hold on stock for the items in a cart, taken during checkout."
+    icon: PackageCheck
+  - id: Authorization
+    name: Authorization
+    summary: "A hold placed on a customer's payment method for the order total, captured when the order is created."
+    icon: ShieldCheck
+  - id: Order Item
+    name: Order Item
+    summary: "A single product line within an order: a product, a quantity and the price paid per unit."
+    icon: ListOrdered
+  - id: Order Status
+    name: Order Status
+    summary: "Where an order sits in its life: CREATED, COMPLETED or CANCELLED."
+    description: |
+      - CREATED — the order exists and is being fulfilled.
+      - COMPLETED — the order has been fully fulfilled.
+      - CANCELLED — the order was cancelled before completion.
+    icon: Workflow
+---
diff --git a/examples/default/domains/Payments/entities/fraud-check/index.mdx b/examples/default/domains/Payments/entities/fraud-check/index.mdx
new file mode 100644
index 000000000..f700c2a2f
--- /dev/null
+++ b/examples/default/domains/Payments/entities/fraud-check/index.mdx
@@ -0,0 +1,39 @@
+---
+id: fraud-check
+name: Fraud Check
+version: 1.0.0
+identifier: fraudCheckId
+summary: Fraud screening result associated with a payment attempt.
+owners:
+  - payments-platform
+properties:
+  - name: fraudCheckId
+    type: UUID
+    required: true
+    description: Unique fraud check identifier.
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Payment attempt being screened.
+    references: payment
+    relationType: screens
+    referencesIdentifier: paymentId
+  - name: result
+    type: string
+    required: true
+    description: Screening result.
+    enum:
+      - passed
+      - failed
+      - review
+  - name: checkedAt
+    type: datetime
+    required: true
+    description: Time screening completed.
+---
+
+## Overview
+
+Fraud Check documents the screening outcome from [[system|fraud-detection]] so payment decisions are auditable.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Payments/entities/payment-authorization/index.mdx b/examples/default/domains/Payments/entities/payment-authorization/index.mdx
new file mode 100644
index 000000000..29413fc6d
--- /dev/null
+++ b/examples/default/domains/Payments/entities/payment-authorization/index.mdx
@@ -0,0 +1,35 @@
+---
+id: payment-authorization
+name: Payment Authorization
+version: 1.0.0
+identifier: authorizationId
+summary: Approval from a payment provider to reserve funds for an order.
+owners:
+  - payments-platform
+properties:
+  - name: authorizationId
+    type: UUID
+    required: true
+    description: Unique authorization identifier.
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Payment this authorization belongs to.
+    references: payment
+    relationType: belongsTo
+    referencesIdentifier: paymentId
+  - name: providerReference
+    type: string
+    required: true
+    description: External payment provider reference.
+  - name: authorizedAt
+    type: datetime
+    required: true
+    description: Time authorization was granted.
+---
+
+## Overview
+
+Payment Authorization captures the result of [[command|authorize-payment]] and links Acme payment state to provider state.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Payments/entities/payment/index.mdx b/examples/default/domains/Payments/entities/payment/index.mdx
new file mode 100644
index 000000000..889df22e3
--- /dev/null
+++ b/examples/default/domains/Payments/entities/payment/index.mdx
@@ -0,0 +1,36 @@
+---
+id: payment
+name: Payment
+version: 1.0.0
+identifier: paymentId
+aggregateRoot: true
+summary: Acme's internal record of payment intent and outcome for an order.
+owners:
+  - payments-platform
+properties:
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Unique payment identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order being paid for.
+    references: order
+    relationType: paysFor
+    referencesIdentifier: orderId
+  - name: amount
+    type: decimal
+    required: true
+    description: Amount requested.
+  - name: status
+    type: string
+    required: true
+    description: Payment lifecycle status.
+---
+
+## Overview
+
+Payment is the Payments domain aggregate. It records Acme's view of payment state regardless of external provider retries or webhook order.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Payments/entities/refund/index.mdx b/examples/default/domains/Payments/entities/refund/index.mdx
new file mode 100644
index 000000000..36ff90861
--- /dev/null
+++ b/examples/default/domains/Payments/entities/refund/index.mdx
@@ -0,0 +1,36 @@
+---
+id: refund
+name: Refund
+version: 1.0.0
+identifier: refundId
+aggregateRoot: true
+summary: A request to return money to a customer after payment.
+owners:
+  - payments-platform
+properties:
+  - name: refundId
+    type: UUID
+    required: true
+    description: Unique refund identifier.
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Payment being refunded.
+    references: payment
+    relationType: refunds
+    referencesIdentifier: paymentId
+  - name: amount
+    type: decimal
+    required: true
+    description: Refund amount.
+  - name: status
+    type: string
+    required: true
+    description: Refund lifecycle state.
+---
+
+## Overview
+
+Refund is owned by Payments and records refund requests and provider outcomes such as [[event|refund-processed]].
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Payments/index.mdx b/examples/default/domains/Payments/index.mdx
new file mode 100644
index 000000000..8a2d2d49a
--- /dev/null
+++ b/examples/default/domains/Payments/index.mdx
@@ -0,0 +1,70 @@
+---
+id: payments
+name: Payments
+version: 1.0.0
+summary: |
+  The Payments domain takes payment for orders and processes refunds. It orchestrates authorization and capture through an external payment processor, and screens payments for fraud.
+owners:
+  - payments-platform
+systems:
+  - id: payment-processing-system
+    version: 1.0.0
+  - id: stripe
+    version: 1.0.0
+  - id: fraud-detection
+    version: 1.0.0
+entities:
+  - id: payment
+    version: 1.0.0
+  - id: payment-authorization
+    version: 1.0.0
+  - id: refund
+    version: 1.0.0
+  - id: fraud-check
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Payments** domain is responsible for moving money. It authorizes and captures payment for orders, issues refunds, and screens payments for fraud. It owns one internal system and integrates with two external providers:
+
+<Tiles>
+  <Tile
+    icon="CreditCardIcon"
+    href="/docs/systems/payment-processing-system/1.0.0"
+    title="Payment Processing System"
+    description="Orchestrates authorization, capture and refunds for orders."
+  />
+  <Tile
+    icon="BuildingLibraryIcon"
+    href="/docs/systems/stripe/1.0.0"
+    title="Stripe"
+    description="External payment processor that charges cards and issues refunds."
+  />
+  <Tile
+    icon="ShieldExclamationIcon"
+    href="/docs/systems/fraud-detection/1.0.0"
+    title="Fraud Detection"
+    description="External provider that screens payments for fraud."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Payment Processing System** is the internal orchestrator. When the Ordering domain authorizes a payment, it requests payment via the external **Stripe** system and, in parallel, asks **Fraud Detection** to screen the payment. Stripe reports back whether the payment succeeded or failed, and the Payment Processing System records the outcome.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
diff --git a/examples/default/domains/Payments/systems/fraud-detection/index.mdx b/examples/default/domains/Payments/systems/fraud-detection/index.mdx
new file mode 100644
index 000000000..9980011f3
--- /dev/null
+++ b/examples/default/domains/Payments/systems/fraud-detection/index.mdx
@@ -0,0 +1,49 @@
+---
+id: fraud-detection
+name: Fraud Detection
+version: 1.0.0
+scope: external
+summary: |
+  External provider that screens payments for fraud. It consumes payment requests and returns a pass or fail verdict.
+owners:
+  - payments-platform
+services:
+  - id: fraud-api
+relationships:
+  - id: payment-processing-system
+    label: screens payments for
+badges:
+  - content: External
+    backgroundColor: yellow
+    textColor: yellow
+    icon: GlobeAltIcon
+---
+
+## Overview
+
+**Fraud Detection** is an external provider Acme Inc uses to screen payments for fraud. It is owned and operated by a third party — modelled here as an **external system** so the catalog shows how the [[system|payment-processing-system]] integrates with it.
+
+It consumes [[event|payment-requested]] and returns a verdict via [[event|fraud-check-passed]] or [[event|fraud-check-failed]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|fraud-api]] | Service | Screens a payment for fraud and returns a pass/fail verdict. |
+
+## Messages this system publishes
+
+- [[event\|fraud-check-passed]] — a payment passed fraud screening.
+- [[event\|fraud-check-failed]] — a payment failed fraud screening.
diff --git a/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/index.mdx b/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/index.mdx
new file mode 100644
index 000000000..ec4dcf580
--- /dev/null
+++ b/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/index.mdx
@@ -0,0 +1,29 @@
+---
+id: fraud-check-failed
+name: Fraud Check Failed
+version: 1.0.0
+summary: |
+  Published when a payment fails fraud screening.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`FraudCheckFailed` is published by the [[service|fraud-api]] when a payment is flagged as fraudulent. The [[system|payment-processing-system]] uses it to block the charge and cancel the order.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/schema.json b/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/schema.json
new file mode 100644
index 000000000..8deb7fd1a
--- /dev/null
+++ b/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/schema.json
@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FraudCheckFailed",
+  "description": "Published when a payment fails fraud screening",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraud risk score; higher is riskier"
+    },
+    "reason": {
+      "type": "string",
+      "enum": ["HIGH_RISK_SCORE", "BLOCKLISTED", "VELOCITY", "MISMATCH"]
+    },
+    "checkedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "reason", "checkedAt"]
+}
diff --git a/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/index.mdx b/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/index.mdx
new file mode 100644
index 000000000..551254e24
--- /dev/null
+++ b/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/index.mdx
@@ -0,0 +1,29 @@
+---
+id: fraud-check-passed
+name: Fraud Check Passed
+version: 1.0.0
+summary: |
+  Published when a payment passes fraud screening.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`FraudCheckPassed` is published by the [[service|fraud-api]] when a payment clears fraud screening. The [[system|payment-processing-system]] uses it to allow the charge to proceed.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/schema.json b/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/schema.json
new file mode 100644
index 000000000..979e2cab9
--- /dev/null
+++ b/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/schema.json
@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FraudCheckPassed",
+  "description": "Published when a payment passes fraud screening",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraud risk score; lower is safer"
+    },
+    "checkedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "checkedAt"]
+}
diff --git a/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/index.mdx b/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/index.mdx
new file mode 100644
index 000000000..8999426d2
--- /dev/null
+++ b/examples/default/domains/Payments/systems/fraud-detection/services/FraudAPI/index.mdx
@@ -0,0 +1,41 @@
+---
+id: fraud-api
+version: 1.0.0
+name: Fraud API
+summary: |
+  External fraud screening API. It consumes payment requests and returns a pass or fail verdict for each.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - payments-platform
+receives:
+  - id: payment-requested
+    version: 1.0.0
+sends:
+  - id: fraud-check-passed
+    version: 1.0.0
+  - id: fraud-check-failed
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/acme/fraud-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Fraud API** screens payments for fraud. It consumes [[event|payment-requested]] from the [[system|payment-processing-system]] and returns a verdict — [[event|fraud-check-passed]] or [[event|fraud-check-failed]] — which the Payments domain uses to allow or block the charge.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="Fraud verdicts" />
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} message`} description="Payment requests to screen" />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Payments/systems/payment-processing-system/containers/payment-database/index.mdx b/examples/default/domains/Payments/systems/payment-processing-system/containers/payment-database/index.mdx
new file mode 100644
index 000000000..2422aa6b2
--- /dev/null
+++ b/examples/default/domains/Payments/systems/payment-processing-system/containers/payment-database/index.mdx
@@ -0,0 +1,39 @@
+---
+id: payment-database
+name: Payment Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for payments and refunds.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for payments and refunds
+classification: confidential
+retention: 7y
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Payment Database** is the authoritative store for payments and refunds at Acme Inc. The [[service|payment-api]] and [[service|payment-worker]] read from and write to it as payments are authorized, charged and refunded.
+
+### What does it store?
+
+- **Payments** — one row per payment: id, order, amount, status and timestamps.
+- **Refunds** — one row per refund: id, payment, amount, status and timestamps.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Payment Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Retention
+
+Payments and refunds are financial records and are retained for **7 years** (see frontmatter) to meet accounting and audit requirements.
diff --git a/examples/default/domains/Payments/systems/payment-processing-system/containers/payment-database/schema.sql b/examples/default/domains/Payments/systems/payment-processing-system/containers/payment-database/schema.sql
new file mode 100644
index 000000000..a53415c14
--- /dev/null
+++ b/examples/default/domains/Payments/systems/payment-processing-system/containers/payment-database/schema.sql
@@ -0,0 +1,25 @@
+-- Payment Database — system of record for payments and refunds
+
+CREATE TABLE payments (
+    payment_id   UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    order_id     UUID NOT NULL,
+    customer_id  UUID,
+    amount_cents INTEGER NOT NULL CHECK (amount_cents >= 0),
+    currency     CHAR(3) NOT NULL DEFAULT 'USD',
+    status       TEXT NOT NULL DEFAULT 'REQUESTED'
+                   CHECK (status IN ('REQUESTED', 'SUCCEEDED', 'FAILED')),
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE refunds (
+    refund_id    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    payment_id   UUID NOT NULL REFERENCES payments (payment_id),
+    amount_cents INTEGER NOT NULL CHECK (amount_cents >= 0),
+    status       TEXT NOT NULL DEFAULT 'REQUESTED'
+                   CHECK (status IN ('REQUESTED', 'PROCESSED', 'FAILED')),
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_payments_order  ON payments (order_id);
+CREATE INDEX idx_payments_status ON payments (status);
diff --git a/examples/default/domains/Payments/systems/payment-processing-system/index.mdx b/examples/default/domains/Payments/systems/payment-processing-system/index.mdx
new file mode 100644
index 000000000..60dde9539
--- /dev/null
+++ b/examples/default/domains/Payments/systems/payment-processing-system/index.mdx
@@ -0,0 +1,53 @@
+---
+id: payment-processing-system
+name: Payment Processing System
+version: 1.0.0
+summary: |
+  Internal system that orchestrates payment for orders. It authorizes payments, requests charges from the external payment processor, handles the outcome, and issues refunds.
+owners:
+  - payments-platform
+services:
+  - id: payment-api
+  - id: payment-worker
+containers:
+  - id: payment-database
+relationships:
+  - id: stripe
+    label: requests charges from
+  - id: fraud-detection
+    label: screens payments with
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Payment Processing System** is the internal heart of the Payments domain. When the Ordering domain sends [[command|authorize-payment]], the [[service|payment-api]] records the intent in the [[container|payment-database]] and the [[service|payment-worker]] requests a charge from the external [[system|stripe]] via [[event|payment-requested]]. Stripe reports the outcome back as [[event|payment-succeeded]] or [[event|payment-failed]], which the worker records. The system also issues refunds via [[event|refund-requested]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|payment-api]] | Service | Receives authorization requests and records payment intent. |
+| [[service\|payment-worker]] | Service | Drives charges and refunds against Stripe and records outcomes. |
+| [[container\|payment-database]] | Data store | PostgreSQL system of record for payments and refunds. |
+
+## Messages this system publishes
+
+- [[event\|payment-requested]] — a charge has been requested from the payment processor.
+- [[event\|refund-requested]] — a refund has been requested from the payment processor.
diff --git a/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentAPI/index.mdx b/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentAPI/index.mdx
new file mode 100644
index 000000000..e958eb81b
--- /dev/null
+++ b/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentAPI/index.mdx
@@ -0,0 +1,46 @@
+---
+id: payment-api
+version: 1.0.0
+name: Payment API
+summary: |
+  Receives payment authorization requests from the Ordering domain and records the payment intent, kicking off the charge against the payment processor.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - payments-platform
+receives:
+  - id: authorize-payment
+    version: 1.0.0
+writesTo:
+  - id: payment-database
+readsFrom:
+  - id: payment-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/payment-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Payment API** is the entry point to the Payment Processing System. It receives [[command|authorize-payment]] from the Ordering domain, records the payment intent in the [[container|payment-database]], and leaves the [[service|payment-worker]] to drive the charge against [[system|stripe]].
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} message`} description="The authorize-payment command from Ordering" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Authorization | Receives and validates [[command\|authorize-payment]]. |
+| Persistence | Records payment intent in the [[container\|payment-database]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/index.mdx b/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/index.mdx
new file mode 100644
index 000000000..425194162
--- /dev/null
+++ b/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/index.mdx
@@ -0,0 +1,29 @@
+---
+id: payment-requested
+name: Payment Requested
+version: 1.0.0
+summary: |
+  Published when the Payment Processing System requests a charge from the payment processor.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`PaymentRequested` is published by the [[service|payment-worker]] to ask the external [[system|stripe]] to charge a customer for an order. Stripe responds with [[event|payment-succeeded]] or [[event|payment-failed]]. The [[system|fraud-detection]] system also consumes this event to screen the payment.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/schema.json b/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/schema.json
new file mode 100644
index 000000000..b25ed842b
--- /dev/null
+++ b/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/schema.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PaymentRequested",
+  "description": "Published when a charge is requested from the payment processor",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "customerId": { "type": "string", "format": "uuid" },
+    "amount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Amount to charge, in minor units (e.g. cents)"
+    },
+    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+    "requestedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "amount", "currency", "requestedAt"]
+}
diff --git a/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/index.mdx b/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/index.mdx
new file mode 100644
index 000000000..ffedefba9
--- /dev/null
+++ b/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/index.mdx
@@ -0,0 +1,29 @@
+---
+id: refund-requested
+name: Refund Requested
+version: 1.0.0
+summary: |
+  Published when the Payment Processing System requests a refund from the payment processor.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RefundRequested` is published by the [[service|payment-worker]] to ask the external [[system|stripe]] to refund a previous charge — for example when an order is cancelled after payment. Stripe responds with [[event|refund-processed]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/schema.json b/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/schema.json
new file mode 100644
index 000000000..db69eb603
--- /dev/null
+++ b/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/schema.json
@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RefundRequested",
+  "description": "Published when a refund is requested from the payment processor",
+  "type": "object",
+  "properties": {
+    "refundId": { "type": "string", "format": "uuid" },
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "amount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Amount to refund, in minor units (e.g. cents)"
+    },
+    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+    "reason": { "type": "string" },
+    "requestedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["refundId", "paymentId", "amount", "currency", "requestedAt"]
+}
diff --git a/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/index.mdx b/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/index.mdx
new file mode 100644
index 000000000..a303776d2
--- /dev/null
+++ b/examples/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/index.mdx
@@ -0,0 +1,56 @@
+---
+id: payment-worker
+version: 1.0.0
+name: Payment Worker
+summary: |
+  Drives charges and refunds against the external payment processor and records the outcomes. It requests payments and refunds, and consumes the success/failure events Stripe returns.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - payments-platform
+receives:
+  - id: payment-succeeded
+    version: 1.0.0
+  - id: payment-failed
+    version: 1.0.0
+sends:
+  - id: payment-requested
+    version: 1.0.0
+  - id: refund-requested
+    version: 1.0.0
+writesTo:
+  - id: payment-database
+readsFrom:
+  - id: payment-database
+repository:
+  language: Go
+  url: 'https://github.com/acme/payment-worker'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Payment Worker** drives money movement. It requests charges from the external [[system|stripe]] via [[event|payment-requested]] and refunds via [[event|refund-requested]], then consumes the [[event|payment-succeeded]] and [[event|payment-failed]] events Stripe returns and records the outcome in the [[container|payment-database]].
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="Payment and refund requests" />
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="Payment outcomes from Stripe" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Charging | Requests charges via [[event\|payment-requested]]. |
+| Refunds | Requests refunds via [[event\|refund-requested]]. |
+| Outcomes | Consumes [[event\|payment-succeeded]] / [[event\|payment-failed]] and records them. |
+| Persistence | Reads from and writes to the [[container\|payment-database]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Payments/systems/stripe/index.mdx b/examples/default/domains/Payments/systems/stripe/index.mdx
new file mode 100644
index 000000000..a97cbffb6
--- /dev/null
+++ b/examples/default/domains/Payments/systems/stripe/index.mdx
@@ -0,0 +1,52 @@
+---
+id: stripe
+name: Stripe
+version: 1.0.0
+scope: external
+summary: |
+  External payment processor used by Acme Inc to charge cards and issue refunds. It receives payment and refund requests and reports outcomes back via webhook events.
+owners:
+  - payments-platform
+services:
+  - id: stripe-payments-api
+  - id: stripe-webhook-endpoint
+relationships:
+  - id: payment-processing-system
+    label: processes payments for
+badges:
+  - content: External
+    backgroundColor: yellow
+    textColor: yellow
+    icon: GlobeAltIcon
+---
+
+## Overview
+
+[Stripe](https://stripe.com) is the external payment processor Acme Inc uses to charge customer cards and issue refunds. It is owned and operated by Stripe — modelled here as an **external system** so the catalog shows how the [[system|payment-processing-system]] integrates with it.
+
+Stripe receives [[event|payment-requested]] and [[event|refund-requested]], and reports outcomes back via [[event|payment-succeeded]], [[event|payment-failed]] and [[event|refund-processed]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|stripe-payments-api]] | Service | Accepts charge and refund requests and processes them. |
+| [[service\|stripe-webhook-endpoint]] | Service | Delivers payment and refund outcomes back to Acme Inc as webhook events. |
+
+## Messages this system publishes
+
+- [[event\|payment-succeeded]] — a charge succeeded.
+- [[event\|payment-failed]] — a charge failed.
+- [[event\|refund-processed]] — a refund was processed.
diff --git a/examples/default/domains/Payments/systems/stripe/services/StripePaymentsAPI/index.mdx b/examples/default/domains/Payments/systems/stripe/services/StripePaymentsAPI/index.mdx
new file mode 100644
index 000000000..b821545b8
--- /dev/null
+++ b/examples/default/domains/Payments/systems/stripe/services/StripePaymentsAPI/index.mdx
@@ -0,0 +1,37 @@
+---
+id: stripe-payments-api
+version: 1.0.0
+name: Payments API
+summary: |
+  Stripe's API for charging cards and issuing refunds. Acme Inc's Payment Processing System calls it to request payments and refunds.
+styles:
+  icon: /icons/payments/stripe.svg
+owners:
+  - payments-platform
+receives:
+  - id: payment-requested
+    version: 1.0.0
+  - id: refund-requested
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/stripe/stripe-node'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Payments API** is Stripe's external interface for charging cards and issuing refunds. The [[system|payment-processing-system]] sends [[event|payment-requested]] and [[event|refund-requested]], and Stripe processes them and reports the outcome back through its [[service|stripe-webhook-endpoint]].
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="Payment and refund requests" />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/index.mdx b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/index.mdx
new file mode 100644
index 000000000..5dfbcb287
--- /dev/null
+++ b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/index.mdx
@@ -0,0 +1,29 @@
+---
+id: payment-failed
+name: Payment Failed
+version: 1.0.0
+summary: |
+  Published by Stripe when a charge fails.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`PaymentFailed` is delivered by Stripe's [[service|stripe-webhook-endpoint]] when a requested charge fails — for example a declined card. The [[service|payment-worker]] consumes it and records the payment as failed, which ultimately leads the order to be cancelled.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/schema.json b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/schema.json
new file mode 100644
index 000000000..fd0e83885
--- /dev/null
+++ b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/schema.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PaymentFailed",
+  "description": "Published when a charge fails",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "reason": {
+      "type": "string",
+      "enum": ["CARD_DECLINED", "INSUFFICIENT_FUNDS", "EXPIRED_CARD", "PROCESSING_ERROR"]
+    },
+    "failedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "reason", "failedAt"]
+}
diff --git a/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/index.mdx b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/index.mdx
new file mode 100644
index 000000000..ed59c5311
--- /dev/null
+++ b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/index.mdx
@@ -0,0 +1,29 @@
+---
+id: payment-succeeded
+name: Payment Succeeded
+version: 1.0.0
+summary: |
+  Published by Stripe when a charge succeeds.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`PaymentSucceeded` is delivered by Stripe's [[service|stripe-webhook-endpoint]] when a requested charge succeeds. The [[service|payment-worker]] consumes it and records the payment as succeeded.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/schema.json b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/schema.json
new file mode 100644
index 000000000..91755e4b3
--- /dev/null
+++ b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/schema.json
@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PaymentSucceeded",
+  "description": "Published when a charge succeeds",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "amount": { "type": "integer", "description": "Amount charged, in minor units (e.g. cents)" },
+    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+    "processorReference": { "type": "string", "description": "Stripe's charge identifier" },
+    "succeededAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "amount", "currency", "succeededAt"]
+}
diff --git a/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/index.mdx b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/index.mdx
new file mode 100644
index 000000000..3c9fa3a24
--- /dev/null
+++ b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/index.mdx
@@ -0,0 +1,29 @@
+---
+id: refund-processed
+name: Refund Processed
+version: 1.0.0
+summary: |
+  Published by Stripe when a refund has been processed.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RefundProcessed` is delivered by Stripe's [[service|stripe-webhook-endpoint]] when a requested refund has been processed. The [[service|payment-worker]] consumes it and records the refund as complete.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/schema.json b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/schema.json
new file mode 100644
index 000000000..70e376974
--- /dev/null
+++ b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/schema.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RefundProcessed",
+  "description": "Published when a refund has been processed",
+  "type": "object",
+  "properties": {
+    "refundId": { "type": "string", "format": "uuid" },
+    "paymentId": { "type": "string", "format": "uuid" },
+    "amount": { "type": "integer", "description": "Amount refunded, in minor units (e.g. cents)" },
+    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+    "processedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["refundId", "paymentId", "amount", "currency", "processedAt"]
+}
diff --git a/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/index.mdx b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/index.mdx
new file mode 100644
index 000000000..9b53316b8
--- /dev/null
+++ b/examples/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/index.mdx
@@ -0,0 +1,39 @@
+---
+id: stripe-webhook-endpoint
+version: 1.0.0
+name: Webhook Endpoint
+summary: |
+  Stripe's webhook delivery for payment and refund outcomes. It notifies Acme Inc whether a charge succeeded or failed, and when a refund is processed.
+styles:
+  icon: /icons/payments/stripe.svg
+owners:
+  - payments-platform
+sends:
+  - id: payment-succeeded
+    version: 1.0.0
+  - id: payment-failed
+    version: 1.0.0
+  - id: refund-processed
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/stripe/stripe-node'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Webhook Endpoint** is how Stripe reports outcomes back to Acme Inc. After processing a request from the [[service|stripe-payments-api]], it delivers [[event|payment-succeeded]], [[event|payment-failed]] or [[event|refund-processed]] to the [[system|payment-processing-system]].
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="Payment and refund outcomes" />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Payments/ubiquitous-language.mdx b/examples/default/domains/Payments/ubiquitous-language.mdx
new file mode 100644
index 000000000..e043f11da
--- /dev/null
+++ b/examples/default/domains/Payments/ubiquitous-language.mdx
@@ -0,0 +1,41 @@
+---
+dictionary:
+  - id: Payment
+    name: Payment
+    summary: "A charge taken from a customer to pay for an order."
+    description: |
+      A payment is the central concept of the Payments domain. It is owned by the Payment Processing
+      System, which records every payment's status (REQUESTED, SUCCEEDED or FAILED). The actual money
+      movement happens at the external payment processor.
+    icon: CreditCard
+  - id: Authorization
+    name: Authorization
+    summary: "A hold placed on a customer's payment method, confirming funds are available before capture."
+    icon: ShieldCheck
+  - id: Capture
+    name: Capture
+    summary: "Taking the held funds from an authorized payment — turning an authorization into an actual charge."
+    icon: Banknote
+  - id: Refund
+    name: Refund
+    summary: "Returning money to a customer for a previous payment, in full or in part."
+    icon: Undo2
+  - id: Payment Processor
+    name: Payment Processor
+    summary: "The external provider (Stripe) that charges cards and issues refunds on Acme Inc's behalf."
+    description: |
+      The payment processor is a third party. Acme Inc never stores raw card details — it delegates
+      the actual charge and refund to the processor and reacts to the outcomes it reports back.
+    icon: Building2
+  - id: Fraud Screening
+    name: Fraud Screening
+    summary: "Checking a payment for signs of fraud before allowing the charge to proceed."
+    description: |
+      Fraud screening is performed by an external Fraud Detection provider. It returns a verdict —
+      passed or failed — that determines whether a payment is allowed or blocked.
+    icon: ShieldAlert
+  - id: Webhook
+    name: Webhook
+    summary: "A callback the payment processor sends to report the outcome of a charge or refund."
+    icon: Webhook
+---
diff --git a/examples/default/domains/Reviews/asyncapi.yml b/examples/default/domains/Reviews/asyncapi.yml
new file mode 100644
index 000000000..b85d9b379
--- /dev/null
+++ b/examples/default/domains/Reviews/asyncapi.yml
@@ -0,0 +1,181 @@
+asyncapi: 3.0.0
+
+info:
+  title: Review Moderation Worker
+  version: 1.0.0
+  description: |
+    The event-driven interface of the Review Moderation Worker.
+
+    The worker consumes submitted and flagged reviews, screens them for spam, abuse
+    and policy violations, and publishes the outcome (published or rejected).
+  contact:
+    name: Reviews Platform
+    email: reviews-platform@acme.test
+
+defaultContentType: application/json
+
+servers:
+  production:
+    host: broker.acme.test:9092
+    protocol: kafka
+    description: Production Kafka cluster.
+
+channels:
+  reviewIntake:
+    address: reviews.intake
+    title: Reviews to moderate
+    description: Reviews that need screening — newly submitted or flagged for re-moderation.
+    messages:
+      ReviewSubmitted:
+        $ref: '#/components/messages/ReviewSubmitted'
+      ReviewFlagged:
+        $ref: '#/components/messages/ReviewFlagged'
+
+  reviewOutcomes:
+    address: reviews.outcomes
+    title: Moderation outcomes
+    description: The decisions the worker publishes after screening a review.
+    messages:
+      ReviewPublished:
+        $ref: '#/components/messages/ReviewPublished'
+      ReviewRejected:
+        $ref: '#/components/messages/ReviewRejected'
+
+operations:
+  receiveReviewSubmitted:
+    action: receive
+    title: Review Submitted
+    summary: Screen a newly submitted review.
+    channel:
+      $ref: '#/channels/reviewIntake'
+    messages:
+      - $ref: '#/channels/reviewIntake/messages/ReviewSubmitted'
+
+  receiveReviewFlagged:
+    action: receive
+    title: Review Flagged
+    summary: Re-screen a previously published review that has been flagged.
+    channel:
+      $ref: '#/channels/reviewIntake'
+    messages:
+      - $ref: '#/channels/reviewIntake/messages/ReviewFlagged'
+
+  publishReviewPublished:
+    action: send
+    title: Review Published
+    summary: Published when a review passes moderation.
+    channel:
+      $ref: '#/channels/reviewOutcomes'
+    messages:
+      - $ref: '#/channels/reviewOutcomes/messages/ReviewPublished'
+
+  publishReviewRejected:
+    action: send
+    title: Review Rejected
+    summary: Published when a review fails moderation.
+    channel:
+      $ref: '#/channels/reviewOutcomes'
+    messages:
+      - $ref: '#/channels/reviewOutcomes/messages/ReviewRejected'
+
+components:
+  messages:
+    ReviewSubmitted:
+      name: ReviewSubmitted
+      title: Review Submitted
+      summary: A customer submitted a review; it awaits moderation.
+      payload:
+        $ref: '#/components/schemas/ReviewSubmitted'
+    ReviewFlagged:
+      name: ReviewFlagged
+      title: Review Flagged
+      summary: A published review was flagged and needs re-screening.
+      payload:
+        $ref: '#/components/schemas/ReviewFlagged'
+    ReviewPublished:
+      name: ReviewPublished
+      title: Review Published
+      summary: A review passed moderation and is visible on the storefront.
+      payload:
+        $ref: '#/components/schemas/ReviewPublished'
+    ReviewRejected:
+      name: ReviewRejected
+      title: Review Rejected
+      summary: A review failed moderation and will not be shown.
+      payload:
+        $ref: '#/components/schemas/ReviewRejected'
+
+  schemas:
+    ReviewSubmitted:
+      type: object
+      properties:
+        reviewId:
+          type: string
+          format: uuid
+        productId:
+          type: string
+        customerId:
+          type: string
+        rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        title:
+          type: string
+        body:
+          type: string
+        submittedAt:
+          type: string
+          format: date-time
+      required: [reviewId, productId, customerId, rating, submittedAt]
+    ReviewFlagged:
+      type: object
+      properties:
+        reviewId:
+          type: string
+          format: uuid
+        productId:
+          type: string
+        reason:
+          type: string
+          enum: [spam, abuse, off_topic, inappropriate, other]
+        flagCount:
+          type: integer
+          minimum: 1
+        flaggedAt:
+          type: string
+          format: date-time
+      required: [reviewId, productId, reason, flaggedAt]
+    ReviewPublished:
+      type: object
+      properties:
+        reviewId:
+          type: string
+          format: uuid
+        productId:
+          type: string
+        customerId:
+          type: string
+        rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        publishedAt:
+          type: string
+          format: date-time
+      required: [reviewId, productId, rating, publishedAt]
+    ReviewRejected:
+      type: object
+      properties:
+        reviewId:
+          type: string
+          format: uuid
+        productId:
+          type: string
+        reason:
+          type: string
+          enum: [spam, abuse, off_topic, policy_violation]
+        rejectedAt:
+          type: string
+          format: date-time
+      required: [reviewId, productId, reason, rejectedAt]
diff --git a/examples/default/domains/Reviews/containers/rating-cache/index.mdx b/examples/default/domains/Reviews/containers/rating-cache/index.mdx
new file mode 100644
index 000000000..d52dc76ed
--- /dev/null
+++ b/examples/default/domains/Reviews/containers/rating-cache/index.mdx
@@ -0,0 +1,29 @@
+---
+id: rating-cache
+name: Rating Cache
+version: 1.0.0
+summary: Redis cache that serves each product's aggregate star rating with low latency.
+container_type: cache
+technology: redis@7
+authoritative: false
+access_mode: readWrite
+purpose: Fast read store for aggregate product ratings
+classification: internal
+retention: transient
+residency: eu-west-1
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Rating Cache** holds the aggregate rating (average score and review count) for each product. It is a derived read model — never a source of truth — so it can be rebuilt at any time by replaying published reviews.
+
+### What does it store?
+
+- **Aggregate rating** — one entry per product: average rating, review count and last-updated timestamp.
+
+### Access patterns
+
+- The [[service|rating-aggregator]] writes the aggregate rating whenever a review is published.
+- The [[service|review-api]] reads it to serve [[query|get-product-reviews]].
diff --git a/examples/default/domains/Reviews/containers/review-database/index.mdx b/examples/default/domains/Reviews/containers/review-database/index.mdx
new file mode 100644
index 000000000..6b61a44ac
--- /dev/null
+++ b/examples/default/domains/Reviews/containers/review-database/index.mdx
@@ -0,0 +1,33 @@
+---
+id: review-database
+name: Review Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for reviews and their moderation state.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for reviews, ratings and moderation decisions
+classification: internal
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Review Database** is the authoritative store for every review in the Reviews & Ratings domain. The [[service|review-api]] writes new reviews to it, and the [[service|review-moderation-worker]] records each moderation decision against the stored review.
+
+### What does it store?
+
+- **Reviews** — one row per review: product, customer, rating, title, body and lifecycle status (`submitted`, `published`, `rejected`).
+- **Moderation decisions** — the outcome and reason for each moderated review, kept for audit.
+
+### Access patterns
+
+- The [[service|review-api]] writes new reviews and reads published reviews.
+- The [[service|review-moderation-worker]] reads submitted reviews and writes moderation outcomes.
+- The [[service|rating-aggregator]] reads published reviews to recompute aggregates.
diff --git a/examples/default/domains/Reviews/entities/moderation-decision/index.mdx b/examples/default/domains/Reviews/entities/moderation-decision/index.mdx
new file mode 100644
index 000000000..610f9a0f4
--- /dev/null
+++ b/examples/default/domains/Reviews/entities/moderation-decision/index.mdx
@@ -0,0 +1,38 @@
+---
+id: moderation-decision
+name: Moderation Decision
+version: 1.0.0
+identifier: moderationDecisionId
+summary: The outcome of reviewing submitted customer feedback.
+owners:
+  - reviews-platform
+properties:
+  - name: moderationDecisionId
+    type: UUID
+    required: true
+    description: Unique moderation decision identifier.
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Review being moderated.
+    references: review
+    relationType: decides
+    referencesIdentifier: reviewId
+  - name: outcome
+    type: string
+    required: true
+    description: Moderation result.
+    enum:
+      - published
+      - rejected
+  - name: decidedAt
+    type: datetime
+    required: true
+    description: Time the decision was made.
+---
+
+## Overview
+
+Moderation Decision records why a review became published or rejected and supports audit of [[service|review-moderation-worker]] behavior.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Reviews/entities/rating-summary/index.mdx b/examples/default/domains/Reviews/entities/rating-summary/index.mdx
new file mode 100644
index 000000000..40871dcf4
--- /dev/null
+++ b/examples/default/domains/Reviews/entities/rating-summary/index.mdx
@@ -0,0 +1,35 @@
+---
+id: rating-summary
+name: Rating Summary
+version: 1.0.0
+identifier: productId
+summary: Aggregated review statistics for a product.
+owners:
+  - reviews-platform
+properties:
+  - name: productId
+    type: UUID
+    required: true
+    description: Product being summarized.
+    references: product
+    relationType: summarizes
+    referencesIdentifier: productId
+  - name: averageRating
+    type: decimal
+    required: true
+    description: Average published rating.
+  - name: reviewCount
+    type: integer
+    required: true
+    description: Number of published reviews.
+  - name: updatedAt
+    type: datetime
+    required: true
+    description: Time the summary was recalculated.
+---
+
+## Overview
+
+Rating Summary is the read model maintained by [[service|rating-aggregator]] and stored in [[container|rating-cache]].
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Reviews/entities/review-flag/index.mdx b/examples/default/domains/Reviews/entities/review-flag/index.mdx
new file mode 100644
index 000000000..bff385fd4
--- /dev/null
+++ b/examples/default/domains/Reviews/entities/review-flag/index.mdx
@@ -0,0 +1,35 @@
+---
+id: review-flag
+name: Review Flag
+version: 1.0.0
+identifier: flagId
+summary: A customer report that a review may violate policy.
+owners:
+  - reviews-platform
+properties:
+  - name: flagId
+    type: UUID
+    required: true
+    description: Unique review flag identifier.
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Review being reported.
+    references: review
+    relationType: flags
+    referencesIdentifier: reviewId
+  - name: reason
+    type: string
+    required: true
+    description: Reason selected by the customer.
+  - name: flaggedAt
+    type: datetime
+    required: true
+    description: Time the review was flagged.
+---
+
+## Overview
+
+Review Flag captures [[command|flag-review]] interactions and can send a published review back through moderation.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Reviews/entities/review-vote/index.mdx b/examples/default/domains/Reviews/entities/review-vote/index.mdx
new file mode 100644
index 000000000..f9cd217f7
--- /dev/null
+++ b/examples/default/domains/Reviews/entities/review-vote/index.mdx
@@ -0,0 +1,38 @@
+---
+id: review-vote
+name: Review Vote
+version: 1.0.0
+identifier: voteId
+summary: A customer's helpfulness vote on a product review.
+owners:
+  - reviews-platform
+properties:
+  - name: voteId
+    type: UUID
+    required: true
+    description: Unique review vote identifier.
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Review being voted on.
+    references: review
+    relationType: votesOn
+    referencesIdentifier: reviewId
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer who voted.
+    references: customer-profile
+    relationType: submittedBy
+    referencesIdentifier: customerId
+  - name: votedAt
+    type: datetime
+    required: true
+    description: Time the vote was submitted.
+---
+
+## Overview
+
+Review Vote captures [[command|vote-review-helpful]] interactions and contributes to review helpfulness ranking.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Reviews/entities/review/index.mdx b/examples/default/domains/Reviews/entities/review/index.mdx
new file mode 100644
index 000000000..d9872f4fc
--- /dev/null
+++ b/examples/default/domains/Reviews/entities/review/index.mdx
@@ -0,0 +1,63 @@
+---
+id: review
+name: Review
+version: 1.0.0
+identifier: reviewId
+aggregateRoot: true
+summary: A customer's review and rating of a product, including its moderation lifecycle.
+owners:
+  - reviews-platform
+properties:
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Unique identifier for the review.
+  - name: productId
+    type: string
+    required: true
+    description: The product being reviewed.
+    references: product
+    relationType: reviews
+    referencesIdentifier: productId
+  - name: customerId
+    type: string
+    required: true
+    description: The customer who wrote the review.
+    references: customer-profile
+    relationType: writtenBy
+    referencesIdentifier: customerId
+  - name: rating
+    type: integer
+    required: true
+    description: Star rating from 1 to 5.
+  - name: title
+    type: string
+    required: false
+    description: Short headline for the review.
+  - name: body
+    type: string
+    required: true
+    description: The review text.
+  - name: status
+    type: string
+    required: true
+    description: Lifecycle status of the review.
+    enum:
+      - submitted
+      - published
+      - rejected
+  - name: submittedAt
+    type: datetime
+    required: true
+    description: When the review was submitted.
+---
+
+## Overview
+
+The **Review** is the core aggregate of the Reviews & Ratings domain. It captures a customer's rating and written feedback for a product, along with the moderation `status` that controls whether it is visible on the storefront.
+
+A review moves through three states:
+
+1. **submitted** — stored by the [[service|review-api]], awaiting moderation.
+2. **published** — passed moderation and visible (the [[service|rating-aggregator]] folds it into the product's rating).
+3. **rejected** — failed moderation and never shown, but kept for audit.
diff --git a/examples/default/domains/Reviews/flows/review-submission/index.mdx b/examples/default/domains/Reviews/flows/review-submission/index.mdx
new file mode 100644
index 000000000..f6797dd1a
--- /dev/null
+++ b/examples/default/domains/Reviews/flows/review-submission/index.mdx
@@ -0,0 +1,120 @@
+---
+id: review-submission
+name: Review Submission
+version: 1.0.0
+summary: |
+  How a customer's product review travels from submission, through moderation, to being published and folded into the product's aggregate rating.
+owners:
+  - reviews-platform
+steps:
+  - id: customer_submits
+    title: Customer submits a review
+    actor:
+      name: Customer
+      summary: A customer writes a review and rating for a product they purchased.
+    next_step:
+      id: review_api
+      label: Submit review
+
+  - id: review_api
+    title: Review API
+    service:
+      id: review-api
+      version: 1.0.0
+    next_step:
+      id: review_database
+      label: Store review
+
+  - id: review_database
+    title: Review Database
+    container:
+      id: review-database
+    next_step:
+      id: review_submitted
+      label: Review stored
+
+  - id: review_submitted
+    title: Review Submitted
+    message:
+      id: review-submitted
+      version: 1.0.0
+    next_step:
+      id: moderation_worker
+      label: Screen review
+
+  - id: moderation_worker
+    title: Review Moderation Worker
+    service:
+      id: review-moderation-worker
+      version: 1.0.0
+    next_steps:
+      - id: review_published
+        label: Approved
+      - id: review_rejected
+        label: Rejected
+
+  - id: review_published
+    title: Review Published
+    message:
+      id: review-published
+      version: 1.0.0
+    next_step:
+      id: rating_aggregator
+      label: Update rating
+
+  - id: review_rejected
+    title: Review Rejected
+    message:
+      id: review-rejected
+      version: 1.0.0
+    next_step:
+      id: rejected_outcome
+      label: Not shown
+
+  - id: rating_aggregator
+    title: Rating Aggregator
+    service:
+      id: rating-aggregator
+      version: 1.0.0
+    next_step:
+      id: rating_cache
+      label: Write aggregate
+
+  - id: rating_cache
+    title: Rating Cache
+    container:
+      id: rating-cache
+    next_step:
+      id: published_outcome
+      label: Visible on storefront
+
+  - id: published_outcome
+    title: Review is live
+    custom:
+      title: Review is live
+      color: green
+      icon: StarIcon
+      type: Outcome
+      summary: The review is published and the product's aggregate rating is updated and served from the cache.
+
+  - id: rejected_outcome
+    title: Review rejected
+    custom:
+      title: Review rejected
+      color: red
+      icon: NoSymbolIcon
+      type: Outcome
+      summary: The review failed moderation. It is kept for audit but never shown on the storefront.
+---
+
+## Overview
+
+**Review Submission** documents the journey of a customer review from submission through moderation to publication. A review is only ever folded into a product's rating once it has been approved.
+
+<NodeGraph />
+
+## How it works
+
+1. A customer submits a review via the [[service|review-api]], which stores it in the [[container|review-database]] and publishes [[event|review-submitted]].
+2. The [[service|review-moderation-worker]] screens the review and publishes either [[event|review-published]] or [[event|review-rejected]].
+3. On approval, the [[service|rating-aggregator]] updates the product's aggregate rating in the [[container|rating-cache]] and the review goes live.
diff --git a/examples/default/domains/Reviews/index.mdx b/examples/default/domains/Reviews/index.mdx
new file mode 100644
index 000000000..0ab26e2dc
--- /dev/null
+++ b/examples/default/domains/Reviews/index.mdx
@@ -0,0 +1,93 @@
+---
+id: reviews
+name: Reviews & Ratings
+version: 1.0.0
+summary: |
+  The Reviews & Ratings domain owns customer feedback on products — how reviews are submitted, moderated, published and aggregated into the star ratings shown across the storefront.
+owners:
+  - reviews-platform
+services:
+  - id: review-api
+    version: 1.0.0
+  - id: review-moderation-worker
+    version: 1.0.0
+  - id: rating-aggregator
+    version: 1.0.0
+entities:
+  - id: review
+    version: 1.0.0
+  - id: moderation-decision
+    version: 1.0.0
+  - id: rating-summary
+    version: 1.0.0
+  - id: review-vote
+    version: 1.0.0
+  - id: review-flag
+    version: 1.0.0
+flows:
+  - id: review-submission
+    version: 1.0.0
+receives:
+  - id: submit-review
+    version: 1.0.0
+  - id: flag-review
+    version: 1.0.0
+  - id: vote-review-helpful
+    version: 1.0.0
+  - id: get-product-reviews
+    version: 1.0.0
+sends:
+  - id: review-submitted
+    version: 1.0.0
+  - id: review-published
+    version: 1.0.0
+  - id: review-rejected
+    version: 1.0.0
+  - id: review-flagged
+    version: 1.0.0
+  - id: review-helpful-voted
+    version: 1.0.0
+  - id: rating-updated
+    version: 1.0.0
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Review API
+  - type: asyncapi
+    path: asyncapi.yml
+    name: Reviews Eventing
+badges:
+  - content: Supporting domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+---
+
+## Overview
+
+The **Reviews & Ratings** domain is responsible for everything to do with customer feedback on products: accepting reviews, moderating them for quality and abuse, publishing the approved ones, and aggregating them into the star ratings shown across the storefront.
+
+Unlike most other domains in the catalog, Reviews & Ratings is modelled **without systems** — its services, data stores and flows hang directly off the domain.
+
+### What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|review-api]] | Service | Accepts review submissions and serves product reviews. |
+| [[service\|review-moderation-worker]] | Service | Screens submitted reviews and publishes or rejects them. |
+| [[service\|rating-aggregator]] | Service | Keeps each product's aggregate rating in sync as reviews are published. |
+| [[container\|review-database]] | Data Store | System of record for reviews and their moderation state. |
+| [[container\|rating-cache]] | Data Store | Fast read store for aggregate product ratings. |
+| [[entity\|review]] | Entity | The core review aggregate. |
+
+The diagram below shows the services, data stores and messages that make up this domain.
+
+<NodeGraph />
+
+## How it works
+
+1. A customer submits a review via the [[service\|review-api]], which stores it and publishes [[event\|review-submitted]].
+2. The [[service\|review-moderation-worker]] screens the review and publishes either [[event\|review-published]] or [[event\|review-rejected]].
+3. The [[service\|rating-aggregator]] consumes [[event\|review-published]] and updates the product's aggregate rating, publishing [[event\|rating-updated]].
+
+Once a review is live, customers can interact with it: [[command\|vote-review-helpful]] updates its helpful count (publishing [[event\|review-helpful-voted]]), and [[command\|flag-review]] reports it for re-moderation (publishing [[event\|review-flagged]], which the [[service\|review-moderation-worker]] re-screens).
diff --git a/examples/default/domains/Reviews/openapi.yml b/examples/default/domains/Reviews/openapi.yml
new file mode 100644
index 000000000..4f1046a66
--- /dev/null
+++ b/examples/default/domains/Reviews/openapi.yml
@@ -0,0 +1,209 @@
+openapi: 3.0.3
+info:
+  title: Review API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Reviews & Ratings domain. It is the entry point for
+    submitting reviews, flagging reviews, voting reviews helpful, and reading the
+    published reviews and aggregate rating for a product.
+  contact:
+    name: Reviews Platform
+    email: reviews-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+tags:
+  - name: Reviews
+    description: Submit, read and interact with product reviews.
+paths:
+  /products/{productId}/reviews:
+    get:
+      operationId: getProductReviews
+      summary: Get product reviews
+      description: Returns the published reviews and aggregate rating for a product.
+      tags:
+        - Reviews
+      parameters:
+        - name: productId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: page
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - name: pageSize
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+        - name: sort
+          in: query
+          schema:
+            type: string
+            enum: [newest, highest, lowest, most_helpful]
+            default: newest
+      responses:
+        '200':
+          description: The published reviews and aggregate rating for the product.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProductReviews'
+    post:
+      operationId: submitReview
+      summary: Submit a review
+      description: Submits a review for a product. On success a `ReviewSubmitted` event is published and the review awaits moderation.
+      tags:
+        - Reviews
+      parameters:
+        - name: productId
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SubmitReviewRequest'
+      responses:
+        '202':
+          description: The review was accepted and is awaiting moderation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Review'
+        '400':
+          description: The request was invalid.
+  /reviews/{reviewId}/flags:
+    post:
+      operationId: flagReview
+      summary: Flag a review
+      description: Flags a published review for re-moderation. On success a `ReviewFlagged` event is published.
+      tags:
+        - Reviews
+      parameters:
+        - name: reviewId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FlagReviewRequest'
+      responses:
+        '202':
+          description: The flag was recorded.
+  /reviews/{reviewId}/helpful:
+    post:
+      operationId: voteReviewHelpful
+      summary: Vote a review helpful
+      description: Marks a review as helpful (or removes the vote). On success a `ReviewHelpfulVoted` event is published.
+      tags:
+        - Reviews
+      parameters:
+        - name: reviewId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VoteReviewHelpfulRequest'
+      responses:
+        '200':
+          description: The helpful count was updated.
+components:
+  schemas:
+    Review:
+      type: object
+      properties:
+        reviewId:
+          type: string
+          format: uuid
+        productId:
+          type: string
+        customerId:
+          type: string
+        rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        title:
+          type: string
+        body:
+          type: string
+        status:
+          type: string
+          enum: [submitted, published, rejected]
+        helpfulCount:
+          type: integer
+          minimum: 0
+        submittedAt:
+          type: string
+          format: date-time
+    ProductReviews:
+      type: object
+      properties:
+        productId:
+          type: string
+        averageRating:
+          type: number
+          minimum: 0
+          maximum: 5
+        reviewCount:
+          type: integer
+          minimum: 0
+        reviews:
+          type: array
+          items:
+            $ref: '#/components/schemas/Review'
+    SubmitReviewRequest:
+      type: object
+      required: [customerId, rating, body]
+      properties:
+        customerId:
+          type: string
+        rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        title:
+          type: string
+        body:
+          type: string
+    FlagReviewRequest:
+      type: object
+      required: [flaggedBy, reason]
+      properties:
+        flaggedBy:
+          type: string
+        reason:
+          type: string
+          enum: [spam, abuse, off_topic, inappropriate, other]
+        notes:
+          type: string
+    VoteReviewHelpfulRequest:
+      type: object
+      required: [customerId, vote]
+      properties:
+        customerId:
+          type: string
+        vote:
+          type: string
+          enum: [helpful, remove]
diff --git a/examples/default/domains/Reviews/services/RatingAggregator/events/rating-updated/index.mdx b/examples/default/domains/Reviews/services/RatingAggregator/events/rating-updated/index.mdx
new file mode 100644
index 000000000..22feb3771
--- /dev/null
+++ b/examples/default/domains/Reviews/services/RatingAggregator/events/rating-updated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: rating-updated
+name: Rating Updated
+version: 1.0.0
+summary: |
+  Published when a product's aggregate rating changes as a result of a newly published review.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RatingUpdated` is published by the [[service|rating-aggregator]] whenever a product's aggregate rating changes. Other domains (such as the storefront and search) can consume it to keep displayed ratings fresh.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Reviews/services/RatingAggregator/events/rating-updated/schema.json b/examples/default/domains/Reviews/services/RatingAggregator/events/rating-updated/schema.json
new file mode 100644
index 000000000..27ce8dfbf
--- /dev/null
+++ b/examples/default/domains/Reviews/services/RatingAggregator/events/rating-updated/schema.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RatingUpdated",
+  "type": "object",
+  "properties": {
+    "productId": { "type": "string" },
+    "averageRating": { "type": "number", "minimum": 0, "maximum": 5 },
+    "reviewCount": { "type": "integer", "minimum": 0 },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["productId", "averageRating", "reviewCount", "updatedAt"]
+}
diff --git a/examples/default/domains/Reviews/services/RatingAggregator/index.mdx b/examples/default/domains/Reviews/services/RatingAggregator/index.mdx
new file mode 100644
index 000000000..652ca2d40
--- /dev/null
+++ b/examples/default/domains/Reviews/services/RatingAggregator/index.mdx
@@ -0,0 +1,47 @@
+---
+id: rating-aggregator
+version: 1.0.0
+name: Rating Aggregator
+summary: |
+  Keeps each product's aggregate star rating up to date as reviews are published, and serves it fast from a cache.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - reviews-platform
+receives:
+  - id: review-published
+    version: 1.0.0
+sends:
+  - id: rating-updated
+    version: 1.0.0
+writesTo:
+  - id: rating-cache
+readsFrom:
+  - id: review-database
+  - id: rating-cache
+repository:
+  language: Go
+  url: 'https://github.com/acme/rating-aggregator'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Rating Aggregator** consumes [[event|review-published]] and recomputes the affected product's aggregate rating (average score and review count). It writes the result to the [[container|rating-cache]] for fast reads and publishes [[event|rating-updated]] so other domains can stay in sync.
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Aggregation | Recomputes average rating and review count per product. |
+| Caching | Writes aggregate ratings to the [[container\|rating-cache]]. |
+| Eventing | Publishes [[event\|rating-updated]] on every change. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/commands/flag-review/index.mdx b/examples/default/domains/Reviews/services/ReviewAPI/commands/flag-review/index.mdx
new file mode 100644
index 000000000..74d1fbcef
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/commands/flag-review/index.mdx
@@ -0,0 +1,29 @@
+---
+id: flag-review
+name: Flag Review
+version: 1.0.0
+summary: |
+  Command issued by a customer or moderator to flag a published review for re-moderation.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`FlagReview` is sent to the [[service|review-api]] when someone reports a published review as inappropriate. The API records the flag and publishes [[event|review-flagged]] so the review can be screened again.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/commands/flag-review/schema.json b/examples/default/domains/Reviews/services/ReviewAPI/commands/flag-review/schema.json
new file mode 100644
index 000000000..488407d6d
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/commands/flag-review/schema.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FlagReview",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "flaggedBy": { "type": "string", "description": "Customer or moderator id raising the flag." },
+    "reason": { "type": "string", "enum": ["spam", "abuse", "off_topic", "inappropriate", "other"] },
+    "notes": { "type": "string", "maxLength": 1000 },
+    "flaggedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "flaggedBy", "reason", "flaggedAt"]
+}
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/commands/submit-review/index.mdx b/examples/default/domains/Reviews/services/ReviewAPI/commands/submit-review/index.mdx
new file mode 100644
index 000000000..965b0f4f6
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/commands/submit-review/index.mdx
@@ -0,0 +1,29 @@
+---
+id: submit-review
+name: Submit Review
+version: 1.0.0
+summary: |
+  Command issued by a customer to submit a review and rating for a product.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`SubmitReview` is sent to the [[service|review-api]] when a customer submits a review for a product they have purchased. The API validates and stores the review, then publishes [[event|review-submitted]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/commands/submit-review/schema.json b/examples/default/domains/Reviews/services/ReviewAPI/commands/submit-review/schema.json
new file mode 100644
index 000000000..8b360e06f
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/commands/submit-review/schema.json
@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SubmitReview",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid", "description": "Client-generated id for the review." },
+    "productId": { "type": "string", "description": "The product being reviewed." },
+    "customerId": { "type": "string", "description": "The customer submitting the review." },
+    "rating": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Star rating from 1 to 5." },
+    "title": { "type": "string", "maxLength": 120 },
+    "body": { "type": "string", "maxLength": 5000 },
+    "submittedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "customerId", "rating", "body", "submittedAt"]
+}
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/index.mdx b/examples/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/index.mdx
new file mode 100644
index 000000000..9ce8ca853
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/index.mdx
@@ -0,0 +1,29 @@
+---
+id: vote-review-helpful
+name: Vote Review Helpful
+version: 1.0.0
+summary: |
+  Command issued by a customer to mark a published review as helpful (or remove their vote).
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`VoteReviewHelpful` is sent to the [[service|review-api]] when a customer marks a review as helpful. The API updates the helpful count and publishes [[event|review-helpful-voted]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/schema.json b/examples/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/schema.json
new file mode 100644
index 000000000..9707f3d6b
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/schema.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "VoteReviewHelpful",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "customerId": { "type": "string" },
+    "vote": { "type": "string", "enum": ["helpful", "remove"], "description": "Add a helpful vote or remove an existing one." },
+    "votedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "customerId", "vote", "votedAt"]
+}
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/events/review-flagged/index.mdx b/examples/default/domains/Reviews/services/ReviewAPI/events/review-flagged/index.mdx
new file mode 100644
index 000000000..e009c522d
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/events/review-flagged/index.mdx
@@ -0,0 +1,29 @@
+---
+id: review-flagged
+name: Review Flagged
+version: 1.0.0
+summary: |
+  Published when a published review is flagged and needs to be screened again.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReviewFlagged` is published by the [[service|review-api]] when a published review is flagged. The [[service|review-moderation-worker]] consumes it and re-screens the review, which may lead to it being rejected.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/events/review-flagged/schema.json b/examples/default/domains/Reviews/services/ReviewAPI/events/review-flagged/schema.json
new file mode 100644
index 000000000..b38a182b0
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/events/review-flagged/schema.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewFlagged",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "productId": { "type": "string" },
+    "reason": { "type": "string", "enum": ["spam", "abuse", "off_topic", "inappropriate", "other"] },
+    "flagCount": { "type": "integer", "minimum": 1, "description": "Total flags this review has now received." },
+    "flaggedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "reason", "flaggedAt"]
+}
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/events/review-helpful-voted/index.mdx b/examples/default/domains/Reviews/services/ReviewAPI/events/review-helpful-voted/index.mdx
new file mode 100644
index 000000000..7eef3fa54
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/events/review-helpful-voted/index.mdx
@@ -0,0 +1,29 @@
+---
+id: review-helpful-voted
+name: Review Helpful Voted
+version: 1.0.0
+summary: |
+  Published when a review's helpful count changes as a result of a customer vote.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReviewHelpfulVoted` is published by the [[service|review-api]] whenever a review's helpful count changes. It lets other surfaces (such as the storefront) keep "most helpful" ordering fresh.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/events/review-helpful-voted/schema.json b/examples/default/domains/Reviews/services/ReviewAPI/events/review-helpful-voted/schema.json
new file mode 100644
index 000000000..b8e2413ce
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/events/review-helpful-voted/schema.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewHelpfulVoted",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "productId": { "type": "string" },
+    "helpfulCount": { "type": "integer", "minimum": 0 },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "helpfulCount", "updatedAt"]
+}
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/events/review-submitted/index.mdx b/examples/default/domains/Reviews/services/ReviewAPI/events/review-submitted/index.mdx
new file mode 100644
index 000000000..ac2dfabd5
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/events/review-submitted/index.mdx
@@ -0,0 +1,29 @@
+---
+id: review-submitted
+name: Review Submitted
+version: 1.0.0
+summary: |
+  Published when a customer submits a review. The review is stored but not yet visible — it awaits moderation.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReviewSubmitted` is published by the [[service|review-api]] once a review has been accepted and stored. The [[service|review-moderation-worker]] consumes it to screen the review before it can be published.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/events/review-submitted/schema.json b/examples/default/domains/Reviews/services/ReviewAPI/events/review-submitted/schema.json
new file mode 100644
index 000000000..308f882b0
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/events/review-submitted/schema.json
@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewSubmitted",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "productId": { "type": "string" },
+    "customerId": { "type": "string" },
+    "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
+    "title": { "type": "string" },
+    "body": { "type": "string" },
+    "submittedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "customerId", "rating", "submittedAt"]
+}
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/index.mdx b/examples/default/domains/Reviews/services/ReviewAPI/index.mdx
new file mode 100644
index 000000000..0eccf6501
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/index.mdx
@@ -0,0 +1,58 @@
+---
+id: review-api
+version: 1.0.0
+name: Review API
+summary: |
+  The public-facing API for product reviews. Accepts review submissions, serves published reviews, and is the entry point into the Reviews & Ratings domain.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - reviews-platform
+receives:
+  - id: submit-review
+    version: 1.0.0
+  - id: flag-review
+    version: 1.0.0
+  - id: vote-review-helpful
+    version: 1.0.0
+  - id: get-product-reviews
+    version: 1.0.0
+sends:
+  - id: review-submitted
+    version: 1.0.0
+  - id: review-flagged
+    version: 1.0.0
+  - id: review-helpful-voted
+    version: 1.0.0
+writesTo:
+  - id: review-database
+readsFrom:
+  - id: review-database
+  - id: rating-cache
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/review-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Review API** is the front door to the Reviews & Ratings domain. It validates incoming [[command|submit-review]] commands, persists reviews to the [[container|review-database]], and publishes [[event|review-submitted]]. It also serves [[query|get-product-reviews]], reading published reviews from the [[container|review-database]] and aggregate ratings from the [[container|rating-cache]].
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Command handling | Validates and applies [[command\|submit-review]]. |
+| Reads | Serves [[query\|get-product-reviews]] from the review database and rating cache. |
+| Eventing | Publishes [[event\|review-submitted]] for moderation. |
+| Persistence | Writes to the [[container\|review-database]]; reads from the [[container\|review-database]] and [[container\|rating-cache]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/index.mdx b/examples/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/index.mdx
new file mode 100644
index 000000000..a218643d7
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/index.mdx
@@ -0,0 +1,24 @@
+---
+id: get-product-reviews
+name: Get Product Reviews
+version: 1.0.0
+summary: |
+  Query to fetch the published reviews and aggregate rating for a product.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetProductReviews` is served by the [[service|review-api]]. It returns the published reviews for a product along with its aggregate rating, read from the [[container|review-database]] and the [[container|rating-cache]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/schema.json b/examples/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/schema.json
new file mode 100644
index 000000000..a65eb3384
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/schema.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetProductReviews",
+  "type": "object",
+  "properties": {
+    "productId": { "type": "string", "description": "The product to fetch reviews for." },
+    "page": { "type": "integer", "minimum": 1, "default": 1 },
+    "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 },
+    "sort": { "type": "string", "enum": ["newest", "highest", "lowest", "most_helpful"], "default": "newest" }
+  },
+  "required": ["productId"]
+}
diff --git a/examples/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/index.mdx b/examples/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/index.mdx
new file mode 100644
index 000000000..774093e22
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/index.mdx
@@ -0,0 +1,29 @@
+---
+id: review-published
+name: Review Published
+version: 1.0.0
+summary: |
+  Published when a submitted review passes moderation and becomes visible on the storefront.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReviewPublished` is published by the [[service|review-moderation-worker]] when a review passes moderation. The [[service|rating-aggregator]] consumes it to update the product's aggregate rating.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/schema.json b/examples/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/schema.json
new file mode 100644
index 000000000..6420fec00
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/schema.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewPublished",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "productId": { "type": "string" },
+    "customerId": { "type": "string" },
+    "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
+    "publishedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "rating", "publishedAt"]
+}
diff --git a/examples/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/index.mdx b/examples/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/index.mdx
new file mode 100644
index 000000000..1074977a6
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/index.mdx
@@ -0,0 +1,29 @@
+---
+id: review-rejected
+name: Review Rejected
+version: 1.0.0
+summary: |
+  Published when a submitted review fails moderation (spam, abuse or policy violation) and will not be shown.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReviewRejected` is published by the [[service|review-moderation-worker]] when a review fails moderation. The review is kept for audit but never published to the storefront.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/schema.json b/examples/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/schema.json
new file mode 100644
index 000000000..aa777cc49
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/schema.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewRejected",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "productId": { "type": "string" },
+    "reason": { "type": "string", "enum": ["spam", "abuse", "off_topic", "policy_violation"] },
+    "rejectedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "reason", "rejectedAt"]
+}
diff --git a/examples/default/domains/Reviews/services/ReviewModerationWorker/index.mdx b/examples/default/domains/Reviews/services/ReviewModerationWorker/index.mdx
new file mode 100644
index 000000000..6b856a871
--- /dev/null
+++ b/examples/default/domains/Reviews/services/ReviewModerationWorker/index.mdx
@@ -0,0 +1,50 @@
+---
+id: review-moderation-worker
+version: 1.0.0
+name: Review Moderation Worker
+summary: |
+  Asynchronous worker that screens submitted reviews for spam, abuse and policy violations, then publishes or rejects them.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - reviews-platform
+receives:
+  - id: review-submitted
+    version: 1.0.0
+  - id: review-flagged
+    version: 1.0.0
+sends:
+  - id: review-published
+    version: 1.0.0
+  - id: review-rejected
+    version: 1.0.0
+writesTo:
+  - id: review-database
+readsFrom:
+  - id: review-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/review-moderation-worker'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Review Moderation Worker** consumes [[event|review-submitted]] (and [[event|review-flagged]] for already-published reviews), screens each review (automated checks plus thresholds for manual review), and records the outcome on the [[container|review-database]]. It then publishes either [[event|review-published]] or [[event|review-rejected]].
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Moderation | Screens reviews for spam, abuse and policy violations. |
+| Outcome | Publishes [[event\|review-published]] or [[event\|review-rejected]]. |
+| Persistence | Records the moderation decision on the [[container\|review-database]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Shopping/entities/cart-item/index.mdx b/examples/default/domains/Shopping/entities/cart-item/index.mdx
new file mode 100644
index 000000000..0f6a7b38e
--- /dev/null
+++ b/examples/default/domains/Shopping/entities/cart-item/index.mdx
@@ -0,0 +1,38 @@
+---
+id: cart-item
+name: Cart Item
+version: 1.0.0
+identifier: cartItemId
+summary: A product variant and quantity inside a cart.
+owners:
+  - shopping-platform
+properties:
+  - name: cartItemId
+    type: UUID
+    required: true
+    description: Unique cart item identifier.
+  - name: cartId
+    type: UUID
+    required: true
+    description: Cart this item belongs to.
+    references: cart
+    relationType: belongsTo
+    referencesIdentifier: cartId
+  - name: productId
+    type: UUID
+    required: true
+    description: Product selected by the customer.
+    references: product
+    relationType: references
+    referencesIdentifier: productId
+  - name: quantity
+    type: integer
+    required: true
+    description: Quantity requested.
+---
+
+## Overview
+
+Cart Item records the customer's intent to buy a product variant before checkout. It is owned by [[entity|cart]].
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Shopping/entities/cart/index.mdx b/examples/default/domains/Shopping/entities/cart/index.mdx
new file mode 100644
index 000000000..bd298f675
--- /dev/null
+++ b/examples/default/domains/Shopping/entities/cart/index.mdx
@@ -0,0 +1,40 @@
+---
+id: cart
+name: Cart
+version: 1.0.0
+identifier: cartId
+aggregateRoot: true
+summary: The customer's active collection of items before an order exists.
+owners:
+  - shopping-platform
+properties:
+  - name: cartId
+    type: UUID
+    required: true
+    description: Unique cart identifier.
+  - name: customerId
+    type: UUID
+    required: false
+    description: Customer that owns the cart, if authenticated.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: status
+    type: string
+    required: true
+    description: Current cart state.
+    enum:
+      - active
+      - checked-out
+      - abandoned
+  - name: updatedAt
+    type: datetime
+    required: true
+    description: Time the cart last changed.
+---
+
+## Overview
+
+Cart is the Shopping domain aggregate. It accepts item changes and emits [[event|cart-checked-out]] when the customer commits to buy.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Shopping/entities/discount/index.mdx b/examples/default/domains/Shopping/entities/discount/index.mdx
new file mode 100644
index 000000000..94f68325a
--- /dev/null
+++ b/examples/default/domains/Shopping/entities/discount/index.mdx
@@ -0,0 +1,35 @@
+---
+id: discount
+name: Discount
+version: 1.0.0
+identifier: discountId
+summary: The calculated benefit applied to a cart or cart item.
+owners:
+  - shopping-platform
+properties:
+  - name: discountId
+    type: UUID
+    required: true
+    description: Unique discount identifier.
+  - name: promotionId
+    type: UUID
+    required: false
+    description: Promotion that produced the discount.
+    references: promotion
+    relationType: derivedFrom
+    referencesIdentifier: promotionId
+  - name: amount
+    type: decimal
+    required: true
+    description: Monetary value of the discount.
+  - name: reason
+    type: string
+    required: true
+    description: Human-readable explanation for the discount.
+---
+
+## Overview
+
+Discount is a calculated result from [[command|calculate-discount]]. It is separate from cart persistence so promotion logic can evolve independently.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Shopping/entities/promotion/index.mdx b/examples/default/domains/Shopping/entities/promotion/index.mdx
new file mode 100644
index 000000000..052c9bf04
--- /dev/null
+++ b/examples/default/domains/Shopping/entities/promotion/index.mdx
@@ -0,0 +1,40 @@
+---
+id: promotion
+name: Promotion
+version: 1.0.0
+identifier: promotionId
+aggregateRoot: true
+summary: A commercial offer evaluated against a cart.
+owners:
+  - shopping-platform
+properties:
+  - name: promotionId
+    type: UUID
+    required: true
+    description: Unique promotion identifier.
+  - name: code
+    type: string
+    required: false
+    description: Optional customer-entered promotion code.
+  - name: categoryId
+    type: UUID
+    required: false
+    description: Category the promotion applies to when scoped.
+    references: category
+    relationType: appliesTo
+    referencesIdentifier: categoryId
+  - name: status
+    type: string
+    required: true
+    description: Promotion lifecycle state.
+  - name: startsAt
+    type: datetime
+    required: true
+    description: When the promotion becomes active.
+---
+
+## Overview
+
+Promotion is owned by the Promotion System and is evaluated when Shopping calculates discounts for a cart.
+
+<EntityPropertiesTable />
diff --git a/examples/default/domains/Shopping/index.mdx b/examples/default/domains/Shopping/index.mdx
new file mode 100644
index 000000000..83673c9b0
--- /dev/null
+++ b/examples/default/domains/Shopping/index.mdx
@@ -0,0 +1,67 @@
+---
+id: shopping
+name: Shopping
+version: 1.0.0
+summary: |
+  The Shopping domain owns the customer's path to purchase — building a cart, applying promotions, and checking out. It coordinates the cart and the discounts that apply to it.
+owners:
+  - shopping-platform
+systems:
+  - id: cart-system
+    version: 1.0.0
+  - id: promotion-system
+    version: 1.0.0
+entities:
+  - id: cart
+    version: 1.0.0
+  - id: cart-item
+    version: 1.0.0
+  - id: promotion
+    version: 1.0.0
+  - id: discount
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Shopping** domain is responsible for everything between browsing and buying — the shopping cart and the promotions applied to it. It is split into two systems:
+
+<Tiles>
+  <Tile
+    icon="ShoppingCartIcon"
+    href="/docs/systems/cart-system/1.0.0"
+    title="Cart System"
+    description="System of record for shopping carts — add, remove and check out items."
+  />
+  <Tile
+    icon="TagIcon"
+    href="/docs/systems/promotion-system/1.0.0"
+    title="Promotion System"
+    description="Calculates the discounts and promotions that apply to a cart."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Cart System** owns the customer's cart and the checkout flow. When pricing a cart, it asks the **Promotion System** to calculate the discounts that apply. When the customer checks out, the Cart System publishes an event the rest of the business reacts to.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The components that make up this domain.
+
+<NodeGraph />
diff --git a/examples/default/domains/Shopping/systems/cart-system/containers/cart-database/index.mdx b/examples/default/domains/Shopping/systems/cart-system/containers/cart-database/index.mdx
new file mode 100644
index 000000000..8e1e634f0
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/containers/cart-database/index.mdx
@@ -0,0 +1,39 @@
+---
+id: cart-database
+name: Cart Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for shopping carts and their items.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for shopping carts
+classification: internal
+retention: 90d
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Cart Database** is the authoritative store for shopping carts at Acme Inc. The [[service|cart-api]] reads from and writes to it as customers add, remove and check out items.
+
+### What does it store?
+
+- **Carts** — one row per cart: id, customer, status and timestamps.
+- **Cart Items** — one row per item in a cart: product, quantity and unit price.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Cart Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Retention
+
+Carts are transient. Abandoned carts are pruned after **90 days** (see frontmatter). A checked-out cart's contents live on in the [[event|cart-checked-out]] event and downstream order records.
diff --git a/examples/default/domains/Shopping/systems/cart-system/containers/cart-database/schema.sql b/examples/default/domains/Shopping/systems/cart-system/containers/cart-database/schema.sql
new file mode 100644
index 000000000..113fc17f4
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/containers/cart-database/schema.sql
@@ -0,0 +1,22 @@
+-- Cart Database — system of record for shopping carts
+
+CREATE TABLE carts (
+    cart_id      UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    customer_id  UUID,
+    status       TEXT NOT NULL DEFAULT 'OPEN'
+                   CHECK (status IN ('OPEN', 'CHECKED_OUT', 'ABANDONED')),
+    currency     CHAR(3) NOT NULL DEFAULT 'USD',
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE cart_items (
+    cart_id          UUID NOT NULL REFERENCES carts (cart_id) ON DELETE CASCADE,
+    product_id       UUID NOT NULL,
+    quantity         INTEGER NOT NULL CHECK (quantity > 0),
+    unit_price_cents INTEGER NOT NULL CHECK (unit_price_cents >= 0),
+    PRIMARY KEY (cart_id, product_id)
+);
+
+CREATE INDEX idx_carts_customer ON carts (customer_id);
+CREATE INDEX idx_carts_status   ON carts (status);
diff --git a/examples/default/domains/Shopping/systems/cart-system/index.mdx b/examples/default/domains/Shopping/systems/cart-system/index.mdx
new file mode 100644
index 000000000..d1b8c9108
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/index.mdx
@@ -0,0 +1,53 @@
+---
+id: cart-system
+name: Cart System
+version: 1.0.0
+summary: |
+  Internal system that owns the customer's shopping cart and the checkout flow. It is the source of truth for cart contents and publishes an event when a cart is checked out.
+owners:
+  - shopping-platform
+services:
+  - id: cart-api
+containers:
+  - id: cart-database
+relationships:
+  - id: promotion-system
+    label: calculates discounts via
+actors:
+  - id: shopper
+    name: Shopper
+    label: adds items and checks out
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Cart System** owns the shopping cart at Acme Inc. It accepts commands to add and remove items and to check out, persists cart contents in the [[container|cart-database]], and asks the [[system|promotion-system]] to calculate the discounts that apply. When a cart is checked out it publishes a [[event|cart-checked-out]] event.
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|cart-api]] | Service | Public-facing API. Handles add/remove/checkout commands and publishes the checkout event. |
+| [[container\|cart-database]] | Data store | PostgreSQL system of record for shopping carts and their items. |
+
+## Messages this system publishes
+
+- [[event|cart-checked-out]] — a customer has checked out their cart.
diff --git a/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/index.mdx b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/index.mdx
new file mode 100644
index 000000000..0d310bef9
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/index.mdx
@@ -0,0 +1,32 @@
+---
+id: add-item-to-cart
+name: Add Item To Cart
+version: 1.0.0
+summary: |
+  Command to add an item to a shopping cart.
+owners:
+  - shopping-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /carts/{cartId}/items
+  statusCodes: ['200', '400', '404']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`AddItemToCart` is handled by the [[service|cart-api]]. It adds an item (or increases its quantity) in the cart and persists the change to the [[container|cart-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/schema.json b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/schema.json
new file mode 100644
index 000000000..2ff550e23
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/schema.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AddItemToCart",
+  "description": "Command to add an item to a shopping cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Unique identifier of the cart",
+      "type": "string",
+      "format": "uuid"
+    },
+    "productId": {
+      "description": "Identifier of the product to add",
+      "type": "string",
+      "format": "uuid"
+    },
+    "quantity": {
+      "description": "Number of units to add",
+      "type": "integer",
+      "minimum": 1,
+      "default": 1
+    }
+  },
+  "required": ["cartId", "productId", "quantity"]
+}
diff --git a/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/index.mdx b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/index.mdx
new file mode 100644
index 000000000..8b2dde56c
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/index.mdx
@@ -0,0 +1,32 @@
+---
+id: checkout-cart
+name: Checkout Cart
+version: 1.0.0
+summary: |
+  Command to check out a shopping cart.
+owners:
+  - shopping-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /carts/{cartId}/checkout
+  statusCodes: ['200', '400', '404', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CheckoutCart` is handled by the [[service|cart-api]]. It finalises the cart — pricing it (including discounts from the [[system|promotion-system]]) — and on success publishes a [[event|cart-checked-out]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/schema.json b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/schema.json
new file mode 100644
index 000000000..57c74aed5
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/schema.json
@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CheckoutCart",
+  "description": "Command to check out a shopping cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Unique identifier of the cart to check out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "description": "Identifier of the customer checking out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "promotionCode": {
+      "description": "Optional promotion code to apply at checkout",
+      "type": "string"
+    }
+  },
+  "required": ["cartId", "customerId"]
+}
diff --git a/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/index.mdx b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/index.mdx
new file mode 100644
index 000000000..6fd484071
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/index.mdx
@@ -0,0 +1,32 @@
+---
+id: remove-item-from-cart
+name: Remove Item From Cart
+version: 1.0.0
+summary: |
+  Command to remove an item from a shopping cart.
+owners:
+  - shopping-platform
+schemaPath: schema.json
+operation:
+  method: DELETE
+  path: /carts/{cartId}/items/{productId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'DELETE'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RemoveItemFromCart` is handled by the [[service|cart-api]]. It removes an item from the cart (or decreases its quantity) and persists the change to the [[container|cart-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/schema.json b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/schema.json
new file mode 100644
index 000000000..d3dcbfe60
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RemoveItemFromCart",
+  "description": "Command to remove an item from a shopping cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Unique identifier of the cart",
+      "type": "string",
+      "format": "uuid"
+    },
+    "productId": {
+      "description": "Identifier of the product to remove",
+      "type": "string",
+      "format": "uuid"
+    },
+    "quantity": {
+      "description": "Number of units to remove. If omitted, removes the item entirely.",
+      "type": "integer",
+      "minimum": 1
+    }
+  },
+  "required": ["cartId", "productId"]
+}
diff --git a/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/index.mdx b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/index.mdx
new file mode 100644
index 000000000..fc2b7875c
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/index.mdx
@@ -0,0 +1,29 @@
+---
+id: cart-checked-out
+name: Cart Checked Out
+version: 1.0.0
+summary: |
+  Published when a customer has checked out their cart.
+owners:
+  - shopping-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CartCheckedOut` is published by the [[service|cart-api]] when a customer checks out. Downstream systems consume this event to create an order, take payment, and begin fulfilment.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/schema.json b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/schema.json
new file mode 100644
index 000000000..3242b297e
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/schema.json
@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CartCheckedOut",
+  "description": "Emitted when a customer checks out their cart",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "cartId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "quantity": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "unitPrice": {
+            "description": "Price per unit in minor units (e.g. cents)",
+            "type": "integer"
+          }
+        },
+        "required": ["productId", "quantity", "unitPrice"]
+      }
+    },
+    "subtotal": {
+      "description": "Total before discounts, in minor units (e.g. cents)",
+      "type": "integer"
+    },
+    "discount": {
+      "description": "Total discount applied, in minor units (e.g. cents)",
+      "type": "integer"
+    },
+    "total": {
+      "description": "Final total, in minor units (e.g. cents)",
+      "type": "integer"
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    }
+  },
+  "required": ["eventId", "occurredAt", "cartId", "customerId", "items", "total", "currency"]
+}
diff --git a/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/index.mdx b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/index.mdx
new file mode 100644
index 000000000..45fc15d95
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/index.mdx
@@ -0,0 +1,62 @@
+---
+id: cart-api
+version: 1.0.0
+name: Cart API
+summary: |
+  The public-facing API for shopping carts. Handles commands to add and remove items and to check out, and publishes an event when a cart is checked out.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - shopping-platform
+receives:
+  - id: add-item-to-cart
+    version: 1.0.0
+  - id: remove-item-from-cart
+    version: 1.0.0
+  - id: checkout-cart
+    version: 1.0.0
+sends:
+  - id: cart-checked-out
+    version: 1.0.0
+  - id: calculate-discount
+    version: 1.0.0
+writesTo:
+  - id: cart-database
+readsFrom:
+  - id: cart-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/cart-api'
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Cart API
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Cart API** is the front door to the Cart System. It validates incoming commands, persists cart contents to the [[container|cart-database]], asks the [[system|promotion-system]] to calculate discounts via [[command|calculate-discount]], and publishes a [[event|cart-checked-out]] event when the customer checks out.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} messages`} description="Checkout event and discount requests" />
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="Cart commands handled by this service" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Cart management | Validates and applies [[command\|add-item-to-cart]], [[command\|remove-item-from-cart]] and [[command\|checkout-cart]]. |
+| Discounts | Requests pricing from the Promotion System via [[command\|calculate-discount]]. |
+| Event publishing | Emits [[event\|cart-checked-out]] when a cart is checked out. |
+| Persistence | Reads from and writes to the [[container\|cart-database]] (system of record). |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/openapi.yml b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/openapi.yml
new file mode 100644
index 000000000..3671bc55c
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/cart-system/services/CartAPI/openapi.yml
@@ -0,0 +1,200 @@
+openapi: 3.0.3
+info:
+  title: Cart API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Cart System. Customers use it to build a cart —
+    adding and removing items — and to check out. At checkout the cart is priced
+    (including discounts from the Promotion System) and a `CartCheckedOut` event
+    is published.
+  contact:
+    name: Shopping Platform
+    email: shopping-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+tags:
+  - name: Cart
+    description: Build and check out a shopping cart.
+paths:
+  /carts/{cartId}/items:
+    parameters:
+      - $ref: '#/components/parameters/CartId'
+    post:
+      operationId: addItemToCart
+      summary: Add an item to the cart
+      tags:
+        - Cart
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AddItemRequest'
+      responses:
+        '200':
+          description: The item was added; the updated cart is returned.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Cart'
+        '400':
+          description: The request was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: The cart was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /carts/{cartId}/items/{productId}:
+    parameters:
+      - $ref: '#/components/parameters/CartId'
+      - name: productId
+        in: path
+        required: true
+        description: Identifier of the product to remove.
+        schema:
+          type: string
+          format: uuid
+    delete:
+      operationId: removeItemFromCart
+      summary: Remove an item from the cart
+      tags:
+        - Cart
+      responses:
+        '200':
+          description: The item was removed; the updated cart is returned.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Cart'
+        '404':
+          description: The cart or item was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /carts/{cartId}/checkout:
+    parameters:
+      - $ref: '#/components/parameters/CartId'
+    post:
+      operationId: checkoutCart
+      summary: Check out the cart
+      description: Prices the cart (including discounts) and, on success, publishes a `CartCheckedOut` event.
+      tags:
+        - Cart
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CheckoutRequest'
+      responses:
+        '200':
+          description: The cart was checked out.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Cart'
+        '400':
+          description: The request was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: The cart was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: The cart is empty or already checked out.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  parameters:
+    CartId:
+      name: cartId
+      in: path
+      required: true
+      description: Unique identifier of the cart.
+      schema:
+        type: string
+        format: uuid
+  schemas:
+    Cart:
+      type: object
+      required: [cartId, status, items, currency]
+      properties:
+        cartId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [OPEN, CHECKED_OUT, ABANDONED]
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/CartItem'
+        subtotal:
+          type: integer
+          description: Total before discounts, in minor units (e.g. cents).
+        discount:
+          type: integer
+          description: Total discount applied, in minor units (e.g. cents).
+        total:
+          type: integer
+          description: Final total, in minor units (e.g. cents).
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+    CartItem:
+      type: object
+      required: [productId, quantity, unitPrice]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        quantity:
+          type: integer
+          minimum: 1
+        unitPrice:
+          type: integer
+          description: Price per unit in minor units (e.g. cents).
+    AddItemRequest:
+      type: object
+      required: [productId, quantity]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        quantity:
+          type: integer
+          minimum: 1
+    CheckoutRequest:
+      type: object
+      required: [customerId]
+      properties:
+        customerId:
+          type: string
+          format: uuid
+        promotionCode:
+          type: string
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string
diff --git a/examples/default/domains/Shopping/systems/promotion-system/containers/promotion-database/index.mdx b/examples/default/domains/Shopping/systems/promotion-system/containers/promotion-database/index.mdx
new file mode 100644
index 000000000..f552037eb
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/promotion-system/containers/promotion-database/index.mdx
@@ -0,0 +1,40 @@
+---
+id: promotion-database
+name: Promotion Database
+version: 1.0.0
+summary: PostgreSQL store of promotion and discount rules.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for promotion and discount rules
+classification: internal
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Promotion Database** holds the promotion and discount rules that the [[service|promotion-service]] evaluates when pricing a cart. It is the source of truth for what promotions exist, who they apply to, and when they are valid.
+
+### What does it store?
+
+- **Promotions** — one row per promotion: code, type (percentage / fixed amount), value, and validity window.
+- **Eligibility rules** — the conditions under which a promotion applies (minimum spend, customer segment, etc.).
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Promotion Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Access patterns
+
+- The [[service|promotion-service]] reads rules when handling [[command|calculate-discount]].
+- Rules are managed by the promotions team and change infrequently relative to read volume.
diff --git a/examples/default/domains/Shopping/systems/promotion-system/containers/promotion-database/schema.sql b/examples/default/domains/Shopping/systems/promotion-system/containers/promotion-database/schema.sql
new file mode 100644
index 000000000..125d58a1b
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/promotion-system/containers/promotion-database/schema.sql
@@ -0,0 +1,21 @@
+-- Promotion Database — system of record for promotion and discount rules
+
+CREATE TABLE promotions (
+    promotion_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    code         TEXT NOT NULL UNIQUE,
+    description  TEXT,
+    type         TEXT NOT NULL CHECK (type IN ('PERCENTAGE', 'FIXED_AMOUNT')),
+    value        INTEGER NOT NULL CHECK (value >= 0),
+    starts_at    TIMESTAMPTZ NOT NULL,
+    ends_at      TIMESTAMPTZ,
+    active       BOOLEAN NOT NULL DEFAULT true
+);
+
+CREATE TABLE eligibility_rules (
+    promotion_id     UUID NOT NULL REFERENCES promotions (promotion_id) ON DELETE CASCADE,
+    min_spend_cents  INTEGER CHECK (min_spend_cents >= 0),
+    customer_segment TEXT,
+    PRIMARY KEY (promotion_id)
+);
+
+CREATE INDEX idx_promotions_active ON promotions (active) WHERE active = true;
diff --git a/examples/default/domains/Shopping/systems/promotion-system/index.mdx b/examples/default/domains/Shopping/systems/promotion-system/index.mdx
new file mode 100644
index 000000000..658f2f878
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/promotion-system/index.mdx
@@ -0,0 +1,48 @@
+---
+id: promotion-system
+name: Promotion System
+version: 1.0.0
+summary: |
+  Internal system that calculates the discounts and promotions that apply to a cart. It owns promotion rules and returns calculated discounts to the Cart System.
+owners:
+  - shopping-platform
+services:
+  - id: promotion-service
+containers:
+  - id: promotion-database
+relationships:
+  - id: cart-system
+    label: provides discounts to
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Promotion System** owns the discount and promotion rules at Acme Inc. It receives requests to calculate the discount for a cart, evaluates the applicable rules from the [[container|promotion-database]], and publishes a [[event|discount-calculated]] event with the result. It provides discounts to the [[system|cart-system]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component | Type | Responsibility |
+|-----------|------|----------------|
+| [[service\|promotion-service]] | Service | Evaluates promotion rules and calculates discounts for a cart. |
+| [[container\|promotion-database]] | Data store | PostgreSQL store of promotion and discount rules. |
+
+## Messages this system publishes
+
+- [[event|discount-calculated]] — a discount has been calculated for a cart.
diff --git a/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/index.mdx b/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/index.mdx
new file mode 100644
index 000000000..70fc6186f
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/index.mdx
@@ -0,0 +1,32 @@
+---
+id: calculate-discount
+name: Calculate Discount
+version: 1.0.0
+summary: |
+  Command to calculate the discount that applies to a cart.
+owners:
+  - shopping-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /discounts/calculate
+  statusCodes: ['200', '400']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CalculateDiscount` is handled by the [[service|promotion-service]]. It is sent by the [[service|cart-api]] when pricing a cart. The service evaluates the applicable promotion rules and returns the discount, also publishing a [[event|discount-calculated]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/schema.json b/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/schema.json
new file mode 100644
index 000000000..8fb6c243c
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/schema.json
@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CalculateDiscount",
+  "description": "Command to calculate the discount for a cart, and the discount returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "type": "object",
+      "properties": {
+        "cartId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "customerId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "subtotal": {
+          "description": "Cart subtotal before discounts, in minor units (e.g. cents)",
+          "type": "integer",
+          "minimum": 0
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "promotionCode": {
+          "description": "Optional promotion code supplied by the customer",
+          "type": "string"
+        }
+      },
+      "required": ["cartId", "subtotal", "currency"]
+    },
+    "response": {
+      "type": "object",
+      "properties": {
+        "discount": {
+          "description": "Total discount to apply, in minor units (e.g. cents)",
+          "type": "integer",
+          "minimum": 0
+        },
+        "appliedPromotions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": ["discount"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/index.mdx b/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/index.mdx
new file mode 100644
index 000000000..eb2dc0182
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: discount-calculated
+name: Discount Calculated
+version: 1.0.0
+summary: |
+  Published when a discount has been calculated for a cart.
+owners:
+  - shopping-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`DiscountCalculated` is published by the [[service|promotion-service]] after evaluating the promotion rules for a cart. The [[system|cart-system]] uses the result to price the cart, and other systems can consume it for analytics.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/schema.json b/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/schema.json
new file mode 100644
index 000000000..a4f22b48a
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/schema.json
@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "DiscountCalculated",
+  "description": "Emitted when a discount has been calculated for a cart",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "cartId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "discount": {
+      "description": "Total discount applied, in minor units (e.g. cents)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "appliedPromotions": {
+      "description": "Identifiers of the promotions that were applied",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": ["eventId", "occurredAt", "cartId", "discount", "currency"]
+}
diff --git a/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/index.mdx b/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/index.mdx
new file mode 100644
index 000000000..4ea87ec2b
--- /dev/null
+++ b/examples/default/domains/Shopping/systems/promotion-system/services/PromotionService/index.mdx
@@ -0,0 +1,49 @@
+---
+id: promotion-service
+version: 1.0.0
+name: Promotion Service
+summary: |
+  Evaluates promotion rules and calculates the discount that applies to a cart. Receives discount requests and publishes the calculated result.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - shopping-platform
+receives:
+  - id: calculate-discount
+    version: 1.0.0
+sends:
+  - id: discount-calculated
+    version: 1.0.0
+readsFrom:
+  - id: promotion-database
+repository:
+  language: Go
+  url: 'https://github.com/acme/promotion-service'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Promotion Service** is the heart of the Promotion System. It receives [[command|calculate-discount]] requests from the [[system|cart-system]], evaluates the applicable rules from the [[container|promotion-database]], and publishes a [[event|discount-calculated]] event with the result.
+
+<Tiles>
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Sends ${frontmatter.sends.length} message`} description="The calculated discount, published as an event" />
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} message`} description="Discount calculation requests" />
+</Tiles>
+
+### Responsibilities
+
+| Area | Description |
+|------|-------------|
+| Discount calculation | Handles [[command\|calculate-discount]] and evaluates promotion rules. |
+| Rules | Reads promotion and discount rules from the [[container\|promotion-database]]. |
+| Event publishing | Emits [[event\|discount-calculated]] with the calculated result. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />
diff --git a/examples/default/domains/Shopping/ubiquitous-language.mdx b/examples/default/domains/Shopping/ubiquitous-language.mdx
new file mode 100644
index 000000000..60676a0fb
--- /dev/null
+++ b/examples/default/domains/Shopping/ubiquitous-language.mdx
@@ -0,0 +1,48 @@
+---
+dictionary:
+  - id: Cart
+    name: Cart
+    summary: "A customer's in-progress collection of items they intend to buy."
+    description: |
+      The cart is the central concept of the Shopping domain. It is owned by the Cart System, which
+      is the source of truth for cart contents. A cart has a status (OPEN, CHECKED_OUT or ABANDONED),
+      a customer, a currency, and a set of cart items. Carts are transient — abandoned carts are
+      pruned after a retention window.
+    icon: ShoppingCart
+  - id: Cart Item
+    name: Cart Item
+    summary: "A single product line within a cart: a product, a quantity and a unit price."
+    icon: ListOrdered
+  - id: Checkout
+    name: Checkout
+    summary: "The act of finalising a cart — pricing it and committing to purchase."
+    description: |
+      At checkout the Cart System prices the cart (including any discounts from the Promotion System)
+      and, on success, publishes a CartCheckedOut event that the rest of the business reacts to —
+      creating an order, taking payment and beginning fulfilment.
+    icon: CreditCard
+  - id: Promotion
+    name: Promotion
+    summary: "A rule that reduces the price of a cart, such as a percentage off or a fixed amount."
+    description: |
+      Promotions are owned by the Promotion System. Each promotion has a code, a type (PERCENTAGE or
+      FIXED_AMOUNT), a value, a validity window, and eligibility rules (e.g. minimum spend or customer
+      segment) that determine when it applies.
+    icon: Tag
+  - id: Discount
+    name: Discount
+    summary: "The actual amount taken off a specific cart after evaluating the applicable promotions."
+    description: |
+      A discount is the calculated result of applying promotions to a cart. The Cart System asks the
+      Promotion System to calculate it; the Promotion System evaluates the rules and returns the
+      discount, also publishing a DiscountCalculated event.
+    icon: Percent
+  - id: Subtotal
+    name: Subtotal
+    summary: "The total value of a cart's items before any discounts are applied."
+    icon: Calculator
+  - id: Promotion Code
+    name: Promotion Code
+    summary: "A code a customer enters at checkout to apply a specific promotion."
+    icon: Ticket
+---
diff --git a/examples/default/eventcatalog.auth.js b/examples/default/eventcatalog.auth.js
deleted file mode 100644
index 472a1df28..000000000
--- a/examples/default/eventcatalog.auth.js
+++ /dev/null
@@ -1,24 +0,0 @@
-export default {
-    debug: false,
-    providers: {
-        github: {
-            clientId: process.env.GITHUB_CLIENT_ID,
-            clientSecret: process.env.GITHUB_CLIENT_SECRET
-        },
-        okta: {
-            clientId: process.env.AUTH_OKTA_ID,
-            clientSecret: process.env.AUTH_OKTA_SECRET,
-            issuer: process.env.AUTH_OKTA_ISSUER,
-        },
-        entra: {
-            clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
-            clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
-            issuer: process.env.AUTH_MICROSOFT_ENTRA_ID_ISSUER,
-        },
-        auth0: {
-            clientId: process.env.AUTH_AUTH0_ID,
-            clientSecret: process.env.AUTH_AUTH0_SECRET,
-            issuer: process.env.AUTH_AUTH0_ISSUER,
-        },
-    },
-}
\ No newline at end of file
diff --git a/examples/default/eventcatalog.config.js b/examples/default/eventcatalog.config.js
index add492eb2..1a38aabe3 100644
--- a/examples/default/eventcatalog.config.js
+++ b/examples/default/eventcatalog.config.js
@@ -5,109 +5,102 @@ const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
 
 /** @type {import('../../bin/eventcatalog.config').Config} */
 export default {
-  cId: '8027010c-f3d6-417a-8234-e2f46087fc56',
-  title: 'FlowMart',
-  tagline: 'Welcome to FlowMart EventCatalog. Here you can find all the information you need to know about our events and services (demo catalog).',
-  organizationName: 'FlowMart',
-  homepageLink: 'https://eventcatalog.dev',
-  editUrl: 'https://github.com/event-catalog/eventcatalog/edit/main',
+  cId: "8027010c-f3d6-417a-8234-e2f46087fc56",
+  title: "Acme Inc",
+  tagline: "Discover, Explore and Document your Event Driven Architectures.",
+  organizationName: "Acme Inc",
+  homepageLink: "https://eventcatalog.dev",
+  editUrl: "https://github.com/event-catalog/eventcatalog/edit/main",
   port: 3000,
-  outDir: 'dist',
-  // output: 'server',
+  outDir: "dist",
   logo: {
-    alt: 'FlowMart',
-    src: '/logo.png',
-    text: 'FlowMart',
+    src: "/logo.png",
+    text: "Acme Inc",
   },
-  base: '/',
+
+  base: "/",
   trailingSlash: false,
+
+  // Theme: 'default', 'ocean', 'sapphire', 'sunset', 'forest', or custom (defined in eventcatalog.styles.css)
+  theme: "sunset",
+
   mermaid: {
     enableSupportForElkLayout: true,
-    iconPacks: ['logos'],
+    iconPacks: ["logos"],
   },
+
   rss: {
     enabled: true,
     limit: 15,
   },
-  llmsTxt: {
-    enabled: true,
-  },
-  // chat: {
-  //   enabled: true,
-  //   provider: 'openai',
-  //   model: 'gpt-4.1',
+
+  // navigation: {
+  //   pages: [
+  //     {
+  //       type: "group",
+  //       title: "Domains",
+  //       icon: "Boxes",
+  //       pages: [
+  //         "domain:catalog",
+  //         "domain:customer",
+  //         "domain:shopping",
+  //         "domain:ordering",
+  //         "domain:payments",
+  //         "domain:fulfilment",
+  //         "domain:reviews",
+  //       ],
+  //     },
+  //     {
+  //       type: "group",
+  //       title: "Top level diagrams",
+  //       icon: "Workflow",
+  //       pages: [
+  //         {
+  //           type: "item",
+  //           title: "System Context Map",
+  //           href: "/visualiser/system-context-map",
+  //         },
+  //       ],
+  //     },
+  //   ],
   // },
+
   customDocs: {
     sidebar: [
       {
-        label: 'Guides',
-        badge: {
-          text: 'New', color: 'green'
-        },
+        label: "Platform",
+        collapsed: false,
+        autogenerated: { directory: "/platform" },
+      },
+      {
+        label: "Domains",
         collapsed: false,
-        items: [
-          {
-            label: 'Creating new microservices', autogenerated: { directory: 'guides/creating-new-microservices' }
-          },
-          {
-            label: 'Event Storming', autogenerated: { directory: 'guides/event-storming', collapsed: false }
-          }
-        ]
+        autogenerated: { directory: "/domains" },
       },
       {
-        label: 'Technical Architecture & Design',
-        badge: {
-          text: 'New', color: 'green'
-        },
+        label: "Flows",
         collapsed: false,
-        items: [
-          {
-            label: 'Architecture Decision Records', autogenerated: { directory: 'technical-architecture-design/architecture-decision-records', collapsed: false }
-          },
-          { label: 'System Architecture Diagrams', autogenerated: { directory: 'technical-architecture-design/system-architecture-diagrams', collapsed: false } },
-          { label: 'Infrastructure as Code', autogenerated: { directory: 'technical-architecture-design/infrastructure-as-code', collapsed: false } },
-          {
-            label: 'Read more on GitHub',
-            link: 'https://github.com/event-catalog/eventcatalog',
-            attrs: { target: '_blank', style: 'font-style: italic;' },
-          },
-        ]
+        autogenerated: { directory: "/flows" },
       },
       {
-        label: 'Operations & Support',
-        badge: {
-          text: 'New', color: 'green'
-        },
+        label: "Operations",
         collapsed: false,
-        items: [
-          { label: 'Runbooks', autogenerated: { directory: 'operations-and-support/runbooks', collapsed: false } },
-        ]
-      }
-    ]
+        autogenerated: { directory: "/operations" },
+      },
+    ],
+  },
+
+  search: {
+    type: "resource",
   },
+
   visualiser: {
     channels: {
-      renderMode: 'flat'
-    }
-  },
-  environments: [
-    {
-      name: 'Development',
-      url: 'https://demo.eventcatalog.dev',
-      description: 'Local development environment',
-      shortName: 'Dev'
-    },
-    {
-      name: 'Test',
-      url: 'https://demo.eventcatalog.dev',
-      description: 'Test environment for QA',
-      shortName: 'Test'
+      renderMode: "flat",
     },
-    {
-      name: 'Production',
-      url: 'https://demo.eventcatalog.dev',
-      description: 'Production environment',
-      shortName: 'Prod'
-    },
-  ]
+  },
+
+  llmsTxt: {
+    enabled: true,
+  },
 };
diff --git a/examples/default/eventcatalog.styles.css b/examples/default/eventcatalog.styles.css
index 0bbd3620e..e69de29bb 100644
--- a/examples/default/eventcatalog.styles.css
+++ b/examples/default/eventcatalog.styles.css
@@ -1,15 +0,0 @@
-
-/**
-
-Stylesheet overrides for EventCatalog. 
-There is currently a limit on what can be changed. 
-
-If you want to override some styles of particular elements, raise an issue for discussion. (https://github.com/event-catalog/eventcatalog)
-
-Note: Override based on custom selectors / hacks at your own risk. EventCatalog selectors will change over time, which may break your styles.
-      use the styles marked with `ec-` for non breaking styling changes.
-
-*/
-.ec-homepage{
-    background:black;
-}
\ No newline at end of file
diff --git a/examples/default/middleware.ts b/examples/default/middleware.ts
deleted file mode 100644
index 057a12da1..000000000
--- a/examples/default/middleware.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import type { MiddlewareHandler } from 'astro';
-interface Locals {
-  hasRole: (role: string) => boolean;
-  hasGroup: (group: string) => boolean;
-  findMatchingRule: (rules: Record<string, () => boolean>, pathname: string) => (() => boolean) | null;
-}
-
-export const rbacMiddleware: MiddlewareHandler = async (context, next) => {
-  const { locals, url } = context;
-  const pathname = url.pathname;
-
-  const { hasRole, hasGroup, findMatchingRule } = locals as Locals;
-
-  const accessRules = {
-    '/docs/domains/E-Commerce/*': () => !hasGroup('Viewer'),
-    '/visualiser/domains/E-Commerce/*': () => !hasGroup('Viewer'),
-  };
-
-  if (findMatchingRule) {
-    // Use the utility from locals - no import needed!
-    const rule = findMatchingRule(accessRules, pathname);
-
-    if (rule && !rule()) {
-      return new Response('Forbidden', { status: 403 });
-    }
-  }
-
-  return next();
-};
\ No newline at end of file
diff --git a/examples/default/package.json b/examples/default/package.json
index b32cb9372..3740abbb9 100644
--- a/examples/default/package.json
+++ b/examples/default/package.json
@@ -1,5 +1,9 @@
 {
     "name": "default-example-catalog",
     "version": "0.1.0",
-    "private": true
+    "private": true,
+    "dependencies": {
+        "@eventcatalog/connectors": "workspace:*",
+        "@eventcatalog/core": "workspace:*"
+    }
 }
diff --git a/examples/default/pages/homepage.astro b/examples/default/pages/homepage.astro
index fbf277f79..c29cc0bef 100644
--- a/examples/default/pages/homepage.astro
+++ b/examples/default/pages/homepage.astro
@@ -1,95 +1,109 @@
 ---
-const { Tile, Tiles, Flow, NodeGraph, Admonition, EntityMap } = Astro.props.components;
----
+import { getCollection } from 'astro:content';
 
-<div class="p-8 pt-2 max-w-8xl mx-auto">
-  <h1 class="text-4xl font-bold text-gray-800 mb-4">Welcome to FlowMart's EventCatalog</h1>
-  <p class="text-lg text-gray-600 mb-8">Explore the events, services, and domains that power the FlowMart ecosystem. This catalog provides a centralized place to discover and understand our asynchronous architecture.</p>
+// EventCatalog injects its components via Astro.props.components. Destructure the ones
+// this landing page uses (including the SystemContextMap embed).
+const { Tile, Tiles, SystemContextMap } = Astro.props.components;
 
-  <!-- This is a demo -->
-   <Admonition type="info" title="Demo application">
-    <p>This is a demo of the EventCatalog and what it can do. The company is called FlowMart and they are an e-commerce company.</p>
-    <p>Using EventCatalog, we documented their systems (domains, services, events, commands, flows) and how they fit together.</p>
-   </Admonition>
+// Count the catalog's top-level resources. We filter out versioned/ entries so each
+// resource is counted once (by its latest version).
+const isCurrent = (entry) => !entry.filePath?.includes('/versioned/');
 
-  <div class="grid grid-cols-2 gap-4 border-b border-gray-200 pb-8 pt-4">
-    <div class="col-span-1">
-      <h2 class="text-2xl font-semibold text-gray-700 mb-2">E-Commerce Domain</h2>
-      <p class="text-gray-500 mb-2">The core domain of FlowMart, responsible for all e-commerce operations.</p>
-      <NodeGraph id="E-Commerce" version="1.0.0" type="domain" />
-    </div>
-    <div class="col-span-1">
-      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Orders Domain</h2>
-      <p class="text-gray-500 mb-2">The sub-domain responsible for all orders.</p>
-      <NodeGraph id="Orders" version="0.0.3" type="domain" />
-    </div>
-    <div class="col-span-1">
-      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Payment Domain</h2>
-      <p class="text-gray-500 mb-2">The sub-domain responsible for all payments.</p>
-      <NodeGraph id="Payment" version="0.0.1" type="domain" />
-    </div>
-    <div class="col-span-1">
-      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Payment Entity Map</h2>
-      <p class="text-gray-500 mb-2">The entity map for the payment domain.</p>
-      <EntityMap id="Payment" version="0.0.1" title="Payment Entity Map" />
-    </div>
-    <div class="col-span-1">
-      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Subscription Domain</h2>
-      <p class="text-gray-500 mb-2">The sub-domain responsible for all subscriptions.</p>
-      <NodeGraph id="Subscriptions" version="0.0.1" type="domain" />
-    </div>
-    <div class="col-span-1">
-      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Subscription Entity Map</h2>
-      <p class="text-gray-500 mb-2">The entity map for the subscription domain.</p>
-      <EntityMap id="Subscriptions" version="0.0.1" title="Subscription Entity Map" />
-    </div>
-  </div>
+const [domains, systems, services] = await Promise.all([
+  getCollection('domains'),
+  getCollection('systems'),
+  getCollection('services'),
+]);
 
-  <div class="bg-blue-50 p-6 rounded-lg shadow-md mb-12">
-    <h2 class="text-2xl font-semibold text-blue-800 mb-3">Discover Our Architecture</h2>
-    <p class="text-gray-700 mb-4">
-      Navigate through our Domains to understand the different business capabilities, explore Services to see the microservices involved, and dive into Events and Commands to see how they communicate.
-    </p>
-    <p class="text-gray-700">
-      Use the search bar above or browse the sections in the sidebar to get started.
+const stats = [
+  { label: 'Domains', value: domains.filter(isCurrent).length, href: '/discover/domains' },
+  { label: 'Systems', value: systems.filter(isCurrent).length, href: '/visualiser/system-context-map' },
+  { label: 'Services', value: services.filter(isCurrent).length, href: '/discover/services' },
+];
+---
+
+<div class="not-prose">
+  {/* Hero */}
+  <div class="pb-8 border-b border-[rgb(var(--ec-page-border))]">
+    <h1 class="text-4xl md:text-5xl font-bold text-[rgb(var(--ec-page-text))]">Acme Inc Catalog</h1>
+    <p class="mt-3 text-lg text-[rgb(var(--ec-page-text-muted))] max-w-3xl font-light">
+      Discover, explore and document the event-driven architecture that powers Acme Inc — our
+      domains, the systems inside them, and the services and messages that connect everything.
     </p>
   </div>
 
-  <div class="grid grid-cols-2 gap-4 border-b border-gray-200 pb-8">
-    <div class="col-span-1">
-      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Cancel Subscription Flow</h2>
-      <p class="text-gray-500 mb-2">This flow is triggered when a user cancels their subscription.</p>
-      <Flow id="CancelSubscription" version="latest" includeKey={false} />
-    </div>
-    <div class="col-span-1">
-      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Payment Flow</h2>
-      <p class="text-gray-500 mb-2">This flow documents how a payment is processed at FlowMart.</p>
-      <Flow id="PaymentFlow" version="latest" includeKey={false} />
-    </div>
+  {/* Stat cards */}
+  <div class="grid grid-cols-1 sm:grid-cols-3 gap-4 mt-8">
+    {
+      stats.map((stat) => (
+        <a
+          href={stat.href}
+          class="group rounded-xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] p-6 shadow-xs hover:shadow-md hover:border-[rgb(var(--ec-accent)/0.5)] transition-all"
+        >
+          <div class="text-4xl font-bold text-[rgb(var(--ec-page-text))]">{stat.value}</div>
+          <div class="mt-1 text-sm font-medium uppercase tracking-wide text-[rgb(var(--ec-page-text-muted))]">
+            {stat.label}
+          </div>
+        </a>
+      ))
+    }
   </div>
 
-  <div class="border-b border-gray-200 pb-8 py-4">
-  <h2 class="text-3xl font-semibold text-gray-700 py-4">Quick Links</h2>
-  <p class="text-gray-700 mb-4">Learn how to get started with EventCatalog, create domains, services, events, and commands.</p>
-  <Tiles columns={3}>
-    <Tile icon="BookOpenIcon" href="https://eventcatalog.dev/docs/development/getting-started/introduction" title="Getting started with EventCatalog" description="How to get started with EventCatalog" />
-    <Tile icon="RectangleGroupIcon" href="https://eventcatalog.dev/docs/development/guides/domains/adding-domains" title="Creating domains" description="Learn how to create domains in your event catalog" />
-    <Tile icon="ServerIcon" href="https://eventcatalog.dev/docs/development/guides/services/adding-services" title="Creating services" description="Learn how to create services in your event catalog" />
-    <Tile icon="ChatBubbleLeftIcon" iconColor="text-blue-500" href="https://eventcatalog.dev/docs/development/guides/messages/commands/introduction" title="Creating commands" description="Learn how to create commands in your event catalog" />
-    <Tile icon="BoltIcon" iconColor="text-orange-500" href="https://eventcatalog.dev/docs/development/guides/messages/events/introduction" title="Creating events" description="Learn how to create events in your event catalog" />
-    <Tile icon="UserGroupIcon" iconColor="text-green-500" href="https://eventcatalog.dev/docs/owners" title="Assigning owners to resources" description="Learn how to assign owners to resources in your event catalog" />
-  </Tiles>
+  {/* System context map */}
+  <h2 class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-12 mb-2">System context map</h2>
+  <p class="text-[rgb(var(--ec-page-text-muted))] font-light mb-2">
+    How every system in the catalog relates — and the people who interact with them.
+  </p>
 </div>
 
-  <div class="pb-8 py-4">
-    <h2 class="text-3xl font-semibold text-gray-700 mb-6 pt-4">Join the community</h2>
-
-    <p class="text-gray-700 mb-4">Our project and community is growing fast. We have over 1000+ members in our <a href="https://discord.gg/3rjaZMmrAm" class="text-blue-500 hover:text-blue-600">Discord community</a>.</p>
-
-    <Tiles columns={2}>
-      <Tile icon="UserGroupIcon" iconColor="text-green-500" href="https://discord.gg/3rjaZMmrAm" title="Join the Discord community" description="Join the community to get help and support" />
-      <Tile icon="StarIcon"  iconColor="text-yellow-500" href="https://github.com/event-catalog/eventcatalog/stargazers" title="Star EventCatalog on GitHub" description="If you like the project, please star it on GitHub to show your support ❤️" />
-    </Tiles>
-  </div>
+<SystemContextMap />
 
+<div class="not-prose">
+  {/* Domains */}
+  <h2 class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-12 mb-4">Explore the domains</h2>
 </div>
+
+<Tiles columns={3}>
+  <Tile
+    icon="RectangleGroupIcon"
+    href="/docs/domains/catalog/1.0.0"
+    title="Catalog"
+    description="Source of truth for product data and the search that makes it discoverable."
+  />
+  <Tile
+    icon="UserGroupIcon"
+    href="/docs/domains/customer/1.0.0"
+    title="Customer"
+    description="Customer profiles and authentication across Acme Inc."
+  />
+  <Tile
+    icon="ShoppingCartIcon"
+    href="/docs/domains/shopping/1.0.0"
+    title="Shopping"
+    description="The shopping cart and the promotions applied to it at checkout."
+  />
+  <Tile
+    icon="ClipboardDocumentListIcon"
+    href="/docs/domains/ordering/1.0.0"
+    title="Ordering"
+    description="Turning a checked-out cart into a confirmed order, from checkout to fulfilment."
+  />
+  <Tile
+    icon="CreditCardIcon"
+    href="/docs/domains/payments/1.0.0"
+    title="Payments"
+    description="Taking payment and processing refunds, with external payment and fraud providers."
+  />
+  <Tile
+    icon="TruckIcon"
+    href="/docs/domains/fulfilment/1.0.0"
+    title="Fulfilment"
+    description="Reserving stock, picking and packing orders, and shipping them to customers."
+  />
+  <Tile
+    icon="StarIcon"
+    href="/docs/domains/reviews/1.0.0"
+    title="Reviews & Ratings"
+    description="Collecting, moderating and publishing customer reviews, and aggregating them into product ratings."
+  />
+</Tiles>
diff --git a/examples/default/public/icons/analytics/clickhouse.svg b/examples/default/public/icons/analytics/clickhouse.svg
new file mode 100644
index 000000000..95c0bef80
--- /dev/null
+++ b/examples/default/public/icons/analytics/clickhouse.svg
@@ -0,0 +1 @@
+<svg fill="#FFCC01" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>ClickHouse</title><path d="M21.333 10H24v4h-2.667ZM16 1.335h2.667v21.33H16Zm-5.333 0h2.666v21.33h-2.666ZM0 22.665V1.335h2.667v21.33zm5.333-21.33H8v21.33H5.333Z"/></svg>
\ No newline at end of file
diff --git a/examples/default/public/icons/cache/redis.svg b/examples/default/public/icons/cache/redis.svg
new file mode 100644
index 000000000..61480c931
--- /dev/null
+++ b/examples/default/public/icons/cache/redis.svg
@@ -0,0 +1 @@
+<svg fill="#FF4438" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Redis</title><path d="M22.71 13.145c-1.66 2.092-3.452 4.483-7.038 4.483-3.203 0-4.397-2.825-4.48-5.12.701 1.484 2.073 2.685 4.214 2.63 4.117-.133 6.94-3.852 6.94-7.239 0-4.05-3.022-6.972-8.268-6.972-3.752 0-8.4 1.428-11.455 3.685C2.59 6.937 3.885 9.958 4.35 9.626c2.648-1.904 4.748-3.13 6.784-3.744C8.12 9.244.886 17.05 0 18.425c.1 1.261 1.66 4.648 2.424 4.648.232 0 .431-.133.664-.365a100.49 100.49 0 0 0 5.54-6.765c.222 3.104 1.748 6.898 6.014 6.898 3.819 0 7.604-2.756 9.33-8.965.2-.764-.73-1.361-1.261-.73zm-4.349-5.013c0 1.959-1.926 2.922-3.685 2.922-.941 0-1.664-.247-2.235-.568 1.051-1.592 2.092-3.225 3.21-4.973 1.972.334 2.71 1.43 2.71 2.619z"/></svg>
\ No newline at end of file
diff --git a/examples/default/public/icons/database/postgresql.svg b/examples/default/public/icons/database/postgresql.svg
new file mode 100644
index 000000000..931bdae18
--- /dev/null
+++ b/examples/default/public/icons/database/postgresql.svg
@@ -0,0 +1 @@
+<svg fill="#4169E1" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>PostgreSQL</title><path d="M23.5594 14.7228a.5269.5269 0 0 0-.0563-.1191c-.139-.2632-.4768-.3418-1.0074-.2321-1.6533.3411-2.2935.1312-2.5256-.0191 1.342-2.0482 2.445-4.522 3.0411-6.8297.2714-1.0507.7982-3.5237.1222-4.7316a1.5641 1.5641 0 0 0-.1509-.235C21.6931.9086 19.8007.0248 17.5099.0005c-1.4947-.0158-2.7705.3461-3.1161.4794a9.449 9.449 0 0 0-.5159-.0816 8.044 8.044 0 0 0-1.3114-.1278c-1.1822-.0184-2.2038.2642-3.0498.8406-.8573-.3211-4.7888-1.645-7.2219.0788C.9359 2.1526.3086 3.8733.4302 6.3043c.0409.818.5069 3.334 1.2423 5.7436.4598 1.5065.9387 2.7019 1.4334 3.582.553.9942 1.1259 1.5933 1.7143 1.7895.4474.1491 1.1327.1441 1.8581-.7279.8012-.9635 1.5903-1.8258 1.9446-2.2069.4351.2355.9064.3625 1.39.3772a.0569.0569 0 0 0 .0004.0041 11.0312 11.0312 0 0 0-.2472.3054c-.3389.4302-.4094.5197-1.5002.7443-.3102.064-1.1344.2339-1.1464.8115-.0025.1224.0329.2309.0919.3268.2269.4231.9216.6097 1.015.6331 1.3345.3335 2.5044.092 3.3714-.6787-.017 2.231.0775 4.4174.3454 5.0874.2212.5529.7618 1.9045 2.4692 1.9043.2505 0 .5263-.0291.8296-.0941 1.7819-.3821 2.5557-1.1696 2.855-2.9059.1503-.8707.4016-2.8753.5388-4.1012.0169-.0703.0357-.1207.057-.1362.0007-.0005.0697-.0471.4272.0307a.3673.3673 0 0 0 .0443.0068l.2539.0223.0149.001c.8468.0384 1.9114-.1426 2.5312-.4308.6438-.2988 1.8057-1.0323 1.5951-1.6698zM2.371 11.8765c-.7435-2.4358-1.1779-4.8851-1.2123-5.5719-.1086-2.1714.4171-3.6829 1.5623-4.4927 1.8367-1.2986 4.8398-.5408 6.108-.13-.0032.0032-.0066.0061-.0098.0094-2.0238 2.044-1.9758 5.536-1.9708 5.7495-.0002.0823.0066.1989.0162.3593.0348.5873.0996 1.6804-.0735 2.9184-.1609 1.1504.1937 2.2764.9728 3.0892.0806.0841.1648.1631.2518.2374-.3468.3714-1.1004 1.1926-1.9025 2.1576-.5677.6825-.9597.5517-1.0886.5087-.3919-.1307-.813-.5871-1.2381-1.3223-.4796-.839-.9635-2.0317-1.4155-3.5126zm6.0072 5.0871c-.1711-.0428-.3271-.1132-.4322-.1772.0889-.0394.2374-.0902.4833-.1409 1.2833-.2641 1.4815-.4506 1.9143-1.0002.0992-.126.2116-.2687.3673-.4426a.3549.3549 0 0 0 .0737-.1298c.1708-.1513.2724-.1099.4369-.0417.156.0646.3078.26.3695.4752.0291.1016.0619.2945-.0452.4444-.9043 1.2658-2.2216 1.2494-3.1676 1.0128zm2.094-3.988-.0525.141c-.133.3566-.2567.6881-.3334 1.003-.6674-.0021-1.3168-.2872-1.8105-.8024-.6279-.6551-.9131-1.5664-.7825-2.5004.1828-1.3079.1153-2.4468.079-3.0586-.005-.0857-.0095-.1607-.0122-.2199.2957-.2621 1.6659-.9962 2.6429-.7724.4459.1022.7176.4057.8305.928.5846 2.7038.0774 3.8307-.3302 4.7363-.084.1866-.1633.3629-.2311.5454zm7.3637 4.5725c-.0169.1768-.0358.376-.0618.5959l-.146.4383a.3547.3547 0 0 0-.0182.1077c-.0059.4747-.054.6489-.115.8693-.0634.2292-.1353.4891-.1794 1.0575-.11 1.4143-.8782 2.2267-2.4172 2.5565-1.5155.3251-1.7843-.4968-2.0212-1.2217a6.5824 6.5824 0 0 0-.0769-.2266c-.2154-.5858-.1911-1.4119-.1574-2.5551.0165-.5612-.0249-1.9013-.3302-2.6462.0044-.2932.0106-.5909.019-.8918a.3529.3529 0 0 0-.0153-.1126 1.4927 1.4927 0 0 0-.0439-.208c-.1226-.4283-.4213-.7866-.7797-.9351-.1424-.059-.4038-.1672-.7178-.0869.067-.276.1831-.5875.309-.9249l.0529-.142c.0595-.16.134-.3257.213-.5012.4265-.9476 1.0106-2.2453.3766-5.1772-.2374-1.0981-1.0304-1.6343-2.2324-1.5098-.7207.0746-1.3799.3654-1.7088.5321a5.6716 5.6716 0 0 0-.1958.1041c.0918-1.1064.4386-3.1741 1.7357-4.4823a4.0306 4.0306 0 0 1 .3033-.276.3532.3532 0 0 0 .1447-.0644c.7524-.5706 1.6945-.8506 2.802-.8325.4091.0067.8017.0339 1.1742.081 1.939.3544 3.2439 1.4468 4.0359 2.3827.8143.9623 1.2552 1.9315 1.4312 2.4543-1.3232-.1346-2.2234.1268-2.6797.779-.9926 1.4189.543 4.1729 1.2811 5.4964.1353.2426.2522.4522.2889.5413.2403.5825.5515.9713.7787 1.2552.0696.087.1372.1714.1885.245-.4008.1155-1.1208.3825-1.0552 1.717-.0123.1563-.0423.4469-.0834.8148-.0461.2077-.0702.4603-.0994.7662zm.8905-1.6211c-.0405-.8316.2691-.9185.5967-1.0105a2.8566 2.8566 0 0 0 .135-.0406 1.202 1.202 0 0 0 .1342.103c.5703.3765 1.5823.4213 3.0068.1344-.2016.1769-.5189.3994-.9533.6011-.4098.1903-1.0957.333-1.7473.3636-.7197.0336-1.0859-.0807-1.1721-.151zm.5695-9.2712c-.0059.3508-.0542.6692-.1054 1.0017-.055.3576-.112.7274-.1264 1.1762-.0142.4368.0404.8909.0932 1.3301.1066.887.216 1.8003-.2075 2.7014a3.5272 3.5272 0 0 1-.1876-.3856c-.0527-.1276-.1669-.3326-.3251-.6162-.6156-1.1041-2.0574-3.6896-1.3193-4.7446.3795-.5427 1.3408-.5661 2.1781-.463zm.2284 7.0137a12.3762 12.3762 0 0 0-.0853-.1074l-.0355-.0444c.7262-1.1995.5842-2.3862.4578-3.4385-.0519-.4318-.1009-.8396-.0885-1.2226.0129-.4061.0666-.7543.1185-1.0911.0639-.415.1288-.8443.1109-1.3505.0134-.0531.0188-.1158.0118-.1902-.0457-.4855-.5999-1.938-1.7294-3.253-.6076-.7073-1.4896-1.4972-2.6889-2.0395.5251-.1066 1.2328-.2035 2.0244-.1859 2.0515.0456 3.6746.8135 4.8242 2.2824a.908.908 0 0 1 .0667.1002c.7231 1.3556-.2762 6.2751-2.9867 10.5405zm-8.8166-6.1162c-.025.1794-.3089.4225-.6211.4225a.5821.5821 0 0 1-.0809-.0056c-.1873-.026-.3765-.144-.5059-.3156-.0458-.0605-.1203-.178-.1055-.2844.0055-.0401.0261-.0985.0925-.1488.1182-.0894.3518-.1226.6096-.0867.3163.0441.6426.1938.6113.4186zm7.9305-.4114c.0111.0792-.049.201-.1531.3102-.0683.0717-.212.1961-.4079.2232a.5456.5456 0 0 1-.075.0052c-.2935 0-.5414-.2344-.5607-.3717-.024-.1765.2641-.3106.5611-.352.297-.0414.6111.0088.6356.1851z"/></svg>
\ No newline at end of file
diff --git a/examples/default/public/icons/languages/go.svg b/examples/default/public/icons/languages/go.svg
new file mode 100644
index 000000000..51990bd01
--- /dev/null
+++ b/examples/default/public/icons/languages/go.svg
@@ -0,0 +1 @@
+<svg fill="#00ADD8" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Go</title><path d="M1.811 10.231c-.047 0-.058-.023-.035-.059l.246-.315c.023-.035.081-.058.128-.058h4.172c.046 0 .058.035.035.07l-.199.303c-.023.036-.082.07-.117.07zM.047 11.306c-.047 0-.059-.023-.035-.058l.245-.316c.023-.035.082-.058.129-.058h5.328c.047 0 .07.035.058.07l-.093.28c-.012.047-.058.07-.105.07zm2.828 1.075c-.047 0-.059-.035-.035-.07l.163-.292c.023-.035.07-.07.117-.07h2.337c.047 0 .07.035.07.082l-.023.28c0 .047-.047.082-.082.082zm12.129-2.36c-.736.187-1.239.327-1.963.514-.176.046-.187.058-.34-.117-.174-.199-.303-.327-.548-.444-.737-.362-1.45-.257-2.115.175-.795.514-1.204 1.274-1.192 2.22.011.935.654 1.706 1.577 1.835.795.105 1.46-.175 1.987-.77.105-.13.198-.27.315-.434H10.47c-.245 0-.304-.152-.222-.35.152-.362.432-.97.596-1.274a.315.315 0 01.292-.187h4.253c-.023.316-.023.631-.07.947a4.983 4.983 0 01-.958 2.29c-.841 1.11-1.94 1.8-3.33 1.986-1.145.152-2.209-.07-3.143-.77-.865-.655-1.356-1.52-1.484-2.595-.152-1.274.222-2.419.993-3.424.83-1.086 1.928-1.776 3.272-2.02 1.098-.2 2.15-.07 3.096.571.62.41 1.063.97 1.356 1.648.07.105.023.164-.117.2m3.868 6.461c-1.064-.024-2.034-.328-2.852-1.029a3.665 3.665 0 01-1.262-2.255c-.21-1.32.152-2.489.947-3.529.853-1.122 1.881-1.706 3.272-1.95 1.192-.21 2.314-.095 3.33.595.923.63 1.496 1.484 1.648 2.605.198 1.578-.257 2.863-1.344 3.962-.771.783-1.718 1.273-2.805 1.495-.315.06-.63.07-.934.106zm2.78-4.72c-.011-.153-.011-.27-.034-.387-.21-1.157-1.274-1.81-2.384-1.554-1.087.245-1.788.935-2.045 2.033-.21.912.234 1.835 1.075 2.21.643.28 1.285.244 1.905-.07.923-.48 1.425-1.228 1.484-2.233z"/></svg>
\ No newline at end of file
diff --git a/examples/default/public/icons/languages/java.svg b/examples/default/public/icons/languages/java.svg
new file mode 100644
index 000000000..c72c27432
--- /dev/null
+++ b/examples/default/public/icons/languages/java.svg
@@ -0,0 +1 @@
+<svg fill="#ED8B00" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Java</title><path d="M8.851 18.56s-.917.534.653.714c1.902.218 2.874.187 4.969-.211 0 0 .552.346 1.321.646-4.699 2.013-10.633-.118-6.943-1.149M8.276 15.933s-1.028.761.542.924c2.032.209 3.636.227 6.413-.308 0 0 .384.389.987.602-5.679 1.661-12.007.13-7.942-1.218M13.116 11.475c1.158 1.333-.304 2.533-.304 2.533s2.939-1.518 1.589-3.418c-1.261-1.772-2.228-2.652 3.007-5.688 0-.001-8.216 2.051-4.292 6.573M19.33 20.504s.679.559-.747.991c-2.712.822-11.288 1.069-13.669.033-.856-.373.75-.89 1.254-.998.527-.114.828-.093.828-.093-.953-.671-6.156 1.317-2.643 1.887 9.58 1.553 17.462-.7 14.977-1.82M9.292 13.21s-4.362 1.036-1.544 1.412c1.189.159 3.561.123 5.77-.062 1.806-.152 3.618-.477 3.618-.477s-.637.272-1.098.587c-4.429 1.165-12.986.623-10.522-.568 2.082-1.006 3.776-.892 3.776-.892M17.116 17.584c4.503-2.34 2.421-4.589.968-4.285-.355.074-.515.138-.515.138s.132-.207.385-.297c2.875-1.011 5.086 2.981-.928 4.562 0-.001.07-.062.09-.118M13.408 0s2.494 2.494-2.365 6.33c-3.896 3.077-.888 4.832-.001 6.836-2.274-2.053-3.943-3.858-2.824-5.539 1.644-2.469 6.197-3.665 5.19-7.627M9.734 23.924c4.322.277 10.959-.153 11.116-2.198 0 0-.302.775-3.572 1.391-3.688.694-8.239.613-10.937.168 0-.001.553.457 3.393.639"/></svg>
diff --git a/examples/default/public/icons/languages/nodejs.svg b/examples/default/public/icons/languages/nodejs.svg
new file mode 100644
index 000000000..3cc5893e0
--- /dev/null
+++ b/examples/default/public/icons/languages/nodejs.svg
@@ -0,0 +1 @@
+<svg fill="#5FA04E" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Node.js</title><path d="M11.998,24c-0.321,0-0.641-0.084-0.922-0.247l-2.936-1.737c-0.438-0.245-0.224-0.332-0.08-0.383 c0.585-0.203,0.703-0.25,1.328-0.604c0.065-0.037,0.151-0.023,0.218,0.017l2.256,1.339c0.082,0.045,0.197,0.045,0.272,0l8.795-5.076 c0.082-0.047,0.134-0.141,0.134-0.238V6.921c0-0.099-0.053-0.192-0.137-0.242l-8.791-5.072c-0.081-0.047-0.189-0.047-0.271,0 L3.075,6.68C2.99,6.729,2.936,6.825,2.936,6.921v10.15c0,0.097,0.054,0.189,0.139,0.235l2.409,1.392 c1.307,0.654,2.108-0.116,2.108-0.89V7.787c0-0.142,0.114-0.253,0.256-0.253h1.115c0.139,0,0.255,0.112,0.255,0.253v10.021 c0,1.745-0.95,2.745-2.604,2.745c-0.508,0-0.909,0-2.026-0.551L2.28,18.675c-0.57-0.329-0.922-0.945-0.922-1.604V6.921 c0-0.659,0.353-1.275,0.922-1.603l8.795-5.082c0.557-0.315,1.296-0.315,1.848,0l8.794,5.082c0.57,0.329,0.924,0.944,0.924,1.603 v10.15c0,0.659-0.354,1.273-0.924,1.604l-8.794,5.078C12.643,23.916,12.324,24,11.998,24z M19.099,13.993 c0-1.9-1.284-2.406-3.987-2.763c-2.731-0.361-3.009-0.548-3.009-1.187c0-0.528,0.235-1.233,2.258-1.233 c1.807,0,2.473,0.389,2.747,1.607c0.024,0.115,0.129,0.199,0.247,0.199h1.141c0.071,0,0.138-0.031,0.186-0.081 c0.048-0.054,0.074-0.123,0.067-0.196c-0.177-2.098-1.571-3.076-4.388-3.076c-2.508,0-4.004,1.058-4.004,2.833 c0,1.925,1.488,2.457,3.895,2.695c2.88,0.282,3.103,0.703,3.103,1.269c0,0.983-0.789,1.402-2.642,1.402 c-2.327,0-2.839-0.584-3.011-1.742c-0.02-0.124-0.126-0.215-0.253-0.215h-1.137c-0.141,0-0.254,0.112-0.254,0.253 c0,1.482,0.806,3.248,4.655,3.248C17.501,17.007,19.099,15.91,19.099,13.993z"/></svg>
\ No newline at end of file
diff --git a/examples/default/public/icons/payments/stripe.svg b/examples/default/public/icons/payments/stripe.svg
new file mode 100644
index 000000000..77e678c71
--- /dev/null
+++ b/examples/default/public/icons/payments/stripe.svg
@@ -0,0 +1 @@
+<svg fill="#635BFF" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Stripe</title><path d="M13.976 9.15c-2.172-.806-3.356-1.426-3.356-2.409 0-.831.683-1.305 1.901-1.305 2.227 0 4.515.858 6.090 1.631l.890-5.494C18.252.975 15.687 0 12.585 0 10.469 0 8.703.555 7.439 1.583 6.123 2.658 5.444 4.208 5.444 6.078c0 3.39 2.072 4.839 5.446 6.057 2.172.78 2.901 1.331 2.901 2.179 0 .825-.707 1.306-1.978 1.306-1.575 0-4.18-.78-5.886-1.768L5.04 19.601c1.46.831 4.157 1.673 6.952 1.673 2.235 0 4.098-.527 5.355-1.523 1.406-1.085 2.135-2.682 2.135-4.764 0-3.471-2.118-4.926-5.507-6.117v.28z"/></svg>
diff --git a/examples/default/public/logo.png b/examples/default/public/logo.png
index d65c29da2..670057fbb 100644
Binary files a/examples/default/public/logo.png and b/examples/default/public/logo.png differ
diff --git a/examples/default/public/logo.svg b/examples/default/public/logo.svg
deleted file mode 100644
index a3b326372..000000000
--- a/examples/default/public/logo.svg
+++ /dev/null
@@ -1,14 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 300 200">
-  <!-- Background shape -->
-  <rect x="50" y="50" width="200" height="100" rx="20" fill="#4a86e8" />
-  
-  <!-- Flow waves -->
-  <path d="M80 90 Q100 70, 120 90 Q140 110, 160 90 Q180 70, 200 90 Q220 110, 240 90" 
-        fill="none" stroke="#ffffff" stroke-width="8" stroke-linecap="round" />
-  
-  <!-- Shopping cart icon -->
-  <circle cx="220" cy="110" r="10" fill="#ffffff" />
-  <circle cx="180" cy="110" r="10" fill="#ffffff" />
-  <path d="M160 80 L170 110 L230 110 L240 80 Z" fill="none" stroke="#ffffff" stroke-width="3" />
-  <path d="M170 80 L245 80" fill="none" stroke="#ffffff" stroke-width="3" />
-</svg>
\ No newline at end of file
diff --git a/examples/default/reports/eventcatalog-assessment.pdf b/examples/default/reports/eventcatalog-assessment.pdf
deleted file mode 100644
index 5d81752d6..000000000
Binary files a/examples/default/reports/eventcatalog-assessment.pdf and /dev/null differ
diff --git a/examples/default/reports/eventcatalog-full-report.pdf b/examples/default/reports/eventcatalog-full-report.pdf
deleted file mode 100644
index 87927f0e2..000000000
Binary files a/examples/default/reports/eventcatalog-full-report.pdf and /dev/null differ
diff --git a/examples/default/teams/customer-platform.mdx b/examples/default/teams/customer-platform.mdx
new file mode 100644
index 000000000..d7902b036
--- /dev/null
+++ b/examples/default/teams/customer-platform.mdx
@@ -0,0 +1,18 @@
+---
+id: customer-platform
+name: Customer Platform
+summary: Owns the Customer domain — customer profiles and authentication across Acme Inc.
+members:
+  - dboyne
+email: customer-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/customer-platform
+---
+
+## Overview
+
+The **Customer Platform** team owns the [[domain|customer]] domain. They are responsible for how customers register, how their profiles are maintained, and how they authenticate.
+
+## Responsibilities
+
+- **Customer Management System** — registering, updating and reading customer profiles, and publishing customer change events.
+- **Identity Provider** — authenticating customers and owning credentials in the user directory.
diff --git a/examples/default/teams/fulfilment-platform.mdx b/examples/default/teams/fulfilment-platform.mdx
new file mode 100644
index 000000000..d13738aac
--- /dev/null
+++ b/examples/default/teams/fulfilment-platform.mdx
@@ -0,0 +1,20 @@
+---
+id: fulfilment-platform
+name: Fulfilment Platform
+summary: Owns the Fulfilment domain — reserving stock, picking and packing orders, and shipping them to customers.
+members:
+  - dboyne
+email: fulfilment-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/fulfilment-platform
+---
+
+## Overview
+
+The **Fulfilment Platform** team owns the [[domain|fulfilment]] domain. They are responsible for inventory, warehousing and shipping — everything that gets a confirmed order physically to the customer.
+
+## Responsibilities
+
+- **Inventory System** — tracking and reserving stock.
+- **Warehouse System** — picking and packing orders.
+- **Shipping System** — handing packed orders to carriers.
+- Integration with external **Carriers** for delivery.
diff --git a/examples/default/teams/order-management.mdx b/examples/default/teams/order-management.mdx
deleted file mode 100644
index 80700dbbb..000000000
--- a/examples/default/teams/order-management.mdx
+++ /dev/null
@@ -1,24 +0,0 @@
----
-id: order-management
-name: The order management team
-members:
-    - asmith
-    - mchen
-    - nshah
-    - slee
-    - spatel
----
-
-The order management team is responsible for overseeing and optimizing the entire order lifecycle within our organization. Their key responsibilities include:
-
-- Processing and validating incoming customer orders
-- Managing order fulfillment workflows and inventory allocation
-- Coordinating with warehouse and shipping teams
-- Handling order modifications and cancellations
-- Resolving order-related customer issues and disputes
-- Monitoring order processing metrics and KPIs
-- Implementing and maintaining order management systems
-- Developing strategies to improve order accuracy and efficiency
-
-The team works closely with sales, customer service, and logistics departments to ensure smooth order processing and customer satisfaction.
-
diff --git a/examples/default/teams/ordering-platform.mdx b/examples/default/teams/ordering-platform.mdx
new file mode 100644
index 000000000..ee58d62ab
--- /dev/null
+++ b/examples/default/teams/ordering-platform.mdx
@@ -0,0 +1,18 @@
+---
+id: ordering-platform
+name: Ordering Platform
+summary: Owns the Ordering domain — turning a checked-out cart into a confirmed order.
+members:
+  - dboyne
+email: ordering-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/ordering-platform
+---
+
+## Overview
+
+The **Ordering Platform** team owns the [[domain|ordering]] domain. They are responsible for the checkout flow that turns a checked-out cart into a confirmed order, and for the lifecycle of orders once they exist.
+
+## Responsibilities
+
+- **Checkout System** — orchestrating checkout: reserving inventory, authorizing payment and creating the order.
+- **Order Management System** — the system of record for orders and their lifecycle.
diff --git a/examples/default/teams/payments-platform.mdx b/examples/default/teams/payments-platform.mdx
new file mode 100644
index 000000000..3a9d135d1
--- /dev/null
+++ b/examples/default/teams/payments-platform.mdx
@@ -0,0 +1,18 @@
+---
+id: payments-platform
+name: Payments Platform
+summary: Owns the Payments domain — authorizing payments, processing refunds, and integrating with external payment and fraud providers.
+members:
+  - dboyne
+email: payments-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/payments-platform
+---
+
+## Overview
+
+The **Payments Platform** team owns the [[domain|payments]] domain. They are responsible for taking payment for orders, processing refunds, and integrating with the external payment processor and fraud provider.
+
+## Responsibilities
+
+- **Payment Processing System** — orchestrating authorization, capture and refunds.
+- Integrations with **Stripe** (payment processing) and **Fraud Detection** (fraud screening).
diff --git a/examples/default/teams/product-platform.mdx b/examples/default/teams/product-platform.mdx
new file mode 100644
index 000000000..43846b74d
--- /dev/null
+++ b/examples/default/teams/product-platform.mdx
@@ -0,0 +1,20 @@
+---
+id: product-platform
+name: Product Platform
+summary: Owns the Product Catalog System — the source of truth for product data at Acme Inc.
+members:
+  - dboyne
+email: product-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/product-platform
+---
+
+## Overview
+
+The **Product Platform** team owns the [[system|product-catalog-system]]. They are responsible for how products are created, maintained and stored, and for reliably publishing product change events to the rest of the business.
+
+## Responsibilities
+
+- **Product API** — the public-facing API for creating, updating, deleting and reading products.
+- **Product Worker** — asynchronous catalog processing (enrichment, media, bulk imports).
+- **Product Search Publisher** — reliable, ordered delivery of product change events.
+- **Product Database** — the PostgreSQL system of record for all product data.
diff --git a/examples/default/teams/reviews-platform.mdx b/examples/default/teams/reviews-platform.mdx
new file mode 100644
index 000000000..19a5bb07d
--- /dev/null
+++ b/examples/default/teams/reviews-platform.mdx
@@ -0,0 +1,20 @@
+---
+id: reviews-platform
+name: Reviews Platform
+summary: Owns the Reviews & Ratings domain — how customers review products and how those reviews are moderated, published and aggregated into ratings.
+members:
+  - dboyne
+email: reviews-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/reviews-platform
+---
+
+## Overview
+
+The **Reviews Platform** team owns the [[domain|reviews]] domain. They are responsible for collecting customer reviews, moderating them, publishing the approved ones, and turning ratings into the aggregate scores shown across the storefront.
+
+## Responsibilities
+
+- **Review API** — accepts review submissions and serves product reviews.
+- **Review Moderation Worker** — screens submitted reviews and decides whether to publish or reject them.
+- **Rating Aggregator** — keeps each product's aggregate rating up to date as reviews are published.
+- **Review Database** — the system of record for reviews and their moderation state.
diff --git a/examples/default/teams/search-platform.mdx b/examples/default/teams/search-platform.mdx
new file mode 100644
index 000000000..9b10a2bfb
--- /dev/null
+++ b/examples/default/teams/search-platform.mdx
@@ -0,0 +1,19 @@
+---
+id: search-platform
+name: Search Platform
+summary: Owns the Search System — keeps the catalog discoverable through fast, relevant product search.
+members:
+  - dboyne
+email: search-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/search-platform
+---
+
+## Overview
+
+The **Search Platform** team owns the [[system|search-system]]. They consume product change events, keep the search index in sync, and serve product search to the rest of Acme Inc.
+
+## Responsibilities
+
+- **Search API** — the public-facing API that serves product search queries.
+- **Search Indexer** — consumes product change events and keeps the index current.
+- **Search Index** — the search-optimised, rebuildable read model of the catalog.
diff --git a/examples/default/teams/shopping-platform.mdx b/examples/default/teams/shopping-platform.mdx
new file mode 100644
index 000000000..bd972fa05
--- /dev/null
+++ b/examples/default/teams/shopping-platform.mdx
@@ -0,0 +1,18 @@
+---
+id: shopping-platform
+name: Shopping Platform
+summary: Owns the Shopping domain — the cart and the promotions applied to it.
+members:
+  - dboyne
+email: shopping-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/shopping-platform
+---
+
+## Overview
+
+The **Shopping Platform** team owns the [[domain|shopping]] domain. They are responsible for the shopping cart, the checkout flow, and the promotions and discounts applied to a cart.
+
+## Responsibilities
+
+- **Cart System** — building, pricing and checking out shopping carts.
+- **Promotion System** — evaluating promotion rules and calculating discounts.
diff --git a/examples/default/tsconfig.json b/examples/default/tsconfig.json
new file mode 100644
index 000000000..1da4b3189
--- /dev/null
+++ b/examples/default/tsconfig.json
@@ -0,0 +1,26 @@
+{
+  // Editor support (IntelliSense, go-to-definition) for custom pages.
+  // These aliases mirror the ones the EventCatalog build provides at runtime.
+  // In a real catalog the paths point into .eventcatalog-core instead.
+  "compilerOptions": {
+    "baseUrl": ".",
+    "allowJs": true,
+    "jsx": "preserve",
+    "paths": {
+      "@catalog/components/*": ["components/*"],
+      "@catalog/layouts/*": ["../../packages/core/eventcatalog/src/toolkit/layouts/*"],
+      "@catalog/utils": ["../../packages/core/eventcatalog/src/toolkit/utils/index.ts"],
+      "@catalog/utils/*": ["../../packages/core/eventcatalog/src/toolkit/utils/*"],
+      "@components/*": ["../../packages/core/eventcatalog/src/components/*"],
+      "@layouts/*": ["../../packages/core/eventcatalog/src/layouts/*"],
+      "@utils/*": ["../../packages/core/eventcatalog/src/utils/*"],
+      "@enterprise/*": ["../../packages/core/eventcatalog/src/enterprise/*"],
+      "@icons/*": ["../../packages/core/eventcatalog/src/icons/*"],
+      "@stores/*": ["../../packages/core/eventcatalog/src/stores/*"],
+      "@types": ["../../packages/core/eventcatalog/src/types/index.ts"],
+      "@config": ["eventcatalog.config.js"],
+      "@eventcatalog": ["../../packages/core/eventcatalog/src/utils/eventcatalog-config/catalog.ts"]
+    }
+  },
+  "include": ["pages/**/*", "components/**/*"]
+}
diff --git a/examples/default/users/aSmith.mdx b/examples/default/users/aSmith.mdx
deleted file mode 100644
index 26d703845..000000000
--- a/examples/default/users/aSmith.mdx
+++ /dev/null
@@ -1,27 +0,0 @@
----
-id: asmith
-name: Amy Smith
-avatarUrl: https://randomuser.me/api/portraits/women/48.jpg
-role: Product owner
----
-
-Hello! I'm Amy Smith, the Product Owner of the innovative Full Stackers team. With a strong focus on delivering exceptional value, I specialize in connecting business objectives with technical solutions to create products that users love.
-
-### About Me
-
-With a comprehensive background in product management and a solid understanding of software development, I bring a unique perspective to the table. My career has been driven by a passion for understanding user needs, defining clear product visions, and leading teams to successful product deliveries.
-
-### What I Do
-
-As the Product Owner for Full Stackers, my role involves a wide range of responsibilities aimed at ensuring our products are both high-quality and user-centric. Key aspects of my role include:
-
-- **Product Vision & Strategy**: Defining and communicating the long-term vision and strategy for our products, ensuring alignment with the company's objectives and market demands.
-- **Roadmap Planning**: Developing and maintaining a product roadmap that highlights key features and milestones, prioritizing tasks based on their business value and user feedback.
-- **Stakeholder Management**: Engaging with stakeholders across the organization to gather requirements, provide updates, and ensure everyone is aligned on the product's direction.
-- **User-Centric Design**: Championing the end-users by conducting user research, analyzing feedback, and ensuring our products effectively solve their problems.
-- **Agile Leadership**: Leading the development process using Agile methodologies, facilitating sprint planning, and ensuring the team has clear priorities and objectives.
-
-My mission is to deliver products that not only meet but exceed customer expectations. I thrive on the challenge of translating complex requirements into simple, intuitive solutions.
-
-If you’re interested in product management, user experience, or discussing the latest trends in technology, feel free to reach out!
-
diff --git a/examples/default/users/alee.mdx b/examples/default/users/alee.mdx
deleted file mode 100644
index d9c3e1aa8..000000000
--- a/examples/default/users/alee.mdx
+++ /dev/null
@@ -1,8 +0,0 @@
----
-id: alee
-name: Alice Lee
-avatarUrl: https://randomuser.me/api/portraits/women/91.jpg
-role: Technical Writer
----
-
-As a Technical Writer on the Documentation team, I create clear, comprehensive documentation for our products and APIs. My focus is on making complex technical concepts accessible to developers and end-users alike. I collaborate with engineering teams to ensure our documentation stays current and accurate. 
\ No newline at end of file
diff --git a/examples/default/users/azhang.mdx b/examples/default/users/azhang.mdx
deleted file mode 100644
index 1d86cf90f..000000000
--- a/examples/default/users/azhang.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
----
-id: azhang
-name: Alice Zhang
-avatarUrl: https://randomuser.me/api/portraits/women/97.jpg
-role: Data Engineer
-email: azhang@company.com
-slackDirectMessageUrl: https://yourteam.slack.com/channels/azhang
-msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=azhang@company.com
----
-
-Building and maintaining data pipelines and infrastructure... 
\ No newline at end of file
diff --git a/examples/default/users/dkim.mdx b/examples/default/users/dkim.mdx
deleted file mode 100644
index 96fd60ede..000000000
--- a/examples/default/users/dkim.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
----
-id: dkim
-name: David Kim
-avatarUrl: https://randomuser.me/api/portraits/men/96.jpg
-role: Performance Engineer
-email: dkim@company.com
-slackDirectMessageUrl: https://yourteam.slack.com/channels/dkim
-msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=dkim@company.com
----
-
-Optimizing application performance and user experience... 
\ No newline at end of file
diff --git a/examples/default/users/jbrown.mdx b/examples/default/users/jbrown.mdx
deleted file mode 100644
index 226bf6a5d..000000000
--- a/examples/default/users/jbrown.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
----
-id: jbrown
-name: Jessica Brown
-avatarUrl: https://randomuser.me/api/portraits/women/95.jpg
-role: UI/UX Designer
-email: jbrown@company.com
-slackDirectMessageUrl: https://yourteam.slack.com/channels/jbrown
-msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=jbrown@company.com
----
-
-Creating intuitive and engaging user interfaces... 
\ No newline at end of file
diff --git a/examples/default/users/mSmith.mdx b/examples/default/users/mSmith.mdx
deleted file mode 100644
index 1311cd656..000000000
--- a/examples/default/users/mSmith.mdx
+++ /dev/null
@@ -1,8 +0,0 @@
----
-id: msmith
-name: Martin Smith
-avatarUrl: "https://randomuser.me/api/portraits/men/51.jpg"
-role: Senior software engineer
----
-
-As a Senior Mobile Developer on The Mobile Devs team, I play a key role in designing, developing, and maintaining our company’s mobile applications. My focus is on creating a seamless and intuitive user experience for our customers on both iOS and Android platforms. I work closely with cross-functional teams, including backend developers, UX/UI designers, and product managers, to deliver high-quality mobile solutions that meet business objectives and exceed user expectations.
\ No newline at end of file
diff --git a/images/ai-demo.gif b/images/ai-demo.gif
new file mode 100644
index 000000000..4241e31bf
Binary files /dev/null and b/images/ai-demo.gif differ
diff --git a/images/banner.png b/images/banner.png
new file mode 100644
index 000000000..e3d2cca1d
Binary files /dev/null and b/images/banner.png differ
diff --git a/images/bring-your-own-docs.gif b/images/bring-your-own-docs.gif
new file mode 100644
index 000000000..88c09a6b3
Binary files /dev/null and b/images/bring-your-own-docs.gif differ
diff --git a/images/example.png b/images/example.png
index 2a341bb80..6b949e453 100644
Binary files a/images/example.png and b/images/example.png differ
diff --git a/images/flow-demo.gif b/images/flow-demo.gif
new file mode 100644
index 000000000..2b4469727
Binary files /dev/null and b/images/flow-demo.gif differ
diff --git a/images/overview-demo.gif b/images/overview-demo.gif
new file mode 100644
index 000000000..fcf0cf24c
Binary files /dev/null and b/images/overview-demo.gif differ
diff --git a/images/schema-explorer-demo.gif b/images/schema-explorer-demo.gif
new file mode 100644
index 000000000..96f994fba
Binary files /dev/null and b/images/schema-explorer-demo.gif differ
diff --git a/images/schema-fields-demo.gif b/images/schema-fields-demo.gif
new file mode 100644
index 000000000..8f3ca3959
Binary files /dev/null and b/images/schema-fields-demo.gif differ
diff --git a/images/sponsors/gravitee-logo-black.svg b/images/sponsors/gravitee-logo-black.svg
deleted file mode 100644
index 17d1740fa..000000000
--- a/images/sponsors/gravitee-logo-black.svg
+++ /dev/null
@@ -1,54 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Generator: Adobe Illustrator 26.0.2, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
-<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
-	 viewBox="0 0 624.3 125.8" style="enable-background:new 0 0 624.3 125.8;" xml:space="preserve">
-<style type="text/css">
-	.st0{fill:#000;}
-</style>
-<g>
-	<g>
-		<path class="st0" d="M279.4,85.5V23.7c0-1.6,1.3-2.9,2.9-2.9h5.7c1.6,0,2.9,1.3,2.9,2.9v61.8c0,1.6-1.3,2.9-2.9,2.9h-5.7
-			C280.7,88.4,279.4,87.1,279.4,85.5z"/>
-		<path class="st0" d="M282.3,0h5.7c1.6,0,2.9,1.3,2.9,2.9v5.7c0,1.6-1.3,2.9-2.9,2.9h-5.7c-1.6,0-2.9-1.3-2.9-2.9V2.9
-			C279.4,1.3,280.7,0,282.3,0z"/>
-	</g>
-	<path class="st0" d="M515,77h5.7c1.6,0,2.9,1.3,2.9,2.9v5.7c0,1.6-1.3,2.9-2.9,2.9H515c-1.6,0-2.9-1.3-2.9-2.9v-5.7
-		C512.1,78.2,513.4,77,515,77z"/>
-	<path class="st0" d="M266,20.9l-5.8,0c-1.8,0.1-3.3,1.2-3.8,2.9l-14.3,50.7c-0.4,2.1-2.5,3.4-4.5,3c-1.5-0.3-2.7-1.5-3-3.1
-		l-14.3-50.6c-0.5-1.7-2-2.9-3.8-2.9l-5.8,0c-1.2-0.1-2.3,0.8-2.4,2.1c0,0.3,0,0.6,0.1,0.9l15.1,53.8h0c2.2,8.1,10.6,12.9,18.7,10.7
-		c5.3-1.4,9.5-5.7,10.8-11l15-53.5c0.4-1.2-0.2-2.4-1.4-2.8C266.6,20.9,266.3,20.8,266,20.9z"/>
-	<g>
-		<path class="st0" d="M539.6,1.1L539.6,1.1c1.6,0,2.9,1.3,2.9,2.9v5.7c0,1.6-1.3,2.9-2.9,2.9l0,0c-1.6,0-2.9-1.3-2.9-2.9V3.9
-			C536.8,2.3,538.1,1.1,539.6,1.1z"/>
-		<path class="st0" d="M539.6,21.9L539.6,21.9c1.6,0,2.9,1.3,2.9,2.9v61.8c0,1.6-1.3,2.9-2.9,2.9l0,0c-1.6,0-2.9-1.3-2.9-2.9V24.7
-			C536.8,23.1,538.1,21.9,539.6,21.9z"/>
-	</g>
-	<path class="st0" d="M607.3,26.6c6.2,0,11.3,5.1,11.3,11.3V71c0,6.2-5.1,11.3-11.3,11.3h-34c-6.2,0-11.3-5.1-11.3-11.3V37.9
-		c0-6.2,5.1-11.3,11.3-11.3H607.3 M607.3,21h-34c-9.4,0-17,7.6-17,17V71c0,9.4,7.6,17,17,17h34c9.4,0,17-7.6,17-17V37.9
-		C624.3,28.6,616.7,21,607.3,21C607.3,21,607.3,21,607.3,21L607.3,21z"/>
-	<path class="st0" d="M79.7,21H21.2c-9.4,0-17,7.6-17,17c0,0,0,0,0,0v25.5c0,4.1,1.5,8,4.1,11.1c-4.8,5.2-5.5,13-1.7,19
-		C2.5,96.8,0,101.7,0,107v1.8c0,9.4,7.6,17,17,17h46.5c9.4,0,17-7.6,17-17V107c0-9.4-7.6-17-17-17H20.2v0c-2.7,0-4.8-2.2-4.7-4.9
-		c0-2.6,2.2-4.7,4.8-4.7h0.2c0.3,0,38.9,0,38.9,0c9.4,0,17-7.6,17-17c0,0,0,0,0,0l0.1-29c0-1.3,1-2.3,2.3-2.3h1.1
-		c1.5,0,2.8-1.3,2.8-2.8v-5.6C82.5,22.2,81.2,21,79.7,21z M69.3,107v1.8c0,3.2-2.6,5.8-5.8,5.8H17c-3.2,0-5.8-2.6-5.8-5.8V107
-		c0-3.2,2.6-5.8,5.8-5.8h46.5C66.7,101.2,69.3,103.8,69.3,107z M65,63.5c0,3.2-2.6,5.8-5.8,5.8h-38c-3.2,0-5.8-2.6-5.8-5.8V37.9
-		c0-3.2,2.6-5.8,5.8-5.8h38c3.2,0,5.8,2.6,5.8,5.8L65,63.5z"/>
-	<path class="st0" d="M123.6,21l-14.3,0c-9.4,0-17,7.6-17,17v47.6c0,1.5,1.2,2.8,2.8,2.8c0,0,0,0,0,0h5.6c1.5,0,2.8-1.2,2.8-2.8
-		c0,0,0,0,0,0l0-47.6c0-3.2,2.6-5.8,5.8-5.8h14.3c1.5,0,2.8-1.2,2.8-2.8c0,0,0,0,0,0v-5.6C126.4,22.2,125.1,21,123.6,21z"/>
-	<path class="st0" d="M338.4,32.2c1.6,0,2.9-1.3,2.9-2.9c0,0,0,0,0,0v-5.7c0-1.6-1.3-2.9-2.9-2.9l0,0h-15.8v-18
-		c0-1.5-1.2-2.8-2.8-2.8c0,0,0,0,0,0h-5.6c-1.5,0-2.8,1.2-2.8,2.8c0,0,0,0,0,0v18h-5.7c-1.6,0-2.9,1.3-2.9,2.9c0,0,0,0,0,0v5.7
-		c0,1.6,1.3,2.9,2.9,2.9c0,0,0,0,0,0h5.7v38.9c0,9.4,7.6,17,17,17l10,0c1.5,0,2.8-1.2,2.8-2.8l0,0v-5.6c0-1.5-1.2-2.8-2.8-2.8l0,0
-		h-10c-3.2,0-5.8-2.6-5.8-5.8l0-38.9L338.4,32.2z"/>
-	<path class="st0" d="M182.5,21l-43.5,0c-1.5,0-2.8,1.2-2.8,2.8c0,0,0,0,0,0v5.6c0,1.5,1.2,2.8,2.8,2.8h43.5c3.2,0,5.8,2.6,5.8,5.8
-		v7.4c-1.9-0.7-3.8-1-5.8-1h-33.4c-9.4,0-17,7.6-17,17v9.9c0,9.4,7.6,17,17,17l0,0h33.4c9.4,0,17-7.6,17-17V37.9
-		C199.4,28.6,191.8,21,182.5,21z M182.5,77h-33.4c-3.2,0-5.8-2.6-5.8-5.8v-9.9c0-3.2,2.6-5.8,5.8-5.8h33.4c3.1,0,5.7,2.5,5.8,5.6
-		v2.7c0,0,0,0.1,0,0.1v7.4C188.3,74.4,185.7,77,182.5,77L182.5,77z"/>
-	<path class="st0" d="M406.7,62.4c9.4,0,17-7.6,17-17v-7.5c0-9.4-7.6-17-17-17h-37.4c-9.4,0-17,7.6-17,17v0v4.8h0c0,0.1,0,0.1,0,0.2
-		v28.2c0,9.4,7.6,17,17,17l0,0l47.5,0c1.5,0,2.8-1.2,2.8-2.8l0,0v-5.6c0-1.5-1.2-2.8-2.8-2.8l0,0h-47.5c-3.2,0-5.8-2.6-5.8-5.8v-8.7
-		L406.7,62.4z M363.5,42.7v-4.8c0-3.2,2.6-5.8,5.8-5.8h37.4c3.2,0,5.8,2.6,5.8,5.8v7.5c0,3.2-2.6,5.8-5.8,5.8h-43.2v-8.3
-		C363.5,42.8,363.5,42.7,363.5,42.7L363.5,42.7z"/>
-	<path class="st0" d="M489,62.4c9.4,0,17-7.6,17-17c0,0,0,0,0,0v-7.5c0-9.4-7.6-17-17-17l0,0h-37.4c-9.4,0-17,7.6-17,17v0v4.8h0
-		c0,0.1,0,0.1,0,0.2v28.2c0,9.4,7.6,17,17,17l0,0l47.5,0c1.5,0,2.8-1.2,2.8-2.8l0,0v-5.6c0-1.5-1.2-2.8-2.8-2.8l0,0h-47.5
-		c-3.2,0-5.8-2.6-5.8-5.8v-8.7L489,62.4z M445.8,42.7v-4.8c0-3.2,2.6-5.8,5.8-5.8H489c3.2,0,5.8,2.6,5.8,5.8v7.5
-		c0,3.2-2.6,5.8-5.8,5.8h-43.2v-8.3C445.8,42.8,445.8,42.7,445.8,42.7L445.8,42.7z"/>
-</g>
-</svg>
diff --git a/images/sponsors/gravitee-logo-white.webp b/images/sponsors/gravitee-logo-white.webp
deleted file mode 100644
index 9397b59fa..000000000
Binary files a/images/sponsors/gravitee-logo-white.webp and /dev/null differ
diff --git a/images/sponsors/hookdeck.svg b/images/sponsors/hookdeck.svg
deleted file mode 100644
index 962b07dcc..000000000
--- a/images/sponsors/hookdeck.svg
+++ /dev/null
@@ -1,11 +0,0 @@
-<svg width="355" height="57" viewBox="0 0 355 57" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M54.475 21.1C54.875 21.1 55.275 21.4 55.475 21.8C55.675 22.2 55.575 22.7 55.275 23L30.275 48C23.375 54.9 12.075 54.9 5.175 48C-1.725 41.1 -1.725 29.8 5.175 22.9L19.575 8.50003C23.675 4.40003 29.275 2.80003 34.575 3.50003C34.975 3.60003 35.275 3.80002 35.475 4.20002C35.575 4.60002 35.475 5.00003 35.175 5.30003L31.975 8.50003C31.475 9.00003 30.875 9.30002 30.275 9.40002C27.875 9.80002 25.575 10.9 23.775 12.7L9.375 27.1C4.775 31.7 4.775 39.2 9.375 43.8C13.975 48.4 21.475 48.4 26.075 43.8L43.975 25.9L41.075 23C40.775 22.7 40.675 22.2 40.875 21.8C41.075 21.4 41.475 21.1 41.875 21.1H54.475ZM28.675 35.6C29.075 35.6 29.475 35.3 29.675 34.9C29.875 34.5 29.775 34 29.475 33.7L26.575 30.8L44.475 12.9C49.075 8.30002 56.575 8.30002 61.175 12.9C65.775 17.5 65.775 25 61.175 29.6L46.675 44C44.875 45.8 42.575 46.9 40.175 47.3C39.475 47.4 38.875 47.7 38.475 48.2L35.275 51.4C34.975 51.7 34.875 52.1 34.975 52.5C35.075 52.9 35.475 53.2 35.875 53.2C41.175 53.9 46.775 52.3 50.875 48.2L65.275 33.8C72.175 26.9 72.175 15.6 65.275 8.70002C58.375 1.80002 47.075 1.80002 40.175 8.70002L15.175 33.7C14.875 34 14.775 34.5 14.975 34.9C15.175 35.3 15.575 35.6 15.975 35.6H28.675Z" fill="#0044CC"/>
-<path d="M114.784 48V8.09997H122.593V48H114.784ZM88.507 48V8.04297H96.316V48H88.507ZM94.321 31.185V24.003H118.489V31.185H94.321Z" fill="#141412"/>
-<path d="M144.139 48.684C141.251 48.684 138.667 48.057 136.387 46.803C134.145 45.511 132.378 43.744 131.086 41.502C129.832 39.26 129.205 36.676 129.205 33.75C129.205 30.824 129.832 28.24 131.086 25.998C132.34 23.756 134.088 22.008 136.33 20.754C138.572 19.462 141.137 18.816 144.025 18.816C146.951 18.816 149.535 19.462 151.777 20.754C154.019 22.008 155.767 23.756 157.021 25.998C158.275 28.24 158.902 30.824 158.902 33.75C158.902 36.676 158.275 39.26 157.021 41.502C155.767 43.744 154.019 45.511 151.777 46.803C149.573 48.057 147.027 48.684 144.139 48.684ZM144.139 41.73C145.545 41.73 146.78 41.388 147.844 40.704C148.908 40.02 149.725 39.089 150.295 37.911C150.903 36.695 151.207 35.308 151.207 33.75C151.207 32.192 150.903 30.824 150.295 29.646C149.687 28.43 148.832 27.48 147.73 26.796C146.666 26.112 145.431 25.77 144.025 25.77C142.657 25.77 141.422 26.112 140.32 26.796C139.256 27.48 138.42 28.43 137.812 29.646C137.204 30.824 136.9 32.192 136.9 33.75C136.9 35.308 137.204 36.695 137.812 37.911C138.42 39.089 139.275 40.02 140.377 40.704C141.479 41.388 142.733 41.73 144.139 41.73Z" fill="#141412"/>
-<path d="M177.829 48.684C174.941 48.684 172.357 48.057 170.077 46.803C167.835 45.511 166.068 43.744 164.776 41.502C163.522 39.26 162.895 36.676 162.895 33.75C162.895 30.824 163.522 28.24 164.776 25.998C166.03 23.756 167.778 22.008 170.02 20.754C172.262 19.462 174.827 18.816 177.715 18.816C180.641 18.816 183.225 19.462 185.467 20.754C187.709 22.008 189.457 23.756 190.711 25.998C191.965 28.24 192.592 30.824 192.592 33.75C192.592 36.676 191.965 39.26 190.711 41.502C189.457 43.744 187.709 45.511 185.467 46.803C183.263 48.057 180.717 48.684 177.829 48.684ZM177.829 41.73C179.235 41.73 180.47 41.388 181.534 40.704C182.598 40.02 183.415 39.089 183.985 37.911C184.593 36.695 184.897 35.308 184.897 33.75C184.897 32.192 184.593 30.824 183.985 29.646C183.377 28.43 182.522 27.48 181.42 26.796C180.356 26.112 179.121 25.77 177.715 25.77C176.347 25.77 175.112 26.112 174.01 26.796C172.946 27.48 172.11 28.43 171.502 29.646C170.894 30.824 170.59 32.192 170.59 33.75C170.59 35.308 170.894 36.695 171.502 37.911C172.11 39.089 172.965 40.02 174.067 40.704C175.169 41.388 176.423 41.73 177.829 41.73Z" fill="#141412"/>
-<path d="M205.306 40.761L200.803 35.574L215.395 19.5H224.344L205.306 40.761ZM198.124 48V8.09997H205.648V48H198.124ZM216.364 48L206.902 34.206L211.804 29.019L225.199 48H216.364Z" fill="#141412"/>
-<path d="M248.154 48L247.755 42.699V8.09997H255.279V48H248.154ZM239.205 48.684C236.583 48.684 234.303 48.076 232.365 46.86C230.465 45.644 228.983 43.915 227.919 41.673C226.855 39.431 226.323 36.79 226.323 33.75C226.323 30.672 226.855 28.031 227.919 25.827C228.983 23.585 230.465 21.856 232.365 20.64C234.303 19.424 236.583 18.816 239.205 18.816C241.599 18.816 243.613 19.424 245.247 20.64C246.919 21.856 248.192 23.585 249.066 25.827C249.94 28.031 250.377 30.672 250.377 33.75C250.377 36.79 249.94 39.431 249.066 41.673C248.192 43.915 246.919 45.644 245.247 46.86C243.613 48.076 241.599 48.684 239.205 48.684ZM241.143 41.787C242.435 41.787 243.575 41.445 244.563 40.761C245.589 40.077 246.387 39.127 246.957 37.911C247.527 36.695 247.812 35.308 247.812 33.75C247.812 32.192 247.527 30.805 246.957 29.589C246.387 28.373 245.589 27.442 244.563 26.796C243.575 26.112 242.416 25.77 241.086 25.77C239.718 25.77 238.521 26.112 237.495 26.796C236.469 27.442 235.652 28.373 235.044 29.589C234.436 30.805 234.132 32.192 234.132 33.75C234.132 35.308 234.436 36.695 235.044 37.911C235.652 39.127 236.469 40.077 237.495 40.761C238.559 41.445 239.775 41.787 241.143 41.787Z" fill="#141412"/>
-<path d="M275.214 48.684C272.402 48.684 269.913 48.057 267.747 46.803C265.581 45.511 263.871 43.744 262.617 41.502C261.401 39.26 260.793 36.676 260.793 33.75C260.793 30.824 261.42 28.24 262.674 25.998C263.966 23.756 265.714 22.008 267.918 20.754C270.16 19.462 272.725 18.816 275.613 18.816C278.121 18.816 280.42 19.481 282.51 20.811C284.638 22.103 286.329 24.022 287.583 26.568C288.875 29.076 289.521 32.135 289.521 35.745H267.918L268.602 35.061C268.602 36.467 268.944 37.702 269.628 38.766C270.35 39.792 271.262 40.59 272.364 41.16C273.504 41.692 274.72 41.958 276.012 41.958C277.57 41.958 278.843 41.635 279.831 40.989C280.819 40.305 281.579 39.431 282.111 38.367L288.837 40.989C288.039 42.585 286.994 43.972 285.702 45.15C284.448 46.29 282.947 47.164 281.199 47.772C279.451 48.38 277.456 48.684 275.214 48.684ZM269.001 30.843L268.317 30.159H282.054L281.427 30.843C281.427 29.475 281.104 28.392 280.458 27.594C279.812 26.758 279.014 26.15 278.064 25.77C277.152 25.39 276.259 25.2 275.385 25.2C274.511 25.2 273.58 25.39 272.592 25.77C271.604 26.15 270.749 26.758 270.027 27.594C269.343 28.392 269.001 29.475 269.001 30.843Z" fill="#141412"/>
-<path d="M308.2 48.684C305.236 48.684 302.595 48.057 300.277 46.803C297.959 45.511 296.154 43.744 294.862 41.502C293.57 39.222 292.924 36.638 292.924 33.75C292.924 30.824 293.57 28.24 294.862 25.998C296.154 23.756 297.94 22.008 300.22 20.754C302.5 19.462 305.122 18.816 308.086 18.816C310.936 18.816 313.539 19.519 315.895 20.925C318.251 22.331 319.961 24.364 321.025 27.024L313.957 29.532C313.425 28.43 312.589 27.556 311.449 26.91C310.347 26.226 309.112 25.884 307.744 25.884C306.338 25.884 305.103 26.226 304.039 26.91C302.975 27.556 302.139 28.468 301.531 29.646C300.923 30.824 300.619 32.192 300.619 33.75C300.619 35.308 300.923 36.676 301.531 37.854C302.139 38.994 302.994 39.906 304.096 40.59C305.198 41.274 306.452 41.616 307.858 41.616C309.226 41.616 310.461 41.255 311.563 40.533C312.703 39.811 313.539 38.861 314.071 37.683L321.196 40.191C320.094 42.889 318.365 44.979 316.009 46.461C313.691 47.943 311.088 48.684 308.2 48.684Z" fill="#141412"/>
-<path d="M333.331 40.761L328.828 35.574L343.42 19.5H352.369L333.331 40.761ZM326.149 48V8.09997H333.673V48H326.149ZM344.389 48L334.927 34.206L339.829 29.019L353.224 48H344.389Z" fill="#141412"/>
-</svg>
diff --git a/images/sponsors/oso-logo-green.png b/images/sponsors/oso-logo-green.png
deleted file mode 100644
index 61a8e8185..000000000
Binary files a/images/sponsors/oso-logo-green.png and /dev/null differ
diff --git a/images/visualizer-demo.gif b/images/visualizer-demo.gif
new file mode 100644
index 000000000..74a5c92c0
Binary files /dev/null and b/images/visualizer-demo.gif differ
diff --git a/package.json b/package.json
index 5f6dd269c..f3cbddac3 100644
--- a/package.json
+++ b/package.json
@@ -1,159 +1,35 @@
 {
-  "name": "@eventcatalog/core",
-  "homepage": "https://github.com/event-catalog/eventcatalog",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/event-catalog/eventcatalog.git"
-  },
-  "type": "module",
-  "version": "2.65.1",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "eventcatalog": "bin/eventcatalog.js"
-  },
-  "files": [
-    "eventcatalog/",
-    "!eventcatalog/**/__tests__/",
-    "bin/",
-    "dist/",
-    "default-files-for-collections/"
-  ],
+  "name": "eventcatalog-monorepo",
+  "private": true,
+  "license": "MIT",
   "scripts": {
-    "dev": "astro dev",
-    "build:bin": "tsup",
-    "prepublishOnly": "pnpm run build:bin",
-    "test": "vitest",
-    "test:ci": "node scripts/ci/test.js",
-    "test:e2e": "playwright test",
-    "start": "astro dev",
-    "build": "astro build",
-    "build:cd": "node scripts/build-ci.js",
-    "preview": "astro preview",
-    "astro": "astro",
-    "start:catalog": "node scripts/start-catalog-locally.js",
-    "pagefind": "node scripts/pagefind.js",
-    "preview:catalog": "node scripts/preview-catalog-locally.js",
-    "generate:catalog": "node scripts/generate-catalog-locally.js",
-    "verify-build:catalog": "rimraf dist && pnpm run build:cd",
+    "build:bin": "turbo run build:bin",
+    "build": "turbo run build",
+    "test": "turbo run test",
+    "test:ci": "turbo run test:ci",
+    "format": "turbo run format",
+    "format:diff": "turbo run format:diff",
+    "start:playground": "pnpm --filter @eventcatalog/dsl-playground run dev",
+    "start:dsl-docs": "pnpm --filter @eventcatalog/language-server run docs:dev",
+    "build:dsl-docs": "pnpm --filter @eventcatalog/sdk run build && pnpm --filter @eventcatalog/language-server run build && pnpm --filter @eventcatalog/language-server run docs:build",
+    "start:catalog": "pnpm --filter @eventcatalog/core run start:catalog",
+    "export:catalog": "pnpm --filter @eventcatalog/core run export:catalog",
+    "preview:catalog": "pnpm --filter @eventcatalog/core run preview:catalog",
+    "start:catalog:server": "pnpm --filter @eventcatalog/core run start:catalog:server",
+    "verify-build:catalog": "pnpm --filter @eventcatalog/core run verify-build:catalog",
     "changeset": "changeset",
-    "generate": "pnpm run build:bin && npx . generate",
-    "release": "changeset publish",
-    "format": "prettier --config .prettierrc --write \"**/*.{js,jsx,ts,tsx,json,astro}\"",
-    "format:diff": "prettier --config .prettierrc --list-different \"**/*.{js,jsx,ts,tsx,json,astro}\"",
-    "lint:catalog": "pnpm dlx @eventcatalog/linter examples/default"
-  },
-  "dependencies": {
-    "@ai-sdk/anthropic": "^2.0.23",
-    "@ai-sdk/google": "^2.0.17",
-    "@ai-sdk/openai": "^2.0.42",
-    "@ai-sdk/react": "^2.0.60",
-    "@astrojs/markdown-remark": "^6.3.9",
-    "@astrojs/mdx": "^4.3.12",
-    "@astrojs/node": "^9.5.1",
-    "@astrojs/react": "^4.4.2",
-    "@astrojs/rss": "^4.0.14",
-    "@astrojs/tailwind": "^6.0.2",
-    "@asyncapi/avro-schema-parser": "3.0.24",
-    "@asyncapi/parser": "3.4.0",
-    "@asyncapi/react-component": "2.4.3",
-    "@auth/core": "^0.37.4",
-    "@eventcatalog/generator-ai": "^1.1.0",
-    "@eventcatalog/license": "^0.0.7",
-    "@eventcatalog/linter": "^0.0.2",
-    "@eventcatalog/sdk": "^2.9.2",
-    "@eventcatalog/visualizer": "^0.0.6",
-    "@fontsource/inter": "^5.2.5",
-    "@headlessui/react": "^2.0.3",
-    "@heroicons/react": "^2.1.3",
-    "@iconify-json/logos": "^1.2.4",
-    "@mermaid-js/layout-elk": "^0.2.0",
-    "@parcel/watcher": "^2.4.1",
-    "@radix-ui/react-context-menu": "^2.2.6",
-    "@radix-ui/react-dialog": "^1.1.6",
-    "@radix-ui/react-dropdown-menu": "^2.1.12",
-    "@radix-ui/react-tooltip": "^1.1.8",
-    "@scalar/api-reference-react": "^0.4.37",
-    "@tailwindcss/typography": "^0.5.13",
-    "@tanstack/react-query": "^5.74.3",
-    "@tanstack/react-table": "^8.17.3",
-    "@xyflow/react": "^12.3.6",
-    "ai": "^5.0.60",
-    "astro": "^5.16.0",
-    "astro-compress": "^2.3.8",
-    "astro-expressive-code": "^0.41.3",
-    "astro-seo": "^0.8.4",
-    "auth-astro": "^4.2.0",
-    "axios": "^1.7.7",
-    "boxen": "^8.0.1",
-    "commander": "^12.1.0",
-    "concurrently": "^8.2.2",
-    "cross-env": "^7.0.3",
-    "dagre": "^0.8.5",
-    "date-fns": "^4.1.0",
-    "diff": "^7.0.0",
-    "diff2html": "^3.4.48",
-    "dotenv": "^16.5.0",
-    "elkjs": "^0.10.0",
-    "glob": "^10.5.0",
-    "gray-matter": "^4.0.3",
-    "html-to-image": "^1.11.11",
-    "js-yaml": "^4.1.0",
-    "jsonpath": "^1.1.1",
-    "jsonwebtoken": "^9.0.2",
-    "lodash.debounce": "^4.0.8",
-    "lodash.merge": "4.6.2",
-    "lucide-react": "^0.453.0",
-    "marked": "^15.0.6",
-    "mermaid": "^11.4.1",
-    "pagefind": "^1.3.0",
-    "pako": "^2.1.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "react-markdown": "^10.1.0",
-    "react-syntax-highlighter": "^15.6.1",
-    "rehype-autolink-headings": "^7.1.0",
-    "rehype-expressive-code": "^0.41.3",
-    "rehype-slug": "^6.0.0",
-    "remark-comment": "^1.0.0",
-    "remark-directive": "^3.0.0",
-    "remark-gfm": "^3.0.1",
-    "rimraf": "^5.0.7",
-    "semver": "7.6.3",
-    "shelljs": "^0.8.5",
-    "tailwindcss": "^3.4.3",
-    "typescript": "^5.4.5",
-    "unist-util-visit": "^5.0.0",
-    "update-notifier": "^7.3.1",
-    "uuid": "^10.0.0"
+    "release": "changeset publish"
   },
   "devDependencies": {
-    "@astrojs/check": "^0.9.5",
     "@changesets/cli": "^2.27.5",
-    "@playwright/test": "^1.48.1",
-    "@types/dagre": "^0.7.52",
-    "@types/diff": "^5.2.2",
-    "@types/js-yaml": "^4.0.9",
-    "@types/jsonpath": "^0.2.4",
-    "@types/jsonwebtoken": "^9.0.10",
-    "@types/lodash.debounce": "^4.0.9",
-    "@types/lodash.merge": "4.6.9",
-    "@types/node": "^20.14.2",
-    "@types/pako": "^2.0.3",
-    "@types/react": "^18.3.3",
-    "@types/react-dom": "^18.3.0",
-    "@types/react-syntax-highlighter": "^15.5.13",
-    "@types/semver": "^7.5.8",
-    "@types/shelljs": "^0.8.15",
-    "@types/update-notifier": "^6.0.8",
-    "@types/uuid": "^10.0.0",
-    "prettier": "^3.3.3",
     "prettier-plugin-astro": "^0.14.1",
-    "tsup": "^8.1.0",
-    "vite": "^7.1.7",
-    "vite-tsconfig-paths": "^4.3.2",
-    "vitest": "2.1.9"
+    "turbo": "^2.8.4"
+  },
+  "pnpm": {
+    "overrides": {
+      "prismjs": ">=1.30.0"
+    }
   },
-  "packageManager": "pnpm@10.23.0+sha512.21c4e5698002ade97e4efe8b8b4a89a8de3c85a37919f957e7a0f30f38fbc5bbdd05980ffe29179b2fb6e6e691242e098d945d1601772cad0fef5fb6411e2a4b"
+  "packageManager": "pnpm@10.23.0+sha512.21c4e5698002ade97e4efe8b8b4a89a8de3c85a37919f957e7a0f30f38fbc5bbdd05980ffe29179b2fb6e6e691242e098d945d1601772cad0fef5fb6411e2a4b",
+  "dependencies": {}
 }
diff --git a/packages/breaking-changes/CHANGELOG.md b/packages/breaking-changes/CHANGELOG.md
new file mode 100644
index 000000000..16a91fb3f
--- /dev/null
+++ b/packages/breaking-changes/CHANGELOG.md
@@ -0,0 +1,9 @@
+# @eventcatalog/breaking-changes
+
+## 0.2.0
+
+### Minor Changes
+
+- a3313f6: feat: add breaking schema change detection with governance webhooks
+
+  New `schema_breaking_change` governance trigger that detects breaking JSON Schema changes per compatibility strategy (BACKWARD, FORWARD, FULL, NONE). Users configure `compatibility.strategy` in governance.yaml and subscribe to breaking change webhooks with detailed diff information.
diff --git a/packages/breaking-changes/package.json b/packages/breaking-changes/package.json
new file mode 100644
index 000000000..974eb1531
--- /dev/null
+++ b/packages/breaking-changes/package.json
@@ -0,0 +1,41 @@
+{
+  "name": "@eventcatalog/breaking-changes",
+  "version": "0.2.0",
+  "description": "Breaking schema change detection for EventCatalog",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:bin": "tsup",
+    "test": "vitest --run",
+    "test:ci": "vitest --run",
+    "format": "prettier --write .",
+    "format:diff": "prettier --list-different ."
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "prettier": "^3.3.3",
+    "tsup": "^8.1.0",
+    "typescript": "^5.5.3",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/event-catalog/eventcatalog"
+  }
+}
diff --git a/packages/breaking-changes/src/index.ts b/packages/breaking-changes/src/index.ts
new file mode 100644
index 000000000..a95c46b28
--- /dev/null
+++ b/packages/breaking-changes/src/index.ts
@@ -0,0 +1,9 @@
+export type {
+  CompatibilityStrategy,
+  SchemaChange,
+  BreakingChange,
+  SchemaChangeType,
+} from "./types";
+
+export { detectBreakingChanges } from "./json-schema/rules";
+export { diffJsonSchemas } from "./json-schema/differ";
diff --git a/packages/breaking-changes/src/json-schema/differ.ts b/packages/breaking-changes/src/json-schema/differ.ts
new file mode 100644
index 000000000..5b7d848e5
--- /dev/null
+++ b/packages/breaking-changes/src/json-schema/differ.ts
@@ -0,0 +1,122 @@
+import type { SchemaChange } from "../types";
+
+type JsonSchemaObject = {
+  type?: string;
+  properties?: Record<string, JsonSchemaObject>;
+  required?: string[];
+  [key: string]: any;
+};
+
+const hasProperties = (schema: JsonSchemaObject): boolean =>
+  !!(schema.properties || schema.required);
+
+export const diffJsonSchemas = (
+  before: JsonSchemaObject,
+  after: JsonSchemaObject,
+): SchemaChange[] => {
+  const changes: SchemaChange[] = [];
+
+  // Detect root-level type changes
+  if (before.type && after.type && before.type !== after.type) {
+    changes.push({
+      type: "TYPE_CHANGED",
+      field: "(root)",
+      message: `Root type changed from '${before.type}' to '${after.type}'`,
+      previousType: before.type,
+      currentType: after.type,
+    });
+  }
+
+  compareProperties(before, after, "", changes);
+  return changes;
+};
+
+const compareProperties = (
+  before: JsonSchemaObject,
+  after: JsonSchemaObject,
+  prefix: string,
+  changes: SchemaChange[],
+): void => {
+  const beforeProps = before.properties || {};
+  const afterProps = after.properties || {};
+  const beforeRequired = new Set(before.required || []);
+  const afterRequired = new Set(after.required || []);
+
+  const allFields = new Set([
+    ...Object.keys(beforeProps),
+    ...Object.keys(afterProps),
+  ]);
+
+  for (const field of allFields) {
+    const fullPath = prefix ? `${prefix}.${field}` : field;
+    const inBefore = field in beforeProps;
+    const inAfter = field in afterProps;
+
+    if (!inBefore && inAfter) {
+      const isRequired = afterRequired.has(field);
+      changes.push({
+        type: isRequired ? "FIELD_ADDED_REQUIRED" : "FIELD_ADDED_OPTIONAL",
+        field: fullPath,
+        message: `${isRequired ? "Required" : "Optional"} field '${fullPath}' was added`,
+      });
+      continue;
+    }
+
+    if (inBefore && !inAfter) {
+      const wasRequired = beforeRequired.has(field);
+      changes.push({
+        type: wasRequired ? "FIELD_REMOVED_REQUIRED" : "FIELD_REMOVED_OPTIONAL",
+        field: fullPath,
+        message: `${wasRequired ? "Required" : "Optional"} field '${fullPath}' was removed`,
+      });
+      continue;
+    }
+
+    // Field exists in both — check type
+    const beforeType = beforeProps[field].type;
+    const afterType = afterProps[field].type;
+
+    if (beforeType && afterType && beforeType !== afterType) {
+      changes.push({
+        type: "TYPE_CHANGED",
+        field: fullPath,
+        message: `Field '${fullPath}' type changed from '${beforeType}' to '${afterType}'`,
+        previousType: beforeType,
+        currentType: afterType,
+      });
+    }
+
+    // Check required status change
+    const wasPreviouslyRequired = beforeRequired.has(field);
+    const isNowRequired = afterRequired.has(field);
+
+    if (!wasPreviouslyRequired && isNowRequired) {
+      changes.push({
+        type: "REQUIRED_ADDED",
+        field: fullPath,
+        message: `Field '${fullPath}' was made required`,
+      });
+    } else if (wasPreviouslyRequired && !isNowRequired) {
+      changes.push({
+        type: "REQUIRED_REMOVED",
+        field: fullPath,
+        message: `Field '${fullPath}' was made optional`,
+      });
+    }
+
+    // Recurse into nested objects (explicit type or implicit via properties/required)
+    if (
+      beforeProps[field].type === "object" ||
+      afterProps[field].type === "object" ||
+      hasProperties(beforeProps[field]) ||
+      hasProperties(afterProps[field])
+    ) {
+      compareProperties(
+        beforeProps[field],
+        afterProps[field],
+        fullPath,
+        changes,
+      );
+    }
+  }
+};
diff --git a/packages/breaking-changes/src/json-schema/rules.ts b/packages/breaking-changes/src/json-schema/rules.ts
new file mode 100644
index 000000000..c25184292
--- /dev/null
+++ b/packages/breaking-changes/src/json-schema/rules.ts
@@ -0,0 +1,44 @@
+import type {
+  CompatibilityStrategy,
+  SchemaChange,
+  BreakingChange,
+  SchemaChangeType,
+} from "../types";
+import { diffJsonSchemas } from "./differ";
+
+const BREAKING_RULES: Record<CompatibilityStrategy, Set<SchemaChangeType>> = {
+  BACKWARD: new Set([
+    "FIELD_ADDED_REQUIRED",
+    "FIELD_REMOVED_REQUIRED",
+    "TYPE_CHANGED",
+    "REQUIRED_ADDED",
+  ]),
+  FORWARD: new Set([
+    "FIELD_ADDED_REQUIRED",
+    "FIELD_REMOVED_REQUIRED",
+    "TYPE_CHANGED",
+    "REQUIRED_ADDED",
+  ]),
+  FULL: new Set([
+    "FIELD_ADDED_REQUIRED",
+    "FIELD_REMOVED_REQUIRED",
+    "TYPE_CHANGED",
+    "REQUIRED_ADDED",
+  ]),
+  NONE: new Set(),
+};
+
+export const detectBreakingChanges = (
+  before: object,
+  after: object,
+  strategy: CompatibilityStrategy,
+): BreakingChange[] => {
+  if (strategy === "NONE") return [];
+
+  const changes = diffJsonSchemas(before, after);
+  const breakingTypes = BREAKING_RULES[strategy];
+
+  return changes
+    .filter((change) => breakingTypes.has(change.type))
+    .map((change) => ({ ...change, breaking: true as const }));
+};
diff --git a/packages/breaking-changes/src/test/index.test.ts b/packages/breaking-changes/src/test/index.test.ts
new file mode 100644
index 000000000..5312ebb73
--- /dev/null
+++ b/packages/breaking-changes/src/test/index.test.ts
@@ -0,0 +1,73 @@
+import { describe, it, expect } from "vitest";
+import { detectBreakingChanges, diffJsonSchemas } from "../index";
+
+describe("public API", () => {
+  it("detectBreakingChanges returns breaking changes for a real schema evolution", () => {
+    const v1 = {
+      type: "object",
+      properties: {
+        orderId: { type: "string" },
+        amount: { type: "string" },
+        currency: { type: "string" },
+      },
+      required: ["orderId", "amount"],
+    };
+
+    const v2 = {
+      type: "object",
+      properties: {
+        orderId: { type: "string" },
+        amount: { type: "number" },
+        currency: { type: "string" },
+        region: { type: "string" },
+      },
+      required: ["orderId", "amount", "region"],
+    };
+
+    const result = detectBreakingChanges(v1, v2, "BACKWARD");
+
+    expect(result).toContainEqual(
+      expect.objectContaining({
+        type: "TYPE_CHANGED",
+        field: "amount",
+        breaking: true,
+      }),
+    );
+    expect(result).toContainEqual(
+      expect.objectContaining({
+        type: "FIELD_ADDED_REQUIRED",
+        field: "region",
+        breaking: true,
+      }),
+    );
+    expect(result).toHaveLength(2);
+  });
+
+  it("diffJsonSchemas is exported and returns all changes", () => {
+    const before = {
+      type: "object",
+      properties: { name: { type: "string" } },
+    };
+    const after = {
+      type: "object",
+      properties: { name: { type: "number" } },
+    };
+
+    const changes = diffJsonSchemas(before, after);
+    expect(changes).toHaveLength(1);
+    expect(changes[0].type).toBe("TYPE_CHANGED");
+  });
+
+  it("NONE strategy always returns empty", () => {
+    const result = detectBreakingChanges(
+      {
+        type: "object",
+        properties: { a: { type: "string" } },
+        required: ["a"],
+      },
+      { type: "object" },
+      "NONE",
+    );
+    expect(result).toEqual([]);
+  });
+});
diff --git a/packages/breaking-changes/src/test/json-schema-differ.test.ts b/packages/breaking-changes/src/test/json-schema-differ.test.ts
new file mode 100644
index 000000000..e3f573b4a
--- /dev/null
+++ b/packages/breaking-changes/src/test/json-schema-differ.test.ts
@@ -0,0 +1,375 @@
+import { describe, it, expect } from "vitest";
+import { diffJsonSchemas } from "../json-schema/differ";
+
+describe("diffJsonSchemas", () => {
+  describe("field additions", () => {
+    it("detects an added optional field", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" } },
+      };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+      };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toEqual([
+        {
+          type: "FIELD_ADDED_OPTIONAL",
+          field: "email",
+          message: "Optional field 'email' was added",
+        },
+      ]);
+    });
+
+    it("detects an added required field", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+      };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name", "email"],
+      };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toEqual([
+        {
+          type: "FIELD_ADDED_REQUIRED",
+          field: "email",
+          message: "Required field 'email' was added",
+        },
+      ]);
+    });
+  });
+
+  describe("field removals", () => {
+    it("detects a removed optional field", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name"],
+      };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+      };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toEqual([
+        {
+          type: "FIELD_REMOVED_OPTIONAL",
+          field: "email",
+          message: "Optional field 'email' was removed",
+        },
+      ]);
+    });
+
+    it("detects a removed required field", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name", "email"],
+      };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+      };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toEqual([
+        {
+          type: "FIELD_REMOVED_REQUIRED",
+          field: "email",
+          message: "Required field 'email' was removed",
+        },
+      ]);
+    });
+  });
+
+  describe("type changes", () => {
+    it("detects a field type change", () => {
+      const before = {
+        type: "object",
+        properties: { amount: { type: "string" } },
+      };
+      const after = {
+        type: "object",
+        properties: { amount: { type: "number" } },
+      };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toEqual([
+        {
+          type: "TYPE_CHANGED",
+          field: "amount",
+          message: "Field 'amount' type changed from 'string' to 'number'",
+          previousType: "string",
+          currentType: "number",
+        },
+      ]);
+    });
+  });
+
+  describe("required changes (without add/remove)", () => {
+    it("detects a field becoming required", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name"],
+      };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name", "email"],
+      };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toEqual([
+        {
+          type: "REQUIRED_ADDED",
+          field: "email",
+          message: "Field 'email' was made required",
+        },
+      ]);
+    });
+
+    it("detects a field becoming optional", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name", "email"],
+      };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name"],
+      };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toEqual([
+        {
+          type: "REQUIRED_REMOVED",
+          field: "email",
+          message: "Field 'email' was made optional",
+        },
+      ]);
+    });
+  });
+
+  describe("nested objects", () => {
+    it("detects changes in nested properties using dot-path notation", () => {
+      const before = {
+        type: "object",
+        properties: {
+          address: {
+            type: "object",
+            properties: {
+              street: { type: "string" },
+              zipCode: { type: "string" },
+            },
+            required: ["street"],
+          },
+        },
+      };
+      const after = {
+        type: "object",
+        properties: {
+          address: {
+            type: "object",
+            properties: { street: { type: "string" } },
+            required: ["street"],
+          },
+        },
+      };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toEqual([
+        {
+          type: "FIELD_REMOVED_OPTIONAL",
+          field: "address.zipCode",
+          message: "Optional field 'address.zipCode' was removed",
+        },
+      ]);
+    });
+
+    it("detects type changes in deeply nested fields", () => {
+      const before = {
+        type: "object",
+        properties: {
+          order: {
+            type: "object",
+            properties: {
+              item: {
+                type: "object",
+                properties: { price: { type: "string" } },
+              },
+            },
+          },
+        },
+      };
+      const after = {
+        type: "object",
+        properties: {
+          order: {
+            type: "object",
+            properties: {
+              item: {
+                type: "object",
+                properties: { price: { type: "number" } },
+              },
+            },
+          },
+        },
+      };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toEqual([
+        {
+          type: "TYPE_CHANGED",
+          field: "order.item.price",
+          message:
+            "Field 'order.item.price' type changed from 'string' to 'number'",
+          previousType: "string",
+          currentType: "number",
+        },
+      ]);
+    });
+  });
+
+  describe("no changes", () => {
+    it("returns empty array when schemas are identical", () => {
+      const schema = {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+      };
+      expect(diffJsonSchemas(schema, schema)).toEqual([]);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles empty schemas", () => {
+      expect(diffJsonSchemas({}, {})).toEqual([]);
+    });
+
+    it("handles schema with no properties going to one with properties", () => {
+      const before = { type: "object" };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" } },
+      };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toEqual([
+        {
+          type: "FIELD_ADDED_OPTIONAL",
+          field: "name",
+          message: "Optional field 'name' was added",
+        },
+      ]);
+    });
+
+    it("handles schema with properties going to one with no properties", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+      };
+      const after = { type: "object" };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toEqual([
+        {
+          type: "FIELD_REMOVED_REQUIRED",
+          field: "name",
+          message: "Required field 'name' was removed",
+        },
+      ]);
+    });
+
+    it("handles multiple simultaneous changes", () => {
+      const before = {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          age: { type: "string" },
+          email: { type: "string" },
+        },
+        required: ["name", "email"],
+      };
+      const after = {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          age: { type: "number" },
+          phone: { type: "string" },
+        },
+        required: ["name"],
+      };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toContainEqual({
+        type: "TYPE_CHANGED",
+        field: "age",
+        message: "Field 'age' type changed from 'string' to 'number'",
+        previousType: "string",
+        currentType: "number",
+      });
+      expect(changes).toContainEqual({
+        type: "FIELD_REMOVED_REQUIRED",
+        field: "email",
+        message: "Required field 'email' was removed",
+      });
+      expect(changes).toContainEqual({
+        type: "FIELD_ADDED_OPTIONAL",
+        field: "phone",
+        message: "Optional field 'phone' was added",
+      });
+      expect(changes).toHaveLength(3);
+    });
+
+    it("detects root-level type changes", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" } },
+      };
+      const after = { type: "array" };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toContainEqual({
+        type: "TYPE_CHANGED",
+        field: "(root)",
+        message: "Root type changed from 'object' to 'array'",
+        previousType: "object",
+        currentType: "array",
+      });
+    });
+
+    it("recurses into implicit object nodes (no explicit type)", () => {
+      const before = {
+        type: "object",
+        properties: {
+          address: {
+            properties: {
+              street: { type: "string" },
+              city: { type: "string" },
+            },
+            required: ["street"],
+          },
+        },
+      };
+      const after = {
+        type: "object",
+        properties: {
+          address: {
+            properties: {
+              street: { type: "string" },
+            },
+            required: ["street"],
+          },
+        },
+      };
+      const changes = diffJsonSchemas(before, after);
+      expect(changes).toEqual([
+        {
+          type: "FIELD_REMOVED_OPTIONAL",
+          field: "address.city",
+          message: "Optional field 'address.city' was removed",
+        },
+      ]);
+    });
+  });
+});
diff --git a/packages/breaking-changes/src/test/json-schema-rules.test.ts b/packages/breaking-changes/src/test/json-schema-rules.test.ts
new file mode 100644
index 000000000..cbd6f7cdb
--- /dev/null
+++ b/packages/breaking-changes/src/test/json-schema-rules.test.ts
@@ -0,0 +1,324 @@
+import { describe, it, expect } from "vitest";
+import { detectBreakingChanges } from "../json-schema/rules";
+import type { CompatibilityStrategy } from "../types";
+
+describe("detectBreakingChanges", () => {
+  const beforeSchema = {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      email: { type: "string" },
+    },
+    required: ["name", "email"],
+  };
+
+  describe("NONE strategy", () => {
+    it("never returns breaking changes regardless of schema diff", () => {
+      const after = { type: "object" };
+      const result = detectBreakingChanges(beforeSchema, after, "NONE");
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("BACKWARD strategy", () => {
+    it("adding an optional field is NOT breaking", () => {
+      const after = {
+        ...beforeSchema,
+        properties: { ...beforeSchema.properties, phone: { type: "string" } },
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "BACKWARD");
+      expect(result).toEqual([]);
+    });
+
+    it("adding a required field IS breaking", () => {
+      const after = {
+        type: "object",
+        properties: { ...beforeSchema.properties, phone: { type: "string" } },
+        required: ["name", "email", "phone"],
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "BACKWARD");
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe("FIELD_ADDED_REQUIRED");
+      expect(result[0].breaking).toBe(true);
+    });
+
+    it("removing a required field IS breaking", () => {
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "BACKWARD");
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe("FIELD_REMOVED_REQUIRED");
+    });
+
+    it("removing an optional field is NOT breaking", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" }, nickname: { type: "string" } },
+        required: ["name"],
+      };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+      };
+      const result = detectBreakingChanges(before, after, "BACKWARD");
+      expect(result).toEqual([]);
+    });
+
+    it("changing a field type IS breaking", () => {
+      const after = {
+        type: "object",
+        properties: { name: { type: "number" }, email: { type: "string" } },
+        required: ["name", "email"],
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "BACKWARD");
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe("TYPE_CHANGED");
+    });
+
+    it("making an optional field required IS breaking", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name"],
+      };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name", "email"],
+      };
+      const result = detectBreakingChanges(before, after, "BACKWARD");
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe("REQUIRED_ADDED");
+    });
+
+    it("making a required field optional is NOT breaking", () => {
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name"],
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "BACKWARD");
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("FORWARD strategy", () => {
+    it("adding a required field IS breaking", () => {
+      const after = {
+        type: "object",
+        properties: { ...beforeSchema.properties, phone: { type: "string" } },
+        required: ["name", "email", "phone"],
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "FORWARD");
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe("FIELD_ADDED_REQUIRED");
+    });
+
+    it("removing a required field IS breaking", () => {
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "FORWARD");
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe("FIELD_REMOVED_REQUIRED");
+    });
+
+    it("changing a field type IS breaking", () => {
+      const after = {
+        type: "object",
+        properties: { name: { type: "number" }, email: { type: "string" } },
+        required: ["name", "email"],
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "FORWARD");
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe("TYPE_CHANGED");
+    });
+
+    it("adding an optional field is NOT breaking", () => {
+      const after = {
+        ...beforeSchema,
+        properties: { ...beforeSchema.properties, phone: { type: "string" } },
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "FORWARD");
+      expect(result).toEqual([]);
+    });
+
+    it("removing an optional field is NOT breaking", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" }, nickname: { type: "string" } },
+        required: ["name"],
+      };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+      };
+      const result = detectBreakingChanges(before, after, "FORWARD");
+      expect(result).toEqual([]);
+    });
+
+    it("making an optional field required IS breaking", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name"],
+      };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name", "email"],
+      };
+      const result = detectBreakingChanges(before, after, "FORWARD");
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe("REQUIRED_ADDED");
+    });
+
+    it("making a required field optional is NOT breaking", () => {
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name"],
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "FORWARD");
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("FULL strategy", () => {
+    it("adding a required field IS breaking", () => {
+      const after = {
+        type: "object",
+        properties: { ...beforeSchema.properties, phone: { type: "string" } },
+        required: ["name", "email", "phone"],
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "FULL");
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe("FIELD_ADDED_REQUIRED");
+    });
+
+    it("removing a required field IS breaking", () => {
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "FULL");
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe("FIELD_REMOVED_REQUIRED");
+    });
+
+    it("changing a field type IS breaking", () => {
+      const after = {
+        type: "object",
+        properties: { name: { type: "number" }, email: { type: "string" } },
+        required: ["name", "email"],
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "FULL");
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe("TYPE_CHANGED");
+    });
+
+    it("adding an optional field is NOT breaking", () => {
+      const after = {
+        ...beforeSchema,
+        properties: { ...beforeSchema.properties, phone: { type: "string" } },
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "FULL");
+      expect(result).toEqual([]);
+    });
+
+    it("removing an optional field is NOT breaking", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" }, nickname: { type: "string" } },
+        required: ["name"],
+      };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+      };
+      const result = detectBreakingChanges(before, after, "FULL");
+      expect(result).toEqual([]);
+    });
+
+    it("making an optional field required IS breaking", () => {
+      const before = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name"],
+      };
+      const after = {
+        type: "object",
+        properties: { name: { type: "string" }, email: { type: "string" } },
+        required: ["name", "email"],
+      };
+      const result = detectBreakingChanges(before, after, "FULL");
+      expect(result).toHaveLength(1);
+      expect(result[0].type).toBe("REQUIRED_ADDED");
+    });
+  });
+
+  describe("multiple breaking changes", () => {
+    it("returns all breaking changes in a single diff", () => {
+      const after = {
+        type: "object",
+        properties: { name: { type: "number" }, phone: { type: "string" } },
+        required: ["name", "phone"],
+      };
+      const result = detectBreakingChanges(beforeSchema, after, "BACKWARD");
+      expect(result.length).toBeGreaterThanOrEqual(2);
+      expect(result.every((c) => c.breaking === true)).toBe(true);
+    });
+  });
+
+  describe("nested schemas", () => {
+    it("detects breaking changes in nested fields", () => {
+      const before = {
+        type: "object",
+        properties: {
+          address: {
+            type: "object",
+            properties: {
+              street: { type: "string" },
+              city: { type: "string" },
+            },
+            required: ["street", "city"],
+          },
+        },
+      };
+      const after = {
+        type: "object",
+        properties: {
+          address: {
+            type: "object",
+            properties: { street: { type: "number" } },
+            required: ["street"],
+          },
+        },
+      };
+      const result = detectBreakingChanges(before, after, "BACKWARD");
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          type: "TYPE_CHANGED",
+          field: "address.street",
+          breaking: true,
+        }),
+      );
+      expect(result).toContainEqual(
+        expect.objectContaining({
+          type: "FIELD_REMOVED_REQUIRED",
+          field: "address.city",
+          breaking: true,
+        }),
+      );
+    });
+  });
+});
diff --git a/packages/breaking-changes/src/types.ts b/packages/breaking-changes/src/types.ts
new file mode 100644
index 000000000..9814e157c
--- /dev/null
+++ b/packages/breaking-changes/src/types.ts
@@ -0,0 +1,22 @@
+export type CompatibilityStrategy = "BACKWARD" | "FORWARD" | "FULL" | "NONE";
+
+export type SchemaChangeType =
+  | "FIELD_ADDED_REQUIRED"
+  | "FIELD_ADDED_OPTIONAL"
+  | "FIELD_REMOVED_REQUIRED"
+  | "FIELD_REMOVED_OPTIONAL"
+  | "TYPE_CHANGED"
+  | "REQUIRED_ADDED"
+  | "REQUIRED_REMOVED";
+
+export type SchemaChange = {
+  type: SchemaChangeType;
+  field: string;
+  message: string;
+  previousType?: string;
+  currentType?: string;
+};
+
+export type BreakingChange = SchemaChange & {
+  breaking: true;
+};
diff --git a/packages/breaking-changes/tsconfig.json b/packages/breaking-changes/tsconfig.json
new file mode 100644
index 000000000..2e6fb2b7a
--- /dev/null
+++ b/packages/breaking-changes/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "moduleResolution": "bundler"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/breaking-changes/tsup.config.ts b/packages/breaking-changes/tsup.config.ts
new file mode 100644
index 000000000..94d39e344
--- /dev/null
+++ b/packages/breaking-changes/tsup.config.ts
@@ -0,0 +1,11 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  shims: true,
+});
diff --git a/packages/breaking-changes/vitest.config.ts b/packages/breaking-changes/vitest.config.ts
new file mode 100644
index 000000000..7057c8f3c
--- /dev/null
+++ b/packages/breaking-changes/vitest.config.ts
@@ -0,0 +1,8 @@
+/// <reference types="vitest" />
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    testTimeout: 15_000,
+  },
+});
diff --git a/packages/cli/.claude/rules/sdk-cli-docs-sync.md b/packages/cli/.claude/rules/sdk-cli-docs-sync.md
new file mode 100644
index 000000000..4e9d15bed
--- /dev/null
+++ b/packages/cli/.claude/rules/sdk-cli-docs-sync.md
@@ -0,0 +1,37 @@
+# SDK and CLI Documentation Sync
+
+When any SDK function is **added**, **edited**, or **deleted** in this project, you must check and update the `src/cli-docs.ts` file to keep CLI documentation in sync.
+
+## What to check
+
+1. **New function added** → Add a corresponding entry to the `cliFunctions` array in `src/cli-docs.ts`
+2. **Function signature changed** → Update the `args` array for that function in `cli-docs.ts`
+3. **Function deleted** → Remove the corresponding entry from `cli-docs.ts`
+4. **Function renamed** → Update the `name` field in `cli-docs.ts`
+
+## Files to watch
+
+- `src/index.ts` - Main SDK exports
+- `src/events.ts`, `src/commands.ts`, `src/queries.ts`, etc. - Individual resource modules
+- `src/services.ts`, `src/domains.ts`, `src/channels.ts`
+- `src/teams.ts`, `src/users.ts`, `src/custom-docs.ts`
+- `src/entities.ts`, `src/data-stores.ts`, `src/data-products.ts`
+- `src/messages.ts`, `src/eventcatalog.ts`
+
+## CLI docs entry format
+
+Each function in `cli-docs.ts` should have:
+
+```typescript
+{
+  name: 'functionName',
+  description: 'What the function does',
+  category: 'Events' | 'Commands' | 'Services' | etc.,
+  args: [
+    { name: 'argName', type: 'string' | 'json' | 'boolean' | 'number', required: true/false, description: '...' }
+  ],
+  examples: [
+    { description: 'Example description', command: 'npx @eventcatalog/sdk functionName "arg1"' }
+  ]
+}
+```
diff --git a/packages/cli/.prettierrc b/packages/cli/.prettierrc
new file mode 100644
index 000000000..2fbe55cde
--- /dev/null
+++ b/packages/cli/.prettierrc
@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "printWidth": 130,
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true
+}
diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
new file mode 100644
index 000000000..33279a997
--- /dev/null
+++ b/packages/cli/CHANGELOG.md
@@ -0,0 +1,380 @@
+# @eventcatalog/cli
+
+## 0.6.12
+
+### Patch Changes
+
+- Updated dependencies [9949f9f]
+- Updated dependencies [d64cfab]
+  - @eventcatalog/sdk@2.25.0
+  - @eventcatalog/language-server@0.8.23
+
+## 0.6.12-beta.1
+
+### Patch Changes
+
+- Updated dependencies [9949f9f]
+  - @eventcatalog/sdk@2.25.0-beta.1
+  - @eventcatalog/language-server@0.8.23-beta.1
+
+## 0.6.12-beta.0
+
+### Patch Changes
+
+- Updated dependencies [d64cfab]
+  - @eventcatalog/sdk@2.25.0-beta.0
+  - @eventcatalog/language-server@0.8.23-beta.0
+
+## 0.6.11
+
+### Patch Changes
+
+- Updated dependencies [29dc055]
+  - @eventcatalog/sdk@2.24.2
+  - @eventcatalog/language-server@0.8.22
+
+## 0.6.10
+
+### Patch Changes
+
+- Updated dependencies [3334ab1]
+  - @eventcatalog/sdk@2.24.1
+  - @eventcatalog/language-server@0.8.21
+
+## 0.6.9
+
+### Patch Changes
+
+- Updated dependencies [6b7fc3c]
+  - @eventcatalog/sdk@2.24.0
+  - @eventcatalog/language-server@0.8.20
+
+## 0.6.8
+
+### Patch Changes
+
+- Updated dependencies [2801b3e]
+  - @eventcatalog/sdk@2.23.1
+  - @eventcatalog/language-server@0.8.19
+
+## 0.6.7
+
+### Patch Changes
+
+- Updated dependencies [3ad00ad]
+  - @eventcatalog/sdk@2.23.0
+  - @eventcatalog/language-server@0.8.18
+
+## 0.6.6
+
+### Patch Changes
+
+- Updated dependencies [50b38f6]
+  - @eventcatalog/sdk@2.22.0
+  - @eventcatalog/language-server@0.8.17
+
+## 0.6.5
+
+### Patch Changes
+
+- Updated dependencies [67940c4]
+  - @eventcatalog/sdk@2.21.2
+  - @eventcatalog/language-server@0.8.16
+
+## 0.6.4
+
+### Patch Changes
+
+- Updated dependencies [1c9c217]
+  - @eventcatalog/sdk@2.21.1
+  - @eventcatalog/language-server@0.8.15
+
+## 0.6.3
+
+### Patch Changes
+
+- Updated dependencies [3a7b096]
+  - @eventcatalog/sdk@2.21.0
+  - @eventcatalog/language-server@0.8.14
+
+## 0.6.2
+
+### Patch Changes
+
+- Updated dependencies [8f724a7]
+  - @eventcatalog/sdk@2.20.0
+  - @eventcatalog/language-server@0.8.13
+
+## 0.6.1
+
+### Patch Changes
+
+- Updated dependencies [52b4f24]
+  - @eventcatalog/sdk@2.19.0
+  - @eventcatalog/language-server@0.8.12
+
+## 0.6.0
+
+### Minor Changes
+
+- a3313f6: feat: add breaking schema change detection with governance webhooks
+
+  New `schema_breaking_change` governance trigger that detects breaking JSON Schema changes per compatibility strategy (BACKWARD, FORWARD, FULL, NONE). Users configure `compatibility.strategy` in governance.yaml and subscribe to breaking change webhooks with detailed diff information.
+
+### Patch Changes
+
+- Updated dependencies [a3313f6]
+  - @eventcatalog/breaking-changes@0.2.0
+
+## 0.5.11
+
+### Patch Changes
+
+- Updated dependencies [ee142e4]
+  - @eventcatalog/sdk@2.18.4
+  - @eventcatalog/language-server@0.8.11
+
+## 0.5.10
+
+### Patch Changes
+
+- Updated dependencies [88795d0]
+  - @eventcatalog/sdk@2.18.3
+  - @eventcatalog/language-server@0.8.10
+
+## 0.5.9
+
+### Patch Changes
+
+- Updated dependencies [4639ec3]
+  - @eventcatalog/sdk@2.18.2
+  - @eventcatalog/language-server@0.8.9
+
+## 0.5.8
+
+### Patch Changes
+
+- Updated dependencies [e2b0460]
+  - @eventcatalog/sdk@2.18.1
+  - @eventcatalog/language-server@0.8.8
+
+## 0.5.7
+
+### Patch Changes
+
+- Updated dependencies [913ca20]
+  - @eventcatalog/sdk@2.18.0
+  - @eventcatalog/language-server@0.8.7
+
+## 0.5.6
+
+### Patch Changes
+
+- Updated dependencies [83aca74]
+  - @eventcatalog/sdk@2.17.4
+  - @eventcatalog/language-server@0.8.6
+
+## 0.5.5
+
+### Patch Changes
+
+- 21c8095: Add `type: fail` governance action to block CI/CD pipelines when rules trigger. Supports optional `message` field with `$ENV_VAR` interpolation. Rules without a fail action continue to exit 0 (backward compatible).
+
+## 0.5.4
+
+### Patch Changes
+
+- Updated dependencies [46a2292]
+  - @eventcatalog/sdk@2.17.3
+  - @eventcatalog/language-server@0.8.5
+
+## 0.5.3
+
+### Patch Changes
+
+- Updated dependencies [0514bb1]
+  - @eventcatalog/sdk@2.17.2
+  - @eventcatalog/language-server@0.8.4
+
+## 0.5.2
+
+### Patch Changes
+
+- Updated dependencies [6456054]
+  - @eventcatalog/sdk@2.17.1
+  - @eventcatalog/language-server@0.8.3
+
+## 0.5.1
+
+### Patch Changes
+
+- 78bf2d4: Support governance.yml in addition to governance.yaml
+- bcef8cc: add message_deprecated governance trigger to notify teams when a producing service deprecates a message
+
+## 0.5.0
+
+### Minor Changes
+
+- af2d4f4: add architecture change detection with governance rules, catalog snapshots, and webhook notifications
+
+### Patch Changes
+
+- Updated dependencies [af2d4f4]
+  - @eventcatalog/sdk@2.17.0
+  - @eventcatalog/language-server@0.8.2
+
+## 0.4.11
+
+### Patch Changes
+
+- Updated dependencies [283c147]
+  - @eventcatalog/sdk@2.16.0
+  - @eventcatalog/language-server@0.8.1
+
+## 0.4.10
+
+### Patch Changes
+
+- Updated dependencies [a461a9b]
+  - @eventcatalog/language-server@0.8.0
+
+## 0.4.9
+
+### Patch Changes
+
+- Updated dependencies [b86daae]
+  - @eventcatalog/language-server@0.7.0
+
+## 0.4.8
+
+### Patch Changes
+
+- cb0235a: Replace playground.eventcatalog.dev URLs with compass.eventcatalog.dev
+- Updated dependencies [cb0235a]
+  - @eventcatalog/language-server@0.6.2
+
+## 0.4.7
+
+### Patch Changes
+
+- Updated dependencies [a43021e]
+  - @eventcatalog/language-server@0.6.1
+
+## 0.4.6
+
+### Patch Changes
+
+- Updated dependencies [b5bbb3d]
+  - @eventcatalog/sdk@2.15.1
+
+## 0.4.5
+
+### Patch Changes
+
+- Updated dependencies [2663850]
+  - @eventcatalog/language-server@0.6.0
+
+## 0.4.4
+
+### Patch Changes
+
+- Updated dependencies [a85a4d7]
+  - @eventcatalog/language-server@0.5.0
+
+## 0.4.3
+
+### Patch Changes
+
+- Updated dependencies [6122f93]
+  - @eventcatalog/language-server@0.4.1
+
+## 0.4.2
+
+### Patch Changes
+
+- e6a759e: Default container_type to 'database' when not specified in .ec file imports
+
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [7531be8]
+- Updated dependencies [a1c5012]
+- Updated dependencies [25acfdd]
+  - @eventcatalog/sdk@2.15.0
+  - @eventcatalog/language-server@0.4.0
+
+## 0.4.0
+
+### Minor Changes
+
+- cf7fcac: add DSL-managed key merging for import to preserve non-DSL frontmatter, fix deprecated/draft falsy value handling in compiler
+
+### Patch Changes
+
+- Updated dependencies [cf7fcac]
+- Updated dependencies [c4104a1]
+  - @eventcatalog/language-server@0.3.0
+
+## 0.3.4
+
+### Patch Changes
+
+- Updated dependencies [f3685b6]
+  - @eventcatalog/sdk@2.14.3
+
+## 0.3.3
+
+### Patch Changes
+
+- 6a4e582: Improve DSL import with container ref support, resource stubs, and cache upsert; add writes-to and reads-from compilation in the language server.
+- Updated dependencies [6a4e582]
+  - @eventcatalog/language-server@0.2.3
+  - @eventcatalog/sdk@2.14.2
+
+## 0.3.2
+
+### Patch Changes
+
+- d703923: Replace base64 logo blob with actual logo.png asset, add import DSL command, and improve compiler with nested output support and domain/subdomain service pointer generation
+- Updated dependencies [d703923]
+  - @eventcatalog/language-server@0.2.2
+
+## 0.3.1
+
+### Patch Changes
+
+- 69cb966: add in-memory file index cache to SDK for faster lookups, fix playground URL in CLI export
+- Updated dependencies [69cb966]
+  - @eventcatalog/sdk@2.14.1
+
+## 0.3.0
+
+### Minor Changes
+
+- c782129: Add CLI export command for exporting catalog resources to EventCatalog DSL (.ec) format. Supports single resource, bulk, and full catalog export with hydration, section grouping, and visualizer blocks. Fix getServices to ignore nested channels, containers, data-products, data-stores, and flows.
+- c782129: feat(cli): add export command for DSL (.ec) format
+
+### Patch Changes
+
+- Updated dependencies [c782129]
+- Updated dependencies [c782129]
+  - @eventcatalog/sdk@2.14.0
+
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [b466daf]
+  - @eventcatalog/sdk@2.13.2
+
+## 0.2.0
+
+### Minor Changes
+
+- 0b35904: Extract CLI into new @eventcatalog/cli package for cleaner separation of concerns. The SDK no longer bundles the CLI binary.
+
+### Patch Changes
+
+- Updated dependencies [0b35904]
+  - @eventcatalog/sdk@2.13.1
diff --git a/packages/cli/README.md b/packages/cli/README.md
new file mode 100644
index 000000000..ca97528c4
--- /dev/null
+++ b/packages/cli/README.md
@@ -0,0 +1,199 @@
+## @eventcatalog/cli
+
+Command-line interface for [EventCatalog](https://eventcatalog.dev). Import and export catalogs using the [EventCatalog DSL](https://www.eventcatalog.dev/docs/development/dsl/introduction), run SDK functions directly from your terminal, and automate your EventCatalog workflows.
+
+### Installation
+
+```sh
+npm i @eventcatalog/cli
+```
+
+### Running with npx (no installation required)
+
+```bash
+npx @eventcatalog/cli --dir <catalog-path> <command> [args...]
+```
+
+### Running after installation
+
+If you've installed the package, the `eventcatalog` command is available:
+
+```bash
+eventcatalog --dir <catalog-path> <command> [args...]
+```
+
+### Global Options
+
+| Option             | Description                    | Default                 |
+| ------------------ | ------------------------------ | ----------------------- |
+| `-d, --dir <path>` | Path to your catalog directory | `.` (current directory) |
+
+---
+
+### Commands
+
+#### `import` — Import DSL files into your catalog
+
+Parse `.ec` (EventCatalog DSL) files and write them as catalog resources (markdown + frontmatter).
+
+```bash
+eventcatalog import [files...] [options]
+```
+
+**Options:**
+
+| Option      | Description                                                  |
+| ----------- | ------------------------------------------------------------ |
+| `--stdin`   | Read DSL from stdin instead of files                         |
+| `--dry-run` | Preview changes without writing to disk                      |
+| `--flat`    | Write all resources at the top level (no nested directories) |
+| `--no-init` | Skip the interactive catalog scaffolding prompt              |
+
+**Examples:**
+
+```bash
+# Import a single DSL file
+eventcatalog import architecture.ec
+
+# Import multiple files
+eventcatalog import services.ec events.ec domains.ec
+
+# Pipe DSL from another tool
+cat architecture.ec | eventcatalog import --stdin
+
+# Preview what would change
+eventcatalog import architecture.ec --dry-run
+
+# Import without nesting services inside domains
+eventcatalog import architecture.ec --flat
+```
+
+**Behaviors:**
+
+- If no `eventcatalog.config.js` exists, you'll be prompted to scaffold a new catalog (skip with `--no-init`).
+- Importing a newer version of an existing resource automatically versions the old one.
+- Re-importing the same version overwrites the existing resource.
+- Referenced resources that aren't defined in the DSL (e.g., `sends event OrderCreated` without an inline body) are created as stubs at version `0.0.1`.
+- Existing resource locations are preserved — updates go to where the resource already lives.
+
+---
+
+#### `export` — Export catalog resources to DSL
+
+Convert catalog resources back into EventCatalog DSL (`.ec`) format.
+
+```bash
+eventcatalog export [options]
+```
+
+**Options:**
+
+| Option                | Description                                                                               |
+| --------------------- | ----------------------------------------------------------------------------------------- |
+| `--all`               | Export the entire catalog                                                                 |
+| `--resource <type>`   | Resource type to export (`event`, `command`, `query`, `service`, `domain`, `channel`)     |
+| `--id <id>`           | Export a specific resource by ID (requires `--resource`)                                  |
+| `--version <version>` | Export a specific version (requires `--resource` and `--id`)                              |
+| `--hydrate`           | Include referenced resources (e.g., messages referenced by a service)                     |
+| `--stdout`            | Print to stdout instead of writing a file                                                 |
+| `--playground`        | Open the exported DSL in the [EventCatalog Playground](https://compass.eventcatalog.dev/) |
+| `--output <path>`     | Custom output file path                                                                   |
+
+**Examples:**
+
+```bash
+# Export a single event
+eventcatalog export --resource event --id OrderCreated --stdout
+
+# Export all services with their referenced messages
+eventcatalog export --resource service --hydrate --stdout
+
+# Export the entire catalog to a file
+eventcatalog export --all --output catalog.ec
+
+# Export and open in the playground
+eventcatalog export --all --playground
+```
+
+---
+
+#### `list` — List available SDK functions
+
+Display all SDK functions organized by category (Events, Commands, Queries, Services, Domains, etc.).
+
+```bash
+eventcatalog list
+```
+
+---
+
+#### `<function>` — Run any SDK function
+
+Any unrecognized command is treated as an SDK function call. Output is JSON.
+
+```bash
+eventcatalog <function-name> [args...]
+```
+
+**Examples:**
+
+```bash
+# Get an event (latest version)
+eventcatalog --dir ./my-catalog getEvent "OrderCreated"
+
+# Get a specific version
+eventcatalog --dir ./my-catalog getEvent "OrderCreated" "1.0.0"
+
+# Get all events with options
+eventcatalog --dir ./my-catalog getEvents '{"latestOnly":true}'
+
+# Write an event
+eventcatalog --dir ./my-catalog writeEvent '{"id":"OrderCreated","name":"Order Created","version":"1.0.0","markdown":"# Order Created"}'
+
+# Get a service
+eventcatalog --dir ./my-catalog getService "InventoryService"
+
+# Add an event to a service
+eventcatalog --dir ./my-catalog addEventToService "InventoryService" "sends" '{"id":"OrderCreated","version":"1.0.0"}'
+```
+
+Run `eventcatalog list` to see all available functions.
+
+---
+
+### Piping and Composing
+
+Output from SDK functions is JSON, making it easy to pipe to tools like `jq`:
+
+```bash
+# Filter events by version
+eventcatalog --dir ./my-catalog getEvents | jq '.[] | select(.version == "1.0.0")'
+
+# Count total events
+eventcatalog --dir ./my-catalog getEvents | jq 'length'
+
+# Extract event IDs
+eventcatalog --dir ./my-catalog getEvents | jq '.[].id'
+```
+
+### Arguments Format
+
+Arguments are automatically parsed:
+
+- **JSON objects:** `'{"key":"value"}'` — parsed as object
+- **JSON arrays:** `'["item1","item2"]'` — parsed as array
+- **Booleans:** `true` or `false` — parsed as boolean
+- **Numbers:** `42` or `3.14` — parsed as number
+- **Strings:** anything else — kept as string
+
+### Documentation
+
+- [EventCatalog DSL](https://www.eventcatalog.dev/docs/development/dsl/introduction)
+- [SDK reference](https://www.eventcatalog.dev/docs/sdk)
+- [CLI documentation](https://www.eventcatalog.dev/docs/development/cli)
+
+## Enterprise support
+
+Interested in collaborating with us? Our offerings include dedicated support, priority assistance, feature development, custom integrations, and more.
+
+Find more details on our [services page](https://eventcatalog.dev/services).
diff --git a/packages/cli/package.json b/packages/cli/package.json
new file mode 100644
index 000000000..8657fa0a7
--- /dev/null
+++ b/packages/cli/package.json
@@ -0,0 +1,59 @@
+{
+  "name": "@eventcatalog/cli",
+  "version": "0.6.12",
+  "description": "CLI for EventCatalog",
+  "scripts": {
+    "build": "tsup",
+    "build:bin": "tsup",
+    "test": "vitest --run",
+    "test:ci": "vitest --run",
+    "bench:import-export": "node src/test/bench/import-export.benchmark.js",
+    "format": "prettier --write .",
+    "format:diff": "prettier --list-different ."
+  },
+  "bin": {
+    "eventcatalog": "./dist/cli/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "exports": {
+    "./cli-docs": {
+      "types": "./dist/cli-docs.d.ts",
+      "require": "./dist/cli-docs.js",
+      "import": "./dist/cli-docs.mjs"
+    }
+  },
+  "dependencies": {
+    "@eventcatalog/breaking-changes": "workspace:*",
+    "@eventcatalog/language-server": "workspace:*",
+    "@eventcatalog/sdk": "workspace:*",
+    "@eventcatalog/license": "^0.0.7",
+    "commander": "^12.0.0",
+    "dotenv": "^16.5.0",
+    "gray-matter": "^4.0.3",
+    "js-yaml": "^4.1.1",
+    "langium": "^3.3.1",
+    "open": "^11.0.0",
+    "semver": "^7.7.2"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.14.10",
+    "prettier": "^3.3.3",
+    "tsup": "^8.1.0",
+    "typescript": "^5.5.3",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/event-catalog/eventcatalog"
+  }
+}
diff --git a/packages/cli/src/cli-docs.ts b/packages/cli/src/cli-docs.ts
new file mode 100644
index 000000000..9d124685c
--- /dev/null
+++ b/packages/cli/src/cli-docs.ts
@@ -0,0 +1,1885 @@
+/**
+ * CLI Documentation Registry
+ *
+ * This file contains metadata for all SDK functions that can be called via the CLI.
+ * It is used to generate documentation for the EventCatalog website.
+ *
+ * @module cli-docs
+ */
+
+export interface CLIFunctionArg {
+  name: string;
+  type: 'string' | 'json' | 'boolean' | 'number';
+  required: boolean;
+  description: string;
+}
+
+export interface CLIFunctionExample {
+  description: string;
+  command: string;
+}
+
+export interface CLIFunctionDoc {
+  name: string;
+  description: string;
+  category: string;
+  args: CLIFunctionArg[];
+  examples: CLIFunctionExample[];
+}
+
+/**
+ * All CLI-callable functions with their documentation
+ */
+export const cliFunctions: CLIFunctionDoc[] = [
+  // ================================
+  //            Events
+  // ================================
+  {
+    name: 'getEvent',
+    description: 'Returns an event from EventCatalog by its ID',
+    category: 'Events',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the event to retrieve' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to retrieve (supports semver)' },
+      { name: 'options', type: 'json', required: false, description: 'Options object, e.g. {"attachSchema": true}' },
+    ],
+    examples: [
+      { description: 'Get the latest version of an event', command: 'npx @eventcatalog/cli getEvent "OrderCreated"' },
+      { description: 'Get a specific version', command: 'npx @eventcatalog/cli getEvent "OrderCreated" "1.0.0"' },
+      {
+        description: 'Get event with schema attached',
+        command: 'npx @eventcatalog/cli getEvent "OrderCreated" "1.0.0" \'{"attachSchema":true}\'',
+      },
+    ],
+  },
+  {
+    name: 'getEvents',
+    description: 'Returns all events from EventCatalog',
+    category: 'Events',
+    args: [
+      {
+        name: 'options',
+        type: 'json',
+        required: false,
+        description: 'Options object, e.g. {"latestOnly": true, "attachSchema": true}',
+      },
+    ],
+    examples: [
+      { description: 'Get all events', command: 'npx @eventcatalog/cli getEvents' },
+      { description: 'Get only latest versions', command: 'npx @eventcatalog/cli getEvents \'{"latestOnly":true}\'' },
+      {
+        description: 'Get all events with schemas',
+        command: 'npx @eventcatalog/cli getEvents \'{"latestOnly":true,"attachSchema":true}\'',
+      },
+    ],
+  },
+  {
+    name: 'writeEvent',
+    description: 'Writes an event to EventCatalog',
+    category: 'Events',
+    args: [
+      { name: 'event', type: 'json', required: true, description: 'Event object with id, name, version, and markdown' },
+      {
+        name: 'options',
+        type: 'json',
+        required: false,
+        description: 'Options: {path?, override?, versionExistingContent?, format?}',
+      },
+    ],
+    examples: [
+      {
+        description: 'Write a new event',
+        command:
+          'npx @eventcatalog/cli writeEvent \'{"id":"OrderCreated","name":"Order Created","version":"1.0.0","markdown":"# Order Created"}\'',
+      },
+      {
+        description: 'Write and version existing content',
+        command:
+          'npx @eventcatalog/cli writeEvent \'{"id":"OrderCreated","name":"Order Created","version":"2.0.0","markdown":"# Order Created v2"}\' \'{"versionExistingContent":true}\'',
+      },
+    ],
+  },
+  {
+    name: 'writeEventToService',
+    description: 'Writes an event to a specific service in EventCatalog',
+    category: 'Events',
+    args: [
+      { name: 'event', type: 'json', required: true, description: 'Event object with id, name, version, and markdown' },
+      { name: 'service', type: 'json', required: true, description: 'Service reference: {id, version?}' },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, format?, override?}' },
+    ],
+    examples: [
+      {
+        description: 'Write event to a service',
+        command:
+          'npx @eventcatalog/cli writeEventToService \'{"id":"InventoryUpdated","name":"Inventory Updated","version":"1.0.0","markdown":"# Inventory Updated"}\' \'{"id":"InventoryService"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmEvent',
+    description: 'Removes an event by its path',
+    category: 'Events',
+    args: [{ name: 'path', type: 'string', required: true, description: 'Path to the event, e.g. /InventoryAdjusted' }],
+    examples: [{ description: 'Remove an event by path', command: 'npx @eventcatalog/cli rmEvent "/InventoryAdjusted"' }],
+  },
+  {
+    name: 'rmEventById',
+    description: 'Removes an event by its ID',
+    category: 'Events',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the event to remove' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to remove' },
+    ],
+    examples: [
+      { description: 'Remove latest version', command: 'npx @eventcatalog/cli rmEventById "OrderCreated"' },
+      { description: 'Remove specific version', command: 'npx @eventcatalog/cli rmEventById "OrderCreated" "1.0.0"' },
+    ],
+  },
+  {
+    name: 'versionEvent',
+    description: 'Moves the current event to a versioned directory',
+    category: 'Events',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the event to version' }],
+    examples: [{ description: 'Version an event', command: 'npx @eventcatalog/cli versionEvent "OrderCreated"' }],
+  },
+  {
+    name: 'addFileToEvent',
+    description: 'Adds a file to an event',
+    category: 'Events',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the event' },
+      { name: 'file', type: 'json', required: true, description: 'File object: {content, fileName}' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to add file to' },
+    ],
+    examples: [
+      {
+        description: 'Add a file to an event',
+        command: 'npx @eventcatalog/cli addFileToEvent "OrderCreated" \'{"content":"# Schema","fileName":"schema.md"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addSchemaToEvent',
+    description: 'Adds a schema file to an event',
+    category: 'Events',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the event' },
+      { name: 'schema', type: 'json', required: true, description: 'Schema object: {schema, fileName}' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to add schema to' },
+    ],
+    examples: [
+      {
+        description: 'Add a JSON schema to an event',
+        command:
+          'npx @eventcatalog/cli addSchemaToEvent "OrderCreated" \'{"schema":"{\\"type\\":\\"object\\"}","fileName":"schema.json"}\'',
+      },
+    ],
+  },
+  {
+    name: 'eventHasVersion',
+    description: 'Checks if a specific version of an event exists',
+    category: 'Events',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the event' },
+      { name: 'version', type: 'string', required: true, description: 'Version to check (supports semver)' },
+    ],
+    examples: [
+      { description: 'Check if version exists', command: 'npx @eventcatalog/cli eventHasVersion "OrderCreated" "1.0.0"' },
+      { description: 'Check with semver range', command: 'npx @eventcatalog/cli eventHasVersion "OrderCreated" "1.0.x"' },
+    ],
+  },
+
+  // ================================
+  //            Commands
+  // ================================
+  {
+    name: 'getCommand',
+    description: 'Returns a command from EventCatalog by its ID',
+    category: 'Commands',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the command to retrieve' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to retrieve (supports semver)' },
+    ],
+    examples: [
+      { description: 'Get the latest command', command: 'npx @eventcatalog/cli getCommand "CreateOrder"' },
+      { description: 'Get a specific version', command: 'npx @eventcatalog/cli getCommand "CreateOrder" "1.0.0"' },
+    ],
+  },
+  {
+    name: 'getCommands',
+    description: 'Returns all commands from EventCatalog',
+    category: 'Commands',
+    args: [{ name: 'options', type: 'json', required: false, description: 'Options: {latestOnly?, attachSchema?}' }],
+    examples: [
+      { description: 'Get all commands', command: 'npx @eventcatalog/cli getCommands' },
+      { description: 'Get only latest versions', command: 'npx @eventcatalog/cli getCommands \'{"latestOnly":true}\'' },
+    ],
+  },
+  {
+    name: 'writeCommand',
+    description: 'Writes a command to EventCatalog',
+    category: 'Commands',
+    args: [
+      { name: 'command', type: 'json', required: true, description: 'Command object with id, name, version, and markdown' },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, override?, versionExistingContent?}' },
+    ],
+    examples: [
+      {
+        description: 'Write a new command',
+        command:
+          'npx @eventcatalog/cli writeCommand \'{"id":"CreateOrder","name":"Create Order","version":"1.0.0","markdown":"# Create Order"}\'',
+      },
+    ],
+  },
+  {
+    name: 'writeCommandToService',
+    description: 'Writes a command to a specific service',
+    category: 'Commands',
+    args: [
+      { name: 'command', type: 'json', required: true, description: 'Command object' },
+      { name: 'service', type: 'json', required: true, description: 'Service reference: {id, version?}' },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, format?, override?}' },
+    ],
+    examples: [
+      {
+        description: 'Write command to a service',
+        command:
+          'npx @eventcatalog/cli writeCommandToService \'{"id":"UpdateInventory","name":"Update Inventory","version":"1.0.0","markdown":"# Update Inventory"}\' \'{"id":"InventoryService"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmCommand',
+    description: 'Removes a command by its path',
+    category: 'Commands',
+    args: [{ name: 'path', type: 'string', required: true, description: 'Path to the command' }],
+    examples: [{ description: 'Remove a command', command: 'npx @eventcatalog/cli rmCommand "/CreateOrder"' }],
+  },
+  {
+    name: 'rmCommandById',
+    description: 'Removes a command by its ID',
+    category: 'Commands',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the command to remove' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to remove' },
+    ],
+    examples: [{ description: 'Remove a command', command: 'npx @eventcatalog/cli rmCommandById "CreateOrder"' }],
+  },
+  {
+    name: 'versionCommand',
+    description: 'Moves the current command to a versioned directory',
+    category: 'Commands',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the command to version' }],
+    examples: [{ description: 'Version a command', command: 'npx @eventcatalog/cli versionCommand "CreateOrder"' }],
+  },
+  {
+    name: 'addFileToCommand',
+    description: 'Adds a file to a command',
+    category: 'Commands',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the command' },
+      { name: 'file', type: 'json', required: true, description: 'File object: {content, fileName}' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version' },
+    ],
+    examples: [
+      {
+        description: 'Add a file to a command',
+        command: 'npx @eventcatalog/cli addFileToCommand "CreateOrder" \'{"content":"# Notes","fileName":"notes.md"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addSchemaToCommand',
+    description: 'Adds a schema to a command',
+    category: 'Commands',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the command' },
+      { name: 'schema', type: 'json', required: true, description: 'Schema object: {schema, fileName}' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version' },
+    ],
+    examples: [
+      {
+        description: 'Add a schema to a command',
+        command:
+          'npx @eventcatalog/cli addSchemaToCommand "CreateOrder" \'{"schema":"{\\"type\\":\\"object\\"}","fileName":"schema.json"}\'',
+      },
+    ],
+  },
+  {
+    name: 'commandHasVersion',
+    description: 'Checks if a specific version of a command exists',
+    category: 'Commands',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the command' },
+      { name: 'version', type: 'string', required: true, description: 'Version to check' },
+    ],
+    examples: [
+      { description: 'Check if version exists', command: 'npx @eventcatalog/cli commandHasVersion "CreateOrder" "1.0.0"' },
+    ],
+  },
+
+  // ================================
+  //            Queries
+  // ================================
+  {
+    name: 'getQuery',
+    description: 'Returns a query from EventCatalog by its ID',
+    category: 'Queries',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the query to retrieve' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to retrieve' },
+    ],
+    examples: [
+      { description: 'Get the latest query', command: 'npx @eventcatalog/cli getQuery "GetOrder"' },
+      { description: 'Get a specific version', command: 'npx @eventcatalog/cli getQuery "GetOrder" "1.0.0"' },
+    ],
+  },
+  {
+    name: 'getQueries',
+    description: 'Returns all queries from EventCatalog',
+    category: 'Queries',
+    args: [{ name: 'options', type: 'json', required: false, description: 'Options: {latestOnly?, attachSchema?}' }],
+    examples: [
+      { description: 'Get all queries', command: 'npx @eventcatalog/cli getQueries' },
+      { description: 'Get only latest versions', command: 'npx @eventcatalog/cli getQueries \'{"latestOnly":true}\'' },
+    ],
+  },
+  {
+    name: 'writeQuery',
+    description: 'Writes a query to EventCatalog',
+    category: 'Queries',
+    args: [
+      { name: 'query', type: 'json', required: true, description: 'Query object with id, name, version, and markdown' },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, override?, versionExistingContent?}' },
+    ],
+    examples: [
+      {
+        description: 'Write a new query',
+        command:
+          'npx @eventcatalog/cli writeQuery \'{"id":"GetOrder","name":"Get Order","version":"1.0.0","markdown":"# Get Order"}\'',
+      },
+    ],
+  },
+  {
+    name: 'writeQueryToService',
+    description: 'Writes a query to a specific service',
+    category: 'Queries',
+    args: [
+      { name: 'query', type: 'json', required: true, description: 'Query object' },
+      { name: 'service', type: 'json', required: true, description: 'Service reference: {id, version?}' },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, format?, override?}' },
+    ],
+    examples: [
+      {
+        description: 'Write query to a service',
+        command:
+          'npx @eventcatalog/cli writeQueryToService \'{"id":"GetInventory","name":"Get Inventory","version":"1.0.0","markdown":"# Get Inventory"}\' \'{"id":"InventoryService"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmQuery',
+    description: 'Removes a query by its path',
+    category: 'Queries',
+    args: [{ name: 'path', type: 'string', required: true, description: 'Path to the query' }],
+    examples: [{ description: 'Remove a query', command: 'npx @eventcatalog/cli rmQuery "/GetOrder"' }],
+  },
+  {
+    name: 'rmQueryById',
+    description: 'Removes a query by its ID',
+    category: 'Queries',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the query to remove' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to remove' },
+    ],
+    examples: [{ description: 'Remove a query', command: 'npx @eventcatalog/cli rmQueryById "GetOrder"' }],
+  },
+  {
+    name: 'versionQuery',
+    description: 'Moves the current query to a versioned directory',
+    category: 'Queries',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the query to version' }],
+    examples: [{ description: 'Version a query', command: 'npx @eventcatalog/cli versionQuery "GetOrder"' }],
+  },
+  {
+    name: 'addFileToQuery',
+    description: 'Adds a file to a query',
+    category: 'Queries',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the query' },
+      { name: 'file', type: 'json', required: true, description: 'File object: {content, fileName}' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version' },
+    ],
+    examples: [
+      {
+        description: 'Add a file to a query',
+        command: 'npx @eventcatalog/cli addFileToQuery "GetOrder" \'{"content":"# Notes","fileName":"notes.md"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addSchemaToQuery',
+    description: 'Adds a schema to a query',
+    category: 'Queries',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the query' },
+      { name: 'schema', type: 'json', required: true, description: 'Schema object: {schema, fileName}' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version' },
+    ],
+    examples: [
+      {
+        description: 'Add a schema to a query',
+        command:
+          'npx @eventcatalog/cli addSchemaToQuery "GetOrder" \'{"schema":"{\\"type\\":\\"object\\"}","fileName":"schema.json"}\'',
+      },
+    ],
+  },
+  {
+    name: 'queryHasVersion',
+    description: 'Checks if a specific version of a query exists',
+    category: 'Queries',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the query' },
+      { name: 'version', type: 'string', required: true, description: 'Version to check' },
+    ],
+    examples: [{ description: 'Check if version exists', command: 'npx @eventcatalog/cli queryHasVersion "GetOrder" "1.0.0"' }],
+  },
+
+  // ================================
+  //            Services
+  // ================================
+  {
+    name: 'getService',
+    description: 'Returns a service from EventCatalog by its ID',
+    category: 'Services',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the service to retrieve' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to retrieve' },
+    ],
+    examples: [
+      { description: 'Get the latest service', command: 'npx @eventcatalog/cli getService "OrderService"' },
+      { description: 'Get a specific version', command: 'npx @eventcatalog/cli getService "OrderService" "1.0.0"' },
+    ],
+  },
+  {
+    name: 'getServices',
+    description: 'Returns all services from EventCatalog',
+    category: 'Services',
+    args: [{ name: 'options', type: 'json', required: false, description: 'Options: {latestOnly?}' }],
+    examples: [
+      { description: 'Get all services', command: 'npx @eventcatalog/cli getServices' },
+      { description: 'Get only latest versions', command: 'npx @eventcatalog/cli getServices \'{"latestOnly":true}\'' },
+    ],
+  },
+  {
+    name: 'writeService',
+    description: 'Writes a service to EventCatalog',
+    category: 'Services',
+    args: [
+      { name: 'service', type: 'json', required: true, description: 'Service object with id, name, version, and markdown' },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, override?, versionExistingContent?}' },
+    ],
+    examples: [
+      {
+        description: 'Write a new service',
+        command:
+          'npx @eventcatalog/cli writeService \'{"id":"OrderService","name":"Order Service","version":"1.0.0","markdown":"# Order Service"}\'',
+      },
+    ],
+  },
+  {
+    name: 'writeServiceToDomain',
+    description: 'Writes a service to a specific domain',
+    category: 'Services',
+    args: [
+      { name: 'service', type: 'json', required: true, description: 'Service object' },
+      { name: 'domain', type: 'json', required: true, description: 'Domain reference: {id, version?}' },
+      { name: 'options', type: 'json', required: false, description: 'Options' },
+    ],
+    examples: [
+      {
+        description: 'Write service to a domain',
+        command:
+          'npx @eventcatalog/cli writeServiceToDomain \'{"id":"PaymentService","name":"Payment Service","version":"1.0.0","markdown":"# Payment Service"}\' \'{"id":"Payments"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmService',
+    description: 'Removes a service by its path',
+    category: 'Services',
+    args: [{ name: 'path', type: 'string', required: true, description: 'Path to the service' }],
+    examples: [{ description: 'Remove a service', command: 'npx @eventcatalog/cli rmService "/OrderService"' }],
+  },
+  {
+    name: 'rmServiceById',
+    description: 'Removes a service by its ID',
+    category: 'Services',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the service to remove' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to remove' },
+    ],
+    examples: [{ description: 'Remove a service', command: 'npx @eventcatalog/cli rmServiceById "OrderService"' }],
+  },
+  {
+    name: 'versionService',
+    description: 'Moves the current service to a versioned directory',
+    category: 'Services',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the service to version' }],
+    examples: [{ description: 'Version a service', command: 'npx @eventcatalog/cli versionService "OrderService"' }],
+  },
+  {
+    name: 'addFileToService',
+    description: 'Adds a file to a service',
+    category: 'Services',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the service' },
+      { name: 'file', type: 'json', required: true, description: 'File object: {content, fileName}' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version' },
+    ],
+    examples: [
+      {
+        description: 'Add a file to a service',
+        command: 'npx @eventcatalog/cli addFileToService "OrderService" \'{"content":"# API Docs","fileName":"api.md"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addEventToService',
+    description: 'Adds an event relationship to a service',
+    category: 'Services',
+    args: [
+      { name: 'serviceId', type: 'string', required: true, description: 'The ID of the service' },
+      { name: 'direction', type: 'string', required: true, description: 'Direction: "sends" or "receives"' },
+      { name: 'event', type: 'json', required: true, description: 'Event reference: {id, version}' },
+      { name: 'serviceVersion', type: 'string', required: false, description: 'Specific service version' },
+    ],
+    examples: [
+      {
+        description: 'Add event that service sends',
+        command: 'npx @eventcatalog/cli addEventToService "OrderService" "sends" \'{"id":"OrderCreated","version":"1.0.0"}\'',
+      },
+      {
+        description: 'Add event that service receives',
+        command:
+          'npx @eventcatalog/cli addEventToService "OrderService" "receives" \'{"id":"PaymentCompleted","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addCommandToService',
+    description: 'Adds a command relationship to a service',
+    category: 'Services',
+    args: [
+      { name: 'serviceId', type: 'string', required: true, description: 'The ID of the service' },
+      { name: 'direction', type: 'string', required: true, description: 'Direction: "sends" or "receives"' },
+      { name: 'command', type: 'json', required: true, description: 'Command reference: {id, version}' },
+      { name: 'serviceVersion', type: 'string', required: false, description: 'Specific service version' },
+    ],
+    examples: [
+      {
+        description: 'Add command that service sends',
+        command: 'npx @eventcatalog/cli addCommandToService "OrderService" "sends" \'{"id":"ProcessPayment","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addQueryToService',
+    description: 'Adds a query relationship to a service',
+    category: 'Services',
+    args: [
+      { name: 'serviceId', type: 'string', required: true, description: 'The ID of the service' },
+      { name: 'direction', type: 'string', required: true, description: 'Direction: "sends" or "receives"' },
+      { name: 'query', type: 'json', required: true, description: 'Query reference: {id, version}' },
+      { name: 'serviceVersion', type: 'string', required: false, description: 'Specific service version' },
+    ],
+    examples: [
+      {
+        description: 'Add query that service sends',
+        command: 'npx @eventcatalog/cli addQueryToService "OrderService" "sends" \'{"id":"GetInventory","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addEntityToService',
+    description: 'Adds an entity to a service',
+    category: 'Services',
+    args: [
+      { name: 'serviceId', type: 'string', required: true, description: 'The ID of the service' },
+      { name: 'entity', type: 'json', required: true, description: 'Entity reference: {id, version}' },
+      { name: 'serviceVersion', type: 'string', required: false, description: 'Specific service version' },
+    ],
+    examples: [
+      {
+        description: 'Add entity to a service',
+        command: 'npx @eventcatalog/cli addEntityToService "OrderService" \'{"id":"Order","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addDataStoreToService',
+    description: 'Adds a data store relationship to a service',
+    category: 'Services',
+    args: [
+      { name: 'serviceId', type: 'string', required: true, description: 'The ID of the service' },
+      { name: 'relationship', type: 'string', required: true, description: 'Relationship: "writesTo" or "readsFrom"' },
+      { name: 'dataStore', type: 'json', required: true, description: 'Data store reference: {id, version}' },
+      { name: 'serviceVersion', type: 'string', required: false, description: 'Specific service version' },
+    ],
+    examples: [
+      {
+        description: 'Add data store that service writes to',
+        command: 'npx @eventcatalog/cli addDataStoreToService "OrderService" "writesTo" \'{"id":"orders-db","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'serviceHasVersion',
+    description: 'Checks if a specific version of a service exists',
+    category: 'Services',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the service' },
+      { name: 'version', type: 'string', required: true, description: 'Version to check' },
+    ],
+    examples: [
+      { description: 'Check if version exists', command: 'npx @eventcatalog/cli serviceHasVersion "OrderService" "1.0.0"' },
+    ],
+  },
+  {
+    name: 'getSpecificationFilesForService',
+    description: 'Returns specification files (OpenAPI, AsyncAPI) for a service',
+    category: 'Services',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the service' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version' },
+    ],
+    examples: [
+      { description: 'Get spec files', command: 'npx @eventcatalog/cli getSpecificationFilesForService "OrderService"' },
+    ],
+  },
+
+  // ================================
+  //            Domains
+  // ================================
+  {
+    name: 'getDomain',
+    description: 'Returns a domain from EventCatalog by its ID',
+    category: 'Domains',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the domain to retrieve' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to retrieve' },
+    ],
+    examples: [
+      { description: 'Get the latest domain', command: 'npx @eventcatalog/cli getDomain "Orders"' },
+      { description: 'Get a specific version', command: 'npx @eventcatalog/cli getDomain "Orders" "1.0.0"' },
+    ],
+  },
+  {
+    name: 'getDomains',
+    description: 'Returns all domains from EventCatalog',
+    category: 'Domains',
+    args: [{ name: 'options', type: 'json', required: false, description: 'Options: {latestOnly?}' }],
+    examples: [
+      { description: 'Get all domains', command: 'npx @eventcatalog/cli getDomains' },
+      { description: 'Get only latest versions', command: 'npx @eventcatalog/cli getDomains \'{"latestOnly":true}\'' },
+    ],
+  },
+  {
+    name: 'writeDomain',
+    description: 'Writes a domain to EventCatalog',
+    category: 'Domains',
+    args: [
+      { name: 'domain', type: 'json', required: true, description: 'Domain object with id, name, version, and markdown' },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, override?, versionExistingContent?}' },
+    ],
+    examples: [
+      {
+        description: 'Write a new domain',
+        command:
+          'npx @eventcatalog/cli writeDomain \'{"id":"Orders","name":"Orders Domain","version":"1.0.0","markdown":"# Orders Domain"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmDomain',
+    description: 'Removes a domain by its path',
+    category: 'Domains',
+    args: [{ name: 'path', type: 'string', required: true, description: 'Path to the domain' }],
+    examples: [{ description: 'Remove a domain', command: 'npx @eventcatalog/cli rmDomain "/Orders"' }],
+  },
+  {
+    name: 'rmDomainById',
+    description: 'Removes a domain by its ID',
+    category: 'Domains',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the domain to remove' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to remove' },
+    ],
+    examples: [{ description: 'Remove a domain', command: 'npx @eventcatalog/cli rmDomainById "Orders"' }],
+  },
+  {
+    name: 'versionDomain',
+    description: 'Moves the current domain to a versioned directory',
+    category: 'Domains',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the domain to version' }],
+    examples: [{ description: 'Version a domain', command: 'npx @eventcatalog/cli versionDomain "Orders"' }],
+  },
+  {
+    name: 'addFileToDomain',
+    description: 'Adds a file to a domain',
+    category: 'Domains',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the domain' },
+      { name: 'file', type: 'json', required: true, description: 'File object: {content, fileName}' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version' },
+    ],
+    examples: [
+      {
+        description: 'Add a file to a domain',
+        command: 'npx @eventcatalog/cli addFileToDomain "Orders" \'{"content":"# Overview","fileName":"overview.md"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addServiceToDomain',
+    description: 'Adds a service to a domain',
+    category: 'Domains',
+    args: [
+      { name: 'domainId', type: 'string', required: true, description: 'The ID of the domain' },
+      { name: 'service', type: 'json', required: true, description: 'Service reference: {id, version}' },
+      { name: 'domainVersion', type: 'string', required: false, description: 'Specific domain version' },
+    ],
+    examples: [
+      {
+        description: 'Add service to domain',
+        command: 'npx @eventcatalog/cli addServiceToDomain "Orders" \'{"id":"OrderService","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addSubDomainToDomain',
+    description: 'Adds a subdomain to a domain',
+    category: 'Domains',
+    args: [
+      { name: 'domainId', type: 'string', required: true, description: 'The ID of the parent domain' },
+      { name: 'subDomain', type: 'json', required: true, description: 'Subdomain reference: {id, version}' },
+      { name: 'domainVersion', type: 'string', required: false, description: 'Specific domain version' },
+    ],
+    examples: [
+      {
+        description: 'Add subdomain',
+        command: 'npx @eventcatalog/cli addSubDomainToDomain "Orders" \'{"id":"Fulfillment","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addEntityToDomain',
+    description: 'Adds an entity to a domain',
+    category: 'Domains',
+    args: [
+      { name: 'domainId', type: 'string', required: true, description: 'The ID of the domain' },
+      { name: 'entity', type: 'json', required: true, description: 'Entity reference: {id, version}' },
+      { name: 'domainVersion', type: 'string', required: false, description: 'Specific domain version' },
+    ],
+    examples: [
+      {
+        description: 'Add entity to domain',
+        command: 'npx @eventcatalog/cli addEntityToDomain "Orders" \'{"id":"Order","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addEventToDomain',
+    description: 'Adds an event relationship to a domain',
+    category: 'Domains',
+    args: [
+      { name: 'domainId', type: 'string', required: true, description: 'The ID of the domain' },
+      { name: 'direction', type: 'string', required: true, description: 'Direction: "sends" or "receives"' },
+      { name: 'event', type: 'json', required: true, description: 'Event reference: {id, version}' },
+      { name: 'domainVersion', type: 'string', required: false, description: 'Specific domain version' },
+    ],
+    examples: [
+      {
+        description: 'Add event that domain sends',
+        command: 'npx @eventcatalog/cli addEventToDomain "Orders" "sends" \'{"id":"OrderCreated","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addCommandToDomain',
+    description: 'Adds a command relationship to a domain',
+    category: 'Domains',
+    args: [
+      { name: 'domainId', type: 'string', required: true, description: 'The ID of the domain' },
+      { name: 'direction', type: 'string', required: true, description: 'Direction: "sends" or "receives"' },
+      { name: 'command', type: 'json', required: true, description: 'Command reference: {id, version}' },
+      { name: 'domainVersion', type: 'string', required: false, description: 'Specific domain version' },
+    ],
+    examples: [
+      {
+        description: 'Add command that domain sends',
+        command: 'npx @eventcatalog/cli addCommandToDomain "Orders" "sends" \'{"id":"ProcessOrder","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addQueryToDomain',
+    description: 'Adds a query relationship to a domain',
+    category: 'Domains',
+    args: [
+      { name: 'domainId', type: 'string', required: true, description: 'The ID of the domain' },
+      { name: 'direction', type: 'string', required: true, description: 'Direction: "sends" or "receives"' },
+      { name: 'query', type: 'json', required: true, description: 'Query reference: {id, version}' },
+      { name: 'domainVersion', type: 'string', required: false, description: 'Specific domain version' },
+    ],
+    examples: [
+      {
+        description: 'Add query that domain sends',
+        command: 'npx @eventcatalog/cli addQueryToDomain "Orders" "sends" \'{"id":"GetOrderStatus","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addUbiquitousLanguageToDomain',
+    description: 'Adds ubiquitous language definitions to a domain',
+    category: 'Domains',
+    args: [
+      { name: 'domainId', type: 'string', required: true, description: 'The ID of the domain' },
+      { name: 'dictionary', type: 'json', required: true, description: 'Array of {term, definition} objects' },
+      { name: 'domainVersion', type: 'string', required: false, description: 'Specific domain version' },
+    ],
+    examples: [
+      {
+        description: 'Add ubiquitous language',
+        command:
+          'npx @eventcatalog/cli addUbiquitousLanguageToDomain "Orders" \'[{"term":"Order","definition":"A customer purchase request"}]\'',
+      },
+    ],
+  },
+  {
+    name: 'getUbiquitousLanguageFromDomain',
+    description: 'Gets ubiquitous language definitions from a domain',
+    category: 'Domains',
+    args: [
+      { name: 'domainId', type: 'string', required: true, description: 'The ID of the domain' },
+      { name: 'domainVersion', type: 'string', required: false, description: 'Specific domain version' },
+    ],
+    examples: [
+      { description: 'Get ubiquitous language', command: 'npx @eventcatalog/cli getUbiquitousLanguageFromDomain "Orders"' },
+    ],
+  },
+  {
+    name: 'domainHasVersion',
+    description: 'Checks if a specific version of a domain exists',
+    category: 'Domains',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the domain' },
+      { name: 'version', type: 'string', required: true, description: 'Version to check' },
+    ],
+    examples: [{ description: 'Check if version exists', command: 'npx @eventcatalog/cli domainHasVersion "Orders" "1.0.0"' }],
+  },
+
+  // ================================
+  //            Channels
+  // ================================
+  {
+    name: 'getChannel',
+    description: 'Returns a channel from EventCatalog by its ID',
+    category: 'Channels',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the channel to retrieve' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to retrieve' },
+    ],
+    examples: [
+      { description: 'Get the latest channel', command: 'npx @eventcatalog/cli getChannel "orders.events"' },
+      { description: 'Get a specific version', command: 'npx @eventcatalog/cli getChannel "orders.events" "1.0.0"' },
+    ],
+  },
+  {
+    name: 'getChannels',
+    description: 'Returns all channels from EventCatalog',
+    category: 'Channels',
+    args: [{ name: 'options', type: 'json', required: false, description: 'Options: {latestOnly?}' }],
+    examples: [
+      { description: 'Get all channels', command: 'npx @eventcatalog/cli getChannels' },
+      { description: 'Get only latest versions', command: 'npx @eventcatalog/cli getChannels \'{"latestOnly":true}\'' },
+    ],
+  },
+  {
+    name: 'writeChannel',
+    description: 'Writes a channel to EventCatalog',
+    category: 'Channels',
+    args: [
+      { name: 'channel', type: 'json', required: true, description: 'Channel object with id, name, version, and markdown' },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, override?}' },
+    ],
+    examples: [
+      {
+        description: 'Write a new channel',
+        command:
+          'npx @eventcatalog/cli writeChannel \'{"id":"orders.events","name":"Orders Events","version":"1.0.0","markdown":"# Orders Events Channel"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmChannel',
+    description: 'Removes a channel by its path',
+    category: 'Channels',
+    args: [{ name: 'path', type: 'string', required: true, description: 'Path to the channel' }],
+    examples: [{ description: 'Remove a channel', command: 'npx @eventcatalog/cli rmChannel "/orders.events"' }],
+  },
+  {
+    name: 'rmChannelById',
+    description: 'Removes a channel by its ID',
+    category: 'Channels',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the channel to remove' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to remove' },
+    ],
+    examples: [{ description: 'Remove a channel', command: 'npx @eventcatalog/cli rmChannelById "orders.events"' }],
+  },
+  {
+    name: 'versionChannel',
+    description: 'Moves the current channel to a versioned directory',
+    category: 'Channels',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the channel to version' }],
+    examples: [{ description: 'Version a channel', command: 'npx @eventcatalog/cli versionChannel "orders.events"' }],
+  },
+  {
+    name: 'addEventToChannel',
+    description: 'Adds an event to a channel',
+    category: 'Channels',
+    args: [
+      { name: 'channelId', type: 'string', required: true, description: 'The ID of the channel' },
+      { name: 'event', type: 'json', required: true, description: 'Event reference: {id, version, parameters?}' },
+    ],
+    examples: [
+      {
+        description: 'Add event to channel',
+        command: 'npx @eventcatalog/cli addEventToChannel "orders.events" \'{"id":"OrderCreated","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addCommandToChannel',
+    description: 'Adds a command to a channel',
+    category: 'Channels',
+    args: [
+      { name: 'channelId', type: 'string', required: true, description: 'The ID of the channel' },
+      { name: 'command', type: 'json', required: true, description: 'Command reference: {id, version, parameters?}' },
+    ],
+    examples: [
+      {
+        description: 'Add command to channel',
+        command: 'npx @eventcatalog/cli addCommandToChannel "orders.commands" \'{"id":"CreateOrder","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addQueryToChannel',
+    description: 'Adds a query to a channel',
+    category: 'Channels',
+    args: [
+      { name: 'channelId', type: 'string', required: true, description: 'The ID of the channel' },
+      { name: 'query', type: 'json', required: true, description: 'Query reference: {id, version, parameters?}' },
+    ],
+    examples: [
+      {
+        description: 'Add query to channel',
+        command: 'npx @eventcatalog/cli addQueryToChannel "orders.queries" \'{"id":"GetOrder","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'channelHasVersion',
+    description: 'Checks if a specific version of a channel exists',
+    category: 'Channels',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the channel' },
+      { name: 'version', type: 'string', required: true, description: 'Version to check' },
+    ],
+    examples: [
+      { description: 'Check if version exists', command: 'npx @eventcatalog/cli channelHasVersion "orders.events" "1.0.0"' },
+    ],
+  },
+
+  // ================================
+  //            Teams
+  // ================================
+  {
+    name: 'getTeam',
+    description: 'Returns a team from EventCatalog by its ID',
+    category: 'Teams',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the team to retrieve' }],
+    examples: [{ description: 'Get a team', command: 'npx @eventcatalog/cli getTeam "platform-team"' }],
+  },
+  {
+    name: 'getTeams',
+    description: 'Returns all teams from EventCatalog',
+    category: 'Teams',
+    args: [],
+    examples: [{ description: 'Get all teams', command: 'npx @eventcatalog/cli getTeams' }],
+  },
+  {
+    name: 'writeTeam',
+    description: 'Writes a team to EventCatalog',
+    category: 'Teams',
+    args: [
+      { name: 'team', type: 'json', required: true, description: 'Team object with id, name, and markdown' },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, override?}' },
+    ],
+    examples: [
+      {
+        description: 'Write a new team',
+        command: 'npx @eventcatalog/cli writeTeam \'{"id":"platform-team","name":"Platform Team","markdown":"# Platform Team"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmTeamById',
+    description: 'Removes a team by its ID',
+    category: 'Teams',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the team to remove' }],
+    examples: [{ description: 'Remove a team', command: 'npx @eventcatalog/cli rmTeamById "platform-team"' }],
+  },
+
+  // ================================
+  //            Users
+  // ================================
+  {
+    name: 'getUser',
+    description: 'Returns a user from EventCatalog by their ID',
+    category: 'Users',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the user to retrieve' }],
+    examples: [{ description: 'Get a user', command: 'npx @eventcatalog/cli getUser "jsmith"' }],
+  },
+  {
+    name: 'getUsers',
+    description: 'Returns all users from EventCatalog',
+    category: 'Users',
+    args: [],
+    examples: [{ description: 'Get all users', command: 'npx @eventcatalog/cli getUsers' }],
+  },
+  {
+    name: 'writeUser',
+    description: 'Writes a user to EventCatalog',
+    category: 'Users',
+    args: [
+      { name: 'user', type: 'json', required: true, description: 'User object with id, name, and markdown' },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, override?}' },
+    ],
+    examples: [
+      {
+        description: 'Write a new user',
+        command: 'npx @eventcatalog/cli writeUser \'{"id":"jsmith","name":"John Smith","markdown":"# John Smith"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmUserById',
+    description: 'Removes a user by their ID',
+    category: 'Users',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the user to remove' }],
+    examples: [{ description: 'Remove a user', command: 'npx @eventcatalog/cli rmUserById "jsmith"' }],
+  },
+
+  // ================================
+  //            Custom Docs
+  // ================================
+  {
+    name: 'getCustomDoc',
+    description: 'Returns a custom doc from EventCatalog by its path',
+    category: 'Custom Docs',
+    args: [{ name: 'path', type: 'string', required: true, description: 'Path to the custom doc' }],
+    examples: [{ description: 'Get a custom doc', command: 'npx @eventcatalog/cli getCustomDoc "/getting-started"' }],
+  },
+  {
+    name: 'getCustomDocs',
+    description: 'Returns all custom docs from EventCatalog',
+    category: 'Custom Docs',
+    args: [{ name: 'options', type: 'json', required: false, description: 'Options: {path?}' }],
+    examples: [
+      { description: 'Get all custom docs', command: 'npx @eventcatalog/cli getCustomDocs' },
+      { description: 'Get docs from a path', command: 'npx @eventcatalog/cli getCustomDocs \'{"path":"/guides"}\'' },
+    ],
+  },
+  {
+    name: 'writeCustomDoc',
+    description: 'Writes a custom doc to EventCatalog',
+    category: 'Custom Docs',
+    args: [
+      { name: 'customDoc', type: 'json', required: true, description: 'Custom doc object with id, title, and markdown' },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, override?}' },
+    ],
+    examples: [
+      {
+        description: 'Write a custom doc',
+        command:
+          'npx @eventcatalog/cli writeCustomDoc \'{"id":"getting-started","title":"Getting Started","markdown":"# Getting Started"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmCustomDoc',
+    description: 'Removes a custom doc by its path',
+    category: 'Custom Docs',
+    args: [{ name: 'path', type: 'string', required: true, description: 'Path to the custom doc to remove' }],
+    examples: [{ description: 'Remove a custom doc', command: 'npx @eventcatalog/cli rmCustomDoc "/getting-started"' }],
+  },
+
+  // ================================
+  //            Entities
+  // ================================
+  {
+    name: 'getEntity',
+    description: 'Returns an entity from EventCatalog by its ID',
+    category: 'Entities',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the entity to retrieve' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to retrieve' },
+    ],
+    examples: [
+      { description: 'Get the latest entity', command: 'npx @eventcatalog/cli getEntity "Order"' },
+      { description: 'Get a specific version', command: 'npx @eventcatalog/cli getEntity "Order" "1.0.0"' },
+    ],
+  },
+  {
+    name: 'getEntities',
+    description: 'Returns all entities from EventCatalog',
+    category: 'Entities',
+    args: [{ name: 'options', type: 'json', required: false, description: 'Options: {latestOnly?}' }],
+    examples: [
+      { description: 'Get all entities', command: 'npx @eventcatalog/cli getEntities' },
+      { description: 'Get only latest versions', command: 'npx @eventcatalog/cli getEntities \'{"latestOnly":true}\'' },
+    ],
+  },
+  {
+    name: 'writeEntity',
+    description: 'Writes an entity to EventCatalog',
+    category: 'Entities',
+    args: [
+      { name: 'entity', type: 'json', required: true, description: 'Entity object with id, name, version, and markdown' },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, override?, versionExistingContent?}' },
+    ],
+    examples: [
+      {
+        description: 'Write a new entity',
+        command:
+          'npx @eventcatalog/cli writeEntity \'{"id":"Order","name":"Order","version":"1.0.0","markdown":"# Order Entity"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmEntity',
+    description: 'Removes an entity by its path',
+    category: 'Entities',
+    args: [{ name: 'path', type: 'string', required: true, description: 'Path to the entity' }],
+    examples: [{ description: 'Remove an entity', command: 'npx @eventcatalog/cli rmEntity "/Order"' }],
+  },
+  {
+    name: 'rmEntityById',
+    description: 'Removes an entity by its ID',
+    category: 'Entities',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the entity to remove' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to remove' },
+    ],
+    examples: [{ description: 'Remove an entity', command: 'npx @eventcatalog/cli rmEntityById "Order"' }],
+  },
+  {
+    name: 'versionEntity',
+    description: 'Moves the current entity to a versioned directory',
+    category: 'Entities',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the entity to version' }],
+    examples: [{ description: 'Version an entity', command: 'npx @eventcatalog/cli versionEntity "Order"' }],
+  },
+  {
+    name: 'entityHasVersion',
+    description: 'Checks if a specific version of an entity exists',
+    category: 'Entities',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the entity' },
+      { name: 'version', type: 'string', required: true, description: 'Version to check' },
+    ],
+    examples: [{ description: 'Check if version exists', command: 'npx @eventcatalog/cli entityHasVersion "Order" "1.0.0"' }],
+  },
+
+  // ================================
+  //            Data Stores
+  // ================================
+  {
+    name: 'getDataStore',
+    description: 'Returns a data store from EventCatalog by its ID',
+    category: 'Data Stores',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the data store to retrieve' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to retrieve' },
+    ],
+    examples: [
+      { description: 'Get the latest data store', command: 'npx @eventcatalog/cli getDataStore "orders-db"' },
+      { description: 'Get a specific version', command: 'npx @eventcatalog/cli getDataStore "orders-db" "1.0.0"' },
+    ],
+  },
+  {
+    name: 'getDataStores',
+    description: 'Returns all data stores from EventCatalog',
+    category: 'Data Stores',
+    args: [{ name: 'options', type: 'json', required: false, description: 'Options: {latestOnly?}' }],
+    examples: [
+      { description: 'Get all data stores', command: 'npx @eventcatalog/cli getDataStores' },
+      { description: 'Get only latest versions', command: 'npx @eventcatalog/cli getDataStores \'{"latestOnly":true}\'' },
+    ],
+  },
+  {
+    name: 'writeDataStore',
+    description: 'Writes a data store to EventCatalog',
+    category: 'Data Stores',
+    args: [
+      {
+        name: 'dataStore',
+        type: 'json',
+        required: true,
+        description: 'Data store object with id, name, version, and markdown',
+      },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, override?, versionExistingContent?}' },
+    ],
+    examples: [
+      {
+        description: 'Write a new data store',
+        command:
+          'npx @eventcatalog/cli writeDataStore \'{"id":"orders-db","name":"Orders Database","version":"1.0.0","markdown":"# Orders Database"}\'',
+      },
+    ],
+  },
+  {
+    name: 'writeDataStoreToService',
+    description: 'Writes a data store to a specific service',
+    category: 'Data Stores',
+    args: [
+      { name: 'dataStore', type: 'json', required: true, description: 'Data store object' },
+      { name: 'service', type: 'json', required: true, description: 'Service reference: {id, version?}' },
+    ],
+    examples: [
+      {
+        description: 'Write data store to a service',
+        command:
+          'npx @eventcatalog/cli writeDataStoreToService \'{"id":"orders-db","name":"Orders Database","version":"1.0.0","markdown":"# Orders DB"}\' \'{"id":"OrderService"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmDataStore',
+    description: 'Removes a data store by its path',
+    category: 'Data Stores',
+    args: [{ name: 'path', type: 'string', required: true, description: 'Path to the data store' }],
+    examples: [{ description: 'Remove a data store', command: 'npx @eventcatalog/cli rmDataStore "/orders-db"' }],
+  },
+  {
+    name: 'rmDataStoreById',
+    description: 'Removes a data store by its ID',
+    category: 'Data Stores',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the data store to remove' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to remove' },
+    ],
+    examples: [{ description: 'Remove a data store', command: 'npx @eventcatalog/cli rmDataStoreById "orders-db"' }],
+  },
+  {
+    name: 'versionDataStore',
+    description: 'Moves the current data store to a versioned directory',
+    category: 'Data Stores',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the data store to version' }],
+    examples: [{ description: 'Version a data store', command: 'npx @eventcatalog/cli versionDataStore "orders-db"' }],
+  },
+  {
+    name: 'addFileToDataStore',
+    description: 'Adds a file to a data store',
+    category: 'Data Stores',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the data store' },
+      { name: 'file', type: 'json', required: true, description: 'File object: {content, fileName}' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version' },
+    ],
+    examples: [
+      {
+        description: 'Add a file to a data store',
+        command: 'npx @eventcatalog/cli addFileToDataStore "orders-db" \'{"content":"# Schema","fileName":"schema.md"}\'',
+      },
+    ],
+  },
+  {
+    name: 'dataStoreHasVersion',
+    description: 'Checks if a specific version of a data store exists',
+    category: 'Data Stores',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the data store' },
+      { name: 'version', type: 'string', required: true, description: 'Version to check' },
+    ],
+    examples: [
+      { description: 'Check if version exists', command: 'npx @eventcatalog/cli dataStoreHasVersion "orders-db" "1.0.0"' },
+    ],
+  },
+
+  // ================================
+  //            Data Products
+  // ================================
+  {
+    name: 'getDataProduct',
+    description: 'Returns a data product from EventCatalog by its ID',
+    category: 'Data Products',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the data product to retrieve' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to retrieve' },
+    ],
+    examples: [
+      { description: 'Get the latest data product', command: 'npx @eventcatalog/cli getDataProduct "customer-360"' },
+      { description: 'Get a specific version', command: 'npx @eventcatalog/cli getDataProduct "customer-360" "1.0.0"' },
+    ],
+  },
+  {
+    name: 'getDataProducts',
+    description: 'Returns all data products from EventCatalog',
+    category: 'Data Products',
+    args: [{ name: 'options', type: 'json', required: false, description: 'Options: {latestOnly?}' }],
+    examples: [
+      { description: 'Get all data products', command: 'npx @eventcatalog/cli getDataProducts' },
+      { description: 'Get only latest versions', command: 'npx @eventcatalog/cli getDataProducts \'{"latestOnly":true}\'' },
+    ],
+  },
+  {
+    name: 'writeDataProduct',
+    description: 'Writes a data product to EventCatalog',
+    category: 'Data Products',
+    args: [
+      {
+        name: 'dataProduct',
+        type: 'json',
+        required: true,
+        description: 'Data product object with id, name, version, and markdown',
+      },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, override?, versionExistingContent?}' },
+    ],
+    examples: [
+      {
+        description: 'Write a new data product',
+        command:
+          'npx @eventcatalog/cli writeDataProduct \'{"id":"customer-360","name":"Customer 360","version":"1.0.0","markdown":"# Customer 360"}\'',
+      },
+    ],
+  },
+  {
+    name: 'writeDataProductToDomain',
+    description: 'Writes a data product to a specific domain',
+    category: 'Data Products',
+    args: [
+      { name: 'dataProduct', type: 'json', required: true, description: 'Data product object' },
+      { name: 'domain', type: 'json', required: true, description: 'Domain reference: {id, version?}' },
+      { name: 'options', type: 'json', required: false, description: 'Options' },
+    ],
+    examples: [
+      {
+        description: 'Write data product to a domain',
+        command:
+          'npx @eventcatalog/cli writeDataProductToDomain \'{"id":"customer-360","name":"Customer 360","version":"1.0.0","markdown":"# Customer 360"}\' \'{"id":"Analytics"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmDataProduct',
+    description: 'Removes a data product by its path',
+    category: 'Data Products',
+    args: [{ name: 'path', type: 'string', required: true, description: 'Path to the data product' }],
+    examples: [{ description: 'Remove a data product', command: 'npx @eventcatalog/cli rmDataProduct "/customer-360"' }],
+  },
+  {
+    name: 'rmDataProductById',
+    description: 'Removes a data product by its ID',
+    category: 'Data Products',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the data product to remove' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to remove' },
+    ],
+    examples: [{ description: 'Remove a data product', command: 'npx @eventcatalog/cli rmDataProductById "customer-360"' }],
+  },
+  {
+    name: 'versionDataProduct',
+    description: 'Moves the current data product to a versioned directory',
+    category: 'Data Products',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the data product to version' }],
+    examples: [{ description: 'Version a data product', command: 'npx @eventcatalog/cli versionDataProduct "customer-360"' }],
+  },
+  {
+    name: 'addFileToDataProduct',
+    description: 'Adds a file to a data product',
+    category: 'Data Products',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the data product' },
+      { name: 'file', type: 'json', required: true, description: 'File object: {content, fileName}' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version' },
+    ],
+    examples: [
+      {
+        description: 'Add a file to a data product',
+        command: 'npx @eventcatalog/cli addFileToDataProduct "customer-360" \'{"content":"# Schema","fileName":"schema.md"}\'',
+      },
+    ],
+  },
+  {
+    name: 'addDataProductToDomain',
+    description: 'Adds a data product reference to a domain',
+    category: 'Data Products',
+    args: [
+      { name: 'domainId', type: 'string', required: true, description: 'The ID of the domain' },
+      { name: 'dataProduct', type: 'json', required: true, description: 'Data product reference: {id, version}' },
+      { name: 'domainVersion', type: 'string', required: false, description: 'Specific domain version' },
+    ],
+    examples: [
+      {
+        description: 'Add data product to domain',
+        command: 'npx @eventcatalog/cli addDataProductToDomain "Analytics" \'{"id":"customer-360","version":"1.0.0"}\'',
+      },
+    ],
+  },
+  {
+    name: 'dataProductHasVersion',
+    description: 'Checks if a specific version of a data product exists',
+    category: 'Data Products',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the data product' },
+      { name: 'version', type: 'string', required: true, description: 'Version to check' },
+    ],
+    examples: [
+      {
+        description: 'Check if version exists',
+        command: 'npx @eventcatalog/cli dataProductHasVersion "customer-360" "1.0.0"',
+      },
+    ],
+  },
+
+  // ================================
+  //            Diagrams
+  // ================================
+  {
+    name: 'getDiagram',
+    description: 'Returns a diagram from EventCatalog by its ID',
+    category: 'Diagrams',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the diagram to retrieve' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to retrieve' },
+    ],
+    examples: [
+      { description: 'Get the latest diagram', command: 'npx @eventcatalog/cli getDiagram "ArchitectureDiagram"' },
+      { description: 'Get a specific version', command: 'npx @eventcatalog/cli getDiagram "ArchitectureDiagram" "1.0.0"' },
+    ],
+  },
+  {
+    name: 'getDiagrams',
+    description: 'Returns all diagrams from EventCatalog',
+    category: 'Diagrams',
+    args: [{ name: 'options', type: 'json', required: false, description: 'Options: {latestOnly?}' }],
+    examples: [
+      { description: 'Get all diagrams', command: 'npx @eventcatalog/cli getDiagrams' },
+      { description: 'Get only latest versions', command: 'npx @eventcatalog/cli getDiagrams \'{"latestOnly":true}\'' },
+    ],
+  },
+  {
+    name: 'writeDiagram',
+    description: 'Writes a diagram to EventCatalog',
+    category: 'Diagrams',
+    args: [
+      {
+        name: 'diagram',
+        type: 'json',
+        required: true,
+        description: 'Diagram object with id, name, version, and markdown',
+      },
+      { name: 'options', type: 'json', required: false, description: 'Options: {path?, override?, versionExistingContent?}' },
+    ],
+    examples: [
+      {
+        description: 'Write a new diagram',
+        command:
+          'npx @eventcatalog/cli writeDiagram \'{"id":"ArchitectureDiagram","name":"Architecture Diagram","version":"1.0.0","markdown":"# Architecture Diagram"}\'',
+      },
+    ],
+  },
+  {
+    name: 'rmDiagram',
+    description: 'Removes a diagram by its path',
+    category: 'Diagrams',
+    args: [{ name: 'path', type: 'string', required: true, description: 'Path to the diagram' }],
+    examples: [{ description: 'Remove a diagram', command: 'npx @eventcatalog/cli rmDiagram "/ArchitectureDiagram"' }],
+  },
+  {
+    name: 'rmDiagramById',
+    description: 'Removes a diagram by its ID',
+    category: 'Diagrams',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the diagram to remove' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version to remove' },
+    ],
+    examples: [{ description: 'Remove a diagram', command: 'npx @eventcatalog/cli rmDiagramById "ArchitectureDiagram"' }],
+  },
+  {
+    name: 'versionDiagram',
+    description: 'Moves the current diagram to a versioned directory',
+    category: 'Diagrams',
+    args: [{ name: 'id', type: 'string', required: true, description: 'The ID of the diagram to version' }],
+    examples: [{ description: 'Version a diagram', command: 'npx @eventcatalog/cli versionDiagram "ArchitectureDiagram"' }],
+  },
+  {
+    name: 'addFileToDiagram',
+    description: 'Adds a file to a diagram',
+    category: 'Diagrams',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the diagram' },
+      { name: 'file', type: 'json', required: true, description: 'File object: {content, fileName}' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version' },
+    ],
+    examples: [
+      {
+        description: 'Add a file to a diagram',
+        command: 'npx @eventcatalog/cli addFileToDiagram "ArchitectureDiagram" \'{"content":"...","fileName":"diagram.png"}\'',
+      },
+    ],
+  },
+  {
+    name: 'diagramHasVersion',
+    description: 'Checks if a specific version of a diagram exists',
+    category: 'Diagrams',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the diagram' },
+      { name: 'version', type: 'string', required: true, description: 'Version to check' },
+    ],
+    examples: [
+      {
+        description: 'Check if version exists',
+        command: 'npx @eventcatalog/cli diagramHasVersion "ArchitectureDiagram" "1.0.0"',
+      },
+    ],
+  },
+
+  // ================================
+  //            Messages
+  // ================================
+  {
+    name: 'getProducersAndConsumersForMessage',
+    description: 'Returns the producers and consumers (services) for a given message',
+    category: 'Messages',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the message' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version' },
+    ],
+    examples: [
+      {
+        description: 'Get producers and consumers',
+        command: 'npx @eventcatalog/cli getProducersAndConsumersForMessage "OrderCreated"',
+      },
+    ],
+  },
+  {
+    name: 'getConsumersOfSchema',
+    description: 'Returns services that consume a given schema',
+    category: 'Messages',
+    args: [{ name: 'schemaPath', type: 'string', required: true, description: 'Path to the schema file' }],
+    examples: [
+      {
+        description: 'Get consumers of a schema',
+        command: 'npx @eventcatalog/cli getConsumersOfSchema "events/OrderCreated/schema.json"',
+      },
+    ],
+  },
+  {
+    name: 'getProducersOfSchema',
+    description: 'Returns services that produce a given schema',
+    category: 'Messages',
+    args: [{ name: 'schemaPath', type: 'string', required: true, description: 'Path to the schema file' }],
+    examples: [
+      {
+        description: 'Get producers of a schema',
+        command: 'npx @eventcatalog/cli getProducersOfSchema "events/OrderCreated/schema.json"',
+      },
+    ],
+  },
+  {
+    name: 'getOwnersForResource',
+    description: 'Returns the owners (users/teams) for a given resource',
+    category: 'Messages',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'The ID of the resource' },
+      { name: 'version', type: 'string', required: false, description: 'Specific version' },
+    ],
+    examples: [
+      { description: 'Get owners for a resource', command: 'npx @eventcatalog/cli getOwnersForResource "OrderService"' },
+    ],
+  },
+
+  // ================================
+  //            Utilities
+  // ================================
+  {
+    name: 'dumpCatalog',
+    description: 'Dumps the entire catalog to a JSON structure',
+    category: 'Utilities',
+    args: [],
+    examples: [
+      { description: 'Dump entire catalog', command: 'npx @eventcatalog/cli dumpCatalog' },
+      { description: 'Dump and save to file', command: 'npx @eventcatalog/cli dumpCatalog > catalog.json' },
+    ],
+  },
+  {
+    name: 'getEventCatalogConfigurationFile',
+    description: 'Returns the EventCatalog configuration file',
+    category: 'Utilities',
+    args: [],
+    examples: [{ description: 'Get config file', command: 'npx @eventcatalog/cli getEventCatalogConfigurationFile' }],
+  },
+
+  // ================================
+  //            Export (DSL)
+  // ================================
+  {
+    name: 'export',
+    description: 'Export catalog resources to EventCatalog DSL (.ec) format',
+    category: 'Export',
+    args: [
+      { name: 'all', type: 'boolean', required: false, description: 'Export the entire catalog (all resource types)' },
+      {
+        name: 'resource',
+        type: 'string',
+        required: false,
+        description: 'Resource type: event, command, query, service, domain (or plural forms)',
+      },
+      { name: 'id', type: 'string', required: false, description: 'Resource ID (omit to export all of the given type)' },
+      { name: 'version', type: 'string', required: false, description: 'Resource version (defaults to latest)' },
+      {
+        name: 'hydrate',
+        type: 'boolean',
+        required: false,
+        description: 'Include referenced resources (messages, channels, owners)',
+      },
+      { name: 'stdout', type: 'boolean', required: false, description: 'Print to stdout instead of writing a file' },
+      {
+        name: 'playground',
+        type: 'boolean',
+        required: false,
+        description: 'Open the exported DSL in EventCatalog Compass',
+      },
+      { name: 'output', type: 'string', required: false, description: 'Output file path (defaults to <id>.ec or catalog.ec)' },
+    ],
+    examples: [
+      {
+        description: 'Export a single service',
+        command: 'npx @eventcatalog/cli export --resource service --id OrderService',
+      },
+      {
+        description: 'Export a service with all dependencies',
+        command: 'npx @eventcatalog/cli export --resource service --id OrderService --hydrate',
+      },
+      {
+        description: 'Export all services',
+        command: 'npx @eventcatalog/cli export --resource services',
+      },
+      {
+        description: 'Export all services with hydration to stdout',
+        command: 'npx @eventcatalog/cli export --resource services --hydrate --stdout',
+      },
+      {
+        description: 'Export the entire catalog',
+        command: 'npx @eventcatalog/cli export --all --hydrate',
+      },
+      {
+        description: 'Export entire catalog to a custom file',
+        command: 'npx @eventcatalog/cli export --all --hydrate -o my-catalog.ec',
+      },
+      {
+        description: 'Export and open in EventCatalog Compass',
+        command: 'npx @eventcatalog/cli export --resource services --hydrate --playground',
+      },
+    ],
+  },
+
+  // ================================
+  //            Import
+  // ================================
+  {
+    name: 'import',
+    description:
+      'Import EventCatalog DSL (.ec) files into catalog markdown files. Existing resources with the same version are overridden. Importing a newer version automatically moves the old version into the versioned/ folder.',
+    category: 'Import',
+    args: [
+      { name: 'files', type: 'string', required: false, description: 'One or more .ec file paths to import' },
+      { name: 'stdin', type: 'boolean', required: false, description: 'Read DSL from stdin' },
+      { name: 'dry-run', type: 'boolean', required: false, description: 'Preview resources without writing' },
+      {
+        name: 'flat',
+        type: 'boolean',
+        required: false,
+        description: 'Write resources in a flat structure (no nesting under domains/services)',
+      },
+      { name: 'no-init', type: 'boolean', required: false, description: 'Skip catalog initialization prompt' },
+    ],
+    examples: [
+      {
+        description: 'Import a single .ec file',
+        command: 'npx @eventcatalog/cli import catalog.ec',
+      },
+      {
+        description: 'Import multiple .ec files',
+        command: 'npx @eventcatalog/cli import services.ec events.ec',
+      },
+      {
+        description: 'Import from stdin (pipe from export)',
+        command: 'npx @eventcatalog/cli export --all --stdout | npx @eventcatalog/cli import --stdin -d ./new-catalog',
+      },
+      {
+        description: 'Preview what would be written or merged',
+        command: 'npx @eventcatalog/cli import catalog.ec --dry-run',
+      },
+      {
+        description: 'Import without nested folders',
+        command: 'npx @eventcatalog/cli import catalog.ec --flat',
+      },
+      {
+        description: 'Import into an existing catalog directory without init prompts',
+        command: 'npx @eventcatalog/cli import catalog.ec --no-init -d ./existing-catalog',
+      },
+    ],
+  },
+
+  // Snapshots
+  {
+    name: 'createSnapshot',
+    description: 'Take a point-in-time snapshot of the entire catalog, capturing all resources and their metadata as a JSON file',
+    category: 'Snapshots',
+    args: [
+      {
+        name: 'label',
+        type: 'string',
+        required: false,
+        description: 'Human-readable label for the snapshot (defaults to ISO timestamp)',
+      },
+      {
+        name: 'outputDir',
+        type: 'string',
+        required: false,
+        description: 'Output directory for the snapshot file (defaults to .snapshots/)',
+      },
+    ],
+    examples: [
+      {
+        description: 'Create a snapshot with default settings',
+        command: 'npx @eventcatalog/cli snapshot create',
+      },
+      {
+        description: 'Create a snapshot with a custom label',
+        command: 'npx @eventcatalog/cli snapshot create --label pre-release-v2',
+      },
+      {
+        description: 'Create a snapshot and print JSON to stdout',
+        command: 'npx @eventcatalog/cli snapshot create --stdout',
+      },
+    ],
+  },
+  {
+    name: 'diffSnapshots',
+    description:
+      'Compare two snapshot files and output a structured diff showing added, removed, modified, and versioned resources plus relationship changes',
+    category: 'Snapshots',
+    args: [
+      { name: 'fileA', type: 'string', required: true, description: 'Path to the first (older) snapshot file' },
+      { name: 'fileB', type: 'string', required: true, description: 'Path to the second (newer) snapshot file' },
+    ],
+    examples: [
+      {
+        description: 'Diff two snapshot files as text',
+        command: 'npx @eventcatalog/cli snapshot diff .snapshots/before.snapshot.json .snapshots/after.snapshot.json',
+      },
+      {
+        description: 'Diff two snapshot files as JSON',
+        command:
+          'npx @eventcatalog/cli snapshot diff .snapshots/before.snapshot.json .snapshots/after.snapshot.json --format json',
+      },
+    ],
+  },
+  {
+    name: 'listSnapshots',
+    description: 'List all snapshots in the catalog .snapshots directory with their labels, timestamps, and git info',
+    category: 'Snapshots',
+    args: [],
+    examples: [
+      {
+        description: 'List all snapshots',
+        command: 'npx @eventcatalog/cli snapshot list',
+      },
+      {
+        description: 'List all snapshots as JSON',
+        command: 'npx @eventcatalog/cli snapshot list --format json',
+      },
+    ],
+  },
+
+  // Governance
+  {
+    name: 'governanceCheck',
+    description:
+      'Compare the current catalog (or a target branch) against a base branch and evaluate governance rules defined in governance.yaml (or governance.yml)',
+    category: 'Governance',
+    args: [
+      { name: '--base', type: 'string', required: false, description: 'Base branch to compare against (default: main)' },
+      {
+        name: '--target',
+        type: 'string',
+        required: false,
+        description: 'Target branch to compare (default: current working directory)',
+      },
+      { name: '--format', type: 'string', required: false, description: 'Output format: text or json (default: text)' },
+      {
+        name: '--status',
+        type: 'string',
+        required: false,
+        description: 'Status label to include in webhook payloads (e.g. proposed, approved)',
+      },
+    ],
+    examples: [
+      {
+        description: 'Check governance rules against main branch',
+        command: 'npx @eventcatalog/cli governance check',
+      },
+      {
+        description: 'Check against a specific base branch',
+        command: 'npx @eventcatalog/cli governance check --base develop',
+      },
+      {
+        description: 'Compare two branches directly',
+        command: 'npx @eventcatalog/cli governance check --base main --target feat/new-service',
+      },
+      {
+        description: 'Output results as JSON',
+        command: 'npx @eventcatalog/cli governance check --format json',
+      },
+    ],
+  },
+];
+
+/**
+ * Get all unique categories
+ */
+export function getCategories(): string[] {
+  return [...new Set(cliFunctions.map((fn) => fn.category))];
+}
+
+/**
+ * Get functions by category
+ */
+export function getFunctionsByCategory(category: string): CLIFunctionDoc[] {
+  return cliFunctions.filter((fn) => fn.category === category);
+}
+
+/**
+ * Get a function by name
+ */
+export function getFunction(name: string): CLIFunctionDoc | undefined {
+  return cliFunctions.find((fn) => fn.name === name);
+}
diff --git a/packages/cli/src/cli/dsl-managed-keys.ts b/packages/cli/src/cli/dsl-managed-keys.ts
new file mode 100644
index 000000000..05b7aa8c9
--- /dev/null
+++ b/packages/cli/src/cli/dsl-managed-keys.ts
@@ -0,0 +1,14 @@
+/**
+ * DSL-managed frontmatter keys by resource type.
+ *
+ * Keys listed here are controlled by DSL import and should not be preserved
+ * from existing frontmatter when omitted by the incoming DSL.
+ */
+const MESSAGE_MANAGED_KEYS: ReadonlySet<string> = new Set(['id', 'name', 'version', 'owners', 'deprecated', 'draft', 'summary']);
+
+export const DSL_MANAGED_KEYS_BY_TYPE: Record<string, ReadonlySet<string>> = {
+  domain: new Set(['id', 'name', 'version', 'owners', 'deprecated', 'draft', 'summary', 'services', 'domains']),
+  event: MESSAGE_MANAGED_KEYS,
+  command: MESSAGE_MANAGED_KEYS,
+  query: MESSAGE_MANAGED_KEYS,
+};
diff --git a/packages/cli/src/cli/executor.ts b/packages/cli/src/cli/executor.ts
new file mode 100644
index 000000000..6a7bb5e36
--- /dev/null
+++ b/packages/cli/src/cli/executor.ts
@@ -0,0 +1,38 @@
+import { existsSync } from 'node:fs';
+import { parseArguments } from './parser';
+import createSDK from '@eventcatalog/sdk';
+
+/**
+ * Execute a SDK function with the given arguments
+ */
+export async function executeFunction(catalogDir: string, functionName: string, rawArgs: string[]): Promise<any> {
+  // Validate catalog directory exists
+  if (!existsSync(catalogDir)) {
+    throw new Error(`Catalog directory not found: ${catalogDir}`);
+  }
+
+  // Initialize the SDK
+  const sdk = createSDK(catalogDir);
+
+  // Validate function exists
+  if (!(functionName in sdk)) {
+    throw new Error(`Function '${functionName}' not found. Use 'eventcatalog list' to see available functions.`);
+  }
+
+  const fn = (sdk as any)[functionName];
+
+  // Validate it's callable
+  if (typeof fn !== 'function') {
+    throw new Error(`'${functionName}' is not a callable function.`);
+  }
+
+  // Parse arguments
+  const parsedArgs = parseArguments(rawArgs);
+
+  // Execute function
+  try {
+    return await fn(...parsedArgs);
+  } catch (error) {
+    throw new Error(`Error executing '${functionName}': ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
diff --git a/packages/cli/src/cli/export.ts b/packages/cli/src/cli/export.ts
new file mode 100644
index 000000000..5113c9006
--- /dev/null
+++ b/packages/cli/src/cli/export.ts
@@ -0,0 +1,366 @@
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import open from 'open';
+import createSDK from '@eventcatalog/sdk';
+
+const RESOURCE_TYPES = ['event', 'command', 'query', 'service', 'domain'] as const;
+type ResourceType = (typeof RESOURCE_TYPES)[number];
+const SUPPORTED_RESOURCE_TYPES = RESOURCE_TYPES.join(', ');
+
+const PLURAL_MAP: Record<string, ResourceType> = {
+  events: 'event',
+  commands: 'command',
+  queries: 'query',
+  services: 'service',
+  domains: 'domain',
+};
+
+const KNOWN_UNSUPPORTED_EXPORT_TYPES = new Set([
+  'channel',
+  'channels',
+  'team',
+  'teams',
+  'user',
+  'users',
+  'container',
+  'containers',
+  'data-product',
+  'data-products',
+  'dataproduct',
+  'dataproducts',
+  'diagram',
+  'diagrams',
+  'flow',
+  'flows',
+]);
+
+interface ExportOptions {
+  resource: string;
+  id?: string;
+  version?: string;
+  hydrate?: boolean;
+  stdout?: boolean;
+  playground?: boolean;
+  output?: string;
+  dir: string;
+}
+
+function normalizeResourceType(resource: string): ResourceType {
+  const lower = resource.toLowerCase();
+  if (PLURAL_MAP[lower]) return PLURAL_MAP[lower];
+  return lower as ResourceType;
+}
+
+function assertSupportedExportType(resource: string, type: ResourceType): void {
+  const lower = resource.toLowerCase();
+
+  if (KNOWN_UNSUPPORTED_EXPORT_TYPES.has(lower)) {
+    throw new Error(
+      `Resource type '${resource}' is not yet supported for DSL export. Supported types: ${SUPPORTED_RESOURCE_TYPES}`
+    );
+  }
+
+  if (!RESOURCE_TYPES.includes(type)) {
+    throw new Error(`Invalid resource type '${resource}'. Must be one of: ${SUPPORTED_RESOURCE_TYPES}`);
+  }
+}
+
+function getResourceFetcher(sdk: ReturnType<typeof createSDK>, type: ResourceType) {
+  switch (type) {
+    case 'event':
+      return sdk.getEvent;
+    case 'command':
+      return sdk.getCommand;
+    case 'query':
+      return sdk.getQuery;
+    case 'service':
+      return sdk.getService;
+    case 'domain':
+      return sdk.getDomain;
+  }
+}
+
+function getCollectionFetcher(sdk: ReturnType<typeof createSDK>, type: ResourceType) {
+  switch (type) {
+    case 'event':
+      return sdk.getEvents;
+    case 'command':
+      return sdk.getCommands;
+    case 'query':
+      return sdk.getQueries;
+    case 'service':
+      return sdk.getServices;
+    case 'domain':
+      return sdk.getDomains;
+  }
+}
+
+function pluralize(type: ResourceType): string {
+  if (type === 'query') return 'queries';
+  return `${type}s`;
+}
+
+const SECTION_ORDER = ['team', 'user', 'channel', 'event', 'command', 'query', 'service', 'domain'] as const;
+
+const SECTION_LABELS: Record<string, string> = {
+  team: 'TEAMS',
+  user: 'USERS',
+  channel: 'CHANNELS',
+  event: 'EVENTS',
+  command: 'COMMANDS',
+  query: 'QUERIES',
+  service: 'SERVICES',
+  domain: 'DOMAINS',
+};
+
+/**
+ * Groups DSL blocks by resource type and orders them with section headers.
+ *
+ * Raw toDSL output may interleave different resource types (e.g. teams, channels,
+ * services, events). This splits on blank lines, buckets each block by its leading
+ * keyword, then reassembles in SECTION_ORDER with "// EVENTS" style headers.
+ */
+function groupDSLBlocks(dsl: string): string {
+  const blocks = dsl.split(/\n\n/).filter((b) => b.trim());
+  const buckets: Record<string, string[]> = {};
+
+  for (const block of blocks) {
+    const firstWord = block.trimStart().split(/\s/)[0];
+    const key = firstWord === 'subdomain' ? 'domain' : firstWord;
+    if (!buckets[key]) buckets[key] = [];
+    buckets[key].push(block);
+  }
+
+  const sections: string[] = [];
+  for (const type of SECTION_ORDER) {
+    if (!buckets[type] || buckets[type].length === 0) continue;
+    const label = SECTION_LABELS[type] || type.toUpperCase();
+    sections.push(`// ${label}\n${buckets[type].join('\n\n')}`);
+    delete buckets[type];
+  }
+
+  // Any remaining types not in SECTION_ORDER
+  for (const [type, items] of Object.entries(buckets)) {
+    if (items.length === 0) continue;
+    const label = type.toUpperCase();
+    sections.push(`// ${label}\n${items.join('\n\n')}`);
+  }
+
+  return sections.join('\n\n');
+}
+
+interface ResourceDefinition {
+  keyword: string;
+  id: string;
+  version?: string;
+}
+
+/**
+ * Extracts resource definitions from DSL text by scanning for top-level
+ * `<keyword> <id> {` lines and reading the version from the block body.
+ */
+function extractResourceDefinitions(dsl: string, filterTypes: string[]): ResourceDefinition[] {
+  const results: ResourceDefinition[] = [];
+  const lines = dsl.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trimStart();
+    const parts = trimmed.split(/\s/);
+    const keyword = parts[0];
+    const id = parts[1];
+    if (!filterTypes.includes(keyword)) continue;
+    if (!id || !trimmed.endsWith('{')) continue;
+
+    // Look ahead inside the block for a `version X.Y.Z` line
+    let version: string | undefined;
+    for (let j = i + 1; j < lines.length; j++) {
+      const inner = lines[j].trim();
+      if (inner === '}') break;
+      const vMatch = inner.match(/^version\s+(.+)$/);
+      if (vMatch) {
+        version = vMatch[1];
+        break;
+      }
+    }
+    results.push({ keyword, id, version });
+  }
+
+  return results;
+}
+
+/**
+ * Builds a `visualizer main { ... }` block listing all resource definitions
+ * found in the DSL output.
+ *
+ * When multiple versions of the same resource exist (e.g. two versions of
+ * OrderService), references are version-qualified (`service OrderService@1.0.0`)
+ * to avoid ambiguity. Single-version resources use bare ids.
+ */
+function buildVisualizerBlock(dsl: string, name: string, filterTypes: ResourceType | ResourceType[]): string {
+  const types = Array.isArray(filterTypes) ? filterTypes : [filterTypes];
+  const definitions = extractResourceDefinitions(dsl, types);
+
+  if (definitions.length === 0) return '';
+
+  // Count occurrences of each keyword+id to detect duplicates needing version qualification
+  const counts = new Map<string, number>();
+  for (const def of definitions) {
+    const key = `${def.keyword}:${def.id}`;
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+
+  const entries = definitions.map((def) => {
+    const key = `${def.keyword}:${def.id}`;
+    const needsVersion = (counts.get(key) || 0) > 1 && def.version;
+    const ref = needsVersion ? `${def.id}@${def.version}` : def.id;
+    return `  ${def.keyword} ${ref}`;
+  });
+
+  return `\nvisualizer main {\n  name "${name}"\n${entries.join('\n')}\n}`;
+}
+
+export async function exportCatalog(options: Omit<ExportOptions, 'resource'>): Promise<string> {
+  const { hydrate = false, stdout = false, playground = false, output, dir } = options;
+
+  const sdk = createSDK(dir);
+  // Independent collection fetches/conversions can run in parallel.
+  // Promise.all preserves RESOURCE_TYPES order in the resulting array.
+  const dslParts = (
+    await Promise.all(
+      RESOURCE_TYPES.map(async (type) => {
+        const fetcher = getCollectionFetcher(sdk, type);
+        const resources = await fetcher({ latestOnly: true });
+        if (!resources || resources.length === 0) return '';
+        return sdk.toDSL(resources, { type, hydrate });
+      })
+    )
+  ).filter((dsl): dsl is string => Boolean(dsl));
+
+  if (dslParts.length === 0) {
+    throw new Error(`No resources found in catalog at '${dir}'`);
+  }
+
+  const combined = dslParts.join('\n\n');
+  const grouped = groupDSLBlocks(combined);
+  const vizBlock = buildVisualizerBlock(grouped, 'Full Catalog', [...RESOURCE_TYPES]);
+  const dsl = vizBlock ? `${grouped}\n${vizBlock}` : grouped;
+
+  if (stdout) {
+    return dsl;
+  }
+
+  const filename = output || 'catalog.ec';
+  const filepath = resolve(filename);
+  writeFileSync(filepath, dsl + '\n', 'utf-8');
+
+  const lines = ['', `  Exported full catalog to ${filepath}`];
+
+  if (playground) {
+    const encoded = Buffer.from(dsl).toString('base64');
+    const playgroundUrl = `https://compass.eventcatalog.dev/?code=${encoded}`;
+    await open(playgroundUrl);
+    lines.push('', `  Opening in EventCatalog Compass...`);
+  } else {
+    lines.push('', `  Tip: Use --playground to open in EventCatalog Compass`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+export async function exportAll(options: ExportOptions): Promise<string> {
+  const { resource, hydrate = false, stdout = false, playground = false, output, dir } = options;
+
+  const type = normalizeResourceType(resource);
+  assertSupportedExportType(resource, type);
+
+  const plural = pluralize(type);
+  const sdk = createSDK(dir);
+
+  const fetcher = getCollectionFetcher(sdk, type);
+  const allResources = (await fetcher({ latestOnly: true })) || [];
+
+  if (allResources.length === 0) {
+    throw new Error(`No ${plural} found in catalog at '${dir}'`);
+  }
+
+  const rawDsl = await sdk.toDSL(allResources, { type, hydrate });
+  const grouped = groupDSLBlocks(rawDsl);
+  const vizBlock = buildVisualizerBlock(grouped, `All ${plural}`, type);
+  const dsl = vizBlock ? `${grouped}\n${vizBlock}` : grouped;
+
+  if (stdout) {
+    return dsl;
+  }
+
+  const filename = output || `${plural}.ec`;
+  const filepath = resolve(filename);
+  writeFileSync(filepath, dsl + '\n', 'utf-8');
+
+  const lines = ['', `  Exported ${allResources.length} ${plural} to ${filepath}`];
+
+  if (playground) {
+    const encoded = Buffer.from(dsl).toString('base64');
+    const playgroundUrl = `https://compass.eventcatalog.dev/?code=${encoded}`;
+    await open(playgroundUrl);
+    lines.push('', `  Opening in EventCatalog Compass...`);
+  } else {
+    lines.push('', `  Tip: Use --playground to open in EventCatalog Compass`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+export async function exportResource(options: ExportOptions): Promise<string> {
+  const { resource, id, version, hydrate = false, stdout = false, playground = false, output, dir } = options;
+
+  if (!id) {
+    return exportAll(options);
+  }
+
+  const type = normalizeResourceType(resource);
+  assertSupportedExportType(resource, type);
+
+  const sdk = createSDK(dir);
+
+  const fetcher = getResourceFetcher(sdk, type);
+  const data = await fetcher(id, version);
+
+  if (!data) {
+    const versionStr = version ? `@${version}` : ' (latest)';
+    throw new Error(`${resource} '${id}${versionStr}' not found in catalog at '${dir}'`);
+  }
+
+  const rawDsl = await sdk.toDSL(data, { type, hydrate });
+
+  // When hydrating, toDSL pulls in related resources (services, channels, owners)
+  // so we group by type with section headers and widen the visualizer filter to
+  // include all resource types that may appear in the hydrated output.
+  const grouped = hydrate ? groupDSLBlocks(rawDsl) : rawDsl;
+  const vizTypes: ResourceType[] = hydrate ? [...RESOURCE_TYPES] : [type];
+  const vizBlock = buildVisualizerBlock(grouped, `View of ${id}`, vizTypes);
+  const dsl = vizBlock ? `${grouped}\n${vizBlock}` : grouped;
+
+  if (stdout) {
+    return dsl;
+  }
+
+  const filename = output || `${id}.ec`;
+  const filepath = resolve(filename);
+  writeFileSync(filepath, dsl + '\n', 'utf-8');
+
+  const lines = ['', `  Exported ${type} '${id}' to ${filepath}`];
+
+  if (playground) {
+    const encoded = Buffer.from(dsl).toString('base64');
+    const playgroundUrl = `https://compass.eventcatalog.dev/?code=${encoded}`;
+    await open(playgroundUrl);
+    lines.push('', `  Opening in EventCatalog Compass...`);
+  } else {
+    lines.push('', `  Tip: Use --playground to open in EventCatalog Compass`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
diff --git a/packages/cli/src/cli/governance/actions.ts b/packages/cli/src/cli/governance/actions.ts
new file mode 100644
index 000000000..fffe63dda
--- /dev/null
+++ b/packages/cli/src/cli/governance/actions.ts
@@ -0,0 +1,249 @@
+import { randomUUID } from 'node:crypto';
+import type { CatalogSnapshot } from '@eventcatalog/sdk';
+import type { CompatibilityStrategy } from '@eventcatalog/breaking-changes';
+import type { GovernanceResult } from './types';
+import { resolveEnvVars, isProducerTrigger, getChangeVerb } from './rules';
+
+export type MessageTypeMap = Map<string, string>;
+export type ServiceOwnersMap = Map<string, string[]>;
+
+export type GovernanceActionOptions = {
+  messageTypes?: MessageTypeMap;
+  status?: string;
+  serviceOwners?: ServiceOwnersMap;
+  baseRef?: string;
+  targetRef?: string;
+  compatibilityStrategy?: CompatibilityStrategy;
+};
+
+export const buildMessageTypeMap = (snapshot: CatalogSnapshot): MessageTypeMap => {
+  const map: MessageTypeMap = new Map();
+  for (const event of snapshot.resources.messages.events) {
+    map.set(event.id as string, 'event');
+  }
+  for (const command of snapshot.resources.messages.commands) {
+    map.set(command.id as string, 'command');
+  }
+  for (const query of snapshot.resources.messages.queries) {
+    map.set(query.id as string, 'query');
+  }
+  return map;
+};
+
+export const buildServiceOwnersMap = (snapshot: CatalogSnapshot): ServiceOwnersMap => {
+  const map: ServiceOwnersMap = new Map();
+  for (const service of snapshot.resources.services) {
+    if (service.owners && Array.isArray(service.owners) && service.owners.length > 0) {
+      map.set(service.id as string, service.owners as string[]);
+    }
+  }
+  return map;
+};
+
+export const executeGovernanceActions = async (
+  results: GovernanceResult[],
+  opts: GovernanceActionOptions = {}
+): Promise<string[]> => {
+  const { messageTypes, status, serviceOwners, baseRef, targetRef, compatibilityStrategy } = opts;
+  const webhookCalls: Array<{ urlTemplate: string; request: Promise<Response> }> = [];
+  const now = new Date().toISOString();
+
+  for (const result of results) {
+    for (const action of result.rule.actions) {
+      if (action.type !== 'webhook') continue;
+
+      const url = resolveEnvVars(action.url);
+      const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+
+      if (action.headers) {
+        for (const [key, value] of Object.entries(action.headers)) {
+          headers[key] = resolveEnvVars(value);
+        }
+      }
+
+      // Handle schema changes
+      if (result.schemaChanges && result.schemaChanges.length > 0) {
+        for (const sc of result.schemaChanges) {
+          const messageType = messageTypes?.get(sc.resourceChange.resourceId) || 'message';
+
+          const payload = {
+            specversion: '1.0',
+            type: 'eventcatalog.governance.schema_changed',
+            source: 'eventcatalog/governance',
+            id: randomUUID(),
+            time: now,
+            datacontenttype: 'application/json',
+            data: {
+              schemaVersion: 1,
+              ...(status && { status }),
+              summary: `Schema changed for ${messageType} ${sc.resourceChange.resourceId}`,
+              message: {
+                id: sc.resourceChange.resourceId,
+                version: sc.resourceChange.version,
+                type: messageType,
+              },
+              schema: {
+                beforeHash: sc.beforeSchemaHash ?? null,
+                afterHash: sc.afterSchemaHash ?? null,
+                beforePath: sc.beforeSchemaPath ?? null,
+                afterPath: sc.afterSchemaPath ?? null,
+              },
+              refs: {
+                base: baseRef ?? null,
+                target: targetRef ?? null,
+              },
+              consumers: sc.consumerServices,
+              producers: sc.producerServices,
+            },
+          };
+
+          webhookCalls.push({
+            urlTemplate: action.url,
+            request: fetch(url, { method: 'POST', headers, body: JSON.stringify(payload) }),
+          });
+        }
+        continue;
+      }
+
+      // Handle breaking schema changes
+      if (result.breakingSchemaChanges && result.breakingSchemaChanges.length > 0) {
+        for (const bsc of result.breakingSchemaChanges) {
+          const messageType = messageTypes?.get(bsc.resourceChange.resourceId) || 'message';
+
+          const payload = {
+            specversion: '1.0',
+            type: 'eventcatalog.governance.schema_breaking_change',
+            source: 'eventcatalog/governance',
+            id: randomUUID(),
+            time: now,
+            datacontenttype: 'application/json',
+            data: {
+              schemaVersion: 1,
+              ...(status && { status }),
+              ...(compatibilityStrategy && { compatibilityStrategy }),
+              summary: `Breaking schema change detected for ${messageType} ${bsc.resourceChange.resourceId}`,
+              message: {
+                id: bsc.resourceChange.resourceId,
+                version: bsc.resourceChange.version,
+                type: messageType,
+              },
+              schema: {
+                beforeHash: bsc.beforeSchemaHash ?? null,
+                afterHash: bsc.afterSchemaHash ?? null,
+                beforePath: bsc.beforeSchemaPath ?? null,
+                afterPath: bsc.afterSchemaPath ?? null,
+              },
+              breakingChanges: bsc.breakingChanges,
+              refs: {
+                base: baseRef ?? null,
+                target: targetRef ?? null,
+              },
+              consumers: bsc.consumerServices,
+              producers: bsc.producerServices,
+            },
+          };
+
+          webhookCalls.push({
+            urlTemplate: action.url,
+            request: fetch(url, { method: 'POST', headers, body: JSON.stringify(payload) }),
+          });
+        }
+        continue;
+      }
+
+      // Handle deprecation changes
+      if (result.deprecationChanges && result.deprecationChanges.length > 0) {
+        for (const dc of result.deprecationChanges) {
+          const messageType = messageTypes?.get(dc.resourceChange.resourceId) || 'message';
+
+          const producers =
+            dc.producerServices.length > 0
+              ? dc.producerServices
+              : [{ id: 'unknown', version: 'unknown' } as { id: string; version: string; owners?: string[] }];
+
+          for (const producer of producers) {
+            const payload = {
+              specversion: '1.0',
+              type: `eventcatalog.governance.message_deprecated`,
+              source: 'eventcatalog/governance',
+              id: randomUUID(),
+              time: now,
+              datacontenttype: 'application/json',
+              data: {
+                schemaVersion: 1,
+                ...(status && { status }),
+                summary: `${dc.resourceChange.resourceId} (${messageType}) has been deprecated by ${producer.id}`,
+                producer: {
+                  id: producer.id,
+                  version: producer.version,
+                  ...(producer.owners && { owners: producer.owners }),
+                },
+                message: {
+                  id: dc.resourceChange.resourceId,
+                  version: dc.resourceChange.version,
+                  type: messageType,
+                },
+              },
+            };
+
+            webhookCalls.push({
+              urlTemplate: action.url,
+              request: fetch(url, { method: 'POST', headers, body: JSON.stringify(payload) }),
+            });
+          }
+        }
+        continue;
+      }
+
+      // Handle relationship changes
+      for (const change of result.matchedChanges) {
+        const verb = getChangeVerb(result.trigger, change.changeType);
+        const messageType = messageTypes?.get(change.resourceId) || 'message';
+        const serviceRole = isProducerTrigger(result.trigger) ? 'producer' : 'consumer';
+
+        const payload = {
+          specversion: '1.0',
+          type: `eventcatalog.governance.${result.trigger}`,
+          source: 'eventcatalog/governance',
+          id: randomUUID(),
+          time: now,
+          datacontenttype: 'application/json',
+          data: {
+            schemaVersion: 1,
+            ...(status && { status }),
+            summary: `${change.serviceId} is ${verb} the ${messageType} ${change.resourceId}`,
+            [serviceRole]: {
+              id: change.serviceId,
+              version: change.serviceVersion,
+              ...(serviceOwners?.get(change.serviceId) && { owners: serviceOwners.get(change.serviceId) }),
+            },
+            message: {
+              id: change.resourceId,
+              version: change.resourceVersion,
+              type: messageType,
+            },
+          },
+        };
+
+        webhookCalls.push({
+          urlTemplate: action.url,
+          request: fetch(url, { method: 'POST', headers, body: JSON.stringify(payload) }),
+        });
+      }
+    }
+  }
+
+  const settled = await Promise.allSettled(webhookCalls.map((c) => c.request));
+
+  return settled.map((result, i) => {
+    const url = webhookCalls[i].urlTemplate;
+    if (result.status === 'fulfilled') {
+      const res = result.value;
+      if (!res.ok) {
+        return `  Webhook failed: ${url} ✗ (HTTP ${res.status})`;
+      }
+      return `  Webhook sent: ${url} ✓`;
+    }
+    return `  Webhook failed: ${url} ✗ (${result.reason instanceof Error ? result.reason.message : String(result.reason)})`;
+  });
+};
diff --git a/packages/cli/src/cli/governance/check.ts b/packages/cli/src/cli/governance/check.ts
new file mode 100644
index 000000000..179d4f7cc
--- /dev/null
+++ b/packages/cli/src/cli/governance/check.ts
@@ -0,0 +1,173 @@
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import dotenv from 'dotenv';
+import createSDK from '@eventcatalog/sdk';
+import { isEventCatalogScaleEnabled } from '@eventcatalog/license';
+import { loadGovernanceConfig, evaluateGovernanceRules, enrichSchemaContent, resolveEnvVars } from './rules';
+import { formatGovernanceOutput, formatFailureOutput } from './format';
+import { executeGovernanceActions, buildMessageTypeMap, buildServiceOwnersMap } from './actions';
+import type { GovernanceCheckResult } from './types';
+
+export type GovernanceCheckOptions = {
+  base?: string;
+  target?: string;
+  format?: string;
+  status?: string;
+  dir: string;
+};
+
+const BRANCH_NAME_RE = /^[a-zA-Z0-9._\-/]+$/;
+
+const extractBranchToTempDir = (branch: string, catalogDir: string, tempDirs: string[]): string => {
+  if (!BRANCH_NAME_RE.test(branch)) {
+    throw new Error(`Invalid branch name: "${branch}"`);
+  }
+  const tmpDir = mkdtempSync(path.join(tmpdir(), 'ec-governance-'));
+  tempDirs.push(tmpDir);
+  try {
+    execSync(`git archive ${branch} | tar -x -C ${tmpDir}`, { cwd: catalogDir, stdio: 'pipe' });
+  } catch {
+    throw new Error(`Failed to extract branch "${branch}". Is it a valid git branch?`);
+  }
+  return tmpDir;
+};
+
+export const governanceCheck = async (opts: GovernanceCheckOptions): Promise<GovernanceCheckResult> => {
+  const dir = path.resolve(opts.dir);
+
+  // Load .env file from catalog directory (contains license key, webhook secrets, etc.)
+  dotenv.config({ path: path.join(dir, '.env') });
+
+  const isScale = await isEventCatalogScaleEnabled();
+  if (!isScale) {
+    throw new Error('Governance requires an EventCatalog Scale plan. Learn more at https://eventcatalog.dev/pricing');
+  }
+
+  const baseBranch = opts.base || 'main';
+
+  const tempDirs: string[] = [];
+  const trackTempDir = (prefix: string): string => {
+    const d = mkdtempSync(path.join(tmpdir(), prefix));
+    tempDirs.push(d);
+    return d;
+  };
+
+  try {
+    const baseTmpDir = extractBranchToTempDir(baseBranch, dir, tempDirs);
+
+    const baseSnapshotDir = trackTempDir('ec-snap-base-');
+    const targetSnapshotDir = trackTempDir('ec-snap-target-');
+
+    const baseSDK = createSDK(baseTmpDir);
+    const baseResult = await baseSDK.createSnapshot({ label: `base-${baseBranch}`, outputDir: baseSnapshotDir });
+
+    let targetResult;
+    let targetCatalogDir: string;
+    if (opts.target) {
+      targetCatalogDir = extractBranchToTempDir(opts.target, dir, tempDirs);
+      const targetSDK = createSDK(targetCatalogDir);
+      targetResult = await targetSDK.createSnapshot({ label: `target-${opts.target}`, outputDir: targetSnapshotDir });
+    } else {
+      targetCatalogDir = dir;
+      const targetSDK = createSDK(dir);
+      targetResult = await targetSDK.createSnapshot({ label: 'current', outputDir: targetSnapshotDir });
+    }
+
+    const diff = await baseSDK.diffSnapshots(baseResult.filePath, targetResult.filePath);
+
+    const config = loadGovernanceConfig(dir);
+
+    if (config.rules.length === 0) {
+      return { output: 'No governance.yaml (or governance.yml) found or no rules defined.', exitCode: 0, failures: [] };
+    }
+
+    const results = evaluateGovernanceRules(diff, config, targetResult.snapshot, baseResult.snapshot);
+
+    // Populate before/after schema content for any schema_changed results
+    await enrichSchemaContent(results, baseTmpDir, targetCatalogDir, config.compatibility?.strategy);
+
+    // Remove schema_breaking_change results where no actual breaking changes were found
+    const filteredResults = results.filter((r) => {
+      if (r.trigger !== 'schema_breaking_change') return true;
+      if (!r.breakingSchemaChanges) return false;
+      r.breakingSchemaChanges = r.breakingSchemaChanges.filter((bsc) => bsc.breakingChanges.length > 0);
+      return r.breakingSchemaChanges.length > 0;
+    });
+
+    // Mark results that have fail actions and collect their messages
+    for (const result of filteredResults) {
+      const failActions = result.rule.actions.filter((a) => a.type === 'fail');
+      if (failActions.length > 0) {
+        result.failed = true;
+        result.failMessages = failActions
+          .map((a) => ('message' in a && a.message ? resolveEnvVars(a.message) : undefined))
+          .filter((m): m is string => m !== undefined);
+      }
+    }
+
+    // Always execute actions (webhooks) regardless of output format
+    const messageTypes = buildMessageTypeMap(targetResult.snapshot);
+    const serviceOwners = buildServiceOwnersMap(targetResult.snapshot);
+    const actionOutput = await executeGovernanceActions(filteredResults, {
+      messageTypes,
+      status: opts.status,
+      serviceOwners,
+      baseRef: baseBranch,
+      targetRef: opts.target || 'working-directory',
+      compatibilityStrategy: config.compatibility?.strategy,
+    });
+
+    // Collect failures
+    const failures = filteredResults
+      .filter((r) => r.failed)
+      .map((r) => ({ ruleName: r.rule.name, messages: r.failMessages || [] }));
+
+    if (opts.format === 'json') {
+      const jsonOutput = {
+        baseBranch,
+        target: opts.target || 'working directory',
+        results: filteredResults,
+        summary: {
+          rulesTriggered: filteredResults.length,
+          failures: failures.length,
+          passed: failures.length === 0,
+        },
+        diff: diff.summary,
+      };
+      return { output: JSON.stringify(jsonOutput, null, 2), exitCode: failures.length > 0 ? 1 : 0, failures };
+    }
+
+    const targetLabel = opts.target || 'working directory';
+    const lines: string[] = [`Governance check: comparing ${targetLabel} against ${baseBranch}`, ''];
+
+    lines.push(formatGovernanceOutput(filteredResults));
+
+    if (actionOutput.length > 0) {
+      lines.push('');
+      lines.push(...actionOutput);
+    }
+
+    if (filteredResults.length > 0) {
+      const webhookCount = actionOutput.filter((l) => l.includes('Webhook sent')).length;
+      const parts = [`${filteredResults.length} rule${filteredResults.length === 1 ? '' : 's'} triggered`];
+      if (webhookCount > 0) parts.push(`${webhookCount} webhook${webhookCount === 1 ? '' : 's'} sent`);
+      lines.push('');
+      lines.push(parts.join(', ') + '.');
+    }
+
+    // Append failure output
+    const failureOutput = formatFailureOutput(failures);
+    if (failureOutput) {
+      lines.push('');
+      lines.push(failureOutput);
+    }
+
+    return { output: lines.join('\n'), exitCode: failures.length > 0 ? 1 : 0, failures };
+  } finally {
+    for (const d of tempDirs) {
+      rmSync(d, { recursive: true, force: true });
+    }
+  }
+};
diff --git a/packages/cli/src/cli/governance/format.ts b/packages/cli/src/cli/governance/format.ts
new file mode 100644
index 000000000..fff50b87d
--- /dev/null
+++ b/packages/cli/src/cli/governance/format.ts
@@ -0,0 +1,53 @@
+import type { GovernanceResult } from './types';
+import { getChangeVerb } from './rules';
+
+export const formatGovernanceOutput = (results: GovernanceResult[]): string => {
+  if (results.length === 0) {
+    return 'No governance rules triggered. Catalog is compliant.';
+  }
+
+  const lines: string[] = ['Governance:', ''];
+
+  for (const result of results) {
+    lines.push(`  Rule "${result.rule.name}" triggered (${result.trigger}):`);
+
+    if (result.schemaChanges && result.schemaChanges.length > 0) {
+      for (const sc of result.schemaChanges) {
+        const consumers = sc.consumerServices.length > 0 ? sc.consumerServices.map((c) => c.id).join(', ') : 'no known consumers';
+        lines.push(
+          `    ! Schema changed for ${sc.resourceChange.resourceId} (${sc.resourceChange.type}) — consumers: ${consumers}`
+        );
+      }
+    } else if (result.deprecationChanges && result.deprecationChanges.length > 0) {
+      for (const dc of result.deprecationChanges) {
+        const producers = dc.producerServices.length > 0 ? dc.producerServices.map((p) => p.id).join(', ') : 'unknown producer';
+        lines.push(`    ! ${dc.resourceChange.resourceId} (${dc.resourceChange.type}) deprecated by ${producers}`);
+      }
+    } else {
+      for (const change of result.matchedChanges) {
+        const prefix = change.changeType === 'added' ? '+' : '-';
+        const verb = getChangeVerb(result.trigger, change.changeType);
+        lines.push(`    ${prefix} ${change.serviceId} is ${verb} ${change.resourceId}`);
+      }
+    }
+
+    lines.push('');
+  }
+
+  return lines.join('\n');
+};
+
+export const formatFailureOutput = (failures: Array<{ ruleName: string; messages: string[] }>): string => {
+  if (failures.length === 0) return '';
+
+  const lines: string[] = [];
+
+  for (const f of failures) {
+    lines.push(`FAILED: ${f.ruleName}`);
+    for (const msg of f.messages) {
+      lines.push(`  ${msg}`);
+    }
+  }
+
+  return lines.join('\n');
+};
diff --git a/packages/cli/src/cli/governance/index.ts b/packages/cli/src/cli/governance/index.ts
new file mode 100644
index 000000000..b3b19060c
--- /dev/null
+++ b/packages/cli/src/cli/governance/index.ts
@@ -0,0 +1,25 @@
+export {
+  loadGovernanceConfig,
+  evaluateGovernanceRules,
+  resolveEnvVars,
+  isProducerTrigger,
+  getChangeVerb,
+  buildServiceMessageSets,
+  enrichSchemaContent,
+} from './rules';
+export { executeGovernanceActions, buildMessageTypeMap, buildServiceOwnersMap } from './actions';
+export type { MessageTypeMap, ServiceOwnersMap, GovernanceActionOptions } from './actions';
+export { formatGovernanceOutput, formatFailureOutput } from './format';
+export { governanceCheck } from './check';
+export type { GovernanceCheckOptions } from './check';
+export type {
+  GovernanceTrigger,
+  GovernanceAction,
+  GovernanceRule,
+  GovernanceConfig,
+  GovernanceResult,
+  GovernanceCheckResult,
+  DeprecationChange,
+  SchemaChange,
+  BreakingSchemaChange,
+} from './types';
diff --git a/packages/cli/src/cli/governance/rules.ts b/packages/cli/src/cli/governance/rules.ts
new file mode 100644
index 000000000..b8ca08648
--- /dev/null
+++ b/packages/cli/src/cli/governance/rules.ts
@@ -0,0 +1,526 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import yaml from 'js-yaml';
+import { satisfies, validRange } from 'semver';
+import createSDK from '@eventcatalog/sdk';
+import type { SnapshotDiff, RelationshipChange, CatalogSnapshot, ResourceChange } from '@eventcatalog/sdk';
+import type {
+  GovernanceConfig,
+  GovernanceTrigger,
+  GovernanceResult,
+  DeprecationChange,
+  SchemaChange,
+  BreakingSchemaChange,
+} from './types';
+import { detectBreakingChanges } from '@eventcatalog/breaking-changes';
+import type { CompatibilityStrategy } from '@eventcatalog/breaking-changes';
+
+export const loadGovernanceConfig = (catalogDir: string): GovernanceConfig => {
+  const yamlPath = path.join(catalogDir, 'governance.yaml');
+  const ymlPath = path.join(catalogDir, 'governance.yml');
+
+  const configPath = fs.existsSync(yamlPath) ? yamlPath : fs.existsSync(ymlPath) ? ymlPath : null;
+
+  if (!configPath) {
+    return { rules: [] };
+  }
+
+  const content = fs.readFileSync(configPath, 'utf-8');
+  const parsed = yaml.load(content) as GovernanceConfig;
+  const rules = parsed?.rules || [];
+
+  for (const rule of rules) {
+    for (const action of rule.actions) {
+      if (action.type === 'fail' && action.message !== undefined && typeof action.message !== 'string') {
+        throw new Error(`Invalid "message" in fail action for rule "${rule.name}". Must be a string.`);
+      }
+    }
+  }
+
+  if (parsed?.compatibility?.strategy) {
+    const validStrategies = new Set(['BACKWARD', 'FORWARD', 'FULL', 'NONE']);
+    if (!validStrategies.has(parsed.compatibility.strategy)) {
+      throw new Error(
+        `Invalid compatibility strategy "${parsed.compatibility.strategy}". Must be one of: BACKWARD, FORWARD, FULL, NONE.`
+      );
+    }
+  }
+
+  return {
+    ...(parsed?.compatibility && { compatibility: parsed.compatibility }),
+    rules,
+  };
+};
+
+const TRIGGER_FILTERS: Partial<Record<GovernanceTrigger, (change: RelationshipChange) => boolean>> = {
+  consumer_added: (c) => c.direction === 'receives' && c.changeType === 'added',
+  consumer_removed: (c) => c.direction === 'receives' && c.changeType === 'removed',
+  producer_added: (c) => c.direction === 'sends' && c.changeType === 'added',
+  producer_removed: (c) => c.direction === 'sends' && c.changeType === 'removed',
+};
+
+export const buildServiceMessageSets = (
+  snapshot: CatalogSnapshot
+): { produces: Map<string, Set<string>>; consumes: Map<string, Set<string>> } => {
+  const produces = new Map<string, Set<string>>();
+  const consumes = new Map<string, Set<string>>();
+
+  for (const service of snapshot.resources.services) {
+    const serviceId = service.id as string;
+    if (service.sends) {
+      const ids = new Set<string>();
+      for (const s of service.sends) ids.add(s.id as string);
+      produces.set(serviceId, ids);
+    }
+    if (service.receives) {
+      const ids = new Set<string>();
+      for (const r of service.receives) ids.add(r.id as string);
+      consumes.set(serviceId, ids);
+    }
+  }
+
+  return { produces, consumes };
+};
+
+type ServiceMessageSets = ReturnType<typeof buildServiceMessageSets>;
+
+const matchesResourceId = (
+  resourceId: string,
+  serviceId: string | undefined,
+  resources: string[],
+  messageSets?: ServiceMessageSets
+): boolean => {
+  return resources.some((r) => {
+    if (r === '*') return true;
+    if (r.startsWith('service:')) {
+      if (serviceId) return serviceId === r.slice(8);
+      // For deprecation: match if the specified service produces this message
+      return messageSets?.produces.get(r.slice(8))?.has(resourceId) ?? false;
+    }
+    if (r.startsWith('message:')) return resourceId === r.slice(8);
+    if (r.startsWith('produces:')) return messageSets?.produces.get(r.slice(9))?.has(resourceId) ?? false;
+    if (r.startsWith('consumes:')) return messageSets?.consumes.get(r.slice(9))?.has(resourceId) ?? false;
+    return false;
+  });
+};
+
+const REMOVED_TRIGGERS: Set<GovernanceTrigger> = new Set(['consumer_removed', 'producer_removed']);
+
+const MESSAGE_RESOURCE_TYPES = new Set(['event', 'command', 'query']);
+
+const buildMessageMap = (snapshot: CatalogSnapshot): Map<string, Record<string, any>> => {
+  const map = new Map<string, Record<string, any>>();
+  for (const msg of snapshot.resources.messages.events) map.set(msg.id as string, msg);
+  for (const msg of snapshot.resources.messages.commands) map.set(msg.id as string, msg);
+  for (const msg of snapshot.resources.messages.queries) map.set(msg.id as string, msg);
+  return map;
+};
+
+type ServiceEntry = { id: string; version: string; owners?: string[] };
+
+const buildServiceIndex = (snapshot: CatalogSnapshot, direction: 'sends' | 'receives'): Map<string, ServiceEntry[]> => {
+  const index = new Map<string, ServiceEntry[]>();
+  for (const service of snapshot.resources.services) {
+    const pointers = service[direction] as Array<{ id: string }> | undefined;
+    if (!pointers) continue;
+    for (const pointer of pointers) {
+      let entries = index.get(pointer.id);
+      if (!entries) {
+        entries = [];
+        index.set(pointer.id, entries);
+      }
+      const entry: ServiceEntry = {
+        id: service.id as string,
+        version: service.version as string,
+      };
+      if (service.owners && Array.isArray(service.owners) && service.owners.length > 0) {
+        entry.owners = service.owners as string[];
+      }
+      entries.push(entry);
+    }
+  }
+  return index;
+};
+
+const getMessageTypeKey = (resourceId: string, type: string): string => `${type}:${resourceId}`;
+
+const buildLatestMessageVersionMap = (snapshot: CatalogSnapshot): Map<string, string> => {
+  const versions = new Map<string, string>();
+
+  for (const event of snapshot.resources.messages.events) {
+    versions.set(getMessageTypeKey(event.id as string, 'event'), event.version as string);
+  }
+  for (const command of snapshot.resources.messages.commands) {
+    versions.set(getMessageTypeKey(command.id as string, 'command'), command.version as string);
+  }
+  for (const query of snapshot.resources.messages.queries) {
+    versions.set(getMessageTypeKey(query.id as string, 'query'), query.version as string);
+  }
+
+  return versions;
+};
+
+const getTargetMessageVersion = (resourceChange: ResourceChange): string => {
+  if (resourceChange.changeType === 'versioned') {
+    return resourceChange.newVersion || resourceChange.version;
+  }
+  return resourceChange.version;
+};
+
+const pointerTargetsChangedVersion = (
+  pointer: { id: string; version?: string },
+  resourceChange: ResourceChange,
+  latestMessageVersions: Map<string, string>
+): boolean => {
+  if (pointer.id !== resourceChange.resourceId) return false;
+
+  const targetVersion = getTargetMessageVersion(resourceChange);
+  const pointerVersion = pointer.version;
+
+  if (!pointerVersion || pointerVersion === 'latest') {
+    const latestVersion = latestMessageVersions.get(getMessageTypeKey(resourceChange.resourceId, resourceChange.type));
+    if (!latestVersion) return true;
+    return latestVersion === targetVersion;
+  }
+
+  if (validRange(pointerVersion)) {
+    try {
+      return satisfies(targetVersion, pointerVersion);
+    } catch {
+      return false;
+    }
+  }
+
+  return pointerVersion === targetVersion;
+};
+
+const getServicesForSchemaChange = (
+  snapshot: CatalogSnapshot,
+  direction: 'sends' | 'receives',
+  resourceChange: ResourceChange,
+  latestMessageVersions: Map<string, string>
+): ServiceEntry[] => {
+  const matches: ServiceEntry[] = [];
+
+  for (const service of snapshot.resources.services) {
+    const pointers = service[direction] as Array<{ id: string; version?: string }> | undefined;
+    if (!pointers) continue;
+
+    const hasMatch = pointers.some((pointer) => pointerTargetsChangedVersion(pointer, resourceChange, latestMessageVersions));
+    if (!hasMatch) continue;
+
+    const entry: ServiceEntry = {
+      id: service.id as string,
+      version: service.version as string,
+    };
+
+    if (service.owners && Array.isArray(service.owners) && service.owners.length > 0) {
+      entry.owners = service.owners as string[];
+    }
+
+    matches.push(entry);
+  }
+
+  return matches;
+};
+
+const matchesSchemaChangeResource = (schemaChange: SchemaChange, resources: string[]): boolean => {
+  return resources.some((resource) => {
+    if (resource === '*') return true;
+    if (resource.startsWith('message:')) return schemaChange.resourceChange.resourceId === resource.slice(8);
+    if (resource.startsWith('consumes:'))
+      return schemaChange.consumerServices.some((service) => service.id === resource.slice(9));
+    if (resource.startsWith('produces:'))
+      return schemaChange.producerServices.some((service) => service.id === resource.slice(9));
+    if (resource.startsWith('service:')) return schemaChange.producerServices.some((service) => service.id === resource.slice(8));
+    return false;
+  });
+};
+
+const evaluateDeprecationRules = (
+  diff: SnapshotDiff,
+  config: GovernanceConfig,
+  targetSnapshot: CatalogSnapshot,
+  targetMessageSets: ServiceMessageSets,
+  baseSnapshot?: CatalogSnapshot
+): GovernanceResult[] => {
+  const deprecationRules = config.rules.filter((rule) => rule.when.includes('message_deprecated'));
+  if (deprecationRules.length === 0) return [];
+
+  const targetMessages = buildMessageMap(targetSnapshot);
+  const baseMessages = baseSnapshot ? buildMessageMap(baseSnapshot) : undefined;
+  const producerIndex = buildServiceIndex(targetSnapshot, 'sends');
+
+  // Find messages that were newly deprecated
+  const deprecatedResources = diff.resources.filter((rc) => {
+    if (!MESSAGE_RESOURCE_TYPES.has(rc.type)) return false;
+    if (!rc.changedFields?.includes('deprecated')) return false;
+
+    // Confirm the message is deprecated in the target (not un-deprecated)
+    const targetMessage = targetMessages.get(rc.resourceId);
+    if (!targetMessage || !targetMessage.deprecated) return false;
+
+    // Confirm it was NOT deprecated in the base
+    if (baseMessages) {
+      const baseMessage = baseMessages.get(rc.resourceId);
+      if (baseMessage && baseMessage.deprecated) return false;
+    }
+
+    return true;
+  });
+
+  if (deprecatedResources.length === 0) return [];
+
+  const results: GovernanceResult[] = [];
+
+  for (const rule of deprecationRules) {
+    const matched: DeprecationChange[] = [];
+
+    for (const rc of deprecatedResources) {
+      if (!matchesResourceId(rc.resourceId, undefined, rule.resources, targetMessageSets)) continue;
+
+      const producers = producerIndex.get(rc.resourceId) || [];
+      matched.push({ resourceChange: rc, producerServices: producers });
+    }
+
+    if (matched.length > 0) {
+      results.push({ rule, trigger: 'message_deprecated', matchedChanges: [], deprecationChanges: matched });
+    }
+  }
+
+  return results;
+};
+
+const evaluateSchemaChangeRules = (
+  diff: SnapshotDiff,
+  config: GovernanceConfig,
+  targetSnapshot: CatalogSnapshot
+): GovernanceResult[] => {
+  const schemaRules = config.rules.filter((rule) => rule.when.includes('schema_changed'));
+  if (schemaRules.length === 0) return [];
+
+  const schemaChangedResources = diff.resources.filter((rc) => {
+    if (!MESSAGE_RESOURCE_TYPES.has(rc.type)) return false;
+    return rc.changedFields?.includes('schemaHash');
+  });
+
+  if (schemaChangedResources.length === 0) return [];
+
+  const latestMessageVersions = buildLatestMessageVersionMap(targetSnapshot);
+  const schemaChanges = schemaChangedResources.map((resourceChange) => ({
+    resourceChange,
+    producerServices: getServicesForSchemaChange(targetSnapshot, 'sends', resourceChange, latestMessageVersions),
+    consumerServices: getServicesForSchemaChange(targetSnapshot, 'receives', resourceChange, latestMessageVersions),
+  }));
+
+  const results: GovernanceResult[] = [];
+
+  for (const rule of schemaRules) {
+    const matched = schemaChanges.filter((schemaChange) => matchesSchemaChangeResource(schemaChange, rule.resources));
+
+    if (matched.length > 0) {
+      results.push({ rule, trigger: 'schema_changed', matchedChanges: [], schemaChanges: matched });
+    }
+  }
+
+  return results;
+};
+
+const evaluateBreakingSchemaChangeRules = (
+  diff: SnapshotDiff,
+  config: GovernanceConfig,
+  targetSnapshot: CatalogSnapshot
+): GovernanceResult[] => {
+  const breakingRules = config.rules.filter((rule) => rule.when.includes('schema_breaking_change'));
+  if (breakingRules.length === 0) return [];
+
+  const strategy = config.compatibility?.strategy;
+  if (!strategy || strategy === 'NONE') return [];
+
+  const schemaChangedResources = diff.resources.filter((rc) => {
+    if (!MESSAGE_RESOURCE_TYPES.has(rc.type)) return false;
+    return rc.changedFields?.includes('schemaHash');
+  });
+
+  if (schemaChangedResources.length === 0) return [];
+
+  const latestMessageVersions = buildLatestMessageVersionMap(targetSnapshot);
+  const breakingSchemaChanges: BreakingSchemaChange[] = schemaChangedResources.map((resourceChange) => ({
+    resourceChange,
+    producerServices: getServicesForSchemaChange(targetSnapshot, 'sends', resourceChange, latestMessageVersions),
+    consumerServices: getServicesForSchemaChange(targetSnapshot, 'receives', resourceChange, latestMessageVersions),
+    breakingChanges: [],
+  }));
+
+  const results: GovernanceResult[] = [];
+
+  for (const rule of breakingRules) {
+    const matched = breakingSchemaChanges.filter((sc) => matchesSchemaChangeResource(sc, rule.resources));
+    if (matched.length > 0) {
+      results.push({ rule, trigger: 'schema_breaking_change', matchedChanges: [], breakingSchemaChanges: matched });
+    }
+  }
+
+  return results;
+};
+
+export const evaluateGovernanceRules = (
+  diff: SnapshotDiff,
+  config: GovernanceConfig,
+  targetSnapshot?: CatalogSnapshot,
+  baseSnapshot?: CatalogSnapshot
+): GovernanceResult[] => {
+  const results: GovernanceResult[] = [];
+  const targetMessageSets = targetSnapshot ? buildServiceMessageSets(targetSnapshot) : undefined;
+  const baseMessageSets = baseSnapshot ? buildServiceMessageSets(baseSnapshot) : undefined;
+
+  for (const rule of config.rules) {
+    for (const trigger of rule.when) {
+      const filter = TRIGGER_FILTERS[trigger];
+      if (!filter) continue;
+
+      // For removed triggers, resolve produces:/consumes: prefixes against
+      // the base snapshot where the relationship still existed.
+      const messageSets = REMOVED_TRIGGERS.has(trigger) && baseMessageSets ? baseMessageSets : targetMessageSets;
+
+      const matchedChanges = diff.relationships.filter(
+        (c) => filter(c) && matchesResourceId(c.resourceId, c.serviceId, rule.resources, messageSets)
+      );
+
+      if (matchedChanges.length > 0) {
+        results.push({ rule, trigger, matchedChanges });
+      }
+    }
+  }
+
+  // Evaluate deprecation rules separately (they operate on resource changes, not relationship changes)
+  if (targetSnapshot && targetMessageSets) {
+    results.push(...evaluateDeprecationRules(diff, config, targetSnapshot, targetMessageSets, baseSnapshot));
+    results.push(...evaluateSchemaChangeRules(diff, config, targetSnapshot));
+    results.push(...evaluateBreakingSchemaChangeRules(diff, config, targetSnapshot));
+  }
+
+  return results;
+};
+
+const PRODUCER_TRIGGERS: Set<GovernanceTrigger> = new Set(['producer_added', 'producer_removed']);
+
+export const isProducerTrigger = (trigger: GovernanceTrigger): boolean => PRODUCER_TRIGGERS.has(trigger);
+
+export const getChangeVerb = (trigger: GovernanceTrigger, changeType: 'added' | 'removed'): string => {
+  const producer = isProducerTrigger(trigger);
+  return changeType === 'added'
+    ? producer
+      ? 'now producing'
+      : 'now consuming'
+    : producer
+      ? 'no longer producing'
+      : 'no longer consuming';
+};
+
+export const resolveEnvVars = (value: string): string => {
+  return value.replace(/\$([A-Z_][A-Z0-9_]*)/g, (match, varName) => {
+    const envValue = process.env[varName];
+    if (envValue === undefined) {
+      throw new Error(`Environment variable ${varName} is not set`);
+    }
+    return envValue;
+  });
+};
+
+type SDK = ReturnType<typeof createSDK>;
+
+const readSchemaDetails = async (
+  sdk: SDK,
+  resourceId: string,
+  version: string,
+  type: string
+): Promise<{ content?: string; schemaPath?: string; schemaHash?: string }> => {
+  if (!MESSAGE_RESOURCE_TYPES.has(type)) return {};
+  try {
+    const schema = await sdk.getSchemaForMessage(resourceId, version);
+    if (!schema) return {};
+    return {
+      content: schema.schema,
+      schemaPath: schema.fileName,
+      schemaHash: createHash('sha256').update(schema.schema).digest('hex'),
+    };
+  } catch {
+    return {};
+  }
+};
+
+export const enrichSchemaContent = async (
+  results: GovernanceResult[],
+  baseCatalogDir: string,
+  targetCatalogDir: string,
+  compatibilityStrategy?: CompatibilityStrategy
+): Promise<void> => {
+  const baseSDK = createSDK(baseCatalogDir);
+  const targetSDK = createSDK(targetCatalogDir);
+
+  const promises: Promise<void>[] = [];
+
+  for (const result of results) {
+    if (!result.schemaChanges) continue;
+    for (const sc of result.schemaChanges) {
+      const { resourceId, version, type, changeType, previousVersion, newVersion } = sc.resourceChange;
+      const baseVersion = changeType === 'versioned' ? previousVersion || version : version;
+      const targetVersion = changeType === 'versioned' ? newVersion || version : version;
+      promises.push(
+        (async () => {
+          const [before, after] = await Promise.all([
+            readSchemaDetails(baseSDK, resourceId, baseVersion, type),
+            readSchemaDetails(targetSDK, resourceId, targetVersion, type),
+          ]);
+          sc.before = before.content;
+          sc.after = after.content;
+          sc.beforeSchemaPath = before.schemaPath;
+          sc.afterSchemaPath = after.schemaPath;
+          sc.beforeSchemaHash = before.schemaHash;
+          sc.afterSchemaHash = after.schemaHash;
+        })()
+      );
+    }
+  }
+
+  for (const result of results) {
+    if (!result.breakingSchemaChanges || !compatibilityStrategy) continue;
+    for (const bsc of result.breakingSchemaChanges) {
+      const { resourceId, version, type, changeType, previousVersion, newVersion } = bsc.resourceChange;
+      const baseVersion = changeType === 'versioned' ? previousVersion || version : version;
+      const targetVersion = changeType === 'versioned' ? newVersion || version : version;
+      promises.push(
+        (async () => {
+          const [before, after] = await Promise.all([
+            readSchemaDetails(baseSDK, resourceId, baseVersion, type),
+            readSchemaDetails(targetSDK, resourceId, targetVersion, type),
+          ]);
+          bsc.before = before.content;
+          bsc.after = after.content;
+          bsc.beforeSchemaPath = before.schemaPath;
+          bsc.afterSchemaPath = after.schemaPath;
+          bsc.beforeSchemaHash = before.schemaHash;
+          bsc.afterSchemaHash = after.schemaHash;
+
+          if (before.content && after.content) {
+            let beforeSchema: object | undefined;
+            let afterSchema: object | undefined;
+            try {
+              beforeSchema = JSON.parse(before.content);
+              afterSchema = JSON.parse(after.content);
+            } catch {
+              // Schema is not valid JSON — skip breaking change detection
+            }
+            if (beforeSchema && afterSchema) {
+              bsc.breakingChanges = detectBreakingChanges(beforeSchema, afterSchema, compatibilityStrategy);
+            }
+          }
+        })()
+      );
+    }
+  }
+
+  await Promise.all(promises);
+};
diff --git a/packages/cli/src/cli/governance/types.ts b/packages/cli/src/cli/governance/types.ts
new file mode 100644
index 000000000..31b709c31
--- /dev/null
+++ b/packages/cli/src/cli/governance/types.ts
@@ -0,0 +1,67 @@
+import type { RelationshipChange, ResourceChange } from '@eventcatalog/sdk';
+
+export type GovernanceTrigger =
+  | 'consumer_added'
+  | 'consumer_removed'
+  | 'producer_added'
+  | 'producer_removed'
+  | 'message_deprecated'
+  | 'schema_changed'
+  | 'schema_breaking_change';
+
+export type GovernanceAction =
+  | { type: 'console' }
+  | { type: 'webhook'; url: string; headers?: Record<string, string> }
+  | { type: 'fail'; message?: string };
+
+export type GovernanceRule = {
+  name: string;
+  when: GovernanceTrigger[];
+  resources: string[];
+  actions: GovernanceAction[];
+};
+
+export type GovernanceConfig = {
+  compatibility?: {
+    strategy: import('@eventcatalog/breaking-changes').CompatibilityStrategy;
+  };
+  rules: GovernanceRule[];
+};
+
+export type DeprecationChange = {
+  resourceChange: ResourceChange;
+  producerServices: Array<{ id: string; version: string; owners?: string[] }>;
+};
+
+export type SchemaChange = {
+  resourceChange: ResourceChange;
+  consumerServices: Array<{ id: string; version: string; owners?: string[] }>;
+  producerServices: Array<{ id: string; version: string; owners?: string[] }>;
+  before?: string;
+  after?: string;
+  beforeSchemaPath?: string;
+  afterSchemaPath?: string;
+  beforeSchemaHash?: string;
+  afterSchemaHash?: string;
+};
+
+export type BreakingSchemaChange = SchemaChange & {
+  breakingChanges: import('@eventcatalog/breaking-changes').BreakingChange[];
+};
+
+export type GovernanceResult = {
+  rule: GovernanceRule;
+  trigger: GovernanceTrigger;
+  matchedChanges: RelationshipChange[];
+  deprecationChanges?: DeprecationChange[];
+  schemaChanges?: SchemaChange[];
+  breakingSchemaChanges?: BreakingSchemaChange[];
+  failed?: boolean;
+  failMessages?: string[];
+};
+
+export type GovernanceCheckResult = {
+  output: string;
+  exitCode: number;
+  failures: Array<{ ruleName: string; messages: string[] }>;
+};
diff --git a/packages/cli/src/cli/import.ts b/packages/cli/src/cli/import.ts
new file mode 100644
index 000000000..1ea1089df
--- /dev/null
+++ b/packages/cli/src/cli/import.ts
@@ -0,0 +1,982 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync, copyFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline';
+import matter from 'gray-matter';
+import createSDK from '@eventcatalog/sdk';
+import { DSL_MANAGED_KEYS_BY_TYPE } from './dsl-managed-keys';
+
+export interface ImportOptions {
+  files?: string[];
+  stdin?: boolean;
+  dryRun?: boolean;
+  flat?: boolean;
+  noInit?: boolean;
+  dir: string;
+}
+
+interface ParsedResource {
+  type: string;
+  id: string;
+  version?: string;
+  frontmatter: Record<string, any>;
+  markdown: string;
+  path: string;
+}
+
+interface ImportResult {
+  created: string[];
+  updated: string[];
+  versioned: string[];
+  errors: string[];
+}
+
+function normalizeImportedFrontmatter(type: string, frontmatter: Record<string, any>): Record<string, any> {
+  const normalized = { ...frontmatter };
+
+  // SDK/container schema uses snake_case fields.
+  if (type === 'container') {
+    if (normalized.container_type === undefined && normalized.containerType !== undefined) {
+      normalized.container_type = normalized.containerType;
+      delete normalized.containerType;
+    }
+    if (normalized.access_mode === undefined && normalized.accessMode !== undefined) {
+      normalized.access_mode = normalized.accessMode;
+      delete normalized.accessMode;
+    }
+    // Default container_type to 'database' if not specified in the DSL
+    if (!normalized.container_type) {
+      normalized.container_type = 'database';
+    }
+  }
+
+  return normalized;
+}
+
+function toFrontmatter(resource: any): Record<string, any> {
+  if (!resource || typeof resource !== 'object') return {};
+  const { markdown: _markdown, ...frontmatter } = resource;
+  return frontmatter;
+}
+
+function mergeImportedFrontmatter(
+  type: string,
+  incomingFrontmatter: Record<string, any>,
+  existing?: any,
+  latest?: any
+): Record<string, any> {
+  const normalizedIncoming = normalizeImportedFrontmatter(type, incomingFrontmatter);
+  const managedKeys = DSL_MANAGED_KEYS_BY_TYPE[type];
+
+  if (!managedKeys) {
+    return normalizedIncoming;
+  }
+
+  const baseFrontmatter = toFrontmatter(existing ?? latest);
+  const preservedFrontmatter = { ...baseFrontmatter };
+
+  for (const key of managedKeys) {
+    delete preservedFrontmatter[key];
+  }
+
+  return {
+    ...preservedFrontmatter,
+    ...normalizedIncoming,
+  };
+}
+
+const RESOURCE_TYPE_FROM_FOLDER: Record<string, string> = {
+  events: 'event',
+  commands: 'command',
+  queries: 'query',
+  services: 'service',
+  domains: 'domain',
+  channels: 'channel',
+  flows: 'flow',
+  containers: 'container',
+  'data-products': 'dataProduct',
+  diagrams: 'diagram',
+  users: 'user',
+  teams: 'team',
+};
+
+async function parseDSL(
+  source: string,
+  options?: { nested?: boolean }
+): Promise<{ outputs: { path: string; content: string }[]; program: any }> {
+  const { createEcServices, compile } = await import('@eventcatalog/language-server');
+  const { EmptyFileSystem, URI } = await import('langium');
+
+  const services = createEcServices(EmptyFileSystem);
+  const uri = URI.parse(`file:///import-${Date.now()}.ec`);
+  const document = services.shared.workspace.LangiumDocumentFactory.fromString(source, uri);
+  services.shared.workspace.LangiumDocuments.addDocument(document);
+  await services.shared.workspace.DocumentBuilder.build([document]);
+
+  const parserErrors = document.parseResult.parserErrors;
+  if (parserErrors.length > 0) {
+    const messages = parserErrors.map((e: any) => `  Line ${e.token?.startLine ?? '?'}: ${e.message}`);
+    throw new Error(`Parse errors:\n${messages.join('\n')}`);
+  }
+
+  const program = document.parseResult.value;
+  const outputs = compile(program, { nested: options?.nested });
+
+  try {
+    services.shared.workspace.LangiumDocuments.deleteDocument(uri);
+  } catch {
+    // Ignore cleanup errors
+  }
+
+  return { outputs, program };
+}
+
+/**
+ * Extract the resource type folder from a path that may be nested.
+ * e.g. "events/OrderCreated/..." → "events"
+ * e.g. "domains/Payment/services/OrderService/..." → "services"
+ * e.g. "domains/Payment/services/OrderService/events/X/..." → "events"
+ * e.g. "users/jdoe.md" → "users"
+ *
+ * Walk the segments and return the last known resource-type folder.
+ */
+function extractResourceTypeFolder(path: string): string {
+  const segments = path.split('/');
+  let lastTypeFolder = segments[0];
+  for (const seg of segments) {
+    if (RESOURCE_TYPE_FROM_FOLDER[seg]) {
+      lastTypeFolder = seg;
+    }
+  }
+  return lastTypeFolder;
+}
+
+function parseCompiledOutput(output: { path: string; content: string }): ParsedResource {
+  const { data: frontmatter, content: markdown } = matter(output.content);
+
+  const typeFolder = extractResourceTypeFolder(output.path);
+  const type = RESOURCE_TYPE_FROM_FOLDER[typeFolder] || typeFolder;
+
+  return {
+    type,
+    id: frontmatter.id,
+    version: frontmatter.version,
+    frontmatter,
+    markdown: markdown.trim(),
+    path: output.path,
+  };
+}
+
+const MESSAGE_TYPE_FOLDER: Record<string, string> = {
+  event: 'events',
+  command: 'commands',
+  query: 'queries',
+  channel: 'channels',
+};
+
+const DEFAULT_STUB_VERSION = '0.0.1';
+const NO_VERSION_KEY = '__no_version__';
+
+function getResourceNameKey(type: string, id: string): string {
+  return `${type}:${id}`;
+}
+
+function getResourceVersionKey(type: string, id: string, version?: string): string {
+  return `${type}:${id}@${version || NO_VERSION_KEY}`;
+}
+
+function hasReferenceStatements(source: string): boolean {
+  return /\b(?:sends|receives|writes-to|reads-from)\b/.test(source);
+}
+
+/**
+ * Extract resource stubs from service references that weren't compiled as standalone resources.
+ * Uses the DSL AST to determine message types accurately.
+ */
+async function extractMessageStubs(program: any, compiledIds: Set<string>, nested: boolean = false): Promise<ParsedResource[]> {
+  const stubs: ParsedResource[] = [];
+  const stubIds = new Set<string>();
+
+  function processDefinitions(definitions: any[], parentPath: string = '') {
+    for (const def of definitions) {
+      // Handle visualizer wrappers
+      if (def.$type === 'VisualizerDef' && def.body) {
+        processDefinitions(def.body, parentPath);
+        continue;
+      }
+
+      // Handle domains — recurse into their services with domain parentPath
+      if (def.$type === 'DomainDef') {
+        const domainPath = nested ? `domains/${def.name}` : '';
+        const domainBody = def.body || [];
+
+        // Process services inside the domain
+        const domainServices = domainBody.filter((d: any) => d.$type === 'ServiceDef');
+        processDefinitions(domainServices, domainPath);
+
+        // Process subdomains
+        const subdomains = domainBody.filter((d: any) => d.$type === 'SubdomainDef');
+        for (const sub of subdomains) {
+          const subPath = nested ? `domains/${def.name}/subdomains/${sub.name}` : '';
+          const subServices = (sub.body || []).filter((d: any) => d.$type === 'ServiceDef');
+          processDefinitions(subServices, subPath);
+        }
+        continue;
+      }
+
+      if (def.$type !== 'ServiceDef') continue;
+
+      const servicePath = nested ? (parentPath ? `${parentPath}/services/${def.name}` : `services/${def.name}`) : '';
+
+      const body = def.body || [];
+      for (const stmt of body) {
+        if (stmt.$type === 'SendsStmt' || stmt.$type === 'ReceivesStmt') {
+          const msgType = stmt.messageType; // 'event', 'command', or 'query'
+          const msgName = stmt.messageName;
+          const hasBody = stmt.body && stmt.body.length > 0;
+          const version = stmt.version || DEFAULT_STUB_VERSION;
+
+          if (!hasBody) {
+            const folder = MESSAGE_TYPE_FOLDER[msgType];
+            if (folder) {
+              const key = getResourceVersionKey(msgType, msgName, version);
+              const anyVersionKey = getResourceNameKey(msgType, msgName);
+
+              // For explicit refs (e.g. Event@2.0.0), require exact version match.
+              // For unversioned refs, treat any compiled version as satisfying the reference.
+              if (!compiledIds.has(key) && !stubIds.has(key) && !(!stmt.version && compiledIds.has(anyVersionKey))) {
+                const stubFolder = nested && servicePath ? `${servicePath}/${folder}` : folder;
+
+                stubIds.add(key);
+                stubs.push({
+                  type: msgType,
+                  id: msgName,
+                  version,
+                  frontmatter: {
+                    id: msgName,
+                    name: msgName,
+                    version,
+                  },
+                  markdown: '',
+                  path: `${stubFolder}/${msgName}/versioned/${version}/index.md`,
+                });
+              }
+            }
+          }
+
+          // Create channel stubs for to/from references
+          if (stmt.channelClause) {
+            const channels = stmt.channelClause.channels || [];
+            for (const ch of channels) {
+              const chName = ch.channelName;
+              const chVersion = ch.channelVersion || DEFAULT_STUB_VERSION;
+              const chKey = getResourceVersionKey('channel', chName, chVersion);
+              const chAnyVersionKey = getResourceNameKey('channel', chName);
+              if (compiledIds.has(chKey) || stubIds.has(chKey)) continue;
+              if (!ch.channelVersion && compiledIds.has(chAnyVersionKey)) continue;
+
+              const chFolder = nested && parentPath ? `${parentPath}/channels` : 'channels';
+              stubIds.add(chKey);
+              stubs.push({
+                type: 'channel',
+                id: chName,
+                version: chVersion,
+                frontmatter: {
+                  id: chName,
+                  name: chName,
+                  version: chVersion,
+                },
+                markdown: '',
+                path: `${chFolder}/${chName}/versioned/${chVersion}/index.md`,
+              });
+            }
+          }
+          continue;
+        }
+
+        if (stmt.$type === 'WritesToStmt' || stmt.$type === 'ReadsFromStmt') {
+          const containerName = stmt.ref?.name;
+          if (!containerName) continue;
+
+          const containerVersion = stmt.ref?.version || DEFAULT_STUB_VERSION;
+          const containerKey = getResourceVersionKey('container', containerName, containerVersion);
+          const containerAnyVersionKey = getResourceNameKey('container', containerName);
+          if (compiledIds.has(containerKey) || stubIds.has(containerKey)) continue;
+          if (!stmt.ref?.version && compiledIds.has(containerAnyVersionKey)) continue;
+
+          const containerFolder = nested && parentPath ? `${parentPath}/containers` : 'containers';
+          stubIds.add(containerKey);
+          stubs.push({
+            type: 'container',
+            id: containerName,
+            version: containerVersion,
+            frontmatter: {
+              id: containerName,
+              name: containerName,
+              version: containerVersion,
+            },
+            markdown: '',
+            path: `${containerFolder}/${containerName}/versioned/${containerVersion}/index.md`,
+          });
+        }
+      }
+    }
+  }
+
+  processDefinitions(program.definitions);
+
+  return stubs;
+}
+
+function getVersionFromBody(body: any[] | undefined): string | undefined {
+  if (!body) return undefined;
+  const versionStmt = body.find((stmt) => stmt?.$type === 'VersionStmt');
+  return versionStmt?.value;
+}
+
+function buildServiceOutputPath(serviceName: string, body: any[] | undefined, nested: boolean, parentPath: string): string {
+  const folder = nested && parentPath ? `${parentPath}/services` : 'services';
+  const version = getVersionFromBody(body);
+  if (version) return `${folder}/${serviceName}/versioned/${version}/index.md`;
+  return `${folder}/${serviceName}/index.md`;
+}
+
+function extractServiceContainerRefs(
+  program: any,
+  nested: boolean = false
+): Map<string, { writesTo?: Array<{ id: string; version?: string }>; readsFrom?: Array<{ id: string; version?: string }> }> {
+  const refsByPath = new Map<
+    string,
+    { writesTo?: Array<{ id: string; version?: string }>; readsFrom?: Array<{ id: string; version?: string }> }
+  >();
+
+  function processDefinitions(definitions: any[], parentPath: string = ''): void {
+    for (const def of definitions || []) {
+      if (def.$type === 'VisualizerDef' && def.body) {
+        processDefinitions(def.body, parentPath);
+        continue;
+      }
+
+      if (def.$type === 'DomainDef') {
+        const domainPath = nested ? `domains/${def.name}` : '';
+        const domainBody = def.body || [];
+        const domainServices = domainBody.filter((d: any) => d.$type === 'ServiceDef');
+        processDefinitions(domainServices, domainPath);
+
+        const subdomains = domainBody.filter((d: any) => d.$type === 'SubdomainDef');
+        for (const sub of subdomains) {
+          const subPath = nested ? `domains/${def.name}/subdomains/${sub.name}` : '';
+          const subServices = (sub.body || []).filter((d: any) => d.$type === 'ServiceDef');
+          processDefinitions(subServices, subPath);
+        }
+        continue;
+      }
+
+      if (def.$type !== 'ServiceDef') continue;
+
+      const body = def.body || [];
+      const writesTo = body
+        .filter((stmt: any) => stmt.$type === 'WritesToStmt' && stmt.ref?.name)
+        .map((stmt: any) => ({
+          id: stmt.ref.name,
+          ...(stmt.ref.version ? { version: stmt.ref.version } : {}),
+        }));
+
+      const readsFrom = body
+        .filter((stmt: any) => stmt.$type === 'ReadsFromStmt' && stmt.ref?.name)
+        .map((stmt: any) => ({
+          id: stmt.ref.name,
+          ...(stmt.ref.version ? { version: stmt.ref.version } : {}),
+        }));
+
+      if (writesTo.length === 0 && readsFrom.length === 0) continue;
+
+      const path = buildServiceOutputPath(def.name, body, nested, parentPath);
+      refsByPath.set(path, {
+        ...(writesTo.length > 0 ? { writesTo } : {}),
+        ...(readsFrom.length > 0 ? { readsFrom } : {}),
+      });
+    }
+  }
+
+  processDefinitions(program.definitions || []);
+  return refsByPath;
+}
+
+/**
+ * Map resource type to the base folder used by the SDK writer.
+ * The SDK creates writers with type-prefixed directories, e.g.
+ *   writeService → catalogDir/services/
+ *   writeEvent → catalogDir/events/
+ * So any custom path must be relative to that base.
+ */
+const SDK_WRITER_BASE: Record<string, string> = {
+  event: 'events',
+  command: 'commands',
+  query: 'queries',
+  service: 'services',
+  domain: 'domains',
+  channel: 'channels',
+  container: 'containers',
+  dataProduct: 'data-products',
+  diagram: 'diagrams',
+  team: 'teams',
+  user: 'users',
+};
+
+/**
+ * Extract the SDK-compatible path option from a compiler output path.
+ * The SDK writer already prefixes with the type folder, so we need to
+ * return a path relative to that base.
+ *
+ * e.g. for type "service":
+ *   "services/OrderService/versioned/1.0.0/index.md" → "" (default behavior)
+ *   "domains/Payment/services/OrderService/versioned/1.0.0/index.md"
+ *     → "../domains/Payment/services/OrderService"
+ *
+ * Returns empty string when the resource is at its default location.
+ */
+function extractSdkPath(compiledPath: string, resourceType: string): string {
+  // Strip versioned/X/index.md or index.md or .md suffix
+  const dirPath = compiledPath
+    .replace(/\/versioned\/[^/]+\/index\.md$/, '')
+    .replace(/\/index\.md$/, '')
+    .replace(/\.md$/, '');
+
+  const baseFolder = SDK_WRITER_BASE[resourceType];
+  if (!baseFolder) return '';
+
+  // If path starts with the type's default folder, strip it
+  // e.g. "services/OrderService" → "OrderService" (default SDK behavior handles this)
+  if (dirPath.startsWith(`${baseFolder}/`)) {
+    const relative = dirPath.slice(baseFolder.length + 1);
+    // If it's just the resource name (no nesting), return empty to use default
+    if (!relative.includes('/')) return '';
+    return relative;
+  }
+
+  // Path is nested under a different folder (e.g. domains/X/services/Y)
+  // Need to go up one level from the SDK writer's base directory
+  return `../${dirPath}`;
+}
+
+const TYPES_WITH_NODE_GRAPH = new Set(['event', 'command', 'query', 'service', 'domain', 'channel', 'flow']);
+
+type SDK = ReturnType<typeof createSDK>;
+
+function getWriter(sdk: SDK, type: string): ((resource: any, options?: any) => Promise<void>) | null {
+  switch (type) {
+    case 'event':
+      return sdk.writeEvent;
+    case 'command':
+      return sdk.writeCommand;
+    case 'query':
+      return sdk.writeQuery;
+    case 'service':
+      return sdk.writeService;
+    case 'domain':
+      return sdk.writeDomain;
+    case 'channel':
+      return sdk.writeChannel;
+    case 'container':
+      return sdk.writeDataStore;
+    case 'dataProduct':
+      return sdk.writeDataProduct;
+    case 'diagram':
+      return sdk.writeDiagram;
+    case 'team':
+      return sdk.writeTeam;
+    case 'user':
+      return sdk.writeUser;
+    default:
+      return null;
+  }
+}
+
+function getReader(sdk: SDK, type: string): ((id: string, version?: string) => Promise<any>) | null {
+  switch (type) {
+    case 'event':
+      return sdk.getEvent;
+    case 'command':
+      return sdk.getCommand;
+    case 'query':
+      return sdk.getQuery;
+    case 'service':
+      return sdk.getService;
+    case 'domain':
+      return sdk.getDomain;
+    case 'channel':
+      return sdk.getChannel;
+    case 'container':
+      return sdk.getDataStore;
+    case 'dataProduct':
+      return sdk.getDataProduct;
+    case 'diagram':
+      return sdk.getDiagram;
+    case 'team':
+      return sdk.getTeam;
+    case 'user':
+      return sdk.getUser;
+    default:
+      return null;
+  }
+}
+
+export function promptConfirm(message: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`${message} `, (answer) => {
+      rl.close();
+      const normalized = answer.trim().toLowerCase();
+      resolve(normalized === '' || normalized === 'y' || normalized === 'yes');
+    });
+  });
+}
+
+export function promptInput(message: string, defaultValue: string): Promise<string> {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`${message} `, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue);
+    });
+  });
+}
+
+export function initCatalog(dir: string, organizationName: string = 'My Organization'): void {
+  const catalogDir = resolve(dir);
+  mkdirSync(catalogDir, { recursive: true });
+
+  // package.json
+  const packageJson = {
+    name: 'my-catalog',
+    version: '0.1.0',
+    private: true,
+    scripts: {
+      dev: 'eventcatalog dev',
+      build: 'eventcatalog build',
+      start: 'eventcatalog start',
+      preview: 'eventcatalog preview',
+      generate: 'eventcatalog generate',
+      lint: 'eventcatalog-linter',
+      test: 'echo "Error: no test specified" && exit 1',
+    },
+    dependencies: {
+      '@eventcatalog/core': 'latest',
+      '@eventcatalog/linter': 'latest',
+    },
+  };
+  writeFileSync(join(catalogDir, 'package.json'), JSON.stringify(packageJson, null, 2) + '\n', 'utf-8');
+
+  // eventcatalog.config.js
+  const cId = randomUUID();
+  const config = `/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  title: 'EventCatalog',
+  tagline: 'Discover, Explore and Document your Event Driven Architectures',
+  organizationName: '${organizationName}',
+  homepageLink: 'https://eventcatalog.dev/',
+  output: 'static',
+  trailingSlash: false,
+  base: '/',
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'EventCatalog',
+  },
+  cId: '${cId}',
+};
+`;
+  writeFileSync(join(catalogDir, 'eventcatalog.config.js'), config, 'utf-8');
+
+  // .gitignore
+  const gitignore = `# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.astro
+out
+dist
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.eventcatalog-core
+
+.env
+.env-*
+`;
+  writeFileSync(join(catalogDir, '.gitignore'), gitignore, 'utf-8');
+
+  // .env
+  const envFile = `# EventCatalog Scale License Key, if you want to unlock the scale features
+# You can get a 14 day trial license key from https://eventcatalog.cloud
+
+EVENTCATALOG_SCALE_LICENSE_KEY=
+
+# Optional key if you are using EventCatalog Chat with OpenAI Models.
+# You need to set \`output\` to \`server\` in your eventcatalog.config.js file.
+# See documentation for more details: https://www.eventcatalog.dev/features/ai-assistant
+OPENAI_API_KEY=
+`;
+  writeFileSync(join(catalogDir, '.env'), envFile, 'utf-8');
+
+  // .npmrc
+  writeFileSync(join(catalogDir, '.npmrc'), 'strict-peer-dependencies=false\n', 'utf-8');
+
+  // public/logo.png
+  mkdirSync(join(catalogDir, 'public'), { recursive: true });
+  copyFileSync(join(__dirname, 'logo.png'), join(catalogDir, 'public', 'logo.png'));
+}
+
+export async function importDSL(options: ImportOptions): Promise<string> {
+  const { files, stdin = false, dryRun = false, flat = false, noInit = false, dir } = options;
+  const nested = !flat;
+
+  let source: string;
+
+  if (stdin) {
+    source = await readStdin();
+  } else if (files && files.length > 0) {
+    const parts: string[] = [];
+    for (const file of files) {
+      const filepath = resolve(file);
+      if (!existsSync(filepath)) {
+        throw new Error(`File not found: ${filepath}`);
+      }
+      parts.push(readFileSync(filepath, 'utf-8'));
+    }
+    source = parts.join('\n\n');
+  } else {
+    throw new Error('Either provide .ec file paths or use --stdin');
+  }
+
+  if (!source.trim()) {
+    throw new Error('No DSL content to import');
+  }
+
+  // Check if catalog needs initialization
+  const catalogDir = resolve(dir);
+  let didInit = false;
+  if (!noInit && !existsSync(join(catalogDir, 'eventcatalog.config.js')) && process.stdin.isTTY) {
+    const confirmed = await promptConfirm(`Initialize a new EventCatalog at ${catalogDir}? (Y/n)`);
+    if (confirmed) {
+      const organizationName = await promptInput('Organization name (My Organization):', 'My Organization');
+      initCatalog(dir, organizationName);
+      didInit = true;
+    }
+  }
+
+  const parsed = await parseDSL(source, { nested });
+  const outputs = parsed.outputs;
+
+  if (outputs.length === 0) {
+    throw new Error('No resources found in DSL content');
+  }
+
+  const sdk = createSDK(catalogDir);
+  const result: ImportResult = { created: [], updated: [], versioned: [], errors: [] };
+  const readerCache = new Map<string, Promise<any>>();
+
+  const readResourceCached = async (
+    reader: ((id: string, version?: string) => Promise<any>) | null,
+    type: string,
+    id: string,
+    version?: string
+  ): Promise<any> => {
+    if (!reader) return undefined;
+    const cacheKey = getResourceVersionKey(type, id, version);
+    if (!readerCache.has(cacheKey)) {
+      readerCache.set(
+        cacheKey,
+        reader(id, version).catch(() => undefined)
+      );
+    }
+    return await readerCache.get(cacheKey)!;
+  };
+
+  const invalidateReaderCache = (type: string, id: string, version?: string): void => {
+    // We only read "latest" (no version) and the current version in this import path,
+    // so targeted invalidation avoids scanning the full cache for every write.
+    readerCache.delete(getResourceVersionKey(type, id));
+    readerCache.delete(getResourceVersionKey(type, id, version));
+  };
+
+  const resources = outputs.map(parseCompiledOutput);
+  const serviceContainerRefsByPath = extractServiceContainerRefs(parsed.program, nested);
+
+  for (const resource of resources) {
+    if (resource.type !== 'service') continue;
+    const refs = serviceContainerRefsByPath.get(resource.path);
+    if (!refs) continue;
+    resource.frontmatter = {
+      ...resource.frontmatter,
+      ...refs,
+    };
+  }
+
+  // Create stub resources for referenced messages that weren't compiled as standalone
+  const compiledIds = new Set<string>();
+  for (const resource of resources) {
+    compiledIds.add(getResourceNameKey(resource.type, resource.id));
+    compiledIds.add(getResourceVersionKey(resource.type, resource.id, resource.version));
+  }
+  const stubs = hasReferenceStatements(source) ? await extractMessageStubs(parsed.program, compiledIds, nested) : [];
+  resources.push(...stubs);
+
+  for (const resource of resources) {
+    const label = resource.version ? `${resource.type} ${resource.id}@${resource.version}` : `${resource.type} ${resource.id}`;
+
+    if (dryRun) {
+      const reader = getReader(sdk, resource.type);
+      if (reader) {
+        const existing = await readResourceCached(reader, resource.type, resource.id, resource.version);
+        if (existing) {
+          result.updated.push(label);
+        } else {
+          const latest = await readResourceCached(reader, resource.type, resource.id);
+          if (latest && latest.version && latest.version !== resource.version) {
+            result.versioned.push(`${resource.type} ${resource.id}@${latest.version}`);
+          }
+          result.created.push(label);
+        }
+      } else {
+        result.created.push(label);
+      }
+      continue;
+    }
+
+    const writer = getWriter(sdk, resource.type);
+    if (!writer) {
+      result.errors.push(`${label}: unsupported resource type '${resource.type}'`);
+      continue;
+    }
+
+    try {
+      const reader = getReader(sdk, resource.type);
+      const existing = await readResourceCached(reader, resource.type, resource.id, resource.version);
+      const latest = !existing && resource.version ? await readResourceCached(reader, resource.type, resource.id) : undefined;
+      const versionedFrom =
+        !existing && resource.version && latest?.version && latest.version !== resource.version ? latest.version : undefined;
+
+      const incomingMarkdown = resource.markdown;
+      const hasIncomingMarkdown = incomingMarkdown.trim().length > 0;
+      let markdown = incomingMarkdown;
+
+      // Preserve existing markdown when DSL import has no markdown body.
+      if (!hasIncomingMarkdown) {
+        if (existing?.markdown) {
+          markdown = existing.markdown;
+        } else if (!existing && latest?.markdown) {
+          // If importing a newer version without markdown, carry forward latest markdown.
+          markdown = latest.markdown;
+        }
+      }
+
+      // Add <NodeGraph /> to markdown for newly created resources (not updates)
+      if (!existing && TYPES_WITH_NODE_GRAPH.has(resource.type)) {
+        if (!markdown) {
+          markdown = '<NodeGraph />';
+        } else if (!markdown.includes('<NodeGraph />')) {
+          markdown = `${markdown}\n\n<NodeGraph />`;
+        }
+      }
+
+      const resourceData = {
+        ...mergeImportedFrontmatter(resource.type, resource.frontmatter, existing, latest),
+        markdown,
+      };
+
+      // If resource already exists, write with default SDK behavior (existing location).
+      // For new resources in nested mode, extract directory from compiler path.
+      const writeOptions: Record<string, any> = {
+        override: true,
+        versionExistingContent: Boolean(versionedFrom),
+      };
+
+      if (!existing && nested) {
+        const sdkPath = extractSdkPath(resource.path, resource.type);
+        if (sdkPath) {
+          writeOptions.path = sdkPath;
+        }
+      }
+
+      await writer(resourceData, writeOptions);
+      invalidateReaderCache(resource.type, resource.id, resource.version);
+
+      if (existing) {
+        result.updated.push(label);
+      } else {
+        result.created.push(label);
+        if (versionedFrom) {
+          result.versioned.push(`${resource.type} ${resource.id}@${versionedFrom}`);
+        }
+      }
+    } catch (error) {
+      result.errors.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  let output = formatResult(result, dryRun);
+  if (didInit) {
+    output += `  Tip: Run 'npm install' in ${catalogDir} to install dependencies\n`;
+  }
+  return output;
+}
+
+// ANSI color helpers
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m',
+};
+
+const TYPE_CONFIG: Record<string, { color: string; label: string; order: number }> = {
+  domain: { color: c.magenta, label: 'domain', order: 0 },
+  service: { color: c.blue, label: 'service', order: 1 },
+  event: { color: c.green, label: 'event', order: 2 },
+  command: { color: c.yellow, label: 'command', order: 3 },
+  query: { color: c.cyan, label: 'query', order: 4 },
+  channel: { color: c.gray, label: 'channel', order: 5 },
+  flow: { color: c.white, label: 'flow', order: 6 },
+  container: { color: c.white, label: 'container', order: 7 },
+  dataProduct: { color: c.white, label: 'data product', order: 8 },
+  diagram: { color: c.white, label: 'diagram', order: 9 },
+  user: { color: c.blue, label: 'user', order: 10 },
+  team: { color: c.blue, label: 'team', order: 11 },
+};
+
+const DEFAULT_TYPE_CONFIG = { color: c.white, label: 'resource', order: 99 };
+
+/**
+ * Parse a label like "event OrderCreated@1.0.0" into { type, name }.
+ */
+function parseLabel(label: string): { type: string; name: string } {
+  const spaceIdx = label.indexOf(' ');
+  if (spaceIdx === -1) return { type: '', name: label };
+  return { type: label.slice(0, spaceIdx), name: label.slice(spaceIdx + 1) };
+}
+
+/**
+ * Group labels by resource type, sorted by type order then alphabetically.
+ */
+function groupByType(labels: string[]): Map<string, string[]> {
+  const groups = new Map<string, string[]>();
+  for (const label of labels) {
+    const { type, name } = parseLabel(label);
+    if (!groups.has(type)) groups.set(type, []);
+    groups.get(type)!.push(name);
+  }
+  const sorted = new Map(
+    [...groups.entries()].sort((a, b) => {
+      const orderA = (TYPE_CONFIG[a[0]] || DEFAULT_TYPE_CONFIG).order;
+      const orderB = (TYPE_CONFIG[b[0]] || DEFAULT_TYPE_CONFIG).order;
+      return orderA - orderB;
+    })
+  );
+  for (const [, names] of sorted) {
+    names.sort();
+  }
+  return sorted;
+}
+
+/**
+ * Format a type badge like "  event  " with background color.
+ */
+function typeBadge(type: string): string {
+  const cfg = TYPE_CONFIG[type] || DEFAULT_TYPE_CONFIG;
+  const padded = ` ${cfg.label} `;
+  // Use reverse video for a "badge" effect: swaps fg/bg
+  return `${cfg.color}\x1b[7m${padded}${c.reset}`;
+}
+
+function formatResourceList(labels: string[]): string[] {
+  const lines: string[] = [];
+  const groups = groupByType(labels);
+
+  for (const [type, names] of groups) {
+    const cfg = TYPE_CONFIG[type] || DEFAULT_TYPE_CONFIG;
+    const plural = names.length === 1 ? cfg.label : `${cfg.label}s`;
+    lines.push('');
+    lines.push(`   ${typeBadge(type)} ${c.dim}${names.length} ${plural}${c.reset}`);
+    for (const name of names) {
+      lines.push(`   ${cfg.color}│${c.reset}  ${name}`);
+    }
+  }
+  return lines;
+}
+
+function formatResult(result: ImportResult, dryRun: boolean): string {
+  const lines: string[] = [''];
+  const prefix = dryRun ? `${c.yellow}${c.bold}DRY RUN${c.reset} ` : '';
+  const total = result.created.length + result.updated.length + result.versioned.length;
+
+  if (total > 0 || result.errors.length > 0) {
+    lines.push(`  ${prefix}${c.bold}Import complete${c.reset}`);
+    lines.push(`  ${c.dim}${'─'.repeat(40)}${c.reset}`);
+  }
+
+  if (result.created.length > 0) {
+    const verb = dryRun ? 'Would create' : 'Created';
+    lines.push('');
+    lines.push(`  ${c.green}${c.bold}+ ${verb} ${result.created.length} resource(s)${c.reset}`);
+    lines.push(...formatResourceList(result.created));
+  }
+
+  if (result.updated.length > 0) {
+    const verb = dryRun ? 'Would update' : 'Updated';
+    lines.push('');
+    lines.push(`  ${c.blue}${c.bold}~ ${verb} ${result.updated.length} resource(s)${c.reset}`);
+    lines.push(...formatResourceList(result.updated));
+  }
+
+  if (result.versioned.length > 0) {
+    const verb = dryRun ? 'Would version' : 'Versioned';
+    lines.push('');
+    lines.push(`  ${c.yellow}${c.bold}↑ ${verb} ${result.versioned.length} existing resource(s)${c.reset}`);
+    lines.push(...formatResourceList(result.versioned));
+  }
+
+  if (result.errors.length > 0) {
+    lines.push('');
+    lines.push(`  ${c.red}${c.bold}✘ ${result.errors.length} error(s)${c.reset}`);
+    for (const e of result.errors) {
+      lines.push(`   ${c.red}│${c.reset}  ${c.red}${e}${c.reset}`);
+    }
+  }
+
+  if (result.created.length === 0 && result.updated.length === 0 && result.errors.length === 0) {
+    lines.push(`  ${c.dim}No resources to write.${c.reset}`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    process.stdin.on('data', (chunk) => chunks.push(chunk));
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+    process.stdin.on('error', reject);
+  });
+}
diff --git a/packages/cli/src/cli/index.ts b/packages/cli/src/cli/index.ts
new file mode 100644
index 000000000..083c4fa5a
--- /dev/null
+++ b/packages/cli/src/cli/index.ts
@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { executeFunction } from './executor';
+import { listFunctions, formatListOutput } from './list';
+import { exportResource, exportCatalog } from './export';
+import { importDSL } from './import';
+import { snapshotCreate, snapshotDiff, snapshotList } from './snapshot';
+import { governanceCheck } from './governance';
+
+// Read package.json to get version
+let version = '1.0.0';
+try {
+  const packageJsonPath = resolve(__dirname, '../../package.json');
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+  version = packageJson.version;
+} catch {
+  // Fall back to default version if package.json not found
+}
+
+program
+  .name('eventcatalog')
+  .description('EventCatalog Command-Line Interface')
+  .version(version)
+  .option('-d, --dir <path>', 'Path to the EventCatalog directory (default: current directory)', '.');
+
+// List command - show all available functions
+program
+  .command('list')
+  .description('List all available SDK functions')
+  .action(() => {
+    try {
+      const functions = listFunctions('.');
+      const output = formatListOutput(functions);
+      console.log(output);
+    } catch (error) {
+      console.error('Error listing functions:', error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+// Export command - export a resource to .ec DSL format
+program
+  .command('export')
+  .description('Export a catalog resource to EventCatalog DSL (.ec) format')
+  .option('-a, --all', 'Export the entire catalog (all resource types)', false)
+  .option('-r, --resource <type>', 'Resource type (event, command, query, service, domain)')
+  .option('--id <id>', 'Resource ID (omit to export all resources of the given type)')
+  .option('-v, --version <version>', 'Resource version (defaults to latest)')
+  .option('--hydrate', 'Include referenced resources (messages, channels, owners)', false)
+  .option('--stdout', 'Print to stdout instead of writing a file', false)
+  .option('--playground', 'Open the exported DSL in EventCatalog Compass', false)
+  .option('-o, --output <path>', 'Output file path (defaults to <id>.ec or catalog.ec)')
+  .action(async (opts) => {
+    try {
+      const globalOpts = program.opts() as any;
+      const dir = globalOpts.dir || '.';
+
+      if (opts.all) {
+        const result = await exportCatalog({
+          hydrate: opts.hydrate,
+          stdout: opts.stdout,
+          playground: opts.playground,
+          output: opts.output,
+          dir,
+        });
+        console.log(result);
+        return;
+      }
+
+      if (!opts.resource) {
+        console.error('Either --all or --resource is required');
+        process.exit(1);
+      }
+
+      const result = await exportResource({
+        resource: opts.resource,
+        id: opts.id,
+        version: opts.version,
+        hydrate: opts.hydrate,
+        stdout: opts.stdout,
+        playground: opts.playground,
+        output: opts.output,
+        dir,
+      });
+      console.log(result);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+// Import command - import .ec DSL files into catalog markdown
+program
+  .command('import [files...]')
+  .description('Import EventCatalog DSL (.ec) files into catalog markdown')
+  .option('--stdin', 'Read DSL from stdin', false)
+  .option('--dry-run', 'Preview resources without writing', false)
+  .option('--flat', 'Write resources in flat structure (no nesting under domains/services)', false)
+  .option('--no-init', 'Skip catalog initialization prompt')
+  .action(async (files: string[], opts) => {
+    try {
+      const globalOpts = program.opts() as any;
+      const dir = globalOpts.dir || '.';
+
+      const result = await importDSL({
+        files: files.length > 0 ? files : undefined,
+        stdin: opts.stdin,
+        dryRun: opts.dryRun,
+        flat: opts.flat,
+        noInit: !opts.init,
+        dir,
+      });
+      console.log(result);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+// Snapshot command group
+const snapshot = program.command('snapshot').description('Create, diff, and list catalog snapshots');
+
+snapshot
+  .command('create')
+  .description('Take a point-in-time snapshot of the catalog')
+  .option('--label <label>', 'Human-readable label (default: ISO timestamp)')
+  .option('-o, --output <path>', 'Output directory for the snapshot file')
+  .option('--stdout', 'Print JSON to stdout instead of writing a file', false)
+  .action(async (opts) => {
+    try {
+      const globalOpts = program.opts() as any;
+      const dir = globalOpts.dir || '.';
+      const result = await snapshotCreate({ label: opts.label, output: opts.output, stdout: opts.stdout, dir });
+      console.log(result);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+snapshot
+  .command('diff <fileA> <fileB>')
+  .description('Compare two snapshot files and output a structured diff')
+  .option('--format <format>', 'Output format: text or json', 'text')
+  .action(async (fileA: string, fileB: string, opts) => {
+    try {
+      const globalOpts = program.opts() as any;
+      const dir = globalOpts.dir || '.';
+      const result = await snapshotDiff({ fileA, fileB, format: opts.format, dir });
+      console.log(result);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+snapshot
+  .command('list')
+  .description('List all snapshots in the catalog')
+  .option('--format <format>', 'Output format: text or json', 'text')
+  .action(async (opts) => {
+    try {
+      const globalOpts = program.opts() as any;
+      const dir = globalOpts.dir || '.';
+      const result = await snapshotList({ format: opts.format, dir });
+      console.log(result);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+// Governance command group
+const governance = program.command('governance').description('Run governance rules against catalog changes');
+
+governance
+  .command('check')
+  .description('Compare catalog against a base branch and evaluate governance rules')
+  .option('--base <branch>', 'Base branch to compare against (default: main)')
+  .option('--target <branch>', 'Target branch to compare (default: current working directory)')
+  .option('--format <format>', 'Output format: text or json', 'text')
+  .option('--status <status>', 'Status label to include in webhook payloads (e.g. proposed, approved)')
+  .action(async (opts) => {
+    try {
+      const globalOpts = program.opts() as any;
+      const dir = globalOpts.dir || '.';
+      const result = await governanceCheck({
+        base: opts.base,
+        target: opts.target,
+        format: opts.format,
+        status: opts.status,
+        dir,
+      });
+      console.log(result.output);
+      process.exitCode = result.exitCode;
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+// Catch-all for any other command - execute as SDK function
+program.arguments('<function> [args...]').action(async (functionName: string, args: string[]) => {
+  try {
+    const options = program.opts() as any;
+    const dir = options.dir || '.';
+    const result = await executeFunction(dir, functionName, args);
+    console.log(JSON.stringify(result, null, 0));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+});
+
+program.parse(process.argv);
+
+// Show help if no command provided
+if (process.argv.length < 3) {
+  program.outputHelp();
+}
diff --git a/packages/cli/src/cli/list.ts b/packages/cli/src/cli/list.ts
new file mode 100644
index 000000000..b509309f7
--- /dev/null
+++ b/packages/cli/src/cli/list.ts
@@ -0,0 +1,78 @@
+import createSDK from '@eventcatalog/sdk';
+
+interface CategorizedFunctions {
+  [category: string]: string[];
+}
+
+/**
+ * Get all available SDK functions organized by category
+ */
+export function listFunctions(catalogDir: string = '.'): CategorizedFunctions {
+  // Initialize SDK to get all functions
+  const sdk = createSDK(catalogDir);
+
+  // Get all function names from SDK
+  const functionNames = Object.keys(sdk).filter((key) => typeof (sdk as any)[key] === 'function');
+
+  // Categorize functions based on naming patterns
+  const categories: CategorizedFunctions = {
+    Events: [],
+    Commands: [],
+    Queries: [],
+    Channels: [],
+    Services: [],
+    Domains: [],
+    Entities: [],
+    DataStores: [],
+    DataProducts: [],
+    Teams: [],
+    Users: [],
+    'Custom Docs': [],
+    Messages: [],
+    Utilities: [],
+  };
+
+  functionNames.forEach((name) => {
+    if (name.includes('Event')) categories['Events'].push(name);
+    else if (name.includes('Command')) categories['Commands'].push(name);
+    else if (name.includes('Query')) categories['Queries'].push(name);
+    else if (name.includes('Channel')) categories['Channels'].push(name);
+    else if (name.includes('Service')) categories['Services'].push(name);
+    else if (name.includes('Domain')) categories['Domains'].push(name);
+    else if (name.includes('Entity')) categories['Entities'].push(name);
+    else if (name.includes('DataStore')) categories['DataStores'].push(name);
+    else if (name.includes('DataProduct')) categories['DataProducts'].push(name);
+    else if (name.includes('Team')) categories['Teams'].push(name);
+    else if (name.includes('User')) categories['Users'].push(name);
+    else if (name.includes('CustomDoc')) categories['Custom Docs'].push(name);
+    else if (name.includes('Message') || name.includes('Producers') || name.includes('Consumers'))
+      categories['Messages'].push(name);
+    else categories['Utilities'].push(name);
+  });
+
+  // Remove empty categories
+  Object.keys(categories).forEach((key) => {
+    if (categories[key].length === 0) {
+      delete categories[key];
+    }
+  });
+
+  return categories;
+}
+
+/**
+ * Format and print categorized functions
+ */
+export function formatListOutput(functions: CategorizedFunctions): string {
+  let output = 'Available EventCatalog SDK Functions:\n\n';
+
+  Object.entries(functions).forEach(([category, names]) => {
+    output += `${category}:\n`;
+    names.sort().forEach((name) => {
+      output += `  - ${name}\n`;
+    });
+    output += '\n';
+  });
+
+  return output;
+}
diff --git a/eventcatalog/public/logo-old.png b/packages/cli/src/cli/logo.png
similarity index 100%
rename from eventcatalog/public/logo-old.png
rename to packages/cli/src/cli/logo.png
diff --git a/packages/cli/src/cli/parser.ts b/packages/cli/src/cli/parser.ts
new file mode 100644
index 000000000..70768983c
--- /dev/null
+++ b/packages/cli/src/cli/parser.ts
@@ -0,0 +1,34 @@
+/**
+ * Parse command-line arguments into typed values
+ * Supports JSON objects/arrays, booleans, numbers, and strings
+ */
+export function parseArguments(rawArgs: string[]): any[] {
+  return rawArgs.map((arg, index) => {
+    // Try to parse as JSON object or array if it looks like JSON
+    if ((arg.startsWith('{') && arg.endsWith('}')) || (arg.startsWith('[') && arg.endsWith(']'))) {
+      try {
+        return JSON.parse(arg);
+      } catch (error) {
+        // If it fails to parse as JSON, treat it as a string
+        // Only throw error if it looks like valid JSON syntax was intended
+        if (arg.includes(':') || arg.includes(',')) {
+          throw new Error(`Invalid JSON in argument ${index + 1}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Otherwise, return as string
+        return arg;
+      }
+    }
+
+    // Parse booleans
+    if (arg === 'true') return true;
+    if (arg === 'false') return false;
+
+    // Parse numbers
+    if (/^-?\d+(\.\d+)?$/.test(arg)) {
+      return Number(arg);
+    }
+
+    // Return as string
+    return arg;
+  });
+}
diff --git a/packages/cli/src/cli/snapshot.ts b/packages/cli/src/cli/snapshot.ts
new file mode 100644
index 000000000..a30350946
--- /dev/null
+++ b/packages/cli/src/cli/snapshot.ts
@@ -0,0 +1,108 @@
+import { resolve } from 'node:path';
+import { rmSync } from 'node:fs';
+import createSDK from '@eventcatalog/sdk';
+
+export const snapshotCreate = async (opts: { label?: string; output?: string; stdout?: boolean; dir: string }) => {
+  const dir = resolve(opts.dir);
+  const sdk = createSDK(dir);
+
+  const result = await sdk.createSnapshot({
+    label: opts.label,
+    outputDir: opts.output ? resolve(opts.output) : undefined,
+  });
+
+  if (opts.stdout) {
+    rmSync(result.filePath, { force: true });
+    return JSON.stringify(result.snapshot, null, 2);
+  }
+
+  const resources = result.snapshot.resources;
+  const counts = [
+    resources.services.length && `${resources.services.length} services`,
+    resources.messages.events.length && `${resources.messages.events.length} events`,
+    resources.messages.commands.length && `${resources.messages.commands.length} commands`,
+    resources.messages.queries.length && `${resources.messages.queries.length} queries`,
+    resources.domains.length && `${resources.domains.length} domains`,
+    resources.channels.length && `${resources.channels.length} channels`,
+  ]
+    .filter(Boolean)
+    .join(', ');
+
+  return `Snapshot created: ${result.filePath}\nResources: ${counts}`;
+};
+
+const formatDiffText = (diff: any): string => {
+  const lines: string[] = [];
+
+  const labelA = diff.snapshotA.label;
+  const labelB = diff.snapshotB.label;
+  lines.push(`Comparing: ${labelA} vs ${labelB}`);
+  lines.push('');
+
+  if (diff.resources.length > 0) {
+    lines.push(`Resources (${diff.resources.length} changes):`);
+    for (const r of diff.resources) {
+      const prefix = r.changeType === 'added' ? '+' : r.changeType === 'removed' ? '-' : r.changeType === 'versioned' ? '^' : '~';
+      const version = r.changeType === 'versioned' ? `${r.previousVersion} -> ${r.newVersion}` : r.version;
+      const fields = r.changedFields ? ` (${r.changedFields.join(', ')})` : '';
+      lines.push(`  ${prefix} ${r.resourceId}@${version}  [${r.type}] ${r.changeType}${fields}`);
+    }
+    lines.push('');
+  }
+
+  if (diff.relationships.length > 0) {
+    lines.push(`Relationships (${diff.relationships.length} changes):`);
+    for (const r of diff.relationships) {
+      const prefix = r.changeType === 'added' ? '+' : '-';
+      lines.push(
+        `  ${prefix} ${r.serviceId} --${r.direction}--> ${r.resourceId}${r.resourceVersion ? `@${r.resourceVersion}` : ''}`
+      );
+    }
+    lines.push('');
+  }
+
+  if (diff.summary.totalChanges === 0) {
+    lines.push('No changes detected.');
+  } else {
+    lines.push(`Summary: ${diff.resources.length} resource changes, ${diff.relationships.length} relationship changes`);
+  }
+
+  return lines.join('\n');
+};
+
+export const snapshotDiff = async (opts: { fileA: string; fileB: string; format?: string; dir: string }) => {
+  const dir = resolve(opts.dir);
+  const sdk = createSDK(dir);
+
+  const diff = await sdk.diffSnapshots(resolve(opts.fileA), resolve(opts.fileB));
+
+  if (opts.format === 'json') {
+    return JSON.stringify(diff, null, 2);
+  }
+
+  return formatDiffText(diff);
+};
+
+export const snapshotList = async (opts: { format?: string; dir: string }) => {
+  const dir = resolve(opts.dir);
+  const sdk = createSDK(dir);
+
+  const snapshots = await sdk.listSnapshots();
+
+  if (opts.format === 'json') {
+    return JSON.stringify(snapshots, null, 2);
+  }
+
+  if (snapshots.length === 0) {
+    return 'No snapshots found.';
+  }
+
+  const lines = ['Snapshots:', ''];
+  for (const s of snapshots) {
+    const git = s.git ? ` (${s.git.branch} ${s.git.commit})` : '';
+    lines.push(`  ${s.label}  ${s.createdAt}${git}`);
+    lines.push(`    ${s.filePath}`);
+  }
+
+  return lines.join('\n');
+};
diff --git a/packages/cli/src/test/bench/import-export.benchmark.js b/packages/cli/src/test/bench/import-export.benchmark.js
new file mode 100644
index 000000000..f030463bf
--- /dev/null
+++ b/packages/cli/src/test/bench/import-export.benchmark.js
@@ -0,0 +1,145 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { performance } = require('node:perf_hooks');
+const { spawnSync } = require('node:child_process');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '../../..');
+const CLI_ENTRY = path.join(PACKAGE_ROOT, 'dist', 'cli', 'index.js');
+
+function envInt(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const value = Number.parseInt(raw, 10);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`Invalid ${name} value '${raw}'. Must be a positive integer.`);
+  }
+  return value;
+}
+
+const ITERATIONS = envInt('BENCH_ITERATIONS', 5);
+const SERVICES = envInt('BENCH_SERVICES', 60);
+const EVENTS_PER_SERVICE = envInt('BENCH_EVENTS_PER_SERVICE', 2);
+const WARMUP_RUNS = envInt('BENCH_WARMUP_RUNS', 1);
+
+function runCli(args) {
+  const result = spawnSync('node', [CLI_ENTRY, ...args], {
+    cwd: PACKAGE_ROOT,
+    encoding: 'utf8',
+    stdio: 'pipe',
+    maxBuffer: 50 * 1024 * 1024,
+  });
+
+  if (result.status !== 0) {
+    const stderr = result.stderr || '';
+    const stdout = result.stdout || '';
+    throw new Error(`Command failed: node ${CLI_ENTRY} ${args.join(' ')}\nstdout:\n${stdout}\nstderr:\n${stderr}`);
+  }
+
+  return result.stdout;
+}
+
+function makeDataset(services, eventsPerService) {
+  const blocks = [];
+  const totalEvents = services * eventsPerService;
+
+  for (let i = 1; i <= totalEvents; i += 1) {
+    blocks.push(`event Event${i} {\n  version 1.0.0\n  name "Event ${i}"\n}`);
+  }
+
+  for (let i = 1; i <= services; i += 1) {
+    const refs = [];
+    for (let j = 0; j < eventsPerService; j += 1) {
+      const eventId = (i - 1) * eventsPerService + j + 1;
+      refs.push(`  sends event Event${eventId}@1.0.0`);
+    }
+    blocks.push(`service Service${i} {\n  version 1.0.0\n  name "Service ${i}"\n${refs.join('\n')}\n}`);
+  }
+
+  return blocks.join('\n\n');
+}
+
+function stats(samples) {
+  const sorted = [...samples].sort((a, b) => a - b);
+  const sum = sorted.reduce((acc, v) => acc + v, 0);
+  const mean = sum / sorted.length;
+  const median = sorted[Math.floor(sorted.length / 2)];
+  const min = sorted[0];
+  const max = sorted[sorted.length - 1];
+  const p95 = sorted[Math.floor((sorted.length - 1) * 0.95)];
+  return { mean, median, min, max, p95 };
+}
+
+function fmt(n) {
+  return `${n.toFixed(1)}ms`;
+}
+
+function runIteration(dsl) {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'eventcatalog-cli-bench-'));
+  const catalogDir = path.join(tmpRoot, 'catalog');
+  const inputFile = path.join(tmpRoot, 'catalog.ec');
+  fs.mkdirSync(catalogDir, { recursive: true });
+  fs.writeFileSync(inputFile, dsl, 'utf8');
+
+  const tImportStart = performance.now();
+  runCli(['import', inputFile, '--no-init', '-d', catalogDir]);
+  const tImportEnd = performance.now();
+
+  const tExportStart = performance.now();
+  const exported = runCli(['export', '--all', '--stdout', '-d', catalogDir]);
+  const tExportEnd = performance.now();
+
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+
+  return {
+    importMs: tImportEnd - tImportStart,
+    exportMs: tExportEnd - tExportStart,
+    exportBytes: Buffer.byteLength(exported, 'utf8'),
+  };
+}
+
+function main() {
+  if (!fs.existsSync(CLI_ENTRY)) {
+    throw new Error(`Missing ${CLI_ENTRY}. Run 'pnpm --filter @eventcatalog/cli build' first.`);
+  }
+
+  const dsl = makeDataset(SERVICES, EVENTS_PER_SERVICE);
+  const events = SERVICES * EVENTS_PER_SERVICE;
+
+  console.log('EventCatalog CLI Benchmark');
+  console.log(`- Iterations: ${ITERATIONS}`);
+  console.log(`- Warmup Runs: ${WARMUP_RUNS}`);
+  console.log(`- Services: ${SERVICES}`);
+  console.log(`- Events: ${events}`);
+  console.log(`- Events per service: ${EVENTS_PER_SERVICE}`);
+  console.log('');
+
+  for (let i = 0; i < WARMUP_RUNS; i += 1) {
+    runIteration(dsl);
+  }
+
+  const importSamples = [];
+  const exportSamples = [];
+  let bytes = 0;
+
+  for (let i = 1; i <= ITERATIONS; i += 1) {
+    const { importMs, exportMs, exportBytes } = runIteration(dsl);
+    importSamples.push(importMs);
+    exportSamples.push(exportMs);
+    bytes = exportBytes;
+    console.log(`run ${i}: import=${fmt(importMs)} export=${fmt(exportMs)}`);
+  }
+
+  const importStats = stats(importSamples);
+  const exportStats = stats(exportSamples);
+
+  console.log('');
+  console.log('Summary');
+  console.log(`- Import mean/median: ${fmt(importStats.mean)} / ${fmt(importStats.median)}`);
+  console.log(`- Import min/max/p95: ${fmt(importStats.min)} / ${fmt(importStats.max)} / ${fmt(importStats.p95)}`);
+  console.log(`- Export mean/median: ${fmt(exportStats.mean)} / ${fmt(exportStats.median)}`);
+  console.log(`- Export min/max/p95: ${fmt(exportStats.min)} / ${fmt(exportStats.max)} / ${fmt(exportStats.p95)}`);
+  console.log(`- Export output size: ${bytes} bytes`);
+}
+
+main();
diff --git a/packages/cli/src/test/cli-executor.test.ts b/packages/cli/src/test/cli-executor.test.ts
new file mode 100644
index 000000000..a20695b4f
--- /dev/null
+++ b/packages/cli/src/test/cli-executor.test.ts
@@ -0,0 +1,70 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { executeFunction } from '../cli/executor';
+
+// Mock the SDK
+vi.mock('@eventcatalog/sdk', () => ({
+  default: vi.fn((path: string) => ({
+    testFunction: vi.fn(async (arg1: string, arg2: number) => ({
+      success: true,
+      arg1,
+      arg2,
+    })),
+    getEvent: vi.fn(async (id: string) => ({
+      id,
+      name: `Event ${id}`,
+    })),
+    getEvents: vi.fn(async (options: any) => [
+      { id: 'Event1', version: '1.0.0' },
+      { id: 'Event2', version: '1.0.0' },
+    ]),
+    notAFunction: 'not callable',
+  })),
+}));
+
+describe('executeFunction', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should execute a function with arguments', async () => {
+    const result = await executeFunction('.', 'testFunction', ['test', '42']);
+    expect(result).toEqual({
+      success: true,
+      arg1: 'test',
+      arg2: 42,
+    });
+  });
+
+  it('should execute getEvent function', async () => {
+    const result = await executeFunction('.', 'getEvent', ['OrderCreated']);
+    expect(result).toEqual({
+      id: 'OrderCreated',
+      name: 'Event OrderCreated',
+    });
+  });
+
+  it('should execute getEvents function with options', async () => {
+    const result = await executeFunction('.', 'getEvents', ['{"latestOnly":true}']);
+    expect(result).toEqual([
+      { id: 'Event1', version: '1.0.0' },
+      { id: 'Event2', version: '1.0.0' },
+    ]);
+  });
+
+  it('should throw error when function does not exist', async () => {
+    await expect(executeFunction('.', 'nonexistentFunction', [])).rejects.toThrow(`Function 'nonexistentFunction' not found`);
+  });
+
+  it('should throw error when trying to call non-function property', async () => {
+    await expect(executeFunction('.', 'notAFunction', [])).rejects.toThrow(`'notAFunction' is not a callable function`);
+  });
+
+  it('should throw error when catalog directory does not exist', async () => {
+    await expect(executeFunction('/nonexistent/path', 'getEvent', ['test'])).rejects.toThrow(`Catalog directory not found`);
+  });
+
+  it('should parse JSON arguments', async () => {
+    const result = await executeFunction('.', 'getEvents', ['{"latestOnly":true}']);
+    expect(result).toBeDefined();
+  });
+});
diff --git a/packages/cli/src/test/cli-export.test.ts b/packages/cli/src/test/cli-export.test.ts
new file mode 100644
index 000000000..de81c2469
--- /dev/null
+++ b/packages/cli/src/test/cli-export.test.ts
@@ -0,0 +1,643 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { exportResource, exportAll, exportCatalog } from '../cli/export';
+import path from 'node:path';
+import fs from 'node:fs';
+import createSDK from '@eventcatalog/sdk';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-export-test');
+
+const { writeEvent, writeCommand, writeService, writeDomain, writeChannel, writeTeam, writeUser } = createSDK(CATALOG_PATH);
+
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('export command', () => {
+  it('exports an event to stdout', async () => {
+    await writeEvent({
+      id: 'OrderCreated',
+      name: 'Order Created',
+      version: '1.0.0',
+      summary: 'An order was created',
+      markdown: '',
+    });
+
+    const result = await exportResource({
+      resource: 'event',
+      id: 'OrderCreated',
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "An order was created"
+}
+
+visualizer main {
+  name "View of OrderCreated"
+  event OrderCreated
+}`);
+  });
+
+  it('exports a command to stdout', async () => {
+    await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' });
+
+    const result = await exportResource({
+      resource: 'command',
+      id: 'CreateOrder',
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toBe(`command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+}
+
+visualizer main {
+  name "View of CreateOrder"
+  command CreateOrder
+}`);
+  });
+
+  it('exports a service to stdout', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+    await writeService({
+      id: 'OrderService',
+      name: 'Order Service',
+      version: '1.0.0',
+      sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      markdown: '',
+    });
+
+    const result = await exportResource({
+      resource: 'service',
+      id: 'OrderService',
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0
+}
+
+visualizer main {
+  name "View of OrderService"
+  service OrderService
+}`);
+  });
+
+  it('exports a domain to stdout', async () => {
+    await writeDomain({
+      id: 'Orders',
+      name: 'Orders Domain',
+      version: '1.0.0',
+      summary: 'Order management',
+      markdown: '',
+    });
+
+    const result = await exportResource({
+      resource: 'domain',
+      id: 'Orders',
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toBe(`domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  summary "Order management"
+}
+
+visualizer main {
+  name "View of Orders"
+  domain Orders
+}`);
+  });
+
+  it('exports a specific version', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '2.0.0', summary: 'v2', markdown: '' });
+
+    const result = await exportResource({
+      resource: 'event',
+      id: 'OrderCreated',
+      version: '2.0.0',
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toBe(`event OrderCreated {
+  version 2.0.0
+  name "Order Created"
+  summary "v2"
+}
+
+visualizer main {
+  name "View of OrderCreated"
+  event OrderCreated
+}`);
+  });
+
+  it('exports with hydrate includes referenced resources', async () => {
+    await writeTeam({ id: 'orders-team', name: 'Orders Team', markdown: '' });
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+    await writeService({
+      id: 'OrderService',
+      name: 'Order Service',
+      version: '1.0.0',
+      owners: ['orders-team'],
+      sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      markdown: '',
+    });
+
+    const result = await exportResource({
+      resource: 'service',
+      id: 'OrderService',
+      hydrate: true,
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toBe(`// TEAMS
+team orders-team {
+  name "Orders Team"
+}
+
+// EVENTS
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+// SERVICES
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  owner orders-team
+  sends event OrderCreated@1.0.0
+}
+
+visualizer main {
+  name "View of OrderService"
+  event OrderCreated
+  service OrderService
+}`);
+  });
+
+  it('writes to file by default', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+    const result = await exportResource({
+      resource: 'event',
+      id: 'OrderCreated',
+      dir: CATALOG_PATH,
+    });
+
+    const filepath = path.resolve('OrderCreated.ec');
+    expect(result).toContain(`Exported event 'OrderCreated' to ${filepath}`);
+    expect(result).toContain('Tip: Use --playground to open in EventCatalog Compass');
+    expect(fs.existsSync(filepath)).toBe(true);
+
+    const content = fs.readFileSync(filepath, 'utf-8');
+    expect(content).toContain('event OrderCreated {');
+    expect(content).toContain('visualizer main {');
+
+    fs.rmSync(filepath);
+  });
+
+  it('writes to custom output path', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+    const outputPath = path.join(CATALOG_PATH, 'custom-output.ec');
+    const result = await exportResource({
+      resource: 'event',
+      id: 'OrderCreated',
+      output: outputPath,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain(`Exported event 'OrderCreated' to ${outputPath}`);
+    expect(result).toContain('Tip: Use --playground to open in EventCatalog Compass');
+    expect(fs.existsSync(outputPath)).toBe(true);
+
+    const content = fs.readFileSync(outputPath, 'utf-8');
+    expect(content).toContain('event OrderCreated {');
+    expect(content).toContain('visualizer main {');
+  });
+
+  it('includes playground URL when --playground is set', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+    const outputPath = path.join(CATALOG_PATH, 'playground-test.ec');
+    const result = await exportResource({
+      resource: 'event',
+      id: 'OrderCreated',
+      playground: true,
+      output: outputPath,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain(`Exported event 'OrderCreated' to ${outputPath}`);
+    expect(result).toContain('Opening in EventCatalog Compass...');
+    expect(result).not.toContain('Tip: Use --playground');
+  });
+
+  it('throws for invalid resource type', async () => {
+    await expect(
+      exportResource({
+        resource: 'invalid',
+        id: 'Foo',
+        stdout: true,
+        dir: CATALOG_PATH,
+      })
+    ).rejects.toThrow("Invalid resource type 'invalid'. Must be one of: event, command, query, service, domain");
+  });
+
+  it('throws a specific message for known but unsupported export types', async () => {
+    await expect(
+      exportResource({
+        resource: 'channel',
+        id: 'OrderTopic',
+        stdout: true,
+        dir: CATALOG_PATH,
+      })
+    ).rejects.toThrow(
+      "Resource type 'channel' is not yet supported for DSL export. Supported types: event, command, query, service, domain"
+    );
+  });
+
+  it('throws when resource not found', async () => {
+    await expect(
+      exportResource({
+        resource: 'event',
+        id: 'NonExistent',
+        stdout: true,
+        dir: CATALOG_PATH,
+      })
+    ).rejects.toThrow("event 'NonExistent (latest)' not found");
+  });
+
+  it('throws when versioned resource not found', async () => {
+    await expect(
+      exportResource({
+        resource: 'event',
+        id: 'NonExistent',
+        version: '9.9.9',
+        stdout: true,
+        dir: CATALOG_PATH,
+      })
+    ).rejects.toThrow("event 'NonExistent@9.9.9' not found");
+  });
+
+  it('delegates to exportAll when id is omitted', async () => {
+    await writeService({ id: 'ServiceA', name: 'Service A', version: '1.0.0', markdown: '' });
+
+    const result = await exportResource({
+      resource: 'service',
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain('service ServiceA');
+  });
+});
+
+describe('exportAll - bulk export', () => {
+  it('exports all services to stdout', async () => {
+    await writeService({ id: 'ServiceA', name: 'Service A', version: '1.0.0', markdown: '' });
+    await writeService({ id: 'ServiceB', name: 'Service B', version: '2.0.0', markdown: '' });
+
+    const result = await exportAll({
+      resource: 'service',
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain('service ServiceA');
+    expect(result).toContain('service ServiceB');
+  });
+
+  it('exports all events to stdout', async () => {
+    await writeEvent({ id: 'EventA', name: 'Event A', version: '1.0.0', markdown: '' });
+    await writeEvent({ id: 'EventB', name: 'Event B', version: '1.0.0', markdown: '' });
+
+    const result = await exportAll({
+      resource: 'event',
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain('event EventA');
+    expect(result).toContain('event EventB');
+  });
+
+  it('handles plural resource names (services -> service)', async () => {
+    await writeService({ id: 'MyService', name: 'My Service', version: '1.0.0', markdown: '' });
+
+    const result = await exportAll({
+      resource: 'services',
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain('service MyService');
+  });
+
+  it('handles plural resource names (events -> event)', async () => {
+    await writeEvent({ id: 'MyEvent', name: 'My Event', version: '1.0.0', markdown: '' });
+
+    const result = await exportAll({
+      resource: 'events',
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain('event MyEvent');
+  });
+
+  it('exports all services with hydrate', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+    await writeService({
+      id: 'OrderService',
+      name: 'Order Service',
+      version: '1.0.0',
+      sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      markdown: '',
+    });
+
+    const result = await exportAll({
+      resource: 'service',
+      hydrate: true,
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain('event OrderCreated');
+    expect(result).toContain('service OrderService');
+    expect(result).toContain('sends event OrderCreated@1.0.0');
+  });
+
+  it('deduplicates shared dependencies when hydrating multiple services', async () => {
+    await writeEvent({ id: 'SharedEvent', name: 'Shared Event', version: '1.0.0', markdown: '' });
+    await writeService({
+      id: 'ServiceA',
+      name: 'Service A',
+      version: '1.0.0',
+      sends: [{ id: 'SharedEvent', version: '1.0.0' }],
+      markdown: '',
+    });
+    await writeService({
+      id: 'ServiceB',
+      name: 'Service B',
+      version: '1.0.0',
+      sends: [{ id: 'SharedEvent', version: '1.0.0' }],
+      markdown: '',
+    });
+
+    const result = await exportAll({
+      resource: 'service',
+      hydrate: true,
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    // SharedEvent should appear only once despite being referenced by both services
+    const matches = result.match(/event SharedEvent \{/g);
+    expect(matches).toHaveLength(1);
+  });
+
+  it('writes to file with default plural name', async () => {
+    await writeService({ id: 'ServiceA', name: 'Service A', version: '1.0.0', markdown: '' });
+
+    const result = await exportAll({
+      resource: 'service',
+      dir: CATALOG_PATH,
+    });
+
+    const filepath = path.resolve('services.ec');
+    expect(result).toContain(`Exported 1 services to ${filepath}`);
+    expect(fs.existsSync(filepath)).toBe(true);
+
+    fs.rmSync(filepath);
+  });
+
+  it('throws for invalid resource type in bulk export', async () => {
+    await expect(
+      exportAll({
+        resource: 'invalid',
+        stdout: true,
+        dir: CATALOG_PATH,
+      })
+    ).rejects.toThrow("Invalid resource type 'invalid'. Must be one of: event, command, query, service, domain");
+  });
+
+  it('throws when no resources found', async () => {
+    await expect(
+      exportAll({
+        resource: 'service',
+        stdout: true,
+        dir: CATALOG_PATH,
+      })
+    ).rejects.toThrow('No services found in catalog');
+  });
+
+  it('groups blocks by type with section comments', async () => {
+    await writeService({ id: 'ServiceA', name: 'Service A', version: '1.0.0', markdown: '' });
+    await writeService({ id: 'ServiceB', name: 'Service B', version: '1.0.0', markdown: '' });
+
+    const result = await exportAll({
+      resource: 'service',
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain('// SERVICES');
+    expect(result).toContain('service ServiceA');
+    expect(result).toContain('service ServiceB');
+  });
+
+  it('includes visualizer block listing all resources', async () => {
+    await writeService({ id: 'ServiceA', name: 'Service A', version: '1.0.0', markdown: '' });
+    await writeService({ id: 'ServiceB', name: 'Service B', version: '1.0.0', markdown: '' });
+
+    const result = await exportAll({
+      resource: 'service',
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain('visualizer main {');
+    expect(result).toContain('service ServiceA');
+    expect(result).toContain('service ServiceB');
+    expect(result).toContain('name "All services"');
+  });
+
+  it('includes visualizer with hydrated resources', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+    await writeService({
+      id: 'OrderService',
+      name: 'Order Service',
+      version: '1.0.0',
+      sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      markdown: '',
+    });
+
+    const result = await exportAll({
+      resource: 'service',
+      hydrate: true,
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    // Visualizer should only include services, not hydrated dependencies
+    const vizSection = result.substring(result.indexOf('visualizer main {'));
+    expect(vizSection).not.toContain('event OrderCreated');
+    expect(vizSection).toContain('service OrderService');
+  });
+
+  it('groups hydrated blocks by type with section comments in order', async () => {
+    await writeTeam({ id: 'my-team', name: 'My Team', markdown: '' });
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+    await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' });
+    await writeService({
+      id: 'OrderService',
+      name: 'Order Service',
+      version: '1.0.0',
+      owners: ['my-team'],
+      sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      receives: [{ id: 'CreateOrder', version: '1.0.0' }],
+      markdown: '',
+    });
+
+    const result = await exportAll({
+      resource: 'service',
+      hydrate: true,
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    // Verify section comments exist
+    expect(result).toContain('// TEAMS');
+    expect(result).toContain('// EVENTS');
+    expect(result).toContain('// COMMANDS');
+    expect(result).toContain('// SERVICES');
+
+    // Verify order: teams before events before commands before services
+    const teamsIdx = result.indexOf('// TEAMS');
+    const eventsIdx = result.indexOf('// EVENTS');
+    const commandsIdx = result.indexOf('// COMMANDS');
+    const servicesIdx = result.indexOf('// SERVICES');
+    expect(teamsIdx).toBeLessThan(eventsIdx);
+    expect(eventsIdx).toBeLessThan(commandsIdx);
+    expect(commandsIdx).toBeLessThan(servicesIdx);
+  });
+});
+
+describe('exportCatalog - full catalog export', () => {
+  it('exports all resource types to stdout', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+    await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' });
+    await writeService({ id: 'OrderService', name: 'Order Service', version: '1.0.0', markdown: '' });
+    await writeDomain({ id: 'Orders', name: 'Orders Domain', version: '1.0.0', markdown: '' });
+
+    const result = await exportCatalog({
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain('// EVENTS');
+    expect(result).toContain('event OrderCreated');
+    expect(result).toContain('// COMMANDS');
+    expect(result).toContain('command CreateOrder');
+    expect(result).toContain('// SERVICES');
+    expect(result).toContain('service OrderService');
+    expect(result).toContain('// DOMAINS');
+    expect(result).toContain('domain Orders');
+  });
+
+  it('includes visualizer with all resource types', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+    await writeService({ id: 'OrderService', name: 'Order Service', version: '1.0.0', markdown: '' });
+    await writeDomain({ id: 'Orders', name: 'Orders Domain', version: '1.0.0', markdown: '' });
+
+    const result = await exportCatalog({
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    const vizSection = result.substring(result.indexOf('visualizer main {'));
+    expect(vizSection).toContain('event OrderCreated');
+    expect(vizSection).toContain('service OrderService');
+    expect(vizSection).toContain('domain Orders');
+    expect(vizSection).toContain('name "Full Catalog"');
+  });
+
+  it('exports with hydrate', async () => {
+    await writeTeam({ id: 'my-team', name: 'My Team', markdown: '' });
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+    await writeService({
+      id: 'OrderService',
+      name: 'Order Service',
+      version: '1.0.0',
+      owners: ['my-team'],
+      sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      markdown: '',
+    });
+
+    const result = await exportCatalog({
+      hydrate: true,
+      stdout: true,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain('// TEAMS');
+    expect(result).toContain('team my-team');
+    expect(result).toContain('// EVENTS');
+    expect(result).toContain('// SERVICES');
+  });
+
+  it('writes to catalog.ec by default', async () => {
+    await writeService({ id: 'OrderService', name: 'Order Service', version: '1.0.0', markdown: '' });
+
+    const result = await exportCatalog({
+      dir: CATALOG_PATH,
+    });
+
+    const filepath = path.resolve('catalog.ec');
+    expect(result).toContain(`Exported full catalog to ${filepath}`);
+    expect(fs.existsSync(filepath)).toBe(true);
+
+    fs.rmSync(filepath);
+  });
+
+  it('writes to custom output path', async () => {
+    await writeService({ id: 'OrderService', name: 'Order Service', version: '1.0.0', markdown: '' });
+
+    const outputPath = path.join(CATALOG_PATH, 'my-catalog.ec');
+    const result = await exportCatalog({
+      output: outputPath,
+      dir: CATALOG_PATH,
+    });
+
+    expect(result).toContain(`Exported full catalog to ${outputPath}`);
+    expect(fs.existsSync(outputPath)).toBe(true);
+  });
+
+  it('throws when catalog is empty', async () => {
+    await expect(
+      exportCatalog({
+        stdout: true,
+        dir: CATALOG_PATH,
+      })
+    ).rejects.toThrow('No resources found in catalog');
+  });
+});
diff --git a/packages/cli/src/test/cli-integration.test.ts b/packages/cli/src/test/cli-integration.test.ts
new file mode 100644
index 000000000..aa920072d
--- /dev/null
+++ b/packages/cli/src/test/cli-integration.test.ts
@@ -0,0 +1,137 @@
+import { describe, it, expect, vi } from 'vitest';
+import { listFunctions, formatListOutput } from '../cli/list';
+
+// Mock the SDK
+vi.mock('@eventcatalog/sdk', () => ({
+  default: vi.fn(() => ({
+    // Event functions
+    getEvent: () => {},
+    getEvents: () => {},
+    writeEvent: () => {},
+    removeEvent: () => {},
+    eventHasVersion: () => {},
+
+    // Command functions
+    getCommand: () => {},
+    getCommands: () => {},
+    writeCommand: () => {},
+    commandHasVersion: () => {},
+
+    // Query functions
+    getQuery: () => {},
+    getQueries: () => {},
+    writeQuery: () => {},
+    queryHasVersion: () => {},
+
+    // Service functions
+    getService: () => {},
+    getServices: () => {},
+    writeService: () => {},
+    serviceHasVersion: () => {},
+
+    // Domain functions
+    getDomain: () => {},
+    getDomains: () => {},
+    writeDomain: () => {},
+    domainHasVersion: () => {},
+
+    // Channel functions
+    getChannel: () => {},
+    getChannels: () => {},
+    writeChannel: () => {},
+    channelHasVersion: () => {},
+
+    // Entity functions
+    getEntity: () => {},
+    getEntities: () => {},
+    writeEntity: () => {},
+    entityHasVersion: () => {},
+
+    // DataStore functions
+    getDataStore: () => {},
+    getDataStores: () => {},
+    writeDataStore: () => {},
+    dataStoreHasVersion: () => {},
+
+    // DataProduct functions
+    getDataProduct: () => {},
+    getDataProducts: () => {},
+    writeDataProduct: () => {},
+    dataProductHasVersion: () => {},
+
+    // Team functions
+    getTeam: () => {},
+    getTeams: () => {},
+    writeTeam: () => {},
+
+    // User functions
+    getUser: () => {},
+    getUsers: () => {},
+    writeUser: () => {},
+
+    // Custom Doc functions
+    getCustomDoc: () => {},
+    getCustomDocs: () => {},
+    writeCustomDoc: () => {},
+
+    // Message functions
+    getProducersAndConsumersForMessage: () => {},
+    getConsumersOfSchema: () => {},
+    getProducersOfSchema: () => {},
+
+    // Utility functions
+    dumpCatalog: () => {},
+    getResourcePath: () => {},
+    getResourceFolderName: () => {},
+  })),
+}));
+
+describe('CLI Integration', () => {
+  it('should list functions organized by category', () => {
+    const functions = listFunctions('.');
+
+    expect(functions).toHaveProperty('Events');
+    expect(functions).toHaveProperty('Commands');
+    expect(functions).toHaveProperty('Queries');
+    expect(functions).toHaveProperty('Services');
+    expect(functions).toHaveProperty('Domains');
+    expect(functions).toHaveProperty('Channels');
+    expect(functions).toHaveProperty('Entities');
+    expect(functions).toHaveProperty('DataStores');
+    expect(functions).toHaveProperty('DataProducts');
+    expect(functions).toHaveProperty('Teams');
+    expect(functions).toHaveProperty('Users');
+    expect(functions).toHaveProperty('Custom Docs');
+    expect(functions).toHaveProperty('Messages');
+  });
+
+  it('should categorize functions correctly', () => {
+    const functions = listFunctions('.');
+
+    expect(functions.Events).toContain('getEvent');
+    expect(functions.Events).toContain('getEvents');
+    expect(functions.Events).toContain('writeEvent');
+    expect(functions.Commands).toContain('getCommand');
+    expect(functions.Services).toContain('getService');
+    expect(functions.Domains).toContain('getDomain');
+  });
+
+  it('should format output as human-readable string', () => {
+    const functions = listFunctions('.');
+    const output = formatListOutput(functions);
+
+    expect(output).toContain('Available EventCatalog SDK Functions:');
+    expect(output).toContain('Events:');
+    expect(output).toContain('Commands:');
+    expect(output).toContain('Services:');
+  });
+
+  it('should include all function categories in output', () => {
+    const functions = listFunctions('.');
+    const output = formatListOutput(functions);
+
+    Object.keys(functions).forEach((category) => {
+      expect(output).toContain(`${category}:`);
+    });
+  });
+});
diff --git a/packages/cli/src/test/cli-parser.test.ts b/packages/cli/src/test/cli-parser.test.ts
new file mode 100644
index 000000000..da5b3b26f
--- /dev/null
+++ b/packages/cli/src/test/cli-parser.test.ts
@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import { parseArguments } from '../cli/parser';
+
+describe('parseArguments', () => {
+  it('should parse string arguments', () => {
+    const result = parseArguments(['hello', 'world']);
+    expect(result).toEqual(['hello', 'world']);
+  });
+
+  it('should parse numeric arguments', () => {
+    const result = parseArguments(['42', '3.14', '-100']);
+    expect(result).toEqual([42, 3.14, -100]);
+  });
+
+  it('should parse boolean arguments', () => {
+    const result = parseArguments(['true', 'false']);
+    expect(result).toEqual([true, false]);
+  });
+
+  it('should parse JSON objects', () => {
+    const result = parseArguments(['{"id":"test","name":"Test"}']);
+    expect(result).toEqual([{ id: 'test', name: 'Test' }]);
+  });
+
+  it('should parse JSON arrays', () => {
+    const result = parseArguments(['["item1","item2","item3"]']);
+    expect(result).toEqual([['item1', 'item2', 'item3']]);
+  });
+
+  it('should parse nested JSON objects', () => {
+    const result = parseArguments(['{"user":{"id":"123","name":"John"},"active":true}']);
+    expect(result).toEqual([{ user: { id: '123', name: 'John' }, active: true }]);
+  });
+
+  it('should parse mixed argument types', () => {
+    const result = parseArguments(['OrderCreated', '1.0.0', '{"latestOnly":true}']);
+    expect(result).toEqual(['OrderCreated', '1.0.0', { latestOnly: true }]);
+  });
+
+  it('should throw error on invalid JSON with key-value pairs', () => {
+    expect(() => parseArguments(['{"invalid":"json}'])).toThrow('Invalid JSON in argument 1');
+  });
+
+  it('should handle empty array', () => {
+    const result = parseArguments([]);
+    expect(result).toEqual([]);
+  });
+
+  it('should preserve string that looks like JSON but is not surrounded by quotes', () => {
+    const result = parseArguments(['{not json}']);
+    expect(result).toEqual(['{not json}']);
+  });
+
+  it('should parse JSON with numeric values', () => {
+    const result = parseArguments(['{"count":42,"price":19.99}']);
+    expect(result).toEqual([{ count: 42, price: 19.99 }]);
+  });
+});
diff --git a/packages/cli/src/test/governance-check.test.ts b/packages/cli/src/test/governance-check.test.ts
new file mode 100644
index 000000000..ca25ef6c3
--- /dev/null
+++ b/packages/cli/src/test/governance-check.test.ts
@@ -0,0 +1,220 @@
+import { expect, it, describe, vi, beforeEach, afterEach } from 'vitest';
+import path from 'node:path';
+import fs from 'node:fs';
+import { execSync } from 'node:child_process';
+
+// Mock @eventcatalog/license
+vi.mock('@eventcatalog/license', () => ({
+  isEventCatalogScaleEnabled: vi.fn(),
+}));
+
+// Mock @eventcatalog/sdk
+vi.mock('@eventcatalog/sdk', () => ({
+  default: vi.fn(),
+}));
+
+import { governanceCheck } from '../cli/governance';
+import { isEventCatalogScaleEnabled } from '@eventcatalog/license';
+import createSDK from '@eventcatalog/sdk';
+
+const TEMP_DIR = path.join(__dirname, 'governance-check-temp');
+
+beforeEach(() => {
+  fs.mkdirSync(TEMP_DIR, { recursive: true });
+  vi.mocked(isEventCatalogScaleEnabled).mockResolvedValue(true);
+});
+
+afterEach(() => {
+  fs.rmSync(TEMP_DIR, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+describe('governance check', () => {
+  it('throws when Scale plan is not enabled', async () => {
+    vi.mocked(isEventCatalogScaleEnabled).mockResolvedValue(false);
+
+    await expect(governanceCheck({ dir: TEMP_DIR })).rejects.toThrow('Governance requires an EventCatalog Scale plan');
+  });
+
+  it('returns message when no governance.yaml exists', async () => {
+    // Need to mock git archive - init a git repo
+    try {
+      execSync('git init', { cwd: TEMP_DIR, stdio: 'pipe' });
+      execSync('git checkout -b main', { cwd: TEMP_DIR, stdio: 'pipe' });
+      fs.writeFileSync(path.join(TEMP_DIR, 'dummy.txt'), 'hello');
+      execSync('git add . && git commit -m "init"', { cwd: TEMP_DIR, stdio: 'pipe' });
+    } catch {
+      // Skip if git not available
+      return;
+    }
+
+    // Mock SDK to return empty resources
+    const mockSnapshot = {
+      snapshotVersion: '1.0.0',
+      catalogVersion: 'unknown',
+      label: 'test',
+      createdAt: new Date().toISOString(),
+      resources: {
+        domains: [],
+        services: [],
+        messages: { events: [], commands: [], queries: [] },
+        channels: [],
+      },
+    };
+
+    const mockCreateSnapshot = vi.fn().mockResolvedValue({
+      filePath: '/tmp/test.snapshot.json',
+      snapshot: mockSnapshot,
+    });
+
+    const mockDiffSnapshots = vi.fn().mockResolvedValue({
+      snapshotA: { label: 'base', createdAt: '' },
+      snapshotB: { label: 'current', createdAt: '' },
+      summary: {
+        totalChanges: 0,
+        resourcesAdded: 0,
+        resourcesRemoved: 0,
+        resourcesModified: 0,
+        resourcesVersioned: 0,
+        relationshipsAdded: 0,
+        relationshipsRemoved: 0,
+      },
+      resources: [],
+      relationships: [],
+    });
+
+    vi.mocked(createSDK).mockReturnValue({
+      createSnapshot: mockCreateSnapshot,
+      diffSnapshots: mockDiffSnapshots,
+    } as any);
+
+    const result = await governanceCheck({ dir: TEMP_DIR });
+
+    expect(result.output).toContain('No governance.yaml (or governance.yml) found or no rules defined');
+    expect(result.exitCode).toBe(0);
+    expect(result.failures).toEqual([]);
+  });
+
+  it('when governanceCheck finds a schema change, the json output includes schema content plus compact schema metadata for the affected message', async () => {
+    try {
+      execSync('git init', { cwd: TEMP_DIR, stdio: 'pipe' });
+      execSync('git checkout -b main', { cwd: TEMP_DIR, stdio: 'pipe' });
+      fs.writeFileSync(
+        path.join(TEMP_DIR, 'governance.yaml'),
+        `rules:
+  - name: notify-schema-change
+    when:
+      - schema_changed
+    resources:
+      - "*"
+    actions:
+      - type: console
+`
+      );
+      fs.writeFileSync(path.join(TEMP_DIR, 'dummy.txt'), 'hello');
+      execSync('git add .', { cwd: TEMP_DIR, stdio: 'pipe' });
+      execSync('git commit -m "init"', { cwd: TEMP_DIR, stdio: 'pipe' });
+    } catch {
+      return;
+    }
+
+    const writeSchemaFiles = (dir: string, schemaContent: string) => {
+      const resourceDir = path.join(dir, 'events', 'OrderCreated');
+      fs.mkdirSync(resourceDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(resourceDir, 'index.mdx'),
+        '---\nid: OrderCreated\nversion: 1.0.0\nname: OrderCreated\nschemaPath: schema.json\n---\n'
+      );
+      fs.writeFileSync(path.join(resourceDir, 'schema.json'), schemaContent);
+    };
+
+    const baseSnapshot = {
+      snapshotVersion: '1.0.0',
+      catalogVersion: 'unknown',
+      label: 'base-main',
+      createdAt: new Date().toISOString(),
+      resources: {
+        domains: [],
+        services: [],
+        messages: {
+          events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+          commands: [],
+          queries: [],
+        },
+        channels: [],
+      },
+    };
+
+    const targetSnapshot = {
+      snapshotVersion: '1.0.0',
+      catalogVersion: 'unknown',
+      label: 'current',
+      createdAt: new Date().toISOString(),
+      resources: {
+        domains: [],
+        services: [{ id: 'BillingService', version: '1.0.0', name: 'BillingService', receives: [{ id: 'OrderCreated' }] }],
+        messages: {
+          events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+          commands: [],
+          queries: [],
+        },
+        channels: [],
+      },
+    };
+
+    const mockDiffSnapshots = vi.fn().mockResolvedValue({
+      snapshotA: { label: 'base-main', createdAt: '' },
+      snapshotB: { label: 'current', createdAt: '' },
+      summary: {
+        totalChanges: 1,
+        resourcesAdded: 0,
+        resourcesRemoved: 0,
+        resourcesModified: 1,
+        resourcesVersioned: 0,
+        relationshipsAdded: 0,
+        relationshipsRemoved: 0,
+      },
+      resources: [
+        {
+          resourceId: 'OrderCreated',
+          version: '1.0.0',
+          type: 'event',
+          changeType: 'modified',
+          changedFields: ['schemaHash'],
+        },
+      ],
+      relationships: [],
+    });
+
+    vi.mocked(createSDK).mockImplementation((dir: string) => {
+      const isTargetDir = dir === TEMP_DIR;
+      writeSchemaFiles(dir, isTargetDir ? '{"after":"schema"}' : '{"before":"schema"}');
+
+      return {
+        createSnapshot: vi.fn().mockResolvedValue({
+          filePath: path.join(dir, '.snapshots', `${isTargetDir ? 'target' : 'base'}.snapshot.json`),
+          snapshot: isTargetDir ? targetSnapshot : baseSnapshot,
+        }),
+        diffSnapshots: mockDiffSnapshots,
+        getSchemaForMessage: vi.fn().mockResolvedValue({
+          schema: isTargetDir ? '{"after":"schema"}' : '{"before":"schema"}',
+          fileName: 'schema.json',
+        }),
+      } as any;
+    });
+
+    const result = await governanceCheck({ dir: TEMP_DIR, format: 'json' });
+    const parsed = JSON.parse(result.output);
+
+    expect(parsed.results).toHaveLength(1);
+    expect(parsed.results[0].trigger).toBe('schema_changed');
+    expect(parsed.results[0].schemaChanges).toHaveLength(1);
+    expect(parsed.results[0].schemaChanges[0].before).toBe('{"before":"schema"}');
+    expect(parsed.results[0].schemaChanges[0].after).toBe('{"after":"schema"}');
+    expect(parsed.results[0].schemaChanges[0].beforeSchemaPath).toBe('schema.json');
+    expect(parsed.results[0].schemaChanges[0].afterSchemaPath).toBe('schema.json');
+    expect(parsed.results[0].schemaChanges[0].beforeSchemaHash).toHaveLength(64);
+    expect(parsed.results[0].schemaChanges[0].afterSchemaHash).toHaveLength(64);
+    expect(parsed.results[0].schemaChanges[0].consumerServices).toEqual([{ id: 'BillingService', version: '1.0.0' }]);
+  });
+});
diff --git a/packages/cli/src/test/governance.test.ts b/packages/cli/src/test/governance.test.ts
new file mode 100644
index 000000000..0dca6d538
--- /dev/null
+++ b/packages/cli/src/test/governance.test.ts
@@ -0,0 +1,3551 @@
+import { expect, it, describe, beforeEach, afterEach, vi } from 'vitest';
+import path from 'node:path';
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import {
+  loadGovernanceConfig,
+  evaluateGovernanceRules,
+  resolveEnvVars,
+  formatGovernanceOutput,
+  formatFailureOutput,
+  executeGovernanceActions,
+  buildMessageTypeMap,
+  buildServiceOwnersMap,
+  enrichSchemaContent,
+} from '../cli/governance';
+import type {
+  GovernanceConfig,
+  MessageTypeMap,
+  ServiceOwnersMap,
+  GovernanceActionOptions,
+  GovernanceResult,
+} from '../cli/governance';
+import type { SnapshotDiff, RelationshipChange, ResourceChange, CatalogSnapshot } from '@eventcatalog/sdk';
+
+const TEMP_DIR = path.join(__dirname, 'governance-temp');
+
+beforeEach(() => {
+  fs.mkdirSync(TEMP_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(TEMP_DIR, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+const makeDiff = (relationships: RelationshipChange[], resources: ResourceChange[] = []): SnapshotDiff => ({
+  snapshotA: { label: 'before', createdAt: '2026-03-04T12:00:00Z' },
+  snapshotB: { label: 'after', createdAt: '2026-03-04T13:00:00Z' },
+  summary: {
+    totalChanges: relationships.length + resources.length,
+    resourcesAdded: 0,
+    resourcesRemoved: 0,
+    resourcesModified: resources.length,
+    resourcesVersioned: 0,
+    relationshipsAdded: relationships.filter((r) => r.changeType === 'added').length,
+    relationshipsRemoved: relationships.filter((r) => r.changeType === 'removed').length,
+  },
+  resources,
+  relationships,
+});
+
+type SnapshotMessages = {
+  events?: Array<Record<string, any>>;
+  commands?: Array<Record<string, any>>;
+  queries?: Array<Record<string, any>>;
+};
+
+const makeSnapshot = (
+  services: Array<{
+    id: string;
+    sends?: Array<{ id: string; version?: string }>;
+    receives?: Array<{ id: string; version?: string }>;
+    owners?: string[];
+  }>,
+  messages?: SnapshotMessages
+): CatalogSnapshot => ({
+  snapshotVersion: '1.0.0',
+  catalogVersion: '1.0.0',
+  label: 'test',
+  createdAt: '2026-03-04T12:00:00Z',
+  resources: {
+    domains: [],
+    services: services.map((s) => ({ ...s, version: '1.0.0', name: s.id })),
+    messages: {
+      events: messages?.events || [],
+      commands: messages?.commands || [],
+      queries: messages?.queries || [],
+    },
+    channels: [],
+  },
+});
+
+describe('Governance', () => {
+  describe('loadGovernanceConfig', () => {
+    it('returns empty rules when no governance.yaml exists', () => {
+      const config = loadGovernanceConfig(TEMP_DIR);
+      expect(config.rules).toEqual([]);
+    });
+
+    it('throws when governance.yaml contains invalid YAML', () => {
+      fs.writeFileSync(path.join(TEMP_DIR, 'governance.yaml'), 'rules:\n  - name: test\n    bad:\n  indent: broken\n\t\tmixed');
+
+      expect(() => loadGovernanceConfig(TEMP_DIR)).toThrow();
+    });
+
+    it('parses a valid governance.yaml file', () => {
+      fs.writeFileSync(
+        path.join(TEMP_DIR, 'governance.yaml'),
+        `rules:
+  - name: notify-consumer-added
+    when:
+      - consumer_added
+    resources:
+      - "*"
+    actions:
+      - type: console
+`
+      );
+
+      const config = loadGovernanceConfig(TEMP_DIR);
+
+      expect(config.rules).toHaveLength(1);
+      expect(config.rules[0].name).toBe('notify-consumer-added');
+      expect(config.rules[0].when).toEqual(['consumer_added']);
+      expect(config.rules[0].resources).toEqual(['*']);
+      expect(config.rules[0].actions).toEqual([{ type: 'console' }]);
+    });
+
+    it('parses a valid governance.yml file', () => {
+      fs.writeFileSync(
+        path.join(TEMP_DIR, 'governance.yml'),
+        `rules:
+  - name: notify-consumer-added
+    when:
+      - consumer_added
+    resources:
+      - "*"
+    actions:
+      - type: console
+`
+      );
+
+      const config = loadGovernanceConfig(TEMP_DIR);
+
+      expect(config.rules).toHaveLength(1);
+      expect(config.rules[0].name).toBe('notify-consumer-added');
+    });
+
+    it('prefers governance.yaml over governance.yml when both exist', () => {
+      fs.writeFileSync(
+        path.join(TEMP_DIR, 'governance.yaml'),
+        `rules:
+  - name: from-yaml
+    when:
+      - consumer_added
+    resources:
+      - "*"
+    actions:
+      - type: console
+`
+      );
+      fs.writeFileSync(
+        path.join(TEMP_DIR, 'governance.yml'),
+        `rules:
+  - name: from-yml
+    when:
+      - consumer_added
+    resources:
+      - "*"
+    actions:
+      - type: console
+`
+      );
+
+      const config = loadGovernanceConfig(TEMP_DIR);
+      expect(config.rules[0].name).toBe('from-yaml');
+    });
+
+    it('parses rules with webhook actions including headers', () => {
+      fs.writeFileSync(
+        path.join(TEMP_DIR, 'governance.yaml'),
+        `rules:
+  - name: webhook-rule
+    when:
+      - consumer_added
+    resources:
+      - OrderCreated
+    actions:
+      - type: webhook
+        url: https://hooks.slack.com/test
+        headers:
+          Authorization: Bearer token123
+          Content-Type: application/json
+`
+      );
+
+      const config = loadGovernanceConfig(TEMP_DIR);
+
+      expect(config.rules[0].actions[0]).toEqual({
+        type: 'webhook',
+        url: 'https://hooks.slack.com/test',
+        headers: {
+          Authorization: 'Bearer token123',
+          'Content-Type': 'application/json',
+        },
+      });
+    });
+  });
+
+  describe('evaluateGovernanceRules', () => {
+    it('matches consumer_added when a service starts receiving a message', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'consumer-added-rule',
+            when: ['consumer_added'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'PaymentService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].trigger).toBe('consumer_added');
+      expect(results[0].matchedChanges).toHaveLength(1);
+      expect(results[0].matchedChanges[0].serviceId).toBe('PaymentService');
+    });
+
+    it('matches consumer_removed when a service stops receiving a message', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'consumer-removed-rule',
+            when: ['consumer_removed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'LegacyService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'removed',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].trigger).toBe('consumer_removed');
+      expect(results[0].matchedChanges[0].serviceId).toBe('LegacyService');
+    });
+
+    it('does not match consumer_added for sends relationship changes', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'consumer-added-rule',
+            when: ['consumer_added'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'OrdersService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'sends',
+          changeType: 'added',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('filters by specific resource ID', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'order-created-only',
+            when: ['consumer_added'],
+            resources: ['message:OrderCreated'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'PaymentService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+        {
+          serviceId: 'ShippingService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderShipped',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].matchedChanges).toHaveLength(1);
+      expect(results[0].matchedChanges[0].resourceId).toBe('OrderCreated');
+    });
+
+    it('filters by multiple specific resource IDs', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'multi-resource',
+            when: ['consumer_added'],
+            resources: ['message:OrderCreated', 'message:OrderShipped'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'PaymentService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+        {
+          serviceId: 'ShippingService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderShipped',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+        {
+          serviceId: 'AnalyticsService',
+          serviceVersion: '1.0.0',
+          resourceId: 'UserSignedUp',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].matchedChanges).toHaveLength(2);
+    });
+
+    it('filters by service: prefix matching serviceId', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'service-filter',
+            when: ['consumer_added'],
+            resources: ['service:PaymentService'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'PaymentService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+        {
+          serviceId: 'ShippingService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].matchedChanges).toHaveLength(1);
+      expect(results[0].matchedChanges[0].serviceId).toBe('PaymentService');
+    });
+
+    it('ignores bare strings without a prefix', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'bare-string',
+            when: ['consumer_added'],
+            resources: ['OrderCreated'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'PaymentService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('produces: prefix matches changes involving messages a service sends', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'notify-ordersservice-consumers',
+            when: ['consumer_added'],
+            resources: ['produces:OrdersService'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const snapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }, { id: 'OrderShipped' }] }]);
+
+      const diff = makeDiff([
+        {
+          serviceId: 'PaymentService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+        {
+          serviceId: 'AnalyticsService',
+          serviceVersion: '1.0.0',
+          resourceId: 'UserSignedUp',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config, snapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].matchedChanges).toHaveLength(1);
+      expect(results[0].matchedChanges[0].resourceId).toBe('OrderCreated');
+    });
+
+    it('consumes: prefix matches changes involving messages a service receives', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'notify-payment-deps-removed',
+            when: ['producer_removed'],
+            resources: ['consumes:PaymentService'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const snapshot = makeSnapshot([{ id: 'PaymentService', receives: [{ id: 'OrderCreated' }, { id: 'OrderConfirmed' }] }]);
+
+      const diff = makeDiff([
+        {
+          serviceId: 'OrdersService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'sends',
+          changeType: 'removed',
+        },
+        {
+          serviceId: 'ShippingService',
+          serviceVersion: '1.0.0',
+          resourceId: 'ShipmentCreated',
+          resourceVersion: '1.0.0',
+          direction: 'sends',
+          changeType: 'removed',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config, snapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].matchedChanges).toHaveLength(1);
+      expect(results[0].matchedChanges[0].resourceId).toBe('OrderCreated');
+    });
+
+    it('produces: returns no matches when snapshot is not provided', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'no-snapshot',
+            when: ['consumer_added'],
+            resources: ['produces:OrdersService'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'PaymentService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('handles a rule with multiple triggers in when[]', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'both-triggers',
+            when: ['consumer_added', 'consumer_removed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'PaymentService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+        {
+          serviceId: 'LegacyService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'removed',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(2);
+      expect(results.find((r) => r.trigger === 'consumer_added')).toBeDefined();
+      expect(results.find((r) => r.trigger === 'consumer_removed')).toBeDefined();
+    });
+
+    it('returns empty results when no rules match', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'consumer-added-rule',
+            when: ['consumer_added'],
+            resources: ['message:OrderCreated'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'PaymentService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderShipped',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'removed',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('multiple rules can match the same change', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'rule-one',
+            when: ['consumer_added'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+          {
+            name: 'rule-two',
+            when: ['consumer_added'],
+            resources: ['message:OrderCreated'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'PaymentService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(2);
+      expect(results[0].rule.name).toBe('rule-one');
+      expect(results[1].rule.name).toBe('rule-two');
+    });
+
+    it('matches producer_added when a service starts sending a message', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'producer-added-rule',
+            when: ['producer_added'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'OrdersService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'sends',
+          changeType: 'added',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].trigger).toBe('producer_added');
+      expect(results[0].matchedChanges).toHaveLength(1);
+      expect(results[0].matchedChanges[0].serviceId).toBe('OrdersService');
+    });
+
+    it('matches producer_removed when a service stops sending a message', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'producer-removed-rule',
+            when: ['producer_removed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'OrdersService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'sends',
+          changeType: 'removed',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].trigger).toBe('producer_removed');
+      expect(results[0].matchedChanges[0].serviceId).toBe('OrdersService');
+    });
+
+    it('does not match producer_added for receives relationship changes', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'producer-added-rule',
+            when: ['producer_added'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([
+        {
+          serviceId: 'PaymentService',
+          serviceVersion: '1.0.0',
+          resourceId: 'OrderCreated',
+          resourceVersion: '1.0.0',
+          direction: 'receives',
+          changeType: 'added',
+        },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('returns empty results when diff has no relationship changes', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'consumer-added-rule',
+            when: ['consumer_added'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff([]);
+
+      const results = evaluateGovernanceRules(diff, config);
+
+      expect(results).toHaveLength(0);
+    });
+  });
+
+  describe('evaluateGovernanceRules - message_deprecated', () => {
+    it('fires when a message is newly deprecated with wildcard resource', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'deprecation-rule',
+            when: ['message_deprecated'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['deprecated'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated', deprecated: true }],
+      });
+      const baseSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot, baseSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].trigger).toBe('message_deprecated');
+      expect(results[0].deprecationChanges).toHaveLength(1);
+      expect(results[0].deprecationChanges![0].resourceChange.resourceId).toBe('OrderCreated');
+      expect(results[0].deprecationChanges![0].producerServices).toHaveLength(1);
+      expect(results[0].deprecationChanges![0].producerServices[0].id).toBe('OrdersService');
+    });
+
+    it('does not fire when message was already deprecated in base', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'deprecation-rule',
+            when: ['message_deprecated'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['deprecated'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated', deprecated: true }],
+      });
+      const baseSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated', deprecated: true }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot, baseSnapshot);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('does not fire when deprecated field is removed (un-deprecation)', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'deprecation-rule',
+            when: ['message_deprecated'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['deprecated'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+      });
+      const baseSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated', deprecated: true }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot, baseSnapshot);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('supports deprecated as an object with date and message', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'deprecation-rule',
+            when: ['message_deprecated'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['deprecated'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [
+          {
+            id: 'OrderCreated',
+            version: '1.0.0',
+            name: 'OrderCreated',
+            deprecated: { date: '2026-06-01', message: 'Use OrderCreatedV2 instead' },
+          },
+        ],
+      });
+      const baseSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot, baseSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].deprecationChanges![0].resourceChange.resourceId).toBe('OrderCreated');
+    });
+
+    it('filters by message: prefix', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'specific-message',
+            when: ['message_deprecated'],
+            resources: ['message:OrderCreated'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['deprecated'],
+          },
+          {
+            resourceId: 'OrderShipped',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['deprecated'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }, { id: 'OrderShipped' }] }], {
+        events: [
+          { id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated', deprecated: true },
+          { id: 'OrderShipped', version: '1.0.0', name: 'OrderShipped', deprecated: true },
+        ],
+      });
+      const baseSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }, { id: 'OrderShipped' }] }], {
+        events: [
+          { id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' },
+          { id: 'OrderShipped', version: '1.0.0', name: 'OrderShipped' },
+        ],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot, baseSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].deprecationChanges).toHaveLength(1);
+      expect(results[0].deprecationChanges![0].resourceChange.resourceId).toBe('OrderCreated');
+    });
+
+    it('filters by consumes: prefix to notify consuming services', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'consumer-deprecation-alert',
+            when: ['message_deprecated'],
+            resources: ['consumes:PaymentService'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['deprecated'],
+          },
+          {
+            resourceId: 'UserSignedUp',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['deprecated'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot(
+        [
+          { id: 'OrdersService', sends: [{ id: 'OrderCreated' }] },
+          { id: 'PaymentService', receives: [{ id: 'OrderCreated' }] },
+          { id: 'AuthService', sends: [{ id: 'UserSignedUp' }] },
+        ],
+        {
+          events: [
+            { id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated', deprecated: true },
+            { id: 'UserSignedUp', version: '1.0.0', name: 'UserSignedUp', deprecated: true },
+          ],
+        }
+      );
+      const baseSnapshot = makeSnapshot(
+        [
+          { id: 'OrdersService', sends: [{ id: 'OrderCreated' }] },
+          { id: 'PaymentService', receives: [{ id: 'OrderCreated' }] },
+          { id: 'AuthService', sends: [{ id: 'UserSignedUp' }] },
+        ],
+        {
+          events: [
+            { id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' },
+            { id: 'UserSignedUp', version: '1.0.0', name: 'UserSignedUp' },
+          ],
+        }
+      );
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot, baseSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].deprecationChanges).toHaveLength(1);
+      expect(results[0].deprecationChanges![0].resourceChange.resourceId).toBe('OrderCreated');
+    });
+
+    it('includes producer service owners in deprecation changes', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'deprecation-rule',
+            when: ['message_deprecated'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['deprecated'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }], owners: ['team-orders'] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated', deprecated: true }],
+      });
+      const baseSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }], owners: ['team-orders'] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot, baseSnapshot);
+
+      expect(results[0].deprecationChanges![0].producerServices[0].owners).toEqual(['team-orders']);
+    });
+
+    it('works with commands and queries, not just events', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'deprecation-rule',
+            when: ['message_deprecated'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'PlaceOrder',
+            version: '1.0.0',
+            type: 'command',
+            changeType: 'modified',
+            changedFields: ['deprecated'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'PlaceOrder' }] }], {
+        commands: [{ id: 'PlaceOrder', version: '1.0.0', name: 'PlaceOrder', deprecated: true }],
+      });
+      const baseSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'PlaceOrder' }] }], {
+        commands: [{ id: 'PlaceOrder', version: '1.0.0', name: 'PlaceOrder' }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot, baseSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].deprecationChanges![0].resourceChange.type).toBe('command');
+    });
+
+    it('ignores non-message resource types like service', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'deprecation-rule',
+            when: ['message_deprecated'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrdersService',
+            version: '1.0.0',
+            type: 'service',
+            changeType: 'modified',
+            changedFields: ['deprecated'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [] }]);
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(0);
+    });
+  });
+
+  describe('evaluateGovernanceRules - schema_changed', () => {
+    it('when a message schema hash changes, the schema_changed rule triggers for that message', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'schema-change-rule',
+            when: ['schema_changed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+      });
+      const baseSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot, baseSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].trigger).toBe('schema_changed');
+      expect(results[0].schemaChanges).toHaveLength(1);
+      expect(results[0].schemaChanges![0].resourceChange.resourceId).toBe('OrderCreated');
+    });
+
+    it('when a resource changes without changing schemaHash, the schema_changed rule does not trigger', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'schema-change-rule',
+            when: ['schema_changed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['name'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }]);
+      const baseSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }]);
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot, baseSnapshot);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('when a rule targets message:OrderCreated, it ignores schema changes for other messages', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'specific-schema-rule',
+            when: ['schema_changed'],
+            resources: ['message:OrderCreated'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+          {
+            resourceId: 'PaymentProcessed',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }]);
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].schemaChanges).toHaveLength(1);
+      expect(results[0].schemaChanges![0].resourceChange.resourceId).toBe('OrderCreated');
+    });
+
+    it('when a rule targets consumes:PaymentService, it triggers for schema changes on messages consumed by that service', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'consumer-schema-rule',
+            when: ['schema_changed'],
+            resources: ['consumes:PaymentService'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+          {
+            resourceId: 'UserRegistered',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([
+        { id: 'PaymentService', receives: [{ id: 'OrderCreated' }] },
+        { id: 'OrdersService', sends: [{ id: 'OrderCreated' }] },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].schemaChanges).toHaveLength(1);
+      expect(results[0].schemaChanges![0].resourceChange.resourceId).toBe('OrderCreated');
+    });
+
+    it('when a rule targets produces:OrdersService, it triggers for schema changes on messages produced by that service', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'producer-schema-rule',
+            when: ['schema_changed'],
+            resources: ['produces:OrdersService'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+          {
+            resourceId: 'UserRegistered',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([
+        { id: 'OrdersService', sends: [{ id: 'OrderCreated' }] },
+        { id: 'UserService', sends: [{ id: 'UserRegistered' }] },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].schemaChanges).toHaveLength(1);
+      expect(results[0].schemaChanges![0].resourceChange.resourceId).toBe('OrderCreated');
+    });
+
+    it('when a schema change is matched, it includes impacted consumer and producer services in the result', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'schema-change-rule',
+            when: ['schema_changed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([
+        { id: 'OrdersService', sends: [{ id: 'OrderCreated' }], owners: ['team-orders'] },
+        { id: 'PaymentService', receives: [{ id: 'OrderCreated' }], owners: ['team-payments'] },
+        { id: 'NotificationService', receives: [{ id: 'OrderCreated' }] },
+      ]);
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(1);
+      const sc = results[0].schemaChanges![0];
+      expect(sc.producerServices).toHaveLength(1);
+      expect(sc.producerServices[0]).toEqual({ id: 'OrdersService', version: '1.0.0', owners: ['team-orders'] });
+      expect(sc.consumerServices).toHaveLength(2);
+      expect(sc.consumerServices.find((c) => c.id === 'PaymentService')).toEqual({
+        id: 'PaymentService',
+        version: '1.0.0',
+        owners: ['team-payments'],
+      });
+      expect(sc.consumerServices.find((c) => c.id === 'NotificationService')).toEqual({
+        id: 'NotificationService',
+        version: '1.0.0',
+      });
+    });
+
+    it('when a schema changes for version 2.0.0, only services pinned to version 2.0.0 are included as impacted consumers and producers', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'schema-change-rule',
+            when: ['schema_changed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '2.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot(
+        [
+          { id: 'OrdersV1Producer', sends: [{ id: 'OrderCreated', version: '1.0.0' }] },
+          { id: 'OrdersV2Producer', sends: [{ id: 'OrderCreated', version: '2.0.0' }] },
+          { id: 'BillingV1Consumer', receives: [{ id: 'OrderCreated', version: '1.0.0' }] },
+          { id: 'BillingV2Consumer', receives: [{ id: 'OrderCreated', version: '2.0.0' }] },
+        ],
+        {
+          events: [{ id: 'OrderCreated', version: '2.0.0', name: 'OrderCreated' }],
+        }
+      );
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].schemaChanges).toHaveLength(1);
+      expect(results[0].schemaChanges![0].producerServices).toEqual([{ id: 'OrdersV2Producer', version: '1.0.0' }]);
+      expect(results[0].schemaChanges![0].consumerServices).toEqual([{ id: 'BillingV2Consumer', version: '1.0.0' }]);
+    });
+
+    it('when a schema changes for the latest version, services with no version are treated as consuming and producing latest', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'schema-change-rule',
+            when: ['schema_changed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '2.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot(
+        [
+          { id: 'OrdersLatestProducer', sends: [{ id: 'OrderCreated' }] },
+          { id: 'BillingLatestConsumer', receives: [{ id: 'OrderCreated' }] },
+        ],
+        {
+          events: [{ id: 'OrderCreated', version: '2.0.0', name: 'OrderCreated' }],
+        }
+      );
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].schemaChanges).toHaveLength(1);
+      expect(results[0].schemaChanges![0].producerServices).toEqual([{ id: 'OrdersLatestProducer', version: '1.0.0' }]);
+      expect(results[0].schemaChanges![0].consumerServices).toEqual([{ id: 'BillingLatestConsumer', version: '1.0.0' }]);
+    });
+
+    it('when a schema changes for version 2.0.0, services with no version are not included if 2.0.0 is not the latest version in the target snapshot', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'schema-change-rule',
+            when: ['schema_changed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '2.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot(
+        [
+          { id: 'OrdersLatestProducer', sends: [{ id: 'OrderCreated' }] },
+          { id: 'BillingLatestConsumer', receives: [{ id: 'OrderCreated' }] },
+          { id: 'OrdersV2Producer', sends: [{ id: 'OrderCreated', version: '2.0.0' }] },
+          { id: 'BillingV2Consumer', receives: [{ id: 'OrderCreated', version: '2.0.0' }] },
+        ],
+        {
+          events: [{ id: 'OrderCreated', version: '3.0.0', name: 'OrderCreated' }],
+        }
+      );
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].schemaChanges).toHaveLength(1);
+      expect(results[0].schemaChanges![0].producerServices).toEqual([{ id: 'OrdersV2Producer', version: '1.0.0' }]);
+      expect(results[0].schemaChanges![0].consumerServices).toEqual([{ id: 'BillingV2Consumer', version: '1.0.0' }]);
+    });
+
+    it('when a rule targets consumes:BillingService, it does not trigger for a schema change on a version BillingService does not consume', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'schema-change-rule',
+            when: ['schema_changed'],
+            resources: ['consumes:BillingService'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '2.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'BillingService', receives: [{ id: 'OrderCreated', version: '1.0.0' }] }], {
+        events: [{ id: 'OrderCreated', version: '2.0.0', name: 'OrderCreated' }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('when a rule targets produces:OrdersService, it does not trigger for a schema change on a version OrdersService does not produce', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'schema-change-rule',
+            when: ['schema_changed'],
+            resources: ['produces:OrdersService'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '2.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated', version: '1.0.0' }] }], {
+        events: [{ id: 'OrderCreated', version: '2.0.0', name: 'OrderCreated' }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('when a service uses a caret semver range, it is included when the changed schema version satisfies that range', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'schema-change-rule',
+            when: ['schema_changed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.2.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot(
+        [
+          { id: 'OrdersCaretProducer', sends: [{ id: 'OrderCreated', version: '^1.0.0' }] },
+          { id: 'BillingCaretConsumer', receives: [{ id: 'OrderCreated', version: '^1.0.0' }] },
+        ],
+        {
+          events: [{ id: 'OrderCreated', version: '2.0.0', name: 'OrderCreated' }],
+        }
+      );
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].schemaChanges).toHaveLength(1);
+      expect(results[0].schemaChanges![0].producerServices).toEqual([{ id: 'OrdersCaretProducer', version: '1.0.0' }]);
+      expect(results[0].schemaChanges![0].consumerServices).toEqual([{ id: 'BillingCaretConsumer', version: '1.0.0' }]);
+    });
+
+    it('when a service uses a tilde semver range, it is included for compatible patch releases and excluded for incompatible minor releases', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'schema-change-rule',
+            when: ['schema_changed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const patchDiff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.2.5',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const incompatibleMinorDiff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.3.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot(
+        [
+          { id: 'OrdersTildeProducer', sends: [{ id: 'OrderCreated', version: '~1.2.0' }] },
+          { id: 'BillingTildeConsumer', receives: [{ id: 'OrderCreated', version: '~1.2.0' }] },
+        ],
+        {
+          events: [{ id: 'OrderCreated', version: '2.0.0', name: 'OrderCreated' }],
+        }
+      );
+
+      const patchResults = evaluateGovernanceRules(patchDiff, config, targetSnapshot);
+      const incompatibleMinorResults = evaluateGovernanceRules(incompatibleMinorDiff, config, targetSnapshot);
+
+      expect(patchResults).toHaveLength(1);
+      expect(patchResults[0].schemaChanges).toHaveLength(1);
+      expect(patchResults[0].schemaChanges![0].producerServices).toEqual([{ id: 'OrdersTildeProducer', version: '1.0.0' }]);
+      expect(patchResults[0].schemaChanges![0].consumerServices).toEqual([{ id: 'BillingTildeConsumer', version: '1.0.0' }]);
+
+      expect(incompatibleMinorResults).toHaveLength(1);
+      expect(incompatibleMinorResults[0].schemaChanges).toHaveLength(1);
+      expect(incompatibleMinorResults[0].schemaChanges![0].producerServices).toEqual([]);
+      expect(incompatibleMinorResults[0].schemaChanges![0].consumerServices).toEqual([]);
+    });
+
+    it('when schemaHash changes on commands and queries, the schema_changed rule treats them as supported message types', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'schema-change-rule',
+            when: ['schema_changed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'ProcessPayment',
+            version: '1.0.0',
+            type: 'command',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+          {
+            resourceId: 'GetOrder',
+            version: '1.0.0',
+            type: 'query',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'ProcessPayment' }, { id: 'GetOrder' }] }]);
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].schemaChanges).toHaveLength(2);
+    });
+
+    it('when schemaHash changes on non-message resources, the schema_changed rule ignores those changes', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'schema-change-rule',
+            when: ['schema_changed'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrdersService',
+            version: '1.0.0',
+            type: 'service',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService' }]);
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(0);
+    });
+  });
+
+  describe('evaluateGovernanceRules - schema_breaking_change', () => {
+    it('triggers schema_breaking_change when schema has breaking changes per strategy', () => {
+      const config: GovernanceConfig = {
+        compatibility: { strategy: 'BACKWARD' },
+        rules: [
+          {
+            name: 'breaking-schema-rule',
+            when: ['schema_breaking_change'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+      });
+
+      const baseSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot, baseSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].trigger).toBe('schema_breaking_change');
+    });
+
+    it('does not trigger when compatibility strategy is NONE', () => {
+      const config: GovernanceConfig = {
+        compatibility: { strategy: 'NONE' },
+        rules: [
+          {
+            name: 'breaking-schema-rule',
+            when: ['schema_breaking_change'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+      expect(results).toHaveLength(0);
+    });
+
+    it('does not trigger when no compatibility config is set', () => {
+      const config: GovernanceConfig = {
+        rules: [
+          {
+            name: 'breaking-schema-rule',
+            when: ['schema_breaking_change'],
+            resources: ['*'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+      expect(results).toHaveLength(0);
+    });
+
+    it('respects resource filters for schema_breaking_change', () => {
+      const config: GovernanceConfig = {
+        compatibility: { strategy: 'BACKWARD' },
+        rules: [
+          {
+            name: 'breaking-schema-rule',
+            when: ['schema_breaking_change'],
+            resources: ['message:OrderCreated'],
+            actions: [{ type: 'console' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+          {
+            resourceId: 'PaymentProcessed',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot(
+        [
+          { id: 'OrdersService', sends: [{ id: 'OrderCreated' }] },
+          { id: 'PaymentService', sends: [{ id: 'PaymentProcessed' }] },
+        ],
+        {
+          events: [
+            { id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' },
+            { id: 'PaymentProcessed', version: '1.0.0', name: 'PaymentProcessed' },
+          ],
+        }
+      );
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].breakingSchemaChanges).toHaveLength(1);
+      expect(results[0].breakingSchemaChanges![0].resourceChange.resourceId).toBe('OrderCreated');
+    });
+
+    it('schema_breaking_change with fail action preserves fail action on result', () => {
+      const config: GovernanceConfig = {
+        compatibility: { strategy: 'BACKWARD' },
+        rules: [
+          {
+            name: 'block-breaking-changes',
+            when: ['schema_breaking_change'],
+            resources: ['*'],
+            actions: [{ type: 'fail', message: 'Breaking schema changes are not allowed' }],
+          },
+        ],
+      };
+
+      const diff = makeDiff(
+        [],
+        [
+          {
+            resourceId: 'OrderCreated',
+            version: '1.0.0',
+            type: 'event',
+            changeType: 'modified',
+            changedFields: ['schemaHash'],
+          },
+        ]
+      );
+
+      const targetSnapshot = makeSnapshot([{ id: 'OrdersService', sends: [{ id: 'OrderCreated' }] }], {
+        events: [{ id: 'OrderCreated', version: '1.0.0', name: 'OrderCreated' }],
+      });
+
+      const results = evaluateGovernanceRules(diff, config, targetSnapshot);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].rule.actions[0].type).toBe('fail');
+    });
+  });
+
+  describe('formatGovernanceOutput - schema_changed', () => {
+    it('when formatting schema_changed output, it includes the changed message type and impacted consumer names', () => {
+      const results: GovernanceResult[] = [
+        {
+          rule: {
+            name: 'schema-change-rule',
+            when: ['schema_changed' as const],
+            resources: ['*'],
+            actions: [{ type: 'console' as const }],
+          },
+          trigger: 'schema_changed' as const,
+          matchedChanges: [],
+          schemaChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrderCreated',
+                version: '1.0.0',
+                type: 'event' as const,
+                changeType: 'modified' as const,
+                changedFields: ['schemaHash'],
+              },
+              consumerServices: [
+                { id: 'PaymentService', version: '1.0.0' },
+                { id: 'NotificationService', version: '1.0.0' },
+              ],
+              producerServices: [{ id: 'OrdersService', version: '1.0.0' }],
+            },
+          ],
+        },
+      ];
+
+      const output = formatGovernanceOutput(results);
+
+      expect(output).toContain('schema-change-rule');
+      expect(output).toContain('schema_changed');
+      expect(output).toContain('OrderCreated');
+      expect(output).toContain('event');
+      expect(output).toContain('PaymentService');
+      expect(output).toContain('NotificationService');
+    });
+  });
+
+  describe('formatGovernanceOutput - message_deprecated', () => {
+    it('formats deprecation results with producer names', () => {
+      const results: GovernanceResult[] = [
+        {
+          rule: {
+            name: 'deprecation-rule',
+            when: ['message_deprecated' as const],
+            resources: ['*'],
+            actions: [{ type: 'console' as const }],
+          },
+          trigger: 'message_deprecated' as const,
+          matchedChanges: [],
+          deprecationChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrderCreated',
+                version: '1.0.0',
+                type: 'event' as const,
+                changeType: 'modified' as const,
+                changedFields: ['deprecated'],
+              },
+              producerServices: [
+                { id: 'OrdersService', version: '1.0.0' },
+                { id: 'LegacyService', version: '2.0.0' },
+              ],
+            },
+          ],
+        },
+      ];
+
+      const output = formatGovernanceOutput(results);
+
+      expect(output).toContain('deprecation-rule');
+      expect(output).toContain('message_deprecated');
+      expect(output).toContain('! OrderCreated (event) deprecated by OrdersService, LegacyService');
+    });
+
+    it('shows unknown producer when no producer services found', () => {
+      const results: GovernanceResult[] = [
+        {
+          rule: {
+            name: 'deprecation-rule',
+            when: ['message_deprecated' as const],
+            resources: ['*'],
+            actions: [{ type: 'console' as const }],
+          },
+          trigger: 'message_deprecated' as const,
+          matchedChanges: [],
+          deprecationChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrphanEvent',
+                version: '1.0.0',
+                type: 'event' as const,
+                changeType: 'modified' as const,
+                changedFields: ['deprecated'],
+              },
+              producerServices: [],
+            },
+          ],
+        },
+      ];
+
+      const output = formatGovernanceOutput(results);
+
+      expect(output).toContain('! OrphanEvent (event) deprecated by unknown producer');
+    });
+  });
+
+  describe('resolveEnvVars', () => {
+    it('replaces $VAR_NAME with environment variable value', () => {
+      vi.stubEnv('MY_WEBHOOK_URL', 'https://hooks.slack.com/test');
+
+      expect(resolveEnvVars('$MY_WEBHOOK_URL')).toBe('https://hooks.slack.com/test');
+    });
+
+    it('replaces $VAR within a larger string', () => {
+      vi.stubEnv('API_TOKEN', 'secret123');
+
+      expect(resolveEnvVars('Bearer $API_TOKEN')).toBe('Bearer secret123');
+    });
+
+    it('throws when an environment variable is not set', () => {
+      delete process.env.MISSING_VAR;
+
+      expect(() => resolveEnvVars('$MISSING_VAR')).toThrow('MISSING_VAR');
+    });
+
+    it('returns string unchanged when no $VAR patterns present', () => {
+      expect(resolveEnvVars('https://example.com')).toBe('https://example.com');
+    });
+  });
+
+  describe('formatGovernanceOutput', () => {
+    it('formats consumer_added results as human-readable text', () => {
+      const results: GovernanceResult[] = [
+        {
+          rule: {
+            name: 'consumer-added-rule',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'console' as const }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'PaymentService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      const output = formatGovernanceOutput(results);
+
+      expect(output).toContain('consumer-added-rule');
+      expect(output).toContain('PaymentService');
+      expect(output).toContain('OrderCreated');
+    });
+
+    it('returns compliant message when no results', () => {
+      const output = formatGovernanceOutput([]);
+
+      expect(output).toContain('No governance rules triggered');
+    });
+
+    it('formats producer_added results with producing verb', () => {
+      const results: GovernanceResult[] = [
+        {
+          rule: {
+            name: 'producer-added-rule',
+            when: ['producer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'console' as const }],
+          },
+          trigger: 'producer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'OrdersService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'sends' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      const output = formatGovernanceOutput(results);
+
+      expect(output).toContain('+ OrdersService is now producing OrderCreated');
+    });
+
+    it('formats producer_removed results with no longer producing verb', () => {
+      const results = [
+        {
+          rule: {
+            name: 'producer-removed-rule',
+            when: ['producer_removed' as const],
+            resources: ['*'],
+            actions: [{ type: 'console' as const }],
+          },
+          trigger: 'producer_removed' as const,
+          matchedChanges: [
+            {
+              serviceId: 'OrdersService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'sends' as const,
+              changeType: 'removed' as const,
+            },
+          ],
+        },
+      ];
+
+      const output = formatGovernanceOutput(results);
+
+      expect(output).toContain('- OrdersService is no longer producing OrderCreated');
+    });
+
+    it('formats consumer_removed results correctly', () => {
+      const results = [
+        {
+          rule: {
+            name: 'consumer-removed-rule',
+            when: ['consumer_removed' as const],
+            resources: ['*'],
+            actions: [{ type: 'console' as const }],
+          },
+          trigger: 'consumer_removed' as const,
+          matchedChanges: [
+            {
+              serviceId: 'LegacyService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'removed' as const,
+            },
+          ],
+        },
+      ];
+
+      const output = formatGovernanceOutput(results);
+
+      expect(output).toContain('- LegacyService is no longer consuming OrderCreated');
+    });
+  });
+
+  describe('executeGovernanceActions', () => {
+    const eventMessageTypes: MessageTypeMap = new Map([['OrderCreated', 'event']]);
+
+    it('returns empty output for console-only actions', async () => {
+      const results = [
+        {
+          rule: {
+            name: 'console-rule',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'console' as const }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'PaymentService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      const output = await executeGovernanceActions(results);
+
+      expect(output).toEqual([]);
+    });
+
+    it('sends one webhook per change with CloudEvents envelope', async () => {
+      vi.stubEnv('TEST_WEBHOOK_URL', 'https://hooks.example.com/webhook');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'webhook-rule',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$TEST_WEBHOOK_URL' }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'PaymentService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      const output = await executeGovernanceActions(results, { messageTypes: eventMessageTypes });
+
+      expect(fetchSpy).toHaveBeenCalledOnce();
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body.specversion).toBe('1.0');
+      expect(body.type).toBe('eventcatalog.governance.consumer_added');
+      expect(body.source).toBe('eventcatalog/governance');
+      expect(body.id).toBeDefined();
+      expect(body.time).toBeDefined();
+      expect(body.datacontenttype).toBe('application/json');
+      expect(body.data).toEqual({
+        schemaVersion: 1,
+        summary: 'PaymentService is now consuming the event OrderCreated',
+        consumer: { id: 'PaymentService', version: '1.0.0' },
+        message: { id: 'OrderCreated', version: '1.0.0', type: 'event' },
+      });
+      expect(output).toEqual(['  Webhook sent: $TEST_WEBHOOK_URL ✓']);
+    });
+
+    it('includes status in payload when provided', async () => {
+      vi.stubEnv('STATUS_URL', 'https://status.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'status-test',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$STATUS_URL' }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'PaymentService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      await executeGovernanceActions(results, { messageTypes: eventMessageTypes, status: 'proposed' });
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body.data.status).toBe('proposed');
+    });
+
+    it('omits status from payload when not provided', async () => {
+      vi.stubEnv('NO_STATUS_URL', 'https://nostatus.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'no-status-test',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$NO_STATUS_URL' }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'PaymentService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      await executeGovernanceActions(results, { messageTypes: eventMessageTypes });
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body.data.status).toBeUndefined();
+    });
+
+    it('includes message type from the message type map', async () => {
+      vi.stubEnv('TYPE_URL', 'https://type.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+      const commandTypes: MessageTypeMap = new Map([['PlaceOrder', 'command']]);
+
+      const results = [
+        {
+          rule: {
+            name: 'type-test',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$TYPE_URL' }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'OrdersService',
+              serviceVersion: '1.0.0',
+              resourceId: 'PlaceOrder',
+              resourceVersion: '2.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      await executeGovernanceActions(results, { messageTypes: commandTypes });
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body.data.message.type).toBe('command');
+    });
+
+    it('defaults message type to "message" when no type map provided', async () => {
+      vi.stubEnv('NO_MAP_URL', 'https://nomap.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'no-map',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$NO_MAP_URL' }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'SomeService',
+              serviceVersion: '1.0.0',
+              resourceId: 'UnknownMessage',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      await executeGovernanceActions(results);
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body.data.message.type).toBe('message');
+    });
+
+    it('sends separate webhooks for each matched change', async () => {
+      vi.stubEnv('MULTI_URL', 'https://multi.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'multi-change',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$MULTI_URL' }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'PaymentService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+            {
+              serviceId: 'ShippingService',
+              serviceVersion: '2.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      await executeGovernanceActions(results, { messageTypes: eventMessageTypes });
+
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+
+      const body1 = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body1.data.summary).toBe('PaymentService is now consuming the event OrderCreated');
+      expect(body1.data.consumer.id).toBe('PaymentService');
+
+      const body2 = JSON.parse(fetchSpy.mock.calls[1][1]!.body as string);
+      expect(body2.data.summary).toBe('ShippingService is now consuming the event OrderCreated');
+      expect(body2.data.consumer.id).toBe('ShippingService');
+
+      // Each webhook gets a unique CloudEvents id
+      expect(body1.id).not.toBe(body2.id);
+    });
+
+    it('sends webhook with custom headers resolved from env vars', async () => {
+      vi.stubEnv('WEBHOOK_URL', 'https://api.example.com/notify');
+      vi.stubEnv('API_TOKEN', 'my-secret-token');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'webhook-with-headers',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [
+              {
+                type: 'webhook' as const,
+                url: '$WEBHOOK_URL',
+                headers: {
+                  Authorization: 'Bearer $API_TOKEN',
+                  'X-Custom': 'static-value',
+                },
+              },
+            ],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'PaymentService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      await executeGovernanceActions(results);
+
+      expect(fetchSpy).toHaveBeenCalledWith('https://api.example.com/notify', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: 'Bearer my-secret-token',
+          'X-Custom': 'static-value',
+        },
+        body: expect.any(String),
+      });
+    });
+
+    it('reports failure when a webhook request throws', async () => {
+      vi.stubEnv('FAIL_URL', 'https://fail.example.com');
+
+      vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('Connection refused'));
+
+      const results = [
+        {
+          rule: {
+            name: 'failing-webhook',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$FAIL_URL' }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'PaymentService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      const output = await executeGovernanceActions(results);
+
+      expect(output).toHaveLength(1);
+      expect(output[0]).toContain('$FAIL_URL');
+      expect(output[0]).toContain('✗');
+      expect(output[0]).toContain('Connection refused');
+    });
+
+    it('reports failure when webhook returns non-2xx status', async () => {
+      vi.stubEnv('NON2XX_URL', 'https://non2xx.example.com');
+
+      vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('Forbidden', { status: 403 }));
+
+      const results = [
+        {
+          rule: {
+            name: 'non2xx-webhook',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$NON2XX_URL' }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'PaymentService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      const output = await executeGovernanceActions(results);
+
+      expect(output).toHaveLength(1);
+      expect(output[0]).toContain('$NON2XX_URL');
+      expect(output[0]).toContain('✗');
+      expect(output[0]).toContain('HTTP 403');
+    });
+
+    it('consumer_removed payload uses correct summary verb', async () => {
+      vi.stubEnv('REMOVED_URL', 'https://removed.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'removed-rule',
+            when: ['consumer_removed' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$REMOVED_URL' }],
+          },
+          trigger: 'consumer_removed' as const,
+          matchedChanges: [
+            {
+              serviceId: 'LegacyService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'removed' as const,
+            },
+          ],
+        },
+      ];
+
+      await executeGovernanceActions(results, { messageTypes: eventMessageTypes });
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body.type).toBe('eventcatalog.governance.consumer_removed');
+      expect(body.data.summary).toBe('LegacyService is no longer consuming the event OrderCreated');
+      expect(body.data.consumer.id).toBe('LegacyService');
+    });
+
+    it('producer_added payload uses producer field instead of consumer', async () => {
+      vi.stubEnv('PRODUCER_URL', 'https://producer.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'producer-webhook',
+            when: ['producer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$PRODUCER_URL' }],
+          },
+          trigger: 'producer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'OrdersService',
+              serviceVersion: '2.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'sends' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      await executeGovernanceActions(results, { messageTypes: eventMessageTypes });
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body.type).toBe('eventcatalog.governance.producer_added');
+      expect(body.data.summary).toBe('OrdersService is now producing the event OrderCreated');
+      expect(body.data.producer).toEqual({ id: 'OrdersService', version: '2.0.0' });
+      expect(body.data.consumer).toBeUndefined();
+      expect(body.data.message).toEqual({ id: 'OrderCreated', version: '1.0.0', type: 'event' });
+    });
+
+    it('producer_removed payload uses correct summary verb', async () => {
+      vi.stubEnv('PROD_REMOVED_URL', 'https://prod-removed.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'producer-removed-webhook',
+            when: ['producer_removed' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$PROD_REMOVED_URL' }],
+          },
+          trigger: 'producer_removed' as const,
+          matchedChanges: [
+            {
+              serviceId: 'OrdersService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'sends' as const,
+              changeType: 'removed' as const,
+            },
+          ],
+        },
+      ];
+
+      await executeGovernanceActions(results, { messageTypes: eventMessageTypes });
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body.type).toBe('eventcatalog.governance.producer_removed');
+      expect(body.data.summary).toBe('OrdersService is no longer producing the event OrderCreated');
+      expect(body.data.producer).toEqual({ id: 'OrdersService', version: '1.0.0' });
+      expect(body.data.consumer).toBeUndefined();
+    });
+
+    it('includes owners in payload when service has owners', async () => {
+      vi.stubEnv('OWNER_URL', 'https://owner.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'test-owners',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$OWNER_URL' }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'PaymentService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      const serviceOwners: ServiceOwnersMap = new Map([['PaymentService', ['team-payments', 'team-platform']]]);
+
+      await executeGovernanceActions(results, { serviceOwners });
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body as string);
+      expect(body.data.consumer.owners).toEqual(['team-payments', 'team-platform']);
+    });
+
+    it('omits owners from payload when service has no owners', async () => {
+      vi.stubEnv('NO_OWNER_URL', 'https://no-owner.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'test-no-owners',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$NO_OWNER_URL' }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'UnownedService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      const serviceOwners: ServiceOwnersMap = new Map();
+
+      await executeGovernanceActions(results, { serviceOwners });
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body as string);
+      expect(body.data.consumer.owners).toBeUndefined();
+    });
+
+    it('includes owners in producer payload', async () => {
+      vi.stubEnv('PROD_OWNER_URL', 'https://prod-owner.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'test-producer-owners',
+            when: ['producer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$PROD_OWNER_URL' }],
+          },
+          trigger: 'producer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'OrdersService',
+              serviceVersion: '2.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'sends' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      const serviceOwners: ServiceOwnersMap = new Map([['OrdersService', ['team-orders']]]);
+
+      await executeGovernanceActions(results, { serviceOwners });
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body as string);
+      expect(body.data.producer.owners).toEqual(['team-orders']);
+      expect(body.data.consumer).toBeUndefined();
+    });
+
+    it('sends deprecation webhook with CloudEvents envelope per producer', async () => {
+      vi.stubEnv('DEPR_WEBHOOK_URL', 'https://deprecation.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'deprecation-webhook',
+            when: ['message_deprecated' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$DEPR_WEBHOOK_URL' }],
+          },
+          trigger: 'message_deprecated' as const,
+          matchedChanges: [],
+          deprecationChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrderCreated',
+                version: '1.0.0',
+                type: 'event' as const,
+                changeType: 'modified' as const,
+                changedFields: ['deprecated'],
+              },
+              producerServices: [
+                { id: 'OrdersService', version: '2.0.0', owners: ['team-orders'] },
+                { id: 'LegacyService', version: '1.0.0' },
+              ],
+            },
+          ],
+        },
+      ];
+
+      const eventTypes: MessageTypeMap = new Map([['OrderCreated', 'event']]);
+      const output = await executeGovernanceActions(results, { messageTypes: eventTypes });
+
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+
+      const body1 = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body1.specversion).toBe('1.0');
+      expect(body1.type).toBe('eventcatalog.governance.message_deprecated');
+      expect(body1.source).toBe('eventcatalog/governance');
+      expect(body1.data.summary).toBe('OrderCreated (event) has been deprecated by OrdersService');
+      expect(body1.data.producer).toEqual({ id: 'OrdersService', version: '2.0.0', owners: ['team-orders'] });
+      expect(body1.data.message).toEqual({ id: 'OrderCreated', version: '1.0.0', type: 'event' });
+
+      const body2 = JSON.parse(fetchSpy.mock.calls[1][1]!.body as string);
+      expect(body2.data.producer).toEqual({ id: 'LegacyService', version: '1.0.0' });
+      expect(body2.data.producer.owners).toBeUndefined();
+
+      expect(body1.id).not.toBe(body2.id);
+      expect(output).toHaveLength(2);
+      expect(output[0]).toContain('✓');
+    });
+
+    it('sends fallback deprecation webhook when producerServices is empty', async () => {
+      vi.stubEnv('DEPR_WEBHOOK_URL', 'https://deprecation.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'deprecation-webhook',
+            when: ['message_deprecated' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$DEPR_WEBHOOK_URL' }],
+          },
+          trigger: 'message_deprecated' as const,
+          matchedChanges: [],
+          deprecationChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrphanEvent',
+                version: '1.0.0',
+                type: 'event' as const,
+                changeType: 'modified' as const,
+                changedFields: ['deprecated'],
+              },
+              producerServices: [],
+            },
+          ],
+        },
+      ];
+
+      const eventTypes: MessageTypeMap = new Map([['OrphanEvent', 'event']]);
+      const output = await executeGovernanceActions(results, { messageTypes: eventTypes });
+
+      expect(fetchSpy).toHaveBeenCalledOnce();
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body.type).toBe('eventcatalog.governance.message_deprecated');
+      expect(body.data.summary).toBe('OrphanEvent (event) has been deprecated by unknown');
+      expect(body.data.producer).toEqual({ id: 'unknown', version: 'unknown' });
+      expect(body.data.message).toEqual({ id: 'OrphanEvent', version: '1.0.0', type: 'event' });
+      expect(output).toHaveLength(1);
+      expect(output[0]).toContain('✓');
+    });
+
+    it('sends schema_changed webhook with schema hashes, schema paths, impacted services, and refs instead of raw schema bodies', async () => {
+      vi.stubEnv('SCHEMA_WEBHOOK_URL', 'https://schema.example.com/hook');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'schema-change-webhook',
+            when: ['schema_changed' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$SCHEMA_WEBHOOK_URL' }],
+          },
+          trigger: 'schema_changed' as const,
+          matchedChanges: [],
+          schemaChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrderCreated',
+                version: '1.0.0',
+                type: 'event' as const,
+                changeType: 'modified' as const,
+                changedFields: ['schemaHash'],
+              },
+              consumerServices: [{ id: 'PaymentService', version: '1.0.0', owners: ['team-payments'] }],
+              producerServices: [{ id: 'OrdersService', version: '1.0.0', owners: ['team-orders'] }],
+              beforeSchemaHash: 'before-hash',
+              afterSchemaHash: 'after-hash',
+              beforeSchemaPath: 'schemas/order-created.v1.json',
+              afterSchemaPath: 'schemas/order-created.v2.json',
+            },
+          ],
+        },
+      ];
+
+      const eventTypes: MessageTypeMap = new Map([['OrderCreated', 'event']]);
+      await executeGovernanceActions(results, {
+        messageTypes: eventTypes,
+        baseRef: 'main',
+        targetRef: 'working-directory',
+      });
+
+      expect(fetchSpy).toHaveBeenCalledOnce();
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body.specversion).toBe('1.0');
+      expect(body.type).toBe('eventcatalog.governance.schema_changed');
+      expect(body.source).toBe('eventcatalog/governance');
+      expect(body.data.summary).toContain('OrderCreated');
+      expect(body.data.message).toEqual({ id: 'OrderCreated', version: '1.0.0', type: 'event' });
+      expect(body.data.schema).toEqual({
+        beforeHash: 'before-hash',
+        afterHash: 'after-hash',
+        beforePath: 'schemas/order-created.v1.json',
+        afterPath: 'schemas/order-created.v2.json',
+      });
+      expect(body.data.refs).toEqual({ base: 'main', target: 'working-directory' });
+      expect(body.data.consumers).toEqual([{ id: 'PaymentService', version: '1.0.0', owners: ['team-payments'] }]);
+      expect(body.data.producers).toEqual([{ id: 'OrdersService', version: '1.0.0', owners: ['team-orders'] }]);
+    });
+
+    it('sends schema_changed webhook with null schema metadata on the missing side when a schema is newly added', async () => {
+      vi.stubEnv('SCHEMA_WEBHOOK_URL', 'https://schema.example.com/hook');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'schema-change-webhook',
+            when: ['schema_changed' as const],
+            resources: ['*'],
+            actions: [{ type: 'webhook' as const, url: '$SCHEMA_WEBHOOK_URL' }],
+          },
+          trigger: 'schema_changed' as const,
+          matchedChanges: [],
+          schemaChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrderCreated',
+                version: '1.0.0',
+                type: 'event' as const,
+                changeType: 'modified' as const,
+                changedFields: ['schemaHash'],
+              },
+              consumerServices: [],
+              producerServices: [],
+              afterSchemaHash: 'new-hash',
+              afterSchemaPath: 'schema.json',
+            },
+          ],
+        },
+      ];
+
+      const eventTypes: MessageTypeMap = new Map([['OrderCreated', 'event']]);
+      await executeGovernanceActions(results, { messageTypes: eventTypes });
+
+      const body = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+      expect(body.data.schema).toEqual({
+        beforeHash: null,
+        afterHash: 'new-hash',
+        beforePath: null,
+        afterPath: 'schema.json',
+      });
+    });
+
+    it('skips console actions and only executes webhooks', async () => {
+      vi.stubEnv('MIX_URL', 'https://mix.example.com');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+      const results = [
+        {
+          rule: {
+            name: 'mixed-actions',
+            when: ['consumer_added' as const],
+            resources: ['*'],
+            actions: [{ type: 'console' as const }, { type: 'webhook' as const, url: '$MIX_URL' }],
+          },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [
+            {
+              serviceId: 'PaymentService',
+              serviceVersion: '1.0.0',
+              resourceId: 'OrderCreated',
+              resourceVersion: '1.0.0',
+              direction: 'receives' as const,
+              changeType: 'added' as const,
+            },
+          ],
+        },
+      ];
+
+      const output = await executeGovernanceActions(results);
+
+      expect(fetchSpy).toHaveBeenCalledOnce();
+      expect(output).toHaveLength(1);
+      expect(output[0]).toContain('✓');
+    });
+  });
+
+  describe('enrichSchemaContent', () => {
+    const createCatalogWithSchema = (baseDir: string, resourceId: string, version: string, schemaContent: string) => {
+      const resourceDir = path.join(baseDir, 'events', resourceId);
+      fs.mkdirSync(resourceDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(resourceDir, 'index.mdx'),
+        `---\nid: ${resourceId}\nversion: ${version}\nname: ${resourceId}\nschemaPath: schema.json\n---\n`
+      );
+      fs.writeFileSync(path.join(resourceDir, 'schema.json'), schemaContent);
+    };
+
+    it('populates schema content, schema paths, and schema hashes from the base and target catalog directories', async () => {
+      const baseCatalog = path.join(TEMP_DIR, 'base');
+      const targetCatalog = path.join(TEMP_DIR, 'target');
+
+      const beforeSchema = '{"type":"object","properties":{"orderId":{"type":"string"}}}';
+      const afterSchema = '{"type":"object","properties":{"orderId":{"type":"string"},"amount":{"type":"number"}}}';
+
+      createCatalogWithSchema(baseCatalog, 'OrderCreated', '1.0.0', beforeSchema);
+      createCatalogWithSchema(targetCatalog, 'OrderCreated', '1.0.0', afterSchema);
+
+      const results = [
+        {
+          rule: { name: 'test', when: ['schema_changed' as const], resources: ['*'], actions: [] },
+          trigger: 'schema_changed' as const,
+          matchedChanges: [],
+          schemaChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrderCreated',
+                version: '1.0.0',
+                type: 'event' as const,
+                changeType: 'modified' as const,
+                changedFields: ['schemaHash'],
+              },
+              consumerServices: [],
+              producerServices: [],
+            },
+          ],
+        },
+      ];
+
+      await enrichSchemaContent(results, baseCatalog, targetCatalog);
+
+      expect(results[0].schemaChanges![0].before).toBe(beforeSchema);
+      expect(results[0].schemaChanges![0].after).toBe(afterSchema);
+      expect(results[0].schemaChanges![0].beforeSchemaPath).toBe('schema.json');
+      expect(results[0].schemaChanges![0].afterSchemaPath).toBe('schema.json');
+      expect(results[0].schemaChanges![0].beforeSchemaHash).toBe(createHash('sha256').update(beforeSchema).digest('hex'));
+      expect(results[0].schemaChanges![0].afterSchemaHash).toBe(createHash('sha256').update(afterSchema).digest('hex'));
+    });
+
+    it('sets before to undefined when schema does not exist in the base catalog', async () => {
+      const baseCatalog = path.join(TEMP_DIR, 'base');
+      const targetCatalog = path.join(TEMP_DIR, 'target');
+
+      fs.mkdirSync(baseCatalog, { recursive: true });
+      createCatalogWithSchema(targetCatalog, 'OrderCreated', '1.0.0', '{"type":"object"}');
+
+      const results = [
+        {
+          rule: { name: 'test', when: ['schema_changed' as const], resources: ['*'], actions: [] },
+          trigger: 'schema_changed' as const,
+          matchedChanges: [],
+          schemaChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrderCreated',
+                version: '1.0.0',
+                type: 'event' as const,
+                changeType: 'modified' as const,
+                changedFields: ['schemaHash'],
+              },
+              consumerServices: [],
+              producerServices: [],
+            },
+          ],
+        },
+      ];
+
+      await enrichSchemaContent(results, baseCatalog, targetCatalog);
+
+      expect(results[0].schemaChanges![0].before).toBeUndefined();
+      expect(results[0].schemaChanges![0].after).toBe('{"type":"object"}');
+    });
+
+    it('sets after to undefined when schema does not exist in the target catalog', async () => {
+      const baseCatalog = path.join(TEMP_DIR, 'base');
+      const targetCatalog = path.join(TEMP_DIR, 'target');
+
+      createCatalogWithSchema(baseCatalog, 'OrderCreated', '1.0.0', '{"old":"schema"}');
+      fs.mkdirSync(targetCatalog, { recursive: true });
+
+      const results = [
+        {
+          rule: { name: 'test', when: ['schema_changed' as const], resources: ['*'], actions: [] },
+          trigger: 'schema_changed' as const,
+          matchedChanges: [],
+          schemaChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrderCreated',
+                version: '1.0.0',
+                type: 'event' as const,
+                changeType: 'modified' as const,
+                changedFields: ['schemaHash'],
+              },
+              consumerServices: [],
+              producerServices: [],
+            },
+          ],
+        },
+      ];
+
+      await enrichSchemaContent(results, baseCatalog, targetCatalog);
+
+      expect(results[0].schemaChanges![0].before).toBe('{"old":"schema"}');
+      expect(results[0].schemaChanges![0].after).toBeUndefined();
+    });
+
+    it('handles versioned resource directories', async () => {
+      const baseCatalog = path.join(TEMP_DIR, 'base');
+      const targetCatalog = path.join(TEMP_DIR, 'target');
+
+      // Versioned: resource may be in events/OrderCreated/versioned/1.0.0/
+      const versionedDir = path.join(baseCatalog, 'events', 'OrderCreated', 'versioned', '1.0.0');
+      fs.mkdirSync(versionedDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(versionedDir, 'index.mdx'),
+        '---\nid: OrderCreated\nversion: 1.0.0\nname: OrderCreated\nschemaPath: schema.json\n---\n'
+      );
+      fs.writeFileSync(path.join(versionedDir, 'schema.json'), '{"versioned":"base"}');
+
+      createCatalogWithSchema(targetCatalog, 'OrderCreated', '1.0.0', '{"versioned":"target"}');
+
+      const results = [
+        {
+          rule: { name: 'test', when: ['schema_changed' as const], resources: ['*'], actions: [] },
+          trigger: 'schema_changed' as const,
+          matchedChanges: [],
+          schemaChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrderCreated',
+                version: '1.0.0',
+                type: 'event' as const,
+                changeType: 'modified' as const,
+                changedFields: ['schemaHash'],
+              },
+              consumerServices: [],
+              producerServices: [],
+            },
+          ],
+        },
+      ];
+
+      await enrichSchemaContent(results, baseCatalog, targetCatalog);
+
+      expect(results[0].schemaChanges![0].before).toBe('{"versioned":"base"}');
+      expect(results[0].schemaChanges![0].after).toBe('{"versioned":"target"}');
+    });
+
+    it('uses previousVersion for base and newVersion for target on versioned schema changes', async () => {
+      const baseCatalog = path.join(TEMP_DIR, 'base');
+      const targetCatalog = path.join(TEMP_DIR, 'target');
+
+      createCatalogWithSchema(baseCatalog, 'OrderCreated', '1.0.0', '{"version":"1.0.0"}');
+      createCatalogWithSchema(targetCatalog, 'OrderCreated', '2.0.0', '{"version":"2.0.0"}');
+
+      const results = [
+        {
+          rule: { name: 'test', when: ['schema_changed' as const], resources: ['*'], actions: [] },
+          trigger: 'schema_changed' as const,
+          matchedChanges: [],
+          schemaChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrderCreated',
+                version: '2.0.0',
+                type: 'event' as const,
+                changeType: 'versioned' as const,
+                previousVersion: '1.0.0',
+                newVersion: '2.0.0',
+                changedFields: ['schemaHash'],
+              },
+              consumerServices: [],
+              producerServices: [],
+            },
+          ],
+        },
+      ];
+
+      await enrichSchemaContent(results, baseCatalog, targetCatalog);
+
+      expect(results[0].schemaChanges![0].before).toBe('{"version":"1.0.0"}');
+      expect(results[0].schemaChanges![0].after).toBe('{"version":"2.0.0"}');
+    });
+
+    it('skips results that have no schemaChanges', async () => {
+      const baseCatalog = path.join(TEMP_DIR, 'base');
+      const targetCatalog = path.join(TEMP_DIR, 'target');
+      fs.mkdirSync(baseCatalog, { recursive: true });
+      fs.mkdirSync(targetCatalog, { recursive: true });
+
+      const results = [
+        {
+          rule: { name: 'test', when: ['consumer_added' as const], resources: ['*'], actions: [] },
+          trigger: 'consumer_added' as const,
+          matchedChanges: [],
+        },
+      ];
+
+      // Should not throw
+      await enrichSchemaContent(results, baseCatalog, targetCatalog);
+      expect(results[0]).not.toHaveProperty('schemaChanges');
+    });
+  });
+
+  describe('fail action', () => {
+    describe('loadGovernanceConfig', () => {
+      it('when governance.yaml contains a rule with a fail action and a message, the action is parsed with type "fail" and the message string', () => {
+        const configYaml = `rules:
+  - name: block-schema-changes
+    when:
+      - schema_changed
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: fail
+        message: "Schema changes require review"
+`;
+        fs.writeFileSync(path.join(TEMP_DIR, 'governance.yaml'), configYaml);
+        const config = loadGovernanceConfig(TEMP_DIR);
+
+        expect(config.rules).toHaveLength(1);
+        expect(config.rules[0].actions).toHaveLength(2);
+        expect(config.rules[0].actions[1]).toEqual({ type: 'fail', message: 'Schema changes require review' });
+      });
+
+      it('when governance.yaml contains a fail action without a message field, the action is parsed with type "fail" and no message', () => {
+        const configYaml = `rules:
+  - name: block-schema-changes
+    when:
+      - schema_changed
+    resources:
+      - "*"
+    actions:
+      - type: fail
+`;
+        fs.writeFileSync(path.join(TEMP_DIR, 'governance.yaml'), configYaml);
+        const config = loadGovernanceConfig(TEMP_DIR);
+
+        expect(config.rules[0].actions[0]).toEqual({ type: 'fail' });
+      });
+
+      it('when governance.yaml contains a rule with multiple fail actions, all fail actions are parsed and preserved in order', () => {
+        const configYaml = `rules:
+  - name: multi-fail
+    when:
+      - schema_changed
+    resources:
+      - "*"
+    actions:
+      - type: fail
+        message: "First failure reason"
+      - type: fail
+        message: "Second failure reason"
+`;
+        fs.writeFileSync(path.join(TEMP_DIR, 'governance.yaml'), configYaml);
+        const config = loadGovernanceConfig(TEMP_DIR);
+
+        expect(config.rules[0].actions).toHaveLength(2);
+        expect(config.rules[0].actions[0]).toEqual({ type: 'fail', message: 'First failure reason' });
+        expect(config.rules[0].actions[1]).toEqual({ type: 'fail', message: 'Second failure reason' });
+      });
+    });
+
+    describe('formatFailureOutput', () => {
+      it('when the failures array is empty, the failure output is an empty string', () => {
+        expect(formatFailureOutput([])).toBe('');
+      });
+
+      it('when a failure has a message, the output shows "FAILED: <rule-name>" followed by the message', () => {
+        const output = formatFailureOutput([{ ruleName: 'schema-guard', messages: ['Schema changes require review'] }]);
+        expect(output).toContain('FAILED: schema-guard');
+        expect(output).toContain('Schema changes require review');
+      });
+
+      it('when a failure has no messages, the output shows "FAILED: <rule-name>" with no message line', () => {
+        const output = formatFailureOutput([{ ruleName: 'schema-guard', messages: [] }]);
+        expect(output).toContain('FAILED: schema-guard');
+      });
+
+      it('when multiple failures exist, each is listed in the output', () => {
+        const output = formatFailureOutput([
+          { ruleName: 'schema-guard', messages: ['Review required'] },
+          { ruleName: 'removal-guard', messages: ['Breaking change'] },
+        ]);
+        expect(output).toContain('FAILED: schema-guard');
+        expect(output).toContain('Review required');
+        expect(output).toContain('FAILED: removal-guard');
+        expect(output).toContain('Breaking change');
+      });
+
+      it('when a single failure has multiple messages, all messages are shown under the rule name', () => {
+        const output = formatFailureOutput([{ ruleName: 'multi-fail', messages: ['First reason', 'Second reason'] }]);
+        expect(output).toContain('FAILED: multi-fail');
+        expect(output).toContain('First reason');
+        expect(output).toContain('Second reason');
+      });
+    });
+
+    describe('executeGovernanceActions with fail action', () => {
+      it('when a rule has console, fail, and webhook actions, only the webhook is sent and the fail action does not trigger an HTTP request', async () => {
+        vi.stubEnv('FAIL_TEST_URL', 'https://fail-test.example.com');
+
+        const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok'));
+
+        const results: GovernanceResult[] = [
+          {
+            rule: {
+              name: 'mixed-with-fail',
+              when: ['consumer_added' as const],
+              resources: ['*'],
+              actions: [
+                { type: 'console' as const },
+                { type: 'fail' as const, message: 'Block the build' },
+                { type: 'webhook' as const, url: '$FAIL_TEST_URL' },
+              ],
+            },
+            trigger: 'consumer_added' as const,
+            matchedChanges: [
+              {
+                serviceId: 'PaymentService',
+                serviceVersion: '1.0.0',
+                resourceId: 'OrderCreated',
+                resourceVersion: '1.0.0',
+                direction: 'receives' as const,
+                changeType: 'added' as const,
+              },
+            ],
+          },
+        ];
+
+        const output = await executeGovernanceActions(results);
+
+        // Only the webhook should fire, not the fail action
+        expect(fetchSpy).toHaveBeenCalledOnce();
+        expect(output).toHaveLength(1);
+        expect(output[0]).toContain('✓');
+      });
+    });
+
+    describe('fail action message supports env var interpolation', () => {
+      it('when a fail action message contains $ENV_VAR references, the variables are resolved to their values in the formatted output', () => {
+        vi.stubEnv('TEAM_LEAD', 'Alice');
+
+        const output = formatFailureOutput([
+          { ruleName: 'env-fail', messages: [resolveEnvVars('Contact $TEAM_LEAD for approval')] },
+        ]);
+        expect(output).toContain('Contact Alice for approval');
+      });
+    });
+  });
+
+  describe('loadGovernanceConfig - compatibility', () => {
+    it('parses compatibility.strategy from governance.yaml', () => {
+      const yamlContent = `
+compatibility:
+  strategy: BACKWARD
+rules:
+  - name: breaking-change-rule
+    when: [schema_breaking_change]
+    resources: ['*']
+    actions:
+      - type: webhook
+        url: https://example.com/hook
+`;
+      fs.writeFileSync(path.join(TEMP_DIR, 'governance.yaml'), yamlContent);
+      const config = loadGovernanceConfig(TEMP_DIR);
+      expect(config.compatibility).toEqual({ strategy: 'BACKWARD' });
+      expect(config.rules).toHaveLength(1);
+    });
+
+    it('defaults compatibility to undefined when not specified', () => {
+      const yamlContent = `
+rules:
+  - name: some-rule
+    when: [consumer_added]
+    resources: ['*']
+    actions:
+      - type: console
+`;
+      fs.writeFileSync(path.join(TEMP_DIR, 'governance.yaml'), yamlContent);
+      const config = loadGovernanceConfig(TEMP_DIR);
+      expect(config.compatibility).toBeUndefined();
+    });
+
+    it('throws on invalid compatibility strategy', () => {
+      const yamlContent = `
+compatibility:
+  strategy: BACKWARDS
+rules: []
+`;
+      fs.writeFileSync(path.join(TEMP_DIR, 'governance.yaml'), yamlContent);
+      expect(() => loadGovernanceConfig(TEMP_DIR)).toThrow(
+        'Invalid compatibility strategy "BACKWARDS". Must be one of: BACKWARD, FORWARD, FULL, NONE.'
+      );
+    });
+  });
+
+  describe('executeGovernanceActions - schema_breaking_change webhook', () => {
+    it('sends correct CloudEvents payload for schema_breaking_change', async () => {
+      const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('ok', { status: 200 }));
+
+      const results: GovernanceResult[] = [
+        {
+          rule: {
+            name: 'breaking-rule',
+            when: ['schema_breaking_change'],
+            resources: ['*'],
+            actions: [{ type: 'webhook', url: 'https://example.com/hook' }],
+          },
+          trigger: 'schema_breaking_change',
+          matchedChanges: [],
+          breakingSchemaChanges: [
+            {
+              resourceChange: {
+                resourceId: 'OrderCreated',
+                version: '1.0.0',
+                type: 'event',
+                changeType: 'modified',
+                changedFields: ['schemaHash'],
+              },
+              consumerServices: [{ id: 'PaymentService', version: '1.0.0', owners: ['team-payments'] }],
+              producerServices: [{ id: 'OrdersService', version: '1.0.0' }],
+              beforeSchemaHash: 'abc123',
+              afterSchemaHash: 'def456',
+              beforeSchemaPath: 'schema.json',
+              afterSchemaPath: 'schema.json',
+              breakingChanges: [
+                {
+                  type: 'TYPE_CHANGED',
+                  field: 'amount',
+                  message: "Field 'amount' type changed from 'string' to 'number'",
+                  previousType: 'string',
+                  currentType: 'number',
+                  breaking: true as const,
+                },
+              ],
+            },
+          ],
+        },
+      ];
+
+      const messageTypes: MessageTypeMap = new Map([['OrderCreated', 'event']]);
+
+      await executeGovernanceActions(results, {
+        messageTypes,
+        baseRef: 'main',
+        targetRef: 'feature-branch',
+        compatibilityStrategy: 'BACKWARD',
+      });
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      const [, options] = fetchSpy.mock.calls[0];
+      const body = JSON.parse(options.body as string);
+      expect(body.type).toBe('eventcatalog.governance.schema_breaking_change');
+      expect(body.specversion).toBe('1.0');
+      expect(body.data.compatibilityStrategy).toBe('BACKWARD');
+      expect(body.data.message.id).toBe('OrderCreated');
+      expect(body.data.breakingChanges).toHaveLength(1);
+      expect(body.data.breakingChanges[0].type).toBe('TYPE_CHANGED');
+      expect(body.data.breakingChanges[0].field).toBe('amount');
+      expect(body.data.consumers).toHaveLength(1);
+      expect(body.data.producers).toHaveLength(1);
+      expect(body.data.schema.beforeHash).toBe('abc123');
+      expect(body.data.schema.afterHash).toBe('def456');
+
+      fetchSpy.mockRestore();
+    });
+  });
+});
diff --git a/packages/cli/src/test/import-export/channels.test.ts b/packages/cli/src/test/import-export/channels.test.ts
new file mode 100644
index 000000000..81b514d0f
--- /dev/null
+++ b/packages/cli/src/test/import-export/channels.test.ts
@@ -0,0 +1,290 @@
+import { describe, it, expect } from 'vitest';
+import { importDSL } from '../../cli/import';
+import createSDK from '@eventcatalog/sdk';
+import { createCatalogHelper } from './helpers';
+
+const { catalogPath, setup, writeEcFile } = createCatalogHelper('channels');
+setup();
+
+describe('import channels', () => {
+  it('imports a standalone channel', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `channel OrderTopic {
+  version 1.0.0
+  name "Order Topic"
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    expect(result).toContain('Created 1 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    const channel = await sdk.getChannel('OrderTopic', '1.0.0');
+    expect(channel).toBeDefined();
+    expect(channel!.name).toBe('Order Topic');
+  });
+
+  it('produces sends with to channels in service frontmatter', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `channel OrderTopic {
+  version 1.0.0
+  name "Order Topic"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0 to OrderTopic
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    expect(result).toContain('Created 3 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    const service = await sdk.getService('OrderService', '1.0.0');
+    expect(service).toBeDefined();
+    expect(service!.sends).toBeDefined();
+    expect(service!.sends).toHaveLength(1);
+    expect(service!.sends![0].id).toBe('OrderCreated');
+    expect((service!.sends![0] as any).to).toBeDefined();
+    expect((service!.sends![0] as any).to).toHaveLength(1);
+    expect((service!.sends![0] as any).to[0].id).toBe('OrderTopic');
+  });
+
+  it('produces receives with from channels in service frontmatter', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `channel OrderChannel {
+  version 1.0.0
+  name "Order Channel"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  receives command CreateOrder@1.0.0 from OrderChannel
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    expect(result).toContain('Created 3 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    const service = await sdk.getService('OrderService', '1.0.0');
+    expect(service).toBeDefined();
+    expect(service!.receives).toBeDefined();
+    expect(service!.receives).toHaveLength(1);
+    expect(service!.receives![0].id).toBe('CreateOrder');
+    expect((service!.receives![0] as any).from).toBeDefined();
+    expect((service!.receives![0] as any).from).toHaveLength(1);
+    expect((service!.receives![0] as any).from[0].id).toBe('OrderChannel');
+  });
+
+  it('includes delivery_mode in channel refs', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `channel OrderTopic {
+  version 1.0.0
+  name "Order Topic"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0 to OrderTopic delivery push
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    const service = await sdk.getService('OrderService', '1.0.0');
+    const sendRef = service!.sends![0] as any;
+    expect(sendRef.to[0].delivery_mode).toBe('push');
+  });
+
+  it('includes channel version in channel refs', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `channel OrderTopic {
+  version 2.0.0
+  name "Order Topic"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0 to OrderTopic@2.0.0
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    const service = await sdk.getService('OrderService', '1.0.0');
+    const sendRef = service!.sends![0] as any;
+    expect(sendRef.to[0].version).toBe('2.0.0');
+  });
+
+  it('creates a versioned channel stub when a different channel version is referenced', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `channel OrderTopic {
+  version 1.0.0
+  name "Order Topic"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0 to OrderTopic@2.0.0
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+    expect(result).toContain('Created 4 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getChannel('OrderTopic', '1.0.0')).toBeDefined();
+    expect(await sdk.getChannel('OrderTopic', '2.0.0')).toBeDefined();
+    expect(await sdk.getChannel('OrderTopic', '0.0.1')).toBeUndefined();
+  });
+
+  it('creates channel stubs for referenced channels without standalone definitions', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated to OrderTopic
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+
+    // Should create service + event stub + channel stub
+    const channel = await sdk.getChannel('OrderTopic', '0.0.1');
+    expect(channel).toBeDefined();
+    expect(channel!.name).toBe('OrderTopic');
+    expect(channel!.version).toBe('0.0.1');
+  });
+
+  it('does not create channel stubs for channels already defined in the DSL', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `channel OrderTopic {
+  version 1.0.0
+  name "Order Topic"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated to OrderTopic
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+
+    // Channel defined in DSL should exist at 1.0.0
+    const channel = await sdk.getChannel('OrderTopic', '1.0.0');
+    expect(channel).toBeDefined();
+
+    // Should NOT have a 0.0.1 stub
+    const stub = await sdk.getChannel('OrderTopic', '0.0.1');
+    expect(stub).toBeUndefined();
+  });
+
+  it('does not create duplicate channel stubs when multiple sends reference same channel', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated to SharedTopic
+  sends event OrderUpdated to SharedTopic
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    const channel = await sdk.getChannel('SharedTopic', '0.0.1');
+    expect(channel).toBeDefined();
+
+    // Count channel resources in result — should only be 1
+    const channelMatches = result.match(/SharedTopic@/g);
+    expect(channelMatches).toHaveLength(1);
+  });
+
+  it('imports a channel with template parameters in the name', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `channel inventory.{env}.events {
+  version 1.0.0
+  name "Inventory Events Channel"
+  address "inventory.{env}.events"
+  protocol "kafka"
+  summary "Central event stream for inventory events"
+}
+
+service InventoryService {
+  version 1.0.0
+  name "Inventory Service"
+  sends event InventoryAdjusted to inventory.{env}.events
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    expect(result).toContain('Created');
+
+    const sdk = createSDK(catalogPath);
+    const channel = await sdk.getChannel('inventory.{env}.events', '1.0.0');
+    expect(channel).toBeDefined();
+    expect(channel!.name).toBe('Inventory Events Channel');
+    expect(channel!.address).toBe('inventory.{env}.events');
+
+    const service = await sdk.getService('InventoryService', '1.0.0');
+    expect(service).toBeDefined();
+    expect(service!.sends).toBeDefined();
+    expect(service!.sends).toHaveLength(1);
+    expect((service!.sends![0] as any).to).toBeDefined();
+    expect((service!.sends![0] as any).to[0].id).toBe('inventory.{env}.events');
+  });
+});
diff --git a/packages/cli/src/test/import-export/container-refs.test.ts b/packages/cli/src/test/import-export/container-refs.test.ts
new file mode 100644
index 000000000..a25ee2aab
--- /dev/null
+++ b/packages/cli/src/test/import-export/container-refs.test.ts
@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest';
+import { importDSL } from '../../cli/import';
+import createSDK from '@eventcatalog/sdk';
+import { createCatalogHelper } from './helpers';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const { catalogPath, setup, writeEcFile } = createCatalogHelper('container-refs');
+setup();
+
+function existsInCatalog(...segments: string[]): boolean {
+  return fs.existsSync(path.join(catalogPath, ...segments));
+}
+
+describe('import container refs', () => {
+  it('imports writes-to and reads-from refs on services', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `container OrdersDb {
+  version 1.0.0
+  name "Orders DB"
+  container-type database
+}
+
+container OrdersCache {
+  version 1.0.0
+  name "Orders Cache"
+  container-type cache
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  writes-to container OrdersDb@1.0.0
+  reads-from container OrdersCache
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+    expect(result).toContain('Created 3 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    const service: any = await sdk.getService('OrderService', '1.0.0');
+    expect(service).toBeDefined();
+    expect(service.writesTo).toEqual([{ id: 'OrdersDb', version: '1.0.0' }]);
+    expect(service.readsFrom).toEqual([{ id: 'OrdersCache' }]);
+  });
+
+  it('creates container stubs for writes-to/reads-from refs without standalone definitions', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service AnalyticsService {
+  version 1.0.0
+  writes-to container AnalyticsStore
+  reads-from container ReportsStore@2.0.0
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+    expect(result).toContain('Created 3 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getDataStore('AnalyticsStore', '0.0.1')).toBeDefined();
+    expect(await sdk.getDataStore('ReportsStore', '2.0.0')).toBeDefined();
+
+    const service: any = await sdk.getService('AnalyticsService', '1.0.0');
+    expect(service.writesTo).toEqual([{ id: 'AnalyticsStore' }]);
+    expect(service.readsFrom).toEqual([{ id: 'ReportsStore', version: '2.0.0' }]);
+  });
+
+  it('defaults container_type to database for container stubs', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service InventoryService {
+  version 1.0.0
+  writes-to container InventoryDb
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    const container: any = await sdk.getDataStore('InventoryDb', '0.0.1');
+    expect(container).toBeDefined();
+    expect(container.container_type).toBe('database');
+  });
+
+  it('nests container stubs under the domain by default', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `domain Payments {
+  version 1.0.0
+  service SettlementService {
+    version 1.0.0
+    writes-to container LedgerDb
+  }
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getDataStore('LedgerDb', '0.0.1')).toBeDefined();
+    expect(existsInCatalog('domains', 'Payments', 'containers', 'LedgerDb')).toBe(true);
+  });
+});
diff --git a/packages/cli/src/test/import-export/domains.test.ts b/packages/cli/src/test/import-export/domains.test.ts
new file mode 100644
index 000000000..c634b2471
--- /dev/null
+++ b/packages/cli/src/test/import-export/domains.test.ts
@@ -0,0 +1,698 @@
+import { describe, it, expect } from 'vitest';
+import { importDSL } from '../../cli/import';
+import { exportResource } from '../../cli/export';
+import createSDK from '@eventcatalog/sdk';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createCatalogHelper } from './helpers';
+
+const { catalogPath, setup, writeEcFile } = createCatalogHelper('domains');
+setup();
+
+describe('domains import-export rules', () => {
+  describe('import (.ec to eventcatalog)', () => {
+    it('when we import a domain that does not exist in the catalog, a domain resource is created from the DSL', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  summary "Order management"
+}`
+      );
+
+      const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+      expect(result).toContain('Created 1 resource(s)');
+
+      const sdk = createSDK(catalogPath);
+      const domain = await sdk.getDomain('Orders', '1.0.0');
+      expect(domain).toBeDefined();
+      expect(domain!.name).toBe('Orders Domain');
+    });
+
+    it('when no domain exists, a domain resource is created with NodeGraph data in markdown', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const sdk = createSDK(catalogPath);
+      const domain = await sdk.getDomain('Orders', '1.0.0');
+      expect(domain).toBeDefined();
+      expect(domain!.markdown).toContain('<NodeGraph />');
+    });
+
+    it('when we import a domain with a subdomain, the parent domain contains a subdomain pointer and the subdomain resource is created', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `domain Ecommerce {
+  version 1.0.0
+  name "Ecommerce Domain"
+  subdomain Payments {
+    version 1.0.0
+    name "Payments Subdomain"
+    summary "Payments context"
+  }
+}`
+      );
+
+      const result = await importDSL({ files: [ecFile], dir: catalogPath });
+      expect(result).toContain('Created 2 resource(s)');
+
+      const sdk = createSDK(catalogPath);
+      const domain = await sdk.getDomain('Ecommerce', '1.0.0');
+      expect(domain).toBeDefined();
+      expect(domain!.domains).toEqual([{ id: 'Payments', version: '1.0.0' }]);
+
+      const subdomain = await sdk.getDomain('Payments', '1.0.0');
+      expect(subdomain).toBeDefined();
+      expect(subdomain!.name).toBe('Payments Subdomain');
+      expect(subdomain!.summary).toBe('Payments context');
+    });
+
+    it('when we import a domain with duplicate service and subdomain references, domain pointers are deduplicated in frontmatter', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `domain Ecommerce {
+  version 1.0.0
+  name "Ecommerce Domain"
+
+  service OrderService {
+    version 1.0.0
+    name "Order Service"
+  }
+
+  service OrderService {
+    version 1.0.0
+    name "Order Service"
+  }
+
+  subdomain Payments {
+    version 1.0.0
+    name "Payments Subdomain"
+  }
+
+  subdomain Payments {
+    version 1.0.0
+    name "Payments Subdomain"
+  }
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const sdk = createSDK(catalogPath);
+      const domain = await sdk.getDomain('Ecommerce', '1.0.0');
+      expect(domain).toBeDefined();
+      expect(domain!.services).toEqual([{ id: 'OrderService', version: '1.0.0' }]);
+      expect(domain!.domains).toEqual([{ id: 'Payments', version: '1.0.0' }]);
+    });
+
+    it('when importing the same domain version from multiple .ec files, the final result is deterministic and the last file wins', async () => {
+      const firstFile = writeEcFile(
+        'first.ec',
+        `domain Orders {
+  version 1.0.0
+  name "Orders Domain First"
+  summary "first summary"
+}`
+      );
+      const secondFile = writeEcFile(
+        'second.ec',
+        `domain Orders {
+  version 1.0.0
+  name "Orders Domain Second"
+}`
+      );
+
+      await importDSL({ files: [firstFile, secondFile], dir: catalogPath });
+
+      const sdk = createSDK(catalogPath);
+      const domain = await sdk.getDomain('Orders', '1.0.0');
+      expect(domain).toBeDefined();
+      expect(domain!.name).toBe('Orders Domain Second');
+      expect((domain as any).summary).toBeUndefined();
+      expect(domain!.markdown).toContain('<NodeGraph />');
+    });
+
+    it('when importing in --flat mode, domain and subdomain output paths are flat and domain pointers remain correct', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `domain Ecommerce {
+  version 1.0.0
+  name "Ecommerce Domain"
+  subdomain Payments {
+    version 1.0.0
+    name "Payments Subdomain"
+  }
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath, flat: true });
+
+      const sdk = createSDK(catalogPath);
+      const domain = await sdk.getDomain('Ecommerce', '1.0.0');
+      expect(domain).toBeDefined();
+      expect(domain!.domains).toEqual([{ id: 'Payments', version: '1.0.0' }]);
+      expect(await sdk.getDomain('Payments', '1.0.0')).toBeDefined();
+
+      expect(fs.existsSync(path.join(catalogPath, 'domains', 'Ecommerce', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(catalogPath, 'domains', 'Payments', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(catalogPath, 'domains', 'Ecommerce', 'subdomains', 'Payments'))).toBe(false);
+      expect(fs.existsSync(path.join(catalogPath, 'domains', 'Ecommerce', 'domains', 'Payments'))).toBe(false);
+    });
+
+    it('when importing in --flat mode, services from domains are written to top-level paths and domain service pointers remain correct', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `domain Ecommerce {
+  version 1.0.0
+  name "Ecommerce Domain"
+  service OrderService {
+    version 1.0.0
+    name "Order Service"
+  }
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath, flat: true });
+
+      const sdk = createSDK(catalogPath);
+      const domain = await sdk.getDomain('Ecommerce', '1.0.0');
+      const service = await sdk.getService('OrderService', '1.0.0');
+      expect(domain).toBeDefined();
+      expect(service).toBeDefined();
+      expect(domain!.services).toEqual([{ id: 'OrderService', version: '1.0.0' }]);
+
+      expect(fs.existsSync(path.join(catalogPath, 'services', 'OrderService', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(catalogPath, 'domains', 'Ecommerce', 'services', 'OrderService'))).toBe(false);
+    });
+
+    it('when importing in --flat mode, messages from domain services are written to top-level paths and service message pointers remain correct', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `domain Ecommerce {
+  version 1.0.0
+  name "Ecommerce Domain"
+  service OrderService {
+    version 1.0.0
+    name "Order Service"
+    sends event OrderCreated {
+      version 1.0.0
+      name "Order Created"
+    }
+    receives command CancelOrder {
+      version 1.0.0
+      name "Cancel Order"
+    }
+  }
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath, flat: true });
+
+      const sdk = createSDK(catalogPath);
+      const service = await sdk.getService('OrderService', '1.0.0');
+      expect(service).toBeDefined();
+      expect(service!.sends).toEqual([{ id: 'OrderCreated', version: '1.0.0' }]);
+      expect(service!.receives).toEqual([{ id: 'CancelOrder', version: '1.0.0' }]);
+      expect(await sdk.getEvent('OrderCreated', '1.0.0')).toBeDefined();
+      expect(await sdk.getCommand('CancelOrder', '1.0.0')).toBeDefined();
+
+      expect(fs.existsSync(path.join(catalogPath, 'events', 'OrderCreated', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(catalogPath, 'commands', 'CancelOrder', 'index.mdx'))).toBe(true);
+      expect(
+        fs.existsSync(path.join(catalogPath, 'domains', 'Ecommerce', 'services', 'OrderService', 'events', 'OrderCreated'))
+      ).toBe(false);
+      expect(
+        fs.existsSync(path.join(catalogPath, 'domains', 'Ecommerce', 'services', 'OrderService', 'commands', 'CancelOrder'))
+      ).toBe(false);
+    });
+
+    it('when we import a domain with draft true and deprecated true, both flags are written to domain frontmatter', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  draft true
+  deprecated true
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const sdk = createSDK(catalogPath);
+      const domain = await sdk.getDomain('Orders', '1.0.0');
+      expect(domain).toBeDefined();
+      expect((domain as any).draft).toBe(true);
+      expect((domain as any).deprecated).toBe(true);
+    });
+
+    it('when we import a domain with draft false and deprecated false over existing true values, existing values are overridden and set to false', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeDomain({
+        id: 'Orders',
+        version: '1.0.0',
+        name: 'Orders Domain',
+        draft: true,
+        deprecated: true,
+        markdown: 'Existing docs',
+      } as any);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `domain Orders {
+  version 1.0.0
+  name "Orders Domain Updated"
+  draft false
+  deprecated false
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const domain = await sdk.getDomain('Orders', '1.0.0');
+      expect(domain).toBeDefined();
+      expect(domain!.name).toBe('Orders Domain Updated');
+      expect((domain as any).draft).toBe(false);
+      expect((domain as any).deprecated).toBe(false);
+      expect(domain!.markdown).toBe('Existing docs');
+    });
+
+    it('when we import a domain with owner statements over existing owners, owners are overwritten from DSL', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeDomain({
+        id: 'Orders',
+        version: '1.0.0',
+        name: 'Orders Domain',
+        owners: ['legacy-owner'],
+        markdown: 'Existing docs',
+      } as any);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `domain Orders {
+  version 1.0.0
+  name "Orders Domain Updated"
+  owner orders-team
+  owner platform-team
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const domain = await sdk.getDomain('Orders', '1.0.0');
+      expect(domain).toBeDefined();
+      expect(domain!.name).toBe('Orders Domain Updated');
+      expect((domain as any).owners).toEqual(['orders-team', 'platform-team']);
+      expect(domain!.markdown).toBe('Existing docs');
+    });
+
+    it('when we import a domain without owner statements over existing owners, owners are removed from frontmatter', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeDomain({
+        id: 'Orders',
+        version: '1.0.0',
+        name: 'Orders Domain',
+        owners: ['legacy-owner'],
+        markdown: 'Existing docs',
+      } as any);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `domain Orders {
+  version 1.0.0
+  name "Orders Domain Updated"
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const domain = await sdk.getDomain('Orders', '1.0.0');
+      expect(domain).toBeDefined();
+      expect(domain!.name).toBe('Orders Domain Updated');
+      expect((domain as any).owners).toBeUndefined();
+      expect(domain!.markdown).toBe('Existing docs');
+    });
+
+    const managedDomainKeyCases: Array<{
+      key: 'name' | 'version' | 'owners' | 'deprecated' | 'draft' | 'summary' | 'services' | 'domains';
+      existingValue: any;
+      importSource: string;
+      expectedValue: any;
+      readVersion?: string;
+    }> = [
+      {
+        key: 'name',
+        existingValue: 'Legacy Orders Domain Name',
+        importSource: `domain Orders {
+  version 1.0.0
+}`,
+        expectedValue: 'Orders',
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'version',
+        existingValue: '1.0.0',
+        importSource: `domain Orders {
+  name "Orders Domain Updated"
+}`,
+        expectedValue: undefined,
+      },
+      {
+        key: 'owners',
+        existingValue: ['orders-team'],
+        importSource: `domain Orders {
+  version 1.0.0
+  name "Orders Domain Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'deprecated',
+        existingValue: true,
+        importSource: `domain Orders {
+  version 1.0.0
+  name "Orders Domain Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'draft',
+        existingValue: true,
+        importSource: `domain Orders {
+  version 1.0.0
+  name "Orders Domain Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'summary',
+        existingValue: 'Legacy orders summary',
+        importSource: `domain Orders {
+  version 1.0.0
+  name "Orders Domain Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'services',
+        existingValue: [{ id: 'OrderService', version: '1.0.0' }],
+        importSource: `domain Orders {
+  version 1.0.0
+  name "Orders Domain Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'domains',
+        existingValue: [{ id: 'Payments', version: '1.0.0' }],
+        importSource: `domain Orders {
+  version 1.0.0
+  name "Orders Domain Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+    ];
+
+    it.each(managedDomainKeyCases)(
+      'when importing over an existing domain and the DSL does not provide managed key "$key", that managed key is not preserved from existing frontmatter',
+      async ({ key, existingValue, importSource, expectedValue, readVersion }) => {
+        const sdk = createSDK(catalogPath);
+        const domainToWrite: Record<string, any> = {
+          id: 'Orders',
+          version: '1.0.0',
+          name: 'Orders Domain',
+          markdown: 'Existing docs',
+          customField: 'preserve-me',
+        };
+        domainToWrite[key] = existingValue;
+        await sdk.writeDomain(domainToWrite as any);
+
+        const ecFile = writeEcFile('test.ec', importSource);
+        await importDSL({ files: [ecFile], dir: catalogPath });
+
+        const domain = await sdk.getDomain('Orders', readVersion);
+        expect(domain).toBeDefined();
+        expect(domain!.id).toBe('Orders');
+        if (expectedValue === undefined) {
+          expect((domain as any)[key]).toBeUndefined();
+        } else {
+          expect((domain as any)[key]).toEqual(expectedValue);
+        }
+        expect(domain!.markdown).toBe('Existing docs');
+        expect((domain as any).customField).toBe('preserve-me');
+      }
+    );
+
+    it('when importing a newer domain version, non-DSL keys are carried forward from the latest version', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeDomain({
+        id: 'Billing',
+        version: '1.0.0',
+        name: 'Billing Domain',
+        summary: 'Billing summary',
+        markdown: 'Billing docs v1',
+        customField: 'carry-forward',
+      } as any);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `domain Billing {
+  version 2.0.0
+  name "Billing Domain v2"
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const domain = await sdk.getDomain('Billing', '2.0.0');
+      expect(domain).toBeDefined();
+      expect(domain!.name).toBe('Billing Domain v2');
+      expect((domain as any).summary).toBeUndefined();
+      expect(domain!.markdown).toBe('Billing docs v1\n\n<NodeGraph />');
+      expect((domain as any).customField).toBe('carry-forward');
+    });
+  });
+
+  describe('export (from eventcatalog to .ec)', () => {
+    it('when we export an existing domain to stdout, the DSL output contains the domain definition and visualizer entry', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        summary: 'Order management',
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: 'domain',
+        id: 'Orders',
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        domain Orders {
+          version 1.0.0
+          name "Orders Domain"
+          summary "Order management"
+        }
+
+        visualizer main {
+          name "View of Orders"
+          domain Orders
+        }
+      `);
+    });
+
+    it('when we export a domain with hydrate enabled, referenced service resources are included in the DSL output', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        services: [{ id: 'OrderService', version: '1.0.0' }],
+        markdown: '',
+      } as any);
+
+      const result = await exportResource({
+        resource: 'domain',
+        id: 'Orders',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        // SERVICES
+        service OrderService {
+          version 1.0.0
+          name "Order Service"
+        }
+
+        // DOMAINS
+        domain Orders {
+          version 1.0.0
+          name "Orders Domain"
+          service OrderService@1.0.0
+        }
+
+        visualizer main {
+          name "View of Orders"
+          service OrderService
+          domain Orders
+        }
+      `);
+    });
+
+    it('when we export a domain with hydrate enabled and a referenced service publishes and subscribes to messages, the service and message resources are included in the DSL output', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeEvent({
+        id: 'OrderCancelled',
+        name: 'Order Cancelled',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        receives: [{ id: 'OrderCancelled', version: '1.0.0' }],
+        markdown: '',
+      });
+      await sdk.writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        services: [{ id: 'OrderService', version: '1.0.0' }],
+        markdown: '',
+      } as any);
+
+      const result = await exportResource({
+        resource: 'domain',
+        id: 'Orders',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        // EVENTS
+        event OrderCreated {
+          version 1.0.0
+          name "Order Created"
+        }
+
+        event OrderCancelled {
+          version 1.0.0
+          name "Order Cancelled"
+        }
+
+        // SERVICES
+        service OrderService {
+          version 1.0.0
+          name "Order Service"
+          sends event OrderCreated@1.0.0
+          receives event OrderCancelled@1.0.0
+        }
+
+        // DOMAINS
+        domain Orders {
+          version 1.0.0
+          name "Orders Domain"
+          service OrderService@1.0.0
+        }
+
+        visualizer main {
+          name "View of Orders"
+          event OrderCreated
+          event OrderCancelled
+          service OrderService
+          domain Orders
+        }
+      `);
+    });
+
+    it('when we export a domain with hydrate enabled and domain owners are defined, owner resources are included in the DSL output', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeTeam({
+        id: 'orders-team',
+        name: 'Orders Team',
+        markdown: '',
+      } as any);
+      await sdk.writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        owners: ['orders-team'],
+        markdown: '',
+      } as any);
+
+      const result = await exportResource({
+        resource: 'domain',
+        id: 'Orders',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        // TEAMS
+        team orders-team {
+          name "Orders Team"
+        }
+
+        // DOMAINS
+        domain Orders {
+          version 1.0.0
+          name "Orders Domain"
+          owner orders-team
+        }
+
+        visualizer main {
+          name "View of Orders"
+          domain Orders
+        }
+      `);
+    });
+
+    it('when we export a domain that does not exist, a not found error is returned with the requested domain id', async () => {
+      await expect(
+        exportResource({
+          resource: 'domain',
+          id: 'MissingDomain',
+          stdout: true,
+          dir: catalogPath,
+        })
+      ).rejects.toThrow(`domain 'MissingDomain (latest)' not found in catalog at '${catalogPath}'`);
+    });
+  });
+});
diff --git a/packages/cli/src/test/import-export/general.test.ts b/packages/cli/src/test/import-export/general.test.ts
new file mode 100644
index 000000000..19370f205
--- /dev/null
+++ b/packages/cli/src/test/import-export/general.test.ts
@@ -0,0 +1,174 @@
+import { describe, it, expect } from 'vitest';
+import { importDSL } from '../../cli/import';
+import createSDK from '@eventcatalog/sdk';
+import { createCatalogHelper } from './helpers';
+
+const { catalogPath, setup, writeEcFile } = createCatalogHelper('general');
+setup();
+
+describe('import general', () => {
+  it('imports multiple resource types from a single .ec file', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0
+}`
+    );
+
+    const result = await importDSL({
+      files: [ecFile],
+      dir: catalogPath,
+    });
+
+    expect(result).toContain('Created 2 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getEvent('OrderCreated', '1.0.0')).toBeDefined();
+    expect(await sdk.getService('OrderService', '1.0.0')).toBeDefined();
+  });
+
+  it('imports from multiple .ec files', async () => {
+    const file1 = writeEcFile(
+      'events.ec',
+      `event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}`
+    );
+    const file2 = writeEcFile(
+      'commands.ec',
+      `command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+}`
+    );
+
+    const result = await importDSL({
+      files: [file1, file2],
+      dir: catalogPath,
+    });
+
+    expect(result).toContain('Created 2 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getEvent('OrderCreated', '1.0.0')).toBeDefined();
+    expect(await sdk.getCommand('CreateOrder', '1.0.0')).toBeDefined();
+  });
+
+  it('handles mix of new and existing resources', async () => {
+    const sdk = createSDK(catalogPath);
+    await sdk.writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+    const ecFile = writeEcFile(
+      'test.ec',
+      `event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    expect(result).toContain('Created 1 resource(s)');
+    expect(result).toContain('Updated 1 resource(s)');
+
+    const sdk2 = createSDK(catalogPath);
+    expect(await sdk2.getCommand('CreateOrder', '1.0.0')).toBeDefined();
+  });
+
+  it('handles duplicate definitions in a single import run with create then update semantics', async () => {
+    const file1 = writeEcFile(
+      'first.ec',
+      `event OrderCreated {
+  version 1.0.0
+  name "Order Created V1"
+}`
+    );
+    const file2 = writeEcFile(
+      'second.ec',
+      `event OrderCreated {
+  version 1.0.0
+  name "Order Created V2"
+}`
+    );
+
+    const result = await importDSL({
+      files: [file1, file2],
+      dir: catalogPath,
+    });
+
+    expect(result).toContain('Created 1 resource(s)');
+    expect(result).toContain('Updated 1 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    const event = await sdk.getEvent('OrderCreated', '1.0.0');
+    expect(event).toBeDefined();
+    expect(event!.name).toBe('Order Created V2');
+  });
+
+  it('previews without writing with --dry-run', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dryRun: true, dir: catalogPath });
+
+    expect(result).toContain('DRY RUN');
+    expect(result).toContain('Would create 2 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getEvent('OrderCreated', '1.0.0')).toBeUndefined();
+  });
+
+  it('dry-run reports update when resource already exists', async () => {
+    const sdk = createSDK(catalogPath);
+    await sdk.writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+    const ecFile = writeEcFile(
+      'test.ec',
+      `event OrderCreated {
+  version 1.0.0
+  name "Order Created Updated"
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dryRun: true, dir: catalogPath });
+
+    expect(result).toContain('Would update 1 resource(s)');
+  });
+
+  it('throws on parse errors', async () => {
+    const ecFile = writeEcFile('bad.ec', 'this is not valid DSL {{{{');
+
+    await expect(importDSL({ files: [ecFile], dir: catalogPath })).rejects.toThrow('Parse errors');
+  });
+
+  it('throws when file not found', async () => {
+    await expect(importDSL({ files: ['/nonexistent/path/test.ec'], dir: catalogPath })).rejects.toThrow('File not found');
+  });
+
+  it('throws when no files or stdin provided', async () => {
+    await expect(importDSL({ dir: catalogPath })).rejects.toThrow('Either provide .ec file paths or use --stdin');
+  });
+});
diff --git a/packages/cli/src/test/import-export/helpers.ts b/packages/cli/src/test/import-export/helpers.ts
new file mode 100644
index 000000000..7c6b6bf96
--- /dev/null
+++ b/packages/cli/src/test/import-export/helpers.ts
@@ -0,0 +1,26 @@
+import { beforeEach, afterEach } from 'vitest';
+import path from 'node:path';
+import fs from 'node:fs';
+
+export function createCatalogHelper(suffix: string) {
+  const catalogPath = path.join(__dirname, `catalog-import-test-${suffix}`);
+
+  function setup() {
+    beforeEach(() => {
+      fs.rmSync(catalogPath, { recursive: true, force: true });
+      fs.mkdirSync(catalogPath, { recursive: true });
+    });
+
+    afterEach(() => {
+      fs.rmSync(catalogPath, { recursive: true, force: true });
+    });
+  }
+
+  function writeEcFile(name: string, content: string): string {
+    const filepath = path.join(catalogPath, name);
+    fs.writeFileSync(filepath, content, 'utf-8');
+    return filepath;
+  }
+
+  return { catalogPath, setup, writeEcFile };
+}
diff --git a/packages/cli/src/test/import-export/init.test.ts b/packages/cli/src/test/import-export/init.test.ts
new file mode 100644
index 000000000..5ea2b180d
--- /dev/null
+++ b/packages/cli/src/test/import-export/init.test.ts
@@ -0,0 +1,163 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { importDSL, initCatalog } from '../../cli/import';
+import createSDK from '@eventcatalog/sdk';
+import { createCatalogHelper } from './helpers';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const { catalogPath, setup, writeEcFile } = createCatalogHelper('init');
+setup();
+
+describe('catalog initialization', () => {
+  describe('initCatalog', () => {
+    it('creates package.json with correct dependencies and scripts', () => {
+      initCatalog(catalogPath);
+
+      const pkg = JSON.parse(fs.readFileSync(path.join(catalogPath, 'package.json'), 'utf-8'));
+      expect(pkg.dependencies['@eventcatalog/core']).toBe('latest');
+      expect(pkg.dependencies['@eventcatalog/linter']).toBe('latest');
+      expect(pkg.scripts.dev).toBe('eventcatalog dev');
+      expect(pkg.scripts.build).toBe('eventcatalog build');
+      expect(pkg.scripts.start).toBe('eventcatalog start');
+      expect(pkg.scripts.preview).toBe('eventcatalog preview');
+      expect(pkg.scripts.generate).toBe('eventcatalog generate');
+      expect(pkg.scripts.lint).toBe('eventcatalog-linter');
+    });
+
+    it('creates eventcatalog.config.js with a valid cId', () => {
+      initCatalog(catalogPath);
+
+      const config = fs.readFileSync(path.join(catalogPath, 'eventcatalog.config.js'), 'utf-8');
+      expect(config).toContain('organizationName');
+      expect(config).toContain('My Organization');
+      // cId should be a UUID
+      const match = config.match(/cId:\s*'([^']+)'/);
+      expect(match).toBeTruthy();
+      expect(match![1]).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+    });
+
+    it('uses custom organization name when provided', () => {
+      initCatalog(catalogPath, 'Acme Corp');
+
+      const config = fs.readFileSync(path.join(catalogPath, 'eventcatalog.config.js'), 'utf-8');
+      expect(config).toContain("organizationName: 'Acme Corp'");
+    });
+
+    it('creates .gitignore', () => {
+      initCatalog(catalogPath);
+      expect(fs.existsSync(path.join(catalogPath, '.gitignore'))).toBe(true);
+      const content = fs.readFileSync(path.join(catalogPath, '.gitignore'), 'utf-8');
+      expect(content).toContain('node_modules');
+    });
+
+    it('creates .env', () => {
+      initCatalog(catalogPath);
+      expect(fs.existsSync(path.join(catalogPath, '.env'))).toBe(true);
+    });
+
+    it('creates .npmrc', () => {
+      initCatalog(catalogPath);
+      const content = fs.readFileSync(path.join(catalogPath, '.npmrc'), 'utf-8');
+      expect(content).toContain('strict-peer-dependencies=false');
+    });
+
+    it('creates public/logo.png', () => {
+      initCatalog(catalogPath);
+      const logoPath = path.join(catalogPath, 'public', 'logo.png');
+      expect(fs.existsSync(logoPath)).toBe(true);
+      // Should be a valid PNG (starts with PNG magic bytes)
+      const buf = fs.readFileSync(logoPath);
+      expect(buf[0]).toBe(0x89);
+      expect(buf[1]).toBe(0x50); // P
+      expect(buf[2]).toBe(0x4e); // N
+      expect(buf[3]).toBe(0x47); // G
+    });
+  });
+
+  describe('importDSL with init', () => {
+    it('skips scaffolding when noInit is true', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}`
+      );
+
+      await importDSL({
+        files: [ecFile],
+        noInit: true,
+        dir: catalogPath,
+      });
+
+      // Should NOT have created config (noInit skips it)
+      expect(fs.existsSync(path.join(catalogPath, 'eventcatalog.config.js'))).toBe(false);
+    });
+
+    it('skips scaffolding when eventcatalog.config.js already exists', async () => {
+      // Pre-create a config file
+      fs.writeFileSync(path.join(catalogPath, 'eventcatalog.config.js'), 'export default {};', 'utf-8');
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}`
+      );
+
+      await importDSL({
+        files: [ecFile],
+        dir: catalogPath,
+      });
+
+      // Config should still be the original one (not overwritten)
+      const config = fs.readFileSync(path.join(catalogPath, 'eventcatalog.config.js'), 'utf-8');
+      expect(config).toBe('export default {};');
+    });
+
+    it('imports resources into a scaffolded catalog when init runs', async () => {
+      // Scaffold first, then import
+      initCatalog(catalogPath);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0
+}`
+      );
+
+      const result = await importDSL({
+        files: [ecFile],
+        noInit: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toContain('Created 2 resource(s)');
+
+      const sdk = createSDK(catalogPath);
+      expect(await sdk.getEvent('OrderCreated', '1.0.0')).toBeDefined();
+      expect(await sdk.getService('OrderService', '1.0.0')).toBeDefined();
+    });
+
+    it('creates unique cId on each init', () => {
+      initCatalog(catalogPath);
+      const config1 = fs.readFileSync(path.join(catalogPath, 'eventcatalog.config.js'), 'utf-8');
+      const cId1 = config1.match(/cId:\s*'([^']+)'/)![1];
+
+      // Re-init to get a different cId
+      initCatalog(catalogPath);
+      const config2 = fs.readFileSync(path.join(catalogPath, 'eventcatalog.config.js'), 'utf-8');
+      const cId2 = config2.match(/cId:\s*'([^']+)'/)![1];
+
+      expect(cId1).not.toBe(cId2);
+    });
+  });
+});
diff --git a/packages/cli/src/test/import-export/messages.test.ts b/packages/cli/src/test/import-export/messages.test.ts
new file mode 100644
index 000000000..b567436c2
--- /dev/null
+++ b/packages/cli/src/test/import-export/messages.test.ts
@@ -0,0 +1,937 @@
+import { describe, it, expect } from 'vitest';
+import { importDSL } from '../../cli/import';
+import { exportResource } from '../../cli/export';
+import createSDK from '@eventcatalog/sdk';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createCatalogHelper } from './helpers';
+
+const messageTypes = [
+  { type: 'event', dslKeyword: 'event', plural: 'events', write: 'writeEvent', get: 'getEvent', version: 'versionEvent' },
+  {
+    type: 'command',
+    dslKeyword: 'command',
+    plural: 'commands',
+    write: 'writeCommand',
+    get: 'getCommand',
+    version: 'versionCommand',
+  },
+  { type: 'query', dslKeyword: 'query', plural: 'queries', write: 'writeQuery', get: 'getQuery', version: 'versionQuery' },
+] as const;
+
+type MessageTypeConfig = (typeof messageTypes)[number];
+
+const { catalogPath, setup, writeEcFile } = createCatalogHelper('messages');
+setup();
+
+describe.each(messageTypes)('$type import-export rules', (c: MessageTypeConfig) => {
+  describe('import (.ec to eventcatalog)', () => {
+    it(`when we import a ${c.type} that does not exist in the catalog, a ${c.type} resource is created from the DSL`, async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "An order was created"
+}`
+      );
+
+      const result = await importDSL({
+        files: [ecFile],
+        dir: catalogPath,
+      });
+
+      expect(result).toContain('Created 1 resource(s)');
+      expect(result).toContain('OrderCreated@1.0.0');
+
+      const sdk = createSDK(catalogPath);
+      const resource = await sdk[c.get]('OrderCreated', '1.0.0');
+      expect(resource).toBeDefined();
+      expect(resource!.name).toBe('Order Created');
+    });
+
+    it(`when we import a ${c.type} without a version, the ${c.type} resource is created in the root folder`, async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `${c.dslKeyword} SimpleMessage {
+  name "Simple Message"
+}`
+      );
+
+      const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+      expect(result).toContain('Created 1 resource(s)');
+
+      const sdk = createSDK(catalogPath);
+      const resource = await sdk[c.get]('SimpleMessage');
+      expect(resource).toBeDefined();
+      expect(resource!.name).toBe('Simple Message');
+    });
+
+    it(`when no ${c.type} exists, a ${c.type} resource is created with NodeGraph data in markdown`, async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const sdk = createSDK(catalogPath);
+      const resource = await sdk[c.get]('OrderCreated', '1.0.0');
+      expect(resource).toBeDefined();
+      expect(resource!.markdown).toContain('<NodeGraph />');
+    });
+
+    it(`when we import a ${c.type} that already exists, the existing markdown is preserved and NodeGraph is not added`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        markdown: 'existing docs',
+      });
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created V2"
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const sdk2 = createSDK(catalogPath);
+      const resource = await sdk2[c.get]('OrderCreated', '1.0.0');
+      expect(resource).toBeDefined();
+      expect(resource!.markdown).toBe('existing docs');
+      expect(resource!.markdown).not.toContain('<NodeGraph />');
+    });
+
+    it(`when importing the same ${c.type} version from multiple .ec files, the final result is deterministic and the last file wins`, async () => {
+      const firstFile = writeEcFile(
+        'first.ec',
+        `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created First"
+  summary "first summary"
+}`
+      );
+      const secondFile = writeEcFile(
+        'second.ec',
+        `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created Second"
+}`
+      );
+
+      await importDSL({ files: [firstFile, secondFile], dir: catalogPath });
+
+      const sdk = createSDK(catalogPath);
+      const resource = await sdk[c.get]('OrderCreated', '1.0.0');
+      expect(resource).toBeDefined();
+      expect(resource!.name).toBe('Order Created Second');
+      expect((resource as any).summary).toBeUndefined();
+      expect(resource!.markdown).toContain('<NodeGraph />');
+    });
+
+    it(`when we import a ${c.type} with draft true and deprecated true, both flags are written to ${c.type} frontmatter`, async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  draft true
+  deprecated true
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const sdk = createSDK(catalogPath);
+      const resource = await sdk[c.get]('OrderCreated', '1.0.0');
+      expect(resource).toBeDefined();
+      expect((resource as any).draft).toBe(true);
+      expect((resource as any).deprecated).toBe(true);
+    });
+
+    it(`when we import a ${c.type} with draft false and deprecated false over existing true values, existing values are overridden and set to false`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        version: '1.0.0',
+        name: 'Order Created',
+        draft: true,
+        deprecated: true,
+        markdown: 'Existing docs',
+      } as any);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created Updated"
+  draft false
+  deprecated false
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const resource = await sdk[c.get]('OrderCreated', '1.0.0');
+      expect(resource).toBeDefined();
+      expect(resource!.name).toBe('Order Created Updated');
+      expect((resource as any).draft).toBe(false);
+      expect((resource as any).deprecated).toBe(false);
+      expect(resource!.markdown).toBe('Existing docs');
+    });
+
+    it(`when we import a ${c.type} with owner statements over existing owners, owners are overwritten from DSL`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        version: '1.0.0',
+        name: 'Order Created',
+        owners: ['legacy-owner'],
+        markdown: 'Existing docs',
+      } as any);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created Updated"
+  owner orders-team
+  owner platform-team
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const resource = await sdk[c.get]('OrderCreated', '1.0.0');
+      expect(resource).toBeDefined();
+      expect(resource!.name).toBe('Order Created Updated');
+      expect((resource as any).owners).toEqual(['orders-team', 'platform-team']);
+      expect(resource!.markdown).toBe('Existing docs');
+    });
+
+    it(`when we import a ${c.type} without owner statements over existing owners, owners are removed from frontmatter`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        version: '1.0.0',
+        name: 'Order Created',
+        owners: ['legacy-owner'],
+        markdown: 'Existing docs',
+      } as any);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created Updated"
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const resource = await sdk[c.get]('OrderCreated', '1.0.0');
+      expect(resource).toBeDefined();
+      expect(resource!.name).toBe('Order Created Updated');
+      expect((resource as any).owners).toBeUndefined();
+      expect(resource!.markdown).toBe('Existing docs');
+    });
+
+    const managedMessageKeyCases: Array<{
+      key: 'name' | 'version' | 'owners' | 'deprecated' | 'draft' | 'summary';
+      existingValue: any;
+      importSource: string;
+      expectedValue: any;
+      readVersion?: string;
+    }> = [
+      {
+        key: 'name',
+        existingValue: 'Legacy Order Created Name',
+        importSource: `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+}`,
+        expectedValue: 'OrderCreated',
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'version',
+        existingValue: '1.0.0',
+        importSource: `${c.dslKeyword} OrderCreated {
+  name "Order Created Updated"
+}`,
+        expectedValue: undefined,
+      },
+      {
+        key: 'owners',
+        existingValue: ['orders-team'],
+        importSource: `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'deprecated',
+        existingValue: true,
+        importSource: `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'draft',
+        existingValue: true,
+        importSource: `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'summary',
+        existingValue: 'Legacy order created summary',
+        importSource: `${c.dslKeyword} OrderCreated {
+  version 1.0.0
+  name "Order Created Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+    ];
+
+    it.each(managedMessageKeyCases)(
+      `when importing over an existing ${c.type} and the DSL does not provide managed key "$key", that managed key is not preserved from existing frontmatter`,
+      async ({ key, existingValue, importSource, expectedValue, readVersion }) => {
+        const sdk = createSDK(catalogPath);
+        const resourceToWrite: Record<string, any> = {
+          id: 'OrderCreated',
+          version: '1.0.0',
+          name: 'Order Created',
+          markdown: 'Existing docs',
+        };
+        resourceToWrite[key] = existingValue;
+        await sdk[c.write](resourceToWrite as any);
+
+        const ecFile = writeEcFile('test.ec', importSource);
+        await importDSL({ files: [ecFile], dir: catalogPath });
+
+        const resource = await sdk[c.get]('OrderCreated', readVersion);
+        expect(resource).toBeDefined();
+        expect(resource!.id).toBe('OrderCreated');
+        if (expectedValue === undefined) {
+          expect((resource as any)[key]).toBeUndefined();
+        } else {
+          expect((resource as any)[key]).toEqual(expectedValue);
+        }
+        expect(resource!.markdown).toBe('Existing docs');
+      }
+    );
+
+    it(`when importing a newer ${c.type} version, non-DSL keys are carried forward from the latest version`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        version: '1.0.0',
+        name: 'Order Created',
+        summary: 'Order created summary',
+        markdown: 'Order created docs v1',
+      } as any);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `${c.dslKeyword} OrderCreated {
+  version 2.0.0
+  name "Order Created v2"
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const resource = await sdk[c.get]('OrderCreated', '2.0.0');
+      expect(resource).toBeDefined();
+      expect(resource!.name).toBe('Order Created v2');
+      expect((resource as any).summary).toBeUndefined();
+      expect(resource!.markdown).toBe('Order created docs v1\n\n<NodeGraph />');
+    });
+  });
+
+  describe('export (from eventcatalog to .ec)', () => {
+    it(`when we export an existing ${c.type} to stdout, the DSL output contains the ${c.type} definition and visualizer entry`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'An order was created',
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: c.type,
+        id: 'OrderCreated',
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        ${c.dslKeyword} OrderCreated {
+          version 1.0.0
+          name "Order Created"
+          summary "An order was created"
+        }
+
+        visualizer main {
+          name "View of OrderCreated"
+          ${c.dslKeyword} OrderCreated
+        }
+      `);
+    });
+
+    it(`when we export an existing ${c.type}, the latest version is used unless a version is specified`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'v1 summary',
+        markdown: '',
+      });
+      await sdk[c.version]('OrderCreated');
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created V2',
+        version: '2.0.0',
+        summary: 'v2 summary',
+        markdown: '',
+      });
+
+      // Without version, exports latest (2.0.0)
+      const latestResult = await exportResource({
+        resource: c.type,
+        id: 'OrderCreated',
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(latestResult).toBe(dsl`
+        ${c.dslKeyword} OrderCreated {
+          version 2.0.0
+          name "Order Created V2"
+          summary "v2 summary"
+        }
+
+        visualizer main {
+          name "View of OrderCreated"
+          ${c.dslKeyword} OrderCreated
+        }
+      `);
+
+      // With version, exports that specific version
+      const v1Result = await exportResource({
+        resource: c.type,
+        id: 'OrderCreated',
+        version: '1.0.0',
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(v1Result).toBe(dsl`
+        ${c.dslKeyword} OrderCreated {
+          version 1.0.0
+          name "Order Created"
+          summary "v1 summary"
+        }
+
+        visualizer main {
+          name "View of OrderCreated"
+          ${c.dslKeyword} OrderCreated
+        }
+      `);
+    });
+
+    it(`when we export a ${c.type} with hydrate enabled and ${c.type} owners are defined, owner resources are included in the DSL output`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeTeam({
+        id: 'orders-team',
+        name: 'Orders Team',
+        markdown: '',
+      } as any);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        owners: ['orders-team'],
+        markdown: '',
+      } as any);
+
+      const result = await exportResource({
+        resource: c.type,
+        id: 'OrderCreated',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        // TEAMS
+        team orders-team {
+          name "Orders Team"
+        }
+
+        // ${c.plural.toUpperCase()}
+        ${c.dslKeyword} OrderCreated {
+          version 1.0.0
+          name "Order Created"
+          owner orders-team
+        }
+
+        visualizer main {
+          name "View of OrderCreated"
+          ${c.dslKeyword} OrderCreated
+        }
+      `);
+    });
+
+    it(`when we export a ${c.type} with hydrate enabled, the DSL output contains the producers and consumers of the ${c.type}`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'NotificationService',
+        name: 'Notification Service',
+        version: '1.0.0',
+        receives: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: c.type,
+        id: 'OrderCreated',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        // ${c.plural.toUpperCase()}
+        ${c.dslKeyword} OrderCreated {
+          version 1.0.0
+          name "Order Created"
+        }
+
+        // SERVICES
+        service OrderService {
+          version 1.0.0
+          name "Order Service"
+          sends ${c.dslKeyword} OrderCreated@1.0.0
+        }
+
+        service NotificationService {
+          version 1.0.0
+          name "Notification Service"
+          receives ${c.dslKeyword} OrderCreated@1.0.0
+        }
+
+        visualizer main {
+          name "View of OrderCreated"
+          ${c.dslKeyword} OrderCreated
+          service OrderService
+          service NotificationService
+        }
+      `);
+    });
+
+    it(`when we export a ${c.type} with hydrate enabled, the DSL output contains the producers and consumers of the ${c.type}, the producers and consumers only contain the ${c.type} and no other messages`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeEvent({
+        id: 'OrderShipped',
+        name: 'Order Shipped',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeCommand({
+        id: 'CancelOrder',
+        name: 'Cancel Order',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [
+          { id: 'OrderCreated', version: '1.0.0' },
+          { id: 'OrderShipped', version: '1.0.0' },
+        ],
+        receives: [{ id: 'CancelOrder', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: c.type,
+        id: 'OrderCreated',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      // Service should only contain OrderCreated references, not OrderShipped or CancelOrder
+      expect(result).toContain('service OrderService');
+      expect(result).toContain(`sends ${c.dslKeyword} OrderCreated@1.0.0`);
+      expect(result).not.toContain('OrderShipped');
+      expect(result).not.toContain('CancelOrder');
+    });
+
+    it(`when we export a ${c.type} with hydrate enabled, producers and consumers using semver range patterns are matched`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.2.3',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '^1.0.0' }],
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'NotificationService',
+        name: 'Notification Service',
+        version: '1.0.0',
+        receives: [{ id: 'OrderCreated', version: '~1.2.0' }],
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'ArchiveService',
+        name: 'Archive Service',
+        version: '1.0.0',
+        receives: [{ id: 'OrderCreated', version: '2.0.0' }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: c.type,
+        id: 'OrderCreated',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      // ^1.0.0 matches 1.2.3, ~1.2.0 matches 1.2.3
+      expect(result).toContain('service OrderService');
+      expect(result).toContain('service NotificationService');
+      // 2.0.0 does not match 1.2.3
+      expect(result).not.toContain('ArchiveService');
+    });
+
+    it(`when we export a ${c.type} with hydrate enabled and multiple versions of the same service publish the ${c.type}, all versions are included in the DSL output`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+      await sdk.versionService('OrderService');
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service V2',
+        version: '2.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: c.type,
+        id: 'OrderCreated',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      // Both versions of OrderService should be included
+      expect(result).toContain('service OrderService {');
+      expect(result).toContain('version 1.0.0');
+      expect(result).toContain('version 2.0.0');
+      expect(result).toContain('name "Order Service"');
+      expect(result).toContain('name "Order Service V2"');
+    });
+
+    it(`when we export a ${c.type} with hydrate enabled, the DSL output contains the producers and consumers, any duplicates are removed`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        receives: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: c.type,
+        id: 'OrderCreated',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        // ${c.plural.toUpperCase()}
+        ${c.dslKeyword} OrderCreated {
+          version 1.0.0
+          name "Order Created"
+        }
+
+        // SERVICES
+        service OrderService {
+          version 1.0.0
+          name "Order Service"
+          sends ${c.dslKeyword} OrderCreated@1.0.0
+          receives ${c.dslKeyword} OrderCreated@1.0.0
+        }
+
+        visualizer main {
+          name "View of OrderCreated"
+          ${c.dslKeyword} OrderCreated
+          service OrderService
+        }
+      `);
+    });
+
+    it(`when we export a ${c.type} with hydrate enabled, any channels used by the services to consume or produce the ${c.type} are included in the DSL output`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeChannel({
+        id: 'orders-topic',
+        name: 'Orders Topic',
+        version: '1.0.0',
+        address: 'orders.events',
+        markdown: '',
+      } as any);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: c.type,
+        id: 'OrderCreated',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        // CHANNELS
+        channel orders-topic {
+          version 1.0.0
+          name "Orders Topic"
+          address "orders.events"
+        }
+
+        // ${c.plural.toUpperCase()}
+        ${c.dslKeyword} OrderCreated {
+          version 1.0.0
+          name "Order Created"
+        }
+
+        // SERVICES
+        service OrderService {
+          version 1.0.0
+          name "Order Service"
+          sends ${c.dslKeyword} OrderCreated@1.0.0 to orders-topic@1.0.0
+        }
+
+        visualizer main {
+          name "View of OrderCreated"
+          ${c.dslKeyword} OrderCreated
+          service OrderService
+        }
+      `);
+    });
+
+    it(`when we export a ${c.type} with hydrate enabled and multiple versions of the same service exist, the visualizer block includes version-qualified service references`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+      await sdk.versionService('OrderService');
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service V2',
+        version: '2.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: c.type,
+        id: 'OrderCreated',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toContain('service OrderService@2.0.0');
+      expect(result).toContain('service OrderService@1.0.0');
+    });
+
+    it(`when we export a ${c.type} with hydrate enabled, if there are services, they are added to the visualizer block`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: c.type,
+        id: 'OrderCreated',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        // ${c.plural.toUpperCase()}
+        ${c.dslKeyword} OrderCreated {
+          version 1.0.0
+          name "Order Created"
+        }
+
+        // SERVICES
+        service OrderService {
+          version 1.0.0
+          name "Order Service"
+          sends ${c.dslKeyword} OrderCreated@1.0.0
+        }
+
+        visualizer main {
+          name "View of OrderCreated"
+          ${c.dslKeyword} OrderCreated
+          service OrderService
+        }
+      `);
+    });
+
+    it(`when we export a ${c.type} with hydrate enabled and a service references the ${c.type} without a version (latest), the service is included as a consumer/producer`, async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk[c.write]({
+        id: 'PaymentProcessed',
+        name: 'Payment Processed',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'ShippingService',
+        name: 'Shipping Service',
+        version: '1.0.0',
+        receives: [{ id: 'PaymentProcessed' }],
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'PaymentService',
+        name: 'Payment Service',
+        version: '1.0.0',
+        sends: [{ id: 'PaymentProcessed' }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: c.type,
+        id: 'PaymentProcessed',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toContain('service ShippingService');
+      expect(result).toContain(`receives ${c.dslKeyword} PaymentProcessed`);
+      expect(result).toContain('service PaymentService');
+      expect(result).toContain(`sends ${c.dslKeyword} PaymentProcessed`);
+    });
+
+    it(`when we export a ${c.type} that does not exist, a not found error is returned with the requested ${c.type} id`, async () => {
+      await expect(
+        exportResource({
+          resource: c.type,
+          id: 'MissingMessage',
+          stdout: true,
+          dir: catalogPath,
+        })
+      ).rejects.toThrow(`${c.type} 'MissingMessage (latest)' not found in catalog at '${catalogPath}'`);
+    });
+  });
+});
diff --git a/packages/cli/src/test/import-export/nesting.test.ts b/packages/cli/src/test/import-export/nesting.test.ts
new file mode 100644
index 000000000..2ce5b5beb
--- /dev/null
+++ b/packages/cli/src/test/import-export/nesting.test.ts
@@ -0,0 +1,252 @@
+import { describe, it, expect } from 'vitest';
+import { importDSL } from '../../cli/import';
+import createSDK from '@eventcatalog/sdk';
+import { createCatalogHelper } from './helpers';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const { catalogPath, setup, writeEcFile } = createCatalogHelper('nesting');
+setup();
+
+function existsInCatalog(...segments: string[]): boolean {
+  return fs.existsSync(path.join(catalogPath, ...segments));
+}
+
+describe('import nested structure', () => {
+  it('nests services inside domains by default', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `domain Payment {
+  version 1.0.0
+  service OrderService {
+    version 1.0.0
+  }
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getDomain('Payment', '1.0.0')).toBeDefined();
+    expect(await sdk.getService('OrderService', '1.0.0')).toBeDefined();
+
+    // Service should be nested under domain
+    expect(existsInCatalog('domains', 'Payment', 'services', 'OrderService')).toBe(true);
+  });
+
+  it('nests services inside subdomains', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `domain Ecommerce {
+  version 1.0.0
+  subdomain Payments {
+    version 1.0.0
+    service PaymentService {
+      version 1.0.0
+    }
+  }
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getDomain('Ecommerce', '1.0.0')).toBeDefined();
+    expect(await sdk.getService('PaymentService', '1.0.0')).toBeDefined();
+
+    // Service should be nested under subdomain
+    expect(existsInCatalog('domains', 'Ecommerce', 'subdomains', 'Payments', 'services', 'PaymentService')).toBe(true);
+  });
+
+  it('nests inline messages under service path', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `domain Payment {
+  version 1.0.0
+  service OrderService {
+    version 1.0.0
+    sends event OrderCreated {
+      version 1.0.0
+    }
+  }
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getEvent('OrderCreated', '1.0.0')).toBeDefined();
+
+    // Event should be nested under the service under the domain
+    expect(existsInCatalog('domains', 'Payment', 'services', 'OrderService', 'events', 'OrderCreated')).toBe(true);
+  });
+
+  it('nests message stubs under parent service', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `domain Payment {
+  version 1.0.0
+  service OrderService {
+    version 1.0.0
+    sends event OrderCreated
+    receives command PlaceOrder
+  }
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getEvent('OrderCreated', '0.0.1')).toBeDefined();
+    expect(await sdk.getCommand('PlaceOrder', '0.0.1')).toBeDefined();
+
+    // Stubs should be nested under the service
+    expect(existsInCatalog('domains', 'Payment', 'services', 'OrderService', 'events', 'OrderCreated')).toBe(true);
+    expect(existsInCatalog('domains', 'Payment', 'services', 'OrderService', 'commands', 'PlaceOrder')).toBe(true);
+  });
+
+  it('nests channel stubs under domain', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `domain Payment {
+  version 1.0.0
+  service OrderService {
+    version 1.0.0
+    sends event OrderCreated to orders-topic
+  }
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getChannel('orders-topic', '0.0.1')).toBeDefined();
+
+    // Channel stub should be under the domain
+    expect(existsInCatalog('domains', 'Payment', 'channels', 'orders-topic')).toBe(true);
+  });
+
+  it('produces flat structure with --flat flag', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `domain Payment {
+  version 1.0.0
+  service OrderService {
+    version 1.0.0
+    sends event OrderCreated {
+      version 1.0.0
+    }
+  }
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath, flat: true });
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getDomain('Payment', '1.0.0')).toBeDefined();
+    expect(await sdk.getService('OrderService', '1.0.0')).toBeDefined();
+    expect(await sdk.getEvent('OrderCreated', '1.0.0')).toBeDefined();
+
+    // With flat, services and events should be at top level
+    expect(existsInCatalog('services', 'OrderService')).toBe(true);
+    expect(existsInCatalog('events', 'OrderCreated')).toBe(true);
+    // Should NOT be nested under domain
+    expect(existsInCatalog('domains', 'Payment', 'services')).toBe(false);
+  });
+
+  it('writes to existing location when resource already exists', async () => {
+    // Pre-create a service at a flat location
+    const sdk = createSDK(catalogPath);
+    await sdk.writeService({
+      id: 'OrderService',
+      name: 'Order Service',
+      version: '1.0.0',
+      markdown: 'existing docs',
+    });
+
+    // Verify it exists at flat location
+    expect(existsInCatalog('services', 'OrderService')).toBe(true);
+
+    // Now import with nesting — the service is inside a domain
+    const ecFile = writeEcFile(
+      'test.ec',
+      `domain Payment {
+  version 1.0.0
+  service OrderService {
+    version 1.0.0
+    name "Updated Order Service"
+  }
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    // Resource should be updated at its existing flat location
+    const updated = await sdk.getService('OrderService', '1.0.0');
+    expect(updated).toBeDefined();
+    expect(updated!.name).toBe('Updated Order Service');
+
+    // It should still be at the flat location (existing takes precedence)
+    expect(existsInCatalog('services', 'OrderService')).toBe(true);
+  });
+
+  it('top-level service (no domain) still goes to services/', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service StandaloneService {
+  version 1.0.0
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    expect(existsInCatalog('services', 'StandaloneService')).toBe(true);
+  });
+
+  it('uses subdomains path instead of domains for subdomain output', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `domain Ecommerce {
+  version 1.0.0
+  subdomain Payments {
+    version 1.0.0
+  }
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    // Subdomain should use subdomains/ not domains/
+    expect(existsInCatalog('domains', 'Ecommerce', 'subdomains', 'Payments')).toBe(true);
+    expect(existsInCatalog('domains', 'Ecommerce', 'domains', 'Payments')).toBe(false);
+  });
+
+  it('domain frontmatter lists its services', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `domain Payment {
+  version 1.0.0
+  service OrderService {
+    version 2.0.0
+  }
+  service RefundService {
+    version 1.0.0
+  }
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    const domain = await sdk.getDomain('Payment', '1.0.0');
+    expect(domain).toBeDefined();
+    expect(domain!.services).toBeDefined();
+    expect(domain!.services).toHaveLength(2);
+    expect(domain!.services).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ id: 'OrderService', version: '2.0.0' }),
+        expect.objectContaining({ id: 'RefundService', version: '1.0.0' }),
+      ])
+    );
+  });
+});
diff --git a/packages/cli/src/test/import-export/resource-types.test.ts b/packages/cli/src/test/import-export/resource-types.test.ts
new file mode 100644
index 000000000..7b1dfccea
--- /dev/null
+++ b/packages/cli/src/test/import-export/resource-types.test.ts
@@ -0,0 +1,231 @@
+import { describe, it, expect } from 'vitest';
+import { importDSL } from '../../cli/import';
+import createSDK from '@eventcatalog/sdk';
+import { createCatalogHelper } from './helpers';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const { catalogPath, setup, writeEcFile } = createCatalogHelper('resource-types');
+setup();
+
+function existsInCatalog(...segments: string[]): boolean {
+  return fs.existsSync(path.join(catalogPath, ...segments));
+}
+
+describe('import additional resource types', () => {
+  it('imports containers, data products, and diagrams', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `container orders-db {
+  version 1.0.0
+  name "Orders DB"
+  summary "Orders database"
+  container-type database
+}
+
+data-product CustomerAnalytics {
+  version 1.0.0
+  name "Customer Analytics"
+  summary "Customer analytics data product"
+}
+
+diagram system-overview {
+  version 1.0.0
+  name "System Overview"
+  summary "High-level architecture diagram"
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    expect(result).toContain('Created 3 resource(s)');
+    expect(result).toContain('orders-db@1.0.0');
+    expect(result).toContain('CustomerAnalytics@1.0.0');
+    expect(result).toContain('system-overview@1.0.0');
+    expect(result).not.toContain('unsupported resource type');
+
+    const sdk = createSDK(catalogPath);
+    const container = await sdk.getDataStore('orders-db', '1.0.0');
+    const dataProduct = await sdk.getDataProduct('CustomerAnalytics', '1.0.0');
+    const diagram = await sdk.getDiagram('system-overview', '1.0.0');
+
+    expect(container).toBeDefined();
+    expect(container!.name).toBe('Orders DB');
+    expect(container!.markdown).not.toContain('<NodeGraph />');
+    expect(dataProduct).toBeDefined();
+    expect(dataProduct!.name).toBe('Customer Analytics');
+    expect(dataProduct!.markdown).not.toContain('<NodeGraph />');
+    expect(diagram).toBeDefined();
+    expect(diagram!.name).toBe('System Overview');
+    expect(diagram!.markdown).not.toContain('<NodeGraph />');
+  });
+
+  it('dry-run reports updates for existing containers', async () => {
+    const sdk = createSDK(catalogPath);
+    await sdk.writeDataStore({
+      id: 'orders-db',
+      name: 'Orders DB',
+      version: '1.0.0',
+      summary: 'Orders database',
+      markdown: '',
+      container_type: 'database',
+    });
+
+    const ecFile = writeEcFile(
+      'test.ec',
+      `container orders-db {
+  version 1.0.0
+  name "Orders DB Updated"
+  summary "Orders database"
+  container-type database
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dryRun: true, dir: catalogPath });
+
+    expect(result).toContain('Would update 1 resource(s)');
+    expect(result).toContain('orders-db@1.0.0');
+  });
+
+  it('normalizes container fields to SDK/core naming', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `container orders-db {
+  version 1.0.0
+  name "Orders DB"
+  summary "Orders database"
+  container-type database
+  access-mode readWrite
+  classification internal
+  residency "eu-west-1"
+  retention "P90D"
+  authoritative true
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    const container: any = await sdk.getDataStore('orders-db', '1.0.0');
+    expect(container).toBeDefined();
+    expect(container.container_type).toBe('database');
+    expect(container.access_mode).toBe('readWrite');
+    expect(container.containerType).toBeUndefined();
+    expect(container.accessMode).toBeUndefined();
+  });
+
+  it('defaults container_type to database when not specified in DSL', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `container orders-db {
+  version 1.0.0
+  name "Orders DB"
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    const container: any = await sdk.getDataStore('orders-db', '1.0.0');
+    expect(container).toBeDefined();
+    expect(container.container_type).toBe('database');
+  });
+
+  it('nests domain containers by default', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `domain Payment {
+  version 1.0.0
+  container payment-db {
+    version 1.0.0
+    container-type database
+  }
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getDataStore('payment-db', '1.0.0')).toBeDefined();
+    expect(existsInCatalog('domains', 'Payment', 'containers', 'payment-db')).toBe(true);
+  });
+
+  it('writes domain containers to top-level with --flat', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `domain Payment {
+  version 1.0.0
+  container payment-db {
+    version 1.0.0
+    container-type database
+  }
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath, flat: true });
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getDataStore('payment-db', '1.0.0')).toBeDefined();
+    expect(existsInCatalog('containers', 'payment-db')).toBe(true);
+    expect(existsInCatalog('domains', 'Payment', 'containers', 'payment-db')).toBe(false);
+  });
+
+  it('versions existing data products when importing a newer version', async () => {
+    const sdk = createSDK(catalogPath);
+    await sdk.writeDataProduct({
+      id: 'CustomerAnalytics',
+      name: 'Customer Analytics',
+      version: '1.0.0',
+      summary: 'v1',
+      markdown: '',
+    });
+
+    const ecFile = writeEcFile(
+      'test.ec',
+      `data-product CustomerAnalytics {
+  version 2.0.0
+  name "Customer Analytics V2"
+  summary "v2"
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+    expect(result).toContain('Created 1 resource(s)');
+    expect(result).toContain('Versioned 1 existing resource(s)');
+    expect(result).toContain('CustomerAnalytics@1.0.0');
+
+    expect(existsInCatalog('data-products', 'CustomerAnalytics', 'versioned', '1.0.0', 'index.mdx')).toBe(true);
+    const latest = await sdk.getDataProduct('CustomerAnalytics');
+    expect(latest).toBeDefined();
+    expect(latest!.version).toBe('2.0.0');
+    expect(latest!.name).toBe('Customer Analytics V2');
+  });
+
+  it('updates existing diagrams when importing the same version', async () => {
+    const sdk = createSDK(catalogPath);
+    await sdk.writeDiagram({
+      id: 'system-overview',
+      name: 'System Overview',
+      version: '1.0.0',
+      summary: 'old summary',
+      markdown: '',
+    });
+
+    const ecFile = writeEcFile(
+      'test.ec',
+      `diagram system-overview {
+  version 1.0.0
+  name "System Overview Updated"
+  summary "new summary"
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+    expect(result).toContain('Updated 1 resource(s)');
+
+    const updated = await sdk.getDiagram('system-overview', '1.0.0');
+    expect(updated).toBeDefined();
+    expect(updated!.name).toBe('System Overview Updated');
+    expect(updated!.markdown).not.toContain('<NodeGraph />');
+  });
+});
diff --git a/packages/cli/src/test/import-export/services.test.ts b/packages/cli/src/test/import-export/services.test.ts
new file mode 100644
index 000000000..b64630e69
--- /dev/null
+++ b/packages/cli/src/test/import-export/services.test.ts
@@ -0,0 +1,743 @@
+import { describe, it, expect } from 'vitest';
+import { importDSL } from '../../cli/import';
+import { exportResource } from '../../cli/export';
+import createSDK from '@eventcatalog/sdk';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createCatalogHelper } from './helpers';
+
+const { catalogPath, setup, writeEcFile } = createCatalogHelper('services');
+setup();
+
+describe('services import-export rules', () => {
+  describe('import (.ec to eventcatalog)', () => {
+    it('when we import a service that does not exist in the catalog, a service resource is created from the DSL', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `service PaymentService {
+  version 2.0.0
+  name "Payment Service"
+  summary "Handles payments"
+}`
+      );
+
+      const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+      expect(result).toContain('Created 1 resource(s)');
+
+      const sdk = createSDK(catalogPath);
+      const service = await sdk.getService('PaymentService', '2.0.0');
+      expect(service).toBeDefined();
+      expect(service!.name).toBe('Payment Service');
+    });
+
+    it('when no service exists, a service resource is created with NodeGraph data in markdown', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `service PaymentService {
+  version 1.0.0
+  name "Payment Service"
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const sdk = createSDK(catalogPath);
+      const service = await sdk.getService('PaymentService', '1.0.0');
+      expect(service).toBeDefined();
+      expect(service!.markdown).toContain('<NodeGraph />');
+    });
+
+    it('when we import a service with inline messages, the service and message resources are created', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated {
+    version 1.0.0
+    name "Order Created"
+    summary "An order was created"
+  }
+}`
+      );
+
+      const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+      expect(result).toContain('Created 2 resource(s)');
+
+      const sdk = createSDK(catalogPath);
+      expect(await sdk.getService('OrderService', '1.0.0')).toBeDefined();
+      expect(await sdk.getEvent('OrderCreated', '1.0.0')).toBeDefined();
+    });
+
+    it('when we import a service that already exists with sends/receives and the DSL does not include them, sends/receives are removed', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: 'existing service docs',
+      });
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `service OrderService {
+  version 1.0.0
+  name "Order Service Updated"
+}`
+      );
+
+      const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+      expect(result).toContain('Updated 1 resource(s)');
+
+      const sdk2 = createSDK(catalogPath);
+      const service = await sdk2.getService('OrderService', '1.0.0');
+      expect(service!.name).toBe('Order Service Updated');
+      expect((service as any).sends).toBeUndefined();
+    });
+
+    it('when we import a service that already exists, the existing markdown is preserved and NodeGraph is not added', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        markdown: 'existing docs',
+      });
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `service OrderService {
+  version 1.0.0
+  name "Order Service V2"
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const sdk2 = createSDK(catalogPath);
+      const service = await sdk2.getService('OrderService', '1.0.0');
+      expect(service).toBeDefined();
+      expect(service!.markdown).toBe('existing docs');
+      expect(service!.markdown).not.toContain('<NodeGraph />');
+    });
+
+    it('when importing the same service version from multiple .ec files, the final result is deterministic and the last file wins', async () => {
+      const firstFile = writeEcFile(
+        'first.ec',
+        `service OrderService {
+  version 1.0.0
+  name "Order Service First"
+  summary "first summary"
+}`
+      );
+      const secondFile = writeEcFile(
+        'second.ec',
+        `service OrderService {
+  version 1.0.0
+  name "Order Service Second"
+}`
+      );
+
+      await importDSL({ files: [firstFile, secondFile], dir: catalogPath });
+
+      const sdk = createSDK(catalogPath);
+      const service = await sdk.getService('OrderService', '1.0.0');
+      expect(service).toBeDefined();
+      expect(service!.name).toBe('Order Service Second');
+      expect((service as any).summary).toBeUndefined();
+      expect(service!.markdown).toContain('<NodeGraph />');
+    });
+
+    it('when we import a service with draft true and deprecated true, both flags are written to service frontmatter', async () => {
+      const ecFile = writeEcFile(
+        'test.ec',
+        `service OrderService {
+  version 1.0.0
+  name "Order Service"
+  draft true
+  deprecated true
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const sdk = createSDK(catalogPath);
+      const service = await sdk.getService('OrderService', '1.0.0');
+      expect(service).toBeDefined();
+      expect((service as any).draft).toBe(true);
+      expect((service as any).deprecated).toBe(true);
+    });
+
+    it('when we import a service with draft false and deprecated false over existing true values, existing values are overridden and set to false', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeService({
+        id: 'OrderService',
+        version: '1.0.0',
+        name: 'Order Service',
+        draft: true,
+        deprecated: true,
+        markdown: 'Existing docs',
+      } as any);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `service OrderService {
+  version 1.0.0
+  name "Order Service Updated"
+  draft false
+  deprecated false
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const service = await sdk.getService('OrderService', '1.0.0');
+      expect(service).toBeDefined();
+      expect(service!.name).toBe('Order Service Updated');
+      expect((service as any).draft).toBe(false);
+      expect((service as any).deprecated).toBe(false);
+      expect(service!.markdown).toBe('Existing docs');
+    });
+
+    it('when we import a service with owner statements over existing owners, owners are overwritten from DSL', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeService({
+        id: 'OrderService',
+        version: '1.0.0',
+        name: 'Order Service',
+        owners: ['legacy-owner'],
+        markdown: 'Existing docs',
+      } as any);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `service OrderService {
+  version 1.0.0
+  name "Order Service Updated"
+  owner orders-team
+  owner platform-team
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const service = await sdk.getService('OrderService', '1.0.0');
+      expect(service).toBeDefined();
+      expect(service!.name).toBe('Order Service Updated');
+      expect((service as any).owners).toEqual(['orders-team', 'platform-team']);
+      expect(service!.markdown).toBe('Existing docs');
+    });
+
+    it('when we import a service without owner statements over existing owners, owners are removed from frontmatter', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeService({
+        id: 'OrderService',
+        version: '1.0.0',
+        name: 'Order Service',
+        owners: ['legacy-owner'],
+        markdown: 'Existing docs',
+      } as any);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `service OrderService {
+  version 1.0.0
+  name "Order Service Updated"
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const service = await sdk.getService('OrderService', '1.0.0');
+      expect(service).toBeDefined();
+      expect(service!.name).toBe('Order Service Updated');
+      expect((service as any).owners).toBeUndefined();
+      expect(service!.markdown).toBe('Existing docs');
+    });
+
+    const managedServiceKeyCases: Array<{
+      key: 'name' | 'version' | 'owners' | 'deprecated' | 'draft' | 'summary' | 'sends' | 'receives';
+      existingValue: any;
+      importSource: string;
+      expectedValue: any;
+      readVersion?: string;
+    }> = [
+      {
+        key: 'name',
+        existingValue: 'Legacy Order Service Name',
+        importSource: `service OrderService {
+  version 1.0.0
+}`,
+        expectedValue: 'OrderService',
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'version',
+        existingValue: '1.0.0',
+        importSource: `service OrderService {
+  name "Order Service Updated"
+}`,
+        expectedValue: undefined,
+      },
+      {
+        key: 'owners',
+        existingValue: ['orders-team'],
+        importSource: `service OrderService {
+  version 1.0.0
+  name "Order Service Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'deprecated',
+        existingValue: true,
+        importSource: `service OrderService {
+  version 1.0.0
+  name "Order Service Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'draft',
+        existingValue: true,
+        importSource: `service OrderService {
+  version 1.0.0
+  name "Order Service Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'summary',
+        existingValue: 'Legacy order service summary',
+        importSource: `service OrderService {
+  version 1.0.0
+  name "Order Service Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'sends',
+        existingValue: [{ id: 'OrderCreated', version: '1.0.0' }],
+        importSource: `service OrderService {
+  version 1.0.0
+  name "Order Service Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+      {
+        key: 'receives',
+        existingValue: [{ id: 'CancelOrder', version: '1.0.0' }],
+        importSource: `service OrderService {
+  version 1.0.0
+  name "Order Service Updated"
+}`,
+        expectedValue: undefined,
+        readVersion: '1.0.0',
+      },
+    ];
+
+    it.each(managedServiceKeyCases)(
+      'when importing over an existing service and the DSL does not provide managed key "$key", that managed key is not preserved from existing frontmatter',
+      async ({ key, existingValue, importSource, expectedValue, readVersion }) => {
+        const sdk = createSDK(catalogPath);
+        const serviceToWrite: Record<string, any> = {
+          id: 'OrderService',
+          version: '1.0.0',
+          name: 'Order Service',
+          markdown: 'Existing docs',
+        };
+        serviceToWrite[key] = existingValue;
+        await sdk.writeService(serviceToWrite as any);
+
+        const ecFile = writeEcFile('test.ec', importSource);
+        await importDSL({ files: [ecFile], dir: catalogPath });
+
+        const service = await sdk.getService('OrderService', readVersion);
+        expect(service).toBeDefined();
+        expect(service!.id).toBe('OrderService');
+        if (expectedValue === undefined) {
+          expect((service as any)[key]).toBeUndefined();
+        } else {
+          expect((service as any)[key]).toEqual(expectedValue);
+        }
+        expect(service!.markdown).toBe('Existing docs');
+      }
+    );
+
+    it('when importing a newer service version, non-DSL keys are carried forward from the latest version', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeService({
+        id: 'OrderService',
+        version: '1.0.0',
+        name: 'Order Service',
+        summary: 'Order service summary',
+        markdown: 'Order service docs v1',
+      } as any);
+
+      const ecFile = writeEcFile(
+        'test.ec',
+        `service OrderService {
+  version 2.0.0
+  name "Order Service v2"
+}`
+      );
+
+      await importDSL({ files: [ecFile], dir: catalogPath });
+
+      const service = await sdk.getService('OrderService', '2.0.0');
+      expect(service).toBeDefined();
+      expect(service!.name).toBe('Order Service v2');
+      expect((service as any).summary).toBeUndefined();
+      expect(service!.markdown).toBe('Order service docs v1\n\n<NodeGraph />');
+    });
+  });
+
+  describe('export (from eventcatalog to .ec)', () => {
+    it('when we export an existing service to stdout, the DSL output contains the service definition and visualizer entry', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        summary: 'Order management',
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: 'service',
+        id: 'OrderService',
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        service OrderService {
+          version 1.0.0
+          name "Order Service"
+          summary "Order management"
+        }
+
+        visualizer main {
+          name "View of OrderService"
+          service OrderService
+        }
+      `);
+    });
+
+    it('when we export a service with hydrate enabled and service sends messages, the message resources are included in the DSL output', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: 'service',
+        id: 'OrderService',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        // EVENTS
+        event OrderCreated {
+          version 1.0.0
+          name "Order Created"
+        }
+
+        // SERVICES
+        service OrderService {
+          version 1.0.0
+          name "Order Service"
+          sends event OrderCreated@1.0.0
+        }
+
+        visualizer main {
+          name "View of OrderService"
+          event OrderCreated
+          service OrderService
+        }
+      `);
+    });
+
+    it('when we export a service with hydrate enabled and service receives messages, the message resources are included in the DSL output', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeCommand({
+        id: 'CancelOrder',
+        name: 'Cancel Order',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        receives: [{ id: 'CancelOrder', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: 'service',
+        id: 'OrderService',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        // COMMANDS
+        command CancelOrder {
+          version 1.0.0
+          name "Cancel Order"
+        }
+
+        // SERVICES
+        service OrderService {
+          version 1.0.0
+          name "Order Service"
+          receives command CancelOrder@1.0.0
+        }
+
+        visualizer main {
+          name "View of OrderService"
+          command CancelOrder
+          service OrderService
+        }
+      `);
+    });
+
+    it('when we export a service with hydrate enabled, downstream consumers of published messages and upstream producers of consumed messages are included, but fellow consumers are excluded', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        markdown: '',
+      });
+      await sdk.writeCommand({
+        id: 'CancelOrder',
+        name: 'Cancel Order',
+        version: '1.0.0',
+        markdown: '',
+      });
+      // OrderService sends OrderCreated and receives CancelOrder
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        receives: [{ id: 'CancelOrder', version: '1.0.0' }],
+        markdown: '',
+      });
+      // NotificationService consumes OrderCreated (downstream consumer of our published message)
+      await sdk.writeService({
+        id: 'NotificationService',
+        name: 'Notification Service',
+        version: '1.0.0',
+        receives: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+      // CustomerService produces CancelOrder (upstream producer of a message we consume)
+      await sdk.writeService({
+        id: 'CustomerService',
+        name: 'Customer Service',
+        version: '1.0.0',
+        sends: [{ id: 'CancelOrder', version: '1.0.0' }],
+        markdown: '',
+      });
+      // InventoryService also receives CancelOrder (fellow consumer — should NOT be included)
+      await sdk.writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        receives: [{ id: 'CancelOrder', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: 'service',
+        id: 'OrderService',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      // The exported service and its messages should be present
+      expect(result).toContain('service OrderService');
+      expect(result).toContain('event OrderCreated');
+      expect(result).toContain('command CancelOrder');
+      // Consumers of messages this service publishes should be included
+      expect(result).toContain('service NotificationService');
+      // Producers of messages this service consumes should be included
+      expect(result).toContain('service CustomerService');
+      // Fellow consumers of the same messages should NOT be included
+      expect(result).not.toContain('service InventoryService');
+    });
+
+    it('when we export a service with hydrate enabled and a related producer sends a message through a channel, the channel is included in the DSL output', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeChannel({
+        id: 'inventory.{env}.events',
+        name: 'Inventory Events Channel',
+        version: '1.0.0',
+        address: 'inventory.{env}.events',
+        markdown: '',
+      } as any);
+      await sdk.writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory adjusted',
+        version: '1.0.1',
+        markdown: '',
+      });
+      // InventoryService sends InventoryAdjusted through a channel
+      await sdk.writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.2',
+        sends: [{ id: 'InventoryAdjusted', version: '1.0.1', to: [{ id: 'inventory.{env}.events' }] }],
+        markdown: '',
+      });
+      // NotificationService receives InventoryAdjusted
+      await sdk.writeService({
+        id: 'NotificationService',
+        name: 'Notifications',
+        version: '0.0.2',
+        receives: [{ id: 'InventoryAdjusted', version: '1.0.1' }],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: 'service',
+        id: 'NotificationService',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      // The upstream producer should be included
+      expect(result).toContain('service InventoryService');
+      // The channel the producer uses should also be included
+      expect(result).toContain('channel inventory.{env}.events');
+      expect(result).toContain('sends event InventoryAdjusted@1.0.1 to inventory.{env}.events');
+    });
+
+    it('when we export a service with hydrate enabled and service owners are defined, owner resources are included in the DSL output', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeTeam({
+        id: 'orders-team',
+        name: 'Orders Team',
+        markdown: '',
+      } as any);
+      await sdk.writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        owners: ['orders-team'],
+        markdown: '',
+      } as any);
+
+      const result = await exportResource({
+        resource: 'service',
+        id: 'OrderService',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      expect(result).toBe(dsl`
+        // TEAMS
+        team orders-team {
+          name "Orders Team"
+        }
+
+        // SERVICES
+        service OrderService {
+          version 1.0.0
+          name "Order Service"
+          owner orders-team
+        }
+
+        visualizer main {
+          name "View of OrderService"
+          service OrderService
+        }
+      `);
+    });
+
+    it('when we export a service with hydrate enabled and message pointers use semver ranges, the ranges are resolved to concrete versions in the DSL output', async () => {
+      const sdk = createSDK(catalogPath);
+      await sdk.writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory adjusted',
+        version: '1.0.1',
+        summary: 'Indicates a change in inventory level',
+        markdown: '',
+      });
+      await sdk.writeEvent({
+        id: 'PaymentProcessed',
+        name: 'Payment Processed',
+        version: '1.0.0',
+        summary: 'Payment has been processed',
+        markdown: '',
+      });
+      await sdk.writeService({
+        id: 'NotificationService',
+        name: 'Notifications',
+        version: '0.0.2',
+        receives: [
+          { id: 'InventoryAdjusted', version: '>1.0.0' },
+          { id: 'PaymentProcessed', version: '^1.0.0' },
+        ],
+        markdown: '',
+      });
+
+      const result = await exportResource({
+        resource: 'service',
+        id: 'NotificationService',
+        hydrate: true,
+        stdout: true,
+        dir: catalogPath,
+      });
+
+      // Semver ranges should be resolved to concrete versions
+      expect(result).toContain('receives event InventoryAdjusted@1.0.1');
+      expect(result).not.toContain('>1.0.0');
+      expect(result).toContain('receives event PaymentProcessed@1.0.0');
+      expect(result).not.toContain('^1.0.0');
+      // Hydrated message definitions should have their summaries
+      expect(result).toContain('summary "Indicates a change in inventory level"');
+      expect(result).toContain('summary "Payment has been processed"');
+    });
+
+    it('when we export a service that does not exist, a not found error is returned with the requested service id', async () => {
+      await expect(
+        exportResource({
+          resource: 'service',
+          id: 'MissingService',
+          stdout: true,
+          dir: catalogPath,
+        })
+      ).rejects.toThrow(`service 'MissingService (latest)' not found in catalog at '${catalogPath}'`);
+    });
+  });
+});
diff --git a/packages/cli/src/test/import-export/stubs.test.ts b/packages/cli/src/test/import-export/stubs.test.ts
new file mode 100644
index 000000000..015c373c3
--- /dev/null
+++ b/packages/cli/src/test/import-export/stubs.test.ts
@@ -0,0 +1,265 @@
+import { describe, it, expect } from 'vitest';
+import { importDSL } from '../../cli/import';
+import createSDK from '@eventcatalog/sdk';
+import { createCatalogHelper } from './helpers';
+
+const { catalogPath, setup, writeEcFile } = createCatalogHelper('stubs');
+setup();
+
+describe('import message stubs', () => {
+  it('creates stub events for sends references without inline body', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service UserService {
+  version 1.0.0
+  name "User Service"
+  sends event UserCreated
+  sends event UserUpdated
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getService('UserService', '1.0.0')).toBeDefined();
+
+    const userCreated = await sdk.getEvent('UserCreated', '0.0.1');
+    const userUpdated = await sdk.getEvent('UserUpdated', '0.0.1');
+    expect(userCreated).toBeDefined();
+    expect(userCreated!.name).toBe('UserCreated');
+    expect(userCreated!.version).toBe('0.0.1');
+    expect(userUpdated).toBeDefined();
+    expect(userUpdated!.name).toBe('UserUpdated');
+    expect(userUpdated!.version).toBe('0.0.1');
+  });
+
+  it('creates stub commands and queries for receives references', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service UserService {
+  version 1.0.0
+  name "User Service"
+  receives command CreateUser
+  receives command UpdateUser
+  receives query GetUser
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+
+    const createUser = await sdk.getCommand('CreateUser', '0.0.1');
+    const updateUser = await sdk.getCommand('UpdateUser', '0.0.1');
+    const getUser = await sdk.getQuery('GetUser', '0.0.1');
+    expect(createUser).toBeDefined();
+    expect(createUser!.version).toBe('0.0.1');
+    expect(updateUser).toBeDefined();
+    expect(getUser).toBeDefined();
+  });
+
+  it('creates stubs for all message types in a full service', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `visualizer main {
+  service UserService {
+    version 1.0.0
+    summary "Manages user accounts"
+    sends event UserCreated
+    sends event UserUpdated
+    receives command CreateUser
+    receives command UpdateUser
+    receives query GetUser
+  }
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    // Service + 5 message stubs = 6 created
+    expect(result).toContain('Created 6 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getService('UserService', '1.0.0')).toBeDefined();
+    expect(await sdk.getEvent('UserCreated', '0.0.1')).toBeDefined();
+    expect(await sdk.getEvent('UserUpdated', '0.0.1')).toBeDefined();
+    expect(await sdk.getCommand('CreateUser', '0.0.1')).toBeDefined();
+    expect(await sdk.getCommand('UpdateUser', '0.0.1')).toBeDefined();
+    expect(await sdk.getQuery('GetUser', '0.0.1')).toBeDefined();
+  });
+
+  it('does not create stubs for messages that have inline definitions', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated {
+    version 2.0.0
+    name "Order Created"
+  }
+  sends event OrderShipped
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+
+    // OrderCreated has inline body -> compiled normally with version 2.0.0
+    const orderCreated = await sdk.getEvent('OrderCreated', '2.0.0');
+    expect(orderCreated).toBeDefined();
+    expect(orderCreated!.name).toBe('Order Created');
+
+    // OrderShipped has no body -> stub with 0.0.1
+    const orderShipped = await sdk.getEvent('OrderShipped', '0.0.1');
+    expect(orderShipped).toBeDefined();
+    expect(orderShipped!.version).toBe('0.0.1');
+  });
+
+  it('does not create stubs for messages already defined elsewhere in the DSL', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    // Should be 2: event + service. No stub needed.
+    expect(result).toContain('Created 2 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    const event = await sdk.getEvent('OrderCreated', '1.0.0');
+    expect(event).toBeDefined();
+    expect(event!.name).toBe('Order Created');
+
+    // Should NOT have a 0.0.1 stub
+    const stub = await sdk.getEvent('OrderCreated', '0.0.1');
+    expect(stub).toBeUndefined();
+  });
+
+  it('does not create duplicate stubs when multiple services reference the same message', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service ServiceA {
+  version 1.0.0
+  name "Service A"
+  sends event SharedEvent
+}
+
+service ServiceB {
+  version 1.0.0
+  name "Service B"
+  receives event SharedEvent
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    // 2 services + 1 stub event = 3
+    expect(result).toContain('Created 3 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getEvent('SharedEvent', '0.0.1')).toBeDefined();
+  });
+
+  it('uses explicit version from ref instead of 0.0.1 when provided', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@2.0.0
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+
+    const event = await sdk.getEvent('OrderCreated', '2.0.0');
+    expect(event).toBeDefined();
+    expect(event!.version).toBe('2.0.0');
+  });
+
+  it('creates a stub for a different explicit version even when another version is defined in DSL', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0
+  sends event OrderCreated@2.0.0
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+    expect(result).toContain('Created 3 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    expect(await sdk.getEvent('OrderCreated', '1.0.0')).toBeDefined();
+    expect(await sdk.getEvent('OrderCreated', '2.0.0')).toBeDefined();
+    expect(await sdk.getEvent('OrderCreated', '0.0.1')).toBeUndefined();
+  });
+
+  it('stubs are not created when message already exists in catalog', async () => {
+    const sdk = createSDK(catalogPath);
+    await sdk.writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: 'existing docs' });
+
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk2 = createSDK(catalogPath);
+
+    // The existing event should still be there, untouched (stub has different version 0.0.1)
+    const existing = await sdk2.getEvent('OrderCreated', '1.0.0');
+    expect(existing).toBeDefined();
+    expect(existing!.markdown).toBe('existing docs');
+  });
+
+  it('adds <NodeGraph /> to stub messages', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service UserService {
+  version 1.0.0
+  name "User Service"
+  sends event UserCreated
+  receives command CreateUser
+  receives query GetUser
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    const event = await sdk.getEvent('UserCreated', '0.0.1');
+    const command = await sdk.getCommand('CreateUser', '0.0.1');
+    const query = await sdk.getQuery('GetUser', '0.0.1');
+
+    expect(event!.markdown).toContain('<NodeGraph />');
+    expect(command!.markdown).toContain('<NodeGraph />');
+    expect(query!.markdown).toContain('<NodeGraph />');
+  });
+});
diff --git a/packages/cli/src/test/import-export/users-teams.test.ts b/packages/cli/src/test/import-export/users-teams.test.ts
new file mode 100644
index 000000000..2e2ed863b
--- /dev/null
+++ b/packages/cli/src/test/import-export/users-teams.test.ts
@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { importDSL } from '../../cli/import';
+import createSDK from '@eventcatalog/sdk';
+import { createCatalogHelper } from './helpers';
+
+const { catalogPath, setup, writeEcFile } = createCatalogHelper('users-teams');
+setup();
+
+describe('import users and teams', () => {
+  it('imports users and teams', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `user jdoe {
+  name "John Doe"
+  role "Engineer"
+  email "jdoe@example.com"
+}
+
+team platform {
+  name "Platform Team"
+  member jdoe
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    expect(result).toContain('Created 2 resource(s)');
+
+    const sdk = createSDK(catalogPath);
+    const user = await sdk.getUser('jdoe');
+    const team = await sdk.getTeam('platform');
+    expect(user).toBeDefined();
+    expect(team).toBeDefined();
+    expect(user!.name).toBe('John Doe');
+    expect(team!.name).toBe('Platform Team');
+  });
+
+  it('does not add <NodeGraph /> to users', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `user jdoe {
+  name "John Doe"
+  role "Engineer"
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    const user = await sdk.getUser('jdoe');
+    expect(user).toBeDefined();
+    expect(user!.markdown).not.toContain('<NodeGraph />');
+  });
+
+  it('does not add <NodeGraph /> to teams', async () => {
+    const ecFile = writeEcFile(
+      'test.ec',
+      `team platform {
+  name "Platform Team"
+}`
+    );
+
+    await importDSL({ files: [ecFile], dir: catalogPath });
+
+    const sdk = createSDK(catalogPath);
+    const team = await sdk.getTeam('platform');
+    expect(team).toBeDefined();
+    expect(team!.markdown).not.toContain('<NodeGraph />');
+  });
+});
diff --git a/packages/cli/src/test/import-export/versioning.test.ts b/packages/cli/src/test/import-export/versioning.test.ts
new file mode 100644
index 000000000..c6887c5e3
--- /dev/null
+++ b/packages/cli/src/test/import-export/versioning.test.ts
@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { importDSL } from '../../cli/import';
+import path from 'node:path';
+import fs from 'node:fs';
+import createSDK from '@eventcatalog/sdk';
+import { createCatalogHelper } from './helpers';
+
+const { catalogPath, setup, writeEcFile } = createCatalogHelper('versioning');
+setup();
+
+describe('import versioning', () => {
+  it('versions existing resource when importing a newer version', async () => {
+    const sdk = createSDK(catalogPath);
+    await sdk.writeService({ id: 'PaymentService', name: 'Payment Service', version: '1.0.0', markdown: 'v1 docs' });
+
+    expect(fs.existsSync(path.join(catalogPath, 'services/PaymentService/index.mdx'))).toBe(true);
+
+    const ecFile = writeEcFile(
+      'test.ec',
+      `service PaymentService {
+  version 2.0.0
+  name "Payment Service V2"
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    expect(result).toContain('Created 1 resource(s)');
+    expect(result).toContain('Versioned 1 existing resource(s)');
+    expect(result).toContain('PaymentService@1.0.0');
+
+    // v1 should now be in versioned/
+    expect(fs.existsSync(path.join(catalogPath, 'services/PaymentService/versioned/1.0.0/index.mdx'))).toBe(true);
+
+    // v2 should be at root
+    const sdk2 = createSDK(catalogPath);
+    const latest = await sdk2.getService('PaymentService');
+    expect(latest!.version).toBe('2.0.0');
+    expect(latest!.name).toBe('Payment Service V2');
+    expect(latest!.markdown).toContain('v1 docs');
+  });
+
+  it('overrides existing resource when same version already exists', async () => {
+    const sdk = createSDK(catalogPath);
+    await sdk.writeEvent({
+      id: 'OrderCreated',
+      name: 'Order Created',
+      version: '1.0.0',
+      summary: 'original summary',
+      markdown: 'original docs',
+    } as any);
+
+    const ecFile = writeEcFile(
+      'test.ec',
+      `event OrderCreated {
+  version 1.0.0
+  name "Order Created V2"
+}`
+    );
+
+    const result = await importDSL({ files: [ecFile], dir: catalogPath });
+
+    expect(result).toContain('Updated 1 resource(s)');
+
+    const sdk2 = createSDK(catalogPath);
+    const event = await sdk2.getEvent('OrderCreated', '1.0.0');
+    expect(event!.name).toBe('Order Created V2');
+    // summary NOT preserved — full override, not merge
+    expect((event as any).summary).toBeUndefined();
+  });
+});
diff --git a/packages/cli/tsconfig.json b/packages/cli/tsconfig.json
new file mode 100644
index 000000000..3ffa57bad
--- /dev/null
+++ b/packages/cli/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "es2016",
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true
+  }
+}
diff --git a/packages/cli/tsup.config.ts b/packages/cli/tsup.config.ts
new file mode 100644
index 000000000..968bd9054
--- /dev/null
+++ b/packages/cli/tsup.config.ts
@@ -0,0 +1,20 @@
+import { defineConfig } from 'tsup';
+import { copyFileSync } from 'node:fs';
+
+export default defineConfig({
+  target: 'es2020',
+  format: ['cjs', 'esm'],
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  dts: true,
+  entry: {
+    'cli/index': 'src/cli/index.ts',
+    'cli-docs': 'src/cli-docs.ts',
+  },
+  outDir: 'dist',
+  shims: true,
+  async onSuccess() {
+    copyFileSync('src/cli/logo.png', 'dist/cli/logo.png');
+  },
+});
diff --git a/packages/cli/vitest.config.ts b/packages/cli/vitest.config.ts
new file mode 100644
index 000000000..8099a3ba0
--- /dev/null
+++ b/packages/cli/vitest.config.ts
@@ -0,0 +1,9 @@
+/// <reference types="vitest" />
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    setupFiles: ['./vitest.setup.ts'],
+    testTimeout: 15_000,
+  },
+});
diff --git a/packages/cli/vitest.setup.ts b/packages/cli/vitest.setup.ts
new file mode 100644
index 000000000..7872b637d
--- /dev/null
+++ b/packages/cli/vitest.setup.ts
@@ -0,0 +1,70 @@
+import { expect } from 'vitest';
+
+interface CliCustomMatchers<R = unknown> {
+  toEqualDsl: (expected: string) => R;
+}
+
+declare module 'vitest' {
+  interface Assertion<T = any> extends CliCustomMatchers<T> {}
+  interface AsymmetricMatchersContaining extends CliCustomMatchers {}
+}
+
+declare global {
+  var dsl: (strings: TemplateStringsArray, ...values: unknown[]) => string;
+
+  namespace vitest {
+    interface Assertion<T> {
+      toEqualDsl(expected: string): T;
+    }
+  }
+}
+
+function dedentBlock(input: string): string {
+  const normalizedNewlines = input.replace(/\r\n/g, '\n');
+  const lines = normalizedNewlines.split('\n');
+
+  while (lines.length > 0 && lines[0].trim() === '') lines.shift();
+  while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop();
+
+  const nonEmptyLines = lines.filter((line) => line.trim().length > 0);
+  const indents = nonEmptyLines.map((line) => {
+    const match = line.match(/^[ \t]*/);
+    return match ? match[0].length : 0;
+  });
+  const minIndent = indents.length > 0 ? Math.min(...indents) : 0;
+
+  return lines
+    .map((line) => line.replace(new RegExp(`^[ \\t]{0,${minIndent}}`), ''))
+    .map((line) => line.replace(/[ \t]+$/g, ''))
+    .join('\n');
+}
+
+function dsl(strings: TemplateStringsArray, ...values: unknown[]): string {
+  const raw = String.raw({ raw: strings }, ...values);
+  return dedentBlock(raw);
+}
+
+globalThis.dsl = dsl;
+
+expect.extend({
+  toEqualDsl(received: unknown, expected: string) {
+    if (typeof received !== 'string') {
+      return {
+        pass: false,
+        message: () => `expected a string, but received ${typeof received}`,
+      };
+    }
+
+    const normalizedReceived = dedentBlock(received);
+    const normalizedExpected = dedentBlock(expected);
+    const pass = normalizedReceived === normalizedExpected;
+
+    return {
+      pass,
+      message: () =>
+        pass
+          ? `expected DSL not to be equal:\n${normalizedExpected}`
+          : `expected DSL to be equal.\n\nReceived:\n${normalizedReceived}\n\nExpected:\n${normalizedExpected}`,
+    };
+  },
+});
diff --git a/packages/connectors/CHANGELOG.md b/packages/connectors/CHANGELOG.md
new file mode 100644
index 000000000..b8ea9b9e5
--- /dev/null
+++ b/packages/connectors/CHANGELOG.md
@@ -0,0 +1,22 @@
+# @eventcatalog/connectors
+
+## 0.2.1
+
+### Patch Changes
+
+- a793c2e: Add support for external schema sources, including a new git schema source connector. Messages can now reference schemas by `ref` resolved through configurable schema sources, and the sidebar reflects the resolved schema format.
+
+## 0.2.0
+
+### Minor Changes
+
+- 3334ab1: Add Microsoft Entra directory connector for syncing users and teams from Microsoft Entra ID (Azure AD).
+  - `@eventcatalog/connectors`: new `microsoftEntraDirectory` connector export and docs
+  - `@eventcatalog/sdk`: `Team`/`User` source now supports an optional `id`, and `User.avatarUrl` is now optional
+  - `@eventcatalog/core`: render the Microsoft Entra directory source badge with an Azure icon
+
+## 0.1.0
+
+### Minor Changes
+
+- 6b7fc3c: Add directory connectors for syncing users and teams from external sources (e.g. GitHub organizations) into EventCatalog collections. Introduces the new `@eventcatalog/connectors` package and `directory.sources` configuration in `eventcatalog.config`.
diff --git a/packages/connectors/README.md b/packages/connectors/README.md
new file mode 100644
index 000000000..d9c9f35d4
--- /dev/null
+++ b/packages/connectors/README.md
@@ -0,0 +1,119 @@
+# @eventcatalog/connectors
+
+Connectors for syncing external systems into EventCatalog.
+
+## GitHub
+
+```js
+// eventcatalog.config.js
+import { githubDirectory } from "@eventcatalog/connectors";
+
+export default {
+  directory: {
+    sources: [
+      githubDirectory({
+        org: "acme",
+        teams: ["platform", "architecture"],
+        users: true,
+        token: process.env.GITHUB_TOKEN,
+      }),
+    ],
+  },
+};
+```
+
+## Microsoft Entra ID
+
+Sync selected Microsoft Entra ID groups into EventCatalog teams, and sync their
+direct user members into EventCatalog users.
+
+```js
+// eventcatalog.config.js
+import { microsoftEntraDirectory } from "@eventcatalog/connectors";
+
+export default {
+  directory: {
+    sources: [
+      microsoftEntraDirectory({
+        tenantId: process.env.AZURE_TENANT_ID,
+        clientId: process.env.AZURE_CLIENT_ID,
+        clientSecret: process.env.AZURE_CLIENT_SECRET,
+        groups: [
+          {
+            id: "00000000-0000-0000-0000-000000000000",
+            alias: "platform",
+          },
+          {
+            displayName: "Architecture Guild",
+          },
+        ],
+      }),
+    ],
+  },
+};
+```
+
+The connector uses Microsoft Graph with the OAuth client credentials flow.
+Create an app registration in Microsoft Entra ID, add read-only Microsoft Graph
+application permissions for reading groups, users, and group members, grant
+admin consent, then create a client secret for the build environment.
+
+Groups can be configured by stable `id` or exact `displayName`. Group IDs are
+recommended. If a `displayName` lookup finds no groups or multiple groups, the
+connector fails and asks you to use the group ID.
+
+Selected groups become EventCatalog teams. Team IDs use `alias` when provided,
+otherwise they are slugified from the Entra group display name. Only direct user
+members are synced. Disabled users are excluded by default; set
+`includeDisabledUsers: true` to include them.
+
+```js
+microsoftEntraDirectory({
+  tenantId: process.env.AZURE_TENANT_ID,
+  clientId: process.env.AZURE_CLIENT_ID,
+  clientSecret: process.env.AZURE_CLIENT_SECRET,
+  groups: [{ id: "00000000-0000-0000-0000-000000000000" }],
+  includeDisabledUsers: true,
+  graphBaseUrl: "https://graph.microsoft.com/v1.0",
+  tokenUrl: "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token",
+});
+```
+
+External directory sources require EventCatalog Scale when loaded by EventCatalog.
+
+Custom directory sources can use the same contract:
+
+```js
+import { defineDirectorySource } from "@eventcatalog/connectors";
+
+export const companyDirectory = defineDirectorySource({
+  type: "directory",
+  name: "company-directory",
+
+  async loadTeams() {
+    return [
+      {
+        id: "platform",
+        name: "Platform",
+        members: ["alice"],
+        source: {
+          provider: "company-directory",
+        },
+      },
+    ];
+  },
+
+  async loadUsers() {
+    return [
+      {
+        id: "alice",
+        name: "Alice",
+        avatarUrl: "https://example.com/alice.png",
+        source: {
+          provider: "company-directory",
+        },
+      },
+    ];
+  },
+});
+```
diff --git a/packages/connectors/package.json b/packages/connectors/package.json
new file mode 100644
index 000000000..86498de34
--- /dev/null
+++ b/packages/connectors/package.json
@@ -0,0 +1,52 @@
+{
+  "name": "@eventcatalog/connectors",
+  "version": "0.2.1",
+  "description": "Connectors for syncing external systems into EventCatalog Collections",
+  "scripts": {
+    "build": "tsup",
+    "build:bin": "tsup",
+    "test": "vitest --run",
+    "test:ci": "vitest --run",
+    "format": "prettier --write .",
+    "format:diff": "prettier --list-different ."
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "eventcatalog",
+    "connectors",
+    "github",
+    "directory"
+  ],
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "prettier": "^3.3.3",
+    "tsup": "^8.1.0",
+    "typescript": "^5.5.3",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/event-catalog/eventcatalog"
+  },
+  "dependencies": {
+    "simple-git": "^3.36.0"
+  }
+}
diff --git a/packages/connectors/src/git-schema-source.test.ts b/packages/connectors/src/git-schema-source.test.ts
new file mode 100644
index 000000000..440ef4ae3
--- /dev/null
+++ b/packages/connectors/src/git-schema-source.test.ts
@@ -0,0 +1,169 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { gitSchemaSource } from "./git-schema-source";
+
+const { cloneMock } = vi.hoisted(() => ({
+  cloneMock: vi.fn(),
+}));
+
+vi.mock("simple-git", () => ({
+  default: vi.fn(() => ({
+    clone: cloneMock,
+  })),
+}));
+
+describe("gitSchemaSource", () => {
+  beforeEach(() => {
+    cloneMock.mockReset();
+  });
+
+  it("resolves schemas from a configured git source", async () => {
+    cloneMock.mockImplementationOnce(async (_url: string, target: string) => {
+      const schemaDir = path.join(target, "schemas", "events");
+      await mkdir(schemaDir, { recursive: true });
+      await writeFile(
+        path.join(schemaDir, "OrderPlaced.schema.json"),
+        '{"type":"object"}',
+      );
+    });
+
+    const source = gitSchemaSource({
+      name: "contracts",
+      url: "https://github.com/acme/schema-contracts.git",
+      branch: "main",
+      directory: "schemas",
+      token: "github-token",
+    });
+
+    await expect(
+      source.resolve("git://contracts/events/OrderPlaced.schema.json"),
+    ).resolves.toEqual({
+      id: "git://contracts/events/OrderPlaced.schema.json",
+      name: "OrderPlaced.schema.json",
+      format: "jsonschema",
+      content: '{"type":"object"}',
+      source: {
+        provider: "git",
+        id: "contracts:events/OrderPlaced.schema.json",
+        url: "https://github.com/acme/schema-contracts.git",
+        branch: "main",
+        path: "schemas/events/OrderPlaced.schema.json",
+      },
+    });
+
+    expect(
+      source.canResolve("git://contracts/events/OrderPlaced.schema.json"),
+    ).toBe(true);
+    expect(
+      source.canResolve("git://other/events/OrderPlaced.schema.json"),
+    ).toBe(false);
+    expect(cloneMock).toHaveBeenCalledWith(
+      "https://github-token:x-oauth-basic@github.com/acme/schema-contracts.git",
+      expect.any(String),
+      {
+        "--branch": "main",
+        "--depth": 1,
+        "--single-branch": null,
+      },
+    );
+  });
+
+  it("reuses the checkout for multiple schema resolutions", async () => {
+    cloneMock.mockImplementationOnce(async (_url: string, target: string) => {
+      const schemaDir = path.join(target, "schemas", "events");
+      await mkdir(schemaDir, { recursive: true });
+      await writeFile(
+        path.join(schemaDir, "OrderPlaced.schema.json"),
+        '{"type":"object"}',
+      );
+      await writeFile(
+        path.join(schemaDir, "OrderCancelled.avsc"),
+        '{"type":"record"}',
+      );
+    });
+
+    const source = gitSchemaSource({
+      name: "contracts",
+      url: "https://github.com/acme/schema-contracts.git",
+      directory: "schemas",
+    });
+
+    await expect(
+      source.resolve("git://contracts/events/OrderPlaced.schema.json"),
+    ).resolves.toMatchObject({
+      format: "jsonschema",
+    });
+    await expect(
+      source.resolve("git://contracts/events/OrderCancelled.avsc"),
+    ).resolves.toMatchObject({
+      format: "avro",
+    });
+
+    expect(cloneMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("reports a clear error when the schema file does not exist in the checkout", async () => {
+    cloneMock.mockImplementationOnce(async (_url: string, target: string) => {
+      await mkdir(path.join(target, "schemas", "events"), { recursive: true });
+    });
+
+    const source = gitSchemaSource({
+      name: "contracts",
+      url: "https://github.com/acme/schema-contracts.git",
+      branch: "main",
+      directory: "schemas",
+    });
+
+    await expect(
+      source.resolve("git://contracts/events/Missing.schema.json"),
+    ).rejects.toThrow(
+      'Git schema source "contracts" could not find schema file "schemas/events/Missing.schema.json" in "https://github.com/acme/schema-contracts.git" on branch "main".',
+    );
+  });
+
+  it("requires a valid git schema ref", async () => {
+    const source = gitSchemaSource({
+      name: "contracts",
+      url: "https://github.com/acme/schema-contracts.git",
+    });
+
+    await expect(
+      source.resolve("github://contracts/events/OrderPlaced.schema.json"),
+    ).rejects.toThrow(
+      'Invalid git schema ref "github://contracts/events/OrderPlaced.schema.json". Expected git://<source-name>/<path>.',
+    );
+  });
+
+  it("prevents schema refs escaping the checked out source directory", async () => {
+    cloneMock.mockResolvedValueOnce(undefined);
+
+    const source = gitSchemaSource({
+      name: "contracts",
+      url: "https://github.com/acme/schema-contracts.git",
+      directory: "..",
+    });
+
+    await expect(
+      source.resolve("git://contracts/package.json"),
+    ).rejects.toThrow(
+      'Schema path "../package.json" resolves outside the git schema source directory.',
+    );
+  });
+
+  it("requires a source name and repository url", () => {
+    expect(() =>
+      gitSchemaSource({
+        name: "",
+        url: "https://github.com/acme/schema-contracts.git",
+      }),
+    ).toThrow("Git schema source requires a name.");
+
+    expect(() =>
+      gitSchemaSource({
+        name: "contracts",
+        url: "",
+      }),
+    ).toThrow("Git schema source requires a repository url.");
+  });
+});
diff --git a/packages/connectors/src/git-schema-source.ts b/packages/connectors/src/git-schema-source.ts
new file mode 100644
index 000000000..5a1b7f9e8
--- /dev/null
+++ b/packages/connectors/src/git-schema-source.ts
@@ -0,0 +1,185 @@
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import simpleGit from "simple-git";
+import {
+  defineSchemaSource,
+  type SchemaEntry,
+  type SchemaSource,
+} from "./types";
+
+type GitSchemaSourceOptions = {
+  /**
+   * Stable source name used in schema refs, for example:
+   * `git://contracts/events/OrderPlaced.schema.json`.
+   */
+  name: string;
+  /** Git repository URL. Supports any URL your local git can clone. */
+  url: string;
+  /** Branch to clone. */
+  branch?: string;
+  /** Optional directory inside the repository that contains schemas. */
+  directory?: string;
+  /** Optional HTTPS token. SSH auth is handled by the local git environment. */
+  token?: string;
+};
+
+const getSchemaFormat = (filePath: string) => {
+  const extension = path.extname(filePath).replace(".", "").toLowerCase();
+
+  if (extension === "avsc" || extension === "avro") return "avro";
+  if (extension === "proto") return "protobuf";
+  if (extension === "json") return "jsonschema";
+  if (extension === "yaml" || extension === "yml") return "yaml";
+
+  return extension || "unknown";
+};
+
+const parseGitSchemaRef = (ref: string) => {
+  let url: URL;
+
+  try {
+    url = new URL(ref);
+  } catch {
+    throw new Error(
+      `Invalid git schema ref "${ref}". Expected git://<source-name>/<path>.`,
+    );
+  }
+
+  if (url.protocol !== "git:") {
+    throw new Error(
+      `Invalid git schema ref "${ref}". Expected git://<source-name>/<path>.`,
+    );
+  }
+
+  const filePath = decodeURIComponent(url.pathname.replace(/^\//, ""));
+
+  if (!url.hostname || !filePath) {
+    throw new Error(
+      `Invalid git schema ref "${ref}". Expected git://<source-name>/<path>.`,
+    );
+  }
+
+  if (filePath.split(/[\\/]/).includes("..")) {
+    throw new Error(
+      `Schema path "${filePath}" resolves outside the git schema source directory.`,
+    );
+  }
+
+  return {
+    sourceName: url.hostname,
+    filePath,
+  };
+};
+
+const addTokenToHttpsUrl = (url: string, token?: string) => {
+  if (!token || !url.startsWith("https://")) return url;
+
+  const parsed = new URL(url);
+  parsed.username = token;
+  parsed.password = "x-oauth-basic";
+  return parsed.toString();
+};
+
+const resolveInside = (basePath: string, ...segments: string[]) => {
+  const base = path.resolve(basePath);
+  const resolved = path.resolve(base, ...segments);
+
+  if (resolved !== base && !resolved.startsWith(`${base}${path.sep}`)) {
+    throw new Error(
+      `Schema path "${segments.join("/")}" resolves outside the git schema source directory.`,
+    );
+  }
+
+  return resolved;
+};
+
+const isNodeFileNotFoundError = (
+  error: unknown,
+): error is NodeJS.ErrnoException => {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+};
+
+export const gitSchemaSource = (
+  options: GitSchemaSourceOptions,
+): SchemaSource => {
+  if (!options.name) {
+    throw new Error("Git schema source requires a name.");
+  }
+
+  if (!options.url) {
+    throw new Error("Git schema source requires a repository url.");
+  }
+
+  const branch = options.branch ?? "main";
+  const directory = options.directory ?? "";
+  let checkoutPath: Promise<string> | undefined;
+
+  const checkout = async () => {
+    checkoutPath =
+      checkoutPath ??
+      (async () => {
+        const target = await mkdtemp(
+          path.join(tmpdir(), "eventcatalog-schema-git-"),
+        );
+        await simpleGit().clone(
+          addTokenToHttpsUrl(options.url, options.token),
+          target,
+          {
+            "--branch": branch,
+            "--depth": 1,
+            "--single-branch": null,
+          },
+        );
+        return target;
+      })();
+
+    return checkoutPath;
+  };
+
+  return defineSchemaSource({
+    type: "schemas",
+    name: options.name,
+    canResolve: (id) => {
+      if (!id.startsWith("git://")) return false;
+      return parseGitSchemaRef(id).sourceName === options.name;
+    },
+    resolve: async (id): Promise<SchemaEntry | undefined> => {
+      const { sourceName, filePath } = parseGitSchemaRef(id);
+      if (sourceName !== options.name) return undefined;
+
+      const repositoryPath = await checkout();
+      const schemaPath = resolveInside(repositoryPath, directory, filePath);
+      let content: string;
+
+      try {
+        content = await readFile(schemaPath, "utf8");
+      } catch (error) {
+        if (isNodeFileNotFoundError(error)) {
+          const schemaSourcePath = [directory, filePath]
+            .filter(Boolean)
+            .join("/");
+          throw new Error(
+            `Git schema source "${options.name}" could not find schema file "${schemaSourcePath}" in "${options.url}" on branch "${branch}".`,
+          );
+        }
+
+        throw error;
+      }
+
+      return {
+        id,
+        name: path.basename(filePath),
+        format: getSchemaFormat(filePath),
+        content,
+        source: {
+          provider: "git",
+          id: `${options.name}:${filePath}`,
+          url: options.url,
+          branch,
+          path: [directory, filePath].filter(Boolean).join("/"),
+        },
+      };
+    },
+  });
+};
diff --git a/packages/connectors/src/github-directory.test.ts b/packages/connectors/src/github-directory.test.ts
new file mode 100644
index 000000000..0a78fe1a2
--- /dev/null
+++ b/packages/connectors/src/github-directory.test.ts
@@ -0,0 +1,269 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { githubDirectory } from "./github-directory";
+
+const fetchMock = vi.fn();
+
+describe("githubDirectory", () => {
+  beforeEach(() => {
+    fetchMock.mockReset();
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  it("loads configured teams and their members from a GitHub organization", async () => {
+    fetchMock
+      .mockResolvedValueOnce(
+        jsonResponse({
+          id: 123,
+          name: "Platform",
+          slug: "platform",
+          description: "Platform team",
+          html_url: "https://github.com/orgs/acme/teams/platform",
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse([
+          {
+            id: 456,
+            login: "jane",
+            avatar_url: "https://avatars.githubusercontent.com/u/456",
+            html_url: "https://github.com/jane",
+          },
+        ]),
+      );
+
+    const source = githubDirectory({
+      org: "acme",
+      token: "github-token",
+      teams: ["platform"],
+    });
+
+    await expect(source.loadTeams?.()).resolves.toEqual([
+      {
+        id: "platform",
+        name: "Platform",
+        summary: "Platform team",
+        members: ["jane"],
+        markdown: [
+          ":::note",
+          "This team is synced from GitHub and is read-only in EventCatalog.",
+          "",
+          "Manage the team and its members in GitHub.",
+          "",
+          "[View team on GitHub](https://github.com/orgs/acme/teams/platform)",
+          ":::",
+        ].join("\n"),
+        source: {
+          provider: "github",
+          id: "123",
+          url: "https://github.com/orgs/acme/teams/platform",
+        },
+      },
+    ]);
+    await expect(source.loadUsers?.()).resolves.toEqual([
+      {
+        id: "jane",
+        name: "jane",
+        avatarUrl: "https://avatars.githubusercontent.com/u/456",
+        markdown: [
+          ":::note",
+          "This user is synced from GitHub and is read-only in EventCatalog.",
+          "",
+          "Manage profile details and team membership in GitHub.",
+          "",
+          "[View user on GitHub](https://github.com/jane)",
+          ":::",
+        ].join("\n"),
+        source: {
+          provider: "github",
+          id: "456",
+          url: "https://github.com/jane",
+        },
+      },
+    ]);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      1,
+      "https://api.github.com/orgs/acme/teams/platform?per_page=100",
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          authorization: "Bearer github-token",
+          "x-github-api-version": "2022-11-28",
+        }),
+      }),
+    );
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      2,
+      "https://api.github.com/orgs/acme/teams/platform/members?per_page=100",
+      expect.any(Object),
+    );
+  });
+
+  it("loads only configured teams and avoids loading members when users are disabled", async () => {
+    fetchMock
+      .mockResolvedValueOnce(
+        jsonResponse({
+          id: 123,
+          name: "Platform",
+          slug: "platform",
+          description: null,
+          html_url: "https://github.com/orgs/acme/teams/platform",
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          id: 789,
+          name: "Product",
+          slug: "product",
+          description: null,
+          html_url: "https://github.com/orgs/acme/teams/product",
+        }),
+      );
+
+    const source = githubDirectory({
+      org: "acme",
+      teams: ["platform", "product"],
+      users: false,
+    });
+
+    await expect(source.loadTeams?.()).resolves.toEqual([
+      {
+        id: "platform",
+        name: "Platform",
+        summary: undefined,
+        markdown: [
+          ":::note",
+          "This team is synced from GitHub and is read-only in EventCatalog.",
+          "",
+          "Manage the team and its members in GitHub.",
+          "",
+          "[View team on GitHub](https://github.com/orgs/acme/teams/platform)",
+          ":::",
+        ].join("\n"),
+        source: {
+          provider: "github",
+          id: "123",
+          url: "https://github.com/orgs/acme/teams/platform",
+        },
+      },
+      {
+        id: "product",
+        name: "Product",
+        summary: undefined,
+        markdown: [
+          ":::note",
+          "This team is synced from GitHub and is read-only in EventCatalog.",
+          "",
+          "Manage the team and its members in GitHub.",
+          "",
+          "[View team on GitHub](https://github.com/orgs/acme/teams/product)",
+          ":::",
+        ].join("\n"),
+        source: {
+          provider: "github",
+          id: "789",
+          url: "https://github.com/orgs/acme/teams/product",
+        },
+      },
+    ]);
+    await expect(source.loadUsers?.()).resolves.toEqual([]);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      1,
+      "https://api.github.com/orgs/acme/teams/platform?per_page=100",
+      expect.any(Object),
+    );
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      2,
+      "https://api.github.com/orgs/acme/teams/product?per_page=100",
+      expect.any(Object),
+    );
+  });
+
+  it("follows GitHub pagination links for team members", async () => {
+    fetchMock
+      .mockResolvedValueOnce(
+        jsonResponse({
+          id: 123,
+          name: "Platform",
+          slug: "platform",
+          description: null,
+          html_url: "https://github.com/orgs/acme/teams/platform",
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(
+          [
+            {
+              id: 456,
+              login: "jane",
+              avatar_url: "https://avatars.githubusercontent.com/u/456",
+              html_url: "https://github.com/jane",
+            },
+          ],
+          {
+            link: '<https://api.github.com/orgs/acme/teams/platform/members?page=2&per_page=100>; rel="next"',
+          },
+        ),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse([
+          {
+            id: 789,
+            login: "john",
+            avatar_url: "https://avatars.githubusercontent.com/u/789",
+            html_url: "https://github.com/john",
+          },
+        ]),
+      );
+
+    const source = githubDirectory({
+      org: "acme",
+      teams: ["platform"],
+    });
+
+    await expect(source.loadUsers?.()).resolves.toHaveLength(2);
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      3,
+      "https://api.github.com/orgs/acme/teams/platform/members?page=2&per_page=100",
+      expect.any(Object),
+    );
+  });
+
+  it("requires explicit team slugs", () => {
+    expect(() =>
+      githubDirectory({
+        org: "acme",
+      } as never),
+    ).toThrow(
+      'GitHub directory connector requires at least one team slug. Set teams: ["platform"].',
+    );
+  });
+
+  it("throws with the GitHub response body when a request fails", async () => {
+    fetchMock.mockResolvedValueOnce(
+      new Response("Requires authentication", {
+        status: 401,
+        statusText: "Unauthorized",
+      }),
+    );
+
+    const source = githubDirectory({
+      org: "acme",
+      teams: ["platform"],
+      users: false,
+    });
+
+    await expect(source.loadTeams?.()).rejects.toThrow(
+      "GitHub directory connector failed (401 Unauthorized): Requires authentication",
+    );
+  });
+});
+
+const jsonResponse = (body: unknown, headers?: HeadersInit) =>
+  new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+      ...headers,
+    },
+  });
diff --git a/packages/connectors/src/github-directory.ts b/packages/connectors/src/github-directory.ts
new file mode 100644
index 000000000..97c055254
--- /dev/null
+++ b/packages/connectors/src/github-directory.ts
@@ -0,0 +1,243 @@
+import {
+  defineDirectorySource,
+  type DirectorySource,
+  type DirectoryTeam,
+  type DirectoryUser,
+} from "./types";
+
+type GitHubDirectoryOptions = {
+  org: string;
+  token?: string;
+  teams: string[];
+  users?: boolean;
+  baseUrl?: string;
+};
+
+type GitHubTeam = {
+  id: number;
+  name: string;
+  slug: string;
+  description: string | null;
+  html_url: string;
+};
+
+type GitHubUser = {
+  id: number;
+  login: string;
+  avatar_url: string;
+  html_url: string;
+};
+
+type GitHubDirectoryData = {
+  teams: DirectoryTeam[];
+  users: DirectoryUser[];
+};
+
+const GITHUB_API_VERSION = "2022-11-28";
+
+export const githubDirectory = (
+  options: GitHubDirectoryOptions,
+): DirectorySource => {
+  if (!Array.isArray(options.teams) || options.teams.length === 0) {
+    throw new Error(
+      'GitHub directory connector requires at least one team slug. Set teams: ["platform"].',
+    );
+  }
+
+  let cachedData: Promise<GitHubDirectoryData> | undefined;
+
+  const load = () => {
+    cachedData = cachedData ?? loadGitHubDirectory(options);
+    return cachedData;
+  };
+
+  return defineDirectorySource({
+    type: "directory",
+    name: `github:${options.org}`,
+    loadTeams: async () => {
+      const data = await load();
+      return data.teams;
+    },
+    loadUsers: async () => {
+      const data = await load();
+      return data.users;
+    },
+  });
+};
+
+const loadGitHubDirectory = async (
+  options: GitHubDirectoryOptions,
+): Promise<GitHubDirectoryData> => {
+  const teams = await loadGitHubTeams(options);
+  const shouldLoadUsers = options.users !== false;
+
+  if (!shouldLoadUsers) {
+    return { teams, users: [] };
+  }
+
+  const usersById = new Map<string, DirectoryUser>();
+  const teamsWithMembers: DirectoryTeam[] = [];
+
+  for (const team of teams) {
+    const members = await loadGitHubTeamMembers(options, team.id);
+
+    for (const member of members) {
+      usersById.set(member.id, member);
+    }
+
+    teamsWithMembers.push({
+      ...team,
+      members: members.map((member) => member.id),
+    });
+  }
+
+  return {
+    teams: teamsWithMembers,
+    users: Array.from(usersById.values()),
+  };
+};
+
+const loadGitHubTeams = async (
+  options: GitHubDirectoryOptions,
+): Promise<DirectoryTeam[]> => {
+  const teams: GitHubTeam[] = [];
+
+  for (const teamSlug of options.teams) {
+    teams.push(await loadGitHubTeam(options, teamSlug));
+  }
+
+  return teams.map((team) => ({
+    id: team.slug,
+    name: team.name,
+    summary: team.description ?? undefined,
+    markdown: createGitHubSyncedMarkdown("team", team.html_url),
+    source: {
+      provider: "github",
+      id: String(team.id),
+      url: team.html_url,
+    },
+  }));
+};
+
+const loadGitHubTeam = async (
+  options: GitHubDirectoryOptions,
+  teamSlug: string,
+) => {
+  const response = await githubRequest<GitHubTeam>(
+    options,
+    buildGitHubUrl(
+      options,
+      `/orgs/${encodeURIComponent(options.org)}/teams/${encodeURIComponent(teamSlug)}`,
+    ),
+  );
+
+  return response.data;
+};
+
+const loadGitHubTeamMembers = async (
+  options: GitHubDirectoryOptions,
+  teamSlug: string,
+): Promise<DirectoryUser[]> => {
+  const members = await paginate<GitHubUser>(
+    options,
+    `/orgs/${encodeURIComponent(options.org)}/teams/${encodeURIComponent(teamSlug)}/members`,
+  );
+
+  return members.map((member) => ({
+    id: member.login,
+    name: member.login,
+    avatarUrl: member.avatar_url,
+    markdown: createGitHubSyncedMarkdown("user", member.html_url),
+    source: {
+      provider: "github",
+      id: String(member.id),
+      url: member.html_url,
+    },
+  }));
+};
+
+const createGitHubSyncedMarkdown = (type: "team" | "user", url: string) => {
+  if (type === "team") {
+    return [
+      ":::note",
+      "This team is synced from GitHub and is read-only in EventCatalog.",
+      "",
+      "Manage the team and its members in GitHub.",
+      "",
+      `[View team on GitHub](${url})`,
+      ":::",
+    ].join("\n");
+  }
+
+  return [
+    ":::note",
+    "This user is synced from GitHub and is read-only in EventCatalog.",
+    "",
+    "Manage profile details and team membership in GitHub.",
+    "",
+    `[View user on GitHub](${url})`,
+    ":::",
+  ].join("\n");
+};
+
+const paginate = async <T>(
+  options: GitHubDirectoryOptions,
+  pathname: string,
+): Promise<T[]> => {
+  const results: T[] = [];
+  let url: string | undefined = buildGitHubUrl(options, pathname);
+
+  while (url) {
+    const response = await githubRequest<T[]>(options, url);
+    results.push(...response.data);
+    url = getNextPageUrl(response.headers.get("link"));
+  }
+
+  return results;
+};
+
+const githubRequest = async <T>(
+  options: GitHubDirectoryOptions,
+  url: string,
+): Promise<{ data: T; headers: Headers }> => {
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/vnd.github+json",
+      "x-github-api-version": GITHUB_API_VERSION,
+      "user-agent": "@eventcatalog/connectors",
+      ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+    },
+  });
+
+  if (!response.ok) {
+    const message = await response.text();
+    throw new Error(
+      `GitHub directory connector failed (${response.status} ${response.statusText}): ${message}`,
+    );
+  }
+
+  return {
+    data: (await response.json()) as T,
+    headers: response.headers,
+  };
+};
+
+const buildGitHubUrl = (options: GitHubDirectoryOptions, pathname: string) => {
+  const baseUrl = options.baseUrl ?? "https://api.github.com";
+  const normalizedBaseUrl = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  const normalizedPathname = pathname.replace(/^\//u, "");
+  const url = new URL(normalizedPathname, normalizedBaseUrl);
+  url.searchParams.set("per_page", "100");
+  return url.toString();
+};
+
+const getNextPageUrl = (linkHeader: string | null) => {
+  if (!linkHeader) return undefined;
+
+  const nextLink = linkHeader
+    .split(",")
+    .find((link) => link.includes('rel="next"'));
+  const match = nextLink?.match(/<([^>]+)>/);
+
+  return match?.[1];
+};
diff --git a/packages/connectors/src/index.ts b/packages/connectors/src/index.ts
new file mode 100644
index 000000000..62a281966
--- /dev/null
+++ b/packages/connectors/src/index.ts
@@ -0,0 +1,14 @@
+export { githubDirectory } from "./github-directory";
+export { microsoftEntraDirectory } from "./microsoft-entra-directory";
+export { gitSchemaSource } from "./git-schema-source";
+export { defineDirectorySource, defineSchemaSource } from "./types";
+export type {
+  DirectoryEntrySource,
+  DirectorySource,
+  DirectoryTeam,
+  DirectoryUser,
+  SchemaEntry,
+  SchemaEntrySource,
+  SchemaResolveContext,
+  SchemaSource,
+} from "./types";
diff --git a/packages/connectors/src/microsoft-entra-directory.test.ts b/packages/connectors/src/microsoft-entra-directory.test.ts
new file mode 100644
index 000000000..1aa015440
--- /dev/null
+++ b/packages/connectors/src/microsoft-entra-directory.test.ts
@@ -0,0 +1,485 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { microsoftEntraDirectory } from "./microsoft-entra-directory";
+
+const fetchMock = vi.fn();
+
+describe("microsoftEntraDirectory", () => {
+  beforeEach(() => {
+    fetchMock.mockReset();
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  it("loads configured groups and direct enabled members from Microsoft Entra ID", async () => {
+    fetchMock
+      .mockResolvedValueOnce(tokenResponse("graph-token"))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          id: "group-1",
+          displayName: "Platform Engineering",
+          description: "Platform team",
+          mail: "platform@example.com",
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          value: [
+            {
+              id: "user-1",
+              displayName: "Jane Doe",
+              userPrincipalName: "jane@example.com",
+              mail: "jane.doe@example.com",
+              jobTitle: "Staff Engineer",
+              accountEnabled: true,
+            },
+            {
+              id: "user-2",
+              displayName: "Disabled User",
+              userPrincipalName: "disabled@example.com",
+              mail: "disabled@example.com",
+              accountEnabled: false,
+            },
+          ],
+        }),
+      );
+
+    const source = microsoftEntraDirectory({
+      tenantId: "tenant-id",
+      clientId: "client-id",
+      clientSecret: "client-secret",
+      groups: [{ id: "group-1", alias: "platform" }],
+    });
+
+    await expect(source.loadTeams?.()).resolves.toEqual([
+      {
+        id: "platform",
+        name: "Platform Engineering",
+        summary: "Platform team",
+        email: "platform@example.com",
+        members: ["jane.doe@example.com"],
+        markdown: [
+          ":::note",
+          "This team is synced from Microsoft Entra ID and is read-only in EventCatalog.",
+          "",
+          "Manage the team and its members in Microsoft Entra ID.",
+          ":::",
+        ].join("\n"),
+        source: {
+          provider: "microsoft-entra",
+          id: "group-1",
+        },
+      },
+    ]);
+    await expect(source.loadUsers?.()).resolves.toEqual([
+      {
+        id: "jane.doe@example.com",
+        name: "Jane Doe",
+        email: "jane.doe@example.com",
+        role: "Staff Engineer",
+        markdown: [
+          ":::note",
+          "This user is synced from Microsoft Entra ID and is read-only in EventCatalog.",
+          "",
+          "Manage profile details and team membership in Microsoft Entra ID.",
+          ":::",
+        ].join("\n"),
+        source: {
+          provider: "microsoft-entra",
+          id: "user-1",
+        },
+      },
+    ]);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      1,
+      "https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          "content-type": "application/x-www-form-urlencoded",
+        }),
+      }),
+    );
+    expect(String(fetchMock.mock.calls[0][1].body)).toBe(
+      "client_id=client-id&client_secret=client-secret&grant_type=client_credentials&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default",
+    );
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      2,
+      "https://graph.microsoft.com/v1.0/groups/group-1?%24select=id%2CdisplayName%2Cdescription%2Cmail",
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          authorization: "Bearer graph-token",
+        }),
+      }),
+    );
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      3,
+      "https://graph.microsoft.com/v1.0/groups/group-1/members/microsoft.graph.user?%24select=id%2CdisplayName%2CuserPrincipalName%2Cmail%2CjobTitle%2CaccountEnabled",
+      expect.any(Object),
+    );
+  });
+
+  it("resolves groups by exact displayName and slugifies team ids when no alias is provided", async () => {
+    fetchMock
+      .mockResolvedValueOnce(tokenResponse("graph-token"))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          value: [
+            {
+              id: "group-1",
+              displayName: "Architecture Guild",
+              description: null,
+              mail: null,
+            },
+          ],
+        }),
+      );
+
+    const source = microsoftEntraDirectory({
+      tenantId: "tenant-id",
+      clientId: "client-id",
+      clientSecret: "client-secret",
+      groups: [{ displayName: "Architecture Guild" }],
+      users: false,
+    });
+
+    await expect(source.loadTeams?.()).resolves.toMatchObject([
+      {
+        id: "architecture-guild",
+        name: "Architecture Guild",
+        source: {
+          provider: "microsoft-entra",
+          id: "group-1",
+        },
+      },
+    ]);
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      2,
+      "https://graph.microsoft.com/v1.0/groups?%24filter=displayName+eq+%27Architecture+Guild%27&%24select=id%2CdisplayName%2Cdescription%2Cmail",
+      expect.any(Object),
+    );
+  });
+
+  it("includes disabled users when includeDisabledUsers is enabled", async () => {
+    fetchMock
+      .mockResolvedValueOnce(tokenResponse("graph-token"))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          id: "group-1",
+          displayName: "Platform",
+          description: null,
+          mail: null,
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          value: [
+            {
+              id: "user-1",
+              displayName: "Disabled User",
+              userPrincipalName: "disabled@example.com",
+              accountEnabled: false,
+            },
+          ],
+        }),
+      );
+
+    const source = microsoftEntraDirectory({
+      tenantId: "tenant-id",
+      clientId: "client-id",
+      clientSecret: "client-secret",
+      groups: ["group-1"],
+      includeDisabledUsers: true,
+    });
+
+    await expect(source.loadUsers?.()).resolves.toMatchObject([
+      {
+        id: "disabled@example.com",
+        source: {
+          id: "user-1",
+        },
+      },
+    ]);
+  });
+
+  it("normalizes guest user principal names when no mail address is available", async () => {
+    fetchMock
+      .mockResolvedValueOnce(tokenResponse("graph-token"))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          id: "group-1",
+          displayName: "Platform",
+          description: null,
+          mail: null,
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          value: [
+            {
+              id: "user-1",
+              displayName: "Dave",
+              userPrincipalName:
+                "dave_eventcatalog.dev#EXT#@daveeventcatalog.onmicrosoft.com",
+              mail: null,
+              accountEnabled: true,
+            },
+          ],
+        }),
+      );
+
+    const source = microsoftEntraDirectory({
+      tenantId: "tenant-id",
+      clientId: "client-id",
+      clientSecret: "client-secret",
+      groups: ["group-1"],
+    });
+
+    await expect(source.loadTeams?.()).resolves.toMatchObject([
+      {
+        members: ["dave@eventcatalog.dev"],
+      },
+    ]);
+    await expect(source.loadUsers?.()).resolves.toMatchObject([
+      {
+        id: "dave@eventcatalog.dev",
+        email: "dave_eventcatalog.dev#EXT#@daveeventcatalog.onmicrosoft.com",
+        source: {
+          id: "user-1",
+        },
+      },
+    ]);
+  });
+
+  it("follows Microsoft Graph pagination links for group members", async () => {
+    fetchMock
+      .mockResolvedValueOnce(tokenResponse("graph-token"))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          id: "group-1",
+          displayName: "Platform",
+          description: null,
+          mail: null,
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          value: [
+            {
+              id: "user-1",
+              displayName: "Jane Doe",
+              userPrincipalName: "jane@example.com",
+              accountEnabled: true,
+            },
+          ],
+          "@odata.nextLink":
+            "https://graph.microsoft.com/v1.0/groups/group-1/members/microsoft.graph.user?$skiptoken=next",
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          value: [
+            {
+              id: "user-2",
+              displayName: "John Doe",
+              userPrincipalName: "john@example.com",
+              accountEnabled: true,
+            },
+          ],
+        }),
+      );
+
+    const source = microsoftEntraDirectory({
+      tenantId: "tenant-id",
+      clientId: "client-id",
+      clientSecret: "client-secret",
+      groups: ["group-1"],
+    });
+
+    await expect(source.loadUsers?.()).resolves.toHaveLength(2);
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      4,
+      "https://graph.microsoft.com/v1.0/groups/group-1/members/microsoft.graph.user?$skiptoken=next",
+      expect.any(Object),
+    );
+  });
+
+  it("retries Microsoft Graph 429 responses before failing or returning data", async () => {
+    fetchMock
+      .mockResolvedValueOnce(tokenResponse("graph-token"))
+      .mockResolvedValueOnce(
+        new Response("Too many requests", {
+          status: 429,
+          statusText: "Too Many Requests",
+          headers: {
+            "retry-after": "0",
+          },
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          id: "group-1",
+          displayName: "Platform",
+          description: null,
+          mail: null,
+        }),
+      );
+
+    const source = microsoftEntraDirectory({
+      tenantId: "tenant-id",
+      clientId: "client-id",
+      clientSecret: "client-secret",
+      groups: ["group-1"],
+      users: false,
+    });
+
+    await expect(source.loadTeams?.()).resolves.toMatchObject([
+      {
+        id: "platform",
+      },
+    ]);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+  });
+
+  it("throws when a displayName lookup is missing or ambiguous", async () => {
+    fetchMock
+      .mockResolvedValueOnce(tokenResponse("graph-token"))
+      .mockResolvedValueOnce(jsonResponse({ value: [] }));
+
+    const missingSource = microsoftEntraDirectory({
+      tenantId: "tenant-id",
+      clientId: "client-id",
+      clientSecret: "client-secret",
+      groups: [{ displayName: "Missing Group" }],
+      users: false,
+    });
+
+    await expect(missingSource.loadTeams?.()).rejects.toThrow(
+      'Microsoft Entra directory connector could not find a group with displayName "Missing Group". Use the group id instead.',
+    );
+
+    fetchMock.mockReset();
+    fetchMock
+      .mockResolvedValueOnce(tokenResponse("graph-token"))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          value: [
+            { id: "group-1", displayName: "Platform" },
+            { id: "group-2", displayName: "Platform" },
+          ],
+        }),
+      );
+
+    const ambiguousSource = microsoftEntraDirectory({
+      tenantId: "tenant-id",
+      clientId: "client-id",
+      clientSecret: "client-secret",
+      groups: [{ displayName: "Platform" }],
+      users: false,
+    });
+
+    await expect(ambiguousSource.loadTeams?.()).rejects.toThrow(
+      'Microsoft Entra directory connector found 2 groups with displayName "Platform". Use the group id instead.',
+    );
+  });
+
+  it("throws when configured groups resolve to duplicate EventCatalog team ids", async () => {
+    fetchMock
+      .mockResolvedValueOnce(tokenResponse("graph-token"))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          id: "group-1",
+          displayName: "Platform Engineering",
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          id: "group-2",
+          displayName: "Platform-Engineering",
+        }),
+      );
+
+    const source = microsoftEntraDirectory({
+      tenantId: "tenant-id",
+      clientId: "client-id",
+      clientSecret: "client-secret",
+      groups: ["group-1", "group-2"],
+      users: false,
+    });
+
+    await expect(source.loadTeams?.()).rejects.toThrow(
+      'Microsoft Entra directory connector resolved duplicate team id "platform-engineering" from groups "group-1" and "group-2". Set alias for one of the groups.',
+    );
+  });
+
+  it("throws when required options are missing", () => {
+    expect(() =>
+      microsoftEntraDirectory({
+        tenantId: "tenant-id",
+        clientId: "client-id",
+        clientSecret: "client-secret",
+      } as never),
+    ).toThrow(
+      'Microsoft Entra directory connector requires at least one group. Set groups: [{ id: "00000000-0000-0000-0000-000000000000" }].',
+    );
+  });
+
+  it("throws with the Microsoft Graph response body when a request fails", async () => {
+    fetchMock
+      .mockResolvedValueOnce(tokenResponse("graph-token"))
+      .mockResolvedValueOnce(
+        new Response("Insufficient privileges", {
+          status: 403,
+          statusText: "Forbidden",
+        }),
+      );
+
+    const source = microsoftEntraDirectory({
+      tenantId: "tenant-id",
+      clientId: "client-id",
+      clientSecret: "client-secret",
+      groups: ["group-1"],
+      users: false,
+    });
+
+    await expect(source.loadTeams?.()).rejects.toThrow(
+      "Microsoft Entra directory connector failed (403 Forbidden): Insufficient privileges",
+    );
+  });
+
+  it("throws with the token response body when authentication fails", async () => {
+    fetchMock.mockResolvedValueOnce(
+      new Response("invalid_client", {
+        status: 401,
+        statusText: "Unauthorized",
+      }),
+    );
+
+    const source = microsoftEntraDirectory({
+      tenantId: "tenant-id",
+      clientId: "client-id",
+      clientSecret: "client-secret",
+      groups: ["group-1"],
+      users: false,
+    });
+
+    await expect(source.loadTeams?.()).rejects.toThrow(
+      "Microsoft Entra directory connector failed to get an access token (401 Unauthorized): invalid_client",
+    );
+  });
+});
+
+const tokenResponse = (token: string) =>
+  jsonResponse({
+    token_type: "Bearer",
+    expires_in: 3599,
+    access_token: token,
+  });
+
+const jsonResponse = (body: unknown, headers?: HeadersInit) =>
+  new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+      ...headers,
+    },
+  });
diff --git a/packages/connectors/src/microsoft-entra-directory.ts b/packages/connectors/src/microsoft-entra-directory.ts
new file mode 100644
index 000000000..899849e0d
--- /dev/null
+++ b/packages/connectors/src/microsoft-entra-directory.ts
@@ -0,0 +1,486 @@
+import {
+  defineDirectorySource,
+  type DirectorySource,
+  type DirectoryTeam,
+  type DirectoryUser,
+} from "./types";
+
+type MicrosoftEntraGroupInput =
+  | string
+  | {
+      id: string;
+      alias?: string;
+    }
+  | {
+      displayName: string;
+      alias?: string;
+    };
+
+type MicrosoftEntraDirectoryOptions = {
+  tenantId: string;
+  clientId: string;
+  clientSecret: string;
+  groups: MicrosoftEntraGroupInput[];
+  users?: boolean;
+  includeDisabledUsers?: boolean;
+  graphBaseUrl?: string;
+  tokenUrl?: string;
+};
+
+type MicrosoftEntraGroup = {
+  id: string;
+  displayName?: string | null;
+  description?: string | null;
+  mail?: string | null;
+};
+
+type MicrosoftEntraUser = {
+  id: string;
+  displayName?: string | null;
+  userPrincipalName?: string | null;
+  mail?: string | null;
+  jobTitle?: string | null;
+  accountEnabled?: boolean | null;
+};
+
+type MicrosoftEntraDirectoryData = {
+  teams: DirectoryTeam[];
+  users: DirectoryUser[];
+};
+
+type MicrosoftGraphCollection<T> = {
+  value?: T[];
+  "@odata.nextLink"?: string;
+};
+
+type ResolvedGroupInput = {
+  group: MicrosoftEntraGroup;
+  alias?: string;
+};
+
+const DEFAULT_GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0";
+const GRAPH_RETRY_ATTEMPTS = 3;
+const GRAPH_SELECT_GROUP = "id,displayName,description,mail";
+const GRAPH_SELECT_USER =
+  "id,displayName,userPrincipalName,mail,jobTitle,accountEnabled";
+
+export const microsoftEntraDirectory = (
+  options: MicrosoftEntraDirectoryOptions,
+): DirectorySource => {
+  validateOptions(options);
+
+  let cachedData: Promise<MicrosoftEntraDirectoryData> | undefined;
+
+  const load = () => {
+    cachedData = cachedData ?? loadMicrosoftEntraDirectory(options);
+    return cachedData;
+  };
+
+  return defineDirectorySource({
+    type: "directory",
+    name: `microsoft-entra:${options.tenantId}`,
+    loadTeams: async () => {
+      const data = await load();
+      return data.teams;
+    },
+    loadUsers: async () => {
+      const data = await load();
+      return data.users;
+    },
+  });
+};
+
+const validateOptions = (options: MicrosoftEntraDirectoryOptions) => {
+  if (!options.tenantId) {
+    throw new Error("Microsoft Entra directory connector requires tenantId.");
+  }
+  if (!options.clientId) {
+    throw new Error("Microsoft Entra directory connector requires clientId.");
+  }
+  if (!options.clientSecret) {
+    throw new Error(
+      "Microsoft Entra directory connector requires clientSecret.",
+    );
+  }
+  if (!Array.isArray(options.groups) || options.groups.length === 0) {
+    throw new Error(
+      'Microsoft Entra directory connector requires at least one group. Set groups: [{ id: "00000000-0000-0000-0000-000000000000" }].',
+    );
+  }
+};
+
+const loadMicrosoftEntraDirectory = async (
+  options: MicrosoftEntraDirectoryOptions,
+): Promise<MicrosoftEntraDirectoryData> => {
+  const token = await getAccessToken(options);
+  const resolvedGroups = await loadMicrosoftEntraGroups(options, token);
+  const teams = mapMicrosoftEntraTeams(resolvedGroups);
+  const shouldLoadUsers = options.users !== false;
+
+  if (!shouldLoadUsers) {
+    return { teams, users: [] };
+  }
+
+  const usersById = new Map<string, DirectoryUser>();
+  const teamsWithMembers: DirectoryTeam[] = [];
+
+  for (const team of teams) {
+    const members = await loadMicrosoftEntraGroupMembers(
+      options,
+      token,
+      String(team.source?.id ?? team.id),
+    );
+
+    for (const member of members) {
+      usersById.set(member.id, member);
+    }
+
+    teamsWithMembers.push({
+      ...team,
+      members: members.map((member) => member.id),
+    });
+  }
+
+  return {
+    teams: teamsWithMembers,
+    users: Array.from(usersById.values()),
+  };
+};
+
+const loadMicrosoftEntraGroups = async (
+  options: MicrosoftEntraDirectoryOptions,
+  token: string,
+): Promise<ResolvedGroupInput[]> => {
+  const resolvedGroups: ResolvedGroupInput[] = [];
+
+  for (const groupInput of options.groups) {
+    resolvedGroups.push(
+      await resolveMicrosoftEntraGroup(options, token, groupInput),
+    );
+  }
+
+  assertUniqueTeamIds(resolvedGroups);
+
+  return resolvedGroups;
+};
+
+const resolveMicrosoftEntraGroup = async (
+  options: MicrosoftEntraDirectoryOptions,
+  token: string,
+  groupInput: MicrosoftEntraGroupInput,
+): Promise<ResolvedGroupInput> => {
+  if (typeof groupInput === "string") {
+    return {
+      group: await loadMicrosoftEntraGroupById(options, token, groupInput),
+    };
+  }
+
+  if ("id" in groupInput) {
+    return {
+      group: await loadMicrosoftEntraGroupById(options, token, groupInput.id),
+      alias: groupInput.alias,
+    };
+  }
+
+  return {
+    group: await loadMicrosoftEntraGroupByDisplayName(
+      options,
+      token,
+      groupInput.displayName,
+    ),
+    alias: groupInput.alias,
+  };
+};
+
+const loadMicrosoftEntraGroupById = async (
+  options: MicrosoftEntraDirectoryOptions,
+  token: string,
+  groupId: string,
+) => {
+  return microsoftGraphRequest<MicrosoftEntraGroup>(
+    options,
+    token,
+    buildMicrosoftGraphUrl(options, `/groups/${encodeURIComponent(groupId)}`, {
+      $select: GRAPH_SELECT_GROUP,
+    }),
+  );
+};
+
+const loadMicrosoftEntraGroupByDisplayName = async (
+  options: MicrosoftEntraDirectoryOptions,
+  token: string,
+  displayName: string,
+) => {
+  const groups = await paginate<MicrosoftEntraGroup>(
+    options,
+    token,
+    buildMicrosoftGraphUrl(options, "/groups", {
+      $filter: `displayName eq '${escapeODataString(displayName)}'`,
+      $select: GRAPH_SELECT_GROUP,
+    }),
+  );
+
+  if (groups.length === 0) {
+    throw new Error(
+      `Microsoft Entra directory connector could not find a group with displayName "${displayName}". Use the group id instead.`,
+    );
+  }
+
+  if (groups.length > 1) {
+    throw new Error(
+      `Microsoft Entra directory connector found ${groups.length} groups with displayName "${displayName}". Use the group id instead.`,
+    );
+  }
+
+  return groups[0];
+};
+
+const mapMicrosoftEntraTeams = (groups: ResolvedGroupInput[]) => {
+  return groups.map(({ group, alias }) => {
+    const displayName = group.displayName ?? group.id;
+
+    return {
+      id: alias ?? slugify(displayName),
+      name: displayName,
+      summary: group.description ?? undefined,
+      email: group.mail ?? undefined,
+      markdown: createMicrosoftEntraSyncedMarkdown("team"),
+      source: {
+        provider: "microsoft-entra",
+        id: group.id,
+      },
+    };
+  });
+};
+
+const loadMicrosoftEntraGroupMembers = async (
+  options: MicrosoftEntraDirectoryOptions,
+  token: string,
+  groupId: string,
+): Promise<DirectoryUser[]> => {
+  const users = await paginate<MicrosoftEntraUser>(
+    options,
+    token,
+    buildMicrosoftGraphUrl(
+      options,
+      `/groups/${encodeURIComponent(groupId)}/members/microsoft.graph.user`,
+      {
+        $select: GRAPH_SELECT_USER,
+      },
+    ),
+  );
+
+  return users
+    .filter(
+      (user) => options.includeDisabledUsers || user.accountEnabled !== false,
+    )
+    .map(mapMicrosoftEntraUser);
+};
+
+const mapMicrosoftEntraUser = (user: MicrosoftEntraUser): DirectoryUser => {
+  const userPrincipalName = user.userPrincipalName ?? undefined;
+  const email = user.mail ?? userPrincipalName;
+  const id = getMicrosoftEntraUserId(user);
+  const name = user.displayName ?? userPrincipalName ?? user.id;
+
+  return {
+    id,
+    name,
+    email,
+    role: user.jobTitle ?? undefined,
+    markdown: createMicrosoftEntraSyncedMarkdown("user"),
+    source: {
+      provider: "microsoft-entra",
+      id: user.id,
+    },
+  };
+};
+
+const getMicrosoftEntraUserId = (user: MicrosoftEntraUser) => {
+  if (user.mail) return user.mail.toLowerCase();
+  if (user.userPrincipalName)
+    return normalizeMicrosoftEntraUserPrincipalName(user.userPrincipalName);
+  return user.id;
+};
+
+const normalizeMicrosoftEntraUserPrincipalName = (
+  userPrincipalName: string,
+) => {
+  const guestUserMatch = userPrincipalName.match(/^(.+)#EXT#@.+$/i);
+
+  if (!guestUserMatch) return userPrincipalName.toLowerCase();
+
+  const externalUserName = guestUserMatch[1];
+  const lastUnderscoreIndex = externalUserName.lastIndexOf("_");
+
+  if (lastUnderscoreIndex === -1) return externalUserName.toLowerCase();
+
+  return `${externalUserName.slice(0, lastUnderscoreIndex)}@${externalUserName.slice(lastUnderscoreIndex + 1)}`.toLowerCase();
+};
+
+const createMicrosoftEntraSyncedMarkdown = (type: "team" | "user") => {
+  if (type === "team") {
+    return [
+      ":::note",
+      "This team is synced from Microsoft Entra ID and is read-only in EventCatalog.",
+      "",
+      "Manage the team and its members in Microsoft Entra ID.",
+      ":::",
+    ].join("\n");
+  }
+
+  return [
+    ":::note",
+    "This user is synced from Microsoft Entra ID and is read-only in EventCatalog.",
+    "",
+    "Manage profile details and team membership in Microsoft Entra ID.",
+    ":::",
+  ].join("\n");
+};
+
+const getAccessToken = async (options: MicrosoftEntraDirectoryOptions) => {
+  const tokenUrl =
+    options.tokenUrl ??
+    `https://login.microsoftonline.com/${encodeURIComponent(options.tenantId)}/oauth2/v2.0/token`;
+  const body = new URLSearchParams({
+    client_id: options.clientId,
+    client_secret: options.clientSecret,
+    grant_type: "client_credentials",
+    scope: getMicrosoftGraphScope(options),
+  });
+
+  const response = await fetch(tokenUrl, {
+    method: "POST",
+    headers: {
+      "content-type": "application/x-www-form-urlencoded",
+      "user-agent": "@eventcatalog/connectors",
+    },
+    body,
+  });
+
+  if (!response.ok) {
+    const message = await response.text();
+    throw new Error(
+      `Microsoft Entra directory connector failed to get an access token (${response.status} ${response.statusText}): ${message}`,
+    );
+  }
+
+  const data = (await response.json()) as { access_token?: string };
+  if (!data.access_token) {
+    throw new Error(
+      "Microsoft Entra directory connector failed to get an access token: response did not include access_token.",
+    );
+  }
+
+  return data.access_token;
+};
+
+const getMicrosoftGraphScope = (options: MicrosoftEntraDirectoryOptions) => {
+  const graphBaseUrl = options.graphBaseUrl ?? DEFAULT_GRAPH_BASE_URL;
+  return `${new URL(graphBaseUrl).origin}/.default`;
+};
+
+const microsoftGraphRequest = async <T>(
+  options: MicrosoftEntraDirectoryOptions,
+  token: string,
+  url: string,
+  attempt = 0,
+): Promise<T> => {
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${token}`,
+      ConsistencyLevel: "eventual",
+      "user-agent": "@eventcatalog/connectors",
+    },
+  });
+
+  if (response.status === 429 && attempt < GRAPH_RETRY_ATTEMPTS) {
+    await waitForRetry(response.headers.get("retry-after"));
+    return microsoftGraphRequest(options, token, url, attempt + 1);
+  }
+
+  if (!response.ok) {
+    const message = await response.text();
+    throw new Error(
+      `Microsoft Entra directory connector failed (${response.status} ${response.statusText}): ${message}`,
+    );
+  }
+
+  return (await response.json()) as T;
+};
+
+const paginate = async <T>(
+  options: MicrosoftEntraDirectoryOptions,
+  token: string,
+  url: string,
+): Promise<T[]> => {
+  const results: T[] = [];
+  let nextUrl: string | undefined = url;
+
+  while (nextUrl) {
+    const response: MicrosoftGraphCollection<T> = await microsoftGraphRequest<
+      MicrosoftGraphCollection<T>
+    >(options, token, nextUrl);
+    results.push(...(response.value ?? []));
+    nextUrl = response["@odata.nextLink"];
+  }
+
+  return results;
+};
+
+const buildMicrosoftGraphUrl = (
+  options: MicrosoftEntraDirectoryOptions,
+  pathname: string,
+  query?: Record<string, string>,
+) => {
+  const baseUrl = options.graphBaseUrl ?? DEFAULT_GRAPH_BASE_URL;
+  const normalizedBaseUrl = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  const normalizedPathname = pathname.replace(/^\//u, "");
+  const url = new URL(normalizedPathname, normalizedBaseUrl);
+
+  for (const [key, value] of Object.entries(query ?? {})) {
+    url.searchParams.set(key, value);
+  }
+
+  return url.toString();
+};
+
+const assertUniqueTeamIds = (groups: ResolvedGroupInput[]) => {
+  const teamIds = new Map<string, string>();
+
+  for (const { group, alias } of groups) {
+    const displayName = group.displayName ?? group.id;
+    const teamId = alias ?? slugify(displayName);
+    const existingGroupId = teamIds.get(teamId);
+
+    if (existingGroupId) {
+      throw new Error(
+        `Microsoft Entra directory connector resolved duplicate team id "${teamId}" from groups "${existingGroupId}" and "${group.id}". Set alias for one of the groups.`,
+      );
+    }
+
+    teamIds.set(teamId, group.id);
+  }
+};
+
+const slugify = (value: string) => {
+  const slug = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return slug || value;
+};
+
+const escapeODataString = (value: string) => value.replace(/'/g, "''");
+
+const waitForRetry = async (retryAfter: string | null) => {
+  const retryAfterSeconds = retryAfter ? Number(retryAfter) : 1;
+  const delayMs = Number.isFinite(retryAfterSeconds)
+    ? Math.max(retryAfterSeconds, 0) * 1000
+    : 1000;
+
+  await new Promise((resolve) => setTimeout(resolve, delayMs));
+};
diff --git a/packages/connectors/src/types.ts b/packages/connectors/src/types.ts
new file mode 100644
index 000000000..7f58e479c
--- /dev/null
+++ b/packages/connectors/src/types.ts
@@ -0,0 +1,134 @@
+/**
+ * Describes where a generated directory entry came from.
+ *
+ * EventCatalog uses the provider to show source badges and to treat generated
+ * resources as externally managed.
+ */
+export type DirectoryEntrySource = {
+  /** Provider identifier, for example `github`, `okta`, or `ldap`. */
+  provider: string;
+  /** Optional provider-specific identifier for the external resource. */
+  id?: string;
+  /** Optional URL back to the resource in the external provider. */
+  url?: string;
+  [key: string]: unknown;
+};
+
+/**
+ * User returned by a directory source.
+ *
+ * Directory users are synced as read-only EventCatalog users and can be
+ * referenced by teams through their `id`.
+ */
+export type DirectoryUser = {
+  id: string;
+  name: string;
+  avatarUrl?: string;
+  role?: string;
+  email?: string;
+  markdown?: string;
+  source?: DirectoryEntrySource;
+  [key: string]: unknown;
+};
+
+/**
+ * Team returned by a directory source.
+ *
+ * Directory teams are synced as read-only EventCatalog teams.
+ */
+export type DirectoryTeam = {
+  id: string;
+  name: string;
+  summary?: string;
+  /** User IDs for members of this team. */
+  members?: string[];
+  email?: string;
+  markdown?: string;
+  source?: DirectoryEntrySource;
+  [key: string]: unknown;
+};
+
+/**
+ * Loads users and/or teams from an external directory provider.
+ *
+ * EventCatalog calls these loaders during content sync, writes the returned
+ * entries into Astro collections, and mirrors them into the generated
+ * `.eventcatalog/store/directory.json` file for SDK/editor reads.
+ */
+export type DirectorySource = {
+  type: "directory";
+  /** Stable source identifier, usually `<provider>:<account-or-org>`. */
+  name: string;
+  /** Load users from the external directory. */
+  loadUsers?: () => Promise<DirectoryUser[]>;
+  /** Load teams from the external directory. */
+  loadTeams?: () => Promise<DirectoryTeam[]>;
+};
+
+/**
+ * Defines a custom directory source with type inference for connector authors.
+ */
+export const defineDirectorySource = <TSource extends DirectorySource>(
+  source: TSource,
+) => source;
+
+/**
+ * Describes where a synced schema came from.
+ */
+export type SchemaEntrySource = {
+  /** Provider identifier, for example `git`, `github`, `confluent`, or `eventbridge`. */
+  provider: string;
+  /** Optional provider-specific identifier for the external schema. */
+  id?: string;
+  /** Optional URL back to the schema source. */
+  url?: string;
+  /** Optional version/ref/branch for versioned sources. */
+  ref?: string;
+  /** Optional branch for git-backed schema sources. */
+  branch?: string;
+  /** Optional path inside the source. */
+  path?: string;
+  [key: string]: unknown;
+};
+
+/**
+ * Schema returned by an external schema source.
+ */
+export type SchemaEntry = {
+  id: string;
+  name?: string;
+  format?: string;
+  content: string;
+  source: SchemaEntrySource;
+};
+
+export type SchemaResolveContext = {
+  /** Absolute path to the message file that referenced the schema. */
+  messageFilePath?: string;
+};
+
+/**
+ * Loads schemas from an external source.
+ *
+ * EventCatalog calls schema sources during content sync to resolve schema
+ * references from messages into generated schema collection entries.
+ */
+export type SchemaSource = {
+  type: "schemas";
+  /** Stable source identifier used in schema refs, for example `contracts`. */
+  name: string;
+  /** Returns true when this source can resolve the given schema ref. */
+  canResolve: (ref: string) => boolean;
+  /** Resolves a schema ref into schema content and source metadata. */
+  resolve: (
+    ref: string,
+    context?: SchemaResolveContext,
+  ) => Promise<SchemaEntry | undefined>;
+};
+
+/**
+ * Defines a custom schema source with type inference for connector authors.
+ */
+export const defineSchemaSource = <TSource extends SchemaSource>(
+  source: TSource,
+) => source;
diff --git a/packages/connectors/tsconfig.json b/packages/connectors/tsconfig.json
new file mode 100644
index 000000000..e5f1a6400
--- /dev/null
+++ b/packages/connectors/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "es2020",
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true
+  }
+}
diff --git a/packages/connectors/tsup.config.ts b/packages/connectors/tsup.config.ts
new file mode 100644
index 000000000..21370bf5a
--- /dev/null
+++ b/packages/connectors/tsup.config.ts
@@ -0,0 +1,15 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  target: "es2020",
+  format: ["cjs", "esm"],
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  dts: true,
+  entry: {
+    index: "src/index.ts",
+  },
+  outDir: "dist",
+  shims: true,
+});
diff --git a/packages/core/.prettierignore b/packages/core/.prettierignore
new file mode 100644
index 000000000..d11c95031
--- /dev/null
+++ b/packages/core/.prettierignore
@@ -0,0 +1,8 @@
+dist
+node_modules
+.astro/
+dist
+eventcatalog.config.js
+examples/
+docs/
+
diff --git a/.prettierrc b/packages/core/.prettierrc
similarity index 100%
rename from .prettierrc
rename to packages/core/.prettierrc
diff --git a/packages/core/.size-baseline.json b/packages/core/.size-baseline.json
new file mode 100644
index 000000000..88d50e8ca
--- /dev/null
+++ b/packages/core/.size-baseline.json
@@ -0,0 +1,7 @@
+{
+  "dist": {
+    "size": 124806,
+    "unit": "KB",
+    "updatedAt": "2026-01-14"
+  }
+}
diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md
new file mode 100644
index 000000000..00971b5c8
--- /dev/null
+++ b/packages/core/CHANGELOG.md
@@ -0,0 +1,4537 @@
+# @eventcatalog/core
+
+## 4.1.4
+
+### Patch Changes
+
+- 3a64d3a: fix(core): toolkit pages no longer inherit the default app content wrapper, so they can control their own layout and padding
+
+## 4.1.3
+
+### Patch Changes
+
+- a4caa45: Count custom pages and custom API routes in build analytics resource inventory
+
+## 4.1.2
+
+### Patch Changes
+
+- c4df67f: fix(core): builds failing with `TypeError: Missing parameter: id` when `trailingSlash: true` is set
+
+  Astro 7.0.4 (withastro/astro PR #17224) changed route patterns for dynamic file
+  endpoints (e.g. `/docs/teams/[id].md`) to never accept a trailing slash, but the
+  prerender path generator still appends one when `trailingSlash: 'always'` is
+  configured. The generated path (`/docs/teams/customer-platform.md/`) no longer
+  matches the route pattern, so static builds crash. A Vite plugin now patches
+  Astro's param extraction to retry with the trailing slash flipped when no route
+  pattern matches — a no-op on unaffected Astro versions and once the regression
+  is fixed upstream.
+
+## 4.1.1
+
+### Patch Changes
+
+- c769012: feat(create-eventcatalog): optionally install EventCatalog Skills when scaffolding a new project, and surface the skills repo in the CLI banner
+
+## 4.1.0
+
+### Minor Changes
+
+- 80b0ddc: Custom pages: `.astro` and API route files in your catalog's `pages/` directory are now served as routes under a configurable prefix (`pages.prefix`, defaults to `custom`). Requires the Scale plan.
+
+## 4.0.7
+
+### Patch Changes
+
+- a68d3a2: Fix the AI assistant API URL when EventCatalog is deployed with a custom base path (#1345).
+- 9c6ead6: Schema Explorer version comparison now lets you pick any two versions to diff using From/To selectors instead of only showing consecutive-version diffs
+- 37bb4c9: Resolve JSON Schema `$ref` pointers (local and remote) when rendering remote JSON schemas, so referenced definitions are inlined instead of shown as unresolved `$ref` values.
+- Updated dependencies [0983132]
+- Updated dependencies [f963964]
+  - @eventcatalog/linter@1.1.4
+  - @eventcatalog/visualiser@4.0.1
+
+## 4.0.6
+
+### Patch Changes
+
+- 7ca87f7: Fix SchemaViewer portal targeting when multiple schemas share the same id on a page, so each schema renders into its correct container.
+
+## 4.0.5
+
+### Patch Changes
+
+- d6da676: Add a domain type filter (root domains / subdomains) to the Discover table and show subdomains nested under their parent domain in the name column.
+
+## 4.0.4
+
+### Patch Changes
+
+- cb103f0: Persist Discover table filters in the URL so searches, filters, and toggles survive page reloads and can be shared via link
+
+## 4.0.3
+
+### Patch Changes
+
+- eec436c: Add custom documentation tools (getCustomDocs, searchCustomDocs, getCustomDoc) to AI Chat and MCP Server, with section-level full-text search powered by MiniSearch
+
+## 4.0.2
+
+### Patch Changes
+
+- a74a736: Restrict EntityMap MDX component collection prop to domains or services
+
+## 4.0.1
+
+### Patch Changes
+
+- Updated dependencies [44f4bcf]
+  - @eventcatalog/linter@1.1.3
+
+## 4.0.0
+
+### Major Changes
+
+- 728ca67: Add support for a new `systems` collection. Systems are a versioned resource that can be defined in any folder (including inside domains), rendered as documentation pages, and listed in the sidebar with their own icon and color. Systems can group services, flows, entities, data stores (containers), and diagrams, have their own architecture overview page (`/architecture/systems/[id]`) listing their entities, services, external integrations, data stores, and flows, be visualised as an architecture map, be browsed and filtered on a dedicated discover page (`/discover/systems`), and be targeted by architecture decision records (`appliesTo: [{ type: 'system' }]`). Domains can reference one or more systems, which are listed in the domain sidebar, rendered as expandable sections on the domain's architecture page (listing the system's services, like subdomains, with external services shown under "External Integrations"), and merged into the domain's architecture map (each referenced system's services are grouped within the domain graph). Teams and users can own systems, which are surfaced on their profile pages.
+
+  Systems can also declare `relationships` to other systems (each with an optional `version` and `label`), which power a new **Context Diagram** visualiser (`/visualiser/systems/[id]/[version]/context`, linked from the system sidebar under Architecture). Starting from a system, the diagram walks its relationships outward to build the reachable neighbourhood of systems, rendering each as a node (showing its service, entity, and data store counts) connected by labelled edges. Clicking a system node opens that system's architecture map.
+
+  Systems support a `scope` of `internal` (default) or `external`. External systems represent third-party/SaaS systems you integrate with (e.g. "Resend", "Stripe") and are shaded and badged as "External System" in the Context Diagram.
+
+  Systems can also declare `actors` — people or roles that interact with the system (e.g. a Customer or Support Agent). Each actor has an `id` (used to de-duplicate the same actor across systems), an optional `name`/`label`, and a `direction` (`inbound` = actor → system, e.g. "logs into"; `outbound` = system → actor, e.g. "sends notifications to"). Actors are rendered as nodes on the Context Diagram connected to their system by a labelled, directional edge.
+
+### Minor Changes
+
+- cc936ab: Add configurable navigation groups for the vertical sidebar. You can now define custom navigation groups and items via `navigation.groups` in your `eventcatalog.config.ts`, including custom labels, Lucide icons, hrefs, external links, active-state matching, and top/bottom positioning. This replaces the previous `sidebar` visibility config.
+- f02e737: Add a dedicated "Top level diagrams" navigation group that surfaces the System Context Map below top-level domains in the sidebar.
+- e1c3984: Upgrade to Astro 7 and migrate markdown/MDX config to the new unified processor API
+
+### Patch Changes
+
+- 6f1790b: Replace the resource-specific Browse sidebar links with a single Discover link and add a Kind filter to discover pages for switching between available resource collections.
+- bea8571: Rebuild the create-eventcatalog default template with a new e-commerce catalog (domains, systems, services, messages) and fix the collapsed vertical nav brand link alignment.
+- 15aabba: Fix dev watcher incorrectly matching generated files when IGNORE_BUILD_ARTIFACTS is set. Build-artifact exclusions are now skipped in dev mode, since Astro's watcher uses picomatch against the pattern array where negated patterns caused unrelated generated files to match.
+- a99dc45: Remove the Export to PDF / print feature and make diagram version comparison available to everyone (no longer gated behind the Scale plan)
+- 86148d9: Add systems support to AI Chat, catalog tools, and sidebar navigation. The chat panel now recognises system pages and resources, the AI tools accept the `systems` collection, the custom documentation page renders the System Context Map when a domain has systems, and the System section in the sidebar shows the System Context Map when systems exist.
+- d64cfab: Add systems support to the SDK. Systems are a new resource type that can group services, flows, entities, and containers, and can be nested within domains. Includes helpers to read and write systems, add resources to a system, write resources directly into a system, and add systems to domains.
+- Updated dependencies [9949f9f]
+- Updated dependencies [728ca67]
+- Updated dependencies [d64cfab]
+  - @eventcatalog/sdk@2.25.0
+  - @eventcatalog/visualiser@4.0.0
+  - @eventcatalog/linter@1.1.2
+
+## 4.0.0-beta.5
+
+### Patch Changes
+
+- bea8571: Rebuild the create-eventcatalog default template with a new e-commerce catalog (domains, systems, services, messages) and fix the collapsed vertical nav brand link alignment.
+
+## 4.0.0-beta.4
+
+### Patch Changes
+
+- Updated dependencies [9949f9f]
+  - @eventcatalog/sdk@2.25.0-beta.1
+  - @eventcatalog/linter@1.1.2-beta.1
+
+## 4.0.0-beta.3
+
+### Patch Changes
+
+- 15aabba: Fix dev watcher incorrectly matching generated files when IGNORE_BUILD_ARTIFACTS is set. Build-artifact exclusions are now skipped in dev mode, since Astro's watcher uses picomatch against the pattern array where negated patterns caused unrelated generated files to match.
+
+## 4.0.0-beta.2
+
+### Minor Changes
+
+- cc936ab: Add configurable navigation groups for the vertical sidebar. You can now define custom navigation groups and items via `navigation.groups` in your `eventcatalog.config.ts`, including custom labels, Lucide icons, hrefs, external links, active-state matching, and top/bottom positioning. This replaces the previous `sidebar` visibility config.
+
+### Patch Changes
+
+- a99dc45: Remove the Export to PDF / print feature and make diagram version comparison available to everyone (no longer gated behind the Scale plan)
+- 86148d9: Add systems support to AI Chat, catalog tools, and sidebar navigation. The chat panel now recognises system pages and resources, the AI tools accept the `systems` collection, the custom documentation page renders the System Context Map when a domain has systems, and the System section in the sidebar shows the System Context Map when systems exist.
+
+## 4.0.0-beta.1
+
+### Patch Changes
+
+- d64cfab: Add systems support to the SDK. Systems are a new resource type that can group services, flows, entities, and containers, and can be nested within domains. Includes helpers to read and write systems, add resources to a system, write resources directly into a system, and add systems to domains.
+- Updated dependencies [d64cfab]
+  - @eventcatalog/sdk@2.25.0-beta.0
+  - @eventcatalog/linter@1.1.2-beta.0
+
+## 4.0.0-beta.0
+
+### Major Changes
+
+- 728ca67: Add support for a new `systems` collection. Systems are a versioned resource that can be defined in any folder (including inside domains), rendered as documentation pages, and listed in the sidebar with their own icon and color. Systems can group services, flows, entities, data stores (containers), and diagrams, have their own architecture overview page (`/architecture/systems/[id]`) listing their entities, services, external integrations, data stores, and flows, be visualised as an architecture map, be browsed and filtered on a dedicated discover page (`/discover/systems`), and be targeted by architecture decision records (`appliesTo: [{ type: 'system' }]`). Domains can reference one or more systems, which are listed in the domain sidebar, rendered as expandable sections on the domain's architecture page (listing the system's services, like subdomains, with external services shown under "External Integrations"), and merged into the domain's architecture map (each referenced system's services are grouped within the domain graph). Teams and users can own systems, which are surfaced on their profile pages.
+
+  Systems can also declare `relationships` to other systems (each with an optional `version` and `label`), which power a new **Context Diagram** visualiser (`/visualiser/systems/[id]/[version]/context`, linked from the system sidebar under Architecture). Starting from a system, the diagram walks its relationships outward to build the reachable neighbourhood of systems, rendering each as a node (showing its service, entity, and data store counts) connected by labelled edges. Clicking a system node opens that system's architecture map.
+
+  Systems support a `scope` of `internal` (default) or `external`. External systems represent third-party/SaaS systems you integrate with (e.g. "Resend", "Stripe") and are shaded and badged as "External System" in the Context Diagram.
+
+  Systems can also declare `actors` — people or roles that interact with the system (e.g. a Customer or Support Agent). Each actor has an `id` (used to de-duplicate the same actor across systems), an optional `name`/`label`, and a `direction` (`inbound` = actor → system, e.g. "logs into"; `outbound` = system → actor, e.g. "sends notifications to"). Actors are rendered as nodes on the Context Diagram connected to their system by a labelled, directional edge.
+
+### Minor Changes
+
+- f02e737: Add a dedicated "Top level diagrams" navigation group that surfaces the System Context Map below top-level domains in the sidebar.
+- e1c3984: Upgrade to Astro 7 and migrate markdown/MDX config to the new unified processor API
+
+### Patch Changes
+
+- 6f1790b: Replace the resource-specific Browse sidebar links with a single Discover link and add a Kind filter to discover pages for switching between available resource collections.
+- Updated dependencies [728ca67]
+  - @eventcatalog/visualiser@4.0.0-beta.0
+
+## 3.48.4
+
+### Patch Changes
+
+- Updated dependencies [29dc055]
+  - @eventcatalog/sdk@2.24.2
+  - @eventcatalog/linter@1.1.1
+
+## 3.48.3
+
+### Patch Changes
+
+- 2bb0759: Improve node graph performance by deferring dagre layout when composing sub-graphs and using Map-based de-duplication for nodes and edges
+
+## 3.48.2
+
+### Patch Changes
+
+- 38287a4: Sort ADRs in the sidebar by resource name instead of date
+
+## 3.48.1
+
+### Patch Changes
+
+- a57b658: Track changelog, auth, and environments features in build analytics
+
+## 3.48.0
+
+### Minor Changes
+
+- 984e0ee: Add `getC4Diagram` MCP tool to expose LikeC4 source files and view metadata, and add support for the `adrs` collection in MCP resources and tools
+
+## 3.47.4
+
+### Patch Changes
+
+- 956d324: Add linter support for agents, ADRs, containers, data products, and diagrams, expand reference validation across resource types, and update the LikeC4 install message to pin compatible versions.
+- Updated dependencies [956d324]
+  - @eventcatalog/linter@1.1.0
+
+## 3.47.3
+
+### Patch Changes
+
+- 3378c82: Prevent LikeC4 source files from being copied into generated public assets.
+
+## 3.47.2
+
+### Patch Changes
+
+- 82c5ca1: Enable the AI assistant on paid (Starter) plans, not just Scale, and update billing copy to reflect that MCP server and other advanced features remain Scale-only
+- 295a146: Add LikeC4 diagram support via the `<LikeC4View />` MDX component. EventCatalog now auto-detects `.c4` sources, loads the LikeC4 Vite plugin when present, and renders views from discovered LikeC4 projects.
+- 431e547: chore(core): update astro dependencies
+
+## 3.47.1
+
+### Patch Changes
+
+- c80ad76: Improve type safety in SchemaViewer by typing the resolved schemas array and documenting supported SchemaViewer props
+
+## 3.47.0
+
+### Minor Changes
+
+- f632dcf: feat(core): add Protobuf support to SchemaViewer and Schema Explorer
+
+  The `<SchemaViewer />` MDX component and the Schema Explorer now render
+  structured views for Protocol Buffers (`.proto`) schemas, like JSON Schema
+  and Avro. Includes a dependency-free proto2/proto3 parser that captures
+  doc comments, nested messages, enums, maps, and oneofs. Also fixes the
+  Schema Explorer filter panel not collapsing when filters are active.
+
+### Patch Changes
+
+- 728e94e: Hide the Ubiquitous Language sidebar link and language pages for domains (and their subdomains) that have no ubiquitous language terms defined
+- e18ed1b: Entity maps now visualise `array` properties that reference other entities. Array properties display their item type (e.g. `OrderItem[]`), draw a `hasMany` relationship edge to the referenced entity, and show a reference indicator in the visualiser.
+
+## 3.46.1
+
+### Patch Changes
+
+- fd3abbc: chor(core): clean up on catalogs packages
+- c4ad818: Remove decorative backticks from inline code in MDX docs and improve inline code styling
+
+## 3.46.0
+
+### Minor Changes
+
+- 906b6e3: Fix unreadable code blocks in dark mode by making Expressive Code follow the EventCatalog theme toggle (`data-theme`) instead of the OS dark mode media query.
+
+## 3.45.1
+
+### Patch Changes
+
+- a793c2e: Add support for external schema sources, including a new git schema source connector. Messages can now reference schemas by `ref` resolved through configurable schema sources, and the sidebar reflects the resolved schema format.
+
+## 3.45.0
+
+### Minor Changes
+
+- 8870068: schemas are now a collection type in eventcatalog
+
+## 3.44.2
+
+### Patch Changes
+
+- 5269292: Fix environment switcher to support catalogs hosted under different base paths. The environment dropdown now matches the current environment by origin and base path, and preserves the in-catalog path, search params, and hash when switching environments.
+
+## 3.44.1
+
+### Patch Changes
+
+- 3334ab1: Add Microsoft Entra directory connector for syncing users and teams from Microsoft Entra ID (Azure AD).
+
+  - `@eventcatalog/connectors`: new `microsoftEntraDirectory` connector export and docs
+  - `@eventcatalog/sdk`: `Team`/`User` source now supports an optional `id`, and `User.avatarUrl` is now optional
+  - `@eventcatalog/core`: render the Microsoft Entra directory source badge with an Azure icon
+
+- Updated dependencies [3334ab1]
+  - @eventcatalog/sdk@2.24.1
+  - @eventcatalog/linter@1.0.29
+
+## 3.44.0
+
+### Minor Changes
+
+- 6b7fc3c: Add directory connectors for syncing users and teams from external sources (e.g. GitHub organizations) into EventCatalog collections. Introduces the new `@eventcatalog/connectors` package and `directory.sources` configuration in `eventcatalog.config`.
+
+### Patch Changes
+
+- Updated dependencies [6b7fc3c]
+  - @eventcatalog/sdk@2.24.0
+  - @eventcatalog/linter@1.0.28
+
+## 3.43.1
+
+### Patch Changes
+
+- Updated dependencies [2801b3e]
+  - @eventcatalog/sdk@2.23.1
+  - @eventcatalog/linter@1.0.27
+
+## 3.43.0
+
+### Minor Changes
+
+- c130c02: feat(core): add Architecture Decision Records (ADRs) as a first-class resource
+
+  ADRs are now a versioned resource type with their own collection, discover page, sidebar section, and relationships (supersedes/amends/related). ADRs can link to other resources via `appliesTo`, and linked ADRs surface on the resource sidebar under "Decision Records". Includes new example ADRs in the default catalog.
+
+## 3.42.0
+
+### Minor Changes
+
+- 31fcb40: Add RFC 9727 `.well-known/api-catalog` endpoint that publishes a machine-readable Linkset of services, domains, their specifications (OpenAPI, AsyncAPI, GraphQL), and the EventCatalog MCP server when enabled. Raw specifications are served from `/.well-known/api-catalog/specifications/{collection}/{id}/{version}/{specification}`.
+
+## 3.41.4
+
+### Patch Changes
+
+- 1c2b7bf: fix(core): OpenAPI, AsyncAPI and GraphQL spec badges now respect dark mode theme
+
+## 3.41.3
+
+### Patch Changes
+
+- 13e2474: chore(deps): replace axios with native fetch in analytics
+- f86fd4c: Fix implicit any type on tool parameter in services node graph
+
+## 3.41.2
+
+### Patch Changes
+
+- c3b0958: fix node graph styling when rendered inside prose containers and prevent prose styles from affecting visualiser images
+- Updated dependencies [c3b0958]
+  - @eventcatalog/visualiser@3.22.1
+
+## 3.41.1
+
+### Patch Changes
+
+- Updated dependencies [3ad00ad]
+  - @eventcatalog/sdk@2.23.0
+  - @eventcatalog/linter@1.0.26
+
+## 3.41.0
+
+### Minor Changes
+
+- 50b38f6: Add agents as a first-class resource type. Agents can now be documented alongside services, with support for AI model metadata, tools (MCP servers, APIs), and rendered as distinct nodes in the visualiser. Closes #2564.
+
+### Patch Changes
+
+- Updated dependencies [50b38f6]
+  - @eventcatalog/visualiser@3.22.0
+  - @eventcatalog/sdk@2.22.0
+  - @eventcatalog/linter@1.0.25
+
+## 3.40.2
+
+### Patch Changes
+
+- 4f61ed4: Fix editor autocomplete for `eventcatalog.config.js` by publishing the config type declaration at the documented import path.
+
+## 3.40.1
+
+### Patch Changes
+
+- 005ee19: Update the default cloud analytics ingest endpoint to https://api.ecingest.dev/v1/analytics/ingest
+
+## 3.40.0
+
+### Minor Changes
+
+- 9fd1049: feat(core): add OAuth Bearer token authentication for the built-in MCP server. EventCatalog now acts as an MCP protected resource server and can require valid access tokens (JWT) on `/docs/mcp`, with protected resource metadata served at `/.well-known/oauth-protected-resource`.
+
+## 3.39.6
+
+### Patch Changes
+
+- 67940c4: Add optional `url` support to badges so they can render as clickable links.
+- Updated dependencies [67940c4]
+  - @eventcatalog/linter@1.0.24
+  - @eventcatalog/sdk@2.21.2
+
+## 3.39.5
+
+### Patch Changes
+
+- 380b151: Support hiding individual sidebar items (Browse, Organization, Settings) via `sidebar` config in `eventcatalog.config.js`. Section headers and dividers now hide when all items in that section are hidden. Legacy group ids (`/docs`, `/discover`, `/directory`, `/settings`) still work as aliases.
+
+## 3.39.4
+
+### Patch Changes
+
+- 108ed91: Support user-defined named badge colors (slate, gray, red, blue, etc.) via CSS variables, and render resource and schema badges with a neutral, theme-aware style.
+
+## 3.39.3
+
+### Patch Changes
+
+- 8fcd552: Fix domain architecture entity links to include versions and avoid unversioned docs prefetch crashes.
+
+## 3.39.2
+
+### Patch Changes
+
+- 2a5f49a: Support `security` and `server.allowedHosts` configuration options in `eventcatalog.config.js`, forwarding them to the underlying Astro config.
+
+## 3.39.1
+
+### Patch Changes
+
+- 4627289: force patch
+
+## 3.39.0
+
+### Minor Changes
+
+- 8d7b6b1: feat(search): show matched excerpts in search results to highlight where the query matched in resource descriptions
+
+## 3.38.0
+
+### Minor Changes
+
+- 6ea9d32: Serve `llms.txt` and `llms-full.txt` from the catalog root and include data products and ubiquitous languages in the generated output. AI tools can now read the catalog at `/llms.txt` instead of `/docs/llm/llms.txt`, and the docs `.md`/`.mdx` endpoints now resolve data products as well.
+
+## 3.37.0
+
+### Minor Changes
+
+- 6d7151b: Unify resource reference colors across tables, MDX components, and the sidebar via a shared collection-colors utility. Add data-product support to ResourceRef with rich tooltip styling, custom icon support, and updated visualiser data node palette.
+
+### Patch Changes
+
+- 6d7151b: Apply theme variables to custom documentation pages so they respect light/dark mode, and hide the custom docs sidebar nav item when no custom docs are configured.
+- 84fc314: Refresh Admonition component with refined styling and reuse it for the "new version found" callouts on doc pages.
+- Updated dependencies [6d7151b]
+  - @eventcatalog/visualiser@3.21.0
+
+## 3.36.5
+
+### Patch Changes
+
+- 6d9f8dc: Apply theme variables to custom documentation pages so they respect light/dark mode, and hide the custom docs sidebar nav item when no custom docs are configured.
+
+## 3.36.4
+
+### Patch Changes
+
+- 3fd03c0: Improve `<Flow />` and `<NodeGraph />` MDX embeds: support boolean MDX props for `search`, `legend`, and `walkthrough`; avoid duplicate page node graph when a `<Flow />` or `<NodeGraph />` is already embedded; use unique portal IDs per flow embed; render a compact NodeGraph menu button when no title is provided.
+- Updated dependencies [3fd03c0]
+  - @eventcatalog/visualiser@3.20.3
+
+## 3.36.3
+
+### Patch Changes
+
+- 1c9c217: Add support for `container` and `dataProduct` steps in flows. Flows can now reference data stores (containers) and data products directly as steps, rendered in the flow node graph and sidebar. SDK adds `addDataStoreStep`, `addContainerStep`, and `addDataProductStep` builders.
+- Updated dependencies [1c9c217]
+  - @eventcatalog/sdk@2.21.1
+  - @eventcatalog/visualiser@3.20.2
+  - @eventcatalog/linter@1.0.23
+
+## 3.36.2
+
+### Patch Changes
+
+- cf1647c: Default theme to dark when the user has no system preference set.
+
+## 3.36.1
+
+### Patch Changes
+
+- 9cf2a80: Polish search result highlight styling and refresh default template branding.
+
+## 3.36.0
+
+### Minor Changes
+
+- 61853ef: Add opt-in indexed full-content search powered by Pagefind. Enable by setting `search: { type: 'indexed' }` in `eventcatalog.config.js` to index markdown content across resources, custom docs, resource docs and changelogs. Resource search remains the default.
+
+## 3.35.1
+
+### Patch Changes
+
+- 5874143: Bundle EventCatalog docs into `@eventcatalog/core` so coding agents can read the source-of-truth documentation locally, and scaffold `AGENTS.md` / `CLAUDE.md` into new projects so agents are pointed at those bundled docs before making changes.
+
+## 3.35.0
+
+### Minor Changes
+
+- f581840: Expand sidebar and search navigation: link messages and services to the flows they appear in, surface flow steps (messages, services, subflows) on flow pages, add entities to the global sidebar, and include data products, flows, and entities in the search modal with correct icons, filters, and URLs.
+
+## 3.34.0
+
+### Minor Changes
+
+- f2f4a48: Upgrade Astro and related integrations to the latest 6.3.x line (astro 6.3.1, @astrojs/check 0.9.9, @astrojs/markdown-remark 7.1.1, @astrojs/mdx 5.0.4, @astrojs/node 10.1.0, @astrojs/react 5.0.4). Align `@types/react` / `@types/react-dom` on v19 so type-checking works across the workspace. Replace `getEntry('customPages', …)` with a cached `getCollection` lookup in the custom-documentation nav builder to avoid Astro's noisy `slug` deprecation accessor firing thousands of times per build.
+
+## 3.33.0
+
+### Minor Changes
+
+- 4206935: Add a Visibility MDX component for audience-specific docs in the UI and markdown endpoints.
+
+## 3.32.2
+
+### Patch Changes
+
+- fcdd9e2: Add `<Prompt />` MDX component and refresh admonition styling for a more compact, modern look.
+
+## 3.32.1
+
+### Patch Changes
+
+- Updated dependencies [3a7b096]
+  - @eventcatalog/sdk@2.21.0
+  - @eventcatalog/linter@1.0.22
+
+## 3.32.0
+
+### Minor Changes
+
+- 313388f: feat(visualiser): expandable message groups and improved search for large catalogs
+
+  Visualiser now supports expanding grouped message nodes inline so producers/consumers with many messages stay readable on domain and service diagrams. Surrounding nodes are packed around the expanded group so they no longer overlap, and search has been overhauled with icons, resource-type filtering, and better keyboard navigation. Addresses #2079.
+
+### Patch Changes
+
+- Updated dependencies [313388f]
+  - @eventcatalog/visualiser@3.20.0
+
+## 3.31.4
+
+### Patch Changes
+
+- 7d6da5c: Add `EVENTCATALOG_DISABLE_CHANNEL_MIGRATION` env var to opt out of the message → service channel migration on startup.
+
+## 3.31.3
+
+### Patch Changes
+
+- c948f87: Show HTTP method and path on command and query documentation pages when defined via the `operation` frontmatter.
+
+## 3.31.2
+
+### Patch Changes
+
+- 705f82b: feat(core): improved AvroSchemaViewer nested type resolution and enum handling
+
+## 3.31.1
+
+### Patch Changes
+
+- 2c3e3d8: Refresh settings copy: simplify the read-only banner guidance, tighten the MCP/Assistant SSR-required messaging, and let `build:cd` honour license keys provided via the environment.
+
+## 3.31.0
+
+### Minor Changes
+
+- 1ef52e1: Add settings UI, refresh homepage and theme styling, introduce `chat.enabled` config flag, and add new `--ec-rail-bg` / `--ec-rail-active-bg` CSS variables for sidebar rail theming.
+
+### Patch Changes
+
+- 68992a2: Refresh resource page header with accent label, refine Copy page split button, and tighten dropdown spacing
+
+## 3.30.0
+
+### Minor Changes
+
+- bd2b2e7: Refresh UI theme and layout: refined dark-mode palette, restyled header, sidebar, and code blocks (expressive-code), and updated default logo assets.
+
+## 3.29.2
+
+### Patch Changes
+
+- 6beef0c: Watcher now ignores transient `.lock` sidecar files and tolerates files that vanish between the event firing and the stat call, preventing ENOENT crashes during SDK atomic writes.
+
+## 3.29.1
+
+### Patch Changes
+
+- 32e6cbb: fix type error for resourceDocs in llms-full.txt route
+
+## 3.29.0
+
+### Minor Changes
+
+- 3ba10fd: Sub-flow references inside a flow can now be expanded inline. Clicking a sub-flow node in the visualiser inlines the referenced flow's steps in place (mirroring the message-group expand/collapse pattern), with the Collapse button in the header restoring the single-node view. Expanded sub-flow children participate in the business-flow walkthrough, and the graph recentres via `fitView` on both expand and collapse.
+
+### Patch Changes
+
+- Updated dependencies [3ba10fd]
+  - @eventcatalog/visualiser@3.19.0
+
+## 3.28.4
+
+### Patch Changes
+
+- 31ffbd9: fix: render JSON Schema array-valued `type` correctly in `SchemaViewer`. Types declared as arrays (e.g. `["object", "null"]`) now display as `object | null` instead of `objectnull`, and nested properties/array items are still traversable when the type is a union.
+
+## 3.28.3
+
+### Patch Changes
+
+- 1f6fc59: fix: restore custom right-click context menu for message and service nodes in flow diagrams. `flows-node-graph` now populates `contextMenu` on step nodes (previously only non-flow graphs did, so flow pages fell through to the browser default menu). Context-menu items also get explicit colour and no-underline styling so they no longer inherit browser-default purple/underlined link styling when the host page has no link resets.
+- b8734d4: feat(llm): include resource docs in llms.txt and expose raw markdown routes
+
+  Resource docs (domain/service/event/... `docs/` pages) are now listed in `llms.txt` and `llms-full.txt`, grouped under their parent resource as subheadings with links to the resource's `.mdx` page. New `.md` and `.mdx` route handlers at `/docs/[type]/[id]/[version]/[docType]/[docId].mdx` expose the raw markdown so LLMs can fetch resource doc content directly.
+
+- Updated dependencies [1f6fc59]
+  - @eventcatalog/visualiser@3.18.4
+
+## 3.28.2
+
+### Patch Changes
+
+- b8a7bc1: fix(core): preserve non-channel sends (e.g. queries) during message-channels-to-service-channels migration. The migration previously rebuilt the `sends`/`receives` arrays from only the subset of entries matching messages with legacy `channels:` frontmatter, silently dropping any other entries (queries, or messages without channels) on disk during dev/build.
+
+## 3.28.1
+
+### Patch Changes
+
+- 792458e: Add custom icon support to resources via `styles.icon`. Icons render on visualiser nodes, in the sidebar, on documentation page headers, and in the search modal. Accepts a path under the catalog's `public/` folder or an absolute URL. When no custom icon is set, resources now fall back to collection-appropriate default icons. Also maps container `container_type` to a human-readable label on data nodes.
+- Updated dependencies [792458e]
+  - @eventcatalog/visualiser@3.18.2
+
+## 3.28.0
+
+### Minor Changes
+
+- 8f724a7: feat: add `externalSystem` flag to services for modelling third-party integrations
+
+  Services can now set `externalSystem: true` in their frontmatter to be rendered as external systems. This changes their presentation without changing their capabilities — they still send and receive messages, have owners, and support specifications like any other service.
+
+  - Visualiser: external services render purple with a Globe icon and an "External System" badge
+  - Sidebar (root): a dedicated "External Systems" section lists externals; the regular "Services" section excludes them
+  - Sidebar (domain): externals appear under a new "External Integrations" group, separate from "Services In Domain"
+  - Per-service nav badge reads "External System" instead of "Service"
+  - `/discover`: a new "External Systems" tab alongside the "Services" tab
+  - SDK: the `Service` type now accepts `externalSystem?: boolean`
+
+### Patch Changes
+
+- Updated dependencies [8f724a7]
+  - @eventcatalog/sdk@2.20.0
+  - @eventcatalog/visualiser@3.18.0
+  - @eventcatalog/linter@1.0.21
+
+## 3.27.4
+
+### Patch Changes
+
+- 50cb951: Inline isSSR in enterprise feature module to fix circular dependency with utils/feature
+
+## 3.27.3
+
+### Patch Changes
+
+- 0a4a5bd: Replace jsonpath with jsonpath-plus and bump dependencies (@asyncapi/react-component, @scalar/api-reference-react, hono)
+
+## 3.27.2
+
+### Patch Changes
+
+- 80ff83d: fix security vulnerabilities by upgrading mermaid to 11.12.3 and @astrojs/rss to 4.0.18
+- 6a7862a: Replace jsonpath with jsonpath-plus and bump dependencies (@asyncapi/react-component, @scalar/api-reference-react, hono)
+- Updated dependencies [80ff83d]
+- Updated dependencies [4d5a01b]
+  - @eventcatalog/visualiser@3.17.1
+
+## 3.27.1
+
+### Patch Changes
+
+- Updated dependencies [52b4f24]
+  - @eventcatalog/sdk@2.19.0
+  - @eventcatalog/linter@1.0.20
+
+## 3.27.0
+
+### Minor Changes
+
+- 748c528: Expanding a message group node now renders the full downstream graph (channels, consumers, producers) matching the ungrouped view
+
+### Patch Changes
+
+- Updated dependencies [748c528]
+  - @eventcatalog/visualiser@3.17.0
+
+## 3.26.16
+
+### Patch Changes
+
+- Updated dependencies [ee142e4]
+  - @eventcatalog/sdk@2.18.4
+  - @eventcatalog/linter@1.0.19
+
+## 3.26.15
+
+### Patch Changes
+
+- 39539b3: Fix circular reference error when rendering AsyncAPI specs with oneOf/allOf discriminator patterns
+
+## 3.26.14
+
+### Patch Changes
+
+- 141b7c1: Add `eventcatalog export` CLI command to export catalog as JSON using dumpCatalog SDK function
+
+## 3.26.13
+
+### Patch Changes
+
+- Updated dependencies [88795d0]
+  - @eventcatalog/sdk@2.18.3
+  - @eventcatalog/linter@1.0.18
+
+## 3.26.12
+
+### Patch Changes
+
+- 3b68937: Bump astro-compress to ^2.4.0 and sort dependencies alphabetically
+
+## 3.26.11
+
+### Patch Changes
+
+- a02b8f9: Clarify licensing boundaries: add root MIT LICENSE, add EventCatalog Commercial License to enterprise directory, move paid feature flags and routes into enterprise scope, add license headers to all enterprise files, and fix package.json license fields
+
+## 3.26.10
+
+### Patch Changes
+
+- f1680b6: Fix fields explorer crash when JSON Schema uses array type syntax for nullable fields (e.g. `"type": ["string", "null"]`)
+
+## 3.26.9
+
+### Patch Changes
+
+- 6dcb136: fix fields index build failing with "entries is not iterable" when a catalog has no events, commands, or queries
+
+## 3.26.8
+
+### Patch Changes
+
+- 6418562: Fix auth behind reverse proxy: default trustHost to true and add signout error handling
+
+## 3.26.7
+
+### Patch Changes
+
+- 1035f52: Replace better-sqlite3 (native module) with sql.js (WASM) to eliminate native compilation requirements during npm install
+
+## 3.26.6
+
+### Patch Changes
+
+- 038e402: Fix SSR compatibility: remove CSS import from NodeGraph that breaks server-side rendering, add proper type assertion for lazy-loaded component, and export NodeGraphProps type
+- Updated dependencies [038e402]
+  - @eventcatalog/visualiser@3.16.1
+
+## 3.26.5
+
+### Patch Changes
+
+- 26f2b3d: Fix SSR crash on schema/fields page by adding @xyflow/react to vite.ssr.noExternal so Vite handles CSS imports during SSR
+
+## 3.26.4
+
+### Patch Changes
+
+- 214d9df: Fix SSR crash on schema/fields page by moving @xyflow/react CSS import from static to dynamic
+
+## 3.26.3
+
+### Patch Changes
+
+- 6cbccb5: Widen @tailwindcss/vite version range to >=4.1.5 <4.2.2
+
+## 3.26.2
+
+### Patch Changes
+
+- 223ac55: pin @tailwindcss/vite to ~4.2.1 to avoid breaking changes from minor releases
+
+## 3.26.1
+
+### Patch Changes
+
+- 02747f8: Update Astro dependency to ^6.0.8
+
+## 3.26.0
+
+### Minor Changes
+
+- 1539e71: add schema fields explorer with field traceability, conflict detection, and node graph visualization
+
+### Patch Changes
+
+- Updated dependencies [1539e71]
+  - @eventcatalog/visualiser@3.16.0
+
+## 3.25.6
+
+### Patch Changes
+
+- 925eb0b: update astro and astro integration dependencies to latest patch versions
+
+## 3.25.5
+
+### Patch Changes
+
+- cfeac9b: fix(core): disambiguate multiple specs per service in schema explorer by adding filename to group key
+
+## 3.25.4
+
+### Patch Changes
+
+- Updated dependencies [4639ec3]
+  - @eventcatalog/sdk@2.18.2
+  - @eventcatalog/linter@1.0.17
+
+## 3.25.3
+
+### Patch Changes
+
+- Updated dependencies [e2b0460]
+  - @eventcatalog/sdk@2.18.1
+  - @eventcatalog/linter@1.0.16
+
+## 3.25.2
+
+### Patch Changes
+
+- cd78c03: Support flows in nested directories and across domains and services by using recursive glob patterns
+
+## 3.25.1
+
+### Patch Changes
+
+- ed1bfdf: Add entity map visualiser for services, matching the existing domain entity map. Services with entities now show an "Entity Map" link in the sidebar under Architecture. Also fix entity map edge arrows not visible in dark mode.
+- Updated dependencies [ed1bfdf]
+  - @eventcatalog/visualiser@3.15.4
+
+## 3.25.0
+
+### Minor Changes
+
+- e8ab8db: Continue running remaining generators when one fails instead of stopping the entire generation process
+
+## 3.24.0
+
+### Minor Changes
+
+- 913ca20: feat: add field-level usage tracking for message consumers
+
+  Services and domains can now declare which specific fields they depend on in their `receives` (and `sends`) pointers using an optional `fields` array. When declared, a new Field Usage page appears in the message sidebar showing all schema properties alongside their consumers. Supports JSON Schema, Avro, and Protobuf schemas. Includes detection of fields declared by consumers that don't exist in the schema.
+
+### Patch Changes
+
+- Updated dependencies [913ca20]
+  - @eventcatalog/sdk@2.18.0
+  - @eventcatalog/linter@1.0.15
+
+## 3.23.3
+
+### Patch Changes
+
+- 3ea125d: allow scalar configuration to be passed through to the OpenAPI spec component via `scalarConfiguration` config option
+- 3411565: Add export to PDF for message pages (events, commands, queries) with print-friendly layout, schema viewer, producer/consumer tables, version history, and owner details
+
+## 3.23.2
+
+### Patch Changes
+
+- 7946203: update dependencies: bump @asyncapi/parser, astro-compress, and jsonpath to latest versions
+
+## 3.23.1
+
+### Patch Changes
+
+- 2ba795d: fix(core): populate actor node data in flow node graphs
+- 13958d6: fix(core): sidebar navigation loses sync with custom base path
+
+## 3.23.0
+
+### Minor Changes
+
+- 85c1d5c: Upgrade to Astro 6, Zod 4, Vite 7, and Vitest 4. Migrate content collection schemas to Zod 4 API (z.record two-arg, .extend over .merge), update z imports to astro/zod, and rename ContentCollectionKey to CollectionKey.
+
+### Patch Changes
+
+- 96c0bf3: fix version sorting to use semver comparison instead of lexicographic ordering
+
+## 3.22.1
+
+### Patch Changes
+
+- 83aca74: add usage examples support for messages in schema explorer with optional config metadata
+- Updated dependencies [83aca74]
+  - @eventcatalog/sdk@2.17.4
+  - @eventcatalog/linter@1.0.14
+
+## 3.22.0
+
+### Minor Changes
+
+- 3d40745: Redesign schema explorer UI with modern layout, dark mode support, and improved code organization
+
+## 3.21.0
+
+### Minor Changes
+
+- 0517d15: Add analytics integrations support (GA4, GTM, PostHog) for Scale plan users with adapter-based tracking system
+
+## 3.20.4
+
+### Patch Changes
+
+- Updated dependencies [46a2292]
+  - @eventcatalog/sdk@2.17.3
+  - @eventcatalog/linter@1.0.13
+
+## 3.20.3
+
+### Patch Changes
+
+- 1ac3ffc: fix resource docs without explicit version being silently dropped — they now inherit the version from their parent resource
+
+## 3.20.2
+
+### Patch Changes
+
+- Updated dependencies [0514bb1]
+  - @eventcatalog/sdk@2.17.2
+  - @eventcatalog/linter@1.0.12
+
+## 3.20.1
+
+### Patch Changes
+
+- 6456054: Fix schema API returning empty response in SSR mode and add getSchemaForMessage SDK function
+- Updated dependencies [6456054]
+  - @eventcatalog/sdk@2.17.1
+  - @eventcatalog/linter@1.0.11
+
+## 3.20.0
+
+### Minor Changes
+
+- 7ebc6b2: Bump hono dependency from 4.11.7 to 4.12.4
+
+## 3.19.4
+
+### Patch Changes
+
+- Updated dependencies [af2d4f4]
+  - @eventcatalog/sdk@2.17.0
+  - @eventcatalog/linter@1.0.10
+
+## 3.19.3
+
+### Patch Changes
+
+- 2015fc0: Bump astro dependency from ^5.17.3 to ^5.18.0 and sort @tailwindcss/vite alphabetically in package.json
+- a5e20a3: Add changelog link to left sidebar Quick Reference section for all resource types and remove redundant "Read changelog" link from right-side panel
+- Updated dependencies [283c147]
+  - @eventcatalog/sdk@2.16.0
+  - @eventcatalog/linter@1.0.9
+
+## 3.19.2
+
+### Patch Changes
+
+- 29f57f5: Add getChannelsForService utility and display channels in the service sidebar
+
+## 3.19.1
+
+### Patch Changes
+
+- 6338c0d: fix tailwind v4 migration: add CSS import to embed page and expand hover border safelist with missing shades and colors
+- Updated dependencies [a43021e]
+  - @eventcatalog/visualiser@3.15.2
+
+## 3.19.0
+
+### Minor Changes
+
+- 4ef3e75: migrate from Tailwind CSS v3 to v4 with native Vite plugin, reducing dev server startup from ~6.7s to ~1.1s and first page TTFB from ~6.7s to ~1.7s
+
+## 3.18.5
+
+### Patch Changes
+
+- 143fe9c: fix first-run vite dep-scan errors by adding awaitWriteFinish to chokidar watcher config
+
+## 3.18.4
+
+### Patch Changes
+
+- da693fb: fix service sidebar entities to render as navigable links instead of unresolved pointers
+
+## 3.18.3
+
+### Patch Changes
+
+- 58fdcf2: fix dark mode for embedded Flow border and footer text by using theme CSS variables instead of hardcoded colors
+
+## 3.18.2
+
+### Patch Changes
+
+- 56fae87: Include visualiser dist files in tailwind content paths for published package installs
+
+## 3.18.1
+
+### Patch Changes
+
+- Updated dependencies [b5bbb3d]
+  - @eventcatalog/sdk@2.15.1
+  - @eventcatalog/linter@1.0.8
+
+## 3.18.0
+
+### Minor Changes
+
+- e11249b: Refine UI theme: improve sidebar active states with accent colors, brighten dark mode text, add subtle gradients, update homepage layout, and add dark mode icon invert support
+
+### Patch Changes
+
+- a67f051: fix visualiser URL builder to support configurable base paths via setBuildUrlFn
+- 31b931c: Use relative content paths in tailwind config and lazy-load visualizer styles to prevent CSS conflicts
+- ad8b333: Fix Tailwind content paths to be relative to config file, preventing missing utilities in production builds when Astro runs from a different working directory
+- 0d4892a: chore(core): updated rimraf version
+- Updated dependencies [e11249b]
+- Updated dependencies [a67f051]
+- Updated dependencies [31b931c]
+  - @eventcatalog/visualiser@3.15.0
+
+## 3.17.6
+
+### Patch Changes
+
+- 3a3b9ec: fix(mcp): create McpServer and transport per-request to fix stateless transport reuse error
+
+## 3.17.5
+
+### Patch Changes
+
+- d35fbbe: bump astro to 5.17.3 and @astrojs/node to 9.5.4
+- Updated dependencies [f435078]
+  - @eventcatalog/visualiser@3.14.1
+
+## 3.17.4
+
+### Patch Changes
+
+- Updated dependencies [7531be8]
+- Updated dependencies [a1c5012]
+- Updated dependencies [25acfdd]
+  - @eventcatalog/sdk@2.15.0
+  - @eventcatalog/linter@1.0.8
+
+## 3.17.3
+
+### Patch Changes
+
+- e9012cb: Fix resource docs not appearing when folder name differs from frontmatter id
+
+## 3.17.2
+
+### Patch Changes
+
+- 22bd7b8: Use double-star glob patterns for resource doc category collection to support nested directory structures
+
+## 3.17.1
+
+### Patch Changes
+
+- 88de335: Fix resource docs glob patterns to support nested directory structures using double-star wildcards
+
+## 3.17.0
+
+### Minor Changes
+
+- 9d279cc: Add message hydration for DSL export, shared managed keys for all message types, and fix query edge labels in visualizer
+
+## 3.16.0
+
+### Minor Changes
+
+- 0f946fe: Fix NodeGraph version-specific channel routing and add semver/x-pattern version matching support
+
+  **Bug Fix:**
+
+  - Fixed NodeGraph visualisation incorrectly routing all event versions to the same channel instead of their version-specific channels when a service sends multiple versions of the same event to different channels
+
+  **New Features:**
+
+  - Services can now use semver range patterns (^1.0.0, ~1.2.0) and x-patterns (1.x, 1.2.x) in their `sends` and `receives` configurations, and these will correctly resolve in the graph visualiser
+
+## 3.15.6
+
+### Patch Changes
+
+- e1aa05e: upgrade @asyncapi/react-component from 2.4.3 to 3.0.2
+- 19b0bc8: Upgrade glob dependency from v10 to v13
+- ce665d0: upgrade jsonpath dependency from v1.2.0 to v1.2.1
+- deaacc2: upgrade @asyncapi/parser from 3.4.0 to 3.6.0
+- Updated dependencies [f3685b6]
+  - @eventcatalog/sdk@2.14.3
+  - @eventcatalog/linter@1.0.7
+
+## 3.15.5
+
+### Patch Changes
+
+- fbe8860: Fix dark theme support on custom documentation feature page by replacing hardcoded dark: variants with CSS variables
+- da4c50d: Add `doc` resource reference type support for custom documentation pages, extract badge styling into shared utility, and fix theming to use CSS variables
+- a7288ea: Remove the "View Documentation" CTA from the domain integrations visualizer page.
+
+## 3.15.4
+
+### Patch Changes
+
+- Updated dependencies [6a4e582]
+  - @eventcatalog/sdk@2.14.2
+  - @eventcatalog/linter@1.0.6
+
+## 3.15.3
+
+### Patch Changes
+
+- 6bf21c4: Replace `concurrently` with native `spawn` for dev server process management, improving output filtering and replacing astro version line with eventcatalog version
+
+## 3.12.6-beta.0
+
+### Patch Changes
+
+- Monorepo migration: Moved EventCatalog core to packages/core and fixed content path resolution for monorepo structure. Uses relative paths when CATALOG_DIR is set, maintaining backward compatibility with standalone installations.
+
+## 3.12.6
+
+### Patch Changes
+
+- c8c2330: verify required config fields before copying core to prevent Vite restart race conditions
+
+## 3.12.5
+
+### Patch Changes
+
+- 6bd6369: Remove unused dependencies: @eventcatalog/generator-ai, @tanstack/react-query, date-fns, rehype-raw, tw-animate-css, @playwright/test
+
+## 3.12.4
+
+### Patch Changes
+
+- bc85255: configure esbuild jsx automatic mode in vite optimizeDeps
+- daab80f: upgrade axios from 1.7.7 to 1.13.5
+
+## 3.12.3
+
+### Patch Changes
+
+- 4287f97: Upgrade astro dependency from 5.16.16 to 5.17.1
+- 31a0efe: update dependencies: @modelcontextprotocol/sdk, diff2html, and jsonpath
+- 94f3b93: fix(core): resolve PlantUML rendering race condition
+
+## 3.12.2
+
+### Patch Changes
+
+- 404ca30: Downgrade react-syntax-highlighter to v15.6.6 for CJS/ESM compatibility and override prismjs to >=1.30.0 to fix CVE-2024-53382
+
+## 3.12.1
+
+### Patch Changes
+
+- f2255d9: feat(core): added support for clickable folder navigation in custom documentation when index files exist
+- ff678ea: Fix MCP server to support AI SDK tool() helper inputSchema property
+
+## 3.12.0
+
+### Minor Changes
+
+- 265ec79: Add focus mode to visualizer for exploring node connections
+  - Click any node in the visualizer to open a focus mode modal
+  - Shows clicked node in center with incoming connections on left, outgoing on right
+  - Click connected nodes to switch focus with smooth slide animation
+  - Displays placeholder message when no inputs/outputs exist
+  - Includes documentation link and switch actions for each node
+  - Features zoom controls and edge hover animations
+  - Disabled for flow and entity visualizers
+
+### Patch Changes
+
+- 2c300de: Add transition:persist to Header and Footer to prevent asset re-requests during View Transitions navigation
+
+## 3.11.0
+
+### Minor Changes
+
+- 11e34d4: feat: add visualizer layout persistence in dev mode (#2035)
+
+  Add ability to save and restore custom node positions in the visualizer during development. Layouts are saved to `_data/visualizer-layouts/` and can be committed to git for team sharing. Dev-only feature with UI indicators for layout changes and save/reset options in the visualizer dropdown menu.
+
+### Patch Changes
+
+- 11e34d4: Add config option to disable /api/catalog endpoint during static builds to reduce memory usage for large catalogs (fixes #2050)
+
+## 3.10.2
+
+### Patch Changes
+
+- 11963f0: Add config option to disable /api/catalog endpoint during static builds to reduce memory usage for large catalogs (fixes #2050)
+
+## 3.10.1
+
+### Patch Changes
+
+- caea0ec: Update diff package from v7 to v8.0.3
+- 6dd86e3: chore(core): updated astro
+- 9e758f6: update hono dependency from 4.11.4 to 4.11.7
+
+## 3.10.0
+
+### Minor Changes
+
+- 3c573c4: Add resource counting to build telemetry (events, services, domains, etc.)
+
+## 3.9.1
+
+### Patch Changes
+
+- 9d0042b: Add configurable maxTextSize for mermaid diagrams to allow rendering larger diagrams
+
+## 3.9.0
+
+### Minor Changes
+
+- 0c69558: Add mermaid export support for NodeGraph visualizations with view mode switching and shareable URLs
+
+### Patch Changes
+
+- 8f92272: Fix containers collection glob pattern to support nested directories
+
+## 3.8.2
+
+### Patch Changes
+
+- dcdebdc: fix(core): fixed issue with custom docs on windows
+
+## 3.8.1
+
+### Patch Changes
+
+- 732d7f6: Fix type errors in data product builder test file by adding proper type casting and missing required fields
+- 732d7f6: fix(sidebar): resolve typescript type errors in data product builder tests
+
+## 3.8.0
+
+### Minor Changes
+
+- 05f0e2e: feat(core): added Data Products collection support
+
+## 3.7.2
+
+### Patch Changes
+
+- d1bb4db: Extract shared specification processing utilities to reduce code duplication
+
+## 3.7.1
+
+### Patch Changes
+
+- be0ba03: fix(schema-viewer): add support for oneOf and anyOf JSON Schema keywords
+
+  - Add handling for `anyOf` in processSchema function (was missing entirely)
+  - Fix `oneOf` rendering to show selected variant's properties instead of merged properties
+  - Add variant selector UI for nested `oneOf`/`anyOf` within properties
+  - Add support for `oneOf`/`anyOf` in array items
+  - Show variant type indicator ("anyOf" or "oneOf") in property type display
+
+  Fixes #1965
+
+- 141a126: chore(core): updated astro versions
+
+## 3.7.0
+
+### Minor Changes
+
+- 4cbd86f: Add sends and receives properties to domains, allowing domains to directly document event flows without requiring services as intermediaries
+
+## 3.6.2
+
+### Patch Changes
+
+- d4d09e8: Fix type errors in ResourceRef and SearchModal components, add type check script
+- 66d5769: Default to teams page in directory navigation when no users are defined
+
+## 3.6.1
+
+### Patch Changes
+
+- 971adf4: chore(core): bumped hono version up
+- cbf9071: fix sidebar favorites removal for deleted nodes and add theme support to plans and custom docs pages
+- e6b54fb: Add inline resource references with wiki-style syntax and hover tooltips. Use `[[type|ResourceName]]` syntax to create interactive links that display resource details on hover.
+
+## 3.6.0
+
+### Minor Changes
+
+- ac114f0: Add new Discover page with enhanced table filtering and tabbed navigation for browsing catalog resources
+
+### Patch Changes
+
+- 6d7dff5: fix(sidebar): reduce build size with node references and static json api
+
+## 3.5.2
+
+### Patch Changes
+
+- caaf899: Fix visualizer showing incorrect "subscribed by" edge when producer references non-existent channel version
+
+## 3.5.1
+
+### Patch Changes
+
+- 3177b34: Fix Avro schema file downloads in context menu by using actual schema filename from schemaPath instead of hardcoded 'schema.json'
+
+## 3.5.0
+
+### Minor Changes
+
+- 672bcd8: Fixed duplicate search results in sidebar by filtering out unversioned node keys. Added grouping of search results by type with alphabetical sorting. Extracted shared `getBadgeClasses` utility for consistent theming using CSS variables. Added missing Channel type to filter mapping.
+
+### Patch Changes
+
+- d3ce092: Fixed search results not respecting base path and trailing slash configuration. Search result URLs now correctly include the configured base path and trailing slash settings.
+
+## 3.4.2
+
+### Patch Changes
+
+- be85edd: Fix React Rules of Hooks violation in NestedSideBar by moving isFavorited hook before early returns
+
+## 3.4.1
+
+### Patch Changes
+
+- c1a349f: feat(core): add interactive controls to mermaid and plantuml
+
+## 3.4.0
+
+### Minor Changes
+
+- 5162696: feat(core): add mcp server and shared catalog tools
+
+## 3.3.1
+
+### Patch Changes
+
+- 1bd23c3: fix(core): fixed schema explorer in srr mode on start
+
+## 3.3.0
+
+### Minor Changes
+
+- a4645bf: feat(core): added new resource type diagrams
+
+## 3.2.2
+
+### Patch Changes
+
+- d1b2172: fix(core): changelog theme styles
+
+## 3.2.1
+
+### Patch Changes
+
+- c8e2c5c: feat(core): added support for icepanel diagrams
+
+## 3.2.0
+
+### Minor Changes
+
+- 31c0bfe: feat(core): added ability to add custom tools to AI assistant
+
+## 3.1.0
+
+### Minor Changes
+
+- c518cf3: core(feat): added support for dark mode and custom themes
+
+## 3.0.0
+
+### Major Changes
+
+- 1d1111d: feat(core): eventcatalog-v3 release
+- bf6fe18: chore(core): release of v3
+
+### Patch Changes
+
+- 786db2d: chore(core): added icons to spec files in sidebar
+- f49aade: feat(core): updated architecture overview pages
+- 80399f5: chore(core): updated ubi lang styles
+- 6c33b1f: feat(core): visualizer now has presentation mode
+- d1e0979: feat(core): updated chat features
+- c5592f1: fix(core): fixed issue embedding pages on build
+- 39fbd2f: feat(core): added support for titles on admonitions
+- 5525414: chore(core): removed md to mdx checks
+- 8db71c9: fix(core): fixed issue embedding pages on build
+- 507d14d: fix(core): fixed deployment of example catalogs on releases
+- 341279e: fix(core): fixed issue embedding pages on build
+- 713c535: chore(core): updated logger for the ecstudio watcher
+- de19451: feat(core): simplified eventcatalog chat
+- c43115d: feat(core): added channel support in nav and search
+- 8ed1960: chore(core): removed unused icons on domain grid
+- 17c1abc: chore(core): updated tables styles
+- 0bc73d3: chore(core): auth is now more explict opt in
+- f7ef380: feat(fix): fixed search throughout the application
+- 35f760b: chore(core): updated styles for v3
+- 1a0bc7d: chore(core): removed some redundant files
+- 9ec4525: chore(core): refactored features into astro custom integrations
+- 2a32d7c: chore(core): added empty state to nested sidebar
+- fcd3e9c: chore(core): removed some redundant files
+- ddc8af5: fix(core): fixed issues with nested sidebar state
+- dfce0b7: chore(core): llms-txt is now enabled by default
+- 4a17954: chore(core): updated sidebar styles
+- 1cc63fa: chore(core): added v3 beta message update
+- 7b1311b: chore(core): updated packages
+- 8ca5436: chore(core): fixing circular dep in JS
+- 57d1496: chore(core): auth is now more explict opt in
+- b8730a9: fix(core): mdx pages are added to teams and users
+- 5a7f45b: chore(core): updated the schema explorer UI
+- 08f0c81: chore(core): updated cli logger
+- dac4dc5: feat(core): updated homepage styles
+- aff2f92: fix(core): removed duplicated edge labels
+- cd713b8: feat(core): updated default homepage
+- 5b4095e: fix(core): fixed accessibility issues
+- c0372e5: feat(core): embedding visualizer can be embedded with animations
+- 525c809: chore(core): updated react-syntax-highlighter
+- c270a98: fix(core): problems with asyncapi loading in the DOM
+
+## 3.0.0-beta.28
+
+### Patch Changes
+
+- dfce0b7: chore(core): llms-txt is now enabled by default
+
+## 3.0.0-beta.27
+
+### Patch Changes
+
+- f49aade: feat(core): updated architecture overview pages
+
+## 3.0.0-beta.26
+
+### Patch Changes
+
+- 80399f5: chore(core): updated ubi lang styles
+- 5525414: chore(core): removed md to mdx checks
+- 17c1abc: chore(core): updated tables styles
+- 4a17954: chore(core): updated sidebar styles
+- 5a7f45b: chore(core): updated the schema explorer UI
+- cd713b8: feat(core): updated default homepage
+
+## 3.0.0-beta.25
+
+### Patch Changes
+
+- f7ef380: feat(fix): fixed search throughout the application
+
+## 3.0.0-beta.24
+
+### Patch Changes
+
+- d1e0979: feat(core): updated chat features
+
+## 3.0.0-beta.23
+
+### Patch Changes
+
+- aff2f92: fix(core): removed duplicated edge labels
+
+## 3.0.0-beta.22
+
+### Patch Changes
+
+- fcd3e9c: chore(core): removed some redundant files
+
+## 3.0.0-beta.21
+
+### Patch Changes
+
+- 1a0bc7d: chore(core): removed some redundant files
+
+## 3.0.0-beta.20
+
+### Patch Changes
+
+- 9ec4525: chore(core): refactored features into astro custom integrations
+
+## 3.0.0-beta.19
+
+### Patch Changes
+
+- de19451: feat(core): simplified eventcatalog chat
+- 7b1311b: chore(core): updated packages
+
+## 3.0.0-beta.18
+
+### Patch Changes
+
+- 1cc63fa: chore(core): added v3 beta message update
+
+## 3.0.0-beta.17
+
+### Patch Changes
+
+- c0372e5: feat(core): embedding visualizer can be embedded with animations
+
+## 3.0.0-beta.16
+
+### Patch Changes
+
+- 786db2d: chore(core): added icons to spec files in sidebar
+
+## 3.0.0-beta.15
+
+### Patch Changes
+
+- 5b4095e: fix(core): fixed accessibility issues
+
+## 3.0.0-beta.14
+
+### Patch Changes
+
+- 57d1496: chore(core): auth is now more explict opt in
+- c270a98: fix(core): problems with asyncapi loading in the DOM
+
+## 3.0.0-beta.13
+
+### Patch Changes
+
+- 0bc73d3: chore(core): auth is now more explict opt in
+- b8730a9: fix(core): mdx pages are added to teams and users
+
+## 3.0.0-beta.12
+
+### Patch Changes
+
+- 8ed1960: chore(core): removed unused icons on domain grid
+
+## 3.0.0-beta.11
+
+### Patch Changes
+
+- 39fbd2f: feat(core): added support for titles on admonitions
+- dac4dc5: feat(core): updated homepage styles
+
+## 3.0.0-beta.10
+
+### Patch Changes
+
+- c5592f1: fix(core): fixed issue embedding pages on build
+
+## 3.0.0-beta.9
+
+### Patch Changes
+
+- 8db71c9: fix(core): fixed issue embedding pages on build
+
+## 3.0.0-beta.8
+
+### Patch Changes
+
+- 507d14d: fix(core): fixed deployment of example catalogs on releases
+
+## 3.0.0-beta.7
+
+### Patch Changes
+
+- 341279e: fix(core): fixed issue embedding pages on build
+
+## 3.0.0-beta.6
+
+### Patch Changes
+
+- 713c535: chore(core): updated logger for the ecstudio watcher
+- 2a32d7c: chore(core): added empty state to nested sidebar
+
+## 3.0.0-beta.5
+
+### Patch Changes
+
+- 525c809: chore(core): updated react-syntax-highlighter
+
+## 3.0.0-beta.4
+
+### Patch Changes
+
+- c43115d: feat(core): added channel support in nav and search
+
+## 3.0.0-beta.3
+
+### Patch Changes
+
+- 08f0c81: chore(core): updated cli logger
+
+## 3.0.0-beta.2
+
+### Patch Changes
+
+- 6c33b1f: feat(core): visualizer now has presentation mode
+
+## 3.0.0-beta.1
+
+### Patch Changes
+
+- 35f760b: chore(core): updated styles for v3
+- ddc8af5: fix(core): fixed issues with nested sidebar state
+- 8ca5436: chore(core): fixing circular dep in JS
+
+## 3.0.0-beta.0
+
+### Major Changes
+
+- 1d1111d: feat(core): eventcatalog-v3 release
+
+## 2.65.1
+
+### Patch Changes
+
+- fa47d1e: feat(core): added ability for defult homepage and turn visualizer off
+
+## 2.65.0
+
+### Minor Changes
+
+- 0392e72: fix(core): fixed bug for missing adapter on static sites
+- 1bf9a0f: feat(core): added new channel 2.0
+- 9d8e419: fix(core): fixed a bug with avro schema viewer layout
+- 81033b8: feat(core): refactored channel configuration for eventcataog
+
+### Patch Changes
+
+- 544f480: fix(plugin): fix versions of asyncapi plugin
+- 41f3637: fix(core): fixed a bug with avro schema viewer and union options
+- 682c149: feat(core): added ability to get latest schema in the schema api
+- a3e8bfe: chore(core): updated astro versions
+- 38958d2: chore(core): updated glob version of package
+- c5ec61b: fix(core): fixed minor issues with new channel updates
+
+## 2.65.0-beta.5
+
+### Patch Changes
+
+- c5ec61b: fix(core): fixed minor issues with new channel updates
+
+## 2.65.0-beta.4
+
+### Patch Changes
+
+- 544f480: fix(plugin): fix versions of asyncapi plugin
+
+## 2.65.0-beta.3
+
+### Patch Changes
+
+- 682c149: feat(core): added ability to get latest schema in the schema api
+- 38958d2: chore(core): updated glob version of package
+
+## 2.65.0-beta.2
+
+### Minor Changes
+
+- 9d8e419: fix(core): fixed a bug with avro schema viewer layout
+
+### Patch Changes
+
+- 41f3637: fix(core): fixed a bug with avro schema viewer and union options
+- a3e8bfe: chore(core): updated astro versions
+
+## 2.65.0-beta.1
+
+### Minor Changes
+
+- 0392e72: fix(core): fixed bug for missing adapter on static sites
+
+## 2.65.0-beta.0
+
+### Minor Changes
+
+- 81033b8: feat(core): refactored channel configuration for eventcataog
+
+## 2.64.4
+
+### Patch Changes
+
+- ac4cf00: fix(core): Schemaviewer required flags for Avro schemas now working
+
+## 2.64.3
+
+### Patch Changes
+
+- c0d466e: chore(core): removed unsed dependency
+
+## 2.64.2
+
+### Patch Changes
+
+- c48484f: fix(core): fixed issue fetching specifications on ssr mode for pages
+- c009458: chore(core): updated astro versions
+
+## 2.64.1
+
+### Patch Changes
+
+- ca1478d: feat(core): avro schema viewer now shows required fields
+
+## 2.64.0
+
+### Minor Changes
+
+- 4235eb3: feat(core): added schema registry page
+- f37fbad: feat(core): added schemas.txt and also schema API
+
+### Patch Changes
+
+- 5d40372: chore(core): allowed allowed host configuration for server
+
+## 2.63.0
+
+### Minor Changes
+
+- 465d8b8: feat(core): added configuration for eventcatalog tables
+
+## 2.62.1
+
+### Patch Changes
+
+- 750c983: fix(core): https proxy added for license server
+
+## 2.62.0
+
+### Minor Changes
+
+- 7b62734: fix(core): public paths to download schemas fixed
+
+### Patch Changes
+
+- 7b62734: fix(core): fixed an issue when downloading schemas with foldername and id mismatches
+
+## 2.61.9
+
+### Patch Changes
+
+- 1b7b6b1: chore(core): eventcatalog no longer compresses static output by default
+
+## 2.61.8
+
+### Patch Changes
+
+- 77c109a: feat(core): added ability to hide orphaned messages
+
+## 2.61.7
+
+### Patch Changes
+
+- ba3d4cc: fix(core): users can now hide studio on the sidebar
+
+## 2.61.6
+
+### Patch Changes
+
+- 57a1f3f: fix(core): resource versions can be strings or numbers
+- 3c1e854: fix(core): replaced commonjs imports for tailwind
+- cfb08cf: chore(core): catalog api is enabled by default
+
+## 2.61.5
+
+### Patch Changes
+
+- 44ae131: feat(core): mermaid diagrams now support ELK layout
+
+## 2.61.4
+
+### Patch Changes
+
+- a8c060a: feat(core): users can now load all resources into studio
+
+## 2.61.3
+
+### Patch Changes
+
+- f3817eb: fix(core): fixed issue with broken sidebar
+
+## 2.61.2
+
+### Patch Changes
+
+- 788b4f4: feat(core): added support for remote spec files
+
+## 2.61.1
+
+### Patch Changes
+
+- fa838a6: chore(core): updated astro to 5.14.1
+- 02d4217: chore(core): simplify eventcatalog chat
+
+## 2.61.0
+
+### Minor Changes
+
+- e32da88: chore(core): simplify eventcatalog chat
+
+## 2.60.0
+
+### Minor Changes
+
+- df59049: feat(core): services are now nested in domains for the sidebar
+
+## 2.59.1
+
+### Patch Changes
+
+- aff5ad1: fix(core): fixed changelogs for data stores
+
+## 2.59.0
+
+### Minor Changes
+
+- 1901c50: feat(core): added database containers as a resource type
+
+## 2.58.2
+
+### Patch Changes
+
+- 4d30128: fix(core): fixed code styling issues
+
+## 2.58.1
+
+### Patch Changes
+
+- dbdd4d7: fix(core): fixed small type issue with astro
+
+## 2.58.0
+
+### Minor Changes
+
+- 3ed761b: feat(core): added support for graphql specs in EventCatalog
+
+## 2.57.2
+
+### Patch Changes
+
+- ed05f34: chore(core): fixing vite issues using eventcataog with pnpm
+- 1a2ddca: feat(core): added ability to add attachments to all resources
+
+## 2.57.1
+
+### Patch Changes
+
+- def4aaf: chore(core): updated visualizer version
+
+## 2.57.0
+
+### Minor Changes
+
+- 99c2474: feat(core): added ability to open visualizer into studio
+
+## 2.56.4
+
+### Patch Changes
+
+- 068cdf6: feat(core): added new mermaid file loader component
+
+## 2.56.3
+
+### Patch Changes
+
+- d5299f2: chore(core): updated astro version
+- e378fc7: fix(core): fix copy button for trialing slash catalogs
+
+## 2.56.2
+
+### Patch Changes
+
+- 2509425: feat(core): added ability to mofidy the service label in the sidebar
+
+## 2.56.1
+
+### Patch Changes
+
+- 551a687: chore(core): updated astro versions
+
+## 2.56.0
+
+### Minor Changes
+
+- fad3998: feat(core): added support for offline license checks
+
+### Patch Changes
+
+- 9877fcb: chore(core): updated astro versions
+
+## 2.55.6
+
+### Patch Changes
+
+- 290d4d1: fix(core): SchemaViewer now display constant values
+- b0928a8: fix(core): enums and items now shown on entity properties map
+- 821fdd0: fix(core): fixed actor details now showing in visualizer
+
+## 2.55.5
+
+### Patch Changes
+
+- 1c9a4bb: fix(core): fixed architecture page for filtered messages with services
+
+## 2.55.4
+
+### Patch Changes
+
+- ba5b02a: feat(core): added ability to switch column layout for architecture pages
+
+## 2.55.3
+
+### Patch Changes
+
+- 362933f: fix(core): reduced the pagesize of the architecture/messages page
+
+## 2.55.2
+
+### Patch Changes
+
+- bf83b89: fix(core): fixed schemaviewer for array rooted schemas
+
+## 2.55.1
+
+### Patch Changes
+
+- e77e6fc: feat(viualizer): added support for webrtc in channels
+
+## 2.55.0
+
+### Minor Changes
+
+- 5ba7868: feat(core): updated visualizer and setup for designs
+  - Visualizer now pulls information from @eventcatalog/visualizer package
+  - Project now supports .ecstudio files (For EventCatalog Studio)
+  - Project now supports Designs as a Resource type (EventCatalog Studio)
+
+### Patch Changes
+
+- 4f4a911: chore(core): architecture pages now single column
+- b3e5636: feat(core): added support for avsc files in diffs
+- b3dfb93: fix(core): added data nodes from studio into eventcatalog
+- 68cbd22: feat(core): fixed type checks in build
+
+## 2.54.8
+
+### Patch Changes
+
+- f3f8f5d: fix(core): fixed issue with pagefind when users have trailingslash configured
+
+## 2.54.7
+
+### Patch Changes
+
+- 7a2cd70: fix(core): schema viewer now renders in the correct location
+- cbc8d2b: fix(core): fixed custom docs layout issues
+
+## 2.54.6
+
+### Patch Changes
+
+- 6f2f4f9: fix(core): pagefind now includes the base config param
+
+## 2.54.5
+
+### Patch Changes
+
+- 8c87054: Fix cross-platform path resolution for OpenAPI specs and schemas
+
+  Addresses issues #1652 and #1644 by improving the path resolution logic in the `resolveProjectPath` function with full cross-platform compatibility. This fix ensures that paths starting with `../` are resolved correctly on Windows, macOS, and Linux systems.
+
+  **Key improvements:**
+
+  - Normalizes path separators (`/` and `\`) for cross-platform compatibility
+  - Prevents `../` paths from incorrectly resolving outside the project directory
+  - Fixes OpenAPI specifications and schemas failing to load after version 2.54.4
+  - Maintains security boundaries while ensuring functionality across all operating systems
+
+  This resolves the root cause that wasn't fully addressed in version 2.54.4, ensuring that both OpenAPI specifications and AsyncAPI specifications render correctly across all platforms.
+
+## 2.54.4
+
+### Patch Changes
+
+- 2d563c9: fix(core): resolve SchemaViewer path resolution for relative paths
+
+  Fixes SchemaViewer components failing to load schema files with paths starting with "../". The issue was caused by inconsistent path resolution logic in SchemaViewerRoot.astro.
+
+  - Added resolveProjectPath function to handle "../" paths correctly
+  - Updated getAbsoluteFilePathForAstroFile to use the new path resolution logic
+  - SchemaViewerRoot.astro now uses resolveProjectPath for consistent path handling
+
+## 2.54.3
+
+### Patch Changes
+
+- 3f99807: chore(core): updated astro
+- 898e53f: fix(core): entities now render in services pages
+
+## 2.54.2
+
+### Patch Changes
+
+- 6b1b554: fix(core): search no longer loads every result on load
+
+## 2.54.1
+
+### Patch Changes
+
+- 44ac76f: fix(core): fixed pagefind output directory on build
+- cba92ab: fix(core): fixed entity spelling on search modal
+
+## 2.54.0
+
+### Minor Changes
+
+- 3944204: feat(core): update search to custom pagefind solution
+
+## 2.53.1
+
+### Patch Changes
+
+- f811fb0: fix(core): fixed issue with scrolling on docs and nodegraphs
+
+## 2.53.0
+
+### Minor Changes
+
+- c4074d0: feat(core): added ability to customize detail panels on all pages
+
+## 2.52.0
+
+### Minor Changes
+
+- 6c7433e: feat(core): added ability to fetch schemas from a remote url
+
+## 2.51.1
+
+### Patch Changes
+
+- 2622135: feat:(core): added ability to restrict which entities are shown on the EntityMap component
+
+## 2.51.0
+
+### Minor Changes
+
+- 560c3a8: feat(core): updated ubiquitous language page, now renders subdomains …
+
+## 2.50.3
+
+### Patch Changes
+
+- a14c3e8: feat(core): added customization (props) to nodegraphs and flow compon…
+- 34d6bfa: fix(core): mermaid and plantuml now render in accordian
+
+## 2.50.2
+
+### Patch Changes
+
+- 498b9e4: feat(core): dropdown cta for all resource pages are now shown by default
+
+## 2.50.1
+
+### Patch Changes
+
+- 7f6da53: fix(core): fixed issue loading files in SSR mode
+
+## 2.50.0
+
+### Minor Changes
+
+- fff1249: fix(core): fixed issue loading files in SSR mode
+
+## 2.49.5
+
+### Patch Changes
+
+- 789a248: fix(core): fixed domain language explorer in SSR mode
+
+## 2.49.4
+
+### Patch Changes
+
+- f9d22d8: feat(core): added edit links into resource pages
+
+## 2.49.3
+
+### Patch Changes
+
+- 7130716: fix(core): no longer compress css
+
+## 2.49.2
+
+### Patch Changes
+
+- 8b0ae38: fix(core): fixed broken sidebar styles on list view settings
+
+## 2.49.1
+
+### Patch Changes
+
+- 9e0b525: feat(core): compressing build is now optional (again)
+
+## 2.49.0
+
+### Minor Changes
+
+- 48de32d: feat(core): added domain entity map visualizer pages
+
+## 2.48.5
+
+### Patch Changes
+
+- ab83e48: feat(core): compressing build is now optional
+
+## 2.48.4
+
+### Patch Changes
+
+- 99a34cf: feat(core): added draft support for resources
+
+## 2.48.3
+
+### Patch Changes
+
+- cf4f246: feat(core): added draft support for resources
+
+## 2.48.2
+
+### Patch Changes
+
+- f0d88aa: feat(core): added environments switcher
+
+## 2.48.1
+
+### Patch Changes
+
+- b77aa3b: fix(core): fixed list view sidebar scrolling to resources
+- 49f794e: feat(core): added support for MDX snippets
+
+## 2.48.0
+
+### Minor Changes
+
+- 49d8395: feat(core): added support for MDX snippets
+
+### Patch Changes
+
+- a35c5b2: feat(core): sidebar now has collapse buttons
+
+## 2.47.1
+
+### Patch Changes
+
+- c7f7ca1: chore(core): updated width of services in architecture page
+
+## 2.47.0
+
+### Minor Changes
+
+- 66edd2e: chore(core): refactor sidebar to reduce page weights
+
+## 2.46.0
+
+### Minor Changes
+
+- 9ad51a1: feat(core): added support for plantuml code blocks
+
+## 2.45.3
+
+### Patch Changes
+
+- d9b144e: feat(core): added ability to link to headings
+
+## 2.45.2
+
+### Patch Changes
+
+- 79ec914: feat(core): added search and expand features to schema viewer
+
+## 2.45.1
+
+### Patch Changes
+
+- 59d3275: chore(core): renamed new domain feature
+
+## 2.45.0
+
+### Minor Changes
+
+- 537281e: feat(core): added domain integration visualizer
+
+## 2.44.5
+
+### Patch Changes
+
+- 125f14d: fix(core): fixing type errors
+
+## 2.44.4
+
+### Patch Changes
+
+- 3247596: feat(core): added node walkthroughs for flows
+- 5a27960: feat(core): improved search, now searched by name and id
+
+## 2.44.3
+
+### Patch Changes
+
+- 46600ff: fix(core): fix for schema viewer
+
+## 2.44.2
+
+### Patch Changes
+
+- c42518e: fix(core): fixed path matching for middleware
+- d4fd84a: fix(core): removed redundant error log
+
+## 2.44.1
+
+### Patch Changes
+
+- 885bd94: feat(core): added search on visualizer
+
+## 2.44.0
+
+### Minor Changes
+
+- e0d3efe: chore(core): added auth middleware for rbac
+
+## 2.43.5
+
+### Patch Changes
+
+- e09594b: chore(core): updated astro versions
+
+## 2.43.4
+
+### Patch Changes
+
+- a070530: chore(core): added feature logs
+
+## 2.43.3
+
+### Patch Changes
+
+- c70e610: feat(core): added google authentication options
+
+## 2.43.2
+
+### Patch Changes
+
+- 1bc6ee4: feat(core): added entra to auth providers
+
+## 2.43.1
+
+### Patch Changes
+
+- 0dbdeae: feat(core): added auth0 to list of providers for auth
+
+## 2.43.0
+
+### Minor Changes
+
+- 1b6c725: feat(core): added authentication and SSR options
+
+## 2.42.10
+
+### Patch Changes
+
+- 3b5138c: fix(core): services and domains visualizers now read the channel type
+
+## 2.42.9
+
+### Patch Changes
+
+- 6522f76: chore(core): added host configuration support for eventcatalog
+- 650cd38: fix(core): added headers and tabs into openapi render
+
+## 2.42.8
+
+### Patch Changes
+
+- 5f58157: feat(core): added new end point for producers and consumers
+- ea92c89: feat(core): Added entities and ubquitous lang, and channels to llms txt
+
+## 2.42.7
+
+### Patch Changes
+
+- de85086: feat(core): Added entities and ubquitous lang, and channels to llms txt
+
+## 2.42.6
+
+### Patch Changes
+
+- 4c635fa: feat(core): added ability to turn off changelogs
+
+## 2.42.5
+
+### Patch Changes
+
+- cb0c00a: fix(core): fixed issue with long list of messages on architecture page
+
+## 2.42.4
+
+### Patch Changes
+
+- b8e0725: fix(core): fixed broken zindex for search on asyncapi page
+- 2a5574b: fix(core): fixed a bug where schema viewer did not support ref definitions
+
+## 2.42.3
+
+### Patch Changes
+
+- c04abcd: feat(core): added ability to remove minor branding
+- 01d3db9: fix(core): deprecated dates can now be strings
+
+## 2.42.2
+
+### Patch Changes
+
+- 2e4b4f1: fix(core): fix for broken visualizer
+
+## 2.42.1
+
+### Patch Changes
+
+- ad4ece8: feat(core): added producers and consumers to channel docs
+
+## 2.42.0
+
+### Minor Changes
+
+- 1b95c70: Allow channels to be displayed as a single node (Fix #989)
+
+## 2.41.1
+
+### Patch Changes
+
+- 3d8df99: fix(core): fixed base url for llms txt endpoint
+
+## 2.41.0
+
+### Minor Changes
+
+- ab7203c: feat(core): added schemas to AI features
+
+## 2.40.1
+
+### Patch Changes
+
+- 3174cbd: fix(core): now hides glob loader warning in dev mode
+
+## 2.40.0
+
+### Minor Changes
+
+- dc6a17c: feat(core): added subdomain folder support
+
+## 2.39.2
+
+### Patch Changes
+
+- 0094562: feat(core): added ability to turn of visualizer per resource
+
+## 2.39.1
+
+### Patch Changes
+
+- 7dcd349: fix(core): fixing badges for specification files and types
+
+## 2.39.0
+
+### Minor Changes
+
+- e1578ae: feat(core): added support for multi spec files for services
+
+## 2.38.1
+
+### Patch Changes
+
+- e3374f5: feat(core): version dropdown added to visualizer
+
+## 2.38.0
+
+### Minor Changes
+
+- 7c6ad76: feat(core): added google and anthropic models to chat feature
+
+### Patch Changes
+
+- c23584e: fix(core): fix protocol icon nullability issue
+
+## 2.37.4
+
+### Patch Changes
+
+- 186b308: feat(core) added azure messaging protocols
+
+## 2.37.3
+
+### Patch Changes
+
+- c77bc89: feat(core): added ability to embed any nodegraph in your docs
+
+## 2.37.2
+
+### Patch Changes
+
+- 394537f: feat(core): added ability to copy pages and schemas to clipboard
+
+## 2.37.1
+
+### Patch Changes
+
+- 4c3cdd4: fix(core): fixed issue loading in custom landing pages
+
+## 2.37.0
+
+### Minor Changes
+
+- 76464b3: feat(core): added ability for custom landing page for EventCatalog
+
+## 2.36.1
+
+### Patch Changes
+
+- 0c0d378: feat(core): added new protocols for tibco
+
+## 2.36.0
+
+### Minor Changes
+
+- 1042621: feat(core): added entity support to eventcatalog
+
+## 2.35.10
+
+### Patch Changes
+
+- b67bd66: feat(core): badges now accept protocol icons
+
+## 2.35.9
+
+### Patch Changes
+
+- bc5c9a3: fix(core): now loads the eventcatalog stylesheet
+
+## 2.35.8
+
+### Patch Changes
+
+- e4482cc: feat(core): added openai embeddings model option for chat
+
+## 2.35.7
+
+### Patch Changes
+
+- db73875: fix(core): added queries to mention box for chat
+
+## 2.35.6
+
+### Patch Changes
+
+- e3c1b68: fix(core): fixed problem loading config in the chat feature
+
+## 2.35.5
+
+### Patch Changes
+
+- 40336a4: chore(core): generate script now reads .env files
+- 5e480cd: chore(core): removed redundant log
+
+## 2.35.4
+
+### Patch Changes
+
+- 2e78817: fix(core): fixed start command for server catalogs
+
+## 2.35.3
+
+### Patch Changes
+
+- d703b5f: feat(core): env file support and eventcatalog chat updates
+
+## 2.35.2
+
+### Patch Changes
+
+- d52166b: fix(core): fixed redirect for the chat feature
+
+## 2.35.1
+
+### Patch Changes
+
+- 51ac0a6: fix(core): style of sidebar labels
+- 8db9242: fix(core): propagate vite error in eventcatalog build correctly
+
+## 2.35.0
+
+### Minor Changes
+
+- 2cb0534: feat(core): added chat v2 - bring your own keys and server rendered EventCatalog
+
+## 2.34.7
+
+### Patch Changes
+
+- e76317c: fix(core): embedding now works with scale plan
+
+## 2.34.6
+
+### Patch Changes
+
+- 196e711: fix(core): add missing query badge
+- 196098e: feat(core): added figjam component
+
+## 2.34.5
+
+### Patch Changes
+
+- d77355c: feat(core): added support for drawio component
+
+## 2.34.4
+
+### Patch Changes
+
+- e0765c4: feat(core): added support for lucid component
+
+## 2.34.3
+
+### Patch Changes
+
+- 30ac1c7: chore(core): updated catalog sdk version
+- 2f445b2: chore(core): updated astro version
+
+## 2.34.2
+
+### Patch Changes
+
+- d0cfa4d: feat(core): allow flows to reference other flows
+
+## 2.34.1
+
+### Patch Changes
+
+- 933bafd: feat(core): added support for subdomains
+
+## 2.34.0
+
+### Minor Changes
+
+- 7d80063: feat(core): added support for subdomains
+
+### Patch Changes
+
+- fdd24d4: fix(core): consistent layout on User and Team pages
+- a5bca18: fix(core): use the node label in `simple` mode too
+
+## 2.33.12
+
+### Patch Changes
+
+- 39d9f70: fix(core): fix versions list in changelog
+
+## 2.33.11
+
+### Patch Changes
+
+- 57a3879: fix(core): update to schema viewer to support more usecases
+
+## 2.33.10
+
+### Patch Changes
+
+- cb0ce3b: feat(core): deprecation field now supports booleans
+
+## 2.33.9
+
+### Patch Changes
+
+- 80ba8c5: feat(core): added ability to deprecate resources in eventcatalog
+
+## 2.33.8
+
+### Patch Changes
+
+- ce4948d: feat(core): added customization to nodes in visualizer
+
+## 2.33.7
+
+### Patch Changes
+
+- 9a51be2: fix(core): add colors for missing types in NodeGraph legend
+- 8526a17: feat(core): added experimental api for catalog
+- 3a7ca75: feat(core): added customization to nodes in visualizer
+
+## 2.33.6
+
+### Patch Changes
+
+- 5dad823: fix(core): revert for 1340
+
+## 2.33.5
+
+### Patch Changes
+
+- ba769ab: fix(core): astro loaders no longer read node_modules
+- f8c762b: fix(core): visualizer no longer zoomes on moving nodes
+- 1f3ed45: feat(core): added miro components to eventcatalog
+- 8bca5dd: fix(core): changelogs now support EventCatalog components
+- a047db9: feat(core): added miro components to eventcatalog
+
+## 2.33.4
+
+### Patch Changes
+
+- 57dc25c: feat(core): added supported for nested custom docs
+- 9c5893c: feat(core): added ability to add custom link in docs sidebar
+
+## 2.33.3
+
+### Patch Changes
+
+- 59fae38: feat(core): fixes and improvements for ResourceLink
+- d5270b6: fix(core): prevent icon shrinking in PillListFlat.tsx
+- 7dfc047: feat(badges): enhance badge functionality with dynamic icons
+- a6b5cb5: chore(core): updated astro
+- 646f085: feat(core): added GRPC & ZMQ protocol to channels
+
+## 2.33.2
+
+### Patch Changes
+
+- f1576ac: chore(core): replaced schema viewer with new one
+
+## 2.33.1
+
+### Patch Changes
+
+- 23266b5: feat(core): added llms-txt support for custom docs
+- 5f5e81f: feat(core): embed visualizer into custom docs
+
+## 2.33.0
+
+### Minor Changes
+
+- ca07ee5: feat(core): updated custom pages logic
+
+## 2.32.2
+
+### Patch Changes
+
+- fc29b52: feat(core): added new link components
+- a384781: chore(core): updated astro
+
+## 2.32.1
+
+### Patch Changes
+
+- edda4c3: fix(core): types for resource group
+
+## 2.32.0
+
+### Minor Changes
+
+- aa2bda5: feat(core): added resource groups
+
+## 2.31.5
+
+### Patch Changes
+
+- 36291f6: fix(core): fixed highlighting in custom docs and nested docs
+
+## 2.31.4
+
+### Patch Changes
+
+- 18b7d57: fix(core): fixed missing types and removed redundant scroll code for doc pages
+
+## 2.31.3
+
+### Patch Changes
+
+- 41798fb: feat(core): added next and previous to custom docs
+
+## 2.31.2
+
+### Patch Changes
+
+- 8de6538: fix(core): custom-docs now show summaries
+
+## 2.31.1
+
+### Patch Changes
+
+- 43488cb: fix:(core): fixed issue with missing docs in catalogs
+
+## 2.31.0
+
+### Minor Changes
+
+- 145f3ba: feat(core): added custom documentation to eventcatalog
+
+## 2.30.8
+
+### Patch Changes
+
+- 33b2dc3: feat(core): collapse everything except domains in TreeView
+- 79f66a8: feat(core): improve search quality
+- cd99bd5: feat(core): added sidebar to flow resource types and changelog support for flows
+
+## 2.30.7
+
+### Patch Changes
+
+- 548580d: core(fix): update getCollection filter function to match `changelog.mdx`
+
+## 2.30.6
+
+### Patch Changes
+
+- f9fe7a5: feat(core): added ability to add custom nodes in flows
+
+## 2.30.5
+
+### Patch Changes
+
+- b59706f: fix(core): tabs now support optional title param
+
+## 2.30.4
+
+### Patch Changes
+
+- ab46611: chore(core): updated astro versions
+
+## 2.30.3
+
+### Patch Changes
+
+- 53a363a: fix(core): fixed render issue with large message names on architecture view
+
+## 2.30.2
+
+### Patch Changes
+
+- 96e3403: fix(core): fixed custom pages/index.mdx not showing in eventcatalog
+
+## 2.30.1
+
+### Patch Changes
+
+- 86a1ca3: feat(core): sidebar items can now be hidden
+- cc9ba67: feat(core): added optional language prop for Schema component
+- cc9ba67: feat(Schema): add optional language prop for code highlighting
+
+## 2.30.0
+
+### Minor Changes
+
+- 34e3cce: feat(core): moving to astro glob loaders
+
+## 2.29.4
+
+### Patch Changes
+
+- 6aec3b7: fix(core): rss pages now render OK with empty catalog
+
+## 2.29.3
+
+### Patch Changes
+
+- d63ce45: feat(core): customize sidebar labels and badge for messages
+
+## 2.29.2
+
+### Patch Changes
+
+- 9696f82: fix(core): Redirects to latest version now work correctly when basePath is used
+- ba09ab6: fix(core): fixed issue with chat not working when config has path or url in it
+
+## 2.29.1
+
+### Patch Changes
+
+- 9c94fdf: fix(core): fixed icon images which were broken when a base path was used
+
+## 2.29.0
+
+### Minor Changes
+
+- 238db19: feat(core): replaced openapi renderer with new UI
+
+## 2.28.3
+
+### Patch Changes
+
+- 14c748c: fix(core): fixed broken architecture pages when the trailing slash feature was enabled
+
+## 2.28.2
+
+### Patch Changes
+
+- 6bfab57: fix(core): fixed ui issues with architecture in docs
+
+## 2.28.1
+
+### Patch Changes
+
+- 1342032: fix(core): fixed styles in nav bar
+
+## 2.28.0
+
+### Minor Changes
+
+- 5bb6579: feat(core): new nav type and new ui features for docs
+
+### Patch Changes
+
+- dcd6274: chore(core): updated landing page
+
+## 2.27.0
+
+### Minor Changes
+
+- e408977: feat: new architecture pages and initial landing page for EventCatalog
+
+### Patch Changes
+
+- 661eee9: chore(core): added missing tests for url builder
+
+## 2.26.1
+
+### Patch Changes
+
+- b5404ef: refactor(core): migrate `users`/`teams` to Astro new content layer API
+- db9633f: fix(core): fixed broken link in AI instructions
+
+## 2.26.0
+
+### Minor Changes
+
+- c787162: feat(core): added new message table component
+
+## 2.25.1
+
+### Patch Changes
+
+- d84fa26: feat: add protocol check to tile component's href handling
+- 11eac24: fix(core): fixed long edge labels for flows
+- c7fac97: fix(core): fixed broken link on ai page
+- a1ee7da: chore(core): updated astro versions
+
+## 2.25.0
+
+### Minor Changes
+
+- 278b440: feat(core): added context menus to all nodes in visualizer
+
+### Patch Changes
+
+- 375b924: fix(core): remove empty index page to prevent blank docs page
+- 470d62f: fix(core): improved `basePathname` selection in `getTreeView` for the sidebar
+
+## 2.24.3
+
+### Patch Changes
+
+- a9aec83: feat(core): resources added to ai results
+- 2ff4d7e: fix(core): changed default model for AI chat
+
+## 2.24.2
+
+### Patch Changes
+
+- b45488f: fix(core): added browser checks for AI features
+- 0d924f8: fix(plugin): moved the generated ai file location to public dir
+
+## 2.24.1
+
+### Patch Changes
+
+- d8fdb7a: fix(plugin): moved the generated ai file location to public dir
+
+## 2.24.0
+
+### Minor Changes
+
+- 5cc528e: feat(core): added new EventCatalog AI assistant
+
+## 2.23.3
+
+### Patch Changes
+
+- bf92c1d: fix(core): fixed issue for new sidebar for windows
+
+## 2.23.2
+
+### Patch Changes
+
+- a2db8df: fix(core): messages now rendered correctly on service table
+
+## 2.23.1
+
+### Patch Changes
+
+- ec3039e: feat(core): added cli logs to let users know about updates
+- 6501081: chore(core): updated astro version
+
+## 2.23.0
+
+### Minor Changes
+
+- dc707bc: feat(core): added new sidebar type "tree_view". A new sidebar nav that matches your file system
+
+## 2.22.0
+
+### Minor Changes
+
+- 6d967ee: feat(core): added support for llms.txt
+
+## 2.21.5
+
+### Patch Changes
+
+- 5a7801c: chore(core): small ui improvements
+
+## 2.21.4
+
+### Patch Changes
+
+- ee884df: chore(core): added backstage license checks to embed eventcatalog
+
+## 2.21.3
+
+### Patch Changes
+
+- 49ede5c: chore(core): added backstage license checks to embed eventcatalog
+
+## 2.21.2
+
+### Patch Changes
+
+- eec1f5a: chore(core): added catalog update version check
+
+## 2.21.1
+
+### Patch Changes
+
+- e10da45: fix(core): rss feed now gets file dates from git
+
+## 2.21.0
+
+### Minor Changes
+
+- 67ad29f: feat(core): added rss feed for all resources
+
+### Patch Changes
+
+- 85ed55a: chore(core): updated astro versions
+
+## 2.20.3
+
+### Patch Changes
+
+- 22cf545: chore(core): removed redundant/duplicated package.json files for EventCatalog
+
+## 2.20.2
+
+### Patch Changes
+
+- 3891571: fix(core): fixed map of users and teams to owned resources
+
+## 2.20.1
+
+### Patch Changes
+
+- b2fa2ef: fix(core): removed hard coded static page for users
+
+## 2.20.0
+
+### Minor Changes
+
+- 2e0a37e: feat(core): moved users away from docs into directory
+
+## 2.19.9
+
+### Patch Changes
+
+- 577c781: feat(plugin): if apigateway schemas are empty the render-schema-viewe…
+
+## 2.19.8
+
+### Patch Changes
+
+- 21524b3: feat(core): <SchemaViewer/> visibility can be controlled by schema it…
+
+## 2.19.7
+
+### Patch Changes
+
+- e7a1cf9: fix(core): fixed issue with double scroll bars on spec pages
+
+## 2.19.6
+
+### Patch Changes
+
+- 3211cad: refactor(core): reduced amount of data the discover table needs
+
+## 2.19.5
+
+### Patch Changes
+
+- 3872726: chore(core): removed css dependency on spotlight
+
+## 2.19.4
+
+### Patch Changes
+
+- 0d035f5: feat(core): users can now filter by latest version of resources on the discover page
+- c8f86b7: fix(core): fixed dependencies frontmatter quoting when values would be interpreted as non-scalar
+- 8955521: chore(core): updated expressive code plugin for astro
+- 63b4bec: feat(core): changelog collapsed lines simplified
+
+## 2.19.3
+
+### Patch Changes
+
+- 7ffbf6f: chore(core): setup pnpm on the project
+
+## 2.19.2
+
+### Patch Changes
+
+- 0dda8b3: fix(core): removed cache from `getMessages` function as child functions already cache
+- be3a5c1: fix(core): fixed issue where changelog page would show the wrong information
+
+## 2.19.1
+
+### Patch Changes
+
+- 166b0ed: fix(core): ubiquitous language pages now render without any data
+- 475f2b0: fix(core): use slug for changelog matching
+- 1915b3e: fix(core): refactored how versions are sorted across the catalog
+
+## 2.19.0
+
+### Minor Changes
+
+- 5f8dbfe: feat(core): updated astro and also added ubiquitous lang page support
+
+### Patch Changes
+
+- 00f9c2c: fix(core): added ability to sort by semver and numbers
+- 4a710a5: fix(core): fixed the tab component rendering issues on load of page
+- 04ab91d: fix(core): fixed issue with teams/owners not showing in the UI
+
+## 2.18.7
+
+### Patch Changes
+
+- f4e8985: fix(core): visualizer now defaults to correct messages
+- 73b80ae: fix(core): ubiquitous-language matching by domains, also astro upgrade to 5.1.x
+
+## 2.18.6
+
+### Patch Changes
+
+- 1a9b102: fix(core): fixed matching for ubiquitous lang
+- efad265: feat(core): added kinesis protocol to channels
+
+## 2.18.5
+
+### Patch Changes
+
+- a60e94f: feat(core): resources across eventcatalog are now ordered by name
+- 12bbcaa: feat(core) enabled remark-gfm enabling tables in markdown
+
+## 2.18.4
+
+### Patch Changes
+
+- eb01981: fix(core): fixed issue with version ordering now uses semver
+
+## 2.18.3
+
+### Patch Changes
+
+- c8f1847: fix(core): fixing cache issues on build
+
+## 2.18.2
+
+### Patch Changes
+
+- 6f5746b: fix(core): ubiquitous lang now renders on domains
+
+## 2.18.1
+
+### Patch Changes
+
+- 2a0592e: feat(core): added icons packs for mermaid diagrams
+
+## 2.18.0
+
+### Minor Changes
+
+- 972478d: feat(core): added ability to specify dependencies for catalogs
+
+## 2.17.3
+
+### Patch Changes
+
+- f0d68f4: chore(core): updated mermaid to v11
+
+## 2.17.2
+
+### Patch Changes
+
+- 9f960c8: chore(core): cache data between build generation and added script to generate large catalogs
+- 9a61833: fix(core): fixed broken context map link in sidebar
+
+## 2.17.1
+
+### Patch Changes
+
+- 0c2f681: chore(core): removed --root and --port flags from astro preview command
+- fb6c0f2: feat(core): markdown files now support comments
+
+## 2.17.0
+
+### Minor Changes
+
+- 8746d32: chore(core): update to astro 5
+
+## 2.16.6
+
+### Patch Changes
+
+- f73eb3d: feat(core): added admonitions using markdown
+
+## 2.16.5
+
+### Patch Changes
+
+- 45da645: feat(core): forward extra args to astro cli via `--`
+- 46545ee: feat(core): added new <Tabs> component
+
+## 2.16.4
+
+### Patch Changes
+
+- 44ad73d: fix(core): fixed small fontsizes for mermaid diagrams
+
+## 2.16.3
+
+### Patch Changes
+
+- 9c84f9c: feat(core): added inital version of the domain map to visualizer
+
+## 2.16.2
+
+### Patch Changes
+
+- fb2b5c3: chore(core): removed changelog
+- 7559d42: chore(core): revert commit for workspaces
+
+## 2.16.1
+
+### Patch Changes
+
+- a907d96: feat(core): added ubiquitous language support
+- ff449d7: feat(core): added ability to filter by badges
+
+## 2.16.0
+
+### Minor Changes
+
+- ccd3a5a: feat(core): added ubiquitous language support
+
+### Patch Changes
+
+- 18b6478: feat(core): added ability to zoom out even further in visualizer
+- ec7c16c: fix(core): fixed issue rendering animated nodes with flow diagrams
+- dea456a: feat(core): services in the discover table now shows expandable sections
+- e87bb9b: feat(core): sidebar collapsed states now persisted between page loads
+- 38e6165: feat(core): schema viewer now renders yaml files
+
+## 2.15.0
+
+### Minor Changes
+
+- 8e95677: chore(core): refactor to code base moving files to new src directory
+- e260995: chore(core): refactor project files and folders
+
+### Patch Changes
+
+- 920be57: feat(core): added ability to turn channels on/off
+
+## 2.14.3
+
+### Patch Changes
+
+- eb2c620: feat(core): added support to teams chat url in users and teams pages
+- 95ed136: feat(core): added support for rendering avro schema formats in AsyncApi page
+
+## 2.14.2
+
+### Patch Changes
+
+- bb4d278: fix(core): fixed styles for links in the step component
+
+## 2.14.1
+
+### Patch Changes
+
+- a904248: Revert "fix/service-node-graph-metadata (#964)"
+
+## 2.14.0
+
+### Minor Changes
+
+- 536511e: chore(core): refactor core logic to simplify the code
+
+## 2.13.4
+
+### Patch Changes
+
+- 2ad9561: fix(core): fixed issues with node graphs for services and metadata in the nodes
+
+## 2.13.3
+
+### Patch Changes
+
+- b893559: fix(core): fixed issue with styling of schema files
+
+## 2.13.2
+
+### Patch Changes
+
+- 1c79a5f: chore(core): moved types deps to dev deps
+
+## 2.13.1
+
+### Patch Changes
+
+- 240a9d3: fix(core): fixed channel information component
+
+## 2.13.0
+
+### Minor Changes
+
+- 003c1f2: feat(core): adding channels to eventcatalog
+
+## 2.12.3
+
+### Patch Changes
+
+- d0d13c9: chore(core): fixing z-index issue with the header nav and removing the max-width
+
+## 2.12.2
+
+### Patch Changes
+
+- 93e224c: fix(core): custom defined landing page for docs now render on docs tab
+
+## 2.12.1
+
+### Patch Changes
+
+- a57282e: fix(core): new property for AsyncAPI rendering
+- d739d7b: fix(core): changelog buttons now render the correct changelog
+
+## 2.12.0
+
+### Minor Changes
+
+- a136d50: feat(core): services can now send and receive the same messages in vis…
+
+## 2.11.7
+
+### Patch Changes
+
+- 159e2d4: feat(core): added ability to embed discovery table
+
+## 2.11.6
+
+### Patch Changes
+
+- 9a531d2: feat(core): added ability to embed discovery table
+- 2352fc0: feat(core): added ability to embed catalog pages
+- 112f735: feat(core): added ability to embed visualiser without footers
+
+## 2.11.5
+
+### Patch Changes
+
+- 61e5cf1: fix(core): fixed outdir to output to users directory now
+- 6e88fcf: chore(core): moved some GitHub CI/CD to pnpm
+- b29d4f9: chore(core): removed code that copies over files twice to users catalog.
+- a283534: fix(docs): remove blank space from the version tag
+
+## 2.11.4
+
+### Patch Changes
+
+- 7749acd: feat(core): added support for outDir
+
+## 2.11.3
+
+### Patch Changes
+
+- 5442d40: fix(core): counters on homepage only include latest versions
+
+## 2.11.2
+
+### Patch Changes
+
+- 48d61f3: feat(core): added repo support for all resources
+
+## 2.11.1
+
+### Patch Changes
+
+- 214f164: chore(core): minor changes to ui
+
+## 2.11.0
+
+### Minor Changes
+
+- 597dcf2: feat(core): UI improvements to EventCatalog
+
+## 2.10.1
+
+### Patch Changes
+
+- e2c99e7: fix(core): fixed issue adding additional properties to users frontmatter on build
+
+## 2.10.0
+
+### Minor Changes
+
+- aa2090b: feat(core): added support for query message types/resources
+
+## 2.9.1
+
+### Patch Changes
+
+- 5fa9228: fix(core): moving rimraf to dep of project
+
+## 2.9.0
+
+### Minor Changes
+
+- 70d27a7: feat(core): support nested folder structures for domains, services and messages
+
+## 2.8.12
+
+### Patch Changes
+
+- e7cb5d7: chore(core): added astro file path to resources
+
+## 2.8.11
+
+### Patch Changes
+
+- b1912da: fix(core): fixed rapi-docs for large openapi files
+
+## 2.8.10
+
+### Patch Changes
+
+- 2f4b7af: fix(core): fixed issue with using tmp directories
+
+## 2.8.9
+
+### Patch Changes
+
+- 4e0823d: fix(core): fixed issue with importing users package json files
+
+## 2.8.8
+
+### Patch Changes
+
+- 3d3f56e: chore(core): changed the way eventcatalog file is now imported into the project
+
+## 2.8.7
+
+### Patch Changes
+
+- ce04693: fix(core): fixed visualization node graph for domains, reduced overlapping
+
+## 2.8.6
+
+### Patch Changes
+
+- b4c49ef: feat(core): added links to the landing page and fixed resource counter values
+
+## 2.8.5
+
+### Patch Changes
+
+- db41392: fix(core): flows now work with latest semver for services
+- 8376da8: chore(core): fixed url builder for server/client components
+
+## 2.8.4
+
+### Patch Changes
+
+- 95ca9aa: chore(core): removed type checks for consuming catalogs
+
+## 2.8.3
+
+### Patch Changes
+
+- d07a946: chore(core): updated astro versions
+
+## 2.8.2
+
+### Patch Changes
+
+- 591e06f: chore(core): fixed css issues with badges on pages
+
+## 2.8.1
+
+### Patch Changes
+
+- 16c6a28: feat(core): added api path and http verb in openapi viewer
+- c8118b7: fix(core): downloading images in visualizer now shows the whole diagram
+
+## 2.8.0
+
+### Minor Changes
+
+- 6f882b3: feat(core): added ability to focus nodes in the node graph on visualiser
+- dddb730: feat(core): added basic theming support for colors
+
+## 2.7.16
+
+### Patch Changes
+
+- 4d15fdf: fix(core): fixed windows issue for fetching config files
+
+## 2.7.15
+
+### Patch Changes
+
+- 7e63592: fix(core): user ownership on resources within a team
+
+## 2.7.14
+
+### Patch Changes
+
+- c45ebd0: feat(core): added new steps component
+
+## 2.7.13
+
+### Patch Changes
+
+- 6268155: feat(core): new styles added to header and docs sidebar
+
+## 2.7.12
+
+### Patch Changes
+
+- 3016b7f: feat(core): added tile MDX components
+
+## 2.7.11
+
+### Patch Changes
+
+- b106e34: chore(core): added logs for builds
+
+## 2.7.10
+
+### Patch Changes
+
+- d4e2013: chore(core): added ability to check and add properties on users catal…
+
+## 2.7.9
+
+### Patch Changes
+
+- 4cad2eb: fix(core): fixing generate command (again)
+
+## 2.7.8
+
+### Patch Changes
+
+- c67052f: fix(core): fixed generate command
+
+## 2.7.7
+
+### Patch Changes
+
+- f699aed: feat(core): added utils to read and write catalog files
+
+## 2.7.6
+
+### Patch Changes
+
+- bb7333d: feat(core): added protobuf support for auto diffs
+
+## 2.7.5
+
+### Patch Changes
+
+- fde6544: chore(core): updated astro versions
+
+## 2.7.4
+
+### Patch Changes
+
+- 0189ebb: fix(core): ignore trailing slash for icons
+
+## 2.7.3
+
+### Patch Changes
+
+- 1c56b8d: feat(core): added automatic diffs for changelogs for json, yml and avro files
+
+## 2.7.2
+
+### Patch Changes
+
+- ac64dc4: fix(core): only generate discover page for each collection
+
+## 2.7.1
+
+### Patch Changes
+
+- 29ccffc: fix(core): fixed changelogs path matching
+
+## 2.7.0
+
+### Minor Changes
+
+- 515b01f: feat(core): added ability to full screen visuals, new icons for messages and new landing page
+
+## 2.6.4
+
+### Patch Changes
+
+- 0459eec: chore(core): fixed styled for openapi pages
+
+## 2.6.3
+
+### Patch Changes
+
+- d35846b: chore(core): refactored the way pages are rendered reducing code
+
+## 2.6.2
+
+### Patch Changes
+
+- 498f58c: fix(core): generate command now removes any tmp files required for ge…
+
+## 2.6.1
+
+### Patch Changes
+
+- 4aecf6a: fix(core): fixed broken images for specifications on the service page
+
+## 2.6.0
+
+### Minor Changes
+
+- 76bebd7: feat(core): added AsyncAPI pages and new specifications frontmatter api. Deprecated the AsyncAPI and OpenAPI MDX components
+
+## 2.5.5
+
+### Patch Changes
+
+- 2b84b47: fix(core): moved node graphs to only load on client fixing the invalid hook call warning
+
+## 2.5.4
+
+### Patch Changes
+
+- b6052d9: fix(core): added client side url builder
+
+## 2.5.3
+
+### Patch Changes
+
+- a7f1bd0: fix(core): fixed generate script for plugins
+
+## 2.5.2
+
+### Patch Changes
+
+- deacd55: fix(core): can now add producers/consumers without required version number or latest or undefined
+- 2d8ef10: fix(core): homepage redirect status code from permanent to temporary
+
+## 2.5.1
+
+### Patch Changes
+
+- 2bbccf8: feat(core): added new MDX component for Flows
+
+## 2.5.0
+
+### Minor Changes
+
+- 067fd89: feat(core): added flows to eventcatalog
+- c336807: feat(core): only latest versions are now shown in visualizer
+- 20c2cba: fix(core): fixing search not working after builds
+- 7476fa6: fix(core): nodegraphs for domains now work with semver versions
+- 737380a: feat(core): added ability to see how many domains a team and users own
+- a1490d3: chore(core): updated astro versions
+  feat(core): visuzlier arrows stroke width increased
+- 58d6a2d: chore(core): fixing default for flows
+
+## 2.4.0
+
+### Minor Changes
+
+- 3a4b8ec: feat(c0re): add semantic version support, referencing services or messages can now be done with semver
+
+## 2.3.4
+
+### Patch Changes
+
+- a99057e: feat(core): added ability to drag nodes in visualizer
+
+## 2.3.3
+
+### Patch Changes
+
+- dad4df7: fix(core): visualiser now truncates labels on sidebar
+
+## 2.3.2
+
+### Patch Changes
+
+- 90c9219: feat(core): added page redirect to latest version when going to /{resource/{id}
+
+## 2.3.1
+
+### Patch Changes
+
+- 0de35d9: fix(core): vitest no longer added to the npm package
+
+## 2.3.0
+
+### Minor Changes
+
+- d662cb1: feat(core): added custom component support for eventcatalog
+
+## 2.2.7
+
+### Patch Changes
+
+- d7148fa: chore(core): fixed long labels on the documentation sidebar
+
+## 2.2.6
+
+### Patch Changes
+
+- 50a43e0: core(fix): removed forward slash before # to prevent double trailing slash
+- 8104078: chore(core): added windows tests and fixed watcher to work with changelogs files on windows
+
+## 2.2.5
+
+### Patch Changes
+
+- edd58a6: fix(core): enforce the leading slash to the logo
+- 269aef9: fix(core): fixed url paths for EC assets
+
+## 2.2.4
+
+### Patch Changes
+
+- 34fa215: fix(core): now word wrapping code blocks by default in markdown files so not to break the layout of the page
+
+## 2.2.3
+
+### Patch Changes
+
+- ea7302b: fix(core): fixed changelog urls on resource pages
+
+## 2.2.2
+
+### Patch Changes
+
+- 5ec8513: chore(core): added new footer component to tidy up code
+- 7a0e839: fix(core): added defaults for no pages in catalog
+
+## 2.2.1
+
+### Patch Changes
+
+- abac0a7: fix(core): fixed urls on changelogs
+
+## 2.2.0
+
+### Minor Changes
+
+- 9b92648: feat(core): added changelog support for domains, services and messages
+
+## 2.1.0
+
+### Minor Changes
+
+- 35fa4a3: feat(core): added ability to customize the landing page
+
+## 2.0.31
+
+### Patch Changes
+
+- c4f6f40: fix(core): discover table width now fixed on long summarys
+
+## 2.0.30
+
+### Patch Changes
+
+- 32f93a9: fix(core): running eventcatalog on windows (cross-compatibility between operational systems)
+- 956dd32: fix(core): updated service list to render with with name rather than id
+- 6580ff2: fix(core): fixed missing base in redirect target
+
+## 2.0.29
+
+### Patch Changes
+
+- 83d76b7: fix(core): fixed the json schema viewer require issues
+
+## 2.0.28
+
+### Patch Changes
+
+- 0bad036: feat(core): added beta version of generators
+
+## 2.0.27
+
+### Patch Changes
+
+- c6da224: feat(core): added ability to configure landing page
+
+## 2.0.26
+
+### Patch Changes
+
+- 3dc05d8: fix(core): fixed search, now set output path on build
+
+## 2.0.25
+
+### Patch Changes
+
+- 109ce19: feat(core): added optimize flag to make eventcatalog work with large catalogs
+
+## 2.0.24
+
+### Patch Changes
+
+- db66733: fix(core): favicon having invalid url with default base url configuration
+- 26a4a37: fix perf issues for discover pages in build step
+- f29d718: fix(core): sidebar configuration for section visibility is now optional
+- 3426ea8: fix(core): temp fix for domains for users
+
+## 2.0.23
+
+### Patch Changes
+
+- 66a764c: fix(core: fixed additional ts errors)
+
+## 2.0.22
+
+### Patch Changes
+
+- 58a02a1: chore(core): removed console logs
+
+## 2.0.21
+
+### Patch Changes
+
+- 22e4b6d: fix(core): fixed issues with styling
+
+## 2.0.20
+
+### Patch Changes
+
+- 5de772b: fix(core): fixed typescript errors
+
+## 2.0.19
+
+### Patch Changes
+
+- 4be2512: feat(core): added ability to configure port on EventCatlog
+
+## 2.0.18
+
+### Patch Changes
+
+- 209e428: fix(core): fixed domain nav bar in discovery page
+
+## 2.0.17
+
+### Patch Changes
+
+- 6337769: feat(core): added ability to customise header text and logo
+
+## 2.0.16
+
+### Patch Changes
+
+- cae7c0a: fix(core): added missing urls for slash support
+
+## 2.0.15
+
+### Patch Changes
+
+- 73a40b4: fix(core): added support for trailingSlash in the EventCatalog types.
+
+## 2.0.14
+
+### Patch Changes
+
+- 9d61581: feat(core): added support for base url and slashes
+
+## 2.0.13
+
+### Patch Changes
+
+- 1e4c805: feat(core): Adding <SchemaViewer /> component
+
+## 2.0.12
+
+### Patch Changes
+
+- 18f1c3d: fix(core): fixed start and preview commands
+
+## 2.0.11
+
+### Patch Changes
+
+- 45ea9f6: feat(core): added types file for eventcatalog.config.js
+
+## 2.0.10
+
+### Patch Changes
+
+- 62422dd: fix to build
+- 1c42b9f: feat(core): added ability to hide resources in sidebar
+
+## 2.0.9
+
+### Patch Changes
+
+- d4916a0: fix(core): configure width for nodes in visualiser (#560)
+
+## 2.0.8
+
+### Patch Changes
+
+- 5bde1d4: feat(core): versions now show as a dropdown
+
+## 2.0.7
+
+### Patch Changes
+
+- b82d79e: feat(core): Renders names for services side bars and also links to services from domains fixed
+
+## 2.0.6
+
+### Patch Changes
+
+- c098f12: fix(core): hydrate content before building
+
+## 2.0.5
+
+### Patch Changes
+
+- 4410826: feat(core): adding preview and start commands to eventcatalog
+
+## 2.0.4
+
+### Patch Changes
+
+- 00def6d: bug(core): now loads /docs when going to /
+
+## 2.0.3
+
+### Patch Changes
+
+- dc89208: fix(core): core folder now copied on buld
+
+## 2.0.2
+
+### Patch Changes
+
+- a4bfa8b: chore(core): update the project url to the github org
+
+## 2.0.1
+
+### Patch Changes
+
+- 20aa425: chore(misc): Testing the release of EventCatalog
+
+## 2.0.0
+
+New version launched of EventCatalog with major changes.
+
+## 1.2.7
+
+### Patch Changes
+
+- [`65aa33d`](https://github.com/boyney123/eventcatalog/commit/65aa33d618b9f415768554bb85a926c1f1913698) [#510](https://github.com/boyney123/eventcatalog/pull/510) Thanks [@boyney123](https://github.com/boyney123)! - Update mermaid version to latest
+
+## 1.2.6
+
+### Patch Changes
+
+- [`1fce9a2`](https://github.com/boyney123/eventcatalog/commit/1fce9a298ff1820056fcbc4dc75cfd6f18535f60) [#499](https://github.com/boyney123/eventcatalog/pull/499) Thanks [@marciovmartins](https://github.com/marciovmartins)! - feat: add search via query parameter for events, services and domains (#498)
+
+## 1.2.5
+
+### Patch Changes
+
+- [`56b9f0d`](https://github.com/boyney123/eventcatalog/commit/56b9f0daefde6cba75b68c4a5a33742376b540dd) [#485](https://github.com/boyney123/eventcatalog/pull/485) Thanks [@dreglad](https://github.com/dreglad)! - fix: (#484) ensure link exists before opening link in visualizer
+
+- [`56b9f0d`](https://github.com/boyney123/eventcatalog/commit/56b9f0daefde6cba75b68c4a5a33742376b540dd) [#485](https://github.com/boyney123/eventcatalog/pull/485) Thanks [@dreglad](https://github.com/dreglad)! - fix: (#484) ensure link exists before opening link in visualizer.
+
+## 1.2.4
+
+### Patch Changes
+
+- [`821a1a7`](https://github.com/boyney123/eventcatalog/commit/821a1a7553dbfebb6793923d1e49a81fee27826d) [#482](https://github.com/boyney123/eventcatalog/pull/482) Thanks [@WaYdotNET](https://github.com/WaYdotNET)! - fix: visualization of asyncapi: 3.0.0 file
+
+## 1.2.3
+
+### Patch Changes
+
+- [`c2faad3`](https://github.com/boyney123/eventcatalog/commit/c2faad32c756589f4e11e82b7a5b659257e6b98b) [#480](https://github.com/boyney123/eventcatalog/pull/480) Thanks [@boyney123](https://github.com/boyney123)! - fix: bug when copy styles over
+
+## 1.2.2
+
+### Patch Changes
+
+- [`e8846cb`](https://github.com/boyney123/eventcatalog/commit/e8846cb66620581e6cc33a0c8d36ddac912c78b9) [#477](https://github.com/boyney123/eventcatalog/pull/477) Thanks [@boyney123](https://github.com/boyney123)! - feat - fixing copy over
+
+## 1.2.1
+
+### Patch Changes
+
+- [`65a46b1`](https://github.com/boyney123/eventcatalog/commit/65a46b1ecea14837f9cbfa5e66ba3b369f36646a) [#475](https://github.com/boyney123/eventcatalog/pull/475) Thanks [@boyney123](https://github.com/boyney123)! - feat - copy over styles on dev and build
+
+## 1.2.0
+
+### Minor Changes
+
+- [`59fc853`](https://github.com/boyney123/eventcatalog/commit/59fc853878b1e3c5413f7c6fd5bf982b30165693) [#473](https://github.com/boyney123/eventcatalog/pull/473) Thanks [@boyney123](https://github.com/boyney123)! - feat - added ability to add css overrides
+
+## 1.1.2
+
+### Patch Changes
+
+- [`b08f273`](https://github.com/boyney123/eventcatalog/commit/b08f2733b8f6cfea8b89e0708f3ad88bc2e9903f) [#470](https://github.com/boyney123/eventcatalog/pull/470) Thanks [@boyney123](https://github.com/boyney123)! - fix - fixed build with swagger version
+
+## 1.1.1
+
+### Patch Changes
+
+- [`7eb8c93`](https://github.com/boyney123/eventcatalog/commit/7eb8c93a2f13088e45c725dc18699e4f66bdf2c5) [#462](https://github.com/boyney123/eventcatalog/pull/462) Thanks [@boyney123](https://github.com/boyney123)! - fix - copy config file on build
+
+## 1.1.0
+
+### Minor Changes
+
+- [`4b34273`](https://github.com/boyney123/eventcatalog/commit/4b34273931e141a651c0a56e1bc6fba5543869eb) [#447](https://github.com/boyney123/eventcatalog/pull/447) Thanks [@rberger](https://github.com/rberger)! - Force the dependency trim to be version 0.0.3 with a resolution to eliminate a high vulnerability
+
+## 1.0.7
+
+### Patch Changes
+
+- [`63abb59`](https://github.com/boyney123/eventcatalog/commit/63abb596bb2a63caad6349d93b201bac01434f79) [#445](https://github.com/boyney123/eventcatalog/pull/445) Thanks [@boyney123](https://github.com/boyney123)! - fix- build for typescript and react types
+
+## 1.0.6
+
+### Patch Changes
+
+- [`fc2dcd5`](https://github.com/boyney123/eventcatalog/commit/fc2dcd5acc09ea8e03e796537e6b8597f08d5546) [#440](https://github.com/boyney123/eventcatalog/pull/440) Thanks [@rtoro](https://github.com/rtoro)! - feat - added new page for users
+
+## 1.0.5
+
+### Patch Changes
+
+- [`4834e9f`](https://github.com/boyney123/eventcatalog/commit/4834e9f4d1761615e7e5d4740e98c66c00fdc99e) [#438](https://github.com/boyney123/eventcatalog/pull/438) Thanks [@boyney123](https://github.com/boyney123)! - fix: set key on rendered serices, no longer duplicates them
+
+## 1.0.4
+
+### Patch Changes
+
+- [`40a6221`](https://github.com/boyney123/eventcatalog/commit/40a62216f4d9a2d4bfba525bd1f9c92cbd63ecdb) [#414](https://github.com/boyney123/eventcatalog/pull/414) Thanks [@pebbz](https://github.com/pebbz)! - chore(core) - FIX-408 - upgrade typescript
+
+## 1.0.3
+
+### Patch Changes
+
+- [`9476d74`](https://github.com/boyney123/eventcatalog/commit/9476d74af8fc3af8f1aaceb4e6def77e61c5e17f) [#428](https://github.com/boyney123/eventcatalog/pull/428) Thanks [@jlee-spt](https://github.com/jlee-spt)! - feat: Allow fetching of remote asyncapi docs
+
+## 1.0.2
+
+### Patch Changes
+
+- [`69298ce`](https://github.com/boyney123/eventcatalog/commit/69298ce8b46b77c2662ab789af7c00295cb7fe06) [#432](https://github.com/boyney123/eventcatalog/pull/432) Thanks [@boyney123](https://github.com/boyney123)! - chore - locking down Asyncapi version
+
+- [`bfdd189`](https://github.com/boyney123/eventcatalog/commit/bfdd18917d3ec4e51a78dd6c4c93c445e6430e67) [#431](https://github.com/boyney123/eventcatalog/pull/431) Thanks [@jslim](https://github.com/jslim)! - Chore: including fs false by default
+
+## 1.0.1
+
+### Patch Changes
+
+- [`a83e9e5`](https://github.com/boyney123/eventcatalog/commit/a83e9e5e7922689b6ac3326c680a84b9ce582c2a) [#415](https://github.com/boyney123/eventcatalog/pull/415) Thanks [@rafaelrenanpacheco](https://github.com/rafaelrenanpacheco)! - feat: sort sidebar filters
+
+## 1.0.0
+
+### Major Changes
+
+- [`24634aa`](https://github.com/boyney123/eventcatalog/commit/24634aa00d14c05b56cf9fd6e5e7e7dcdd943b07) [#409](https://github.com/boyney123/eventcatalog/pull/409) Thanks [@pebbz](https://github.com/pebbz)! - FIX-276 - Fix bug 276 by upgrading packages
+
+## 0.6.12
+
+### Patch Changes
+
+- [`3bf1979`](https://github.com/boyney123/eventcatalog/commit/3bf19799880cb379e8fbea1bf4cdc40b0c7be7b1) [#400](https://github.com/boyney123/eventcatalog/pull/400) Thanks [@boyney123](https://github.com/boyney123)! - feat- allow props to be used in openAPI components
+
+## 0.6.11
+
+### Patch Changes
+
+- [`21c6260`](https://github.com/boyney123/eventcatalog/commit/21c6260b04bd849f93c11a571c6a6c9b55501911) [#397](https://github.com/boyney123/eventcatalog/pull/397) Thanks [@boyney123](https://github.com/boyney123)! - feta - Adding support for OpenAPI files in events.
+
+## 0.6.10
+
+### Patch Changes
+
+- [`97c0da5`](https://github.com/boyney123/eventcatalog/commit/97c0da5c2976f024286f7760cd688e93b9c53701) [#340](https://github.com/boyney123/eventcatalog/pull/340) Thanks [@michelgrootjans](https://github.com/michelgrootjans)! - - feat - added ability to show node graphs on the event and service overview pages.
+
+## 0.6.9
+
+### Patch Changes
+
+- [`264b6c8`](https://github.com/boyney123/eventcatalog/commit/264b6c8525e59c76bc28bec11d093c5740cf73bf) [#328](https://github.com/boyney123/eventcatalog/pull/328) Thanks [@dremonkey](https://github.com/dremonkey)! - fix: support spaces in projectDIR path
+
+## 0.6.8
+
+### Patch Changes
+
+- [`78945be`](https://github.com/boyney123/eventcatalog/commit/78945be651c48e9194794eff4a73566cb8a045b4) [#360](https://github.com/boyney123/eventcatalog/pull/360) Thanks [@boyney123](https://github.com/boyney123)! - (fix) - fixing 404 issues with domain page
+
+## 0.6.7
+
+### Patch Changes
+
+- [`a93ab13`](https://github.com/boyney123/eventcatalog/commit/a93ab13bf939d8ebdfc771cc6fff23167420a403) [#350](https://github.com/boyney123/eventcatalog/pull/350) Thanks [@ldiego73](https://github.com/ldiego73)! - fix to correctly display the user when there are no events associated with a domain.
+
+- [`a93ab13`](https://github.com/boyney123/eventcatalog/commit/a93ab13bf939d8ebdfc771cc6fff23167420a403) [#350](https://github.com/boyney123/eventcatalog/pull/350) Thanks [@ldiego73](https://github.com/ldiego73)! - fix: correct display of users in domain
+
+## 0.6.6
+
+### Patch Changes
+
+- [`c8b765b`](https://github.com/boyney123/eventcatalog/commit/c8b765b62446097781fd650675b04fe1d4daa287) [#354](https://github.com/boyney123/eventcatalog/pull/354) Thanks [@rafaelrenanpacheco](https://github.com/rafaelrenanpacheco)! - feat: add event tags
+
+## 0.6.5
+
+### Patch Changes
+
+- [`b63773b`](https://github.com/boyney123/eventcatalog/commit/b63773bbb774a1bbf518f3dd0195bba6c09687cd) [#348](https://github.com/boyney123/eventcatalog/pull/348) Thanks [@boyney123](https://github.com/boyney123)! - fix for 260 - nodegraphs used over mermaid graphs when writing to eve…
+
+## 0.6.4
+
+### Patch Changes
+
+- [`adeda51`](https://github.com/boyney123/eventcatalog/commit/adeda51f7f1f5c375e0b54248ac33d4dd2476054) Thanks [@boyney123](https://github.com/boyney123)! - OpenAPI component now supports remote spec files.
+
+## 0.6.3
+
+### Patch Changes
+
+- [`16e792e`](https://github.com/boyney123/eventcatalog/commit/16e792ea72ed524ac80108754a16f655ec6a2a91) [#336](https://github.com/boyney123/eventcatalog/pull/336) Thanks [@boyney123](https://github.com/boyney123)! - adding fix for 324 - domains with services edit link now correct
+
+## 0.6.2
+
+### Patch Changes
+
+- [`8f72480`](https://github.com/boyney123/eventcatalog/commit/8f724804873317940d62b2887aa8f54ced430260) [#330](https://github.com/boyney123/eventcatalog/pull/330) Thanks [@michelgrootjans](https://github.com/michelgrootjans)! - Fix to the 3D node graph
+
+## 0.6.1
+
+### Patch Changes
+
+- [`9315416`](https://github.com/boyney123/eventcatalog/commit/931541626315a753d630593083e2f1f87c7c51cc) [#320](https://github.com/boyney123/eventcatalog/pull/320) Thanks [@mikaelvesavuori](https://github.com/mikaelvesavuori)! - Mermaid component not working
+
+## 0.6.0
+
+### Minor Changes
+
+- [`34358f5`](https://github.com/boyney123/eventcatalog/commit/34358f5b55fa58a8502a81ed44fb9c4b1901bdd2) [#314](https://github.com/boyney123/eventcatalog/pull/314) Thanks [@martzcodes](https://github.com/martzcodes)! - Feature: Add Badge Filtering to Domains, Events, and Services
+
+## 0.5.2
+
+### Patch Changes
+
+- [`7372407`](https://github.com/boyney123/eventcatalog/commit/73724077d528d48d16bfffaa97231e7f63e3903f) [#312](https://github.com/boyney123/eventcatalog/pull/312) Thanks [@boyney123](https://github.com/boyney123)! - fix version for spotlight
+
+## 0.5.1
+
+### Patch Changes
+
+- [`8419a50`](https://github.com/boyney123/eventcatalog/commit/8419a506c7ffa686fb474235474261462949f888) [#308](https://github.com/boyney123/eventcatalog/pull/308) Thanks [@boyney123](https://github.com/boyney123)! - chore: updating to minify files and change cdn for font-awesome
+
+## 0.5.0
+
+### Minor Changes
+
+- [`a790134`](https://github.com/boyney123/eventcatalog/commit/a7901349fc12efce430f5aeda87d5befb03bd628) [#303](https://github.com/boyney123/eventcatalog/pull/303) Thanks [@dpwdec](https://github.com/dpwdec)! - feat: added new badges for event, services and domains
+
+## 0.4.0
+
+### Minor Changes
+
+- [`cda7105`](https://github.com/boyney123/eventcatalog/commit/cda7105b03e5d5aa6fc9451552cc89c1e88e8859) [#304](https://github.com/boyney123/eventcatalog/pull/304) Thanks [@lcsbltm](https://github.com/lcsbltm)! - feat: added support for asyncapi file in service directory. Now supports new AsyncAPI MDX component.
+
+## 0.3.4
+
+### Patch Changes
+
+- [`390f0a1`](https://github.com/boyney123/eventcatalog/commit/390f0a103ca011afbb7611f88f69daf06a930bd5) [#297](https://github.com/boyney123/eventcatalog/pull/297) Thanks [@boyney123](https://github.com/boyney123)! - fix - autoprefix warning in console
+
+## 0.3.3
+
+### Patch Changes
+
+- [`1e30f43`](https://github.com/boyney123/eventcatalog/commit/1e30f439364143022bac7094e06bfbed11e51af9) [#295](https://github.com/boyney123/eventcatalog/pull/295) Thanks [@boyney123](https://github.com/boyney123)! - chore - update mermaid package
+
+## 0.3.2
+
+### Patch Changes
+
+- [`d7368d0`](https://github.com/boyney123/eventcatalog/commit/d7368d0a5dec261e99b3f556af4c90572d4bb38c) [#293](https://github.com/boyney123/eventcatalog/pull/293) Thanks [@boyney123](https://github.com/boyney123)! - fix - allow button configuration on the homescreen
+
+## 0.3.1
+
+### Patch Changes
+
+- [`8ccc733`](https://github.com/boyney123/eventcatalog/commit/8ccc733c69b7b262c6d1d9751d331a101719de42) [#291](https://github.com/boyney123/eventcatalog/pull/291) Thanks [@boyney123](https://github.com/boyney123)! - fix - overflow issues with too many examples in the Examples MDX comp…
+
+## 0.3.0
+
+### Minor Changes
+
+- [`93db111`](https://github.com/boyney123/eventcatalog/commit/93db11169279435a762a8098c2f50014a5698504) [#286](https://github.com/boyney123/eventcatalog/pull/286) Thanks [@boyney123](https://github.com/boyney123)! - feat - users can now edit header links
+
+## 0.2.20
+
+### Patch Changes
+
+- [`3ca978a`](https://github.com/boyney123/eventcatalog/commit/3ca978a5fd16267f3479d67c54fa0f8007f94dc9) [#281](https://github.com/boyney123/eventcatalog/pull/281) Thanks [@dytyniuk](https://github.com/dytyniuk)! - Fix a broken link behind View in Visualiser button on the Event Details page
+
+## 0.2.19
+
+### Patch Changes
+
+- [`6848067`](https://github.com/boyney123/eventcatalog/commit/68480677ed079bb73c0b8e19f60e15abb3aff707) [#264](https://github.com/boyney123/eventcatalog/pull/264) Thanks [@rtoro](https://github.com/rtoro)! - feat: adding search box into service page
+
+## 0.2.18
+
+### Patch Changes
+
+- [`602f726`](https://github.com/boyney123/eventcatalog/commit/602f72693f9b4f3f9dd9838dd8cad2da6c4ff6a2) [#254](https://github.com/boyney123/eventcatalog/pull/254) Thanks [@drub0y](https://github.com/drub0y)! - fix(core): Fixes getEditUrl to build URLs w/URL vs just path.join
+
+## 0.2.17
+
+### Patch Changes
+
+- [`c5330cd`](https://github.com/boyney123/eventcatalog/commit/c5330cd9776de26389271a2bd7b0c589a59b0982) [#265](https://github.com/boyney123/eventcatalog/pull/265) Thanks [@boyney123](https://github.com/boyney123)! - fix: fixing small padding issues on various pages
+
+## 0.2.16
+
+### Patch Changes
+
+- [`6ffc4af`](https://github.com/boyney123/eventcatalog/commit/6ffc4afe7059b98c02b496349ca624c9b672dbcb) [#261](https://github.com/boyney123/eventcatalog/pull/261) Thanks [@boyney123](https://github.com/boyney123)! - fix(core): Fixes node domain service/event linking
+
+## 0.2.15
+
+### Patch Changes
+
+- [`c5cb51f`](https://github.com/boyney123/eventcatalog/commit/c5cb51f60926d2edad806de59873aadab61e0d9d) [#258](https://github.com/boyney123/eventcatalog/pull/258) Thanks [@boyney123](https://github.com/boyney123)! - fix: now checks events folder in domains before moving them to public…
+
+## 0.2.14
+
+### Patch Changes
+
+- [`17a5883`](https://github.com/boyney123/eventcatalog/commit/17a5883bcc15480872c2944296fcac503bfab8c4) [#251](https://github.com/boyney123/eventcatalog/pull/251) Thanks [@boyney123](https://github.com/boyney123)! - fix: build issues with eventcatalog core
+
+## 0.2.13
+
+### Patch Changes
+
+- [`5211140`](https://github.com/boyney123/eventcatalog/commit/5211140b254353b7aa1c5baead6be416a853cc9d) [#240](https://github.com/boyney123/eventcatalog/pull/240) Thanks [@thim81](https://github.com/thim81)! - feat: Analytics - Added Google Analytics option
+
+## 0.2.12
+
+### Patch Changes
+
+- [`4269b19`](https://github.com/boyney123/eventcatalog/commit/4269b199809807bd08968ce4f9c6e025c5d14794) [#241](https://github.com/boyney123/eventcatalog/pull/241) Thanks [@donaldpipowitch](https://github.com/donaldpipowitch)! - chore: improve typings
+
+## 0.2.11
+
+### Patch Changes
+
+- [`8c3c719`](https://github.com/boyney123/eventcatalog/commit/8c3c719b94e005921f6caec16106466da3f86992) [#244](https://github.com/boyney123/eventcatalog/pull/244) Thanks [@otbe](https://github.com/otbe)! - Fix broken links for services that have no domain on events detail page
+
+## 0.2.10
+
+### Patch Changes
+
+- [`41f6b5a`](https://github.com/boyney123/eventcatalog/commit/41f6b5a03645bfac2006f80c013ed7315cbe3add) [#229](https://github.com/boyney123/eventcatalog/pull/229) Thanks [@rtoro](https://github.com/rtoro)! - feat(core): allow the use of swagger ui in service pages
+
+## 0.2.9
+
+### Patch Changes
+
+- [`3740427`](https://github.com/boyney123/eventcatalog/commit/37404275e021c4d55ae43f5efbf12e321bf65025) [#230](https://github.com/boyney123/eventcatalog/pull/230) Thanks [@boyney123](https://github.com/boyney123)! - fix: visualiser now supports long names in diagram (again)
+
+## 0.2.8
+
+### Patch Changes
+
+- [`2985a14`](https://github.com/boyney123/eventcatalog/commit/2985a14ecdebb5f15ea0ff6512ee88f8863e676f) [#227](https://github.com/boyney123/eventcatalog/pull/227) Thanks [@boyney123](https://github.com/boyney123)! - feat: adding new node in visualiser to show all events and services
+
+## 0.2.7
+
+### Patch Changes
+
+- [`4e03a95`](https://github.com/boyney123/eventcatalog/commit/4e03a95f1420c36169232723f277e88b12c3d5f7) [#224](https://github.com/boyney123/eventcatalog/pull/224) Thanks [@boyney123](https://github.com/boyney123)! - feat: visualiser on click now sets query params
+
+## 0.2.6
+
+### Patch Changes
+
+- [`ccb524a`](https://github.com/boyney123/eventcatalog/commit/ccb524abc97ec7c58b66fd8b1fcb34b0f9a7bd02) [#217](https://github.com/boyney123/eventcatalog/pull/217) Thanks [@otbe](https://github.com/otbe)! - fix: add a stable render key for events/services in visualizer
+
+## 0.2.5
+
+### Patch Changes
+
+- [`65ee3da`](https://github.com/boyney123/eventcatalog/commit/65ee3daab667c0f8b960733c738e3fb12f683144) [#215](https://github.com/boyney123/eventcatalog/pull/215) Thanks [@otbe](https://github.com/otbe)! - add a stable render key for events
+
+## 0.2.4
+
+### Patch Changes
+
+- [`c833a2a`](https://github.com/boyney123/eventcatalog/commit/c833a2a74b049e231c804504550b942d4dc33e70) [#213](https://github.com/boyney123/eventcatalog/pull/213) Thanks [@boyney123](https://github.com/boyney123)! - chore: update to new nextjs version
+
+## 0.2.3
+
+### Patch Changes
+
+- [`a0b90f9`](https://github.com/boyney123/eventcatalog/commit/a0b90f9a4ce9bfd0409b2dff44da5f00bafdfa87) [#211](https://github.com/boyney123/eventcatalog/pull/211) Thanks [@boyney123](https://github.com/boyney123)! - fix: fixing domain mappings and change log issues with domains
+
+## 0.2.2
+
+### Patch Changes
+
+- [`7dcdd9e`](https://github.com/boyney123/eventcatalog/commit/7dcdd9efa077ab9beafcb92bf4789359f9eed02c) [#209](https://github.com/boyney123/eventcatalog/pull/209) Thanks [@boyney123](https://github.com/boyney123)! - fix: now check for events dir before moving schemas
+
+## 0.2.1
+
+### Patch Changes
+
+- [`ccefeee`](https://github.com/boyney123/eventcatalog/commit/ccefeeee93e80620c1c3755676bd0dbe448b4a8a) [#206](https://github.com/boyney123/eventcatalog/pull/206) Thanks [@boyney123](https://github.com/boyney123)! - feat: fixing domains and adding them to create package
+
+## 0.2.0
+
+### Minor Changes
+
+- [`8352416`](https://github.com/boyney123/eventcatalog/commit/835241609aa03cb8158b7a5a1c662c57f8e22505) [#204](https://github.com/boyney123/eventcatalog/pull/204) Thanks [@boyney123](https://github.com/boyney123)! - feat: adding domain support to eventcatalog
+
+## 0.1.19
+
+### Patch Changes
+
+- [`a6f5ae3`](https://github.com/boyney123/eventcatalog/commit/a6f5ae3684279b57cbb4c337e98a5373a2facabb) [#195](https://github.com/boyney123/eventcatalog/pull/195) Thanks [@donaldpipowitch](https://github.com/donaldpipowitch)! - fix(logs): break line in diff view
+
+* [`f48322a`](https://github.com/boyney123/eventcatalog/commit/f48322ab96be22a65baa4cbd5b5ce6d7a0fadd8b) [#167](https://github.com/boyney123/eventcatalog/pull/167) Thanks [@thim81](https://github.com/thim81)! - feat: set page title, description, favicon and og metadata
+
+## 0.1.18
+
+### Patch Changes
+
+- [`3eb7f3b`](https://github.com/boyney123/eventcatalog/commit/3eb7f3b98ef5061beaff4d1ebfac3874cab33c95) [#190](https://github.com/boyney123/eventcatalog/pull/190) Thanks [@boyney123](https://github.com/boyney123)! - chore: added new footer link for visualiser
+
+## 0.1.17
+
+### Patch Changes
+
+- [`d57e67b`](https://github.com/boyney123/eventcatalog/commit/d57e67bf38be9391841b3c6dee6ab360b2eb1325) [#188](https://github.com/boyney123/eventcatalog/pull/188) Thanks [@boyney123](https://github.com/boyney123)! - fixing visualiser for mobile devices
+
+## 0.1.16
+
+### Patch Changes
+
+- [`2d10847`](https://github.com/boyney123/eventcatalog/commit/2d108470af945e1cec59c114627878c56d7385dd) [#186](https://github.com/boyney123/eventcatalog/pull/186) Thanks [@boyney123](https://github.com/boyney123)! - feat: added new visualiser feature
+
+## 0.1.15
+
+### Patch Changes
+
+- [`60bea4d`](https://github.com/boyney123/eventcatalog/commit/60bea4db471bf3c63a936b86ce7ee549e73972a6) [#182](https://github.com/boyney123/eventcatalog/pull/182) Thanks [@thim81](https://github.com/thim81)! - fix: optional title for all MDX components
+
+* [`bf5bab4`](https://github.com/boyney123/eventcatalog/commit/bf5bab44b9be92c5888c6548694c42d1fa83a678) [#184](https://github.com/boyney123/eventcatalog/pull/184) Thanks [@thim81](https://github.com/thim81)! - fix: increase node width for NodeGraph
+
+## 0.1.14
+
+### Patch Changes
+
+- [`1558d17`](https://github.com/boyney123/eventcatalog/commit/1558d17b1c9f925c8e74d22b57edbfc4195a73a6) [#178](https://github.com/boyney123/eventcatalog/pull/178) Thanks [@boyney123](https://github.com/boyney123)! - feat: added better code example component
+
+## 0.1.13
+
+### Patch Changes
+
+- [`ca01bef`](https://github.com/boyney123/eventcatalog/commit/ca01bef1659b2c364210a86e0f9e916f6c1fbaa4) [#166](https://github.com/boyney123/eventcatalog/pull/166) Thanks [@thim81](https://github.com/thim81)! - feat: new nodegraph component to render services and events
+
+## 0.1.12
+
+### Patch Changes
+
+- [`5dcc188`](https://github.com/boyney123/eventcatalog/commit/5dcc188dbd68f70b867e38df91211ba077f14189) [#175](https://github.com/boyney123/eventcatalog/pull/175) Thanks [@thim81](https://github.com/thim81)! - fix: mermaid diagram with pub/sub of same service now shows correctly
+
+## 0.1.11
+
+### Patch Changes
+
+- [`0976201`](https://github.com/boyney123/eventcatalog/commit/0976201a6949f4a78934a4ddfb75e7ea4598caae) [#172](https://github.com/boyney123/eventcatalog/pull/172) Thanks [@boyney123](https://github.com/boyney123)! - fix: header logo now reads from config
+
+## 0.1.10
+
+### Patch Changes
+
+- [`b44bd6c`](https://github.com/boyney123/eventcatalog/commit/b44bd6ca73194165e6448abebd020e3d6f3007a2) [#169](https://github.com/boyney123/eventcatalog/pull/169) Thanks [@thim81](https://github.com/thim81)! - fix: logic for services publish & subscribe nodes
+
+## 0.1.9
+
+### Patch Changes
+
+- [`c4d78c7`](https://github.com/boyney123/eventcatalog/commit/c4d78c77da6bc18638c6612e865c2c8cdd596e0b) [#139](https://github.com/boyney123/eventcatalog/pull/139) Thanks [@thim81](https://github.com/thim81)! - feat: add new eventcatalog config property to set homepage url
+
+## 0.1.8
+
+### Patch Changes
+
+- [`fd9b26a`](https://github.com/boyney123/eventcatalog/commit/fd9b26a24fd94e298b79b59777f148988a7c89b1) [#151](https://github.com/boyney123/eventcatalog/pull/151) Thanks [@thim81](https://github.com/thim81)! - feat: new mdx component json schema viewer
+
+## 0.1.7
+
+### Patch Changes
+
+- [`740c504`](https://github.com/boyney123/eventcatalog/commit/740c5041f033aff975a7ce89e99b3722b271e2b3) [#154](https://github.com/boyney123/eventcatalog/pull/154) Thanks [@boyney123](https://github.com/boyney123)! - fix: trying to fix npm versions problem
+
+## 0.1.6
+
+### Patch Changes
+
+- [`00e3c89`](https://github.com/boyney123/eventcatalog/commit/00e3c898ca8bf72bd563d246d6a2ee8620dd8284) [#143](https://github.com/boyney123/eventcatalog/pull/143) Thanks [@thim81](https://github.com/thim81)! - feat: mermaid name and link
+
+* [`b4774fb`](https://github.com/boyney123/eventcatalog/commit/b4774fbf9773e66e1f85d71e99992e699833bf99) [#141](https://github.com/boyney123/eventcatalog/pull/141) Thanks [@thim81](https://github.com/thim81)! - bug: use title when setting page title
+
+## 0.1.5
+
+### Patch Changes
+
+- [`1975995`](https://github.com/boyney123/eventcatalog/commit/1975995e2a77662742e8f7d95b827ff3cb0e4ac2) [#136](https://github.com/boyney123/eventcatalog/pull/136) Thanks [@boyney123](https://github.com/boyney123)! - fix: header link now goes to landing page
+
+## 0.1.4
+
+### Patch Changes
+
+- [`71d0b85`](https://github.com/boyney123/eventcatalog/commit/71d0b85139cb057db718c10bf5f5aa6017cfe43c) [#132](https://github.com/boyney123/eventcatalog/pull/132) Thanks [@boyney123](https://github.com/boyney123)! - fix: build directory is now copied over to the users proejct dir
+
+## 0.1.3
+
+### Patch Changes
+
+- [`904c4df`](https://github.com/boyney123/eventcatalog/commit/904c4dff59bfdac681d8c18879a5840862aeb616) [#127](https://github.com/boyney123/eventcatalog/pull/127) Thanks [@boyney123](https://github.com/boyney123)! - bug: fixed issue with purging css from the admonition component
+
+## 0.1.2
+
+### Patch Changes
+
+- [`cc8eb2f`](https://github.com/boyney123/eventcatalog/commit/cc8eb2fe14501447206bdb8fe141a0575c753636) [#121](https://github.com/boyney123/eventcatalog/pull/121) Thanks [@otbe](https://github.com/otbe)! - Allow to configure "trailingSlash"
+
+* [`dacd9eb`](https://github.com/boyney123/eventcatalog/commit/dacd9eb41e3f519341f32e60c4de27df5a9137b7) [#120](https://github.com/boyney123/eventcatalog/pull/120) Thanks [@thim81](https://github.com/thim81)! - feat: Hide owners section if the events has owners defined
+
+## 0.1.1
+
+### Patch Changes
+
+- [`23930c8`](https://github.com/boyney123/eventcatalog/commit/23930c8f4f4a9234e037473aaeccae3dafdfe385) [#114](https://github.com/boyney123/eventcatalog/pull/114) Thanks [@boyney123](https://github.com/boyney123)! - feat: adding search to events page
+
+* [`e37ff4b`](https://github.com/boyney123/eventcatalog/commit/e37ff4b31c06779ae89f2b17beb14cb409d464e3) [#113](https://github.com/boyney123/eventcatalog/pull/113) Thanks [@otbe](https://github.com/otbe)! - Configure base path
+
+## 0.1.0
+
+### Minor Changes
+
+- [`688e2da`](https://github.com/boyney123/eventcatalog/commit/688e2da9ade503e4276c6710c77e45f4652e19a1) [#111](https://github.com/boyney123/eventcatalog/pull/111) Thanks [@boyney123](https://github.com/boyney123)! - feat: catalog now staticlly exports rather than using server code
+
+## 0.0.14
+
+### Patch Changes
+
+- [`7c23703`](https://github.com/boyney123/eventcatalog/commit/7c237039535d7f5d6f229396cf59eb5cbf5b0645) [#109](https://github.com/boyney123/eventcatalog/pull/109) Thanks [@boyney123](https://github.com/boyney123)! - fix: issue with long names for services and events rendering incorrectly
+
+## 0.0.13
+
+### Patch Changes
+
+- [`732dac2`](https://github.com/boyney123/eventcatalog/commit/732dac24c1de62537732083a53c2218c2794773a) [#102](https://github.com/boyney123/eventcatalog/pull/102) Thanks [@boyney123](https://github.com/boyney123)! - feat: allow default frontmatter when creating events
+
+## 0.0.12
+
+### Patch Changes
+
+- [`dd1b29f`](https://github.com/boyney123/eventcatalog/commit/dd1b29f81658a3c5bea9ed92c1cf54265c7feb0b) [#98](https://github.com/boyney123/eventcatalog/pull/98) Thanks [@boyney123](https://github.com/boyney123)! - feat: adding more mermaid support in mdx
+
+## 0.0.11
+
+### Patch Changes
+
+- [`97e447a`](https://github.com/boyney123/eventcatalog/commit/97e447aa0ec255b2c879eac7fa83d7b705230790) [#95](https://github.com/boyney123/eventcatalog/pull/95) Thanks [@boyney123](https://github.com/boyney123)! - fix: edit url is now optional in not found pages and no longer fetche…
+
+## 0.0.10
+
+### Patch Changes
+
+- [`df372c6`](https://github.com/boyney123/eventcatalog/commit/df372c675e76a4a5980740222ccf8268c0c71540) [#91](https://github.com/boyney123/eventcatalog/pull/91) Thanks [@boyney123](https://github.com/boyney123)! - feat: fix-generator
+
+## 0.0.9
+
+### Patch Changes
+
+- [`b7202dc`](https://github.com/boyney123/eventcatalog/commit/b7202dcd7548d1d0f406ce9d979182cd4c09232a) [#82](https://github.com/boyney123/eventcatalog/pull/82) Thanks [@boyney123](https://github.com/boyney123)! - fix: event log page now displays correct name
+
+## 0.0.8
+
+### Patch Changes
+
+- [`534bec1`](https://github.com/boyney123/eventcatalog/commit/534bec11f57bcabe7f79f40338ae02bef134efc2) [#78](https://github.com/boyney123/eventcatalog/pull/78) Thanks [@thim81](https://github.com/thim81)! - feat: externalLinks for services
+
+* [`b557ff8`](https://github.com/boyney123/eventcatalog/commit/b557ff8f7186b939cbe1e23f2c0e1e9a7254c907) [#79](https://github.com/boyney123/eventcatalog/pull/79) Thanks [@boyney123](https://github.com/boyney123)! - fix: adding keys on maps in react
+
+- [`407d9e0`](https://github.com/boyney123/eventcatalog/commit/407d9e0d7f8d5eab4747ce0af6d5079204b53d21) [#75](https://github.com/boyney123/eventcatalog/pull/75) Thanks [@thim81](https://github.com/thim81)! - feat: optional editUrl config
+
+* [`9eb7463`](https://github.com/boyney123/eventcatalog/commit/9eb7463b32baa09a6dd693e7f0eede63e33cd39c) [#71](https://github.com/boyney123/eventcatalog/pull/71) Thanks [@thim81](https://github.com/thim81)! - feat: link to external event documentation added
+
+## 0.0.7
+
+### Patch Changes
+
+- [`ee17db8`](https://github.com/boyney123/eventcatalog/commit/ee17db8958ac6368f7d833f0d3ebec2604722e42) [#56](https://github.com/boyney123/eventcatalog/pull/56) Thanks [@boyney123](https://github.com/boyney123)! - feat: changelog.md files now belong inside the versioned folders
+
+## 0.0.6
+
+### Patch Changes
+
+- [`ad66a66`](https://github.com/boyney123/eventcatalog/commit/ad66a66b526a167cc8da43dd2371642c9f9029f2) [#49](https://github.com/boyney123/eventcatalog/pull/49) Thanks [@boyney123](https://github.com/boyney123)! - fix: now supports any extension for event examples also added missing docs
+
+## 0.0.5
+
+### Patch Changes
+
+- [`576debd`](https://github.com/boyney123/eventcatalog/commit/576debdfc5dbc2fbbf98e2b3f4d78b84f9a07669) [#46](https://github.com/boyney123/eventcatalog/pull/46) Thanks [@boyney123](https://github.com/boyney123)! - fix: using cross-env to fix issues with windows OS
+
+## 0.0.4
+
+### Patch Changes
+
+- [`1eb4572`](https://github.com/boyney123/eventcatalog/commit/1eb4572918ac06afb64554fef2fc1a3877fbf06d) [#44](https://github.com/boyney123/eventcatalog/pull/44) Thanks [@boyney123](https://github.com/boyney123)! - feat: added more customise options and documentation for them
+
+## 0.0.3
+
+### Patch Changes
+
+- [`23a96fc`](https://github.com/boyney123/eventcatalog/commit/23a96fc651907517cee937657be14cbf9fe95fb9) [#42](https://github.com/boyney123/eventcatalog/pull/42) Thanks [@boyney123](https://github.com/boyney123)! - fix: now remove the .next folder before we start the dev server foric…
+
+## 0.0.2
+
+### Patch Changes
+
+- [`53b27cb`](https://github.com/boyney123/eventcatalog/commit/53b27cb5bb5ab7fa8d526309c6dd50e1f17f3db1) [#39](https://github.com/boyney123/eventcatalog/pull/39) Thanks [@boyney123](https://github.com/boyney123)! - feat: removed ids from services
diff --git a/packages/core/Dockerfile.server b/packages/core/Dockerfile.server
new file mode 100644
index 000000000..4a7da649c
--- /dev/null
+++ b/packages/core/Dockerfile.server
@@ -0,0 +1,47 @@
+# This docker file is used for project development only.
+# If you are looking for your Docker File for SSR you can find one in our docs: https://www.eventcatalog.dev/docs/development/deployment/hosting-options
+
+# If you want to locally reproduce any SSR / Docker bugs, use this docker file 
+
+# FOR DEVELOPMENT ONLY, DO NOT USE THIS FOR PRODUCTION
+
+FROM node:20.19.6-trixie-slim AS runtime
+WORKDIR /app
+
+# Install pnpm
+RUN corepack enable && corepack prepare pnpm@latest --activate
+
+# Copy package files
+COPY package.json pnpm-lock.yaml ./
+
+# Copy the rest of the app
+COPY eventcatalog ./eventcatalog
+COPY examples/default ./examples/default
+COPY src ./src
+COPY scripts ./scripts
+COPY tsup.config.js ./tsup.config.js
+COPY . .   
+
+ENV PNPM_HOME=/usr/local/pnpm
+ENV PATH=$PNPM_HOME:$PATH
+
+RUN mkdir -p $PNPM_HOME \
+  && pnpm config set global-bin-dir $PNPM_HOME \
+  && pnpm add -g cross-env
+
+RUN pnpm install
+RUN pnpm run build:bin
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=4096
+
+ENV HOST=0.0.0.0
+ENV PORT=3000
+EXPOSE 3000
+
+RUN echo "HELLO"
+RUN pnpm run verify-build:catalog
+
+# Start the server
+# 
+CMD cd examples/default && node ../../dist/eventcatalog.js start
diff --git a/packages/core/README.md b/packages/core/README.md
new file mode 100644
index 000000000..a047a5070
--- /dev/null
+++ b/packages/core/README.md
@@ -0,0 +1,208 @@
+<div align="center">
+
+<!-- <h1>📖 EventCatalog</h1> -->
+<!-- <h3>The open source tool to help you discover and document your event-driven architectures</h3> -->
+
+
+
+
+<!-- [![Star on GitHub][github-star-badge]][github-star] -->
+<!-- <h3>Bring discoverability to your -->
+<!-- event-driven architectures</h3> -->
+<!-- <p>Discover, Explore and Document your Event Driven Architectures.</p> -->
+
+<!-- [![MIT License][license-badge]][license] -->
+<!-- [![PRs Welcome][prs-badge]][prs] -->
+
+
+<!-- [![Watch on GitHub][github-watch-badge]][github-watch] -->
+<!-- [![Star on GitHub][github-star-badge]][github-star] -->
+
+<!-- <hr /> -->
+
+
+
+<img width="745" alt="EventCatalog" src="./packages/core/images/example.png" />
+
+<p align="center">
+  <br/>
+  <a href="https://eventcatalog.dev">EventCatalog</a> is a documentation tool for software architectures &mdash;
+  <br/>
+  bring discoverability to complex systems.
+  <br/><br/>
+</p>
+
+<div align="center">
+
+[![main](https://github.com/event-catalog/eventcatalog/actions/workflows/verify-build.yml/badge.svg)](https://github.com/event-catalog/eventcatalog/actions/workflows/verify-build.yml)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/event-catalog/eventcatalog/blob/main/LICENSE)
+[![npm version](https://badge.fury.io/js/@eventcatalog%2Fcore.svg)](https://badge.fury.io/js/@eventcatalog/core)
+
+</div>
+
+
+<!-- 
+
+[![MIT License][license-badge]][license]
+[![PRs Welcome][prs-badge]][prs]
+<img src="https://img.shields.io/github/actions/workflow/status/event-catalog/eventcatalog/verify-build.yml"/>
+[![](https://dcbadge.limes.pink/api/server/https://discord.gg/3rjaZMmrAm?style=flat)](https://discord.gg/3rjaZMmrAm) [<img src="https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white" height="20px" />](https://www.linkedin.com/in/david-boyne/) [![blog](https://img.shields.io/badge/blog-EDA--Visuals-brightgreen)](https://eda-visuals.boyney.io/?utm_source=event-catalog-gihub) 
+ -->
+
+
+
+
+
+<!-- 
+
+<h4>Features: Documentation for Event Driven Architectures, Integration with any broker, Generator from your OpenAPI and AsyncAPI documents, Docs and Code, Markdown driven, Document Domains/Services/Messages/Schemas and more, Content versioning, Assign Owners, Schemas, OpenAPI, MDX Components and more...</h4> -->
+
+<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+[![All Contributors](https://img.shields.io/badge/all_contributors-68-orange.svg?style=flat-square)](#contributors-)
+<!-- ALL-CONTRIBUTORS-BADGE:END -->
+
+<!-- [Read the Docs](https://www.eventcatalog.dev/docs/development/getting-started/introduction) | [View Demo](https://demo.eventcatalog.dev) -->
+
+</div>
+
+## Install
+
+The **recommended** way to install the latest version of EventCatalog is by running the command below:
+```
+npx @eventcatalog/create-eventcatalog@latest my-catalog
+```
+
+Looking for help? Start with our [Getting Started](https://www.eventcatalog.dev/docs/development/getting-started/installation) guide
+
+## Documentation
+Visit our [official documentation](https://www.eventcatalog.dev/docs/development/getting-started).
+
+## Support
+Having trouble? Get help in the official [EventCatalog Discord](https://discord.gg/3rjaZMmrAm).
+
+## Demos
+
+Here are some examples of EventCatalog in action:
+
+- [Finance System](https://eventcatalog-examples-finance.vercel.app/)
+- [Healthcare System](https://eventcatalog-examples-healthcare.vercel.app/)
+- [E-Commerce System](https://demo.eventcatalog.dev/)
+- [SaaS System](https://eventcatalog-examples-saas.vercel.app/)
+
+
+## Contributing
+
+If you have any questions, features or issues please raise any issue or pull requests you like. We will try my best to get back to you.
+
+You can find the [contributing guidelines here](https://eventcatalog.dev/docs/contributing/overview).
+
+## Contributors ✨
+
+Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://boyney.io/"><img src="https://avatars.githubusercontent.com/u/3268013?v=4?s=100" width="100px;" alt="David Boyne"/><br /><sub><b>David Boyne</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=boyney123" title="Code">💻</a> <a href="#content-boyney123" title="Content">🖋</a> <a href="#design-boyney123" title="Design">🎨</a> <a href="#example-boyney123" title="Examples">💡</a> <a href="#ideas-boyney123" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/event-catalog/eventcatalog/commits?author=boyney123" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://otbe.io"><img src="https://avatars.githubusercontent.com/u/3391052?v=4?s=100" width="100px;" alt="Benjamin Otto"/><br /><sub><b>Benjamin Otto</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=otbe" title="Code">💻</a> <a href="#ideas-otbe" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/event-catalog/eventcatalog/commits?author=otbe" title="Documentation">📖</a> <a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3Aotbe" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/pongz79"><img src="https://avatars.githubusercontent.com/u/250872?v=4?s=100" width="100px;" alt="Tiago Oliveira"/><br /><sub><b>Tiago Oliveira</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=pongz79" title="Documentation">📖</a> <a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3Apongz79" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://www.bigjump.com/"><img src="https://avatars.githubusercontent.com/u/11387911?v=4?s=100" width="100px;" alt="Jay McGuinness"/><br /><sub><b>Jay McGuinness</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=jaymcguinness" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/davidkpiano"><img src="https://avatars.githubusercontent.com/u/1093738?v=4?s=100" width="100px;" alt="David Khourshid"/><br /><sub><b>David Khourshid</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=davidkpiano" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/thim81"><img src="https://avatars.githubusercontent.com/u/952446?v=4?s=100" width="100px;" alt="thim81"/><br /><sub><b>thim81</b></sub></a><br /><a href="#ideas-thim81" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3Athim81" title="Bug reports">🐛</a> <a href="https://github.com/event-catalog/eventcatalog/commits?author=thim81" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Muthuveerappanv"><img src="https://avatars.githubusercontent.com/u/33663725?v=4?s=100" width="100px;" alt="Muthu"/><br /><sub><b>Muthu</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3AMuthuveerappanv" title="Bug reports">🐛</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/tavelli"><img src="https://avatars.githubusercontent.com/u/484951?v=4?s=100" width="100px;" alt="Dan Tavelli"/><br /><sub><b>Dan Tavelli</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=tavelli" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/steppi91"><img src="https://avatars.githubusercontent.com/u/25939641?v=4?s=100" width="100px;" alt="steppi91"/><br /><sub><b>steppi91</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=steppi91" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://twitter.com/PipoPeperoni"><img src="https://avatars.githubusercontent.com/u/1152805?v=4?s=100" width="100px;" alt="Donald Pipowitch"/><br /><sub><b>Donald Pipowitch</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3Adonaldpipowitch" title="Bug reports">🐛</a> <a href="https://github.com/event-catalog/eventcatalog/commits?author=donaldpipowitch" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://unravelled.dev"><img src="https://avatars.githubusercontent.com/u/2233210?v=4?s=100" width="100px;" alt="Ken"/><br /><sub><b>Ken</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=kzhen" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://rtoro.cl"><img src="https://avatars.githubusercontent.com/u/5186897?v=4?s=100" width="100px;" alt="Rodolfo Toro"/><br /><sub><b>Rodolfo Toro</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=rtoro" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://blog.hackedbrain.com"><img src="https://avatars.githubusercontent.com/u/284152?v=4?s=100" width="100px;" alt="Drew Marsh"/><br /><sub><b>Drew Marsh</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=drub0y" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/dpwdec"><img src="https://avatars.githubusercontent.com/u/51292634?v=4?s=100" width="100px;" alt="Dec Kolakowski"/><br /><sub><b>Dec Kolakowski</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=dpwdec" title="Code">💻</a> <a href="https://github.com/event-catalog/eventcatalog/commits?author=dpwdec" title="Documentation">📖</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/dytyniuk"><img src="https://avatars.githubusercontent.com/u/1890615?v=4?s=100" width="100px;" alt="Yevhenii Dytyniuk"/><br /><sub><b>Yevhenii Dytyniuk</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=dytyniuk" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/lcsbltm"><img src="https://avatars.githubusercontent.com/u/25868958?v=4?s=100" width="100px;" alt="lcsbltm"/><br /><sub><b>lcsbltm</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=lcsbltm" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://matt.martz.codes"><img src="https://avatars.githubusercontent.com/u/978362?v=4?s=100" width="100px;" alt="Matt Martz"/><br /><sub><b>Matt Martz</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=martzcodes" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/michelgrootjans"><img src="https://avatars.githubusercontent.com/u/345770?v=4?s=100" width="100px;" alt="Michel Grootjans"/><br /><sub><b>Michel Grootjans</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=michelgrootjans" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/arturoabruzzini"><img src="https://avatars.githubusercontent.com/u/17528406?v=4?s=100" width="100px;" alt="Arturo Abruzzini"/><br /><sub><b>Arturo Abruzzini</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=arturoabruzzini" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/adlecluse"><img src="https://avatars.githubusercontent.com/u/13390934?v=4?s=100" width="100px;" alt="Ad L'Ecluse"/><br /><sub><b>Ad L'Ecluse</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=adlecluse" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/rafaelrenanpacheco"><img src="https://avatars.githubusercontent.com/u/12160864?v=4?s=100" width="100px;" alt="Rafael Renan Pacheco"/><br /><sub><b>Rafael Renan Pacheco</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=rafaelrenanpacheco" title="Code">💻</a> <a href="https://github.com/event-catalog/eventcatalog/commits?author=rafaelrenanpacheco" title="Documentation">📖</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://ldiego73.github.io/"><img src="https://avatars.githubusercontent.com/u/394222?v=4?s=100" width="100px;" alt="Luis Diego"/><br /><sub><b>Luis Diego</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=ldiego73" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://www.linkedin.com/in/danielruf/"><img src="https://avatars.githubusercontent.com/u/827205?v=4?s=100" width="100px;" alt="Daniel Ruf"/><br /><sub><b>Daniel Ruf</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=DanielRuf" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/frenkan"><img src="https://avatars.githubusercontent.com/u/859840?v=4?s=100" width="100px;" alt="Fredrik Johansson"/><br /><sub><b>Fredrik Johansson</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=frenkan" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://gaddam1987.github.io/"><img src="https://avatars.githubusercontent.com/u/2576375?v=4?s=100" width="100px;" alt="Naresh Kumar Reddy Gaddam"/><br /><sub><b>Naresh Kumar Reddy Gaddam</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=gaddam1987" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/dremonkey"><img src="https://avatars.githubusercontent.com/u/480159?v=4?s=100" width="100px;" alt="Andre Deutmeyer"/><br /><sub><b>Andre Deutmeyer</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=dremonkey" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/pebbz"><img src="https://avatars.githubusercontent.com/u/1685464?v=4?s=100" width="100px;" alt="Pebbz"/><br /><sub><b>Pebbz</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=pebbz" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://alexander.holbreich.org/"><img src="https://avatars.githubusercontent.com/u/16252784?v=4?s=100" width="100px;" alt="Alexander Holbreich"/><br /><sub><b>Alexander Holbreich</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=aholbreich" title="Documentation">📖</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://www.josedelgadoing.com/"><img src="https://avatars.githubusercontent.com/u/30370263?v=4?s=100" width="100px;" alt="José Delgado"/><br /><sub><b>José Delgado</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=jslim" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/jlee-spt"><img src="https://avatars.githubusercontent.com/u/135801616?v=4?s=100" width="100px;" alt="jlee-spt"/><br /><sub><b>jlee-spt</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=jlee-spt" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/kimrejstrom"><img src="https://avatars.githubusercontent.com/u/26428365?v=4?s=100" width="100px;" alt="Kim Rejström"/><br /><sub><b>Kim Rejström</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=kimrejstrom" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/cgabard"><img src="https://avatars.githubusercontent.com/u/6103932?v=4?s=100" width="100px;" alt="Christophe Gabard"/><br /><sub><b>Christophe Gabard</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=cgabard" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://www.waydotnet.com"><img src="https://avatars.githubusercontent.com/u/197466?v=4?s=100" width="100px;" alt="Carlo Bertini"/><br /><sub><b>Carlo Bertini</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=WaYdotNET" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/dreglad"><img src="https://avatars.githubusercontent.com/u/50302?v=4?s=100" width="100px;" alt="David Regla"/><br /><sub><b>David Regla</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=dreglad" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://blogdomarcioweb.wordpress.com/"><img src="https://avatars.githubusercontent.com/u/6377735?v=4?s=100" width="100px;" alt="Marcio Vinicius"/><br /><sub><b>Marcio Vinicius</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=marciovmartins" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/danielcastill0"><img src="https://avatars.githubusercontent.com/u/40574235?v=4?s=100" width="100px;" alt="Daniel Andres Castillo Ardila"/><br /><sub><b>Daniel Andres Castillo Ardila</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=danielcastill0" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://www.ennovative-solutions.be"><img src="https://avatars.githubusercontent.com/u/2007116?v=4?s=100" width="100px;" alt="Baerten Dennis"/><br /><sub><b>Baerten Dennis</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=debae" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ryancormack"><img src="https://avatars.githubusercontent.com/u/1962883?v=4?s=100" width="100px;" alt="Ryan Cormack"/><br /><sub><b>Ryan Cormack</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=ryancormack" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://natee.biz"><img src="https://avatars.githubusercontent.com/u/4300215?v=4?s=100" width="100px;" alt="Nathan Birrell"/><br /><sub><b>Nathan Birrell</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=nathanbirrell" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://www.jacktomlinson.co.uk/"><img src="https://avatars.githubusercontent.com/u/15871032?v=4?s=100" width="100px;" alt="Jack Tomlinson"/><br /><sub><b>Jack Tomlinson</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=jacktomlinson" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/carlosallexandre"><img src="https://avatars.githubusercontent.com/u/20143946?v=4?s=100" width="100px;" alt="Carlos Rodrigues"/><br /><sub><b>Carlos Rodrigues</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=carlosallexandre" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/XaaXaaX"><img src="https://avatars.githubusercontent.com/u/13409925?v=4?s=100" width="100px;" alt="omid eidivandi"/><br /><sub><b>omid eidivandi</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=XaaXaaX" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/hpatoio"><img src="https://avatars.githubusercontent.com/u/249948?v=4?s=100" width="100px;" alt="Simone Fumagalli"/><br /><sub><b>Simone Fumagalli</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=hpatoio" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/d-o-h"><img src="https://avatars.githubusercontent.com/u/23699653?v=4?s=100" width="100px;" alt="d-o-h"/><br /><sub><b>d-o-h</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=d-o-h" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://pallares.io"><img src="https://avatars.githubusercontent.com/u/1077520?v=4?s=100" width="100px;" alt="Cristian Pallarés"/><br /><sub><b>Cristian Pallarés</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=skyrpex" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/SebasRendon12"><img src="https://avatars.githubusercontent.com/u/69688183?v=4?s=100" width="100px;" alt="Sebastian Rendon"/><br /><sub><b>Sebastian Rendon</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=SebasRendon12" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://craig0990.co.uk"><img src="https://avatars.githubusercontent.com/u/461897?v=4?s=100" width="100px;" alt="Craig Roberts"/><br /><sub><b>Craig Roberts</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=craig0990" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Vertygo"><img src="https://avatars.githubusercontent.com/u/1658326?v=4?s=100" width="100px;" alt="Ivan Milosavljevic"/><br /><sub><b>Ivan Milosavljevic</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=Vertygo" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Mezzle"><img src="https://avatars.githubusercontent.com/u/570639?v=4?s=100" width="100px;" alt="Martin Meredith"/><br /><sub><b>Martin Meredith</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=Mezzle" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://www.linkedin.com/in/ruudwelling/"><img src="https://avatars.githubusercontent.com/u/4014179?v=4?s=100" width="100px;" alt="Ruud Welling"/><br /><sub><b>Ruud Welling</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=WellingR" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/vienin"><img src="https://avatars.githubusercontent.com/u/2124283?v=4?s=100" width="100px;" alt="Kevin Pouget"/><br /><sub><b>Kevin Pouget</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=vienin" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/VitaliiBalash"><img src="https://avatars.githubusercontent.com/u/4520809?v=4?s=100" width="100px;" alt="Vitalii Balash"/><br /><sub><b>Vitalii Balash</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=VitaliiBalash" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ababilone"><img src="https://avatars.githubusercontent.com/u/925013?v=4?s=100" width="100px;" alt="Arnaud Babilone"/><br /><sub><b>Arnaud Babilone</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=ababilone" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/alexanderhorner"><img src="https://avatars.githubusercontent.com/u/18349361?v=4?s=100" width="100px;" alt="Alexander Horner"/><br /><sub><b>Alexander Horner</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=alexanderhorner" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/simonwfarrow"><img src="https://avatars.githubusercontent.com/u/3245908?v=4?s=100" width="100px;" alt="simonwfarrow"/><br /><sub><b>simonwfarrow</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=simonwfarrow" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/augusto-romero-arango"><img src="https://avatars.githubusercontent.com/u/142316821?v=4?s=100" width="100px;" alt="Augusto Romero Arango"/><br /><sub><b>Augusto Romero Arango</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=augusto-romero-arango" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/cc-stjm"><img src="https://avatars.githubusercontent.com/u/47748595?v=4?s=100" width="100px;" alt="cc-stjm"/><br /><sub><b>cc-stjm</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=cc-stjm" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://www.linkedin.com/in/lucianlature/"><img src="https://avatars.githubusercontent.com/u/24992?v=4?s=100" width="100px;" alt="Lucian Lature"/><br /><sub><b>Lucian Lature</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3Alucianlature" title="Bug reports">🐛</a> <a href="https://github.com/event-catalog/eventcatalog/commits?author=lucianlature" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/villAsh"><img src="https://avatars.githubusercontent.com/u/50195101?v=4?s=100" width="100px;" alt="Vilas Chauvhan"/><br /><sub><b>Vilas Chauvhan</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=villAsh" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/mrerichoffman"><img src="https://avatars.githubusercontent.com/u/7565432?v=4?s=100" width="100px;" alt="Eric Hoffman"/><br /><sub><b>Eric Hoffman</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3Amrerichoffman" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/wimhaesen-kine"><img src="https://avatars.githubusercontent.com/u/231914377?v=4?s=100" width="100px;" alt="wimhaesen-kine"/><br /><sub><b>wimhaesen-kine</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=wimhaesen-kine" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://www.ondrejmusil.cz"><img src="https://avatars.githubusercontent.com/u/959390?v=4?s=100" width="100px;" alt="Ondrej Musil"/><br /><sub><b>Ondrej Musil</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3Afreaz" title="Bug reports">🐛</a> <a href="#ideas-freaz" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/anatolybolshakov"><img src="https://avatars.githubusercontent.com/u/8779682?v=4?s=100" width="100px;" alt="Anatoly Bolshakov"/><br /><sub><b>Anatoly Bolshakov</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=anatolybolshakov" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/reisingerf"><img src="https://avatars.githubusercontent.com/u/31906163?v=4?s=100" width="100px;" alt="reisingerf"/><br /><sub><b>reisingerf</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=reisingerf" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/jbarette-rossel"><img src="https://avatars.githubusercontent.com/u/162966566?v=4?s=100" width="100px;" alt="Jonathan Barette"/><br /><sub><b>Jonathan Barette</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=jbarette-rossel" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/mumundum"><img src="https://avatars.githubusercontent.com/u/196062898?v=4?s=100" width="100px;" alt="mumundum"/><br /><sub><b>mumundum</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/commits?author=mumundum" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://www.argonus.tech"><img src="https://avatars.githubusercontent.com/u/9743549?v=4?s=100" width="100px;" alt="Piotr Rybarczyk"/><br /><sub><b>Piotr Rybarczyk</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3AArgonus" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ZakaryaCH"><img src="https://avatars.githubusercontent.com/u/45012800?v=4?s=100" width="100px;" alt="ZakaryaCH"/><br /><sub><b>ZakaryaCH</b></sub></a><br /><a href="https://github.com/event-catalog/eventcatalog/issues?q=author%3AZakaryaCH" title="Bug reports">🐛</a></td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+
+# License
+
+MIT.
diff --git a/packages/core/bin/eventcatalog.config.d.ts b/packages/core/bin/eventcatalog.config.d.ts
new file mode 100644
index 000000000..6a6173f5c
--- /dev/null
+++ b/packages/core/bin/eventcatalog.config.d.ts
@@ -0,0 +1 @@
+export type { Config } from '../dist/eventcatalog.config.js';
diff --git a/bin/eventcatalog.js b/packages/core/bin/eventcatalog.js
similarity index 100%
rename from bin/eventcatalog.js
rename to packages/core/bin/eventcatalog.js
diff --git a/packages/core/docs/api/01-overview.md b/packages/core/docs/api/01-overview.md
new file mode 100644
index 000000000..f88ec88ea
--- /dev/null
+++ b/packages/core/docs/api/01-overview.md
@@ -0,0 +1,74 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog CLI
+sidebar_label: EventCatalog CLI
+title: EventCatalog CLI
+description: Understand the CLI of EventCatalog
+---
+
+EventCatalog provides a set of scripts to help you generate, serve, and deploy your catalog.
+
+Once your catalog is bootstrapped, the source will contain the EventCatalog scripts that you can invoke with your package manager:
+
+```json title="package.json"
+{
+  // ...
+  "scripts": {
+    // Runs the dev server locally
+    "dev": "eventcatalog dev",
+    // Builds the catalog
+    "build": "eventcatalog build",
+
+    // start/preview both run the built catalog locally.
+    "start": "eventcatalog start",
+    "preview": "eventcatalog preview",
+
+    // Export your catalog as JSON
+    "export": "eventcatalog export",
+  }
+}
+```
+
+import TOCInline from "@theme/TOCInline"
+
+<TOCInline toc={toc} minHeadingLevel={3}/>
+
+## EventCatalog CLI commands {#eventcatalog-cli-commands}
+
+Below is a list of EventCatalog CLI commands and their usages:
+
+### `eventcatalog dev` {#eventcatalog-dev-sitedir}
+
+Runs your catalog in development mode.
+
+This will start the dev server and watch for changes to your catalog. You will use this as you develop your catalog.
+
+
+### `eventcatalog start/preview` {#eventcatalog-start-sitedir}
+
+Runs EventCatalog in production mode, requires a `build` first. This will serve the built catalog from the `dist` folder.
+
+Can be used to preview your catalog before deploying.
+
+### `eventcatalog build` {#eventcatalog-build-sitedir}
+
+Builds your catalog for production, and outputs the catalog to the `dist` folder.
+
+### `eventcatalog export` {#eventcatalog-export}
+
+Exports your entire catalog as a JSON file using the SDK's `dumpCatalog` function. The export is saved to the `exports/` directory in your project with a date stamp (e.g. `exports/catalog-2026-03-30.json`).
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--include-markdown` | Include markdown content in the export (default: `false`) |
+
+```bash
+# Export catalog as JSON
+eventcatalog export
+
+# Export with markdown content included
+eventcatalog export --include-markdown
+```
diff --git a/packages/core/docs/api/02-config.md b/packages/core/docs/api/02-config.md
new file mode 100644
index 000000000..544e7b05e
--- /dev/null
+++ b/packages/core/docs/api/02-config.md
@@ -0,0 +1,1136 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog api
+sidebar_label: eventcatalog.config.js
+title: eventcatalog.config.js
+description: Understanding the configuration file for EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+## Overview {#overview}
+
+`eventcatalog.config.js` contains configurations for your site and is placed in the root directory of your site.
+
+## Required fields {#required-fields}
+
+### `cId` {#cId}
+
+- Type: `string`
+
+An automated generated ID for your catalog. EventCatalog will generate this for you.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  cId: '107fdebb-7c68-42cc-975d-413b1d30d758',
+};
+```
+
+### `title` {#title}
+
+- Type: `string`
+
+Title for your website.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  title: 'EventCatalog',
+};
+```
+
+### `organizationName` {#organizationName}
+
+- Type: `string`
+
+Your organization name.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  organizationName: 'Your Company',
+};
+```
+
+## Optional fields {#optional-fields}
+
+### `base` {#base}
+
+- Type: `string`
+- Default value: `/`
+
+The base path to deploy to. EventCatalog will use this path as the root for your pages and assets both in development and in production build.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  base: '/',
+};
+```
+
+### `output` {#output}
+
+<AddedIn version="2.35.4" />
+
+- Type: `string`
+- Default value: `static`
+
+The output type for your EventCatalog, choose from `static` or `server`.
+
+:::info "What is the difference between static and server?"
+
+- `static` - The default output type for EventCatalog. This will output a static website that you can host anywhere.
+- `server` - This will output a Node.js server that you can host anywhere. This is required for certain features like the [EventCatalog Chat](/features/ai-assistant) (bring your own keys). The easiest way to host this is with our [Docker image](/docs/development/deployment/hosting-options#hosting-a-server).
+
+:::
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  output: 'static',
+};
+```
+
+### `outDir` {#outDir}
+
+<AddedIn version="2.11.4" />
+
+- Type: `string`
+- Default value: `dist`
+
+The output path of your EventCatalog. By default it will output to the `dist` folder.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  // Catalog would output to the /build folder
+  outDir: 'build',
+};
+```
+
+### `trailingSlash` {#trailingSlash}
+
+- Type: `boolean`
+- Default: `false`
+
+Set the route matching behavior of the dev server. Choose from the following options:
+
+'true' - Only match URLs that include a trailing slash (ex: “/foo/“)
+'false' - Match URLs regardless of whether a trailing ”/” exists
+
+Use this configuration option if your production host has strict handling of how trailing slashes work or do not work.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  // Setting to true will add / onto all routes e.g http://website.com/visualiser/
+  trailingSlash: true,
+};
+```
+
+### `port` {#port}
+
+- Type: `number`
+- Default: 3000
+
+Configure the port EventCatalog is running on.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  // Changes the port from default 3000 to 5000
+  port: 5000,
+};
+```
+
+### `host` {#host}
+
+<AddedIn version="2.42.9" />
+
+- Type: `string` | `boolean`
+- Default: `false`
+
+Set which network IP addresses the dev server should listen on (i.e. non-localhost IPs).
+
+- `false` - do not expose on a network IP address
+- `true` - listen on all addresses, including LAN and public addresses
+- `[custom-address]` - expose on a network IP address at `[custom-address]`
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  host: '0.0.0.0',
+};
+```
+
+### `server.allowedHosts` {#server.allowedHosts}
+
+<AddedIn version="2.64.0" />
+
+- Type: `string[]` | `true`
+- Default: `[]`
+
+A list of hostnames that Astro is allowed to respond to. When the value is set to true, any hostname is allowed.
+
+You can read more on the Astro documentation [here](https://docs.astro.build/en/reference/configuration-reference/#serverallowedhosts).
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  server: {
+    allowedHosts: ['example.com', 'subdomain.example.com'],
+  },
+};
+```
+
+### `security` {#security}
+
+<AddedIn version="3.39.2" />
+
+- Type: `Record<"checkOrigin", boolean> | undefined`
+- Default: `{checkOrigin: true}`
+
+Enables security measures for an EventCatalog website.
+
+These features only exist for pages rendered on demand (SSR) using server mode or pages that opt out of prerendering in static mode.
+
+By default, EventCatalog will automatically check that the “origin” header matches the URL sent by each request in on-demand rendered pages. You can disable this behavior by setting checkOrigin to false:
+
+You can read more on the Astro documentation [here](https://docs.astro.build/en/reference/configuration-reference/#security).
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  output: "server",
+  security: {
+    checkOrigin: false
+  }
+};
+```
+
+### `generators` {#generators}
+
+- Type: `Generator[]`
+- Default: `[]`
+
+Generators are the foundation of plugins with EventCatalog. EventCatalog will call your generators on build.
+
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  generators: [
+    [
+      // This will load plugin.js in the root of your catalog
+      '<rootDir>/plugin.js',
+      // configuration for your generator
+      {
+        customValue: true,
+        test: "Add any configuration values you want"
+      },
+    ],
+  ],
+};
+```
+
+### `environments` {#environment}
+
+<AddedIn version="2.48.2" />
+
+- Type: `object`
+- Default: `{}`
+
+Optional configuration for EventCatalog environments.
+
+When environments are set, a dropdown will be shown in the top right of the EventCatalog allowing your users to switch between environments.
+
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  environments: [
+    {
+      // Name of the environment
+      name: 'Development',
+      // URL of the environment
+      url: 'https://demo.eventcatalog.dev',
+      // Description of the environment
+      description: 'Local development environment',
+      // Short name of the environment (optional, used in the dropdown)
+      shortName: 'Dev'
+    },
+    {
+      name: 'Test',
+      url: 'https://demo.eventcatalog.dev',
+      description: 'Test environment for QA',
+      shortName: 'Test'
+    },
+    {
+      name: 'Production',
+      url: 'https://demo.eventcatalog.dev',
+      description: 'Production environment',
+      shortName: 'Prod'
+    },
+  ]
+};
+```
+
+### `landingPage` {#landingPage}
+
+- Type: `string`
+- Default: `'/docs'`
+
+Configure the landing page URL your EventCatalog loads. By default EventCatalog loads `/` (the default or [custom landing page](/docs/development/customization/customize-landing-page#how-to-customize-your-landing-page)).
+
+Clicking on the EventCatalog logo (or [your custom logo](/docs/api/config#logo)), will also go to this URL.
+
+If you set this value the `Home` icon in the Application sidebar will not be shown and your users will be redirected to this default URL.
+
+You can set this to any EventCatalog page URL. 
+
+Examples:
+
+- `/visualiser`
+- `/discover/events`
+- `/docs/services/InventoryService/0.0.2`
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  landingPage: '/visualiser',
+};
+```
+
+### `navigation` {#navigation}
+
+<AddedIn version="4.0" />
+
+- Type: `object`
+
+Configure navigation in EventCatalog.
+
+Use `navigation.groups` to configure the [Application sidebar](/docs/development/customization/application-sidebar).
+
+Use `navigation.pages` to configure the [Documentation sidebar](/docs/development/customization/documentation-sidebar) shown on `/docs/*` pages.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    groups: [
+      {
+        id: 'main',
+        items: [{ id: 'home' }, { id: 'docs' }],
+      },
+      {
+        id: 'browse',
+        label: 'Browse',
+        items: [
+          { id: 'catalog' },
+          { id: 'schemas' },
+          { id: 'schema-insights', visible: false },
+        ],
+      },
+      {
+        id: 'organization',
+        label: 'Organization',
+        items: [{ id: 'teams' }, { id: 'users' }],
+      },
+      {
+        id: 'settings',
+        position: 'bottom',
+        items: [{ id: 'settings' }],
+      },
+    ],
+    pages: ['list:top-level-domains', 'list:all'],
+  },
+};
+```
+
+#### `navigation.groups`
+
+`navigation.groups` configures the Application sidebar that appears across EventCatalog.
+
+If you do not configure `navigation.groups`, EventCatalog renders the default Application sidebar.
+
+If you do configure `navigation.groups`, your groups replace the default Application sidebar. Add every item you want users to see.
+
+Built-in Application sidebar item IDs include:
+
+- `home`
+- `docs`
+- `catalog`
+- `schemas`
+- `schema-insights`
+- `teams`
+- `users`
+- `settings`
+
+You can also reference built-in route IDs directly, such as `/schemas/explorer`, `/directory/teams`, or `/settings/general`.
+
+Groups support:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Unique group identifier. |
+| `label` | `string` | Optional label shown above the group. |
+| `visible` | `boolean` | Set to `false` to hide the group. |
+| `position` | `'top' \| 'bottom'` | Use `bottom` for groups pinned below the main navigation. Defaults to `top`. |
+| `items` | `array` | Navigation items in this group. |
+
+Items support:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Built-in item id, route id, or custom item id. |
+| `label` | `string` | Custom label. Required for custom items. |
+| `icon` | `string` | Any icon exported by [lucide-react](https://lucide.dev/icons/), such as `House`, `BookOpen`, or `LifeBuoy`. |
+| `href` | `string` | Required for custom items. Built-in items provide their own `href`. |
+| `visible` | `boolean` | Set to `false` to hide the item. |
+| `match` | `string \| string[]` | Paths that should mark the item as active. Useful for custom navigation items. |
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    groups: [
+      {
+        id: 'platform',
+        label: 'Platform',
+        items: [
+          {
+            id: 'platform-docs',
+            label: 'Platform Docs',
+            icon: 'BookOpen',
+            href: '/docs/custom/platform/overview',
+            match: ['/docs/custom/platform'],
+          },
+          {
+            id: 'support',
+            label: 'Support',
+            icon: 'LifeBuoy',
+            href: 'https://support.example.com',
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+External `href` values open in a new tab.
+
+#### `navigation.pages`
+
+`navigation.pages` configures the context-aware Documentation sidebar shown on `/docs/*` pages.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    pages: ['list:top-level-domains', 'list:all'],
+  },
+};
+```
+
+See [Documentation sidebar](/docs/development/customization/documentation-sidebar) for all supported list, resource, group, and custom link options.
+
+:::note Migrating from `sidebar`
+
+In v3 you could show or hide Application sidebar items using the top-level `sidebar` property.
+
+In v4 this has been replaced by `navigation.groups`.
+
+The `SideBarConfig` type is no longer exported.
+
+:::
+
+### `visualiser` {#visualiser}
+
+<AddedIn version="2.42.0" />
+
+- Type: `object`
+
+Configuration for the [EventCatalog visualiser](/features/visualization).
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  visualiser: {
+    // visualizer is enabled by default
+    // you can turn it off by setting it to false
+    enabled: true,
+
+    channels: {
+      // The render mode for channels in the visualiser
+      // Flat or single
+      renderMode: 'flat'
+    }
+  }
+};
+```
+
+<!-- Table of configuration -->
+| Configuration | Option | Default | Description |
+| ------------- | ----------- | ----------- | ----------- |
+| `visualiser.enabled` | `true` or `false` | `true` | **Enabled or disables the visualiser**. Setting this to false will not render any visualiser pages in your catalog and also remove references to the visualiser features in your catalog. _(Added in 2.65.1)_ |
+| `visualiser.channels.renderMode` | `flat` or `single` | `flat` | The render mode for the visualiser. `flat` means the channel node is duplicated for each message. `single` means the channel node is a single node for all messages. Depending on your use case/preferences you may want to use one or the other. |
+
+
+
+
+
+
+### `docs` {#docs}
+
+- Type: `object`
+
+Configure documentation rendering options in EventCatalog.
+
+Use `docs.sidebar` for the Documentation sidebar render mode and orphaned message behavior.
+
+Use [`navigation.pages`](#navigationpages) when you want to choose which resources, groups, and custom links appear in the [Documentation sidebar](/docs/development/customization/documentation-sidebar).
+
+```js title="eventcatalog.config.js"
+module.exports = {
+   docs: {
+    sidebar: {
+      type: 'LIST_VIEW'
+    }
+  }
+};
+```
+
+Configuration for the Documentation sidebar render mode.
+
+### `docs.sidebar` options
+
+#### Sidebar Type
+
+You can choose between `LIST_VIEW` or `TREE_VIEW` to render your documentation.
+
+- `LIST_VIEW` will render your docs as you see in the [demo](https://demo.eventcatalog.dev/docs/) 
+- `TREE_VIEW` will render the DOCS as a tree view and map your file system folder structure.
+   - Can be useful for large catalogs and navigation
+
+<AddedIn version="2.28.0" />
+
+
+```js title="eventcatalog.config.js"
+docs: {
+    sidebar: {
+      type: 'LIST_VIEW'
+    },
+  },
+```
+
+### Show/Hide Orphaned Messages
+
+<AddedIn version="2.61.8" />
+
+Any messages that do not belong to a service will be shown as orphaned messages in the sidebar (LIST_VIEW only).
+
+If you wish to hide orphaned messages you can set the `showOrphanedMessages` to `false`.
+
+```js title="eventcatalog.config.js"
+docs: {
+    sidebar: {
+      type: 'LIST_VIEW',
+      // Default is true
+      showOrphanedMessages: false,
+    },
+  },
+```
+
+### `chat` {#chat}
+
+- Type: `object`
+
+Configuration for the EventCatalog AI chat feature.
+
+:::info
+The `chat` property requires a Starter or Scale plan and `output: 'server'` to take effect.
+:::
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  output: 'server',
+  chat: {
+    // Set to false to disable the AI chat feature entirely
+    enabled: false,
+  },
+};
+```
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `chat.enabled` | `boolean` | `true` | Enables or disables the AI chat feature. Set to `false` to hide the chat UI and prevent chat requests even when all other prerequisites are met. |
+
+### `search` {#search}
+
+<AddedIn version="3.36.0" />
+
+- Type: `object`
+
+Configure the search mode for your catalog.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  search: {
+    type: 'resource', // default
+  },
+};
+```
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `search.type` | `'resource'` \| `'indexed'` | `'resource'` | `'resource'` searches resource metadata only. `'indexed'` enables full-content search powered by [Pagefind](https://pagefind.app/) and builds a static index at build time. |
+
+See the [Search customization](/docs/development/customization/search) guide for details and trade-offs.
+
+### `changelog` {#changelog}
+
+- Type: `object`
+
+Configuration for EventCatalog Changelog.
+
+**Changelogs are disabled by default.**
+
+You can enable changelogs by setting `enabled` to `true`.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  changelog: {
+    // Default is false
+    enabled: true,
+  },
+};
+```
+
+### `editUrl` {#editUrl}
+
+- Type: `string`
+
+URL used when people want to edit the documentation. For example your GitHub repo and branch.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+};
+```
+
+### `repositoryUrl` {#repositoryUrl}
+
+<AddedIn version="2.42.3" />
+
+- Type: `string`
+
+:::tip
+For Stater or Scale plans. This gives you the ability to show your own GitHub repository in EventCatalog (in the header bar).
+:::
+
+URL to your repository for EventCatalog.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  repositoryUrl: 'https://github.com/boyney123/eventcatalog-demo',
+};
+```
+
+### `logo` {#logo}
+
+- Type: `object`
+
+Logo, alt and text for your company logo.
+
+:::tip Public directory
+Add your logo to your `/public` directory.
+:::
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  logo: {
+    // This logo is located at public/logo.svg
+    src: '/logo.svg',
+    alt: 'Company logo',
+    text: 'Urban Slice | EventCatalog',
+  },
+};
+```
+
+**Example output**
+
+![./logo.png](./logo.png)
+
+### `homepageLink` {#homepageLink}
+
+- Type: `string`
+
+URL used when people want to link the logo & title in the top navigation to the homepage of a website.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  homepageLink: 'https://eventcatalog.dev',
+};
+```
+
+### `mdxOptimize` {#mdxOptimize}
+
+- Type: `string`
+
+This is an optional configuration setting to optimize the MDX output for faster builds. This may be useful if you have many catalog files and notice slow builds. However, this option may generate some unescaped HTML, so make sure your catalog interactive parts still work correctly after enabling it.
+
+This is disabled by default. 
+
+Read [Astro documentation on optimize for MDX](https://docs.astro.build/en/guides/integrations-guide/mdx/#optimize) for more information.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  mdxOptimize: true
+};
+```
+
+### `compress` {#compress}
+
+<AddedIn version="2.48.5" />
+
+- Type: `boolean`
+
+Setting this to true will automatically compress all your CSS, HTML, SVG, JavaScript, JSON and image files in the Astro outDir folder.
+
+This is disabled by default from EventCatalog v2.61.9.
+
+**This only works for static builds.**
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  compress: true
+};
+```
+
+### `asyncAPI.renderParsedSchemas` {#asyncAPI.renderParsedSchemas}
+
+<AddedIn version="2.12.1" />
+
+- Type: `boolean`
+
+EventCatalog will render your AsyncAPI files into their own pages. By default EventCatalog will read your AsyncAPI files and parse your schemas to render them on the screen. Part of this process is validating your schemas and also adding metadata onto them (default).
+
+If you want to keep your schemas as they are then you can set the `asyncAPI.renderParsedSchemas` to false. 
+
+:::tip Having issues rendering AsyncAPI files?
+If you are having issues seeing or rendering your AsyncAPI file try setting the renderParsedSchemas to `false`
+:::
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  asyncAPI: {
+    renderParsedSchemas: false // default is true
+  }
+};
+```
+
+### `mermaid` {#mermaid}
+
+<AddedIn version="2.18.1" />
+
+- Type: `object`
+
+EventCatalog uses [mermaid](https://mermaid.js.org/) to render diagrams.
+
+Using mermaid you can render icons in your diagrams (e.g [AWS architecture icons](/docs/development/components/diagram-syntax/mermaid#architecture-diagrams-with-icons)).
+
+<img src="/img/mermaid/mermaid-custom-icons.png" alt="Example output of mermaid" style={{width: "20%"}}/>
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  mermaid: {
+    iconPacks: ['logos'], // will load https://icones.js.org/collection/logos into eventcatalog
+    maxTextSize: 100000 // maximum text size for Mermaid diagrams (default: 100000)
+  }
+};
+```
+
+You can choose from over **200,000 icons** from [icones.js.org](https://icones.js.org/collection/logos).
+
+#### `mermaid.iconPacks`
+
+<AddedIn version="2.18.1" />
+
+- Type: `string[]`
+- Default: `[]`
+
+Icon packs to load from [icones.js.org](https://icones.js.org/). Use icon pack names like `['logos', 'mdi']` to load AWS, Azure, and other service icons.
+
+[Learn more about using icons in mermaid diagrams](/docs/development/components/diagram-syntax/mermaid#architecture-diagrams-with-icons).
+
+#### `mermaid.maxTextSize`
+
+<AddedIn version="3.9.1" />
+
+- Type: `number`
+- Default: `100000`
+
+Maximum text size for Mermaid diagrams in characters. Increase this value if you have large diagrams that fail to render.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  mermaid: {
+    maxTextSize: 200000 // Allow larger diagrams
+  }
+};
+```
+
+### `rss` {#rss}
+
+<AddedIn version="2.21.1" />
+
+- Type: `object`
+- Default: `{ enabled: false, limit: 15 }`
+
+Configure RSS feeds for catalog resources. RSS feeds are disabled by default.
+
+When enabled, EventCatalog creates feeds for messages, services, domains, flows, and an `all` feed that combines the latest changes across supported resource types.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  rss: {
+    enabled: true,
+    limit: 20,
+  },
+};
+```
+
+#### `rss.enabled`
+
+- Type: `boolean`
+- Default: `false`
+
+Turns RSS feeds on or off.
+
+#### `rss.limit`
+
+- Type: `number`
+- Default: `15`
+
+Controls the maximum number of items returned in each feed.
+
+Items are ordered by the last updated date of the resource file, with the most recently changed items first.
+
+#### Feed URLs
+
+After RSS is enabled, EventCatalog serves feeds at these paths:
+
+| Feed | Path | Demo |
+| --- | --- | --- |
+| Events | `/rss/events/rss.xml` | [View demo](https://demo.eventcatalog.dev/rss/events/rss.xml) |
+| Commands | `/rss/commands/rss.xml` | [View demo](https://demo.eventcatalog.dev/rss/commands/rss.xml) |
+| Queries | `/rss/queries/rss.xml` | [View demo](https://demo.eventcatalog.dev/rss/queries/rss.xml) |
+| Services | `/rss/services/rss.xml` | [View demo](https://demo.eventcatalog.dev/rss/services/rss.xml) |
+| Domains | `/rss/domains/rss.xml` | [View demo](https://demo.eventcatalog.dev/rss/domains/rss.xml) |
+| Flows | `/rss/flows/rss.xml` | [View demo](https://demo.eventcatalog.dev/rss/flows/rss.xml) |
+| Everything | `/rss/all/rss.xml` | [View demo](https://demo.eventcatalog.dev/rss/all/rss.xml) |
+
+### `llms.txt` {#llms.txt}
+
+<AddedIn version="2.20.0" />
+
+Enable tools like Claude, ChatGPT, GitHub Copilot, and Cursor to quickly understand your EventCatalog. When enabled, your catalog is accessible at `/llms.txt` and `/llms-full.txt`.
+
+```js title="eventcatalog.config.js"
+{
+  llmsTxt: {
+    enabled: true,
+  }
+}
+```
+
+See the [LLMs documentation](/docs/development/ask-your-architecture/llms.txt) for more information, how you can use it and examples.
+
+
+### `fullCatalogAPIEnabled` {#fullCatalogAPIEnabled}
+
+<AddedIn version="3.10.2" />
+
+- Type: `boolean`
+- Default: `true`
+
+Enable or disable the full catalog API which allows you to get the full catalog dump in the `/api/catalog` endpoint.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  api: {
+    fullCatalogAPIEnabled: false, // default is true
+  }
+};
+```
+### `domains` {#domains}
+
+<AddedIn version="2.63.0" />
+
+- Type: `object`
+
+Configuration for the domains table.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  domains: {
+    tableConfiguration: {
+      columns: {
+        name: { visible: true, label: 'Name' },
+        summary: { visible: true, label: 'Summary' },
+        services: { visible: true, label: 'Services' },
+        badges: { visible: true, label: 'Badges' },
+        actions: { visible: true, label: 'Actions' },
+      }
+    }
+  }
+};
+```
+
+See the [Customize tables](/docs/development/customization/customize-tables) documentation for more information and examples.
+
+### `systems` {#systems}
+
+<AddedIn version="4.0" />
+
+- Type: `object`
+
+Configuration for the systems table.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  systems: {
+    tableConfiguration: {
+      columns: {
+        name: { visible: true, label: 'System' },
+        summary: { visible: true, label: 'Summary' },
+        services: { visible: true, label: 'Services' },
+        flows: { visible: true, label: 'Flows' },
+        badges: { visible: true, label: 'Badges' },
+        actions: { visible: true, label: 'Actions' },
+      }
+    }
+  }
+};
+```
+
+See the [Customize tables](/docs/development/customization/customize-tables) documentation for more information and examples.
+
+### `events` {#events}
+
+<AddedIn version="2.63.0" />
+
+- Type: `object`
+
+Configuration for the events table.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  events: {
+    tableConfiguration: { 
+      columns: {
+        name: { visible: true, label: 'Name' },
+        summary: { visible: true, label: 'Summary' },
+        producers: { visible: true, label: 'Producers' },
+        consumers: { visible: true, label: 'Consumers' },
+        badges: { visible: true, label: 'Badges' },
+        actions: { visible: true, label: 'Actions' },
+      }
+    }
+  }
+};
+```
+
+See the [Customize tables](/docs/development/customization/customize-tables) documentation for more information and examples.
+
+### `queries` {#queries}
+
+<AddedIn version="2.63.0" />
+
+- Type: `object`
+
+Configuration for the queries table.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  queries: {
+    tableConfiguration: { 
+      columns: {
+        name: { visible: true, label: 'Name' },
+        summary: { visible: true, label: 'Summary' },
+        producers: { visible: true, label: 'Producers' },
+        consumers: { visible: true, label: 'Consumers' },
+        badges: { visible: true, label: 'Badges' },
+        actions: { visible: true, label: 'Actions' },
+      }
+    }
+  }
+};
+```
+
+### `commands` {#commands}
+
+<AddedIn version="2.63.0" />
+
+- Type: `object`
+
+Configuration for the commands table.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  commands: {
+    tableConfiguration: {
+      columns: {
+        name: { visible: true, label: 'Name' },
+        summary: { visible: true, label: 'Summary' },
+        producers: { visible: true, label: 'Producers' },
+        consumers: { visible: true, label: 'Consumers' },
+        badges: { visible: true, label: 'Badges' },
+        actions: { visible: true, label: 'Actions' },
+      }
+    }
+  }
+};
+```
+
+See the [Customize tables](/docs/development/customization/customize-tables) documentation for more information and examples.
+
+### `services` {#services}
+
+<AddedIn version="2.63.0" />
+
+- Type: `object`
+
+Configuration for the services table.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  services: {
+    tableConfiguration: {
+      columns: {
+        name: { visible: true, label: 'Name' },
+        summary: { visible: true, label: 'Summary' },
+        sends: { visible: true, label: 'Sends' },
+        receives: { visible: true, label: 'Receives' },
+        badges: { visible: true, label: 'Badges' },
+        actions: { visible: true, label: 'Actions' },
+      }
+    }
+  }
+};  
+```
+
+See the [Customize tables](/docs/development/customization/customize-tables) documentation for more information and examples.
+
+### `containers` {#containers}
+
+<AddedIn version="2.63.0" />
+
+- Type: `object`
+
+Configuration for the containers table.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  containers: {
+    tableConfiguration: {
+      columns: {
+        name: { visible: true, label: 'Name' },
+        summary: { visible: true, label: 'Summary' },
+        writes: { visible: true, label: 'Writes' },
+        reads: { visible: true, label: 'Reads' },
+        badges: { visible: true, label: 'Badges' },
+        actions: { visible: true, label: 'Actions' },
+      }   
+    }
+  }
+};
+```
+
+See the [Customize tables](/docs/development/customization/customize-tables) documentation for more information and examples.
+
+### `flows` {#flows}
+
+<AddedIn version="2.63.0" />
+
+- Type: `object`
+
+Configuration for the flows table.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  flows: {
+    tableConfiguration: {
+      columns: {
+        name: { visible: true, label: 'Name' },
+        summary: { visible: true, label: 'Summary' },
+        version: { visible: true, label: 'Version' },
+        badges: { visible: true, label: 'Badges' },
+        actions: { visible: true, label: 'Actions' },
+      }
+    }
+  }
+};
+```
+
+See the [Customize tables](/docs/development/customization/customize-tables) documentation for more information and examples.
+
+### `users` {#users}
+
+<AddedIn version="2.63.0" />
+
+- Type: `object`
+
+Configuration for the users table.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  users: {
+    tableConfiguration: {
+      columns: {
+        name: { visible: true, label: 'Name' },
+        email: { visible: true, label: 'Email' },
+        slackDirectMessageUrl: { visible: true, label: 'Slack URL' },
+        summary: { visible: true, label: 'Summary' },
+        badges: { visible: true, label: 'Badges' },
+        actions: { visible: true, label: 'Actions' },
+      }
+    }
+  }
+};
+```
+
+See the [Customize tables](/docs/development/customization/customize-tables) documentation for more information and examples.
+
+### `scalarConfiguration` {#scalarConfiguration}
+
+- Type: `object`
+
+Pass custom configuration directly to the [Scalar](https://scalar.com/) OpenAPI reference component. Any properties set here are spread into Scalar's configuration, allowing you to override or extend the defaults EventCatalog applies.
+
+This is useful when you need Scalar-specific behaviour such as routing API requests through a proxy, changing the theme, or disabling built-in UI controls.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  scalarConfiguration: {
+    // Route OpenAPI requests through a proxy
+    proxy: 'https://proxy.example.com',
+  },
+};
+```
+
+Refer to the [Scalar configuration reference](https://github.com/scalar/scalar/blob/main/documentation/configuration.md) for the full list of supported options.
+
+:::info Note on defaults
+EventCatalog sets several Scalar options by default (such as `theme`, `showSidebar`, and `hideDarkModeToggle`). Any matching keys in `scalarConfiguration` will override these defaults.
+:::
+
+### `teams` {#teams}
+
+<AddedIn version="2.63.0" />
+
+- Type: `object`
+
+Configuration for the teams table.
+
+```js title="eventcatalog.config.js"  
+module.exports = {
+  teams: {
+    tableConfiguration: {
+      columns: {
+        name: { visible: true, label: 'Name' },
+        summary: { visible: true, label: 'Summary' },
+        badges: { visible: true, label: 'Badges' },
+        actions: { visible: true, label: 'Actions' },
+      }
+    }
+  }
+};
+```
+
+See the [Customize tables](/docs/development/customization/customize-tables) documentation for more information and examples.
diff --git a/packages/core/docs/api/08-code-blocks.md b/packages/core/docs/api/08-code-blocks.md
new file mode 100644
index 000000000..85d292005
--- /dev/null
+++ b/packages/core/docs/api/08-code-blocks.md
@@ -0,0 +1,53 @@
+---
+sidebar_position: 6
+sidebar_label: Code blocks
+title: Code blocks
+description: Understanding what is possible with EventCatalog code blocks
+---
+
+EventCatalog is powered by markdown files, this allows you to add custom code blocks.
+
+EventCatalog is using [expressive-code](https://expressive-code.com/) which provides a range of additional features for your code blocks.
+
+**Features include:**
+
+- [Editor & Terminal Frames](https://expressive-code.com/key-features/frames/)
+- [Text & Line Markers](https://expressive-code.com/key-features/text-markers/)
+  - [Adding labels to line markers](https://expressive-code.com/key-features/text-markers/#adding-labels-to-line-markers) - Great way to give context to your example code.
+  - [Using diff-like syntax](https://expressive-code.com/key-features/text-markers/#using-diff-like-syntax) - Add diffs to your examples (e.g Schemas)
+  - [Marking individual text inside lines](https://expressive-code.com/key-features/text-markers/#marking-individual-text-inside-lines)
+- [Word wrapping](https://expressive-code.com/key-features/word-wrap/)
+- [And more...](https://expressive-code.com/)
+
+## Examples of code blocks
+
+### Diff code blocks
+Highlight diffs with your code, could be useful for your Schemas or any changes you want to show to your teams.
+
+![Example](/img/code-blocks/diff.png)
+![Example](/img/code-blocks/diff2.png)
+
+See https://expressive-code.com/key-features/text-markers/#using-diff-like-syntax
+
+### Word highlighting
+If you want to highlight words in your code blocks you can use this feature.
+
+![Example](/img/code-blocks/word-highlight.png)
+![Example](/img/code-blocks/word-highlight2.png)
+
+See https://expressive-code.com/key-features/text-markers/#marking-individual-text-inside-lines
+
+### Labels to line markers
+Great way to give context to changes in your code. For example if your Schema has changed, then maybe use this to give context with additional labels.
+
+![Example](/img/code-blocks/context-diff.png)
+
+See https://expressive-code.com/key-features/text-markers/#adding-labels-to-line-markers
+
+### Frames
+
+Nice UI for your code blocks.
+
+![Example](/img/code-blocks/title-blocks.png)
+
+See https://expressive-code.com/key-features/frames/
\ No newline at end of file
diff --git a/packages/core/docs/api/_category_.json b/packages/core/docs/api/_category_.json
new file mode 100644
index 000000000..a1e8dfb65
--- /dev/null
+++ b/packages/core/docs/api/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Development",
+  "position": 2,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "api",
+    "title": "EventCatalog API Documentation",
+    "description": "EventCatalog API Documentation"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/cli/channels.md b/packages/core/docs/cli/channels.md
new file mode 100644
index 000000000..3b7381fa0
--- /dev/null
+++ b/packages/core/docs/cli/channels.md
@@ -0,0 +1,180 @@
+---
+id: cli-channels
+title: Channels
+sidebar_label: Channels
+sidebar_position: 7
+---
+
+# Channels CLI Commands
+
+Manage channels in your EventCatalog from the command line.
+
+## getChannel
+
+Returns a channel from EventCatalog by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the channel to retrieve |
+| version | string | No | Specific version to retrieve |
+
+**Examples:**
+
+```bash
+# Get the latest channel
+npx @eventcatalog/cli getChannel "orders.events"
+
+# Get a specific version
+npx @eventcatalog/cli getChannel "orders.events" "1.0.0"
+```
+
+---
+
+## getChannels
+
+Returns all channels from EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;latestOnly?&#125; |
+
+**Examples:**
+
+```bash
+# Get all channels
+npx @eventcatalog/cli getChannels
+```
+
+---
+
+## writeChannel
+
+Writes a channel to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| channel | json | Yes | Channel object with id, name, version, and markdown |
+| options | json | No | Options: &#123;path?, override?&#125; |
+
+
+
+---
+
+## rmChannel
+
+Removes a channel by its path
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| path | string | Yes | Path to the channel |
+
+**Examples:**
+
+```bash
+# Remove a channel
+npx @eventcatalog/cli rmChannel "/orders.events"
+```
+
+---
+
+## rmChannelById
+
+Removes a channel by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the channel to remove |
+| version | string | No | Specific version to remove |
+
+**Examples:**
+
+```bash
+# Remove a channel
+npx @eventcatalog/cli rmChannelById "orders.events"
+```
+
+---
+
+## versionChannel
+
+Moves the current channel to a versioned directory
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the channel to version |
+
+**Examples:**
+
+```bash
+# Version a channel
+npx @eventcatalog/cli versionChannel "orders.events"
+```
+
+---
+
+## addEventToChannel
+
+Adds an event to a channel
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| channelId | string | Yes | The ID of the channel |
+| event | json | Yes | Event reference: &#123;id, version, parameters?&#125; |
+
+
+
+---
+
+## addCommandToChannel
+
+Adds a command to a channel
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| channelId | string | Yes | The ID of the channel |
+| command | json | Yes | Command reference: &#123;id, version, parameters?&#125; |
+
+
+
+---
+
+## addQueryToChannel
+
+Adds a query to a channel
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| channelId | string | Yes | The ID of the channel |
+| query | json | Yes | Query reference: &#123;id, version, parameters?&#125; |
+
+
+
+---
+
+## channelHasVersion
+
+Checks if a specific version of a channel exists
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the channel |
+| version | string | Yes | Version to check |
+
+**Examples:**
+
+```bash
+# Check if version exists
+npx @eventcatalog/cli channelHasVersion "orders.events" "1.0.0"
+```
+
+---
diff --git a/packages/core/docs/cli/commands.md b/packages/core/docs/cli/commands.md
new file mode 100644
index 000000000..6c822fc75
--- /dev/null
+++ b/packages/core/docs/cli/commands.md
@@ -0,0 +1,183 @@
+---
+id: cli-commands
+title: Commands
+sidebar_label: Commands
+sidebar_position: 3
+---
+
+# Commands CLI Commands
+
+Manage commands in your EventCatalog from the command line.
+
+## getCommand
+
+Returns a command from EventCatalog by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the command to retrieve |
+| version | string | No | Specific version to retrieve (supports semver) |
+
+**Examples:**
+
+```bash
+# Get the latest command
+npx @eventcatalog/cli getCommand "CreateOrder"
+
+# Get a specific version
+npx @eventcatalog/cli getCommand "CreateOrder" "1.0.0"
+```
+
+---
+
+## getCommands
+
+Returns all commands from EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;latestOnly?, attachSchema?&#125; |
+
+**Examples:**
+
+```bash
+# Get all commands
+npx @eventcatalog/cli getCommands
+```
+
+---
+
+## writeCommand
+
+Writes a command to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| command | json | Yes | Command object with id, name, version, and markdown |
+| options | json | No | Options: &#123;path?, override?, versionExistingContent?&#125; |
+
+
+
+---
+
+## writeCommandToService
+
+Writes a command to a specific service
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| command | json | Yes | Command object |
+| service | json | Yes | Service reference: &#123;id, version?&#125; |
+| options | json | No | Options: &#123;path?, format?, override?&#125; |
+
+
+
+---
+
+## rmCommand
+
+Removes a command by its path
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| path | string | Yes | Path to the command |
+
+**Examples:**
+
+```bash
+# Remove a command
+npx @eventcatalog/cli rmCommand "/CreateOrder"
+```
+
+---
+
+## rmCommandById
+
+Removes a command by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the command to remove |
+| version | string | No | Specific version to remove |
+
+**Examples:**
+
+```bash
+# Remove a command
+npx @eventcatalog/cli rmCommandById "CreateOrder"
+```
+
+---
+
+## versionCommand
+
+Moves the current command to a versioned directory
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the command to version |
+
+**Examples:**
+
+```bash
+# Version a command
+npx @eventcatalog/cli versionCommand "CreateOrder"
+```
+
+---
+
+## addFileToCommand
+
+Adds a file to a command
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the command |
+| file | json | Yes | File object: &#123;content, fileName&#125; |
+| version | string | No | Specific version |
+
+
+
+---
+
+## addSchemaToCommand
+
+Adds a schema to a command
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the command |
+| schema | json | Yes | Schema object: &#123;schema, fileName&#125; |
+| version | string | No | Specific version |
+
+
+
+---
+
+## commandHasVersion
+
+Checks if a specific version of a command exists
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the command |
+| version | string | Yes | Version to check |
+
+**Examples:**
+
+```bash
+# Check if version exists
+npx @eventcatalog/cli commandHasVersion "CreateOrder" "1.0.0"
+```
+
+---
diff --git a/packages/core/docs/cli/custom-docs.md b/packages/core/docs/cli/custom-docs.md
new file mode 100644
index 000000000..c8913c728
--- /dev/null
+++ b/packages/core/docs/cli/custom-docs.md
@@ -0,0 +1,78 @@
+---
+id: cli-custom-docs
+title: Custom Docs
+sidebar_label: Custom Docs
+sidebar_position: 10
+---
+
+# Custom Docs CLI Commands
+
+Manage custom docs in your EventCatalog from the command line.
+
+## getCustomDoc
+
+Returns a custom doc from EventCatalog by its path
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| path | string | Yes | Path to the custom doc |
+
+**Examples:**
+
+```bash
+# Get a custom doc
+npx @eventcatalog/cli getCustomDoc "/getting-started"
+```
+
+---
+
+## getCustomDocs
+
+Returns all custom docs from EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;path?&#125; |
+
+**Examples:**
+
+```bash
+# Get all custom docs
+npx @eventcatalog/cli getCustomDocs
+```
+
+---
+
+## writeCustomDoc
+
+Writes a custom doc to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| customDoc | json | Yes | Custom doc object with id, title, and markdown |
+| options | json | No | Options: &#123;path?, override?&#125; |
+
+
+
+---
+
+## rmCustomDoc
+
+Removes a custom doc by its path
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| path | string | Yes | Path to the custom doc to remove |
+
+**Examples:**
+
+```bash
+# Remove a custom doc
+npx @eventcatalog/cli rmCustomDoc "/getting-started"
+```
+
+---
diff --git a/packages/core/docs/cli/data-products.md b/packages/core/docs/cli/data-products.md
new file mode 100644
index 000000000..2c61f57a4
--- /dev/null
+++ b/packages/core/docs/cli/data-products.md
@@ -0,0 +1,177 @@
+---
+id: cli-data-products
+title: Data Products
+sidebar_label: Data Products
+sidebar_position: 13
+---
+
+# Data Products CLI Commands
+
+Manage data products in your EventCatalog from the command line.
+
+## getDataProduct
+
+Returns a data product from EventCatalog by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the data product to retrieve |
+| version | string | No | Specific version to retrieve |
+
+**Examples:**
+
+```bash
+# Get the latest data product
+npx @eventcatalog/cli getDataProduct "customer-360"
+
+# Get a specific version
+npx @eventcatalog/cli getDataProduct "customer-360" "1.0.0"
+```
+
+---
+
+## getDataProducts
+
+Returns all data products from EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;latestOnly?&#125; |
+
+**Examples:**
+
+```bash
+# Get all data products
+npx @eventcatalog/cli getDataProducts
+```
+
+---
+
+## writeDataProduct
+
+Writes a data product to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;path?, override?, versionExistingContent?&#125; |
+
+
+
+---
+
+## writeDataProductToDomain
+
+Writes a data product to a specific domain
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| dataProduct | json | Yes | Data product object |
+| domain | json | Yes | Domain reference: &#123;id, version?&#125; |
+| options | json | No | Options |
+
+
+
+---
+
+## rmDataProduct
+
+Removes a data product by its path
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| path | string | Yes | Path to the data product |
+
+**Examples:**
+
+```bash
+# Remove a data product
+npx @eventcatalog/cli rmDataProduct "/customer-360"
+```
+
+---
+
+## rmDataProductById
+
+Removes a data product by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the data product to remove |
+| version | string | No | Specific version to remove |
+
+**Examples:**
+
+```bash
+# Remove a data product
+npx @eventcatalog/cli rmDataProductById "customer-360"
+```
+
+---
+
+## versionDataProduct
+
+Moves the current data product to a versioned directory
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the data product to version |
+
+**Examples:**
+
+```bash
+# Version a data product
+npx @eventcatalog/cli versionDataProduct "customer-360"
+```
+
+---
+
+## addFileToDataProduct
+
+Adds a file to a data product
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the data product |
+| file | json | Yes | File object: &#123;content, fileName&#125; |
+| version | string | No | Specific version |
+
+
+
+---
+
+## addDataProductToDomain
+
+Adds a data product reference to a domain
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| domainId | string | Yes | The ID of the domain |
+| dataProduct | json | Yes | Data product reference: &#123;id, version&#125; |
+| domainVersion | string | No | Specific domain version |
+
+
+
+---
+
+## dataProductHasVersion
+
+Checks if a specific version of a data product exists
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the data product |
+| version | string | Yes | Version to check |
+
+
+
+---
diff --git a/packages/core/docs/cli/data-stores.md b/packages/core/docs/cli/data-stores.md
new file mode 100644
index 000000000..591851122
--- /dev/null
+++ b/packages/core/docs/cli/data-stores.md
@@ -0,0 +1,166 @@
+---
+id: cli-data-stores
+title: Data Stores
+sidebar_label: Data Stores
+sidebar_position: 12
+---
+
+# Data Stores CLI Commands
+
+Manage data stores in your EventCatalog from the command line.
+
+## getDataStore
+
+Returns a data store from EventCatalog by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the data store to retrieve |
+| version | string | No | Specific version to retrieve |
+
+**Examples:**
+
+```bash
+# Get the latest data store
+npx @eventcatalog/cli getDataStore "orders-db"
+
+# Get a specific version
+npx @eventcatalog/cli getDataStore "orders-db" "1.0.0"
+```
+
+---
+
+## getDataStores
+
+Returns all data stores from EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;latestOnly?&#125; |
+
+**Examples:**
+
+```bash
+# Get all data stores
+npx @eventcatalog/cli getDataStores
+```
+
+---
+
+## writeDataStore
+
+Writes a data store to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;path?, override?, versionExistingContent?&#125; |
+
+
+
+---
+
+## writeDataStoreToService
+
+Writes a data store to a specific service
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| dataStore | json | Yes | Data store object |
+| service | json | Yes | Service reference: &#123;id, version?&#125; |
+
+
+
+---
+
+## rmDataStore
+
+Removes a data store by its path
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| path | string | Yes | Path to the data store |
+
+**Examples:**
+
+```bash
+# Remove a data store
+npx @eventcatalog/cli rmDataStore "/orders-db"
+```
+
+---
+
+## rmDataStoreById
+
+Removes a data store by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the data store to remove |
+| version | string | No | Specific version to remove |
+
+**Examples:**
+
+```bash
+# Remove a data store
+npx @eventcatalog/cli rmDataStoreById "orders-db"
+```
+
+---
+
+## versionDataStore
+
+Moves the current data store to a versioned directory
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the data store to version |
+
+**Examples:**
+
+```bash
+# Version a data store
+npx @eventcatalog/cli versionDataStore "orders-db"
+```
+
+---
+
+## addFileToDataStore
+
+Adds a file to a data store
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the data store |
+| file | json | Yes | File object: &#123;content, fileName&#125; |
+| version | string | No | Specific version |
+
+
+
+---
+
+## dataStoreHasVersion
+
+Checks if a specific version of a data store exists
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the data store |
+| version | string | Yes | Version to check |
+
+**Examples:**
+
+```bash
+# Check if version exists
+npx @eventcatalog/cli dataStoreHasVersion "orders-db" "1.0.0"
+```
+
+---
diff --git a/packages/core/docs/cli/diagrams.md b/packages/core/docs/cli/diagrams.md
new file mode 100644
index 000000000..e8f4687d3
--- /dev/null
+++ b/packages/core/docs/cli/diagrams.md
@@ -0,0 +1,147 @@
+---
+id: cli-diagrams
+title: Diagrams
+sidebar_label: Diagrams
+sidebar_position: 14
+---
+
+# Diagrams CLI Commands
+
+Manage diagrams in your EventCatalog from the command line.
+
+## getDiagram
+
+Returns a diagram from EventCatalog by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the diagram to retrieve |
+| version | string | No | Specific version to retrieve |
+
+**Examples:**
+
+```bash
+# Get the latest diagram
+npx @eventcatalog/cli getDiagram "ArchitectureDiagram"
+
+# Get a specific version
+npx @eventcatalog/cli getDiagram "ArchitectureDiagram" "1.0.0"
+```
+
+---
+
+## getDiagrams
+
+Returns all diagrams from EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;latestOnly?&#125; |
+
+**Examples:**
+
+```bash
+# Get all diagrams
+npx @eventcatalog/cli getDiagrams
+```
+
+---
+
+## writeDiagram
+
+Writes a diagram to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;path?, override?, versionExistingContent?&#125; |
+
+
+
+---
+
+## rmDiagram
+
+Removes a diagram by its path
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| path | string | Yes | Path to the diagram |
+
+**Examples:**
+
+```bash
+# Remove a diagram
+npx @eventcatalog/cli rmDiagram "/ArchitectureDiagram"
+```
+
+---
+
+## rmDiagramById
+
+Removes a diagram by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the diagram to remove |
+| version | string | No | Specific version to remove |
+
+**Examples:**
+
+```bash
+# Remove a diagram
+npx @eventcatalog/cli rmDiagramById "ArchitectureDiagram"
+```
+
+---
+
+## versionDiagram
+
+Moves the current diagram to a versioned directory
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the diagram to version |
+
+**Examples:**
+
+```bash
+# Version a diagram
+npx @eventcatalog/cli versionDiagram "ArchitectureDiagram"
+```
+
+---
+
+## addFileToDiagram
+
+Adds a file to a diagram
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the diagram |
+| file | json | Yes | File object: &#123;content, fileName&#125; |
+| version | string | No | Specific version |
+
+
+
+---
+
+## diagramHasVersion
+
+Checks if a specific version of a diagram exists
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the diagram |
+| version | string | Yes | Version to check |
+
+
+
+---
diff --git a/packages/core/docs/cli/domains.md b/packages/core/docs/cli/domains.md
new file mode 100644
index 000000000..f4592217b
--- /dev/null
+++ b/packages/core/docs/cli/domains.md
@@ -0,0 +1,280 @@
+---
+id: cli-domains
+title: Domains
+sidebar_label: Domains
+sidebar_position: 6
+---
+
+# Domains CLI Commands
+
+Manage domains in your EventCatalog from the command line.
+
+## getDomain
+
+Returns a domain from EventCatalog by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the domain to retrieve |
+| version | string | No | Specific version to retrieve |
+
+**Examples:**
+
+```bash
+# Get the latest domain
+npx @eventcatalog/cli getDomain "Orders"
+
+# Get a specific version
+npx @eventcatalog/cli getDomain "Orders" "1.0.0"
+```
+
+---
+
+## getDomains
+
+Returns all domains from EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;latestOnly?&#125; |
+
+**Examples:**
+
+```bash
+# Get all domains
+npx @eventcatalog/cli getDomains
+```
+
+---
+
+## writeDomain
+
+Writes a domain to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| domain | json | Yes | Domain object with id, name, version, and markdown |
+| options | json | No | Options: &#123;path?, override?, versionExistingContent?&#125; |
+
+
+
+---
+
+## rmDomain
+
+Removes a domain by its path
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| path | string | Yes | Path to the domain |
+
+**Examples:**
+
+```bash
+# Remove a domain
+npx @eventcatalog/cli rmDomain "/Orders"
+```
+
+---
+
+## rmDomainById
+
+Removes a domain by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the domain to remove |
+| version | string | No | Specific version to remove |
+
+**Examples:**
+
+```bash
+# Remove a domain
+npx @eventcatalog/cli rmDomainById "Orders"
+```
+
+---
+
+## versionDomain
+
+Moves the current domain to a versioned directory
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the domain to version |
+
+**Examples:**
+
+```bash
+# Version a domain
+npx @eventcatalog/cli versionDomain "Orders"
+```
+
+---
+
+## addFileToDomain
+
+Adds a file to a domain
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the domain |
+| file | json | Yes | File object: &#123;content, fileName&#125; |
+| version | string | No | Specific version |
+
+
+
+---
+
+## addServiceToDomain
+
+Adds a service to a domain
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| domainId | string | Yes | The ID of the domain |
+| service | json | Yes | Service reference: &#123;id, version&#125; |
+| domainVersion | string | No | Specific domain version |
+
+
+
+---
+
+## addSubDomainToDomain
+
+Adds a subdomain to a domain
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| domainId | string | Yes | The ID of the parent domain |
+| subDomain | json | Yes | Subdomain reference: &#123;id, version&#125; |
+| domainVersion | string | No | Specific domain version |
+
+
+
+---
+
+## addEntityToDomain
+
+Adds an entity to a domain
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| domainId | string | Yes | The ID of the domain |
+| entity | json | Yes | Entity reference: &#123;id, version&#125; |
+| domainVersion | string | No | Specific domain version |
+
+
+
+---
+
+## addEventToDomain
+
+Adds an event relationship to a domain
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| domainId | string | Yes | The ID of the domain |
+| direction | string | Yes | Direction: "sends" or "receives" |
+| event | json | Yes | Event reference: &#123;id, version&#125; |
+| domainVersion | string | No | Specific domain version |
+
+
+
+---
+
+## addCommandToDomain
+
+Adds a command relationship to a domain
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| domainId | string | Yes | The ID of the domain |
+| direction | string | Yes | Direction: "sends" or "receives" |
+| command | json | Yes | Command reference: &#123;id, version&#125; |
+| domainVersion | string | No | Specific domain version |
+
+
+
+---
+
+## addQueryToDomain
+
+Adds a query relationship to a domain
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| domainId | string | Yes | The ID of the domain |
+| direction | string | Yes | Direction: "sends" or "receives" |
+| query | json | Yes | Query reference: &#123;id, version&#125; |
+| domainVersion | string | No | Specific domain version |
+
+
+
+---
+
+## addUbiquitousLanguageToDomain
+
+Adds ubiquitous language definitions to a domain
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| domainId | string | Yes | The ID of the domain |
+| dictionary | json | Yes | Array of &#123;term, definition&#125; objects |
+| domainVersion | string | No | Specific domain version |
+
+
+
+---
+
+## getUbiquitousLanguageFromDomain
+
+Gets ubiquitous language definitions from a domain
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| domainId | string | Yes | The ID of the domain |
+| domainVersion | string | No | Specific domain version |
+
+**Examples:**
+
+```bash
+# Get ubiquitous language
+npx @eventcatalog/cli getUbiquitousLanguageFromDomain "Orders"
+```
+
+---
+
+## domainHasVersion
+
+Checks if a specific version of a domain exists
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the domain |
+| version | string | Yes | Version to check |
+
+**Examples:**
+
+```bash
+# Check if version exists
+npx @eventcatalog/cli domainHasVersion "Orders" "1.0.0"
+```
+
+---
diff --git a/packages/core/docs/cli/entities.md b/packages/core/docs/cli/entities.md
new file mode 100644
index 000000000..e6f4bf6aa
--- /dev/null
+++ b/packages/core/docs/cli/entities.md
@@ -0,0 +1,138 @@
+---
+id: cli-entities
+title: Entities
+sidebar_label: Entities
+sidebar_position: 11
+---
+
+# Entities CLI Commands
+
+Manage entities in your EventCatalog from the command line.
+
+## getEntity
+
+Returns an entity from EventCatalog by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the entity to retrieve |
+| version | string | No | Specific version to retrieve |
+
+**Examples:**
+
+```bash
+# Get the latest entity
+npx @eventcatalog/cli getEntity "Order"
+
+# Get a specific version
+npx @eventcatalog/cli getEntity "Order" "1.0.0"
+```
+
+---
+
+## getEntities
+
+Returns all entities from EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;latestOnly?&#125; |
+
+**Examples:**
+
+```bash
+# Get all entities
+npx @eventcatalog/cli getEntities
+```
+
+---
+
+## writeEntity
+
+Writes an entity to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| entity | json | Yes | Entity object with id, name, version, and markdown |
+| options | json | No | Options: &#123;path?, override?, versionExistingContent?&#125; |
+
+
+
+---
+
+## rmEntity
+
+Removes an entity by its path
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| path | string | Yes | Path to the entity |
+
+**Examples:**
+
+```bash
+# Remove an entity
+npx @eventcatalog/cli rmEntity "/Order"
+```
+
+---
+
+## rmEntityById
+
+Removes an entity by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the entity to remove |
+| version | string | No | Specific version to remove |
+
+**Examples:**
+
+```bash
+# Remove an entity
+npx @eventcatalog/cli rmEntityById "Order"
+```
+
+---
+
+## versionEntity
+
+Moves the current entity to a versioned directory
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the entity to version |
+
+**Examples:**
+
+```bash
+# Version an entity
+npx @eventcatalog/cli versionEntity "Order"
+```
+
+---
+
+## entityHasVersion
+
+Checks if a specific version of an entity exists
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the entity |
+| version | string | Yes | Version to check |
+
+**Examples:**
+
+```bash
+# Check if version exists
+npx @eventcatalog/cli entityHasVersion "Order" "1.0.0"
+```
+
+---
diff --git a/packages/core/docs/cli/events.md b/packages/core/docs/cli/events.md
new file mode 100644
index 000000000..0c25530f9
--- /dev/null
+++ b/packages/core/docs/cli/events.md
@@ -0,0 +1,186 @@
+---
+id: cli-events
+title: Events
+sidebar_label: Events
+sidebar_position: 2
+---
+
+# Events CLI Commands
+
+Manage events in your EventCatalog from the command line.
+
+## getEvent
+
+Returns an event from EventCatalog by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the event to retrieve |
+| version | string | No | Specific version to retrieve (supports semver) |
+| options | json | No | Options object, e.g. &#123;"attachSchema": true&#125; |
+
+**Examples:**
+
+```bash
+# Get the latest version of an event
+npx @eventcatalog/cli getEvent "OrderCreated"
+
+# Get a specific version
+npx @eventcatalog/cli getEvent "OrderCreated" "1.0.0"
+```
+
+---
+
+## getEvents
+
+Returns all events from EventCatalog
+
+**Arguments:** None
+
+**Examples:**
+
+```bash
+# Get all events
+npx @eventcatalog/cli getEvents
+```
+
+---
+
+## writeEvent
+
+Writes an event to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| event | json | Yes | Event object with id, name, version, and markdown |
+
+
+
+---
+
+## writeEventToService
+
+Writes an event to a specific service in EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| event | json | Yes | Event object with id, name, version, and markdown |
+| service | json | Yes | Service reference: &#123;id, version?&#125; |
+| options | json | No | Options: &#123;path?, format?, override?&#125; |
+
+
+
+---
+
+## rmEvent
+
+Removes an event by its path
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| path | string | Yes | Path to the event, e.g. /InventoryAdjusted |
+
+**Examples:**
+
+```bash
+# Remove an event by path
+npx @eventcatalog/cli rmEvent "/InventoryAdjusted"
+```
+
+---
+
+## rmEventById
+
+Removes an event by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the event to remove |
+| version | string | No | Specific version to remove |
+
+**Examples:**
+
+```bash
+# Remove latest version
+npx @eventcatalog/cli rmEventById "OrderCreated"
+
+# Remove specific version
+npx @eventcatalog/cli rmEventById "OrderCreated" "1.0.0"
+```
+
+---
+
+## versionEvent
+
+Moves the current event to a versioned directory
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the event to version |
+
+**Examples:**
+
+```bash
+# Version an event
+npx @eventcatalog/cli versionEvent "OrderCreated"
+```
+
+---
+
+## addFileToEvent
+
+Adds a file to an event
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the event |
+| file | json | Yes | File object: &#123;content, fileName&#125; |
+| version | string | No | Specific version to add file to |
+
+
+
+---
+
+## addSchemaToEvent
+
+Adds a schema file to an event
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the event |
+| schema | json | Yes | Schema object: &#123;schema, fileName&#125; |
+| version | string | No | Specific version to add schema to |
+
+
+
+---
+
+## eventHasVersion
+
+Checks if a specific version of an event exists
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the event |
+| version | string | Yes | Version to check (supports semver) |
+
+**Examples:**
+
+```bash
+# Check if version exists
+npx @eventcatalog/cli eventHasVersion "OrderCreated" "1.0.0"
+
+# Check with semver range
+npx @eventcatalog/cli eventHasVersion "OrderCreated" "1.0.x"
+```
+
+---
diff --git a/packages/core/docs/cli/export.md b/packages/core/docs/cli/export.md
new file mode 100644
index 000000000..379d1d3fd
--- /dev/null
+++ b/packages/core/docs/cli/export.md
@@ -0,0 +1,27 @@
+---
+id: cli-export
+title: Export
+sidebar_label: Export
+sidebar_position: 17
+---
+
+# Export CLI Commands
+
+Manage export in your EventCatalog from the command line.
+
+## export
+
+Export catalog resources to EventCatalog DSL (.ec) format
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| all | boolean | No | Export the entire catalog (all resource types) |
+| id | string | No | Resource ID (omit to export all of the given type) |
+| version | string | No | Resource version (defaults to latest) |
+| stdout | boolean | No | Print to stdout instead of writing a file |
+| output | string | No | Output file path (defaults to &lt;id&gt;.ec or catalog.ec) |
+
+
+
+---
diff --git a/packages/core/docs/cli/governance.md b/packages/core/docs/cli/governance.md
new file mode 100644
index 000000000..d385a373f
--- /dev/null
+++ b/packages/core/docs/cli/governance.md
@@ -0,0 +1,24 @@
+---
+id: cli-governance
+title: Governance
+sidebar_label: Governance
+sidebar_position: 20
+---
+
+# Governance CLI Commands
+
+Manage governance in your EventCatalog from the command line.
+
+## governanceCheck
+
+Compare the current catalog (or a target branch) against a base branch and evaluate governance rules defined in governance.yaml (or governance.yml)
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| --base | string | No | Base branch to compare against (default: main) |
+| --format | string | No | Output format: text or json (default: text) |
+
+
+
+---
diff --git a/packages/core/docs/cli/import.md b/packages/core/docs/cli/import.md
new file mode 100644
index 000000000..277b4b8e6
--- /dev/null
+++ b/packages/core/docs/cli/import.md
@@ -0,0 +1,26 @@
+---
+id: cli-import
+title: Import
+sidebar_label: Import
+sidebar_position: 18
+---
+
+# Import CLI Commands
+
+Manage import in your EventCatalog from the command line.
+
+## import
+
+Import EventCatalog DSL (.ec) files into catalog markdown files. Existing resources with the same version are overridden. Importing a newer version automatically moves the old version into the versioned/ folder.
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| files | string | No | One or more .ec file paths to import |
+| stdin | boolean | No | Read DSL from stdin |
+| dry-run | boolean | No | Preview resources without writing |
+| no-init | boolean | No | Skip catalog initialization prompt |
+
+
+
+---
diff --git a/packages/core/docs/cli/index.md b/packages/core/docs/cli/index.md
new file mode 100644
index 000000000..4215c761a
--- /dev/null
+++ b/packages/core/docs/cli/index.md
@@ -0,0 +1,121 @@
+---
+id: cli-overview
+title: CLI Reference
+sidebar_label: Overview
+sidebar_position: 1
+---
+
+# EventCatalog CLI
+
+The EventCatalog CLI allows you to interact with your EventCatalog directly from the command line. Execute any SDK function without writing code.
+
+## Installation
+
+You can run the CLI directly using `npx` without installing:
+
+```bash
+npx @eventcatalog/cli <function> [args...]
+```
+
+Or install globally:
+
+```bash
+npm install -g @eventcatalog/cli
+```
+
+Then use the `eventcatalog` command:
+
+```bash
+eventcatalog <function> [args...]
+```
+
+## Basic Usage
+
+### Specifying the catalog directory
+
+By default, the CLI uses the current directory. Use `--dir` to specify a different path:
+
+```bash
+npx @eventcatalog/cli --dir /path/to/catalog getEvents
+```
+
+### Listing available functions
+
+```bash
+npx @eventcatalog/cli list
+```
+
+### Getting help
+
+```bash
+npx @eventcatalog/cli --help
+```
+
+## Output Format
+
+All commands output JSON, making it easy to pipe to other tools like `jq`:
+
+```bash
+# Get all events and extract IDs
+npx @eventcatalog/cli getEvents | jq '.[].id'
+
+# Count total events
+npx @eventcatalog/cli getEvents | jq 'length'
+
+# Filter events by version
+npx @eventcatalog/cli getEvents | jq '.[] | select(.version == "1.0.0")'
+```
+
+## Argument Types
+
+Arguments are automatically parsed:
+
+| Type | Format | Example |
+|------|--------|---------|
+| String | Plain text or quoted | `"OrderCreated"` |
+| Number | Numeric value | `42` or `3.14` |
+| Boolean | `true` or `false` | `true` |
+| JSON Object | `'{...}'` | `'{"id":"test","version":"1.0.0"}'` |
+| JSON Array | `'[...]'` | `'["item1","item2"]'` |
+
+## Quick Examples
+
+### Read operations
+
+```bash
+# Get a specific event
+npx @eventcatalog/cli getEvent "OrderCreated"
+
+# Get all services (latest versions only)
+npx @eventcatalog/cli getServices '{"latestOnly":true}'
+
+# Check if a version exists
+npx @eventcatalog/cli eventHasVersion "OrderCreated" "1.0.0"
+```
+
+### Write operations
+
+```bash
+# Create a new event
+npx @eventcatalog/cli writeEvent '{"id":"OrderCreated","name":"Order Created","version":"1.0.0","markdown":"# Order Created Event"}'
+
+# Add a service to a domain
+npx @eventcatalog/cli addServiceToDomain "Orders" '{"id":"OrderService","version":"1.0.0"}'
+```
+
+### Delete operations
+
+```bash
+# Remove an event by ID
+npx @eventcatalog/cli rmEventById "OrderCreated"
+
+# Remove a specific version
+npx @eventcatalog/cli rmEventById "OrderCreated" "1.0.0"
+```
+
+### Version operations
+
+```bash
+# Version an event (move current to versioned directory)
+npx @eventcatalog/cli versionEvent "OrderCreated"
+```
diff --git a/packages/core/docs/cli/messages.md b/packages/core/docs/cli/messages.md
new file mode 100644
index 000000000..4787fe1e1
--- /dev/null
+++ b/packages/core/docs/cli/messages.md
@@ -0,0 +1,69 @@
+---
+id: cli-messages
+title: Messages
+sidebar_label: Messages
+sidebar_position: 15
+---
+
+# Messages CLI Commands
+
+Manage messages in your EventCatalog from the command line.
+
+## getProducersAndConsumersForMessage
+
+Returns the producers and consumers (services) for a given message
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the message |
+| version | string | No | Specific version |
+
+
+
+---
+
+## getConsumersOfSchema
+
+Returns services that consume a given schema
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| schemaPath | string | Yes | Path to the schema file |
+
+
+
+---
+
+## getProducersOfSchema
+
+Returns services that produce a given schema
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| schemaPath | string | Yes | Path to the schema file |
+
+
+
+---
+
+## getOwnersForResource
+
+Returns the owners (users/teams) for a given resource
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the resource |
+| version | string | No | Specific version |
+
+**Examples:**
+
+```bash
+# Get owners for a resource
+npx @eventcatalog/cli getOwnersForResource "OrderService"
+```
+
+---
diff --git a/packages/core/docs/cli/queries.md b/packages/core/docs/cli/queries.md
new file mode 100644
index 000000000..686a2d3ff
--- /dev/null
+++ b/packages/core/docs/cli/queries.md
@@ -0,0 +1,183 @@
+---
+id: cli-queries
+title: Queries
+sidebar_label: Queries
+sidebar_position: 4
+---
+
+# Queries CLI Commands
+
+Manage queries in your EventCatalog from the command line.
+
+## getQuery
+
+Returns a query from EventCatalog by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the query to retrieve |
+| version | string | No | Specific version to retrieve |
+
+**Examples:**
+
+```bash
+# Get the latest query
+npx @eventcatalog/cli getQuery "GetOrder"
+
+# Get a specific version
+npx @eventcatalog/cli getQuery "GetOrder" "1.0.0"
+```
+
+---
+
+## getQueries
+
+Returns all queries from EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;latestOnly?, attachSchema?&#125; |
+
+**Examples:**
+
+```bash
+# Get all queries
+npx @eventcatalog/cli getQueries
+```
+
+---
+
+## writeQuery
+
+Writes a query to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| query | json | Yes | Query object with id, name, version, and markdown |
+| options | json | No | Options: &#123;path?, override?, versionExistingContent?&#125; |
+
+
+
+---
+
+## writeQueryToService
+
+Writes a query to a specific service
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| query | json | Yes | Query object |
+| service | json | Yes | Service reference: &#123;id, version?&#125; |
+| options | json | No | Options: &#123;path?, format?, override?&#125; |
+
+
+
+---
+
+## rmQuery
+
+Removes a query by its path
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| path | string | Yes | Path to the query |
+
+**Examples:**
+
+```bash
+# Remove a query
+npx @eventcatalog/cli rmQuery "/GetOrder"
+```
+
+---
+
+## rmQueryById
+
+Removes a query by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the query to remove |
+| version | string | No | Specific version to remove |
+
+**Examples:**
+
+```bash
+# Remove a query
+npx @eventcatalog/cli rmQueryById "GetOrder"
+```
+
+---
+
+## versionQuery
+
+Moves the current query to a versioned directory
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the query to version |
+
+**Examples:**
+
+```bash
+# Version a query
+npx @eventcatalog/cli versionQuery "GetOrder"
+```
+
+---
+
+## addFileToQuery
+
+Adds a file to a query
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the query |
+| file | json | Yes | File object: &#123;content, fileName&#125; |
+| version | string | No | Specific version |
+
+
+
+---
+
+## addSchemaToQuery
+
+Adds a schema to a query
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the query |
+| schema | json | Yes | Schema object: &#123;schema, fileName&#125; |
+| version | string | No | Specific version |
+
+
+
+---
+
+## queryHasVersion
+
+Checks if a specific version of a query exists
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the query |
+| version | string | Yes | Version to check |
+
+**Examples:**
+
+```bash
+# Check if version exists
+npx @eventcatalog/cli queryHasVersion "GetOrder" "1.0.0"
+```
+
+---
diff --git a/packages/core/docs/cli/services.md b/packages/core/docs/cli/services.md
new file mode 100644
index 000000000..c1d9ffeb0
--- /dev/null
+++ b/packages/core/docs/cli/services.md
@@ -0,0 +1,266 @@
+---
+id: cli-services
+title: Services
+sidebar_label: Services
+sidebar_position: 5
+---
+
+# Services CLI Commands
+
+Manage services in your EventCatalog from the command line.
+
+## getService
+
+Returns a service from EventCatalog by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the service to retrieve |
+| version | string | No | Specific version to retrieve |
+
+**Examples:**
+
+```bash
+# Get the latest service
+npx @eventcatalog/cli getService "OrderService"
+
+# Get a specific version
+npx @eventcatalog/cli getService "OrderService" "1.0.0"
+```
+
+---
+
+## getServices
+
+Returns all services from EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| options | json | No | Options: &#123;latestOnly?&#125; |
+
+**Examples:**
+
+```bash
+# Get all services
+npx @eventcatalog/cli getServices
+```
+
+---
+
+## writeService
+
+Writes a service to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| service | json | Yes | Service object with id, name, version, and markdown |
+| options | json | No | Options: &#123;path?, override?, versionExistingContent?&#125; |
+
+
+
+---
+
+## writeServiceToDomain
+
+Writes a service to a specific domain
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| service | json | Yes | Service object |
+| domain | json | Yes | Domain reference: &#123;id, version?&#125; |
+| options | json | No | Options |
+
+
+
+---
+
+## rmService
+
+Removes a service by its path
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| path | string | Yes | Path to the service |
+
+**Examples:**
+
+```bash
+# Remove a service
+npx @eventcatalog/cli rmService "/OrderService"
+```
+
+---
+
+## rmServiceById
+
+Removes a service by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the service to remove |
+| version | string | No | Specific version to remove |
+
+**Examples:**
+
+```bash
+# Remove a service
+npx @eventcatalog/cli rmServiceById "OrderService"
+```
+
+---
+
+## versionService
+
+Moves the current service to a versioned directory
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the service to version |
+
+**Examples:**
+
+```bash
+# Version a service
+npx @eventcatalog/cli versionService "OrderService"
+```
+
+---
+
+## addFileToService
+
+Adds a file to a service
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the service |
+| file | json | Yes | File object: &#123;content, fileName&#125; |
+| version | string | No | Specific version |
+
+
+
+---
+
+## addEventToService
+
+Adds an event relationship to a service
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| serviceId | string | Yes | The ID of the service |
+| direction | string | Yes | Direction: "sends" or "receives" |
+| event | json | Yes | Event reference: &#123;id, version&#125; |
+| serviceVersion | string | No | Specific service version |
+
+
+
+---
+
+## addCommandToService
+
+Adds a command relationship to a service
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| serviceId | string | Yes | The ID of the service |
+| direction | string | Yes | Direction: "sends" or "receives" |
+| command | json | Yes | Command reference: &#123;id, version&#125; |
+| serviceVersion | string | No | Specific service version |
+
+
+
+---
+
+## addQueryToService
+
+Adds a query relationship to a service
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| serviceId | string | Yes | The ID of the service |
+| direction | string | Yes | Direction: "sends" or "receives" |
+| query | json | Yes | Query reference: &#123;id, version&#125; |
+| serviceVersion | string | No | Specific service version |
+
+
+
+---
+
+## addEntityToService
+
+Adds an entity to a service
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| serviceId | string | Yes | The ID of the service |
+| entity | json | Yes | Entity reference: &#123;id, version&#125; |
+| serviceVersion | string | No | Specific service version |
+
+
+
+---
+
+## addDataStoreToService
+
+Adds a data store relationship to a service
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| serviceId | string | Yes | The ID of the service |
+| relationship | string | Yes | Relationship: "writesTo" or "readsFrom" |
+| dataStore | json | Yes | Data store reference: &#123;id, version&#125; |
+| serviceVersion | string | No | Specific service version |
+
+
+
+---
+
+## serviceHasVersion
+
+Checks if a specific version of a service exists
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the service |
+| version | string | Yes | Version to check |
+
+**Examples:**
+
+```bash
+# Check if version exists
+npx @eventcatalog/cli serviceHasVersion "OrderService" "1.0.0"
+```
+
+---
+
+## getSpecificationFilesForService
+
+Returns specification files (OpenAPI, AsyncAPI) for a service
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the service |
+| version | string | No | Specific version |
+
+**Examples:**
+
+```bash
+# Get spec files
+npx @eventcatalog/cli getSpecificationFilesForService "OrderService"
+```
+
+---
diff --git a/packages/core/docs/cli/snapshots.md b/packages/core/docs/cli/snapshots.md
new file mode 100644
index 000000000..cf8829138
--- /dev/null
+++ b/packages/core/docs/cli/snapshots.md
@@ -0,0 +1,44 @@
+---
+id: cli-snapshots
+title: Snapshots
+sidebar_label: Snapshots
+sidebar_position: 19
+---
+
+# Snapshots CLI Commands
+
+Manage snapshots in your EventCatalog from the command line.
+
+## createSnapshot
+
+Take a point-in-time snapshot of the entire catalog, capturing all resources and their metadata as a JSON file
+
+**Arguments:** None
+
+
+
+---
+
+## diffSnapshots
+
+Compare two snapshot files and output a structured diff showing added, removed, modified, and versioned resources plus relationship changes
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| fileA | string | Yes | Path to the first (older) snapshot file |
+| fileB | string | Yes | Path to the second (newer) snapshot file |
+
+
+
+---
+
+## listSnapshots
+
+List all snapshots in the catalog .snapshots directory with their labels, timestamps, and git info
+
+**Arguments:** None
+
+
+
+---
diff --git a/packages/core/docs/cli/teams.md b/packages/core/docs/cli/teams.md
new file mode 100644
index 000000000..01ba0e124
--- /dev/null
+++ b/packages/core/docs/cli/teams.md
@@ -0,0 +1,75 @@
+---
+id: cli-teams
+title: Teams
+sidebar_label: Teams
+sidebar_position: 8
+---
+
+# Teams CLI Commands
+
+Manage teams in your EventCatalog from the command line.
+
+## getTeam
+
+Returns a team from EventCatalog by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the team to retrieve |
+
+**Examples:**
+
+```bash
+# Get a team
+npx @eventcatalog/cli getTeam "platform-team"
+```
+
+---
+
+## getTeams
+
+Returns all teams from EventCatalog
+
+**Arguments:** None
+
+**Examples:**
+
+```bash
+# Get all teams
+npx @eventcatalog/cli getTeams
+```
+
+---
+
+## writeTeam
+
+Writes a team to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| team | json | Yes | Team object with id, name, and markdown |
+| options | json | No | Options: &#123;path?, override?&#125; |
+
+
+
+---
+
+## rmTeamById
+
+Removes a team by its ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the team to remove |
+
+**Examples:**
+
+```bash
+# Remove a team
+npx @eventcatalog/cli rmTeamById "platform-team"
+```
+
+---
diff --git a/packages/core/docs/cli/users.md b/packages/core/docs/cli/users.md
new file mode 100644
index 000000000..22b06ab19
--- /dev/null
+++ b/packages/core/docs/cli/users.md
@@ -0,0 +1,75 @@
+---
+id: cli-users
+title: Users
+sidebar_label: Users
+sidebar_position: 9
+---
+
+# Users CLI Commands
+
+Manage users in your EventCatalog from the command line.
+
+## getUser
+
+Returns a user from EventCatalog by their ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the user to retrieve |
+
+**Examples:**
+
+```bash
+# Get a user
+npx @eventcatalog/cli getUser "jsmith"
+```
+
+---
+
+## getUsers
+
+Returns all users from EventCatalog
+
+**Arguments:** None
+
+**Examples:**
+
+```bash
+# Get all users
+npx @eventcatalog/cli getUsers
+```
+
+---
+
+## writeUser
+
+Writes a user to EventCatalog
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| user | json | Yes | User object with id, name, and markdown |
+| options | json | No | Options: &#123;path?, override?&#125; |
+
+
+
+---
+
+## rmUserById
+
+Removes a user by their ID
+
+**Arguments:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | The ID of the user to remove |
+
+**Examples:**
+
+```bash
+# Remove a user
+npx @eventcatalog/cli rmUserById "jsmith"
+```
+
+---
diff --git a/packages/core/docs/cli/utilities.md b/packages/core/docs/cli/utilities.md
new file mode 100644
index 000000000..e5f8661dd
--- /dev/null
+++ b/packages/core/docs/cli/utilities.md
@@ -0,0 +1,43 @@
+---
+id: cli-utilities
+title: Utilities
+sidebar_label: Utilities
+sidebar_position: 16
+---
+
+# Utilities CLI Commands
+
+Manage utilities in your EventCatalog from the command line.
+
+## dumpCatalog
+
+Dumps the entire catalog to a JSON structure
+
+**Arguments:** None
+
+**Examples:**
+
+```bash
+# Dump entire catalog
+npx @eventcatalog/cli dumpCatalog
+
+# Dump and save to file
+npx @eventcatalog/cli dumpCatalog > catalog.json
+```
+
+---
+
+## getEventCatalogConfigurationFile
+
+Returns the EventCatalog configuration file
+
+**Arguments:** None
+
+**Examples:**
+
+```bash
+# Get config file
+npx @eventcatalog/cli getEventCatalogConfigurationFile
+```
+
+---
diff --git a/packages/core/docs/contributing/01-overview.md b/packages/core/docs/contributing/01-overview.md
new file mode 100644
index 000000000..ff171836c
--- /dev/null
+++ b/packages/core/docs/contributing/01-overview.md
@@ -0,0 +1,186 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Contributing
+sidebar_label: Contributing to EventCatalog
+title: Contributing
+description: Understand how to contribute of EventCatalog
+---
+
+# Contributing to EventCatalog
+
+[EventCatalog](https://eventcatalog.dev) is designed to help teams document their document Event Driven Architectures. If you're interested in contributing to EventCatalog, hopefully, this document makes the process for contributing clear.
+
+The [Open Source Guides](https://opensource.guide/) website has a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to an open source project. Contributors and people new to open source alike will find the following guides especially useful:
+
+- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
+- [Building Welcoming Communities](https://opensource.guide/building-community/)
+
+## Get Involved
+
+There are many ways to contribute to EventCatalog, and many of them do not involve writing any code. Here's a few ideas to get started:
+
+- Simply start using EventCatalog. Go through the [Getting Started](/docs/development/getting-started/installation) guide. Does everything work as expected? If not, we're always looking for improvements. Let us know by [opening an issue](#reporting-new-issues).
+- Look through the [open issues](https://github.com/event-catalog/eventcatalog/issues). Provide workarounds, ask for clarification, or suggest labels. Help [triage issues](#triaging-issues-and-pull-requests).
+- If you find an issue you would like to fix, [open a pull request](#your-first-pull-request). Issues tagged as [_Good first issue_](https://github.com/event-catalog/eventcatalog/labels/Good%20first%20issue) are a good place to get started.
+- Read through the [EventCatalog docs](/docs/development/getting-started/installation). If you find anything that is confusing or can be improved, you can click "Edit this page" at the bottom of most docs, which takes you to the GitHub interface to make and propose changes.
+- Take a look at the [features requested](https://github.com/event-catalog/eventcatalog/labels/feature) by others in the community and consider opening a pull request if you see something you want to work on.
+
+Contributions are very welcome. If you think you need help planning your contribution, please ping on Twitter at [@boyney123](https://twitter.com/boyney123) and let us know you are looking for a bit of help.
+
+### Join our Discord Channel
+
+We have the [`#contributors`](https://eventcatalog.dev/discord) channel on [Discord](https://eventcatalog.dev/discord) to discuss all things about EventCatalog development. You can also be of great help by helping other users in the help channel.
+
+### Triaging Issues and Pull Requests
+
+One great way you can contribute to the project without writing any code is to help triage issues and pull requests as they come in.
+
+- Ask for more information if you believe the issue does not provide all the details required to solve it.
+- Suggest [labels](https://github.com/event-catalog/eventcatalog/labels) that can help categorize issues.
+- Flag issues that are stale or that should be closed.
+- Ask for test plans and review code.
+
+## Our Development Process
+
+EventCatalog uses [GitHub](https://github.com/event-catalog/eventcatalog) as its source of truth. All changes will be public from the beginning.
+
+All pull requests will be checked by the continuous integration system, GitHub actions.
+
+### Running the project locally
+
+To run the project locally follow these steps:
+
+1. Clone the repo `git clone git@github.com:event-catalog/eventcatalog.git`
+1. Install project dependencies `npm run i`
+1. Run the project locally `npm run start:catalog`
+    - This will load EventCatalog locally using the catalog found in the [`/examples` folder](https://github.com/event-catalog/eventcatalog/tree/main/examples/default).
+
+### Branch Organization
+
+EventCatalog has one primary branch `main` and we use feature branches to deliver new features with pull requests.
+
+## Proposing a Change
+
+If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with the [feature template](https://github.com/event-catalog/eventcatalog/issues/new?assignees=&labels=feature%2Cneeds+triage&template=feature.yml).
+
+If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend [filing an issue](https://github.com/event-catalog/eventcatalog/issues/new?assignees=&labels=bug%2Cneeds+triage&template=bug.yml) detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
+
+### Reporting New Issues
+
+When [opening a new issue](https://github.com/event-catalog/eventcatalog/issues/new/choose), always make sure to fill out the issue template. **This step is very important!** Not doing so may result in your issue not being managed in a timely fashion. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template.
+
+- **One issue, one bug:** Please report a single bug per issue.
+- **Provide reproduction steps:** List all the steps necessary to reproduce the issue. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort.
+
+### Bugs
+
+We use [GitHub Issues](https://github.com/event-catalog/eventcatalog/issues) for our public bugs. If you would like to report a problem, take a look around and see if someone already opened an issue about it. If you are certain this is a new, unreported bug, you can submit a [bug report](#reporting-new-issues).
+
+### Feature requests
+
+You can also file issues as [feature requests or enhancements](https://github.com/event-catalog/eventcatalog/labels/feature%20request). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/boyney123/eventcatalog/master/.github/ISSUE_TEMPLATE/feature.md)
+
+### Questions
+
+If you have questions about using EventCatalog, ask in [Discord](https://eventcatalog.dev/discord) or contact on [Twitter](https://twitter.com/boyney123) and we will do our best to answer your questions.
+
+## Pull Requests
+
+### Your First Pull Request
+
+So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at.
+
+Working on your first Pull Request? You can learn how from this free video series:
+
+[**How to Contribute to an Open Source Project on GitHub**](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github)
+
+We have a list of [beginner-friendly issues](https://github.com/event-catalog/eventcatalog/labels/good%20first%20issue) to help you get your feet wet in the EventCatalog codebase and familiar with our contribution process. This is a great place to get started.
+
+### Installation
+
+1. Ensure you have [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed.
+1. After cloning the repository, run `npm i` in the root of the repository.
+1. To start the catalog locally run `npm run start:catalog`
+
+### Sending a Pull Request
+
+Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. It is recommended to follow this [commit message style](#semantic-commit-messages).
+
+Please make sure the following is done when submitting a pull request:
+
+1. Fork [the repository](https://github.com/event-catalog/eventcatalog) and create your branch from `main`.
+1. Make sure your code lints (`yarn format && yarn lint`).
+1. Make sure your Jest tests pass (`yarn test`).
+
+All pull requests should be opened against the `main` branch.
+
+#### Breaking Changes
+
+When adding a new breaking change, follow this template in your pull request:
+
+```md
+### New breaking change here
+
+- **Who does this affect**:
+- **How to migrate**:
+- **Why make this breaking change**:
+- **Severity (number of people affected x effort)**:
+```
+
+### What Happens Next?
+
+We will be monitoring for pull requests. Do help us by keeping pull requests consistent by following the guidelines above.
+
+## Style Guide
+
+[Prettier](https://prettier.io) will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `yarn prettier`.
+
+However, there are still some styles that Prettier cannot pick up.
+
+## Semantic Commit Messages
+
+See how a minor change to your commit message style can make you a better programmer.
+
+Format: `<type>(<scope>): <subject>`
+
+`<scope>` is optional. If your change is specific to one/two packages, consider adding the scope. Scopes should be brief but recognizable, e.g. `content-docs`, `theme-classic`, `core`
+
+The various types of commits:
+
+- `feat`: a new API or behavior **for the end user**.
+- `fix`: a bug fix **for the end user**.
+- `docs`: a change to the website or other Markdown documents in our repo.
+- `refactor`: a change to production code that leads to no behavior difference, e.g. splitting files, renaming internal variables, improving code style...
+- `test`: adding missing tests, refactoring tests; no production code change.
+- `chore`: upgrading dependencies, releasing new versions... Chores that are **regularly done** for maintenance purposes.
+- `misc`: anything else that doesn't change production code, yet is not `test` or `chore`. e.g. updating GitHub actions workflow.
+
+Do not get too stressed about PR titles, however. The maintainers will help you get them right, and we also have a PR label system that doesn't equate with the commit message types. Your code is more important than conventions!
+
+### Example
+
+```
+feat(core): allow overriding of webpack config
+^--^^----^  ^------------^
+|   |       |
+|   |       +-> Summary in present tense.
+|   |
+|   +-> The package(s) that this change affected.
+|
++-------> Type: see below for the list we use.
+```
+
+Use lower case not title case!
+
+## Code Conventions
+
+### General
+
+- **Most important: Look around.** Match the style you see used in the rest of the project. This includes formatting, naming files, naming things in code, naming things in documentation, etc.
+- "Attractive"
+- We do have Prettier (a formatter) and ESLint (a syntax linter) to catch most stylistic problems. If you are working locally, they should automatically fix some issues during every git commit.
+
+## License
+
+By contributing to EventCatalog, you agree that your contributions will be licensed under its license.
\ No newline at end of file
diff --git a/packages/core/docs/contributing/_category_.json b/packages/core/docs/contributing/_category_.json
new file mode 100644
index 000000000..824ba8ab1
--- /dev/null
+++ b/packages/core/docs/contributing/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Contributing",
+  "position": 3,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "contributing",
+    "title": "EventCatalog Contributing Documentation",
+    "description": "EventCatalog Contributing Documentation"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/development/00-why-eventcatalog.md b/packages/core/docs/development/00-why-eventcatalog.md
new file mode 100644
index 000000000..cf1a2095d
--- /dev/null
+++ b/packages/core/docs/development/00-why-eventcatalog.md
@@ -0,0 +1,76 @@
+---
+sidebar_position: 1
+slug: /development/getting-started/introduction
+keywords:
+- EventCatalog introduction
+sidebar_label: Why EventCatalog?
+title: Why EventCatalog?
+description: EventCatalog is an open source project to help you bring discoverability to your event-driven architecture.
+---
+
+Software architecture consists of many different primitives including domains, systems, services, APIS, contracts, messages and many more.
+
+As systems grow, complexity grows. Documentation becomes important for teams but teams struggle to keep docs in sync, or relevant to what they are trying to model.
+
+**Many documentation tools are not designed for software architecture**; they let you create generic pages that get lost across the organization, they do not stay in sync with your code, specifications and teams making changes.
+
+**Our vision with EventCatalog is to change this.**
+
+### What is EventCatalog?
+
+EventCatalog is a documentation and governance tool that is built for architects.
+
+ It lets you document and visualize your architecture with primitives you are already familiar with. You can document domains, systems, applications and schemas and visualize how they all relate to each other.
+
+EventCatalog creates an internal architecture graph of how your systems work. This makes EventCatalog accessible to your AI agents, LLMs and AI workflows and [creates context of your business and architecture](/docs/development/ask-your-architecture/intro).
+
+EventCatalog is technology agnostic, this means you can document and model any systems you have
+
+
+#### What can EventCatalog do for you?
+
+- **Save time across the organization**
+  - Help teams find information they need across your business and organization
+  - Document high level information for stakeholders while providing lower level details to your teams.
+  - Connect to your AI Agents and AI Workflows. Give your LLMs the context they need.
+- **Create documentation you can trust**
+  - Sync documentation from your code with our Agent
+  - Automate documentation from your OpenAPI, AsyncAPI, or schema registries
+  - Use EventCatalog Agent to sync code to docs from your CI/CD workflows.
+  - Write your own automation and plugins with the [EventCatalog SDK](/docs/sdk)
+- **Detect breaking changes before they reach production**
+  - Use EventCatalog Agent to detect breaking schema changes
+  - Bring your own model and get notified when things break
+- **Use natural langugage to query your architecture**
+  - Connect AI tools to your architecture using [EventCatalog's MCP server](/docs/development/ask-your-architecture/mcp-server/introduction)
+  - Ask architectural questions grounded in your documented domains, services, events, data products, and schemas
+- **Show the bigger picture**
+  - Help business stakeholders understand the bigger picture
+  - Visualize your architecture and future ideas
+  - Document key business workflows
+
+**EventCatalog is self-hosted. You own your data and host it wherever you want.**
+
+---
+
+<!-- ## Why we built this
+
+Distributed architecture starts simple but grow complex fast. More services, more events, more teams — and suddenly nobody knows how anything connects.
+
+EventCatalog brings discoverability, documentation, and visualization to your architecture — so teams can reason about change before it happens, not after.
+
+<details>
+<summary>🎥 Watch: "Complexity is the Gotcha of Event-driven Architecture"</summary>
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/VLUvfIm9wnQ?si=XEEkOqHyZBynqZHo" 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>
+</details>
+
+--- -->
+
+## Join the community
+
+- [GitHub](https://github.com/event-catalog/eventcatalog) — Star, contribute, report issues
+- [Discord](https://eventcatalog.dev/discord) — Ask questions, share feedback
+
+## Something missing?
+
+If you find issues with the documentation or have suggestions on how to improve the documentation or the project in general, please [file an issue](https://github.com/event-catalog/eventcatalog) for us.
diff --git a/packages/core/docs/development/01-fundamentals.md b/packages/core/docs/development/01-fundamentals.md
new file mode 100644
index 000000000..005a7bea7
--- /dev/null
+++ b/packages/core/docs/development/01-fundamentals.md
@@ -0,0 +1,92 @@
+---
+sidebar_position: 2
+slug: /development/getting-started/fundamentals
+keywords:
+- EventCatalog introduction
+sidebar_label: Fundamentals
+title: Fundamentals
+description: Understanding the fundamentals of EventCatalog
+---
+
+EventCatalog is a architecture catalog built around software primitives and domain-driven design patterns, so you can model the systems you actually build instead of creating disconnected documentation pages.
+
+EventCatalog gives your teams and AI agents a shared understanding of how your systems work across your organization.
+
+EventCatalog is an open source project and is self-hosted and follows the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) pattern. All pages in EventCatalog are powered by [markdown (MDX)](https://mdxjs.com/).
+
+Your catalog is private, stays in your own repository and infrastructure. 
+
+At its core, EventCatalog gives you a small set of building blocks.
+
+- **Domains (Level 1)** - a domain describes a business boundary
+- **Systems (Level 2)** - a system is a collection of resources that work together to perform a function.
+- **Resources (Level 3)** - individual resources (e.g services, messages, data stores) that can be assigned to systems or domains.
+
+All building blocks are optional, it's up to you how you want to model your architecture in your catalog.
+
+![EventCatalog model showing domains, systems, resources, contracts, and ownership](./img/ec-types.png)
+
+## The EventCatalog model
+
+Domains give your catalog a business shape. They help users understand the boundaries in your architecture, such as `Shopping`, `Payments`, `Fulfilment`, or `Customer`.
+
+Systems give your catalog an operating shape. A system is a collection of resources that work together to perform a function. For example, a `Shopping` domain might contain a `Cart System` and a `Promotion System`.
+
+Resources are the documented building blocks inside your architecture. They can include:
+
+- [Services](/docs/development/guides/resources/services/introduction), such as APIs, workers, frontends, and backends.
+- [Messages](/docs/development/guides/resources/messages/what-are-messages), such as events, commands, and queries.
+- [Data stores](/docs/development/guides/resources/data/introduction), such as databases, caches, and file stores.
+- [Entities](/docs/development/guides/resources/entities/introduction), such as `Order`, `Customer`, or `Payment`.
+- [Data products](/docs/development/guides/resources/data-products/introduction), such as warehouse tables or analytical datasets.
+- [Agents](/docs/development/guides/resources/agents/introduction), such as customer support AI agents.
+- [Flows](/docs/development/guides/resources/flows/introduction), such as business workflows.
+
+Contracts are attached to resources. Schemas, OpenAPI specs, AsyncAPI specs, and GraphQL schemas help users understand the data and interfaces that resources produce, consume, or implement.
+
+Teams and users can own domains, systems, resources, and contracts. This makes ownership part of the architecture model, not a separate spreadsheet.
+
+## Levels of detail
+
+EventCatalog is useful to anyone in your organization. You can define high level primitives whilst giving lower level implementation details.
+
+| Level | Name | What it answers | Example |
+|-------|------|-----------------|---------|
+| Level 1 | Domains | High level, what business boundary are we looking at? | Shopping |
+| Level 2 | Systems | What software capability exists inside that boundary? | Cart System |
+| Level 3 | Resources | What makes up, connects to, or documents that system? | Cart API, cart database, checkout flow |
+
+Contracts and ownership sit across these levels. A service can implement an OpenAPI contract. A message can have a schema. A team can own a domain, system, or resource.
+
+This gives different users a way into the same catalog. Architects can start at domains, platform teams can reason about systems, and developers can drill into the resources and contracts they work with every day.
+
+## Docs-as-code
+
+EventCatalog is a [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) tool. This means you can store your documentation in your existing Git repository, version it, and use your existing workflows to review and merge changes.
+
+This also let's you define custom workflows and patterns in your organization for documentation and automation. 
+
+It's up to you where you define your catalog (or catalogs). Here are some examples:
+
+| Pattern | Description |
+|---------|-------------|
+| **Standalone repo** | Keep documentation separate from code |
+| **Next to your code** | Docs live alongside the services they describe |
+| **Monorepo** | Documentation as part of your existing monorepo |
+| **Federated** | Multiple EventCatalog instances connected into one view |
+
+
+## Automation
+
+Your documentation can also be automated, keeping your implementation details close to your documentation. There are many [integrations](/integrations) or you can create your own automations with our [SDK](/docs/sdk).
+
+## Visual editing
+
+You can also use [EventCatalog Editor](/docs/editor/overview) to maintain your catalog through a local visual workflow.
+
+The editor runs on top of your EventCatalog project, writes changes back to the same local files, and gives you a Git-backed way to review and publish changes. This helps developers, architects, analysts, and product owners contribute to the catalog without needing to work directly in Markdown files.
+
+
+## Ready to build?
+
+Now that you understand the fundamentals, [get started with EventCatalog](/docs/development/getting-started/installation).
diff --git a/packages/core/docs/development/01-getting-started/_category_.json b/packages/core/docs/development/01-getting-started/_category_.json
new file mode 100644
index 000000000..d81d6934f
--- /dev/null
+++ b/packages/core/docs/development/01-getting-started/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Getting Started",
+  "position": 3,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/getting-started",
+    "title": "Getting Started Documentation",
+    "description": "Learn how to install EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/01-getting-started/configuration-overview.md b/packages/core/docs/development/01-getting-started/configuration-overview.md
new file mode 100644
index 000000000..606fa522e
--- /dev/null
+++ b/packages/core/docs/development/01-getting-started/configuration-overview.md
@@ -0,0 +1,32 @@
+---
+sidebar_position: 6
+keywords:
+- EventCatalog configuration
+sidebar_label: Configuration
+title: Configuration
+description: Understand how to configure EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Most new EventCatalog projects are ready to run as soon as they are created. You only need to change configuration when you want to adjust how the catalog behaves, where it builds, or which features are enabled.
+
+Configuration lives in `eventcatalog.config.js` at the root of your project. You can read the [full reference documentation](/docs/api/config) to learn what can be changed.
+
+## Configuring environment variables {#configuring-environment-variables}
+
+Some features need values that should not live directly in `eventcatalog.config.js`, such as license keys or provider credentials.
+
+Put those values in a `.env` file in the root of your catalog. EventCatalog loads `.env` when it runs locally and when it builds.
+
+```bash title=".env (example)"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-api-key
+```
+
+Do not commit real secrets to source control.
+
+## Related configuration
+
+EventCatalog has a linter that can be used to validate your EventCatalog documentation.
+
+You can read more about the EventCatalog Linter in the [EventCatalog Linter documentation](/docs/development/developer-tools/eventcatalog-linter).
diff --git a/packages/core/docs/development/01-getting-started/develop-and-build.md b/packages/core/docs/development/01-getting-started/develop-and-build.md
new file mode 100644
index 000000000..763c7c9d2
--- /dev/null
+++ b/packages/core/docs/development/01-getting-started/develop-and-build.md
@@ -0,0 +1,72 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog Develop and build
+sidebar_label: Develop and build
+title: Develop and build
+description: Understanding how to develop and build EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+## Edit your project
+
+To make changes to your project, open your project folder in your code editor. Working in development mode with the dev server running allows you to see updates to your site as you edit the code.
+
+## Starting the development server
+
+EventCatalog comes with a built-in development server that has everything you need for project development. The `eventcatalog dev` CLI command will start the local development server so that you can see your new website in action for the very first time.
+
+Every starter template comes with a pre-configured script that will run `eventcatalog dev` for you. After navigating into your project directory, run this command and start the EventCatalog development server:
+
+```bash
+npm run dev
+```
+If all goes well, EventCatalog will now be serving your project on http://localhost:3000/. Visit that link in your browser and see your new site!
+
+## Build and preview your catalog
+
+To check the version of your site that will be created at build time, quit the dev server (Ctrl + C) and run the appropriate build command in your terminal:
+
+```bash
+npm run build
+```
+
+EventCatalog will build a deploy-ready version of your site in a separate folder (dist/ by default) and you can watch its progress in the terminal. This will alert you to any build errors in your project before you deploy to production.
+
+When the build is finished, run the appropriate preview command (e.g. npm run preview) in your terminal and you can view the built version of your site locally in the same browser preview window.
+
+Note that this previews your code as it existed when the build command was last run. This is meant to give you a preview of how your site will look when it is deployed to the web. Any later changes you make to your code after building will not be reflected while you preview your site until you run the build command again.
+
+Use (Ctrl + C) to quit the preview and run another terminal command, such as restarting the dev server to go back to working in development mode which does update as you edit to show a live preview of your code changes.
+
+
+## EventCatalog static vs server output
+
+By default, EventCatalog will build a static website. This means you can [host this website](/docs/development/deployment/hosting-options) anywhere you like.
+
+Some features of EventCatalog (e.g SSO) require a to run EventCatalog as a server.
+
+You can opt into which build mode you want to use by setting the [`output` property in your `eventcatalog.config.js` file](/docs/api/config#output).
+
+
+<!-- ## Supported plugins
+
+EventCatalog uses [MDX](https://mdxjs.com/) file format for documentation.
+
+If you are using VSCode you can install the [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) plugin, for the `.mdx` files.
+
+Recommended Plugins:
+    - https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx
+    - https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode -->
+
+## Next Steps
+
+Success! You are now ready to start building with EventCatalog! 🥳
+
+Here are a few things that we recommend exploring next. You can read them in any order. You can even leave our documentation for a bit and go play in your new EventCatalog project codebase, coming back here whenever you run into trouble or have a question.
+
+- [Create your first domain](/docs/development/guides/domains/create-domain)
+- [Create your first system](/docs/development/guides/systems/create-system)
+- [Create your first service](/docs/development/guides/resources/services/create-service)
+- [Create your first message](/docs/development/guides/resources/messages/what-are-messages)
diff --git a/packages/core/docs/development/01-getting-started/installation.md b/packages/core/docs/development/01-getting-started/installation.md
new file mode 100644
index 000000000..f4e6ce797
--- /dev/null
+++ b/packages/core/docs/development/01-getting-started/installation.md
@@ -0,0 +1,111 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog installation install
+sidebar_label: Installation
+title: Installation
+description: Install EventCatalog and create a new catalog
+---
+
+The `create-eventcatalog` CLI command is the fastest way to start a new EventCatalog project. It creates a catalog directory, installs what you need, and gives you scripts for local development and production builds.
+
+You can also start from a template, create an empty catalog, or use the EventCatalog AI skill to generate documentation from an existing codebase.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download/) v22 or higher. Check your version with `node -v`.
+- A terminal to run the EventCatalog CLI.
+- A text editor to edit your catalog files.
+
+## Install from the CLI wizard
+
+Run the following command in your terminal:
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog
+```
+
+This creates a `my-catalog` directory with:
+
+- an EventCatalog project
+- sample architecture resources
+- an `eventcatalog.config.js` file
+- a `package.json` file with scripts for local development and builds
+
+Now move into your new project directory:
+
+```bash
+cd my-catalog
+```
+
+If the CLI asks whether to install dependencies and you skip that step, install them before continuing:
+
+```bash
+npm install
+```
+
+## Start the development server
+
+Start EventCatalog locally:
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view your catalog.
+
+## CLI installation flags
+
+You can pass flags to `create-eventcatalog` to customize the catalog that gets created.
+
+### Create an empty catalog
+
+Use `--empty` when you want a clean catalog without sample resources.
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --empty
+```
+
+### Use a starter template
+
+Use `--template` to start from one of the EventCatalog integration templates.
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --template asyncapi
+```
+
+Templates are useful when you already know which integration you want to use, such as AsyncAPI, OpenAPI, EventBridge, GitHub, or a schema registry.
+
+## Generate a catalog from an existing codebase
+
+If you already have a codebase, you can use the [Catalog Documentation Creator](https://github.com/event-catalog/skills) AI skill to generate EventCatalog documentation from the information in your project.
+
+First, add the EventCatalog skill to your project:
+
+```bash
+npx skills add event-catalog/skills --skill catalog-documentation-creator
+```
+
+Then ask your AI agent to inspect your codebase and generate EventCatalog documentation:
+
+```txt
+Look at my directory and generate EventCatalog documentation from information you find.
+```
+
+The generated files can be edited like any other EventCatalog documentation. Learn more about [EventCatalog skills](/docs/development/ask-your-architecture/skills/introduction).
+
+## Optional: Use EventCatalog Editor
+
+You can edit your catalog files directly in Markdown, or use [EventCatalog Editor](/docs/editor/overview) for a local visual editing workflow.
+
+The editor runs on top of your EventCatalog project, writes changes back to your local files, and gives you a Git-backed way to review and publish changes. This is useful when architects, developers, analysts, or product owners need to help maintain the catalog without working directly in Markdown.
+
+To use the editor, you need Git installed and editor access through [EventCatalog Cloud](https://eventcatalog.cloud). Learn how to [run EventCatalog Editor locally](/docs/editor/how-to/run-locally).
+
+## Next steps
+
+- [Understand the project structure](/docs/development/getting-started/project-structure)
+- [Develop and build your catalog](/docs/development/getting-started/develop-and-build)
+- [Create your first domain](/docs/development/guides/domains/create-domain)
+- [Create your first service](/docs/development/guides/resources/services/create-service)
+- [Document your first message](/docs/development/guides/resources/messages/what-are-messages)
diff --git a/packages/core/docs/development/01-getting-started/project-structure.md b/packages/core/docs/development/01-getting-started/project-structure.md
new file mode 100644
index 000000000..56fb622b0
--- /dev/null
+++ b/packages/core/docs/development/01-getting-started/project-structure.md
@@ -0,0 +1,204 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog project structure
+sidebar_label: Project structure
+title: Project structure
+description: Understanding how to structure your EventCatalog project
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+An EventCatalog project is a folder of Markdown files that describe and model your architecture.
+
+You can edit these files directly, or use the optional [EventCatalog Editor](/docs/editor/overview) to create, preview, review, and commit catalog content through a visual workflow.
+
+Each resource type in your catalog (e.g domain, system, message) is represented by a file or folder in your project. EventCatalog reads those files and turns them into a catalog.
+
+You can also bring your own documentation into EventCatalog, such as guides, onboarding material, or runbooks. Learn more about [bringing your own documentation](/docs/development/bring-your-own-documentation/introduction).
+
+All resource types are optional. You decide what you want to document, and you can add more resource types later as your catalog becomes more useful to your teams.
+
+## Directories and files
+
+Every EventCatalog project has a few core files used to run and configure the catalog. 
+
+Architecture resources exist in folders such as `domains/`, `systems/`, `services/`, and `events/`. All resources in EventCatalog are optional, it's up to you how you want to model and document your architecture.
+
+EventCatalog creates resources from folders that contain an `index.mdx` file. For example, `domains/Orders/index.mdx` creates an `Orders` domain, `domains/Orders/systems/order-management-system/index.mdx` creates an `order-management-system` system inside that domain, and `domains/Orders/systems/order-management-system/services/OrderService/index.mdx` creates an `OrderService` service inside that system.
+
+- `eventcatalog.config.js` - Configures your catalog.
+- `package.json` - Defines scripts and dependencies.
+- `public/` - Stores static assets that should be served directly.
+- `domains/` - Documents business domains and bounded contexts.
+- `systems/` - Documents groups of resources that work together to provide a capability.
+- `services/` - Documents services, APIs, applications, external systems, jobs, and workers.
+- `events/`, `commands/`, `queries/` - Documents messages.
+- `channels/` - Documents topics, queues, streams, webhooks, or other communication paths.
+- `diagrams/` - Documents architecture diagrams and flows.
+- `teams/` and `users/` - Documents ownership metadata.
+
+### Example project tree
+
+A common EventCatalog project directory might look like this:
+
+<ProjectTree
+  items={[
+    { name: 'eventcatalog.config.js' },
+    { name: 'package.json' },
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: false,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: false,
+          children: [
+            { name: 'index.mdx', highlight: true },
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: false,
+              children: [
+                {
+                  name: 'order-management-system',
+                  type: 'folder',
+                  defaultOpen: false,
+                  children: [
+                    { name: 'index.mdx', highlight: true },
+                    {
+                      name: 'services',
+                      type: 'folder',
+                      defaultOpen: false,
+                      children: [
+                        {
+                          name: 'OrderService',
+                          type: 'folder',
+                          defaultOpen: false,
+                          children: [
+                            { name: 'index.mdx' },
+                            { name: 'openapi.yaml' },
+                            { name: 'asyncapi.yaml' },
+                            {
+                              name: 'events',
+                              type: 'folder',
+                              defaultOpen: false,
+                              children: [
+                                {
+                                  name: 'OrderPlaced',
+                                  type: 'folder',
+                                  defaultOpen: false,
+                                  children: [
+                                    { name: 'index.mdx' },
+                                    { name: 'schema.avsc' },
+                                  ],
+                                },
+                              ],
+                            },
+                            {
+                              name: 'commands',
+                              type: 'folder',
+                              defaultOpen: false,
+                              children: [
+                                {
+                                  name: 'CancelOrder',
+                                  type: 'folder',
+                                  children: [{ name: 'index.mdx' }],
+                                },
+                              ],
+                            },
+                            {
+                              name: 'queries',
+                              type: 'folder',
+                              defaultOpen: false,
+                              children: [
+                                {
+                                  name: 'GetOrder',
+                                  type: 'folder',
+                                  children: [{ name: 'index.mdx' }],
+                                },
+                              ],
+                            },
+                          ],
+                        },
+                      ],
+                    },
+                    {
+                      name: 'containers',
+                      type: 'folder',
+                      defaultOpen: false,
+                      children: [
+                        {
+                          name: 'orders-db',
+                          type: 'folder',
+                          children: [{ name: 'index.mdx' }],
+                        },
+                      ],
+                    },
+                    {
+                      name: 'flows',
+                      type: 'folder',
+                      defaultOpen: false,
+                      children: [
+                        {
+                          name: 'order-fulfilment',
+                          type: 'folder',
+                          children: [{ name: 'index.mdx' }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'teams',
+      type: 'folder',
+      defaultOpen: false,
+      children: [{ name: 'mobile-team.mdx' }],
+    },
+    {
+      name: 'users',
+      type: 'folder',
+      defaultOpen: false,
+      children: [{ name: 'dboyne.mdx' }],
+    },
+    {
+      name: 'public',
+      type: 'folder',
+      defaultOpen: false,
+      children: [
+        {
+          name: 'icons',
+          type: 'folder',
+          children: [{ name: 'orders.svg' }],
+        },
+      ],
+    },
+  ]}
+/>
+
+You do not need every folder on day one. Start with the resources you know about, then add more as your catalog grows.
+
+## What should I create first?
+
+If you want to create your first few resources you can follow our [Learning EventCatalog Guide](/learn).
+
+## Next Steps
+
+Now you know some of the ways EventCatalog work, you can start to document some of your architecture resources.
+Here are some links below to help depending on what you want to document.
+
+:::tip Using AI to help
+AI is great at helping you document and get going with EventCatalog. You can install our [EventCatalog Skills](https://github.com/event-catalog/eventcatalog-skills) to teach your LLM about EventCatalog, and then ask your LLM to help you get going.
+:::
+
+- [Start documenting a business domain](/docs/development/guides/domains/introduction)
+- [Start documenting a system](/docs/development/guides/systems/create-system)
+- [Start documenting producers and consumers of a service](/docs/development/guides/resources/services/introduction)
diff --git a/packages/core/docs/development/_category_.json b/packages/core/docs/development/_category_.json
new file mode 100644
index 000000000..6fa1f6fae
--- /dev/null
+++ b/packages/core/docs/development/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Development",
+  "position": 2,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "development",
+    "title": "EventCatalog documentation",
+    "description": "EventCatalog documentation. Learn about the fundamentals of EventCatalog."
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/development/_getting-started.mdx b/packages/core/docs/development/_getting-started.mdx
new file mode 100644
index 000000000..306c5b246
--- /dev/null
+++ b/packages/core/docs/development/_getting-started.mdx
@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog introduction
+sidebar_label: Getting Started
+title: Getting Started
+description: EventCatalog is an open source project to help you bring discoverability to your event-driven architecture.
+hide_title: true
+hide_table_of_contents: true
+hide_breadcrumbs: true
+---
+
+import DocumentationLanding from '@site/src/components/MDX/DocumentationLanding';
+
+<DocumentationLanding />
diff --git a/packages/core/docs/development/agent-resources/_category_.json b/packages/core/docs/development/agent-resources/_category_.json
new file mode 100644
index 000000000..00706688a
--- /dev/null
+++ b/packages/core/docs/development/agent-resources/_category_.json
@@ -0,0 +1,6 @@
+{
+  "label": "Agent Resources",
+  "position": 14,
+  "collapsible": true,
+  "collapsed": false
+}
diff --git a/packages/core/docs/development/agent-resources/eventcatalog-skills.md b/packages/core/docs/development/agent-resources/eventcatalog-skills.md
new file mode 100644
index 000000000..f5f54f2ad
--- /dev/null
+++ b/packages/core/docs/development/agent-resources/eventcatalog-skills.md
@@ -0,0 +1,17 @@
+---
+sidebar_position: 1
+sidebar_label: EventCatalog Skills
+title: EventCatalog Skills
+custom_edit_url: null
+---
+
+import BrowserOnly from '@docusaurus/BrowserOnly';
+
+<BrowserOnly>
+  {() => {
+    window.location.href = 'https://github.com/event-catalog/eventcatalog-skills';
+    return null;
+  }}
+</BrowserOnly>
+
+<a href="https://github.com/event-catalog/eventcatalog-skills">EventCatalog Skills</a>
diff --git a/packages/core/docs/development/agent-resources/llms-full.md b/packages/core/docs/development/agent-resources/llms-full.md
new file mode 100644
index 000000000..bad2dbfd5
--- /dev/null
+++ b/packages/core/docs/development/agent-resources/llms-full.md
@@ -0,0 +1,17 @@
+---
+sidebar_position: 3
+sidebar_label: EventCatalog Docs llms-full.txt
+title: EventCatalog Docs llms-full.txt
+custom_edit_url: null
+---
+
+import BrowserOnly from '@docusaurus/BrowserOnly';
+
+<BrowserOnly>
+  {() => {
+    window.location.href = 'https://www.eventcatalog.dev/llms-full.txt';
+    return null;
+  }}
+</BrowserOnly>
+
+<a href="https://www.eventcatalog.dev/llms-full.txt">EventCatalog Docs llms-full.txt</a>
diff --git a/packages/core/docs/development/agent-resources/llms.md b/packages/core/docs/development/agent-resources/llms.md
new file mode 100644
index 000000000..dfbe9e20f
--- /dev/null
+++ b/packages/core/docs/development/agent-resources/llms.md
@@ -0,0 +1,17 @@
+---
+sidebar_position: 2
+sidebar_label: EventCatalog Docs llms.txt
+title: EventCatalog Docs llms.txt
+custom_edit_url: null
+---
+
+import BrowserOnly from '@docusaurus/BrowserOnly';
+
+<BrowserOnly>
+  {() => {
+    window.location.href = 'https://www.eventcatalog.dev/llms.txt';
+    return null;
+  }}
+</BrowserOnly>
+
+<a href="https://www.eventcatalog.dev/llms.txt">EventCatalog Docs llms.txt</a>
diff --git a/packages/core/docs/development/ask-your-architecture/01-intro.md b/packages/core/docs/development/ask-your-architecture/01-intro.md
new file mode 100644
index 000000000..8a3af3dac
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/01-intro.md
@@ -0,0 +1,21 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Using AI with EventCatalog
+title: AI with EventCatalog
+description: Architecture documentation for humans and AI
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+EventCatalog creates an internal graph of your architecture. Perfect for AI and LLMs.
+
+EventCatalog supports five ways to use AI with your catalog:
+
+- [llms.txt](/docs/development/ask-your-architecture/llms.txt) - Give AI tools a machine-readable index of your catalog.
+- [schemas.txt](/docs/development/ask-your-architecture/schemas.txt) - Give AI tools access to your schemas and specifications.
+- [EventCatalog Assistant](/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-eventcatalog-assistant) - AI Chat in your Catalog.
+- [EventCatalog MCP Server](/docs/development/ask-your-architecture/mcp-server/introduction) - Connect EventCatalog to Agents through MCP
+- [EventCatalog Agent](/docs/development/ask-your-architecture/agents/overview) - CI/CD Agent for breaking changes and doc updates
+- [AI Skills](/docs/development/ask-your-architecture/skills/introduction) - Install our Skills to help you manage your catalog
diff --git a/packages/core/docs/development/ask-your-architecture/02-eventcatalog-assistant/01-what-is-eventcatalog-assistant.md b/packages/core/docs/development/ask-your-architecture/02-eventcatalog-assistant/01-what-is-eventcatalog-assistant.md
new file mode 100644
index 000000000..c88908423
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/02-eventcatalog-assistant/01-what-is-eventcatalog-assistant.md
@@ -0,0 +1,24 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Assistant
+sidebar_label: What is EventCatalog Assistant?
+title: What is EventCatalog Assistant?
+description: Learn how EventCatalog Assistant helps users explore documentation using natural language.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+EventCatalog Assistant brings AI chat to your catalog.
+
+It is embedded directly into your documentation site, enabling users to quickly find answers, understand your system, and succeed without manually searching through pages.
+
+**You bring your own model to EventCatalog and your data is owned by you and never shared.**
+
+The assistant integrates with your preferred AI models using the [AI SDK](https://ai-sdk.dev/), giving you full control over which models power the experience.
+
+![EventCatalog Assistant](./images/example.png)
diff --git a/packages/core/docs/development/ask-your-architecture/02-eventcatalog-assistant/02-configuration.md b/packages/core/docs/development/ask-your-architecture/02-eventcatalog-assistant/02-configuration.md
new file mode 100644
index 000000000..48e02973a
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/02-eventcatalog-assistant/02-configuration.md
@@ -0,0 +1,73 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Assistant
+sidebar_label: Configuration    
+title: Configuration
+description: Configure EventCatalog Assistant
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+**EventCatalog Assistant is turned off by default.**
+
+To enable the assistant feature, you need to set the following:
+
+1. Turn on the `chat` feature in your `eventcatalog.config.js` file and add 
+2. Add a `eventcatalog.chat.js` file to your catalog.
+
+### Enabling the feature
+
+To turn on the assistant feature, you need to set the following:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  // Enable the chat feature in your catalog
+  chat: {
+    enabled: true,
+  },
+  // AI integrations require you to run eventcatalog as as server
+  output: 'server'
+};
+```
+
+### Installing your model and configuring `eventcatalog.chat.js` file
+
+First you have to install your model of choice ([list of models](https://ai-sdk.dev/docs/foundations/providers-and-models#ai-sdk-providers)) and configure the relevant secrets in your `.env` file.
+
+_Example of installing the OpenAI model:_
+
+```md
+<!-- in the root of your project -->
+npm install @ai-sdk/openai
+```
+
+#### Configuring `eventcatalog.chat.js`
+
+This file will provide the model and any model configuration to EventCatalog.
+
+In the example below we are using the OpenAI model `gpt-4.1-nano` and configuring the model with some additional parameters.
+
+```js title="eventcatalog.chat.js"
+import { openai } from '@ai-sdk/openai';
+
+// Export your model using the default export
+export default async () => {
+    return openai('gpt-4.1-nano');
+}
+
+// Export the configuration for the model (optional)
+export const configuration = {
+    topP: 0.9,
+    topK: 40,
+    frequencyPenalty: 0.0,
+    presencePenalty: 0.0,
+    temperature: 0.7,
+    maxTokens: 10000,
+}
+```
+
+Once you have enabled the feature and configured your model, restart EventCatalog and you can start asking questions about your architecture.
diff --git a/packages/core/docs/development/ask-your-architecture/02-eventcatalog-assistant/03-bring-your-own-tools.md b/packages/core/docs/development/ask-your-architecture/02-eventcatalog-assistant/03-bring-your-own-tools.md
new file mode 100644
index 000000000..bf0169cd5
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/02-eventcatalog-assistant/03-bring-your-own-tools.md
@@ -0,0 +1,383 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog Assistant
+- Custom Tools
+- AI Tools
+- Runtime Data
+- Metrics
+sidebar_label: Configure your own tools
+title: Custom Tools
+description: Extend EventCatalog Assistant with custom tools to bring real-time data, metrics, and integrations into your architecture conversations
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<PlanBanner plan="Scale" />
+
+EventCatalog Assistant comes with built-in tools that allow the AI to search and understand your architecture documentation. But what if you could go beyond static documentation and bring **real-time data** directly into your conversations?
+
+With custom tools, you can extend the assistant to query your production metrics, check service health, look up on-call engineers, fetch data from your databases, and much more.
+
+## Why custom tools?
+
+Your architecture documentation tells part of the story, but the real value often lies in the runtime data:
+
+- **Production metrics** - How many events per second? What's the error rate?
+- **Service health** - Is OrderService healthy right now?
+- **Queue depths** - Are there any event backlogs building up?
+- **On-call information** - Who should I contact about PaymentService?
+- **Database queries** - What's the current state of this entity?
+- **External APIs** - Enrich answers with data from Datadog, PagerDuty, Jira, etc.
+
+Custom tools transform EventCatalog from a static documentation site into a **live knowledge hub** where developers can ask questions like:
+
+> "Is OrderService healthy and who should I contact if there's an issue?"
+
+And get real answers based on live data.
+
+## How it works
+
+Custom tools are defined in your `eventcatalog.chat.js` file alongside your model configuration. Each tool has:
+
+1. **A description** - Tells the AI when to use this tool
+2. **An input schema** - Defines what parameters the tool accepts (using Zod)
+3. **An execute function** - The code that runs when the tool is called
+
+The AI automatically decides when to use your tools based on the user's question and the tool descriptions.
+
+## Creating custom tools
+
+### Basic example
+
+Here's a simple tool that returns service health information:
+
+```js title="eventcatalog.chat.js"
+import { anthropic } from '@ai-sdk/anthropic';
+import { tool } from 'ai';
+import { z } from 'zod';
+
+// Export your model
+export default async () => {
+    return anthropic('claude-haiku-4-5');
+}
+
+// Export custom tools
+export const tools = {
+    getServiceHealth: tool({
+        description: 'Get the current health status of a service including uptime and active instances. Use this when users ask if a service is up, healthy, or having issues.',
+        inputSchema: z.object({
+            serviceName: z.string().describe('The name of the service to check health for'),
+        }),
+        execute: async ({ serviceName }) => {
+            // In production, query your monitoring system (Datadog, Prometheus, etc.)
+            const response = await fetch(`https://your-monitoring-api.com/health/${serviceName}`);
+            const health = await response.json();
+
+            return {
+                serviceName,
+                status: health.status,
+                uptime: health.uptime,
+                instances: health.activeInstances,
+                lastIncident: health.lastIncident,
+            };
+        },
+    }),
+};
+```
+
+### The AI uses tools automatically
+
+Once configured, the AI will automatically use your tools when relevant. If a user asks:
+
+> "Is the OrderService healthy?"
+
+The assistant will:
+1. Recognize this is a health-related question
+2. Call your `getServiceHealth` tool with `serviceName: "OrderService"`
+3. Use the returned data to formulate a helpful response
+
+## Example tools
+
+### Production metrics
+
+Query real-time metrics from your observability platform:
+
+```js
+getEventMetrics: tool({
+    description: 'Get real-time production metrics for an event including throughput, latency, and error rates. Use this when users ask about event performance, traffic, or production health.',
+    inputSchema: z.object({
+        eventId: z.string().describe('The event ID to get metrics for'),
+        timeRange: z.enum(['1h', '24h', '7d', '30d']).default('24h').describe('Time range for metrics'),
+    }),
+    execute: async ({ eventId, timeRange }) => {
+        // Query Datadog, Prometheus, CloudWatch, etc.
+        const metrics = await datadogClient.getMetrics(eventId, timeRange);
+
+        return {
+            eventId,
+            timeRange,
+            throughput: `${metrics.eventsPerSecond.toLocaleString()} events/sec`,
+            latency: {
+                p50: `${metrics.p50}ms`,
+                p99: `${metrics.p99}ms`,
+            },
+            errorRate: `${metrics.errorRate}%`,
+            status: metrics.errorRate > 0.1 ? 'degraded' : 'healthy',
+        };
+    },
+}),
+```
+
+### On-call information
+
+Look up who's on-call for a service:
+
+```js
+getOnCall: tool({
+    description: 'Get the current on-call engineer and escalation contacts for a service. Use this when users ask who to contact, who owns a service, or who is on-call.',
+    inputSchema: z.object({
+        serviceName: z.string().describe('The name of the service to get on-call info for'),
+    }),
+    execute: async ({ serviceName }) => {
+        // Query PagerDuty, OpsGenie, or your internal system
+        const oncall = await pagerdutyClient.getOnCall(serviceName);
+
+        return {
+            serviceName,
+            team: oncall.team,
+            primary: {
+                name: oncall.primary.name,
+                email: oncall.primary.email,
+                slack: oncall.primary.slack,
+            },
+            secondary: oncall.secondary,
+            slackChannel: oncall.slackChannel,
+            escalationPolicy: oncall.escalationUrl,
+        };
+    },
+}),
+```
+
+### Queue depth and consumer lag
+
+Monitor your message brokers:
+
+```js
+getQueueDepth: tool({
+    description: 'Get the current queue depth, consumer lag, and processing rate for an event. Use this when users ask about event backlogs, processing delays, or queue health.',
+    inputSchema: z.object({
+        eventId: z.string().describe('The event ID to check queue depth for'),
+        environment: z.enum(['production', 'staging', 'development']).default('production'),
+    }),
+    execute: async ({ eventId, environment }) => {
+        // Query Kafka, RabbitMQ, SQS, etc.
+        const queue = await kafkaClient.getConsumerLag(eventId, environment);
+
+        return {
+            eventId,
+            environment,
+            status: queue.lag > 30 ? 'critical' : queue.lag > 5 ? 'warning' : 'healthy',
+            queue: {
+                depth: queue.depth.toLocaleString(),
+                oldestMessage: `${queue.lag.toFixed(1)} seconds ago`,
+            },
+            consumers: {
+                active: queue.consumers,
+                processingRate: `${queue.rate.toLocaleString()} events/sec`,
+            },
+        };
+    },
+}),
+```
+
+### Database queries
+
+Look up entity state from your databases:
+
+```js
+getEntityState: tool({
+    description: 'Get the current state of an entity from the database. Use this when users ask about the current state of an order, user, or other business entity.',
+    inputSchema: z.object({
+        entityType: z.enum(['order', 'user', 'product', 'inventory']),
+        entityId: z.string().describe('The ID of the entity to look up'),
+    }),
+    execute: async ({ entityType, entityId }) => {
+        // Query your database
+        const entity = await db.collection(entityType).findOne({ id: entityId });
+
+        return {
+            entityType,
+            entityId,
+            state: entity.state,
+            lastUpdated: entity.updatedAt,
+            history: entity.stateHistory?.slice(-5), // Last 5 state changes
+        };
+    },
+}),
+```
+
+## Best practices
+
+### Write clear descriptions
+
+The AI uses tool descriptions to decide when to call them. Be specific about:
+- What the tool does
+- When it should be used
+- What kind of questions it answers
+
+```js
+// ❌ Vague description
+description: 'Gets metrics',
+
+// ✅ Clear description
+description: 'Get real-time production metrics for an event including throughput, latency, and error rates. Use this when users ask about event performance, traffic, or production health.',
+```
+
+### Return structured data
+
+Return well-structured objects that the AI can easily interpret:
+
+```js
+// ❌ Raw data dump
+return rawApiResponse;
+
+// ✅ Structured, meaningful data
+return {
+    serviceName,
+    status: health.status,
+    statusEmoji: health.status === 'healthy' ? '✅' : '⚠️',
+    uptime: `${health.uptime}%`,
+    recommendation: health.status !== 'healthy'
+        ? 'Consider scaling up instances'
+        : 'No action needed',
+};
+```
+
+### Handle errors gracefully
+
+Always handle potential errors in your tools:
+
+```js
+execute: async ({ serviceName }) => {
+    try {
+        const health = await monitoringApi.getHealth(serviceName);
+        return { serviceName, ...health };
+    } catch (error) {
+        return {
+            serviceName,
+            error: `Unable to fetch health data: ${error.message}`,
+            suggestion: 'Check if the monitoring API is available',
+        };
+    }
+},
+```
+
+### Secure your tools
+
+Remember that tools execute server-side. Keep security in mind:
+
+- **Validate inputs** - Don't trust user-provided data
+- **Use least privilege** - Only grant tools the permissions they need
+- **Protect secrets** - Store API keys in environment variables
+- **Rate limit** - Consider adding rate limiting for expensive operations
+
+```js
+execute: async ({ serviceName }) => {
+    // Validate the service name exists in your catalog
+    const validServices = await getServices();
+    if (!validServices.includes(serviceName)) {
+        return { error: 'Service not found in catalog' };
+    }
+
+    // Proceed with the query...
+},
+```
+
+## Complete example
+
+Here's a complete `eventcatalog.chat.js` with multiple tools:
+
+```js title="eventcatalog.chat.js"
+import { anthropic } from '@ai-sdk/anthropic';
+import { tool } from 'ai';
+import { z } from 'zod';
+
+// Your model configuration
+export default async () => {
+    return anthropic('claude-haiku-4-5');
+}
+
+export const configuration = {
+    temperature: 0.7,
+    maxTokens: 10000,
+}
+
+// Your custom tools
+export const tools = {
+    getEventMetrics: tool({
+        description: 'Get real-time production metrics for an event including throughput, latency, and error rates.',
+        inputSchema: z.object({
+            eventId: z.string(),
+            timeRange: z.enum(['1h', '24h', '7d', '30d']).default('24h'),
+        }),
+        execute: async ({ eventId, timeRange }) => {
+            // Your implementation
+        },
+    }),
+
+    getServiceHealth: tool({
+        description: 'Get the current health status of a service including uptime and active instances.',
+        inputSchema: z.object({
+            serviceName: z.string(),
+        }),
+        execute: async ({ serviceName }) => {
+            // Your implementation
+        },
+    }),
+
+    getOnCall: tool({
+        description: 'Get the current on-call engineer and escalation contacts for a service.',
+        inputSchema: z.object({
+            serviceName: z.string(),
+        }),
+        execute: async ({ serviceName }) => {
+            // Your implementation
+        },
+    }),
+
+    getQueueDepth: tool({
+        description: 'Get the current queue depth and consumer lag for an event.',
+        inputSchema: z.object({
+            eventId: z.string(),
+            environment: z.enum(['production', 'staging', 'development']).default('production'),
+        }),
+        execute: async ({ eventId, environment }) => {
+            // Your implementation
+        },
+    }),
+};
+```
+
+## Viewing available tools
+
+Users can see all available tools (including custom ones) by clicking the **wrench icon** in the chat panel. Custom tools are labeled with a "Custom" badge to distinguish them from built-in tools.
+
+## What can you build?
+
+The possibilities are endless. Here are some ideas:
+
+- **Cost tracking** - "How much did the OrderCreated event cost to process last month?"
+- **Compliance checks** - "Does the PaymentService meet our SLA requirements?"
+- **Deployment info** - "When was InventoryService last deployed?"
+- **Incident history** - "What incidents has NotificationService had this quarter?"
+- **Schema validation** - "Would this schema change break any consumers?"
+- **Test coverage** - "What's the test coverage for OrderService?"
+- **Documentation gaps** - "Which events are missing descriptions?"
+
+Custom tools turn EventCatalog into your organization's single pane of glass for architecture knowledge—combining static documentation with live operational data.
+
+---
+
+Have questions about custom tools? [Join our Discord community](https://eventcatalog.dev/discord) to share ideas and get help.
diff --git a/packages/core/docs/development/ask-your-architecture/02-eventcatalog-assistant/_category_.json b/packages/core/docs/development/ask-your-architecture/02-eventcatalog-assistant/_category_.json
new file mode 100644
index 000000000..a9c24dc4d
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/02-eventcatalog-assistant/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "EventCatalog Assistant",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development/guides/eventcatalog-assistant",
+    "description": "EventCatalog Assistant"
+  }
+}
diff --git a/packages/core/docs/development/ask-your-architecture/02-llms.txt.md b/packages/core/docs/development/ask-your-architecture/02-llms.txt.md
new file mode 100644
index 000000000..6b3c8b6f6
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/02-llms.txt.md
@@ -0,0 +1,65 @@
+---
+sidebar_position: 2
+keywords:
+- llms.txt
+- AI
+- LLM
+sidebar_label: llms.txt
+title: LLMS.txt
+description: Understanding how to use LLMS.txt with EventCatalog and your LLMs
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.20.0" />
+
+Enable tools like Claude, ChatGPT, GitHub Copilot, and Cursor to quickly understand your EventCatalog.
+
+### What is LLMS.txt?
+
+[LLMS.txt](https://llmstxt.org/) is a proposed standard that helps AI-powered development tools better understand and interact with your documentation. Similar to how robots.txt guides web crawlers, LLMS.txt provides structured information that makes it easier for AI assistants like Claude, ChatGPT, and GitHub Copilot to process your EventCatalog documentation.
+
+The file is automatically generated and maintained as part of your documentation pipeline, requiring no manual configuration. It organizes your documentation's key concepts, structures, and relationships in a format optimized for machine reading.
+
+### llms.txt and llms-full.txt
+
+The `llms.txt` file includes your EventCatalog resources in a simple format, listing each resource with a short summary.
+
+The `llms-full.txt` file includes your EventCatalog resources in a more detailed format — all the contents of your catalog resources are included in the file.
+
+Both files cover events, commands, queries, services, domains, flows, channels, teams, users, entities, data products, and ubiquitous languages.
+
+### Enable in EventCatalog
+
+**`llms.txt` is enabled by default in EventCatalog.**
+
+You can disable it by turning it off in your `eventcatalog.config.js` file.
+
+```js title="eventcatalog.config.js"
+llmsTxt: {
+    enabled: false,
+},
+```
+
+### Access the files
+
+<AddedIn version="3.37.0" />
+
+The recommended URLs for AI tools are at the catalog root:
+
+ - `https://<your-catalog-url>/llms.txt`
+    - Demo: https://demo.eventcatalog.dev/llms.txt
+ - `https://<your-catalog-url>/llms-full.txt`
+    - Demo: https://demo.eventcatalog.dev/llms-full.txt
+
+The legacy paths `/docs/llm/llms.txt` and `/docs/llm/llms-full.txt` still work for backward compatibility.
+
+### How to use LLMS.txt?
+
+Once you deploy your EventCatalog you can use your tools to ask questions about your Catalog.
+
+![LLMS.txt](./img/ai-example.png)
+
+
+
+
diff --git a/packages/core/docs/development/ask-your-architecture/03-mcp-server/_category_.json b/packages/core/docs/development/ask-your-architecture/03-mcp-server/_category_.json
new file mode 100644
index 000000000..a859825bc
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/03-mcp-server/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "EventCatalog MCP Server",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/developer-tools/mcp-server",
+    "title": "MCP Server",
+    "description": "This section contains tutorials for the EventCatalog MCP Server."
+  }
+}
diff --git a/packages/core/docs/development/ask-your-architecture/03-mcp-server/getting-started.md b/packages/core/docs/development/ask-your-architecture/03-mcp-server/getting-started.md
new file mode 100644
index 000000000..013405f6b
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/03-mcp-server/getting-started.md
@@ -0,0 +1,288 @@
+---
+sidebar_position: 2
+keywords:
+- MCP Server
+sidebar_label: Installation
+title: Getting started
+description: Connect MCP clients to your EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+### Prerequisites
+
+1. **SSR mode** - EventCatalog must run in [server mode](/docs/development/deployment/build-ssr-mode#building-your-eventcatalog-ssr) (not static)
+2. **Scale license** - You can get a 30-day free trial at [eventcatalog.cloud](https://eventcatalog.cloud)
+
+### Quick start
+
+Your MCP server is available at:
+
+```
+https://your-eventcatalog.com/docs/mcp/
+```
+
+For local development:
+
+```
+http://localhost:3000/docs/mcp/
+```
+
+### Verify the server
+
+Visit the endpoint in your browser to verify. It returns available tools and resources:
+
+```json
+{
+  "name": "EventCatalog MCP Server",
+  "version": "1.0.0",
+  "status": "running",
+  "tools": ["getResources", "getResource", ...],
+  "resources": ["eventcatalog://all", "eventcatalog://events", ...]
+}
+```
+
+### Protect with OAuth
+
+<AddedIn version="3.40.0" />
+
+The built-in MCP server can be protected with OAuth Bearer tokens, following the MCP authorization specification for HTTP transports.
+
+EventCatalog acts as the OAuth protected resource server for `/docs/mcp`. Your identity provider or authorization server remains responsible for user login, consent, client registration, `/authorize`, `/oauth/token`, and token refresh.
+
+Configure MCP authorization in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  output: 'server',
+  mcp: {
+    auth: {
+      enabled: true,
+      resource: 'https://your-eventcatalog.com/docs/mcp',
+      authorizationServers: ['https://auth.example.com'],
+      issuer: 'https://auth.example.com',
+      audience: 'https://your-eventcatalog.com/docs/mcp',
+      requiredScopes: ['catalog:read'],
+      jwksUri: 'https://auth.example.com/.well-known/jwks.json',
+    },
+  },
+};
+```
+
+When enabled, EventCatalog serves protected resource metadata at `/.well-known/oauth-protected-resource`. Unauthenticated MCP clients receive a `401 Unauthorized` response with a `WWW-Authenticate` header pointing at that document. MCP clients then obtain an access token from the advertised authorization server and call `/docs/mcp` with:
+
+```http
+Authorization: Bearer <access-token>
+```
+
+The access token must be valid, unexpired, issued by the configured issuer, intended for the configured audience, and include all required scopes.
+
+#### Key signing options
+
+Choose one of the following strategies for token validation:
+
+| Strategy | Config fields |
+|---|---|
+| JWKS endpoint (recommended) | `jwksUri` |
+| Inline asymmetric public key | `publicKey` or `publicKeyEnvVar` |
+| Symmetric shared secret | `sharedSecret` or `sharedSecretEnvVar` |
+
+Prefer `publicKeyEnvVar` or `sharedSecretEnvVar` over inline values to avoid committing secrets to source control.
+
+#### All options
+
+| Field | Required | Description |
+|---|---|---|
+| `enabled` | Yes | Enables OAuth Bearer token validation |
+| `resource` | No | Absolute URL of the MCP resource. Set this explicitly when behind a proxy |
+| `protectedResourceMetadataUrl` | No | URL for the protected resource metadata document. Defaults to `/.well-known/oauth-protected-resource` |
+| `authorizationServers` | No | Authorization server URLs advertised to MCP clients |
+| `issuer` | No | Expected token issuer (`iss` claim) |
+| `audience` | No | Expected token audience (`aud` claim). Defaults to `resource` |
+| `requiredScopes` | No | Scopes every token must include |
+| `jwksUri` | No | JWKS endpoint for asymmetric JWT validation |
+| `publicKey` | No | Inline public key for asymmetric JWT validation |
+| `publicKeyEnvVar` | No | Environment variable containing the public key |
+| `sharedSecret` | No | Inline shared secret for symmetric JWT validation |
+| `sharedSecretEnvVar` | No | Environment variable containing the shared secret |
+
+:::note Existing website authentication
+The `auth.enabled` and `eventcatalog.auth.js` settings protect the EventCatalog website with browser sessions. MCP authorization is separate because MCP clients authenticate with Bearer tokens, not browser cookies.
+:::
+
+:::tip Authorization server discovery
+EventCatalog serves `/.well-known/oauth-protected-resource` for MCP client discovery. It does not serve `/.well-known/oauth-authorization-server`, `/authorize`, or `/oauth/token` -- those endpoints must be provided by the authorization server listed in `authorizationServers`. If your MCP client expects those endpoints on the catalog host, proxy the authorization server behind that host with your load balancer or reverse proxy.
+:::
+
+### Connect clients
+
+<details>
+<summary>Claude Desktop</summary>
+1. Get your MCP URL `https://your-eventcatalog.com/docs/mcp/`
+1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in Claude Settings.
+1. Select **Add custom connector**
+1. Select **Add**
+5. When using Claude, select the attachments button (the plus icon).
+6. Select your MCP server.
+</details>
+
+<details>
+<summary>Claude Code</summary>
+1. Get your MCP URL `https://your-eventcatalog.com/docs/mcp/`
+2. Run the command to connect claude code to your eventcatalog instance
+```bash
+claude mcp add --transport http <name> <url>
+```
+</details>
+
+<details>
+<summary>Cursor</summary>
+1. Get your MCP URL `https://your-eventcatalog.com/docs/mcp/`
+1. Use `Command` + `Shift` + `P` (`Ctrl` + `Shift` + `P` on Windows) to open the Command Palette.
+1. Search for "Open MCP settings"
+1. Select **Add custom MCP.** This opens the `mcp.json` file.
+1. Add the following to the `mcp.json` file:
+```json
+{
+  "servers": {
+    "<your-mcp-server-name>": {
+      "url": "https://your-eventcatalog.com/docs/mcp/"
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>VS Code</summary>
+1. Get your MCP URL `https://your-eventcatalog.com/docs/mcp/`
+1. Create a `.vscode/mcp.json` file.
+1. Inside the `mcp.json` file, add the following:
+```json
+{
+  "servers": {
+    "<your-mcp-server-name>": {
+      "type": "http",
+      "url": "https://your-eventcatalog.com/docs/mcp/"
+    }
+  }
+}
+```
+</details>
+
+## Available tools
+
+### 15 built-in tools
+
+- `getResources` - Get events, services, commands, queries, flows, domains
+- `getResource` - Get a specific resource by id and version
+- `getMessagesProducedOrConsumedByResource` - Messages a resource sends/receives
+- `getSchemaForResource` - Get OpenAPI, AsyncAPI, or other schemas
+- `findResourcesByOwner` - Resources owned by a team or user
+- `getProducersOfMessage` - Services that produce a message
+- `getConsumersOfMessage` - Services that consume a message
+- `analyzeChangeImpact` - Impact of changing a message
+- `explainBusinessFlow` - Detailed flow information
+- `getTeams` / `getTeam` - Query teams
+- `getUsers` / `getUser` - Query users
+- `findMessageBySchemaId` - Find messages by schema identifiers
+- `explainUbiquitousLanguageTerms` - DDD ubiquitous language from domains
+
+[See full API documentation →](/docs/development/ask-your-architecture/mcp-server/getting-started)
+
+### 12 resources
+
+- `eventcatalog://all` - All resources
+- `eventcatalog://events` - All events
+- `eventcatalog://commands` - All commands
+- `eventcatalog://queries` - All queries
+- `eventcatalog://services` - All services
+- `eventcatalog://channels` - All channels
+- `eventcatalog://diagrams` - All diagrams
+- `eventcatalog://containers` - All containers
+- `eventcatalog://domains` - All domains
+- `eventcatalog://flows` - All flows
+- `eventcatalog://teams` - All teams
+- `eventcatalog://users` - All users
+
+## Add custom tools
+
+Extend the MCP server with custom tools in `eventcatalog.chat.js`:
+
+```javascript
+// eventcatalog.chat.js
+export const tools = {
+  myCustomTool: {
+    description: 'My custom tool for EventCatalog',
+    parameters: z.object({
+      query: z.string().describe('The query parameter'),
+    }),
+    execute: async ({ query }) => {
+      // Your custom logic here
+      return { result: 'Custom data' };
+    },
+  },
+};
+```
+
+Custom tools appear alongside built-in tools automatically.
+
+## Use standalone server
+
+For catalogs without SSR mode, use the standalone `@eventcatalog/mcp-server` package. We plan to deprecate this in a future release, so we recommend migrating to the built-in server when possible.
+
+<details>
+<summary>Standalone server on stdio</summary>
+
+For local development and testing, you can use the MCP Server on stdio. This is useful for single-client, low-latency tools.
+
+**Prerequisites:**
+- EventCatalog configured with the [`LLMS.txt` feature](/docs/development/ask-your-architecture/llms.txt)
+- EventCatalog Scale license
+- MCP client installed
+
+**Command:**
+
+```bash
+npx -y @eventcatalog/mcp-server {URL_TO_YOUR_EVENTCATALOG_INSTANCE} {EVENTCATALOG_LICENSE_KEY}
+```
+
+</details>
+
+<details>
+<summary>Standalone server over HTTP</summary>
+
+Run the MCP Server over HTTP for production deployments.
+
+**Prerequisites:**
+- EventCatalog instance running
+- EventCatalog Scale license
+- MCP client installed
+
+**Run using npx:**
+
+```bash
+npx -y @eventcatalog/mcp-server https://your-eventcatalog-instance.com {EVENTCATALOG_LICENSE_KEY} http {PORT} {ROOT_PATH}
+```
+
+**Example:**
+
+```bash
+npx -y @eventcatalog/mcp-server https://demo.eventcatalog.dev {EVENTCATALOG_LICENSE_KEY} http 3000 /mcp
+```
+
+This starts the MCP Server over HTTP on port 3000 with root path `/mcp`.
+
+**Run using Docker:**
+
+See [instructions on the GitHub repository](https://github.com/event-catalog/mcp-server/blob/main/README.Docker.md).
+
+</details>
+
+
+
+
+
diff --git a/packages/core/docs/development/ask-your-architecture/03-mcp-server/introduction.md b/packages/core/docs/development/ask-your-architecture/03-mcp-server/introduction.md
new file mode 100644
index 000000000..69b91c348
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/03-mcp-server/introduction.md
@@ -0,0 +1,24 @@
+---
+sidebar_position: 1
+keywords:
+- MCP Server
+sidebar_label: Introduction
+title: MCP server
+description: Connect AI tools to your architecture catalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+EventCatalog exposes an MCP server. This allows you to connect any MCP client to your catalog to fetch the relevant information about your architecture when you need it.
+
+EventCatalog MCP server has out the box tools, that helps your AI agents and LLMs query the correct information based on the task it is trying to do.
+
+
+
+
+
+
diff --git a/packages/core/docs/development/ask-your-architecture/03-schemas.txt.md b/packages/core/docs/development/ask-your-architecture/03-schemas.txt.md
new file mode 100644
index 000000000..da723460f
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/03-schemas.txt.md
@@ -0,0 +1,41 @@
+---
+sidebar_position: 3
+keywords:
+- mermaid
+sidebar_label: schemas.txt
+title: schemas.txt
+description: Understanding how to use schemas.txt with EventCatalog and your schemas
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.64.0" />
+
+Enable tools like Claude, ChatGPT, GitHub Copilot, and Cursor to quickly fetch and understand your EventCatalog schemas.
+
+Message schemas and service specifications can be fetched from your EventCatalog and used in your own applications.
+
+### What is schemas.txt?
+
+Schemas.txt is very similar to [LLMS.txt](/docs/development/ask-your-architecture/llms.txt), but it is specifically for schemas in your EventCatalog. 
+
+Schemas.txt supports any schema format for your messages (e.g Avro, Protobuf, JSON Schema etc) and any specification for your services (e.g OpenAPI, AsyncAPI, GraphQL etc).
+
+The schemas.txt file is automatically generated and maintained as part of your documentation pipeline, requiring no manual configuration. It organizes your schemas in a format optimized for machine reading.
+
+### schemas.txt and schemas-full.txt
+
+The `schemas.txt` file includes your EventCatalog schemas in a simple format. Lists your schemas with a summary for each of them.
+
+### How to use schemas.txt?
+
+The [EventCatalog MCP](/docs/development/ask-your-architecture/mcp-server/introduction) already uses the schemas.txt file to provide access to your schemas in your MCP clients (e.g Cursor, Windsurf, Claude Desktop etc).
+
+If you want to use schemas.txt in your own application, you can query the urls:
+
+ - `https://<your-catalog-url>/docs/llm/schemas.txt`
+    - Demo: https://demo.eventcatalog.dev/docs/llm/schemas.txt
+
+
+
+
diff --git a/packages/core/docs/development/ask-your-architecture/04-agents/01-overview.md b/packages/core/docs/development/ask-your-architecture/04-agents/01-overview.md
new file mode 100644
index 000000000..2bc26b2af
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/04-agents/01-overview.md
@@ -0,0 +1,27 @@
+---
+sidebar_position: 1
+keywords:
+  - AI Agents
+  - documentation generation
+  - automation
+sidebar_label: Overview
+title: EventCatalog Agents
+description: AI agents that help you manage and document your architecture with EventCatalog
+---
+
+[EventCatalog Agent](https://github.com/event-catalog/agents) is an agent that helps you manage your documentation through CI/CD and adds a governing layer to your pull requests.
+
+Our Agent understands EventCatalog conventions (domains, systems and resources) and uses that understanding to keep your architecture documented for you, without you having to hand-write and maintain every catalog file yourself.
+
+EventCatalog Agent lets you define and bring your own model.
+
+### Available workflows
+
+| Agent | What it does |
+| --- | --- |
+| [Code-to-Docs](/docs/development/ask-your-architecture/agents/code-to-docs) | The EventCatalog Agent will review your pull request code and update your catalog documentation for you. |
+| [Breaking Changes](/docs/development/ask-your-architecture/agents/breaking-changes) | Detects breaking schema changes in a pull request and shows which catalog consumers could be affected. |
+
+### Have an idea for a workflow?
+
+More agents and AI workflows are on the way. If you have an idea for an agent or an AI workflow you'd like to see in EventCatalog, [open an issue on GitHub](https://github.com/event-catalog/agents/issues/new) and let us know. We use these ideas to decide what to build next.
diff --git a/packages/core/docs/development/ask-your-architecture/04-agents/02-code-to-docs.md b/packages/core/docs/development/ask-your-architecture/04-agents/02-code-to-docs.md
new file mode 100644
index 000000000..c831ad75b
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/04-agents/02-code-to-docs.md
@@ -0,0 +1,124 @@
+---
+sidebar_position: 2
+keywords:
+  - Code to Docs
+  - AI Agents
+  - GitHub Action
+  - documentation generation
+sidebar_label: Code-to-Docs Agent
+title: Code-to-Docs Agent
+description: Keep your EventCatalog documentation in sync with your code using the Code-to-Docs agent
+---
+
+The **Code-to-Docs** agent keeps your EventCatalog documentation in sync with your code.
+
+When you open a pull request, the agent reviews the diff, works out which documentation should change, updates it in your catalog repository, and opens (or updates) a documentation pull request. It then comments back on your source pull request with a summary and a link.
+
+## How it works
+
+```mermaid
+flowchart LR
+    PR[Source pull request] --> Agent[Code-to-Docs agent]
+    Agent --> Plan{Docs need<br/>updating?}
+    Plan -- No --> Comment[Comment on source PR]
+    Plan -- Yes --> Docs[Update catalog docs]
+    Docs --> CatalogPR[Open catalog pull request]
+    CatalogPR --> Comment
+```
+
+When a pull request is opened, the agent:
+
+1. **Checks out your catalog** so it can see your existing documentation.
+2. **Collects the changed source files** from the pull request.
+3. **Plans the impact**. A read-only pass where the agent decides whether the diff requires any documentation changes, and if so, exactly which catalog resources should change. If nothing is needed, it stops here and says so.
+4. **Applies the plan**. The agent updates the documentation, using EventCatalog conventions for frontmatter and folder structure, and a linter to validate its changes. It is only allowed to touch the resources approved in the plan.
+5. **Opens a catalog pull request** with the changes for you to review.
+6. **Comments on your source pull request** with a high-level summary and a link to the catalog pull request.
+
+You stay in control: the agent never edits your catalog silently. Every change arrives as a pull request you can review, tweak, and merge.
+
+## Getting started
+
+The Code-to-Docs agent runs as a GitHub Action. Add it to your repository in three steps.
+
+### 1. Add a new GitHub workflow
+
+Create a new workflow in your source directory. Typically this is where your source code lives (e.g a service that publishes/consumes messages).
+
+Create a `.github/workflows/eventcatalog.yml` file.
+
+```yaml
+on:
+  pull_request:
+
+jobs:
+  eventcatalog:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: event-catalog/agents@main
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        with:
+          agent: code-to-docs
+          catalog-repo: your-org/your-catalog
+          catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
+```
+
+`fetch-depth: 0` is required so the agent can diff the pull request against its base.
+
+### 2. Add your model provider key
+
+Add the API key for your chosen model as a secret in your repository (**Settings → Secrets and variables → Actions**). Use the one that matches your model, for example `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`.
+
+You can see the list of [available models here](https://pi.dev/models).
+
+### 3. Open a pull request
+
+When you next open a pull request on your project, the EventCatalog Agent will run.
+
+If your architecture changed, opens a documentation pull request in your catalog repository and comments back with a link.
+
+## Configuration
+
+### Inputs
+
+| Input | Required | Default | Description |
+| --- | --- | --- | --- |
+| `catalog-repo` | Yes | | The location of your hosted EventCatalog. EventCatalog repository to document into, in `owner/repo` format. |
+| `catalog-ref` | No | `main` | Branch checked out from the catalog repository and targeted by documentation pull requests. |
+| `catalog-token` | No | `github.token` | Token used to check out the catalog repository and open documentation pull requests. |
+| `model` | No | `anthropic/claude-sonnet-4-6` | Model specifier for the agent. See [available models](https://pi.dev/models). |
+| `ignore-paths` | No | common build/output paths | Comma-separated paths or glob patterns to ignore in pull request diffs. |
+| `agent` | No | `code-to-docs` | Which EventCatalog agent to run. Use `code-to-docs` for this workflow. |
+
+### Provider API keys
+
+The model provider's API key is passed as a normal workflow environment variable. Set the one that matches your `model`:
+
+| Provider | Environment variable |
+| --- | --- |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+
+The agent supports models from many providers. See the full list of model specifiers at [pi.dev/models](https://pi.dev/models).
+
+### Documenting into a separate catalog repository
+
+When your catalog lives in a **different** repository from your source code, provide a `catalog-token` with permission to push branches and open pull requests in that catalog repository (the default `github.token` only has access to the current repository).
+
+:::info Early access
+The Code-to-Docs agent is in early access and free to evaluate. In the future, a license will be required to run EventCatalog Agents in production.
+:::
+
+## Found an issue or have feedback?
+
+The Code-to-Docs agent is open on GitHub at [event-catalog/agents](https://github.com/event-catalog/agents). If you hit a problem, or the agent documents something in a way you didn't expect, [open an issue](https://github.com/event-catalog/agents/issues/new) and let us know. Your feedback during early access directly shapes how the agent works.
diff --git a/packages/core/docs/development/ask-your-architecture/04-agents/03-breaking-changes.md b/packages/core/docs/development/ask-your-architecture/04-agents/03-breaking-changes.md
new file mode 100644
index 000000000..e3b3000ce
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/04-agents/03-breaking-changes.md
@@ -0,0 +1,170 @@
+---
+sidebar_position: 3
+keywords:
+  - Breaking Changes
+  - AI Agents
+  - GitHub Action
+  - schema governance
+  - schema compatibility
+sidebar_label: Breaking Changes Agent
+title: Breaking Changes Agent
+description: Detect breaking schema changes and affected EventCatalog consumers from pull requests
+---
+
+The **Breaking Changes** agent reviews schema changes in pull requests and reports whether they are likely to break existing consumers.
+
+When a pull request changes a message schema, the agent checks whether the diff removes or renames fields, changes types, adds new required fields, narrows enums, or introduces similar compatibility risks. If it finds a breaking change, it traces the schema through your EventCatalog and comments on the source pull request with the breaking lines and affected consumers.
+
+The Breaking Changes agent is read-only. It does not edit your catalog or open documentation pull requests.
+
+![Breaking Changes agent pull request comment showing detected schema changes and affected consumers](./img/breaking-changes-agent.jpeg)
+
+## How it works
+
+```mermaid
+flowchart LR
+    PR[Source pull request] --> Agent[Breaking Changes agent]
+    Agent --> Schema{Schema<br/>changed?}
+    Schema -- No --> Skip[Nothing to report]
+    Schema -- Yes --> Breaking{Breaking<br/>change?}
+    Breaking -- No --> Skip
+    Breaking -- Yes --> Consumers[Find catalog consumers]
+    Consumers --> Comment[Comment on source PR]
+```
+
+When a pull request is opened, the agent:
+
+1. **Checks out your catalog** so it can understand the existing producers, consumers, messages, schemas, and flows.
+2. **Collects the changed source files** from the pull request.
+3. **Filters to schema files** using the configured schema extensions.
+4. **Scores each schema change** for breaking-change risk. Additive changes, such as adding an optional field, are skipped.
+5. **Finds affected consumers** for each breaking schema change by tracing the message through EventCatalog.
+6. **Comments on your source pull request** with the breaking change, the relevant diff lines, and the consumers that could be affected.
+
+If the pull request has no changed schema files, or only non-breaking schema changes, the workflow exits without creating a catalog pull request.
+
+## Getting started
+
+The Breaking Changes agent runs as a GitHub Action.
+
+### 1. Add a new GitHub workflow
+
+Create a `.github/workflows/eventcatalog-breaking-changes.yml` file in the repository where your source changes happen.
+
+```yaml
+on:
+  pull_request:
+
+jobs:
+  eventcatalog-breaking-changes:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: event-catalog/agents@main
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        with:
+          agent: breaking-changes
+          catalog-repo: your-org/your-catalog
+          catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
+```
+
+`fetch-depth: 0` is required so the agent can diff the pull request against its base.
+
+### 2. Add your model provider key
+
+Add the API key for your chosen model as a secret in your repository (**Settings → Secrets and variables → Actions**). Use the one that matches your model, for example `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`.
+
+You can see the list of [available models here](https://pi.dev/models).
+
+### 3. Open a pull request that changes a schema
+
+When a pull request changes a schema, the agent reviews the schema diff. If it finds a breaking change, it comments on the pull request with the affected EventCatalog consumers.
+
+## Configuration
+
+### Inputs
+
+| Input | Required | Default | Description |
+| --- | --- | --- | --- |
+| `agent` | No | `code-to-docs` | Set this to `breaking-changes` to run the Breaking Changes agent. |
+| `catalog-repo` | Yes | | The EventCatalog repository to inspect, in `owner/repo` format. |
+| `catalog-ref` | No | `main` | Branch checked out from the catalog repository. |
+| `catalog-token` | No | `github.token` | Token used to check out the catalog repository. Use a token with read access when the catalog is in another private repository. |
+| `model` | No | `anthropic/claude-sonnet-4-6` | Model specifier for the agent. See [available models](https://pi.dev/models). |
+| `ignore-paths` | No | common build/output paths | Comma-separated paths or glob patterns to ignore in pull request diffs. |
+| `schema-extensions` | No | `.json,.yml,.yaml,.avro,.avsc,.proto,.graphql,.gql` | Comma-separated file extensions the agent treats as message schemas. |
+
+### Schema extensions
+
+By default, the agent checks common schema files:
+
+```yaml
+schema-extensions: .json,.yml,.yaml,.avro,.avsc,.proto,.graphql,.gql
+```
+
+If your message contracts live in another file type, add that extension:
+
+```yaml
+- uses: event-catalog/agents@main
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  with:
+    agent: breaking-changes
+    catalog-repo: your-org/your-catalog
+    catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
+    schema-extensions: .json,.yaml,.ts
+```
+
+Only add source-code extensions when those files contain message contracts. The agent ignores non-schema files for this workflow.
+
+### Provider API keys
+
+The model provider's API key is passed as a normal workflow environment variable. Set the one that matches your `model`:
+
+| Provider | Environment variable |
+| --- | --- |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+
+The agent supports models from many providers. See the full list of model specifiers at [pi.dev/models](https://pi.dev/models).
+
+## Run with Code-to-Docs
+
+Each Action step runs one EventCatalog agent. To run Breaking Changes and [Code-to-Docs](/docs/development/ask-your-architecture/agents/code-to-docs) on the same pull request, add two steps:
+
+```yaml
+- uses: event-catalog/agents@main
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  with:
+    agent: breaking-changes
+    catalog-repo: your-org/your-catalog
+    catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
+
+- uses: event-catalog/agents@main
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  with:
+    agent: code-to-docs
+    catalog-repo: your-org/your-catalog
+    catalog-token: ${{ secrets.EVENTCATALOG_TOKEN }}
+```
+
+Use Breaking Changes when you want pull request feedback about schema compatibility. Use Code-to-Docs when you want catalog documentation updates proposed as a separate pull request.
+
+:::info Early access
+The Breaking Changes agent is in early access and free to evaluate. In the future, a license will be required to run EventCatalog Agents in production.
+:::
+
+## Found an issue or have feedback?
+
+The Breaking Changes agent is open on GitHub at [event-catalog/agents](https://github.com/event-catalog/agents). If you hit a problem, or the agent reports something in a way you didn't expect, [open an issue](https://github.com/event-catalog/agents/issues/new) and let us know. Your feedback during early access directly shapes how the agent works.
diff --git a/packages/core/docs/development/ask-your-architecture/04-agents/_category_.json b/packages/core/docs/development/ask-your-architecture/04-agents/_category_.json
new file mode 100644
index 000000000..e1b5e5679
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/04-agents/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Agents",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development/ask-your-architecture/agents",
+    "title": "EventCatalog Agents",
+    "description": "AI agents that help you manage and document your architecture with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/ask-your-architecture/05-skills/01-introduction.md b/packages/core/docs/development/ask-your-architecture/05-skills/01-introduction.md
new file mode 100644
index 000000000..0e8021752
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/05-skills/01-introduction.md
@@ -0,0 +1,40 @@
+---
+sidebar_position: 1
+keywords:
+- AI Skills
+- Claude Code
+- documentation generation
+sidebar_label: Introduction
+title: AI Skills
+description: Pre-built AI skills to help you document your architecture with EventCatalog
+---
+
+EventCatalog Skills are pre-built instructions that teach AI agents how to work with your EventCatalog project. Install a skill and your AI agent gains the ability to generate correct documentation, following EventCatalog conventions and best practices.
+
+Skills work with any AI coding agent that supports the skills format (e.g. [Claude Code](https://claude.ai/code)).
+
+## Why use skills?
+
+When you ask an AI agent to generate EventCatalog documentation, it doesn't know about EventCatalog's frontmatter format, folder structure, or component conventions. Skills solve this by providing the agent with structured instructions and reference material.
+
+With skills installed, you can ask your agent things like:
+
+- "Document my OrderService that receives OrderCreated events and sends OrderConfirmed events"
+- "Create a Payments domain with a PaymentService, PaymentProcessed event, and ProcessPayment command"
+- "Look at my src/ directory and generate EventCatalog documentation for the services and events you find"
+- "Document the checkout flow from cart submission through payment processing to order confirmation"
+
+The agent will generate properly formatted `index.mdx` files with correct frontmatter, schemas, and visualizations.
+
+## Available skills
+
+| Skill | Description |
+|-------|-------------|
+| [Catalog Documentation Creator](https://github.com/event-catalog/skills) | Generates EventCatalog documentation files (services, events, commands, queries, domains, flows, channels, containers) with correct frontmatter, folder structure, and best practices. |
+| [Flow Wizard](https://github.com/event-catalog/skills) | Guides you through documenting a business flow step by step in a conversational session, cross-referencing your existing catalog resources to link services, events, and commands automatically. |
+
+## Getting started
+
+Head to the [installation guide](/docs/development/ask-your-architecture/skills/installation) to add skills to your project.
+
+**Source code:** [github.com/event-catalog/skills](https://github.com/event-catalog/skills)
diff --git a/packages/core/docs/development/ask-your-architecture/05-skills/02-installation.md b/packages/core/docs/development/ask-your-architecture/05-skills/02-installation.md
new file mode 100644
index 000000000..0ee1016e0
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/05-skills/02-installation.md
@@ -0,0 +1,60 @@
+---
+sidebar_position: 2
+keywords:
+- AI Skills
+- installation
+sidebar_label: Installation
+title: Installing AI Skills
+description: How to install EventCatalog AI skills for your AI coding agent
+---
+
+## CLI install (recommended)
+
+Use [npx skills](https://github.com/vercel-labs/skills) to install skills directly into your project:
+
+```bash
+# Install all EventCatalog skills
+npx skills add event-catalog/skills
+
+# Install a specific skill
+npx skills add event-catalog/skills --skill catalog-documentation-creator
+```
+
+This copies the skill files into your project's `.claude/skills/` directory where your AI agent can access them.
+
+## Clone and copy
+
+Clone the repository and copy the skills you need:
+
+```bash
+git clone https://github.com/event-catalog/skills.git
+cp -r skills/skills/catalog-documentation-creator .claude/skills/
+```
+
+## Git submodule
+
+Add as a submodule for easy updates:
+
+```bash
+git submodule add https://github.com/event-catalog/skills.git .claude/skills/eventcatalog
+```
+
+When new skills are released, pull updates with:
+
+```bash
+git submodule update --remote
+```
+
+## Fork and customize
+
+Fork the repository and tailor skills to your team's conventions:
+
+1. Fork [event-catalog/skills](https://github.com/event-catalog/skills) on GitHub
+2. Modify skills to match your naming conventions, ownership patterns, and schema formats
+3. Install from your fork:
+
+```bash
+npx add-skill https://github.com/YOUR_ORG/eventcatalog-skills
+```
+
+This is useful when your team has specific conventions for IDs, owners, or folder structures that differ from the defaults.
diff --git a/packages/core/docs/development/ask-your-architecture/05-skills/_category_.json b/packages/core/docs/development/ask-your-architecture/05-skills/_category_.json
new file mode 100644
index 000000000..a10d5fa0c
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/05-skills/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Skills",
+  "position": 7,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development/ask-your-architecture/skills",
+    "description": "Pre-built AI skills for generating EventCatalog documentation"
+  }
+}
diff --git a/packages/core/docs/development/ask-your-architecture/06-slack-integration/01-introduction.md b/packages/core/docs/development/ask-your-architecture/06-slack-integration/01-introduction.md
new file mode 100644
index 000000000..b18559e25
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/06-slack-integration/01-introduction.md
@@ -0,0 +1,63 @@
+---
+sidebar_position: 1
+keywords:
+- Slack Bot
+- Slack Integration
+sidebar_label: Introduction
+title: Slack integration
+description: Query architecture documentation directly from Slack
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+The EventCatalog Slack Bot connects to your EventCatalog MCP server, allowing teams to query architecture documentation directly from Slack. Ask questions about events, services, domains, and schemas without leaving your workspace.
+
+The slack bot is self hosted, you own your data and deployment.
+
+<div className="flex justify-center items-center gap-4 flex-col">
+  <img src="/img/slack.png" alt="EventCatalog Slack Bot" className="rounded-lg" style={{ width: '30%', height: 'auto' }} />
+  <span className="text-center text-sm text-gray-500">Example of the EventCatalog Slack Bot in action asking about the OrderCreated event</span>
+</div>
+
+## How it works
+
+1. You configure the bot with your own AI provider and model (e.g. Anthropic, OpenAI, Google)
+1. Users @mention the bot or post in dedicated channels
+2. The bot queries your EventCatalog MCP server
+3. AI-powered responses appear in threads to keep channels organized
+
+## Key features
+
+- **@Mention anywhere** - Add the bot to any channel and ask questions
+- **Dedicated channels** - Create auto-reply channels for architecture questions
+- **Multiple AI providers** - Works with Anthropic, OpenAI, or Google
+- **Self-hosted** - Your data stays private, you control your data and deployment
+- **Socket Mode** - No public URL or webhooks needed
+- **Custom tools support** - Bring your own integrations for real-time data
+
+## Custom tools
+
+The Slack bot supports [custom tools](/docs/development/ask-your-architecture/eventcatalog-assistant/bring-your-own-tools) defined in your `eventcatalog.chat.js` file. This means you can bring real-time data into your Slack conversations:
+
+- Query production metrics from Datadog or Prometheus
+- Check service health and uptime
+- Look up on-call engineers from PagerDuty
+- Fetch queue depths from Kafka
+- Any custom integration your team needs
+
+Custom tools work automatically - the AI decides when to use them based on user questions. Ask "who is on-call for OrderService?" and get live data directly in Slack.
+
+## Prerequisites
+
+- EventCatalog instance (with configured MCP server) running in [SSR mode](/docs/development/deployment/build-ssr-mode)
+- [EventCatalog Scale license](https://eventcatalog.cloud)
+- Slack workspace with app creation permissions
+- API key for your chosen AI provider
+
+## Repository
+
+The EventCatalog Slack Bot is open source:
+
+[github.com/event-catalog/eventcatalog-slack-bot](https://github.com/event-catalog/eventcatalog-slack-bot)
diff --git a/packages/core/docs/development/ask-your-architecture/06-slack-integration/02-slack-app-setup.md b/packages/core/docs/development/ask-your-architecture/06-slack-integration/02-slack-app-setup.md
new file mode 100644
index 000000000..55da58d09
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/06-slack-integration/02-slack-app-setup.md
@@ -0,0 +1,154 @@
+---
+sidebar_position: 2
+keywords:
+- Slack Bot
+- Slack App
+sidebar_label: Slack app setup
+title: Slack app setup
+description: Create and configure your Slack app
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+Create a Slack app to enable the EventCatalog bot in your workspace. You can create the app using a manifest (recommended) or manually configure all settings.
+
+## Create from manifest (recommended)
+
+The fastest way to get started. The manifest automatically configures all required permissions and settings.
+
+### Steps
+
+1. Navigate to [api.slack.com/apps](https://api.slack.com/apps)
+2. Click **Create New App** → **From an app manifest**
+3. Select your workspace and click **Next**
+4. Choose **YAML** and paste this manifest:
+
+```yaml
+display_information:
+  name: EventCatalog Bot
+  description: Query your EventCatalog directly from Slack
+  background_color: "#000000"
+
+features:
+  bot_user:
+    display_name: EventCatalog
+    always_online: true
+
+oauth_config:
+  scopes:
+    bot:
+      - app_mentions:read
+      - chat:write
+      - reactions:read
+      - reactions:write
+      - channels:history
+
+settings:
+  event_subscriptions:
+    bot_events:
+      - app_mention
+      - message.channels
+  interactivity:
+    is_enabled: false
+  org_deploy_enabled: false
+  socket_mode_enabled: true
+  token_rotation_enabled: false
+```
+
+5. Click **Next**, review the summary, and click **Create**
+
+### Get credentials
+
+After creating the app, collect three credentials needed to run the bot.
+
+#### App-Level Token
+
+1. Go to **Basic Information** → **App-Level Tokens**
+2. Click **Generate Token and Scopes**
+3. Name: `socket-mode-token`
+4. Add scope: `connections:write`
+5. Click **Generate** and copy the token (starts with `xapp-`)
+6. Save this as `SLACK_APP_TOKEN`
+
+#### Bot Token
+
+1. Go to **OAuth & Permissions**
+2. Click **Install to Workspace**
+3. Review permissions and click **Allow**
+4. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
+5. Save this as `SLACK_BOT_TOKEN`
+
+#### Signing Secret
+
+1. Go to **Basic Information** → **App Credentials**
+2. Copy the **Signing Secret**
+3. Save this as `SLACK_SIGNING_SECRET`
+
+<details>
+<summary>Setup Slack app manually</summary>
+
+If you prefer to configure settings yourself, follow these steps.
+
+### Create the app
+
+1. Navigate to [api.slack.com/apps](https://api.slack.com/apps)
+2. Click **Create New App** → **From scratch**
+3. Name your app (e.g., "EventCatalog Bot") and select your workspace
+4. Click **Create App**
+
+### Enable Socket Mode
+
+1. Click **Socket Mode** in the left sidebar
+2. Toggle **Enable Socket Mode** to On
+3. Create an App-Level Token when prompted:
+   - Name: `socket-mode-token`
+   - Scope: `connections:write`
+4. Click **Generate**
+5. Copy the token (starts with `xapp-`) - this is `SLACK_APP_TOKEN`
+
+### Configure permissions
+
+1. Click **OAuth & Permissions** in the left sidebar
+2. Scroll to **Scopes** → **Bot Token Scopes**
+3. Add these scopes:
+   - `app_mentions:read` - Receive @mention events
+   - `chat:write` - Send messages
+   - `reactions:read` - Read reactions
+   - `reactions:write` - Add and remove reactions
+   - `channels:history` - Read public channel messages
+
+### Enable events
+
+1. Click **Event Subscriptions** in the left sidebar
+2. Toggle **Enable Events** to On
+3. Expand **Subscribe to bot events**
+4. Add these events:
+   - `app_mention`
+   - `message.channels`
+
+### Install the app
+
+1. Click **OAuth & Permissions** in the left sidebar
+2. Click **Install to Workspace**
+3. Review permissions and click **Allow**
+4. Copy the **Bot User OAuth Token** (starts with `xoxb-`) - this is `SLACK_BOT_TOKEN`
+
+### Get signing secret
+
+1. Click **Basic Information** in the left sidebar
+2. Scroll to **App Credentials**
+3. Copy the **Signing Secret** - this is `SLACK_SIGNING_SECRET`
+
+</details>
+
+## Optional: Private channels and DMs
+
+By default, the bot only reads thread context in public channels. To enable thread context in private channels and DMs, add these additional scopes:
+
+- `groups:history` - Private channels
+- `im:history` - Direct messages
+- `mpim:history` - Group DMs
+
+After adding scopes, reinstall the app to your workspace.
diff --git a/packages/core/docs/development/ask-your-architecture/06-slack-integration/03-installation.md b/packages/core/docs/development/ask-your-architecture/06-slack-integration/03-installation.md
new file mode 100644
index 000000000..2d957395a
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/06-slack-integration/03-installation.md
@@ -0,0 +1,169 @@
+---
+sidebar_position: 3
+keywords:
+- Slack Bot
+- Installation
+sidebar_label: Installation
+title: Installation
+description: Install and configure the bot
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PlanBanner plan="Scale" />
+
+Install the EventCatalog Slack Bot locally or deploy it to your infrastructure. The bot runs as a long-lived process that maintains a connection to Slack.
+
+## Install locally
+
+### Clone repository
+
+```bash
+git clone https://github.com/event-catalog/eventcatalog-slack-bot.git
+cd eventcatalog-slack-bot
+```
+
+### Install dependencies
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+    ```bash
+    npm install
+    ```
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+    ```bash
+    pnpm install
+    ```
+  </TabItem>
+</Tabs>
+
+### Configure environment
+
+Create a `.env` file with your credentials:
+
+```bash
+# EventCatalog Scale License (Required)
+EVENTCATALOG_SCALE_LICENSE_KEY=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
+
+# Slack Credentials (Required)
+SLACK_BOT_TOKEN=xoxb-...
+SLACK_APP_TOKEN=xapp-...
+SLACK_SIGNING_SECRET=...
+
+# AI Provider (at least one required)
+ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# GOOGLE_GENERATIVE_AI_API_KEY=...
+```
+
+### Create configuration
+
+Create `eventcatalog-bot.config.ts`:
+
+```typescript
+export default {
+  eventCatalog: {
+    url: 'http://localhost:3000',
+    // Optional: Add authentication headers
+    // headers: {
+    //   'Authorization': 'Bearer your-token',
+    // },
+  },
+  ai: {
+    provider: 'anthropic', // 'anthropic' | 'openai' | 'google'
+    // model: 'claude-sonnet-4-20250514', // Optional: override default model
+    maxSteps: 5,
+    temperature: 0.4,
+  },
+  slack: {
+    // Optional: Channel IDs for auto-reply (bot responds to all messages)
+    autoReplyChannels: [],
+    // Optional: Custom icon URL for bot messages
+    icon: 'https://www.eventcatalog.dev/img/logo.png',
+    // Optional: Custom username for bot messages
+    username: 'EventCatalog',
+  },
+};
+```
+
+### Start the bot
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+    ```bash
+    npm run dev
+    ```
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+    ```bash
+    pnpm dev
+    ```
+  </TabItem>
+</Tabs>
+
+Or with a custom config path:
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+    ```bash
+    npm run dev -- --config ./my-config.ts
+    ```
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+    ```bash
+    pnpm dev --config ./my-config.ts
+    ```
+  </TabItem>
+</Tabs>
+
+## Configuration reference
+
+### eventCatalog
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `url` | string | Yes | URL of your EventCatalog instance |
+| `headers` | object | No | Authentication headers if needed |
+
+### ai
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `provider` | string | Required | AI provider: `anthropic`, `openai`, or `google` |
+| `model` | string | Provider default | Model to use (see [supported models](#supported-ai-providers)) |
+| `maxSteps` | number | 5 | Maximum tool-calling steps (1-20) |
+| `temperature` | number | 0.4 | AI temperature (0-2) |
+
+### slack
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `autoReplyChannels` | string[] | [] | Channel IDs where bot auto-replies to all messages |
+| `icon` | string | EventCatalog logo | Custom icon URL for bot messages |
+| `username` | string | 'EventCatalog' | Custom display name for bot messages |
+
+## Supported AI providers
+
+| Provider | Environment Variable | Default Model |
+|----------|---------------------|---------------|
+| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+| OpenAI | `OPENAI_API_KEY` | `gpt-4o` |
+| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | `gemini-2.0-flash` |
+
+You can override the default model in your configuration. For a full list of available models, see the [Vercel AI SDK Providers documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
+
+```typescript
+ai: {
+  provider: 'anthropic',
+  model: 'claude-opus-4-20250514', // Use a different model
+}
+```
+
+## License key
+
+Get your EventCatalog Scale license key from [eventcatalog.cloud](https://eventcatalog.cloud). A 30-day free trial is available.
+
+The license key must be set as the `EVENTCATALOG_SCALE_LICENSE_KEY` environment variable.
diff --git a/packages/core/docs/development/ask-your-architecture/06-slack-integration/04-deployment.md b/packages/core/docs/development/ask-your-architecture/06-slack-integration/04-deployment.md
new file mode 100644
index 000000000..1a7862f14
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/06-slack-integration/04-deployment.md
@@ -0,0 +1,236 @@
+---
+sidebar_position: 4
+keywords:
+- Slack Bot
+- Deployment
+- Docker
+sidebar_label: Deployment
+title: Deployment
+description: Deploy the bot to production
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PlanBanner plan="Scale" />
+
+Deploy the EventCatalog Slack Bot to your infrastructure. The bot uses Socket Mode, so it maintains an outbound connection to Slack without requiring a public URL, load balancer, or SSL certificates.
+
+## Docker
+
+The simplest way to deploy is using Docker. The bot includes a Dockerfile and docker-compose configuration.
+
+### Build the image
+
+```bash
+docker build -t eventcatalog-slack-bot .
+```
+
+### Run with docker-compose
+
+```bash
+docker compose up -d
+```
+
+### View logs
+
+```bash
+docker compose logs -f
+```
+
+The `docker-compose.yml` file mounts your config and reads environment variables from `.env`:
+
+```yaml
+services:
+  eventcatalog-slack-bot:
+    build: .
+    container_name: eventcatalog-slack-bot
+    restart: unless-stopped
+    env_file:
+      - .env
+    volumes:
+      - ./eventcatalog-bot.config.ts:/app/eventcatalog-bot.config.ts:ro
+    environment:
+      - NODE_ENV=production
+```
+
+## Docker networking
+
+When running the bot in Docker, the container needs network access to your EventCatalog server. Configuration depends on where EventCatalog runs.
+
+### EventCatalog on localhost
+
+Docker containers cannot use `localhost` to reach the host machine. Use one of these approaches:
+
+**Option 1: Use host.docker.internal (recommended)**
+
+Update your config to use the special Docker hostname:
+
+```typescript
+eventCatalog: {
+  url: 'http://host.docker.internal:3000',
+}
+```
+
+:::info
+Your EventCatalog server must bind to all interfaces (`0.0.0.0`), not just `localhost`. Check your EventCatalog startup logs. If it shows `localhost:3000`, you may need to start it with a `--host 0.0.0.0` flag.
+:::
+
+**Option 2: Run the bot outside Docker**
+
+For local development, skip Docker and run the bot directly:
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+    ```bash
+    npm install
+    npm run dev
+    ```
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+    ```bash
+    pnpm install
+    pnpm dev
+    ```
+  </TabItem>
+</Tabs>
+
+This avoids networking complexity during development.
+
+### EventCatalog in Docker
+
+Put both containers on the same Docker network and use the container name as hostname:
+
+```yaml
+services:
+  eventcatalog:
+    # your EventCatalog config
+    networks:
+      - app-network
+
+  eventcatalog-slack-bot:
+    build: .
+    env_file:
+      - .env
+    volumes:
+      - ./eventcatalog-bot.config.ts:/app/eventcatalog-bot.config.ts:ro
+    networks:
+      - app-network
+
+networks:
+  app-network:
+```
+
+Configure the bot to use the container name:
+
+```typescript
+eventCatalog: {
+  url: 'http://eventcatalog:3000',
+}
+```
+
+### EventCatalog at public URL
+
+Use the public URL directly - no special configuration needed:
+
+```typescript
+eventCatalog: {
+  url: 'https://your-catalog.example.com',
+}
+```
+
+## Other deployment options
+
+<details>
+<summary>Railway</summary>
+
+Railway automatically detects the Dockerfile and deploys the bot.
+
+1. Create a new project and connect your repository
+2. Add environment variables in the Railway dashboard:
+   - `EVENTCATALOG_SCALE_LICENSE_KEY`
+   - `SLACK_BOT_TOKEN`
+   - `SLACK_APP_TOKEN`
+   - `SLACK_SIGNING_SECRET`
+   - `ANTHROPIC_API_KEY` (or your chosen provider)
+3. Add your `eventcatalog-bot.config.ts` to the repository
+4. Deploy - Railway detects the Dockerfile automatically
+
+</details>
+
+<details>
+<summary>Fly.io</summary>
+
+Deploy to Fly.io using their CLI.
+
+**Initialize:**
+
+```bash
+fly launch --no-deploy
+```
+
+**Set secrets:**
+
+```bash
+fly secrets set EVENTCATALOG_SCALE_LICENSE_KEY=your-key
+fly secrets set SLACK_BOT_TOKEN=xoxb-...
+fly secrets set SLACK_APP_TOKEN=xapp-...
+fly secrets set SLACK_SIGNING_SECRET=...
+fly secrets set ANTHROPIC_API_KEY=sk-ant-...
+```
+
+**Deploy:**
+
+```bash
+fly deploy
+```
+
+</details>
+
+<details>
+<summary>Render</summary>
+
+Deploy as a Background Worker on Render.
+
+1. Create a new **Background Worker** (not a Web Service)
+2. Connect your repository
+3. Set the build and start commands:
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+    - Build command: `npm install && npm run build`
+    - Start command: `npm start`
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+    - Build command: `pnpm install && pnpm build`
+    - Start command: `pnpm start`
+  </TabItem>
+</Tabs>
+
+4. Add environment variables in the Render dashboard
+5. Deploy
+
+</details>
+
+<details>
+<summary>AWS, GCP, or Azure</summary>
+
+Deploy as a container or long-running process. The bot requires:
+
+- Outbound HTTPS/WSS connections to Slack
+- No inbound connections (Socket Mode handles communication)
+- No load balancers or public endpoints needed
+
+Suitable services include:
+
+- **AWS:** ECS, EKS, EC2
+- **GCP:** Cloud Run (always running), GKE, Compute Engine
+- **Azure:** Container Instances, AKS, Virtual Machines
+
+Ensure the process stays running and can make outbound connections to:
+- `slack.com` (Socket Mode connection)
+- Your EventCatalog instance
+- Your AI provider API
+
+</details>
diff --git a/packages/core/docs/development/ask-your-architecture/06-slack-integration/05-usage.md b/packages/core/docs/development/ask-your-architecture/06-slack-integration/05-usage.md
new file mode 100644
index 000000000..aa350f349
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/06-slack-integration/05-usage.md
@@ -0,0 +1,140 @@
+---
+sidebar_position: 5
+keywords:
+- Slack Bot
+- Usage
+sidebar_label: Using the bot
+title: Using the bot
+description: Query architecture documentation from Slack
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+Interact with the EventCatalog Slack Bot to query your architecture documentation. The bot responds to @mentions and can auto-reply in dedicated channels.
+
+## @Mention in any channel
+
+Invite the bot to any channel and @mention it to ask questions. The bot replies in a thread to keep channels organized.
+
+### Example questions
+
+```
+@eventcatalog Tell me about the OrderCreated event
+```
+
+```
+@eventcatalog What services consume the InventoryUpdated event?
+```
+
+```
+@eventcatalog List all events in the Orders domain
+```
+
+```
+@eventcatalog Show me the schema for the PaymentProcessed event
+```
+
+The bot reads your EventCatalog documentation and provides detailed answers grounded in your architecture.
+
+## Dedicated auto-reply channels
+
+Create a channel where the bot automatically responds to every message - no @mention needed. This gives your team a dedicated space for architecture questions.
+
+### Setup
+
+1. Create a new channel (e.g., `#ask-eventcatalog` or `#ask-eda`)
+2. Invite the bot to the channel
+3. Get the channel ID:
+   - Right-click the channel name
+   - Click **View channel details**
+   - Scroll to the bottom to find the Channel ID
+4. Add the channel ID to your config:
+
+```typescript
+slack: {
+  autoReplyChannels: ['C0123456789'],
+}
+```
+
+5. Restart the bot
+
+Now anyone can post questions directly in the channel and receive instant answers.
+
+### Multiple channels
+
+Configure multiple auto-reply channels:
+
+```typescript
+slack: {
+  autoReplyChannels: ['C0123456789', 'C9876543210'],
+}
+```
+
+## Thread context
+
+The bot automatically reads conversation history in threads. This enables natural follow-up questions without repeating context.
+
+### Example conversation
+
+**User:** Tell me about the OrderCreated event
+
+**Bot:** The OrderCreated event is published when...
+
+**User:** What are its consumers?
+
+**Bot:** Based on our earlier discussion about OrderCreated, the consumers are...
+
+**User:** Show me the schema
+
+**Bot:** Here's the schema for OrderCreated...
+
+Thread context works automatically in public channels. For private channels and DMs, add optional scopes to your Slack app:
+
+- `groups:history` - Private channels
+- `im:history` - Direct messages
+- `mpim:history` - Group DMs
+
+After adding scopes, reinstall the app to your workspace.
+
+## Best practices
+
+### Ask specific questions
+
+The bot performs best with clear, specific questions:
+
+**Good:**
+- "What services consume the OrderCreated event?"
+- "Show me all events in the Payment domain"
+- "What's the schema format for UserRegistered?"
+
+**Less effective:**
+- "Tell me about everything"
+- "What does this system do?"
+
+### Use thread conversations
+
+Keep related questions in the same thread. The bot uses thread history to provide better context-aware answers.
+
+### Name resources clearly
+
+Mention specific event names, service names, or domain names to get precise answers:
+
+- "Tell me about the **OrderCreated** event"
+- "What events does the **PaymentService** produce?"
+- "List all events in the **Orders** domain"
+
+## Invite the bot to channels
+
+The bot can only see messages in channels where it's invited.
+
+### Invite the bot
+
+1. Navigate to the channel
+2. Click the channel name at the top
+3. Click the **Integrations** tab
+4. Click **Add an app**
+5. Search for your bot and add it
+
+Alternatively, type `/invite @eventcatalog` in the channel.
diff --git a/packages/core/docs/development/ask-your-architecture/06-slack-integration/06-troubleshooting.md b/packages/core/docs/development/ask-your-architecture/06-slack-integration/06-troubleshooting.md
new file mode 100644
index 000000000..5860d2d36
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/06-slack-integration/06-troubleshooting.md
@@ -0,0 +1,268 @@
+---
+sidebar_position: 6
+keywords:
+- Slack Bot
+- Troubleshooting
+sidebar_label: Troubleshooting
+title: Troubleshooting
+description: Common issues and solutions
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+Common issues and solutions for the EventCatalog Slack Bot.
+
+## Bot doesn't respond
+
+### Check bot invitation
+
+The bot must be invited to the channel where you're trying to use it.
+
+**Solution:**
+1. Navigate to the channel
+2. Type `/invite @eventcatalog` (use your bot's actual name)
+3. Try your question again
+
+### Verify Socket Mode
+
+Socket Mode must be enabled in your Slack app settings.
+
+**Solution:**
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Select your app
+3. Click **Socket Mode** in the sidebar
+4. Verify it's toggled to **On**
+5. Restart the bot
+
+### Check bot logs
+
+Look for connection errors or startup issues.
+
+**Solution:**
+
+View logs based on how you're running the bot:
+
+```bash
+# Local development
+# Check terminal output
+
+# Docker
+docker compose logs -f
+
+# Docker (specific container)
+docker logs eventcatalog-slack-bot
+```
+
+Look for error messages about:
+- Missing credentials
+- Connection failures
+- License validation issues
+
+## Missing API key error
+
+The bot cannot find the API key for your configured AI provider.
+
+**Solution:**
+
+1. Check your `.env` file contains the correct variable:
+
+```bash
+# For Anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+
+# For OpenAI
+OPENAI_API_KEY=sk-...
+
+# For Google
+GOOGLE_GENERATIVE_AI_API_KEY=...
+```
+
+2. Verify your config matches the environment variable:
+
+```typescript
+ai: {
+  provider: 'anthropic', // Must match your API key
+}
+```
+
+3. Restart the bot after adding the key
+
+## MCP connection errors
+
+The bot cannot connect to your EventCatalog MCP server.
+
+### Verify EventCatalog URL
+
+**Solution:**
+
+1. Check your config has the correct URL:
+
+```typescript
+eventCatalog: {
+  url: 'https://your-catalog.example.com',
+}
+```
+
+2. Verify the URL is accessible from where the bot runs:
+
+```bash
+curl https://your-catalog.example.com/docs/mcp/
+```
+
+3. For Docker deployments, see [Docker networking](/docs/development/ask-your-architecture/slack-integration/deployment#docker-networking)
+
+### Check MCP server status
+
+**Solution:**
+
+1. Visit your MCP endpoint in a browser:
+
+```
+https://your-catalog.example.com/docs/mcp/
+```
+
+2. You should see JSON output with available tools and resources
+3. If you see an error, verify:
+   - EventCatalog is running in [SSR mode](/docs/development/deployment/build-ssr-mode)
+   - You have a valid [Scale license](https://eventcatalog.cloud)
+
+### Authentication required
+
+If your EventCatalog requires authentication, add headers to your config.
+
+**Solution:**
+
+```typescript
+eventCatalog: {
+  url: 'https://your-catalog.example.com',
+  headers: {
+    'Authorization': 'Bearer your-token',
+  },
+}
+```
+
+## Permission errors
+
+The bot is missing required Slack permissions.
+
+**Solution:**
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Select your app
+3. Click **OAuth & Permissions**
+4. Verify these **Bot Token Scopes** are added:
+   - `app_mentions:read`
+   - `chat:write`
+   - `reactions:read`
+   - `reactions:write`
+   - `channels:history`
+5. If you added new scopes, click **Reinstall to Workspace**
+6. Restart the bot
+
+## Auto-reply channels not working
+
+The bot doesn't auto-reply in configured channels.
+
+### Verify channel ID
+
+**Solution:**
+
+1. Get the correct channel ID:
+   - Right-click channel name
+   - Click **View channel details**
+   - Scroll to bottom for Channel ID
+2. Check your config uses the ID (not name):
+
+```typescript
+slack: {
+  autoReplyChannels: ['C0123456789'], // Channel ID, not #channel-name
+}
+```
+
+3. Restart the bot after changing config
+
+### Check event subscription
+
+**Solution:**
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Select your app
+3. Click **Event Subscriptions**
+4. Verify **Enable Events** is On
+5. Check `message.channels` is in **Subscribe to bot events**
+
+## Thread context not working
+
+The bot doesn't remember previous messages in a thread.
+
+### Public channels
+
+Thread context should work automatically in public channels.
+
+**Solution:**
+
+1. Verify `channels:history` scope is added
+2. Reinstall the app if you just added the scope
+3. Restart the bot
+
+### Private channels and DMs
+
+Thread context requires additional scopes.
+
+**Solution:**
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Select your app
+3. Click **OAuth & Permissions**
+4. Add these scopes:
+   - `groups:history` - Private channels
+   - `im:history` - Direct messages
+   - `mpim:history` - Group DMs
+5. Click **Reinstall to Workspace**
+6. Restart the bot
+
+## Docker networking issues
+
+The bot cannot reach EventCatalog running on localhost.
+
+**Solution:**
+
+See the [Docker networking guide](/docs/development/ask-your-architecture/slack-integration/deployment#docker-networking) for detailed solutions based on your setup.
+
+Quick fix for local EventCatalog:
+
+```typescript
+eventCatalog: {
+  url: 'http://host.docker.internal:3000',
+}
+```
+
+## License validation errors
+
+The bot reports an invalid or expired license.
+
+**Solution:**
+
+1. Verify your license key is correct in `.env`:
+
+```bash
+EVENTCATALOG_SCALE_LICENSE_KEY=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
+```
+
+2. Check your license status at [eventcatalog.cloud](https://eventcatalog.cloud)
+3. For expired trials, upgrade to a paid plan
+4. Restart the bot after updating the key
+
+## Getting help
+
+If you're still experiencing issues:
+
+1. Check the bot logs for detailed error messages
+2. Review the [GitHub repository](https://github.com/event-catalog/eventcatalog-slack-bot) for known issues
+3. Join the [EventCatalog Discord](https://eventcatalog.dev/discord) for community support
+4. File an issue on [GitHub](https://github.com/event-catalog/eventcatalog-slack-bot/issues) with:
+   - Bot version
+   - Error messages from logs
+   - Steps to reproduce the issue
diff --git a/packages/core/docs/development/ask-your-architecture/06-slack-integration/_category_.json b/packages/core/docs/development/ask-your-architecture/06-slack-integration/_category_.json
new file mode 100644
index 000000000..73bcd92c9
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/06-slack-integration/_category_.json
@@ -0,0 +1,13 @@
+{
+  "label": "Slack Integration",
+  "position": 8,
+  "className": "hidden",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/ask-your-architecture/slack-integration",
+    "title": "Slack Integration",
+    "description": "Query your EventCatalog directly from Slack using the EventCatalog Slack Bot."
+  }
+}
diff --git a/packages/core/docs/development/ask-your-architecture/_category_.json b/packages/core/docs/development/ask-your-architecture/_category_.json
new file mode 100644
index 000000000..5753d6240
--- /dev/null
+++ b/packages/core/docs/development/ask-your-architecture/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "AI with EventCatalog",
+  "position": 6,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "ask-your-architecture",
+    "title": "Ask your architecture",
+    "description": "Learn how to integrate your LLM models with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/authentication/01-introduction.md b/packages/core/docs/development/authentication/01-introduction.md
new file mode 100644
index 000000000..c11d040ad
--- /dev/null
+++ b/packages/core/docs/development/authentication/01-introduction.md
@@ -0,0 +1,78 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog components
+sidebar_label: Introduction
+title: Introduction
+description: Introduction to EventCatalog Authentication
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+# Authentication Guide
+
+<PlanBanner plan="Scale" />
+<AddedIn version="2.43.0" />
+
+
+EventCatalog provides secure authentication to control access to your event-driven architecture documentation. Whether you're a small team getting started or a large enterprise with complex identity requirements, EventCatalog's flexible authentication system grows with your needs.
+
+<iframe width="100%" height="455" src="https://www.youtube.com/embed/OVbXNP0Ns_U?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>
+
+
+
+
+## How it works
+
+EventCatalog uses industry-standard **OpenID Connect (OIDC)** and **OAuth 2.0** protocols to integrate with your identity provider. Here's the authentication flow:
+
+1. **User visits EventCatalog** and attempts to access protected documentation
+2. **Redirected to your identity provider** (GitHub, Google, Auth0, etc.)
+3. **User authenticates** with their existing credentials
+4. **Provider confirms identity** and sends user back to EventCatalog
+5. **User gains access** to your documentation and architecture
+
+![Authentication](./img/auth.png)
+
+EventCatalog runs in **SSR mode** to handle authentication sessions and uses [Auth.js](https://authjs.dev/) to manage the authentication flow securely.
+
+## Authentication by Plan
+
+EventCatalog Authentication is a **paid feature** available in Scale and Enterprise plans.
+
+#### Scale Plan
+Perfect for growing teams that need secure collaboration with popular business providers:
+
+- **GitHub** - Ideal for development teams already using GitHub
+<!-- - **Google** - For teams using Gmail and Google Workspace -->
+
+#### Enterprise Plan
+Designed for large organizations with dedicated identity management systems:
+
+- **Microsoft Azure AD (Entra ID)** - For organizations using Office 365 and Azure
+- **Auth0** - Developer-friendly identity platform with advanced features
+- **Okta** - Popular enterprise identity platform with custom claims
+- **Custom OIDC** - Contact us to add your provider at [hello@eventcatalog.cloud](mailto:hello@eventcatalog.cloud)
+
+## Why EventCatalog Authentication?
+
+- ✅ **No new passwords** - Users authenticate with accounts they already have
+- ✅ **Secure by default** - Leverage enterprise-grade security from major providers
+- ✅ **Single sign-on experience** - Seamless access across your tools
+- ✅ **Centralized management** - Control access through your existing identity systems
+- ✅ **Team collaboration** - Secure access for distributed teams
+
+## Getting Started
+
+Ready to secure your EventCatalog with authentication?
+
+**New to EventCatalog?** Start your **30-day free trial** at [EventCatalog.cloud](https://eventcatalog.cloud) to explore all authentication features.
+
+## Next steps
+
+Ready to get started? Let's enable authentication in your EventCatalog project:
+
+→ [Enabling Authentication](/docs/development/authentication/enabling-authentication)
+
+**Questions?** Join our [Discord community](https://discord.gg/eventcatalog) for support and guidance.
\ No newline at end of file
diff --git a/packages/core/docs/development/authentication/02-enabling-authentication.md b/packages/core/docs/development/authentication/02-enabling-authentication.md
new file mode 100644
index 000000000..5023b7c1b
--- /dev/null
+++ b/packages/core/docs/development/authentication/02-enabling-authentication.md
@@ -0,0 +1,152 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog authentication
+sidebar_label: Enabling authentication
+title: Enabling authentication
+description: Enabling authentication for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import { Card, CardGrid, GitHubIcon, OktaIcon, AzureIcon, GoogleIcon, Auth0Icon, GitLabIcon } from '@site/src/components/MDX/Card';
+
+<AddedIn version="2.43.0" />
+<PlanBanner plan="Scale" />
+
+To enable authentication for your site, you will need to do three things:
+
+1. [Setup Environment](#setup-environment)
+1. [Enable EventCatalog Server Side Rendering (SSR)](#enable-eventcatalog-server-side-rendering-ssr)
+1. [Create your `eventcatalog.auth.js` file](#create-your-eventcatalogauthjs-file)
+
+:::info Authentication is a paid feature
+Authentication is a paid feature, and is available on EventCatalog Scale and Enterprise plans.
+
+You can get a 30-day free trial of EventCatalog Scale and Enterprise [here](https://www.eventcatalog.dev/pricing).
+
+You will need to set your license key in your `.env` file.
+
+```env title=".env"
+EVENTCATALOG_LICENSE_KEY=your-license-key
+```
+:::
+
+### Setup Environment
+
+EventCatalog uses [Auth.js](https://authjs.dev/) to handle the authentication flow.
+
+Auth.js libraries require you to set an `AUTH_SECRET` environment variable. This is used to encrypt cookies and tokens. It should be a cryptographically secure random string of at least 32 characters:
+
+This is the only strictly required environment variable. It is the secret used to encode the JWT and encrypt things in transit. We recommend at least a 32 character random string. This can be generated via openssl with `openssl rand -base64 33`.
+
+```env title=".env"
+AUTH_SECRET=your-secret
+```
+
+#### AUTH_TRUST_HOST {#auth_trust_host}
+
+When running EventCatalog behind a reverse proxy (Kubernetes/AKS, Nginx, Cloudflare, AWS ALB, etc.), you must set `AUTH_TRUST_HOST=true`. Without it, Auth.js falls back to the internal container URL (e.g. `http://localhost:3000`) instead of the real domain, which causes login and sign-out to fail with CSRF/cross-site errors such as "Cross-site POST form submissions are forbidden".
+
+```env title=".env"
+AUTH_TRUST_HOST=true
+```
+
+Setting this tells Auth.js to trust the `x-forwarded-host` and `x-forwarded-proto` headers forwarded by your proxy so it can resolve the correct callback URL.
+
+:::tip Vercel and Cloudflare Pages
+You do not need to set `AUTH_TRUST_HOST` when deploying to Vercel or Cloudflare Pages - it is inferred automatically. It is also not required in local development.
+:::
+
+To learn more, refer to the [Auth.js deployment documentation](https://authjs.dev/getting-started/deployment#auth_trust_host).
+
+
+### Enable EventCatalog Server Side Rendering (SSR)
+
+Authentication requires EventCatalog to be SSR enabled. This is because EventCatalog needs to be able to access the user's session to determine if they are authenticated.
+
+To enable SSR, you will need to add the following to your `eventcatalog.config.js` file:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  // ... other config options
+  output: 'server',
+};
+```
+
+This will ensure that EventCatalog is rendered on the server side, and that the user's session is available to the client.
+
+:::info Deploying EventCatalog in SSR mode
+You will be running EventCatalog in SSR mode when you deploy your site. This means the output of your site will require a server to be running. You can use EventCatalog Docker file to deploy your site or read our [deployment guide](https://www.eventcatalog.dev/docs/deployment/overview) for more information.
+:::
+
+### Create your `eventcatalog.auth.js` file
+
+The `eventcatalog.auth.js` file is used to configure the authentication for your site, and is created in the root of your EventCatalog project.
+
+```js title="eventcatalog.auth.js"
+module.exports = {
+  // Enable debug mode for development
+  debug: false,
+  // List of providers you want to enable
+  providers: {
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+    },
+  },
+  // Optional session configuration
+  session?: {
+    // 30 days default
+    maxAge?: number;
+  };
+};
+```
+
+Once you have these three things, you can start setting up your authentication providers.
+
+### Setting up your authentication providers
+
+EventCatalog supports a range of authentication providers, and you can find the documentation for each provider below.
+
+<CardGrid columns={2}>
+  <Card
+    title="Setting up GitHub"
+    icon={<GitHubIcon />}
+    badge="Scale"
+    href="/docs/development/authentication/providers/setting-up-github"
+  />
+  <Card
+    title="Setting up Google"
+    icon={<GoogleIcon />}
+    badge="Scale"
+    href="/docs/development/authentication/providers/setting-up-google"
+  />
+  <Card
+    title="Setting up Azure AD"
+    icon={<AzureIcon />}
+    badge="Enterprise"
+    href="/docs/development/authentication/providers/setting-up-azure-ad"
+  />
+  <!-- <Card
+    title="Setting up Google"
+    icon={<GoogleIcon />}
+    href="/docs/auth/google"
+  /> -->
+  
+  <Card
+    title="Setting up Okta"
+    icon={<OktaIcon />}
+    href="/docs/development/authentication/providers/setting-up-okta"
+    badge="Enterprise"
+  />
+  <Card
+    title="Setting up Auth0"
+    icon={<Auth0Icon />}
+    href="/docs/development/authentication/providers/setting-up-auth0"
+    badge="Enterprise"
+  />
+</CardGrid>
+
+Missing a provider? [Let us know](https://github.com/event-catalog/eventcatalog/issues/new) and we'll add it to the list.
+
diff --git a/packages/core/docs/development/authentication/07-rbac-middleware.md b/packages/core/docs/development/authentication/07-rbac-middleware.md
new file mode 100644
index 000000000..ce8e99c46
--- /dev/null
+++ b/packages/core/docs/development/authentication/07-rbac-middleware.md
@@ -0,0 +1,269 @@
+---
+sidebar_position: 7
+keywords:
+- EventCatalog RBAC
+- Role-based access control
+- Middleware
+- Custom authentication
+- Access control
+sidebar_label: Role-Based Access Control
+title: RBAC Middleware
+description: Implementing role-based access control with custom middleware in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="2.44.0" />
+<PlanBanner plan="Enterprise" />
+
+# Role-Based Access Control (RBAC) Middleware
+
+EventCatalog supports **Role-Based Access Control (RBAC)** through custom middleware, allowing you to control user access to specific pages and sections based on their roles and groups.
+
+## How it works
+
+The RBAC middleware integrates with EventCatalog's authentication system to provide fine-grained access control:
+
+1. **User authenticates** through your configured identity provider
+2. **Middleware evaluates** the user's roles and groups against defined access rules
+3. **Access is granted or denied** based on the matching rules for the requested path
+4. **User sees appropriate content** or receives a 403 Forbidden response
+
+## Prerequisites
+
+Before setting up RBAC middleware, ensure you have:
+
+- ✅ [Authentication enabled](/docs/development/authentication/enabling-authentication) in your EventCatalog
+- ✅ An authentication provider configured (GitHub, Google, Azure AD, etc.)
+- ✅ User roles and groups configured in your identity provider
+
+## Setting up RBAC Middleware
+
+### 1. Create the middleware file
+
+Create a `middleware.ts` file in the root of your EventCatalog project:
+
+```typescript title="middleware.ts"
+import type { MiddlewareHandler } from 'astro';
+
+interface Locals {
+  hasRole: (role: string) => boolean;
+  hasGroup: (group: string) => boolean;
+  findMatchingRule: (rules: Record<string, () => boolean>, pathname: string) => (() => boolean) | null;
+}
+
+export const rbacMiddleware: MiddlewareHandler = async (context, next) => {
+  const { locals, url } = context;
+  const pathname = url.pathname;
+
+  // Utility functions are available in the locals object
+  const { hasRole, hasGroup, findMatchingRule } = locals as Locals;
+
+  // Define your access rules
+  // Maps page routes to a function that returns true if the user has access, false otherwise
+  // You can use wildcards to match multiple paths
+  const accessRules = {
+    '/docs/domains/E-Commerce/*': () => !hasGroup('Viewer'),
+    '/visualiser/domains/E-Commerce/*': () => !hasGroup('Viewer'),
+    '/docs/services/payment/*': () => hasRole('Developer') || hasRole('Admin'),
+    '/admin/*': () => hasRole('Admin'),
+  };
+
+  if (findMatchingRule) {
+    // Find matching rule for the current path
+    const rule = findMatchingRule(accessRules, pathname);
+
+    if (rule && !rule()) {
+      return new Response('Forbidden', { status: 403 });
+    }
+  }
+
+  return next();
+};
+```
+
+### 2. Configure your access rules
+
+The `accessRules` object defines path-based access control:
+
+```typescript
+const accessRules = {
+  // Block 'Viewer' group from E-Commerce domain docs
+  '/docs/domains/E-Commerce/*': () => !hasGroup('Viewer'),
+  
+  // Require 'Developer' or 'Admin' role for payment services
+  '/docs/services/payment/*': () => hasRole('Developer') || hasRole('Admin'),
+  
+  // Admin-only sections
+  '/admin/*': () => hasRole('Admin'),
+  
+  // Multiple conditions
+  '/docs/sensitive/*': () => hasRole('Admin') && !hasGroup('External'),
+};
+```
+
+### 3. Available helper functions
+
+The middleware provides several helper functions through `locals`:
+
+#### `hasRole(role: string)`
+Checks if the user has a specific role:
+```typescript
+hasRole('Admin')        // Returns true if user has Admin role
+hasRole('Developer')    // Returns true if user has Developer role
+```
+
+#### `hasGroup(group: string)`
+Checks if the user belongs to a specific group:
+```typescript
+hasGroup('Viewer')      // Returns true if user is in Viewer group
+hasGroup('External')    // Returns true if user is in External group
+```
+
+#### `findMatchingRule(rules, pathname)`
+Finds the first matching rule for a given pathname using glob patterns:
+```typescript
+// Matches paths like:
+// - /docs/domains/E-Commerce/orders
+// - /docs/domains/E-Commerce/products/catalog
+'/docs/domains/E-Commerce/*': () => hasRole('Developer')
+```
+
+## Access Rule Patterns
+
+### Path-based rules
+Control access to specific pages or sections using exact paths or wildcard patterns.
+```typescript
+const accessRules = {
+  // Exact path match
+  '/admin/settings': () => hasRole('Admin'),
+  
+  // Wildcard matching
+  '/docs/domains/Banking/*': () => hasGroup('Banking-Team'),
+  
+  // Multiple level wildcards
+  '/api/*/internal/*': () => hasRole('Internal-Developer'),
+};
+```
+
+### Role-based rules
+Define access permissions based on user roles with single or multiple role requirements.
+```typescript
+const accessRules = {
+  // Single role requirement
+  '/admin/*': () => hasRole('Admin'),
+  
+  // Multiple role options (OR)
+  '/docs/api/*': () => hasRole('Developer') || hasRole('Architect'),
+  
+  // Multiple role requirements (AND)
+  '/sensitive/*': () => hasRole('Admin') && hasRole('Security-Cleared'),
+};
+```
+
+### Group-based rules
+Manage access using group membership with inclusion, exclusion, or complex group logic.
+```typescript
+const accessRules = {
+  // Exclude specific groups
+  '/public/*': () => !hasGroup('External'),
+  
+  // Include specific groups
+  '/team-docs/*': () => hasGroup('Internal-Team'),
+  
+  // Complex group logic
+  '/project-alpha/*': () => hasGroup('Alpha-Team') || hasGroup('Leadership'),
+};
+```
+
+## Common use cases
+
+### Department-based access
+Organize access control around your organizational structure, ensuring teams only see documentation relevant to their department.
+```typescript
+const accessRules = {
+  '/docs/domains/HR/*': () => hasGroup('HR-Department'),
+  '/docs/domains/Finance/*': () => hasGroup('Finance-Department'),
+  '/docs/domains/Engineering/*': () => hasGroup('Engineering-Department'),
+};
+```
+
+### Hierarchical permissions
+Create layered access levels where higher privilege users can access all lower-level content.
+```typescript
+const accessRules = {
+  '/docs/public/*': () => true, // Everyone can access
+  '/docs/internal/*': () => !hasGroup('External'),
+  '/docs/confidential/*': () => hasRole('Manager') || hasRole('Admin'),
+  '/docs/top-secret/*': () => hasRole('Admin'),
+};
+```
+
+### Feature-based access
+Control access to specific EventCatalog features based on user roles and responsibilities.
+```typescript
+const accessRules = {
+  '/visualiser/*': () => hasRole('Architect') || hasRole('Developer'),
+  '/api-explorer/*': () => hasRole('Developer'),
+  '/admin/*': () => hasRole('Admin'),
+};
+```
+
+## Troubleshooting
+
+### Users getting 403 errors unexpectedly
+
+1. **Check role/group assignment** in your identity provider
+2. **Debug user permissions** by logging the locals to see what roles and groups are available:
+   ```typescript
+   export const rbacMiddleware: MiddlewareHandler = async (context, next) => {
+     const { locals, url } = context;
+     
+     // Log the user's roles and groups for debugging
+     console.log('User locals:', {
+       pathname: url.pathname,
+       locals: locals
+     });
+     
+     // Your existing middleware code...
+   };
+   ```
+3. **Verify rule logic** - ensure your conditions are correct:
+   ```typescript
+   // Wrong: This blocks everyone except Viewers
+   '/docs/*': () => hasGroup('Viewer')
+   
+   // Correct: This blocks only Viewers
+   '/docs/*': () => !hasGroup('Viewer')
+   ```
+
+### Rules not matching expected paths
+
+1. **Test your glob patterns** - ensure wildcards match your URL structure
+2. **Check path casing** - paths are case-sensitive
+3. **Verify rule order** - more specific rules should come before general ones
+
+### Session issues
+
+1. **Ensure user is authenticated** before middleware runs
+2. **Check session expiration** - users may need to re-authenticate
+3. **Verify locals are populated** - `hasRole` and `hasGroup` functions must be available
+
+## Security best practices
+
+- ✅ **Principle of least privilege** - Grant minimum required access
+- ✅ **Regular access reviews** - Audit user roles and permissions
+- ✅ **Test thoroughly** - Verify access rules with different user types
+- ✅ **Monitor access attempts** - Log and review 403 responses
+- ✅ **Use groups over individual users** - Easier to manage and scale
+
+## Next steps
+
+With RBAC middleware configured, you can:
+
+- Set up more complex access patterns based on your organization structure
+- Integrate with external authorization systems
+- Add custom logging for access attempts
+
+Need help? Join our [Discord community](https://eventcatalog.dev/discord) for support and best practices from other EventCatalog users.
\ No newline at end of file
diff --git a/packages/core/docs/development/authentication/_category_.json b/packages/core/docs/development/authentication/_category_.json
new file mode 100644
index 000000000..08a992bf6
--- /dev/null
+++ b/packages/core/docs/development/authentication/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Authentication",
+  "position": 10,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development/guides/auth",
+    "description": "Authentication for EventCatalog"
+  }
+}
diff --git a/packages/core/docs/development/authentication/providers/03-setting-up-github.md b/packages/core/docs/development/authentication/providers/03-setting-up-github.md
new file mode 100644
index 000000000..e2fe7d482
--- /dev/null
+++ b/packages/core/docs/development/authentication/providers/03-setting-up-github.md
@@ -0,0 +1,107 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog GitHub Authentication
+sidebar_label: GitHub
+title: Setting up GitHub
+description: Setting up GitHub authentication for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="2.43.0" />
+<PlanBanner plan="Scale" />
+
+:::info
+This guide takes your through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you’ve first gone through [Enabling authentication](/docs/development/authentication/enabling-authentication).
+:::
+
+To setup your EventCatalog site with visitor authentication using [GitHub](https://github.com/), the process looks as follows:
+
+1. Create a new GitHub OAuth app
+2. Configure the OAuth app in EventCatalog
+3. Test the authentication
+
+## Create a new GitHub OAuth app
+
+First, you will need to create a new GitHub OAuth app.
+
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
+2. Click on "New OAuth App"
+3. Fill in the details for your app
+    - **Application name:** `EventCatalog`
+    - **Homepage URL:** `{YOUR_EVENTCATALOG_SITE_URL}`
+        - Local development: `http://localhost:3000`
+    - **Authorization callback URL:** `{YOUR_EVENTCATALOG_SITE_URL}/api/auth/callback/github`
+        - Local development: `http://localhost:3000/api/auth/callback/github`
+4. Click on "Register application"
+5. Copy the Client ID and Client Secret
+
+## Configure the OAuth app in EventCatalog
+
+Add your GitHub Client ID and Client Secret to your `.env` file.
+
+```env title=".env"
+AUTH_GITHUB_CLIENT_ID={YOUR_GITHUB_CLIENT_ID}
+AUTH_GITHUB_CLIENT_SECRET={YOUR_GITHUB_CLIENT_SECRET}
+```
+
+In your `eventcatalog.auth.js` file, add the following:
+
+```js title="eventcatalog.auth.js"
+export default {
+  providers: {
+    github: {
+      clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+      clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+    },
+  },
+};
+```
+
+## Test the authentication
+
+Restart your EventCatalog server and test the authentication.
+
+```bash
+npm run dev
+```
+
+All pages should now be protected and require a GitHub account to access.
+
+![GitHub authentication](./img/github-auth.png)
+
+## Running behind a reverse proxy (`redirectProxyUrl`)
+
+When running behind a reverse proxy or load balancer (Kubernetes/AKS, Nginx, Cloudflare, AWS ALB/ECS, etc.), GitHub sign-in can break with:
+
+> The redirect_uri is not associated with this application.
+
+This happens when the OAuth `redirect_uri` ends up as `http://` (or an internal host) instead of your real `https://` URL, because the proxy terminates TLS and forwards the request internally. You may also see `InvalidCheck: pkceCodeVerifier value could not be parsed` in your logs from the same wrong base URL.
+
+[`AUTH_TRUST_HOST=true`](/docs/development/authentication/enabling-authentication#auth_trust_host) fixes this for most setups. If your proxy doesn't reliably forward the `x-forwarded-host` / `x-forwarded-proto` headers, set `redirectProxyUrl` to your canonical public URL to force the correct callback:
+
+```js title="eventcatalog.auth.js"
+export default {
+  providers: {
+    github: {
+      clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+      clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+      // Canonical public URL of your site, including /api/auth
+      redirectProxyUrl: 'https://catalog.example.com/api/auth',
+    },
+  },
+};
+```
+
+The host must match the **Authorization callback URL** on your GitHub OAuth app (`https://catalog.example.com/api/auth/callback/github`). Not needed on Vercel, Cloudflare Pages, or local dev. See the [Auth.js reference](https://authjs.dev/reference/core#redirectproxyurl) for more.
+
+## Found an issue?
+
+Remember to setup the prerequisites for this guide:
+
+- [Enabling authentication](/docs/development/authentication/enabling-authentication)
+
+If you still have problems, please [let us know](https://github.com/eventcatalog/eventcatalog/issues/new/choose).
+
diff --git a/packages/core/docs/development/authentication/providers/03a-setting-up-google.md b/packages/core/docs/development/authentication/providers/03a-setting-up-google.md
new file mode 100644
index 000000000..f23751bf8
--- /dev/null
+++ b/packages/core/docs/development/authentication/providers/03a-setting-up-google.md
@@ -0,0 +1,91 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog Google Authentication
+sidebar_label: Google
+title: Setting up Google
+description: Setting up Google authentication for EventCatalog
+id: setting-up-google
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="2.43.3" />
+<PlanBanner plan="Scale" />
+
+:::info
+This guide takes your through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you've first gone through [Enabling authentication](/docs/development/authentication/enabling-authentication).
+:::
+
+To setup your EventCatalog site with visitor authentication using [Google](https://accounts.google.com/), the process looks as follows:
+
+1. Create a new Google OAuth app
+2. Configure the OAuth app in EventCatalog
+3. Test the authentication
+
+## Create a new Google OAuth app
+
+First, you will need to create a new Google OAuth app in the Google Cloud Console.
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select an existing one
+3. Navigate to "APIs & Services" → "Library"
+4. Search for and enable the "Google+ API"
+5. Go to "APIs & Services" → "Credentials"
+6. Click "Create Credentials" → "OAuth client ID"
+7. If prompted, configure the OAuth consent screen:
+  - Choose "External" for testing
+  - Fill in app name: `EventCatalog`
+  - Add your user support email and developer contact email
+  - Save and continue through the remaining screens
+8. Create the OAuth client ID:
+  - **Application type:** Web application
+  - **Name:** `EventCatalog`
+  - **Authorized JavaScript origins:** `{YOUR_EVENTCATALOG_SITE_URL}`
+    - Local development: `http://localhost:3000`
+  - **Authorized redirect URIs:** `{YOUR_EVENTCATALOG_SITE_URL}/api/auth/callback/google`
+    - Local development: `http://localhost:3000/api/auth/callback/google`
+9. Click "Create" and copy the Client ID and Client Secret
+
+## Configure the OAuth app in EventCatalog
+
+Add your Google Client ID and Client Secret to your `.env` file.
+
+```env title=".env"
+AUTH_GOOGLE_CLIENT_ID={YOUR_GOOGLE_CLIENT_ID}
+AUTH_GOOGLE_CLIENT_SECRET={YOUR_GOOGLE_CLIENT_SECRET}
+```
+
+In your eventcatalog.auth.js file, add the following:
+
+```js title="eventcatalog.auth.js"
+export default {
+  enabled: true,
+  google: {
+    clientId: process.env.AUTH_GOOGLE_CLIENT_ID,
+    clientSecret: process.env.AUTH_GOOGLE_CLIENT_SECRET,
+  },
+}
+```
+
+## Test the authentication
+
+Restart your EventCatalog server and test the authentication.
+
+```bash
+npm run dev
+```
+
+All pages should now be protected and require a Google account to access.
+
+![Google authentication](./img/google-auth.png)
+
+## Found an issue?
+
+Remember to setup the prerequisites for this guide:
+
+- [Enabling authentication](/docs/development/authentication/enabling-authentication)
+
+If you still have problems, please [let us know](https://github.com/eventcatalog/eventcatalog/issues/new/choose).
+
diff --git a/packages/core/docs/development/authentication/providers/04-setting-up-azure-ad.md b/packages/core/docs/development/authentication/providers/04-setting-up-azure-ad.md
new file mode 100644
index 000000000..05f90f1f5
--- /dev/null
+++ b/packages/core/docs/development/authentication/providers/04-setting-up-azure-ad.md
@@ -0,0 +1,100 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog components
+sidebar_label: Azure AD (Entra ID)
+title: Setting up Azure AD (Entra ID)
+description: Setting up Microsoft Entra ID authentication for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="2.43.1" />
+<PlanBanner plan="Enterprise" />
+
+:::info
+This guide takes your through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you've first gone through [Enabling authentication](/docs/development/authentication/enabling-authentication).
+:::
+
+To setup your EventCatalog site with visitor authentication using [Microsoft Entra ID](https://entra.microsoft.com/) (formerly Azure Active Directory), the process looks as follows:
+
+1. [Create a new Azure app registration](#create-a-new-azure-app-registration)
+2. [Configure the Azure app in EventCatalog](#configure-the-azure-app-in-eventcatalog)
+3. [Test the authentication](#test-the-authentication)
+
+## Create a new Azure app registration
+
+First, you will need to create a new app registration in the Azure portal.
+
+1. Go to [portal.azure.com](https://portal.azure.com) and sign up for a free account or login
+2. Search for **Microsoft Entra ID** (or **Azure Active Directory**) in the top search bar
+3. Navigate to **App registrations** → **New registration**
+4. Fill in the application details:
+  - **Name:** `EventCatalog`
+  - **Supported account types:** Select **Accounts in any organizational directory and personal Microsoft accounts** (for broader compatibility)
+  - **Redirect URI:** Select **Web** and enter:
+    - Local development: `http://localhost:3000/api/auth/callback/microsoft-entra-id`
+5. Click **Register**
+6. After registration, note the **Application (client) ID** and **Directory (tenant) ID** from the Overview page
+7. Navigate to **Certificates & secrets** → **New client secret**
+8. Add a description (e.g., "EventCatalog Secret") and choose an expiration period
+9. Click **Add** and immediately copy the secret **Value** (you won't see it again)
+10. Go to **Authentication** in the sidebar and configure:
+   - Add additional redirect URIs for production: `{YOUR_EVENTCATALOG_SITE_URL}/api/auth/callback/microsoft-entra-id`
+   - Under **Implicit grant and hybrid flows**, check **ID tokens**
+   - Click **Save**
+
+## Configure the Azure app in EventCatalog
+
+Add your Azure AD Client ID, Client Secret, and Tenant ID to your `.env` file.
+
+```env title=".env"
+AUTH_MICROSOFT_ENTRA_ID_ID={YOUR_AZURE_CLIENT_ID}
+AUTH_MICROSOFT_ENTRA_ID_SECRET={YOUR_AZURE_CLIENT_SECRET}
+AUTH_MICROSOFT_ENTRA_ID_ISSUER=https://login.microsoftonline.com/{YOUR_AZURE_TENANT_ID}/v2.0
+```
+
+Your Azure AD tenant ID can be found in your app registration's Overview page in the Azure portal.
+
+In your eventcatalog.auth.js file, add the following:
+
+```js title="eventcatalog.auth.js"
+export default {
+  enabled: true,
+  providers: {
+    entra: {
+      clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
+      clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
+      issuer: process.env.AUTH_MICROSOFT_ENTRA_ID_ISSUER,
+    },
+  },
+};
+```
+
+## Test the authentication
+
+![Okta authentication](./img/microsoft-auth.png)
+
+Restart your EventCatalog server and test the authentication.
+
+```bash
+npm run dev
+```
+
+All pages should now be protected and require a Microsoft account to access.
+
+1. Navigate to your EventCatalog site
+1. You should be redirected to the sign-in page
+1. Click Sign in with Azure AD
+1. You'll be redirected to Microsoft's login page
+1. Enter your Microsoft account credentials (personal or organizational)
+1. After successful authentication, you'll be redirected back to EventCatalog
+
+## Found an issue?
+
+Remember to setup the prerequisites for this guide:
+
+- [Enabling authentication](/docs/development/authentication/enabling-authentication)
+
+If you still have problems, please [let us know](https://github.com/eventcatalog/eventcatalog/issues/new/choose).
\ No newline at end of file
diff --git a/packages/core/docs/development/authentication/providers/05-setting-up-okta.md b/packages/core/docs/development/authentication/providers/05-setting-up-okta.md
new file mode 100644
index 000000000..f2e26d312
--- /dev/null
+++ b/packages/core/docs/development/authentication/providers/05-setting-up-okta.md
@@ -0,0 +1,105 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog components
+sidebar_label: Okta 
+title: Setting up Okta
+description: Setting up Okta authentication for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="2.43.0" />
+<PlanBanner plan="Enterprise" />
+
+:::info
+This guide takes your through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you've first gone through [Enabling authentication](/docs/development/authentication/enabling-authentication).
+:::
+
+To setup your EventCatalog site with visitor authentication using [Okta](https://www.okta.com/), the process looks as follows:
+
+1. Create a new Okta OAuth app
+2. Configure the OAuth app in EventCatalog
+3. Test the authentication
+
+## Create a new Okta OAuth app
+
+First, you will need to create a new Okta OAuth app in your Okta Admin Console.
+
+1. Log in to your **[Okta Admin Console](https://login.okta.com/signin)**
+2. Navigate to **Applications** → **Applications**
+3. Click **Create App Integration**
+4. Select **OIDC - OpenID Connect** as the sign-in method
+5. Select **Web Application** as the application type
+6. Click **Next**
+7. Fill in the application details:
+    - **App integration name:** `EventCatalog`
+    - **Grant types:** Check `Authorization Code`
+    - **Sign-in redirect URIs:** 
+        - Production: `{YOUR_EVENTCATALOG_SITE_URL}/api/auth/callback/okta`
+        - Local development: `http://localhost:3000/api/auth/callback/okta`
+    - **Sign-out redirect URIs:**
+        - Production: `{YOUR_EVENTCATALOG_SITE_URL}`
+        - Local development: `http://localhost:3000`
+8. Under **Assignments**, choose who can access this application:
+    - **Allow everyone in your organization to access** (recommended)
+    - Or assign to specific groups
+9. Click **Save**
+10. Copy the **Client ID** and **Client Secret** from the app settings
+11. Note your **Okta domain** (e.g., `https://your-domain.okta.com`)
+
+## Configure the OAuth app in EventCatalog
+
+Add your Okta Client ID, Client Secret, and Issuer to your `.env` file.
+
+```env title=".env"
+AUTH_OKTA_CLIENT_ID={YOUR_OKTA_CLIENT_ID}
+AUTH_OKTA_CLIENT_SECRET={YOUR_OKTA_CLIENT_SECRET}
+AUTH_OKTA_ISSUER=https://{YOUR_OKTA_DOMAIN}
+```
+
+Your Okta issuer URL should be in the format: https://your-domain.okta.com (without /oauth2/default unless you're using a custom authorization server).
+In your eventcatalog.auth.js file, add the following:
+
+```js title="eventcatalog.auth.js"
+export default {
+  enabled: true,
+  providers: {
+    okta: {
+      clientId: process.env.AUTH_OKTA_CLIENT_ID,
+      clientSecret: process.env.AUTH_OKTA_CLIENT_SECRET,
+      issuer: process.env.AUTH_OKTA_ISSUER,
+    },
+  },
+};
+```
+
+## Test the authentication
+
+![Okta authentication](./img/okta-auth.png)
+
+Restart your EventCatalog server and test the authentication.
+
+```bash
+npm run dev
+```
+
+All pages should now be protected and require an Okta account to access.
+
+1. Navigate to your EventCatalog site
+1. You should be redirected to the sign-in page
+1. Click Sign in with Okta
+1. You'll be redirected to your Okta login page
+1. Enter your Okta credentials
+1. After successful authentication, you'll be redirected back to EventCatalog
+
+
+## Found an issue?
+
+Remember to setup the prerequisites for this guide:
+
+- [Enabling authentication](/docs/development/authentication/enabling-authentication)
+
+If you still have problems, please [let us know](https://github.com/eventcatalog/eventcatalog/issues/new/choose).
+
diff --git a/packages/core/docs/development/authentication/providers/06-setting-up-auth0.md b/packages/core/docs/development/authentication/providers/06-setting-up-auth0.md
new file mode 100644
index 000000000..9858e2d8e
--- /dev/null
+++ b/packages/core/docs/development/authentication/providers/06-setting-up-auth0.md
@@ -0,0 +1,106 @@
+---
+sidebar_position: 6
+keywords:
+- EventCatalog components
+sidebar_label: Auth0 
+title: Setting up Auth0
+description: Setting up Auth0 authentication for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="2.43.1" />
+<PlanBanner plan="Enterprise" />
+
+:::info
+This guide takes your through setting up a protected sign-in screen for your docs. Before going through this guide, make sure you've first gone through [Enabling authentication](/docs/development/authentication/enabling-authentication).
+:::
+
+To setup your EventCatalog site with visitor authentication using [Auth0](https://auth0.com/), the process looks as follows:
+
+1. [Create a new Auth0 application](#create-a-new-auth0-application)
+2. [Configure the Auth0 app in EventCatalog](#configure-the-auth0-app-in-eventcatalog)
+3. [Test the authentication](#test-the-authentication)
+
+## Create a new Auth0 application
+
+First, you will need to create a new Auth0 application in your Auth0 Dashboard.
+
+1. Go to [auth0.com](https://auth0.com) and sign up for a free account or login
+2. In the Auth0 Dashboard, navigate to **Applications** → **Applications**
+3. Click **Create Application**
+4. Fill in the application details:
+   - **Name:** `EventCatalog`
+   - **Application Type:** Select **Regular Web Applications**
+5. Click **Create**
+6. In your new application's **Settings** tab, configure the following:
+   - **Allowed Callback URLs:**
+       - Production: `{YOUR_EVENTCATALOG_SITE_URL}/api/auth/callback/auth0`
+       - Local development: `http://localhost:3000/api/auth/callback/auth0`
+   - **Allowed Logout URLs:**
+       - Production: `{YOUR_EVENTCATALOG_SITE_URL}`
+       - Local development: `http://localhost:3000`
+   - **Allowed Web Origins:**
+       - Production: `{YOUR_EVENTCATALOG_SITE_URL}`
+       - Local development: `http://localhost:3000`
+   - **Allowed Origins (CORS):**
+       - Production: `{YOUR_EVENTCATALOG_SITE_URL}`
+       - Local development: `http://localhost:3000`
+7. Leave **Initiate Login URI** empty (not required)
+8. Click **Save Changes**
+9. Copy the **Domain**, **Client ID**, and **Client Secret** from the app settings
+
+## Configure the Auth0 app in EventCatalog
+
+Add your Auth0 Domain, Client ID, and Client Secret to your `.env` file.
+
+```env title=".env"
+AUTH_AUTH0_ID={YOUR_AUTH0_CLIENT_ID}
+AUTH_AUTH0_SECRET={YOUR_AUTH0_CLIENT_SECRET}
+AUTH_AUTH0_ISSUER=https://{YOUR_AUTH0_DOMAIN}
+```
+
+Your Auth0 issuer URL should be in the format: https://your-tenant.auth0.com (this is the Domain from your Auth0 application settings).
+
+In your eventcatalog.auth.js file, add the following:
+
+```js title="eventcatalog.auth.js"
+export default {
+  enabled: true,
+  providers: {
+    auth0: {
+      clientId: process.env.AUTH_AUTH0_ID,
+      clientSecret: process.env.AUTH_AUTH0_SECRET,
+      issuer: process.env.AUTH_AUTH0_ISSUER,
+    },
+  },
+};
+```
+
+## Test the authentication
+
+![Okta authentication](./img/auth0-auth.png)
+
+Restart your EventCatalog server and test the authentication.
+
+```bash
+npm run dev
+```
+
+All pages should now be protected and require an Auth0 account to access.
+
+1. Navigate to your EventCatalog site
+1. You should be redirected to the sign-in page
+1. Click Sign in with Auth0
+1. You'll be redirected to your Auth0 login page
+1. Enter your credentials or sign up for a new account
+1. After successful authentication, you'll be redirected back to EventCatalog
+
+## Found an issue?
+
+Remember to setup the prerequisites for this guide:
+
+- [Enabling authentication](/docs/development/authentication/enabling-authentication)
+
+If you still have problems, please [let us know](https://github.com/eventcatalog/eventcatalog/issues/new/choose).
\ No newline at end of file
diff --git a/packages/core/docs/development/authentication/providers/_category_.json b/packages/core/docs/development/authentication/providers/_category_.json
new file mode 100644
index 000000000..c6cecc51a
--- /dev/null
+++ b/packages/core/docs/development/authentication/providers/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Providers",
+  "position": 15,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development/authentication/providers",
+    "description": "Authentication for EventCatalog"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/development/bring-your-own-documentation/01-introduction.md b/packages/core/docs/development/bring-your-own-documentation/01-introduction.md
new file mode 100644
index 000000000..8d89370a8
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/01-introduction.md
@@ -0,0 +1,54 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog custom documentation
+sidebar_label: Introduction
+title: Bring your own documentation
+description: Bring your own documentation to EventCatalog
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+EventCatalog lets you bring your own documentation and diagrams into your catalog.
+
+This is useful when your documentation is spread across multiple repositories, project folders, wikis, or internal tools. You can bring that context into EventCatalog and make it part of the same experience people already use to explore your architecture.
+
+You can document anything that helps your teams understand, operate, and govern your systems, including:
+
+- Team onboarding documentation
+- Best practices and engineering standards
+- Runbooks and operational guides
+- CI/CD and deployment documentation
+- User journeys and business processes
+- Technical debt and migration notes
+
+EventCatalog has a few ways to bring your own information to your catalog:
+
+1. [High level documentation](#high-level-documentation)
+   - for catalog-wide knowledge that is not tied to one specific resource
+1. [Resource-level documentation](#resource-level-documentation)
+   - for documentation attached to a specific domain, service, event, API, or other catalog resource
+1. [Diagrams](/docs/development/bring-your-own-documentation/diagrams/introduction)
+   -  bring your own diagrams (e.g Miro, DrawIO, Mermaid) to your catalog.
+
+---
+
+### High level documentation
+
+High level documentation is for top-level knowledge that should live in your catalog but does not belong to one specific resource.
+
+Use high level documentation for things like engineering standards, onboarding guides, architecture principles, platform runbooks, team processes, or shared API guidance. These pages appear in your catalog's documentation area and can be organized independently from your domains, services, and events.
+
+[Read the high level documentation guide](/docs/development/bring-your-own-documentation/custom-pages/introduction).
+
+### Resource-level documentation
+
+Resource-level documentation is for knowledge that belongs with a specific EventCatalog resource.
+
+Use resource-level documentation when the context should appear next to the thing it describes. For example, you can attach service runbooks to a service, onboarding material to a domain, operational notes to a system, or extra API documentation to an API.
+
+EventCatalog renders this documentation alongside the resource, so readers can move between the resource overview and its supporting documentation without leaving the catalog.
+
+[Read the resource-level documentation guide](/docs/development/bring-your-own-documentation/resource-docs/introduction).
diff --git a/packages/core/docs/development/bring-your-own-documentation/_category_.json b/packages/core/docs/development/bring-your-own-documentation/_category_.json
new file mode 100644
index 000000000..6d53511c2
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Bring your own documentation",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "bring-your-own-documentation",
+    "title": "Bring your own documentation",
+    "description": "Bring your own documentation to EventCatalog. Add global custom pages or attach docs directly to individual resources."
+  }
+}
diff --git a/packages/core/docs/development/bring-your-own-documentation/custom-pages/01-introduction.md b/packages/core/docs/development/bring-your-own-documentation/custom-pages/01-introduction.md
new file mode 100644
index 000000000..3a0ae1e01
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/custom-pages/01-introduction.md
@@ -0,0 +1,61 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog custom documentation
+sidebar_label: Introduction
+title: Introduction
+description: Customize documentation in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="2.33.0" />
+<PlanBanner plan="Scale" />
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/auzmEf0AdJg?si=wHe-3X6b6uLN39sB" 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>
+
+---
+
+High level documentation is a way to add catalog-wide custom documentation pages to your catalog.
+
+This can be a great way to extend your catalog beyond what is provided, and bring your own documentation to EventCatalog, rather than having documentation spread across multiple tools.
+
+
+![Example](./img/custom-docs.png)
+<a class="block" href="https://demo.eventcatalog.dev/docs/custom/technical-architecture-design/architecture-decision-records/published/01-api-gateway-pattern">View demo</a>
+
+High level documentation is not limited, here are some examples of what you can do:
+
+- Document infrastructure & operations
+- Document CI/CD pipelines
+- Document user journeys
+- Document API documentation
+- Document technical debt
+- Document team processes
+- Document onboarding information
+- Document best practices
+- Document standards
+
+It's really up to you what you add here.
+
+### How high level documentation can help
+
+EventCatalog provides the ability to document your architecture with domains, services and messages. 
+
+Users still have third party tools to document other parts of their architecture (e.g confluence, Google docs, etc), so this is an option to help you keep all your documentation in one place.
+
+### What can I do with high level documentation in EventCatalog?
+
+You can add any custom documentation to your catalog, this also gives you access to the [EventCatalog components](/docs/components).
+Your custom documentation is powered by markdown, meaning you can use EventCatalog components within your documentation.
+
+### Roadmap for high level documentation
+
+This is the initial version of high level documentation in EventCatalog.
+
+We plan to add the following features:
+
+- Add support to embed EventCatalog visualizations into your documentation pages
+- Embed EventCatalog resources into your custom documentation pages
+- Add ability to add runtime blocks into your pages (e.g making requests to get third party data to display)
diff --git a/packages/core/docs/development/bring-your-own-documentation/custom-pages/02-adding-custom-docs.md b/packages/core/docs/development/bring-your-own-documentation/custom-pages/02-adding-custom-docs.md
new file mode 100644
index 000000000..9111c6be8
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/custom-pages/02-adding-custom-docs.md
@@ -0,0 +1,245 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog high level documentation
+sidebar_label: Adding high level documentation
+title: Adding high level documentation
+description: Adding high level documentation to your EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+<AddedIn version="2.33.0" />
+<PlanBanner plan="Scale" />
+
+## Getting started
+
+High level documentation requires an EventCatalog Scale license key. You can get a 30-day free trial from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+## Adding high level documentation
+
+High level documentation is split into two parts:
+
+1. [Creating your documentation (markdown files)](#creating-your-documentation)
+2. [Configuring your sidebar (eventcatalog.config.js)](#configuring-your-sidebar)
+
+### Creating documentation
+
+High level documentation is stored in the `/docs` folder in your catalog [(see example on GitHub)](https://github.com/event-catalog/eventcatalog/tree/main/examples/default/docs), and can be accessed via the url `/docs/custom/`.
+
+All documentation is a `.mdx` (markdown extended) file. You can organize these however you want, for example:
+
+<ProjectTree
+  items={[
+    {
+      name: 'docs',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'architecture-decision-records',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'drafts',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: '01-introduction.mdx' },
+                { name: '02-example-record.mdx' },
+              ],
+            },
+            {
+              name: 'published',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: '01-introduction.mdx' },
+                { name: '02-example-record.mdx' },
+              ],
+            },
+            {
+              name: 'examples',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: '01-introduction.mdx' },
+                { name: '02-example-record.mdx' },
+              ],
+            },
+          ],
+        },
+        {
+          name: 'runbooks',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: '01-introduction.mdx' },
+            { name: '02-deployment-procedure.mdx' },
+            { name: '03-disaster-recovery.mdx' },
+            { name: '04-incident-response.mdx' },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+In this example we have high level documentation for:
+
+- architecture Decision Records
+- Runbooks
+
+:::tip Organize your high level documentation
+We added numbers (01, 02, 03) to the files to help with maintenance, you can configure the order of the files in your configuration.
+:::
+
+
+#### Structure of markdown files for high level documentation
+
+Each markdown file is split into two parts:
+
+1. The frontmatter (properties at the top of the file)
+2. The content (the rest of the file)
+
+```mdx
+---
+title: Architecture decision records
+summary: A comprehensive guide to creating new microservices at FlowMart following our best practices and standards
+owners: 
+  - dboyne
+badges:
+  - content: 'Guide'
+    backgroundColor: 'teal'
+    textColor: 'teal'
+---
+
+This is your content for your file.
+
+```
+
+**Frontmatter properties**
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `title` | Yes | The title of the page |
+| `summary` | Yes | A summary of the page |
+| `slug` | No | Ability to override the slug (url) of the page |
+| `owners` | No | Owners of the page (EventCatalog owners) |
+| `badges` | No | The badges of the page |
+
+#### Sidebar configuration
+
+You need to configure the sidebar to include your custom documentation, we do this by using the `customDocs` property in your `eventcatalog.config.js` file.
+
+We have two options for the sidebar:
+
+1. Manually map files and paths to the sidebar
+2. Use the autogenerated option to generate the sidebar items
+
+:::tip Autogenerated sidebar
+The autogenerated sidebar is the easiest option, it will render all the files in the directory and subdirectories.
+If you want to choose which files and order they are displayed in, you can manually map the files and paths to the sidebar.
+:::
+
+```js
+export default {
+  // rest of your config
+  customDocs: {
+    sidebar: [
+      {
+        label: 'architecture Decision Records',
+        badge: {
+          text: 'New', color: 'green'
+        },
+        collapsed: false,
+        items: [
+          {
+            // Here we map the directory, and use autogenerated to generate the sidebar items
+            // Any item added to the folder will be rendered automatically in EventCatalog
+            label: 'Drafts', autogenerated: { directory: '/architecture-decision-records/drafts' }
+          },
+          {
+            label: 'Published', autogenerated: { directory: '/architecture-decision-records/published' }
+          },
+          {
+            label: 'Examples', autogenerated: { directory: '/architecture-decision-records/examples' }
+          }
+        ]
+      },
+      {
+        label: 'Runbooks',
+        badge: {
+          text: 'New', color: 'green'
+        },
+        collapsed: false,
+        items: [
+          {
+            // Here we create custom pages in the sidebar
+            // We can manually map the slug to a file, or use the autogenerated to generate the sidebar items
+            label: 'Creating a new runbook', items: [
+              { label: 'Introduction', slug: 'runbooks/01-introduction' },
+              { label: 'Deployment Procedure', slug: 'runbooks/02-deployment-procedure' },
+              { label: 'Disaster Recovery', slug: 'runbooks/03-disaster-recovery' },
+              { label: 'Incident Response', slug: 'runbooks/04-incident-response' },
+            ]
+          },
+        ]
+      }
+    ]
+  }
+};
+ ```
+
+
+#### Rendered output
+
+The rendered output will be the content of the markdown file, with the frontmatter properties.
+
+![Example](./img/custom-docs.png)
+<a class="block" href="https://demo.eventcatalog.dev/docs/custom/technical-architecture-design/architecture-decision-records/published/01-api-gateway-pattern">View demo</a>
+
+### Custom HTML attributes
+
+<AddedIn version="2.33.4" />
+
+Links can also include an attrs property to add custom HTML attributes to the link element.
+
+In the following example, attrs is used to add a target="_blank" attribute, so that the link opens in a new tab, and to apply a custom style attribute to italicize the link label:
+
+```js
+export default {
+  // rest of your config
+  customDocs: {
+    sidebar: [
+      {
+        label: 'My Links',
+        items: [
+          {
+            label: 'Read more on GitHub',
+            link: 'https://github.com/event-catalog/eventcatalog',
+            attrs: { target: '_blank', style: 'font-style: italic;' },
+          },
+        ]
+      },
+    ]
+  }
+};
+ ```
+
+ #### Rendered output
+
+![Example](./img/custom-attrs.png)
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/core/docs/development/bring-your-own-documentation/custom-pages/03-components.md b/packages/core/docs/development/bring-your-own-documentation/custom-pages/03-components.md
new file mode 100644
index 000000000..86d600365
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/custom-pages/03-components.md
@@ -0,0 +1,56 @@
+---
+sidebar_position: 3
+keywords:
+    - components 
+    - domains
+sidebar_label: Components
+title: Components
+description: Component list for custom pages 
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+You can add custom EventCatalog components to your custom pages.
+
+[See the list of components and how to use them](/docs/development/components/using-components).
+
+You can also added components designed specifically for custom documentation.
+
+### Embed EventCatalog Visualizer (NodeGraph)
+
+In your custom documentation pages you can embed the EventCatalog Visualizer (NodeGraph) using the `NodeGraph` component.
+
+![Example](./img/custom-docs-with-nodegraph.png)
+
+This let's you embed any visualization (domain, service, message) into your custom documentation page.
+
+To embed the NodeGraph component, you need to use the component, and pass in the `id` of the resource, `version` and `type`.
+
+```md
+This is my custom documentation page, here is a NodeGraph:
+
+<!-- Here we embed the NodeGraph component, passing in the id, version and type of the resource -->
+<!-- This exammple will render a domain called "Orders" with the version "1.0.0" -->
+<NodeGraph id="Orders" version="1.0.0" type="domain" />
+
+## Getting Started
+
+Rest of my markdown content...
+```
+
+:::note Required props
+In custom documentation pages, `id`, `version`, and `type` are all required. A `<NodeGraph />` missing any of these props is silently ignored.
+:::
+
+#### NodeGraph props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | string | Yes | The id of the resource (domain, service, or message) |
+| `version` | string | Yes | The version of the resource |
+| `type` | string | Yes | The type of the resource (domain, service, command, event, query) |
+| `search` | boolean | No | Show or hide the search bar. Accepts `true`/`false` or `"true"`/`"false"`. Defaults to `true`. |
+| `legend` | boolean | No | Show or hide the legend. Accepts `true`/`false` or `"true"`/`"false"`. Defaults to `true`. |
+| `mode` | string | No | `"simple"` or `"full"`. Defaults to `"simple"`. |
diff --git a/packages/core/docs/development/bring-your-own-documentation/custom-pages/04-owners.md b/packages/core/docs/development/bring-your-own-documentation/custom-pages/04-owners.md
new file mode 100644
index 000000000..ede315648
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/custom-pages/04-owners.md
@@ -0,0 +1,46 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog
+- channels 
+- owners
+sidebar_label: Owners
+title: Adding custom page owners
+description: Adding owners to custom pages with EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="2.33.0" />
+<PlanBanner plan="Scale" />
+
+Owners in EventCatalog are either **users** or **teams** and are **optional**.
+
+To add an owner or a team, you need to add the user or team to the owners field of the custom page.
+
+## Adding owners using frontmatter
+
+To add owners within a custom page you need to add them to the `owners` array within your custom page frontmatter API.
+
+You need to add the `id` of the owner.
+
+```md title="/docs/guides/creating-a-new-producer/index.mdx (example)"
+---
+id: OrderChannel
+... # other custom page frontmatter
+owners:
+    - dboyne # represents a user
+    - webTeam # represents a team
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Assigning owners to your custom pages can provide others with context of who owns this custom page and how to contact them.
+
+:::tip Creating users and teams
+    EventCatalog gives you the ability to create users and teams. You can read the documentation to get started.
+:::
+
diff --git a/packages/core/docs/development/bring-your-own-documentation/custom-pages/_category_.json b/packages/core/docs/development/bring-your-own-documentation/custom-pages/_category_.json
new file mode 100644
index 000000000..fbc3ecc92
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/custom-pages/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "High level documentation",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "guides/bring-your-own-documentation/custom-pages",
+    "description": "Add catalog-wide custom documentation pages to your catalog."
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/development/bring-your-own-documentation/diagrams/01-introduction.md b/packages/core/docs/development/bring-your-own-documentation/diagrams/01-introduction.md
new file mode 100644
index 000000000..214ef4e80
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/diagrams/01-introduction.md
@@ -0,0 +1,56 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog diagrams
+- Architecture diagrams
+- Custom diagrams
+- Mermaid
+- PlantUML
+- Miro
+- IcePanel
+sidebar_label: What are diagrams?
+title: What are diagrams?
+description: Bring your own diagrams to EventCatalog - version them, compare them, and assign them to any resource
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+You can bring your own diagrams (e.g Miro, DrawIO, Mermaid, PlantUML) into your catalog and assign them to any resource in your catalog.
+
+With diagrams in EventCatalog you can:
+
+- **Bring any diagram type** - Mermaid, PlantUML, Miro embeds, IcePanel, Lucidchart, draw.io, images, or any MDX content
+- **Version and compare your diagrams** - Track how your architecture visualizations evolve over time and compare them
+- **Assign to any resource** - Link to any catalog resource (e.g domain, system, service, message)
+- **Context to your AI** - EventCatalog MCP exposes your diagrams to your AI agents.
+
+<!-- 
+### What do diagrams look like in EventCatalog?
+
+Diagrams have their own dedicated pages with version switching and appear in the sidebar when assigned to resources.
+
+![Diagram page](./img/diagrams.png)
+
+[View Demo of a Target Architecture diagram &rarr;](https://demo.eventcatalog.dev/diagrams/target-architecture/1.0.0)
+
+### When to use custom diagrams
+
+Use diagrams when you want to:
+
+- Document target architecture or migration plans
+- Embed Miro boards, IcePanel views, or other collaborative diagrams
+- Create sequence diagrams showing detailed message flows
+- Share event storming results or architecture decision records
+- Maintain historical versions of architectural diagrams
+- Add visual context that can't be auto-generated from your resources
+
+### Supported content formats
+
+Diagrams support any content you can write in MDX:
+
+- **Mermaid diagrams** - Flowcharts, sequence diagrams, C4 diagrams
+- **PlantUML diagrams** - UML, sequence, component diagrams
+- **Embedded diagrams** - Miro, IcePanel, Lucidchart, draw.io, FigJam
+- **Static images** - PNG, SVG, JPG files
+- **Markdown content** - Add explanations and documentation around visuals
+- **Custom components** - Use any MDX component to enhance your diagrams -->
diff --git a/packages/core/docs/development/bring-your-own-documentation/diagrams/02-creating-diagrams.md b/packages/core/docs/development/bring-your-own-documentation/diagrams/02-creating-diagrams.md
new file mode 100644
index 000000000..c222d8b7d
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/diagrams/02-creating-diagrams.md
@@ -0,0 +1,262 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog diagrams
+- Creating diagrams
+sidebar_label: Create a diagram
+title: Create a diagram
+description: How to create and organize diagrams in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+EventCatalog Diagrams let's you bring your own diagrams into your Catalog.
+
+![System Architecture diagram](./img/diagrams.png)
+
+## Creating a diagram
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog diagram">
+Read https://www.eventcatalog.dev/docs/development/bring-your-own-documentation/diagrams/creating-diagrams.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/diagrams.md then help me create a new EventCatalog diagram in my catalog.
+
+Ask me for the diagram name, what it shows, summary, whether it belongs at the root of the catalog or inside a resource, and what diagram format I want to use such as Mermaid, PlantUML, an embedded tool, an image, or markdown. Then create the correct diagrams/{'{Diagram Name}'}/index.mdx, domains/{'{Domain Name}'}/diagrams/{'{Diagram Name}'}/index.mdx, services/{'{Service Name}'}/diagrams/{'{Diagram Name}'}/index.mdx, or another relevant resource-level diagrams/{'{Diagram Name}'}/index.mdx file with frontmatter and starter markdown.
+
+If I want to embed an external diagram, ask for the embed URL and use the correct EventCatalog diagram component if one exists.
+
+If the catalog does not have a relevant resource, put it into the root diagrams folder.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the diagram should live, create the right folder structure, and add the first version of the diagram documentation.
+
+### Manual Creation
+
+Diagrams live in a `diagrams` folder. EventCatalog discovers any `index.mdx` file inside a `diagrams` directory, regardless of where that directory lives in your catalog.
+
+You can place diagrams:
+
+At the root of your catalog:
+
+<ProjectTree
+  items={[
+    {
+      name: 'diagrams',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'system-overview',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a domain:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'E-Commerce',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'diagrams',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'target-architecture',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a service:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrderService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'diagrams',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'api-flow',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+:::tip
+Organize diagrams close to where they're most relevant. System-wide diagrams can be placed at the root level, while resource-specific diagrams should live within that resource's folder.
+:::
+
+## Create the diagram file
+
+Create an `index.mdx` file for the diagram.
+
+Here is an example of a system architecture diagram:
+
+```md title="/diagrams/system-overview/index.mdx (example)"
+---
+id: system-overview
+name: System Overview
+version: 1.0.0
+summary: High-level architecture showing all microservices and their interactions
+---
+
+## System Architecture
+
+This diagram shows our microservices architecture:
+
+\`\`\`mermaid
+graph TB
+    subgraph "Frontend"
+        WebApp[Web Application]
+        MobileApp[Mobile App]
+    end
+
+    subgraph "Backend Services"
+        Gateway[API Gateway]
+        OrderService[Order Service]
+        PaymentService[Payment Service]
+        InventoryService[Inventory Service]
+    end
+
+    subgraph "Data Layer"
+        OrderDB[(Orders DB)]
+        PaymentDB[(Payments DB)]
+        Kafka[Event Stream]
+    end
+
+    WebApp --> Gateway
+    MobileApp --> Gateway
+    Gateway --> OrderService
+    Gateway --> PaymentService
+    OrderService --> Kafka
+    PaymentService --> Kafka
+    OrderService --> OrderDB
+    PaymentService --> PaymentDB
+\`\`\`
+
+### Key Components
+
+- **API Gateway**: Single entry point for all client requests
+- **Order Service**: Handles order creation and management
+- **Payment Service**: Processes payments and refunds
+- **Event Stream**: Kafka for asynchronous communication
+```
+
+
+### Example with PlantUML
+
+```md title="/diagrams/order-flow/index.mdx (example)"
+---
+id: order-flow
+name: Order Processing Flow
+version: 1.0.0
+summary: Sequence diagram showing the complete order processing flow
+---
+
+\`\`\`plantuml
+@startuml
+actor Customer
+participant "Order Service" as Order
+participant "Payment Service" as Payment
+participant "Inventory Service" as Inventory
+
+Customer -> Order: Create Order
+Order -> Inventory: Check Stock
+Inventory --> Order: Stock Available
+Order -> Payment: Process Payment
+Payment --> Order: Payment Confirmed
+Order --> Customer: Order Confirmed
+@enduml
+\`\`\`
+
+## Order Processing Flow
+
+This sequence diagram illustrates the order processing workflow:
+
+1. Customer initiates order creation
+2. Order service validates inventory availability
+3. Payment is processed
+4. Order confirmation is sent to customer
+```
+
+### Example with embedded diagram
+
+EventCatalog provides built-in components to embed diagrams from popular tools like Miro, IcePanel, Lucidchart, draw.io, and FigJam. This lets you bring your existing collaborative diagrams directly into your catalog.
+
+```md title="/diagrams/architecture-overview/index.mdx (example)"
+---
+id: architecture-overview
+name: Architecture Overview
+version: 1.0.0
+summary: Miro board showing our system architecture and design decisions
+---
+
+<Miro embedUrl="https://miro.com/app/board/..." />
+
+## Architecture Overview
+
+This Miro board captures our architecture decisions and system design.
+Key areas covered:
+
+- System context
+- Container architecture
+- Component relationships
+- Technology choices
+```
+
+:::tip
+Check out the [Diagrams documentation](/docs/components/diagram-syntax) to see all available diagram syntax and embed components including `<Miro>`, `<IcePanel>`, `<Lucid>`, `<DrawIO>`, and `<FigJam>`.
+:::
+
+## Next steps
+
+Once you've created diagrams, you can:
+
+- [Reference them from resources](/docs/development/bring-your-own-documentation/diagrams/referencing-diagrams) like domains, services, and messages
+- [Compare diagram versions](/docs/development/bring-your-own-documentation/diagrams/comparing-diagrams) side-by-side
diff --git a/packages/core/docs/development/bring-your-own-documentation/diagrams/03-referencing-diagrams.md b/packages/core/docs/development/bring-your-own-documentation/diagrams/03-referencing-diagrams.md
new file mode 100644
index 000000000..22f16a886
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/diagrams/03-referencing-diagrams.md
@@ -0,0 +1,111 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog diagrams
+- Referencing diagrams
+sidebar_label: Add diagrams to resources
+title: Add diagrams to resources
+description: How to link diagrams to domains, services, messages, and other resources
+---
+
+You can assign your diagrams to resources in EventCatalog.
+
+When you reference a diagram from a resource, EventCatalog automatically:
+
+- Adds the diagram to the resource's sidebar under a "Diagrams" section
+- Creates a clickable link to the full diagram page
+- Shows the diagram name and summary in the sidebar
+
+<div className="flex justify-center">
+  <img src="/img/diagram-sidebar.png" alt="Diagram references" className="rounded-lg" style={{ width: '20%', height: 'auto' }} />
+</div>
+
+## Referencing diagrams in frontmatter
+
+To reference diagrams from any resource, use the `diagrams` field in the frontmatter:
+
+```yaml
+diagrams:
+  - id: diagram-id
+    # version is optional and defaults to latest if not specified
+    version: 1.0.0
+```
+
+The `version` field is optional and defaults to `latest` if not specified.
+
+## Examples
+
+### Referencing diagrams from a domain
+
+Domain-level diagrams often show the overall architecture, domain boundaries, or integration patterns.
+
+```md title="/domains/E-Commerce/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce Domain
+version: 1.0.0
+summary: Core business domain for our e-commerce platform
+diagrams:
+  - id: target-architecture
+    version: 1.0.0
+  - id: order-flow
+    version: 1.0.0
+---
+
+## Overview
+
+The E-Commerce domain handles all order processing...
+```
+
+When users view the E-Commerce domain, they'll see a "Diagrams" section in the sidebar with links to both the "Target Architecture" and "Order Flow" diagrams.
+
+### Referencing diagrams from a service
+
+Service-level diagrams typically show API flows, service interactions, or internal component architecture.
+
+```md title="/services/OrderService/index.mdx"
+---
+id: OrderService
+name: Order Service
+version: 2.0.0
+summary: Manages order lifecycle and orchestration
+diagrams:
+  - id: order-api-flow
+    version: 2.0.0
+  - id: order-state-machine
+    version: 1.0.0
+---
+
+## Overview
+
+The Order Service is responsible for...
+```
+
+### Referencing diagrams from a message
+
+Message-level diagrams can show sequence flows, event propagation, or payload structures.
+
+```md title="/events/OrderCreated/index.mdx"
+---
+id: OrderCreated
+name: Order Created
+version: 1.0.0
+summary: Published when a new order is created
+diagrams:
+  - id: order-creation-flow
+    version: 1.0.0
+---
+
+## Event Details
+
+This event is published when...
+```
+
+## Viewing referenced diagrams
+
+When viewing a resource that references diagrams, users will see:
+
+1. A "Diagrams" section in the sidebar navigation
+2. Each diagram listed with its name
+3. Clicking a diagram navigates to the full diagram page
+4. The diagram page includes version selection and full content
diff --git a/packages/core/docs/development/bring-your-own-documentation/diagrams/05-comparing-diagrams.md b/packages/core/docs/development/bring-your-own-documentation/diagrams/05-comparing-diagrams.md
new file mode 100644
index 000000000..09b56d0cf
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/diagrams/05-comparing-diagrams.md
@@ -0,0 +1,25 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog diagrams
+- Diagram comparison
+sidebar_label: Compare diagram versions
+title: Comparing diagram versions
+description: Side-by-side version comparison for diagrams in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+The diagram comparison feature allows you to view two versions of a diagram side-by-side, making it easy to understand architectural changes and evolution over time.
+
+This can be useful if you want to plan for changes, or track changes over time.
+
+![Compare diagram versions](./img/diagrams-compare.png)
+
+### How to compare diagrams
+
+1. Navigate to any diagram page that has multiple versions
+2. Click the "Compare diagram versions" button in the header
+3. Select which two versions you want to compare
+4. View both diagrams side-by-side with synchronized scrolling
+
diff --git a/packages/core/docs/development/bring-your-own-documentation/diagrams/07-reference.md b/packages/core/docs/development/bring-your-own-documentation/diagrams/07-reference.md
new file mode 100644
index 000000000..33affd555
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/diagrams/07-reference.md
@@ -0,0 +1,144 @@
+---
+keywords:
+- EventCatalog diagrams
+- Diagram frontmatter
+sidebar_label: Reference
+title: Diagrams reference
+description: Frontmatter fields, paths, and routes for diagrams in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by diagrams.
+
+## Paths
+
+Diagrams can be created in any `diagrams` folder:
+
+```txt
+/diagrams/{Diagram Name}/index.mdx
+/domains/{Domain Name}/diagrams/{Diagram Name}/index.mdx
+/systems/{System Name}/diagrams/{Diagram Name}/index.mdx
+```
+
+Versioned diagrams use:
+
+```txt
+/diagrams/{Diagram Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/diagrams/{diagram-id}/{version}` | Diagram documentation page. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the diagram. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: checkout-sequence
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the diagram.
+
+```md title="Example"
+---
+name: Checkout Sequence
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the diagram documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short description of the diagram.
+
+```md title="Example"
+---
+summary: Sequence diagram for checkout orchestration.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the diagram.
+
+```md title="Example"
+---
+owners:
+  - checkout-platform
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the diagram page.
+
+```md title="Example"
+---
+badges:
+  - content: Mermaid
+    backgroundColor: blue
+    textColor: blue
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the diagram.
+
+```md title="Example"
+---
+repository:
+  url: https://github.com/acme/architecture
+---
+```
+
+### `attachments` {#attachments}
+
+- Type: `array`
+
+External links or supporting documents attached to the diagram.
+
+```md title="Example"
+---
+attachments:
+  - title: Source diagram
+    url: https://miro.com/app/board/example
+    type: miro
+---
+```
+
+## Content
+
+Diagram pages can contain any MDX supported by EventCatalog, including Mermaid, PlantUML, Miro, IcePanel, Lucid, Draw.io, FigJam, images, and normal markdown.
diff --git a/packages/core/docs/development/bring-your-own-documentation/diagrams/_category_.json b/packages/core/docs/development/bring-your-own-documentation/diagrams/_category_.json
new file mode 100644
index 000000000..964bf042a
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/diagrams/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Diagrams",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "bring-your-own-documentation/diagrams",
+    "description": "Learn how to document your architecture with reusable diagrams"
+  }
+}
diff --git a/packages/core/docs/development/bring-your-own-documentation/resource-docs/01-introduction.md b/packages/core/docs/development/bring-your-own-documentation/resource-docs/01-introduction.md
new file mode 100644
index 000000000..3ce82998a
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/resource-docs/01-introduction.md
@@ -0,0 +1,32 @@
+---
+sidebar_position: 1
+sidebar_label: Introduction
+title: Resource-level documentation
+description: Attach documentation pages to any resource in your catalog.
+keywords:
+  - EventCatalog resource-level documentation
+  - ADRs
+  - runbooks
+  - resource-level documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="3.15.0" />
+<PlanBanner plan="Scale" />
+
+Resource-level documentation lets you attach documentation pages directly to any resource in your catalog. Instead of keeping ADRs, runbooks, contracts, and guides in a separate tool, you can place them alongside the resource they describe.
+
+![](./img/docs.png)
+
+Attached docs appear in the resource sidebar, grouped by custom defined types, so readers can navigate between the resource overview and its supporting documentation without leaving the catalog.
+
+### Supported resources
+
+Resource-level documentation can be attached to any of the following resource types:
+
+- Domains and subdomains
+- Services
+- Events, Commands, Queries
+- Flows, Channels, Containers, Entities, Data products
diff --git a/packages/core/docs/development/bring-your-own-documentation/resource-docs/02-adding-resource-docs.md b/packages/core/docs/development/bring-your-own-documentation/resource-docs/02-adding-resource-docs.md
new file mode 100644
index 000000000..ec1e4925b
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/resource-docs/02-adding-resource-docs.md
@@ -0,0 +1,238 @@
+---
+sidebar_position: 2
+sidebar_label: Adding resource-level documentation
+title: Adding resource-level documentation
+description: Place MDX files in a docs/ directory alongside any resource.
+keywords:
+  - EventCatalog resource docs
+  - ADRs
+  - runbooks
+  - resource documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+<AddedIn version="3.15.0" />
+<PlanBanner plan="Scale" />
+
+## Adding resource-level documentation
+
+Place `.mdx` files inside a `docs/` directory under any resource. EventCatalog will automatically pick them up and display them in the resource's sidebar.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'docs',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: '01-deployment.mdx', highlight: true },
+                { name: '02-incident-response.mdx', highlight: true },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Frontmatter properties
+
+Each doc file supports the following frontmatter.
+
+| Property  | Required | Description                                      |
+|-----------|----------|--------------------------------------------------|
+| `title`   | No       | Display name of the doc. Defaults to the file name. |
+| `summary` | No       | Short description shown below the title.        |
+| `type`    | No       | Groups the doc in the sidebar. Defaults to the folder name, or `pages` if placed directly in `docs/`. |
+| `version` | No       | Doc version. Defaults to the resource version.  |
+| `order`   | No       | Explicit sort position within the group.        |
+| `badges`  | No       | Badges shown on the doc page.                   |
+
+
+#### Example of resource-level documentation
+
+```mdx title="services/OrdersService/docs/01-deployment.mdx"
+---
+title: Deployment runbook
+summary: Step-by-step guide for deploying the Orders service to production.
+version: 1.0.0
+---
+
+## Pre-deployment checklist
+
+1. Confirm staging tests pass.
+2. Notify the on-call engineer.
+...
+```
+
+### Order docs with numeric prefixes
+
+Files are sorted alphabetically by default. Prefix the file name with a number to control the order.
+
+<ProjectTree
+  items={[
+    {
+      name: 'docs',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        { name: '01-deployment.mdx', highlight: true },
+        { name: '02-incident-response.mdx', highlight: true },
+        { name: '03-disaster-recovery.mdx', highlight: true },
+      ],
+    },
+  ]}
+/>
+
+The numeric prefix is stripped from the doc's ID and URL, so `01-deployment.mdx` is accessible at `.../pages/deployment`.
+
+You can also set an explicit `order` value in frontmatter, which takes precedence over the numeric prefix.
+
+### Use with domains and subdomains
+
+Domains and subdomains follow the same pattern.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'E-Commerce',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'docs',
+              type: 'folder',
+              defaultOpen: true,
+              children: [{ name: '01-bounded-context.mdx', highlight: true }],
+            },
+            {
+              name: 'subdomains',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'Orders',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    { name: 'index.mdx' },
+                    {
+                      name: 'docs',
+                      type: 'folder',
+                      defaultOpen: true,
+                      children: [{ name: '01-order-processing.mdx', highlight: true }],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Navigate to a resource doc
+
+Resource docs are served at:
+
+```
+http://localhost:3000/docs/{resourceType}/{resourceId}/{version}/{docType}/{docId}
+```
+
+For example, `01-deployment.mdx` for `OrdersService` version `1.0.0` would be at:
+
+```
+http://localhost:3000/docs/services/OrdersService/1.0.0/pages/deployment
+```
+
+## Grouping docs by type
+
+Docs can be organised into groups using subdirectories inside `docs/`. Each subdirectory becomes a **doc type** and gets its own section in the resource sidebar.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'docs',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'adrs',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: '01-use-postgres.mdx', highlight: true }],
+                },
+                {
+                  name: 'runbooks',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    { name: '01-deployment.mdx', highlight: true },
+                    { name: '02-incident-response.mdx', highlight: true },
+                  ],
+                },
+                {
+                  name: 'guides',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'on-call.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The folder name is used as the group label by default. The built-in types `adrs`, `runbooks`, `contracts`, `troubleshooting`, and `guides` are automatically formatted with friendly labels in the sidebar.
+
+You can override the type for any doc using the `type` frontmatter field, regardless of which folder it lives in:
+
+```mdx title="services/OrdersService/docs/adrs/01-use-postgres.mdx"
+---
+title: Use PostgreSQL for order storage
+type: architecture-records
+---
+```
+
+The type resolution order is:
+
+1. `type` frontmatter — takes highest precedence
+2. Folder name — used when `type` is not set
+3. `pages` — fallback when the doc is placed directly in `docs/` with no subfolder
diff --git a/packages/core/docs/development/bring-your-own-documentation/resource-docs/03-categories.md b/packages/core/docs/development/bring-your-own-documentation/resource-docs/03-categories.md
new file mode 100644
index 000000000..5ca055f46
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/resource-docs/03-categories.md
@@ -0,0 +1,97 @@
+---
+sidebar_position: 3
+sidebar_label: Configure categories
+title: Configure categories
+description: Control sidebar labels and ordering for doc type groups using category files.
+keywords:
+  - EventCatalog resource docs categories
+  - category.json
+  - resource documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+<AddedIn version="2.x.0" />
+<PlanBanner plan="Scale" />
+
+When you group resource docs into subdirectories, each subdirectory becomes a section in the resource sidebar. By default, the section label is the folder name and sections are sorted alphabetically.
+
+**Categories** let you customise this — you can give a group a friendlier display label and control the order it appears relative to other groups, without renaming the folder.
+
+## Category files
+
+Place a `category.json` file inside any doc type folder to configure its sidebar label and position.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'docs',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'runbooks',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    { name: 'category.json', highlight: true },
+                    { name: '01-deployment.md' },
+                    { name: '02-incident-response.md' },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+```json title="services/OrdersService/docs/runbooks/category.json"
+{
+  "label": "Runbooks",
+  "position": 1
+}
+```
+
+### Category file properties
+
+| Property   | Required | Description                                                      |
+|------------|----------|------------------------------------------------------------------|
+| `label`    | No       | Display name for the doc type group in the sidebar.             |
+| `position` | No       | Sort order of the group relative to other doc type groups.      |
+
+### Use `_category_.json` as an alternative
+
+EventCatalog also accepts `_category_.json` as the file name. When both files exist in the same folder, `category.json` takes precedence.
+
+### Control group ordering
+
+Set `position` on each group to control the order they appear in the sidebar. Groups without a position are sorted alphabetically after positioned groups.
+
+```json title="docs/adrs/category.json"
+{
+  "label": "Architecture decisions",
+  "position": 1
+}
+```
+
+```json title="docs/runbooks/category.json"
+{
+  "label": "Runbooks",
+  "position": 2
+}
+```
diff --git a/packages/core/docs/development/bring-your-own-documentation/resource-docs/04-versioning.md b/packages/core/docs/development/bring-your-own-documentation/resource-docs/04-versioning.md
new file mode 100644
index 000000000..905dcc132
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/resource-docs/04-versioning.md
@@ -0,0 +1,94 @@
+---
+sidebar_position: 4
+sidebar_label: Version documents
+title: Version documents
+description: Keep historical versions of resource docs alongside versioned resources.
+keywords:
+  - EventCatalog resource docs versioning
+  - versioned documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+<AddedIn version="3.15.0" />
+<PlanBanner plan="Scale" />
+
+## How versioning works
+
+Resource docs are associated with a specific version of a resource. When you version a resource, the docs in that resource's `docs/` directory apply to the current (latest) version.
+
+Previous versions of a doc are stored inside the resource's `versioned/` directory, following the same pattern used for versioned resources.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'docs',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'runbooks',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: '01-deployment.md', highlight: true }],
+                },
+              ],
+            },
+            {
+              name: 'versioned',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '0.0.2',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    {
+                      name: 'docs',
+                      type: 'folder',
+                      defaultOpen: true,
+                      children: [
+                        {
+                          name: 'runbooks',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: '01-deployment.md', highlight: true }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Navigate between versions
+
+When a doc has multiple versions, a **Versions** panel is shown in the right-hand column of the doc page. You can use it to jump to any historical version of that document.
+
+A banner is shown at the top of older versions to make clear that a newer version exists.
+
+## Doc version vs resource version
+
+A doc file's `version` frontmatter field refers to the **doc's own version**, not the resource version. This allows a doc to be updated independently of the resource it belongs to.
+
+If `version` is omitted from frontmatter, EventCatalog infers it from the resource version the doc file lives under.
diff --git a/packages/core/docs/development/bring-your-own-documentation/resource-docs/_category_.json b/packages/core/docs/development/bring-your-own-documentation/resource-docs/_category_.json
new file mode 100644
index 000000000..2334c2b67
--- /dev/null
+++ b/packages/core/docs/development/bring-your-own-documentation/resource-docs/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Resource-level documentation",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "guides/bring-your-own-documentation/resource-docs",
+    "description": "Attach documentation pages directly to any resource in your catalog."
+  }
+}
diff --git a/packages/core/docs/development/components/04-snippets.md b/packages/core/docs/development/components/04-snippets.md
new file mode 100644
index 000000000..8ec03c77d
--- /dev/null
+++ b/packages/core/docs/development/components/04-snippets.md
@@ -0,0 +1,132 @@
+---
+sidebar_position: 6
+keywords:
+- snippets
+sidebar_label: Reusable snippets
+title: Reusable snippets
+description: Understanding how to use snippets with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Keep your documentation consistent and maintainable with reusable snippets.
+
+In EventCatalog, staying DRY (Don't Repeat Yourself) isn't just for code—it's for documentation too. If you're repeating the same content across multiple pages, consider using a snippet to centralize it. This makes your docs easier to manage and keeps everything in sync.
+
+## Creating a Snippet
+
+:::important
+Snippets must live in the `/snippets` directory to be recognized by EventCatalog. Files in this folder won’t generate standalone pages—they’re designed to be imported wherever needed.
+:::
+
+## Basic Usage
+
+1. Create your snippet
+
+```md title="snippets/my-snippet.mdx"
+Hello world! This is my content I want to reuse across pages. 
+```
+
+2. Import and use in any page:
+
+```markdown title="/domains/my-domain/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce
+version: 1.0.0
+---
+
+<!-- Import the snippet from the snippets directory -->
+import MySnippet from '@eventcatalog/snippets/my-snippet.mdx';
+
+<!-- Use the snippet anywhere on your page -->
+<MySnippet />
+
+```
+
+
+## Passing Variables to Snippets
+
+Snippets can accept props for dynamic content. Here's how:
+
+1. Create a snippet with props:
+
+```md title="snippets/my-snippet.mdx"
+Hello {props.name}! This is my content I want to reuse across pages. 
+```
+
+2. Import and use with props:
+
+```md title="/domains/my-domain/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce
+version: 1.0.0
+---
+
+<!-- Import the snippet from the snippets directory -->
+import MySnippet from '@eventcatalog/snippets/my-snippet.mdx';
+
+<!-- Use the snippet with props -->
+<MySnippet name="John" />
+
+```
+
+## Exporting Variables
+
+You can also export constants or objects from a snippet for use elsewhere.
+
+1. Export a variable from the snippet:
+
+```md title="snippets/my-snippet.mdx"
+export const platformName = 'EventCatalog';
+export const colors = { primary: '#000000' };
+```
+
+2. Import the variable in your page:
+
+```md title="/domains/my-domain/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce
+version: 1.0.0
+---
+
+<!-- Import the snippet from the snippets directory -->
+import { platformName, colors } from '/snippets/constants.mdx';
+
+<!-- Use the variable -->
+<p>Hello {platformName}!</p>
+<p>The primary color is {colors.primary}.</p>
+
+```
+
+## JSX-Based Snippets
+
+Need something more dynamic? Use a snippet as a JSX component:
+
+```md title="snippets/my-snippet.mdx"
+export default function MySnippet({ name }) {
+  return <div>Hello {name}!</div>;
+}
+```
+
+Then import and use it like this:
+
+```md title="/domains/my-domain/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce
+version: 1.0.0
+---
+
+<!-- Import the snippet from the snippets directory -->
+import MySnippet from '@eventcatalog/snippets/my-snippet.mdx';
+
+<!-- Use the snippet as a JSX component -->
+<MySnippet name="John" />
+
+```
+
+
+
diff --git a/packages/core/docs/development/components/05-using-components.md b/packages/core/docs/development/components/05-using-components.md
new file mode 100644
index 000000000..e9ae6f3ce
--- /dev/null
+++ b/packages/core/docs/development/components/05-using-components.md
@@ -0,0 +1,55 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Using components
+description: Understanding components
+---
+
+EventCatalog is powered by [Astro](https://astro.build/) and [MDX](https://mdxjs.com/). This gives you the flexibility to use [prebuilt components](/docs/components/list) or [create your own components](/docs/components/custom-components) for your documentation.
+
+### Using prebuild components
+
+EventCatalog comes with a range of prebuilt components, you can use these by adding them to the markdown content of any resource.
+
+This example renders an Accordion component within an event.
+
+```md title="/events/Orders/OrderAmended/index.mdx"
+---
+id: OrderAmended
+name: Order amended
+version: 0.0.1
+summary: |
+  Indicates an order has been changed
+owners:
+    - dboyne
+    - msmith
+badges:
+    - content: Recently updated!
+      backgroundColor: green
+      textColor: green
+    - content: Channel:Apache Kafka
+      backgroundColor: yellow
+      textColor: yellow
+---
+
+## Overview
+
+Event is raised when an order has been changed.
+
+<Accordion title="Learn how to raise this event">
+  You can run the following command to raise this event.
+
+  ```sh
+  bin/kafka-topics.sh --create --topic OrderAmended --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1
+  ``
+</Accordion>
+
+```
+
+
+![Example](./img/accordian.png)
+
+
+
diff --git a/packages/core/docs/development/components/07-resource-references.md b/packages/core/docs/development/components/07-resource-references.md
new file mode 100644
index 000000000..012a74b5e
--- /dev/null
+++ b/packages/core/docs/development/components/07-resource-references.md
@@ -0,0 +1,136 @@
+---
+sidebar_position: 5
+keywords:
+- resource references
+- links
+- cross-references
+sidebar_label: Resource references
+title: Resource references
+description: Create inline links to resources with hover tooltips
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.6.1" />
+
+Create inline references to resources in your documentation using wiki-style syntax. References render as styled links with interactive tooltips showing resource details.
+
+<div className="flex justify-center flex-col items-center gap-4">
+  <img src="/img/resource-link.png" alt="Resource link example" className="rounded-lg"  />
+  <a href="https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.1" target="_blank" class="block text-xs w-full text-center">See in EventCatalog demo &rarr;</a>
+</div>
+
+## Basic syntax
+
+Use double square brackets to create a resource reference.
+
+```md
+[[type|ResourceName]]
+```
+
+The reference automatically links to the resource and displays a tooltip on hover showing key information like version, summary, and related resources.
+
+### Example
+
+```md
+---
+id: OrdersService
+name: Orders Service
+version: 0.0.1
+summary: |
+  Handles all order processing
+owners:
+  - dboyne
+  - msmith
+---
+
+The [[service|OrdersService]] handles all order processing and will publish the event [[event|OrderCreated]] when an order is created.
+```
+
+This creates a link to the OrdersService with a tooltip showing service details, published messages, API specifications, and owners.
+
+## Supported resource types
+
+Reference any resource type in your catalog.
+
+| Type | Syntax | Links to |
+|------|--------|----------|
+| Service | `[[service\|OrdersService]]` | Service documentation |
+| Event | `[[event\|OrderCreated]]` | Event documentation |
+| Command | `[[command\|CreateOrder]]` | Command documentation |
+| Query | `[[query\|GetOrderStatus]]` | Query documentation |
+| Domain | `[[domain\|E-Commerce]]` | Domain documentation |
+| Flow | `[[flow\|PaymentFlow]]` | Flow documentation |
+| Channel | `[[channel\|OrderChannel]]` | Channel documentation |
+| Entity | `[[entity\|Order]]` or `[[Order]]` | Entity documentation |
+| Diagram | `[[diagram\|target-architecture]]` | Diagram page |
+| Container | `[[container\|APIGateway]]` | Container documentation |
+| User | `[[user\|dboyne]]` | User profile |
+| Team | `[[team\|backend-team]]` | Team profile |
+| Custom doc | `[[doc\|guides/getting-started]]` | Custom documentation page |
+
+### Reference custom docs
+
+Link to pages in your [custom documentation](/docs/development/bring-your-own-documentation/custom-pages/introduction) using path-based identifiers.
+
+```md
+[[doc|guides/getting-started]]
+[[doc|operations-and-support/runbooks/payment-service-runbook]]
+```
+
+The path matches the file location inside your `docs/` directory, relative to the catalog root. Paths are case-insensitive and leading `/docs/custom/` prefixes are stripped automatically.
+
+Doc references do not support version pinning since custom documentation pages are not versioned.
+
+### Default to entity
+
+Reference entities without specifying the type.
+
+```md
+The [[Customer]] entity stores user information.
+```
+
+This defaults to entity type and is equivalent to `[[entity|Customer]]`.
+
+## Version pinning
+
+Reference a specific version of a resource.
+
+```md
+[[service|OrdersService@1.0.0]]
+```
+
+Without a version, the reference uses the latest version. Pin versions when documenting specific implementations or historical states.
+
+### Example
+
+```md
+Our legacy [[service|PaymentService@0.9.0]] is being replaced by [[service|PaymentGatewayService]].
+```
+
+## Interactive tooltips
+
+Hover over any reference to see detailed information without leaving the page.
+
+<div className="flex justify-center flex-col items-center gap-4">
+  <img src="/img/resource-link.png" alt="Resource link example" className="rounded-lg"  />
+  <a href="https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.1" target="_blank" class="block text-xs w-full text-center">See in EventCatalog demo &rarr;</a>
+</div>
+
+Tooltips show different information based on resource type.
+
+### Combine with other components
+
+Mix references with other EventCatalog components.
+
+```md
+## Architecture
+
+The [[service|OrdersService]] coordinates between inventory and payment:
+
+<NodeGraph id="OrdersService" version="latest" type="service" />
+```
+
+### Review references regularly
+
+Regularly audit references to ensure they point to current resources and remove outdated links.
diff --git a/packages/core/docs/development/components/_category_.json b/packages/core/docs/development/components/_category_.json
new file mode 100644
index 000000000..5c3dbb260
--- /dev/null
+++ b/packages/core/docs/development/components/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Components",
+  "position": 7,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "components",
+    "title": "Components",
+    "description": "Use MDX components, diagram syntax, and external embeds in EventCatalog documentation."
+  }
+}
diff --git a/packages/core/docs/development/components/components/01-accordian.md b/packages/core/docs/development/components/components/01-accordian.md
new file mode 100644
index 000000000..a8ca7d127
--- /dev/null
+++ b/packages/core/docs/development/components/components/01-accordian.md
@@ -0,0 +1,41 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Accordion
+title: Accordion
+description: Component for EventCatalog
+---
+
+The accordion component renders collapsable section in EventCatalog.
+
+```jsx /events/OrderAmended/index.mdx
+<Accordion title="Learn how to raise this event">
+    This will be rendered as a child inside a collapsible section.
+</Accordion>
+```
+**Example with code as child**
+
+```jsx /events/OrderAmended/index.mdx
+<Accordion title="Learn how to raise this event">
+  You can run the following command to raise this event.
+
+  ```sh
+  bin/kafka-topics.sh --create --topic OrderAmended --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1
+  ``
+</Accordion>
+```
+
+### Output
+
+![Example output](./img/accordian.png)
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `title` (required)                 | `string`  | (empty)           | Title to render in your accordion block                              |
+| `children`             | `string`  | (empty)           | Content that goes inside your accordion|
+
+### Support
+
+The `<Accordion/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/02-accordian-group.md b/packages/core/docs/development/components/components/02-accordian-group.md
new file mode 100644
index 000000000..84a35f581
--- /dev/null
+++ b/packages/core/docs/development/components/components/02-accordian-group.md
@@ -0,0 +1,57 @@
+---
+sidebar_position: 2
+keywords:
+- components
+sidebar_label: AccordionGroup
+title: AccordionGroup
+description: Component for EventCatalog
+---
+
+The accordion group component renders a collection of accordions.
+
+**Basic Example**
+
+```jsx /events/OrderAmended/index.mdx
+<AccordionGroup>
+  <Accordion title="Example 1">Hello</Accordion>
+  <Accordion title="Example 2">Hello this is an example</Accordion>
+  <Accordion title="Example 3">Another example</Accordion>
+  <Accordion title="Example 4">Final example</Accordion>
+</AccordionGroup>
+```
+
+**Code example**
+
+Add code inside the Accordion to render code snippets.
+
+```jsx /events/OrderAmended/index.mdx
+<AccordionGroup>
+  <Accordion title="Code snippet 1">
+    ```js
+    console.log('My code here');
+    ``
+  </Accordion>
+  <Accordion title="Code snippet 2">
+  ```js
+    console.log('My other code snippet');
+  ``
+  </Accordion>
+  <Accordion title="Schema example">
+  ```json
+  { "test": true}
+  ``
+  </Accordion>
+</AccordionGroup>
+```
+
+### Output
+![Example output](./img/accordiangroup.png)
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `children`             | `Accordion`  | (empty)           | Accordion components that are contained within the group|
+
+### Support
+
+The `<AccordionGroup/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/03-admonitions.md b/packages/core/docs/development/components/components/03-admonitions.md
new file mode 100644
index 000000000..b52df15ea
--- /dev/null
+++ b/packages/core/docs/development/components/components/03-admonitions.md
@@ -0,0 +1,43 @@
+---
+sidebar_position: 3
+keywords:
+- components
+sidebar_label: Admonitions
+title: Admonitions
+description: Component for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.16.6"/>
+
+The admonitions syntax is used to render a block of text with a specific style. You can use it to highlight important information, warnings, or other types of content.
+
+**Basic Example**
+
+```md /events/OrderAmended/index.mdx
+:::note
+Some content with _Markdown_ syntax. Check [this api](https://eventcatalog.dev/).
+:::
+
+:::tip
+Some content with _Markdown_ syntax. Check [this api](https://eventcatalog.dev/).
+:::
+
+:::warning
+Some content with _Markdown_ syntax. Check [this api](https://eventcatalog.dev/).
+:::
+
+:::danger
+Some content with _Markdown_ syntax. Check [this api](https://eventcatalog.dev/).
+:::
+
+```
+
+
+### Output
+![Example output](./img/admonitions.png)
+
+### Support
+
+The markdown syntax is supported in all pages in EventCatalog.
diff --git a/packages/core/docs/development/components/components/04-agent-tools.md b/packages/core/docs/development/components/components/04-agent-tools.md
new file mode 100644
index 000000000..fe8e9da42
--- /dev/null
+++ b/packages/core/docs/development/components/components/04-agent-tools.md
@@ -0,0 +1,43 @@
+---
+sidebar_position: 4
+keywords:
+- components
+- agents
+- agent tools
+sidebar_label: AgentTools
+title: AgentTools
+description: Component for displaying the tools an agent can call in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+The `<AgentTools/>` component renders a table of the tools an agent can call (MCP servers, REST APIs, internal search indexes, databases, and so on).
+
+The component reads the `tools` array from the current agent's frontmatter, so it requires no props.
+
+### Use case
+
+- Display all the external capabilities an agent reaches out to at runtime.
+- Show MCP server endpoints, REST APIs, and other integrations on the agent page.
+
+**Basic Example**
+
+```jsx /agents/OrderSupportAgent/index.mdx
+<AgentTools />
+```
+
+### Output
+
+![Example output](./img/agent-tools.png)
+
+### Props
+
+The `<AgentTools/>` component takes no props — it reads the `tools` array from the current agent's frontmatter.
+
+For details on the `tools` frontmatter shape, see [Agent tools](/docs/development/guides/resources/agents/adding-tools).
+
+### Support
+
+The `<AgentTools/>` component is supported in agent pages only. If you add it to a service, message, or domain page, the catalog will display a warning and skip the table.
diff --git a/packages/core/docs/development/components/components/05-attachments.md b/packages/core/docs/development/components/components/05-attachments.md
new file mode 100644
index 000000000..b7f232788
--- /dev/null
+++ b/packages/core/docs/development/components/components/05-attachments.md
@@ -0,0 +1,56 @@
+---
+sidebar_position: 5
+keywords:
+- attachments
+- documentation
+- ADR
+- diagrams
+sidebar_label: Attachments
+title: Attachments
+description: Learn how to add attachments to your EventCatalog resources
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.57.2" />
+
+The Attachments component allows you to link related documents, diagrams, and resources to any EventCatalog resource. This is perfect for connecting Architecture Decision Records (ADRs), design documents, external diagrams, or any other relevant documentation.
+
+Attachments can be a url (string) or an object with additional properties.
+
+Here we have a domain with two attachments, one is a simple url and the other is an object with additional properties.
+
+```md title="domains/E-Commerce/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce Domain
+attachments:
+  - https://example.com/adr/001-microservices-architecture
+  - url: https://example.com/adr/001
+    title: ADR-001 - Use Kafka for asynchronous messaging
+    description: Learn more about why we chose Kafka for asynchronous messaging in this architecture decision record.
+    type: 'architecture-decisions'
+    icon: FileTextIcon
+---
+
+## Domain Overview
+
+This domain handles all e-commerce operations.
+
+<Attachments />
+
+```
+
+### Output
+
+![Example output](./img/attachments.png)
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `title` (optional)                 | `string`  | (empty)           | Title to render in your attachments block                             |
+| `description` (optional)             | `string`  | (empty)           | Any additional description to render in your attachments block|
+
+## Support
+
+The `<Attachments />` component is supported in all EventCatalog resources, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/06-channel-information.md b/packages/core/docs/development/components/components/06-channel-information.md
new file mode 100644
index 000000000..46a481c92
--- /dev/null
+++ b/packages/core/docs/development/components/components/06-channel-information.md
@@ -0,0 +1,29 @@
+---
+sidebar_position: 6
+keywords:
+  - components
+sidebar_label: ChannelInformation
+title: ChannelInformation
+description: Render channel into EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.13.0"/>
+
+The ChannelInformation component is a EventCatalog component that will render a table into your markdown page that contains information about the Channel. 
+
+**Example**
+
+```jsx /services/MyService/index.mdx
+<ChannelInformation />
+```
+
+### Output
+![Example output](./img/channel.png)
+
+See example in the [demo EventCatalog application](https://demo.eventcatalog.dev/docs/channels/inventory.%7Benv%7D.events/1.0.0).
+
+### Support
+
+The `<ChannelInformation/>` component is supported in channels.
diff --git a/packages/core/docs/development/components/components/07-design.md b/packages/core/docs/development/components/components/07-design.md
new file mode 100644
index 000000000..9d7f17b24
--- /dev/null
+++ b/packages/core/docs/development/components/components/07-design.md
@@ -0,0 +1,65 @@
+---
+sidebar_position: 7
+keywords:
+- components
+- remote schema
+- fetch
+- runtime
+sidebar_label: Design
+title: Design
+description: Component for embedding EventCatalog Studio diagrams into your documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.56.0" />
+
+The **Design** component is a EventCatalog component that will render a [EventCatalog Studio diagram](https://eventcatalog.studio) into your markdown page.
+
+## Interactive controls
+
+<AddedIn version="3.9.0" />
+
+Design visualizations include the same interactive controls as NodeGraph components.
+
+Switch between React Flow and Mermaid view modes, export as Mermaid diagram code, or share URLs with your team.
+
+[Read more about interactive controls](/docs/development/components/components/nodegraph#interactive-controls)
+
+Design visualizations also support [layout persistence](/docs/development/components/components/nodegraph#layout-persistence) in dev mode, allowing you to save custom node positions.
+
+### Usage
+
+**Basic Example**
+
+```jsx /events/MyEvent/index.mdx
+<Design file="event-stream-example" search={false} />
+```
+
+**With Custom Title and Height**
+
+```jsx /events/MyEvent/index.mdx
+<Design
+  file="event-stream-example"
+  title="Event Stream Example"
+  maxHeight="600"
+/>
+```
+
+### Output
+When you use the `<Design />` component, it will render the diagram in your EventCatalog page.
+
+![Example output](/img/embed-ec.png)
+
+### Props
+
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `file` (required)        | `string`  | (empty)           | The `.ecstudio` file to load into the diagram block. Path is resolved by EventCatalog. |
+| `title` (optional)      | `string`  | "Remote Schema"   | Title to display above the diagram                                 |
+| `maxHeight` (optional)  | `string`  | "400"             | Maximum height of the diagram in pixels                    |
+| `search` (optional)    | `boolean`  | `false`              | Show or hide the search bar in the diagram |
+
+### Support
+
+The `<Design/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/08-entitymap.md b/packages/core/docs/development/components/components/08-entitymap.md
new file mode 100644
index 000000000..d6ddcdaef
--- /dev/null
+++ b/packages/core/docs/development/components/components/08-entitymap.md
@@ -0,0 +1,71 @@
+---
+sidebar_position: 8
+keywords:
+- components
+sidebar_label: EntityMap
+title: EntityMap
+description: Component for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.49.0" />
+
+A component to visually render a domain's entity map.
+
+The `<EntityMap/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
+
+:::info
+To visualize entities [you need to create entities in EventCatalog](/docs/development/guides/resources/entities/introduction) and assign them to your services or domains.
+:::
+
+## Interactive controls
+
+<AddedIn version="3.9.0" />
+
+Entity map visualizations include the same interactive controls as NodeGraph components.
+
+Switch between React Flow and Mermaid view modes, export as Mermaid diagram code, or share URLs with your team.
+
+[Read more about interactive controls](/docs/development/components/components/nodegraph#interactive-controls)
+
+Entity maps also support [layout persistence](/docs/development/components/components/nodegraph#layout-persistence) in dev mode, allowing you to save custom node positions.
+
+## Usage
+
+**Example**
+
+```jsx /domains/OrdersDomain/index.mdx
+<EntityMap title="Orders Domain Entity Map" />
+```
+
+#### Output
+![Example output](./img/entity-map.png)
+
+#### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `id` (optional)             | `string`  | -          | The id of the domain or service entity map to render. By default the component will use the id of the current page. If you want to embed this component into custom documentation pages, you can use the `id` prop to specify the id of the domain or service to render. |
+| `version` (optional)             | `string`  | -          | The version of the domain or service to render. By default the component will use the version of the current page. If you want to embed this component into custom documentation pages, you can use the `version` prop to specify the version of the domain or service to render. |
+| `title` (optional)             | `string`  | -          | The title of the entity map to render. |
+| `maxHeight` (optional)             | `string`  | 30           | Max height to set the nodegraph in your document. |
+| `includeKey` (optional)             | `boolean`  | true           | Show or hide the legend. |
+| `entities` (optional)             | `array`  | []           | Array of entities (ids or names) to filter in the map. Useful if you want to render a subset of the entities in the map. (Added in v2.51.1). [Read more about filtering](#filter-entities) |
+
+#### Filter Entities
+
+<AddedIn version="2.51.1" />
+
+The `<EntityMap/>` component will render all entities by default for a given domain.
+
+If you want to render a subset of the entities in the map, you can use the `entities` prop.
+
+**Example**
+
+```jsx /events/MyEvents/index.mdx
+<EntityMap id="OrdersDomain" title="Orders Domain Entity Map" entities={["Order", "Customer"]} />
+```
+
+In this example, only the `Order` and `Customer` entities will be chosen to be rendered in the map.
+
+If the `Order` or `Customer` entity references other entities, they will also be rendered in the map
\ No newline at end of file
diff --git a/packages/core/docs/development/components/components/09-flow.md b/packages/core/docs/development/components/components/09-flow.md
new file mode 100644
index 000000000..f1de1f97b
--- /dev/null
+++ b/packages/core/docs/development/components/components/09-flow.md
@@ -0,0 +1,55 @@
+---
+sidebar_position: 9
+keywords:
+- components
+sidebar_label: Flow
+title: Flow
+description: Render a Flow in any EventCatalog page
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Embed flows into your pages.
+
+**Example**
+
+```jsx /domains/MyDomain/index.mdx
+<Flow id="CancelSubscription" version="latest" legend={false} />
+```
+
+### Output
+![Example output](./img/flows.png)
+
+### Props
+
+<AddedIn version="3.36.3" />
+
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `id` (required)                 | `string`  | (empty)           | Flow id to render in your page                               |
+| `version` (optional)             | `string`  | `"latest"`           | Version of the flow to render. Supports exact version and semver versions (e.g 1.0.x, ^1.3.5, latest)|
+| `legend` (optional)             | `boolean`  | `true`           | Show or hide the diagram key. Accepts `true`/`false` or `"true"`/`"false"`. `includeKey` is still accepted as an alias. |
+| `search` (optional)             | `boolean`  | `false`           | Show or hide the search bar in the flow. Accepts `true`/`false` or `"true"`/`"false"`. |
+| `walkthrough` (optional)             | `boolean`  | `false`           | Show or hide the step walkthrough controls. Accepts `true`/`false` or `"true"`/`"false"`. |
+| `mode` (optional)             | `string` ("simple" or "full")  | `"simple"`           | `simple` renders the flow in a simplified view without descriptions. `full` renders descriptions and other information.|
+
+:::tip Multiple embeds per page
+You can embed multiple `<Flow />` components on the same page and each one renders independently.
+:::
+
+
+## Interactive controls
+
+<AddedIn version="3.9.0" />
+
+Flow visualizations include the same interactive controls as NodeGraph components.
+
+Switch between React Flow and Mermaid view modes, export as Mermaid diagram code, or share URLs with your team.
+
+[Read more about interactive controls](/docs/development/components/components/nodegraph#interactive-controls)
+
+Flow visualizations also support [layout persistence](/docs/development/components/components/nodegraph#layout-persistence) in dev mode, allowing you to save custom node positions.
+
+### Support
+
+The `<Flow/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/10-link.md b/packages/core/docs/development/components/components/10-link.md
new file mode 100644
index 000000000..adfafa135
--- /dev/null
+++ b/packages/core/docs/development/components/components/10-link.md
@@ -0,0 +1,32 @@
+---
+sidebar_position: 10
+keywords:
+- components
+sidebar_label: Link
+title: Link
+description: Create links in your documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.32.3" />
+
+The `<Link/>` component renders a link to a resource in EventCatalog.
+
+EventCatalog handles links depending on your configuration file (e.g trailing slashes, etc), using this component creates links that are consistent with your EventCatalog configuration.
+
+**Basic Example**
+
+```jsx /domains/MyDomain/index.mdx
+<Link href="/my/awesome/page">My Awesome Page</Link>
+
+```
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `href`             | `string`  | none           | The href of the link. |
+
+### Support
+
+The `<Link/>` component is supported on all EventCatalog pages.
diff --git a/packages/core/docs/development/components/components/11-mermaid-file-loader.md b/packages/core/docs/development/components/components/11-mermaid-file-loader.md
new file mode 100644
index 000000000..f48b53d67
--- /dev/null
+++ b/packages/core/docs/development/components/components/11-mermaid-file-loader.md
@@ -0,0 +1,63 @@
+---
+sidebar_position: 11
+keywords:
+- components
+- remote schema
+- fetch
+- runtime
+sidebar_label: MermaidFileLoader
+title: MermaidFileLoader
+description: Component for embedding EventCatalog Studio diagrams into your documentation
+---
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<AddedIn version="2.56.4" />
+
+The **MermaidFileLoader** component is a EventCatalog component that will render a [Mermaid](https://mermaid.js.org/) file into your markdown page.
+
+**Basic Example**
+
+<Tabs>
+  <TabItem value="Markdown file" label="Markdown file" default>
+    
+```jsx /events/MyEvent/index.mdx
+<MermaidFileLoader file="mermaid.mmd" />
+```
+  </TabItem>
+  <TabItem value="Mermaid file (.mmd or .mermaid)" label="Mermaid file (.mmd or .mermaid)">
+    ```
+  sequenceDiagram
+      participant Customer
+      participant OrdersService
+      participant InventoryService
+      participant NotificationService
+
+      Customer->>OrdersService: Place Order
+      OrdersService->>InventoryService: Check Inventory
+      InventoryService-->>OrdersService: Inventory Available
+      OrdersService->>InventoryService: Reserve Inventory
+      OrdersService->>NotificationService: Send Order Confirmation
+      NotificationService-->>Customer: Order Confirmation
+      OrdersService->>Customer: Order Placed Successfully
+      OrdersService->>InventoryService: Update Inventory
+    ```
+  </TabItem>
+</Tabs>
+
+### Output
+When you use the `<MermaidFileLoader />` component, it will render the diagram in your EventCatalog page.
+
+![Example output](./img/mermaid.png)
+
+### Props
+
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `file` (required)        | `string`  | (empty)           | The `.mmd` or `.mermaid` file to load into the diagram block. Path is resolved by EventCatalog. |
+
+### Support
+
+The `<MermaidFileLoader/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/12-message-table.md b/packages/core/docs/development/components/components/12-message-table.md
new file mode 100644
index 000000000..53d67e9d9
--- /dev/null
+++ b/packages/core/docs/development/components/components/12-message-table.md
@@ -0,0 +1,43 @@
+---
+sidebar_position: 12
+keywords:
+- components
+sidebar_label: MessageTable
+title: MessageTable
+description: Component for displaying messages for services and domains in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.26.0" />
+
+The `<MessageTable/>` component renders a table of messages for a service or domain in EventCatalog.
+
+The component renders a paginated table of messages, with the ability to filter by message type (event, command, query), and text search.
+
+### Use case
+
+- Display all the messages that a service sends and receives.
+- Display all the messages that a domain sends and receives.
+  - These are all messages that are sent and received in child services of the domain.
+
+**Basic Example**
+
+```jsx /domains/MyDomain/index.mdx
+<MessageTable limit={10} showChannels={true} />
+```
+### Output
+![Example output](./img/message-table.png)
+
+See the [demo](https://demo.eventcatalog.dev/docs/domains/Orders/0.0.3) for a full example.
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `format`                  | `string`  | 'all'           | Which messages to render. `all` will render messages that are sent and received. `sends` will render messages that are sent and `receives` will render messages that are received.                               |
+| `limit`             | `number`  | 10           | The number of messages to render in the table. Results are paginated. |
+| `showChannels`             | `boolean`  | true           | Whether to show the channel information in the table for each message. |
+
+### Support
+
+The `<MessageTable/>` component is supported in domains and services.
diff --git a/packages/core/docs/development/components/components/13-nodegraph.md b/packages/core/docs/development/components/components/13-nodegraph.md
new file mode 100644
index 000000000..7d9fbfc9a
--- /dev/null
+++ b/packages/core/docs/development/components/components/13-nodegraph.md
@@ -0,0 +1,170 @@
+---
+sidebar_position: 13
+keywords:
+- components
+sidebar_label: NodeGraph
+title: NodeGraph
+description: Component for EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+A component to visually render your information.
+
+The `<NodeGraph/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
+
+### Single NodeGraph
+
+**Example**
+
+```jsx /events/MyEvents/index.mdx
+<NodeGraph/>
+```
+
+#### Output
+![Example output](./img/nodegraph.png)
+
+#### Props
+
+<AddedIn version="3.36.3" />
+
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `maxHeight` (optional)             | `string`  | `30`           | Max height to set the nodegraph in your document|
+| `search` (optional)             | `boolean`  | `true`           | Show or hide the search bar. Accepts `true`/`false` or `"true"`/`"false"`. |
+| `legend` (optional)             | `boolean`  | `true`           | Show or hide the legend. Accepts `true`/`false` or `"true"`/`"false"`. |
+| `mode` (optional)             | `string` ("simple" or "full")  | `"simple"`           | `simple` renders a simplified view without descriptions. `full` renders descriptions and other information.|
+
+
+## Interactive controls
+
+<AddedIn version="3.9.0" />
+
+All NodeGraph visualizations include interactive controls for better viewing, exploration, and sharing.
+
+![NodeGraph interactive controls](./img/interactive-controls.png)
+
+### View modes
+
+Switch between two visualization modes using the view switcher dropdown.
+
+**React Flow** - Interactive node-based visualization with drag and pan controls.
+
+**Mermaid** - Standard Mermaid diagram view with automatic layout and pan/zoom controls.
+
+### Export as Mermaid
+
+Copy the NodeGraph as Mermaid diagram code to your clipboard. The diagram preserves all nodes, edges, and styling information.
+
+Useful for sharing architectures with LLMs, documentation tools, or pasting into Mermaid-compatible renderers like [mermaid.live](https://mermaid.live).
+
+:::tip Large diagram exports
+If you export large NodeGraphs and they fail to render as Mermaid diagrams, increase the `maxTextSize` configuration. [Learn more about maxTextSize](/docs/api/config#mermaid).
+:::
+
+### Share URL
+
+Copy the current page URL to share the visualization with your team.
+
+## Layout persistence
+
+<AddedIn version="3.11.0" />
+
+Save and restore custom node positions in the visualizer during development.
+
+When you drag nodes to arrange your visualization, a "Layout changed" indicator appears with a quick save button. Layouts are saved to `_data/visualizer-layouts/` as JSON files and can be committed to git to share with your team.
+
+:::info Dev mode only
+Layout persistence is only available when running EventCatalog in development mode (`npm run start`). This ensures saved layouts don't affect production builds.
+:::
+
+### Saving layouts
+
+Drag any node to reposition it. When changes are detected, the "Layout changed" indicator appears in the bottom-left corner with a quick save button.
+
+You can also save layouts from the dropdown menu:
+
+1. Click the menu icon (three dots) in the top-right corner
+2. Select **Layout** > **Save Layout**
+
+Layouts are saved to `_data/visualizer-layouts/{collection}/{id}/{version}.json` in your catalog directory.
+
+### Resetting layouts
+
+Reset a saved layout to return to auto-positioning:
+
+1. Click the menu icon (three dots) in the top-right corner
+2. Select **Layout** > **Reset Layout**
+3. Confirm the reset
+
+This deletes the saved layout file and reloads the page with auto-calculated positions.
+
+### Layout files
+
+Layout files are keyed by resource (collection/id/version), so the same layout is used whether viewing in the visualizer or embedded in documentation.
+
+Works across all visualizers including services, events, flows, domains, entity maps, and designs.
+
+**Example layout file structure:**
+
+```json
+{
+  "version": 1,
+  "savedAt": "2026-01-29T12:00:00.000Z",
+  "resourceKey": "services/OrderService/1.0.0",
+  "positions": {
+    "node-1": { "x": 100, "y": 200 },
+    "node-2": { "x": 300, "y": 400 }
+  }
+}
+```
+
+### Sharing layouts with your team
+
+Saved layouts can be committed to git and shared with your team. When team members pull the changes, they'll see the same node positions in their local development environment.
+
+Add the layout directory to your git repository:
+
+```bash
+git add _data/visualizer-layouts
+git commit -m "Add custom visualizer layouts"
+```
+
+
+### Multiple NodeGraphs
+
+<AddedIn version="2.37.3" />
+
+You can add multiple NodeGraphs to your document by using the `NodeGraph` component multiple times.
+
+Here is an example of how to add multiple NodeGraphs to your document:
+
+```jsx /events/MyEvents/index.mdx
+<!-- Without any properties, this will render the current pages NodeGraph like you see in the above example -->
+<NodeGraph/>
+
+<!--  -->
+<div class="grid grid-cols-2 gap-4 not-prose">
+  <!-- We tell EventCatalog to render the Orders Domain version 0.0.3 NodeGraph -->
+  <NodeGraph id="Orders" version="0.0.3" type="domain" />
+  <!-- We tell EventCatalog to render the Subscription Domain version 0.0.1 NodeGraph -->
+  <NodeGraph id="Subscription" version="0.0.1" type="domain" />
+</div>
+```
+
+#### Output
+![Example output](./img/multi-nodegraph.png)
+
+You can see a demo of this [here](https://demo.eventcatalog.dev/docs/domains/E-Commerce/1.0.0)
+
+#### Props
+
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `id`                    | `string`  | `undefined`       | The id of the NodeGraph to render. If not provided, the current page's NodeGraph will be rendered. |
+| `version`               | `string`  | `undefined`       | The version of the NodeGraph to render. If not provided, the current page's NodeGraph will be rendered. |
+| `type`                  | `string`  | `undefined`       | The type of the NodeGraph to render. If not provided, the current page's NodeGraph will be rendered. |
+
+
+
+
diff --git a/packages/core/docs/development/components/components/14-openapi.md b/packages/core/docs/development/components/components/14-openapi.md
new file mode 100644
index 000000000..53faf85eb
--- /dev/null
+++ b/packages/core/docs/development/components/components/14-openapi.md
@@ -0,0 +1,55 @@
+---
+sidebar_position: 14
+keywords:
+- components
+sidebar_label: OpenAPI
+title: OpenAPI
+description: Component for EventCatalog
+---
+
+
+:::warning
+This component is now deprecated. Please read the frontmatter API documentation [here](/docs/development/guides/resources/schemas/add-specifications-to-services/add-openapi-specifications).
+:::
+
+You can add specifications to any service in EventCatalog using the specifications frontmatter API. You can read more about it [here](/docs/development/guides/resources/schemas/add-specifications-to-services/add-openapi-specifications).
+
+If you are interested in automating your EventCatalog with OpenAPI files, you can use the [OpenAPI plugin](/docs/plugins/openapi/intro).
+
+<!-- A component to render [OpenAPI specification files](https://swagger.io/specification/) into EventCatalog.
+
+:::tip
+ OpenAPI files can be great for your services. Remember you can version your services and all files that associate with it. This allows you to version your OpenAPI files with EventCatalog.
+:::
+
+### Usage
+
+1. Add your `openapi.yml` file to your folder
+    - e.g `/events/MyEvent/openapi.yml`
+
+When you include the component three things happen:
+
+- You get a section in your document with a link to the spec file
+- A button is rendered in the sidebar for the document
+- A new page is rendered loading the OpenAPI file.
+
+**Example**
+
+```jsx /events/MyEvents/index.mdx
+<OpenAPI/>
+```
+
+### Output
+![Example output](./img/openapi.png)
+
+**New page that is created for your OpenAPI spec**
+
+![Example openapi page](./img/openapi-page.png)
+
+### Props
+
+_No configuration required._ -->
+
+### Support
+
+The `<OpenAPI/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/15-prompt.md b/packages/core/docs/development/components/components/15-prompt.md
new file mode 100644
index 000000000..68c8ae64a
--- /dev/null
+++ b/packages/core/docs/development/components/components/15-prompt.md
@@ -0,0 +1,69 @@
+---
+sidebar_position: 15
+keywords:
+  - components
+  - prompt
+  - ai
+  - cursor
+  - clipboard
+sidebar_label: Prompt
+title: Prompt
+description: Embed copyable AI prompts into resource documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.32.2" />
+
+`<Prompt />` lets you embed ready-to-use AI prompts directly in your documentation pages. Readers can copy the prompt to their clipboard or open it straight in Cursor with one click.
+
+Place the prompt text as the slot content and configure the label and actions via props.
+
+**Copy only (default)**
+
+```jsx /events/OrderCreated/index.mdx
+<Prompt description="Generate test cases for this event">
+  You are a senior QA engineer. Review the OrderCreated event schema above and write
+  Jest test cases that cover the happy path and the top three failure modes.
+</Prompt>
+```
+
+**Copy and open in Cursor**
+
+```jsx /services/OrdersService/index.mdx
+<Prompt
+  description="Generate Gherkin scenarios for this service"
+  actions={["copy", "cursor"]}
+  icon="sparkles"
+>
+  You are a senior QA engineer. Read the attached service documentation and produce
+  Gherkin Given/When/Then scenarios covering the happy path and the top three failure modes.
+</Prompt>
+```
+
+### Output
+![Example output](./img/prompt.png)
+
+### Props
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `description` (required) | `string` | — | Short label shown to the reader, e.g. "Generate test cases for this event". |
+| `actions` (optional) | `('copy' \| 'cursor')[]` | `['copy']` | Buttons to render. `'copy'` adds a clipboard button; `'cursor'` adds an "Open in Cursor" deep-link button. |
+| `icon` (optional) | `string` | — | Lucide icon name to display beside the description. Accepts kebab-case, snake_case, or space-separated input (e.g. `"sparkles"`, `"bot-message-square"`). |
+
+### Understand the actions
+
+Use `actions={["copy"]}` (the default) when you only need clipboard support. Add `"cursor"` to the array when your team works in Cursor and you want a one-click "Open in Cursor" button that pre-fills the prompt.
+
+Both actions derive their text from the slot content. HTML tags are stripped automatically, so plain text is always passed to the clipboard and the Cursor deep-link.
+
+### Use the icon prop
+
+Pass any [Lucide](https://lucide.dev/icons/) icon name to the `icon` prop. The component normalises the value to PascalCase internally, so `"bot-message-square"`, `"bot_message_square"`, and `"Bot Message Square"` all resolve to the same icon.
+
+If the icon name is not found in the Lucide library, no icon is rendered and no error is thrown.
+
+### Support
+
+The `<Prompt />` component is supported in domains, services, all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/16-remote-schema.md b/packages/core/docs/development/components/components/16-remote-schema.md
new file mode 100644
index 000000000..41598c19a
--- /dev/null
+++ b/packages/core/docs/development/components/components/16-remote-schema.md
@@ -0,0 +1,176 @@
+---
+sidebar_position: 16
+keywords:
+- components
+- remote schema
+- fetch
+- runtime
+sidebar_label: RemoteSchema
+title: RemoteSchema
+description: Component for fetching and rendering remote schemas in EventCatalog
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.52.0" />
+
+The **RemoteSchema** component fetches and renders schemas from remote URLs at runtime, keeping your documentation automatically synchronized with external schema sources.
+
+**Schemas can be fetched from any accessible URL and support authentication headers for private APIs.**
+
+:::tip
+**The `<RemoteSchema/>` component fetches schemas at runtime.**
+
+This ensures your documentation stays up-to-date with the latest schema versions without manual updates.
+:::
+
+:::info SSR Mode Required
+The `<RemoteSchema/>` component only works in Server-Side Rendering (SSR) mode. Make sure your EventCatalog is configured to run in SSR mode to use this component. You can read more about how to configure your EventCatalog to run in SSR mode [here](/docs/development/deployment/build-ssr-mode).
+:::
+
+### Usage
+
+**Basic Example**
+
+```jsx /events/MyEvent/index.mdx
+<RemoteSchema url="https://api.example.com/schemas/user-registered.json" />
+```
+
+**With Custom Title and Height**
+
+```jsx /events/MyEvent/index.mdx
+<RemoteSchema
+  url="https://api.example.com/schemas/payment.json"
+  title="Payment Schema"
+  maxHeight="600"
+/>
+```
+
+### Fetching from Private APIs
+
+<PlanBanner plan="Scale" />
+
+For private APIs requiring authentication, you can provide headers:
+
+```jsx /events/MyEvent/index.mdx
+<RemoteSchema 
+  url="https://private-api.example.com/schemas/order.json"
+  headers={{
+    "Authorization": "Bearer ${API_TOKEN}",
+    "X-API-Key": "${API_KEY}"
+  }}
+  title="Order Schema"
+/>
+```
+
+:::tip Loading environment variables
+
+Add your environment variables to the `.env` file in the root of your EventCatalog project.
+
+The RemoteSchema component will automatically map the environment variables to the template string.
+:::
+
+**Using JSONPath to Extract Specific Schema Parts**
+
+When your API returns nested schemas, use JSONPath to extract specific parts:
+
+```jsx /events/MyEvent/index.mdx
+<RemoteSchema 
+  url="https://api.example.com/openapi.json"
+  jsonPath="$.components.schemas.UserEvent"
+  title="User Event Schema"
+/>
+```
+
+**Rendering as Raw JSON**
+
+Force rendering as raw JSON instead of the schema viewer:
+
+```jsx /events/MyEvent/index.mdx
+<RemoteSchema 
+  url="https://api.example.com/schemas/config.json"
+  renderAs="raw"
+  title="Configuration Schema"
+/>
+```
+
+### Output
+The component automatically detects JSON Schema format and renders an interactive [Schema Viewer](/docs/development/components/components/schema-viewer), or displays raw content for other formats.
+
+### Props
+
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `url` (required)        | `string`  | (empty)           | The URL to fetch the schema from. Supports environment variable templating with `${VAR_NAME}` syntax. |
+| `title` (optional)      | `string`  | "Remote Schema"   | Title to display above the schema                                 |
+| `maxHeight` (optional)  | `string`  | "400"             | Maximum height of the schema viewer in pixels                    |
+| `headers` (optional)    | `object`  | `{}`              | HTTP headers for authentication (requires EventCatalog Scale plan) |
+| `jsonPath` (optional)   | `string`  | (empty)           | [JSONPath expression](https://github.com/dchester/jsonpath) to extract specific parts of the response    |
+| `renderAs` (optional)   | `string`  | "auto"            | Rendering mode: "auto", "schema", or "raw"                      |
+
+### Environment Variable Support
+
+The `url` and `headers` props support environment variable templating using `${VARIABLE_NAME}` syntax:
+
+```md
+<RemoteSchema 
+  url="https://${API_HOST}/schemas/user.json"
+  headers={{
+    "Authorization": "Bearer ${API_TOKEN}"
+  }}
+/>
+```
+
+:::tip Loading environment variables
+Add your environment variables to the `.env` file in the root of your EventCatalog project.
+
+The RemoteSchema component will automatically map the environment variables to the template string.
+:::
+
+### JSONPath Examples
+
+Extract specific schema definitions from complex API responses using [JSONPath](https://github.com/dchester/jsonpath).
+
+```md
+<!-- Extract a specific component schema from OpenAPI -->
+<RemoteSchema 
+  url="https://api.example.com/openapi.json"
+  jsonPath="$.components.schemas.User"
+/>
+
+<!-- Extract from AsyncAPI -->
+<RemoteSchema 
+  url="https://api.example.com/asyncapi.json"
+  jsonPath="$.components.messages.UserCreated.payload"
+/>
+
+<!-- Extract from nested arrays -->
+<RemoteSchema 
+  url="https://api.example.com/schemas.json"
+  jsonPath="$.definitions[0].schema"
+/>
+```
+
+### Error Handling
+
+The component provides clear error messages for common issues:
+
+- **Network errors**: Connection timeouts, DNS resolution failures
+- **Authentication errors**: Invalid credentials or missing headers
+- **JSONPath errors**: Invalid JSONPath expressions
+- **Format errors**: Unsupported schema formats
+
+### Benefits for Teams
+
+- **Always up-to-date**: Schemas are fetched at runtime, ensuring documentation reflects the latest API changes
+- **Reduced maintenance**: No need to manually update schema files when APIs change
+- **Single source of truth**: Documentation pulls directly from your API definitions
+- **Private API support**: Secure access to internal schemas with authentication headers
+- **Flexible extraction**: Use JSONPath to document specific parts of large API specifications
+
+This component bridges the gap between your live APIs and documentation, ensuring your EventCatalog always reflects the current state of your systems.
+
+### Support
+
+The `<RemoteSchema/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/17-resource-group-table.md b/packages/core/docs/development/components/components/17-resource-group-table.md
new file mode 100644
index 000000000..bbef8996f
--- /dev/null
+++ b/packages/core/docs/development/components/components/17-resource-group-table.md
@@ -0,0 +1,86 @@
+---
+sidebar_position: 17
+keywords:
+- components
+sidebar_label: ResourceGroupTable
+title: ResourceGroupTable
+description: Component for displaying EventCatalog grouped resources in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.32.0" />
+
+The `<ResourceGroupTable/>` component renders a table of resources for your page in EventCtalog.
+
+The component renders a paginated table of (messages, services, domains, flows, channels), with the ability to filter by resource type, and text search.
+
+### Why use ResourceGroupTable?
+
+Sometimes in your catalog you may want to link related resources together or group them in particular ways that EventCatalog does not naturally support.
+
+Examples:
+
+- List a custom list of messages in a domain page
+- Create a "Related Resources" section on your docs for your documentation readers
+- Create a custom list of resources in your page and let people search them easily.
+
+### Usage
+
+The `<ResourceGroupTable/>` component requires **frontmatter** property called **resourceGroups** defined in your resource, and then the component itself.
+
+1. Adding `resourceGroup` property to your resource
+```md title="example /domains/Orders/index.mdx"
+---
+id: Orders
+name: Orders
+version: 0.0.3
+owners:
+  - dboyne
+  - full-stack
+# Here we define the resourceGroups, in this example we create a group called core resources
+# We create a list called `related-resources` and we group these services.
+# Remember you can define any group of information you want, and link to any catalog resource
+resourceGroups:
+  - id: related-resources
+    title: Core resources
+    items:
+      - id: InventoryService
+        type: service
+      - id: OrdersService
+        type: service
+      - id: NotificationService
+        type: service
+      - id: ShippingService
+        type: service
+---
+```
+
+
+**Basic Example**
+
+```md /domains/MyDomain/index.mdx
+---
+#domain frontmatter
+---
+
+<ResourceGroupTable id="related-resources" limit={4} showOwners={true} title="Core resources for the Orders domain" description="Resources that are related to the Orders domain, you may find them useful" />
+```
+### Output
+![Example output](./img/resource-group-table.png)
+
+You can see the demo of this in the [Orders domain page](https://demo.eventcatalog.dev/domains/Orders/0.0.3).
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `id`             | `string`  | none           | Id of the resource group to render. |
+| `title`             | `string`  | 'Related Resources'           | The title shown above the table. |
+| `subtitle`             | `string`  | 'Resources'           | The title shown inside the table. |
+| `description`             | `string`  | 'Resources that are related to the current resource.'           | The description of the table. |
+| `limit`             | `number`  | 10           | The number of resources to render in the table. Results are paginated. |
+| `showOwners`             | `boolean`  | false           | Whether to show the owners of the resources in the table. |
+
+### Support
+
+The `<ResourceGroupTable/>` component is supported on all EventCatalog pages.
diff --git a/packages/core/docs/development/components/components/18-resource-link.md b/packages/core/docs/development/components/components/18-resource-link.md
new file mode 100644
index 000000000..72037d12f
--- /dev/null
+++ b/packages/core/docs/development/components/components/18-resource-link.md
@@ -0,0 +1,57 @@
+---
+sidebar_position: 18
+keywords:
+- components
+sidebar_label: ResourceLink
+title: ResourceLink
+description: Create links in your documentation to resources in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.32.3" />
+
+:::tip Prefer wiki-style syntax
+For most use cases, we recommend using the newer [resource references](/docs/development/components/resource-references) syntax instead:
+
+```md
+[[service|InventoryService]]
+```
+
+This provides interactive tooltips and a more natural writing experience. Use `<ResourceLink/>` only when you need custom link text or explicit component control.
+:::
+
+The `<ResourceLink/>` component renders a link to a resource in EventCatalog.
+
+**Basic Example**
+
+```jsx /domains/MyDomain/index.mdx
+<ResourceLink id="InventoryService" type="service" />
+
+<ResourceLink id="InventoryService" type="service" version="1.0.0" />
+
+<ResourceLink id="InventoryService" type="service">This is a custom link</ResourceLink>
+```
+
+### Props
+| Name                    | Type      | Default           | Required | Description                                                       |
+| ----------------------- | --------- | ----------------- | -------- | ----------------------------------------------------------------- |
+| `id`             | `string`  | none           | Yes      | Id of the resource group to render. |
+| `type`             | `string`  | none           | Yes      | The type of resource to render (service, event, query, command, channel, flow, domain, user, team) |
+| `version`             | `string`  | none           | Optional. The version of the resource to render, by default the latest version is used. | Version of the resource to link to.
+
+### Recommended alternative
+
+<AddedIn version="3.6.1" />
+
+For most documentation, prefer the wiki-style syntax which provides interactive tooltips:
+
+```md
+The [[service|InventoryService]] manages inventory.
+```
+
+See [Resource references](/docs/development/components/resource-references) for full documentation.
+
+### Support
+
+The `<ResourceLink/>` component is supported on all EventCatalog pages.
diff --git a/packages/core/docs/development/components/components/19-schema.md b/packages/core/docs/development/components/components/19-schema.md
new file mode 100644
index 000000000..3b6e739ca
--- /dev/null
+++ b/packages/core/docs/development/components/components/19-schema.md
@@ -0,0 +1,44 @@
+---
+sidebar_position: 19
+keywords:
+- components
+sidebar_label: Schema
+title: Schema
+description: Component for EventCatalog
+---
+
+The schema component renders a given schema into the page. 
+
+**Schemas can be any file format (.avro, .json etc).**
+
+:::tip
+**The `<Schema/>` component renders any schema format.**
+
+If you need to render JSON Schema, you can also use the [\<SchemaViewer/\> component](/docs/development/components/components/schema-viewer).
+
+:::
+
+### Usage
+
+1. Add your schema file to your folder.
+    - e.g `/events/MyEvent/schema.avro`
+
+**Example**
+
+```jsx /events/MyEvent/index.mdx
+<Schema file="schema.avro" />
+```
+
+### Output
+![Example output](./img/schema.png)
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `file` (required)             | `string`  | (empty)           | The file to load into the schema block. Path is resolved by EventCatalog.                              |
+| `title` (optional)                 | `string`  | (empty)           | Title to render in your schema block                              |
+| `lang` (optional)             | `string`  | `json`           | The code language of the schema. Defaults to `json`. Over 100 languages are supported. [List of options can be found here.](https://github.com/shikijs/textmate-grammars-themes/blob/main/packages/tm-grammars/README.md)                             |
+
+### Support
+
+The `<Schema/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/20-schema-viewer.md b/packages/core/docs/development/components/components/20-schema-viewer.md
new file mode 100644
index 000000000..8c51d947a
--- /dev/null
+++ b/packages/core/docs/development/components/components/20-schema-viewer.md
@@ -0,0 +1,69 @@
+---
+sidebar_position: 20
+keywords:
+- components
+sidebar_label: SchemaViewer
+title: SchemaViewer
+description: Render JSON schema in EventCatalog
+---
+
+A Schema Viewer component for EventCatalog that supports JSON schemas and Avro schemas.
+
+Renders the given schema (.json, .yaml, .avro, .avsc) into the page.
+
+:::tip
+**The `<SchemaViewer/>` component only works with JSON Schema and Avro schemas.**
+
+If you need to render other schema formats, please use the [\<Schema/\> component](/docs/development/components/components/schema).
+
+_Avro support was added in 2.64.0. Please upgrade to the latest version of EventCatalog to use this component._
+:::
+
+### Usage
+
+1. Add a JSON or Avro schema file to your folder.
+    - e.g `/events/MyEvent/schema.json`
+    - e.g `/events/MyEvent/schema.avro`
+
+**Example**
+
+```jsx /events/MyEvent/index.mdx
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" search="true" expand="true" />
+
+<SchemaViewer file="schema.avro" title="Avro Schema" maxHeight="500" />
+
+<SchemaViewer file="schema.yaml" title="YAML Schema" maxHeight="500" />
+```
+
+### Output
+![Example output](./img/schemaviewer.png)
+
+### Props
+| Name                    | Type      | Default           | Description                                                       |
+| ----------------------- | --------- | ----------------- | ----------------------------------------------------------------- |
+| `title` (optional)                 | `string`  | (empty)           | Title to render above your schema                               |
+| `file` (required)             | `string`  | (empty)           | The file to load into the schema block. Path is resolved by EventCatalog.                              |
+| `maxHeight` (optional)             | `string`  | "500"           | Max height of the JSON Schema viewer (in pixels).                              |
+| `search` (optional)             | `boolean`  | false           | Renders a search input in the viewer                             |
+| `expand` (optional)             | `boolean`  | false           | Expands all properties by default                             |
+| `showRequired` (optional)             | `boolean`  | false           | **Avro Schemas only**: Will show which fields are required. Fields are required if they don't have a default value or null as their type. As documented in the [Avro Specification](https://avro.apache.org/docs/++version++/specification/)                           |
+
+
+## Rendering multiple schemas
+
+You can use the SchemaViewer multiple times in your page.
+
+**Example**
+
+```md /events/MyEvents.index.mdx
+The Inventory Adjusted event is triggered whenever there is a change in the inventory levels of a product. 
+This could occur due to various reasons such as receiving new stock, sales, returns, or manual adjustments by the inventory management team.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" id="json-schema" />
+<SchemaViewer file="old-schema.json" title="Another Version" maxHeight="500" id="json-schema2" />
+<SchemaViewer file="new-schema.yml" title="Another Version" maxHeight="500" id="yaml-schema" />
+```
+
+### Support
+
+The `<SchemaViewer/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/21-steps.md b/packages/core/docs/development/components/components/21-steps.md
new file mode 100644
index 000000000..b3b603cde
--- /dev/null
+++ b/packages/core/docs/development/components/components/21-steps.md
@@ -0,0 +1,83 @@
+---
+sidebar_position: 21
+keywords:
+  - components
+sidebar_label: Steps
+title: Steps
+description: Render steps into EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.7.14"/>
+
+The Steps component is a powerful tool for creating structured, sequential guides in EventCatalog. It's ideal for presenting step-by-step instructions, tutorials, or workflows, particularly when explaining processes, API integrations, or code implementations.
+
+### Key Features:
+
+- Automatic Numbering: Steps are automatically numbered, providing clear sequence and structure.
+- Flexible Content: Supports various content types including text, code snippets, and embedded components.
+
+### Use Cases:
+
+- Walking users through setup procedures
+- Explaining complex workflows
+- Presenting API integration steps
+- Showcasing code examples with explanations
+
+**Example**
+
+```jsx /services/MyService/index.mdx
+<Steps title="How to connect to Inventory Service">
+  <Step title="Obtain API credentials">
+    Request API credentials from the Inventory Service team.
+  </Step>
+  <Step title="Install the SDK">
+    Run the following command in your project directory:
+    ```bash
+      npm install inventory-service-sdk
+    ```_
+  </Step>
+  <Step title="Initialize the client">
+  Use the following code to initialize the Inventory Service client:
+  ```js
+    const InventoryService = require('inventory-service-sdk');
+    const client = new InventoryService.Client({
+      clientId: 'YOUR_CLIENT_ID',
+      clientSecret: 'YOUR_CLIENT_SECRET',
+      apiUrl: 'https://api.inventoryservice.com/v1'
+    });
+  ```_
+  </Step>
+  <Step title="Make API calls">
+  
+  You can now use the client to make API calls. For example, to get all products:
+  ```js
+  client.getProducts()
+    .then(products => console.log(products))
+    .catch(error => console.error(error));
+  ```_
+  </Step>
+</Steps>
+```
+
+### Output
+![Example output](./img/steps.png)
+
+See example in the [demo EventCatalog application](https://demo.eventcatalog.dev/docs/services/InventoryService/0.0.2).
+
+### Props (`<Steps>`)
+
+| Name               | Type     | Default | Description                             |
+| ------------------ | -------- | ------- | --------------------------------------- |
+| `title` (optional) | `string` | (empty) | Title that gets renders above the steps |
+
+### Props (`<Step>`)
+
+| Name                     | Type      | Default | Description                                                                                                                                                |
+| ------------------------ | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title` (required)       | `string`  | (empty) | Title for the step                                                                                                                                         |
+
+### Support
+
+The `<Steps/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/22-tabs.md b/packages/core/docs/development/components/components/22-tabs.md
new file mode 100644
index 000000000..691b0b730
--- /dev/null
+++ b/packages/core/docs/development/components/components/22-tabs.md
@@ -0,0 +1,55 @@
+---
+sidebar_position: 22
+keywords:
+  - components
+sidebar_label: Tabs
+title: Tabs
+description: Render tabs in your EventCatalog pages
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.16.5"/>
+
+The `<Tabs />` component is a EventCatalog component that will render a tabs into your markdown page.
+
+Add Tabs and TabItems into your markdown file.
+
+**Example**
+
+```jsx /services/MyService/index.mdx
+<Tabs>
+  <TabItem title="Tab 1">
+    This is the content for tab 1
+  </TabItem>
+  <TabItem title="Tab 2">
+    This is the content for tab 2
+  </TabItem>
+</Tabs>
+```
+
+**Example with code as child**
+
+```jsx /services/MyService/index.mdx
+<Tabs>
+  <TabItem title="Tab 1">
+    ``sh
+    This is the content for tab 1
+    ``
+  </TabItem>
+  <TabItem title="Tab 2">
+    ``js
+    console.log('This is the content for tab 2');
+    ``
+  </TabItem>
+</Tabs>
+```
+
+### Output
+![Example output](./img/tabs.png)
+
+See example in the [demo EventCatalog application](https://demo.eventcatalog.dev/docs/events/InventoryAdjusted/1.0.1).
+
+### Support
+
+The `<Tabs/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/23-tiles.md b/packages/core/docs/development/components/components/23-tiles.md
new file mode 100644
index 000000000..8ee1de044
--- /dev/null
+++ b/packages/core/docs/development/components/components/23-tiles.md
@@ -0,0 +1,53 @@
+---
+sidebar_position: 23
+keywords:
+  - components
+sidebar_label: Tiles
+title: Tiles
+description: Render tiles into EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.7.12"/>
+
+Renders Tiles in EventCatalog, can be great for internal and external links.
+
+Tile icons are from [hero icons](https://heroicons.com/), you can find a [list of them here](https://unpkg.com/browse/@heroicons/react@2.1.5/24/outline/).
+
+**Example**
+
+```jsx /services/MyService/index.mdx
+<Tiles columns={2}>
+  <Tile icon="DocumentIcon" href="/docs" title="View the docs" description="Dive deeper and view our docs" />
+  <Tile icon="DocumentIcon" href="/visualiser" title="View the visualiser" description="Explore your architecture" />
+  <Tile icon="UserGroupIcon" href="https://eventcatalog.dev" openWindow="true" title="Contact EventCatalog" description="Any questions? Visit our website!" />
+  <Tile icon="BoltIcon" href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`} title={`Receives ${frontmatter.receives.length} messages`} description="This service receives messages from downstream consumers" />
+</Tiles>
+```
+
+### Output
+![Example output](./img/tiles.png)
+
+See example in the [demo EventCatalog application](https://demo.eventcatalog.dev/docs/services/InventoryService/0.0.2).
+
+### Props (`<Tiles>`)
+
+| Name               | Type     | Default | Description                             |
+| ------------------ | -------- | ------- | --------------------------------------- |
+| `title` (optional) | `string` | (empty) | Title that gets renders above the tiles |
+| `columns` (optional) | `number` | 2 | Number of columns to render the tiles in |
+### Props (`<Tile>`)
+
+| Name                     | Type      | Default | Description                                                                                                                                                |
+| ------------------------ | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title` (optional)       | `string`  | (empty) | Title for the tile                                                                                                                                         |
+| `description` (optional) | `string`  | (empty) | Description for the tile                                                                                                                                   |
+| `icon` (optional)        | `string`  | (empty) | Icon to show in the tile. Iconss are [HeroIcons](https://heroicons.com/). [Find a list here](https://unpkg.com/browse/@heroicons/react@2.1.5/24/outline/). |
+| `iconColor` (optional)   | `string`  | `text-purple-500` | The color of the icon, using tailwind classes.                                                                                |
+| `href` (optional)        | `string`  | (empty) | URL for the tile                                                                                                                                           |
+| `openWindow` (optional)  | `boolean` | (empty) | Open the URL in a new window                                                                                                                               |
+
+### Support
+
+The `<Tiles/>` component is supported in domains, services, and all messages, changelogs, and custom documentation pages.
diff --git a/packages/core/docs/development/components/components/24-visibility.md b/packages/core/docs/development/components/components/24-visibility.md
new file mode 100644
index 000000000..673fce246
--- /dev/null
+++ b/packages/core/docs/development/components/components/24-visibility.md
@@ -0,0 +1,61 @@
+---
+sidebar_position: 24
+keywords:
+  - components
+  - visibility
+  - agents
+  - ai
+  - llm
+sidebar_label: Visibility
+title: Visibility
+description: Gate content by audience — humans in the UI, agents in raw markdown
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.33.0" />
+
+`<Visibility>` lets you write a single MDX file that serves two audiences: human readers in the browser and AI agents or LLMs consuming raw markdown. Wrap content in the appropriate block and EventCatalog handles the rest — no content forking required.
+
+**Example**
+
+```jsx /queries/GetInventoryList/index.mdx
+<Visibility for="humans">
+  Use the **Schema** and **Visualiser** actions on this page to inspect the
+  inventory query contract and its relationships.
+</Visibility>
+
+<Visibility for="agents">
+  When reasoning about this query, treat `GET /inventory` as a read-only
+  inventory lookup. Prefer linking this query to inventory reporting, order
+  placement, and stock reservation workflows.
+</Visibility>
+```
+
+### How it works
+
+In the browser UI, only `for="humans"` blocks render. The `for="agents"` block returns nothing and is never visible to human readers.
+
+When an AI agent or LLM fetches the raw markdown for a resource — via the `.md` / `.mdx` endpoints, the `/llms-full.txt` feed, custom docs, team/user pages, language pages, or diagram pages — the `for="humans"` blocks are stripped and only `for="agents"` content remains.
+
+This means the same file can give a human reader UI-oriented guidance ("click the Schema tab") while giving an agent structured, machine-actionable context ("treat this as a read-only lookup") without any duplication.
+
+### Props
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| `for` | `"agents"` \| `"humans"` | Yes | The target audience for the wrapped content. |
+
+### Write effective agent content
+
+Use `for="agents"` blocks to provide context that helps AI tools reason about your architecture. Good agent content includes:
+
+- The intent and constraints of the resource ("read-only", "idempotent", "fires on every state change")
+- How the resource relates to other services or workflows
+- Edge cases or business rules that are not obvious from the schema
+
+Use `for="humans"` blocks for UI-oriented guidance: links to tabs, interactive tools, visual walkthroughs, or anything that only makes sense in a browser context.
+
+### Support
+
+`<Visibility>` is supported in domains, services, all messages, changelogs, custom documentation pages, team pages, user pages, language pages, and diagram pages.
diff --git a/packages/core/docs/development/components/components/_category_.json b/packages/core/docs/development/components/components/_category_.json
new file mode 100644
index 000000000..7db9b0893
--- /dev/null
+++ b/packages/core/docs/development/components/components/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Components",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "components/list",
+    "title": "Components",
+    "description": "Reference for EventCatalog MDX components."
+  }
+}
diff --git a/packages/core/docs/development/components/custom-components/01-introduction.md b/packages/core/docs/development/components/custom-components/01-introduction.md
new file mode 100644
index 000000000..1fff8360f
--- /dev/null
+++ b/packages/core/docs/development/components/custom-components/01-introduction.md
@@ -0,0 +1,74 @@
+---
+sidebar_position: 1
+sidebar_label: Introduction
+title: Write your own components
+description: Learn when and why to create custom components in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+EventCatalog is powered by [Astro](https://docs.astro.build/en/basics/astro-components/). This means you can create your own components and use them inside your catalog pages.
+
+Custom components are useful when you want to reuse the same block of UI or logic across services, events, domains, teams, and custom documentation pages.
+
+For example, you can create components for:
+
+- service health cards
+- ownership summaries
+- links to runbooks or dashboards
+- API status panels
+- scorecards
+- custom diagrams
+- metadata from another system
+
+## What you will create
+
+In this section, we will create a small component, render it in a service page, pass catalog data into it, fetch data from another system, and add simple browser behavior.
+
+By the end, you will have the main patterns you need to build your own reusable components.
+
+## Component types
+
+EventCatalog supports two types of custom component:
+
+- `.astro` components for reusable UI, JavaScript, data fetching, and dynamic rendering
+- `.mdx` components for reusable Markdown content
+
+Most custom components should be `.astro` files. They give you the most flexibility and match how EventCatalog renders built-in components.
+
+## Where components live
+
+Create custom components in the `components` directory at the root of your catalog.
+
+<ProjectTree
+  items={[
+    {
+      name: 'my-catalog',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'components',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'service-summary.astro', highlight: true }],
+        },
+        { name: 'services', type: 'folder' },
+        { name: 'events', type: 'folder' },
+        { name: 'eventcatalog.config.js' },
+      ],
+    },
+  ]}
+/>
+
+You can import these components into any MDX page using the `@catalog/components` alias.
+
+```tsx title="/services/OrderService/index.mdx"
+import ServiceSummary from '@catalog/components/service-summary.astro';
+
+<ServiceSummary />
+```
+
+:::tip
+Astro has its own component model. If you want to go deeper, read the [Astro components documentation](https://docs.astro.build/en/basics/astro-components/).
+:::
diff --git a/packages/core/docs/development/components/custom-components/02-create-your-first-component.md b/packages/core/docs/development/components/custom-components/02-create-your-first-component.md
new file mode 100644
index 000000000..0b634436f
--- /dev/null
+++ b/packages/core/docs/development/components/custom-components/02-create-your-first-component.md
@@ -0,0 +1,71 @@
+---
+sidebar_position: 2
+sidebar_label: Create your first component
+title: Create your first component
+description: Create a small reusable component and render it in a catalog page.
+---
+
+In this guide, we will create a simple component and add it to a service page.
+
+## Create the component
+
+Create a new file in your catalog.
+
+```txt title="File"
+/components/service-note.astro
+```
+
+Add the component markup.
+
+```jsx title="/components/service-note.astro"
+---
+const { title = 'Service note' } = Astro.props;
+---
+
+<aside class="not-prose rounded-lg border border-gray-200 bg-gray-50 p-4 dark:border-gray-800 dark:bg-gray-900">
+  <p class="m-0 text-sm font-semibold text-gray-900 dark:text-gray-100">{title}</p>
+  <p class="mb-0 mt-2 text-sm text-gray-600 dark:text-gray-300">
+    This note is rendered from a custom EventCatalog component.
+  </p>
+</aside>
+```
+
+The `not-prose` class keeps the documentation page typography from changing the spacing and styles inside your component.
+
+## Add it to a page
+
+Open one of your service pages and import the component.
+
+```markdown title="/services/OrderService/index.mdx"
+---
+id: OrderService
+name: Order Service
+version: 0.0.1
+summary: Handles customer orders.
+---
+
+import ServiceNote from '@catalog/components/service-note.astro';
+
+# Order Service
+
+<ServiceNote title="About this service" />
+```
+
+## Check the page
+
+Start your catalog and open the service page.
+
+```bash
+npm run dev
+```
+
+You should see the custom note rendered inside the service documentation.
+
+<div className="not-prose my-8 flex flex-col items-center gap-2">
+  <img src="/img/docs/custom-components/first-component.png" alt="Custom service note component rendered in EventCatalog" className="rounded-lg border border-gray-200 shadow-sm dark:border-gray-800" />
+  <span className="text-center text-sm italic text-gray-500 dark:text-gray-400">A custom component rendered inside an EventCatalog service page.</span>
+</div>
+
+:::tip
+Start small. Once you can render one component, the same pattern works for richer cards, tables, status panels, and diagrams.
+:::
diff --git a/packages/core/docs/development/components/custom-components/03-pass-data-into-components.md b/packages/core/docs/development/components/custom-components/03-pass-data-into-components.md
new file mode 100644
index 000000000..3393cb1ac
--- /dev/null
+++ b/packages/core/docs/development/components/custom-components/03-pass-data-into-components.md
@@ -0,0 +1,86 @@
+---
+sidebar_position: 3
+sidebar_label: Pass data into components
+title: Pass data into components
+description: Pass props, frontmatter, variables, and config data into custom components.
+---
+
+Components become more useful when they can render data from the page they are used on.
+
+## Use props
+
+Props are values passed into the component when you render it.
+
+```jsx title="/components/service-owner.astro"
+---
+const { team } = Astro.props;
+---
+
+<p class="not-prose text-sm">
+  Owned by <strong>{team}</strong>
+</p>
+```
+
+Render the component from a catalog page.
+
+```tsx title="/services/OrderService/index.mdx"
+import ServiceOwner from '@catalog/components/service-owner.astro';
+
+<ServiceOwner team="Commerce Platform" />
+```
+
+## Use frontmatter
+
+Every EventCatalog resource page has frontmatter. You can pass that data into your component.
+
+```markdown title="/services/OrderService/index.mdx"
+---
+id: OrderService
+name: Order Service
+version: 0.0.1
+summary: Handles customer orders.
+---
+
+import ServiceSummary from '@catalog/components/service-summary.astro';
+
+<ServiceSummary name={frontmatter.name} summary={frontmatter.summary} />
+```
+
+Then read those props in your component.
+
+```jsx title="/components/service-summary.astro"
+---
+const { name, summary } = Astro.props;
+---
+
+<section class="not-prose rounded-lg border border-gray-200 p-4 dark:border-gray-800">
+  <h2 class="m-0 text-lg font-semibold">{name}</h2>
+  <p class="mb-0 mt-2 text-sm text-gray-600 dark:text-gray-300">{summary}</p>
+</section>
+```
+
+## Use page variables
+
+You can export variables from an MDX page and pass them into a component.
+
+```tsx title="/services/OrderService/index.mdx"
+import ServiceStatus from '@catalog/components/service-status.astro';
+
+export const status = 'Stable';
+
+<ServiceStatus status={status} />
+```
+
+## Use catalog config
+
+You can import values from `eventcatalog.config.js` using `@config`.
+
+```jsx title="/components/catalog-name.astro"
+---
+import config from '@config';
+---
+
+<span>{config.title}</span>
+```
+
+Use this when a component needs shared catalog settings, organization names, or other global values.
diff --git a/packages/core/docs/development/components/custom-components/04-fetch-data-in-components.md b/packages/core/docs/development/components/custom-components/04-fetch-data-in-components.md
new file mode 100644
index 000000000..4a6ea0ef7
--- /dev/null
+++ b/packages/core/docs/development/components/custom-components/04-fetch-data-in-components.md
@@ -0,0 +1,191 @@
+---
+sidebar_position: 4
+sidebar_label: Fetch data
+title: Fetch data in components
+description: Fetch build-time, runtime, or browser data from custom EventCatalog components.
+---
+
+Custom components can fetch data from other systems. This is useful when your documentation needs to show information from tools such as internal platforms, service catalogs, monitoring systems, observability platforms, on-call tools, custom registries, schema registries, or deployment platforms.
+
+Astro components can use `await fetch()` in the component frontmatter. EventCatalog is powered by Astro, so the same pattern works in custom EventCatalog components.
+
+## Fetch and render data
+
+This example fetches a random user and renders their name and location.
+
+```jsx title="/components/random-user.astro"
+---
+const response = await fetch('https://randomuser.me/api/');
+const data = await response.json();
+const randomUser = data.results[0];
+---
+
+<article class="not-prose rounded-lg border border-gray-200 p-4 dark:border-gray-800">
+  <p class="m-0 text-sm font-semibold text-gray-900 dark:text-gray-100">
+    {randomUser.name.first} {randomUser.name.last}
+  </p>
+  <p class="mb-0 mt-2 text-sm text-gray-600 dark:text-gray-300">
+    {randomUser.location.city}, {randomUser.location.country}
+  </p>
+</article>
+```
+
+Use the component in a catalog page.
+
+```tsx title="/services/OrderService/index.mdx"
+import RandomUser from '@catalog/components/random-user.astro';
+
+<RandomUser />
+```
+
+The same pattern can be used to render data from systems your team already uses.
+
+For example, you might fetch:
+
+- a service owner from an internal platform API
+- a support rotation from an on-call tool
+- a maturity score from a scorecard system
+- repository metadata from GitHub
+- deployment metadata from your platform
+
+## Static builds
+
+By default, EventCatalog builds a static website.
+
+In a static build, `fetch()` calls in Astro component frontmatter run when the catalog is built. The fetched data is written into the generated HTML.
+
+This means:
+
+- the data is captured at build time
+- the page will not refetch that data for every viewer
+- the page updates when you rebuild and redeploy the catalog
+- a failed API request can fail the build unless you handle the error
+
+Static fetching works well for documentation data that does not need to change every time someone opens the page.
+
+```jsx title="/components/service-score.astro"
+---
+const { service } = Astro.props;
+
+let score = 'Unknown';
+
+try {
+  const response = await fetch(`https://platform.example.com/services/${service}/score`);
+  const data = await response.json();
+  score = data.score;
+} catch {
+  score = 'Unavailable';
+}
+---
+
+<span class="not-prose rounded-md border border-gray-200 px-2 py-1 text-sm dark:border-gray-800">
+  Score: {score}
+</span>
+```
+
+Use this pattern when the data can be slightly stale and tied to your documentation release process.
+
+## SSR builds
+
+EventCatalog can also run in [SSR mode](/docs/development/deployment/build-ssr-mode).
+
+In SSR mode, pages are rendered by a server. Astro frontmatter fetches run at runtime instead of only during the static build.
+
+This means:
+
+- the data can be fresher
+- the request can use server-side environment variables
+- the catalog needs a running server
+- slow APIs can slow down the page unless you cache or handle failures
+
+SSR mode is a better fit when the component needs private or frequently changing data.
+
+You can enable server output in `eventcatalog.config.js`.
+
+```js title="/eventcatalog.config.js"
+export default {
+  output: 'server',
+};
+```
+
+Read more about [EventCatalog static and server output](/docs/development/getting-started/develop-and-build#eventcatalog-static-vs-server-output).
+
+## Private APIs and API keys
+
+If the API requires a token, keep the token on the server.
+
+For static builds, the token can be available in your build environment. The fetch runs during the build, and only the rendered result is included in the generated HTML. You can store secrets in your `.env` file or deployment environment variables. Read more about [configuring environment variables](/docs/development/getting-started/configuration-overview#configuring-environment-variables).
+
+```jsx title="/components/internal-service-score.astro"
+---
+const { service } = Astro.props;
+
+const response = await fetch(`https://platform.example.com/services/${service}/score`, {
+  headers: {
+    Authorization: `Bearer ${process.env.PLATFORM_API_TOKEN}`,
+  },
+});
+
+const data = await response.json();
+---
+
+<span class="not-prose rounded-md border border-gray-200 px-2 py-1 text-sm dark:border-gray-800">
+  Score: {data.score}
+</span>
+```
+
+For SSR builds, the token is read by the server at runtime.
+
+:::caution
+Do not render API keys into the page, pass them to client-side scripts, or expose them through props that end up in HTML.
+:::
+
+If the request must happen in the browser, do not call private APIs directly with a secret. Use a server-side endpoint, proxy, or SSR component that keeps the token on the server.
+
+## Browser fetching
+
+Use browser fetching when the data should update after the page loads and does not require a private secret.
+
+```jsx title="/components/live-status.astro"
+---
+const { endpoint } = Astro.props;
+---
+
+<div data-service-status data-endpoint={endpoint} class="not-prose rounded-lg border border-gray-200 p-4 text-sm dark:border-gray-800">
+  Loading status...
+</div>
+
+<script>
+  const elements = document.querySelectorAll('[data-service-status]');
+
+  elements.forEach(async (element) => {
+    const endpoint = element.getAttribute('data-endpoint');
+
+    try {
+      const response = await fetch(endpoint);
+      const data = await response.json();
+      element.textContent = `Status: ${data.status}`;
+    } catch {
+      element.textContent = 'Status unavailable';
+    }
+  });
+</script>
+```
+
+Use the component in a page.
+
+```tsx title="/services/OrderService/index.mdx"
+import LiveStatus from '@catalog/components/live-status.astro';
+
+<LiveStatus endpoint="https://status.example.com/order-service.json" />
+```
+
+## Which pattern should you use?
+
+Use static build fetching when the data can be part of the generated documentation.
+
+Use SSR fetching when the data should be fresh at request time or needs private server-side credentials.
+
+Use browser fetching when the data is public and should update after the page loads.
+
+For more examples, read the [Astro data fetching documentation](https://docs.astro.build/en/guides/data-fetching/).
diff --git a/packages/core/docs/development/components/custom-components/05-style-components.md b/packages/core/docs/development/components/custom-components/05-style-components.md
new file mode 100644
index 000000000..e0bc4c04d
--- /dev/null
+++ b/packages/core/docs/development/components/custom-components/05-style-components.md
@@ -0,0 +1,60 @@
+---
+sidebar_position: 5
+sidebar_label: Style components
+title: Style components
+description: Style custom EventCatalog components with Tailwind CSS.
+---
+
+EventCatalog includes Tailwind CSS. You can use Tailwind classes inside your custom components.
+
+```jsx title="/components/service-card.astro"
+---
+const { name, summary } = Astro.props;
+---
+
+<article class="not-prose rounded-lg border border-gray-200 bg-white p-4 shadow-sm dark:border-gray-800 dark:bg-gray-950">
+  <h2 class="m-0 text-base font-semibold text-gray-900 dark:text-gray-100">{name}</h2>
+  <p class="mb-0 mt-2 text-sm leading-6 text-gray-600 dark:text-gray-300">{summary}</p>
+</article>
+```
+
+Use the component from a catalog page.
+
+```tsx title="/services/OrderService/index.mdx"
+import ServiceCard from '@catalog/components/service-card.astro';
+
+<ServiceCard name={frontmatter.name} summary={frontmatter.summary} />
+```
+
+## Keep components readable
+
+Custom components usually sit inside documentation pages, so keep them simple.
+
+- Use small, focused components.
+- Prefer readable text over dense layouts.
+- Support light and dark mode.
+- Avoid large custom layouts unless the component needs them.
+
+## Use local styles when needed
+
+Astro components can include a `<style>` block.
+
+```jsx title="/components/status-pill.astro"
+---
+const { status } = Astro.props;
+---
+
+<span class="not-prose status-pill">{status}</span>
+
+<style>
+  .status-pill {
+    border: 1px solid var(--ifm-color-emphasis-300);
+    border-radius: 999px;
+    display: inline-flex;
+    font-size: 0.875rem;
+    padding: 0.125rem 0.5rem;
+  }
+</style>
+```
+
+Use Tailwind for most styling, and local CSS when a component needs a small custom rule.
diff --git a/packages/core/docs/development/components/custom-components/06-add-client-side-scripts.md b/packages/core/docs/development/components/custom-components/06-add-client-side-scripts.md
new file mode 100644
index 000000000..f06369946
--- /dev/null
+++ b/packages/core/docs/development/components/custom-components/06-add-client-side-scripts.md
@@ -0,0 +1,67 @@
+---
+sidebar_position: 6
+sidebar_label: Client-side scripts
+title: Add client-side scripts
+description: Add browser JavaScript to custom EventCatalog components.
+---
+
+Astro components render HTML by default. If your component needs browser behavior, add a `<script>` tag.
+
+## Add a copy button
+
+Create a component that copies text to the clipboard.
+
+```jsx title="/components/copy-command.astro"
+---
+const { command } = Astro.props;
+---
+
+<div class="not-prose flex items-center gap-2 rounded-lg border border-gray-200 p-3 dark:border-gray-800">
+  <code class="flex-1 text-sm">{command}</code>
+  <button type="button" data-copy-command={command} class="rounded-md border border-gray-200 px-3 py-1 text-sm dark:border-gray-700">
+    Copy
+  </button>
+</div>
+
+<script>
+  const buttons = document.querySelectorAll('[data-copy-command]');
+
+  buttons.forEach((button) => {
+    button.addEventListener('click', async () => {
+      const command = button.getAttribute('data-copy-command');
+      await navigator.clipboard.writeText(command);
+      button.textContent = 'Copied';
+    });
+  });
+</script>
+```
+
+Use it in a page.
+
+```tsx title="/docs/runbooks/deploy-order-service.mdx"
+import CopyCommand from '@catalog/components/copy-command.astro';
+
+<CopyCommand command="npm run deploy:orders" />
+```
+
+## Pass data through HTML attributes
+
+The component script runs when the page loads in the browser. If it needs values from `Astro.props`, render them as HTML attributes first.
+
+```jsx
+---
+const { message } = Astro.props;
+---
+
+<button data-message={message}>Show message</button>
+
+<script>
+  document.querySelectorAll('[data-message]').forEach((button) => {
+    button.addEventListener('click', () => {
+      alert(button.getAttribute('data-message'));
+    });
+  });
+</script>
+```
+
+Read the [Astro client-side scripts documentation](https://docs.astro.build/en/guides/client-side-scripts/) for more details.
diff --git a/packages/core/docs/development/components/custom-components/07-reference.md b/packages/core/docs/development/components/custom-components/07-reference.md
new file mode 100644
index 000000000..8bf93c817
--- /dev/null
+++ b/packages/core/docs/development/components/custom-components/07-reference.md
@@ -0,0 +1,115 @@
+---
+sidebar_position: 7
+sidebar_label: Reference
+title: Custom components reference
+description: Reference for custom components in EventCatalog.
+---
+
+## Component directory
+
+Custom components live in the `components` directory at the root of your catalog.
+
+```txt
+my-catalog/
+└── components/
+    ├── service-card.astro
+    └── reusable-note.mdx
+```
+
+## Import path
+
+Use the `@catalog/components` alias to import custom components.
+
+```tsx
+import ServiceCard from '@catalog/components/service-card.astro';
+```
+
+## Supported file types
+
+| File type | Use for |
+| --- | --- |
+| `.astro` | Reusable UI, props, data fetching, browser scripts, and styling |
+| `.mdx` | Reusable Markdown content |
+
+## Astro component structure
+
+Astro components have a component script and a component template.
+
+```jsx
+---
+// Component script
+const { title } = Astro.props;
+---
+
+<!-- Component template -->
+<h2>{title}</h2>
+```
+
+Read the [Astro components documentation](https://docs.astro.build/en/basics/astro-components/) for the full syntax.
+
+## Props
+
+Read props with `Astro.props`.
+
+```jsx
+---
+const { title, summary } = Astro.props;
+---
+```
+
+Pass props from MDX.
+
+```tsx
+<ServiceCard title="Order Service" summary="Handles customer orders." />
+```
+
+## Frontmatter
+
+Resource frontmatter can be passed into components from MDX pages.
+
+```tsx
+<ServiceCard title={frontmatter.name} summary={frontmatter.summary} />
+```
+
+## Catalog config
+
+Import `eventcatalog.config.js` values with `@config`.
+
+```jsx
+---
+import config from '@config';
+---
+
+<span>{config.title}</span>
+```
+
+## Data fetching
+
+Use `await fetch()` in Astro component frontmatter for build-time data.
+
+```jsx
+---
+const response = await fetch('https://api.example.com/status');
+const status = await response.json();
+---
+```
+
+Use browser JavaScript when data should be fetched after the page loads.
+
+```jsx
+<div data-status class="not-prose">Loading...</div>
+
+<script>
+  const response = await fetch('/status.json');
+  const data = await response.json();
+  document.querySelector('[data-status]').textContent = data.status;
+</script>
+```
+
+## Related documentation
+
+- [Using components](/docs/development/components/using-components)
+- [Built-in components](/docs/components)
+- [Astro components](https://docs.astro.build/en/basics/astro-components/)
+- [Astro data fetching](https://docs.astro.build/en/guides/data-fetching/)
+- [Astro client-side scripts](https://docs.astro.build/en/guides/client-side-scripts/)
diff --git a/packages/core/docs/development/components/custom-components/_category_.json b/packages/core/docs/development/components/custom-components/_category_.json
new file mode 100644
index 000000000..65df6e572
--- /dev/null
+++ b/packages/core/docs/development/components/custom-components/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Write your own components",
+  "position": 7,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "components/custom-components",
+    "description": "Learn how to create reusable components for your EventCatalog documentation."
+  }
+}
diff --git a/packages/core/docs/development/components/diagram-syntax/01-drawio.md b/packages/core/docs/development/components/diagram-syntax/01-drawio.md
new file mode 100644
index 000000000..e6fb8988b
--- /dev/null
+++ b/packages/core/docs/development/components/diagram-syntax/01-drawio.md
@@ -0,0 +1,45 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: DrawIO
+title: <DrawIO />
+description: Embed a DrawIO diagram in your documentation
+id: drawio
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.34.5" />
+
+The `<DrawIO />` component renders a [DrawIO diagram](https://draw.io/) in your documentation.
+
+### Support
+
+The `<DrawIO />` component is supported in domains, services, all messages and [custom documentation](/docs/development/bring-your-own-documentation/custom-pages/introduction).
+
+### Usage
+
+1. Include the `<DrawIO />` component inside the markdown
+    - e.g `/events/MyEvent/index.mdx`
+
+**Basic Example**
+
+```md /events/OrderAmended/index.mdx
+---
+#event frontmatter
+---
+
+<DrawIO url="https://viewer.diagrams.net/?border=0&tags=%7B%7D&lightbox=1&highlight=0000ff&edit=_blank&layers=1&nav=1&title=Untitled%20Diagram.drawio&dark=auto#R%3Cmxfile%3E%3Cdiagram%20id%3D%22yPxyJZ8AM_hMuL3Unpa9%22%20name%3D%22complex%20gitflow%22%3E7V1dm6I2FP41c6kP4ZvL0dHd7bbbbWf7tNubPhmJSheIhTjj7K9vwoeiiRgREGfZi1kJECDvez5yzoHcaeNg8y6Cq%2BUv2EX%2Bnaq4mzvt4U5VgaIq9D%2FW8pq2mEBLGxaR52YH7Roeve8oPzNrXXsuivcOJBj7xFvtN85wGKIZ2WuDUYRf9g%2BbY3%2F%2Fqiu4QFzD4wz6fOufnkuWWStQlN2O98hbLLNL20a2I4D5wVlDvIQufik0aZM7bRxhTNJfwWaMfDZ4%2Bbik502P7N3eWIRCInPC%2Bs8%2Fwk%2BTB%2FP9xFfhR2Puwg9PAyvt5Rn66%2ByB32My9za0bYyDwCPZvZPXfEAI2tDLjZYk8GkDoD9jEuFvaIx9HNGWEIf0yNHc8%2F2DJuh7i5BuzugNI9o%2BekYR8ehQ32c7As912WVGL0uPoMcVnLFrvlBi0TZMj577yQAu6XGInjDihyAbFdYz2hSasiF5h3CASPRKD8n26qo1VI30rIyilKTp9ssOcDsDcVmAWsvaYEaxxbbzHQr0RwbEGaDYHCgcCsilLM02cUSWeIFD6E92raMIr0MXscso%2B3D9iwh5zQQNrglmY7vt4WeMV9lxKx964eApuYcRCt17Jk07NGnL1GPPlfSfciCXEJ1jxR0dreRfciYdpL%2ByE5ONr2xjaOSbD5vizofX4tZnFHl0lBl%2FksajFIjxOpqhklHONQyB0QJl5zrL0cfPD9%2BxR15WH0bu9%2BnDb9YAZHRgYy5DKdVROUoBcJwrWUefsUcfYUdM%2FXQv6a1nJx6Qbntf1XnoVKDdbB09J6wDZRxEG4%2F8VfhdIADdOsT4JGH4E8rZKisCPKvnOCTZicConX7iAw1J%2BkXIh8R73jdctSun%2FL7LtFOu2H%2BGT8j%2FjGOPeJgp%2BCdMCA4Emp%2BwIedtyp4%2BWcIV6z7YLJinMWS2YLaEERnicMCs8D8RmiOKAxv1feVFT3A9ClCJiaL6aWRMtCkq1Vw12BvV5MQaOLy90Vq1NxKQXiT5QuESCGFRQ5xtcLpiVnIv9aRcK07dgi22JJamD3Vn9%2B%2B6RgUoxvXJVWp%2BdjxhG6%2BFjbMN0zmUO5%2FxzBhNYeD5rN8xJaZHO1OVT%2Bgl27mnwxynXIfVyWy9WyYr19I3b7KOmyaRMZvUY7JMtXsma6s83yCmGkUV3DeLqW2C7mGq1uGGXDzvFXkW5Zr5KB4SmlJSUeag1jK1BHmM6lgXqSlozgXQOKADKicc2F0KNRUnftuJYHar4JQtrkNgtQNhVThhNQTCqqtNCaterxd3QXDgBub6hqw%2BsLrlOBm3Y2RX62jl1%2BE6PRgTO7mLGqRW05yhdaCvbXBlM2t2RnLfYljPkhX12mf%2Fl7GCzwT1on5WIkk3uyfqdi%2FqDYq6IyvqoFuifkNT506KuqF3z6qrfAwfDMFQGVBOIRijBiZXPpqTNzG1snk0%2BVCIqgvgVJuC05IIWZ4bC2klC1NdnZqy6tSSDZq0o06tKvmMGpDJLOp2o9XUw56T0ALmHUuCOzVHP%2FocVks5LGnC2WqnCGf2PtuF0zPATc8088o%2Bm1VLod%2B16y6qC6MlWwJldSssat1QCVQnhdEAeueEMc9%2B3rYwtmxOLdlop9Mt%2F83qo50XSrDTPQkGSs3hzkumZT%2BEN%2B1I5zUV2Rr6luZvfWLzwpowp4PuNG%2FBXfSMfApLH%2Fw8Gvy0eBx1DkcH8Dg2FvvMQ%2Bk%2FUOwzjzacDkt0q7I2v%2B9ej1b1oxTlUP50nS%2FtancmZF3fjeqDm1W0iC6pRTo2G8vvu9ciVb0xADqnRWzeG%2Fvpw%2B%2F3A80YDNAGBmwUVWWOIFlHfXa61EE7RNbgkG03OW3z0ZMvS4Zm5m4HKKk2x2wc4lWU1p4%2FRTCcLW8UaKWKvj4DY4Nzwm3eCW8ZZD458ZWyuyizPaZnYaqbVxdcPouYCu62SKiHtPSlKU5MlWsXCjl8LiqFNH2jZoun6bPRf6Lyay7Idjh6hLlSMO5jMLwfBQqlvu2ALBMR2c1OZj6MY29W5v6e9FzOHuSTc4kTbyrlbRe%2B7E4lktO7hp67UCdecOM%2FwmIIejvoq%2BmPsEiEWHrs0xMECtrSqyGvWaf7ahp5%2FjXJHnkxWipf3aPmCf1zkVf51AbXV%2BPfyOAV%2Fhe4uNPuaVtS1t2A%2BW7uXdkaDLPhKNz76pbAMoM2fS%2Bg8BJagEn58WBS%2BY%2BWiWCy2kVJotijr%2Bw59g2Xm8vtb%2B%2B8DydXlGJBcv%2Fq7zcBUOU1i7645xINYEprgI69y6xI1HL2GqBEA1j8TKoDGoBHteBtqT%2Bet2UD3tsy7Ws7xTJfEmhp2pqXEexKB77eFSoHhGUEUgpz%2Fhj%2BbTyHX7%2FE%2Ftj4BKOPQfTPQDap3s6U2ALcF75MzagaCBP0piuNhUOEw9vHQGWhtxWuHECzKgIv6kttLAIqBF7kzqfpjHgFwz0GmP%2Bt2ef0R0zxDzIdzsxDpsa3%2B%2FMsyBQlyxXMI8RSJtTfow%2FluvRviAmKE3SSRCd8wms2KCRJrawiPEMx243n9E%2BAooUXLthjhEkXRJhTG4qSMGkLHZb0UW4qN6PK5Gbq%2B3KyJYrI8hlVYGpbTVWULdM8LkayBq9M7Qvo6XrPQnbyPNwndCPcPMzao3h4lH7b5uQJelKW1W%2BqQ3P%2F03y6zZNSB7aQlFpTpJR4XbiFEmoRMHWuCFHdV8u8ZImprSZp2i%2FNYAg%2Bsmsf%2BOhH7Cx1eeBr4bAVOyCudKmjOZGTp9Af6X3UavpFL0hXM%2F2MLArj3yBOCJlMGsFqI1THE8hKJig7FgmwqwjFKBlSBaYq1l3PknDB1sof16U3oTVBu1rT0Q9qGoEhmLaqouiCfbbC%2FCNG0a9P%2F7LFoVTFZ9Ge9NTJtgjV9eAigkFCkCgD%2BQVH35IRo%2Bh5dH4Ao9wI7%2BjyziOD9JgdgZSEWuwWfS%2F8ll5pSQhbreqe3aE6DZ89NJxhernpCseMVVM4iNczZrbna3%2BwoL2mJpoa7kGQrqg1TfvMhUW4To1aGPNMuHjiidhxqLEPqltzkpg1RS04VSL4li1blqmmEhu6WaBAKSVyIWYEWEZovqdY6kHxUNXU1Guue%2BC%2B4mmdg1oNHKyBY9tswevBdjF4abTOr0eErqcerG5Aw4u%2FEBy1QfHnfA%2Fxsl8SacQ%2B4JRiavGL6B06r9IBJ0FfupwjXMHrFCN%2FfEr%2FViJOfQyqmvIy%2BPUXBHkxYIq9F7tEsmSn%2B2LXrxuvTB9%2BW%2FcWFvEqXfLxCp%2F2FWtFw%2BTq3xpcuKt0TG4hqX5kxR2qDSb35sg0Oe3FltexDd0Q5NWn9ngyHtejP3Ref7S57I4QV5PXHXtFjIBD%2BY2n1XXVPgxPNFfDSDd3S0CnorpbSFub%2FA8%3D%3C%2Fdiagram%3E%3C%2Fmxfile%3E" />
+```
+
+### Output example in EventCatalog
+
+![Example output](../components/img/drawio.png)
+
+- [Example: View demo in custom documentation page](https://demo.eventcatalog.dev/docs/custom/guides/event-storming/01-index)
+
+### Props
+| Name                    | Type      | Default           | Required | Description                                                       |
+| ----------------------- | --------- | ----------------- | -------- | ----------------------------------------------------------------- |
+| `url`               | `string`  |               | Yes      | The URL of the DrawIO diagram to embed. To get the URL, click "File", "embed", then "Notion...", copy the URL to the component.
diff --git a/packages/core/docs/development/components/diagram-syntax/02-figjam.md b/packages/core/docs/development/components/diagram-syntax/02-figjam.md
new file mode 100644
index 000000000..1fc5c3a39
--- /dev/null
+++ b/packages/core/docs/development/components/diagram-syntax/02-figjam.md
@@ -0,0 +1,43 @@
+---
+sidebar_position: 2
+keywords:
+- components
+sidebar_label: FigJam
+title: <FigJam />
+description: Embed a FigJam diagram in your documentation
+id: figjam
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.34.6" />
+
+The `<FigJam />` component renders a [FigJam diagram](https://www.figma.com/figjam/) in your documentation.
+
+### Support
+
+The `<FigJam />` component is supported in domains, services, all messages and [custom documentation](/docs/development/bring-your-own-documentation/custom-pages/introduction).
+
+### Usage
+
+1. Include the `<FigJam />` component inside the markdown
+    - e.g `/events/MyEvent/index.mdx`
+
+**Basic Example**
+
+```md /events/OrderAmended/index.mdx
+---
+#event frontmatter
+---
+
+<FigJam url="{embed_url_from_figjam}" />
+```
+
+### Output example in EventCatalog
+
+![Example output](../components/img/figjam.png)
+
+### Props
+| Name                    | Type      | Default           | Required | Description                                                       |
+| ----------------------- | --------- | ----------------- | -------- | ----------------------------------------------------------------- |
+| `url`               | `string`  |               | Yes      | The embed URL of the FigJam diagram. To get the URL, click "Shared", "Get embed code", then copy the URL from the iframe.
diff --git a/packages/core/docs/development/components/diagram-syntax/03-icepanel.md b/packages/core/docs/development/components/diagram-syntax/03-icepanel.md
new file mode 100644
index 000000000..f64fb137d
--- /dev/null
+++ b/packages/core/docs/development/components/diagram-syntax/03-icepanel.md
@@ -0,0 +1,74 @@
+---
+sidebar_position: 3
+keywords:
+- icepanel
+- diagrams
+- architecture
+sidebar_label: IcePanel
+title: Using IcePanel
+description: Understanding how to embed IcePanel diagrams in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.2.1" />
+
+EventCatalog supports embedding [IcePanel](https://icepanel.io/) diagrams in all your markdown files.
+
+IcePanel is a collaborative diagramming tool designed for visualizing software architecture using the [C4 model](https://c4model.com/). It helps teams create interactive system context, container, and component diagrams that can be shared and explored.
+
+![Example output](/img/ice-panel.png)
+
+## Using IcePanel in EventCatalog
+
+To embed an IcePanel diagram, use the `<IcePanel />` component in any markdown file.
+
+### Getting your IcePanel share URL
+
+1. Open your diagram in IcePanel
+2. Click the **Share** button
+3. Copy the share/embed URL (it should look like `https://s.icepanel.io/...`)
+
+### Basic Example
+
+```markdown
+---
+# your frontmatter
+---
+
+<IcePanel url="https://s.icepanel.io/OpQVdslrqhZkyb/0QfB" />
+```
+
+### Example with title and description
+
+```markdown
+---
+# your frontmatter
+---
+
+<IcePanel
+  url="https://s.icepanel.io/OpQVdslrqhZkyb/0QfB"
+  title="System Architecture"
+  description="Overview of our microservices architecture showing how services communicate."
+  height="800"
+/>
+```
+
+### Full screen mode
+
+Each embedded IcePanel diagram includes a full screen button, allowing your teams to explore the diagram in detail without leaving EventCatalog.
+
+### Props
+
+| Name          | Type     | Default | Required | Description                                                                                                     |
+| ------------- | -------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `url`         | `string` |         | Yes      | The share URL of the IcePanel diagram. To get the URL, click "Share" in IcePanel and copy the embed/share URL. |
+| `title`       | `string` |         | No       | The title to display above the diagram.                                                                         |
+| `description` | `string` |         | No       | A description to display below the title.                                                                       |
+| `height`      | `string` | `600`   | No       | The height of the embedded diagram in pixels.                                                                   |
+| `width`       | `string` | `100%`  | No       | The width of the embedded diagram.                                                                              |
+
+### More resources
+
+- [IcePanel documentation](https://docs.icepanel.io/) - Learn more about IcePanel and how to use it
+- [C4 model](https://c4model.com/) - Learn about the C4 model for visualizing software architecture
diff --git a/packages/core/docs/development/components/diagram-syntax/04-likec4.md b/packages/core/docs/development/components/diagram-syntax/04-likec4.md
new file mode 100644
index 000000000..737d65bed
--- /dev/null
+++ b/packages/core/docs/development/components/diagram-syntax/04-likec4.md
@@ -0,0 +1,136 @@
+---
+sidebar_position: 4
+keywords:
+- likec4
+- diagrams
+- architecture
+- c4
+sidebar_label: LikeC4
+title: Using LikeC4
+description: Embed LikeC4 architecture diagrams in EventCatalog pages
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.47.2" />
+
+EventCatalog supports embedding [LikeC4](https://likec4.dev) diagrams in all your markdown files via the `<LikeC4View />` component.
+
+LikeC4 is an architecture-as-code tool that lets you model and visualize your system landscape using `.c4` source files. Views defined in those files can be rendered directly inside EventCatalog documentation pages.
+
+## Install dependencies
+
+LikeC4 support is opt-in. Add the required packages as dev dependencies in your EventCatalog project:
+
+```bash
+# npm
+npm install --save-dev likec4@1.55.1 @likec4/icons@1.46.4
+
+# pnpm
+pnpm add -D likec4@1.55.1 @likec4/icons@1.46.4
+
+# yarn
+yarn add -D likec4@1.55.1 @likec4/icons@1.46.4
+```
+
+EventCatalog uses React 18, so install `likec4@1.55.1`. Newer LikeC4 versions may require React 19.
+
+EventCatalog auto-detects `.c4` files in your project. When it finds them it loads the LikeC4 Vite plugin automatically. If `.c4` files are present but the `likec4` package is not installed, EventCatalog will show an install message at startup.
+
+## Basic usage
+
+Add `.c4` source files anywhere in your EventCatalog project (outside `node_modules`), then reference a view by its id using `<LikeC4View />` in any markdown file.
+
+```likec4 /likec4/order-flow.c4
+specification {
+  element actor {
+    style {
+      shape person
+    }
+  }
+  element system
+}
+
+model {
+  customer = actor 'Customer'
+  ordering = system 'Ordering service'
+  payment = system 'Payment service'
+  fulfillment = system 'Fulfillment service'
+
+  customer -> ordering 'places order'
+  ordering -> payment 'authorizes payment'
+  ordering -> fulfillment 'requests shipment'
+}
+
+views {
+  view OrderFlow {
+    include *
+    autoLayout LeftRight
+  }
+}
+```
+
+```md /events/OrderCreated/index.mdx
+---
+# event frontmatter
+---
+
+<LikeC4View viewId="OrderFlow" height={300} />
+```
+
+## Multi-project setup
+
+When your workspace contains more than one LikeC4 project, each project needs a `likec4.config.json` file with a `name` field. EventCatalog reads these files at build time and registers each named project separately.
+
+```json likec4.config.json
+{
+  "name": "payments"
+}
+```
+
+A common layout is to keep each project in its own folder, with the `likec4.config.json` alongside the `.c4` files that belong to it. EventCatalog scans your whole project (outside `node_modules`), so you can place these folders wherever makes sense for your catalog:
+
+```
+your-catalog/
+├── eventcatalog.config.js
+├── likec4/
+│   ├── payments/
+│   │   ├── likec4.config.json    # { "name": "payments" }
+│   │   ├── model.c4
+│   │   └── views.c4
+│   └── orders/
+│       ├── likec4.config.json    # { "name": "orders" }
+│       ├── model.c4
+│       └── views.c4
+├── services/
+│   └── PaymentsService/
+│       └── index.mdx             # <LikeC4View viewId="..." project="payments" />
+└── events/
+    └── OrderCreated/
+        └── index.mdx
+```
+
+Pass the `project` prop to load a view from a specific project:
+
+```md /services/PaymentsService/index.mdx
+---
+# service frontmatter
+---
+
+<LikeC4View viewId="PaymentsOverview" project="payments" />
+```
+
+When `project` is omitted, the component uses the default (unnamed) project.
+
+## Props
+
+| Name      | Type     | Default  | Required | Description                                                                   |
+| --------- | -------- | -------- | -------- | ----------------------------------------------------------------------------- |
+| `viewId`  | `string` |          | Yes      | The id of the LikeC4 view to render.                                          |
+| `project` | `string` |          | No       | The name of the LikeC4 project (from `likec4.config.json`). Defaults to the default project. |
+| `height`  | `string` | `600px`  | No       | CSS height of the embedded diagram.                                           |
+
+## More resources
+
+- [LikeC4 documentation](https://likec4.dev/docs/) - Learn how to model your architecture with LikeC4
+- [LikeC4 view syntax](https://likec4.dev/docs/dsl/views/) - Reference for defining views in `.c4` files
diff --git a/packages/core/docs/development/components/diagram-syntax/05-lucid.md b/packages/core/docs/development/components/diagram-syntax/05-lucid.md
new file mode 100644
index 000000000..b12133ddf
--- /dev/null
+++ b/packages/core/docs/development/components/diagram-syntax/05-lucid.md
@@ -0,0 +1,46 @@
+---
+sidebar_position: 5
+keywords:
+- components
+sidebar_label: Lucid
+title: <Lucid />
+description: Embed a Lucid diagram in your documentation
+id: lucid
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.34.4" />
+
+The `<Lucid />` component renders a [Lucid diagram](https://lucid.app/) in your documentation.
+
+### Support
+
+The `<Lucid />` component is supported in domains, services, all messages and [custom documentation](/docs/development/bring-your-own-documentation/custom-pages/introduction).
+
+### Usage
+
+1. Include the `<Lucid />` component inside the markdown
+    - e.g `/events/MyEvent/index.mdx`
+
+**Basic Example**
+
+```md /events/OrderAmended/index.mdx
+---
+#event frontmatter
+---
+
+<Lucid diagramId="e29f42a0-67e2-4f80-b0d7-6922bb7dd9c5" />
+```
+
+### Output example in EventCatalog
+
+![Example output](../components/img/lucid.png)
+
+- [Example: View demo in a domain page](https://demo.eventcatalog.dev/docs/domains/Orders/0.0.3)
+- [Example: View demo in custom documentation page](https://demo.eventcatalog.dev/docs/custom/guides/event-storming/01-index)
+
+### Props
+| Name                    | Type      | Default           | Required | Description                                                       |
+| ----------------------- | --------- | ----------------- | -------- | ----------------------------------------------------------------- |
+| `diagramId`               | `string`  |               | Yes      | The ID of the Lucid diagram to embed. You can find the ID in the URL of the Lucid diagram or by clicking "Share" in Lucid and copying the ID from the URL.
diff --git a/packages/core/docs/development/components/diagram-syntax/06-mermaid.md b/packages/core/docs/development/components/diagram-syntax/06-mermaid.md
new file mode 100644
index 000000000..df672551c
--- /dev/null
+++ b/packages/core/docs/development/components/diagram-syntax/06-mermaid.md
@@ -0,0 +1,218 @@
+---
+sidebar_position: 6
+keywords:
+- mermaid
+sidebar_label: Mermaid
+title: Using mermaid
+description: Understanding how to use mermaid with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<!-- 2.56.4 -->
+
+EventCatalog supports [mermaid](https://www.npmjs.com/package/mermaid) (v11.x) in all your markdown files.
+
+This let's you create [Class Diagrams](https://mermaid.js.org/syntax/classDiagram.html), [Sequence Diagrams](https://mermaid.js.org/syntax/sequenceDiagram.html), [Entity Relationship Diagrams](https://mermaid.js.org/syntax/entityRelationshipDiagram.html), [Architecture Diagrams](https://mermaid.js.org/syntax/architecture.html) and much more.
+
+## Using mermaid in EventCatalog
+
+There are two ways to use mermaid in EventCatalog.
+
+1. [Using the `mermaid` code block in any markdown file.](#using-the-mermaid-code-block-in-any-markdown-file)
+2. [Using Mermaid files `.mmd` and `.mermaid` files and loading them into your EventCatalog page.](#loading-mermaid-files-into-your-eventcatalog-page)
+    - _Added in EventCatalog 2.56.4_
+
+:::tip Diagrams not rendering?
+If you have large diagrams that fail to render, increase the `maxTextSize` configuration value. [Learn more about maxTextSize configuration](/docs/api/config#mermaid).
+:::
+
+### Using the `mermaid` code block in any markdown file.
+
+To use mermaid you need to use the `mermaid` code block in any markdown file.
+
+#### Example
+
+```markdown
+```mermaid
+sequenceDiagram
+    participant Customer
+    participant OrdersService
+    participant InventoryService
+    participant NotificationService
+
+    Customer->>OrdersService: Place Order
+    OrdersService->>InventoryService: Check Inventory
+    InventoryService-->>OrdersService: Inventory Available
+    OrdersService->>InventoryService: Reserve Inventory
+    OrdersService->>NotificationService: Send Order Confirmation
+    NotificationService-->>Customer: Order Confirmation
+    OrdersService->>Customer: Order Placed Successfully
+    OrdersService->>InventoryService: Update Inventory
+```_
+```
+
+This example will output the following in the markdown file.
+
+![Example output of mermaid](../img/mermaid.png)
+
+### Loading Mermaid files into your EventCatalog page.
+
+<AddedIn version="2.56.4" />
+
+You can load Mermaid files using the [`<MermaidFileLoader />`](/docs/development/components/components/mermaid-file-loader) component, if you prefer to use a file instead of a code block.
+
+Add your .mmd or .mermaid file to your folder (e.g `/events/MyEvent/mermaid.mmd`)
+
+```md /events/MyEvent/index.mdx
+---
+#event frontmatter
+---
+
+<!-- Using the .mmd file extension -->
+<MermaidFileLoader file="mermaid.mmd" />
+
+<!-- Using the .mermaid file extension -->
+<MermaidFileLoader file="my-second-mermaid-file.mermaid" />
+```
+
+This example will load a mermaid file (.mmd or .mermaid) into your EventCatalog page.
+
+**The file must be in the same directory as the markdown file.**
+
+---
+
+## Architecture diagrams with mermaid
+
+<AddedIn version="2.18.0" />
+
+Mermaid 11 introduced the [ability to create architecture diagrams](https://mermaid.js.org/syntax/architecture.html).
+
+You can use these diagrams to document your architecture.
+
+#### Example
+
+```markdown
+```mermaid
+architecture-beta
+    group api(cloud)[API]
+
+    service db(database)[Database] in api
+    service disk1(disk)[Storage] in api
+    service disk2(disk)[Storage] in api
+    service server(server)[Server] in api
+
+    db:L -- R:server
+    disk1:T -- B:server
+    disk2:T -- B:db
+
+```_
+```
+
+This example will output the following in the markdown file.
+
+<img src="/img/mermaid/mermaid-architecture.png" alt="Example output of mermaid" style={{width: "30%"}}/>
+
+## Architecture diagrams with icons
+
+<AddedIn version="2.18.0" />
+
+EventCatalog supports over **200,000 icons** from [icones.js.org](https://icones.js.org/collection/logos).
+
+To add icon support you need to add the icon pack into your `eventcatalog.config.js` file.
+
+```js
+// eventcatalog.config.js
+mermaid: {
+  iconPacks: ['logos'] // will load https://icones.js.org/collection/logos into eventcatalog
+}
+```
+
+In this example above we import the icon pack [logos](https://icones.js.org/collection/logos) from [icones.js.org](https://icones.js.org/collection/logos), but you can import any icon pack you like from [icones.js.org](https://icones.js.org/collection/logos).
+
+To use the icons in your mermaid diagrams you need to prefix the icon name with pack name. 
+
+In this example we are using the `logos` pack, so we prefix the icon name with `logos:`.
+
+```markdown
+```mermaid
+architecture-beta
+    group api(logos:aws-lambda)[API]
+
+    service db(logos:aws-aurora)[Database] in api
+    service disk1(logos:aws-glacier)[Storage] in api
+    service disk2(logos:aws-s3)[Storage] in api
+    service server(logos:aws-ec2)[Server] in api
+
+    db:L -- R:server
+    disk1:T -- B:server
+    disk2:T -- B:db
+```_
+```
+
+EventCatalog will then import the icons from the icon pack and render them in the diagram.
+
+<img src="/img/mermaid/mermaid-custom-icons.png" alt="Example output of mermaid" style={{width: "30%"}}/>
+
+## Mermaid with ELK (Eclipse Layout Kernel) layout algorithm
+
+<AddedIn version="2.61.2" />
+
+EventCatalog supports the [ELK (Eclipse Layout Kernel)](https://eclipse.dev/elk/) layout algorithm for mermaid diagrams.
+
+To add support for the ELK layout algorithm you need to add the following to your `eventcatalog.config.js` file.
+
+```js
+// eventcatalog.config.js
+mermaid: {
+  // default value is false
+  enableSupportForElkLayout: true
+}
+```
+
+After you set the value, mermaid will be configured to use the ELK layout algorithm.
+
+## Interactive controls
+
+<AddedIn version="3.4.1" />
+
+All Mermaid diagrams include interactive controls for better viewing and exploration.
+
+![Example output of mermaid](../img/interactive.png)
+
+### Zoom and pan
+
+Click and drag to pan around the diagram, or use the zoom controls in the bottom-left corner to zoom in and out. Double-click the diagram to zoom in quickly.
+
+### Presentation mode
+
+Click the presentation button in the top-left corner to view the diagram in fullscreen. In presentation mode, mouse wheel zooming is enabled for precise control.
+
+Press `Escape` to exit presentation mode.
+
+### Copy diagram code
+
+Click the copy button in the top-right corner to copy the diagram code to your clipboard. 
+
+Useful for copying diagrams into LLM prompts.
+
+## Export NodeGraphs as Mermaid
+
+<AddedIn version="3.9.0" />
+
+EventCatalog can export any NodeGraph visualization as Mermaid diagram code.
+
+Click the view switcher dropdown in any NodeGraph and select "Copy as Mermaid" to copy the diagram to your clipboard. The exported diagram preserves all nodes, edges, labels, and styling.
+
+You can then paste the Mermaid code into:
+- LLM prompts for architecture discussions
+- Other documentation tools
+- [mermaid.live](https://mermaid.live) for further editing
+- Mermaid code blocks in EventCatalog pages
+
+[Read more about NodeGraph controls](/docs/development/components/components/nodegraph#interactive-controls)
+
+### More resources
+
+- [Mermaid documentation](https://mermaid.js.org) - Learn more about mermaid and how to use it
+- [Icon packs](https://icones.js.org/) - Explore over 200,000 icons from iconify
diff --git a/packages/core/docs/development/components/diagram-syntax/07-miro.md b/packages/core/docs/development/components/diagram-syntax/07-miro.md
new file mode 100644
index 000000000..bc5408767
--- /dev/null
+++ b/packages/core/docs/development/components/diagram-syntax/07-miro.md
@@ -0,0 +1,63 @@
+---
+sidebar_position: 7
+keywords:
+- components
+sidebar_label: Miro
+title: <Miro />
+description: Embed a Miro board in your documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.33.4" />
+
+The `<Miro />` component renders a [Miro board](https://miro.com/) in your documentation.
+
+Each Miro board embedded can also be loaded in a full screen mode, letting your teams edit the board live ([view demo](https://demo.eventcatalog.dev/miro?autoplay=true&embedMode=view_only_without_ui&moveToWidget=3074457347671667709&boardId=uXjVIHCImos=/&back=/docs/domains/Orders/0.0.3)).
+
+### Support
+
+The `<Miro />` component is supported in domains, services, all messages and [custom documentation](/docs/development/bring-your-own-documentation/custom-pages/introduction).
+
+### Usage
+
+1. Include the `<Miro />` component inside the markdown
+    - e.g `/events/MyEvent/index.mdx`
+
+**Basic Example**
+
+```md /events/OrderAmended/index.mdx
+---
+#event frontmatter
+---
+
+<Miro boardId="uXjVIHCImos=/" edit={false} />
+```
+**Example with edit enabled and scroll to default widget in Miro**
+
+```md /events/OrderAmended/index.mdx
+---
+#event frontmatter
+---
+
+<Miro boardId="uXjVIHCImos=/" moveToWidget="3074457347671667709" edit={false} />
+```
+
+### Output example in EventCatalog
+
+![Example output](../components/img/miro.png)
+
+- [Example: View demo in a domain page](https://demo.eventcatalog.dev/docs/domains/Orders/0.0.3)
+- [Example: View demo in custom documentation page](https://demo.eventcatalog.dev/docs/custom/guides/event-storming/01-index)
+- [Example: View demo of screen Miro board in EventCatalog](https://demo.eventcatalog.dev/miro?autoplay=true&embedMode=view_only_without_ui&moveToWidget=3074457347671667709&boardId=uXjVIHCImos=/&back=/docs/domains/Orders/0.0.3#undefined-miro-title)
+
+### Props
+| Name                    | Type      | Default           | Required | Description                                                       |
+| ----------------------- | --------- | ----------------- | -------- | ----------------------------------------------------------------- |
+| `boardId`               | `string`  |               | Yes      | The ID of the Miro board to embed. ([miro docs](https://developers.miro.com/docs/miro-live-embed-with-a-direct-link#get-the-board-id))
+| `edit`                  | `boolean` | `false`           | No       | Whether to enable edit mode for the Miro board.                    |
+| `moveToViewport`        | `string`  |        | No       | The ID of the widget to scroll to. ([miro docs](https://developers.miro.com/docs/miro-live-embed-with-a-direct-link#set-the-initial-view-based-on-a-specific-viewport))                                |
+| `moveToWidget`          | `string`  |        | No       | The ID of the widget to scroll to. ([miro docs](https://developers.miro.com/docs/miro-live-embed-with-a-direct-link#set-the-initial-view-based-on-a-specific-board-item))                                |
+| `height`                | `string`  | `500`             | No       | The height of the Miro board.                                        |
+| `title`                 | `string`  |        | No       | The title of the Miro board.                                        |
+| `autoplay`              | `boolean` | `true`            | No       | Whether to skip the preloader of the miro board. ([miro docs](https://developers.miro.com/docs/miro-live-embed-with-a-direct-link#skip-the-preloader-screen))                                  |
diff --git a/packages/core/docs/development/components/diagram-syntax/08-plantuml.md b/packages/core/docs/development/components/diagram-syntax/08-plantuml.md
new file mode 100644
index 000000000..87494ad14
--- /dev/null
+++ b/packages/core/docs/development/components/diagram-syntax/08-plantuml.md
@@ -0,0 +1,140 @@
+---
+sidebar_position: 8
+keywords:
+- plantuml
+sidebar_label: PlantUML
+title: Using PlantUML
+description: Understanding how to use plantuml with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.46.0" />
+
+EventCatalog supports [PlantUML](https://plantuml.com/) in all your markdown files.
+
+This let's you create [Class Diagrams](https://plantuml.com/class-diagram), [Sequence Diagrams](https://plantuml.com/sequence-diagram), [Class Diagrams](https://plantuml.com/class-diagram), [State Diagrams](https://plantuml.com/state-diagram) and much more.
+
+## Using plantuml in EventCatalog
+
+To use plantuml you need to use the `plantuml` code block in any markdown file.
+
+#### Example
+
+```markdown
+```plantuml
+@startuml
+!define Table(name,desc) class name as "desc" << (T,#E5E7EB) >>
+!define PK(x) <u>x</u>
+!define FK(x) <i>x</i>
+
+' ===== Core Tables =====
+
+Table(Customers, "Customers") {
+  PK(customerId): UUID
+  firstName: VARCHAR
+  lastName: VARCHAR
+  email: VARCHAR
+  phone: VARCHAR
+  dateRegistered: TIMESTAMP
+}
+
+Table(Orders, "Orders") {
+  PK(orderId): UUID
+  FK(customerId): UUID
+  orderDate: TIMESTAMP
+  status: VARCHAR
+  totalAmount: DECIMAL
+}
+
+Table(Products, "Products") {
+  PK(productId): UUID
+  name: VARCHAR
+  description: TEXT
+  price: DECIMAL
+  stockQuantity: INT
+}
+
+Table(OrderItems, "Order Items") {
+  PK(id): UUID
+  FK(orderId): UUID
+  FK(productId): UUID
+  quantity: INT
+  unitPrice: DECIMAL
+}
+
+Table(Payments, "Payments") {
+  PK(paymentId): UUID
+  FK(orderId): UUID
+  amount: DECIMAL
+  method: VARCHAR
+  status: VARCHAR
+  paidAt: TIMESTAMP
+}
+
+Table(InventoryEvents, "Inventory Events") {
+  PK(eventId): UUID
+  FK(productId): UUID
+  eventType: VARCHAR
+  quantityChange: INT
+  eventTime: TIMESTAMP
+}
+
+Table(Subscription, "Subscriptions") {
+  PK(subscriptionId): UUID
+  FK(customerId): UUID
+  plan: VARCHAR
+  status: VARCHAR
+  startDate: TIMESTAMP
+  endDate: TIMESTAMP
+}
+
+' ===== Relationships =====
+
+Customers ||--o{ Orders : places
+Orders ||--o{ OrderItems : contains
+Products ||--o{ OrderItems : includes
+Orders ||--o{ Payments : paid_by
+Products ||--o{ InventoryEvents : logs
+Customers ||--o{ Subscription : subscribes
+
+@enduml
+```_
+```
+
+This example will output the following in the markdown file.
+
+![Example output of plantuml](../img/plantuml.png)
+
+### How it works?
+
+The PlantUML implementation takes your content and converts it to a PNG image using https://www.plantuml.com/plantuml/svg.
+
+![Example output of plantuml](../img/interactive.png)
+
+## Interactive controls
+
+<AddedIn version="3.5.0" />
+
+All PlantUML diagrams include interactive controls for better viewing and exploration.
+
+### Zoom and pan
+
+Click and drag to pan around the diagram, or use the zoom controls in the bottom-left corner to zoom in and out. Double-click the diagram to zoom in quickly.
+
+### Presentation mode
+
+Click the presentation button in the top-left corner to view the diagram in fullscreen. In presentation mode, mouse wheel zooming is enabled for precise control.
+
+Press `Escape` to exit presentation mode.
+
+### Copy diagram code
+
+Click the copy button in the top-right corner to copy the diagram code to your clipboard. 
+
+Useful for copying diagrams into LLM prompts.
+
+### More resources
+
+- [PlantUML documentation](https://plantuml.com) - Learn more about plantuml and how to use it
+- [Real world examples](https://real-world-plantuml.com/) - Real world examples of plantuml in use
diff --git a/packages/core/docs/development/components/diagram-syntax/09-structurizr.md b/packages/core/docs/development/components/diagram-syntax/09-structurizr.md
new file mode 100644
index 000000000..32441d9a1
--- /dev/null
+++ b/packages/core/docs/development/components/diagram-syntax/09-structurizr.md
@@ -0,0 +1,24 @@
+---
+sidebar_position: 9
+keywords:
+- mermaid
+sidebar_label: Structurizr
+title: Using Structurizr
+description: Understanding how to use Structurizr with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.56.4" />
+
+You can embed your [Structurizr diagrams](https://structurizr.com/) into your EventCatalog pages using the [`<MermaidFileLoader />`](/docs/development/components/components/mermaid-file-loader) component.
+
+You will need to export your Structurizr diagrams into mermaid files and then use the [`<MermaidFileLoader />`](/docs/development/components/components/mermaid-file-loader) component to embed them into your EventCatalog pages.
+
+## How to export your Structurizr diagrams into mermaid files
+
+You will need to use the Structurizr CLI to export your diagrams into mermaid files.
+
+1. [Install the Structurizr CLI](https://docs.structurizr.com/cli/installation)
+2. [Export your diagrams into mermaid files](https://docs.structurizr.com/cli/export)
+3. Use the [`<MermaidFileLoader />`](/docs/development/components/components/mermaid-file-loader) component to embed them into your EventCatalog pages.
diff --git a/packages/core/docs/development/components/diagram-syntax/_category_.json b/packages/core/docs/development/components/diagram-syntax/_category_.json
new file mode 100644
index 000000000..5ceb52a3a
--- /dev/null
+++ b/packages/core/docs/development/components/diagram-syntax/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Embed Diagrams",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "components/diagram-syntax",
+    "title": "Diagrams",
+    "description": "Use diagram languages and tools inside EventCatalog documentation."
+  }
+}
diff --git a/packages/core/docs/development/customization/01-customize-landing-page.md b/packages/core/docs/development/customization/01-customize-landing-page.md
new file mode 100644
index 000000000..fd880a0fe
--- /dev/null
+++ b/packages/core/docs/development/customization/01-customize-landing-page.md
@@ -0,0 +1,147 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog landing page
+sidebar_label: Custom homepage
+title: Customize landing page
+description: Customize landing pages in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+EventCatalog provides a landing page for your catalog, this is the first page that users see when they visit your catalog. 
+
+You can customize the landing page with your own content, HTML and EventCatalog components.
+
+### Example of a custom landing page
+
+You can add any HTML you want to your landing page, in this example we have added custom content using EventCatalog components, which includes the
+visualizer for a domains, subdomains and flows.
+
+<div className="space-y-2 text-center mb-8">
+<img src="/img/landing-page-example.png" alt="EventCatalog Custom Landing Page" className="rounded-lg mb-0" />
+<a href="https://demo.eventcatalog.dev" className="block p-0 m-0">View custom landing page demo</a>
+</div>
+
+## How to customize your landing page
+
+1. Create a new folder called `pages` and an Astro file called `homepage.astro`
+    - Example: `/pages/homepage.astro`
+1. Add the contents to your Astro file.
+    - You can see a full example of this on our [GitHub repository](https://github.com/event-catalog/eventcatalog/blob/main/examples/default/pages/homepage.astro).
+1. Run `npm run dev` or `npm run build` to see your changes.
+
+:::info What is Astro?
+[Astro](https://astro.build/) is a static site builder that powers EventCatalog. You can learn more about Astro [here](https://docs.astro.build/en/getting-started/).
+:::
+
+**Example of homepage.astro**
+
+```md title="/pages/homepage.astro"
+---
+# Import EventCatalog components to use in your landing page
+const { Tile, Tiles, Flow, NodeGraph, Admonition } = Astro.props.components;
+---
+
+<div class="p-8 pt-2 max-w-8xl mx-auto">
+  <h1 class="text-4xl font-bold text-gray-800 mb-4">Welcome to FlowMart's EventCatalog</h1>
+  <p class="text-lg text-gray-600 mb-8">Explore the events, services, and domains that power the FlowMart ecosystem. This catalog provides a centralized place to discover and understand our asynchronous architecture.</p>
+
+  <Admonition type="info" title="Demo application">
+    <p>This is a demo of the EventCatalog and what it can do. The company is called FlowMart and they are an e-commerce company.</p>
+    <p>Using EventCatalog, we documented their systems (domains, services, events, commands, flows) and how they fit together.</p>
+  </Admonition>
+
+  <div class="grid grid-cols-2 gap-4 border-b border-gray-200 pb-8 pt-4">
+    <div class="col-span-1">
+      <h2 class="text-2xl font-semibold text-gray-700 mb-2">E-Commerce Domain</h2>
+      <p class="text-gray-500 mb-2">The core domain of FlowMart, responsible for all e-commerce operations.</p>
+      <NodeGraph id="E-Commerce" version="1.0.0" type="domain" />
+    </div>
+    <div class="col-span-1">
+      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Orders Domain</h2>
+      <p class="text-gray-500 mb-2">The sub-domain responsible for all orders.</p>
+      <NodeGraph id="Orders" version="0.0.3" type="domain" />
+    </div>
+    <div class="col-span-1">
+      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Payment Domain</h2>
+      <p class="text-gray-500 mb-2">The sub-domain responsible for all payments.</p>
+      <NodeGraph id="Payment" version="0.0.1" type="domain" />
+    </div>
+    <div class="col-span-1">
+      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Subscription Domain</h2>
+      <p class="text-gray-500 mb-2">The sub-domain responsible for all subscriptions.</p>
+      <NodeGraph id="Subscription" version="0.0.1" type="domain" />
+    </div>
+  </div>
+
+  <div class="bg-blue-50 p-6 rounded-lg shadow-md mb-12">
+    <h2 class="text-2xl font-semibold text-blue-800 mb-3">Discover Our Architecture</h2>
+    <p class="text-gray-700 mb-4">
+      Navigate through our Domains to understand the different business capabilities, explore Services to see the microservices involved, and dive into Events and Commands to see how they communicate.
+    </p>
+    <p class="text-gray-700">
+      Use the search bar above or browse the sections in the sidebar to get started.
+    </p>
+  </div>
+
+  <div class="grid grid-cols-2 gap-4 border-b border-gray-200 pb-8">
+    <div class="col-span-1">
+      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Cancel Subscription Flow</h2>
+      <p class="text-gray-500 mb-2">This flow is triggered when a user cancels their subscription.</p>
+      <Flow id="CancelSubscription" version="latest" includeKey={false} />
+    </div>
+    <div class="col-span-1">
+      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Payment Flow</h2>
+      <p class="text-gray-500 mb-2">This flow documents how a payment is processed at FlowMart.</p>
+      <Flow id="PaymentFlow" version="latest" includeKey={false} />
+    </div>
+  </div>
+
+  <div class="border-b border-gray-200 pb-8 py-4">
+    <h2 class="text-3xl font-semibold text-gray-700 py-4">Quick Links</h2>
+    <p class="text-gray-700 mb-4">Learn how to get started with EventCatalog, create domains, services, events, and commands.</p>
+    <Tiles columns={3}>
+      <Tile icon="BookOpenIcon" href="https://eventcatalog.dev/docs/development/getting-started" title="Getting started with EventCatalog" description="How to get started with EventCatalog" />
+      <Tile icon="RectangleGroupIcon" href="https://eventcatalog.dev/docs/development/guides/domains/create-domain" title="Create a domain" description="Learn how to create domains in your event catalog" />
+      <Tile icon="ServerIcon" href="https://eventcatalog.dev/docs/development/guides/resources/services/create-service" title="Creating services" description="Learn how to create services in your event catalog" />
+      <Tile icon="ChatBubbleLeftIcon" iconColor="text-blue-500" href="https://eventcatalog.dev/docs/development/guides/resources/messages/message-types/commands" title="Creating commands" description="Learn how to create commands in your event catalog" />
+      <Tile icon="BoltIcon" iconColor="text-orange-500" href="https://eventcatalog.dev/docs/development/guides/resources/messages/message-types/events" title="Creating events" description="Learn how to create events in your event catalog" />
+      <Tile icon="UserGroupIcon" iconColor="text-green-500" href="https://eventcatalog.dev/docs/owners" title="Assigning owners to resources" description="Learn how to assign owners to resources in your event catalog" />
+    </Tiles>
+  </div>
+
+  <div class="pb-8 py-4">
+    <h2 class="text-3xl font-semibold text-gray-700 mb-6 pt-4">Join the community</h2>
+
+    <p class="text-gray-700 mb-4">Our project and community is growing fast. We have over 1000+ members in our <a href="https://eventcatalog.dev/discord" class="text-blue-500 hover:text-blue-600">Discord community</a>.</p>
+
+    <Tiles columns={2}>
+      <Tile icon="UserGroupIcon" iconColor="text-green-500" href="https://eventcatalog.dev/discord" title="Join the Discord community" description="Join the community to get help and support" />
+      <Tile icon="StarIcon"  iconColor="text-yellow-500" href="https://github.com/event-catalog/eventcatalog/stargazers" title="Star EventCatalog on GitHub" description="If you like the project, please star it on GitHub to show your support ❤️" />
+    </Tiles>
+  </div>
+
+</div>
+
+
+```
+
+See the example output [here](https://demo.eventcatalog.dev)
+
+
+### Using components
+
+You can use EventCatalog components in your custom landing page.
+
+These include embedding visuals, flows, and more.
+
+Example:
+
+```md
+<Tiles columns={3}>
+  <Tile icon="BookOpenIcon" href="https://eventcatalog.dev/docs/development/getting-started" title="Getting started with EventCatalog" description="How to get started with EventCatalog" />
+</Tiles>
+```
+
+You can get a list of components [here](/docs/components).
diff --git a/packages/core/docs/development/customization/02-themes.md b/packages/core/docs/development/customization/02-themes.md
new file mode 100644
index 000000000..626ea197e
--- /dev/null
+++ b/packages/core/docs/development/customization/02-themes.md
@@ -0,0 +1,430 @@
+---
+sidebar_position: 6
+keywords:
+  - EventCatalog themes
+  - dark mode
+  - light mode
+  - customization
+  - custom theme
+sidebar_label: Themes
+title: Themes
+description: Customize the look and feel of your catalog with built-in themes, dark/light mode, and custom themes
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+EventCatalog comes with a selection of built-in themes and supports both light and dark modes out of the box.
+
+## Choosing a theme
+
+To set a theme, add the `theme` property to your `eventcatalog.config.js` file:
+
+```js title="eventcatalog.config.js"
+export default {
+  // ... other config
+  theme: 'sapphire',
+};
+```
+
+### Available themes
+
+EventCatalog includes the following built-in themes:
+
+| Theme | Description |
+|-------|-------------|
+| `default` | Purple accent - the original EventCatalog look |
+| `ocean` | Teal accent - calm and professional |
+| `sapphire` | Blue accent - premium enterprise feel |
+| `sunset` | Orange accent - warm and energetic |
+| `forest` | Dark green accent - natural and grounded |
+
+
+## Light and dark mode
+
+EventCatalog supports both light and dark modes. Users can toggle between modes using the theme switcher in the header.
+
+### How it works
+
+- The theme toggle appears in the header navigation
+- **System preference by default**: New visitors see light or dark mode based on their operating system preference
+- **Remembers user choice**: Once a user manually toggles the theme, their preference is saved and used on future visits
+- **Syncs across tabs**: Theme changes sync across browser tabs
+- **Responds to system changes**: If no manual preference is set, the theme automatically updates when the user changes their OS dark mode setting
+
+### Theme persistence
+
+When a user manually selects light or dark mode, their preference is stored in `localStorage` under the key `eventcatalog-theme`. This ensures their choice persists across page reloads and browser sessions.
+
+If no preference is stored, EventCatalog automatically follows the user's system preference using the `prefers-color-scheme` media query.
+
+---
+
+## Creating custom themes
+
+<PlanBanner plan="Scale" />
+
+Custom themes allow you to fully brand EventCatalog with your organization's colors. You define your theme in `eventcatalog.styles.css` using CSS variables.
+
+### Step 1: Create your theme CSS
+
+Add your custom theme to `eventcatalog.styles.css` in your project root. Your theme needs to define CSS variables for both light and dark modes.
+
+```css title="eventcatalog.styles.css"
+/**
+ * Custom "ruby" theme - Red accent colors
+ */
+
+/* Light Mode */
+:root[data-catalog-theme="ruby"],
+:root[data-catalog-theme="ruby"][data-theme="light"] {
+  /* Accent colors */
+  --ec-accent: 220 38 38;           /* red-600 */
+  --ec-accent-hover: 185 28 28;     /* red-700 */
+  --ec-accent-subtle: 254 226 226;  /* red-100 */
+  --ec-accent-text: 153 27 27;      /* red-800 */
+
+  /* Buttons */
+  --ec-button-bg: 185 28 28;        /* red-700 */
+  --ec-button-bg-hover: 153 27 27;  /* red-800 */
+  --ec-button-text: 255 255 255;
+
+  /* Sidebar */
+  --ec-sidebar-active-bg: 185 28 28;
+  --ec-sidebar-active-text: 255 255 255;
+  --ec-sidebar-hover-bg: 185 28 28;
+
+  /* You can override any CSS variable here */
+}
+
+/* Dark Mode */
+:root[data-catalog-theme="ruby"][data-theme="dark"] {
+  /* Accent colors - use lighter shades for dark mode */
+  --ec-accent: 248 113 113;         /* red-400 */
+  --ec-accent-hover: 239 68 68;     /* red-500 */
+  --ec-accent-subtle: 127 29 29 / 0.3;
+  --ec-accent-text: 252 165 165;    /* red-300 */
+
+  /* Buttons */
+  --ec-button-bg: 220 38 38;        /* red-600 */
+  --ec-button-bg-hover: 239 68 68;  /* red-500 */
+  --ec-button-text: 255 255 255;
+
+  /* Sidebar */
+  --ec-sidebar-active-bg: 220 38 38;
+  --ec-sidebar-active-text: 255 255 255;
+}
+```
+
+### Step 2: Set the theme in config
+
+Reference your custom theme name in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+export default {
+  // ... other config
+  theme: 'ruby',  // Matches data-catalog-theme="ruby" in your CSS
+};
+```
+
+### Step 3: Test both modes
+
+Start your catalog and test both light and dark modes to ensure all colors look correct:
+
+```bash
+npm run dev
+```
+
+Toggle between light and dark mode using the theme switcher in the header.
+
+:::tip Tailwind Color Reference
+Use [Tailwind CSS colors](https://tailwindcss.com/docs/customizing-colors) as a reference for your RGB values. For example, `red-600` is `220 38 38`.
+:::
+
+:::caution RGB Format Required
+CSS variables must use space-separated RGB values (e.g., `220 38 38`) **without** the `rgb()` wrapper. This allows EventCatalog to apply opacity modifiers like `rgb(var(--ec-accent) / 0.5)`.
+:::
+
+---
+
+## Full CSS variable reference
+
+Here are all available CSS variables you can customize:
+
+### Core colors
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-accent` | Primary accent color for highlights and interactive elements |
+| `--ec-accent-hover` | Accent color on hover |
+| `--ec-accent-subtle` | Light accent background (badges, highlights) |
+| `--ec-accent-text` | Text color on accent backgrounds |
+| `--ec-accent-gradient-from` | Gradient start color |
+| `--ec-accent-gradient-to` | Gradient end color |
+
+### Header
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-header-bg` | Header background |
+| `--ec-header-text` | Header text color |
+| `--ec-header-border` | Header border color |
+
+### Sidebar
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-sidebar-bg` | Sidebar background |
+| `--ec-sidebar-bg-gradient` | Sidebar gradient end color |
+| `--ec-sidebar-border` | Sidebar border |
+| `--ec-sidebar-text` | Sidebar text color |
+| `--ec-sidebar-active-bg` | Active item background |
+| `--ec-sidebar-active-text` | Active item text |
+| `--ec-sidebar-hover-bg` | Hover item background |
+
+### Rail
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-rail-bg` | Inset panel/navigation rail background, sits slightly off the page background |
+| `--ec-rail-active-bg` | Active item background within a rail |
+
+### Content area
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-content-bg` | Nested sidebar content background |
+| `--ec-content-text` | Content text |
+| `--ec-content-text-muted` | Muted text |
+| `--ec-content-text-secondary` | Secondary text |
+| `--ec-content-border` | Content borders |
+| `--ec-content-hover` | Hover background |
+| `--ec-content-active` | Active item background |
+
+### Page
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-page-bg` | Main page background |
+| `--ec-page-text` | Page text color |
+| `--ec-page-text-muted` | Muted/secondary text |
+| `--ec-page-border` | Page borders |
+
+### Buttons
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-button-bg` | Button background |
+| `--ec-button-bg-hover` | Button hover background |
+| `--ec-button-text` | Button text color |
+
+### Form inputs
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-input-bg` | Input field background |
+| `--ec-input-border` | Input field border |
+| `--ec-input-text` | Input field text |
+| `--ec-input-placeholder` | Placeholder text color |
+
+### Dropdowns
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-dropdown-bg` | Dropdown background |
+| `--ec-dropdown-text` | Dropdown text |
+| `--ec-dropdown-hover` | Dropdown hover background |
+| `--ec-dropdown-border` | Dropdown border |
+
+### Icons
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-icon-color` | Default icon color |
+| `--ec-icon-hover` | Icon hover color |
+
+### Other
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-card-bg` | Card/elevated surface background |
+| `--ec-code-bg` | Code block background |
+| `--ec-group-icon-bg` | Group header icon background |
+| `--ec-group-icon-text` | Group header icon text |
+
+---
+
+## Dark mode prose overrides
+
+For custom themes, you may want to customize how markdown content (prose) appears in dark mode:
+
+```css title="eventcatalog.styles.css"
+:root[data-catalog-theme="ruby"][data-theme="dark"] .prose {
+  --tw-prose-body: rgb(163 163 163);
+  --tw-prose-headings: rgb(245 245 245);
+  --tw-prose-links: rgb(248 113 113);  /* Match your accent */
+  --tw-prose-bold: rgb(245 245 245);
+  --tw-prose-code: rgb(245 245 245);
+  --tw-prose-pre-bg: rgb(23 23 23);
+}
+
+:root[data-catalog-theme="ruby"][data-theme="dark"] .prose a {
+  color: rgb(248 113 113);
+}
+
+:root[data-catalog-theme="ruby"][data-theme="dark"] .prose a:hover {
+  color: rgb(252 165 165);
+}
+```
+
+---
+
+## Example: Complete custom theme
+
+Here's a complete example of a custom "ruby" red theme you can use as a starting point:
+
+<details>
+<summary>View full ruby theme CSS</summary>
+
+```css title="eventcatalog.styles.css"
+/**
+ * Ruby Theme - Custom Red Theme
+ */
+
+/* Ruby Light Mode */
+:root[data-catalog-theme="ruby"],
+:root[data-catalog-theme="ruby"][data-theme="light"] {
+  --ec-header-bg: 255 255 255;
+  --ec-header-text: 23 23 23;
+  --ec-header-border: 229 229 229;
+
+  --ec-primary: 220 38 38;
+  --ec-primary-hover: 185 28 28;
+
+  --ec-accent: 220 38 38;
+  --ec-accent-hover: 185 28 28;
+  --ec-accent-subtle: 254 226 226;
+  --ec-accent-text: 153 27 27;
+  --ec-accent-gradient-from: 239 68 68;
+  --ec-accent-gradient-to: 185 28 28;
+
+  --ec-button-bg: 185 28 28;
+  --ec-button-bg-hover: 153 27 27;
+  --ec-button-text: 255 255 255;
+
+  --ec-dropdown-bg: 255 255 255;
+  --ec-dropdown-text: 64 64 64;
+  --ec-dropdown-hover: 254 242 242;
+  --ec-dropdown-border: 229 229 229;
+
+  --ec-icon-color: 82 82 82;
+  --ec-icon-hover: 185 28 28;
+
+  --ec-sidebar-bg: 255 255 255;
+  --ec-sidebar-bg-gradient: 254 242 242;
+  --ec-sidebar-border: 229 229 229;
+  --ec-sidebar-text: 82 82 82;
+  --ec-sidebar-active-bg: 185 28 28;
+  --ec-sidebar-active-text: 255 255 255;
+  --ec-sidebar-hover-bg: 185 28 28;
+
+  --ec-content-bg: 255 255 255;
+  --ec-content-text: 23 23 23;
+  --ec-content-text-muted: 82 82 82;
+  --ec-content-text-secondary: 115 115 115;
+  --ec-content-border: 229 229 229;
+  --ec-content-hover: 250 250 250;
+  --ec-content-active: 254 226 226;
+
+  --ec-input-bg: 255 255 255;
+  --ec-input-border: 212 212 212;
+  --ec-input-text: 23 23 23;
+  --ec-input-placeholder: 163 163 163;
+
+  --ec-group-icon-bg: 254 226 226;
+  --ec-group-icon-text: 153 27 27;
+
+  --ec-page-bg: 255 255 255;
+  --ec-page-text: 23 23 23;
+  --ec-page-text-muted: 82 82 82;
+  --ec-page-border: 229 229 229;
+
+  --ec-card-bg: 255 255 255;
+  --ec-code-bg: 250 250 250;
+}
+
+/* Ruby Dark Mode */
+:root[data-catalog-theme="ruby"][data-theme="dark"] {
+  --ec-header-bg: 23 23 23;
+  --ec-header-text: 245 245 245;
+  --ec-header-border: 38 38 38;
+
+  --ec-accent: 248 113 113;
+  --ec-accent-hover: 239 68 68;
+  --ec-accent-subtle: 127 29 29 / 0.3;
+  --ec-accent-text: 252 165 165;
+  --ec-accent-gradient-from: 248 113 113;
+  --ec-accent-gradient-to: 239 68 68;
+
+  --ec-button-bg: 220 38 38;
+  --ec-button-bg-hover: 239 68 68;
+  --ec-button-text: 255 255 255;
+
+  --ec-dropdown-bg: 23 23 23;
+  --ec-dropdown-text: 212 212 212;
+  --ec-dropdown-hover: 38 38 38;
+  --ec-dropdown-border: 64 64 64;
+
+  --ec-icon-color: 163 163 163;
+  --ec-icon-hover: 252 165 165;
+
+  --ec-sidebar-bg: 10 10 10;
+  --ec-sidebar-bg-gradient: 10 10 10;
+  --ec-sidebar-border: 38 38 38;
+  --ec-sidebar-text: 163 163 163;
+  --ec-sidebar-active-bg: 220 38 38;
+  --ec-sidebar-active-text: 255 255 255;
+  --ec-sidebar-hover-bg: 38 38 38;
+
+  --ec-content-bg: 10 10 10;
+  --ec-content-text: 245 245 245;
+  --ec-content-text-muted: 163 163 163;
+  --ec-content-text-secondary: 163 163 163;
+  --ec-content-border: 38 38 38;
+  --ec-content-hover: 23 23 23;
+  --ec-content-active: 38 38 38;
+
+  --ec-input-bg: 23 23 23;
+  --ec-input-border: 64 64 64;
+  --ec-input-text: 245 245 245;
+  --ec-input-placeholder: 115 115 115;
+
+  --ec-group-icon-bg: 38 38 38;
+  --ec-group-icon-text: 252 165 165;
+
+  --ec-page-bg: 10 10 10;
+  --ec-page-text: 245 245 245;
+  --ec-page-text-muted: 163 163 163;
+  --ec-page-border: 38 38 38;
+
+  --ec-card-bg: 10 10 10;
+  --ec-code-bg: 23 23 23;
+}
+
+/* Ruby theme prose overrides */
+:root[data-catalog-theme="ruby"][data-theme="dark"] .prose {
+  --tw-prose-body: rgb(163 163 163);
+  --tw-prose-headings: rgb(245 245 245);
+  --tw-prose-links: rgb(248 113 113);
+  --tw-prose-bold: rgb(245 245 245);
+}
+
+:root[data-catalog-theme="ruby"][data-theme="dark"] .prose a {
+  color: rgb(248 113 113);
+}
+
+:root[data-catalog-theme="ruby"][data-theme="dark"] .prose a:hover {
+  color: rgb(252 165 165);
+}
+```
+
+</details>
diff --git a/packages/core/docs/development/customization/03-application-sidebar.md b/packages/core/docs/development/customization/03-application-sidebar.md
new file mode 100644
index 000000000..e5d3823a8
--- /dev/null
+++ b/packages/core/docs/development/customization/03-application-sidebar.md
@@ -0,0 +1,246 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog application sidebar
+sidebar_label: Application sidebar
+title: Application Sidebar
+description: Pick and customize the application sidebar.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+The application sidebar is the vertical sidebar that is rendered on every page in EventCatalog.
+
+![Example](../guides/img/custom-sidebars/application-sidebar.png)
+
+### Customize the application sidebar
+
+You can customize the application sidebar with the `navigation.groups` property in your `eventcatalog.config.js` file.
+
+Use this when you want to:
+
+- Reorder the application navigation.
+- Hide built-in navigation items.
+- Add custom links to internal or external pages.
+- Group navigation items under labels.
+- Pin navigation groups to the bottom of the sidebar.
+- Configure which routes make an item active.
+
+:::info Application sidebar vs documentation sidebar
+
+`navigation.groups` customizes the vertical application sidebar.
+
+`navigation.pages` customizes the context-aware documentation sidebar shown on `/docs/*` pages.
+
+:::
+
+If you do not configure `navigation.groups`, EventCatalog renders the default application sidebar.
+
+If you do configure `navigation.groups`, your groups replace the default application sidebar. Add every item you want users to see.
+
+### Built-in navigation items
+
+EventCatalog provides built-in navigation items you can reference by `id`.
+
+| ID | Description |
+| --- | --- |
+| `home` | Home |
+| `docs` | Custom documentation |
+| `catalog` | Discover catalog |
+| `schemas` | Schemas & APIs |
+| `schema-insights` | Schema Insights |
+| `teams` | Teams |
+| `users` | Users |
+| `settings` | Settings |
+
+You can also reference built-in route IDs directly, such as `/schemas/explorer`, `/directory/teams`, or `/settings/general`.
+
+### Group options
+
+Each group in `navigation.groups` supports:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Unique group identifier. |
+| `label` | `string` | Optional label shown above the group. |
+| `visible` | `boolean` | Set to `false` to hide the group. |
+| `position` | `'top' \| 'bottom'` | Use `bottom` for settings-style groups pinned below the main navigation. Defaults to `top`. |
+| `items` | `array` | Navigation items in this group. |
+
+### Item options
+
+Each item supports:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Built-in item id, route id, or custom item id. |
+| `label` | `string` | Custom label. Required for custom items. |
+| `icon` | `string` | Any icon exported by [lucide-react](https://lucide.dev/icons/), such as `House`, `BookOpen`, or `LifeBuoy`. |
+| `href` | `string` | Required for custom items. Built-in items provide their own `href`. |
+| `visible` | `boolean` | Set to `false` to hide the item. |
+| `match` | `string \| string[]` | Paths that should mark the item as active. Useful for custom navigation items. |
+
+### Example: default-style navigation
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    groups: [
+      {
+        id: 'main',
+        items: [{ id: 'home' }, { id: 'docs' }],
+      },
+      {
+        id: 'browse',
+        label: 'Browse',
+        items: [
+          { id: 'catalog' },
+          { id: 'schemas' },
+          { id: 'schema-insights' },
+        ],
+      },
+      {
+        id: 'organization',
+        label: 'Organization',
+        items: [{ id: 'teams' }, { id: 'users' }],
+      },
+      {
+        id: 'settings',
+        position: 'bottom',
+        items: [{ id: 'settings' }],
+      },
+    ],
+  },
+};
+```
+
+### Hide items
+
+Use `visible: false` to hide a group or item.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    groups: [
+      {
+        id: 'browse',
+        label: 'Browse',
+        items: [
+          { id: 'catalog' },
+          { id: 'schemas' },
+          // Hide Schema Insights
+          { id: 'schema-insights', visible: false },
+        ],
+      },
+      {
+        id: 'organization',
+        label: 'Organization',
+        items: [
+          // Hide Teams
+          { id: 'teams', visible: false },
+          { id: 'users' },
+        ],
+      },
+    ],
+  },
+};
+```
+
+### Add custom links
+
+Custom items require an `id`, `label`, `icon`, and `href`.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    groups: [
+      {
+        id: 'platform',
+        label: 'Platform',
+        items: [
+          {
+            id: 'platform-docs',
+            label: 'Platform Docs',
+            icon: 'BookOpen',
+            href: '/docs/custom/platform/overview',
+            match: ['/docs/custom/platform'],
+          },
+          {
+            id: 'support',
+            label: 'Support',
+            icon: 'LifeBuoy',
+            href: 'https://support.example.com',
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+External `href` values open in a new tab.
+
+### Active route matching
+
+Built-in items know which routes should mark them as active.
+
+For custom links, use `match` when more than one route should activate the same navigation item.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    groups: [
+      {
+        id: 'platform',
+        items: [
+          {
+            id: 'platform-docs',
+            label: 'Platform Docs',
+            icon: 'BookOpen',
+            href: '/docs/custom/platform/overview',
+            match: [
+              '/docs/custom/platform',
+              '/docs/custom/engineering-standards',
+            ],
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+### Migrating from `sidebar`
+
+In v3 you could show or hide application sidebar items using the top-level `sidebar` property.
+
+In v4 this has been replaced by `navigation.groups`.
+
+```diff title="eventcatalog.config.js"
+module.exports = {
+-  sidebar: [
+-    { id: '/directory/teams', visible: false },
+-    { id: '/schemas/fields', visible: false },
+-  ],
++  navigation: {
++    groups: [
++      {
++        id: 'browse',
++        label: 'Browse',
++        items: [
++          { id: 'catalog' },
++          { id: 'schemas' },
++          { id: 'schema-insights', visible: false },
++        ],
++      },
++      {
++        id: 'organization',
++        label: 'Organization',
++        items: [{ id: 'teams', visible: false }, { id: 'users' }],
++      },
++    ],
++  },
+};
+```
+
+The `SideBarConfig` type is no longer exported.
diff --git a/packages/core/docs/development/customization/03-search.md b/packages/core/docs/development/customization/03-search.md
new file mode 100644
index 000000000..02d957318
--- /dev/null
+++ b/packages/core/docs/development/customization/03-search.md
@@ -0,0 +1,79 @@
+---
+sidebar_position: 4
+keywords:
+  - EventCatalog search
+  - full-content search
+  - indexed search
+  - pagefind
+  - search configuration
+sidebar_label: Global Search
+title: Search
+description: Configure resource metadata search or opt-in to full-content indexed search
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.36.0" />
+
+EventCatalog ships with two search modes. The default is a fast metadata search that works with no extra configuration. An opt-in indexed mode adds full-content search powered by [Pagefind](https://pagefind.app/).
+
+## Understand the modes
+
+**Resource search (default)** indexes the metadata of every catalog resource — names, summaries, badges, types, and identifiers. It is fast, requires no build step, and works in both `static` and `server` output modes.
+
+**Indexed search (opt-in)** builds a static index of the full markdown content of your catalog at build time. It can find matches inside the body of a page, changelogs, custom docs, and resource docs — not just the frontmatter fields.
+
+## Enable indexed search
+
+Set `search.type` to `'indexed'` in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  search: {
+    type: 'indexed',
+  },
+};
+```
+
+No other changes are required. The index is built automatically as part of `eventcatalog build` and also during `eventcatalog dev`.
+
+## What gets indexed
+
+When indexed search is enabled, the following content is included in the index:
+
+- All catalog resources: events, commands, queries, services, domains, subdomains, channels, containers, data products, entities, and flows
+- Custom docs pages
+- Resource docs
+- Changelogs
+
+## When the index is built
+
+During `eventcatalog build`, the indexer runs after the Astro build and writes the index to `<outDir>/pagefind`.
+
+During `eventcatalog dev`, the index is built on startup and rebuilt automatically whenever any `.md` or `.mdx` file changes (debounced to avoid excessive rebuilds). The first build may take a few seconds depending on the size of your catalog. Subsequent incremental rebuilds are faster.
+
+## Result ranking
+
+Indexed results are ranked by relevance. Matches in the resource title and identifier score highest, followed by matches in the summary and type. Content-body matches score lower than title matches but are still surfaced when no title match is found.
+
+## Auth and the `/pagefind` assets
+
+:::warning Private catalogs
+If your catalog uses authentication (an `eventcatalog.auth.js` file is present), the generated `/pagefind` directory is served as static client-readable assets. Anyone who can load the page can download the index, which contains the full text of all indexed content.
+
+Ensure your deployment platform protects the `/pagefind` path behind the same authentication layer as the rest of your catalog.
+:::
+
+## Keep resource search
+
+To stay on the default resource search, either omit the `search` key entirely or set the type explicitly:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  search: {
+    type: 'resource', // default, no index built
+  },
+};
+```
+
+Existing catalogs are not affected by this feature — no changes are needed unless you want to opt in.
diff --git a/packages/core/docs/development/customization/04-documentation-sidebar.md b/packages/core/docs/development/customization/04-documentation-sidebar.md
new file mode 100644
index 000000000..18f22646a
--- /dev/null
+++ b/packages/core/docs/development/customization/04-documentation-sidebar.md
@@ -0,0 +1,187 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog documentation sidebar
+sidebar_label: Docs sidebar
+title: Documentation sidebar
+description: Pick and customize the documentation sidebar.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+The documentation sidebar is a [context aware sidebar](#what-is-context-aware-sidebar) that is shown on the `/docs/` pages.
+
+Clicking on any resource in the sidebar will show you related information to that selected resource ([see demo](https://demo.eventcatalog.dev/)).
+
+![](./img/docs-sidebar.png)
+
+## What is a context aware sidebar?
+
+**Many documentation tools use a flat navigation structure, which can be overwhelming and difficult to navigate.**
+
+EventCatalog's documentation sidebar is a context aware sidebar that shows you related information to the selected resource.
+
+This can help you navigate your documentation and find the information you need quickly, as you go deeper into the hierarchy of your architecture.
+
+For example, selecting a domain will show you the subdomains, related services, ubiquitous language, etc, where as selecting a message will show you the producers, consumers and schemas.
+
+
+## Customizing the documentation sidebar
+
+By default EventCatalog will show you a list of all the resources in your catalog, but you can customize the navigation bar to show any resource you want.
+
+This can be useful if you want to show a specific resource or a group of resources in the sidebar, helping your teams find the information they need quickly.
+
+### How to customize the documentation sidebar
+
+To customize the documentation sidebar you need to set the `navigation.pages` property in your `eventcatalog.config.js` file.
+
+The example below will show you a list of the top-level domains and all resources in your catalog.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  // ... rest of your config
+  navigation: {
+    // pick any key you want to show in the sidebar
+    pages: ['list:top-level-domains', 'list:all'],
+  },
+};
+```
+
+![](./img/custom-docs-sidebar.png)
+
+#### Available navigation configuration
+
+You can specify the following options in the `navigation.pages` property:
+
+- [Top level options](#top-level-options) 
+  - Useful if you want to show the top-level resources in your catalog in the sidebar. For example high level domains and let your users drill down.
+- [List all resources (by type)](#list-all-resources-type)
+  - Useful if you want to show all resources of a specific type in the sidebar. For example all domains, services, messages, etc.
+- [Pick specific resources to show](#pick-specific-resources-to-show)
+  - Useful if you want to show a specific resource or a group of resources in the sidebar. For example a specific domain, service, message, etc.
+- [Custom groups and links](#custom-groups-and-links)
+  - Useful if you want to create custom groups and links to external pages in the sidebar. For example a group of resources, or a link to an external page.
+
+#### Top level options:
+
+| Key | Description |
+| --- | --- |
+| `list:all` | Lists all resources types in your catalog, organized by resource type (e.g domain, services, messages) |
+| `list:top-level-domains` | Displays a list of the top-level domains in your catalog. (Does not include subdomains) |
+
+**Example**
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    pages: ['list:top-level-domains'],
+  },
+};
+```
+
+
+#### List all resources (by type):
+
+| Key | Description |
+| --- | --- |
+| `list:domains` | Lists all domains in your catalog. |
+| `list:services` | Lists all services in your catalog. |
+| `list:messages` | Lists all messages in your catalog. |
+| `list:channels` | Lists all channels in your catalog. |
+| `list:designs` | Lists all designs in your catalog. |
+| `list:flows` | Lists all flows in your catalog. |
+| `list:containers` | Lists all containers in your catalog. |
+
+**Example**
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    pages: ['list:domains', 'list:services'],
+  },
+};
+```
+
+#### Chose which resources to show:
+
+You can specify any resource you want to show in the sidebar using the following key structure
+
+`<resource-type>:<resource-id>` or `<resource-type>:<resource-id>:<resource-version>`
+
+*If no version is specified, the latest version will be used.*
+
+*Example:*
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    // Show the MyDomain domain, MyService service and the 0.0.1 version of the MyEvent event
+    pages: [
+      // Show the latest version of the MyDomain domain
+      'domain:MyDomain',
+      // Show the latest version of the MyService service
+      'service:MyService',
+      // Show the 0.0.1 version of the MyMessage message
+      'message:MyMessage:0.0.1',
+    ],
+  },
+};
+```
+
+Available resource types:
+| Resource Type | Description |
+| --- | --- |
+| `domain` | Domain resource type. |
+| `service` | Service resource type. |
+| `message` | Message resource type. |
+| `channel` | Channel resource type. |
+| `design` | Design resource type. |
+| `flow` | Flow resource type. |
+| `container` | Container resource type. |
+| `user` | User resource type. |
+| `team` | Team resource type. |
+| `event` | Event resource type. |
+| `command` | Command resource type. |
+| `query` | Query resource type. |
+
+### Custom groups and links
+
+You can also create custom groups and links to external pages in the sidebar.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  navigation: {
+    pages: [
+      // Custom group
+      {
+        type: 'group',
+        // Custom group title
+        title: 'My Custom Group',
+        // Custom group icon from lucide icons
+        icon: 'Boxes',
+        // Custom group pages
+        pages: [
+          // You can still reference resources, lists as you would normally do
+          'domain:E-Commerce',
+          // Create a custom item link to an external page
+          {
+            type: 'item',
+            title: 'My Custom Link',
+            // Custom link to an external page
+            href: 'https://eventcatalog.dev',
+          }
+        ],
+      },
+      // Or have a custom item on the root (outside a group)
+      {
+        type: 'item',
+        title: 'My Custom Item',
+        href: 'https://eventcatalog.dev',
+      }
+      // You can still use EventCatalog lists or resources as you would normally do
+      'list:all',
+    ]
+  },
+};
+```
diff --git a/packages/core/docs/development/customization/05-custom-pages-and-api-routes/01-introduction.md b/packages/core/docs/development/customization/05-custom-pages-and-api-routes/01-introduction.md
new file mode 100644
index 000000000..3b86fa3f8
--- /dev/null
+++ b/packages/core/docs/development/customization/05-custom-pages-and-api-routes/01-introduction.md
@@ -0,0 +1,94 @@
+---
+sidebar_position: 1
+keywords:
+  - EventCatalog custom pages
+  - EventCatalog API routes
+  - Astro pages
+  - custom routes
+sidebar_label: Introduction
+title: Custom pages and API routes
+description: Understand custom pages and API routes in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<AddedIn version="4.1.1" />
+<PlanBanner plan="Scale" />
+
+EventCatalog gives you a structured catalog out of the box, but every organization eventually needs pages that are specific to how they work.
+
+Custom pages and API routes let you extend EventCatalog beyond the built-in catalog views. You can create any page you need, reuse your own components, keep pages static when the content is simple, or connect pages to other systems when you need live data.
+
+Use this when you want EventCatalog to become the place for catalog-specific tools and experiences, such as:
+
+- Internal reports and dashboards.
+- Team onboarding pages.
+- Architecture review workflows.
+- Scorecards and ownership views.
+- Lightweight API routes for catalog data.
+- Pages that combine EventCatalog resources with data from systems such as service catalogs, deployment platforms, observability tools, or internal APIs.
+
+## What are custom pages?
+
+Custom pages are `.astro` files that EventCatalog turns into routes in your generated catalog.
+
+For example, `pages/reports.astro` becomes `/custom/reports` by default.
+
+Custom pages are useful when markdown is not enough. Use them when you need layout control, custom components, conditional rendering, or a small internal tool that belongs inside the catalog.
+
+They can be static pages built entirely from catalog data, or pages that call API routes and other systems to show live information.
+
+## What are API routes?
+
+API routes are server endpoints that live in `pages/api`.
+
+For example, `pages/api/services.ts` becomes `/custom/api/services` by default.
+
+API routes are useful when you want to expose catalog data, receive form submissions, power a custom page, or connect a catalog workflow to another internal system.
+
+For example, a custom page could show service ownership from EventCatalog, deployment status from your platform, and incidents from your observability tool in one view.
+
+## Custom pages, custom docs, and custom components
+
+EventCatalog has a few customization features. Pick the smallest one that fits the job.
+
+| Feature | Use it when |
+| --- | --- |
+| [Custom documentation](/docs/development/bring-your-own-documentation/custom-pages/introduction) | You want markdown documentation under `/docs/custom`. |
+| [Custom components](/docs/development/components/custom-components/introduction) | You want reusable UI inside markdown or MDX pages. |
+| [Custom homepage](/docs/development/customization/customize-landing-page) | You want to replace the catalog homepage at `/`. |
+| Custom pages | You want new catalog routes with custom Astro code. |
+| API routes | You want server endpoints inside the catalog. |
+
+:::info Custom homepage
+
+`pages/homepage.astro` is still the way to customize the catalog homepage. That file is rendered at `/` and is not served under the custom pages prefix.
+
+This section covers additional custom pages and API routes.
+
+:::
+
+## How routing works
+
+EventCatalog uses [Astro](https://astro.build/) under the hood. Files in your catalog's top-level `pages` directory become routes in your generated catalog.
+
+By default, custom pages are served under `/custom`. You can change this prefix.
+
+| File | Route |
+| --- | --- |
+| `pages/reports.astro` | `/custom/reports` |
+| `pages/reports/index.astro` | `/custom/reports` |
+| `pages/reports/[id].astro` | `/custom/reports/[id]` |
+| `pages/api/teams.ts` | `/custom/api/teams` |
+| `pages/data.json.ts` | `/custom/data.json` |
+
+EventCatalog supports Astro-style dynamic route segments such as `[id]` and `[...slug]`.
+
+After you create a custom page, you can add it to your catalog navigation by customizing the [application sidebar](/docs/development/customization/application-sidebar).
+
+## Next steps
+
+- [Create a custom page](/docs/development/customization/custom-pages-and-api-routes/create-a-custom-page)
+- [Create an API route](/docs/development/customization/custom-pages-and-api-routes/create-an-api-route)
+- [Routing and configuration reference](/docs/development/customization/custom-pages-and-api-routes/reference)
diff --git a/packages/core/docs/development/customization/05-custom-pages-and-api-routes/02-create-a-custom-page.md b/packages/core/docs/development/customization/05-custom-pages-and-api-routes/02-create-a-custom-page.md
new file mode 100644
index 000000000..867a287c4
--- /dev/null
+++ b/packages/core/docs/development/customization/05-custom-pages-and-api-routes/02-create-a-custom-page.md
@@ -0,0 +1,177 @@
+---
+sidebar_position: 2
+keywords:
+  - EventCatalog custom pages
+  - Astro page
+  - custom routes
+sidebar_label: Create a custom page
+title: Create a custom page
+description: Add a custom Astro page to your EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+This guide shows you how to add a custom page to your catalog.
+
+Use this when you want a new route for an internal report, dashboard, onboarding page, or catalog-specific workflow. The page can be static, built from catalog data, or use browser-side code to call API routes and other systems.
+
+## Create the page file
+
+Create a top-level `pages` directory and add an `.astro` file.
+
+<ProjectTree
+  items={[
+    {
+      name: 'pages',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        { name: 'reports.astro', highlight: true },
+      ],
+    },
+  ]}
+/>
+
+```js title="pages/reports.astro"
+---
+// Use the EventCatalog layout so your page keeps the catalog header and sidebar.
+import Layout from '@catalog/layouts/Layout.astro';
+
+// Use @catalog/utils to read catalog resources from your custom page.
+import { getServices } from '@catalog/utils';
+
+// getAllVersions: false returns the latest version of each service.
+const services = await getServices({ getAllVersions: false });
+---
+
+<Layout title="Service reports" description="Operational views built from catalog data.">
+  <div class="not-prose space-y-6">
+    <div>
+      <h1 class="text-3xl font-semibold">Service reports</h1>
+      <p class="text-gray-600">There are {services.length} services in this catalog.</p>
+    </div>
+
+    <ul class="grid gap-3 md:grid-cols-2">
+      {services.map((service) => (
+        <li class="rounded-lg border border-gray-200 p-4">
+          <h2 class="font-semibold">{service.data.name}</h2>
+          <p class="text-sm text-gray-600">{service.data.summary}</p>
+        </li>
+      ))}
+    </ul>
+  </div>
+</Layout>
+```
+
+## Run your catalog
+
+Start EventCatalog.
+
+```bash
+npm run dev
+```
+
+Open `/custom/reports`.
+
+## Add the page to your navigation
+
+Custom pages are available by URL as soon as you create them. To make the page easier for users to find, add it to your application sidebar.
+
+Add a custom navigation item in `eventcatalog.config.js`.
+
+```js title="eventcatalog.config.js"
+export default {
+  navigation: {
+    groups: [
+      {
+        id: 'tools',
+        label: 'Tools',
+        items: [
+          {
+            id: 'service-reports',
+            label: 'Service reports',
+            icon: 'ChartBar',
+            href: '/custom/reports',
+            match: ['/custom/reports'],
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+The `href` is the custom page route. The `match` value tells EventCatalog when to mark the navigation item as active.
+
+For more navigation options, see [Application sidebar](/docs/development/customization/application-sidebar).
+
+## Add a custom component
+
+You can reuse Astro components from your catalog's top-level `components` directory.
+
+<ProjectTree
+  items={[
+    {
+      name: 'components',
+      type: 'folder',
+      defaultOpen: true,
+      children: [{ name: 'ReportCard.astro', highlight: true }],
+    },
+    {
+      name: 'pages',
+      type: 'folder',
+      defaultOpen: true,
+      children: [{ name: 'reports.astro' }],
+    },
+  ]}
+/>
+
+```js title="components/ReportCard.astro"
+---
+// Props are values passed into this component from the page that renders it.
+const { title, description } = Astro.props;
+---
+
+<article class="rounded-lg border border-gray-200 p-4">
+  <h2 class="font-semibold">{title}</h2>
+  <p class="text-sm text-gray-600">{description}</p>
+</article>
+```
+
+Import the component into your custom page.
+
+```js title="pages/reports.astro"
+---
+import Layout from '@catalog/layouts/Layout.astro';
+
+// Components in your catalog's top-level components directory are available from @catalog/components.
+import ReportCard from '@catalog/components/ReportCard.astro';
+---
+
+<Layout title="Reports">
+  <ReportCard title="Service health" description="Operational view for catalog services." />
+</Layout>
+```
+
+## Add a dynamic page
+
+Use Astro dynamic route segments when the route needs a parameter.
+
+```js title="pages/reports/[id].astro"
+---
+import Layout from '@catalog/layouts/Layout.astro';
+
+// Dynamic route parameters come from the filename. Here, [id].astro provides Astro.params.id.
+const { id } = Astro.params;
+---
+
+<Layout title={`Report: ${id}`}>
+  <h1>Report: {id}</h1>
+</Layout>
+```
+
+This page is available at `/custom/reports/:id`, for example `/custom/reports/orders`.
+
+## Learn more
+
+Custom pages follow Astro's routing model. See the [Astro pages documentation](https://docs.astro.build/en/basics/astro-pages/) if you want to go deeper.
diff --git a/packages/core/docs/development/customization/05-custom-pages-and-api-routes/03-create-an-api-route.md b/packages/core/docs/development/customization/05-custom-pages-and-api-routes/03-create-an-api-route.md
new file mode 100644
index 000000000..f757c8b81
--- /dev/null
+++ b/packages/core/docs/development/customization/05-custom-pages-and-api-routes/03-create-an-api-route.md
@@ -0,0 +1,128 @@
+---
+sidebar_position: 3
+keywords:
+  - EventCatalog API routes
+  - Astro endpoints
+  - server mode
+sidebar_label: Create an API route
+title: Create an API route
+description: Add a custom API route to your EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+This guide shows you how to add a custom API route to your catalog.
+
+Use this when you want to expose catalog data, receive form submissions, or power a custom page with server-side logic. API routes are also useful when a custom page needs data from another internal system and you want that integration to live inside EventCatalog.
+
+## Enable server mode
+
+Custom API routes require EventCatalog to run in server mode when you build the catalog.
+
+Set `output: 'server'` in `eventcatalog.config.js`.
+
+```js title="eventcatalog.config.js"
+export default {
+  output: 'server',
+};
+```
+
+## Create the endpoint file
+
+Create a file inside `pages/api`.
+
+<ProjectTree
+  items={[
+    {
+      name: 'pages',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'api',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'services.ts', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+```js title="pages/api/services.ts"
+import type { APIRoute } from 'astro';
+
+// Use @catalog/utils to read catalog resources from your API route.
+import { getServices } from '@catalog/utils';
+
+// Export a function named after the HTTP method this route should handle.
+export const GET: APIRoute = async () => {
+  // getAllVersions: false returns the latest version of each service.
+  const services = await getServices({ getAllVersions: false });
+
+  return Response.json({
+    services: services.map((service) => ({
+      id: service.data.id,
+      name: service.data.name,
+      version: service.data.version,
+    })),
+  });
+};
+```
+
+This route is served at `/custom/api/services`.
+
+## Add another HTTP method
+
+Astro calls exported functions that match the request method, such as `GET`, `POST`, or `DELETE`.
+
+```js title="pages/api/reviews.ts"
+import type { APIRoute } from 'astro';
+
+// This function handles POST requests sent to /custom/api/reviews.
+export const POST: APIRoute = async ({ request }) => {
+  const body = await request.json();
+
+  return Response.json({
+    status: 'received',
+    resource: body.resource,
+  });
+};
+```
+
+This route receives `POST` requests at `/custom/api/reviews`.
+
+## Call an API route from a custom page
+
+You can call your API route from a custom page like any other endpoint.
+
+```js title="pages/reports.astro"
+---
+// Use the EventCatalog layout so your page keeps the catalog header and sidebar.
+import Layout from '@catalog/layouts/Layout.astro';
+---
+
+<Layout title="Reports">
+  <button id="load-services">Load services</button>
+  <pre id="services-output"></pre>
+</Layout>
+
+<script>
+  const button = document.querySelector('#load-services');
+  const output = document.querySelector('#services-output');
+
+  button?.addEventListener('click', async () => {
+    // This calls the custom API route defined in pages/api/services.ts.
+    const response = await fetch('/custom/api/services');
+    const data = await response.json();
+
+    if (output) {
+      output.textContent = JSON.stringify(data, null, 2);
+    }
+  });
+</script>
+```
+
+## Learn more
+
+Custom API routes follow Astro's endpoint model. See the [Astro endpoints documentation](https://docs.astro.build/en/guides/endpoints/) if you want to go deeper.
diff --git a/packages/core/docs/development/customization/05-custom-pages-and-api-routes/04-reference.md b/packages/core/docs/development/customization/05-custom-pages-and-api-routes/04-reference.md
new file mode 100644
index 000000000..8f3979e8d
--- /dev/null
+++ b/packages/core/docs/development/customization/05-custom-pages-and-api-routes/04-reference.md
@@ -0,0 +1,138 @@
+---
+sidebar_position: 4
+keywords:
+  - EventCatalog custom pages reference
+  - EventCatalog pages prefix
+  - custom routes reference
+sidebar_label: Reference
+title: Custom pages and API routes reference
+description: Route, file, and configuration reference for custom pages and API routes.
+---
+
+## Route prefix
+
+Custom pages and API routes are served under `/custom` by default.
+
+Use `pages.prefix` to serve them somewhere else.
+
+```js title="eventcatalog.config.js"
+export default {
+  pages: {
+    prefix: 'internal/tools',
+  },
+};
+```
+
+With this configuration:
+
+| File | Route |
+| --- | --- |
+| `pages/reports.astro` | `/internal/tools/reports` |
+| `pages/api/services.ts` | `/internal/tools/api/services` |
+
+The prefix must use URL-safe characters: letters, numbers, `-`, and `_`, optionally separated with `/`.
+
+The prefix cannot be empty.
+
+Some top-level routes are reserved by EventCatalog. If a configured prefix conflicts with a reserved route, EventCatalog will ask you to choose a different prefix.
+
+## Routable files
+
+Code files in the top-level `pages` directory are treated as custom routes.
+
+| Extension | Route type |
+| --- | --- |
+| `.astro` | Page |
+| `.ts` | Endpoint |
+| `.js` | Endpoint |
+| `.mjs` | Endpoint |
+
+Other files in `pages`, such as images, are copied as static assets. For example, `pages/diagram.png` can be referenced from `/generated/pages/diagram.png`.
+
+## Route patterns
+
+| File | Default route |
+| --- | --- |
+| `pages/reports.astro` | `/custom/reports` |
+| `pages/reports/index.astro` | `/custom/reports` |
+| `pages/reports/[id].astro` | `/custom/reports/[id]` |
+| `pages/docs/[...slug].astro` | `/custom/docs/[...slug]` |
+| `pages/api/teams.ts` | `/custom/api/teams` |
+| `pages/data.json.ts` | `/custom/data.json` |
+
+## Ignored files and folders
+
+Files or folders that start with `_` are not treated as routes.
+
+Use this for partials, helpers, and colocated components.
+
+| File | Result |
+| --- | --- |
+| `pages/_partial.astro` | Ignored |
+| `pages/_components/Card.astro` | Ignored |
+| `pages/reports/_helpers.ts` | Ignored |
+| `pages/reports/index.astro` | `/custom/reports` |
+
+## Homepage exception
+
+`pages/homepage.astro` is rendered as the catalog homepage at `/`.
+
+It is not served as `/custom/homepage`.
+
+## Server mode
+
+Custom pages can be used in static or server output.
+
+Custom API routes require server mode for production builds.
+
+```js title="eventcatalog.config.js"
+export default {
+  output: 'server',
+};
+```
+
+If EventCatalog finds API routes in `pages/api` during a static build, the build fails and asks you to enable server mode or remove the `pages/api` directory.
+
+## Import aliases
+
+Use these aliases in custom pages.
+
+| Alias | Description |
+| --- | --- |
+| `@catalog/layouts/Layout.astro` | Stable EventCatalog layout shell for custom pages. |
+| `@catalog/utils` | Stable catalog data helpers such as `getServices`, `getDomains`, and `getEvents`. |
+| `@catalog/components/*` | Components from your catalog's top-level `components` directory. |
+
+## `@catalog/utils`
+
+Use `@catalog/utils` to read catalog resources from custom pages and API routes.
+
+```js title="pages/reports.astro"
+---
+import { getServices, getDomains } from '@catalog/utils';
+
+const services = await getServices({ getAllVersions: false });
+const domains = await getDomains({ getAllVersions: false });
+---
+```
+
+Getter functions return hydrated, cached collection entries. Pass `{ getAllVersions: false }` when you only want the latest version of each resource.
+
+| Helper | Returns |
+| --- | --- |
+| `getDomains` | Domains |
+| `getServices` | Services |
+| `getSystems` | Systems |
+| `getEvents` | Events |
+| `getCommands` | Commands |
+| `getQueries` | Queries |
+| `getFlows` | Flows |
+| `getChannels` | Channels |
+| `getEntities` | Entities |
+| `getAgents` | Agents |
+| `getContainers` | Containers |
+| `getDataProducts` | Data products |
+| `getAdrs` | Architecture decision records |
+| `getTeams` | Teams |
+| `getUsers` | Users |
+| `getItemsFromCollectionByIdAndSemverOrLatest` | A specific version, semver range, or latest item from a collection |
diff --git a/packages/core/docs/development/customization/05-custom-pages-and-api-routes/_category_.json b/packages/core/docs/development/customization/05-custom-pages-and-api-routes/_category_.json
new file mode 100644
index 000000000..4bc924722
--- /dev/null
+++ b/packages/core/docs/development/customization/05-custom-pages-and-api-routes/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Custom pages and API routes",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development/customization/custom-pages-and-api-routes",
+    "title": "Custom pages and API routes",
+    "description": "Add custom pages, internal tools, dashboards, and API routes to your EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/customization/06-customize-tables.md b/packages/core/docs/development/customization/06-customize-tables.md
new file mode 100644
index 000000000..ccaf90e52
--- /dev/null
+++ b/packages/core/docs/development/customization/06-customize-tables.md
@@ -0,0 +1,194 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog tables
+sidebar_label: Tables
+title: Customize tables
+description: Customize tables in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.63.0" />
+
+EventCatalog allows you to customize the columns and names on the [Explore page](https://demo.eventcatalog.dev/discover/events), [Teams](https://demo.eventcatalog.dev/directory/teams) and [Users](https://demo.eventcatalog.dev/directory/users) pages.
+
+![EventCatalog Custom Tables](./img/table-example.png)
+
+### How to customize tables
+
+You can customize the tables in EventCatalog by configuring them in your `eventcatalog.config.js` file.
+
+Example of how to customize the tables for the events table page:
+
+
+```js title="eventcatalog.config.js"
+events: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      summary: { visible: true, label: 'Summary' },
+      producers: { visible: true, label: 'Producers' },
+      consumers: { visible: true, label: 'Consumers' },
+      badges: { visible: true, label: 'Badges' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+},
+```
+### Configuration
+
+List of available configuration options for the table columns:
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `visible` | boolean | true | Whether the column is visible. |
+| `label` | string | - | The label to display for the column. |
+
+<details>
+  <summary>Events, Queries and Commands Table</summary>
+
+The key property is either `events`, `queries`, `commands`.
+
+In this example we set the **events** table configuration.
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+// change property to `events`, `queries`, `commands`
+events: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      summary: { visible: true, label: 'Summary' },
+      producers: { visible: true, label: 'Producers' },
+      consumers: { visible: true, label: 'Consumers' },
+      badges: { visible: true, label: 'Badges' },
+      actions: { visible: true, label: 'Actions' },
+    },
+  },
+}
+// ... other configuration ...
+```
+</details>
+<details>
+  <summary>Services Table</summary>
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+services: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      summary: { visible: true, label: 'Summary' },
+      receives: { visible: true, label: 'Receives' },
+      sends: { visible: true, label: 'Sends' },
+      badges: { visible: true, label: 'Badges' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+}
+// ... other configuration ...
+```
+</details>
+<details>
+  <summary>Domains Table</summary>
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+domains: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      summary: { visible: true, label: 'Summary' },
+      services: { visible: true, label: 'Owners' },
+      badges: { visible: true, label: 'Badges' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+}
+// ... other configuration ...
+```
+</details>
+<details>
+  <summary>Data Table</summary>
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+containers: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      summary: { visible: true, label: 'Summary' },
+      writes: { visible: true, label: 'Writes' },
+      reads: { visible: true, label: 'Reads' },
+      badges: { visible: true, label: 'Badges' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+}
+// ... other configuration ...
+```
+</details>
+<details>
+  <summary>Flows Table</summary>
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+flows: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      version: { visible: true, label: 'Version' },
+      summary: { visible: true, label: 'Summary' },
+      badges: { visible: true, label: 'Badges' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+}
+// ... other configuration ...
+```
+</details>
+<details>
+  <summary>Users Table</summary>
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+users: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },
+      ownedEvents: { visible: true, label: 'Owned Events' },
+      ownedCommands: { visible: true, label: 'Owned Commands' },
+      ownedQueries: { visible: true, label: 'Owned Queries' },
+      ownedServices: { visible: true, label: 'Owned Services' },
+      teams: { visible: true, label: 'Teams' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+}
+// ... other configuration ...
+```
+</details>
+<details>
+  <summary>Teams Table</summary>
+
+```js title="eventcatalog.config.js"
+// ... other configuration ...
+teams: {
+  tableConfiguration: {
+    columns: {
+      name: { visible: true, label: 'Name' },]
+      ownedEvents: { visible: true, label: 'Owned Events' },
+      ownedCommands: { visible: true, label: 'Owned Commands' },
+      ownedQueries: { visible: true, label: 'Owned Queries' },
+      ownedServices: { visible: true, label: 'Owned Services' },
+      actions: { visible: true, label: 'Actions' },
+    }
+  },
+}
+// ... other configuration ...
+```
+</details>
+
+
+
+You can read the `eventcatalog.config.js` API reference for [more information on the table configuration](/docs/api/config#domains).
diff --git a/packages/core/docs/development/customization/07-resource-icons.md b/packages/core/docs/development/customization/07-resource-icons.md
new file mode 100644
index 000000000..2b20f5252
--- /dev/null
+++ b/packages/core/docs/development/customization/07-resource-icons.md
@@ -0,0 +1,190 @@
+---
+sidebar_position: 7
+keywords:
+- EventCatalog resource icons
+- custom icons
+- resource customization
+sidebar_label: Resource icons
+title: Resource icons
+description: Customize the icons shown for resources in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+<AddedIn version="3.28.1" />
+
+Resource icons let you replace the default icon EventCatalog uses for a resource.
+
+Use them when you want services, messages, data stores, agents, or other catalog resources to show the technology, platform, vendor, or domain-specific concept they represent.
+
+Resource icons can appear in places like:
+
+- Resource page headers
+- Search and discover results
+- Resource references
+- Sidebar navigation
+- Visualizer nodes
+
+## Set a resource icon
+
+Add `styles.icon` to the resource frontmatter.
+
+```md title="/services/Orders/index.mdx"
+---
+id: Orders
+name: Orders
+version: 1.0.0
+summary: Handles order placement and order history.
+styles:
+  icon: /icons/languages/nodejs.svg
+---
+```
+
+The icon value must be either:
+
+- a path to a file in your catalog's `public` folder
+- an absolute `https://` or `http://` URL
+
+## Use icons from your catalog
+
+Put icon files in your catalog's `public` folder.
+
+<ProjectTree
+  items={[
+    {
+      name: 'public',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'icons',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'languages',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: 'nodejs.svg', highlight: true },
+                { name: 'go.svg', highlight: true },
+              ],
+            },
+            {
+              name: 'database',
+              type: 'folder',
+              defaultOpen: true,
+              children: [{ name: 'postgresql.svg', highlight: true }],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Files in `public` are served from the root of your catalog, so `public/icons/languages/nodejs.svg` is referenced as `/icons/languages/nodejs.svg`.
+
+## Use external icon URLs
+
+You can also use an absolute URL.
+
+```md title="/services/StripePayments/index.mdx"
+---
+id: StripePayments
+name: Stripe Payments
+version: 1.0.0
+summary: External payment provider used for card payments.
+externalSystem: true
+styles:
+  icon: https://cdn.simpleicons.org/stripe
+---
+```
+
+[Simple Icons CDN](https://cdn.simpleicons.org) is useful for common technology and vendor logos.
+
+## Examples
+
+### Service icon
+
+```md title="/services/Orders/index.mdx"
+---
+id: Orders
+name: Orders
+version: 1.0.0
+styles:
+  icon: /icons/languages/java.svg
+---
+```
+
+### Data store icon
+
+```md title="/containers/orders-db/index.mdx"
+---
+id: orders-db
+name: Orders DB
+version: 1.0.0
+container_type: database
+technology: postgres@16
+styles:
+  icon: /icons/database/postgresql.svg
+---
+```
+
+### Message icon
+
+```md title="/events/OrderPlaced/index.mdx"
+---
+id: OrderPlaced
+name: Order Placed
+version: 1.0.0
+summary: Raised when an order is placed.
+styles:
+  icon: /icons/events/eventbridge.svg
+---
+```
+
+## Supported file types
+
+Use image files that browsers can render, such as:
+
+- SVG
+- PNG
+- WEBP
+
+SVG icons usually work best because they stay sharp at different sizes.
+
+## Resource icons vs sidebar icons
+
+Resource icons use file paths or URLs through `styles.icon`.
+
+```md
+styles:
+  icon: /icons/languages/nodejs.svg
+```
+
+Application and documentation sidebar icons are different. Those use icon names from [Lucide](https://lucide.dev/icons/) in your sidebar configuration.
+
+```js title="eventcatalog.config.js"
+export default {
+  navigation: {
+    groups: [
+      {
+        id: 'main',
+        items: [{ id: 'docs', icon: 'BookOpen' }],
+      },
+    ],
+  },
+};
+```
+
+Use `styles.icon` when you want to customize a resource. Use sidebar icon names when you want to customize navigation.
+
+## Tips
+
+- Keep icons simple and readable at small sizes.
+- Prefer square or near-square assets.
+- Store shared icons under `public/icons`.
+- Use consistent folder names, such as `/icons/languages`, `/icons/database`, or `/icons/tools`.
+- Use external URLs only when you are comfortable depending on that external service at runtime.
diff --git a/packages/core/docs/development/customization/_category_.json b/packages/core/docs/development/customization/_category_.json
new file mode 100644
index 000000000..5cadd4d35
--- /dev/null
+++ b/packages/core/docs/development/customization/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Customization",
+  "position": 8,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/customization",
+    "title": "Customization Documentation",
+    "description": "Learn how to customize EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/customization/customize-visualizer/00-visualizer-nodes.md b/packages/core/docs/development/customization/customize-visualizer/00-visualizer-nodes.md
new file mode 100644
index 000000000..ca5d5d219
--- /dev/null
+++ b/packages/core/docs/development/customization/customize-visualizer/00-visualizer-nodes.md
@@ -0,0 +1,50 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog visualizer nodes 
+sidebar_label: Customize nodes
+title: Customize visualizer nodes
+description: Customize the color, label and icon of the visualizer nodes.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.33.8" />
+
+Every node in the visualizer has a color, label and icon. 
+
+The example below shows the default node for a **Service** resource.
+
+<!-- Image image -->
+![Visualizer Node](./img/customize-node.png)
+
+By default the icon, color and label in the node is generated by EventCatalog. Helping you maintain consistency across your catalog.
+
+You can use the `styles` property to customize the icon, color and label of the node, if you want to customize the node to be more specific to your use case.
+
+```md title="/domains/MyDomain/services/MyService.md"
+---
+id: NotificationService
+version: 0.0.2
+name: Notification Service
+summary: |
+  Service that handles orders
+styles:
+  icon: "BellIcon"
+  node: 
+    color: purple
+    label: "Custom"
+---
+```
+
+#### Rendered output
+
+![Customized Node](./img/customize-node-example.png)
+
+### Configuration
+
+| ID | Required | Default | Description |
+| --- | --- | --- | --- |
+| `styles.icon` | No | Depends on resource type | The icon to use for the resource. Icons are from [hero icons](https://heroicons.com/). <br/> You can find a list of icons [here](https://unpkg.com/browse/@heroicons/react@2.1.5/24/outline/). |
+| `styles.node.color` | No | Depends on resource type | The color to use for the node. These are tailwind colors and you can find a list of them [here](https://tailwindcss.com/docs/colors). |
+| `styles.node.label` | No | Depends on resource type | The label to use for the node (side label). |
\ No newline at end of file
diff --git a/packages/core/docs/development/customization/customize-visualizer/_category_.json b/packages/core/docs/development/customization/customize-visualizer/_category_.json
new file mode 100644
index 000000000..d357dd6e3
--- /dev/null
+++ b/packages/core/docs/development/customization/customize-visualizer/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Customize Visualizer",
+  "position": 8,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/customize-visualizer",
+    "description": "A collection of guides to help you customize the visualizer in your catalog."
+  }
+}
diff --git a/packages/core/docs/development/deployment/_category_.json b/packages/core/docs/development/deployment/_category_.json
new file mode 100644
index 000000000..4cb9c783d
--- /dev/null
+++ b/packages/core/docs/development/deployment/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Deployment",
+  "position": 12,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/deployment",
+    "title": "Deployment guides",
+    "description": "This section contains deployment tutorials for developers. This includes tutorials for deploying to Heroku, AWS, and other cloud providers."
+  }
+}
diff --git a/packages/core/docs/development/deployment/build-and-deploy.md b/packages/core/docs/development/deployment/build-and-deploy.md
new file mode 100644
index 000000000..b2849b087
--- /dev/null
+++ b/packages/core/docs/development/deployment/build-and-deploy.md
@@ -0,0 +1,71 @@
+---
+sidebar_position: 5
+keywords:
+- build
+- deploy
+sidebar_label: Build (Static Mode)
+title: Building Eventcatalog
+description: This document describes step by step how to deploy EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+By default, EventCatalog exports a static HTML site. This means you can deploy your application anywhere you want.
+
+:::tip Have large or slow deployments?
+Some users have large catalogs, and slow deployments. This is because the static mode builds the entire catalog into HTML files.
+
+If you have a large catalog you may want to use [SSR mode](/docs/development/deployment/build-ssr-mode), this will give you a server-side rendered application. 
+This reduces build times, and renders pages on the fly. 
+:::
+
+
+## Building your EventCatalog (Static)
+
+To build your Catalog you will need to run:
+
+```bash
+npm run build
+```
+
+This will output one directory
+
+- `dist` - Your EventCatalog as Static HTML
+
+### Passing custom options
+
+<AddedIn version="2.16.5" />
+
+EventCatalog uses [Astro](https://astro.build/) to build the application. You can pass custom options to the build command by using the `--` prefix.
+
+```bash title="Passing custom options"
+npx eventcatalog dev --debug -- --env=production --port=3000
+```
+
+### Compression
+
+You can opt into our build step which will compress your static assets. 
+
+You can enable this by setting the [compress option](/docs/api/config#compress) to `true` in your `eventcatalog.config.js` file.
+
+:::info "Why is compression disabled by default?"
+Compression can increase your build time and the amount of memory required to build your catalog.
+
+If you want to enable this feature, you might also want to increase your build memory using the `max_old_space_size` value.
+:::
+
+### Memory limits
+
+If you get any `JavaScript heap out of memory` errors, you can increase the memory limit by setting the `NODE_OPTIONS` environment variable. This gives astro more memory to work with.
+
+```bash title="Increasing the memory limit"
+NODE_OPTIONS=--max_old_space_size=8196 npm run build
+```
+
+If you are still experiencing issues, you can try:
+
+
+- Turning off HTML compression ([see documentation](/docs/api/config#compress))
+- Turning on MDX optimization ([see documentation](/docs/api/config#mdxOptimize))
+- Rendering EventCatalog in [SSR mode](/docs/development/deployment/build-ssr-mode). 
+    - This requires you to run your EventCatalog on a server. But your pages are rendered on the fly, so you don't need to build the entire catalog into HTML files. This can also save you a lot of time when deploying your catalog.
diff --git a/packages/core/docs/development/deployment/build-ssr-mode.md b/packages/core/docs/development/deployment/build-ssr-mode.md
new file mode 100644
index 000000000..5650b968b
--- /dev/null
+++ b/packages/core/docs/development/deployment/build-ssr-mode.md
@@ -0,0 +1,50 @@
+---
+sidebar_position: 5
+keywords:
+- build
+- deploy
+sidebar_label: Build (SSR Mode)
+title: Building Eventcatalog
+description: This document describes step by step how to deploy EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+You can also use EventCatalog in SSR mode, which means you can use EventCatalog as a server-side rendered application.
+
+This can be useful for large catalogs, or for users with slow deployment times.
+
+Certain features like **Authentication** and **EventCatalog Chat** require SSR mode.
+
+### How it works
+
+Rather than building the entire catalog into HTML files, EventCatalog will render the pages on the fly (using server-side rendering).
+
+This means you can use EventCatalog as a server-side rendered application.
+
+## Building your EventCatalog (SSR)
+
+First you need to update your `eventcatalog.config.js` file to use SSR mode.
+
+```js title="eventcatalog.config.js"
+export default {
+  // defaults to static
+  output: 'server', 
+}
+```
+
+Next you need to build your EventCatalog
+
+```bash
+npm run build
+```
+
+This will output one directory
+
+- `dist` - Your EventCatalog as a SSR application
+
+## Deployment   
+
+You will need to deploy your EventCatalog to a server that can run Node.js.
+
+The easiest way to do this is to use [a docker container](/docs/development/deployment/hosting-options#hosting-static-website-with-docker).
\ No newline at end of file
diff --git a/packages/core/docs/development/deployment/deployment-workflows.md b/packages/core/docs/development/deployment/deployment-workflows.md
new file mode 100644
index 000000000..c43edcfd8
--- /dev/null
+++ b/packages/core/docs/development/deployment/deployment-workflows.md
@@ -0,0 +1,43 @@
+---
+sidebar_position: 5
+keywords:
+- build
+- deploy
+sidebar_label: Deployment Workflows
+title: Deployment Workflows
+description: This document describes different deployment workflows for EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Many people are deploying EventCatalog in different ways, as it's self hosted you can rebuild and redeploy your catalog as often as you want.
+
+### Keeping EventCatalog up to date
+
+Keeping documentation up to date is a challenge, as it's easy to forget to update the documentation when you make changes to your code.
+
+One way to keep your documentation up to date, is to redeploy your catalog whenever changes are made to your code, specifications or schemas.
+
+EventCatalog has companies redeploying their catalogs hundreds of times a day.... it really depends on how often you make changes to your code, specifications or schemas, and how often you want to update your documentation. **You are in control of how often you redeploy your catalog.**
+
+Many folks using EventCatalog have information scattered across multiple repositories, schema registries and other systems.
+
+Users of EventCatalog either use [our integrations (e.g AsyncAPI, OpenAPI, Schema Registry)](/integrations) or have built their own automated systems using our [SDK](/docs/sdk).
+
+### CI/CD workflow to keep your documentation up to date
+
+EventCatalog is docs-as-code solution. This means you can store EventCatalog next to your code and in git repositories.
+
+You can setup your CI/CD pipeline to build and deploy your catalog whenever changes are made to your code, specifications or schemas.
+
+
+```mermaid LR
+flowchart LR
+    A[Code changes in any repository] --> B[Trigger CI/CD pipeline to build and deploy catalog]
+    B --> C[EventCatalog is rebuilt and deployed]
+```
+
+EventCatalog is flexible. And you can redeploy your catalog in various ways.
+
+This can let you setup automation to ensure your documentation can stay up to date with any changes to your code, specifications or schemas.
+
diff --git a/packages/core/docs/development/deployment/hosting-options.md b/packages/core/docs/development/deployment/hosting-options.md
new file mode 100644
index 000000000..97989342f
--- /dev/null
+++ b/packages/core/docs/development/deployment/hosting-options.md
@@ -0,0 +1,111 @@
+---
+sidebar_position: 6
+keywords:
+- build
+- deploy
+sidebar_label: Hosting
+title: Hosting
+description: This document describes hosting options for EventCatalog.
+---
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+### Hosting Options
+
+EventCatalog can be hosted in two ways:
+
+- [Hosting a static website output (default)](#hosting-a-static-website)
+- [Hosting EventCatalog Server](#hosting-as-a-server)
+
+### Hosting a static website
+
+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)
+- [Deploy to NextJS](https://nextjs.org/docs/deployment)
+- [Host in AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html)
+
+**Community posts**
+- [Using AWS CDK to Deploy EventCatalog](https://matt.martz.codes/using-aws-cdk-to-deploy-eventcatalog)
+- [Using Netlify to host Static Content](https://www.netlify.com/blog/2016/10/27/a-step-by-step-guide-deploying-a-static-site-or-single-page-app/)
+- [How to create an EventCatlaog with Azure](https://www.kallemarjokorpi.fi/blog/how-to-create-and-event-catalog.html)
+- [Autonomous EventCatalog for documenting EventBridge Events](https://medium.com/@wrennkieran/autonomous-eventcatalog-for-documenting-eventbridge-events-73e6334f2400)
+
+### Hosting static website with Docker
+
+EventCatalog comes with a DockerFile you can build the image and deploy the container. The container exposes ports `3000`.
+
+To build the docker container you need to run:
+
+```bash
+# Builds the container
+docker build -t eventcatalog .
+
+# Runs the container locally
+docker run -p 3000:80 -it eventcatalog
+```
+
+### Hosting as a server
+
+<AddedIn version="2.35.4" />
+
+First you need to update your `eventcatalog.config.js` file to use SSR mode.
+
+```js title="eventcatalog.config.js"
+export default {
+  // defaults to static
+  output: 'server', 
+}
+```
+
+A server output is required if you are using any EventCatalog feature that requires a server, these include:
+
+- [EventCatalog Chat (bring your own keys)](/features/ai-assistant)
+- [EventCatalog Authentication](/docs/development/authentication/introduction)
+
+You can use the server Docker image to run the server, this is the recommended way to run the server.
+
+First you need to create a Dockerfile for the server (if you don't already have one).
+
+```bash title="/Dockerfile.server"
+FROM node:lts AS runtime
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+RUN npm run build
+
+ENV HOST=0.0.0.0
+ENV PORT=3000
+EXPOSE 3000
+
+# Start the server
+CMD npm run start
+```
+
+Then you can build the docker image with:
+
+```bash
+docker build -f Dockerfile.server -t eventcatalog-server .
+```
+
+Then you can run the server with:
+
+```bash
+docker run -p 3000:3000 eventcatalog-server
+```
+
+:::info "Why do I need a server to run EventCatalog?"
+
+Some features of EventCatalog require a server to run (e.g. [EventCatalog Chat](/features/ai-assistant) and [EventCatalog Authentication](/docs/development/authentication/introduction)).
+
+If you have a large catalog, you may want to use [SSR mode](/docs/development/deployment/build-ssr-mode) to reduce build times.
+
+:::
diff --git a/packages/core/docs/development/design/_category_.json b/packages/core/docs/development/design/_category_.json
new file mode 100644
index 000000000..a0837162b
--- /dev/null
+++ b/packages/core/docs/development/design/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Designing with Studio",
+  "position": 30,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "design",
+    "title": "Design",
+    "description": "This section describes how to use EventCatalog to design workflows and new ideas."
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/development/design/embed-designs-into-eventcatalog.md b/packages/core/docs/development/design/embed-designs-into-eventcatalog.md
new file mode 100644
index 000000000..1af52a278
--- /dev/null
+++ b/packages/core/docs/development/design/embed-designs-into-eventcatalog.md
@@ -0,0 +1,29 @@
+---
+sidebar_position: 4
+keywords:
+- design
+- studio
+- resources
+sidebar_label: Embed Designs into EventCatalog
+title: Embed Designs into EventCatalog
+description: Embed Designs into EventCatalog with EventCatalog
+unlisted: true
+---
+
+You can embed any diagram directly into your documentation using the [`<Design />`](/docs/development/components/components/design) component.
+
+![Embed into EventCatalog](/img/embed-ec.png)
+
+To embed your diagrams you need to:
+
+1. Save your diagram as a `.ecstudio` file
+1. Put your `.ecstudio` file in the location of your markdown file in EventCatalog.
+2. Use the [`<Design />`](/docs/development/components/components/design) component in your markdown file to embed your diagram into your documentation
+
+:::info Embed diagrams anywhere
+
+Our vision to to allow users to be embed diagrams anywhere, letting them embed diagrams into their tools they already use.
+
+This is currently on our roadmap, and we will be adding more support for this in the future.
+
+:::
diff --git a/packages/core/docs/development/design/further-reading.md b/packages/core/docs/development/design/further-reading.md
new file mode 100644
index 000000000..f2e555e42
--- /dev/null
+++ b/packages/core/docs/development/design/further-reading.md
@@ -0,0 +1,19 @@
+---
+sidebar_position: 5
+keywords:
+- design
+- studio
+- resources
+sidebar_label: Further Reading
+title: Further Reading
+description: Further Reading with EventCatalog
+unlisted: true
+---
+
+If you want to learn more about EventCatalog Studio you can [read our documentation here](/docs/studio/getting-started) or click on the links below to learn more.
+
+
+
+- [How to add nodes to your diagram](/docs/studio/diagrams/using-nodes)
+- [Adding comments to your designs](/docs/studio/diagrams/adding-comments)
+- [Import & Export your designs](/docs/studio/diagrams/import-export)
diff --git a/packages/core/docs/development/design/import-resources.md b/packages/core/docs/development/design/import-resources.md
new file mode 100644
index 000000000..7dbca7651
--- /dev/null
+++ b/packages/core/docs/development/design/import-resources.md
@@ -0,0 +1,27 @@
+---
+sidebar_position: 3
+keywords:
+- design
+- studio
+- resources
+sidebar_label: Import Resources into Studio
+title: Import Resources into Studio
+description: Import Resources into Studio with EventCatalog
+unlisted: true
+---
+
+To import your resources into EventCatalog Studio, click on the **EventCatalog Studio** button in the navigation bar, then click on the **Open EventCatalog Studio** button.
+
+![Import Resources](./img/studio.png)
+
+Then click on **Copy resources to clipboard** to copy your architecture primitives to the clipboard, then click on **Open EventCatalog Studio** to open the drag and drop editor.
+
+<img src="/img/studio-copy.png" alt="Copy Resources" />
+
+Then you can paste your resources into the drag and drop editor, and click **Import resources** to import your resources into the drag and drop editor.
+
+![Import Resources](./img/paste.png)
+
+Once you have imported your resources, you can start to use them to create new designs or workflows for your architecture.
+
+![Import Resources](./img/example.png)
diff --git a/packages/core/docs/development/design/intro.md b/packages/core/docs/development/design/intro.md
new file mode 100644
index 000000000..0cc599b85
--- /dev/null
+++ b/packages/core/docs/development/design/intro.md
@@ -0,0 +1,22 @@
+---
+sidebar_position: 2
+keywords:
+- components
+sidebar_label: Documentation to Design
+title: Documentation to Design
+description: Documentation to Design with EventCatalog
+unlisted: true
+---
+
+When you document your architecture with EventCatalog, you can use your architecture primitives (your domains, services, messages, channels, schemas, etc) to create designs of business workflows, and explore new ideas with your teams using our drag and drop editor [(EventCatalog Studio)](http://eventcatalog.studio/).
+
+This can be useful if you want to share new ideas with your teams, or document end to end business workflows in your organization using a drag and drop interface.
+This means your developers, architects and business stakeholders can all work together to create workflows or designs together and embed them back into your documentation.
+
+![Design workflows](/img/studio-app-2.png)
+
+### How EventCatalog Studio works
+
+EventCatalog Studio is a drag and drop editor that lets you create designs (.ecstudio files) with your architecture primitives.
+
+You can embed these designs back into your documentation using the [`<Design />` component](/docs/development/components/components/design).
diff --git a/packages/core/docs/development/developer-tools/_category_.json b/packages/core/docs/development/developer-tools/_category_.json
new file mode 100644
index 000000000..a11f5d060
--- /dev/null
+++ b/packages/core/docs/development/developer-tools/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Developer tools",
+  "position": 11,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "developer-tools",
+    "title": "Developer tools",
+    "description": "Developer tools for EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/developer-tools/api-catalog.md b/packages/core/docs/development/developer-tools/api-catalog.md
new file mode 100644
index 000000000..4a46c1f95
--- /dev/null
+++ b/packages/core/docs/development/developer-tools/api-catalog.md
@@ -0,0 +1,114 @@
+---
+sidebar_position: 5
+keywords:
+- api-catalog
+- RFC 9727
+- well-known
+- API discovery
+- OpenAPI
+- AsyncAPI
+- GraphQL
+sidebar_label: api-catalog (RFC 9727)
+title: api-catalog
+description: Machine-readable catalog discovery endpoint for tools and agents
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.42.0" />
+
+Let API tools, agents, and crawlers discover every service and domain specification in your catalog from a single endpoint, without parsing HTML.
+
+### What is RFC 9727?
+
+[RFC 9727](https://datatracker.ietf.org/doc/rfc9727/) defines the `/.well-known/api-catalog` well-known URI. It returns a [Linkset](https://www.rfc-editor.org/rfc/rfc9264) document that lists every API an organization publishes along with links to their specifications and documentation.
+
+Tools that understand RFC 9727 can point at your catalog URL and immediately enumerate all services and domains, their OpenAPI, AsyncAPI, and GraphQL specs, and their documentation pages. No scraping required.
+
+### How it works
+
+EventCatalog automatically publishes a Linkset at `/.well-known/api-catalog`. Every service and domain that has `specifications` defined in its frontmatter appears as an entry.
+
+Each entry contains:
+
+- **`anchor`** - the canonical URL of the service. EventCatalog reads the `servers[].url` field from OpenAPI or AsyncAPI specs and uses that. When no server URL is found it falls back to the EventCatalog documentation page.
+- **`service-desc`** - one link per specification file, pointing at `/api-catalog/specifications/{collection}/{id}/{version}/{specification}` with the correct media type (`application/yaml`, `application/json`, or `application/graphql`).
+- **`service-doc`** - two links per resource: the markdown source and the rendered HTML page.
+
+Resources marked `hidden: true` are excluded from the linkset.
+
+### Access the endpoint
+
+```
+GET  /.well-known/api-catalog
+HEAD /.well-known/api-catalog
+```
+
+The `GET` response body is `application/linkset+json` profiled against RFC 9727:
+
+```json
+{
+  "linkset": [
+    {
+      "anchor": "https://api.example.com/orders",
+      "service-desc": [
+        {
+          "href": "https://catalog.example.com/api-catalog/specifications/services/OrderService/1.0.0/openapi-b3BlbmFwaS55bWw",
+          "type": "application/yaml",
+          "title": "Order Service OpenAPI"
+        }
+      ],
+      "service-doc": [
+        {
+          "href": "https://catalog.example.com/docs/services/OrderService/1.0.0.md",
+          "type": "text/markdown",
+          "title": "Order Service documentation"
+        },
+        {
+          "href": "https://catalog.example.com/docs/services/OrderService/1.0.0",
+          "type": "text/html",
+          "title": "Order Service documentation"
+        }
+      ]
+    }
+  ]
+}
+```
+
+The `HEAD` response includes a `Link` header so clients can confirm the endpoint exists before fetching the full body:
+
+```
+Link: <https://catalog.example.com/.well-known/api-catalog>; rel="api-catalog"
+```
+
+### Fetch a specification file
+
+The raw specification files referenced in `service-desc` are served from:
+
+```
+GET /api-catalog/specifications/{collection}/{id}/{version}/{specification}
+```
+
+| Segment | Values |
+|---------|--------|
+| `collection` | `services`, `domains` |
+| `id` | The resource `id` field |
+| `version` | The resource `version` field |
+| `specification` | Stable specification identifier, formatted as `{type}-{base64url(path)}` |
+
+Example:
+
+```
+GET /api-catalog/specifications/services/OrderService/1.0.0/openapi-b3BlbmFwaS55bWw
+Content-Type: application/yaml
+```
+
+### MCP server entry
+
+When the EventCatalog MCP server is enabled, an additional entry pointing at `/docs/mcp` is appended to the linkset. This lets MCP-aware agents discover the catalog's machine interface alongside its API specifications.
+
+### What is included
+
+Only services and domains are included in v1 of this endpoint. Events, commands, queries, data products, schemas, diagrams, teams, and users are out of scope for this release.
+
+For a broader machine-readable index of your catalog content, see [llms.txt](/docs/development/ask-your-architecture/llms.txt) and [schemas.txt](/docs/development/ask-your-architecture/schemas.txt).
diff --git a/packages/core/docs/development/developer-tools/eventcatalog-linter.md b/packages/core/docs/development/developer-tools/eventcatalog-linter.md
new file mode 100644
index 000000000..7425be3bd
--- /dev/null
+++ b/packages/core/docs/development/developer-tools/eventcatalog-linter.md
@@ -0,0 +1,732 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog linter
+- schema validation
+- reference validation
+- CI/CD
+- quality assurance
+sidebar_label: EventCatalog Linter
+title: EventCatalog Linter
+description: Validate your EventCatalog frontmatter schemas and resource references with the comprehensive EventCatalog Linter
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+A comprehensive linter for EventCatalog that validates frontmatter schemas and resource references to ensure your architecture documentation is correct and consistent.
+
+The EventCatalog Linter helps you catch issues early in your development process, ensuring your documentation maintains high quality and accuracy across all your EventCatalog resources.
+
+## Use cases
+
+- **Quality Assurance**: Ensure your documentation is correct and consistent
+- **CI/CD**: Integrate the linter into your CI/CD pipeline to catch issues early
+- **Documentation**: Run the linter regularly as part of your development workflow
+- **Version Consistency**: Use consistent version patterns across your EventCatalog resources
+
+## Features
+
+- **📋 Schema Validation**: Validates all resource frontmatter against defined schemas using Zod
+- **🔗 Reference Validation**: Ensures all referenced resources (services, events, domains, etc.) actually exist
+- **📦 Semver Version Support**: Supports semantic versions, ranges (`^1.0.0`, `~1.2.0`), x-patterns (`0.0.x`), and `latest`
+- **⚙️ Configurable Rules**: Optional `.eventcatalogrc.js` config file for customizing rule severity and behavior
+- **🚫 Ignore Patterns**: Skip validation for specific file patterns (archived, drafts, etc.)
+- **🎯 Rule Overrides**: Apply different rules to different file patterns for flexible team workflows
+- **🎯 Comprehensive Coverage**: Supports all EventCatalog resource types
+- **⚡ Fast Performance**: Efficiently scans large catalogs
+- **🎨 ESLint-Inspired Output**: Clean, file-grouped error reporting with severity levels
+- **⚠️ Warnings Support**: Distinguish between errors and warnings with `--fail-on-warning` option
+
+### Supported Resource Types
+
+The linter validates all EventCatalog resource types:
+
+- 🏢 **Domains** (including subdomains)
+- ⚙️ **Services**
+- 📨 **Events**
+- 📤 **Commands**
+- ❓ **Queries**
+- 📡 **Channels**
+- 🔄 **Flows**
+- 📊 **Entities**
+- 🤖 **Agents**
+- 🧱 **Containers** (including the legacy data store alias)
+- 📈 **Data Products**
+- 🧭 **Diagrams**
+- 📝 **ADRs**
+- 👤 **Users**
+- 👥 **Teams**
+
+<AddedIn version="1.2.0" />
+
+Agents, Containers, Data Products, Diagrams, and ADRs are validated as of version 1.2.0.
+
+## Quick Start
+
+Get started with the EventCatalog Linter in three simple steps:
+
+### 1. Run the Linter
+
+Start linting your EventCatalog immediately with npx:
+
+```bash
+npx @eventcatalog/linter
+```
+
+### 2. Configure Rules (Optional)
+
+Create a `.eventcatalogrc.js` file in your EventCatalog root to customize validation:
+
+```javascript
+module.exports = {
+  rules: {
+    'best-practices/summary-required': 'warn',
+    'refs/owner-exists': 'error'
+  },
+  ignorePatterns: ['**/drafts/**']
+};
+```
+
+### 3. Integrate with CI/CD
+
+Add to your CI/CD pipeline for automated validation:
+
+```yaml
+# GitHub Actions
+- run: npx @eventcatalog/linter --fail-on-warning
+```
+
+## Installation
+
+### Use with npx (Recommended)
+
+<Tabs>
+  <TabItem value="npm">
+```bash
+npx @eventcatalog/linter
+```
+</TabItem>
+<TabItem value="pnpm">
+```bash
+pnpm dlx @eventcatalog/linter
+```
+</TabItem>
+</Tabs>
+
+### Global Installation
+
+<Tabs>
+  <TabItem value="npm">
+```bash
+npm install -g @eventcatalog/linter
+```
+</TabItem>
+<TabItem value="pnpm">
+```bash
+pnpm install -g @eventcatalog/linter
+```
+</TabItem>
+</Tabs>
+
+### Add to your project
+
+<Tabs>
+  <TabItem value="npm">
+```bash
+npm install --save-dev @eventcatalog/linter
+```
+</TabItem>
+<TabItem value="pnpm">
+```bash
+pnpm install --save-dev @eventcatalog/linter
+```
+</TabItem>
+</Tabs>
+
+## Usage
+
+### Basic Usage
+
+Run the linter in your EventCatalog directory:
+
+```js
+// Lint current directory
+eventcatalog-linter
+
+// Lint specific directory
+eventcatalog-linter ./my-eventcatalog
+
+// Verbose output with detailed information
+eventcatalog-linter --verbose
+
+// Show help
+eventcatalog-linter --help
+```
+
+### CLI Options
+
+```
+Usage: eventcatalog-linter [options] [directory]
+
+Arguments:
+  directory              EventCatalog directory to lint (default: ".")
+
+Options:
+  -V, --version          output the version number
+  -v, --verbose          Show verbose output (default: false)
+  --fail-on-warning      Exit with non-zero code on warnings (default: false)
+  -h, --help             display help for command
+```
+
+## Configuration
+
+The EventCatalog Linter supports optional configuration through a `.eventcatalogrc.js` file in your catalog root directory. This allows you to:
+
+- Turn rules on/off 
+- Configure rule severity levels (error, warn, off)
+- Ignore specific file patterns
+- Override rules for specific file patterns
+
+### Quick Start with Configuration
+
+Create a `.eventcatalogrc.js` file in your EventCatalog root directory:
+
+```javascript
+// .eventcatalogrc.js
+module.exports = {
+  rules: {
+    // Schema validation rules
+    'schema/required-fields': 'error',
+    'schema/valid-semver': 'error', 
+    'schema/valid-email': 'warn',
+    
+    // Reference validation rules
+    'refs/owner-exists': 'error',
+    'refs/valid-version-range': 'error',
+    
+    // Best practice rules
+    'best-practices/summary-required': 'warn',
+    'best-practices/owner-required': 'error',
+  },
+  
+  // Ignore certain paths
+  ignorePatterns: ['**/archived/**', '**/drafts/**'],
+  
+  // Override rules for specific file patterns
+  overrides: [
+    {
+      files: ['**/experimental/**'],
+      rules: {
+        'best-practices/owner-required': 'off'
+      }
+    }
+  ]
+};
+```
+
+### Rule Severity Levels
+
+- **`'error'`** - Causes the linter to exit with error code 1
+- **`'warn'`** - Shows warnings but allows the linter to pass (unless `--fail-on-warning` is used)
+- **`'off'`** - Disables the rule completely
+
+### Available Rules
+
+| Rule Name | Description | Accepted Values | Default |
+|-----------|-------------|-----------------|----------|
+| **Schema Validation Rules** |
+| `schema/required-fields` | Validates that required fields are present in frontmatter | `error`, `warn`, `off` | `error` |
+| `schema/valid-type` | Validates that field types are correct (strings, arrays, objects) | `error`, `warn`, `off` | `error` |
+| `schema/valid-semver` | Validates semantic version format (1.0.0, 2.1.3-beta) | `error`, `warn`, `off` | `error` |
+| `schema/valid-email` | Validates email address format in user frontmatter | `error`, `warn`, `off` | `error` |
+| `schema/validation-error` | General schema validation errors | `error`, `warn`, `off` | `error` |
+| **Reference Validation Rules** |
+| `refs/owner-exists` | Ensures referenced owners (users/teams) exist | `error`, `warn`, `off` | `error` |
+| `refs/valid-version-range` | Validates version references and patterns | `error`, `warn`, `off` | `error` |
+| `refs/resource-exists` | Ensures referenced resources exist (always enabled for critical resources) | Always enabled | Always enabled |
+| **Best Practice Rules** |
+| `best-practices/summary-required` | Requires summary field for better documentation | `error`, `warn`, `off` | `error` |
+| `best-practices/owner-required` | Requires at least one owner for accountability | `error`, `warn`, `off` | `error` |
+
+:::info Core Resource Validation
+Core resource reference validation (services, domains, entities) is always enabled and cannot be disabled, ensuring referential integrity of your EventCatalog.
+:::
+
+### Configuration Examples
+
+#### Relaxed Configuration for Development
+
+```javascript
+module.exports = {
+  rules: {
+    'best-practices/summary-required': 'warn',
+    'best-practices/owner-required': 'warn',
+    'refs/owner-exists': 'warn',
+  },
+  ignorePatterns: ['**/drafts/**', '**/experimental/**']
+};
+```
+
+#### Strict Configuration for Production
+
+```javascript
+module.exports = {
+  rules: {
+    'schema/required-fields': 'error',
+    'refs/owner-exists': 'error',
+    'best-practices/summary-required': 'error',
+    'best-practices/owner-required': 'error',
+  }
+};
+```
+
+#### Team-Specific Overrides
+
+```javascript
+module.exports = {
+  rules: {
+    'best-practices/owner-required': 'error',
+    'best-practices/summary-required': 'error',
+  },
+  overrides: [
+    {
+      files: ['**/legacy/**'],
+      rules: {
+        'best-practices/owner-required': 'warn',
+        'best-practices/summary-required': 'off'
+      }
+    },
+    {
+      files: ['**/critical/**'],
+      rules: {
+        'best-practices/summary-required': 'error',
+        'refs/owner-exists': 'error'
+      }
+    }
+  ]
+};
+```
+
+### Using with CI/CD
+
+The configuration file allows you to have different validation rules for different environments:
+
+```bash
+# Development - warnings allowed
+npx @eventcatalog/linter
+
+# Production - fail on warnings
+npx @eventcatalog/linter --fail-on-warning
+```
+
+### Default Behavior
+
+If no `.eventcatalogrc.js` file is found, the linter uses the default rules listed above. Most validations are errors by default, while documentation quality checks such as orphan messages, missing descriptions, missing schemas, and deprecated references default to warnings.
+
+### Package.json Integration
+
+Add to your `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "lint:eventcatalog": "eventcatalog-linter",
+    "lint:eventcatalog:verbose": "eventcatalog-linter --verbose"
+  }
+}
+```
+
+## What It Validates
+
+### Frontmatter Schema Validation
+
+- ✅ Required fields are present (`id`, `name`, `version`)
+- ✅ Field types are correct (strings, arrays, objects)
+- ✅ Semantic versions follow proper format (`1.0.0`, `2.1.3-beta`)
+- ✅ Version patterns supported (`latest`, `^1.0.0`, `~1.2.0`, `0.0.x`)
+- ✅ URLs are valid format
+- ✅ Email addresses are valid format
+- ✅ Enum values are from allowed lists
+- ✅ Nested object structures are correct
+- ✅ Common resource configuration is supported, including `attachments`, `editUrl`, `diagrams`, `detailsPanel`, sidebar colors, and GraphQL specifications
+
+### Reference Validation
+
+- ✅ Services referenced in domains exist
+- ✅ Agents, data products, flows, entities, and subdomains referenced in domains exist
+- ✅ Events/Commands/Queries referenced in services exist
+- ✅ Events/Commands/Queries referenced in agents exist
+- ✅ Data product inputs and outputs reference existing resources
+- ✅ ADR relationships and typed `appliesTo` references exist
+- ✅ Entities referenced in domains/services exist
+- ✅ Channels referenced in sends/receives `to`/`from`, routes, messages, and message channels exist
+- ✅ Containers referenced in `writesTo`/`readsFrom` exist
+- ✅ Diagrams referenced from other resources exist
+- ✅ Users/Teams referenced as owners exist
+- ✅ User/team owned resources and team members exist
+- ✅ Flow steps reference existing services/messages/agents/containers/data products
+- ✅ Entity properties reference existing entities
+- ✅ Version-specific references are valid
+
+<AddedIn version="1.2.0" />
+
+The expanded reference checks for agents, data products, ADRs, diagrams, and flow steps were added in version 1.2.0.
+
+## Example Output
+
+### ✅ Success Output
+
+```bash
+$ eventcatalog-linter
+
+✔ No problems found!
+
+  42 files checked
+```
+
+### ❌ Error Output
+
+```bash
+$ eventcatalog-linter
+
+services/user-service/index.mdx
+  ✖ error version: Invalid semantic version format [version] (schema/valid-semver)
+  ⚠ warning Summary is required for better documentation [summary] (best-practices/summary-required)
+
+✖ 2 problems
+
+domains/sales/index.mdx
+  ✖ error Referenced service "order-service" does not exist [services] (refs/resource-exists)
+
+✖ 1 problem
+
+flows/user-registration/index.mdx
+  ✖ error Referenced service "notification-service" (version: 2.0.0) does not exist [steps[1].service] (refs/valid-version-range)
+
+✖ 1 problem
+
+✖ 4 problems (3 errors, 1 warning)
+  3 files checked
+```
+
+## Version Pattern Support
+
+The linter supports flexible version patterns for resource references:
+
+### Exact Versions
+
+```yaml
+sends:
+  - id: user-created
+    version: 1.0.0 # Exact semantic version
+```
+
+### Latest Version
+
+```yaml
+sends:
+  - id: user-created
+    version: latest # Always use the latest available version
+```
+
+### Semver Ranges
+
+```yaml
+sends:
+  - id: user-created
+    version: ^1.0.0 # Compatible with 1.x.x (1.0.0, 1.2.3, but not 2.0.0)
+  - id: user-updated
+    version: ~1.2.0 # Compatible with 1.2.x (1.2.0, 1.2.5, but not 1.3.0)
+```
+
+### X-Pattern Matching
+
+```yaml
+sends:
+  - id: user-created
+    version: 0.0.x # Matches 0.0.1, 0.0.5, 0.0.12, etc.
+  - id: order-placed
+    version: 1.x # Matches 1.0.0, 1.5.3, 1.99.0, etc.
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: EventCatalog Lint
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - run: npx @eventcatalog/linter
+```
+
+### GitLab CI
+
+```yaml
+eventcatalog-lint:
+  stage: test
+  image: node:18
+  script:
+    - npx @eventcatalog/linter
+```
+
+## Rule Names and Error Codes
+
+The linter provides descriptive rule names in parentheses to help identify and fix issues quickly. Each error shows the specific rule that was violated:
+
+### Schema Validation Rules
+
+- `(schema/required-fields)` - Required field is missing
+- `(schema/valid-type)` - Field has wrong data type  
+- `(schema/valid-semver)` - Invalid semantic version format
+- `(schema/valid-email)` - Invalid email address format
+- `(schema/validation-error)` - General schema validation error
+
+### Reference Validation Rules
+
+- `(refs/owner-exists)` - Referenced owner (user/team) doesn't exist
+- `(refs/valid-version-range)` - Referenced version doesn't exist or invalid pattern
+- `(refs/resource-exists)` - Referenced resource doesn't exist
+- `(refs/channel-exists)` - Referenced channel in sends/receives `to`/`from`, routes, messages, or message channels doesn't exist
+- `(refs/container-exists)` - Referenced container in `writesTo`/`readsFrom` or flow steps doesn't exist
+- `(refs/orphan-messages)` - Event/command/query has no producer and no consumer
+
+### Best Practice Rules
+
+- `(best-practices/summary-required)` - Summary field is missing
+- `(best-practices/owner-required)` - At least one owner is required
+
+### Parse Errors
+
+- `(@eventcatalog/parse-error)` - YAML/frontmatter parsing error
+
+## Warnings Support
+
+The linter distinguishes between errors (critical issues) and warnings (suggestions for improvement):
+
+- **Errors**: Critical issues that must be fixed
+- **Warnings**: Suggestions for better documentation
+
+Use `--fail-on-warning` to treat warnings as errors in CI/CD pipelines:
+
+```bash
+# Exit with error code if warnings are found
+eventcatalog-linter --fail-on-warning
+```
+
+## Common Validation Examples
+
+### Valid Frontmatter Examples
+
+#### Service
+
+```yaml
+---
+id: user-service
+name: User Service
+version: 2.1.0
+summary: Manages user accounts and authentication
+owners:
+  - platform-team
+  - john-doe
+sends:
+  - id: user-created
+    version: 1.0.0
+  - id: user-updated
+receives:
+  - id: create-user
+  - id: update-user
+entities:
+  - id: user
+repository:
+  language: TypeScript
+  url: https://github.com/company/user-service
+---
+```
+
+#### Event
+
+```yaml
+---
+id: user-created
+name: User Created
+version: 1.0.0
+summary: Triggered when a new user account is created
+owners:
+  - platform-team
+sidebar:
+  badge: POST
+  label: User Events
+draft: false
+deprecated: false
+---
+```
+
+#### Agent
+
+<AddedIn version="1.2.0" />
+
+```yaml
+---
+id: refund-agent
+name: Refund Agent
+version: 1.0.0
+summary: Coordinates customer refund decisions
+owners:
+  - platform-team
+receives:
+  - id: refund-requested
+    from:
+      - id: refunds
+sends:
+  - id: refund-approved
+    to:
+      - id: public-events/orders
+readsFrom:
+  - id: orders-db
+model:
+  provider: OpenAI
+  name: gpt-4.1-mini
+tools:
+  - name: Payment lookup
+    type: mcp
+---
+```
+
+#### Container
+
+<AddedIn version="1.2.0" />
+
+```yaml
+---
+id: orders-db
+name: Orders DB
+version: 1.0.0
+summary: Stores order records
+container_type: database
+technology: PostgreSQL
+classification: internal
+access_mode: readWrite
+authoritative: true
+---
+```
+
+#### Data product
+
+<AddedIn version="1.2.0" />
+
+```yaml
+---
+id: refund-analytics
+name: Refund Analytics
+version: 1.0.0
+summary: Curated refund metrics for finance teams
+inputs:
+  - id: refund-approved
+  - id: orders-db
+outputs:
+  - id: public-events/orders
+    contract:
+      path: contracts/refund-analytics.json
+      name: Refund Analytics Contract
+---
+```
+
+#### ADR
+
+<AddedIn version="1.2.0" />
+
+```yaml
+---
+id: adr-001
+name: Use event-driven refunds
+version: 1.0.0
+summary: Records the decision to coordinate refunds through events
+status: accepted
+date: 2026-05-26
+decisionMakers:
+  - id: platform-team
+    collection: teams
+appliesTo:
+  - type: service
+    id: order-service
+  - type: data-product
+    id: refund-analytics
+related:
+  - id: adr-000
+---
+```
+
+#### Diagram
+
+<AddedIn version="1.2.0" />
+
+```yaml
+---
+id: refund-flow
+name: Refund Flow Diagram
+version: 1.0.0
+summary: Shows the refund workflow across services and agents
+owners:
+  - platform-team
+---
+```
+
+### Common Validation Errors
+
+#### ❌ Missing Required Fields
+
+```yaml
+---
+# Missing 'id' field
+name: User Service
+version: 1.0.0
+---
+```
+
+#### ❌ Invalid Semantic Version
+
+```yaml
+---
+id: user-service
+name: User Service
+version: v1.0 # Should be 1.0.0
+---
+```
+
+#### ❌ Invalid Reference
+
+```yaml
+---
+id: sales-domain
+name: Sales Domain
+version: 1.0.0
+services:
+  - id: non-existent-service # Service doesn't exist
+---
+```
+
+## Best Practices
+
+1. **Start with Configuration**: Create a `.eventcatalogrc.js` file to customize rules for your team's workflow
+2. **Run in CI/CD**: Integrate the linter into your CI/CD pipeline to catch issues early
+3. **Use `--fail-on-warning`**: Consider treating warnings as errors in production environments
+4. **Regular Validation**: Run the linter regularly as part of your development workflow
+5. **Fix Issues Promptly**: Address validation errors immediately to maintain documentation quality
+6. **Version Consistency**: Use consistent version patterns across your EventCatalog resources
+7. **Team Overrides**: Use file pattern overrides for different validation requirements across teams
+8. **Ignore Patterns**: Use ignore patterns for draft or experimental content that shouldn't be validated yet
+
+## Issues?
+
+If you have any issues or feedback, please let us know by opening an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or joining our [Discord server](https://eventcatalog.dev/discord).
\ No newline at end of file
diff --git a/packages/core/docs/development/governance/_category_.json b/packages/core/docs/development/governance/_category_.json
new file mode 100644
index 000000000..17602dbbf
--- /dev/null
+++ b/packages/core/docs/development/governance/_category_.json
@@ -0,0 +1,7 @@
+{
+  "label": "Governance Patterns",
+  "position": 9,
+  "className": "hidden",
+  "collapsible": true,
+  "collapsed": false
+}
diff --git a/packages/core/docs/development/governance/architecture-change-detection/01-introduction.md b/packages/core/docs/development/governance/architecture-change-detection/01-introduction.md
new file mode 100644
index 000000000..f038e2c74
--- /dev/null
+++ b/packages/core/docs/development/governance/architecture-change-detection/01-introduction.md
@@ -0,0 +1,62 @@
+---
+sidebar_position: 1
+sidebar_label: Introduction
+title: Architecture Change Detection
+description: Know when your event-driven architecture changes. Get notified when services start or stop producing and consuming messages.
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+Services get added. Consumers change. Producers disappear. In event-driven systems, these relationship changes often go unnoticed until something breaks downstream.
+
+**Architecture Change Detection** compares your catalog across branches and tells you exactly what changed: which services started consuming a message, which stopped producing one, and who is affected.
+
+You can configure webhooks to send notifications to tools like Slack or PagerDuty when changes are detected, including relationship changes, deprecations, and schema updates. Rules can also be configured to block CI/CD pipelines entirely using the `fail` action.
+
+:::info Scale plan required
+Architecture Change Detection requires an [EventCatalog Scale plan](https://eventcatalog.dev/pricing).
+:::
+
+## How it works
+
+1. Define rules in `governance.yaml` at the root of your catalog
+2. Each rule specifies **triggers** (what kind of change to detect), **resources** (which services or messages to watch), and **actions** (how to get notified)
+3. Run `eventcatalog governance check` to compare your catalog against a base branch
+4. Matched changes print to the console, fire webhook notifications, and optionally exit with a non-zero code to block merges
+
+```mermaid
+flowchart LR
+    A[governance.yaml] --> B[eventcatalog governance check]
+    B --> C{Compare branches}
+    C --> D[Detect changes]
+    D --> E[Console output]
+    D --> F[Webhook notifications]
+    D --> G[Fail action — exit code 1]
+```
+
+## Quick example
+
+```yaml title="governance.yaml"
+rules:
+  - name: notify-consumer-changes
+    when:
+      - consumer_added
+      - consumer_removed
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+```
+
+This rule detects whenever any service starts or stops consuming any message, and sends a notification to Slack.
+
+## Notifications when you want them
+
+Using the [`status` field](/docs/development/governance/architecture-change-detection/ci-cd#include-a-status-label) you can choose to detect changes that are proposed vs approved. This can be useful when you want to detect changes that are proposed vs approved in your architecture.
+
+
+
diff --git a/packages/core/docs/development/governance/architecture-change-detection/02-configuration.md b/packages/core/docs/development/governance/architecture-change-detection/02-configuration.md
new file mode 100644
index 000000000..1531183e1
--- /dev/null
+++ b/packages/core/docs/development/governance/architecture-change-detection/02-configuration.md
@@ -0,0 +1,134 @@
+---
+sidebar_position: 2
+sidebar_label: Configuration
+title: Configuration
+description: Configure governance rules with triggers, resource filters, and actions
+---
+
+## Create a config file
+
+Add a `governance.yaml` file to the root of your catalog directory. Each rule has a name, a list of triggers, a resource filter, and one or more actions.
+
+```yaml title="governance.yaml"
+rules:
+  # Name of your rule
+  - name: notify-consumer-changes
+    # List of triggers
+    when:
+      - consumer_added
+      - consumer_removed
+    # Configure which resources to watch
+    # * is everything
+    resources:
+      - "*"
+    # List of actions to perform
+    actions:
+      # Print to the console
+      - type: console
+      # Send a webhook to a Slack or PagerDuty webhook
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+        headers:
+          Authorization: Bearer $API_TOKEN
+```
+
+## Triggers
+
+The `when` field lists the events that activate a rule. Relationship triggers compare the target state against the base branch. The `message_deprecated` and `schema_changed` triggers inspect the target branch directly.
+
+| Trigger | Description |
+|---|---|
+| `consumer_added` | A service starts receiving a message |
+| `consumer_removed` | A service stops receiving a message |
+| `producer_added` | A service starts sending a message |
+| `producer_removed` | A service stops sending a message |
+| `message_deprecated` | A producing service marks a message as deprecated |
+| `schema_changed` | A message schema file is added, modified, or replaced |
+
+A single rule can listen to multiple triggers:
+
+```yaml
+when:
+  - consumer_added
+  - consumer_removed
+```
+
+## Resource filters
+
+The `resources` field controls which changes are checked against the rule. Each entry uses a prefix to specify what to match.
+
+| Prefix | Example | Matches |
+|---|---|---|
+| `"*"` | `"*"` | All changes across the catalog |
+| `"message:<id>"` | `"message:OrderCreated"` | Changes involving a specific message |
+| `"service:<id>"` | `"service:NotificationService"` | Changes where the named service is the consumer or producer |
+| `"produces:<service>"` | `"produces:OrdersService"` | Changes involving any message that the named service sends |
+| `"consumes:<service>"` | `"consumes:PaymentService"` | Changes involving any message that the named service receives. For `message_deprecated` and `schema_changed`, matches messages consumed by the named service |
+
+You can combine multiple filters in one rule. A change matches if it matches **any** entry:
+
+```yaml
+resources:
+  - message:OrderCreated
+  - message:OrderConfirmed
+  - service:NotificationService
+```
+
+## Actions
+
+Each rule can trigger one or more actions when its conditions are met.
+
+### Console
+
+Prints a summary of matched changes to the terminal. No additional configuration required.
+
+```yaml
+actions:
+  - type: console
+```
+
+### Webhook
+
+Sends a POST request in [CloudEvents 1.0](https://cloudevents.io/) format to the specified URL. Custom headers are supported.
+
+_You can use [Webhook Sites](https://webhook.site) to test your webhook URLs. Don't share any sensitive information in the payload._
+
+```yaml
+actions:
+  - type: webhook
+    url: $SLACK_WEBHOOK_URL
+    headers:
+      Authorization: Bearer $API_TOKEN
+```
+
+See [Webhook Payload](/docs/development/governance/architecture-change-detection/webhooks) for the full payload format.
+
+### Fail
+
+Exits the CLI with code `1`, failing the CI/CD step and blocking the pipeline. An optional `message` field provides a human-readable reason shown in the terminal output.
+
+```yaml
+actions:
+  - type: fail
+    message: "Schema change impacts payment services. Requires sign-off from @payments-team."
+```
+
+The `message` field supports `$ENV_VAR` interpolation. A rule can include multiple `fail` actions; all messages are collected and printed together before the process exits.
+
+If no triggered rule has a `fail` action, the CLI exits with code `0` regardless of how many rules fired. This means adding `type: fail` to specific rules is a non-breaking, opt-in change.
+
+See [Pipeline gates](/docs/development/governance/architecture-change-detection/pipeline-gates) for full examples of blocking CI/CD with governance rules.
+
+## Environment variables
+
+Webhook URLs and header values can reference environment variables using the `$VAR_NAME` syntax. The CLI loads your catalog's `.env` file automatically, so you can keep secrets out of `governance.yaml`.
+
+```yaml
+actions:
+  - type: webhook
+    url: $SLACK_WEBHOOK_URL
+    headers:
+      Authorization: Bearer $API_TOKEN
+```
+
+If a referenced variable is not set at runtime, the command exits with an error.
diff --git a/packages/core/docs/development/governance/architecture-change-detection/03-recipes.md b/packages/core/docs/development/governance/architecture-change-detection/03-recipes.md
new file mode 100644
index 000000000..2ac05d8c7
--- /dev/null
+++ b/packages/core/docs/development/governance/architecture-change-detection/03-recipes.md
@@ -0,0 +1,309 @@
+---
+sidebar_position: 3
+sidebar_label: Recipes
+title: Recipes
+description: Common governance configurations you can copy and adapt
+---
+
+## Alert when anyone consumes a message your service produces
+
+Use the `produces:` prefix to scope a rule to all messages sent by a given service. This is the recommended pattern for service owners who want visibility into downstream adoption.
+
+```yaml title="governance.yaml"
+rules:
+  - name: orders-service-consumer-changes
+    when:
+      - consumer_added
+      - consumer_removed
+    resources:
+      - produces:OrdersService
+    actions:
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+        headers:
+          Authorization: Bearer $API_TOKEN
+```
+
+## Alert when a producer stops producing a message your service depends on
+
+Use `consumes:` to watch all messages a service receives, then trigger on `producer_removed`. This catches upstream breaking changes before they affect your service.
+
+```yaml title="governance.yaml"
+rules:
+  - name: payment-service-upstream-removed
+    when:
+      - producer_removed
+    resources:
+      - consumes:PaymentService
+    actions:
+      - type: console
+      - type: webhook
+        url: $PAGERDUTY_WEBHOOK_URL
+```
+
+A collection of examples of common governance configurations you can copy and adapt.
+
+## Alert when a message gets a new consumer
+
+Useful when you own a message and want to know when other teams start depending on it.
+
+```yaml title="governance.yaml"
+rules:
+  - name: new-consumer-for-payment-processed
+    when:
+      - consumer_added
+    resources:
+      - message:PaymentProcessed
+    actions:
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+```
+
+## Alert when a message gets a new producer
+
+Useful for messages that should only ever have one authoritative producer.
+
+```yaml title="governance.yaml"
+rules:
+  - name: new-producer-for-order-created
+    when:
+      - producer_added
+    resources:
+      - message:OrderCreated
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+```
+
+
+
+## Track all changes across the catalog
+
+The `"*"` wildcard matches every consumer and producer change. Useful for audit logs or a central ops channel.
+
+```yaml title="governance.yaml"
+rules:
+  - name: catalog-wide-relationship-changes
+    when:
+      - consumer_added
+      - consumer_removed
+      - producer_added
+      - producer_removed
+    resources:
+      - "*"
+    actions:
+      - type: webhook
+        url: $AUDIT_WEBHOOK_URL
+```
+
+## Monitor all changes for a specific service
+
+Use the `service:` prefix to watch any consuming or producing change that involves a named service, regardless of which message is affected.
+
+```yaml title="governance.yaml"
+rules:
+  - name: notification-service-changes
+    when:
+      - consumer_added
+      - consumer_removed
+      - producer_added
+      - producer_removed
+    resources:
+      - service:NotificationService
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+```
+
+## Get notified when a message your service consumes is deprecated
+
+Use `consumes:` with `message_deprecated` to alert your team when an upstream producer deprecates a message you depend on. This is the most useful deprecation pattern for consumer teams.
+
+```yaml title="governance.yaml"
+rules:
+  - name: alert-deprecated-messages
+    when:
+      - message_deprecated
+    resources:
+      - "consumes:InventoryService"
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+```
+
+## Watch a specific message for deprecation
+
+Use `message:` to monitor a single message across any of its producers.
+
+```yaml title="governance.yaml"
+rules:
+  - name: watch-order-placed-deprecation
+    when:
+      - message_deprecated
+    resources:
+      - "message:OrderPlaced"
+    actions:
+      - type: webhook
+        url: $TEAM_WEBHOOK_URL
+```
+
+## Track all deprecations across the catalog
+
+The `"*"` wildcard catches every deprecation in the catalog. Useful for a central ops channel or audit log.
+
+```yaml title="governance.yaml"
+rules:
+  - name: catalog-wide-deprecation-alerts
+    when:
+      - message_deprecated
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: webhook
+        url: $AUDIT_WEBHOOK_URL
+```
+
+## Alert when a message schema changes
+
+Use `schema_changed` to detect when the schema file for any message is added, modified, or replaced. This is useful for catching breaking changes before they propagate to consumers.
+
+```yaml title="governance.yaml"
+rules:
+  - name: schema-change-alerts
+    when:
+      - schema_changed
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_WEBHOOK_URL
+```
+
+## Alert when a schema changes for messages your service consumes
+
+Use `consumes:` with `schema_changed` to scope alerts to only the messages your service depends on.
+
+```yaml title="governance.yaml"
+rules:
+  - name: payment-service-schema-changes
+    when:
+      - schema_changed
+    resources:
+      - consumes:PaymentService
+    actions:
+      - type: webhook
+        url: $PAGERDUTY_WEBHOOK_URL
+```
+
+## Watch a specific message for schema changes
+
+Use `message:` to monitor schema changes for a single message across any of its producers.
+
+```yaml title="governance.yaml"
+rules:
+  - name: order-created-schema-watch
+    when:
+      - schema_changed
+    resources:
+      - message:OrderCreated
+    actions:
+      - type: console
+      - type: webhook
+        url: $TEAM_WEBHOOK_URL
+```
+
+## Block CI when a payment-critical schema changes
+
+Combine `type: fail` with `schema_changed` and service-scoped resource filters to require sign-off before a schema change can merge.
+
+```yaml title="governance.yaml"
+rules:
+  - name: payment-schema-guard
+    when:
+      - schema_changed
+    resources:
+      - consumes:PaymentService
+      - consumes:BillingService
+      - message:PaymentProcessed
+      - message:OrderCreated
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_ALERTS_WEBHOOK
+        headers:
+          Authorization: Bearer $SLACK_TOKEN
+      - type: fail
+        message: "Schema change impacts payment services. Requires sign-off from @payments-team."
+```
+
+## Block CI when a consumer is silently removed
+
+Use `consumer_removed` with `type: fail` to ensure consumer removals are never merged without a migration ticket.
+
+```yaml title="governance.yaml"
+rules:
+  - name: consumer-removal-guard
+    when:
+      - consumer_removed
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: fail
+        message: "Removing a consumer is a breaking change. Open a migration ticket first."
+```
+
+## Block CI on deprecation without a replacement
+
+Pair `message_deprecated` with `type: fail` to enforce that deprecations are reviewed before merging.
+
+```yaml title="governance.yaml"
+rules:
+  - name: deprecation-review-gate
+    when:
+      - message_deprecated
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: fail
+        message: "Deprecations require a migration guide before merging. See CONTRIBUTING.md."
+```
+
+## Notify on some changes, block on others
+
+Rules without `type: fail` always exit `0`, so you can mix notification-only rules with blocking rules in the same file.
+
+```yaml title="governance.yaml"
+rules:
+  # Blocks CI — schema changes to payment-critical messages
+  - name: payment-schema-guard
+    when:
+      - schema_changed
+    resources:
+      - consumes:PaymentService
+    actions:
+      - type: console
+      - type: fail
+        message: "Schema change impacts payment services. Requires sign-off from @payments-team."
+
+  # Notifies only — new consumers are welcome but the team wants visibility
+  - name: notify-new-consumers
+    when:
+      - consumer_added
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_NOTIFICATIONS_WEBHOOK
+```
+
+## Future changes
+
+We are working on adding new change detection features to EventCatalog, if you have any ideas or feedback please let us know on [Discord](https://eventcatalog.dev/discord) or raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).
\ No newline at end of file
diff --git a/packages/core/docs/development/governance/architecture-change-detection/04-webhooks.md b/packages/core/docs/development/governance/architecture-change-detection/04-webhooks.md
new file mode 100644
index 000000000..d4e07c7e4
--- /dev/null
+++ b/packages/core/docs/development/governance/architecture-change-detection/04-webhooks.md
@@ -0,0 +1,187 @@
+---
+sidebar_position: 4
+sidebar_label: Webhook Payload
+title: Webhook Payload
+description: CloudEvents 1.0 payload format sent by governance webhook actions
+---
+
+## Payload format
+
+Webhook actions send a POST request in [CloudEvents 1.0](https://cloudevents.io/) format. Each matched change produces a separate request.
+
+```json
+{
+  "specversion": "1.0",
+  "type": "eventcatalog.governance.consumer_added",
+  "source": "eventcatalog/governance",
+  "id": "uuid",
+  "time": "2026-03-04T12:00:00.000Z",
+  "datacontenttype": "application/json",
+  "data": {
+    "schemaVersion": 1,
+    "summary": "NotificationService is now consuming the event OrderConfirmed",
+    "consumer": {
+      "id": "NotificationService",
+      "version": "0.0.2"
+    },
+    "message": {
+      "id": "OrderConfirmed",
+      "version": "0.0.1",
+      "type": "event"
+    }
+  }
+}
+```
+
+## CloudEvents envelope
+
+| Field | Value |
+|---|---|
+| `specversion` | Always `"1.0"` |
+| `type` | `eventcatalog.governance.<trigger>`, one of `consumer_added`, `consumer_removed`, `producer_added`, `producer_removed`, `message_deprecated`, `schema_changed` |
+| `source` | `eventcatalog/governance` |
+| `id` | Unique UUID per request |
+| `time` | ISO 8601 timestamp |
+| `datacontenttype` | `application/json` |
+
+## Data object
+
+| Field | Description |
+|---|---|
+| `schemaVersion` | Always `1` (reserved for future format changes) |
+| `status` | Only present when `--status` is passed to the CLI |
+| `summary` | Human-readable description of the change |
+| `consumer` or `producer` | The service involved. `consumer` for consumer triggers, `producer` for producer and `message_deprecated` triggers |
+| `message` | The message involved, including its `type` (`event`, `command`, or `query`) |
+| `schema` | Only present for `schema_changed`. Contains `beforeHash`, `afterHash`, `beforePath`, and `afterPath` |
+| `consumers` | Only present for `schema_changed`. Array of services that consume the changed message |
+| `producers` | Only present for `schema_changed`. Array of services that produce the changed message |
+| `refs` | Only present for `schema_changed`. Contains `base` and `target` branch labels |
+
+## Producer triggers
+
+For `producer_added` and `producer_removed`, the `consumer` field is replaced with `producer`:
+
+```json
+{
+  "data": {
+    "schemaVersion": 1,
+    "summary": "OrdersService is now producing the event OrderCreated",
+    "producer": {
+      "id": "OrdersService",
+      "version": "1.0.0"
+    },
+    "message": {
+      "id": "OrderCreated",
+      "version": "1.0.0",
+      "type": "event"
+    }
+  }
+}
+```
+
+## Deprecation trigger
+
+For `message_deprecated`, the payload identifies the producing service and the deprecated message. One webhook fires per producing service, so if a message has multiple producers, each producer sends a separate request.
+
+```json
+{
+  "specversion": "1.0",
+  "type": "eventcatalog.governance.message_deprecated",
+  "source": "eventcatalog/governance",
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "time": "2026-03-05T14:30:00.000Z",
+  "datacontenttype": "application/json",
+  "data": {
+    "schemaVersion": 1,
+    "summary": "OrderCreated (event) has been deprecated by OrdersService",
+    "producer": {
+      "id": "OrdersService",
+      "version": "2.0.0",
+      "owners": ["team-orders"]
+    },
+    "message": {
+      "id": "OrderCreated",
+      "version": "1.0.0",
+      "type": "event"
+    }
+  }
+}
+```
+
+The `owners` field is only present when the producing service has owners defined. The trigger fires only for newly deprecated messages: existing deprecations and un-deprecations do not fire.
+
+## Schema changed trigger
+
+For `schema_changed`, the payload includes a `schema` object with hashes and paths for the before and after versions, plus arrays of the affected consumer and producer services. One webhook fires per changed message.
+
+```json
+{
+  "specversion": "1.0",
+  "type": "eventcatalog.governance.schema_changed",
+  "source": "eventcatalog/governance",
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "time": "2026-03-05T14:30:00.000Z",
+  "datacontenttype": "application/json",
+  "data": {
+    "schemaVersion": 1,
+    "summary": "Schema changed for event OrderCreated",
+    "message": {
+      "id": "OrderCreated",
+      "version": "1.0.0",
+      "type": "event"
+    },
+    "schema": {
+      "beforeHash": "abc123",
+      "afterHash": "def456",
+      "beforePath": "schemas/order-created.v1.json",
+      "afterPath": "schemas/order-created.v2.json"
+    },
+    "refs": {
+      "base": "main",
+      "target": "feature/update-schema"
+    },
+    "producers": [
+      { "id": "OrdersService", "version": "1.0.0", "owners": ["team-orders"] }
+    ],
+    "consumers": [
+      { "id": "PaymentService", "version": "1.0.0", "owners": ["team-payments"] }
+    ]
+  }
+}
+```
+
+The `schema.beforeHash` and `schema.afterHash` are SHA-256 hashes of the schema file content. Either side can be `null` when a schema is first added or removed. The `owners` field on each service is only present when owners are defined.
+
+## Status field
+
+When you pass `--status` to the CLI, the value is included in the payload. This is useful for distinguishing between stages in a pull request lifecycle.
+
+```bash
+eventcatalog governance check --status proposed
+```
+
+```json
+{
+  "data": {
+    "schemaVersion": 1,
+    "status": "proposed",
+    "summary": "NotificationService is now consuming the event OrderConfirmed",
+    "consumer": { "id": "NotificationService", "version": "0.0.2" },
+    "message": { "id": "OrderConfirmed", "version": "0.0.1", "type": "event" }
+  }
+}
+```
+
+## Custom headers
+
+Headers support environment variable substitution using `$VAR_NAME` syntax.
+
+```yaml
+actions:
+  - type: webhook
+    url: $SLACK_WEBHOOK_URL
+    headers:
+      Authorization: Bearer $API_TOKEN
+      X-Custom-Header: my-value
+```
diff --git a/packages/core/docs/development/governance/architecture-change-detection/05-ci-cd.md b/packages/core/docs/development/governance/architecture-change-detection/05-ci-cd.md
new file mode 100644
index 000000000..e19800714
--- /dev/null
+++ b/packages/core/docs/development/governance/architecture-change-detection/05-ci-cd.md
@@ -0,0 +1,121 @@
+---
+sidebar_position: 5
+sidebar_label: CLI & CI/CD
+title: CLI & CI/CD
+description: Run governance checks locally and in your CI/CD pipeline
+---
+
+## Run the check
+
+Run the check from inside your catalog directory. By default it compares the current working directory against the `main` branch.
+
+```bash
+eventcatalog governance check
+```
+
+#### Testing locally
+
+To test locally, make changes to your catalog locally and then run the governance check command.
+
+```sh
+eventcatalog governance check --target main
+```
+
+This will compare the current working directory against the specified branch.
+
+## CLI options
+
+| Option | Description | Default |
+|---|---|---|
+| `--base <branch>` | Base branch to compare against | `main` |
+| `--target <branch>` | Target branch to compare (instead of working directory) | working directory |
+| `--format json` | Output results as JSON | text |
+| `--status <label>` | Status label included in webhook payloads (e.g. `proposed`, `approved`) | none |
+
+### Compare two branches
+
+```bash
+eventcatalog governance check --base main --target feature/new-consumers
+```
+
+### Output JSON
+
+```bash
+eventcatalog governance check --format json
+```
+
+### Include a status label
+
+The `--status` flag adds a `status` field to webhook payloads, useful when running governance checks at different stages of a pull request lifecycle.
+
+```bash
+eventcatalog governance check --status proposed
+```
+
+## GitHub Actions
+
+### Proposed changes
+
+When you want to notify your teams of incoming changes (not merged yet), you can use the `--status proposed` flag to mark the changes as proposed.
+
+This example workflow will notify your teams of incoming changes (not merged yet). The status `proposed` will be included in the webhook payload.
+
+```yaml title=".github/workflows/governance.yaml"
+name: EventCatalog Governance
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.head_ref }}
+      # Fetch the base branch (e.g. main or whatever you want to compare against)
+      - run: git fetch origin main
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: |
+          npx @eventcatalog/cli governance check \
+            --base main \
+            --target ${{ github.head_ref }} \
+            --status proposed
+        env:
+          EVENTCATALOG_SCALE_LICENSE_KEY: ${{ secrets.EVENTCATALOG_SCALE_LICENSE_KEY }}
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+```
+
+### Approved changes
+
+When a pull request is merged to the base branch, you can run the check again with `--status approved` to notify teams that the change is confirmed.
+
+This example workflow will notify your teams that the change is confirmed. The status `approved` will be included in the webhook payload.
+
+```yaml title=".github/workflows/governance.yaml"
+name: EventCatalog Governance
+on: merge
+
+jobs:
+  governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.base_ref }} 
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: |
+          npx @eventcatalog/cli governance check \
+            --base main \
+            --target ${{ github.base_ref }} \
+            --status approved
+        env:
+          EVENTCATALOG_SCALE_LICENSE_KEY: ${{ secrets.EVENTCATALOG_SCALE_LICENSE_KEY }}
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+```
\ No newline at end of file
diff --git a/packages/core/docs/development/governance/architecture-change-detection/06-pipeline-gates.md b/packages/core/docs/development/governance/architecture-change-detection/06-pipeline-gates.md
new file mode 100644
index 000000000..7dc6828f3
--- /dev/null
+++ b/packages/core/docs/development/governance/architecture-change-detection/06-pipeline-gates.md
@@ -0,0 +1,162 @@
+---
+sidebar_position: 6
+sidebar_label: Pipeline gates
+title: Pipeline gates
+description: Block merges automatically when governance rules trigger
+---
+
+Use the `fail` action to exit the CLI with code `1`, turning governance checks into hard gates that prevent merges when architectural rules are violated. Without `fail`, triggered rules only notify -- the CLI always exits `0`.
+
+:::info Scale plan required
+Architecture Change Detection requires an [EventCatalog Scale plan](https://eventcatalog.dev/pricing).
+:::
+
+## Add the fail action
+
+Add `type: fail` to any rule that should block the pipeline. The `message` field is optional but recommended -- it explains to the developer exactly what needs to happen before the PR can merge.
+
+```yaml title="governance.yaml"
+rules:
+  - name: payment-schema-guard
+    when:
+      - schema_changed
+    resources:
+      - consumes:PaymentService
+      - message:PaymentProcessed
+    actions:
+      - type: console
+      - type: fail
+        message: "Schema change impacts payment services. Requires sign-off from @payments-team."
+```
+
+When this rule fires, the CLI prints the failure reason and exits with code `1`:
+
+```
+Governance check: comparing feat/api-change against main
+
+Governance:
+
+  Rule "payment-schema-guard" triggered (schema_changed):
+    ! Schema changed for PaymentProcessed (event) — consumers: PaymentService
+
+1 rule triggered.
+
+FAILED: payment-schema-guard
+  Schema change impacts payment services. Requires sign-off from @payments-team.
+```
+
+## Combine with webhooks
+
+Pairing `type: fail` with `type: webhook` lets you block the pipeline and notify the right team at the same time. Both actions run before the process exits.
+
+```yaml title="governance.yaml"
+rules:
+  - name: payment-schema-guard
+    when:
+      - schema_changed
+    resources:
+      - consumes:PaymentService
+      - consumes:BillingService
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_ALERTS_WEBHOOK
+        headers:
+          Authorization: Bearer $SLACK_TOKEN
+      - type: fail
+        message: "Schema change impacts payment services. Requires sign-off from @payments-team."
+```
+
+## Use environment variables in messages
+
+The `message` field supports `$ENV_VAR` interpolation, the same as webhook URLs and headers. This lets you include dynamic content such as a team handle or ticket URL stored in CI secrets.
+
+```yaml
+actions:
+  - type: fail
+    message: "Breaking change detected. Contact $PAYMENTS_TEAM_HANDLE for approval."
+```
+
+## Mix blocking and non-blocking rules
+
+Rules without a `fail` action always exit `0`. You can freely mix notification-only rules with blocking rules in the same file. Only rules that include `type: fail` and actually trigger will cause a non-zero exit.
+
+```yaml title="governance.yaml"
+rules:
+  # Blocks CI
+  - name: consumer-removal-guard
+    when:
+      - consumer_removed
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: fail
+        message: "Removing a consumer is a breaking change. Open a migration ticket first."
+
+  # Notifies only, never blocks
+  - name: notify-new-consumers
+    when:
+      - consumer_added
+    resources:
+      - "*"
+    actions:
+      - type: console
+      - type: webhook
+        url: $SLACK_NOTIFICATIONS_WEBHOOK
+```
+
+## Set up GitHub Actions
+
+No special flags are needed. The step fails automatically when the CLI exits with code `1`.
+
+```yaml title=".github/workflows/governance.yaml"
+name: EventCatalog Governance
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.head_ref }}
+      - run: git fetch origin main
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: |
+          npx @eventcatalog/cli governance check \
+            --base main \
+            --target ${{ github.head_ref }}
+        env:
+          EVENTCATALOG_SCALE_LICENSE_KEY: ${{ secrets.EVENTCATALOG_SCALE_LICENSE_KEY }}
+          SLACK_ALERTS_WEBHOOK: ${{ secrets.SLACK_ALERTS_WEBHOOK }}
+          SLACK_TOKEN: ${{ secrets.SLACK_TOKEN }}
+```
+
+If a triggered rule has `type: fail`, the `Run governance check` step is marked as failed and the PR cannot be merged until the check passes.
+
+## Set up GitLab CI
+
+```yaml title=".gitlab-ci.yml"
+governance:
+  stage: validate
+  script:
+    - npx @eventcatalog/cli governance check --base origin/main
+  variables:
+    EVENTCATALOG_SCALE_LICENSE_KEY: $EVENTCATALOG_SCALE_LICENSE_KEY
+    SLACK_ALERTS_WEBHOOK: $SLACK_ALERTS_WEBHOOK
+```
+
+## Common gating patterns
+
+| Scenario | Trigger | Resource filter |
+|---|---|---|
+| Block schema changes to payment messages | `schema_changed` | `consumes:PaymentService` or `message:PaymentProcessed` |
+| Block silent consumer removal | `consumer_removed` | `"*"` |
+| Block unreviewed deprecations | `message_deprecated` | `"*"` |
+| Block producer removal for critical messages | `producer_removed` | `message:OrderCreated` |
diff --git a/packages/core/docs/development/governance/architecture-change-detection/_category_.json b/packages/core/docs/development/governance/architecture-change-detection/_category_.json
new file mode 100644
index 000000000..4b9126b26
--- /dev/null
+++ b/packages/core/docs/development/governance/architecture-change-detection/_category_.json
@@ -0,0 +1,6 @@
+{
+  "label": "Architecture Change Detection",
+  "position": 1,
+  "collapsible": true,
+  "collapsed": true
+}
diff --git a/packages/core/docs/development/guides/98-versioning-resources.md b/packages/core/docs/development/guides/98-versioning-resources.md
new file mode 100644
index 000000000..b8eeccab5
--- /dev/null
+++ b/packages/core/docs/development/guides/98-versioning-resources.md
@@ -0,0 +1,192 @@
+---
+sidebar_position: 98
+keywords:
+- versioning
+- resources
+- EventCatalog
+sidebar_label: Versioning resources
+title: Versioning resources
+description: Learn how versioning works for EventCatalog resources.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+EventCatalog resources can be versioned when you want to preserve how a resource looked at a point in time.
+
+Use versioning when a resource changes in a way that people may need to understand later, such as a service contract change, a message payload change, a domain boundary change, or a new major version of a system capability.
+
+## How versioning works
+
+The latest version of a resource lives in the normal resource folder.
+
+Older versions live inside a `versioned` folder under that resource. Each version has its own folder and its own `index.mdx` file.
+
+For example, a versioned service looks like this:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx', highlight: true },
+            {
+              name: 'versioned',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '1.0.0',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The root `index.mdx` is the current version. The file in `versioned/1.0.0/index.mdx` is the historical version.
+
+## Create a new version
+
+To create a new version:
+
+1. Copy the current resource into a new folder under `versioned/{version}`.
+2. Keep the copied file at the old version number.
+3. Update the root resource to the new version number.
+4. Update the root resource content to describe the latest state.
+
+For example, before changing `Orders` from `1.0.0` to `2.0.0`, copy the current file into `versioned/1.0.0/index.mdx`.
+
+```md title="/services/Orders/versioned/1.0.0/index.mdx"
+---
+id: Orders
+name: Orders
+version: 1.0.0
+summary: Handles order placement and order history.
+---
+
+## Overview
+
+This is the original Orders service documentation.
+```
+
+Then update the root file:
+
+```md title="/services/Orders/index.mdx"
+---
+id: Orders
+name: Orders
+version: 2.0.0
+summary: Handles order placement, order history, and order amendments.
+---
+
+## Overview
+
+This is the latest Orders service documentation.
+```
+
+## Versioned URLs
+
+EventCatalog creates versioned pages for resources that have versions.
+
+For example:
+
+| Resource | URL |
+|----------|-----|
+| Latest `Orders` service | `/docs/services/Orders` |
+| `Orders` service version `1.0.0` | `/docs/services/Orders/1.0.0` |
+
+This lets users compare the current resource with previous versions when they need historical context.
+
+## Referencing versions
+
+When one resource references another resource, you can include a `version` field when you want to point to a specific version.
+
+```md title="/services/Payments/index.mdx"
+---
+id: Payments
+name: Payments
+version: 1.0.0
+
+receives:
+  - id: OrderPlaced
+    version: 1.0.0
+---
+```
+
+Use a specific version when the relationship depends on that version of the resource.
+
+Leave the version out when the relationship should point to the latest version.
+
+```md title="/services/Payments/index.mdx"
+---
+id: Payments
+name: Payments
+version: 1.0.0
+
+receives:
+  - id: OrderPlaced
+---
+```
+
+## What can be versioned?
+
+You can version the resources you document in EventCatalog, including:
+
+- Domains
+- Systems
+- Services
+- Messages
+- Schemas and specifications
+- Data stores
+- Data products
+- Entities
+- Flows
+- Agents
+- Architecture decision records
+
+The folder location changes by resource type, but the pattern is the same: keep the latest resource in the root folder and store older versions under `versioned/{version}`.
+
+## Version numbers
+
+EventCatalog does not force a specific versioning strategy. Most teams use semantic versioning:
+
+| Version change | Use when |
+|----------------|----------|
+| Patch | Fixing documentation, examples, or non-behavioral details |
+| Minor | Adding fields, endpoints, resources, or capabilities in a backwards-compatible way |
+| Major | Removing or changing behavior, contracts, fields, routes, or ownership in a breaking way |
+
+The important part is consistency. Pick a convention your team understands and apply it across the catalog.
+
+## Versioning and changelogs
+
+Versioning preserves the old state of a resource. Changelogs explain why the resource changed.
+
+Use both when the change needs context. For example, a service can have version `2.0.0` and a changelog entry explaining that the service started publishing a new event or removed an old endpoint.
+
+## When to version
+
+Version resources when the old state still matters.
+
+Good examples include:
+
+- A breaking API or schema change.
+- A message contract changing.
+- A service or system taking on a new responsibility.
+- A domain boundary changing.
+- A resource being replaced or deprecated.
+
+You do not need to version every small documentation edit. If the change is just wording, formatting, or a small clarification, updating the current page is usually enough.
diff --git a/packages/core/docs/development/guides/99-adding-analytics.md b/packages/core/docs/development/guides/99-adding-analytics.md
new file mode 100644
index 000000000..4a1e7ce2f
--- /dev/null
+++ b/packages/core/docs/development/guides/99-adding-analytics.md
@@ -0,0 +1,137 @@
+---
+sidebar_position: 99
+sidebar_label: Adding Analytics
+title: Adding Analytics
+description: Track page views and user behavior across your catalog
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<PlanBanner plan="Scale" />
+
+EventCatalog supports analytics integrations that let you track how your team navigates and uses your catalog. Connect your existing analytics tools to understand which services, events, and flows your team visits most.
+
+Three providers are supported: **Google Analytics 4**, **Google Tag Manager**, and **PostHog**. Multiple providers can be enabled at the same time.
+
+*Don't see your analytics provider? [Get in contact with us](https://discord.gg/3rjaZMmrAm) and let us know.*
+
+## How it works
+
+Analytics are configured in `eventcatalog.config.js` under the `integrations` key. When EventCatalog loads, the provider scripts are injected into the page `<head>` and a tracker listens for every navigation event.
+
+Every page view sends a set of properties automatically extracted from the URL:
+
+| Property | Description |
+|---|---|
+| `url` | The page pathname |
+| `section` | Catalog area: `visualiser`, `discover`, `directory`, `schemas`, `custom-docs`, `docs`, `home`, or `other` |
+| `resource_type` | One of: `service`, `event`, `command`, `query`, `domain`, `flow`, `channel`, `entity` |
+| `resource_id` | The resource identifier |
+| `resource_version` | The semver version |
+
+Analytics scripts load asynchronously and never block page rendering. If a provider fails, errors are caught silently so analytics never affect the catalog.
+
+## Configure a provider
+
+Add an `integrations` block to your `eventcatalog.config.js`. All providers are optional and can be combined.
+
+### Google Analytics 4
+
+```js title="eventcatalog.config.js"
+export default {
+  // ...
+  integrations: {
+    ga4: {
+      measurementId: 'G-XXXXXXXXXX',
+    },
+  },
+};
+```
+
+### Google Tag Manager
+
+```js title="eventcatalog.config.js"
+export default {
+  // ...
+  integrations: {
+    gtm: {
+      tagId: 'GTM-XXXXXXX',
+    },
+  },
+};
+```
+
+### PostHog
+
+```js title="eventcatalog.config.js"
+export default {
+  // ...
+  integrations: {
+    posthog: {
+      apiKey: 'phc_XXXXXXXXXXXX',
+      // Optional: defaults to US cloud
+      apiHost: 'https://us.i.posthog.com',
+    },
+  },
+};
+```
+
+### Use multiple providers
+
+Providers can be combined in a single `integrations` block.
+
+```js title="eventcatalog.config.js"
+export default {
+  // ...
+  integrations: {
+    ga4: {
+      measurementId: 'G-XXXXXXXXXX',
+    },
+    gtm: {
+      tagId: 'GTM-XXXXXXX',
+    },
+    posthog: {
+      apiKey: 'phc_XXXXXXXXXXXX',
+    },
+  },
+};
+```
+
+## Enable debug mode
+
+Set `debug: true` to log all analytics events to the browser console. This is useful for verifying that events are being sent correctly before deploying.
+
+```js title="eventcatalog.config.js"
+export default {
+  // ...
+  integrations: {
+    debug: true,
+    ga4: {
+      measurementId: 'G-XXXXXXXXXX',
+    },
+  },
+};
+```
+
+All events will appear in the browser console prefixed with `[EventCatalog Analytics]`, including adapter registration, page views, and any custom events.
+
+## Track custom events
+
+The analytics manager is exposed on `window.__ec_analytics`. Use it to send custom events from your own scripts or MDX pages.
+
+```js
+if (window.__ec_analytics) {
+  window.__ec_analytics.track('custom_event', { key: 'value' });
+}
+```
+
+Custom events are forwarded to all configured providers simultaneously.
+
+## Missing an integration?
+
+If you need support for an analytics provider not listed here, [open a GitHub issue](https://github.com/boyney123/eventcatalog/issues) or [join the Discord community](https://discord.gg/3rjaZMmrAm) and let us know. We are always looking to expand our integrations based on what teams are using.
+
+:::info Scale plan required
+Analytics integrations require an [EventCatalog Scale plan](https://eventcatalog.dev/pricing). If you configure integrations without a valid license, a warning is shown during build.
+:::
diff --git a/packages/core/docs/development/guides/_category_.json b/packages/core/docs/development/guides/_category_.json
new file mode 100644
index 000000000..b8a71221f
--- /dev/null
+++ b/packages/core/docs/development/guides/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Documenting your architecture",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "guides",
+    "description": "A collection of guides for EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/changelogs/01-introduction.md b/packages/core/docs/development/guides/changelogs/01-introduction.md
new file mode 100644
index 000000000..9e36a390f
--- /dev/null
+++ b/packages/core/docs/development/guides/changelogs/01-introduction.md
@@ -0,0 +1,33 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Changelogs
+sidebar_label: What are changelogs?
+title: Understanding changelogs
+description: What are changelogs
+---
+
+In your architecture, various resources like domains, services, schemas, and boundaries are constantly evolving. **Unfortunately, the context or reason behind these changes often gets lost.**
+
+EventCatalog changelogs allow you to capture these changes and help your team understand the history of your architecture.
+
+### Features
+
+- Powered by markdown, add a `changelog.mdx` to your domains, services and messages
+- Automated diffs for `.json`, `.avro`, `.yml` and `.yaml` files.
+- Custom components and MDX component support
+- Timestamps and linear history on page
+
+
+
+
+#### Example
+
+<!-- ![Example](/assets/images/changelog-b60ba4ecaafb228a61fd5a517d3c1428.png) -->
+
+![Example](/img/blogs/changelog.png)
+
+[You can see a changelog example here](https://demo.eventcatalog.dev/docs/events/InventoryAdjusted/1.0.1/changelog).
+
+<!-- http://localhost:3000/assets/images/changelog-b60ba4ecaafb228a61fd5a517d3c1428.png -->
diff --git a/packages/core/docs/development/guides/changelogs/02-adding-changelogs.md b/packages/core/docs/development/guides/changelogs/02-adding-changelogs.md
new file mode 100644
index 000000000..4abf4c265
--- /dev/null
+++ b/packages/core/docs/development/guides/changelogs/02-adding-changelogs.md
@@ -0,0 +1,94 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog changelogs
+sidebar_label: Creating a changelog
+title: Creating changelogs
+description: Creating and managing changelogs within EventCatalog.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Changelogs are currently supported in [domains](/docs/development/guides/domains/add-changelog), [services](/docs/development/guides/resources/services/versioning-and-lifecycle/add-changelog) and [messages](/docs/development/guides/resources/messages/versioning-and-lifecycle/add-changelog).
+
+To add a changelog to your resources you need to create a `changelog.mdx` file.
+
+- /\{resource\}/\{resource name\}/changelog.mdx
+  - example: /services/My Service/changelog.mdx
+  - example for verion: /services/My Service/versioned/0.0.1/changelog.mdx
+
+**Example of changelogs for resources**
+
+<Tabs>
+  <TabItem value="events" label="Events" default>
+   ```md title="/events/OrderPlaced/changelog.mdx"
+---
+createdAt: 2024-08-01
+badges:
+    - content: ⭐️ JSON Schema
+      backgroundColor: purple
+      textColor: purple
+---
+
+### Added support for JSON Schema
+
+InventoryAdjusted uses Avro but now also supports JSON Draft 7.
+
+```json title="Employee JSON Draft"
+// labeled-line-markers.jsx
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Employee",
+  "properties": {
+    "Name": {
+      "type": "string"
+    },
+    "Age": {
+      "type": "integer"
+    },
+    "Town": {
+      "type": "string"
+    }
+  },
+  "required": ["Name", "Age", "Town"]
+}
+
+``
+```
+
+  </TabItem>
+  <TabItem value="services" label="Services">
+    ```md title="/services/Inventory/changelog.mdx"
+    ---
+createdAt: 2024-08-01
+---
+
+### Service receives additional events
+
+Service now receives [OrderAmended](/docs/events/OrderAmended/0.0.1) and [UpdateInventory](/docs/commands/UpdateInventory/0.0.3) events.
+    ```
+  </TabItem>
+  <TabItem value="domains" label="Domains">
+    ```md title="/domains/Order/changelog.mdx"
+    ---
+createdAt: 2024-08-01
+---
+
+### New service added to the Payment domain
+
+Service now receives [OrderAmended](/docs/events/OrderAmended/0.0.1) and [UpdateInventory](/docs/commands/UpdateInventory/0.0.3) events.
+    ```
+  </TabItem>
+</Tabs>
+
+### Viewing your changelog
+
+Domains, services and messages have a **Changelog** button. Clicking this button will take you to the changelog for that resource.
+
+![Example output](./img/changelog-button.png)
+
+Domains, services and messages all have a changelog url.
+
+See example changelog: https://demo.eventcatalog.dev/docs/events/InventoryAdjusted/1.0.1/changelog
diff --git a/packages/core/docs/development/guides/changelogs/03-automated-changelogs.md b/packages/core/docs/development/guides/changelogs/03-automated-changelogs.md
new file mode 100644
index 000000000..910e0d990
--- /dev/null
+++ b/packages/core/docs/development/guides/changelogs/03-automated-changelogs.md
@@ -0,0 +1,44 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog diffs
+sidebar_label: Automated diffs
+title: Automated diffs
+description: Understanding how EventCatalog automates diffs for your files
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.7.3"/>
+
+EventCatalog allows you to store schemas, API specifications and custom files along side your domains, services and messages. For [example you can add specifications to a service](/docs/development/guides/resources/schemas/add-specifications-to-services/add-openapi-specifications).
+
+When you version your resources, you can also version the files. When you do this, EventCatalog will match the current version to it's previous version and calculate if any diffs should be displayed in your changelog page.
+
+**Features**
+
+- Automated diffs for your OpenAPI and AsyncAPI files
+- Automated diffs for your schemas (any format)
+
+:::info
+Automated diffs only work with `.json`, `.avro`, `.yml` and `.yaml` files at the moment. If you would like to support more files please raise an issue on GitHub.
+:::
+
+### How it works
+
+Let's say we have a service called Orders, this service has an OpenAPI file.
+- `/services/Orders/index.mdx`
+- `/services/Orders/openapi.yml`
+- `/services/Orders/changelog.mdx`
+
+Let's now version this service, by added the `versioned` folder.
+
+- `/services/Orders/versioned/0.0.1/index.mdx`
+- `/services/Orders/versioned/0.0.1/openapi.yml`
+- `/services/Orders/versioned/0.0.1/changelog.mdx`
+
+If any changes have been made to the `openapi.yml` file in this example, this changes will be shown in the service changelog page.
+
+![Automated logs](./img/automated-logs.png)
+
+[You can see the example in our demo](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3/changelog).
diff --git a/packages/core/docs/development/guides/changelogs/04-reference.md b/packages/core/docs/development/guides/changelogs/04-reference.md
new file mode 100644
index 000000000..9ab1b6831
--- /dev/null
+++ b/packages/core/docs/development/guides/changelogs/04-reference.md
@@ -0,0 +1,77 @@
+---
+keywords:
+- EventCatalog changelogs
+- Changelog frontmatter
+sidebar_label: Reference
+title: Changelogs reference
+description: Frontmatter fields and paths for changelogs in EventCatalog.
+---
+
+This page lists the fields and paths supported by changelogs.
+
+## Paths
+
+Changelogs can be created for versioned resources using `changelog.md` or `changelog.mdx`.
+
+```txt
+/{collection}/{Resource Name}/versioned/{version}/changelog.mdx
+```
+
+For example:
+
+```txt
+/services/PaymentService/versioned/1.0.0/changelog.mdx
+/domains/Payments/versioned/1.0.0/changelog.mdx
+```
+
+## Optional fields
+
+### `createdAt` {#createdAt}
+
+- Type: `date`
+
+Date the changelog entry was created.
+
+```md title="Example"
+---
+createdAt: 2026-05-26
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badge metadata for the changelog entry.
+
+```md title="Example"
+---
+badges:
+  - content: Breaking change
+    backgroundColor: red
+    textColor: red
+---
+```
+
+## Badge fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `content` | `string` | Badge text. |
+| `backgroundColor` | `string` | Badge background color. |
+| `textColor` | `string` | Badge text color. |
+| `icon` | `string` | Optional icon. |
+
+## Example
+
+```md
+---
+createdAt: 2026-05-26
+badges:
+  - content: Breaking change
+    backgroundColor: red
+    textColor: red
+---
+
+Updated the payment authorization event contract.
+```
diff --git a/packages/core/docs/development/guides/changelogs/_category_.json b/packages/core/docs/development/guides/changelogs/_category_.json
new file mode 100644
index 000000000..60dab4360
--- /dev/null
+++ b/packages/core/docs/development/guides/changelogs/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Changelogs",
+  "position": 14,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/changelogs",
+    "description": "A collection of guides to help you understand changelogs and how they work with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/domains/01-introduction.md b/packages/core/docs/development/guides/domains/01-introduction.md
new file mode 100644
index 000000000..926190ac2
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/01-introduction.md
@@ -0,0 +1,27 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog domains
+sidebar_label: What are domains?
+title: What are domains?
+description: What are domains? Why are they useful for event-driven architectures?
+---
+
+In EventCatalog a domain describes a business boundary (term from Domain-Driven Design).
+
+For example, an e-commerce architecture may have domains such as `Fulfilment`, `Ordering`, `Payments` or `Shopping` and these domains may contain their own language, systems, services, events, and many more lower level resources.
+
+Documenting domains (and subdomains) in EventCatalog can help your teams understand busiess boundaries, team ownership and how these boundaries fit together in your organization.
+
+You can assign resources to your domains (e.g systems, services, messages) that can help your team dive deeper into a domain to understand implmentation details.
+
+<details>
+    <summary>What is Domain Driven Design?</summary>
+
+    Domain-Driven Design (DDD) is a software development approach that focuses on deeply understanding and accurately modelling the business domain. This methodology aims to enhance software quality by ensuring it aligns closely with the business requirements it supports. Eric Evans introduced DDD to the software development community in 2003 through his influential book, [Domain-Driven Design: Tackling Complexity in the Heart of Software](https://www.amazon.co.uk/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215).
+
+The essence of domain-driven design lies in managing complexity by centering software development around the ‘domain,’ which is the specific business context where the software is used. DDD promotes the use of a [ubiquitous language](https://martinfowler.com/bliki/UbiquitousLanguage.html), a shared vocabulary between developers and business stakeholders. This common language is used throughout the design and implementation process, ensuring that the software accurately represents the business domain it is designed to serve.
+
+Domain-driven design has some core building blocks including entities, value objects, bounded context and aggregates.
+
+  </details>
diff --git a/packages/core/docs/development/guides/domains/02-create-domain.md b/packages/core/docs/development/guides/domains/02-create-domain.md
new file mode 100644
index 000000000..05682bbfd
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/02-create-domain.md
@@ -0,0 +1,124 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog domains
+sidebar_label: Create a domain
+title: Create a domain
+description: Creating and managing domains within EventCatalog.
+---
+
+import PromptBox from '@site/src/components/MDX/PromptBox';
+
+Domains are a great way to document a business boundary, define its [ubiquitous language](/docs/development/guides/domains/ownership-and-language/adding-ubiquitous-language) and group your documentation into logical units that can be represented in your organization.
+
+Domains can contains resources (e.g [systems](/docs/development/guides/systems/introduction), [services](/docs/development/guides/resources/services/introduction), [entities](/docs/development/guides/resources/entities/introduction), [messages](/docs/development/guides/resources/messages/what-are-messages), subdomains,  and more).
+
+![Example](../img/domains/domain-example.png)
+
+---
+
+### Creating a domain
+
+#### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog domain">
+Read https://www.eventcatalog.dev/docs/development/guides/domains/create-domain.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/domains.md then help me create a new EventCatalog domain in my catalog.
+
+Ask me for the domain name, business boundary, summary and what it does. Then create the correct domains/{'{Domain Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+
+
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can guide you through creating the domain, choosing the right folder structure, and adding the first version of the domain documentation.
+
+#### Manual Creation
+
+To add a new domain create a new folder within the `/domains` folder with an `index.mdx` file.
+
+- `/domains/{Domain Name}/index.mdx` 
+  - (example `/domains/Orders/index.mdx`)
+
+The `index.mdx` contents are split into two sections, [**frontmatter**](/docs/development/guides/domains/reference) and the [**markdown content**](#adding-content).
+
+_Here is an example of what a domain markdown file may look like._
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+# id of your domain, used for slugs and references in EventCatalog.
+id: Orders
+
+# Display name of the domain, rendered in EventCatalog
+name: Orders
+
+# Version of the domain
+version: 0.0.1
+
+# Short summary of your domain
+summary: |
+  Domain that contains order related information
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional services. Groups services into this domain.
+services:
+    - id: PaymentService
+      version: 0.0.1
+
+# Optional flows associated with this domain
+flows:
+    - id: OrderProcessing
+      version: 1.0.0
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: New domain
+      backgroundColor: blue
+      textColor: blue
+---
+
+## Overview
+
+Domain that contains all services that are related to the orders domain within FakeCompany.
+
+<NodeGraph />
+
+```
+
+Once you add your domain it will appear in your catalog.
+
+---
+
+## Adding content to your domain
+
+Your domain page will render the markdown content you add to the file. To add content to your domain page, add markdown to the file.
+
+EventCatalog supports [MDX](https://mdxjs.com/) under the hood. This gives you the ability to use components inside your domain page.
+
+You can find a list of EventCatalog components you can use here: [EventCatalog components](/docs/development/components/using-components).
+
+```md title="/domains/Orders/index.mdx"
+---
+id: Orders
+version: 0.0.1
+name: Orders
+---
+
+## Overview
+
+This is your domain markdown....
+
+You can add anything here...
+
+Including EventCatalog components
+
+<NodeGraph />
+
+```
+
+
+
+
diff --git a/packages/core/docs/development/guides/domains/03-model-subdomains.md b/packages/core/docs/development/guides/domains/03-model-subdomains.md
new file mode 100644
index 000000000..adb31de37
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/03-model-subdomains.md
@@ -0,0 +1,96 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog domains
+sidebar_label: Model subdomains
+title: Model subdomains
+description: Creating and managing subdomains within EventCatalog.
+---
+
+import PromptBox from '@site/src/components/MDX/PromptBox';
+
+Subdomains are optional in EventCatalog but can be a great way to group domains together. 
+
+Some organizations have multiple domains, and each domain may have multiple subdomains.
+
+When you add a subdomain to a domain, your users will be able to see the relationship between the domain and subdomain, and be able to navigate between them.
+
+### What do subdomains look like in EventCatalog?
+
+![Example](../img/domains/subdomain-example.png)
+
+_See [subdomain example](https://demo.eventcatalog.dev/docs/domains/E-Commerce/1.0.0) in the EventCatalog Demo._
+
+
+#### Domains Visualizer (with subdomains)
+
+When you reference a subdomain from a domain, it will appear in the domains visualizer.
+You can use the legend to highlight resources that are part of a subdomain.
+
+![Domains Visualizer (with subdomains)](../img/domains/subdomain-visualizer.png)
+
+_See [subdomain example](https://demo.eventcatalog.dev/visualiser/domains/E-Commerce/1.0.0) in the EventCatalog Demo._
+
+## Adding subdomains
+
+### Automatic Creation
+
+<PromptBox preview="Model subdomains in EventCatalog">
+Read https://www.eventcatalog.dev/docs/development/guides/domains/model-subdomains.md and https://github.com/event-catalog/skills/blob/main/skills/catalog-documentation-creator/references/domains.md then help me model subdomains in my EventCatalog catalog.
+
+Ask me for the parent domain, subdomain names, business boundaries, and summaries. Then create the correct domains/{'{Parent Domain}'}/subdomains/{'{Subdomain Name}'}/index.mdx files and update the parent domain frontmatter to reference each subdomain.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you decide which domains should become subdomains, create the right folder structure, and update the parent domain references.
+
+### Manual Creation
+
+A subdomain is just another domain resource. But a parent domain references the subdomains.
+
+First you need to create your subdomain.
+
+You can create a subdomain in the `/domains` folder or in a `/subdomains` folder.
+
+**Examples**
+
+1. `/domains/MySubDomain/index.mdx` - Just like any other domain resource.
+2. `/domains/MyParentDomain/subdomains/MySubDomain/index.mdx`
+    - You nest the subdomain within the parent domain. (recommended)
+
+Once you have created your subdomain, you can reference it from your parent domain.
+
+#### Referencing subdomains
+
+To add a `subdomain` to a `domain` you need to reference the `subdomain` from the `domain` markdown file.
+
+We do this using the `domains` property.
+
+In this example we are adding the `Orders` and `Customers` subdomains to the `Ecommerce` domain.
+
+```md title="/domains/Ecommerce/index.mdx (example)"
+---
+id: Ecommerce
+name: Ecommerce
+version: 0.0.1
+
+# List of subdomains (version is optional)
+domains:
+  # Here version is given, the latest version of Orders Domain is used.
+  - id: Orders
+    version: 0.0.1
+  # Here version is not given, the latest version of Customers Domain is used.
+  - id: Customers
+---
+
+## Overview
+
+Ecommerce domain contains all ecommerce related information for FakeCompany.
+
+<NodeGraph />
+
+```
+
+Once you add the subdomains to the domain, it will now show in the docs, visualizer and discoverability table.
diff --git a/packages/core/docs/development/guides/domains/03-ownership-and-language/01-owners.md b/packages/core/docs/development/guides/domains/03-ownership-and-language/01-owners.md
new file mode 100644
index 000000000..49c2a49ef
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/03-ownership-and-language/01-owners.md
@@ -0,0 +1,36 @@
+---
+sidebar_position: 1
+
+keywords:
+- EventCatalog
+- domain 
+- owners
+sidebar_label: Adding domain owners
+title: Adding domain owners
+description: Adding owners to domains with EventCatalog.
+---
+
+You can assign owners to your domains to provide context of who owns this domain and how to contact them.
+
+Owners in EventCatalog are either [**users**](/docs/development/guides/owners/what-are-teams-and-users) or [**teams**](/docs/development/guides/owners/what-are-teams-and-users) and are **optional**.
+
+## Adding owners to a domain
+
+To add owners to a domain you need to add them to the `owners` array within your domain frontmatter API.
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+id: PaymentDomain
+... # other domain frontmatter
+owners:
+    - dboyne # represents a user
+    - webTeam # represents a team
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Assigning owners to your domains can provide others with context of who owns this domain and how to contact them.
+
+
diff --git a/packages/core/docs/development/guides/domains/03-ownership-and-language/02-adding-ubiquitous-language.md b/packages/core/docs/development/guides/domains/03-ownership-and-language/02-adding-ubiquitous-language.md
new file mode 100644
index 000000000..08876ac51
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/03-ownership-and-language/02-adding-ubiquitous-language.md
@@ -0,0 +1,71 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog domains
+sidebar_label: Ubiquitous language
+title: Ubiquitous language
+description: Creating a Ubiquitous-language dictionary for your domain
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Ubiquitous Language is a shared language that is used by all stakeholders in a project/domain to improve communication and reduce misunderstandings.
+
+In EventCatalog you can define a dictionary of ubiquitous language terms for your domain, this can help your teams understand the language used in your domain and models used in your architecture.
+
+## Using ubiquitous language in EventCatalog
+
+To add a ubiquitous language dictionary, create a new file within your domain folder with the name `ubiquitous-language.mdx`.
+
+- `/domains/{Domain Name}/ubiquitous-language.mdx`
+
+The contents of the file should be a list of terms used in your domain. 
+
+Each term should have a name, summary, description and icon. The icon is optional and can be used to visually represent the term. You can find a list of icons [here](https://lucide.dev/). Use the PascalCase React component name for Lucide icons, for example `file-text` should be configured as `FileText`.
+
+```md title="/domains/Orders/ubiquitous-language.md"
+---
+dictionary:
+  - id: Purchase Order
+    name: Purchase Order
+    summary: "A mystical document issued by a buyer to a seller, here indicating the types, quantities, and agreed prices for enchanted products or services."
+    description: |
+      A purchase order (PO) is a magical document that initiates the buying process between mystical entities. It protects both buyer and seller by clearly documenting the transaction details. Key components include:
+
+      - Unique PO number for tracking
+      - Detailed item specifications and quantities
+      - Agreed prices and payment terms
+      - Delivery requirements and timelines
+      - Terms and conditions of the purchase
+
+      POs are essential for budget control, audit trails, and inventory management. They help prevent unauthorized purchases and provide a clear record for accounting and reconciliation purposes.
+    icon: FileText 
+  - id: Order Line
+    name: Order Line
+    summary: "An individual enchanted item within a purchase order, representing a specific magical product or service being ordered."
+    description: |
+      Order lines are the fundamental building blocks of any purchase order. Each line represents a distinct item or service and contains critical information for order fulfillment:
+
+      - Product identifier (SKU or part number)
+      - Quantity ordered
+      - Unit price and total line value
+      - Special handling instructions
+      - Required delivery date
+
+      Order lines drive warehouse picking operations, shipping processes, and financial calculations. They are essential for tracking partial shipments and managing order modifications.
+    icon: ListOrdered
+---
+
+```
+
+### Viewing the ubiquitous language in EventCatalog
+
+When you add a ubiquitous language dictionary to your domain, it will automatically appear in the sidebar of the domain.
+
+![Example](../../img/domains/ubiquitous-lang-sidebar.png)
+<a class="block" href="https://demo.eventcatalog.dev/docs/domains/Orders/language">View demo</a>
+
+Clicking on a term in the Domain Language explorer will open that term in a new page. 
+
+
+
diff --git a/packages/core/docs/development/guides/domains/03-ownership-and-language/_category_.json b/packages/core/docs/development/guides/domains/03-ownership-and-language/_category_.json
new file mode 100644
index 000000000..33d8faf8a
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/03-ownership-and-language/_category_.json
@@ -0,0 +1,10 @@
+{
+  "label": "Ownership & language",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/ownership-and-language"
+  }
+}
diff --git a/packages/core/docs/development/guides/domains/04-add-resources-to-domains/01-add-systems-to-domains.md b/packages/core/docs/development/guides/domains/04-add-resources-to-domains/01-add-systems-to-domains.md
new file mode 100644
index 000000000..39d12b5c8
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/04-add-resources-to-domains/01-add-systems-to-domains.md
@@ -0,0 +1,154 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog domains
+- EventCatalog systems
+sidebar_label: Add systems to domains
+title: Add systems to domains
+description: Add systems to domains so users can move from a business boundary to the software capabilities inside it.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+<AddedIn version="4.0" />
+
+A [system](/docs/development/guides/systems/introduction) is a collection of resources that work together to perform a function.
+
+Adding systems to your domains helps users move from a business boundary to the software capabilities inside that boundary.
+
+A domain describes the business area or bounded context. A system groups the resources that work together to deliver a capability, such as services, messages, APIs, data stores, flows, or agents.
+
+Systems can live inside a domain folder or outside it. Add them to a domain when you want the domain page to show which systems belong to that business boundary.
+
+## Example domains and systems
+
+For an e-commerce catalog, your domains might look like this:
+
+| Domain | What it represents | Example systems |
+|--------|--------------------|-----------------|
+| `Shopping` | Browsing products, managing carts, and preparing checkout. | `Product Discovery System`, `Cart System`, `Promotion System` |
+| `Ordering` | Taking an order from checkout through fulfilment. | `Checkout System`, `Order Management System`, `Fulfilment System` |
+| `Payments` | Authorizing, capturing, refunding, and reconciling payments. | `Payment Processing System`, `Fraud Review System`, `Refund System` |
+| `Customer` | Customer identity, profiles, preferences, and communication settings. | `Customer Profile System`, `Identity System`, `Notification Preferences System` |
+
+The domain gives users the business boundary. The systems show the software capabilities inside that boundary.
+
+## Recommended structure
+
+When a system clearly belongs to a domain, keep it inside the domain folder.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Shopping',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cart-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+                {
+                  name: 'promotion-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This keeps the business model clear: the `Shopping` domain owns the `Cart System` and `Promotion System`.
+
+## Adding systems using frontmatter
+
+To add systems to a domain, add a `systems` array to the domain frontmatter.
+
+```md title="/domains/Shopping/index.mdx (example)"
+---
+id: shopping
+name: Shopping
+version: 1.0.0
+summary: |
+  The Shopping domain owns the customer's path to purchase.
+systems:
+  - id: cart-system
+    version: 1.0.0
+  - id: promotion-system
+    version: 1.0.0
+---
+
+## Overview
+
+The Shopping domain is responsible for everything between browsing and buying.
+```
+
+The `systems` field tells EventCatalog which systems belong to the domain.
+
+The `version` is optional. If no version is given, EventCatalog uses the latest version of the system.
+
+## Showing systems in context
+
+You can add `<ContextDiagram />` to the domain page to show the systems in that domain and how they relate to each other.
+
+![Systems context map showing systems and actors inside a domain](./img/systems-in-domain-context.png)
+
+```md title="/domains/Shopping/index.mdx (example)"
+---
+id: shopping
+name: Shopping
+version: 1.0.0
+systems:
+  - id: cart-system
+  - id: promotion-system
+---
+
+## System context
+
+<ContextDiagram />
+```
+
+Use this view when you want readers to understand the systems inside a domain before they drill into lower-level resources.
+
+## Linking to systems from domain docs
+
+You can link to systems from domain Markdown using resource references.
+
+```md
+The [[system|cart-system]] owns cart state and checkout.
+```
+
+If you want systems to act as entry points from the domain page, you can also use tiles or regular Markdown links.
+
+## When to add systems to a domain
+
+Add systems to a domain when the system is part of that domain's business boundary.
+
+For example:
+
+- `Shopping` contains `Cart System` and `Promotion System`.
+- `Ordering` contains `Checkout System` and `Order Management System`.
+- `Customer` contains `Customer Management System` and `Identity Provider`.
+
+If a system is shared across multiple domains, you can keep it outside the domain folder and still reference it from the domain frontmatter.
+
+For the complete system fields and file structure, see the [systems reference](/docs/development/guides/systems/reference).
diff --git a/packages/core/docs/development/guides/domains/04-add-resources-to-domains/02-add-services-to-domains.md b/packages/core/docs/development/guides/domains/04-add-resources-to-domains/02-add-services-to-domains.md
new file mode 100644
index 000000000..845f546cd
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/04-add-resources-to-domains/02-add-services-to-domains.md
@@ -0,0 +1,86 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog domains
+sidebar_label: Add services to domains
+title: Add services to domains
+description: Creating and managing domains within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+A service is an implementation resource. It might be an API, worker, backend service, frontend application, or other deployable component. A service can produce/consume messages or implement an API specification (e.g OpenAPI, AsyncAPI, GraphQL).
+
+Adding [services](/docs/development/guides/resources/services/introduction) to your domains is a great way to group services within a particular domain.
+
+When adding services to your domain EventCatalog will:
+
+- Show the services in the domain sidebar
+- Visualize all the services within that domain using the visualizer
+
+## Adding services using frontmatter
+
+To add services within a domain you need to add them to the `services` array within your domain frontmatter API.
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+id: PaymentDomain
+... # other domain frontmatter
+services:
+    # id of the service you want to add
+    - id: PaymentsService
+    # (optional) The version of the service you want to add.
+      version: 0.0.1
+
+    # Note: version is optional. If no version is given the latest version of the service will be used.
+    - id: NotificationsService
+---
+
+<!-- Markdown content... -->
+
+```
+
+The `services` frontmatter in your domain tells EventCatalog that these documented services belong to this domain.
+
+In the example above we can see that the services `PaymentsService` and `NotificationsService` belong to the `PaymentDomain`.
+
+### Using semver versioning
+
+<AddedIn version="2.4.0" />
+
+You can also use semver to match the version of the service you want to add.
+
+<details>
+  <summary>Example of using semver versioning</summary>
+
+  ```md title="/domains/Orders/index.mdx (example)"
+---
+id: PaymentDomain
+... # other domain frontmatter
+services:
+    # Latest minor version of PaymentsService will be added
+    - id: PaymentsService
+      version: 0.x.1
+    # Minor and patches of this version will be linked
+    - id: NotificationsService
+      version: ^1.0.1
+    # Latest version of this service will be shown by default.
+    - id: PaymentsService
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Although it's recommended to link to a version of a service it is now optional. If no version is given **latest** is used by default.
+</details>
+
+
+
+
+### Visualizing services within a domain
+
+When you view your domain in EventCatalog, the services will be visualized for you.
+
+![Example](../../img/domains/visualiser.png)
+
diff --git a/packages/core/docs/development/guides/domains/04-add-resources-to-domains/03-add-messages-to-domains.md b/packages/core/docs/development/guides/domains/04-add-resources-to-domains/03-add-messages-to-domains.md
new file mode 100644
index 000000000..7dde21f78
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/04-add-resources-to-domains/03-add-messages-to-domains.md
@@ -0,0 +1,105 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog domains
+- domain messages
+sidebar_label: Add messages to domains
+title: Add messages to domains
+description: Document event flows at the domain level.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Adding [messages](/docs/development/guides/resources/messages/what-are-messages) to your domains allows you to document which messages are published and consumed by your domain.
+
+Some teams may prefer to document messages at the domain level, and have the service reference the domain messages (implementation of the domain messages).
+
+These can be known as "domain events", "external events" or "integration events", it's really up to you how you want to model them.
+
+These messages can live anywhere in your catalog, at the domain level or within the service folder. You just need to reference them in your domain frontmatter.
+
+## Adding messages using frontmatter
+
+To add messages to a domain you need to define them in either the `sends` or `receives` array within your domain frontmatter API.
+
+- sends: messages this domain publishes
+- receives: messages this domain consumes
+
+You need to add the `id` of the message and optionally the `version` of the message.
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+id: Orders
+... # other domain frontmatter
+receives:
+    # id of the message this domain receives
+    - id: PaymentProcessed
+    # (optional) The version of the message you want to add.
+    # If no version is given the latest version of the message will be used.
+      version: 0.0.1
+sends:
+    # id of the message this domain sends
+    - id: OrderCreated
+      version: 2.0.1
+---
+
+<!-- Markdown content... -->
+
+```
+
+The `sends` and `receives` fields in your domain tell EventCatalog which messages this domain either publishes or consumes.
+
+In the example above we can see that the `Orders` domain receives the `PaymentProcessed` message and sends the `OrderCreated` message.
+
+## Domain vs service level messaging
+
+Messages can be documented at either the domain level or service level. This is flexible and it's up to you which you prefer.
+
+- Service Level
+  - You document messages a particular service publishes or consumes.
+- Domain Level
+  - You document messages that are published or consumed by a domain.
+
+Remember you can also use both approaches together, and your messages can live anywhere in your catalog.
+
+## Using semver versioning
+
+<AddedIn version="2.4.0" />
+
+You can use [semver](https://semver.org/) syntax when referencing messages in your domains.
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+id: Orders
+... # other domain frontmatter
+receives:
+    # Domain receives a message called PaymentProcessed
+    # The latest minor/patch version of this event will be used
+    - id: PaymentProcessed
+      version: 1.x.x
+sends:
+    # Domain sends a message called OrderCreated
+    # This pulls the latest patch version of OrderCreated
+    - id: OrderCreated
+      version: 2.0.x
+    # Domain sends a message called OrderCancelled
+    # This pulls the latest minor/patch version of OrderCancelled
+    - id: OrderCancelled
+      version: >1.0.1
+---
+
+<!-- Markdown content... -->
+
+```
+
+Although it's recommended to link to a version of a message it is now optional. If no version is given the latest version is used by default.
+
+## Visualizing messages within a domain
+
+Messages are shown in the sidebar of your domain under "Publishes Messages" and "Consumes Messages" sections. There is currently no visualizer support for messages at the domain level.
+
+_Coming soon: Visualizer support for messages at the domain level._
+
+## Making changes and versioning
+
+You can make as many changes as you want, but if you are adding or removing messages you may want to consider versioning your domain. This allows you to keep historic changes, and let others understand why messages are coming in or out of a particular domain.
diff --git a/packages/core/docs/development/guides/domains/04-add-resources-to-domains/04-add-data-products-to-domains.md b/packages/core/docs/development/guides/domains/04-add-resources-to-domains/04-add-data-products-to-domains.md
new file mode 100644
index 000000000..9ec571630
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/04-add-resources-to-domains/04-add-data-products-to-domains.md
@@ -0,0 +1,106 @@
+---
+sidebar_position: 5
+sidebar_class_name: hidden
+keywords:
+  - EventCatalog domains
+  - domain data products
+sidebar_label: Add data products to domains
+title: Add data products to domains
+description: Organize analytics and data assets within domain boundaries.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.8.0" />
+
+Adding [data products](/docs/development/guides/resources/data-products/introduction) to your domains allows you to document which analytical assets and data pipelines belong to a domain.
+
+Data products can live anywhere in your catalog, at the domain level or in their own folder. You just need to reference them in your domain frontmatter.
+
+## Adding data products using frontmatter
+
+To add data products to a domain you need to add them to the `data-products` array within your domain frontmatter API.
+
+```md title="/domains/E-Commerce/index.mdx (example)"
+---
+id: e-commerce
+name: E-Commerce
+version: 1.0.0
+
+data-products:
+  # id of the data product you want to add
+  - id: order-analytics
+    # (optional) The version of the data product you want to add.
+    # If no version is given the latest version of the data product will be used.
+    version: 1.0.0
+
+  # version is optional for all data products
+  - id: payment-analytics
+---
+
+<!-- Markdown content... -->
+
+```
+
+The `data-products` field in your domain tells EventCatalog which data products belong to this domain.
+
+In the example above we can see that the `order-analytics` and `payment-analytics` data products belong to the `e-commerce` domain.
+
+## Using semver versioning
+
+<AddedIn version="3.8.0" />
+
+You can use [semver](https://semver.org/) syntax when referencing data products in your domains.
+
+```md title="/domains/E-Commerce/index.mdx (example)"
+---
+id: e-commerce
+name: E-Commerce
+version: 1.0.0
+
+data-products:
+  # Latest minor/patch version of order-analytics will be used
+  - id: order-analytics
+    version: 1.x.x
+  # Latest patch version of payment-analytics will be used
+  - id: payment-analytics
+    version: 2.0.x
+  # Latest version of fulfillment-metrics will be used
+  - id: fulfillment-metrics
+---
+
+<!-- Markdown content... -->
+
+```
+
+Although it's recommended to link to a version of a data product it is now optional. If no version is given the latest version is used by default.
+
+## Visualizing data products within a domain
+
+Data products are shown in the sidebar of your domain under a "Data Products" section. You can also display them in a grid alongside other domain resources.
+
+```md title="/domains/E-Commerce/index.mdx"
+---
+id: e-commerce
+name: E-Commerce
+version: 1.0.0
+
+data-products:
+  - id: order-analytics
+  - id: payment-analytics
+---
+
+## Data Products
+
+Our analytical capabilities include order metrics, payment insights, and fulfillment KPIs.
+
+```
+
+## Making changes and versioning
+
+You can make as many changes as you want, but if you are adding or removing data products you may want to consider versioning your domain. This allows you to keep historic changes, and let others understand why data products are coming in or out of a particular domain.
+
+## See also
+
+- [Data products guide](/docs/development/guides/resources/data-products/introduction)
+- [Adding data products to domains](/docs/development/guides/domains/add-resources-to-domains/add-data-products-to-domains)
diff --git a/packages/core/docs/development/guides/domains/04-add-resources-to-domains/05-add-entities-to-domains.md b/packages/core/docs/development/guides/domains/04-add-resources-to-domains/05-add-entities-to-domains.md
new file mode 100644
index 000000000..4ba872ab2
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/04-add-resources-to-domains/05-add-entities-to-domains.md
@@ -0,0 +1,115 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_position: 4
+sidebar_label: Add entities to domains
+title: Add entities to domains
+description: Creating and managing entities within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Once you have [created your entities](/docs/development/guides/resources/entities/create-entity) you can add them to your domains.
+
+To add an entity to a domain, add the entity to the `entities` array in the domain's markdown file.
+
+```mdx title="/domains/Orders/index.mdx"
+
+---
+id: Orders
+name: Orders
+version: 1.0.0
+entities:
+  - id: Order
+    version: 1.0.0
+  - id: OrderItem
+    version: 1.0.0
+---
+
+Your domain markdown...
+
+```
+
+## Visualize domain entities
+
+<AddedIn version="2.49.0" />
+
+When a domain has entities assigned, EventCatalog can generate an entity map for that domain.
+
+The entity map helps teams understand the domain model at a glance. It shows:
+
+- The entities inside the domain
+- The relationships between those entities
+- Which entities are owned by the current domain
+- Entities referenced from other domains
+
+Entities that are referenced from another domain are shown as **yellow**.
+
+![Entity Map](../../resources/entities/img/entity-map.png)
+
+## View the entity map in the visualizer
+
+EventCatalog creates a dedicated entity map visualizer route for domains:
+
+```txt
+/visualiser/domains/{id}/{version}/entity-map
+```
+
+For services, the route is:
+
+```txt
+/visualiser/services/{id}/{version}/entity-map
+```
+
+When a domain or service has entities assigned, an **Entity Map** link appears automatically in the resource sidebar under the visualizer section.
+
+## Embed the entity map on a page
+
+You can also embed the entity map of a domain on any page in your catalog using the `<EntityMap />` component.
+
+```mdx
+<EntityMap id="Orders" title="Orders Domain Entity Map" />
+```
+
+![Entity Map Component](../../resources/entities/img/entity-map-component.png)
+
+## Create relationships between entities
+
+Entity maps become more useful when your entities reference each other.
+
+Use the optional reference fields on entity properties:
+
+- `references`: The entity you want to reference, for example `Order`
+- `relationType`: The type of relationship, for example `hasOne`, `hasMany`, or `belongsTo`
+- `referencesIdentifier`: The property in the referenced entity used to establish the relationship, for example `orderId`
+
+For example, an `OrderItem` can reference an `Order` through `orderId`.
+
+```yaml title="/domains/Orders/entities/OrderItem/index.mdx"
+---
+id: OrderItem
+name: OrderItem
+version: 1.0.0
+identifier: orderItemId
+summary: Represents a single item within a customer's order.
+
+properties:
+  - name: orderItemId
+    type: UUID
+    required: true
+    description: Unique identifier for the order item
+  - name: orderId
+    type: UUID
+    required: true
+    description: Identifier for the parent Order
+    references: Order
+    relationType: hasOne
+    referencesIdentifier: orderId
+---
+```
+
+This configuration generates an entity map that visually shows the relationship between `OrderItem` and `Order`.
+
+![Entity Map showing a relationship between OrderItem and Order](../../resources/entities/img/simple-entity-map.png)
+
+More information on entity reference fields can be found in the [entities reference](/docs/development/guides/resources/entities/reference).
diff --git a/packages/core/docs/development/guides/domains/04-add-resources-to-domains/_category_.json b/packages/core/docs/development/guides/domains/04-add-resources-to-domains/_category_.json
new file mode 100644
index 000000000..d461a81b3
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/04-add-resources-to-domains/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Add resources to domains",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/domains/add-resources-to-domains",
+    "description": "Add systems, services, messages, data products, and entities to your domains."
+  }
+}
diff --git a/packages/core/docs/development/guides/domains/06-visualize-domains/01-domain-integration-map.md b/packages/core/docs/development/guides/domains/06-visualize-domains/01-domain-integration-map.md
new file mode 100644
index 000000000..9d2fba182
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/06-visualize-domains/01-domain-integration-map.md
@@ -0,0 +1,40 @@
+---
+sidebar_position: 1
+sidebar_class_name: hidden
+keywords:
+    - domain integration map
+    - domains
+sidebar_label: Domain integration map
+title: Domain integration map
+description: Component list for domains 
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.45.0" />
+
+The **GlobalDomain Integration Map** (see [demo](https://demo.eventcatalog.dev/visualiser/domain-integrations)) is a powerful visualization feature in EventCatalog that provides a high-level view of your domains, services and messages. It displays domains containing their services, with cross-domain message flows clearly visualized as connections between domains.
+
+![Example](../../img/domains/domain-integration.png)
+
+This feature is particularly valuable for organizations practicing Domain-Driven Design (DDD) and event-driven architecture, where understanding the interactions between domains is crucial for system design and evolution.
+
+## How it works?
+
+EventCatalog will visualize messages that are being sent between domains in EventCatalog.
+
+As you write domains, services and messages in EventCatalog, some of these communications will be cross domain and boundary.
+This can be intentional or accidental.
+
+Using the Domain Integration Map, you can see these cross-domain communications and understand the dependencies between domains.
+
+
+## How to see the Global Domain Integration Map
+
+To see the Domain integration map, you need at least one domain in your EventCatalog.
+
+1. Click on the **Global Domain Integration Map** section in the navigation bar for any domain in your EventCatalog.
+
+You can a demo of the Domain Integration Map in the [EventCatalog Demo](https://demo.eventcatalog.dev/visualiser/domain-integrations).
+
+
diff --git a/packages/core/docs/development/guides/domains/06-visualize-domains/_category_.json b/packages/core/docs/development/guides/domains/06-visualize-domains/_category_.json
new file mode 100644
index 000000000..7daf4787a
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/06-visualize-domains/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Visualize domains",
+  "position": 6,
+  "className": "hidden",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/domains/visualize-domains",
+    "description": "Visualize domain relationships, integrations, and entities."
+  }
+}
diff --git a/packages/core/docs/development/guides/domains/07-version-domains.md b/packages/core/docs/development/guides/domains/07-version-domains.md
new file mode 100644
index 000000000..79500855d
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/07-version-domains.md
@@ -0,0 +1,39 @@
+---
+keywords:
+- versioning
+- domains
+sidebar_position: 7
+sidebar_class_name: hidden
+sidebar_label: Version domains
+title: Version domains
+description: Learn how to version domains
+---
+
+**All content in EventCatalog can be versioned**.
+
+This allows you to keep historic versions of content which can give context to users why things are changing.
+
+:::tip Tip: Versioning can be great for context
+
+Versioning in EventCatalog is a great way to track changes over time. At any point users using EventCatalog can look back in time and understand what changes have been made to domains, services and messages. This gives extra context that is usually missed.
+
+Example would when new developers come on board, maybe they are interested in a particular domain, maybe they want to understand the history of this domain, where it started and how it came to be what it is today. Versioning allows you to capture this context.
+
+:::
+
+## How to version a domain
+
+1. Create a `/versioned` directory inside the `/domains` folder if one is not created already.
+1. Create a new folder with the version number inside the folder.
+    - Example: `/domains/Orders/versioned/0.0.1`
+1. Copy contents into the new folder, it at least needs your index.mdx file.
+    - Example: `/domains/Orders/versioned/0.0.1/index.mdx`
+    - Note: the version inside this index.mdx file would be `0.0.1`
+1. Bump the version of the `index.mdx` file in the route of the domain.
+    - Example `/domains/Orders/index.mdx`, change the `version` to `0.0.2`
+
+## How to navigate to versions
+
+EventCatalog will automatically create links for you within your latest version of your document. Users will also be able to navigate to any version by adding the version in the url (e.g /docs/domains/Orders/1.0.2 would load the 1.0.2 version of this domain).
+
+![Example](../img/domains/versioned.png)
diff --git a/packages/core/docs/development/guides/domains/08-add-changelog.md b/packages/core/docs/development/guides/domains/08-add-changelog.md
new file mode 100644
index 000000000..021958d6f
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/08-add-changelog.md
@@ -0,0 +1,52 @@
+---
+sidebar_position: 8
+sidebar_class_name: hidden
+keywords:
+    - changelog 
+    - domains
+sidebar_label: Add a changelog
+title: Add a changelog
+description: Adding changelogs to your domains
+---
+
+EventCatalog supports changelogs for [domains](/docs/domains), [services](/docs/development/guides/resources/services/introduction) and [messages](/docs/development/guides/resources/messages/what-are-messages).
+
+When you [version a domain](/docs/development/guides/domains/version-domains) in EventCatalog, you can also attach a `changelog.mdx` to that domain or version.
+
+### Adding a changelog
+
+1. Add a `changelog.mdx` to your domain (or versioned domain)
+    - example `/domains/{Domain}/changelog.mdx`
+    - versioned example `/domains/{Domain}/versioned/1.0.0/changelog.mdx`
+
+**Example**
+```md title="/docs/domains/Orders/changelog.md"
+---
+createdAt: 2024-08-01
+badges:
+    - content: ⭐️ JSON Schema
+      backgroundColor: purple
+      textColor: purple
+---
+
+### Added new service to the domain
+
+Added the Payment service into the domain.
+
+``` 
+
+Navigate to your change log page for your domain (example [/docs/domains/Orders/0.0.2/changelog](https://demo.eventcatalog.dev/docs/domains/Orders/0.0.2/changelog)) or **click on the Changelog button** on your domain page.
+
+:::tip "What do add to your change log?"
+Changelogs are just markdown files, this allows you to add anything you want (e.g code blocks, tables)
+
+EventCatalog code blocks supports diffs, code labels which are great features for changelogs. You can [read more here](/docs/api/code-blocks).
+
+:::
+
+### Why add changelogs?
+
+Changelogs can provide your team with the context behind the reasons and choices for changes within your domain and also be used for auditing purposes.
+
+Changelogs are visualized by EventCatalog.
+
diff --git a/packages/core/docs/development/guides/domains/09-reference.md b/packages/core/docs/development/guides/domains/09-reference.md
new file mode 100644
index 000000000..9859c726d
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/09-reference.md
@@ -0,0 +1,517 @@
+---
+keywords:
+- EventCatalog domains
+- Domain frontmatter
+sidebar_position: 9
+sidebar_label: Reference
+title: Domains reference
+description: Frontmatter fields, paths, and routes for domains in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+This page lists the fields, paths, and routes supported by domains.
+
+## Paths
+
+Domains can be created at the root of the `domains` folder:
+
+```txt
+/domains/{Domain Name}/index.mdx
+```
+
+Subdomains can be created inside a domain:
+
+```txt
+/domains/{Domain Name}/subdomains/{Subdomain Name}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/domains/{domain-id}/{version}` | Domain documentation page. |
+| `/visualiser/domains/{domain-id}/{version}` | Domain resource diagram. |
+| `/visualiser/domains/{domain-id}/{version}/systems-context` | System context map for systems inside a domain. |
+| `/visualiser/domains/{domain-id}/{version}/entity-map` | Entity map for entities inside a domain. |
+
+## Frontmatter example
+
+Domains are Markdown files. They support content, MDX components, and [frontmatter](https://jekyllrb.com/docs/front-matter/).
+
+```md title="/domains/Orders/index.mdx (example)"
+---
+# id of your domain, used for slugs and references in EventCatalog.
+id: Orders
+
+# Display name of the domain, rendered in EventCatalog.
+name: Orders
+
+# Version of the domain.
+version: 0.0.1
+
+# Short summary of your domain.
+summary: |
+  Domain that contains order related information.
+
+# Optional owners, references teams or users.
+owners:
+  - dboyne
+
+# Optional systems. Groups systems into this domain.
+systems:
+  # System id to include in this domain.
+  - id: PaymentProcessingSystem
+    # Optional version of the system. Latest version is used if not provided.
+    version: 1.0.0
+
+# Optional services. Groups services into this domain.
+services:
+  # Service id to include in this domain.
+  - id: PaymentService
+    # Optional version of the service. Latest version is used if not provided.
+    version: 0.0.1
+
+# Optional flows associated with this domain.
+flows:
+  # Flow id to include in this domain.
+  - id: OrderProcessing
+    # Optional version of the flow. Latest version is used if not provided.
+    version: 1.0.0
+
+# Optional messages this domain sends.
+sends:
+  # Message id sent by this domain.
+  - id: OrderCreated
+    # Optional version of the message. Latest version is used if not provided.
+    version: 1.0.0
+
+# Optional messages this domain receives.
+receives:
+  # Message id received by this domain.
+  - id: PaymentInitiated
+    # Optional version of the message. Latest version is used if not provided.
+    version: 1.0.0
+
+# Optional badges, rendered to UI by EventCatalog.
+badges:
+  # Badge text.
+  - content: New domain
+    # Badge background color.
+    backgroundColor: blue
+    # Badge text color.
+    textColor: blue
+    # Optional icon from the supported icon set.
+    icon: BoltIcon
+---
+
+## Overview
+
+Domain that contains all services related to orders.
+
+<NodeGraph />
+```
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the domain. EventCatalog uses this for references and slugs.
+
+```mdx title="Example"
+---
+id: Orders
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Name of the domain. This is used to display the domain name in the UI.
+
+```mdx title="Example"
+---
+name: My orders domain
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the domain.
+
+```mdx title="Example"
+---
+version: 0.0.1
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+Short summary of your domain, shown on domain summary pages.
+
+```mdx title="Example"
+---
+summary: |
+  Domain that contains everything about orders.
+---
+```
+
+### `owners` {#owners}
+
+An array of team or user ids that own the domain.
+
+```mdx title="Example"
+---
+owners:
+  - dboyne
+  - platform-team
+---
+```
+
+### `domains` {#domains}
+
+An array of subdomain ids that belong to this domain.
+
+```md title="Example"
+---
+domains:
+  - id: Payments
+  - id: Shipping
+    # Optional version of the subdomain, latest version is used if not provided.
+    version: 1.0.0
+---
+```
+
+### `systems` {#systems}
+
+<AddedIn version="4.0" />
+
+An array of [system](/docs/development/guides/systems/introduction) ids that belong to this domain.
+
+```md title="Example"
+---
+systems:
+  - id: CheckoutSystem
+  - id: PaymentProcessingSystem
+    # Optional version of the system, latest version is used if not provided.
+    version: 1.0.0
+---
+```
+
+### `services` {#services}
+
+An array of service ids that belong to this domain.
+
+```md title="Example"
+---
+services:
+  - id: InventoryService
+  - id: OrderService
+    # Optional version of the service, latest version is used if not provided.
+    version: 0.0.1
+---
+```
+
+### `agents` {#agents}
+
+<AddedIn version="3.41.0" />
+
+An array of [agent](/docs/development/guides/resources/agents/introduction) ids that belong to this domain.
+
+```md title="Example"
+---
+agents:
+  - id: FraudReviewAgent
+  - id: CustomerSupportAgent
+    # Optional version of the agent, latest version is used if not provided.
+    version: 1.0.0
+---
+```
+
+### `entities` {#entities}
+
+<AddedIn version="2.36.0" />
+
+An array of [entity](/docs/development/guides/resources/entities/introduction) ids that belong to this domain.
+
+```md title="Example"
+---
+entities:
+  - id: Order
+  - id: OrderItem
+    # Optional version of the entity, latest version is used if not provided.
+    version: 0.0.1
+---
+```
+
+### `data-products` {#data-products}
+
+<AddedIn version="3.8.0" />
+
+An array of [data product](/docs/development/guides/resources/data-products/introduction) ids that belong to this domain.
+
+```md title="Example"
+---
+data-products:
+  - id: order-analytics
+  - id: payment-analytics
+    # Optional version of the data product, latest version is used if not provided.
+    version: 1.0.0
+---
+```
+
+### `flows` {#flows}
+
+An array of [flow](/docs/development/guides/resources/flows/introduction) ids that are associated with this domain.
+
+```md title="Example"
+---
+flows:
+  - id: OrderProcessing
+  - id: PaymentFlow
+    # Optional version of the flow, latest version is used if not provided.
+    version: 1.0.0
+---
+```
+
+### `sends` {#sends}
+
+<AddedIn version="3.7.0" />
+
+An array of [message](/docs/development/guides/resources/messages/what-are-messages) ids that this domain sends or publishes.
+
+In Domain-Driven Design these can be classed as domain events, which are events that are published by the domain.
+
+This allows you to document messages at a domain level and have services document them as the implementation of the domain event.
+
+:::tip Where to store these messages?
+
+You can store messages anywhere in your catalog. If you prefer, you can store them in your domain folder.
+
+```md
+domains/
+  Orders/
+    events/
+      OrderCreated/
+        index.mdx
+```
+
+:::
+
+```md title="Example"
+---
+sends:
+  - id: OrderCreated
+  - id: PaymentProcessed
+    # Optional version of the message, latest version is used if not provided.
+    version: 1.0.0
+---
+```
+
+### `receives` {#receives}
+
+<AddedIn version="3.7.0" />
+
+An array of [message](/docs/development/guides/resources/messages/what-are-messages) ids that this domain receives.
+
+These are typically messages that are consumed by your domain from outside its boundary.
+
+```md title="Example"
+---
+receives:
+  - id: PaymentInitiated
+  - id: FraudDetected
+    # Optional version of the message, latest version is used if not provided.
+    version: 0.0.1
+---
+```
+
+### `badges` {#badges}
+
+<AddedIn version="3.39.4" />
+
+An array of badges that get rendered on the page.
+
+```md title="Example"
+---
+badges:
+  - content: My badge
+    backgroundColor: green
+    textColor: green
+    # Optional icon to display from lucide icons.
+    # Or the name of a broker, for example Kafka or EventBridge.
+    icon: BoltIcon
+---
+```
+
+#### Use named colors
+
+Set `backgroundColor` or `textColor` to a named palette token for automatic light and dark mode adaptation.
+
+Supported names: `slate`, `gray`, `zinc`, `neutral`, `stone`, `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`.
+
+```md title="Named color example"
+---
+badges:
+  - content: Critical
+    backgroundColor: red
+    textColor: red
+---
+```
+
+#### Use any CSS color
+
+You can also pass any valid CSS color value directly: hex (`#ff0000`), `rgb()`, `hsl()`, `oklch()`, or a CSS variable (`var(--my-color)`).
+
+```md title="CSS color example"
+---
+badges:
+  - content: Custom
+    backgroundColor: "#6366f1"
+    textColor: "#ffffff"
+---
+```
+
+#### Link to external URLs
+
+<AddedIn version="3.39.6" />
+
+Add a `url` to a badge to make it render as a clickable link with an external-link icon. When `url` is omitted, the badge renders as a plain label.
+
+```md title="Link badge example"
+---
+badges:
+  - content: View Runbook
+    url: https://runbooks.example.com/my-domain
+    backgroundColor: blue
+    textColor: white
+---
+```
+
+### `specifications` {#specifications}
+
+<AddedIn version="2.6.0" />
+
+Specifications to include on the domain page.
+
+<AddedIn version="2.39.1" />
+
+You can assign one or more specifications to a domain.
+
+```mdx title="Example"
+---
+specifications:
+  - type: asyncapi
+    path: order-service-asyncapi.yaml
+    name: AsyncAPI Specification
+  - type: openapi
+    path: openapi.yml
+    name: OpenAPI Specification
+  - type: graphql
+    path: graphql.yml
+    name: GraphQL Specification
+---
+```
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `type` | `string` | Yes | The type of specification. |
+| `path` | `string` | Yes | The path to the specification file. |
+| `name` | `string` | No | Optional friendly name of the specification, rendered in the UI. |
+
+**Older versions of EventCatalog (< 2.39.0)**
+
+If you are using an older version of EventCatalog, use the following syntax.
+
+```mdx title="Example"
+---
+specifications:
+  asyncapiPath: order-service-asyncapi.yaml
+  openapiPath: openapi.yml
+---
+```
+
+### `repository` {#repository}
+
+Repository metadata for the domain.
+
+```mdx title="Example"
+---
+repository:
+  url: https://github.com/event-catalog/eventcatalog
+  language: TypeScript
+---
+```
+
+### `diagrams` {#diagrams}
+
+An array of diagrams associated with the domain.
+
+```mdx title="Example"
+---
+diagrams:
+  - id: orders-context
+    version: 1.0.0
+---
+```
+
+### `visualiser` {#visualiser}
+
+<AddedIn version="2.39.2" />
+
+Turn off the visualiser for this resource. This means the resource will not be included in the visualiser or the navigation bar for the visualiser.
+
+Default: `true`
+
+```mdx title="Example"
+---
+visualiser: false
+---
+```
+
+### `editUrl` {#editUrl}
+
+<AddedIn version="2.49.4" />
+
+Override the default edit URL for the page. This is used to navigate the user to the edit page for the page, for example GitHub or GitLab.
+
+```mdx title="Example"
+---
+editUrl: https://github.com/event-catalog/eventcatalog/edit/main/domains/Orders/index.mdx
+---
+```
+
+### `attachments` {#attachments}
+
+<AddedIn version="2.57.2" />
+
+An array of attachments for this domain.
+
+```mdx title="Example"
+---
+attachments:
+  - url: https://example.com/adr/001
+    title: ADR-001 - Use Kafka for asynchronous messaging
+    description: Learn more about why we chose Kafka for asynchronous messaging in this architecture decision record.
+    type: architecture-decisions
+    icon: FileTextIcon
+  - https://example.com/adr/002
+---
+```
+
+The attachments can be a URL string or an object with additional properties.
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `url` | `string` | Yes | The URL of the attachment. |
+| `title` | `string` | No | The title of the attachment. |
+| `description` | `string` | No | The description of the attachment. |
+| `type` | `string` | No | The type of the attachment, used to group attachments in the UI. |
+| `icon` | `string` | No | The icon of the attachment. You can pick from the [lucide icons](https://lucide.dev/icons/) library. |
diff --git a/packages/core/docs/development/guides/domains/_category_.json b/packages/core/docs/development/guides/domains/_category_.json
new file mode 100644
index 000000000..bec0d2fe8
--- /dev/null
+++ b/packages/core/docs/development/guides/domains/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Domains",
+  "position": 1,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/domains",
+    "description": "A collection of guides to help you understand domains and how they work with EventCatalog."
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/development/guides/owners/01-what-are-teams-and-users.md b/packages/core/docs/development/guides/owners/01-what-are-teams-and-users.md
new file mode 100644
index 000000000..8e413df36
--- /dev/null
+++ b/packages/core/docs/development/guides/owners/01-what-are-teams-and-users.md
@@ -0,0 +1,46 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog teams
+- EventCatalog users
+- owners
+sidebar_label: What are teams & users?
+title: What are teams & users?
+description: Understand how teams and users work in EventCatalog.
+---
+
+Teams and users describe **ownership** in EventCatalog.
+
+You can assign ownership to any resource in EventCatalog.
+
+Teams & users can be manually created or you can [sync them with your existing systems](/docs/development/guides/owners/automated-teams-and-users).
+
+## Teams
+
+A team is a group of users. Teams are useful when ownership belongs to a platform team, product team, domain team, or operating group rather than one person.
+
+Teams live in the `/teams` folder and can reference users in their frontmatter.
+
+![Example team page](../img/teams/example.png)
+
+## Users
+
+A user represents a person in your organization. Users are useful when a specific person owns, maintains, or can answer questions about a resource.
+
+Users live in the `/users` folder and can be assigned directly as owners or added to teams.
+
+![Example user page](../img/users/example.png)
+
+## How ownership works
+
+You can assign teams and users to resources using owner fields in resource frontmatter.
+
+For example, a domain, service, message, or agent can reference a team or user id in its `owners` array. EventCatalog then shows that ownership on the resource page and links back to the team or user.
+
+## Next steps
+
+- [Create a team](/docs/development/guides/owners/create-team)
+- [Create a user](/docs/development/guides/owners/create-user)
+- [Sync teams and users from external systems](/docs/development/guides/owners/automated-teams-and-users)
+- [Review the teams reference](/docs/development/guides/owners/teams-reference)
+- [Review the users reference](/docs/development/guides/owners/users-reference)
diff --git a/packages/core/docs/development/guides/owners/02-create-team.md b/packages/core/docs/development/guides/owners/02-create-team.md
new file mode 100644
index 000000000..ce86f383b
--- /dev/null
+++ b/packages/core/docs/development/guides/owners/02-create-team.md
@@ -0,0 +1,110 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog teams
+sidebar_label: Create a team
+title: Create a team
+description: Create and manage teams within EventCatalog.
+---
+
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+A team represents a group of people that owns, maintains, or can answer questions about parts of your architecture.
+
+![Example team page](../img/teams/example.png)
+
+## Adding a new team
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog team">
+Read https://www.eventcatalog.dev/docs/development/guides/owners/create-team.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/teams.md then help me create a new EventCatalog team in my catalog.
+
+Ask me for the team id, team name, summary, contact email, Slack or Microsoft Teams contact URL if known, and the users that belong to the team. Then create the correct teams/{'{team-id}'}.mdx file with frontmatter and starter markdown.
+
+If users do not exist yet, ask whether to create user files for them too.
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can create the team file, add the right frontmatter, and optionally create user files for team members.
+
+### Manual Creation
+
+Teams live in the `/teams` folder.
+
+Create one `.mdx` file for each team.
+
+<ProjectTree
+  items={[
+    {
+      name: 'teams',
+      type: 'folder',
+      defaultOpen: true,
+      children: [{ name: 'payments-platform.mdx', highlight: true }],
+    },
+  ]}
+/>
+
+## Create the team file
+
+Create a team file with frontmatter and markdown content.
+
+```md title="/teams/payments-platform.mdx"
+---
+# id of the team, used for references from resources
+id: payments-platform
+
+# display name for the team
+name: Payments Platform
+
+# short summary of the team
+summary: Owns payment processing, refunds, and payment platform reliability.
+
+# users that belong to the team
+members:
+  - dboyne
+  - asmith
+
+# optional email address to contact the team
+email: payments@example.com
+
+# optional Slack URL to contact the team
+slackDirectMessageUrl: https://yourteam.slack.com/channels/payments-platform
+---
+
+## Overview
+
+The Payments Platform team owns payment processing, refund workflows, and the operational systems that support payments across the organization.
+```
+
+Once the file is added, the team appears in EventCatalog and can be referenced by resources.
+
+## Add team members
+
+Team members reference users by id. User files live in the `/users` folder.
+
+<ProjectTree
+  items={[
+    {
+      name: 'users',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        { name: 'dboyne.mdx', highlight: true },
+        { name: 'asmith.mdx', highlight: true },
+      ],
+    },
+    {
+      name: 'teams',
+      type: 'folder',
+      defaultOpen: true,
+      children: [{ name: 'payments-platform.mdx', highlight: true }],
+    },
+  ]}
+/>
+
+## Next steps
+
+- [Create a user](/docs/development/guides/owners/create-user)
+- [Review the teams reference](/docs/development/guides/owners/teams-reference)
+- [Sync teams from external systems](/docs/development/guides/owners/automated-teams-and-users)
diff --git a/packages/core/docs/development/guides/owners/03-create-user.md b/packages/core/docs/development/guides/owners/03-create-user.md
new file mode 100644
index 000000000..9fd9bbdb4
--- /dev/null
+++ b/packages/core/docs/development/guides/owners/03-create-user.md
@@ -0,0 +1,99 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog users
+sidebar_label: Create a user
+title: Create a user
+description: Create and manage users within EventCatalog.
+---
+
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+A user represents a person who owns, maintains, or can answer questions about resources in your architecture.
+
+![Example user page](../img/users/example.png)
+
+## Adding a new user
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog user">
+Read https://www.eventcatalog.dev/docs/development/guides/owners/create-user.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/users.md then help me create a new EventCatalog user in my catalog.
+
+Ask me for the user id, name, role, email, avatar URL if known, Slack or Microsoft Teams contact URL if known, and any teams they belong to. Then create the correct users/{'{user-id}'}.mdx file with frontmatter and starter markdown.
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can create the user file and add the right ownership/contact metadata.
+
+### Manual Creation
+
+Users live in the `/users` folder.
+
+Create one `.mdx` file for each user.
+
+<ProjectTree
+  items={[
+    {
+      name: 'users',
+      type: 'folder',
+      defaultOpen: true,
+      children: [{ name: 'dboyne.mdx', highlight: true }],
+    },
+  ]}
+/>
+
+## Create the user file
+
+Create a user file with frontmatter and markdown content.
+
+```md title="/users/dboyne.mdx"
+---
+# id of the user, used for references from resources
+id: dboyne
+
+# display name for the user
+name: David Boyne
+
+# optional URL path for a profile image
+avatarUrl: https://github.com/dboyne.png
+
+# user's role in the company
+role: Lead developer
+
+# optional user email address
+email: david@example.com
+
+# optional Slack URL to contact the user
+slackDirectMessageUrl: https://yourteam.slack.com/team/dboyne
+
+# optional teams this user belongs to
+associatedTeams:
+  - payments-platform
+---
+
+## Overview
+
+David works on platform architecture and helps teams document their event-driven systems.
+```
+
+Once the file is added, the user appears in EventCatalog and can be referenced by resources or teams.
+
+## Add users to teams
+
+Teams can reference users in their `members` array:
+
+```md title="/teams/payments-platform.mdx"
+---
+id: payments-platform
+name: Payments Platform
+members:
+  - dboyne
+---
+```
+
+## Next steps
+
+- [Create a team](/docs/development/guides/owners/create-team)
+- [Review the users reference](/docs/development/guides/owners/users-reference)
+- [Sync users from external systems](/docs/development/guides/owners/automated-teams-and-users)
diff --git a/packages/core/docs/development/guides/owners/05-teams-reference.md b/packages/core/docs/development/guides/owners/05-teams-reference.md
new file mode 100644
index 000000000..41e2550e4
--- /dev/null
+++ b/packages/core/docs/development/guides/owners/05-teams-reference.md
@@ -0,0 +1,144 @@
+---
+keywords:
+- EventCatalog teams
+- Team frontmatter
+sidebar_position: 4
+sidebar_label: Teams reference
+title: Teams reference
+description: Frontmatter fields and paths for teams in EventCatalog.
+---
+
+This page lists the fields and paths supported by teams.
+
+## Paths
+
+Teams are created in the `teams` folder:
+
+```txt
+/teams/{team-id}.mdx
+```
+
+Teams can also be synced from directory sources such as GitHub or Microsoft Entra.
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/teams/{team-id}` | Team documentation page. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the team. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: payments-platform
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the team.
+
+```md title="Example"
+---
+name: Payments Platform
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short description of the team.
+
+```md title="Example"
+---
+summary: Owns payment processing and refund workflows.
+---
+```
+
+### `email` {#email}
+
+- Type: `string`
+
+Team email address.
+
+```md title="Example"
+---
+email: payments@example.com
+---
+```
+
+### `hidden` {#hidden}
+
+- Type: `boolean`
+
+Hide the team from generated lists.
+
+```md title="Example"
+---
+hidden: true
+---
+```
+
+### `slackDirectMessageUrl` {#slackDirectMessageUrl}
+
+- Type: `string`
+
+Slack URL for contacting the team.
+
+```md title="Example"
+---
+slackDirectMessageUrl: https://slack.example.com/team/payments
+---
+```
+
+### `msTeamsDirectMessageUrl` {#msTeamsDirectMessageUrl}
+
+- Type: `string`
+
+Microsoft Teams URL for contacting the team.
+
+```md title="Example"
+---
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/channel/example
+---
+```
+
+### `members` {#members}
+
+- Type: `array`
+
+Users that belong to the team.
+
+```md title="Example"
+---
+members:
+  - dboyne
+---
+```
+
+## Example
+
+```md
+---
+id: payments-platform
+name: Payments Platform
+summary: Owns payment processing and refund workflows.
+members:
+  - dboyne
+ownedServices:
+  - payment-api
+ownedEvents:
+  - PaymentAuthorized
+---
+```
diff --git a/packages/core/docs/development/guides/owners/06-users-reference.md b/packages/core/docs/development/guides/owners/06-users-reference.md
new file mode 100644
index 000000000..e3eaec63c
--- /dev/null
+++ b/packages/core/docs/development/guides/owners/06-users-reference.md
@@ -0,0 +1,128 @@
+---
+keywords:
+- EventCatalog users
+- User frontmatter
+sidebar_position: 5
+sidebar_label: Users reference
+title: Users reference
+description: Frontmatter fields and paths for users in EventCatalog.
+---
+
+This page lists the fields and paths supported by users.
+
+## Paths
+
+Users are created in the `users` folder:
+
+```txt
+/users/{user-id}.mdx
+```
+
+Users can also be synced from directory sources such as GitHub or Microsoft Entra.
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/users/{user-id}` | User documentation page. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the user. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: dboyne
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the user.
+
+```md title="Example"
+---
+name: David Boyne
+---
+```
+
+## Optional fields
+
+### `avatarUrl` {#avatarUrl}
+
+- Type: `string`
+
+Avatar URL for the user.
+
+```md title="Example"
+---
+avatarUrl: https://github.com/dboyne.png
+---
+```
+
+### `role` {#role}
+
+- Type: `string`
+
+User role or title.
+
+```md title="Example"
+---
+role: Staff Engineer
+---
+```
+
+### `email` {#email}
+
+- Type: `string`
+
+User email address.
+
+```md title="Example"
+---
+email: david@example.com
+---
+```
+
+### `hidden` {#hidden}
+
+- Type: `boolean`
+
+Hide the user from generated lists.
+
+```md title="Example"
+---
+hidden: true
+---
+```
+
+### `slackDirectMessageUrl` {#slackDirectMessageUrl}
+
+- Type: `string`
+
+Slack direct message URL.
+
+```md title="Example"
+---
+slackDirectMessageUrl: https://slack.example.com/team/dboyne
+---
+```
+
+### `msTeamsDirectMessageUrl` {#msTeamsDirectMessageUrl}
+
+- Type: `string`
+
+Microsoft Teams direct message URL.
+
+```md title="Example"
+---
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/example
+---
+```
+
diff --git a/packages/core/docs/development/guides/owners/_category_.json b/packages/core/docs/development/guides/owners/_category_.json
new file mode 100644
index 000000000..27b5a0e32
--- /dev/null
+++ b/packages/core/docs/development/guides/owners/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Teams & Users",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/owners",
+    "description": "A collection of guides to help you understand owners and how they work with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/owners/automated-teams-and-users/_category_.json b/packages/core/docs/development/guides/owners/automated-teams-and-users/_category_.json
new file mode 100644
index 000000000..c2476a96b
--- /dev/null
+++ b/packages/core/docs/development/guides/owners/automated-teams-and-users/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Automated teams and users",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development/guides/owners/automated-teams-and-users",
+    "description": "A collection of guides to help you sync teams and users into EventCatalog from external systems."
+  }
+}
diff --git a/packages/core/docs/development/guides/owners/automated-teams-and-users/create-your-own-connector.md b/packages/core/docs/development/guides/owners/automated-teams-and-users/create-your-own-connector.md
new file mode 100644
index 000000000..25523d553
--- /dev/null
+++ b/packages/core/docs/development/guides/owners/automated-teams-and-users/create-your-own-connector.md
@@ -0,0 +1,108 @@
+---
+sidebar_position: 3
+slug: /development/guides/owners/create-your-own-connector
+keywords:
+- EventCatalog custom directory connector
+- defineDirectorySource
+sidebar_label: Create your own connector
+title: Create your own connector
+description: Build a custom directory connector to sync users and teams from any provider.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+<AddedIn version="3.44.0" pkg="@eventcatalog/connectors" />
+
+Connectors are how EventCatalog imports and syncs users and teams from an external source so you can assign them as owners on resources in your catalog. EventCatalog ships with built-in connectors (such as [Sync from GitHub](/docs/development/guides/owners/sync-from-github) and [Sync from Microsoft Entra ID](/docs/development/guides/owners/sync-from-microsoft-entra)), but if your team uses a different system &mdash; an internal HR tool, an LDAP directory, a SaaS like Okta, or anything else &mdash; you can write your own connector with a small amount of custom code.
+
+A custom connector is a JavaScript function you define that returns a list of users and teams. EventCatalog runs it on startup and treats the results the same as any other connector. You build it using `defineDirectorySource` from `@eventcatalog/connectors` and register it in the same `directory.sources` array used by the built-in connectors.
+
+```mermaid
+flowchart LR
+    SRC[Your source<br/>e.g. LDAP, Okta, HR tool] --> C[Your custom connector]
+    C --> EC[EventCatalog]
+    EC --> U[Users & Teams]
+```
+
+## Build a connector
+
+A connector is an object with a `type`, a `name`, and at least one of `loadUsers` or `loadTeams`:
+
+```js title="connectors/company-directory.js"
+import { defineDirectorySource } from '@eventcatalog/connectors';
+
+export const companyDirectory = defineDirectorySource({
+  type: 'directory',
+  name: 'company-directory',
+
+  async loadTeams() {
+    // Call your external API here (e.g. LDAP, Okta, your HR system)
+    // and return the teams in the shape below.
+    return [
+      {
+        id: 'platform',
+        name: 'Platform',
+        summary: 'Platform engineering team.',
+        members: ['alice'],
+        source: {
+          provider: 'company-directory',
+        },
+      },
+    ];
+  },
+
+  async loadUsers() {
+    // Call your external API here to fetch users
+    // and return them in the shape below.
+    return [
+      {
+        id: 'alice',
+        name: 'Alice',
+        avatarUrl: 'https://example.com/alice.png',
+        source: {
+          provider: 'company-directory',
+        },
+      },
+    ];
+  },
+});
+```
+
+Register it in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+import { companyDirectory } from './connectors/company-directory.js';
+
+export default {
+  // ... rest of config
+  directory: {
+    sources: [companyDirectory],
+  },
+};
+```
+
+## User shape
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | Yes | Unique identifier. Matches the `id` used to reference the user as an owner. |
+| `name` | `string` | Yes | Display name. |
+| `avatarUrl` | `string` | No | URL to a profile image. |
+| `role` | `string` | No | Job title or role description. |
+| `email` | `string` | No | Contact email address. |
+| `markdown` | `string` | No | Markdown body rendered on the user's page. |
+| `source` | `object` | No | Provider metadata. The `provider` field is used for the source badge in the UI. |
+
+## Team shape
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | Yes | Unique identifier. Matches the `id` used to reference the team as an owner. |
+| `name` | `string` | Yes | Display name. |
+| `summary` | `string` | No | Short description. |
+| `members` | `string[]` | No | List of user `id` values who belong to the team. |
+| `email` | `string` | No | Contact email address. |
+| `markdown` | `string` | No | Markdown body rendered on the team's page. |
+| `source` | `object` | No | Provider metadata. The `provider` field is used for the source badge in the UI. |
diff --git a/packages/core/docs/development/guides/owners/automated-teams-and-users/sync-from-github.md b/packages/core/docs/development/guides/owners/automated-teams-and-users/sync-from-github.md
new file mode 100644
index 000000000..3be4ab2b2
--- /dev/null
+++ b/packages/core/docs/development/guides/owners/automated-teams-and-users/sync-from-github.md
@@ -0,0 +1,156 @@
+---
+sidebar_position: 1
+slug: /development/guides/owners/sync-from-github
+keywords:
+- EventCatalog GitHub connector
+- sync GitHub teams users
+- directory connector
+sidebar_label: Sync from GitHub
+title: Sync from GitHub
+description: Sync GitHub organization teams and members into EventCatalog as users and teams.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+In EventCatalog, you can import and sync your users and teams directly from GitHub. Instead of adding people and teams by hand, you point EventCatalog at your GitHub organization and the catalog stays in sync with it automatically. Once synced, your GitHub teams and users can be assigned as owners on any resource in the catalog (services, events, domains, and more).
+
+```mermaid
+flowchart LR
+    GH[GitHub org] --> C[GitHub connector]
+    C --> EC[EventCatalog]
+    EC --> U[Users & Teams]
+```
+
+## Why sync from GitHub
+
+Teams and users in EventCatalog are used to assign ownership to resources such as services, events, and domains. Keeping that ownership data accurate requires the user and team lists to reflect who actually works on each system. Syncing from GitHub automates that by pulling the data from an org you already manage.
+
+## How it works
+
+When EventCatalog starts, the connector fetches users and teams from GitHub. They appear in the catalog alongside any users and teams you have defined locally, and each synced entry is marked as read-only with a link back to the source record on GitHub.
+
+## Install
+
+```bash
+npm install @eventcatalog/connectors
+```
+
+## Configure
+
+Import `githubDirectory` and add it to the `directory.sources` array in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+import { githubDirectory } from '@eventcatalog/connectors';
+
+export default {
+  // ... rest of config
+  directory: {
+    sources: [
+      githubDirectory({
+        org: 'your-org',
+        token: process.env.GITHUB_TOKEN,
+        teams: ['platform', 'architecture'],
+        users: true,
+      }),
+    ],
+  },
+};
+```
+
+## Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `org` | `string` | Yes | GitHub organization slug. |
+| `teams` | `string[]` | Yes | One or more team slugs to sync. At least one is required. |
+| `token` | `string` | No | Personal access token or GitHub App installation token. Required for private organizations and to avoid rate limits. |
+| `users` | `boolean` | No | When `true` (default), members of every synced team are also synced as users. Set to `false` to sync teams only. |
+| `baseUrl` | `string` | No | Override the GitHub API base URL. Useful for GitHub Enterprise Server instances. |
+
+## GitHub token
+
+Pass a token via an environment variable so it is never committed to source control:
+
+```bash
+GITHUB_TOKEN=ghp_yourtoken npx eventcatalog dev
+```
+
+The token needs the following permissions:
+
+- `read:org` - to read teams and their members in the organization.
+
+For public organizations the connector works without a token, but GitHub rate limits unauthenticated requests to 60 per hour.
+
+## What gets synced
+
+### Teams
+
+Each team slug listed in the `teams` option is fetched from the GitHub API. The connector creates a team entry with:
+
+- `id` set to the team slug.
+- `name` taken from the GitHub team display name.
+- `summary` taken from the GitHub team description.
+- A read-only note linking back to the team on GitHub.
+
+### Users
+
+When `users` is `true`, every member of each synced team is fetched and created as a user entry with:
+
+- `id` set to the GitHub username (login).
+- `name` set to the GitHub username.
+- `avatarUrl` set to the GitHub avatar URL.
+- A read-only note linking back to the user's GitHub profile.
+
+A user who belongs to multiple synced teams is only written once.
+
+## Use synced owners
+
+Synced teams and users behave identically to hand-authored ones. Reference them by their `id` in any resource frontmatter:
+
+```yaml title="services/order-service/index.md"
+---
+id: OrderService
+name: Order Service
+owners:
+  - platform
+  - jsmith
+---
+```
+
+## Conflict strategy
+
+When a locally authored user or team shares the same `id` as one returned by the connector, EventCatalog uses the `conflictStrategy` setting to decide what to do.
+
+| Strategy | Behaviour |
+|---|---|
+| `local-wins` (default) | The local file is kept and the external entry is skipped. |
+| `source-wins` | The external entry overwrites the local file. |
+| `error` | EventCatalog throws an error and stops the build. |
+
+Configure the strategy in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+export default {
+  // ... rest of config
+  directory: {
+    conflictStrategy: 'local-wins',
+    sources: [ /* ... */ ],
+  },
+};
+```
+
+## GitHub Enterprise Server
+
+Set the `baseUrl` option to your GHES API endpoint:
+
+```js
+githubDirectory({
+  org: 'your-org',
+  token: process.env.GITHUB_TOKEN,
+  teams: ['platform'],
+  baseUrl: 'https://github.example.com/api/v3',
+})
+```
diff --git a/packages/core/docs/development/guides/owners/automated-teams-and-users/sync-from-microsoft-entra.md b/packages/core/docs/development/guides/owners/automated-teams-and-users/sync-from-microsoft-entra.md
new file mode 100644
index 000000000..41ac74f9b
--- /dev/null
+++ b/packages/core/docs/development/guides/owners/automated-teams-and-users/sync-from-microsoft-entra.md
@@ -0,0 +1,253 @@
+---
+sidebar_position: 2
+slug: /development/guides/owners/sync-from-microsoft-entra
+keywords:
+- EventCatalog Microsoft Entra connector
+- sync Microsoft Entra teams users
+- sync Azure AD groups users
+- directory connector
+sidebar_label: Sync from Microsoft Entra ID
+title: Sync from Microsoft Entra ID
+description: Sync Microsoft Entra ID groups and direct members into EventCatalog as teams and users.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+<AddedIn version="3.45.0" pkg="@eventcatalog/connectors" />
+
+In EventCatalog, you can import and sync your users and teams directly from Microsoft Entra ID. Instead of adding people and teams by hand, you point EventCatalog at selected Entra groups and the catalog keeps those teams and their direct members in sync.
+
+```mermaid
+flowchart LR
+    E[Microsoft Entra ID] --> C[Microsoft Entra connector]
+    C --> EC[EventCatalog]
+    EC --> U[Users & Teams]
+```
+
+## Why sync from Microsoft Entra ID
+
+Teams and users in EventCatalog are used to assign ownership to resources such as services, events, domains, and more. Many organizations already manage team membership in Microsoft Entra ID. Syncing from Entra keeps ownership data aligned with the directory your organization already maintains.
+
+## How it works
+
+When EventCatalog starts, the connector fetches the configured Entra groups from Microsoft Graph. Each selected group becomes an EventCatalog team, and each direct enabled user member becomes an EventCatalog user.
+
+Synced teams and users appear alongside locally authored users and teams. Each synced entry is marked as read-only and surfaced in directory source badges so people know the source of truth is Microsoft Entra ID.
+
+## Install
+
+```bash
+npm install @eventcatalog/connectors
+```
+
+## Configure
+
+Import `microsoftEntraDirectory` and add it to the `directory.sources` array in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+import { microsoftEntraDirectory } from '@eventcatalog/connectors';
+
+export default {
+  // ... rest of config
+  directory: {
+    sources: [
+      microsoftEntraDirectory({
+        // Directory (tenant) ID from your Microsoft Entra app registration.
+        tenantId: process.env.AZURE_TENANT_ID,
+
+        // Application (client) ID from your Microsoft Entra app registration.
+        clientId: process.env.AZURE_CLIENT_ID,
+
+        // Client secret value from Certificates & secrets.
+        // Use the secret value, not the secret ID.
+        clientSecret: process.env.AZURE_CLIENT_SECRET,
+
+        // Entra groups to sync into EventCatalog as teams.
+        groups: [
+          {
+            // Stable Entra group Object ID. Recommended because it is unique and does not change if the group is renamed.
+            id: '00000000-0000-0000-0000-000000000000',
+
+            // Optional EventCatalog team id. If omitted, the connector slugifies the Entra group display name.
+            alias: 'platform',
+          },
+          {
+            // You can also sync by exact display name. If more than one group matches, use the group Object ID instead.
+            displayName: 'Architecture Guild',
+          },
+        ],
+      }),
+    ],
+  },
+};
+```
+
+## Microsoft Entra app registration
+
+The connector uses Microsoft Graph with the OAuth client credentials flow.
+
+1. In Azure Portal, open **Microsoft Entra ID**.
+2. Go to **App registrations** and create a new app registration.
+3. Copy the **Directory (tenant) ID** into `AZURE_TENANT_ID`.
+4. Copy the **Application (client) ID** into `AZURE_CLIENT_ID`.
+5. Go to **Certificates & secrets** and create a new client secret.
+6. Copy the secret **Value** into `AZURE_CLIENT_SECRET`. You do not need the secret ID.
+7. Go to **API permissions** and add these Microsoft Graph **Application permissions**:
+   - `Group.Read.All` - read the configured groups.
+   - `GroupMember.Read.All` - read direct members of the configured groups.
+   - `User.Read.All` - read user profile fields for synced members.
+8. Grant admin consent for the permissions.
+
+Pass the credentials with environment variables:
+
+```bash
+AZURE_TENANT_ID=00000000-0000-0000-0000-000000000000 \
+AZURE_CLIENT_ID=00000000-0000-0000-0000-000000000000 \
+AZURE_CLIENT_SECRET=your-secret-value \
+npx eventcatalog dev
+```
+
+## Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `tenantId` | `string` | Yes | Microsoft Entra tenant ID. |
+| `clientId` | `string` | Yes | Application/client ID for the app registration. |
+| `clientSecret` | `string` | Yes | Client secret value for the app registration. |
+| `groups` | `(string \| { id: string; alias?: string } \| { displayName: string; alias?: string })[]` | Yes | Entra groups to sync. Group IDs are recommended. |
+| `users` | `boolean` | No | When `true` (default), direct members of every synced group are also synced as users. Set to `false` to sync teams only. |
+| `includeDisabledUsers` | `boolean` | No | Disabled users are excluded by default. Set to `true` to include them. |
+| `graphBaseUrl` | `string` | No | Override the Microsoft Graph base URL. Defaults to `https://graph.microsoft.com/v1.0`. Useful for sovereign cloud environments. |
+| `tokenUrl` | `string` | No | Override the OAuth token URL. Defaults to `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`. Useful for sovereign cloud environments. |
+
+## Selecting groups
+
+Groups can be configured by stable group ID:
+
+```js
+microsoftEntraDirectory({
+  tenantId: process.env.AZURE_TENANT_ID,
+  clientId: process.env.AZURE_CLIENT_ID,
+  clientSecret: process.env.AZURE_CLIENT_SECRET,
+  groups: [
+    {
+      // Stable Entra group Object ID. Recommended because it is unique and does not change if the group is renamed.
+      id: 'e3d11d65-178c-45ff-a9e0-a1d4b74006ff',
+
+      // Optional EventCatalog team id. Use this in owner frontmatter, for example `owners: ['platform-engineering']`.
+      alias: 'platform-engineering',
+    },
+  ],
+});
+```
+
+You can also configure a group by exact display name:
+
+```js
+microsoftEntraDirectory({
+  tenantId: process.env.AZURE_TENANT_ID,
+  clientId: process.env.AZURE_CLIENT_ID,
+  clientSecret: process.env.AZURE_CLIENT_SECRET,
+  groups: [
+    {
+      // Exact Entra group display name. If more than one group has this name, use the group Object ID instead.
+      displayName: 'Platform Engineering',
+
+      // Optional EventCatalog team id. If omitted, the connector slugifies the display name.
+      alias: 'platform-engineering',
+    },
+  ],
+});
+```
+
+Group IDs are recommended because they are stable and unique. If a `displayName` lookup finds no groups or more than one group, EventCatalog stops the build and asks you to use the group ID instead.
+
+## What gets synced
+
+### Teams
+
+Each configured Entra group creates a team entry with:
+
+- `id` set to `alias` when provided, otherwise a slugified version of the Entra group display name.
+- `name` taken from the Entra group display name.
+- `summary` taken from the Entra group description.
+- `email` taken from the Entra group mail address when available.
+- `source.provider` set to `microsoft-entra`.
+- `source.id` set to the Entra group object ID.
+- A read-only note explaining the team is managed in Microsoft Entra ID.
+
+### Users
+
+Users are synced only from the configured groups. When `users` is `true`, every direct enabled user member of each synced group is fetched and created as a user entry with:
+
+- `id` set to the user's mail address when available.
+- Guest user principal names such as `name_example.com#EXT#@tenant.onmicrosoft.com` normalized back to `name@example.com` when no mail address is available.
+- `id` set to the user's user principal name when no mail address is available and the user is not a guest account.
+- `id` set to the Microsoft Graph user object ID when no mail address or user principal name is available.
+- `name` taken from the Entra user display name.
+- `email` taken from the user's mail address or user principal name.
+- `role` taken from the user's job title.
+- `source.provider` set to `microsoft-entra`.
+- `source.id` set to the Entra user object ID.
+- A read-only note explaining the user is managed in Microsoft Entra ID.
+
+Profile photos are not fetched. User avatars are optional in EventCatalog.
+
+:::info Direct members only
+
+The connector syncs direct user members of the configured groups. It does not expand nested groups or transitive membership in this version.
+
+:::
+
+## Use synced owners
+
+Synced teams and users behave identically to hand-authored ones. Reference them by their `id` in any resource frontmatter:
+
+```yaml title="services/order-service/index.md"
+---
+id: OrderService
+name: Order Service
+owners:
+  - platform-engineering
+  - dave@eventcatalog.dev
+---
+```
+
+## Conflict strategy
+
+When a locally authored user or team shares the same `id` as one returned by the connector, EventCatalog uses the `conflictStrategy` setting to decide what to do.
+
+| Strategy | Behaviour |
+|---|---|
+| `local-wins` (default) | The local file is kept and the external entry is skipped. |
+| `source-wins` | The external entry overwrites the local file. |
+| `error` | EventCatalog throws an error and stops the build. |
+
+Configure the strategy in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+export default {
+  // ... rest of config
+  directory: {
+    conflictStrategy: 'local-wins',
+    sources: [ /* ... */ ],
+  },
+};
+```
+
+## Sovereign cloud endpoints
+
+For sovereign cloud environments, override the Graph and token endpoints:
+
+```js
+microsoftEntraDirectory({
+  tenantId: process.env.AZURE_TENANT_ID,
+  clientId: process.env.AZURE_CLIENT_ID,
+  clientSecret: process.env.AZURE_CLIENT_SECRET,
+  groups: [{ id: '00000000-0000-0000-0000-000000000000' }],
+  graphBaseUrl: 'https://graph.microsoft.com/v1.0',
+  tokenUrl: 'https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token',
+});
+```
diff --git a/packages/core/docs/development/guides/resources/_category_.json b/packages/core/docs/development/guides/resources/_category_.json
new file mode 100644
index 000000000..e802cb775
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Resources",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources",
+    "description": "Guides for documenting EventCatalog resources such as services, messages, schemas, data stores, data products, entities, agents, flows, and architecture decision records."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/adrs/01-introduction.md b/packages/core/docs/development/guides/resources/adrs/01-introduction.md
new file mode 100644
index 000000000..afac80e0a
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/adrs/01-introduction.md
@@ -0,0 +1,37 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog ADR
+- architecture decision records
+- ADR documentation
+sidebar_label: What are ADRs?
+title: What are architecture decision records?
+description: Document and govern architectural choices alongside your catalog resources.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+[Architecture decision records (ADRs)](https://adr.github.io/) capture why your team made a particular design choice. In EventCatalog, ADRs are first-class resources that live alongside services, events, domains, and flows.
+
+Architectural choices are often made once and then forgotten. When a new engineer joins or a design is revisited months later, the reasoning behind past decisions is usually lost.
+
+Documenting ADRs in your catalog gives your team:
+
+- **Context** — anyone can see what alternatives were considered and why a particular path was chosen.
+- **Traceability** — decisions are linked directly to the services, events, domains, and flows they affect via `appliesTo`.
+- **Lifecycle tracking** — each ADR has a status (`proposed`, `accepted`, `rejected`, `deprecated`, `superseded`) so it is clear which decisions are still in force.
+- **AI-ready context** — because ADRs sit alongside the resources they govern, the [EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/introduction) can surface the *why* behind your architecture to AI assistants, not just the *what*. When an LLM is reasoning about a service or event, it picks up the decisions, trade-offs, and constraints recorded in your ADRs.
+
+## Lifecycle statuses
+
+Every ADR must declare a `status` field. The available values are:
+
+| Status | Meaning |
+| --- | --- |
+| `proposed` | Under discussion, not yet accepted |
+| `accepted` | In force |
+| `rejected` | Considered and deliberately not adopted |
+| `deprecated` | Was accepted but is being phased out |
+| `superseded` | Replaced by a newer decision |
+
+EventCatalog renders a colored badge for each status and shows a warning banner on `deprecated` and `superseded` pages so readers are directed to the current decision.
diff --git a/packages/core/docs/development/guides/resources/adrs/02-creating-adrs.md b/packages/core/docs/development/guides/resources/adrs/02-creating-adrs.md
new file mode 100644
index 000000000..2411e535e
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/adrs/02-creating-adrs.md
@@ -0,0 +1,211 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog ADR
+- create architecture decision records
+sidebar_label: Create an ADR
+title: Create an ADR
+description: Add architecture decision records to your catalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+[Architecture decision records (ADRs)](https://adr.github.io/) capture why your team made a particular design choice and can be rendered and assigned to resources in EventCatalog.
+
+![Architecture decision record page in EventCatalog](./img/adr-overview.png)
+
+## Creating an ADR
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog ADR">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/adrs/creating-adrs.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/adrs.md then help me create a new EventCatalog architecture decision record in my catalog.
+
+Ask me for the decision title, context, decision, consequences, status, date, version, whether it belongs at the root of the catalog or inside a domain or system, and any resources it applies to. Then create the correct adrs/{'{ADR Name}'}/index.mdx, domains/{'{Domain Name}'}/adrs/{'{ADR Name}'}/index.mdx, or systems/{'{System Name}'}/adrs/{'{ADR Name}'}/index.mdx file with frontmatter and starter markdown.
+
+If I do not know the status, use proposed. If I do not provide a date, use today's date. If the ADR affects existing resources, add them to appliesTo.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the ADR should live, create the right folder structure, and write the first draft of the decision record.
+
+### Manual Creation
+
+ADRs live in an `adrs` folder. EventCatalog discovers any `index.mdx` file inside an `adrs` directory, regardless of where that directory lives in your catalog.
+
+You can place ADRs:
+
+At the root of your catalog:
+
+<ProjectTree
+  items={[
+    {
+      name: 'adrs',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'choose-kafka',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a domain:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'adrs',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'event-driven-orders',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+ADRs can also live inside a system folder when the decision is specific to that system.
+
+## Create the ADR file
+
+Create an `index.mdx` file for the ADR.
+
+Here is a minimal ADR with all required fields.
+
+```md title="adrs/choose-kafka/index.mdx"
+---
+# Unique identifier for the ADR. Used for URLs and references.
+id: choose-kafka
+
+# Display name rendered in EventCatalog.
+name: Choose Kafka for domain event distribution
+
+# Version of the ADR.
+version: 1.0.0
+
+# Current lifecycle status: proposed, accepted, rejected, deprecated, or superseded.
+status: accepted
+
+# Date the decision was made or proposed.
+date: 2026-05-26
+---
+
+## Context
+
+Services need a reliable backbone for cross-domain event distribution.
+
+## Decision
+
+We will use Apache Kafka as the primary event bus for inter-domain communication.
+
+## Consequences
+
+Teams gain reliable, ordered delivery with replay support. They also take on operational responsibility for the Kafka cluster.
+```
+
+## Add optional fields
+
+Enrich the ADR with owners, decision makers, links to affected resources, and badges.
+
+```md title="adrs/choose-kafka/index.mdx"
+---
+# Unique identifier for the ADR. Used for URLs and references.
+id: choose-kafka
+
+# Display name rendered in EventCatalog.
+name: Choose Kafka for domain event distribution
+
+# Short summary shown in lists and page headers.
+summary: Kafka is the primary backbone for inter-domain event distribution.
+
+# Version of the ADR.
+version: 1.0.0
+
+# Current lifecycle status: proposed, accepted, rejected, deprecated, or superseded.
+status: accepted
+
+# Date the decision was made or proposed.
+date: 2026-05-26
+
+# Optional owners. References team or user ids.
+owners:
+  - platform-team
+
+# Optional decision makers. References team or user ids.
+decisionMakers:
+  - architecture-board
+
+# Optional resources affected by this decision.
+appliesTo:
+  - type: domain
+    id: Orders
+  - type: service
+    id: PaymentService
+  - type: event
+    id: PaymentAccepted
+
+# Optional badges rendered on the ADR page.
+badges:
+  - content: Messaging
+    backgroundColor: blue
+    textColor: blue
+---
+
+## Context
+
+...
+
+## Decision
+
+...
+
+## Consequences
+
+...
+```
+
+## Recommended body structure
+
+EventCatalog does not enforce a particular body format, but the classic ADR structure works well.
+
+**Context** — the situation or problem that prompted the decision.
+
+**Decision** — the choice that was made and the reasoning behind it.
+
+**Consequences** — what happens as a result, both positive and negative.
+
+You can use any markdown content here including headings, tables, code blocks, and MDX components.
+
+## Next steps
+
+- [Link decisions to resources](/docs/development/guides/resources/adrs/linking-resources)
+- [Model relationships between decisions](/docs/development/guides/resources/adrs/relationships)
+- [Architecture decision records reference](/docs/development/guides/resources/adrs/reference)
diff --git a/packages/core/docs/development/guides/resources/adrs/03-linking-resources.md b/packages/core/docs/development/guides/resources/adrs/03-linking-resources.md
new file mode 100644
index 000000000..5f10a2504
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/adrs/03-linking-resources.md
@@ -0,0 +1,52 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog ADR
+- link ADR to resources
+sidebar_label: Add ADRs to resources
+title: Add ADRs to resources
+description: Connect decisions to the services, events, and domains they affect.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Use `appliesTo` to connect an ADR to the catalog resources it affects. When resources are linked, the ADR appears in the **Decision Records** section of each resource's sidebar.
+
+![Decision Records section on a resource sidebar listing linked ADRs](./img/linked-adr-document.png)
+
+## Use `appliesTo`
+
+Add an `appliesTo` array to the frontmatter, specifying the `type` and `id` of each affected resource.
+
+```yaml title="adrs/choose-kafka/index.mdx"
+appliesTo:
+  #  ADR will apply to the Orders Domain
+  - type: domain
+    id: Orders
+  # ADR will apply to the PaymentService
+  - type: service
+    id: PaymentService
+  # ADR will apply to the PaymentAccepted event
+  - type: event
+    id: PaymentAccepted
+```
+
+## Pin to a specific version
+
+By default, EventCatalog resolves the link to the latest version of the resource. Add a `version` field to pin to a specific version.
+
+```yaml
+appliesTo:
+  - type: service
+    id: PaymentService
+    version: 1.0.0
+  - type: event
+    id: OrderConfirmed
+    version: latest   # explicit, same as omitting version
+```
+
+## How it appears in the UI
+
+When a resource has one or more ADRs linked via `appliesTo`, a **Decision Records** group appears in that resource's sidebar. Each linked ADR shows its name and links directly to the decision page.
+
+This means engineers reading a service or event page can immediately see which architectural choices affect it, without leaving the page.
diff --git a/packages/core/docs/development/guides/resources/adrs/04-relationships.md b/packages/core/docs/development/guides/resources/adrs/04-relationships.md
new file mode 100644
index 000000000..450b973c3
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/adrs/04-relationships.md
@@ -0,0 +1,80 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog ADR
+- supersedes
+- amends
+sidebar_label: Model ADR relationships
+title: Model ADR relationships
+description: Model how decisions supersede, amend, or relate to each other.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.42.0" />
+
+ADRs often build on or replace earlier decisions. EventCatalog supports four relationship types to capture this history.
+
+## Supersedes and supersededBy
+
+Use `supersedes` when a new decision replaces an older one. The older decision should set its `status` to `superseded`.
+
+```yaml title="adrs/adr-003-v2/index.mdx (new decision)"
+---
+id: adr-003-standardize-domain-event-buses
+version: 2.0.0
+status: accepted
+supersedes:
+  - id: adr-003-standardize-domain-event-buses
+    version: 1.0.0
+---
+```
+
+You can also declare the relationship from the older side using `supersededBy`.
+
+```yaml title="adrs/adr-003-v1/index.mdx (old decision)"
+---
+id: adr-003-standardize-domain-event-buses
+version: 1.0.0
+status: superseded
+supersededBy:
+  - id: adr-003-standardize-domain-event-buses
+    version: 2.0.0
+---
+```
+
+EventCatalog derives reverse links automatically. Declaring `supersedes` on the new decision is enough to infer the `supersededBy` relationship on the old one, and vice versa.
+
+## Amends and amendedBy
+
+Use `amends` when a decision refines or extends an earlier one without fully replacing it.
+
+```yaml
+amends:
+  - id: adr-001-choose-event-driven-orders
+```
+
+As with supersedes, reverse links are derived automatically from either side.
+
+## Related
+
+Use `related` to point to decisions that are relevant context but not in a supersedes or amends relationship.
+
+```yaml
+related:
+  - id: adr-001-choose-event-driven-orders
+  - id: adr-003-standardize-domain-event-buses
+    version: 2.0.0
+```
+
+## How relationships appear in the sidebar
+
+Each relationship group appears as a separate section in the ADR's sidebar:
+
+- **Supersedes** — decisions this ADR replaces
+- **Superseded by** — decisions that replace this ADR
+- **Amends** — decisions this ADR refines
+- **Amended by** — decisions that refine this ADR
+- **Related decisions** — associated decisions
+
+Deprecated and superseded ADRs also display a warning banner at the top of the page with links to the current decision.
diff --git a/packages/core/docs/development/guides/resources/adrs/06-reference.md b/packages/core/docs/development/guides/resources/adrs/06-reference.md
new file mode 100644
index 000000000..25c51f586
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/adrs/06-reference.md
@@ -0,0 +1,247 @@
+---
+keywords:
+- EventCatalog ADRs
+- Architecture decision records
+- ADR frontmatter
+sidebar_label: Reference
+title: Architecture decision records reference
+description: Frontmatter fields, paths, and routes for architecture decision records in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by architecture decision records.
+
+## Paths
+
+ADRs can be created in any `adrs` folder:
+
+```txt
+/adrs/{ADR Name}/index.mdx
+/domains/{Domain Name}/adrs/{ADR Name}/index.mdx
+/systems/{System Name}/adrs/{ADR Name}/index.mdx
+```
+
+Versioned ADRs use:
+
+```txt
+/adrs/{ADR Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/adrs/{adr-id}/{version}` | ADR documentation page. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the decision record. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: adr-001-use-event-driven-checkout
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the decision record.
+
+```md title="Example"
+---
+name: Use event-driven checkout
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the decision record.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `status` {#status}
+
+- Type: `proposed`, `accepted`, `rejected`, `deprecated`, or `superseded`
+
+Lifecycle status for the decision.
+
+```md title="Example"
+---
+status: accepted
+---
+```
+
+### `date` {#date}
+
+- Type: `date`
+
+Date the decision was created or recorded.
+
+```md title="Example"
+---
+date: 2026-06-01
+---
+```
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short summary shown in lists and search.
+
+```md title="Example"
+---
+summary: Checkout will publish domain events for downstream fulfilment.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+Teams or users that own the decision record.
+
+```md title="Example"
+---
+owners:
+  - architecture-team
+---
+```
+
+### `decisionMakers` {#decisionMakers}
+
+- Type: `array`
+
+Teams or users that made or approved the decision.
+
+```md title="Example"
+---
+decisionMakers:
+  - architecture-review-board
+---
+```
+
+### `appliesTo` {#appliesTo}
+
+- Type: `array`
+
+Resources affected by this decision.
+
+```md title="Example"
+---
+appliesTo:
+  - type: system
+    id: checkout-system
+---
+```
+
+### `supersedes` {#supersedes}
+
+- Type: `array`
+
+Decision records replaced by this decision.
+
+```md title="Example"
+---
+supersedes:
+  - id: adr-000-old-checkout-design
+---
+```
+
+### `supersededBy` {#supersededBy}
+
+- Type: `array`
+
+Decision records that replace this decision.
+
+```md title="Example"
+---
+supersededBy:
+  - id: adr-004-new-checkout-design
+---
+```
+
+### `amends` {#amends}
+
+- Type: `array`
+
+Decision records amended by this decision.
+
+```md title="Example"
+---
+amends:
+  - id: adr-002-payment-routing
+---
+```
+
+### `amendedBy` {#amendedBy}
+
+- Type: `array`
+
+Decision records that amend this decision.
+
+```md title="Example"
+---
+amendedBy:
+  - id: adr-005-payment-retry-policy
+---
+```
+
+### `related` {#related}
+
+- Type: `array`
+
+Related decision records.
+
+```md title="Example"
+---
+related:
+  - id: adr-003-order-events
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the decision record page.
+
+```md title="Example"
+---
+badges:
+  - content: Accepted
+    backgroundColor: green
+    textColor: green
+---
+```
+
+## Applies to
+
+Use `appliesTo` to link the decision to resources.
+
+```md
+---
+appliesTo:
+  - type: system
+    id: checkout-system
+  - type: service
+    id: payment-service
+  - type: event
+    id: PaymentAuthorized
+---
+```
+
+Supported resource types include `agent`, `service`, `system`, `event`, `command`, `query`, `flow`, `channel`, `domain`, `user`, `team`, `container`, `entity`, `diagram`, and `data-product`.
diff --git a/packages/core/docs/development/guides/resources/adrs/_category_.json b/packages/core/docs/development/guides/resources/adrs/_category_.json
new file mode 100644
index 000000000..bdc7b2c7e
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/adrs/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Architecture Decision Records",
+  "position": 9,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources/adrs",
+    "description": "A collection of guides to help you document and manage architecture decision records in EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/agents/01-introduction.md b/packages/core/docs/development/guides/resources/agents/01-introduction.md
new file mode 100644
index 000000000..b1aac88d6
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/agents/01-introduction.md
@@ -0,0 +1,28 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog agents
+- AI agents
+- LLM agents
+- agent documentation
+sidebar_label: What are agents?
+title: Understanding agents
+description: Document and govern AI agents alongside your services and events.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+In EventCatalog, agents represent AI-powered components in your architecture. They sit alongside services, messages, domains, and flows as first-class catalog resources.
+
+An agent typically wraps a large language model (LLM) and is given access to tools (MCP servers, APIs, databases) so it can take autonomous or semi-autonomous actions.
+
+### Why document agents?
+
+As AI agents take on real responsibilities in production systems they become part of your architecture whether or not they are documented.
+
+Cataloging them gives your team:
+
+- **Discoverability** — engineers and stakeholders can find what agents exist, what they do, and who owns them.
+- **Model governance** — the `model` block captures which provider, model, and snapshot version the agent runs on so drift is visible in the catalog.
+- **Tool transparency** — the `tools` array lists every external capability (MCP server, API, database) the agent can reach.
+
diff --git a/packages/core/docs/development/guides/resources/agents/02-create-agent.md b/packages/core/docs/development/guides/resources/agents/02-create-agent.md
new file mode 100644
index 000000000..33c996df8
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/agents/02-create-agent.md
@@ -0,0 +1,188 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog agents
+- AI agents
+- creating agents
+sidebar_label: Create an agent
+title: Create an agent
+description: Creating and managing agents within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Agents document AI-powered capabilities in your architecture. Use them for assistants, autonomous workers, copilots, review agents, or any LLM-backed component that can reason over data, call tools, receive messages, or send messages.
+
+You can also add [model metadata](/docs/development/guides/resources/agents/model-metadata), [tools](/docs/development/guides/resources/agents/adding-tools), [messages](/docs/development/guides/resources/agents/add-messages-to-agents), and [data stores](/docs/development/guides/resources/agents/add-data-stores-to-agents) to your agents.
+
+![Example](./img/agent-documentation.png)
+
+## Adding a new agent
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog agent">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/agents/create-agent.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/agents.md then help me create a new EventCatalog agent in my catalog.
+
+Ask me for the agent name, what the agent does, summary, model provider/name/version if known, tools it can call, messages it receives or sends, data stores it reads from or writes to, and whether it belongs at the root of the catalog or inside a domain. Then create the correct agents/{'{Agent Name}'}/index.mdx or domains/{'{Domain Name}'}/agents/{'{Agent Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+If the catalog does not have any domains, put it into the root agents folder.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the agent should live, create the right folder structure, and add the first version of the agent documentation.
+
+### Manual Creation
+
+Agents can live at the root of your catalog or inside a domain.
+
+Create a new folder for the agent with an `index.mdx` file.
+
+<ProjectTree
+  items={[
+    {
+      name: 'agents',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'FraudReviewAgent',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+If the agent belongs to a domain, keep it inside that domain:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Payments',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'agents',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'FraudReviewAgent',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+You can also place agents inside a subdomain when the agent belongs to a more specific business boundary.
+
+## Create the agent file
+
+Create an `index.mdx` file for the agent.
+
+_Here is an example of what an agent markdown file may look like._
+
+```md title="/agents/FraudReviewAgent/index.mdx (example)"
+---
+# id of your agent, used for slugs and references in EventCatalog.
+id: FraudReviewAgent
+
+# Display name of the Agent, rendered in EventCatalog
+name: Fraud Review Agent
+
+# Version of the Agent
+version: 0.0.1
+
+# Short summary of your Agent
+summary: |
+  Reviews risky payments, explains fraud signals, and recommends whether payment processing should continue.
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional model metadata describing the LLM this agent runs on
+model:
+  provider: OpenAI
+  name: gpt-4.1
+  version: "2025-04-14"
+
+# Optional external tools the agent can call
+tools:
+  - name: Risk profile lookup
+    type: mcp
+    icon: /icons/tools/datadog.svg
+    url: https://mcp.example.com/fraud/risk-profile
+    description: Retrieves transaction anomaly, device fingerprint, and fraud model signals.
+
+# Optional messages this agent receives and its version
+receives:
+  - id: PaymentInitiated
+    version: 0.0.1
+
+# Optional messages this agent sends and its version
+sends:
+  - id: FraudReviewCompleted
+    version: 0.0.1
+
+# Optional data stores this agent reads from
+readsFrom:
+  - id: fraud-analytics-db
+    version: 0.0.1
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: AI Agent
+      backgroundColor: purple
+      textColor: purple
+---
+
+## Overview
+
+The Fraud Review Agent reviews risky payment attempts before they continue through the payment gateway.
+
+<NodeGraph />
+
+## Tools
+
+<AgentTools />
+```
+
+## Attaching an agent to a domain
+
+To associate an agent with a domain, add its `id` to the `agents` array in the domain's frontmatter:
+
+```md title="/domains/Payment/index.mdx (example)"
+---
+id: Payment
+name: Payment Domain
+version: 0.0.1
+agents:
+  - id: FraudReviewAgent
+    version: 0.0.1
+services:
+  - id: PaymentService
+    version: 0.0.1
+---
+```
+
+EventCatalog will show the agent in the domain sidebar and include it in the domain visualiser.
diff --git a/packages/core/docs/development/guides/resources/agents/03-adding-tools.md b/packages/core/docs/development/guides/resources/agents/03-adding-tools.md
new file mode 100644
index 000000000..0717cf325
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/agents/03-adding-tools.md
@@ -0,0 +1,91 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog agents
+- agent tools
+- MCP
+- AgentTools component
+sidebar_label: Add tools to agents
+title: Add tools to agents
+description: Document and display the tools an agent can call.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+Agents often call external capabilities to do their work — MCP servers, REST APIs, internal search indexes, or databases. The `tools` array in an agent's frontmatter captures these dependencies so anyone reading the catalog can understand what the agent reaches out to at runtime.
+
+![Agent tools table rendered on an agent page](./img/agent-tools-component.png)
+
+## Define tools in frontmatter
+
+Add a `tools` array to your agent's frontmatter. Each entry describes one tool:
+
+```md title="/agents/OrderSupportAgent/index.mdx (example)"
+---
+# id of your agent, used for slugs and references in EventCatalog.
+id: OrderSupportAgent
+
+# Display name of the Agent, rendered in EventCatalog
+name: Order Support Agent
+
+# Version of the Agent
+version: 0.0.1
+
+# Optional external tools the agent can call
+tools:
+    # Display name of the tool
+  - name: Order lookup
+    # Type of tool (e.g. `mcp`, `api`) — free-form string
+    type: mcp
+    # Optional icon path (from your catalog's `public/` folder) or absolute URL
+    icon: /icons/tools/snowflake.svg
+    # Optional link to the tool endpoint or documentation
+    url: https://mcp.example.com/orders/lookup
+    # Optional short description of what the tool does
+    description: Retrieves order status, totals, shipment milestones, and recent order events from the operational read model.
+  - name: Support case notes
+    type: mcp
+    icon: /icons/tools/zendesk.svg
+    url: https://mcp.example.com/support/case-notes
+    description: Appends investigation notes, suggested customer replies, and follow-up actions to the support ticket.
+---
+```
+
+### Tool fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Display name of the tool |
+| `type` | Yes | Free-form string — use `mcp` for MCP servers, `api` for REST/HTTP endpoints, or any label that fits your stack |
+| `icon` | No | Path in your catalog's `public/` folder or an absolute URL to an icon image |
+| `url` | No | Link to the tool endpoint or documentation |
+| `description` | No | One or two sentences describing what the tool does |
+
+The `type` field is a plain string. `mcp` gets special rendering in the catalog (the MCP logo appears next to the badge), but you can use any value that is meaningful to your team.
+
+## Render tools on the page
+
+Add the [`<AgentTools />`](/docs/development/components/components/agent-tools) component anywhere in your agent's MDX body to render the tools table. The component reads the `tools` array from the current agent's frontmatter — no props needed.
+
+```md title="/agents/OrderSupportAgent/index.mdx (example)"
+---
+id: OrderSupportAgent
+# ... rest of frontmatter
+---
+
+This agent helps the support team answer order questions.
+
+## Tools
+
+<AgentTools />
+
+## Responsibilities
+
+- Summarize the current state of an order for support staff.
+```
+
+`<AgentTools />` is only supported inside agent pages. If you add it to a service or message page, the catalog will display a warning and skip the table.
+
+![Agent tools table with MCP badge and icon columns](./img/agent-tools-component.png)
diff --git a/packages/core/docs/development/guides/resources/agents/04-model-metadata.md b/packages/core/docs/development/guides/resources/agents/04-model-metadata.md
new file mode 100644
index 000000000..3a7931508
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/agents/04-model-metadata.md
@@ -0,0 +1,96 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog agents
+- LLM model
+- model governance
+- AI governance
+sidebar_label: Model metadata
+title: Model metadata
+description: Capture the LLM provider, model, and version your agent uses.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+Every agent can declare the LLM it uses through a `model` block in its frontmatter. This gives your team a single place to see which model powers each agent across your entire catalog.
+
+![Agents in the EventCatalog discover view](./img/explore-agents.png)
+
+## Why track the model?
+
+LLM providers release new model versions, retire old snapshots, and change behavior between releases — often without a corresponding code deployment. Capturing `provider`, `name`, and `version` makes it easy to:
+
+- Audit which agents are running on deprecated or retired snapshots.
+- Surface model drift when a provider rolls out a new default.
+- Give reviewers the context they need when an agent's output changes unexpectedly.
+
+## Add model metadata
+
+Add a `model` block to your agent's frontmatter:
+
+```md title="/agents/FraudReviewAgent/index.mdx (OpenAI example)"
+---
+id: FraudReviewAgent
+name: Fraud Review Agent
+version: 0.0.1
+
+# Optional model metadata describing the LLM this agent runs on
+model:
+  # The provider or platform powering the model
+  provider: OpenAI
+  # The model identifier
+  name: gpt-4.1
+  # The snapshot or API version of the model
+  version: "2025-04-14"
+---
+```
+
+```md title="/agents/InventoryRebalancingAgent/index.mdx (Gemini example)"
+---
+id: InventoryRebalancingAgent
+name: Inventory Rebalancing Agent
+version: 0.0.1
+
+# Optional model metadata describing the LLM this agent runs on
+model:
+  # The provider or platform powering the model
+  provider: Gemini
+  # The model identifier
+  name: gemini-2.5-pro
+  # The snapshot or API version of the model
+  version: "2025-06-17"
+---
+```
+
+```md title="/agents/ProductContentAgent/index.mdx (Anthropic example)"
+---
+id: ProductContentAgent
+name: Product Content Agent
+version: 0.0.1
+
+# Optional model metadata describing the LLM this agent runs on
+model:
+  # The provider or platform powering the model
+  provider: Anthropic
+  # The model identifier
+  name: claude-sonnet-4-5
+  # The snapshot or API version of the model
+  version: "20241022"
+---
+```
+
+### Model fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `provider` | No | The provider or platform — e.g. `OpenAI`, `Anthropic`, `Gemini`, `Azure OpenAI` |
+| `name` | No | The model identifier — e.g. `gpt-4.1`, `claude-sonnet-4-5`, `gemini-2.5-pro` |
+| `version` | No | The snapshot or API version — e.g. `2025-04-14`, `20241022` |
+
+All three fields are optional strings. Use whatever convention your provider uses for model identifiers and snapshot dates.
+
+## Model changes and versioning
+
+When you upgrade the model an agent uses, consider whether the behavior change is significant enough to warrant a new agent version. Capturing the new `model.version` in a versioned snapshot (see [Version agents](/docs/development/guides/versioning-resources)) gives your team a clear record of when the model changed and who approved it.
diff --git a/packages/core/docs/development/guides/resources/agents/05-add-messages-to-agents.md b/packages/core/docs/development/guides/resources/agents/05-add-messages-to-agents.md
new file mode 100644
index 000000000..aaae45ae1
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/agents/05-add-messages-to-agents.md
@@ -0,0 +1,123 @@
+---
+keywords:
+- EventCatalog agents
+- agent messages
+- sends receives
+sidebar_position: 5
+sidebar_label: Add messages to agents
+title: Adding messages to agents
+description: Connecting agents to the messages they produce and consume.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+An agent can **receive** messages (events, commands, or queries) that trigger its reasoning, and **send** messages as a result of its actions.
+
+Connecting agents to messages keeps the full event topology visible in the visualiser and lets your team trace which agents react to which events.
+
+![Agent visualiser showing received events, connected services, and data stores](./img/agent-consuming-messages.png)
+
+## Adding messages to your agent
+
+To add messages to an agent you need to define them in either the **sends** or **receives** array within your agent frontmatter API.
+
+You need to add the `id` of the message and optionally the `version` of the message.
+
+```md title="/agents/FraudReviewAgent/index.mdx (example)"
+---
+id: FraudReviewAgent
+... # other agent frontmatter
+receives:
+    # id of the message this agent receives
+    - id: PaymentInitiated
+    # (optional) The version of the message you want to add.
+    # If no version is given the latest version of the message will be used.
+      version: 0.0.1
+sends:
+    # id of the message this agent sends
+    - id: FraudCaseCreated
+      version: 0.0.1
+---
+
+<!-- Markdown contents... -->
+
+```
+
+The **receives** and **sends** fields in your agent tell EventCatalog which messages this agent either consumes or publishes.
+
+:::info The power of versioning
+  When you define your messages for your agent you can define the version of them too. This can be powerful if you have multiple versions of your events, commands or queries. Example could be an event raised by another team — you can pin the exact version your agent reasons over so a future change doesn't silently alter its behaviour.
+:::
+
+### Routing messages through channels
+
+You can also route your messages through channels. Examples of these could be your brokers, queues, topics, etc.
+
+To do this you can use the `to` and `from` fields in your agent frontmatter.
+
+This example shows:
+- the `FraudReviewAgent` sending a `FraudCaseCreated` message to the `fraud.events` channel.
+- the `FraudReviewAgent` consuming a `PaymentInitiated` message from the `payments.events` channel.
+
+```md title="/agents/FraudReviewAgent/index.mdx (example)"
+---
+id: FraudReviewAgent
+... # other agent frontmatter
+
+# Agent sends a message called FraudCaseCreated
+# This message is published to the fraud.events channel (e.g broker)
+sends:
+  - id: FraudCaseCreated
+    to:
+      - id: fraud.events
+
+# Agent consumes a message called PaymentInitiated
+# This message is consumed from the payments.events channel (e.g queue)
+receives:
+  - id: PaymentInitiated
+    from:
+      - id: payments.events
+---
+```
+
+You can read more about routing messages through channels in the [routing messages through channels guide](/docs/development/guides/resources/messages/message-channels/introduction).
+
+### Using semver versioning
+
+<AddedIn version="2.4.0" />
+
+You can use [semver](https://semver.org/) syntax when referencing your messages in your agents.
+
+```md title="/agents/FraudReviewAgent/index.mdx (example)"
+---
+id: FraudReviewAgent
+... # other agent frontmatter
+receives:
+    # Agent receives a message called RiskScoreCalculated
+    # The latest minor/patch version of this event will be used
+    - id: RiskScoreCalculated
+      version: 1.x.x
+sends:
+    # Agent sends a message called FraudCaseCreated
+    # This pulls the latest patch version of FraudCaseCreated
+    - id: FraudCaseCreated
+      version: 2.0.x
+    # Agent sends a message called FraudEscalated
+    # This pulls the latest minor/patch version of FraudEscalated
+    - id: FraudEscalated
+      version: >1.0.1
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Although it's recommended to link to a version of a message it is now optional. If no version is given **latest** is used by default.
+
+### Visualizing messages within an agent
+
+When messages get added within your agents EventCatalog will visualize this for you either using the `NodeGraph` component or through the visualizer.
+
+![Agent node graph showing sends and receives connections](./img/agent-visualizer.png)
diff --git a/packages/core/docs/development/guides/resources/agents/06-add-data-stores-to-agents.md b/packages/core/docs/development/guides/resources/agents/06-add-data-stores-to-agents.md
new file mode 100644
index 000000000..a112785a3
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/agents/06-add-data-stores-to-agents.md
@@ -0,0 +1,51 @@
+---
+keywords:
+- EventCatalog agents
+- agent data stores
+- writesTo readsFrom
+sidebar_position: 6
+sidebar_label: Add data stores to agents
+title: Adding data stores to agents
+description: Document the data stores an agent reads from or writes to.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.41.0" />
+
+[Data stores](/docs/development/guides/resources/data/introduction) are containers that hold data in your architecture — databases, caches, object stores, search indexes, and so on. Agents can read from and write to these containers, and documenting those relationships keeps the full data-access picture visible in the visualiser.
+
+## Specify read/write relationships
+
+Add `readsFrom` or `writesTo` arrays to your agent's frontmatter. Provide the `id` of the data store and optionally its `version`.
+
+```md title="/agents/FraudReviewAgent/index.mdx (example)"
+---
+id: FraudReviewAgent
+version: 0.0.1
+readsFrom:
+  - id: fraud-analytics-db
+  - id: ml-model-store
+    version: 2.0.0
+---
+```
+
+```md title="/agents/InventoryRebalancingAgent/index.mdx (example)"
+---
+id: InventoryRebalancingAgent
+version: 0.0.1
+readsFrom:
+  - id: inventory-readmodel
+  - id: inventory-db
+writesTo:
+  - id: rebalancing-audit-log
+---
+```
+
+If no version is provided, EventCatalog uses the latest version of the data store.
+
+## Visualize data stores
+
+When data stores are connected to an agent, EventCatalog visualizes the read/write relationships — either via the `<NodeGraph />` component on the agent page or through the full-screen visualiser.
+
+![Agent visualiser showing data store nodes connected with reads and writes](./img/agent-consuming-messages.png)
diff --git a/packages/core/docs/development/guides/resources/agents/11-reference.md b/packages/core/docs/development/guides/resources/agents/11-reference.md
new file mode 100644
index 000000000..1930d6385
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/agents/11-reference.md
@@ -0,0 +1,238 @@
+---
+keywords:
+- EventCatalog agents
+- Agent frontmatter
+sidebar_position: 11
+sidebar_label: Reference
+title: Agents reference
+description: Frontmatter fields, paths, and routes for agents in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by agents.
+
+## Paths
+
+Agents can be created in any `agents` folder:
+
+```txt
+/agents/{Agent Name}/index.mdx
+/domains/{Domain Name}/agents/{Agent Name}/index.mdx
+```
+
+Versioned agents use:
+
+```txt
+/agents/{Agent Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/agents/{agent-id}/{version}` | Agent documentation page. |
+| `/visualiser/agents/{agent-id}/{version}` | Agent resource diagram. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the agent. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: customer-support-agent
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the agent.
+
+```md title="Example"
+---
+name: Customer Support Agent
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the agent documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short description of what the agent does.
+
+```md title="Example"
+---
+summary: Answers customer support questions using catalog and order context.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the agent.
+
+```md title="Example"
+---
+owners:
+  - support-platform
+---
+```
+
+### `model` {#model}
+
+- Type: `object`
+
+Model metadata for the agent.
+
+```md title="Example"
+---
+model:
+  provider: OpenAI
+  name: gpt-4.1-mini
+  version: "2025-04-14"
+---
+```
+
+### `tools` {#tools}
+
+- Type: `array`
+
+Tools the agent can use.
+
+```md title="Example"
+---
+tools:
+  - name: Order lookup
+    type: mcp
+    url: https://mcp.example.com/orders
+    description: Retrieves order status and recent order events.
+---
+```
+
+### `sends` {#sends}
+
+- Type: `array`
+
+Messages the agent sends.
+
+```md title="Example"
+---
+sends:
+  - id: SupportCaseCreated
+    version: 1.0.0
+---
+```
+
+### `receives` {#receives}
+
+- Type: `array`
+
+Messages the agent receives.
+
+```md title="Example"
+---
+receives:
+  - id: CustomerQuestionAsked
+    version: 1.0.0
+---
+```
+
+### `readsFrom` {#readsFrom}
+
+- Type: `array`
+
+Data stores the agent reads from.
+
+```md title="Example"
+---
+readsFrom:
+  - id: support-knowledge-base
+    version: 1.0.0
+---
+```
+
+### `writesTo` {#writesTo}
+
+- Type: `array`
+
+Data stores the agent writes to.
+
+```md title="Example"
+---
+writesTo:
+  - id: support-case-store
+    version: 1.0.0
+---
+```
+
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the agent page.
+
+```md title="Example"
+---
+badges:
+  - content: AI
+    backgroundColor: purple
+    textColor: purple
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the agent.
+
+```md title="Example"
+---
+repository:
+  language: TypeScript
+  url: https://github.com/acme/support-agent
+---
+```
+
+## Model fields
+
+```md
+---
+model:
+  provider: OpenAI
+  name: gpt-4.1-mini
+  version: "2025-04-14"
+---
+```
+
+## Tool fields
+
+```md
+---
+tools:
+  - name: Order lookup
+    type: mcp
+    url: https://mcp.example.com/orders
+    description: Retrieves order status and recent order events.
+---
+```
diff --git a/packages/core/docs/development/guides/resources/agents/_category_.json b/packages/core/docs/development/guides/resources/agents/_category_.json
new file mode 100644
index 000000000..a95c03652
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/agents/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Agents",
+  "position": 10,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources/agents",
+    "description": "A collection of guides to help you understand agents and how they work with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/data-products/01-introduction.md b/packages/core/docs/development/guides/resources/data-products/01-introduction.md
new file mode 100644
index 000000000..8eb4fc5f9
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/data-products/01-introduction.md
@@ -0,0 +1,100 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog data products
+- Data products
+sidebar_label: What are data products?
+title: Understanding data products
+description: Data as a product for analytics and insights
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Data products in EventCatalog represent analytical datasets that transform raw operational (e.g databases, messages, channels) data into high-quality, discoverable, and reusable information assets.
+
+A data product may consumes inputs (e.g [events](/docs/development/guides/resources/messages/message-types/events), [services](/docs/development/guides/resources/services/introduction), [data stores](/docs/development/guides/resources/data/introduction)) and produces outputs (e.g [data stores](/docs/development/guides/resources/data/introduction), metrics) optimized for specific use cases like reporting, business intelligence, or machine learning.
+
+## Key characteristics
+
+Data products have specific properties that make them distinct:
+
+**Inputs** (input ports) represent source dependencies including events, services, channels, or data stores that feed the data product.
+
+**Outputs** (output ports) represent the analytical assets produced including aggregated tables, metrics streams, or downstream systems that consume the data.
+
+**Contracts** (data contracts) define the schema structure for output datasets. EventCatalog supports any format (e.g JSON Schema, ODCS YAML).
+
+**Ownership** assigns clear accountability with designated teams or individuals responsible for data quality and availability.
+
+## Use cases
+
+Data products are valuable when you need to:
+
+- Document analytical pipelines and their dependencies
+- Provide and visualize lineage between data products and their inputs and outputs
+- Provide clear contracts for downstream consumers
+- Provide clear SLA's and quality metrics for analytical datasets
+- Enable self-service data discovery and consumption across teams
+
+## Example scenarios
+
+### Order Analytics
+
+Consumes order and payment events to produce aggregated sales metrics, daily revenue summaries, and customer behavior analysis.
+
+```mermaid
+graph LR
+    A["Order Events"] --> B["Order Analytics"]
+    C["Payment Events"] --> B
+    B --> D["Sales Metrics"]
+    B --> E["Revenue Summary"]
+    B --> F["Customer Behavior"]
+    style B fill:#4f46e5,color:#fff
+```
+
+### Payment Metrics
+
+Transforms payment lifecycle events into fraud detection insights, success rate analysis, and revenue attribution by channel.
+
+```mermaid
+graph LR
+    A["Payment Created"] --> B["Payment Metrics"]
+    C["Payment Completed"] --> B
+    D["Payment Failed"] --> B
+    B --> E["Fraud Detection"]
+    B --> F["Success Rate"]
+    B --> G["Revenue by Channel"]
+    style B fill:#4f46e5,color:#fff
+```
+
+### Fulfillment KPIs
+
+Combines order, shipment, and delivery events to produce operational metrics like processing times and delivery performance.
+
+```mermaid
+graph LR
+    A["Order Created"] --> B["Fulfillment KPIs"]
+    C["Shipment Dispatched"] --> B
+    D["Delivery Completed"] --> B
+    B --> E["Processing Times"]
+    B --> F["Delivery Performance"]
+    B --> G["Operational Metrics"]
+    style B fill:#4f46e5,color:#fff
+```
+
+## Relationship to other resources
+
+Data products integrate with existing EventCatalog resources:
+
+- **Messages (e.g events) ** can be inputs to data products for real-time processing
+- **Services** can also be inputs to data products if your data product consumed it's API for example.
+- **Data stores** can be both inputs and outputs for data products
+- **Domains** can contain data products as part of their bounded context
+- **Channels (e.g Eventbus, Kafka, RabbitMQ)** can but inputs and outputs to data products
+
+## SDK support
+
+Data products are fully supported in the EventCatalog SDK, enabling programmatic creation and management of data product documentation.
+
+Use the SDK to automate data product documentation as part of your CI/CD pipeline or integrate with external analytics platforms.
+
diff --git a/packages/core/docs/development/guides/resources/data-products/02-adding-data-products.md b/packages/core/docs/development/guides/resources/data-products/02-adding-data-products.md
new file mode 100644
index 000000000..ac5aad3ad
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/data-products/02-adding-data-products.md
@@ -0,0 +1,174 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog data products
+sidebar_label: Create a data product
+title: Create a data product
+description: Creating and managing data products
+---
+
+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="3.8.0" />
+
+Data products document analytical datasets that transform operational (e.g databases, messages, channels) data into insights. Adding a data product helps teams understand data lineage, contracts, and consumption patterns.
+
+![Example](./img/data-product.png)
+
+## Adding a new data product
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog data product">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/data-products/adding-data-products.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/data-products.md then help me create a new EventCatalog data product in my catalog.
+
+Ask me for the data product name, what analytical dataset it provides, summary, owners, whether it belongs at the root of the catalog or inside a domain, and any known inputs, outputs, or data contracts. Then create the correct data-products/{'{Data Product Name}'}/index.mdx or domains/{'{Domain Name}'}/data-products/{'{Data Product Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+If the data product has output contracts, ask me for the contract file names, types, and where those contract files should live.
+
+If the catalog does not have any domains, put it into the root data-products folder.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the data product should live, create the right folder structure, and add the first version of the data product documentation.
+
+### Manual Creation
+
+Data products live in a `data-products` folder. EventCatalog discovers any `index.mdx` file inside a `data-products` directory, regardless of where that directory lives in your catalog.
+
+You can place data products:
+
+At the root of your catalog:
+
+<ProjectTree
+  items={[
+    {
+      name: 'data-products',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrderAnalytics',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx', highlight: true },
+            { name: 'fact-orders-contract.json' },
+          ],
+        },
+        {
+          name: 'PaymentMetrics',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx', highlight: true },
+            { name: 'payment-contract.json' },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a domain:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'E-Commerce',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'data-products',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'CustomerSegmentation',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The contents are split into two sections: **frontmatter** and **markdown content**.
+
+## Create the data product file
+
+Create an `index.mdx` file for the data product.
+
+Here is an example data product markdown file. [You can read the data product reference](/docs/development/guides/resources/data-products/reference).
+
+```md title="/data-products/OrderAnalytics/index.mdx (example)"
+---
+# Unique identifier for your data product
+id: order-analytics
+
+# Display name rendered in EventCatalog
+name: Order Analytics
+
+# Version of the data product
+version: 1.0.0
+
+# Brief summary of what this data product provides
+summary: Aggregated order metrics and KPIs for business intelligence
+
+# Optional owners (references teams or users)
+owners:
+  - dboyne
+
+# Optional badges for categorization
+badges:
+  - content: Analytics
+    backgroundColor: purple
+    textColor: purple
+  - content: dbt
+    backgroundColor: orange
+    textColor: orange
+
+# Input dependencies (events, services, data stores)
+inputs:
+  - id: OrderConfirmed
+    # version is optional for all inputs
+    version: 1.0.0
+  - id: PaymentProcessed
+  - id: payment-cache
+
+# Output data products (events, services, data stores)
+outputs:
+  - id: OrderMetricsCalculated
+    # version is optional for all outputs
+    version: 1.0.0
+  - id: NotificationService
+  - id: orders-db
+    contract:
+      path: fact-orders-contract.json
+      name: Fact Orders Contract
+      type: json-schema
+---
+
+## Overview
+
+The Order Analytics data product transforms raw order and payment events into aggregated metrics optimized for reporting and business intelligence.
+
+<NodeGraph />
+
+Rest of your markdown....
+```
+
diff --git a/packages/core/docs/development/guides/resources/data-products/03-inputs-and-outputs.md b/packages/core/docs/development/guides/resources/data-products/03-inputs-and-outputs.md
new file mode 100644
index 000000000..ee876d4da
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/data-products/03-inputs-and-outputs.md
@@ -0,0 +1,126 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog data products
+sidebar_label: Inputs and outputs
+title: Inputs and outputs
+description: Define dependencies and consumers
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Data products consume inputs (e.g events, services, data stores, channels) and produce outputs (e.g events, services, data stores, channels). Defining these relationships helps teams understand data lineage and dependencies.
+
+## Defining inputs (input ports)
+
+Inputs represent the source dependencies your data product consumes. In EventCatalog these can be [events](/docs/development/guides/resources/messages/message-types/events), commands, queries, [services](/docs/development/guides/resources/services/introduction), [data stores](/docs/development/guides/resources/data/introduction), or [channels](/docs/development/guides/resources/messages/message-channels/introduction).
+
+You need to specify the `id` of the input and optionally the `version` of the input. If no version is provided the latest version will be used.
+
+```md
+---
+id: order-analytics
+name: Order Analytics
+version: 1.0.0
+
+# Define input dependencies
+inputs:
+  - id: OrderConfirmed
+  - id: PaymentProcessed
+  - id: FraudDetectionService
+  - id: payment-cache
+  - id: payment-domain-eventbus
+---
+```
+
+## Defining outputs
+
+Outputs represent what your data product produces. These can be events, commands, queries, services, data stores, or channels.
+
+You need to specify the `id` of the output and optionally the `version` of the output. If no version is provided the latest version will be used.
+
+```md
+---
+id: order-analytics
+name: Order Analytics
+version: 1.0.0
+
+# Define what this data product produces
+outputs:
+  - id: OrderMetricsCalculated
+  - id: NotificationService
+  - id: orders-db
+  - id: orders-domain-eventbus
+---
+```
+
+## Visualizing relationships
+
+The `<NodeGraph />` component automatically visualizes inputs and outputs.
+
+```md
+<NodeGraph />
+```
+
+![Example](./img/data-product-node-graph.png)
+
+This graph shows:
+- Input events flowing into the data product
+- Output events or data stores produced
+- Services that interact with the data product
+- Contract relationships for data stores
+
+## Complete example
+
+```md title="/data-products/PaymentAnalytics/index.mdx"
+---
+id: payment-analytics
+name: Payment Analytics
+version: 1.0.0
+summary: Payment performance metrics and fraud insights
+
+inputs:
+  - id: PaymentInitiated
+  - id: PaymentProcessed
+  - id: PaymentFailed
+  - id: FraudCheckCompleted
+  - id: PaymentService
+  - id: payments-db
+
+outputs:
+  - id: NotificationService
+  - id: payment-domain-eventbus
+  - id: payment-analytics-db
+    contract:
+      path: payment-metrics-contract.json
+      name: Payment Metrics Contract
+      type: json-schema
+---
+
+## Overview
+
+Payment Analytics transforms payment lifecycle events into comprehensive metrics.
+
+<NodeGraph />
+
+## Input Events
+
+- **PaymentInitiated** - Start of payment flow (~60k/day)
+- **PaymentProcessed** - Successful payments (~55k/day)
+- **PaymentFailed** - Failed transactions (~5k/day)
+- **FraudCheckCompleted** - Fraud detection results (~60k/day)
+
+## Output Tables
+
+### fact_payments
+
+Transaction-level payment data with fraud scores.
+
+<SchemaViewer file="payment-metrics-contract.json" />
+```
+
+## Next steps
+
+- [Add schema contracts](/docs/development/guides/resources/data-products/contracts)
+- [Version data products](/docs/development/guides/versioning-resources)
+- [Add to domains](/docs/development/guides/domains/add-resources-to-domains/add-data-products-to-domains)
diff --git a/packages/core/docs/development/guides/resources/data-products/04-contracts.md b/packages/core/docs/development/guides/resources/data-products/04-contracts.md
new file mode 100644
index 000000000..547566320
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/data-products/04-contracts.md
@@ -0,0 +1,100 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog data products
+sidebar_label: Data Contracts
+title: Data Contracts
+description: Define schema contracts for outputs
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Contracts define the schema structure for data product outputs. They provide clear expectations for downstream consumers and enable schema validation.
+
+Your contracts can be any format you want (e.g JSON Schema, ODCS YAML, etc).
+
+## What are contracts?
+
+Contracts are schema specifications attached to data product outputs. They document the structure, types, and constraints of the data your product produces.
+
+Contracts help teams:
+
+- Understand output data structures without inspecting code
+- Validate data against expected schemas
+- Catch breaking changes before deployment
+- Enable self-service data consumption
+
+## Supported formats
+
+EventCatalog supports any schema or specification format.
+
+## Adding contracts
+
+Contracts are defined in the `outputs` array of your data product frontmatter.
+
+```md title="/data-products/PaymentAnalytics/index.mdx"
+---
+id: payment-analytics
+name: Payment Analytics
+version: 1.0.0
+
+outputs:
+  - id: payment-analytics-db
+    contract:
+      path: payment-metrics-contract.json
+      name: Payment Metrics Contract
+      type: json-schema
+---
+```
+
+Contract properties:
+
+- **path** is the file path relative to the data product directory
+- **name** is the display name shown in EventCatalog
+- **type** specifies the format (`json-schema` or `odcs`)
+
+## Viewing contracts
+
+EventCatalog provides a schema explorer for viewing contracts.
+
+Use the `<SchemaViewer />` component to display contracts in your documentation:
+
+```md
+## Output Schema
+
+<SchemaViewer file="payment-metrics-contract.json" />
+```
+
+![Example](./img/data-schema-viewer.png)
+
+The schema explorer renders:
+
+- Interactive field navigation
+- Type information and constraints
+- Field descriptions
+- Required field indicators
+
+## Multiple contracts
+
+A single output can have multiple contracts for different tables or datasets.
+
+```md
+outputs:
+  - id: analytics-warehouse
+    contract:
+      path: fact-orders.json
+      name: Fact Orders
+      type: json-schema
+  - id: analytics-warehouse
+    contract:
+      path: dim-customers.json
+      name: Customer Dimension
+      type: json-schema
+```
+
+
+## Next steps
+
+- [Version data products](/docs/development/guides/versioning-resources)
+- [Add to domains](/docs/development/guides/domains/add-resources-to-domains/add-data-products-to-domains)
+- [Schema explorer component](/docs/development/components/using-components)
diff --git a/packages/core/docs/development/guides/resources/data-products/07-reference.md b/packages/core/docs/development/guides/resources/data-products/07-reference.md
new file mode 100644
index 000000000..25cfeb210
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/data-products/07-reference.md
@@ -0,0 +1,201 @@
+---
+keywords:
+- EventCatalog data products
+- Data product frontmatter
+sidebar_label: Reference
+title: Data products reference
+description: Frontmatter fields, paths, and routes for data products in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by data products.
+
+## Paths
+
+Data products can be created in any `data-products` folder:
+
+```txt
+/data-products/{Data Product Name}/index.mdx
+/domains/{Domain Name}/data-products/{Data Product Name}/index.mdx
+```
+
+Versioned data products use:
+
+```txt
+/data-products/{Data Product Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/data-products/{data-product-id}/{version}` | Data product documentation page. |
+| `/visualiser/data-products/{data-product-id}/{version}` | Data product resource diagram. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the data product. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: customer-analytics
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the data product.
+
+```md title="Example"
+---
+name: Customer Analytics
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the data product documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short description of the data product.
+
+```md title="Example"
+---
+summary: Curated customer analytics dataset for reporting and segmentation.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the data product.
+
+```md title="Example"
+---
+owners:
+  - data-platform
+---
+```
+
+### `inputs` {#inputs}
+
+- Type: `array`
+
+Resources used as inputs to the data product.
+
+```md title="Example"
+---
+inputs:
+  - id: customer-database
+    type: container
+---
+```
+
+### `outputs` {#outputs}
+
+- Type: `array`
+
+Outputs produced by the data product.
+
+```md title="Example"
+---
+outputs:
+  - id: customer-analytics
+    contract:
+      path: contracts/customer-analytics.avro
+      name: Customer analytics contract
+      type: avro
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the data product page.
+
+```md title="Example"
+---
+badges:
+  - content: Certified
+    backgroundColor: green
+    textColor: green
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the data product.
+
+```md title="Example"
+---
+repository:
+  language: SQL
+  url: https://github.com/acme/customer-analytics
+---
+```
+
+### `diagrams` {#diagrams}
+
+- Type: `array`
+
+Diagrams associated with the data product.
+
+```md title="Example"
+---
+diagrams:
+  - id: customer-analytics-lineage
+    version: 1.0.0
+---
+```
+
+### `attachments` {#attachments}
+
+- Type: `array`
+
+External links or supporting documents attached to the data product.
+
+```md title="Example"
+---
+attachments:
+  - title: Data contract review
+    url: https://docs.example.com/customer-analytics
+    type: document
+---
+```
+
+## Output contracts
+
+Outputs can include a contract that describes the data product output.
+
+```md
+---
+outputs:
+  - id: customer-analytics
+    contract:
+      path: contracts/customer-analytics.avro
+      name: Customer analytics contract
+      type: avro
+---
+```
diff --git a/packages/core/docs/development/guides/resources/data-products/_category_.json b/packages/core/docs/development/guides/resources/data-products/_category_.json
new file mode 100644
index 000000000..a39277c3a
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/data-products/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Data Products",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources/data-products",
+    "description": "A collection of guides to help you understand data products and how they work with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/data/01-introduction.md b/packages/core/docs/development/guides/resources/data/01-introduction.md
new file mode 100644
index 000000000..6ff33c9d8
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/data/01-introduction.md
@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Services
+sidebar_label: What are data stores?
+title: Understanding data stores
+description: What are data resources in EventCatalog?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+In EventCatalog **data stores** represent data stores that are used in your architecture (e.g. databases, caches, object store, search indexes, etc).
+
+Using the data store resource in EventCatalog you can define how your [services](/docs/development/guides/resources/services/introduction) read/write to data stores in your architecture, helping your teams understand how your services interact with data in your architecture. 
\ No newline at end of file
diff --git a/packages/core/docs/development/guides/resources/data/02-adding-data.md b/packages/core/docs/development/guides/resources/data/02-adding-data.md
new file mode 100644
index 000000000..e4db938cb
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/data/02-adding-data.md
@@ -0,0 +1,184 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog data stores
+sidebar_label: Create a data store
+title: Create a data store
+description: Creating and managing data stores within EventCatalog.
+---
+
+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="2.59.0" />
+
+Data stores document the databases, caches, object stores, search indexes, warehouses, and other storage systems used by your architecture.
+
+![Example](../../img/containers/data-example.png)
+
+## Adding a new data store
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog data store">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/data/adding-data.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/containers.md then help me create a new EventCatalog data store in my catalog.
+
+Ask me for the data store name, what it stores, summary, type, technology, classification, retention, residency, whether it belongs at the root of the catalog or inside a service or system, and any known services or agents that read from or write to it. Then create the correct containers/{'{Data Store Name}'}/index.mdx, services/{'{Service Name}'}/containers/{'{Data Store Name}'}/index.mdx, systems/{'{System Name}'}/containers/{'{Data Store Name}'}/index.mdx, or domains/{'{Domain Name}'}/systems/{'{System Name}'}/containers/{'{Data Store Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+If the catalog does not have any services or systems, put it into the root containers folder.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the data store should live, create the right folder structure, and add the first version of the data store documentation.
+
+### Manual Creation
+
+Data stores live in a `containers` folder. EventCatalog discovers any `index.mdx` file inside a `containers` directory, regardless of where that directory lives in your catalog.
+
+You can place data stores:
+
+At the root of your catalog:
+
+<ProjectTree
+  items={[
+    {
+      name: 'containers',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersDatabase',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a service:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'containers',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrdersDatabase',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a system:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'order-management-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    {
+                      name: 'containers',
+                      type: 'folder',
+                      defaultOpen: true,
+                      children: [
+                        {
+                          name: 'OrdersDatabase',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx', highlight: true }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+## Create the data store file
+
+Create an `index.mdx` file for the data store.
+
+_Here is an example of what a data store markdown file may look like._
+
+```md title="/containers/OrdersDatabase/index.mdx (example)"
+---
+# id of your data store, used for slugs and references in EventCatalog.
+id: orders-db
+# Display name of the data store, rendered in EventCatalog.
+name: Orders DB
+# Version of the data store
+version: 0.0.1
+# Type of the data store (e.g. database, cache, objectStore, searchIndex)
+container_type: database
+# Technology of the data store (e.g. postgres@14, redis@7, etc)
+technology: postgres@14
+# Classification of the data store (e.g. internal, external, etc)
+classification: internal
+# Retention of the data store (e.g. 7y, 10y, etc)
+retention: 7y
+# Residency of the data store (e.g. eu-west-1, us-east-1, etc)
+residency: eu-west-1
+---
+
+## Overview
+
+This orders database stores all orders and order lines for the orders domain.
+
+<NodeGraph />
+
+```
+
+Once this file is added, the data store will automatically appear across EventCatalog.
+
+### Assign read/write relationships to data stores
+
+You can assign read/write relationships to data stores in EventCatalog. You can read more about how to do this in [Add read/write relationships](/docs/development/guides/resources/data/add-read-write-relationships).
diff --git a/packages/core/docs/development/guides/resources/data/03-add-read-write-relationships.md b/packages/core/docs/development/guides/resources/data/03-add-read-write-relationships.md
new file mode 100644
index 000000000..efc382666
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/data/03-add-read-write-relationships.md
@@ -0,0 +1,128 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog data stores
+- readsFrom
+- writesTo
+sidebar_label: Add read/write relationships
+title: Add read/write relationships
+description: Document which resources read from and write to data stores.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Data stores become more useful when EventCatalog knows which resources read from them and write to them.
+
+Use `writesTo` when a resource stores, appends, or updates data in a data store. Use `readsFrom` when a resource reads, queries, or depends on data from a data store.
+
+## How relationships work
+
+Read/write relationships are defined on the resource that uses the data store.
+
+For example, if `OrdersService` writes to `OrdersDatabase` and reads from `ProductRedisCache`, add `writesTo` and `readsFrom` to the service frontmatter.
+
+```md title="/services/OrdersService/index.mdx"
+---
+id: OrdersService
+name: Orders Service
+version: 1.0.0
+
+# Data stores this service writes to
+writesTo:
+  - id: OrdersDatabase
+
+# Data stores this service reads from
+readsFrom:
+  - id: ProductRedisCache
+    # optional version. If omitted, EventCatalog uses the latest version.
+    version: 1.0.0
+---
+```
+
+## Create the data stores
+
+The referenced data stores still need to exist in your catalog.
+
+<ProjectTree
+  items={[
+    {
+      name: 'containers',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersDatabase',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+        {
+          name: 'ProductRedisCache',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+The `id` values in `readsFrom` and `writesTo` must match the `id` fields in the data store frontmatter.
+
+```md title="/containers/OrdersDatabase/index.mdx"
+---
+id: OrdersDatabase
+name: Orders Database
+version: 1.0.0
+container_type: database
+technology: PostgreSQL
+---
+```
+
+```md title="/containers/ProductRedisCache/index.mdx"
+---
+id: ProductRedisCache
+name: Product Redis Cache
+version: 1.0.0
+container_type: cache
+technology: Redis
+---
+```
+
+## Version matching
+
+You can provide a specific version when linking to a data store.
+
+```md
+readsFrom:
+  - id: ProductRedisCache
+    version: 1.0.0
+```
+
+If no version is provided, EventCatalog uses the latest version.
+
+## Visualize the relationships
+
+When a resource reads from or writes to a data store, EventCatalog can show that relationship in the visualiser and on resource pages.
+
+![Service visualiser showing read and write relationships to data stores](../../img/services/visualiser-with-data.png)
+
+## Next steps
+
+You can use the same relationship pattern when connecting data stores to services and agents.
+
+- [Add data stores to services](/docs/development/guides/resources/services/add-resources-to-services/add-data-stores-to-services)
+- [Add data stores to agents](/docs/development/guides/resources/agents/add-data-stores-to-agents)
diff --git a/packages/core/docs/development/guides/resources/data/04-reference.md b/packages/core/docs/development/guides/resources/data/04-reference.md
new file mode 100644
index 000000000..17209b7cf
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/data/04-reference.md
@@ -0,0 +1,211 @@
+---
+keywords:
+- EventCatalog data stores
+- Data store frontmatter
+sidebar_label: Reference
+title: Data stores reference
+description: Frontmatter fields, paths, and routes for data stores in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by data stores.
+
+## Paths
+
+Data stores use the `containers` collection.
+
+```txt
+/containers/{Data Store Name}/index.mdx
+/services/{Service Name}/containers/{Data Store Name}/index.mdx
+/systems/{System Name}/containers/{Data Store Name}/index.mdx
+```
+
+Versioned data stores use:
+
+```txt
+/containers/{Data Store Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/containers/{container-id}/{version}` | Data store documentation page. |
+| `/visualiser/containers/{container-id}/{version}` | Data store resource diagram. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the data store. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: orders-database
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the data store.
+
+```md title="Example"
+---
+name: Orders Database
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the data store documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short description of the data store.
+
+```md title="Example"
+---
+summary: Stores order state and fulfilment status.
+---
+```
+
+### `container_type` {#container_type}
+
+- Type: `database`, `cache`, `objectStore`, `searchIndex`, `dataWarehouse`, `dataLake`, `externalSaaS`, or `other`
+
+Type of data store.
+
+```md title="Example"
+---
+container_type: database
+---
+```
+
+### `technology` {#technology}
+
+- Type: `string`
+
+Technology used by the data store.
+
+```md title="Example"
+---
+technology: PostgreSQL
+---
+```
+
+### `authoritative` {#authoritative}
+
+- Type: `boolean`
+
+Marks this data store as an authoritative source of data.
+
+```md title="Example"
+---
+authoritative: true
+---
+```
+
+### `access_mode` {#access_mode}
+
+- Type: `read`, `write`, `readWrite`, or `appendOnly`
+
+How consumers interact with the data store.
+
+```md title="Example"
+---
+access_mode: readWrite
+---
+```
+
+### `classification` {#classification}
+
+- Type: `public`, `internal`, `confidential`, or `regulated`
+
+Data classification.
+
+```md title="Example"
+---
+classification: confidential
+---
+```
+
+### `residency` {#residency}
+
+- Type: `string`
+
+Region or residency information.
+
+```md title="Example"
+---
+residency: eu-west-1
+---
+```
+
+### `retention` {#retention}
+
+- Type: `string`
+
+Retention policy or duration.
+
+```md title="Example"
+---
+retention: 7 years
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the data store.
+
+```md title="Example"
+---
+owners:
+  - data-platform
+---
+```
+
+### `services` {#services}
+
+- Type: `array`
+
+Services associated with the data store.
+
+```md title="Example"
+---
+services:
+  - id: order-service
+    version: 1.0.0
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the data store page.
+
+```md title="Example"
+---
+badges:
+  - content: Authoritative
+    backgroundColor: green
+    textColor: green
+---
+```
diff --git a/packages/core/docs/development/guides/resources/data/_category_.json b/packages/core/docs/development/guides/resources/data/_category_.json
new file mode 100644
index 000000000..a63afb913
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/data/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Data Stores",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources/data",
+    "description": "A collection of guides to help you understand data resources and how they work with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/entities/01-introduction.md b/packages/core/docs/development/guides/resources/entities/01-introduction.md
new file mode 100644
index 000000000..94583dfd7
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/entities/01-introduction.md
@@ -0,0 +1,26 @@
+---
+keywords:
+- EventCatalog entities
+- Domain model
+sidebar_label: What are entities?
+title: What are entities?
+description: What are entities? Why are they useful in EventCatalog?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+An entity is a documented business object or concept that your architecture cares about.
+
+Examples of entities include `Order`, `Customer`, `Invoice`, `Payment`, `Shipment` `Product`.
+
+Entities are useful when you want to describe the shape and relationships of your domain model, separate from the services, messages, and systems that use it. For example, in an event-driven system, `OrderCreated` might be the message, `OrderService` might be the producer, and `Order` is the entity that gives the event business meaning.
+
+Entities can be referenced from [Domains](/docs/development/guides/domains/introduction), [Systems](/docs/development/guides/systems/introduction) and [Services](/docs/development/guides/resources/services/introduction).
+
+## Next steps
+
+- [Create an entity](/docs/development/guides/resources/entities/create-entity)
+- [Model entity relationships](/docs/development/guides/resources/entities/model-entity-relationships)
+- [Add entities to resources](/docs/development/guides/resources/entities/add-entities-to-resources)
+- [Visualize entity maps](/docs/development/guides/resources/entities/entity-maps)
+- [Review the entities reference](/docs/development/guides/resources/entities/reference)
diff --git a/packages/core/docs/development/guides/resources/entities/02-create-entity.md b/packages/core/docs/development/guides/resources/entities/02-create-entity.md
new file mode 100644
index 000000000..c06cefec1
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/entities/02-create-entity.md
@@ -0,0 +1,162 @@
+---
+keywords:
+- EventCatalog entities
+sidebar_position: 2
+sidebar_label: Create an entity
+title: Create an entity
+description: Create an entity in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+An entity is a documented business object or concept that your architecture cares about. You can document entity properties, and assign them to any domain, system or service in your architecture.
+
+![Example entity page in EventCatalog](./img/entity-example.png)
+
+## Creating an entity
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog entity">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/entities/create-entity.md and https://www.eventcatalog.dev/docs/development/guides/resources/entities/reference.md then help me create a new EventCatalog entity in my catalog.
+
+Ask me for the entity name, business meaning, summary, identifier field, important properties, relationships to other entities, and where the entity should live. Then create the correct entities/{'{Entity Name}'}/index.mdx, domains/{'{Domain Name}'}/entities/{'{Entity Name}'}/index.mdx, systems/{'{System Name}'}/entities/{'{Entity Name}'}/index.mdx, or services/{'{Service Name}'}/entities/{'{Entity Name}'}/index.mdx file with frontmatter and starter markdown.
+
+Use the EntityPropertiesTable component when it helps explain the properties.
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you decide where the entity should live, define the properties, and create the starter documentation.
+
+### Manual Creation
+
+Most teams start by creating shared entities at the root of the catalog.
+
+<ProjectTree
+  items={[
+    {
+      name: 'entities',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'order',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+        {
+          name: 'customer',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+You can also keep entities inside the resource folder they clearly belong to.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Ordering',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'entities',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'order',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Create the entity file
+
+Create an `index.mdx` file for the entity.
+
+```md title="/entities/order/index.mdx"
+---
+# Unique identifier for the entity. Used in URLs and resource references.
+id: order
+# Friendly display name shown in EventCatalog.
+name: Order
+# Version of this entity documentation.
+version: 1.0.0
+# Short summary shown in lists, sidebars, and previews.
+summary: Represents a customer's purchase.
+# The property that uniquely identifies this entity.
+identifier: orderId
+# Optional. Marks this entity as the aggregate root for the model.
+aggregateRoot: true
+# Teams or users that own this entity.
+owners:
+  - ordering-platform
+# Properties that describe the shape of the entity.
+properties:
+  # Unique identifier for this order.
+  - name: orderId
+    # Data type for the property.
+    type: string
+    # Whether this property is required.
+    required: true
+    # Human-readable description of what the property represents.
+    description: Unique identifier for the order.
+  # Identifier for the customer that placed the order.
+  - name: customerId
+    # Data type for the property.
+    type: string
+    # Whether this property is required.
+    required: true
+    # Human-readable description of what the property represents.
+    description: Customer that placed the order.
+    # Entity this property references.
+    references: customer
+    # Label used to describe the relationship in entity maps.
+    relationType: placedBy
+    # Identifier property on the referenced entity.
+    referencesIdentifier: customerId
+  # Current lifecycle state of the order.
+  - name: status
+    # Data type for the property.
+    type: string
+    # Whether this property is required.
+    required: true
+    # Human-readable description of what the property represents.
+    description: Current lifecycle state of the order.
+---
+
+## Overview
+
+The Order entity represents a customer's purchase and tracks the state required to fulfil, pay for, and ship that purchase.
+
+<EntityPropertiesTable />
+```
+
+
+## Next steps
+
+- [Model entity relationships](/docs/development/guides/resources/entities/model-entity-relationships)
+- [Add entities to resources](/docs/development/guides/resources/entities/add-entities-to-resources)
+- [Visualize entity maps](/docs/development/guides/resources/entities/entity-maps)
+- [Review the entities reference](/docs/development/guides/resources/entities/reference)
diff --git a/packages/core/docs/development/guides/resources/entities/03-model-entity-relationships.md b/packages/core/docs/development/guides/resources/entities/03-model-entity-relationships.md
new file mode 100644
index 000000000..2a0c5652f
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/entities/03-model-entity-relationships.md
@@ -0,0 +1,115 @@
+---
+keywords:
+- EventCatalog entities
+- Entity relationships
+sidebar_position: 3
+sidebar_label: Model relationships
+title: Model entity relationships
+description: Model relationships between entities in EventCatalog.
+---
+
+Entity relationships are defined on entity properties.
+
+Use relationships when one entity property identifies or points to another entity. For example, an `Order` might have a `customerId` property that references `Customer`, and an `OrderItem` might have an `orderId` property that references `Order`.
+
+```mermaid
+erDiagram
+  direction LR
+  CUSTOMER ||--o{ ORDER : places
+  ORDER ||--o{ ORDER_ITEM : contains
+
+  CUSTOMER {
+    string customerId
+    string name
+  }
+
+  ORDER {
+    string orderId
+    string customerId
+    string status
+  }
+
+  ORDER_ITEM {
+    string orderItemId
+    string orderId
+    string productId
+  }
+```
+
+## Relationship fields
+
+Use these fields on an entity property:
+
+- `references`: The id of the entity being referenced.
+- `referencesIdentifier`: The property on the referenced entity that this property matches.
+- `relationType`: The relationship label, such as `belongsTo`, `hasOne`, `hasMany`, or a business-specific label.
+
+## Example relationship
+
+```md title="/entities/order/index.mdx"
+---
+# Unique identifier for the entity. Used in URLs and resource references.
+id: order
+# Friendly display name shown in EventCatalog.
+name: Order
+# Version of this entity documentation.
+version: 1.0.0
+# The property that uniquely identifies this entity.
+identifier: orderId
+# Properties that describe the shape of the entity.
+properties:
+  # Unique identifier for this order.
+  - name: orderId
+    # Data type for the property.
+    type: string
+    # Whether this property is required.
+    required: true
+  # Identifier for the customer that placed the order.
+  - name: customerId
+    # Data type for the property.
+    type: string
+    # Whether this property is required.
+    required: true
+    # Human-readable description of what the property represents.
+    description: Customer that placed the order.
+    # Entity this property references.
+    references: customer
+    # Label used to describe the relationship in entity maps.
+    relationType: placedBy
+    # Identifier property on the referenced entity.
+    referencesIdentifier: customerId
+---
+```
+
+This tells EventCatalog that `order.customerId` references the `customer.customerId` identifier.
+
+## Relationship direction
+
+Define the relationship where the reference exists.
+
+If `Order` has a `customerId`, define the relationship on the `customerId` property in `Order`. You do not need to add the inverse relationship to `Customer` unless that relationship is useful to document explicitly.
+
+## Keep relationship labels useful
+
+Use relationship labels that help readers understand the business model.
+
+Good examples include:
+
+- `placedBy`
+- `belongsTo`
+- `contains`
+- `paysFor`
+- `shipsTo`
+
+Avoid labels that only repeat implementation detail, such as `foreignKey`.
+
+## Visual output
+
+When entities are attached to a domain or service, EventCatalog can use these relationships to generate an entity map.
+
+![Entity Map showing a relationship between OrderItem and Order](./img/simple-entity-map.png)
+
+## Next steps
+
+- [Add entities to resources](/docs/development/guides/resources/entities/add-entities-to-resources)
+- [Visualize entity maps](/docs/development/guides/resources/entities/entity-maps)
diff --git a/packages/core/docs/development/guides/resources/entities/04-add-entities-to-resources.md b/packages/core/docs/development/guides/resources/entities/04-add-entities-to-resources.md
new file mode 100644
index 000000000..bf0d776d7
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/entities/04-add-entities-to-resources.md
@@ -0,0 +1,188 @@
+---
+keywords:
+- EventCatalog entities
+- Entity resources
+sidebar_position: 4
+sidebar_label: Add entities to resources
+title: Add entities to resources
+description: Add entities to domains, systems, and services in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Adding [entities](/docs/development/guides/resources/entities/introduction) to resources helps people understand which business concepts a domain, system, or service owns, uses, or documents.
+
+In EventCatalog, entities can be connected to:
+
+- [Domains](/docs/development/guides/domains/introduction)
+- [Systems](/docs/development/guides/systems/introduction)
+- [Services](/docs/development/guides/resources/services/introduction)
+
+## Add entities using frontmatter
+
+Add entities to a resource using the `entities` array in the resource frontmatter.
+
+```md title="/domains/Ordering/index.mdx"
+---
+id: ordering
+name: Ordering
+version: 1.0.0
+# define entities that belong to this domain
+entities:
+  - id: order
+    version: 1.0.0
+  - id: customer
+---
+```
+
+You can use the same pattern for systems:
+
+```md title="/domains/Ordering/systems/order-management/index.mdx"
+---
+id: order-management
+name: Order Management
+version: 1.0.0
+# define entities that are part of this system
+entities:
+  - id: order
+  - id: shipment
+---
+```
+
+And services:
+
+```md title="/services/OrderService/index.mdx"
+---
+id: order-service
+name: Order Service
+version: 1.0.0
+# define entities this service owns, reads, writes, or exposes
+entities:
+  - id: order
+  - id: customer
+---
+```
+
+The `version` is optional. If no version is given, EventCatalog uses the latest version of the referenced entity.
+
+## Keep entities inside the resource folder
+
+You can also define entities inside a resource folder to keep related business model documentation together.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Ordering',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'entities',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'Order',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+                {
+                  name: 'Customer',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This structure makes the domain the entry point for the entities that belong to that business boundary.
+
+Entities can also live inside services:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrderService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'entities',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'Order',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This structure is useful when the entity is owned by, exposed by, or tightly coupled to one service.
+
+## Keep shared entities at the root
+
+Entities can live at the root of the catalog when they are shared across multiple domains, systems, or services.
+
+<ProjectTree
+  items={[
+    {
+      name: 'entities',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Customer',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+        {
+          name: 'Payment',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Use frontmatter when the entity is shared across multiple resources. Keep the entity inside a resource folder when the entity is owned by that resource and should move with it.
+
+## Show entities on resource pages
+
+When a domain, service, or system references entities, EventCatalog shows that relationship on the resource page.
+
+Domains and services can also show entity maps, which help people understand the entity relationships inside that part of your architecture.
+
+Learn more in [entity maps](/docs/development/guides/resources/entities/entity-maps) and [model entity relationships](/docs/development/guides/resources/entities/model-entity-relationships).
+
+For the complete list of supported fields, see the [entities reference](/docs/development/guides/resources/entities/reference).
diff --git a/packages/core/docs/development/guides/resources/entities/05-entity-maps.md b/packages/core/docs/development/guides/resources/entities/05-entity-maps.md
new file mode 100644
index 000000000..5d95a1cf5
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/entities/05-entity-maps.md
@@ -0,0 +1,48 @@
+---
+keywords:
+- EventCatalog entities
+- Entity maps
+sidebar_position: 5
+sidebar_label: Entity maps
+title: Entity maps
+description: Visualize entity relationships in EventCatalog.
+---
+
+Entity maps help teams understand the relationships between business concepts.
+
+When entities are assigned to a domain or service, EventCatalog can create an entity map that shows:
+
+- The entities assigned to that resource.
+- Relationships between those entities.
+- Entities referenced from outside the current resource.
+- Which entities are owned by the current domain or service context.
+
+![Entity Map](./img/entity-map.png)
+
+## Open an entity map in the visualizer
+
+Domains and services have dedicated entity map routes:
+
+```txt
+/visualiser/domains/{id}/{version}/entity-map
+/visualiser/services/{id}/{version}/entity-map
+```
+
+When a domain or service has entities assigned, an **Entity Map** link appears automatically in the resource sidebar under the visualizer section.
+
+## Embed an entity map
+
+You can also embed an entity map on a page using the `<EntityMap />` component.
+
+```mdx
+<EntityMap id="ordering" title="Ordering Entity Map" />
+```
+
+![Entity Map Component](./img/entity-map-component.png)
+
+Use embedded entity maps when you want the model to appear directly in domain, service, or custom documentation.
+
+## Next steps
+
+- [Model entity relationships](/docs/development/guides/resources/entities/model-entity-relationships)
+- [EntityMap component reference](/docs/development/components/components/entitymap)
diff --git a/packages/core/docs/development/guides/resources/entities/06-reference.md b/packages/core/docs/development/guides/resources/entities/06-reference.md
new file mode 100644
index 000000000..faaa5791a
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/entities/06-reference.md
@@ -0,0 +1,273 @@
+---
+keywords:
+- EventCatalog entities
+- Entity frontmatter
+sidebar_position: 6
+sidebar_label: Reference
+title: Entities reference
+description: Frontmatter fields, paths, and routes for entities in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by entities.
+
+## Paths
+
+Entities can be created at the root of your catalog:
+
+```txt
+/entities/{Entity Name}/index.mdx
+```
+
+Entities can also be created inside domains, systems, or services:
+
+```txt
+/domains/{Domain Name}/entities/{Entity Name}/index.mdx
+/systems/{System Name}/entities/{Entity Name}/index.mdx
+/domains/{Domain Name}/systems/{System Name}/entities/{Entity Name}/index.mdx
+/services/{Service Name}/entities/{Entity Name}/index.mdx
+```
+
+Versioned entities use:
+
+```txt
+/entities/{Entity Name}/versioned/{version}/index.mdx
+```
+
+Nested entities use the same `versioned/{version}/index.mdx` pattern inside their entity folder.
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/entities/{entity-id}/{version}` | Entity documentation page. |
+| `/visualiser/entities/{entity-id}/{version}` | Entity resource diagram. |
+| `/visualiser/domains/{domain-id}/{version}/entity-map` | Entity map for entities assigned to a domain. |
+| `/visualiser/services/{service-id}/{version}/entity-map` | Entity map for entities assigned to a service. |
+
+## Frontmatter example
+
+```md
+---
+# Unique identifier for the entity. Used in URLs and resource references.
+id: order
+# Friendly display name shown in EventCatalog.
+name: Order
+# Version of this entity documentation.
+version: 1.0.0
+# Short summary shown in lists, sidebars, and previews.
+summary: Represents a customer's purchase.
+# The property that uniquely identifies this entity.
+identifier: orderId
+# Optional. Marks this entity as the aggregate root for the model.
+aggregateRoot: true
+# Teams or users that own this entity.
+owners:
+  - ordering-platform
+# Properties that describe the shape of the entity.
+properties:
+  # Unique identifier for this order.
+  - name: orderId
+    # Data type for the property.
+    type: string
+    # Whether this property is required.
+    required: true
+    # Human-readable description of what the property represents.
+    description: Unique order identifier.
+  # Identifier for the customer that placed the order.
+  - name: customerId
+    # Data type for the property.
+    type: string
+    # Whether this property is required.
+    required: true
+    # Human-readable description of what the property represents.
+    description: Customer that placed the order.
+    # Entity this property references.
+    references: customer
+    # Label used to describe the relationship in entity maps.
+    relationType: placedBy
+    # Identifier property on the referenced entity.
+    referencesIdentifier: customerId
+  # Current lifecycle state of the order.
+  - name: status
+    # Data type for the property.
+    type: string
+    # Allowed values for the property.
+    enum:
+      - pending
+      - confirmed
+      - cancelled
+---
+```
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the entity. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: order
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the entity.
+
+```md title="Example"
+---
+name: Order
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the entity documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short summary of what the entity represents.
+
+```md title="Example"
+---
+summary: Represents a customer's purchase.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the entity.
+
+```md title="Example"
+---
+owners:
+  - ordering-platform
+---
+```
+
+### `aggregateRoot` {#aggregateRoot}
+
+- Type: `boolean`
+
+Marks the entity as an aggregate root.
+
+```md title="Example"
+---
+aggregateRoot: true
+---
+```
+
+### `identifier` {#identifier}
+
+- Type: `string`
+
+The property that uniquely identifies the entity.
+
+```md title="Example"
+---
+identifier: orderId
+---
+```
+
+### `properties` {#properties}
+
+- Type: `array`
+
+Properties that describe the shape of the entity.
+
+```md title="Example"
+---
+properties:
+  - name: orderId
+    type: string
+    required: true
+    description: Unique order identifier.
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the entity page.
+
+```md title="Example"
+---
+badges:
+  - content: Aggregate root
+    backgroundColor: blue
+    textColor: blue
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the entity.
+
+```md title="Example"
+---
+repository:
+  language: TypeScript
+  url: https://github.com/acme/orders
+---
+```
+
+### `attachments` {#attachments}
+
+- Type: `array`
+
+External links or supporting documents attached to the entity.
+
+```md title="Example"
+---
+attachments:
+  - title: Order model runbook
+    url: https://runbooks.example.com/orders
+    type: runbook
+---
+```
+
+## Property fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Property name. |
+| `type` | `string` | Property type, such as `string`, `UUID`, `datetime`, or another entity name. |
+| `required` | `boolean` | Whether the property is required. |
+| `description` | `string` | Description of the property. |
+| `references` | `string` | Entity id referenced by this property. |
+| `referencesIdentifier` | `string` | Identifier property on the referenced entity. |
+| `relationType` | `string` | Relationship label shown in entity maps. |
+| `enum` | `array` | Allowed string values. |
+| `items` | `object` | Item type for array properties. |
+
+## EntityPropertiesTable component
+
+Use `<EntityPropertiesTable />` in the entity Markdown body to render the entity properties as a table.
+
+```mdx
+<EntityPropertiesTable />
+```
+
+This is useful when you want the documentation page to show the same properties defined in frontmatter.
diff --git a/packages/core/docs/development/guides/resources/entities/_category_.json b/packages/core/docs/development/guides/resources/entities/_category_.json
new file mode 100644
index 000000000..1a4debdd3
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/entities/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Entities",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources/entities",
+    "description": "A collection of guides to help you understand entities and how they work with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/flows/01-introduction.md b/packages/core/docs/development/guides/resources/flows/01-introduction.md
new file mode 100644
index 000000000..c88c5b457
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/flows/01-introduction.md
@@ -0,0 +1,28 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog flows
+- Flows
+sidebar_label: What are flows?
+title: Understanding flows
+description: What are flows? Why are they useful for event-driven architectures?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Flows are a way to document business workflows in your organization. Flows help teams understand end-to-end flows across your organization and architecture.
+
+An example of a flow could be user purchasing a product in an e-commerce store. They start by logging into a service, getting onboarded and purchasing something from a business. Across this journey may applications, databases, interactions are happening. Flows let you capture these.
+
+You can reuse your documented resources (e.g services, messages, data stores, data products) in your flows.
+
+![Example](../../img/flows/flow-example.png)
+
+<!-- [You can see a payment flow example here](https://demo.eventcatalog.dev/visualiser/flows/PaymentFlow/1.0.0). -->
+
+
+<!-- 
+### Further reading
+- [Event-driven architecture and domain-driven design](https://eda-visuals.boyney.io/visuals/eda-and-ddd)
+- [Domain, Subdomain, Bounded Context: Problem/Solution Space in DDD: Clearly Defined](https://medium.com/nick-tune-tech-strategy-blog/domains-subdomain-problem-solution-space-in-ddd-clearly-defined-e0b49c7b586c)
+- [Building Blocks of DDD](https://redis.io/glossary/domain-driven-design-ddd/) -->
diff --git a/packages/core/docs/development/guides/resources/flows/02-create-flow.md b/packages/core/docs/development/guides/resources/flows/02-create-flow.md
new file mode 100644
index 000000000..199fdc03e
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/flows/02-create-flow.md
@@ -0,0 +1,304 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog flows
+sidebar_label: Create a flow
+title: Create a flow
+description: Creating and managing flows within EventCatalog.
+---
+
+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="2.5.0" />
+
+Flows document business processes, user journeys, and architecture workflows across your catalog.
+
+Users can step through flows step by step, and your flows can reference any resource in EventCatalog or define custom nodes.
+
+![Example flow page in EventCatalog](../../img/flows/flow-example.png)
+
+## Creating a flow
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog flow">
+Read https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/flow-wizard/SKILL.md and follow that wizard.
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you identify the steps, connect them, choose where the flow should live, and create the first version of the flow documentation.
+
+:::tip EventCatalog Skills
+You can install the EventCatalog Skills (https://github.com/event-catalog/skills/tree/main/skills/flow-wizard) and use the [flow-wizard](https://github.com/event-catalog/skills/tree/main/skills/flow-wizard) skill to help you document your business workflow. Use natural language and your LLM will do the rest.
+:::
+
+### Manual Creation
+
+Flows live in a `flows` folder. EventCatalog discovers any `index.mdx` file inside a `flows` directory, regardless of where that directory lives in your catalog.
+
+You can place flows:
+
+At the root of your catalog:
+
+<ProjectTree
+  items={[
+    {
+      name: 'flows',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'cancel-subscription',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a domain:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Subscriptions',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'flows',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cancel-subscription',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Inside a service:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'SubscriptionService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'flows',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cancel-subscription',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+## Create the flow file
+
+Create an `index.mdx` file for the flow.
+
+_Here is an example of what a flow file may look like._
+
+```md title="/flows/CancelSubscription/index.mdx (example)"
+---
+id: "CancelSubscription"
+name: "User Cancels Subscription"
+version: "0.0.1"
+summary: "Flow for when a user has cancelled a subscription"
+steps:
+  - id: "cancel_subscription_initiated"
+    title: "Cancels Subscription"
+    summary: "User cancels their subscription"
+    # define the actor for, in this case it's a user.
+    actor:
+      name: "User"
+    # What happens next? Define the next step  
+    next_step: 
+      id: "cancel_subscription_request"
+      label: "Initiate subscription cancellation"
+
+  - id: "cancel_subscription_request"
+    title: "Cancel Subscription"
+    # This step is a message, include the message and version
+    message:
+      id: "CancelSubscription"
+      version: "0.0.1"
+    next_step: 
+      id: "subscription_service"
+      label: "Proceed to subscription service"
+
+  - id: "stripe_integration"
+    title: "Stripe"
+    # This is an external system (e.g Stripe)
+    externalSystem:
+      name: "Stripe"
+      summary: "3rd party payment system"
+      url: "https://stripe.com/"
+    next_step: 
+      id: "subscription_service"
+      label: "Return to subscription service"
+
+  - id: "subscription_service"
+    title: "Subscription Service"
+    # This node is a service, include that.
+    service:
+      id: "SubscriptionService"
+      version: "0.0.1"
+    # Define multiple steps
+    next_steps:
+      - id: "stripe_integration"
+        label: "Cancel subscription via Stripe"
+      - id: "subscription_cancelled"
+        label: "Successful cancellation"
+      - id: "subscription_rejected"
+        label: "Failed cancellation"
+
+  - id: "subscription_cancelled"
+    title: "Subscription has been Cancelled"
+    message:
+      id: "UserSubscriptionCancelled"
+      version: "0.0.1"
+    next_step:
+      id: "notification_service"
+      label: "Email customer"
+
+  - id: "subscription_rejected"
+    title: "Subscription cancellation has been rejected"
+
+  - id: "notification_service"
+    title: "Notifications Service"
+    service:
+      id: "NotificationService"
+      version: "0.0.2"
+
+---
+
+This flow documents what happens when a User Cancels Subscription in our system. 
+
+<NodeGraph />
+
+<!-- Add any markdown you want, the workflow will also render in its own page /docs/flows/{Flow}/{version} -->
+
+```
+
+Once this file is added, the flow will automatically appear in EventCatalog.
+
+## Add subflows / reuseable flows
+
+You can reference a flow from another flow. This lets you reuse flows in your flow diagrams, useful if you have complex flows that reuse information from another flow.
+
+You can also group related flows by placing them in subdirectories inside any `flows` folder. EventCatalog discovers them regardless of nesting depth.
+
+<ProjectTree
+  items={[
+    {
+      name: 'flows',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Payments',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'ProcessPayment',
+              type: 'folder',
+              defaultOpen: true,
+              children: [{ name: 'index.mdx', highlight: true }],
+            },
+            {
+              name: 'RefundPayment',
+              type: 'folder',
+              defaultOpen: true,
+              children: [{ name: 'index.mdx', highlight: true }],
+            },
+          ],
+        },
+        {
+          name: 'Subscriptions',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'CancelSubscription',
+              type: 'folder',
+              defaultOpen: true,
+              children: [{ name: 'index.mdx', highlight: true }],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The flow `id` in your frontmatter is what EventCatalog uses for routing and references. The directory structure is purely for organization.
+
+To reference a flow from another flow, use the `flow` node type.
+
+```yml
+steps:
+  - id: "step-1"
+    title: "Example Step of a Event"
+    flow:
+      id: "order-flow"
+      version: 0.0.1
+```
+
+This will render the `order-flow` within the described flow.
+Right clicking on the `order-flow` node will let you navigate to the referenced flow.
+
+### Expand sub-flows inline
+
+Click any sub-flow node in the visualiser to expand its steps inline inside the parent flow diagram. Click the Collapse button in the expanded node's header to restore the single-node view.
+
+![Expanded sub-flow showing inline steps inside a parent flow diagram](/img/docs/subflow-assets/subflow-expanded.png)
+
+Expanded steps participate in the step-by-step walkthrough, so you can navigate through them using the next/previous controls without leaving the parent flow. Nested sub-flows (a sub-flow that itself references another flow) also expand correctly.
+
+### Tips for flow content
+
+It's entirely up to you what you want to add to your flows markdown content but here are a few things you might want to consider.
+
+- Context of the flow. What is it? Why does it exist?
+- Examples of how to trigger the flow?
+- Any edit/contributing guidelines?
+
+[See a flow example](https://demo.eventcatalog.dev/visualiser/flows/PaymentFlow/1.0.0).
diff --git a/packages/core/docs/development/guides/resources/flows/03-model-flow-steps.md b/packages/core/docs/development/guides/resources/flows/03-model-flow-steps.md
new file mode 100644
index 000000000..652a67b36
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/flows/03-model-flow-steps.md
@@ -0,0 +1,357 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog flows
+sidebar_label: Model flow steps
+title: Model flow steps
+description: Flow step types within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<!-- <AddedIn version="2.5.0" /> -->
+
+Nodes are the building blocks of flows. They are used to represent the different steps in a flow.
+
+With flow nodes you can reference your services, events, commands and queries, external services, users (actors), data stores, data products, or create your own custom nodes.
+
+## Common step properties
+
+Every flow step (regardless of node type) supports these properties:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string \| number` | **Yes** | Unique identifier for the step |
+| `title` | `string` | **Yes** | The label displayed on the node in the flow diagram |
+| `summary` | `string` | No | A short description shown in the node sidebar |
+| `type` | `"node" \| "message" \| "user" \| "actor"` | No | Hint for how the node should be rendered |
+| `next_step` | [Step reference](#connecting-steps) | No | The next step in the flow (cannot be used with `next_steps`) |
+| `next_steps` | [Step reference](#connecting-steps)[] | No | Multiple next steps for branching (cannot be used with `next_step`) |
+
+:::tip Type exclusivity rule
+Each step can only use **one** node type property. You cannot combine `message`, `service`, `flow`, `container`, `dataProduct`, `actor`, `custom`, or `externalSystem` on the same step.
+:::
+
+## Connecting steps {#connecting-steps}
+
+Use `next_step` or `next_steps` (not both) to connect steps together.
+
+A step reference can be:
+- A **string or number** matching another step's `id` (e.g. `next_step: "step-2"`)
+- An **object** with `id` and an optional `label` for the edge
+
+```yml
+# Simple reference
+next_step: "step-2"
+
+# Reference with edge label
+next_step:
+  id: "step-2"
+  label: "on success"
+
+# Multiple next steps (branching)
+next_steps:
+  - id: "step-success"
+    label: "on success"
+  - id: "step-failure"
+    label: "on failure"
+```
+
+## Flow node types
+
+- [default](#default) — A blank node type with just a title in your flow
+- [actor](#actor) — Represents a person in your flow diagram
+- [externalSystem](#externalsystem) — Represents an external system in your flow diagram
+- [message](#message) — Represents an event, command or query resource in EventCatalog
+- [service](#service) — Represents a service resource in EventCatalog
+- [agent](#agent) — Represents an agent resource in EventCatalog (added in EventCatalog 3.41.0)
+- [flow](#flow) — Represents a flow in EventCatalog (added in EventCatalog 2.34.2)
+- [container](#container) — Represents a data store (container) resource in EventCatalog
+- [dataProduct](#dataproduct) — Represents a data product resource in EventCatalog
+- [custom](#custom) — A custom node type with configurable title, summary, icon, properties and more
+
+
+### default node type {#default}
+
+A blank node type with just a title in your flow. No additional properties are needed beyond the [common step properties](#common-step-properties).
+
+```yml
+steps:
+  - id: "step-1"
+    title: "This value will be shown in the node on the flow diagram"
+```
+
+---
+
+### actor
+
+Actor represents a person in your flow diagram.
+
+#### Actor properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | `string` | **Yes** | The name of the actor |
+| `summary` | `string` | No | A short description of the actor (added in EventCatalog 2.55.6) |
+
+```yml
+steps:
+  - id: "step-1"
+    title: "Example Step of a Actor"
+    actor:
+      name: "Dave"
+      summary: "This is a summary of the actor"
+```
+
+---
+
+### externalSystem
+
+Represents an external system in your flow diagram.
+
+#### External system properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | `string` | **Yes** | The name of the external system |
+| `summary` | `string` | No | A short description of the external system |
+| `url` | `string` (valid URL) | No | A link to the external system |
+
+```yml
+steps:
+  - id: "step-1"
+    title: "Example Step of a externalSystem"
+    externalSystem:
+      name: "Google"
+      summary: "Search engine"
+      url: "https://google.com"
+```
+
+---
+
+### message
+
+Represents and refers to an event, command or query resource in EventCatalog.
+
+#### Message properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | **Yes** | The id of the event, command or query in your catalog |
+| `version` | `string` | No | The version to reference (defaults to `latest`) |
+
+```yml
+steps:
+  - id: "step-1"
+    title: "Example Step of a Event"
+    message:
+      id: "order-placed"
+      version: "0.0.1"
+```
+
+---
+
+### service
+
+Represents and refers to a service resource in EventCatalog.
+
+#### Service properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | **Yes** | The id of the service in your catalog |
+| `version` | `string` | No | The version to reference (defaults to `latest`) |
+
+```yml
+steps:
+  - id: "step-1"
+    title: "Example Step of a Service"
+    service:
+      id: "order-service"
+      version: "0.0.1"
+```
+
+---
+
+### agent {#agent}
+
+<AddedIn version="3.41.0" />
+
+Represents and refers to an [agent](/docs/development/guides/resources/agents/introduction) resource in EventCatalog. Agents render as purple/violet nodes in the visualiser so they are easy to distinguish from services. When a flow references an agent, the agent's page shows a back-link to the flow.
+
+#### Agent properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | **Yes** | The id of the agent in your catalog |
+| `version` | `string` | No | The version to reference (defaults to `latest`) |
+
+```yml
+steps:
+  - id: "fraud_review"
+    title: "Fraud Review Agent"
+    agent:
+      id: "FraudReviewAgent"
+      version: "0.0.1"
+    next_steps:
+      - id: "payment_approved"
+        label: "Approved"
+      - id: "payment_declined"
+        label: "Declined"
+```
+
+---
+
+### flow
+
+<AddedIn version="2.34.2" />
+
+Represents and refers to a flow resource in EventCatalog. Useful for reusing flows in your flow diagrams.
+
+#### Flow properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | **Yes** | The id of the flow in your catalog |
+| `version` | `string` | No | The version to reference (defaults to `latest`) |
+
+```yml
+steps:
+  - id: "step-1"
+    title: "Example Step of a Flow"
+    flow:
+      id: "order-flow"
+      version: "0.0.1"
+```
+
+#### Expand inline
+
+<AddedIn version="3.29.0" />
+
+Click a flow node in the visualiser to expand the referenced flow's steps inline. Use the Collapse button in the expanded node's header to restore the single-node view. The graph recentres automatically on both expand and collapse, and expanded steps join the parent flow's step walkthrough navigation.
+
+---
+
+### container
+
+<AddedIn version="3.36.3" />
+
+Represents and refers to a data store (container) resource in EventCatalog. When a flow references a container, the container's sidebar automatically shows a "Flows" section linking back to the referencing flow.
+
+#### Container properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | **Yes** | The id of the container in your catalog |
+| `version` | `string` | No | The version to reference (defaults to `latest`) |
+
+```yml
+steps:
+  - id: "orders_db"
+    title: "Orders DB"
+    container:
+      id: "orders-db"
+      version: "1.0.0"
+    next_step:
+      id: "next_step"
+      label: "Persist order records"
+```
+
+---
+
+### dataProduct
+
+<AddedIn version="3.36.3" />
+
+Represents and refers to a data product resource in EventCatalog. When a flow references a data product, the data product's sidebar automatically shows a "Flows" section linking back to the referencing flow.
+
+#### Data product properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | `string` | **Yes** | The id of the data product in your catalog |
+| `version` | `string` | No | The version to reference (defaults to `latest`) |
+
+```yml
+steps:
+  - id: "order_analytics"
+    title: "Order Analytics"
+    dataProduct:
+      id: "order-analytics"
+      version: "1.0.0"
+    next_step:
+      id: "next_step"
+      label: "Prepare fulfillment KPIs"
+```
+
+---
+
+### custom
+
+<AddedIn version="2.30.6" />
+
+The custom node allows you to define any custom node you want in your flow diagram.
+
+Use cases could include:
+
+- A custom node that represents a scheduled job
+- A custom node that represents a batch job
+- A custom node that represents a decision
+- A custom node that represents a process
+- A custom node that represents an aggregate
+
+**Custom nodes can be anything you want.**
+
+You can view a UI example of a custom nodes [here](https://demo.eventcatalog.dev/visualiser/flows/SubscriptionRenewed/1.0.0).
+
+#### Custom node properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `title` | `string` | **Yes** | The title shown on the node |
+| `icon` | `string` | No | Icon shown on the node (see [Heroicons](https://heroicons.com/) for the list of icons) |
+| `type` | `string` | No | A type label shown on the sidebar of the node (e.g. "Scheduler", "Database") |
+| `summary` | `string` | No | A short description of the node |
+| `url` | `string` (valid URL) | No | A link associated with the custom node |
+| `color` | `string` | No | The color of the node (see [Tailwind colors](https://tailwindcss.com/docs/colors)) |
+| `properties` | `Record<string, string \| number>` | No | Key-value pairs shown in the node. URL values are rendered as links |
+| `height` | `number` | No | The height of the node (be careful going too high, the diagram does not calculate the graph based on the height of nodes) |
+| `menu` | `{ label: string, url?: string }[]` | No | Right-click context menu items |
+
+**UI Example**
+
+<img src="/img/custom-flow.png" alt="Custom Node" style={{width: "50%"}} />
+
+---
+
+**MDX Example**
+
+This example shows a custom node that represents a scheduler.
+
+```yml
+steps:
+  - id: "renewal_timer_triggered"
+    title: "Renewal Period Reached"
+    custom:
+      title: "Renewal Timer"
+      color: "orange"
+      icon: "ClockIcon"
+      type: "Scheduler"
+      summary: "Automated timer triggers the subscription renewal process"
+      height: 8
+      properties:
+        subscription_id: "sub_12345678"
+        renewal_type: "Automatic"
+        billing_cycle: "Monthly"
+        next_billing_date: "2024-08-01"
+      menu:
+        - label: "View scheduler configuration"
+          url: "https://docs.example.com/scheduler"
+        - label: "Subscription timing documentation"
+          url: "https://docs.example.com/subscription-timing"
+    next_step:
+      id: "check_subscription_status"
+      label: "Verify subscription status"
+```
+
+You can find a full example on GitHub [here](https://raw.githubusercontent.com/event-catalog/eventcatalog/refs/heads/main/examples/default/domains/Subscriptions/flows/SubscriptionRenewed/index.mdx).
diff --git a/packages/core/docs/development/guides/resources/flows/04-add-flows-to-resources.md b/packages/core/docs/development/guides/resources/flows/04-add-flows-to-resources.md
new file mode 100644
index 000000000..498a7b027
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/flows/04-add-flows-to-resources.md
@@ -0,0 +1,149 @@
+---
+keywords:
+- EventCatalog flows
+sidebar_position: 4
+sidebar_label: Add flows to resources
+title: Add flows to resources
+description: Associate flows with domains, services, and systems in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Adding [flows](/docs/development/guides/resources/flows/introduction) to resources helps people understand where a business process belongs and which parts of the architecture participate in it.
+
+In EventCatalog, flows can be connected to:
+
+- [Domains](/docs/development/guides/domains/introduction)
+- [Systems](/docs/development/guides/systems/introduction)
+- [Services](/docs/development/guides/resources/services/introduction)
+
+## Add flows using frontmatter
+
+Add flows to a resource using the `flows` array in the resource frontmatter.
+
+```md title="/services/Orders/index.mdx"
+---
+id: OrdersService
+name: Orders Service
+version: 1.0.0
+# define flows this service participates in
+flows:
+  - id: OrderProcessing
+    version: 1.0.0
+  - id: PaymentFlow
+---
+```
+
+You can use the same pattern for domains:
+
+```md title="/domains/Orders/index.mdx"
+---
+id: OrdersDomain
+name: Orders
+version: 1.0.0
+# define flows that belong to this domain
+flows:
+  - id: OrderProcessing
+    version: 1.0.0
+---
+```
+
+And systems:
+
+```md title="/domains/Orders/systems/order-management/index.mdx"
+---
+id: order-management
+name: Order Management
+version: 1.0.0
+# define flows that are part of this system
+flows:
+  - id: OrderProcessing
+    version: 1.0.0
+---
+```
+
+The `version` is optional. If no version is given, EventCatalog uses the latest version of the referenced flow.
+
+## Keep flows inside the resource folder
+
+You can also define flows inside a resource folder to keep related process documentation together.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'flows',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderProcessing',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This structure makes the domain the entry point for the flows that belong to that business area.
+
+Flows can also live inside services:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersService',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'flows',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderProcessing',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This structure is useful when the flow is specific to one service.
+
+## Show flows on resource pages
+
+When a domain, service, or system references a flow, EventCatalog shows that relationship on the resource page and in the visualizer.
+
+Use frontmatter when the flow is shared across multiple resources. Keep the flow inside a resource folder when the flow is owned by that resource and should move with it.
+
+For the complete list of supported fields, see the [flows reference](/docs/development/guides/resources/flows/reference).
diff --git a/packages/core/docs/development/guides/resources/flows/06-reference.md b/packages/core/docs/development/guides/resources/flows/06-reference.md
new file mode 100644
index 000000000..6e85c8d9b
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/flows/06-reference.md
@@ -0,0 +1,226 @@
+---
+keywords:
+- EventCatalog flows
+- Flow frontmatter
+sidebar_position: 6
+sidebar_label: Reference
+title: Flows reference
+description: Frontmatter fields, paths, and routes for flows in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by flows.
+
+## Paths
+
+Flows can be created in any `flows` folder:
+
+```txt
+/flows/{Flow Name}/index.mdx
+/domains/{Domain Name}/flows/{Flow Name}/index.mdx
+/services/{Service Name}/flows/{Flow Name}/index.mdx
+```
+
+Versioned flows use:
+
+```txt
+/flows/{Flow Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/flows/{flow-id}/{version}` | Flow documentation page. |
+| `/visualiser/flows/{flow-id}/{version}` | Flow diagram. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the flow. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: checkout-flow
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the flow.
+
+```md title="Example"
+---
+name: Checkout Flow
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the flow documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short description of the flow.
+
+```md title="Example"
+---
+summary: Describes the steps from checkout start to order confirmation.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the flow.
+
+```md title="Example"
+---
+owners:
+  - checkout-platform
+---
+```
+
+### `steps` {#steps}
+
+- Type: `array`
+
+Ordered steps in the flow.
+
+```md title="Example"
+---
+steps:
+  - id: submit-order
+    title: Submit order
+    message:
+      id: SubmitOrder
+    next_step: authorize-payment
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the flow page.
+
+```md title="Example"
+---
+badges:
+  - content: Critical path
+    backgroundColor: red
+    textColor: red
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the flow.
+
+```md title="Example"
+---
+repository:
+  language: TypeScript
+  url: https://github.com/acme/checkout
+---
+```
+
+### `diagrams` {#diagrams}
+
+- Type: `array`
+
+Diagrams associated with the flow.
+
+```md title="Example"
+---
+diagrams:
+  - id: checkout-sequence
+    version: 1.0.0
+---
+```
+
+### `attachments` {#attachments}
+
+- Type: `array`
+
+External links or supporting documents attached to the flow.
+
+```md title="Example"
+---
+attachments:
+  - title: Checkout runbook
+    url: https://runbooks.example.com/checkout
+    type: runbook
+---
+```
+
+## Step fields
+
+Each flow step supports:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` or `number` | Unique step id. |
+| `title` | `string` | Step title. |
+| `summary` | `string` | Optional step summary. |
+| `message` | `object` | Message referenced by this step. |
+| `agent` | `object` | Agent referenced by this step. |
+| `service` | `object` | Service referenced by this step. |
+| `flow` | `object` | Nested flow referenced by this step. |
+| `container` | `object` | Data store referenced by this step. |
+| `dataProduct` | `object` | Data product referenced by this step. |
+| `actor` | `object` | Inline actor for this step. |
+| `custom` | `object` | Custom node for this step. |
+| `externalSystem` | `object` | External system for this step. |
+| `next_step` | `string` or `number` | Next step id. |
+| `next_steps` | `array` | Multiple next step ids. |
+
+## External services nodes {#external-services-nodes}
+
+Use `externalSystem` when a flow step points at a third-party system.
+
+```md
+---
+steps:
+  - id: payment-provider
+    title: Payment provider
+    externalSystem:
+      name: Stripe
+      summary: External payment processor.
+    next_step: complete
+---
+```
+
+## Actor nodes {#actor-nodes}
+
+Use `actor` when a flow step represents a person, role, or external participant.
+
+```md
+---
+steps:
+  - id: customer
+    title: Customer starts checkout
+    actor:
+      name: Customer
+    next_step: submit-order
+---
+```
diff --git a/packages/core/docs/development/guides/resources/flows/_category_.json b/packages/core/docs/development/guides/resources/flows/_category_.json
new file mode 100644
index 000000000..9aa3170d2
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/flows/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Flows",
+  "position": 8,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources/flows",
+    "description": "A collection of guides to help you understand flows and how they work with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/messages/01-what-are-messages.md b/packages/core/docs/development/guides/resources/messages/01-what-are-messages.md
new file mode 100644
index 000000000..27c102843
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/01-what-are-messages.md
@@ -0,0 +1,104 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog queries
+- Queries
+sidebar_label: What are messages?
+title: What are messages?
+description: Understand events, commands, and queries in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+EventCatalog supports different types of messages ([commands](/docs/development/guides/resources/messages/message-types/commands), [events](/docs/development/guides/resources/messages/message-types/events) and [queries](/docs/development/guides/resources/messages/message-types/queries)).
+
+- **Commands** - represent intent, commands can be rejected in distributed systems.
+- **Events** - represents an immutable fact.
+- **Queries** - represent requests for information.
+
+
+### Linking messages to services, domains and channels
+
+- Messages can be sent (producer) or received (consumer) by [services](/docs/development/guides/resources/services/introduction), [domains](/docs/development/guides/domains/add-resources-to-domains/add-messages-to-domains) or be totally independent.
+- You can also route messages through one or more [channels](/docs/development/guides/resources/messages/message-channels/adding-messages-to-services) (e.g queue, broker, bus).
+
+### Where do messages live?
+
+Messages can live anywhere in your catalog, at the service level or domain level.
+
+**Example of a message living at the service level**
+
+Here we have the `OrderPlaced` message living at the service level.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'events',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderPlaced',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+**Example of a message living at the domain level**
+
+Here we have the `OrderPlaced` message living at the domain level.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'events',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderPlaced',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+:::tip You can reference messages from anywhere in your catalog
+It does not matter where you store your messages, you can reference them from anywhere in your catalog.
+Your domains and services will reference them by their `id` and optionally the `version`. EventCatalog will resolve the message.
+:::
diff --git a/packages/core/docs/development/guides/resources/messages/02-message-types/01-events.md b/packages/core/docs/development/guides/resources/messages/02-message-types/01-events.md
new file mode 100644
index 000000000..8c9d5773a
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/02-message-types/01-events.md
@@ -0,0 +1,21 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Events
+sidebar_label: Events
+title: Events
+description: What are events? Why are they useful for event-driven architectures?
+---
+
+Events are a type of message that represent immutable facts.
+
+An example of an event would be `OrderPlaced` event.
+
+- This event is a fact that an order has been placed.
+- Other services (consumers) may be interested in this event and can typically subscribe to it.
+
+### Events in EventCatalog
+
+- Events in EventCatalog are orange (following [EventStorming conventions](https://www.eventstorming.com/))
+- Events live in the `/events` folder.
\ No newline at end of file
diff --git a/packages/core/docs/development/guides/resources/messages/02-message-types/02-commands.md b/packages/core/docs/development/guides/resources/messages/02-message-types/02-commands.md
new file mode 100644
index 000000000..cc3d9ad6b
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/02-message-types/02-commands.md
@@ -0,0 +1,23 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Commands
+sidebar_label: Commands
+title: Commands
+description: What are commands? Why are they useful for event-driven architectures?
+---
+
+Commands are messages that represent intent, commands can be rejected in distributed systems.
+
+In EventCatalog [Services](/docs/development/guides/resources/services/introduction) may invoke (send) or accept (receive) commands in your architecture.
+
+An example of a command would be `PlaceOrder` message over HTTP.
+
+- This message is used to place an order in a system
+- Commands can be rejected, the `PlaceOrder` may be rejected by the service that processes it.
+
+### Commands in EventCatalog
+
+- Commands in EventCatalog are blue (following [EventStorming conventions](https://www.eventstorming.com/))
+- Commands live in the `/commands` folder.
diff --git a/packages/core/docs/development/guides/resources/messages/02-message-types/03-queries.md b/packages/core/docs/development/guides/resources/messages/02-message-types/03-queries.md
new file mode 100644
index 000000000..ee2a52db3
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/02-message-types/03-queries.md
@@ -0,0 +1,20 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog queries
+- Queries
+sidebar_label: Queries
+title: Queries
+description: What are queries? Why are they useful for event-driven architectures?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Queries are a type of message that represent requests for information (e.g a GET request)
+
+In EventCatalog [Services](/docs/development/guides/resources/services/introduction) may query (send) or accept (receive) queries in your architecture.
+
+### Queries in EventCatalog
+
+- Queries in EventCatalog are green
+- Queries live in the `/queries` folder.
\ No newline at end of file
diff --git a/packages/core/docs/development/guides/resources/messages/02-message-types/_category_.json b/packages/core/docs/development/guides/resources/messages/02-message-types/_category_.json
new file mode 100644
index 000000000..69f3bce75
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/02-message-types/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Message types",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/messages/message-types",
+    "description": "Understand events, commands, and queries in EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/messages/03-create-messages/01-create-event.md b/packages/core/docs/development/guides/resources/messages/03-create-messages/01-create-event.md
new file mode 100644
index 000000000..6f40ce66c
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/03-create-messages/01-create-event.md
@@ -0,0 +1,137 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog events
+sidebar_label: Create an event
+title: Create an event
+description: Creating and managing events within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Events are a type of message in EventCatalog that represent an immutable fact.
+
+![Example](../../../img/events/example.png)
+
+## Adding a new event
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog event">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/messages/create-messages/create-event.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/events.md then help me create a new EventCatalog event in my catalog.
+
+Ask me for the event name, what happened, summary, whether it belongs at the root of the catalog or inside a service, domain, or system, and any known producers, consumers, channels, or schema files. Then create the correct events/{'{Event Name}'}/index.mdx, services/{'{Service Name}'}/events/{'{Event Name}'}/index.mdx, domains/{'{Domain Name}'}/events/{'{Event Name}'}/index.mdx, or domains/{'{Domain Name}'}/systems/{'{System Name}'}/services/{'{Service Name}'}/events/{'{Event Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+You can also ask the user if they have a schema of the event, if they provide one, you can add this schema to the event, and set the schemaPath to that schema on the event frontmatter properties.
+
+If the catalog does not have any services, domains, or systems, put it into the root events folder.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the event should live, create the right folder structure, and add the first version of the event documentation.
+
+### Manual Creation
+
+Events live in a `/events` folder. This folder can be placed:
+
+- At the root of your catalog
+- Inside a specific service or domain folder
+
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'InventoryAdjusted',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'events',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderPlaced',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_Here is an example of what a event markdown file may look like._
+
+```md title="/events/InventoryAdjusted/index.mdx (example)"
+---
+# id of your event, used for slugs and references in EventCatalog.
+id: InventoryAdjusted
+
+# Display name of the event, rendered in EventCatalog
+name: Inventory Adjusted
+
+# Version of the event
+version: 0.0.4
+
+# Short summary of your event
+summary: |
+  Event with the intent to adjust the inventory
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: New service
+      backgroundColor: blue
+      textColor: blue
+---
+
+## Overview
+
+The `Inventory Adjusted` event represents intent to adjust the inventory of a given item.
+
+<NodeGraph />
+
+```
+
+Once this file is added, the event will automatically appear across EventCatalog.
+
+### Assign producers and consumers to your event
+
+To add producers or consumers to your event you can read the [guide on adding messages to services](/docs/development/guides/resources/messages/connect-messages/map-producers-and-consumers).
+
+You can also assign your event to one or more [channels](/docs/development/guides/resources/messages/message-channels/adding-messages-to-services) (e.g Kafka, RabbitMQ, AWS SQS, AWS SNS, etc).
+
+### Adding schemas to your event
+
+You can add any schema format to your event, you can read the [guide on adding schemas to messages](/docs/development/guides/resources/schemas/add-schemas-to-messages).
+
diff --git a/packages/core/docs/development/guides/resources/messages/03-create-messages/02-create-command.md b/packages/core/docs/development/guides/resources/messages/03-create-messages/02-create-command.md
new file mode 100644
index 000000000..484eec1c9
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/03-create-messages/02-create-command.md
@@ -0,0 +1,156 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog commands
+sidebar_label: Create a command
+title: Create a command
+description: Creating and managing commands within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+A command documents intent. Use commands when one part of your architecture asks another part to do something that may be accepted, rejected, validated, or handled asynchronously (e.g a POST request)
+
+![Example](../../../img/commands/example.png)
+
+## Adding a new command
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog command">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/messages/create-messages/create-command.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/commands.md then help me create a new EventCatalog command in my catalog.
+
+Ask me for the command name, what action it requests, summary, whether it belongs at the root of the catalog or inside a service, domain, or system, and any known invokers, handlers, channels, HTTP operation details, or schema files. Then create the correct commands/{'{Command Name}'}/index.mdx, services/{'{Service Name}'}/commands/{'{Command Name}'}/index.mdx, domains/{'{Domain Name}'}/commands/{'{Command Name}'}/index.mdx, or domains/{'{Domain Name}'}/systems/{'{System Name}'}/services/{'{Service Name}'}/commands/{'{Command Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+If the catalog does not have any services, domains, or systems, put it into the root commands folder.
+
+You can also ask the user if they have a schema of the command, if they provide one, you can add this schema to the command, and set the schemaPath to that schema on the command frontmatter properties.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the command should live, create the right folder structure, and add the first version of the command documentation.
+
+### Manual Creation
+
+Commands live in a `/commands` folder. This folder can be placed:
+
+- At the root of your catalog
+- Inside a specific service folder
+
+<ProjectTree
+  items={[
+    {
+      name: 'commands',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'UpdateInventory',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'commands',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'AddOrder',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_Here is an example of what a command markdown file may look like._
+
+```md title="/commands/UpdateInventory/index.mdx (example)"
+---
+# id of your command, used for slugs and references in EventCatalog.
+id: UpdateInventory
+
+# Display name of the command, rendered in EventCatalog
+name: Update Inventory
+
+# Version of the command
+version: 0.0.3
+
+# Short summary of your command
+summary: |
+  Command with the intent to update the inventory
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: New service
+      backgroundColor: blue
+      textColor: blue
+---
+
+## Overview
+
+The `Update Inventory` command represents intent to update the inventory of a given item over HTTP.
+
+<NodeGraph />
+
+```
+
+Once this file is added, the command will automatically appear across EventCatalog.
+
+### Assign producers and consumer to your command
+
+To add services that invoke or accept your command you can read the [guide on adding messages to services](/docs/development/guides/resources/messages/connect-messages/map-producers-and-consumers).
+
+You can also assign your command to one or more [channels](/docs/development/guides/resources/messages/message-channels/adding-messages-to-services) (e.g HTTP, GraphQL, etc).
+
+### Document an HTTP operation
+
+If your command maps to an HTTP endpoint, use the `operation` field to document the method, path, and expected status codes.
+
+```md title="/commands/UpdateInventory/index.mdx (example)"
+---
+id: UpdateInventory
+# ...
+operation:
+  method: PUT
+  path: /inventory/{id}
+  statusCodes:
+    - "200"
+    - "400"
+    - "404"
+---
+```
+
+When defined, the visualiser shows an HTTP method badge, the API path, and colored status code pills on the command node. See the [messages reference](/docs/development/guides/resources/messages/reference#operation) for all available options.
+
+### Adding schemas to your command
+
+You can add any schema format to your command, you can read the [guide on adding schemas to messages](/docs/development/guides/resources/schemas/add-schemas-to-messages).
diff --git a/packages/core/docs/development/guides/resources/messages/03-create-messages/03-create-query.md b/packages/core/docs/development/guides/resources/messages/03-create-messages/03-create-query.md
new file mode 100644
index 000000000..9e3ee1607
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/03-create-messages/03-create-query.md
@@ -0,0 +1,158 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog queries
+sidebar_label: Create a query
+title: Create a query
+description: Creating and managing queries within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+A query documents a request for information. Use queries when one part of your architecture asks another part to return data without changing state (e.g GET request)
+
+![Example](../../../img/queries/example.png)
+
+## Adding a new query
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog query">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/messages/create-messages/create-query.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/queries.md then help me create a new EventCatalog query in my catalog.
+
+Ask me for the query name, what information it returns, summary, whether it belongs at the root of the catalog or inside a service, domain, or system, and any known callers, handlers, channels, HTTP operation details, or schema files. Then create the correct queries/{'{Query Name}'}/index.mdx, services/{'{Service Name}'}/queries/{'{Query Name}'}/index.mdx, domains/{'{Domain Name}'}/queries/{'{Query Name}'}/index.mdx, or domains/{'{Domain Name}'}/systems/{'{System Name}'}/services/{'{Service Name}'}/queries/{'{Query Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+If the catalog does not have any services, domains, or systems, put it into the root queries folder.
+
+You can also ask the user if they have a schema of the query, if they provide one, you can add this schema to the query, and set the schemaPath to that schema on the query frontmatter properties.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the query should live, create the right folder structure, and add the first version of the query documentation.
+
+### Manual Creation
+
+Queries live in a `/queries` folder. This folder can be placed:
+
+- At the root of your catalog
+- Inside a specific service folder
+
+<ProjectTree
+  items={[
+    {
+      name: 'queries',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'GetOrder',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'queries',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'GetOrder',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_Here is an example of what a query markdown file may look like._
+
+```md title="/queries/GetOrder/index.mdx (example)"
+---
+# id of your query, used for slugs and references in EventCatalog.
+id: GetOrder
+
+# Display name of the query, rendered in EventCatalog
+name: Get Order
+
+# Version of the query
+version: 0.0.4
+
+# Short summary of your query
+summary: |
+    Query with the intent to get an order from the system
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: New service
+      backgroundColor: blue
+      textColor: blue
+---
+
+## Overview
+
+The `GetOrder` query represents intent to get an order from the system.
+
+<NodeGraph />
+
+```
+
+Once this file is added, the query will automatically appear across EventCatalog.
+
+## Assign services to your queries
+
+To add services that invoke or accept your query you can read the [guide on adding messages to services](/docs/development/guides/resources/messages/connect-messages/map-producers-and-consumers).
+
+You can also assign your query to one or more [channels](/docs/development/guides/resources/messages/message-channels/adding-messages-to-services) (e.g HTTP, GraphQL, etc).
+
+<AddedIn version="3.18.0" />
+
+## Document an HTTP operation
+
+If your query maps to an HTTP endpoint, use the `operation` field to document the method, path, and expected status codes.
+
+```md title="/queries/GetOrder/index.mdx (example)"
+---
+id: GetOrder
+# ...
+operation:
+  method: GET
+  path: /orders/{id}
+  statusCodes:
+    - "200"
+    - "404"
+---
+```
+
+When defined, the visualiser shows an HTTP method badge, the API path, and colored status code pills on the query node. See the [messages reference](/docs/development/guides/resources/messages/reference#operation) for all available options.
+
+## Adding schemas to your query
+
+You can add any schema format to your query, you can read the [guide on adding schemas to messages](/docs/development/guides/resources/schemas/add-schemas-to-messages).
+
diff --git a/packages/core/docs/development/guides/resources/messages/03-create-messages/04-create-draft-message.md b/packages/core/docs/development/guides/resources/messages/03-create-messages/04-create-draft-message.md
new file mode 100644
index 000000000..fb7da10b6
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/03-create-messages/04-create-draft-message.md
@@ -0,0 +1,61 @@
+---
+keywords:
+- EventCatalog events
+sidebar_label: Create a draft message
+title: Create a draft message
+description: Creating and managing draft messages within EventCatalog.
+sidebar_position: 4
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Sometimes, you may want to create a message without immediately publishing it to production. Draft messages allow you to collaborate, gather feedback, or prepare for future changes—without exposing the message as "live" in your catalog
+
+**Common Use Cases**
+- **Collaboration & Feedback**
+  - Share a draft message with teammates to gather comments and suggestions before it goes live.
+- **Versioning with Breaking Changes**
+  - Introduce a new version of a message that includes breaking changes. Keep it in draft mode until it’s fully reviewed and ready for deployment.
+- **Designing Event Lifecycles**
+  - Use drafts to plan and iterate on message definitions before promoting them to production.
+
+### How to add a draft message
+
+To mark an event as a draft, simply add the draft attribute to the frontmatter of the event file.
+
+- **Option 1:** Add a `draft` attribute to your message frontmatter.
+- **Option 2:** Add a `draft` object to your message frontmatter. (recommended)
+
+```md title="/{events|commands|queries}/InventoryOutOfStock/index.mdx (example)"
+---
+# Uses the default title and summary to mark things as draft in the UI
+draft: true
+
+# Or you can specify a title and summary for your draft
+draft: 
+  title: "Inventory Adjusted 1.0.1 is in draft"
+  # Supports markdown
+  message: |
+    ### New version of Inventory Adjusted is in draft
+
+    This is a new version of the Inventory Adjusted event. It is not yet ready for production. We are still working on it and collecting feedback from the team.
+    You can use this version in lower environments, **but please be aware that it is still in draft and may change.**
+    You can still use a previous version of the event, [Inventory Adjusted 1.0.0](/docs/events/InventoryAdjusted/1.0.0), until that version is deprecated.
+    _If you would like to provide feedback, please contact us at [feedback@eventcatalog.io](mailto:feedback@eventcatalog.io) or our slack channel [Order Management](https://join.slack.com/t/eventcatalog/shared_invite/zt-1q900000000000000000000000000000)_
+
+---
+
+```
+
+When you mark a message as draft, it will show in the UI as a draft message.
+
+
+![Example](../../../img/draft-message.png)
+
+### Filtering for Draft Messages
+
+If you want to quickly find draft messages, in your architecture, you can use the [**discover** feature](https://demo.eventcatalog.dev/discover/{events|commands|queries}) and filter for draft messages.
+
+![Example](../../../img/draft-filter.png)
+
+This will remove all resources, and only show the draft messages.
diff --git a/packages/core/docs/development/guides/resources/messages/03-create-messages/_category_.json b/packages/core/docs/development/guides/resources/messages/03-create-messages/_category_.json
new file mode 100644
index 000000000..4b53802c3
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/03-create-messages/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Create messages",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/messages/create-messages",
+    "description": "Create events, commands, queries, and draft messages."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/messages/04-connect-messages/01-map-producers-and-consumers.md b/packages/core/docs/development/guides/resources/messages/04-connect-messages/01-map-producers-and-consumers.md
new file mode 100644
index 000000000..0e366548e
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/04-connect-messages/01-map-producers-and-consumers.md
@@ -0,0 +1,32 @@
+---
+keywords:
+- EventCatalog commands
+sidebar_label: Map producers and consumers
+title: Map producers and consumers
+description: Understand how to link messages to services.
+sidebar_position: 1
+---
+
+[Services](/docs/development/guides/resources/services/introduction) or Domains can either **send** or **receive** events, commands and queries. 
+
+To add messages to resource you need to reference them within your resource itself by adding the `id`. The `version` is optional and if not provided the latest version will be used.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+receives:
+    # id of the message this service receives
+    - id: OrderPlaced
+    # (optional) The version of the message you want to add
+    # If no version is given latest version is used.
+      version: 0.0.1
+sends:  
+    # id of the message this service sends
+    - id: PaymentProcessed
+---
+
+<!-- Markdown contents... -->
+```
+
+If you don't specify a version the latest version will be used.
diff --git a/packages/core/docs/development/guides/resources/messages/04-connect-messages/02-shared-messages-across-boundaries.md b/packages/core/docs/development/guides/resources/messages/04-connect-messages/02-shared-messages-across-boundaries.md
new file mode 100644
index 000000000..af46042e7
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/04-connect-messages/02-shared-messages-across-boundaries.md
@@ -0,0 +1,170 @@
+---
+keywords:
+- EventCatalog commands
+sidebar_label: Patterns for shared messages
+title: Patterns for shared messages
+description: Understand the patterns for shared messages in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+You can store your events, commands and queries in any folder in your EventCatalog.
+
+Here are some common usecases:
+
+- [Messages defined by the service](/docs/development/guides/resources/messages/connect-messages/shared-messages-across-boundaries#messages-defined-by-the-service)
+- [Messages defined at a domain level](/docs/development/guides/resources/messages/connect-messages/shared-messages-across-boundaries#define-messages-at-a-domain-level)
+- [Messages defined at a system level](/docs/development/guides/resources/messages/connect-messages/shared-messages-across-boundaries#define-messages-at-a-system-level)
+
+### Messages defined by the service
+
+If you want to keep your message definition close to the service that producers or consumes it you can store them in the `/services` folder.
+
+In the example below the `OrderPlaced` event, `AddOrder` command and `GetOrder` query are defined in the `/services/Orders` folder.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'events',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderPlaced',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+            {
+              name: 'commands',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'AddOrder',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+            {
+              name: 'queries',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'GetOrder',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Define messages at a domain level
+
+If you want to share messages across multiple services you can define them in the `/domains` folder.
+
+In the example below the `OrderPlaced` event, `AddOrder` command and `GetOrder` query are defined in the `/domains/Orders` folder.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'events',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrderPlaced',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Define messages at a system level
+
+If you want to share messages across all your domains you can define them in the root of your catalog.
+
+In the example below the `OrderPlaced` event, `AddOrder` command and `GetOrder` query are defined in the root of your catalog.
+
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrderPlaced',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'commands',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'AddOrder',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'queries',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'GetOrder',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
diff --git a/packages/core/docs/development/guides/resources/messages/04-connect-messages/03-group-messages.md b/packages/core/docs/development/guides/resources/messages/04-connect-messages/03-group-messages.md
new file mode 100644
index 000000000..c6adec5e6
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/04-connect-messages/03-group-messages.md
@@ -0,0 +1,96 @@
+---
+keywords:
+- EventCatalog messages
+- message groups
+- visualiser
+sidebar_label: Group messages
+title: Group messages
+description: Learn how to group related messages in the visualiser to reduce clutter.
+sidebar_position: 4
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+When a service sends or receives many messages, the visualiser can become crowded. You can use the `group` field on any `sends` or `receives` entry to collect related messages into a named **group node**.
+
+## Adding groups to messages
+
+Add the `group` field to any message in your service's `sends` or `receives` list. Messages that share the same `group` value are collapsed into a single node.
+
+```md title="/services/WarehouseService/index.mdx"
+---
+id: WarehouseService
+version: 1.0.0
+name: Warehouse Service
+sends:
+  - id: ShipmentDispatched
+    version: 1.0.0
+    group: Shipping
+  - id: ShipmentFailed
+    version: 1.0.0
+    group: Shipping
+  - id: InventoryReserved
+    version: 1.0.0
+receives:
+  - id: PickRequested
+    version: 1.0.0
+    group: Picking
+  - id: PickCancelled
+    version: 1.0.0
+    group: Picking
+  - id: OrderPlaced
+    version: 1.0.0
+---
+```
+
+In this example:
+- `ShipmentDispatched` and `ShipmentFailed` are grouped under **Shipping**
+- `PickRequested` and `PickCancelled` are grouped under **Picking**
+- `InventoryReserved` and `OrderPlaced` remain ungrouped and render as individual nodes
+
+## How groups appear in the visualiser
+
+Grouped messages are displayed as a stacked card node showing the group name and message count.
+
+![Message group expanded in the visualiser](./imgs/message-group-expanded.png)
+
+## Expanding and collapsing groups
+
+Click the group node to expand it. The expanded view shows each individual message inside a container, along with the **full downstream graph** — channels the messages route to and any connected producer or consumer services. This is the same graph that would appear if the messages were ungrouped.
+
+Click **Collapse** to return to the compact group node.
+
+![Message group expanded in the visualiser](./imgs/expanding-groups.png)
+
+## Combining groups with channels
+
+Groups work with channel routing (`to` and `from` fields). When a grouped message defines a channel, the expanded view will show the correct channel path for each message.
+
+```md title="/services/WarehouseService/index.mdx"
+---
+id: WarehouseService
+version: 1.0.0
+name: Warehouse Service
+sends:
+  - id: ShipmentDispatched
+    version: 1.0.0
+    group: Shipping
+    to:
+      - id: shipping-events-topic
+  - id: ShipmentFailed
+    version: 1.0.0
+    group: Shipping
+receives:
+  - id: PickRequested
+    version: 1.0.0
+    group: Picking
+    from:
+      - id: warehouse-commands-queue
+---
+```
+
+## Tips
+
+- **Group names are per-service** — the same group name on different services creates separate group nodes.
+- **Mix grouped and ungrouped** — not every message needs a group. Ungrouped messages render as individual nodes as usual.
+- **Groups work for events, commands, and queries** — any message type can be grouped.
diff --git a/packages/core/docs/development/guides/resources/messages/04-connect-messages/_category_.json b/packages/core/docs/development/guides/resources/messages/04-connect-messages/_category_.json
new file mode 100644
index 000000000..289174414
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/04-connect-messages/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Connect messages",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/messages/connect-messages",
+    "description": "Connect messages to producers, consumers, services, domains, and systems."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/messages/04-message-channels/01-introduction.md b/packages/core/docs/development/guides/resources/messages/04-message-channels/01-introduction.md
new file mode 100644
index 000000000..5b30d692e
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/04-message-channels/01-introduction.md
@@ -0,0 +1,87 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Services
+sidebar_label: What are channels?
+title: Understanding channels
+description: What are channels? Why are they useful for event-driven architectures?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Channels in EventCatalog describe how a messages transport between producers and consumers. You can use the channels resource to help your team understand how your messages are transported.
+
+Example of channels (not limited to) can be topics, queues, buses.
+
+```mermaid 
+sequenceDiagram
+    participant P as Producer
+    participant MC as Channel
+    participant C as Consumer
+    
+    P->>MC: Send Message
+    MC->>C: Deliver Message
+    C-->>MC: Acknowledge
+```
+<br/>
+
+<!-- ### Routing messages through multiple channels
+
+<AddedIn version="2.55.0" />
+
+In some cases you may want to model how messages are routed through multiple channels, you can do this using channel `routes`.
+
+In the example below:
+
+    - The Payment Service publishes a `PaymentProcessed` event over the `PaymentEvents` channel.
+    - The Billing Service subscribes to the `PaymentProcessed` event through the `PaymentEvents` channel.
+    - The Fraud Detection Service subscribes to the `PaymentProcessed` event through the `Fraud Dection Queue` which is pulling from the `PaymentEvents` channel (chained channels)
+
+:::info What is the `PaymentEvents` channel?
+This is just an example, but a channel can be any protocol you like. For example if you are using Kafka then this channel could be a Kafka topic.
+Or if you are using an Event Bus this channel could be your bus, queue or topic.
+
+You can model as many channels as you like, and you can route messages through multiple channels.
+:::
+
+![Example](../../../img/channels/channel-chains.png) -->
+
+
+### Supported Channel Protocols
+
+Here is a list of protocols that are supported by EventCatalog (with icons)
+
+- [amqp](https://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol#:~:text=The%20Advanced%20Message%20Queuing%20Protocol,protocol%20for%20message%2Doriented%20middleware.)
+- [azure-event-hubs](https://learn.microsoft.com/en-us/azure/event-hubs/event-hubs-about)
+- [azure-service-bus](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview)
+- [azure-eventgrid](https://learn.microsoft.com/en-us/azure/event-grid/overview)
+- [eventbridge](https://aws.amazon.com/eventbridge/)
+- [googlepubsub](https://cloud.google.com/pubsub)
+- [grpc](https://grpc.io/)
+- [http](https://en.wikipedia.org/wiki/HTTP)
+- [jms](https://www.oracle.com/java/technologies/java-message-service.html)
+- [kafka](https://kafka.apache.org/protocol.html)
+- [kinesis](https://aws.amazon.com/kinesis/)
+- [mercure](https://mercure.rocks/)
+- [mqtt](https://en.wikipedia.org/wiki/MQTT)
+- [nats](https://docs.nats.io/reference/reference-protocols/nats-protocol)
+- [pulsar](https://pulsar.apache.org/docs/next/developing-binary-protocol/)
+- [redis](https://redis-doc-test.readthedocs.io/en/latest/topics/protocol/)
+- [sns](https://aws.amazon.com/sns/)
+- [solace](https://solace.com/products/apis-protocols/)
+- [sqs](https://aws.amazon.com/sqs/)
+- [tibco-ftl](https://www.tibco.com/products/tibco-ftl)
+- [tibco-rv](https://docs.tibco.com/products/tibco-rendezvous)
+- [ws](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
+- [webrtc](https://webrtc.org/)
+- [zmq](https://zeromq.org/)
+
+If you are using a protocol that is not on this list, please raise on issue on [GitHub](https://github.com/event-catalog/eventcatalog) so we can get the icon supported.
+
+
+<!-- 
+### Further reading
+- [Event-driven architecture and domain-driven design](https://eda-visuals.boyney.io/visuals/eda-and-ddd)
+- [Domain, Subdomain, Bounded Context: Problem/Solution Space in DDD: Clearly Defined](https://medium.com/nick-tune-tech-strategy-blog/domains-subdomain-problem-solution-space-in-ddd-clearly-defined-e0b49c7b586c)
+- [Building Blocks of DDD](https://redis.io/glossary/domain-driven-design-ddd/) -->
\ No newline at end of file
diff --git a/packages/core/docs/development/guides/resources/messages/04-message-channels/02-adding-channels.md b/packages/core/docs/development/guides/resources/messages/04-message-channels/02-adding-channels.md
new file mode 100644
index 000000000..0798e04d2
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/04-message-channels/02-adding-channels.md
@@ -0,0 +1,213 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog domains
+sidebar_label: Creating a channel
+title: Creating channels
+description: Creating and managing channels within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+A message channel documents how messages are transported between producers and consumers. A channel might represent a Kafka topic, queue, event bus, HTTP route, webhook, or any other transport your architecture uses.
+
+![Example](../../../img/channels/channel-page-example.png)
+
+## Adding a new channel
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog channel">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/messages/message-channels/adding-channels.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/channels.md then help me create a new EventCatalog channel in my catalog.
+
+Ask me for the channel name, address, protocol, summary, whether the channel belongs at the root of the catalog or inside a service, domain, or system, and any known messages routed through it. Then create the correct channels/{'{Channel Name}'}/index.mdx, services/{'{Service Name}'}/channels/{'{Channel Name}'}/index.mdx, domains/{'{Domain Name}'}/channels/{'{Channel Name}'}/index.mdx, or domains/{'{Domain Name}'}/systems/{'{System Name}'}/services/{'{Service Name}'}/channels/{'{Channel Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+If the channel address has dynamic parts, ask me for the parameters and document them in the channel frontmatter.
+
+If the catalog does not have any services, domains, or systems, put it into the root channels folder.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the channel should live, create the right folder structure, and add the first version of the channel documentation.
+
+### Manual Creation
+
+Channels live in a `/channels` folder. This folder can be placed anywhere in your catalog.
+
+<ProjectTree
+  items={[
+    {
+      name: 'channels',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'inventory.{env}.events',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'channels',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'orders.events',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+_Here is an example of what a channel markdown file may look like. [You can read the channel reference](/docs/development/guides/resources/messages/message-channels/reference)._
+
+```md title="/channels/inventory.{env}.events/index.mdx (example)"
+---
+# id of your channel, used for slugs and references in EventCatalog.
+# this channel is using dynamic naming using parameters
+id: inventory.{env}.events
+
+# Display name of the Channel, rendered in EventCatalog
+name: Inventory channel
+
+# Version of the Channel
+version: 0.0.1
+
+# Short summary of your Channel
+summary: |
+  Central event stream for all inventory-related events including stock updates, allocations, and adjustments
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Address of the channel, this example shows a kafka address with parameters, but it can be anything
+address: inventory.{env}.events
+
+# optionally document the params for your channel name
+# here we know that the channel address "env" value can be "dev,stg,or prod"
+parameters:
+  env:
+    enum:
+      - dev
+      - stg
+      - prod
+    description: 'Environment to use'
+---
+
+### Overview
+
+The Inventory Events channel is the central stream for all inventory-related events across the system. This includes stock level changes, inventory allocations, adjustments, and stocktake events. Events for a specific SKU are guaranteed to be processed in sequence when using productId as the partition key.
+
+<!-- Shows channel information on the page including a table of all your params and their values -->
+<ChannelInformation />
+
+<!-- Rest of markdown -->
+
+```
+
+---
+
+### Using parameters in channel names
+
+You may have some channel names/addresses that are dynamic. For example `address: inventory.{env}.events`.
+
+The channel `address: inventory.{env}.events` shows us the channel name is dynamic with the given parameter `env`.
+
+In your channel you can document your parameters, give them values, default values and descriptions.
+
+```md
+---
+# channel markdown file.
+
+# The dynamic address
+address: inventory.{env}.events
+
+# optionally document the params for your channel name
+# here we know that the channel address "env" value can be "dev,stg,or prod"
+parameters:
+  env:
+    # What values for the parameter? (optional)
+    enum:
+      - dev
+      - stg
+      - prod
+    # what is the default value (optional)
+    default: dev
+    # Any examples if you want to list them
+    examples: 
+      - dev
+      - stg
+      - prod
+    # Describe the channel information (optional)
+    description: 'Environment to use'
+---
+```
+
+Once this information is defined, it can then be rendered on your page using the `<ChannelInformation />` component.
+
+#### Example output using the `<ChannelInformation />` component
+
+![Example](../../../img/channels/channelinformation-example.png)
+
+### Using protocols in channels
+
+Your channel can have one or many protocols. To define a protocol you add the property to your channel.
+
+```md
+---
+id: inventory.{env}.events
+
+# rest of channel markdown...
+
+# You can define one or many protocols
+# list of protocols: https://eventcatalog.dev/docs/development/guides/resources/messages/message-channels/introduction#protocols
+protocols:
+  - http
+  - kafka
+  - mqtt
+---
+```
+
+These protocols will be displayed on your channel page and the visualizer.
+
+You can get [the list of protocols here](/docs/development/guides/resources/messages/message-channels/introduction#protocols).
+
+### Setting a delivery guarantee
+
+You can document the delivery guarantee for your channel using the `deliveryGuarantee` field. This tells consumers what to expect regarding message delivery behavior.
+
+```md
+---
+id: inventory.{env}.events
+
+# How reliably messages are delivered through this channel
+# Accepted values: at-most-once | at-least-once | exactly-once
+deliveryGuarantee: at-least-once
+---
+```
+
+When set, the visualiser shows a colored badge on the channel node. You can read more about the accepted values in the [channel reference](/docs/development/guides/resources/messages/message-channels/reference#deliveryGuarantee).
diff --git a/packages/core/docs/development/guides/resources/messages/04-message-channels/04-adding-messages-to-services.md b/packages/core/docs/development/guides/resources/messages/04-message-channels/04-adding-messages-to-services.md
new file mode 100644
index 000000000..9fec9c41b
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/04-message-channels/04-adding-messages-to-services.md
@@ -0,0 +1,288 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog domains
+sidebar_label: Routing messages through channels
+title: Routing messages through channels
+description: Understanding how to route messages through channels
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+When you define a message (command, query or event) in EventCatalog, you can also specify how this message is transported (channel).
+
+You do this using the `to` and `from` fields in your producer/consumer frontmatter.
+
+### Publishing messages to channels
+
+To publish a message through a channel you need to specify the channel in the `to` field in your producers frontmatter.
+
+In this example the `OrderService` (service) sends an `OrderPlaced` message to the `orders.events` channel.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+# The messages this service sends
+sends:
+  # The id of the message this service sends
+  - id: OrderPlaced
+    to:
+      - id: orders.events
+      # You can also publish to many channels
+      - id: orders.events.filtered
+---
+```
+
+_This assumes you have already defined the `orders.events` channel documentation._
+
+### Consuming messages from channels
+
+To consume a message from a channel you need to specify the channel in the `from` field in your consumer frontmatter.
+
+In this example the `PaymentService` (service) consumes the `OrderPlaced` message from the `orders.events` channel.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: PaymentService
+# The messages this service receives
+receives:
+  - id: OrderPlaced
+    from:
+      - id: orders.events
+      # You can also consume from many channels
+      - id: orders.events.filtered
+---
+```
+
+### Channels visualized in EventCatalog
+
+When messages get added to your channels EventCatalog will visualize this for you through the visualizer.
+
+![Example](../../../img/channels/channels-example.png)
+
+:::tip Turn off channels in the visualizer
+You can turn off the channels in the visualizer by using the visualizer settings in the UI.
+:::
+
+## Chaining channels
+
+In some cases you may want to chain channels together. For example you may want to send a message from one channel to another channel before it is consumed by something downstream.
+
+For example you may want to publish an event to a broker, then route/filter events to another channel (e.g Queue, Topic, etc) before it is consumed by something downstream.
+
+This let's you model publish/subscribe patterns or point to point messaging patterns.
+
+### Example of publish/subscribe pattern
+
+Let's say we have :
+
+- A `OrdersService` publishing an `OrderPlaced` event to the `orders.events` channel.
+- A `PaymentService` consuming the `OrderPlaced` event from the `orders.events` channel.
+- A `FraudDetectionService` consuming the `OrderPlaced` event from the `orders.events` channel.
+
+
+To model this, we define the `OrdersService` to send the `OrderPlaced` event to the `orders.events` channel.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+# The messages this service sends
+sends:
+  - id: OrderPlaced
+    to:
+      - id: orders.events
+---
+```
+
+Then we define the `PaymentService` to consume the `OrderPlaced` event from the `orders.events` channel.
+
+```md title="/services/Payment/index.mdx (example)"
+---
+id: PaymentService
+# The messages this service receives
+receives:
+  - id: OrderPlaced
+    from:
+      - id: orders.events
+---
+```
+
+Then we define the `FraudDetectionService` to consume the `OrderPlaced` event from the `orders.events` channel.
+
+```md title="/services/FraudDetection/index.mdx (example)"
+---
+id: FraudDetectionService
+# The messages this service receives
+receives:
+  - id: OrderPlaced
+    from:
+      - id: orders.events
+---
+```
+
+This will model that the `OrderServices` is publishing onto the broker, with many consumers consuming the event from the same channel.
+
+### Point to point messaging pattern
+
+Let's say we have :
+
+- A `OrdersService` publishing an `OrderPlaced` event to the `orders.events` event broker.
+- Filtering is setup on the `orders.events` event broker to route the event to a new topic `orders.events.filtered`
+- A `PaymentService` consumes the event through a custom queue `payment.queue`
+
+First we define the `OrdersService` to publish an event to the `orders.events` event broker.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+# The messages this service sends
+sends:
+  - id: OrderPlaced
+    to:
+      # Route to the event broker we defined
+      - id: orders.events
+---
+```
+
+Next we define the `PaymentService` to consume the event from the `payment.queue` queue.
+
+```md title="/services/Payment/index.mdx (example)"
+---
+id: PaymentService
+# The messages this service receives
+receives:
+  - id: OrderPlaced
+    from:
+      # Consume from it's own queue
+      - id: payment.queue
+---
+```
+
+Next we setup the routing logic between the channels.
+
+Here, we tell the broker (channel) that is can route to the `orders.events.filtered` topic.
+
+```md title="/channels/orders.events/index.mdx (example)"
+---
+id: orders.events
+# The routes for this channel
+routes:
+  - id: orders.events.filtered
+---
+```
+
+Next, we tell the `orders.events.filtered` channel it can route to the `payment.queue` queue.
+
+```md title="/channels/orders.events.filtered/index.mdx (example)"
+---
+id: orders.events.filtered
+# The routes for this channel
+routes:
+  - id: payment.queue
+    to:
+      - id: payment.queue
+---
+```
+
+EventCatalog will understand the channel routes and relationships and create a visual representation of the channels and their relationships.
+
+![Example](../../../img/channels/channel-chains.png)
+
+
+---
+
+### Looking for previous channel documentation?
+
+Find previous channel documentation below. If you are using EventCatalog 2.65.0 or greater you can skip this section.
+
+<details>
+<summary>Channel documentation for versions less than 2.65.0 </summary>
+
+
+EventCatalog supports different types of messages (commands, events and queries).
+
+Any message can be added to **one or many channels**.
+
+![Example](../../../img/channels/channels-example.png)
+
+To add messages to a channel you first have to define your messages.
+
+Once you define your message you can specify that channel/s it uses.
+
+:::tip Turn off channels in the visualizer
+
+In the visualizer you can show and hide the channels.
+
+To hide the channels in the visualizer you can use the visualizer settings in the UI
+:::
+
+:::tip Why am I seeing multiple nodes for my channels in the visualizer?
+
+By default EventCatalog will render multiple nodes for your channels in the visualizer. This is to give you a better understanding of the relationship between your messages and channels.
+
+If you prefer to only see a single node for your channels you can change the [rendering mode in the visualizer settings](/docs/api/config#visualiser).
+
+:::
+
+## Adding messages to your channels
+
+To add a message to a channel, you need to add the `channels` information to your message.
+
+Here is an example of adding channel information to an `InventoryOutOfStockEvent`.
+
+```md title="/events/InventoryOutOfStockEvent/index.mdx (example)"
+---
+id: InventoryOutOfStockEvent
+... # other event frontmatter
+channels:
+  # The id of the channel to map to.
+  - id: inventory.{env}.events
+    # The version of the channel, this is optional and not required
+    # EventCatalog will map to the latest channel version if not used.
+    version: 0.0.1
+    # optional list of params for this channel
+    # this example means that this message is used on the inventory.dev.events channel
+    parameters:
+      env: dev
+---
+
+<!-- Markdown contents... -->
+
+```
+
+The **receives** and **sends** fields in your service tell EventCatalog which messages this service either consumes or publishes.  
+
+:::info Versioning your channels
+  Versioning for channels is optional. But if your message/channel relationship evolves over time, and you find value capturing this version/history then you can version your channels.
+:::
+
+### Using semver versioning
+
+You can use [semver](https://semver.org/) syntax when referencing your channels in your messages.
+
+```md title="/events/InventoryOutOfStockEvent/index.mdx (example)"
+---
+id: PaymentDomain
+... # other domain frontmatter
+channels:
+    # Latest minor version of InventoryEvents (channel) will be added
+    - id: InventoryEvents
+      version: 0.x.1
+    # Minor and patches of this version will be linked
+    - id: NotificationsChannel
+      version: ^1.0.1
+    # Latest version of this service will be shown by default.
+    - id: PaymentsChannel
+---
+
+<!-- Markdown contents... -->
+
+```
+
+### Visualizing messages with channels
+
+When messages get added to your channels EventCatalog will visualize this for you through the visualizer.
+
+![Example](../../../img/channels/visualizer.png)
+
+</details>
\ No newline at end of file
diff --git a/packages/core/docs/development/guides/resources/messages/04-message-channels/05-reference.md b/packages/core/docs/development/guides/resources/messages/04-message-channels/05-reference.md
new file mode 100644
index 000000000..0a71ffea6
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/04-message-channels/05-reference.md
@@ -0,0 +1,177 @@
+---
+keywords:
+- EventCatalog channels
+- Channel frontmatter
+sidebar_label: Reference
+title: Message channels reference
+description: Frontmatter fields, paths, and routes for channels in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by channels.
+
+## Paths
+
+Channels can be created in any `channels` folder:
+
+```txt
+/channels/{Channel Name}/index.mdx
+/domains/{Domain Name}/channels/{Channel Name}/index.mdx
+/services/{Service Name}/channels/{Channel Name}/index.mdx
+```
+
+Versioned channels use:
+
+```txt
+/channels/{Channel Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/channels/{channel-id}/{version}` | Channel documentation page. |
+| `/visualiser/channels/{channel-id}/{version}` | Channel resource diagram. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the channel. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: orders-topic
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the channel.
+
+```md title="Example"
+---
+name: Orders Topic
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the channel documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short description of the channel.
+
+```md title="Example"
+---
+summary: Kafka topic that carries ordering events.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the channel.
+
+```md title="Example"
+---
+owners:
+  - ordering-platform
+---
+```
+
+### `address` {#address}
+
+- Type: `string`
+
+Broker address, topic, stream, queue, or route.
+
+```md title="Example"
+---
+address: orders.events
+---
+```
+
+### `protocols` {#protocols}
+
+- Type: `array`
+
+Protocols used by the channel, such as Kafka, HTTP, or AMQP.
+
+```md title="Example"
+---
+protocols:
+  - kafka
+---
+```
+
+### `deliveryGuarantee` {#deliveryGuarantee}
+
+- Type: `at-most-once`, `at-least-once`, or `exactly-once`
+
+Delivery guarantee for messages on the channel.
+
+```md title="Example"
+---
+deliveryGuarantee: at-least-once
+---
+```
+
+### `parameters` {#parameters}
+
+- Type: `object`
+
+Parameter definitions for templated channel addresses.
+
+```md title="Example"
+---
+parameters:
+  region:
+    description: Deployment region for the topic.
+---
+```
+
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the channel page.
+
+```md title="Example"
+---
+badges:
+  - content: Kafka
+    backgroundColor: purple
+    textColor: purple
+---
+```
+
+## Delivery guarantee
+
+Use `deliveryGuarantee` to describe how messages are delivered on the channel.
+
+Supported values are `at-most-once`, `at-least-once`, and `exactly-once`.
+
+```md
+---
+deliveryGuarantee: at-least-once
+---
+```
diff --git a/packages/core/docs/development/guides/resources/messages/04-message-channels/09-configuration b/packages/core/docs/development/guides/resources/messages/04-message-channels/09-configuration
new file mode 100644
index 000000000..d36335757
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/04-message-channels/09-configuration
@@ -0,0 +1,39 @@
+---
+sidebar_position: 9
+keywords:
+    - configuration
+    - channels
+sidebar_label: Visualizer Configuration
+title: Visualizer Configuration
+description: Configuration for the visualizer
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.42.0" />
+
+By default EventCatalog will render multiple nodes for your channels in the visualizer. This is to give you a better understanding of the relationship between your messages and channels.
+
+If you prefer to only see a single node for your channels you can change the [rendering mode in the visualizer settings](/docs/api/config#visualiser).
+
+
+## Visualizer configuration
+
+The visualizer configuration is set in the `eventcatalog.config.js` file.
+
+```js
+module.exports = {
+  visualiser: {
+    channels: {
+      // The render mode for channels in the visualiser
+      // supports `flat` or `single`
+      renderMode: 'single'
+    }
+  }
+}
+```
+
+### `flat` and `single` view examples
+
+![Flat Example](./img/flat-single-view.png)
+
diff --git a/packages/core/docs/development/guides/resources/messages/04-message-channels/_category_.json b/packages/core/docs/development/guides/resources/messages/04-message-channels/_category_.json
new file mode 100644
index 000000000..e03967415
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/04-message-channels/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Message Channels",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/messages/message-channels",
+    "description": "A collection of guides to help you understand channels and how they work with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/messages/08-versioning-and-lifecycle/01-version-messages.md b/packages/core/docs/development/guides/resources/messages/08-versioning-and-lifecycle/01-version-messages.md
new file mode 100644
index 000000000..6e5f14e9f
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/08-versioning-and-lifecycle/01-version-messages.md
@@ -0,0 +1,62 @@
+---
+keywords:
+- versioning
+- events
+sidebar_label: Version messages
+title: Version messages
+description: Learn how to version messages.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+All content in EventCatalog can be versioned. This allows you to keep historic versions of content which can give context to users why things are changing.
+
+## How to version a message
+
+1. Create a `/versioned` directory inside the `/events|commands|queries` folder if one is not created already.
+1. Create a new folder with the version number inside the folder.
+    - Example: `/events|commands|queries/InventoryOutOfStock/versioned/0.0.1`
+1. Copy contents into the new folder, it at least needs your index.mdx file.
+    - Example: `/events|commands|queries/InventoryOutOfStock/versioned/0.0.1/index.mdx`
+    - Note: the version inside this index.mdx file would be `0.0.1`
+1. Bump the version of the `index.mdx` file in the route of the domain.
+    - Example `/events|commands|queries/InventoryOutOfStock/index.mdx`, change the `version` to `0.0.2`
+
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'InventoryOutOfStock',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx', highlight: true },
+            {
+              name: 'versioned',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '0.0.1',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## How to navigate to versions
+
+EventCatalog will automatically create links for you within your latest version of your document. Users will also be able to navigate to any version by adding the version in the url (e.g /docs/events|commands|queries/InventoryOutOfStock/1.0.2 would load the 1.0.2 version of this service).
+
+![Example](../../../img/domains/versioned.png)
diff --git a/packages/core/docs/development/guides/resources/messages/08-versioning-and-lifecycle/02-add-changelog.md b/packages/core/docs/development/guides/resources/messages/08-versioning-and-lifecycle/02-add-changelog.md
new file mode 100644
index 000000000..33d9dd475
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/08-versioning-and-lifecycle/02-add-changelog.md
@@ -0,0 +1,72 @@
+---
+keywords:
+    - changelog 
+    - events
+sidebar_label: Add a changelog
+title: Add a changelog
+description: Add changelogs to messages.
+---
+
+EventCatalog supports changelogs for [domains](/docs/domains), [services](/docs/development/guides/resources/services/introduction) and [messages](/docs/development/guides/resources/messages/what-are-messages).
+
+When you [version a message](/docs/development/guides/resources/messages/versioning-and-lifecycle/version-messages) in EventCatalog, you can also attach a `changelog.mdx` to that message or versioned message.
+
+### Adding a changelog
+
+1. Add a `changelog.mdx` to your message (or versioned message)
+    - example `/events|commands|queries/{Message}/changelog.mdx`
+    - versioned example `/events|commands|queries/{Message}/versioned/1.0.0/changelog.mdx`
+
+**Example**
+```md title="/docs/event/InventoryAdjusted/changelog.md"
+---
+createdAt: 2024-08-01
+badges:
+    - content: ⭐️ JSON Schema
+      backgroundColor: purple
+      textColor: purple
+---
+
+### Added support for JSON Schema
+
+InventoryAdjusted uses Avro but now also supports JSON Draft 7.
+
+```json title="Employee JSON Draft"
+// labeled-line-markers.jsx
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Employee",
+  "properties": {
+    "Name": {
+      "type": "string"
+    },
+    "Age": {
+      "type": "integer"
+    },
+    "Town": {
+      "type": "string"
+    }
+  },
+  "required": ["Name", "Age", "Town"]
+}
+
+``
+``` 
+
+Navigate to your change log page for your message (example [/docs/events/InventoryAdjusted/1.0.0/changelog](https://demo.eventcatalog.dev/docs/events/InventoryAdjusted/1.0.0/changelog)) or **click on the Changelog button** on your  message page.
+
+:::tip "What do add to your change log?"
+Changelogs are just markdown files, this allows you to add anything you want (e.g code blocks, tables)
+
+EventCatalog code blocks supports diffs, code labels which are great features for changelogs. You can [read more here](/docs/api/code-blocks).
+
+:::
+
+### Why add changelogs?
+
+Changelogs can provide your team with the context behind the reasons and choices for changes within your message and also be used for auditing purposes.
+
+Changelogs are visualized by EventCatalog.
+
+
diff --git a/packages/core/docs/development/guides/resources/messages/08-versioning-and-lifecycle/03-deprecate-messages.md b/packages/core/docs/development/guides/resources/messages/08-versioning-and-lifecycle/03-deprecate-messages.md
new file mode 100644
index 000000000..8dcf80b80
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/08-versioning-and-lifecycle/03-deprecate-messages.md
@@ -0,0 +1,71 @@
+---
+keywords:
+- EventCatalog
+- messages  
+- deprecating
+sidebar_label: Deprecate messages
+title: Deprecate messages
+description: Deprecating messages with EventCatalog.
+sidebar_position: 4
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.33.10" />
+
+Any resource in EventCatalog can be deprecated or marked as deprecated.
+
+This will show a banner on the page indicating that the resource is deprecated.
+
+## Deprecating messages using frontmatter
+
+To deprecate a message you need to add the `deprecated` field to the message frontmatter API.
+
+This accepts a `boolean` or an `object` with the following properties:
+
+- `date`: Date the message will be or was deprecated (YYYY-MM-DD)
+- `message`: Reason the message is deprecated, supports markdown (optional)
+
+```md title="/{events|commands|queries}/UpdateInventory/index.mdx (example)"
+---
+id: UpdateInventory
+... # other message frontmatter
+
+# deprecated as an object (Recommended)
+deprecated:
+  # Date the event will be or was deprecated (YYYY-MM-DD)
+  date: 2025-01-01
+  # Reason the event is deprecated, supports markdown (optional)
+  message: | 
+    This message has been deprecated and replaced by the new message **UpdateInventoryV2**.
+    Please contact the [team for more information](mailto:inventory-team@example.com) or visit our [website](https://eventcatalog.dev).
+
+# deprecated as a boolean 
+deprecated: true
+---
+
+```
+
+Configuration:
+
+- `deprecated`: `boolean` or `object`
+
+Deprecated as an object is recommended, as it gives your users more information to why the resource is deprecated and a date in the past or future.
+
+- `deprecated.date`: Date the message will be or was deprecated (YYYY-MM-DD)
+- `deprecated.message`: Reason the message is deprecated, supports markdown (optional)
+
+
+#### Rendered output
+
+Example of resource that will be deprecated:
+
+  ![Deprecating messages](../../../img/deprecated/will-be-deprecated.png) 
+
+Example of resource that is deprecated:
+
+![Deprecating messages](../../../img/deprecated/is-deprecated.png) 
+
+#### Demo
+
+You can see a demo of deprecating resources in the [EventCatalog demo site](https://demo.eventcatalog.dev/docs/services/InventoryService/0.0.2).
diff --git a/packages/core/docs/development/guides/resources/messages/08-versioning-and-lifecycle/_category_.json b/packages/core/docs/development/guides/resources/messages/08-versioning-and-lifecycle/_category_.json
new file mode 100644
index 000000000..c68ddf4fd
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/08-versioning-and-lifecycle/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Versioning & lifecycle",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/messages/versioning-and-lifecycle",
+    "description": "Version, deprecate, and document changes to messages."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/messages/09-add-usage-examples.md b/packages/core/docs/development/guides/resources/messages/09-add-usage-examples.md
new file mode 100644
index 000000000..232eba34e
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/09-add-usage-examples.md
@@ -0,0 +1,136 @@
+---
+keywords:
+    - examples
+    - events
+    - commands
+    - queries
+sidebar_label: Add usage examples
+title: Add usage examples
+description: Add usage examples to your messages for quick reference.
+sidebar_position: 7
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+EventCatalog lets you attach example payloads to any message (event, command, or query). This can help your team understand exactly how your schemas can be used
+in your architecture and provide them with real examples.
+
+Examples appear in the Schema Explorer under a **Usage Examples** tab alongside the schema, properties, and changelog tabs.
+
+![Example](./imgs/examples.png)
+
+### Add examples
+
+Create an `examples/` folder inside your message directory and drop in any example files. EventCatalog supports any text-based format: JSON, YAML, XML, Protobuf, and more.
+
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrderCreated',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            { name: 'schema.json' },
+            {
+              name: 'examples',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                { name: 'basic-order.json', highlight: true },
+                { name: 'international-order.json', highlight: true },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The **Usage Examples** tab appears automatically when at least one example file is present. No frontmatter changes are required.
+
+### Organise with subfolders
+
+You can use nested folders to group related examples. EventCatalog displays all files in a flat list regardless of folder depth.
+
+<ProjectTree
+  items={[
+    {
+      name: 'examples',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'domestic',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'basic-order.json', highlight: true }],
+        },
+        {
+          name: 'international',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'eu-order.json', highlight: true },
+            { name: 'apac-order.json', highlight: true },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Add metadata
+
+Place an `examples.config.yaml` (or `.yml` or `.json`) file inside the `examples/` folder to add a display name, summary, and usage snippet to each example.
+
+```yaml title="events/OrderCreated/examples/examples.config.yaml"
+basic-order.json:
+  name: Basic Order
+  summary: A simple domestic order with a single item.
+  usage: |
+    curl -X POST http://localhost:3000/events/publish \
+      -H "Content-Type: application/json" \
+      -d @basic-order.json
+
+international-order.json:
+  name: International Order
+  summary: An order with international shipping and customs information.
+```
+
+All fields are optional. When `name` is omitted, EventCatalog uses the filename without its extension as the title.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `name` | `string` | Display name shown in the examples list |
+| `summary` | `string` | Short description shown below the name |
+| `usage` | `string` | How-to-run snippet shown below the code block |
+
+### Use the SDK
+
+You can manage examples programmatically using the EventCatalog SDK.
+
+```ts
+import { addExampleToEvent, getExamplesFromEvent, removeExampleFromEvent } from '@eventcatalog/sdk';
+
+// Add an example
+await addExampleToEvent('OrderCreated', '1.0.0', {
+  fileName: 'basic-order.json',
+  content: JSON.stringify({ orderId: '123', total: 49.99 }, null, 2),
+});
+
+// Read all examples
+const examples = await getExamplesFromEvent('OrderCreated', '1.0.0');
+
+// Remove an example
+await removeExampleFromEvent('OrderCreated', '1.0.0', 'basic-order.json');
+```
+
+Equivalent functions exist for commands (`addExampleToCommand`, `getExamplesFromCommand`, `removeExampleFromCommand`) and queries (`addExampleToQuery`, `getExamplesFromQuery`, `removeExampleFromQuery`).
diff --git a/packages/core/docs/development/guides/resources/messages/10-reference.md b/packages/core/docs/development/guides/resources/messages/10-reference.md
new file mode 100644
index 000000000..9237eedcd
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/10-reference.md
@@ -0,0 +1,439 @@
+---
+keywords:
+- EventCatalog messages
+- Message frontmatter
+sidebar_label: Reference
+sidebar_position: 8
+title: Messages reference
+description: Frontmatter fields, paths, and routes for events, commands, and queries in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+This page lists the fields, paths, and routes supported by messages.
+
+Messages are modeled as three collections:
+
+- `events`
+- `commands`
+- `queries`
+
+## Paths
+
+Messages can be created at the root of their collection:
+
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: '{Event Name}',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'commands',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: '{Command Name}',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'queries',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: '{Query Name}',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Messages can also be created inside domains, systems, and services:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: '{Domain Name}',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'events',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '{Event Name}',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '{System Name}',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    {
+                      name: 'services',
+                      type: 'folder',
+                      defaultOpen: true,
+                      children: [
+                        {
+                          name: '{Service Name}',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [
+                            {
+                              name: 'commands',
+                              type: 'folder',
+                              defaultOpen: true,
+                              children: [
+                                {
+                                  name: '{Command Name}',
+                                  type: 'folder',
+                                  defaultOpen: true,
+                                  children: [{ name: 'index.mdx', highlight: true }],
+                                },
+                              ],
+                            },
+                          ],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'systems',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: '{System Name}',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'services',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '{Service Name}',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    {
+                      name: 'events',
+                      type: 'folder',
+                      defaultOpen: true,
+                      children: [
+                        {
+                          name: '{Event Name}',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx', highlight: true }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Versioned messages use:
+
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: '{Message Name}',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'versioned',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '{version}',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/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. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the message. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: OrderCreated
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the message.
+
+```md title="Example"
+---
+name: Order Created
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the message documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short summary of what the message represents.
+
+```md title="Example"
+---
+summary: Published when an order has been accepted.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the message.
+
+```md title="Example"
+---
+owners:
+  - ordering-platform
+---
+```
+
+### `schemaPath` {#schemaPath}
+
+- Type: `string`
+
+Path to the message schema.
+
+```md title="Example"
+---
+schemaPath: schema.json
+---
+```
+
+### `schemas` {#schemas}
+
+- Type: `array`
+
+Schema references associated with the message.
+
+```md title="Example"
+---
+schemas:
+  - path: schema.json
+    name: JSON schema
+    format: jsonschema
+---
+```
+
+### `channels` {#channels}
+
+- Type: `array`
+
+Inline channel references for the message.
+
+```md title="Example"
+---
+channels:
+  - id: orders-topic
+    address: orders.events
+    protocol: kafka
+---
+```
+
+### `operation` {#operation}
+
+- Type: `object`
+
+HTTP operation metadata shown on the visualizer node.
+
+```md title="Example"
+---
+operation:
+  method: POST
+  path: /orders
+  statusCodes:
+    - "201"
+    - "400"
+---
+```
+
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the message page.
+
+```md title="Example"
+---
+badges:
+  - content: Public event
+    backgroundColor: green
+    textColor: green
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the message.
+
+```md title="Example"
+---
+repository:
+  language: TypeScript
+  url: https://github.com/acme/orders
+---
+```
+
+### `attachments` {#attachments}
+
+- Type: `array`
+
+External links or supporting documents attached to the message.
+
+```md title="Example"
+---
+attachments:
+  - title: Event contract review
+    url: https://docs.example.com/order-created-review
+    type: document
+---
+```
+
+## Operation fields
+
+Use `operation` to document HTTP metadata for an event, command, or query.
+
+```md
+---
+operation:
+  method: POST
+  path: /orders
+  statusCodes:
+    - "201"
+    - "400"
+---
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `method` | `GET`, `POST`, `PUT`, `DELETE`, `PATCH` | HTTP method for the operation. |
+| `path` | `string` | API path for the operation. |
+| `statusCodes` | `array` | HTTP status codes the operation may return. |
+
+## Schema examples
+
+Use `schemaPath` to attach a schema to the message.
+
+```md
+---
+schemaPath: schema.json
+---
+```
+
+You can also use schema references when a message has multiple schemas or named schemas.
+
+```md
+---
+schemas:
+  - path: schema.json
+    name: JSON schema
+    format: jsonschema
+---
+```
diff --git a/packages/core/docs/development/guides/resources/messages/_category_.json b/packages/core/docs/development/guides/resources/messages/_category_.json
new file mode 100644
index 000000000..22dfbdc83
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/messages/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Messages",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources/messages",
+    "description": "Understand, create, connect, and manage events, commands, and queries in EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/schemas/01-what-are-schemas-and-specifications.md b/packages/core/docs/development/guides/resources/schemas/01-what-are-schemas-and-specifications.md
new file mode 100644
index 000000000..a2d066b6c
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/01-what-are-schemas-and-specifications.md
@@ -0,0 +1,25 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Schemas
+sidebar_label: What are schemas and specifications?
+title: What are schemas and specifications?
+description: Understand how schemas and specifications fit into EventCatalog.
+---
+
+EventCatalog supports **any schema or specification format**, including (but not limited to) JSON / YAML, Avro, Protobuf, GraphQL, OpenAPI, AsyncAPI.
+
+Schemas can be stored in EventCatalog or synced from remote registries/locations.
+
+Schemas are **optional**, but they add valuable context to your resources (e.g messages, services and domains).
+
+### Why add schemas?
+
+By adding schemas to your catalog you unlock several benefits:
+
+- **Schema Explorer** – Your teams can quickly find and browse schemas across your architecture [(see demo)](https://demo.eventcatalog.dev/schemas/explorer)
+- **Fields Explorer** – Drill down into properties of every schema, find duplications and mismatches [(see guide)](/docs/development/guides/resources/schemas/explore-schemas/fields-explorer)
+- **API access** – Programatic access to your schemas through your Catalog API. [(see guide)](/docs/development/guides/resources/schemas/schema-api)
+- **AI Context** – Give LLMs context of your schemas with the [EventCatalog MCP](/docs/development/ask-your-architecture/mcp-server/introduction)
+- **Visualization** – Help developers understand data structures using [schema property search and visualization](/docs/development/components/components/schema-viewer)
+
diff --git a/packages/core/docs/development/guides/resources/schemas/02-add-schemas-to-messages.md b/packages/core/docs/development/guides/resources/schemas/02-add-schemas-to-messages.md
new file mode 100644
index 000000000..4ae3d1182
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/02-add-schemas-to-messages.md
@@ -0,0 +1,63 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog Schemas
+sidebar_label: Add schemas to messages
+title: Add schemas to messages
+description: Attach schemas to events, commands, and queries in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Schemas can be added to any message type (Event, Command or Query).
+
+## Adding a schema to a message
+
+Add the schema file next to the message and reference it with `schemaPath` in the message frontmatter.
+
+```md title="/events/InventoryAdjusted/index.mdx"
+---
+id: InventoryAdjusted
+version: 0.0.4
+schemaPath: schema.avro
+---
+```
+
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'InventoryAdjusted',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            { name: 'schema.avro', highlight: true },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Rendering schemas
+
+You can render schema files inside the message page with the [schema components](/docs/development/components/components/schema-viewer).
+
+```md title="/events/InventoryAdjusted/index.mdx"
+<!-- Raw codeblock for your schema -->
+<Schema file="schema.avro" />
+
+<!-- Richer UI experinece for your schemas -->
+<SchemaViewer file="schema.avro" />
+```
+
+Use `<Schema />` when you want to render the raw schema as a code block. Use `<SchemaViewer />` when you want a richer schema viewer for supported formats.
+
+## Next steps
+
+Once schemas are attached to your messages, you can use the [Schema Explorer](/docs/development/guides/resources/schemas/explore-schemas/schema-explorer), [Fields Explorer](/docs/development/guides/resources/schemas/explore-schemas/fields-explorer), and [Schema API](/docs/development/guides/resources/schemas/schema-api) to make them easier to find and use.
diff --git a/packages/core/docs/development/guides/resources/schemas/03-add-schemas-to-data-stores.md b/packages/core/docs/development/guides/resources/schemas/03-add-schemas-to-data-stores.md
new file mode 100644
index 000000000..827b80e3f
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/03-add-schemas-to-data-stores.md
@@ -0,0 +1,90 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog schemas
+- EventCatalog data stores
+sidebar_label: Add schemas to data stores
+title: Add schemas to data stores
+description: Attach schemas, queries, and data files to data stores in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+<AddedIn version="2.59.0" />
+
+EventCatalog supports any schema format.
+
+When you document your [data stores](/docs/development/guides/resources/data/introduction), you may want to include schemas, queries, or other files that explain the data store.
+
+You can attach this information in two ways:
+
+- [Use codeblocks to render your schema](#using-codeblocks-to-render-your-schema)
+- [Use the `<Schema/>` component to render your schema from a file](#using-the-schema-component-to-render-your-schema-from-a-file)
+
+## Using codeblocks to render your schema
+
+You can use codeblocks to render your schema directly in your Markdown files.
+
+Here is an example of a SQL codeblock:
+
+````md
+```sql
+CREATE TABLE users (
+  id INT PRIMARY KEY,
+  name VARCHAR(255),
+  email VARCHAR(255)
+);
+```
+````
+
+You can learn more about codeblocks and configuring them in the [codeblocks documentation](/docs/api/code-blocks).
+
+## Using the `<Schema/>` component to render your schema from a file
+
+If you prefer to keep your schemas or queries in separate files, add them to the data store folder and render them with the `<Schema/>` component.
+
+<ProjectTree
+  items={[
+    {
+      name: 'containers',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersDatabase',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            { name: 'schema.sql', highlight: true },
+            { name: 'queries.sql', highlight: true },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+```md title="/containers/OrdersDatabase/index.mdx"
+<!-- Render the file into your page -->
+<Schema file="schema.sql" lang="sql" title="Users Table" />
+
+<!-- Render the schemas separately in an AccordionGroup -->
+<AccordionGroup>
+  <Accordion title="Users Table">
+    <!-- Load the schema from the file -->
+    <Schema file="schema.sql" lang="sql" title="Users Table" />
+  </Accordion>
+  <Accordion title="Common Queries">
+    <!-- Load the queries from the file -->
+    <Schema file="queries.sql" lang="sql" title="Common Queries" />
+  </Accordion>
+</AccordionGroup>
+```
+
+You can see an example of this in the [EventCatalog Demo](https://demo.eventcatalog.dev/docs/containers/orders-db/0.0.1).
+
+:::tip Versioning information
+Everything in EventCatalog can be versioned. When your data store changes, keep older documentation in a `versioned` folder and add a `changelog.mdx` file to explain what changed.
+:::
diff --git a/packages/core/docs/development/guides/resources/schemas/03-add-specifications-to-services/01-add-openapi-specifications.md b/packages/core/docs/development/guides/resources/schemas/03-add-specifications-to-services/01-add-openapi-specifications.md
new file mode 100644
index 000000000..4d1b39102
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/03-add-specifications-to-services/01-add-openapi-specifications.md
@@ -0,0 +1,106 @@
+---
+keywords:
+- EventCatalog schemas
+- OpenAPI
+sidebar_position: 1
+sidebar_label: OpenAPI
+title: Add OpenAPI specifications
+description: Attach an OpenAPI specification to your service and render it in your documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Services in EventCatalog allow you to attach one or more OpenAPI specifications to them and render them in the Catalog. ([see demo](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3/spec/openapi-v1)).
+
+![Example](../../../img/services/openapi-spec.png)
+
+You have two options for adding OpenAPI specifications to your service:
+
+- [Adding OpenAPI files to EventCatalog](#adding-openapi-specifications-to-eventcatalog)
+- [Reference the OpenAPI file from a remote URL](#reference-the-openapi-file-from-a-remote-url)
+
+:::tip Why not automate your EventCatalog from your OpenAPI files?
+  Did you know you can automate your documentation, visualizations and owners using your OpenAPI Files?
+
+  We have a [OpenAPI plugin](/docs/plugins/openapi/intro) that can generate your catalog from your OpenAPI files, transforming your operations into 
+  commands, queries and events. You can assign these to services and domains and much more...
+:::
+
+## Adding OpenAPI files to EventCatalog
+
+To add an OpenAPI file to your service you will need to include the file itself inside the service directory.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            { name: 'openapi.yml', highlight: true },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Then you need to reference the file in the service frontmatter.
+
+```md title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: openapi
+      # Path to the OpenAPI file relative to the service directory
+      path: openapi.yml
+      # Friendly name for the specification
+      name: OpenAPI Specification
+---
+```  
+
+### Remote OpenAPI files
+
+This can be useful if you want to keep your OpenAPI files in a remote repository and render them in EventCatalog.
+
+The pages will be built at build time, so the URL needs to be accessible by the build machine.
+
+If your specifications changes you need to rebuild your EventCatalog as the pages are built at build time.
+
+```md title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: openapi
+      # Path to the OpenAPI file from a remote URL (accessible by the build machine)
+      path: https://raw.githubusercontent.com/event-catalog/generator-openapi/refs/heads/main/examples/product-api/openapi.yml
+      # Friendly name for the specification
+      name: Product API
+---
+```
+
+### Multiple OpenAPI Files
+
+If your service exposes multiple APIs or versions of the same API, you can assign multiple OpenAPI files to a single service.
+
+```mdx title="example: /services/Orders/index.mdx"
+---
+  # rest of service frontmatter...
+  specifications:
+    - type: openapi
+      path: openapi-v1.yml
+      name: v1
+    - type: openapi
+      path: openapi-v2.yml
+      name: v2
+---
+```
+
+This will render a list of specification files on your service page and navigation bar.
+
+![Example](../../../img/services/openapi-many.png)
diff --git a/packages/core/docs/development/guides/resources/schemas/03-add-specifications-to-services/02-add-asyncapi-specifications.md b/packages/core/docs/development/guides/resources/schemas/03-add-specifications-to-services/02-add-asyncapi-specifications.md
new file mode 100644
index 000000000..14545fca8
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/03-add-specifications-to-services/02-add-asyncapi-specifications.md
@@ -0,0 +1,107 @@
+---
+keywords:
+- EventCatalog schemas
+- AsyncAPI
+sidebar_position: 2
+sidebar_label: AsyncAPI
+title: Add AsyncAPI specifications
+description: Attach an AsyncAPI specification to your service and render it in your documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Services in EventCatalog allow you to attach one or more AsyncAPI specifications to them and render them in the Catalog. ([see demo](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3/asyncapi/order-service-asyncapi)).
+
+![Example](../../../img/services/asyncapi-spec.png)
+
+You have two options for adding AsyncAPI specifications to your service:
+
+- [Adding AsyncAPI files to EventCatalog](#adding-asyncapi-specifications-to-eventcatalog)
+- [Reference the AsyncAPI file from a remote URL](#reference-the-asyncapi-file-from-a-remote-url)
+
+:::tip Why not automate your EventCatalog from your AsyncAPI files?
+  Did you know you can automate your documentation, visualizations and owners using your AsyncAPI Files?
+
+  We have a [AsyncAPI plugin](/docs/plugins/asyncapi/intro) that can generate your catalog from your AsyncAPI files, transforming your operations into commands, queries and events. You can assign these to services and domains and much more...
+:::
+
+## Adding AsyncAPI files to EventCatalog
+
+This option is useful if you want to keep your AsyncAPI files in your EventCatalog.
+
+To add an AsyncAPI file to your service you will need to include the file itself inside the service directory.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            { name: 'asyncapi.yml', highlight: true },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Then you need to reference the file in the service frontmatter.
+
+```md title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: asyncapi
+      # Path to the AsyncAPI file relative to the service directory
+      path: asyncapi.yml
+      # Friendly name for the specification
+      name: AsyncAPI Specification
+---
+```  
+
+### Remove AsyncAPI file
+
+This can be useful if you want to keep your AsyncAPI files in a remote repository and render them in EventCatalog.
+
+The pages will be built at build time, so the URL needs to be accessible by the build machine.
+
+If your specifications changes you need to rebuild your EventCatalog as the pages are built at build time.
+
+```md title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: asyncapi
+      # Path to the AsyncAPI file from a remote URL (accessible by the build machine)
+      path: https://raw.githubusercontent.com/event-catalog/generator-asyncapi/refs/heads/main/examples/product-api/asyncapi.yml
+      # Friendly name for the specification
+      name: Product API
+---
+```
+
+### Multiple AsyncAPI Files
+
+You can also assign multiple AsyncAPI files to a single service.
+
+This can be useful if your service exposes multiple APIs or versions of the same API.
+
+```mdx title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: asyncapi
+      path: asyncapi-v1.yml
+      name: v1
+    - type: asyncapi
+      path: asyncapi-v2.yml
+      name: v2
+---
+```
+
+This will render a list of specification files on your service page and navigation bar.
+
diff --git a/packages/core/docs/development/guides/resources/schemas/03-add-specifications-to-services/03-add-graphql-schemas.md b/packages/core/docs/development/guides/resources/schemas/03-add-specifications-to-services/03-add-graphql-schemas.md
new file mode 100644
index 000000000..b4dc4a362
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/03-add-specifications-to-services/03-add-graphql-schemas.md
@@ -0,0 +1,106 @@
+---
+keywords:
+- EventCatalog schemas
+- GraphQL
+sidebar_position: 3
+sidebar_label: GraphQL
+title: Add GraphQL schemas
+description: Add a GraphQL schema to your service and render it in your documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Services in EventCatalog allow you to attach one or more GraphQL schemas to them and render them in the Catalog. ([see demo](https://demo.eventcatalog.dev/docs/services/BillingService/0.0.1/graphql/schema)).
+
+![Example](../../../img/services/graphql-spec.png)
+
+You have two options for adding GraphQL schemas to your service:
+
+- [Adding GraphQL files to EventCatalog](#adding-graphql-files-to-eventcatalog)
+- [Reference the GraphQL file from a remote URL](#reference-the-graphql-file-from-a-remote-url)
+
+:::tip Why not automate your EventCatalog from your GraphQL files?
+  Did you know you can automate your documentation, visualizations and owners using your GraphQL Files?
+
+  We have a [GraphQL plugin](/docs/plugins/graphql/intro) that can generate your catalog from your GraphQL files, transforming your operations into commands, queries and events. You can assign these to services and domains and much more...
+:::
+
+## Adding GraphQL files to EventCatalog
+
+This option is useful if you want to keep your GraphQL files in your EventCatalog.
+
+To add a GraphQL schema to your service you will need to include the file itself inside the service directory.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            { name: 'schema.graphql', highlight: true },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Then you need to reference the file in the service frontmatter.
+
+```md title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: graphql
+      # Path to the GraphQL schema relative to the service directory
+      path: schema.graphql
+      # Friendly name for the specification
+      name: GraphQL Specification
+---
+```  
+
+## Reference the GraphQL file from a remote URL
+
+This can be useful if you want to keep your GraphQL files in a remote repository and render them in EventCatalog.
+
+The pages will be built at build time, so the URL needs to be accessible by the build machine.
+
+If your schemas changes you need to rebuild your EventCatalog as the pages are built at build time.
+
+```md title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: graphql
+      # Path to the GraphQL schema from a remote URL (accessible by the build machine)
+      path: https://raw.githubusercontent.com/event-catalog/generator-graphql/refs/heads/main/examples/product-api/schema.graphql
+      # Friendly name for the specification
+      name: Product API
+---
+```
+
+### Multiple GraphQL Files
+
+You can also assign multiple GraphQL files to a single service.
+
+This can be useful if your service exposes multiple APIs or versions of the same API.
+
+```mdx title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: graphql
+      path: schema-v1.graphql
+      name: v1
+    - type: graphql
+      path: schema-v2.graphql
+      name: v2
+---
+```
+
+This will render a list of schema files on your service page and navigation bar.
diff --git a/packages/core/docs/development/guides/resources/schemas/03-add-specifications-to-services/_category_.json b/packages/core/docs/development/guides/resources/schemas/03-add-specifications-to-services/_category_.json
new file mode 100644
index 000000000..1f6b3a5de
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/03-add-specifications-to-services/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Add specifications to services",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/schemas/add-specifications-to-services",
+    "description": "Attach OpenAPI, AsyncAPI, and GraphQL specifications to services."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/schemas/04-explore-schemas/01-schema-explorer.md b/packages/core/docs/development/guides/resources/schemas/04-explore-schemas/01-schema-explorer.md
new file mode 100644
index 000000000..608d8de0f
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/04-explore-schemas/01-schema-explorer.md
@@ -0,0 +1,51 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Schemas
+sidebar_label: Schema Explorer
+title: Schema Explorer
+description: Explore your schemas in the Schema Explorer
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+The Schema Explorer lets your teams quickly find the schema, understand who owns it, and who is producing or consuming it (see [demo](https://demo.eventcatalog.dev/schemas)).
+
+![Example](../img/schema-explorer.png)
+
+Using the Schema Explorer, you can:
+
+- Quickly find schemas in your Architecture
+- View diffs between versions of your schemas
+- Quickly find who is consuming or producing your schemas
+- Schema ownership to query who owns a schema
+- Get API (GET) access to your schemas for mocking or testing
+
+### How to use the Schema Explorer?
+
+You can access the Schema Explorer from the sidebar, or by going to the `/schemas/explorer` page.
+
+The page will take all the schemas from your EventCatalog and render them in a searchable list.
+
+:::tip Schema Path
+You need to set the `schemaPath` in your schema frontmatter to the path to your schema file for Events, Queries and Commands.
+
+For services you need to specify the path to your specification file in the `specifications` frontmatter.
+:::
+
+![Example](../img/schema-explorer-2.png)
+
+##### Filters
+You can use the filters to quickly find schemas in your Architecture. You can filter by name, message type and schema format.
+
+##### Schema Preview
+
+The schema preview will show you a preview of the schema in a readable format, you can use the `Schema` button to switch between different views of your schema (if they are supported, JSON or Avro).
+
+##### API Access
+
+For EventCatalog Scale users, you can get API (GET) access to your schemas for mocking or testing. 
+
+##### Producers and Consumers
+
+The producers and consumers section will show you who is producing or consuming the schema. You can click on the producer or consumer to see more information about them.
diff --git a/packages/core/docs/development/guides/resources/schemas/04-explore-schemas/02-fields-explorer.md b/packages/core/docs/development/guides/resources/schemas/04-explore-schemas/02-fields-explorer.md
new file mode 100644
index 000000000..f2cc6f4d1
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/04-explore-schemas/02-fields-explorer.md
@@ -0,0 +1,118 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog schema fields explorer
+- field traceability
+- field conflict detection
+- schema field search
+sidebar_label: Fields Explorer
+title: Fields Explorer
+description: Browse, search, and trace schema fields across all messages in your catalog.
+---
+
+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.
+:::
+
+<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
+
+Fields are indexed automatically when EventCatalog starts in SSR mode. No additional configuration is required beyond adding schemas to your messages via the `schemaPath` frontmatter property.
+
+The following schema formats are supported:
+
+- JSON Schema
+- Avro
+- Protobuf
+
+Once your catalog is running, navigate to `/schemas/fields` or click **Schema Fields** in the sidebar to open the Fields Explorer.
+
+## Search and filter
+
+The left sidebar contains all filtering options.
+
+**Full-text search** -- Type in the search box to find fields by path, type, or description. The search uses prefix matching, so `ord` will match `orderId`, `orderStatus`, etc.
+
+**Schema format** -- Filter results to a single schema format (json-schema, avro, or proto). The count next to each option shows how many fields match.
+
+**Message type** -- Narrow results to fields that appear only in events, commands, or queries.
+
+**Shared fields only** -- Show only fields whose path appears in more than one message. This is useful for spotting reused data structures and understanding cross-message coupling.
+
+## Read the fields table
+
+Each row in the table represents a single field in a specific message schema.
+
+| Column | Description |
+|---|---|
+| Field Path | The dotted path to the field (e.g. `order.shipping.address`). Hover to reveal a copy button. |
+| Type | The data type declared in the schema. |
+| Message | The event, command, or query that contains this field. Click to open that message's documentation page. |
+| Format | The schema format the field was extracted from. |
+| Required | Shown when the field is marked required in the schema. |
+| Owners | Teams or users who own the message this field belongs to. |
+
+## 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
+2. **Messages** -- the events, commands, or queries that carry the field
+3. **Consumer services** -- services that subscribe to those messages
+
+The right-hand panel lists the same information in a collapsible format and lets you click any node to focus the graph on it.
+
+![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)
+
+In the table, a conflict is shown as an amber warning badge with the number of distinct types (for example, `2 types`). Hovering reveals a tooltip listing each type and the count of schemas that use it.
+
+![Field Explorer](../img/type-conflicts-visual.png)
+
+Inside the Field Traceability panel, a **Type Conflict** section appears in the right-hand details panel. It lists each type variant and how many schemas use it. When conflicts exist, the node graph renders a separate field node per type, making it immediately clear which messages use each variant.
+
+To see only conflicting fields across your entire catalog, enable the **Conflicting fields** filter in the sidebar.
+
+## Understand the fields index
+
+When EventCatalog starts in SSR mode it builds a SQLite index at `.eventcatalog/fields.db` inside your catalog directory. The index is rebuilt on every start, so it always reflects the latest version of each message schema.
+
+Only the **latest version** of each event, command, and query is indexed. Older versions are not included.
+
+If a message has no `schemaPath` set, it is skipped silently. If a schema file cannot be parsed (for example, due to a syntax error), the indexer emits a warning in the startup logs and continues.
+
+## Hide the Fields Explorer
+
+You can hide the Fields Explorer from the sidebar by setting its visibility to `false` in `eventcatalog.config.js`.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  sidebar: [
+    {
+      id: '/schemas/fields',
+      visible: false,
+    }
+  ]
+};
+```
diff --git a/packages/core/docs/development/guides/resources/schemas/04-explore-schemas/03-consumer-field-usage.md b/packages/core/docs/development/guides/resources/schemas/04-explore-schemas/03-consumer-field-usage.md
new file mode 100644
index 000000000..915ea0d96
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/04-explore-schemas/03-consumer-field-usage.md
@@ -0,0 +1,118 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog field usage
+- field lineage
+- schema field tracking
+sidebar_label: Consumer Field Usage
+title: Consumer Field Usage
+description: Track which services depend on specific message fields.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Field Usage lets consumers declare which specific fields of a message they depend on. When fields are declared, EventCatalog generates a **Field Usage** page for that message showing a cross-service view of field dependencies.
+
+This gives producers visibility into downstream impact before changing or removing a field.
+
+![Field Usage](../img/field-usage.png)
+
+## Declare fields in services
+
+To declare field dependencies, add a `fields` array to any entry in your service's `receives` frontmatter.
+
+```md title="/services/ShippingService/index.mdx"
+---
+id: ShippingService
+version: 1.0.0
+receives:
+  - id: PaymentProcessed
+    version: 1.0.0
+    fields:
+      - orderId
+      - amount
+      - currency
+    from:
+      - id: payments.events
+---
+```
+
+The `fields` array is a list of field names as strings. Only include the fields your service actually reads -- you do not need to list every field in the message.
+
+## Declare fields in domains
+
+Domains support the same `fields` property on their `receives` pointers.
+
+```md title="/domains/Billing/index.mdx"
+---
+id: Billing
+version: 1.0.0
+receives:
+  - id: PaymentProcessed
+    version: 1.0.0
+    fields:
+      - orderId
+      - amount
+---
+```
+
+## View the Field Usage page
+
+When a message has a `schemaPath` set and at least one service or domain declares `fields` for that message, a **Field Usage** link appears in the message sidebar under "API & Contracts".
+
+Navigate to any message page and click **Field Usage** in the sidebar, or go directly to:
+
+```
+http://localhost:3000/docs/{type}/{id}/{version}/field-lineage
+```
+
+The page shows a table with the following columns:
+
+| Column | Description |
+|---|---|
+| Field | The field name from the schema |
+| Type | The data type (extracted from the schema) |
+| Description | The field description (extracted from the schema) |
+| Consumers | Services or domains that declared a dependency on this field |
+
+All fields from the schema are listed -- not only the ones with declared consumers. This gives you a complete picture and makes it easy to spot unused fields.
+
+Use the **Consumed only** filter button to narrow the list down to fields that have at least one consumer.
+
+## Understand the "Fields not found in schema" section
+
+If a service declares a field that does not exist in the message schema, it appears in a separate **Fields not found in schema** warning section at the bottom of the page.
+
+This section helps you catch:
+
+- Typos in field names declared by consumers
+- Fields that were removed from the schema but are still referenced by consumers
+- Outdated documentation that has drifted from the actual schema
+
+Resolving these mismatches keeps your documentation accurate and prevents consumers from unknowingly depending on fields that no longer exist.
+
+## Supported schema formats
+
+Field metadata (type and description) is automatically extracted from the message schema. The following formats are supported:
+
+- JSON Schema
+- Avro
+- Protobuf
+
+If your schema is in a different format, the Field Usage page will still list declared consumers but will not show type or description information.
+
+## Use the SDK
+
+The `fields` property is also available when using the EventCatalog SDK to programmatically add messages to services or domains.
+
+```typescript
+import { addEventToService } from '@eventcatalog/sdk';
+
+await addEventToService('ShippingService', 'receives', {
+  id: 'PaymentProcessed',
+  version: '1.0.0',
+  fields: ['orderId', 'amount', 'currency'],
+});
+```
+
+The same `fields` option is available on `addCommandToService`, `addQueryToService`, `addEventToDomain`, `addCommandToDomain`, and `addQueryToDomain`.
diff --git a/packages/core/docs/development/guides/resources/schemas/04-explore-schemas/_category_.json b/packages/core/docs/development/guides/resources/schemas/04-explore-schemas/_category_.json
new file mode 100644
index 000000000..c59ab8650
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/04-explore-schemas/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Explore schemas",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/schemas/explore-schemas",
+    "description": "Find, inspect, and understand schemas across your catalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/schemas/05-schema-api.md b/packages/core/docs/development/guides/resources/schemas/05-schema-api.md
new file mode 100644
index 000000000..161e1c7b9
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/05-schema-api.md
@@ -0,0 +1,54 @@
+---
+sidebar_position: 6
+keywords:
+- EventCatalog Schemas
+sidebar_label: Schema API
+title: Schema API
+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.
+
+### Message Schemas
+
+The Message Schemas API allows you to get the schema for a specific event, query or command.
+
+```
+GET /api/schemas/events/{eventId}/{version}
+GET /api/schemas/queries/{queryId}/{version}
+GET /api/schemas/commands/{commandId}/{version}
+```
+
+You can also get the latest version of the schema by omitting the version parameter.
+
+```
+GET /api/schemas/events/{eventId}/latest
+GET /api/schemas/queries/{queryId}/latest
+GET /api/schemas/commands/{commandId}/latest
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `eventId` | The id of the event |
+| `queryId` | The id of the query |
+| `commandId` | The id of the command |
+| `version` | The version of the message or `latest` to get the latest version |
+
+### Service Specifications
+
+The Service Specifications API allows you to get the specification for a specific service.
+
+```
+GET /api/schemas/services/{serviceId}/{version}/{type}
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `serviceId` | The id of the service |
+| `version` | The version of the service |
+| `type` | The type of specification, currently only `asyncapi`, `openapi` and `graphql` are supported. |
diff --git a/packages/core/docs/development/guides/resources/schemas/06-schema-mcp.md b/packages/core/docs/development/guides/resources/schemas/06-schema-mcp.md
new file mode 100644
index 000000000..c1533aa6c
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/06-schema-mcp.md
@@ -0,0 +1,21 @@
+---
+sidebar_position: 7
+keywords:
+- EventCatalog Schemas
+sidebar_label: Schema MCP
+title: Schema MCP
+description: Get access to your schemas for your MCP clients (e.g Cursor, Windsurf, Claude Desktop etc)
+---
+
+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).
+
+Your documented schemas for your Events, Queries, Commands and Services can be accessed via the EventCatalog MCP server.
+
+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).
diff --git a/packages/core/docs/development/guides/resources/schemas/07-reference.md b/packages/core/docs/development/guides/resources/schemas/07-reference.md
new file mode 100644
index 000000000..5a0608ead
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/07-reference.md
@@ -0,0 +1,23 @@
+---
+keywords:
+- EventCatalog schemas
+- Schema reference
+sidebar_label: Reference
+sidebar_position: 8
+title: Schemas reference
+description: Fields, sources, and routes for schemas in EventCatalog.
+---
+
+This page lists how schemas are discovered and represented in EventCatalog.
+
+Schemas are generated from:
+
+- Message schema files referenced by events, commands, and queries.
+- Schema sources configured in `eventcatalog.config.js`.
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/schemas/explorer` | Schema Explorer. |
+| `/schemas/fields` | Fields Explorer. |
diff --git a/packages/core/docs/development/guides/resources/schemas/_category_.json b/packages/core/docs/development/guides/resources/schemas/_category_.json
new file mode 100644
index 000000000..fd1e6762b
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/schemas/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Schemas & Specifications",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources/schemas",
+    "description": "A collection of guides to help you understand schemas and how they work with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/services/01-introduction.md b/packages/core/docs/development/guides/resources/services/01-introduction.md
new file mode 100644
index 000000000..1d4560d06
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/01-introduction.md
@@ -0,0 +1,27 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Services
+sidebar_label: What are services?
+title: Understanding services
+description: What are services? Why are they useful for event-driven architectures?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+A service is an implementation resource. It might be an API, worker, backend service, frontend application, or other deployable component.
+
+Services can produce or receive messages (e.g [commands](/docs/development/guides/resources/messages/message-types/commands), [events](/docs/development/guides/resources/messages/message-types/events) or [queries](/docs/development/guides/resources/messages/message-types/queries)) and also be implementations of one or more specifications (OpenAPI, AsyncAPI, GraphQL).
+
+Services can be part of a domain, system or independent.
+
+### Internal and external services
+
+Services in EventCatalog fall into two categories:
+
+- **Internal services** — a resource your company owns and operates.
+- **External services** — a third-party resource you integrate with but do not own (e.g Stripe, Twilio, or Snowflake). 
+
+Both are just services under the hood. They share the same schema, can send and receive messages, be versioned, have owners, and carry specifications. The distinction only affects how they are grouped in the sidebar and rendered in the visualiser, so that the systems you operate are easy to tell apart from the ones you depend on.
+
diff --git a/packages/core/docs/development/guides/resources/services/02-create-service.md b/packages/core/docs/development/guides/resources/services/02-create-service.md
new file mode 100644
index 000000000..14a1c3715
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/02-create-service.md
@@ -0,0 +1,195 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog domains
+sidebar_label: Create a service
+title: Create a service
+description: Creating and managing services within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PromptBox from '@site/src/components/MDX/PromptBox';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+A service is an implementation resource. It might be an API, worker, backend service, frontend application, or other deployable component.
+
+![Example](../../img/services/service-example.png)
+
+## Adding a new service
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog service">
+Read https://www.eventcatalog.dev/docs/development/guides/resources/services/create-service.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/services.md then help me create a new EventCatalog service in my catalog.
+
+Ask me for the service name, what it does, summary, whether it belongs inside a domain or system, and any known messages, or specifications. Then create the correct services/{'{Service Name}'}/index.mdx, domains/{'{Domain Name}'}/services/{'{Service Name}'}/index.mdx, systems/{'{System Name}'}/services/{'{Service Name}'}/index.mdx, or domains/{'{Domain Name}'}/systems/{'{System Name}'}/services/{'{Service Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+If the catalog does not have any domains, or systems, just assume and put it into the root of the catalog, no need to ask about systems or domains.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the service should live, create the right folder structure, and add the first version of the service documentation.
+
+### Manual Creation
+
+Services can live at the root of your catalog, inside a domain, inside a system, or inside a system that belongs to a domain.
+
+Create a new folder for the service with an `index.mdx` file.
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+If the service belongs to a domain, keep it inside that domain:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'services',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'OrdersService',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Services can also live inside systems:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Shopping',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cart-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    {
+                      name: 'services',
+                      type: 'folder',
+                      defaultOpen: true,
+                      children: [
+                        {
+                          name: 'CartAPI',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx', highlight: true }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+_Here is an example of what a service markdown file may look like._
+
+```md title="/services/Orders/index.mdx (example)"
+---
+# id of your service, used for slugs and references in EventCatalog.
+id: Orders
+
+# Display name of the Service, rendered in EventCatalog
+name: Orders
+
+# Version of the Service
+version: 0.0.1
+
+# Short summary of your Service
+summary: |
+  Service that contains order related information
+
+# Optional owners, references teams or users
+owners:
+    - dboyne
+
+# Optional messages this service receives and it's version
+receives:
+  - id: InventoryAdjusted
+    version: 0.0.3
+
+# Optional messages this service sends and it's version
+sends:
+  - id: AddInventory
+    version: 0.0.3
+
+# Optional flows associated with this service
+flows:
+  - id: OrderProcessing
+    version: 1.0.0
+
+# Optional badges, rendered to UI by EventCatalog
+badges:
+    - content: New service
+      backgroundColor: blue
+      textColor: blue
+---
+
+## Overview
+
+This orders service gives API consumers the ability to produce orders in the systems. Events are raised from this system for downstream consumption.
+
+<NodeGraph />
+
+```
+
+## Adding content
+
+With **services** you can write any Markdown you want and it will render on your page. Every service gets its own page.
+
+Within your markdown content you can use [components](/docs/development/components/using-components) to add interactive components to your page.
diff --git a/packages/core/docs/development/guides/resources/services/03-create-external-service.md b/packages/core/docs/development/guides/resources/services/03-create-external-service.md
new file mode 100644
index 000000000..a3405f228
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/03-create-external-service.md
@@ -0,0 +1,52 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog services
+- External services
+sidebar_label: Create an external service
+title: Create an external service
+description: Model third-party services like Stripe, Twilio, or Snowflake as external services in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.28.0" />
+
+External services are services your architecture integrates with but does not own — Stripe, Twilio, Snowflake, Auth0, and similar third-party providers. They behave like any other service in EventCatalog: they can send and receive messages, be versioned, have owners, and carry specifications. The only difference is how they are presented — purple with a Globe icon and an "External System" badge in the visualiser, and grouped under a dedicated "External Services" section in the sidebar (or "External Integrations" when inside a domain).
+
+Creating an external service is identical to creating a regular service — just add `externalSystem: true` to the frontmatter.
+
+## Example: modelling Stripe
+
+Here is an example modelling Stripe as an external service. Stripe receives a `ChargeCard` command from your `PaymentGatewayService` and sends back `StripeChargeSucceeded` and `StripeChargeFailed` webhook events.
+
+```md title="/services/Stripe/index.mdx (example)"
+---
+id: Stripe
+name: Stripe
+version: 1.0.0
+summary: External payment processor used to charge customer cards.
+externalSystem: true
+receives:
+  - id: ChargeCard
+    version: 0.0.1
+sends:
+  - id: StripeChargeSucceeded
+    version: 0.0.1
+  - id: StripeChargeFailed
+    version: 0.0.1
+---
+
+## Overview
+
+Stripe is used to process card payments. We send a `ChargeCard` command and Stripe
+webhooks back `StripeChargeSucceeded` or `StripeChargeFailed` to complete the round trip.
+
+<NodeGraph />
+```
+
+Your paired `PaymentGatewayService` would mirror this — `sends: [ChargeCard]` and `receives: [StripeChargeSucceeded, StripeChargeFailed]` — giving you a complete integration contract visible in the visualiser.
+
+![Stripe rendered as an external service in the EventCatalog visualiser](./img/services/external-system-stripe.png)
+
+Modelling third-party systems this way lets you document exactly what you call and what they call back, see external dependencies cleanly separated from your own services on the visualiser, and reason about which of your services depend on which third parties.
\ No newline at end of file
diff --git a/packages/core/docs/development/guides/resources/services/04-add-resources-to-services/01-add-messages-to-services.md b/packages/core/docs/development/guides/resources/services/04-add-resources-to-services/01-add-messages-to-services.md
new file mode 100644
index 000000000..78ff38e0c
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/04-add-resources-to-services/01-add-messages-to-services.md
@@ -0,0 +1,142 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_position: 1
+sidebar_label: Add messages to services
+title: Add messages to services
+description: Understanding how to add messages to services.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+A service in EventCatalog can **receive** (consume) or **send** (produce) messages ([commands](/docs/development/guides/resources/messages/message-types/commands), [events](/docs/development/guides/resources/messages/message-types/events) and [queries](/docs/development/guides/resources/messages/message-types/queries)). 
+
+![Example](../../../img/services/example.png)
+
+## Producing and consuming messages from your service
+
+To add messages to your service you first have to define your messages, if you don't have any messages you can create one.
+
+To add messages to a service you need to define them in either the **sends** or **receives** array within your service frontmatter API.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+receives:
+    # id of the message this service receives (consumes)
+    - id: PaymentProcessed
+    # (optional) The version of the message you want to add.
+    # Supports semver matching (e.g ^1.0.1, 1.x.x). 
+    # But if no version is given the latest version of the message will be used.
+      version: 0.0.1
+sends:
+    # id of the message this service sends (produces)
+    - id: OrderProcessed
+      version: 2.x.x
+---
+
+<!-- Markdown contents... -->
+
+```
+
+:::info The power of versioning
+  When you define your messages for your service you can define the version of them too. This can be powerful if you have multiple versions of your events, commands or queries. Example could be an API that you are consuming, maybe you are consuming an old version of this API you can specify that.
+:::
+
+### Routing messages through channels
+
+Messages may also travel through [channels](https://www.enterpriseintegrationpatterns.com/patterns/messaging/MessageChannel.html) (e.g message brokers, queues, buses).
+
+To specify a channel you need to use the `to` and `from` fields in your service frontmatter.
+
+This example shows :
+- the `OrderService` sending an `OrderPlaced` message to the `orders.events` channel.
+- the `OrderService` consuming the a `PaymentProcessed` message from the `payments.events` channel.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+
+# Service sends a message called OrderPlaced
+# This message is published to the orders.events channel (e.g broker)
+sends:
+  - id: OrderPlaced
+    to:
+      # The id of the channel (e.g queue)
+      - id: orders.events
+
+# Service consumes a message called PaymentProcessed
+# This message is consumed from the payments.events channel (e.g queue)
+receives:
+  - id: PaymentProcessed
+    from:
+      # The id of the channel (e.g bus)
+      - id: payments.events
+---
+```
+
+You can read more about routing messages through channels in the [routing messages through channels guide](/docs/development/guides/resources/messages/message-channels/introduction).
+
+
+<!-- ### Group messages in the visualiser
+
+<AddedIn version="3.27.0" />
+
+When a service sends or receives many messages, the visualiser can become crowded. You can use the `group` field on any `sends` or `receives` entry to collect related messages into a named group node.
+
+```md title="/services/WarehouseService/index.mdx (example)"
+---
+id: WarehouseService
+version: 1.0.0
+name: Warehouse Service
+sends:
+  - id: ShipmentDispatched
+    version: 1.0.0
+    group: Shipping
+  - id: ShipmentFailed
+    version: 1.0.0
+    group: Shipping
+  - id: PickRequested
+    version: 1.0.0
+    group: Picking
+receives:
+  - id: OrderPlaced
+    version: 1.0.0
+    group: Orders
+---
+```
+
+Messages that share the same `group` value are collapsed into a single stacked (purple) card node in the visualiser. The node displays the group name and the number of messages it contains.
+
+![Message group expanded in the visualiser](../../../img/services/message-group-expanded.png)
+
+Click the group node to expand it. The expanded view renders each individual message inside a container, along with the full downstream graph: channels the messages route to and any connected producer or consumer services, exactly as they would appear when ungrouped. Click **Collapse** inside the expanded container to return to the compact group node.
+
+![Message group expanded in the visualiser](../../../img/services/expanding-groups.png)
+
+Groups can be combined with channel routing. The expanded view will show the correct channel paths for each message.
+
+```md title="/services/WarehouseService/index.mdx (example)"
+---
+id: WarehouseService
+version: 1.0.0
+name: Warehouse Service
+sends:
+  - id: ShipmentDispatched
+    version: 1.0.0
+    group: Shipping
+    to:
+      - id: shipping.events
+  - id: ShipmentFailed
+    version: 1.0.0
+    group: Shipping
+---
+``` -->
+
+<!-- ### Visualizing messages within a service
+
+When messages get added within your services EventCatalog will visualize this for you either using the `NodeGraph` component or through the visualizer.
+
+![Example](../../../img/services/visualiser.png) -->
diff --git a/packages/core/docs/development/guides/resources/services/04-add-resources-to-services/02-add-data-stores-to-services.md b/packages/core/docs/development/guides/resources/services/04-add-resources-to-services/02-add-data-stores-to-services.md
new file mode 100644
index 000000000..229c3796f
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/04-add-resources-to-services/02-add-data-stores-to-services.md
@@ -0,0 +1,45 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_position: 2
+sidebar_label: Add data stores to services
+title: Add data stores to services
+description: Adding data stores to services
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+In EventCatalog a [data store](/docs/development/guides/resources/data/introduction) is a persistent storage system (e.g database, cache, index) that holds information used by one or resources.
+
+Your service can **read** and/or **write** to any data store documented in your catalog.
+
+## Specifying read/write relationships
+
+To document the read/write relationship from a service to a data store you use the **writesTo** or **readsFrom** array within your service frontmatter API.
+
+In the example below the `OrderService` writes to the `OrdersDatabase` and reads from the `ProductRedisCache`.
+
+```md title="/services/Orders/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+writesTo:
+    # id of the data store this service writes to
+    - id: OrdersDatabase
+readsFrom:
+    # id of the data store this service reads from
+    - id: ProductRedisCache
+      # optional version of the data store if none provided latest will be used
+      # also supports sever matching (0.x.x)
+      version: 0.0.1
+---
+
+```
+
+You can choose not to provide a version for a data store. If no version is given **latest** is used by default.
+
+### Visualizing data stores within a service
+
+When your service reads/writes to a data store, EventCatalog will visualize this relationship [(see example)](https://demo.eventcatalog.dev/visualiser/services/OrdersService/0.0.3)
+
+![Example](../../../img/services/visualiser-with-data.png)
diff --git a/packages/core/docs/development/guides/resources/services/04-add-resources-to-services/03-add-entities-to-services.md b/packages/core/docs/development/guides/resources/services/04-add-resources-to-services/03-add-entities-to-services.md
new file mode 100644
index 000000000..9993f1c29
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/04-add-resources-to-services/03-add-entities-to-services.md
@@ -0,0 +1,43 @@
+---
+keywords:
+- EventCatalog services
+sidebar_position: 3
+sidebar_label: Add entities to services
+title: Add entities to services
+description: Creating and managing entities within EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Once you have [created your entities](/docs/development/guides/resources/entities/create-entity) you can add them to your services.
+
+To add an entity to a service you need to add the entity to the `entities` array in the service's markdown file.
+
+```md title="/services/PaymentService/index.mdx"
+
+---
+id: PaymentService
+name: PaymentService
+version: 1.0.0
+# This assumes you have an entity called Payment
+entities:
+  - id: Payment
+    # Optional, if not provided the latest version will be used
+    version: 1.0.0
+---
+
+Your service markdown...
+
+```
+
+## Visualize entity relationships
+
+<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.
+
+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.
+
+![Entity Map showing entity relationships](../../entities/img/entity-map.png)
+
+To learn how to define relationships between entities, see [model entity relationships](/docs/development/guides/resources/entities/model-entity-relationships).
diff --git a/packages/core/docs/development/guides/resources/services/04-add-resources-to-services/_category_.json b/packages/core/docs/development/guides/resources/services/04-add-resources-to-services/_category_.json
new file mode 100644
index 000000000..c8bfa20b8
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/04-add-resources-to-services/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Add resources to services",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/services/add-resources-to-services",
+    "description": "Add messages, data stores, and entities to your services."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/services/06-ownership-and-components/01-add-service-owners.md b/packages/core/docs/development/guides/resources/services/06-ownership-and-components/01-add-service-owners.md
new file mode 100644
index 000000000..358ffc8b3
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/06-ownership-and-components/01-add-service-owners.md
@@ -0,0 +1,40 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog
+- services 
+- owners
+sidebar_label: Add service owners
+title: Add service owners
+description: Adding owners to services with EventCatalog.
+---
+
+Owners in EventCatalog are either **users** or **teams** and are **optional**.
+
+To add an owner or a team, you need to add the user or team to the owners field of the service.
+
+## Adding owners using frontmatter
+
+To add owners within a service you need to add them to the `owners` array within your service frontmatter API.
+
+You need to add the `id` of the owner.
+
+```md title="/services/OrderService/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+owners:
+    - dboyne # represents a user
+    - webTeam # represents a team
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Assigning owners to your services can provide others with context of who owns this service and how to contact them.
+
+:::tip Creating users and teams
+    EventCatalog gives you the ability to create users and teams. You can read the documentation to get started.
+:::
+
diff --git a/packages/core/docs/development/guides/resources/services/06-ownership-and-components/02-use-components.md b/packages/core/docs/development/guides/resources/services/06-ownership-and-components/02-use-components.md
new file mode 100644
index 000000000..c652c75e7
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/06-ownership-and-components/02-use-components.md
@@ -0,0 +1,13 @@
+---
+sidebar_position: 2
+keywords:
+    - components 
+    - domains
+sidebar_label: Use components
+title: Use components
+description: Component list for domains 
+---
+
+You can add custom EventCatalog components to your services.
+
+[See the list of components and how to use them](/docs/development/components/using-components).
diff --git a/packages/core/docs/development/guides/resources/services/06-ownership-and-components/_category_.json b/packages/core/docs/development/guides/resources/services/06-ownership-and-components/_category_.json
new file mode 100644
index 000000000..8e396b611
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/06-ownership-and-components/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Ownership & components",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/services/ownership-and-components",
+    "description": "Add owners and custom components to services."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/services/07-versioning-and-lifecycle/01-version-services.md b/packages/core/docs/development/guides/resources/services/07-versioning-and-lifecycle/01-version-services.md
new file mode 100644
index 000000000..05daacc82
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/07-versioning-and-lifecycle/01-version-services.md
@@ -0,0 +1,28 @@
+---
+keywords:
+- versioning
+- services
+sidebar_position: 1
+sidebar_label: Version services
+title: Version services
+description: Learn how to version services
+---
+
+All content in EventCatalog can be versioned. This allows you to keep historic versions of content which can give context to users why things are changing.
+
+## How to version a service
+
+1. Create a `/versioned` directory inside the `/services` folder if one is not created already.
+1. Create a new folder with the version number inside the folder.
+    - Example: `/services/Orders/versioned/0.0.1`
+1. Copy contents into the new folder, it at least needs your index.mdx file.
+    - Example: `/services/Orders/versioned/0.0.1/index.mdx`
+    - Note: the version inside this index.mdx file would be `0.0.1`
+1. Bump the version of the `index.mdx` file in the route of the domain.
+    - Example `/services/Orders/index.mdx`, change the `version` to `0.0.2`
+
+## How to navigate to versions
+
+EventCatalog will automatically create links for you within your latest version of your document. Users will also be able to navigate to any version by adding the version in the url (e.g /docs/services/Orders/1.0.2 would load the 1.0.2 version of this service).
+
+![Example](../../../img/domains/versioned.png)
diff --git a/packages/core/docs/development/guides/resources/services/07-versioning-and-lifecycle/02-add-changelog.md b/packages/core/docs/development/guides/resources/services/07-versioning-and-lifecycle/02-add-changelog.md
new file mode 100644
index 000000000..25c063e9c
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/07-versioning-and-lifecycle/02-add-changelog.md
@@ -0,0 +1,52 @@
+---
+keywords:
+    - changelog 
+    - services
+sidebar_position: 2
+sidebar_label: Add a changelog
+title: Add a changelog
+description: Adding changelogs to your services
+---
+
+EventCatalog supports changelogs for [domains](/docs/domains), [services](/docs/development/guides/resources/services/introduction) and [messages](/docs/development/guides/resources/messages/what-are-messages).
+
+When you [version a service](/docs/development/guides/resources/services/versioning-and-lifecycle/version-services) in EventCatalog, you can also attach a `changelog.mdx` to that service or versioned service.
+
+### Adding a changelog
+
+1. Add a `changelog.mdx` to your service (or versioned service)
+    - example `/services/{Service}/changelog.mdx`
+    - versioned example `/services/{Service}/versioned/1.0.0/changelog.mdx`
+
+**Example**
+```md title="/docs/services/PaymentService/changelog.md"
+---
+createdAt: 2024-08-01
+badges:
+    - content: New event published
+      backgroundColor: green
+      textColor: green
+---
+
+### Service now publishes a new event
+
+The PaymentService now publishes a new event called `PaymentAccepted`
+
+``` 
+
+Navigate to your change log page for your service (example [/docs/services/PaymentService/0.0.1/changelog](https://demo.eventcatalog.dev/docs/domains/Orders/0.0.2/changelog)) or **click on the Changelog button** on your service page.
+
+:::tip "What do add to your change log?"
+Changelogs are just markdown files, this allows you to add anything you want (e.g code blocks, tables)
+
+EventCatalog code blocks supports diffs, code labels which are great features for changelogs. You can [read more here](/docs/api/code-blocks).
+
+:::
+
+### Why add changelogs?
+
+Changelogs can provide your team with the context behind the reasons and choices for changes within your service and also be used for auditing purposes.
+
+Changelogs are visualized by EventCatalog.
+
+
diff --git a/packages/core/docs/development/guides/resources/services/07-versioning-and-lifecycle/03-deprecate-services.md b/packages/core/docs/development/guides/resources/services/07-versioning-and-lifecycle/03-deprecate-services.md
new file mode 100644
index 000000000..7d952edbc
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/07-versioning-and-lifecycle/03-deprecate-services.md
@@ -0,0 +1,71 @@
+---
+keywords:
+- EventCatalog
+- services 
+- owners
+sidebar_position: 3
+sidebar_label: Deprecate services
+title: Deprecate services
+description: Deprecating services with EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.33.10" />
+
+Any resource in EventCatalog can be deprecated or marked as deprecated.
+
+This will show a banner on the page indicating that the resource is deprecated.
+
+## Deprecating services using frontmatter
+
+To deprecate a service you need to add the `deprecated` field to the service frontmatter API.
+
+This accepts a `boolean` or an `object` with the following properties:
+
+- `date`: Date the service will be or was deprecated (YYYY-MM-DD)
+- `message`: Reason the service is deprecated, supports markdown (optional)
+
+```md title="/services/OrderService/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+
+# deprecatd as an object (Recommended)
+deprecated:
+  # Date the service will be or was deprecated (YYYY-MM-DD)
+  date: 2025-01-01
+  # Reason the service is deprecated, supports markdown (optional)
+  message: | 
+    This service has been deprecated and replaced by the new service **InventoryServiceV2**.
+    Please contact the [team for more information](mailto:inventory-team@example.com) or visit our [website](https://eventcatalog.dev).
+
+# deprecated as a boolean 
+deprecated: true
+---
+
+```
+
+Configuration:
+
+- `deprecated`: `boolean` or `object`
+
+Deprecated as an object is recommended, as it gives your users more information to why the resource is deprecated and a date in the past or future.
+
+- `deprecated.date`: Date the service will be or was deprecated (YYYY-MM-DD)
+- `deprecated.message`: Reason the service is deprecated, supports markdown (optional)
+
+
+#### Rendered output
+
+Example of resource that will be deprecated:
+
+![Deprecating services](../../../img/deprecated/will-be-deprecated.png) 
+
+Example of resource that is deprecated:
+
+![Deprecating services](../../../img/deprecated/is-deprecated.png) 
+
+#### Demo
+
+You can see a demo of deprecating resources in the [EventCatalog demo site](https://demo.eventcatalog.dev/docs/services/InventoryService/0.0.2).
diff --git a/packages/core/docs/development/guides/resources/services/07-versioning-and-lifecycle/_category_.json b/packages/core/docs/development/guides/resources/services/07-versioning-and-lifecycle/_category_.json
new file mode 100644
index 000000000..bed5c1ca9
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/07-versioning-and-lifecycle/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Versioning & lifecycle",
+  "position": 7,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/services/versioning-and-lifecycle",
+    "description": "Version, deprecate, and document changes to services."
+  }
+}
diff --git a/packages/core/docs/development/guides/resources/services/08-reference.md b/packages/core/docs/development/guides/resources/services/08-reference.md
new file mode 100644
index 000000000..39eb0e9c5
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/08-reference.md
@@ -0,0 +1,295 @@
+---
+sidebar_position: 8
+keywords:
+- EventCatalog services
+- Service frontmatter
+sidebar_label: Reference
+title: Services reference
+description: Frontmatter fields, paths, and routes for services in EventCatalog.
+---
+
+This page lists the fields, paths, and routes supported by services.
+
+## Paths
+
+Services can be created at the root of your catalog:
+
+```txt
+/services/{Service Name}/index.mdx
+```
+
+Services can also be created inside domains or systems:
+
+```txt
+/domains/{Domain Name}/services/{Service Name}/index.mdx
+/systems/{System Name}/services/{Service Name}/index.mdx
+/domains/{Domain Name}/systems/{System Name}/services/{Service Name}/index.mdx
+```
+
+Versioned services use:
+
+```txt
+/services/{Service Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/services/{service-id}/{version}` | Service documentation page. |
+| `/visualiser/services/{service-id}/{version}` | Service resource diagram. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the service. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: payment-service
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the service.
+
+```md title="Example"
+---
+name: Payment Service
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the service documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short summary of what the service does.
+
+```md title="Example"
+---
+summary: Authorizes payments and emits payment lifecycle events.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the service.
+
+```md title="Example"
+---
+owners:
+  - payments-platform
+---
+```
+
+### `sends` {#sends}
+
+- Type: `array`
+
+Messages the service sends or publishes.
+
+```md title="Example"
+---
+sends:
+  - id: PaymentAuthorized
+    version: 1.0.0
+---
+```
+
+### `receives` {#receives}
+
+- Type: `array`
+
+Messages the service receives or consumes.
+
+```md title="Example"
+---
+receives:
+  - id: AuthorizePayment
+    version: 1.0.0
+---
+```
+
+### `entities` {#entities}
+
+- Type: `array`
+
+Entities associated with the service.
+
+```md title="Example"
+---
+entities:
+  - id: payment
+    version: 1.0.0
+---
+```
+
+### `writesTo` {#writesTo}
+
+- Type: `array`
+
+Data stores the service writes to.
+
+```md title="Example"
+---
+writesTo:
+  - id: payments-database
+    version: 1.0.0
+---
+```
+
+### `readsFrom` {#readsFrom}
+
+- Type: `array`
+
+Data stores the service reads from.
+
+```md title="Example"
+---
+readsFrom:
+  - id: customer-database
+    version: 1.0.0
+---
+```
+
+### `flows` {#flows}
+
+- Type: `array`
+
+Flows associated with the service.
+
+```md title="Example"
+---
+flows:
+  - id: payment-authorization
+    version: 1.0.0
+---
+```
+
+### `externalSystem` {#externalSystem}
+
+- Type: `boolean`
+
+Marks the service as an external service or integration.
+
+```md title="Example"
+---
+externalSystem: true
+---
+```
+
+### `specifications` {#specifications}
+
+- Type: `object` or `array`
+
+OpenAPI, AsyncAPI, or GraphQL specifications for the service.
+
+```md title="Example"
+---
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Public API
+  - type: asyncapi
+    path: asyncapi.yml
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the service page.
+
+```md title="Example"
+---
+badges:
+  - content: Critical
+    backgroundColor: red
+    textColor: red
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the service.
+
+```md title="Example"
+---
+repository:
+  language: TypeScript
+  url: https://github.com/acme/payment-service
+---
+```
+
+### `diagrams` {#diagrams}
+
+- Type: `array`
+
+Diagrams associated with the service.
+
+```md title="Example"
+---
+diagrams:
+  - id: payment-service-sequence
+    version: 1.0.0
+---
+```
+
+### `attachments` {#attachments}
+
+- Type: `array`
+
+External links or supporting documents attached to the service.
+
+```md title="Example"
+---
+attachments:
+  - url: https://runbooks.example.com/payment-service
+    title: Payment Service runbook
+    type: runbook
+---
+```
+
+## Resource pointers
+
+Services reference related resources using `id` and optional `version`.
+
+```md
+---
+sends:
+  - id: OrderCreated
+receives:
+  - id: CreateOrder
+writesTo:
+  - id: orders-database
+flows:
+  - id: checkout-flow
+---
+```
+
+If `version` is omitted, EventCatalog uses the latest version.
diff --git a/packages/core/docs/development/guides/resources/services/_category_.json b/packages/core/docs/development/guides/resources/services/_category_.json
new file mode 100644
index 000000000..206064c1c
--- /dev/null
+++ b/packages/core/docs/development/guides/resources/services/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Services",
+  "position": 1,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources/services",
+    "description": "A collection of guides to help you understand services and how they work with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/guides/systems/01-introduction.md b/packages/core/docs/development/guides/systems/01-introduction.md
new file mode 100644
index 000000000..8de742e80
--- /dev/null
+++ b/packages/core/docs/development/guides/systems/01-introduction.md
@@ -0,0 +1,119 @@
+---
+keywords:
+- EventCatalog domains
+- EventCatalog systems
+sidebar_label: What are systems?
+title: What are systems?
+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" />
+
+A system is a collection of resources that work together to perform a function.
+
+In EventCatalog, systems help you document software capabilities at a useful operating level. They often sit between domains and the lower-level resources that make up your architecture, but they do not have to belong to a domain.
+
+One way you can think of this:
+
+- **Domains** describe a business boundary or bounded context.
+- **Systems** describe a software capability or external system.
+- **Resources** describe the things that make up, connect to, or document that system.
+
+For example, a `Shopping` domain might contain a `Cart System` and a `Promotion System`. The `Cart System` is made up of resources (e.g cart state, service (API), and publishes events).
+
+## Why use systems?
+
+Systems help teams document architecture at a useful operating level.
+
+Services, messages, containers, flows, and entities are useful on their own, but larger catalogs can become hard to navigate if every resource sits directly inside a domain. Systems give you a way to group the resources that cooperate to deliver one capability.
+
+Use systems when you want to show:
+
+- The boundary of a product capability or technical system.
+- Which services, containers, flows, and entities belong together.
+- Which team owns a system.
+- Which people or roles interact with the system.
+- Which other systems it depends on.
+- Whether the system is internal or external.
+
+## How systems relate to other resources
+
+A system can reference:
+
+- [Services](/docs/development/guides/resources/services/introduction)
+- [Flows](/docs/development/guides/resources/flows/introduction)
+- [Entities](/docs/development/guides/resources/entities/introduction)
+- [Data stores](/docs/development/guides/resources/data/introduction)
+
+Contracts such as schemas, OpenAPI specs, AsyncAPI specs, and GraphQL schemas are documented on the messages and services inside the system. This makes the system the entry point for understanding which contracts it implements, consumes, or produces.
+
+Systems can also define:
+
+- **Relationships** to other systems, such as "calculates discounts via" or "sends notifications to".
+- **Actors**, such as "Shopper", "Support Agent", or "Warehouse Operator".
+- **Scope**, so a system can be marked as `internal` or `external`.
+
+## Systems vs services
+
+A service is an implementation resource. It might be an API, worker, backend service, frontend application, or other deployable component.
+
+A system is a higher-level boundary that can contain one or more services plus the supporting resources that make that function work.
+
+For example:
+
+- `Cart System` is the system.
+- `Cart API` is a service inside the system.
+- `cart-database` is a container inside the system.
+- `CartCheckedOut` is an event produced by the system through one of its services.
+
+## Systems vs domains
+
+A domain is a business boundary. A system is how part of that domain is implemented or operated.
+
+One domain can contain many systems. Each system can then contain the resources that belong to that specific capability.
+
+Systems can also live outside domains when they are shared, external, or not owned by one business boundary.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Shopping',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cart-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+                {
+                  name: 'promotion-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+This keeps the business model clear while still giving engineering teams a place to document the concrete systems they own and operate.
diff --git a/packages/core/docs/development/guides/systems/02-create-system.md b/packages/core/docs/development/guides/systems/02-create-system.md
new file mode 100644
index 000000000..4cbc1dfe2
--- /dev/null
+++ b/packages/core/docs/development/guides/systems/02-create-system.md
@@ -0,0 +1,127 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog systems
+sidebar_label: Create a system
+title: Create a system
+description: Create a system in EventCatalog.
+---
+
+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" />
+
+A system is a collection of resources that work together to perform a function.
+
+Use a system when you want to document a group of resources that work together to perform one function.
+
+![Example system page in EventCatalog](./img/create-system-example.png)
+
+## Creating a system
+
+### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog system">
+Read https://www.eventcatalog.dev/docs/development/guides/systems/create-system.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/systems.md then help me create a new EventCatalog system in my catalog.
+
+Ask me for the system name, what function it performs, whether it is internal or external, and whether it belongs inside a domain. Then create the correct systems/{'{System Name}'}/index.mdx or domains/{'{Domain Name}'}/systems/{'{System Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you choose where the system should live, create the right folder structure, and add the first version of the system documentation.
+
+### Manual Creation
+
+Systems can live inside a domain or at the root of your catalog.
+
+If the system clearly belongs to one domain, keep it inside that domain and [attach the domain to that system](/docs/development/guides/domains/add-resources-to-domains/add-systems-to-domains).
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Shopping',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cart-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+If the system is shared, external, or you want to attach it to domains later, create it at the root:
+
+<ProjectTree
+  items={[
+    {
+      name: 'systems',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'stripe',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Most teams start by keeping systems inside the domain they belong to.
+
+## Create the system file
+
+Create an `index.mdx` file for the system.
+
+```md title="/domains/Shopping/systems/cart-system/index.mdx"
+---
+id: cart-system
+# freindly name of the system
+name: Cart System
+version: 1.0.0
+# summary of the system
+summary: |
+  Internal system that owns the customer's shopping cart and checkout flow.
+# is the system internal to your organization or external
+scope: internal
+# who owns this system in your organization?
+owners:
+  - shopping-platform
+---
+
+## Overview
+
+The Cart System owns the shopping cart. It accepts commands to add and remove items, persists cart contents in the cart database, asks the Promotion System to calculate discounts, and publishes an event when a cart is checked out.
+```
+
+## Next steps
+
+- [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)
+- [Review the systems reference](/docs/development/guides/systems/reference)
diff --git a/packages/core/docs/development/guides/systems/03-add-resources-to-systems.md b/packages/core/docs/development/guides/systems/03-add-resources-to-systems.md
new file mode 100644
index 000000000..113a7d965
--- /dev/null
+++ b/packages/core/docs/development/guides/systems/03-add-resources-to-systems.md
@@ -0,0 +1,157 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog systems
+- system resources
+sidebar_label: Add resources to systems
+title: Add resources to systems
+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" />
+
+In EventCatalog, systems can directly reference:
+
+- [Services](/docs/development/guides/resources/services/introduction)
+- [Flows](/docs/development/guides/resources/flows/introduction)
+- [Entities](/docs/development/guides/resources/entities/introduction)
+- [Data stores](/docs/development/guides/resources/data/introduction)
+
+Messages, APIs, schemas, and channels are usually documented through the services and messages inside the system.
+
+## Add resources using frontmatter
+
+Add resources to the system frontmatter using `services`, `flows`, `entities`, and `containers`.
+
+```md title="/domains/Shopping/systems/cart-system/index.mdx"
+---
+id: cart-system
+name: Cart System
+version: 1.0.0
+# define services in this system
+services:
+  - id: cart-api
+    version: 1.0.0
+# define databases in this system    
+containers:
+  - id: cart-database
+    version: 1.0.0
+# define documented business workflows part of this system
+flows:
+  - id: checkout-flow
+    version: 1.0.0
+# define any entities that belong to this system
+entities:
+  - id: cart
+    version: 1.0.0
+---
+```
+
+The `version` is optional. If no version is given, EventCatalog uses the latest version of the referenced resource.
+
+## Keep resources inside the system folder
+
+You can also define resources inside the system folder to keep related architecture documentation together.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Shopping',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'cart-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    { name: 'index.mdx', highlight: true },
+                    {
+                      name: 'services',
+                      type: 'folder',
+                      defaultOpen: false,
+                      highlight: true,
+                      children: [
+                        {
+                          name: 'CartAPI',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx' }],
+                        },
+                      ],
+                    },
+                    {
+                      name: 'containers',
+                      type: 'folder',
+                      defaultOpen: false,
+                      highlight: true,
+                      children: [
+                        {
+                          name: 'cart-database',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx' }],
+                        },
+                      ],
+                    },
+                    {
+                      name: 'flows',
+                      type: 'folder',
+                      defaultOpen: false,
+                      highlight: true,
+                      children: [
+                        {
+                          name: 'CheckoutFlow',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx' }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+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.
+
+
+
+```md title="/domains/Shopping/systems/cart-system/index.mdx"
+## Resource Diagram
+
+<NodeGraph />
+```
+
+![Product Catalog System resource diagram](./img/product-catalog-system-resource-map.png)
+
+You can also open the resource diagram directly:
+
+```txt
+/visualiser/systems/{system-id}/{version}
+```
+
+For the complete list of supported fields, see the [systems reference](/docs/development/guides/systems/reference).
diff --git a/packages/core/docs/development/guides/systems/04-model-relationships-and-actors.md b/packages/core/docs/development/guides/systems/04-model-relationships-and-actors.md
new file mode 100644
index 000000000..85230646a
--- /dev/null
+++ b/packages/core/docs/development/guides/systems/04-model-relationships-and-actors.md
@@ -0,0 +1,86 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog systems
+- system relationships
+- system actors
+sidebar_label: Model relationships and actors
+title: Model relationships and actors
+description: Model relationships between systems and the actors that interact with them.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.0" />
+
+Systems can describe how they relate to other systems and which people, roles, or external participants interact with them.
+
+EventCatalog uses this information to render context diagrams for systems and domains.
+
+![Product Catalog System context diagram](./img/product-catalog-system-context-map.png)
+
+## Add relationships to other systems
+
+Use `relationships` to connect one system to another system.
+
+```md title="/domains/Shopping/systems/cart-system/index.mdx"
+---
+id: cart-system
+name: Cart System
+version: 1.0.0
+relationships:
+  # id of the system it has a relationship with
+  - id: promotion-system
+    # version of the system (optional)
+    version: 1.0.0
+    # label used for edge in graph
+    label: calculates discounts via
+---
+```
+
+The `label` is shown on the relationship edge in context diagrams.
+
+Relationships are one-directional. Define the relationship on the system that owns the source of the relationship.
+
+## Add actors
+
+Use `actors` to show people, roles, or external participants that interact with a system.
+
+```md title="/domains/Shopping/systems/cart-system/index.mdx"
+---
+id: cart-system
+name: Cart System
+version: 1.0.0
+# define any actors for that system
+actors:
+  # unique id for actor (shared across your catalog)
+  - id: shopper
+    name: Shopper
+    # label used in the edge
+    label: adds items and checks out
+    # inbound or outbound
+    direction: inbound
+---
+```
+
+Use `direction: inbound` when the actor interacts with the system.
+
+Use `direction: outbound` when the system reaches out to the actor, such as sending an email or notification.
+
+## Show the context diagram
+
+Add `<ContextDiagram />` to a system page to show the system in context with related systems and actors.
+
+```md title="/domains/Shopping/systems/cart-system/index.mdx"
+## Context Diagram
+
+<ContextDiagram />
+```
+
+You can also open the context diagram directly:
+
+```txt
+/visualiser/systems/{system-id}/{version}/context
+```
+
+For the complete relationship and actor fields, see the [systems reference](/docs/development/guides/systems/reference).
diff --git a/packages/core/docs/development/guides/systems/05-system-context-maps.md b/packages/core/docs/development/guides/systems/05-system-context-maps.md
new file mode 100644
index 000000000..fe26c766a
--- /dev/null
+++ b/packages/core/docs/development/guides/systems/05-system-context-maps.md
@@ -0,0 +1,67 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog systems
+- System context map
+- Architecture visualizer
+sidebar_label: System context maps
+title: System context maps
+description: Visualize systems from high-level context maps down to detailed resource maps.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.0" />
+
+System context maps 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.
+
+## Start with the system context map
+
+The global system context map shows your systems and how they relate to each other.
+
+Use this view when you want to answer questions like:
+
+- What systems exist in this architecture?
+- Which systems depend on each other?
+- 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)
+
+You can open the global system context map at:
+
+```txt
+/visualiser/system-context-map
+```
+
+## Drill into a system
+
+After users understand the high-level context, they can click into a system and view its resource diagram.
+
+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:
+
+```txt
+/visualiser/systems/{system-id}/{version}
+```
+
+For example:
+
+```txt
+/visualiser/systems/search-system/1.0.0
+```
+
+## 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.
+
+This gives teams a path from architecture overview to implementation detail without forcing every user to start at the lowest level.
diff --git a/packages/core/docs/development/guides/systems/06-reference.md b/packages/core/docs/development/guides/systems/06-reference.md
new file mode 100644
index 000000000..bfe8b20bb
--- /dev/null
+++ b/packages/core/docs/development/guides/systems/06-reference.md
@@ -0,0 +1,329 @@
+---
+sidebar_position: 6
+keywords:
+- EventCatalog systems
+- System frontmatter
+sidebar_label: Reference
+title: Systems reference
+description: Frontmatter fields, paths, and routes for systems in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.0" />
+
+This page lists the fields, paths, and routes supported by systems.
+
+## Paths
+
+Systems can be created at the root of your catalog:
+
+```txt
+/systems/{System Name}/index.mdx
+```
+
+Systems can also be created inside domains:
+
+```txt
+/domains/{Domain Name}/systems/{System Name}/index.mdx
+```
+
+Versioned systems use the same versioning pattern as other EventCatalog resources:
+
+```txt
+/systems/{System Name}/versioned/{version}/index.mdx
+/domains/{Domain Name}/systems/{System Name}/versioned/{version}/index.mdx
+```
+
+## Routes
+
+| 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. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the system. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: checkout-system
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the system.
+
+```md title="Example"
+---
+name: Checkout System
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the system documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short summary of what the system does.
+
+```md title="Example"
+---
+summary: Handles checkout, payment authorization, and order submission.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the system.
+
+```md title="Example"
+---
+owners:
+  - checkout-platform
+---
+```
+
+### `scope` {#scope}
+
+- Type: `internal` or `external`
+
+Whether the system is owned by your organization or is an external system. Defaults to `internal`.
+
+```md title="Example"
+---
+scope: external
+---
+```
+
+### `services` {#services}
+
+- Type: `array`
+
+Services that belong to the system.
+
+```md title="Example"
+---
+services:
+  - id: checkout-api
+    version: 1.0.0
+---
+```
+
+### `flows` {#flows}
+
+- Type: `array`
+
+Flows that belong to the system.
+
+```md title="Example"
+---
+flows:
+  - id: checkout-flow
+    version: 1.0.0
+---
+```
+
+### `entities` {#entities}
+
+- Type: `array`
+
+Entities that belong to the system.
+
+```md title="Example"
+---
+entities:
+  - id: order
+    version: 1.0.0
+---
+```
+
+### `containers` {#containers}
+
+- Type: `array`
+
+Containers or data stores that belong to the system.
+
+```md title="Example"
+---
+containers:
+  - id: checkout-database
+    version: 1.0.0
+---
+```
+
+### `relationships` {#relationships}
+
+- Type: `array`
+
+Other systems this system relates to.
+
+```md title="Example"
+---
+relationships:
+  - id: promotion-system
+    version: 1.0.0
+    label: calculates discounts via
+---
+```
+
+### `actors` {#actors}
+
+- Type: `array`
+
+People, roles, or external actors that interact with the system.
+
+```md title="Example"
+---
+actors:
+  - id: shopper
+    name: Shopper
+    label: adds items and checks out
+    direction: inbound
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the system page.
+
+```md title="Example"
+---
+badges:
+  - content: Critical
+    backgroundColor: red
+    textColor: red
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the system.
+
+```md title="Example"
+---
+repository:
+  language: TypeScript
+  url: https://github.com/acme/checkout
+---
+```
+
+### `diagrams` {#diagrams}
+
+- Type: `array`
+
+Diagrams associated with the system.
+
+```md title="Example"
+---
+diagrams:
+  - id: checkout-deployment
+    version: 1.0.0
+---
+```
+
+### `attachments` {#attachments}
+
+- Type: `array`
+
+External links or supporting documents attached to the system.
+
+```md title="Example"
+---
+attachments:
+  - title: Checkout runbook
+    url: https://runbooks.example.com/checkout
+    type: runbook
+---
+```
+
+## Resource pointers
+
+Systems reference resources using `id` and optional `version`.
+
+```md
+---
+services:
+  - id: cart-api
+    version: 1.0.0
+containers:
+  - id: cart-database
+flows:
+  - id: checkout-flow
+entities:
+  - id: cart
+---
+```
+
+If `version` is omitted, EventCatalog uses the latest version.
+
+## Relationship fields
+
+Relationships connect one system to another system.
+
+```md
+---
+relationships:
+  - id: promotion-system
+    version: 1.0.0
+    label: calculates discounts via
+---
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Target system id. |
+| `version` | `string` | Target system version. Optional. Defaults to latest. |
+| `label` | `string` | Text shown on the relationship edge. |
+
+Relationships are one-directional. Define the relationship on the system that owns the source of the relationship.
+
+## Actor fields
+
+Actors are people, roles, or external participants that interact with a system.
+
+```md
+---
+actors:
+  - id: shopper
+    name: Shopper
+    label: adds items and checks out
+    direction: inbound
+---
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique actor id. |
+| `name` | `string` | Display name shown in diagrams. Optional. |
+| `label` | `string` | Text shown on the actor relationship edge. Optional. |
+| `direction` | `inbound` or `outbound` | `inbound` means actor to system. `outbound` means system to actor. Defaults to `inbound`. |
diff --git a/packages/core/docs/development/guides/systems/_category_.json b/packages/core/docs/development/guides/systems/_category_.json
new file mode 100644
index 000000000..b315d6883
--- /dev/null
+++ b/packages/core/docs/development/guides/systems/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Systems",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/systems",
+    "description": "A collection of guides to help you understand systems and how they work with EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/license-keys/_category_.json b/packages/core/docs/development/license-keys/_category_.json
new file mode 100644
index 000000000..7b0dd90c5
--- /dev/null
+++ b/packages/core/docs/development/license-keys/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "License Keys",
+  "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)."
+  }
+}
diff --git a/packages/core/docs/development/license-keys/integrations.md b/packages/core/docs/development/license-keys/integrations.md
new file mode 100644
index 000000000..959ed2f61
--- /dev/null
+++ b/packages/core/docs/development/license-keys/integrations.md
@@ -0,0 +1,52 @@
+---
+sidebar_position: 3
+keywords:
+- licenses
+- integrations
+- plugins
+- openapi
+- asyncapi
+sidebar_label: Integrations
+title: Getting a license key for integrations
+description: How to use EventCatalog Scale with integrations such as OpenAPI, AsyncAPI, Backstage, and more.
+---
+
+EventCatalog integrations (sometimes called plugins) let you generate your catalog from sources you already have — OpenAPI specs, AsyncAPI documents, Backstage, federated catalogs, and more. You can see the full list on the [integrations page](/integrations).
+
+Official integrations are included with EventCatalog Scale. Start Scale from your [EventCatalog Cloud dashboard](https://eventcatalog.cloud/dashboard) and use your Scale license key to unlock supported integrations in your catalog.
+
+![Pick your integrations in EventCatalog Cloud](./images/pick-your-integraions.png)
+
+Once Scale is active, your license key appears on your [API keys page](https://eventcatalog.cloud/dashboard/api-keys):
+
+![Your license keys in the EventCatalog Cloud API keys dashboard](./images/api-keys-dashboard.png)
+
+## Adding your Scale key to your catalog
+
+Copy your Scale license key from your dashboard into your `.env` file:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key-here
+```
+
+Then configure the integration in your `eventcatalog.config.js` as described in the [integration's documentation](/integrations).
+
+:::info Using plugin API keys?
+If you already have older plugin-specific API keys, you can still use them with the environment variables shown in each integration's documentation.
+
+For example, the OpenAPI plugin supports:
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_OPENAPI=your-license-key-here
+```
+
+For new projects, use `EVENTCATALOG_SCALE_LICENSE_KEY`.
+:::
+
+## Trying multiple integrations
+
+Scale includes all official integrations, so you can configure multiple integrations in the same catalog with the same Scale license key.
+
+## Need more time?
+
+If 30 days isn't enough to evaluate Scale and integrations in your environment, email us at `hello@eventcatalog.dev` and we'll extend your trial.
diff --git a/packages/core/docs/development/license-keys/license-validation.md b/packages/core/docs/development/license-keys/license-validation.md
new file mode 100644
index 000000000..b3a48c893
--- /dev/null
+++ b/packages/core/docs/development/license-keys/license-validation.md
@@ -0,0 +1,34 @@
+---
+sidebar_position: 4
+keywords:
+- licenses
+- validation
+- offline
+sidebar_label: License Validation
+title: How license validation works
+description: How EventCatalog validates your license keys online and offline.
+---
+
+Once you have a license key from [EventCatalog Cloud](https://eventcatalog.cloud) (see [Overview](/docs/development/license-keys/overview) if you don't yet), EventCatalog validates it every time you build or serve your catalog. There are two modes: online and offline.
+
+## Online validation (default)
+
+By default, EventCatalog validates license keys online. Your keys are read from your `.env` file (or environment variables) and verified against the EventCatalog API.
+
+This is the recommended mode — it requires no extra setup and your keys stay in sync with your account automatically.
+
+## Offline validation
+
+If you're behind a firewall or otherwise can't reach the EventCatalog API at build time, you can validate your keys offline.
+
+To set up offline validation:
+
+1. Email us at `hello@eventcatalog.dev` to request an offline license file (`license.jwt`).
+2. Place the `license.jwt` file in the root of your catalog directory.
+3. EventCatalog will validate against the local file instead of calling our API.
+
+Offline license files expire one year from purchase. You'll need to request a new file each year.
+
+## Managing your keys
+
+You can view, rotate, and revoke license keys at any time from your [API keys dashboard](https://eventcatalog.cloud/dashboard/api-keys).
diff --git a/packages/core/docs/development/license-keys/overview.md b/packages/core/docs/development/license-keys/overview.md
new file mode 100644
index 000000000..017eb98f7
--- /dev/null
+++ b/packages/core/docs/development/license-keys/overview.md
@@ -0,0 +1,41 @@
+---
+sidebar_position: 1
+keywords:
+- licenses
+- license keys
+- trial
+sidebar_label: Overview
+title: License Keys Overview
+description: Learn how license keys work in EventCatalog, how to get a free trial, and where to find your keys.
+---
+
+EventCatalog is open source with a [community edition and commercial plans](/pricing). EventCatalog Scale, Enterprise, and commercial integrations are unlocked using **license keys**.
+
+If you are using the community edition, you don't need a license key and can skip this section.
+
+## Where license keys come from
+
+All license keys are managed in [EventCatalog Cloud](https://eventcatalog.cloud). You sign up for an account, activate the plan or integration you want to use, and your license keys appear on your dashboard.
+
+You can then add those keys to your `.env` file (or set them as environment variables) and EventCatalog will unlock the corresponding features.
+
+## Free trials
+
+:::tip 30-day free trials
+Every plan and every integration comes with a **30-day free trial**. No payment is required to start one — just sign in to [EventCatalog Cloud](https://eventcatalog.cloud) and activate what you want to try.
+
+Need longer to evaluate? Email us at `hello@eventcatalog.dev` and we'll happily extend your trial.
+:::
+
+## Quick start
+
+1. Create an account at [eventcatalog.cloud](https://eventcatalog.cloud).
+1. Start your [EventCatalog Scale Trial](https://eventcatalog.cloud/dashboard)
+1. Pick your [integrations](https://eventcatalog.cloud/dashboard/integrations)
+4. Run your catalog with integrations and commercial features are now unlocked.
+
+## Next steps
+
+- [Starting an EventCatalog Scale plan](/docs/development/license-keys/plans)
+- [Getting license keys for integrations](/docs/development/license-keys/integrations)
+- [How license validation works (online and offline)](/docs/development/license-keys/license-validation)
diff --git a/packages/core/docs/development/license-keys/plans.md b/packages/core/docs/development/license-keys/plans.md
new file mode 100644
index 000000000..97835ff16
--- /dev/null
+++ b/packages/core/docs/development/license-keys/plans.md
@@ -0,0 +1,41 @@
+---
+sidebar_position: 2
+keywords:
+- licenses
+- scale
+- plans
+sidebar_label: Scale Plan
+title: Getting a license key for EventCatalog Scale
+description: How to start an EventCatalog Scale plan in EventCatalog Cloud and get your license key.
+---
+
+EventCatalog Scale is the self-serve commercial plan for teams that need automation, integrations, governance, and a living architecture catalog that stays in sync with code, specs, teams, and tools.
+
+See the [pricing page](/pricing) for a full breakdown of what Scale includes.
+
+## Starting a plan
+
+1. Sign in to [EventCatalog Cloud](https://eventcatalog.cloud).
+2. Go to your [dashboard](https://eventcatalog.cloud/dashboard).
+3. Start your Scale Trial License.
+4. Once the plan is active, head to your [API keys page](https://eventcatalog.cloud/dashboard/api-keys) to find your license key.
+
+   ![Your license keys in the EventCatalog Cloud API keys dashboard](./images/api-keys-dashboard.png)
+
+## Adding your license key to your catalog
+
+Copy the license key from your dashboard into your `.env` file:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-license-key-here
+```
+
+Then start EventCatalog as normal. Scale features will be unlocked automatically.
+
+## Need more time?
+
+The default trial is 30 days. If you need longer to evaluate, email us at `hello@eventcatalog.dev` and we'll extend it for you.
+
+## Enterprise
+
+If you need features beyond Scale — SSO, dedicated support, custom contracts, or on-premise/offline deployment — get in touch at `hello@eventcatalog.dev`.
diff --git a/packages/core/docs/development/upgrading/_category_.json b/packages/core/docs/development/upgrading/_category_.json
new file mode 100644
index 000000000..7ff45d532
--- /dev/null
+++ b/packages/core/docs/development/upgrading/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Upgrading",
+  "position": 13,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "starting-a-new-project/getting-started",
+    "title": "Starting a new project",
+    "description": "Learn how to install EventCatalog."
+  }
+}
diff --git a/packages/core/docs/development/upgrading/upgrading.md b/packages/core/docs/development/upgrading/upgrading.md
new file mode 100644
index 000000000..d87f03c79
--- /dev/null
+++ b/packages/core/docs/development/upgrading/upgrading.md
@@ -0,0 +1,142 @@
+---
+sidebar_position: 1
+keywords:
+- Upgrade EventCatalog
+sidebar_label: Upgrading EventCatalog
+title: Upgrading EventCatalog
+description: How to upgrade EventCatalog.
+---
+
+## Upgrade to latest version
+
+To upgrade your EventCatalog to the latest version you can run the following command in your catalog directory.
+
+```bash
+npm install @eventcatalog/core@latest
+```
+
+### Manual upgrade
+
+To upgrade your EventCatalog you can find the packages `@eventcatalog/core` your `package.json` file.
+
+```json
+{
+  "name": "my-catalog",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    ...
+  },
+  "dependencies": {
+    // Using "latest" will install the latest version of EventCatalog keeping you up to date
+    // or you can specify a specific version like "@eventcatalog/core": "2.4.0"
+    "@eventcatalog/core": "latest"
+  }
+}
+```
+
+Once you upgrade the version number, run `npm install` to install the latest updates.
+
+:::tip
+If you don't see the changes you expect, try removing the `.eventcatalog-core` folder, `node_modules` folder and install fresh again.
+:::
+
+### Having problems?
+
+Trying to upgrade and having issues? Try these steps
+
+1. Delete `node_modules` folder
+1. Delete `.eventcatalog-core` folder
+1. Delete `package-lock.json` (if you have one).
+1. Run `npm run i`
+1. Verify if issues are fixed
+
+Still having issues?
+  1. [Raise an issue on GitHub](https://github.com/event-catalog/eventcatalog) about your problems and how to replicate it.
+  1. Or join our [Discord](https://eventcatalog.dev/discord) and add your problem to the [Bugs channel](https://discord.com/channels/918092420338569216/1272467373042958377).
+
+## Upgrading from v1 to v2
+
+If you are upgrading from EventCatalog v1 to v2 you can follow the instructions below.
+
+<details>
+  <summary>Upgrading from v1 to v2</summary>
+  EventCatalog v2 comes with some small breaking changes to your EventCatalog.
+
+If you are using v1.x.x then this guide can help you.
+
+:::info Still want to use v1?
+
+**Still using v1 of EventCatalog?** V1 documentation can be found at https://v1.eventcatalog.dev/
+
+You can find the code for v1 on the branch https://github.com/event-catalog/eventcatalog/tree/v1
+
+We recommended to upgrade to v2 as support for v1 changes will be reduced.
+
+:::
+
+## Migrating to version 2
+
+EventCatalog v2 has been rewritten from the ground up. The easiest way to migrate to version 2 is following these steps:
+
+1. [Create a new Catalog](/docs/development/getting-started/installation)
+1. Delete the `domains`, `services`, `commands` and `events` folder.
+1. Copy your `eventcatalog.config.js` and `domains`, `services`, `events` folders into the new catalog.
+1. Add `ids` to all your resources ([read more](/docs/starting-a-new-project/getting-started#resources-now-require-ids))
+1. If your resource are in a nested structure [you need to flatten these out](/docs/starting-a-new-project/getting-started#resources-require-a-flat-structure).
+
+:::tip Having problems?
+If you are still having issues upgrading your catalog, [then please raise an issue on our GitHub repo.](https://github.com/event-catalog/eventcatalog/issues).
+:::
+
+
+## Resources now require ids
+
+**All domains, services and events need an id property in the frontmatter**. EventCatalog uses this `id` as the slug of the page and uses it as internal references.
+
+#### Example
+```md
+---
+# id is now required on all resources (domains, services and messages)
+id: order-service
+name: Order Service
+# rest of frontmatter..
+---
+<!-- Your markdown content -->
+```
+
+## Resources require a flat structure
+
+In EventCatalog v1 you could nest your resources for example have your events or services within your domains folder. (Example /domains/services/MyService/index.mdx)
+
+This feature is not currently supported in version 2.
+
+Version 2 requires your domains, services and messages (commands, and events) to be in the root directory.
+
+## Change to build output
+
+The build output has changed from v1 from being `out` directory to `dist` directory in version 2.
+
+## Customising your Catalog
+
+Customizing your catalog is not currently supported in v2, although this is on our roadmap (July 2024).
+
+## Generator plugins
+
+EventCatalog v1 supports generators (from EventBridge and AsyncAPI).
+
+EventCatalog v2 does not support these yet and are on the roadmap (July 2024).
+
+## Missing components
+
+Components from v1 has not yet been implemented. 
+
+- `<EventExamples/>` - Not currently supported, but you can use [AccordionGroup with code blocks](/docs/development/components/components/accordian-group)
+- `<SchemaExample />` - Not currently implemented - [Issue open](https://github.com/event-catalog/eventcatalog/issues/568)
+
+## Any other issues?
+
+If you have any issues or questions please [feel free to reach us on Discord](https://discord.com/invite/3rjaZMmrAm).
+
+</details>
+
diff --git a/packages/core/docs/development/upgrading/v2.md b/packages/core/docs/development/upgrading/v2.md
new file mode 100644
index 000000000..76fce083a
--- /dev/null
+++ b/packages/core/docs/development/upgrading/v2.md
@@ -0,0 +1,68 @@
+---
+sidebar_position: 4
+keywords:
+- Upgrade EventCatalog
+sidebar_label: v2 
+title: Upgrade to EventCatalog v2
+description: How to upgrade to EventCatalog v2.
+---
+
+This guide will help you upgrade from v1 to v2 of EventCatalog.
+
+EventCatalog v2 comes with some small breaking changes to your EventCatalog.
+
+:::info Still want to use v1?
+
+**Still using v1 of EventCatalog?** V1 documentation can be found at https://v1.eventcatalog.dev/
+
+You can find the code for v1 on the branch https://github.com/event-catalog/eventcatalog/tree/v1
+
+We recommended to upgrade to v2 as support for v1 changes will be reduced.
+
+:::
+
+## Migrating to version 2
+
+EventCatalog v2 has been rewritten from the ground up. The easiest way to migrate to version 2 is following these steps:
+
+1. [Create a new Catalog](/docs/development/getting-started/installation)
+1. Delete the `domains`, `services`, `commands` and `events` folder.
+1. Copy your `eventcatalog.config.js` and `domains`, `services`, `events` folders into the new catalog.
+1. Add `ids` to all your resources ([read more](/docs/starting-a-new-project/getting-started#resources-now-require-ids))
+1. If your resource are in a nested structure [you need to flatten these out](/docs/starting-a-new-project/getting-started#resources-require-a-flat-structure).
+
+:::tip Having problems?
+If you are still having issues upgrading your catalog, [then please raise an issue on our GitHub repo.](https://github.com/event-catalog/eventcatalog/issues).
+:::
+
+
+## Resources now require ids
+
+**All domains, services and events need an id property in the frontmatter**. EventCatalog uses this `id` as the slug of the page and uses it as internal references.
+
+#### Example
+```md
+---
+# id is now required on all resources (domains, services and messages)
+id: order-service
+name: Order Service
+# rest of frontmatter..
+---
+<!-- Your markdown content -->
+```
+
+## Resources require a flat structure
+
+In EventCatalog v1 you could nest your resources for example have your events or services within your domains folder. (Example /domains/services/MyService/index.mdx)
+
+This feature is not currently supported in version 2.
+
+Version 2 requires your domains, services and messages (commands, and events) to be in the root directory.
+
+## Change to build output
+
+The build output has changed from v1 from being `out` directory to `dist` directory in version 2.
+
+## Any other issues?
+
+If you have any issues or questions please [feel free to reach us on Discord](https://discord.com/invite/3rjaZMmrAm).
diff --git a/packages/core/docs/development/upgrading/v3.md b/packages/core/docs/development/upgrading/v3.md
new file mode 100644
index 000000000..52ae0235a
--- /dev/null
+++ b/packages/core/docs/development/upgrading/v3.md
@@ -0,0 +1,276 @@
+---
+sidebar_position: 3
+keywords:
+- Upgrade EventCatalog
+sidebar_label: v3
+title: Upgrade to EventCatalog v3
+description: How to upgrade to EventCatalog v3.
+---
+
+This guide will help you upgrade from v2 to v3 of EventCatalog. (Missed the announcement? [Read the blog post](/blog/eventcatalog-v3) to find out what's new.)
+
+Need to see the v2 docs? Visit this [older version of the docs site](https://v2.eventcatalog.dev/). EventCatalog V2 will continue to get security updates, but new features and improvements will only be available in v3.
+
+## Upgrade EventCatalog
+
+Update your project’s version of EventCatalog to the latest version using your package manager:
+
+```bash
+npm install @eventcatalog/core@latest
+```
+
+_Problems upgrading? [Try resetting your project](/docs/development/upgrading#having-problems)._
+
+## Deprecated
+
+The following deprecated features are no longer supported and are no longer documented. Please update your project accordingly.
+
+Some deprecated features may temporarily continue to function until they are completely removed. Others may silently have no effect, or throw an error prompting you to update your code.
+
+### Deprecated: Visualizer sidebar icon
+
+The visualizer vertical sidebar icon has been removed and replaced with the new navigation system.
+
+To get to the visualizer for a resource, you will now click on the **Visualizer** link in the new navigation system.
+
+### Deprecated: `/architecture/` pages
+
+The general `/architecture/domains`, `/architecture/services` and `/architecture/messages` pages have been removed and replaced with architecture pages per domains and service.
+
+To get to the architecture, you will now click on the **Architecture Diagram** link in the new navigation system.
+
+### Deprecated: Resource sidebars
+
+The resource sidebar (sidebar on the right of the page) has been removed and replaced with `On this page` section.
+
+We have moved the resource information into the new navigation system.
+
+### Deprecated: `@eventcatalog/generator-ai` package
+
+The AI package has been removed and replaced with the [EventCatalog Assistant](/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-eventcatalog-assistant).
+
+#### What do I need to do?
+
+Remove the `@eventcatalog/generator-ai` package from your project (if you have one) and any references to it in your generator configuration.
+
+```bash
+npm uninstall @eventcatalog/generator-ai
+```
+
+## Removed
+
+The following features have now been entirely removed from the code base and can no longer be used. Some of these features may have continued to work in your project even after deprecation. Others may have silently had no effect.
+
+Projects now containing these removed features will be unable to build, and there will no longer be any supporting documentation prompting you to remove these features.
+
+### Removed: `LIST_VIEW` and `SIDE_VIEW` navigation options 
+
+EventCatalog v3 introduces a new navigation sidebar.
+
+For maintainability reasons going forward we have removed the old `LIST_VIEW` and `SIDE_VIEW` navigation options.
+
+#### What do I need to do?
+
+Remove the `sidebar.type` property from your `eventcatalog.config.js` file.
+
+```diff title="eventcatalog.config.js"
+module.exports = {
+   docs: {
+-    sidebar: {
+-       type: 'LIST_VIEW'
+-    }
+  }
+};
+```
+
+### Removed: `/docs` landing page
+
+In EventCatalog v2 we had two homepages, one for `/` and one for `/docs` (both could be customized).
+
+#### What do I need to do?
+
+You can removed the `/pages/index.mdx` file from your project (if you have one).
+
+If you still need to customize the homepage you can create a `/pages/homepage.astro` file and add your own content to it.
+
+### Removed: Pagefind (updated search)
+
+In EventCatalog v2 we used Pagefind for search, this would run after you build your catalog and index your resources.
+
+We have now moved to `nanostores` to share state across the catalog, and users no longer have to build their catalog to search.
+
+### Removed: EventCatalog Chat
+
+We have removed the EventCatalog Chat feature as it was in EventCatalog v2, and any model npm packages used.
+
+We have replaced EventCatalog Chat with the [EventCatalog Assistant](/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-eventcatalog-assistant).
+
+#### What do I need to do?
+
+Remove the `@eventcatalog/generator-ai` plugin from your project (if you have one)
+
+```bash
+npm uninstall @eventcatalog/generator-ai
+```
+
+Remove the chat configuration from your `eventcatalog.config.js` file (if you have one)
+
+```diff title="eventcatalog.config.js"
+module.exports = {
+    chat: {
+      enabled: true,
+-      provider: 'openai'
+-      model: 'o4-mini',
+    }
+};
+```
+
+The model and provider configuration has been moved to the `eventcatalog.chat.js` file.
+
+You can read more about the new AI assistant in the [AI assistant documentation](/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-eventcatalog-assistant).
+
+### Removed: EventCatalog Chat prompts
+
+We have removed the EventCatalog Chat prompts in EventCatalog. 
+
+#### What do I need to do?
+
+Remove the `chat-prompts` directory from your project (if you have one)
+
+```bash
+rm -rf chat-prompts
+```
+
+_We plan to support custom prompts and tools in the future._
+
+
+### Removed: Governance Reports
+
+We have removed the Governance Reports feature which used EventCatalog with AI to generate reports on your architecture. We will be reviewing better ways to support governance reports in the future but for now we have decided to remove the feature.
+
+## Breaking changes
+
+The following changes are considered breaking changes in EventCatalog v3. Breaking changes may or may not provide temporary backwards compatibility. If you were using these features, you may have to update your code as recommended in each entry.
+
+### Changed: Domain hierarchy changed
+
+Previously in EventCatalog v2 domains would show all resources within it's subdomains and services including all the messages in that service. A cascading approach was used to show the resources.
+
+In EventCatalog v3 domains are now more explicit about what resources are within it and you have to specify the resources you want to include in the domain.
+
+This allows us to move forward to support [domain level specifications and events (in this RFC)](https://github.com/event-catalog/eventcatalog/issues/1816)
+
+### Changed: Authentication
+
+In EventCatalog v3 we introduced a new configuration variable to enable authentication, which fixes the need for catalogs running on the server without authentication required.
+
+If you are using authentication you will need to update your `eventcatalog.config.js` file to enable authentication.
+
+```diff title="eventcatalog.config.js"
+module.exports = {
++  auth: {
++    enabled: true,
++  }
+};
+```
+
+### Changed: EventCatalog no longer supports `.md` files
+
+EventCatalog v3 no longer supports `.md` files and only supports `.mdx` files.
+
+EventCatalog v2 would transform any `.md` files found in your catalog to `.mdx` files during the migration to v2, we have removed this going forward.
+
+#### What do I need to do?
+
+If you have any `.md` files in your catalog, you will need to convert them to `.mdx` files. You can use the `eventcatalog convert` command to convert your `.md` files to `.mdx` files.
+
+```bash
+eventcatalog convert
+```
+
+### Changed: Changelogs are disabled by default
+
+In EventCatalog v3 changelogs are now disabled by default. If you want to enable changelogs for your resources you will need to update your `eventcatalog.config.js` file.
+
+#### What do I need to do?
+
+If you want to enable changelogs, add the `changelog` configuration to your `eventcatalog.config.js` file:
+
+```diff title="eventcatalog.config.js"
+module.exports = {
++  changelog: {
++    enabled: true,
++  }
+};
+```
+
+## New features
+
+The following new features and improvements have been added to EventCatalog v3.
+
+### New context aware navigation
+
+EventCatalog v2 sidebars were restricting in the way users could navigate their resources. With a growing number of resources this became a bottleneck.
+
+To solve this we have introduced a new navigation system that introduces new benefits:
+
+- **Context aware navigation** - the navigation system is aware of the context of the resource itself.
+- **Filtered information** - Information is only shown which is relevant to the context of the resource itself.
+- **Drilldown navigation** - you can drill down into your resources to see more information.
+- **Better performance** as information is now stored in nanostores.
+- **Fully customizable navigation system** - define your own navigation system for your catalog.
+- **Favorited resources** - add your favorite resources to your navigation system.
+
+You can read more about the new context aware navigation in the [documentation sidebar documentation](/docs/development/customization/documentation-sidebar).
+
+### New caching and performance improvements
+
+In EventCatalog v3 we have introduced a new caching system that will cache the information for your resources.
+
+We also introduced `nanostores` to the code base, this will help us with performance and caching of information across pages.
+
+Catalogs now have better lighthouse scores (demo has 100/100).
+
+### Store business workflows with your services and domains
+
+In EventCatalog v3 you can now assign flows to your services and domains.
+
+This can help you document business workflows and features that are relevant to your services and domains.
+
+To get started, you can add the `flows` property to your domain frontmatter.
+
+### New homepage for catalogs
+
+In EventCatalog v3 we have introduced a new homepage for your catalog.
+
+If you want to customize the homepage you can create a `/pages/homepage.astro` file and add your own content to it.
+
+### llms.txt is now enabled by default
+
+We have enabled llms.txt by default in EventCatalog v3, as this is a common use case for EventCatalog and helps with AI integrations.
+
+#### What do I need to do?
+
+Remove the `llmsTxt` property from your `eventcatalog.config.js` file (if you have one)
+
+```diff title="eventcatalog.config.js"
+module.exports = {
+-   llmsTxt: {
+-       enabled: true,
+-   }
+};
+```
+
+If you want to disable llms.txt you can set the `enabled` property to `false`.
+
+```diff title="eventcatalog.config.js"
+module.exports = {
+    llmsTxt: {
+        enabled: false,
+    }
+};
+```
+
+## Known issues
+
+Please check [EventCatalog issues on GitHub](https://github.com/event-catalog/eventcatalog/issues) for any reported issues, or to file an issue yourself.
diff --git a/packages/core/docs/development/upgrading/v4.md b/packages/core/docs/development/upgrading/v4.md
new file mode 100644
index 000000000..1fa620c37
--- /dev/null
+++ b/packages/core/docs/development/upgrading/v4.md
@@ -0,0 +1,377 @@
+---
+sidebar_position: 2
+keywords:
+- Upgrade EventCatalog
+sidebar_label: v4
+title: Upgrade to EventCatalog v4
+description: How to upgrade to EventCatalog v4.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+This guide will help you upgrade from v3 to v4 of EventCatalog.
+
+EventCatalog v4 introduces systems as a first-class resource, adds system context maps, updates the Discover and Application sidebar experience, moves EventCatalog onto Astro 7 internally, and removes the PDF export feature.
+
+:::info v4 beta
+
+The v4 branch is currently published as a beta. If v4 has not been promoted to `latest` yet, install the beta package instead of `latest`.
+
+:::
+
+## Upgrade EventCatalog
+
+Update your project's version of EventCatalog using your package manager:
+
+```bash
+npm install @eventcatalog/core@latest
+```
+
+If you are testing the v4 beta, use the beta tag:
+
+```bash
+npm install @eventcatalog/core@beta
+```
+
+_Problems upgrading? [Try resetting your project](/docs/development/upgrading#having-problems)._
+
+## Before you upgrade
+
+Most v3 catalogs should continue to build without changing their existing resources. You do not need to move your services, messages, flows, entities, or data stores into systems to upgrade to v4.
+
+Before upgrading, we recommend:
+
+1. Create a branch for the upgrade.
+1. Upgrade `@eventcatalog/core`.
+1. Remove `.eventcatalog-core`, `node_modules`, and your lock file if the catalog does not pick up the new version.
+1. Run your catalog locally and check custom pages, custom navigation, and visualiser links.
+
+## Removed
+
+The following features have now been entirely removed from the code base and can no longer be used.
+
+### Removed: Export to PDF
+
+The Export to PDF / print feature has been removed from EventCatalog v4.
+
+#### What do I need to do?
+
+Remove any user guidance, screenshots, or internal runbooks that tell people to export resource pages to PDF from EventCatalog.
+
+Diagram version comparison is still available, and is no longer gated behind the Scale plan.
+
+### Removed: `/visualiser/context-map`
+
+The old global context map route has been removed.
+
+#### What do I need to do?
+
+If you have custom navigation, docs, or bookmarks that link to `/visualiser/context-map`, update them to the new system context map route:
+
+```diff title="eventcatalog.config.js"
+export default {
+  navigation: {
+    pages: [
+      {
+        type: 'item',
+        title: 'System Context Map',
+-       href: '/visualiser/context-map',
++       href: '/visualiser/system-context-map',
+      },
+    ],
+  },
+};
+```
+
+## Breaking changes
+
+The following changes are considered breaking changes in EventCatalog v4. Breaking changes may or may not affect your catalog depending on how much you customize EventCatalog.
+
+### Changed: EventCatalog now uses Astro 7 internally
+
+EventCatalog v4 upgrades the internal application from Astro 6 to Astro 7.
+
+Most catalogs do not need to change anything. If you have custom Astro pages, custom integrations, or custom MDX/Markdown processing that depends on Astro internals, review those customizations during the upgrade.
+
+#### What do I need to do?
+
+If your catalog only uses EventCatalog resources and MDX content, upgrade EventCatalog and test the catalog.
+
+If you maintain custom Astro pages or custom integrations, check them against Astro 7 behavior and run the catalog locally after upgrading.
+
+### Changed: Application sidebar configuration has moved to `navigation.groups`
+
+EventCatalog v4 removes the top-level `sidebar` configuration that only let you show or hide items in the Application sidebar.
+
+You can now configure the whole Application sidebar using `navigation.groups`. This lets you define groups, labels, item order, icons, custom links, bottom-positioned groups, active route matching, and visibility.
+
+:::info
+
+`navigation.pages` still controls the context-aware documentation sidebar. Use `navigation.groups` for the Application sidebar.
+
+:::
+
+#### What do I need to do?
+
+If you are not using the top-level `sidebar` property in `eventcatalog.config.js`, there is nothing to change.
+
+If you are using `sidebar`, move that configuration to `navigation.groups`.
+
+```diff title="eventcatalog.config.js"
+export default {
+-  sidebar: [
+-    { id: '/directory/teams', visible: false },
+-    { id: '/schemas/fields', visible: false },
+-  ],
++  navigation: {
++    groups: [
++      {
++        id: 'main',
++        items: [{ id: 'home' }, { id: 'docs' }],
++      },
++      {
++        id: 'browse',
++        label: 'Browse',
++        items: [
++          { id: 'catalog' },
++          { id: 'schemas' },
++          { id: 'schema-insights', visible: false },
++        ],
++      },
++      {
++        id: 'organization',
++        label: 'Organization',
++        items: [{ id: 'teams', visible: false }, { id: 'users' }],
++      },
++      {
++        id: 'settings',
++        position: 'bottom',
++        items: [{ id: 'settings' }],
++      },
++    ],
++  },
+};
+```
+
+Built-in Application sidebar item IDs include:
+
+- `home`
+- `docs`
+- `catalog`
+- `schemas`
+- `schema-insights`
+- `teams`
+- `users`
+- `settings`
+You can also use route IDs such as `/schemas/explorer` or add custom items:
+
+```js title="eventcatalog.config.js"
+export default {
+  navigation: {
+    groups: [
+      {
+        id: 'platform',
+        label: 'Platform',
+        items: [
+          {
+            id: 'platform-docs',
+            label: 'Platform Docs',
+            icon: 'BookOpen',
+            href: '/docs/custom/platform/overview',
+            match: ['/docs/custom/platform'],
+          },
+          {
+            id: 'support',
+            label: 'Support',
+            icon: 'LifeBuoy',
+            href: 'https://support.example.com',
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+When `navigation.groups` is provided, it replaces the default Application sidebar groups. Add every item you want users to see.
+
+If you import `SideBarConfig` from EventCatalog types, remove that import. It is no longer exported.
+
+### Changed: Discover navigation has been simplified
+
+EventCatalog v4 replaces the resource-specific Browse sidebar links with a single Discover experience and a Kind filter. Users can switch between domains, systems, services, messages, flows, entities, data stores, and other resource collections from the Discover page.
+
+![Discover domains page showing the new Kind filter](./img/discover-domains.png)
+
+#### What do I need to do?
+
+If you use the default Application sidebar, there is nothing to change.
+
+If you have custom screenshots, onboarding docs, or training material that mentions the old resource-specific Browse links, update them to reference Discover and the Kind filter.
+
+### Changed: System context maps are now the high-level architecture view
+
+EventCatalog v4 adds dedicated system context map routes:
+
+- `/visualiser/system-context-map` for the global system context map.
+- `/visualiser/systems/:id/:version/context` for a single system in context.
+- `/visualiser/domains/:id/:version/systems-context` for systems inside a domain.
+
+The existing resource visualiser routes still work for resources such as services and domains.
+
+#### What do I need to do?
+
+Update any custom links that should point users to the new high-level system context map.
+
+## New features
+
+The following new features and improvements have been added to EventCatalog v4.
+
+### Systems are now a first-class resource
+
+Systems are collections of resources that work together to perform a function, such as checkout, payment processing, customer identity, or product search.
+
+A system can group the resources that cooperate to deliver one capability, including [services](/docs/development/guides/resources/services/introduction), [flows](/docs/development/guides/resources/flows/introduction), [entities](/docs/development/guides/resources/entities/introduction), [data stores](/docs/development/guides/resources/data/introduction), [diagrams](/docs/development/bring-your-own-documentation/diagrams/introduction), and documentation.
+
+![Catalog domain system context map showing systems and actors](./img/catalog-systems-context.png)
+
+Systems are versioned resources. You can define them at the top level of your catalog, or inside a domain when that system clearly belongs to a business boundary.
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Payments',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: 'payment-processing-system',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    { name: 'index.mdx', highlight: true },
+                    {
+                      name: 'services',
+                      type: 'folder',
+                      defaultOpen: true,
+                      children: [
+                        {
+                          name: 'PaymentAPI',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx' }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Example system frontmatter:
+
+```md title="domains/Payments/systems/payment-processing-system/index.mdx"
+---
+id: payment-processing-system
+name: Payment Processing System
+version: 1.0.0
+summary: Handles payment authorization, capture, and refund processing.
+owners:
+  - payments-platform
+services:
+  - id: PaymentAPI
+flows:
+  - id: CheckoutSaga
+relationships:
+  - id: fraud-detection
+    version: 1.0.0
+    label: requests fraud checks from
+---
+```
+
+You can also reference systems from a domain:
+
+```md title="domains/Payments/index.mdx"
+---
+id: payments
+name: Payments
+version: 1.0.0
+systems:
+  - id: payment-processing-system
+    version: 1.0.0
+---
+```
+
+Read more in the [systems documentation](/docs/development/guides/systems/introduction).
+
+### System context maps
+
+Systems can declare relationships to other systems. EventCatalog uses those relationships to render context maps that show how systems relate to each other.
+
+System context maps help users move from a high-level architecture view into a detailed system view. From the global map, users can click into a system, then explore the [services](/docs/development/guides/resources/services/introduction), [APIs](/docs/development/guides/resources/schemas/add-specifications-to-services/add-openapi-specifications), [messages](/docs/development/guides/resources/messages/what-are-messages), [flows](/docs/development/guides/resources/flows/introduction), [entities](/docs/development/guides/resources/entities/introduction), and [data stores](/docs/development/guides/resources/data/introduction) that make up that system.
+
+Read more in the [system context maps documentation](/docs/development/guides/systems/system-context-maps).
+
+### Systems in the SDK
+
+The EventCatalog SDK now supports systems. You can read and write systems, add resources to a system, write resources directly into a system, and add systems to domains.
+
+This is useful for generators and integrations that sync architecture information from source code, specifications, schema registries, or internal platforms.
+
+### Systems in AI, MCP, and catalog tools
+
+EventCatalog Assistant, MCP tools, and catalog tools now understand systems. AI workflows can retrieve systems, inspect system resources, and generate architecture diagrams for systems.
+
+### Systems in Discover, sidebars, teams, and ADRs
+
+Systems are now available across the catalog experience:
+
+- Systems can be discovered on `/discover/systems`.
+- Systems appear in sidebars with their own icon and color.
+- Teams and users can own systems.
+- ADRs can target systems with `appliesTo: [{ type: 'system' }]`.
+- Resource-level documentation can be attached to systems.
+
+### Top-level diagrams sidebar group
+
+EventCatalog v4 adds a Top level diagrams navigation group when systems exist. This surfaces the System Context Map from the sidebar so users can start from the highest-level architecture view.
+
+### Custom homepages are available in Community Edition
+
+Custom homepages are now available in Community Edition. You no longer need a paid feature flag to customize the catalog homepage.
+
+Create your custom homepage at `pages/homepage.astro`.
+
+<ProjectTree
+  items={[
+    {
+      name: 'pages',
+      type: 'folder',
+      defaultOpen: true,
+      children: [{ name: 'homepage.astro', highlight: true }],
+    },
+  ]}
+/>
+
+Custom homepages can also embed the new System Context Map using the `SystemContextMap` component.
+
+## Known issues
+
+Please check [EventCatalog issues on GitHub](https://github.com/event-catalog/eventcatalog/issues) for any reported issues, or to file an issue yourself.
diff --git a/packages/core/docs/editor/00-overview.md b/packages/core/docs/editor/00-overview.md
new file mode 100644
index 000000000..fe9bd1454
--- /dev/null
+++ b/packages/core/docs/editor/00-overview.md
@@ -0,0 +1,73 @@
+---
+sidebar_position: 1
+sidebar_label: Overview
+title: EventCatalog Editor
+description: Understand what EventCatalog Editor is, who it is for, and how it fits into your catalog workflow.
+---
+
+EventCatalog Editor is a local visual editor for maintaining an EventCatalog.
+
+It runs on your machine, opens your catalog from disk, lets you edit architecture resources without working directly in Markdown or MDX, and gives you a Git-backed view of the changes before you commit them.
+
+![EventCatalog Editor open on a service resource](./images/editor.png)
+
+## Who the editor is for
+
+The editor is for people who maintain an EventCatalog:
+
+- Architects documenting [domains](/docs/development/guides/domains/introduction), [services](/docs/development/guides/resources/services/introduction), [messages](/docs/development/guides/resources/messages/what-are-messages), and [ownership](/docs/owners)
+- Developers keeping resource documentation, schemas, and specifications up to date
+- Analysts, product owners, or domain experts who can improve catalog content but do not want to edit MDX files directly
+
+You still own your catalog as files. The editor makes those files easier to browse, edit, preview, review, and commit.
+
+::::info Need an EventCatalog first?
+
+These docs assume you already have an EventCatalog project. If you are just getting started, create a catalog first with the [EventCatalog installation guide](/docs/development/getting-started/installation), then come back here.
+
+::::
+
+## What the editor does
+
+Use EventCatalog Editor to:
+
+- Open a local EventCatalog project
+- Browse [domains](/docs/development/guides/domains/introduction), [services](/docs/development/guides/resources/services/introduction), [messages](/docs/development/guides/resources/messages/what-are-messages), [channels](/docs/development/guides/resources/messages/message-channels/introduction), [entities](/docs/development/guides/resources/entities/introduction), [data stores](/docs/development/guides/resources/data/introduction), [flows](/docs/development/guides/resources/flows/introduction), [users](/docs/development/guides/owners/what-are-teams-and-users), and [teams](/docs/development/guides/owners/what-are-teams-and-users)
+- Edit documentation in a rich editor or source editor
+- Update common frontmatter fields through forms
+- Add schemas to [events](/docs/development/guides/resources/messages/message-types/events), [commands](/docs/development/guides/resources/messages/message-types/commands), and [queries](/docs/development/guides/resources/messages/message-types/queries)
+- Add OpenAPI, AsyncAPI, and GraphQL specifications to domains and services
+- Preview resources in a running EventCatalog site
+- Inspect local Git changes, view diffs, revert files, and commit work
+- Invite editors through [EventCatalog Cloud](https://eventcatalog.cloud) and assign editor seats
+
+## Local workflow
+
+The editor sits on top of the same files that EventCatalog already uses.
+
+```mermaid
+flowchart LR
+  A[Local EventCatalog files] --> B[EventCatalog Editor]
+  B --> C[Markdown, MDX, schema, and config changes]
+  C --> D[Git changes view]
+  D --> E[Commit locally]
+  E --> F[Your existing review and publishing workflow]
+```
+
+The editor does not replace Git, Markdown, MDX, or your deployment process. It gives catalog maintainers a safer interface for making changes before those changes go through the workflow your team already uses.
+
+## Beta status
+
+EventCatalog Editor is in beta. You can use it today, but some workflows and features may change before general availability.
+
+The editor is a seat-based paid product. Community includes 1 editor seat, Starter includes 3 editor seats, Scale includes 10 editor seats, and Enterprise includes unlimited editor seats. See the [pricing page](/pricing) for current plan details.
+
+If you want to help shape the editor, join the [EventCatalog Discord](https://eventcatalog.dev/discord) or [open an issue in the editor repository](https://github.com/event-catalog/eventcatalog-editor-code/issues).
+
+## Next steps
+
+- Follow the [first edit tutorial](/docs/editor/first-edit).
+- Learn how to [run the editor locally](/docs/editor/how-to/run-locally).
+- Learn how to [use the Flow Editor](/docs/editor/how-to/use-flow-editor).
+- Learn how to [invite editors](/docs/editor/how-to/invite-editors).
+- Understand [how the editor works](/docs/editor/explanation/how-it-works).
diff --git a/packages/core/docs/editor/01-first-edit.md b/packages/core/docs/editor/01-first-edit.md
new file mode 100644
index 000000000..107fff2a9
--- /dev/null
+++ b/packages/core/docs/editor/01-first-edit.md
@@ -0,0 +1,124 @@
+---
+sidebar_position: 2
+sidebar_label: First edit tutorial
+title: Make your first edit with EventCatalog Editor
+description: Learn the basic editor workflow by opening a local catalog, changing a resource, previewing it, and reviewing the Git change.
+slug: /editor/first-edit
+---
+
+This tutorial takes you through the first successful editor workflow:
+
+1. Run EventCatalog locally
+2. Run EventCatalog Editor
+3. Open a catalog resource
+4. Make a small documentation change
+5. Preview the resource
+6. Review the Git diff
+7. Publish the change
+
+The goal is not to document a whole architecture. The goal is to learn the editor loop.
+
+::::info Need a catalog?
+
+This tutorial assumes you already have an EventCatalog project on your machine. If you do not, follow the [EventCatalog installation guide](/docs/development/getting-started/installation) first.
+
+::::
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+- Node.js 22 or later
+- Git installed
+- An EventCatalog project containing `eventcatalog.config.js`
+- Access to EventCatalog Editor through [EventCatalog Cloud](https://eventcatalog.cloud)
+- A terminal open in or near your catalog project
+
+If a teammate needs access, an organization admin can [invite them as an editor](/docs/editor/how-to/invite-editors).
+
+Check Node and Git with:
+
+```bash
+node -v
+git --version
+```
+
+## Start your EventCatalog preview
+
+Open a terminal in your EventCatalog project and start EventCatalog:
+
+```bash
+npm run dev
+```
+
+By default, EventCatalog runs at [http://localhost:3000](http://localhost:3000).
+
+The editor can still run without a preview, but preview links are only available when EventCatalog is running locally.
+
+## Start the editor
+
+Open another terminal in the same catalog directory and run:
+
+```bash
+npx @eventcatalog/editor
+```
+
+The editor starts on [http://localhost:3900](http://localhost:3900) and opens your browser.
+
+If the editor asks you to sign in, sign in with [EventCatalog Cloud](https://eventcatalog.cloud) and return to the local editor.
+
+## Open a resource
+
+Choose a resource from the left navigation. A good first edit is a [service](/docs/development/guides/resources/services/introduction), [domain](/docs/development/guides/domains/introduction), [event](/docs/development/guides/resources/messages/message-types/events), [command](/docs/development/guides/resources/messages/message-types/commands), or [query](/docs/development/guides/resources/messages/message-types/queries) that already exists in your catalog.
+
+The editor shows:
+
+- The resource list on the left
+- The resource documentation in the center
+- Metadata and relationship fields around the editor
+
+![Service resource open in EventCatalog Editor](./images/editor.png)
+
+## Make a small change
+
+Change a short paragraph, summary, [owner](/docs/owners), badge, or other low-risk field.
+
+The editor writes changes back to your local catalog files. For example, editing a service updates the matching `index.mdx` file in your catalog.
+
+You can use the rich editor for normal writing, or switch to source mode when you need to work directly with Markdown, MDX, or frontmatter.
+
+## Preview the resource
+
+Use **Open Preview** to view the resource in your running EventCatalog site.
+
+![Open Preview button in EventCatalog Editor](./images/open-preview.png)
+
+Preview opens the page from your local EventCatalog development server. If preview is unavailable, check that EventCatalog is running and that the editor detected the correct preview port.
+
+## Review the change
+
+Open **Changes** from the editor navigation.
+
+The changes page groups local Git changes by EventCatalog resource. Open the changed file to inspect the diff.
+
+![Changes page showing a local Git diff](./images/change-diff.png)
+
+## Publish the change
+
+When the diff looks right, click **Publish** in the editor.
+
+In the beta editor, **Publish** commits your changes locally to Git. It does not deploy your catalog or open a pull request.
+
+After publishing, continue with your team's normal review and release workflow. For example, you might push a branch and open a pull request, or push directly if that is how your catalog is maintained.
+
+## What you learned
+
+You have completed the core editor loop:
+
+- Open a local catalog
+- Edit a resource
+- Preview the resource locally
+- Review the Git diff
+- Publish a local commit
+
+Next, learn how to [edit resources](/docs/editor/how-to/edit-resource), [add schemas and specifications](/docs/editor/how-to/add-schemas-and-specifications), or [review and publish changes](/docs/editor/how-to/review-and-commit-changes).
diff --git a/packages/core/docs/editor/_category_.json b/packages/core/docs/editor/_category_.json
new file mode 100644
index 000000000..b9f8435b5
--- /dev/null
+++ b/packages/core/docs/editor/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Editor",
+  "position": 2,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "editor",
+    "title": "EventCatalog Editor",
+    "description": "Edit, preview, review, and commit EventCatalog documentation from a local visual editor."
+  }
+}
diff --git a/packages/core/docs/editor/explanation/_category_.json b/packages/core/docs/editor/explanation/_category_.json
new file mode 100644
index 000000000..f5cd66d90
--- /dev/null
+++ b/packages/core/docs/editor/explanation/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Explanation",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Editor explanation",
+    "description": "Conceptual guides that explain how EventCatalog Editor fits with files, Markdown, MDX, Git, and beta access."
+  }
+}
diff --git a/packages/core/docs/editor/explanation/beta-status-feedback.md b/packages/core/docs/editor/explanation/beta-status-feedback.md
new file mode 100644
index 000000000..94c3c580b
--- /dev/null
+++ b/packages/core/docs/editor/explanation/beta-status-feedback.md
@@ -0,0 +1,48 @@
+---
+sidebar_position: 3
+sidebar_label: Beta and feedback
+title: Beta status and feedback
+description: Understand the beta status of EventCatalog Editor and how to give feedback.
+---
+
+EventCatalog Editor is in beta.
+
+You can start using it today, but expect some features, workflows, and interface details to change as the product moves toward general availability.
+
+## What beta means
+
+During beta:
+
+- Some workflows may be incomplete
+- Some resource fields may only be editable in source mode
+- Pull request creation and richer publishing flows may change
+- Documentation and screenshots may lag behind fast-moving features
+
+The editor is ready for real feedback, but not every planned workflow is finished.
+
+## Access and seats
+
+EventCatalog Editor is a seat-based paid product.
+
+Community includes 1 editor seat. Starter includes 3 editor seats. Scale includes 10 editor seats. Enterprise includes unlimited editor seats.
+
+Organization admins can [invite editors](/docs/editor/how-to/invite-editors) through [EventCatalog Cloud](https://eventcatalog.cloud). Admin and editor roles use editor seats; viewer roles are free.
+
+See the [pricing page](/pricing) for current plan details.
+
+## Give feedback
+
+The best feedback is specific:
+
+- What you were trying to document
+- What catalog resource you were editing
+- What worked
+- What was confusing
+- What blocked you
+- What you expected the editor to do
+
+Share feedback in the [EventCatalog Discord](https://eventcatalog.dev/discord) or [open an issue in the editor repository](https://github.com/event-catalog/eventcatalog-editor-code/issues).
+
+## What the beta looks like
+
+![EventCatalog Editor beta interface](../images/editor.png)
diff --git a/packages/core/docs/editor/explanation/how-it-works.md b/packages/core/docs/editor/explanation/how-it-works.md
new file mode 100644
index 000000000..53d0f89ec
--- /dev/null
+++ b/packages/core/docs/editor/explanation/how-it-works.md
@@ -0,0 +1,49 @@
+---
+sidebar_position: 1
+sidebar_label: How it works
+title: How EventCatalog Editor works
+description: Understand the local architecture and workflow behind EventCatalog Editor.
+---
+
+EventCatalog Editor is local-first.
+
+It starts a small local server, opens a browser UI, reads your EventCatalog project from disk, and writes changes back to the same files.
+
+```mermaid
+flowchart LR
+  A[Browser UI] <--> B[Local editor server]
+  B <--> C[EventCatalog project files]
+  B <--> D[Git repository]
+  B -. detects .-> E[Local EventCatalog preview]
+```
+
+## The editor runs on your machine
+
+The editor binds to your local machine and opens at [http://localhost:3900](http://localhost:3900) by default.
+
+Your catalog stays on disk. Editing a resource changes files in the catalog directory, such as `index.mdx`, schema files, specification files, or `eventcatalog.config.js`.
+
+## The browser talks to the local server
+
+The browser UI does not edit files directly. It talks to the local editor server, which:
+
+- Validates catalog paths
+- Reads resources
+- Writes resource files
+- Manages schema and specification files
+- Reads Git status and diffs
+- Detects local EventCatalog preview URLs
+
+## [EventCatalog Cloud](https://eventcatalog.cloud) controls access
+
+The beta editor uses [EventCatalog Cloud](https://eventcatalog.cloud) for sign-in and editor access.
+
+Organizations in [EventCatalog Cloud](https://eventcatalog.cloud) control which people can open the local editor. Admins and editors can start local editor sessions. Viewers can belong to an organization without using an editor seat, but they cannot open a local editor session.
+
+After sign-in, editing still happens locally. The editor does not become a hosted catalog editor; it remains a local tool pointed at your local catalog files.
+
+## Git remains the review boundary
+
+The editor shows local Git changes, diffs, revert actions, and commits.
+
+It does not replace your team's review and release process. After committing, push and publish the catalog the same way your team already does.
diff --git a/packages/core/docs/editor/explanation/markdown-mdx-git.md b/packages/core/docs/editor/explanation/markdown-mdx-git.md
new file mode 100644
index 000000000..a9528295c
--- /dev/null
+++ b/packages/core/docs/editor/explanation/markdown-mdx-git.md
@@ -0,0 +1,58 @@
+---
+sidebar_position: 2
+sidebar_label: Markdown, MDX, and Git
+title: Editor, Markdown, MDX, and Git
+description: Understand how the editor works with EventCatalog's file-based authoring model.
+---
+
+EventCatalog is file-based. The editor keeps that model.
+
+Instead of asking every contributor to edit Markdown, MDX, YAML frontmatter, schemas, and Git diffs by hand, the editor gives them a visual workflow on top of the same project files.
+
+## Markdown and MDX are still the source of truth
+
+Each EventCatalog resource is still represented by files in your catalog.
+
+For example, a [service](/docs/development/guides/resources/services/introduction) might live at:
+
+```txt
+domains/Orders/services/OrderService/index.mdx
+```
+
+When you edit that service in the editor, the editor updates the same file.
+
+## Visual editing is an authoring layer
+
+The editor helps with common tasks:
+
+- Writing documentation
+- Changing summaries and owners
+- Adding badges
+- Modeling relationships
+- Adding schemas and specifications
+- Managing draft status
+
+For advanced content, source mode lets you edit the underlying Markdown, MDX, and frontmatter.
+
+## Git shows exactly what changed
+
+Because the editor writes to files, Git can show the exact change.
+
+That makes the editor useful for contributors who prefer a visual workflow while still giving reviewers the normal file diff.
+
+```mermaid
+flowchart LR
+  A[Visual edit] --> B[MDX and schema files]
+  B --> C[Git diff]
+  C --> D[Commit]
+  D --> E[Review and publish]
+```
+
+## Why this matters
+
+This keeps EventCatalog portable:
+
+- You can still edit files in an IDE
+- You can still review changes in pull requests
+- You can still build and deploy with your existing pipeline
+- You can let non-MDX contributors improve documentation safely
diff --git a/packages/core/docs/editor/how-to/_category_.json b/packages/core/docs/editor/how-to/_category_.json
new file mode 100644
index 000000000..b723ed849
--- /dev/null
+++ b/packages/core/docs/editor/how-to/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "How-to guides",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Editor how-to guides",
+    "description": "Task-focused guides for running EventCatalog Editor and working with catalog changes."
+  }
+}
diff --git a/packages/core/docs/editor/how-to/add-schemas-and-specifications.md b/packages/core/docs/editor/how-to/add-schemas-and-specifications.md
new file mode 100644
index 000000000..ecf740bbf
--- /dev/null
+++ b/packages/core/docs/editor/how-to/add-schemas-and-specifications.md
@@ -0,0 +1,66 @@
+---
+sidebar_position: 7
+sidebar_label: Add schemas and specifications
+title: Add schemas and specifications
+description: Attach message schemas and API specifications from EventCatalog Editor.
+---
+
+Use schemas and specifications to keep implementation contracts close to the architecture resources they describe.
+
+## Add a schema to a message
+
+Schemas are supported on:
+
+- [Events](/docs/development/guides/resources/messages/message-types/events)
+- [Commands](/docs/development/guides/resources/messages/message-types/commands)
+- [Queries](/docs/development/guides/resources/messages/message-types/queries)
+
+Open the message resource, then use the **Schema** section to add or edit the schema file.
+
+Supported schema formats include:
+
+- JSON Schema
+- Avro
+- Protobuf
+- Other text-based schema files
+
+When you save a schema, the editor writes the schema file into the resource folder and updates the resource metadata so EventCatalog can render it.
+
+If the schema editor does not expose the exact change you need yet, use source mode or edit the schema file directly.
+
+## Add a specification to a domain or service
+
+Specifications are supported on:
+
+- [Domains](/docs/development/guides/domains/introduction)
+- [Services](/docs/development/guides/resources/services/introduction)
+
+Open the domain or service, then use the specifications area to add:
+
+- OpenAPI
+- AsyncAPI
+- GraphQL
+
+The editor writes the specification file into the resource folder and updates the resource `specifications` metadata.
+
+![Service resource showing attached API specifications](../images/editor.png)
+
+## Preview schema and specification changes
+
+Start EventCatalog locally with:
+
+```bash
+npm run dev
+```
+
+Then use **Open Preview** in the editor to check how the schema or specification renders in the catalog.
+
+## When to use source mode
+
+Use source mode when you need to:
+
+- Adjust a custom `SchemaViewer` component
+- Add custom MDX around a schema
+- Edit specification metadata the visual form does not expose yet
+
+For more on schema documentation in EventCatalog, see the [schema documentation guides](/docs/development/guides/resources/schemas/what-are-schemas-and-specifications).
diff --git a/packages/core/docs/editor/how-to/edit-resource.md b/packages/core/docs/editor/how-to/edit-resource.md
new file mode 100644
index 000000000..5faa4bdb5
--- /dev/null
+++ b/packages/core/docs/editor/how-to/edit-resource.md
@@ -0,0 +1,88 @@
+---
+sidebar_position: 4
+sidebar_label: Edit a resource
+title: Edit an EventCatalog resource
+description: Update resource documentation, metadata, relationships, and source content in EventCatalog Editor.
+---
+
+Use this guide when you want to update a resource that already exists in your catalog.
+
+## Open the resource
+
+Start the editor and choose a resource from the resource list.
+
+The editor supports common EventCatalog resource types, including [domains](/docs/development/guides/domains/introduction), [services](/docs/development/guides/resources/services/introduction), [events](/docs/development/guides/resources/messages/message-types/events), [commands](/docs/development/guides/resources/messages/message-types/commands), [queries](/docs/development/guides/resources/messages/message-types/queries), [channels](/docs/development/guides/resources/messages/message-channels/introduction), [entities](/docs/development/guides/resources/entities/introduction), [data stores](/docs/development/guides/resources/data/introduction), [flows](/docs/development/guides/resources/flows/introduction), [users](/docs/development/guides/owners/what-are-teams-and-users), and [teams](/docs/development/guides/owners/what-are-teams-and-users).
+
+![Resource list with a service selected](../images/editor.png)
+
+## Edit the documentation
+
+Use the rich editor to change the resource body.
+
+The rich editor supports common writing blocks such as headings, paragraphs, lists, tables, blockquotes, code blocks, links, and dividers.
+
+Use `/` in an empty paragraph to open the block menu. Slash commands also help you insert EventCatalog components such as diagrams, callouts, steps, tiles, prompts, and resource-aware blocks. Learn more in [Use slash commands](/docs/editor/how-to/use-slash-commands).
+
+![Slash command menu showing EventCatalog components](../images/custom-slash-commands.png)
+
+## Edit resource metadata
+
+Use the resource fields to update common frontmatter values such as:
+
+- Name
+- Summary
+- Owners
+- Badges
+- Repository links
+- Draft status
+- Resource image or icon
+
+Some resource types have extra fields. For example, services can model sent and received messages, and data stores can describe type, technology, access mode, classification, retention, and residency.
+
+## Edit relationships
+
+Use relationship fields to connect resources.
+
+For example:
+
+- Add services to a domain
+- Show messages a service sends or receives
+- Connect services to data stores they read from or write to
+- Connect [owners](/docs/owners) to resources
+
+These fields update the same resource metadata that EventCatalog uses when it renders architecture relationships.
+
+## Create related resources
+
+When a relationship field allows new resources, the editor can create the resource and model how it relates to the current resource.
+
+For example, when creating an event from a service, choose whether the service publishes the event, consumes the event, or only contains the event in its folder.
+
+![Create event dialog showing relationship choices](../images/creating-new-event-modal.png)
+
+## Edit flows
+
+Flow resources include a visual Flow Editor for modeling business processes, user journeys, and architecture workflows.
+
+![Flow editor showing a service node in a business flow](../images/flow-editor.png)
+
+Learn how to [use the Flow Editor](/docs/editor/how-to/use-flow-editor).
+
+## Use source mode
+
+Switch to source mode when you need to edit Markdown, MDX, or frontmatter directly.
+
+![Editor source mode showing Markdown and frontmatter](../images/using-source-mode.png)
+
+Source mode is useful for:
+
+- Checking exact frontmatter
+- Editing custom MDX components
+- Making changes the rich editor does not expose yet
+- Copying content from another file
+
+## Save conflicts
+
+If the file changed on disk after the editor loaded it, the editor protects you from overwriting those changes.
+
+Reload the resource, review the external change, and apply your edit again.
diff --git a/packages/core/docs/editor/how-to/invite-editors.md b/packages/core/docs/editor/how-to/invite-editors.md
new file mode 100644
index 000000000..b778789c1
--- /dev/null
+++ b/packages/core/docs/editor/how-to/invite-editors.md
@@ -0,0 +1,68 @@
+---
+sidebar_position: 3
+sidebar_label: Invite editors
+title: Invite editors to your organization
+description: Add team members in EventCatalog Cloud and assign editor seats so they can use EventCatalog Editor locally.
+---
+
+Use [EventCatalog Cloud](https://eventcatalog.cloud) to manage who can use EventCatalog Editor.
+
+The editor still runs locally on each person's machine. Cloud verifies that the person belongs to your organization and has a role that can open a local editor session.
+
+![Invite team members in EventCatalog Cloud](../images/invite-team-members.png)
+
+## Before you start
+
+You need:
+
+- An [EventCatalog Cloud](https://eventcatalog.cloud) organization
+- Admin access to that organization
+- An available editor seat if you want to invite another admin or editor
+
+If you have not created an organization yet, sign in to [EventCatalog Cloud](https://eventcatalog.cloud) and complete the organization setup first.
+
+## Editor seats by plan
+
+Editor seats control how many people can use EventCatalog Editor for an organization.
+
+- Community includes 1 editor seat
+- Starter includes 3 editor seats
+- Scale includes 10 editor seats
+- Enterprise includes unlimited editor seats
+
+Admins and editors use editor seats. Viewers are free, but viewers cannot open a local editor session.
+
+You can compare plans on the [pricing page](/pricing).
+
+## Invite a team member
+
+1. Sign in to [EventCatalog Cloud](https://eventcatalog.cloud).
+2. Open the organization you want the editor to use.
+3. Go to **Team**.
+4. Enter the team member's email address.
+5. Choose their role.
+6. Click **Invite**.
+
+Invitations expire after 7 days.
+
+Pending invitations for admin and editor roles count toward your editor seat usage. If you run out of editor seats, invite the person as a viewer, cancel an unused pending invitation, change an existing member's role, or upgrade your plan.
+
+## Choose the right role
+
+- Admin can manage the organization, invite members, and use EventCatalog Editor.
+- Editor can use EventCatalog Editor for the organization.
+- Viewer can belong to the organization without using an editor seat.
+
+Use **Editor** for most people who need to maintain catalog content. Use **Admin** when the person also needs to manage organization settings and team access.
+
+## What the invited person does next
+
+After accepting the invitation, the team member can:
+
+1. Clone or open the EventCatalog project locally.
+2. Install catalog dependencies if needed.
+3. [Run EventCatalog Editor locally](/docs/editor/how-to/run-locally).
+4. Sign in with [EventCatalog Cloud](https://eventcatalog.cloud) when the editor asks for access.
+5. Choose the organization if their account belongs to more than one organization.
+
+The editor changes their local files and gives them a Git UI to publish a local commit. It does not upload catalog source files to [EventCatalog Cloud](https://eventcatalog.cloud).
diff --git a/packages/core/docs/editor/how-to/open-catalog.md b/packages/core/docs/editor/how-to/open-catalog.md
new file mode 100644
index 000000000..4c7b0ff9e
--- /dev/null
+++ b/packages/core/docs/editor/how-to/open-catalog.md
@@ -0,0 +1,44 @@
+---
+sidebar_position: 2
+sidebar_label: Open a catalog
+title: Open a catalog in the editor
+description: Mount an EventCatalog project from the CLI or from the editor UI.
+---
+
+EventCatalog Editor needs a local catalog directory before it can show resources.
+
+## How the editor finds a catalog
+
+When you run `npx @eventcatalog/editor`, the editor looks for a catalog in this order:
+
+1. The path passed with `--catalog`
+2. The current directory, if it contains `eventcatalog.config.js`
+3. The first child directory containing `eventcatalog.config.js`
+4. The catalog path screen in the browser
+
+## Open a catalog from the CLI
+
+Pass the catalog path:
+
+```bash
+npx @eventcatalog/editor --catalog /path/to/my-catalog
+```
+
+Use an absolute path when possible. It makes it clear which catalog the editor is changing.
+
+## Open a catalog from the browser
+
+If the editor cannot find a catalog automatically, it shows a catalog path screen.
+
+Enter the path to your EventCatalog project and choose **Open**.
+
+## Fix catalog loading errors
+
+If the editor cannot open the catalog, check that:
+
+- The path points to the catalog root
+- The directory contains `eventcatalog.config.js`
+- The config file can be imported by Node.js
+- Dependencies for the catalog are installed
+
+If you are not sure what the catalog root should look like, read the [EventCatalog project structure guide](/docs/development/getting-started/project-structure).
diff --git a/packages/core/docs/editor/how-to/preview-changes.md b/packages/core/docs/editor/how-to/preview-changes.md
new file mode 100644
index 000000000..2d49c0ccb
--- /dev/null
+++ b/packages/core/docs/editor/how-to/preview-changes.md
@@ -0,0 +1,55 @@
+---
+sidebar_position: 8
+sidebar_label: Preview changes
+title: Preview editor changes
+description: Open local EventCatalog preview links from the editor.
+---
+
+Preview lets you check how a resource looks in EventCatalog before committing your changes.
+
+## Start EventCatalog locally
+
+In your catalog project, run:
+
+```bash
+npm run dev
+```
+
+EventCatalog usually runs at [http://localhost:3000](http://localhost:3000).
+
+## Start the editor
+
+In another terminal, run:
+
+```bash
+npx @eventcatalog/editor
+```
+
+The editor checks whether EventCatalog is running locally. When it detects a preview, resource pages show **Open Preview**.
+
+## Use a custom preview port
+
+If EventCatalog is running on a different port, tell the editor:
+
+```bash
+npx @eventcatalog/editor --eventcatalog-port 3001
+```
+
+## Open a preview
+
+Open a resource in the editor and choose **Open Preview**.
+
+The editor opens the matching resource page in the local EventCatalog site.
+
+![Editor header with Open Preview action](../images/header.png)
+
+## Fix missing preview links
+
+If preview is unavailable:
+
+- Check that EventCatalog is running
+- Check the preview port
+- Restart the editor after starting EventCatalog
+- Open the local EventCatalog URL directly to confirm it works
+
+Preview is local. It does not publish your changes.
diff --git a/packages/core/docs/editor/how-to/revert-local-changes.md b/packages/core/docs/editor/how-to/revert-local-changes.md
new file mode 100644
index 000000000..181862428
--- /dev/null
+++ b/packages/core/docs/editor/how-to/revert-local-changes.md
@@ -0,0 +1,43 @@
+---
+sidebar_position: 10
+sidebar_label: Revert local changes
+title: Revert local editor changes
+description: Discard local catalog edits from the editor changes view.
+---
+
+Use revert when you want to discard local edits before committing them.
+
+## Open the Changes page
+
+Choose **Changes** from the editor navigation.
+
+The editor shows modified, added, deleted, renamed, and untracked files when Git change tracking is available.
+
+## Revert one file
+
+Open a changed file and choose **Revert**.
+
+The editor asks for confirmation before it discards the local file change.
+
+![Changes page with revert actions for local edits](../images/change-diff.png)
+
+## Revert a resource group
+
+If a resource has multiple changed files, you can revert the group from the Changes page.
+
+For example, reverting a message resource might discard changes to both:
+
+- `index.mdx`
+- `schema.json`
+
+## What revert does
+
+Revert restores modified and deleted files from Git.
+
+Untracked files are removed from disk.
+
+::::warning Revert cannot be undone by the editor
+
+Only revert files when you are sure you do not need the local edits. If you are unsure, inspect the diff first or commit the work to a temporary branch.
+
+::::
diff --git a/packages/core/docs/editor/how-to/review-and-commit-changes.md b/packages/core/docs/editor/how-to/review-and-commit-changes.md
new file mode 100644
index 000000000..078ffb6ad
--- /dev/null
+++ b/packages/core/docs/editor/how-to/review-and-commit-changes.md
@@ -0,0 +1,57 @@
+---
+sidebar_position: 9
+sidebar_label: Review and publish changes
+title: Review and publish editor changes
+description: Use the editor changes view to inspect local Git changes and publish a local commit.
+---
+
+EventCatalog Editor writes to your local catalog files. Use the **Changes** page to inspect what changed before you publish.
+
+## Open the Changes page
+
+Choose **Changes** from the editor navigation.
+
+If the catalog is a Git repository, the editor shows local changes grouped by EventCatalog resource.
+
+![Changes page with a grouped resource diff](../images/change-diff.png)
+
+## Inspect a file diff
+
+Open a changed file to view the unified diff.
+
+Use the diff to check:
+
+- The intended Markdown or MDX changed
+- Metadata changes are correct
+- Generated schema or specification paths look right
+- Unrelated files were not changed accidentally
+
+## Publish from the editor
+
+When the changes look right, click **Publish** in the editor.
+
+In the beta editor, **Publish** commits your changes locally to Git. It does not deploy your catalog or open a pull request.
+
+Use a short message that describes the catalog change, for example:
+
+```txt
+Document OrderPlaced event schema
+```
+
+## Continue with your team's workflow
+
+After publishing, use your existing Git workflow to share and release the change.
+
+For example:
+
+```bash
+git push
+```
+
+Then open a pull request if your team reviews catalog changes through GitHub or another Git hosting provider.
+
+::::info Pull request creation
+
+Built-in pull request creation is planned, but beta users should continue using their existing Git workflow after publishing local changes.
+
+::::
diff --git a/packages/core/docs/editor/how-to/run-locally.md b/packages/core/docs/editor/how-to/run-locally.md
new file mode 100644
index 000000000..dc4b6c875
--- /dev/null
+++ b/packages/core/docs/editor/how-to/run-locally.md
@@ -0,0 +1,71 @@
+---
+sidebar_position: 1
+sidebar_label: Run locally
+title: Run EventCatalog Editor locally
+description: Start EventCatalog Editor against a local EventCatalog project.
+---
+
+Use this guide when you want to start EventCatalog Editor on your machine.
+
+## Prerequisites
+
+You need:
+
+- Node.js 22 or later
+- Git
+- An EventCatalog project containing `eventcatalog.config.js`
+- EventCatalog Editor access through [EventCatalog Cloud](https://eventcatalog.cloud)
+
+## Run from a catalog directory
+
+Open a terminal in your EventCatalog project and run:
+
+```bash
+npx @eventcatalog/editor
+```
+
+The editor starts on [http://localhost:3900](http://localhost:3900).
+
+## Run with an explicit catalog path
+
+If you are not in the catalog directory, pass the catalog path:
+
+```bash
+npx @eventcatalog/editor --catalog /path/to/my-catalog
+```
+
+The directory must contain `eventcatalog.config.js`.
+
+## Choose a different editor port
+
+Use `--port` when port `3900` is already in use:
+
+```bash
+npx @eventcatalog/editor --port 3999
+```
+
+## Connect preview links to a running catalog
+
+The editor looks for a local EventCatalog preview on port `3000` by default.
+
+Start EventCatalog in your catalog project:
+
+```bash
+npm run dev
+```
+
+Then start the editor in another terminal:
+
+```bash
+npx @eventcatalog/editor
+```
+
+If your EventCatalog preview runs on another port, pass it to the editor:
+
+```bash
+npx @eventcatalog/editor --eventcatalog-port 3001
+```
+
+## Stop the editor
+
+Return to the terminal running the editor and press `Ctrl+C`.
diff --git a/packages/core/docs/editor/how-to/use-flow-editor.md b/packages/core/docs/editor/how-to/use-flow-editor.md
new file mode 100644
index 000000000..dc5856c8c
--- /dev/null
+++ b/packages/core/docs/editor/how-to/use-flow-editor.md
@@ -0,0 +1,66 @@
+---
+sidebar_position: 5
+sidebar_label: Flow Editor
+title: Use the Flow Editor
+description: Create and update EventCatalog flows visually with EventCatalog Editor.
+---
+
+Use the Flow Editor when you want to document a business process, user journey, or architecture workflow without editing the [flow](/docs/development/guides/resources/flows/introduction) files by hand.
+
+Flow resources are still stored in your local EventCatalog project. The editor gives you a visual way to create and arrange the steps, then writes the change back to your catalog files.
+
+![Flow editor showing a service node in a business flow](../images/flow-editor.png)
+
+## Open a flow
+
+Start EventCatalog Editor and open a flow from the resource list.
+
+If you are creating a new flow, create it from the editor first, then open it from the flow list.
+
+Click the **Flow Editor** tab at the top of the resource to switch from the documentation view into the visual editor.
+
+## Add a step
+
+Use **Add step** or choose an empty node in the flow.
+
+The editor opens a picker so you can choose what kind of node belongs in the flow.
+
+![Flow editor node type picker](../images/flow-editor-pick-a-node.png)
+
+## Choose the right node
+
+Use the node picker to add the resource that best represents the next step.
+
+For example:
+
+- Add a [service](/docs/development/guides/resources/services/introduction) when a system performs work
+- Add an [event](/docs/development/guides/resources/messages/message-types/events) when something has happened
+- Add a [command](/docs/development/guides/resources/messages/message-types/commands) when one system asks another system to do something
+- Add a [query](/docs/development/guides/resources/messages/message-types/queries) when the flow reads information
+
+Use existing catalog resources when they already exist. Create new resources when the flow reveals something that is missing from the catalog.
+
+## Review the flow
+
+After adding steps, read the flow from left to right and check that it tells the story clearly.
+
+Check that:
+
+- The flow starts with the trigger or first meaningful step
+- Each step uses the most accurate resource type
+- Resource names match the language your team uses
+- The flow is clear enough for someone who was not in the design discussion
+
+## Preview the flow
+
+Use **Open Preview** to view the flow in your local EventCatalog site.
+
+Preview helps you check how the flow will look to readers before you publish the local commit.
+
+## Publish the change
+
+Open **Changes** and review the files the Flow Editor changed.
+
+When the diff looks right, click **Publish**. In the beta editor, **Publish** commits your changes locally to Git.
+
+After publishing, continue with your team's normal Git review and release workflow.
diff --git a/packages/core/docs/editor/how-to/use-slash-commands.md b/packages/core/docs/editor/how-to/use-slash-commands.md
new file mode 100644
index 000000000..fb2139afd
--- /dev/null
+++ b/packages/core/docs/editor/how-to/use-slash-commands.md
@@ -0,0 +1,67 @@
+---
+sidebar_position: 6
+sidebar_label: Use slash commands
+title: Use slash commands
+description: Insert Markdown blocks and EventCatalog components from the rich editor.
+---
+
+Slash commands let you add content without remembering Markdown syntax or MDX component names.
+
+Type `/` in an empty paragraph to open the command menu. The menu shows matching blocks, grouped by purpose, with a visual preview of the selected command.
+
+![Slash command menu showing EventCatalog diagram components](../images/custom-slash-commands.png)
+
+## Insert a block
+
+1. Click into the resource documentation.
+2. Start a new empty paragraph.
+3. Type `/`.
+4. Search or scroll to the block you want.
+5. Press `Enter` or click the command.
+
+The editor inserts the matching Markdown or MDX block into the resource.
+
+## Add EventCatalog components
+
+Slash commands are useful for adding EventCatalog-specific components without switching to source mode.
+
+You can insert components such as:
+
+- Node Graph
+- Miro diagram
+- Draw.io diagram
+- Lucid diagram
+- IcePanel diagram
+- [Flow](/docs/development/guides/resources/flows/introduction)
+- Mermaid diagram
+- Entity Map
+- Schema Viewer
+- Steps
+- Tiles
+- Accordion group
+- Prompt
+- Visibility
+- Admonitions such as note, tip, warning, danger, and info
+
+Some commands are available only when they make sense for the current resource. For example, **Schema Viewer** is available for [events](/docs/development/guides/resources/messages/message-types/events), [commands](/docs/development/guides/resources/messages/message-types/commands), and [queries](/docs/development/guides/resources/messages/message-types/queries), while **Entity Map** is available for [domains](/docs/development/guides/domains/introduction).
+
+## Use visual previews
+
+The preview panel shows what the selected command is for before you insert it.
+
+Use this when you are deciding between similar blocks, such as diagram components or callout types.
+
+## Edit the inserted block
+
+After inserting a component, you can usually edit it directly in the rich editor.
+
+If the component needs configuration that is not exposed visually yet, switch to source mode and edit the MDX.
+
+## When to use source mode instead
+
+Use source mode when you need to:
+
+- Paste an existing MDX component
+- Change advanced component attributes
+- Edit custom components that the slash menu does not know about
+- Review the exact Markdown or MDX that will be saved
diff --git a/packages/core/docs/editor/reference/_category_.json b/packages/core/docs/editor/reference/_category_.json
new file mode 100644
index 000000000..9db74ba83
--- /dev/null
+++ b/packages/core/docs/editor/reference/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Reference",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Editor reference",
+    "description": "Lookup information for EventCatalog Editor commands, supported resources, content support, and troubleshooting."
+  }
+}
diff --git a/packages/core/docs/editor/reference/cli.md b/packages/core/docs/editor/reference/cli.md
new file mode 100644
index 000000000..441fe2448
--- /dev/null
+++ b/packages/core/docs/editor/reference/cli.md
@@ -0,0 +1,61 @@
+---
+sidebar_position: 1
+sidebar_label: CLI
+title: EventCatalog Editor CLI reference
+description: Command and option reference for running EventCatalog Editor.
+---
+
+Run the editor with:
+
+```bash
+npx @eventcatalog/editor
+```
+
+## Requirements
+
+- Node.js 22 or later
+- Git
+- An EventCatalog directory containing `eventcatalog.config.js`
+
+## Options
+
+| Option | Description | Default |
+| --- | --- | --- |
+| `--catalog <path>` | Path to the EventCatalog root to edit. | Current directory, a detected child catalog, or browser selection |
+| `--port <n>` | Port for the editor server. | `3900` |
+| `--eventcatalog-port <n>` | Port where local EventCatalog preview is running. | `3000` |
+| `--no-open` | Start the editor without opening the browser automatically. | Opens browser |
+| `--help`, `-h` | Show CLI help. |  |
+| `--version`, `-v` | Show the installed editor version. |  |
+
+## Examples
+
+Run from a catalog directory:
+
+```bash
+npx @eventcatalog/editor
+```
+
+Run against a specific catalog:
+
+```bash
+npx @eventcatalog/editor --catalog /Users/me/dev/my-catalog
+```
+
+Use a different editor port:
+
+```bash
+npx @eventcatalog/editor --port 3999
+```
+
+Use a different EventCatalog preview port:
+
+```bash
+npx @eventcatalog/editor --eventcatalog-port 3001
+```
+
+Start without opening a browser:
+
+```bash
+npx @eventcatalog/editor --no-open
+```
diff --git a/packages/core/docs/editor/reference/supported-content.md b/packages/core/docs/editor/reference/supported-content.md
new file mode 100644
index 000000000..570fd09ae
--- /dev/null
+++ b/packages/core/docs/editor/reference/supported-content.md
@@ -0,0 +1,81 @@
+---
+sidebar_position: 3
+sidebar_label: Supported content
+title: Supported content and MDX
+description: Markdown, MDX, and component support in EventCatalog Editor.
+---
+
+EventCatalog Editor supports rich editing for common Markdown content and source editing for advanced Markdown and MDX.
+
+## Rich editor content
+
+The rich editor supports:
+
+- Headings
+- Paragraphs
+- Bold and italic text
+- Links
+- Bullet lists
+- Numbered lists
+- Blockquotes
+- Code blocks
+- Horizontal dividers
+- Tables
+
+Use `/` in an empty paragraph to open the slash command menu.
+
+![Slash command menu showing component previews](../images/custom-slash-commands.png)
+
+## Slash commands
+
+Slash commands can insert Markdown blocks and EventCatalog components from the rich editor.
+
+Common command groups include:
+
+- Text: headings, paragraphs, and quotes
+- Lists: bullet and ordered lists
+- Advanced: code blocks, dividers, and tables
+- Admonitions: note, tip, warning, danger, and info callouts
+- Diagrams: Node Graph, [Flow](/docs/development/guides/resources/flows/introduction), Mermaid, Miro, Draw.io, Lucid, IcePanel, Entity Map, and Schema Viewer
+- Layout: Steps, Tiles, and Accordion group
+- AI: Prompt and Visibility blocks
+
+Some commands are resource-aware. For example, Schema Viewer appears for [events](/docs/development/guides/resources/messages/message-types/events), [commands](/docs/development/guides/resources/messages/message-types/commands), and [queries](/docs/development/guides/resources/messages/message-types/queries), and Entity Map appears for [domains](/docs/development/guides/domains/introduction).
+
+## Source mode
+
+Use source mode for:
+
+- Frontmatter edits
+- Custom Markdown
+- MDX components
+- Content the rich editor does not expose yet
+
+Source mode edits the full document source.
+
+## MDX components
+
+The editor understands common EventCatalog MDX components and keeps unknown or complex components as blocks so they can round trip through the editor.
+
+Examples of EventCatalog content you may see include:
+
+- `NodeGraph`
+- `EntityMap`
+- `Mermaid`
+- `Steps`
+- `Schema`
+- `SchemaViewer`
+- `MessageTable`
+- `ChannelInformation`
+- `OpenAPI`
+- `AsyncAPI`
+- `Admonition`
+- `ResourceGroupList`
+
+If a component cannot be edited visually yet, use source mode.
+
+## Editor modes
+
+Use the header controls to switch between visual editing and source editing.
+
+![Editor header showing visual and source mode controls](../images/header.png)
diff --git a/packages/core/docs/editor/reference/supported-resources.md b/packages/core/docs/editor/reference/supported-resources.md
new file mode 100644
index 000000000..19d3aff6d
--- /dev/null
+++ b/packages/core/docs/editor/reference/supported-resources.md
@@ -0,0 +1,51 @@
+---
+sidebar_position: 2
+sidebar_label: Supported resources
+title: Supported resources
+description: Resource types and capabilities currently supported by EventCatalog Editor.
+---
+
+EventCatalog Editor can browse and edit the main EventCatalog resource types.
+
+| Resource type | Browse | Edit docs | Edit metadata | Create | Delete | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| [Domain](/docs/development/guides/domains/introduction) | Yes | Yes | Yes | Yes | Yes | Supports services, messages, entities, specifications, and ubiquitous language |
+| [Service](/docs/development/guides/resources/services/introduction) | Yes | Yes | Yes | Yes | Yes | Supports message relationships, data store relationships, and specifications |
+| [Event](/docs/development/guides/resources/messages/message-types/events) | Yes | Yes | Yes | Yes | Yes | Supports schemas and producer/consumer relationships |
+| [Command](/docs/development/guides/resources/messages/message-types/commands) | Yes | Yes | Yes | Yes | Yes | Supports schemas, operations, and producer/consumer relationships |
+| [Query](/docs/development/guides/resources/messages/message-types/queries) | Yes | Yes | Yes | Yes | Yes | Supports schemas, operations, and producer/consumer relationships |
+| [Channel](/docs/development/guides/resources/messages/message-channels/introduction) | Yes | Yes | Yes | Yes | Yes | Supports common metadata |
+| [Entity](/docs/development/guides/resources/entities/introduction) | Yes | Yes | Yes | Yes | Yes | Supports common metadata |
+| [Data store](/docs/development/guides/resources/data/introduction) | Yes | Yes | Yes | Yes | Yes | Represented as EventCatalog container resources |
+| [Flow](/docs/development/guides/resources/flows/introduction) | Yes | Yes | Yes | Yes | Yes | Supports flow step editing |
+| [User](/docs/development/guides/owners/what-are-teams-and-users) | Yes | Yes | Yes | Yes | Yes | Versionless |
+| [Team](/docs/development/guides/owners/what-are-teams-and-users) | Yes | Yes | Yes | Yes | Yes | Versionless |
+
+## Schemas
+
+Schemas are supported on:
+
+- [Events](/docs/development/guides/resources/messages/message-types/events)
+- [Commands](/docs/development/guides/resources/messages/message-types/commands)
+- [Queries](/docs/development/guides/resources/messages/message-types/queries)
+
+## Specifications
+
+Specifications are supported on:
+
+- [Domains](/docs/development/guides/domains/introduction)
+- [Services](/docs/development/guides/resources/services/introduction)
+
+Supported specification types:
+
+- OpenAPI
+- AsyncAPI
+- GraphQL
+
+## Versionless resources
+
+Users and teams are versionless in EventCatalog. Other resources use versions.
+
+## Beta limitations
+
+Some advanced resource fields may still require source mode. If a visual field is missing, switch to source mode and edit the underlying Markdown, MDX, or frontmatter directly.
diff --git a/packages/core/docs/editor/reference/troubleshooting.md b/packages/core/docs/editor/reference/troubleshooting.md
new file mode 100644
index 000000000..687eeb310
--- /dev/null
+++ b/packages/core/docs/editor/reference/troubleshooting.md
@@ -0,0 +1,76 @@
+---
+sidebar_position: 4
+sidebar_label: Troubleshooting
+title: Troubleshooting EventCatalog Editor
+description: Fix common issues when running EventCatalog Editor.
+---
+
+## The editor cannot find my catalog
+
+Check that:
+
+- You are running the editor from the catalog directory, or using `--catalog`
+- The directory contains `eventcatalog.config.js`
+- The config file can be loaded by Node.js
+- Catalog dependencies are installed
+
+Run with an explicit path:
+
+```bash
+npx @eventcatalog/editor --catalog /path/to/my-catalog
+```
+
+## I cannot sign in
+
+The editor uses [EventCatalog Cloud](https://eventcatalog.cloud) for access.
+
+If sign-in fails:
+
+- Check your internet connection
+- Try signing out of [EventCatalog Cloud](https://eventcatalog.cloud) and signing in again
+- Restart the local editor
+- Check that your account has editor access
+
+If you see an editor access message, ask an organization admin to [invite you as an editor](/docs/editor/how-to/invite-editors) or change your role to **Editor** or **Admin**. Viewer accounts can sign in to [EventCatalog Cloud](https://eventcatalog.cloud), but they cannot open a local editor session.
+
+## Preview is unavailable
+
+Preview links require a local EventCatalog development server.
+
+Start EventCatalog:
+
+```bash
+npm run dev
+```
+
+Then restart the editor. If your catalog runs on a different port, pass it with `--eventcatalog-port`.
+
+## Changes are not shown
+
+The Changes page uses Git. Check that:
+
+- Your catalog is inside a Git repository
+- Git is installed
+- The files have actually changed on disk
+
+You can also check from a terminal:
+
+```bash
+git status
+```
+
+## A save reports a conflict
+
+A conflict means the file changed on disk after the editor loaded it.
+
+Reload the resource, review the external change, and apply your edit again.
+
+## A visual field is missing
+
+The beta editor does not expose every possible EventCatalog field as a form yet.
+
+Use source mode to edit unsupported frontmatter or MDX directly.
+
+## Get help
+
+Join the [EventCatalog Discord](https://eventcatalog.dev/discord) or [open an issue in the editor repository](https://github.com/event-catalog/eventcatalog-editor-code/issues).
diff --git a/packages/core/docs/miro/_category_.json b/packages/core/docs/miro/_category_.json
new file mode 100644
index 000000000..973a5d55f
--- /dev/null
+++ b/packages/core/docs/miro/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Miro",
+  "position": 4,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "miro",
+    "title": "EventCatalog Miro App",
+    "description": "Visualize your EventCatalog resources on Miro boards"
+  }
+}
diff --git a/packages/core/docs/miro/contributing/01-getting-involved.md b/packages/core/docs/miro/contributing/01-getting-involved.md
new file mode 100644
index 000000000..b1b9add70
--- /dev/null
+++ b/packages/core/docs/miro/contributing/01-getting-involved.md
@@ -0,0 +1,53 @@
+---
+sidebar_position: 1
+sidebar_label: Getting Involved
+title: "Getting Involved"
+description: How to contribute to the EventCatalog Miro App
+slug: /miro/getting-involved
+---
+
+The EventCatalog Miro App is open source and we welcome contributions of all kinds — from bug reports and feature requests to code contributions and documentation improvements.
+
+### Ways to contribute
+
+#### Report bugs and request features
+
+Found a bug or have an idea for a new feature? [Open a GitHub issue](https://github.com/event-catalog/eventcatalog-miro-app/issues) and let us know. Please include as much detail as possible — screenshots, steps to reproduce, and what you expected to happen.
+
+#### Join the community
+
+Our [Discord community](https://eventcatalog.dev/discord) is the best place to ask questions, share feedback, and connect with other users building with EventCatalog. We're active there and happy to help.
+
+#### Contribute code
+
+The app is built with React, TypeScript, and the Miro Web SDK. To get started:
+
+1. Fork the repository: [github.com/event-catalog/eventcatalog-miro-app](https://github.com/event-catalog/eventcatalog-miro-app)
+2. Clone your fork and install dependencies:
+   ```bash
+   git clone https://github.com/<your-username>/eventcatalog-miro-app.git
+   cd eventcatalog-miro-app
+   npm install
+   ```
+3. Start the development server:
+   ```bash
+   npm run dev
+   ```
+4. Make your changes and open a pull request
+
+#### Improve the documentation
+
+If you spot something missing or unclear in these docs, contributions are welcome. The documentation lives alongside the main EventCatalog website.
+
+### What we're looking for
+
+The app is in beta and there are plenty of areas where help is appreciated:
+
+- **Bug fixes** — if you find something broken, a fix is always welcome
+- **New features** — check the [issues page](https://github.com/event-catalog/eventcatalog-miro-app/issues) for feature requests or propose your own
+- **Testing** — try the app with your own catalog and let us know how it goes
+- **Feedback** — share what works well and what could be improved
+
+### Code of conduct
+
+Please be kind and respectful in all interactions. We're building this together and every contribution matters.
diff --git a/packages/core/docs/miro/contributing/_category_.json b/packages/core/docs/miro/contributing/_category_.json
new file mode 100644
index 000000000..8379b2e19
--- /dev/null
+++ b/packages/core/docs/miro/contributing/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Contributing",
+  "position": 5,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Contributing to the Miro App",
+    "description": "Help improve the EventCatalog Miro App"
+  }
+}
diff --git a/packages/core/docs/miro/getting-started/01-overview.md b/packages/core/docs/miro/getting-started/01-overview.md
new file mode 100644
index 000000000..e4143b9c0
--- /dev/null
+++ b/packages/core/docs/miro/getting-started/01-overview.md
@@ -0,0 +1,63 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Miro
+- Miro integration
+- architecture visualization
+sidebar_label: Overview
+title: "EventCatalog Miro App"
+description: Bring your EventCatalog architecture into Miro for collaborative visual design
+slug: /miro/overview
+---
+
+The EventCatalog Miro App lets you bring your architecture artifacts you already documented into Miro — drag services, events, commands, and more onto a board to collaboratively design and explore your systems.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/getting-started/example.png" alt="Panel" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0.5rem"}}>EventCatalog Miro Application</span>
+</div>
+
+:::info Beta — we'd love your feedback
+The EventCatalog Miro App is currently in beta. We're actively building new features and improving the experience based on real-world usage.
+
+If you run into any issues, have ideas for new features, or want to share how you're using the app, we'd love to hear from you:
+
+- [Join our Discord community](https://eventcatalog.dev/discord) to chat with us and other users
+- [Raise a GitHub issue](https://github.com/event-catalog/eventcatalog-miro-app/issues) to report bugs or request features
+- [Contribute to the project](https://github.com/event-catalog/eventcatalog-miro-app) — the app is open source and contributions are welcome
+:::
+
+### Why use the Miro App?
+
+EventCatalog helps you document your architecture. Many teams already use Miro to help visualize and model new ideas.
+
+The EventCatalog Miro application helps you model and plan what comes next using tools you already use. Model new services, new events, new connections — you need a space to think visually with your team.
+
+The Miro App bridges that gap:
+
+- **Import your real architecture** — bring services, events, commands, queries, channels, and data stores from EventCatalog into Miro
+- **Design collaboratively** — drag resources onto the board, draw connections, and model your next iteration as a team
+- **Create new resources** — sketch out new services and events directly in the app before they exist in code
+- **Stay grounded in reality** — your board is built from real architecture artifacts, not generic boxes and lines
+
+### How it works
+
+1. **Export** your catalog from your EventCatalog project
+2. **Import** the JSON into the Miro App
+3. **Drag** resources onto the board to visualize your architecture
+4. **Design** what comes next — add new resources, draw connections, and collaborate with your team
+
+### Supported resources
+
+| Resource | Description |
+|----------|-------------|
+| **Services** | Microservices and systems in your architecture |
+| **Events** | Domain events flowing between services |
+| **Commands** | Command messages handled by services |
+| **Queries** | Query messages for reading data |
+| **Channels** | Message brokers and routing channels |
+| **Data Stores** | Databases and storage systems |
+
+### Getting in touch
+
+If you have any questions, feedback, or want to get in touch, please join our [Discord community](https://eventcatalog.dev/discord) or [raise a GitHub issue](https://github.com/event-catalog/eventcatalog-miro-app/issues).
diff --git a/packages/core/docs/miro/getting-started/02-installation.md b/packages/core/docs/miro/getting-started/02-installation.md
new file mode 100644
index 000000000..545636e64
--- /dev/null
+++ b/packages/core/docs/miro/getting-started/02-installation.md
@@ -0,0 +1,37 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog Miro
+- Miro app install
+sidebar_label: Installation
+title: "Installing the Miro App"
+description: How to install the EventCatalog Miro app to your Miro board
+slug: /miro/installation
+---
+
+### Install the app
+
+1. Open the [EventCatalog Miro App install link](https://miro.com/app-install/?response_type=code&client_id=3458764623600229458&redirect_uri=%2Fapp-install%2Fconfirm%2F)
+2. Select the team and board where you want to install the app
+3. Click **Tools, Media and Integrations**
+4. Search for **EventCatalog** and click on the app.
+
+### Opening the app
+
+Click the **EventCatalog icon** in the toolbar to open the app panel. The panel opens on the right side of your board.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/getting-started/panel.png" alt="Panel" style={{width: "50%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0.5rem"}}>The EventCatalog icon in the Miro toolbar</span>
+</div>
+
+:::tip Auto-open on selection
+When you select a node on the board, the app panel will automatically open and show that resource's details — even if the panel was closed.
+:::
+
+### Requirements
+
+- A Miro account (free or paid)
+- An EventCatalog project with resources to import
+
+No authentication or API keys are required. The app runs entirely in your browser and stores data locally.
diff --git a/packages/core/docs/miro/getting-started/03-connecting-to-eventcatalog.md b/packages/core/docs/miro/getting-started/03-connecting-to-eventcatalog.md
new file mode 100644
index 000000000..cb7f68889
--- /dev/null
+++ b/packages/core/docs/miro/getting-started/03-connecting-to-eventcatalog.md
@@ -0,0 +1,59 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog Miro
+- import catalog
+- connect EventCatalog
+sidebar_label: Connecting to EventCatalog
+title: "Connecting to EventCatalog"
+description: Export and import your EventCatalog resources into the Miro app
+slug: /miro/connecting-to-eventcatalog
+---
+
+To use the Miro App, you first need to export your EventCatalog data and import it into the app.
+
+### Step 1: Export your catalog
+
+In your EventCatalog project, run the export command:
+
+```bash
+npm run export
+```
+
+This generates a JSON file containing all your resources — services, events, commands, queries, channels, and data stores — along with their relationships, owners, and metadata.
+
+### Step 2: Import into the Miro App
+
+Open the EventCatalog app in Miro and click **Import Resources**. You have two options:
+
+#### Option A: Upload a file
+
+Click the upload area and select the exported JSON file from your file system.
+
+#### Option B: Paste JSON
+
+Copy the contents of the exported JSON file and paste it into the text area, then click **Import**.
+
+The app validates the JSON before importing. If the format is invalid, you'll see an error message — check that you're using the output from `npm run export`.
+
+### What gets imported?
+
+All resources from your catalog are imported and organized by type:
+
+- **Services** — with their sends, receives, writesTo, and readsFrom relationships
+- **Events, Commands, Queries** — message types with producer/consumer information
+- **Channels** — message brokers with routing configuration
+- **Data Stores** — databases with read/write relationships
+- **Owners and Teams** — used to display ownership on resources
+
+### Re-importing
+
+You can import a new catalog at any time by clicking **Import Resources** from the dashboard. This replaces your current data with the new import.
+
+:::info Data is stored locally
+All imported data is stored in your browser's local storage. No data is sent to any server. If you clear your browser data, you'll need to re-import your catalog.
+:::
+
+### Next steps
+
+Once your data is imported, you're ready to start adding resources to the board. Head to the [guides](/docs/miro/adding-resources) to learn how.
diff --git a/packages/core/docs/miro/getting-started/_category_.json b/packages/core/docs/miro/getting-started/_category_.json
new file mode 100644
index 000000000..ab86d46af
--- /dev/null
+++ b/packages/core/docs/miro/getting-started/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Getting Started",
+  "position": 1,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Getting Started with the Miro App",
+    "description": "Install and connect EventCatalog to Miro"
+  }
+}
diff --git a/packages/core/docs/miro/guides/01-adding-resources-to-board.md b/packages/core/docs/miro/guides/01-adding-resources-to-board.md
new file mode 100644
index 000000000..b396c1565
--- /dev/null
+++ b/packages/core/docs/miro/guides/01-adding-resources-to-board.md
@@ -0,0 +1,90 @@
+---
+sidebar_position: 1
+sidebar_label: Adding resources to the board
+title: "Adding Resources to the Board"
+description: Drag and drop services, events, commands, and more onto your Miro board
+slug: /miro/adding-resources
+---
+
+Once you've [imported your catalog](/docs/miro/connecting-to-eventcatalog), you can start adding resources to your Miro board.
+
+### The dashboard
+
+After importing, you'll see the dashboard — a grid showing all your resource categories with the number of resources in each:
+
+- **Services** — microservices and systems
+- **Events** — domain events
+- **Commands** — command messages
+- **Queries** — query messages
+- **Channels** — message brokers and routing
+- **Data Stores** — databases and storage
+
+Click any category to drill into its resource list.
+
+### Dragging resources onto the board
+
+There are two ways to add resources to the board:
+
+#### From the category list
+
+1. Click a category (e.g. **Services**) to see all resources in that category
+2. Grab a resource by its drag handle and drag it onto the Miro board
+3. The resource appears on the board as a card with its name, version, and metadata
+
+Each resource in the list shows its name, version, summary, and owners. You can search to filter resources down.
+
+#### From the dashboard
+
+You can also drag a category card directly from the dashboard onto the board. This creates a new blank resource of that type on the board — useful for quickly sketching out resources that don't exist yet.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/list-of-services.png" alt="Panel" style={{width: "15%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0.5rem"}}>Imported Services for Miro</span>
+</div>
+
+
+### Display modes
+
+The app supports two display modes for how resources appear on the board. You can switch between them from the **Display Mode** toggle on the dashboard:
+
+#### App Card
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/app-card.png" alt="Panel" style={{width: "50%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Style - App Card</span>
+</div>
+
+
+The default mode. Resources appear as Miro App Cards with:
+- Resource name as the title
+- Summary as the description
+- Version, category, owners, and badges as fields
+- Color-coded by resource type
+- Status indicator (Active, Draft, or Deprecated)
+
+#### Post-it
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/post-it.png" alt="Panel" style={{width: "50%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Style - Post-it</span>
+</div>
+
+Resources appear as colored Miro sticky notes with the resource name. This is a simpler, more compact view — useful when you want a high-level overview without the detail.
+
+:::tip Switching display modes
+When you switch display modes, all existing resources on the board are automatically converted to the new format. Connections between resources are preserved.
+:::
+
+### Auto-layout
+
+If your board gets messy, click the **Auto-layout** button in the dashboard header. This automatically arranges all resources on the board using a left-to-right directed graph layout, organizing connected resources into a clean flow.
+
+### Finding resources on the board
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/focus.png" alt="Panel" style={{width: "50%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Style - Post-it</span>
+</div>
+
+
+When browsing the resource list, hover over any resource to reveal a crosshair icon. Click it to zoom to that resource on the board — helpful when you have a large board and need to find a specific resource.
diff --git a/packages/core/docs/miro/guides/02-creating-new-resources.md b/packages/core/docs/miro/guides/02-creating-new-resources.md
new file mode 100644
index 000000000..35cba0764
--- /dev/null
+++ b/packages/core/docs/miro/guides/02-creating-new-resources.md
@@ -0,0 +1,61 @@
+---
+sidebar_position: 2
+sidebar_label: Creating new resources
+title: "Creating New Resources"
+description: Create new services, events, and other resources directly from the Miro app
+slug: /miro/creating-resources
+---
+
+You can create new resources directly in the Miro app — useful for designing services, events, and other resources that don't exist in your catalog yet.
+
+### Creating from the resource list
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/new-resource.png" alt="New Service" style={{width: "50%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Creating a new resource</span>
+</div>
+
+1. Click a category (e.g. **Services**) to open the resource list
+2. Click the **+ New** button in the header
+3. A new resource is created with a default name (e.g. "New Service") and version `1.0.0`
+4. The resource is added to both the sidebar list and the Miro board
+
+The new resource appears at the top of the list with a slide-in animation so you can spot it easily.
+
+### Creating from the dashboard
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/dragging-resources.gif" alt="Dragging a service with dependencies" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Dragging a service with its dependencies onto the board</span>
+</div>
+
+
+You can also drag a category card from the dashboard directly onto the board. This creates a new blank resource of that type at the drop position — a quick way to sketch out new resources without opening the category list first.
+
+### Editing new resources
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/edit-resource.gif" alt="Dragging a service with dependencies" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Dragging a service with its dependencies onto the board</span>
+</div>
+
+Once created, click the resource on the board to open its detail view. From there you can edit:
+
+- **Name** — click the pencil icon next to the name to rename it
+- **Version** — click the pencil icon next to the version to change it
+- **Summary** — click the pencil icon next to the summary to add a description
+
+Changes sync to both the sidebar and the board item automatically. Press **Enter** to save or **Escape** to cancel.
+
+### Deleting resources
+
+To remove a resource, you have two options:
+
+- **From the resource list** — hover over a resource and click the trash icon on the right
+- **From the detail view** — select a node on the board, then click the trash icon in the top-right of the detail panel
+
+Deleting from the detail view removes the resource from both the catalog and the Miro board.
+
+### Draft resources
+
+New resources created in the app are marked as drafts. This distinguishes them from resources that were imported from your EventCatalog project, making it easy to see what's new versus what already exists in your architecture.
diff --git a/packages/core/docs/miro/guides/03-editing-resources.md b/packages/core/docs/miro/guides/03-editing-resources.md
new file mode 100644
index 000000000..d7f009539
--- /dev/null
+++ b/packages/core/docs/miro/guides/03-editing-resources.md
@@ -0,0 +1,50 @@
+---
+sidebar_position: 3
+sidebar_label: Editing resources
+title: "Editing Resources"
+description: Edit resource details by selecting nodes on the board
+slug: /miro/editing-resources
+---
+
+Select any node on the Miro board to view and edit its details in the app panel.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/edit-resource.gif" alt="Editing a resource" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Editing a resource from the detail panel</span>
+</div>
+
+### Viewing resource details
+
+Click any resource node on the board to open its detail view in the panel. You'll see:
+
+- **Category** — the resource type (Service, Event, Command, etc.)
+- **Name** — the resource name
+- **Version** — the current version
+- **Summary** — a short description
+- **Badges** — tags and labels on the resource
+- **Connected resources** — incoming and outgoing connections grouped by type
+
+For services, connections are organized into:
+- **Incoming Messages** — events, commands, and queries the service receives
+- **Outgoing Messages** — events, commands, and queries the service sends
+- **Data Stores** — databases the service reads from or writes to
+
+For messages, connections show **Producers** and **Consumers**.
+
+### Editing fields
+
+Click the pencil icon next to any editable field to modify it:
+
+- **Name** — updates the resource name on both the board and in the catalog
+- **Version** — updates the version number
+- **Summary** — updates the description
+
+Press **Enter** to save your changes or **Escape** to cancel. Changes are synced to the Miro board item automatically.
+
+### Adding and removing badges
+
+You can add badges to any resource by typing in the badge input field and pressing **Enter**. Click the **x** on a badge to remove it. Badges are useful for tagging resources with metadata like team ownership, status, or technology.
+
+### Deleting resources
+
+Click the trash icon in the top-right of the detail panel to delete the resource. This removes it from both the catalog and the Miro board. You can also select a node on the board and press **Backspace** or **Delete** to remove it.
diff --git a/packages/core/docs/miro/guides/04-connected-resources.md b/packages/core/docs/miro/guides/04-connected-resources.md
new file mode 100644
index 000000000..b34646c2d
--- /dev/null
+++ b/packages/core/docs/miro/guides/04-connected-resources.md
@@ -0,0 +1,54 @@
+---
+sidebar_position: 4
+sidebar_label: Connected resources
+title: "Connected Resources"
+description: View and navigate connections between resources on the board
+slug: /miro/connected-resources
+---
+
+When you draw a connector between two resources on the Miro board, the app automatically labels it and styles it based on the resource types — no manual labeling needed.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/connectors.gif" alt="Editing a resource" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Editing a resource from the detail panel</span>
+</div>
+
+### Drawing connections
+
+Use Miro's built-in connector tool to draw a line from one resource to another. The app detects the resource types and automatically sets:
+
+- **Label** — describes the relationship (e.g. "publishes event", "receives", "writes to")
+- **Color** — matches the connection type
+- **Shape** — elbowed connectors with directional arrows
+
+### Automatic labels
+
+The label applied depends on the direction and types of the connected resources:
+
+| From | To | Label |
+|------|----|-------|
+| Service | Event / Command / Query | "publishes event", "invokes command", "requests" |
+| Event / Command / Query | Service | "receives event", "accepts", "accepts" |
+| Service | Channel | "publishes to" |
+| Channel | Service | "subscribes from" |
+| Event / Command / Query | Channel | "routed through" |
+| Channel | Event / Command / Query | "delivers" |
+| Service | Data Store | "writes to" |
+| Data Store | Service | "reads from" |
+| Service | Service | "connects to" |
+
+### Viewing connections
+
+Select a resource on the board to see all its connections in the detail panel. Connections are grouped by direction:
+
+- **Services** show Incoming Messages, Outgoing Messages, and Data Stores
+- **Events, Commands, Queries** show Producers and Consumers
+- **Channels** show incoming and outgoing routes
+
+### Connection highlighting
+
+When you select a resource, all of its connections are highlighted in purple on the board. This makes it easy to trace the flow of a message or see which resources depend on the selected one.
+
+### Navigating connections
+
+Click any connected resource in the detail panel to zoom to it on the board and open its details. This lets you follow the message flow through your architecture — from producer to event to consumer — without manually searching the board.
diff --git a/packages/core/docs/miro/guides/05-services-and-dependencies.md b/packages/core/docs/miro/guides/05-services-and-dependencies.md
new file mode 100644
index 000000000..7e56d5e20
--- /dev/null
+++ b/packages/core/docs/miro/guides/05-services-and-dependencies.md
@@ -0,0 +1,54 @@
+---
+sidebar_position: 6
+sidebar_label: Services and Dependencies
+title: "Services and Dependencies"
+description: Control whether services are added with their full dependency graph or standalone
+slug: /miro/services-and-dependencies
+---
+
+When you drag a service onto the board, you can choose whether to add just the service itself or its entire dependency graph — messages, channels, data stores, and related services.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/services-with-deps.gif" alt="Dragging a service with dependencies" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Dragging a service with its dependencies onto the board</span>
+</div>
+
+
+### The dependencies toggle
+
+In the services list view, you'll find a checkbox labeled **Include dependencies when adding to board**.
+
+- **Checked** — dragging a service onto the board also adds all of its connected resources and the connections between them
+- **Unchecked** — only the service node is added to the board, with no dependencies
+
+This setting is remembered between sessions.
+
+### What gets included with dependencies
+
+When the toggle is enabled and you drag a service onto the board, the app automatically adds:
+
+- **Messages** — all events, commands, and queries that the service sends or receives
+- **Channels** — any message brokers or routing channels between the service and its messages
+- **Data Stores** — databases the service reads from or writes to, with labeled connections (reads, writes, or reads & writes)
+- **Related Services** — other services that produce or consume the same messages, so you can see the full communication flow
+
+All connections are drawn automatically with descriptive labels like "publishes event", "receives", "accepts", "writes to", etc.
+
+### When to use each mode
+
+#### With dependencies
+
+Use this when you want to see the full picture of how a service fits into your architecture. This is useful for:
+
+- Understanding the impact of changing a service
+- Onboarding new team members to a service's role in the system
+- Planning migrations that affect multiple services
+
+#### Without dependencies
+
+Use this when you want to manually compose your board — for example:
+
+- Designing a new architecture from scratch
+- Placing specific services side by side for comparison
+- Building a simplified view that only shows certain resources
+- Adding services one at a time and drawing connections manually
diff --git a/packages/core/docs/miro/guides/06-navigating-the-board.md b/packages/core/docs/miro/guides/06-navigating-the-board.md
new file mode 100644
index 000000000..2c08bf683
--- /dev/null
+++ b/packages/core/docs/miro/guides/06-navigating-the-board.md
@@ -0,0 +1,44 @@
+---
+sidebar_position: 5
+sidebar_label: Navigating the Board
+title: "Navigating the Board"
+description: Navigate between connected resources and organize your board layout
+slug: /miro/navigating-the-board
+---
+
+As your board grows, the Miro app provides several ways to navigate between resources and keep things organized.
+
+<div style={{textAlign: "center"}}>
+  <img src="/img/miro/guides/navigation.gif" alt="Editing a resource" style={{width: "75%"}} />
+  <span style={{display: "block", fontSize: "0.8rem", color: "#6B7280", marginTop: "0rem", marginBottom: "1rem"}}>Editing a resource from the detail panel</span>
+</div>
+
+### Clicking connected resources
+
+When viewing a resource's detail panel, you'll see its incoming and outgoing connections listed. Click any connected resource to:
+
+1. **Zoom** to that resource on the board
+2. **Select** it so its detail panel opens automatically
+
+This lets you follow the flow of messages through your architecture — click from a service to an event it publishes, then to the service that consumes it, and so on.
+
+### Finding resources from the list
+
+When browsing the resource list in the sidebar, hover over any resource to reveal a **crosshair icon**. Click it to zoom directly to that resource on the board — helpful when you have a large board and need to locate a specific resource.
+
+### Auto-layout
+
+If your board gets cluttered, click the **Auto-layout** button in the dashboard header. This automatically arranges all resources using a left-to-right directed graph layout, organizing connected resources into a clean flow.
+
+Auto-layout is useful after:
+- Adding several resources with dependencies at once
+- Manually moving things around and wanting to reset the layout
+- Getting a clear picture of the overall architecture flow
+
+### Auto-opening the panel
+
+When you select a node on the board, the app panel automatically opens and shows that resource's details — even if the panel was previously closed. This means you can close the panel to get more board space, then click any node to bring it back with the right context.
+
+### Connection highlighting
+
+When you select a resource on the board, all of its connections are highlighted in purple. This makes it easy to see at a glance which resources are connected to the selected one, even on a busy board.
diff --git a/packages/core/docs/miro/guides/07-exporting-to-eventcatalog.md b/packages/core/docs/miro/guides/07-exporting-to-eventcatalog.md
new file mode 100644
index 000000000..5f363eabf
--- /dev/null
+++ b/packages/core/docs/miro/guides/07-exporting-to-eventcatalog.md
@@ -0,0 +1,75 @@
+---
+sidebar_position: 7
+sidebar_label: Exporting to EventCatalog
+title: "Exporting to EventCatalog"
+description: Export your Miro board design back to EventCatalog
+slug: /miro/exporting-to-eventcatalog
+---
+
+Once you've designed your architecture on the Miro board, you can export it and use AI to update your EventCatalog project automatically.
+
+### Exporting the board
+
+1. Open the app panel and navigate to the dashboard
+2. Click the **Export to JSON** button
+3. A `miro-board-export.json` file is downloaded containing all the items currently on your board — cards, sticky notes, connectors, positions, and styles
+
+The export captures everything on the board as raw Miro data, including resources you imported from your catalog and any new resources or connections you created during your design session.
+
+### Updating your catalog with AI
+
+The exported JSON can be used with [EventCatalog Skills](https://github.com/event-catalog/skills) — AI-powered instructions that understand EventCatalog's file structure and conventions. An AI agent can read your Miro board export and update your catalog accordingly.
+
+#### Step 1: Install EventCatalog Skills
+
+If you haven't already, add the EventCatalog skills to your project:
+
+```bash
+npx skills add event-catalog/skills
+```
+
+This installs conversational skills that teach AI agents how to create and update EventCatalog documentation.
+
+#### Step 2: Feed the export to an AI agent
+
+Open your AI agent (e.g. Claude) in your EventCatalog project directory and provide the exported JSON along with instructions. For example:
+
+```
+Here is a Miro board export from our architecture design session.
+Please update my EventCatalog to reflect the changes we made:
+
+- Add any new services, events, commands, or other resources
+- Update connections between services and messages
+- Create documentation files for new resources
+
+<paste or attach miro-board-export.json>
+```
+
+The AI agent will use the EventCatalog skills to:
+
+- Parse the board items and connectors from the Miro export
+- Identify new resources that need to be added to your catalog
+- Identify updated connections between existing resources
+- Generate properly formatted documentation files with correct frontmatter and folder structure
+- Cross-reference existing catalog resources to avoid duplicates
+
+#### Step 3: Review and commit
+
+The AI generates files in your EventCatalog project. Review the changes, then commit them to your repository:
+
+```bash
+git add .
+git commit -m "Update architecture from Miro design session"
+```
+
+### The workflow
+
+The Miro app is designed to fit into a collaborative design workflow:
+
+1. **Import** your existing architecture from EventCatalog into Miro
+2. **Design** collaboratively — add new resources, draw connections, model what comes next
+3. **Export** the board to JSON
+4. **Update** your catalog using AI skills that understand the Miro export format
+5. **Review and merge** — treat architecture changes like code changes with pull requests
+
+This creates a loop where your catalog stays in sync with your team's design decisions, and every change is tracked in version control.
diff --git a/packages/core/docs/miro/guides/_category_.json b/packages/core/docs/miro/guides/_category_.json
new file mode 100644
index 000000000..879326879
--- /dev/null
+++ b/packages/core/docs/miro/guides/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Guides",
+  "position": 2,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Miro App Guides",
+    "description": "Learn how to use the EventCatalog Miro app to visualize and manage your architecture"
+  }
+}
diff --git a/packages/core/docs/miro/specifications/01-asyncapi.md b/packages/core/docs/miro/specifications/01-asyncapi.md
new file mode 100644
index 000000000..321372d77
--- /dev/null
+++ b/packages/core/docs/miro/specifications/01-asyncapi.md
@@ -0,0 +1,86 @@
+---
+sidebar_position: 1
+sidebar_label: AsyncAPI
+title: "Import AsyncAPI into Miro"
+description: Import your AsyncAPI specifications into Miro via EventCatalog
+slug: /miro/asyncapi
+---
+
+If you have AsyncAPI specifications, you can import them into Miro through EventCatalog. The [AsyncAPI plugin](/docs/plugins/asyncapi/intro) generates services, messages, and channels from your specs — which you can then drag onto a Miro board to visualize and design with your team.
+
+### How it works
+
+```mermaid
+flowchart LR
+    A[AsyncAPI Spec] --> B[EventCatalog<br/>AsyncAPI Plugin]
+    B --> C[EventCatalog]
+    C --> D[Export JSON]
+    D --> E[Miro App]
+
+    style A fill:#6B46C1,color:#fff,stroke:none
+    style B fill:#9333EA,color:#fff,stroke:none
+    style C fill:#7C3AED,color:#fff,stroke:none
+    style D fill:#8B5CF6,color:#fff,stroke:none
+    style E fill:#FFD02F,color:#000,stroke:none
+```
+
+1. **AsyncAPI Spec** — your existing AsyncAPI specification files (YAML or JSON)
+2. **EventCatalog AsyncAPI Plugin** — parses your specs and generates EventCatalog resources
+3. **EventCatalog** — your catalog now contains services, events, commands, queries, and channels from your specs
+4. **Export JSON** — run `npm run export` to generate the catalog JSON
+5. **Miro App** — import the JSON and drag your resources onto the board
+
+### What gets generated
+
+The AsyncAPI plugin creates the following resources from your specifications:
+
+- **Services** — each AsyncAPI spec maps to a service
+- **Messages** — operations become events, commands, or queries (configurable via extensions)
+- **Channels** — AsyncAPI channels are mapped to EventCatalog channels with routing information
+- **Schemas** — message payloads are preserved as schemas in your catalog
+
+All relationships between services, messages, and channels are maintained — so when you drag a service onto the Miro board with dependencies enabled, you'll see the full message flow.
+
+### Getting started
+
+#### 1. Install the AsyncAPI plugin
+
+```bash
+npm install @eventcatalog/generator-asyncapi
+```
+
+#### 2. Configure the plugin
+
+Add the plugin to your `eventcatalog.config.js`:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        { id: 'my-service', path: './asyncapi.yml' },
+      ],
+      domain: { id: 'my-domain', name: 'My Domain', version: '1.0.0' },
+    },
+  ],
+],
+```
+
+#### 3. Generate your catalog
+
+```bash
+npm run generate
+```
+
+#### 4. Export and import into Miro
+
+```bash
+npm run export
+```
+
+Then open the Miro app and [import the JSON](/docs/miro/connecting-to-eventcatalog).
+
+### Learn more
+
+For full plugin configuration, features, and extensions, see the [AsyncAPI plugin documentation](/docs/plugins/asyncapi/intro).
diff --git a/packages/core/docs/miro/specifications/02-openapi.md b/packages/core/docs/miro/specifications/02-openapi.md
new file mode 100644
index 000000000..81ad78e3c
--- /dev/null
+++ b/packages/core/docs/miro/specifications/02-openapi.md
@@ -0,0 +1,86 @@
+---
+sidebar_position: 2
+sidebar_label: OpenAPI
+title: "Import OpenAPI into Miro"
+description: Import your OpenAPI specifications into Miro via EventCatalog
+slug: /miro/openapi
+---
+
+If you have OpenAPI specifications, you can import them into Miro through EventCatalog. The [OpenAPI plugin](/docs/plugins/openapi/intro) generates services and messages from your specs — which you can then drag onto a Miro board to visualize and design with your team.
+
+### How it works
+
+```mermaid
+flowchart LR
+    A[OpenAPI Spec] --> B[EventCatalog<br/>OpenAPI Plugin]
+    B --> C[EventCatalog]
+    C --> D[Export JSON]
+    D --> E[Miro App]
+
+    style A fill:#6B46C1,color:#fff,stroke:none
+    style B fill:#9333EA,color:#fff,stroke:none
+    style C fill:#7C3AED,color:#fff,stroke:none
+    style D fill:#8B5CF6,color:#fff,stroke:none
+    style E fill:#FFD02F,color:#000,stroke:none
+```
+
+1. **OpenAPI Spec** — your existing OpenAPI specification files (YAML or JSON)
+2. **EventCatalog OpenAPI Plugin** — parses your specs and generates EventCatalog resources
+3. **EventCatalog** — your catalog now contains services and messages from your API definitions
+4. **Export JSON** — run `npm run export` to generate the catalog JSON
+5. **Miro App** — import the JSON and drag your resources onto the board
+
+### What gets generated
+
+The OpenAPI plugin creates the following resources from your specifications:
+
+- **Services** — each OpenAPI spec maps to a service (or multiple specs can map to one service)
+- **Messages** — API operations become events, commands, or queries based on HTTP method (configurable)
+- **Schemas** — request/response schemas are preserved in your catalog
+- **Consumer services** — optionally define which services consume specific API routes
+
+All relationships between services and messages are maintained — so when you drag a service onto the Miro board with dependencies enabled, you'll see the full API flow.
+
+### Getting started
+
+#### 1. Install the OpenAPI plugin
+
+```bash
+npm install @eventcatalog/generator-openapi
+```
+
+#### 2. Configure the plugin
+
+Add the plugin to your `eventcatalog.config.js`:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [
+        { id: 'my-api', path: './openapi.yml' },
+      ],
+      domain: { id: 'my-domain', name: 'My Domain', version: '1.0.0' },
+    },
+  ],
+],
+```
+
+#### 3. Generate your catalog
+
+```bash
+npm run generate
+```
+
+#### 4. Export and import into Miro
+
+```bash
+npm run export
+```
+
+Then open the Miro app and [import the JSON](/docs/miro/connecting-to-eventcatalog).
+
+### Learn more
+
+For full plugin configuration, features, and extensions, see the [OpenAPI plugin documentation](/docs/plugins/openapi/intro).
diff --git a/packages/core/docs/miro/specifications/03-schema-registries.md b/packages/core/docs/miro/specifications/03-schema-registries.md
new file mode 100644
index 000000000..d1bb1d214
--- /dev/null
+++ b/packages/core/docs/miro/specifications/03-schema-registries.md
@@ -0,0 +1,88 @@
+---
+sidebar_position: 3
+sidebar_label: Schema Registries
+title: "Import from Schema Registries"
+description: Import schemas from your registry into Miro via EventCatalog
+slug: /miro/schema-registries
+---
+
+If your organization uses a schema registry, you can import your schemas into EventCatalog and use them in Miro. EventCatalog supports several popular schema registries out of the box — and you can build your own using the SDK.
+
+### How it works
+
+```mermaid
+flowchart LR
+    A[Schema Registry] --> B[EventCatalog<br/>Registry Plugin]
+    B --> C[EventCatalog]
+    C --> D[Export JSON]
+    D --> E[Miro App]
+
+    style A fill:#6B46C1,color:#fff,stroke:none
+    style B fill:#9333EA,color:#fff,stroke:none
+    style C fill:#7C3AED,color:#fff,stroke:none
+    style D fill:#8B5CF6,color:#fff,stroke:none
+    style E fill:#FFD02F,color:#000,stroke:none
+```
+
+1. **Schema Registry** — your existing registry containing message schemas
+2. **EventCatalog Registry Plugin** — connects to your registry and generates EventCatalog resources
+3. **EventCatalog** — your catalog now contains services, messages, and schemas from your registry
+4. **Export JSON** — run `npm run export` to generate the catalog JSON
+5. **Miro App** — import the JSON and drag your resources onto the board to model your architecture
+
+### Supported registries
+
+EventCatalog has plugins for the following schema registries:
+
+| Registry | Plugin | Description |
+|----------|--------|-------------|
+| [Confluent Schema Registry](/docs/plugins/confluent-schema-registry/intro) | `@eventcatalog/generator-confluent-schema-registry` | Import Avro, JSON Schema, and Protobuf schemas from Confluent |
+| [AWS Glue Schema Registry](/docs/plugins/aws-glue-registry/intro) | `@eventcatalog/generator-aws-glue-schema-registry` | Import schemas from AWS Glue |
+| [Amazon EventBridge](/integrations/amazon-eventbridge) | `@eventcatalog/generator-amazon-eventbridge` | Import event schemas from EventBridge Schema Registry |
+| [Apicurio Registry](/integrations/apicurio) | `@eventcatalog/generator-apicurio` | Import schemas from Apicurio Registry |
+| [Azure Schema Registry](/docs/plugins/azure-schema-registry/intro) | `@eventcatalog/generator-azure-schema-registry` | Import schemas from Azure Schema Registry |
+| [GitHub](/integrations/github) | `@eventcatalog/generator-github` | Use a GitHub repository as a schema registry |
+
+### Custom registries
+
+If your registry isn't listed above, you can build your own plugin using the [EventCatalog SDK](/docs/sdk). The SDK gives you full control over how schemas are fetched, parsed, and mapped to EventCatalog resources.
+
+### Getting started
+
+Each registry plugin follows the same pattern:
+
+#### 1. Install the plugin
+
+```bash
+npm install @eventcatalog/generator-<your-registry>
+```
+
+#### 2. Configure the plugin
+
+Add the plugin to your `eventcatalog.config.js`:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-<your-registry>',
+    {
+      // Plugin-specific configuration
+      // See the plugin docs for details
+    },
+  ],
+],
+```
+
+#### 3. Generate your catalog
+
+```bash
+npm run generate
+```
+
+#### 4. Export and import into Miro
+
+```bash
+npm run export
+```
+
+Then open the Miro app and [import the JSON](/docs/miro/connecting-to-eventcatalog). Your schemas and messages will be available to drag onto the board, connect to services, and use in your architecture design sessions.
diff --git a/packages/core/docs/miro/specifications/_category_.json b/packages/core/docs/miro/specifications/_category_.json
new file mode 100644
index 000000000..a3ab20b62
--- /dev/null
+++ b/packages/core/docs/miro/specifications/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Import from Specifications",
+  "position": 3,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Import OpenAPI & AsyncAPI into Miro",
+    "description": "Use EventCatalog plugins to import your API specifications and visualize them in Miro"
+  }
+}
diff --git a/packages/core/docs/miro/using-ai/01-overview.md b/packages/core/docs/miro/using-ai/01-overview.md
new file mode 100644
index 000000000..e2ca6a40d
--- /dev/null
+++ b/packages/core/docs/miro/using-ai/01-overview.md
@@ -0,0 +1,105 @@
+---
+sidebar_position: 1
+sidebar_label: From Miro to EventCatalog
+title: "From Miro to EventCatalog with AI"
+description: Use AI to turn your Miro board designs into EventCatalog documentation automatically
+slug: /miro/using-ai
+---
+
+The real power of the Miro app is the round-trip: **import your architecture, design what comes next, then push it all back into EventCatalog**, with AI handling the documentation for you.
+
+### The value
+
+When you design on a Miro board, you're making architecture decisions: new services, new events, new connections. Normally, turning those decisions into documented, structured catalog entries is manual work. With [EventCatalog Skills](https://github.com/event-catalog/skills), an AI agent does it for you:
+
+- **Model with real artifacts.** Start from your actual architecture, not a blank canvas
+- **Draft the future.** Create new services, events, and connections on the board before they exist in code
+- **Pull it back automatically.** Export the board and let AI create the documentation, frontmatter, folder structure, and relationships in your catalog
+
+No copy-pasting. No manually creating files. The AI reads your Miro board export and generates properly structured EventCatalog documentation.
+
+### How it works
+
+```mermaid
+flowchart LR
+    A[Design in Miro] --> B[Export Board JSON]
+    B --> C[Feed to AI Agent]
+    C --> D[AI Creates Docs]
+    D --> E[Review & Commit]
+
+    style A fill:#FFD02F,color:#000,stroke:none
+    style B fill:#8B5CF6,color:#fff,stroke:none
+    style C fill:#7C3AED,color:#fff,stroke:none
+    style D fill:#9333EA,color:#fff,stroke:none
+    style E fill:#6B46C1,color:#fff,stroke:none
+```
+
+### Walkthrough
+
+#### 1. Design your architecture in Miro
+
+Import your existing catalog, then make changes. Add new services, draw new connections, rename resources, sketch out a future state. Everything you'd normally do in a design session with your team.
+
+#### 2. Export the board
+
+Click **Export to JSON** on the dashboard. This downloads a `miro-board-export.json` file containing everything on the board: resources, connections, positions, and labels.
+
+#### 3. Install EventCatalog Skills
+
+If you haven't already, add the skills to your project:
+
+```bash
+npx skills add event-catalog/skills
+```
+
+These skills teach your AI agent how to create and update EventCatalog documentation: proper frontmatter, folder structure, naming conventions, and resource relationships.
+
+#### 4. Feed the export to your AI agent
+
+Open your AI agent (e.g. Claude, Cursor, Windsurf) in your EventCatalog project and give it the export:
+
+```
+Here is the Miro board export from our architecture design session.
+
+Please update my EventCatalog to reflect the changes:
+- Add any new services, events, commands, or queries we created
+- Update connections between services and messages
+- Create documentation for all new resources
+
+<attach or paste miro-board-export.json>
+```
+
+The AI will:
+- Parse the board items (cards, sticky notes) and connectors
+- Identify new resources that need catalog entries
+- Map connections to EventCatalog relationships (sends, receives, writesTo, readsFrom)
+- Generate MDX files with correct frontmatter and folder structure
+- Cross-reference existing resources to avoid duplicates
+
+#### 5. Review and commit
+
+The AI creates files directly in your EventCatalog project. Review the changes, then commit:
+
+```bash
+git add .
+git commit -m "Update architecture from Miro design session"
+```
+
+Open a pull request if your team reviews architecture changes, just like code.
+
+### Example
+
+Say your team designs a new `NotificationService` on the Miro board that consumes an `OrderCompleted` event and sends an `EmailSent` event. After exporting and running through AI, you'd get:
+
+- `services/NotificationService/index.md` with frontmatter linking to the events it sends and receives
+- `events/EmailSent/index.md` with schema, summary, and producer information
+- Updated `events/OrderCompleted/index.md` with `NotificationService` added as a consumer
+
+All properly structured, all linked, all ready for your team to review.
+
+### Tips
+
+- **Be specific in your prompt.** Tell the AI what changed in this session so it knows what to focus on
+- **Attach the full export.** The AI needs the complete board state to understand connections
+- **Review before committing.** AI is great at structure and boilerplate, but you should verify the details match your team's decisions
+- **Use with pull requests.** Treat architecture documentation changes like code changes for team visibility
diff --git a/packages/core/docs/miro/using-ai/_category_.json b/packages/core/docs/miro/using-ai/_category_.json
new file mode 100644
index 000000000..53a1c1957
--- /dev/null
+++ b/packages/core/docs/miro/using-ai/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Using AI",
+  "position": 4,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Using AI with the Miro App",
+    "description": "Use AI to turn your Miro board designs into EventCatalog documentation"
+  }
+}
diff --git a/packages/core/docs/plugins/01-intro.md b/packages/core/docs/plugins/01-intro.md
new file mode 100644
index 000000000..455f4111c
--- /dev/null
+++ b/packages/core/docs/plugins/01-intro.md
@@ -0,0 +1,49 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Contributing
+sidebar_label: Getting started with plugins
+title: Understanding EventCatalog Plugins
+description: Understand how to use EventCatalog plugins
+---
+
+EventCatalog is technology agnostic, which means we can integrate with any system in the world that exposes an API.
+
+This can be schema registries, brokers, cloud providers and more.
+
+EventCatalog intergrates with systems using [generators](/docs/plugins/generators).
+
+### What are generators?    
+
+Generators are scripts that are executed before your build time. They can be used to integrate with brokers, cloud providers and many more systems.
+
+EventCatalog will use generators to pull schemas from registries, or generate messages from your OpenAPI or AsyncAPI files and much more.
+
+You can create your own generators or use the [EventCatalog plugins](#official-eventcatalog-plugins) which are updated and maintained by the EventCatalog team.
+
+#### Official EventCatalog plugins
+
+These plugins are maintained by the EventCatalog team and are updated regularly, to get started click the link below to view the documentation for each plugin.
+
+- [AsyncAPI Plugin](/docs/plugins/asyncapi/intro) - Generate documentation from your AsyncAPI files
+- [OpenAPI Plugin](/docs/plugins/openapi/intro) - Generate documentation from your OpenAPI files
+- [GraphQL Plugin](/docs/plugins/graphql/intro) - Generate documentation from your GraphQL files
+- [Github Plugin](/docs/plugins/github/intro) - Sync your schemas from GitHub to EventCatalog
+- [Backstage Plugin](/docs/plugins/backstage/intro) - Use EventCatalog features within Backstage
+- [Amazon EventBridge](/docs/plugins/eventbridge/intro) - Sync Amazon EventBridge schemas to EventCatalog
+- [Amazon API Gateway](/docs/plugins/amazon-apigateway/intro) - Generate documentation from your Amazon API Gateway
+- [Confluent Schema Registry](/docs/plugins/confluent-schema-registry/intro) - Sync your schemas from Confluent Schema Registry to EventCatalog
+- [EventCatalog Federation](/docs/plugins/eventcatalog-federation/introduction) - Merge multiple EventCatalog instances into a single catalog.
+
+#### Community plugins
+
+- [Atlassian Compass](https://github.com/IsmaelMartinez/generator-atlassian-compass-event-catalog) - Integration with Atlassian Compass. 
+- [Hookdeck](/docs/plugins/hookdeck/intro) - Integration with Hookdeck.
+
+## Custom integrations
+
+EventCatalog can integrate with anything that has an API. 
+
+We offer support and services to build custom integrations for your EventCatalog.
+
+If you would like to explore custom integrations and have us build your integrate for you please contact us at `hello@eventcatalog.dev`.
\ No newline at end of file
diff --git a/packages/core/docs/plugins/02-generators.md b/packages/core/docs/plugins/02-generators.md
new file mode 100644
index 000000000..f5877eafb
--- /dev/null
+++ b/packages/core/docs/plugins/02-generators.md
@@ -0,0 +1,76 @@
+---
+sidebar_position: 2
+keywords:
+  - Generators
+sidebar_label: Understanding generators
+title: Generators
+description: Understanding EventCatalog generators.
+---
+EventCatalog generators are custom scripts executed before the build process begins.
+
+During the catalog build, your configured generators run dynamically, providing the opportunity to utilize open-source generators and plugins or develop your own custom solutions.
+
+### Why use generators?
+
+Generators can be used to automate areas of your catalog. Examples of this include API requests to get schemas from a cloud provider, or integrating with brokers. A generator script can be anything you want.
+
+You can also use the [EventCatalog SDK](/docs/sdk) within your generators to interact with your catalog.
+
+### Getting Started
+
+When configuring a generator you need to define an entry point and it's custom configuration.
+
+In the example below we create a new plugin called `plugin.js` located in the root of the project.
+The object below is configuration the plugin will receive.
+
+```js title="eventcatalog.config.js"
+generators: [
+    [
+        // This generator called 'plugin.js' is located at in the root of your catalog
+      '<rootDir>/plugin.js',
+      // This is custom configuration your generator can use.
+      {
+        customValue: true,
+        hello: 'world'
+      },
+    ],
+    // more generators...
+  ],
+```
+
+```js title="/plugin.js"
+const utils = require('@eventcatalog/sdk');
+
+// Plugins require CJS files at the moment, this is being worked on...
+const { getEvent } = utils.default(__dirname);
+
+// The config value is your EventCatalog config
+// The options value is the configuration you pass to your plugin
+module.exports = async (config, options) => {
+
+    // access to your eventcatalog.config.js file
+    const { homepageLink } = config;
+
+    // Get values from your custom configuration
+    const { customValue, hello  } = options;
+
+    // Call the EventCatalog SDK
+    const event = await getEvent('InventoryAdjusted');
+}
+```
+
+### Running your generators
+
+To run your generators you need to call the command
+
+```sh
+npm run generate
+```
+
+Run generators in their debug mode.
+
+```sh
+npm run generate -- debug
+```
+
+EventCatalog will then run through your generators and call your scripts.
\ No newline at end of file
diff --git a/packages/core/docs/plugins/03-all-plugins.md b/packages/core/docs/plugins/03-all-plugins.md
new file mode 100644
index 000000000..547492f1e
--- /dev/null
+++ b/packages/core/docs/plugins/03-all-plugins.md
@@ -0,0 +1,26 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog Contributing
+sidebar_label: All plugins
+title: All EventCatalog plugins
+description: All EventCatalog plugins
+---
+
+<!--  Table of plugins -->
+
+Automate and sync your data from a wide range of systems to EventCatalog.
+
+| Plugin | Description |
+|--------|-------------|
+| [AsyncAPI Plugin](/docs/plugins/asyncapi/intro) | Generate documentation from your AsyncAPI files |
+| [OpenAPI Plugin](/docs/plugins/openapi/intro) | Generate documentation from your OpenAPI files |
+| [GraphQL Plugin](/docs/plugins/graphql/intro) | Generate documentation from your GraphQL files |
+| [Apicurio Registry](/docs/plugins/apicurio/intro) | Import schemas and specifications from Apicurio Registry into EventCatalog |
+| [Azure Schema Registry](/docs/plugins/azure-schema-registry/intro) | Import schemas from Azure Schema Registry into EventCatalog |
+| [Github Plugin](/docs/plugins/github/intro) | Sync your schemas from GitHub to EventCatalog |
+| [Backstage Plugin](/docs/plugins/backstage/intro) | Use EventCatalog features within Backstage |
+| [Amazon EventBridge](/docs/plugins/eventbridge/intro) | Sync Amazon EventBridge schemas to EventCatalog |
+| [Amazon API Gateway](/docs/plugins/amazon-apigateway/intro) | Generate documentation from your Amazon API Gateway |
+| [Confluent Schema Registry](/docs/plugins/confluent-schema-registry/intro) | Sync your schemas from Confluent Schema Registry to EventCatalog |
+| [EventCatalog Federation](/docs/plugins/eventcatalog-federation/introduction) | Merge multiple EventCatalog instances into a single catalog. |
diff --git a/packages/core/docs/plugins/_category_.json b/packages/core/docs/plugins/_category_.json
new file mode 100644
index 000000000..d036ac462
--- /dev/null
+++ b/packages/core/docs/plugins/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Integrations",
+  "position": 4,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "integrations",
+    "title": "Integrations",
+    "description": "Integrations with EventCatalog"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/plugins/amazon-apigateway/00-intro.md b/packages/core/docs/plugins/amazon-apigateway/00-intro.md
new file mode 100644
index 000000000..3b73ee487
--- /dev/null
+++ b/packages/core/docs/plugins/amazon-apigateway/00-intro.md
@@ -0,0 +1,75 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Getting started
+description: Getting started with Amazon EventBridge plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#commercial-use" />
+
+<!-- <iframe width="100%" height="415" src="https://www.youtube.com/embed/MeBuwAflwM4?si=rhio4gjfDPau4eqB" 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> -->
+
+---
+
+[API Gateway](https://aws.amazon.com/api-gateway/) is an AWS service that allows you to create, publish, maintain, monitor, and secure APIs at any scale.
+
+### Why use EventCatalog with Amazon API Gateway?
+
+Using the EventCatalog Amazon API Gateway integration you can import your API Gateway specifications into EventCatalog. 
+
+This allows you to visualize your API's, their endpoints, and the messages they send and receive. You can map the endpoints to commands, events and queries in your catalog and assign these to services and domains and teams in your organization.
+
+EventCatalog will also allow you to download and view your OpenAPI specifications in the catalog directly, download schemas for each endpoint and see the requests/responses for each endpoint.
+
+### Core Features
+
+The EventCatalog Amazon API Gateway plugin can provide you with many features:
+
+- ⭐️ Generate domains, services, channels and messages into your catalog
+- ⭐️ Import and map your API Gateway specifications into EventCatalog
+- ⭐️ Map API Gateway routes to commands, events and queries in your catalog
+- ⭐️ Add semantic meaning to your API Gateway routes
+- ⭐️ and more....
+
+### How it works
+
+![Example](/img/integrations/amazon-apigateway/amazon-apigateway.png)
+
+This plugin will download OpenAPI specifications from your API Gateway and import them into EventCatalog. The API Gateway integration will add custom EventCatalog extensions onto your OpenAPI specification and then use the [OpenAPI plugin](/docs/plugins/openapi/intro) to import the specification into EventCatalog.
+
+This will map your routes into commands, events and queries in your catalog and assign these to services and domains and teams in your organization.
+
+## Commercial and License
+
+This plugin requires an EventCatalog Scale license key to be used.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial, you can continue using this plugin with EventCatalog Scale. 
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## License FAQ
+
+### What is the license key for?
+The EventCatalog Scale license key is required to use the Amazon API Gateway plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get an EventCatalog Scale license key?
+You can obtain an EventCatalog Scale license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). Your organization can start with a 30-day trial.
+
+### Terms
+- **Trial Period**: 30-day free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can continue with EventCatalog Scale through [EventCatalog Cloud](https://eventcatalog.cloud).
+
+## Issues
+
+If you have any problems or feature requests please feel free to raise them on GitHub. https://github.com/event-catalog/generators or join our [Discord community](https://eventcatalog.dev/discord) to chat with the team and other users.
\ No newline at end of file
diff --git a/packages/core/docs/plugins/amazon-apigateway/01-installation.md b/packages/core/docs/plugins/amazon-apigateway/01-installation.md
new file mode 100644
index 000000000..08f12a228
--- /dev/null
+++ b/packages/core/docs/plugins/amazon-apigateway/01-installation.md
@@ -0,0 +1,196 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Installation
+title: Installation
+description: Installation instructions for the Amazon API Gateway plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PluginLicense url="#commercial-use" />
+
+This plugin requires the OpenAPI and Amazon API Gateway plugins to be installed.
+
+<!-- <iframe width="100%" height="415" src="https://www.youtube.com/embed/MeBuwAflwM4?si=rhio4gjfDPau4eqB" 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> -->
+
+---
+
+## Installation
+
+Run the command below to install the Amazon API Gateway generator.
+
+:::tip "Don't have an EventCatalog project yet?"
+If you don't have an EventCatalog project yet, you can follow the instructions in the [Getting Started](/docs/development/getting-started/installation) guide.
+:::
+
+<Tabs>
+  <TabItem value="apple" label="Install on existing catalog" default>
+    ```bash
+npm i @eventcatalog/generator-amazon-apigateway
+```
+  </TabItem>
+  <TabItem value="orange" label="Create new catalog with the Amazon API Gateway template">
+     ```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --template amazon-apigateway
+```
+  </TabItem>
+</Tabs>
+
+## Configuration
+
+In your `eventcatalog.config.js` file, add the API Gateway generator and OpenAPI plugin to the `generators` array.
+
+```js title="eventcatalog.config.js"
+import path from "path";
+import url from "url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  cId: "10b46030-5736-4600-8254-421c3ed56e47",
+  title: "EventCatalog",
+  tagline: "Discover, Explore and Document your Event Driven Architectures",
+  organizationName: "Your Company",
+  homepageLink: "https://eventcatalog.dev/",
+  editUrl: "https://github.com/boyney123/eventcatalog-demo/edit/master",
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: "/",
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: "EventCatalog Logo",
+    src: "/logo.png",
+    text: "EventCatalog",
+  },
+  docs: {
+    sidebar: {
+      // Should the sub heading be rendered in the docs sidebar?
+      showPageHeadings: true,
+    },
+  },
+  generators: [
+    [
+      "@eventcatalog/generator-amazon-apigateway",
+      {
+        output: 'amazon-api-gateway-output',
+        apis: [
+          {
+            // The name of the API we want to process
+            name: 'EcommerceApi',
+            // Assume it's deployed to us-east-1, change this if you deployed somewhere else
+            region: 'us-east-1',
+            // The API stage name
+            stageName: 'prod',
+            version: '2',
+            // Optional routes, we can map routes to message types
+            // give them descriptions and unique ids in eventcatalog
+            routes: {
+              'post /cart/checkout': {
+                type: 'command',
+                id: 'CheckoutCart',
+                description: 'Request to checkout the cart',
+              },
+              'post /cart/clear': {
+                type: 'command',
+                id: 'ClearCart',
+                description: 'Request to clear the cart',
+              },
+            }
+          }
+        ]
+      },
+    ],
+    // This will process the output of the amazon api gateway generator
+    // it will process the OpenAPI file and map it into a service and domain
+    // All routes are mapped to messages.
+    [
+      "@eventcatalog/generator-openapi",
+      {
+        services: [
+          { path: path.join(__dirname, "amazon-api-gateway-output", "EcommerceApi.json"), id: 'ecommerce-api', owners: ['full-stack'] },
+        ]
+      },
+    ],
+  ],
+};
+```
+
+### Configure license key
+
+The API Gateway and OpenAPI plugin both require a license key to work with EventCatalog.
+
+You can get a trial Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+You have a few options for setting the license key:
+
+1. [Setting license key in `.env` file (recommended)](#setting-license-key-in-env-file-recommended)
+2. [Setting license key in eventcatalog.config.js](#setting-license-key-in-eventcatalogconfigjs)
+
+#### 1. Setting license key in `.env` file (recommended) {#setting-license-key-in-env-file-recommended}
+
+<AddedIn version="2.35.4" />
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+:::tip Using an Older API Key?
+
+If you already have older Amazon API Gateway and OpenAPI plugin keys, you can still use them with the plugin-specific environment variables.
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_AMAZON_APIGATEWAY=your-license-key
+EVENTCATALOG_LICENSE_KEY_OPENAPI=your-license-key
+```
+
+:::
+
+#### 2. Setting license key in eventcatalog.config.js {#setting-license-key-in-eventcatalogconfigjs}
+
+If you prefer, you can set the license key in the `eventcatalog.config.js` file
+using the `licenseKey` property in both the API Gateway and OpenAPI plugin.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-eventbridge',
+      {
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_SCALE_LICENSE_KEY
+      },
+    ],
+  ],
+};
+```
+
+#### White listing EventCatalog domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+## Run the generator
+
+Once you have configured the plugin and license key you can run the generator.
+
+```sh
+npm run generate
+```
+
+## View your catalog
+
+Run your catalog locally to see the changes.
+
+```sh
+npm run dev
+```
+
+
diff --git a/packages/core/docs/plugins/amazon-apigateway/02-plugin-configuration.md b/packages/core/docs/plugins/amazon-apigateway/02-plugin-configuration.md
new file mode 100644
index 000000000..87b4b2724
--- /dev/null
+++ b/packages/core/docs/plugins/amazon-apigateway/02-plugin-configuration.md
@@ -0,0 +1,137 @@
+---
+sidebar_position: 1
+keywords:
+- Amazon API Gateway
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the Amazon API Gateway plugin
+---
+
+This plugin requires an EventCatalog Scale license key.
+
+You can get a 30-day free trial license key by signing up to [EventCatalog Cloud](https://eventcatalog.dev/cloud).
+
+Once you have your license key you can set the `EVENTCATALOG_SCALE_LICENSE_KEY` environment variable.
+
+## Overview
+
+The Amazon API Gateway plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+## Configuration Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `output` | string | No | `amazon-apigateway-specs` | The output directory for the OpenAPI specifications (used by the OpenAPI Generator plugin) |
+| `credentials` | [AwsCredentialIdentity](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-types/Interface/AwsCredentialIdentity/) | No | - | AWS credentials to use for the import on AWS. If this is not provided it will default to the credentials on the machine. |
+| `licenseKey` | string | No | - | You can either pass the license key directly or set the `EVENTCATALOG_SCALE_LICENSE_KEY` environment variable. |
+| `apis` | API[] | Yes | - | Array of API configurations |
+
+## API Configuration
+
+The `apis` option is an array of API configurations. Each API configuration has the following options:
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `name` | string | Yes | - | Name of the API in AWS |
+| `region` | string | Yes | - | AWS region of the API |
+| `stageName` | string | Yes | - | Stage name of the API |
+| `version` | number | No | 1 | Version of the API. Amazon API Gateway versions using dates. EventCatalog needs to use semver as versions. It will default to `1` but you can specify a different version. |
+| `routes` | Route | No | - | Map your routes into EventCatalog information. For example map your routes into commands, queries, events, etc. |
+
+## Route Configuration
+
+The `routes` option is a map of routes. Each route has the following options:
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `type` | string | Yes | - | Type of the route. Can be `command`, `query`, or `event`. |
+| `id` | string | No | - | EventCatalog ID, if you want to override it. |
+| `name` | string | No | - | Give the message (route) a name in EventCatalog |
+| `description` | string | No | - | Define a description for the message |
+
+## Example Configuration
+
+```js title="eventcatalog.config.js"
+import path from "path";
+import url from "url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  cId: "10b46030-5736-4600-8254-421c3ed56e47",
+  title: "EventCatalog",
+  tagline: "Discover, Explore and Document your Event Driven Architectures",
+  organizationName: "Your Company",
+  homepageLink: "https://eventcatalog.dev/",
+  editUrl: "https://github.com/boyney123/eventcatalog-demo/edit/master",
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: "/",
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: "EventCatalog Logo",
+    src: "/logo.png",
+    text: "EventCatalog",
+  },
+  docs: {
+    sidebar: {
+      // Should the sub heading be rendered in the docs sidebar?
+      showPageHeadings: true,
+    },
+  },
+  generators: [
+    [
+      "@eventcatalog/generator-amazon-apigateway",
+      {
+        output: 'amazon-api-gateway-output',
+        apis: [
+          {
+            // The name of the API we want to process
+            name: 'EcommerceApi',
+            // Assume it's deployed to us-east-1, change this if you deployed somewhere else
+            region: 'us-east-1',
+            // The API stage name
+            stageName: 'prod',
+            version: '2',
+            // Optional routes, we can map routes to message types
+            // give them descriptions and unique ids in eventcatalog
+            routes: {
+              'post /cart/checkout': {
+                type: 'command',
+                id: 'CheckoutCart',
+                description: 'Request to checkout the cart',
+              },
+              'post /cart/clear': {
+                type: 'command',
+                id: 'ClearCart',
+                description: 'Request to clear the cart',
+              },
+            }
+          }
+        ]
+      },
+    ],
+    // This will process the output of the amazon api gateway generator
+    // it will process the OpenAPI file and map it into a service and domain
+    // All routes are mapped to messages.
+    [
+      "@eventcatalog/generator-openapi",
+      {
+        services: [
+          { path: path.join(__dirname, "amazon-api-gateway-output", "EcommerceApi.json"), id: 'ecommerce-api', owners: ['full-stack'] },
+        ]
+      },
+    ],
+  ],
+};
+```
+
+You can view an example configuration in the  [EventCatalog Amazon API Gateway plugin GitHub repository](https://github.com/event-catalog/generators/blob/main/examples/generator-amazon-apigateway/basic/eventcatalog.config.js).
+
+
+
+
+
diff --git a/packages/core/docs/plugins/amazon-apigateway/03-features.md b/packages/core/docs/plugins/amazon-apigateway/03-features.md
new file mode 100644
index 000000000..8c2a8fddf
--- /dev/null
+++ b/packages/core/docs/plugins/amazon-apigateway/03-features.md
@@ -0,0 +1,71 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Features
+title: Features
+description: Features of AsyncAPI with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+### Customize the output directory
+
+The plugin will output the OpenAPI specification to the directory you specify in the `output` property.
+
+```js title="eventcatalog.config.js"  
+output: 'amazon-api-gateway-output',
+```
+
+By default the plugin will output to `amazon-api-gateway-output` in the root of your project.
+
+Remember to add the output directory to your `.gitignore` file so it's not checked into your repository.
+
+### Map routes to messages in EventCatalog
+
+The API Gateway plugin maps routes to messages in EventCatalog. You can map your routes to queries, commands or events.
+
+To map routes you can use the `apis` property in the plugin configuration.
+
+```js title="eventcatalog.config.js"  
+generators: [
+    [
+      "@eventcatalog/generator-amazon-apigateway",
+      {
+        output: 'amazon-api-gateway-output',
+        apis: [
+          {
+            // The name of the API we want to process
+            name: 'EcommerceApi',
+            // Assume it's deployed to us-east-1, change this if you deployed somewhere else
+            region: 'us-east-1',
+            // The API stage name
+            stageName: 'prod',
+            version: '2',
+            // Optional routes, we can map routes to message types
+            // give them descriptions and unique ids in eventcatalog
+            routes: {
+              'post /cart/checkout': {
+                type: 'command',
+                id: 'CheckoutCart',
+                description: 'Request to checkout the cart',
+              },
+              'post /cart/clear': {
+                type: 'command',
+                id: 'ClearCart',
+                description: 'Request to clear the cart',
+              },
+            }
+          }
+        ]
+      },
+    ],
+  ],
+```
+
+In the example above we are mapping the `post /cart/checkout` and `post /cart/clear` routes to commands in EventCatalog. When we run the plugin new messages called `CheckoutCart` and `ClearCart` will be created in EventCatalog.
+
+We can also specify the `id` and `description` for the message if we choose to override the default values. The values are taken from the operationId in the OpenAPI specification.
+
+
+
diff --git a/packages/core/docs/plugins/amazon-apigateway/04-examples.md b/packages/core/docs/plugins/amazon-apigateway/04-examples.md
new file mode 100644
index 000000000..896ea7822
--- /dev/null
+++ b/packages/core/docs/plugins/amazon-apigateway/04-examples.md
@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the Amazon API Gateway plugin
+---
+
+You can find many examples of using the Amazon API Gateway plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [Amazon API Gateway Example](https://github.com/event-catalog/generators/tree/main/examples/generator-amazon-apigateway/basic)
+  - Pull OpenAPI specifications from Amazon API Gateway and map to services, domains and messages. Use custom filters to map routes to services.
\ No newline at end of file
diff --git a/packages/core/docs/plugins/amazon-apigateway/_category_.json b/packages/core/docs/plugins/amazon-apigateway/_category_.json
new file mode 100644
index 000000000..89c620b26
--- /dev/null
+++ b/packages/core/docs/plugins/amazon-apigateway/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Amazon API Gateway Plugin",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "amazon-apigateway",
+    "title": "Amazon API Gateway",
+    "description": "Amazon API Gateway integration documentation for EventCatalog"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/plugins/apicurio/00-intro.md b/packages/core/docs/plugins/apicurio/00-intro.md
new file mode 100644
index 000000000..1bed0c404
--- /dev/null
+++ b/packages/core/docs/plugins/apicurio/00-intro.md
@@ -0,0 +1,102 @@
+---
+sidebar_position: 1
+keywords:
+- apicurio
+- schema registry
+sidebar_label: Introduction
+title: Introduction
+description: Getting started with Apicurio Registry plugin
+---
+
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#commercial-use" />
+
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/0DmGWa0sr6w?si=KsE4D9C_yN7998Vo" 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>
+
+
+---
+
+Many teams building event-driven architectures use schema registries to manage their message schemas and API specifications.
+
+[Apicurio Registry](https://www.apicur.io/registry/) is an open-source schema registry that provides a centralized location to store and manage schemas for your event-driven applications. It supports multiple schema formats including Avro, JSON Schema, Protobuf, AsyncAPI, and OpenAPI.
+
+We believe schema registries are a great foundation, but there's significant value in adding semantic meaning to your schemas, assigning them to services and domains, and creating comprehensive documentation around your architecture.
+
+The [EventCatalog Apicurio Registry plugin](https://github.com/event-catalog/generators/tree/main/packages/generator-apicurio) allows you to import your schemas and specifications from Apicurio Registry into EventCatalog. Keep your architecture documentation in sync with your registry while unlocking additional visualization and documentation capabilities.
+
+:::info
+**What is Apicurio Registry?**: An open-source schema registry for event-driven architectures. Use it to store and manage your event schemas and API specifications. Learn more at the [Apicurio website](https://www.apicur.io/registry/).
+:::
+
+### Core Features of the Apicurio Registry plugin
+
+The EventCatalog Apicurio Registry plugin provides you with many powerful features:
+
+- ⭐️ Import schemas and specifications from your Apicurio Registry into EventCatalog
+- ⭐️ Keep schemas in sync with your architecture documentation
+- ⭐️ Automatic versioning - as your schemas change they are versioned in EventCatalog alongside your documentation
+- ⭐️ Support for multiple schema formats (Avro, JSON Schema, Protobuf, AsyncAPI, OpenAPI)
+- ⭐️ Add semantic meaning (markdown) to your schemas - provide business context and added value
+- ⭐️ Use custom filters (prefix, suffix, exact matches) to select which schemas to import
+- ⭐️ Assign schemas to services and domains
+- ⭐️ Document your schemas as commands, events, or queries
+- ⭐️ Integrate with OpenAPI and AsyncAPI plugins to generate complete service documentation
+- ⭐️ Visualize your event-driven architecture with the [EventCatalog Visualizer](/features/visualization)
+- ⭐️ Download and view schemas directly in EventCatalog
+- ⭐️ Talk to your schemas, services, and domains with the [EventCatalog Chat](/features/ai-assistant)
+- ⭐️ Support for Bearer token authentication for secured registries
+- ⭐️ and more....
+
+### How it works
+
+1. Install the Apicurio Registry plugin
+1. Configure the plugin (schemas, services, domains, specifications)
+1. Run the plugin to import your schemas into EventCatalog
+1. View and deploy your catalog
+
+![Apicurio Registry plugin](./images/apicurio.png)
+
+**What are generators?**
+
+EventCatalog supports [generators](/docs/plugins/generators). These are scripts or plugins that can be run to integrate with any external API, system, or specification files. EventCatalog also provides an [SDK](/docs/sdk) to give developers easier access to their catalogs through custom scripts or generators.
+
+The EventCatalog Apicurio Registry plugin is a generator. It will import your schemas and specifications from your Apicurio Registry into EventCatalog.
+
+## Commercial and License
+
+This plugin requires an EventCatalog Scale license key to be used.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial, you can continue using this plugin with EventCatalog Scale.
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## Need a demo?
+
+If you would like a demo of the plugin, please feel free to reach out to us and book a time to chat at hello@eventcatalog.dev.
+
+## License FAQ
+
+### What is the license key for?
+The EventCatalog Scale license key is required to use the Apicurio Registry plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get an EventCatalog Scale license key?
+You can obtain an EventCatalog Scale license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 30-day free trial.
+
+### Terms
+- **Trial Period**: 30-day free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can continue with EventCatalog Scale through [EventCatalog Cloud](https://eventcatalog.cloud).
+
+## Any questions or need help?
+
+If you have questions or need help, you can join our [Discord community](https://eventcatalog.dev/discord) or raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).
diff --git a/packages/core/docs/plugins/apicurio/01-installation.md b/packages/core/docs/plugins/apicurio/01-installation.md
new file mode 100644
index 000000000..c187a6d9d
--- /dev/null
+++ b/packages/core/docs/plugins/apicurio/01-installation.md
@@ -0,0 +1,175 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Apicurio Registry
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog Apicurio Registry plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PluginLicense url="#commercial-use" />
+
+The Apicurio Registry plugin is used to generate a catalog from an Apicurio Registry and import your schemas and specifications into EventCatalog.
+
+You can map your schemas from your Apicurio Registry to events, commands, or queries in your catalog, and assign these to services and domains.
+
+## Installation
+
+Run the command below to install the EventCatalog Apicurio Registry plugin.
+
+:::tip "Don't have an EventCatalog project yet?"
+If you don't have an EventCatalog project yet, you can follow the instructions in the [Getting Started](/docs/development/getting-started/installation) guide.
+:::
+
+```bash
+npm i @eventcatalog/generator-apicurio
+```
+
+<!-- <Tabs>
+  <TabItem value="apple" label="Install on existing catalog" default>
+    
+  </TabItem>
+  <TabItem value="orange" label="Create new catalog with Apicurio Registry plugin">
+     ```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --template apicurio
+```
+  </TabItem>
+</Tabs> -->
+
+## Configuration
+
+To use the plugin you need to configure it in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators` array.
+
+<Tabs>
+  <TabItem value="apple" label="Import all schemas" default>
+
+  In this example we import all schemas from an Apicurio Registry into EventCatalog.
+
+  You can also create services and assign schemas to them, along with domains. [(see examples)](/docs/plugins/apicurio/plugin-configuration#example-configurations).
+
+
+    ```js title="eventcatalog.config.js"
+    // ...
+    generators: [
+      // 1. Import all schemas from an Apicurio Registry
+      [
+        '@eventcatalog/generator-apicurio',
+        {
+          // The URL of your Apicurio Registry
+          registryUrl: 'http://localhost:8080',
+          // Do you want to include all versions of a schema? (default: false)
+          includeAllVersions: true
+        },
+      ],
+    ];
+    ```
+  </TabItem>
+  <TabItem value="orange" label="Import schemas and assign them to services and domains">
+
+In this example we document services, assign schemas to them, and organize everything within a domain.
+
+We create an `orders` domain and an `Orders Service` that sends and receives messages.
+
+```js title="eventcatalog.config.js"
+// ...
+ [
+  '@eventcatalog/generator-apicurio',
+      {
+        // The URL of your Apicurio Registry
+        registryUrl: 'http://localhost:8080',
+        // The services to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // the messages this service sends
+            // We use the prefix matching against the artifact name
+            sends: [
+              { events: { prefix: 'order-' } }
+            ],
+            // the messages this service receives
+            // We use the exact matching against the artifact name
+            receives: [
+              { commands: ['place-order', 'cancel-order'] }
+            ],
+          },
+        ],
+        domain: {
+          id: 'orders',
+          name: 'Orders',
+          version: '1.0.0',
+        }
+      },
+    ],
+```
+  </TabItem>
+</Tabs>
+
+### Configure API keys
+
+The EventCatalog Apicurio Registry plugin requires API keys in your environment variables.
+
+1. An EventCatalog Scale license key for the Apicurio Registry plugin (30-day trial, at [EventCatalog Cloud](https://eventcatalog.cloud))
+2. Apicurio Registry access token (optional - only if your registry requires authentication)
+
+Create a `.env` file in the root, and add your keys to the project.
+
+```bash title=".env"
+# EventCatalog license key
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+
+# Apicurio Registry Bearer Token (optional - only if your registry requires authentication)
+APICURIO_ACCESS_TOKEN=your-access-token-here
+```
+
+:::tip Using an Older API Key?
+
+If you already have an older Apicurio Registry plugin key, you can still use it with the plugin-specific environment variable.
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_APICURIO_SCHEMA_REGISTRY=your-license-key
+```
+
+:::
+
+#### White listing EventCatalog domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+#### Run the plugin
+
+Run the plugin to import your schemas into EventCatalog.
+
+_This command will run the generators in your eventcatalog.config.js file._
+
+```
+npm run generate
+```
+
+#### View your catalog
+
+Run your catalog locally to see the changes
+
+```
+npm run dev
+```
+
+#### Build your catalog for production
+
+```
+npm run build
+```
+
+## Any questions or need help?
+
+If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
+
+You can also find some examples of the plugin in action in our examples repository: [eventcatalog/examples](https://github.com/event-catalog/generators/tree/main/examples/generator-apicurio).
diff --git a/packages/core/docs/plugins/apicurio/02-plugin-configuration.md b/packages/core/docs/plugins/apicurio/02-plugin-configuration.md
new file mode 100644
index 000000000..da500938b
--- /dev/null
+++ b/packages/core/docs/plugins/apicurio/02-plugin-configuration.md
@@ -0,0 +1,680 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Apicurio Registry plugin
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog Apicurio Registry plugin
+---
+
+# Plugin Configuration
+
+## Overview
+
+The EventCatalog Apicurio Registry plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+:::info Authentication
+If your Apicurio Registry requires authentication, you can configure a Bearer token as an environment variable.
+
+<details>
+<summary>Example .env file</summary>
+
+```bash
+export APICURIO_ACCESS_TOKEN=your-access-token-here
+```
+
+</details>
+
+:::
+
+## Required Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `registryUrl` | `string` | Yes | The URL of your Apicurio Registry (e.g., `http://localhost:8080`). The plugin automatically appends the `/apis/registry/v3` API path. |
+| `includeAllVersions` | `boolean` | No | If true, all versions of the schemas will be imported into EventCatalog (default is `false`). When enabled, each version of a schema creates a separate versioned entry in EventCatalog. |
+
+## Optional Configuration Options
+
+### Services
+
+You can assign schemas to services (producers/consumers).
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `services` | object | - | List of services to assign the schemas to. |
+| `services.id` | string | - | EventCatalog ID for the service. |
+| `services.version` | string | - | Version of the service. |
+| `services.name` | string | - | Name of the service (optional, defaults to ID). |
+| `services.summary` | string | - | Summary description of the service (optional). |
+| `services.sends` | Filter | - | Configuration to assign schemas that this service sends (publishes). |
+| `services.receives` | Filter | - | Configuration to assign schemas that this service receives (consumes). |
+| `services.writesTo` | array | - | Array of services this service writes to. Each entry has `id` (required) and optional `version`. |
+| `services.readsFrom` | array | - | Array of services this service reads from. Each entry has `id` (required) and optional `version`. |
+| `services.specifications` | array | - | Array of specification artifacts (OpenAPI/AsyncAPI) to attach to the service. See [Specifications](#specifications) section below. |
+
+### Domains
+
+You can define and assign domains to your services.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `domain.id` | string | - | EventCatalog ID for the domain (e.g `orders`). |
+| `domain.name` | string | - | Name of the domain (e.g `Orders`). |
+| `domain.version` | string | - | Version of the domain (e.g `1.0.0`). |
+| `domain.summary` | string | - | Summary description of the domain (optional). |
+
+### Specifications
+
+You can attach OpenAPI or AsyncAPI specifications stored in your Apicurio Registry to services. When configured with a generator, these specifications will be automatically processed to generate comprehensive service documentation including REST endpoints, async events, and more.
+
+<details>
+<summary>Learn more about attaching OpenAPI and AsyncAPI specifications</summary>
+
+You can attach OpenAPI or AsyncAPI specifications from your Apicurio Registry to services. These specifications can optionally be processed by their respective EventCatalog plugins to generate additional documentation.
+
+:::info Plugin Licenses Required
+The OpenAPI and AsyncAPI generators require an EventCatalog Scale license key. To use them with the Apicurio plugin, you'll need to:
+- Install the respective plugins: `npm install @eventcatalog/generator-openapi @eventcatalog/generator-asyncapi`
+- Obtain an EventCatalog Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud) (30-day free trial available)
+- Configure the license key in your `.env` file:
+  - `EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key`
+
+Learn more: [OpenAPI Plugin Docs](/docs/plugins/openapi/intro) | [AsyncAPI Plugin Docs](/docs/plugins/asyncapi/intro)
+:::
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `services.specifications` | array | No | Array of specification configurations to attach to the service. |
+| `specifications[].type` | string | Yes | Type of specification: `'openapi'` or `'asyncapi'`. |
+| `specifications[].artifactId` | string | Yes | The artifact ID in Apicurio Registry. |
+| `specifications[].version` | string | No | Specific version to fetch, or `'latest'` (default). |
+| `specifications[].generator` | array | No | Optional EventCatalog generator to process the specification. Format: `['@eventcatalog/generator-openapi', { options }]` |
+
+**Example:**
+
+```js
+services: [{
+  id: 'Orders Service',
+  version: '1.0.0',
+  specifications: [
+    {
+      type: 'openapi',
+      artifactId: 'OrdersAPI-OPENAPI',
+      version: 'latest',
+      generator: ['@eventcatalog/generator-openapi', {
+        // generator options here
+      }]
+    },
+    {
+      type: 'asyncapi',
+      artifactId: 'OrdersEvents-ASYNCAPI',
+      version: '2.0.0',
+      generator: ['@eventcatalog/generator-asyncapi', {
+        // generator options here
+      }]
+    }
+  ]
+}]
+```
+
+When a generator is configured, the plugin will:
+1. Fetch the specification from Apicurio Registry
+2. Save it to the service directory
+3. Run the specified generator to process the specification
+4. Pass the domain configuration to the generator if a domain is configured
+
+</details>
+
+### Filtering schemas to services
+
+When you assign schemas to a service, you can use a range of filtering options including exact matches, prefixes, suffixes, and includes.
+
+Here are some examples of how to filter schemas to services.
+
+<details>
+<summary>`exact` matching example - Match schemas that exactly match the specified name</summary>
+
+**What is exact matching?**
+
+Exact matching is when the schema artifact ID exactly matches the specified name.
+
+In this example, the `Orders Service` will send `events` with the artifact IDs `order-placed`, `order-cancelled` and receive `commands` with the artifact ID `place-order`.
+
+Example artifacts in Apicurio Registry:
+- `order-placed`
+- `order-cancelled`
+- `place-order`
+- `cancel-order`
+
+```js
+// ...
+generators: [
+  // Import schemas (using filters), assign them to services and domains
+  [
+    '@eventcatalog/generator-apicurio',
+      {
+        // The URL of your Apicurio Registry
+        registryUrl: 'http://localhost:8080',
+        // The services to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that match the artifact IDs
+            sends: [{ events: ['order-placed', 'order-cancelled']}],
+            // The Order service receives commands that match the artifact IDs
+            receives: [{ commands: ['place-order', 'cancel-order']}],
+          }
+        ],
+      },
+  ],
+];
+```
+
+</details>
+
+<details>
+<summary>`suffix` matching example - Match schemas that end with a specific string</summary>
+
+**What is suffix matching?**
+
+Suffix matching is when the artifact ID ends with the specified suffix.
+
+In this example, the `Orders Service` will send `events` with a suffix of `-placed` and receive `commands` with a suffix of `-command`.
+
+Example artifacts in registry:
+- `order-placed`
+- `order-cancelled`
+- `place-order-command`
+- `cancel-order-command`
+
+```js
+// ...
+generators: [
+  // Import schemas (using filters), assign them to services and domains
+  [
+    '@eventcatalog/generator-apicurio',
+      {
+        // The URL of your Apicurio Registry
+        registryUrl: 'http://localhost:8080',
+        // The services to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events with a suffix of `-placed`
+            sends: [{ events: { suffix: '-placed' }}],
+            // The Order service receives commands with a suffix of `-command`
+            receives: [{ commands: { suffix: '-command' }}],
+          }
+        ],
+      },
+  ],
+];
+```
+
+</details>
+
+<details>
+<summary>`prefix` matching example - Match schemas that start with a specific string</summary>
+
+**What is prefix matching?**
+
+Prefix matching is when the artifact ID starts with the specified prefix.
+
+In this example, the `Orders Service` will send `events` with a prefix of `order-` and receive `commands` with a prefix of `analytics-`.
+
+Example artifacts in registry:
+- `order-placed`
+- `order-cancelled`
+- `analytics-place-order`
+- `analytics-cancel-order`
+
+```js
+// ...
+generators: [
+  // Import schemas (using filters), assign them to services and domains
+  [
+    '@eventcatalog/generator-apicurio',
+      {
+        // The URL of your Apicurio Registry
+        registryUrl: 'http://localhost:8080',
+        // The services to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events with a prefix of `order-`
+            sends: [{ events: { prefix: 'order-' }}],
+            // The Order service receives commands with a prefix of `analytics-`
+            receives: [{ commands: { prefix: 'analytics-' }}],
+          }
+        ],
+      },
+  ],
+];
+```
+
+</details>
+
+<details>
+<summary>`includes` matching example - Match schemas that include a specific string</summary>
+
+**What is includes matching?**
+
+Includes matching is when the artifact ID contains the specified string anywhere in its name.
+
+In this example, the `Orders Service` will send `events` that include the string `order` and receive `commands` that include the string `analytics`.
+
+Example artifacts in registry:
+- `order-placed`
+- `order-cancelled`
+- `analytics-place-order`
+- `analytics-cancel-order`
+
+```js
+// ...
+generators: [
+  // Import schemas (using filters), assign them to services and domains
+  [
+    '@eventcatalog/generator-apicurio',
+      {
+        // The URL of your Apicurio Registry
+        registryUrl: 'http://localhost:8080',
+        // The services to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that include `order`
+            sends: [{ events: { includes: 'order' }}],
+            // The Order service receives commands that include `analytics`
+            receives: [{ commands: { includes: 'analytics' }}],
+          }
+        ],
+      },
+  ],
+];
+```
+
+</details>
+
+<details>
+<summary>Message types - Document schemas as events, commands, or queries</summary>
+
+**What are message types?**
+
+You can document your schemas as different message types in EventCatalog:
+- **events**: Things that have happened (past tense)
+- **commands**: Requests to do something (imperative)
+- **queries**: Requests for information
+
+In this example, the `Orders Service` sends events and receives both commands and queries.
+
+```js
+// ...
+generators: [
+  [
+    '@eventcatalog/generator-apicurio',
+      {
+        registryUrl: 'http://localhost:8080',
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Sends events
+            sends: [{ events: { prefix: 'order-' }}],
+            // Receives commands and queries
+            receives: [
+              { commands: ['place-order', 'cancel-order']},
+              { queries: ['get-order-status']}
+            ],
+          }
+        ],
+      },
+  ],
+];
+```
+
+</details>
+
+## Example Configurations
+
+The Apicurio Registry plugin is flexible to work with your use case.
+Here are a few examples of how you can configure the plugin.
+
+<details>
+<summary>Example configuration - Import all schemas (and versions) into EventCatalog</summary>
+
+In this example we import all schemas from the Apicurio Registry into EventCatalog.
+No services or domains are configured or created. This is a simple way to import schemas into the catalog and keep them in sync with your documentation.
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-apicurio',
+      {
+        // The URL of your Apicurio Registry
+        registryUrl: 'http://localhost:8080',
+
+        // Include all versions of the schemas
+        includeAllVersions: true,
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+<details>
+<summary>Example configuration - Assign schemas to services</summary>
+
+In this example we assign schemas to services (producers and consumers in EventCatalog).
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-apicurio',
+      {
+        // The URL of your Apicurio Registry
+        registryUrl: 'http://localhost:8080',
+        // The services to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that match the artifact IDs
+            sends: [{ events: ['order-placed', 'order-cancelled']}],
+            // The Order service receives commands that match the artifact IDs
+            receives: [{ commands: ['place-order', 'cancel-order']}],
+          }
+        ]
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+<details>
+<summary>Example configuration - Assign schemas to services (with filters)</summary>
+
+In this example we assign schemas to services (producers and consumers in EventCatalog) but we use filters to match the schemas.
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-apicurio',
+      {
+        // The URL of your Apicurio Registry
+        registryUrl: 'http://localhost:8080',
+        // The services to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that start with `order-`
+            sends: [{ events: { prefix: 'order-' }}],
+            // The Order service receives commands that end with `-command`
+            receives: [{ commands: { suffix: '-command' }}],
+          }
+        ]
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+<details>
+<summary>Example configuration - Assign schemas to services within a domain</summary>
+
+In this example we assign schemas to services (producers and consumers in EventCatalog) and we also assign them to a *domain*.
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-apicurio',
+      {
+        // The URL of your Apicurio Registry
+        registryUrl: 'http://localhost:8080',
+        // The services to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events
+            sends: [{ events: ['order-placed', 'order-cancelled']}],
+            // The Order service receives commands
+            receives: [{ commands: ['place-order', 'cancel-order']}],
+          }
+        ],
+        // The domain to assign the service to
+        // if it does not exist, it will be created
+        domain: {
+          id: 'orders',
+          name: 'Orders',
+          version: '1.0.0',
+        }
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+<details>
+<summary>Example configuration - Attach specifications and use nested generators</summary>
+
+In this example we attach OpenAPI and AsyncAPI specifications to a service and use the respective EventCatalog generators to process them.
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-apicurio',
+      {
+        // The URL of your Apicurio Registry
+        registryUrl: 'http://localhost:8080',
+        // The services to assign schemas to
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Attach specifications from Apicurio Registry
+            specifications: [
+              {
+                type: 'openapi',
+                artifactId: 'OrdersAPI-OPENAPI',
+                version: 'latest',
+                // Use the OpenAPI generator to process the specification
+                generator: ['@eventcatalog/generator-openapi', {
+                  // Pass options to the OpenAPI generator if needed
+                }]
+              },
+              {
+                type: 'asyncapi',
+                artifactId: 'OrdersEvents-ASYNCAPI',
+                version: '2.0.0',
+                // Use the AsyncAPI generator to process the specification
+                generator: ['@eventcatalog/generator-asyncapi', {
+                  // Pass options to the AsyncAPI generator if needed
+                }]
+              }
+            ],
+            // You can also assign schemas directly
+            sends: [{ events: { prefix: 'order-' }}],
+            receives: [{ commands: ['place-order', 'cancel-order']}],
+          }
+        ],
+        domain: {
+          id: 'orders',
+          name: 'Orders',
+          version: '1.0.0',
+        }
+      }
+    ]
+  ],
+};
+```
+
+:::tip
+When using nested generators, make sure to:
+1. Install the respective plugins:
+```bash
+npm install @eventcatalog/generator-openapi @eventcatalog/generator-asyncapi
+```
+2. Obtain an EventCatalog Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud) (30-day free trial available)
+3. Add the license key to your `.env` file:
+```bash
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+See [OpenAPI Plugin Docs](/docs/plugins/openapi/intro) | [AsyncAPI Plugin Docs](/docs/plugins/asyncapi/intro) for more information.
+:::
+
+</details>
+
+<details>
+<summary>Example configuration - Service relationships with writesTo and readsFrom</summary>
+
+In this example we document service-to-service relationships using `writesTo` and `readsFrom` to show how services interact with each other.
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-apicurio',
+      {
+        // The URL of your Apicurio Registry
+        registryUrl: 'http://localhost:8080',
+        // The services to assign schemas to
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            sends: [{ events: { prefix: 'order-' }}],
+            receives: [{ commands: ['place-order', 'cancel-order']}],
+            // This service writes to Inventory Service and Notifications Service
+            writesTo: [
+              { id: 'Inventory Service', version: '1.0.0' },
+              { id: 'Notifications Service', version: '1.0.0' }
+            ]
+          },
+          {
+            id: 'Inventory Service',
+            version: '1.0.0',
+            sends: [{ events: { prefix: 'inventory-' }}],
+            // This service reads from Orders Service
+            readsFrom: [
+              { id: 'Orders Service', version: '1.0.0' }
+            ]
+          },
+          {
+            id: 'Notifications Service',
+            version: '1.0.0',
+            receives: [{ events: ['order-placed', 'order-cancelled']}],
+            // This service reads from Orders Service
+            readsFrom: [
+              { id: 'Orders Service', version: '1.0.0' }
+            ]
+          }
+        ],
+        domain: {
+          id: 'orders',
+          name: 'Orders',
+          version: '1.0.0',
+        }
+      }
+    ]
+  ],
+};
+```
+
+This configuration will create service relationships in EventCatalog, making it easier to visualize and understand how services communicate with each other.
+
+</details>
+
+<details>
+<summary>Example configuration - Multiple domains with version management</summary>
+
+In this example we configure the plugin multiple times to document different domains, and we use `includeAllVersions` to track schema evolution.
+
+:::info "Why configure the plugin multiple times?"
+The generator can be configured as many times as you want.
+In this example we configure the plugin twice, once for each domain.
+:::
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    // Retail domain
+    [
+      '@eventcatalog/generator-apicurio',
+      {
+        registryUrl: 'http://localhost:8080',
+        includeAllVersions: true,
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            sends: [{ events: { prefix: 'order-' }}],
+            receives: [{ commands: ['place-order', 'cancel-order']}],
+          },
+          {
+            id: 'Inventory Service',
+            version: '1.0.0',
+            sends: [{ events: { prefix: 'inventory-' }}],
+            receives: [{ events: { prefix: 'order-' }}],
+          },
+        ],
+        domain: {
+          id: 'retail',
+          name: 'Retail',
+          version: '1.0.0',
+        }
+      },
+    ],
+    // Communications domain
+    [
+      '@eventcatalog/generator-apicurio',
+      {
+        registryUrl: 'http://localhost:8080',
+        includeAllVersions: true,
+        services: [
+          {
+            id: 'Notifications Service',
+            version: '1.0.0',
+            receives: [
+              { events: ['user-registered']},
+              { events: ['order-placed']},
+              { events: ['shipment-created']},
+            ],
+          },
+        ],
+        domain: {
+          id: 'communications',
+          name: 'Communications',
+          version: '1.0.0',
+        }
+      },
+    ],
+  ],
+};
+```
+
+</details>
+
+## Need help?
+
+If you have questions or need help, you can join our [Discord community](https://eventcatalog.dev/discord)
+or refer to the [Apicurio Registry examples on GitHub](https://github.com/event-catalog/generators/tree/main/examples/generator-apicurio).
diff --git a/packages/core/docs/plugins/apicurio/03-features.md b/packages/core/docs/plugins/apicurio/03-features.md
new file mode 100644
index 000000000..93d4cfdd3
--- /dev/null
+++ b/packages/core/docs/plugins/apicurio/03-features.md
@@ -0,0 +1,221 @@
+---
+sidebar_position: 1
+keywords:
+- apicurio
+- features
+sidebar_label: Features
+title: Features
+description: Features of Apicurio Registry with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+## Schema Version Management
+
+### Track All Schema Versions
+
+The Apicurio Registry plugin supports comprehensive schema version management through the `includeAllVersions` configuration option.
+
+When `includeAllVersions` is set to `true`, the plugin will:
+- Import all versions of each schema from your Apicurio Registry
+- Create versioned entries in EventCatalog for each schema version
+- Maintain version history for your schemas
+- Allow you to view and compare different versions
+
+When `includeAllVersions` is set to `false` (default):
+- Only the latest version of each schema is imported
+- This is useful for keeping your catalog focused on current schemas
+
+**Example:**
+
+```js
+{
+  registryUrl: 'http://localhost:8080',
+  includeAllVersions: true, // Import all versions
+}
+```
+
+**Use cases for version tracking:**
+- Understanding schema evolution over time
+- Maintaining backwards compatibility documentation
+- Tracking breaking changes in your schemas
+- Compliance and audit requirements
+
+### Adding Semantic Meaning to Schemas
+
+Using the Apicurio Registry plugin, you can import your schemas and then add business context and semantic meaning to them.
+
+When you import a schema into EventCatalog, an event, command, or query will be created with the schema attached. Each message has its own `index.mdx` file where you can add:
+- Title and summary
+- Detailed descriptions
+- Business context and use cases
+- Custom components and visualizations
+- Ownership and team information
+
+This gives you the opportunity to add meaning to your schemas and make them easier to understand for teams across your organization.
+
+**Important:** When you reimport your schemas, your semantic meaning will persist between imports. The plugin will:
+- Download the latest version of the schema from Apicurio Registry
+- Update the schema file in EventCatalog
+- Preserve your markdown documentation and business context
+
+## Integration with OpenAPI and AsyncAPI Generators
+
+One of the powerful features of the Apicurio Registry plugin is its ability to work with other EventCatalog generators.
+
+You can store OpenAPI and AsyncAPI specifications in your Apicurio Registry and use them to generate comprehensive service documentation automatically.
+
+:::info EventCatalog Scale License Required
+The OpenAPI and AsyncAPI generators require an EventCatalog Scale license key. You can get a 30-day free trial from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+See the [OpenAPI Plugin](/docs/plugins/openapi/intro) and [AsyncAPI Plugin](/docs/plugins/asyncapi/intro) documentation for more details on installation and configuration.
+:::
+
+### How it works
+
+1. Store your OpenAPI/AsyncAPI specifications in Apicurio Registry
+2. Configure the Apicurio plugin to attach these specifications to services
+3. Specify which EventCatalog generator should process each specification
+4. The plugin will fetch the specification and run the appropriate generator
+
+### Benefits
+
+- **Centralized Storage**: Keep all your schemas and specifications in one place (Apicurio Registry)
+- **Automated Documentation**: Generate service documentation from specifications automatically
+- **Consistent Workflow**: Use the same import process for schemas and specifications
+- **Domain Awareness**: Specifications inherit domain configuration from the Apicurio plugin
+
+### Example Configuration
+
+```js
+services: [{
+  id: 'Orders Service',
+  version: '1.0.0',
+  specifications: [
+    {
+      type: 'openapi',
+      artifactId: 'OrdersAPI-OPENAPI',
+      version: 'latest',
+      generator: ['@eventcatalog/generator-openapi', {
+        // OpenAPI generator options
+      }]
+    },
+    {
+      type: 'asyncapi',
+      artifactId: 'OrdersEvents-ASYNCAPI',
+      version: '2.0.0',
+      generator: ['@eventcatalog/generator-asyncapi', {
+        // AsyncAPI generator options
+      }]
+    }
+  ]
+}]
+```
+
+This configuration will:
+1. Fetch the OpenAPI specification from Apicurio Registry
+2. Save it to the service directory
+3. Run the OpenAPI generator to document REST endpoints
+4. Fetch the AsyncAPI specification
+5. Run the AsyncAPI generator to document async events
+6. All within the context of the Orders Service and its domain
+
+## Flexible Filtering System
+
+The Apicurio Registry plugin provides a powerful filtering system to control which schemas are assigned to services.
+
+### Filter Types
+
+- **Exact Matching**: Match schemas by exact artifact ID
+- **Prefix Matching**: Match schemas that start with a specific string
+- **Suffix Matching**: Match schemas that end with a specific string
+- **Includes Matching**: Match schemas that contain a specific string
+
+### Use Cases
+
+**Exact matching** is useful when you know the specific schemas a service interacts with:
+```js
+sends: [{ events: ['order-placed', 'order-cancelled'] }]
+```
+
+**Prefix matching** is useful for namespaced schemas:
+```js
+sends: [{ events: { prefix: 'order-' } }]
+// Matches: order-placed, order-cancelled, order-updated, etc.
+```
+
+**Suffix matching** is useful for schema naming conventions:
+```js
+receives: [{ commands: { suffix: '-command' } }]
+// Matches: place-order-command, cancel-order-command, etc.
+```
+
+**Includes matching** is useful for flexible pattern matching:
+```js
+receives: [{ events: { includes: 'inventory' } }]
+// Matches: inventory-updated, check-inventory, inventory-low, etc.
+```
+
+## Message Type Classification
+
+Document your schemas with semantic meaning by classifying them as:
+
+- **Events**: Things that have happened (past tense) - e.g., `order-placed`, `user-registered`
+- **Commands**: Requests to do something (imperative) - e.g., `place-order`, `cancel-order`
+- **Queries**: Requests for information - e.g., `get-order-status`, `find-user`
+
+This classification helps teams understand the intent and purpose of each message in your architecture.
+
+```js
+services: [{
+  id: 'Orders Service',
+  sends: [
+    { events: ['order-placed', 'order-cancelled'] }
+  ],
+  receives: [
+    { commands: ['place-order', 'cancel-order'] },
+    { queries: ['get-order-status'] }
+  ]
+}]
+```
+
+## Authentication Support
+
+<AddedIn version="0.1.0" />
+
+The Apicurio Registry plugin supports Bearer token authentication for secured registries.
+
+Simply set the `APICURIO_ACCESS_TOKEN` environment variable and the plugin will automatically include the Authorization header in all requests:
+
+```bash
+# .env file
+APICURIO_ACCESS_TOKEN=your-access-token-here
+```
+
+The plugin handles authentication transparently - all API requests will include the Bearer token when the environment variable is set.
+
+## Visualize Schemas, Services and Domains
+
+When you import your schemas into EventCatalog and assign them to services, you can use the EventCatalog Visualizer to see exactly how your schemas, services and domains are connected.
+
+The visualizer helps you:
+- Understand message flow between services
+- Identify dependencies and relationships
+- See your domain boundaries
+- Navigate your event-driven architecture visually
+
+## Downloading Schemas
+
+EventCatalog supports any schema format (Avro, JSON Schema, Protobuf, etc.). When you import your schemas from Apicurio Registry you can:
+- View the schema directly in EventCatalog
+- Download the schema for local development
+- See schema metadata and version information
+- Compare different versions of the same schema
+
+## Missing a Feature?
+
+If you are missing a feature, please let us know by opening an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or joining our [Discord community](https://eventcatalog.dev/discord).
+
+## Examples
+
+See the [eventcatalog-apicurio-example](https://github.com/event-catalog/generators/tree/main/examples/generator-apicurio) for working examples.
diff --git a/packages/core/docs/plugins/apicurio/04-examples.md b/packages/core/docs/plugins/apicurio/04-examples.md
new file mode 100644
index 000000000..a0a881cef
--- /dev/null
+++ b/packages/core/docs/plugins/apicurio/04-examples.md
@@ -0,0 +1,20 @@
+---
+sidebar_position: 1
+keywords:
+- apicurio
+- examples
+sidebar_label: Examples
+title: Examples
+description: Examples of using the Apicurio Registry plugin
+---
+
+## Community Examples
+
+Have you created an example using the Apicurio Registry plugin? Share it with the community by opening a PR on [GitHub](https://github.com/event-catalog/generators) or sharing it in our [Discord community](https://eventcatalog.dev/discord).
+
+## Need Help?
+
+If you need help with any of these examples or have questions, please:
+- Join our [Discord community](https://eventcatalog.dev/discord)
+- Open an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues)
+- Check out the [plugin configuration documentation](/docs/plugins/apicurio/plugin-configuration)
diff --git a/packages/core/docs/plugins/apicurio/_category_.json b/packages/core/docs/plugins/apicurio/_category_.json
new file mode 100644
index 000000000..befb7cf25
--- /dev/null
+++ b/packages/core/docs/plugins/apicurio/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Apicurio Registry Plugin",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "apicurio",
+    "title": "Apicurio Registry",
+    "description": "Apicurio Registry integration for EventCatalog"
+  }
+}
diff --git a/packages/core/docs/plugins/asyncapi/00-intro.md b/packages/core/docs/plugins/asyncapi/00-intro.md
new file mode 100644
index 000000000..622d13c81
--- /dev/null
+++ b/packages/core/docs/plugins/asyncapi/00-intro.md
@@ -0,0 +1,81 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Introduction
+description: Getting started with AsyncAPI plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<AddedIn version="2.5.0"/>
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/XglwSNAnpKY?si=CtM_M0odLSPB8nhY" 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>
+
+---
+
+Many folks building event-driven architectures are using and defining [AsyncAPI](https://www.asyncapi.com/en) files. The files are used to describe the service, it's messages it sends and receives and channels it uses to communicate.
+
+Using the EventCatalog AsyncAPI generator you can generate and maintain your EventCatalog.
+
+:::tip Try it now
+Want to see what your AsyncAPI file looks like in EventCatalog? [Try the playground](https://try.eventcatalog.dev) — drop your file and see the result in seconds.
+:::
+
+
+:::info
+**What is AsyncAPI?**: An industry standard for defining asynchronous APIs. Use this specification to document your service, channels and messages.
+:::
+
+### Core Features
+
+The EventCatalog AsyncAPI plugin can provide you with many features:
+
+- ⭐️ Generate domains, services and messages into your catalog from your AsyncAPI specification files
+- ⭐️ [Automate your EventCatalog and fetch AsyncAPI files by URL](/docs/plugins/asyncapi/features#fetch-asyncapi-files-by-url)
+- ⭐️ [Map commands, queries and events from your OpenAPI file using custom extensions](/docs/plugins/asyncapi/features#mapping-messages-events-commands-or-queries)
+- ⭐️ [Automatically version your changes in EventCatalog in sync with your AsyncAPI versions](#automatic-versioning)
+- ⭐️ [Allow you to write and persist custom markdown between changes](#persist-markdown)
+- ⭐️ [Display your message schemas in the catalog](#downloading-schemas)
+- ⭐️ [Fetch AsyncAPI files from any URL](#fetch-asyncapi-files-by-url)
+- ⭐️ Ability to download your message schemas and AsyncAPI files (also versioned)
+- ⭐️ Ability to draft services and endpoints in EventCatalog from your AsyncAPI files
+- ⭐️ and more....
+
+### How it works
+
+![Example](/img/integrations/asyncapi/asyncapi.jpeg)
+
+EventCatalog supports [generators](/docs/plugins/generators). These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an [SDK](/docs/sdk) to give developers easier access to their catalogs through custom scripts or generators.
+
+The EventCatalog AsyncAPI plugin let's you define 1 or many AsyncAPI files. When running the generate command the scripts populate your eventcatalog. You can choose how your AsyncAPI services are added to EventCatalog and which domain they belong to.
+
+## Commercial and License
+
+This plugin requires an EventCatalog Scale license key to be used.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial, you can continue using this plugin with EventCatalog Scale. 
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## License FAQ
+
+### What is the license key for?
+The EventCatalog Scale license key is required to use the OpenAPI plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get an EventCatalog Scale license key?
+You can obtain an EventCatalog Scale license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 30-day free trial.
+
+### Terms
+- **Trial Period**: 30-day free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can continue with EventCatalog Scale through [EventCatalog Cloud](https://eventcatalog.cloud).
diff --git a/packages/core/docs/plugins/asyncapi/01-installation.md b/packages/core/docs/plugins/asyncapi/01-installation.md
new file mode 100644
index 000000000..8a32ec93d
--- /dev/null
+++ b/packages/core/docs/plugins/asyncapi/01-installation.md
@@ -0,0 +1,154 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog AsyncAPI
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog AsyncAPI plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PluginLicense url="#commercial-use" />
+
+The AsyncAPI plugin is used to generate a catalog from an AsyncAPI specification files.
+
+You can map your AsyncAPI files to commands, events and queries in your catalog, and assign these to services and domains.
+
+## Installation
+
+Run the command below to install the EventCatalog AsyncAPI plugin.
+
+<Tabs>
+  <TabItem value="apple" label="Install on existing catalog" default>
+    ```bash
+npm i @eventcatalog/generator-asyncapi
+```
+  </TabItem>
+  <TabItem value="orange" label="Create new catalog with AsyncAPI plugin">
+     ```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --template asyncapi
+```
+  </TabItem>
+</Tabs>
+
+#### Configuration
+
+Configure the plugin in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators` array.
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  // Add single AsyncAPI file to a domain
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: "Orders Service"}
+      ],
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+
+      // Run in debug mode, for extra output, if your AsyncAPI fails to parse, it will tell you why
+      debug: true
+    },
+  ],
+  // Add many AsyncAPI files to a domain
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        // Add AsyncAPI file by URL
+        { path: "https://raw.githubusercontent.com/event-catalog/eventcatalog-asyncapi-example/refs/heads/main/asyncapi-files/payment-service.yml", id: "Payment Service"}
+        // Add AsyncAPI file using file system
+        { path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml'), "Fraud Service"}
+      ],
+      domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
+      // Run in debug mode, for extra output, if your AsyncAPI fails to parse, it will tell you why
+      debug: true
+    },
+  ],
+],
+};
+
+```
+
+### Configure license key
+
+The EventCatalog AsyncAPI plugin requires an EventCatalog Scale license key to work with EventCatalog.
+
+You can get a trial Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+You have a few options for setting the license key:
+
+1. [Setting license key in `.env` file (recommended)](#setting-license-key-in-env-file-recommended)
+2. [Setting license key in eventcatalog.config.js](#setting-license-key-in-eventcatalogconfigjs)
+
+#### 1. Setting license key in `.env` file (recommended) {#setting-license-key-in-env-file-recommended}
+
+<AddedIn version="2.35.4" />
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+:::tip Using an Older API Key?
+
+If you already have an older AsyncAPI plugin key, you can still use it with the AsyncAPI-specific environment variable.
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_ASYNCAPI=your-license-key
+```
+
+:::
+
+#### 2. Setting license key in eventcatalog.config.js {#setting-license-key-in-eventcatalogconfigjs}
+
+If you prefer, you can set the license key in the `eventcatalog.config.js` file
+using the `licenseKey` property in the EventCatalog AsyncAPI plugin.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-asyncapi',
+      {
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_SCALE_LICENSE_KEY
+      },
+    ],
+  ],
+};
+```
+
+#### White listing EventCatalog domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+#### Run the plugin
+
+_This command will run the generators in your eventcatalog.config.js file._
+
+```
+npm run generate
+```
+
+#### View your catalog
+
+Run your catalog locally to see the changes
+
+```
+npm run dev
+```
+
+## Any questions or need help?
+
+If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
+
+
diff --git a/packages/core/docs/plugins/asyncapi/02-plugin-configuration.md b/packages/core/docs/plugins/asyncapi/02-plugin-configuration.md
new file mode 100644
index 000000000..e404f21e9
--- /dev/null
+++ b/packages/core/docs/plugins/asyncapi/02-plugin-configuration.md
@@ -0,0 +1,312 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog AsyncAPI plugin
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog AsyncAPI plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Plugin Configuration
+
+## Overview
+
+The EventCatalog AsyncAPI plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+## Required Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `services` | `Service[]` | Yes | List of AsyncAPI files to add to your catalog |
+| `licenseKey` | string | Yes* | EventCatalog Scale license key. Get a 30-day trial at [EventCatalog Cloud](https://eventcatalog.cloud). Can also be set via the `EVENTCATALOG_SCALE_LICENSE_KEY` environment variable. |
+
+### Service Configuration
+
+Each service in the `services` array requires the following properties:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | string | Yes | EventCatalog ID for the service. |
+| `path` | string | Yes | Path to your AsyncAPI file or remote URL to the AsyncAPI file |
+| `version` | string | No | Version for the generated EventCatalog service. If not provided, the version from the AsyncAPI `info.version` field is used. Messages and channels default to this version unless overridden by `x-eventcatalog-message-version` or `x-eventcatalog-channel-version`. |
+| `name` | string | No | Display name for the service. If not provided, the specification will be used. _Added in v4.5.3_|
+| `summary` | string | No | Short summary of the service. If not provided, the specification will be used. _Added in v4.5.3_|
+| `owners` | string[] | No | Owners of the service. You can assign EventCatalog users or teams to services. Setting owners on the service will also set the owners of the messages in the AsyncAPI file. If owners are already set on any resource, those owners are persisted. |
+| `generateMarkdown` | function | - | Function to override the default markdown generation for the service. See [Markdown templates](#markdown-templates) for more information. |
+| `writesTo` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service writes to. (Added in v4.5.4) |
+| `readsFrom` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service reads from. (Added in v4.5.4) |
+| `headers` | `Record<string, string>` | No | HTTP headers for authenticated remote URLs (e.g., `{ Authorization: 'Bearer token' }`). Used when fetching AsyncAPI files from URLs that require authentication. |
+
+## Optional Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `domain` | object | - | Domain to associate all configured services with |
+| `domain.id` | string | - | Domain identifier |
+| `domain.name` | string | - | Domain display name |
+| `domain.version` | string | - | Domain version |
+| `domain.owners` | string[] | - | Owners of the domain. If owners are already set on the domain, those owners are persisted. |
+| `domain.generateMarkdown` | function | - | Function to override the default markdown generation for the domain. See [Markdown templates](#markdown-templates) for more information. |
+| `messages.generateMarkdown` | function | - | Function to override the default markdown generation for the message. See [Markdown templates](#markdown-templates) for more information. |
+| `messages.id` | object | - | Configure the id of the messages that are generated (for example, set a prefix to all messages that are generated) _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/features#adding-prefix-to-all-messages) |
+| `messages.id.prefix` | string | - | A prefix value for the message that is generated. For example a message with the id `orderPlaced` with a configured prefix of `hello-` will be `hello-orderPlaced`. _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/plugin-configuration#adding-prefix-to-all-messages) |
+| `messages.id.separator` | string | `-` | The separator to use between the prefix and the message id. _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/plugin-configuration#adding-prefix-to-all-messages) |
+| `messages.id.prefixWithServiceId` | boolean | | If true, the service id will be added to the id of the messages that are generated. For example a message with the id `orderPlaced` and the service id `orders-service` will be `orders-service-orderPlaced`. _(Added in v4.5.1)_ [(Read more)](/docs/plugins/asyncapi/plugin-configuration#adding-prefix-to-all-messages) |
+| `messages.id.lowerCase` | boolean | false | If true, the message id will be stored in lowercase and the folder will also be lowercased. (e.g `/events/orderplaced/index.mdx) _(Added in v5.0.0)_ |
+| `saveParsedSpecFile` | boolean | `false` | Parse and save expanded AsyncAPI spec (helpful for files with $refs) |
+| `parseSchemas` | boolean | `true` | If you choose to parse your specification file using the [saveParsedSpecFile](#saveparsedspecfile-saveparsedspecfile) field, you can also opt in or out to have your ,message schemas parsed using the `parseSchemas` field. By default message schemas are parsed, if you want to keep your original schemas you have to set `parseSchemas` to false. | | `parseChannels` | boolean | `false` | Parse and save channels. If you set to true the AsyncAPI channels will also be documented in the catalog. |
+| `parseChannels` | boolean | `false` | When setting the value to true the generator will parse and write channels to your EventCatalog. |
+| `writeFilesToRoot` | boolean | `false` | Write AsyncAPI messages to root instead of service folder. By default all domains, services and messages will be grouped in the folder directory structure. |
+| `saveParsedSpecFile` | boolean | `true` | By default your AsyncAPI file will render in your catalog as you define it. If you are using $refs, or having issues seeing your AsyncAPI file in your catalog, then you can set this value to true. `saveParsedSpecFile`  is false by default. |
+| `attachHeadersToSchema` | boolean | `false` | When enabled, combines message headers and payload into a single schema with `headers` and `payload` properties. Only applies to messages using JSON schema format. _(Added in v5.5.1)_ [(Read more)](/docs/plugins/asyncapi/features#attach-headers-to-schema) |
+| `parseExamples` | boolean | `true` | Parse message examples from AsyncAPI files and write each payload as a `.json` file to the message's `examples` folder. Named examples use `{name}.json`; unnamed examples fall back to `example-{index}.json`. Set to `false` to disable. _(Added in v6.1.0)_ [(Read more)](/docs/plugins/asyncapi/features#parse-message-examples) |
+| `debug` | boolean | `false` | Enable debug mode |
+
+## Example Configuration
+
+```js title="eventcatalog.config.js"
+import path from "path";
+import url from "url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  cId: "10b46030-5736-4600-8254-421c3ed56e47",
+  title: "MetaRetail Inc",
+  tagline: "Fake Retail Company for EventCatalog Demo",
+  organizationName: "MetaRetail Inc",
+  homepageLink: "https://eventcatalog.dev/",
+  editUrl: "https://github.com/boyney123/eventcatalog-demo/edit/master",
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: "/",
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: "EventCatalog Logo",
+    src: "/logo.png",
+    text: "MetaRetail Inc",
+  },
+  docs: {
+    sidebar: {
+      // Should the sub heading be rendered in the docs sidebar?
+      showPageHeadings: true,
+    },
+  },
+  generators: [
+    [
+      '@eventcatalog/generator-asyncapi',
+      {
+        services: [
+          { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'Orders Service', version: '1.0.0' },
+          { path: path.join(__dirname, 'asyncapi-files', 'order-fulfillment-service.yml'), id: 'Order Fulfillment' },
+          { path: path.join(__dirname, 'asyncapi-files', 'inventory-service.yml'), id: 'Inventory Service' },
+        ],
+        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+      },
+    ],
+    [
+      '@eventcatalog/generator-asyncapi',
+      {
+        services: [
+          // Add AsyncAPI file by public URL
+          { path: "https://raw.githubusercontent.com/event-catalog/eventcatalog-asyncapi-example/refs/heads/main/asyncapi-files/payment-service.yml", id: "Payment Service"},
+          // Add AsyncAPI file by file system
+          { path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml'), id: 'Fraud Detection' },
+        ],
+        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
+      },
+    ],
+    [
+      '@eventcatalog/generator-asyncapi',
+      {
+        services: [
+          { path: path.join(__dirname, 'asyncapi-files', 'user-service.yml'), id: 'User Service' },
+        ],
+        domain: { id: 'user-domain', name: 'User Domain', version: '0.0.1' },
+        debug: true
+      },
+    ],
+  ],
+};
+```
+
+You can view an example configuration in the [EventCatalog AsyncAPI plugin GitHub repository](https://github.com/event-catalog/generators/blob/main/examples/generator-asyncapi/basic/eventcatalog.config.js).
+
+## Markdown templates
+
+<AddedIn version="4.3.0" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+The EventCatalog AsyncAPI plugin will generate default markdown for each domain, service and message.
+
+If you want more control, you can override these using your own **markdown templates**.
+
+To use your own markdown templates you need to provide a function that returns the markdown for the domain, service or message.
+
+Below you can see examples of how to override the default markdown for the domain, service and message.
+
+<Tabs>
+  <TabItem value="Domain Markdown Template">
+
+  #### Domain
+
+  In this example we will override the default markdown for the domain using our custom function. We will also preserve the default markdown for the domain.
+
+```js title="eventcatalog.config.js"
+// function to generate the markdown for the domain
+// You can include this in your config file or in a separate file and import it
+const generateMarkdownForDomain = ({ domain, markdown }) => {
+  return `# ${domain.name}
+    This is the default markdown for the domain
+
+    You can add anything you want here, including components, tables, etc.
+
+    ## Architecture Diagram
+    <NodeGraph />
+
+    // Add the default markdown for the domain if you want to preserve it
+    ${markdown}
+  `;
+}
+
+// Your configuration
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-asyncapi',
+      {
+        // ...rest of generator config
+        domain: {
+          id: 'orders',
+          name: 'Orders',
+          version: '0.0.1',
+          generateMarkdown: generateMarkdownForDomain
+        }
+      }
+    ]
+  ]
+}
+```
+
+**Function Arguments:**
+
+| Argument | Type | Properties | Description |
+|----------|------|----------|-------------|
+| `domain` | object | `id`, `name`, `version` | The domain object you provided in the config |
+| `markdown` | string | - | The default markdown for the domain. Incase you want to preserve the default markdown you can use this argument to add to your own markdown. |
+
+
+  </TabItem>
+  <TabItem value="Service Markdown Template">
+
+  #### Service
+
+  In this example we will override the default markdown for the service using our custom function. We will also preserve the default markdown for the service.
+
+  ```js title="eventcatalog.config.js"
+  // function to generate the markdown for the service
+  // You can include this in your config file or in a separate file and import it
+  const generateMarkdownForService = ({ service, markdown, document }) => {
+    return `# ${service.name}
+      This is the default markdown for the service
+
+      ## Description
+      ${document.info.description ? `${document.info.description}` : ''}  
+    `;
+  }
+
+  // Your configuration
+  export default {
+    generators: [
+      [
+        '@eventcatalog/generator-asyncapi',
+        {
+          // ...rest of generator config
+          service: {
+            id: 'orders-service',
+            name: 'Orders Service',
+            version: '0.0.1',
+            generateMarkdown: generateMarkdownForService
+          }
+        }
+      ]
+    ]
+  }
+  ```
+
+  **Function Arguments:**
+
+  | Argument | Type | Properties | Description |
+  |----------|------|----------|-------------|
+  | `service` | object | `id`, `name`, `version` | The service object you provided in the config |
+  | `markdown` | string | - | The default markdown for the service. Incase you want to preserve the default markdown you can use this argument to add to your own markdown. |
+  | `document` | object | AsyncAPI.Document | The AsyncAPI document object. |
+
+
+  </TabItem>
+  <TabItem value="Message Markdown Template">
+
+  #### Message
+
+  In this example we will override the default markdown for the message using our custom function. We will also preserve the default markdown for the message.
+
+  ```js title="eventcatalog.config.js"
+  // function to generate the markdown for the message
+  // You can include this in your config file or in a separate file and import it
+  const generateMarkdownForMessage = ({ message, markdown, document }) => {
+    return `# ${message.name}
+      This is the default markdown for the message
+    `;
+  }
+
+  // Your configuration
+  export default {
+    generators: [
+      [
+        '@eventcatalog/generator-asyncapi',
+        {
+          // ...rest of generator config
+          messages: {
+            generateMarkdown: generateMarkdownForMessage
+          }
+        }
+      ]
+    ]
+  }
+  ```
+
+  **Function Arguments:**
+
+  | Argument | Type | Properties | Description |
+  |----------|------|----------|-------------|
+  | `document` | object | AsyncAPI.Message | The AsyncAPI message object. |
+  | `document` | object | AsyncAPI.Document | The AsyncAPI document object. |
+  | `markdown` | string | - | The default markdown for the message. Incase you want to preserve the default markdown you can use this argument to add to your own markdown. |
+
+  </TabItem>
+</Tabs>
+
+
+## Need help?
+
+If you have questions or need help, you can join our [Discord community](https://eventcatalog.dev/discord)
+or refer to the [AsyncAPI examples on GitHub](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi).
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/core/docs/plugins/asyncapi/03-features.md b/packages/core/docs/plugins/asyncapi/03-features.md
new file mode 100644
index 000000000..702ade16c
--- /dev/null
+++ b/packages/core/docs/plugins/asyncapi/03-features.md
@@ -0,0 +1,698 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Features
+title: Features
+description: Features of AsyncAPI with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<!-- Table -->
+| Feature | Use cases |
+|---------|-----------|
+| [Mapping messages events, commands or queries](#mapping-messages-events-commands-or-queries) | AsyncAPI does not distinguish between commands, events and queries, everything is a message. Using the EventCatalog custom AsyncAPI [extension](https://www.asyncapi.com/docs/concepts/asyncapi-document/extending-specification) `x-eventcatalog-message-type` you can specify if your messages are events, command or queries. |
+| [Defining message ownership roles](#defining-message-ownership-roles) | AsyncAPI specification files do not define who owns the message and it's contract. Your AsyncAPI file my define messages your service consumes and produces but that service may not be the service that owns it's contract. (e.g An order service that consumes a Payment event. The order service (AsyncAPI file) would specify it consumes the payment event, but it is not the owner of the contract or event). |
+| [Defining message versions](#defining-message-versions) | In EventCatalog you can version your domains, services and all your messages. This can be useful as you can specify which version of a message your service produces or consumes. |
+| [Mapping channels into EventCatalog](#mapping-channels-into-eventcatalog) | EventCatalog supports [Channels](/docs/development/guides/resources/messages/message-channels/introduction) ([see demo](https://demo.eventcatalog.dev/docs/channels/inventory.%7Benv%7D.events/1.0.0)). This let's you document how messages or organized and transported in your event-driven architecture. |
+| [Creating draft domains, services and messages](#creating-draft-domains-services-and-messages) | You can create draft domains, services and messages in EventCatalog from your AsyncAPI files. This will be used to mark the resources as draft in EventCatalog. |
+| [Persist markdown](#persist-markdown) | When you generate your AsyncAPI files your markdown on your domains,services, and messages in EventCatalog is persisted between versions. This allows you to add [custom components](/docs/components/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when you version your AsyncAPI files. |
+| [Fetch AsyncAPI files by URL](#fetch-asyncapi-files-by-url) | You can use the `path` property of the generator to specify a path to your local file system or an external URL, or you can mix both of them. |
+| [Authenticate remote URLs](#authenticate-remote-urls) | Use HTTP headers to access protected AsyncAPI files from authenticated URLs. |
+| [Automatic versioning](#automatic-versioning) | When you change versions in your AsyncAPI file and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between AsyncAPI files, schemas and more. |
+| [Downloading schemas](#downloading-schemas) | If your messages have schemas (e.g avro, json) EventCatalog will document these for you. Run your generator and every message will show it's schema on the UI and give users the ability to download it's schema. |
+| [Attach headers to schema](#attach-headers-to-schema) | Combine message headers and payload into a single schema with `headers` and `payload` properties. Useful when header metadata is part of the message contract. |
+| [Parse message examples](#parse-message-examples) | Automatically write message examples from your AsyncAPI file as `.json` files in the message's `examples` folder in EventCatalog. |
+| [AsyncAPI 3.1.0 support](#asyncapi-310-support) | Use AsyncAPI specification files up to version 3.1.0 without any extra configuration. |
+| [Group messages](#group-messages) | Group related messages together in the visualiser for easier navigation of large APIs. |
+
+### Mapping messages events, commands or queries
+
+AsyncAPI does not distinguish between commands, events and queries, everything is a message. 
+
+Using the EventCatalog custom AsyncAPI [extension](https://www.asyncapi.com/docs/concepts/asyncapi-document/extending-specification) `x-eventcatalog-message-type` you can specify if your messages are events, command or queries.
+
+You can use the `x-eventcatalog-message-type` to specify the type of message. 
+
+By default everything parsed by EventCatalog is an event, unless you specify with the x-eventcatalog-message-type extension.
+
+```js title="x-eventcatalog-message-type example"
+components:
+  messages:
+    OrderCreated:
+      description: 'Event triggered when an order is created'
+      x-eventcatalog-message-type: event // event/query/command
+```
+
+You can see more [examples of the extension on the demo project](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/tree/main/asyncapi-files).
+
+### Defining message ownership roles
+
+<AddedIn version="2.4.0" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+AsyncAPI specification files do not define who owns the message and it's contract. Your AsyncAPI file my define messages your service consumes and produces but that service may not be the service that owns it's contract. (e.g An order service that consumes a Payment event. The order service (AsyncAPI file) would specify it consumes the payment event, but it is not the owner of the contract or event).
+
+By default when you integrate your AsyncAPI files into EventCatalog, EventCatalog will assume your service (AsyncAPI file) owns the messages and will document them this way.
+
+If you want to define ownership of messages in your files you can use the `x-eventcatalog-role` extension in your AsyncAPI files. This let's you specify if your service is a provider (owner) or the message or just a consumer (client) of the message.
+
+The available extension values are:
+
+- `provider`: Generator will generate a new message considering the service is the owner of message contract (`default`).
+- `client`: Generator will consider the message as a sent/received message in service but will NOT generate or modify the message in EventCatalog.
+
+```js title="x-eventcatalog-role example"
+components:
+  messages:
+    SendOrderConfirmation:
+      description: 'Command received to ask for sending an Order confirmation notification'
+      x-eventcatalog-role: client // Define the ownership. This example shows the service is a client of the message and does not own the message.
+```
+
+You can see more [examples of the extension on the demo project](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/tree/main/asyncapi-files).
+
+AsyncAPI specification files do not define who owns the message and it's contract. Your AsyncAPI file my define messages your service consumes and produces but that service may not be the service that owns it's contract. (e.g An order service that consumes a Payment event. The order service (AsyncAPI file) would specify it consumes the payment event, but it is not the owner of the contract or event).
+
+By default when you integrate your AsyncAPI files into EventCatalog, EventCatalog will assume your service (AsyncAPI file) owns the messages and will document them this way.
+
+If you want to define ownership of messages in your files you can use the `x-eventcatalog-role` extension in your AsyncAPI files. This let's you specify if your service is a provider (owner) or the message or just a consumer (client) of the message.
+
+The available extension values are:
+
+- `provider`: Generator will generate a new message considering the service is the owner of message contract (`default`).
+- `client`: Generator will consider the message as a sent/received message in service but will NOT generate or modify the message in EventCatalog.
+
+```js title="x-eventcatalog-role example"
+components:
+  messages:
+    SendOrderConfirmation:
+      description: 'Command received to ask for sending an Order confirmation notification'
+      x-eventcatalog-role: client // Define the ownership. This example shows the service is a client of the message and does not own the message.
+```
+
+You can see more [examples of the extension on the demo project](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/tree/main/asyncapi-files).
+
+### Defining message versions
+
+<AddedIn version="2.4.2" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+In EventCatalog you can version your domains, services and all your messages. This can be useful as you can specify which version of a message your service produces or consumes.
+
+Using the AsyncAPI generator by default the messages that are generated all use the AsyncAPI version.
+
+In the example below the service `Account Service` will be documented using the version `1.0.0`. The `UserSignedUp` event will be documented as version `1.0.0` (taken from the AsyncAPI version).
+
+```yaml
+asyncapi: 3.0.0
+info:
+  title: Account Service
+  # This version is uses for your service and all messages
+  version: 1.0.0
+  description: This service is in charge of processing user signups
+  contact:
+    name: Awesome Team
+    url: https://example.com
+    email: support@asyncapi.org
+# rest of AsyncAPI file...
+UserSignedUp:
+  description: 'Sign up a user'
+  x-eventcatalog-message-version: 2.0.0
+  tags:
+    - name: 'New'
+      description: 'New event'
+  payload:
+    type: object
+    properties:
+      displayName:
+        type: string
+        description: Name of the user
+      email:
+        type: string
+        format: email
+        description: Email of the user    
+```
+
+#### Defining message versions
+
+If you want to version your messages separate from the AsyncAPI file you can use the `x-eventcatalog-message-version` extension.
+
+Using the `x-eventcatalog-message-version` extension you can specify individual message versions.
+
+In the example below the service `Account Service` will be documented using the version `1.0.0`. The `UserSignedUp` event will be documented as version `2.0.0`.
+
+
+```yaml
+asyncapi: 3.0.0
+info:
+  title: Account Service
+  # This version is uses for your service and all messages
+  version: 1.0.0
+  description: This service is in charge of processing user signups
+  contact:
+    name: Awesome Team
+    url: https://example.com
+    email: support@asyncapi.org
+# rest of AsyncAPI file...
+UserSignedUp:
+  description: 'Sign up a user'
+  # Here we set the version of this message to 2.0.0.
+  x-eventcatalog-message-version: 2.0.0
+  tags:
+    - name: 'New'
+      description: 'New event'
+  payload:
+    type: object
+    properties:
+      displayName:
+        type: string
+        description: Name of the user
+      email:
+        type: string
+        format: email
+        description: Email of the user
+# rest of AsyncAPI file...
+```
+
+`x-eventcatalog-message-version` is optional per message, by default the AsyncAPI version will be used per message unless you specify the `x-eventcatalog-message-version` version.
+
+### Mapping channels into EventCatalog
+
+<AddedIn version="2.7.0" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+EventCatalog supports [Channels](/docs/development/guides/resources/messages/message-channels/introduction) ([see demo](https://demo.eventcatalog.dev/docs/channels/inventory.%7Benv%7D.events/1.0.0)). This let's you document how messages or organized and transported in your event-driven architecture.
+
+![Example](../../../docs/development/guides/img/channels/channels-example.png)
+
+AsyncAPI also supports [documenting channels](https://www.asyncapi.com/docs/concepts/channel#main-content). These can be added using the `channels` object. ([see example](https://github.com/asyncapi/spec/blob/97ea47fc412c3c1b6259e897eb900c73a6141205/examples/streetlights-kafka-asyncapi.yml#L39)).
+
+Channels can give your developers more insights into how messages are transported between services (e.g producers and consumers). Channels support dynamic naming, protocol definition and can be assigned to messages.
+
+**Documenting channels is off by default** but you can turn this on using the `parseChannels` [flag in your generator](/docs/plugins/asyncapi/plugin-configuration).
+
+When `parseChannels` is `true`, channels are associated with the service via `sends`/`receives` using `to`/`from` pointers rather than being added directly to messages. Channel pointers include the version only when `x-eventcatalog-channel-version` is explicitly set on the channel; otherwise they default to `"latest"`.
+
+### Creating draft domains, services and messages
+
+<AddedIn version="4.4.0" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+You can create draft domains, services and messages in EventCatalog from your AsyncAPI files. 
+
+![Draft resources](../img/draft-resource.png)
+
+**Use case:**
+
+- You want to create a service in EventCatalog that is not yet implemented or going through feedback/design phase.
+- You want to introduce a new endpoint to your service, but warn users that it is not yet implemented or still in development or draft.
+- You want to introduce a whole new domain, but warn users everything in the domain is still in development or draft.
+
+**Getting started**
+
+You have a few options to create draft resources from your specification files.
+
+- `domain.draft` - If true, the domain will be drafted in EventCatalog with all it's services / messages.
+- `service.draft` - If true, the service will be drafted in EventCatalog with all it's endpoints / messages.
+
+You can also choose to use AsyncAPI extensions to create draft resources.
+
+- `x-eventcatalog-draft` - If true, the resource will be drafted in EventCatalog (e.g service and messages).
+
+<details>
+  <summary>Example of creating draft resources through domains (configuration)</summary>
+
+Setting the `draft` property to true will create a draft domain with all it's services and messages in EventCatalog.
+
+```js title="eventcatalog.config.js"
+// ..rest of file
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1', draft: true },
+      services: [
+        { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'orders-service', draft: true },
+      ],
+    },
+  ],
+],
+};
+```
+</details>
+<details>
+  <summary>Example of creating draft resources through services (configuration)</summary>
+
+Setting the `draft` property to true will create a draft service with all it's messages in EventCatalog.
+
+```js title="eventcatalog.config.js"
+// ..rest of file
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        { path: path.join(__dirname, 'openapi-files', 'orders-service.yml'), id: 'orders-service', draft: true },
+      ],
+    },
+  ],
+],
+};
+```
+
+In this example the **Orders Service** and all it's messages will be marked as draft in EventCatalog.
+</details>
+<details>
+  <summary>Example marking service as draft (AsyncAPI extension)</summary>
+
+Setting the `x-eventcatalog-draft` extension to true will mark the service as draft in EventCatalog.
+
+```yml title="x-eventcatalog-draft example"
+asyncapi: 3.0.0
+info:
+  title: Orders Service
+  version: 1.0.0
+  # Here we mark the service as draft
+  x-eventcatalog-draft: true
+# rest of AsyncAPI file...
+```
+
+In this example the **Orders Service** and all it's messages will be marked as draft in EventCatalog.
+
+</details>
+<details>
+  <summary>Example marking a message as draft (AsyncAPI extension)</summary>
+
+Setting the `x-eventcatalog-draft` extension on each message will mark the message as draft in EventCatalog.
+
+```yml title="x-eventcatalog-draft example"
+asyncapi: 3.0.0
+info:
+  title: Account Service
+  version: 1.0.0
+  description: This service is in charge of processing user signups
+channels:
+  userSignedup:
+    address: user/signedup
+    messages:
+      UserSignedUp:
+        $ref: '#/components/messages/UserSignedUp'
+operations:
+  sendUserSignedup:
+    action: send
+    channel:
+      $ref: '#/channels/userSignedup'
+    messages:
+      - $ref: '#/channels/userSignedup/messages/UserSignedUp'
+components:
+  messages:
+    UserSignedUp:
+      description: 'User signed up the application'
+      x-eventcatalog-message-type: event
+      # This will mark the message as draft in EventCatalog
+      x-eventcatalog-draft: true
+      tags:
+        - name: 'New'
+          description: 'New event'
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          displayName:
+            type: string
+            description: Name of the user
+          email:
+            type: string
+            format: email
+            description: Email of the user
+```
+
+In this example we mark the message `UserSignedUp` as draft but the service is not marked as draft in EventCatalog.
+
+This can be useful if you want to introduce a new message, but warn users that it is not yet implemented or still in development or draft.
+
+</details>
+
+
+#### Setting custom versions for channels
+
+EventCatalog supports versioning of channels. By default the version of the channel documented is the AsyncAPI version (you specify in the info object).
+
+If you want more flexibility and document your channels individually you can use the `x-eventcatalog-channel-version` extension.
+
+**Example of a channel with custom version**
+
+```yaml
+info:
+  title: Streetlights Kafka API
+  # Global version of this service (used by default)
+  version: 1.0.0
+channels:
+  lightingMeasured:
+    address: 'smartylighting.streetlights.1.0.event.{streetlightId}.lighting.measured'
+    bindings:
+      kafka:
+        topic: 'my-topic'
+        partitions: 3
+    title: 'Lighting Measured Channel'
+    summary: 'Inform about environmental lighting conditions of a particular streetlight.'
+    messages:
+      lightMeasured:
+        $ref: '#/components/messages/lightMeasured'
+    description: The topic on which measured values may be produced and consumed.
+    parameters:
+      streetlightId:
+        $ref: '#/components/parameters/streetlightId'
+    # The version of the channel
+    x-eventcatalog-channel-version: 2.0.0
+# AsyncAPI file contents...
+```
+
+When `parseChannels` is set to true, running the generate command will document your channels and all messages that are assigned to that channel.
+
+### Parsing $ref values and message schemas
+
+<AddedIn version="2.5.1" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+Your AsyncAPI file may have references to other files/schemas in it. When using this with EventCatalog it's recommended to use the [saveParsedSpecFile](/docs/plugins/asyncapi/plugin-configuration) field.
+
+Setting this value to true, will parse your specification file and remove any $ref values, as EventCatalog cannot parse $ref values when hosted in the project.
+
+When your AsyncAPI file is parsed, by default the schemas will also be parsed. If you want to keep them as they are you can also use the [parseSchemas](/docs/plugins/asyncapi/plugin-configuration) flag. Setting this to `false` will keep your schemas as they are.
+
+### Attach headers to schema
+
+<AddedIn version="5.5.1" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+When a message defines both headers and a payload, you can combine them into a single schema using `attachHeadersToSchema`. The resulting schema wraps both under `headers` and `payload` properties.
+
+This is useful when your consumers need to validate or inspect message headers alongside the payload, for example when Spring `__TypeId__` headers or routing metadata are part of the contract.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'orders-service' },
+      ],
+      attachHeadersToSchema: true,
+    },
+  ],
+],
+```
+
+Given an AsyncAPI message with headers and a JSON schema payload, the generated `schema.json` will look like this:
+
+```json title="schema.json (generated output)"
+{
+  "type": "object",
+  "properties": {
+    "headers": {
+      "type": "object",
+      "properties": {
+        "__TypeId__": {
+          "type": "string",
+          "description": "Spring Type Id Header"
+        }
+      }
+    },
+    "payload": {
+      "type": "object",
+      "properties": {
+        "orderId": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}
+```
+
+This option only applies to messages using JSON schema format. Messages with non-JSON schema formats (e.g. Avro) are not affected. If a message has no headers, the payload schema is written unchanged.
+
+### Parse message examples
+
+<AddedIn version="6.1.0" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+When `parseExamples` is enabled (the default), the generator reads any [examples](https://www.asyncapi.com/docs/reference/specification/v3.0.0#messageExampleObject) defined on your AsyncAPI messages and writes each payload to the message's `examples` folder in EventCatalog.
+
+Named examples use `{name}.json` as the filename. Unnamed examples fall back to `example-{index}.json` (e.g. `example-0.json`).
+
+```yaml title="AsyncAPI message with examples"
+components:
+  messages:
+    OrderCreated:
+      description: 'Triggered when an order is created'
+      x-eventcatalog-message-type: event
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+          total:
+            type: number
+      examples:
+        - name: basic-order
+          payload:
+            orderId: 'ord-123'
+            total: 49.99
+        - payload:
+            orderId: 'ord-456'
+            total: 0.00
+```
+
+Running the generator with the above file produces two example files for the `OrderCreated` message:
+
+- `examples/basic-order.json` (named example)
+- `examples/example-1.json` (unnamed, falls back to index)
+
+To disable example parsing, set `parseExamples` to `false` in your generator configuration:
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'orders-service' },
+      ],
+      parseExamples: false,
+    },
+  ],
+],
+```
+
+### Adding prefix to all messages
+
+<AddedIn version="4.5.1" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+If you want more control over the ids of the generated messages you can add a prefix to the id of the generated messages.
+
+<Tabs>
+  <TabItem value="prefix (with a string)">
+
+This will add a prefix to the id of the generated messages. For example a message with the id `orderPlaced` with a configured prefix of `hello-` will be `hello-orderPlaced`.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+      {
+        messages: { id: { prefix: 'hello' } },
+      },
+  ],
+],
+```
+</TabItem>
+  <TabItem value="prefix (with custom separator)">
+
+This will add a prefix to the id of the generated messages. For example a message with the id `orderPlaced` with a configured prefix of `hello-` and separator of `_` will be `hello_orderPlaced`.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+      { 
+        messages: { id: { prefix: 'hello', separator: '_' } },
+      },
+  ],
+],
+```
+</TabItem>
+  <TabItem value="prefix (with service id)">
+
+This will add the service id to the id of the generated messages. For example a message with the id `orderPlaced` and the service id `orders-service` will be `orders-service-orderPlaced`.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+      { 
+        messages: { id: { prefixWithServiceId: true } },
+      },
+  ],
+],
+```
+</TabItem>
+</Tabs>
+
+### Deprecating messages
+
+<AddedIn version="4.0.3" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+To mark messages as deprecated you can use the `x-eventcatalog-deprecated-date` and `x-eventcatalog-deprecated-message` extensions.
+
+```yml title="Deprecating a message using x-eventcatalog-deprecated-date and x-eventcatalog-deprecated-message"
+SignUpUser:
+  description: 'Sign up a user'
+  x-eventcatalog-message-type: command
+  x-eventcatalog-message-version: 2.0.0
+  # Date the message will be deprecated (YYYY-MM-DD)
+  x-eventcatalog-deprecated-date: 2025-04-09
+  # Message to show in the deprecation banner (optional)
+  x-eventcatalog-deprecated-message: This operation is deprecated because it is not used in the codebase
+  payload:
+    type: object
+    properties:
+      displayName:
+        type: string
+        description: Name of the user
+      email:
+        type: string
+        format: email
+        description: Email of the user
+```
+
+This will render a banner in EventCatalog indicating that the message will be deprecated on 2026-05-01.
+
+_Example of a deprecated resource in EventCatalog:_
+
+![Deprecated message](../../development/guides/img/deprecated/will-be-deprecated.png)
+
+
+### Persist markdown
+
+When you generate your AsyncAPI files your markdown on your domains,services, and messages in EventCatalog is persisted between versions.
+
+This allows you to add [custom components](/docs/components/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when you version your AsyncAPI files.
+
+### Fetch AsyncAPI files by URL
+
+<AddedIn version="2.3.0" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+You can use the `path` property of the generator to specify a path to your local file system or an external URL, or you can mix both of them.
+
+```js
+[
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        // Add AsyncAPI file by public URL
+        { path: "https://raw.githubusercontent.com/event-catalog/eventcatalog-asyncapi-example/refs/heads/main/asyncapi-files/payment-service.yml", id: "Payment Service"},
+        // Add AsyncAPI file using file system
+        { path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml'), "Fraud Service"}
+      ],
+      domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
+
+      // Run in debug mode, for extra output, if your AsyncAPI fails to parse, it will tell you why
+      debug: true,
+
+      // Parse and add channels to your eventcatalog from the AsyncAPI spec files
+      parseChannels: true
+    },
+  ],
+```
+
+### Authenticate remote URLs
+
+When fetching AsyncAPI files from authenticated URLs, provide HTTP headers using the `headers` property.
+
+This is useful for accessing private specifications from internal registries, API gateways, or other protected endpoints.
+
+```js
+[
+  '@eventcatalog/generator-asyncapi',
+  {
+    services: [
+      {
+        path: "https://api.example.com/specs/payment-service.asyncapi.yml",
+        id: "Payment Service",
+        headers: {
+          Authorization: 'Bearer your-api-token',
+          'X-Api-Key': 'your-api-key'
+        }
+      }
+    ],
+    domain: { id: 'payment', name: 'Payment', version: '0.0.1' }
+  }
+]
+```
+
+The headers are passed with every HTTP request when fetching the AsyncAPI file from the specified URL.
+
+### Automatic versioning
+
+When you change versions in your AsyncAPI file and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between AsyncAPI files, schemas and more.
+
+You can also add changelogs between different versions of your services and messages. [Read here for more information](/docs/development/guides/resources/messages/versioning-and-lifecycle/add-changelog).
+
+### Downloading schemas
+
+If your messages have schemas (e.g avro, json) EventCatalog will document these for you. Run your generator and every message will show it's schema on the UI and give users the ability to download it's schema.
+
+The service that is also generated will allow you to see and download the AsyncAPI file.
+
+### AsyncAPI 3.1.0 support
+
+<AddedIn version="6.0.0" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+The generator supports AsyncAPI specification files up to and including version 3.1.0. No extra configuration is needed; point the `path` property at your 3.1.0 file and the generator handles the rest.
+
+### Group messages
+
+<AddedIn version="6.4.0" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+When a service sends or receives many messages, the [visualiser](/docs/development/guides/resources/messages/connect-messages/group-messages) can become crowded. The `groupMessagesBy` option lets you automatically group related messages together so they collapse into a single node in the visualiser map, making your architecture easier to understand at a glance.
+
+![Message group expanded in the visualiser](./img/message-group-expanded.png)
+
+To learn more about how groups work in the visualiser, see [Grouping messages](/docs/development/guides/resources/messages/connect-messages/group-messages).
+
+Set `groupMessagesBy: 'x-extension'` in your generator config, then add `x-eventcatalog-group` to each message in your AsyncAPI components.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [{ path: './asyncapi.yml', id: 'my-service' }],
+      groupMessagesBy: 'x-extension',
+    },
+  ],
+],
+```
+
+```yaml title="asyncapi.yml"
+components:
+  messages:
+    ShipmentDispatched:
+      x-eventcatalog-group: Shipping
+      description: A shipment has been dispatched
+```
+
+When `parseChannels` is also enabled, group assignments and channel pointers are both preserved on the generated messages.
+
+:::tip
+Once grouped, messages appear as a compact stacked card in the visualiser. Click the group to expand it and see the full downstream graph — channels, consumers, and producers — just as if the messages were ungrouped. See [Grouping messages](/docs/development/guides/resources/messages/connect-messages/group-messages) for more details.
+:::
+
+### Example
+
+See the [eventcatalog-asyncapi-example](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi) for a working example.
diff --git a/packages/core/docs/plugins/asyncapi/03a-workflows.md b/packages/core/docs/plugins/asyncapi/03a-workflows.md
new file mode 100644
index 000000000..a37fcb996
--- /dev/null
+++ b/packages/core/docs/plugins/asyncapi/03a-workflows.md
@@ -0,0 +1,153 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Workflows  
+title: Workflows
+description: Workflows of AsyncAPI with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+There are a few ways to configure the AsyncAPI plugin depending on your preferred development workflows.
+Many companies have different needs, so we have provided a few different workflows to choose from.
+
+- [Simple mapping between AsyncAPI files and EventCatalog services](#simple-mapping-between-asyncapi-files-and-eventcatalog-services)
+  - Map a single AsyncAPI file to a single EventCatalog service
+- [Independent message versions from your AsyncAPI file](#independent-message-versions-from-your-asyncapi-file)
+  - Version your messages independently of the service version
+- [Mapping multiple AsyncAPI files to a single EventCatalog service](#mapping-multiple-asyncapi-files-to-a-single-eventcatalog-service)
+  - Map multiple AsyncAPI files to a single EventCatalog service
+- [Mapping AsyncAPI and OpenAPI files to the same EventCatalog service](#mapping-asyncapi-and-openapi-files-to-the-same-eventcatalog-service)
+  - Map an AsyncAPI and OpenAPI file to the same EventCatalog service
+
+_If we are missing a workflow that you think is useful, please raise an [issue on GitHub](https://github.com/event-catalog/generators/issues)._  
+
+## Simple mapping between AsyncAPI files and EventCatalog services
+
+This is the simplest workflow and is useful if you have a single AsyncAPI file per service.
+
+EventCatalog will parse your AsyncAPI file and map it's specification to the service you define. 
+
+This will document your service, and the messages it produces and consumes.
+
+```js title="eventcatalog.config.js"
+// ...rest of file
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        // Tell EventCatalog where the AsyncAPI file is located and map it to the service you define
+        { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'orders-service' },
+      ],
+    },
+  ],
+],
+```
+
+### Independent message versions from your AsyncAPI file
+
+This is useful if you want to version your messages separately from the AsyncAPI file.
+
+AsyncAPI currently does not support versioning messages separately from the AsyncAPI file, that's why you have to use the `x-eventcatalog-message-version` extension.
+
+You can use the `x-eventcatalog-message-version` extension to specify a different version for a particular message.
+
+```yaml
+asyncapi: 3.0.0
+info:
+  title: Orders Service
+  version: 1.0.0
+components:
+  messages:
+    OrderCreated:
+      description: 'Event triggered when an order is created'
+      # Specify the version of the message to 2.0.0
+      x-eventcatalog-message-version: 2.0.0
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            description: The ID of the order
+```
+
+In the example above, the message `OrderCreated` will be versioned as `2.0.0` and all other messages will be versioned as `1.0.0`.
+
+You can read more about message versioning in the [Features](/docs/plugins/asyncapi/features#defining-message-versions) section.
+
+## Mapping multiple AsyncAPI files to a single EventCatalog service
+
+This is useful if you have a single service that produces and consumes multiple AsyncAPI versions.
+
+Some people call this a "polyglot" service, as it produces and consumes multiple APIs.
+
+```js title="eventcatalog.config.js"
+// ...rest of file
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        // Version 1 of the AsyncAPI file
+        { path: path.join(__dirname, 'asyncapi-files', 'orders-service-v1.yml'), id: 'orders-service' },
+        // Version 2 of the AsyncAPI File
+        { path: path.join(__dirname, 'asyncapi-files', 'orders-service-v2.yml'), id: 'orders-service' },
+      ],
+    },
+  ],
+],
+```
+
+:::info Versioning
+When you map multiple versions of an AsyncAPI file to a single service, the `version` property in your AsyncAPI files needs to be the same.
+
+If they are different, EventCatalog will version the previous versions of your service.
+
+In the example above, the `version` property in the AsyncAPI files is `1.0.0` and `2.0.0`.
+
+EventCatalog will version the service as `1.0.0` and `2.0.0`.
+
+The messages in the service will be versioned as `1.0.0` and `2.0.0`.
+
+This allows you to track the history of your service and the messages in it.
+
+:::
+
+## Mapping AsyncAPI and OpenAPI files to the same EventCatalog service
+
+<AddedIn version="5.1.1" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+<AddedIn version="7.6.1" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+This is useful if you have a single service that produces and consumes both AsyncAPI and OpenAPI files.
+
+In this example we map an OpenAPI file and an AsyncAPI file to the same service (inventory-service). 
+
+The AsyncAPI and OpenAPI may have their own versions independent of each other, but EventCatalog will document both of them in the same service.
+
+:::tip Message Versioning
+You can still use the `x-eventcatalog-message-version` extension to version your messages independently of the service version.
+:::
+
+```js title="eventcatalog.config.js"
+// ...rest of file
+generators: [
+    [
+      "@eventcatalog/generator-openapi",
+      {
+        services: [
+          { path: path.join(__dirname, "specifications", "openapi.yml"), id: "inventory-service", version: "15.2.0" },
+        ],
+      },
+    ],
+    [
+      "@eventcatalog/generator-asyncapi",
+      {
+        services: [{ path: path.join(__dirname, "specifications", "asyncapi.yml"), id: "inventory-service", version: "15.2.0" }],
+      },
+    ],
+  ],
+```
\ No newline at end of file
diff --git a/packages/core/docs/plugins/asyncapi/04-examples.md b/packages/core/docs/plugins/asyncapi/04-examples.md
new file mode 100644
index 000000000..a204490f5
--- /dev/null
+++ b/packages/core/docs/plugins/asyncapi/04-examples.md
@@ -0,0 +1,23 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the AsyncAPI plugin
+---
+
+You can find many examples of using the AsyncAPI plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [AsyncAPI Example](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/basic)
+  -  A basic example of using the AsyncAPI plugin to generate a catalog from an AsyncAPI file.
+- [Fetch AsyncAPI files from remote URLs](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/fetch-from-remote-urls) 
+  - An example of using the AsyncAPI plugin to fetch an AsyncAPI file from a remote URL.
+- [Version AsyncAPI messages in EventCatalog](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/independent-message-versioning) 
+  - An example of using the AsyncAPI plugin to version AsyncAPI messages in EventCatalog.
+- [Map AsyncAPI routes to commands, events and queries](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/mapping-commands-events-queries) 
+  - An example of using the AsyncAPI plugin to map AsyncAPI routes to commands, events and queries.
+- [Assign ownership to teams](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi/message-ownership)
+  - An example of using the AsyncAPI plugin to assign ownership to teams.
diff --git a/packages/core/docs/plugins/asyncapi/04-using-reference-objects.md b/packages/core/docs/plugins/asyncapi/04-using-reference-objects.md
new file mode 100644
index 000000000..d8a148355
--- /dev/null
+++ b/packages/core/docs/plugins/asyncapi/04-using-reference-objects.md
@@ -0,0 +1,45 @@
+---
+sidebar_position: 4
+keywords:
+- components
+sidebar_label: Using reference objects
+title: Using reference objects
+description: Understanding reference objects with AsyncAPI
+---
+
+AsyncAPI supports reusable parts in your AsyncAPI files using [References Objects](https://www.asyncapi.com/docs/concepts/asyncapi-document/reusable-parts).
+
+EventCatalog also supports reference with EventCatalog. For example you can keep your message schemas outside of your AsyncAPI file, as seen in this example.
+
+```yaml title="/asyncapi.yml"
+channels:
+  signUp:
+    address: user/signedup
+    messages:
+      UserSignup:
+        $ref: './message-schema.yaml#/UserSignup'
+operations:
+  user/signedup.publish:
+    action: receive
+    channel:
+      $ref: '#/channels/signUp'
+    messages:
+      - $ref: '#/channels/signUp/messages/UserSignup'
+```
+
+```yaml title="/message-schema.yaml"
+UserSignup:
+  name: UserSignup
+  title: User signup
+  summary: Action to sign a user up.
+  description: A longer description
+  contentType: application/json
+  payload: null
+```
+
+You can see the example [EventCatalog AsyncAPI GitHub project for a demo](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi).
+
+---
+
+Note: When the AsyncAPI file is written against your EventCatalog service, all refs are removed. This allows EventCatalog to render the AsyncAPI UI without the need to store and track references. 
+
diff --git a/packages/core/docs/plugins/asyncapi/_category_.json b/packages/core/docs/plugins/asyncapi/_category_.json
new file mode 100644
index 000000000..eb9545371
--- /dev/null
+++ b/packages/core/docs/plugins/asyncapi/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "AsyncAPI Plugin",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "asyncapi",
+    "title": "AsyncAPI",
+    "description": "AsyncAPI integration documentation for EventCatalog"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/plugins/aws-glue-registry/00-intro.md b/packages/core/docs/plugins/aws-glue-registry/00-intro.md
new file mode 100644
index 000000000..9540e543d
--- /dev/null
+++ b/packages/core/docs/plugins/aws-glue-registry/00-intro.md
@@ -0,0 +1,104 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Getting started
+description: Getting started with AWS Glue Schema Registry plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="515" src="https://www.youtube.com/embed/cUQDdisz1wg?si=4Sj262A8N6iD8MTV" 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>
+
+---
+
+[AWS Glue Schema Registry](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html) is a feature of [AWS Glue](https://aws.amazon.com/glue) that enables you to discover, register, and evolve schemas for your data streams. The Schema Registry helps you centrally store and manage schemas for your event-driven applications and streaming data platforms.
+
+AWS Glue Schema Registry provides schema evolution with full compatibility control, supporting Apache Avro, JSON Schema, and Protocol Buffers formats. It integrates seamlessly with AWS services like Amazon Kinesis, Amazon MSK, and the Apache Kafka ecosystem.
+
+Using [schema versioning and compatibility features](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-concepts.html), as schemas evolve in your applications, they are versioned and stored in the registry. These schemas can be used to help you and your teams understand and discover events in your event-driven architecture, ensuring data quality and contract compliance.
+
+Although Glue Schema Registry offers powerful schema management solutions, [there is still an issue of discoverability and documentation for your events, services and domains](https://www.youtube.com/watch?v=VLUvfIm9wnQ&t=4s). It remains difficult to organize your event-driven architecture for governance and team collaboration.
+
+### Why use EventCatalog with AWS Glue Schema Registry?
+
+Using the EventCatalog AWS Glue Schema Registry integration you can sync your schemas with EventCatalog.
+
+You can map and sync schemas to your services and domains, and then use the EventCatalog to document your architecture.
+Giving your teams a single source of truth for your event-driven architecture.
+
+### Core Features
+
+The EventCatalog AWS Glue plugin can provide you with many features:
+
+- Import schemas directly from AWS Glue Schema Registry and keep them in sync with your documentation
+- Assign schemas to producers and consumers
+- Use filters to assign your schemas to your producer and consumers (e.g tag matching, prefix, suffix, etc)
+- Generate domains, services, channels and messages into your catalog
+- Add more meaning to your schemas with custom markdown. Persisted between changes to your schemas.
+- Visualize your schemas and let your teams download and explore them in your catalog.
+- Use EventCatalog MCP and AI features to talk to your schemas, and find insights in seconds.
+- and more....
+
+### How it works
+
+![How it works](/img/integrations/aws-glue/glue.png)
+
+EventCatalog supports [generators](/docs/plugins/generators). These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an [SDK](/docs/sdk) to give developers easier access to their catalogs through custom scripts or generators.
+
+The EventCatalog AWS Glue Schema Registry plugin lets you document, sync and map your schemas into EventCatalog.
+
+You can use [custom filters (schemaName, prefix, suffix, includes, tags, dataFormat)](/docs/plugins/aws-glue-registry/features) to map which schemas you want your service to produce and consume. This is useful if you have a lot of schemas and you want to map only a subset of them to your services.
+
+You can also use the EventCatalog plugin to map ALL schemas from your registry into your system and not map them into services if you wish to have a direct import.
+
+### Supported Schema Formats
+
+EventCatalog is technology agnostic, and supports all schema formats.
+
+The plugin supports all AWS Glue Schema Registry formats:
+
+- **Apache Avro** - For efficient serialization in streaming applications
+- **JSON Schema** - For JSON data validation and documentation  
+- **Protocol Buffers** - For language-neutral, platform-neutral serialization
+
+
+### See an example
+
+If you would like to get started with our example project, [you can find it on GitHub](https://github.com/event-catalog/generators/tree/main/examples/generator-glue-registry/basic).
+
+
+
+## Commercial and License
+
+This plugin requires an EventCatalog Scale license key to be used.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial, you can continue using this plugin with EventCatalog Scale. 
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## License FAQ
+
+### What is the license key for?
+The EventCatalog Scale license key is required to use the AWS Glue Schema Registry plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get an EventCatalog Scale license key?
+You can obtain an EventCatalog Scale license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 30-day free trial.
+
+### Terms
+- **Trial Period**: 30-day free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can continue with EventCatalog Scale through [EventCatalog Cloud](https://eventcatalog.cloud).
+
+## Issues
+
+If you have any problems or feature requests please feel free to raise them on GitHub. https://github.com/event-catalog/generators
\ No newline at end of file
diff --git a/packages/core/docs/plugins/aws-glue-registry/00a-installation.md b/packages/core/docs/plugins/aws-glue-registry/00a-installation.md
new file mode 100644
index 000000000..e153bd176
--- /dev/null
+++ b/packages/core/docs/plugins/aws-glue-registry/00a-installation.md
@@ -0,0 +1,315 @@
+---
+sidebar_position: 2
+keywords:
+- installation
+sidebar_label: Installation
+title: Installation
+description: How to install the AWS Glue Schema Registry plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PluginLicense url="#commercial-use" />
+
+## Installation
+
+Install the plugin into your EventCatalog application:
+
+:::tip "Don't have an EventCatalog project yet?"
+If you don't have an EventCatalog project yet, you can follow the instructions in the [Getting Started](/docs/development/getting-started/installation) guide.
+:::
+
+
+```bash
+npm install @eventcatalog/generator-aws-glue
+```
+
+## Configuration
+
+Add the generator to your `eventcatalog.config.js` file:
+
+<Tabs>
+  <TabItem value="apple" label="Import all schemas" default>
+
+  ---
+
+  In this example we import all schemas from an AWS Glue Schema Registry.
+
+  We don't map them to any services or domains.
+
+  ```js title="eventcatalog.config.js"
+  // ...
+generators: [
+    // Import all schemas into your catalog
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        // The region of your AWS Glue Schema Registry
+        region: 'us-east-1',
+        // The name of your AWS Glue Schema Registry
+        registryName: 'my-glue-registry'
+      },
+    ],
+],
+// ...
+```
+  </TabItem>
+  <TabItem value="orange" label="Map schemas to producers and consumers">
+
+  ---
+
+  In this example we map schemas to producers and consumers (services).
+
+  Every time you run the plugin, it will check if the service already exists in your catalog.
+
+  If the service already exists, it will not create a new one and just maintain the schema mappings.
+
+  We create two services, the `orders` service and the `inventory` service.
+  
+  
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  [
+    '@eventcatalog/generator-eventbridge',
+    {
+      // The region of your EventBridge registry
+      region: 'us-east-1',
+      // The name of your AWS Glue Schema Registry
+      registryName: 'my-glue-registry',
+      // Creating producers and consumers, and mapping them to your catalog
+      services: [
+        
+        // We map schemas to the orders service
+        // Using the prefix and suffix we can map specific schemas to the service
+        { id: 'Orders Service', version: '1.0.0', sends: [{ prefix: 'Order' }, { suffix: 'Placed' }], receives:[{ prefix: 'Inventory' }, { suffix: 'Adjusted' }] },
+
+        // Map schemas to the Inventory Service
+        // Filter by prefix (all schemas that match the prefix get assigned). This example shows any schema matching the prefix
+        // "myapp.orders" will be assigned to the inventory service. The inventory service will publish these schemas.
+        { id: 'Inventory Service', version: '1.0.0', sends: [{ prefix: "myapp.orders"}], receives:[{ prefix: "UserCheckedOut"}] },
+
+
+        // This service sends schemas that match the SchemaName prefixing myapp, and will receive schemas that end with Payment
+        // this also does not map any schemas to your schemas
+        { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
+      ],
+
+      // all services are mapped to this domain
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+    },
+  ],
+],
+// ...
+```
+  </TabItem>
+  <TabItem value="orange2" label="Multiple domains, services and events">
+
+  ---
+
+  In this example we have two domains, `orders` and `inventory`.
+
+  We map schemas to the orders and inventory services, and we assign these services to new domains.
+
+  If the domain or service already exists in your catalog, the plugin will not create a new one and just maintain the schema mappings.
+
+  :::info Why do we define the plugin twice?
+  The plugin can be defined multiple times in your `eventcatalog.config.js` file.
+
+  In this example we define the plugin twice, the first time we import the schemas and create the `orders` domain.
+
+  The second time we map the inventory service to the `inventory` domain.
+  :::
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  [
+    '@eventcatalog/generator-aws-glue',
+    {
+      // The region of your AWS Glue Schema Registry
+      region: 'us-east-1',
+      // The name of your AWS Glue Schema Registry
+      registryName: 'my-glue-registry',
+      // Creating producers and consumers, and mapping them to your catalog
+      services: [
+        // We map schemas to the orders service
+        // Using the prefix and suffix we can map specific schemas to the service
+        { id: 'Orders Service', version: '1.0.0', sends: [{ prefix: 'Order' }, { suffix: 'Placed' }], receives:[{ prefix: 'Inventory' }, { suffix: 'Adjusted' }] },
+      ],
+
+      // all services are mapped to this domain
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+    },
+  ],
+  [
+    '@eventcatalog/generator-aws-glue',
+    {
+      region: 'us-east-1',
+      registryName: 'my-glue-registry',
+      services: [
+        // Create the inventory service and map schemas to it (producer/consumer relationship)
+        { id: 'Inventory Service', version: '1.0.0', sends: [{ prefix: "myapp.orders"}], receives:[{ prefix: "UserCheckedOut"}] },
+      ],
+
+      // create the inventory domain and assign the inventory service to it
+      domain: { id: 'inventory', name: 'Inventory', version: '0.0.1' },
+    },
+  ],
+],
+// ...
+```
+  </TabItem>
+</Tabs>
+
+### Configure license key
+
+The EventCatalog AWS Glue Schema Registry plugin requires an EventCatalog Scale license key to work with EventCatalog.
+
+You can get a trial Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+You have a few options for setting the license key:
+
+1. [Setting license key in `.env` file (recommended)](#setting-license-key-in-env-file-recommended)
+2. [Setting license key in eventcatalog.config.js](#setting-license-key-in-eventcatalogconfigjs)
+
+#### 1. Setting license key in `.env` file (recommended) {#setting-license-key-in-env-file-recommended}
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+:::tip Using an Older API Key?
+
+If you already have an older AWS Glue Schema Registry plugin key, you can still use it with the plugin-specific environment variable.
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_AWS_GLUE_SCHEMA_REGISTRY=your-license-key
+```
+
+:::
+
+#### 2. Setting license key in eventcatalog.config.js {#setting-license-key-in-eventcatalogconfigjs}
+
+If you prefer, you can set the license key in the `eventcatalog.config.js` file
+using the `licenseKey` property in the EventCatalog AWS Glue Schema Registry plugin.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_SCALE_LICENSE_KEY
+      },
+    ],
+  ],
+};
+```
+
+#### White listing EventCatalog domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+## Required AWS Permissions
+
+The plugin requires the following AWS IAM permissions to access your Glue Schema Registry:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "glue:ListSchemas",
+        "glue:GetSchema",
+        "glue:GetSchemaVersion",
+        "glue:GetTags"
+      ],
+      "Resource": [
+        "arn:aws:glue:*:*:registry/*",
+        "arn:aws:glue:*:*:schema/*/*"
+      ]
+    }
+  ]
+}
+```
+
+## AWS Credential Configuration
+
+The plugin uses the AWS SDK for JavaScript and supports all standard AWS credential methods:
+
+### Environment Variables
+```bash
+export AWS_ACCESS_KEY_ID=your-access-key
+export AWS_SECRET_ACCESS_KEY=your-secret-key
+export AWS_REGION=us-east-1
+```
+
+### AWS CLI Profile
+```bash
+aws configure --profile eventcatalog
+export AWS_PROFILE=eventcatalog
+```
+
+### Custom Credentials
+You can also provide credentials directly in the configuration:
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryName: 'my-event-registry',
+        credentials: {
+          accessKeyId: 'your-access-key',
+          secretAccessKey: 'your-secret-key',
+        },
+      },
+    ],
+  ],
+}
+```
+
+:::warning
+Never commit credentials to your repository. Use environment variables or AWS credential files instead.
+:::
+
+## Cross-Account Access
+
+To access registries in different AWS accounts, use the `registryArn` parameter:
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryArn: 'arn:aws:glue:us-east-1:123456789012:registry/cross-account-registry',
+      },
+    ],
+  ],
+}
+```
+
+## Running the Generator
+
+Once configured, generate your catalog:
+
+```bash
+npm run generate
+```
+
+This will connect to your AWS Glue Schema Registry and generate EventCatalog documentation for all your schemas.
diff --git a/packages/core/docs/plugins/aws-glue-registry/01-features.md b/packages/core/docs/plugins/aws-glue-registry/01-features.md
new file mode 100644
index 000000000..93678fe79
--- /dev/null
+++ b/packages/core/docs/plugins/aws-glue-registry/01-features.md
@@ -0,0 +1,287 @@
+---
+sidebar_position: 3
+keywords:
+- components
+sidebar_label: Features
+title: Features
+description: Features of AWS Glue Schema Registry with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+### Using filters to map schemas to your services
+
+EventCatalog plugin supports a comprehensive range of filters to give you precise control over which schemas map to your services:
+
+- `schemaName` - Exact matching on the schema name
+- `prefix` - Matches schemas that start with the specified prefix
+- `suffix` - Matches schemas that end with the specified suffix
+- `includes` - Matches schemas that contain the specified text (supports arrays)
+- `tags` - Matches schemas with specific tag key-value pairs
+- `dataFormat` - Matches schemas by format (AVRO, JSON, PROTOBUF)
+
+You can use these filters to map schemas directly to your services, giving you flexibility on how you want to structure your EventCatalog and map events to services.
+
+:::tip
+All filters can accept either a single string value or an array of strings for multiple matching criteria.
+:::
+
+#### **schemaName example**
+
+Match schemas by their exact name:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-aws-glue',
+    {
+      region: 'us-east-1',
+      registryName: 'my-event-registry',
+      services: [
+        {
+          id: 'Customer Service',
+          version: '1.0.0',
+          sends: [{ schemaName: ['CustomerCreated', 'CustomerUpdated'] }],
+          receives: [{ schemaName: 'OrderPlaced' }]
+        },
+      ],
+    },
+  ],
+],
+```
+
+#### **prefix example**
+
+Match schemas that start with a specific prefix:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-aws-glue',
+    {
+      region: 'us-east-1',
+      registryName: 'my-event-registry',
+      services: [
+        {
+          id: 'Customer Service',
+          version: '1.0.0',
+          sends: [{ prefix: ['Customer', 'User'] }],
+          receives: [{ prefix: 'Order' }]
+        },
+      ],
+    },
+  ],
+],
+```
+
+#### **suffix example**
+
+Match schemas that end with a specific suffix:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-aws-glue',
+    {
+      region: 'us-east-1',
+      registryName: 'my-event-registry',
+      services: [
+        {
+          id: 'Event Service',
+          version: '1.0.0',
+          sends: [{ suffix: ['Created', 'Updated'] }],
+          receives: [{ suffix: ['Completed', 'Failed'] }]
+        },
+      ],
+    },
+  ],
+],
+```
+
+#### **includes example**
+
+Match schemas that contain specific text anywhere in the name:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-aws-glue',
+    {
+      region: 'us-east-1',
+      registryName: 'my-event-registry',
+      services: [
+        {
+          id: 'Analytics Service',
+          version: '1.0.0',
+          // Single string
+          sends: [{ includes: 'analytics' }],
+          // Array of strings - matches schemas containing ANY of these
+          receives: [{ includes: ['customer', 'user', 'profile'] }]
+        },
+      ],
+    },
+  ],
+],
+```
+
+#### **dataFormat example**
+
+Match schemas by their data format:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-aws-glue',
+    {
+      region: 'us-east-1',
+      registryName: 'my-event-registry',
+      services: [
+        {
+          id: 'Streaming Service',
+          version: '1.0.0',
+          sends: [{ dataFormat: ['AVRO'] }],
+          receives: [{ dataFormat: ['JSON', 'PROTOBUF'] }]
+        },
+      ],
+    },
+  ],
+],
+```
+
+#### **tags example**
+
+Match schemas by their AWS tags. This is particularly useful for organizing schemas by team, environment, or purpose:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-aws-glue',
+    {
+      region: 'us-east-1',
+      registryName: 'my-event-registry',
+      services: [
+        {
+          id: 'Customer Team Service',
+          version: '1.0.0',
+          // Match schemas with specific tag
+          sends: [{ tags: { team: 'customer' } }],
+          // Match schemas with multiple tags (ALL must match)
+          receives: [{ tags: { env: 'prod', type: 'event' } }]
+        },
+      ],
+    },
+  ],
+],
+```
+
+#### **Combining multiple filters**
+
+You can combine multiple filter types in a single filter object:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-aws-glue',
+    {
+      region: 'us-east-1',
+      registryName: 'my-event-registry',
+      services: [
+        {
+          id: 'Advanced Service',
+          version: '1.0.0',
+          sends: [
+            {
+              prefix: 'Customer',
+              dataFormat: 'AVRO',
+              tags: { team: 'customer' }
+            }
+          ],
+          receives: [
+            {
+              suffix: 'Event',
+              includes: 'order',
+              tags: { env: 'prod' }
+            }
+          ]
+        },
+      ],
+    },
+  ],
+],
+```
+
+:::tip
+When multiple filter criteria are specified in a single filter object, ALL criteria must match for a schema to be included.
+:::
+
+### Persist markdown
+
+Your markdown is persisted between generation runs on EventCatalog. Initially the generator will generate markdown for you for your domains, services and events, but any edits to the markdown file will be persisted between versions.
+
+This allows you to add [custom components](/docs/components/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when your schemas are versioned.
+
+This can be useful for adding extra additional context to your events, example payloads, example CLI commands on how to produce/consume them and any other useful information.
+
+### Automatic versioning
+
+AWS Glue Schema Registry maintains version history for all schemas. The generator uses the schema version numbers from the registry to version your events in EventCatalog.
+
+#### How it works
+
+- You register a schema in AWS Glue Schema Registry (v1 of this schema is stored)
+- You run generate for your catalog (v1 is documented in your catalog)
+- You update the schema and register a new version (v2 is created in the registry)
+- You run generate for your catalog (v1 is versioned for you, and v2 takes its place)
+
+#### Compatibility modes
+
+The generator respects the compatibility mode settings from your registry:
+
+- **BACKWARD** - New schema version is compatible with previous version
+- **FORWARD** - Previous schema version is compatible with new version  
+- **FULL** - New schema version is both backward and forward compatible
+- **NONE** - No compatibility checking
+
+This information is displayed in your EventCatalog documentation.
+
+### Downloading schemas
+
+The generator downloads the actual schema definitions from AWS Glue Schema Registry and attaches them to each event in EventCatalog. Users will be able to see and download these files.
+
+#### Supported formats
+
+- **Avro schemas** (.avsc) - Complete Avro schema definitions
+- **JSON schemas** (.json) - JSON Schema specifications  
+- **Protocol Buffer schemas** (.proto) - Protocol Buffer definitions
+
+#### Schema components
+
+The generator automatically selects the appropriate EventCatalog component based on the schema format:
+
+- **JSON schemas** use `<SchemaViewer>` for enhanced JSON display
+- **Avro and Protocol Buffer schemas** use `<Schema>` for general schema display
+
+### Cross-account registry access
+
+The generator supports accessing registries across different AWS accounts using IAM roles and registry ARNs:
+
+```js
+generators: [
+  [
+    '@eventcatalog/generator-aws-glue',
+    {
+      region: 'us-east-1',
+      registryArn: 'arn:aws:glue:us-east-1:123456789012:registry/shared-schemas',
+      services: [
+        {
+          id: 'Cross Account Service',
+          version: '1.0.0',
+          sends: [{ prefix: 'Shared' }],
+        },
+      ],
+    },
+  ],
+],
+```
+
+This is useful for organizations that centralize schema management across multiple AWS accounts.
diff --git a/packages/core/docs/plugins/aws-glue-registry/02-examples.md b/packages/core/docs/plugins/aws-glue-registry/02-examples.md
new file mode 100644
index 000000000..a7d15449e
--- /dev/null
+++ b/packages/core/docs/plugins/aws-glue-registry/02-examples.md
@@ -0,0 +1,368 @@
+---
+sidebar_position: 4
+keywords:
+- examples
+sidebar_label: Examples
+title: Examples
+description: Examples of using AWS Glue Schema Registry with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+Here are some practical examples showing different ways to use the AWS Glue Schema Registry generator.
+
+## Basic Example: Document All Schemas
+
+The simplest configuration generates events for every schema in your registry:
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryName: 'ecommerce-events',
+      },
+    ],
+  ],
+}
+```
+
+This creates:
+- An event for each schema in the `ecommerce-events` registry
+- A channel representing the registry
+- Schema files attached to each event
+
+## E-commerce Platform Example
+
+Map schemas to services based on business domains:
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryName: 'ecommerce-events',
+        domain: {
+          id: 'ecommerce',
+          name: 'E-commerce Platform',
+          version: '1.0.0'
+        },
+        services: [
+          {
+            id: 'Customer Service',
+            version: '1.0.0',
+            sends: [
+              { prefix: 'Customer' },
+              { suffix: 'ProfileUpdated' }
+            ],
+            receives: [
+              { schemaName: 'OrderPlaced' },
+              { includes: 'payment' }
+            ]
+          },
+          {
+            id: 'Order Service', 
+            version: '1.0.0',
+            sends: [
+              { prefix: 'Order' },
+              { schemaName: ['InventoryReserved', 'PaymentRequested'] }
+            ],
+            receives: [
+              { prefix: 'Customer' },
+              { suffix: ['Confirmed', 'Updated'] }
+            ]
+          },
+          {
+            id: 'Inventory Service',
+            version: '1.0.0', 
+            sends: [
+              { prefix: 'Inventory' },
+              { includes: 'stock' }
+            ],
+            receives: [
+              { schemaName: 'OrderPlaced' },
+              { includes: 'reservation' }
+            ]
+          }
+        ]
+      },
+    ],
+  ],
+}
+```
+
+## Team-based Organization with Tags
+
+Use AWS tags to organize schemas by team ownership:
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryName: 'company-events',
+        services: [
+          {
+            id: 'Customer Experience Service',
+            version: '1.0.0',
+            sends: [{ tags: { team: 'customer-experience' } }],
+            receives: [{ tags: { team: 'orders', env: 'prod' } }]
+          },
+          {
+            id: 'Data Analytics Service',
+            version: '1.0.0',
+            sends: [{ tags: { team: 'analytics' } }],
+            receives: [{ tags: { type: 'analytics-input' } }]
+          },
+          {
+            id: 'Platform Service',
+            version: '1.0.0',
+            sends: [{ tags: { team: 'platform', env: 'prod' } }],
+            receives: [{ tags: { category: 'infrastructure' } }]
+          }
+        ]
+      },
+    ],
+  ],
+}
+```
+
+## Multi-Format Schema Environment
+
+Handle different schema formats for different use cases:
+
+```js
+// eventcatalog.config.js  
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryName: 'multi-format-schemas',
+        services: [
+          {
+            id: 'High Volume Streaming Service',
+            version: '1.0.0',
+            sends: [{ dataFormat: 'AVRO' }], // Efficient binary format
+            receives: [{ dataFormat: ['AVRO'] }]
+          },
+          {
+            id: 'API Gateway Service',
+            version: '1.0.0', 
+            sends: [{ dataFormat: 'JSON' }], // Human readable for APIs
+            receives: [{ dataFormat: ['JSON'] }]
+          },
+          {
+            id: 'gRPC Microservice',
+            version: '1.0.0',
+            sends: [{ dataFormat: 'PROTOBUF' }], // Language neutral
+            receives: [{ dataFormat: ['PROTOBUF'] }]
+          }
+        ]
+      },
+    ],
+  ],
+}
+```
+
+## Advanced Filtering Example
+
+Combine multiple filter types for precise schema mapping:
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryName: 'advanced-events',
+        services: [
+          {
+            id: 'Production Customer Service',
+            version: '1.0.0',
+            sends: [
+              {
+                prefix: 'Customer',
+                dataFormat: 'AVRO',
+                tags: { env: 'prod', team: 'customer' }
+              }
+            ],
+            receives: [
+              {
+                includes: ['order', 'payment'],
+                dataFormat: ['JSON', 'AVRO'],
+                tags: { env: 'prod' }
+              }
+            ]
+          },
+          {
+            id: 'Event Processing Service',
+            version: '1.0.0',
+            sends: [
+              {
+                suffix: ['Processed', 'Enriched'],
+                dataFormat: 'AVRO'
+              }
+            ],
+            receives: [
+              {
+                prefix: 'Raw',
+                includes: 'event',
+                tags: { type: 'input' }
+              }
+            ]
+          }
+        ]
+      },
+    ],
+  ],
+}
+```
+
+## Cross-Account Registry Access
+
+Access schemas from a centralized registry in another AWS account:
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryArn: 'arn:aws:glue:us-east-1:123456789012:registry/central-schemas',
+        services: [
+          {
+            id: 'Consumer Service',
+            version: '1.0.0',
+            receives: [
+              { prefix: 'Shared' },
+              { tags: { shared: 'true' } }
+            ]
+          }
+        ]
+      },
+    ],
+  ],
+}
+```
+
+## Multiple Registries
+
+Document schemas from multiple registries in one catalog:
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryName: 'customer-events',
+        domain: {
+          id: 'customer',
+          name: 'Customer Domain',
+          version: '1.0.0'
+        },
+        services: [
+          {
+            id: 'Customer Service',
+            version: '1.0.0',
+            sends: [{ prefix: 'Customer' }]
+          }
+        ]
+      },
+    ],
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1', 
+        registryName: 'order-events',
+        domain: {
+          id: 'orders',
+          name: 'Order Domain', 
+          version: '1.0.0'
+        },
+        services: [
+          {
+            id: 'Order Service',
+            version: '1.0.0',
+            sends: [{ prefix: 'Order' }]
+          }
+        ]
+      },
+    ],
+  ],
+}
+```
+
+## Custom Output Format
+
+Generate markdown files instead of MDX:
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryName: 'my-events',
+        format: 'md', // Generate .md files instead of .mdx
+        writeFilesToRoot: true, // Write files to root instead of service subdirectories
+        services: [
+          {
+            id: 'Simple Service',
+            version: '1.0.0',
+            sends: [{ prefix: 'Simple' }]
+          }
+        ]
+      },
+    ],
+  ],
+}
+```
+
+## Debug Mode
+
+Enable debug mode to see detailed information during generation:
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        region: 'us-east-1',
+        registryName: 'debug-events',
+        debug: true, // Enable detailed logging
+        services: [
+          {
+            id: 'Debug Service',
+            version: '1.0.0',
+            sends: [{ prefix: 'Debug' }]
+          }
+        ]
+      },
+    ],
+  ],
+}
+```
+
+These examples show the flexibility of the AWS Glue Schema Registry generator. You can start simple and add complexity as your schema management needs grow.
\ No newline at end of file
diff --git a/packages/core/docs/plugins/aws-glue-registry/03-api.md b/packages/core/docs/plugins/aws-glue-registry/03-api.md
new file mode 100644
index 000000000..97ee4e7f8
--- /dev/null
+++ b/packages/core/docs/plugins/aws-glue-registry/03-api.md
@@ -0,0 +1,282 @@
+---
+sidebar_position: 5
+keywords:
+- api
+sidebar_label: API Reference
+title: API Reference
+description: Complete API reference for AWS Glue Schema Registry plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+## Configuration Options
+
+### Required Configuration
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `region` | `string` | AWS region where your schema registry is located |
+| `registryName` | `string` | Name of the AWS Glue Schema Registry |
+
+### Optional Configuration
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `registryArn` | `string` | `undefined` | ARN of the registry (for cross-account access) |
+| `services` | `Service[]` | `[]` | Array of service definitions to map schemas to |
+| `domain` | `Domain` | `undefined` | Domain configuration for organizing services |
+| `credentials` | `AwsCredentials` | `undefined` | Custom AWS credentials |
+| `debug` | `boolean` | `false` | Enable debug logging |
+| `format` | `'md' \| 'mdx'` | `'mdx'` | Output file format |
+| `writeFilesToRoot` | `boolean` | `false` | Write files to root instead of service directories |
+
+## Type Definitions
+
+### Service
+
+Defines a service and which schemas it produces/consumes.
+
+```typescript
+type Service = {
+  id: string;           // Unique service identifier
+  version: string;      // Service version
+  sends?: Filter[];     // Schemas this service produces
+  receives?: Filter[];  // Schemas this service consumes
+}
+```
+
+### Filter
+
+Defines criteria for matching schemas to services.
+
+```typescript
+type Filter = {
+  schemaName?: string | string[];    // Exact schema name matching
+  prefix?: string | string[];        // Schema name starts with
+  suffix?: string | string[];        // Schema name ends with  
+  includes?: string | string[];      // Schema name contains
+  dataFormat?: string | string[];    // Schema format (AVRO, JSON, PROTOBUF)
+  tags?: Record<string, string>;     // AWS tags key-value pairs
+}
+```
+
+#### Filter Examples
+
+```js
+// Exact name matching
+{ schemaName: 'CustomerCreated' }
+{ schemaName: ['CustomerCreated', 'CustomerUpdated'] }
+
+// Prefix matching
+{ prefix: 'Customer' }
+{ prefix: ['Customer', 'User'] }
+
+// Suffix matching  
+{ suffix: 'Created' }
+{ suffix: ['Created', 'Updated'] }
+
+// Contains matching
+{ includes: 'customer' }
+{ includes: ['customer', 'user'] }
+
+// Format matching
+{ dataFormat: 'AVRO' }
+{ dataFormat: ['AVRO', 'JSON'] }
+
+// Tag matching (ALL tags must match)
+{ tags: { team: 'customer' } }
+{ tags: { team: 'customer', env: 'prod' } }
+
+// Combined filters (ALL criteria must match)
+{
+  prefix: 'Customer',
+  dataFormat: 'AVRO', 
+  tags: { env: 'prod' }
+}
+```
+
+### Domain
+
+Defines a domain for organizing related services.
+
+```typescript
+type Domain = {
+  id: string;      // Unique domain identifier
+  name: string;    // Display name for the domain
+  version: string; // Domain version
+}
+```
+
+### AWS Credentials
+
+Custom AWS credentials (use environment variables when possible).
+
+```typescript
+type AwsCredentials = {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;  // For temporary credentials
+}
+```
+
+## Complete Configuration Example
+
+```js
+// eventcatalog.config.js
+module.exports = {
+  generators: [
+    [
+      '@eventcatalog/generator-aws-glue',
+      {
+        // Required
+        region: 'us-east-1',
+        registryName: 'my-event-registry',
+        
+        // Optional - Cross-account access
+        registryArn: 'arn:aws:glue:us-east-1:123456789012:registry/shared-registry',
+        
+        // Optional - Custom credentials (not recommended)
+        credentials: {
+          accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+          secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+        },
+        
+        // Optional - Domain organization
+        domain: {
+          id: 'ecommerce',
+          name: 'E-commerce Platform',
+          version: '1.0.0'
+        },
+        
+        // Optional - Service mapping
+        services: [
+          {
+            id: 'Customer Service',
+            version: '1.0.0',
+            sends: [
+              { prefix: 'Customer' },
+              { tags: { team: 'customer' } }
+            ],
+            receives: [
+              { schemaName: ['OrderPlaced', 'PaymentProcessed'] },
+              { includes: 'notification' }
+            ]
+          },
+          {
+            id: 'Order Service',
+            version: '1.0.0', 
+            sends: [
+              { prefix: 'Order' },
+              { dataFormat: 'AVRO' }
+            ],
+            receives: [
+              { suffix: ['Created', 'Updated'] },
+              { tags: { env: 'prod', type: 'input' } }
+            ]
+          }
+        ],
+        
+        // Optional - Output configuration
+        format: 'mdx',
+        writeFilesToRoot: false,
+        debug: true
+      },
+    ],
+  ],
+}
+```
+
+## Schema Matching Logic
+
+### Filter Evaluation
+
+When a schema is evaluated against a filter:
+
+1. **Within a filter object**: ALL criteria must match (AND logic)
+2. **Between filter objects**: ANY filter can match (OR logic)  
+3. **Within array values**: ANY value can match (OR logic)
+
+### Examples
+
+```js
+// Schema must start with 'Customer' AND be AVRO format AND have team=customer tag
+{
+  prefix: 'Customer',
+  dataFormat: 'AVRO',
+  tags: { team: 'customer' }
+}
+
+// Schema must contain 'order' OR 'customer' OR 'payment'
+{
+  includes: ['order', 'customer', 'payment']
+}
+
+// Multiple filters - schema matches if it satisfies ANY filter
+sends: [
+  { prefix: 'Customer' },      // OR
+  { tags: { team: 'orders' } } // OR  
+  { dataFormat: 'AVRO' }       // OR
+]
+```
+
+### Priority and Precedence
+
+1. More specific filters take precedence over general ones
+2. Exact `schemaName` matches have highest priority
+3. Combined filters are more specific than single criteria
+4. Schema can only be assigned to one service per filter match
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `AccessDenied` | Insufficient IAM permissions | Check IAM policy has required Glue permissions |
+| `RegistryNotFound` | Registry doesn't exist | Verify registry name and region |
+| `InvalidCredentials` | AWS credentials invalid | Check AWS credential configuration |
+| `SchemaNotFound` | Schema was deleted | Re-run generator to sync with current state |
+
+### Debug Mode
+
+Enable debug mode to troubleshoot issues:
+
+```js
+{
+  debug: true,
+  // ... other config
+}
+```
+
+This will output detailed information about:
+- Schemas being fetched
+- Filter matching results  
+- Service assignments
+- File generation progress
+
+## AWS Permissions Required
+
+The plugin requires these IAM permissions:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "glue:ListSchemas",
+        "glue:GetSchema", 
+        "glue:GetSchemaVersion",
+        "glue:GetTags"
+      ],
+      "Resource": [
+        "arn:aws:glue:*:*:registry/*",
+        "arn:aws:glue:*:*:schema/*/*"
+      ]
+    }
+  ]
+}
+```
+
+For cross-account access, additional permissions may be required on the target account's registry.
\ No newline at end of file
diff --git a/packages/core/docs/plugins/aws-glue-registry/_category_.json b/packages/core/docs/plugins/aws-glue-registry/_category_.json
new file mode 100644
index 000000000..3a7c052ba
--- /dev/null
+++ b/packages/core/docs/plugins/aws-glue-registry/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "AWS Glue Schema Registry Plugin",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "aws-glue-schema-registry",
+    "title": "AWS Glue Schema Registry",
+    "description": "AWS Glue Schema Registry integration documentation for EventCatalog"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/plugins/azure-schema-registry/00-intro.md b/packages/core/docs/plugins/azure-schema-registry/00-intro.md
new file mode 100644
index 000000000..92d66ce3e
--- /dev/null
+++ b/packages/core/docs/plugins/azure-schema-registry/00-intro.md
@@ -0,0 +1,92 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Introduction
+description: Getting started with Azure Schema Registry plugin
+---
+
+<!-- import PluginLicense from '@site/src/components/MDX/PluginLicense'; -->
+
+<!-- <PluginLicense url="#commercial-use" /> -->
+
+---
+
+
+The [EventCatalog Azure Schema Registry plugin](https://github.com/event-catalog/generators/tree/main/packages/generator-azure-schema-registry) allows you to import schemas from Azure Schema Registry into EventCatalog and keep them in sync alongside your documentation. 
+
+<iframe width="100%" height="515" src="https://www.youtube.com/embed/rNDa2JDyr_A?si=uFAbZbAiAxiy9dqJ" 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>
+
+
+:::info
+**What is Azure Schema Registry?**: A schema registry for Azure Event Hubs. Use this to store and manage your schemas for event-driven applications. You can read more about it on the [Microsoft Learn website](https://learn.microsoft.com/en-us/azure/event-hubs/schema-registry-overview).
+:::
+
+### Why use EventCatalog with Azure Schema Registry?
+
+The EventCatalog Azure Schema Registry plugin can provide you with many features, including:
+
+- Keep your schemas in sync with your architecture documentation
+- Automatic versioning; as your schemas change they are versioned in EventCatalog alongside your documentation
+- Understand how your schemas have evolved over time with the Schema diff explorer with the [Schema Explorer](/docs/development/guides/resources/schemas/explore-schemas/schema-explorer)
+- Add meaning (markdown) to your schemas. Provide business context to your schemas and add value
+- Quickly find who is producing or consuming your schemas
+- Visualize your Azure Event Hubs architecture with the [EventCatalog Visualizer](/features/visualization)
+- Download and view schemas in EventCatalog (Avro, JSON Schema) or through the [Schema API](/docs/development/guides/resources/schemas/schema-api)
+- Use [EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/introduction) to get schemas for your LLMs
+
+### How it works
+
+1. Install the Azure Schema Registry plugin
+1. Configure the plugin (schemas, services, domains, message types)
+1. Get an Azure access token using Azure CLI: `az account get-access-token --resource https://eventhubs.azure.net`
+1. Set the token as an environment variable: `AZURE_SCHEMA_REGISTRY_TOKEN`
+1. Run the plugin to import your schemas into EventCatalog
+1. View and deploy your catalog
+
+<!-- ![Example](/img/integrations/azure-schema-registry/azure-example.png) -->
+
+**What are generators?**
+
+EventCatalog supports [generators](/docs/plugins/generators). These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an [SDK](/docs/sdk) to give developers easier access to their catalogs through custom scripts or generators.
+
+The EventCatalog Azure Schema Registry plugin is a generator. It will import your schemas from your Azure Schema Registry into EventCatalog.
+
+## Authentication
+
+The plugin uses Azure's REST API with Bearer token authentication. You need to provide an Azure access token via the `AZURE_SCHEMA_REGISTRY_TOKEN` environment variable.
+
+:::info Why use the REST API vs the Azure SDK?
+
+The schema registry SDK is limiting and doesn't allow you to fetch all schemas from a registry. It also doesn't allow you to fetch schemas from multiple registries in one configuration.
+
+We use the REST API because it is simpler and more flexible. It doesn't require you to install any Azure SDK packages and works seamlessly across different environments without requiring any code changes.
+
+:::
+
+## Commercial and License
+
+This plugin requires an EventCatalog Scale license key to be used.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial, you can continue using this plugin with EventCatalog Scale.
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## License FAQ
+
+### What is the license key for?
+The EventCatalog Scale license key is required to use the Azure Schema Registry plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get an EventCatalog Scale license key?
+You can obtain an EventCatalog Scale license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 30-day free trial.
+
+### Terms
+- **Trial Period**: 30-day free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can continue with EventCatalog Scale through [EventCatalog Cloud](https://eventcatalog.cloud).
diff --git a/packages/core/docs/plugins/azure-schema-registry/01-installation.md b/packages/core/docs/plugins/azure-schema-registry/01-installation.md
new file mode 100644
index 000000000..fd90d4fa8
--- /dev/null
+++ b/packages/core/docs/plugins/azure-schema-registry/01-installation.md
@@ -0,0 +1,419 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog Azure Schema Registry
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog Azure Schema Registry plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PluginLicense url="#commercial-use" />
+
+Run the command below to install the EventCatalog Azure Schema Registry plugin.
+
+:::tip "Don't have an EventCatalog project yet?"
+If you don't have an EventCatalog project yet, you can follow the instructions in the [Getting Started](/docs/development/getting-started/installation) guide.
+:::
+
+```bash
+npm i @eventcatalog/generator-azure-schema-registry
+```
+
+:::info License Key
+The EventCatalog Azure Schema Registry plugin requires an EventCatalog Scale license key to work with EventCatalog.
+
+You can get a trial Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+:::
+
+## Configuration
+
+To use the plugin you need to configure it in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators` array.
+
+<Tabs>
+  <TabItem value="basic" label="Basic Example" default>
+
+  In this example we import schemas from an Azure Schema Registry and assign them to a service.
+
+  **Note**: Unlike Confluent, Azure Schema Registry doesn't provide an API to list all schemas, so you must explicitly define which schemas to fetch using schema groups and names.
+
+    ```js title="eventcatalog.config.js"
+    // ...
+    generators: [
+      [
+        '@eventcatalog/generator-azure-schema-registry',
+        {
+          // The URL of your Azure Schema Registry
+          schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+          // Define services and the schemas they use
+          services: [
+            {
+              id: 'orders-service',
+              name: 'Orders Service',
+              version: '1.0.0',
+              // The orders service sends the order-created event
+              sends: [
+                {
+                  id: 'order-created',
+                  schemaGroup: 'com.example.orders'
+                },
+              ],
+              // The orders service receives the payment-received event
+              receives: [
+                {
+                  id: 'payment-received',
+                  schemaGroup: 'com.example.payments'
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    ];
+    ```
+  </TabItem>
+  <TabItem value="advanced" label="Advanced Example with Domains and Message Types">
+
+In this example we document services from Azure Event Hubs, assign schemas to them as different message types (events, commands, queries), and organize them into domains.
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      // The URL of your Azure Schema Registry
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      // Define the domain for these services
+      domain: {
+        id: 'orders-domain',
+        name: 'Orders Domain',
+        version: '1.0.0',
+      },
+      // The services to assign schemas to
+      services: [
+        {
+          id: 'orders-service',
+          name: 'Orders Service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'order-created',
+              schemaGroup: 'com.example.orders',
+              name: 'Order Created Event',
+              messageType: 'event', // Specify as event
+            },
+            {
+              id: 'create-order',
+              schemaGroup: 'com.example.orders',
+              name: 'Create Order Command',
+              messageType: 'command', // Specify as command
+            },
+          ],
+          receives: [
+            {
+              id: 'get-order',
+              schemaGroup: 'com.example.orders',
+              name: 'Get Order Query',
+              messageType: 'query', // Specify as query
+            },
+            {
+              id: 'payment-received',
+              schemaGroup: 'com.example.payments',
+              name: 'Payment Received Event',
+            },
+          ],
+        },
+        {
+          id: 'inventory-service',
+          name: 'Inventory Service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'inventory-updated',
+              schemaGroup: 'com.example.inventory',
+              messageType: 'event',
+            },
+          ],
+          receives: [
+            {
+              id: 'order-created',
+              schemaGroup: 'com.example.orders',
+              messageType: 'event',
+            },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+  </TabItem>
+  <TabItem value="multiple-registries" label="Multiple Schema Registries">
+
+In this example we fetch schemas from multiple Azure Schema Registries by overriding the registry URL per schema.
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      // Default schema registry URL
+      schemaRegistryUrl: 'https://primary-namespace.servicebus.windows.net',
+      services: [
+        {
+          id: 'orders-service',
+          name: 'Orders Service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'order-created',
+              schemaGroup: 'com.example.orders',
+              // Uses default schemaRegistryUrl
+            },
+            {
+              id: 'order-shipped',
+              schemaGroup: 'com.example.shipping',
+              // Override to fetch from a different registry
+              schemaRegistryUrl: 'https://shipping-namespace.servicebus.windows.net',
+            },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+  </TabItem>
+</Tabs>
+
+### Configure Authentication
+
+The EventCatalog Azure Schema Registry plugin uses Azure's REST API with Bearer token authentication. You need to set the `AZURE_SCHEMA_REGISTRY_TOKEN` environment variable with your Azure access token.
+
+### Configure Azure Schema Registry License Key
+
+The EventCatalog Azure Schema Registry plugin requires an EventCatalog Scale license key to work with EventCatalog.
+
+You can get a trial Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+
+---
+
+## Getting an Azure Access Token
+
+### Prerequisites
+
+Before getting a token, ensure you have:
+
+1. **Azure CLI installed** - [Install Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)
+2. **Access to an Azure Event Hubs namespace** with Schema Registry enabled
+3. **Appropriate permissions** - You need one of these roles on the Event Hubs namespace:
+   - `Azure Event Hubs Data Owner` (full access)
+   - `Azure Event Hubs Data Receiver` (read access)
+
+### Method 1: Quick Setup for Local Development (Recommended)
+
+This is the fastest way to get started:
+
+**Step 1: Login to Azure**
+
+```bash
+az login
+```
+
+This opens your browser for authentication. After logging in, you'll see your subscriptions.
+
+**Step 2: Set Your Subscription (if you have multiple)**
+
+```bash
+# List your subscriptions
+az account list --output table
+
+# Set the subscription containing your Event Hubs namespace
+az account set --subscription "Your-Subscription-Name-or-ID"
+```
+
+**Step 3: Get and Export the Access Token**
+
+```bash
+# Get token for Azure Event Hubs and export it
+export AZURE_SCHEMA_REGISTRY_TOKEN=$(az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv)
+
+# Verify the token is set
+echo $AZURE_SCHEMA_REGISTRY_TOKEN
+```
+
+**Step 4: Run the Generator**
+
+```bash
+# Your token is now ready - run the generator
+npm run generate
+```
+
+:::tip Quick Command
+You can also set the token and run the generator in one command:
+```bash
+AZURE_SCHEMA_REGISTRY_TOKEN=$(az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv) npm run generate
+```
+:::
+
+### Method 2: Using .env File (Recommended for Projects)
+
+For a more permanent setup, add the token to your `.env` file:
+
+**Step 1: Get the Token**
+
+```bash
+# Login first
+az login
+
+# Get the token
+az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv
+```
+
+**Step 2: Add to .env File**
+
+Create or update your `.env` file in your EventCatalog project root:
+
+```bash title=".env"
+# EventCatalog license key
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+
+# Azure Schema Registry access token (paste the token from step 1)
+AZURE_SCHEMA_REGISTRY_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOi...
+```
+
+:::tip Using an Older API Key?
+
+If you already have an older Azure Schema Registry plugin key, you can still use it with the plugin-specific environment variable.
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_AZURE_SCHEMA_REGISTRY=your-license-key
+```
+
+:::
+
+**Step 3: Run the Generator**
+
+```bash
+npm run generate
+```
+
+### Method 3: CI/CD with Service Principal
+
+For automated pipelines, use a service principal to obtain tokens programmatically:
+
+**Step 1: Create a Service Principal (one-time setup)**
+
+```bash
+# Create service principal
+az ad sp create-for-rbac --name "eventcatalog-generator" --role "Azure Event Hubs Data Receiver" \
+  --scopes /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventHub/namespaces/{namespace-name}
+```
+
+This outputs credentials like:
+```json
+{
+  "appId": "12345678-1234-1234-1234-123456789012",
+  "password": "your-secret",
+  "tenant": "your-tenant-id"
+}
+```
+
+**Step 2: Set Environment Variables in CI/CD**
+
+Add these secrets to your CI/CD environment:
+
+```bash
+AZURE_TENANT_ID=your-tenant-id
+AZURE_CLIENT_ID=your-app-id
+AZURE_CLIENT_SECRET=your-password
+```
+
+**Step 3: Get Token in CI/CD Pipeline**
+
+```bash
+# Login with service principal and get token
+export AZURE_SCHEMA_REGISTRY_TOKEN=$(az login --service-principal \
+  --username $AZURE_CLIENT_ID \
+  --password $AZURE_CLIENT_SECRET \
+  --tenant $AZURE_TENANT_ID \
+  --output none && \
+  az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv)
+
+# Run the generator
+npm run generate
+```
+
+### Verify Your Permissions
+
+To check if you have the right permissions:
+
+```bash
+# Check your current user
+az account show --query user.name
+
+# List role assignments for your Event Hubs namespace
+az role assignment list \
+  --scope /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventHub/namespaces/{namespace-name} \
+  --query "[?principalName=='your-email@domain.com'].{Role:roleDefinitionName}" \
+  --output table
+```
+
+You should see one of these roles:
+- `Azure Event Hubs Data Owner`
+- `Azure Event Hubs Data Receiver`
+
+### If You Don't Have Permission
+
+Ask your Azure administrator to grant you access:
+
+```bash
+az role assignment create \
+  --role "Azure Event Hubs Data Receiver" \
+  --assignee "your-email@domain.com" \
+  --scope /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventHub/namespaces/{namespace-name}
+```
+
+## White listing EventCatalog Domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+### Run the plugin
+
+Run the plugin to import your schemas into EventCatalog.
+
+_This command will run the generators in your eventcatalog.config.js file._
+
+```bash
+npm run generate
+```
+
+### View your catalog
+
+Run your catalog locally to see the changes
+
+```bash
+npm run dev
+```
+
+### Build your catalog for production
+
+```bash
+npm run build
+```
+
+## Any questions or need help?
+
+If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
+
+You can also find some examples of the plugin in action in our examples repository: [eventcatalog/examples](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry).
diff --git a/packages/core/docs/plugins/azure-schema-registry/02-plugin-configuration.md b/packages/core/docs/plugins/azure-schema-registry/02-plugin-configuration.md
new file mode 100644
index 000000000..8e5e3429a
--- /dev/null
+++ b/packages/core/docs/plugins/azure-schema-registry/02-plugin-configuration.md
@@ -0,0 +1,375 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog Azure Schema Registry plugin
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog Azure Schema Registry plugin
+---
+
+# Plugin Configuration
+
+## Overview
+
+The EventCatalog Azure Schema Registry plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+:::info Authentication
+The plugin uses Azure's REST API with Bearer token authentication. You must set the `AZURE_SCHEMA_REGISTRY_TOKEN` environment variable.
+
+<details>
+<summary>Example .env file</summary>
+
+```bash
+# EventCatalog license key
+export EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+
+# Azure Schema Registry access token
+export AZURE_SCHEMA_REGISTRY_TOKEN=your-azure-access-token
+```
+
+Get the token using Azure CLI:
+```bash
+az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv
+```
+
+</details>
+
+:::
+
+## Required Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `schemaRegistryUrl` | `string` | Yes | The URL of your Azure Schema Registry (e.g., `https://your-namespace.servicebus.windows.net`). You can find this in the Azure Portal under your Event Hubs namespace. |
+| `services` | `array` | Yes | List of services and their schema mappings. **Note:** Unlike Confluent, Azure Schema Registry doesn't provide an API to list all schemas, so you must explicitly define which schemas to fetch. |
+
+## Optional Configuration Options
+
+### Services
+
+You can assign schemas to services (producers/consumers) in your architecture.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `services` | `array` | - | List of services to document with their schemas. |
+| `services[].id` | `string` | - | EventCatalog ID for the service (e.g., `orders-service`). |
+| `services[].name` | `string` | `services[].id` | Display name for the service (e.g., `Orders Service`). |
+| `services[].version` | `string` | - | Version of the service (e.g., `1.0.0`). |
+| `services[].sends` | `array` | - | Array of schema filters for messages this service sends. |
+| `services[].receives` | `array` | - | Array of schema filters for messages this service receives. |
+| `services[].writesTo` | `array[{id: string, version?: string}]` | - | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service writes to. |
+| `services[].readsFrom` | `array[{id: string, version?: string}]` | - | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service reads from. |
+
+### Schema Filters (sends/receives)
+
+Each schema in `sends` and `receives` arrays can have the following properties:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `id` | `string` | **Required** | The schema name in the Azure Schema Registry. |
+| `schemaGroup` | `string` | **Required** | The schema group name in the registry. |
+| `name` | `string` | `id` | Custom display name for the schema in EventCatalog. Useful for making technical schema names more user-friendly. |
+| `messageType` | `'event' \| 'command' \| 'query'` | `'event'` | The type of message this schema represents. |
+| `schemaRegistryUrl` | `string` | Global `schemaRegistryUrl` | Override the registry URL for this specific schema. Useful when schemas are in different Azure Schema Registries. |
+
+### Domains
+
+You can define and assign domains to organize your services.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `domain` | `object` | - | Optional domain configuration to group services. |
+| `domain.id` | `string` | - | EventCatalog ID for the domain (e.g., `orders-domain`). |
+| `domain.name` | `string` | - | Display name of the domain (e.g., `Orders Domain`). |
+| `domain.version` | `string` | - | Version of the domain (e.g., `1.0.0`). |
+
+### License
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `licenseKey` | `string` | From env var | EventCatalog Scale license key. Can also be set via the `EVENTCATALOG_SCALE_LICENSE_KEY` environment variable. |
+
+## Example Configurations
+
+### Basic Configuration
+
+Import schemas from Azure Schema Registry and assign them to services:
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      services: [
+        {
+          id: 'orders-service',
+          name: 'Orders Service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'order-created',
+              schemaGroup: 'com.example.orders',
+            },
+          ],
+          receives: [
+            {
+              id: 'payment-received',
+              schemaGroup: 'com.example.payments',
+            },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+
+### Custom Schema Names
+
+Provide user-friendly display names for your schemas:
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      services: [
+        {
+          id: 'orders-service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'app.orders.created.v1',
+              schemaGroup: 'com.example.orders',
+              name: 'Order Created Event', // Custom friendly name
+            },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+
+### Message Types (Events, Commands, Queries)
+
+Document different message types to better represent your architecture:
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      services: [
+        {
+          id: 'orders-service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'order-created',
+              schemaGroup: 'com.example.orders',
+              name: 'Order Created Event',
+              messageType: 'event', // Event message
+            },
+            {
+              id: 'create-order',
+              schemaGroup: 'com.example.orders',
+              name: 'Create Order Command',
+              messageType: 'command', // Command message
+            },
+          ],
+          receives: [
+            {
+              id: 'get-order',
+              schemaGroup: 'com.example.orders',
+              name: 'Get Order Query',
+              messageType: 'query', // Query message
+            },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+
+### Multiple Schema Registries
+
+Fetch schemas from multiple Azure Schema Registries in one configuration:
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      // Default registry URL
+      schemaRegistryUrl: 'https://primary-namespace.servicebus.windows.net',
+      services: [
+        {
+          id: 'orders-service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'order-created',
+              schemaGroup: 'com.example.orders',
+              // Uses default schemaRegistryUrl
+            },
+            {
+              id: 'order-shipped',
+              schemaGroup: 'com.example.shipping',
+              name: 'Order Shipped Event',
+              // Override to fetch from different registry
+              schemaRegistryUrl: 'https://shipping-namespace.servicebus.windows.net',
+            },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+
+### With Domains
+
+Organize your services into domains:
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      domain: {
+        id: 'orders-domain',
+        name: 'Orders Domain',
+        version: '1.0.0',
+      },
+      services: [
+        {
+          id: 'orders-service',
+          name: 'Orders Service',
+          version: '1.0.0',
+          sends: [
+            { id: 'order-created', schemaGroup: 'com.example.orders' },
+          ],
+        },
+        {
+          id: 'inventory-service',
+          name: 'Inventory Service',
+          version: '1.0.0',
+          receives: [
+            { id: 'order-created', schemaGroup: 'com.example.orders' },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+
+### Multiple Domains
+
+You can configure the plugin multiple times to document different domains:
+
+```js title="eventcatalog.config.js"
+generators: [
+  // Orders Domain
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      domain: {
+        id: 'orders-domain',
+        name: 'Orders Domain',
+        version: '1.0.0',
+      },
+      services: [
+        {
+          id: 'orders-service',
+          version: '1.0.0',
+          sends: [
+            { id: 'order-created', schemaGroup: 'com.example.orders' },
+          ],
+        },
+      ],
+    },
+  ],
+  // Payments Domain
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      domain: {
+        id: 'payments-domain',
+        name: 'Payments Domain',
+        version: '1.0.0',
+      },
+      services: [
+        {
+          id: 'payments-service',
+          version: '1.0.0',
+          sends: [
+            { id: 'payment-received', schemaGroup: 'com.example.payments' },
+          ],
+        },
+      ],
+    },
+  ],
+];
+```
+
+## Schema Group Naming
+
+Azure Schema Registry organizes schemas into schema groups. When configuring the plugin, make sure to use the exact schema group name as it appears in your Azure Schema Registry.
+
+Common schema group naming patterns:
+- Namespace style: `com.example.orders`, `com.example.payments`
+- Application style: `myapp-orders`, `myapp-inventory`
+- Environment-based: `production.orders`, `staging.orders`
+
+You can find your schema groups in the Azure Portal under your Event Hubs namespace > Schema Registry.
+
+## Supported Schema Formats
+
+The plugin supports the following schema formats from Azure Schema Registry:
+
+- **Avro** - Schemas with `.avsc` file extension
+- **JSON Schema** - Schemas with `.json` file extension
+
+The plugin automatically detects the schema format and generates the appropriate documentation in EventCatalog.
+
+## Troubleshooting
+
+### Authentication Issues
+
+If you encounter authentication errors:
+
+1. **Token not set**: Ensure `AZURE_SCHEMA_REGISTRY_TOKEN` environment variable is set
+2. **Token expired**: Azure access tokens expire after 1 hour. Re-run `az account get-access-token` to get a fresh token
+3. **Invalid token**: Verify you're using the correct resource (`https://eventhubs.azure.net`) when obtaining the token
+4. **Permission errors**: Ensure your Azure user/service principal has "Azure Event Hubs Data Receiver" or "Azure Event Hubs Data Owner" role on the Event Hubs namespace
+
+### Schema Not Found
+
+If the plugin can't find a schema:
+
+1. Verify the `schemaGroup` and `id` values match exactly what's in Azure Schema Registry
+2. Check that your authenticated user/identity has read permissions on the schema registry
+3. Ensure the schema exists in the specified schema group
+
+### License Key Issues
+
+If you have problems with your license key:
+
+1. Ensure `https://api.eventcatalog.cloud` is not blocked by your firewall
+2. Verify your license key is correctly set in the `.env` file or passed via configuration
+3. Check your license hasn't expired at [EventCatalog Cloud](https://eventcatalog.cloud)
+
+## Need Help?
+
+- [GitHub Issues](https://github.com/event-catalog/eventcatalog/issues)
+- [Discord Community](https://eventcatalog.dev/discord)
+- Email: hello@eventcatalog.dev
diff --git a/packages/core/docs/plugins/azure-schema-registry/03-features.md b/packages/core/docs/plugins/azure-schema-registry/03-features.md
new file mode 100644
index 000000000..517e0b8e5
--- /dev/null
+++ b/packages/core/docs/plugins/azure-schema-registry/03-features.md
@@ -0,0 +1,347 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog Azure Schema Registry plugin features
+sidebar_label: Features
+title: Features
+description: Features of the EventCatalog Azure Schema Registry plugin
+---
+
+# Features
+
+The EventCatalog Azure Schema Registry plugin provides a comprehensive set of features to help you document and visualize your Azure Event Hubs architecture.
+
+## Schema Import and Synchronization
+
+### Import Schemas from Azure Schema Registry
+
+The plugin connects to your Azure Schema Registry and imports schemas based on your configuration. Unlike some other registries, Azure Schema Registry requires explicit schema definitions since it doesn't provide a "list all schemas" API.
+
+```js
+{
+  schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+  services: [
+    {
+      id: 'orders-service',
+      version: '1.0.0',
+      sends: [
+        { id: 'order-created', schemaGroup: 'com.example.orders' },
+      ],
+    },
+  ],
+}
+```
+
+### Automatic Multi-Version Support
+
+The plugin automatically fetches and documents **the latest 5 versions** of each schema from Azure Schema Registry. This happens automatically without any configuration needed.
+
+**How it works:**
+1. Plugin fetches up to 5 most recent versions of each configured schema
+2. Latest version is written to the root directory (e.g., `/events/order-created/`)
+3. Older versions are stored in versioned folders (e.g., `/events/order-created/versioned/1/`)
+4. Custom documentation (markdown, badges, owners) is persisted between versions
+
+**Example:**
+If your `order-created` schema has versions 1, 2, 3, and 4:
+- Version 4 (latest) → `/events/order-created/` (root)
+- Version 3 → `/events/order-created/versioned/3/`
+- Version 2 → `/events/order-created/versioned/2/`
+- Version 1 → `/events/order-created/versioned/1/`
+
+**Benefits:**
+- Complete version history without extra configuration
+- See how schemas evolved over time
+- Compare different versions side-by-side
+- Understand breaking vs non-breaking changes
+- Teams can reference specific versions they're using
+
+This ensures your documentation stays in sync with your schemas while preserving the semantic meaning you've added across all versions.
+
+### Multiple Schema Formats
+
+The plugin supports both schema formats available in Azure Schema Registry:
+
+- **Avro** - Binary serialization format with compact data representation
+- **JSON Schema** - JSON-based schema definition for flexible data structures
+
+The plugin automatically detects the format and displays it correctly in your catalog.
+
+## Message Type Classification
+
+### Events, Commands, and Queries
+
+Document your messages using different types to better represent your architecture:
+
+```js
+sends: [
+  {
+    id: 'order-created',
+    schemaGroup: 'com.example.orders',
+    messageType: 'event', // Something that happened
+  },
+  {
+    id: 'create-order',
+    schemaGroup: 'com.example.orders',
+    messageType: 'command', // Request to do something
+  },
+],
+receives: [
+  {
+    id: 'get-order',
+    schemaGroup: 'com.example.orders',
+    messageType: 'query', // Request for information
+  },
+]
+```
+
+**Benefits:**
+- Clear architectural patterns in your documentation
+- Better understanding of message flow and intent
+- Improved discoverability for teams
+
+## Custom Schema Names
+
+### User-Friendly Display Names
+
+Provide readable names for technical schema identifiers:
+
+```js
+{
+  id: 'app.orders.created.v2.avro',
+  schemaGroup: 'com.company.orders',
+  name: 'Order Created Event', // User-friendly name
+}
+```
+
+**Benefits:**
+- Technical schema IDs preserved in the catalog
+- User-friendly names for documentation
+- Better search and discovery for non-technical users
+
+## Multi-Registry Support
+
+### Fetch from Multiple Azure Schema Registries
+
+Override the registry URL per schema to fetch from multiple registries:
+
+```js
+{
+  schemaRegistryUrl: 'https://primary-namespace.servicebus.windows.net',
+  services: [
+    {
+      id: 'orders-service',
+      version: '1.0.0',
+      sends: [
+        {
+          id: 'order-created',
+          schemaGroup: 'com.example.orders',
+          // Uses default registry
+        },
+        {
+          id: 'order-shipped',
+          schemaGroup: 'com.example.shipping',
+          schemaRegistryUrl: 'https://shipping-namespace.servicebus.windows.net',
+          // Uses different registry
+        },
+      ],
+    },
+  ],
+}
+```
+
+**Use Cases:**
+- Multi-region deployments
+- Separate registries for different business units
+- Development/staging/production registries
+- Legacy and new registry migrations
+
+## Domain-Driven Documentation
+
+### Organize Services into Domains
+
+Group related services into domains for better organization:
+
+```js
+{
+  domain: {
+    id: 'orders-domain',
+    name: 'Orders Domain',
+    version: '1.0.0',
+  },
+  services: [
+    { id: 'orders-service', version: '1.0.0', /* ... */ },
+    { id: 'inventory-service', version: '1.0.0', /* ... */ },
+  ],
+}
+```
+
+**Benefits:**
+- Logical grouping of related services
+- Better navigation for large architectures
+- Align with domain-driven design principles
+- Visualize domain boundaries
+
+## Flexible Authentication
+
+### REST API with Bearer Token
+
+The plugin uses Azure's REST API with Bearer token authentication for maximum compatibility and flexibility.
+
+#### Getting an Access Token
+
+**For Local Development:**
+```bash
+export AZURE_SCHEMA_REGISTRY_TOKEN=$(az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv)
+```
+
+**For CI/CD:**
+```bash
+# Using service principal
+export AZURE_SCHEMA_REGISTRY_TOKEN=$(az login --service-principal \
+  --username $AZURE_CLIENT_ID \
+  --password $AZURE_CLIENT_SECRET \
+  --tenant $AZURE_TENANT_ID && \
+  az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv)
+```
+
+**Benefits:**
+- Works across all environments
+- No Azure SDK packages required
+- Simple Bearer token authentication
+- Easy to integrate with CI/CD pipelines
+- Compatible with any Azure authentication method
+
+:::tip Token Expiration
+Azure access tokens typically expire after 1 hour. For long-running processes, you may need to refresh the token periodically.
+:::
+
+## Metadata Persistence
+
+### Preserve Custom Documentation
+
+When schemas are versioned, the plugin preserves:
+
+- **Custom markdown** - Your detailed documentation
+- **Badges** - Visual indicators and labels
+- **Owners** - Team and individual assignments
+- **Attachments** - Related files and links
+- **Repository links** - Source code references
+
+**Example:**
+
+```markdown
+# Order Created Event
+
+This event is emitted when a new order is successfully placed in the system.
+
+## Business Rules
+- Only emitted after payment is confirmed
+- Includes customer and line item details
+- Triggers inventory reservation
+
+## Related Documentation
+- [Order Processing Guide](link)
+- [Payment Integration](link)
+```
+
+This markdown persists when the schema is updated to version 2, 3, etc.
+
+## Service Documentation
+
+### Document Producers and Consumers
+
+Clearly define which services send and receive which messages:
+
+```js
+{
+  id: 'orders-service',
+  version: '1.0.0',
+  sends: [
+    { id: 'order-created', schemaGroup: 'com.example.orders' },
+  ],
+  receives: [
+    { id: 'payment-received', schemaGroup: 'com.example.payments' },
+  ],
+}
+```
+
+**In EventCatalog, you can see:**
+- All messages a service produces
+- All messages a service consumes
+- Service dependencies
+- Message flow visualization
+
+## Search and Discovery
+
+### Find Schemas Easily
+
+EventCatalog provides powerful search capabilities:
+
+- Search by schema name
+- Filter by domain
+- Filter by service
+- Filter by message type (event/command/query)
+- Full-text search across documentation
+
+## Versioning and History
+
+### Track Schema Evolution
+
+The plugin automatically imports the **latest 5 versions** of each schema, giving you complete visibility into schema evolution:
+
+**Features:**
+- **Automatic version import** - No configuration needed, fetches latest 5 versions
+- **Version timeline** - See all versions of each schema
+- **Side-by-side comparison** - Compare versions to understand changes
+- **Latest in root** - Current version easily accessible, older versions organized in versioned folders
+- **Breaking change detection** - Understand impact of schema changes
+- **Version-specific references** - Teams can reference the exact version they're using
+
+**Example Structure:**
+```
+/events/order-created/           ← Latest version (v4)
+/events/order-created/versioned/1/  ← Older version
+/events/order-created/versioned/2/  ← Older version
+/events/order-created/versioned/3/  ← Older version
+```
+
+This comprehensive versioning support helps teams understand how schemas have evolved and make informed decisions about upgrades.
+
+## Data Store Integration
+
+### Document Data Dependencies
+
+Link services to their data stores:
+
+```js
+{
+  id: 'orders-service',
+  version: '1.0.0',
+  writesTo: [
+    { id: 'orders-database', version: '1.0.0' },
+  ],
+  readsFrom: [
+    { id: 'customer-cache', version: '1.0.0' },
+  ],
+}
+```
+
+## Configuration Validation
+
+### Catch Errors Early
+
+The plugin validates your configuration and provides helpful error messages:
+
+- Missing required fields
+- Invalid schema group references
+- Authentication issues
+- Registry connectivity problems
+
+## Need a Feature?
+
+Have a feature request? Let us know:
+
+- [GitHub Discussions](https://github.com/event-catalog/eventcatalog/discussions)
+- [Discord Community](https://eventcatalog.dev/discord)
+- Email: hello@eventcatalog.dev
diff --git a/packages/core/docs/plugins/azure-schema-registry/04-examples.md b/packages/core/docs/plugins/azure-schema-registry/04-examples.md
new file mode 100644
index 000000000..718321c4a
--- /dev/null
+++ b/packages/core/docs/plugins/azure-schema-registry/04-examples.md
@@ -0,0 +1,378 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog Azure Schema Registry plugin examples
+sidebar_label: Examples
+title: Examples
+description: Examples of the EventCatalog Azure Schema Registry plugin
+---
+
+# Examples
+
+Explore real-world examples of using the Azure Schema Registry plugin with EventCatalog.
+
+## GitHub Examples Repository
+
+All examples are available in the EventCatalog generators repository:
+
+[View Azure Schema Registry Examples on GitHub](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry)
+
+## Available Examples
+
+### Basic Example
+
+**Get started quickly with a simple setup**
+
+This example demonstrates:
+- Connecting to Azure Schema Registry
+- Importing schemas from schema groups
+- Assigning schemas to services
+- Basic configuration setup
+
+[View Basic Example](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry/basic) (Coming Soon)
+
+### Message Types Example
+
+**Document events, commands, and queries**
+
+This example demonstrates:
+- Mapping schemas to different message types
+- Events for things that happened
+- Commands for requests to do something
+- Queries for requests for information
+- Clear architectural patterns
+
+[View Message Types Example](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry/message-types) (Coming Soon)
+
+### Multiple Registries Example
+
+**Fetch schemas from multiple Azure Schema Registries**
+
+This example demonstrates:
+- Default registry URL configuration
+- Per-schema registry URL overrides
+- Multi-region deployment patterns
+- Separate registries for different business units
+
+[View Multiple Registries Example](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry/multiple-registries) (Coming Soon)
+
+### Domain-Driven Design Example
+
+**Organize services into domains**
+
+This example demonstrates:
+- Domain configuration
+- Grouping related services
+- Domain visualization
+- Cross-domain dependencies
+
+[View Domain-Driven Design Example](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry/domains) (Coming Soon)
+
+### Custom Schema Names Example
+
+**User-friendly schema names**
+
+This example demonstrates:
+- Using technical schema IDs
+- Providing user-friendly display names
+- Better discoverability for non-technical users
+
+[View Custom Names Example](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry/custom-names) (Coming Soon)
+
+### Service Authentication Example
+
+**Different authentication methods**
+
+This example demonstrates:
+- Azure CLI authentication (local dev)
+- Service Principal authentication (CI/CD)
+- Managed Identity authentication (Azure-hosted)
+- Environment-specific configurations
+
+[View Authentication Example](https://github.com/event-catalog/generators/tree/main/examples/generator-azure-schema-registry/authentication) (Coming Soon)
+
+## Running the Examples
+
+Each example includes:
+
+1. **README.md** - Detailed instructions for running the example
+2. **eventcatalog.config.js** - Complete configuration
+3. **.env.example** - Template for environment variables
+4. **Sample data** - Mock schemas and configurations for testing
+
+### Prerequisites
+
+- Node.js 18 or higher
+- Azure CLI installed ([Install guide](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli))
+- Azure account with Event Hubs namespace
+- Azure Schema Registry with sample schemas
+- EventCatalog license key ([30-day trial available](https://eventcatalog.cloud))
+- Appropriate Azure permissions (`Azure Event Hubs Data Receiver` role)
+
+### Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/event-catalog/generators.git
+
+# Navigate to an example
+cd generators/examples/generator-azure-schema-registry/basic
+
+# Install dependencies
+npm install
+
+# Copy and configure environment variables
+cp .env.example .env
+# Edit .env with your EventCatalog license key
+
+# Authenticate with Azure
+az login
+
+# Get Azure access token and set it as environment variable
+export AZURE_SCHEMA_REGISTRY_TOKEN=$(az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv)
+
+# Verify token is set
+echo $AZURE_SCHEMA_REGISTRY_TOKEN
+
+# Run the generator
+npm run generate
+
+# Start the catalog
+npm run dev
+```
+
+:::tip One-Line Command
+You can also set the token and run the generator in one command:
+```bash
+AZURE_SCHEMA_REGISTRY_TOKEN=$(az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv) npm run generate
+```
+:::
+
+:::warning Token Expiration
+Azure access tokens expire after 1 hour. If you get authentication errors, refresh your token by running the `export AZURE_SCHEMA_REGISTRY_TOKEN=...` command again.
+:::
+
+## Example Patterns
+
+### Pattern 1: Single Service, Multiple Messages
+
+```js
+{
+  schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+  services: [
+    {
+      id: 'orders-service',
+      version: '1.0.0',
+      sends: [
+        { id: 'order-created', schemaGroup: 'com.example.orders' },
+        { id: 'order-updated', schemaGroup: 'com.example.orders' },
+        { id: 'order-cancelled', schemaGroup: 'com.example.orders' },
+      ],
+    },
+  ],
+}
+```
+
+**Use Case**: Document a single service that produces multiple related events.
+
+### Pattern 2: Multiple Services, Shared Messages
+
+```js
+{
+  schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+  services: [
+    {
+      id: 'orders-service',
+      version: '1.0.0',
+      sends: [
+        { id: 'order-created', schemaGroup: 'com.example.orders' },
+      ],
+    },
+    {
+      id: 'inventory-service',
+      version: '1.0.0',
+      receives: [
+        { id: 'order-created', schemaGroup: 'com.example.orders' },
+      ],
+    },
+    {
+      id: 'notifications-service',
+      version: '1.0.0',
+      receives: [
+        { id: 'order-created', schemaGroup: 'com.example.orders' },
+      ],
+    },
+  ],
+}
+```
+
+**Use Case**: Document multiple services that consume the same event.
+
+### Pattern 3: Command-Query Separation
+
+```js
+{
+  schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+  services: [
+    {
+      id: 'orders-api',
+      version: '1.0.0',
+      sends: [
+        { id: 'create-order', schemaGroup: 'com.example.orders', messageType: 'command' },
+        { id: 'update-order', schemaGroup: 'com.example.orders', messageType: 'command' },
+      ],
+      receives: [
+        { id: 'get-order', schemaGroup: 'com.example.orders', messageType: 'query' },
+        { id: 'list-orders', schemaGroup: 'com.example.orders', messageType: 'query' },
+      ],
+    },
+    {
+      id: 'orders-processor',
+      version: '1.0.0',
+      receives: [
+        { id: 'create-order', schemaGroup: 'com.example.orders', messageType: 'command' },
+        { id: 'update-order', schemaGroup: 'com.example.orders', messageType: 'command' },
+      ],
+      sends: [
+        { id: 'order-created', schemaGroup: 'com.example.orders', messageType: 'event' },
+        { id: 'order-updated', schemaGroup: 'com.example.orders', messageType: 'event' },
+      ],
+    },
+  ],
+}
+```
+
+**Use Case**: Implement CQRS pattern with clear separation of commands and queries.
+
+### Pattern 4: Multi-Domain Architecture
+
+```js
+generators: [
+  // Orders Domain
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      domain: {
+        id: 'orders-domain',
+        name: 'Orders Domain',
+        version: '1.0.0',
+      },
+      services: [
+        { id: 'orders-service', version: '1.0.0', /* ... */ },
+        { id: 'inventory-service', version: '1.0.0', /* ... */ },
+      ],
+    },
+  ],
+  // Payments Domain
+  [
+    '@eventcatalog/generator-azure-schema-registry',
+    {
+      schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
+      domain: {
+        id: 'payments-domain',
+        name: 'Payments Domain',
+        version: '1.0.0',
+      },
+      services: [
+        { id: 'payments-service', version: '1.0.0', /* ... */ },
+      ],
+    },
+  ],
+];
+```
+
+**Use Case**: Organize large architectures into bounded contexts.
+
+### Pattern 5: Multi-Region with Registry Overrides
+
+```js
+{
+  schemaRegistryUrl: 'https://us-east-namespace.servicebus.windows.net',
+  services: [
+    {
+      id: 'global-orders-service',
+      version: '1.0.0',
+      sends: [
+        {
+          id: 'order-created',
+          schemaGroup: 'com.example.orders',
+          // US East registry
+        },
+        {
+          id: 'order-created-eu',
+          schemaGroup: 'com.example.orders',
+          schemaRegistryUrl: 'https://eu-west-namespace.servicebus.windows.net',
+          // EU West registry
+        },
+      ],
+    },
+  ],
+}
+```
+
+**Use Case**: Document multi-region deployments with separate registries.
+
+## Testing Locally
+
+### Using Docker Compose for Local Testing
+
+While Azure Schema Registry requires an Azure account, you can test the plugin configuration locally using mock data:
+
+```bash
+# In the example directory
+npm run generate:mock  # Uses mock schemas for testing
+
+npm run dev  # View the catalog locally
+```
+
+### With Azure Dev/Test Environment
+
+For testing with real Azure Schema Registry:
+
+```bash
+# Step 1: Create a development schema registry (one-time setup)
+az eventhubs namespace create \
+  --name your-dev-namespace \
+  --resource-group your-resource-group \
+  --location eastus \
+  --sku Standard
+
+# Step 2: Register test schemas
+az eventhubs eventhub schema-registry create \
+  --namespace-name your-dev-namespace \
+  --resource-group your-resource-group \
+  --name com.example.test
+
+# Step 3: Get access token
+export AZURE_SCHEMA_REGISTRY_TOKEN=$(az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv)
+
+# Step 4: Run the generator
+npm run generate
+
+# Step 5: View the catalog
+npm run dev
+```
+
+:::info Azure Resource Setup
+Make sure you have the appropriate permissions on the Azure resources. You need at least the `Azure Event Hubs Data Receiver` role on the Event Hubs namespace.
+:::
+
+## Contributing Examples
+
+Have a great example you'd like to share? We'd love to include it!
+
+1. Fork the [generators repository](https://github.com/event-catalog/generators)
+2. Create your example in `examples/generator-azure-schema-registry/`
+3. Include a detailed README
+4. Submit a pull request
+
+## Need Help?
+
+Can't find an example for your use case?
+
+- [Ask in Discord](https://eventcatalog.dev/discord)
+- [Open a GitHub Discussion](https://github.com/event-catalog/eventcatalog/discussions)
+- Email: hello@eventcatalog.dev
+
+We're here to help you get the most out of EventCatalog!
diff --git a/packages/core/docs/plugins/azure-schema-registry/_category_.json b/packages/core/docs/plugins/azure-schema-registry/_category_.json
new file mode 100644
index 000000000..c9d38e4b5
--- /dev/null
+++ b/packages/core/docs/plugins/azure-schema-registry/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Azure Schema Registry Plugin",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "azure-schema-registry",
+    "title": "Azure Schema Registry",
+    "description": "Azure Schema Registry integration for EventCatalog"
+  }
+}
diff --git a/packages/core/docs/plugins/backstage/00-intro.md b/packages/core/docs/plugins/backstage/00-intro.md
new file mode 100644
index 000000000..c8af195fe
--- /dev/null
+++ b/packages/core/docs/plugins/backstage/00-intro.md
@@ -0,0 +1,67 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Getting started
+description: Getting started with Backstage plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/mjf7qwoSAC4?si=eBZfgjMOQrD75teb" 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>
+
+---
+
+Many folks are using [Backstage](https://backstage.spotify.com/) for their internal developer portals. Backstage is a highly configurable platform that allows you to document your architecture in components, apis, services, domains and much more.
+
+Backstage supports plugins, that have a frontend and backend support.
+
+Using the EventCatalog Backstage plugin you can embed your EventCatalog information into backstage.
+
+### Core Features
+
+The EventCatalog Backstage plugin can provide you with many features:
+
+- 📃 Bring [EventCatalog documentation](https://demo.eventcatalog.dev/docs/domains/Orders/0.0.3) into Backstage
+- 📃 Custom tabs for your APIs and Services. Embed documentation, visualizations and searchable tables.
+- 📊 Embed [EventCatalog visualizer](https://demo.eventcatalog.dev/visualiser/domains/Orders/0.0.3) into your Backstage pages
+- 🔎 Embed the [EventCatalog discovery table](https://demo.eventcatalog.dev/discover/events) to quickly find messages for your services
+- ⭐ And much more...
+
+### How it works
+
+![Example](/img/integrations/backstage/backstage-eventcatalog.png)
+
+This plugin exposes React components that you can embed on your pages to display information from EventCatalog.
+
+_Your EventCatalog has be hosted and the URL given to the app.config.yml file._
+
+- `<EventCatalogDocumentationEntityPage page="docs/page/visualiser"  />`
+  - Used to embed whole pages of EventCatalog into your Backstage instance. You can add these as tabs to your pages, clicking on the tab will show the desired feature.
+- `<EventCatalogEntityVisualiserCard />`
+  - Used to embed a widget (Card) on your existing pages. This component will display the visualiser on your page.
+- `<EventCatalogEntityMessageCard />`
+  - Used to embed a widget (Card) on your existing pages. This component will display the explore (table) on your page. Great for displaying a list of messages your service produces/consumes.
+
+_Note: If you want to embed private EventCatalog instances, raise an issue on GitHub and we can explore this_.
+
+---
+
+## Commercial Use
+
+This plugin requires an EventCatalog Scale license key to be used.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+You can try the Backstage plugin, or use EventCatalog Scale (as it's already included).
+
+After the trial, you can continue using this plugin with EventCatalog Scale. 
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
diff --git a/packages/core/docs/plugins/backstage/01-installation.md b/packages/core/docs/plugins/backstage/01-installation.md
new file mode 100644
index 000000000..635712e72
--- /dev/null
+++ b/packages/core/docs/plugins/backstage/01-installation.md
@@ -0,0 +1,242 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Installation
+title: Installation
+description: Installation instructions for the EventCatalog Backstage plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#commercial-use" />
+
+:::info Using Backstage plugin version 1.0.0?
+
+We introduced some breaking changes in the plugin, and the ways you map your resources to EventCatalog resources.
+
+We recommend using the latest version of the plugin. You can read the [migration guide](#migrating-from--100-to-100) to help you upgrade.
+
+:::
+
+---
+
+## Configuring EventCatalog for Backstage
+
+You will need an EventCatalog Scale license key to use the Backstage integration.
+
+You can get a 30-day trial Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+Once you have an EventCatalog Scale license key, you will need to build and deploy your EventCatalog with the license key set.
+
+#### 1. Setting license key in `.env` file (recommended)
+
+<AddedIn version="2.35.4" />
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+:::tip Using an Older API Key?
+
+If you already have an older Backstage plugin key, you can still use it with the Backstage-specific environment variable.
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_BACKSTAGE=your-license-key
+```
+
+:::
+
+This will enable you to use EventCatalog within backstage.
+
+## Configuring Backstage to use EventCatalog
+
+### 1. Install the plugin on Backstage
+
+First install the plugin in your Backstage instance.
+
+```sh
+yarn add @eventcatalog/backstage-plugin-eventcatalog
+```
+
+### 2. Add the EventCatalog URL to the app-config.yaml
+
+The EventCatalog plugin needs to know the URL of your EventCatalog instance. This can be set in the `app-config.yaml` file.
+
+```yaml
+eventcatalog:
+  URL: "https://demo.eventcatalog.dev"
+```
+
+### 3. Mapping Backstage resources to EventCatalog resources with annotations
+
+Backstage and EventCatalog have different ways to create resources. For example backstage supports components, APIS, domains, systems etc, and EventCatalog supports resources (domains, services and messages (queries, commands and events)).
+
+When you configure the plugin you need to map Backstage information to EventCatalog information, so the plugin knows which EventCatalog page to render.
+
+We do this by adding annotations to the Backstage resources.
+
+<!-- Make table -->
+
+| Annotation | Required | Default | Description |
+|------------|----------|---------|-------------|
+| `eventcatalog.dev/id` | Yes | - | The id of the resource in EventCatalog |
+| `eventcatalog.dev/version` | No | `latest` | The version of the resource in EventCatalog |
+| `eventcatalog.dev/collection` | No | Uses the entity kind | The collection of the resource in EventCatalog. Options include `services`, `domains`, `queries`, `commands`, `events` |
+
+Example of creating a new service in Backstage and mapping it to an EventCatalog resource:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backend-service
+  description: Backend API service
+  annotations:
+    github.com/project-slug: organization/backend-repo
+    # Here we map the Backstage service to an EventCatalog resource
+    # The id of the resource in EventCatalog
+    eventcatalog.dev/id: InventoryService
+    # The version of the resource in EventCatalog
+    eventcatalog.dev/version: 0.0.2
+    # The collection of the resource in EventCatalog
+    eventcatalog.dev/collection: services
+  tags:
+    - nodejs
+    - express
+    - api
+spec:
+  type: service
+  lifecycle: production
+  owner: team-name
+  system: example-system
+  providesApis:
+    - backend-api
+  dependsOn:
+    - resource:default/database
+```
+
+### 4. Using the components in Backstage
+
+You have two options to use the components in Backstage:
+
+- [Embed EventCatalog as a tabbed page](#tabbed-pages)
+- [Embed EventCatalog as a card component](#card-components)
+
+#### Tabbed pages
+
+The `EventCatalogDocumentationEntityPage` components, is a full page component that you can assign to any `EntityLayout.Route`. 
+
+```js
+import { EventCatalogDocumentationEntityPage } from "@eventcatalog/backstage-plugin-eventcatalog";
+```
+
+You can import the `EventCatalogDocumentationEntityPage` component to render EventCatalog pages as full pages in your Backstage entity.
+
+**Rendered output example:**
+
+![EventCatalog Pages](/img/integrations/backstage/eventcatalog-pages.png)
+
+**Usage Example:**
+
+```js
+// Will create a new tab called "Docs" and route called /eventcatalog. This will embed the docs for that
+// entity in your page. Using the info from the app-config to map your Backstage ID to EventCatalog ID
+<EntityLayout.Route path="/eventcatlaog" title="Docs">
+  <EventCatalogDocumentationEntityPage page='docs' />
+</EntityLayout.Route>
+
+// Will create a new tab called "Visualzer" and route called /eventcatalog-visualizer.
+// This will embed the EventCatalog visualiser to your Backstage entity
+<EntityLayout.Route path="/eventcatlaog-visualizer" title="Visualzer">
+  <EventCatalogDocumentationEntityPage page='visualiser' />
+</EntityLayout.Route>
+
+// Will create a new tab called "Entity Map" and route called /eventcatalog-entity-map.
+// This will embed the EventCatalog entity map to your Backstage entity
+<EntityLayout.Route path="/eventcatlaog-entity-map" title="Entity Map">
+  <EventCatalogDocumentationEntityPage page='entity-map' />
+</EntityLayout.Route>
+
+// Will create a new tab called "Schema Explorer" and route called /eventcatalog-schema-explorer.
+<EntityLayout.Route path="/eventcatlaog-schema-explorer" title="Schema Explorer">
+  <EventCatalogDocumentationEntityPage page='schema-explorer' />
+</EntityLayout.Route>
+
+// Override the id, collection and version of the resource in EventCatalog
+// you can choose to override what is rendered, (not read from your backstage configuration)
+<EntityLayout.Route path="/eventcatlaog-entity-map" title="Entity Map">
+  <EventCatalogDocumentationEntityPage page='entity-map' id="MyDomainId" collection="domains" version="0.0.1" />
+</EntityLayout.Route>
+
+```
+
+#### Card components
+
+These components can be added to your pages as Cards, that can live inside the Backstage Grid System.
+
+![EventCatalog Card Components](/img/integrations/backstage/eventcatalog-card-components.png)
+![EventCatalog Card Components](/img/integrations/backstage/eventcatalog-card-component-entitymap.png)
+
+```jsx
+import {
+  EventCatalogEntityVisualiserCard,
+  EventCatalogEntityMessageCard,
+} from "@eventcatalog/backstage-plugin-eventcatalog";
+
+<Grid container spacing={3} alignItems="stretch">
+  <Grid item md={6}>
+    <!-- Backstage card -->
+    <EntityAboutCard variant="gridItem" />
+  </Grid>
+  <Grid item md={6}>
+    <!-- Adds the visualizer to a grid item in Backstage -->
+    <EventCatalogEntityVisualiserCard />
+  </Grid>
+  <Grid item md={6} xs={12}>
+    <!-- Adds the explore (messages) to a grid item in Backstage -->
+    <EventCatalogEntityMessageCard />
+  </Grid>
+  <Grid item md={6} xs={12}>
+    <!-- Adds the entity map to a grid item in Backstage -->
+    <EventCatalogEntityEntityMapCard />
+  </Grid>
+</Grid>;
+```
+
+---
+
+## Migrating from < 1.0.0
+
+We introduced some breaking changes in the plugin, and the ways you map your resources to EventCatalog resources.
+
+Previously you mapped your resources to EventCatalog resources in the `app-config.yaml` file.
+
+```yaml
+eventcatalog:
+  services:
+    - backstage-name: "backend-service"
+      eventcatalog-id: "InventoryService"
+```
+
+Now you have to use annotations to map your resources to EventCatalog resources.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backend-service
+  annotations:
+    eventcatalog.dev/id: "InventoryService"
+    eventcatalog.dev/version: "0.0.2"
+    eventcatalog.dev/collection: "services"
+```
+
+This are the preferred ways to map your resources to EventCatalog resources and following Backstage best practices.
+
+## Demo
+
+If you want to learn how the code works in a basic demo [you can see our demo on GitHub](https://github.com/event-catalog/backstage-eventcatalog-demo).
diff --git a/packages/core/docs/plugins/backstage/02-api.md b/packages/core/docs/plugins/backstage/02-api.md
new file mode 100644
index 000000000..54aa77cf4
--- /dev/null
+++ b/packages/core/docs/plugins/backstage/02-api.md
@@ -0,0 +1,51 @@
+---
+sidebar_position: 1
+keywords:
+  - backstage
+sidebar_label: Backstage configuration
+title: Backstage configuration
+description: Getting started with Backstage and EventCatalog plugin
+---
+
+## Overview {#overview}
+
+Add the following to your `app-config.yaml` file.
+
+```yaml title="app-config.yaml"
+# Backstage configrations...
+
+# eventcatalog plugin configuration
+eventcatalog:
+  # URL of your catalog (has to be public, if private please raise and issue and we can fix this)
+  URL: "https://demo.eventcatalog.dev"
+```
+
+### Mapping your resources
+
+You can use backstage `annotations` to map your resources to EventCatalog resources.
+
+```yaml title="example-service.yaml"
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: example-service
+  annotations:
+    # The id of the resource in EventCatalog
+    eventcatalog.dev/id: "example-service"
+    # The version of the resource in EventCatalog (optional, latest is used if not provided)
+    eventcatalog.dev/version: "1.0.0" 
+    # The collection of the resource in EventCatalog (optional, uses the entity kind if not provided)
+    eventcatalog.dev/collection: "services"
+```
+
+| Annotation | Required | Default | Description |
+|------------|----------|---------|-------------|
+| `eventcatalog.dev/id` | Yes | - | The id of the resource in EventCatalog |
+| `eventcatalog.dev/version` | No | `latest` | The version of the resource in EventCatalog |
+| `eventcatalog.dev/collection` | No | Uses the entity kind | The collection of the resource in EventCatalog. Options include `services`, `domains`, `queries`, `commands`, `events` |
+
+
+
+
+Looking for more mappings? Let us know! Raise an issue on [GitHub](https://github.com/event-catalog/backstage-plugin-eventcatalog).
+
diff --git a/packages/core/docs/plugins/backstage/03-examples.md b/packages/core/docs/plugins/backstage/03-examples.md
new file mode 100644
index 000000000..8f46faedd
--- /dev/null
+++ b/packages/core/docs/plugins/backstage/03-examples.md
@@ -0,0 +1,12 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the AsyncAPI plugin
+---
+
+You can find an example of how to use Backstage and EventCatalog in the [EventCatalog Backstage Demo repository](https://github.com/event-catalog/backstage-eventcatalog-demo).
+
+Or you can watch a video tutorial on [how to setup Backstage and EventCatalog](https://www.youtube.com/watch?v=mjf7qwoSAC4).
\ No newline at end of file
diff --git a/packages/core/docs/plugins/backstage/_category_.json b/packages/core/docs/plugins/backstage/_category_.json
new file mode 100644
index 000000000..98cf6a0f8
--- /dev/null
+++ b/packages/core/docs/plugins/backstage/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Backstage Plugin",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "backstage",
+    "title": "Backstage",
+    "description": "Backstage integration with EventCatalog"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/plugins/confluent-schema-registry/00-intro.md b/packages/core/docs/plugins/confluent-schema-registry/00-intro.md
new file mode 100644
index 000000000..cb0a007a6
--- /dev/null
+++ b/packages/core/docs/plugins/confluent-schema-registry/00-intro.md
@@ -0,0 +1,90 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Introduction
+description: Getting started with AsyncAPI plugin
+---
+
+
+<!-- import PluginLicense from '@site/src/components/MDX/PluginLicense'; -->
+
+<!-- <PluginLicense url="#commercial-use" /> -->
+
+<iframe width="100%" height="515" src="https://www.youtube.com/embed/NMZKnPKx-L0?si=og1Nvnr3FfPfAqn4" 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>
+
+---
+
+Many folks building event-driven architecture are using [Apache Kafka](https://kafka.apache.org/) as their broker of choice. 
+
+[Confluent](https://www.confluent.io/) is a popular provider for Kafka and has a [Schema Registry](https://docs.confluent.io/platform/current/schema-registry/index.html) that can be used to store and manage your schemas.
+
+We believe schema registries can only go so far, and there is a lot of value adding semantic meaning to your schemas, assigning them owners, topics, services and domains.
+
+The [EventCatalog Confluent Schema Registry plugin](https://github.com/event-catalog/generators/tree/main/packages/generator-confluent-schema-registry) allows you to import your schemas into EventCatalog and keep them in sync along side your documentation. You can visualize your architecture and unlock value from your schema registries.
+
+:::info
+**What is Confluent Schema Registry?**: A schema registry for Apache Kafka. Use this to store and manage your schemas. You can read more about it on the [Confluent website](https://docs.confluent.io/platform/current/schema-registry/index.html).
+:::
+
+### Core Features of the Confluent Schema Registry plugin
+
+The EventCatalog Confluent Schema Registry plugin can provide you with many features:
+
+- ⭐️ Import your schemas from your Confluent Schema Registry into EventCatalog
+- ⭐️ Keep schemas in sync with your architecture documentation
+- ⭐️ Automatic versioning, as your schemas change they are versioned in EventCatalog along side your documentation
+- ⭐️ Add semantic meaning (markdown) to your schemas. Provide business context to your schemas and added value.
+- ⭐️ Use custom filters (prefix, suffix, includes) to select which schemas to import
+- ⭐️ Assign schemas to topics, services, domains and owners
+- ⭐️ Document your schemas as commands or events.
+- ⭐️ Visualize your kafka architecture with the [EventCatalog Visualizer](/features/visualization)
+- ⭐️ Download and view schemas in EventCatalog (AVRO, JSON, Protobuf)
+- ⭐️ Talk to your schemas, topics, producers and consumers with the [EventCatalog Chat](/features/ai-assistant)
+- ⭐️ and more....
+
+### How it works
+
+1. Install the Confluent Schema Registry plugin
+1. Configure the plugin (example; schemas, topics, commands, events,services, domains)
+1. Run the plugin to import your schemas into EventCatalog
+1. View and deploy your catalog
+
+![Example](/img/integrations/confluent-schema-registry/confluent.png)
+
+**What are generators?**
+
+EventCatalog supports [generators](/docs/plugins/generators). These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an [SDK](/docs/sdk) to give developers easier access to their catalogs through custom scripts or generators.
+
+The EventCatalog Confluent Schema Registry plugin is a generator. It will import your schemas from your Confluent Schema Registry into EventCatalog.
+
+## Commercial and License
+
+This plugin requires an EventCatalog Scale license key to be used.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial, you can continue using this plugin with EventCatalog Scale.
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## Need a demo?
+
+If you would like a demo of the plugin, please feel free to reach out to us and book a time to chat at hello@eventcatalog.dev.
+
+## License FAQ
+
+### What is the license key for?
+The EventCatalog Scale license key is required to use the Confluent Schema Registry plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get an EventCatalog Scale license key?
+You can obtain an EventCatalog Scale license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 30-day free trial.
+
+### Terms
+- **Trial Period**: 30-day free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can continue with EventCatalog Scale through [EventCatalog Cloud](https://eventcatalog.cloud).
diff --git a/packages/core/docs/plugins/confluent-schema-registry/01-installation.md b/packages/core/docs/plugins/confluent-schema-registry/01-installation.md
new file mode 100644
index 000000000..ed1e7aeeb
--- /dev/null
+++ b/packages/core/docs/plugins/confluent-schema-registry/01-installation.md
@@ -0,0 +1,231 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Confluent Schema Registry
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog Confluent Schema Registry plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PluginLicense url="#commercial-use" />
+
+The Confluent Schema Registry plugin is used to generate a catalog from a Confluent Schema Registry and import your schemas into EventCatalog.
+
+You can map your schemas from your Confluent Schema Registry to commands, events in your catalog, and assign these to services and domains.
+
+## Installation
+
+Run the command below to install the EventCatalog Confluent Schema Registry plugin.
+
+:::tip "Don't have an EventCatalog project yet?"
+If you don't have an EventCatalog project yet, you can follow the instructions in the [Getting Started](/docs/development/getting-started/installation) guide.
+:::
+
+<Tabs>
+  <TabItem value="apple" label="Install on existing catalog" default>
+    ```bash
+npm i @eventcatalog/generator-confluent-schema-registry
+```
+  </TabItem>
+  <TabItem value="orange" label="Create new catalog with Confluent Schema Registry plugin">
+     ```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --template confluent-schema-registry
+```
+  </TabItem>
+</Tabs>
+
+## Configuration
+
+To use the plugin you need to configure it in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators` array.
+
+<Tabs>
+  <TabItem value="apple" label="Import all schemas" default>
+
+  In this example we import all schemas from a Confluent Schema Registry.
+
+  You can also create topics, and assign schemas to producers/consumers and domains. [(see examples)](/docs/plugins/confluent-schema-registry/plugin-configuration#example-configurations).
+
+
+  
+    ```js title="eventcatalog.config.js"
+    // ...
+    generators: [
+      // 1. Import all schemas from a Confluent Schema Registry
+      [
+        '@eventcatalog/generator-confluent-schema-registry',
+        {
+          // The URL of your Confluent Schema Registry
+          schemaRegistryUrl: 'http://localhost:8081',
+          // Do you want to include all versions of a schema? (default: false)
+          includeAllVersions: true
+        },
+      ],
+    ];
+    ```
+  </TabItem>
+  <TabItem value="orange" label="Import schemas, assign them to topics, services and domains">
+
+In this example we document topics from kafka, assign schemas to them, and schemas to producers/consumers (services).
+We create two domains, the `retail-domain` and the `communications-domain`.
+
+:::info "Why do we configure the plugin twice?"
+The generator can be configured as many times as you want.
+In this example we configure the plugin twice, the first time we import and create the `retail-domain` and the second time we assign the schemas to the `communications-domain`.
+:::
+
+```js title="eventcatalog.config.js"
+// ...
+ [
+  '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The topics (channels) to assign schemas to (optional)
+        topics: [{
+          id: 'orders-topic',
+          name: 'Orders Topic',
+          address: 'kafka-cluster-bootstrap:9092',
+        }, {
+          id: 'inventory-topic',
+          name: 'Inventory Topic',
+          address: 'kafka-cluster-bootstrap:9092',
+        }],
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // the messages this service sends, this example sends events with a prefix of 'order-' to the 'orders-topic'
+            sends: [{ events: { prefix: 'order-' }, topic: 'orders-topic' }],
+            // the messages this service receives, this example receives events with a prefix of 'analytics-' from the 'inventory-topic'
+            receives: [{ events: { prefix: 'analytics-' }, topic: 'inventory-topic' }],
+          },
+          {
+            id: 'Inventory Service',
+            version: '1.0.0',
+            // the messages this service sends, this example sends events with a prefix of 'inventory-' to the 'inventory-topic'
+            sends: [{ events: { prefix: 'inventory-' }, topic: 'inventory-topic' }],
+            // the messages this service receives, this example receives events with a prefix of 'order-' from the 'orders-topic'
+            receives: [{ events: { prefix: 'order-' }, topic: 'orders-topic' }],
+          },
+        ],
+        domain: {
+          id: 'retail-domain',
+          name: 'Retail Domain',
+          version: '1.0.0',
+        }
+      },
+    ],
+  [
+    '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The topics (channels) to assign schemas to (optional)
+        topics: [{
+          id: 'users-topic',
+          name: 'Users Topic',
+          address: 'kafka-cluster-bootstrap:9092',
+        }, {
+          id: 'shipments-topic',
+          name: 'Shipments Topic',
+          address: 'kafka-cluster-bootstrap:9092',
+        }],
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Notifications Service',
+            version: '1.0.0',
+            receives: [
+              // the messages this service receives, this example receives events with a prefix of 'user-registered' from the 'users-topic'
+              { events: ['user-registered'], topic: 'users-topic' },
+              // the messages this service receives, this example receives events with a prefix of 'shipment-created' from the 'shipments-topic'
+              { events: ['shipment-created'], topic: 'shipments-topic' },
+              // the messages this service receives, this example receives events with a prefix of 'payment-received' from the 'payments-topic'
+              { events: ['payment-received'] }
+            ],
+          },
+        ],
+        domain: {
+          id: 'communications-domain',
+          name: 'Communications Domain',
+          version: '1.0.0',
+        }
+      },
+  ],
+```  
+  </TabItem>
+</Tabs>
+
+### Configure API keys
+
+The EventCatalog Confluent Schema Registry plugin requires API keys in your environment variables.
+
+1. An EventCatalog Scale license key for the Confluent Schema Registry plugin (30-day trial, at [EventCatalog Cloud](https://eventcatalog.cloud))
+2. Confluent Schema Registry API keys (found in the [Confluent Cloud](https://confluent.cloud) console)
+
+Create a `.env` file in the root, and add your keys to the project.
+
+```bash title=".env"
+# EventCatalog license key
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+
+# Confluent Schema Registry API Keys
+CONFLUENT_SCHEMA_REGISTRY_KEY=your-confluent-schema-registry-key
+CONFLUENT_SCHEMA_REGISTRY_SECRET=your-confluent-schema-registry-key-secret
+```
+
+:::tip Using an Older API Key?
+
+If you already have an older Confluent Schema Registry plugin key, you can still use it with the plugin-specific environment variable.
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_CONFLUENT_SCHEMA_REGISTRY=your-license-key
+```
+
+:::
+
+#### White listing EventCatalog domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+#### Run the plugin
+
+Run the plugin to import your schemas into EventCatalog.
+
+_This command will run the generators in your eventcatalog.config.js file._
+
+```
+npm run generate
+```
+
+#### View your catalog
+
+Run your catalog locally to see the changes
+
+```
+npm run dev
+```
+
+#### Build your catalog for production
+
+```
+npm run build
+```
+
+
+
+## Any questions or need help?
+
+If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
+
+You can also find some examples of the plugin in action in our examples repository: [eventcatalog/examples](https://github.com/event-catalog/generators/tree/main/examples/generator-confluent-schema-registry).
+
diff --git a/packages/core/docs/plugins/confluent-schema-registry/02-plugin-configuration.md b/packages/core/docs/plugins/confluent-schema-registry/02-plugin-configuration.md
new file mode 100644
index 000000000..35d428523
--- /dev/null
+++ b/packages/core/docs/plugins/confluent-schema-registry/02-plugin-configuration.md
@@ -0,0 +1,473 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Confluent Schema Registry plugin
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog Confluent Schema Registry plugin
+---
+
+# Plugin Configuration
+
+## Overview
+
+The EventCatalog Confluent Schema Registry plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+:::info API Keys
+If you are using Confluent Cloud, you need to export your API keys as environment variables in the `.env` file.
+
+<details>
+<summary>Example .env file</summary>
+
+```bash
+export CONFLUENT_SCHEMA_REGISTRY_KEY=your-confluent-schema-registry-key
+export CONFLUENT_SCHEMA_REGISTRY_SECRET=your-confluent-schema-registry-key-secret
+```
+
+</details>
+
+:::
+
+## Required Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `schemaRegistryUrl` | `string` | Yes | The URL of your Confluent Schema Registry. You can find this in the Confluent Cloud dashboard. If you are running locally you can use the `http://localhost:8081` endpoint. |
+| `includeAllVersions` | `boolean` | No | If true, all versions of the schemas will be imported into EventCatalog (default is `false`). |
+
+
+
+## Optional Configuration Options
+
+### Services
+
+You can assign the schemas to a producer or consumer (service).
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `services` | object | - | List of producers/consumers (services) to assign the schemas to. |
+| `services.id` | string | - | EventCatalog ID for the service. |
+| `services.sends` | Filter | - | Configuration to assign schemas to a producer. The schemas and topic defined here will be assigned to the producer. |
+| `services.receives` | Filter | - | Configuration to assign schemas to a consumer. The schemas and topic defined here will be assigned to the consumer. |
+| `services.writesTo` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service writes to. (Added in v0.2.1) |
+| `services.readsFrom` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service reads from. (Added in v0.2.1) |
+
+### Topics
+
+You can document the topics for your schemas. These are channels in EventCatalog.
+Schemas are mapped to their topics.
+
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topics` | object | - | Optional list of topics to assign the schemas to. (optional). [These are documented as channels](/docs/development/guides/resources/messages/message-channels/introduction) in EventCatalog. |
+| `topics.id` | string | - | EventCatalog ID for the topic (e.g `orders-topic`). |
+| `topics.name` | string | - | Name of the topic (e.g `Orders Topic`). |
+| `topics.address` | string | - | Address of the topic (e.g `kafka-cluster-1.us-east-1.confluent.cloud:9092`). |
+
+### Domains
+
+You can define and assign domains to your services.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `domain.id` | string | - | EventCatalog ID for the domain (e.g `orders-domain`). |
+| `domain.name` | string | - | Name of the domain (e.g `Orders Domain`). |
+| `domain.version` | string | - | Version of the domain (e.g `1.0.0`). |
+
+### Filtering schemas to producers and consumers
+
+When you assign schemas to a producer or consumer (service), you can use a range of filtering options including:(suffixes, prefixes, includes or exact matches).
+
+Here are some examples of how to filter schemas to producers and consumers.
+
+<details>
+<summary>`exact` matching example - Match schemas that exactly match the specified name</summary>
+
+**What is exact matching?**
+
+Exact matching is when the schema name exactly matches the specified name.
+
+In this example, the `Orders Service` will send `events` with the schema name `order-placed`, `order-cancelled` and receive `commands` with the schema name `place-order`.
+
+Example schemas (subjects) in Confluent Schema Registry:
+
+- `order-placed-value`
+- `order-cancelled-value`
+- `place-order-value`
+- `cancel-order-value`
+
+_Note: EventCatalog matches the `subject` of the schema in the registry. The `subject` in the registry has a suffix of `-value`. This is automatically removed when the schema is assigned to a producer or consumer. So you need to match the `subject` without the `-value` suffix._
+
+```js
+// ...
+generators: [
+  // Import schemas (using filters), assign them to topics, services and domains
+  [
+    '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that match the schema name `order-placed` or `order-cancelled`
+            sends: [{ events: ['order-placed', 'order-cancelled']},
+            // The Order services receives commands that match the schema name `place-order` or `cancel-order`
+            receives: [{ commands: ['place-order', 'cancel-order']},
+          }
+        ],
+      },
+  ],
+];
+``` 
+
+</details>
+
+
+<details>
+<summary>`suffix` matching example - Match schemas that end with a specific string</summary>
+
+**What is suffix matching?**
+
+Suffix matching is when the schema name ends with the specified suffix.
+
+In this example, the `Orders Service` will send `events` with a suffix of `placed` and receive `commands` with a suffix of `command`.
+
+Example schemas in registry:
+
+- `order-placed-value`
+- `order-cancelled-value`
+- `place-order-command-value`
+- `cancel-order-command-value`
+
+_Note: EventCatalog matches the `subject` of the schema in the registry. The `subject` in the registry has a suffix of `-value`. This is automatically removed when the schema is assigned to a producer or consumer. So you need to match the `subject` without the `-value` suffix._
+
+
+```js
+// ...
+generators: [
+  // Import schemas (using filters), assign them to topics, services and domains
+  [
+    '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events (schemas) with a suffix of `placed`
+            sends: [{ events: { suffix: '-placed' }},
+            // The Order services receives commands (schemas) with a suffix of `command`
+            receives: [{ commands: { suffix: '-command' }},
+          }
+        ],
+      },
+  ],
+];
+``` 
+
+</details>
+
+<details>
+<summary>`prefix` matching example - Match schemas that start with a specific string</summary>
+
+In this example, the `Orders Service` will send `events` with a prefix of `order` and receive `commands` with a prefix of `analytics`
+
+Example schemas in registry:
+
+- `order-placed-value`
+- `order-cancelled-value`
+- `analytics-place-order-value`
+- `analytics-cancel-order-value`
+
+_Note: EventCatalog matches the `subject` of the schema in the registry. The `subject` in the registry has a suffix of `-value`. This is automatically removed when the schema is assigned to a producer or consumer. So you need to match the `subject` without the `-value` suffix._
+
+
+```js
+// ...
+generators: [
+  // Import schemas (using filters), assign them to topics, services and domains
+  [
+    '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events with a prefix of `order`
+            sends: [{ events: { prefix: 'order' }}],
+            // The Order services receives commands with a prefix of `analytics`
+            receives: [{ commands: { prefix: 'analytics' }}],
+          }
+        ],
+      },
+  ],
+];
+``` 
+
+</details>
+
+<details>
+<summary>`includes` matching example - Match schemas that include a specific string</summary>
+
+In this example, the `Orders Service` will send `events` that include the string `order` and receives `commands` that include the string `analytics`
+
+Example schemas in registry:
+
+- `order-placed-value`
+- `order-cancelled-value`
+- `analytics-place-order-value`
+- `analytics-cancel-order-value`
+
+_Note: EventCatalog matches the `subject` of the schema in the registry. The `subject` in the registry has a suffix of `-value`. This is automatically removed when the schema is assigned to a producer or consumer. So you need to match the `subject` without the `-value` suffix._
+
+
+```js
+// ...
+generators: [
+  // Import schemas (using filters), assign them to topics, services and domains
+  [
+    '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events with a prefix of `order`
+            sends: [{ events: { includes: 'order' }}],
+            // The Order services receives commands with a prefix of `analytics`
+            receives: [{ commands: { includes: 'analytics' }}],
+          }
+        ],
+      },
+  ],
+];
+``` 
+
+</details>
+
+
+## Example Configurations
+
+The Confluent Schema Registry plugin is flexible to work with your use case.
+Here are a few examples of how you can configure the plugin.
+
+
+<details>
+<summary>Example configuration - Import all schemas (and versions) into EventCatalog</summary>
+
+In this example we import all schemas from the Confluent Schema Registry into EventCatalog.
+No topics, services or domains are configured or created. This is a simple way to import schemas into the catalog and keep them in sync with your documentation.
+
+:::success Remember your API keys
+If you want to use the Confluent Schema Registry plugin, you need to configure your API keys as environment variables in the `.env` file.
+:::
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+
+        // Include all versions of the schemas
+        includeAllVersions: true,
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+<details>
+<summary>Example configuration - Assign schemas to producers and consumers</summary>
+
+In this example we assign schemas to producers and consumers (services in EventCatalog).
+
+:::success Remember your API keys
+If you want to use the Confluent Schema Registry plugin, you need to configure your API keys as environment variables in the `.env` file.
+:::
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that match the schema name `order-placed` or `order-cancelled`
+            sends: [{ events: ['order-placed', 'order-cancelled']}],
+            // The Order services receives commands that match the schema name `place-order` or `cancel-order`
+            receives: [{ commands: ['place-order', 'cancel-order']}],
+          }
+        ]
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+<details>
+<summary>Example configuration - Assign schemas to producers and consumers (with filters)</summary>
+
+In this example we assign schemas to producers and consumers (services in EventCatalog) but we use filters to match the schemas.
+
+:::success Remember your API keys
+If you want to use the Confluent Schema Registry plugin, you need to configure your API keys as environment variables in the `.env` file.
+:::
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that start with `order`
+            sends: [{ events: { prefix: 'order' }}],
+            // The Order services receives commands that end with `command`
+            receives: [{ commands: { suffix: 'command' }}],
+          }
+        ]
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+<details>
+<summary>Example configuration - Assign schemas to producers and consumers with topics</summary>
+
+In this example we assign schemas to producers and consumers (services in EventCatalog) but we also assign them to *topics*.
+
+:::success Remember your API keys
+If you want to use the Confluent Schema Registry plugin, you need to configure your API keys as environment variables in the `.env` file.
+:::
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // List of kafka topics to assign the schemas to (optional)
+        // These will be documented as channels in EventCatalog
+        topics: [
+          {
+            id: 'orders-topic',
+            name: 'Orders Topic',
+            address: 'kafka-cluster-1.us-east-1.confluent.cloud:9092',
+          }
+        ],
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that start with `order` using the `orders-topic` (channel)
+            sends: [{ events: { prefix: 'order' }, topic: 'orders-topic'}],
+            // The Order services receives commands that end with `command` using the `orders-topic` (channel)
+            receives: [{ commands: { suffix: 'command' }, topic: 'orders-topic'}],
+          }
+        ]
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+<details>
+<summary>Example configuration - Assign schemas to producers and consumers within a domain</summary>
+
+In this example we assign schemas to producers and consumers (services in EventCatalog) but we also assign them to a *domain*.
+
+:::success Remember your API keys
+If you want to use the Confluent Schema Registry plugin, you need to configure your API keys as environment variables in the `.env` file.
+:::
+
+```js title="eventcatalog.config.js"
+  // ...rest of eventcatalog.config.js file
+  generators: [
+    [
+      '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL of your Confluent Schema Registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // Order service publishes events that match the schema name `order-placed` or `order-cancelled`
+            sends: [{ events: ['order-placed', 'order-cancelled']}],
+            // The Order services receives commands that match the schema name `place-order` or `cancel-order`
+            receives: [{ commands: ['place-order', 'cancel-order']}],
+          }
+        ],
+        // The domain to assign the service (orders-service) to
+        // if it does not exist, it will be created
+        domain: {
+          id: 'orders-domain',
+          name: 'Orders Domain',
+          version: '1.0.0',
+        }
+      }
+    ]
+  ],
+};
+```
+
+</details>
+
+## Need help?
+
+If you have questions or need help, you can join our [Discord community](https://eventcatalog.dev/discord)
+or refer to the [Confluent Schema Registry examples on GitHub](https://github.com/event-catalog/generators/tree/main/examples/generator-confluent-schema-registry).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/core/docs/plugins/confluent-schema-registry/03-features.md b/packages/core/docs/plugins/confluent-schema-registry/03-features.md
new file mode 100644
index 000000000..009df4c72
--- /dev/null
+++ b/packages/core/docs/plugins/confluent-schema-registry/03-features.md
@@ -0,0 +1,43 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Features
+title: Features
+description: Features of AsyncAPI with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+### Adding semantic meaning to schemas
+
+Using the Confluent Schema Registry plugin, you can import and map your schemas to topics, services, domains and owners.
+
+When you import a schema into EventCatalog your (event or command) will be created. The schema (JSON, Avro or Protobuf) will be stored against the message in EventCatalog. 
+
+Each message (command or event) has their own `index.mdx` file. This is the place to store semantic meaning for the message. You can add a title, summary, description, and more (custom components, markdown, etc).
+
+This gives you the opportunity to add meaning to your messages and make them easier to understand for teams.
+
+When you reimport your schemas, your schemas will download the latest version of the schema from the Confluent Schema Registry and your semantic meaning will persist between imports. This means you can keep your message schemas up to date and your semantic meaning will be preserved.
+
+### Visualize schemas, topics, services and domains
+
+When you import your schemas into EventCatalog you can assign them to producers, consumers and topics (channels).
+
+After the import process, you can use the EventCatalog Visualizer to see exactly how your schemas, topics, services and domains are mapped.
+
+![Example Image](./images/visualizer.png)
+
+
+### Downloading schemas
+
+EventCatalog supports any schema format (e.g avro, json, protobuf, etc). When you import your schemas into EventCatalog you can view and download the schema directly from EventCatalog.
+
+### Missing a feature?
+
+If you are missing a feature, please let us know by opening an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).
+
+### Example
+
+See the [eventcatalog-asyncapi-example](https://github.com/event-catalog/generators/tree/main/examples/generator-asyncapi) for a working example.
\ No newline at end of file
diff --git a/packages/core/docs/plugins/confluent-schema-registry/04-examples.md b/packages/core/docs/plugins/confluent-schema-registry/04-examples.md
new file mode 100644
index 000000000..4d0b9536e
--- /dev/null
+++ b/packages/core/docs/plugins/confluent-schema-registry/04-examples.md
@@ -0,0 +1,19 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the AsyncAPI plugin
+---
+
+You can find many examples of using the Confluent Schema Registry plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [Confluent Schema Registry Example](https://github.com/event-catalog/generators/tree/main/examples/generator-confluent-schema-registry/basic)
+  - An example of using the Confluent Schema Registry plugin to generate a catalog from a Confluent Schema Registry, including services, and topics.
+- [Import all schemas in a Confluent Schema Registry](https://github.com/event-catalog/generators/tree/main/examples/generator-confluent-schema-registry/document-all-schemas) 
+  - An example that will document all schemas in a Confluent Schema Registry including all the versions.
+- [Confluent Schema Registry with EventCatalog Chat](https://github.com/event-catalog/generators/tree/main/examples/generator-confluent-schema-registry/eventcatalog-chat-with-schemas-and-topics) 
+  - Import schemas into EventCatalog and use EventCatalog Chat to ask questions about the schemas and topics.
diff --git a/packages/core/docs/plugins/confluent-schema-registry/_category_.json b/packages/core/docs/plugins/confluent-schema-registry/_category_.json
new file mode 100644
index 000000000..04c40c413
--- /dev/null
+++ b/packages/core/docs/plugins/confluent-schema-registry/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Confluent Schema Registry Plugin",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "confluent-schema-registry",
+    "title": "Confluent Schema Registry",
+    "description": "Confluent Schema Registry integration for EventCatalog"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/plugins/eventbridge/00-intro.md b/packages/core/docs/plugins/eventbridge/00-intro.md
new file mode 100644
index 000000000..9404bf56e
--- /dev/null
+++ b/packages/core/docs/plugins/eventbridge/00-intro.md
@@ -0,0 +1,55 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Getting started
+description: Getting started with Amazon EventBridge plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<AddedIn version="2.6.0"/>
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/MeBuwAflwM4?si=rhio4gjfDPau4eqB" 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>
+
+---
+
+[Amazon EventBridge](https://aws.amazon.com/eventbridge/) is an AWS service that helps developers build event-driven applications at scale. Amazon EventBridge offers mutiple solutions including [Event Bus](https://aws.amazon.com/eventbridge/), [Amazon EventBridge Pipes](https://aws.amazon.com/eventbridge/) and [Amazon EventBridge Scheduler](https://aws.amazon.com/eventbridge/).
+
+Amazon EventBridge also offers [a schema registry](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-schema.html). This registry help you store your events in JSON and OpenAPI formats, give you the ability to download code bindings and also manage schema versions with automatic schema discovery.
+
+Using the [schema discovery feature](https://aws.amazon.com/blogs/compute/introducing-amazon-eventbridge-schema-registry-and-discovery-in-preview/), as events are put onto the event bus they are versioned and stored in the registry. These schemas can be used to help you and your teams understand and discover events in your event-driven architecture.
+
+Although EventBridge offers managed schema solutions, [there is a still an issue of discoverabilty and documentation for your events, services and domains](https://www.youtube.com/watch?v=VLUvfIm9wnQ&t=4s). It still remains difficult to organize your event-driven architecture for governance. 
+
+### Why use EventCatalog with EventBridge?
+
+Using the EventCatalog EventBridge generator you can automate and generate your EventCatalog. Enable your teams to quickly find events from EventBridge, what services they belong too and how to start consuming them.
+
+
+### Core Features
+
+The EventCatalog Amazon EventBridge plugin can provide you with many features:
+
+- ⭐️ Generate domains, services, channels and messages into your catalog
+- ⭐️ [Automatically version your changes in EventCatalog in sync with your registry versions](#automatic-versioning)
+- ⭐️ [Allow you to write and persist custom markdown between changes](#persist-markdown)
+- ⭐️ [Display your JSONDraft and OpenAPI schemas for each event in EventCatalog](#downloading-schemas)
+- ⭐️ [Filter events to match to your services](#using-filters-to-map-events-to-your-services)
+- ⭐️ Visualize your architecture
+- ⭐️ Download schemas and code bindings
+- ⭐️ and more....
+
+### How it works
+
+![Example](/img/integrations/eventbridge/eventbridge.png)
+
+EventCatalog supports [generators](/docs/plugins/generators). These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an [SDK](/docs/sdk) to give developers easier access to their catalogs through custom scripts or generators.
+
+The EventCatalog EventBridge plugin let's you map your events into domains and services. You can use [custom filters (prefix, suffix, detailType and source)](#using-filters-to-map-events-to-your-services) to map which events you want your service to produce and consume.
+
+You can also use the EventCatalog plugin to map ALL events from your registry into your system and not map them into services if you wish to have a direct import.
+
diff --git a/packages/core/docs/plugins/eventbridge/00a-installation.md b/packages/core/docs/plugins/eventbridge/00a-installation.md
new file mode 100644
index 000000000..7a4f758b2
--- /dev/null
+++ b/packages/core/docs/plugins/eventbridge/00a-installation.md
@@ -0,0 +1,317 @@
+---
+sidebar_position: 2
+keywords:
+- components
+sidebar_label: Installation
+title:  Installation
+description: Installation guide for the EventCatalog Amazon EventBridge plugin
+id: installation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<AddedIn version="2.6.0"/>
+
+The EventBridge plugin is a generator that can be used to generate your EventCatalog from an EventBridge registry.
+
+You can map your schemas to services, domains and messages. You can also map all events from your registry into your catalog.
+
+## Installation
+
+Run the following command to install the plugin.
+
+:::tip "Don't have an EventCatalog project yet?"
+If you don't have an EventCatalog project yet, you can follow the instructions in the [Getting Started](/docs/development/getting-started/installation) guide.
+:::
+
+<Tabs>
+  <TabItem value="apple" label="Install on existing catalog" default>
+    ```bash
+npm i @eventcatalog/generator-eventbridge
+```
+  </TabItem>
+  <TabItem value="orange" label="Create new catalog with the EventBridge template">
+     ```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --template eventbridge
+```
+  </TabItem>
+</Tabs>
+
+
+#### Configuration
+
+Configure the plugin in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators` array.
+
+<Tabs>
+  <TabItem value="apple" label="Import all schemas" default>
+
+  ---
+
+  In this example we import all schemas from an EventBridge registry.
+
+  We don't map them to any services or domains.
+
+  ```js title="eventcatalog.config.js"
+  // ...
+generators: [
+    // Import all schemas into your catalog
+    [
+      '@eventcatalog/generator-eventbridge',
+      {
+        // The region of your EventBridge registry
+        region: 'us-east-1',
+        // The name of your EventBridge registry
+        registryName: 'discovered-schemas'
+      },
+    ],
+],
+// ...
+```
+  </TabItem>
+  <TabItem value="orange" label="Map schemas to producers and consumers">
+
+  ---
+
+  In this example we map schemas to producers and consumers (services).
+
+  Every time you run the plugin, it will check if the service already exists in your catalog.
+
+  If the service already exists, it will not create a new one and just maintain the schema mappings.
+
+  We create two services, the `orders` service and the `inventory` service.
+  
+  
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  [
+    '@eventcatalog/generator-eventbridge',
+    {
+      // The region of your EventBridge registry
+      region: 'us-east-1',
+      // The name of your EventBridge registry
+      registryName: 'discovered-schemas',
+      // Creating producers and consumers, and mapping them to your catalog
+      services: [
+        
+        // We map schemas to the orders service
+        // Using the detailType we can map specific events to the service
+        { id: 'Orders Service', version: '1.0.0', sends: [{ detailType: ['OrderPlaced', 'OrderUpdated'], eventBusName: 'orders'}], receives:[{ detailType: "InventoryAdjusted", eventBusName: 'inventory'}] },
+
+        // Map events to the Inventory Service
+        // Filter by source (all events that match the source get assigned). This example shows any event matching the source
+        // "myapp.orders" will be assigned to the inventory service. The inventory service will publish these events.
+        { id: 'Inventory Service', version: '1.0.0', sends: [{ source: "myapp.orders", eventBusName: 'orders'}], receives:[{ detailType: "UserCheckedOut", eventBusName: 'inventory'}] },
+
+
+        // This service sends events that match the SchemaName prefixing myapp, and will receive events that end with Payment
+        // this also does not map any event buses to your events
+        { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
+      ],
+
+      // all services are mapped to this domain
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+    },
+  ],
+],
+// ...
+```
+  </TabItem>
+  <TabItem value="orange2" label="Multiple domains, services and events">
+
+  ---
+
+  In this example we have two domains, `orders` and `inventory`.
+
+  We map schemas to the orders and inventory services, and we assign these services to new domains.
+
+  If the domain or service already exists in your catalog, the plugin will not create a new one and just maintain the schema mappings.
+
+  :::info Why do we define the plugin twice?
+  The plugin can be defined multiple times in your `eventcatalog.config.js` file.
+
+  In this example we define the plugin twice, the first time we import the schemas and create the `orders` domain.
+
+  The second time we map the inventory service to the `inventory` domain.
+  :::
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  [
+    '@eventcatalog/generator-eventbridge',
+    {
+      // The region of your EventBridge registry
+      region: 'us-east-1',
+      // The name of your EventBridge registry
+      registryName: 'discovered-schemas',
+      // Creating producers and consumers, and mapping them to your catalog
+      services: [
+        // We map schemas to the orders service
+        // Using the detailType we can map specific events to the service
+        { id: 'Orders Service', version: '1.0.0', sends: [{ detailType: ['OrderPlaced', 'OrderUpdated'], eventBusName: 'orders'}], receives:[{ detailType: "InventoryAdjusted", eventBusName: 'inventory'}] },
+      ],
+
+      // all services are mapped to this domain
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+    },
+  ],
+  [
+    '@eventcatalog/generator-eventbridge',
+    {
+      region: 'us-east-1',
+      registryName: 'discovered-schemas',
+      services: [
+        // Create the inventory service and map schemas to it (producer/consumer relationship)
+        { id: 'Inventory Service', version: '1.0.0', sends: [{ source: "myapp.orders", eventBusName: 'orders'}], receives:[{ detailType: "UserCheckedOut", eventBusName: 'inventory'}] },
+      ],
+
+      // create the inventory domain and assign the inventory service to it
+      domain: { id: 'inventory', name: 'Inventory', version: '0.0.1' },
+    },
+  ],
+],
+// ...
+```
+  </TabItem>
+</Tabs>
+
+
+
+### Configure license key
+
+The EventBridge plugin requires an EventCatalog Scale license key to work with EventCatalog.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+You have a few options for setting the license key:
+
+1. [Setting license key in `.env` file (recommended)](#setting-license-key-in-env-file-recommended)
+2. [Setting license key in eventcatalog.config.js](#setting-license-key-in-eventcatalogconfigjs)
+
+#### 1. Setting license key in `.env` file (recommended) {#setting-license-key-in-env-file-recommended}
+
+<AddedIn version="2.35.4" />
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+:::tip Using an Older API Key?
+
+If you already have an older EventBridge plugin key, you can still use it with the EventBridge-specific environment variable.
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_EVENTBRIDGE=your-license-key
+```
+
+:::
+
+
+#### 2. Setting license key in eventcatalog.config.js {#setting-license-key-in-eventcatalogconfigjs}
+
+If you prefer, you can set the license key in the `eventcatalog.config.js` file
+using the `licenseKey` property in the EventCatalog EventBridge plugin.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-eventbridge',
+      {
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_SCALE_LICENSE_KEY
+        region: 'us-east-1',
+        registryName: 'discovered-schemas'
+      },
+    ],
+  ],
+};
+```
+
+#### White listing EventCatalog domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+#### Run the plugin
+
+_This command will run the generators in your eventcatalog.config.js file._
+
+```
+npm run generate
+```
+
+#### View your catalog
+
+Run your catalog locally to see the changes
+
+```
+npm run dev
+```
+
+### AWS Configuration
+
+#### Policy for AWS
+
+This plugin will require some read access to your Schema Registry and Versions.
+
+It's recommended you create a new IAM user with the following policy.
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "EventCatalog",
+            "Effect": "Allow",
+            "Action": [
+                "schemas:ExportSchema",
+                "schemas:SearchSchemas",
+                "schemas:ListSchemas",
+                "schemas:ListSchemaVersions",
+                "schemas:DescribeSchema",
+                "schemas:GetDiscoveredSchema"
+            ],
+            "Resource": "*"
+        }
+    ]
+}
+```
+
+
+## Commercial and License
+
+This plugin requires an EventCatalog Scale license key to be used.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial, you can continue using this plugin with EventCatalog Scale. 
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## License FAQ
+
+### What is the license key for?
+The EventCatalog Scale license key is required to use the OpenAPI plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get an EventCatalog Scale license key?
+You can obtain an EventCatalog Scale license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 30-day free trial.
+
+### Terms
+- **Trial Period**: 30-day free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can continue with EventCatalog Scale through [EventCatalog Cloud](https://eventcatalog.cloud).
+
+## Issues
+
+If you have any problems or feature requests please feel free to raise them on GitHub. https://github.com/event-catalog/generators
diff --git a/packages/core/docs/plugins/eventbridge/01-features.md b/packages/core/docs/plugins/eventbridge/01-features.md
new file mode 100644
index 000000000..efa271f5c
--- /dev/null
+++ b/packages/core/docs/plugins/eventbridge/01-features.md
@@ -0,0 +1,225 @@
+---
+sidebar_position: 3
+keywords:
+- components
+sidebar_label: Features
+title: Features
+description: Features of AsyncAPI with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+
+
+### Using filters to map events to your services
+
+EventCatalog plugin supports a range of filters:
+
+- `suffix` - Matches anything at the end of the schema name
+- `preffix` - Matches anything at the start of the schema name
+- `detailType` - Exact matching on the detail type of the event
+- `source` - Exact matching on the source of the events
+
+You can use the filters to map events directly to your services, this gives you flexibility on how you want to structure your EventCatalog and map events to services.
+
+:::tip
+Filters are mapped on the registry schema name. If you are using schema-discovery this will be the `source@detailType` (e.g `myapp.test.com@OrderCreated`). 
+If you are using a custom registry this will be the schema name you defined for that event.
+:::
+
+**suffix example**
+
+In this example any event in the registry that ends with `Orders` or `Inventory` will get mapped into EventCatalog. 
+These events will map into the Orders Service.
+
+```js
+generators: [
+    [
+      '@eventcatalog/generator-eventbridge',
+      {
+        region: 'us-east-1',
+        registryName: 'discovered-schemas',
+        services: [
+          { id: 'Orders Service', version: '1.0.0', sends: [{ suffix: ['Orders'] }], receives:[{ suffix: "Inventory"}] },
+        ],
+        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+      },
+    ],
+  ],
+
+```
+
+**prefix example**
+
+In this example all events in the registry that starts with `myapp.orders.test@Orders` or `myapp.orders.test@Inventory` will get mapped into EventCatalog. 
+In this example the Orders Service sends events that start with `myapp.orders.test@Orders` and receives events that start with `myapp.orders.test@Inventory`
+
+
+```js
+generators: [
+    [
+      '@eventcatalog/generator-eventbridge',
+      {
+        region: 'us-east-1',
+        registryName: 'discovered-schemas',
+        services: [
+          { id: 'Orders Service', version: '1.0.0', sends: [{ prefix: ['myapp.orders.test@Orders']}], receives:[{ prefix: "myapp.orders.test@Inventory"}] },
+        ],
+        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+      },
+    ],
+  ],
+
+```
+
+**detailType example**
+
+In this example all events that match the given detailType will get mapped into EventCatalog. 
+```js
+generators: [
+    [
+      '@eventcatalog/generator-eventbridge',
+      {
+        region: 'us-east-1',
+        registryName: 'discovered-schemas',
+        services: [
+          { id: 'Orders Service', version: '1.0.0', sends: [{ detailType: 'OrderCreated'}], receives:[{ detailType: ["InventoryAdjusted", "InventoryOutOfStock"]}] },
+        ],
+        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+      },
+    ],
+  ],
+
+```
+
+**source example**
+
+In this example all events that match the given source will get mapped into EventCatalog. 
+
+This example shows the Order Service will send all events that match the source `myapp.orders` and will receives all events that match the source `myapp.inventory` and `myapp.payments`.
+
+```js
+generators: [
+    [
+      '@eventcatalog/generator-eventbridge',
+      {
+        region: 'us-east-1',
+        registryName: 'discovered-schemas',
+        services: [
+          { id: 'Orders Service', version: '1.0.0', sends: [{ source: 'myapp.orders'}], receives:[{ source: ["myapp.inventory", "myapp.payments"]}] },
+        ],
+        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+      },
+    ],
+  ],
+
+```
+
+### Using custom schema registries
+
+EventBridge offers users the ability to create custom schema registries. This let's you create and upload new schemas to EventBridge.
+
+This generator will support these custom registries and map events to your services based on these registries.
+
+The mapping works slightly different with custom registries. The event name is mapped as the `source`.
+
+Here is an example of how this works:
+
+- Custom registry name: `custom-schemas`
+- Schema Name (the service sends this event): `OrderPlaced`
+- Schema Name (the service receives this event): `InventoryAdjusted`
+- Schema Name (the service receives this event): `InventoryAmountUpdated`
+
+```yml
+generators: [
+    [
+      '@eventcatalog/generator-eventbridge',
+      {
+        region: 'us-east-1',
+        # This is the name of your custom registry
+        registryName: 'custom-schemas',
+        services: [
+          # Map the name of the schema (event) into this service. 
+          # In this example the Order Service will send an event called OrderPlaced and receive an event called InventoryAdjusted and InventoryAmountUpdated
+          # Note: The source value is the name of the schema in the registry, this is how AWS names the schemas in your custom registry.
+          { id: 'Orders Service', version: '1.0.0', sends: [{ source: 'OrderPlaced'}], receives:[{ source: ["InventoryAdjusted", "InventoryAmountUpdated"]}] },
+        ],
+        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+      },
+    ],
+  ],
+```
+
+### Document Event Buses (as channels)
+
+<AddedIn version="1.2.0" pkg="@eventcatalog/generator-eventbridge" url="https://github.com/event-catalog/generator-eventbridge/releases/tag/v"/>
+
+EventCatalog [supports channels as resources](/docs/development/guides/resources/messages/message-channels/introduction). This let's you document your event buses in EventCatalog.
+
+EventCatalog will use your Event Bus as a channel, the protocol for the channel is set to `eventbridge`.
+
+This can help your developers understand and visually see that EventBridge events are published and consumed from Amazon EventBridge.
+
+![Example](/img/integrations/eventbridge/eventbridge-channel.png)
+
+The channel page will be populated with quick links to your AWS console.
+
+![Example](/img/integrations/eventbridge/eventbridge-channel-doc.png)
+
+#### Getting started
+
+To document your eventbus you need to specify the `eventBusName` in your `sends` or `receives` array.
+
+The example below shows a service that sends events from the `orders` event bus` and receives events from the `inventory` event bus.
+
+```md
+---
+generators: [
+    [
+      '@eventcatalog/generator-eventbridge',
+      {
+        region: 'us-east-1',
+        registryName: 'discovered-schemas',
+        services: [
+          # Define the service, and map events the service producers/consumes
+          # EventBusName is used to map the producer/consumer events to an event bus
+          { id: 'Orders Service', version: '1.0.0', sends: [{ source: 'myapp.orders', eventBusName: "orders"}], receives:[{ source: ["myapp.inventory", "myapp.payments"], "eventBusName"}] },
+        ],
+        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+      },
+    ],
+  ],
+---
+```
+
+### Persist markdown
+
+Your markdown is persisted between generation runs on EventCatalog. Initially the generator will generate markdown for you for your domains, services and events, but any edits to the markdown file will be persisted between versions.
+
+This allows you to add [custom components](/docs/components/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when your events are versioned.
+
+This can be useful for adding extra additional context to your events, example payloads, example CLI commands on how to raise them and any other useful information.
+
+### Automatic versioning
+
+**Schema discovery**
+
+If you are using the schema discovery feature, then Amazon EventBridge will version the schemas for you. They version your schema using a field called `VersionCount`. This value is used and mapped to your event version. When you re-generate your catalog using this generator it will check your event versions and automatcily version your events based on these fields.
+
+How it works
+
+- You put and event onto a bus with discovery enabled (v1 of this event is stored in registry by EventBridge)
+- You run generate for your catalog (v1 is documented in your catalog)
+- You change the payload of the original event and put another event on the bus (v2 is created by EventBridge.)
+- You run generate for your catalog (v1 is versioned for you, and v2 takes it place).
+
+**Custom registry**
+
+You can create your own custom registry with Amazon EventBridge. This let's you create and upload new schemas.
+
+Any version changes here will get copied over into EventCatalog.
+
+
+### Downloading schemas
+
+The generator will try and download the JSONDraft4 and OpenAPI specifications for your events from EventBridge. These files will be attached to each even in EventCatalog. Users will be able to see and download these files.
diff --git a/packages/core/docs/plugins/eventbridge/02-examples.md b/packages/core/docs/plugins/eventbridge/02-examples.md
new file mode 100644
index 000000000..dc1cf5490
--- /dev/null
+++ b/packages/core/docs/plugins/eventbridge/02-examples.md
@@ -0,0 +1,17 @@
+---
+sidebar_position: 4
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the OpenAPI plugin
+---
+
+You can find many examples of using the OpenAPI plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [Amazon EventBridge Example](https://github.com/event-catalog/generators/tree/main/examples/generator-eventbridge/basic)
+  - Pull schemas from EventBridge schema registry and map to services, domains and messages. Use custom filters to map events to services.
+- [Using custom schema registry](https://github.com/event-catalog/generators/tree/main/examples/generator-eventbridge/custom-registry)
+  - Use a custom schema registry to store your schemas including custom filters to map events to services.
\ No newline at end of file
diff --git a/packages/core/docs/plugins/eventbridge/03-api.md b/packages/core/docs/plugins/eventbridge/03-api.md
new file mode 100644
index 000000000..b6faa11d6
--- /dev/null
+++ b/packages/core/docs/plugins/eventbridge/03-api.md
@@ -0,0 +1,441 @@
+---
+sidebar_position: 5
+keywords:
+  - components
+sidebar_label: Generator configuration
+title: Generator API
+description: Getting started with Amazon EventBridge plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+## Overview {#overview}
+
+API for the EventCatalog Amazon EventBridge generator.
+
+**Example eventcatalog.config.js file**
+
+```js title="eventcatalog.config.js"
+---
+import path from 'path';
+import url from 'url';
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  title: 'OurLogix',
+  tagline: 'A comprehensive logistics and shipping management company',
+  organizationName: 'OurLogix',
+  homepageLink: 'https://eventcatalog.dev/',
+  landingPage: '',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  trailingSlash: false,
+  base: '/',
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'OurLogix',
+  },
+  docs: {
+    sidebar: {
+      showPageHeadings: true,
+    },
+  },
+  generators: [
+    [
+      '@eventcatalog/generator-eventbridge',
+      {
+        region: 'us-east-1',
+        registryName: 'discovered-schemas',
+        services: [
+          // Maps exact events to the service
+          { id: 'Orders Service', version: '1.0.0', sends: [{ detailType: ['OrderPlaced', 'OrderUpdated'], eventBusName: 'orders'}], receives:[{ detailType: "InventoryAdjusted"}, eventBusName: 'inventory'] },
+
+          // Filter by source (all events that match the source get assigned). This example shows any event matching the source
+          // "myapp.orders" will be assigned to the inventory service. The inventory service will publish these events.
+          { id: 'Inventory Service', version: '1.0.0', sends: [{ source: "myapp.orders"}], receives:[{ detailType: "UserCheckedOut"}] },
+
+
+          // This service sends events that match the SchemaName prefixing myapp, and will receive events that end with Payment
+          { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
+        ],
+
+        // all services are mapped to this domain
+        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+      },
+    ],
+    // Just import all events into the Catalog from a registry
+    [
+      '@eventcatalog/generator-eventbridge',
+      {
+        region: 'us-east-1',
+        registryName: 'discovered-schemas'
+      },
+    ],
+    // Example using optional credentials
+    [
+      '@eventcatalog/generator-eventbridge',
+      {
+        region: 'us-east-1',
+        registryName: 'discovered-schemas',
+        credentials: {
+          accessKeyId: 'X',
+          secretAccessKey: 'X',
+          accountId: 'X',
+        },
+      },
+    ],
+  ],
+};
+
+```
+
+:::warning
+When importing node modules into your `eventcatalog.config.js` file, you need to import the entire package.
+
+```js
+import path from "path"; //work
+
+import { join } from "path"; // will not work
+```
+
+This is currently a limitation and is being looked at. Any problems or issues feel free to raise a GitHub issue.
+
+:::
+
+## Required fields {#required-fields}
+
+### `region` {#region}
+
+- Type: `String`
+
+The region of your schema registry.
+
+```js title="eventcatalog.config.js"
+[
+  '@eventcatalog/generator-eventbridge',
+  {
+    region: 'us-east-1',
+    registryName: 'discovered-schemas'
+  },
+],
+```
+
+### `registryName` {#registryName}
+
+- Type: `String`
+
+The EventBridge registry name for your schemas.
+
+```js title="eventcatalog.config.js"
+[
+  '@eventcatalog/generator-eventbridge',
+  {
+    region: 'us-east-1',
+    registryName: 'discovered-schemas'
+  },
+],
+```
+
+### `licenseKey` {#licenseKey}
+
+- Type: `String`
+
+The license key for the EventBridge generator. You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+```js title="eventcatalog.config.js"
+[
+  '@eventcatalog/generator-eventbridge',
+  {
+    licenseKey: 'YOUR_LICENSE_KEY'
+  },
+],
+```
+
+:::info Using environment variables
+
+You can also set the license key as an environment variable. If this is set on the machine the `licenseKey` is not required in the generator configuration.
+
+```bash
+EVENTCATALOG_SCALE_LICENSE_KEY=YOUR_SCALE_LICENSE_KEY
+```
+:::
+
+## Optional fields {#optional-fields}
+
+### `services` {#services}
+
+- Type: `Service[]`
+
+List of services to add and what events they publish (sends) and consume (receives)
+
+```js title="eventcatalog.config.js"
+[
+   '@eventcatalog/generator-eventbridge',
+    {
+      region: 'us-east-1',
+      registryName: 'discovered-schemas',
+      services: [
+        // Maps exact events to the service
+        { id: 'Orders Service', version: '1.0.0', sends: [{ detailType: ['OrderPlaced', 'OrderUpdated'], receives:[{ detailType: "InventoryAdjusted"}]}] },
+
+        // Filter by source (all events that match the source get assigned). This example shows any event matching the source
+        // "myapp.orders" will be assigned to the inventory service. The inventory service will publish these events.
+        { id: 'Inventory Service', version: '1.0.0', sends: [{ source: "myapp.orders"}], receives:[{ detailType: "UserCheckedOut"}] },
+
+
+        // This service sends events that match the SchemaName prefixing myapp, and will receive events that end with Payment
+        { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
+      ]
+  },
+];
+```
+
+**Service properties**
+
+| Property name | Required | Description                                                                   |
+| ------------- | -------- | ----------------------------------------------------------------------------- |
+| id            | required | Id of the service, this will also be used as the folder name of your service. |
+| version            | required | The version of the service |
+| sends            | optional | The events the service sends (publishes). You can use [EventCatalog filters](/docs/plugins/eventbridge/intro#using-filters-to-map-events-to-your-services) to match your events. |
+| sends.eventBusName            | optional | The name of the EventBus for the matched events. This will be displayed as an EventCatalog Channel. |
+| receives            | optional | The events the service receives (consumes). You can use [EventCatalog filters](/docs/plugins/eventbridge/intro#using-filters-to-map-events-to-your-services) to match your events. |
+| receives.eventBusName            | optional | The name of the EventBus for the matched events. This will be displayed as an EventCatalog Channel. |
+| writesTo            | optional | Array of [data stores](/docs/development/guides/resources/data/introduction) ids that the service writes to. (Added in v3.2.2) |
+| readsFrom            | optional | Array of [data stores](/docs/development/guides/resources/data/introduction) ids that the service reads from. (Added in v3.2.2) |
+| writeToRoot            | optional | Write the service to the root of your catalog, ignoring the domain structure. [Useful if you have shared services between domains](/docs/plugins/eventbridge/03a-workflows#shared-services-between-domains) (Added in v3.3.0) |
+
+### `domain` {#domain}
+
+The domain you want the services be associated with in your catalog.
+
+```js title="eventcatalog.config.js"
+[
+  '@eventcatalog/generator-eventbridge',
+  {
+    region: 'us-east-1',
+    registryName: 'discovered-schemas',
+    services: [
+      { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
+    ],
+    domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+  },
+];
+```
+
+**Service properties**
+
+| Property name | Required | Description                                                                   |
+| ------------- | -------- | ----------------------------------------------------------------------------- |
+| id            | required | Id of the domain, this will also be used as the folder name of your domain. |
+| version       | required | The version of the domain |
+| name          | optional | Friendly name for your domain. |
+
+### `writeFilesToRoot` {#writeFilesToRoot}
+
+<AddedIn version="2.0.0" pkg="@eventcatalog/generator-eventbridge" url="https://github.com/event-catalog/generators/releases/"/>
+
+- Type: `Boolean`
+
+By default your EventBridge events will be written to the service folder (if you define one). This helps keep related events together in your EventCatalog folder structure.
+
+Example:
+
+```
+services/
+  payment-service/
+    index.mdx
+    events/
+      payment-created/
+        index.mdx
+      payment-updated/
+        index.mdx
+```
+
+If you set `writeFilesToRoot` to true, your EventBridge events will be written to the root of your catalog (pre v2.0.0 behavior).
+
+Example:
+
+```
+services/
+  payment-service/
+    index.mdx
+events/
+  payment-created/
+    index.mdx
+  payment-updated/
+    index.mdx
+```
+### `writeEventsToRoot` {#writeEventsToRoot}
+
+<AddedIn version="3.3.0" pkg="@eventcatalog/generator-eventbridge" url="https://github.com/event-catalog/generators/releases/"/>
+
+- Type: `Boolean`
+
+By default your EventBridge events will be written to the service folder (if you define one). 
+
+Setting this to true will write your events to the root of your catalog, but keep your services and domains folder in the same structure you define.
+
+This is useful if you have shared events between services, and you want to document them in a central place.
+
+You can read more about this in the [Workflows](/docs/plugins/eventbridge/03a-workflows#storing-shared-events-in-your-catalog-for-producers-and-consumers) section.
+
+Example:
+
+```
+services/
+  payment-service/
+    index.mdx
+    events/
+      payment-created/
+        index.mdx
+      payment-updated/
+        index.mdx
+```
+
+If you set `writeEventsToRoot` to true, your EventBridge events will be written to the root of your catalog, but keep your services and domains folder in the same structure you define.
+
+Example:
+
+```
+services/
+  payment-service/
+    index.mdx
+events/
+  payment-created/
+    index.mdx
+  payment-updated/
+    index.mdx
+```
+
+### `credentials` {#credentials}
+
+- Type: `AwsCredentialIdentity | AwsCredentialIdentityProvider`
+
+AWS credentials to use for your plugin.
+
+```js title="eventcatalog.config.js"
+[
+   '@eventcatalog/generator-eventbridge',
+    {
+      region: 'us-east-1',
+      registryName: 'discovered-schemas',
+      credentials: {
+        accessKeyId: 'ACCESS_KEY',
+        secretAccessKey: 'ACCESS_KEY',
+        accountId: 'ACCOUNT_ID',
+      },
+      services: [
+        { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
+      ]
+  },
+];
+```
+
+If you are using credentials you will want to create a user with limited permissions. [See the documentation to get started](/docs/plugins/eventbridge/intro#aws-configuration).
+
+### `domain` {#domain}
+
+The domain you want the services be associated with in your catalog.
+
+```js title="eventcatalog.config.js"
+[
+  '@eventcatalog/generator-eventbridge',
+  {
+    region: 'us-east-1',
+    registryName: 'discovered-schemas',
+    services: [
+      { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
+    ],
+    domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+  },
+];
+```
+
+### `eventBusName` {#eventBusName}
+
+The name of the event bus the events belong too.
+
+A EventCatalog badge is added to your events when they generate with the event bus name.
+
+```js title="eventcatalog.config.js"
+[
+  '@eventcatalog/generator-eventbridge',
+  {
+    region: 'us-east-1',
+    registryName: 'discovered-schemas',
+    eventBusName: 'payment-bus',
+    services: [
+      { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
+    ],
+    domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+  },
+];
+```
+
+### `mapEventsBy` {#mapEventsBy}
+
+<AddedIn version="1.0.0" pkg="@eventcatalog/generator-eventbridge" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+When events are mapped to EventCatalog they are mapped by `detailType` by default. 
+This means a schema with the name `orders.app@OrderPlaced` would be mapped to EventCatalog as `OrderPlaced`.
+
+You can override this by setting the `mapEventsBy` field in your generator configuration.
+
+Setting `mapEventsBy` to `schema-name` will map the event to EventCatalog by it's schema name, in this example
+it would map the event to `orders.app@OrderPlaced`.
+
+```js title="eventcatalog.config.js"
+[
+  '@eventcatalog/generator-eventbridge',
+  {
+    region: 'us-east-1',
+    registryName: 'discovered-schemas',
+    eventBusName: 'payment-bus',
+    services: [
+      { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
+    ],
+    domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+    // Will now map by the schema name itself
+    mapEventsBy: 'schema-name'
+  },
+];
+```
+
+| Property name | Required | Options | Description                                                                   |
+| ------------- | -------- | -----------| ----------------------------------------------------------------------------- |
+| mapEventsBy            | optional (default 'detail-type') | `detail-type`, `schema-name` | Specify how you want events to map to EventCatalog from the EventBridge registry. By default the `detailType` is used of your event, setting the value to `schema-name` uses the schema name (source@detailType). |
+
+### `format` {#format}
+
+<AddedIn version="3.0.2" pkg="@eventcatalog/generator-eventbridge" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+The format specifies the format of the markdown files that are generated (`md` or `mdx`).
+
+By default the generator will use `mdx` files which is recommended if you are using the latest version of EventCatalog.
+
+:::warning
+If you are using an older version of EventCatalog that does not support mdx files you can set the format to `md`.
+:::
+
+```js title="eventcatalog.config.js"
+[
+  '@eventcatalog/generator-eventbridge',
+  {
+    region: 'us-east-1',
+    registryName: 'discovered-schemas',
+    eventBusName: 'payment-bus',
+    services: [
+      { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
+    ],
+    domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+    // Will write .md files instead of .mdx
+    format: 'md'
+  },
+];
+```
+
+| Property name | Required | Options | Description                                                                   |
+| ------------- | -------- | -----------| ----------------------------------------------------------------------------- |
+| format            | optional (default 'mdx') | `md`, `mdx` | Specify the format of the markdown files that are generated. |
diff --git a/packages/core/docs/plugins/eventbridge/03a-workflows.md b/packages/core/docs/plugins/eventbridge/03a-workflows.md
new file mode 100644
index 000000000..55ff31a35
--- /dev/null
+++ b/packages/core/docs/plugins/eventbridge/03a-workflows.md
@@ -0,0 +1,133 @@
+---
+sidebar_position: 3
+keywords:
+- components
+sidebar_label: Workflows  
+title: Workflows
+description: Workflows of EventBridge with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+There are a few ways to configure the EventBridge plugin depending on your preferred development workflows.
+Many companies have different needs, so we have provided a few different workflows to choose from.
+
+- [Storing shared events in your catalog for producers and consumers.](#storing-shared-events-in-your-catalog-for-producers-and-consumers)
+- [Shared services between domains.](#shared-services-between-domains)
+
+<!-- - [Simple mapping between AsyncAPI files and EventCatalog services](#simple-mapping-between-asyncapi-files-and-eventcatalog-services)
+  - Map a single AsyncAPI file to a single EventCatalog service
+- [Independent message versions from your AsyncAPI file](#independent-message-versions-from-your-asyncapi-file)
+  - Version your messages independently of the service version
+- [Mapping multiple AsyncAPI files to a single EventCatalog service](#mapping-multiple-asyncapi-files-to-a-single-eventcatalog-service)
+  - Map multiple AsyncAPI files to a single EventCatalog service
+- [Mapping AsyncAPI and OpenAPI files to the same EventCatalog service](#mapping-asyncapi-and-openapi-files-to-the-same-eventcatalog-service) -->
+  <!-- - Map an AsyncAPI and OpenAPI file to the same EventCatalog service -->
+
+_If we are missing a workflow that you think is useful, please raise an [issue on GitHub](https://github.com/event-catalog/generators/issues)._  
+
+### Storing shared events in your catalog for producers and consumers.
+
+<AddedIn version="3.3.0" pkg="@eventcatalog/generator-eventbridge" url="https://github.com/event-catalog/generators/releases/"/>
+
+Ownership of events varies by company. Some companies have the producer own the event and contract, others have different patterns.
+
+When you use the EventBridge plugin, EventCatalog will store your events within the service folder you define.
+
+For more usecases this is OK, but if you want more control over where your events are written, in your catalog, you can use the `writeEventsToRoot` option.
+
+When you use the `writeEventsToRoot` option, EventCatalog will write your events to the root of your catalog, but keep your services and domains folder in the same structure you define.
+
+```js title="eventcatalog.config.js"
+// ...rest of file
+generators: [
+  [
+    '@eventcatalog/generator-eventbridge',
+    {
+      writeFilesToRoot: true,
+      services: [
+        { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }] }
+        { id: 'Payment Service', version: '1.0.0', receives: [{ source: "myapp"}] }
+      ],
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+    },
+  ],
+],
+```
+
+In this situation the events will be written to the root of your catalog, but keep your services and domains folder in the same structure you define.
+
+```md
+<!-- events stores in the root, referenced by other resources -->
+events/
+  payment-created/
+    index.mdx
+  payment-updated/
+    index.mdx
+<!-- Domains and services are still in their original location -->
+domains/
+  orders/
+    services/
+      payment-service/
+        index.mdx
+      payment-service/
+        index.mdx
+    index.mdx
+```
+
+This pattern can be useful if your events are references between many resources in your catalog, and you only want to document them in one place.
+
+## Shared services between domains
+
+<AddedIn version="3.3.0" pkg="@eventcatalog/generator-eventbridge" url="https://github.com/event-catalog/generators/releases/"/>
+
+Sometimes you may have services that are shared between domains.
+
+Using the `writeToRoot` option, EventCatalog will write your services to the root of your catalog, but keep your domains folder in the same structure you define.
+
+Your domains will still reference the services you define, but they will be stored in the root of your catalog, allowing you to manage them in a central place, rather than duplicating services in each domain.
+
+In the example below we have two domains, `orders` and `inventory`. We have a shared service between the two domains, the `Payment Service`.
+
+We define the `writeToRoot` option to true, which will write the services to the root of your catalog, but keep your domains folder in the same structure you define.
+
+```js title="eventcatalog.config.js"
+// ...rest of file
+generators: [
+  [
+    '@eventcatalog/generator-eventbridge',
+    {
+      services: [
+        { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }], writeToRoot: true }
+      ],
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+    }
+  ],
+  [
+    '@eventcatalog/generator-eventbridge',
+    {
+      services: [
+        { id: 'Payment Service', version: '1.0.0', sends: [{ prefix: "myapp"}], receives:[{ suffix: "Payment" }], writeToRoot: true }
+      ],
+      domain: { id: 'inventory', name: 'Inventory', version: '0.0.1' },
+    }
+  ],
+],
+```
+
+The outcome of this configuration will be:
+
+```md
+<!-- services stores in the root, referenced by other resources -->
+services/
+  payment-service/
+    index.mdx
+<!-- domains are still in their original location and reference the services in the root -->
+domains/
+  orders/
+    index.mdx
+  inventory/
+    index.mdx
+```
\ No newline at end of file
diff --git a/packages/core/docs/plugins/eventbridge/_category_.json b/packages/core/docs/plugins/eventbridge/_category_.json
new file mode 100644
index 000000000..767682771
--- /dev/null
+++ b/packages/core/docs/plugins/eventbridge/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Amazon EventBridge Plugin",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "amazon-eventbridge",
+    "title": "Amazon EventBridge",
+    "description": "Amazon EventBridge integration documentation for EventCatalog"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/plugins/eventcatalog-federation/00-introduction.md b/packages/core/docs/plugins/eventcatalog-federation/00-introduction.md
new file mode 100644
index 000000000..bc92edda4
--- /dev/null
+++ b/packages/core/docs/plugins/eventcatalog-federation/00-introduction.md
@@ -0,0 +1,69 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Federation
+sidebar_label: Introduction
+title: Introduction
+description: Merge multiple EventCatalog instances into a single catalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+
+<!-- <Beta /> -->
+<AddedIn version="2.18.0" />
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/KnTQkrt-7cc?si=RjEasqw_KJ6AN4cr" 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>
+
+---
+
+**EventCatalog Federation** is a feature that allows you to merge multiple EventCatalog instances into a single catalog. 
+
+
+This is useful if you:
+
+- Have **multiple teams** that want to own there own EventCatalog / Documentation
+- Want to **keep your documentation close to your code**
+- Want to **give ownership of documentation to different teams** and still have a single source of truth
+
+![EventCatalog Federation](/img/federation-example.png)
+
+<!-- ![Example](/img/integrations/openapi/openapi.png) -->
+
+## How it works
+
+EventCatalog Federation is powered by the [EventCatalog Federation Generator](https://github.com/event-catalog/generators).
+
+1. Your teams create their own EventCatalog instances
+2. Your teams document their services, messages and domains in their own EventCatalog
+3. Your teams commit their EventCatalog to a git repository, either in the same repo as your code or in a separate repo
+4. You setup a main catalog that will be the source of truth for your documentation
+5. You use the federation generator to merge your teams catalogs into the main catalog
+6. You setup CI/CD to keep your main catalog up to date with your teams catalogs (or just rebuild every X time)
+
+To use the federation generator you will need an EventCatalog Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+You can get a free 30-day trial Scale license key for the plugin.
+
+You can read more documentation:
+
+- [Configuring your main catalog](/docs/plugins/eventcatalog-federation/configuration)
+    - This is the main catalog for your organization. It will pull in and merge documentation from your teams catalogs.
+- [Configuring your team catalogs](/docs/plugins/eventcatalog-federation/setup-team-catalog)
+    - This is the documentation for how to setup your team catalogs
+
+## Commercial Use
+
+This plugin requires an EventCatalog Scale license key to be used.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial, you can continue using this plugin with EventCatalog Scale. 
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+
+<a href="https://eventcatalog.cloud" target="_blank" className="bg-purple-500 hover:bg-purple-100 cursor-pointer hover:text-white !hover:underline px-2 py-1 rounded-md text-white ">Login to EventCatalog Dashboard</a>
diff --git a/packages/core/docs/plugins/eventcatalog-federation/01-installation.md b/packages/core/docs/plugins/eventcatalog-federation/01-installation.md
new file mode 100644
index 000000000..806498c2c
--- /dev/null
+++ b/packages/core/docs/plugins/eventcatalog-federation/01-installation.md
@@ -0,0 +1,181 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Federation
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog Federation plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+
+<PluginLicense url="#commercial-use" />
+
+The EventCatalog Federation plugin is designed for your [main catalog](/docs/plugins/eventcatalog-federation/configuration).
+
+This plugin will allow you to merge multiple EventCatalog instances into a single catalog.
+
+## Prerequisites
+
+- [Installed EventCatalog](/docs/development/getting-started/installation)
+
+## Installation
+
+Run the command below to install the EventCatalog Federation plugin.
+
+```sh
+npm i @eventcatalog/generator-federation
+```
+
+## Configuration
+
+Configure the plugin in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators`.
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+    [
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitHub repository, (generator supports any Git source e.g GitLab, Bitbucket, etc)
+        source: 'git@github.com:event-catalog/generators.git',
+
+        // specifying the branch to pull from (default is main)
+        branch: 'main',
+
+        // optional (specify which files you want to copy from the repository)
+        copy: [
+          {
+            // importing content from the customer-experience-team catalog
+            content: 'examples/generator-federation/basic/customer-experience-team/services',
+            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
+            destination: path.resolve(__dirname, 'services')
+          },
+          {
+            // importing content from the customer-experience-team catalog
+            content: 'examples/generator-federation/basic/customer-experience-team/teams',
+            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
+            destination: path.resolve(__dirname, 'teams')
+          },
+          {
+            // importing content from the customer-experience-team catalog
+            content: 'examples/generator-federation/basic/customer-experience-team/users',
+            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
+            destination: path.resolve(__dirname, 'users')
+          }
+        ],
+
+        // optional, if you want to merge and override any conflicts then set to true (default is false)
+        override: true,
+
+        // optional, if you want the plugin to error 
+        // if there are duplicate resources in your 
+        // main catalog then set to true (default is false)
+        enforceUniqueResources: true
+      },
+    ],
+    // Payment Team
+    // When no `copy` values are provided, the plugin will copy eventcatalog files for you.
+    [
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitHub repository
+        source: 'git@github.com:event-catalog/generators.git',
+
+        // specifying the directory of the eventcatalog in your project (default it the root directory)
+        // This example clones the generators repository, and looks for the eventcatalog in the my-project-eventcatalog directory
+        sourceRootDir: 'my-project-eventcatalog'
+
+        // specifying the branch to pull from (default is main)
+        branch: 'main',
+
+        // optional, if you want to merge and override any conflicts then set to true (default is false)
+        override: true,
+
+        // optional, if you want the plugin to error 
+        // if there are duplicate resources in your 
+        // main catalog then set to true (default is false)
+        enforceUniqueResources: true
+      },
+    ],
+  ],
+```
+
+### Configure license key
+
+The EventCatalog Federation plugin requires an EventCatalog Scale license key to work with EventCatalog.
+
+You can get a trial Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+You have a few options for setting the license key:
+
+1. [Setting license key in `.env` file (recommended)](#setting-license-key-in-env-file-recommended)
+2. [Setting license key in eventcatalog.config.js](#setting-license-key-in-eventcatalogconfigjs)
+
+#### 1. Setting license key in `.env` file (recommended) {#setting-license-key-in-env-file-recommended}
+
+<AddedIn version="2.35.4" />
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+:::tip Using an Older API Key?
+
+If you already have an older Federation plugin key, you can still use it with the Federation-specific environment variable.
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_FEDERATION=your-license-key
+```
+
+:::
+
+#### 2. Setting license key in eventcatalog.config.js {#setting-license-key-in-eventcatalogconfigjs}
+
+If you prefer, you can set the license key in the `eventcatalog.config.js` file
+using the `licenseKey` property in the EventCatalog Federation plugin.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-federation',
+      {
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_SCALE_LICENSE_KEY
+      },
+    ],
+  ],
+};
+```
+
+#### White listing EventCatalog domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+## Run the generator
+
+Once you have configured the plugin and license key you can run the generator.
+
+```sh
+npm run generate
+```
+
+## View your catalog
+
+Run your catalog locally to see the changes.
+
+```sh
+npm run dev
+```
+
+## Any questions or need help?
+
+If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
+
+
diff --git a/packages/core/docs/plugins/eventcatalog-federation/02-plugin-configuration.md b/packages/core/docs/plugins/eventcatalog-federation/02-plugin-configuration.md
new file mode 100644
index 000000000..e0b8860a4
--- /dev/null
+++ b/packages/core/docs/plugins/eventcatalog-federation/02-plugin-configuration.md
@@ -0,0 +1,208 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Federation
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog Federation plugin
+---
+
+API Configuration for the EventCatalog Federation plugin
+
+
+
+## Overview
+
+The EventCatalog Federation plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+## Configuration Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `source` | string | Yes | - | Git repository URL (supports any git provider e.g GitHub, GitLab, Bitbucket) |
+| `sourceRootDir` | string | No | - | The root directory for your files. For example if your repository is organized with subdirectories, you can specify the root directory to use for the import (e.g `'my-awesome-catalog'`, would be the root directory for the import). |
+| `branch` | string | No | `'main'` | Branch to use for the import. Default is `'main'`. |
+| `copy` | object | No | - | Copy options for the import. You can pick which files to copy from the remote repository. |
+| `copy.content` | string | No | - | Content to copy to the destination. |
+| `copy.destination` | string | No | - | Destination path to copy the content to. |
+| `debug` | boolean | No | `false` | Enable debug mode. |
+| `override` | boolean | No | `false` | Override existing files in the destination. |
+| `destination` | string | No | - | Destination path to copy the content to, if you don't specify the `copy` option, the content will be copied to the root of the destination path. |
+| `enforceUniqueResources` | boolean | No | `false` | Setting to true. The plugin will enforce unique resources in the destination and error if any resources are not unique. |
+
+## Example Configuration
+
+```js title="eventcatalog.config.js"
+import path from "path";
+import url from "url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  cId: "10b46030-5736-4600-8254-421c3ed56e47",
+  title: "MetaRetail Inc",
+  tagline: "Fake Retail Company for EventCatalog Demo",
+  organizationName: "MetaRetail Inc",
+  homepageLink: "https://eventcatalog.dev/",
+  editUrl: "https://github.com/boyney123/eventcatalog-demo/edit/master",
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: "/",
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: "EventCatalog Logo",
+    src: "/logo.png",
+    text: "MetaRetail Inc",
+  },
+  docs: {
+    sidebar: {
+      // Should the sub heading be rendered in the docs sidebar?
+      showPageHeadings: true,
+    },
+  },
+  generators: [
+    [
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitHub repository
+        source: 'git@github.com:event-catalog/generators.git',
+
+        // specifying the branch to pull from (default is main)
+        branch: 'main',
+
+        // specify which files you want to copy from the repository
+        copy: [
+          {
+            // importing content from the customer-experience-team catalog
+            content: 'examples/generator-federation/basic/customer-experience-team/services',
+            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
+            destination: path.resolve(__dirname, 'services')
+          },
+          {
+            // importing content from the customer-experience-team catalog
+            content: 'examples/generator-federation/basic/customer-experience-team/teams',
+            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
+            destination: path.resolve(__dirname, 'teams')
+          },
+          {
+            // importing content from the customer-experience-team catalog
+            content: 'examples/generator-federation/basic/customer-experience-team/users',
+            // specify the target path in your main catalog, here we are importing the services from the customer-experience-team catalog
+            destination: path.resolve(__dirname, 'users')
+          }
+        ],
+
+        // optional, if you want to merge and override any conflicts then set to true (default is false)
+        override: true,
+
+        // optional, if you want the plugin to error 
+        // if there are duplicate resources in your 
+        // main catalog then set to true (default is false)
+        enforceUniqueResources: true
+      },
+    ],
+    // Payment Team
+    [
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitHub repository
+        source: 'git@github.com:event-catalog/generators.git',
+
+        // specifying the branch to pull from (default is main)
+        branch: 'main',
+
+        // specify which files you want to copy from the repository
+        copy: [
+          {
+            // importing content from the payment-team catalog
+            content: 'examples/generator-federation/basic/payment-team/services',
+            // specify the target path in your main catalog, here we are importing the services from the payment-team catalog
+            destination: path.resolve(__dirname, 'services')
+          },
+          {
+            // importing content from the payment-team catalog
+            content: 'examples/generator-federation/basic/payment-team/teams',
+            // specify the target path in your main catalog, here we are importing the services from the payment-team catalog
+            destination: path.resolve(__dirname, 'teams')
+          },
+          {
+            // importing content from the payment-team catalog
+            content: 'examples/generator-federation/basic/payment-team/users',
+            // specify the target path in your main catalog, here we are importing the services from the payment-team catalog
+            destination: path.resolve(__dirname, 'users')
+          }
+        ],
+
+        // optional, if you want to merge and override any conflicts then set to true (default is false)
+        override: true,
+
+        // optional, if you want the plugin to error 
+        // if there are duplicate resources in your 
+        // main catalog then set to true (default is false)
+        enforceUniqueResources: true
+      },
+    ],
+    [
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitHub repository
+        source: 'git@github.com:event-catalog/generators.git',
+
+        // specifying the branch to pull from (default is main)
+        branch: 'main',
+
+        // specify which files you want to copy from the repository
+        copy: [
+          {
+            // importing content from the order-management-team catalog
+            content: 'examples/generator-federation/basic/order-management-team/services',
+            // specify the target path in your main catalog, here we are importing the services from the order-management-team catalog
+            destination: path.resolve(__dirname, 'services')
+          },
+          {
+            // importing content from the order-management-team catalog
+            content: 'examples/generator-federation/basic/order-management-team/teams',
+            // specify the target path in your main catalog, here we are importing the services from the order-management-team catalog
+            destination: path.resolve(__dirname, 'teams')
+          },
+          {
+            // importing content from the order-management-team catalog
+            content: 'examples/generator-federation/basic/order-management-team/users',
+            // specify the target path in your main catalog, here we are importing the services from the order-management-team catalog
+            destination: path.resolve(__dirname, 'users')
+          }
+        ],
+
+        // optional, if you want to merge and override any conflicts then set to true (default is false)
+        override: true,
+
+        // optional, if you want the plugin to error 
+        // if there are duplicate resources in your 
+        // main catalog then set to true (default is false)
+        enforceUniqueResources: true
+      },
+    ],
+  ],
+};
+```
+
+You can view an example configuration in the [EventCatalog Federation plugin GitHub repository](https://github.com/event-catalog/generators/blob/main/examples/generator-federation/basic/central-catalog/eventcatalog.config.js).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/core/docs/plugins/eventcatalog-federation/03-examples.md b/packages/core/docs/plugins/eventcatalog-federation/03-examples.md
new file mode 100644
index 000000000..aff3b08bb
--- /dev/null
+++ b/packages/core/docs/plugins/eventcatalog-federation/03-examples.md
@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the Federation plugin
+---
+
+You can find many examples of using the Federation plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [Federation Example](https://github.com/event-catalog/generators/tree/main/examples/generator-federation/basic)
+  -  An example of merging multiple catalogs into a single catalog from different teams.
diff --git a/packages/core/docs/plugins/eventcatalog-federation/04-configuration.md b/packages/core/docs/plugins/eventcatalog-federation/04-configuration.md
new file mode 100644
index 000000000..d66b658e3
--- /dev/null
+++ b/packages/core/docs/plugins/eventcatalog-federation/04-configuration.md
@@ -0,0 +1,193 @@
+---
+keywords:
+- EventCatalog components
+sidebar_label: Configuring main catalog
+title: Setup main catalog
+description: Configuring federation in your EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+
+<!-- <Beta /> -->
+<AddedIn version="2.18.0" />
+<PluginLicense url="/docs/plugins/eventcatalog-federation/intro#commercial-use" />
+
+EventCatalog Federation is powered by the [EventCatalog Federation Generator](https://github.com/event-catalog/generators), this let's you define the repositories you want to merge into your main catalog.
+
+### Getting started
+
+If you haven't already, you will need to create a new EventCatalog instance that will be your main catalog, this will be the one you will use to generate your documentation and host your documentation for your users.
+
+You can create a new empty EventCatalog instance using the `eventcatalog` CLI.
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest main-catalog --empty
+```
+
+Next you will need to install the `federation` generator (in your main catalog).
+
+```bash
+npm install @eventcatalog/generator-federation
+```
+
+#### Configuring the federation generator
+
+You need to configure the federation generator in your main catalog, this is done by adding the generator to the `generators` section of your `eventcatalog.config.js` file.
+
+Using the federation generator you need to specify:
+
+- The source repository to pull from (your teams catalogs)
+- The branch to pull from (default is `main`)
+- The files to copy from the source repository to your main catalog 
+- If you want to override any conflicts (`last-write-wins`)
+- If you want the plugin to error if there are duplicate resources in your main catalog
+
+Here is an example of how you can configure the federation generator.
+ This demo shows:
+
+- Pulling information from a GitHub repository
+- Pulling information from a GitLab repository
+- Copying files from the source repository to your main catalog
+- Overriding any conflicts (`last-write-wins`)
+- Enforcing unique resources in your main catalog
+
+```js
+import path from 'path';
+import url from 'url';
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  cId: 'fe4efb73-11db-4bea-ad2b-d7e1d424a0c1',
+  title: 'OurLogix',
+  tagline: 'A comprehensive logistics and shipping management company',
+  organizationName: 'OurLogix',
+  homepageLink: 'https://eventcatalog.dev/',
+  landingPage: '',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  trailingSlash: false,
+  base: '/',
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'OurLogix',
+  },
+  docs: {
+    sidebar: {
+      showPageHeadings: true,
+    },
+  },
+  // Add the federation generator to your main catalog
+  generators: [
+    [
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitHub repository (this would be your teams catalogs)
+        source: 'git@github.com:event-catalog/eventcatalog.git',
+
+        // specifying the branch to pull from (default is main)
+        branch: 'main',
+
+        // specify which files you want to copy from the repository 
+        copy: [
+          { 
+            // specify the path in the external catalog
+            content: 'examples/default/components',
+
+            // specify the target path in your main catalog
+            destination: path.resolve(__dirname, 'components')
+          },
+          { 
+            // specify the path in the external catalog
+            content: 'examples/default/domains/Orders/services',
+
+            // specify the target path in your main catalog
+            destination: path.resolve(__dirname, 'services')
+          },
+          {
+            // specify the path in the external catalog
+            content: 'examples/default/teams',
+
+            // specify the target path in your main catalog
+            destination: path.resolve(__dirname, 'teams')
+          },
+          {
+            // specify the path in the external catalog
+            content: 'examples/default/domains/Payment/services',
+
+            // specify the target path in your main catalog
+            destination: path.resolve(__dirname, 'services')
+          }
+        ],
+
+        // optional, if you want to merge and override any conflicts then set to true (default is false)
+        override: true,
+
+        // optional, if you want the plugin to error 
+        // if there are duplicate resources in your 
+        // main catalog then set to true (default is false)
+        enforceUniqueResources: true
+      },
+    ],
+    [
+      // This example does not specify the files to copy, the plugin will find all the files in the repository and copy them to your main catalog
+      '@eventcatalog/generator-federation',
+      {
+        // Pulling information from a GitLab repository, it will check for events, queries, domains, services, teams, etc
+        // Any matching files will be copied to your main catalog
+        source: 'git@gitlab.com:boyneyy123/eventcatalog-gitlab-example.git',
+        branch: 'main',
+        destination: path.resolve(__dirname),
+        override: true,
+        enforceUniqueResources: true
+      },
+    ],
+  ],
+};
+
+```
+
+Generator options:
+
+- `source` - The source repository to pull from (required)
+- `branch` - The branch to pull from (default is `main`)
+- `copy` - The files to copy from the source repository to your main catalog (optional, if not specified the plugin will find all the files in the repository and copy them to your main catalog)
+- `override` - If you want to override any conflicts (`last-write-wins`) (default is `false`)
+- `enforceUniqueResources` - If you want the plugin to error if there are duplicate resources in your main catalog (default is `false`). 
+
+If you want to learn more about the federation generator you can read the [EventCatalog Federation Generator documentation](https://github.com/event-catalog/generators).
+
+### Running the generator
+
+You will need an EventCatalog Scale license key to run the generator. You can get a free 30-day trial Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+Once you have configured the federation generator you can run the generator.
+
+Inside your main catalog run the following command:
+
+```bash
+npm run generate
+```
+
+This will generate the resources from the source repositories and copy them to your main catalog and handle any conflicts if you have configured the generator to do so.
+
+:::tip Combining multiple generators
+EventCatalog offers other plugins including [AsyncAPI](/docs/plugins/asyncapi/intro) and [OpenAPI](/docs/plugins/openapi/intro) plugins. You can combine generators to pull information from multiple sources and generate your documentation.
+:::
+
+### Authentication
+
+The federation generator uses `git` under the hood, so you will need to ensure you have the correct authentication setup for your git provider on the machine you are running the generator on.
+
+### View demo
+
+You can view and run a demo of the federation generator on GitHub.
+
+- [View demo](https://github.com/event-catalog/generators/tree/main/examples/generator-federation/basic)
+
+### Need help or got a question?
+
+If you need help or got a question, please [create an issue](https://github.com/event-catalog/eventcatalog/issues/new) or [join the community on Discord](https://eventcatalog.dev/discord).
diff --git a/packages/core/docs/plugins/eventcatalog-federation/05-setup-team-catalog.md b/packages/core/docs/plugins/eventcatalog-federation/05-setup-team-catalog.md
new file mode 100644
index 000000000..e9c9a9dcf
--- /dev/null
+++ b/packages/core/docs/plugins/eventcatalog-federation/05-setup-team-catalog.md
@@ -0,0 +1,96 @@
+---
+keywords:
+- EventCatalog components
+sidebar_label: Configuring team catalogs
+title: Configuring team catalogs
+description: Configuring federation in your EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+
+<!-- <Beta /> -->
+<AddedIn version="2.18.0" />
+<PluginLicense url="/docs/plugins/eventcatalog-federation/intro#commercial-use" />
+
+Multiple teams can own their own EventCatalog, this is useful if you have multiple teams that want to own their own EventCatalog / Documentation.
+
+**Why would your teams want their own EventCatalog?**
+
+- They want to own their own documentation
+- They want to keep their documentation close to their code
+- They want to control their own teams documentation but share it with the rest of the organization
+
+### Getting started
+
+To get started you will need to create a new EventCatalog instance for your team.
+
+You can run the following command in any directory you want to create your team catalog in.
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest team-catalog
+```
+
+This will create a new EventCatalog instance in the current directory called `team-catalog`.
+
+Your team can document their own services, messages and domains in this catalog, and these can be merged into the main catalog using the federation generator.
+
+To help you get started:
+
+- [Creating domains in EventCatalog](/docs/development/guides/domains/introduction)
+- [Creating services in EventCatalog](/docs/development/guides/resources/services/introduction)
+- [Creating events in EventCatalog](/docs/development/guides/resources/messages/message-types/events)
+- [Creating commands in EventCatalog](/docs/development/guides/resources/messages/message-types/commands)
+- [Creating queries in EventCatalog](/docs/development/guides/resources/messages/message-types/queries)
+
+Once your teams have created their own documentation you can [merge them into the main catalog using the federation generator](https://github.com/event-catalog/generators).
+
+### Mocking out dependencies in your Catalog
+
+<AddedIn version="2.18.0" />
+
+If you have many team catalogs you can mock out `dependencies` in your catalog. 
+
+**Why would you want to mock out dependencies?**
+
+- Team A wants to consume an event from Team B, but Team B owns the event documentation
+- Team A mocks out the event using the `dependencies` section of their `eventcatalog.config.js` file
+- EventCatalog renders a mocked page for Team B event.
+- When merging the catalogs, the federation generator will resolve events.
+
+**How to use dependencies?**
+
+You can define dependencies in your `eventcatalog.config.js` file in the `dependencies` section.
+
+```js title="eventcatalog.config.js"
+// rest of your config
+dependencies: {
+  events: [{
+    id: 'OrderPlaced',
+    version: '1.0.0', // optional
+  }, {
+    id: 'OrderShipped',
+    version: '1.0.0', // optional
+  }]
+}
+// rest of your config
+```
+
+This will mock out the `OrderPlaced` and `OrderShipped` events in the catalog and EventCatalog will render a mocked page for these events.
+
+You can also mock out domains, services, events, commands and queries by changing the key to `domains`, `services`, `events`, `commands` and `queries` respectively.
+
+Example:
+
+```js title="eventcatalog.config.js"
+// rest of your config
+dependencies: {
+  domains: [{
+    id: 'Order',
+    version: '1.0.0', // optional
+  }]
+}
+// rest of your config
+```
+
diff --git a/packages/core/docs/plugins/eventcatalog-federation/_category_.json b/packages/core/docs/plugins/eventcatalog-federation/_category_.json
new file mode 100644
index 000000000..6f4aab0b8
--- /dev/null
+++ b/packages/core/docs/plugins/eventcatalog-federation/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "EventCatalog Federation",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/eventcatalog-federation",
+    "description": "Merge multiple EventCatalog instances into a single catalog."
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/plugins/github/00-intro.md b/packages/core/docs/plugins/github/00-intro.md
new file mode 100644
index 000000000..66a88c447
--- /dev/null
+++ b/packages/core/docs/plugins/github/00-intro.md
@@ -0,0 +1,93 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Introduction
+description: Getting started with GitHub plugin
+---
+
+
+<!-- import PluginLicense from '@site/src/components/MDX/PluginLicense'; -->
+
+<!-- <PluginLicense url="#commercial-use" /> -->
+
+<!-- <iframe width="100%" height="515" src="https://www.youtube.com/embed/NMZKnPKx-L0?si=og1Nvnr3FfPfAqn4" 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> -->
+
+<iframe width="100%" height="515" src="https://www.youtube.com/embed/o2ryPdBa-68?si=2d1cynW_wgzNhbaV" 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>
+
+---
+
+Many folks are using GitHub as a source of truth for their schemas. This gives the flexibility to use any schema format, version control, and have review and approval processes.
+
+EventCatalog supports documenting any schema format, and you can use the [EventCatalog GitHub plugin](https://github.com/event-catalog/generators/tree/main/packages/generator-github) to pull your schemas into EventCatalog and keep them in sync along side your documentation.
+
+You can choose either to import all your schemas, or specific folders or files, and assign them to producers, consumers, domains and owners.
+
+:::info Why are people using GitHub as a source of truth for their schemas?
+GitHub is a popular tool for version control and collaboration. It gives the flexibility to use any schema format, version control, and have review and approval processes.
+:::
+
+### Core Features of the GitHub plugin
+
+The EventCatalog GitHub plugin can provide you with many features:
+
+- 📃 Pull and sync your schemas from your GitHub repository to EventCatalog
+- 📃 Keep your schemas in sync with your producers and consumers documentation
+- 📃 Supports any schema format (e.g Avro, Protobuf, JSON)
+- 📃 Import all schemas, or specific folders/files
+- ⭐ **Go beyond a schema.** Add semantic meaning to your schemas, business logic and much more. Help your developers and teams understand the meaning behind the schemas with clear documentation and visualisations.
+- 📊 Visualise producers and consumers in your architecture ([demo](https://demo.eventcatalog.dev/visualiser))
+- ⭐ Download synced schemas from EventCatalog (e.g Avro, Protobuf, JSON) ([demo](https://demo.eventcatalog.dev/docs/events/InventoryAdjusted/0.0.4))
+- 📃 Assign schemas to **events**, **commands** and **queries**
+- ⭐ Discoverability feature (search, filter and more) ([demo](https://demo.eventcatalog.dev/discover/events))
+- ⭐ And much more...
+
+### How it works
+
+1. Install the GitHub plugin on your EventCatalog instance
+1. Configure the plugin (e.g. repository, branch, path to schemas)
+1. Run the plugin to import your schemas into EventCatalog
+1. View and deploy your catalog
+
+![Example](/img/integrations/github/github-generator.png)
+
+:::info How are my schemas kept in sync?
+
+EventCatalog is a static site generator, and as such the schemas are pulled into EventCatalog when the site is built.
+
+When your schemas change in GitHub, you can re-run your build to pull in the latest changes. You can build EventCatalog as many times as you want, and it will only pull in the changes from GitHub if there are any changes.
+
+Any documentation you add to your schemas in EventCatalog will persist between builds. Only the schemas are updated.
+
+:::
+
+## Commercial and License
+
+This plugin requires an EventCatalog Scale license key to be used.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial, you can continue using this plugin with EventCatalog Scale.
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## Need a demo?
+
+If you would like a demo of the plugin, please feel free to reach out to us and book a time to chat at hello@eventcatalog.dev.
+
+## License FAQ
+
+### What is the license key for?
+The EventCatalog Scale license key is required to use the GitHub plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get an EventCatalog Scale license key?
+You can obtain an EventCatalog Scale license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 30-day free trial.
+
+### Terms
+- **Trial Period**: 30-day free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can continue with EventCatalog Scale through [EventCatalog Cloud](https://eventcatalog.cloud).
diff --git a/packages/core/docs/plugins/github/01-installation.md b/packages/core/docs/plugins/github/01-installation.md
new file mode 100644
index 000000000..318a1182e
--- /dev/null
+++ b/packages/core/docs/plugins/github/01-installation.md
@@ -0,0 +1,300 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog GitHub
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog GitHub plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PluginLicense url="#commercial-use" />
+
+The GitHub plugin is used to pull and sync your schemas from your GitHub repository to EventCatalog, these can be public or private repositories.
+
+You can map your schemas from your GitHub repository to commands, events and queries in your catalog, and assign these to services (producers and consumers) and domains.
+
+## Installation
+
+Run the command below to install the EventCatalog GitHub plugin.
+
+:::tip "Don't have an EventCatalog project yet?"
+If you don't have an EventCatalog project yet, you can follow the instructions in the [Getting Started](/docs/development/getting-started/installation) guide.
+:::
+
+<Tabs>
+  <TabItem value="apple" label="Install on existing catalog" default>
+    ```bash
+npm i @eventcatalog/generator-github
+```
+  </TabItem>
+  <TabItem value="orange" label="Create new catalog with GitHub plugin">
+     ```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --template github
+```
+  </TabItem>
+</Tabs>
+
+## Configuration
+
+To use the plugin you need to configure it in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators` array.
+
+<Tabs>
+  <TabItem value="apple" label="Assign schemas to commands, events and queries" default>
+
+  In this example we assign schemas to commands, events and queries in our catalog.
+
+  We don't create any producers or consumers in this example.
+
+  :::info "Why would I import schemas without assigning them to producers or consumers?"
+  You may just want to import the schemas into EventCatalog (events, queries, commands) without assigning them to producers or consumers.
+  You can assign them later to producers and consumers yourself in EventCatalog.
+  :::
+
+  
+    ```js title="eventcatalog.config.js"
+    // ...
+    generators: [
+      // 1. Import all schemas from a Confluent Schema Registry
+      [
+        '@eventcatalog/generator-github',
+        {
+          // The HTTP or SSH URL of your GitHub repository
+          source: 'https://github.com/event-catalog/eventcatalog',
+          // The branch to pull schemas from (default: main)
+          branch: 'main',
+          // The root path to your schemas
+          path: 'some-folder/schemas',
+          messages: [
+            {
+              // the id of the message, needed for eventcatalog
+              id: 'place-order',
+              // Optional name for your message (if not provided, the id will be used)
+              name: 'Place Order',
+              // Optional version for your message (if not provided, default version of 1 will be used)
+              version: '2.1',
+              // The path to the schema file (relative to the root path, some-folder/schemas/place-order.avro)
+              schemaPath: 'place-order.avro',
+              // The type of message, can be 'command', 'event' or 'query'
+              type: 'command',
+            },
+            // just required fields, defaulting version and name
+            {
+              id: 'order-shipped',
+              // The path to the schema file (relative to the root path, some-folder/schemas/order-shipped.avro)
+              schemaPath: 'order-shipped.avro',
+              type: 'event',
+            },
+          ]
+        },
+      ],
+    ];
+    ```
+  </TabItem>
+  <TabItem value="orange" label="Import schemas and assign them to producers and consumers (services)">
+
+In this example we import schemas from a GitHub repository, and assign them to producers and consumers (services).
+We also create a domain and assign our services to it. 
+
+:::info Adding documentation to your schemas
+This plugin will import and keep your schemas in sync with your producers and consumers.
+
+You can still use EventCatalog to document your schemas, services and domains using markdown. The markdown is persisted between imports.
+This let's you add semantic meaning to your schemas, and document them for your teams, whilst keeping your schemas in sync with your producers and consumers.
+:::
+
+In this example we:
+
+- Create two services (producers and consumers)
+  - `Orders Service`
+    - Sends `place-order` command
+    - Receives `order-shipped` event
+  - `Inventory Service`
+    - Sends `inventory-updated` event
+    - Receives `order-placed` event
+- Create a domain `Retail Domain`
+  - Assign the services to the domain
+
+
+```js title="eventcatalog.config.js"
+// ...
+ [
+  '@eventcatalog/generator-github',
+      {
+        // The URL of your GitHub repository
+        source: 'https://github.com/event-catalog/eventcatalog',
+        // The branch to pull schemas from (default: main)
+        branch: 'main',
+        // The root path to your schemas
+        path: 'some-folder/schemas',
+        
+        // The producers and consumers (services) to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // the messages this service sends
+            sends: [{
+              id: 'place-order',
+              version: '2.1',
+              // The path to the schema file (relative to the root path, some-folder/schemas/place-order.avro)
+              schemaPath: 'place-order.avro',
+              // The type of message, can be 'command', 'event' or 'query'
+              type: 'command',
+            }],
+            // the messages this service receives
+            receives: [{
+              id: 'order-shipped',
+              version: '1.0',
+              // The path to the schema file (relative to the root path, some-folder/schemas/order-shipped.avro)
+              schemaPath: 'order-shipped.avro',
+              // The type of message, can be 'command', 'event' or 'query'
+              type: 'event',
+            }],
+          },
+          {
+            id: 'Inventory Service',
+            version: '1.0.0',
+            // the messages this service sends
+            sends: [{
+              id: 'inventory-updated',
+              version: '1.0',
+              // The path to the schema file (relative to the root path, some-folder/schemas/inventory-updated.avro)
+              schemaPath: 'inventory-updated.avro',
+              // The type of message, can be 'command', 'event' or 'query'
+              type: 'event',
+            }],
+            // the messages this service receives
+            receives: [{
+              id: 'order-placed',
+              version: '1.0',
+              // The path to the schema file (relative to the root path, some-folder/schemas/order-placed.avro)
+              schemaPath: 'order-placed.avro',
+              // The type of message, can be 'command', 'event' or 'query'
+              type: 'event',
+            }],
+          },
+        ],
+        // We assign the services to a domain "Retail Domain" (optional)
+        domain: {
+          id: 'retail-domain',
+          name: 'Retail Domain',
+          version: '1.0.0',
+        }
+      },
+    ]
+```  
+  </TabItem>
+</Tabs>
+
+### Configure API keys
+
+The EventCatalog GitHub plugin requires API keys in your environment variables.
+
+1. An EventCatalog Scale license key for the GitHub plugin (30-day trial, at [EventCatalog Cloud](https://eventcatalog.cloud))
+
+Create a `.env` file in the root, and add your keys to the project.
+
+```bash title=".env"
+# EventCatalog license key
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+:::tip Using an Older API Key?
+
+If you already have an older GitHub plugin key, you can still use it with the plugin-specific environment variable.
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_GITHUB=your-license-key
+```
+
+:::
+
+#### White listing EventCatalog domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+### Private repository authentication
+
+<AddedIn version="1.0.0" pkg="@eventcatalog/generator-github" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+The GitHub plugin supports authentication for private repositories using GitHub personal access tokens (PAT) or GitHub App installation tokens.
+
+You can authenticate in two ways:
+
+**Option 1: Environment variable (recommended)**
+
+Set the `EVENTCATALOG_GITHUB_TOKEN` environment variable in your `.env` file.
+
+```bash title=".env"
+# EventCatalog license key
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+
+# GitHub token for private repository access
+EVENTCATALOG_GITHUB_TOKEN=ghp_your_token_here
+```
+
+**Option 2: Configuration option**
+
+Pass the token directly in your configuration file.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-github',
+    {
+      source: 'https://github.com/your-org/private-repo',
+      path: 'schemas',
+      token: process.env.MY_GITHUB_TOKEN,
+      // ... rest of configuration
+    },
+  ],
+];
+```
+
+:::tip Create a GitHub token
+To create a personal access token, visit [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens). For private repositories, you need the `repo` scope.
+:::
+
+:::info Public repositories
+For public repositories, authentication is not required. The plugin will work without any token configuration.
+:::
+
+### Running the plugin
+
+Run the plugin to import your schemas into EventCatalog.
+
+_This command will run the generators in your eventcatalog.config.js file._
+
+```
+npm run generate
+```
+
+#### View your catalog
+
+Run your catalog locally to see the changes
+
+```
+npm run dev
+```
+
+#### Build your catalog for production
+
+```
+npm run build
+```
+
+
+
+## Any questions or need help?
+
+If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
+
+You can also find some examples of the plugin in action in our examples repository: [eventcatalog/examples](https://github.com/event-catalog/generators/tree/main/examples/generator-github).
diff --git a/packages/core/docs/plugins/github/02-plugin-configuration.md b/packages/core/docs/plugins/github/02-plugin-configuration.md
new file mode 100644
index 000000000..4c1b3c549
--- /dev/null
+++ b/packages/core/docs/plugins/github/02-plugin-configuration.md
@@ -0,0 +1,253 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog GitHub plugin
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog GitHub plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+# Plugin Configuration
+
+## Overview
+
+The EventCatalog GitHub plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+
+## Required Configuration Options
+
+| Option | Type | Required | Example | Description |
+|--------|------|----------|---------|-------------|
+| `source` | `string` | Yes | `https://github.com/event-catalog/eventcatalog.git` | The HTTP or SSH URL of the GitHub repository. |
+| `path` | `string` | Yes | `examples/default` | The path to the directory in the repository that contains the schemas. |
+
+
+## Optional Configuration Options
+
+<AddedIn version="1.0.0" pkg="@eventcatalog/generator-github" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+### Authentication
+
+| Option | Type | Required | Example | Description |
+|--------|------|----------|---------|-------------|
+| `token` | `string` | No | `process.env.MY_GITHUB_TOKEN` | GitHub personal access token or GitHub App installation token for private repository access. Can also be set via `EVENTCATALOG_GITHUB_TOKEN` environment variable. |
+
+<details>
+<summary>See an example configuration - Private repository authentication</summary>
+
+Access private repositories by providing a GitHub token.
+
+```js
+// ...rest of eventcatalog.config.js file
+generators: [
+  [
+    '@eventcatalog/generator-github',
+    {
+      source: 'https://github.com/your-org/private-repo',
+      path: 'schemas',
+      token: process.env.GITHUB_TOKEN,
+      messages: [
+        {
+          id: 'order-placed',
+          schemaPath: 'order-placed.avro',
+          type: 'event',
+        },
+      ]
+    }
+  ]
+]
+```
+</details>
+
+### Messages
+
+You can assign schemas to messages (events, commands, or commands) in EventCatalog.
+
+:::tip Documentation
+Remember the GitHub plugin will keep your schemas in sync with your messages. Any documentation (markdown) added to your messages will be persisted between imports and versions.
+:::
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `messages` | object | - | - | List of messages to assign the schemas to. |
+| `messages.id` | string | Yes | - | EventCatalog ID for the message. |
+| `messages.name` | string | No | - | Friendly name of the message, if not provided the message id will be used. |
+| `messages.version` | string | No | - | Version of the message, recommended you set this to the version of the message in the repository, Defaults to `1`. |
+| `messages.schemaPath` | string | Yes | - | The path to your schema file in the repository, relative to the path configured in the `path` option. For example if `path` is `examples/default` and your `schemaPath` is `/schemas/order-placed.avro`, the path used will be `examples/default/schemas/order-placed.avro`. |
+| `messages.type` | string | Yes | - | Type of the message (`event`, `command`, or `query`). |
+
+<details>
+<summary>See an example configuration - Assign schemas to messages</summary>
+
+In this example we assign schemas to messages.
+
+```js
+// ...rest of eventcatalog.config.js file
+generators: [
+  [
+    '@eventcatalog/generator-github',
+    {
+      source: 'https://github.com/event-catalog/eventcatalog.git',
+      path: 'examples/default',
+      messages: [
+        {
+          id: 'order-placed',
+          name: 'Order Placed',
+          version: '1',
+          schemaPath: 'domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro',
+          type: 'event',
+        }, 
+        {
+          id: 'update-order',
+          name: 'Update Order',
+          version: '1',
+          schemaPath: 'domains/Orders/services/InventoryService/commands/UpdateOrder/schema.avro',
+          type: 'command',
+        }, 
+      ]
+    }
+  ]
+]
+```
+</details>
+
+### Services
+
+You can assign your schemas to your producers and consumers (services).
+
+:::tip Documentation
+Remember the GitHub plugin will keep your schemas in sync with your services. Any documentation (markdown) added to your services will be persisted between imports and versions.
+:::
+
+
+| Option | Type | Default | Required | Description |
+|--------|------|---------|----------|-------------|
+| `services` | object | - | Yes | List of producers/consumers (services) to assign the schemas to. |
+| `services.id` | string | - | Yes | EventCatalog ID for the service. |
+| `services.sends` | Message[] | - | No | Configuration to assign schemas to a producer. The schemas and topic defined here will be assigned to the producer. |
+| `services.receives` | Message[] | - | No | Configuration to assign schemas to a consumer. The schemas and topic defined here will be assigned to the consumer. |
+
+<details>
+<summary>See an example configuration - Assign schemas to producers and consumers</summary>
+
+In this example we assign schemas to producers and consumers (services).
+
+```js
+// ...rest of eventcatalog.config.js file
+generators: [
+  [
+    '@eventcatalog/generator-github',
+    {
+      source: 'https://github.com/event-catalog/eventcatalog.git',
+      path: 'examples/default',
+      services: [
+        {
+          id: 'Orders Service',
+          // The order service sends these messages...
+          sends: [
+            {
+              id: 'order-placed', 
+              name: 'Order Placed',
+              version: '1',
+              schemaPath: 'domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro',
+              type: 'event',
+            }
+          ],
+          // The order service receives these messages...
+          receives: [{
+            {
+              id: 'place-order', 
+              version: '1',
+              schemaPath: 'domains/Orders/services/InventoryService/commands/UpdateOrder/schema.avro',
+              type: 'command',
+            }
+          }]
+        }
+      ]
+    }
+  ]
+]
+```
+
+</details>
+
+### Domains
+
+You can define and assign domains to your services.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `domain.id` | string | - | EventCatalog ID for the domain (e.g `orders-domain`). |
+| `domain.name` | string | - | Name of the domain (e.g `Orders Domain`). |
+| `domain.version` | string | - | Version of the domain (e.g `1.0.0`). |
+
+<details>
+<summary>See an example configuration - Assign a domain to a service</summary>
+
+In this example we assign a domain to a service.
+
+```js
+// ...rest of eventcatalog.config.js file
+generators: [
+  [
+    '@eventcatalog/generator-github',
+    { 
+      source: 'https://github.com/event-catalog/eventcatalog.git',
+      path: 'examples/default',
+      services: [
+        {
+          id: 'Orders Service',
+          version: '1.0.0',
+          sends: [
+            {
+              id: 'order-placed',
+              name: 'Order Placed',
+              version: '1',
+              schemaPath: 'domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro',
+              type: 'event',
+            }
+          ],
+          receives: [
+            {
+              id: 'place-order',
+              version: '1',
+              schemaPath: 'domains/Orders/services/InventoryService/commands/UpdateOrder/schema.avro',
+              type: 'command',
+            }
+          ]
+        }
+      ],
+      // The list of services are assigned to this domain
+      domain: {
+        id: 'orders-domain',
+        name: 'Orders Domain',
+        version: '1.0.0',
+      }
+    }
+  ]
+]
+```
+
+</details>
+
+
+## Need help?
+
+If you have questions or need help, you can join our [Discord community](https://eventcatalog.dev/discord)
+or refer to the [Github Plugin examples on GitHub](https://github.com/event-catalog/generators/tree/main/examples/generator-github).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/core/docs/plugins/github/03-features.md b/packages/core/docs/plugins/github/03-features.md
new file mode 100644
index 000000000..2d4265c20
--- /dev/null
+++ b/packages/core/docs/plugins/github/03-features.md
@@ -0,0 +1,42 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Features
+title: Features
+description: Features of the Github Plugin with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+### Adding semantic meaning to schemas
+
+Using the Github plugin with EventCatalog, you can import and keep your schemas in Sync with your documentation.
+
+When you import a schema into EventCatalog the schema will be mapped to your event, query or command. The schema (any format, e.g JSON, Avro, Protobuf) will be stored against the message in EventCatalog. 
+
+Each message (command, event, query) has their own `index.mdx` file. This is the place you can write your documentation for the message. Everytime you reimport your schemas, your documentation will be preserved.
+
+This pattern gives you the flexibility to add business meaning to your messages and make them easier to understand for teams whilst keeping your schemas up to date and in sync with the real world.
+
+### Visualize producers, consumers and your schemas.
+
+When you import your schemas into EventCatalog you can assign them to producers and consumers.
+
+After the import process, you can use the EventCatalog Visualizer ([see demo](https://demo.eventcatalog.dev/visualiser/domains/E-Commerce/1.0.0)) to see exactly how your messages, producers and consumers are mapped.
+
+![Example Image](./images/visualizer.png)
+
+### Downloading schemas
+
+EventCatalog supports any schema format (e.g avro, json, protobuf, etc). When you import your schemas into EventCatalog users can view and download the schema directly from EventCatalog.
+
+You can use the [Schema](/docs/development/components/components/schema) or [SchemaViewer](/docs/development/components/components/schema-viewer) components in your markdown to display them in your documentation.
+
+### Missing a feature?
+
+If you are missing a feature, please let us know by opening an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).
+
+### Example
+
+See the [eventcatalog-github-example](https://github.com/event-catalog/generators/tree/main/examples/generator-github) for a working example.
\ No newline at end of file
diff --git a/packages/core/docs/plugins/github/04-examples.md b/packages/core/docs/plugins/github/04-examples.md
new file mode 100644
index 000000000..5d0929c3a
--- /dev/null
+++ b/packages/core/docs/plugins/github/04-examples.md
@@ -0,0 +1,17 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the Github plugin
+---
+
+You can find many examples of using the Github plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [Basic example](https://github.com/event-catalog/generators/tree/main/examples/generator-github/basic)
+  - An example of using the Github plugin to pull schemas from GitHub and assign them to events, queries and commands.
+- [Import all schemas and assign them to producers and consumers](https://github.com/event-catalog/generators/tree/main/examples/generator-github/assign-schemas-to-producers-and-consumers) 
+  - An example of using the Github plugin to pull schemas from GitHub and assign them to producers and consumers (Services).
diff --git a/packages/core/docs/plugins/github/_category_.json b/packages/core/docs/plugins/github/_category_.json
new file mode 100644
index 000000000..4d5cfd6f7
--- /dev/null
+++ b/packages/core/docs/plugins/github/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "GitHub Plugin",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "github",
+    "title": "GitHub",
+    "description": "GitHub integration for EventCatalog"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/plugins/graphql/00-intro.md b/packages/core/docs/plugins/graphql/00-intro.md
new file mode 100644
index 000000000..12a5484d9
--- /dev/null
+++ b/packages/core/docs/plugins/graphql/00-intro.md
@@ -0,0 +1,74 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Introduction
+description: Getting started with GraphQL plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/J352QYLWQkw?si=hwwKr-k2IENfICmR" 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>
+
+---
+
+[GraphQL](https://graphql.org/) is a query language and runtime for APIs that provides a complete and understandable description of the data in your API. It gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
+
+Using the EventCatalog GraphQL generator you can generate and maintain your EventCatalog from your GraphQL schema files. 
+
+### Core Features
+
+The EventCatalog GraphQL plugin can provide you with many features:
+
+- ⭐️ Generate domains, services and messages into your catalog from your GraphQL schema files
+- ⭐️ [Map queries, mutations and subscriptions from your GraphQL schema](/docs/plugins/graphql/features#mapping-operations-as-queries-mutations-or-subscriptions)
+- ⭐️ [Assign owners (your teams) to your services and messages all generated by your GraphQL schemas](/docs/plugins/graphql/features#assign-owners-to-your-domains-services-and-messages)
+- ⭐️ [Add semantic meaning to your GraphQL schemas, persist this meaning between versions](/docs/plugins/graphql/features#persist-markdown)
+- ⭐️ [Automatically version your changes in EventCatalog in sync with your GraphQL schema versions](#automatic-versioning)
+- ⭐️ [Display your GraphQL schemas and operations in the catalog](#displaying-schemas)
+- ⭐️ Ability to download your schemas and GraphQL files (also versioned)
+- ⭐️ Ability to draft services and operations in EventCatalog from your GraphQL schemas
+- ⭐️ and more....
+
+### How it works
+
+![Example](/img/integrations/graphql/graphql.png)
+
+EventCatalog supports [generators](/docs/plugins/generators). These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an [SDK](/docs/sdk) to give developers easier access to their catalogs through custom scripts or generators.
+
+The EventCatalog GraphQL plugin let's you generate your catalog from one or more GraphQL schema files.
+
+Your GraphQL schemas are parsed and transformed into services, domains and messages in your catalog.
+
+This let's you visualize your architecture, assign owners to your services and much more.
+
+## Commercial and License
+
+This plugin requires an EventCatalog Scale license key to be used.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial, you can continue using this plugin with EventCatalog Scale.
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## License FAQ
+
+### What is the license key for?
+The EventCatalog Scale license key is required to use the GraphQL plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get an EventCatalog Scale license key?
+You can obtain an EventCatalog Scale license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 30-day free trial.
+
+### Terms
+- **Trial Period**: 30-day free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can continue with EventCatalog Scale through [EventCatalog Cloud](https://eventcatalog.cloud).
\ No newline at end of file
diff --git a/packages/core/docs/plugins/graphql/01-installation.md b/packages/core/docs/plugins/graphql/01-installation.md
new file mode 100644
index 000000000..14a94427a
--- /dev/null
+++ b/packages/core/docs/plugins/graphql/01-installation.md
@@ -0,0 +1,144 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog GraphQL
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog GraphQL plugin
+---
+
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PluginLicense url="#commercial-use" />
+
+The GraphQL plugin is used to generate EventCatalog resources (e.g domains, services and messages) from your GraphQL schema files.
+
+## Installation
+
+Run the command below to install the EventCatalog GraphQL plugin.
+
+<Tabs>
+  <TabItem value="apple" label="Install on existing catalog" default>
+    ```bash
+npm i @eventcatalog/generator-graphql
+```
+  </TabItem>
+</Tabs>
+
+:::tip "Don't have an EventCatalog project yet?"
+If you don't have an EventCatalog project yet, you can follow the instructions in the [Getting Started](/docs/development/getting-started/installation) guide.
+:::
+
+#### Configuration
+
+Configure the plugin in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators` array.
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  // Add single GraphQL schema to a domain
+  [
+    '@eventcatalog/generator-graphql',
+    {
+      services: [
+        // Point to a local GraphQL schema file, we assign it to the service "User Service", the service has a version of 1.0.0
+        { path: path.join(__dirname, 'graphql-schemas', 'user-service.graphql'), id: "User Service", version: "1.0.0"}
+      ],
+      // The services are assigned to the domain "Users"
+      domain: { id: 'users', name: 'Users', version: '0.0.1' },
+    },
+  ],
+  // Add many GraphQL schemas to a domain
+  [
+    '@eventcatalog/generator-graphql',
+    {
+      services: [
+        // Orders service
+        { path: path.join(__dirname, 'graphql-schemas', 'order-service.graphql'), id: "Order Service", version: "1.0.0"}
+        // Payment service
+        { path: path.join(__dirname, 'graphql-schemas', 'payment-service.graphql'), id: "Payment Service", version: "1.0.0"}
+      ],
+      // We add the orders and payment services to the domain "Shopping"
+      domain: { id: 'shopping', name: 'Shopping', version: '0.0.1' },
+    },
+  ],
+],
+};
+
+```
+
+### Configure license key
+
+The EventCatalog GraphQL plugin requires an EventCatalog Scale license key to work with EventCatalog.
+
+You can get a trial Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+You have a few options for setting the license key:
+
+1. [Setting license key in `.env` file (recommended)](#setting-license-key-in-env-file-recommended)
+2. [Setting license key in eventcatalog.config.js](#setting-license-key-in-eventcatalogconfigjs)
+
+#### 1. Setting license key in `.env` file (recommended) {#setting-license-key-in-env-file-recommended}
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+:::tip Using an Older API Key?
+
+If you already have an older GraphQL plugin key, you can still use it with the GraphQL-specific environment variable.
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_GRAPHQL=your-license-key
+```
+
+:::
+
+#### 2. Setting license key in eventcatalog.config.js {#setting-license-key-in-eventcatalogconfigjs}
+
+If you prefer, you can set the license key in the `eventcatalog.config.js` file
+using the `licenseKey` property in the EventCatalog GraphQL plugin.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-graphql',
+      {
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_SCALE_LICENSE_KEY
+      },
+    ],
+  ],
+};
+```
+
+#### White listing EventCatalog domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+#### Run the plugin
+
+_This command will run the generators in your eventcatalog.config.js file._
+
+```
+npm run generate
+```
+
+#### View your catalog
+
+Run your catalog locally to see the changes
+
+```
+npm run dev
+```
+
+## Any questions or need help?
+
+If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
diff --git a/packages/core/docs/plugins/graphql/02-plugin-configuration.md b/packages/core/docs/plugins/graphql/02-plugin-configuration.md
new file mode 100644
index 000000000..d5883524f
--- /dev/null
+++ b/packages/core/docs/plugins/graphql/02-plugin-configuration.md
@@ -0,0 +1,126 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog GraphQL plugin
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog GraphQL plugin
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Plugin Configuration
+
+## Overview
+
+The EventCatalog GraphQL plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+## Required Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `services` | `Service[]` | Yes | List of GraphQL schema files to add to your catalog, and the service name and version |
+| `licenseKey` | string | Yes* | EventCatalog Scale license key. Get a 30-day trial at [EventCatalog Cloud](https://eventcatalog.cloud). Can also be set via the `EVENTCATALOG_SCALE_LICENSE_KEY` environment variable. |
+
+### Service Configuration
+
+Each service in the `services` array requires the following properties:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | string | Yes | EventCatalog ID for the service. This is required and must be unique. |
+| `path` | string | Yes | Path to your GraphQL schema file |
+| `version` | string | Yes | Version of the service. _EventCatalog resources are versioned, you must specify a version for the service._|
+| `owners` | string[] | No | Owners of the service. You can assign EventCatalog users or teams to services. Setting owners on the service will also set the owners of the messages in the GraphQL schema. If owners are already set on any resource, those owners are persisted. |
+| `name` | string | No | Display name for the service. If not provided, the `id` will be used. |
+| `summary` | string | No | Short summary of the service. |
+| `generateMarkdown` | function | - | Function to override the default markdown generation for the service. See [Markdown templates](#markdown-templates) for more information. |
+| `writesTo` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service writes to. (Added in v0.4.4) |
+| `readsFrom` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service reads from. (Added in v0.4.0) |
+
+## Optional Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `domain` | object | - | Domain to associate all configured services with |
+| `domain.id` | string | - | Domain identifier |
+| `domain.name` | string | - | Domain display name |
+| `domain.version` | string | - | Domain version |
+| `domain.owners` | string[] | - | Owners of the domain. If owners are already set on the domain, those owners are persisted. |
+| `domain.markdown` | string | - | Custom markdown content for the domain. |
+| `messages.generateMarkdown` | function | - | Function to override the default markdown generation for the message. See [Markdown templates](#markdown-templates) for more information. |
+| `writeFilesToRoot` | boolean | `false` | Write GraphQL messages to root instead of service folder. By default all domains, services and messages will be grouped in the folder directory structure. |
+
+## Example Configuration
+
+```js title="eventcatalog.config.js"
+import path from "path";
+import url from "url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  cId: "10b46030-5736-4600-8254-421c3ed56e47",
+  title: "GraphQL API Catalog",
+  tagline: "Your GraphQL API Documentation",
+  organizationName: "Your Organization",
+  homepageLink: "https://eventcatalog.dev/",
+  editUrl: "https://github.com/your-org/your-catalog/edit/master",
+  trailingSlash: false,
+  base: "/",
+  logo: {
+    alt: "EventCatalog Logo",
+    src: "/logo.png",
+    text: "Your Organization",
+  },
+  docs: {
+    sidebar: {
+      showPageHeadings: true,
+    },
+  },
+  generators: [
+    [
+      '@eventcatalog/generator-graphql',
+      {
+        services: [
+          {
+            id: 'User Service',
+            version: '1.0.0',
+            name: 'User Service',
+            path: path.join(__dirname, 'graphql-schemas', 'user-service.graphql'),
+            owners: ['team-users']
+          },
+          {
+            id: 'Order Service',
+            version: '1.2.0',
+            name: 'Order Service',
+            path: path.join(__dirname, 'graphql-schemas', 'order-service.graphql'),
+            owners: ['team-orders']
+          },
+        ],
+        domain: { id: 'ecommerce', name: 'E-commerce', version: '0.0.1' },
+      },
+    ],
+    [
+      '@eventcatalog/generator-graphql',
+      {
+        services: [
+          {
+            id: 'Analytics Service',
+            version: '3.0.0',
+            name: 'Analytics Service',
+            path: path.join(__dirname, 'graphql-schemas', 'analytics-service.graphql'),
+            draft: true
+          },
+        ],
+        domain: { id: 'analytics', name: 'Analytics', version: '0.0.1' },
+        debug: true
+      },
+    ],
+  ],
+};
+```
+
+You can view an example configuration in the [EventCatalog GraphQL plugin GitHub repository](https://github.com/event-catalog/generators/blob/main/examples/generator-graphql/basic/eventcatalog.config.js).
diff --git a/packages/core/docs/plugins/graphql/03-features.md b/packages/core/docs/plugins/graphql/03-features.md
new file mode 100644
index 000000000..3c1f893a6
--- /dev/null
+++ b/packages/core/docs/plugins/graphql/03-features.md
@@ -0,0 +1,197 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Features
+title: Features
+description: Features of GraphQL with EventCatalog
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<!-- Table -->
+| Feature | Use cases |
+|---------|-----------|
+| [Mapping operations as queries, mutations, or subscriptions](#mapping-operations-as-queries-mutations-or-subscriptions) | GraphQL distinguishes between queries (read operations), mutations (write operations), and subscriptions (real-time operations). EventCatalog automatically maps these operations from your GraphQL schema to the appropriate message types in your catalog. |
+| [Assign owners to your domains, services and messages](#assign-owners-to-your-domains-services-and-messages) | You can assign owners (teams or individuals) to your GraphQL services and all the messages that are generated from your schema. This helps with accountability and contact information for your APIs. |
+| [Automatic versioning](#automatic-versioning) | When you change versions in your GraphQL schema and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between schema versions. |
+| [Creating draft domains, services and messages](#creating-draft-domains-services-and-messages) | You can create draft domains, services and messages in EventCatalog from your GraphQL schemas. This will be used to mark the resources as draft in EventCatalog. |
+| [Persist markdown](#persist-markdown) | When you generate your GraphQL schemas your markdown on your domains, services, and messages in EventCatalog is persisted between versions. This allows you to add [custom components](/docs/components/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when you version your schemas. |
+| [Displaying schemas](#displaying-schemas) | EventCatalog will document your GraphQL schemas and allow users to download them. Your schema files are versioned alongside your services and messages. |
+
+### Mapping operations as queries, mutations, or subscriptions
+
+GraphQL has three main operation types:
+
+- **Queries**: Read operations that fetch data
+- **Mutations**: Write operations that modify data
+- **Subscriptions**: Real-time operations that listen for data changes
+
+The EventCatalog GraphQL generator automatically maps these operations from your GraphQL schema:
+
+```graphql title="Example GraphQL Schema"
+type Query {
+  getUser(id: ID!): User
+  getAllUsers: [User]
+}
+
+type Mutation {
+  createUser(input: CreateUserInput!): User
+  updateUser(id: ID!, input: UpdateUserInput!): User
+  deleteUser(id: ID!): Boolean
+}
+
+type Subscription {
+  userUpdated(id: ID!): User
+  userDeleted: ID
+}
+
+type User {
+  id: ID!
+  name: String!
+  email: String!
+}
+```
+
+When this schema is processed by the GraphQL generator:
+
+- **Queries** like `getUser` and `getAllUsers` will be documented as [queries](/docs/development/guides/resources/messages/message-types/queries)
+- **Mutations** like `createUser`, `updateUser`, and `deleteUser` will be documented as [commands](/docs/development/guides/resources/messages/message-types/commands)
+- **Subscriptions** like `userUpdated` and `userDeleted` will be documented as [events](/docs/development/guides/resources/messages/message-types/events)
+
+Each operation becomes a message in EventCatalog with:
+- The operation name as the message ID
+- The operation description (if provided in schema)
+- Input parameters and return types
+- The operation type (query/mutation/subscription) as a badge
+
+### Assign owners to your domains, services and messages
+
+You can assign owners to your GraphQL services and all generated messages to help with accountability and contact information.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-graphql',
+      {
+        services: [
+          {
+            id: 'User Service',
+            version: '1.0.0',
+            name: 'User Service',
+            summary: 'This is the user service',
+            path: path.join(__dirname, 'graphql-schemas', 'user-service.graphql'),
+            owners: ['team-users', 'john.doe@company.com']
+          },
+        ],
+        domain: {
+          id: 'users',
+          name: 'Users',
+          version: '0.0.1',
+          owners: ['team-platform']
+        },
+      },
+    ],
+  ],
+};
+```
+
+When you assign owners:
+- **Service owners**: Set on the service configuration and apply to the service and all its messages
+- **Domain owners**: Set on the domain configuration and apply to the domain
+
+
+### Automatic versioning
+
+EventCatalog automatically versions your services and messages when you change the version in your configuration:
+
+```js title="eventcatalog.config.js - Version 1.0.0"
+{
+  path: path.join(__dirname, 'schemas', 'user-service.graphql'),
+  id: 'User Service',
+  version: '1.0.0'  // Initial version
+}
+```
+
+```js title="eventcatalog.config.js - Version 1.1.0"
+{
+  path: path.join(__dirname, 'schemas', 'user-service.graphql'),
+  id: 'User Service',
+  version: '1.1.0'  // Updated version
+}
+```
+
+When you update the version and run `npm run generate`:
+
+1. **Service versioning**: The service gets a new version (1.1.0) while keeping the old version (1.0.0)
+2. **Message versioning**: All messages (queries, mutations, subscriptions) get versioned
+3. **Schema versioning**: The GraphQL schema file is versioned and downloadable
+4. **Change tracking**: You can see what changed between versions
+
+This allows you to:
+- Track API evolution over time
+- Maintain backward compatibility documentation
+- Show deprecation timelines
+- Compare schema changes between versions
+
+### Creating draft domains, services and messages
+
+You can mark your GraphQL services as drafts during development:
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-graphql',
+      {
+        services: [
+          {
+            path: path.join(__dirname, 'schemas', 'new-feature-service.graphql'),
+            id: 'New Feature Service',
+            version: '0.1.0',
+            draft: true  // Mark as draft
+          },
+        ],
+        domain: { id: 'experimental', name: 'Experimental', version: '0.0.1' },
+      },
+    ],
+  ],
+};
+```
+
+Draft resources:
+- Are marked with a "DRAFT" badge in the UI
+- Can be filtered out from production views
+- Help distinguish between stable and experimental APIs
+- Useful for API development and review processes
+
+### Persist markdown
+
+EventCatalog preserves your custom markdown content when you regenerate from GraphQL schemas:
+
+1. **Initial generation**: GraphQL generator creates default markdown for your services and messages
+2. **Custom additions**: You add custom content, components, or documentation
+3. **Regeneration**: When you run the generator again, your custom content is preserved
+4. **Version updates**: Custom content persists across version changes
+
+This allows you to:
+- Add business context to technical schema definitions
+- Include examples and usage guidelines
+- Add custom MDX components for rich documentation
+- Provide architectural decision records (ADRs)
+- Include troubleshooting guides
+
+### Displaying schemas
+
+EventCatalog displays your GraphQL schemas and makes them downloadable:
+
+1. **Schema visualization**: Your complete GraphQL schema is rendered in the service page
+2. **Operation details**: Each query, mutation, and subscription shows:
+   - Input parameters and types
+   - Return types
+   - Field descriptions
+   - Deprecation notices
+3. **Downloadable schemas**: Users can download the complete GraphQL schema file
+4. **Versioned schemas**: Each version of your service includes its schema version
diff --git a/packages/core/docs/plugins/graphql/04-examples.md b/packages/core/docs/plugins/graphql/04-examples.md
new file mode 100644
index 000000000..c1952cfd7
--- /dev/null
+++ b/packages/core/docs/plugins/graphql/04-examples.md
@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the GraphQL plugin
+---
+
+You can find many examples of using the GraphQL plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [GraphQL Basic Example](https://github.com/event-catalog/generators/tree/main/examples/generator-graphql/basic)
+  -  A basic example of using the GraphQL plugin to generate a catalog from GraphQL schema files.
\ No newline at end of file
diff --git a/packages/core/docs/plugins/graphql/_category_.json b/packages/core/docs/plugins/graphql/_category_.json
new file mode 100644
index 000000000..8dd8b1090
--- /dev/null
+++ b/packages/core/docs/plugins/graphql/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "GraphQL Plugin",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "graphql",
+    "title": "GraphQL",
+    "description": "GraphQL integration documentation for EventCatalog"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/plugins/hookdeck/01-intro.md b/packages/core/docs/plugins/hookdeck/01-intro.md
new file mode 100644
index 000000000..cf79bd949
--- /dev/null
+++ b/packages/core/docs/plugins/hookdeck/01-intro.md
@@ -0,0 +1,152 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Getting started
+description: Getting started with Hookdeck plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+[Hookdeck](https://hookdeck.com?ref=eventcatalog-docs) is an event gateway that provides serverless infrastructure, features, tooling to enable the full software development lifecycle of event-driven applications.
+
+Using the EventCatalog Hookdeck plugin you can extract information from Hookdeck to gain further understanding of event sources, destinations, and flows within the Hookdeck platform.
+
+### Core Features
+
+The Hookdeck plugin can provide you with the following features:
+
+- ⭐️ [Generate EventCatalog Services](#generate-services) from Hookdeck Sources and Destinations
+- ⭐️ [Auto-generate EventCatalog Messages](#generate-messages) from Hookdeck Requests and Events
+- ⭐️ [Auto-generate EventCatalog Message Schemas](#generate-schemas) from Hookdeck Requests and Events
+- ⭐️ [Provide insight into Hookdeck Filters](#filtered-messages) by indicating Requests that are received by an EventCatalog Service but are not connected to destination Service.
+
+### How it works
+
+EventCatalog supports [generators](/docs/plugins/generators). These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an [SDK](/docs/sdk) to give developers easier access to their catalogs through custom scripts or generators.
+
+The EventCatalog Hookdeck plugin queries the [Hookdeck API](https://hookdeck.com/docs/api?ref=eventcatalog-docs) to generate an EventCatalog visualization including Services and Messages. It also generates inferred Message schemas.
+
+The plugin can either be used as a plugin within an EventCatalog instance or as a CLI configured to point to an EventCatalog instance.
+
+
+### Getting started
+
+#### 1. Install the plugin
+
+```sh
+npm i @hookdeck/eventcatalog-generator
+```
+
+#### 2. Configure your generator in your `eventcatalog.config.js` file
+
+```js title="eventcatalog.config.js"
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  title: 'OurLogix',
+  tagline: 'A comprehensive logistics and shipping management company',
+  organizationName: 'OurLogix',
+  homepageLink: 'https://eventcatalog.dev/',
+  landingPage: '',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  trailingSlash: false,
+  base: '/',
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'OurLogix',
+  },
+  docs: {
+    sidebar: {
+      showPageHeadings: true,
+    },
+  },
+  generators: [
+    [
+      "@hookdeck/eventcatalog-generator",
+      {
+        hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+        domain: "Payments",
+        connectionSourcedMatch: "payments-.*",
+        processMaxEvents: 200,
+        logLevel: "debug",
+      },
+    ],
+  ],
+};
+
+```
+
+#### 3. Run the generate command
+
+_This command will run the generators in your eventcatalog.config.js file._
+
+```sh
+npm run generate
+```
+
+#### 4. View your catalog
+
+Run your catalog locally to see the changes:
+
+```sh
+npm run dev
+```
+
+![Example](/img/integrations/hookdeck/example.png)
+
+## Hookdeck Concepts
+
+### Sources
+
+A Hookdeck [Source](https://hookdeck.com/docs/sources?ref=eventcatalog-docs) represents any service that makes an HTTP request to Hookdeck. The HTTP requests can be inbound events such as webhooks or asynchronous API calls.
+
+### Destinations
+
+A Hookdeck [Destination](https://hookdeck.com/docs/destinations?ref=eventcatalog-docs) represents the destination for an event to be routed to. A destination can be connected to one or many Sources.
+
+### Connections
+
+[Connections](https://hookdeck.com/docs/connection?ref=eventcatalog-docs) in Hookdeck route an event from a Source to a Destination. Connections can reuse sources and destinations, allowing one event to be routed to multiple destinations.
+
+### Event lifecycle
+
+The following represent different stages of the lifecycle of an event within Hookdeck:
+
+- [Requests](https://hookdeck.com/docs/requests?ref=eventcatalog-docs): An HTTP request received by a Source URL defined within Hookdeck, such as a webhook.
+- [Events](https://hookdeck.com/docs/events?ref=eventcatalog-docs): An outbound event payload that Hookdeck has queued for delivery.
+- [Attempts](https://hookdeck.com/docs/attempts?ref=eventcatalog-docs): An HTTP delivery attempt to the URL defined by a Destination.
+
+## Features
+
+### Generate EventCatalog Services {#generate-services}
+
+The Hookdeck plugin generates EventCatalog Services from Sources and Destinations that are used within defined Hookdeck Connections. The Sources and Destinations that have Services created can be filtered using the `connectionSourcedMatch` configuration option which performs a regular expression match on the connection source name.
+
+### Auto-generate EventCatalog Messages {#generate-message}
+
+EventCatalog Messages are generated for Requests received by a Source and Events received by a Destination. The number of Hookdeck Request and Events to have EventCatalog Messages generated can be set using the `processMaxEvents` configuration option.
+
+By default, the plugin search for a `type` or `eventType` property on the event payload to uniquely identify a Request or Event type. If the property cannot be found, each Request or Event is treated as a unique Message within EventCatalog.
+
+### Auto-generate EventCatalog Message Schemas {#generate-schemas}
+
+Hookdeck does not presently support schemas. Therefore, a Message schema can only be inferred from an event payload. The Hookdeck EventCatalog plugin generates inferred schemas for the first instance of an Event type and Request type it processes.
+
+### Provide insight into Hookdeck Filters {#filtered-messages}
+
+Hookdeck supports the ability to [filter events](https://hookdeck.com/docs/filters?ref=eventcatalog-docs) based on header or body contents. This can result in Sources receiving Requests but not Events being generated. EventCatalog's visual representation help you identify where events are being entirely filtered out and not delivered to any destination service.
+
+## Commercial Use
+
+This plugin is free to use for commercial use.
+
+## Source
+
+https://github.com/hookdeck/eventcatalog-generator
+
+## Issues
+
+If you have any problems or feature requests please raise them on GitHub: https://github.com/hookdeck/eventcatalog-generator/issues
+
diff --git a/packages/core/docs/plugins/hookdeck/02-api.md b/packages/core/docs/plugins/hookdeck/02-api.md
new file mode 100644
index 000000000..d81e74e4c
--- /dev/null
+++ b/packages/core/docs/plugins/hookdeck/02-api.md
@@ -0,0 +1,133 @@
+---
+sidebar_position: 2
+keywords:
+  - components
+sidebar_label: Generator configuration
+title: Hookdeck Generator API
+description: Getting started with Hookdeck plugin
+---
+
+## Overview {#overview}
+
+API for the EventCatalog Hookdeck generator.
+
+**Example eventcatalog.config.js file**
+
+```js title="eventcatalog.config.js"
+export default {
+  title: 'OurLogix',
+  tagline: 'A comprehensive logistics and shipping management company',
+  organizationName: 'OurLogix',
+  homepageLink: 'https://eventcatalog.dev/',
+  landingPage: '',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  trailingSlash: false,
+  base: '/',
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'OurLogix',
+  },
+  docs: {
+    sidebar: {
+      showPageHeadings: true,
+    },
+  },
+  generators: [
+    [
+      "@hookdeck/eventcatalog-generator",
+      {
+        hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+        domain: "Payments",
+        connectionSourcedMatch: "payments-.*",
+        processMaxEvents: 200,
+        logLevel: "debug",
+      },
+    ],
+  ],
+};
+
+```
+
+## Required fields {#required-fields}
+
+### `hookdeckApiKey` {#hookdeckApiKey}
+
+- Type: `String`
+
+Hookdeck Project API Key to generate an EventCatalog visualization from.
+
+```js title="eventcatalog.config.js"
+[
+  '@hookdeck/eventcatalog-generator',
+  {
+    hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+  },
+],
+```
+
+## Optional fields {#optional-fields}
+
+### `domain` {#domain}
+
+The domain you want the services be associated with in your catalog.
+
+- Type: `String`
+
+```js title="eventcatalog.config.js"
+[
+  '@hookdeck/eventcatalog-generator',
+  {
+    hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+    domain: "Payments",
+  },
+],
+```
+
+### `connectionSourcedMatch` {#connectionSourcedMatch}
+
+Regular expression match for Source names on Connections.
+
+- Type: `String`
+
+```js title="eventcatalog.config.js"
+[
+  '@hookdeck/eventcatalog-generator',
+  {
+    hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+    connectionSourcedMatch: "payments-.*",
+  },
+],
+```
+
+### `processMaxEvents` {#processMaxEvents}
+
+The maximum number of Requests/Events to process per Source/Destination
+
+- Type: `Integer`
+
+```js title="eventcatalog.config.js"
+[
+  '@hookdeck/eventcatalog-generator',
+  {
+    hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+    processMaxEvents: 200,
+  },
+],
+```
+
+### `logLevel` {#logLevel}
+
+The level to log at.
+
+- Type: `fatal` | `error` | `warn` | `info` | `debug` | `trace`
+
+```js title="eventcatalog.config.js"
+[
+  '@hookdeck/eventcatalog-generator',
+  {
+    hookdeckApiKey: process.env.HOOKDECK_API_KEY,
+    logLevel: "debug",
+  },
+],
+```
diff --git a/packages/core/docs/plugins/hookdeck/03-cli.md b/packages/core/docs/plugins/hookdeck/03-cli.md
new file mode 100644
index 000000000..c9006cd77
--- /dev/null
+++ b/packages/core/docs/plugins/hookdeck/03-cli.md
@@ -0,0 +1,45 @@
+---
+sidebar_position: 3
+keywords:
+  - components
+sidebar_label: Generator CLI
+title: Hookdeck Generator CLI
+description: Getting started with Hookdeck plugin as a CLI
+---
+
+## Overview {#overview}
+
+The Hookdeck EventCatalog plugin can be run as a CLI.
+
+## Run the generator as a CLI
+
+```sh
+npx @hookdeck/eventcatalog-generator {flags}
+```
+
+Supported flags are:
+
+- `dir`: **Required**. Path the the EventCatalog install directory
+- `api-key`: **Required**. Hookdeck Project API Key
+- `log-level`: The level to log at - "fatal" | "error" | "warn" | "info" | "debug" | "trace"
+- `match`: Regular expression match for Source names on Connections
+- `max-events`: The maximum number of Requests/Events to process per Source/Destination
+
+Example:
+
+```sh
+npx @hookdeck/eventcatalog-generator \
+    --dir ./path/to/eventcatalog/install \
+    --api-key {HOOKDECK_API_KEY} \
+    --log-level debug \
+    --match "stripe-production" \
+    --domain Payments \
+    --max-events 200
+```
+
+The CLI will also use the following environment variables:
+
+- `PROJECT_DIR`: Path the the EventCatalog install directory
+- `HOOKDECK_PROJECT_API_KEY`: Hookdeck Project API Key
+
+The environment variables can be within a `.env` file that will automatically be detected.
\ No newline at end of file
diff --git a/packages/core/docs/plugins/hookdeck/_category_.json b/packages/core/docs/plugins/hookdeck/_category_.json
new file mode 100644
index 000000000..aa5c5a706
--- /dev/null
+++ b/packages/core/docs/plugins/hookdeck/_category_.json
@@ -0,0 +1,11 @@
+{
+  "label": "Hookdeck Plugin",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "hookdeck",
+    "title": "Hookdeck",
+    "description": "Hookdeck integration with EventCatalog"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/plugins/openapi/00-intro.md b/packages/core/docs/plugins/openapi/00-intro.md
new file mode 100644
index 000000000..d5ea4a9d8
--- /dev/null
+++ b/packages/core/docs/plugins/openapi/00-intro.md
@@ -0,0 +1,78 @@
+---
+sidebar_position: 1
+keywords:
+  - components
+sidebar_label: Introduction
+title: Getting started
+description: Getting started with OpenAPI plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<AddedIn version="2.6.0"/>
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/E6cXxQXH49k?si=1IfHfIvrOLxIy3DF" 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 [OpenAPI specification](https://swagger.io/specification/) is a widely-adopted standard for defining and describing RESTful APIs in a structured, machine-readable format. It provides a way to document APIs, including the endpoints, parameters, request and response formats, authentication methods, and more, making it easier for both humans and machines to understand and interact with the API.
+
+Using the EventCatalog OpenAPI generator you can automate and generate your EventCatalog.
+
+:::tip Try it now
+Want to see what your OpenAPI file looks like in EventCatalog? [Try the playground](https://try.eventcatalog.dev) — drop your file and see the result in seconds.
+:::
+
+### Core Features
+
+The EventCatalog OpenAPI plugin can provide you with many features:
+
+- ⭐️ Generate domains, services and messages into your catalog from your OpenAPI specification files
+- ⭐️ [Assign owners (your teams) to your services and messages all generated by your OpenAPI files](/docs/plugins/openapi/features#assign-owners-to-your-domains-services-and-messages)
+- ⭐️ [Automate your EventCatalog and fetch OpenAPI files by URL](/docs/plugins/openapi/features#fetch-openapi-files-by-url)
+- ⭐️ [Map commands, queries and events from your OpenAPI file using custom extensions](/docs/plugins/openapi/features#mapping-messages-as-commands-queries-or-events)
+- ⭐️ [Add semantic meaning to your OpenAPI files, persist this meaning between versions](/docs/plugins/openapi/features#persist-markdown)
+- ⭐️ [Automatically version your changes in EventCatalog in sync with your OpenAPI versions](#automatic-versioning)
+- ⭐️ [Render and display your OpenAPI specification in EventCatalog](/docs/plugins/openapi/intro)
+- ⭐️ Display your endpoints and parameters in the catalog
+- ⭐️ Ability to download your schemas and OpenAPI files (also versioned)
+- ⭐️ Ability to draft services and endpoints in EventCatalog from your OpenAPI files
+- ⭐️ and more....
+
+### How it works
+
+![Example](/img/integrations/openapi/openapi.png)
+
+EventCatalog supports [generators](/docs/plugins/generators). These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an [SDK](/docs/sdk) to give developers easier access to their catalogs through custom scripts or generators.
+
+The EventCatalog OpenAPI plugin let's you define 1 or many OpenAPI files. When running the generate command the scripts populate your EventCatalog. You can choose how your OpenAPI services are added to EventCatalog and which domain they belong to.
+
+
+
+## Commercial and License
+
+This plugin requires an EventCatalog Scale license key to be used.
+
+You can get a 30-day trial Scale license key by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial, you can continue using this plugin with EventCatalog Scale. 
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## License FAQ
+
+### What is the license key for?
+The EventCatalog Scale license key is required to use the OpenAPI plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get an EventCatalog Scale license key?
+You can obtain an EventCatalog Scale license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 30-day free trial.
+
+### Terms
+- **Trial Period**: 30-day free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can continue with EventCatalog Scale through [EventCatalog Cloud](https://eventcatalog.cloud).
diff --git a/packages/core/docs/plugins/openapi/01-installation.md b/packages/core/docs/plugins/openapi/01-installation.md
new file mode 100644
index 000000000..754561117
--- /dev/null
+++ b/packages/core/docs/plugins/openapi/01-installation.md
@@ -0,0 +1,147 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog OpenAPI
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog OpenAPI plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PluginLicense url="#commercial-use" />
+
+The OpenAPI plugin is used to generate a catalog from an OpenAPI specification files.
+
+You can map your OpenAPI files to commands, events and queries in your catalog, and assign these to services and domains.
+
+## Installation
+
+Run the command below to install the EventCatalog OpenAPI plugin.
+
+<Tabs>
+  <TabItem value="apple" label="Install on existing catalog" default>
+    ```bash
+npm i @eventcatalog/generator-openapi
+```
+  </TabItem>
+  <TabItem value="orange" label="Create new catalog with OpenAPI plugin">
+     ```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --template openapi
+```
+  </TabItem>
+</Tabs>
+
+#### Configuration
+
+Configure the plugin in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators` array.
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [
+        { path: path.join(__dirname, 'openapi-files', 'orders-service.yml'), id: 'orders-service' },
+      ],
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+    },
+  ],
+  // Add many openapi files to a domain
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [
+        { path: path.join(__dirname, 'openapi-files', 'payment-service.yml'), id: 'payment-store' },
+        { path: path.join(__dirname, 'openapi-files', 'fraud-detection-service.yml'), id: 'fraud-detection-service' },
+      ],
+      domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
+    },
+  ],
+],
+};
+
+```
+
+### Configure license key
+
+The EventCatalog OpenAPI plugin requires an EventCatalog Scale license key to work with EventCatalog.
+
+You can get a trial Scale license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+You have a few options for setting the license key: 
+
+1. [Setting license key in `.env` file (recommended)](#setting-license-key-in-env-file-recommended)
+2. [Setting license key in eventcatalog.config.js](#setting-license-key-in-eventcatalogconfigjs)
+
+#### 1. Setting license key in `.env` file (recommended) {#setting-license-key-in-env-file-recommended}
+
+<AddedIn version="2.35.4" />
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+EVENTCATALOG_SCALE_LICENSE_KEY=your-scale-license-key
+```
+
+:::tip Using an Older API Key?
+
+If you already have an older OpenAPI plugin key, you can still use it with the OpenAPI-specific environment variable.
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_OPENAPI=your-license-key
+```
+
+:::
+
+
+### White listing domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+#### 2. Setting license key in eventcatalog.config.js {#setting-license-key-in-eventcatalogconfigjs}
+
+If you prefer, you can set the license key in the `eventcatalog.config.js` file
+using the `licenseKey` property in the EventCatalog OpenAPI plugin.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-openapi',
+      {
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_SCALE_LICENSE_KEY
+      },
+    ],
+  ],
+};
+```
+
+#### Run the plugin
+
+_This command will run the generators in your eventcatalog.config.js file._
+
+```
+npm run generate
+```
+
+#### View your catalog
+
+Run your catalog locally to see the changes
+
+```
+npm run dev
+```
+
+## Any questions or need help?
+
+If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
+
+
diff --git a/packages/core/docs/plugins/openapi/02-plugin-configuration.md b/packages/core/docs/plugins/openapi/02-plugin-configuration.md
new file mode 100644
index 000000000..296ab9fbc
--- /dev/null
+++ b/packages/core/docs/plugins/openapi/02-plugin-configuration.md
@@ -0,0 +1,333 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog OpenAPI
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the EventCatalog OpenAPI plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Plugin Configuration
+
+## Overview
+
+The EventCatalog OpenAPI plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+## Required Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `services` | `Service[]` | Yes | List of OpenAPI files to add to your catalog |
+| `licenseKey` | string | Yes* | EventCatalog Scale license key. Get a 30-day trial at [EventCatalog Cloud](https://eventcatalog.cloud). Can also be set via the `EVENTCATALOG_SCALE_LICENSE_KEY` environment variable. |
+
+
+### Service Configuration
+
+Each service in the `services` array requires the following properties:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | string | Yes | EventCatalog ID for the service. |
+| `path` | string or string[] | Yes | Path/s to your OpenAPI file or remote URL to the OpenAPI file. v6.0.0 introduced the ability to map multiple OpenAPI files to a single service. |
+| `version` | string | No | Version for the generated EventCatalog service and messages. If not provided, the version from the OpenAPI `info.version` field is used. |
+| `name` | string | No | Display name for the service. If not provided, the specification will be used. _Added in v7.4.3_|
+| `summary` | string | No | Short summary of the service. If not provided, the specification will be used. _Added in v7.4.3_|
+| `owners` | string[] | No | Owners of the service. You can assign EventCatalog users or teams to services. |
+| `setMessageOwnersToServiceOwners` | boolean | No | If true, the owners of the service will be set to the owners of the messages in the OpenAPI file (default is true). |
+| `generateMarkdown` | function | - | Function to override the default markdown generation for the service. See [Markdown templates](#markdown-templates) for more information. |
+| `draft` | boolean | No | If true, the service will be drafted in EventCatalog with all it's endpoints / messages. (Added in v7.3.0) |
+| `writesTo` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service writes to. (Added in v7.5.0) |
+| `readsFrom` | array[\{id: string, version?: string\}] | No | Array of [data stores](/docs/development/guides/resources/data/introduction) id and version (optional) that the service reads from. (Added in v7.5.0) |
+| `headers` | `Record<string, string>` | No | HTTP headers for authenticated remote URLs (e.g., `{ Authorization: 'Bearer token' }`). Used when fetching OpenAPI files from URLs that require authentication. |
+| `consumers` | `ConsumerService[]` | No | Services that consume messages generated from this OpenAPI spec. Each entry requires an `id`, and supports an optional `version` and `routes` filter. See [consumer services](/docs/plugins/openapi/features#define-consumer-services) for details. |
+
+## Optional Configuration Options
+
+
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `domain` | object | - | Domain to associate all configured services with |
+| `domain.id` | string | - | Domain identifier |
+| `domain.name` | string | - | Domain display name |
+| `domain.version` | string | - | Domain version |
+| `domain.draft` | boolean | No | If true, the domain will be drafted in EventCatalog with all it's services / messages. (Added in v7.3.0) |
+| `domain.generateMarkdown` | function | - | Function to override the default markdown generation for the domain. See [Markdown templates](#markdown-templates) for more information. |
+| `messages.generateMarkdown` | function | - | Function to override the default markdown generation for the message. See [Markdown templates](#markdown-templates) for more information. |
+| `messages.id` | object | - | Configure the id of the messages that are generated (for example, set a prefix to all messages that are generated) _(Added in v7.4.1)_ [(Read more)](/docs/plugins/openapi/features#adding-prefix-to-all-messages) |
+| `messages.id.prefix` | string | - | A prefix value for the message that is generated. For example a message with the operationId `getOrders` with a configured prefix of `hello-` will be `hello-getOrders`. _(Added in v7.4.1)_ [(Read more)](/docs/plugins/openapi/features#adding-prefix-to-all-messages) |
+| `messages.id.separator` | string | `-` | The separator to use between the prefix and the message id. _(Added in v7.4.1)_ [(Read more)](/docs/plugins/openapi/features#adding-prefix-to-all-messages) |
+| `messages.id.prefixWithServiceId` | boolean | - | If true, the service id will be added to the id of the messages that are generated. For example a message with the operationId `getOrders` and the service id `orders-service` will be `orders-service-getOrders`. _(Added in v7.4.1)_ [(Read more)](/docs/plugins/openapi/features#adding-prefix-to-all-messages) |
+| `writeFilesToRoot` | boolean | `false` | Write OpenAPI messages to root instead of service folder. By default all domains, services and messages 
+will be grouped in the folder directory structure. |
+| `saveParsedSpecFile` | boolean | `false` | Parse and save expanded OpenAPI spec (helpful for files with $refs) |
+| `sidebarBadgeType` | string | `HTTP_METHOD` | (Added in v5.0.1) Decides what badges are shown in the [documentation sidebar](/docs/development/customization/documentation-sidebar). `HTTP_METHOD` shows HTTP methods as badges, `MESSAGE_TYPE` shows `QUERY`, `COMMAND` or `EVENT` as badges. |
+| `httpMethodsToMessages` | object | - | (Added in v5.0.2) Gives you the ability to map HTTP methods (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, etc.) to message types (`command`, `query`, `event`). By default OpenAPI will map your requests to queries, you can use this property to change this behavior or use the `x-eventcatalog-message-type` extension to set the message type for each request. **If you use the `x-eventcatalog-message-type` extension in your spec file, this will be used.** |
+| `preserveExistingMessages` | boolean | true | (Added in v5.0.5) If true, the existing message markdown is preserved on new generation (default is true). Setting to false will always write the message markdown from the OpenAPI spec file. |
+| `parseExamples` | boolean | true | <AddedIn version="7.9.0" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/> When enabled, parses examples from OpenAPI operations (request body and response examples) and writes them to each message's `examples` folder as JSON files. Set to `false` to disable. |
+
+## Example Configuration
+
+```js title="eventcatalog.config.js"
+import path from "path";
+import url from "url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  cId: "10b46030-5736-4600-8254-421c3ed56e47",
+  title: "MetaRetail Inc",
+  tagline: "Fake Retail Company for EventCatalog Demo",
+  organizationName: "MetaRetail Inc",
+  homepageLink: "https://eventcatalog.dev/",
+  editUrl: "https://github.com/boyney123/eventcatalog-demo/edit/master",
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: "/",
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: "EventCatalog Logo",
+    src: "/logo.png",
+    text: "MetaRetail Inc",
+  },
+  docs: {
+    sidebar: {
+      // Should the sub heading be rendered in the docs sidebar?
+      showPageHeadings: true,
+    },
+  },
+  generators: [
+    // Add single OpenAPI file to a domain
+    [
+      '@eventcatalog/generator-openapi',
+      {
+        services: [
+          { 
+            path: path.join(__dirname, 'openapi-files', 'orders-service.yml'),
+            id: 'orders-service',
+            version: '1.0.0'
+          }
+        ],
+        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+        // Will render POST, GET, PUT, DELETE as badges in the sidebar
+        sidebarBadgeType: 'HTTP_METHOD',
+        // or set the license key via the environment variable as EVENTCATALOG_LICENSE_KEY_OPENAPI
+        licenseKey: 'YOUR_LICENSE_KEY'
+      },
+    ],
+    // Add multiple OpenAPI files to a domain
+    [
+      '@eventcatalog/generator-openapi',
+      {
+        services: [
+          { 
+            path: path.join(__dirname, 'openapi-files', 'payment-service.yml'),
+            id: 'payment-service'
+          },
+          { 
+            path: path.join(__dirname, 'openapi-files', 'fraud-detection-service.yml'),
+            id: 'fraud-detection-service'
+          }
+        ],
+        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
+        // Will render QUERY, COMMAND, EVENT as badges in the sidebar
+        sidebarBadgeType: 'MESSAGE_TYPE',
+        // Here we map the HTTP methods to the message types for EventCatalog (optional)
+        // e.g All post requests are mapped to commands, all get requests are mapped to queries
+        httpMethodsToMessages: {
+          GET: 'query',
+          POST: 'command',
+          PUT: 'command',
+          DELETE: 'command',
+        }
+        // or set the license key via the environment variable as EVENTCATALOG_LICENSE_KEY_OPENAPI
+        licenseKey: 'YOUR_LICENSE_KEY'
+      },
+    ],
+  ],
+};
+```
+
+You can view an example configuration in the [EventCatalog OpenAPI plugin GitHub repository](https://github.com/event-catalog/generators/blob/main/examples/generator-openapi/basic/eventcatalog.config.js).
+
+## Markdown templates
+
+<AddedIn version="7.2.1" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+The EventCatalog OpenAPI plugin will generate default markdown for each domain, service and message.
+
+If you want more control, you can override these using your own **markdown templates**.
+
+To use your own markdown templates you need to provide a function that returns the markdown for the domain, service or message.
+
+Below you can see examples of how to override the default markdown for the domain, service and message.
+
+<Tabs>
+  <TabItem value="Domain Markdown Template">
+
+  #### Domain
+
+  In this example we will override the default markdown for the domain using our custom function. We will also preserve the default markdown for the domain.
+
+```js title="eventcatalog.config.js"
+// function to generate the markdown for the domain
+// You can include this in your config file or in a separate file and import it
+const generateMarkdownForDomain = ({ domain, markdown }) => {
+  return `# ${domain.name}
+    This is the default markdown for the domain
+
+    You can add anything you want here, including components, tables, etc.
+
+    ## Architecture Diagram
+    <NodeGraph />
+
+    // Add the default markdown for the domain if you want to preserve it
+    ${markdown}
+  `;
+}
+
+// Your configuration
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-openapi',
+      {
+        // ...rest of generator config
+        domain: {
+          id: 'orders',
+          name: 'Orders',
+          version: '0.0.1',
+          generateMarkdown: generateMarkdownForDomain
+        }
+      }
+    ]
+  ]
+}
+```
+
+**Function Arguments:**
+
+| Argument | Type | Properties | Description |
+|----------|------|----------|-------------|
+| `domain` | object | `id`, `name`, `version` | The domain object you provided in the config |
+| `markdown` | string | - | The default markdown for the domain. Incase you want to preserve the default markdown you can use this argument to add to your own markdown. |
+
+
+  </TabItem>
+  <TabItem value="Service Markdown Template">
+
+  #### Service
+
+  In this example we will override the default markdown for the service using our custom function. We will also preserve the default markdown for the service.
+
+  ```js title="eventcatalog.config.js"
+  // function to generate the markdown for the service
+  // You can include this in your config file or in a separate file and import it
+  const generateMarkdownForService = ({ service, markdown, document }) => {
+    return `# ${service.name}
+      This is the default markdown for the service
+
+      ## Description
+      ${document.info.description ? `${document.info.description}` : ''}  
+    `;
+  }
+
+  // Your configuration
+  export default {
+    generators: [
+      [
+        '@eventcatalog/generator-openapi',
+        {
+          // ...rest of generator config
+          service: {
+            id: 'orders-service',
+            name: 'Orders Service',
+            version: '0.0.1',
+            generateMarkdown: generateMarkdownForService
+          }
+        }
+      ]
+    ]
+  }
+  ```
+
+  **Function Arguments:**
+
+  | Argument | Type | Properties | Description |
+  |----------|------|----------|-------------|
+  | `service` | object | `id`, `name`, `version` | The service object you provided in the config |
+  | `markdown` | string | - | The default markdown for the service. Incase you want to preserve the default markdown you can use this argument to add to your own markdown. |
+  | `document` | object | OpenAPI.Document | The OpenAPI document object. |
+
+
+  </TabItem>
+  <TabItem value="Message Markdown Template">
+
+  #### Message
+
+  In this example we will override the default markdown for the message using our custom function. We will also preserve the default markdown for the message.
+
+  ```js title="eventcatalog.config.js"
+  // function to generate the markdown for the message
+  // You can include this in your config file or in a separate file and import it
+  const generateMarkdownForMessage = ({ message, markdown, document }) => {
+    return `# ${message.name}
+      This is the default markdown for the message
+    `;
+  }
+
+  // Your configuration
+  export default {
+    generators: [
+      [
+        '@eventcatalog/generator-openapi',
+        {
+          // ...rest of generator config
+          messages: {
+            generateMarkdown: generateMarkdownForMessage
+          }
+        }
+      ]
+    ]
+  }
+  ```
+
+  **Function Arguments:**
+
+  | Argument | Type | Properties | Description |
+  |----------|------|----------|-------------|
+  | `operation` | object | OpenAPI.Operation | The operation object from the OpenAPI document. |
+  | `markdown` | string | - | The default markdown for the message. Incase you want to preserve the default markdown you can use this argument to add to your own markdown. |
+
+  </TabItem>
+</Tabs>
+
+
+
+
+
+
+## Need help?
+
+If you have questions or need help, you can join our [Discord community](https://eventcatalog.dev/discord)
+or refer to the [OpenAPI examples on GitHub](https://github.com/event-catalog/generators/tree/main/examples/generator-openapi).
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/core/docs/plugins/openapi/03-features.md b/packages/core/docs/plugins/openapi/03-features.md
new file mode 100644
index 000000000..2fa48229c
--- /dev/null
+++ b/packages/core/docs/plugins/openapi/03-features.md
@@ -0,0 +1,789 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Features
+title: Features
+description: Features of OpenAPI with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<!-- <AddedIn version="2.6.0"/> -->
+<PluginLicense url="#commercial-use" />
+
+<!-- Table -->
+| Feature | Use cases |
+|---------|-----------|
+| [Mapping messages as commands, queries or events](#mapping-messages-as-commands-queries-or-events) | OpenAPI does not have the concept of commands, queries or events, everything is a message (endpoint). Using the EventCatalog extension you can map your payloads as commands, queries or events. |
+| [Assign owners to your domains, services and messages](#assign-owners-to-your-domains-services-and-messages) | Set ownership of your service, and it's messages. Let your teams understand who owns what. |
+| [Creating draft domains, services and messages](#creating-draft-domains-services-and-messages) | Evolve your specifications. Mark endpoints as draft for your teams. This can help you highlight which endpoints are still in development or draft. |
+| [Map many OpenAPI files to a single service](#map-many-openapi-files-to-a-single-service) | If your service exposes multiple APIs, you can map many OpenAPI files to a single service. |
+| [Custom versioning with x-eventcatalog-message-version](#custom-versioning-with-x-eventcatalog-message-version) | By default this plugin will use the OpenAPI version for all your messages. You can use the `x-eventcatalog-message-version` extension to specify a different version for a particular message. |
+| [Fetch OpenAPI files by URL](#fetch-openapi-files-by-url) | You can use the `path` property of the generator to specify a path to your local file system or an external URL, or you can mix both of them. |
+| [Authenticate remote URLs](#authenticate-remote-urls) | Use HTTP headers to access protected OpenAPI files from authenticated URLs. |
+| [Define EventCatalog ids and names in your OpenAPI specification file](#define-eventcatalog-ids-and-names-in-your-openapi-specification-file) | EventCatalog messages (commands, queries and events) have two important properties, these are `id` and `name`. |
+| [Define messages a service sends or receives](#define-messages-a-service-sends-or-receives) | **By default all messages in your OpenAPI spec file are documented as messages that are received by your service** (e.g a route with /getOrders will be a query/command/event that the service accepts). You can override this by using the `x-eventcatalog-message-action` extension. |
+| [Deprecating messages](#deprecating-messages) | To mark messages as deprecated you can use the `deprecated` field or the `x-eventcatalog-deprecated-date` and `x-eventcatalog-deprecated-message` extensions. |
+| [Persist markdown](#persist-markdown) | When you generate your OpenAPI files your markdown on your domains,services, and messages in EventCatalog is persisted between versions. This allows you to add [custom components](/docs/components/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when you version your OpenAPI files. |
+| [Automatic versioning](#automatic-versioning) | When you change versions in your OpenAPI file and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between OpenAPI files, schemas and more. |
+| [Downloading schemas](#downloading-schemas) | If your messages have schemas EventCatalog will document these for you. Run your generator and every message will show it's schema on the UI and give users the ability to download it's schema. |
+| [Parse examples from operations](#parse-examples-from-operations) | Automatically extract request body and response examples from your OpenAPI operations and save them as JSON files alongside your messages in EventCatalog. |
+| [Define consumer services](#define-consumer-services) | Declare which services consume the messages generated from an OpenAPI spec, with optional route-based filtering to limit which messages each consumer sends to. |
+| [Group messages](#group-messages) | Group related messages together in the visualiser for easier navigation of large APIs. |
+
+### Define consumer services
+
+<AddedIn version="7.11." pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+EventCatalog will document who **owns** the service. You can also define consumers of your APIs. This can help you document which services are calling your endpoints to help with future maintenance of your APIs and develop a shared understanding.
+
+Add a `consumers` array to any service in your generator config to declare which other services send requests to that service. Each consumer entry needs at minimum an `id`; a `version` and `routes` filter are both optional.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [
+        {
+          path: path.join(__dirname, 'openapi-files', 'orders-service.yml'),
+          id: 'orders-service',
+          consumers: [
+            // Sends to all messages from the service
+            { id: 'audit-service' },
+            // Pinned to a specific version
+            { id: 'billing-service', version: '1.0.0' },
+            // Only messages whose path ends with /events
+            { id: 'notifications-service', routes: [{ suffix: '/events' }] },
+            // Only messages matching a wildcard pattern
+            { id: 'analytics', routes: [{ match: '/api/*/track' }] },
+          ],
+        },
+      ],
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+    },
+  ],
+],
+```
+
+#### Route filtering
+
+Route filters let you limit which messages a consumer sends to based on the API path of each operation. Omitting `routes` means the consumer sends to every message from the service.
+
+Each filter object supports four matching strategies:
+
+| Key | Behaviour | Example |
+|-----|-----------|---------|
+| `path` | Exact match | `{ path: '/orders/{id}' }` |
+| `prefix` | Path starts with the value | `{ prefix: '/orders' }` |
+| `suffix` | Path ends with the value | `{ suffix: '/events' }` |
+| `match` | Wildcard match (`*` spans one or more path segments) | `{ match: '/api/*/track' }` |
+
+All keys in a single filter object must match (AND). Multiple filter objects in the array are evaluated as OR, so a message is included if it satisfies any one of them.
+
+```js title="Filter examples"
+// Exact path only
+routes: [{ path: '/orders/{id}' }]
+
+// Paths under /orders OR paths ending with /events
+routes: [{ prefix: '/orders' }, { suffix: '/events' }]
+
+// Path must start with /api AND end with /events (AND within one object)
+routes: [{ prefix: '/api', suffix: '/events' }]
+
+// Wildcard: matches /api/orders/track, /api/payments/track, etc.
+routes: [{ match: '/api/*/track' }]
+```
+
+#### How consumers are created and updated
+
+When the generator runs, each consumer service is looked up by `id` and `version`. If a consumer service does not yet exist, it is created automatically with a basic `<NodeGraph />` page. New consumers are placed inside the configured `domain` if one is defined.
+
+If the consumer already exists in the catalog, it is updated in-place so its existing markdown, location, and metadata are preserved. The `sends` list on the consumer is merged with the incoming messages, with deduplication applied. If a consumer entry already tracks a versioned message, its version is updated to the latest value from the spec.
+
+---
+
+### Mapping messages as commands, queries or events
+
+OpenAPI does not distinguish between commands, events and queries, everything is a message. 
+
+Using the EventCatalog custom OpenAPI extension you can specify if your messages are queries, commands or events.
+
+You can use the `x-eventcatalog-message-type` to specify the type of message. 
+
+**By default everything parsed by EventCatalog is a query**, unless you specify with the x-eventcatalog-message-type extension.
+
+```yml title="x-eventcatalog-message-type example"
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+      x-eventcatalog-message-type: query # command,  query, or event
+      parameters:
+        - name: limit
+          in: query
+          description: How many items to return at one time (max 100)
+          required: false
+          schema:
+            type: integer
+            maximum: 100
+            format: int32
+```
+---
+
+### Assign owners to your domains, services and messages
+
+<AddedIn version="4.0.3" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+You can set owners to your domains and services. Setting owners to services will also set the owner to all messages in the service.
+
+To do this you can use the `owners` property in the service or domain.
+
+```js title="eventcatalog.config.js"
+// ..rest of file
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [
+        // here we assign owners to the service (owners documented in EventCatalog)
+        // The owners will also be set to all messages in the service
+        { path: path.join(__dirname, 'openapi-files', 'orders-service.yml'), id: 'orders-service', owners: ['dboyne', 'team-1'] },
+        // If you don't want to set owners to all messages you can use the setMessageOwnersToServiceOwners flag
+        { path: path.join(__dirname, 'openapi-files', 'orders-service.yml'), id: 'orders-service', owners: ['dboyne', 'team-1'], setMessageOwnersToServiceOwners: false },
+      ],
+      // You can also set owners to the domain, this does not cascade to the services or messages
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1', owners: ['dboyne', 'team-1'] },
+    },
+  ],
+],
+};
+
+```
+
+---
+
+### Creating draft domains, services and messages
+
+<AddedIn version="7.3.0" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+You can create draft domains, services and messages in EventCatalog from your OpenAPI files. 
+
+![Draft resources](../img/draft-resource.png)
+
+**Use case:**
+
+- You want to create a service in EventCatalog that is not yet implemented or going through feedback/design phase.
+- You want to introduce a new endpoint to your service, but warn users that it is not yet implemented or still in development or draft.
+- You want to introduce a whole new domain, but warn users everything in the domain is still in development or draft.
+
+**Getting started**
+
+You have a few options to create draft resources from your specification files.
+
+- `domain.draft` - If true, the domain will be drafted in EventCatalog with all it's services / messages.
+- `service.draft` - If true, the service will be drafted in EventCatalog with all it's endpoints / messages.
+
+You can also choose to use OpenAPI extensions to create draft resources.
+
+- `x-eventcatalog-draft` - If true, the resource will be drafted in EventCatalog (e.g service and messages).
+
+<details>
+  <summary>Example of creating draft resources through domains (configuration)</summary>
+
+Setting the `draft` property to true will create a draft domain with all it's services and messages in EventCatalog.
+
+```js title="eventcatalog.config.js"
+// ..rest of file
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1', draft: true },
+    },
+  ],
+],
+};
+```
+</details>
+<details>
+  <summary>Example of creating draft resources through services (configuration)</summary>
+
+Setting the `draft` property to true will create a draft service with all it's messages in EventCatalog.
+
+```js title="eventcatalog.config.js"
+// ..rest of file
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [
+        { path: path.join(__dirname, 'openapi-files', 'orders-service.yml'), id: 'orders-service', draft: true },
+      ],
+    },
+  ],
+],
+};
+```
+
+In this example the **Orders Service** and all it's messages will be marked as draft in EventCatalog.
+</details>
+<details>
+  <summary>Example marking service as draft (OpenAPI extension)</summary>
+
+Setting the `x-eventcatalog-draft` extension to true will mark the service as draft in EventCatalog.
+
+```yml title="x-eventcatalog-draft example"
+openapi: 3.0.0
+info:
+  title: Pet Service
+  version: 1.0.0
+  # Here we mark the service as draft
+  x-eventcatalog-draft: true
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+```
+
+In this example the **Pet Service** and the `/pets` endpoint will be marked as draft in EventCatalog.
+
+</details>
+<details>
+  <summary>Example marking a message as draft (OpenAPI extension)</summary>
+
+Setting the `x-eventcatalog-draft` extension to true will mark the message as draft in EventCatalog.
+
+```yml title="x-eventcatalog-draft example"
+openapi: 3.0.0
+info:
+  title: Pet Service
+  version: 1.0.0
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      x-eventcatalog-draft: true # This will mark the message as draft
+      tags:
+        - pets
+```
+
+In this example we mark the message `listPets` as draft but the service is not marked as draft in EventCatalog.
+
+This can be useful if you want to introduce a new endpoint, but warn users that it is not yet implemented or still in development or draft.
+
+</details>
+
+
+---
+
+### Map many OpenAPI files to a single service
+
+<AddedIn version="6.0.0" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+If your service exposes multiple APIs, you can map many OpenAPI files to a single service.
+
+```js title="eventcatalog.config.js"
+// ..rest of file
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [
+        // Here we map two OpenAPI files to a single service
+        { 
+          path: [
+            path.join(__dirname, 'openapi-files', 'orders-service-v1.yml'),
+            path.join(__dirname, 'openapi-files', 'orders-service-v2.yml')
+          ], 
+          id: 'orders-service', owners: ['dboyne', 'team-1'] 
+        },
+      ],
+      // You can also set owners to the domain, this does not cascade to the services or messages
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1', owners: ['dboyne', 'team-1'] },
+    },
+  ],
+],
+};
+
+```
+
+---
+
+#### How does mapping multiple OpenAPI files to a single service work?
+
+The OpenAPI plugin will parse all the files in the `path` array. The are ordered by version (info.version).
+
+Old versions are parsed first and versioned in your catalog along side the messages.
+
+The latest version is parsed last and will be used as the current version in your catalog.
+
+You can try this demo out for yourself by running the [mapping-many-openapi-files-to-a-service example](https://github.com/event-catalog/generators/tree/main/examples/generator-openapi/mapping-many-openapi-files-to-a-service).
+
+---
+
+### Custom versioning with x-eventcatalog-message-version
+
+<AddedIn version="3.3.2" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+By default this plugin will use the OpenAPI version for all your messages. 
+
+You can use the `x-eventcatalog-message-version` extension to specify a different version for a particular message.
+
+```yml title="x-eventcatalog-message-version example"
+openapi: '3.0.0'
+info:
+  title: Test Service
+  version: 1.0.0
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+      x-eventcatalog-message-version: 5.0.0
+```
+
+In the example above, the message `listPets` will be versioned as `5.0.0` and all other messages will be versioned as `1.0.0`.
+
+This feature lets you control the version of your messages individually.
+
+### Fetch OpenAPI files by URL
+
+<AddedIn version="3.1.0" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+You can use the `path` property of the generator to specify a path to your local file system or an external URL, or you can mix both of them.
+
+```js
+[
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        // Add OpenAPI file by public URL
+        { path: "https://raw.githubusercontent.com/event-catalog/generator-openapi/refs/heads/main/examples/product-api/openapi.yml", id: "Product Service"},
+        // Add OpenAPI file using file system
+        { path: path.join(__dirname, 'openapi-files', 'fraud-detection-service.yml'), "Fraud Service"}
+      ],
+      domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
+
+      // Parse the YML before we save it to the catalog (optional) (http://localhost:3000/docs/development/plugins/open-api/api#saveParsedSpecFile)
+      saveParsedSpecFile: true,
+
+      // Run in debug mode, for extra output, if your AsyncAPI fails to parse, it will tell you why
+      debug: true,
+    },
+  ],
+```
+
+:::info URLS for OpenAPI files
+
+The path can be the file path to your local file system or an external URL. The external URL has to be accessible from the machine running the generator.
+:::
+
+### Authenticate remote URLs
+
+When fetching OpenAPI files from authenticated URLs, provide HTTP headers using the `headers` property.
+
+This is useful for accessing private specifications from internal registries, API gateways, or other protected endpoints.
+
+```js
+[
+  '@eventcatalog/generator-openapi',
+  {
+    services: [
+      {
+        path: "https://api.example.com/specs/orders-service.openapi.yml",
+        id: "orders-service",
+        headers: {
+          Authorization: 'Bearer your-api-token',
+          'X-Api-Key': 'your-api-key'
+        }
+      }
+    ],
+    domain: { id: 'orders', name: 'Orders', version: '0.0.1' }
+  }
+]
+```
+
+The headers are passed with every HTTP request when fetching the OpenAPI file from the specified URL.
+
+### Define EventCatalog ids and names in your OpenAPI specification file
+
+<AddedIn version="3.0.0" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+EventCatalog messages (commands, queries and events) have two important properties, these are `id` and `name`.
+
+- id - The id of your message (used for url slugs)
+- name - Friendly name for your message in EventCatalog (used in the UI)
+
+The OpenAPI generator will set a default value for the `name` and `id` using the operationId or the service name.
+
+If you want more control, you can use the `x-eventcatalog-message-name` and `x-eventcatalog-message-id` extensions to specify the `id` and `name` value.
+
+```yml title="x-eventcatalog-message-type example"
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+      x-eventcatalog-message-type: query # command,  query, or event
+      x-eventcatalog-message-id: list-pets # Used as EventCatalog ID (slug) and reference to the resource
+      x-eventcatalog-message-name: List pets # Used by EventCatalog as friendly name for the message
+      parameters:
+        - name: limit
+          in: query
+          description: How many items to return at one time (max 100)
+          required: false
+          schema:
+            type: integer
+            maximum: 100
+            format: int32
+```
+
+### Define messages a service sends or receives
+
+<AddedIn version="2.3.0" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+**By default all messages in your OpenAPI spec file are documented as messages that are received by your service** (e.g a route with /getOrders will be a query/command/event that the service accepts).
+
+If you want to specify the relationship of your messages and services (sends or receives) you can do this using the custom extension `x-eventcatalog-message-action`. Which you can define in your OpenAPI files.
+
+```yml title="x-eventcatalog-message-action example"
+paths:
+  /pets/{petId}/vaccinated:
+      post:
+        summary: Notify that a pet has been vaccinated
+        operationId: petVaccinated
+        tags:
+          - pets
+        # This tells eventcatalog that this message is sent from this service.  
+        x-eventcatalog-message-action: sends 
+        requestBody:
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Vaccination'
+          required: true
+        responses:
+          '200':
+            description: Notification that the pet has been vaccinated successfully
+          default:
+            description: unexpected error
+            content:
+              application/json:
+                schema:
+                  $ref: '#/components/schemas/Error'
+```
+
+In the example above, when the generator runs, it will put the message `petVaccinated` as a message the petstore service sends.
+
+### Adding prefix to all messages
+
+<AddedIn version="7.4.1" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+If you want more control over the ids of the generated messages you can
+
+1. [Define ids nad names using the `x-eventcatalog-message-id` and `x-eventcatalog-message-name` extensions](#define-eventcatalog-ids-and-names-in-your-openapi-specification-file).
+2. Add a prefix to the id of the generated messages (see below)
+
+<Tabs>
+  <TabItem value="prefix (with a string)">
+
+This will add a prefix to the id of the generated messages. For example a message with the operationId `getOrders` with a configured prefix of `hello-` will be `hello-getOrders`.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+      {
+        messages: { id: { prefix: 'hello' } },
+      },
+  ],
+],
+```
+</TabItem>
+  <TabItem value="prefix (with custom separator)">
+
+This will add a prefix to the id of the generated messages. For example a message with the operationId `getOrders` with a configured prefix of `hello-` and separator of `_` will be `hello_getOrders`.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+      { 
+        messages: { id: { prefix: 'hello', separator: '_' } },
+      },
+  ],
+],
+```
+</TabItem>
+  <TabItem value="prefix (with service id)">
+
+This will add the service id to the id of the generated messages. For example a message with the operationId `getOrders` and the service id `orders-service` will be `orders-service-getOrders`.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+      { 
+        messages: { id: { prefixWithServiceId: true } },
+      },
+  ],
+],
+```
+</TabItem>
+</Tabs>
+
+
+### Deprecating messages
+
+<AddedIn version="5.0.4" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+To mark messages as deprecated you can use the `deprecated` field or the `x-eventcatalog-deprecated-date` and `x-eventcatalog-deprecated-message` extensions.
+
+**Deprecated as a boolean**
+
+[OpenAPI natively supports deprecating](https://swagger.io/specification/) messages using the `deprecated` field.
+
+```yml title="Deprecated as a boolean"
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      deprecated: true
+```
+
+When this deprecated field is set to `true`, the message will be rendered in EventCatalog with a banner indicating that the message is deprecated.
+
+![Deprecated message](../../development/guides/img/deprecated/is-deprecated.png)
+
+**Deprecated as an object**
+
+If you want more fine grained control over the deprecation date and message, you can use the `x-eventcatalog-deprecated-date` and `x-eventcatalog-deprecated-message` extensions.
+
+```yml title="Deprecated as an object"
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      x-eventcatalog-deprecated-date: 2026-05-01
+      x-eventcatalog-deprecated-message: |
+        This message is **being deprecated** and replaced by the new service **InventoryService**.
+        Please contact the [team for more information](mailto:inventory-team@example.com) or visit our [website](https://eventcatalog.dev).
+```
+This will render a banner in EventCatalog indicating that the message will be deprecated on 2026-05-01.
+
+![Deprecated message](../../development/guides/img/deprecated/will-be-deprecated.png)
+
+### Persist markdown
+
+When you generate your OpenAPI files your markdown on your domains,services, and messages in EventCatalog is persisted between versions.
+
+This allows you to add [custom components](/docs/components/custom-components), our [MDX components](/docs/components) and customize your EventCatalog pages without losing changes when you version your OpenAPI files.
+
+### Automatic versioning
+
+When you change versions in your OpenAPI file and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between OpenAPI files, schemas and more.
+
+You can also add changelogs between different versions of your services and messages. [Read here for more information](/docs/development/guides/resources/messages/versioning-and-lifecycle/add-changelog).
+
+### Downloading schemas
+
+If your messages have schemas EventCatalog will document these for you. Run your generator and every message will show it's schema on the UI and give users the ability to download it's schema.
+
+The service that is also generated will allow you to see and download the OpenAPI file.
+
+### Group messages
+
+<AddedIn version="7.12.0" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+When a service sends or receives many messages, the [visualiser](/docs/development/guides/resources/messages/connect-messages/group-messages) can become crowded. The `groupMessagesBy` option lets you automatically group related messages together so they collapse into a single node in the visualiser map, making your architecture easier to understand at a glance.
+
+![Message group expanded in the visualiser](./img/message-group-expanded.png)
+
+To learn more about how groups work in the visualiser, see [Grouping messages](/docs/development/guides/resources/messages/connect-messages/group-messages).
+
+Three strategies are supported:
+
+| Strategy | How the group is determined |
+|----------|----------------------------|
+| `x-extension` | Reads the `x-eventcatalog-group` field on each OpenAPI operation |
+| `path-prefix` | Derives the group from the first meaningful URL path segment, skipping common prefixes like `api`, `v1`, `v2` |
+| `single-group` | Places every operation into a single group called `operations` |
+
+#### Use the x-extension strategy
+
+Set `groupMessagesBy: 'x-extension'` and add `x-eventcatalog-group` to each operation you want to group.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [{ path: './openapi.yml', id: 'my-service' }],
+      groupMessagesBy: 'x-extension',
+    },
+  ],
+],
+```
+
+```yaml title="openapi.yml"
+paths:
+  /pets/{petId}/adopt:
+    post:
+      x-eventcatalog-group: Adoptions
+      summary: Adopt a pet
+      operationId: adoptPet
+```
+
+#### Use the path-prefix strategy
+
+Set `groupMessagesBy: 'path-prefix'` and the generator derives the group name automatically from the URL. No changes to your OpenAPI file are needed.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [{ path: './openapi.yml', id: 'my-service' }],
+      groupMessagesBy: 'path-prefix',
+    },
+  ],
+],
+```
+
+The generator reads the first meaningful path segment and capitalizes it as the group name. Common technical prefixes are skipped automatically.
+
+| Path | Group |
+|------|-------|
+| `/pets/{petId}` | `Pets` |
+| `/api/v1/billing/invoices` | `Billing` |
+| `/health` | _(no group, single segment)_ |
+| `/pets` | _(no group, single segment)_ |
+
+#### Use the single-group strategy
+
+Set `groupMessagesBy: 'single-group'` to place every operation into one group called `operations`, regardless of its path or any extensions. No changes to your OpenAPI file are needed.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [{ path: './openapi.yml', id: 'my-service' }],
+      groupMessagesBy: 'single-group',
+    },
+  ],
+],
+```
+
+This is useful for very large APIs where `path-prefix` still leaves too many ungrouped nodes. Every message collapses into a single `operations` node in the visualiser.
+
+:::tip
+Once grouped, messages appear as a compact stacked card in the visualiser. Click the group to expand it and see the full downstream graph — channels, consumers, and producers — just as if the messages were ungrouped. See [Grouping messages](/docs/development/guides/resources/messages/connect-messages/group-messages) for more details.
+:::
+
+---
+
+### Parse examples from operations
+
+<AddedIn version="7.9.0" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+When `parseExamples` is enabled (the default), the generator reads examples defined on your OpenAPI operations and writes them as JSON files into each message's `examples` folder in EventCatalog.
+
+Both request body examples and response examples are supported, across the single `example` and named `examples` formats from the OpenAPI specification.
+
+**How examples are named**
+
+| Source | File name |
+|--------|-----------|
+| Single request body `example` | `example.json` |
+| Named request body `examples` (e.g. `dog`) | `dog.json` |
+| Single response `example` (e.g. status `200`) | `response-200.json` |
+| Named response `examples` (e.g. status `200`, name `dog`) | `response-200-dog.json` |
+
+**OpenAPI example formats**
+
+```yml title="Single request body example"
+paths:
+  /pets:
+    post:
+      operationId: createPet
+      requestBody:
+        content:
+          application/json:
+            example:
+              name: Fido
+              tag: dog
+```
+
+```yml title="Named request body examples"
+paths:
+  /pets:
+    post:
+      operationId: createPet
+      requestBody:
+        content:
+          application/json:
+            examples:
+              dog:
+                value:
+                  name: Fido
+                  tag: dog
+              cat:
+                value:
+                  name: Whiskers
+                  tag: cat
+```
+
+```yml title="Named response examples"
+paths:
+  /pets:
+    post:
+      operationId: createPet
+      responses:
+        '200':
+          content:
+            application/json:
+              examples:
+                dog:
+                  value:
+                    id: 1
+                    name: Fido
+                cat:
+                  value:
+                    id: 2
+                    name: Whiskers
+```
+
+To disable example parsing, set `parseExamples: false` in your generator configuration.
+
+```js title="eventcatalog.config.js"
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [
+        { path: path.join(__dirname, 'openapi-files', 'orders-service.yml'), id: 'orders-service' }
+      ],
+      parseExamples: false,
+    },
+  ],
+],
+```
diff --git a/packages/core/docs/plugins/openapi/03a-workflows.md b/packages/core/docs/plugins/openapi/03a-workflows.md
new file mode 100644
index 000000000..9f3b64652
--- /dev/null
+++ b/packages/core/docs/plugins/openapi/03a-workflows.md
@@ -0,0 +1,153 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Workflows  
+title: Workflows
+description: Workflows of OpenAPI with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+There are a few ways to configure the OpenAPI plugin depending on your preferred development workflows.
+Many companies have different needs, so we have provided a few different workflows to choose from.
+
+- [Simple mapping between OpenAPI files and EventCatalog services](#simple-mapping-between-openapi-files-and-eventcatalog-services)
+  - Map a single OpenAPI file to a single EventCatalog service
+- [Independent message versions from your OpenAPI file](#independent-message-versions-from-your-openapi-file)
+  - Version your messages independently of the service version
+- [Mapping multiple OpenAPI files to a single EventCatalog service](#mapping-multiple-openapi-files-to-a-single-eventcatalog-service)
+  - Map multiple OpenAPI files to a single EventCatalog service
+- [Mapping OpenAPI and AsyncAPI files to the same EventCatalog service](#mapping-openapi-and-asyncapi-files-to-the-same-eventcatalog-service)
+  - Map an OpenAPI and AsyncAPI file to the same EventCatalog service
+
+_If we are missing a workflow that you think is useful, please raise an [issue on GitHub](https://github.com/event-catalog/generators/issues)._  
+
+## Simple mapping between OpenAPI files and EventCatalog services
+
+This is the simplest workflow and is useful if you have a single OpenAPI file per service.
+
+EventCatalog will parse your OpenAPI file and map it's specification to the service you define. 
+
+This will document your service, and the messages it produces and consumes.
+
+```js title="eventcatalog.config.js"
+// ...rest of file
+generators: [
+  [
+    '@eventcatalog/generator-openapi',
+    {
+      services: [
+        // Tell EventCatalog where the OpenAPI file is located and map it to the service you define
+        { path: path.join(__dirname, 'openapi-files', 'orders-service.yml'), id: 'orders-service' },
+      ],
+    },
+  ],
+],
+```
+
+### Independent message versions from your OpenAPI file
+
+This is useful if you want to version your messages separately from the OpenAPI file.
+
+OpenAPI currently does not support versioning messages separately from the OpenAPI file, that's why you have to use the `x-eventcatalog-message-version` extension.
+
+You can use the `x-eventcatalog-message-version` extension to specify a different version for a particular message.
+
+```yaml
+openapi: 3.0.0
+info:
+  title: Orders Service
+  version: 1.0.0
+paths:
+  /orders:
+    get:
+      summary: List all orders
+      operationId: listOrders
+      # Specify the version of the message to 2.0.0
+      x-eventcatalog-message-version: 2.0.0
+      tags:
+        - orders
+      responses:
+        '200':
+          description: A list of orders
+          content:
+            application/json:
+```
+
+In the example above, the message `listOrders` will be versioned as `2.0.0` and all other messages will be versioned as `1.0.0`.
+
+You can read more about message versioning in the [Features](/docs/plugins/openapi/features#defining-message-versions) section.
+
+## Mapping multiple OpenAPI files to a single EventCatalog service
+
+This is useful if you have a single service that produces and consumes multiple OpenAPI versions.
+
+Some people call this a "polyglot" service, as it produces and consumes multiple APIs.
+
+```js title="eventcatalog.config.js"
+// ...rest of file
+generators: [
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        // Version 1 of the OpenAPI file
+        { path: path.join(__dirname, 'openapi-files', 'orders-service-v1.yml'), id: 'orders-service' },
+        // Version 2 of the AsyncAPI File
+        { path: path.join(__dirname, 'openapi-files', 'orders-service-v2.yml'), id: 'orders-service' },
+      ],
+    },
+  ],
+],
+```
+
+:::info Versioning
+When you map multiple versions of an OpenAPI file to a single service, the `version` property in your OpenAPI files needs to be the same.
+
+If they are different, EventCatalog will version the previous versions of your service.
+
+In the example above, the `version` property in the OpenAPI files is `1.0.0` and `2.0.0`.
+
+EventCatalog will version the service as `1.0.0` and `2.0.0`.
+
+The messages in the service will be versioned as `1.0.0` and `2.0.0`.
+
+This allows you to track the history of your service and the messages in it.
+
+:::
+
+## Mapping OpenAPI and AsyncAPI files to the same EventCatalog service
+
+<AddedIn version="5.1.1" pkg="@eventcatalog/generator-asyncapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+<AddedIn version="7.6.1" pkg="@eventcatalog/generator-openapi" url="https://github.com/event-catalog/generators/releases/tag/v"/>
+
+This is useful if you have a single service that produces and consumes both OpenAPI and AsyncAPI files.
+
+In this example we map an OpenAPI file and an AsyncAPI file to the same service (inventory-service). 
+
+The OpenAPI and AsyncAPI may have their own versions independent of each other, but EventCatalog will document both of them in the same service.
+
+:::tip Message Versioning
+You can still use the `x-eventcatalog-message-version` extension to version your messages independently of the service version.
+:::
+
+```js title="eventcatalog.config.js"
+// ...rest of file
+generators: [
+    [
+      "@eventcatalog/generator-openapi",
+      {
+        services: [{ path: path.join(__dirname, "specifications", "openapi.yml"), id: "inventory-service", version: "15.2.0" }],
+      },
+    ],
+    [
+      "@eventcatalog/generator-asyncapi",
+      {
+        services: [{ path: path.join(__dirname, "specifications", "asyncapi.yml"), id: "inventory-service", version: "15.2.0" }],
+      },
+    ],
+  ],
+```
\ No newline at end of file
diff --git a/packages/core/docs/plugins/openapi/04-examples.md b/packages/core/docs/plugins/openapi/04-examples.md
new file mode 100644
index 000000000..0333be379
--- /dev/null
+++ b/packages/core/docs/plugins/openapi/04-examples.md
@@ -0,0 +1,23 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the OpenAPI plugin
+---
+
+You can find many examples of using the OpenAPI plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [OpenAPI Example](https://github.com/event-catalog/generators/tree/main/examples/generator-openapi/basic)
+  -  A basic example of using the OpenAPI plugin to generate a catalog from an OpenAPI file.
+- [Fetch OpenAPI files from remote URLs](https://github.com/event-catalog/generators/tree/main/examples/generator-openapi/fetch-from-remote-urls) 
+  - An example of using the OpenAPI plugin to fetch an OpenAPI file from a remote URL.
+- [Version OpenAPI messages in EventCatalog](https://github.com/event-catalog/generators/tree/main/examples/generator-openapi/independent-message-versioning) 
+  - An example of using the OpenAPI plugin to version OpenAPI messages in EventCatalog.
+- [Map OpenAPI routes to commands, events and queries](https://github.com/event-catalog/generators/tree/main/examples/generator-openapi/mapping-commands-events-queries) 
+  - An example of using the OpenAPI plugin to map OpenAPI routes to commands, events and queries.
+- [Map many OpenAPI files to a single service](https://github.com/event-catalog/generators/tree/main/examples/generator-openapi/mapping-many-openapi-files-to-a-service) 
+  - An example of using the OpenAPI plugin to map many OpenAPI files to a single service. This can be useful if your service exposes multiple APIs.
\ No newline at end of file
diff --git a/packages/core/docs/plugins/openapi/_category_.json b/packages/core/docs/plugins/openapi/_category_.json
new file mode 100644
index 000000000..1b5ebff86
--- /dev/null
+++ b/packages/core/docs/plugins/openapi/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "OpenAPI Plugin",
+  "collapsible": true,
+  "position": 3,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "openapi",
+    "title": "OpenAPI",
+    "description": "OpenAPI integration documentation for EventCatalog"
+  }
+}
\ No newline at end of file
diff --git a/packages/core/docs/tutorial/01-start-here.md b/packages/core/docs/tutorial/01-start-here.md
new file mode 100644
index 000000000..f52572746
--- /dev/null
+++ b/packages/core/docs/tutorial/01-start-here.md
@@ -0,0 +1,75 @@
+---
+sidebar_position: 1
+slug: /tutorial
+sidebar_label: Introduction
+title: Introduction
+description: Learn what you will build in the EventCatalog tutorial.
+---
+
+In this tutorial, you will build your first EventCatalog from a small commerce architecture.
+
+The goal is to get you from a blank project to a working catalog you can open in the browser and understand how EventCatalog works.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/tutorial-introduction.png"
+    alt="The tutorial catalog overview page in EventCatalog"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    The catalog you will build during this tutorial.
+  </figcaption>
+</figure>
+
+## What we are building
+
+We are going to document a small order flow for an e-commerce system.
+
+The system is simple on purpose. A customer places an order, one service publishes an event, another service consumes it, and the catalog explains how those pieces connect.
+
+You will build the first version of that catalog by adding:
+
+| Resource | Tutorial example |
+| --- | --- |
+| Domain | E-Commerce |
+| Service | OrderService |
+| Event | OrderPlaced |
+| Consumer | InventoryService |
+| Schema | schema.json |
+| Owner | Commerce Platform Team |
+
+By the end of the tutorial, you will have:
+
+- created a new EventCatalog project
+- run the catalog locally
+- found domains, services, messages, schemas, owners, and visualizations in the UI
+- added a domain, service, event, schema, owner, producer, and consumer
+- used EventCatalog to answer who owns an event and which services produce or consume it
+- built the catalog so it can be shared with your team
+
+This will not cover every EventCatalog feature. It gives you a clear first path through the product, then points you to the next places to go.
+
+## How EventCatalog docs work
+
+EventCatalog pages are written with [MDX](https://mdxjs.com/). That means you can write normal Markdown, and when you need something richer, you can add components directly into the page.
+
+Most catalog resources also have frontmatter at the top of the file. Frontmatter is where EventCatalog reads structured information like the resource `id`, `name`, `version`, owners, schemas, producers, consumers, and domain relationships.
+
+You will use both in this tutorial:
+
+- Markdown for the human-readable documentation.
+- Frontmatter for the architecture metadata EventCatalog uses to build relationships.
+- [EventCatalog components](/docs/development/components/using-components) for richer views, such as schemas and visualizations.
+
+You can learn more about [custom documentation and frontmatter](/docs/development/bring-your-own-documentation/custom-pages/adding-custom-docs), or come back to those docs after you finish this first catalog.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download/) v22 or higher installed.
+- Operating systems: macOS, Windows including WSL, or Linux.
+
+You do not need to know EventCatalog before starting.
+
+## Next step
+
+Continue to [Install EventCatalog](/docs/tutorial/install-eventcatalog).
diff --git a/packages/core/docs/tutorial/02-install-eventcatalog.md b/packages/core/docs/tutorial/02-install-eventcatalog.md
new file mode 100644
index 000000000..6e9d0a008
--- /dev/null
+++ b/packages/core/docs/tutorial/02-install-eventcatalog.md
@@ -0,0 +1,98 @@
+---
+sidebar_position: 2
+sidebar_label: Install EventCatalog
+title: Install EventCatalog
+description: Create a new EventCatalog project from the command line.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will create an empty EventCatalog project and run it locally.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'terminal',
+      text: 'Create an empty EventCatalog project from the command line.',
+    },
+    {
+      icon: 'folder',
+      text: 'Review the files and folders created for a blank catalog.',
+    },
+    {
+      icon: 'eye',
+      text: 'Start EventCatalog and open the empty catalog in your browser.',
+    },
+  ]}
+/>
+
+### Create an empty catalog
+
+Run:
+
+```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --empty
+```
+
+The `--empty` flag creates a clean catalog without sample domains, services, or messages. This gives us a blank project to build on during the tutorial.
+
+### Project structure
+
+After the install finishes, your empty catalog should look similar to this:
+
+<ProjectTree
+  items={[
+    {
+      name: 'public',
+      type: 'folder',
+      defaultOpen: true,
+      children: [{ name: 'logo.png' }],
+    },
+    { name: '.env' },
+    { name: 'AGENTS.md' },
+    { name: 'CLAUDE.md' },
+    { name: 'eventcatalog.auth.js' },
+    { name: 'eventcatalog.config.js', highlight: true },
+    { name: 'eventcatalog.styles.css' },
+    { name: 'package.json', highlight: true },
+  ]}
+/>
+
+For this tutorial, most of your work will happen in new folders that you create later. You will also come back to `eventcatalog.config.js` when you need to change catalog configuration.
+
+### Start EventCatalog
+
+Run commands in your new catalog directory
+
+```bash
+cd my-catalog
+```
+
+Run:
+
+```bash
+npm run dev
+```
+
+Open the local URL shown in your terminal. It is usually:
+
+```txt
+http://localhost:3000
+```
+
+### Expected result
+
+You should see a working EventCatalog site in your browser.
+
+The catalog will be mostly empty. That is expected. In the next steps, you will add the architecture yourself.
+
+<figure style={{ textAlign: "center" }}>
+  <img src="/img/tutorial/empty-catalog-home.png" alt="An empty EventCatalog running locally in the browser" style={{ display: "block", margin: "0 auto" }} />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>An empty EventCatalog running locally. Your catalog will start with very little content.</figcaption>
+</figure>
+
+
+### Next
+
+Continue to [Create a service](/docs/tutorial/create-a-service).
diff --git a/packages/core/docs/tutorial/04-add-ownership.md b/packages/core/docs/tutorial/04-add-ownership.md
new file mode 100644
index 000000000..f6149c4d9
--- /dev/null
+++ b/packages/core/docs/tutorial/04-add-ownership.md
@@ -0,0 +1,184 @@
+---
+sidebar_position: 7
+sidebar_label: Add ownership
+slug: /tutorial/add-ownership
+title: Add ownership
+description: Create a team and assign it to your services and event.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will add ownership to your catalog.
+
+Ownership helps people understand who maintains a service or event, who to ask for help, and who should review changes.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'folder',
+      text: 'Create the Commerce Platform Team.',
+    },
+    {
+      icon: 'server',
+      text: 'Assign the team to both services.',
+    },
+    {
+      icon: 'network',
+      text: 'Assign the team to OrderPlaced.',
+    },
+  ]}
+/>
+
+### Create the team
+
+Owners in EventCatalog can be [teams](/docs/development/guides/owners/what-are-teams-and-users) or [users](/docs/development/guides/owners/what-are-teams-and-users). For this tutorial, you will create one team: `Commerce Platform Team`.
+
+From the root of your catalog, create a `teams` folder:
+
+```bash
+mkdir -p teams
+```
+
+Create a new file at `teams/commerce-platform-team.mdx`:
+
+```mdx title="teams/commerce-platform-team.mdx"
+---
+id: commerce-platform-team
+name: Commerce Platform Team
+summary: |
+  Owns the services and events that support customer ordering.
+email: commerce-platform@example.com
+---
+
+## Overview
+
+The Commerce Platform Team owns the systems that support customer checkout, ordering, and inventory coordination.
+```
+
+The important frontmatter fields are:
+
+- `id` is the stable identifier you will reference from other resources.
+- `name` is the label people see in EventCatalog.
+- `summary` explains what the team owns.
+- `email` gives people a contact path.
+
+You can learn more in the [teams guide](/docs/development/guides/owners/what-are-teams-and-users).
+
+### Assign the services
+
+Open `services/OrderService/index.mdx` and add `owners` to the frontmatter:
+
+```mdx title="services/OrderService/index.mdx"
+---
+id: OrderService
+name: Order Service
+version: 0.0.1
+summary: |
+  Handles customer orders from checkout through to fulfilment.
+owners:
+  - commerce-platform-team
+sends:
+  - id: OrderPlaced
+    version: 0.0.1
+---
+```
+
+Now open `services/InventoryService/index.mdx` and add the same owner:
+
+```mdx title="services/InventoryService/index.mdx"
+---
+id: InventoryService
+name: Inventory Service
+version: 0.0.1
+summary: |
+  Tracks stock levels and reserves inventory for customer orders.
+owners:
+  - commerce-platform-team
+receives:
+  - id: OrderPlaced
+    version: 0.0.1
+---
+```
+
+The `owners` list references the team `id`, not the display name.
+
+### Assign the event
+
+Open `services/OrderService/events/OrderPlaced/index.mdx` and add the same owner:
+
+```mdx title="services/OrderService/events/OrderPlaced/index.mdx"
+---
+id: OrderPlaced
+name: Order Placed
+version: 0.0.1
+summary: |
+  Raised when a customer places an order.
+owners:
+  - commerce-platform-team
+schemaPath: schema.json
+---
+```
+
+Assigning owners to events is optional, but useful when the event contract needs a clear team responsible for changes.
+
+You can learn more in the [messages reference](/docs/development/guides/resources/messages/reference#owners) and the [service reference](/docs/development/guides/resources/services/reference#owners).
+
+### Check ownership in EventCatalog
+
+Refresh EventCatalog and open [OrderService](http://localhost:3000/docs/services/OrderService/0.0.1).
+
+You should see `Commerce Platform Team` listed as an owner of the service.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-service-owner-page.png"
+    alt="Order Service showing Commerce Platform Team as an owner"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    Order Service shows Commerce Platform Team as the owner.
+  </figcaption>
+</figure>
+
+Open [OrderPlaced](http://localhost:3000/docs/events/OrderPlaced/0.0.1).
+
+You should see the same team listed as the owner of the event. This tells people who maintains the event contract and who to contact before changing it.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-placed-owner-page.png"
+    alt="Order Placed event showing Commerce Platform Team as an owner"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    Order Placed shows its owner alongside its producers and consumers.
+  </figcaption>
+</figure>
+
+Open [Commerce Platform Team](http://localhost:3000/docs/teams/commerce-platform-team) from the team directory.
+
+The team page gives people a central place to understand who owns this part of the architecture.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/commerce-platform-team-page.png"
+    alt="Commerce Platform Team page showing owned services and messages"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    The team page lists the services and messages owned by Commerce Platform Team.
+  </figcaption>
+</figure>
+
+### What you have now
+
+Your catalog now has a first ownership model:
+
+- a team page
+- owned services
+- an owned event
+- a clear contact path for the team
+
+### Next
+
+Continue to [Create a domain](/docs/tutorial/create-a-domain).
diff --git a/packages/core/docs/tutorial/04-create-event.md b/packages/core/docs/tutorial/04-create-event.md
new file mode 100644
index 000000000..0ee74d8ee
--- /dev/null
+++ b/packages/core/docs/tutorial/04-create-event.md
@@ -0,0 +1,176 @@
+---
+sidebar_position: 4
+sidebar_label: Create an event
+slug: /tutorial/create-event
+title: Create an event
+description: Add the first event and schema to your tutorial catalog.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will document the first event in your catalog and add a schema for its payload.
+
+An event describes something that has happened. In this tutorial, the first event is `OrderPlaced`. It tells other systems that a customer has placed an order.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'folder',
+      text: 'Create an event folder inside OrderService.',
+    },
+    {
+      icon: 'file',
+      text: 'Add the event metadata and a short description.',
+    },
+    {
+      icon: 'code',
+      text: 'Add a JSON schema and render it on the event page.',
+    },
+    {
+      icon: 'eye',
+      text: 'Open the event in EventCatalog.',
+    },
+  ]}
+/>
+
+### Create the event folder
+
+From the root of your catalog, create an event folder inside `OrderService`:
+
+```bash
+mkdir -p services/OrderService/events/OrderPlaced
+```
+
+This keeps the event close to the service that publishes it. You can also put events in a top-level `events` folder, but service-owned events are a useful place to start when you are learning.
+
+### Add the event page
+
+Create a new file at `services/OrderService/events/OrderPlaced/index.mdx`:
+
+```mdx title="services/OrderService/events/OrderPlaced/index.mdx"
+---
+id: OrderPlaced
+name: Order Placed
+version: 0.0.1
+summary: |
+  Raised when a customer places an order.
+schemaPath: schema.json
+---
+
+## Overview
+
+The Order Placed event is raised after a customer completes checkout.
+
+Other systems can use this event to start work that depends on the order, such as fulfilment, inventory allocation, or customer notifications.
+
+## Schema
+
+<SchemaViewer file="schema.json" title="OrderPlaced schema" maxHeight="500" search="true" />
+```
+
+Keep the event focused on what happened and why it matters. The important part is the frontmatter at the top of the file:
+
+- `id` is the stable identifier EventCatalog uses for links and references.
+- `name` is the label people see in the UI.
+- `version` is the version of this event.
+- `summary` is a short description shown in event lists and page headers.
+- `schemaPath` tells EventCatalog which schema belongs to this event.
+
+### Add the schema file
+
+The event page explains the meaning of the event. The schema explains the shape of the payload.
+
+EventCatalog supports any schema format. In this tutorial, you will add a JSON schema.
+
+:::info Using a schema registry?
+EventCatalog has [many integrations](https://www.eventcatalog.dev/integrations) and can sync schemas directly from your registry into the catalog. In this tutorial, you will manually create the schema, but you can set up a registry integration later.
+:::
+
+Create `schema.json` in the same folder as the event:
+
+```json title="services/OrderService/events/OrderPlaced/schema.json"
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/order-placed.json",
+  "title": "OrderPlaced",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["eventId", "orderId", "customerId", "total", "currency", "createdAt"],
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "description": "Unique identifier for this event."
+    },
+    "orderId": {
+      "type": "string",
+      "description": "Unique identifier for the order."
+    },
+    "customerId": {
+      "type": "string",
+      "description": "Unique identifier for the customer."
+    },
+    "total": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Total value of the order."
+    },
+    "currency": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 3,
+      "description": "Three letter currency code for the order total."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Time the order was created."
+    }
+  }
+}
+```
+
+### Show the schema on the event page
+
+The event page already includes the [`SchemaViewer`](/docs/development/components/components/schema-viewer) component:
+
+```mdx
+<SchemaViewer file="schema.json" title="OrderPlaced schema" maxHeight="500" search="true" />
+```
+
+[`SchemaViewer`](/docs/development/components/components/schema-viewer) renders schemas in a more readable way than a plain code block.
+
+### Check the event in EventCatalog
+
+Refresh EventCatalog in your browser. You should now be able to find `OrderPlaced` in your catalog at [http://localhost:3000/docs/events/OrderPlaced/0.0.1](http://localhost:3000/docs/events/OrderPlaced/0.0.1).
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-placed-event-page.png"
+    alt="The Order Placed event page in EventCatalog"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>The Order Placed event page after adding the event and schema.</figcaption>
+</figure>
+
+The schema should also render on the event page.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-placed-schema-viewer.png"
+    alt="The SchemaViewer component rendering the OrderPlaced schema"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>The OrderPlaced schema rendered with SchemaViewer.</figcaption>
+</figure>
+
+### What you have now
+
+Your catalog now has:
+
+- `services/OrderService/events/OrderPlaced/index.mdx`
+- `services/OrderService/events/OrderPlaced/schema.json`
+- a [`SchemaViewer`](/docs/development/components/components/schema-viewer) block that renders the schema in EventCatalog
+
+### Next
+
+Continue to [Publish the event from a service](/docs/tutorial/publish-event).
diff --git a/packages/core/docs/tutorial/05-create-a-domain.md b/packages/core/docs/tutorial/05-create-a-domain.md
new file mode 100644
index 000000000..1b8a072a4
--- /dev/null
+++ b/packages/core/docs/tutorial/05-create-a-domain.md
@@ -0,0 +1,133 @@
+---
+sidebar_position: 8
+sidebar_label: Create a domain
+slug: /tutorial/create-a-domain
+title: Create a domain
+description: Group the tutorial services into a domain.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will create your first domain.
+
+A [domain](/docs/development/guides/domains/introduction) groups related parts of your architecture around a business area. In this tutorial, you will create an `E-Commerce` domain and add the two services you already created.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'folder',
+      text: 'Create an E-Commerce domain folder.',
+    },
+    {
+      icon: 'server',
+      text: 'Add OrderService and InventoryService to the domain.',
+    },
+    {
+      icon: 'eye',
+      text: 'Refresh EventCatalog and check the domain page.',
+    },
+  ]}
+/>
+
+### Create the domain folder
+
+From the root of your catalog, create a folder for the domain:
+
+```bash
+mkdir -p domains/E-Commerce
+```
+
+### Add the domain page
+
+Create a new file at `domains/E-Commerce/index.mdx`:
+
+```mdx title="domains/E-Commerce/index.mdx"
+---
+id: E-Commerce
+name: E-Commerce
+version: 0.0.1
+summary: |
+  Contains the services that support customer ordering.
+owners:
+  - commerce-platform-team
+services:
+  - id: OrderService
+    version: 0.0.1
+  - id: InventoryService
+    version: 0.0.1
+---
+
+## Overview
+
+The E-Commerce domain contains the services that support checkout, orders, and inventory coordination.
+```
+
+The important frontmatter fields are:
+
+- `id` is the stable identifier for the domain.
+- `name` is the label people see in EventCatalog.
+- `version` is the version of the domain page.
+- `summary` explains what belongs in the domain.
+- `owners` links the domain to the team that owns it.
+- `services` lists the services that belong to the domain.
+
+You can learn more in the [create a domain guide](/docs/development/guides/domains/create-domain), [add services to domains guide](/docs/development/guides/domains/add-resources-to-domains/add-services-to-domains), and [domain owners guide](/docs/development/guides/domains/ownership-and-language/owners).
+
+The `version` field inside each service reference is optional. If you leave it out, EventCatalog will use the latest version of that service.
+
+### Check the domain in EventCatalog
+
+Refresh EventCatalog in your browser and open the `E-Commerce` domain.
+
+You should see the domain page and the two services listed in the sidebar at [http://localhost:3000/docs/domains/E-Commerce/0.0.1](http://localhost:3000/docs/domains/E-Commerce/0.0.1)
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/e-commerce-domain-page.png"
+    alt="E-Commerce domain page showing Order Service and Inventory Service"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    The E-Commerce domain groups Order Service and Inventory Service.
+  </figcaption>
+</figure>
+
+### Check the domain map
+
+Open the `Map` view from the domain page.
+
+EventCatalog shows the services that belong to the domain. Because those services already publish and consume `OrderPlaced`, the map also shows that relationship. You still only added services to the domain.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/e-commerce-domain-map.png"
+    alt="E-Commerce domain map showing Order Service and Inventory Service"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    The E-Commerce domain map shows the services in the domain and the event relationship between them.
+  </figcaption>
+</figure>
+
+:::tip Show the domain map on the page
+You can also embed the domain visualization directly into the domain documentation page with the [`NodeGraph`](/docs/development/components/components/nodegraph) component:
+
+```mdx
+<NodeGraph />
+```
+:::
+
+### What you have now
+
+Your catalog now has:
+
+- two services
+- one event
+- a schema
+- producer and consumer relationships
+- ownership
+- an `E-Commerce` domain that groups the services
+
+### Next
+
+Continue to [Visualize your catalog](/docs/tutorial/visualize-your-catalog).
diff --git a/packages/core/docs/tutorial/05-publish-event.md b/packages/core/docs/tutorial/05-publish-event.md
new file mode 100644
index 000000000..6e831ea22
--- /dev/null
+++ b/packages/core/docs/tutorial/05-publish-event.md
@@ -0,0 +1,82 @@
+---
+sidebar_position: 5
+sidebar_label: Publish from a service
+slug: /tutorial/publish-event
+title: Publish the event from a service
+description: Update OrderService so EventCatalog knows it publishes OrderPlaced.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will connect `OrderService` to the `OrderPlaced` event.
+
+In EventCatalog, a service publishes an event by listing it under `sends`.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'server',
+      text: 'Open the OrderService page.',
+    },
+    {
+      icon: 'network',
+      text: 'Add OrderPlaced to the sends list.',
+    },
+    {
+      icon: 'eye',
+      text: 'Refresh EventCatalog and inspect the relationship.',
+    },
+  ]}
+/>
+
+### Update the service
+
+Open `services/OrderService/index.mdx` and add `sends` to the frontmatter:
+
+```mdx title="services/OrderService/index.mdx"
+---
+id: OrderService
+name: Order Service
+version: 0.0.1
+summary: |
+  Handles customer orders from checkout through to fulfilment.
+sends:
+  - id: OrderPlaced
+    version: 0.0.1
+---
+```
+
+Keep the markdown content below the frontmatter as it is.
+
+The `version` field inside `sends` is optional. If you leave it out, EventCatalog will use the latest version of the event.
+
+### Check the relationship
+
+Refresh EventCatalog in your browser and open the [Order Service page](http://localhost:3000/visualiser/services/OrderService/0.0.1).
+
+You should now be able to see that `OrderService` publishes `OrderPlaced`. Open the event page as well. EventCatalog can now show the event and its producer as connected resources.
+
+You can also open the `Map` view from the Order Service page to see the relationship visually.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-service-publishes-order-placed-map.png"
+    alt="The Order Service map showing that it publishes the Order Placed event"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>The Order Service map showing the OrderPlaced publish relationship.</figcaption>
+</figure>
+
+We are only setting up the producer in this step. Next, you will add another service and connect it as a consumer with `receives`.
+
+### What you have now
+
+Your catalog now knows:
+
+- `OrderPlaced` is an event.
+- `OrderPlaced` has a schema.
+- `OrderService` publishes `OrderPlaced`.
+
+### Next
+
+Continue to [Consume the event from a service](/docs/tutorial/consume-event).
diff --git a/packages/core/docs/tutorial/06-consume-event.md b/packages/core/docs/tutorial/06-consume-event.md
new file mode 100644
index 000000000..7708bb91c
--- /dev/null
+++ b/packages/core/docs/tutorial/06-consume-event.md
@@ -0,0 +1,130 @@
+---
+sidebar_position: 6
+sidebar_label: Consume from a service
+slug: /tutorial/consume-event
+title: Consume the event from a service
+description: Create InventoryService and mark it as a consumer of OrderPlaced.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will create `InventoryService` and connect it to the `OrderPlaced` event.
+
+In EventCatalog, a service consumes an event by listing it under `receives`.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'server',
+      text: 'Create the InventoryService page.',
+    },
+    {
+      icon: 'network',
+      text: 'Add OrderPlaced to the receives list.',
+    },
+    {
+      icon: 'eye',
+      text: 'Refresh EventCatalog and inspect the full relationship.',
+    },
+  ]}
+/>
+
+### Create the service folder
+
+From the root of your catalog, create a new folder for the service:
+
+```bash
+mkdir -p services/InventoryService
+```
+
+### Add the service page
+
+Create a new file at `services/InventoryService/index.mdx` and add `receives` to the frontmatter:
+
+```mdx title="services/InventoryService/index.mdx"
+---
+id: InventoryService
+name: Inventory Service
+version: 0.0.1
+summary: |
+  Tracks stock levels and reserves inventory for customer orders.
+receives:
+  - id: OrderPlaced
+    version: 0.0.1
+---
+
+## Overview
+
+The inventory service tracks product avaliability and reservces stock when a customer places an order.
+
+```
+
+Keep the markdown content below the frontmatter as it is.
+
+The frontmatter follows the same shape as `OrderService`:
+
+- `id` is the stable identifier EventCatalog uses for links and references.
+- `name` is the label people see in the UI.
+- `version` is the version of this service.
+- `summary` appears in service lists and page headers.
+- `receives` lists the events this service consumes.
+
+The `version` field inside `receives` is optional. If you leave it out, EventCatalog will use the latest version of the event.
+
+### Check the service in EventCatalog
+
+Refresh EventCatalog in your browser. You should now be able to find `InventoryService` in your catalog.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/inventory-service-page.png"
+    alt="The Inventory Service page in EventCatalog"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>The Inventory Service page after adding the service file.</figcaption>
+</figure>
+
+### Check the relationship
+
+Refresh EventCatalog in your browser and open the `OrderPlaced` event page.
+
+You should now be able to see both sides of the event:
+
+- `OrderService` publishes `OrderPlaced`.
+- `InventoryService` consumes `OrderPlaced`.
+
+Open the `Map` view from the event page to see the relationship visually.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-placed-producer-consumer-map.png"
+    alt="The OrderPlaced event map showing OrderService as producer and InventoryService as consumer"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>The OrderPlaced map showing OrderService publishing the event and InventoryService consuming it.</figcaption>
+</figure>
+
+:::tip Show the visualizer on the page
+You can embed the same kind of visualization directly into a documentation page with the [`NodeGraph`](/docs/development/components/components/nodegraph) component:
+
+```mdx
+<NodeGraph />
+```
+
+When used on a service or event page, `NodeGraph` renders the graph for the current resource.
+:::
+
+### What you have now
+
+Your catalog now knows:
+
+- `OrderPlaced` is an event.
+- `OrderPlaced` has a schema.
+- `OrderService` publishes `OrderPlaced`.
+- `InventoryService` consumes `OrderPlaced`.
+
+This is the first complete event relationship in the tutorial catalog.
+
+### Next
+
+Continue to [Add ownership](/docs/tutorial/add-ownership).
diff --git a/packages/core/docs/tutorial/06-create-a-service.md b/packages/core/docs/tutorial/06-create-a-service.md
new file mode 100644
index 000000000..fc321fa39
--- /dev/null
+++ b/packages/core/docs/tutorial/06-create-a-service.md
@@ -0,0 +1,99 @@
+---
+sidebar_position: 3
+sidebar_label: Create a service
+title: Create a service
+description: Add the first service to your tutorial catalog.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will add your first service to the catalog.
+
+A service is a system, application, or process that owns part of your architecture. Later in the tutorial, this service will send and receive events. For now, you only need a simple service page that gives people a place to start.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'folder',
+      text: 'Create the folder structure for OrderService.',
+    },
+    {
+      icon: 'file',
+      text: 'Add an index.mdx file with the service metadata.',
+    },
+    {
+      icon: 'eye',
+      text: 'Refresh EventCatalog and find the service in the browser.',
+    },
+  ]}
+/>
+
+### Create the service folder
+
+From the root of your catalog, create a new folder for the service:
+
+```bash
+mkdir -p services/OrderService
+```
+
+EventCatalog looks inside the `services` folder for service pages. Each service has its own folder and an `index.mdx` file.
+
+### Add the service page
+
+Create a new file at `services/OrderService/index.mdx`:
+
+```mdx title="services/OrderService/index.mdx"
+---
+id: OrderService
+name: Order Service
+version: 0.0.1
+summary: |
+  Handles customer orders from checkout through to fulfilment.
+---
+
+## Overview
+
+The Order Service is responsible for creating and managing customer orders.
+
+In this tutorial, you will use this service to learn how EventCatalog connects services, domains, events, schemas, and ownership.
+```
+
+Keep the content small for now. The important part is the frontmatter at the top of the file:
+
+- `id` is the stable identifier EventCatalog uses for links and references.
+- `name` is the label people see in the UI.
+- `version` is the version of this service.
+- `summary` appears in service lists and page headers.
+
+### Check the service in EventCatalog
+
+If your catalog is still running, refresh your browser.
+
+If it is not running, start it again:
+
+```bash
+npm run dev
+```
+
+Open the local EventCatalog URL shown in your terminal. You should now see the Order Service in your catalog at [http://localhost:3000/docs/services/OrderService/0.0.1](http://localhost:3000/docs/services/OrderService/0.0.1).
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-service-page.png"
+    alt="The Order Service page in EventCatalog"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>The Order Service page after adding the service file.</figcaption>
+</figure>
+
+### What you have now
+
+Your catalog now has one documented service:
+
+- `services/OrderService/index.mdx`
+
+This is the first building block. Next, you will group your architecture around a domain.
+
+### Next
+
+Continue to [Create an event](/docs/tutorial/create-event).
diff --git a/packages/core/docs/tutorial/11-visualize-your-catalog.md b/packages/core/docs/tutorial/11-visualize-your-catalog.md
new file mode 100644
index 000000000..9be71feb8
--- /dev/null
+++ b/packages/core/docs/tutorial/11-visualize-your-catalog.md
@@ -0,0 +1,105 @@
+---
+sidebar_position: 9
+sidebar_label: Visualize your catalog
+title: Visualize your catalog
+description: Use EventCatalog visualizations to inspect the tutorial architecture.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will use EventCatalog visualizations to understand the model you created.
+
+Visualizations help people see how systems connect. They grow as your catalog grows, so the same view can start with one event relationship and later include domains, commands, queries, flows, channels, data stores, agents, and other architecture primitives.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'network',
+      text: 'Use NodeGraph inside documentation pages.',
+    },
+    {
+      icon: 'eye',
+      text: 'Use the Visualizer to explore the catalog map.',
+    },
+    {
+      icon: 'code',
+      text: 'Export visualizations to Mermaid when you need to share or edit them elsewhere.',
+    },
+  ]}
+/>
+
+### Use NodeGraph on a page
+
+The [`NodeGraph`](/docs/development/components/components/nodegraph) component can be added to domain, service, message, changelog, and custom documentation pages.
+
+Add it to a resource page like this:
+
+```mdx
+<NodeGraph />
+```
+
+When used without props, `NodeGraph` renders a visualization for the current page. For example, on the `OrderPlaced` page it can show the event, the service that publishes it, and the service that consumes it.
+
+You can also render a graph for a specific resource:
+
+```mdx
+<NodeGraph id="E-Commerce" version="0.0.1" type="domain" />
+```
+
+This is useful when you want the visualization to appear directly next to the documentation people are reading.
+
+### Use the Visualizer
+
+The Visualizer is the full map view in EventCatalog. It gives you more room to explore how resources connect across your catalog.
+
+Open the `OrderPlaced` map from the event page. You should see:
+
+- `OrderService` publishes `OrderPlaced`.
+- `InventoryService` consumes `OrderPlaced`.
+- the relationship between the producer, event, and consumer.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/order-placed-producer-consumer-map.png"
+    alt="The OrderPlaced visualizer map showing OrderService as producer and InventoryService as consumer"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    The OrderPlaced map shows the producer, event, and consumer relationship.
+  </figcaption>
+</figure>
+
+Now open the `E-Commerce` domain map. The domain only references the services, but the map can still show the event relationship between them.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/e-commerce-domain-map.png"
+    alt="The E-Commerce domain visualizer map showing services and their event relationship"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    The E-Commerce domain map gives a focused view of the services in that part of the architecture.
+  </figcaption>
+</figure>
+
+### Export to Mermaid
+
+NodeGraph visualizations can be switched to Mermaid view or copied as Mermaid diagram code. This is useful when you want to share the architecture with another tool, paste it into documentation, or give it to an AI assistant for review.
+
+You can learn more in the [NodeGraph docs](/docs/development/components/components/nodegraph#export-as-mermaid) and the [Mermaid docs](/docs/development/components/diagram-syntax/mermaid#export-nodegraphs-as-mermaid).
+
+### What you have now
+
+You can use EventCatalog to:
+
+- embed visualizations directly inside documentation pages
+- explore the wider catalog with the Visualizer
+- see events between systems
+- understand how services, domains, ownership, and messages connect
+- export visualizations as Mermaid when you need to use them elsewhere
+
+As you add more resources, these visualizations become more useful. Commands, queries, domains, flows, channels, data stores, agents, and extra services can all add more context to the map.
+
+### Next
+
+Continue to [Build and deploy your catalog](/docs/tutorial/build-your-catalog).
diff --git a/packages/core/docs/tutorial/12-build-your-catalog.md b/packages/core/docs/tutorial/12-build-your-catalog.md
new file mode 100644
index 000000000..84afce240
--- /dev/null
+++ b/packages/core/docs/tutorial/12-build-your-catalog.md
@@ -0,0 +1,79 @@
+---
+sidebar_position: 10
+sidebar_label: Build and deploy
+title: Build and deploy your catalog
+description: Build your EventCatalog site and choose a deployment path.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+In this step, you will build your catalog and decide how you want to deploy it.
+
+Most new EventCatalog projects build as a static site. That means EventCatalog creates HTML files that you can host on most static hosting platforms.
+
+<ChapterOverview
+  items={[
+    {
+      icon: 'code',
+      text: 'Run a production build.',
+    },
+    {
+      icon: 'eye',
+      text: 'Preview the built catalog locally.',
+    },
+    {
+      icon: 'server',
+      text: 'Choose a deployment path for your team.',
+    },
+  ]}
+/>
+
+### Build the catalog
+
+Run:
+
+```bash
+npm run build
+```
+
+EventCatalog creates a production-ready build in the `dist` folder.
+
+You can learn more in the [develop and build guide](/docs/development/getting-started/develop-and-build) and the [static build guide](/docs/development/deployment/build-and-deploy).
+
+### Preview the build
+
+After the build finishes, preview the built catalog locally:
+
+```bash
+npm run preview
+```
+
+This lets you check the production build before you publish it.
+
+If the build fails, check the error in your terminal first. Common issues are broken links, invalid frontmatter, schema path mistakes, or missing files.
+
+### Choose a deployment path
+
+For most first catalogs, static hosting is the simplest path. You can deploy the `dist` folder to the hosting platform your team already uses.
+
+EventCatalog also supports server-side rendering for larger catalogs or features that need a server.
+
+Useful deployment docs:
+
+- [Build and deploy](/docs/development/deployment/build-and-deploy)
+- [Hosting options](/docs/development/deployment/hosting-options)
+- [Deployment workflows](/docs/development/deployment/deployment-workflows)
+- [SSR mode](/docs/development/deployment/build-ssr-mode)
+
+### What you have now
+
+You now know how to:
+
+- build the catalog for production
+- preview the production build locally
+- choose between static hosting and server-side rendering
+
+
+### Next
+
+Continue to [Next steps](/docs/tutorial/next-steps).
diff --git a/packages/core/docs/tutorial/14-next-steps.md b/packages/core/docs/tutorial/14-next-steps.md
new file mode 100644
index 000000000..c7b351889
--- /dev/null
+++ b/packages/core/docs/tutorial/14-next-steps.md
@@ -0,0 +1,108 @@
+---
+sidebar_position: 11
+sidebar_label: Next steps
+title: Next steps
+description: Grow your catalog beyond the tutorial.
+---
+
+import ChapterOverview from '@site/src/components/MDX/ChapterOverview';
+
+Congratulations, you have created your first EventCatalog.
+
+This is a real catalog now. It models architecture primitives, links them together, and gives people a place to understand how part of your system works.
+
+<ChapterOverview
+  title="Your catalog now has..."
+  description="The first pieces of a useful architecture catalog"
+  items={[
+    {
+      icon: 'server',
+      text: 'Services that describe the systems in your architecture.',
+    },
+    {
+      icon: 'network',
+      text: 'An event with producer and consumer relationships.',
+    },
+    {
+      icon: 'code',
+      text: 'A schema that explains the event payload.',
+    },
+    {
+      icon: 'folder',
+      text: 'Ownership and a domain to group the work.',
+    },
+    {
+      icon: 'eye',
+      text: 'Visualizations and a production build path.',
+    },
+  ]}
+/>
+
+This is enough to give people a useful first view of your architecture. From here, you can keep adding detail in the way that fits your team.
+
+### See a fuller catalog
+
+The tutorial catalog is small on purpose. EventCatalog can model many more architecture primitives, including [services](/docs/development/guides/resources/services/introduction), [events](/docs/development/guides/resources/messages/message-types/events), [commands](/docs/development/guides/resources/messages/message-types/commands), [queries](/docs/development/guides/resources/messages/message-types/queries), [channels](/docs/development/guides/resources/messages/message-channels/introduction), [data stores](/docs/development/guides/resources/data/introduction), [data products](/docs/development/guides/resources/data-products/introduction), [agents](/docs/development/guides/resources/agents/introduction), [owners](/docs/development/guides/owners/what-are-teams-and-users), [domains](/docs/development/guides/domains/introduction), [flows](/docs/development/guides/resources/flows/introduction), and the relationships between them.
+
+You can explore the public [EventCatalog demo catalog](https://demo.eventcatalog.dev/) to see a larger example.
+
+<figure style={{ textAlign: "center" }}>
+  <img
+    src="/img/tutorial/demo-catalog-orders-service-visualizer.png"
+    alt="The EventCatalog demo visualizer showing a larger Orders Service architecture"
+    style={{ display: "block", margin: "0 auto" }}
+  />
+  <figcaption style={{ fontSize: "0.875rem", fontStyle: "italic" }}>
+    The demo catalog visualizer shows services, events, channels, data stores, agents, and workflows connected together.
+  </figcaption>
+</figure>
+
+[Open this view in the demo catalog](https://demo.eventcatalog.dev/visualiser/services/OrdersService/0.0.3).
+
+### Add more documentation
+
+Every resource page is Markdown and MDX. You can add more explanation, diagrams, links, runbooks, examples, or any other content that helps people understand the system.
+
+Useful docs:
+
+- [Using components](/docs/development/components/using-components)
+- [Custom components](/docs/development/components/custom-components/introduction)
+- [Resource references](/docs/development/components/resource-references)
+- [Bring your own documentation](/docs/development/bring-your-own-documentation/custom-pages/adding-custom-docs)
+
+### Edit visually with EventCatalog Editor
+
+If you prefer a visual local editor, try [EventCatalog Editor](/docs/editor/overview). It runs locally and gives you a UI for editing the catalog files in your project.
+
+### Automate from existing specifications
+
+You do not have to maintain everything by hand. EventCatalog can generate catalog resources from specifications and registries.
+
+Useful plugin docs:
+
+- [OpenAPI plugin](/docs/plugins/openapi/intro)
+- [AsyncAPI plugin](/docs/plugins/asyncapi/intro)
+- [Confluent Schema Registry plugin](/docs/plugins/confluent-schema-registry/intro)
+- [GitHub plugin](/docs/plugins/github/intro)
+
+### Model more architecture primitives
+
+The tutorial focused on services, events, schemas, owners, and domains. EventCatalog can model more of your architecture as your catalog grows.
+
+Use these docs when you are ready to add more primitives to your catalog:
+
+- [Domains](/docs/development/guides/domains/introduction)
+- [Services](/docs/development/guides/resources/services/introduction)
+- [Events](/docs/development/guides/resources/messages/message-types/events)
+- [Commands](/docs/development/guides/resources/messages/message-types/commands)
+- [Queries](/docs/development/guides/resources/messages/message-types/queries)
+- [Channels](/docs/development/guides/resources/messages/message-channels/introduction)
+- [Data stores](/docs/development/guides/resources/data/introduction)
+- [Data products](/docs/development/guides/resources/data-products/introduction)
+- [Agents](/docs/development/guides/resources/agents/introduction)
+- [Flows](/docs/development/guides/resources/flows/add-flows-to-resources)
+- [Owners](/docs/development/guides/owners/what-are-teams-and-users)
+
+### Keep improving the catalog
+
+Start small, keep the content close to the systems it describes, and add more detail when people ask questions the catalog cannot answer yet.
diff --git a/packages/core/docs/tutorial/_category_.json b/packages/core/docs/tutorial/_category_.json
new file mode 100644
index 000000000..00a80784d
--- /dev/null
+++ b/packages/core/docs/tutorial/_category_.json
@@ -0,0 +1,12 @@
+{
+  "label": "Tutorial",
+  "position": 1,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "tutorial",
+    "title": "EventCatalog Tutorial",
+    "description": "Build your first EventCatalog from a small commerce architecture and learn how domains, services, messages, schemas, owners, and visualizations fit together."
+  }
+}
diff --git a/eventcatalog-api-openapi.yaml b/packages/core/eventcatalog-api-openapi.yaml
similarity index 100%
rename from eventcatalog-api-openapi.yaml
rename to packages/core/eventcatalog-api-openapi.yaml
diff --git a/packages/core/eventcatalog/.gitignore b/packages/core/eventcatalog/.gitignore
new file mode 100644
index 000000000..fca2a04c8
--- /dev/null
+++ b/packages/core/eventcatalog/.gitignore
@@ -0,0 +1,26 @@
+# build output
+dist/
+
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# EventCatalog files
+src/content/*
+!src/content/config.ts
+public/generated/*
+src/catalog-files/*
+src/custom-defined-components/*
+src/custom-pages/*
+src/snippets/*
+
+eventcatalog.config.js
+eventcatalog.styles.css
+
+src/generated-ai/*
+
+src/pages/api/server/*
+src/pages/api/chat.ts
+src/pages/api/[...auth].ts
diff --git a/eventcatalog/.npmrc b/packages/core/eventcatalog/.npmrc
similarity index 100%
rename from eventcatalog/.npmrc
rename to packages/core/eventcatalog/.npmrc
diff --git a/packages/core/eventcatalog/astro.config.mjs b/packages/core/eventcatalog/astro.config.mjs
new file mode 100644
index 000000000..272662696
--- /dev/null
+++ b/packages/core/eventcatalog/astro.config.mjs
@@ -0,0 +1,200 @@
+import { defineConfig } from 'astro/config';
+import { unified } from '@astrojs/markdown-remark';
+import tailwindcss from '@tailwindcss/vite';
+import mdx from '@astrojs/mdx';
+import react from '@astrojs/react';
+import { searchForWorkspaceRoot } from 'vite';
+import { mermaid } from './src/remark-plugins/mermaid';
+import { plantuml } from './src/remark-plugins/plantuml';
+import { join } from 'node:path';
+import remarkDirective from 'remark-directive';
+import { remarkDirectives } from './src/remark-plugins/directives';
+import { remarkResourceRef } from './src/remark-plugins/resource-ref';
+import node from '@astrojs/node';
+import remarkComment from 'remark-comment';
+import rehypeSlug from 'rehype-slug';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
+import { eventCatalogLikeC4 } from './src/plugins/likec4';
+import { astroTrailingSlashEndpointFix } from './src/plugins/astro-trailing-slash-endpoint-fix';
+
+import rehypeExpressiveCode from 'rehype-expressive-code';
+
+/** @type {import('bin/eventcatalog.config').Config} */
+import config from './eventcatalog.config';
+import expressiveCode from 'astro-expressive-code';
+// Expressive Code options (including the non-serializable `themeCssSelector`
+// function) live in ec.config.mjs. The `expressiveCode()` integration loads that
+// file automatically; the rehype plugin used by mdx() below needs it passed
+// explicitly, so we import it here to keep a single source of truth.
+import expressiveCodeConfig from './ec.config.mjs';
+import ecstudioWatcher from './integrations/ecstudio-watcher.mjs';
+import eventCatalogIntegration from './src/enterprise/integrations/eventcatalog-features.ts';
+
+const projectDirectory = process.env.PROJECT_DIR || process.cwd();
+const base = config.base || '/';
+const host = config.host || false;
+const compress = config.compress ?? false;
+const isDevMode = process.env.EVENTCATALOG_DEV_MODE === 'true';
+const effectiveOutput = isDevMode ? 'server' : config.output || 'static';
+const searchType = config.search?.type || 'resource';
+
+const markdownRemarkPlugins = [remarkDirective, remarkDirectives, remarkComment, mermaid, plantuml];
+const mdxRemarkPlugins = [...markdownRemarkPlugins, remarkResourceRef];
+const mdxRehypePlugins = [
+  [
+    rehypeExpressiveCode,
+    {
+      ...expressiveCodeConfig,
+    },
+  ],
+  rehypeSlug,
+  [
+    rehypeAutolinkHeadings,
+    {
+      behavior: 'append',
+      properties: { className: ['anchor-link'] },
+    },
+  ],
+];
+
+// https://astro.build/config
+export default defineConfig({
+  base,
+  server: {
+    port: config.port || 3000,
+    host: host,
+    // Add allowed hosts if its set
+    ...(config.server?.allowedHosts ? { allowedHosts: config.server?.allowedHosts } : {}),
+  },
+
+  // If security is set
+  ...(config.security ? { security: config.security } : {}),
+
+  // In dev mode (EVENTCATALOG_DEV_MODE=true) we need 'server' output so that
+  // routes which opt into SSR via `export const prerender = false` (e.g. the
+  // /api/settings/* editing endpoints) are actually invoked instead of being
+  // statically prerendered. Production builds keep the user's configured output.
+  output: effectiveOutput,
+
+  adapter: effectiveOutput === 'server' ? node({ mode: 'standalone' }) : undefined,
+
+  outDir: config.outDir ? join(projectDirectory, config.outDir) : join(projectDirectory, 'dist'),
+
+  // https://docs.astro.build/en/reference/configuration-reference/#site
+  site: config.homepageLink || 'https://eventcatalog.dev/',
+
+  // https://docs.astro.build/en/reference/configuration-reference/#trailingslash
+  trailingSlash: config.trailingSlash === true ? 'always' : 'ignore',
+
+  markdown: {
+    processor: unified({
+      remarkPlugins: markdownRemarkPlugins,
+      rehypePlugins: mdxRehypePlugins,
+    }),
+  },
+
+  // just turn this off for all users (for now...)
+  devToolbar: { enabled: false },
+  integrations: [
+    react(),
+    // Options are loaded automatically from ec.config.mjs.
+    expressiveCode(),
+    mdx({
+      // https://docs.astro.build/en/guides/integrations-guide/mdx/#optimize
+      optimize: config.mdxOptimize || false,
+      processor: unified({
+        remarkPlugins: mdxRemarkPlugins,
+        rehypePlugins: mdxRehypePlugins,
+      }),
+    }),
+    effectiveOutput !== 'server' &&
+      compress &&
+      (await import('astro-compress')).default({
+        Logger: 0,
+        CSS: false,
+      }),
+    ecstudioWatcher(),
+    eventCatalogIntegration(),
+  ].filter(Boolean),
+  vite: {
+    plugins: [
+      tailwindcss(),
+      ...(await eventCatalogLikeC4(projectDirectory)),
+      ...(config.trailingSlash === true ? [astroTrailingSlashEndpointFix()] : []),
+    ],
+    define: {
+      /**
+       * Trailing slash is exposed as global variable here principally for `@utils/url-builder`.
+       * The utility is used by client components and because of that it can't direct import
+       * the eventcatalog.config, as the config use packages that only run in node environments,
+       * such as `node:path`.
+       */
+      __EC_TRAILING_SLASH__: JSON.stringify(config.trailingSlash === true),
+      __EC_BASE__: JSON.stringify(base),
+      __EC_SEARCH_TYPE__: JSON.stringify(searchType),
+    },
+    server: {
+      fs: {
+        allow: ['..', './node_modules/@fontsource', projectDirectory, searchForWorkspaceRoot(process.cwd())],
+      },
+      // Prevent stale FSEvents from triggering a config-dependency restart on first run.
+      // During startup, catalogToAstro copies eventcatalog.config.js into .eventcatalog-core
+      // shortly before Astro/Vite begins watching. On macOS, FSEvents can deliver buffered
+      // notifications for those recent writes, causing Vite to restart mid-dep-scan.
+      // awaitWriteFinish makes chokidar verify the file is stable before emitting events,
+      // filtering out those stale notifications.
+      watch: {
+        awaitWriteFinish: {
+          stabilityThreshold: 100,
+          pollInterval: 50,
+        },
+      },
+      ...(config.server?.allowedHosts ? { allowedHosts: config.server?.allowedHosts } : {}),
+      // Pre-transform critical modules during startup so they're ready when
+      // the first page request arrives. Without this, Vite transforms each
+      // module on-demand during the first request, adding seconds to TTFB.
+      warmup: {
+        ssrFiles: [
+          './src/pages/index.astro',
+          './src/pages/_index.astro',
+          './src/layouts/VerticalSideBarLayout.astro',
+          './src/components/Header.astro',
+          './src/components/SideNav/SideNav.astro',
+        ],
+        clientFiles: ['./src/components/SideNav/NestedSideBar/index.tsx', './src/components/Search/SearchModal.tsx'],
+      },
+    },
+    worker: {
+      format: 'es',
+    },
+    build: {
+      commonjsOptions: {
+        transformMixedEsModules: true,
+      },
+    },
+    ssr: {
+      noExternal: ['@xyflow/react'],
+      external: ['eventcatalog.auth.js', 'eventcatalog.chat.js'],
+    },
+    optimizeDeps: {
+      exclude: [],
+      // Pre-bundle heavy dependencies so Vite doesn't discover and transform
+      // them lazily on first request. This significantly reduces initial page
+      // load time in dev mode.
+      include: [
+        'lucide-react',
+        '@heroicons/react/24/outline',
+        '@heroicons/react/24/solid',
+        '@heroicons/react/20/solid',
+        '@headlessui/react',
+        '@nanostores/react',
+        'nanostores',
+        'react',
+        'react-dom',
+        'semver',
+        'diff',
+        'diff2html',
+      ],
+    },
+  },
+});
diff --git a/eventcatalog/auth.config.ts b/packages/core/eventcatalog/auth.config.ts
similarity index 99%
rename from eventcatalog/auth.config.ts
rename to packages/core/eventcatalog/auth.config.ts
index 96ee6a434..c4e44066d 100644
--- a/eventcatalog/auth.config.ts
+++ b/packages/core/eventcatalog/auth.config.ts
@@ -124,6 +124,7 @@ const getAuthConfig = async () => {
     const providers = await getAuthProviders();
 
     return {
+      trustHost: true,
       providers,
       callbacks: {
         async signIn({ user, account, profile }: { user: User; account: Account | null; profile?: Profile }) {
diff --git a/packages/core/eventcatalog/ec.config.mjs b/packages/core/eventcatalog/ec.config.mjs
new file mode 100644
index 000000000..0b59ada9f
--- /dev/null
+++ b/packages/core/eventcatalog/ec.config.mjs
@@ -0,0 +1,20 @@
+import { defineEcConfig } from 'astro-expressive-code';
+
+// Expressive Code configuration lives in this dedicated file (rather than inline
+// in astro.config.mjs) because it contains non-serializable options such as the
+// `themeCssSelector` function. Astro's `<Code>` component (used on the print
+// pages) requires Expressive Code options coming from the Astro config to be
+// JSON-serializable, so functions must be defined here instead.
+//
+// `useDarkModeMediaQuery: false` + `themeCssSelector` make code blocks follow
+// EventCatalog's own `data-theme` toggle instead of the OS `prefers-color-scheme`
+// media query, so they stay readable when the catalog theme and the OS
+// preference disagree (see issue #2607).
+export default defineEcConfig({
+  themes: ['github-light', 'github-dark'],
+  useDarkModeMediaQuery: false,
+  themeCssSelector: (theme) => `[data-theme='${theme.type}']`,
+  defaultProps: {
+    wrap: true,
+  },
+});
diff --git a/eventcatalog/global.d.ts b/packages/core/eventcatalog/global.d.ts
similarity index 100%
rename from eventcatalog/global.d.ts
rename to packages/core/eventcatalog/global.d.ts
diff --git a/eventcatalog/integrations/ecstudio-watcher.mjs b/packages/core/eventcatalog/integrations/ecstudio-watcher.mjs
similarity index 96%
rename from eventcatalog/integrations/ecstudio-watcher.mjs
rename to packages/core/eventcatalog/integrations/ecstudio-watcher.mjs
index 94aa28f0f..6c17cca42 100644
--- a/eventcatalog/integrations/ecstudio-watcher.mjs
+++ b/packages/core/eventcatalog/integrations/ecstudio-watcher.mjs
@@ -55,7 +55,7 @@ export default function ecstudioWatcher() {
         // Also add the root directory to watch for new files
         server.watcher.add(rootDir);
         
-        console.log('Set up dynamic .ecstudio file watcher with content refresh');
+        // console.log('Set up dynamic .ecstudio file watcher with content refresh');
       },
     },
   };
diff --git a/packages/core/eventcatalog/public/agents/anthropic-dark.svg b/packages/core/eventcatalog/public/agents/anthropic-dark.svg
new file mode 100644
index 000000000..09d2f13f6
--- /dev/null
+++ b/packages/core/eventcatalog/public/agents/anthropic-dark.svg
@@ -0,0 +1 @@
+<svg fill="#ffff" fill-rule="evenodd" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Anthropic</title><path d="M13.827 3.52h3.603L24 20h-3.603l-6.57-16.48zm-7.258 0h3.767L16.906 20h-3.674l-1.343-3.461H5.017l-1.344 3.46H0L6.57 3.522zm4.132 9.959L8.453 7.687 6.205 13.48H10.7z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/agents/anthropic-light.svg b/packages/core/eventcatalog/public/agents/anthropic-light.svg
new file mode 100644
index 000000000..e19a838ad
--- /dev/null
+++ b/packages/core/eventcatalog/public/agents/anthropic-light.svg
@@ -0,0 +1 @@
+<svg fill="#000" fill-rule="evenodd" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Anthropic</title><path d="M13.827 3.52h3.603L24 20h-3.603l-6.57-16.48zm-7.258 0h3.767L16.906 20h-3.674l-1.343-3.461H5.017l-1.344 3.46H0L6.57 3.522zm4.132 9.959L8.453 7.687 6.205 13.48H10.7z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/agents/openai-dark.svg b/packages/core/eventcatalog/public/agents/openai-dark.svg
new file mode 100644
index 000000000..b6d542d09
--- /dev/null
+++ b/packages/core/eventcatalog/public/agents/openai-dark.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="260" preserveAspectRatio="xMidYMid" viewBox="0 0 256 260"><path fill="#fff" d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/agents/openai-light.svg b/packages/core/eventcatalog/public/agents/openai-light.svg
new file mode 100644
index 000000000..2ebab679f
--- /dev/null
+++ b/packages/core/eventcatalog/public/agents/openai-light.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="260" preserveAspectRatio="xMidYMid" viewBox="0 0 256 260"><path d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/agents/openai.svg b/packages/core/eventcatalog/public/agents/openai.svg
new file mode 100644
index 000000000..b6d542d09
--- /dev/null
+++ b/packages/core/eventcatalog/public/agents/openai.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="260" preserveAspectRatio="xMidYMid" viewBox="0 0 256 260"><path fill="#fff" d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/android-chrome-192x192.png b/packages/core/eventcatalog/public/android-chrome-192x192.png
new file mode 100644
index 000000000..b873f82a0
Binary files /dev/null and b/packages/core/eventcatalog/public/android-chrome-192x192.png differ
diff --git a/packages/core/eventcatalog/public/android-chrome-512x512.png b/packages/core/eventcatalog/public/android-chrome-512x512.png
new file mode 100644
index 000000000..376cd2de6
Binary files /dev/null and b/packages/core/eventcatalog/public/android-chrome-512x512.png differ
diff --git a/packages/core/eventcatalog/public/apple-touch-icon.png b/packages/core/eventcatalog/public/apple-touch-icon.png
new file mode 100644
index 000000000..9e147031c
Binary files /dev/null and b/packages/core/eventcatalog/public/apple-touch-icon.png differ
diff --git a/packages/core/eventcatalog/public/events/eventbridge.svg b/packages/core/eventcatalog/public/events/eventbridge.svg
new file mode 100644
index 000000000..469a4d346
--- /dev/null
+++ b/packages/core/eventcatalog/public/events/eventbridge.svg
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="80px" height="80px" viewBox="0 0 80 80" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <title>Icon-Architecture/64/Arch_Amazon-EventBridge_64</title>
+    <defs>
+        <linearGradient x1="0%" y1="100%" x2="100%" y2="0%" id="linearGradient-1">
+            <stop stop-color="#B0084D" offset="0%"></stop>
+            <stop stop-color="#FF4F8B" offset="100%"></stop>
+        </linearGradient>
+    </defs>
+    <g id="Icon-Architecture/64/Arch_Amazon-EventBridge_64" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="Icon-Architecture-BG/64/Application-Integration" fill="url(#linearGradient-1)">
+            <rect id="Rectangle" x="0" y="0" width="80" height="80"></rect>
+        </g>
+        <path d="M53.656744,66 C51.5137882,66 49.7695913,64.247 49.7695913,62.091 C49.7695913,59.935 51.5137882,58.182 53.656744,58.182 C55.7996998,58.182 57.5438968,59.935 57.5438968,62.091 C57.5438968,64.247 55.7996998,66 53.656744,66 L53.656744,66 Z M45.1326526,49 L34.7977386,49 L29.6297845,40 L34.7977386,31 L45.1326526,31 L50.2996124,40 L45.1326526,49 Z M27.6210741,21.818 C25.4781184,21.818 23.7339214,20.065 23.7339214,17.909 C23.7339214,15.753 25.4781184,14 27.6210741,14 C29.7650244,14 31.5092213,15.753 31.5092213,17.909 C31.5092213,20.065 29.7650244,21.818 27.6210741,21.818 L27.6210741,21.818 Z M53.656744,56.182 C52.918891,56.182 52.214848,56.325 51.5635088,56.576 L47.3402451,49.41 L47.117497,49.543 L52.3093171,40.5 C52.4863222,40.19 52.4863222,39.81 52.3093171,39.5 L46.5675877,29.5 C46.3895881,29.19 46.0614325,29 45.7064278,29 L35.2581509,29 L35.2989218,28.976 L31.4266852,22.404 C32.691576,21.32 33.4980434,19.708 33.4980434,17.909 C33.4980434,14.651 30.8618597,12 27.6210741,12 C24.381283,12 21.7450993,14.651 21.7450993,17.909 C21.7450993,21.167 24.381283,23.818 27.6210741,23.818 C28.3599216,23.818 29.0639646,23.675 29.7153038,23.424 L33.3299879,29.557 L27.6200797,39.5 C27.4430746,39.81 27.4430746,40.19 27.6200797,40.5 L33.3628035,50.5 C33.5408031,50.81 33.8689587,51 34.2239635,51 L45.7064278,51 C45.7889639,51 45.8695112,50.987 45.9470752,50.968 L49.8521274,57.596 C48.5862421,58.68 47.7807692,60.292 47.7807692,62.091 C47.7807692,65.349 50.4159585,68 53.656744,68 C56.8975296,68 59.5327189,65.349 59.5327189,62.091 C59.5327189,58.833 56.8975296,56.182 53.656744,56.182 L53.656744,56.182 Z M59.5844283,32.104 C57.4414725,32.104 55.6982699,30.351 55.6982699,28.195 C55.6982699,26.039 57.4414725,24.286 59.5844283,24.286 C61.7273841,24.286 63.471581,26.039 63.471581,28.195 C63.471581,30.351 61.7273841,32.104 59.5844283,32.104 L59.5844283,32.104 Z M66.8665003,39.5 L63.091716,32.925 C64.5266511,31.846 65.4604031,30.13 65.4604031,28.195 C65.4604031,24.937 62.8252138,22.286 59.5844283,22.286 C58.7600615,22.286 57.9744768,22.459 57.2614841,22.77 L54.1837819,17.409 C54.0067767,17.1 53.6776267,16.909 53.3226219,16.909 L40.9949082,16.909 L40.9949082,18.909 L52.7488468,18.909 L55.5958456,23.869 C54.4383511,24.949 53.7094478,26.486 53.7094478,28.195 C53.7094478,31.453 56.3446371,34.104 59.5844283,34.104 C60.1880358,34.104 60.771755,34.011 61.3206699,33.84 L64.85779,40 L59.8917013,48.648 L61.6140212,49.648 L66.8665003,40.5 C67.0444999,40.19 67.0444999,39.81 66.8665003,39.5 L66.8665003,39.5 Z M21.229,55.247 C19.0850498,55.247 17.3408528,53.493 17.3408528,51.338 C17.3408528,49.182 19.0850498,47.429 21.229,47.429 C23.3719558,47.429 25.1161527,49.182 25.1161527,51.338 C25.1161527,53.493 23.3719558,55.247 21.229,55.247 L21.229,55.247 Z M24.4767464,56.258 C26.0588544,55.198 27.1049748,53.389 27.1049748,51.338 C27.1049748,48.08 24.4687911,45.429 21.229,45.429 C20.2902759,45.429 19.4062445,45.657 18.618671,46.052 L15.1432044,40 L20.9018387,29.971 L19.1785244,28.971 L13.1334997,39.5 C12.9555001,39.81 12.9555001,40.19 13.1334997,40.5 L17.0047419,47.24 C15.9834817,48.304 15.3520307,49.747 15.3520307,51.338 C15.3520307,54.596 17.9882144,57.247 21.229,57.247 C21.7172558,57.247 22.189601,57.18 22.6440469,57.066 L25.8162181,62.591 C25.9942177,62.9 26.3223733,63.091 26.6773781,63.091 L39.0060862,63.091 L39.0060862,61.091 L27.2511532,61.091 L24.4767464,56.258 Z" id="Amazon-EventBridge_Icon_64_Squid" fill="#FFFFFF"></path>
+    </g>
+</svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/favicon-16x16.png b/packages/core/eventcatalog/public/favicon-16x16.png
new file mode 100644
index 000000000..c8975bf4a
Binary files /dev/null and b/packages/core/eventcatalog/public/favicon-16x16.png differ
diff --git a/packages/core/eventcatalog/public/favicon-32x32.png b/packages/core/eventcatalog/public/favicon-32x32.png
new file mode 100644
index 000000000..ad0408c2f
Binary files /dev/null and b/packages/core/eventcatalog/public/favicon-32x32.png differ
diff --git a/packages/core/eventcatalog/public/favicon-48x48.png b/packages/core/eventcatalog/public/favicon-48x48.png
new file mode 100644
index 000000000..8ba87c437
Binary files /dev/null and b/packages/core/eventcatalog/public/favicon-48x48.png differ
diff --git a/packages/core/eventcatalog/public/favicon-96x96.png b/packages/core/eventcatalog/public/favicon-96x96.png
new file mode 100644
index 000000000..a69b8cf46
Binary files /dev/null and b/packages/core/eventcatalog/public/favicon-96x96.png differ
diff --git a/packages/core/eventcatalog/public/favicon.ico b/packages/core/eventcatalog/public/favicon.ico
new file mode 100644
index 000000000..32821829b
Binary files /dev/null and b/packages/core/eventcatalog/public/favicon.ico differ
diff --git a/packages/core/eventcatalog/public/favicon.svg b/packages/core/eventcatalog/public/favicon.svg
new file mode 100644
index 000000000..4d29863b1
--- /dev/null
+++ b/packages/core/eventcatalog/public/favicon.svg
@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="58 54 1133 1133" role="img" aria-labelledby="t">
+<title id="t">Reading cat logo</title>
+<style>
+  path { fill: #000; }
+  @media (prefers-color-scheme: dark) { path { fill: #fff; } }
+</style>
+<path fill-rule="evenodd" d="M 445 55 c -174.6 0.5 -188.1 0.7 -196.5 2.3 -20.7 4.1 -35.3 8.5 -51 15.3 -66.7 28.8 -114.7 86.9 -130.3 157.9 l -2.6 12 -0.4 371 c -0.2 261 0 373.8 0.8 380.5 4.6 40.7 21.8 79.6 49.8 113 36.8 43.9 89.5 72.4 144.2 77.9 5.9 0.6 148.2 1.1 372.5 1.3 345.2 0.3 363.5 0.2 373 -1.5 32.1 -5.7 58.7 -16.4 85.5 -34.2 53.2 -35.3 89.1 -93.6 96 -156 0.8 -7.2 1 -114.8 0.8 -381.5 l -0.3 -371.5 -2.2 -10.4 c -7.7 -35.9 -18.8 -61.1 -38.9 -88.2 -9.5 -12.8 -30.7 -34.1 -43.4 -43.5 -34.4 -25.6 -73.7 -40.9 -113.5 -44.3 -12.5 -1.1 -182.7 -1.1 -543.5 -0.1 z m -26.3 152.5 c 30.7 11.6 86.7 67 122.9 121.6 l 8.4 12.6 9.7 -2.3 c 13.3 -3.3 30.3 -6.1 44.8 -7.5 15.1 -1.5 51.8 -0.6 67.5 1.6 10.1 1.4 37.1 6.8 40.5 8.1 0.7 0.3 3.6 -3.4 7.1 -8.8 18.3 -29.1 37.9 -53.5 64.7 -80.7 31.8 -32.2 53.3 -47 68.5 -47.1 10.5 -0 16.2 4.1 22.3 16.1 11.6 23 17.3 80.8 15 153.1 l -1 33.7 6 14.7 c 3.2 8 7.8 20.4 10 27.5 2.3 7.1 4.5 12.9 4.9 12.9 0.4 -0 5 -1.5 10.1 -3.4 29.8 -10.8 61.4 -20.5 89.6 -27.5 20 -5.1 21.5 -5.1 25.9 -0.7 2.9 2.9 3.4 4.1 3.4 7.9 0 3.4 -0.6 5.3 -2.5 7.5 -2.9 3.5 -4.7 4.3 -18 7.7 -23.9 6.3 -83.7 25.2 -103 32.5 -2 0.8 -2 1.2 -1 10.6 0.5 5.3 1.5 9.9 2 10 0.6 0.2 16.8 2.4 36 4.9 69.6 9.1 85.9 11.5 89.4 13.3 10.1 5.1 7.6 20.4 -3.6 21.9 -3.7 0.5 -26.4 -2.1 -63.3 -7.2 -18.4 -2.6 -56.7 -7.5 -58 -7.5 -0.4 -0 -1 0.8 -1.2 1.8 -0.4 1.4 -2.9 2.3 -11.4 4.1 -50.2 10.3 -130.1 33.1 -167.9 47.8 -35.1 13.6 -69.4 33.4 -96.1 55.6 -6.6 5.4 -10.1 7.7 -10.9 7.1 -0.7 -0.5 -5.8 -4.6 -11.5 -9.2 -25 -20.2 -55.1 -37.5 -88.5 -50.7 -39.3 -15.6 -111.9 -36.5 -170.7 -49.1 -15.1 -3.2 -17.8 -4.1 -17.8 -5.6 0 -2.4 0.4 -2.4 -35 2.2 -16.8 2.2 -42.6 5.7 -57.5 7.6 -14.8 2 -28.8 3.3 -31 3 -5.9 -0.7 -9.5 -5.1 -9.5 -11.5 0 -5.7 2.4 -9.4 7.3 -11 3.2 -1.1 62.2 -9.4 103.2 -14.6 11.6 -1.5 21.3 -3 21.7 -3.3 0.3 -0.4 0.9 -5 1.3 -10.3 l 0.7 -9.6 -30.3 -10.1 c -24.9 -8.3 -73.2 -22.8 -85.2 -25.6 -1.5 -0.4 -4.1 -1.9 -5.8 -3.4 -2.6 -2.3 -3.3 -3.8 -3.7 -8 -0.4 -4.7 -0.2 -5.4 2.5 -8.1 1.7 -1.6 4.3 -3.3 5.8 -3.7 5.8 -1.4 46 9.3 88.5 23.7 16.2 5.5 30.3 10.3 31.2 10.6 1 0.3 2 -0.1 2.2 -0.8 4.6 -14.9 9 -27.2 14 -39.4 l 6.2 -15 -1 -32.5 c -1.5 -48.5 0.9 -93.8 6.4 -122.4 5 -25.8 12 -40.4 21.9 -45.6 5.4 -2.9 15.3 -2.6 23.8 0.5 z m -67.6 364.4 c 81.9 16.7 161.5 40.4 199.3 59.3 11.7 5.9 29.8 16.7 34.1 20.3 l 3 2.6 -9.5 -0.4 c -8.7 -0.4 -15.5 -2.1 -78.5 -19.7 -37.9 -10.6 -76 -21.2 -84.5 -23.5 -56.6 -15.7 -123.4 -34.6 -123.8 -35 -0.6 -0.6 13.5 -2.8 37.3 -5.8 6.4 -0.8 8.6 -0.6 22.6 2.2 z m 589.5 -0.4 c 10.4 1.4 20.4 2.8 22.3 3.2 3.4 0.6 -40.5 13.5 -170.9 50.2 -20.1 5.7 -42.6 12 -50 14.1 -50.1 14.2 -53.5 15 -60.8 15 -4 -0 -7.2 -0.3 -7.2 -0.8 0 -2.1 28.9 -19.2 45.8 -27.1 36.1 -16.7 110.6 -38.3 193.2 -55.9 6.6 -1.4 7.1 -1.4 27.6 1.3 z m -672.2 33.1 c 13.2 3.6 31.1 8.5 39.6 10.9 8.5 2.4 35.3 9.8 59.5 16.4 52.5 14.3 120.5 33 167.5 46.1 22.9 6.3 23.5 6.6 24.9 9.6 0.8 1.8 1.1 45.6 1.1 162.2 0 175.7 0.4 164.2 -5.9 164.2 -1.5 -0 -12.4 -2.7 -24.2 -6.1 -20.6 -5.8 -66.3 -18.6 -188.9 -52.7 -31.6 -8.8 -63.1 -17.5 -70 -19.2 -13 -3.3 -16.3 -4.8 -17.9 -7.8 -1.1 -2.1 -7.2 -104.7 -15.6 -262.7 -1.3 -25.9 -2.7 -50.5 -3.1 -54.7 -0.6 -7.3 -0.5 -7.8 2 -10.2 1.4 -1.5 3.5 -2.6 4.7 -2.6 1.2 -0 13 3 26.3 6.6 z m 748.1 -5.6 c 3.9 1.5 4.4 4.2 3.4 19.5 -0.8 12.4 -4.2 70.9 -15 256 -2.6 46 -3.3 53.3 -4.8 55.5 -1.9 2.6 1.3 1.6 -78.6 23.9 -9.9 2.8 -34.2 9.6 -54 15.1 -19.8 5.6 -50.4 14.1 -68 19 -17.6 4.9 -45.7 12.8 -62.5 17.5 -16.7 4.7 -31.7 8.5 -33.2 8.5 -6.3 -0 -5.9 11.3 -5.6 -165.1 0.2 -88.2 0.7 -161.2 1.2 -162.1 0.9 -1.9 4.6 -3.1 32.6 -10.7 10.2 -2.8 25.9 -7.1 35 -9.6 9.1 -2.5 32 -8.9 51 -14.1 47.4 -13.1 124.2 -34.5 168.5 -46.9 14.3 -4 26.3 -7.4 26.7 -7.4 0.4 -0.1 1.8 0.3 3.3 0.9 z m -351.7 95.3 c 0.9 0.7 1.2 35.1 1.2 166.7 l 0 165.9 -2.2 1.3 c -1.8 1 -10.2 1.3 -35.1 1.3 -31.4 -0 -32.9 -0.1 -34.3 -1.9 -2.1 -2.9 -2.1 -330.7 0 -332.8 1.1 -1.2 7.6 -1.4 35.2 -1.4 18.7 0.1 34.5 0.5 35.2 0.9 z"/>
+</svg>
diff --git a/packages/core/eventcatalog/public/icons/agent/anthropic-dark.svg b/packages/core/eventcatalog/public/icons/agent/anthropic-dark.svg
new file mode 100644
index 000000000..09d2f13f6
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agent/anthropic-dark.svg
@@ -0,0 +1 @@
+<svg fill="#ffff" fill-rule="evenodd" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Anthropic</title><path d="M13.827 3.52h3.603L24 20h-3.603l-6.57-16.48zm-7.258 0h3.767L16.906 20h-3.674l-1.343-3.461H5.017l-1.344 3.46H0L6.57 3.522zm4.132 9.959L8.453 7.687 6.205 13.48H10.7z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agent/anthropic-light.svg b/packages/core/eventcatalog/public/icons/agent/anthropic-light.svg
new file mode 100644
index 000000000..e19a838ad
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agent/anthropic-light.svg
@@ -0,0 +1 @@
+<svg fill="#000" fill-rule="evenodd" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Anthropic</title><path d="M13.827 3.52h3.603L24 20h-3.603l-6.57-16.48zm-7.258 0h3.767L16.906 20h-3.674l-1.343-3.461H5.017l-1.344 3.46H0L6.57 3.522zm4.132 9.959L8.453 7.687 6.205 13.48H10.7z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agent/anthropic.svg b/packages/core/eventcatalog/public/icons/agent/anthropic.svg
new file mode 100644
index 000000000..09d2f13f6
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agent/anthropic.svg
@@ -0,0 +1 @@
+<svg fill="#ffff" fill-rule="evenodd" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Anthropic</title><path d="M13.827 3.52h3.603L24 20h-3.603l-6.57-16.48zm-7.258 0h3.767L16.906 20h-3.674l-1.343-3.461H5.017l-1.344 3.46H0L6.57 3.522zm4.132 9.959L8.453 7.687 6.205 13.48H10.7z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agent/gemini.svg b/packages/core/eventcatalog/public/icons/agent/gemini.svg
new file mode 100644
index 000000000..87cce066a
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agent/gemini.svg
@@ -0,0 +1 @@
+<svg viewBox="0 0 296 298" xmlns="http://www.w3.org/2000/svg" width="296" height="298" fill="none"><mask id="gemini__a" width="296" height="298" x="0" y="0" maskUnits="userSpaceOnUse" style="mask-type:alpha"><path fill="#3186FF" d="M141.201 4.886c2.282-6.17 11.042-6.071 13.184.148l5.985 17.37a184.004 184.004 0 0 0 111.257 113.049l19.304 6.997c6.143 2.227 6.156 10.91.02 13.155l-19.35 7.082a184.001 184.001 0 0 0-109.495 109.385l-7.573 20.629c-2.241 6.105-10.869 6.121-13.133.025l-7.908-21.296a184 184 0 0 0-109.02-108.658l-19.698-7.239c-6.102-2.243-6.118-10.867-.025-13.132l20.083-7.467A183.998 183.998 0 0 0 133.291 26.28l7.91-21.394Z"/></mask><g mask="url(#gemini__a)"><g filter="url(#gemini__b)"><ellipse cx="163" cy="149" fill="#3689FF" rx="196" ry="159"/></g><g filter="url(#gemini__c)"><ellipse cx="33.5" cy="142.5" fill="#F6C013" rx="68.5" ry="72.5"/></g><g filter="url(#gemini__d)"><ellipse cx="19.5" cy="148.5" fill="#F6C013" rx="68.5" ry="72.5"/></g><g filter="url(#gemini__e)"><path fill="#FA4340" d="M194 10.5C172 82.5 65.5 134.333 22.5 135L144-66l50 76.5Z"/></g><g filter="url(#gemini__f)"><path fill="#FA4340" d="M190.5-12.5C168.5 59.5 62 111.333 19 112L140.5-89l50 76.5Z"/></g><g filter="url(#gemini__g)"><path fill="#14BB69" d="M194.5 279.5C172.5 207.5 66 155.667 23 155l121.5 201 50-76.5Z"/></g><g filter="url(#gemini__h)"><path fill="#14BB69" d="M196.5 320.5C174.5 248.5 68 196.667 25 196l121.5 201 50-76.5Z"/></g></g><defs><filter id="gemini__b" width="464" height="390" x="-69" y="-46" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="18"/></filter><filter id="gemini__c" width="265" height="273" x="-99" y="6" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="32"/></filter><filter id="gemini__d" width="265" height="273" x="-113" y="12" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="32"/></filter><filter id="gemini__e" width="299.5" height="329" x="-41.5" y="-130" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="32"/></filter><filter id="gemini__f" width="299.5" height="329" x="-45" y="-153" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="32"/></filter><filter id="gemini__g" width="299.5" height="329" x="-41" y="91" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="32"/></filter><filter id="gemini__h" width="299.5" height="329" x="-39" y="132" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="32"/></filter></defs></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agent/openai-dark.svg b/packages/core/eventcatalog/public/icons/agent/openai-dark.svg
new file mode 100644
index 000000000..b6d542d09
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agent/openai-dark.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="260" preserveAspectRatio="xMidYMid" viewBox="0 0 256 260"><path fill="#fff" d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agent/openai-light.svg b/packages/core/eventcatalog/public/icons/agent/openai-light.svg
new file mode 100644
index 000000000..2ebab679f
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agent/openai-light.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="260" preserveAspectRatio="xMidYMid" viewBox="0 0 256 260"><path d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agent/openai.svg b/packages/core/eventcatalog/public/icons/agent/openai.svg
new file mode 100644
index 000000000..b6d542d09
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agent/openai.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="260" preserveAspectRatio="xMidYMid" viewBox="0 0 256 260"><path fill="#fff" d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agents/anthropic-dark.svg b/packages/core/eventcatalog/public/icons/agents/anthropic-dark.svg
new file mode 100644
index 000000000..09d2f13f6
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agents/anthropic-dark.svg
@@ -0,0 +1 @@
+<svg fill="#ffff" fill-rule="evenodd" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Anthropic</title><path d="M13.827 3.52h3.603L24 20h-3.603l-6.57-16.48zm-7.258 0h3.767L16.906 20h-3.674l-1.343-3.461H5.017l-1.344 3.46H0L6.57 3.522zm4.132 9.959L8.453 7.687 6.205 13.48H10.7z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agents/anthropic-light.svg b/packages/core/eventcatalog/public/icons/agents/anthropic-light.svg
new file mode 100644
index 000000000..e19a838ad
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agents/anthropic-light.svg
@@ -0,0 +1 @@
+<svg fill="#000" fill-rule="evenodd" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Anthropic</title><path d="M13.827 3.52h3.603L24 20h-3.603l-6.57-16.48zm-7.258 0h3.767L16.906 20h-3.674l-1.343-3.461H5.017l-1.344 3.46H0L6.57 3.522zm4.132 9.959L8.453 7.687 6.205 13.48H10.7z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agents/anthropic.svg b/packages/core/eventcatalog/public/icons/agents/anthropic.svg
new file mode 100644
index 000000000..09d2f13f6
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agents/anthropic.svg
@@ -0,0 +1 @@
+<svg fill="#ffff" fill-rule="evenodd" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Anthropic</title><path d="M13.827 3.52h3.603L24 20h-3.603l-6.57-16.48zm-7.258 0h3.767L16.906 20h-3.674l-1.343-3.461H5.017l-1.344 3.46H0L6.57 3.522zm4.132 9.959L8.453 7.687 6.205 13.48H10.7z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agents/gemini.svg b/packages/core/eventcatalog/public/icons/agents/gemini.svg
new file mode 100644
index 000000000..87cce066a
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agents/gemini.svg
@@ -0,0 +1 @@
+<svg viewBox="0 0 296 298" xmlns="http://www.w3.org/2000/svg" width="296" height="298" fill="none"><mask id="gemini__a" width="296" height="298" x="0" y="0" maskUnits="userSpaceOnUse" style="mask-type:alpha"><path fill="#3186FF" d="M141.201 4.886c2.282-6.17 11.042-6.071 13.184.148l5.985 17.37a184.004 184.004 0 0 0 111.257 113.049l19.304 6.997c6.143 2.227 6.156 10.91.02 13.155l-19.35 7.082a184.001 184.001 0 0 0-109.495 109.385l-7.573 20.629c-2.241 6.105-10.869 6.121-13.133.025l-7.908-21.296a184 184 0 0 0-109.02-108.658l-19.698-7.239c-6.102-2.243-6.118-10.867-.025-13.132l20.083-7.467A183.998 183.998 0 0 0 133.291 26.28l7.91-21.394Z"/></mask><g mask="url(#gemini__a)"><g filter="url(#gemini__b)"><ellipse cx="163" cy="149" fill="#3689FF" rx="196" ry="159"/></g><g filter="url(#gemini__c)"><ellipse cx="33.5" cy="142.5" fill="#F6C013" rx="68.5" ry="72.5"/></g><g filter="url(#gemini__d)"><ellipse cx="19.5" cy="148.5" fill="#F6C013" rx="68.5" ry="72.5"/></g><g filter="url(#gemini__e)"><path fill="#FA4340" d="M194 10.5C172 82.5 65.5 134.333 22.5 135L144-66l50 76.5Z"/></g><g filter="url(#gemini__f)"><path fill="#FA4340" d="M190.5-12.5C168.5 59.5 62 111.333 19 112L140.5-89l50 76.5Z"/></g><g filter="url(#gemini__g)"><path fill="#14BB69" d="M194.5 279.5C172.5 207.5 66 155.667 23 155l121.5 201 50-76.5Z"/></g><g filter="url(#gemini__h)"><path fill="#14BB69" d="M196.5 320.5C174.5 248.5 68 196.667 25 196l121.5 201 50-76.5Z"/></g></g><defs><filter id="gemini__b" width="464" height="390" x="-69" y="-46" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="18"/></filter><filter id="gemini__c" width="265" height="273" x="-99" y="6" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="32"/></filter><filter id="gemini__d" width="265" height="273" x="-113" y="12" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="32"/></filter><filter id="gemini__e" width="299.5" height="329" x="-41.5" y="-130" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="32"/></filter><filter id="gemini__f" width="299.5" height="329" x="-45" y="-153" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="32"/></filter><filter id="gemini__g" width="299.5" height="329" x="-41" y="91" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="32"/></filter><filter id="gemini__h" width="299.5" height="329" x="-39" y="132" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_69_17998" stdDeviation="32"/></filter></defs></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agents/openai-dark.svg b/packages/core/eventcatalog/public/icons/agents/openai-dark.svg
new file mode 100644
index 000000000..b6d542d09
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agents/openai-dark.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="260" preserveAspectRatio="xMidYMid" viewBox="0 0 256 260"><path fill="#fff" d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agents/openai-light.svg b/packages/core/eventcatalog/public/icons/agents/openai-light.svg
new file mode 100644
index 000000000..2ebab679f
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agents/openai-light.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="260" preserveAspectRatio="xMidYMid" viewBox="0 0 256 260"><path d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/agents/openai.svg b/packages/core/eventcatalog/public/icons/agents/openai.svg
new file mode 100644
index 000000000..b6d542d09
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/agents/openai.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="260" preserveAspectRatio="xMidYMid" viewBox="0 0 256 260"><path fill="#fff" d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/analytics/clickhouse.svg b/packages/core/eventcatalog/public/icons/analytics/clickhouse.svg
new file mode 100644
index 000000000..95c0bef80
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/analytics/clickhouse.svg
@@ -0,0 +1 @@
+<svg fill="#FFCC01" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>ClickHouse</title><path d="M21.333 10H24v4h-2.667ZM16 1.335h2.667v21.33H16Zm-5.333 0h2.666v21.33h-2.666ZM0 22.665V1.335h2.667v21.33zm5.333-21.33H8v21.33H5.333Z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/analytics/databricks.svg b/packages/core/eventcatalog/public/icons/analytics/databricks.svg
new file mode 100644
index 000000000..d67b17058
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/analytics/databricks.svg
@@ -0,0 +1 @@
+<svg fill="#FF3621" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Databricks</title><path d="M.95 14.184L12 20.403l9.919-5.55v2.21L12 22.662l-10.484-5.96-.565.308v.77L12 24l11.05-6.218v-4.317l-.515-.309L12 19.118l-9.867-5.653v-2.21L12 16.805l11.05-6.218V6.32l-.515-.308L12 11.974 2.647 6.681 12 1.388l7.76 4.368.668-.411v-.566L12 0 .95 6.27v.72L12 13.207l9.919-5.55v2.26L12 15.52 1.516 9.56l-.565.308Z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/analytics/dbt.png b/packages/core/eventcatalog/public/icons/analytics/dbt.png
new file mode 100644
index 000000000..e296ed37e
Binary files /dev/null and b/packages/core/eventcatalog/public/icons/analytics/dbt.png differ
diff --git a/packages/core/eventcatalog/public/icons/analytics/looker.svg b/packages/core/eventcatalog/public/icons/analytics/looker.svg
new file mode 100644
index 000000000..31db1e5ca
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/analytics/looker.svg
@@ -0,0 +1 @@
+<svg fill="#4285F4" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Looker</title><path d="M11.9475 0c-1.1598.0021-2.0982.944-2.096 2.1038a2.1 2.1 0 00.356 1.166l.895-.8959a.884.884 0 11.565.564l-.895.895c.9593.6478 2.2621.3953 2.91-.564.6478-.9593.3953-2.262-.564-2.91A2.096 2.096 0 0011.9475 0zm-.835 6.1128a3.2629 3.2629 0 00-.653-1.965l-1.164 1.162a1.667 1.667 0 01-.318 2.012l.632 1.5449a3.2819 3.2819 0 001.503-2.754zm-3.2499 1.666h-.03c-.9217.0009-1.6697-.7455-1.6707-1.6673-.001-.9217.7454-1.6697 1.6672-1.6707a1.669 1.669 0 01.9195.275l1.152-1.152c-1.4069-1.141-3.4724-.9257-4.6135.4811s-.9257 3.4723.481 4.6135a3.2799 3.2799 0 002.7275.6652l-.633-1.5439v-.001zm4.1279 1.3359c-.728 0-1.452.106-2.15.315l.922 2.2519c2.6872-.6819 5.4184.9438 6.1002 3.631.6818 2.6873-.9439 5.4184-3.6311 6.1002s-5.4184-.9439-6.1002-3.631c-.5682-2.2394.4655-4.5774 2.5041-5.6643l-.91-2.2449c-3.6908 1.808-5.2173 6.2657-3.4093 9.9567l.0005.001c1.808 3.6909 6.2657 5.2173 9.9567 3.4093l.001-.0005c3.6913-1.8071 5.2187-6.2645 3.4116-9.9558a7.4417 7.4417 0 00-6.6865-4.1696h-.008l-.001.001z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/analytics/metabase.svg b/packages/core/eventcatalog/public/icons/analytics/metabase.svg
new file mode 100644
index 000000000..02c45b337
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/analytics/metabase.svg
@@ -0,0 +1 @@
+<svg fill="#509EE3" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Metabase</title><path d="M5.385 6.136c0 .807-.644 1.461-1.438 1.461s-1.438-.654-1.438-1.461.644-1.461 1.438-1.461 1.438.654 1.438 1.461zm-1.438 2.63c-.794 0-1.438.654-1.438 1.461s.644 1.461 1.438 1.461 1.438-.654 1.438-1.461-.644-1.461-1.438-1.461zm5.465-2.63c0 .807-.644 1.461-1.438 1.461s-1.438-.654-1.438-1.461.644-1.461 1.438-1.461 1.438.654 1.438 1.461zm-.35 0c0-.613-.488-1.111-1.088-1.111s-1.088.499-1.088 1.111.488 1.111 1.088 1.111 1.088-.498 1.088-1.111zm-1.088 5.592c.794 0 1.438-.654 1.438-1.461s-.644-1.461-1.438-1.461-1.438.654-1.438 1.461.643 1.461 1.438 1.461zm5.464-5.592c0 .807-.644 1.461-1.438 1.461s-1.438-.654-1.438-1.461.644-1.461 1.438-1.461 1.438.654 1.438 1.461zm-.35 0c0-.613-.488-1.111-1.088-1.111s-1.088.498-1.088 1.111S11.4 7.247 12 7.247s1.088-.498 1.088-1.111zm.35-4.675c0 .807-.644 1.461-1.438 1.461s-1.438-.654-1.438-1.461S11.206 0 12 0s1.438.654 1.438 1.461zm-.35 0C13.088.848 12.6.35 12 .35s-1.088.498-1.088 1.111S11.4 2.572 12 2.572s1.088-.498 1.088-1.111zm.35 8.806c0 .807-.644 1.461-1.438 1.461s-1.438-.654-1.438-1.461.644-1.461 1.438-1.461 1.438.654 1.438 1.461zm-.35 0c0-.613-.488-1.111-1.088-1.111s-1.088.498-1.088 1.111.488 1.111 1.088 1.111 1.088-.499 1.088-1.111zm4.376-4.131c0 .807-.644 1.461-1.438 1.461s-1.438-.654-1.438-1.461.644-1.461 1.438-1.461 1.438.654 1.438 1.461zm-.35 0c0-.613-.488-1.111-1.088-1.111s-1.088.498-1.088 1.111.488 1.111 1.088 1.111 1.088-.498 1.088-1.111zm2.939 1.461c.794 0 1.438-.654 1.438-1.461s-.644-1.461-1.438-1.461-1.438.654-1.438 1.461.644 1.461 1.438 1.461zm-4.027 1.209c-.794 0-1.438.654-1.438 1.461s.644 1.461 1.438 1.461 1.438-.654 1.438-1.461-.643-1.461-1.438-1.461zm4.027 0c-.794 0-1.438.654-1.438 1.461s.644 1.461 1.438 1.461 1.438-.654 1.438-1.461-.644-1.461-1.438-1.461zM3.947 12.857a1.45 1.45 0 0 0-1.438 1.461c0 .807.644 1.461 1.438 1.461s1.438-.654 1.438-1.461a1.45 1.45 0 0 0-1.438-1.461zm5.465 1.5c0 .807-.644 1.461-1.438 1.461s-1.438-.654-1.438-1.461.644-1.461 1.438-1.461 1.438.655 1.438 1.461zm-.35 0c0-.613-.488-1.111-1.088-1.111s-1.088.498-1.088 1.111.488 1.111 1.088 1.111 1.088-.498 1.088-1.111zM12 12.896c-.794 0-1.438.654-1.438 1.461s.644 1.461 1.438 1.461 1.438-.654 1.438-1.461-.644-1.461-1.438-1.461zm5.464 1.461c0 .807-.644 1.461-1.438 1.461s-1.438-.654-1.438-1.461.644-1.461 1.438-1.461 1.438.655 1.438 1.461zm-.35 0c0-.613-.488-1.111-1.088-1.111s-1.088.498-1.088 1.111.488 1.111 1.088 1.111 1.088-.498 1.088-1.111zm2.939-1.461c-.794 0-1.438.654-1.438 1.461s.644 1.461 1.438 1.461 1.438-.654 1.438-1.461-.644-1.461-1.438-1.461zM3.947 16.948c-.794 0-1.438.654-1.438 1.461s.644 1.461 1.438 1.461 1.438-.654 1.438-1.461-.644-1.461-1.438-1.461zm5.465 1.5c0 .807-.644 1.461-1.438 1.461s-1.438-.654-1.438-1.461.644-1.461 1.438-1.461 1.438.654 1.438 1.461zm-.35 0c0-.613-.488-1.111-1.088-1.111s-1.088.498-1.088 1.111.488 1.111 1.088 1.111 1.088-.498 1.088-1.111zm4.376 0c0 .807-.644 1.461-1.438 1.461s-1.438-.654-1.438-1.461.644-1.461 1.438-1.461 1.438.654 1.438 1.461zm-.35 0c0-.613-.488-1.111-1.088-1.111s-1.088.498-1.088 1.111.488 1.111 1.088 1.111 1.088-.498 1.088-1.111zm.35 4.091c0 .807-.644 1.461-1.438 1.461s-1.438-.654-1.438-1.461.644-1.461 1.438-1.461 1.438.654 1.438 1.461zm-.35 0c0-.613-.488-1.111-1.088-1.111s-1.088.498-1.088 1.111S11.4 23.65 12 23.65s1.088-.498 1.088-1.111zm4.376-4.091c0 .807-.644 1.461-1.438 1.461s-1.438-.654-1.438-1.461.644-1.461 1.438-1.461 1.438.654 1.438 1.461zm-.35 0c0-.613-.488-1.111-1.088-1.111s-1.088.498-1.088 1.111.488 1.111 1.088 1.111 1.088-.498 1.088-1.111zm2.939-1.461c-.794 0-1.438.654-1.438 1.461s.644 1.461 1.438 1.461 1.438-.654 1.438-1.461-.644-1.461-1.438-1.461z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/asyncapi-black.svg b/packages/core/eventcatalog/public/icons/asyncapi-black.svg
new file mode 100644
index 000000000..8217adbc8
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/asyncapi-black.svg
@@ -0,0 +1,2 @@
+
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 155.51 155.51"><defs><style>.cls-1{fill:"#000"}.cls-2{fill:'#000'}.cls-3{fill:"#000"}.cls-4{fill:"#000";}.cls-5{fill:#fff;}</style><linearGradient id="linear-gradient" x1="133.74" y1="21.76" x2="24.84" y2="130.67" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#2dccfd"/><stop offset="1" stop-color="#ad20e2"/></linearGradient><linearGradient id="linear-gradient-2" x1="6471.36" y1="6969.64" x2="6362.46" y2="7078.54" gradientTransform="translate(7103.38 -6337.62) rotate(90)" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#a829e2"/><stop offset="0.05" stop-color="#a829e2" stop-opacity="0.84"/><stop offset="0.11" stop-color="#a829e2" stop-opacity="0.67"/><stop offset="0.18" stop-color="#a829e2" stop-opacity="0.51"/><stop offset="0.25" stop-color="#a829e2" stop-opacity="0.38"/><stop offset="0.33" stop-color="#a829e2" stop-opacity="0.28"/><stop offset="0.43" stop-color="#a829e2" stop-opacity="0.2"/><stop offset="0.54" stop-color="#a829e2" stop-opacity="0.14"/><stop offset="0.68" stop-color="#a829e2" stop-opacity="0.11"/><stop offset="1" stop-color="#a829e2" stop-opacity="0.1"/></linearGradient><linearGradient id="linear-gradient-3" x1="13419.24" y1="632.02" x2="13310.33" y2="740.92" gradientTransform="translate(13441 765.76) rotate(180)" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#e50e99"/><stop offset="1" stop-color="#a829e2" stop-opacity="0.1"/></linearGradient><linearGradient id="linear-gradient-4" x1="138.74" y1="-7.39" x2="29.84" y2="101.52" gradientTransform="translate(-5 29.16)" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#21d4fd"/><stop offset="0.03" stop-color="#27cdfc" stop-opacity="0.96"/><stop offset="0.23" stop-color="#4e9cf4" stop-opacity="0.7"/><stop offset="0.43" stop-color="#6e73ee" stop-opacity="0.49"/><stop offset="0.61" stop-color="#8753e9" stop-opacity="0.32"/><stop offset="0.77" stop-color="#993ce5" stop-opacity="0.2"/><stop offset="0.9" stop-color="#a42ee3" stop-opacity="0.13"/><stop offset="1" stop-color="#a829e2" stop-opacity="0.1"/></linearGradient></defs><rect class="cls-1" x="8.88" y="8.88" width="137.75" height="137.75" rx="32.58"/><rect class="cls-2" x="8.88" y="8.88" width="137.75" height="137.75" rx="32.58"/><rect class="cls-3" x="8.88" y="8.88" width="137.75" height="137.75" rx="32.58"/><rect class="cls-4" x="8.88" y="8.88" width="137.75" height="137.75" rx="32.58"/><g id="New_lines" data-name="New lines"><polygon class="cls-5" points="53.35 63.21 49.25 68.86 81.27 92.1 81.49 92.26 85.59 86.61 53.57 63.37 53.35 63.21"/><polygon class="cls-5" points="74.27 63.37 74.05 63.21 69.95 68.86 101.97 92.1 102.19 92.26 106.29 86.61 74.27 63.37"/><path class="cls-5" d="M77.78,34.29c-17.35,0-31.48,10.79-31.48,24.06v.27h7v-.27c0-9.42,11-17.08,24.5-17.08s24.51,7.66,24.51,17.08v.27h7v-.27C109.27,45.08,95.14,34.29,77.78,34.29Z"/><path class="cls-5" d="M102.23,97.16c0,9.42-11,17.08-24.51,17.08s-24.5-7.66-24.5-17.08v-.27h-7v.27c0,13.26,14.13,24,31.48,24s31.49-10.79,31.49-24v-.27h-7Z"/></g></svg>
\ No newline at end of file
diff --git a/eventcatalog/public/icons/asyncapi.svg b/packages/core/eventcatalog/public/icons/asyncapi.svg
similarity index 100%
rename from eventcatalog/public/icons/asyncapi.svg
rename to packages/core/eventcatalog/public/icons/asyncapi.svg
diff --git a/eventcatalog/public/icons/avro.svg b/packages/core/eventcatalog/public/icons/avro.svg
similarity index 100%
rename from eventcatalog/public/icons/avro.svg
rename to packages/core/eventcatalog/public/icons/avro.svg
diff --git a/packages/core/eventcatalog/public/icons/azure.svg b/packages/core/eventcatalog/public/icons/azure.svg
new file mode 100644
index 000000000..e059f11b9
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/azure.svg
@@ -0,0 +1,23 @@
+<svg viewBox="0 0 96 96" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="a" x1="-1032.17" x2="-1059.21" y1="145.31" y2="65.43" gradientTransform="matrix(1 0 0 -1 1075 158)" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#114a8b"/>
+      <stop offset="1" stop-color="#0669bc"/>
+    </linearGradient>
+    <linearGradient id="b" x1="-1023.73" x2="-1029.98" y1="108.08" y2="105.97" gradientTransform="matrix(1 0 0 -1 1075 158)" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-opacity=".3"/>
+      <stop offset=".07" stop-opacity=".2"/>
+      <stop offset=".32" stop-opacity=".1"/>
+      <stop offset=".62" stop-opacity=".05"/>
+      <stop offset="1" stop-opacity="0"/>
+    </linearGradient>
+    <linearGradient id="c" x1="-1027.16" x2="-997.48" y1="147.64" y2="68.56" gradientTransform="matrix(1 0 0 -1 1075 158)" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#3ccbf4"/>
+      <stop offset="1" stop-color="#2892df"/>
+    </linearGradient>
+  </defs>
+  <path fill="url(#a)" d="M33.34 6.54h26.04l-27.03 80.1a4.15 4.15 0 0 1-3.94 2.81H8.15a4.14 4.14 0 0 1-3.93-5.47L29.4 9.38a4.15 4.15 0 0 1 3.94-2.83z"/>
+  <path fill="#0078d4" d="M71.17 60.26H29.88a1.91 1.91 0 0 0-1.3 3.31l26.53 24.76a4.17 4.17 0 0 0 2.85 1.13h23.38z"/>
+  <path fill="url(#b)" d="M33.34 6.54a4.12 4.12 0 0 0-3.95 2.88L4.25 83.92a4.14 4.14 0 0 0 3.91 5.54h20.79a4.44 4.44 0 0 0 3.4-2.9l5.02-14.78 17.91 16.7a4.24 4.24 0 0 0 2.67.97h23.29L71.02 60.26H41.24L59.47 6.55z"/>
+  <path fill="url(#c)" d="M66.6 9.36a4.14 4.14 0 0 0-3.93-2.82H33.65a4.15 4.15 0 0 1 3.93 2.82l25.18 74.62a4.15 4.15 0 0 1-3.93 5.48h29.02a4.15 4.15 0 0 0 3.93-5.48z"/>
+</svg>
diff --git a/packages/core/eventcatalog/public/icons/cache/redis.svg b/packages/core/eventcatalog/public/icons/cache/redis.svg
new file mode 100644
index 000000000..61480c931
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/cache/redis.svg
@@ -0,0 +1 @@
+<svg fill="#FF4438" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Redis</title><path d="M22.71 13.145c-1.66 2.092-3.452 4.483-7.038 4.483-3.203 0-4.397-2.825-4.48-5.12.701 1.484 2.073 2.685 4.214 2.63 4.117-.133 6.94-3.852 6.94-7.239 0-4.05-3.022-6.972-8.268-6.972-3.752 0-8.4 1.428-11.455 3.685C2.59 6.937 3.885 9.958 4.35 9.626c2.648-1.904 4.748-3.13 6.784-3.744C8.12 9.244.886 17.05 0 18.425c.1 1.261 1.66 4.648 2.424 4.648.232 0 .431-.133.664-.365a100.49 100.49 0 0 0 5.54-6.765c.222 3.104 1.748 6.898 6.014 6.898 3.819 0 7.604-2.756 9.33-8.965.2-.764-.73-1.361-1.261-.73zm-4.349-5.013c0 1.959-1.926 2.922-3.685 2.922-.941 0-1.664-.247-2.235-.568 1.051-1.592 2.092-3.225 3.21-4.973 1.972.334 2.71 1.43 2.71 2.619z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/cloud/snowflake.svg b/packages/core/eventcatalog/public/icons/cloud/snowflake.svg
new file mode 100644
index 000000000..dae8f5531
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/cloud/snowflake.svg
@@ -0,0 +1 @@
+<svg fill="#29B5E8" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Snowflake</title><path d="M24 3.459c0 .646-.418 1.18-1.141 1.18-.723 0-1.142-.534-1.142-1.18 0-.647.419-1.18 1.142-1.18.723 0 1.141.533 1.141 1.18zm-.228 0c0-.533-.38-.951-.913-.951s-.913.38-.913.95c0 .533.38.952.913.952.57 0 .913-.419.913-.951zm-1.37-.533h.495c.266 0 .456.152.456.38 0 .153-.076.229-.19.305l.19.266v.038h-.266l-.19-.266h-.229v.266h-.266zm.495.228h-.229v.267h.229c.114 0 .152-.038.152-.114.038-.077-.038-.153-.152-.153zM7.602 12.4c.038-.151.076-.304.076-.456 0-.114-.038-.228-.038-.342-.114-.343-.304-.647-.646-.838l-4.87-2.777c-.685-.38-1.56-.152-1.94.533-.381.685-.153 1.56.532 1.94l2.701 1.56-2.701 1.56c-.685.38-.913 1.256-.533 1.94.38.685 1.256.914 1.94.533l4.832-2.777c.343-.267.571-.533.647-.876zm1.332 2.626c-.266-.038-.57.038-.837.19l-4.832 2.777c-.685.38-.913 1.256-.532 1.94.38.686 1.255.914 1.94.533l2.701-1.56v3.12c0 .8.647 1.408 1.446 1.408.799 0 1.407-.647 1.407-1.408v-5.592c0-.761-.57-1.37-1.293-1.408zm4.946-6.088c.266.038.57-.038.837-.19l4.832-2.777c.685-.38.913-1.256.532-1.94-.38-.686-1.255-.914-1.94-.533l-2.701 1.56V1.975c0-.799-.647-1.408-1.446-1.408-.799 0-1.446.609-1.446 1.408V7.53c0 .76.609 1.37 1.332 1.407zM3.265 5.97l4.832 2.777c.266.152.533.19.837.19.723-.038 1.331-.684 1.331-1.407V1.975c0-.799-.646-1.408-1.407-1.408-.799 0-1.446.647-1.446 1.408v3.12l-2.701-1.56c-.685-.38-1.56-.152-1.94.533-.419.646-.19 1.521.494 1.902zm9.093 6.011a.412.412 0 00-.114-.266l-.57-.571a.346.346 0 00-.267-.114.412.412 0 00-.266.114l-.571.57a.411.411 0 00-.114.267c0 .076.038.19.114.267l.57.57a.345.345 0 00.267.114c.076 0 .19-.038.266-.114l.571-.57a.412.412 0 00.114-.267zm1.598.533L11.94 14.53c-.039.038-.153.114-.229.114h-.608a.411.411 0 01-.267-.114L8.82 12.514a.408.408 0 01-.076-.229v-.608c0-.076.038-.19.114-.267l2.016-2.016a.41.41 0 01.267-.114h.608a.41.41 0 01.267.114l2.016 2.016a.347.347 0 01.114.267v.608c-.076.077-.114.19-.19.229zm5.593 5.44l-4.832-2.777c-.266-.152-.57-.19-.837-.152-.723.038-1.332.684-1.332 1.408v5.554c0 .8.647 1.408 1.408 1.408.799 0 1.446-.647 1.446-1.408v-3.12l2.7 1.56c.686.38 1.561.152 1.941-.533.419-.646.19-1.521-.494-1.94zm2.549-7.533l-2.701 1.56 2.7 1.56c.686.38.914 1.256.533 1.94-.38.685-1.255.913-1.94.533l-4.832-2.778a1.644 1.644 0 01-.647-.798c-.037-.153-.076-.305-.076-.457 0-.114.039-.228.039-.342.114-.343.342-.647.646-.837l4.832-2.778c.685-.38 1.56-.152 1.94.533.457.609.19 1.484-.494 1.864"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/database/postgresql.svg b/packages/core/eventcatalog/public/icons/database/postgresql.svg
new file mode 100644
index 000000000..931bdae18
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/database/postgresql.svg
@@ -0,0 +1 @@
+<svg fill="#4169E1" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>PostgreSQL</title><path d="M23.5594 14.7228a.5269.5269 0 0 0-.0563-.1191c-.139-.2632-.4768-.3418-1.0074-.2321-1.6533.3411-2.2935.1312-2.5256-.0191 1.342-2.0482 2.445-4.522 3.0411-6.8297.2714-1.0507.7982-3.5237.1222-4.7316a1.5641 1.5641 0 0 0-.1509-.235C21.6931.9086 19.8007.0248 17.5099.0005c-1.4947-.0158-2.7705.3461-3.1161.4794a9.449 9.449 0 0 0-.5159-.0816 8.044 8.044 0 0 0-1.3114-.1278c-1.1822-.0184-2.2038.2642-3.0498.8406-.8573-.3211-4.7888-1.645-7.2219.0788C.9359 2.1526.3086 3.8733.4302 6.3043c.0409.818.5069 3.334 1.2423 5.7436.4598 1.5065.9387 2.7019 1.4334 3.582.553.9942 1.1259 1.5933 1.7143 1.7895.4474.1491 1.1327.1441 1.8581-.7279.8012-.9635 1.5903-1.8258 1.9446-2.2069.4351.2355.9064.3625 1.39.3772a.0569.0569 0 0 0 .0004.0041 11.0312 11.0312 0 0 0-.2472.3054c-.3389.4302-.4094.5197-1.5002.7443-.3102.064-1.1344.2339-1.1464.8115-.0025.1224.0329.2309.0919.3268.2269.4231.9216.6097 1.015.6331 1.3345.3335 2.5044.092 3.3714-.6787-.017 2.231.0775 4.4174.3454 5.0874.2212.5529.7618 1.9045 2.4692 1.9043.2505 0 .5263-.0291.8296-.0941 1.7819-.3821 2.5557-1.1696 2.855-2.9059.1503-.8707.4016-2.8753.5388-4.1012.0169-.0703.0357-.1207.057-.1362.0007-.0005.0697-.0471.4272.0307a.3673.3673 0 0 0 .0443.0068l.2539.0223.0149.001c.8468.0384 1.9114-.1426 2.5312-.4308.6438-.2988 1.8057-1.0323 1.5951-1.6698zM2.371 11.8765c-.7435-2.4358-1.1779-4.8851-1.2123-5.5719-.1086-2.1714.4171-3.6829 1.5623-4.4927 1.8367-1.2986 4.8398-.5408 6.108-.13-.0032.0032-.0066.0061-.0098.0094-2.0238 2.044-1.9758 5.536-1.9708 5.7495-.0002.0823.0066.1989.0162.3593.0348.5873.0996 1.6804-.0735 2.9184-.1609 1.1504.1937 2.2764.9728 3.0892.0806.0841.1648.1631.2518.2374-.3468.3714-1.1004 1.1926-1.9025 2.1576-.5677.6825-.9597.5517-1.0886.5087-.3919-.1307-.813-.5871-1.2381-1.3223-.4796-.839-.9635-2.0317-1.4155-3.5126zm6.0072 5.0871c-.1711-.0428-.3271-.1132-.4322-.1772.0889-.0394.2374-.0902.4833-.1409 1.2833-.2641 1.4815-.4506 1.9143-1.0002.0992-.126.2116-.2687.3673-.4426a.3549.3549 0 0 0 .0737-.1298c.1708-.1513.2724-.1099.4369-.0417.156.0646.3078.26.3695.4752.0291.1016.0619.2945-.0452.4444-.9043 1.2658-2.2216 1.2494-3.1676 1.0128zm2.094-3.988-.0525.141c-.133.3566-.2567.6881-.3334 1.003-.6674-.0021-1.3168-.2872-1.8105-.8024-.6279-.6551-.9131-1.5664-.7825-2.5004.1828-1.3079.1153-2.4468.079-3.0586-.005-.0857-.0095-.1607-.0122-.2199.2957-.2621 1.6659-.9962 2.6429-.7724.4459.1022.7176.4057.8305.928.5846 2.7038.0774 3.8307-.3302 4.7363-.084.1866-.1633.3629-.2311.5454zm7.3637 4.5725c-.0169.1768-.0358.376-.0618.5959l-.146.4383a.3547.3547 0 0 0-.0182.1077c-.0059.4747-.054.6489-.115.8693-.0634.2292-.1353.4891-.1794 1.0575-.11 1.4143-.8782 2.2267-2.4172 2.5565-1.5155.3251-1.7843-.4968-2.0212-1.2217a6.5824 6.5824 0 0 0-.0769-.2266c-.2154-.5858-.1911-1.4119-.1574-2.5551.0165-.5612-.0249-1.9013-.3302-2.6462.0044-.2932.0106-.5909.019-.8918a.3529.3529 0 0 0-.0153-.1126 1.4927 1.4927 0 0 0-.0439-.208c-.1226-.4283-.4213-.7866-.7797-.9351-.1424-.059-.4038-.1672-.7178-.0869.067-.276.1831-.5875.309-.9249l.0529-.142c.0595-.16.134-.3257.213-.5012.4265-.9476 1.0106-2.2453.3766-5.1772-.2374-1.0981-1.0304-1.6343-2.2324-1.5098-.7207.0746-1.3799.3654-1.7088.5321a5.6716 5.6716 0 0 0-.1958.1041c.0918-1.1064.4386-3.1741 1.7357-4.4823a4.0306 4.0306 0 0 1 .3033-.276.3532.3532 0 0 0 .1447-.0644c.7524-.5706 1.6945-.8506 2.802-.8325.4091.0067.8017.0339 1.1742.081 1.939.3544 3.2439 1.4468 4.0359 2.3827.8143.9623 1.2552 1.9315 1.4312 2.4543-1.3232-.1346-2.2234.1268-2.6797.779-.9926 1.4189.543 4.1729 1.2811 5.4964.1353.2426.2522.4522.2889.5413.2403.5825.5515.9713.7787 1.2552.0696.087.1372.1714.1885.245-.4008.1155-1.1208.3825-1.0552 1.717-.0123.1563-.0423.4469-.0834.8148-.0461.2077-.0702.4603-.0994.7662zm.8905-1.6211c-.0405-.8316.2691-.9185.5967-1.0105a2.8566 2.8566 0 0 0 .135-.0406 1.202 1.202 0 0 0 .1342.103c.5703.3765 1.5823.4213 3.0068.1344-.2016.1769-.5189.3994-.9533.6011-.4098.1903-1.0957.333-1.7473.3636-.7197.0336-1.0859-.0807-1.1721-.151zm.5695-9.2712c-.0059.3508-.0542.6692-.1054 1.0017-.055.3576-.112.7274-.1264 1.1762-.0142.4368.0404.8909.0932 1.3301.1066.887.216 1.8003-.2075 2.7014a3.5272 3.5272 0 0 1-.1876-.3856c-.0527-.1276-.1669-.3326-.3251-.6162-.6156-1.1041-2.0574-3.6896-1.3193-4.7446.3795-.5427 1.3408-.5661 2.1781-.463zm.2284 7.0137a12.3762 12.3762 0 0 0-.0853-.1074l-.0355-.0444c.7262-1.1995.5842-2.3862.4578-3.4385-.0519-.4318-.1009-.8396-.0885-1.2226.0129-.4061.0666-.7543.1185-1.0911.0639-.415.1288-.8443.1109-1.3505.0134-.0531.0188-.1158.0118-.1902-.0457-.4855-.5999-1.938-1.7294-3.253-.6076-.7073-1.4896-1.4972-2.6889-2.0395.5251-.1066 1.2328-.2035 2.0244-.1859 2.0515.0456 3.6746.8135 4.8242 2.2824a.908.908 0 0 1 .0667.1002c.7231 1.3556-.2762 6.2751-2.9867 10.5405zm-8.8166-6.1162c-.025.1794-.3089.4225-.6211.4225a.5821.5821 0 0 1-.0809-.0056c-.1873-.026-.3765-.144-.5059-.3156-.0458-.0605-.1203-.178-.1055-.2844.0055-.0401.0261-.0985.0925-.1488.1182-.0894.3518-.1226.6096-.0867.3163.0441.6426.1938.6113.4186zm7.9305-.4114c.0111.0792-.049.201-.1531.3102-.0683.0717-.212.1961-.4079.2232a.5456.5456 0 0 1-.075.0052c-.2935 0-.5414-.2344-.5607-.3717-.024-.1765.2641-.3106.5611-.352.297-.0414.6111.0088.6356.1851z"/></svg>
\ No newline at end of file
diff --git a/eventcatalog/public/icons/discord.svg b/packages/core/eventcatalog/public/icons/discord.svg
similarity index 100%
rename from eventcatalog/public/icons/discord.svg
rename to packages/core/eventcatalog/public/icons/discord.svg
diff --git a/packages/core/eventcatalog/public/icons/events/eventbridge.svg b/packages/core/eventcatalog/public/icons/events/eventbridge.svg
new file mode 100644
index 000000000..469a4d346
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/events/eventbridge.svg
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="80px" height="80px" viewBox="0 0 80 80" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <title>Icon-Architecture/64/Arch_Amazon-EventBridge_64</title>
+    <defs>
+        <linearGradient x1="0%" y1="100%" x2="100%" y2="0%" id="linearGradient-1">
+            <stop stop-color="#B0084D" offset="0%"></stop>
+            <stop stop-color="#FF4F8B" offset="100%"></stop>
+        </linearGradient>
+    </defs>
+    <g id="Icon-Architecture/64/Arch_Amazon-EventBridge_64" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="Icon-Architecture-BG/64/Application-Integration" fill="url(#linearGradient-1)">
+            <rect id="Rectangle" x="0" y="0" width="80" height="80"></rect>
+        </g>
+        <path d="M53.656744,66 C51.5137882,66 49.7695913,64.247 49.7695913,62.091 C49.7695913,59.935 51.5137882,58.182 53.656744,58.182 C55.7996998,58.182 57.5438968,59.935 57.5438968,62.091 C57.5438968,64.247 55.7996998,66 53.656744,66 L53.656744,66 Z M45.1326526,49 L34.7977386,49 L29.6297845,40 L34.7977386,31 L45.1326526,31 L50.2996124,40 L45.1326526,49 Z M27.6210741,21.818 C25.4781184,21.818 23.7339214,20.065 23.7339214,17.909 C23.7339214,15.753 25.4781184,14 27.6210741,14 C29.7650244,14 31.5092213,15.753 31.5092213,17.909 C31.5092213,20.065 29.7650244,21.818 27.6210741,21.818 L27.6210741,21.818 Z M53.656744,56.182 C52.918891,56.182 52.214848,56.325 51.5635088,56.576 L47.3402451,49.41 L47.117497,49.543 L52.3093171,40.5 C52.4863222,40.19 52.4863222,39.81 52.3093171,39.5 L46.5675877,29.5 C46.3895881,29.19 46.0614325,29 45.7064278,29 L35.2581509,29 L35.2989218,28.976 L31.4266852,22.404 C32.691576,21.32 33.4980434,19.708 33.4980434,17.909 C33.4980434,14.651 30.8618597,12 27.6210741,12 C24.381283,12 21.7450993,14.651 21.7450993,17.909 C21.7450993,21.167 24.381283,23.818 27.6210741,23.818 C28.3599216,23.818 29.0639646,23.675 29.7153038,23.424 L33.3299879,29.557 L27.6200797,39.5 C27.4430746,39.81 27.4430746,40.19 27.6200797,40.5 L33.3628035,50.5 C33.5408031,50.81 33.8689587,51 34.2239635,51 L45.7064278,51 C45.7889639,51 45.8695112,50.987 45.9470752,50.968 L49.8521274,57.596 C48.5862421,58.68 47.7807692,60.292 47.7807692,62.091 C47.7807692,65.349 50.4159585,68 53.656744,68 C56.8975296,68 59.5327189,65.349 59.5327189,62.091 C59.5327189,58.833 56.8975296,56.182 53.656744,56.182 L53.656744,56.182 Z M59.5844283,32.104 C57.4414725,32.104 55.6982699,30.351 55.6982699,28.195 C55.6982699,26.039 57.4414725,24.286 59.5844283,24.286 C61.7273841,24.286 63.471581,26.039 63.471581,28.195 C63.471581,30.351 61.7273841,32.104 59.5844283,32.104 L59.5844283,32.104 Z M66.8665003,39.5 L63.091716,32.925 C64.5266511,31.846 65.4604031,30.13 65.4604031,28.195 C65.4604031,24.937 62.8252138,22.286 59.5844283,22.286 C58.7600615,22.286 57.9744768,22.459 57.2614841,22.77 L54.1837819,17.409 C54.0067767,17.1 53.6776267,16.909 53.3226219,16.909 L40.9949082,16.909 L40.9949082,18.909 L52.7488468,18.909 L55.5958456,23.869 C54.4383511,24.949 53.7094478,26.486 53.7094478,28.195 C53.7094478,31.453 56.3446371,34.104 59.5844283,34.104 C60.1880358,34.104 60.771755,34.011 61.3206699,33.84 L64.85779,40 L59.8917013,48.648 L61.6140212,49.648 L66.8665003,40.5 C67.0444999,40.19 67.0444999,39.81 66.8665003,39.5 L66.8665003,39.5 Z M21.229,55.247 C19.0850498,55.247 17.3408528,53.493 17.3408528,51.338 C17.3408528,49.182 19.0850498,47.429 21.229,47.429 C23.3719558,47.429 25.1161527,49.182 25.1161527,51.338 C25.1161527,53.493 23.3719558,55.247 21.229,55.247 L21.229,55.247 Z M24.4767464,56.258 C26.0588544,55.198 27.1049748,53.389 27.1049748,51.338 C27.1049748,48.08 24.4687911,45.429 21.229,45.429 C20.2902759,45.429 19.4062445,45.657 18.618671,46.052 L15.1432044,40 L20.9018387,29.971 L19.1785244,28.971 L13.1334997,39.5 C12.9555001,39.81 12.9555001,40.19 13.1334997,40.5 L17.0047419,47.24 C15.9834817,48.304 15.3520307,49.747 15.3520307,51.338 C15.3520307,54.596 17.9882144,57.247 21.229,57.247 C21.7172558,57.247 22.189601,57.18 22.6440469,57.066 L25.8162181,62.591 C25.9942177,62.9 26.3223733,63.091 26.6773781,63.091 L39.0060862,63.091 L39.0060862,61.091 L27.2511532,61.091 L24.4767464,56.258 Z" id="Amazon-EventBridge_Icon_64_Squid" fill="#FFFFFF"></path>
+    </g>
+</svg>
\ No newline at end of file
diff --git a/eventcatalog/public/icons/github-purple.svg b/packages/core/eventcatalog/public/icons/github-purple.svg
similarity index 100%
rename from eventcatalog/public/icons/github-purple.svg
rename to packages/core/eventcatalog/public/icons/github-purple.svg
diff --git a/eventcatalog/public/icons/github.svg b/packages/core/eventcatalog/public/icons/github.svg
similarity index 100%
rename from eventcatalog/public/icons/github.svg
rename to packages/core/eventcatalog/public/icons/github.svg
diff --git a/packages/core/eventcatalog/public/icons/graphql-black.svg b/packages/core/eventcatalog/public/icons/graphql-black.svg
new file mode 100644
index 000000000..88c722d51
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/graphql-black.svg
@@ -0,0 +1 @@
+<svg viewBox="-16 0 288 288" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid" fill="#000000"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"> <g fill-rule="evenodd"> <path d="M152.575995,32.9634453 L211.722058,67.1124427 C213.387503,65.348329 215.332859,63.7907081 217.539734,62.5088708 C229.806457,55.4573413 245.452038,59.6441869 252.577021,71.9109101 C259.62855,84.1776333 255.441705,99.8232143 243.174982,106.948197 C240.984974,108.207124 238.684929,109.10784 236.343812,109.66832 L236.343812,177.99302 C238.659582,178.554683 240.934429,179.449686 243.101528,180.695443 C255.441705,187.820426 259.62855,203.466007 252.503568,215.73273 C245.452038,227.999453 229.733004,232.186299 217.46628,225.13477 C215.024105,223.730884 212.902189,221.983449 211.125456,219.988103 L152.340162,253.928803 C153.180519,256.46808 153.635248,259.18431 153.635248,262.008393 C153.635248,276.111452 142.176512,287.64364 128,287.64364 C113.823488,287.64364 102.364752,276.184905 102.364752,262.008393 C102.364752,259.488481 102.726802,257.054441 103.40181,254.755362 L44.2714887,220.615454 C42.6238257,222.34493 40.705394,223.873378 38.5337196,225.13477 C26.193543,232.186299 10.547962,227.999453 3.49643248,215.73273 C-3.55509701,203.466007 0.631748621,187.820426 12.8984718,180.695443 C15.0673397,179.448669 17.3418356,178.553222 19.6561876,177.991646 L19.6561876,109.66832 C17.3150714,109.10784 15.0150257,108.207124 12.8250184,106.948197 C0.558295189,99.8966677 -3.62855044,84.1776333 3.42297904,71.9109101 C10.4745085,59.6441869 26.193543,55.4573413 38.4602662,62.5088708 C40.6551374,63.7837361 42.5913269,65.3313931 44.2507413,67.0836756 L103.41276,32.9254664 C102.730718,30.6154532 102.364752,28.1687503 102.364752,25.6352478 C102.364752,11.4587354 113.823488,0 128,0 C142.176512,0 153.635248,11.4587354 153.635248,25.6352478 C153.635248,28.1826393 153.265258,30.6422768 152.575995,32.9634453 Z M146.413638,43.4848713 L205.700555,77.715193 C203.867899,84.1516888 204.540515,91.2885638 208.137694,97.5461579 C211.746601,103.824151 217.625783,107.985785 224.150543,109.607654 L224.150543,178.017842 C223.818032,178.099463 223.48718,178.187674 223.158201,178.282419 L145.72529,44.1686182 C145.959017,43.9450469 146.18851,43.7170876 146.413638,43.4848713 Z M110.29093,44.1841203 L32.8593279,178.295656 C32.524559,178.19844 32.1878611,178.108015 31.8494573,178.024438 L31.8494573,109.607654 C38.3742168,107.985785 44.2533992,103.824151 47.8623055,97.5461579 C51.466599,91.276189 52.1347497,84.1234583 50.2885426,77.6770157 L109.558747,43.4563434 C109.797913,43.7038019 110.042027,43.9464469 110.29093,44.1841203 Z M135.162749,50.259763 L212.576817,184.340928 C210.844241,185.99279 209.317376,187.91755 208.064241,190.097482 C206.818484,192.264581 205.923481,194.539429 205.361818,196.855198 L50.6395564,196.855198 C50.0779798,194.540846 49.1825333,192.26635 47.9357589,190.097482 C46.6776713,187.931497 45.1539248,186.017428 43.4300297,184.372667 L120.858821,50.2659993 C123.124941,50.9200822 125.520915,51.2704957 128,51.2704957 C130.486952,51.2704957 132.890265,50.9178547 135.162749,50.259763 Z M146.958084,244.737995 L205.860107,210.729899 C205.683398,210.174924 205.525483,209.614096 205.38664,209.048468 L50.6067643,209.048468 C50.5246888,209.380792 50.4360084,209.711472 50.3407792,210.040295 L109.531782,244.215239 C114.192298,239.378545 120.739739,236.373145 128,236.373145 C135.518379,236.373145 142.272352,239.596041 146.958084,244.737995 Z" fill="#000"> </path> </g> </g></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/graphql.svg b/packages/core/eventcatalog/public/icons/graphql.svg
new file mode 100644
index 000000000..0754ced20
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/graphql.svg
@@ -0,0 +1,3 @@
+<svg viewBox="-16 0 288 288" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid">
+  <path d="M152.575995,32.9634453 L211.722058,67.1124427 C213.387503,65.348329 215.332859,63.7907081 217.539734,62.5088708 C229.806457,55.4573413 245.452038,59.6441869 252.577021,71.9109101 C259.62855,84.1776333 255.441705,99.8232143 243.174982,106.948197 C240.984974,108.207124 238.684929,109.10784 236.343812,109.66832 L236.343812,177.99302 C238.659582,178.554683 240.934429,179.449686 243.101528,180.695443 C255.441705,187.820426 259.62855,203.466007 252.503568,215.73273 C245.452038,227.999453 229.733004,232.186299 217.46628,225.13477 C215.024105,223.730884 212.902189,221.983449 211.125456,219.988103 L152.340162,253.928803 C153.180519,256.46808 153.635248,259.18431 153.635248,262.008393 C153.635248,276.111452 142.176512,287.64364 128,287.64364 C113.823488,287.64364 102.364752,276.184905 102.364752,262.008393 C102.364752,259.488481 102.726802,257.054441 103.40181,254.755362 L44.2714887,220.615454 C42.6238257,222.34493 40.705394,223.873378 38.5337196,225.13477 C26.193543,232.186299 10.547962,227.999453 3.49643248,215.73273 C-3.55509701,203.466007 0.631748621,187.820426 12.8984718,180.695443 C15.0673397,179.448669 17.3418356,178.553222 19.6561876,177.991646 L19.6561876,109.66832 C17.3150714,109.10784 15.0150257,108.207124 12.8250184,106.948197 C0.558295189,99.8966677 -3.62855044,84.1776333 3.42297904,71.9109101 C10.4745085,59.6441869 26.193543,55.4573413 38.4602662,62.5088708 C40.6551374,63.7837361 42.5913269,65.3313931 44.2507413,67.0836756 L103.41276,32.9254664 C102.730718,30.6154532 102.364752,28.1687503 102.364752,25.6352478 C102.364752,11.4587354 113.823488,0 128,0 C142.176512,0 153.635248,11.4587354 153.635248,25.6352478 C153.635248,28.1826393 153.265258,30.6422768 152.575995,32.9634453 Z M146.413638,43.4848713 L205.700555,77.715193 C203.867899,84.1516888 204.540515,91.2885638 208.137694,97.5461579 C211.746601,103.824151 217.625783,107.985785 224.150543,109.607654 L224.150543,178.017842 C223.818032,178.099463 223.48718,178.187674 223.158201,178.282419 L145.72529,44.1686182 C145.959017,43.9450469 146.18851,43.7170876 146.413638,43.4848713 Z M110.29093,44.1841203 L32.8593279,178.295656 C32.524559,178.19844 32.1878611,178.108015 31.8494573,178.024438 L31.8494573,109.607654 C38.3742168,107.985785 44.2533992,103.824151 47.8623055,97.5461579 C51.466599,91.276189 52.1347497,84.1234583 50.2885426,77.6770157 L109.558747,43.4563434 C109.797913,43.7038019 110.042027,43.9464469 110.29093,44.1841203 Z M135.162749,50.259763 L212.576817,184.340928 C210.844241,185.99279 209.317376,187.91755 208.064241,190.097482 C206.818484,192.264581 205.923481,194.539429 205.361818,196.855198 L50.6395564,196.855198 C50.0779798,194.540846 49.1825333,192.26635 47.9357589,190.097482 C46.6776713,187.931497 45.1539248,186.017428 43.4300297,184.372667 L120.858821,50.2659993 C123.124941,50.9200822 125.520915,51.2704957 128,51.2704957 C130.486952,51.2704957 132.890265,50.9178547 135.162749,50.259763 Z M146.958084,244.737995 L205.860107,210.729899 C205.683398,210.174924 205.525483,209.614096 205.38664,209.048468 L50.6067643,209.048468 C50.5246888,209.380792 50.4360084,209.711472 50.3407792,210.040295 L109.531782,244.215239 C114.192298,239.378545 120.739739,236.373145 128,236.373145 C135.518379,236.373145 142.272352,239.596041 146.958084,244.737995 Z" fill="#E535AB" fill-rule="evenodd"/>
+</svg>
diff --git a/eventcatalog/public/icons/json-schema.svg b/packages/core/eventcatalog/public/icons/json-schema.svg
similarity index 100%
rename from eventcatalog/public/icons/json-schema.svg
rename to packages/core/eventcatalog/public/icons/json-schema.svg
diff --git a/packages/core/eventcatalog/public/icons/languages/dotnet.svg b/packages/core/eventcatalog/public/icons/languages/dotnet.svg
new file mode 100644
index 000000000..c4b482ecc
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/languages/dotnet.svg
@@ -0,0 +1 @@
+<svg fill="#512BD4" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>.NET</title><path d="M24 8.77h-2.468v7.565h-1.425V8.77h-2.462V7.53H24zm-6.852 7.565h-4.821V7.53h4.63v1.24h-3.205v2.494h2.953v1.234h-2.953v2.604h3.396zm-6.708 0H8.882L4.78 9.863a2.896 2.896 0 0 1-.258-.51h-.036c.032.189.048.592.048 1.21v5.772H3.157V7.53h1.659l3.965 6.32c.167.261.275.442.323.54h.024c-.04-.233-.06-.629-.06-1.185V7.529h1.372zm-8.703-.693a.868.829 0 0 1-.869.829.868.829 0 0 1-.868-.83.868.829 0 0 1 .868-.828.868.829 0 0 1 .869.829Z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/languages/go.svg b/packages/core/eventcatalog/public/icons/languages/go.svg
new file mode 100644
index 000000000..51990bd01
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/languages/go.svg
@@ -0,0 +1 @@
+<svg fill="#00ADD8" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Go</title><path d="M1.811 10.231c-.047 0-.058-.023-.035-.059l.246-.315c.023-.035.081-.058.128-.058h4.172c.046 0 .058.035.035.07l-.199.303c-.023.036-.082.07-.117.07zM.047 11.306c-.047 0-.059-.023-.035-.058l.245-.316c.023-.035.082-.058.129-.058h5.328c.047 0 .07.035.058.07l-.093.28c-.012.047-.058.07-.105.07zm2.828 1.075c-.047 0-.059-.035-.035-.07l.163-.292c.023-.035.07-.07.117-.07h2.337c.047 0 .07.035.07.082l-.023.28c0 .047-.047.082-.082.082zm12.129-2.36c-.736.187-1.239.327-1.963.514-.176.046-.187.058-.34-.117-.174-.199-.303-.327-.548-.444-.737-.362-1.45-.257-2.115.175-.795.514-1.204 1.274-1.192 2.22.011.935.654 1.706 1.577 1.835.795.105 1.46-.175 1.987-.77.105-.13.198-.27.315-.434H10.47c-.245 0-.304-.152-.222-.35.152-.362.432-.97.596-1.274a.315.315 0 01.292-.187h4.253c-.023.316-.023.631-.07.947a4.983 4.983 0 01-.958 2.29c-.841 1.11-1.94 1.8-3.33 1.986-1.145.152-2.209-.07-3.143-.77-.865-.655-1.356-1.52-1.484-2.595-.152-1.274.222-2.419.993-3.424.83-1.086 1.928-1.776 3.272-2.02 1.098-.2 2.15-.07 3.096.571.62.41 1.063.97 1.356 1.648.07.105.023.164-.117.2m3.868 6.461c-1.064-.024-2.034-.328-2.852-1.029a3.665 3.665 0 01-1.262-2.255c-.21-1.32.152-2.489.947-3.529.853-1.122 1.881-1.706 3.272-1.95 1.192-.21 2.314-.095 3.33.595.923.63 1.496 1.484 1.648 2.605.198 1.578-.257 2.863-1.344 3.962-.771.783-1.718 1.273-2.805 1.495-.315.06-.63.07-.934.106zm2.78-4.72c-.011-.153-.011-.27-.034-.387-.21-1.157-1.274-1.81-2.384-1.554-1.087.245-1.788.935-2.045 2.033-.21.912.234 1.835 1.075 2.21.643.28 1.285.244 1.905-.07.923-.48 1.425-1.228 1.484-2.233z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/languages/java.svg b/packages/core/eventcatalog/public/icons/languages/java.svg
new file mode 100644
index 000000000..c72c27432
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/languages/java.svg
@@ -0,0 +1 @@
+<svg fill="#ED8B00" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Java</title><path d="M8.851 18.56s-.917.534.653.714c1.902.218 2.874.187 4.969-.211 0 0 .552.346 1.321.646-4.699 2.013-10.633-.118-6.943-1.149M8.276 15.933s-1.028.761.542.924c2.032.209 3.636.227 6.413-.308 0 0 .384.389.987.602-5.679 1.661-12.007.13-7.942-1.218M13.116 11.475c1.158 1.333-.304 2.533-.304 2.533s2.939-1.518 1.589-3.418c-1.261-1.772-2.228-2.652 3.007-5.688 0-.001-8.216 2.051-4.292 6.573M19.33 20.504s.679.559-.747.991c-2.712.822-11.288 1.069-13.669.033-.856-.373.75-.89 1.254-.998.527-.114.828-.093.828-.093-.953-.671-6.156 1.317-2.643 1.887 9.58 1.553 17.462-.7 14.977-1.82M9.292 13.21s-4.362 1.036-1.544 1.412c1.189.159 3.561.123 5.77-.062 1.806-.152 3.618-.477 3.618-.477s-.637.272-1.098.587c-4.429 1.165-12.986.623-10.522-.568 2.082-1.006 3.776-.892 3.776-.892M17.116 17.584c4.503-2.34 2.421-4.589.968-4.285-.355.074-.515.138-.515.138s.132-.207.385-.297c2.875-1.011 5.086 2.981-.928 4.562 0-.001.07-.062.09-.118M13.408 0s2.494 2.494-2.365 6.33c-3.896 3.077-.888 4.832-.001 6.836-2.274-2.053-3.943-3.858-2.824-5.539 1.644-2.469 6.197-3.665 5.19-7.627M9.734 23.924c4.322.277 10.959-.153 11.116-2.198 0 0-.302.775-3.572 1.391-3.688.694-8.239.613-10.937.168 0-.001.553.457 3.393.639"/></svg>
diff --git a/packages/core/eventcatalog/public/icons/languages/nodejs.svg b/packages/core/eventcatalog/public/icons/languages/nodejs.svg
new file mode 100644
index 000000000..3cc5893e0
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/languages/nodejs.svg
@@ -0,0 +1 @@
+<svg fill="#5FA04E" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Node.js</title><path d="M11.998,24c-0.321,0-0.641-0.084-0.922-0.247l-2.936-1.737c-0.438-0.245-0.224-0.332-0.08-0.383 c0.585-0.203,0.703-0.25,1.328-0.604c0.065-0.037,0.151-0.023,0.218,0.017l2.256,1.339c0.082,0.045,0.197,0.045,0.272,0l8.795-5.076 c0.082-0.047,0.134-0.141,0.134-0.238V6.921c0-0.099-0.053-0.192-0.137-0.242l-8.791-5.072c-0.081-0.047-0.189-0.047-0.271,0 L3.075,6.68C2.99,6.729,2.936,6.825,2.936,6.921v10.15c0,0.097,0.054,0.189,0.139,0.235l2.409,1.392 c1.307,0.654,2.108-0.116,2.108-0.89V7.787c0-0.142,0.114-0.253,0.256-0.253h1.115c0.139,0,0.255,0.112,0.255,0.253v10.021 c0,1.745-0.95,2.745-2.604,2.745c-0.508,0-0.909,0-2.026-0.551L2.28,18.675c-0.57-0.329-0.922-0.945-0.922-1.604V6.921 c0-0.659,0.353-1.275,0.922-1.603l8.795-5.082c0.557-0.315,1.296-0.315,1.848,0l8.794,5.082c0.57,0.329,0.924,0.944,0.924,1.603 v10.15c0,0.659-0.354,1.273-0.924,1.604l-8.794,5.078C12.643,23.916,12.324,24,11.998,24z M19.099,13.993 c0-1.9-1.284-2.406-3.987-2.763c-2.731-0.361-3.009-0.548-3.009-1.187c0-0.528,0.235-1.233,2.258-1.233 c1.807,0,2.473,0.389,2.747,1.607c0.024,0.115,0.129,0.199,0.247,0.199h1.141c0.071,0,0.138-0.031,0.186-0.081 c0.048-0.054,0.074-0.123,0.067-0.196c-0.177-2.098-1.571-3.076-4.388-3.076c-2.508,0-4.004,1.058-4.004,2.833 c0,1.925,1.488,2.457,3.895,2.695c2.88,0.282,3.103,0.703,3.103,1.269c0,0.983-0.789,1.402-2.642,1.402 c-2.327,0-2.839-0.584-3.011-1.742c-0.02-0.124-0.126-0.215-0.253-0.215h-1.137c-0.141,0-0.254,0.112-0.254,0.253 c0,1.482,0.806,3.248,4.655,3.248C17.501,17.007,19.099,15.91,19.099,13.993z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/messages/mail.svg b/packages/core/eventcatalog/public/icons/messages/mail.svg
new file mode 100644
index 000000000..9b022ee86
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/messages/mail.svg
@@ -0,0 +1,16 @@
+<!-- @license lucide-static v1.8.0 - ISC -->
+<svg
+  class="lucide lucide-mail"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="m22 7-8.991 5.727a2 2 0 0 1-2.009 0L2 7" />
+  <rect x="2" y="4" width="20" height="16" rx="2" />
+</svg>
diff --git a/packages/core/eventcatalog/public/icons/messages/package.svg b/packages/core/eventcatalog/public/icons/messages/package.svg
new file mode 100644
index 000000000..a4a233aa0
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/messages/package.svg
@@ -0,0 +1,18 @@
+<!-- @license lucide-static v1.8.0 - ISC -->
+<svg
+  class="lucide lucide-package"
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M11 21.73a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73z" />
+  <path d="M12 22V12" />
+  <polyline points="3.29 7 12 12 20.71 7" />
+  <path d="m7.5 4.27 9 5.15" />
+</svg>
diff --git a/packages/core/eventcatalog/public/icons/messaging/sns.svg b/packages/core/eventcatalog/public/icons/messaging/sns.svg
new file mode 100644
index 000000000..6cb54adab
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/messaging/sns.svg
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="80px" height="80px" viewBox="0 0 80 80" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <!-- Generator: Sketch 64 (93537) - https://sketch.com -->
+    <title>Icon-Architecture/64/Arch_AWS-Simple-Notification-Service_64</title>
+    <desc>Created with Sketch.</desc>
+    <defs>
+        <linearGradient x1="0%" y1="100%" x2="100%" y2="0%" id="linearGradient-1">
+            <stop stop-color="#B0084D" offset="0%"></stop>
+            <stop stop-color="#FF4F8B" offset="100%"></stop>
+        </linearGradient>
+    </defs>
+    <g id="Icon-Architecture/64/Arch_AWS-Simple-Notification-Service_64" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="Icon-Architecture-BG/64/Application-Integration" fill="url(#linearGradient-1)">
+            <rect id="Rectangle" x="0" y="0" width="80" height="80"></rect>
+        </g>
+        <path d="M17,38 C18.103,38 19,38.897 19,40 C19,41.103 18.103,42 17,42 C15.897,42 15,41.103 15,40 C15,38.897 15.897,38 17,38 L17,38 Z M41,64 C29.314,64 19.289,55.466 17.194,43.98 C18.965,43.894 20.427,42.659 20.857,41 L27,41 L27,39 L20.857,39 C20.427,37.342 18.966,36.107 17.195,36.02 C19.285,24.71 29.511,16 41,16 C45.313,16 49.832,17.622 54.429,20.821 L55.571,19.179 C50.633,15.743 45.73,14 41,14 C28.27,14 16.949,23.865 15.063,36.521 C13.839,37.207 13,38.5 13,40 C13,41.5 13.839,42.793 15.063,43.478 C16.97,56.341 28.056,66 41,66 C46.407,66 51.942,64.157 56.585,60.811 L55.415,59.189 C51.11,62.292 45.991,64 41,64 L41,64 Z M30.101,36.442 C31.955,36.895 34.275,37 36,37 C37.642,37 39.823,36.905 41.629,36.506 L37.105,45.553 C37.036,45.691 37,45.845 37,46 L37,50.453 C36.199,50.964 34.833,51.812 34,51.986 L34,46 C34,45.868 33.974,45.737 33.923,45.615 L30.101,36.442 Z M36,33 C40.025,33 42.174,33.604 42.841,34 C42.174,34.396 40.025,35 36,35 C31.975,35 29.826,34.396 29.159,34 C29.826,33.604 31.975,33 36,33 L36,33 Z M33,54 L34,54 C34.043,54 34.086,53.997 34.128,53.992 C35.352,53.833 36.909,52.887 38.272,52.013 L38.535,51.845 C38.824,51.661 39,51.342 39,51 L39,46.236 L44.559,35.12 C44.833,34.801 45,34.434 45,34 C45,31.39 39.361,31 36,31 C32.639,31 27,31.39 27,34 C27,34.366 27.12,34.684 27.32,34.967 L32,46.2 L32,53 C32,53.552 32.447,54 33,54 L33,54 Z M62,53 C63.103,53 64,53.897 64,55 C64,56.103 63.103,57 62,57 C60.897,57 60,56.103 60,55 C60,53.897 60.897,53 62,53 L62,53 Z M62,23 C63.103,23 64,23.897 64,25 C64,26.103 63.103,27 62,27 C60.897,27 60,26.103 60,25 C60,23.897 60.897,23 62,23 L62,23 Z M64,38 C65.103,38 66,38.897 66,40 C66,41.103 65.103,42 64,42 C62.897,42 62,41.103 62,40 C62,38.897 62.897,38 64,38 L64,38 Z M54,41 L60.143,41 C60.589,42.72 62.142,44 64,44 C66.206,44 68,42.206 68,40 C68,37.794 66.206,36 64,36 C62.142,36 60.589,37.28 60.143,39 L54,39 L54,26 L58.143,26 C58.589,27.72 60.142,29 62,29 C64.206,29 66,27.206 66,25 C66,22.794 64.206,21 62,21 C60.142,21 58.589,22.28 58.143,24 L53,24 C52.447,24 52,24.448 52,25 L52,39 L45,39 L45,41 L52,41 L52,55 C52,55.552 52.447,56 53,56 L58.143,56 C58.589,57.72 60.142,59 62,59 C64.206,59 66,57.206 66,55 C66,52.794 64.206,51 62,51 C60.142,51 58.589,52.28 58.143,54 L54,54 L54,41 Z" id="AWS-Simple-Notification-Service_Icon_64_Squid" fill="#FFFFFF"></path>
+    </g>
+</svg>
\ No newline at end of file
diff --git a/eventcatalog/public/icons/ms-teams.svg b/packages/core/eventcatalog/public/icons/ms-teams.svg
similarity index 100%
rename from eventcatalog/public/icons/ms-teams.svg
rename to packages/core/eventcatalog/public/icons/ms-teams.svg
diff --git a/packages/core/eventcatalog/public/icons/openapi-black.svg b/packages/core/eventcatalog/public/icons/openapi-black.svg
new file mode 100644
index 000000000..c8b9aaa78
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/openapi-black.svg
@@ -0,0 +1 @@
+<svg viewBox="0 0 256 256" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid" fill="#000000"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"> <g> <path d="M127.059657,255.996921 C58.8506544,255.526472 -0.457073619,198.918442 0.00265506057,126.998303 C0.444649399,57.7958628 57.9516598,-0.468967577 129.11002,0.00284555012 C198.267128,0.462386081 256.613109,57.8667711 255.995136,128.194199 C256.568091,197.883453 197.934268,256.489189 127.059657,255.996921 Z M127.059657,255.996921 C58.8506544,255.526472 -0.457073619,198.918442 0.00265506057,126.998303 C0.444649399,57.7958628 57.9516598,-0.468967577 129.11002,0.00284555012 C198.267128,0.462386081 256.613109,57.8667711 255.995136,128.194199 C256.568091,197.883453 197.934268,256.489189 127.059657,255.996921 Z" fill="#FFFFFF"> </path> <path d="M127.184644,238.997327 C68.0323765,238.589271 16.6036091,189.498744 17.0023028,127.131428 C17.3860285,67.1185953 67.2554,16.5917106 128.963117,17.0024872 C188.934544,17.4010221 239.531905,67.1825241 238.995778,128.169251 C239.492444,188.602381 188.64743,239.424426 127.184644,238.997327 Z M127.184644,238.997327 C68.0323765,238.589271 16.6036091,189.498744 17.0023028,127.131428 C17.3860285,67.1185953 67.2554,16.5917106 128.963117,17.0024872 C188.934544,17.4010221 239.531905,67.1825241 238.995778,128.169251 C239.492444,188.602381 188.64743,239.424426 127.184644,238.997327 Z" fill="#000"> </path> <path d="M169.327319,127.956161 C169.042723,133.246373 164.421106,137.639224 159.866213,136.872586 C159.844426,136.872586 159.821277,136.872586 159.798128,136.872586 C154.753021,136.879395 150.658383,132.794288 150.652936,127.749182 C150.824511,122.690458 155.019915,118.703395 160.08,118.789182 C165.125106,118.813692 169.59966,123.077182 169.327319,127.956161 Z M88.2011915,179.220161 C90.1034894,179.27599 92.0071489,179.235139 94.2008511,179.235139 L94.2008511,193.021012 C80.5661277,195.326373 69.3348085,191.455054 66.5787234,179.929607 C65.6350638,175.69199 65.0549787,171.380841 64.8425532,167.04382 C64.5497872,162.452161 65.0563404,157.808756 64.706383,153.225267 C63.7368511,140.613182 62.1028085,136.30748 50,135.711054 L50,120.014714 C50.8674043,119.81182 51.7470638,119.662033 52.6321702,119.562629 C59.2677447,119.23582 62.0646809,117.201437 63.5489362,110.665267 C64.2243404,106.992756 64.6246809,103.275309 64.7431489,99.5428839 C65.268766,92.3258627 65.0822128,84.991735 66.2845957,77.8918201 C68.0221277,67.6245861 74.3962553,62.6366712 84.9249362,62.0783733 C87.9206809,61.9176925 90.9259574,62.0538627 94.3206809,62.0538627 L94.3206809,76.1447563 C92.9235745,76.2441605 91.6435745,76.4470542 90.3717447,76.4089265 C81.7916596,76.146118 81.3477447,79.0683308 80.7213617,86.1709691 C80.3305532,90.6250967 80.8697872,95.1554797 80.5661277,99.6245861 C80.2488511,104.071905 79.6537872,108.496075 78.7850213,112.869863 C77.547234,119.208586 73.6500426,123.922799 68.2495319,127.92348 C78.7332766,134.745607 79.9261277,145.346458 80.6069787,156.110714 C80.9732766,161.895224 80.8057872,167.720586 81.3926809,173.476501 C81.8502128,177.944246 83.5877447,179.08399 88.2011915,179.220161 Z M97.0372766,118.789182 C97.0917447,118.789182 97.1448511,118.789182 97.1993191,118.789182 C102.211745,118.872246 106.209702,123.002288 106.126638,128.016075 C106.126638,128.180841 106.121191,128.344246 106.11166,128.50765 C105.829787,133.407054 101.630298,137.149012 96.7308936,136.867139 C96.5334468,136.871224 96.3373617,136.867139 96.1399149,136.857607 C91.1506383,136.609778 87.3065532,132.36399 87.554383,127.374714 C87.8022128,122.385437 92.048,118.541352 97.0372766,118.789182 Z M128.273362,118.789182 C133.755574,118.746969 137.396766,122.29965 137.425362,127.719224 C137.455319,133.284501 134.003404,136.845352 128.556596,136.868501 C123.017191,136.893012 119.370553,133.389352 119.340596,128.002458 C119.324255,127.727395 119.32017,127.452331 119.32834,127.177267 C119.482213,122.390884 123.486979,118.635309 128.273362,118.789182 Z M193.673191,111.92348 C195.131574,117.370288 197.970723,119.284841 203.704851,119.546288 C204.644426,119.589863 205.579915,119.749182 206.868085,119.892161 L206.868085,135.584416 C206.170894,135.813182 205.456,135.984756 204.730213,136.096416 C197.046128,136.574373 193.54383,139.726714 192.76766,147.431224 C192.272,152.349692 192.312851,157.322629 191.972426,162.258799 C191.829447,167.678373 191.336511,173.082969 190.49634,178.438544 C188.535489,188.142033 182.477277,192.982884 172.467404,193.573863 C169.245617,193.764501 166.000681,193.60382 162.526979,193.60382 L162.526979,179.578288 C164.396596,179.462544 166.046979,179.303224 167.701447,179.263735 C173.682043,179.120756 175.796766,177.192586 176.089532,171.252841 C176.413617,164.727565 176.555234,158.194118 176.846638,151.66748 C177.270128,142.233607 179.853277,133.806033 188.641702,127.922118 C183.612936,124.336756 179.575489,119.994288 178.529702,114.138969 C177.264681,107.041778 176.85617,99.7879903 176.175319,92.5913946 C175.838979,88.9937776 175.855319,85.3648414 175.504,81.7699478 C175.125447,77.8890967 172.459234,76.5464584 168.926979,76.4593095 C166.903489,76.4102882 164.87183,76.4497776 162.284596,76.4497776 L162.284596,62.7537776 C178.793872,60.0126712 190.198128,65.5057776 191.257532,81.3015222 C191.701447,87.9343733 191.636085,94.5985435 192.060936,101.231395 C192.247489,104.839905 192.786723,108.421182 193.673191,111.92348 Z" fill="#FFFFFF"> </path> </g> </g></svg>
\ No newline at end of file
diff --git a/eventcatalog/public/icons/openapi.svg b/packages/core/eventcatalog/public/icons/openapi.svg
similarity index 100%
rename from eventcatalog/public/icons/openapi.svg
rename to packages/core/eventcatalog/public/icons/openapi.svg
diff --git a/packages/core/eventcatalog/public/icons/payments/stripe.svg b/packages/core/eventcatalog/public/icons/payments/stripe.svg
new file mode 100644
index 000000000..77e678c71
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/payments/stripe.svg
@@ -0,0 +1 @@
+<svg fill="#635BFF" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Stripe</title><path d="M13.976 9.15c-2.172-.806-3.356-1.426-3.356-2.409 0-.831.683-1.305 1.901-1.305 2.227 0 4.515.858 6.090 1.631l.890-5.494C18.252.975 15.687 0 12.585 0 10.469 0 8.703.555 7.439 1.583 6.123 2.658 5.444 4.208 5.444 6.078c0 3.39 2.072 4.839 5.446 6.057 2.172.78 2.901 1.331 2.901 2.179 0 .825-.707 1.306-1.978 1.306-1.575 0-4.18-.78-5.886-1.768L5.04 19.601c1.46.831 4.157 1.673 6.952 1.673 2.235 0 4.098-.527 5.355-1.523 1.406-1.085 2.135-2.682 2.135-4.764 0-3.471-2.118-4.926-5.507-6.117v.28z"/></svg>
diff --git a/packages/core/eventcatalog/public/icons/payments/stripe.webp b/packages/core/eventcatalog/public/icons/payments/stripe.webp
new file mode 100644
index 000000000..ed9193cce
Binary files /dev/null and b/packages/core/eventcatalog/public/icons/payments/stripe.webp differ
diff --git a/eventcatalog/public/icons/proto.svg b/packages/core/eventcatalog/public/icons/proto.svg
similarity index 100%
rename from eventcatalog/public/icons/proto.svg
rename to packages/core/eventcatalog/public/icons/proto.svg
diff --git a/eventcatalog/public/icons/protocols/kafka.svg b/packages/core/eventcatalog/public/icons/protocols/kafka.svg
similarity index 100%
rename from eventcatalog/public/icons/protocols/kafka.svg
rename to packages/core/eventcatalog/public/icons/protocols/kafka.svg
diff --git a/packages/core/eventcatalog/public/icons/protocols/mcp-dark.svg b/packages/core/eventcatalog/public/icons/protocols/mcp-dark.svg
new file mode 100644
index 000000000..18523c181
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/protocols/mcp-dark.svg
@@ -0,0 +1 @@
+<svg fill="#ffffff" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>ModelContextProtocol</title><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"/><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/protocols/mcp-light.svg b/packages/core/eventcatalog/public/icons/protocols/mcp-light.svg
new file mode 100644
index 000000000..d14b16bbe
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/protocols/mcp-light.svg
@@ -0,0 +1 @@
+<svg fill="#000000" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>ModelContextProtocol</title><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"/><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/protocols/mcp.svg b/packages/core/eventcatalog/public/icons/protocols/mcp.svg
new file mode 100644
index 000000000..18523c181
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/protocols/mcp.svg
@@ -0,0 +1 @@
+<svg fill="#ffffff" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>ModelContextProtocol</title><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"/><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/queue/sqs.svg b/packages/core/eventcatalog/public/icons/queue/sqs.svg
new file mode 100644
index 000000000..20726b52b
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/queue/sqs.svg
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="80px" height="80px" viewBox="0 0 80 80" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <!-- Generator: Sketch 64 (93537) - https://sketch.com -->
+    <title>Icon-Architecture/64/Arch_AWS-Simple-Queue-Service_64</title>
+    <desc>Created with Sketch.</desc>
+    <defs>
+        <linearGradient x1="0%" y1="100%" x2="100%" y2="0%" id="linearGradient-1">
+            <stop stop-color="#B0084D" offset="0%"></stop>
+            <stop stop-color="#FF4F8B" offset="100%"></stop>
+        </linearGradient>
+    </defs>
+    <g id="Icon-Architecture/64/Arch_AWS-Simple-Queue-Service_64" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="Icon-Architecture-BG/64/Application-Integration" fill="url(#linearGradient-1)">
+            <rect id="Rectangle" x="0" y="0" width="80" height="80"></rect>
+        </g>
+        <path d="M28.7169966,43.6876756 L31.7189265,40.721826 C31.9070474,40.5359011 32.0131156,40.2833614 32.0141233,40.019885 C32.0151169,39.7564086 31.9100493,39.5028747 31.722929,39.3159556 L28.7209992,36.3163014 L27.3020871,37.7181948 L28.5899149,39.0057494 L24.0089701,39.0057494 L24.0089701,40.9942506 L28.6059252,40.9942506 L27.3060896,42.2778282 L28.7169966,43.6876756 Z M51.627725,43.7781524 L55.630298,40.793412 C55.8804589,40.6054986 56.0295547,40.3112004 56.0295547,39.9990057 C56.0295547,39.6858168 55.8804589,39.3905244 55.6292974,39.202611 L51.6267243,36.2218476 L50.4259524,37.8126486 L52.0269816,39.0057494 L48.0244085,39.0057494 L48.0244085,40.9942506 L52.025981,40.9942506 L50.4249518,42.1873514 L51.627725,43.7781524 Z M35.2081695,40 C35.2081695,42.1107941 34.8429347,44.1012839 34.160496,45.8332685 C35.9606533,45.14127 37.9909585,44.7952708 40.0192624,44.7952708 C42.0475663,44.7952708 44.0778715,45.14127 45.8770281,45.8332685 C45.19559,44.1012839 44.8303552,42.1107941 44.8303552,40 C44.8303552,37.8892059 45.19559,35.8997104 45.8770281,34.1667315 C42.2777142,35.5497341 37.7608105,35.5497341 34.160496,34.1667315 C34.8429347,35.8997104 35.2081695,37.8892059 35.2081695,40 L35.2081695,40 Z M30.3060182,49.6511909 C30.1108927,49.4573121 30.0128297,49.2027839 30.0128297,48.9482557 C30.0128297,48.6937276 30.1108927,48.4391994 30.3060182,48.2453205 C32.1221857,46.4407556 33.206883,43.3575844 33.206883,40 C33.206883,36.6424156 32.1221857,33.5592444 30.3060182,31.7546795 C30.1108927,31.5608006 30.0128297,31.3062724 30.0128297,31.0517443 C30.0128297,30.7972161 30.1108927,30.5426879 30.3060182,30.3488091 C30.6972697,29.9600571 31.3296762,29.9600571 31.7209277,30.3488091 C35.5984204,34.2015303 44.4401044,34.2015303 48.317597,30.3488091 C48.7088485,29.9600571 49.3412551,29.9600571 49.7325066,30.3488091 C49.927632,30.5426879 50.0256951,30.7972161 50.0256951,31.0517443 C50.0256951,31.3062724 49.927632,31.5608006 49.7325066,31.7546795 C47.9163391,33.5592444 46.8316418,36.6424156 46.8316418,40 C46.8316418,43.3575844 47.9163391,46.4407556 49.7325066,48.2453205 C49.927632,48.4391994 50.0256951,48.6937276 50.0256951,48.9482557 C50.0256951,49.2027839 49.927632,49.4573121 49.7325066,49.6511909 C49.5373812,49.8450698 49.2812165,49.9425064 49.0250518,49.9425064 C48.7688871,49.9425064 48.5127225,49.8450698 48.317597,49.6511909 C44.4401044,45.7984697 35.5984204,45.7984697 31.7209277,49.6511909 C31.3296762,50.0399429 30.6972697,50.0399429 30.3060182,49.6511909 L30.3060182,49.6511909 Z M66.0009649,40.0049713 C66.0009649,39.0783297 65.6377314,38.2073661 64.9783075,37.5521549 C64.2978701,36.8750702 63.403295,36.5380193 62.5097205,36.5380193 C61.6161461,36.5380193 60.721571,36.8750702 60.0411336,37.5521549 C58.6792581,38.9043358 58.6792581,41.1046125 60.0411336,42.4577876 C61.4020084,43.8099684 63.6154313,43.8109627 64.9783075,42.4577876 C65.6377314,41.8025764 66.0009649,40.9316128 66.0009649,40.0049713 L66.0009649,40.0049713 Z M66.3932171,43.863658 C65.3225288,44.9275062 63.916625,45.4594303 62.5097205,45.4594303 C61.1028161,45.4594303 59.6969123,44.9275062 58.626224,43.863658 C56.4838468,41.7359616 56.4838468,38.2739809 58.626224,36.1462845 C60.7686012,34.0165997 64.2528411,34.0185882 66.3932171,36.1462845 C68.5355943,38.2739809 68.5355943,41.7359616 66.3932171,43.863658 L66.3932171,43.863658 Z M20.9800229,40.027839 C20.9800229,39.1011974 20.6167894,38.2302339 19.9573654,37.5750227 C19.2979415,36.9198115 18.421378,36.5588985 17.4887785,36.5588985 C16.5571796,36.5588985 15.6806161,36.9198115 15.0201916,37.5750227 C14.3607676,38.2302339 13.9985348,39.1011974 13.9985348,40.027839 C13.9985348,40.9534864 14.3607676,41.8244499 15.0201916,42.4806553 C16.34004,43.7900834 18.6385176,43.7900834 19.9573654,42.4806553 C20.6167894,41.8244499 20.9800229,40.9534864 20.9800229,40.027839 L20.9800229,40.027839 Z M21.372275,43.8865257 C20.3015867,44.9503739 18.8956829,45.482298 17.4887785,45.482298 C16.0828747,45.482298 14.6769709,44.9503739 13.605282,43.8865257 C11.464906,41.7588294 11.464906,38.2968487 13.605282,36.1691523 C15.7476592,34.0414559 19.2308984,34.0414559 21.372275,36.1691523 C23.5136516,38.2968487 23.5136516,41.7588294 21.372275,43.8865257 L21.372275,43.8865257 Z M54.8958259,54.856093 C50.901258,58.8261358 45.5888428,61.0114987 39.9392109,61.0114987 C34.2875777,61.0114987 28.9761632,58.8261358 24.9815953,54.856093 C22.241834,52.134829 20.7338646,48.8826352 19.9513616,46.6346345 L18.0601458,47.2848744 C18.9116932,49.730731 20.5577514,53.273246 23.5666857,56.2619634 C27.9394968,60.607833 33.7532342,63 39.9392109,63 C46.124187,63 51.9379244,60.607833 56.3107355,56.2619634 C58.8373597,53.7534691 60.8496533,50.563913 61.9793796,47.2818917 L60.0861625,46.6376173 C59.0534987,49.6382657 57.2103138,52.5573856 54.8958259,54.856093 L54.8958259,54.856093 Z M19.9503609,33.3663597 L18.0611465,32.7141313 C19.2719248,29.2501621 21.229183,26.0606061 23.5726896,23.7330653 C27.9434994,19.3911728 33.7552355,17 39.9392109,17 C46.1231863,17 51.9349225,19.3911728 56.3047316,23.7330653 C58.7713173,26.1838931 60.8396469,29.4569662 61.9773783,32.7141313 L60.0881638,33.3663597 C59.0444929,30.3836078 57.1502752,27.3849479 54.889822,25.1389357 C50.898256,21.1718757 45.5878422,18.9885013 39.9392109,18.9885013 C34.289579,18.9885013 28.9801658,21.1718757 24.9875992,25.1389357 C22.8542277,27.2596723 21.0650775,30.181775 19.9503609,33.3663597 L19.9503609,33.3663597 Z" id="AWS-Simple-Queue-Service_Icon_64_Squid" fill="#FFFFFF"></path>
+    </g>
+</svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/storage/s3.svg b/packages/core/eventcatalog/public/icons/storage/s3.svg
new file mode 100644
index 000000000..425fe6278
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/storage/s3.svg
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="80px" height="80px" viewBox="0 0 80 80" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <title>Icon-Architecture/64/Arch_Amazon-Simple-Storage-Service_64</title>
+    <defs>
+        <linearGradient x1="0%" y1="100%" x2="100%" y2="0%" id="linearGradient-1">
+            <stop stop-color="#1B660F" offset="0%"></stop>
+            <stop stop-color="#6CAE3E" offset="100%"></stop>
+        </linearGradient>
+    </defs>
+    <g id="Icon-Architecture/64/Arch_Amazon-Simple-Storage-Service_64" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="Rectangle" fill="url(#linearGradient-1)">
+            <rect x="0" y="0" width="80" height="80"></rect>
+        </g>
+        <g id="Icon-Service/64/Amazon-Simple-Storage-Service_64" transform="translate(8.000000, 8.000000)" fill="#FFFFFF">
+            <path d="M52.8359,34.8926 L53.2199,32.1886 C56.7609,34.3096 56.8069,35.1856 56.8059132,35.2096 C56.7999,35.2146 56.1959,35.7186 52.8359,34.8926 L52.8359,34.8926 Z M50.8929,34.3526 C44.7729,32.5006 36.2499,28.5906 32.8009,26.9606 C32.8009,26.9466 32.8049,26.9336 32.8049,26.9196 C32.8049,25.5946 31.7269,24.5166 30.4009,24.5166 C29.0769,24.5166 27.9989,25.5946 27.9989,26.9196 C27.9989,28.2446 29.0769,29.3226 30.4009,29.3226 C30.9829,29.3226 31.5109,29.1056 31.9279,28.7606 C35.9859,30.6816 44.4429,34.5346 50.6079,36.3546 L48.1699,53.5606 C48.1629,53.6076 48.1599,53.6546 48.1599,53.7016 C48.1599,55.2166 41.4529,57.9996 30.4939,57.9996 C19.4189,57.9996 12.6409,55.2166 12.6409,53.7016 C12.6409,53.6556 12.6379,53.6106 12.6319,53.5656 L7.5379,16.3586 C11.9469,19.3936 21.4299,20.9996 30.4999,20.9996 C39.5559,20.9996 49.0229,19.3996 53.4409,16.3736 L50.8929,34.3526 Z M6.9999,12.4776 C7.0719,11.1616 14.6339,5.9996 30.4999,5.9996 C46.3639,5.9996 53.9269,11.1606 53.9999,12.4776 L53.9999,12.9266 C53.1299,15.8776 43.3299,18.9996 30.4999,18.9996 C17.6479,18.9996 7.8429,15.8676 6.9999,12.9126 L6.9999,12.4776 Z M55.9999,12.4996 C55.9999,9.0346 46.0659,3.9996 30.4999,3.9996 C14.9339,3.9996 4.9999,9.0346 4.9999,12.4996 L5.0939,13.2536 L10.6419,53.7776 C10.7749,58.3096 22.8609,59.9996 30.4939,59.9996 C39.9659,59.9996 50.0289,57.8216 50.1589,53.7806 L52.5549,36.8836 C53.8879,37.2026 54.9849,37.3656 55.8659,37.3656 C57.0489,37.3656 57.8489,37.0766 58.3339,36.4986 C58.7319,36.0246 58.8839,35.4506 58.7699,34.8396 C58.5109,33.4556 56.8679,31.9636 53.5219,30.0546 L55.8979,13.2926 L55.9999,12.4996 Z" id="Amazon-Simple-Storage-Service-Icon_64_Squid"></path>
+        </g>
+    </g>
+</svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/streaming/kafka.svg b/packages/core/eventcatalog/public/icons/streaming/kafka.svg
new file mode 100644
index 000000000..dc2b7b8ba
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/streaming/kafka.svg
@@ -0,0 +1 @@
+<svg fill="#231F20" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Apache Kafka</title><path d="M9.71 2.136a1.43 1.43 0 0 0-2.047 0h-.007a1.48 1.48 0 0 0-.421 1.042c0 .41.161.777.422 1.039l.007.007c.257.264.616.426 1.019.426.404 0 .766-.162 1.027-.426l.003-.007c.261-.262.421-.629.421-1.039 0-.408-.159-.777-.421-1.042H9.71zM8.683 22.295c.404 0 .766-.167 1.027-.429l.003-.008c.261-.261.421-.631.421-1.036 0-.41-.159-.778-.421-1.044H9.71a1.42 1.42 0 0 0-1.027-.432 1.4 1.4 0 0 0-1.02.432h-.007c-.26.266-.422.634-.422 1.044 0 .406.161.775.422 1.036l.007.008c.258.262.617.429 1.02.429zm7.89-4.462c.359-.096.683-.33.882-.684l.027-.052a1.47 1.47 0 0 0 .114-1.067 1.454 1.454 0 0 0-.675-.896l-.021-.014a1.425 1.425 0 0 0-1.078-.132c-.36.091-.684.335-.881.686-.2.349-.241.75-.146 1.119.099.363.33.691.675.896h.002c.346.203.737.239 1.101.144zm-6.405-7.342a2.083 2.083 0 0 0-1.485-.627c-.58 0-1.103.242-1.482.627-.378.385-.612.916-.612 1.507s.233 1.124.612 1.514a2.08 2.08 0 0 0 2.967 0c.379-.39.612-.923.612-1.514s-.233-1.122-.612-1.507zm-.835-2.51c.843.141 1.6.552 2.178 1.144h.004c.092.093.182.196.265.299l1.446-.851a3.176 3.176 0 0 1-.047-1.808 3.149 3.149 0 0 1 1.456-1.926l.025-.016a3.062 3.062 0 0 1 2.345-.306c.77.21 1.465.721 1.898 1.482v.002c.431.757.518 1.626.313 2.408a3.145 3.145 0 0 1-1.456 1.928l-.198.118h-.02a3.095 3.095 0 0 1-2.154.201 3.127 3.127 0 0 1-1.514-.944l-1.444.848a4.162 4.162 0 0 1 0 2.879l1.444.846c.413-.47.939-.789 1.514-.944a3.041 3.041 0 0 1 2.371.319l.048.023v.002a3.17 3.17 0 0 1 1.408 1.906 3.215 3.215 0 0 1-.313 2.405l-.026.053-.003-.005a3.147 3.147 0 0 1-1.867 1.436 3.096 3.096 0 0 1-2.371-.318v-.006a3.156 3.156 0 0 1-1.456-1.927 3.175 3.175 0 0 1 .047-1.805l-1.446-.848a3.905 3.905 0 0 1-.265.294l-.004.005a3.938 3.938 0 0 1-2.178 1.138v1.699a3.09 3.09 0 0 1 1.56.862l.002.004c.565.572.914 1.368.914 2.243 0 .873-.35 1.664-.914 2.239l-.002.009a3.1 3.1 0 0 1-2.21.931 3.1 3.1 0 0 1-2.206-.93h-.002v-.009a3.186 3.186 0 0 1-.916-2.239c0-.875.35-1.672.916-2.243v-.004h.002a3.1 3.1 0 0 1 1.558-.862v-1.699a3.926 3.926 0 0 1-2.176-1.138l-.006-.005a4.098 4.098 0 0 1-1.173-2.874c0-1.122.452-2.136 1.173-2.872h.006a3.947 3.947 0 0 1 2.176-1.144V6.289a3.137 3.137 0 0 1-1.558-.864h-.002v-.004a3.192 3.192 0 0 1-.916-2.243c0-.871.35-1.669.916-2.243l.002-.002A3.084 3.084 0 0 1 8.683 0c.861 0 1.641.355 2.21.932v.002h.002c.565.574.914 1.372.914 2.243 0 .876-.35 1.667-.914 2.243l-.002.005a3.142 3.142 0 0 1-1.56.864v1.692zm8.121-1.129l-.012-.019a1.452 1.452 0 0 0-.87-.668 1.43 1.43 0 0 0-1.103.146h.002c-.347.2-.58.529-.677.896-.095.365-.054.768.146 1.119l.007.009c.2.347.519.579.874.673.357.103.755.059 1.098-.144l.019-.009a1.47 1.47 0 0 0 .657-.885 1.493 1.493 0 0 0-.141-1.118"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/tools/datadog.svg b/packages/core/eventcatalog/public/icons/tools/datadog.svg
new file mode 100644
index 000000000..eb381c15d
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/tools/datadog.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 256 274"><path fill="#632CA6" fill-rule="evenodd" d="M214.4 194.5l-22.8-15-19 31.7-22.1-6.4-19.5 29.7 1 9.3 105.8-19.5-6.1-66-17.3 36.2zM115.7 166l17-2.3c2.7 1.2 4.6 1.7 8 2.5a25 25 0 0019.8-1.8c2-1 6.3-5 8-7.1l69.6-12.7 7 86-119 21.4-10.4-86zm129.2-31l-6.9 1.4L224.8 0 .1 26l27.7 225 26.2-4c-2.1-3-5.4-6.6-11-11.2-7.7-6.5-5-17.4-.4-24.3 6-11.7 37.2-26.5 35.4-45.2-.6-6.7-1.7-15.6-8-21.6-.2 2.5.2 5 .2 5s-2.6-3.4-3.9-7.9c-1.2-1.7-2.2-2.2-3.6-4.5-1 2.6-.8 5.7-.8 5.7s-2.2-5-2.5-9.2a14.7 14.7 0 00-1.6 5.5s-2.7-8-2-12.1c-1.3-3.7-5-11-4-27.7 6.9 4.8 22 3.7 27.8-5 2-2.9 3.3-10.7-1-26.2-2.7-9.9-9.5-24.6-12.1-30.2l-.3.2a428 428 0 015.3 18.5C75 70.8 76 75.6 74.3 82c-1.3 5.6-4.5 9.2-12.6 13.3-8.1 4-18.9-5.9-19.6-6.4a43.3 43.3 0 01-14.6-21.5c-.7-5.5 3.1-8.7 5-13.2a50 50 0 00-5.8 2.2s3.7-3.8 8.2-7c2-1.3 3-2.1 5-3.8h-5.2s4.8-2.5 9.8-4.4c-3.7-.2-7.2 0-7.2 0s10.7-4.8 19.2-8.3c5.8-2.4 11.5-1.7 14.7 2.9 4.1 6 8.5 9.3 17.9 11.3 5.7-2.5 7.4-3.8 14.6-5.8 6.3-7 11.3-7.8 11.3-7.8s-2.5 2.2-3.1 5.8c3.6-2.8 7.5-5.2 7.5-5.2s-1.5 1.9-3 4.9l.4.5a79 79 0 019.1-4.5l-3 4c3.1 0 9.5.2 12 .5 14.7.3 17.7-15.7 23.3-17.7 7-2.5 10.2-4 22.2 7.8 10.3 10 18.4 28.2 14.4 32.3-3.4 3.3-10-1.3-17.3-10.5a39.5 39.5 0 01-8.2-17.8c-1.1-6.1-5.6-9.7-5.6-9.7s2.6 5.8 2.6 11c0 2.8.3 13.2 4.8 19.1-.4.9-.6 4.3-1.1 5-5.2-6.4-16.5-11-18.3-12.2 6.2 5 20.4 16.7 26 27.9 5.1 10.6 2 20.3 4.7 22.8.7.7 11.1 13.6 13.1 20.2 3.5 11.3.2 23.2-4.4 30.6l-12.7 2c-1.9-.5-3.1-.8-4.8-1.8a32 32 0 002.8-6.5l-.7-1.3a54.4 54.4 0 01-16.2 14.2 27.2 27.2 0 01-21 1.8 117.4 117.4 0 01-33.4-17.9s0 2.2.6 2.7c3.8 4.4 12.7 12.3 21.3 17.8l-18.3 2 8.7 67.4c-3.9.6-4.5.9-8.7 1.5a45.1 45.1 0 00-18.5-26.6A35 35 0 0065 200l-.5.6c6.2-.6 13.6.3 21.2 5.1 7.5 4.7 13.5 17 15.7 24.2 2.9 9.4 4.8 19.4-2.8 30-5.4 7.6-21.3 11.8-34 2.8 3.3 5.5 8 10 14.2 10.8 9.2 1.3 18-.3 24-6.5 5.2-5.3 7.9-16.4 7.2-28l8.1-1.2 3 20.9 135-16.3L245 135.1zm-82-56.8c-.5.9-1 1.4-.2 4.2v.2l.2.4.4.8c1.6 3.3 3.4 6.4 6.3 8 .8-.2 1.5-.3 2.4-.3 2.7-.1 4.5.3 5.6.9v-2.6c-.2-4.1.8-11.2-7.1-14.9-3-1.4-7.3-1-8.7.8l.7.2c2.1.7.7 1.4.3 2.3zm22.3 38.7a45.6 45.6 0 00-24.6 4.3c-2.8 2.2-1.5 6 .6 7.5 5.8 4.4 11 7.3 16.3 6.6 3.3-.4 6.2-5.7 8.3-10.4 1.4-3.3 1.4-6.8-.7-8zm-58-33.5c1.9-1.8-9.2-4.1-17.7 1.7-6.3 4.3-6.5 13.6-.5 18.8l1.6 1.2a51.7 51.7 0 0115.9-4.7c1.3-1.4 2.8-4 2.4-8.5-.5-6.2-5.2-5.2-1.7-8.5z" clip-rule="evenodd"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/tools/github.svg b/packages/core/eventcatalog/public/icons/tools/github.svg
new file mode 100644
index 000000000..7e5e12f78
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/tools/github.svg
@@ -0,0 +1 @@
+<svg viewBox="0 0 1024 1024" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8C0 11.54 2.29 14.53 5.47 15.59C5.87 15.66 6.02 15.42 6.02 15.21C6.02 15.02 6.01 14.39 6.01 13.72C4 14.09 3.48 13.23 3.32 12.78C3.23 12.55 2.84 11.84 2.5 11.65C2.22 11.5 1.82 11.13 2.49 11.12C3.12 11.11 3.57 11.7 3.72 11.94C4.44 13.15 5.59 12.81 6.05 12.6C6.12 12.08 6.33 11.73 6.56 11.53C4.78 11.33 2.92 10.64 2.92 7.58C2.92 6.71 3.23 5.99 3.74 5.43C3.66 5.23 3.38 4.41 3.82 3.31C3.82 3.31 4.49 3.1 6.02 4.13C6.66 3.95 7.34 3.86 8.02 3.86C8.7 3.86 9.38 3.95 10.02 4.13C11.55 3.09 12.22 3.31 12.22 3.31C12.66 4.41 12.38 5.23 12.3 5.43C12.81 5.99 13.12 6.7 13.12 7.58C13.12 10.65 11.25 11.33 9.47 11.53C9.76 11.78 10.01 12.26 10.01 13.01C10.01 14.08 10 14.94 10 15.21C10 15.42 10.15 15.67 10.55 15.59C13.71 14.53 16 11.53 16 8C16 3.58 12.42 0 8 0Z" transform="scale(64)" fill="#ffff"/></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/tools/hubspot.svg b/packages/core/eventcatalog/public/icons/tools/hubspot.svg
new file mode 100644
index 000000000..11866d1ff
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/tools/hubspot.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg id="b" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72"><g id="c"><circle cx="36" cy="36" r="36" fill="#333" stroke-width="0"/><path d="m10.56,29.14v5.19h-4.77v-5.19h-2.26v12.4h2.26v-5.02h4.77v5.02h2.26v-12.4h-2.26Zm9.51,8.39c0,1.03-.84,1.87-1.87,1.87s-1.87-.84-1.87-1.87v-5.31h-2.15v5.31c0,2.22,1.8,4.02,4.02,4.02,2.22,0,4.01-1.8,4.02-4.02v-5.31h-2.14v5.31Zm15.91-4.76c0-1.09.72-1.43,1.51-1.43.64,0,1.48.48,2.02,1.07l1.41-1.66c-.7-.95-2.13-1.61-3.29-1.61-2.33,0-4.01,1.36-4.01,3.63,0,4.2,5.13,2.86,5.13,5.21,0,.72-.7,1.36-1.51,1.36-1.27,0-1.68-.62-2.27-1.28l-1.56,1.62c1,1.23,2.23,1.85,3.7,1.85,2.21,0,3.99-1.38,3.99-3.54,0-4.66-5.13-3.21-5.13-5.23m31.74,6.79c-1.27,0-1.63-.55-1.63-1.39v-3.72h1.97v-1.89h-1.97v-2.49l-2.18.98v7.58c0,1.94,1.34,2.92,3.17,2.92.29,0,.58-.02.86-.07l.53-1.96c-.24.02-.51.03-.76.03m-39.47-7.27c-1.06,0-1.81.31-2.52,1.01v-4.08h-2.15v7.56c0,2.83,2.05,4.77,4.35,4.77,2.55,0,4.8-1.97,4.8-4.63s-2.07-4.63-4.47-4.63m-.01,7.1c-1.35,0-2.44-1.09-2.44-2.44s1.09-2.44,2.44-2.44,2.44,1.09,2.44,2.44-1.09,2.44-2.44,2.44h0m23.37-2.58c0-2.66-2.24-4.63-4.8-4.63-2.3,0-4.35,1.94-4.35,4.77v7.57h2.15v-4.09c.72.7,1.46,1.01,2.52,1.01,2.4,0,4.47-2.01,4.47-4.63m-2.04-.03c0,1.35-1.09,2.44-2.44,2.44s-2.44-1.09-2.44-2.44h0c0-1.35,1.09-2.44,2.44-2.44s2.44,1.09,2.44,2.44" fill="#fff" stroke-width="0"/><path d="m58.55,32.07v-2.16c.58-.27.96-.86.96-1.5v-.05c0-.92-.75-1.66-1.66-1.66h-.05c-.92,0-1.66.75-1.66,1.66h0v.05c0,.64.38,1.23.96,1.5v2.16c-.82.13-1.59.47-2.24.99l-5.93-4.62c.04-.15.06-.31.07-.47,0-1.04-.84-1.88-1.87-1.88-1.04,0-1.88.84-1.88,1.87s.84,1.88,1.87,1.88c0,0,0,0,0,0,.32,0,.64-.09.92-.25l5.84,4.54c-1.07,1.62-1.04,3.73.07,5.32l-1.77,1.78c-.14-.05-.29-.07-.44-.07-.85,0-1.54.69-1.54,1.54,0,.85.69,1.54,1.54,1.54.85,0,1.54-.69,1.54-1.54,0-.15-.03-.3-.07-.44l1.76-1.76c2.07,1.6,5.04,1.21,6.64-.86,1.6-2.07,1.21-5.04-.86-6.64-.64-.49-1.38-.81-2.18-.93m-.73,7.11c-1.34.04-2.46-1.02-2.5-2.36-.04-1.34,1.02-2.46,2.36-2.5.04,0,.09,0,.13,0,1.34.05,2.39,1.17,2.34,2.51-.04,1.27-1.07,2.3-2.34,2.34" fill="#fff" stroke-width="0"/></g></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/tools/slack.svg b/packages/core/eventcatalog/public/icons/tools/slack.svg
new file mode 100644
index 000000000..515d00679
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/tools/slack.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg id="b" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72"><g id="c"><circle cx="36" cy="36" r="36" fill="#333" stroke-width="0"/><path d="m13.3,57.05l.84-1.94c.9.67,2.1,1.02,3.28,1.02.87,0,1.42-.34,1.42-.85-.01-1.42-5.23-.31-5.27-3.88-.01-1.81,1.6-3.21,3.88-3.21,1.36,0,2.72.34,3.68,1.1l-.78,1.97c-.89-.56-1.99-.97-3.04-.97-.71,0-1.19.34-1.19.77.01,1.4,5.27.63,5.33,4.05,0,1.86-1.57,3.16-3.83,3.16-1.65,0-3.17-.39-4.32-1.22" fill="#fff" stroke-width="0"/><path d="m45.29,54.42c-.42.72-1.2,1.22-2.1,1.22-1.33,0-2.41-1.07-2.41-2.41s1.07-2.41,2.41-2.41c.9,0,1.68.5,2.1,1.22l2.3-1.27c-.86-1.54-2.51-2.58-4.4-2.58-2.78,0-5.04,2.26-5.04,5.04s2.26,5.04,5.04,5.04c1.9,0,3.53-1.04,4.4-2.58l-2.3-1.27h0Z" fill="#fff" stroke-width="0"/><rect x="22.62" y="44" width="2.88" height="14.08" fill="#fff" stroke-width="0"/><polygon points="48.72 44 48.72 58.09 51.6 58.09 51.6 53.87 55.02 58.09 58.7 58.09 54.36 53.07 58.38 48.39 54.85 48.39 51.6 52.28 51.6 44 48.72 44" fill="#fff" stroke-width="0"/><path d="m34.05,54.44c-.42.69-1.27,1.2-2.25,1.2-1.33,0-2.41-1.07-2.41-2.41s1.07-2.41,2.41-2.41c.97,0,1.83.54,2.25,1.24v2.38Zm0-6.05v1.14c-.47-.8-1.64-1.35-2.86-1.35-2.53,0-4.52,2.23-4.52,5.03s1.99,5.06,4.52,5.06c1.22,0,2.4-.55,2.86-1.35v1.14h2.88v-9.68h-2.88Z" fill="#fff" stroke-width="0"/><path d="m26.71,28.85c0,1.87-1.51,3.37-3.37,3.37s-3.38-1.51-3.38-3.37,1.51-3.37,3.37-3.37h3.37v3.37h.01Z" fill="#fff" stroke-width="0"/><path d="m28.39,28.85c0-1.87,1.51-3.37,3.37-3.37s3.37,1.51,3.37,3.37v8.43c0,1.87-1.51,3.37-3.37,3.37s-3.37-1.5-3.37-3.37v-8.43Z" fill="#fff" stroke-width="0"/><path d="m31.77,15.29c-1.87,0-3.37-1.51-3.37-3.37s1.51-3.37,3.37-3.37,3.37,1.51,3.37,3.37v3.37h-3.37Z" fill="#fff" stroke-width="0"/><path d="m31.77,17.01c1.87,0,3.37,1.51,3.37,3.37s-1.51,3.37-3.37,3.37h-8.47c-1.87,0-3.37-1.51-3.37-3.37s1.51-3.37,3.37-3.37h8.47Z" fill="#fff" stroke-width="0"/><path d="m45.29,20.38c0-1.87,1.51-3.37,3.37-3.37s3.37,1.51,3.37,3.37-1.51,3.37-3.37,3.37h-3.37v-3.37Z" fill="#fff" stroke-width="0"/><path d="m43.61,20.38c0,1.87-1.51,3.37-3.37,3.37s-3.37-1.51-3.37-3.37v-8.46c0-1.87,1.51-3.37,3.37-3.37s3.37,1.5,3.37,3.37v8.46Z" fill="#fff" stroke-width="0"/><path d="m40.23,33.91c1.87,0,3.37,1.51,3.37,3.37s-1.51,3.37-3.37,3.37-3.37-1.51-3.37-3.37v-3.37h3.37Z" fill="#fff" stroke-width="0"/><path d="m40.23,32.22c-1.87,0-3.37-1.51-3.37-3.37s1.51-3.37,3.37-3.37h8.47c1.87,0,3.37,1.51,3.37,3.37s-1.51,3.37-3.37,3.37h-8.47Z" fill="#fff" stroke-width="0"/></g></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/tools/snowflake.svg b/packages/core/eventcatalog/public/icons/tools/snowflake.svg
new file mode 100644
index 000000000..b9ca737ff
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/tools/snowflake.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg id="b" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72"><g id="c"><circle cx="36" cy="36" r="36" fill="#333" stroke-width="0"/><path id="d" d="m54.46,49.5l-10.87-6.28c-1.53-.88-3.48-.36-4.36,1.17-.34.6-.48,1.26-.41,1.91v12.27c0,1.75,1.43,3.18,3.18,3.18s3.18-1.43,3.18-3.18v-7.06l6.09,3.52c1.53.88,3.48.36,4.36-1.17.88-1.53.36-3.48-1.17-4.36" fill="#fff" stroke-width="0"/><path id="e" d="m27.43,36.04c.02-1.13-.58-2.19-1.56-2.76l-10.87-6.27c-.47-.27-1.01-.42-1.55-.42-1.12,0-2.15.6-2.71,1.56-.86,1.49-.35,3.4,1.14,4.26l6.26,3.61-6.26,3.62c-.72.42-1.24,1.09-1.45,1.89-.22.81-.11,1.65.31,2.37.56.96,1.59,1.56,2.7,1.56.55,0,1.09-.14,1.56-.42l10.87-6.27c.97-.56,1.57-1.61,1.56-2.73" fill="#fff" stroke-width="0"/><path id="f" d="m17.47,22.56l10.87,6.27c1.27.74,2.83.5,3.83-.48.63-.58,1.03-1.42,1.03-2.34v-12.58c0-1.76-1.43-3.18-3.18-3.18s-3.18,1.43-3.18,3.18v7.16l-6.17-3.56c-1.53-.88-3.48-.36-4.36,1.17-.88,1.53-.36,3.48,1.17,4.36" fill="#fff" stroke-width="0"/><path id="g" d="m41.91,36.55c0,.24-.14.57-.31.75l-4.31,4.31c-.17.17-.51.31-.75.31h-1.1c-.24,0-.58-.14-.75-.31l-4.31-4.31c-.17-.18-.31-.51-.31-.75v-1.1c0-.25.14-.58.31-.75l4.31-4.31c.17-.17.51-.31.75-.31h1.1c.24,0,.58.14.75.31l4.31,4.31c.17.17.31.5.31.75v1.1Zm-3.84-.53v-.05c0-.18-.1-.42-.23-.55l-1.27-1.27c-.12-.13-.37-.23-.55-.23h-.05c-.18,0-.42.1-.55.23l-1.27,1.27c-.12.12-.23.37-.23.55v.05c0,.18.1.43.23.55l1.27,1.27c.13.12.37.23.55.23h.05c.18,0,.43-.1.55-.23l1.27-1.27c.12-.12.23-.37.23-.55Z" fill="#fff" stroke-width="0"/><path id="h" d="m43.59,28.84l10.87-6.27c1.53-.88,2.05-2.84,1.17-4.36-.88-1.53-2.84-2.05-4.36-1.17l-6.09,3.52v-7.11c0-1.76-1.43-3.18-3.18-3.18s-3.18,1.43-3.18,3.18v12.33c-.06.64.06,1.3.41,1.91.88,1.53,2.84,2.05,4.36,1.17" fill="#fff" stroke-width="0"/><path id="i" d="m30.51,42.85c-.72-.14-1.49-.02-2.18.37l-10.87,6.28c-1.53.88-2.05,2.83-1.17,4.36.88,1.53,2.84,2.05,4.36,1.17l6.17-3.56v7.1c0,1.75,1.43,3.18,3.18,3.18s3.18-1.43,3.18-3.18v-12.58c0-1.59-1.16-2.9-2.68-3.14" fill="#fff" stroke-width="0"/><path id="j" d="m61.25,28.12c-.88-1.53-2.84-2.05-4.36-1.17l-10.87,6.27c-1.04.6-1.61,1.7-1.6,2.82,0,1.12.56,2.2,1.6,2.79l10.87,6.28c1.53.88,3.48.36,4.36-1.17.88-1.53.36-3.48-1.17-4.36l-6.15-3.55,6.15-3.55c1.53-.88,2.05-2.83,1.17-4.36" fill="#fff" stroke-width="0"/></g></svg>
\ No newline at end of file
diff --git a/packages/core/eventcatalog/public/icons/tools/zendesk.svg b/packages/core/eventcatalog/public/icons/tools/zendesk.svg
new file mode 100644
index 000000000..0660c8e32
--- /dev/null
+++ b/packages/core/eventcatalog/public/icons/tools/zendesk.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg id="b" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72"><g id="c"><circle cx="36" cy="36" r="36" fill="#333" stroke-width="0"/><path d="m35.43,19.36v17.66h-14.63l14.63-17.66Zm0-6.34c0,4.04-3.27,7.31-7.31,7.31s-7.31-3.27-7.31-7.31h14.63Zm2.41,24c0-4.04,3.27-7.31,7.31-7.31s7.31,3.27,7.31,7.31h-14.63Zm0-6.34V13.03h14.63l-14.63,17.66h0Zm8.18,21.45c.75.02,1.48-.26,2.03-.78l1,1.08c-.66.68-1.58,1.19-3.01,1.19-2.45,0-4.04-1.63-4.04-3.83-.04-2.07,1.61-3.79,3.68-3.83.04,0,.09,0,.13,0,2.43,0,3.82,1.85,3.69,4.42h-5.76c.2,1.07.95,1.75,2.26,1.75m1.75-2.97c-.16-1-.75-1.73-1.94-1.73-1.11,0-1.88.63-2.08,1.73h4.02,0Zm-39.54,2.89l4.43-4.5h-4.32v-1.41h6.38v1.44l-4.43,4.5h4.49v1.41h-6.55v-1.44h0Zm11.52.08c.75.02,1.48-.26,2.03-.78l1,1.08c-.66.68-1.58,1.19-3.01,1.19-2.45,0-4.04-1.63-4.04-3.83-.04-2.07,1.61-3.79,3.68-3.83.04,0,.09,0,.13,0,2.43,0,3.82,1.85,3.69,4.42h-5.75c.2,1.07.95,1.75,2.26,1.75m1.75-2.97c-.16-1-.75-1.73-1.94-1.73-1.11,0-1.88.63-2.08,1.73h4.02,0Zm11.3.63c0-2.35,1.76-3.82,3.69-3.82.94-.01,1.84.39,2.45,1.1v-4.34h1.56v10.73h-1.56v-1.01c-.6.74-1.51,1.17-2.47,1.16-1.88,0-3.68-1.49-3.68-3.82m6.23-.02c-.03-1.29-1.11-2.31-2.4-2.27-1.29.03-2.31,1.11-2.27,2.4.03,1.26,1.07,2.27,2.33,2.27,1.35,0,2.33-1.07,2.33-2.4m11.5,2.13l1.42-.74c.38.68,1.11,1.09,1.89,1.07.89,0,1.35-.45,1.35-.97,0-.59-.86-.72-1.79-.91-1.25-.27-2.56-.68-2.56-2.19,0-1.16,1.11-2.24,2.85-2.22,1.37,0,2.39.54,2.97,1.42l-1.31.72c-.37-.55-.99-.86-1.65-.84-.84,0-1.27.41-1.27.88,0,.53.68.68,1.74.91,1.21.27,2.58.66,2.58,2.19,0,1.01-.89,2.38-2.98,2.37-1.53,0-2.61-.62-3.23-1.71m10.47-1.7l-1.24,1.35v1.91h-1.56v-10.73h1.56v7.03l3.32-3.65h1.91l-2.88,3.15,2.95,4.21h-1.77l-2.29-3.26h0Zm-32.93-4.23c-1.86,0-3.42,1.2-3.42,3.21v4.3h1.6v-4.1c0-1.2.69-1.93,1.88-1.93s1.77.72,1.77,1.93v4.1h1.59v-4.3c0-2-1.56-3.21-3.42-3.21" fill="#fff" stroke-width="0"/></g></svg>
\ No newline at end of file
diff --git a/eventcatalog/public/icons/x-twitter.svg b/packages/core/eventcatalog/public/icons/x-twitter.svg
similarity index 100%
rename from eventcatalog/public/icons/x-twitter.svg
rename to packages/core/eventcatalog/public/icons/x-twitter.svg
diff --git a/eventcatalog/public/icons/youtube.svg b/packages/core/eventcatalog/public/icons/youtube.svg
similarity index 100%
rename from eventcatalog/public/icons/youtube.svg
rename to packages/core/eventcatalog/public/icons/youtube.svg
diff --git a/eventcatalog/public/images/ai-placeholder.png b/packages/core/eventcatalog/public/images/ai-placeholder.png
similarity index 100%
rename from eventcatalog/public/images/ai-placeholder.png
rename to packages/core/eventcatalog/public/images/ai-placeholder.png
diff --git a/eventcatalog/public/images/custom-docs-placeholder.png b/packages/core/eventcatalog/public/images/custom-docs-placeholder.png
similarity index 100%
rename from eventcatalog/public/images/custom-docs-placeholder.png
rename to packages/core/eventcatalog/public/images/custom-docs-placeholder.png
diff --git a/eventcatalog/public/images/eventcatalog-upgrade.png b/packages/core/eventcatalog/public/images/eventcatalog-upgrade.png
similarity index 100%
rename from eventcatalog/public/images/eventcatalog-upgrade.png
rename to packages/core/eventcatalog/public/images/eventcatalog-upgrade.png
diff --git a/examples/default/public/logo-old.png b/packages/core/eventcatalog/public/logo-old.png
similarity index 100%
rename from examples/default/public/logo-old.png
rename to packages/core/eventcatalog/public/logo-old.png
diff --git a/packages/core/eventcatalog/public/logo.png b/packages/core/eventcatalog/public/logo.png
new file mode 100644
index 000000000..670057fbb
Binary files /dev/null and b/packages/core/eventcatalog/public/logo.png differ
diff --git a/eventcatalog/public/openapi.yml b/packages/core/eventcatalog/public/openapi.yml
similarity index 100%
rename from eventcatalog/public/openapi.yml
rename to packages/core/eventcatalog/public/openapi.yml
diff --git a/eventcatalog/public/opengraph.png b/packages/core/eventcatalog/public/opengraph.png
similarity index 100%
rename from eventcatalog/public/opengraph.png
rename to packages/core/eventcatalog/public/opengraph.png
diff --git a/eventcatalog/public/rss.xsl b/packages/core/eventcatalog/public/rss.xsl
similarity index 100%
rename from eventcatalog/public/rss.xsl
rename to packages/core/eventcatalog/public/rss.xsl
diff --git a/eventcatalog/public/slack-icon.svg b/packages/core/eventcatalog/public/slack-icon.svg
similarity index 100%
rename from eventcatalog/public/slack-icon.svg
rename to packages/core/eventcatalog/public/slack-icon.svg
diff --git a/eventcatalog/public/studio-bg.png b/packages/core/eventcatalog/public/studio-bg.png
similarity index 100%
rename from eventcatalog/public/studio-bg.png
rename to packages/core/eventcatalog/public/studio-bg.png
diff --git a/packages/core/eventcatalog/src/__tests__/api/api-catalog.spec.ts b/packages/core/eventcatalog/src/__tests__/api/api-catalog.spec.ts
new file mode 100644
index 000000000..6782be994
--- /dev/null
+++ b/packages/core/eventcatalog/src/__tests__/api/api-catalog.spec.ts
@@ -0,0 +1,267 @@
+import type { CollectionKey } from 'astro:content';
+import { expect, describe, it, vi } from 'vitest';
+import { GET, HEAD } from '../../pages/.well-known/api-catalog.ts';
+import { GET as GETSpecification } from '../../pages/api-catalog/specifications/[collection]/[id]/[version]/[specification].ts';
+
+const mockIsEventCatalogMCPEnabled = vi.hoisted(() => vi.fn(() => true));
+
+const mockServices = [
+  {
+    collection: 'services',
+    filePath: '/catalog/services/OrderService/index.mdx',
+    data: {
+      name: 'Order Service',
+      id: 'OrderService',
+      version: '1.0.0',
+      summary: 'Order Service summary',
+      specifications: [
+        { type: 'openapi', path: 'openapi.yml' },
+        { type: 'openapi', path: 'admin-openapi.yml', name: 'Admin OpenAPI' },
+        { type: 'graphql', path: 'schema.graphql', name: 'GraphQL schema' },
+      ],
+    },
+  },
+  {
+    collection: 'services',
+    filePath: '/catalog/services/InventoryService/index.mdx',
+    data: {
+      name: 'Inventory Service',
+      id: 'InventoryService',
+      version: '2.0.0',
+      summary: 'Inventory Service summary',
+      specifications: [{ type: 'asyncapi', path: 'asyncapi.json' }],
+    },
+  },
+  {
+    collection: 'services',
+    filePath: '/catalog/services/CustomerService/index.mdx',
+    data: {
+      name: 'Customer Service',
+      id: 'CustomerService',
+      version: '1.0.0',
+      summary: 'Customer Service summary',
+    },
+  },
+  {
+    collection: 'services',
+    filePath: '/catalog/services/HiddenService/index.mdx',
+    data: {
+      name: 'Hidden Service',
+      id: 'HiddenService',
+      version: '1.0.0',
+      hidden: true,
+      specifications: [{ type: 'openapi', path: 'hidden-openapi.yml' }],
+    },
+  },
+];
+
+const mockDomains = [
+  {
+    collection: 'domains',
+    filePath: '/catalog/domains/Billing/index.mdx',
+    data: {
+      name: 'Billing',
+      id: 'Billing',
+      version: '1.0.0',
+      summary: 'Billing domain summary',
+      specifications: [{ type: 'openapi', path: 'billing-openapi.yml' }],
+    },
+  },
+];
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: (key: CollectionKey) => {
+      switch (key) {
+        case 'services':
+          return Promise.resolve(mockServices);
+        case 'domains':
+          return Promise.resolve(mockDomains);
+        default:
+          return Promise.resolve([]);
+      }
+    },
+  };
+});
+
+vi.mock('@utils/resource-files', () => {
+  return {
+    readResourceFile: (_service: unknown, path: string) => {
+      switch (path) {
+        case 'openapi.yml':
+          return 'openapi: 3.1.0\nservers:\n  - url: https://api.example.com/orders\n';
+        case 'admin-openapi.yml':
+          return 'openapi: 3.1.0\nservers:\n  - url: https://admin-api.example.com/orders\n';
+        case 'billing-openapi.yml':
+          return 'openapi: 3.1.0\nservers:\n  - url: https://api.example.com/billing\n';
+        case 'asyncapi.json':
+          return JSON.stringify({
+            asyncapi: '3.0.0',
+            servers: {
+              production: {
+                host: 'unused.example.com',
+                url: 'https://events.example.com/inventory',
+              },
+            },
+          });
+        case 'schema.graphql':
+          return 'type Query { order(id: ID!): Order }';
+        default:
+          return null;
+      }
+    },
+  };
+});
+
+vi.mock('@utils/feature', () => {
+  return {
+    isEventCatalogMCPEnabled: () => mockIsEventCatalogMCPEnabled(),
+  };
+});
+
+describe('/.well-known/api-catalog', () => {
+  it('returns an RFC 9727 Linkset for services with specifications', async () => {
+    const response = await GET({ request: new Request('https://catalog.example.com/.well-known/api-catalog') } as any);
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get('Content-Type')).toBe(
+      'application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"'
+    );
+
+    expect(await response.json()).toEqual({
+      linkset: [
+        {
+          anchor: 'https://events.example.com/inventory',
+          'service-desc': [
+            {
+              href: 'https://catalog.example.com/api-catalog/specifications/services/InventoryService/2.0.0/asyncapi-YXN5bmNhcGkuanNvbg',
+              type: 'application/json',
+              title: 'Inventory Service AsyncAPI',
+            },
+          ],
+          'service-doc': [
+            {
+              href: 'https://catalog.example.com/docs/services/InventoryService/2.0.0.md',
+              type: 'text/markdown',
+              title: 'Inventory Service documentation',
+            },
+            {
+              href: 'https://catalog.example.com/docs/services/InventoryService/2.0.0',
+              type: 'text/html',
+              title: 'Inventory Service documentation',
+            },
+          ],
+        },
+        {
+          anchor: 'https://api.example.com/orders',
+          'service-desc': [
+            {
+              href: 'https://catalog.example.com/api-catalog/specifications/services/OrderService/1.0.0/openapi-b3BlbmFwaS55bWw',
+              type: 'application/yaml',
+              title: 'Order Service OpenAPI',
+            },
+            {
+              href: 'https://catalog.example.com/api-catalog/specifications/services/OrderService/1.0.0/openapi-YWRtaW4tb3BlbmFwaS55bWw',
+              type: 'application/yaml',
+              title: 'Order Service Admin OpenAPI',
+            },
+            {
+              href: 'https://catalog.example.com/api-catalog/specifications/services/OrderService/1.0.0/graphql-c2NoZW1hLmdyYXBocWw',
+              type: 'application/graphql',
+              title: 'Order Service GraphQL schema',
+            },
+          ],
+          'service-doc': [
+            {
+              href: 'https://catalog.example.com/docs/services/OrderService/1.0.0.md',
+              type: 'text/markdown',
+              title: 'Order Service documentation',
+            },
+            {
+              href: 'https://catalog.example.com/docs/services/OrderService/1.0.0',
+              type: 'text/html',
+              title: 'Order Service documentation',
+            },
+          ],
+        },
+        {
+          anchor: 'https://api.example.com/billing',
+          'service-desc': [
+            {
+              href: 'https://catalog.example.com/api-catalog/specifications/domains/Billing/1.0.0/openapi-YmlsbGluZy1vcGVuYXBpLnltbA',
+              type: 'application/yaml',
+              title: 'Billing OpenAPI',
+            },
+          ],
+          'service-doc': [
+            {
+              href: 'https://catalog.example.com/docs/domains/Billing/1.0.0.md',
+              type: 'text/markdown',
+              title: 'Billing documentation',
+            },
+            {
+              href: 'https://catalog.example.com/docs/domains/Billing/1.0.0',
+              type: 'text/html',
+              title: 'Billing documentation',
+            },
+          ],
+        },
+        {
+          anchor: 'https://catalog.example.com/docs/mcp',
+          'service-desc': [
+            {
+              href: 'https://catalog.example.com/docs/mcp',
+              type: 'application/json',
+              title: 'EventCatalog MCP Server',
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  it('returns a Link header for HEAD requests', async () => {
+    const response = await HEAD({ request: new Request('https://catalog.example.com/.well-known/api-catalog') } as any);
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get('Content-Type')).toBe(
+      'application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"'
+    );
+    expect(response.headers.get('Link')).toBe('<https://catalog.example.com/.well-known/api-catalog>; rel="api-catalog"');
+    expect(await response.text()).toBe('');
+  });
+
+  it('serves raw service and domain specifications referenced by the API catalog', async () => {
+    const response = await GETSpecification({
+      request: new Request(
+        'https://catalog.example.com/api-catalog/specifications/domains/Billing/1.0.0/openapi-YmlsbGluZy1vcGVuYXBpLnltbA'
+      ),
+      props: {},
+      params: { collection: 'domains', id: 'Billing', version: '1.0.0', specification: 'openapi-YmlsbGluZy1vcGVuYXBpLnltbA' },
+    } as any);
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get('Content-Type')).toBe('application/yaml');
+    expect(await response.text()).toBe('openapi: 3.1.0\nservers:\n  - url: https://api.example.com/billing\n');
+  });
+
+  it('serves the exact matching specification when a resource has multiple specs of the same type', async () => {
+    const response = await GETSpecification({
+      request: new Request(
+        'https://catalog.example.com/api-catalog/specifications/services/OrderService/1.0.0/openapi-YWRtaW4tb3BlbmFwaS55bWw'
+      ),
+      props: {},
+      params: {
+        collection: 'services',
+        id: 'OrderService',
+        version: '1.0.0',
+        specification: 'openapi-YWRtaW4tb3BlbmFwaS55bWw',
+      },
+    } as any);
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get('Content-Type')).toBe('application/yaml');
+    expect(await response.text()).toBe('openapi: 3.1.0\nservers:\n  - url: https://admin-api.example.com/orders\n');
+  });
+});
diff --git a/packages/core/eventcatalog/src/__tests__/api/message-schemas-api.spec.ts b/packages/core/eventcatalog/src/__tests__/api/message-schemas-api.spec.ts
new file mode 100644
index 000000000..3d171f716
--- /dev/null
+++ b/packages/core/eventcatalog/src/__tests__/api/message-schemas-api.spec.ts
@@ -0,0 +1,226 @@
+import type { CollectionKey } from 'astro:content';
+import { expect, describe, it, vi, beforeEach } from 'vitest';
+import { getStaticPaths, GET } from '../../enterprise/api/schemas/[collection]/[id]/[version]/index.ts';
+import path from 'path';
+import fs from 'node:fs';
+
+const __dirname = path.dirname(new URL(import.meta.url).pathname);
+
+let mockSchemas: any[] = [];
+
+let mockIsEventCatalogScaleEnabled = vi.fn();
+let mockIsSSR = vi.fn().mockReturnValue(false);
+
+const schemaContent = (fileName: string) => fs.readFileSync(path.join(__dirname, 'schemas', fileName), 'utf8');
+
+const schemaEntry = ({
+  collection,
+  id,
+  version,
+  file,
+  latest = true,
+}: {
+  collection: 'events' | 'commands' | 'queries';
+  id: string;
+  version: string;
+  file: string;
+  latest?: boolean;
+}) => ({
+  collection: 'schemas',
+  data: {
+    id: `schema:${collection}:${id}:${version}:${file}`,
+    name: `${id} schema`,
+    version,
+    format: file.split('.').pop() === 'avro' ? 'avro' : 'jsonschema',
+    content: schemaContent(file),
+    file,
+    filePath: path.join(__dirname, 'schemas', file),
+    latest,
+    message: {
+      collection,
+      id,
+      name: `${id} message`,
+      version,
+      summary: `${id} summary`,
+      owners: ['orders-team'],
+    },
+    source: {
+      provider: 'file',
+      path: file,
+    },
+  },
+});
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: (key: CollectionKey) => {
+      switch (key) {
+        case 'schemas':
+          return Promise.resolve(mockSchemas);
+        default:
+          return Promise.resolve([]);
+      }
+    },
+  };
+});
+
+vi.mock('@utils/feature', () => {
+  return {
+    isEventCatalogScaleEnabled: () => mockIsEventCatalogScaleEnabled(),
+    isSSR: () => mockIsSSR(),
+  };
+});
+
+describe('api/schemas/[collection]/[id]/[version]/index.ts', () => {
+  beforeEach(() => {
+    mockSchemas = [
+      schemaEntry({ collection: 'events', id: 'OrderPlaced', version: '1.0.0', file: 'test-schema.json' }),
+      schemaEntry({ collection: 'commands', id: 'CreateOrder', version: '1.0.0', file: 'test-schema.avro' }),
+      schemaEntry({ collection: 'queries', id: 'GetOrder', version: '1.0.0', file: 'test-schema.avro' }),
+    ];
+  });
+
+  describe('getStaticPaths', () => {
+    it('returns static paths for messages (events, commands, queries) that have a schema including latest paths', async () => {
+      const staticPaths = await getStaticPaths();
+      // 3 versioned paths + 3 latest paths
+      expect(staticPaths).toHaveLength(6);
+
+      const versionedPaths = staticPaths.filter((p) => p.params.version !== 'latest');
+      const latestPaths = staticPaths.filter((p) => p.params.version === 'latest');
+
+      // Check versioned paths
+      expect(versionedPaths.map((path) => path.params.collection)).toEqual(['events', 'commands', 'queries']);
+      expect(versionedPaths.map((path) => path.params.id)).toEqual(['OrderPlaced', 'CreateOrder', 'GetOrder']);
+      expect(versionedPaths.map((path) => path.params.version)).toEqual(['1.0.0', '1.0.0', '1.0.0']);
+
+      // Check latest paths
+      expect(latestPaths.map((path) => path.params.collection)).toEqual(['events', 'commands', 'queries']);
+      expect(latestPaths.map((path) => path.params.id)).toEqual(['OrderPlaced', 'CreateOrder', 'GetOrder']);
+      expect(latestPaths.map((path) => path.params.version)).toEqual(['latest', 'latest', 'latest']);
+
+      // Check all the props
+      expect(versionedPaths.map((path) => path.props.pathToSchema)).toEqual([
+        path.join(__dirname, 'schemas', 'test-schema.json'),
+        path.join(__dirname, 'schemas', 'test-schema.avro'),
+        path.join(__dirname, 'schemas', 'test-schema.avro'),
+      ]);
+    });
+
+    it('returns the latest version schema when multiple versions exist for the same message', async () => {
+      mockSchemas = [
+        schemaEntry({ collection: 'events', id: 'OrderPlaced', version: '1.0.0', file: 'test-schema.json', latest: false }),
+        schemaEntry({ collection: 'events', id: 'OrderPlaced', version: '2.0.0', file: 'test-schema.avro' }),
+      ];
+
+      const staticPaths = await getStaticPaths();
+      // 2 versioned paths + 1 latest path
+      expect(staticPaths).toHaveLength(3);
+
+      const latestPath = staticPaths.find((p) => p.params.version === 'latest');
+      expect(latestPath).toBeDefined();
+      expect(latestPath?.params.id).toEqual('OrderPlaced');
+      // Latest should point to v2.0.0's schema (test-schema.avro)
+      expect(latestPath?.props.pathToSchema).toEqual(path.join(__dirname, 'schemas', 'test-schema.avro'));
+    });
+
+    it('handles non-semver versions and returns the latest based on string comparison', async () => {
+      mockSchemas = [
+        schemaEntry({ collection: 'events', id: 'OrderPlaced', version: 'draft', file: 'test-schema.json', latest: false }),
+        schemaEntry({ collection: 'events', id: 'OrderPlaced', version: 'v2', file: 'test-schema.avro' }),
+      ];
+
+      const staticPaths = await getStaticPaths();
+      // 2 versioned paths + 1 latest path
+      expect(staticPaths).toHaveLength(3);
+
+      const latestPath = staticPaths.find((p) => p.params.version === 'latest');
+      expect(latestPath).toBeDefined();
+      // "v2" > "draft" in string comparison
+      expect(latestPath?.props.pathToSchema).toEqual(path.join(__dirname, 'schemas', 'test-schema.avro'));
+    });
+  });
+
+  describe('GET (static mode)', () => {
+    it('returns the given schema when EventCatalog Scale is enabled', async () => {
+      mockIsEventCatalogScaleEnabled.mockReturnValue(true);
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/events/OrderPlaced/1.0.0'),
+        props: { schema: 'test-schema.json' },
+      } as any);
+      expect(response.status).toBe(200);
+      expect(await response.text()).toEqual('test-schema.json');
+    });
+    it('returns an error when EventCatalog Scale is disabled', async () => {
+      mockIsEventCatalogScaleEnabled.mockReturnValue(false);
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/events/OrderPlaced/1.0.0'),
+        props: { schema: 'test-schema.json' },
+      } as any);
+      expect(response.status).toBe(501);
+      expect(await response.text()).toEqual(
+        '{"error":"feature_not_available_on_server","message":"Schema API is not enabled for this deployment and supported in EventCatalog Scale."}'
+      );
+    });
+  });
+
+  describe('GET (SSR mode)', () => {
+    beforeEach(() => {
+      mockIsEventCatalogScaleEnabled.mockReturnValue(true);
+      mockIsSSR.mockReturnValue(true);
+    });
+
+    it('resolves the schema dynamically when props are empty (SSR mode)', async () => {
+      const schemaContent = fs.readFileSync(path.join(__dirname, 'schemas', 'test-schema.json'), 'utf8');
+
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/events/OrderPlaced/1.0.0'),
+        props: {},
+        params: { collection: 'events', id: 'OrderPlaced', version: '1.0.0' },
+      } as any);
+
+      expect(response.status).toBe(200);
+      expect(await response.text()).toEqual(schemaContent);
+    });
+
+    it('resolves the latest schema dynamically when version is "latest"', async () => {
+      const latestSchemaContent = fs.readFileSync(path.join(__dirname, 'schemas', 'test-schema.avro'), 'utf8');
+      mockSchemas = [
+        schemaEntry({ collection: 'events', id: 'OrderPlaced', version: '1.0.0', file: 'test-schema.json', latest: false }),
+        schemaEntry({ collection: 'events', id: 'OrderPlaced', version: '2.0.0', file: 'test-schema.avro' }),
+      ];
+
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/events/OrderPlaced/latest'),
+        props: {},
+        params: { collection: 'events', id: 'OrderPlaced', version: 'latest' },
+      } as any);
+
+      expect(response.status).toBe(200);
+      expect(await response.text()).toEqual(latestSchemaContent);
+    });
+
+    it('returns 404 when the schema is not found in SSR mode', async () => {
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/events/NonExistent/1.0.0'),
+        props: {},
+        params: { collection: 'events', id: 'NonExistent', version: '1.0.0' },
+      } as any);
+
+      expect(response.status).toBe(404);
+      expect(await response.json()).toEqual({ error: 'Schema not found' });
+    });
+
+    it('returns 400 when id param is missing in SSR mode', async () => {
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/events//1.0.0'),
+        props: {},
+        params: { collection: 'events', id: '', version: '1.0.0' },
+      } as any);
+
+      expect(response.status).toBe(400);
+      expect(await response.json()).toEqual({ error: 'Missing id parameter' });
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/__tests__/api/schemas.txt.spec.ts b/packages/core/eventcatalog/src/__tests__/api/schemas.txt.spec.ts
new file mode 100644
index 000000000..18db268cd
--- /dev/null
+++ b/packages/core/eventcatalog/src/__tests__/api/schemas.txt.spec.ts
@@ -0,0 +1,111 @@
+import type { CollectionKey } from 'astro:content';
+import { expect, describe, it, vi } from 'vitest';
+import { GET } from '../../pages/docs/llm/schemas.txt.ts';
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: (key: CollectionKey) => {
+      switch (key) {
+        case 'services':
+          return Promise.resolve([
+            {
+              data: {
+                name: 'Order Service',
+                id: 'OrderService',
+                version: '1.0.0',
+                summary: 'Order Service summary',
+                specifications: [
+                  { type: 'openapi', path: 'schema.json' },
+                  { type: 'asyncapi', path: 'schema.asyncapi.json' },
+                  { type: 'graphql', path: 'schema.graphql' },
+                ],
+              },
+            },
+            // No schema, does not return
+            {
+              data: { name: 'Inventory Service', id: 'InventoryService', version: '1.0.0', summary: 'Inventory Service summary' },
+            },
+          ]);
+        case 'schemas':
+          return Promise.resolve([
+            {
+              data: {
+                id: 'schema:events:OrderPlaced:1.0.0:schema.json',
+                message: {
+                  collection: 'events',
+                  id: 'OrderPlaced',
+                  name: 'Order Placed',
+                  version: '1.0.0',
+                  summary: 'Order Placed summary',
+                  owners: ['orders-team'],
+                },
+              },
+            },
+            {
+              data: {
+                id: 'schema:commands:CreateOrder:1.0.0:schema.json',
+                message: {
+                  collection: 'commands',
+                  id: 'CreateOrder',
+                  name: 'Create Order',
+                  version: '1.0.0',
+                  summary: 'Create Order summary',
+                  owners: ['orders-team'],
+                },
+              },
+            },
+            {
+              data: {
+                id: 'schema:queries:GetOrder:1.0.0:schema.json',
+                message: {
+                  collection: 'queries',
+                  id: 'GetOrder',
+                  name: 'Get Order',
+                  version: '1.0.0',
+                  summary: 'Get Order summary',
+                  owners: ['orders-team'],
+                },
+              },
+            },
+          ]);
+        default:
+          return Promise.resolve([]);
+      }
+    },
+  };
+});
+
+describe('api/schemas.txt', () => {
+  it('returns a list of schemas for events, commands, queries, and services when EventCatalog Scale is enabled', async () => {
+    process.env.EVENTCATALOG_SCALE = 'true';
+    const response = await GET({ request: new Request('http://localhost:4321/api/schemas.txt') } as any);
+    expect(response.status).toBe(200);
+
+    const responseBody = await response.text();
+    expect(responseBody).toEqual(`# Acme Inc EventCatalog Schemas
+List of schemas for events, commands, queries, and services in EventCatalog.
+
+## Events
+- [Order Placed - OrderPlaced - 1.0.0](http://localhost:4321/api/schemas/events/OrderPlaced/1.0.0)} - Order Placed summary
+
+## Commands
+- [Create Order - CreateOrder - 1.0.0](http://localhost:4321/api/schemas/commands/CreateOrder/1.0.0)} - Create Order summary
+
+## Queries
+- [Get Order - GetOrder - 1.0.0](http://localhost:4321/api/schemas/queries/GetOrder/1.0.0)} - Get Order summary
+
+## Services
+- [OrderService - 1.0.0 - openapi specification](http://localhost:4321/api/schemas/services/OrderService/1.0.0/openapi) - Specification for Order Service summary
+- [OrderService - 1.0.0 - asyncapi specification](http://localhost:4321/api/schemas/services/OrderService/1.0.0/asyncapi) - Specification for Order Service summary
+- [OrderService - 1.0.0 - graphql specification](http://localhost:4321/api/schemas/services/OrderService/1.0.0/graphql) - Specification for Order Service summary`);
+  });
+  it('returns an error when EventCatalog Scale is disabled', async () => {
+    process.env.EVENTCATALOG_SCALE = 'false';
+    const response = await GET({ request: new Request('http://localhost:4321/api/schemas.txt') } as any);
+    expect(response.status).toBe(501);
+    expect(await response.text()).toEqual(
+      '{"error":"feature_not_available_on_server","message":"Schema API is not enabled for this deployment and supported in EventCatalog Scale."}'
+    );
+  });
+});
diff --git a/eventcatalog/src/__tests__/api/schemas/test-asyncapi.yml b/packages/core/eventcatalog/src/__tests__/api/schemas/test-asyncapi.yml
similarity index 100%
rename from eventcatalog/src/__tests__/api/schemas/test-asyncapi.yml
rename to packages/core/eventcatalog/src/__tests__/api/schemas/test-asyncapi.yml
diff --git a/eventcatalog/src/__tests__/api/schemas/test-openapi.yml b/packages/core/eventcatalog/src/__tests__/api/schemas/test-openapi.yml
similarity index 100%
rename from eventcatalog/src/__tests__/api/schemas/test-openapi.yml
rename to packages/core/eventcatalog/src/__tests__/api/schemas/test-openapi.yml
diff --git a/eventcatalog/src/__tests__/api/schemas/test-schema.avro b/packages/core/eventcatalog/src/__tests__/api/schemas/test-schema.avro
similarity index 100%
rename from eventcatalog/src/__tests__/api/schemas/test-schema.avro
rename to packages/core/eventcatalog/src/__tests__/api/schemas/test-schema.avro
diff --git a/eventcatalog/src/__tests__/api/schemas/test-schema.json b/packages/core/eventcatalog/src/__tests__/api/schemas/test-schema.json
similarity index 100%
rename from eventcatalog/src/__tests__/api/schemas/test-schema.json
rename to packages/core/eventcatalog/src/__tests__/api/schemas/test-schema.json
diff --git a/packages/core/eventcatalog/src/__tests__/api/services-schemas-api.spec.ts b/packages/core/eventcatalog/src/__tests__/api/services-schemas-api.spec.ts
new file mode 100644
index 000000000..845e2caf1
--- /dev/null
+++ b/packages/core/eventcatalog/src/__tests__/api/services-schemas-api.spec.ts
@@ -0,0 +1,170 @@
+import type { CollectionKey } from 'astro:content';
+import { expect, describe, it, vi, beforeEach } from 'vitest';
+import { getStaticPaths, GET } from '../../enterprise/api/schemas/services/[id]/[version]/[specification]/index.ts';
+import path from 'path';
+import fs from 'node:fs';
+
+let mockIsEventCatalogScaleEnabled = vi.fn();
+let mockIsSSR = vi.fn().mockReturnValue(false);
+
+const __dirname = path.dirname(new URL(import.meta.url).pathname);
+
+const mockServices = [
+  {
+    collection: 'services',
+    filePath: path.join(__dirname, 'schemas', 'test-openapi.yml'),
+    data: {
+      name: 'Order Service',
+      id: 'OrderService',
+      version: '1.0.0',
+      summary: 'Order Service summary',
+      specifications: [
+        { type: 'openapi', path: 'test-openapi.yml' },
+        { type: 'asyncapi', path: 'test-asyncapi.yml' },
+      ],
+    },
+  },
+  {
+    collection: 'services',
+    filePath: path.join(__dirname, 'schemas', 'test-openapi.yml'),
+    data: {
+      name: 'Order Service',
+      id: 'OrderService',
+      version: '2.0.0',
+      summary: 'Order Service summary',
+      specifications: [{ type: 'openapi', path: 'test-openapi.yml' }],
+    },
+  },
+];
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: (key: CollectionKey) => {
+      switch (key) {
+        case 'services':
+          return Promise.resolve(mockServices);
+        default:
+          return Promise.resolve([]);
+      }
+    },
+  };
+});
+
+vi.mock('@utils/feature', () => {
+  return {
+    isEventCatalogScaleEnabled: () => mockIsEventCatalogScaleEnabled(),
+    isSSR: () => mockIsSSR(),
+  };
+});
+
+describe('api/schemas/services/[id]/[version]/[specification]/index.ts', () => {
+  describe('getStaticPaths', () => {
+    it('returns static paths for services that have a schema', async () => {
+      const staticPaths = await getStaticPaths();
+      expect(staticPaths).toHaveLength(3);
+
+      // Check all the params
+      expect(staticPaths.map((path) => path.params.collection)).toEqual(['services', 'services', 'services']);
+      expect(staticPaths.map((path) => path.params.id)).toEqual(['OrderService', 'OrderService', 'OrderService']);
+      expect(staticPaths.map((path) => path.params.version)).toEqual(['1.0.0', '1.0.0', '2.0.0']);
+      expect(staticPaths.map((path) => path.params.specification)).toEqual(['openapi', 'asyncapi', 'openapi']);
+
+      // Check all the props
+      expect(staticPaths.map((path) => path.props.schema)).toEqual([
+        fs.readFileSync(path.join(__dirname, 'schemas', 'test-openapi.yml'), 'utf8'),
+        fs.readFileSync(path.join(__dirname, 'schemas', 'test-asyncapi.yml'), 'utf8'),
+        fs.readFileSync(path.join(__dirname, 'schemas', 'test-openapi.yml'), 'utf8'),
+      ]);
+    });
+  });
+
+  describe('GET (static mode)', () => {
+    it('returns the given schema when EventCatalog Scale is enabled', async () => {
+      mockIsEventCatalogScaleEnabled.mockReturnValue(true);
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/services/OrderService/1.0.0/openapi'),
+        props: { schema: fs.readFileSync(path.join(__dirname, 'schemas', 'test-openapi.yml'), 'utf8') },
+      } as any);
+      expect(response.status).toBe(200);
+      expect(await response.text()).toEqual(fs.readFileSync(path.join(__dirname, 'schemas', 'test-openapi.yml'), 'utf8'));
+    });
+    it('returns an error when EventCatalog Scale is disabled', async () => {
+      mockIsEventCatalogScaleEnabled.mockReturnValue(false);
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/services/OrderService/1.0.0/openapi'),
+        props: { schema: fs.readFileSync(path.join(__dirname, 'schemas', 'test-openapi.yml'), 'utf8') },
+      } as any);
+      expect(response.status).toBe(501);
+      expect(await response.text()).toEqual(
+        '{"error":"feature_not_available_on_server","message":"Schema API is not enabled for this deployment and supported in EventCatalog Scale."}'
+      );
+    });
+  });
+
+  describe('GET (SSR mode)', () => {
+    beforeEach(() => {
+      mockIsEventCatalogScaleEnabled.mockReturnValue(true);
+      mockIsSSR.mockReturnValue(true);
+    });
+
+    it('resolves the service specification dynamically when props are empty (SSR mode)', async () => {
+      const expectedSchema = fs.readFileSync(path.join(__dirname, 'schemas', 'test-openapi.yml'), 'utf8');
+
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/services/OrderService/1.0.0/openapi'),
+        props: {},
+        params: { id: 'OrderService', version: '1.0.0', specification: 'openapi' },
+      } as any);
+
+      expect(response.status).toBe(200);
+      expect(await response.text()).toEqual(expectedSchema);
+    });
+
+    it('resolves different specification types (asyncapi) in SSR mode', async () => {
+      const expectedSchema = fs.readFileSync(path.join(__dirname, 'schemas', 'test-asyncapi.yml'), 'utf8');
+
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/services/OrderService/1.0.0/asyncapi'),
+        props: {},
+        params: { id: 'OrderService', version: '1.0.0', specification: 'asyncapi' },
+      } as any);
+
+      expect(response.status).toBe(200);
+      expect(await response.text()).toEqual(expectedSchema);
+    });
+
+    it('returns 404 when the service is not found in SSR mode', async () => {
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/services/NonExistent/1.0.0/openapi'),
+        props: {},
+        params: { id: 'NonExistent', version: '1.0.0', specification: 'openapi' },
+      } as any);
+
+      expect(response.status).toBe(404);
+      expect(await response.json()).toEqual({ error: 'Service not found' });
+    });
+
+    it('returns 404 when the specification type is not found in SSR mode', async () => {
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/services/OrderService/1.0.0/graphql'),
+        props: {},
+        params: { id: 'OrderService', version: '1.0.0', specification: 'graphql' },
+      } as any);
+
+      expect(response.status).toBe(404);
+      expect(await response.json()).toEqual({ error: 'Specification not found' });
+    });
+
+    it('returns 400 when required params are missing in SSR mode', async () => {
+      const response = await GET({
+        request: new Request('http://localhost:4321/api/schemas/services/OrderService/1.0.0/'),
+        props: {},
+        params: { id: 'OrderService', version: '1.0.0', specification: '' },
+      } as any);
+
+      expect(response.status).toBe(400);
+      expect(await response.json()).toEqual({ error: 'Missing id, version, or specification parameter' });
+    });
+  });
+});
diff --git a/eventcatalog/src/__tests__/middleware-auth.spec.ts b/packages/core/eventcatalog/src/__tests__/middleware-auth.spec.ts
similarity index 75%
rename from eventcatalog/src/__tests__/middleware-auth.spec.ts
rename to packages/core/eventcatalog/src/__tests__/middleware-auth.spec.ts
index d7849ce4e..40d0d8476 100644
--- a/eventcatalog/src/__tests__/middleware-auth.spec.ts
+++ b/packages/core/eventcatalog/src/__tests__/middleware-auth.spec.ts
@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
-import { findMatchingRule, matchesPattern } from '../middleware-auth';
+import { findMatchingRule, getPublicRoutes, isMcpRoute, matchesPattern } from '../enterprise/auth/middleware/middleware-auth';
 
+// Note:
 describe('middleware-auth', () => {
   describe('matchesPattern', () => {
     it('should match exact paths', () => {
@@ -126,4 +127,37 @@ describe('middleware-auth', () => {
       expect(findMatchingRule(rules, '/users/123/settings')).toBe(doubleWildcard);
     });
   });
+
+  describe('getPublicRoutes', () => {
+    it('includes root llms.txt routes when llms text access is enabled', () => {
+      expect(getPublicRoutes(true)).toContain('/llms.txt');
+      expect(getPublicRoutes(true)).toContain('/llms-full.txt');
+    });
+
+    it('includes schemas.txt when llms text access is enabled', () => {
+      expect(getPublicRoutes(true)).toContain('/docs/llm/schemas.txt');
+    });
+
+    it('does not expose llms routes when llms text access is disabled', () => {
+      expect(getPublicRoutes(false)).not.toContain('/llms.txt');
+      expect(getPublicRoutes(false)).not.toContain('/llms-full.txt');
+      expect(getPublicRoutes(false)).not.toContain('/docs/llm/schemas.txt');
+      expect(getPublicRoutes(false)).not.toContain('/docs/llm/llms.txt');
+      expect(getPublicRoutes(false)).not.toContain('/docs/llm/llms-full.txt');
+    });
+  });
+
+  describe('isMcpRoute', () => {
+    it('matches the MCP endpoint and child paths only', () => {
+      expect(isMcpRoute('/docs/mcp')).toBe(true);
+      expect(isMcpRoute('/docs/mcp/')).toBe(true);
+      expect(isMcpRoute('/docs/mcp/messages')).toBe(true);
+    });
+
+    it('does not match routes that only share the same prefix', () => {
+      expect(isMcpRoute('/docs/mcp-anything')).toBe(false);
+      expect(isMcpRoute('/docs/mcpany')).toBe(false);
+      expect(isMcpRoute('/docs/mcp.v1')).toBe(false);
+    });
+  });
 });
diff --git a/packages/core/eventcatalog/src/__tests__/node-graphs/export-mermaid.spec.ts b/packages/core/eventcatalog/src/__tests__/node-graphs/export-mermaid.spec.ts
new file mode 100644
index 000000000..d55740fd6
--- /dev/null
+++ b/packages/core/eventcatalog/src/__tests__/node-graphs/export-mermaid.spec.ts
@@ -0,0 +1,385 @@
+import { describe, it, expect } from 'vitest';
+import { sanitizeMermaidId, getMermaidNodeShape, getNodeLabel, convertToMermaid } from '../../utils/node-graphs/export-mermaid';
+import type { Node, Edge } from '@xyflow/react';
+
+describe('export-mermaid', () => {
+  describe('sanitizeMermaidId', () => {
+    it('should replace dots with underscores', () => {
+      expect(sanitizeMermaidId('order-1.0.0')).toBe('order_1_0_0');
+    });
+
+    it('should replace hyphens with underscores', () => {
+      expect(sanitizeMermaidId('order-service')).toBe('order_service');
+    });
+
+    it('should handle mixed special characters', () => {
+      expect(sanitizeMermaidId('my.service-v1.2.3')).toBe('my_service_v1_2_3');
+    });
+
+    it('should preserve alphanumeric characters', () => {
+      expect(sanitizeMermaidId('OrderService123')).toBe('OrderService123');
+    });
+
+    it('should handle already valid IDs', () => {
+      expect(sanitizeMermaidId('order_service_v1')).toBe('order_service_v1');
+    });
+  });
+
+  describe('getMermaidNodeShape', () => {
+    it('should return stadium shape for services', () => {
+      expect(getMermaidNodeShape('services')).toEqual(['[[', ']]']);
+      expect(getMermaidNodeShape('service')).toEqual(['[[', ']]']);
+    });
+
+    it('should return flag shape for events (message-like)', () => {
+      expect(getMermaidNodeShape('events')).toEqual(['>', ']']);
+      expect(getMermaidNodeShape('event')).toEqual(['>', ']']);
+    });
+
+    it('should return flag shape for commands (message-like)', () => {
+      expect(getMermaidNodeShape('commands')).toEqual(['>', ']']);
+      expect(getMermaidNodeShape('command')).toEqual(['>', ']']);
+    });
+
+    it('should return hexagon shape for queries', () => {
+      expect(getMermaidNodeShape('queries')).toEqual(['{{', '}}']);
+      expect(getMermaidNodeShape('query')).toEqual(['{{', '}}']);
+    });
+
+    it('should return cylinder shape for channels', () => {
+      expect(getMermaidNodeShape('channels')).toEqual(['[(', ')]']);
+      expect(getMermaidNodeShape('channel')).toEqual(['[(', ')]']);
+    });
+
+    it('should return rectangle shape for domains', () => {
+      expect(getMermaidNodeShape('domains')).toEqual(['[', ']']);
+      expect(getMermaidNodeShape('domain')).toEqual(['[', ']']);
+    });
+
+    it('should return rectangle for unknown types', () => {
+      expect(getMermaidNodeShape('unknown')).toEqual(['[', ']']);
+    });
+  });
+
+  describe('getNodeLabel', () => {
+    it('should extract label from service node', () => {
+      const node: Node = {
+        id: 'order-service-1.0.0',
+        type: 'services',
+        position: { x: 0, y: 0 },
+        data: {
+          service: {
+            id: 'order-service',
+            name: 'Order Service',
+            version: '1.0.0',
+          },
+        },
+      };
+      expect(getNodeLabel(node)).toBe('Order Service (1.0.0)');
+    });
+
+    it('should fallback to id if name is missing for service', () => {
+      const node: Node = {
+        id: 'order-service-1.0.0',
+        type: 'services',
+        position: { x: 0, y: 0 },
+        data: {
+          service: {
+            id: 'order-service',
+            version: '1.0.0',
+          },
+        },
+      };
+      expect(getNodeLabel(node)).toBe('order-service (1.0.0)');
+    });
+
+    it('should extract label from event node', () => {
+      const node: Node = {
+        id: 'order-created-1.0.0',
+        type: 'events',
+        position: { x: 0, y: 0 },
+        data: {
+          message: {
+            id: 'order-created',
+            name: 'OrderCreated',
+            version: '1.0.0',
+          },
+        },
+      };
+      expect(getNodeLabel(node)).toBe('OrderCreated (1.0.0)');
+    });
+
+    it('should extract label from command node', () => {
+      const node: Node = {
+        id: 'create-order-1.0.0',
+        type: 'commands',
+        position: { x: 0, y: 0 },
+        data: {
+          message: {
+            id: 'create-order',
+            name: 'CreateOrder',
+            version: '1.0.0',
+          },
+        },
+      };
+      expect(getNodeLabel(node)).toBe('CreateOrder (1.0.0)');
+    });
+
+    it('should extract label from channel node', () => {
+      const node: Node = {
+        id: 'order-channel-1.0.0',
+        type: 'channels',
+        position: { x: 0, y: 0 },
+        data: {
+          channel: {
+            id: 'order-channel',
+            name: 'Order Channel',
+            version: '1.0.0',
+          },
+        },
+      };
+      expect(getNodeLabel(node)).toBe('Order Channel (1.0.0)');
+    });
+
+    it('should extract label from domain node with nested data', () => {
+      const node: Node = {
+        id: 'orders-domain-1.0.0',
+        type: 'domains',
+        position: { x: 0, y: 0 },
+        data: {
+          domain: {
+            data: {
+              id: 'orders-domain',
+              name: 'Orders Domain',
+              version: '1.0.0',
+            },
+          },
+        },
+      };
+      expect(getNodeLabel(node)).toBe('Orders Domain (1.0.0)');
+    });
+
+    it('should fallback to node id when no data', () => {
+      const node: Node = {
+        id: 'fallback-node',
+        type: 'services',
+        position: { x: 0, y: 0 },
+        data: {},
+      };
+      expect(getNodeLabel(node)).toBe('fallback-node');
+    });
+  });
+
+  describe('convertToMermaid', () => {
+    it('should generate valid mermaid flowchart syntax', () => {
+      const nodes: Node[] = [
+        {
+          id: 'order-service-1.0.0',
+          type: 'services',
+          position: { x: 0, y: 0 },
+          data: {
+            service: {
+              id: 'order-service',
+              name: 'Order Service',
+              version: '1.0.0',
+            },
+          },
+        },
+        {
+          id: 'order-created-1.0.0',
+          type: 'events',
+          position: { x: 100, y: 0 },
+          data: {
+            message: {
+              id: 'order-created',
+              name: 'OrderCreated',
+              version: '1.0.0',
+            },
+          },
+        },
+      ];
+
+      const edges: Edge[] = [
+        {
+          id: 'edge-1',
+          source: 'order-service-1.0.0',
+          target: 'order-created-1.0.0',
+          label: 'publishes',
+        },
+      ];
+
+      const result = convertToMermaid(nodes, edges);
+
+      expect(result).toContain('flowchart LR');
+      expect(result).toContain('order_service_1_0_0[["Order Service (1.0.0)"]]');
+      expect(result).toContain('order_created_1_0_0>"OrderCreated (1.0.0)"]');
+      expect(result).toContain('order_service_1_0_0 -->|"publishes"| order_created_1_0_0');
+    });
+
+    it('should include style class definitions when includeStyles is true', () => {
+      const nodes: Node[] = [
+        {
+          id: 'service-1',
+          type: 'services',
+          position: { x: 0, y: 0 },
+          data: { service: { id: 'service-1', name: 'Service 1' } },
+        },
+      ];
+
+      const result = convertToMermaid(nodes, [], { includeStyles: true });
+
+      expect(result).toContain('classDef services');
+      expect(result).toContain(':::services');
+    });
+
+    it('should not include style classes when includeStyles is false', () => {
+      const nodes: Node[] = [
+        {
+          id: 'service-1',
+          type: 'services',
+          position: { x: 0, y: 0 },
+          data: { service: { id: 'service-1', name: 'Service 1' } },
+        },
+      ];
+
+      const result = convertToMermaid(nodes, [], { includeStyles: false });
+
+      expect(result).not.toContain('classDef');
+      expect(result).not.toContain(':::');
+    });
+
+    it('should support different flowchart directions', () => {
+      const nodes: Node[] = [
+        {
+          id: 'service-1',
+          type: 'services',
+          position: { x: 0, y: 0 },
+          data: { service: { id: 'service-1', name: 'Service 1' } },
+        },
+      ];
+
+      expect(convertToMermaid(nodes, [], { direction: 'TB' })).toContain('flowchart TB');
+      expect(convertToMermaid(nodes, [], { direction: 'RL' })).toContain('flowchart RL');
+      expect(convertToMermaid(nodes, [], { direction: 'BT' })).toContain('flowchart BT');
+    });
+
+    it('should handle edges without labels', () => {
+      const nodes: Node[] = [
+        {
+          id: 'a',
+          type: 'services',
+          position: { x: 0, y: 0 },
+          data: { service: { id: 'a', name: 'A' } },
+        },
+        {
+          id: 'b',
+          type: 'events',
+          position: { x: 100, y: 0 },
+          data: { message: { id: 'b', name: 'B' } },
+        },
+      ];
+
+      const edges: Edge[] = [
+        {
+          id: 'edge-1',
+          source: 'a',
+          target: 'b',
+        },
+      ];
+
+      const result = convertToMermaid(nodes, edges);
+
+      expect(result).toContain('a --> b');
+      expect(result).not.toContain('-->|');
+    });
+
+    it('should escape special characters in labels', () => {
+      const nodes: Node[] = [
+        {
+          id: 'service-1',
+          type: 'services',
+          position: { x: 0, y: 0 },
+          data: { service: { id: 'service-1', name: 'Service "One"' } },
+        },
+      ];
+
+      const result = convertToMermaid(nodes, []);
+
+      expect(result).toContain('Service #quot;One#quot;');
+    });
+
+    it('should handle multiline edge labels', () => {
+      const nodes: Node[] = [
+        {
+          id: 'a',
+          type: 'services',
+          position: { x: 0, y: 0 },
+          data: { service: { id: 'a', name: 'A' } },
+        },
+        {
+          id: 'b',
+          type: 'events',
+          position: { x: 100, y: 0 },
+          data: { message: { id: 'b', name: 'B' } },
+        },
+      ];
+
+      const edges: Edge[] = [
+        {
+          id: 'edge-1',
+          source: 'a',
+          target: 'b',
+          label: 'publishes\nevent',
+        },
+      ];
+
+      const result = convertToMermaid(nodes, edges);
+
+      // Multiline labels should be converted to single line
+      expect(result).toContain('publishes event');
+    });
+
+    it('should handle various node types correctly', () => {
+      const nodes: Node[] = [
+        {
+          id: 'svc',
+          type: 'services',
+          position: { x: 0, y: 0 },
+          data: { service: { id: 'svc', name: 'Service' } },
+        },
+        {
+          id: 'evt',
+          type: 'events',
+          position: { x: 100, y: 0 },
+          data: { message: { id: 'evt', name: 'Event' } },
+        },
+        {
+          id: 'cmd',
+          type: 'commands',
+          position: { x: 200, y: 0 },
+          data: { message: { id: 'cmd', name: 'Command' } },
+        },
+        {
+          id: 'qry',
+          type: 'queries',
+          position: { x: 300, y: 0 },
+          data: { message: { id: 'qry', name: 'Query' } },
+        },
+        {
+          id: 'chn',
+          type: 'channels',
+          position: { x: 400, y: 0 },
+          data: { channel: { id: 'chn', name: 'Channel' } },
+        },
+      ];
+
+      const result = convertToMermaid(nodes, [], { includeStyles: false });
+
+      expect(result).toContain('svc[["Service"]]');
+      expect(result).toContain('evt>"Event"]');
+      expect(result).toContain('cmd>"Command"]');
+      expect(result).toContain('qry{{"Query"}}');
+      expect(result).toContain('chn[("Channel")]');
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/components/Badge.astro b/packages/core/eventcatalog/src/components/Badge.astro
new file mode 100644
index 000000000..4d06114a9
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Badge.astro
@@ -0,0 +1,89 @@
+---
+import { getBadgeHref, getBadgeStyle } from '@utils/badge-styles';
+import { ArrowTopRightOnSquareIcon } from '@heroicons/react/20/solid';
+
+type Badge = {
+  id?: string;
+  content: string;
+  backgroundColor?: string;
+  textColor?: string;
+  icon?: any;
+  iconComponent?: any;
+  iconURL?: string;
+  iconURLLight?: string;
+  iconURLDark?: string;
+  class?: string;
+  url?: string;
+};
+
+type Props = {
+  badge: Badge;
+  className?: string;
+};
+
+const { badge, className = '' } = Astro.props;
+const href = getBadgeHref(badge);
+const Icon = badge.icon || badge.iconComponent;
+const hasThemedIcon = badge.iconURLLight && badge.iconURLDark;
+const classes = `
+  inline-flex items-center gap-1 px-1.5 py-0.5 rounded-md text-xs font-medium
+  ${badge.backgroundColor ? 'bg-[rgb(var(--ec-content-hover))]' : 'bg-transparent'} border border-[rgb(var(--ec-page-border))]
+  text-[rgb(var(--ec-page-text))]
+  shadow-xs
+  ${badge.class ? badge.class : ''}
+  ${className}
+`;
+---
+
+{
+  href ? (
+    <a id={badge.id || undefined} href={href} class={classes} style={getBadgeStyle(badge)} title={badge.content}>
+      {Icon && <Icon className="w-3 h-3 flex-shrink-0" />}
+      {hasThemedIcon && (
+        <img
+          src={badge.iconURLLight}
+          class="w-3 h-3 flex-shrink-0 opacity-80 dark:hidden"
+          alt=""
+          onerror="this.style.display='none'"
+        />
+      )}
+      {hasThemedIcon && (
+        <img
+          src={badge.iconURLDark}
+          class="hidden w-3 h-3 flex-shrink-0 opacity-80 dark:inline-block"
+          alt=""
+          onerror="this.style.display='none'"
+        />
+      )}
+      {!hasThemedIcon && badge.iconURL && (
+        <img src={badge.iconURL} class="w-3 h-3 flex-shrink-0 opacity-80" alt="" onerror="this.style.display='none'" />
+      )}
+      <span>{badge.content}</span>
+      <ArrowTopRightOnSquareIcon className="w-2.5 h-2.5 flex-shrink-0 opacity-70" aria-hidden="true" />
+    </a>
+  ) : (
+    <span id={badge.id || undefined} class={classes} style={getBadgeStyle(badge)} title={badge.content}>
+      {Icon && <Icon className="w-3 h-3 flex-shrink-0" />}
+      {hasThemedIcon && (
+        <img
+          src={badge.iconURLLight}
+          class="w-3 h-3 flex-shrink-0 opacity-80 dark:hidden"
+          alt=""
+          onerror="this.style.display='none'"
+        />
+      )}
+      {hasThemedIcon && (
+        <img
+          src={badge.iconURLDark}
+          class="hidden w-3 h-3 flex-shrink-0 opacity-80 dark:inline-block"
+          alt=""
+          onerror="this.style.display='none'"
+        />
+      )}
+      {!hasThemedIcon && badge.iconURL && (
+        <img src={badge.iconURL} class="w-3 h-3 flex-shrink-0 opacity-80" alt="" onerror="this.style.display='none'" />
+      )}
+      <span>{badge.content}</span>
+    </span>
+  )
+}
diff --git a/packages/core/eventcatalog/src/components/ChatPanel/ChatPanel.tsx b/packages/core/eventcatalog/src/components/ChatPanel/ChatPanel.tsx
new file mode 100644
index 000000000..e8bfc866d
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/ChatPanel/ChatPanel.tsx
@@ -0,0 +1,1356 @@
+import { useEffect, useRef, useCallback, useState, useMemo, memo } from 'react';
+import { X, Square, Trash2, BookOpen, Copy, Check, Maximize2, Minimize2, Wrench, ChevronDown, MessageSquare } from 'lucide-react';
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
+import { oneDark } from 'react-syntax-highlighter/dist/cjs/styles/prism';
+import * as Dialog from '@radix-ui/react-dialog';
+import * as Popover from '@radix-ui/react-popover';
+import { buildUrl } from '@utils/url-builder';
+
+interface ToolMetadata {
+  name: string;
+  description: string;
+  isCustom?: boolean;
+}
+
+// CSS keyframes - defined once outside component to avoid re-injection
+const CHAT_PANEL_STYLES = `
+  @keyframes fadeIn {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+  @keyframes fadeInUp {
+    from {
+      opacity: 0;
+      transform: translateY(8px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+  @keyframes focusIn {
+    from {
+      box-shadow: 0 0 0 0 rgba(168, 85, 247, 0);
+      border-color: #e5e7eb;
+    }
+    to {
+      box-shadow: 0 0 0 3px rgba(168, 85, 247, 0.15);
+      border-color: #c084fc;
+    }
+  }
+  @keyframes pulse-glow {
+    0%, 100% { box-shadow: 0 0 8px rgba(147, 51, 234, 0.3); }
+    50% { box-shadow: 0 0 16px rgba(147, 51, 234, 0.5); }
+  }
+`;
+
+// Stable style object for syntax highlighter
+const CODE_BLOCK_STYLE = {
+  margin: 0,
+  borderRadius: '0.375rem',
+  fontSize: '12px',
+  padding: '1rem',
+};
+
+// Code block component with copy functionality - memoized
+const CodeBlock = memo(({ language, children }: { language: string; children: string }) => {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(children);
+      setCopied(true);
+    } catch {
+      // Clipboard API can fail in some contexts
+    }
+  }, [children]);
+
+  // Clear copied state after 2 seconds with proper cleanup
+  useEffect(() => {
+    if (!copied) return;
+    const timer = setTimeout(() => setCopied(false), 2000);
+    return () => clearTimeout(timer);
+  }, [copied]);
+
+  return (
+    <div className="relative group my-2">
+      <button
+        onClick={handleCopy}
+        className="absolute right-2 top-2 p-1.5 rounded bg-gray-700 hover:bg-gray-600 text-gray-300 opacity-0 group-hover:opacity-100 transition-opacity z-10"
+        aria-label="Copy code"
+      >
+        {copied ? <Check size={14} /> : <Copy size={14} />}
+      </button>
+      <SyntaxHighlighter language={language} style={oneDark} customStyle={CODE_BLOCK_STYLE}>
+        {children}
+      </SyntaxHighlighter>
+    </div>
+  );
+});
+CodeBlock.displayName = 'CodeBlock';
+
+// Get time-based greeting
+const getGreeting = () => {
+  const hour = new Date().getHours();
+  if (hour < 12) return 'Good morning';
+  if (hour < 18) return 'Good afternoon';
+  return 'Good evening';
+};
+
+// ============================================
+// SUGGESTED QUESTIONS CONFIGURATION
+// ============================================
+// Each config has a pattern (regex) to match the URL path
+// and an array of questions to show. Questions are checked
+// in order - first matching pattern wins.
+// ============================================
+
+interface SuggestedQuestion {
+  label: string;
+  prompt: string;
+}
+
+interface QuestionConfig {
+  pattern: RegExp;
+  questions: SuggestedQuestion[];
+}
+
+const suggestedQuestionsConfig: QuestionConfig[] = [
+  // Message pages (events, commands, queries) - most specific first
+  {
+    pattern: /^\/docs\/(events|commands|queries)\/.+/,
+    questions: [
+      { label: 'Which services publish this?', prompt: 'Who produces this message?' },
+      { label: 'Which services subscribe to this?', prompt: 'Who consumes this message?' },
+      { label: 'View the message schema', prompt: 'Show me the schema for this message' },
+      { label: 'What breaks if this changes?', prompt: 'What services would be affected if this message changes?' },
+    ],
+  },
+  // AsyncAPI specification page
+  {
+    pattern: /^\/docs\/services\/.+\/asyncapi\/.+/,
+    questions: [
+      { label: 'Summarize this API', prompt: 'Help me understand this AsyncAPI specification' },
+      { label: 'Show all channels', prompt: 'What channels are defined in this AsyncAPI spec?' },
+      { label: 'How do I authenticate?', prompt: 'What authentication is required for this service?' },
+      { label: 'What message formats are used?', prompt: 'What are the message formats and schemas?' },
+    ],
+  },
+  // OpenAPI specification page
+  {
+    pattern: /^\/docs\/services\/.+\/spec\/.+/,
+    questions: [
+      { label: 'Summarize this API', prompt: 'Help me understand this OpenAPI specification' },
+      { label: 'Show all endpoints', prompt: 'What endpoints are available in this API?' },
+      { label: 'How do I authenticate?', prompt: 'What authentication is required for this API?' },
+      { label: 'What are the request & response formats?', prompt: 'What are the request and response formats?' },
+    ],
+  },
+  // Services page
+  {
+    pattern: /^\/docs\/services\/.+/,
+    questions: [
+      { label: 'Who owns this service?', prompt: 'Who owns this service and how do I contact them?' },
+      {
+        label: 'What does this service depend on?',
+        prompt: 'What are the upstream and downstream dependencies of this service?',
+      },
+      { label: 'How do I integrate with this service?', prompt: 'How do I integrate with this service?' },
+      { label: 'What messages are published and consumed?', prompt: 'What messages does this service produce and consume?' },
+    ],
+  },
+  // Domains page
+  {
+    pattern: /^\/docs\/domains\/.+/,
+    questions: [
+      { label: 'What services are in this domain?', prompt: 'What services belong to this domain?' },
+      { label: 'What business capability is this?', prompt: 'What business capability does this domain represent?' },
+      { label: 'What events come from this domain?', prompt: 'What events are published by this domain?' },
+      { label: 'Who owns this domain?', prompt: 'Who owns this domain and how do I contact them?' },
+    ],
+  },
+  // Systems page
+  {
+    pattern: /^\/(docs|visualiser|architecture)\/systems\/.+/,
+    questions: [
+      { label: 'What services are in this system?', prompt: 'What services belong to this system?' },
+      { label: 'What flows are in this system?', prompt: 'What flows belong to this system?' },
+      {
+        label: 'What does this system connect to?',
+        prompt: 'What systems, services, actors, or resources does this system connect to?',
+      },
+      { label: 'Who owns this system?', prompt: 'Who owns this system and how do I contact them?' },
+    ],
+  },
+  // Business Flows / Workflows (must be before general visualiser pattern)
+  {
+    pattern: /^\/(docs|visualiser)\/flows\/.+/,
+    questions: [
+      {
+        label: 'Walk me through this workflow',
+        prompt:
+          'Get the architecture diagram for this flow and walk me through each step of this business workflow. Explain what happens at each stage.',
+      },
+      {
+        label: 'What services are involved?',
+        prompt:
+          'Using the architecture diagram, list all the services involved in this workflow and explain their role in the process.',
+      },
+      {
+        label: 'What events does this trigger?',
+        prompt: 'What events are produced during this workflow? When are they triggered and who consumes them?',
+      },
+      {
+        label: 'What can go wrong?',
+        prompt:
+          'Analyze this workflow and identify potential failure points. What happens if a step fails? Are there retry mechanisms or compensating actions?',
+      },
+    ],
+  },
+  // Visualizer page (/visualiser/*) - general fallback for other visualiser pages
+  {
+    pattern: /^\/visualiser\/.+/,
+    questions: [
+      {
+        label: 'Explain this architecture',
+        prompt:
+          'Get the architecture diagram for this resource and explain what I am looking at. Describe the key components and how they connect.',
+      },
+      {
+        label: 'What are the dependencies?',
+        prompt: 'Using the architecture diagram, show me what this resource depends on and what depends on it.',
+      },
+      {
+        label: 'How does data flow here?',
+        prompt: 'Get the architecture diagram and explain how data flows through this part of the system.',
+      },
+      {
+        label: 'What would break if this changes?',
+        prompt:
+          'Analyze the architecture diagram to identify what services or components would be affected if this resource changes.',
+      },
+    ],
+  },
+  // Data Products page
+  {
+    pattern: /^\/(docs|visualiser)\/data-products\/.+/,
+    questions: [
+      { label: 'What are the inputs and outputs?', prompt: 'What are the inputs and outputs of this data product?' },
+      { label: 'Show me the data contracts', prompt: 'What are the data contracts for this data product?' },
+      { label: 'Is this data product production ready?', prompt: 'Is this data product production ready?' },
+      { label: 'What is the quality & SLA of this product?', prompt: 'What is the quality & SLA of this product?' },
+      { label: 'Who owns this data product?', prompt: 'Who owns this data product and how do I contact them?' },
+    ],
+  },
+
+  // Designs page
+  {
+    pattern: /^\/diagrams\/.+/,
+    questions: [
+      { label: 'Tell me more about this diagram?', prompt: 'Tell me more about this diagram?' },
+      { label: 'Help me understand this diagram', prompt: 'Help me understand this diagram' },
+      { label: 'What is the context of this diagram?', prompt: 'What is the context of this diagram, what is it related to?' },
+    ],
+  },
+  // Match /schemas with specType=graphql as query parameter
+  {
+    pattern: /^\/schemas.*[?&]specType=graphql/,
+    questions: [
+      { label: 'Tell me more about this GraphQL schema', prompt: 'Tell me more about this GraphQL schema' },
+      { label: 'What queries are available?', prompt: 'What queries are available in this GraphQL schema?' },
+      { label: 'What mutations are available?', prompt: 'What mutations are available in this GraphQL schema?' },
+      { label: 'Show me the types defined', prompt: 'Show me the types defined in this GraphQL schema' },
+    ],
+  },
+  {
+    pattern: /^\/schemas.*[?&]specType=openapi/,
+    questions: [
+      { label: 'Tell me more about this OpenAPI schema', prompt: 'Tell me more about this OpenAPI schema' },
+      { label: 'Show me the endpoints available', prompt: 'Show me the endpoints available in this OpenAPI schema' },
+      {
+        label: 'Show me the request and response formats',
+        prompt: 'Show me the request and response formats in this OpenAPI schema',
+      },
+    ],
+  },
+  {
+    pattern: /^\/schemas.*[?&]specType=asyncapi/,
+    questions: [
+      { label: 'Tell me more about this AsyncAPI schema', prompt: 'Tell me more about this AsyncAPI schema' },
+      { label: 'Show me the channels available', prompt: 'Show me the channels available in this AsyncAPI schema' },
+      { label: 'Show me the messages available', prompt: 'Show me the messages available in this AsyncAPI schema' },
+      {
+        label: 'Show me the request and response formats',
+        prompt: 'Show me the request and response formats in this AsyncAPI schema',
+      },
+    ],
+  },
+  {
+    pattern: /^\/schemas/,
+    questions: [
+      { label: 'Tell me more about this schema?', prompt: 'Tell me more about this schema' },
+      { label: 'Who producers or consumes this schema?', prompt: 'Who producers or consumes this schema?' },
+      { label: 'What fields are required?', prompt: 'What fields are required for this schema?' },
+      {
+        label: 'Generate code using this schema',
+        prompt: 'Create a code example of using this schema, ask me for the programming language I want the example in.',
+      },
+    ],
+  },
+
+  // Any other docs page
+  {
+    pattern: /^\/docs\/.+/,
+    questions: [
+      { label: 'Tell me about this', prompt: 'Tell me more about this page' },
+      { label: 'Who is responsible for this?', prompt: 'Who owns this resource?' },
+      { label: 'What else is related to this?', prompt: 'What other resources are related to this?' },
+    ],
+  },
+  // Default questions (fallback)
+  {
+    pattern: /.*/,
+    questions: [
+      { label: 'What domains do we have?', prompt: 'What domains are in my catalog?' },
+      { label: 'Show me all services', prompt: 'What services do I have?' },
+      { label: 'What changed recently?', prompt: 'What are the most recent changes in the catalog?' },
+      { label: 'How does data flow between services?', prompt: 'Show me how data flows between services' },
+    ],
+  },
+];
+
+// Get suggested questions based on current URL path
+const getSuggestedQuestions = (pathname: string): SuggestedQuestion[] => {
+  for (const config of suggestedQuestionsConfig) {
+    if (config.pattern.test(pathname)) {
+      return config.questions;
+    }
+  }
+  // Fallback to last config (default)
+  return suggestedQuestionsConfig[suggestedQuestionsConfig.length - 1].questions;
+};
+
+interface ChatPanelProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+const PANEL_WIDTH = 400;
+
+// Staggered fade-in animation styles (delays account for 800ms panel slide)
+const fadeInStyles = {
+  header: {
+    animation: 'fadeIn 0.5s ease-out 0.3s both',
+  },
+  welcome: {
+    animation: 'fadeIn 0.6s ease-out 0.4s both',
+  },
+  // Label and questions will be staggered individually in the component
+  questionsLabel: {
+    animation: 'fadeIn 0.5s ease-out 0.7s both',
+  },
+  getQuestionStyle: (index: number) => ({
+    animation: `fadeIn 0.5s ease-out ${0.85 + index * 0.12}s both`,
+  }),
+  inputFocus: {
+    animation: 'focusIn 0.6s ease-out 1.4s both',
+  },
+  // Follow-up suggestions animate with staggered fade-in-up
+  getFollowUpStyle: (index: number) => ({
+    animation: `fadeInUp 0.4s ease-out ${index * 0.1}s both`,
+  }),
+};
+
+// Preprocess markdown to fix common formatting issues
+const preprocessMarkdown = (text: string): string => {
+  // Add newlines before headings if they're directly after text (no newline)
+  // This fixes cases like "some text.## Heading" → "some text.\n\n## Heading"
+  return text.replace(/([^\n])(#{1,6}\s)/g, '$1\n\n$2');
+};
+
+// Helper to extract text content from message parts
+const getMessageContent = (message: { parts?: Array<{ type: string; text?: string }> }): string => {
+  if (!message.parts) return '';
+  const rawContent = message.parts
+    .filter((part): part is { type: 'text'; text: string } => part.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text)
+    .join('');
+  return preprocessMarkdown(rawContent);
+};
+
+// Helper to extract follow-up suggestions from message parts
+const getFollowUpSuggestions = (message: { parts?: Array<any> }): string[] => {
+  if (!message.parts) return [];
+
+  for (const part of message.parts) {
+    // AI SDK format: type is "tool-{toolName}" and result is in "output"
+    if (part.type === 'tool-suggestFollowUpQuestions' && part.state === 'output-available') {
+      const suggestions = part.output?.suggestions;
+      if (suggestions && Array.isArray(suggestions)) {
+        return suggestions;
+      }
+    }
+  }
+  return [];
+};
+
+// Helper to extract currently running tools from message parts
+const getRunningTools = (message: { parts?: Array<any> }): string[] => {
+  if (!message.parts) return [];
+
+  const runningTools: string[] = [];
+  for (const part of message.parts) {
+    // Tool parts have type like "tool-{toolName}" and state indicates progress
+    if (part.type?.startsWith('tool-') && part.state !== 'output-available') {
+      // Extract tool name from type (e.g., "tool-getServiceHealth" -> "getServiceHealth")
+      const toolName = part.type.replace('tool-', '');
+      // Skip the follow-up suggestions tool as it's internal
+      if (toolName !== 'suggestFollowUpQuestions') {
+        runningTools.push(toolName);
+      }
+    }
+  }
+  return runningTools;
+};
+
+// Helper to extract completed tools from message parts (for showing after completion)
+const getCompletedTools = (message: { parts?: Array<any> }): string[] => {
+  if (!message.parts) return [];
+
+  const completedTools: string[] = [];
+  for (const part of message.parts) {
+    // Tool parts have type like "tool-{toolName}" and state 'output-available' when done
+    if (part.type?.startsWith('tool-') && part.state === 'output-available') {
+      const toolName = part.type.replace('tool-', '');
+      // Skip internal tools
+      if (toolName !== 'suggestFollowUpQuestions') {
+        completedTools.push(toolName);
+      }
+    }
+  }
+  return completedTools;
+};
+
+// Skeleton loading component - memoized since it never changes
+const SkeletonLoader = memo(() => (
+  <div className="animate-pulse space-y-3">
+    <div className="h-4 bg-[rgb(var(--ec-content-hover))] rounded w-[90%]" />
+    <div className="h-4 bg-[rgb(var(--ec-content-hover))] rounded w-[75%]" />
+    <div className="h-4 bg-[rgb(var(--ec-content-hover))] rounded w-[85%]" />
+    <div className="h-4 bg-[rgb(var(--ec-content-hover))] rounded w-[60%]" />
+  </div>
+));
+SkeletonLoader.displayName = 'SkeletonLoader';
+
+// Memoized markdown components to prevent re-renders
+const markdownComponents = {
+  a: ({ ...props }: any) => (
+    <a
+      {...props}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="text-[rgb(var(--ec-accent))] hover:text-[rgb(var(--ec-accent-hover))] underline"
+    />
+  ),
+  code: ({ children, className, ...props }: any) => {
+    const isInline = !className;
+    const match = /language-(\w+)/.exec(className || '');
+    const language = match ? match[1] : 'text';
+    const codeString = String(children).replace(/\n$/, '');
+
+    return isInline ? (
+      <code
+        className="px-1 py-0.5 rounded text-xs font-mono bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-page-text))]"
+        {...props}
+      >
+        {children}
+      </code>
+    ) : (
+      <CodeBlock language={language}>{codeString}</CodeBlock>
+    );
+  },
+  table: ({ ...props }: any) => (
+    <div className="overflow-x-auto my-3">
+      <table className="min-w-full text-xs border-collapse border border-[rgb(var(--ec-page-border))]" {...props} />
+    </div>
+  ),
+  thead: ({ ...props }: any) => <thead className="bg-[rgb(var(--ec-content-hover))]" {...props} />,
+  th: ({ ...props }: any) => (
+    <th
+      className="px-3 py-2 text-left font-medium text-[rgb(var(--ec-page-text))] border border-[rgb(var(--ec-page-border))]"
+      {...props}
+    />
+  ),
+  td: ({ ...props }: any) => (
+    <td className="px-3 py-2 text-[rgb(var(--ec-page-text-muted))] border border-[rgb(var(--ec-page-border))]" {...props} />
+  ),
+};
+
+// Modal version with slightly different code styling
+const modalMarkdownComponents = {
+  ...markdownComponents,
+  code: ({ children, className, ...props }: any) => {
+    const isInline = !className;
+    const match = /language-(\w+)/.exec(className || '');
+    const language = match ? match[1] : 'text';
+    const codeString = String(children).replace(/\n$/, '');
+
+    return isInline ? (
+      <code
+        className="px-1.5 py-0.5 rounded text-sm font-mono bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-page-text))]"
+        {...props}
+      >
+        {children}
+      </code>
+    ) : (
+      <CodeBlock language={language}>{codeString}</CodeBlock>
+    );
+  },
+  table: ({ ...props }: any) => (
+    <div className="overflow-x-auto my-3">
+      <table className="min-w-full text-sm border-collapse border border-[rgb(var(--ec-page-border))]" {...props} />
+    </div>
+  ),
+};
+
+const ChatPanel = ({ isOpen, onClose }: ChatPanelProps) => {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const modalInputRef = useRef<HTMLInputElement>(null);
+  const messagesEndRef = useRef<HTMLDivElement>(null);
+  const modalMessagesEndRef = useRef<HTMLDivElement>(null);
+  const messagesContainerRef = useRef<HTMLDivElement>(null);
+  const [inputValue, setInputValue] = useState('');
+  const [isWaitingForResponse, setIsWaitingForResponse] = useState(false);
+  const [pathname, setPathname] = useState('');
+  const [isFullscreen, setIsFullscreen] = useState(false);
+  const [tools, setTools] = useState<ToolMetadata[]>([]);
+  const [showScrollButton, setShowScrollButton] = useState(false);
+  const chatApiUrl = useMemo(() => buildUrl('/api/chat', true), []);
+  const chatTransport = useMemo(() => new DefaultChatTransport({ api: chatApiUrl }), [chatApiUrl]);
+
+  // Sort tools with custom ones first
+  const sortedTools = useMemo(() => {
+    return [...tools].sort((a, b) => {
+      if (a.isCustom && !b.isCustom) return -1;
+      if (!a.isCustom && b.isCustom) return 1;
+      return 0;
+    });
+  }, [tools]);
+
+  // Fetch available tools when panel opens
+  useEffect(() => {
+    if (isOpen && tools.length === 0) {
+      fetch(chatApiUrl)
+        .then((res) => res.json())
+        .then((data) => {
+          if (data.tools) {
+            setTools(data.tools);
+          }
+        })
+        .catch(() => {
+          // Silently fail - tools info is optional
+        });
+    }
+  }, [isOpen, tools.length]);
+
+  // Get current URL (pathname + search) on mount and when panel opens
+  useEffect(() => {
+    setPathname(window.location.pathname + window.location.search);
+  }, [isOpen]);
+
+  // Memoize suggested questions to avoid recalculating on every render
+  const suggestedQuestions = useMemo(() => getSuggestedQuestions(pathname), [pathname]);
+
+  // Memoize page context to avoid recalculating on every render
+  const pageContext = useMemo(() => {
+    const match = pathname.match(
+      /^\/(docs|visualiser|architecture)\/(events|services|commands|queries|flows|domains|systems|channels|entities|containers|data-products)\/([^/]+)(?:\/([^/]+))?/
+    );
+    if (match) {
+      const [, , collection, id, version] = match;
+      const collectionNames: Record<string, string> = {
+        events: 'Event',
+        services: 'Service',
+        commands: 'Command',
+        queries: 'Query',
+        flows: 'Flow',
+        domains: 'Domain',
+        systems: 'System',
+        channels: 'Channel',
+        entities: 'Entity',
+        containers: 'Container',
+        'data-products': 'Data Product',
+      };
+      return {
+        type: collectionNames[collection] || collection,
+        name: id,
+        version: version || 'latest',
+      };
+    }
+    return null;
+  }, [pathname]);
+
+  // Handle scroll to detect if user scrolled up
+  const handleScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
+    const target = e.target as HTMLDivElement;
+    const isNearBottom = target.scrollHeight - target.scrollTop - target.clientHeight < 100;
+    setShowScrollButton(!isNearBottom);
+  }, []);
+
+  const { messages, sendMessage, stop, status, setMessages, error } = useChat({ transport: chatTransport });
+
+  // Extract user-friendly error message
+  const errorMessage = error?.message || 'Something went wrong. Please try again.';
+
+  // Memoize last assistant message to avoid array operations on every render
+  const lastAssistantMessage = useMemo(() => messages.findLast((m) => m.role === 'assistant'), [messages]);
+
+  // Check if the assistant has started outputting content
+  const assistantHasContent = useMemo(
+    () => lastAssistantMessage?.parts?.some((p) => p.type === 'text' && (p as { type: 'text'; text: string }).text.length > 0),
+    [lastAssistantMessage]
+  );
+
+  // Clear waiting state once assistant starts outputting or on error
+  useEffect(() => {
+    if (assistantHasContent || status === 'error') {
+      setIsWaitingForResponse(false);
+    }
+  }, [assistantHasContent, status]);
+
+  const isStreaming = status === 'streaming' && assistantHasContent;
+  const isThinking =
+    isWaitingForResponse || (messages.length > 0 && (status === 'submitted' || status === 'streaming') && !assistantHasContent);
+  const isLoading = isThinking || isStreaming;
+
+  // Get currently running tools from the last assistant message
+  const runningTools = useMemo(() => (lastAssistantMessage ? getRunningTools(lastAssistantMessage) : []), [lastAssistantMessage]);
+
+  // Scroll to bottom when new messages arrive
+  const scrollToBottom = useCallback(() => {
+    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
+  }, []);
+
+  useEffect(() => {
+    scrollToBottom();
+    // Also scroll modal messages
+    modalMessagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
+  }, [messages, scrollToBottom]);
+
+  // Focus modal input when fullscreen opens
+  useEffect(() => {
+    if (isFullscreen && !isLoading) {
+      setTimeout(() => {
+        modalInputRef.current?.focus();
+      }, 100);
+    }
+  }, [isFullscreen, isLoading]);
+
+  // Handle escape key to close
+  useEffect(() => {
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === 'Escape' && isOpen) {
+        onClose();
+      }
+      // Focus input on CMD+I or CTRL+I
+      if ((e.metaKey || e.ctrlKey) && e.key === 'i' && isOpen) {
+        e.preventDefault();
+        inputRef.current?.focus();
+      }
+    };
+    document.addEventListener('keydown', handleEscape);
+    return () => document.removeEventListener('keydown', handleEscape);
+  }, [isOpen, onClose]);
+
+  // Focus input when opened and not loading
+  useEffect(() => {
+    if (isOpen && !isLoading) {
+      setTimeout(() => {
+        inputRef.current?.focus();
+      }, 100);
+    }
+  }, [isOpen, isLoading]);
+
+  // Add/remove padding to main application and header when sidebar panel is open
+  useEffect(() => {
+    const appEl = document.getElementById('eventcatalog-application');
+    const headerEl = document.getElementById('eventcatalog-header');
+    const docsSidebarEl = document.getElementById('eventcatalog-docs-sidebar');
+
+    const elements = [appEl, headerEl].filter(Boolean) as HTMLElement[];
+
+    elements.forEach((el) => {
+      // Add transition if not already present
+      if (!el.style.transition) {
+        el.style.transition = 'padding-right 800ms cubic-bezier(0.16, 1, 0.3, 1)';
+      }
+
+      // Only add padding when panel is open AND not in fullscreen mode
+      if (isOpen && !isFullscreen) {
+        el.style.paddingRight = `${PANEL_WIDTH}px`;
+      } else {
+        el.style.paddingRight = '0';
+      }
+    });
+
+    // Hide docs sidebar when chat panel is open
+    if (docsSidebarEl) {
+      if (isOpen && !isFullscreen) {
+        docsSidebarEl.style.display = 'none';
+      } else {
+        docsSidebarEl.style.display = '';
+      }
+    }
+
+    // Cleanup on unmount
+    return () => {
+      elements.forEach((el) => {
+        el.style.paddingRight = '0';
+      });
+      if (docsSidebarEl) {
+        docsSidebarEl.style.display = '';
+      }
+    };
+  }, [isOpen, isFullscreen]);
+
+  // Submit message handler
+  const submitMessage = useCallback(
+    (text: string) => {
+      if (!text.trim() || isLoading) return;
+      setInputValue('');
+      setIsWaitingForResponse(true);
+      sendMessage({ text });
+    },
+    [isLoading, sendMessage]
+  );
+
+  // Handle suggested action clicks
+  const handleSuggestedAction = useCallback(
+    (prompt: string) => {
+      submitMessage(prompt);
+    },
+    [submitMessage]
+  );
+
+  // Handle input enter key
+  const handleInputKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (e.key === 'Enter' && !e.shiftKey) {
+        e.preventDefault();
+        submitMessage(inputValue);
+      }
+    },
+    [inputValue, submitMessage]
+  );
+
+  // Handle form submit
+  const handleSubmit = useCallback(
+    (e: React.FormEvent) => {
+      e.preventDefault();
+      submitMessage(inputValue);
+    },
+    [inputValue, submitMessage]
+  );
+
+  const hasMessages = messages.length > 0;
+
+  // Memoize greeting - only changes when hour changes (effectively stable during session)
+  const greeting = useMemo(() => getGreeting(), []);
+
+  return (
+    <>
+      {/* Keyframes for fade-in animation - using constant to avoid re-injection */}
+      <style>{CHAT_PANEL_STYLES}</style>
+
+      {/* Panel - hidden when fullscreen modal is open */}
+      {!isFullscreen && (
+        <div
+          className="fixed top-0 right-0 h-[100vh] z-[200] border-l border-[rgb(var(--ec-page-border))] flex flex-col overflow-hidden"
+          style={{
+            width: `${PANEL_WIDTH}px`,
+            transform: isOpen ? 'translateX(0)' : `translateX(${PANEL_WIDTH}px)`,
+            transition: 'transform 800ms cubic-bezier(0.16, 1, 0.3, 1)',
+            background: `
+              radial-gradient(ellipse 100% 40% at 50% 100%, rgb(var(--ec-accent) / 0.15) 0%, transparent 100%),
+              rgb(var(--ec-page-bg))
+            `,
+          }}
+        >
+          {/* Header */}
+          <div className="flex-none shrink-0 border-b border-[rgb(var(--ec-page-border))]">
+            <div className="flex items-center justify-between px-4 py-3">
+              <div className="flex items-center space-x-2">
+                <BookOpen size={16} className="text-[rgb(var(--ec-accent))]" />
+                <span className="font-medium text-[rgb(var(--ec-header-text))] text-sm">EventCatalog Assistant</span>
+              </div>
+              <div className="flex items-center space-x-1">
+                {tools.length > 0 && (
+                  <Popover.Root>
+                    <Popover.Trigger asChild>
+                      <button
+                        className="p-2 rounded-lg hover:bg-[rgb(var(--ec-header-border))] text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-header-text))] transition-colors"
+                        aria-label="View available tools"
+                        title="Available tools"
+                      >
+                        <Wrench size={16} />
+                      </button>
+                    </Popover.Trigger>
+                    <Popover.Portal>
+                      <Popover.Content
+                        className="w-72 bg-[rgb(var(--ec-dropdown-bg))] rounded-lg shadow-lg border border-[rgb(var(--ec-dropdown-border))] p-3 z-[250]"
+                        sideOffset={5}
+                        align="end"
+                      >
+                        <div className="text-[10px] font-medium text-[rgb(var(--ec-page-text-muted))] mb-2">
+                          Available Tools ({sortedTools.length})
+                        </div>
+                        <div className="max-h-64 overflow-y-auto divide-y divide-[rgb(var(--ec-page-border))]">
+                          {sortedTools.map((tool) => (
+                            <div key={tool.name} className="py-1.5 first:pt-0 last:pb-0">
+                              <div className="flex items-center gap-1.5">
+                                <span className="text-[11px] font-medium text-[rgb(var(--ec-dropdown-text))]">{tool.name}</span>
+                                {tool.isCustom && (
+                                  <span className="px-1.5 py-0.5 text-[9px] font-medium bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent-text))] rounded">
+                                    Custom
+                                  </span>
+                                )}
+                              </div>
+                              <div className="text-[10px] text-[rgb(var(--ec-page-text-muted))] mt-0.5">{tool.description}</div>
+                            </div>
+                          ))}
+                        </div>
+                        <Popover.Arrow className="fill-[rgb(var(--ec-dropdown-bg))]" />
+                      </Popover.Content>
+                    </Popover.Portal>
+                  </Popover.Root>
+                )}
+                <button
+                  onClick={() => setIsFullscreen(true)}
+                  className="p-2 rounded-lg hover:bg-[rgb(var(--ec-header-border))] text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-header-text))] transition-colors"
+                  aria-label="Expand to fullscreen"
+                  title="Expand"
+                >
+                  <Maximize2 size={16} />
+                </button>
+                {hasMessages && (
+                  <button
+                    onClick={() => setMessages([])}
+                    className="p-2 rounded-lg hover:bg-[rgb(var(--ec-header-border))] text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-header-text))] transition-colors"
+                    aria-label="Clear chat"
+                    title="Clear chat"
+                  >
+                    <Trash2 size={18} />
+                  </button>
+                )}
+                <button
+                  onClick={onClose}
+                  className="p-2 rounded-lg hover:bg-[rgb(var(--ec-header-border))] text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-header-text))] transition-colors"
+                  aria-label="Close chat panel"
+                >
+                  <X size={18} />
+                </button>
+              </div>
+            </div>
+            {/* Thinking indicator */}
+            {isThinking && (
+              <div className="px-4 pb-2 flex items-center gap-2">
+                <div className="w-1.5 h-1.5 bg-[rgb(var(--ec-accent))] rounded-full animate-pulse" />
+                <span className="text-xs text-[rgb(var(--ec-icon-color))]">
+                  {runningTools.length > 0 ? (
+                    <>
+                      Using <span className="font-medium text-[rgb(var(--ec-accent))]">{runningTools[0]}</span>...
+                    </>
+                  ) : (
+                    'Thinking...'
+                  )}
+                </span>
+              </div>
+            )}
+          </div>
+
+          {/* Content */}
+          <div className="flex-1 flex flex-col min-h-0 relative overflow-hidden" key={isOpen ? 'content-open' : 'content-closed'}>
+            {/* Messages or Welcome area */}
+            <div ref={messagesContainerRef} onScroll={handleScroll} className="flex-1 overflow-y-auto px-5 scrollbar-hide">
+              {!hasMessages ? (
+                /* Welcome area - Clean GitBook-inspired design */
+                <div className="flex flex-col h-full py-6">
+                  {/* Greeting section - centered */}
+                  <div
+                    className="flex-1 flex flex-col items-center justify-center text-center"
+                    style={isOpen ? fadeInStyles.welcome : undefined}
+                  >
+                    {/* Icon with circular background */}
+                    <div className="relative mb-6">
+                      <div className="w-32 h-32 rounded-full bg-[rgb(var(--ec-accent)/0.15)] flex items-center justify-center">
+                        <MessageSquare size={56} className="text-[rgb(var(--ec-accent))]" strokeWidth={1.5} />
+                      </div>
+                    </div>
+                    <h2 className="text-lg font-semibold text-[rgb(var(--ec-accent))] mb-1">{greeting}</h2>
+                    <p className="text-sm font-normal text-[rgb(var(--ec-content-text))]">
+                      I'm here to help with your architecture
+                    </p>
+                  </div>
+
+                  {/* Suggested questions - pill style */}
+                  <div className="flex-none space-y-2">
+                    {suggestedQuestions.map((question, index) => (
+                      <button
+                        key={index}
+                        onClick={() => handleSuggestedAction(question.prompt)}
+                        className="w-full text-left px-4 py-2.5 text-xs text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-page-text)/0.05)] hover:bg-[rgb(var(--ec-accent)/0.15)] rounded-full transition-all duration-200"
+                        style={isOpen ? fadeInStyles.getQuestionStyle(index) : undefined}
+                      >
+                        {question.label}
+                      </button>
+                    ))}
+                  </div>
+                </div>
+              ) : (
+                /* Messages area */
+                <div className="py-4 space-y-4">
+                  {messages.map((message, messageIndex) => {
+                    const content = getMessageContent(message);
+                    const followUpSuggestions = message.role === 'assistant' ? getFollowUpSuggestions(message) : [];
+                    const completedTools = message.role === 'assistant' ? getCompletedTools(message) : [];
+                    const isLastMessage = messageIndex === messages.length - 1;
+                    return (
+                      <div key={message.id} className={`flex flex-col ${message.role === 'user' ? 'items-end' : 'items-start'}`}>
+                        {message.role === 'user' ? (
+                          <div className="max-w-[85%] rounded-2xl rounded-br-md px-4 py-2.5 bg-[rgb(var(--ec-page-text)/0.05)]">
+                            <p className="text-sm font-normal whitespace-pre-wrap text-[rgb(var(--ec-page-text))]">{content}</p>
+                          </div>
+                        ) : (
+                          <>
+                            {/* Tools used indicator */}
+                            {completedTools.length > 0 && (
+                              <div className="flex items-center gap-1.5 mb-2">
+                                <Wrench size={10} className="text-[rgb(var(--ec-icon-color))]" />
+                                <span className="text-[10px] text-[rgb(var(--ec-icon-color))]">
+                                  Used{' '}
+                                  {completedTools.slice(0, 2).map((tool, i) => (
+                                    <span key={tool}>
+                                      <span className="font-medium text-[rgb(var(--ec-accent))]">{tool}</span>
+                                      {i < Math.min(completedTools.length, 2) - 1 && ', '}
+                                    </span>
+                                  ))}
+                                  {completedTools.length > 2 && <span> +{completedTools.length - 2} more</span>}
+                                </span>
+                              </div>
+                            )}
+                            <div className="w-full text-[rgb(var(--ec-content-text))]">
+                              <div className="prose prose-sm max-w-none prose-p:my-2 prose-p:font-normal prose-p:text-[13px] prose-p:text-[rgb(var(--ec-content-text))] prose-headings:my-2 prose-headings:font-semibold prose-headings:text-[rgb(var(--ec-page-text))] prose-h1:text-base prose-h2:text-sm prose-h3:text-[13px] prose-h4:text-[13px] prose-ul:my-2 prose-ol:my-2 prose-li:my-0.5 prose-li:text-[13px] prose-li:font-normal prose-li:text-[rgb(var(--ec-content-text))] text-[13px] font-light">
+                                <ReactMarkdown remarkPlugins={[remarkGfm]} components={markdownComponents}>
+                                  {content}
+                                </ReactMarkdown>
+                              </div>
+                            </div>
+                            {/* Follow-up suggestions - only show for last assistant message when not loading */}
+                            {isLastMessage && followUpSuggestions.length > 0 && !isLoading && (
+                              <div className="flex flex-wrap gap-2 mt-3 w-full">
+                                {followUpSuggestions.map((suggestion, index) => (
+                                  <button
+                                    key={index}
+                                    onClick={() => handleSuggestedAction(suggestion)}
+                                    className="px-4 py-2.5 text-xs text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-page-text)/0.05)] hover:bg-[rgb(var(--ec-accent)/0.15)] rounded-full transition-all duration-200 text-left"
+                                    style={fadeInStyles.getFollowUpStyle(index)}
+                                  >
+                                    {suggestion}
+                                  </button>
+                                ))}
+                              </div>
+                            )}
+                          </>
+                        )}
+                      </div>
+                    );
+                  })}
+
+                  {/* Skeleton loading indicator */}
+                  {isThinking && (
+                    <div className="w-full">
+                      <SkeletonLoader />
+                    </div>
+                  )}
+
+                  {/* Error message as chat bubble */}
+                  {status === 'error' && (
+                    <div className="flex justify-start">
+                      <div className="w-full">
+                        <div className="flex items-start gap-2 text-red-600 text-sm">
+                          <span className="shrink-0">⚠️</span>
+                          <span>{errorMessage}</span>
+                        </div>
+                      </div>
+                    </div>
+                  )}
+
+                  <div ref={messagesEndRef} />
+                </div>
+              )}
+            </div>
+
+            {/* Scroll to bottom button */}
+            {hasMessages && showScrollButton && (
+              <button
+                onClick={scrollToBottom}
+                className="absolute bottom-24 right-4 flex items-center gap-1.5 px-3 py-1.5 bg-[rgb(var(--ec-card-bg))] text-[rgb(var(--ec-page-text-muted))] text-xs font-medium rounded-full shadow-lg border border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-content-hover))] transition-all z-10"
+              >
+                <ChevronDown size={14} />
+                <span>Scroll to bottom</span>
+              </button>
+            )}
+
+            {/* Input area (Fixed at bottom) */}
+            <div className="flex-none px-4 py-3" key={isOpen ? 'input-open' : 'input-closed'}>
+              <form onSubmit={handleSubmit}>
+                <div className="relative bg-[rgb(var(--ec-page-bg)/0.5)] backdrop-blur-sm rounded-xl border border-[rgb(var(--ec-accent)/0.3)] focus-within:border-[rgb(var(--ec-accent)/0.5)] focus-within:ring-2 focus-within:ring-[rgb(var(--ec-accent)/0.1)] transition-all">
+                  <input
+                    ref={inputRef}
+                    type="text"
+                    value={inputValue}
+                    onChange={(e) => setInputValue(e.target.value)}
+                    onKeyDown={handleInputKeyDown}
+                    placeholder="Ask, search, or explain..."
+                    disabled={isLoading}
+                    className="w-full px-4 py-3 pr-16 bg-transparent text-[rgb(var(--ec-input-text))] placeholder-[rgb(var(--ec-input-placeholder))] focus:outline-hidden text-sm disabled:opacity-50 rounded-xl"
+                  />
+                  <div className="absolute right-2 top-1/2 -translate-y-1/2 z-10">
+                    {isStreaming ? (
+                      <button
+                        type="button"
+                        onClick={() => stop()}
+                        className="p-2 text-red-500 hover:bg-red-500/10 rounded-lg transition-colors"
+                        aria-label="Stop generating"
+                      >
+                        <Square size={14} fill="currentColor" />
+                      </button>
+                    ) : (
+                      <button
+                        type="submit"
+                        disabled={!inputValue.trim() || isLoading}
+                        className="px-3 py-1.5 bg-[rgb(var(--ec-accent))] text-white text-xs font-medium rounded-lg hover:bg-[rgb(var(--ec-accent-hover))] disabled:bg-transparent disabled:text-[rgb(var(--ec-icon-color))] transition-colors"
+                        aria-label="Send message"
+                      >
+                        Send
+                      </button>
+                    )}
+                  </div>
+                </div>
+              </form>
+              {/* Context indicator */}
+              <div className="flex items-center justify-center gap-1.5 mt-2">
+                {pageContext ? (
+                  <span className="text-[10px] text-[rgb(var(--ec-icon-color))] flex items-center gap-1">
+                    <span className="w-1.5 h-1.5 rounded-full bg-[rgb(var(--ec-accent))]" />
+                    Based on {pageContext.type}: {pageContext.name}
+                  </span>
+                ) : (
+                  <span className="text-[10px] text-[rgb(var(--ec-icon-color))]">
+                    AI can make mistakes. Verify important info.
+                  </span>
+                )}
+              </div>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Fullscreen Modal */}
+      <Dialog.Root
+        open={isFullscreen}
+        onOpenChange={(open) => {
+          setIsFullscreen(open);
+          // If modal is being closed (clicking outside, etc.), close the chat entirely
+          if (!open) {
+            onClose();
+          }
+        }}
+      >
+        <Dialog.Portal>
+          <Dialog.Overlay className="fixed inset-0 bg-black/50 backdrop-blur-sm z-[300]" />
+          <Dialog.Content
+            className="fixed inset-y-4 left-1/2 -translate-x-1/2 w-[95%] max-w-4xl md:inset-y-8 rounded-xl shadow-2xl z-[301] flex flex-col overflow-hidden focus:outline-hidden border border-[rgb(var(--ec-page-border))]"
+            style={{
+              background: `
+                radial-gradient(ellipse 100% 40% at 50% 100%, rgb(var(--ec-accent) / 0.15) 0%, transparent 100%),
+                rgb(var(--ec-page-bg))
+              `,
+            }}
+          >
+            {/* Modal Header */}
+            <div className="flex items-center justify-between px-5 py-3 border-b border-[rgb(var(--ec-page-border))] flex-shrink-0">
+              <div className="flex items-center space-x-2.5">
+                <div className="p-1.5 bg-[rgb(var(--ec-accent-subtle))] rounded-lg">
+                  <BookOpen size={18} className="text-[rgb(var(--ec-accent))]" />
+                </div>
+                <Dialog.Title className="text-base font-medium text-[rgb(var(--ec-page-text))]">Ask AI</Dialog.Title>
+              </div>
+              <div className="flex items-center space-x-2">
+                {tools.length > 0 && (
+                  <Popover.Root>
+                    <Popover.Trigger asChild>
+                      <button
+                        className="p-2 rounded-lg hover:bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                        aria-label="View available tools"
+                        title="Available tools"
+                      >
+                        <Wrench size={18} />
+                      </button>
+                    </Popover.Trigger>
+                    <Popover.Portal>
+                      <Popover.Content
+                        className="w-80 bg-[rgb(var(--ec-dropdown-bg))] rounded-lg shadow-lg border border-[rgb(var(--ec-dropdown-border))] p-4 z-[350]"
+                        sideOffset={5}
+                        align="end"
+                        style={{ maxHeight: 'calc(100vh - 200px)' }}
+                      >
+                        <div className="text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] mb-2">
+                          Available Tools ({sortedTools.length})
+                        </div>
+                        <div
+                          className="overflow-y-auto divide-y divide-[rgb(var(--ec-page-border))]"
+                          style={{ maxHeight: 'calc(100vh - 280px)' }}
+                        >
+                          {sortedTools.map((tool) => (
+                            <div key={tool.name} className="py-2 first:pt-0 last:pb-0">
+                              <div className="flex items-center gap-1.5">
+                                <span className="text-xs font-medium text-[rgb(var(--ec-dropdown-text))]">{tool.name}</span>
+                                {tool.isCustom && (
+                                  <span className="px-1.5 py-0.5 text-[9px] font-medium bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent-text))] rounded">
+                                    Custom
+                                  </span>
+                                )}
+                              </div>
+                              <div className="text-[11px] text-[rgb(var(--ec-page-text-muted))] mt-0.5">{tool.description}</div>
+                            </div>
+                          ))}
+                        </div>
+                        <Popover.Arrow className="fill-[rgb(var(--ec-dropdown-bg))]" />
+                      </Popover.Content>
+                    </Popover.Portal>
+                  </Popover.Root>
+                )}
+                {hasMessages && (
+                  <button
+                    onClick={() => setMessages([])}
+                    className="p-2 rounded-lg hover:bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                    aria-label="Clear chat"
+                    title="Clear chat"
+                  >
+                    <Trash2 size={18} />
+                  </button>
+                )}
+                <button
+                  onClick={() => setIsFullscreen(false)}
+                  className="p-2 rounded-lg hover:bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                  aria-label="Exit fullscreen"
+                  title="Exit fullscreen"
+                >
+                  <Minimize2 size={18} />
+                </button>
+                <button
+                  onClick={() => {
+                    setIsFullscreen(false);
+                    onClose();
+                  }}
+                  className="p-2 rounded-lg hover:bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                  aria-label="Close"
+                >
+                  <X size={18} />
+                </button>
+              </div>
+            </div>
+
+            {/* Thinking indicator */}
+            {isThinking && (
+              <div className="px-5 py-2 flex items-center gap-2 border-b border-[rgb(var(--ec-page-border))]">
+                <div className="w-1.5 h-1.5 bg-[rgb(var(--ec-accent))] rounded-full animate-pulse" />
+                <span className="text-sm text-[rgb(var(--ec-page-text-muted))]">
+                  {runningTools.length > 0 ? (
+                    <>
+                      Using <span className="font-medium text-[rgb(var(--ec-accent))]">{runningTools[0]}</span>...
+                    </>
+                  ) : (
+                    'Thinking...'
+                  )}
+                </span>
+              </div>
+            )}
+
+            {/* Modal Content */}
+            <div className="flex-1 overflow-y-auto px-6 py-6">
+              {!hasMessages ? (
+                /* Welcome area - Clean design */
+                <div className="flex flex-col h-full max-w-2xl mx-auto">
+                  {/* Greeting section - centered */}
+                  <div className="flex-1 flex flex-col justify-center items-center text-center">
+                    {/* Icon with circular background */}
+                    <div className="relative mb-8">
+                      <div className="w-40 h-40 rounded-full bg-[rgb(var(--ec-accent)/0.15)] flex items-center justify-center">
+                        <MessageSquare size={72} className="text-[rgb(var(--ec-accent))]" strokeWidth={1.5} />
+                      </div>
+                    </div>
+                    <h2 className="text-2xl font-semibold text-[rgb(var(--ec-accent))] mb-2">{greeting}</h2>
+                    <p className="font-normal text-[rgb(var(--ec-content-text))] text-center">
+                      I'm here to help with your architecture
+                    </p>
+                  </div>
+
+                  {/* Suggested questions - pill style */}
+                  <div className="flex-none grid grid-cols-2 gap-2">
+                    {suggestedQuestions.map((question, index) => (
+                      <button
+                        key={index}
+                        onClick={() => handleSuggestedAction(question.prompt)}
+                        className="px-4 py-2.5 text-xs text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-page-text)/0.05)] hover:bg-[rgb(var(--ec-accent)/0.15)] rounded-full transition-all duration-200 text-left"
+                      >
+                        {question.label}
+                      </button>
+                    ))}
+                  </div>
+                </div>
+              ) : (
+                /* Messages area */
+                <div className="max-w-3xl mx-auto space-y-4">
+                  {messages.map((message, messageIndex) => {
+                    const content = getMessageContent(message);
+                    const followUpSuggestions = message.role === 'assistant' ? getFollowUpSuggestions(message) : [];
+                    const completedTools = message.role === 'assistant' ? getCompletedTools(message) : [];
+                    const isLastMessage = messageIndex === messages.length - 1;
+                    return (
+                      <div key={message.id} className={`flex flex-col ${message.role === 'user' ? 'items-end' : 'items-start'}`}>
+                        {message.role === 'user' ? (
+                          <div className="max-w-[75%] rounded-2xl rounded-br-md px-4 py-2.5 bg-[rgb(var(--ec-page-text)/0.05)]">
+                            <p className="text-sm font-normal whitespace-pre-wrap text-[rgb(var(--ec-page-text))]">{content}</p>
+                          </div>
+                        ) : (
+                          <>
+                            {/* Tools used indicator */}
+                            {completedTools.length > 0 && (
+                              <div className="flex items-center gap-1.5 mb-2">
+                                <Wrench size={12} className="text-[rgb(var(--ec-icon-color))]" />
+                                <span className="text-[11px] text-[rgb(var(--ec-icon-color))]">
+                                  Used{' '}
+                                  {completedTools.slice(0, 3).map((tool, i) => (
+                                    <span key={tool}>
+                                      <span className="font-medium text-[rgb(var(--ec-accent))]">{tool}</span>
+                                      {i < Math.min(completedTools.length, 3) - 1 && ', '}
+                                    </span>
+                                  ))}
+                                  {completedTools.length > 3 && <span> +{completedTools.length - 3} more</span>}
+                                </span>
+                              </div>
+                            )}
+                            <div className="w-full text-[rgb(var(--ec-content-text))]">
+                              <div className="prose prose-sm max-w-none prose-p:text-[rgb(var(--ec-content-text))] prose-headings:my-2 prose-headings:font-semibold prose-headings:text-[rgb(var(--ec-page-text))] prose-h1:text-lg prose-h2:text-base prose-h3:text-sm prose-h4:text-sm prose-li:text-[rgb(var(--ec-content-text))]">
+                                <ReactMarkdown remarkPlugins={[remarkGfm]} components={modalMarkdownComponents}>
+                                  {content}
+                                </ReactMarkdown>
+                              </div>
+                            </div>
+                            {/* Follow-up suggestions - only show for last assistant message when not loading */}
+                            {isLastMessage && followUpSuggestions.length > 0 && !isLoading && (
+                              <div className="flex flex-wrap gap-2 mt-3 w-full">
+                                {followUpSuggestions.map((suggestion, index) => (
+                                  <button
+                                    key={index}
+                                    onClick={() => handleSuggestedAction(suggestion)}
+                                    className="px-4 py-2.5 text-xs text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-page-text)/0.05)] hover:bg-[rgb(var(--ec-accent)/0.15)] rounded-full transition-all duration-200 text-left"
+                                    style={fadeInStyles.getFollowUpStyle(index)}
+                                  >
+                                    {suggestion}
+                                  </button>
+                                ))}
+                              </div>
+                            )}
+                          </>
+                        )}
+                      </div>
+                    );
+                  })}
+
+                  {isThinking && (
+                    <div className="w-full max-w-md">
+                      <SkeletonLoader />
+                    </div>
+                  )}
+
+                  {/* Error message as chat bubble */}
+                  {status === 'error' && (
+                    <div className="flex justify-start">
+                      <div className="w-full">
+                        <div className="flex items-start gap-2 text-red-600 text-sm">
+                          <span className="shrink-0">⚠️</span>
+                          <span>{errorMessage}</span>
+                        </div>
+                      </div>
+                    </div>
+                  )}
+
+                  <div ref={modalMessagesEndRef} />
+                </div>
+              )}
+            </div>
+
+            {/* Modal Input area */}
+            <div className="flex-shrink-0 px-6 py-4">
+              <form onSubmit={handleSubmit} className="max-w-3xl mx-auto">
+                <div className="relative bg-[rgb(var(--ec-page-bg)/0.5)] backdrop-blur-sm rounded-xl border border-[rgb(var(--ec-accent)/0.3)] focus-within:border-[rgb(var(--ec-accent)/0.5)] focus-within:ring-2 focus-within:ring-[rgb(var(--ec-accent)/0.1)] transition-all">
+                  <input
+                    ref={modalInputRef}
+                    type="text"
+                    value={inputValue}
+                    onChange={(e) => setInputValue(e.target.value)}
+                    onKeyDown={handleInputKeyDown}
+                    placeholder="Ask, search, or explain..."
+                    disabled={isLoading}
+                    className="w-full px-4 py-3.5 pr-20 bg-transparent text-[rgb(var(--ec-input-text))] placeholder-[rgb(var(--ec-input-placeholder))] focus:outline-hidden text-sm disabled:opacity-50 rounded-xl"
+                  />
+                  <div className="absolute right-2 top-1/2 -translate-y-1/2 z-10">
+                    {isStreaming ? (
+                      <button
+                        type="button"
+                        onClick={() => stop()}
+                        className="p-2 text-red-500 hover:bg-red-500/10 rounded-lg transition-colors"
+                        aria-label="Stop generating"
+                      >
+                        <Square size={14} fill="currentColor" />
+                      </button>
+                    ) : (
+                      <button
+                        type="submit"
+                        disabled={!inputValue.trim() || isLoading}
+                        className="px-4 py-2 bg-[rgb(var(--ec-accent))] text-white text-sm font-medium rounded-lg hover:bg-[rgb(var(--ec-accent-hover))] disabled:bg-transparent disabled:text-[rgb(var(--ec-icon-color))] disabled:cursor-not-allowed transition-colors"
+                        aria-label="Send message"
+                      >
+                        Send
+                      </button>
+                    )}
+                  </div>
+                </div>
+              </form>
+              {/* Context indicator */}
+              <div className="flex items-center justify-center gap-1.5 mt-3 max-w-3xl mx-auto">
+                {pageContext ? (
+                  <span className="text-xs text-[rgb(var(--ec-icon-color))] flex items-center gap-1.5">
+                    <span className="w-1.5 h-1.5 rounded-full bg-[rgb(var(--ec-accent))]" />
+                    Based on {pageContext.type}: {pageContext.name}
+                  </span>
+                ) : (
+                  <span className="text-xs text-[rgb(var(--ec-icon-color))]">AI can make mistakes. Verify important info.</span>
+                )}
+              </div>
+            </div>
+          </Dialog.Content>
+        </Dialog.Portal>
+      </Dialog.Root>
+    </>
+  );
+};
+
+export default ChatPanel;
diff --git a/packages/core/eventcatalog/src/components/ChatPanel/ChatPanelButton.tsx b/packages/core/eventcatalog/src/components/ChatPanel/ChatPanelButton.tsx
new file mode 100644
index 000000000..91acb4b15
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/ChatPanel/ChatPanelButton.tsx
@@ -0,0 +1,34 @@
+import { useState, useEffect } from 'react';
+import { BookOpen } from 'lucide-react';
+import ChatPanel from './ChatPanel';
+
+const ChatPanelButton = () => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  // Listen for custom event to open chat panel from other components
+  useEffect(() => {
+    const handleOpenChat = () => {
+      setIsOpen(true);
+    };
+
+    window.addEventListener('eventcatalog:open-chat', handleOpenChat);
+    return () => window.removeEventListener('eventcatalog:open-chat', handleOpenChat);
+  }, []);
+
+  return (
+    <>
+      <button
+        onClick={() => setIsOpen(true)}
+        className="flex items-center gap-1.5 px-4 py-1.5 rounded-md bg-[rgb(var(--ec-card-bg))] hover:bg-[rgb(var(--ec-content-hover))] ring-1 ring-inset ring-[rgb(var(--ec-page-border))] shadow-xs transition-colors text-sm ml-[-1px]"
+        aria-label="Open AI Assistant"
+      >
+        <BookOpen size={14} className="text-[rgb(var(--ec-accent))]" />
+        <span className="font-light text-[rgb(var(--ec-page-text-muted))]">Ask</span>
+      </button>
+
+      <ChatPanel isOpen={isOpen} onClose={() => setIsOpen(false)} />
+    </>
+  );
+};
+
+export default ChatPanelButton;
diff --git a/eventcatalog/src/components/Checkbox.astro b/packages/core/eventcatalog/src/components/Checkbox.astro
similarity index 80%
rename from eventcatalog/src/components/Checkbox.astro
rename to packages/core/eventcatalog/src/components/Checkbox.astro
index fbcfa85f8..a69c469fd 100644
--- a/eventcatalog/src/components/Checkbox.astro
+++ b/packages/core/eventcatalog/src/components/Checkbox.astro
@@ -12,21 +12,24 @@ const { id, name, label, class: className, ...attrs } = Astro.props;
 
 <label for={id} class="relative block cursor-pointer select-none pl-5">
   <input id={id} name={name} type="checkbox" class="h-0 w-0 cursor-pointer appearance-none group" {...attrs} />
-  <span class="text-md text-gray-700">{label}</span>
+  <span class="text-md text-[rgb(var(--ec-page-text))]">{label}</span>
 </label>
 
 <style>
   input::before {
-    @apply absolute left-0 top-1/2 block h-4 w-4 -translate-y-1/2 rounded-[4px] border border-gray-300;
+    @apply absolute left-0 top-1/2 block h-4 w-4 -translate-y-1/2 rounded-[4px];
     content: '';
+    border: 1px solid rgb(var(--ec-page-border));
+    background-color: rgb(var(--ec-input-bg));
   }
 
   input:checked::before {
-    @apply bg-purple-600;
+    background-color: rgb(var(--ec-accent));
+    border-color: rgb(var(--ec-accent));
   }
 
   input:focus::before {
-    @apply outline outline-purple-300;
+    outline: 2px solid rgb(var(--ec-accent) / 0.3);
   }
 
   input:checked::after {
diff --git a/packages/core/eventcatalog/src/components/CopyAsMarkdown.tsx b/packages/core/eventcatalog/src/components/CopyAsMarkdown.tsx
new file mode 100644
index 000000000..c55d5f4df
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/CopyAsMarkdown.tsx
@@ -0,0 +1,484 @@
+import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
+import { Copy, FileText, Sparkles, ChevronDownIcon, ExternalLink, PenSquareIcon, RssIcon } from 'lucide-react';
+import React, { useState, isValidElement } from 'react';
+import type { Schema } from '@utils/collections/schemas';
+import { buildUrl, toMarkdownUrl } from '@utils/url-builder';
+
+// Type allows either a component type (like Lucide icon) or a pre-rendered element (like <img>)
+type IconInput = React.ElementType | React.ReactElement;
+
+// Helper component for menu items
+const MenuItemContent = ({
+  icon: iconProp,
+  title,
+  description,
+  external = false,
+}: {
+  icon: IconInput;
+  title: string;
+  description: string;
+  external?: boolean;
+}) => {
+  let iconElement: React.ReactNode;
+
+  if (isValidElement(iconProp)) {
+    // It's already a React element (e.g., <img>), render it directly
+    iconElement = iconProp;
+  } else {
+    // It must be an ElementType (component constructor like Lucide icon)
+    const IconComponent = iconProp as React.ElementType;
+    iconElement = <IconComponent className="w-4 h-4 text-[rgb(var(--ec-icon-color))]" />;
+  }
+
+  return (
+    <div className="flex items-center gap-2.5 rounded-lg px-2 py-1.5 text-sm">
+      <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg border border-[rgb(var(--ec-dropdown-border)/0.8)] bg-[rgb(var(--ec-page-bg))]">
+        {iconElement}
+      </div>
+      <div className="flex-1 min-w-0">
+        <div className="flex items-center gap-1.5 text-sm font-medium leading-5 text-[rgb(var(--ec-dropdown-text))]">
+          <span>{title}</span>
+          {external && <ExternalLink className="h-3.5 w-3.5 shrink-0 text-[rgb(var(--ec-icon-color))]" />}
+        </div>
+        <div className="text-xs leading-4 text-[rgb(var(--ec-content-text-muted))]">{description}</div>
+      </div>
+    </div>
+  );
+};
+
+export function CopyPageMenu({
+  schemas,
+  chatQuery,
+  chatEnabled = false,
+  editUrl,
+  markdownDownloadEnabled = false,
+  rssFeedEnabled = false,
+  preferChatAsDefault = false,
+  chatButtonText = 'Ask',
+  variant = 'menu',
+}: {
+  schemas: Schema[];
+  chatQuery?: string;
+  chatEnabled: boolean;
+  editUrl: string;
+  markdownDownloadEnabled: boolean;
+  rssFeedEnabled: boolean;
+  preferChatAsDefault?: boolean;
+  chatButtonText?: string;
+  variant?: 'menu' | 'toolbar';
+}) {
+  // Define available actions
+  const availableActions = {
+    copyMarkdown: markdownDownloadEnabled,
+    editPage: !!editUrl,
+    copySchemas: schemas.length > 0,
+    viewMarkdown: markdownDownloadEnabled,
+    chat: chatEnabled,
+    rssFeed: rssFeedEnabled,
+  };
+
+  // Check if any actions are available
+  const hasAnyActions = Object.values(availableActions).some(Boolean);
+
+  // If no actions are available, return null
+  if (!hasAnyActions) {
+    return null;
+  }
+
+  // get the url of the current page
+  const url = window.location.href;
+  const markdownUrl = toMarkdownUrl(url);
+
+  // Determine the default action based on what's available
+  const getDefaultAction = () => {
+    // If chat is preferred and available, make it the default
+    if (preferChatAsDefault && availableActions.chat) {
+      return {
+        type: 'chat',
+        text: chatButtonText,
+        icon: Sparkles,
+      };
+    }
+    if (availableActions.copyMarkdown) {
+      return {
+        type: 'copyMarkdown',
+        text: 'Copy page',
+        icon: Copy,
+      };
+    }
+    if (availableActions.editPage) {
+      return {
+        type: 'editPage',
+        text: 'Edit page',
+        icon: PenSquareIcon,
+      };
+    }
+    if (availableActions.copySchemas) {
+      return {
+        type: 'copySchemas',
+        text: 'Copy schema',
+        icon: FileText,
+      };
+    }
+    if (availableActions.viewMarkdown) {
+      return {
+        type: 'viewMarkdown',
+        text: 'View Markdown',
+        icon: FileText,
+      };
+    }
+    if (availableActions.chat) {
+      return {
+        type: 'chat',
+        text: chatButtonText,
+        icon: Sparkles,
+      };
+    }
+    if (availableActions.rssFeed) {
+      return {
+        type: 'rssFeed',
+        text: 'RSS Feed',
+        icon: RssIcon,
+      };
+    }
+    return null;
+  };
+
+  const defaultAction = getDefaultAction();
+  const [open, setOpen] = useState(false);
+  const [buttonText, setButtonText] = useState(defaultAction?.text || 'Action');
+  const [copyButtonText, setCopyButtonText] = useState('Copy page as markdown');
+
+  // Fetch the markdown from the url + .mdx
+  const copyMarkdownToClipboard = async () => {
+    console.log('Copying markdown to clipboard');
+    try {
+      setButtonText('Copied');
+      setCopyButtonText('Copied');
+      const response = await fetch(markdownUrl);
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+      const markdown = await response.text();
+      await navigator.clipboard.writeText(markdown);
+      setTimeout(() => setButtonText(defaultAction?.text || 'Action'), 3000); // Revert after 3 seconds
+      setTimeout(() => setCopyButtonText('Copy page as markdown'), 3000);
+    } catch (error) {
+      console.error('Failed to copy markdown:', error);
+      setButtonText('Copy failed'); // Provide feedback on failure
+      setCopyButtonText('Copy failed');
+      setTimeout(() => setButtonText(defaultAction?.text || 'Action'), 3000);
+      setTimeout(() => setCopyButtonText('Copy page as markdown'), 3000);
+    }
+  };
+
+  // Fetch the schema from the schemaURL and copy it to the clipboard
+  const copySchemaToClipboard = async (schema: Schema) => {
+    if (!schema.url) return; // Should not happen if button is hidden, but good practice
+
+    console.log('Copying schema to clipboard from:', schema.url);
+    try {
+      setButtonText('Copied Schema');
+      const response = await fetch(schema.url); // Use the provided schemaURL directly
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+      const schemaContent = await response.text(); // Or response.json() if it's always JSON
+      await navigator.clipboard.writeText(schemaContent);
+      setTimeout(() => setButtonText(defaultAction?.text || 'Action'), 3000); // Revert after 3 seconds
+    } catch (error) {
+      console.error('Failed to copy schema:', error);
+      setButtonText('Copy failed'); // Provide feedback on failure
+      setTimeout(() => setButtonText(defaultAction?.text || 'Action'), 3000);
+    }
+  };
+
+  // Handle the default action based on type
+  const handleDefaultAction = () => {
+    if (!defaultAction) return;
+
+    switch (defaultAction.type) {
+      case 'copyMarkdown':
+        copyMarkdownToClipboard();
+        break;
+      case 'editPage':
+        window.open(editUrl, '_blank');
+        break;
+      case 'copySchemas':
+        copySchemaToClipboard(schemas[0]);
+        break;
+      case 'viewMarkdown':
+        window.open(markdownUrl, '_blank');
+        break;
+      case 'chat':
+        // Dispatch custom event to open chat panel instead of navigating
+        window.dispatchEvent(new CustomEvent('eventcatalog:open-chat'));
+        break;
+    }
+  };
+
+  if (!defaultAction) {
+    return null;
+  }
+
+  const actionButtonClass =
+    'group inline-flex items-center gap-1.5 whitespace-nowrap text-xs font-medium text-[rgb(var(--ec-page-text-muted))] transition-colors duration-150 hover:text-[rgb(var(--ec-page-text))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:ring-offset-2 focus:ring-offset-[rgb(var(--ec-page-bg))] rounded-md';
+  const actionIconClass = 'h-3.5 w-3.5 shrink-0 text-[rgb(var(--ec-icon-color))] group-hover:text-[rgb(var(--ec-page-text))]';
+
+  const hasToolbarActions =
+    availableActions.chat ||
+    availableActions.copyMarkdown ||
+    availableActions.viewMarkdown ||
+    availableActions.copySchemas ||
+    availableActions.rssFeed ||
+    availableActions.editPage;
+
+  if (variant === 'toolbar') {
+    if (!hasToolbarActions) return null;
+
+    const moreActionsAvailable = availableActions.copySchemas || availableActions.rssFeed || availableActions.editPage;
+
+    return (
+      <div className="not-prose flex flex-wrap items-center gap-x-3 gap-y-1.5 text-xs text-[rgb(var(--ec-page-text-muted))]">
+        {availableActions.chat && (
+          <button
+            type="button"
+            onClick={() => window.dispatchEvent(new CustomEvent('eventcatalog:open-chat'))}
+            className={actionButtonClass}
+          >
+            <Sparkles className={actionIconClass} />
+            Ask a question
+          </button>
+        )}
+
+        {availableActions.chat && (availableActions.copyMarkdown || availableActions.viewMarkdown || moreActionsAvailable) && (
+          <span className="h-4 w-px bg-[rgb(var(--ec-page-border))]" aria-hidden="true" />
+        )}
+
+        {availableActions.copyMarkdown && (
+          <button type="button" onClick={copyMarkdownToClipboard} className={actionButtonClass}>
+            <Copy className={actionIconClass} />
+            {copyButtonText}
+          </button>
+        )}
+
+        {availableActions.copyMarkdown && (availableActions.viewMarkdown || moreActionsAvailable) && (
+          <span className="h-4 w-px bg-[rgb(var(--ec-page-border))]" aria-hidden="true" />
+        )}
+
+        {availableActions.viewMarkdown && (
+          <button type="button" onClick={() => window.open(markdownUrl, '_blank')} className={actionButtonClass}>
+            <FileText className={actionIconClass} />
+            View as Markdown
+          </button>
+        )}
+
+        {availableActions.viewMarkdown && moreActionsAvailable && (
+          <span className="h-4 w-px bg-[rgb(var(--ec-page-border))]" aria-hidden="true" />
+        )}
+
+        {moreActionsAvailable && (
+          <DropdownMenu.Root open={open} onOpenChange={setOpen}>
+            <DropdownMenu.Trigger asChild>
+              <button type="button" className={actionButtonClass}>
+                More actions
+                <ChevronDownIcon className={`h-3.5 w-3.5 transition-transform duration-200 ${open ? 'rotate-180' : ''}`} />
+              </button>
+            </DropdownMenu.Trigger>
+            <DropdownMenu.Content
+              className="z-50 w-72 max-w-[calc(100vw-1.5rem)] rounded-2xl border border-[rgb(var(--ec-dropdown-border)/0.8)] bg-[rgb(var(--ec-page-bg))] px-1.5 py-1.5 shadow-[0_24px_64px_rgb(0_0_0/0.35)]"
+              sideOffset={10}
+              align="start"
+            >
+              {availableActions.copySchemas &&
+                schemas.map((schema) => {
+                  const title =
+                    schema.format === 'asyncapi'
+                      ? 'Copy AsyncAPI specification'
+                      : schema.format === 'openapi'
+                        ? 'Copy OpenAPI specification'
+                        : 'Copy schema';
+                  const type =
+                    schema.format === 'asyncapi' || schema.format === 'openapi'
+                      ? 'specification'
+                      : `${schema.format.toUpperCase()} schema`;
+
+                  const Icon =
+                    schema.format === 'asyncapi' ? (
+                      <img src={buildUrl('/icons/asyncapi.svg', true)} className="w-4 h-4" />
+                    ) : schema.format === 'openapi' ? (
+                      <img src={buildUrl('/icons/openapi.svg', true)} className="w-4 h-4" />
+                    ) : (
+                      FileText
+                    );
+
+                  return (
+                    <DropdownMenu.Item
+                      key={schema.url}
+                      className="cursor-pointer rounded-2xl outline-hidden transition-colors duration-150 hover:bg-[rgb(var(--ec-dropdown-hover))] data-[highlighted]:bg-[rgb(var(--ec-dropdown-hover))]"
+                      onSelect={() => copySchemaToClipboard(schema)}
+                    >
+                      <MenuItemContent icon={Icon} title={title} description={`Copy ${type} to clipboard`} />
+                    </DropdownMenu.Item>
+                  );
+                })}
+
+              {availableActions.rssFeed && (
+                <DropdownMenu.Item
+                  className="cursor-pointer rounded-2xl outline-hidden transition-colors duration-150 hover:bg-[rgb(var(--ec-dropdown-hover))] data-[highlighted]:bg-[rgb(var(--ec-dropdown-hover))]"
+                  onSelect={() => window.open(buildUrl(`/rss/all/rss.xml`), '_blank')}
+                >
+                  <MenuItemContent icon={RssIcon} title="RSS Feed" description="View this page as RSS feed" external={true} />
+                </DropdownMenu.Item>
+              )}
+
+              {availableActions.editPage && (
+                <DropdownMenu.Item
+                  className="cursor-pointer rounded-2xl outline-hidden transition-colors duration-150 hover:bg-[rgb(var(--ec-dropdown-hover))] data-[highlighted]:bg-[rgb(var(--ec-dropdown-hover))]"
+                  onSelect={() => window.open(editUrl, '_blank')}
+                >
+                  <MenuItemContent
+                    icon={PenSquareIcon}
+                    title="Edit page"
+                    description="Edit the contents of this page"
+                    external={true}
+                  />
+                </DropdownMenu.Item>
+              )}
+            </DropdownMenu.Content>
+          </DropdownMenu.Root>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <DropdownMenu.Root open={open} onOpenChange={setOpen}>
+      {/* Container for the split button */}
+      <div className="inline-flex h-8 items-stretch overflow-hidden rounded-md border border-[rgb(var(--ec-dropdown-border)/0.75)] bg-[rgb(var(--ec-page-bg))]">
+        {/* Left Button: Default Action */}
+        <button
+          type="button"
+          onClick={handleDefaultAction}
+          className="inline-flex h-full items-center justify-center gap-2 whitespace-nowrap bg-transparent pl-4 pr-3 text-sm font-medium text-[rgb(var(--ec-dropdown-text))] transition-colors duration-150 hover:bg-[rgb(var(--ec-dropdown-hover)/0.75)] focus:z-10 focus:outline-hidden focus:ring-1 focus:ring-[rgb(var(--ec-accent))]"
+        >
+          <defaultAction.icon className="h-4 w-4" />
+          {buttonText}
+        </button>
+        {/* Right Button: Dropdown Trigger */}
+        <DropdownMenu.Trigger asChild>
+          <button
+            type="button"
+            className="inline-flex h-full w-8 items-center justify-center border-l border-[rgb(var(--ec-dropdown-border)/0.75)] bg-transparent text-sm font-medium text-[rgb(var(--ec-icon-color))] transition-colors duration-150 hover:bg-[rgb(var(--ec-dropdown-hover)/0.75)] focus:z-10 focus:outline-hidden focus:ring-1 focus:ring-[rgb(var(--ec-accent))]"
+            aria-label="More options"
+          >
+            <ChevronDownIcon className={`h-4 w-4 transition-transform duration-200 ${open ? 'rotate-180' : ''}`} />
+          </button>
+        </DropdownMenu.Trigger>
+      </div>
+
+      {/* Adjust styling for the content dropdown */}
+      <DropdownMenu.Content
+        className="z-50 w-72 max-w-[calc(100vw-1.5rem)] rounded-2xl border border-[rgb(var(--ec-dropdown-border)/0.8)] bg-[rgb(var(--ec-page-bg))] px-1.5 py-1.5 shadow-[0_24px_64px_rgb(0_0_0/0.35)]"
+        sideOffset={10}
+        align="end"
+      >
+        {availableActions.chat && (
+          <>
+            <DropdownMenu.Item
+              className="cursor-pointer rounded-2xl outline-hidden transition-colors duration-150 hover:bg-[rgb(var(--ec-dropdown-hover))] data-[highlighted]:bg-[rgb(var(--ec-dropdown-hover))]"
+              onSelect={() => window.dispatchEvent(new CustomEvent('eventcatalog:open-chat'))}
+            >
+              <MenuItemContent icon={Sparkles} title="EventCatalog Assistant" description="Ask questions about this page" />
+            </DropdownMenu.Item>
+            <DropdownMenu.Separator className="mx-3 my-3 h-px bg-[rgb(var(--ec-dropdown-border)/0.8)]" />
+          </>
+        )}
+
+        {availableActions.copyMarkdown && (
+          <DropdownMenu.Item
+            className="cursor-pointer rounded-2xl outline-hidden transition-colors duration-150 hover:bg-[rgb(var(--ec-dropdown-hover))] data-[highlighted]:bg-[rgb(var(--ec-dropdown-hover))]"
+            onSelect={() => copyMarkdownToClipboard()}
+          >
+            <MenuItemContent icon={Copy} title="Copy page" description="Copy page as Markdown for LLMs" />
+          </DropdownMenu.Item>
+        )}
+
+        {availableActions.copySchemas &&
+          schemas.map((schema) => {
+            const title =
+              schema.format === 'asyncapi'
+                ? 'Copy AsyncAPI specification'
+                : schema.format === 'openapi'
+                  ? 'Copy OpenAPI specification'
+                  : 'Copy schema';
+            const type =
+              schema.format === 'asyncapi' || schema.format === 'openapi'
+                ? 'specification'
+                : `${schema.format.toUpperCase()} schema`;
+
+            const Icon =
+              schema.format === 'asyncapi' ? (
+                <img src={buildUrl('/icons/asyncapi.svg', true)} className="w-4 h-4" />
+              ) : schema.format === 'openapi' ? (
+                <img src={buildUrl('/icons/openapi.svg', true)} className="w-4 h-4" />
+              ) : (
+                FileText
+              );
+
+            return (
+              <DropdownMenu.Item
+                key={schema.url}
+                className="cursor-pointer rounded-2xl outline-hidden transition-colors duration-150 hover:bg-[rgb(var(--ec-dropdown-hover))] data-[highlighted]:bg-[rgb(var(--ec-dropdown-hover))]"
+                onSelect={() => copySchemaToClipboard(schema)}
+              >
+                <MenuItemContent icon={Icon} title={title} description={`Copy ${type} to clipboard`} />
+              </DropdownMenu.Item>
+            );
+          })}
+
+        {availableActions.viewMarkdown && (
+          <DropdownMenu.Item
+            className="cursor-pointer rounded-2xl outline-hidden transition-colors duration-150 hover:bg-[rgb(var(--ec-dropdown-hover))] data-[highlighted]:bg-[rgb(var(--ec-dropdown-hover))]"
+            onSelect={() => window.open(markdownUrl, '_blank')}
+          >
+            <MenuItemContent
+              icon={FileText}
+              title="View as Markdown"
+              description="View this page as plain text"
+              external={true}
+            />
+          </DropdownMenu.Item>
+        )}
+
+        {availableActions.rssFeed && (
+          <DropdownMenu.Item
+            className="cursor-pointer rounded-2xl outline-hidden transition-colors duration-150 hover:bg-[rgb(var(--ec-dropdown-hover))] data-[highlighted]:bg-[rgb(var(--ec-dropdown-hover))]"
+            onSelect={() => window.open(buildUrl(`/rss/all/rss.xml`), '_blank')}
+          >
+            <MenuItemContent icon={RssIcon} title="RSS Feed" description="View this page as RSS feed" external={true} />
+          </DropdownMenu.Item>
+        )}
+
+        {availableActions.editPage && (
+          <>
+            <DropdownMenu.Separator className="mx-3 my-3 h-px bg-[rgb(var(--ec-dropdown-border)/0.8)]" />
+            <DropdownMenu.Item
+              className="cursor-pointer rounded-2xl outline-hidden transition-colors duration-150 hover:bg-[rgb(var(--ec-dropdown-hover))] data-[highlighted]:bg-[rgb(var(--ec-dropdown-hover))]"
+              onSelect={() => window.open(editUrl, '_blank')}
+            >
+              <MenuItemContent
+                icon={PenSquareIcon}
+                title="Edit page"
+                description="Edit the contents of this page"
+                external={true}
+              />
+            </DropdownMenu.Item>
+          </>
+        )}
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  );
+}
+
+export default CopyPageMenu;
diff --git a/packages/core/eventcatalog/src/components/EnvironmentDropdown.test.ts b/packages/core/eventcatalog/src/components/EnvironmentDropdown.test.ts
new file mode 100644
index 000000000..03c05ae94
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/EnvironmentDropdown.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { buildEnvironmentUrl, findCurrentEnvironment } from './EnvironmentDropdown';
+
+const environments = [
+  {
+    name: 'Development',
+    url: 'https://example.com/event-catalog/dev',
+    shortName: 'Dev',
+  },
+  {
+    name: 'UAT',
+    url: 'https://example.com/event-catalog/uat',
+    shortName: 'UAT',
+  },
+  {
+    name: 'Production',
+    url: 'https://example.com/event-catalog/prod',
+    shortName: 'Prod',
+  },
+];
+
+describe('EnvironmentDropdown', () => {
+  it('finds the current environment when environments share an origin but use different base paths', () => {
+    expect(findCurrentEnvironment(environments, 'https://example.com/event-catalog/uat/services/foo')?.name).toBe('UAT');
+  });
+
+  it('builds environment urls by replacing the current environment base path', () => {
+    expect(
+      buildEnvironmentUrl(
+        'https://example.com/event-catalog/prod',
+        'https://example.com/event-catalog/uat/services/foo',
+        'https://example.com/event-catalog/uat'
+      )
+    ).toBe('https://example.com/event-catalog/prod/services/foo');
+  });
+
+  it('preserves search params and hashes when switching environments', () => {
+    expect(
+      buildEnvironmentUrl(
+        'https://example.com/event-catalog/prod',
+        'https://example.com/event-catalog/uat/services/foo?tab=messages#latest',
+        'https://example.com/event-catalog/uat'
+      )
+    ).toBe('https://example.com/event-catalog/prod/services/foo?tab=messages#latest');
+  });
+
+  it('keeps existing origin based environment switching for root catalogs', () => {
+    expect(
+      buildEnvironmentUrl('https://prod.example.com', 'https://uat.example.com/services/foo', 'https://uat.example.com')
+    ).toBe('https://prod.example.com/services/foo');
+  });
+
+  it('switches from a root catalog to a subpath catalog', () => {
+    expect(buildEnvironmentUrl('https://example.com/prod', 'https://example.com/services/foo', 'https://example.com')).toBe(
+      'https://example.com/prod/services/foo'
+    );
+  });
+
+  it('preserves the current path when the current environment is unknown', () => {
+    expect(buildEnvironmentUrl('https://example.com/prod', 'http://localhost:3000/services/foo')).toBe(
+      'https://example.com/prod/services/foo'
+    );
+  });
+});
diff --git a/packages/core/eventcatalog/src/components/EnvironmentDropdown.tsx b/packages/core/eventcatalog/src/components/EnvironmentDropdown.tsx
new file mode 100644
index 000000000..f3ec809a4
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/EnvironmentDropdown.tsx
@@ -0,0 +1,187 @@
+import React, { useState, useEffect, useRef } from 'react';
+
+interface Environment {
+  name: string;
+  url: string;
+  description?: string;
+  shortName?: string;
+}
+
+interface EnvironmentDropdownProps {
+  environments: Environment[];
+}
+
+const stripTrailingSlash = (pathname: string) => pathname.replace(/\/$/, '') || '/';
+
+const startsWithPath = (pathname: string, basePathname: string) =>
+  basePathname === '/' || pathname === basePathname || pathname.startsWith(`${basePathname}/`);
+
+export const findCurrentEnvironment = (environments: Environment[], currentHref: string) => {
+  const currentUrl = new URL(currentHref);
+
+  return (
+    environments
+      .filter((env) => {
+        const envUrl = new URL(env.url, currentUrl.href);
+        const envPathname = stripTrailingSlash(envUrl.pathname);
+
+        return envUrl.origin === currentUrl.origin && startsWithPath(currentUrl.pathname, envPathname);
+      })
+      .sort(
+        (a, b) =>
+          stripTrailingSlash(new URL(b.url, currentUrl.href).pathname).length -
+          stripTrailingSlash(new URL(a.url, currentUrl.href).pathname).length
+      )[0] || null
+  );
+};
+
+export const buildEnvironmentUrl = (environmentUrl: string, currentHref: string, currentEnvironmentUrl?: string) => {
+  const currentUrl = new URL(currentHref);
+  const targetUrl = new URL(environmentUrl, currentUrl.href);
+  const targetBasePathname = stripTrailingSlash(targetUrl.pathname);
+  const currentBasePathname = currentEnvironmentUrl
+    ? stripTrailingSlash(new URL(currentEnvironmentUrl, currentUrl.href).pathname)
+    : undefined;
+  const pathWithinEnvironment =
+    currentBasePathname && currentBasePathname !== '/' && startsWithPath(currentUrl.pathname, currentBasePathname)
+      ? currentUrl.pathname.slice(currentBasePathname.length)
+      : currentUrl.pathname;
+
+  targetUrl.pathname = `${targetBasePathname}${pathWithinEnvironment}`.replace(/\/+/g, '/');
+  targetUrl.search = currentUrl.search;
+  targetUrl.hash = currentUrl.hash;
+
+  return targetUrl.toString();
+};
+
+export const EnvironmentDropdown: React.FC<EnvironmentDropdownProps> = ({ environments }) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const [currentEnvironment, setCurrentEnvironment] = useState<Environment | null>(null);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    setCurrentEnvironment(findCurrentEnvironment(environments, window.location.href));
+  }, [environments]);
+
+  useEffect(() => {
+    // Handle click outside
+    const handleClickOutside = (event: MouseEvent) => {
+      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+        setIsOpen(false);
+      }
+    };
+
+    // Handle escape key
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        setIsOpen(false);
+      }
+    };
+
+    if (isOpen) {
+      document.addEventListener('click', handleClickOutside);
+      document.addEventListener('keydown', handleEscape);
+    }
+
+    return () => {
+      document.removeEventListener('click', handleClickOutside);
+      document.removeEventListener('keydown', handleEscape);
+    };
+  }, [isOpen]);
+
+  const toggleDropdown = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    setIsOpen(!isOpen);
+  };
+
+  return (
+    <div className="relative" ref={dropdownRef}>
+      <button
+        type="button"
+        onClick={toggleDropdown}
+        className="group inline-flex items-center gap-2.5 rounded-xl border border-[rgb(var(--ec-header-border))] bg-[rgb(var(--ec-header-bg))] px-3.5 py-2 text-[13px] font-medium text-[rgb(var(--ec-header-text)/0.82)] shadow-xs transition-colors hover:border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-dropdown-hover)/0.35)] hover:text-[rgb(var(--ec-header-text))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
+        aria-expanded={isOpen}
+        aria-haspopup="true"
+      >
+        <span className="h-2.5 w-2.5 rounded-full bg-emerald-400 shadow-[0_0_0_3px_rgba(16,185,129,0.14)]" aria-hidden="true" />
+        <span className="truncate">
+          <span className="font-semibold text-[rgb(var(--ec-header-text))]">Environments</span>
+          {currentEnvironment && (
+            <span className="font-medium text-[rgb(var(--ec-header-text)/0.72)]">
+              {' '}
+              ({currentEnvironment.shortName || currentEnvironment.name})
+            </span>
+          )}
+        </span>
+        <svg
+          className={`ml-0.5 h-4 w-4 flex-shrink-0 transition-transform ${isOpen ? 'rotate-180' : ''}`}
+          fill="none"
+          stroke="currentColor"
+          viewBox="0 0 24 24"
+          xmlns="http://www.w3.org/2000/svg"
+        >
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M19 9l-7 7-7-7" />
+        </svg>
+      </button>
+      <div
+        className={`${isOpen ? '' : 'hidden'} absolute right-0 mt-2 w-72 overflow-hidden rounded-2xl border border-[rgb(var(--ec-dropdown-border))] bg-[rgb(var(--ec-dropdown-bg))] p-1.5 shadow-2xl z-[100]`}
+      >
+        {environments.map((env) => {
+          const isCurrentEnv = currentEnvironment?.name === env.name;
+
+          return (
+            <a
+              key={env.name}
+              href={env.url}
+              onClick={(e) => {
+                e.preventDefault();
+                window.location.href = buildEnvironmentUrl(env.url, window.location.href, currentEnvironment?.url);
+              }}
+              className={`block rounded-xl px-3 py-3 transition-colors ${
+                isCurrentEnv
+                  ? 'bg-[rgb(var(--ec-accent)/0.12)] text-[rgb(var(--ec-dropdown-text))]'
+                  : 'text-[rgb(var(--ec-dropdown-text))] hover:bg-[rgb(var(--ec-dropdown-hover))]'
+              }`}
+            >
+              <div className="flex items-start justify-between gap-3">
+                <div className="min-w-0">
+                  <div className="flex items-center gap-2">
+                    <span
+                      className={`mt-0.5 h-2 w-2 rounded-full flex-shrink-0 ${isCurrentEnv ? 'bg-emerald-400' : 'bg-[rgb(var(--ec-icon-color))]'}`}
+                      aria-hidden="true"
+                    />
+                    <div
+                      className={`truncate text-[13px] font-semibold ${isCurrentEnv ? 'text-[rgb(var(--ec-accent-text))]' : ''}`}
+                    >
+                      {env.name}
+                    </div>
+                  </div>
+                  {env.description && (
+                    <div
+                      className={`mt-1 pl-4 text-[12px] leading-5 ${isCurrentEnv ? 'text-[rgb(var(--ec-accent-text)/0.78)]' : 'text-[rgb(var(--ec-icon-color))]'}`}
+                    >
+                      {env.description}
+                    </div>
+                  )}
+                </div>
+                {isCurrentEnv && (
+                  <svg
+                    className="mt-0.5 h-4 w-4 flex-shrink-0 text-[rgb(var(--ec-accent-text))]"
+                    fill="currentColor"
+                    viewBox="0 0 20 20"
+                  >
+                    <path
+                      fillRule="evenodd"
+                      d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z"
+                      clipRule="evenodd"
+                    />
+                  </svg>
+                )}
+              </div>
+            </a>
+          );
+        })}
+      </div>
+    </div>
+  );
+};
diff --git a/packages/core/eventcatalog/src/components/FavoriteButton.tsx b/packages/core/eventcatalog/src/components/FavoriteButton.tsx
new file mode 100644
index 000000000..b65453bb1
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/FavoriteButton.tsx
@@ -0,0 +1,54 @@
+import React, { useState, useEffect } from 'react';
+import { StarIcon as StarIconOutline } from '@heroicons/react/24/outline';
+import { StarIcon as StarIconSolid } from '@heroicons/react/24/solid';
+import { useStore } from '@nanostores/react';
+import { favoritesStore, toggleFavorite, type FavoriteItem } from '../stores/favorites-store';
+
+interface FavoriteButtonProps {
+  nodeKey: string;
+  title: string;
+  badge?: string;
+  href?: string;
+  size?: 'sm' | 'md' | 'lg';
+}
+
+export default function FavoriteButton({ nodeKey, title, badge, href, size = 'md' }: FavoriteButtonProps) {
+  const favorites = useStore(favoritesStore);
+  const [isClient, setIsClient] = useState(false);
+
+  useEffect(() => {
+    setIsClient(true);
+  }, []);
+
+  const isFavorite = isClient && favorites.some((fav) => fav.nodeKey === nodeKey);
+
+  const sizeClasses = {
+    sm: 'h-4 w-4',
+    md: 'h-6 w-6',
+    lg: 'h-8 w-8',
+  };
+
+  const handleToggleFavorite = () => {
+    const favoriteItem: FavoriteItem = {
+      nodeKey,
+      path: [],
+      title,
+      badge,
+      href,
+    };
+    toggleFavorite(favoriteItem);
+  };
+
+  return (
+    <button
+      onClick={handleToggleFavorite}
+      className={`p-2 rounded-md transition-colors ${
+        isFavorite ? 'text-amber-400 hover:text-amber-500' : 'text-[rgb(var(--ec-icon-color))] hover:text-amber-400'
+      }`}
+      aria-label={isFavorite ? 'Remove from favorites' : 'Add to favorites'}
+      title={isFavorite ? 'Remove from favorites' : 'Add to favorites'}
+    >
+      {isFavorite ? <StarIconSolid className={sizeClasses[size]} /> : <StarIconOutline className={sizeClasses[size]} />}
+    </button>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/FieldsExplorer/FieldFilters.tsx b/packages/core/eventcatalog/src/components/FieldsExplorer/FieldFilters.tsx
new file mode 100644
index 000000000..5e0bc6027
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/FieldsExplorer/FieldFilters.tsx
@@ -0,0 +1,175 @@
+import { FilterDropdown, CheckboxItem } from '../Tables/Discover/FilterComponents';
+
+export interface FieldFiltersProps {
+  searchQuery: string;
+  onSearchChange: (value: string) => void;
+  selectedFormats: string[];
+  onFormatsChange: (values: string[]) => void;
+  selectedMessageTypes: string[];
+  onMessageTypesChange: (values: string[]) => void;
+  sharedOnly: boolean;
+  onSharedOnlyChange: (value: boolean) => void;
+  conflictingOnly: boolean;
+  onConflictingOnlyChange: (value: boolean) => void;
+  facets: {
+    formats: { value: string; count: number }[];
+    messageTypes: { value: string; count: number }[];
+  } | null;
+  isScaleEnabled?: boolean;
+}
+
+export default function FieldFilters({
+  selectedFormats,
+  onFormatsChange,
+  selectedMessageTypes,
+  onMessageTypesChange,
+  sharedOnly,
+  onSharedOnlyChange,
+  conflictingOnly,
+  onConflictingOnlyChange,
+  facets,
+  isScaleEnabled = false,
+}: FieldFiltersProps) {
+  const toggleFormat = (value: string) => {
+    if (selectedFormats.includes(value)) {
+      onFormatsChange(selectedFormats.filter((f) => f !== value));
+    } else {
+      onFormatsChange([...selectedFormats, value]);
+    }
+  };
+
+  const toggleMessageType = (value: string) => {
+    if (selectedMessageTypes.includes(value)) {
+      onMessageTypesChange(selectedMessageTypes.filter((t) => t !== value));
+    } else {
+      onMessageTypesChange([...selectedMessageTypes, value]);
+    }
+  };
+
+  const activeFilterCount =
+    selectedFormats.length + selectedMessageTypes.length + (sharedOnly ? 1 : 0) + (conflictingOnly ? 1 : 0);
+
+  const clearAllFilters = () => {
+    onFormatsChange([]);
+    onMessageTypesChange([]);
+    onSharedOnlyChange(false);
+    onConflictingOnlyChange(false);
+  };
+
+  return (
+    <div className="space-y-6">
+      {/* Schema Format Filter */}
+      {facets && facets.formats.length > 0 && (
+        <div>
+          <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Schema format</label>
+          <FilterDropdown
+            label="Select formats..."
+            selectedItems={selectedFormats}
+            onClear={() => onFormatsChange([])}
+            onRemoveItem={(item) => toggleFormat(item)}
+          >
+            {facets.formats.map((format) => (
+              <CheckboxItem
+                key={format.value}
+                label={format.value.charAt(0).toUpperCase() + format.value.slice(1)}
+                checked={selectedFormats.includes(format.value)}
+                onChange={() => toggleFormat(format.value)}
+                count={format.count}
+              />
+            ))}
+          </FilterDropdown>
+        </div>
+      )}
+
+      {/* Message Type Filter */}
+      {facets && facets.messageTypes.length > 0 && (
+        <div>
+          <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Message type</label>
+          <FilterDropdown
+            label="Select message types..."
+            selectedItems={selectedMessageTypes}
+            onClear={() => onMessageTypesChange([])}
+            onRemoveItem={(item) => toggleMessageType(item)}
+          >
+            {facets.messageTypes.map((msgType) => (
+              <CheckboxItem
+                key={msgType.value}
+                label={msgType.value.charAt(0).toUpperCase() + msgType.value.slice(1)}
+                checked={selectedMessageTypes.includes(msgType.value)}
+                onChange={() => toggleMessageType(msgType.value)}
+                count={msgType.count}
+              />
+            ))}
+          </FilterDropdown>
+        </div>
+      )}
+
+      {/* Shared Fields Only Toggle */}
+      <div>
+        <label className="flex items-center gap-2 cursor-pointer group">
+          <div
+            className={`w-4 h-4 flex-shrink-0 rounded border flex items-center justify-center transition-colors ${
+              sharedOnly
+                ? 'bg-[rgb(var(--ec-accent))] border-[rgb(var(--ec-accent))]'
+                : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-input-bg))] group-hover:border-[rgb(var(--ec-icon-color))]'
+            }`}
+            onClick={() => onSharedOnlyChange(!sharedOnly)}
+          >
+            {sharedOnly && (
+              <svg className="w-3 h-3 text-white" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="3">
+                <path d="M5 13l4 4L19 7" strokeLinecap="round" strokeLinejoin="round" />
+              </svg>
+            )}
+          </div>
+          <span className="text-sm text-[rgb(var(--ec-page-text))]" onClick={() => onSharedOnlyChange(!sharedOnly)}>
+            Shared fields only
+          </span>
+        </label>
+        <p className="text-[11px] text-[rgb(var(--ec-page-text-muted))] mt-1 ml-6">
+          Show only fields that appear in multiple messages
+        </p>
+      </div>
+
+      {/* Conflicting Fields Only Toggle */}
+      {isScaleEnabled && (
+        <div>
+          <label className="flex items-center gap-2 cursor-pointer group">
+            <div
+              className={`w-4 h-4 flex-shrink-0 rounded border flex items-center justify-center transition-colors ${
+                conflictingOnly
+                  ? 'bg-amber-500 border-amber-500'
+                  : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-input-bg))] group-hover:border-[rgb(var(--ec-icon-color))]'
+              }`}
+              onClick={() => onConflictingOnlyChange(!conflictingOnly)}
+            >
+              {conflictingOnly && (
+                <svg className="w-3 h-3 text-white" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="3">
+                  <path d="M5 13l4 4L19 7" strokeLinecap="round" strokeLinejoin="round" />
+                </svg>
+              )}
+            </div>
+            <span className="text-sm text-[rgb(var(--ec-page-text))]" onClick={() => onConflictingOnlyChange(!conflictingOnly)}>
+              Conflicting fields
+            </span>
+          </label>
+          <p className="text-[11px] text-[rgb(var(--ec-page-text-muted))] mt-1 ml-6">
+            Show only fields with inconsistent types across messages
+          </p>
+        </div>
+      )}
+
+      {/* Results & Clear */}
+      {activeFilterCount > 0 && (
+        <div className="flex items-center justify-between pt-3 mt-2 border-t border-[rgb(var(--ec-page-border))]">
+          <span className="text-xs text-[rgb(var(--ec-page-text-muted))]">
+            <span className="font-semibold text-[rgb(var(--ec-page-text))]">{activeFilterCount}</span> active{' '}
+            {activeFilterCount === 1 ? 'filter' : 'filters'}
+          </span>
+          <button onClick={clearAllFilters} className="text-xs font-medium text-[rgb(var(--ec-accent))] hover:underline">
+            Clear all
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/FieldsExplorer/FieldNodeGraph.tsx b/packages/core/eventcatalog/src/components/FieldsExplorer/FieldNodeGraph.tsx
new file mode 100644
index 000000000..3c0ccbf2e
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/FieldsExplorer/FieldNodeGraph.tsx
@@ -0,0 +1,524 @@
+import React, { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  ReactFlow,
+  ReactFlowProvider,
+  Background,
+  Controls,
+  useNodesState,
+  useEdgesState,
+  useReactFlow,
+  ConnectionLineType,
+  type Node,
+  type Edge,
+} from '@xyflow/react';
+import {
+  Event as EventNodeComponent,
+  Command as CommandNodeComponent,
+  Query as QueryNodeComponent,
+  Field as FieldNodeComponent,
+  nodeComponents,
+} from '@eventcatalog/visualiser';
+import { X, ChevronDown, ChevronRight, Search, AlertTriangle } from 'lucide-react';
+import { BoltIcon, ChatBubbleLeftIcon, MagnifyingGlassIcon, ServerIcon } from '@heroicons/react/24/solid';
+import { getNodesAndEdges, type FieldOccurrence } from '@utils/node-graphs/field-node-graph';
+import * as ContextMenu from '@radix-ui/react-context-menu';
+import '@xyflow/react/dist/style.css';
+
+interface FieldNodeGraphProps {
+  fieldPath: string;
+  fieldType: string;
+  fieldDescription?: string;
+  fieldRequired?: boolean;
+  fieldConflicts?: { type: string; count: number }[];
+  occurrences: FieldOccurrence[];
+  onClose: () => void;
+}
+
+interface ContextMenuItem {
+  label: string;
+  href: string;
+  external?: boolean;
+  download?: string;
+  separator?: boolean;
+}
+
+function wrapWithContextMenu(Component: React.ComponentType<any>) {
+  const Wrapped = memo((props: any) => {
+    const items: ContextMenuItem[] | undefined = props.data?.contextMenu;
+    if (!items?.length) return <Component {...props} />;
+    return (
+      <ContextMenu.Root>
+        <ContextMenu.Trigger asChild>
+          <div>
+            <Component {...props} />
+          </div>
+        </ContextMenu.Trigger>
+        <ContextMenu.Portal>
+          <ContextMenu.Content
+            className="min-w-[220px] bg-[rgb(var(--ec-card-bg,255_255_255))] rounded-md p-1 shadow-md border border-[rgb(var(--ec-page-border))] z-50"
+            onClick={(e) => e.stopPropagation()}
+          >
+            {items.map((item, index) => (
+              <div key={index}>
+                {item.separator && index > 0 && <ContextMenu.Separator className="h-[1px] bg-[rgb(var(--ec-page-border))] m-1" />}
+                <ContextMenu.Item
+                  asChild
+                  className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-[rgb(var(--ec-content-hover))] rounded-sm flex items-center text-[rgb(var(--ec-page-text))]"
+                >
+                  <a
+                    href={item.href}
+                    {...(item.download ? { download: item.download } : {})}
+                    {...(item.external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+                  >
+                    {item.label}
+                  </a>
+                </ContextMenu.Item>
+              </div>
+            ))}
+          </ContextMenu.Content>
+        </ContextMenu.Portal>
+      </ContextMenu.Root>
+    );
+  });
+  Wrapped.displayName = `WithContextMenu(${Component.displayName || Component.name || 'Component'})`;
+  return Wrapped;
+}
+
+// React 19 vs React 18 ReactNode type drift between @eventcatalog/visualiser
+// and the catalog means these MemoExoticComponents don't match ComponentType<any>
+// unless we widen once here.
+const nodeTypes = {
+  service: wrapWithContextMenu(nodeComponents.service as unknown as React.ComponentType<any>),
+  event: wrapWithContextMenu(EventNodeComponent as unknown as React.ComponentType<any>),
+  command: wrapWithContextMenu(CommandNodeComponent as unknown as React.ComponentType<any>),
+  query: wrapWithContextMenu(QueryNodeComponent as unknown as React.ComponentType<any>),
+  field: FieldNodeComponent as unknown as React.ComponentType<any>,
+} as unknown as import('@xyflow/react').NodeTypes;
+
+const getIconForMessageType = (type: string) => {
+  switch (type) {
+    case 'event':
+      return { Icon: BoltIcon, bg: 'bg-orange-500' };
+    case 'command':
+      return { Icon: ChatBubbleLeftIcon, bg: 'bg-blue-500' };
+    case 'query':
+      return { Icon: MagnifyingGlassIcon, bg: 'bg-green-500' };
+    default:
+      return { Icon: ChatBubbleLeftIcon, bg: 'bg-gray-500' };
+  }
+};
+
+const COLLAPSED_LIMIT = 5;
+
+interface ResourceItem {
+  key: string;
+  label: string;
+  version: string;
+  Icon: React.ComponentType<{ className?: string }>;
+  bg: string;
+  onClick: () => void;
+}
+
+function CollapsibleResourceList({
+  title,
+  count,
+  items,
+  defaultExpanded = true,
+}: {
+  title: string;
+  count: number;
+  items: ResourceItem[];
+  defaultExpanded?: boolean;
+}) {
+  const [expanded, setExpanded] = useState(defaultExpanded);
+  const [showAll, setShowAll] = useState(false);
+  const [search, setSearch] = useState('');
+
+  const filtered = search ? items.filter((item) => item.label.toLowerCase().includes(search.toLowerCase())) : items;
+  const displayed = showAll ? filtered : filtered.slice(0, COLLAPSED_LIMIT);
+  const hasMore = filtered.length > COLLAPSED_LIMIT;
+
+  return (
+    <div>
+      <button className="flex items-center justify-between w-full mb-2 group" onClick={() => setExpanded(!expanded)}>
+        <h4 className="text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider flex items-center gap-1">
+          {expanded ? <ChevronDown className="w-3 h-3" /> : <ChevronRight className="w-3 h-3" />}
+          {title} ({count})
+        </h4>
+      </button>
+      {expanded && (
+        <div className="space-y-1.5">
+          {items.length > COLLAPSED_LIMIT && (
+            <div className="relative mb-1">
+              <Search className="absolute left-2 top-1/2 -translate-y-1/2 w-3 h-3 text-[rgb(var(--ec-icon-color))]" />
+              <input
+                type="text"
+                placeholder={`Filter ${title.toLowerCase()}...`}
+                value={search}
+                onChange={(e) => {
+                  setSearch(e.target.value);
+                  setShowAll(true);
+                }}
+                className="w-full pl-7 pr-2 py-1 text-[11px] rounded border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-input-bg,var(--ec-page-bg)))] text-[rgb(var(--ec-page-text))] placeholder:text-[rgb(var(--ec-page-text-muted))] focus:outline-none focus:border-[rgb(var(--ec-accent))]"
+                onClick={(e) => e.stopPropagation()}
+              />
+            </div>
+          )}
+          {displayed.map((item) => (
+            <button
+              key={item.key}
+              className="flex items-center gap-2 w-full rounded-lg border border-[rgb(var(--ec-page-border)/0.5)] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] hover:border-[rgb(var(--ec-accent))] transition-colors px-2.5 py-2 text-left"
+              onClick={(e) => {
+                e.stopPropagation();
+                item.onClick();
+              }}
+            >
+              <span className={`flex items-center justify-center w-5 h-5 ${item.bg} rounded flex-shrink-0`}>
+                <item.Icon className="h-2.5 w-2.5 text-white" />
+              </span>
+              <div className="min-w-0">
+                <div className="text-xs font-medium text-[rgb(var(--ec-page-text))] truncate">{item.label}</div>
+                <div className="text-[10px] text-[rgb(var(--ec-page-text-muted))]">v{item.version}</div>
+              </div>
+            </button>
+          ))}
+          {hasMore && !search && (
+            <button
+              className="text-[11px] text-[rgb(var(--ec-accent))] hover:underline w-full text-left pl-1"
+              onClick={(e) => {
+                e.stopPropagation();
+                setShowAll(!showAll);
+              }}
+            >
+              {showAll ? 'Show less' : `Show all ${filtered.length}`}
+            </button>
+          )}
+          {search && filtered.length === 0 && (
+            <div className="text-[11px] text-[rgb(var(--ec-page-text-muted))] pl-1">No matches</div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function FieldNodeGraphInner({
+  fieldPath,
+  fieldType,
+  fieldDescription,
+  fieldRequired,
+  fieldConflicts,
+  occurrences,
+  onClose,
+}: FieldNodeGraphProps) {
+  const { nodes: initialNodes, edges: initialEdges } = useMemo(
+    () => getNodesAndEdges({ fieldPath, fieldType, occurrences }),
+    [fieldPath, fieldType, occurrences]
+  );
+
+  const [nodes, , onNodesChange] = useNodesState(initialNodes);
+  const [edges, , onEdgesChange] = useEdgesState(initialEdges);
+  const edgesRef = useRef(initialEdges);
+  edgesRef.current = edges;
+
+  const { fitView } = useReactFlow();
+  const wrapperRef = useRef<HTMLDivElement>(null);
+
+  // Load visualiser styles (animations, hover effects, theme variables)
+  useEffect(() => {
+    import('@eventcatalog/visualiser/styles-core.css');
+  }, []);
+
+  useEffect(() => {
+    const timer = setTimeout(() => fitView({ padding: 0.2 }), 50);
+    return () => clearTimeout(timer);
+  }, [fitView]);
+
+  // Unique messages, producers, consumers for the details panel
+  const uniqueMessages = useMemo(() => {
+    const seen = new Set<string>();
+    return occurrences.filter((occ) => {
+      const key = `${occ.messageId}-${occ.messageVersion}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }, [occurrences]);
+
+  const uniqueProducers = useMemo(() => {
+    const seen = new Set<string>();
+    const result: { id: string; version: string; name?: string }[] = [];
+    for (const occ of occurrences) {
+      for (const p of occ.producers) {
+        const key = `${p.id}-${p.version}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          result.push(p);
+        }
+      }
+    }
+    return result;
+  }, [occurrences]);
+
+  const uniqueConsumers = useMemo(() => {
+    const seen = new Set<string>();
+    const result: { id: string; version: string; name?: string }[] = [];
+    for (const occ of occurrences) {
+      for (const c of occ.consumers) {
+        const key = `${c.id}-${c.version}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          result.push(c);
+        }
+      }
+    }
+    return result;
+  }, [occurrences]);
+
+  // ── Hover highlighting (matches main NodeGraph behaviour) ──
+
+  const hoveredEdgeNodesRef = useRef<Element[]>([]);
+  const hoveredNodeEdgesRef = useRef<Element[]>([]);
+  const hoveredNodePeersRef = useRef<Element[]>([]);
+
+  const handleEdgeMouseEnter = useCallback((_: React.MouseEvent, edge: Edge) => {
+    const wrapper = wrapperRef.current;
+    if (!wrapper) return;
+    const nodeEls = wrapper.querySelectorAll(`[data-id="${edge.source}"], [data-id="${edge.target}"]`);
+    nodeEls.forEach((el) => el.classList.add('ec-edge-hover-node'));
+    hoveredEdgeNodesRef.current = Array.from(nodeEls);
+  }, []);
+
+  const handleEdgeMouseLeave = useCallback(() => {
+    hoveredEdgeNodesRef.current.forEach((el) => el.classList.remove('ec-edge-hover-node'));
+    hoveredEdgeNodesRef.current = [];
+  }, []);
+
+  const handleNodeMouseEnter = useCallback((_: React.MouseEvent, node: Node) => {
+    const wrapper = wrapperRef.current;
+    if (!wrapper) return;
+
+    const peerIds = new Set<string>();
+    const edgeEls: Element[] = [];
+
+    for (const edge of edgesRef.current) {
+      if (edge.source !== node.id && edge.target !== node.id) continue;
+      const el = wrapper.querySelector(`.react-flow__edge[data-id="${edge.id}"]`);
+      if (el) {
+        el.classList.add('ec-node-hover-edge');
+        edgeEls.push(el);
+      }
+      if (edge.source !== node.id) peerIds.add(edge.source);
+      if (edge.target !== node.id) peerIds.add(edge.target);
+    }
+    hoveredNodeEdgesRef.current = edgeEls;
+
+    peerIds.add(node.id);
+    const selector = Array.from(peerIds)
+      .map((id) => `[data-id="${id}"]`)
+      .join(', ');
+    if (selector) {
+      const peerEls = wrapper.querySelectorAll(selector);
+      peerEls.forEach((el) => el.classList.add('ec-edge-hover-node'));
+      hoveredNodePeersRef.current = Array.from(peerEls);
+    }
+  }, []);
+
+  const handleNodeMouseLeave = useCallback(() => {
+    hoveredNodeEdgesRef.current.forEach((el) => el.classList.remove('ec-node-hover-edge'));
+    hoveredNodeEdgesRef.current = [];
+    hoveredNodePeersRef.current.forEach((el) => el.classList.remove('ec-edge-hover-node'));
+    hoveredNodePeersRef.current = [];
+  }, []);
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50" onClick={onClose}>
+      <div
+        className="w-[90vw] h-[80vh] max-w-[1400px] rounded-xl border shadow-2xl flex flex-col overflow-hidden"
+        style={{
+          backgroundColor: 'rgb(var(--ec-page-bg))',
+          borderColor: 'rgb(var(--ec-page-border))',
+        }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        {/* Header */}
+        <div
+          className="flex items-center justify-between px-5 py-3 border-b flex-shrink-0"
+          style={{ borderColor: 'rgb(var(--ec-page-border))' }}
+        >
+          <div className="flex items-center gap-2">
+            <h3 className="text-sm font-semibold" style={{ color: 'rgb(var(--ec-page-text))' }}>
+              Field Traceability
+            </h3>
+            <code
+              className="px-2 py-0.5 rounded text-xs font-mono"
+              style={{
+                backgroundColor: 'rgb(var(--ec-accent) / 0.1)',
+                color: 'rgb(var(--ec-accent))',
+              }}
+            >
+              {fieldPath}
+            </code>
+          </div>
+          <button
+            onClick={onClose}
+            className="p-1.5 rounded-lg transition-colors hover:bg-[rgb(var(--ec-content-hover))] flex-shrink-0"
+            style={{ color: 'rgb(var(--ec-icon-color))' }}
+            title="Close"
+          >
+            <X className="w-4 h-4" />
+          </button>
+        </div>
+
+        {/* Body: Graph + Details panel */}
+        <div className="flex-1 min-h-0 flex">
+          {/* Node Graph */}
+          <div className="flex-1 min-w-0 eventcatalog-visualizer" ref={wrapperRef}>
+            <ReactFlow
+              nodes={nodes}
+              edges={edges}
+              onNodesChange={onNodesChange}
+              onEdgesChange={onEdgesChange}
+              nodeTypes={nodeTypes}
+              onEdgeMouseEnter={handleEdgeMouseEnter}
+              onEdgeMouseLeave={handleEdgeMouseLeave}
+              onNodeMouseEnter={handleNodeMouseEnter}
+              onNodeMouseLeave={handleNodeMouseLeave}
+              defaultEdgeOptions={{ type: 'smoothstep' }}
+              connectionLineType={ConnectionLineType.SmoothStep}
+              fitView
+              proOptions={{ hideAttribution: true }}
+              nodesDraggable={true}
+              nodesConnectable={false}
+              elementsSelectable={false}
+              minZoom={0.07}
+              maxZoom={1.5}
+            >
+              <Background color="var(--ec-bg-dots)" gap={16} />
+              <Controls position="bottom-left" />
+            </ReactFlow>
+          </div>
+
+          {/* Right details panel */}
+          <div className="w-[280px] flex-shrink-0 border-l overflow-y-auto" style={{ borderColor: 'rgb(var(--ec-page-border))' }}>
+            <div className="p-4 space-y-4">
+              {/* Field info */}
+              <div>
+                <h4 className="text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider mb-2">
+                  Field
+                </h4>
+                <div className="space-y-1.5">
+                  <div className="text-sm font-mono font-semibold text-[rgb(var(--ec-page-text))]">{fieldPath}</div>
+                  <div className="text-xs text-[rgb(var(--ec-page-text-muted))]">{fieldType}</div>
+                  {fieldRequired && (
+                    <span className="inline-flex items-center px-1.5 py-0.5 rounded text-[10px] font-semibold bg-red-500/10 text-red-500 border border-red-500/20">
+                      Required
+                    </span>
+                  )}
+                  {fieldDescription && (
+                    <p className="text-xs text-[rgb(var(--ec-page-text-muted))] leading-relaxed mt-1">{fieldDescription}</p>
+                  )}
+                </div>
+              </div>
+
+              {/* Conflicts */}
+              {fieldConflicts && fieldConflicts.length > 1 && (
+                <div>
+                  <h4 className="text-[11px] font-medium text-amber-500 uppercase tracking-wider mb-2 flex items-center gap-1">
+                    <AlertTriangle className="w-3 h-3" />
+                    Type Conflict
+                  </h4>
+                  <div className="rounded-lg border border-amber-500/20 bg-amber-500/5 p-2.5">
+                    <p className="text-xs text-amber-600 mb-2">
+                      This field has inconsistent types across messages (
+                      {fieldConflicts.map((c) => `${c.type} in ${c.count}`).join(', ')})
+                    </p>
+                    <div className="space-y-1">
+                      {fieldConflicts.map((c) => (
+                        <div key={c.type} className="flex items-center justify-between text-xs">
+                          <code className="font-mono text-[rgb(var(--ec-page-text))]">{c.type}</code>
+                          <span className="text-[rgb(var(--ec-page-text-muted))]">
+                            {c.count} {c.count === 1 ? 'schema' : 'schemas'}
+                          </span>
+                        </div>
+                      ))}
+                    </div>
+                  </div>
+                </div>
+              )}
+
+              {/* Messages */}
+              <CollapsibleResourceList
+                title="Messages"
+                count={uniqueMessages.length}
+                defaultExpanded={true}
+                items={uniqueMessages.map((occ) => {
+                  const { Icon, bg } = getIconForMessageType(occ.messageType);
+                  return {
+                    key: `${occ.messageId}-${occ.messageVersion}`,
+                    label: occ.messageName || occ.messageId,
+                    version: occ.messageVersion,
+                    Icon,
+                    bg,
+                    onClick: () => {
+                      const nodeId = `msg-${occ.messageId}-${occ.messageVersion}`;
+                      fitView({ nodes: [{ id: nodeId }], duration: 300, padding: 0.5 });
+                    },
+                  };
+                })}
+              />
+
+              {/* Producers */}
+              {uniqueProducers.length > 0 && (
+                <CollapsibleResourceList
+                  title="Producers"
+                  count={uniqueProducers.length}
+                  defaultExpanded={false}
+                  items={uniqueProducers.map((p) => ({
+                    key: `${p.id}-${p.version}`,
+                    label: p.name || p.id,
+                    version: p.version,
+                    Icon: ServerIcon,
+                    bg: 'bg-pink-500',
+                    onClick: () => {
+                      const nodeId = `svc-producer-${p.id}-${p.version}`;
+                      fitView({ nodes: [{ id: nodeId }], duration: 300, padding: 0.5 });
+                    },
+                  }))}
+                />
+              )}
+
+              {/* Consumers */}
+              {uniqueConsumers.length > 0 && (
+                <CollapsibleResourceList
+                  title="Consumers"
+                  count={uniqueConsumers.length}
+                  defaultExpanded={false}
+                  items={uniqueConsumers.map((c) => ({
+                    key: `${c.id}-${c.version}`,
+                    label: c.name || c.id,
+                    version: c.version,
+                    Icon: ServerIcon,
+                    bg: 'bg-pink-500',
+                    onClick: () => {
+                      const nodeId = `svc-consumer-${c.id}-${c.version}`;
+                      fitView({ nodes: [{ id: nodeId }], duration: 300, padding: 0.5 });
+                    },
+                  }))}
+                />
+              )}
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function FieldNodeGraph(props: FieldNodeGraphProps) {
+  return (
+    <ReactFlowProvider>
+      <FieldNodeGraphInner {...props} />
+    </ReactFlowProvider>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/FieldsExplorer/FieldsExplorer.tsx b/packages/core/eventcatalog/src/components/FieldsExplorer/FieldsExplorer.tsx
new file mode 100644
index 000000000..71bbd8670
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/FieldsExplorer/FieldsExplorer.tsx
@@ -0,0 +1,554 @@
+import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
+import { ChevronLeft, ChevronRight, Lock, Search, X, AlertTriangle } from 'lucide-react';
+import FieldFilters from './FieldFilters';
+import FieldsTable from './FieldsTable';
+import type { FieldResult } from './FieldsTable';
+import FieldNodeGraph from './FieldNodeGraph';
+import { buildUrl } from '@utils/url-builder';
+
+function DummyNode({
+  type,
+  name,
+  version,
+  className,
+}: {
+  type: 'service' | 'event' | 'field';
+  name: string;
+  version?: string;
+  className?: string;
+}) {
+  const styles = {
+    service: { border: 'border-pink-500', badge: 'bg-pink-500', label: 'SERVICE' },
+    event: { border: 'border-orange-500', badge: 'bg-orange-500', label: 'EVENT' },
+    field: { border: 'border-cyan-500', badge: 'bg-cyan-500', label: 'FIELD' },
+  };
+  const s = styles[type];
+  return (
+    <div
+      className={`relative rounded-xl border-2 ${s.border} bg-[rgb(var(--ec-card-bg))] px-3 pt-4 pb-2.5 min-w-[140px] ${className || ''}`}
+    >
+      <div
+        className={`absolute -top-2.5 left-2.5 ${s.badge} text-white text-[7px] font-bold uppercase tracking-widest px-1.5 py-0.5 rounded`}
+      >
+        {s.label}
+      </div>
+      <div className="text-[11px] font-semibold text-[rgb(var(--ec-page-text))]">{name}</div>
+      {version && <div className="text-[9px] text-[rgb(var(--ec-page-text-muted))]">v{version}</div>}
+    </div>
+  );
+}
+
+function DummyEdge({ label }: { label: string }) {
+  return (
+    <div className="flex items-center gap-1">
+      <div className="w-8 h-px bg-[rgb(var(--ec-page-border))]" />
+      <span className="text-[8px] text-[rgb(var(--ec-page-text-muted))] whitespace-nowrap">{label}</span>
+      <div className="w-8 h-px bg-[rgb(var(--ec-page-border))]" />
+    </div>
+  );
+}
+
+function FieldLineageUpgradeModal({ fieldPath, onClose }: { fieldPath: string; onClose: () => void }) {
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50" onClick={onClose}>
+      <div
+        className="w-[90vw] h-[80vh] max-w-[1400px] rounded-xl border shadow-2xl flex flex-col overflow-hidden relative"
+        style={{
+          backgroundColor: 'rgb(var(--ec-page-bg))',
+          borderColor: 'rgb(var(--ec-page-border))',
+        }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        {/* Header */}
+        <div
+          className="flex items-center justify-between px-5 py-3 border-b flex-shrink-0"
+          style={{ borderColor: 'rgb(var(--ec-page-border))' }}
+        >
+          <div className="flex items-center gap-2">
+            <h3 className="text-sm font-semibold" style={{ color: 'rgb(var(--ec-page-text))' }}>
+              Field Traceability
+            </h3>
+            <code
+              className="px-2 py-0.5 rounded text-xs font-mono"
+              style={{
+                backgroundColor: 'rgb(var(--ec-accent) / 0.1)',
+                color: 'rgb(var(--ec-accent))',
+              }}
+            >
+              {fieldPath}
+            </code>
+          </div>
+          <button
+            onClick={onClose}
+            className="p-1.5 rounded-lg transition-colors hover:bg-[rgb(var(--ec-content-hover))] flex-shrink-0"
+            style={{ color: 'rgb(var(--ec-icon-color))' }}
+          >
+            <X className="w-4 h-4" />
+          </button>
+        </div>
+
+        {/* Blurred dummy content */}
+        <div className="flex-1 relative overflow-hidden">
+          {/* Fake graph + side panel */}
+          <div className="absolute inset-0 flex blur-[2px] opacity-60 select-none pointer-events-none">
+            {/* Fake graph area */}
+            <div className="flex-1 flex items-center justify-center p-8">
+              <div className="flex items-center gap-3">
+                {/* Producer services */}
+                <div className="flex flex-col gap-6">
+                  <DummyNode type="service" name="Billing Service" version="1.2.0" />
+                  <DummyNode type="service" name="Order Service" version="2.0.1" />
+                </div>
+                {/* Edges to events */}
+                <div className="flex flex-col gap-12">
+                  <DummyEdge label="produces" />
+                  <DummyEdge label="produces" />
+                </div>
+                {/* Events */}
+                <div className="flex flex-col gap-6">
+                  <DummyNode type="event" name="Payment Due" version="0.0.1" />
+                  <DummyNode type="event" name="Order Created" version="1.0.0" />
+                </div>
+                {/* Edges to field */}
+                <div className="flex flex-col gap-12">
+                  <DummyEdge label="contains" />
+                  <DummyEdge label="contains" />
+                </div>
+                {/* Field */}
+                <div className="flex flex-col gap-6">
+                  <DummyNode type="field" name={fieldPath} />
+                </div>
+                {/* Edges to consumers */}
+                <div className="flex flex-col gap-12">
+                  <DummyEdge label="consumed by" />
+                </div>
+                {/* Consumer services */}
+                <div className="flex flex-col gap-6">
+                  <DummyNode type="service" name="Notification Service" version="0.0.2" />
+                </div>
+              </div>
+            </div>
+            {/* Fake side panel */}
+            <div className="w-[280px] flex-shrink-0 border-l border-[rgb(var(--ec-page-border))] p-4 space-y-4">
+              <div>
+                <div className="text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider mb-2">
+                  Field
+                </div>
+                <div className="text-sm font-mono font-semibold text-[rgb(var(--ec-page-text))]">{fieldPath}</div>
+                <div className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-1">string</div>
+              </div>
+              <div>
+                <div className="text-[11px] font-medium text-amber-500 uppercase tracking-wider mb-2">Type Conflict</div>
+                <div className="rounded-lg border border-amber-500/20 bg-amber-500/5 p-2.5 space-y-1">
+                  <div className="text-xs text-amber-600">Inconsistent types detected</div>
+                  <div className="flex justify-between text-xs">
+                    <code className="font-mono">string</code>
+                    <span className="text-[rgb(var(--ec-page-text-muted))]">3 schemas</span>
+                  </div>
+                  <div className="flex justify-between text-xs">
+                    <code className="font-mono">integer</code>
+                    <span className="text-[rgb(var(--ec-page-text-muted))]">1 schema</span>
+                  </div>
+                </div>
+              </div>
+              <div>
+                <div className="text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider mb-2">
+                  Messages (3)
+                </div>
+                <div className="space-y-1.5">
+                  <div className="rounded-lg border border-[rgb(var(--ec-page-border)/0.5)] bg-[rgb(var(--ec-card-bg))] px-2.5 py-2 text-xs">
+                    Payment Due
+                  </div>
+                  <div className="rounded-lg border border-[rgb(var(--ec-page-border)/0.5)] bg-[rgb(var(--ec-card-bg))] px-2.5 py-2 text-xs">
+                    Order Created
+                  </div>
+                  <div className="rounded-lg border border-[rgb(var(--ec-page-border)/0.5)] bg-[rgb(var(--ec-card-bg))] px-2.5 py-2 text-xs">
+                    Invoice Generated
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+
+          {/* Upgrade prompt overlay */}
+          <div className="absolute inset-0 flex items-center justify-center bg-[rgb(var(--ec-page-bg)/0.5)]">
+            <div className="text-center max-w-lg px-6 py-8 rounded-2xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] shadow-2xl">
+              <div className="w-12 h-12 rounded-full bg-[rgb(var(--ec-accent)/0.1)] flex items-center justify-center mx-auto mb-4">
+                <Lock className="w-6 h-6 text-[rgb(var(--ec-accent))]" />
+              </div>
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))] mb-2">Field Lineage & Traceability</h3>
+              <p className="text-sm text-[rgb(var(--ec-page-text-muted))] mb-5 leading-relaxed">
+                See which services produce and consume this field, detect type conflicts across schemas, and trace field usage
+                across your entire event-driven architecture.
+              </p>
+              <a
+                href="https://eventcatalog.cloud/"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="inline-flex items-center gap-2 px-5 py-2.5 rounded-lg text-sm font-medium text-white bg-[rgb(var(--ec-accent))] hover:opacity-90 transition-opacity"
+              >
+                Start your 14-day free trial
+              </a>
+              <p className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-3">
+                Available with EventCatalog Scale. No credit card required.
+              </p>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+interface Facets {
+  formats: { value: string; count: number }[];
+  types: { value: string; count: number }[];
+  messageTypes: { value: string; count: number }[];
+}
+
+interface FieldsApiResponse {
+  fields: FieldResult[];
+  total: number;
+  cursor: string | null;
+  facets: Facets;
+  error?: string;
+}
+
+interface SelectedField {
+  path: string;
+  type: string;
+  description: string;
+  required: boolean;
+  conflicts?: { type: string; count: number }[];
+  occurrences: FieldResult[];
+}
+
+interface FieldsExplorerProps {
+  isScaleEnabled?: boolean;
+}
+
+export default function FieldsExplorer({ isScaleEnabled = false }: FieldsExplorerProps) {
+  const [fields, setFields] = useState<FieldResult[]>([]);
+  const [total, setTotal] = useState(0);
+  const [cursor, setCursor] = useState<string | null>(null);
+  const [facets, setFacets] = useState<Facets | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // Filter state
+  const [searchQuery, setSearchQuery] = useState('');
+  const [selectedFormats, setSelectedFormats] = useState<string[]>([]);
+  const [selectedMessageTypes, setSelectedMessageTypes] = useState<string[]>([]);
+  const [sharedOnly, setSharedOnly] = useState(false);
+  const [conflictingOnly, setConflictingOnly] = useState(false);
+
+  // Modal state
+  const [selectedField, setSelectedField] = useState<SelectedField | null>(null);
+
+  // Pagination cursors
+  const [cursorHistory, setCursorHistory] = useState<string[]>([]);
+  const [currentPageIndex, setCurrentPageIndex] = useState(0);
+
+  // Abort controller for in-flight requests
+  const abortControllerRef = useRef<AbortController | null>(null);
+
+  const buildQueryParams = useCallback(
+    (extraParams?: Record<string, string>) => {
+      const params = new URLSearchParams();
+      if (searchQuery) params.set('q', searchQuery);
+      if (selectedFormats.length > 0) params.set('format', selectedFormats.join(','));
+      if (selectedMessageTypes.length > 0) params.set('messageType', selectedMessageTypes.join(','));
+      if (sharedOnly) params.set('shared', 'true');
+      if (conflictingOnly) params.set('conflicting', 'true');
+      if (extraParams) {
+        Object.entries(extraParams).forEach(([key, value]) => {
+          params.set(key, value);
+        });
+      }
+      return params;
+    },
+    [searchQuery, selectedFormats, selectedMessageTypes, sharedOnly, conflictingOnly]
+  );
+
+  const fetchFields = useCallback(
+    async (cursorValue?: string) => {
+      // Cancel any in-flight request
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+      const controller = new AbortController();
+      abortControllerRef.current = controller;
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const params = buildQueryParams(cursorValue ? { cursor: cursorValue } : undefined);
+        const response = await fetch(buildUrl(`/api/schemas/fields?${params.toString()}`), {
+          signal: controller.signal,
+        });
+
+        if (!response.ok) {
+          const data = await response.json();
+          throw new Error(data.error || `HTTP ${response.status}`);
+        }
+
+        const data: FieldsApiResponse = await response.json();
+        setFields(data.fields || []);
+        setTotal(data.total || 0);
+        setCursor(data.cursor || null);
+        if (data.facets) {
+          setFacets({
+            formats: data.facets.formats || [],
+            types: data.facets.types || [],
+            messageTypes: data.facets.messageTypes || [],
+          });
+        }
+      } catch (err: any) {
+        if (err.name === 'AbortError') return;
+        setError(err.message || 'Failed to load fields');
+      } finally {
+        if (!controller.signal.aborted) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [buildQueryParams]
+  );
+
+  // Initial fetch and re-fetch when filters change
+  useEffect(() => {
+    setCursorHistory([]);
+    setCurrentPageIndex(0);
+    fetchFields();
+  }, [searchQuery, selectedFormats, selectedMessageTypes, sharedOnly, conflictingOnly]);
+
+  // Open modal: fetch all occurrences for the field path, then show modal
+  const handleSelectField = useCallback(async (fieldPath: string) => {
+    // Non-scale users get the locked upgrade modal
+    if (!isScaleEnabled) {
+      setSelectedField({
+        path: fieldPath,
+        type: 'unknown',
+        description: '',
+        required: false,
+        occurrences: [],
+      });
+      return;
+    }
+
+    try {
+      // Fetch all pages of occurrences for this field path
+      let allOccurrences: FieldResult[] = [];
+      let nextCursor: string | null = null;
+
+      do {
+        const params = new URLSearchParams();
+        params.set('path', fieldPath);
+        params.set('pageSize', '100');
+        if (nextCursor) params.set('cursor', nextCursor);
+
+        const response = await fetch(buildUrl(`/api/schemas/fields?${params.toString()}`));
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`);
+        }
+
+        const data: FieldsApiResponse = await response.json();
+        allOccurrences = allOccurrences.concat(data.fields || []);
+        nextCursor = data.cursor;
+      } while (nextCursor);
+
+      setSelectedField({
+        path: fieldPath,
+        type: allOccurrences[0]?.type || 'unknown',
+        description: allOccurrences[0]?.description || '',
+        required: allOccurrences[0]?.required || false,
+        conflicts: allOccurrences[0]?.conflicts,
+        occurrences: allOccurrences,
+      });
+    } catch {
+      // Silently fail — user can retry by clicking again
+    }
+  }, []);
+
+  const handleNextPage = useCallback(() => {
+    if (!cursor) return;
+    setCursorHistory((prev) => [...prev, cursor]);
+    setCurrentPageIndex((prev) => prev + 1);
+    fetchFields(cursor);
+  }, [cursor, fetchFields]);
+
+  const handlePrevPage = useCallback(() => {
+    if (currentPageIndex === 0) return;
+    const newIndex = currentPageIndex - 1;
+    setCurrentPageIndex(newIndex);
+    if (newIndex === 0) {
+      fetchFields();
+    } else {
+      fetchFields(cursorHistory[newIndex - 1]);
+    }
+    setCursorHistory((prev) => prev.slice(0, -1));
+  }, [currentPageIndex, cursorHistory, fetchFields]);
+
+  // Map facets for FieldFilters
+  const filterFacets = facets
+    ? {
+        formats: facets.formats,
+        messageTypes: facets.messageTypes,
+      }
+    : null;
+
+  const conflictingFieldCount = useMemo(() => {
+    return new Set(fields.filter((field) => field.conflicts && field.conflicts.length > 1).map((field) => field.path)).size;
+  }, [fields]);
+
+  return (
+    <div className="flex h-full min-h-0 flex-col overflow-hidden">
+      <div className="flex flex-1 min-h-0 gap-0 overflow-hidden">
+        {/* Filter Sidebar */}
+        <div
+          className="fixed top-0 z-20 flex h-screen w-[320px] flex-shrink-0 flex-col overflow-hidden border-r border-[rgb(var(--ec-page-border))] bg-linear-to-bl from-[rgb(var(--ec-page-bg))] via-[rgb(var(--ec-page-bg))] to-[rgb(var(--ec-accent)/0.08)]"
+          style={{ left: 'var(--ec-vertical-nav-width)', width: 'var(--ec-fields-sidebar-width, 320px)' }}
+        >
+          <div className="flex h-[60px] flex-shrink-0 items-center border-b border-[rgb(var(--ec-page-border))] px-4">
+            <div className="relative min-w-0 flex-1">
+              <div className="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
+                <Search className="h-4 w-4 text-[rgb(var(--ec-icon-color))]" />
+              </div>
+              <input
+                type="text"
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                placeholder="Search fields..."
+                className="block w-full rounded-md border-0 bg-[rgb(var(--ec-header-bg))] py-1.5 pl-10 pr-8 text-[rgb(var(--ec-header-text))] shadow-xs ring-1 ring-inset ring-[rgb(var(--ec-dropdown-border))] placeholder:text-[rgb(var(--ec-icon-color))] font-light sm:text-sm sm:leading-6 focus:outline-hidden focus:ring-1 focus:ring-inset focus:ring-[rgb(var(--ec-accent))]"
+              />
+              {searchQuery && (
+                <button
+                  onClick={() => setSearchQuery('')}
+                  className="absolute right-2 top-1/2 -translate-y-1/2 p-0.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))]"
+                >
+                  <X className="h-3.5 w-3.5" />
+                </button>
+              )}
+            </div>
+          </div>
+
+          <div className="flex-1 overflow-y-auto px-4 pt-4 pb-4">
+            <FieldFilters
+              searchQuery={searchQuery}
+              onSearchChange={setSearchQuery}
+              selectedFormats={selectedFormats}
+              onFormatsChange={setSelectedFormats}
+              selectedMessageTypes={selectedMessageTypes}
+              onMessageTypesChange={setSelectedMessageTypes}
+              sharedOnly={sharedOnly}
+              onSharedOnlyChange={setSharedOnly}
+              conflictingOnly={conflictingOnly}
+              onConflictingOnlyChange={setConflictingOnly}
+              facets={filterFacets}
+              isScaleEnabled={isScaleEnabled}
+            />
+          </div>
+        </div>
+
+        {/* Main Content */}
+        <div
+          className="flex-1 min-h-0 min-w-0 flex flex-col overflow-hidden bg-[rgb(var(--ec-page-bg))]"
+          style={{ marginLeft: 'var(--ec-fields-sidebar-width, 320px)' }}
+        >
+          {/* Header */}
+          <div className="flex items-center justify-between px-6 py-4">
+            <h2 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">
+              Fields <span className="text-sm text-[rgb(var(--ec-page-text-muted))] font-normal ml-1">({total})</span>
+            </h2>
+          </div>
+
+          {/* Error state */}
+          {error && (
+            <div className="mx-6 mb-4 px-4 py-3 rounded-lg border border-red-300 bg-red-50 text-red-700 text-sm">{error}</div>
+          )}
+
+          {conflictingFieldCount > 0 && (
+            <div className="mx-6 mb-4 rounded-lg border border-amber-500/25 bg-amber-500/8 px-4 py-3 text-sm text-[rgb(var(--ec-page-text))]">
+              <div className="flex items-start gap-2.5">
+                <AlertTriangle className="mt-0.5 h-4 w-4 flex-shrink-0 text-amber-500" />
+                <div>
+                  <p className="font-medium text-[rgb(var(--ec-page-text))]">
+                    {conflictingFieldCount} conflicting {conflictingFieldCount === 1 ? 'property' : 'properties'} found
+                  </p>
+                  <p className="mt-1 text-[0.8rem] text-[rgb(var(--ec-page-text-muted))]">
+                    These properties are used with more than one type across the current results.
+                  </p>
+                </div>
+              </div>
+            </div>
+          )}
+
+          {/* Table */}
+          <FieldsTable fields={fields} onSelectField={handleSelectField} isLoading={isLoading} isScaleEnabled={isScaleEnabled} />
+
+          {/* Pagination */}
+          <div className="flex-shrink-0 flex items-center justify-between px-6 py-3 border-t border-[rgb(var(--ec-page-border))]">
+            <span className="text-xs text-[rgb(var(--ec-page-text-muted))]">
+              {total > 0 && (
+                <>
+                  <span className="font-medium text-[rgb(var(--ec-page-text))]">{fields.length}</span> of{' '}
+                  <span className="font-medium text-[rgb(var(--ec-page-text))]">{total}</span> fields
+                </>
+              )}
+            </span>
+            <div className="flex items-center gap-1.5">
+              <button
+                className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] disabled:opacity-30 disabled:cursor-not-allowed transition-colors"
+                onClick={handlePrevPage}
+                disabled={currentPageIndex === 0}
+                title="Previous page"
+              >
+                <ChevronLeft className="w-4 h-4" />
+              </button>
+              <span className="text-xs tabular-nums text-[rgb(var(--ec-page-text-muted))] min-w-[60px] text-center">
+                <span className="font-medium text-[rgb(var(--ec-page-text))]">{currentPageIndex + 1}</span>
+                {' / '}
+                <span>{Math.max(cursorHistory.length + (cursor ? 2 : 1), currentPageIndex + 1)}</span>
+              </span>
+              <button
+                className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] disabled:opacity-30 disabled:cursor-not-allowed transition-colors"
+                onClick={handleNextPage}
+                disabled={!cursor}
+                title="Next page"
+              >
+                <ChevronRight className="w-4 h-4" />
+              </button>
+            </div>
+          </div>
+        </div>
+
+        {/* Field Detail Modal with Node Graph */}
+        {selectedField && !isScaleEnabled && (
+          <FieldLineageUpgradeModal fieldPath={selectedField.path} onClose={() => setSelectedField(null)} />
+        )}
+        {selectedField && isScaleEnabled && (
+          <FieldNodeGraph
+            fieldPath={selectedField.path}
+            fieldType={selectedField.type}
+            fieldDescription={selectedField.description}
+            fieldRequired={selectedField.required}
+            fieldConflicts={selectedField.conflicts}
+            occurrences={selectedField.occurrences.map((f) => ({
+              messageId: f.messageId,
+              messageVersion: f.messageVersion,
+              messageType: f.messageType,
+              messageName: f.messageName,
+              messageSummary: f.messageSummary,
+              messageOwners: f.messageOwners,
+              fieldType: f.type,
+              producers: f.producers,
+              consumers: f.consumers,
+            }))}
+            onClose={() => setSelectedField(null)}
+          />
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/FieldsExplorer/FieldsTable.tsx b/packages/core/eventcatalog/src/components/FieldsExplorer/FieldsTable.tsx
new file mode 100644
index 000000000..50ba8a13f
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/FieldsExplorer/FieldsTable.tsx
@@ -0,0 +1,235 @@
+import { useState } from 'react';
+import { SearchX, Copy, Check, AlertTriangle } from 'lucide-react';
+import { BoltIcon, ChatBubbleLeftIcon, MagnifyingGlassIcon } from '@heroicons/react/24/solid';
+import { buildUrl } from '@utils/url-builder';
+import { getCollectionTextColorClass } from '@utils/collection-colors';
+
+export interface FieldResult {
+  path: string;
+  type: string;
+  description: string;
+  required: boolean;
+  schemaFormat: string;
+  messageId: string;
+  messageVersion: string;
+  messageType: string;
+  messageName?: string;
+  messageSummary?: string;
+  messageOwners?: string[];
+  producers: { id: string; version: string; name?: string; summary?: string; owners?: string[] }[];
+  consumers: { id: string; version: string; name?: string; summary?: string; owners?: string[] }[];
+  usedInCount?: number;
+  conflicts?: { type: string; count: number }[];
+}
+
+export interface FieldsTableProps {
+  fields: FieldResult[];
+  onSelectField: (fieldPath: string) => void;
+  isLoading: boolean;
+  isScaleEnabled?: boolean;
+}
+
+const getColorAndIconForMessageType = (type: string) => {
+  switch (type) {
+    case 'event':
+      return { color: 'orange', Icon: BoltIcon };
+    case 'command':
+      return { color: 'blue', Icon: ChatBubbleLeftIcon };
+    case 'query':
+      return { color: 'green', Icon: MagnifyingGlassIcon };
+    default:
+      return { color: 'gray', Icon: ChatBubbleLeftIcon };
+  }
+};
+
+function MessageBadge({ id, name, version, type }: { id: string; name?: string; version: string; type: string }) {
+  const { color, Icon } = getColorAndIconForMessageType(type);
+  const collection = type === 'query' ? 'queries' : `${type}s`;
+  const messageUrl = buildUrl(`/docs/${collection}/${id}/${version}`);
+  return (
+    <a
+      href={messageUrl}
+      onClick={(e) => e.stopPropagation()}
+      className="group/msg inline-flex items-center gap-1.5 text-[0.8rem] text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-accent))] transition-colors"
+    >
+      <Icon className={`h-3.5 w-3.5 ${getCollectionTextColorClass(color)} flex-shrink-0`} />
+      <span className="truncate max-w-[160px] text-[rgb(var(--ec-page-text-muted))] group-hover/msg:text-[rgb(var(--ec-accent))]">
+        {name || id}
+      </span>
+    </a>
+  );
+}
+
+function FieldPathCell({ path }: { path: string }) {
+  const [copied, setCopied] = useState(false);
+
+  return (
+    <span className="inline-flex items-center gap-1 font-mono text-[rgb(var(--ec-page-text))]" title={path}>
+      {path}
+      <button
+        className={`opacity-0 group-hover:opacity-100 transition-opacity p-0.5 rounded hover:bg-[rgb(var(--ec-content-hover))]`}
+        onClick={(e) => {
+          e.stopPropagation();
+          navigator.clipboard.writeText(path);
+          setCopied(true);
+          setTimeout(() => setCopied(false), 1500);
+        }}
+        title="Copy field path"
+      >
+        {copied ? <Check className="w-3 h-3 text-green-500" /> : <Copy className="w-3 h-3 text-[rgb(var(--ec-icon-color))]" />}
+      </button>
+    </span>
+  );
+}
+
+export default function FieldsTable({ fields, onSelectField, isLoading, isScaleEnabled = false }: FieldsTableProps) {
+  if (isLoading) {
+    return (
+      <div className="flex-1 flex items-center justify-center px-6 pb-5">
+        <div className="flex flex-col items-center gap-3">
+          <div className="w-8 h-8 border-2 border-[rgb(var(--ec-accent))] border-t-transparent rounded-full animate-spin" />
+          <span className="text-sm text-[rgb(var(--ec-page-text-muted))]">Loading fields...</span>
+        </div>
+      </div>
+    );
+  }
+
+  if (fields.length === 0) {
+    return (
+      <div className="flex-1 flex items-center justify-center px-6 pb-5">
+        <div className="flex flex-col items-center justify-center text-[rgb(var(--ec-page-text-muted))]">
+          <SearchX className="w-10 h-10 text-[rgb(var(--ec-icon-color))] mb-3 opacity-50" />
+          <p className="text-sm font-medium text-[rgb(var(--ec-page-text-muted))]">No schema fields found</p>
+          <p className="text-xs text-[rgb(var(--ec-icon-color))] mt-1 max-w-xs text-center">
+            Add <code className="px-1 py-0.5 rounded bg-[rgb(var(--ec-content-hover))] font-mono text-[11px]">schemaPath</code> to
+            your events, commands, or queries to get started.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="min-h-0 flex-1 overflow-auto px-6 pb-5">
+      <div className="overflow-hidden rounded-xl border border-[rgb(var(--ec-page-border)/0.72)] dark:border-white/10 bg-[rgb(var(--ec-dropdown-bg)/0.66)]">
+        <table className="min-w-full divide-y divide-[rgb(var(--ec-page-border)/0.62)] dark:divide-white/10">
+          <thead className="sticky top-0 z-10 bg-[rgb(var(--ec-content-hover)/0.45)]">
+            <tr>
+              <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+                Property
+              </th>
+              <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+                Type
+              </th>
+              <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+                Message
+              </th>
+              <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+                Format
+              </th>
+              <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+                Required
+              </th>
+              {isScaleEnabled && (
+                <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+                  Consistency
+                </th>
+              )}
+              {isScaleEnabled && (
+                <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+                  Used In
+                </th>
+              )}
+              <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+                Owners
+              </th>
+            </tr>
+          </thead>
+          <tbody className="divide-y divide-[rgb(var(--ec-page-border)/0.5)] dark:divide-white/8">
+            {fields.map((field, index) => {
+              const rowKey = `${field.path}-${field.messageId}-${field.messageVersion}-${index}`;
+              const owners = field.messageOwners || [];
+
+              return (
+                <tr
+                  key={rowKey}
+                  className="group cursor-pointer bg-transparent transition-colors hover:bg-[rgb(var(--ec-content-hover)/0.38)]"
+                  onClick={() => onSelectField(field.path)}
+                >
+                  <td className="px-4 py-3 text-sm text-[rgb(var(--ec-page-text))] max-w-[300px]">
+                    <div className="overflow-x-auto">
+                      <FieldPathCell path={field.path} />
+                    </div>
+                  </td>
+                  <td className="px-4 py-3 text-sm font-mono text-[rgb(var(--ec-page-text-muted))]">{field.type}</td>
+                  <td className="px-4 py-3 text-sm text-[rgb(var(--ec-page-text))]">
+                    <MessageBadge
+                      id={field.messageId}
+                      name={field.messageName}
+                      version={field.messageVersion}
+                      type={field.messageType}
+                    />
+                  </td>
+                  <td className="px-4 py-3 text-sm text-[rgb(var(--ec-page-text-muted))]">{field.schemaFormat}</td>
+                  <td className="px-4 py-3 text-sm text-[rgb(var(--ec-page-text-muted))]">
+                    {field.required ? (
+                      <Check className="h-4 w-4 text-green-500" />
+                    ) : (
+                      <span className="text-[0.8rem] text-[rgb(var(--ec-page-text-muted))]">-</span>
+                    )}
+                  </td>
+                  {isScaleEnabled && (
+                    <td className="px-4 py-3 text-sm text-[rgb(var(--ec-page-text-muted))]">
+                      {field.conflicts && field.conflicts.length > 1 ? (
+                        <div
+                          className="flex items-center gap-1.5"
+                          title={field.conflicts.map((c) => `${c.type} (${c.count})`).join(', ')}
+                        >
+                          <AlertTriangle className="w-3.5 h-3.5 text-amber-500 flex-shrink-0" />
+                          <span className="inline-flex items-center px-1.5 py-0.5 rounded text-[10px] font-semibold bg-amber-500/10 text-amber-600 border border-amber-500/20">
+                            {field.conflicts.length} types
+                          </span>
+                        </div>
+                      ) : (
+                        <span className="inline-flex items-center" title="All usages of this field match the same type">
+                          <Check className="h-4 w-4 text-green-500" />
+                        </span>
+                      )}
+                    </td>
+                  )}
+                  {isScaleEnabled && (
+                    <td className="px-4 py-3 text-sm text-[rgb(var(--ec-page-text-muted))]">
+                      <span className="text-[0.8rem] text-[rgb(var(--ec-page-text-muted))]">
+                        {field.usedInCount || 1} {(field.usedInCount || 1) === 1 ? 'schema' : 'schemas'}
+                      </span>
+                    </td>
+                  )}
+                  <td className="px-4 py-3 text-sm text-[rgb(var(--ec-page-text-muted))]">
+                    {owners.length > 0 ? (
+                      <div className="flex items-center gap-1 flex-wrap">
+                        {owners.slice(0, 2).map((owner) => (
+                          <span
+                            key={owner}
+                            className="inline-flex items-center px-1.5 py-0.5 rounded text-[10px] font-medium bg-[rgb(var(--ec-accent)/0.1)] text-[rgb(var(--ec-accent))] truncate max-w-[100px]"
+                            title={owner}
+                          >
+                            {owner}
+                          </span>
+                        ))}
+                        {owners.length > 2 && (
+                          <span className="text-[10px] text-[rgb(var(--ec-page-text-muted))]">+{owners.length - 2}</span>
+                        )}
+                      </div>
+                    ) : (
+                      <span className="text-[0.8rem] text-[rgb(var(--ec-page-text-muted))]">-</span>
+                    )}
+                  </td>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/Grids/DomainGrid.tsx b/packages/core/eventcatalog/src/components/Grids/DomainGrid.tsx
new file mode 100644
index 000000000..6b9f3986a
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Grids/DomainGrid.tsx
@@ -0,0 +1,830 @@
+import { memo, useMemo, useState } from 'react';
+import {
+  ServerIcon,
+  RectangleGroupIcon,
+  BoltIcon,
+  ChatBubbleLeftIcon,
+  MagnifyingGlassIcon,
+  CircleStackIcon,
+  ChevronDownIcon,
+  ChevronUpIcon,
+  ArrowTopRightOnSquareIcon,
+  ArrowLongRightIcon,
+  ArrowLongLeftIcon,
+  CubeIcon,
+  GlobeAltIcon,
+} from '@heroicons/react/24/outline';
+import { buildUrl } from '@utils/url-builder';
+import { BoxIcon, Group as GroupIcon } from 'lucide-react';
+import { getSpecUrl, getSpecIcon, getSpecLabel, getServiceSpecifications } from './specification-utils';
+
+// ============================================
+// Types
+// ============================================
+
+interface DomainGridProps {
+  domain: any;
+}
+
+// ============================================
+// Helper functions
+// ============================================
+
+const getMessageIcon = (collection: string) => {
+  switch (collection) {
+    case 'events':
+      return { Icon: BoltIcon, color: 'orange' };
+    case 'commands':
+      return { Icon: ChatBubbleLeftIcon, color: 'blue' };
+    case 'queries':
+      return { Icon: MagnifyingGlassIcon, color: 'emerald' };
+    default:
+      return { Icon: BoltIcon, color: 'gray' };
+  }
+};
+
+// ============================================
+// Sub-components
+// ============================================
+
+export const EntityBadge = memo(({ entity }: { entity: any }) => {
+  const id = entity?.data?.id || entity?.id;
+  const name = entity?.data?.name || entity?.name || id;
+  const version = entity?.data?.version || entity?.version || 'latest';
+
+  return (
+    <a
+      href={buildUrl(`/docs/entities/${id}/${version}`)}
+      className="inline-flex items-center gap-2 px-3 py-2 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-lg text-sm font-medium text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] hover:border-[rgb(var(--ec-accent)/0.5)] transition-all shadow-xs"
+    >
+      <BoxIcon className="h-4 w-4 text-[rgb(var(--ec-accent))]" />
+      <span>{name}</span>
+    </a>
+  );
+});
+
+const MessageLink = memo(({ message }: { message: any }) => {
+  const data = message?.data || message;
+  const collection = message?.collection || 'events';
+  const { Icon, color } = getMessageIcon(collection);
+  const id = data?.id || message?.id;
+  const name = data?.name || data?.id || id;
+  const version = data?.version || message?.data?.version || 'latest';
+
+  const iconStyles: Record<string, string> = {
+    orange: 'text-orange-500',
+    blue: 'text-blue-500',
+    emerald: 'text-emerald-500',
+    gray: 'text-gray-500',
+  };
+
+  return (
+    <a
+      href={buildUrl(`/docs/${collection}/${id}/${version}`)}
+      className="flex items-center gap-2 py-1.5 text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors group"
+    >
+      <Icon className={`h-4 w-4 flex-shrink-0 ${iconStyles[color]}`} />
+      <span className="group-hover:underline">{name}</span>
+      <span className="text-xs text-[rgb(var(--ec-icon-color))]">v{version}</span>
+    </a>
+  );
+});
+
+const SpecificationBadge = memo(
+  ({ spec, serviceId, serviceVersion }: { spec: any; serviceId: string; serviceVersion: string }) => {
+    return (
+      <a
+        href={getSpecUrl(spec, serviceId, serviceVersion)}
+        className="inline-flex items-center gap-1.5 px-2 py-1.5 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-lg text-xs font-medium text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] hover:border-[rgb(var(--ec-accent)/0.5)] transition-all shadow-xs"
+      >
+        <img src={buildUrl(`/icons/${getSpecIcon(spec.type)}.svg`, true)} alt={`${spec.type} icon`} className="h-3.5 w-3.5" />
+        <span>{getSpecLabel(spec.type)}</span>
+      </a>
+    );
+  }
+);
+
+const ContainerLink = memo(({ container, type }: { container: any; type: 'reads' | 'writes' }) => {
+  const data = container?.data || container;
+  const id = data?.id || container?.id;
+  const name = data?.name || id;
+  const version = data?.version || 'latest';
+
+  return (
+    <a
+      href={buildUrl(`/docs/containers/${id}/${version}`)}
+      className="flex items-center gap-2 py-1.5 text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors group"
+    >
+      <CircleStackIcon className={`h-4 w-4 ${type === 'reads' ? 'text-amber-500' : 'text-violet-500'}`} />
+      <span className="group-hover:underline">{name}</span>
+    </a>
+  );
+});
+
+// Standalone data store (container) link, used to list a system's data stores
+const DataStoreLink = memo(({ container }: { container: any }) => {
+  const data = container?.data || container;
+  const id = data?.id || container?.id;
+  const name = data?.name || id;
+  const version = data?.version || 'latest';
+  const technology = data?.technology;
+
+  return (
+    <a
+      href={buildUrl(`/docs/containers/${id}/${version}`)}
+      className="inline-flex items-center gap-2 px-3 py-2 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-lg text-sm font-medium text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] hover:border-[rgb(var(--ec-accent)/0.5)] transition-all shadow-xs"
+    >
+      <CircleStackIcon className="h-4 w-4 text-amber-500" />
+      <span>{name}</span>
+      {technology && <span className="text-xs text-[rgb(var(--ec-icon-color))]">{technology}</span>}
+    </a>
+  );
+});
+
+// Searchable scrollable box component
+const SearchableBox = memo(
+  ({
+    title,
+    icon: Icon,
+    iconColor,
+    items,
+    renderItem,
+    emptyText = '—',
+  }: {
+    title: string;
+    icon: any;
+    iconColor: string;
+    items: any[];
+    renderItem: (item: any, idx: number) => React.ReactNode;
+    emptyText?: string;
+  }) => {
+    const [search, setSearch] = useState('');
+
+    const filteredItems = items.filter((item) => {
+      if (!search) return true;
+      const data = item?.data || item;
+      const name = data?.name || data?.id || '';
+      return name.toLowerCase().includes(search.toLowerCase());
+    });
+
+    return (
+      <div className="flex flex-col">
+        <div className="flex items-center gap-2 mb-2">
+          <div className="flex items-center gap-1.5 flex-shrink-0">
+            <Icon className={`h-4 w-4 ${iconColor}`} />
+            <h4 className="text-xs font-semibold text-[rgb(var(--ec-page-text))] uppercase tracking-wide">{title}</h4>
+            <span className="text-[10px] text-[rgb(var(--ec-icon-color))] font-medium">({items.length})</span>
+          </div>
+          {items.length > 0 && (
+            <input
+              type="text"
+              placeholder="Search..."
+              value={search}
+              onChange={(e) => setSearch(e.target.value)}
+              className="flex-1 px-2 py-0.5 text-xs border border-[rgb(var(--ec-input-border))] rounded focus:outline-hidden focus:border-[rgb(var(--ec-accent))] bg-[rgb(var(--ec-input-bg))] text-[rgb(var(--ec-input-text))]"
+              onClick={(e) => e.stopPropagation()}
+            />
+          )}
+        </div>
+        {items.length > 0 ? (
+          <div className="space-y-0.5 max-h-32 overflow-y-auto pr-1">
+            {filteredItems.length > 0 ? (
+              filteredItems.map((item, idx) => renderItem(item, idx))
+            ) : (
+              <p className="text-xs text-[rgb(var(--ec-icon-color))] italic">No matches</p>
+            )}
+          </div>
+        ) : (
+          <p className="text-xs text-[rgb(var(--ec-icon-color))]">{emptyText}</p>
+        )}
+      </div>
+    );
+  }
+);
+
+// Expanded content for service card
+const ServiceExpandedContent = memo(
+  ({ receives, sends, readsFrom, writesTo }: { receives: any[]; sends: any[]; readsFrom: any[]; writesTo: any[] }) => {
+    const hasMessages = receives.length > 0 || sends.length > 0;
+    const hasContainers = readsFrom.length > 0 || writesTo.length > 0;
+
+    return (
+      <div className="border-t border-[rgb(var(--ec-page-border))] px-4 py-3 space-y-4">
+        {/* Messages Row */}
+        {hasMessages && (
+          <div className="grid grid-cols-2 gap-x-6">
+            <SearchableBox
+              title="Receives"
+              icon={ArrowLongRightIcon}
+              iconColor="text-blue-400"
+              items={receives}
+              renderItem={(msg, idx) => {
+                const msgId = msg?.data?.id || msg?.id;
+                return msgId ? <MessageLink key={`${msgId}-${idx}`} message={msg} /> : null;
+              }}
+            />
+            <SearchableBox
+              title="Sends"
+              icon={ArrowLongLeftIcon}
+              iconColor="text-emerald-400 rotate-180"
+              items={sends}
+              renderItem={(msg, idx) => {
+                const msgId = msg?.data?.id || msg?.id;
+                return msgId ? <MessageLink key={`${msgId}-${idx}`} message={msg} /> : null;
+              }}
+            />
+          </div>
+        )}
+
+        {/* Data Row */}
+        {hasContainers && (
+          <div className="grid grid-cols-2 gap-x-6 pt-3 border-t border-[rgb(var(--ec-page-border))]">
+            <SearchableBox
+              title="Reads"
+              icon={CircleStackIcon}
+              iconColor="text-amber-400"
+              items={readsFrom}
+              renderItem={(container, idx) => {
+                const containerId = container?.data?.id || container?.id;
+                return containerId ? <ContainerLink key={`${containerId}-${idx}`} container={container} type="reads" /> : null;
+              }}
+            />
+            <SearchableBox
+              title="Writes"
+              icon={CircleStackIcon}
+              iconColor="text-violet-400"
+              items={writesTo}
+              renderItem={(container, idx) => {
+                const containerId = container?.data?.id || container?.id;
+                return containerId ? <ContainerLink key={`${containerId}-${idx}`} container={container} type="writes" /> : null;
+              }}
+            />
+          </div>
+        )}
+      </div>
+    );
+  }
+);
+
+export const ServiceCard = memo(({ service, defaultOpen = false }: { service: any; defaultOpen?: boolean }) => {
+  const data = service?.data || service;
+  const [isCollapsed, setIsCollapsed] = useState(!defaultOpen);
+
+  if (!data?.id) return null;
+
+  const receives = data.receives || [];
+  const sends = data.sends || [];
+  const readsFrom = data.readsFrom || [];
+  const writesTo = data.writesTo || [];
+  const specifications = getServiceSpecifications(data);
+  const hasMessages = receives.length > 0 || sends.length > 0;
+  const hasContainers = readsFrom.length > 0 || writesTo.length > 0;
+  const hasSpecs = specifications.length > 0;
+  const hasContent = hasMessages || hasContainers;
+
+  return (
+    <div className="bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-xl shadow-xs hover:shadow-md transition-shadow">
+      {/* Service Header */}
+      <div
+        onClick={() => hasContent && setIsCollapsed(!isCollapsed)}
+        className={`flex items-center justify-between px-4 py-3 ${hasContent ? 'cursor-pointer hover:bg-[rgb(var(--ec-content-hover))]' : ''} transition-colors`}
+      >
+        <div className="flex items-center gap-2.5">
+          <div className="flex items-center justify-center w-8 h-8 bg-pink-100 dark:bg-pink-500/20 rounded-lg">
+            <ServerIcon className="h-4 w-4 text-pink-600 dark:text-pink-400" />
+          </div>
+          <div>
+            <div className="flex items-center gap-2">
+              <span className="font-semibold text-[rgb(var(--ec-page-text))]">{data.name || data.id}</span>
+              <span className="text-[11px] text-[rgb(var(--ec-page-text-muted))] font-medium bg-[rgb(var(--ec-content-hover))] px-1.5 py-0.5 rounded">
+                v{data.version}
+              </span>
+            </div>
+            {data.summary && (
+              <p className="text-xs text-[rgb(var(--ec-page-text-muted))] line-clamp-1 mt-0.5 max-w-md">{data.summary}</p>
+            )}
+          </div>
+        </div>
+        <div className="flex items-center gap-2">
+          {/* Specs in header - always visible */}
+          {hasSpecs && (
+            <div className="flex items-center gap-1.5">
+              {specifications.map((spec: any, idx: number) => (
+                <a
+                  key={`${spec.type}-${idx}`}
+                  href={getSpecUrl(spec, data.id, data.version)}
+                  onClick={(e) => e.stopPropagation()}
+                  className="flex items-center gap-1 px-2 py-1 bg-[rgb(var(--ec-content-hover))] hover:bg-[rgb(var(--ec-sidebar-hover-bg))] rounded text-xs text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                  title={getSpecLabel(spec.type)}
+                >
+                  <img src={buildUrl(`/icons/${getSpecIcon(spec.type)}.svg`, true)} alt="" className="h-3.5 w-3.5" />
+                  <span className="hidden sm:inline">{getSpecLabel(spec.type)}</span>
+                </a>
+              ))}
+            </div>
+          )}
+          {hasContent && (
+            <div className="p-1.5 text-[rgb(var(--ec-icon-color))]">
+              {isCollapsed ? <ChevronDownIcon className="h-4 w-4" /> : <ChevronUpIcon className="h-4 w-4" />}
+            </div>
+          )}
+          <a
+            href={buildUrl(`/architecture/services/${data.id}/${data.version}`)}
+            onClick={(e) => e.stopPropagation()}
+            className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-pink-500 hover:bg-pink-500/10 rounded-lg transition-colors"
+            title="View service architecture"
+          >
+            <ArrowTopRightOnSquareIcon className="h-4 w-4" />
+          </a>
+        </div>
+      </div>
+
+      {/* Expanded Content - Compact Flow */}
+      {!isCollapsed && hasContent && (
+        <ServiceExpandedContent receives={receives} sends={sends} readsFrom={readsFrom} writesTo={writesTo} />
+      )}
+    </div>
+  );
+});
+
+const DataProductCard = memo(({ dataProduct }: { dataProduct: any }) => {
+  const data = dataProduct?.data || dataProduct;
+
+  if (!data?.id) return null;
+
+  const href = buildUrl(`/docs/data-products/${data.id}/${data.version}`);
+
+  return (
+    <a
+      href={href}
+      className="block bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-xl shadow-xs hover:shadow-md hover:border-[rgb(var(--ec-accent)/0.5)] transition-all"
+    >
+      <div className="flex items-center justify-between px-4 py-3">
+        <div className="flex items-center gap-2.5">
+          <div className="flex items-center justify-center w-8 h-8 bg-purple-100 dark:bg-purple-500/20 rounded-lg">
+            <CubeIcon className="h-4 w-4 text-purple-600 dark:text-purple-400" />
+          </div>
+          <div>
+            <div className="flex items-center gap-2">
+              <span className="font-semibold text-[rgb(var(--ec-page-text))]">{data.name || data.id}</span>
+              <span className="text-[11px] text-[rgb(var(--ec-page-text-muted))] font-medium bg-[rgb(var(--ec-content-hover))] px-1.5 py-0.5 rounded">
+                v{data.version}
+              </span>
+            </div>
+            {data.summary && (
+              <p className="text-xs text-[rgb(var(--ec-page-text-muted))] line-clamp-1 mt-0.5 max-w-md">{data.summary}</p>
+            )}
+          </div>
+        </div>
+        <div className="p-1.5 text-[rgb(var(--ec-icon-color))]">
+          <ArrowTopRightOnSquareIcon className="h-4 w-4" />
+        </div>
+      </div>
+    </a>
+  );
+});
+
+const SubdomainSection = memo(({ subdomain, defaultOpen = false }: { subdomain: any; defaultOpen?: boolean }) => {
+  const data = subdomain?.data || subdomain;
+  const [isCollapsed, setIsCollapsed] = useState(!defaultOpen);
+
+  if (!data?.id) return null;
+
+  const services = data.services || [];
+  const entities = data.entities || [];
+  const dataProducts = data['data-products'] || [];
+
+  return (
+    <div className="bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-xl overflow-hidden shadow-xs">
+      {/* Subdomain Header - Clickable */}
+      <div
+        onClick={() => setIsCollapsed(!isCollapsed)}
+        className={`flex items-center justify-between px-5 py-4 cursor-pointer hover:bg-[rgb(var(--ec-content-hover))] transition-colors ${!isCollapsed ? 'border-b border-[rgb(var(--ec-page-border))]' : ''}`}
+      >
+        <div className="flex items-center gap-3">
+          <div className="flex items-center justify-center w-9 h-9 bg-orange-100 dark:bg-orange-500/20 rounded-lg">
+            <RectangleGroupIcon className="h-5 w-5 text-orange-600 dark:text-orange-400" />
+          </div>
+          <div>
+            <div className="flex items-center gap-2">
+              <h3 className="text-base font-semibold text-[rgb(var(--ec-page-text))]">{data.name || data.id}</h3>
+              <span className="text-[11px] text-[rgb(var(--ec-page-text-muted))] font-medium bg-[rgb(var(--ec-content-hover))] px-1.5 py-0.5 rounded border border-[rgb(var(--ec-page-border))]">
+                v{data.version}
+              </span>
+              {/* Show counts when collapsed */}
+              {isCollapsed && (services.length > 0 || entities.length > 0 || dataProducts.length > 0) && (
+                <span className="text-[11px] text-[rgb(var(--ec-icon-color))] ml-1">
+                  {services.length > 0 && `${services.length} service${services.length > 1 ? 's' : ''}`}
+                  {services.length > 0 && (entities.length > 0 || dataProducts.length > 0) && ', '}
+                  {entities.length > 0 && `${entities.length} entit${entities.length > 1 ? 'ies' : 'y'}`}
+                  {entities.length > 0 && dataProducts.length > 0 && ', '}
+                  {dataProducts.length > 0 && `${dataProducts.length} data product${dataProducts.length > 1 ? 's' : ''}`}
+                </span>
+              )}
+            </div>
+            <span className="text-[11px] text-[rgb(var(--ec-page-text-muted))] font-medium">Subdomain</span>
+          </div>
+        </div>
+        <div className="flex items-center gap-1">
+          <div className="p-2 text-[rgb(var(--ec-icon-color))]">
+            {isCollapsed ? <ChevronDownIcon className="h-5 w-5" /> : <ChevronUpIcon className="h-5 w-5" />}
+          </div>
+          <a
+            href={buildUrl(`/architecture/domains/${data.id}/${data.version}`)}
+            onClick={(e) => e.stopPropagation()}
+            className="p-2 text-[rgb(var(--ec-icon-color))] hover:text-orange-500 hover:bg-orange-500/10 rounded-lg transition-colors"
+            title="View subdomain architecture"
+          >
+            <ArrowTopRightOnSquareIcon className="h-5 w-5" />
+          </a>
+        </div>
+      </div>
+
+      {!isCollapsed && (
+        <div className="p-5 space-y-5">
+          {/* Subdomain Entities */}
+          {entities.length > 0 && (
+            <div>
+              <div className="flex items-center gap-2 mb-3">
+                <BoxIcon className="h-4 w-4 text-[rgb(var(--ec-accent))]" />
+                <h4 className="text-sm font-semibold text-[rgb(var(--ec-page-text))]">Entities</h4>
+                <span className="text-xs text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2 py-0.5 rounded-full font-medium">
+                  {entities.length}
+                </span>
+              </div>
+              <div className="flex flex-wrap gap-2">
+                {entities.map((entity: any) => {
+                  const entityId = entity?.data?.id || entity?.id;
+                  return entityId ? <EntityBadge key={entityId} entity={entity} /> : null;
+                })}
+              </div>
+            </div>
+          )}
+
+          {/* Subdomain Services */}
+          {services.length > 0 && (
+            <div>
+              <div className="flex items-center gap-2 mb-3">
+                <ServerIcon className="h-4 w-4 text-pink-600 dark:text-pink-400" />
+                <h4 className="text-sm font-semibold text-[rgb(var(--ec-page-text))]">Services</h4>
+                <span className="text-xs text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2 py-0.5 rounded-full font-medium">
+                  {services.length}
+                </span>
+              </div>
+              <div className="space-y-3">
+                {services.map((service: any) => {
+                  const serviceId = service?.data?.id || service?.id;
+                  return serviceId ? <ServiceCard key={serviceId} service={service} /> : null;
+                })}
+              </div>
+            </div>
+          )}
+
+          {/* Subdomain Data Products */}
+          {dataProducts.length > 0 && (
+            <div>
+              <div className="flex items-center gap-2 mb-3">
+                <CubeIcon className="h-4 w-4 text-purple-600 dark:text-purple-400" />
+                <h4 className="text-sm font-semibold text-[rgb(var(--ec-page-text))]">Data Products</h4>
+                <span className="text-xs text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2 py-0.5 rounded-full font-medium">
+                  {dataProducts.length}
+                </span>
+              </div>
+              <div className="space-y-3">
+                {dataProducts.map((dataProduct: any) => {
+                  const dataProductId = dataProduct?.data?.id || dataProduct?.id;
+                  return dataProductId ? <DataProductCard key={dataProductId} dataProduct={dataProduct} /> : null;
+                })}
+              </div>
+            </div>
+          )}
+
+          {entities.length === 0 && services.length === 0 && dataProducts.length === 0 && (
+            <p className="text-sm text-[rgb(var(--ec-icon-color))] italic text-center py-4">
+              No entities, services, or data products in this subdomain
+            </p>
+          )}
+        </div>
+      )}
+    </div>
+  );
+});
+
+const SystemSection = memo(({ system, defaultOpen = false }: { system: any; defaultOpen?: boolean }) => {
+  const data = system?.data || system;
+  const [isCollapsed, setIsCollapsed] = useState(!defaultOpen);
+
+  if (!data?.id) return null;
+
+  const services = data.services || [];
+  const containers = data.containers || [];
+
+  return (
+    <div className="bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-xl overflow-hidden shadow-xs">
+      {/* System Header - Clickable */}
+      <div
+        onClick={() => setIsCollapsed(!isCollapsed)}
+        className={`flex items-center justify-between px-5 py-4 cursor-pointer hover:bg-[rgb(var(--ec-content-hover))] transition-colors ${!isCollapsed ? 'border-b border-[rgb(var(--ec-page-border))]' : ''}`}
+      >
+        <div className="flex items-center gap-3">
+          <div className="flex items-center justify-center w-9 h-9 bg-violet-100 dark:bg-violet-500/20 rounded-lg">
+            <GroupIcon className="h-5 w-5 text-violet-600 dark:text-violet-400" />
+          </div>
+          <div>
+            <div className="flex items-center gap-2">
+              <h3 className="text-base font-semibold text-[rgb(var(--ec-page-text))]">{data.name || data.id}</h3>
+              <span className="text-[11px] text-[rgb(var(--ec-page-text-muted))] font-medium bg-[rgb(var(--ec-content-hover))] px-1.5 py-0.5 rounded border border-[rgb(var(--ec-page-border))]">
+                v{data.version}
+              </span>
+              {/* Show counts when collapsed */}
+              {isCollapsed && (services.length > 0 || containers.length > 0) && (
+                <span className="text-[11px] text-[rgb(var(--ec-icon-color))] ml-1">
+                  {[
+                    services.length > 0 && `${services.length} service${services.length > 1 ? 's' : ''}`,
+                    containers.length > 0 && `${containers.length} data store${containers.length > 1 ? 's' : ''}`,
+                  ]
+                    .filter(Boolean)
+                    .join(' · ')}
+                </span>
+              )}
+            </div>
+            <span className="text-[11px] text-[rgb(var(--ec-page-text-muted))] font-medium">System</span>
+          </div>
+        </div>
+        <div className="flex items-center gap-1">
+          <div className="p-2 text-[rgb(var(--ec-icon-color))]">
+            {isCollapsed ? <ChevronDownIcon className="h-5 w-5" /> : <ChevronUpIcon className="h-5 w-5" />}
+          </div>
+          <a
+            href={buildUrl(`/visualiser/systems/${data.id}/${data.version}`)}
+            onClick={(e) => e.stopPropagation()}
+            className="p-2 text-[rgb(var(--ec-icon-color))] hover:text-violet-500 hover:bg-violet-500/10 rounded-lg transition-colors"
+            title="View system map"
+          >
+            <ArrowTopRightOnSquareIcon className="h-5 w-5" />
+          </a>
+        </div>
+      </div>
+
+      {!isCollapsed && (
+        <div className="p-5 space-y-5">
+          {services.length > 0 && (
+            <div>
+              <div className="flex items-center gap-2 mb-3">
+                <ServerIcon className="h-4 w-4 text-pink-600 dark:text-pink-400" />
+                <h4 className="text-sm font-semibold text-[rgb(var(--ec-page-text))]">Services</h4>
+                <span className="text-xs text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2 py-0.5 rounded-full font-medium">
+                  {services.length}
+                </span>
+              </div>
+              <div className="space-y-3">
+                {services.map((service: any) => {
+                  const serviceId = service?.data?.id || service?.id;
+                  return serviceId ? <ServiceCard key={serviceId} service={service} /> : null;
+                })}
+              </div>
+            </div>
+          )}
+
+          {containers.length > 0 && (
+            <div>
+              <div className="flex items-center gap-2 mb-3">
+                <CircleStackIcon className="h-4 w-4 text-amber-500" />
+                <h4 className="text-sm font-semibold text-[rgb(var(--ec-page-text))]">Data Stores</h4>
+                <span className="text-xs text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2 py-0.5 rounded-full font-medium">
+                  {containers.length}
+                </span>
+              </div>
+              <div className="flex flex-wrap gap-2">
+                {containers.map((container: any) => {
+                  const containerId = container?.data?.id || container?.id;
+                  return containerId ? <DataStoreLink key={containerId} container={container} /> : null;
+                })}
+              </div>
+            </div>
+          )}
+
+          {services.length === 0 && containers.length === 0 && (
+            <p className="text-sm text-[rgb(var(--ec-icon-color))] italic text-center py-4">Nothing in this system yet</p>
+          )}
+        </div>
+      )}
+    </div>
+  );
+});
+
+// ============================================
+// Main Component
+// ============================================
+
+export default function DomainGrid({ domain }: DomainGridProps) {
+  const data = domain?.data;
+  if (!data) return <div className="text-[rgb(var(--ec-page-text-muted))]">No domain data</div>;
+
+  const subdomains = data.domains || [];
+  const systems = data.systems || [];
+  const entities = data.entities || [];
+  const services = data.services || [];
+  const dataProducts = data['data-products'] || [];
+
+  // Get services that are NOT in any subdomain
+  const subdomainServiceIds = useMemo(
+    () =>
+      new Set(
+        subdomains.flatMap((sd: any) => {
+          const sdData = sd?.data || sd;
+          return (sdData?.services || []).map((s: any) => s?.data?.id || s?.id);
+        })
+      ),
+    [subdomains]
+  );
+
+  // Get data products that are NOT in any subdomain
+  const subdomainDataProductIds = useMemo(
+    () =>
+      new Set(
+        subdomains.flatMap((sd: any) => {
+          const sdData = sd?.data || sd;
+          return (sdData?.['data-products'] || []).map((dp: any) => dp?.data?.id || dp?.id);
+        })
+      ),
+    [subdomains]
+  );
+
+  const topLevelServices = useMemo(
+    () =>
+      services.filter((s: any) => {
+        const sId = s?.data?.id || s?.id;
+        return sId && !subdomainServiceIds.has(sId);
+      }),
+    [services, subdomainServiceIds]
+  );
+
+  // Split top-level services into internal services and external integrations
+  // (mirrors the sidebar, where externalSystem services live under "External Integrations")
+  const topLevelInternalServices = useMemo(
+    () => topLevelServices.filter((s: any) => !(s?.data || s)?.externalSystem),
+    [topLevelServices]
+  );
+
+  const topLevelExternalServices = useMemo(
+    () => topLevelServices.filter((s: any) => (s?.data || s)?.externalSystem),
+    [topLevelServices]
+  );
+
+  const topLevelDataProducts = useMemo(
+    () =>
+      dataProducts.filter((dp: any) => {
+        const dpId = dp?.data?.id || dp?.id;
+        return dpId && !subdomainDataProductIds.has(dpId);
+      }),
+    [dataProducts, subdomainDataProductIds]
+  );
+
+  return (
+    <div className="w-full">
+      {/* Domain Header - Doc style */}
+      <div className="border-b border-[rgb(var(--ec-page-border))] md:pb-4">
+        <div className="flex items-start justify-between">
+          <div>
+            <h2 className="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{data.name || data.id}</h2>
+            {data.summary && <p className="text-lg pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{data.summary}</p>}
+          </div>
+        </div>
+      </div>
+
+      {/* Domain Content */}
+      <div className="py-4 space-y-8">
+        {/* Domain Entities */}
+        {entities.length > 0 && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <BoxIcon className="h-5 w-5 text-[rgb(var(--ec-accent))]" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">Entities</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {entities.length}
+              </span>
+            </div>
+            <div className="flex flex-wrap gap-2">
+              {entities.map((entity: any) => {
+                const entityId = entity?.data?.id || entity?.id;
+                return entityId ? <EntityBadge key={entityId} entity={entity} /> : null;
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Subdomains */}
+        {subdomains.length > 0 && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <RectangleGroupIcon className="h-5 w-5 text-orange-600 dark:text-orange-400" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">Subdomains</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {subdomains.length}
+              </span>
+            </div>
+            <div className="space-y-4">
+              {subdomains.map((subdomain: any) => {
+                const subdomainId = subdomain?.data?.id || subdomain?.id;
+                return subdomainId ? <SubdomainSection key={subdomainId} subdomain={subdomain} defaultOpen /> : null;
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Systems */}
+        {systems.length > 0 && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <GroupIcon className="h-5 w-5 text-violet-600 dark:text-violet-400" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">Systems</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {systems.length}
+              </span>
+            </div>
+            <div className="space-y-4">
+              {systems.map((system: any) => {
+                const systemId = system?.data?.id || system?.id;
+                return systemId ? <SystemSection key={systemId} system={system} defaultOpen /> : null;
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Top-level Services */}
+        {topLevelInternalServices.length > 0 && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <ServerIcon className="h-5 w-5 text-pink-600 dark:text-pink-400" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">Services</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {topLevelInternalServices.length}
+              </span>
+            </div>
+            <div className="space-y-3">
+              {topLevelInternalServices.map((service: any) => {
+                const serviceId = service?.data?.id || service?.id;
+                return serviceId ? <ServiceCard key={serviceId} service={service} defaultOpen /> : null;
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* External Integrations (external systems) */}
+        {topLevelExternalServices.length > 0 && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <GlobeAltIcon className="h-5 w-5 text-sky-600 dark:text-sky-400" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">External Integrations</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {topLevelExternalServices.length}
+              </span>
+            </div>
+            <div className="space-y-3">
+              {topLevelExternalServices.map((service: any) => {
+                const serviceId = service?.data?.id || service?.id;
+                return serviceId ? <ServiceCard key={serviceId} service={service} defaultOpen /> : null;
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Top-level Data Products */}
+        {topLevelDataProducts.length > 0 && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <CubeIcon className="h-5 w-5 text-purple-600 dark:text-purple-400" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">Data Products</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {topLevelDataProducts.length}
+              </span>
+            </div>
+            <div className="space-y-3">
+              {topLevelDataProducts.map((dataProduct: any) => {
+                const dataProductId = dataProduct?.data?.id || dataProduct?.id;
+                return dataProductId ? <DataProductCard key={dataProductId} dataProduct={dataProduct} /> : null;
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Empty state */}
+        {entities.length === 0 &&
+          services.length === 0 &&
+          dataProducts.length === 0 &&
+          subdomains.length === 0 &&
+          systems.length === 0 && (
+            <div className="text-center py-12">
+              <div className="flex items-center justify-center w-16 h-16 mx-auto mb-4 bg-[rgb(var(--ec-content-hover))] rounded-2xl">
+                <RectangleGroupIcon className="h-8 w-8 text-[rgb(var(--ec-icon-color))]" />
+              </div>
+              <p className="text-[rgb(var(--ec-page-text-muted))]">
+                This domain has no entities, services, data products, subdomains, or systems defined.
+              </p>
+            </div>
+          )}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/Grids/MessageGrid.tsx b/packages/core/eventcatalog/src/components/Grids/MessageGrid.tsx
new file mode 100644
index 000000000..de8279963
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Grids/MessageGrid.tsx
@@ -0,0 +1,344 @@
+import { memo, useState } from 'react';
+import {
+  ServerIcon,
+  CircleStackIcon,
+  ArrowLongRightIcon,
+  BoltIcon,
+  ChatBubbleLeftIcon,
+  MagnifyingGlassIcon,
+  ChevronDownIcon,
+  ChevronUpIcon,
+} from '@heroicons/react/24/outline';
+import { buildUrl } from '@utils/url-builder';
+import type { CollectionEntry } from 'astro:content';
+import { getSpecUrl, getSpecIcon, getSpecLabel, getSpecColor, type Specification } from './specification-utils';
+
+interface MessageGridV2Props {
+  service: CollectionEntry<'agents'> | CollectionEntry<'services'>;
+  embeded?: boolean;
+  specifications?: Specification[];
+}
+
+// Helper to get message icon and color
+const getMessageStyle = (collection: string) => {
+  switch (collection) {
+    case 'events':
+      return { Icon: BoltIcon, color: 'orange', bg: 'bg-orange-50', border: 'border-orange-200', text: 'text-orange-600' };
+    case 'commands':
+      return { Icon: ChatBubbleLeftIcon, color: 'blue', bg: 'bg-blue-50', border: 'border-blue-200', text: 'text-blue-600' };
+    case 'queries':
+      return {
+        Icon: MagnifyingGlassIcon,
+        color: 'emerald',
+        bg: 'bg-emerald-50',
+        border: 'border-emerald-200',
+        text: 'text-emerald-600',
+      };
+    default:
+      return { Icon: BoltIcon, color: 'gray', bg: 'bg-gray-50', border: 'border-gray-200', text: 'text-gray-600' };
+  }
+};
+
+// Message Card Component
+const MessageCard = memo(({ message, compact = false }: { message: any; compact?: boolean }) => {
+  const { Icon, color } = getMessageStyle(message.collection);
+
+  return (
+    <a
+      href={buildUrl(`/docs/${message.collection}/${message.data.id}/${message.data.version}`)}
+      className={`group block bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-${color}-200 dark:border-${color}-500/30 rounded-lg shadow-xs hover:shadow-md hover:border-${color}-300 dark:hover:border-${color}-500/50 transition-all`}
+    >
+      <div className={compact ? 'p-3' : 'p-4'}>
+        <div className="flex items-center gap-2 mb-1">
+          <div className={`flex items-center justify-center w-7 h-7 bg-${color}-100 dark:bg-${color}-500/20 rounded-md`}>
+            <Icon className={`h-4 w-4 text-${color}-600 dark:text-${color}-400`} />
+          </div>
+          <h3
+            className={`font-semibold text-[rgb(var(--ec-page-text))] group-hover:text-${color}-600 dark:group-hover:text-${color}-400 transition-colors truncate ${compact ? 'text-sm' : 'text-base'}`}
+          >
+            {message.data.name}
+          </h3>
+          <span
+            className={`text-[10px] text-${color}-600 dark:text-${color}-400 font-medium bg-${color}-50 dark:bg-${color}-500/20 px-1.5 py-0.5 rounded flex-shrink-0`}
+          >
+            v{message.data.version}
+          </span>
+        </div>
+        {message.data.summary && (
+          <p className={`text-[rgb(var(--ec-page-text-muted))] line-clamp-2 ${compact ? 'text-xs mt-1' : 'text-sm mt-2'}`}>
+            {message.data.summary}
+          </p>
+        )}
+      </div>
+    </a>
+  );
+});
+
+// Container Card Component
+const ContainerCard = memo(({ container, type }: { container: any; type: 'reads' | 'writes' }) => {
+  const colorClass = type === 'reads' ? 'amber' : 'violet';
+
+  return (
+    <a
+      href={buildUrl(`/docs/containers/${container.data.id}/${container.data.version}`)}
+      className={`group block bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border rounded-lg shadow-xs hover:shadow-md transition-all ${
+        type === 'reads'
+          ? 'border-amber-200 dark:border-amber-500/30 hover:border-amber-300 dark:hover:border-amber-500/50'
+          : 'border-violet-200 dark:border-violet-500/30 hover:border-violet-300 dark:hover:border-violet-500/50'
+      }`}
+    >
+      <div className="p-3">
+        <div className="flex items-center gap-2">
+          <div
+            className={`flex items-center justify-center w-7 h-7 bg-${colorClass}-100 dark:bg-${colorClass}-500/20 rounded-md`}
+          >
+            <CircleStackIcon className={`h-4 w-4 text-${colorClass}-600 dark:text-${colorClass}-400`} />
+          </div>
+          <h3
+            className={`font-semibold text-[rgb(var(--ec-page-text))] text-sm group-hover:text-${colorClass}-600 dark:group-hover:text-${colorClass}-400 transition-colors truncate`}
+          >
+            {container.data.name}
+          </h3>
+        </div>
+        {container.data.summary && (
+          <p className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-1.5 line-clamp-2">{container.data.summary}</p>
+        )}
+      </div>
+    </a>
+  );
+});
+
+// Specification Card Component
+const SpecificationCard = memo(
+  ({ spec, serviceId, serviceVersion }: { spec: any; serviceId: string; serviceVersion: string }) => {
+    const color = getSpecColor(spec.type);
+
+    return (
+      <a
+        href={getSpecUrl(spec, serviceId, serviceVersion)}
+        className={`group flex items-center gap-3 p-3 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-${color}-200 dark:border-${color}-500/30 rounded-lg shadow-xs hover:shadow-md hover:border-${color}-300 dark:hover:border-${color}-500/50 transition-all`}
+      >
+        <img src={buildUrl(`/icons/${getSpecIcon(spec.type)}.svg`, true)} alt={`${spec.type} icon`} className="h-6 w-6" />
+        <div className="flex-1 min-w-0">
+          <h3
+            className={`font-semibold text-[rgb(var(--ec-page-text))] text-sm group-hover:text-${color}-600 dark:group-hover:text-${color}-400 transition-colors truncate`}
+          >
+            {spec.name || spec.filename}
+          </h3>
+          <p className="text-xs text-[rgb(var(--ec-page-text-muted))]">{getSpecLabel(spec.type)}</p>
+        </div>
+      </a>
+    );
+  }
+);
+
+// Collapsible Message Section Component
+const CollapsibleMessageSection = memo(
+  ({
+    icon: Icon,
+    title,
+    messages,
+    color,
+    emptyText,
+    embeded = false,
+  }: {
+    icon: any;
+    title: string;
+    messages: any[];
+    color: string;
+    emptyText: string;
+    embeded?: boolean;
+  }) => {
+    const [isCollapsed, setIsCollapsed] = useState(false);
+    const hasContent = messages.length > 0;
+
+    return (
+      <div className="bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-xl shadow-xs overflow-hidden">
+        <div
+          onClick={() => setIsCollapsed(!isCollapsed)}
+          className={`flex items-center justify-between px-5 py-4 cursor-pointer hover:bg-[rgb(var(--ec-content-hover))] transition-colors ${!isCollapsed && hasContent ? 'border-b border-[rgb(var(--ec-page-border))]' : ''}`}
+        >
+          <div className="flex items-center gap-3">
+            <div className={`flex items-center justify-center w-8 h-8 bg-${color}-100 dark:bg-${color}-500/20 rounded-lg`}>
+              <Icon className={`h-4 w-4 text-${color}-600 dark:text-${color}-400`} />
+            </div>
+            <h2 className="text-base font-bold text-[rgb(var(--ec-page-text))]">{title}</h2>
+            <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2 py-0.5 rounded-full font-medium">
+              {messages.length}
+            </span>
+          </div>
+          <div className="text-[rgb(var(--ec-icon-color))]">
+            {isCollapsed ? <ChevronDownIcon className="h-5 w-5" /> : <ChevronUpIcon className="h-5 w-5" />}
+          </div>
+        </div>
+        {!isCollapsed && (
+          <div className="p-5">
+            {hasContent ? (
+              <div className="space-y-3">
+                {messages.map((message: any) => (
+                  <MessageCard key={`${message.data.id}-${message.data.version}`} message={message} compact={embeded} />
+                ))}
+              </div>
+            ) : (
+              <div className="text-center py-4">
+                <p className="text-sm text-[rgb(var(--ec-icon-color))]">{emptyText}</p>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    );
+  }
+);
+
+// Collapsible Container Section Component
+const CollapsibleContainerSection = memo(
+  ({ title, containers, color, type }: { title: string; containers: any[]; color: string; type: 'reads' | 'writes' }) => {
+    const [isCollapsed, setIsCollapsed] = useState(false);
+
+    return (
+      <div className="bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-xl shadow-xs overflow-hidden">
+        <div
+          onClick={() => setIsCollapsed(!isCollapsed)}
+          className={`flex items-center justify-between px-5 py-4 cursor-pointer hover:bg-[rgb(var(--ec-content-hover))] transition-colors ${!isCollapsed ? 'border-b border-[rgb(var(--ec-page-border))]' : ''}`}
+        >
+          <div className="flex items-center gap-3">
+            <div className={`flex items-center justify-center w-8 h-8 bg-${color}-100 dark:bg-${color}-500/20 rounded-lg`}>
+              <CircleStackIcon className={`h-4 w-4 text-${color}-600 dark:text-${color}-400`} />
+            </div>
+            <h2 className="text-base font-bold text-[rgb(var(--ec-page-text))]">{title}</h2>
+            <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2 py-0.5 rounded-full font-medium">
+              {containers.length}
+            </span>
+          </div>
+          <div className="text-[rgb(var(--ec-icon-color))]">
+            {isCollapsed ? <ChevronDownIcon className="h-5 w-5" /> : <ChevronUpIcon className="h-5 w-5" />}
+          </div>
+        </div>
+        {!isCollapsed && (
+          <div className="p-5">
+            <div className="space-y-3">
+              {containers.map((container: any) => (
+                <ContainerCard key={container.data.id} container={container} type={type} />
+              ))}
+            </div>
+          </div>
+        )}
+      </div>
+    );
+  }
+);
+
+export default function MessageGridV2({ service, embeded = false, specifications = [] }: MessageGridV2Props) {
+  const { sends = [], receives = [], writesTo = [], readsFrom = [] } = service.data;
+  const collection = service.collection || 'services';
+  const resourceLabel = collection === 'agents' ? 'agent' : 'service';
+  const hasContainers = readsFrom.length > 0 || writesTo.length > 0;
+  const hasMessages = receives.length > 0 || sends.length > 0;
+  const hasSpecs = specifications.length > 0;
+
+  return (
+    <div className="w-full">
+      {/* Resource Header - Doc style */}
+      <div className="border-b border-[rgb(var(--ec-page-border))] md:pb-4">
+        <div className="flex items-start justify-between">
+          <div>
+            <h2 className="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{service.data.name}</h2>
+            {service.data.summary && (
+              <p className="text-lg pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{service.data.summary}</p>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/* Service Content */}
+      <div className="py-4 space-y-8">
+        {/* Specifications */}
+        {hasSpecs && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">Specifications</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {specifications.length}
+              </span>
+            </div>
+            <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-3">
+              {specifications.map((spec: any) => (
+                <SpecificationCard
+                  key={`${spec.type}-${spec.filename}`}
+                  spec={spec}
+                  serviceId={service.data.id}
+                  serviceVersion={service.data.version}
+                />
+              ))}
+            </div>
+          </div>
+        )}
+
+        {/* Message Flow - Two columns side by side */}
+        {hasMessages && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <BoltIcon className="h-5 w-5 text-orange-500 dark:text-orange-400" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">Messages</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {receives.length + sends.length}
+              </span>
+            </div>
+            <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+              <CollapsibleMessageSection
+                icon={ArrowLongRightIcon}
+                title="Receives"
+                messages={receives}
+                color="blue"
+                emptyText="No messages received"
+                embeded={embeded}
+              />
+              <CollapsibleMessageSection
+                icon={ArrowLongRightIcon}
+                title="Sends"
+                messages={sends}
+                color="emerald"
+                emptyText="No messages sent"
+                embeded={embeded}
+              />
+            </div>
+          </div>
+        )}
+
+        {/* Container Relationships */}
+        {hasContainers && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <CircleStackIcon className="h-5 w-5 text-amber-500 dark:text-amber-400" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">Data Sources</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {readsFrom.length + writesTo.length}
+              </span>
+            </div>
+            <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+              {readsFrom.length > 0 && (
+                <CollapsibleContainerSection title="Reads from" containers={readsFrom} color="amber" type="reads" />
+              )}
+              {writesTo.length > 0 && (
+                <CollapsibleContainerSection title="Writes to" containers={writesTo} color="violet" type="writes" />
+              )}
+            </div>
+          </div>
+        )}
+
+        {/* Empty State */}
+        {!hasMessages && !hasContainers && !hasSpecs && (
+          <div className="text-center py-12">
+            <div className="flex items-center justify-center w-16 h-16 mx-auto mb-4 bg-[rgb(var(--ec-content-hover))] rounded-2xl">
+              <ServerIcon className="h-8 w-8 text-[rgb(var(--ec-icon-color))]" />
+            </div>
+            <p className="text-[rgb(var(--ec-page-text-muted))]">
+              This {resourceLabel} has no message flows or container relationships defined.
+            </p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/Grids/SystemGrid.tsx b/packages/core/eventcatalog/src/components/Grids/SystemGrid.tsx
new file mode 100644
index 000000000..1f5cbcf21
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Grids/SystemGrid.tsx
@@ -0,0 +1,185 @@
+import { useMemo } from 'react';
+import { ServerIcon, GlobeAltIcon, CircleStackIcon } from '@heroicons/react/24/outline';
+import { buildUrl } from '@utils/url-builder';
+import { BoxIcon, Group as GroupIcon, Waypoints, Database as DatabaseIcon } from 'lucide-react';
+import { ServiceCard, EntityBadge } from './DomainGrid';
+
+interface SystemGridProps {
+  system: any;
+}
+
+const FlowLink = ({ flow }: { flow: any }) => {
+  const data = flow?.data || flow;
+  const id = data?.id || flow?.id;
+  const name = data?.name || id;
+  const version = data?.version || 'latest';
+
+  return (
+    <a
+      href={buildUrl(`/docs/flows/${id}/${version}`)}
+      className="inline-flex items-center gap-2 px-3 py-2 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-lg text-sm font-medium text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] hover:border-[rgb(var(--ec-accent)/0.5)] transition-all shadow-xs"
+    >
+      <Waypoints className="h-4 w-4 text-[rgb(var(--ec-accent))]" />
+      <span>{name}</span>
+      <span className="text-xs text-[rgb(var(--ec-icon-color))]">v{version}</span>
+    </a>
+  );
+};
+
+const DataStoreLink = ({ container }: { container: any }) => {
+  const data = container?.data || container;
+  const id = data?.id || container?.id;
+  const name = data?.name || id;
+  const version = data?.version || 'latest';
+  const technology = data?.technology;
+
+  return (
+    <a
+      href={buildUrl(`/docs/containers/${id}/${version}`)}
+      className="inline-flex items-center gap-2 px-3 py-2 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-lg text-sm font-medium text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] hover:border-[rgb(var(--ec-accent)/0.5)] transition-all shadow-xs"
+    >
+      <CircleStackIcon className="h-4 w-4 text-amber-500" />
+      <span>{name}</span>
+      {technology && <span className="text-xs text-[rgb(var(--ec-icon-color))]">{technology}</span>}
+    </a>
+  );
+};
+
+export default function SystemGrid({ system }: SystemGridProps) {
+  const data = system?.data;
+  if (!data) return <div className="text-[rgb(var(--ec-page-text-muted))]">No system data</div>;
+
+  const entities = data.entities || [];
+  const services = data.services || [];
+  const flows = data.flows || [];
+  const containers = data.containers || [];
+
+  // Split services into internal services and external integrations
+  // (mirrors the sidebar, where externalSystem services live under "External Integrations")
+  const internalServices = useMemo(() => services.filter((s: any) => !(s?.data || s)?.externalSystem), [services]);
+  const externalServices = useMemo(() => services.filter((s: any) => (s?.data || s)?.externalSystem), [services]);
+
+  return (
+    <div className="w-full">
+      {/* System Header - Doc style */}
+      <div className="border-b border-[rgb(var(--ec-page-border))] md:pb-4">
+        <div className="flex items-start justify-between">
+          <div>
+            <h2 className="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{data.name || data.id}</h2>
+            {data.summary && <p className="text-lg pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{data.summary}</p>}
+          </div>
+        </div>
+      </div>
+
+      {/* System Content */}
+      <div className="py-4 space-y-8">
+        {/* System Entities */}
+        {entities.length > 0 && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <BoxIcon className="h-5 w-5 text-[rgb(var(--ec-accent))]" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">Entities</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {entities.length}
+              </span>
+            </div>
+            <div className="flex flex-wrap gap-2">
+              {entities.map((entity: any) => {
+                const entityId = entity?.data?.id || entity?.id;
+                return entityId ? <EntityBadge key={entityId} entity={entity} /> : null;
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Services */}
+        {internalServices.length > 0 && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <ServerIcon className="h-5 w-5 text-pink-600 dark:text-pink-400" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">Services</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {internalServices.length}
+              </span>
+            </div>
+            <div className="space-y-3">
+              {internalServices.map((service: any) => {
+                const serviceId = service?.data?.id || service?.id;
+                return serviceId ? <ServiceCard key={serviceId} service={service} /> : null;
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* External Integrations (external systems) */}
+        {externalServices.length > 0 && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <GlobeAltIcon className="h-5 w-5 text-sky-600 dark:text-sky-400" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">External Integrations</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {externalServices.length}
+              </span>
+            </div>
+            <div className="space-y-3">
+              {externalServices.map((service: any) => {
+                const serviceId = service?.data?.id || service?.id;
+                return serviceId ? <ServiceCard key={serviceId} service={service} /> : null;
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Data Stores (containers) */}
+        {containers.length > 0 && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <DatabaseIcon className="h-5 w-5 text-amber-500" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">Data Stores</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {containers.length}
+              </span>
+            </div>
+            <div className="flex flex-wrap gap-2">
+              {containers.map((container: any) => {
+                const containerId = container?.data?.id || container?.id;
+                return containerId ? <DataStoreLink key={containerId} container={container} /> : null;
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Flows */}
+        {flows.length > 0 && (
+          <div>
+            <div className="flex items-center gap-2 mb-4">
+              <Waypoints className="h-5 w-5 text-[rgb(var(--ec-accent))]" />
+              <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">Flows</h3>
+              <span className="text-sm text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-0.5 rounded-full font-medium">
+                {flows.length}
+              </span>
+            </div>
+            <div className="flex flex-wrap gap-2">
+              {flows.map((flow: any) => {
+                const flowId = flow?.data?.id || flow?.id;
+                return flowId ? <FlowLink key={flowId} flow={flow} /> : null;
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Empty state */}
+        {entities.length === 0 && services.length === 0 && flows.length === 0 && containers.length === 0 && (
+          <div className="text-center py-12">
+            <div className="flex items-center justify-center w-16 h-16 mx-auto mb-4 bg-[rgb(var(--ec-content-hover))] rounded-2xl">
+              <GroupIcon className="h-8 w-8 text-[rgb(var(--ec-icon-color))]" />
+            </div>
+            <p className="text-[rgb(var(--ec-page-text-muted))]">
+              This system has no entities, services, data stores, or flows defined.
+            </p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/Grids/components.tsx b/packages/core/eventcatalog/src/components/Grids/components.tsx
new file mode 100644
index 000000000..8879b481a
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Grids/components.tsx
@@ -0,0 +1,170 @@
+import React from 'react';
+import {
+  MagnifyingGlassIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  ChevronDoubleLeftIcon,
+  ChevronDoubleRightIcon,
+} from '@heroicons/react/24/outline';
+import type { CollectionMessageTypes } from '@types';
+import { getCollectionStyles, type PaginationProps, type SearchBarProps, type TypeFilterProps } from './utils';
+
+export function SearchBar({ searchQuery, onSearchChange, placeholder, totalResults, totalItems }: SearchBarProps) {
+  return (
+    <div className="w-full md:w-96">
+      <div className="relative">
+        <div className="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
+          <MagnifyingGlassIcon className="h-5 w-5 text-gray-400" aria-hidden="true" />
+        </div>
+        <input
+          type="text"
+          placeholder={placeholder || 'Search...'}
+          value={searchQuery}
+          onChange={(e) => onSearchChange(e.target.value)}
+          className="block w-full rounded-lg border-0 py-2.5 pl-10 pr-4 text-gray-900 shadow-xs ring-1 ring-inset ring-gray-300 placeholder:text-gray-400 focus:ring-2 focus:ring-inset focus:ring-primary sm:text-sm sm:leading-6"
+        />
+        {searchQuery && (
+          <div className="absolute inset-y-0 right-0 flex items-center pr-3">
+            <button onClick={() => onSearchChange('')} className="text-gray-400 hover:text-gray-500 focus:outline-hidden">
+              <span className="sr-only">Clear search</span>
+              <svg className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor">
+                <path
+                  fillRule="evenodd"
+                  d="M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z"
+                  clipRule="evenodd"
+                />
+              </svg>
+            </button>
+          </div>
+        )}
+      </div>
+      {searchQuery && totalResults !== undefined && totalItems !== undefined && (
+        <div className="mt-2 text-sm text-gray-500 flex items-center justify-between">
+          <span>
+            Found <span className="font-medium text-gray-900">{totalResults}</span> of{' '}
+            <span className="font-medium text-gray-900">{totalItems}</span>
+          </span>
+          <span className="text-gray-400 text-xs">ESC to clear</span>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function TypeFilters({ selectedTypes, onTypeChange, filteredCount, totalCount }: TypeFilterProps) {
+  const types: CollectionMessageTypes[] = ['events', 'commands', 'queries'];
+
+  return (
+    <div className="flex items-center gap-2">
+      {types.map((type) => {
+        const { color, Icon } = getCollectionStyles(type);
+        const isSelected = selectedTypes.includes(type);
+        return (
+          <button
+            key={type}
+            onClick={() => {
+              onTypeChange(selectedTypes.includes(type) ? selectedTypes.filter((t) => t !== type) : [...selectedTypes, type]);
+            }}
+            className={`
+                            inline-flex items-center gap-2 px-3 py-1.5 rounded-md text-sm font-medium
+                            transition-colors duration-200
+                            ${
+                              isSelected
+                                ? `bg-${color}-100 text-${color}-700 ring-2 ring-${color}-500`
+                                : 'bg-gray-50 text-gray-600 hover:bg-gray-100'
+                            }
+                        `}
+          >
+            <Icon className={`h-4 w-4 ${isSelected ? `text-${color}-500` : 'text-gray-400'}`} />
+            <span className="capitalize">{type}</span>
+            {isSelected && filteredCount !== undefined && (
+              <span
+                className={`inline-flex items-center justify-center px-2 py-0.5 text-xs font-medium bg-${color}-50 text-${color}-700 rounded-full`}
+              >
+                {filteredCount}
+              </span>
+            )}
+          </button>
+        );
+      })}
+      {selectedTypes.length > 0 && (
+        <button onClick={() => onTypeChange([])} className="text-xs text-gray-500 hover:text-gray-700 hover:underline">
+          Clear filters
+        </button>
+      )}
+    </div>
+  );
+}
+
+export function Pagination({ currentPage, totalPages, totalItems, itemsPerPage, onPageChange }: PaginationProps) {
+  if (totalPages <= 1) return null;
+
+  return (
+    <div className="flex items-center justify-between border-gray-200 bg-white px-4 py-3 sm:px-6">
+      <div className="flex flex-1 justify-between sm:hidden">
+        <button
+          onClick={() => onPageChange(Math.max(1, currentPage - 1))}
+          disabled={currentPage === 1}
+          className="relative inline-flex items-center rounded-md border border-gray-300 bg-white px-4 py-2 text-sm font-medium text-gray-700 hover:bg-gray-50 disabled:opacity-50"
+        >
+          Previous
+        </button>
+        <button
+          onClick={() => onPageChange(Math.min(totalPages, currentPage + 1))}
+          disabled={currentPage === totalPages}
+          className="relative ml-3 inline-flex items-center rounded-md border border-gray-300 bg-white px-4 py-2 text-sm font-medium text-gray-700 hover:bg-gray-50 disabled:opacity-50"
+        >
+          Next
+        </button>
+      </div>
+      <div className="hidden sm:flex sm:flex-1 sm:items-center sm:justify-between">
+        <div className="pr-4">
+          <p className="text-sm text-gray-700">
+            Showing <span className="font-medium">{(currentPage - 1) * itemsPerPage + 1}</span> to{' '}
+            <span className="font-medium">{Math.min(currentPage * itemsPerPage, totalItems)}</span> of{' '}
+            <span className="font-medium">{totalItems}</span> results
+          </p>
+        </div>
+        <div>
+          <nav className="isolate inline-flex -space-x-px rounded-md shadow-xs" aria-label="Pagination">
+            <button
+              onClick={() => onPageChange(1)}
+              disabled={currentPage === 1}
+              className="relative inline-flex items-center rounded-l-md px-2 py-2 text-gray-400 ring-1 ring-inset ring-gray-300 hover:bg-gray-50 focus:z-20 focus:outline-offset-0 disabled:opacity-50"
+            >
+              <span className="sr-only">First</span>
+              <ChevronDoubleLeftIcon className="h-5 w-5" aria-hidden="true" />
+            </button>
+            <button
+              onClick={() => onPageChange(Math.max(1, currentPage - 1))}
+              disabled={currentPage === 1}
+              className="relative inline-flex items-center px-2 py-2 text-gray-400 ring-1 ring-inset ring-gray-300 hover:bg-gray-50 focus:z-20 focus:outline-offset-0 disabled:opacity-50"
+            >
+              <span className="sr-only">Previous</span>
+              <ChevronLeftIcon className="h-5 w-5" aria-hidden="true" />
+            </button>
+            <span className="relative inline-flex items-center px-4 py-2 text-sm font-semibold text-gray-900 ring-1 ring-inset ring-gray-300 focus:outline-offset-0">
+              Page {currentPage} of {totalPages}
+            </span>
+            <button
+              onClick={() => onPageChange(Math.min(totalPages, currentPage + 1))}
+              disabled={currentPage === totalPages}
+              className="relative inline-flex items-center px-2 py-2 text-gray-400 ring-1 ring-inset ring-gray-300 hover:bg-gray-50 focus:z-20 focus:outline-offset-0 disabled:opacity-50"
+            >
+              <span className="sr-only">Next</span>
+              <ChevronRightIcon className="h-5 w-5" aria-hidden="true" />
+            </button>
+            <button
+              onClick={() => onPageChange(totalPages)}
+              disabled={currentPage === totalPages}
+              className="relative inline-flex items-center rounded-r-md px-2 py-2 text-gray-400 ring-1 ring-inset ring-gray-300 hover:bg-gray-50 focus:z-20 focus:outline-offset-0 disabled:opacity-50"
+            >
+              <span className="sr-only">Last</span>
+              <ChevronDoubleRightIcon className="h-5 w-5" aria-hidden="true" />
+            </button>
+          </nav>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/Grids/specification-utils.ts b/packages/core/eventcatalog/src/components/Grids/specification-utils.ts
new file mode 100644
index 000000000..153dda9b5
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Grids/specification-utils.ts
@@ -0,0 +1,106 @@
+import { buildUrl } from '@utils/url-builder';
+
+export type SpecificationType = 'openapi' | 'asyncapi' | 'graphql';
+
+export interface Specification {
+  type: SpecificationType;
+  path: string;
+  name?: string;
+  filename: string;
+  filenameWithoutExtension: string;
+}
+
+export const getSpecUrl = (spec: Specification, serviceId: string, serviceVersion: string): string => {
+  switch (spec.type) {
+    case 'openapi':
+      return buildUrl(`/docs/services/${serviceId}/${serviceVersion}/spec/${spec.filenameWithoutExtension}`);
+    case 'asyncapi':
+      return buildUrl(`/docs/services/${serviceId}/${serviceVersion}/asyncapi/${spec.filenameWithoutExtension}`);
+    case 'graphql':
+      return buildUrl(`/docs/services/${serviceId}/${serviceVersion}/graphql/${spec.filenameWithoutExtension}`);
+    default:
+      return '#';
+  }
+};
+
+export const getSpecIcon = (type: string): string => {
+  switch (type) {
+    case 'openapi':
+      return 'openapi';
+    case 'asyncapi':
+      return 'asyncapi';
+    case 'graphql':
+      return 'graphql';
+    default:
+      return 'json-schema';
+  }
+};
+
+export const getSpecLabel = (type: string): string => {
+  switch (type) {
+    case 'openapi':
+      return 'OpenAPI';
+    case 'asyncapi':
+      return 'AsyncAPI';
+    case 'graphql':
+      return 'GraphQL';
+    default:
+      return type;
+  }
+};
+
+export const getSpecColor = (type: string): string => {
+  switch (type) {
+    case 'openapi':
+      return 'green';
+    case 'asyncapi':
+      return 'purple';
+    case 'graphql':
+      return 'pink';
+    default:
+      return 'gray';
+  }
+};
+
+// Helper to normalize specifications from service data
+export const getServiceSpecifications = (data: any): Specification[] => {
+  const specs = data?.specifications;
+  if (!specs) return [];
+
+  // Handle array format
+  if (Array.isArray(specs)) {
+    return specs.map((spec: any) => {
+      const filename = spec.path?.split('/').pop() || spec.path;
+      const filenameWithoutExtension = filename?.replace(/\.[^/.]+$/, '') || '';
+      return {
+        type: spec.type,
+        path: spec.path,
+        name: spec.name,
+        filename,
+        filenameWithoutExtension,
+      };
+    });
+  }
+
+  // Handle legacy object format
+  const result: Specification[] = [];
+  if (specs.asyncapiPath) {
+    const filename = specs.asyncapiPath.split('/').pop();
+    result.push({
+      type: 'asyncapi',
+      path: specs.asyncapiPath,
+      filename,
+      filenameWithoutExtension: filename?.replace(/\.[^/.]+$/, '') || '',
+    });
+  }
+  if (specs.openapiPath) {
+    const filename = specs.openapiPath.split('/').pop();
+    result.push({
+      type: 'openapi',
+      path: specs.openapiPath,
+      filename,
+      filenameWithoutExtension: filename?.replace(/\.[^/.]+$/, '') || '',
+    });
+  }
+  return result;
+};
diff --git a/eventcatalog/src/components/Grids/utils.tsx b/packages/core/eventcatalog/src/components/Grids/utils.tsx
similarity index 82%
rename from eventcatalog/src/components/Grids/utils.tsx
rename to packages/core/eventcatalog/src/components/Grids/utils.tsx
index 4044db3ab..e7e4380a8 100644
--- a/eventcatalog/src/components/Grids/utils.tsx
+++ b/packages/core/eventcatalog/src/components/Grids/utils.tsx
@@ -1,4 +1,11 @@
-import { BoltIcon, ChatBubbleLeftIcon, MagnifyingGlassIcon, EnvelopeIcon, ServerIcon } from '@heroicons/react/24/outline';
+import {
+  BoltIcon,
+  ChatBubbleLeftIcon,
+  MagnifyingGlassIcon,
+  EnvelopeIcon,
+  ServerIcon,
+  DocumentCheckIcon,
+} from '@heroicons/react/24/outline';
 import type { CollectionMessageTypes, CollectionTypes } from '@types';
 
 export const getCollectionStyles = (collection: CollectionMessageTypes | CollectionTypes) => {
@@ -11,6 +18,8 @@ export const getCollectionStyles = (collection: CollectionMessageTypes | Collect
       return { color: 'green', Icon: MagnifyingGlassIcon };
     case 'services':
       return { color: 'pink', Icon: ServerIcon };
+    case 'data-products':
+      return { color: 'purple', Icon: DocumentCheckIcon };
     default:
       return { color: 'gray', Icon: EnvelopeIcon };
   }
diff --git a/packages/core/eventcatalog/src/components/Header.astro b/packages/core/eventcatalog/src/components/Header.astro
new file mode 100644
index 000000000..95856698f
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Header.astro
@@ -0,0 +1,287 @@
+---
+import catalog from '@utils/eventcatalog-config/catalog';
+import Search from '@components/Search/Search.astro';
+import { buildUrl } from '@utils/url-builder';
+import { showEventCatalogBranding, showCustomBranding, isEventCatalogChatEnabled } from '@utils/feature';
+import { getSession } from 'auth-astro/server';
+import { isAuthEnabled, isSSR } from '@utils/feature';
+import { EnvironmentDropdown } from './EnvironmentDropdown';
+import ChatPanelButton from './ChatPanel/ChatPanelButton';
+import ThemeToggle from './ThemeToggle';
+
+const { showNestedSideBar = true } = Astro.props;
+
+let session = null;
+if (isAuthEnabled()) {
+  session = await getSession(Astro.request);
+}
+
+const logo = {
+  src: ('/' + (catalog?.logo?.src || '')).replace(/^\/+/, '/'),
+  alt: catalog?.logo?.alt || 'Event Catalog',
+  text: catalog?.logo?.text || 'EventCatalog',
+};
+
+const repositoryUrl = catalog?.repositoryUrl || 'https://github.com/event-catalog/eventcatalog';
+---
+
+<nav
+  id="eventcatalog-header"
+  class="fixed top-0 right-0 h-[60px] bg-[rgb(var(--ec-header-bg))] border-b border-[rgb(var(--ec-header-border))] py-3 font-bold text-xl z-50 text-[rgb(var(--ec-header-text))]"
+  style={showNestedSideBar
+    ? 'left: calc(var(--ec-vertical-nav-width, 14rem) + var(--ec-sidebar-panel-width, 20rem));'
+    : 'left: var(--ec-vertical-nav-width, 14rem);'}
+>
+  <div class="px-6">
+    <div class="flex justify-between items-center">
+      <div class="hidden lg:flex flex-grow items-center">
+        <div class="w-full max-w-xl">
+          <Search />
+        </div>
+        {isEventCatalogChatEnabled() && <ChatPanelButton client:idle />}
+      </div>
+
+      <div class="hidden md:block w-3/12">
+        {
+          session ? (
+            <div class="flex items-center space-x-4 justify-end pr-2">
+              {catalog.environments && catalog.environments.length > 0 && (
+                <EnvironmentDropdown environments={catalog.environments} client:idle />
+              )}
+              <ThemeToggle client:idle />
+              <div class="relative">
+                <button
+                  id="profile-menu-button"
+                  type="button"
+                  class="flex items-center focus:outline-hidden focus:ring-2 focus:ring-offset-2 focus:ring-gray-400 rounded-full"
+                  aria-expanded="false"
+                  aria-haspopup="true"
+                  aria-label="User menu"
+                >
+                  {session.user?.image && !session.user?.image?.includes('googleusercontent.com') ? (
+                    <img
+                      src={session.user.image}
+                      alt={session.user?.name || 'User'}
+                      class="h-9 w-9 rounded-full border-2 border-gray-200 hover:border-gray-400 transition-all shadow-xs"
+                    />
+                  ) : (
+                    <div class="h-9 w-9 rounded-full border-2 border-gray-200 hover:border-gray-400 transition-all bg-gray-100 hover:bg-gray-200 flex items-center justify-center text-sm font-medium text-gray-600 shadow-xs">
+                      {session.user?.name
+                        ? session.user.name
+                            .split(' ')
+                            .map((n) => n[0])
+                            .join('')
+                            .substring(0, 2)
+                            .toUpperCase()
+                        : 'U'}
+                    </div>
+                  )}
+                </button>
+                <div
+                  id="profile-dropdown"
+                  class="ec-hidden absolute right-0 mt-2 w-48 bg-[rgb(var(--ec-dropdown-bg))] rounded-lg shadow-md py-1 z-50 border-2 border-[rgb(var(--ec-dropdown-border))] overflow-hidden"
+                >
+                  <div class="px-4 py-2 text-sm text-[rgb(var(--ec-dropdown-text))] border-b border-[rgb(var(--ec-dropdown-border))]">
+                    <div class="font-semibold">{session.user?.name || 'User'}</div>
+                    {session.user?.email && (
+                      <div class="text-[rgb(var(--ec-icon-color))] text-xs mt-0.5">{session.user.email}</div>
+                    )}
+                  </div>
+                  <button
+                    id="signout-btn"
+                    class="block w-full text-left px-4 py-2 text-sm text-[rgb(var(--ec-dropdown-text))] hover:bg-[rgb(var(--ec-dropdown-hover))] transition-colors font-medium"
+                  >
+                    Sign out
+                  </button>
+                </div>
+              </div>
+            </div>
+          ) : (
+            <>
+              <div class="flex items-center space-x-4 justify-end pr-2">
+                {catalog.environments && catalog.environments.length > 0 && (
+                  <EnvironmentDropdown environments={catalog.environments} client:idle />
+                )}
+                {isAuthEnabled() && (
+                  <button
+                    id="okta-signin-btn"
+                    class="bg-[rgb(var(--ec-button-bg))] hover:bg-[rgb(var(--ec-button-bg-hover))] text-[rgb(var(--ec-button-text))] text-sm font-medium px-4 py-2 rounded-lg transition-all shadow-xs hover:shadow focus:outline-hidden focus:ring-2 focus:ring-offset-2 focus:ring-gray-500"
+                  >
+                    Sign In
+                  </button>
+                )}
+                <ThemeToggle client:idle />
+                {showEventCatalogBranding() && (
+                  <ul class="flex space-x-4">
+                    <li>
+                      <a
+                        href="https://discord.com/invite/3rjaZMmrAm"
+                        class="block p-1.5 rounded-lg hover:bg-[rgb(var(--ec-dropdown-hover))] transition-colors"
+                        aria-label="Join our Discord community"
+                      >
+                        <img
+                          src={buildUrl('/icons/discord.svg', true)}
+                          alt=""
+                          class="h-6 w-6 hover:opacity-100 transition-opacity ec-themed-icon"
+                          aria-hidden="true"
+                        />
+                      </a>
+                    </li>
+                    <li>
+                      <a
+                        href="https://github.com/event-catalog/eventcatalog"
+                        class="block p-1.5 rounded-lg hover:bg-[rgb(var(--ec-dropdown-hover))] transition-colors"
+                        aria-label="View EventCatalog on GitHub"
+                      >
+                        <img
+                          src={buildUrl('/icons/github.svg', true)}
+                          alt=""
+                          class="h-6 w-6 hover:opacity-100 transition-opacity ec-themed-icon"
+                          aria-hidden="true"
+                        />
+                      </a>
+                    </li>
+                  </ul>
+                )}
+                {showCustomBranding() && !showEventCatalogBranding() && (
+                  <ul class="flex space-x-4">
+                    <li>
+                      <a
+                        href={repositoryUrl}
+                        class="block p-1.5 rounded-lg hover:bg-[rgb(var(--ec-dropdown-hover))] transition-colors focus:outline-hidden"
+                        aria-label="View repository on GitHub"
+                      >
+                        <img
+                          src={buildUrl('/icons/github.svg', true)}
+                          alt=""
+                          class="h-6 w-6 opacity-70 hover:opacity-100 transition-opacity ec-themed-icon"
+                          aria-hidden="true"
+                        />
+                      </a>
+                    </li>
+                  </ul>
+                )}
+              </div>
+            </>
+          )
+        }
+      </div>
+
+      <div class="md:hidden">
+        <button
+          id="menu-toggle"
+          type="button"
+          class="text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-icon-hover))] focus:outline-hidden focus:text-[rgb(var(--ec-icon-hover))]"
+          aria-label="Toggle menu"
+        >
+          <svg viewBox="0 0 24 24" class="h-6 w-6 fill-current">
+            <path
+              fill-rule="evenodd"
+              d="M4 5h16a1 1 0 0 1 0 2H4a1 1 0 1 1 0-2zm0 6h16a1 1 0 0 1 0 2H4a1 1 0 0 1 0-2zm0 6h16a1 1 0 0 1 0 2H4a1 1 0 0 1 0-2z"
+            ></path>
+          </svg>
+        </button>
+      </div>
+    </div>
+
+    <div id="mobile-menu" class="md:hidden ec-hidden mt-4">
+      <ul class="flex flex-col space-y-8 my-4 mb-8">
+        <!-- {
+          navItems.map((item) => {
+            const isActive = currentPath.includes(item.href);
+            return (
+              <li class={`font-light ${isActive ? 'font-bold text-primary' : ''}`}>
+                <a href={item.href}>{item.label}</a>
+              </li>
+            );
+          })
+        } -->
+      </ul>
+    </div>
+  </div>
+</nav>
+
+<div id="eventcatalog-header-spacer" class="h-[60px]"></div>
+<!-- Spacer to prevent content from being hidden under the fixed header -->
+
+<script>
+  import { signOut } from 'auth-astro/client';
+
+  function initializeHeader() {
+    const menuToggle = document.getElementById('menu-toggle');
+    const mobileMenu = document.getElementById('mobile-menu');
+
+    if (menuToggle && mobileMenu) {
+      menuToggle.addEventListener('click', () => {
+        mobileMenu.classList.toggle('ec-hidden');
+      });
+    }
+
+    // Profile dropdown functionality
+    const profileButton = document.getElementById('profile-menu-button');
+    const profileDropdown = document.getElementById('profile-dropdown');
+
+    if (profileButton && profileDropdown) {
+      profileButton.addEventListener('click', (e) => {
+        e.stopPropagation();
+        profileDropdown.classList.toggle('ec-hidden');
+        profileButton.setAttribute('aria-expanded', !profileDropdown.classList.contains('ec-hidden') ? 'true' : 'false');
+      });
+
+      // Close dropdown when clicking outside
+      document.addEventListener('click', (e) => {
+        if (!profileButton.contains(e.target as Node) && !profileDropdown.contains(e.target as Node)) {
+          profileDropdown.classList.add('ec-hidden');
+          profileButton.setAttribute('aria-expanded', 'false');
+        }
+      });
+
+      // Close dropdown on escape key
+      document.addEventListener('keydown', (e) => {
+        if (e.key === 'Escape' && !profileDropdown.classList.contains('ec-hidden')) {
+          profileDropdown.classList.add('ec-hidden');
+          profileButton.setAttribute('aria-expanded', 'false');
+          profileButton.focus();
+        }
+      });
+
+      document.getElementById('signout-btn')?.addEventListener('click', async () => {
+        try {
+          await signOut();
+        } catch (error) {
+          console.error('Sign out failed:', error);
+          alert('Sign out failed. Please check your AUTH_TRUST_HOST configuration if running behind a reverse proxy.');
+        }
+      });
+    }
+  }
+
+  // Initialize on first load
+  initializeHeader();
+
+  // Re-initialize after Astro view transitions (needed because of transition:persist on header)
+  document.addEventListener('astro:page-load', initializeHeader);
+</script>
+
+<style>
+  /* Custom class for toggling dropdowns/menus */
+  .ec-hidden {
+    display: none !important;
+  }
+
+  @media (max-width: 768px) {
+    nav {
+      transition: all 0.3s ease-out;
+    }
+
+    #mobile-menu {
+      transition: all 0.3s ease-out;
+      max-height: 0;
+      overflow: hidden;
+    }
+
+    #mobile-menu:not(.ec-hidden) {
+      max-height: 500px; /* Adjust this value as needed */
+    }
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/components/Lists/OwnersList.tsx b/packages/core/eventcatalog/src/components/Lists/OwnersList.tsx
new file mode 100644
index 000000000..de1b93068
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Lists/OwnersList.tsx
@@ -0,0 +1,72 @@
+import { Disclosure, DisclosureButton, DisclosurePanel } from '@headlessui/react';
+import { ChevronDownIcon } from '@heroicons/react/20/solid';
+import { UserGroupIcon, UserIcon } from '@heroicons/react/24/outline';
+import './PillListFlat.styles.css';
+
+interface Props {
+  title: string;
+  owners: {
+    label: string;
+    badge?: string;
+    type: string;
+    avatarUrl?: string;
+    href: string;
+  }[];
+  emptyMessage: string;
+}
+
+const OwnersList = ({ title, owners, emptyMessage }: Props) => {
+  return (
+    <div>
+      <div className="mx-auto w-full max-w-lg divide-y divide-[rgb(var(--ec-page-border))] rounded-xl">
+        <Disclosure as="div" className="" defaultOpen={owners.length <= 5}>
+          <DisclosureButton className="group flex w-full items-center justify-start space-x-4">
+            <span className="text-sm text-[rgb(var(--ec-page-text))] font-semibold group-data-[hover]:opacity-80 capitalize">
+              {' '}
+              {title}{' '}
+            </span>
+            <ChevronDownIcon className="size-5 fill-[rgb(var(--ec-icon-color))] group-data-[hover]:opacity-80 group-data-[open]:rotate-180" />
+          </DisclosureButton>
+          <DisclosurePanel className="mt-2 text-sm/5 text-[rgb(var(--ec-page-text-muted))]">
+            <ul role="list" className="space-y-2">
+              {owners.map((item) => {
+                return (
+                  <li
+                    className="owner-item has-tooltip rounded-md text-[rgb(var(--ec-page-text-muted))] group px-1 w-full hover:text-white hover:font-normal"
+                    key={item.href}
+                  >
+                    <a className={`flex items-center space-x-2`} href={item.href}>
+                      {item.type === 'users' && (
+                        <UserIcon className="h-4 w-4 text-[rgb(var(--ec-page-text))] group-hover:text-white" strokeWidth={1} />
+                      )}
+                      {item.type === 'teams' && (
+                        <UserGroupIcon
+                          className="h-4 w-4 text-[rgb(var(--ec-page-text))] group-hover:text-white"
+                          strokeWidth={1}
+                        />
+                      )}
+                      <span className="font-light text-sm truncate">{item.label}</span>
+                      {item.label.length > 24 && (
+                        <span className="tooltip rounded relative shadow-lg p-1 font-normal text-xs bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] text-[rgb(var(--ec-page-text))] border border-[rgb(var(--ec-page-border))] ml-[30px] mt-12">
+                          {item.label}
+                        </span>
+                      )}
+                    </a>
+                  </li>
+                );
+              })}
+              {owners.length === 0 && (
+                <li className="inline mr-2 leading-6 text-sm">
+                  <span className="text-[rgb(var(--ec-page-text-muted))]">{emptyMessage}</span>
+                </li>
+              )}
+            </ul>
+          </DisclosurePanel>
+        </Disclosure>
+      </div>
+      <div className="border-b border-[rgb(var(--ec-page-border))] my-4"></div>
+    </div>
+  );
+};
+
+export default OwnersList;
diff --git a/eventcatalog/src/components/Lists/PillList.tsx b/packages/core/eventcatalog/src/components/Lists/PillList.tsx
similarity index 100%
rename from eventcatalog/src/components/Lists/PillList.tsx
rename to packages/core/eventcatalog/src/components/Lists/PillList.tsx
diff --git a/packages/core/eventcatalog/src/components/Lists/PillListFlat.styles.css b/packages/core/eventcatalog/src/components/Lists/PillListFlat.styles.css
new file mode 100644
index 000000000..d7eadd4cd
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Lists/PillListFlat.styles.css
@@ -0,0 +1,20 @@
+.tooltip {
+    visibility: hidden;
+    position: absolute;
+  }
+  .has-tooltip:hover .tooltip {
+    visibility: visible;
+    z-index: 100;
+  }
+
+  .pill-item:hover {
+    background: linear-gradient(to left, rgb(var(--ec-accent-gradient-from)), rgb(var(--ec-accent-gradient-to)));
+    color: white;
+    font-weight: normal;
+  }
+
+  .owner-item:hover {
+    background: linear-gradient(to left, rgb(var(--ec-accent-gradient-from)), rgb(var(--ec-accent-gradient-to)));
+    color: white;
+    font-weight: normal;
+  }
\ No newline at end of file
diff --git a/eventcatalog/src/components/Lists/PillListFlat.tsx b/packages/core/eventcatalog/src/components/Lists/PillListFlat.tsx
similarity index 80%
rename from eventcatalog/src/components/Lists/PillListFlat.tsx
rename to packages/core/eventcatalog/src/components/Lists/PillListFlat.tsx
index c92822584..adc1c3ffa 100644
--- a/eventcatalog/src/components/Lists/PillListFlat.tsx
+++ b/packages/core/eventcatalog/src/components/Lists/PillListFlat.tsx
@@ -66,10 +66,7 @@ const PillList = ({ title, pills, emptyMessage, color = 'gray', limit = 10, ...p
     const PillIcon = item.icon ? (icons as any)[item.icon] : null;
 
     return (
-      <li
-        className=" has-tooltip rounded-md text-gray-600 group px-1 w-full hover:bg-gradient-to-l hover:from-purple-500 hover:to-purple-700 hover:text-white hover:font-normal  "
-        key={item.href}
-      >
+      <li className="pill-item has-tooltip rounded-md text-[rgb(var(--ec-page-text-muted))] group px-1 w-full" key={item.href}>
         <a className={`leading-3`} href={href} target={item.target ?? '_self'}>
           <span className="space-x-2 flex items-center">
             {Icon && !PillIcon && <Icon className="h-4 w-4 shrink-0" />}
@@ -78,7 +75,7 @@ const PillList = ({ title, pills, emptyMessage, color = 'gray', limit = 10, ...p
               {item.label} {item.tag && <>({item.tag})</>}
             </span>
             {item.label.length > 24 && (
-              <span className="tooltip rounded relative shadow-lg p-1 font-normal text-xs bg-white  text-black ml-[30px] mt-12">
+              <span className="tooltip rounded relative shadow-lg p-1 font-normal text-xs bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] text-[rgb(var(--ec-page-text))] border border-[rgb(var(--ec-page-border))] ml-[30px] mt-12">
                 {item.label} {item.tag && <>({item.tag})</>}
               </span>
             )}
@@ -91,13 +88,16 @@ const PillList = ({ title, pills, emptyMessage, color = 'gray', limit = 10, ...p
 
   return (
     <div className="">
-      <div className="mx-auto w-full max-w-lg divide-y divide-white/5 rounded-xl bg-white/5">
+      <div className="mx-auto w-full max-w-lg divide-y divide-[rgb(var(--ec-page-border))] rounded-xl">
         <Disclosure as="div" className="" defaultOpen={pills.length <= limit}>
           <DisclosureButton className="group flex w-full items-center justify-start space-x-4">
-            <span className="text-sm text-black font-semibold group-data-[hover]:text-black/80 capitalize"> {title} </span>
-            <ChevronDownIcon className="size-5 ml-2 fill-black/60 group-data-[hover]:fill-black/50 group-data-[open]:rotate-180" />
+            <span className="text-sm text-[rgb(var(--ec-page-text))] font-semibold group-data-[hover]:opacity-80 capitalize">
+              {' '}
+              {title}{' '}
+            </span>
+            <ChevronDownIcon className="size-5 ml-2 fill-[rgb(var(--ec-icon-color))] group-data-[hover]:opacity-80 group-data-[open]:rotate-180" />
           </DisclosureButton>
-          <DisclosurePanel className="mt-2 text-sm/5 text-black/50">
+          <DisclosurePanel className="mt-2 text-sm/5 text-[rgb(var(--ec-page-text-muted))]">
             <div className="space-y-2">
               {groupedPills.ungrouped.length > 0 && (
                 <ul role="list" className="space-y-2">
@@ -115,10 +115,10 @@ const PillList = ({ title, pills, emptyMessage, color = 'gray', limit = 10, ...p
                           e.stopPropagation();
                           toggleSubgroup(subgroupName);
                         }}
-                        className="p-1 hover:bg-gray-100 rounded-md"
+                        className="p-1 hover:bg-[rgb(var(--ec-content-hover))] rounded-md"
                       >
                         <div className={`transition-transform duration-150 ${isCollapsed ? '' : 'rotate-180'}`}>
-                          <ChevronDownIcon className="h-3 w-3 text-gray-500" />
+                          <ChevronDownIcon className="h-3 w-3 text-[rgb(var(--ec-icon-color))]" />
                         </div>
                       </button>
                       <button
@@ -126,7 +126,7 @@ const PillList = ({ title, pills, emptyMessage, color = 'gray', limit = 10, ...p
                           e.stopPropagation();
                           toggleSubgroup(subgroupName);
                         }}
-                        className="flex-grow flex items-center justify-between px-2 py-0.5 text-xs font-bold rounded-md text-gray-900 uppercase"
+                        className="flex-grow flex items-center justify-between px-2 py-0.5 text-xs font-bold rounded-md text-[rgb(var(--ec-page-text))] uppercase"
                       >
                         {subgroupName} ({subgroupPills.length})
                       </button>
@@ -134,7 +134,7 @@ const PillList = ({ title, pills, emptyMessage, color = 'gray', limit = 10, ...p
                     <div
                       className={`overflow-hidden transition-[height] duration-150 ease-out ${isCollapsed ? 'h-0' : 'h-auto'}`}
                     >
-                      <ul role="list" className="space-y-2 border-l border-gray-200/80 ml-[9px] pl-4 pt-2">
+                      <ul role="list" className="space-y-2 border-l border-[rgb(var(--ec-page-border))] ml-[9px] pl-4 pt-2">
                         {subgroupPills.map(renderPillItem)}
                       </ul>
                     </div>
@@ -144,14 +144,14 @@ const PillList = ({ title, pills, emptyMessage, color = 'gray', limit = 10, ...p
 
               {pills.length === 0 && emptyMessage && (
                 <div className="inline mr-2 leading-tight text-xs">
-                  <span className="text-gray-400">{emptyMessage}</span>
+                  <span className="text-[rgb(var(--ec-icon-color))]">{emptyMessage}</span>
                 </div>
               )}
             </div>
           </DisclosurePanel>
         </Disclosure>
       </div>
-      <div className="border-b border-gray-100 my-4"></div>
+      <div className="border-b border-[rgb(var(--ec-page-border))] my-4"></div>
     </div>
   );
 };
diff --git a/packages/core/eventcatalog/src/components/Lists/VersionList.astro b/packages/core/eventcatalog/src/components/Lists/VersionList.astro
new file mode 100644
index 000000000..acd1675b3
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Lists/VersionList.astro
@@ -0,0 +1,60 @@
+---
+import type { CollectionTypes } from '@types';
+import { buildUrl } from '@utils/url-builder';
+import type { CollectionEntry } from 'astro:content';
+import { HistoryIcon } from 'lucide-react';
+
+interface Props {
+  title?: string;
+  versions: string[];
+  collectionItem: CollectionEntry<CollectionTypes>;
+}
+
+const { versions, collectionItem, title } = Astro.props;
+const currentPath = Astro.url.pathname;
+---
+
+<div class="space-y-2 pb-4">
+  <span
+    class="text-xs text-[rgb(var(--ec-page-text))] font-semibold group-data-[hover]:text-[rgb(var(--ec-page-text))]/80 capitalize"
+  >
+    {title || `Versions (${collectionItem.data.versions?.length})`}
+  </span>
+  <ul role="list" class="space-y-2">
+    {
+      versions.map((version) => {
+        const isCurrent = currentPath.includes(version);
+        return (
+          <li class="version-item rounded-md px-1 group w-full hover:text-white hover:font-normal">
+            <a
+              class={`flex items-center space-x-2 cursor-pointer`}
+              href={buildUrl(`/docs/${collectionItem.collection}/${collectionItem.data.id}/${version}`)}
+            >
+              {/* {Icon && <Icon class={`h-4 w-4`} />} */}
+              <HistoryIcon className="h-4 w-4 text-[rgb(var(--ec-page-text-muted))] group-hover:text-white" strokeWidth={1} />
+              <span
+                class={`font-light text-xs text-[rgb(var(--ec-page-text))] group-hover:text-white ${isCurrent ? 'underline ' : ''}`}
+              >
+                {version === collectionItem.data.latestVersion ? `v${version} (latest)` : `v${version}`}
+              </span>
+            </a>
+          </li>
+        );
+      })
+    }
+  </ul>
+  <div class="border-b border-[rgb(var(--ec-page-border))] pt-2"></div>
+</div>
+
+<style>
+  .version-item:hover {
+    background: linear-gradient(to left, rgb(var(--ec-accent-gradient-from)), rgb(var(--ec-accent-gradient-to)));
+  }
+</style>
+
+<script>
+  document.getElementById('version')?.addEventListener('change', (e: any) => {
+    if (!e.target) return;
+    window.location.href = e.target.value;
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/components/MDX/ADRTable/ADRTable.astro b/packages/core/eventcatalog/src/components/MDX/ADRTable/ADRTable.astro
new file mode 100644
index 000000000..5e740ee9b
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/ADRTable/ADRTable.astro
@@ -0,0 +1,99 @@
+---
+import ADRTableClient from './ADRTable.client';
+import Admonition from '../Admonition';
+import { getAdrs, getAdrsForResource, type AdrResource } from '@utils/collections/adrs';
+import { ADR_STATUS_VALUES, type AdrStatus } from '@utils/collections/adr-constants';
+import { getResourceReferenceStyle } from '@utils/resource-reference-colors';
+
+// The ADR resource-reference styling (colour + CSS custom props), computed here on
+// the server so the table's names match the `[[adr|...]]` wiki reference look. We
+// parse the CSS declaration string into a React style object for the client island.
+const adrRefStyle = getResourceReferenceStyle('adr')
+  .split(';')
+  .map((declaration) => declaration.trim())
+  .filter(Boolean)
+  .reduce<Record<string, string>>((style, declaration) => {
+    const [property, ...rest] = declaration.split(':');
+    const value = rest.join(':').trim();
+    if (!property || !value) return style;
+    const key = property.trim().startsWith('--')
+      ? property.trim()
+      : property.trim().replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    style[key] = value;
+    return style;
+  }, {});
+
+export interface Props {
+  // Filter to one or more statuses. Accepts a single status ("accepted") or a
+  // comma-separated list ("accepted,proposed"). When omitted, all statuses show.
+  status?: string;
+  // Page size for the table. Defaults to 10.
+  limit?: number;
+  // The page resource is injected by the MDX runtime via `...props`.
+  collection?: string;
+  data?: any;
+}
+
+const { status, limit } = Astro.props;
+const collection = Astro.props.collection as string;
+const rawStatus: string = status || '';
+
+// ADRs can apply to any documented resource. The only types that can't be the
+// subject of an ADRTable are non-resource pages.
+const isComponentEnabled = !!collection && !!Astro.props.data?.id;
+
+// Parse the `status` prop into a validated list of statuses.
+const requestedStatuses = rawStatus
+  .split(',')
+  .map((value) => value.trim().toLowerCase())
+  .filter((value): value is AdrStatus => (ADR_STATUS_VALUES as readonly string[]).includes(value));
+
+let adrs: ReturnType<typeof getEssentialPropsForAdr>[] = [];
+
+function getEssentialPropsForAdr(adr: Awaited<ReturnType<typeof getAdrs>>[number]) {
+  return {
+    id: adr.data.id,
+    name: adr.data.name,
+    version: adr.data.version,
+    status: adr.data.status as AdrStatus,
+    // Serialise the date so it survives the server -> client island boundary.
+    date: adr.data.date ? new Date(adr.data.date).toISOString() : null,
+    summary: adr.data.summary || '',
+  };
+}
+
+if (isComponentEnabled) {
+  const allAdrs = await getAdrs();
+  const resource = Astro.props as unknown as AdrResource;
+  let relevant = getAdrsForResource(resource, allAdrs);
+
+  if (requestedStatuses.length > 0) {
+    relevant = relevant.filter((adr) => requestedStatuses.includes(adr.data.status as AdrStatus));
+  }
+
+  adrs = relevant.map(getEssentialPropsForAdr);
+}
+---
+
+{
+  isComponentEnabled && (
+    <ADRTableClient
+      client:load
+      adrs={adrs}
+      limit={limit}
+      resourceName={Astro.props.data?.name || collection}
+      refStyle={adrRefStyle}
+    />
+  )
+}
+
+{
+  !isComponentEnabled && (
+    <Admonition type="warning">
+      <div>
+        <span class="font-bold">{`<ADRTable/>`} component could not be rendered.</span>
+        <span class="block">It must be used on a documented resource page (a service, system, domain, etc.).</span>
+      </div>
+    </Admonition>
+  )
+}
diff --git a/packages/core/eventcatalog/src/components/MDX/ADRTable/ADRTable.client.tsx b/packages/core/eventcatalog/src/components/MDX/ADRTable/ADRTable.client.tsx
new file mode 100644
index 000000000..1cf8709c2
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/ADRTable/ADRTable.client.tsx
@@ -0,0 +1,400 @@
+import { buildUrl } from '@utils/url-builder';
+import { ADR_STATUS_VALUES, adrStatusBadgeColor, formatAdrStatus, type AdrStatus } from '@utils/collections/adr-constants';
+import { useState, useMemo, memo, type CSSProperties } from 'react';
+
+type AdrTableItem = {
+  id: string;
+  name: string;
+  version: string;
+  status: AdrStatus;
+  date: string | null;
+  summary: string;
+};
+
+type ADRTableProps = {
+  adrs: AdrTableItem[];
+  limit?: number;
+  resourceName: string;
+  // React-ready style object for the ADR resource reference (colour + CSS custom
+  // props), computed server-side so we match the `[[adr|...]]` wiki reference look
+  // without pulling server-only utils into the client bundle.
+  refStyle: CSSProperties;
+};
+
+type SortKey = 'name' | 'status' | 'date';
+type SortDirection = 'asc' | 'desc';
+
+// Tailwind classes per status colour. The colour names come from adrStatusBadgeColor.
+const STATUS_BADGE_CLASSES: Record<string, string> = {
+  amber: 'bg-amber-100 text-amber-800 ring-amber-600/20 dark:bg-amber-500/15 dark:text-amber-300',
+  green: 'bg-green-100 text-green-800 ring-green-600/20 dark:bg-green-500/15 dark:text-green-300',
+  red: 'bg-red-100 text-red-800 ring-red-600/20 dark:bg-red-500/15 dark:text-red-300',
+  gray: 'bg-gray-100 text-gray-700 ring-gray-500/20 dark:bg-gray-500/15 dark:text-gray-300',
+  purple: 'bg-purple-100 text-purple-800 ring-purple-600/20 dark:bg-purple-500/15 dark:text-purple-300',
+};
+
+const StatusBadge = memo(({ status }: { status: AdrStatus }) => {
+  const color = adrStatusBadgeColor[status] || 'gray';
+  return (
+    <span
+      className={`inline-flex items-center rounded-md px-2 py-0.5 text-xs font-medium ring-1 ring-inset ${STATUS_BADGE_CLASSES[color] || STATUS_BADGE_CLASSES.gray}`}
+    >
+      {formatAdrStatus(status)}
+    </span>
+  );
+});
+
+const formatDate = (iso: string | null) => {
+  if (!iso) return '-';
+  return new Intl.DateTimeFormat('en-US', { timeZone: 'UTC', year: 'numeric', month: 'short', day: 'numeric' }).format(
+    new Date(iso)
+  );
+};
+
+const AdrRow = memo(({ adr, refStyle }: { adr: AdrTableItem; refStyle: CSSProperties }) => {
+  const url = buildUrl(`/docs/adrs/${adr.id}/${adr.version}`);
+  return (
+    <tr className="group hover:bg-[rgb(var(--ec-content-hover))]">
+      <td className="py-4 pl-4 pr-3 text-sm font-medium sm:pl-6 relative">
+        <a href={url} className="absolute inset-0 z-10" aria-label={`View details for ${adr.name}`} />
+        <span className="rounded px-1 -mx-1 break-words transition-colors hover:bg-[var(--ec-resource-ref-bg)]" style={refStyle}>
+          {adr.name}
+        </span>
+      </td>
+      <td className="whitespace-nowrap px-3 py-4 text-sm relative">
+        <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
+        <StatusBadge status={adr.status} />
+      </td>
+      <td className="whitespace-nowrap px-3 py-4 text-sm text-[rgb(var(--ec-page-text-muted))] relative">
+        <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
+        <span>{formatDate(adr.date)}</span>
+      </td>
+      <td className="px-3 py-4 text-sm text-[rgb(var(--ec-page-text-muted))] relative">
+        <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
+        <span className="line-clamp-2 break-words">{adr.summary || '-'}</span>
+      </td>
+    </tr>
+  );
+});
+
+const FilterButton = memo(
+  ({
+    status,
+    active,
+    count,
+    onToggle,
+  }: {
+    status: AdrStatus;
+    active: boolean;
+    count: number;
+    onToggle: (status: AdrStatus) => void;
+  }) => (
+    <button
+      onClick={() => onToggle(status)}
+      className={`px-3 py-1 rounded-md text-sm font-medium border border-[rgb(var(--ec-page-border))] ${
+        active
+          ? 'bg-[rgb(var(--ec-button-bg))] text-[rgb(var(--ec-button-text))] hover:bg-[rgb(var(--ec-button-bg-hover))]'
+          : 'bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))]'
+      }`}
+    >
+      {formatAdrStatus(status)} ({count})
+    </button>
+  )
+);
+
+const SortHeader = ({
+  label,
+  sortKey,
+  activeSort,
+  direction,
+  onSort,
+  className,
+}: {
+  label: string;
+  sortKey: SortKey;
+  activeSort: SortKey;
+  direction: SortDirection;
+  onSort: (key: SortKey) => void;
+  className?: string;
+}) => {
+  const isActive = activeSort === sortKey;
+  return (
+    <th scope="col" className={className}>
+      <button
+        onClick={() => onSort(sortKey)}
+        className="group inline-flex items-center gap-1 text-left font-semibold text-[rgb(var(--ec-page-text))]"
+      >
+        {label}
+        <span
+          className={`text-xs ${isActive ? 'text-[rgb(var(--ec-page-text))]' : 'text-[rgb(var(--ec-page-text-muted))] opacity-0 group-hover:opacity-100'}`}
+        >
+          {isActive ? (direction === 'asc' ? '▲' : '▼') : '↕'}
+        </span>
+      </button>
+    </th>
+  );
+};
+
+const ADRTable = ({ adrs, limit, resourceName, refStyle }: ADRTableProps) => {
+  const [searchTerm, setSearchTerm] = useState('');
+  const [statusFilters, setStatusFilters] = useState<Set<AdrStatus>>(new Set());
+  const [sortKey, setSortKey] = useState<SortKey>('date');
+  const [sortDirection, setSortDirection] = useState<SortDirection>('desc');
+  const [currentPage, setCurrentPage] = useState(1);
+  const itemsPerPage = limit || 10;
+
+  const toggleStatus = (status: AdrStatus) => {
+    setStatusFilters((prev) => {
+      const next = new Set(prev);
+      if (next.has(status)) next.delete(status);
+      else next.add(status);
+      return next;
+    });
+    setCurrentPage(1);
+  };
+
+  const onSort = (key: SortKey) => {
+    if (key === sortKey) {
+      setSortDirection((d) => (d === 'asc' ? 'desc' : 'asc'));
+    } else {
+      setSortKey(key);
+      setSortDirection(key === 'date' ? 'desc' : 'asc');
+    }
+    setCurrentPage(1);
+  };
+
+  // Counts per status across the full (unfiltered) set, for the filter buttons.
+  const statusCounts = useMemo(() => {
+    const counts = new Map<AdrStatus, number>();
+    adrs.forEach((adr) => counts.set(adr.status, (counts.get(adr.status) || 0) + 1));
+    return counts;
+  }, [adrs]);
+
+  const availableStatuses = useMemo(
+    () => ADR_STATUS_VALUES.filter((status) => (statusCounts.get(status) || 0) > 0),
+    [statusCounts]
+  );
+
+  const filtered = useMemo(() => {
+    let result = adrs;
+
+    if (statusFilters.size > 0) {
+      result = result.filter((adr) => statusFilters.has(adr.status));
+    }
+
+    if (searchTerm) {
+      const term = searchTerm.toLowerCase();
+      result = result.filter(
+        (adr) =>
+          adr.name.toLowerCase().includes(term) ||
+          adr.summary.toLowerCase().includes(term) ||
+          adr.status.toLowerCase().includes(term)
+      );
+    }
+
+    const sorted = [...result].sort((a, b) => {
+      let comparison = 0;
+      if (sortKey === 'name') comparison = a.name.localeCompare(b.name);
+      else if (sortKey === 'status') comparison = a.status.localeCompare(b.status);
+      else comparison = Number(new Date(a.date || 0)) - Number(new Date(b.date || 0));
+      return sortDirection === 'asc' ? comparison : -comparison;
+    });
+
+    return sorted;
+  }, [adrs, statusFilters, searchTerm, sortKey, sortDirection]);
+
+  const totalPages = Math.ceil(filtered.length / itemsPerPage);
+  const startIndex = (currentPage - 1) * itemsPerPage;
+  const paginated = useMemo(() => filtered.slice(startIndex, startIndex + itemsPerPage), [filtered, startIndex, itemsPerPage]);
+
+  const hasFilters = statusFilters.size > 0 || searchTerm.length > 0;
+
+  return (
+    <div className="mx-auto not-prose py-4 space-y-4 my-4">
+      <div className="flow-root bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] p-4 pb-2 rounded-lg text-[rgb(var(--ec-page-text))]">
+        <div className="space-y-4">
+          <h2 className="text-xl font-semibold">
+            Architecture Decision Records ({hasFilters ? `${filtered.length}/${adrs.length}` : adrs.length})
+          </h2>
+          <span className="text-sm text-[rgb(var(--ec-page-text-muted))]">
+            Decisions that apply to this {resourceName}. Search, filter by status, or sort by clicking a column.
+          </span>
+
+          {availableStatuses.length > 0 && (
+            <div className="flex flex-wrap gap-2 pb-2">
+              {availableStatuses.map((status) => (
+                <FilterButton
+                  key={status}
+                  status={status}
+                  active={statusFilters.has(status)}
+                  count={statusCounts.get(status) || 0}
+                  onToggle={toggleStatus}
+                />
+              ))}
+            </div>
+          )}
+
+          <div className="relative">
+            <div className="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
+              <svg
+                className="h-5 w-5 text-[rgb(var(--ec-icon-color))]"
+                viewBox="0 0 20 20"
+                fill="currentColor"
+                aria-hidden="true"
+              >
+                <path
+                  fillRule="evenodd"
+                  d="M9 3.5a5.5 5.5 0 100 11 5.5 5.5 0 000-11zM2 9a7 7 0 1112.452 4.391l3.328 3.329a.75.75 0 11-1.06 1.06l-3.329-3.328A7 7 0 012 9z"
+                  clipRule="evenodd"
+                />
+              </svg>
+            </div>
+            <input
+              type="text"
+              value={searchTerm}
+              onChange={(e) => {
+                setSearchTerm(e.target.value);
+                setCurrentPage(1);
+              }}
+              placeholder="Search by name, status, or summary..."
+              className="block w-full rounded-md border-0 py-1.5 pl-10 pr-10 text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-input-bg))] ring-1 ring-inset ring-[rgb(var(--ec-input-border))] placeholder:text-[rgb(var(--ec-input-placeholder))] focus:ring-2 focus:ring-inset focus:ring-[rgb(var(--ec-accent))] sm:text-sm sm:leading-6"
+            />
+            {searchTerm && (
+              <button
+                onClick={() => {
+                  setSearchTerm('');
+                  setCurrentPage(1);
+                }}
+                className="absolute inset-y-0 right-0 flex items-center pr-3"
+                aria-label="Clear search"
+              >
+                <svg
+                  className="h-5 w-5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-icon-hover))]"
+                  viewBox="0 0 20 20"
+                  fill="currentColor"
+                >
+                  <path d="M6.28 5.22a.75.75 0 00-1.06 1.06L8.94 10l-3.72 3.72a.75.75 0 101.06 1.06L10 11.06l3.72 3.72a.75.75 0 101.06-1.06L11.06 10l3.72-3.72a.75.75 0 00-1.06-1.06L10 8.94 6.28 5.22z" />
+                </svg>
+              </button>
+            )}
+          </div>
+        </div>
+
+        <div className="overflow-x-auto">
+          <div className="inline-block min-w-full py-2 align-middle">
+            <div className="max-w-full overflow-hidden">
+              <table className="min-w-full table-fixed divide-y divide-[rgb(var(--ec-page-border))] rounded-xs bg-[rgb(var(--ec-page-bg))]">
+                <thead>
+                  <tr>
+                    <SortHeader
+                      label="Name"
+                      sortKey="name"
+                      activeSort={sortKey}
+                      direction={sortDirection}
+                      onSort={onSort}
+                      className="w-2/5 py-3.5 pl-4 pr-3 text-left text-sm sm:pl-6"
+                    />
+                    <SortHeader
+                      label="Status"
+                      sortKey="status"
+                      activeSort={sortKey}
+                      direction={sortDirection}
+                      onSort={onSort}
+                      className="w-[120px] px-3 py-3.5 text-left text-sm"
+                    />
+                    <SortHeader
+                      label="Date"
+                      sortKey="date"
+                      activeSort={sortKey}
+                      direction={sortDirection}
+                      onSort={onSort}
+                      className="w-[140px] px-3 py-3.5 text-left text-sm"
+                    />
+                    <th scope="col" className="w-2/5 px-3 py-3.5 text-left text-sm font-semibold text-[rgb(var(--ec-page-text))]">
+                      Summary
+                    </th>
+                  </tr>
+                </thead>
+                <tbody className="divide-y divide-[rgb(var(--ec-page-border))]">
+                  {paginated.length > 0 ? (
+                    paginated.map((adr) => <AdrRow key={`${adr.id}-${adr.version}`} adr={adr} refStyle={refStyle} />)
+                  ) : (
+                    <tr>
+                      <td colSpan={4} className="text-center py-4 text-sm text-[rgb(var(--ec-page-text-muted))]">
+                        No decision records found
+                      </td>
+                    </tr>
+                  )}
+                </tbody>
+              </table>
+            </div>
+          </div>
+        </div>
+
+        {totalPages > 1 && (
+          <div className="flex items-center justify-between border-t border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] px-4 py-3 sm:px-6 -mt-2">
+            <div className="flex flex-1 justify-between sm:hidden">
+              <button
+                onClick={() => setCurrentPage(currentPage - 1)}
+                disabled={currentPage === 1}
+                className={`relative inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] px-4 py-2 text-sm font-medium ${currentPage === 1 ? 'text-[rgb(var(--ec-page-text-muted))] opacity-50' : 'text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))]'}`}
+              >
+                Previous
+              </button>
+              <button
+                onClick={() => setCurrentPage(currentPage + 1)}
+                disabled={currentPage === totalPages}
+                className={`relative ml-3 inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] px-4 py-2 text-sm font-medium ${currentPage === totalPages ? 'text-[rgb(var(--ec-page-text-muted))] opacity-50' : 'text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))]'}`}
+              >
+                Next
+              </button>
+            </div>
+            <div className="hidden sm:flex sm:flex-1 sm:items-center sm:justify-between">
+              <div>
+                <p className="text-sm text-[rgb(var(--ec-page-text-muted))]">
+                  Showing <span className="font-medium">{startIndex + 1}</span> to{' '}
+                  <span className="font-medium">{Math.min(startIndex + itemsPerPage, filtered.length)}</span> of{' '}
+                  <span className="font-medium">{filtered.length}</span> results
+                </p>
+              </div>
+              <div>
+                <nav className="isolate inline-flex -space-x-px rounded-md shadow-xs" aria-label="Pagination">
+                  <button
+                    onClick={() => setCurrentPage(currentPage - 1)}
+                    disabled={currentPage === 1}
+                    className={`relative inline-flex items-center rounded-l-md px-2 py-2 ${currentPage === 1 ? 'text-[rgb(var(--ec-page-text-muted))] opacity-50' : 'text-[rgb(var(--ec-icon-color))] hover:bg-[rgb(var(--ec-content-hover))]'} ring-1 ring-inset ring-[rgb(var(--ec-page-border))]`}
+                  >
+                    <span className="sr-only">Previous</span>
+                    <svg className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+                      <path
+                        fillRule="evenodd"
+                        d="M12.79 5.23a.75.75 0 01-.02 1.06L8.832 10l3.938 3.71a.75.75 0 11-1.04 1.08l-4.5-4.25a.75.75 0 010-1.08l4.5-4.25a.75.75 0 011.06.02z"
+                        clipRule="evenodd"
+                      />
+                    </svg>
+                  </button>
+                  <button
+                    onClick={() => setCurrentPage(currentPage + 1)}
+                    disabled={currentPage === totalPages}
+                    className={`relative inline-flex items-center rounded-r-md px-2 py-2 ${currentPage === totalPages ? 'text-[rgb(var(--ec-page-text-muted))] opacity-50' : 'text-[rgb(var(--ec-icon-color))] hover:bg-[rgb(var(--ec-content-hover))]'} ring-1 ring-inset ring-[rgb(var(--ec-page-border))]`}
+                  >
+                    <span className="sr-only">Next</span>
+                    <svg className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+                      <path
+                        fillRule="evenodd"
+                        d="M7.21 14.77a.75.75 0 01.02-1.06L11.168 10 7.23 6.29a.75.75 0 111.04-1.08l4.5 4.25a.75.75 0 010 1.08l-4.5 4.25a.75.75 0 01-1.06-.02z"
+                        clipRule="evenodd"
+                      />
+                    </svg>
+                  </button>
+                </nav>
+              </div>
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default ADRTable;
diff --git a/eventcatalog/src/components/MDX/Accordion/Accordion.astro b/packages/core/eventcatalog/src/components/MDX/Accordion/Accordion.astro
similarity index 100%
rename from eventcatalog/src/components/MDX/Accordion/Accordion.astro
rename to packages/core/eventcatalog/src/components/MDX/Accordion/Accordion.astro
diff --git a/packages/core/eventcatalog/src/components/MDX/Accordion/Accordion.tsx b/packages/core/eventcatalog/src/components/MDX/Accordion/Accordion.tsx
new file mode 100644
index 000000000..3f45c857a
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/Accordion/Accordion.tsx
@@ -0,0 +1,50 @@
+import { Disclosure, DisclosureButton, DisclosurePanel } from '@headlessui/react';
+import { ChevronDownIcon } from '@heroicons/react/20/solid';
+import { useEffect } from 'react';
+
+declare global {
+  interface Window {
+    renderDiagrams?: (graphs: HTMLCollectionOf<Element>) => void;
+    renderPlantUML?: (graphs: HTMLCollectionOf<Element>) => void;
+  }
+}
+
+export default function Example({ title, children }: any) {
+  return (
+    <div className="accordion border border-[rgb(var(--ec-page-border))] rounded-lg bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] my-3">
+      <Disclosure as="div" key={title}>
+        {({ open }) => {
+          useEffect(() => {
+            if (open) {
+              const graphs = document.getElementsByClassName('mermaid');
+              const plantUML = document.getElementsByClassName('plantuml');
+              if (graphs.length > 0 && window.renderDiagrams) {
+                window.renderDiagrams(graphs);
+              }
+              if (plantUML.length > 0 && window.renderPlantUML) {
+                window.renderPlantUML(plantUML);
+              }
+            }
+          }, [open]);
+
+          return (
+            <div>
+              <DisclosureButton className="group flex w-full items-center gap-3 px-5 py-4 text-left text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-page-text)/0.03)] transition-colors">
+                <ChevronDownIcon
+                  className={`h-5 w-5 shrink-0 text-[rgb(var(--ec-page-text-muted))] transition-transform duration-200 ${
+                    open ? 'rotate-0' : '-rotate-90'
+                  }`}
+                  aria-hidden="true"
+                />
+                <span className="text-base font-semibold leading-6">{title}</span>
+              </DisclosureButton>
+              <DisclosurePanel as="dd" className="px-5 pb-5 pt-1 pl-12 prose prose-sm max-w-none">
+                <div className="text-base leading-7 text-[rgb(var(--ec-page-text-muted))]">{children}</div>
+              </DisclosurePanel>
+            </div>
+          );
+        }}
+      </Disclosure>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/MDX/Accordion/AccordionGroup.astro b/packages/core/eventcatalog/src/components/MDX/Accordion/AccordionGroup.astro
new file mode 100644
index 000000000..b723ffe66
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/Accordion/AccordionGroup.astro
@@ -0,0 +1,22 @@
+---
+
+---
+
+<div
+  class="accordion-group border border-[rgb(var(--ec-page-border))] rounded-lg overflow-hidden bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] my-3"
+>
+  <slot />
+</div>
+
+<style is:global>
+  .accordion-group .accordion {
+    border: none;
+    border-radius: 0;
+    box-shadow: none;
+    margin: 0;
+    background: transparent;
+  }
+  .accordion-group .accordion + .accordion {
+    border-top: 1px solid rgb(var(--ec-page-border));
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/components/MDX/Admonition.tsx b/packages/core/eventcatalog/src/components/MDX/Admonition.tsx
new file mode 100644
index 000000000..7aa4b813d
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/Admonition.tsx
@@ -0,0 +1,88 @@
+type AdmonitionType = 'danger' | 'alert' | 'warning' | 'info' | 'note' | 'tip';
+
+interface AdmonitionConfig {
+  iconPath: string;
+  title: string;
+  containerClasses: string;
+  accentClasses: string;
+}
+
+const getConfigurationByType = (type: string): AdmonitionConfig => {
+  switch (type) {
+    case 'danger':
+    case 'alert':
+      return {
+        iconPath: 'M7.86 2h8.28L22 7.86v8.28L16.14 22H7.86L2 16.14V7.86L7.86 2z M12 8v4 M12 16h.01',
+        title: type === 'danger' ? 'Danger' : 'Alert',
+        containerClasses: 'bg-red-50/60 dark:bg-red-950/30 border border-red-200/70 dark:border-red-900/60',
+        accentClasses: 'text-red-700 dark:text-red-300',
+      };
+    case 'warning':
+      return {
+        iconPath: 'M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0zM12 9v4 M12 17h.01',
+        title: 'Warning',
+        containerClasses: 'bg-amber-50/60 dark:bg-amber-950/30 border border-amber-200/70 dark:border-amber-900/60',
+        accentClasses: 'text-amber-700 dark:text-amber-300',
+      };
+    case 'note':
+      return {
+        iconPath: 'M12 20h9 M16.5 3.5a2.121 2.121 0 1 1 3 3L7 19l-4 1 1-4 12.5-12.5z',
+        title: 'Note',
+        containerClasses: 'bg-slate-50/70 dark:bg-slate-900/40 border border-slate-200/70 dark:border-slate-700/60',
+        accentClasses: 'text-slate-600 dark:text-slate-300',
+      };
+    case 'tip':
+      return {
+        iconPath: 'M9 18h6 M10 22h4 M12 2a7 7 0 0 0-4 12.74V17h8v-2.26A7 7 0 0 0 12 2z',
+        title: 'Tip',
+        containerClasses: 'bg-emerald-50/60 dark:bg-emerald-900/40 border border-emerald-200/70 dark:border-emerald-700/80',
+        accentClasses: 'text-emerald-700 dark:text-emerald-300',
+      };
+    default:
+      return {
+        iconPath: 'M12 2a10 10 0 100 20 10 10 0 000-20zM12 8h.01M11 12h1v4h1',
+        title: 'Info',
+        containerClasses: 'bg-blue-50/60 dark:bg-blue-950/30 border border-blue-200/70 dark:border-blue-900/60',
+        accentClasses: 'text-blue-700 dark:text-blue-300',
+      };
+  }
+};
+
+interface AdmonitionProps {
+  children: React.ReactNode;
+  type?: string;
+  className?: string;
+  title?: string;
+}
+
+export default function Admonition({ children, type = 'info', className = '', title }: AdmonitionProps) {
+  const config = getConfigurationByType(type);
+
+  return (
+    <div
+      className={`ec-admonition ${config.containerClasses} rounded-md px-3 py-2.5 my-4 text-[0.85rem] leading-relaxed not-prose ${className}`}
+    >
+      <div className={`flex items-center gap-1.5 mb-1 ${config.accentClasses}`}>
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="14"
+          height="14"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2.25"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          className="lucide shrink-0"
+          aria-hidden="true"
+        >
+          <path d={config.iconPath} />
+        </svg>
+        <span className="text-[0.7rem] font-semibold uppercase tracking-wider">{title || config.title}</span>
+      </div>
+      <div className="prose prose-sm dark:prose-invert w-full max-w-none! prose-p:my-0.5 prose-p:text-inherit prose-p:text-[0.85rem] prose-p:leading-relaxed prose-code:text-[0.8rem]">
+        {children}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/MDX/AgentTools/AgentTools.astro b/packages/core/eventcatalog/src/components/MDX/AgentTools/AgentTools.astro
new file mode 100644
index 000000000..3e6cb7b3a
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/AgentTools/AgentTools.astro
@@ -0,0 +1,132 @@
+---
+import type { CollectionEntry } from 'astro:content';
+import Admonition from '../Admonition';
+import { buildUrl } from '@utils/url-builder';
+
+type AgentTool = {
+  name: string;
+  type: string;
+  icon?: string;
+  url?: string;
+  description?: string;
+};
+
+export interface Props extends CollectionEntry<'agents'> {}
+
+const { data, collection } = Astro.props;
+const tools = (data?.tools || []) as AgentTool[];
+const isComponentEnabled = collection === 'agents';
+const mcpLogoLightUrl = buildUrl('/icons/protocols/mcp-light.svg', true);
+const mcpLogoDarkUrl = buildUrl('/icons/protocols/mcp-dark.svg', true);
+
+const getToolUrlLabel = (url: string) => {
+  try {
+    const parsedUrl = new URL(url);
+    const pathParts = parsedUrl.pathname.split('/').filter(Boolean);
+    const compactPath =
+      pathParts.length > 1 ? `/.../${pathParts[pathParts.length - 1]}` : parsedUrl.pathname === '/' ? '' : parsedUrl.pathname;
+
+    return `${parsedUrl.hostname}${compactPath}`;
+  } catch {
+    return url;
+  }
+};
+
+const isMcpTool = (tool: AgentTool) => tool.type?.toLowerCase() === 'mcp';
+---
+
+{
+  !isComponentEnabled && (
+    <Admonition type="warning">
+      <div>
+        <span class="font-bold">
+          {`<AgentTools/>`} component is not supported for resources of type {collection}.
+        </span>
+        <span class="block">This component is only supported for agents.</span>
+      </div>
+    </Admonition>
+  )
+}
+
+{
+  isComponentEnabled && tools.length > 0 ? (
+    <div class="overflow-x-auto relative not-prose">
+      <table class="w-full table-fixed text-sm text-left text-[rgb(var(--ec-page-text-muted))] border border-[rgb(var(--ec-page-border))] rounded-lg shadow-xs">
+        <colgroup>
+          <col class="w-[26%]" />
+          <col class="w-[12%]" />
+          <col class="w-[44%]" />
+          <col class="w-[18%]" />
+        </colgroup>
+        <thead class="text-xs text-[rgb(var(--ec-page-text))] uppercase bg-[rgb(var(--ec-content-hover))]">
+          <tr>
+            <th scope="col" class="py-3 px-6">
+              Name
+            </th>
+            <th scope="col" class="py-3 px-6">
+              Type
+            </th>
+            <th scope="col" class="py-3 px-6 min-w-[250px]">
+              Description
+            </th>
+            <th scope="col" class="py-3 px-6">
+              URL
+            </th>
+          </tr>
+        </thead>
+        <tbody>
+          {tools.map((tool) => (
+            <tr class="bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border-b border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-content-hover))] align-top">
+              <td class="py-4 px-6 font-medium text-[rgb(var(--ec-page-text))]">{tool.name}</td>
+              <td class="py-4 px-6">
+                <span class="inline-flex items-center rounded-md bg-sky-500/10 px-2 py-1 text-xs font-medium uppercase text-sky-500 ring-1 ring-inset ring-sky-500/20">
+                  {isMcpTool(tool) && (
+                    <>
+                      <img
+                        src={mcpLogoLightUrl}
+                        alt=""
+                        class="mr-1.5 h-3 w-3 shrink-0 object-contain dark:hidden"
+                        loading="lazy"
+                      />
+                      <img
+                        src={mcpLogoDarkUrl}
+                        alt=""
+                        class="mr-1.5 hidden h-3 w-3 shrink-0 object-contain dark:inline-block"
+                        loading="lazy"
+                      />
+                    </>
+                  )}
+                  {isMcpTool(tool) ? 'MCP' : tool.type}
+                </span>
+              </td>
+              <td class="py-4 px-6 text-[rgb(var(--ec-page-text-muted))]">
+                {tool.description || <span class="text-[rgb(var(--ec-icon-color))] italic">No description provided.</span>}
+              </td>
+              <td class="py-4 px-6 text-[rgb(var(--ec-page-text-muted))]">
+                {tool.url ? (
+                  <a
+                    href={tool.url}
+                    class="inline-flex max-w-full items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover))] px-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text))] hover:border-[rgb(var(--ec-accent))] hover:text-[rgb(var(--ec-accent))]"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    title={tool.url}
+                  >
+                    <span class="truncate">{getToolUrlLabel(tool.url)}</span>
+                  </a>
+                ) : (
+                  <span class="text-[rgb(var(--ec-icon-color))]">-</span>
+                )}
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  ) : (
+    isComponentEnabled && (
+      <Admonition type="note" title="No Tools Defined">
+        <p>There are no tools defined for this agent.</p>
+      </Admonition>
+    )
+  )
+}
diff --git a/eventcatalog/src/components/MDX/AsyncAPI/AsyncAPI.astro b/packages/core/eventcatalog/src/components/MDX/AsyncAPI/AsyncAPI.astro
similarity index 100%
rename from eventcatalog/src/components/MDX/AsyncAPI/AsyncAPI.astro
rename to packages/core/eventcatalog/src/components/MDX/AsyncAPI/AsyncAPI.astro
diff --git a/packages/core/eventcatalog/src/components/MDX/Attachments.astro b/packages/core/eventcatalog/src/components/MDX/Attachments.astro
new file mode 100644
index 000000000..1024727b5
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/Attachments.astro
@@ -0,0 +1,162 @@
+---
+import type { ComponentType } from 'react';
+import * as Icons from '@heroicons/react/24/outline';
+import * as SolidIcons from '@heroicons/react/24/solid';
+import * as LucideIcons from 'lucide-react';
+
+interface AttachmentObject {
+  url: string;
+  title?: string;
+  type?: string;
+  description?: string;
+  summary?: string;
+  icon?: string;
+}
+
+type Attachment = string | AttachmentObject;
+
+interface Props {
+  title?: string;
+  description?: string;
+  columns?: number;
+  data?: {
+    attachments?: Attachment[];
+  };
+}
+
+const { title = 'Attachments', description, columns = 2, ...props } = Astro.props;
+const attachments = props.data?.attachments ?? [];
+
+function getIconForAttachment(attachment: AttachmentObject): ComponentType<{ className?: string }> | null {
+  // If custom icon is provided, try to find it
+  if (attachment.icon) {
+    const customIcon =
+      (LucideIcons as any)[attachment.icon] || (Icons as any)[attachment.icon] || (SolidIcons as any)[attachment.icon];
+    if (customIcon) return customIcon;
+  }
+
+  // Default to link icon for all attachments
+  return Icons.LinkIcon;
+}
+
+function normalizeAttachment(attachment: Attachment): AttachmentObject {
+  if (typeof attachment === 'string') {
+    // Extract filename from URL for title
+    const urlParts = attachment.split('/');
+    const filename = urlParts[urlParts.length - 1];
+    const title = filename.includes('.') ? filename.split('.')[0] : filename || 'Link';
+
+    return {
+      url: attachment,
+      title: title.replace(/[-_]/g, ' ').replace(/\b\w/g, (l) => l.toUpperCase()),
+    };
+  }
+  return attachment;
+}
+
+function isExternalUrl(url: string): boolean {
+  return url.startsWith('http://') || url.startsWith('https://');
+}
+
+const normalizedAttachments = attachments.map(normalizeAttachment);
+
+// Group attachments by type
+const groupedAttachments = normalizedAttachments.reduce(
+  (groups, attachment) => {
+    const type = attachment.type || 'Other';
+    if (!groups[type]) {
+      groups[type] = [];
+    }
+    groups[type].push(attachment);
+    return groups;
+  },
+  {} as Record<string, AttachmentObject[]>
+);
+
+const sortedGroups = Object.entries(groupedAttachments).sort(([a], [b]) => {
+  if (a === 'Other') return 1;
+  if (b === 'Other') return -1;
+  return a.localeCompare(b);
+});
+---
+
+<section class="not-prose my-8">
+  {title && <h3 class="flex items-center gap-2 text-3xl font-bold mb-4">{title}</h3>}
+
+  {description && <p class="text-[rgb(var(--ec-page-text-muted))] mb-6 prose prose-md">{description}</p>}
+
+  {
+    normalizedAttachments.length === 0 ? (
+      <div class="text-[rgb(var(--ec-page-text-muted))] text-sm italic">No attachments available.</div>
+    ) : (
+      <div class="space-y-6">
+        {sortedGroups.map(([groupType, groupAttachments], index) => (
+          <div>
+            <h4 class="text-sm font-medium text-[rgb(var(--ec-page-text))] mb-3 uppercase tracking-wider">
+              {groupType} ({groupAttachments.length})
+            </h4>
+            <div class={`grid grid-cols-1 ${columns === 1 ? '' : `md:grid-cols-${Math.min(columns, 3)}`} gap-4`}>
+              {groupAttachments.map((attachment) => {
+                const IconComponent = getIconForAttachment(attachment);
+                const isExternal = isExternalUrl(attachment.url);
+
+                return (
+                  <a
+                    href={attachment.url}
+                    target={isExternal ? '_blank' : '_self'}
+                    rel={isExternal ? 'noopener noreferrer' : undefined}
+                    class="group block bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-lg p-4 transition-all duration-200 hover:shadow-md hover:border-[rgb(var(--ec-accent)/0.5)] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:ring-offset-2"
+                  >
+                    <div class="flex items-start gap-3">
+                      <div class="flex-shrink-0 p-2 bg-[rgb(var(--ec-content-hover))] rounded-lg group-hover:bg-[rgb(var(--ec-accent-subtle))] transition-colors duration-200">
+                        {IconComponent && (
+                          <IconComponent className="w-5 h-5 text-[rgb(var(--ec-icon-color))] group-hover:text-[rgb(var(--ec-accent))]" />
+                        )}
+                      </div>
+
+                      <div class="flex-grow min-w-0">
+                        <div class="flex items-center gap-2">
+                          <h5 class="text-sm font-medium text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-accent))] truncate">
+                            {attachment.title || 'Attachment'}
+                          </h5>
+                          {isExternal && (
+                            <Icons.ArrowTopRightOnSquareIcon className="w-3 h-3 text-[rgb(var(--ec-icon-color))] group-hover:text-[rgb(var(--ec-accent))] flex-shrink-0" />
+                          )}
+                        </div>
+
+                        {attachment.summary && (
+                          <p class="mt-1 text-xs text-[rgb(var(--ec-page-text-muted))] group-hover:text-[rgb(var(--ec-accent-text))] line-clamp-2">
+                            {attachment.summary}
+                          </p>
+                        )}
+
+                        {attachment.description && (
+                          <p class="mt-1 text-xs text-[rgb(var(--ec-page-text-muted))] group-hover:text-[rgb(var(--ec-accent-text))] line-clamp-2">
+                            {attachment.description}
+                          </p>
+                        )}
+
+                        <div class="mt-2 text-xs text-[rgb(var(--ec-icon-color))] group-hover:text-[rgb(var(--ec-accent))] truncate">
+                          {attachment.url.replace(/^https?:\/\//, '')}
+                        </div>
+                      </div>
+                    </div>
+                  </a>
+                );
+              })}
+            </div>
+          </div>
+        ))}
+      </div>
+    )
+  }
+</section>
+
+<style>
+  .line-clamp-2 {
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/components/MDX/ChannelInformation/ChannelInformation.tsx b/packages/core/eventcatalog/src/components/MDX/ChannelInformation/ChannelInformation.tsx
new file mode 100644
index 000000000..25b262077
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/ChannelInformation/ChannelInformation.tsx
@@ -0,0 +1,79 @@
+import type { CollectionEntry } from 'astro:content';
+import { getIconForProtocol } from '@utils/protocols';
+
+const ChannelParameters = (data: CollectionEntry<'channels'>['data']) => {
+  return (
+    <div className="container mx-auto py-4 not-prose space-y-4">
+      <div>
+        <h4 className="text-2xl font-bold text-[rgb(var(--ec-page-text))]">Channel information</h4>
+      </div>
+
+      <div>
+        <p className="text-md text-[rgb(var(--ec-page-text))]">
+          {data.address && (
+            <div>
+              <span className="font-semibold">Address:</span>{' '}
+              <code className="bg-[rgb(var(--ec-content-hover))] p-1 rounded text-[rgb(var(--ec-page-text))]">
+                {data.address}
+              </code>
+            </div>
+          )}
+          {data.protocols && data.protocols.length > 0 && (
+            <div className="mt-2 flex items-center space-x-1">
+              <span className="font-semibold">{data.protocols.length > 1 ? 'Protocols:' : 'Protocol:'}</span>
+              <ul className="space-x-2 flex">
+                {data.protocols.map((protocol) => {
+                  const IconComponent = getIconForProtocol(protocol.toLowerCase());
+                  return (
+                    <li
+                      key={protocol}
+                      className="text-sm flex items-center space-x-1 bg-[rgb(var(--ec-content-hover))] rounded-md px-1"
+                    >
+                      {IconComponent && <IconComponent className="w-4 h-4" />}
+                      <span>{protocol}</span>
+                    </li>
+                  );
+                })}
+              </ul>
+            </div>
+          )}
+        </p>
+      </div>
+
+      {data.parameters && Object.keys(data.parameters).length > 0 && (
+        <div className="overflow-x-auto">
+          <table className="min-w-full bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))]">
+            <thead>
+              <tr className="bg-[rgb(var(--ec-accent))] text-white">
+                <th className="py-2 px-4 border-b border-[rgb(var(--ec-page-border))] text-left">Parameter</th>
+                <th className="py-2 px-4 border-b border-[rgb(var(--ec-page-border))] text-left">Description</th>
+                <th className="py-2 px-4 border-b border-[rgb(var(--ec-page-border))] text-left">Options</th>
+                <th className="py-2 px-4 border-b border-[rgb(var(--ec-page-border))] text-left">Default</th>
+              </tr>
+            </thead>
+            <tbody>
+              {Object.entries(data.parameters).map(([param, details]) => (
+                <tr className="hover:bg-[rgb(var(--ec-content-hover))]" key={param}>
+                  <td className="py-2 px-4 border-b border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text))]">
+                    {param}
+                  </td>
+                  <td className="py-2 px-4 border-b border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text-muted))]">
+                    {details.description}
+                  </td>
+                  <td className="py-2 px-4 border-b border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text-muted))]">
+                    {details.enum ? details.enum.join(', ') : 'N/A'}
+                  </td>
+                  <td className="py-2 px-4 border-b border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text-muted))]">
+                    {details.default || 'N/A'}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default ChannelParameters;
diff --git a/packages/core/eventcatalog/src/components/MDX/ContextDiagram/ContextDiagramPortal.tsx b/packages/core/eventcatalog/src/components/MDX/ContextDiagram/ContextDiagramPortal.tsx
new file mode 100644
index 000000000..4d3ada49f
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/ContextDiagram/ContextDiagramPortal.tsx
@@ -0,0 +1,21 @@
+/**
+ * Placeholder div the Context Diagram graph is portaled into.
+ *
+ * Mirrors NodeGraphPortal, but uses a distinct `-context-diagram-portal` id so a
+ * system page can render both its System Diagram (the default `<NodeGraph />`)
+ * and its Context Diagram (`<ContextDiagram />`) without the two graphs fighting
+ * over the same portal target.
+ */
+const ContextDiagramPortal = (props: any) => {
+  return (
+    <div
+      className="not-prose h-[30em] my-6 mb-12 w-full relative border! border-[rgb(var(--ec-page-border))]! rounded-md overflow-hidden"
+      id={`${props.id}-context-diagram-portal`}
+      style={{
+        maxHeight: props.maxHeight ? `${props.maxHeight}em` : `30em`,
+      }}
+    />
+  );
+};
+
+export default ContextDiagramPortal;
diff --git a/packages/core/eventcatalog/src/components/MDX/Design/Design.astro b/packages/core/eventcatalog/src/components/MDX/Design/Design.astro
new file mode 100644
index 000000000..2960dd088
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/Design/Design.astro
@@ -0,0 +1,81 @@
+---
+const { file: designPath, filePath, search = true, title } = Astro.props;
+import fs from 'fs';
+import { getAbsoluteFilePathForAstroFile } from '@utils/files';
+import Admonition from '@components/MDX/Admonition';
+import AstroNodeGraph from '../NodeGraph/AstroNodeGraph';
+
+import { isVisualiserEnabled, isEventCatalogChatEnabled, isDevMode } from '@utils/feature';
+import { loadSavedLayout, applyLayoutToNodes, buildResourceKey } from '@utils/node-graphs/layout-persistence';
+
+const isChatEnabled = isEventCatalogChatEnabled();
+
+let design: any;
+let id = 'design';
+let maxHeight = 30;
+
+try {
+  const fileName = designPath.endsWith('.ecstudio') ? designPath : `${designPath}.ecstudio`;
+  const pathToSpec = getAbsoluteFilePathForAstroFile(filePath, fileName);
+  const designFile = fs.readFileSync(pathToSpec, 'utf8');
+  design = JSON.parse(designFile);
+} catch (error) {
+  console.error(`Error reading design file: ${error}`);
+}
+
+// Load and apply saved layout if it exists
+const resourceKey = design ? buildResourceKey('designs', design.id || id) : '';
+const savedLayout = resourceKey ? await loadSavedLayout(resourceKey) : null;
+const nodesWithLayout = design ? applyLayoutToNodes(design.nodes || [], savedLayout) : ([] as any[]);
+---
+
+{
+  !design && (
+    <Admonition type="warning">
+      <div>
+        <span class="block font-bold">{`<Design/>`} failed to load</span>
+        <span class="block">
+          Tried to load design file: {designPath}. Make sure you have this design file defined in your project.
+        </span>
+      </div>
+    </Admonition>
+  )
+}
+
+{
+  design && (
+    <div>
+      <div
+        class="h-[30em] my-6 mb-12 w-full relative border border-[rgb(var(--ec-page-border))] rounded-md"
+        id={`${id}-portal`}
+        style={{
+          maxHeight: maxHeight ? `${maxHeight}em` : `30em`,
+        }}
+      />
+
+      <div>
+        <AstroNodeGraph
+          id={id}
+          title={title ?? design.name}
+          nodes={nodesWithLayout}
+          edges={design.edges || []}
+          hrefLabel={isVisualiserEnabled() ? 'View in visualizer' : undefined}
+          href={isVisualiserEnabled() ? `/visualiser/designs/${design.id}` : undefined}
+          linkTo={'visualiser'}
+          designId={design.id || id}
+          client:only="react"
+          showSearch={search}
+          isChatEnabled={isChatEnabled}
+          isDevMode={isDevMode()}
+          resourceKey={resourceKey}
+        />
+      </div>
+    </div>
+  )
+}
+
+<style is:global>
+  .react-flow__attribution {
+    display: none;
+  }
+</style>
diff --git a/eventcatalog/src/components/MDX/DrawIO/DrawIO.astro b/packages/core/eventcatalog/src/components/MDX/DrawIO/DrawIO.astro
similarity index 100%
rename from eventcatalog/src/components/MDX/DrawIO/DrawIO.astro
rename to packages/core/eventcatalog/src/components/MDX/DrawIO/DrawIO.astro
diff --git a/packages/core/eventcatalog/src/components/MDX/EntityMap/EntityMap.astro b/packages/core/eventcatalog/src/components/MDX/EntityMap/EntityMap.astro
new file mode 100644
index 000000000..24d76536c
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/EntityMap/EntityMap.astro
@@ -0,0 +1,93 @@
+---
+import { getDomains } from '@utils/collections/domains';
+import { getNodesAndEdges } from '@utils/node-graphs/domain-entity-map.ts';
+import Admonition from '@components/MDX/Admonition';
+import AstroNodeGraph from '../NodeGraph/AstroNodeGraph';
+import { getVersionFromCollection } from '@utils/collections/versions';
+import { getServices } from '@utils/collections/services';
+import { isEventCatalogChatEnabled, isDevMode } from '@utils/feature';
+import { loadSavedLayout, applyLayoutToNodes, buildResourceKey } from '@utils/node-graphs/layout-persistence';
+
+const isChatEnabled = isEventCatalogChatEnabled();
+
+const { id, version = 'latest', maxHeight, includeKey = true, entities, collection = 'domains', ...rest } = Astro.props;
+let resource = null;
+
+let resourceId = id;
+
+// If the user did not provide an id, we need to use the id from the rest props (the collection)
+const isAstroGeneratedId = id.match(/-\d+\.\d+\.\d+$/);
+if (isAstroGeneratedId) {
+  resourceId = rest.data.id;
+}
+
+if (collection === 'domains') {
+  const domains = await getDomains();
+  const domainCollection = getVersionFromCollection(domains, resourceId, version) || [];
+  resource = domainCollection[0];
+} else if (collection === 'services') {
+  const services = await getServices();
+  const serviceCollection = getVersionFromCollection(services, resourceId, version) || [];
+  resource = serviceCollection[0];
+} else {
+  throw new Error(`Invalid collection: ${collection}`);
+}
+
+const { nodes, edges } = await getNodesAndEdges({
+  id: resourceId,
+  version: resource?.data?.version,
+  ...(entities ? { entities } : {}), // Pass entities if provided
+  type: collection,
+});
+
+// Load and apply saved layout if it exists
+const resourceKey = buildResourceKey(collection, resourceId, resource?.data?.version);
+const savedLayout = await loadSavedLayout(resourceKey);
+const nodesWithLayout = applyLayoutToNodes(nodes as any[], savedLayout);
+---
+
+{
+  !resource && (
+    <Admonition type="warning">
+      <div>
+        <span class="block font-bold">{`<EntityMap/>`} failed to load</span>
+        <span class="block">
+          Tried to load {collection} id: {id} with version {version}. Make sure you have this {collection} defined in your
+          project.
+        </span>
+      </div>
+    </Admonition>
+  )
+}
+
+<div
+  class="h-[30em] my-6 mb-12 w-full relative border border-[rgb(var(--ec-page-border))] rounded-md"
+  id={`${id}-entity-map-portal`}
+  style={{
+    maxHeight: maxHeight ? `${maxHeight}em` : `30em`,
+  }}
+>
+</div>
+
+<div>
+  <AstroNodeGraph
+    id={id}
+    nodes={nodesWithLayout}
+    edges={edges}
+    linkTo={'visualiser'}
+    mode="simple"
+    includeKey={includeKey}
+    footerLabel={`Entity Map - ${resource?.data?.name} - v(${resource?.data?.version})`}
+    client:only="react"
+    portalId={`${id}-entity-map-portal`}
+    isChatEnabled={isChatEnabled}
+    isDevMode={isDevMode()}
+    resourceKey={resourceKey}
+  />
+</div>
+
+<style is:global>
+  .react-flow__attribution {
+    display: none;
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/components/MDX/EntityPropertiesTable/EntityPropertiesTable.astro b/packages/core/eventcatalog/src/components/MDX/EntityPropertiesTable/EntityPropertiesTable.astro
new file mode 100644
index 000000000..560afc10f
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/EntityPropertiesTable/EntityPropertiesTable.astro
@@ -0,0 +1,113 @@
+---
+import type { CollectionEntry } from 'astro:content';
+import Admonition from '../Admonition';
+
+// Define the shape for a single property used in this component
+type EntityProperty = {
+  name: string;
+  type: string;
+  required?: boolean;
+  description?: string;
+  enum?: string[];
+  items?: {
+    type: string;
+  };
+};
+
+// Expects a CollectionEntry for 'entities'.
+// The actual properties structure might differ slightly from the base type,
+// so we handle it below.
+export interface Props extends CollectionEntry<'entities'> {}
+
+const { data, collection } = Astro.props;
+// Cast the properties to our expected type for use in the template
+const properties = data?.properties as EntityProperty[] | undefined;
+const isComponentEnabled = collection === 'entities';
+---
+
+{
+  !isComponentEnabled && (
+    <Admonition type="warning">
+      <div>
+        <span class="font-bold">
+          {`<MessageTable/>`} component is not supported for resources of type {collection}.
+        </span>
+        <span class="block">This component is only supported for services and domains.</span>
+      </div>
+    </Admonition>
+  )
+}
+
+{
+  isComponentEnabled && properties && properties.length > 0 ? (
+    <div class="overflow-x-auto relative not-prose">
+      <table class="w-full text-sm text-left text-[rgb(var(--ec-page-text-muted))] border border-[rgb(var(--ec-page-border))] rounded-lg shadow-xs">
+        <thead class="text-xs text-[rgb(var(--ec-page-text))] uppercase bg-[rgb(var(--ec-content-hover))]">
+          <tr>
+            <th scope="col" class="py-3 px-6">
+              Name
+            </th>
+            <th scope="col" class="py-3 px-6">
+              Type
+            </th>
+            <th scope="col" class="py-3 px-6">
+              Required
+            </th>
+            <th scope="col" class="py-3 px-6 min-w-[250px]">
+              Description
+            </th>
+          </tr>
+        </thead>
+        <tbody>
+          {properties.map((prop) => (
+            <tr class="bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border-b border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-content-hover))] align-top">
+              <td class="py-4 px-6 font-medium text-[rgb(var(--ec-page-text))] whitespace-nowrap">
+                <code class="text-sm bg-[rgb(var(--ec-content-hover))] rounded px-1 py-0.5">{prop.name}</code>
+              </td>
+              <td class="py-4 px-6 text-[rgb(var(--ec-page-text-muted))]">
+                {prop.type === 'array' && prop.items ? (
+                  <span>
+                    array&lt;<code class="text-sm bg-[rgb(var(--ec-content-hover))] rounded px-1 py-0.5">{prop.items.type}</code>
+                    &gt;
+                  </span>
+                ) : (
+                  <code class="text-sm bg-[rgb(var(--ec-content-hover))] rounded px-1 py-0.5">{prop.type}</code>
+                )}
+                {prop.enum && (
+                  <div class="text-xs text-[rgb(var(--ec-page-text-muted))] mt-2">
+                    <span class="font-semibold block mb-1">Enum:</span>
+                    <ul class="list-disc list-inside ml-2 space-y-1">
+                      {prop.enum.map((enumValue: string) => (
+                        <li>
+                          <code class="text-xs bg-[rgb(var(--ec-content-hover))] rounded px-1 py-0.5">{enumValue}</code>
+                        </li>
+                      ))}
+                    </ul>
+                  </div>
+                )}
+              </td>
+              <td class="py-4 px-6">
+                {prop.required ? (
+                  <span class="bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent-text))] text-xs font-semibold mr-2 px-2.5 py-0.5 rounded">
+                    Required
+                  </span>
+                ) : (
+                  <span class="bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-page-text-muted))] text-xs font-semibold mr-2 px-2.5 py-0.5 rounded">
+                    Optional
+                  </span>
+                )}
+              </td>
+              <td class="py-4 px-6 text-[rgb(var(--ec-page-text-muted))]">
+                {prop.description || <span class="text-[rgb(var(--ec-icon-color))] italic">No description provided.</span>}
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  ) : (
+    <Admonition type="note" title="No Properties Defined">
+      <p>There are no properties defined for this entity.</p>
+    </Admonition>
+  )
+}
diff --git a/eventcatalog/src/components/MDX/FigJam/FigJam.astro b/packages/core/eventcatalog/src/components/MDX/FigJam/FigJam.astro
similarity index 100%
rename from eventcatalog/src/components/MDX/FigJam/FigJam.astro
rename to packages/core/eventcatalog/src/components/MDX/FigJam/FigJam.astro
diff --git a/packages/core/eventcatalog/src/components/MDX/File.tsx b/packages/core/eventcatalog/src/components/MDX/File.tsx
new file mode 100644
index 000000000..a92156c77
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/File.tsx
@@ -0,0 +1,43 @@
+import { resourceFileExists, readResourceFile, getResourceFilePath } from '@utils/resource-files';
+
+const File = ({ file, filePath, title }: any) => {
+  try {
+    const item = { filePath };
+    const exists = resourceFileExists(item, file);
+
+    if (exists) {
+      const text = readResourceFile(item, file);
+      return (
+        <div className="not-prose">
+          <pre className="expressive-code" data-language="json">
+            <figure className="frame has-title">
+              <figcaption className="header">
+                {title && <span className="title">{title}</span>}
+                {!title && <span className="title">{file}</span>}
+              </figcaption>
+              <pre data-language="js">
+                <code>
+                  <div className="ec-line">
+                    <div className="code">{text}</div>
+                  </div>
+                </code>
+              </pre>
+              <div className="copy">
+                <button title="Copy to clipboard" data-copied="Copied!" data-code={text ?? ''}>
+                  <div></div>
+                </button>
+              </div>
+            </figure>
+          </pre>
+        </div>
+      );
+    } else {
+      return <div className="italic">Tried to load file from {getResourceFilePath(item, file)}, but no file can be found</div>;
+    }
+  } catch (error) {
+    console.log('Failed to load file', error);
+    return null;
+  }
+};
+
+export default File;
diff --git a/packages/core/eventcatalog/src/components/MDX/Flow/Flow.astro b/packages/core/eventcatalog/src/components/MDX/Flow/Flow.astro
new file mode 100644
index 000000000..18122f3e2
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/Flow/Flow.astro
@@ -0,0 +1,82 @@
+---
+import { getFlows } from '@utils/collections/flows';
+import { getNodesAndEdges } from '@utils/node-graphs/flows-node-graph';
+import Admonition from '@components/MDX/Admonition';
+import AstroNodeGraph from '../NodeGraph/AstroNodeGraph';
+import { getVersionFromCollection } from '@utils/collections/versions';
+import { isVisualiserEnabled, isEventCatalogChatEnabled, isDevMode } from '@utils/feature';
+import { loadSavedLayout, applyLayoutToNodes, buildResourceKey } from '@utils/node-graphs/layout-persistence';
+import { randomUUID } from 'node:crypto';
+import { parseMdxBooleanProp } from '@utils/markdown';
+
+const isChatEnabled = isEventCatalogChatEnabled();
+
+const { id, version = 'latest', maxHeight, mode = 'simple' } = Astro.props;
+const includeKey = parseMdxBooleanProp(Astro.props.legend ?? Astro.props.includeKey, true);
+const search = parseMdxBooleanProp(Astro.props.search, false);
+const walkthrough = parseMdxBooleanProp(Astro.props.walkthrough, false);
+
+// Find the flow for the given id and version
+const flows = await getFlows();
+const flowCollection = getVersionFromCollection(flows, id, version) || [];
+const flow = flowCollection[0];
+
+// const flow = flows.find((flow) => flow.data.id === id && flow.data.version === version);
+
+const { nodes, edges } = await getNodesAndEdges({
+  id: id,
+  version: flow.data.version,
+  mode: mode,
+});
+
+// Load and apply saved layout if it exists
+const resourceKey = buildResourceKey('flows', id, flow.data.version);
+const savedLayout = await loadSavedLayout(resourceKey);
+const nodesWithLayout = applyLayoutToNodes(nodes, savedLayout);
+const portalId = `${id}-${flow.data.version}-flow-${randomUUID()}-portal`;
+---
+
+{
+  !flow && (
+    <Admonition type="warning">
+      <div>
+        <span class="block font-bold">{`<Flow/>`} failed to load</span>
+        <span class="block">
+          Tried to load flow id: {id} with version {version}. Make sure you have this flow defined in your project.
+        </span>
+      </div>
+    </Admonition>
+  )
+}
+
+<div
+  class="h-[30em] my-6 mb-12 w-full relative border border-[rgb(var(--ec-page-border))] rounded-md"
+  id={portalId}
+  style={{
+    maxHeight: maxHeight ? `${maxHeight}em` : `30em`,
+  }}
+>
+</div>
+
+<div>
+  <AstroNodeGraph
+    id={id}
+    nodes={nodesWithLayout}
+    edges={edges}
+    mode={mode}
+    includeKey={includeKey}
+    client:only="react"
+    portalId={portalId}
+    showFlowWalkthrough={walkthrough}
+    showSearch={search}
+    isChatEnabled={isChatEnabled}
+    isDevMode={isDevMode()}
+    resourceKey={resourceKey}
+  />
+</div>
+
+<style is:global>
+  .react-flow__attribution {
+    display: none;
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/components/MDX/IcePanel/IcePanel.astro b/packages/core/eventcatalog/src/components/MDX/IcePanel/IcePanel.astro
new file mode 100644
index 000000000..ce6aaae0e
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/IcePanel/IcePanel.astro
@@ -0,0 +1,77 @@
+---
+import Admonition from '@components/MDX/Admonition';
+import { buildUrl, buildUrlWithParams } from '@utils/url-builder';
+import type { CollectionEntry } from 'astro:content';
+import { ExpandIcon } from 'lucide-react';
+
+interface Props {
+  title?: string;
+  description?: string;
+  height?: string;
+  width?: string;
+  url: string;
+}
+
+const { title, description, height = '600', width = '100%', url, ...eventCatalogResource } = Astro.props;
+
+const resource = eventCatalogResource as CollectionEntry<'services'>;
+
+// Validate that the URL is from IcePanel
+const isValidIcePanelUrl = url?.startsWith('https://s.icepanel.io/') || url?.startsWith('https://icepanel.io/');
+
+const backUrl = resource.collection
+  ? buildUrl(`/docs/${resource.collection}/${resource.data.id}/${resource.data.version}#${title}-icepanel-title`)
+  : undefined;
+
+const fullScreenParams = {
+  url: url,
+  title: title,
+  back: backUrl,
+};
+
+const openFullScreenUrl = buildUrlWithParams(`/icepanel`, fullScreenParams);
+---
+
+{
+  !url && (
+    <Admonition type="warning">
+      <div>
+        <span class="block font-bold">{`<IcePanel/>`} failed to load</span>
+        <span class="block">Please provide a url to use the IcePanel component.</span>
+      </div>
+    </Admonition>
+  )
+}
+
+{
+  url && !isValidIcePanelUrl && (
+    <Admonition type="warning">
+      <div>
+        <span class="block font-bold">{`<IcePanel/>`} invalid URL</span>
+        <span class="block">Please provide a valid IcePanel URL (e.g., https://s.icepanel.io/...).</span>
+      </div>
+    </Admonition>
+  )
+}
+
+{
+  url && isValidIcePanelUrl && (
+    <div>
+      {title && (
+        <h3 id={`${title}-icepanel-title`} class="text-3xl font-bold">
+          {title}
+        </h3>
+      )}
+      {description && <p class="text-[rgb(var(--ec-page-text-muted))] mb-3">{description}</p>}
+      <div class="relative">
+        <iframe class="rounded-2xl border-none" src={url} width={width} height={height} title={title || 'IcePanel Diagram'} />
+        <a
+          href={openFullScreenUrl}
+          class="absolute bottom-[15px] right-5 bg-[rgb(var(--ec-card-bg))] border border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle))] px-4 py-2 rounded-md transition-colors"
+        >
+          <ExpandIcon className="w-5 h-5" />
+        </a>
+      </div>
+    </div>
+  )
+}
diff --git a/packages/core/eventcatalog/src/components/MDX/LikeC4View/LikeC4View.astro b/packages/core/eventcatalog/src/components/MDX/LikeC4View/LikeC4View.astro
new file mode 100644
index 000000000..28794aa59
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/LikeC4View/LikeC4View.astro
@@ -0,0 +1,13 @@
+---
+import LikeC4ViewWrapper from './LikeC4ViewWrapper';
+
+interface Props {
+  viewId: string;
+  project?: string;
+  height?: string;
+}
+
+const { viewId, project, height } = Astro.props;
+---
+
+<LikeC4ViewWrapper viewId={viewId} project={project} height={height} client:only="react" />
diff --git a/packages/core/eventcatalog/src/components/MDX/LikeC4View/LikeC4ViewWrapper.tsx b/packages/core/eventcatalog/src/components/MDX/LikeC4View/LikeC4ViewWrapper.tsx
new file mode 100644
index 000000000..003e39692
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/LikeC4View/LikeC4ViewWrapper.tsx
@@ -0,0 +1,52 @@
+import { lazy, Suspense, useMemo, type ComponentType } from 'react';
+import { getProjectLoader } from 'virtual:likec4-projects';
+
+interface LikeC4ViewWrapperProps {
+  viewId: string;
+  project?: string;
+  height?: string;
+}
+
+interface LikeC4ViewProps {
+  viewId: string;
+  controls?: boolean;
+  browser?: {
+    enableFocusMode?: boolean;
+    enableSearch?: boolean;
+  };
+}
+
+const lazyComponentCache = new Map<string, ComponentType<LikeC4ViewProps>>();
+
+const getLazyComponent = (project: string): ComponentType<LikeC4ViewProps> => {
+  const key = project || 'default';
+
+  if (!lazyComponentCache.has(key)) {
+    const loader = getProjectLoader(key);
+    const LazyComponent = lazy(() => loader().then((mod) => ({ default: mod.LikeC4View })));
+    lazyComponentCache.set(key, LazyComponent);
+  }
+
+  return lazyComponentCache.get(key)!;
+};
+
+export default function LikeC4ViewWrapper({ viewId, project, height = '600px' }: LikeC4ViewWrapperProps) {
+  const LikeC4ViewComponent = useMemo(() => getLazyComponent(project || 'default'), [project]);
+
+  return (
+    <div style={{ height, maxHeight: height }} className="w-full overflow-hidden rounded-lg border border-gray-200">
+      <Suspense
+        fallback={<div className="flex h-full items-center justify-center rounded-lg bg-gray-100">Loading diagram...</div>}
+      >
+        <LikeC4ViewComponent
+          viewId={viewId}
+          controls={false}
+          browser={{
+            enableFocusMode: false,
+            enableSearch: false,
+          }}
+        />
+      </Suspense>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/MDX/Link/Link.astro b/packages/core/eventcatalog/src/components/MDX/Link/Link.astro
new file mode 100644
index 000000000..184427731
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/Link/Link.astro
@@ -0,0 +1,7 @@
+---
+import { buildUrl } from '@utils/url-builder';
+
+const { href } = Astro.props;
+---
+
+<a href={buildUrl(href)} class="text-[rgb(var(--ec-accent))] hover:text-[rgb(var(--ec-accent-hover))]"><slot /></a>
diff --git a/eventcatalog/src/components/MDX/Lucid/Lucid.astro b/packages/core/eventcatalog/src/components/MDX/Lucid/Lucid.astro
similarity index 100%
rename from eventcatalog/src/components/MDX/Lucid/Lucid.astro
rename to packages/core/eventcatalog/src/components/MDX/Lucid/Lucid.astro
diff --git a/eventcatalog/src/components/MDX/MermaidFileLoader/MermaidFileLoader.astro b/packages/core/eventcatalog/src/components/MDX/MermaidFileLoader/MermaidFileLoader.astro
similarity index 100%
rename from eventcatalog/src/components/MDX/MermaidFileLoader/MermaidFileLoader.astro
rename to packages/core/eventcatalog/src/components/MDX/MermaidFileLoader/MermaidFileLoader.astro
diff --git a/eventcatalog/src/components/MDX/MessageTable/MessageTable.astro b/packages/core/eventcatalog/src/components/MDX/MessageTable/MessageTable.astro
similarity index 100%
rename from eventcatalog/src/components/MDX/MessageTable/MessageTable.astro
rename to packages/core/eventcatalog/src/components/MDX/MessageTable/MessageTable.astro
diff --git a/eventcatalog/src/components/MDX/MessageTable/MessageTable.client.tsx b/packages/core/eventcatalog/src/components/MDX/MessageTable/MessageTable.client.tsx
similarity index 76%
rename from eventcatalog/src/components/MDX/MessageTable/MessageTable.client.tsx
rename to packages/core/eventcatalog/src/components/MDX/MessageTable/MessageTable.client.tsx
index 22ed6778e..7dcc9e6f1 100644
--- a/eventcatalog/src/components/MDX/MessageTable/MessageTable.client.tsx
+++ b/packages/core/eventcatalog/src/components/MDX/MessageTable/MessageTable.client.tsx
@@ -1,4 +1,5 @@
 import { getColorAndIconForCollection } from '@utils/collections/icons';
+import { getCollectionTextColorClass } from '@utils/collection-colors';
 import { buildUrl } from '@utils/url-builder';
 import { useState, useMemo, useCallback, memo } from 'react';
 
@@ -33,35 +34,35 @@ const MessageRow = memo(
     const channels = message.channels || [];
 
     return (
-      <tr className="group hover:bg-gray-100">
-        <td className="whitespace-nowrap py-4 pl-4 pr-3 text-sm font-medium text-gray-900 sm:pl-6 relative">
+      <tr className="group hover:bg-[rgb(var(--ec-content-hover))]">
+        <td className="whitespace-nowrap py-4 pl-4 pr-3 text-sm font-medium text-[rgb(var(--ec-page-text))] sm:pl-6 relative">
           <a href={url} className="absolute inset-0 z-10" aria-label={`View details for ${message.name}`} />
           <div className="flex items-center gap-2 relative">
-            <Icon className={`h-5 w-5 text-${color}-500`} />
+            <Icon className={`h-5 w-5 ${getCollectionTextColorClass(color)}`} />
             <span className="group-hover:text-blue-600 break-all">{message.name}</span>
           </div>
         </td>
-        <td className="whitespace-nowrap px-3 py-4 text-sm text-gray-500 relative">
+        <td className="whitespace-nowrap px-3 py-4 text-sm text-[rgb(var(--ec-page-text-muted))] relative">
           <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
           <span>v{message.version}</span>
         </td>
-        <td className="whitespace-nowrap px-3 py-4 text-sm text-gray-500 relative">
+        <td className="whitespace-nowrap px-3 py-4 text-sm text-[rgb(var(--ec-page-text-muted))] relative">
           <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
           <span>{type}</span>
         </td>
-        <td className="px-3 py-4 text-sm text-gray-500 relative">
+        <td className="px-3 py-4 text-sm text-[rgb(var(--ec-page-text-muted))] relative">
           <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
           <span className="line-clamp-2 break-words">{message.summary || '-'}</span>
         </td>
         {showChannels && (
-          <td className="px-3 py-4 text-sm text-gray-500 relative">
+          <td className="px-3 py-4 text-sm text-[rgb(var(--ec-page-text-muted))] relative">
             <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
             <div className="flex flex-wrap gap-1">
               {channels.length > 0
                 ? channels.map((channel, index) => (
                     <span
                       key={`${channel.id}-${index}`}
-                      className="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 text-xs font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10"
+                      className="inline-flex items-center rounded-md bg-[rgb(var(--ec-content-hover))] px-2 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] ring-1 ring-inset ring-[rgb(var(--ec-page-border))]"
                     >
                       {channel.id}
                     </span>
@@ -98,8 +99,8 @@ const FilterButton = memo(
       }}
       className={`px-3 py-1 rounded-md text-sm font-medium ${
         typeFilter === type
-          ? 'bg-black text-white border border-gray-200 hover:bg-gray-900'
-          : 'bg-white text-black border border-gray-200 hover:bg-gray-100'
+          ? 'bg-[rgb(var(--ec-button-bg))] text-[rgb(var(--ec-button-text))] border border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-button-bg-hover))]'
+          : 'bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text))] border border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-content-hover))]'
       }`}
     >
       {label} ({count})
@@ -210,12 +211,12 @@ const MessageTable = (props: MessageTableProps) => {
     );
 
     return (
-      <div className="flow-root bg-white border-gray-200 border  p-4 pb-2 rounded-lg text-gray-900">
+      <div className="flow-root bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border-[rgb(var(--ec-page-border))] border  p-4 pb-2 rounded-lg text-[rgb(var(--ec-page-text))]">
         <div className="space-y-4">
           <h2 className="text-xl font-semibold">
             {title} ({searchTerm || typeFilter ? `${filteredMessages.length}/${messages.length}` : messages.length})
           </h2>
-          <span className="text-sm text-gray-700">
+          <span className="text-sm text-[rgb(var(--ec-page-text-muted))]">
             Quickly find the message you need by searching for the name, type, or summary.
           </span>
 
@@ -238,7 +239,12 @@ const MessageTable = (props: MessageTableProps) => {
 
           <div className="relative">
             <div className="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
-              <svg className="h-5 w-5 text-gray-400" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+              <svg
+                className="h-5 w-5 text-[rgb(var(--ec-icon-color))]"
+                viewBox="0 0 20 20"
+                fill="currentColor"
+                aria-hidden="true"
+              >
                 <path
                   fillRule="evenodd"
                   d="M9 3.5a5.5 5.5 0 100 11 5.5 5.5 0 000-11zM2 9a7 7 0 1112.452 4.391l3.328 3.329a.75.75 0 11-1.06 1.06l-3.329-3.328A7 7 0 012 9z"
@@ -254,7 +260,7 @@ const MessageTable = (props: MessageTableProps) => {
                 setCurrentPage(1); // Reset to first page when searching
               }}
               placeholder={`Search by name, type, or summary...`}
-              className="block w-full rounded-md border-0 py-1.5 pl-10 pr-10 text-gray-900 ring-1 ring-inset ring-gray-300 placeholder:text-gray-400 focus:ring-2 focus:ring-inset focus:ring-blue-600 sm:text-sm sm:leading-6"
+              className="block w-full rounded-md border-0 py-1.5 pl-10 pr-10 text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-input-bg))] ring-1 ring-inset ring-[rgb(var(--ec-input-border))] placeholder:text-[rgb(var(--ec-input-placeholder))] focus:ring-2 focus:ring-inset focus:ring-[rgb(var(--ec-accent))] sm:text-sm sm:leading-6"
             />
             {searchTerm && (
               <button
@@ -265,7 +271,11 @@ const MessageTable = (props: MessageTableProps) => {
                 className="absolute inset-y-0 right-0 flex items-center pr-3"
                 aria-label="Clear search"
               >
-                <svg className="h-5 w-5 text-gray-400 hover:text-gray-500" viewBox="0 0 20 20" fill="currentColor">
+                <svg
+                  className="h-5 w-5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-icon-hover))]"
+                  viewBox="0 0 20 20"
+                  fill="currentColor"
+                >
                   <path d="M6.28 5.22a.75.75 0 00-1.06 1.06L8.94 10l-3.72 3.72a.75.75 0 101.06 1.06L10 11.06l3.72 3.72a.75.75 0 101.06-1.06L11.06 10l3.72-3.72a.75.75 0 00-1.06-1.06L10 8.94 6.28 5.22z" />
                 </svg>
               </button>
@@ -275,35 +285,44 @@ const MessageTable = (props: MessageTableProps) => {
         <div className="overflow-x-auto">
           <div className="inline-block min-w-full py-2 align-middle">
             <div className="max-w-full overflow-hidden">
-              <table className="min-w-full table-fixed divide-y divide-gray-300  rounded-sm bg-white ">
+              <table className="min-w-full table-fixed divide-y divide-[rgb(var(--ec-page-border))] rounded-xs bg-[rgb(var(--ec-page-bg))]">
                 <thead>
                   <tr>
                     <th
                       scope="col"
-                      className={`${showChannels ? 'w-1/4' : 'w-1/3'} py-3.5 pl-4 pr-3 text-left text-sm font-semibold text-gray-900 sm:pl-6`}
+                      className={`${showChannels ? 'w-1/4' : 'w-1/3'} py-3.5 pl-4 pr-3 text-left text-sm font-semibold text-[rgb(var(--ec-page-text))] sm:pl-6`}
                     >
                       Name
                     </th>
-                    <th scope="col" className="w-[100px] px-3 py-3.5 text-left text-sm font-semibold text-gray-900">
+                    <th
+                      scope="col"
+                      className="w-[100px] px-3 py-3.5 text-left text-sm font-semibold text-[rgb(var(--ec-page-text))]"
+                    >
                       Version
                     </th>
-                    <th scope="col" className="w-[100px] py-3.5 pl-3.5 pr-3 text-left text-sm font-semibold text-gray-900">
+                    <th
+                      scope="col"
+                      className="w-[100px] py-3.5 pl-3.5 pr-3 text-left text-sm font-semibold text-[rgb(var(--ec-page-text))]"
+                    >
                       Type
                     </th>
                     <th
                       scope="col"
-                      className={`${showChannels ? 'w-1/3' : 'w-1/2'} px-3 py-3.5 text-left text-sm font-semibold text-gray-900`}
+                      className={`${showChannels ? 'w-1/3' : 'w-1/2'} px-3 py-3.5 text-left text-sm font-semibold text-[rgb(var(--ec-page-text))]`}
                     >
                       Summary
                     </th>
                     {showChannels && (
-                      <th scope="col" className="w-1/4 px-3 py-3.5 text-left text-sm font-semibold text-gray-900">
+                      <th
+                        scope="col"
+                        className="w-1/4 px-3 py-3.5 text-left text-sm font-semibold text-[rgb(var(--ec-page-text))]"
+                      >
                         Channels
                       </th>
                     )}
                   </tr>
                 </thead>
-                <tbody className="divide-y divide-gray-200">
+                <tbody className="divide-y divide-[rgb(var(--ec-page-border))]">
                   {paginatedMessages.length > 0 ? (
                     paginatedMessages.map((message) => (
                       <MessageRow
@@ -315,7 +334,10 @@ const MessageTable = (props: MessageTableProps) => {
                     ))
                   ) : (
                     <tr>
-                      <td colSpan={showChannels ? 5 : 4} className="text-center py-4 text-sm text-gray-500">
+                      <td
+                        colSpan={showChannels ? 5 : 4}
+                        className="text-center py-4 text-sm text-[rgb(var(--ec-page-text-muted))]"
+                      >
                         No messages found
                       </td>
                     </tr>
@@ -326,37 +348,37 @@ const MessageTable = (props: MessageTableProps) => {
           </div>
         </div>
         {totalPages > 1 && (
-          <div className="flex items-center justify-between border-t border-gray-200 bg-white px-4 py-3 sm:px-6 -mt-2">
+          <div className="flex items-center justify-between border-t border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] px-4 py-3 sm:px-6 -mt-2">
             <div className="flex flex-1 justify-between sm:hidden">
               <button
                 onClick={() => setCurrentPage(currentPage - 1)}
                 disabled={currentPage === 1}
-                className={`relative inline-flex items-center rounded-md border border-gray-300 bg-white px-4 py-2 text-sm font-medium ${currentPage === 1 ? 'text-gray-300' : 'text-gray-700 hover:bg-gray-50'}`}
+                className={`relative inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] px-4 py-2 text-sm font-medium ${currentPage === 1 ? 'text-[rgb(var(--ec-page-text-muted))] opacity-50' : 'text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))]'}`}
               >
                 Previous
               </button>
               <button
                 onClick={() => setCurrentPage(currentPage + 1)}
                 disabled={currentPage === totalPages}
-                className={`relative ml-3 inline-flex items-center rounded-md border border-gray-300 bg-white px-4 py-2 text-sm font-medium ${currentPage === totalPages ? 'text-gray-300' : 'text-gray-700 hover:bg-gray-50'}`}
+                className={`relative ml-3 inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] px-4 py-2 text-sm font-medium ${currentPage === totalPages ? 'text-[rgb(var(--ec-page-text-muted))] opacity-50' : 'text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))]'}`}
               >
                 Next
               </button>
             </div>
             <div className="hidden sm:flex sm:flex-1 sm:items-center sm:justify-between">
               <div>
-                <p className="text-sm text-gray-700">
+                <p className="text-sm text-[rgb(var(--ec-page-text-muted))]">
                   Showing <span className="font-medium">{startIndex + 1}</span> to{' '}
                   <span className="font-medium">{Math.min(startIndex + itemsPerPage, filteredMessages.length)}</span> of{' '}
                   <span className="font-medium">{filteredMessages.length}</span> results
                 </p>
               </div>
               <div>
-                <nav className="isolate inline-flex -space-x-px rounded-md shadow-sm" aria-label="Pagination">
+                <nav className="isolate inline-flex -space-x-px rounded-md shadow-xs" aria-label="Pagination">
                   <button
                     onClick={() => setCurrentPage(currentPage - 1)}
                     disabled={currentPage === 1}
-                    className={`relative inline-flex items-center rounded-l-md px-2 py-2 ${currentPage === 1 ? 'text-gray-300' : 'text-gray-400 hover:bg-gray-50'} ring-1 ring-inset ring-gray-300`}
+                    className={`relative inline-flex items-center rounded-l-md px-2 py-2 ${currentPage === 1 ? 'text-[rgb(var(--ec-page-text-muted))] opacity-50' : 'text-[rgb(var(--ec-icon-color))] hover:bg-[rgb(var(--ec-content-hover))]'} ring-1 ring-inset ring-[rgb(var(--ec-page-border))]`}
                   >
                     <span className="sr-only">Previous</span>
                     <svg className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
@@ -370,7 +392,7 @@ const MessageTable = (props: MessageTableProps) => {
                   <button
                     onClick={() => setCurrentPage(currentPage + 1)}
                     disabled={currentPage === totalPages}
-                    className={`relative inline-flex items-center rounded-r-md px-2 py-2 ${currentPage === totalPages ? 'text-gray-300' : 'text-gray-400 hover:bg-gray-50'} ring-1 ring-inset ring-gray-300`}
+                    className={`relative inline-flex items-center rounded-r-md px-2 py-2 ${currentPage === totalPages ? 'text-[rgb(var(--ec-page-text-muted))] opacity-50' : 'text-[rgb(var(--ec-icon-color))] hover:bg-[rgb(var(--ec-content-hover))]'} ring-1 ring-inset ring-[rgb(var(--ec-page-border))]`}
                   >
                     <span className="sr-only">Next</span>
                     <svg className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
@@ -392,7 +414,7 @@ const MessageTable = (props: MessageTableProps) => {
 
   return (
     <div className={`mx-auto not-prose py-4  space-y-4  my-4`}>
-      <h2 className="text-2xl font-semibold">Messages for this {collection.slice(0, -1)}</h2>
+      <h2 className="text-2xl font-semibold text-[rgb(var(--ec-page-text))]">Messages for this {collection.slice(0, -1)}</h2>
       <div>
         {shouldRenderSends && (
           <div>
diff --git a/eventcatalog/src/components/MDX/Miro/Miro.astro b/packages/core/eventcatalog/src/components/MDX/Miro/Miro.astro
similarity index 100%
rename from eventcatalog/src/components/MDX/Miro/Miro.astro
rename to packages/core/eventcatalog/src/components/MDX/Miro/Miro.astro
diff --git a/packages/core/eventcatalog/src/components/MDX/NodeGraph/AstroNodeGraph.tsx b/packages/core/eventcatalog/src/components/MDX/NodeGraph/AstroNodeGraph.tsx
new file mode 100644
index 000000000..8e71415f5
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/NodeGraph/AstroNodeGraph.tsx
@@ -0,0 +1,114 @@
+/**
+ * Astro adapter for @eventcatalog/visualiser
+ *
+ * This component wraps the framework-agnostic NodeGraph from @eventcatalog/visualiser
+ * and provides Astro-specific integration including:
+ * - Navigation using Astro's navigate function
+ * - Layout persistence via Astro API routes
+ * - URL building with Astro's URL utilities
+ */
+
+import { useCallback, lazy, Suspense, useEffect } from 'react';
+import type { Node, Edge } from '@xyflow/react';
+import { buildUrl } from '@utils/url-builder';
+
+const NodeGraph = lazy(() =>
+  import('@eventcatalog/visualiser').then((module) => ({ default: module.NodeGraph }))
+) as React.LazyExoticComponent<React.ComponentType<AstroNodeGraphProps & Record<string, unknown>>>;
+
+interface AstroNodeGraphProps {
+  id: string;
+  nodes: Node[];
+  edges: Edge[];
+  title?: string;
+  href?: string;
+  hrefLabel?: string;
+  linkTo?: 'docs' | 'visualiser';
+  includeKey?: boolean;
+  footerLabel?: string;
+  linksToVisualiser?: boolean;
+  links?: { label: string; url: string }[];
+  mode?: 'full' | 'simple';
+  portalId?: string;
+  showFlowWalkthrough?: boolean;
+  showSearch?: boolean;
+  zoomOnScroll?: boolean;
+  designId?: string;
+  isChatEnabled?: boolean;
+  maxTextSize?: number;
+  isDevMode?: boolean;
+  resourceKey?: string;
+  disableMessageAnimation?: boolean;
+}
+
+const AstroNodeGraph = ({ isDevMode = false, resourceKey, ...otherProps }: AstroNodeGraphProps) => {
+  useEffect(() => {
+    // Load visualizer styles only when this component is mounted.
+    // Use the core-scoped stylesheet so visualizer styles don't override EventCatalog utility classes globally.
+    import('@eventcatalog/visualiser/styles-core.css');
+  }, []);
+
+  // Astro-specific navigation handler
+  const handleNavigate = useCallback((url: string) => {
+    // Use window.location for navigation since we can't import astro:transitions/client in a React component
+    window.location.href = url;
+  }, []);
+
+  // Astro-specific URL builder that respects the configured base path
+  const handleBuildUrl = useCallback((path: string) => {
+    return buildUrl(path);
+  }, []);
+
+  // Layout persistence: Save layout to Astro API route
+  const handleSaveLayout = useCallback(
+    async (key: string, positions: Record<string, { x: number; y: number }>): Promise<boolean> => {
+      if (!key) return false;
+
+      try {
+        const response = await fetch('/api/dev/visualizer-layout/save', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ resourceKey: key, positions }),
+        });
+        const result = await response.json();
+        return result.success === true;
+      } catch {
+        return false;
+      }
+    },
+    []
+  );
+
+  // Layout persistence: Reset layout via Astro API route
+  const handleResetLayout = useCallback(async (key: string): Promise<boolean> => {
+    if (!key) return false;
+
+    try {
+      const response = await fetch('/api/dev/visualizer-layout/reset', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ resourceKey: key }),
+      });
+      const result = await response.json();
+      return result.success === true;
+    } catch {
+      return false;
+    }
+  }, []);
+
+  return (
+    <Suspense fallback={<div>Loading graph...</div>}>
+      <NodeGraph
+        {...otherProps}
+        resourceKey={resourceKey}
+        isDevMode={isDevMode}
+        onNavigate={handleNavigate}
+        onBuildUrl={handleBuildUrl}
+        onSaveLayout={handleSaveLayout}
+        onResetLayout={handleResetLayout}
+      />
+    </Suspense>
+  );
+};
+
+export default AstroNodeGraph;
diff --git a/packages/core/eventcatalog/src/components/MDX/NodeGraph/NodeGraph.astro b/packages/core/eventcatalog/src/components/MDX/NodeGraph/NodeGraph.astro
new file mode 100644
index 000000000..5094393be
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/NodeGraph/NodeGraph.astro
@@ -0,0 +1,225 @@
+---
+import AstroNodeGraph from './AstroNodeGraph';
+import { getNodesAndEdges as getNodesAndEdgesForAgent } from '@utils/node-graphs/agents-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForService } from '@utils/node-graphs/services-node-graph';
+import {
+  getNodesAndEdgesForCommands,
+  getNodesAndEdgesForEvents,
+  getNodesAndEdgesForQueries,
+} from '@utils/node-graphs/message-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForDomain } from '@utils/node-graphs/domains-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForDomainEntityMap } from '@utils/node-graphs/domain-entity-map';
+import { getDomainsCanvasData } from '@utils/node-graphs/domains-canvas';
+import { getNodesAndEdges as getNodesAndEdgesForFlows } from '@utils/node-graphs/flows-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForDataProduct } from '@utils/node-graphs/data-products-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForSystem } from '@utils/node-graphs/systems-node-graph';
+import {
+  getNodesAndEdges as getNodesAndEdgesForSystemContext,
+  getNodesAndEdgesForDomainSystems as getNodesAndEdgesForDomainSystemsContext,
+  getNodesAndEdgesForAllSystems as getNodesAndEdgesForSystemContextMap,
+} from '@utils/node-graphs/system-context-node-graph';
+import { buildUrl } from '@utils/url-builder';
+import { getVersionFromCollection } from '@utils/collections/versions';
+import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
+import { getNodesAndEdges as getNodesAndEdgesForContainer } from '@utils/node-graphs/container-node-graph';
+import config from '@config';
+import { isEventCatalogChatEnabled, isDevMode } from '@utils/feature';
+import { loadSavedLayout, applyLayoutToNodes, buildResourceKey } from '@utils/node-graphs/layout-persistence';
+
+const isChatEnabled = isEventCatalogChatEnabled();
+
+interface Props {
+  id: string;
+  collection: string;
+  title?: string;
+  version: string;
+  mode: 'full' | 'simple';
+  linkTo?: 'docs' | 'visualiser';
+  href?: {
+    label: string;
+    url: string;
+  };
+  linksToVisualiser?: boolean;
+  showSearch?: boolean;
+  showLegend?: boolean;
+  zoomOnScroll?: boolean;
+  // Override the DOM portal the graph mounts into. Defaults to `${id}-portal`.
+  // Needed when more than one graph for the same resource is on the page
+  // (e.g. the System Diagram and the Context Diagram on a system page).
+  portalId?: string;
+  // Disable + hide the "Simulate Messages" animation (e.g. on the Context Diagram).
+  disableMessageAnimation?: boolean;
+}
+
+const {
+  id,
+  collection,
+  title,
+  mode = 'simple',
+  linkTo = 'docs',
+  version,
+  href,
+  linksToVisualiser,
+  showSearch = true,
+  showLegend = true,
+  zoomOnScroll = false,
+  portalId,
+  disableMessageAnimation,
+} = Astro.props;
+
+let nodes = [],
+  edges = [];
+
+const getNodesAndEdgesFunctions = {
+  agents: getNodesAndEdgesForAgent,
+  services: getNodesAndEdgesForService,
+  events: getNodesAndEdgesForEvents,
+  commands: getNodesAndEdgesForCommands,
+  queries: getNodesAndEdgesForQueries,
+  domains: getNodesAndEdgesForDomain,
+  flows: getNodesAndEdgesForFlows,
+  containers: getNodesAndEdgesForContainer,
+  'data-products': getNodesAndEdgesForDataProduct,
+  systems: getNodesAndEdgesForSystem,
+};
+
+let links: { label: string; url: string }[] = [];
+
+if (collection in getNodesAndEdgesFunctions) {
+  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesFunctions[
+    collection as keyof typeof getNodesAndEdgesFunctions
+  ]({
+    id,
+    version,
+    mode,
+    channelRenderMode: config.visualiser?.channels?.renderMode === 'single' ? 'single' : 'flat',
+    // The standalone System Diagram wraps the system's nodes in one parent boundary node.
+    wrapInSystemGroup: collection === 'systems',
+  });
+
+  nodes = fetchedNodes;
+  edges = fetchedEdges;
+
+  if (mode === 'full') {
+    // Try and get the list of versions for the rendered item
+    try {
+      const allItems = await pageDataLoader[collection as keyof typeof pageDataLoader]();
+      const versions = getVersionFromCollection(allItems, id, version);
+
+      const item = versions[0];
+      const listOfVersions = item.data.versions || [];
+
+      // Order by version
+      listOfVersions.sort((a, b) => b.localeCompare(a));
+
+      if (listOfVersions.length > 1) {
+        links = listOfVersions.map((version) => ({
+          label: `${item.data.name} v${version}`,
+          url: buildUrl(`/visualiser/${collection}/${id}/${version}`),
+          selected: version === version,
+        }));
+      }
+    } catch (error) {
+      links = [];
+    }
+  }
+}
+
+if (collection === 'system-context-map') {
+  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForSystemContextMap({ mode });
+  nodes = fetchedNodes;
+  edges = fetchedEdges;
+}
+
+if (collection === 'domains-canvas') {
+  const { domainNodes, messageNodes, edges: fetchedEdges } = await getDomainsCanvasData();
+  nodes = [...domainNodes, ...messageNodes];
+  edges = fetchedEdges;
+}
+
+if (collection === 'systems-context') {
+  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForSystemContext({
+    id,
+    version,
+    mode,
+  });
+  nodes = fetchedNodes;
+  edges = fetchedEdges;
+}
+
+if (collection === 'domains-systems-context') {
+  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForDomainSystemsContext({
+    id,
+    version,
+    mode,
+  });
+  nodes = fetchedNodes;
+  edges = fetchedEdges;
+}
+
+if (collection === 'domains-entities') {
+  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForDomainEntityMap({
+    id,
+    version,
+  });
+  nodes = fetchedNodes;
+  edges = fetchedEdges;
+}
+
+if (collection === 'services-entities') {
+  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForDomainEntityMap({
+    id,
+    version,
+    type: 'services',
+  });
+  nodes = fetchedNodes;
+  edges = fetchedEdges;
+}
+
+if (collection === 'services-containers') {
+  const { nodes: fetchedNodes, edges: fetchedEdges } = await getNodesAndEdgesForService({
+    id,
+    version,
+    renderMessages: false,
+    mode: 'full',
+  });
+  nodes = fetchedNodes;
+  edges = fetchedEdges;
+}
+
+// Load and apply saved layout if it exists (dev mode feature)
+const resourceKey = buildResourceKey(collection, id, version);
+const savedLayout = await loadSavedLayout(resourceKey);
+const nodesWithLayout = applyLayoutToNodes(nodes as any[], savedLayout);
+---
+
+<div>
+  <AstroNodeGraph
+    id={id}
+    nodes={nodesWithLayout}
+    edges={edges}
+    title={title}
+    hrefLabel={href?.label}
+    href={href?.url}
+    linkTo={linkTo}
+    client:only="react"
+    linksToVisualiser={linksToVisualiser}
+    links={links}
+    mode={mode}
+    showSearch={showSearch}
+    includeKey={showLegend}
+    zoomOnScroll={zoomOnScroll}
+    isChatEnabled={isChatEnabled}
+    maxTextSize={config.mermaid?.maxTextSize}
+    isDevMode={isDevMode()}
+    resourceKey={resourceKey}
+    portalId={portalId}
+    disableMessageAnimation={disableMessageAnimation ?? collection === 'systems-context'}
+  />
+</div>
+
+<style is:global>
+  .react-flow__attribution {
+    display: none;
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/components/MDX/NodeGraph/NodeGraphPortal.tsx b/packages/core/eventcatalog/src/components/MDX/NodeGraph/NodeGraphPortal.tsx
new file mode 100644
index 000000000..458e5c793
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/NodeGraph/NodeGraphPortal.tsx
@@ -0,0 +1,15 @@
+const NodeGraphPortal = (props: any) => {
+  return (
+    <div
+      className="not-prose h-[30em] my-6 mb-12 w-full relative border! border-[rgb(var(--ec-page-border))]! rounded-md overflow-hidden"
+      id={`${props.id}-portal`}
+      style={{
+        maxHeight: props.maxHeight ? `${props.maxHeight}em` : `30em`,
+      }}
+    >
+      {/* <span className="absolute top-2 right-4 bg-white font-bold z-10">{props.title}</span> */}
+    </div>
+  );
+};
+
+export default NodeGraphPortal;
diff --git a/packages/core/eventcatalog/src/components/MDX/NodeGraph/README.md b/packages/core/eventcatalog/src/components/MDX/NodeGraph/README.md
new file mode 100644
index 000000000..735915a83
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/NodeGraph/README.md
@@ -0,0 +1,85 @@
+# NodeGraph - Astro Adapter for @eventcatalog/visualiser
+
+## Overview
+
+This directory contains the Astro-specific adapter for the `@eventcatalog/visualiser` package. The visualiser package is framework-agnostic, and this adapter provides Astro-specific integrations.
+
+## Components
+
+### AstroNodeGraph.tsx
+
+The main adapter component that wraps the `NodeGraph` from `@eventcatalog/visualiser` and provides:
+
+- **Navigation**: Uses Astro's `navigate` function from `astro:transitions/client`
+- **URL Building**: Uses Astro's `buildUrl` utility for consistent URL generation
+- **Layout Persistence**: Integrates with Astro API routes for saving/resetting custom node layouts (dev mode only)
+  - `/api/dev/visualiser-layout/save` - Saves node positions
+  - `/api/dev/visualiser-layout/reset` - Resets node positions to defaults
+
+### NodeGraph.astro
+
+The Astro component that serves as the entry point for rendering node graphs. It:
+- Fetches nodes and edges based on the collection type (services, events, domains, etc.)
+- Applies saved layout positions when available (dev mode feature)
+- Renders the `AstroNodeGraph` component with `client:only="react"`
+
+### NodeGraphPortal.tsx
+
+A simple portal component that creates the DOM container where the React component will render. Used by MDX components to embed node graphs in documentation.
+
+## Usage
+
+### In Astro Pages
+
+```astro
+---
+import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+---
+
+<div id="my-graph-portal"></div>
+<NodeGraph
+  id="my-graph"
+  collection="services"
+  version="1.0.0"
+  mode="full"
+  linkTo="visualiser"
+/>
+```
+
+### In MDX Content
+
+```mdx
+<NodeGraph id="my-service" collection="services" version="1.0.0" />
+```
+
+## Integration with @eventcatalog/visualiser
+
+The `AstroNodeGraph` component directly uses the `NodeGraph` component from `@eventcatalog/visualiser` and provides the framework-specific callbacks:
+
+```typescript
+<NodeGraph
+  {...props}
+  onNavigate={handleNavigate}
+  onBuildUrl={handleBuildUrl}
+  onSaveLayout={handleSaveLayout}
+  onResetLayout={handleResetLayout}
+/>
+```
+
+### Known Limitations
+
+Currently, the `onSaveLayout` and `onResetLayout` callbacks are passed through with a `@ts-expect-error` comment because the visualiser package's outer `NodeGraph` component doesn't expose these props in its TypeScript interface, even though the internal `NodeGraphBuilder` component does accept them.
+
+**TODO**: Update the `@eventcatalog/visualiser` package to expose `onSaveLayout` and `onResetLayout` in the `NodeGraphProps` interface and forward them to `NodeGraphBuilder`.
+
+## Migration Notes
+
+This adapter replaces the old monolithic `NodeGraph.tsx` component that was previously in this directory. The old component has been:
+- Refactored into the framework-agnostic `@eventcatalog/visualiser` package
+- Wrapped by this new `AstroNodeGraph` adapter for Astro-specific integrations
+
+Benefits of this architecture:
+- The visualiser can be used in other frameworks (Next.js, Remix, etc.)
+- Astro-specific concerns are isolated to this adapter
+- Easier to test and maintain
+- Clear separation of concerns
diff --git a/eventcatalog/src/components/MDX/OpenAPI/OpenAPI.astro b/packages/core/eventcatalog/src/components/MDX/OpenAPI/OpenAPI.astro
similarity index 100%
rename from eventcatalog/src/components/MDX/OpenAPI/OpenAPI.astro
rename to packages/core/eventcatalog/src/components/MDX/OpenAPI/OpenAPI.astro
diff --git a/packages/core/eventcatalog/src/components/MDX/Prompt/Prompt.astro b/packages/core/eventcatalog/src/components/MDX/Prompt/Prompt.astro
new file mode 100644
index 000000000..e16766df4
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/Prompt/Prompt.astro
@@ -0,0 +1,226 @@
+---
+import { ChevronDown } from 'lucide-react';
+import { LUCIDE_ICON_MAP } from '@utils/icon-map';
+
+type ActionType = 'copy' | 'cursor';
+
+interface Props {
+  description: string;
+  actions?: ActionType[];
+  icon?: string;
+}
+
+const { description, actions = ['copy'], icon } = Astro.props;
+
+const showCopy = actions.includes('copy');
+const showCursor = actions.includes('cursor');
+
+const toPascalCase = (input: string): string =>
+  input
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+
+const Icon = icon ? (LUCIDE_ICON_MAP[toPascalCase(icon)] ?? null) : null;
+
+// Render the slotted content to a string so we can use it as the prompt text
+// (for clipboard + the Cursor deep link).
+const slotHtml = await Astro.slots.render('default');
+const promptText = (slotHtml ?? '')
+  .replace(/<[^>]+>/g, '')
+  .replace(/&nbsp;/g, ' ')
+  .replace(/&amp;/g, '&')
+  .replace(/&lt;/g, '<')
+  .replace(/&gt;/g, '>')
+  .replace(/&quot;/g, '"')
+  .replace(/&#39;/g, "'")
+  .trim();
+
+const cursorUrl = `https://cursor.com/link/prompt?text=${encodeURIComponent(promptText)}`;
+const promptBodyId = `ec-prompt-body-${Math.random().toString(36).slice(2)}`;
+---
+
+<ec-prompt
+  class="not-prose my-4 block rounded-xl border border-[rgb(var(--ec-page-border))] bg-gray-50 dark:bg-[rgb(var(--ec-rail-bg))]"
+  data-prompt-text={promptText}
+>
+  <div class="flex items-center gap-2.5 px-4 py-3">
+    {Icon && <Icon className="w-4 h-4 shrink-0 text-[rgb(var(--ec-page-text-muted))]" />}
+    <div class="flex-1 min-w-0">
+      <div class="text-sm font-medium text-[rgb(var(--ec-page-text))] leading-snug">{description}</div>
+    </div>
+    <div class="flex items-center gap-1.5 shrink-0">
+      <button
+        type="button"
+        data-prompt-toggle
+        aria-expanded="false"
+        aria-controls={promptBodyId}
+        class="inline-flex items-center gap-1.5 px-2 py-1 text-xs font-medium rounded-md border transition-all duration-150 border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))]"
+      >
+        <span data-prompt-toggle-text>Show prompt</span>
+        <ChevronDown
+          className="w-3.5 h-3.5 shrink-0 transition-transform duration-150 data-[expanded=true]:rotate-180"
+          data-prompt-toggle-icon
+          data-expanded="false"
+        />
+      </button>
+      {
+        showCopy && (
+          <button
+            type="button"
+            data-prompt-copy
+            data-copied="false"
+            aria-label="Copy prompt"
+            aria-live="polite"
+            class="ec-prompt-copy inline-flex items-center gap-1.5 px-2 py-1 text-xs font-medium rounded-md border transition-all duration-150 border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] data-[copied=true]:border-emerald-500/70 data-[copied=true]:bg-emerald-50 data-[copied=true]:text-emerald-700 dark:data-[copied=true]:bg-emerald-950/50 dark:data-[copied=true]:text-emerald-300 dark:data-[copied=true]:border-emerald-500/60"
+          >
+            <span data-prompt-copy-idle class="inline-flex items-center gap-1.5">
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="14"
+                height="14"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+              >
+                <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
+                <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+              </svg>
+              <span>Copy</span>
+            </span>
+            <span data-prompt-copy-done class="inline-flex items-center gap-1.5" style="display:none;">
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="14"
+                height="14"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2.5"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+              >
+                <polyline points="20 6 9 17 4 12" />
+              </svg>
+              <span>Copied!</span>
+            </span>
+          </button>
+        )
+      }
+      {
+        showCursor && (
+          <a
+            href={cursorUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            aria-label="Open in Cursor"
+            class="inline-flex items-center gap-1.5 px-2 py-1 text-xs font-medium rounded-md border border-black bg-black !text-white hover:bg-black/85 transition-colors no-underline"
+          >
+            <svg
+              height="1em"
+              width="1em"
+              viewBox="0 0 16 16"
+              xmlns="http://www.w3.org/2000/svg"
+              aria-hidden="true"
+              class="w-3 h-3 shrink-0"
+            >
+              <path
+                fill="currentColor"
+                d="M14.4734 3.9527L8.31773 0.398522C8.22052 0.342485 8.11029 0.312988 7.99809 0.312988C7.88589 0.312988 7.77566 0.342485 7.67846 0.398522L1.52355 3.9527C1.44182 3.99989 1.37394 4.06773 1.32671 4.14942C1.27948 4.23112 1.25457 4.32379 1.25446 4.41816V11.584C1.25457 11.6783 1.27948 11.771 1.32671 11.8527C1.37394 11.9344 1.44182 12.0022 1.52355 12.0494L7.67918 15.6036C7.77636 15.6597 7.8866 15.6893 7.99882 15.6893C8.11103 15.6893 8.22127 15.6597 8.31846 15.6036L14.4741 12.0502C14.5558 12.003 14.6237 11.9351 14.6709 11.8534C14.7182 11.7717 14.7431 11.6791 14.7432 11.5847V4.41743C14.7431 4.32307 14.7182 4.23039 14.6709 4.14869C14.6237 4.067 14.5558 3.99916 14.4741 3.95198L14.4734 3.9527ZM14.0872 4.70543L8.14464 14.9978C8.10464 15.0669 7.99846 15.0385 7.99846 14.9578V8.21889C7.99841 8.15254 7.98092 8.08738 7.94773 8.02993C7.91454 7.97249 7.86682 7.92478 7.80936 7.89161L1.97373 4.52361C1.90391 4.48289 1.93227 4.3767 2.013 4.3767H13.8966C14.0661 4.3767 14.1715 4.55925 14.0872 4.70543Z"
+              />
+            </svg>
+            <span>Open in Cursor</span>
+          </a>
+        )
+      }
+    </div>
+  </div>
+  <div
+    id={promptBodyId}
+    data-prompt-body
+    hidden
+    class="border-t border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))]/70"
+  >
+    <pre
+      class="m-0 max-h-96 overflow-auto whitespace-pre-wrap break-words px-4 py-3 text-sm leading-6 text-[rgb(var(--ec-page-text))]"><code>{promptText}</code></pre>
+  </div>
+  <div hidden><slot /></div>
+</ec-prompt>
+
+<script>
+  if (!customElements.get('ec-prompt')) {
+    class ECPromptElement extends HTMLElement {
+      private resetTimer: number | null = null;
+      private copyButton: HTMLButtonElement | null = null;
+      private toggleButton: HTMLButtonElement | null = null;
+      private promptBody: HTMLElement | null = null;
+      private toggleText: HTMLElement | null = null;
+      private toggleIcon: HTMLElement | null = null;
+      private boundHandler = this.handleCopy.bind(this);
+      private boundToggleHandler = this.handleToggle.bind(this);
+
+      connectedCallback() {
+        this.copyButton = this.querySelector<HTMLButtonElement>('[data-prompt-copy]');
+        this.toggleButton = this.querySelector<HTMLButtonElement>('[data-prompt-toggle]');
+        this.promptBody = this.querySelector<HTMLElement>('[data-prompt-body]');
+        this.toggleText = this.querySelector<HTMLElement>('[data-prompt-toggle-text]');
+        this.toggleIcon = this.querySelector<HTMLElement>('[data-prompt-toggle-icon]');
+
+        this.copyButton?.addEventListener('click', this.boundHandler);
+        this.toggleButton?.addEventListener('click', this.boundToggleHandler);
+      }
+
+      disconnectedCallback() {
+        this.copyButton?.removeEventListener('click', this.boundHandler);
+        this.toggleButton?.removeEventListener('click', this.boundToggleHandler);
+        if (this.resetTimer != null) {
+          window.clearTimeout(this.resetTimer);
+          this.resetTimer = null;
+        }
+      }
+
+      private async handleCopy() {
+        const text = this.dataset.promptText ?? '';
+        try {
+          await navigator.clipboard.writeText(text);
+        } catch {
+          return;
+        }
+        this.setCopied(true);
+        if (this.resetTimer != null) window.clearTimeout(this.resetTimer);
+        this.resetTimer = window.setTimeout(() => this.setCopied(false), 1500);
+      }
+
+      private handleToggle() {
+        if (!this.promptBody || !this.toggleButton) return;
+
+        const expanded = this.toggleButton.getAttribute('aria-expanded') === 'true';
+        this.setExpanded(!expanded);
+      }
+
+      private setExpanded(expanded: boolean) {
+        if (!this.promptBody || !this.toggleButton) return;
+
+        this.promptBody.hidden = !expanded;
+        this.toggleButton.setAttribute('aria-expanded', expanded ? 'true' : 'false');
+        if (this.toggleText) this.toggleText.textContent = expanded ? 'Hide prompt' : 'Show prompt';
+        if (this.toggleIcon) this.toggleIcon.dataset.expanded = expanded ? 'true' : 'false';
+      }
+
+      private setCopied(copied: boolean) {
+        if (!this.copyButton) return;
+        this.copyButton.dataset.copied = copied ? 'true' : 'false';
+        this.copyButton.setAttribute('aria-label', copied ? 'Copied to clipboard' : 'Copy prompt');
+        const idle = this.copyButton.querySelector<HTMLElement>('[data-prompt-copy-idle]');
+        const done = this.copyButton.querySelector<HTMLElement>('[data-prompt-copy-done]');
+        if (idle) idle.style.display = copied ? 'none' : '';
+        if (done) done.style.display = copied ? '' : 'none';
+      }
+    }
+    customElements.define('ec-prompt', ECPromptElement);
+  }
+</script>
diff --git a/eventcatalog/src/components/MDX/RemoteFile.astro b/packages/core/eventcatalog/src/components/MDX/RemoteFile.astro
similarity index 87%
rename from eventcatalog/src/components/MDX/RemoteFile.astro
rename to packages/core/eventcatalog/src/components/MDX/RemoteFile.astro
index 51cf4574a..9db7c23ff 100644
--- a/eventcatalog/src/components/MDX/RemoteFile.astro
+++ b/packages/core/eventcatalog/src/components/MDX/RemoteFile.astro
@@ -1,8 +1,10 @@
 ---
-import jsonpath from 'jsonpath';
+import { JSONPath } from 'jsonpath-plus';
 import JSONSchemaViewer from '@components/SchemaExplorer/JSONSchemaViewer';
 import { Code } from 'astro-expressive-code/components';
 import { isPrivateRemoteSchemaEnabled } from '@utils/feature';
+import { resolveTemplateVariables } from '@utils/remote-file';
+import { resolveSchemaRefs } from '@utils/json-schema-refs';
 
 const {
   url,
@@ -14,18 +16,6 @@ const {
   ...props
 } = Astro.props;
 
-function resolveTemplates(input: any): any {
-  if (typeof input === 'string') {
-    return input.replace(/\$\{(\w+)\}/g, (_, varName) => import.meta.env[varName] || '');
-  }
-
-  if (typeof input === 'object' && input !== null) {
-    return Object.fromEntries(Object.entries(input).map(([k, v]) => [k, resolveTemplates(v)]));
-  }
-
-  return input;
-}
-
 function isValidJSON(str: string): boolean {
   try {
     JSON.parse(str);
@@ -56,7 +46,7 @@ function isJSONSchema(data: any): boolean {
 
 function extractWithJSONPath(data: any, path: string): any {
   try {
-    const result = jsonpath.query(data, path);
+    const result = JSONPath({ path, json: data });
     // If the result is an array with a single element, return the element itself
     // unless the original query was meant to return an array
     if (Array.isArray(result) && result.length === 1 && !path.includes('[*]') && !path.includes('.*')) {
@@ -69,8 +59,8 @@ function extractWithJSONPath(data: any, path: string): any {
   }
 }
 
-const resolvedUrl = resolveTemplates(url);
-const resolvedHeaders = isPrivateRemoteSchemaEnabled() ? resolveTemplates(headers) : {};
+const resolvedUrl = resolveTemplateVariables(url);
+const resolvedHeaders = isPrivateRemoteSchemaEnabled() ? resolveTemplateVariables(headers) : {};
 
 let content = '';
 let processedData: any = null;
@@ -86,8 +76,8 @@ if (Object.keys(headers).length > 0 && !isPrivateRemoteSchemaEnabled()) {
 }
 
 try {
-  const response = await fetch(resolvedUrl, {
-    headers: resolvedHeaders,
+  const response = await fetch(String(resolvedUrl), {
+    headers: resolvedHeaders as HeadersInit,
   });
 
   if (!response.ok) {
@@ -100,6 +90,10 @@ try {
   if (isValidJSON(content)) {
     contentType = 'json';
     processedData = JSON.parse(content);
+    processedData = await resolveSchemaRefs(processedData, {
+      baseUrl: String(resolvedUrl),
+      headers: resolvedHeaders as HeadersInit,
+    });
 
     // Check if it's a JSON Schema
     isSchema = isJSONSchema(processedData);
@@ -152,7 +146,7 @@ if (renderAs === 'auto') {
     <div class="remote-file-content">
       {finalRenderAs === 'schema' ? (
         <div class="not-prose my-4">
-          {title && <h2 class="text-3xl font-bold mb-2 !mt-0">{title}</h2>}
+          {title && <h2 class="text-3xl font-bold mb-2 mt-0!">{title}</h2>}
           <JSONSchemaViewer client:load schema={processedData} maxHeight={maxHeight} expand={false} search={true} />
         </div>
       ) : (
diff --git a/eventcatalog/src/components/MDX/RemoteSchema.astro b/packages/core/eventcatalog/src/components/MDX/RemoteSchema.astro
similarity index 100%
rename from eventcatalog/src/components/MDX/RemoteSchema.astro
rename to packages/core/eventcatalog/src/components/MDX/RemoteSchema.astro
diff --git a/eventcatalog/src/components/MDX/ResourceGroupTable/ResourceGroupTable.astro b/packages/core/eventcatalog/src/components/MDX/ResourceGroupTable/ResourceGroupTable.astro
similarity index 100%
rename from eventcatalog/src/components/MDX/ResourceGroupTable/ResourceGroupTable.astro
rename to packages/core/eventcatalog/src/components/MDX/ResourceGroupTable/ResourceGroupTable.astro
diff --git a/packages/core/eventcatalog/src/components/MDX/ResourceGroupTable/ResourceGroupTable.client.tsx b/packages/core/eventcatalog/src/components/MDX/ResourceGroupTable/ResourceGroupTable.client.tsx
new file mode 100644
index 000000000..5d54dde1f
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/ResourceGroupTable/ResourceGroupTable.client.tsx
@@ -0,0 +1,430 @@
+import { getColorAndIconForCollection } from '@utils/collections/icons';
+import { getCollectionTextColorClass } from '@utils/collection-colors';
+import { buildUrl } from '@utils/url-builder';
+import { useState, useMemo, useCallback, memo } from 'react';
+
+type Resource = {
+  id: string;
+  name: string;
+  version: string;
+  collection: string;
+  type: string;
+  summary?: string;
+  description?: string;
+  owners?: any[];
+  tags?: string[];
+};
+
+type ResourceGroupTableProps = {
+  resources: Resource[];
+  limit?: number;
+  showTags?: boolean;
+  showOwners?: boolean;
+  title: string;
+  subtitle?: string;
+  description: string;
+};
+
+type ResourceType = 'service' | 'event' | 'query' | 'command' | 'domain' | 'flow' | 'channel' | 'user' | 'team' | null;
+
+const ResourceRow = memo(
+  ({ resource, showTags, showOwners }: { resource: Resource; showTags?: boolean; showOwners?: boolean }) => {
+    const { color, Icon } = getColorAndIconForCollection(resource.collection);
+    const url = buildUrl(`/docs/${resource.collection}/${resource.id}/${resource.version}`);
+    let type = resource.collection.slice(0, -1);
+    type = type === 'querie' ? 'query' : type;
+
+    const tags = resource.tags || [];
+    const owners = resource.owners || [];
+
+    return (
+      <tr className="group hover:bg-[rgb(var(--ec-content-hover))]">
+        <td className="whitespace-nowrap py-4 pl-4 pr-3 text-sm font-medium text-[rgb(var(--ec-page-text))] sm:pl-6 relative">
+          <a href={url} className="absolute inset-0 z-10" aria-label={`View details for ${resource.name}`} />
+          <div className="flex items-center gap-2 relative">
+            <Icon className={`h-5 w-5 ${getCollectionTextColorClass(color)}`} />
+            <span className="group-hover:text-[rgb(var(--ec-accent))] break-all">{resource.name}</span>
+          </div>
+        </td>
+        <td className="whitespace-nowrap px-3 py-4 text-sm text-[rgb(var(--ec-page-text-muted))] relative">
+          <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
+          <span>v{resource.version}</span>
+        </td>
+        <td className="whitespace-nowrap px-3 py-4 text-sm text-[rgb(var(--ec-page-text-muted))] relative">
+          <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
+          <span>{type}</span>
+        </td>
+        <td className="px-3 py-4 text-sm text-[rgb(var(--ec-page-text-muted))] relative">
+          <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
+          <span className="line-clamp-2 break-words">{resource.summary || resource.description || '-'}</span>
+        </td>
+        {showTags && (
+          <td className="px-3 py-4 text-sm text-[rgb(var(--ec-page-text-muted))] relative">
+            <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
+            <div className="flex flex-wrap gap-1">
+              {tags.length > 0
+                ? tags.map((tag, index) => (
+                    <span
+                      key={`${tag}-${index}`}
+                      className="inline-flex items-center rounded-md bg-[rgb(var(--ec-content-hover))] px-2 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] ring-1 ring-inset ring-[rgb(var(--ec-page-border))]"
+                    >
+                      {tag}
+                    </span>
+                  ))
+                : '-'}
+            </div>
+          </td>
+        )}
+        {showOwners && (
+          <td className="px-3 py-4 text-sm text-[rgb(var(--ec-page-text-muted))] relative">
+            <a href={url} className="absolute inset-0 z-10" aria-hidden="true" />
+            <div className="flex flex-wrap gap-1">
+              {owners.length > 0
+                ? owners.map((owner, index) => (
+                    <span
+                      key={`${owner.id || owner.name}-${index}`}
+                      className="inline-flex items-center rounded-md bg-[rgb(var(--ec-content-hover))] px-2 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] ring-1 ring-inset ring-[rgb(var(--ec-page-border))]"
+                    >
+                      {owner.name || owner.id}
+                    </span>
+                  ))
+                : '-'}
+            </div>
+          </td>
+        )}
+      </tr>
+    );
+  }
+);
+
+const FilterButton = memo(
+  ({
+    type,
+    label,
+    typeFilter,
+    setTypeFilter,
+    setCurrentPage,
+    count,
+  }: {
+    type: ResourceType;
+    label: string;
+    typeFilter: ResourceType;
+    setTypeFilter: (type: ResourceType) => void;
+    setCurrentPage: (page: number) => void;
+    count: number;
+  }) => (
+    <button
+      onClick={() => {
+        setTypeFilter(typeFilter === type ? null : type);
+        setCurrentPage(1);
+      }}
+      className={`px-3 py-1 rounded-md text-sm font-medium ${
+        typeFilter === type
+          ? 'bg-[rgb(var(--ec-button-bg))] text-[rgb(var(--ec-button-text))] border border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-button-bg-hover))]'
+          : 'bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] text-[rgb(var(--ec-page-text))] border border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-content-hover))]'
+      }`}
+    >
+      {label} ({count})
+    </button>
+  )
+);
+
+const ResourceGroupTable = (props: ResourceGroupTableProps) => {
+  const { resources = [], limit, showTags = false, showOwners = false, title, subtitle = 'Resources', description } = props;
+  const [searchTerm, setSearchTerm] = useState('');
+  const [currentPage, setCurrentPage] = useState(1);
+  const [typeFilter, setTypeFilter] = useState<ResourceType>(null);
+  const itemsPerPage = limit || 10;
+
+  const filterResources = useCallback((resources: Resource[], searchTerm: string, typeFilter: ResourceType) => {
+    let filtered = resources;
+
+    if (typeFilter) {
+      filtered = filtered.filter((resource) => {
+        const collectionType = resource.collection.slice(0, -1);
+        const normalizedType = collectionType === 'querie' ? 'query' : collectionType;
+        return normalizedType === typeFilter;
+      });
+    }
+
+    if (searchTerm) {
+      const lowerSearchTerm = searchTerm.toLowerCase();
+      filtered = filtered.filter((resource) => {
+        const collectionType = resource.collection.slice(0, -1);
+        const normalizedType = collectionType === 'querie' ? 'query' : collectionType;
+
+        return (
+          resource.name.toLowerCase().includes(lowerSearchTerm) ||
+          resource.summary?.toLowerCase().includes(lowerSearchTerm) ||
+          resource.description?.toLowerCase().includes(lowerSearchTerm) ||
+          normalizedType.toLowerCase().includes(lowerSearchTerm) ||
+          resource.tags?.some((tag) => tag.toLowerCase().includes(lowerSearchTerm)) ||
+          false
+        );
+      });
+    }
+
+    return filtered;
+  }, []);
+
+  const filteredResources = useMemo(
+    () => filterResources(resources, searchTerm, typeFilter),
+    [resources, searchTerm, typeFilter, filterResources]
+  );
+
+  const totalPages = Math.ceil(filteredResources.length / itemsPerPage);
+  const startIndex = (currentPage - 1) * itemsPerPage;
+  const paginatedResources = useMemo(
+    () => filteredResources.slice(startIndex, startIndex + itemsPerPage),
+    [filteredResources, startIndex, itemsPerPage]
+  );
+
+  // Get unique resource types and their counts
+  const resourceTypeCounts = useMemo(() => {
+    const counts = new Map<ResourceType, number>();
+    resources.forEach((resource) => {
+      const collectionType = resource.collection.slice(0, -1);
+      const normalizedType = (collectionType === 'querie' ? 'query' : collectionType) as ResourceType;
+      counts.set(normalizedType, (counts.get(normalizedType) || 0) + 1);
+    });
+    return counts;
+  }, [resources]);
+
+  const availableTypes = useMemo(
+    () =>
+      Array.from(
+        new Set(
+          resources.map((resource) => {
+            const collectionType = resource.collection.slice(0, -1);
+            return collectionType === 'querie' ? 'query' : collectionType;
+          })
+        )
+      ) as ResourceType[],
+    [resources]
+  );
+
+  const filterButtons = useMemo(
+    () =>
+      availableTypes
+        .filter((type): type is NonNullable<ResourceType> => type !== null)
+        .map((type) => ({
+          type,
+          // Format the label to be capitalized and pluralized if needed
+          label: type.charAt(0).toUpperCase() + type.slice(1) + (type.endsWith('s') ? '' : 's'),
+          count: resourceTypeCounts.get(type) || 0,
+        })),
+    [availableTypes, resourceTypeCounts]
+  );
+
+  return (
+    <div className="mx-auto not-prose py-4 space-y-4 my-4">
+      {title && <h2 className="text-2xl font-semibold text-[rgb(var(--ec-page-text))]">{title}</h2>}
+      <div className="flow-root bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border-[rgb(var(--ec-page-border))] border p-4 pb-2 rounded-lg text-[rgb(var(--ec-page-text))]">
+        <div className="space-y-4">
+          <h2 className="text-xl font-semibold">
+            {subtitle} ({searchTerm || typeFilter ? `${filteredResources.length}/${resources.length}` : resources.length})
+          </h2>
+          <span className="text-sm text-[rgb(var(--ec-page-text-muted))]">{description}</span>
+
+          {/* Type filter buttons - only shown if there are filter options */}
+          {filterButtons.length > 0 && (
+            <div className="flex gap-2 pb-2 flex-wrap">
+              {filterButtons.map((button) => (
+                <FilterButton
+                  key={button.type}
+                  type={button.type}
+                  label={button.label}
+                  count={button.count}
+                  typeFilter={typeFilter}
+                  setTypeFilter={setTypeFilter}
+                  setCurrentPage={setCurrentPage}
+                />
+              ))}
+            </div>
+          )}
+
+          <div className="relative">
+            <div className="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
+              <svg
+                className="h-5 w-5 text-[rgb(var(--ec-icon-color))]"
+                viewBox="0 0 20 20"
+                fill="currentColor"
+                aria-hidden="true"
+              >
+                <path
+                  fillRule="evenodd"
+                  d="M9 3.5a5.5 5.5 0 100 11 5.5 5.5 0 000-11zM2 9a7 7 0 1112.452 4.391l3.328 3.329a.75.75 0 11-1.06 1.06l-3.329-3.328A7 7 0 012 9z"
+                  clipRule="evenodd"
+                />
+              </svg>
+            </div>
+            <input
+              type="text"
+              value={searchTerm}
+              onChange={(e) => {
+                setSearchTerm(e.target.value);
+                setCurrentPage(1); // Reset to first page when searching
+              }}
+              placeholder="Search by name, type, description, or tags..."
+              className="block w-full rounded-md border-0 py-1.5 pl-10 pr-10 bg-[rgb(var(--ec-input-bg))] text-[rgb(var(--ec-input-text))] ring-1 ring-inset ring-[rgb(var(--ec-input-border))] placeholder:text-[rgb(var(--ec-input-placeholder))] focus:ring-2 focus:ring-inset focus:ring-[rgb(var(--ec-accent))] sm:text-sm sm:leading-6"
+            />
+            {searchTerm && (
+              <button
+                onClick={() => {
+                  setSearchTerm('');
+                  setCurrentPage(1); // Reset to first page when clearing search
+                }}
+                className="absolute inset-y-0 right-0 flex items-center pr-3"
+                aria-label="Clear search"
+              >
+                <svg
+                  className="h-5 w-5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-icon-hover))]"
+                  viewBox="0 0 20 20"
+                  fill="currentColor"
+                >
+                  <path d="M6.28 5.22a.75.75 0 00-1.06 1.06L8.94 10l-3.72 3.72a.75.75 0 101.06 1.06L10 11.06l3.72 3.72a.75.75 0 101.06-1.06L11.06 10l3.72-3.72a.75.75 0 00-1.06-1.06L10 8.94 6.28 5.22z" />
+                </svg>
+              </button>
+            )}
+          </div>
+        </div>
+        <div className="overflow-x-auto">
+          <div className="inline-block min-w-full py-2 align-middle">
+            <div className="max-w-full overflow-hidden">
+              <table className="min-w-full table-fixed divide-y divide-[rgb(var(--ec-page-border))] rounded-xs bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))]">
+                <thead>
+                  <tr>
+                    <th
+                      scope="col"
+                      className={`${showTags || showOwners ? 'w-1/5' : 'w-1/4'} py-3.5 pl-4 pr-3 text-left text-sm font-semibold text-[rgb(var(--ec-page-text))] sm:pl-6`}
+                    >
+                      Name
+                    </th>
+                    <th
+                      scope="col"
+                      className="w-[100px] px-3 py-3.5 text-left text-sm font-semibold text-[rgb(var(--ec-page-text))]"
+                    >
+                      Version
+                    </th>
+                    <th
+                      scope="col"
+                      className="w-[100px] py-3.5 pl-3.5 pr-3 text-left text-sm font-semibold text-[rgb(var(--ec-page-text))]"
+                    >
+                      Type
+                    </th>
+                    <th
+                      scope="col"
+                      className={`${showTags && showOwners ? 'w-1/4' : showTags || showOwners ? 'w-1/3' : 'w-1/2'} px-3 py-3.5 text-left text-sm font-semibold text-[rgb(var(--ec-page-text))]`}
+                    >
+                      Description
+                    </th>
+                    {showTags && (
+                      <th
+                        scope="col"
+                        className="w-1/6 px-3 py-3.5 text-left text-sm font-semibold text-[rgb(var(--ec-page-text))]"
+                      >
+                        Tags
+                      </th>
+                    )}
+                    {showOwners && (
+                      <th
+                        scope="col"
+                        className="w-1/6 px-3 py-3.5 text-left text-sm font-semibold text-[rgb(var(--ec-page-text))]"
+                      >
+                        Owners
+                      </th>
+                    )}
+                  </tr>
+                </thead>
+                <tbody className="divide-y divide-[rgb(var(--ec-page-border))]">
+                  {paginatedResources.length > 0 ? (
+                    paginatedResources.map((resource) => (
+                      <ResourceRow
+                        key={`${resource.collection}-${resource.id}-${resource.version}`}
+                        resource={resource}
+                        showTags={showTags}
+                        showOwners={showOwners}
+                      />
+                    ))
+                  ) : (
+                    <tr>
+                      <td
+                        colSpan={showTags && showOwners ? 6 : showTags || showOwners ? 5 : 4}
+                        className="text-center py-4 text-sm text-[rgb(var(--ec-page-text-muted))]"
+                      >
+                        No resources found
+                      </td>
+                    </tr>
+                  )}
+                </tbody>
+              </table>
+            </div>
+          </div>
+        </div>
+        {totalPages > 1 && (
+          <div className="flex items-center justify-between border-t border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] px-4 py-3 sm:px-6 -mt-2">
+            <div className="flex flex-1 justify-between sm:hidden">
+              <button
+                onClick={() => setCurrentPage(currentPage - 1)}
+                disabled={currentPage === 1}
+                className={`relative inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] px-4 py-2 text-sm font-medium ${currentPage === 1 ? 'text-[rgb(var(--ec-icon-color))]' : 'text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))]'}`}
+              >
+                Previous
+              </button>
+              <button
+                onClick={() => setCurrentPage(currentPage + 1)}
+                disabled={currentPage === totalPages}
+                className={`relative ml-3 inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] px-4 py-2 text-sm font-medium ${currentPage === totalPages ? 'text-[rgb(var(--ec-icon-color))]' : 'text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))]'}`}
+              >
+                Next
+              </button>
+            </div>
+            <div className="hidden sm:flex sm:flex-1 sm:items-center sm:justify-between">
+              <div>
+                <p className="text-sm text-[rgb(var(--ec-page-text-muted))]">
+                  Showing <span className="font-medium">{startIndex + 1}</span> to{' '}
+                  <span className="font-medium">{Math.min(startIndex + itemsPerPage, filteredResources.length)}</span> of{' '}
+                  <span className="font-medium">{filteredResources.length}</span> results
+                </p>
+              </div>
+              <div>
+                <nav className="isolate inline-flex -space-x-px rounded-md shadow-xs" aria-label="Pagination">
+                  <button
+                    onClick={() => setCurrentPage(currentPage - 1)}
+                    disabled={currentPage === 1}
+                    className={`relative inline-flex items-center rounded-l-md px-2 py-2 ${currentPage === 1 ? 'text-[rgb(var(--ec-icon-color))]' : 'text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-content-hover))]'} ring-1 ring-inset ring-[rgb(var(--ec-page-border))]`}
+                  >
+                    <span className="sr-only">Previous</span>
+                    <svg className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+                      <path
+                        fillRule="evenodd"
+                        d="M12.79 5.23a.75.75 0 01-.02 1.06L8.832 10l3.938 3.71a.75.75 0 11-1.04 1.08l-4.5-4.25a.75.75 0 010-1.08l4.5-4.25a.75.75 0 011.06.02z"
+                        clipRule="evenodd"
+                      />
+                    </svg>
+                  </button>
+                  <button
+                    onClick={() => setCurrentPage(currentPage + 1)}
+                    disabled={currentPage === totalPages}
+                    className={`relative inline-flex items-center rounded-r-md px-2 py-2 ${currentPage === totalPages ? 'text-[rgb(var(--ec-icon-color))]' : 'text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-content-hover))]'} ring-1 ring-inset ring-[rgb(var(--ec-page-border))]`}
+                  >
+                    <span className="sr-only">Next</span>
+                    <svg className="h-5 w-5" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+                      <path
+                        fillRule="evenodd"
+                        d="M7.21 14.77a.75.75 0 01.02-1.06L11.168 10 7.23 6.29a.75.75 0 111.04-1.08l4.5 4.25a.75.75 0 010 1.08l-4.5 4.25a.75.75 0 01-1.06-.02z"
+                        clipRule="evenodd"
+                      />
+                    </svg>
+                  </button>
+                </nav>
+              </div>
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default ResourceGroupTable;
diff --git a/eventcatalog/src/components/MDX/ResourceLink/ResourceLink.astro b/packages/core/eventcatalog/src/components/MDX/ResourceLink/ResourceLink.astro
similarity index 80%
rename from eventcatalog/src/components/MDX/ResourceLink/ResourceLink.astro
rename to packages/core/eventcatalog/src/components/MDX/ResourceLink/ResourceLink.astro
index 938917443..495198a96 100644
--- a/eventcatalog/src/components/MDX/ResourceLink/ResourceLink.astro
+++ b/packages/core/eventcatalog/src/components/MDX/ResourceLink/ResourceLink.astro
@@ -2,9 +2,11 @@
 import { buildUrl } from '@utils/url-builder';
 import { getItemsFromCollectionByIdAndSemverOrLatest, resourceToCollectionMap } from '@utils/collections/util';
 import { getCollection } from 'astro:content';
+import { getResourceReferenceStyle } from '@utils/resource-reference-colors';
 
 const { id, version, type } = Astro.props;
 const collection = resourceToCollectionMap[type as keyof typeof resourceToCollectionMap];
+const resourceReferenceStyle = getResourceReferenceStyle(type);
 
 let slotHTML = await Astro.slots.render('default');
 let href = '#';
@@ -43,7 +45,11 @@ try {
 
 {
   !linkHasError && (
-    <a href={href} class="text-purple-500 hover:text-purple-700">
+    <a
+      href={href}
+      class="rounded px-1 -mx-1 text-[var(--ec-resource-ref-color)] hover:bg-[var(--ec-resource-ref-bg)] transition-colors"
+      style={resourceReferenceStyle}
+    >
       {slotHTML}
     </a>
   )
diff --git a/packages/core/eventcatalog/src/components/MDX/ResourceRef/ResourceRef.astro b/packages/core/eventcatalog/src/components/MDX/ResourceRef/ResourceRef.astro
new file mode 100644
index 000000000..1923f2c5d
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/ResourceRef/ResourceRef.astro
@@ -0,0 +1,569 @@
+---
+/**
+ * Inline resource reference component with hover tooltip.
+ *
+ * Usage via remark plugin:
+ * [[service|OrderService]] -> Links to OrderService with tooltip
+ * [[Order]] -> Shorthand, defaults to entity type
+ */
+import { buildUrl } from '@utils/url-builder';
+import {
+  getItemsFromCollectionByIdAndSemverOrLatest,
+  resourceToCollectionMap,
+  getDeprecatedDetails,
+} from '@utils/collections/util';
+import { getCollection } from 'astro:content';
+import { getServiceSpecifications, getSpecUrl, getSpecLabel } from '@components/Grids/specification-utils';
+import { getResourceReferenceStyle } from '@utils/resource-reference-colors';
+import { isIconPath, resolveIconUrl } from '@utils/icon';
+
+interface Props {
+  type:
+    | 'agent'
+    | 'entity'
+    | 'service'
+    | 'event'
+    | 'command'
+    | 'query'
+    | 'domain'
+    | 'flow'
+    | 'channel'
+    | 'diagram'
+    | 'container'
+    | 'system'
+    | 'user'
+    | 'team'
+    | 'doc'
+    | 'adr'
+    | 'data-product';
+  version?: string;
+}
+
+const { type = 'entity', version } = Astro.props;
+
+// Get resource ID from slot content
+const slotContent = await Astro.slots.render('default');
+const resourceId = slotContent.trim();
+
+const normalizeCustomDocPath = (value: string): string => {
+  const normalized = value
+    .trim()
+    .replace(/^https?:\/\/[^/]+/i, '')
+    .replace(/\\/g, '/');
+  return normalized
+    .replace(/^\/+/, '')
+    .replace(/^docs\/custom\//i, '')
+    .replace(/^docs\//i, '')
+    .replace(/\/+$/, '');
+};
+
+const normalizedResourceId = normalizeCustomDocPath(resourceId).toLowerCase();
+
+// Map type to collection name
+const collection = resourceToCollectionMap[type as keyof typeof resourceToCollectionMap];
+
+const typeLabels: Record<string, string> = {
+  agent: 'Agent',
+  entity: 'Entity',
+  service: 'Service',
+  event: 'Event',
+  command: 'Command',
+  query: 'Query',
+  domain: 'Domain',
+  flow: 'Flow',
+  channel: 'Channel',
+  diagram: 'Diagram',
+  container: 'Container',
+  system: 'System',
+  user: 'User',
+  team: 'Team',
+  doc: 'Custom Doc',
+  adr: 'Decision Record',
+  'data-product': 'Data Product',
+};
+
+// SVG icons for each type (from heroicons outline)
+const typeIcons: Record<string, string> = {
+  agent:
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M12 6V3m-4.5 7.5h9m-9 3h9M7.5 18h9A2.5 2.5 0 0019 15.5v-5A2.5 2.5 0 0016.5 8h-9A2.5 2.5 0 005 10.5v5A2.5 2.5 0 007.5 18zM9 21h6" />',
+  entity:
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M20 7l-8-4-8 4m16 0l-8 4m8-4v10l-8 4m0-10L4 7m8 4v10M4 7v10l8 4" />', // Box/cube
+  service:
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M5 12h14M5 12a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v4a2 2 0 01-2 2M5 12a2 2 0 00-2 2v4a2 2 0 002 2h14a2 2 0 002-2v-4a2 2 0 00-2-2m-2-4h.01M17 16h.01" />', // Server
+  event:
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M3.75 13.5l10.5-11.25L12 10.5h8.25L9.75 21.75 12 13.5H3.75z" />', // Bolt
+  command:
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M8.625 12a.375.375 0 11-.75 0 .375.375 0 01.75 0zm0 0H8.25m4.125 0a.375.375 0 11-.75 0 .375.375 0 01.75 0zm0 0H12m4.125 0a.375.375 0 11-.75 0 .375.375 0 01.75 0zm0 0h-.375M21 12c0 4.556-4.03 8.25-9 8.25a9.764 9.764 0 01-2.555-.337A5.972 5.972 0 015.41 20.97a5.969 5.969 0 01-.474-.065 4.48 4.48 0 00.978-2.025c.09-.457-.133-.901-.467-1.226C3.93 16.178 3 14.189 3 12c0-4.556 4.03-8.25 9-8.25s9 3.694 9 8.25z" />', // ChatBubble
+  query:
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M21 21l-5.197-5.197m0 0A7.5 7.5 0 105.196 5.196a7.5 7.5 0 0010.607 10.607z" />', // MagnifyingGlass
+  domain:
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M2.25 7.125C2.25 6.504 2.754 6 3.375 6h6c.621 0 1.125.504 1.125 1.125v3.75c0 .621-.504 1.125-1.125 1.125h-6a1.125 1.125 0 01-1.125-1.125v-3.75zM14.25 8.625c0-.621.504-1.125 1.125-1.125h5.25c.621 0 1.125.504 1.125 1.125v8.25c0 .621-.504 1.125-1.125 1.125h-5.25a1.125 1.125 0 01-1.125-1.125v-8.25zM3.75 16.125c0-.621.504-1.125 1.125-1.125h5.25c.621 0 1.125.504 1.125 1.125v2.25c0 .621-.504 1.125-1.125 1.125h-5.25a1.125 1.125 0 01-1.125-1.125v-2.25z" />', // RectangleGroup
+  flow: '<path stroke-linecap="round" stroke-linejoin="round" d="M3.75 12h16.5m-16.5 3.75h16.5M3.75 19.5h16.5M5.625 4.5h12.75a1.875 1.875 0 010 3.75H5.625a1.875 1.875 0 010-3.75z" />', // QueueList
+  channel:
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M7.5 21L3 16.5m0 0L7.5 12M3 16.5h13.5m0-13.5L21 7.5m0 0L16.5 12M21 7.5H7.5" />', // ArrowsRightLeft
+  diagram:
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M9 6.75V15m6-6v8.25m.503 3.498l4.875-2.437c.381-.19.622-.58.622-1.006V4.82c0-.836-.88-1.38-1.628-1.006l-3.869 1.934c-.317.159-.69.159-1.006 0L9.503 3.252a1.125 1.125 0 00-1.006 0L3.622 5.689C3.24 5.88 3 6.27 3 6.695V19.18c0 .836.88 1.38 1.628 1.006l3.869-1.934c.317-.159.69-.159 1.006 0l4.994 2.497c.317.158.69.158 1.006 0z" />', // Map
+  container:
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M20.25 6.375c0 2.278-3.694 4.125-8.25 4.125S3.75 8.653 3.75 6.375m16.5 0c0-2.278-3.694-4.125-8.25-4.125S3.75 4.097 3.75 6.375m16.5 0v11.25c0 2.278-3.694 4.125-8.25 4.125s-8.25-1.847-8.25-4.125V6.375m16.5 0v3.75m-16.5-3.75v3.75m16.5 0v3.75C20.25 16.153 16.556 18 12 18s-8.25-1.847-8.25-4.125v-3.75m16.5 0c0 2.278-3.694 4.125-8.25 4.125s-8.25-1.847-8.25-4.125" />', // Database
+  user: '<path stroke-linecap="round" stroke-linejoin="round" d="M15.75 6a3.75 3.75 0 11-7.5 0 3.75 3.75 0 017.5 0zM4.501 20.118a7.5 7.5 0 0114.998 0A17.933 17.933 0 0112 21.75c-2.676 0-5.216-.584-7.499-1.632z" />', // User
+  team: '<path stroke-linecap="round" stroke-linejoin="round" d="M18 18.72a9.094 9.094 0 003.741-.479 3 3 0 00-4.682-2.72m.94 3.198l.001.031c0 .225-.012.447-.037.666A11.944 11.944 0 0112 21c-2.17 0-4.207-.576-5.963-1.584A6.062 6.062 0 016 18.719m12 0a5.971 5.971 0 00-.941-3.197m0 0A5.995 5.995 0 0012 12.75a5.995 5.995 0 00-5.058 2.772m0 0a3 3 0 00-4.681 2.72 8.986 8.986 0 003.74.477m.94-3.197a5.971 5.971 0 00-.94 3.197M15 6.75a3 3 0 11-6 0 3 3 0 016 0zm6 3a2.25 2.25 0 11-4.5 0 2.25 2.25 0 014.5 0zm-13.5 0a2.25 2.25 0 11-4.5 0 2.25 2.25 0 014.5 0z" />', // UserGroup
+  doc: '<path stroke-linecap="round" stroke-linejoin="round" d="M14 2v4a2 2 0 002 2h4" /><path stroke-linecap="round" stroke-linejoin="round" d="M15 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V7z" /><path stroke-linecap="round" stroke-linejoin="round" d="M10 9H8" /><path stroke-linecap="round" stroke-linejoin="round" d="M16 13H8" /><path stroke-linecap="round" stroke-linejoin="round" d="M16 17H8" />', // FileText
+  'data-product':
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M21 7.5l-9-5.25L3 7.5m18 0l-9 5.25M21 7.5v9l-9 5.25M3 7.5l9 5.25M3 7.5v9l9 5.25m0-9v9" />', // Cube
+  system:
+    '<path stroke-linecap="round" stroke-linejoin="round" d="M2.25 7.125C2.25 6.504 2.754 6 3.375 6h6c.621 0 1.125.504 1.125 1.125v3.75c0 .621-.504 1.125-1.125 1.125h-6a1.125 1.125 0 01-1.125-1.125v-3.75zM14.25 8.625c0-.621.504-1.125 1.125-1.125h5.25c.621 0 1.125.504 1.125 1.125v8.25c0 .621-.504 1.125-1.125 1.125h-5.25a1.125 1.125 0 01-1.125-1.125v-8.25zM3.75 16.125c0-.621.504-1.125 1.125-1.125h5.25c.621 0 1.125.504 1.125 1.125v2.25c0 .621-.504 1.125-1.125 1.125h-5.25a1.125 1.125 0 01-1.125-1.125v-2.25z" />', // Group (systems)
+  adr: '<path stroke-linecap="round" stroke-linejoin="round" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" /><path stroke-linecap="round" stroke-linejoin="round" d="M9 7h2" />', // ClipboardList-ish (ADR)
+};
+
+const label = typeLabels[type] || typeLabels.entity;
+const iconPath = typeIcons[type] || typeIcons.entity;
+const resourceReferenceStyle = getResourceReferenceStyle(type);
+
+let resource: any = null;
+let href = '#';
+let hasError = false;
+let errorMessage = '';
+
+try {
+  if (type === 'doc') {
+    const docs = (await getCollection('customPages')) as {
+      id: string;
+      data: { title?: string; summary?: string; slug?: string; owners?: any[] };
+    }[];
+
+    const doc = docs.find((entry) => {
+      const normalizedId = normalizeCustomDocPath(entry.id).toLowerCase();
+      const normalizedSlug = normalizeCustomDocPath(entry.data.slug || '').toLowerCase();
+
+      return normalizedId === normalizedResourceId || normalizedSlug === normalizedResourceId;
+    });
+
+    if (!doc) {
+      throw new Error(`Document not found: ${resourceId}`);
+    }
+
+    const docSlug = normalizeCustomDocPath(doc.data.slug || doc.id);
+    href = buildUrl(`/docs/custom/${docSlug}`);
+    resource = {
+      ...doc,
+      data: {
+        ...doc.data,
+        name: doc.data.title || docSlug,
+      },
+    };
+  } else {
+    if (!collection) {
+      throw new Error(`Unknown resource type: ${type}`);
+    }
+
+    const resourcesCollection = (await getCollection(collection as any)) as { data: { id: string; version: string } }[];
+    const resources = getItemsFromCollectionByIdAndSemverOrLatest(resourcesCollection, resourceId, version);
+
+    if (resources.length === 0) {
+      throw new Error(`Resource not found: ${resourceId}`);
+    }
+
+    resource = resources[0];
+    // Diagrams use /diagrams/ path, other resources use /docs/{collection}/
+    href =
+      type === 'diagram'
+        ? buildUrl(`/diagrams/${resourceId}/${resource.data.version}`)
+        : buildUrl(`/docs/${collection}/${resourceId}/${resource.data.version}`);
+  }
+} catch (error) {
+  hasError = true;
+  errorMessage = error instanceof Error ? error.message : 'Unknown error';
+}
+
+// Truncate summary if too long
+const maxSummaryLength = 120;
+const summary = resource?.data?.summary || '';
+const truncatedSummary = summary.length > maxSummaryLength ? summary.slice(0, maxSummaryLength) + '...' : summary;
+
+const isVersionedResource = type !== 'doc';
+
+// Only these types have visualizers
+const hasVisualizer = ['agent', 'domain', 'service', 'event', 'query', 'command', 'container', 'system'].includes(type);
+
+// Check deprecation status
+const deprecation = resource ? getDeprecatedDetails(resource) : null;
+const isDeprecated = deprecation?.isMarkedAsDeprecated || false;
+const resourceIconUrl = isIconPath(resource?.data?.styles?.icon) ? resolveIconUrl(resource.data.styles.icon) : null;
+
+// Get owners (first 2)
+const owners = resource?.data?.owners?.slice(0, 2) || [];
+
+// Check if message type has a schema
+const isMessageType = ['event', 'command', 'query'].includes(type);
+const hasSchema = isMessageType && resource?.data?.schemaPath;
+
+// Check if resource has a repository URL
+const repositoryUrl = resource?.data?.repository?.url;
+
+// For services: get messages (sends/receives) with resolved versions
+const maxMessages = 3;
+const sends = resource?.data?.sends || [];
+const receives = resource?.data?.receives || [];
+const isService = type === 'service' || type === 'agent';
+const supportsSpecifications = type === 'service';
+
+// Helper to resolve message version and collection - use specified version or fetch from collection
+const resolveMessage = async (msg: any): Promise<{ version: string | null; collection: string | null }> => {
+  // If version is specified and not "latest", use it (assume event as default collection)
+  if (msg.version && msg.version !== 'latest') {
+    return { version: msg.version, collection: 'events' };
+  }
+
+  // Try to find the message in events, commands, or queries collections
+  const collections = ['events', 'commands', 'queries'];
+  for (const col of collections) {
+    try {
+      const items = (await getCollection(col as any)) as { data: { id: string; version: string } }[];
+      const found = getItemsFromCollectionByIdAndSemverOrLatest(items, msg.id);
+      if (found.length > 0 && found[0].data.version && found[0].data.version !== 'latest') {
+        return { version: found[0].data.version, collection: col };
+      }
+    } catch (e) {
+      // Collection might not exist or item not found, continue
+    }
+  }
+  return { version: null, collection: null };
+};
+
+// Resolve versions and collections for messages to show
+const sendsWithVersions = await Promise.all(
+  sends.slice(0, maxMessages).map(async (msg: any) => {
+    const resolved = await resolveMessage(msg);
+    return { ...msg, resolvedVersion: resolved.version, resolvedCollection: resolved.collection };
+  })
+);
+const receivesWithVersions = await Promise.all(
+  receives.slice(0, maxMessages).map(async (msg: any) => {
+    const resolved = await resolveMessage(msg);
+    return { ...msg, resolvedVersion: resolved.version, resolvedCollection: resolved.collection };
+  })
+);
+
+// Get specifications for services
+const specifications = supportsSpecifications ? getServiceSpecifications(resource?.data) : [];
+const hasSpecifications = specifications.length > 0;
+
+// Generate unique ID for this instance
+const tooltipId = `ref-tooltip-${Math.random().toString(36).slice(2, 9)}`;
+---
+
+<span class="resource-ref-wrapper inline relative">
+  {
+    hasError ? (
+      <span
+        class="text-[rgb(var(--ec-page-text-muted))] underline decoration-wavy decoration-red-400/50 underline-offset-2 cursor-help"
+        title={`Reference not found: ${resourceId}`}
+      >
+        {resourceId}
+      </span>
+    ) : (
+      <>
+        <a
+          href={href}
+          class:list={[
+            'resource-ref-trigger inline-flex items-center gap-1 px-1 -mx-1 rounded font-medium underline decoration-dotted decoration-2 underline-offset-[3px] transition-colors',
+            'text-[var(--ec-resource-ref-color)] decoration-[var(--ec-resource-ref-color)] hover:bg-[var(--ec-resource-ref-bg)]',
+          ]}
+          style={resourceReferenceStyle}
+          data-tooltip-id={tooltipId}
+        >
+          <svg
+            class="w-3.5 h-3.5 flex-shrink-0 text-[var(--ec-resource-ref-color)]"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            stroke-width="1.75"
+            set:html={iconPath}
+          />
+          <span>
+            {resource?.data?.name || resourceId}
+            {isDeprecated && ' (deprecated)'}
+          </span>
+        </a>
+        <span
+          id={tooltipId}
+          class="resource-ref-tooltip fixed w-80 bg-[rgb(var(--ec-card-bg))] border border-[rgb(var(--ec-page-border))] border-l-[3px] rounded-r-lg rounded-l-none shadow-lg shadow-black/8 z-[9999] text-left overflow-hidden opacity-0 pointer-events-none transition-all duration-150 scale-95 origin-top-left"
+          style={`${resourceReferenceStyle}; border-left-color: var(--ec-resource-ref-color);`}
+        >
+          {/* Deprecation banner */}
+          {isDeprecated && (
+            <span class="flex items-center gap-1.5 px-3 py-1.5 bg-[rgb(var(--ec-badge-event-bg))] text-[rgb(var(--ec-badge-event-text))] text-xs font-medium">
+              <svg class="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+                <path
+                  stroke-linecap="round"
+                  stroke-linejoin="round"
+                  d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"
+                />
+              </svg>
+              Deprecated
+            </span>
+          )}
+
+          <span class="block p-3">
+            {/* Header: Name with icon top-right */}
+            <span class="grid grid-cols-[minmax(0,1fr)_1.25rem] items-start gap-3 border-b border-[rgb(var(--ec-page-border))] pb-2 mb-3">
+              <span class="flex min-w-0 flex-col">
+                <span class="font-semibold text-[rgb(var(--ec-page-text))] text-[0.95rem] leading-tight">
+                  {resource?.data?.name || resourceId}
+                </span>
+                <span class="mt-0.5 flex items-center gap-1.5 text-[0.7rem] text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wide">
+                  <span class="text-[0.65rem] text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wide">{label}</span>
+                  {isVersionedResource && (
+                    <>
+                      <span aria-hidden="true">•</span>
+                      <span class="font-mono normal-case">v{resource?.data?.version}</span>
+                    </>
+                  )}
+                </span>
+              </span>
+              <span class="flex h-[24px] w-[24px] items-start justify-end mr-4">
+                {resourceIconUrl ? (
+                  <img
+                    src={resourceIconUrl}
+                    alt=""
+                    class="not-prose m-0 block  h-[24px] w-[24px] object-contain"
+                    loading="lazy"
+                  />
+                ) : (
+                  <svg
+                    class="h-5 w-5"
+                    style="color: var(--ec-resource-ref-color);"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                    stroke-width="1.5"
+                    set:html={iconPath}
+                  />
+                )}
+              </span>
+            </span>
+
+            {/* Summary */}
+            {truncatedSummary && (
+              <span class="block text-[rgb(var(--ec-page-text-muted))] text-[0.8rem] leading-relaxed mb-3">
+                {truncatedSummary}
+              </span>
+            )}
+
+            {/* Metadata */}
+            {(isService && (sends.length > 0 || receives.length > 0)) || hasSpecifications || owners.length > 0 ? (
+              <span class="block text-[0.7rem] mb-3 space-y-1">
+                {isService && sends.length > 0 && (
+                  <span class="flex items-baseline gap-2">
+                    <span class="text-[rgb(var(--ec-page-text-muted))]">Publishes</span>
+                    <span class="font-mono text-[rgb(var(--ec-page-text))]">
+                      {sendsWithVersions.slice(0, 2).map((msg: any, idx: number) => (
+                        <>
+                          {msg.resolvedVersion && msg.resolvedCollection ? (
+                            <a
+                              href={buildUrl(`/docs/${msg.resolvedCollection}/${msg.id}/${msg.resolvedVersion}`)}
+                              class="hover:underline hover:text-[rgb(var(--ec-accent))]"
+                            >
+                              {msg.id}
+                            </a>
+                          ) : (
+                            <span class="text-[rgb(var(--ec-page-text-muted))]">{msg.id}</span>
+                          )}
+                          {idx < Math.min(sendsWithVersions.length, 2) - 1 && ', '}
+                        </>
+                      ))}
+                      {sends.length > 2 && <span class="text-[rgb(var(--ec-page-text-muted))]"> +{sends.length - 2}</span>}
+                    </span>
+                  </span>
+                )}
+                {isService && receives.length > 0 && (
+                  <span class="flex items-baseline gap-2">
+                    <span class="text-[rgb(var(--ec-page-text-muted))]">Subscribes</span>
+                    <span class="font-mono text-[rgb(var(--ec-page-text))]">
+                      {receivesWithVersions.slice(0, 2).map((msg: any, idx: number) => (
+                        <>
+                          {msg.resolvedVersion && msg.resolvedCollection ? (
+                            <a
+                              href={buildUrl(`/docs/${msg.resolvedCollection}/${msg.id}/${msg.resolvedVersion}`)}
+                              class="hover:underline hover:text-[rgb(var(--ec-accent))]"
+                            >
+                              {msg.id}
+                            </a>
+                          ) : (
+                            <span class="text-[rgb(var(--ec-page-text-muted))]">{msg.id}</span>
+                          )}
+                          {idx < Math.min(receivesWithVersions.length, 2) - 1 && ', '}
+                        </>
+                      ))}
+                      {receives.length > 2 && <span class="text-[rgb(var(--ec-page-text-muted))]"> +{receives.length - 2}</span>}
+                    </span>
+                  </span>
+                )}
+                {hasSpecifications && (
+                  <span class="flex items-baseline gap-2">
+                    <span class="text-[rgb(var(--ec-page-text-muted))]">APIs</span>
+                    <span class="font-mono text-[rgb(var(--ec-page-text))]">
+                      {specifications.map((spec: any, idx: number) => (
+                        <>
+                          <a
+                            href={getSpecUrl(spec, resourceId, resource?.data?.version)}
+                            class="hover:underline hover:text-[rgb(var(--ec-accent))]"
+                          >
+                            {getSpecLabel(spec.type)}
+                          </a>
+                          {idx < specifications.length - 1 && ', '}
+                        </>
+                      ))}
+                    </span>
+                  </span>
+                )}
+                {owners.length > 0 && (
+                  <span class="flex items-baseline gap-2">
+                    <span class="text-[rgb(var(--ec-page-text-muted))]">Owner</span>
+                    <span class="font-mono text-[rgb(var(--ec-page-text))]">
+                      {owners.map((o: any, idx: number) => {
+                        const ownerId = typeof o === 'string' ? o : o.id;
+                        return (
+                          <>
+                            <a
+                              href={buildUrl(`/docs/users/${ownerId}`)}
+                              class="hover:underline hover:text-[rgb(var(--ec-accent))]"
+                            >
+                              {ownerId}
+                            </a>
+                            {idx < owners.length - 1 && ', '}
+                          </>
+                        );
+                      })}
+                    </span>
+                  </span>
+                )}
+              </span>
+            ) : null}
+
+            {/* Actions */}
+            <span class="flex items-center justify-between pt-1 text-[0.7rem]">
+              <span class="flex items-center gap-3">
+                {type === 'flow' && (
+                  <a
+                    href={buildUrl(`/visualiser/${collection}/${resourceId}/${resource?.data?.version}`)}
+                    class="text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]"
+                  >
+                    View flow
+                  </a>
+                )}
+                {hasSchema && (
+                  <a
+                    href={buildUrl(`/schemas/${collection}/${resourceId}/${resource?.data?.version}`)}
+                    class="text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]"
+                  >
+                    Schema
+                  </a>
+                )}
+                {hasVisualizer && type !== 'flow' && (
+                  <a
+                    href={buildUrl(`/visualiser/${collection}/${resourceId}/${resource?.data?.version}`)}
+                    class="text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]"
+                  >
+                    Map
+                  </a>
+                )}
+                {repositoryUrl && (
+                  <a
+                    href={repositoryUrl}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    class="text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]"
+                  >
+                    Repo
+                  </a>
+                )}
+              </span>
+              <a
+                href={href}
+                class="text-[var(--ec-resource-ref-color)] hover:underline font-medium"
+                style="color: var(--ec-resource-ref-color);"
+              >
+                {type === 'diagram' ? 'View diagram' : type === 'doc' ? 'View doc' : 'View docs'}
+              </a>
+            </span>
+          </span>
+        </span>
+      </>
+    )
+  }
+</span>
+
+<script>
+  // Initialize all resource ref tooltips
+  function initResourceRefTooltips() {
+    const triggers = document.querySelectorAll('.resource-ref-trigger');
+
+    triggers.forEach((trigger) => {
+      const tooltipId = trigger.getAttribute('data-tooltip-id');
+      if (!tooltipId) return;
+
+      const tooltip = document.getElementById(tooltipId);
+      if (!tooltip) return;
+
+      let hideTimeout: ReturnType<typeof setTimeout>;
+
+      const showTooltip = () => {
+        clearTimeout(hideTimeout);
+
+        // Get trigger position
+        const rect = trigger.getBoundingClientRect();
+        const tooltipWidth = 320; // w-80 = 20rem = 320px
+        const padding = 16;
+
+        // Calculate left position - try to align with trigger, but keep within viewport
+        let left = rect.left;
+
+        // If tooltip would overflow right edge, align to right edge of viewport
+        if (left + tooltipWidth > window.innerWidth - padding) {
+          left = window.innerWidth - tooltipWidth - padding;
+        }
+
+        // If tooltip would overflow left edge, align to left edge
+        if (left < padding) {
+          left = padding;
+        }
+
+        // Position below the trigger
+        const top = rect.bottom + 8;
+
+        tooltip.style.left = `${left}px`;
+        tooltip.style.top = `${top}px`;
+        tooltip.classList.remove('opacity-0', 'pointer-events-none', 'scale-95');
+        tooltip.classList.add('opacity-100', 'pointer-events-auto', 'scale-100');
+      };
+
+      const hideTooltip = () => {
+        hideTimeout = setTimeout(() => {
+          tooltip.classList.remove('opacity-100', 'pointer-events-auto', 'scale-100');
+          tooltip.classList.add('opacity-0', 'pointer-events-none', 'scale-95');
+        }, 100);
+      };
+
+      const keepTooltipOpen = () => {
+        clearTimeout(hideTimeout);
+      };
+
+      // Trigger events
+      trigger.addEventListener('mouseenter', showTooltip);
+      trigger.addEventListener('mouseleave', hideTooltip);
+      trigger.addEventListener('focus', showTooltip);
+      trigger.addEventListener('blur', hideTooltip);
+
+      // Tooltip events - keep open when hovering tooltip
+      tooltip.addEventListener('mouseenter', keepTooltipOpen);
+      tooltip.addEventListener('mouseleave', hideTooltip);
+    });
+  }
+
+  // Run on initial load
+  initResourceRefTooltips();
+
+  // Re-run after Astro page transitions
+  document.addEventListener('astro:page-load', initResourceRefTooltips);
+</script>
diff --git a/packages/core/eventcatalog/src/components/MDX/Schema.astro b/packages/core/eventcatalog/src/components/MDX/Schema.astro
new file mode 100644
index 000000000..c921703c6
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/Schema.astro
@@ -0,0 +1,34 @@
+---
+import fs from 'fs';
+import { Code } from 'astro-expressive-code/components';
+import { getAbsoluteFilePathForAstroFile } from '@utils/files';
+import { getResourceFilePath } from '@utils/resource-files';
+
+interface Props {
+  file?: string;
+  title?: string;
+  filePath: string;
+  lang?: string;
+}
+
+const { file = 'schema.json', title, filePath, lang = 'json' } = Astro.props;
+
+let code: string | null = null;
+
+const absoluteFilePath = getAbsoluteFilePathForAstroFile(filePath, file);
+
+const exists = fs.existsSync(absoluteFilePath);
+if (exists) {
+  code = fs.readFileSync(absoluteFilePath, 'utf-8');
+}
+---
+
+{
+  code ? (
+    <div class="not-prose max-w-4xl overflow-x-auto">
+      <Code code={code} title={title || file} lang={lang} />
+    </div>
+  ) : (
+    <div class="italic">Tried to load schema from {getResourceFilePath({ filePath }, file)}, but no schema can be found</div>
+  )
+}
diff --git a/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerPortal.tsx b/packages/core/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerPortal.tsx
similarity index 88%
rename from eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerPortal.tsx
rename to packages/core/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerPortal.tsx
index 6e37d21c6..f9da86e55 100644
--- a/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerPortal.tsx
+++ b/packages/core/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerPortal.tsx
@@ -5,7 +5,7 @@ const SchemaViewerPortal = (props: any) => {
 
   return (
     <div
-      id={`${props.id}-${props.file}-SchemaViewer-portal`}
+      data-schema-viewer-portal-id={props.id}
       data-expand={expandBool ? 'true' : 'false'}
       data-max-height={props.maxHeight}
       data-search={searchBool ? 'true' : 'false'}
diff --git a/packages/core/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerRoot.astro b/packages/core/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerRoot.astro
new file mode 100644
index 000000000..08ebc6041
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerRoot.astro
@@ -0,0 +1,149 @@
+---
+const { id, filePath, collection, version } = Astro.props;
+import fs from 'node:fs/promises';
+import { getCollection } from 'astro:content';
+import JSONSchemaViewer from '@components/SchemaExplorer/JSONSchemaViewer';
+import AvroSchemaViewer from '@components/SchemaExplorer/AvroSchemaViewer';
+import ProtobufSchemaViewer from '@components/SchemaExplorer/ProtobufSchemaViewer';
+import Admonition from '../Admonition';
+import { getMDXComponentsByName } from '@utils/markdown';
+import { resolveProjectPath } from '@utils/files';
+import { resolveSchemaViewer } from './schema-viewer-utils';
+
+type ResolvedSchemaViewer = Awaited<ReturnType<typeof resolveSchemaViewer>>;
+
+let schemas: ResolvedSchemaViewer[] = [];
+
+try {
+  const absoluteFilePath = resolveProjectPath(filePath);
+  const file = await fs.readFile(absoluteFilePath, 'utf-8');
+  const schemaViewers = getMDXComponentsByName(file, 'SchemaViewer');
+  const collectionSchemas = collection && version ? await getCollection('schemas') : [];
+
+  const getAllComponents = schemaViewers.map((schemaViewerProps: any, index: number) =>
+    resolveSchemaViewer({ id, version, collection, filePath, schemaViewerProps, collectionSchemas, index })
+  );
+
+  schemas = await Promise.all(getAllComponents);
+} catch (error) {
+  console.log('Failed to process schemas');
+  console.log(error);
+}
+---
+
+<section class="space-y-4">
+  {
+    schemas.length > 0 &&
+      schemas.map((schema) => {
+        if (!schema.render) return null;
+        return (
+          <div>
+            {schema.exists && (
+              <div
+                id={`${schema.id}-${schema.index}-SchemaViewer-client`}
+                class="not-prose my-4"
+                data-schema-viewer-client-id={schema.id}
+                data-schema-viewer-index={schema.index}
+                data-expand={schema.expand ? 'true' : 'false'}
+                data-search={schema.search !== false ? 'true' : 'false'}
+              >
+                {schema.title && <h2 class="text-2xl font-bold mb-2 mt-0!">{schema.title}</h2>}
+
+                {/* Render the viewer matching the schema format */}
+                {schema.isAvroSchema ? (
+                  <AvroSchemaViewer
+                    client:load
+                    schema={schema.schema}
+                    maxHeight={schema.maxHeight}
+                    expand={schema.expand}
+                    search={schema.search}
+                    showRequired={schema.showRequired}
+                  />
+                ) : schema.isProtobufSchema ? (
+                  <ProtobufSchemaViewer
+                    client:load
+                    schema={schema.schema}
+                    maxHeight={schema.maxHeight}
+                    expand={schema.expand}
+                    search={schema.search}
+                    showRequired={schema.showRequired}
+                  />
+                ) : (
+                  <JSONSchemaViewer
+                    client:load
+                    schema={schema.schema}
+                    maxHeight={schema.maxHeight}
+                    expand={schema.expand}
+                    search={schema.search}
+                  />
+                )}
+              </div>
+            )}
+
+            {/* User has tried to load the schema, but it was not found on file system */}
+            {!schema.exists && (
+              <Admonition type="warning">
+                <div>
+                  <span class="block font-bold">{`<SchemaViewer/>`} failed to load</span>
+                  <span class="block">
+                    {schema.parseError
+                      ? `Tried to parse schema from ${schema.schemaPath}, but it failed: ${schema.parseError}`
+                      : `Tried to load schema from ${schema.schemaPath || schema.file || 'the message schema collection'}, but no schema can be found`}
+                  </span>
+                </div>
+              </Admonition>
+            )}
+          </div>
+        );
+      })
+  }
+</section>
+
+<script is:inline define:vars={{ schemas }}>
+  // Can we move the SchemaViewerClient to another container? example container with the id "my-schema-viewer-container"
+  // and then we can move the SchemaViewerClient to that container?
+
+  function moveSchemaViewerToPortal(schema) {
+    const schemaViewerContainers = document.querySelectorAll(`[data-schema-viewer-portal-id="${schema.id}"]`);
+    const schemaPortalIndex = schemas.slice(0, schema.index).filter((previousSchema) => previousSchema.id === schema.id).length;
+    const schemaViewerContainer = schemaViewerContainers[schemaPortalIndex];
+    const schemaViewerClient = document.getElementById(`${schema.id}-${schema.index}-SchemaViewer-client`);
+
+    if (schemaViewerContainer && schemaViewerClient) {
+      // Get attributes from the portal
+      const expand = schemaViewerContainer.getAttribute('data-expand') === 'true';
+      const maxHeight = schemaViewerContainer.getAttribute('data-max-height');
+      const search = schemaViewerContainer.getAttribute('data-search');
+
+      // Set the expand attribute on the schema viewer client
+      if (expand) {
+        schemaViewerClient.setAttribute('data-expand', 'true');
+      }
+
+      // Set the search attribute on the schema viewer client
+      if (search) {
+        schemaViewerClient.setAttribute('data-search', search);
+      }
+
+      // Set the maxHeight on the schema viewer element
+      if (maxHeight) {
+        const schemaViewerElement = schemaViewerClient.querySelector('.schema-viewer');
+        if (schemaViewerElement) {
+          schemaViewerElement.style.maxHeight = `${maxHeight}px`;
+        }
+      }
+
+      schemaViewerContainer.appendChild(schemaViewerClient);
+    }
+  }
+
+  // on DOM ready, move the SchemaViewerClient to the portal
+  document.addEventListener('DOMContentLoaded', () => {
+    schemas.forEach(moveSchemaViewerToPortal);
+  });
+
+  // on DOM ready, move the SchemaViewerClient to the portal
+  document.addEventListener('astro:page-load', () => {
+    schemas.forEach(moveSchemaViewerToPortal);
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/components/MDX/SchemaViewer/schema-viewer-utils.spec.ts b/packages/core/eventcatalog/src/components/MDX/SchemaViewer/schema-viewer-utils.spec.ts
new file mode 100644
index 000000000..e86bcf91b
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/SchemaViewer/schema-viewer-utils.spec.ts
@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+import { resolveSchemaViewer } from './schema-viewer-utils';
+
+const currentMessageSchema = {
+  id: 'schema:events:OrderPlaced:1.0.0:git://contracts/events/OrderPlaced.schema.json',
+  data: {
+    ref: 'git://contracts/events/OrderPlaced.schema.json',
+    format: 'jsonschema',
+    content: '{"type":"object","title":"OrderPlaced"}',
+    default: true,
+    message: {
+      collection: 'events',
+      id: 'OrderPlaced',
+      version: '1.0.0',
+    },
+  },
+};
+
+describe('resolveSchemaViewer', () => {
+  it('uses the current message default schema when no file is set', async () => {
+    const schema = await resolveSchemaViewer({
+      id: 'OrderPlaced',
+      version: '1.0.0',
+      collection: 'events',
+      filePath: 'events/OrderPlaced/index.mdx',
+      schemaViewerProps: {},
+      collectionSchemas: [currentMessageSchema],
+      index: 0,
+    });
+
+    expect(schema.exists).toBe(true);
+    expect(schema.schema.title).toBe('OrderPlaced');
+    expect(schema.schemaPath).toBe('git://contracts/events/OrderPlaced.schema.json');
+  });
+
+  it('parses protobuf schemas from the schema collection', async () => {
+    const protoSchema = {
+      id: 'schema:events:FraudCheckCompleted:1.0.0:git://contracts/events/FraudCheckCompleted.proto',
+      data: {
+        ref: 'git://contracts/events/FraudCheckCompleted.proto',
+        format: 'protobuf',
+        content: 'syntax = "proto3";\nmessage FraudCheckCompleted {\n  string transaction_id = 1;\n}',
+        default: true,
+        message: {
+          collection: 'events',
+          id: 'FraudCheckCompleted',
+          version: '1.0.0',
+        },
+      },
+    };
+
+    const schema = await resolveSchemaViewer({
+      id: 'FraudCheckCompleted',
+      version: '1.0.0',
+      collection: 'events',
+      filePath: 'events/FraudCheckCompleted/index.mdx',
+      schemaViewerProps: {},
+      collectionSchemas: [protoSchema],
+      index: 0,
+    });
+
+    expect(schema.exists).toBe(true);
+    expect(schema.isProtobufSchema).toBe(true);
+    expect(schema.schema.syntax).toBe('proto3');
+    expect(schema.schema.messages[0].name).toBe('FraudCheckCompleted');
+    expect(schema.schema.messages[0].fields[0].name).toBe('transaction_id');
+  });
+
+  it('captures parse errors for invalid protobuf schemas', async () => {
+    const protoSchema = {
+      id: 'schema:events:FraudCheckCompleted:1.0.0:git://contracts/events/FraudCheckCompleted.proto',
+      data: {
+        ref: 'git://contracts/events/FraudCheckCompleted.proto',
+        format: 'protobuf',
+        content: '{"this": "is not protobuf"}',
+        default: true,
+        message: {
+          collection: 'events',
+          id: 'FraudCheckCompleted',
+          version: '1.0.0',
+        },
+      },
+    };
+
+    const schema = await resolveSchemaViewer({
+      id: 'FraudCheckCompleted',
+      version: '1.0.0',
+      collection: 'events',
+      filePath: 'events/FraudCheckCompleted/index.mdx',
+      schemaViewerProps: {},
+      collectionSchemas: [protoSchema],
+      index: 0,
+    });
+
+    expect(schema.exists).toBe(false);
+    expect(schema.parseError).toBeDefined();
+  });
+
+  it('does not use the schema collection when a file is set and missing', async () => {
+    const schema = await resolveSchemaViewer({
+      id: 'OrderPlaced',
+      version: '1.0.0',
+      collection: 'events',
+      filePath: 'events/OrderPlaced/index.mdx',
+      schemaViewerProps: {
+        file: 'missing-schema.json',
+      },
+      collectionSchemas: [currentMessageSchema],
+      index: 0,
+    });
+
+    expect(schema.exists).toBe(false);
+    expect(schema.schema).toBeUndefined();
+    expect(schema.schemaKey).toBe('missing-schema.json');
+  });
+});
diff --git a/packages/core/eventcatalog/src/components/MDX/SchemaViewer/schema-viewer-utils.ts b/packages/core/eventcatalog/src/components/MDX/SchemaViewer/schema-viewer-utils.ts
new file mode 100644
index 000000000..886164c88
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/SchemaViewer/schema-viewer-utils.ts
@@ -0,0 +1,151 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { load as loadYaml } from 'js-yaml';
+import { getAbsoluteFilePathForAstroFile, isAvroSchema, isProtobufSchema } from '../../../utils/files';
+import { parseProtobufSchema } from '../../../utils/protobuf-schema';
+
+type SchemaViewerProps = {
+  id?: string;
+  file?: string;
+  title?: string;
+  maxHeight?: string;
+  expand?: boolean;
+  search?: boolean;
+  showRequired?: boolean;
+  [key: string]: any;
+};
+
+type CollectionSchema = {
+  id: string;
+  data: {
+    content?: string;
+    file?: string;
+    filePath?: string;
+    ref?: string;
+    format?: string;
+    default?: boolean;
+    source?: {
+      path?: string;
+      branch?: string;
+    };
+    message?: {
+      collection: string;
+      id: string;
+      version: string;
+    };
+  };
+};
+
+type ResolveSchemaViewerOptions = {
+  id: string;
+  version?: string;
+  collection?: string;
+  filePath: string;
+  schemaViewerProps: SchemaViewerProps;
+  collectionSchemas: CollectionSchema[];
+  index: number;
+};
+
+export const getSchemaViewerKey = (schemaViewerProps: SchemaViewerProps) => schemaViewerProps.file || 'default';
+
+const isYamlSchema = (schemaPath?: string, format?: string) =>
+  schemaPath?.endsWith('.yml') || schemaPath?.endsWith('.yaml') || format === 'yaml';
+
+const isAvroSchemaReference = (schemaPath?: string, format?: string) =>
+  format === 'avro' || (schemaPath ? isAvroSchema(schemaPath) : false);
+
+const isProtobufSchemaReference = (schemaPath?: string, format?: string) =>
+  format === 'protobuf' || format === 'proto' || (schemaPath ? isProtobufSchema(schemaPath) : false);
+
+const parseSchemaContent = (content: string, schemaPath?: string, format?: string) => {
+  if (isProtobufSchemaReference(schemaPath, format)) return parseProtobufSchema(content);
+  if (isYamlSchema(schemaPath, format)) return loadYaml(content);
+  return JSON.parse(content);
+};
+
+const shouldRenderSchema = (schema: any, alwaysRender: boolean) => {
+  if (alwaysRender) return true;
+  return schema?.['x-eventcatalog-render-schema-viewer'] !== undefined ? schema['x-eventcatalog-render-schema-viewer'] : true;
+};
+
+const getCollectionSchemaForViewer = ({
+  collectionSchemas,
+  collection,
+  id,
+  version,
+}: Pick<ResolveSchemaViewerOptions, 'collectionSchemas' | 'collection' | 'id' | 'version'>) => {
+  if (!collection || !version) return undefined;
+
+  const resourceSchemas = collectionSchemas.filter((schema) => {
+    const message = schema.data.message;
+    if (!message) return false;
+    return message.collection === collection && message.id === id && message.version === version;
+  });
+
+  return resourceSchemas.find((schema) => schema.data.default) || resourceSchemas[0];
+};
+
+const getCollectionSchemaPath = (schema?: CollectionSchema) =>
+  schema?.data.filePath || schema?.data.file || schema?.data.source?.path || schema?.data.ref;
+
+export const resolveSchemaViewer = async ({
+  id,
+  version,
+  collection,
+  filePath,
+  schemaViewerProps,
+  collectionSchemas,
+  index,
+}: ResolveSchemaViewerOptions) => {
+  const schemaKey = getSchemaViewerKey(schemaViewerProps);
+  const localSchemaPath = schemaViewerProps.file ? getAbsoluteFilePathForAstroFile(filePath, schemaViewerProps.file) : undefined;
+  const localSchemaExists = localSchemaPath ? existsSync(localSchemaPath) : false;
+
+  let schema;
+  let render = true;
+  let isAvro = false;
+  let isProtobuf = false;
+  let schemaPath = localSchemaPath;
+  let parseError;
+
+  if (localSchemaExists && localSchemaPath) {
+    isAvro = isAvroSchema(localSchemaPath);
+    isProtobuf = isProtobufSchema(localSchemaPath);
+    const content = await readFile(localSchemaPath, 'utf-8');
+    try {
+      schema = parseSchemaContent(content, localSchemaPath);
+      render = shouldRenderSchema(schema, isAvro || isProtobuf);
+    } catch (error) {
+      parseError = error instanceof Error ? error.message : 'Unknown parsing error';
+    }
+  } else if (!schemaViewerProps.file) {
+    const collectionSchema = getCollectionSchemaForViewer({ collectionSchemas, collection, id, version });
+    const content = collectionSchema?.data.content;
+    schemaPath = getCollectionSchemaPath(collectionSchema);
+
+    if (content) {
+      try {
+        isAvro = isAvroSchemaReference(schemaPath, collectionSchema?.data.format);
+        isProtobuf = isProtobufSchemaReference(schemaPath, collectionSchema?.data.format);
+        schema = parseSchemaContent(content, schemaPath, collectionSchema?.data.format);
+        render = shouldRenderSchema(schema, isAvro || isProtobuf);
+      } catch (error) {
+        parseError = error instanceof Error ? error.message : 'Unknown parsing error';
+      }
+    }
+  }
+
+  return {
+    id: schemaViewerProps.id || id,
+    exists: schema !== undefined,
+    schema,
+    schemaPath,
+    schemaKey,
+    isAvroSchema: isAvro,
+    isProtobufSchema: isProtobuf,
+    parseError,
+    ...schemaViewerProps,
+    render,
+    index,
+  };
+};
diff --git a/eventcatalog/src/components/MDX/Steps/Step.astro b/packages/core/eventcatalog/src/components/MDX/Steps/Step.astro
similarity index 87%
rename from eventcatalog/src/components/MDX/Steps/Step.astro
rename to packages/core/eventcatalog/src/components/MDX/Steps/Step.astro
index 122d566bd..573c64248 100644
--- a/eventcatalog/src/components/MDX/Steps/Step.astro
+++ b/packages/core/eventcatalog/src/components/MDX/Steps/Step.astro
@@ -9,7 +9,7 @@ const { title } = Astro.props;
     </span>
     <h3 class="font-semibold text-lg ml-0">{title}</h3>
   </div>
-  <p class="text-gray-500 text-sm ml-4"><slot /></p>
+  <p class="text-[rgb(var(--ec-page-text-muted))] text-sm ml-4"><slot /></p>
 </li>
 
 <script>
@@ -26,7 +26,7 @@ const { title } = Astro.props;
 
 <style is:global>
   .step a {
-    color: #4b5563;
+    color: rgb(var(--ec-page-text-muted));
     text-decoration: underline;
     &:hover {
       color: #b977f9;
diff --git a/eventcatalog/src/components/MDX/Steps/Steps.astro b/packages/core/eventcatalog/src/components/MDX/Steps/Steps.astro
similarity index 80%
rename from eventcatalog/src/components/MDX/Steps/Steps.astro
rename to packages/core/eventcatalog/src/components/MDX/Steps/Steps.astro
index f46566a2d..e93ade9cb 100644
--- a/eventcatalog/src/components/MDX/Steps/Steps.astro
+++ b/packages/core/eventcatalog/src/components/MDX/Steps/Steps.astro
@@ -19,9 +19,9 @@ function splitByLi(html: string) {
 const data = splitByLi(html);
 ---
 
-<div class="bg-white text-gray-800 py-10 pb-0 font-sans not-prose">
-  {title && <h2 class="text-2xl font-bold text-gray-800 mb-6">{title}</h2>}
-  <ol class="relative border-l border-gray-200 ml-3">
+<div class="bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text))] py-10 pb-0 font-sans not-prose">
+  {title && <h2 class="text-2xl font-bold text-[rgb(var(--ec-page-text))] mb-6">{title}</h2>}
+  <ol class="relative border-l border-[rgb(var(--ec-page-border))] ml-3">
     {data.map((item: any) => <Fragment set:html={item} />)}
   </ol>
 </div>
diff --git a/packages/core/eventcatalog/src/components/MDX/SystemContextMap/SystemContextMapPortal.tsx b/packages/core/eventcatalog/src/components/MDX/SystemContextMap/SystemContextMapPortal.tsx
new file mode 100644
index 000000000..879715d0a
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/SystemContextMap/SystemContextMapPortal.tsx
@@ -0,0 +1,22 @@
+/**
+ * Placeholder div the global System Context Map graph is portaled into.
+ *
+ * Mirrors NodeGraphPortal, but uses a fixed `system-context-map-portal` id so the
+ * homepage (and any other page) can embed the global system context map without an
+ * id/version. The matching <NodeGraph collection="system-context-map" /> renders the
+ * graph into this portal.
+ */
+const SystemContextMapPortal = (props: any) => {
+  return (
+    <div
+      className="not-prose my-6 mb-12 w-full relative border! border-[rgb(var(--ec-page-border))]! rounded-md overflow-hidden"
+      id="system-context-map-portal"
+      style={{
+        height: props.height ? `${props.height}em` : '36em',
+        maxHeight: props.maxHeight ? `${props.maxHeight}em` : '36em',
+      }}
+    />
+  );
+};
+
+export default SystemContextMapPortal;
diff --git a/eventcatalog/src/components/MDX/Tabs/TabItem.astro b/packages/core/eventcatalog/src/components/MDX/Tabs/TabItem.astro
similarity index 100%
rename from eventcatalog/src/components/MDX/Tabs/TabItem.astro
rename to packages/core/eventcatalog/src/components/MDX/Tabs/TabItem.astro
diff --git a/eventcatalog/src/components/MDX/Tabs/Tabs.astro b/packages/core/eventcatalog/src/components/MDX/Tabs/Tabs.astro
similarity index 78%
rename from eventcatalog/src/components/MDX/Tabs/Tabs.astro
rename to packages/core/eventcatalog/src/components/MDX/Tabs/Tabs.astro
index 71c4b8a55..041b51353 100644
--- a/eventcatalog/src/components/MDX/Tabs/Tabs.astro
+++ b/packages/core/eventcatalog/src/components/MDX/Tabs/Tabs.astro
@@ -32,8 +32,8 @@ const tabItems: TabItem[] = await Promise.all(
 const tabsId = Math.random().toString(36).substring(2, 9);
 ---
 
-<div class="bg-white text-gray-800 pb-10 not-prose" data-tabs-container={tabsId}>
-  {title && <h2 class="text-2xl font-bold text-gray-800 mb-6">{title}</h2>}
+<div class="bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text))] pb-10 not-prose" data-tabs-container={tabsId}>
+  {title && <h2 class="text-2xl font-bold text-[rgb(var(--ec-page-text))] mb-6">{title}</h2>}
 
   {/* Tab List */}
   <div class="">
@@ -41,7 +41,7 @@ const tabsId = Math.random().toString(36).substring(2, 9);
       {
         tabItems.map((item) => (
           <button
-            class="whitespace-nowrap py-4 px-1 border-b-2 px-6 font-bold text-sm border-transparent text-gray-500 hover:text-gray-700 hover:border-gray-300 hover:bg-gray-100 focus:outline-none"
+            class="whitespace-nowrap py-4 px-1 border-b-2 px-6 font-bold text-sm border-transparent text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] hover:border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-content-hover))] focus:outline-hidden tab-button"
             data-tab={item.id}
             aria-selected="false"
           >
@@ -70,22 +70,19 @@ const tabsId = Math.random().toString(36).substring(2, 9);
     const panels: NodeListOf<HTMLElement> = container.querySelectorAll('[data-tab-content]');
 
     // Show first tab by default
-    tabs[0]?.classList.add('text-purple-600', 'border-purple-600');
-    tabs[0]?.classList.remove('text-gray-500', 'border-transparent');
+    tabs[0]?.classList.add('tab-active');
     panels[0]?.classList.remove('hidden');
 
     tabs.forEach((tab: HTMLButtonElement) => {
       tab.addEventListener('click', () => {
         // Remove active states
         tabs.forEach((t: HTMLButtonElement) => {
-          t.classList.remove('text-purple-600', 'border-purple-600');
-          t.classList.add('text-gray-500', 'border-transparent');
+          t.classList.remove('tab-active');
         });
         panels.forEach((p: HTMLElement) => p.classList.add('hidden'));
 
         // Set active states
-        tab.classList.remove('text-gray-500', 'border-transparent');
-        tab.classList.add('text-purple-600', 'border-purple-600');
+        tab.classList.add('tab-active');
 
         // Show corresponding panel
         const tabId = tab.getAttribute('data-tab');
@@ -103,3 +100,10 @@ const tabsId = Math.random().toString(36).substring(2, 9);
     });
   });
 </script>
+
+<style is:global>
+  .tab-button.tab-active {
+    color: rgb(var(--ec-accent));
+    border-color: rgb(var(--ec-accent));
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/components/MDX/Tiles/Tile.astro b/packages/core/eventcatalog/src/components/MDX/Tiles/Tile.astro
new file mode 100644
index 000000000..3ce6d4c2c
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/Tiles/Tile.astro
@@ -0,0 +1,73 @@
+---
+import type { ComponentType } from 'react';
+import * as Icons from '@heroicons/react/24/solid';
+import { buildUrl } from '@utils/url-builder';
+
+interface Props {
+  href: string;
+  icon: keyof typeof Icons;
+  iconColor?: string;
+  title: string;
+  openWindow?: boolean;
+  description: string;
+}
+
+const { href, icon, title, description, openWindow, iconColor = 'text-primary' } = Astro.props;
+
+const IconComponent: ComponentType<{ className?: string }> | undefined = Icons[icon];
+
+function startsWithProtocol(str: string) {
+  // Regular expression to match common protocols (http, https, ftp, ws, etc.)
+  const regex = /^[a-zA-Z][a-zA-Z\d+\-.]*:\/\//;
+  return regex.test(str);
+}
+---
+
+<div class="group">
+  <!-- Card with just the icon -->
+  <a
+    href={startsWithProtocol(href) ? href : buildUrl(href)}
+    target={openWindow ? '_blank' : '_self'}
+    class="tile-card block relative bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-xl h-48 transition-all duration-300 ease-out hover:border-[rgb(var(--ec-accent)/0.5)] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:ring-offset-2 overflow-hidden"
+  >
+    <!-- Squared paper grid spans the full card -->
+    <div class="tile-grid absolute inset-0"></div>
+
+    <!-- Icon centered in card -->
+    <div class="relative h-full flex items-center justify-center p-8">
+      {IconComponent && <IconComponent className="tile-icon relative w-16 h-16 stroke-1" />}
+    </div>
+  </a>
+
+  <!-- Title and description outside card -->
+  <div class="mt-4 space-y-0">
+    <h2 class="text-[rgb(var(--ec-page-text))] text-lg font-semibold">
+      {title}
+    </h2>
+    <p class="text-[rgb(var(--ec-page-text-muted))] text-sm leading-relaxed">
+      {description}
+    </p>
+  </div>
+</div>
+
+<style>
+  .tile-card:hover {
+    box-shadow:
+      0 10px 15px -3px rgb(var(--ec-accent) / 0.1),
+      0 4px 6px -4px rgb(var(--ec-accent) / 0.1);
+  }
+
+  .tile-grid {
+    background-image:
+      linear-gradient(rgb(var(--ec-accent) / 0.1) 1px, transparent 1px),
+      linear-gradient(90deg, rgb(var(--ec-accent) / 0.1) 1px, transparent 1px);
+    background-size: 28px 28px;
+    /* Soft edge fade — full-width grid that softens just at the borders */
+    -webkit-mask-image: radial-gradient(ellipse at center, black 60%, transparent 100%);
+    mask-image: radial-gradient(ellipse at center, black 60%, transparent 100%);
+  }
+
+  .tile-icon {
+    color: rgb(var(--ec-accent));
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/components/MDX/Tiles/Tiles.astro b/packages/core/eventcatalog/src/components/MDX/Tiles/Tiles.astro
new file mode 100644
index 000000000..51204152f
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/Tiles/Tiles.astro
@@ -0,0 +1,10 @@
+---
+const { title, columns = 2 } = Astro.props;
+---
+
+<section class="not-prose my-8">
+  {title && <h2 class="text-2xl font-bold text-[rgb(var(--ec-page-text))] mb-6">{title}</h2>}
+  <div class={`grid grid-cols-1 md:grid-cols-${columns} gap-6 w-full not-prose`}>
+    <slot />
+  </div>
+</section>
diff --git a/packages/core/eventcatalog/src/components/MDX/Visibility.tsx b/packages/core/eventcatalog/src/components/MDX/Visibility.tsx
new file mode 100644
index 000000000..9a7813262
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/Visibility.tsx
@@ -0,0 +1,12 @@
+type VisibilityProps = {
+  for: 'agents' | 'humans';
+  children?: any;
+};
+
+const Visibility = ({ for: audience, children }: VisibilityProps) => {
+  if (audience !== 'humans') return null;
+
+  return <>{children}</>;
+};
+
+export default Visibility;
diff --git a/packages/core/eventcatalog/src/components/MDX/components.tsx b/packages/core/eventcatalog/src/components/MDX/components.tsx
new file mode 100644
index 000000000..d012f43c2
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/MDX/components.tsx
@@ -0,0 +1,96 @@
+// React components
+import Schema from '@components/MDX/Schema.astro';
+import File from '@components/MDX/File';
+import Accordion from '@components/MDX/Accordion/Accordion.astro';
+import AccordionGroup from '@components/MDX/Accordion/AccordionGroup.astro';
+import Flow from '@components/MDX/Flow/Flow.astro';
+import EntityMap from '@components/MDX/EntityMap/EntityMap.astro';
+import Tiles from '@components/MDX/Tiles/Tiles.astro';
+import Tile from '@components/MDX/Tiles/Tile.astro';
+import Steps from '@components/MDX/Steps/Steps.astro';
+import Step from '@components/MDX/Steps/Step.astro';
+import Admonition from '@components/MDX/Admonition';
+import Prompt from '@components/MDX/Prompt/Prompt.astro';
+import OpenAPI from '@components/MDX/OpenAPI/OpenAPI.astro';
+import AsyncAPI from '@components/MDX/AsyncAPI/AsyncAPI.astro';
+import ChannelInformation from '@components/MDX/ChannelInformation/ChannelInformation';
+import Attachments from '@components/MDX/Attachments.astro';
+import AgentTools from '@components/MDX/AgentTools/AgentTools.astro';
+import MessageTable from '@components/MDX/MessageTable/MessageTable.astro';
+import ADRTable from '@components/MDX/ADRTable/ADRTable.astro';
+import ResourceGroupTable from '@components/MDX/ResourceGroupTable/ResourceGroupTable.astro';
+import EntityPropertiesTable from '@components/MDX/EntityPropertiesTable/EntityPropertiesTable.astro';
+import Tabs from '@components/MDX/Tabs/Tabs.astro';
+import TabItem from '@components/MDX/Tabs/TabItem.astro';
+import ResourceLink from '@components/MDX/ResourceLink/ResourceLink.astro';
+import ResourceRef from '@components/MDX/ResourceRef/ResourceRef.astro';
+import Link from '@components/MDX/Link/Link.astro';
+import Miro from '@components/MDX/Miro/Miro.astro';
+import Lucid from '@components/MDX/Lucid/Lucid.astro';
+import DrawIO from '@components/MDX/DrawIO/DrawIO.astro';
+import FigJam from '@components/MDX/FigJam/FigJam.astro';
+import IcePanel from '@components/MDX/IcePanel/IcePanel.astro';
+import Design from '@components/MDX/Design/Design.astro';
+import MermaidFileLoader from '@components/MDX/MermaidFileLoader/MermaidFileLoader.astro';
+import LikeC4View from '@components/MDX/LikeC4View/LikeC4View.astro';
+//  Portals: required for server/client components
+import NodeGraphPortal from '@components/MDX/NodeGraph/NodeGraphPortal';
+import ContextDiagramPortal from '@components/MDX/ContextDiagram/ContextDiagramPortal';
+import SystemContextMapPortal from '@components/MDX/SystemContextMap/SystemContextMapPortal';
+import SchemaViewerPortal from '@components/MDX/SchemaViewer/SchemaViewerPortal';
+import { jsx } from 'astro/jsx-runtime';
+import RemoteSchema from '@components/MDX/RemoteSchema.astro';
+import Visibility from '@components/MDX/Visibility';
+
+const getEntityMapCollection = (props: any, mdxProp: any) => {
+  const collection = mdxProp.collection ?? props.collection;
+  return collection === 'domains' || collection === 'services' ? collection : undefined;
+};
+
+const components = (props: any) => {
+  return {
+    Attachments: (mdxProp: any) => jsx(Attachments, { ...props, ...mdxProp }),
+    Accordion,
+    AccordionGroup,
+    Admonition,
+    AgentTools: (mdxProp: any) => jsx(AgentTools, { ...props, ...mdxProp }),
+    AsyncAPI,
+    ChannelInformation: (mdxProp: any) => ChannelInformation({ ...props.data, ...mdxProp }),
+    Design: (mdxProp: any) => jsx(Design, { ...props, ...mdxProp }),
+    File: (mdxProp: any) => File({ ...props, ...mdxProp }),
+    RemoteSchema,
+    Flow,
+    Link: (mdxProp: any) => jsx(Link, { ...props, ...mdxProp }),
+    MessageTable: (mdxProp: any) => jsx(MessageTable, { ...props, ...mdxProp }),
+    ADRTable: (mdxProp: any) => jsx(ADRTable, { ...props, ...mdxProp }),
+    EntityPropertiesTable: (mdxProp: any) => jsx(EntityPropertiesTable, { ...props, ...mdxProp }),
+    NodeGraph: (mdxProp: any) => jsx(NodeGraphPortal, { ...props.data, ...mdxProp, props, mdxProp }),
+    ComponentDiagram: (mdxProp: any) => jsx(NodeGraphPortal, { ...props.data, ...mdxProp, props, mdxProp }),
+    ContextDiagram: (mdxProp: any) => jsx(ContextDiagramPortal, { ...props.data, ...mdxProp, props, mdxProp }),
+    SystemContextMap: (mdxProp: any) => jsx(SystemContextMapPortal, { ...mdxProp }),
+    EntityMap: (mdxProp: any) => jsx(EntityMap, { ...props, ...mdxProp, collection: getEntityMapCollection(props, mdxProp) }),
+    OpenAPI,
+    Prompt: (mdxProp: any) => jsx(Prompt, { ...props, ...mdxProp }),
+    ResourceGroupTable: (mdxProp: any) => jsx(ResourceGroupTable, { ...props, ...mdxProp }),
+    ResourceLink: (mdxProp: any) => jsx(ResourceLink, { ...props, ...mdxProp }),
+    ResourceRef: (mdxProp: any) => jsx(ResourceRef, { ...props, ...mdxProp }),
+    Schema: (mdxProp: any) => jsx(Schema, { ...props, ...mdxProp }),
+    SchemaViewer: (mdxProp: any) => SchemaViewerPortal({ ...props.data, ...mdxProp }),
+    Step,
+    Steps,
+    TabItem,
+    Tabs,
+    Tile,
+    Tiles,
+    Visibility,
+    Miro: (mdxProp: any) => jsx(Miro, { ...props, ...mdxProp }),
+    Lucid: (mdxProp: any) => jsx(Lucid, { ...props, ...mdxProp }),
+    DrawIO: (mdxProp: any) => jsx(DrawIO, { ...props, ...mdxProp }),
+    FigJam: (mdxProp: any) => jsx(FigJam, { ...props, ...mdxProp }),
+    IcePanel: (mdxProp: any) => jsx(IcePanel, { ...props, ...mdxProp }),
+    MermaidFileLoader: (mdxProp: any) => jsx(MermaidFileLoader, { ...props, ...mdxProp }),
+    LikeC4View: (mdxProp: any) => jsx(LikeC4View, { ...props, ...mdxProp }),
+  };
+};
+
+export default components;
diff --git a/eventcatalog/src/components/MDX/page-components.tsx b/packages/core/eventcatalog/src/components/MDX/page-components.tsx
similarity index 100%
rename from eventcatalog/src/components/MDX/page-components.tsx
rename to packages/core/eventcatalog/src/components/MDX/page-components.tsx
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/ApiAccessSection.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/ApiAccessSection.tsx
new file mode 100644
index 000000000..de3a81947
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/ApiAccessSection.tsx
@@ -0,0 +1,144 @@
+import { ChevronUpIcon, ChevronDownIcon, ClipboardDocumentIcon, CheckIcon } from '@heroicons/react/24/outline';
+import { CommandLineIcon, LockClosedIcon } from '@heroicons/react/24/solid';
+import type { SchemaItem } from './types';
+
+interface ApiAccessSectionProps {
+  message: SchemaItem;
+  isExpanded: boolean;
+  onToggle: () => void;
+  onCopy: (content: string, id: string) => void;
+  copiedId: string | null;
+  apiAccessEnabled?: boolean;
+}
+
+export default function ApiAccessSection({
+  message,
+  isExpanded,
+  onToggle,
+  onCopy,
+  copiedId,
+  apiAccessEnabled = false,
+}: ApiAccessSectionProps) {
+  // Generate API path based on collection type
+  let apiPath = '';
+  if (message.collection === 'services') {
+    const specType = message.specType || 'openapi';
+    apiPath = `/api/schemas/services/${message.data.id}/${message.data.version}/${specType}`;
+  } else {
+    apiPath = `/api/schemas/${message.collection}/${message.data.id}/${message.data.version}`;
+  }
+
+  const fullUrl = typeof window !== 'undefined' ? `${window.location.origin}${apiPath}` : apiPath;
+  const curlCommand = `curl ${fullUrl}`;
+  const isCopied = copiedId === `${message.data.id}-api`;
+
+  return (
+    <div className="flex-shrink-0 border-b border-[rgb(var(--ec-page-border))]">
+      <button
+        onClick={onToggle}
+        className="w-full flex items-center justify-between px-4 py-2 text-left hover:bg-[rgb(var(--ec-page-bg)/0.5)] transition-colors"
+      >
+        <div className="flex items-center gap-2">
+          <CommandLineIcon className="h-3.5 w-3.5 text-[rgb(var(--ec-icon-color))]" />
+          <span className="text-xs font-medium text-[rgb(var(--ec-page-text))]">API</span>
+          {!apiAccessEnabled && (
+            <span className="inline-flex items-center gap-1 rounded bg-[rgb(var(--ec-accent-subtle))] px-1.5 py-0.5 text-[10px] font-medium text-[rgb(var(--ec-accent-text))] border border-[rgb(var(--ec-accent)/0.2)]">
+              <LockClosedIcon className="h-2.5 w-2.5" />
+              Scale
+            </span>
+          )}
+        </div>
+        {isExpanded ? (
+          <ChevronUpIcon className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))]" />
+        ) : (
+          <ChevronDownIcon className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))]" />
+        )}
+      </button>
+
+      {isExpanded && (
+        <div className="px-4 pb-3">
+          {apiAccessEnabled ? (
+            <div className="space-y-2">
+              {/* Endpoint */}
+              <div className="flex items-center gap-2 bg-gray-900 rounded-md px-3 py-2">
+                <span className="text-[10px] font-semibold text-emerald-400 uppercase tracking-wide">GET</span>
+                <code className="flex-1 text-[11px] text-gray-300 font-mono truncate">{apiPath}</code>
+                <button
+                  onClick={() => onCopy(fullUrl, `${message.data.id}-api`)}
+                  className={`flex-shrink-0 p-1 rounded transition-colors ${
+                    isCopied ? 'text-emerald-400' : 'text-gray-500 hover:text-gray-300'
+                  }`}
+                  title="Copy URL"
+                >
+                  {isCopied ? <CheckIcon className="h-3.5 w-3.5" /> : <ClipboardDocumentIcon className="h-3.5 w-3.5" />}
+                </button>
+              </div>
+
+              {/* Quick copy buttons */}
+              <div className="flex items-center gap-2">
+                <button
+                  onClick={() => onCopy(curlCommand, `${message.data.id}-curl`)}
+                  className={`inline-flex items-center gap-1.5 px-2 py-1 text-[10px] font-medium rounded border transition-colors ${
+                    copiedId === `${message.data.id}-curl`
+                      ? 'bg-emerald-50 text-emerald-600 border-emerald-200'
+                      : 'text-[rgb(var(--ec-page-text-muted))] border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-input-bg))] hover:text-[rgb(var(--ec-page-text))]'
+                  }`}
+                >
+                  {copiedId === `${message.data.id}-curl` ? (
+                    <>
+                      <CheckIcon className="h-3 w-3" />
+                      Copied
+                    </>
+                  ) : (
+                    <>
+                      <ClipboardDocumentIcon className="h-3 w-3" />
+                      Copy cURL
+                    </>
+                  )}
+                </button>
+                <button
+                  onClick={() => onCopy(fullUrl, `${message.data.id}-url`)}
+                  className={`inline-flex items-center gap-1.5 px-2 py-1 text-[10px] font-medium rounded border transition-colors ${
+                    copiedId === `${message.data.id}-url`
+                      ? 'bg-emerald-50 text-emerald-600 border-emerald-200'
+                      : 'text-[rgb(var(--ec-page-text-muted))] border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-input-bg))] hover:text-[rgb(var(--ec-page-text))]'
+                  }`}
+                >
+                  {copiedId === `${message.data.id}-url` ? (
+                    <>
+                      <CheckIcon className="h-3 w-3" />
+                      Copied
+                    </>
+                  ) : (
+                    <>
+                      <ClipboardDocumentIcon className="h-3 w-3" />
+                      Copy URL
+                    </>
+                  )}
+                </button>
+              </div>
+            </div>
+          ) : (
+            <div className="flex items-center justify-between gap-3 bg-[rgb(var(--ec-accent-subtle))] border border-[rgb(var(--ec-accent)/0.2)] rounded-md px-3 py-2.5">
+              <div className="flex-1 min-w-0">
+                <p className="text-xs font-medium text-[rgb(var(--ec-page-text))]">Access schemas via API</p>
+                <p className="text-[10px] text-[rgb(var(--ec-page-text-muted))] mt-0.5">CI/CD, automation & integrations</p>
+              </div>
+              <a
+                href="https://eventcatalog.cloud"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="flex-shrink-0 inline-flex items-center gap-1 px-2.5 py-1.5 text-[11px] font-medium text-white bg-[rgb(var(--ec-accent))] rounded-md hover:bg-[rgb(var(--ec-accent-hover))] transition-colors"
+              >
+                Try Scale
+                <svg xmlns="http://www.w3.org/2000/svg" className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+                </svg>
+              </a>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/ApiContentViewer.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/ApiContentViewer.tsx
new file mode 100644
index 000000000..4059e6909
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/ApiContentViewer.tsx
@@ -0,0 +1,242 @@
+import { ClipboardDocumentIcon, CheckIcon, GlobeAltIcon, DocumentTextIcon } from '@heroicons/react/24/outline';
+import { LockClosedIcon } from '@heroicons/react/24/solid';
+import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
+import { oneDark } from 'react-syntax-highlighter/dist/cjs/styles/prism';
+import { oneLight } from 'react-syntax-highlighter/dist/cjs/styles/prism';
+import { getLanguageForHighlight, getSchemaTypeLabel } from './utils';
+import { useDarkMode } from './useDarkMode';
+import type { SchemaItem } from './types';
+
+interface ApiContentViewerProps {
+  message: SchemaItem;
+  onCopy: (content: string, id: string) => void;
+  copiedId: string | null;
+  apiAccessEnabled?: boolean;
+}
+
+export default function ApiContentViewer({ message, onCopy, copiedId, apiAccessEnabled = false }: ApiContentViewerProps) {
+  const isDarkMode = useDarkMode();
+  const dividerColor = isDarkMode ? 'rgb(var(--ec-page-text-muted) / 0.13)' : 'rgb(var(--ec-page-border))';
+  const boxBorderColor = isDarkMode ? 'rgb(var(--ec-page-text-muted) / 0.17)' : 'rgb(var(--ec-page-border))';
+  const insetDividerColor = isDarkMode ? 'rgb(var(--ec-page-text-muted) / 0.11)' : 'rgb(var(--ec-page-border) / 0.8)';
+  const headingClass = 'text-sm font-semibold text-[rgb(var(--ec-page-text))]';
+  const labelClass = 'text-sm text-[rgb(var(--ec-page-text-muted))]';
+  const valueClass = 'text-sm text-[rgb(var(--ec-page-text-muted))]';
+
+  let apiPath = '';
+  if (message.collection === 'services') {
+    const specType = message.specType || 'openapi';
+    apiPath = `/api/schemas/services/${message.data.id}/${message.data.version}/${specType}`;
+  } else {
+    apiPath = `/api/schemas/${message.collection}/${message.data.id}/${message.data.version}`;
+  }
+
+  const fullUrl = typeof window !== 'undefined' ? `${window.location.origin}${apiPath}` : apiPath;
+  const exampleResponse = message.schemaContent || '{}';
+  const schemaTypeLabel = getSchemaTypeLabel(message.schemaExtension);
+  const lineCount = exampleResponse.split('\n').length;
+  const byteSize = new TextEncoder().encode(exampleResponse).length;
+
+  if (!apiAccessEnabled) {
+    return (
+      <div className="flex h-full items-center justify-center p-8">
+        <div className="max-w-md text-center">
+          <div className="mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-2xl border border-[rgb(var(--ec-accent)/0.3)] bg-[rgb(var(--ec-accent-subtle))]">
+            <LockClosedIcon className="h-8 w-8 text-[rgb(var(--ec-accent))]" />
+          </div>
+          <h3 className="mb-2 text-lg font-semibold text-[rgb(var(--ec-page-text))]">API Access</h3>
+          <p className="mb-6 text-sm text-[rgb(var(--ec-page-text-muted))]">
+            Access your schemas programmatically via REST API. Perfect for CI/CD pipelines, automation, and integrations with your
+            development workflow.
+          </p>
+          <a
+            href="https://eventcatalog.cloud"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center gap-2 rounded-lg bg-[rgb(var(--ec-accent))] px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-[rgb(var(--ec-accent-hover))]"
+          >
+            Upgrade to Scale
+            <svg xmlns="http://www.w3.org/2000/svg" className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+            </svg>
+          </a>
+          <p className="mt-3 text-xs text-[rgb(var(--ec-page-text-muted))]">Start your 14-day free trial</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="h-full overflow-auto pr-1">
+      <div className="space-y-4 pb-3">
+        <section className="overflow-hidden rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg)/0.66)]">
+          <div className="flex items-start justify-between gap-4 px-4 py-4">
+            <div className="min-w-0">
+              <div className="flex items-center gap-2">
+                <div className="flex h-6 w-6 items-center justify-center rounded-md bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent))]">
+                  <GlobeAltIcon className="h-3.5 w-3.5" />
+                </div>
+                <h3 className={headingClass}>HTTP Endpoint</h3>
+              </div>
+              <p className={`mt-2 ${labelClass}`}>
+                Use this endpoint to interact with the{' '}
+                <span className="text-[rgb(var(--ec-page-text))]">{message.data.name}</span>.
+              </p>
+            </div>
+            <CopyButton
+              label="Copy"
+              isCopied={copiedId === `${message.data.id}-url`}
+              onClick={() => onCopy(fullUrl, `${message.data.id}-url`)}
+              borderColor={boxBorderColor}
+              variant="ghost"
+            />
+          </div>
+
+          <div className="px-4 pb-4">
+            <div
+              className="flex items-center gap-2 rounded-lg border bg-[rgb(var(--ec-content-hover)/0.45)] p-2"
+              style={{ borderColor: boxBorderColor }}
+            >
+              <span className="rounded-md bg-emerald-500/15 px-3 py-2 text-xs font-bold uppercase tracking-wide text-emerald-400">
+                GET
+              </span>
+              <code className="min-w-0 flex-1 truncate text-[13px] text-[rgb(var(--ec-page-text-muted))]">{apiPath}</code>
+            </div>
+
+            <div className="mt-4 pt-4">
+              <div className="mb-2 flex items-center gap-3">
+                <span className={labelClass}>Full URL</span>
+                <div className="h-px flex-1" style={{ backgroundColor: insetDividerColor }} />
+              </div>
+              <div className="flex items-center gap-4">
+                <code className="min-w-0 flex-1 break-all text-[13px] leading-relaxed text-[rgb(var(--ec-page-text-muted))]">
+                  {fullUrl}
+                </code>
+                <CopyButton
+                  label="Copy"
+                  isCopied={copiedId === `${message.data.id}-full-url`}
+                  onClick={() => onCopy(fullUrl, `${message.data.id}-full-url`)}
+                  borderColor={boxBorderColor}
+                />
+              </div>
+            </div>
+          </div>
+        </section>
+
+        <section className="overflow-hidden rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg)/0.66)]">
+          <div className="px-4 py-4">
+            <h3 className={headingClass}>Response</h3>
+          </div>
+          <div className="border-t" style={{ borderColor: dividerColor }}>
+            <div className="flex items-center justify-between gap-4 px-4 py-3">
+              <span className={labelClass}>Content-Type</span>
+              <code
+                className="rounded-md border bg-[rgb(var(--ec-content-hover)/0.45)] px-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))]"
+                style={{ borderColor: boxBorderColor }}
+              >
+                application/json
+              </code>
+            </div>
+            <div className="flex items-center justify-between gap-4 border-t px-4 py-3" style={{ borderColor: dividerColor }}>
+              <span className={labelClass}>Returns</span>
+              <span className={valueClass}>Raw schema content</span>
+            </div>
+          </div>
+        </section>
+
+        <section className="overflow-hidden rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg)/0.66)]">
+          <div className="flex items-center justify-between gap-4 px-4 py-4">
+            <div className="flex items-center gap-2">
+              <div
+                className="flex h-6 w-6 items-center justify-center rounded-md border bg-[rgb(var(--ec-content-hover)/0.45)] text-[rgb(var(--ec-page-text-muted))]"
+                style={{ borderColor: boxBorderColor }}
+              >
+                <DocumentTextIcon className="h-3.5 w-3.5" />
+              </div>
+              <h3 className={headingClass}>Example Response</h3>
+            </div>
+            <CopyButton
+              label="Copy"
+              isCopied={copiedId === `${message.data.id}-response`}
+              onClick={() => onCopy(exampleResponse, `${message.data.id}-response`)}
+              borderColor={boxBorderColor}
+              variant="ghost"
+            />
+          </div>
+
+          <div className="border-t" style={{ borderColor: dividerColor }}>
+            <SyntaxHighlighter
+              language={getLanguageForHighlight(message.schemaExtension)}
+              style={isDarkMode ? oneDark : oneLight}
+              customStyle={{
+                margin: 0,
+                padding: '1rem 1.25rem',
+                borderRadius: 0,
+                fontSize: '0.8125rem',
+                lineHeight: '1.625',
+                background: 'transparent',
+              }}
+              showLineNumbers={true}
+              wrapLines={true}
+              wrapLongLines={true}
+            >
+              {exampleResponse}
+            </SyntaxHighlighter>
+          </div>
+
+          <div className="flex items-center justify-between gap-4 border-t px-4 py-3" style={{ borderColor: dividerColor }}>
+            <div className="inline-flex items-center gap-2 rounded-md bg-emerald-500/10 px-3 py-1.5 text-xs font-medium text-emerald-400">
+              <span className="h-2 w-2 rounded-full bg-emerald-400" />
+              Valid {schemaTypeLabel}
+            </div>
+            <div className="flex items-center gap-4 text-xs text-[rgb(var(--ec-page-text-muted))]">
+              <span>{lineCount} lines</span>
+              <span>{formatBytes(byteSize)}</span>
+            </div>
+          </div>
+        </section>
+      </div>
+    </div>
+  );
+}
+
+function CopyButton({
+  label,
+  isCopied,
+  onClick,
+  borderColor,
+  variant = 'outline',
+}: {
+  label: string;
+  isCopied: boolean;
+  onClick: () => void;
+  borderColor: string;
+  variant?: 'outline' | 'ghost';
+}) {
+  const classes =
+    variant === 'ghost'
+      ? 'inline-flex items-center gap-2 rounded-md px-1 py-1 text-xs font-medium transition-colors'
+      : 'inline-flex items-center gap-2 rounded-md border px-3 py-2 text-xs font-medium transition-colors';
+
+  return (
+    <button
+      onClick={onClick}
+      style={variant === 'outline' ? { borderColor } : undefined}
+      className={`${classes} ${
+        isCopied
+          ? 'text-emerald-400'
+          : 'text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-content-hover)/0.45)] hover:text-[rgb(var(--ec-page-text))]'
+      }`}
+    >
+      {isCopied ? <CheckIcon className="h-3.5 w-3.5" /> : <ClipboardDocumentIcon className="h-3.5 w-3.5" />}
+      {isCopied ? 'Copied' : label}
+    </button>
+  );
+}
+
+function formatBytes(bytes: number) {
+  if (bytes < 1024) return `${bytes} B`;
+  const kb = bytes / 1024;
+  if (kb < 1024) return `${kb.toFixed(1)} KB`;
+  return `${(kb / 1024).toFixed(1)} MB`;
+}
diff --git a/eventcatalog/src/components/SchemaExplorer/AvroSchemaViewer.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/AvroSchemaViewer.tsx
similarity index 77%
rename from eventcatalog/src/components/SchemaExplorer/AvroSchemaViewer.tsx
rename to packages/core/eventcatalog/src/components/SchemaExplorer/AvroSchemaViewer.tsx
index 54db2a354..d5cf0ca20 100644
--- a/eventcatalog/src/components/SchemaExplorer/AvroSchemaViewer.tsx
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/AvroSchemaViewer.tsx
@@ -52,17 +52,31 @@ function formatAvroType(type: any): string {
 
 // Check if a type has nested fields
 function hasNestedFields(type: any): boolean {
-  // Check if it's a direct record type
+  if (!type) return false;
   if (typeof type === 'object' && !Array.isArray(type)) {
-    return type.type === 'record' && type.fields && type.fields.length > 0;
+    if (type.type === 'record') return !!(type.fields && type.fields.length > 0);
+    if (type.type === 'array') return hasNestedFields(type.items);
+    if (type.type === 'map') return hasNestedFields(type.values);
   }
+  if (Array.isArray(type)) return type.some((t) => hasNestedFields(t));
+  return false;
+}
 
-  // Check if it's a union type that contains a record
+// Deep extractor for Records or Enums
+function getNestedType(type: any, target: 'record' | 'enum'): any {
+  if (!type) return null;
+  if (typeof type === 'object' && !Array.isArray(type)) {
+    if (type.type === target) return type;
+    if (type.type === 'array') return getNestedType(type.items, target);
+    if (type.type === 'map') return getNestedType(type.values, target);
+  }
   if (Array.isArray(type)) {
-    return type.some((t) => typeof t === 'object' && !Array.isArray(t) && t.type === 'record' && t.fields && t.fields.length > 0);
+    for (const t of type) {
+      const result = getNestedType(t, target);
+      if (result) return result;
+    }
   }
-
-  return false;
+  return null;
 }
 
 // Check if a field is required (not optional)
@@ -91,14 +105,6 @@ function isFieldRequired(field: any): boolean {
   return true;
 }
 
-// Helper function to get the record type from a union if it exists
-function getRecordFromUnion(type: any): any {
-  if (Array.isArray(type)) {
-    return type.find((t) => typeof t === 'object' && !Array.isArray(t) && t.type === 'record');
-  }
-  return null;
-}
-
 // AvroField component - displays a single field with nested support
 const AvroField = ({ field, level, expand, showRequired }: AvroFieldProps) => {
   const [isExpanded, setIsExpanded] = useState(expand);
@@ -106,22 +112,23 @@ const AvroField = ({ field, level, expand, showRequired }: AvroFieldProps) => {
   const indentClass = `pl-${level * 4}`;
   const isRequired = showRequired ? isFieldRequired(field) : undefined;
 
-  // Get the record type, either directly or from within a union
-  const recordType = typeof field.type === 'object' && field.type.type === 'record' ? field.type : getRecordFromUnion(field.type);
+  // Get the record and enum types by resolving deep nesting
+  const recordType = getNestedType(field.type, 'record');
+  const enumType = getNestedType(field.type, 'enum');
 
   useEffect(() => {
     setIsExpanded(expand);
   }, [expand]);
 
   return (
-    <div className={`avro-field-container mb-2 border-l border-gray-200 ${indentClass}`}>
+    <div className={`avro-field-container mb-2 border-l border-[rgb(var(--ec-page-border))] ${indentClass}`}>
       <div className="flex space-x-2">
         {/* Collapse/Expand button */}
         <div className="flex-shrink-0 w-4 pt-0.5">
           {hasNested ? (
             <button
               onClick={() => setIsExpanded(!isExpanded)}
-              className="avro-field-toggle text-gray-500 hover:text-gray-700 w-4 text-center"
+              className="avro-field-toggle text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] w-4 text-center"
               aria-expanded={isExpanded}
             >
               <span className="font-mono text-xs">{isExpanded ? '▼' : '▶'}</span>
@@ -132,19 +139,21 @@ const AvroField = ({ field, level, expand, showRequired }: AvroFieldProps) => {
         {/* Field details */}
         <div className="flex-grow min-w-0">
           <div className="flex flex-wrap items-baseline gap-x-1.5 gap-y-1">
-            <span className="avro-field-name font-semibold text-gray-800 text-sm">{field.name}</span>
-            <span className="text-purple-600 font-mono text-xs">{formatAvroType(field.type)}</span>
-            {showRequired && isRequired && <span className="text-red-600 text-xs ml-auto flex-shrink-0">required</span>}
+            <span className="avro-field-name font-semibold text-[rgb(var(--ec-page-text))] text-sm">{field.name}</span>
+            <span className="text-[rgb(var(--ec-accent))] font-mono text-xs">{formatAvroType(field.type)}</span>
+            {showRequired && isRequired && (
+              <span className="text-red-600 dark:text-red-400 text-xs ml-auto flex-shrink-0">required</span>
+            )}
           </div>
 
-          {field.doc && <p className="text-gray-600 text-xs mt-1">{field.doc}</p>}
+          {field.doc && <p className="text-[rgb(var(--ec-page-text-muted))] text-xs mt-1">{field.doc}</p>}
 
           {/* Show enum values if present */}
-          {field.type?.type === 'enum' && field.type.symbols && (
-            <div className="text-xs text-gray-500 mt-1">
+          {enumType && enumType.symbols && (
+            <div className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-1">
               Values:{' '}
-              {field.type.symbols.map((s: string) => (
-                <code key={s} className="bg-gray-100 px-1 rounded mx-0.5">
+              {enumType.symbols.map((s: string) => (
+                <code key={s} className="bg-[rgb(var(--ec-content-hover))] px-1 rounded mx-0.5 text-[rgb(var(--ec-page-text))]">
                   {s}
                 </code>
               ))}
@@ -303,7 +312,7 @@ export default function AvroSchemaViewer({
 
   if (!schema || schema.type !== 'record') {
     return (
-      <div className="flex items-center justify-center p-8 text-gray-500">
+      <div className="flex items-center justify-center p-8 text-[rgb(var(--ec-page-text-muted))]">
         <p className="text-sm">Invalid Avro schema format</p>
       </div>
     );
@@ -318,12 +327,12 @@ export default function AvroSchemaViewer({
 
   return (
     <div
-      className={`${heightClass} ${overflowClass} flex flex-col bg-white border border-gray-100 rounded-md shadow-sm`}
+      className={`${heightClass} ${overflowClass} flex flex-col bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-md shadow-xs`}
       style={containerStyle}
     >
       {/* Toolbar */}
       {searchBool && (
-        <div className="flex-shrink-0 bg-white pt-4 px-4 pb-3 border-b border-gray-100 shadow-sm">
+        <div className="flex-shrink-0 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] pt-4 px-4 pb-3 border-b border-[rgb(var(--ec-page-border))] shadow-xs">
           <div className="flex flex-col sm:flex-row gap-3">
             <div className="flex-1 relative">
               <input
@@ -332,7 +341,7 @@ export default function AvroSchemaViewer({
                 value={searchQuery}
                 onChange={(e) => setSearchQuery(e.target.value)}
                 placeholder="Search fields..."
-                className="w-full px-3 py-1.5 pr-20 text-sm border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+                className="w-full px-3 py-1.5 pr-20 text-sm border border-[rgb(var(--ec-input-border))] bg-[rgb(var(--ec-input-bg))] text-[rgb(var(--ec-input-text))] placeholder:text-[rgb(var(--ec-input-placeholder))] rounded-md focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:border-transparent"
                 onKeyDown={(e) => {
                   if (e.key === 'Enter') {
                     e.preventDefault();
@@ -348,7 +357,7 @@ export default function AvroSchemaViewer({
                 <button
                   onClick={handlePrevMatch}
                   disabled={currentMatches.length === 0 || currentMatchIndex <= 0}
-                  className="p-1 text-gray-400 hover:text-gray-600 disabled:opacity-30 disabled:cursor-not-allowed"
+                  className="p-1 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] disabled:opacity-30 disabled:cursor-not-allowed"
                   title="Previous match"
                 >
                   <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
@@ -358,7 +367,7 @@ export default function AvroSchemaViewer({
                 <button
                   onClick={handleNextMatch}
                   disabled={currentMatches.length === 0 || currentMatchIndex >= currentMatches.length - 1}
-                  className="p-1 text-gray-400 hover:text-gray-600 disabled:opacity-30 disabled:cursor-not-allowed"
+                  className="p-1 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] disabled:opacity-30 disabled:cursor-not-allowed"
                   title="Next match"
                 >
                   <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
@@ -371,7 +380,7 @@ export default function AvroSchemaViewer({
               {onOpenFullscreen && (
                 <button
                   onClick={onOpenFullscreen}
-                  className="px-3 py-1.5 text-xs font-medium text-gray-700 bg-gray-100 rounded-md hover:bg-gray-200 focus:outline-none focus:ring-2 focus:ring-gray-500"
+                  className="px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-content-hover))] rounded-md hover:bg-[rgb(var(--ec-content-active))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
                   title="Open in fullscreen"
                 >
                   <svg
@@ -392,23 +401,23 @@ export default function AvroSchemaViewer({
               )}
               <button
                 onClick={handleExpandAll}
-                className="px-3 py-1.5 text-xs font-medium text-gray-700 bg-gray-100 rounded-md hover:bg-gray-200 focus:outline-none focus:ring-2 focus:ring-gray-500"
+                className="px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-content-hover))] rounded-md hover:bg-[rgb(var(--ec-content-active))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
               >
                 Expand All
               </button>
               <button
                 onClick={handleCollapseAll}
-                className="px-3 py-1.5 text-xs font-medium text-gray-700 bg-gray-100 rounded-md hover:bg-gray-200 focus:outline-none focus:ring-2 focus:ring-gray-500"
+                className="px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-content-hover))] rounded-md hover:bg-[rgb(var(--ec-content-active))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
               >
                 Collapse All
               </button>
-              <div className="text-xs text-gray-500">
+              <div className="text-xs text-[rgb(var(--ec-page-text-muted))]">
                 {totalFields} {totalFields === 1 ? 'field' : 'fields'}
               </div>
             </div>
           </div>
           {searchQuery && (
-            <div className="mt-2 text-xs text-gray-600">
+            <div className="mt-2 text-xs text-[rgb(var(--ec-page-text-muted))]">
               {currentMatches.length > 0
                 ? `${currentMatchIndex + 1} of ${currentMatches.length} ${currentMatches.length === 1 ? 'match' : 'matches'}`
                 : 'No fields found'}
@@ -420,11 +429,13 @@ export default function AvroSchemaViewer({
       {/* Schema info */}
       <div className="px-4 pt-4">
         <div className="flex items-baseline gap-2 mb-2">
-          <span className="text-sm font-medium text-gray-600">Record:</span>
-          <span className="font-mono text-sm text-blue-600">{schema.name}</span>
-          {schema.namespace && <span className="font-mono text-xs text-gray-500">({schema.namespace})</span>}
+          <span className="text-sm font-medium text-[rgb(var(--ec-page-text-muted))]">Record:</span>
+          <span className="font-mono text-sm text-blue-600 dark:text-blue-400">{schema.name}</span>
+          {schema.namespace && (
+            <span className="font-mono text-xs text-[rgb(var(--ec-page-text-muted))]">({schema.namespace})</span>
+          )}
         </div>
-        {schema.doc && <p className="text-gray-600 text-xs mb-4">{schema.doc}</p>}
+        {schema.doc && <p className="text-[rgb(var(--ec-page-text-muted))] text-xs mb-4">{schema.doc}</p>}
       </div>
 
       {/* Fields */}
@@ -434,14 +445,14 @@ export default function AvroSchemaViewer({
             <AvroField key={field.name} field={field} level={0} expand={expandAll} showRequired={showRequiredBool} />
           ))
         ) : (
-          <div className="text-center py-8 text-gray-400">
+          <div className="text-center py-8 text-[rgb(var(--ec-icon-color))]">
             <p className="text-sm">No fields defined</p>
           </div>
         )}
 
         {searchQuery && currentMatches.length === 0 && (
           <div className="text-center py-8">
-            <div className="text-gray-400 text-sm">
+            <div className="text-[rgb(var(--ec-icon-color))] text-sm">
               <svg className="mx-auto h-12 w-12 mb-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                 <path
                   strokeLinecap="round"
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/DiffViewer.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/DiffViewer.tsx
new file mode 100644
index 000000000..e9bd98b71
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/DiffViewer.tsx
@@ -0,0 +1,211 @@
+import { ArrowsPointingOutIcon } from '@heroicons/react/24/outline';
+import type { VersionDiff } from './types';
+import { useDarkMode } from './useDarkMode';
+
+// Dark mode overrides for diff2html - scoped under .diff-dark-mode
+const DIFF_DARK_STYLES = `
+.diff-dark-mode .d2h-wrapper {
+  color: #e5e7eb;
+}
+.diff-dark-mode .d2h-file-header {
+  background-color: rgba(255,255,255,0.05);
+  border-bottom-color: rgba(255,255,255,0.1);
+}
+.diff-dark-mode .d2h-file-header .d2h-file-name {
+  color: #e5e7eb;
+}
+.diff-dark-mode .d2h-diff-table {
+  border-color: rgba(255,255,255,0.1);
+}
+.diff-dark-mode .d2h-code-side-linenumber,
+.diff-dark-mode .d2h-code-linenumber {
+  background-color: rgba(255,255,255,0.03);
+  border-color: rgba(255,255,255,0.08);
+  color: #6b7280;
+}
+.diff-dark-mode .d2h-code-line,
+.diff-dark-mode .d2h-code-side-line {
+  background-color: transparent;
+  border-color: rgba(255,255,255,0.06);
+  color: #d1d5db;
+}
+.diff-dark-mode .d2h-code-line-ctn {
+  color: #d1d5db;
+}
+/* Deletion lines */
+.diff-dark-mode .d2h-del {
+  background-color: rgba(239,68,68,0.1);
+  border-color: rgba(239,68,68,0.15);
+}
+.diff-dark-mode .d2h-del .d2h-code-side-linenumber,
+.diff-dark-mode .d2h-del .d2h-code-linenumber {
+  background-color: rgba(239,68,68,0.15);
+  border-color: rgba(239,68,68,0.15);
+  color: #f87171;
+}
+.diff-dark-mode .d2h-del .d2h-code-line-ctn {
+  color: #fca5a5;
+}
+.diff-dark-mode del {
+  background-color: rgba(239,68,68,0.25);
+  color: #fca5a5;
+  text-decoration: none;
+}
+/* Addition lines */
+.diff-dark-mode .d2h-ins {
+  background-color: rgba(34,197,94,0.1);
+  border-color: rgba(34,197,94,0.15);
+}
+.diff-dark-mode .d2h-ins .d2h-code-side-linenumber,
+.diff-dark-mode .d2h-ins .d2h-code-linenumber {
+  background-color: rgba(34,197,94,0.15);
+  border-color: rgba(34,197,94,0.15);
+  color: #4ade80;
+}
+.diff-dark-mode .d2h-ins .d2h-code-line-ctn {
+  color: #bbf7d0;
+}
+.diff-dark-mode ins {
+  background-color: rgba(34,197,94,0.25);
+  color: #bbf7d0;
+  text-decoration: none;
+}
+/* Info/context header */
+.diff-dark-mode .d2h-info {
+  background-color: rgba(59,130,246,0.08);
+  border-color: rgba(59,130,246,0.15);
+  color: #93c5fd;
+}
+/* File diff border */
+.diff-dark-mode .d2h-file-diff {
+  border-color: rgba(255,255,255,0.1);
+}
+.diff-dark-mode .d2h-file-side-diff {
+  border-color: rgba(255,255,255,0.1);
+}
+/* Tag styles */
+.diff-dark-mode .d2h-tag {
+  background-color: rgba(59,130,246,0.15);
+  border-color: rgba(59,130,246,0.3);
+  color: #93c5fd;
+}
+/* Empty placeholder lines */
+.diff-dark-mode .d2h-code-side-emptyplaceholder,
+.diff-dark-mode .d2h-emptyplaceholder {
+  background-color: rgba(255,255,255,0.02);
+  border-color: rgba(255,255,255,0.06);
+}
+/* File wrapper border */
+.diff-dark-mode .d2h-file-wrapper {
+  border-color: rgba(255,255,255,0.1);
+  border-radius: 0.5rem;
+  overflow: hidden;
+}
+.diff-dark-mode .d2h-files-diff {
+  border-color: rgba(255,255,255,0.1);
+}
+`;
+
+interface DiffViewerProps {
+  diffs: VersionDiff[];
+  onOpenFullscreen?: () => void;
+  apiAccessEnabled?: boolean;
+}
+
+export default function DiffViewer({ diffs, onOpenFullscreen, apiAccessEnabled = false }: DiffViewerProps) {
+  const isDark = useDarkMode();
+
+  if (diffs.length === 0) return null;
+
+  return (
+    <div className="h-full overflow-auto p-2">
+      {isDark && <style dangerouslySetInnerHTML={{ __html: DIFF_DARK_STYLES }} />}
+      <div className="mb-5 flex items-start justify-between">
+        <div className="flex-1">
+          <h3 className="text-base font-semibold text-[rgb(var(--ec-page-text))] mb-1">Version Comparison</h3>
+          <p className="text-sm text-[rgb(var(--ec-page-text-muted))]">
+            {apiAccessEnabled
+              ? `${diffs.length} selected comparison${diffs.length !== 1 ? 's' : ''}`
+              : 'Compare schema versions side-by-side'}
+          </p>
+        </div>
+        {onOpenFullscreen && apiAccessEnabled && (
+          <button
+            onClick={onOpenFullscreen}
+            className="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+            title="Open in fullscreen"
+          >
+            <ArrowsPointingOutIcon className="h-4 w-4" />
+            Fullscreen
+          </button>
+        )}
+      </div>
+      {apiAccessEnabled ? (
+        <div className={`space-y-6 ${isDark ? 'diff-dark-mode' : ''}`}>
+          {diffs.map((diff) => (
+            <div
+              key={`${diff.fromVersion}-${diff.toVersion}`}
+              className="border border-[rgb(var(--ec-page-border))] rounded-lg overflow-hidden"
+            >
+              <div className="bg-[rgb(var(--ec-content-hover))] border-b border-[rgb(var(--ec-page-border))] px-4 py-2.5">
+                <div className="flex items-center justify-between">
+                  <div className="text-sm">
+                    <span className="font-semibold text-[rgb(var(--ec-page-text))]">v{diff.fromVersion}</span>
+                    <span className="text-[rgb(var(--ec-page-text-muted))] mx-2">&rarr;</span>
+                    <span className="font-semibold text-[rgb(var(--ec-page-text))]">v{diff.toVersion}</span>
+                  </div>
+                  <span className="text-xs text-[rgb(var(--ec-page-text-muted))]">Selected comparison</span>
+                </div>
+              </div>
+              <div className="relative">
+                <div dangerouslySetInnerHTML={{ __html: diff.diffHtml }} />
+              </div>
+            </div>
+          ))}
+        </div>
+      ) : (
+        <div className="bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-accent)/0.3)] rounded-lg p-8">
+          <div className="flex flex-col items-center text-center max-w-md mx-auto">
+            <div className="flex-shrink-0 mb-4">
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                className="h-12 w-12 text-[rgb(var(--ec-accent))]"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={1.5}
+                  d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
+                />
+              </svg>
+            </div>
+            <h4 className="text-lg font-semibold text-[rgb(var(--ec-page-text))] mb-2">Upgrade to Scale</h4>
+            <p className="text-sm text-[rgb(var(--ec-page-text-muted))] mb-6 leading-relaxed">
+              Compare schema versions side-by-side with visual diffs. Track breaking changes, see exactly what changed between
+              versions, and maintain better schema governance.
+            </p>
+            <a
+              href="https://eventcatalog.cloud"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex items-center gap-2 px-4 py-2 text-sm font-medium text-white bg-[rgb(var(--ec-accent))] rounded-lg hover:opacity-90 transition-colors"
+            >
+              Start 14-day free trial
+              <svg xmlns="http://www.w3.org/2000/svg" className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"
+                />
+              </svg>
+            </a>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/ExamplesViewer.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/ExamplesViewer.tsx
new file mode 100644
index 000000000..d9c6ccfdd
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/ExamplesViewer.tsx
@@ -0,0 +1,147 @@
+import { useState, useEffect } from 'react';
+import { ClipboardDocumentIcon } from '@heroicons/react/24/outline';
+import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
+import { oneDark } from 'react-syntax-highlighter/dist/cjs/styles/prism';
+import { oneLight } from 'react-syntax-highlighter/dist/cjs/styles/prism';
+import { getLanguageForHighlight } from './utils';
+import { copyToClipboard } from './utils';
+import type { MessageExample } from './types';
+import { useDarkMode } from './useDarkMode';
+
+interface ExamplesViewerProps {
+  examples: MessageExample[];
+}
+
+export default function ExamplesViewer({ examples }: ExamplesViewerProps) {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const [copiedId, setCopiedId] = useState<string | null>(null);
+  const isDarkMode = useDarkMode();
+
+  useEffect(() => {
+    setSelectedIndex(0);
+  }, [examples]);
+
+  if (examples.length === 0) {
+    return (
+      <div className="flex items-center justify-center h-full text-[rgb(var(--ec-page-text-muted))]">
+        <p className="text-sm">No examples available</p>
+      </div>
+    );
+  }
+
+  const selected = examples[selectedIndex];
+  const lang = getLanguageForHighlight(selected.extension);
+
+  const handleCopy = async (content: string, id: string) => {
+    const success = await copyToClipboard(content);
+    if (success) {
+      setCopiedId(id);
+      setTimeout(() => setCopiedId(null), 2000);
+    }
+  };
+
+  return (
+    <div className="h-full flex gap-4 overflow-hidden">
+      {/* Left: example list */}
+      <div className="flex-shrink-0 w-56 overflow-y-auto space-y-1">
+        {examples.map((ex, idx) => (
+          <button
+            key={ex.fileName}
+            onClick={() => setSelectedIndex(idx)}
+            className={`w-full text-left px-3 py-2.5 rounded-lg transition-colors ${
+              idx === selectedIndex
+                ? 'bg-[rgb(var(--ec-accent-subtle))] border border-[rgb(var(--ec-accent)/0.3)]'
+                : 'hover:bg-[rgb(var(--ec-content-hover))] border border-transparent'
+            }`}
+          >
+            <span
+              className={`block text-xs font-medium truncate ${
+                idx === selectedIndex ? 'text-[rgb(var(--ec-page-text))]' : 'text-[rgb(var(--ec-page-text-muted))]'
+              }`}
+            >
+              {ex.title}
+            </span>
+            {ex.summary && (
+              <span className="block text-[11px] text-[rgb(var(--ec-page-text-muted))] mt-0.5 line-clamp-2 leading-relaxed">
+                {ex.summary}
+              </span>
+            )}
+          </button>
+        ))}
+      </div>
+
+      {/* Right: code + usage */}
+      <div className="flex-1 flex flex-col min-w-0 overflow-auto">
+        {/* Code window */}
+        <div className="flex flex-col rounded-lg border border-[rgb(var(--ec-page-border))] overflow-hidden bg-[rgb(var(--ec-dropdown-bg)/0.66)]">
+          {/* Window title bar */}
+          <div className="flex items-center justify-between border-b border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover)/0.45)] px-4 py-2.5">
+            <div className="flex items-center gap-3">
+              <div className="flex items-center gap-1.5">
+                <div className="w-3 h-3 rounded-full bg-[#FF5F56]" />
+                <div className="w-3 h-3 rounded-full bg-[#FFBD2E]" />
+                <div className="w-3 h-3 rounded-full bg-[#27C93F]" />
+              </div>
+              <span className="text-xs font-mono text-[rgb(var(--ec-page-text-muted))]">{selected.fileName}</span>
+            </div>
+
+            <button
+              onClick={() => handleCopy(selected.content, selected.fileName)}
+              className="inline-flex items-center gap-1 px-2 py-1 text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-page-bg)/0.5)] hover:text-[rgb(var(--ec-page-text))] rounded transition-colors"
+              title="Copy code"
+            >
+              <ClipboardDocumentIcon className="h-3 w-3" />
+              {copiedId === selected.fileName ? 'Copied!' : 'Copy'}
+            </button>
+          </div>
+
+          {/* Code content */}
+          <div className="overflow-auto">
+            <SyntaxHighlighter
+              language={lang}
+              style={isDarkMode ? oneDark : oneLight}
+              customStyle={{
+                margin: 0,
+                padding: '1rem 1.25rem',
+                borderRadius: 0,
+                fontSize: '0.8125rem',
+                lineHeight: '1.625',
+                overflow: 'auto',
+                background: 'transparent',
+              }}
+              showLineNumbers={true}
+              wrapLines={true}
+              wrapLongLines={true}
+            >
+              {selected.content}
+            </SyntaxHighlighter>
+          </div>
+        </div>
+
+        {/* Usage section */}
+        {selected.usage && (
+          <div className="flex-shrink-0 mt-3">
+            <div className="rounded-lg border border-[rgb(var(--ec-page-border))] overflow-hidden bg-[rgb(var(--ec-dropdown-bg)/0.66)]">
+              <div className="flex items-center justify-between border-b border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover)/0.45)] px-4 py-2">
+                <span className="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Usage</span>
+                <button
+                  onClick={() => handleCopy(selected.usage!, `usage-${selected.fileName}`)}
+                  className="inline-flex items-center gap-1 px-2 py-1 text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-page-bg)/0.5)] hover:text-[rgb(var(--ec-page-text))] rounded transition-colors"
+                  title="Copy usage"
+                >
+                  <ClipboardDocumentIcon className="h-3 w-3" />
+                  {copiedId === `usage-${selected.fileName}` ? 'Copied!' : 'Copy'}
+                </button>
+              </div>
+              <div className="overflow-auto max-h-32">
+                <pre className="m-0 px-5 py-3 text-[0.75rem] leading-[1.5] whitespace-pre-wrap break-words text-[rgb(var(--ec-page-text-muted))] bg-transparent font-mono">
+                  <code>{selected.usage}</code>
+                </pre>
+              </div>
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/JSONSchemaViewer.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/JSONSchemaViewer.tsx
new file mode 100644
index 000000000..e2d63582f
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/JSONSchemaViewer.tsx
@@ -0,0 +1,903 @@
+import { useState, useEffect, useRef, useMemo } from 'react';
+
+interface JSONSchemaViewerProps {
+  schema: any;
+  title?: string;
+  maxHeight?: string;
+  expand?: boolean | string;
+  search?: boolean | string;
+  id?: string;
+  onOpenFullscreen?: () => void;
+}
+
+interface SchemaPropertyProps {
+  name: string;
+  details: any;
+  isRequired: boolean;
+  level: number;
+  isListItem?: boolean;
+  expand: boolean;
+}
+
+// JSON Schema allows `type` to be a string or an array of strings (e.g. ["object", "null"]).
+// These helpers normalise both forms so the rest of the viewer can treat type checks uniformly.
+function hasType(type: any, candidate: string): boolean {
+  if (Array.isArray(type)) return type.includes(candidate);
+  return type === candidate;
+}
+
+function formatType(type: any): string {
+  if (Array.isArray(type)) return type.join(' | ');
+  return type ?? '';
+}
+
+// Helper function to count properties recursively
+function countProperties(obj: any): number {
+  if (!obj || typeof obj !== 'object') return 0;
+
+  let count = 0;
+  if (obj.properties) {
+    count += Object.keys(obj.properties).length;
+    Object.values(obj.properties).forEach((prop: any) => {
+      count += countProperties(prop);
+    });
+  }
+  if (obj.items) {
+    count += countProperties(obj.items);
+  }
+  if (obj._isRootArrayItem && obj._rootArraySchema?.items) {
+    // Don't double count
+  }
+  return count;
+}
+
+// Schema processing functions
+function mergeAllOfSchemas(schemaWithProcessor: any): any {
+  const { processSchema: processor, ...schema } = schemaWithProcessor;
+  if (!schema.allOf) return schema;
+
+  const mergedSchema: {
+    type: string;
+    properties: Record<string, any>;
+    required: string[];
+    description?: string;
+    [key: string]: any;
+  } = {
+    type: schema.type || 'object',
+    properties: {},
+    required: [],
+    description: schema.description,
+  };
+
+  // Copy base schema properties first (excluding allOf)
+  Object.keys(schema).forEach((key) => {
+    if (key !== 'allOf' && key !== 'properties' && key !== 'required' && key !== 'description') {
+      mergedSchema[key] = schema[key];
+    }
+  });
+
+  // Copy base properties if they exist
+  if (schema.properties) {
+    mergedSchema.properties = { ...schema.properties };
+  }
+  if (schema.required) {
+    mergedSchema.required = [...schema.required];
+  }
+
+  schema.allOf.forEach((subSchema: any) => {
+    const processedSubSchema = processor ? processor(subSchema) : subSchema;
+
+    if (processedSubSchema.properties) {
+      mergedSchema.properties = {
+        ...mergedSchema.properties,
+        ...processedSubSchema.properties,
+      };
+    }
+    if (processedSubSchema.required) {
+      mergedSchema.required = [...new Set([...mergedSchema.required, ...processedSubSchema.required])];
+    }
+    if (processedSubSchema.description && !mergedSchema.description) {
+      mergedSchema.description = processedSubSchema.description;
+    }
+
+    Object.keys(processedSubSchema).forEach((key) => {
+      if (key !== 'properties' && key !== 'required' && key !== 'description' && key !== 'type') {
+        if (!mergedSchema[key]) {
+          mergedSchema[key] = processedSubSchema[key];
+        }
+      }
+    });
+  });
+
+  return mergedSchema;
+}
+
+function processSchema(schema: any, rootSchema?: any): any {
+  if (!schema) return schema;
+
+  const root = rootSchema || schema;
+
+  // Handle $ref
+  if (schema.$ref) {
+    const refPath = schema.$ref;
+    let resolvedSchema = null;
+    let defName = '';
+
+    // Try draft-7 style first: #/definitions/
+    if (refPath.startsWith('#/definitions/')) {
+      defName = refPath.replace('#/definitions/', '');
+      if (root.definitions && root.definitions[defName]) {
+        resolvedSchema = root.definitions[defName];
+      }
+    }
+    // Try 2020-12 style: #/$defs/
+    else if (refPath.startsWith('#/$defs/')) {
+      defName = refPath.replace('#/$defs/', '');
+      if (root.$defs && root.$defs[defName]) {
+        resolvedSchema = root.$defs[defName];
+      }
+    }
+    // Try other common patterns
+    else if (refPath.startsWith('#/components/schemas/')) {
+      defName = refPath.replace('#/components/schemas/', '');
+      if (root.components && root.components.schemas && root.components.schemas[defName]) {
+        resolvedSchema = root.components.schemas[defName];
+      }
+    }
+
+    if (resolvedSchema) {
+      const processedSchema = processSchema(resolvedSchema, root);
+      return {
+        ...processedSchema,
+        _refPath: refPath,
+        _refName: defName,
+        _originalRef: schema.$ref,
+      };
+    }
+
+    return {
+      type: 'string',
+      description: `Reference to ${refPath} (definition not found in root schema)`,
+      title: defName || refPath.split('/').pop(),
+      _refPath: refPath,
+      _refName: defName,
+      _refNotFound: true,
+    };
+  }
+
+  if (schema.allOf) {
+    return mergeAllOfSchemas({ ...schema, processSchema: (s: any) => processSchema(s, root) });
+  }
+
+  if (schema.oneOf || schema.anyOf) {
+    const variantsArray = schema.oneOf || schema.anyOf;
+    const variantType = schema.oneOf ? 'oneOf' : 'anyOf';
+
+    const processedVariants = variantsArray.map((variant: any, index: number) => {
+      const processedVariant = processSchema(variant, root);
+      return {
+        title: processedVariant.title || variant.title || processedVariant.$id || `Option ${index + 1}`,
+        description: processedVariant.description || variant.description,
+        required: processedVariant.required || variant.required || [],
+        properties: processedVariant.properties || {},
+        type: processedVariant.type || variant.type || 'object',
+        ...processedVariant,
+      };
+    });
+
+    return {
+      ...schema,
+      type: schema.type || 'object',
+      properties: schema.properties
+        ? Object.fromEntries(
+            Object.entries(schema.properties).map(([key, prop]: [string, any]) => [key, processSchema(prop, root)])
+          )
+        : {},
+      variants: processedVariants,
+      variantType,
+    };
+  }
+
+  // Process nested schemas in properties
+  if (schema.properties) {
+    const processedProperties: Record<string, any> = {};
+    Object.entries(schema.properties).forEach(([key, prop]: [string, any]) => {
+      processedProperties[key] = processSchema(prop, root);
+    });
+    schema = { ...schema, properties: processedProperties };
+  }
+
+  // Process array items
+  if (hasType(schema.type, 'array') && schema.items) {
+    schema = { ...schema, items: processSchema(schema.items, root) };
+  }
+
+  return schema;
+}
+
+// NestedVariantSelector component for handling variants within array items
+const NestedVariantSelector = ({
+  variants,
+  variantType,
+  level,
+  expand,
+}: {
+  variants: any[];
+  variantType?: string;
+  level: number;
+  expand: boolean;
+}) => {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const selectedVariant = variants[selectedIndex];
+
+  return (
+    <div className="mt-2">
+      <div className="p-2 bg-[rgb(var(--ec-accent-subtle,var(--ec-content-hover)))] border border-[rgb(var(--ec-page-border))] rounded-md">
+        <div className="flex flex-col sm:flex-row sm:items-center gap-2">
+          <span className="text-xs font-medium text-[rgb(var(--ec-page-text))]">
+            {variantType === 'anyOf' ? 'Any of' : 'One of'} {variants.length} options:
+          </span>
+          <select
+            value={selectedIndex}
+            onChange={(e) => setSelectedIndex(parseInt(e.target.value))}
+            className="form-select text-xs border-[rgb(var(--ec-input-border))] bg-[rgb(var(--ec-input-bg))] text-[rgb(var(--ec-input-text))] rounded-md shadow-xs focus:border-[rgb(var(--ec-accent))] focus:ring focus:ring-[rgb(var(--ec-accent)/0.2)] py-1"
+          >
+            {variants.map((variant: any, index: number) => (
+              <option key={index} value={index}>
+                {variant.title}
+              </option>
+            ))}
+          </select>
+        </div>
+        {selectedVariant?.description && (
+          <p className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-1">{selectedVariant.description}</p>
+        )}
+      </div>
+      {selectedVariant?.properties && (
+        <div className="mt-2">
+          {Object.entries(selectedVariant.properties).map(([propName, propDetails]: [string, any]) => (
+            <SchemaProperty
+              key={`${selectedIndex}-${propName}`}
+              name={propName}
+              details={propDetails}
+              isRequired={selectedVariant.required?.includes(propName) ?? false}
+              level={level}
+              expand={expand}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+// SchemaProperty component
+const SchemaProperty = ({ name, details, isRequired, level, isListItem = false, expand }: SchemaPropertyProps) => {
+  const [isExpanded, setIsExpanded] = useState(expand);
+  const [selectedVariantIndex, setSelectedVariantIndex] = useState(0);
+  const contentId = useRef(`prop-${name}-${level}-${Math.random().toString(36).substring(2, 7)}`).current;
+
+  useEffect(() => {
+    setIsExpanded(expand);
+  }, [expand]);
+
+  const hasNestedProperties = hasType(details.type, 'object') && details.properties && Object.keys(details.properties).length > 0;
+  const hasArrayItems = hasType(details.type, 'array') && details.items;
+  const hasArrayItemProperties =
+    hasArrayItems &&
+    ((hasType(details.items.type, 'object') && details.items.properties) ||
+      details.items.allOf ||
+      details.items.oneOf ||
+      details.items.anyOf ||
+      details.items.variants ||
+      details.items.$ref);
+  const hasVariants = details.variants && details.variants.length > 0;
+  const isCollapsible = hasNestedProperties || hasArrayItemProperties || hasVariants;
+
+  const indentationClass = `pl-${level * 3}`;
+
+  return (
+    <div className={`property-container mb-1.5 border-l border-[rgb(var(--ec-page-border))] relative ${indentationClass}`}>
+      <div className="flex items-start space-x-1.5">
+        {isCollapsible ? (
+          <button
+            type="button"
+            aria-expanded={isExpanded}
+            aria-controls={contentId}
+            onClick={() => setIsExpanded(!isExpanded)}
+            className="property-toggle text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] pt-0.5 focus:outline-hidden w-3 text-center flex-shrink-0"
+          >
+            <span className={`icon-collapsed font-mono text-xs ${isExpanded ? 'hidden' : ''}`}>&gt;</span>
+            <span className={`icon-expanded font-mono text-xs ${!isExpanded ? 'hidden' : ''}`}>v</span>
+          </button>
+        ) : (
+          <div className="w-3 h-4 flex-shrink-0" />
+        )}
+
+        <div className="flex-grow">
+          <div className="flex justify-between items-baseline">
+            <div>
+              <span className="font-semibold text-[rgb(var(--ec-page-text))] text-sm">{name}</span>
+              <span className="ml-1.5 text-[rgb(var(--ec-accent))] font-mono text-xs">
+                {hasVariants ? (details.variantType === 'anyOf' ? 'anyOf' : 'oneOf') : formatType(details.type)}
+                {hasType(details.type, 'array') && details.items?.type ? `[${formatType(details.items.type)}]` : ''}
+                {details.format ? `<${details.format}>` : ''}
+                {details._refPath && (
+                  <span className="text-blue-600 dark:text-blue-400 ml-1">→ {details._refName || details._refPath}</span>
+                )}
+                {details._refNotFound && <span className="text-red-600 dark:text-red-400 ml-1">❌ ref not found</span>}
+                {details.const !== undefined && (
+                  <span>
+                    constant: <code>{details.const}</code>
+                  </span>
+                )}
+              </span>
+            </div>
+            {isRequired && <span className="text-red-600 dark:text-red-400 text-xs ml-3 flex-shrink-0">required</span>}
+          </div>
+
+          {details.description && <p className="text-[rgb(var(--ec-page-text-muted))] text-xs mt-0.5">{details.description}</p>}
+          {details.title && details.title !== details.description && (
+            <p className="text-[rgb(var(--ec-page-text-muted))] text-xs mt-0.5 italic">Title: {details.title}</p>
+          )}
+
+          <div className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-0.5 space-y-0">
+            {details.pattern && (
+              <div>
+                Match pattern:{' '}
+                <code className="bg-[rgb(var(--ec-content-hover))] px-1 rounded text-[rgb(var(--ec-page-text))] font-thin py-0.5">
+                  {details.pattern}
+                </code>
+              </div>
+            )}
+            {details.minimum !== undefined && (
+              <div>
+                Minimum:{' '}
+                <code className="bg-[rgb(var(--ec-content-hover))] px-1 rounded text-[rgb(var(--ec-page-text))] font-thin py-0.5">
+                  {details.minimum}
+                </code>
+              </div>
+            )}
+            {details.maximum !== undefined && (
+              <div>
+                Maximum:{' '}
+                <code className="bg-[rgb(var(--ec-content-hover))] px-1 rounded text-[rgb(var(--ec-page-text))] font-thin py-0.5">
+                  {details.maximum}
+                </code>
+              </div>
+            )}
+            {details.minLength !== undefined && (
+              <div>
+                Min length:{' '}
+                <code className="bg-[rgb(var(--ec-content-hover))] px-1 rounded text-[rgb(var(--ec-page-text))] font-thin py-0.5">
+                  {details.minLength}
+                </code>
+              </div>
+            )}
+            {details.maxLength !== undefined && (
+              <div>
+                Max length:{' '}
+                <code className="bg-[rgb(var(--ec-content-hover))] px-1 rounded text-[rgb(var(--ec-page-text))] font-thin py-0.5">
+                  {details.maxLength}
+                </code>
+              </div>
+            )}
+            {details.enum && (
+              <div>
+                <span className="text-xs inline-block">Allowed values:</span>
+                {details.enum.map((val: any, idx: number) => (
+                  <span key={idx} className="text-xs">
+                    {' '}
+                    <code className="bg-[rgb(var(--ec-content-hover))] px-1 rounded text-[rgb(var(--ec-page-text))] font-thin py-0.5">
+                      {val}
+                    </code>
+                  </span>
+                ))}
+              </div>
+            )}
+          </div>
+
+          {(hasNestedProperties || hasArrayItems || hasVariants) && (
+            <div id={contentId} className={`nested-content mt-1 ${isCollapsible && !isExpanded ? 'hidden' : ''}`}>
+              {hasVariants && (
+                <div className="mt-2 mb-2 p-2 bg-[rgb(var(--ec-accent-subtle,var(--ec-content-hover)))] border border-[rgb(var(--ec-page-border))] rounded-md">
+                  <div className="flex flex-col sm:flex-row sm:items-center gap-2">
+                    <span className="text-xs font-medium text-[rgb(var(--ec-page-text))]">
+                      {details.variantType === 'anyOf' ? 'Any of' : 'One of'} {details.variants.length} options:
+                    </span>
+                    <select
+                      value={selectedVariantIndex}
+                      onChange={(e) => setSelectedVariantIndex(parseInt(e.target.value))}
+                      className="form-select text-xs border-[rgb(var(--ec-input-border))] bg-[rgb(var(--ec-input-bg))] text-[rgb(var(--ec-input-text))] rounded-md shadow-xs focus:border-[rgb(var(--ec-accent))] focus:ring focus:ring-[rgb(var(--ec-accent)/0.2)] py-1"
+                    >
+                      {details.variants.map((variant: any, index: number) => (
+                        <option key={index} value={index}>
+                          {variant.title}
+                        </option>
+                      ))}
+                    </select>
+                  </div>
+                  {details.variants[selectedVariantIndex]?.description && (
+                    <p className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-1">
+                      {details.variants[selectedVariantIndex].description}
+                    </p>
+                  )}
+                </div>
+              )}
+
+              {hasVariants && details.variants[selectedVariantIndex]?.properties && (
+                <div className="mt-1">
+                  {Object.entries(details.variants[selectedVariantIndex].properties).map(
+                    ([nestedName, nestedDetails]: [string, any]) => (
+                      <SchemaProperty
+                        key={`${selectedVariantIndex}-${nestedName}`}
+                        name={nestedName}
+                        details={nestedDetails}
+                        isRequired={details.variants[selectedVariantIndex]?.required?.includes(nestedName) ?? false}
+                        level={level + 1}
+                        expand={expand}
+                      />
+                    )
+                  )}
+                </div>
+              )}
+
+              {hasNestedProperties &&
+                !hasVariants &&
+                details.properties &&
+                Object.entries(details.properties).map(([nestedName, nestedDetails]: [string, any]) => (
+                  <SchemaProperty
+                    key={nestedName}
+                    name={nestedName}
+                    details={nestedDetails}
+                    isRequired={details.required?.includes(nestedName) ?? false}
+                    level={level + 1}
+                    expand={expand}
+                  />
+                ))}
+
+              {hasArrayItemProperties && (
+                <div className="mt-1 border-l border-dashed border-[rgb(var(--ec-page-border))] pl-3 ml-1.5">
+                  <span className="text-xs italic text-[rgb(var(--ec-page-text-muted))] block mb-1">Item Details:</span>
+                  {details.items.properties &&
+                    Object.entries(details.items.properties).map(([itemPropName, itemPropDetails]: [string, any]) => (
+                      <SchemaProperty
+                        key={itemPropName}
+                        name={itemPropName}
+                        details={itemPropDetails}
+                        isRequired={details.items.required?.includes(itemPropName) ?? false}
+                        level={level + 1}
+                        isListItem={true}
+                        expand={expand}
+                      />
+                    ))}
+                  {details.items.variants && details.items.variants.length > 0 && (
+                    <NestedVariantSelector
+                      variants={details.items.variants}
+                      variantType={details.items.variantType}
+                      level={level + 1}
+                      expand={expand}
+                    />
+                  )}
+                  {(details.items.allOf || details.items.oneOf || details.items.anyOf || details.items.$ref) &&
+                    !details.items.properties &&
+                    !details.items.variants && (
+                      <div className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-1">
+                        Complex array item schema detected. The properties should be processed by the parent SchemaViewer.
+                      </div>
+                    )}
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+// Main JSONSchemaViewer component
+export default function JSONSchemaViewer({
+  schema,
+  title,
+  maxHeight,
+  expand = false,
+  search = true,
+  id,
+  onOpenFullscreen,
+}: JSONSchemaViewerProps) {
+  // Convert string props to booleans (MDX passes strings)
+  const expandBool = expand === true || expand === 'true';
+  const searchBool = search !== false && search !== 'false';
+
+  const [searchQuery, setSearchQuery] = useState('');
+  const [expandAll, setExpandAll] = useState(expandBool);
+  const [selectedVariantIndex, setSelectedVariantIndex] = useState(0);
+  const [currentMatches, setCurrentMatches] = useState<HTMLElement[]>([]);
+  const [currentMatchIndex, setCurrentMatchIndex] = useState(-1);
+  const searchInputRef = useRef<HTMLInputElement>(null);
+  const propertiesContainerRef = useRef<HTMLDivElement>(null);
+
+  const processedSchema = useMemo(() => processSchema(schema), [schema]);
+
+  // Handle root-level array schemas
+  const { displaySchema, isRootArray } = useMemo(() => {
+    let display = processedSchema;
+    let isArray = false;
+
+    if (hasType(processedSchema.type, 'array') && processedSchema.items) {
+      isArray = true;
+      if (hasType(processedSchema.items.type, 'object') && processedSchema.items.properties) {
+        display = {
+          ...processedSchema.items,
+          description: processedSchema.description || processedSchema.items.description,
+          _isRootArrayItem: true,
+          _rootArraySchema: processedSchema,
+        };
+      } else if (processedSchema.items.allOf || processedSchema.items.oneOf || processedSchema.items.$ref) {
+        display = {
+          ...processSchema(processedSchema.items),
+          description: processedSchema.description || processedSchema.items.description,
+          _isRootArrayItem: true,
+          _rootArraySchema: processedSchema,
+        };
+      }
+    }
+
+    return { displaySchema: display, isRootArray: isArray };
+  }, [processedSchema]);
+
+  const { description, properties, required = [], variants, variantType } = displaySchema;
+  const totalProperties = useMemo(() => countProperties(displaySchema), [displaySchema]);
+
+  // Search functionality
+  useEffect(() => {
+    if (!propertiesContainerRef.current) return;
+
+    const propertyContainers = propertiesContainerRef.current.querySelectorAll('.property-container');
+    const matches: HTMLElement[] = [];
+
+    if (searchQuery === '') {
+      // Reset search
+      propertyContainers.forEach((container) => {
+        container.classList.remove('search-match', 'search-no-match', 'search-current-match', 'search-dimmed');
+        const nameEl = container.querySelector('.font-semibold');
+        if (nameEl) {
+          nameEl.innerHTML = nameEl.textContent || '';
+        }
+      });
+      setCurrentMatches([]);
+      setCurrentMatchIndex(-1);
+      return;
+    }
+
+    const query = searchQuery.toLowerCase().trim();
+
+    propertyContainers.forEach((container) => {
+      const nameEl = container.querySelector('.font-semibold');
+      if (!nameEl) return;
+
+      const propName = (nameEl.textContent || '').toLowerCase();
+
+      if (propName.includes(query)) {
+        container.classList.add('search-match');
+        container.classList.remove('search-dimmed');
+        matches.push(container as HTMLElement);
+
+        // Highlight the search term
+        const regex = new RegExp(`(${query})`, 'gi');
+        nameEl.innerHTML = (nameEl.textContent || '').replace(regex, '<mark class="bg-yellow-200 rounded px-0.5">$1</mark>');
+
+        // Expand parent containers and remove dimming from them
+        let parent = container.parentElement;
+        while (parent && parent !== propertiesContainerRef.current) {
+          if (parent.classList.contains('nested-content') && parent.classList.contains('hidden')) {
+            const parentPropertyContainer = parent.closest('.property-container');
+            if (parentPropertyContainer) {
+              const toggleBtn = parentPropertyContainer.querySelector('.property-toggle');
+              if (toggleBtn && toggleBtn.getAttribute('aria-expanded') === 'false') {
+                (toggleBtn as HTMLButtonElement).click();
+              }
+            }
+          }
+          // Remove dimming from parent property containers so they're fully visible
+          if (parent.classList.contains('property-container')) {
+            parent.classList.remove('search-dimmed');
+          }
+          parent = parent.parentElement;
+        }
+      } else {
+        container.classList.remove('search-match', 'search-current-match');
+        container.classList.add('search-dimmed');
+        nameEl.innerHTML = nameEl.textContent || '';
+      }
+    });
+
+    setCurrentMatches(matches);
+    if (matches.length > 0) {
+      setCurrentMatchIndex(0);
+      matches[0].scrollIntoView({ behavior: 'smooth', block: 'center' });
+    } else {
+      setCurrentMatchIndex(-1);
+    }
+  }, [searchQuery]);
+
+  // Update match highlighting
+  useEffect(() => {
+    currentMatches.forEach((match, index) => {
+      if (index === currentMatchIndex) {
+        match.classList.add('search-current-match');
+      } else {
+        match.classList.remove('search-current-match');
+      }
+    });
+
+    if (currentMatchIndex >= 0 && currentMatches[currentMatchIndex]) {
+      currentMatches[currentMatchIndex].scrollIntoView({ behavior: 'smooth', block: 'center' });
+    }
+  }, [currentMatchIndex, currentMatches]);
+
+  const handleExpandAll = () => {
+    setExpandAll(true);
+  };
+
+  const handleCollapseAll = () => {
+    setExpandAll(false);
+  };
+
+  const handlePrevMatch = () => {
+    if (currentMatchIndex > 0) {
+      setCurrentMatchIndex(currentMatchIndex - 1);
+    }
+  };
+
+  const handleNextMatch = () => {
+    if (currentMatchIndex < currentMatches.length - 1) {
+      setCurrentMatchIndex(currentMatchIndex + 1);
+    }
+  };
+
+  if (!schema) {
+    return (
+      <div className="flex items-center justify-center h-full text-[rgb(var(--ec-page-text-muted))] p-8">
+        <p className="text-sm">Unable to parse JSON schema</p>
+      </div>
+    );
+  }
+
+  const containerStyle = maxHeight
+    ? {
+        maxHeight: maxHeight.includes('px') ? maxHeight : `${maxHeight}px`,
+        minHeight: '15em',
+      }
+    : {};
+
+  // Use h-full when no maxHeight (SchemaExplorer context), otherwise size based on content (MDX context)
+  const heightClass = maxHeight ? '' : 'h-full';
+  const overflowClass = maxHeight ? 'overflow-hidden' : '';
+
+  return (
+    <div
+      id={id}
+      className={`${heightClass} ${overflowClass} flex flex-col bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-md shadow-xs`}
+      style={containerStyle}
+    >
+      {/* Toolbar */}
+      {searchBool && (
+        <div className="flex-shrink-0 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] pt-4 px-4 mb-4 pb-3 border-b border-[rgb(var(--ec-page-border))] shadow-xs">
+          <div className="flex flex-col sm:flex-row gap-3">
+            <div className="flex-1 relative">
+              <input
+                ref={searchInputRef}
+                type="text"
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                placeholder="Search properties..."
+                className="w-full px-3 py-1.5 pr-20 text-sm border border-[rgb(var(--ec-input-border))] rounded-md bg-[rgb(var(--ec-input-bg))] text-[rgb(var(--ec-input-text))] placeholder:text-[rgb(var(--ec-input-placeholder))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:border-transparent"
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter') {
+                    e.preventDefault();
+                    if (e.shiftKey) {
+                      handlePrevMatch();
+                    } else {
+                      handleNextMatch();
+                    }
+                  }
+                }}
+              />
+              <div className="absolute right-2 top-1/2 transform -translate-y-1/2 flex items-center gap-1">
+                <button
+                  onClick={handlePrevMatch}
+                  disabled={currentMatches.length === 0 || currentMatchIndex <= 0}
+                  className="p-1 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] disabled:opacity-30 disabled:cursor-not-allowed"
+                  title="Previous match"
+                >
+                  <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M15 19l-7-7 7-7" />
+                  </svg>
+                </button>
+                <button
+                  onClick={handleNextMatch}
+                  disabled={currentMatches.length === 0 || currentMatchIndex >= currentMatches.length - 1}
+                  className="p-1 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] disabled:opacity-30 disabled:cursor-not-allowed"
+                  title="Next match"
+                >
+                  <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M9 5l7 7-7 7" />
+                  </svg>
+                </button>
+              </div>
+            </div>
+            <div className="flex items-center gap-2">
+              {onOpenFullscreen && (
+                <button
+                  onClick={onOpenFullscreen}
+                  className="px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-content-hover))] rounded-md hover:bg-[rgb(var(--ec-content-active))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
+                  title="Open in fullscreen"
+                >
+                  <svg
+                    xmlns="http://www.w3.org/2000/svg"
+                    className="h-3.5 w-3.5 inline-block"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M4 8V4m0 0h4M4 4l5 5m11-1V4m0 0h-4m4 0l-5 5M4 16v4m0 0h4m-4 0l5-5m11 5l-5-5m5 5v-4m0 4h-4"
+                    />
+                  </svg>
+                </button>
+              )}
+              <button
+                onClick={handleExpandAll}
+                className="px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-content-hover))] rounded-md hover:bg-[rgb(var(--ec-content-active))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
+              >
+                Expand All
+              </button>
+              <button
+                onClick={handleCollapseAll}
+                className="px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-content-hover))] rounded-md hover:bg-[rgb(var(--ec-content-active))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
+              >
+                Collapse All
+              </button>
+              <div className="text-xs text-[rgb(var(--ec-page-text-muted))]">
+                {totalProperties} {totalProperties === 1 ? 'property' : 'properties'}
+              </div>
+            </div>
+          </div>
+          {searchQuery && (
+            <div className="mt-2 text-xs text-[rgb(var(--ec-page-text-muted))]">
+              {currentMatches.length > 0
+                ? `${currentMatchIndex + 1} of ${currentMatches.length} ${currentMatches.length === 1 ? 'match' : 'matches'}`
+                : 'No properties found'}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Content */}
+      <div className="flex-1 px-4 pb-4 overflow-auto">
+        {isRootArray && (
+          <div className="mb-4 p-3 bg-blue-50 dark:bg-blue-950/50 border border-blue-200 dark:border-blue-800 rounded-md">
+            <div className="flex items-center space-x-2">
+              <span className="text-blue-600 dark:text-blue-400 font-medium text-sm">Array Schema</span>
+              <span className="text-blue-500 dark:text-blue-400 font-mono text-xs">array[object]</span>
+            </div>
+            <p className="text-blue-700 dark:text-blue-300 text-xs mt-1">
+              This schema defines an array of objects. Each item in the array has the properties shown below.
+            </p>
+          </div>
+        )}
+        {description && <p className="text-[rgb(var(--ec-page-text-muted))] text-xs mb-5">{description}</p>}
+
+        {variants && variants.length > 0 && (
+          <div className="mb-4 p-3 bg-[rgb(var(--ec-accent-subtle,var(--ec-content-hover)))] border border-[rgb(var(--ec-page-border))] rounded-md">
+            <div className="flex flex-col sm:flex-row sm:items-center gap-2">
+              <span className="text-sm font-medium text-[rgb(var(--ec-page-text))]">
+                {variantType === 'anyOf' ? 'Any of' : 'One of'} {variants.length} options:
+              </span>
+              <select
+                value={selectedVariantIndex}
+                onChange={(e) => setSelectedVariantIndex(parseInt(e.target.value))}
+                className="form-select text-sm border-[rgb(var(--ec-input-border))] bg-[rgb(var(--ec-input-bg))] text-[rgb(var(--ec-input-text))] rounded-md shadow-xs focus:border-[rgb(var(--ec-accent))] focus:ring focus:ring-[rgb(var(--ec-accent)/0.2)] flex-1 sm:flex-initial"
+              >
+                {variants.map((variant: any, index: number) => (
+                  <option key={index} value={index}>
+                    {variant.title}
+                  </option>
+                ))}
+              </select>
+            </div>
+            {variants[selectedVariantIndex]?.description && (
+              <p className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-2">{variants[selectedVariantIndex].description}</p>
+            )}
+          </div>
+        )}
+
+        {(() => {
+          // Determine which properties to display
+          const propsToDisplay =
+            variants && variants.length > 0 && variants[selectedVariantIndex]?.properties
+              ? { ...properties, ...variants[selectedVariantIndex].properties }
+              : properties;
+          const requiredProps = variants && variants.length > 0 ? variants[selectedVariantIndex]?.required || [] : required;
+
+          if (propsToDisplay && Object.keys(propsToDisplay).length > 0) {
+            return (
+              <div ref={propertiesContainerRef}>
+                {Object.entries(propsToDisplay).map(([name, details]: [string, any]) => (
+                  <SchemaProperty
+                    key={`${selectedVariantIndex}-${name}`}
+                    name={name}
+                    details={details}
+                    isRequired={requiredProps.includes(name)}
+                    level={0}
+                    expand={expandAll}
+                  />
+                ))}
+              </div>
+            );
+          } else if (!isRootArray) {
+            return <p className="text-[rgb(var(--ec-page-text-muted))] text-sm">Schema does not contain any properties.</p>;
+          }
+          return null;
+        })()}
+        {!properties && !variants && isRootArray && (
+          <div className="text-center py-8">
+            <div className="text-[rgb(var(--ec-page-text-muted))] text-sm">
+              <p>
+                This array contains items of type:{' '}
+                <span className="font-mono text-blue-600 dark:text-blue-400">
+                  {processedSchema.items?.type ? formatType(processedSchema.items.type) : 'unknown'}
+                </span>
+              </p>
+              {processedSchema.items?.description && (
+                <p className="text-xs mt-2 text-[rgb(var(--ec-page-text-muted))]">{processedSchema.items.description}</p>
+              )}
+            </div>
+          </div>
+        )}
+
+        {searchQuery && currentMatches.length === 0 && (
+          <div className="text-center py-8">
+            <div className="text-[rgb(var(--ec-page-text-muted))] text-sm">
+              <svg className="mx-auto h-12 w-12 mb-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth="2"
+                  d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+                />
+              </svg>
+              <p>No properties match your search</p>
+              <p className="text-xs mt-1">Try a different search term or clear the search to see all properties</p>
+            </div>
+          </div>
+        )}
+      </div>
+
+      <style>{`
+        .search-dimmed {
+          opacity: 0.4;
+          transition: opacity 0.2s ease;
+        }
+
+        .search-match {
+          opacity: 1;
+          transition: opacity 0.2s ease;
+        }
+
+        .search-current-match {
+          background-color: rgba(59, 130, 246, 0.1);
+          border-left: 3px solid #3b82f6;
+          padding-left: 8px;
+          margin-left: -11px;
+          transition: all 0.2s ease;
+        }
+      `}</style>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/OwnersSection.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/OwnersSection.tsx
new file mode 100644
index 000000000..7f51025a7
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/OwnersSection.tsx
@@ -0,0 +1,74 @@
+import { ChevronUpIcon, ChevronDownIcon } from '@heroicons/react/24/outline';
+import { UserIcon, UserGroupIcon } from '@heroicons/react/20/solid';
+import type { SchemaItem, Owner } from './types';
+
+interface OwnersSectionProps {
+  message: SchemaItem;
+  isExpanded: boolean;
+  onToggle: () => void;
+}
+
+export default function OwnersSection({ message, isExpanded, onToggle }: OwnersSectionProps) {
+  const owners = message.data.owners || [];
+
+  if (owners.length === 0) return null;
+
+  return (
+    <div className="flex-shrink-0 border-b border-[rgb(var(--ec-page-border))]">
+      <button
+        onClick={onToggle}
+        className="w-full flex items-center justify-between px-5 py-2.5 text-left hover:bg-[rgb(var(--ec-content-hover)/0.5)] transition-colors"
+      >
+        <div className="flex items-center gap-2.5">
+          <span className="text-xs font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">Owners</span>
+          {!isExpanded && (
+            <div className="flex items-center -space-x-1">
+              {owners.slice(0, 3).map((owner: Owner, idx: number) => {
+                const OwnerIcon = owner.type === 'users' ? UserIcon : UserGroupIcon;
+                return (
+                  <div
+                    key={`${owner.id}-${idx}`}
+                    className="flex items-center justify-center w-5 h-5 rounded-full bg-[rgb(var(--ec-content-hover))] border-2 border-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] text-[rgb(var(--ec-page-text-muted))]"
+                  >
+                    <OwnerIcon className="h-2.5 w-2.5" />
+                  </div>
+                );
+              })}
+              {owners.length > 3 && (
+                <div className="flex items-center justify-center w-5 h-5 rounded-full bg-[rgb(var(--ec-content-hover))] border-2 border-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] text-[10px] font-medium text-[rgb(var(--ec-page-text-muted))]">
+                  +{owners.length - 3}
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+        <ChevronDownIcon
+          className={`h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))] transition-transform ${isExpanded ? 'rotate-180' : ''}`}
+        />
+      </button>
+
+      {isExpanded && (
+        <div className="px-5 pb-3">
+          <div className="flex flex-wrap gap-2">
+            {owners.map((owner: Owner, idx: number) => {
+              const OwnerIcon = owner.type === 'users' ? UserIcon : UserGroupIcon;
+              return (
+                <a
+                  key={`${owner.id}-${idx}`}
+                  href={owner.href}
+                  className="inline-flex items-center gap-1.5 pl-1.5 pr-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-content-hover))] rounded-full hover:ring-1 hover:ring-[rgb(var(--ec-accent)/0.3)] transition-all"
+                  title={owner.name}
+                >
+                  <div className="flex items-center justify-center w-5 h-5 bg-[rgb(var(--ec-accent))] rounded-full">
+                    <OwnerIcon className="h-3 w-3 text-white" />
+                  </div>
+                  <span>{owner.name}</span>
+                </a>
+              );
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/Pagination.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/Pagination.tsx
new file mode 100644
index 000000000..2f575a07e
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/Pagination.tsx
@@ -0,0 +1,39 @@
+import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline';
+
+interface PaginationProps {
+  currentPage: number;
+  totalPages: number;
+  onPageChange: (page: number) => void;
+}
+
+export default function Pagination({ currentPage, totalPages, onPageChange }: PaginationProps) {
+  if (totalPages <= 1) return null;
+
+  return (
+    <div className="flex-shrink-0 border-t border-[rgb(var(--ec-page-border))] px-5 py-4">
+      <div className="flex items-center justify-center gap-4">
+        <button
+          onClick={() => onPageChange(Math.max(1, currentPage - 1))}
+          disabled={currentPage === 1}
+          className="inline-flex h-9 w-9 items-center justify-center rounded-xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg))] text-[rgb(var(--ec-page-text-muted))] transition-colors hover:text-[rgb(var(--ec-page-text))] disabled:cursor-not-allowed disabled:opacity-30"
+          aria-label="Previous page"
+        >
+          <ChevronLeftIcon className="h-4 w-4" />
+        </button>
+
+        <span className="min-w-[5.5rem] text-center text-[12px] font-medium tabular-nums text-[rgb(var(--ec-page-text-muted))]">
+          {currentPage} of {totalPages}
+        </span>
+
+        <button
+          onClick={() => onPageChange(Math.min(totalPages, currentPage + 1))}
+          disabled={currentPage === totalPages}
+          className="inline-flex h-9 w-9 items-center justify-center rounded-xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg))] text-[rgb(var(--ec-page-text-muted))] transition-colors hover:text-[rgb(var(--ec-page-text))] disabled:cursor-not-allowed disabled:opacity-30"
+          aria-label="Next page"
+        >
+          <ChevronRightIcon className="h-4 w-4" />
+        </button>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/ProducersConsumersSection.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/ProducersConsumersSection.tsx
new file mode 100644
index 000000000..49f15db34
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/ProducersConsumersSection.tsx
@@ -0,0 +1,86 @@
+import { ChevronDownIcon } from '@heroicons/react/24/outline';
+import { ServerIcon } from '@heroicons/react/20/solid';
+import { buildUrl } from '@utils/url-builder';
+import type { SchemaItem, Producer, Consumer } from './types';
+
+interface ProducersConsumersSectionProps {
+  message: SchemaItem;
+  isExpanded: boolean;
+  onToggle: () => void;
+}
+
+export default function ProducersConsumersSection({ message, isExpanded, onToggle }: ProducersConsumersSectionProps) {
+  const producers = message.data.producers || [];
+  const consumers = message.data.consumers || [];
+  const totalCount = producers.length + consumers.length;
+
+  if (totalCount === 0) return null;
+
+  return (
+    <div className="flex-shrink-0 border-b border-[rgb(var(--ec-page-border))]">
+      <button
+        onClick={onToggle}
+        className="w-full flex items-center justify-between px-5 py-2.5 text-left hover:bg-[rgb(var(--ec-content-hover)/0.5)] transition-colors"
+      >
+        <div className="flex items-center gap-2.5">
+          <span className="text-xs font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">Services</span>
+          <span className="text-xs tabular-nums text-[rgb(var(--ec-page-text-muted))]">{totalCount}</span>
+        </div>
+        <ChevronDownIcon
+          className={`h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))] transition-transform ${isExpanded ? 'rotate-180' : ''}`}
+        />
+      </button>
+
+      {isExpanded && (
+        <div className="px-5 pb-3 space-y-3">
+          {producers.length > 0 && (
+            <div>
+              <h4 className="text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider mb-2">
+                Producers
+              </h4>
+              <div className="flex flex-wrap gap-1.5">
+                {producers.map((producer: Producer, idx: number) => (
+                  <a
+                    key={`${producer.id}-${idx}`}
+                    href={buildUrl(`/docs/services/${producer.id}/${producer.version}`)}
+                    className="inline-flex items-center gap-1.5 pl-1.5 pr-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-content-hover))] rounded-full hover:ring-1 hover:ring-pink-400/50 transition-all"
+                    title={`View ${producer.id}`}
+                  >
+                    <div className="flex items-center justify-center w-5 h-5 bg-gradient-to-b from-pink-500 to-pink-600 rounded-full">
+                      <ServerIcon className="h-3 w-3 text-white" />
+                    </div>
+                    <span>{producer.id}</span>
+                    <span className="text-[rgb(var(--ec-page-text-muted))] text-[11px] tabular-nums">v{producer.version}</span>
+                  </a>
+                ))}
+              </div>
+            </div>
+          )}
+          {consumers.length > 0 && (
+            <div>
+              <h4 className="text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider mb-2">
+                Consumers
+              </h4>
+              <div className="flex flex-wrap gap-1.5">
+                {consumers.map((consumer: Consumer, idx: number) => (
+                  <a
+                    key={`${consumer.id}-${idx}`}
+                    href={buildUrl(`/docs/services/${consumer.id}/${consumer.version}`)}
+                    className="inline-flex items-center gap-1.5 pl-1.5 pr-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-content-hover))] rounded-full hover:ring-1 hover:ring-pink-400/50 transition-all"
+                    title={`View ${consumer.id}`}
+                  >
+                    <div className="flex items-center justify-center w-5 h-5 bg-gradient-to-b from-pink-500 to-pink-600 rounded-full">
+                      <ServerIcon className="h-3 w-3 text-white" />
+                    </div>
+                    <span>{consumer.id}</span>
+                    <span className="text-[rgb(var(--ec-page-text-muted))] text-[11px] tabular-nums">v{consumer.version}</span>
+                  </a>
+                ))}
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/ProtobufSchemaViewer.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/ProtobufSchemaViewer.tsx
new file mode 100644
index 000000000..3ffd2dffe
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/ProtobufSchemaViewer.tsx
@@ -0,0 +1,532 @@
+import { useState, useEffect, useRef, useMemo } from 'react';
+import type { ProtobufSchema, ProtobufMessage, ProtobufEnum, ProtobufField } from '@utils/protobuf-schema';
+
+interface ProtobufSchemaViewerProps {
+  schema: ProtobufSchema;
+  title?: string;
+  maxHeight?: string;
+  expand?: boolean | string;
+  search?: boolean | string;
+  showRequired?: boolean | string;
+  onOpenFullscreen?: () => void;
+}
+
+// Proto types are referenced by name (not nested inline like Avro), so we build
+// a registry of every message/enum in the file to resolve field types against.
+interface TypeRegistry {
+  messages: Map<string, ProtobufMessage>;
+  enums: Map<string, ProtobufEnum>;
+}
+
+function buildTypeRegistry(schema: ProtobufSchema): TypeRegistry {
+  const registry: TypeRegistry = { messages: new Map(), enums: new Map() };
+
+  const register = <T,>(map: Map<string, T>, qualifiedName: string, simpleName: string, value: T) => {
+    map.set(qualifiedName, value);
+    if (!map.has(simpleName)) map.set(simpleName, value);
+  };
+
+  const walk = (messages: ProtobufMessage[], enums: ProtobufEnum[], prefix: string) => {
+    for (const protoEnum of enums) {
+      register(registry.enums, prefix ? `${prefix}.${protoEnum.name}` : protoEnum.name, protoEnum.name, protoEnum);
+    }
+    for (const message of messages) {
+      const qualifiedName = prefix ? `${prefix}.${message.name}` : message.name;
+      register(registry.messages, qualifiedName, message.name, message);
+      walk(message.messages, message.enums, qualifiedName);
+    }
+  };
+
+  walk(schema.messages, schema.enums, '');
+  return registry;
+}
+
+// Resolve a field type name against the registry, trying the name as written,
+// without the package prefix, and by its last segment (e.g. "com.example.Order" -> "Order").
+// Leading dots (fully-qualified references like ".com.example.Order") are stripped first.
+function resolveTypeName(typeName: string, packageName: string | undefined): string[] {
+  const normalized = typeName.startsWith('.') ? typeName.slice(1) : typeName;
+  const candidates = [normalized];
+  if (packageName && normalized.startsWith(`${packageName}.`)) {
+    candidates.push(normalized.slice(packageName.length + 1));
+  }
+  const lastSegment = normalized.split('.').pop();
+  if (lastSegment && lastSegment !== normalized) candidates.push(lastSegment);
+  return candidates;
+}
+
+function lookupType<T>(map: Map<string, T>, typeName: string, packageName?: string): T | undefined {
+  for (const candidate of resolveTypeName(typeName, packageName)) {
+    const match = map.get(candidate);
+    if (match) return match;
+  }
+  return undefined;
+}
+
+function formatProtobufType(field: ProtobufField): string {
+  if (field.map) return field.type;
+  return field.label ? `${field.label} ${field.type}` : field.type;
+}
+
+function countFields(messages: ProtobufMessage[]): number {
+  return messages.reduce((total, message) => total + message.fields.length + countFields(message.messages), 0);
+}
+
+interface ProtobufFieldRowProps {
+  field: ProtobufField;
+  level: number;
+  expand: boolean;
+  showRequired?: boolean;
+  registry: TypeRegistry;
+  packageName?: string;
+  ancestors: string[];
+}
+
+const ProtobufFieldRow = ({ field, level, expand, showRequired, registry, packageName, ancestors }: ProtobufFieldRowProps) => {
+  const [isExpanded, setIsExpanded] = useState(expand);
+  const indentationClass = `pl-${level * 3}`;
+
+  // The type to drill into: map values and plain types can both reference messages
+  const targetTypeName = field.map ? field.map.valueType : field.type;
+  const nestedMessage = lookupType(registry.messages, targetTypeName, packageName);
+  const nestedEnum = nestedMessage ? undefined : lookupType(registry.enums, targetTypeName, packageName);
+  const isCyclic = nestedMessage ? ancestors.includes(nestedMessage.name) : false;
+  const hasNested = !!nestedMessage && nestedMessage.fields.length > 0 && !isCyclic;
+  const isRequired = field.label === 'required';
+
+  useEffect(() => {
+    setIsExpanded(expand);
+  }, [expand]);
+
+  return (
+    <div className={`proto-field-container mb-1.5 border-l border-[rgb(var(--ec-page-border))] relative ${indentationClass}`}>
+      <div className="flex items-start space-x-1.5">
+        {hasNested ? (
+          <button
+            type="button"
+            aria-expanded={isExpanded}
+            onClick={() => setIsExpanded(!isExpanded)}
+            className="proto-field-toggle text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] pt-0.5 focus:outline-hidden w-3 text-center flex-shrink-0"
+          >
+            <span className={`icon-collapsed font-mono text-xs ${isExpanded ? 'hidden' : ''}`}>&gt;</span>
+            <span className={`icon-expanded font-mono text-xs ${!isExpanded ? 'hidden' : ''}`}>v</span>
+          </button>
+        ) : (
+          <div className="w-3 h-4 flex-shrink-0" />
+        )}
+
+        <div className="flex-grow">
+          <div className="flex justify-between items-baseline">
+            <div>
+              <span className="proto-field-name font-semibold text-[rgb(var(--ec-page-text))] text-sm">{field.name}</span>
+              <span className="ml-1.5 text-[rgb(var(--ec-accent))] font-mono text-xs">{formatProtobufType(field)}</span>
+              {field.number !== undefined && (
+                <span className="ml-1.5 text-[rgb(var(--ec-page-text-muted))] font-mono text-xs">= {field.number}</span>
+              )}
+              {field.oneof && (
+                <span className="ml-1.5 text-[rgb(var(--ec-page-text-muted))] text-xs bg-[rgb(var(--ec-content-hover))] px-1 rounded">
+                  oneof {field.oneof}
+                </span>
+              )}
+            </div>
+            {showRequired && isRequired && (
+              <span className="text-red-600 dark:text-red-400 text-xs ml-3 flex-shrink-0">required</span>
+            )}
+          </div>
+
+          {field.doc && <p className="text-[rgb(var(--ec-page-text-muted))] text-xs mt-0.5">{field.doc}</p>}
+
+          {/* Show enum values if the field type resolves to an enum */}
+          {nestedEnum && nestedEnum.values.length > 0 && (
+            <div className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-0.5">
+              <span className="text-xs inline-block">Allowed values:</span>
+              {nestedEnum.values.map((value) => (
+                <span key={value.name} className="text-xs">
+                  {' '}
+                  <code className="bg-[rgb(var(--ec-content-hover))] px-1 rounded text-[rgb(var(--ec-page-text))] font-thin py-0.5">
+                    {value.name}
+                  </code>
+                </span>
+              ))}
+            </div>
+          )}
+
+          {/* Nested fields for message types */}
+          {hasNested && nestedMessage && (
+            <div className={`proto-nested-content mt-1 ${!isExpanded ? 'hidden' : ''}`}>
+              {nestedMessage.fields.map((nestedField) => (
+                <ProtobufFieldRow
+                  key={nestedField.name}
+                  field={nestedField}
+                  level={level + 1}
+                  expand={expand}
+                  showRequired={showRequired}
+                  registry={registry}
+                  packageName={packageName}
+                  ancestors={[...ancestors, nestedMessage.name]}
+                />
+              ))}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+// Main ProtobufSchemaViewer component
+export default function ProtobufSchemaViewer({
+  schema,
+  title,
+  maxHeight,
+  expand = false,
+  search = true,
+  showRequired = false,
+  onOpenFullscreen,
+}: ProtobufSchemaViewerProps) {
+  const expandBool = expand === true || expand === 'true';
+  const searchBool = search !== false && search !== 'false';
+  const showRequiredBool = showRequired === true || showRequired === 'true';
+
+  const [searchQuery, setSearchQuery] = useState('');
+  const [expandAll, setExpandAll] = useState(expandBool);
+  const [currentMatches, setCurrentMatches] = useState<HTMLElement[]>([]);
+  const [currentMatchIndex, setCurrentMatchIndex] = useState(-1);
+  const searchInputRef = useRef<HTMLInputElement>(null);
+  const fieldsContainerRef = useRef<HTMLDivElement>(null);
+
+  const registry = useMemo(() => (schema ? buildTypeRegistry(schema) : { messages: new Map(), enums: new Map() }), [schema]);
+  const totalFields = useMemo(() => (schema ? countFields(schema.messages) : 0), [schema]);
+
+  // Search functionality with highlighting
+  useEffect(() => {
+    if (!fieldsContainerRef.current) return;
+
+    const fieldContainers = fieldsContainerRef.current.querySelectorAll('.proto-field-container');
+    const matches: HTMLElement[] = [];
+
+    if (searchQuery === '') {
+      // Reset search
+      fieldContainers.forEach((container) => {
+        container.classList.remove('search-match', 'search-no-match', 'search-current-match', 'search-dimmed');
+        const nameEl = container.querySelector('.proto-field-name');
+        if (nameEl) {
+          nameEl.innerHTML = nameEl.textContent || '';
+        }
+      });
+      setCurrentMatches([]);
+      setCurrentMatchIndex(-1);
+      return;
+    }
+
+    const query = searchQuery.toLowerCase().trim();
+
+    fieldContainers.forEach((container) => {
+      const nameEl = container.querySelector('.proto-field-name');
+      if (!nameEl) return;
+
+      const fieldName = (nameEl.textContent || '').toLowerCase();
+
+      if (fieldName.includes(query)) {
+        container.classList.add('search-match');
+        container.classList.remove('search-dimmed');
+        matches.push(container as HTMLElement);
+
+        // Highlight the search term
+        const regex = new RegExp(`(${query})`, 'gi');
+        nameEl.innerHTML = (nameEl.textContent || '').replace(regex, '<mark class="bg-yellow-200 rounded px-0.5">$1</mark>');
+
+        // Expand parent containers
+        let parent = container.parentElement;
+        while (parent && parent !== fieldsContainerRef.current) {
+          if (parent.classList.contains('proto-nested-content') && parent.classList.contains('hidden')) {
+            const parentFieldContainer = parent.closest('.proto-field-container');
+            if (parentFieldContainer) {
+              const toggleBtn = parentFieldContainer.querySelector('.proto-field-toggle');
+              if (toggleBtn && toggleBtn.getAttribute('aria-expanded') === 'false') {
+                (toggleBtn as HTMLButtonElement).click();
+              }
+            }
+          }
+          // Remove dimming from parent containers
+          if (parent.classList.contains('proto-field-container')) {
+            parent.classList.remove('search-dimmed');
+          }
+          parent = parent.parentElement;
+        }
+      } else {
+        container.classList.remove('search-match', 'search-current-match');
+        container.classList.add('search-dimmed');
+        nameEl.innerHTML = nameEl.textContent || '';
+      }
+    });
+
+    setCurrentMatches(matches);
+    if (matches.length > 0) {
+      setCurrentMatchIndex(0);
+      matches[0].scrollIntoView({ behavior: 'smooth', block: 'center' });
+    } else {
+      setCurrentMatchIndex(-1);
+    }
+  }, [searchQuery]);
+
+  // Update match highlighting
+  useEffect(() => {
+    currentMatches.forEach((match, index) => {
+      if (index === currentMatchIndex) {
+        match.classList.add('search-current-match');
+      } else {
+        match.classList.remove('search-current-match');
+      }
+    });
+
+    if (currentMatchIndex >= 0 && currentMatches[currentMatchIndex]) {
+      currentMatches[currentMatchIndex].scrollIntoView({ behavior: 'smooth', block: 'center' });
+    }
+  }, [currentMatchIndex, currentMatches]);
+
+  const handleExpandAll = () => {
+    setExpandAll(true);
+  };
+
+  const handleCollapseAll = () => {
+    setExpandAll(false);
+  };
+
+  const handlePrevMatch = () => {
+    if (currentMatchIndex > 0) {
+      setCurrentMatchIndex(currentMatchIndex - 1);
+    }
+  };
+
+  const handleNextMatch = () => {
+    if (currentMatchIndex < currentMatches.length - 1) {
+      setCurrentMatchIndex(currentMatchIndex + 1);
+    }
+  };
+
+  if (!schema || !Array.isArray(schema.messages)) {
+    return (
+      <div className="flex items-center justify-center p-8 text-[rgb(var(--ec-page-text-muted))]">
+        <p className="text-sm">Invalid Protobuf schema format</p>
+      </div>
+    );
+  }
+
+  const containerStyle = maxHeight
+    ? { maxHeight: maxHeight.includes('px') ? maxHeight : `${maxHeight}px`, minHeight: '15em' }
+    : {};
+
+  const heightClass = maxHeight ? '' : 'h-full';
+  const overflowClass = maxHeight ? 'overflow-hidden' : '';
+
+  return (
+    <div
+      className={`${heightClass} ${overflowClass} flex flex-col bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-md shadow-xs`}
+      style={containerStyle}
+    >
+      {/* Toolbar */}
+      {searchBool && (
+        <div className="flex-shrink-0 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] pt-4 px-4 mb-4 pb-3 border-b border-[rgb(var(--ec-page-border))] shadow-xs">
+          <div className="flex flex-col sm:flex-row gap-3">
+            <div className="flex-1 relative">
+              <input
+                ref={searchInputRef}
+                type="text"
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                placeholder="Search fields..."
+                className="w-full px-3 py-1.5 pr-20 text-sm border border-[rgb(var(--ec-input-border))] bg-[rgb(var(--ec-input-bg))] text-[rgb(var(--ec-input-text))] placeholder:text-[rgb(var(--ec-input-placeholder))] rounded-md focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:border-transparent"
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter') {
+                    e.preventDefault();
+                    if (e.shiftKey) {
+                      handlePrevMatch();
+                    } else {
+                      handleNextMatch();
+                    }
+                  }
+                }}
+              />
+              <div className="absolute right-2 top-1/2 transform -translate-y-1/2 flex items-center gap-1">
+                <button
+                  onClick={handlePrevMatch}
+                  disabled={currentMatches.length === 0 || currentMatchIndex <= 0}
+                  className="p-1 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] disabled:opacity-30 disabled:cursor-not-allowed"
+                  title="Previous match"
+                >
+                  <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M15 19l-7-7 7-7" />
+                  </svg>
+                </button>
+                <button
+                  onClick={handleNextMatch}
+                  disabled={currentMatches.length === 0 || currentMatchIndex >= currentMatches.length - 1}
+                  className="p-1 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] disabled:opacity-30 disabled:cursor-not-allowed"
+                  title="Next match"
+                >
+                  <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M9 5l7 7-7 7" />
+                  </svg>
+                </button>
+              </div>
+            </div>
+            <div className="flex items-center gap-2">
+              {onOpenFullscreen && (
+                <button
+                  onClick={onOpenFullscreen}
+                  className="px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-content-hover))] rounded-md hover:bg-[rgb(var(--ec-content-active))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
+                  title="Open in fullscreen"
+                >
+                  <svg
+                    xmlns="http://www.w3.org/2000/svg"
+                    className="h-3.5 w-3.5 inline-block"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M4 8V4m0 0h4M4 4l5 5m11-1V4m0 0h-4m4 0l-5 5M4 16v4m0 0h4m-4 0l5-5m11 5l-5-5m5 5v-4m0 4h-4"
+                    />
+                  </svg>
+                </button>
+              )}
+              <button
+                onClick={handleExpandAll}
+                className="px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-content-hover))] rounded-md hover:bg-[rgb(var(--ec-content-active))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
+              >
+                Expand All
+              </button>
+              <button
+                onClick={handleCollapseAll}
+                className="px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-content-hover))] rounded-md hover:bg-[rgb(var(--ec-content-active))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
+              >
+                Collapse All
+              </button>
+              <div className="text-xs text-[rgb(var(--ec-page-text-muted))]">
+                {totalFields} {totalFields === 1 ? 'field' : 'fields'}
+              </div>
+            </div>
+          </div>
+          {searchQuery && (
+            <div className="mt-2 text-xs text-[rgb(var(--ec-page-text-muted))]">
+              {currentMatches.length > 0
+                ? `${currentMatchIndex + 1} of ${currentMatches.length} ${currentMatches.length === 1 ? 'match' : 'matches'}`
+                : 'No fields found'}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Messages and enums */}
+      <div ref={fieldsContainerRef} className="flex-1 px-4 pb-4 overflow-auto">
+        {(schema.package || schema.syntax) && (
+          <div className="flex items-baseline gap-2 mb-4">
+            {schema.package && (
+              <>
+                <span className="text-sm font-medium text-[rgb(var(--ec-page-text-muted))]">Package:</span>
+                <span className="font-mono text-sm text-blue-600 dark:text-blue-400">{schema.package}</span>
+              </>
+            )}
+            {schema.syntax && <span className="font-mono text-xs text-[rgb(var(--ec-page-text-muted))]">({schema.syntax})</span>}
+          </div>
+        )}
+
+        {schema.messages.length > 0 || schema.enums.length > 0 ? (
+          <>
+            {schema.messages.map((message) => (
+              <div key={message.name} className="mt-4 first:mt-0">
+                <div className="flex items-baseline gap-2 mb-2">
+                  <span className="text-sm font-medium text-[rgb(var(--ec-page-text-muted))]">Message:</span>
+                  <span className="font-mono text-sm text-blue-600 dark:text-blue-400">{message.name}</span>
+                </div>
+                {message.doc && <p className="text-[rgb(var(--ec-page-text-muted))] text-xs mb-3">{message.doc}</p>}
+                {message.fields.length > 0 ? (
+                  message.fields.map((field) => (
+                    <ProtobufFieldRow
+                      key={field.name}
+                      field={field}
+                      level={0}
+                      expand={expandAll}
+                      showRequired={showRequiredBool}
+                      registry={registry}
+                      packageName={schema.package}
+                      ancestors={[message.name]}
+                    />
+                  ))
+                ) : (
+                  <p className="text-xs text-[rgb(var(--ec-page-text-muted))] mb-2">No fields defined</p>
+                )}
+              </div>
+            ))}
+
+            {schema.enums.map((protoEnum) => (
+              <div key={protoEnum.name} className="mt-4">
+                <div className="flex items-baseline gap-2 mb-2">
+                  <span className="text-sm font-medium text-[rgb(var(--ec-page-text-muted))]">Enum:</span>
+                  <span className="font-mono text-sm text-blue-600 dark:text-blue-400">{protoEnum.name}</span>
+                </div>
+                {protoEnum.doc && <p className="text-[rgb(var(--ec-page-text-muted))] text-xs mb-2">{protoEnum.doc}</p>}
+                <div className="text-xs text-[rgb(var(--ec-page-text-muted))]">
+                  <span className="text-xs inline-block">Allowed values:</span>
+                  {protoEnum.values.map((value) => (
+                    <span key={value.name} className="text-xs">
+                      {' '}
+                      <code className="bg-[rgb(var(--ec-content-hover))] px-1 rounded text-[rgb(var(--ec-page-text))] font-thin py-0.5">
+                        {value.name}
+                      </code>
+                    </span>
+                  ))}
+                </div>
+              </div>
+            ))}
+          </>
+        ) : (
+          <div className="text-center py-8 text-[rgb(var(--ec-icon-color))]">
+            <p className="text-sm">No messages defined</p>
+          </div>
+        )}
+
+        {searchQuery && currentMatches.length === 0 && (
+          <div className="text-center py-8">
+            <div className="text-[rgb(var(--ec-icon-color))] text-sm">
+              <svg className="mx-auto h-12 w-12 mb-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth="2"
+                  d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+                />
+              </svg>
+              <p>No fields match your search</p>
+              <p className="text-xs mt-1">Try a different search term or clear the search to see all fields</p>
+            </div>
+          </div>
+        )}
+      </div>
+
+      <style>{`
+        .search-dimmed {
+          opacity: 0.4;
+          transition: opacity 0.2s ease;
+        }
+
+        .search-match {
+          opacity: 1;
+          transition: opacity 0.2s ease;
+        }
+
+        .search-current-match {
+          background-color: rgba(59, 130, 246, 0.1);
+          border-left: 3px solid #3b82f6;
+          padding-left: 8px;
+          margin-left: -11px;
+          transition: all 0.2s ease;
+        }
+      `}</style>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaCodeModal.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaCodeModal.tsx
new file mode 100644
index 000000000..dbb5ce839
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaCodeModal.tsx
@@ -0,0 +1,97 @@
+import * as Dialog from '@radix-ui/react-dialog';
+import { XMarkIcon, ArrowsPointingOutIcon, ClipboardDocumentIcon } from '@heroicons/react/24/outline';
+import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
+import { oneDark } from 'react-syntax-highlighter/dist/cjs/styles/prism';
+import { oneLight } from 'react-syntax-highlighter/dist/cjs/styles/prism';
+import { getLanguageForHighlight } from './utils';
+import type { SchemaItem } from './types';
+import { useDarkMode } from './useDarkMode';
+
+interface SchemaCodeModalProps {
+  isOpen: boolean;
+  onOpenChange: (open: boolean) => void;
+  message: SchemaItem;
+  onCopy: () => void;
+  isCopied: boolean;
+}
+
+export default function SchemaCodeModal({ isOpen, onOpenChange, message, onCopy, isCopied }: SchemaCodeModalProps) {
+  const isDarkMode = useDarkMode();
+
+  if (!message.schemaContent) return null;
+
+  return (
+    <Dialog.Root open={isOpen} onOpenChange={onOpenChange}>
+      <Dialog.Portal>
+        <Dialog.Overlay className="fixed inset-0 bg-black/50 data-[state=open]:animate-overlayShow z-50" />
+        <Dialog.Content className="fixed inset-4 md:inset-8 rounded-lg bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] shadow-xl focus:outline-hidden data-[state=open]:animate-contentShow z-[100] flex flex-col">
+          {/* Header */}
+          <div className="flex items-center justify-between p-6 border-b border-[rgb(var(--ec-page-border))] flex-shrink-0">
+            <div className="flex items-center gap-3">
+              <ArrowsPointingOutIcon className="h-6 w-6 text-[rgb(var(--ec-icon-color))]" />
+              <div>
+                <Dialog.Title className="text-xl font-semibold text-[rgb(var(--ec-page-text))]">{message.data.name}</Dialog.Title>
+                <Dialog.Description className="text-sm text-[rgb(var(--ec-page-text-muted))] mt-1">
+                  v{message.data.version} · {getLanguageForHighlight(message.schemaExtension).toUpperCase()}
+                </Dialog.Description>
+              </div>
+            </div>
+            <div className="flex items-center gap-2">
+              <button
+                onClick={onCopy}
+                className="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-content-hover))] rounded-md transition-colors"
+                title="Copy code"
+              >
+                <ClipboardDocumentIcon className="h-4 w-4" />
+                {isCopied ? 'Copied!' : 'Copy'}
+              </button>
+              <Dialog.Close asChild>
+                <button
+                  type="button"
+                  className="p-2 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] rounded-md transition-colors"
+                  aria-label="Close"
+                >
+                  <XMarkIcon className="h-6 w-6" />
+                </button>
+              </Dialog.Close>
+            </div>
+          </div>
+
+          {/* Content */}
+          <div className="flex-1 overflow-auto p-6">
+            <SyntaxHighlighter
+              language={getLanguageForHighlight(message.schemaExtension)}
+              style={isDarkMode ? oneDark : oneLight}
+              customStyle={{
+                margin: 0,
+                padding: '1rem',
+                borderRadius: '0.5rem',
+                fontSize: '0.875rem',
+                lineHeight: '1.6',
+                height: '100%',
+                background: 'rgb(var(--ec-code-bg))',
+              }}
+              showLineNumbers={true}
+              wrapLines={true}
+              wrapLongLines={true}
+            >
+              {message.schemaContent}
+            </SyntaxHighlighter>
+          </div>
+
+          {/* Footer */}
+          <div className="flex justify-end p-4 border-t border-[rgb(var(--ec-page-border))] flex-shrink-0">
+            <Dialog.Close asChild>
+              <button
+                type="button"
+                className="px-4 py-2 text-sm font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] focus:outline-hidden transition-colors"
+              >
+                Close
+              </button>
+            </Dialog.Close>
+          </div>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaContentViewer.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaContentViewer.tsx
new file mode 100644
index 000000000..28cb34794
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaContentViewer.tsx
@@ -0,0 +1,136 @@
+import { ClipboardDocumentIcon, ArrowsPointingOutIcon } from '@heroicons/react/24/outline';
+import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
+import { oneDark } from 'react-syntax-highlighter/dist/cjs/styles/prism';
+import { oneLight } from 'react-syntax-highlighter/dist/cjs/styles/prism';
+import { buildUrl } from '@utils/url-builder';
+import JSONSchemaViewer from './JSONSchemaViewer';
+import AvroSchemaViewer from './AvroSchemaViewer';
+import ProtobufSchemaViewer from './ProtobufSchemaViewer';
+import { getLanguageForHighlight } from './utils';
+import type { SchemaItem } from './types';
+import { useDarkMode } from './useDarkMode';
+
+interface SchemaContentViewerProps {
+  message: SchemaItem;
+  onCopy: () => void;
+  isCopied: boolean;
+  viewMode: 'code' | 'schema' | 'diff';
+  parsedSchema: any;
+  parsedAvroSchema?: any;
+  parsedProtoSchema?: any;
+  onOpenFullscreen?: () => void;
+  showRequired?: boolean;
+}
+
+export default function SchemaContentViewer({
+  message,
+  onCopy,
+  isCopied,
+  viewMode,
+  parsedSchema,
+  parsedAvroSchema,
+  parsedProtoSchema,
+  showRequired = false,
+  onOpenFullscreen,
+}: SchemaContentViewerProps) {
+  const isDarkMode = useDarkMode();
+
+  if (!message.schemaContent) {
+    return (
+      <div className="flex items-center justify-center h-full text-[rgb(var(--ec-page-text-muted))]">
+        <p className="text-sm">No schema content available</p>
+      </div>
+    );
+  }
+
+  // Render schema viewer based on schema type
+  if (viewMode === 'schema') {
+    if (parsedAvroSchema) {
+      return <AvroSchemaViewer schema={parsedAvroSchema} onOpenFullscreen={onOpenFullscreen} showRequired={showRequired} />;
+    }
+    if (parsedProtoSchema) {
+      return <ProtobufSchemaViewer schema={parsedProtoSchema} onOpenFullscreen={onOpenFullscreen} showRequired={showRequired} />;
+    }
+    if (parsedSchema) {
+      return <JSONSchemaViewer schema={parsedSchema} onOpenFullscreen={onOpenFullscreen} />;
+    }
+  }
+
+  return (
+    <div className="relative flex h-full min-h-0 flex-col overflow-hidden rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-code-bg))]">
+      <div className="pointer-events-none absolute right-4 top-4 z-10 flex items-center gap-1.5">
+        {message.collection === 'services' &&
+          (() => {
+            const specType = message.specType || 'openapi';
+            const specFilename = message.specFilenameWithoutExtension || 'schema';
+
+            let urlSegment = 'spec';
+            if (specType === 'asyncapi') {
+              urlSegment = 'asyncapi';
+            } else if (specType === 'graphql') {
+              urlSegment = 'graphql';
+            }
+
+            const specUrl = buildUrl(`/docs/services/${message.data.id}/${message.data.version}/${urlSegment}/${specFilename}`);
+
+            return (
+              <a
+                href={specUrl}
+                className="pointer-events-auto inline-flex items-center gap-1 rounded-md bg-[rgb(var(--ec-content-hover)/0.9)] px-2 py-1 text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] backdrop-blur-xs transition-colors hover:bg-[rgb(var(--ec-page-bg)/0.75)] hover:text-[rgb(var(--ec-page-text))]"
+                title="View full specification"
+              >
+                <svg xmlns="http://www.w3.org/2000/svg" className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={2}
+                    d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"
+                  />
+                </svg>
+                View Spec
+              </a>
+            );
+          })()}
+        {onOpenFullscreen && (
+          <button
+            onClick={onOpenFullscreen}
+            className="pointer-events-auto inline-flex items-center rounded-md bg-[rgb(var(--ec-content-hover)/0.9)] p-1.5 text-[rgb(var(--ec-page-text-muted))] backdrop-blur-xs transition-colors hover:bg-[rgb(var(--ec-page-bg)/0.75)] hover:text-[rgb(var(--ec-page-text))]"
+            title="Open in fullscreen"
+          >
+            <ArrowsPointingOutIcon className="h-3.5 w-3.5" />
+          </button>
+        )}
+        <button
+          onClick={onCopy}
+          className="pointer-events-auto inline-flex items-center gap-1 rounded-md bg-[rgb(var(--ec-content-hover)/0.9)] px-2 py-1.5 text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] backdrop-blur-xs transition-colors hover:bg-[rgb(var(--ec-page-bg)/0.75)] hover:text-[rgb(var(--ec-page-text))]"
+          title="Copy code"
+        >
+          <ClipboardDocumentIcon className="h-3 w-3" />
+          {isCopied ? 'Copied!' : 'Copy'}
+        </button>
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-auto">
+        <SyntaxHighlighter
+          language={getLanguageForHighlight(message.schemaExtension)}
+          style={isDarkMode ? oneDark : oneLight}
+          customStyle={{
+            margin: 0,
+            padding: '1.25rem',
+            borderRadius: 0,
+            fontSize: '0.8125rem',
+            lineHeight: '1.625',
+            height: '100%',
+            overflow: 'auto',
+            background: 'transparent',
+          }}
+          showLineNumbers={true}
+          wrapLines={true}
+          wrapLongLines={true}
+        >
+          {message.schemaContent}
+        </SyntaxHighlighter>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaDetailsHeader.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaDetailsHeader.tsx
new file mode 100644
index 000000000..af4339afe
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaDetailsHeader.tsx
@@ -0,0 +1,81 @@
+import { ClipboardDocumentIcon, ArrowDownTrayIcon, ArrowTopRightOnSquareIcon } from '@heroicons/react/24/outline';
+import { CheckIcon } from '@heroicons/react/24/solid';
+import { buildUrl } from '@utils/url-builder';
+import { getCollectionStyles } from '@components/Grids/utils';
+import { getSchemaTypeLabel, ICON_SPECS, getFormatBadge } from './utils';
+import type { SchemaItem } from './types';
+
+interface SchemaDetailsHeaderProps {
+  message: SchemaItem;
+  onCopy: () => void;
+  onDownload: () => void;
+  isCopied: boolean;
+}
+
+export default function SchemaDetailsHeader({ message, onCopy, onDownload, isCopied }: SchemaDetailsHeaderProps) {
+  const { color } = getCollectionStyles(message.collection);
+  const ext = message.schemaExtension?.toLowerCase() || '';
+  const iconSpec = ICON_SPECS[ext];
+
+  return (
+    <div className="flex-shrink-0 px-6 pt-5 pb-4">
+      <div className="flex items-center justify-between gap-4">
+        <div className="flex items-center gap-3 min-w-0">
+          {/* Format badge */}
+          <div className="flex-shrink-0 flex items-center justify-center w-9 h-9 rounded-lg bg-[rgb(var(--ec-content-hover))] border border-[rgb(var(--ec-page-border)/0.5)]">
+            {iconSpec ? (
+              <img src={buildUrl(`/icons/${iconSpec}.svg`, true)} alt={`${ext} icon`} className="h-5 w-5" />
+            ) : (
+              <span className="text-xs font-bold font-mono text-[rgb(var(--ec-page-text-muted))]">
+                {getFormatBadge(ext).label}
+              </span>
+            )}
+          </div>
+
+          {/* Title + badges */}
+          <h2 className="text-lg font-semibold text-[rgb(var(--ec-page-text))] truncate">{message.data.name}</h2>
+          <span className="flex-shrink-0 text-xs font-mono tabular-nums text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2 py-0.5 rounded-md">
+            v{message.data.version}
+          </span>
+          <span className="flex-shrink-0 inline-flex items-center gap-1 px-2 py-0.5 rounded-md text-[11px] font-medium bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-page-text-muted))]">
+            {getSchemaTypeLabel(message.schemaExtension)}
+          </span>
+          <span
+            className={`flex-shrink-0 inline-flex items-center gap-1 px-2 py-0.5 rounded-md text-[11px] font-medium bg-${color}-500/10 text-${color}-400 capitalize`}
+          >
+            {message.collection}
+          </span>
+        </div>
+
+        {/* Action buttons */}
+        <div className="flex items-center gap-2 flex-shrink-0">
+          <button
+            onClick={onCopy}
+            className={`inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded-md border transition-all ${
+              isCopied
+                ? 'bg-green-500/10 text-green-400 border-green-500/30'
+                : 'text-[rgb(var(--ec-page-text-muted))] border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))]'
+            }`}
+          >
+            {isCopied ? <CheckIcon className="h-3.5 w-3.5" /> : <ClipboardDocumentIcon className="h-3.5 w-3.5" />}
+            {isCopied ? 'Copied' : 'Copy link'}
+          </button>
+          <button
+            onClick={onDownload}
+            className="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] transition-all"
+          >
+            <ArrowDownTrayIcon className="h-3.5 w-3.5" />
+            Download
+          </button>
+          <a
+            href={buildUrl(`/docs/${message.collection}/${message.data.id}/${message.data.version}`)}
+            className="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] transition-all"
+          >
+            <ArrowTopRightOnSquareIcon className="h-3.5 w-3.5" />
+            Back
+          </a>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaDetailsPanel.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaDetailsPanel.tsx
new file mode 100644
index 000000000..34941bd9f
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaDetailsPanel.tsx
@@ -0,0 +1,617 @@
+import { useState, useMemo, useEffect, useRef } from 'react';
+import * as Diff from 'diff';
+import { html } from 'diff2html';
+import 'diff2html/bundles/css/diff2html.min.css';
+import {
+  ArrowDownTrayIcon,
+  ArrowTopRightOnSquareIcon,
+  ChevronDownIcon,
+  ClipboardDocumentIcon,
+  TableCellsIcon,
+  CodeBracketIcon,
+  ClockIcon,
+  GlobeAltIcon,
+  ServerIcon,
+  BookOpenIcon,
+} from '@heroicons/react/24/outline';
+import { CheckIcon } from '@heroicons/react/20/solid';
+import { buildUrl } from '@utils/url-builder';
+import { getCollectionStyles } from '@components/Grids/utils';
+import SchemaContentViewer from './SchemaContentViewer';
+import DiffViewer from './DiffViewer';
+import ApiContentViewer from './ApiContentViewer';
+import ExamplesViewer from './ExamplesViewer';
+import VersionHistoryModal from './VersionHistoryModal';
+import SchemaCodeModal from './SchemaCodeModal';
+import SchemaViewerModal from './SchemaViewerModal';
+import { copyToClipboard, downloadSchema, getSchemaTypeLabel, ICON_SPECS, extractServiceName } from './utils';
+import { parseProtobufSchema } from '@utils/protobuf-schema';
+import type { SchemaItem, VersionDiff, Owner, Producer, Consumer } from './types';
+
+interface SchemaDetailsPanelProps {
+  message: SchemaItem;
+  availableVersions: SchemaItem[];
+  selectedVersion: string | null;
+  onVersionChange: (version: string) => void;
+  apiAccessEnabled?: boolean;
+  showOwners?: boolean;
+  showProducersConsumers?: boolean;
+}
+
+export default function SchemaDetailsPanel({
+  message,
+  availableVersions,
+  selectedVersion,
+  onVersionChange,
+  apiAccessEnabled = false,
+  showOwners = true,
+  showProducersConsumers = true,
+}: SchemaDetailsPanelProps) {
+  const [copiedId, setCopiedId] = useState<string | null>(null);
+  const [activeTab, setActiveTab] = useState<'code' | 'schema' | 'diff' | 'api' | 'examples'>('code');
+  const [isDiffModalOpen, setIsDiffModalOpen] = useState(false);
+  const [isCodeModalOpen, setIsCodeModalOpen] = useState(false);
+  const [isSchemaViewerModalOpen, setIsSchemaViewerModalOpen] = useState(false);
+  const [isActionsOpen, setIsActionsOpen] = useState(false);
+  const actionsMenuRef = useRef<HTMLDivElement>(null);
+
+  const hasMultipleVersions = availableVersions.length > 1;
+  const { color } = getCollectionStyles(message.collection);
+  const ext = message.schemaExtension?.toLowerCase() || '';
+  const iconSpec = ICON_SPECS[ext];
+  const owners = message.data.owners || [];
+  const producers = message.data.producers || [];
+  const consumers = message.data.consumers || [];
+  const filename = message.data.schemaPath?.split('/').pop() || `${message.data.id}.${ext || 'json'}`;
+
+  const uniqueAvailableVersions = useMemo(
+    () =>
+      availableVersions.filter(
+        (version, index, versions) => versions.findIndex((item) => item.data.version === version.data.version) === index
+      ),
+    [availableVersions]
+  );
+  const defaultToVersion = uniqueAvailableVersions[0]?.data.version || '';
+  const defaultFromVersion = uniqueAvailableVersions[1]?.data.version || defaultToVersion;
+  const [diffFromVersion, setDiffFromVersion] = useState(defaultFromVersion);
+  const [diffToVersion, setDiffToVersion] = useState(defaultToVersion);
+  const schemaResourceKey = [
+    message.collection,
+    message.data.id,
+    message.specType || '',
+    message.specFilenameWithoutExtension || message.specName || '',
+  ].join(':');
+
+  useEffect(() => {
+    setDiffFromVersion(defaultFromVersion);
+    setDiffToVersion(defaultToVersion);
+    setIsDiffModalOpen(false);
+  }, [schemaResourceKey, defaultFromVersion, defaultToVersion]);
+
+  const diffFromItem = useMemo(
+    () => uniqueAvailableVersions.find((version) => version.data.version === diffFromVersion),
+    [diffFromVersion, uniqueAvailableVersions]
+  );
+  const diffToItem = useMemo(
+    () => uniqueAvailableVersions.find((version) => version.data.version === diffToVersion),
+    [diffToVersion, uniqueAvailableVersions]
+  );
+  const hasDiffFromContent = !!diffFromItem?.schemaContent?.trim();
+  const hasDiffToContent = !!diffToItem?.schemaContent?.trim();
+  const selectedDiff: VersionDiff | null = useMemo(() => {
+    if (!diffFromItem || !diffToItem) return null;
+    if (diffFromItem.data.version === diffToItem.data.version) return null;
+    if (!diffFromItem.schemaContent?.trim() || !diffToItem.schemaContent?.trim()) return null;
+
+    const diff = Diff.createTwoFilesPatch(
+      `v${diffFromItem.data.version}`,
+      `v${diffToItem.data.version}`,
+      diffFromItem.schemaContent,
+      diffToItem.schemaContent,
+      '',
+      '',
+      { context: 3 }
+    );
+
+    const diffHtml = html(diff, {
+      drawFileList: false,
+      matching: 'lines',
+      outputFormat: 'side-by-side',
+    });
+
+    return {
+      fromVersion: diffFromItem.data.version,
+      toVersion: diffToItem.data.version,
+      diffHtml,
+      fromContent: diffFromItem.schemaContent,
+      toContent: diffToItem.schemaContent,
+    };
+  }, [diffFromItem, diffToItem]);
+  const selectedDiffs = selectedDiff ? [selectedDiff] : [];
+
+  // Check if this is a JSON schema
+  const parsedSchema = useMemo(() => {
+    const isJSONSchema =
+      message.schemaExtension?.toLowerCase() === 'json' && message.schemaContent && message.schemaContent.trim() !== '';
+    if (!isJSONSchema) return null;
+
+    try {
+      const parsed = JSON.parse(message.schemaContent ?? '');
+      if (!parsed.properties && !parsed.$schema && !parsed.type) {
+        return null;
+      }
+      return parsed;
+    } catch {
+      return null;
+    }
+  }, [message.schemaContent, message.schemaExtension]);
+
+  // Check if this is an Avro schema
+  const parsedAvroSchema = useMemo(() => {
+    const extLower = message.schemaExtension?.toLowerCase();
+    const isAvroSchema =
+      (extLower === 'avro' || extLower === 'avsc') && message.schemaContent && message.schemaContent.trim() !== '';
+    if (!isAvroSchema) return null;
+
+    try {
+      const parsed = JSON.parse(message.schemaContent ?? '');
+      if (!parsed.type) {
+        return null;
+      }
+      return parsed;
+    } catch {
+      return null;
+    }
+  }, [message.schemaContent, message.schemaExtension]);
+
+  // Check if this is a Protobuf schema. The extension falls back to the schema
+  // format when the schema has no file path, so accept both 'proto' and 'protobuf'.
+  const parsedProtoSchema = useMemo(() => {
+    const extLower = message.schemaExtension?.toLowerCase();
+    const isProtoSchema =
+      (extLower === 'proto' || extLower === 'protobuf') && message.schemaContent && message.schemaContent.trim() !== '';
+    if (!isProtoSchema) return null;
+
+    try {
+      return parseProtobufSchema(message.schemaContent ?? '');
+    } catch {
+      return null;
+    }
+  }, [message.schemaContent, message.schemaExtension]);
+
+  const handleCopy = async () => {
+    if (!message.schemaContent) return;
+    const success = await copyToClipboard(message.schemaContent);
+    if (success) {
+      setCopiedId(message.data.id);
+      setTimeout(() => setCopiedId(null), 2000);
+    }
+  };
+
+  const handleCopyCustom = async (content: string, id: string) => {
+    const success = await copyToClipboard(content);
+    if (success) {
+      setCopiedId(id);
+      setTimeout(() => setCopiedId(null), 2000);
+    }
+  };
+
+  const handleDownload = () => {
+    if (!message.schemaContent) return;
+    downloadSchema(message.schemaContent, message.data.id, message.schemaExtension || 'json');
+  };
+
+  const isCopied = copiedId === message.data.id;
+  const docsUrl = buildUrl(`/docs/${message.collection}/${message.data.id}/${message.data.version}`);
+  const sidebarCardClass = 'rounded-xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg)/0.66)] px-4 py-4';
+
+  useEffect(() => {
+    const handlePointerDown = (event: MouseEvent) => {
+      if (!actionsMenuRef.current?.contains(event.target as Node)) {
+        setIsActionsOpen(false);
+      }
+    };
+
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        setIsActionsOpen(false);
+      }
+    };
+
+    document.addEventListener('mousedown', handlePointerDown);
+    document.addEventListener('keydown', handleEscape);
+
+    return () => {
+      document.removeEventListener('mousedown', handlePointerDown);
+      document.removeEventListener('keydown', handleEscape);
+    };
+  }, []);
+
+  const hasParsedSchema = !!parsedSchema || !!parsedAvroSchema || !!parsedProtoSchema;
+  // Build tabs
+  const tabs: { id: string; label: string; icon: React.ReactNode }[] = [
+    { id: 'code', label: 'Schema', icon: <CodeBracketIcon className="h-3.5 w-3.5" /> },
+  ];
+  if (hasParsedSchema) {
+    tabs.push({ id: 'schema', label: 'Properties', icon: <TableCellsIcon className="h-3.5 w-3.5" /> });
+  }
+  const examples = message.examples || [];
+  if (examples.length > 0) {
+    tabs.push({ id: 'examples', label: 'Usage Examples', icon: <BookOpenIcon className="h-3.5 w-3.5" /> });
+  }
+  if (hasMultipleVersions) {
+    tabs.push({ id: 'diff', label: 'Changes', icon: <ClockIcon className="h-3.5 w-3.5" /> });
+  }
+  tabs.push({ id: 'api', label: 'API', icon: <GlobeAltIcon className="h-3.5 w-3.5" /> });
+
+  return (
+    <div className="flex h-full min-h-0 bg-[rgb(var(--ec-page-bg))] overflow-hidden">
+      {/* Left: header + tabs + content */}
+      <div className="flex-1 min-h-0 min-w-0 flex flex-col overflow-hidden">
+        {/* Compact header */}
+        <div className="flex-shrink-0 px-6 pt-5 pb-3">
+          <div className="flex items-start justify-between gap-4">
+            <div className="min-w-0 flex-1">
+              <div className="flex min-w-0 items-center gap-3">
+                <div className="flex-shrink-0 flex items-center justify-center w-9 h-9 rounded-lg bg-[rgb(var(--ec-content-hover))] border border-[rgb(var(--ec-page-border)/0.5)]">
+                  {iconSpec ? (
+                    <img src={buildUrl(`/icons/${iconSpec}.svg`, true)} alt={`${ext} icon`} className="h-5 w-5 schema-icon" />
+                  ) : (
+                    <span className="text-xs font-bold font-mono text-[rgb(var(--ec-page-text-muted))]">{'{ }'}</span>
+                  )}
+                </div>
+                <h2 className="text-xl font-semibold text-[rgb(var(--ec-page-text))] truncate">{message.data.name}</h2>
+                <span className="flex-shrink-0 text-xs font-mono tabular-nums text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] px-2 py-0.5 rounded-md">
+                  v{message.data.version}
+                </span>
+                <span
+                  className={`flex-shrink-0 inline-flex items-center gap-1 px-2 py-0.5 rounded-md text-[11px] font-medium bg-${color}-500/10 text-${color}-400 capitalize`}
+                >
+                  {message.collection}
+                </span>
+              </div>
+              {message.data.summary && (
+                <p className="mt-3 text-sm leading-relaxed text-[rgb(var(--ec-page-text-muted))]">{message.data.summary}</p>
+              )}
+            </div>
+
+            <div className="relative flex-shrink-0" ref={actionsMenuRef}>
+              <div className="inline-flex overflow-hidden rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover))] shadow-xs">
+                <button
+                  type="button"
+                  onClick={() => setIsActionsOpen((prev) => !prev)}
+                  aria-expanded={isActionsOpen}
+                  aria-haspopup="menu"
+                  className="inline-flex items-center gap-2 px-4 py-2 text-xs font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:bg-[rgb(var(--ec-page-bg)/0.45)] hover:text-[rgb(var(--ec-accent))]"
+                >
+                  Actions
+                </button>
+                <button
+                  type="button"
+                  onClick={() => setIsActionsOpen((prev) => !prev)}
+                  aria-expanded={isActionsOpen}
+                  aria-haspopup="menu"
+                  aria-label="Open actions menu"
+                  className="inline-flex items-center justify-center border-l border-[rgb(var(--ec-page-border))] px-2.5 py-2 text-[rgb(var(--ec-page-text-muted))] transition-colors hover:bg-[rgb(var(--ec-page-bg)/0.45)] hover:text-[rgb(var(--ec-page-text))]"
+                >
+                  <ChevronDownIcon className={`h-3.5 w-3.5 transition-transform ${isActionsOpen ? 'rotate-180' : ''}`} />
+                </button>
+              </div>
+
+              {isActionsOpen && (
+                <div className="absolute right-0 top-[calc(100%+0.5rem)] z-20 min-w-[220px] overflow-hidden rounded-xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg))] shadow-xl">
+                  <a
+                    href={docsUrl}
+                    className="flex items-center gap-2.5 px-3 py-2.5 text-xs font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-accent))]"
+                  >
+                    <ArrowTopRightOnSquareIcon className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))]" />
+                    View documentation
+                  </a>
+                  <button
+                    onClick={() => {
+                      handleDownload();
+                      setIsActionsOpen(false);
+                    }}
+                    className="flex w-full items-center gap-2.5 px-3 py-2.5 text-left text-xs font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-accent))]"
+                  >
+                    <ArrowDownTrayIcon className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))]" />
+                    Download schema
+                  </button>
+                  <button
+                    onClick={() => {
+                      handleCopy();
+                      setIsActionsOpen(false);
+                    }}
+                    className="flex w-full items-center gap-2.5 px-3 py-2.5 text-left text-xs font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-accent))]"
+                  >
+                    {isCopied ? (
+                      <CheckIcon className="h-3.5 w-3.5 text-green-400" />
+                    ) : (
+                      <ClipboardDocumentIcon className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))]" />
+                    )}
+                    {isCopied ? 'Copied to clipboard' : 'Copy schema to clipboard'}
+                  </button>
+                </div>
+              )}
+            </div>
+          </div>
+        </div>
+
+        {/* Tabs */}
+        <div className="flex-shrink-0 px-6">
+          <div className="flex items-center gap-1 border-b border-[rgb(var(--ec-page-border))]">
+            {tabs.map((tab) => (
+              <button
+                key={tab.id}
+                onClick={() => setActiveTab(tab.id as typeof activeTab)}
+                className={`inline-flex items-center gap-1.5 px-3 py-2 text-xs font-medium border-b-2 transition-colors ${
+                  activeTab === tab.id
+                    ? 'border-[rgb(var(--ec-accent))] text-[rgb(var(--ec-page-text))]'
+                    : 'border-transparent text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] hover:border-[rgb(var(--ec-page-border))]'
+                }`}
+              >
+                {tab.icon}
+                {tab.label}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        {/* Tab content */}
+        <div className="flex-1 min-h-0 overflow-hidden p-6">
+          {activeTab === 'examples' && examples.length > 0 ? (
+            <ExamplesViewer examples={examples} />
+          ) : activeTab === 'api' ? (
+            <ApiContentViewer
+              message={message}
+              onCopy={handleCopyCustom}
+              copiedId={copiedId}
+              apiAccessEnabled={apiAccessEnabled}
+            />
+          ) : activeTab === 'diff' && hasMultipleVersions ? (
+            <div className="flex h-full min-h-0 flex-col overflow-hidden">
+              <div className="mb-4 flex flex-shrink-0 flex-col gap-3 rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover)/0.45)] p-3 sm:flex-row sm:items-end sm:justify-between">
+                <div className="grid flex-1 grid-cols-1 gap-3 sm:grid-cols-2">
+                  <label className="flex flex-col gap-1.5">
+                    <span className="text-[11px] font-medium uppercase tracking-[0.14em] text-[rgb(var(--ec-page-text-muted))]">
+                      From
+                    </span>
+                    <select
+                      value={diffFromVersion}
+                      onChange={(event) => setDiffFromVersion(event.target.value)}
+                      className="h-9 rounded-md border border-[rgb(var(--ec-dropdown-border))] bg-[rgb(var(--ec-dropdown-bg))] px-3 text-sm font-mono tabular-nums text-[rgb(var(--ec-page-text))] outline-hidden transition-colors focus:border-[rgb(var(--ec-accent))] focus:ring-1 focus:ring-[rgb(var(--ec-accent)/0.3)]"
+                    >
+                      {uniqueAvailableVersions.map((version) => (
+                        <option key={`from-${version.data.version}`} value={version.data.version}>
+                          v{version.data.version}
+                        </option>
+                      ))}
+                    </select>
+                  </label>
+                  <label className="flex flex-col gap-1.5">
+                    <span className="text-[11px] font-medium uppercase tracking-[0.14em] text-[rgb(var(--ec-page-text-muted))]">
+                      To
+                    </span>
+                    <select
+                      value={diffToVersion}
+                      onChange={(event) => setDiffToVersion(event.target.value)}
+                      className="h-9 rounded-md border border-[rgb(var(--ec-dropdown-border))] bg-[rgb(var(--ec-dropdown-bg))] px-3 text-sm font-mono tabular-nums text-[rgb(var(--ec-page-text))] outline-hidden transition-colors focus:border-[rgb(var(--ec-accent))] focus:ring-1 focus:ring-[rgb(var(--ec-accent)/0.3)]"
+                    >
+                      {uniqueAvailableVersions.map((version) => (
+                        <option key={`to-${version.data.version}`} value={version.data.version}>
+                          v{version.data.version}
+                        </option>
+                      ))}
+                    </select>
+                  </label>
+                </div>
+                <button
+                  type="button"
+                  onClick={() => setIsDiffModalOpen(true)}
+                  disabled={!selectedDiff}
+                  className="inline-flex h-9 items-center justify-center gap-1.5 rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg))] px-3 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] transition-colors hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] disabled:cursor-not-allowed disabled:opacity-50"
+                >
+                  <ArrowTopRightOnSquareIcon className="h-3.5 w-3.5" />
+                  Expand
+                </button>
+              </div>
+              <div className="min-h-0 flex-1 overflow-hidden">
+                {diffFromVersion === diffToVersion ? (
+                  <div className="flex h-full items-center justify-center text-[rgb(var(--ec-page-text-muted))]">
+                    <p className="text-sm">Select two different versions</p>
+                  </div>
+                ) : !hasDiffFromContent || !hasDiffToContent ? (
+                  <div className="flex h-full items-center justify-center text-[rgb(var(--ec-page-text-muted))]">
+                    <p className="text-sm">No schema content available</p>
+                  </div>
+                ) : (
+                  <DiffViewer diffs={selectedDiffs} apiAccessEnabled={apiAccessEnabled} />
+                )}
+              </div>
+            </div>
+          ) : (
+            <SchemaContentViewer
+              message={message}
+              onCopy={handleCopy}
+              isCopied={isCopied}
+              viewMode={activeTab === 'schema' ? 'schema' : 'code'}
+              parsedSchema={parsedSchema}
+              parsedAvroSchema={parsedAvroSchema}
+              parsedProtoSchema={parsedProtoSchema}
+              showRequired={true}
+              onOpenFullscreen={
+                activeTab === 'code'
+                  ? () => setIsCodeModalOpen(true)
+                  : activeTab === 'schema' && (parsedSchema || parsedAvroSchema || parsedProtoSchema)
+                    ? () => setIsSchemaViewerModalOpen(true)
+                    : undefined
+              }
+            />
+          )}
+        </div>
+      </div>
+
+      {/* Right sidebar - spans full height */}
+      <div className="h-full w-80 flex-shrink-0 overflow-y-auto border-l border-[rgb(var(--ec-page-border))] px-3 py-4">
+        <div className="space-y-3">
+          {/* Details section */}
+          <div className={sidebarCardClass}>
+            <h3 className="mb-4 text-[0.8rem] font-semibold text-[rgb(var(--ec-page-text))]">Details</h3>
+            <dl className="space-y-2.5">
+              <div className="flex items-center justify-between">
+                <dt className="text-xs text-[rgb(var(--ec-page-text-muted))]">Format</dt>
+                <dd className="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">
+                  {getSchemaTypeLabel(message.schemaExtension)}
+                </dd>
+              </div>
+              <div className="flex items-center justify-between">
+                <dt className="text-xs text-[rgb(var(--ec-page-text-muted))]">Resource</dt>
+                <dd className={`text-xs font-medium text-${color}-400 capitalize`}>{message.collection}</dd>
+              </div>
+              <div className="flex items-center justify-between gap-3">
+                <dt className="text-xs text-[rgb(var(--ec-page-text-muted))]">Filename</dt>
+                <dd className="max-w-[11rem] truncate text-xs font-medium text-[rgb(var(--ec-page-text-muted))]" title={filename}>
+                  {filename}
+                </dd>
+              </div>
+            </dl>
+          </div>
+
+          {/* Versions section */}
+          <div className={sidebarCardClass}>
+            <div className="mb-3 flex items-center justify-between gap-3">
+              <h3 className="text-[0.8rem] font-semibold text-[rgb(var(--ec-page-text))]">Versions</h3>
+            </div>
+            <div className="space-y-1">
+              {availableVersions
+                .filter((v, idx, arr) => arr.findIndex((a) => a.data.version === v.data.version) === idx)
+                .map((v, idx) => {
+                  const isActive = v.data.version === message.data.version;
+                  const isLatest = idx === 0;
+                  return (
+                    <button
+                      key={`${v.data.version}-${idx}`}
+                      onClick={() => onVersionChange(v.data.version)}
+                      className={`w-full flex items-center gap-2 rounded-lg px-2 py-1.5 text-left transition-colors ${
+                        isActive
+                          ? 'bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-page-text))]'
+                          : 'text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-page-bg)/0.55)]'
+                      }`}
+                    >
+                      <div
+                        className={`w-2 h-2 rounded-full flex-shrink-0 ${
+                          isActive ? 'bg-[rgb(var(--ec-accent))]' : 'bg-[rgb(var(--ec-page-border))]'
+                        }`}
+                      />
+                      <span className="text-xs font-mono tabular-nums">v{v.data.version}</span>
+                      {isLatest && (
+                        <span className="text-[10px] font-medium text-[rgb(var(--ec-accent))] bg-[rgb(var(--ec-accent-subtle))] px-1.5 py-0.5 rounded">
+                          latest
+                        </span>
+                      )}
+                    </button>
+                  );
+                })}
+            </div>
+          </div>
+
+          {/* Schema producers section */}
+          {showProducersConsumers && producers.length > 0 && message.collection !== 'services' && (
+            <div className={sidebarCardClass}>
+              <div className="mb-2.5 flex items-center justify-between gap-3">
+                <h3 className="text-[0.8rem] font-semibold text-[rgb(var(--ec-page-text))]">
+                  Schema Producers ({producers.length})
+                </h3>
+              </div>
+              <div className="space-y-1">
+                {producers.map((producer: Producer, idx: number) => {
+                  const serviceName = extractServiceName(producer.id);
+                  return (
+                    <a
+                      key={`${producer.id}-${idx}`}
+                      href={buildUrl(`/docs/services/${serviceName}/${producer.version}`)}
+                      className="flex items-center gap-2 rounded-lg px-2 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] transition-colors hover:bg-[rgb(var(--ec-page-bg)/0.55)] hover:text-[rgb(var(--ec-accent))]"
+                    >
+                      <ServerIcon className="h-3.5 w-3.5 flex-shrink-0 text-[rgb(var(--ec-page-text-muted))]" />
+                      {serviceName}
+                    </a>
+                  );
+                })}
+              </div>
+            </div>
+          )}
+
+          {/* Schema consumers section */}
+          {showProducersConsumers && consumers.length > 0 && message.collection !== 'services' && (
+            <div className={sidebarCardClass}>
+              <div className="mb-2.5 flex items-center justify-between gap-3">
+                <h3 className="text-[0.8rem] font-semibold text-[rgb(var(--ec-page-text))]">
+                  Schema Consumers ({consumers.length})
+                </h3>
+              </div>
+              <div className="space-y-1">
+                {consumers.map((consumer: Consumer, idx: number) => {
+                  const serviceName = extractServiceName(consumer.id);
+                  return (
+                    <a
+                      key={`${consumer.id}-${idx}`}
+                      href={buildUrl(`/docs/services/${serviceName}/${consumer.version}`)}
+                      className="flex items-center gap-2 rounded-lg px-2 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] transition-colors hover:bg-[rgb(var(--ec-page-bg)/0.55)] hover:text-[rgb(var(--ec-accent))]"
+                    >
+                      <ServerIcon className="h-3.5 w-3.5 flex-shrink-0 text-[rgb(var(--ec-page-text-muted))]" />
+                      {serviceName}
+                    </a>
+                  );
+                })}
+              </div>
+            </div>
+          )}
+
+          {/* Owners section */}
+          {showOwners && owners.length > 0 && (
+            <div className={sidebarCardClass}>
+              <div className="mb-3 flex items-center justify-between gap-3">
+                <h3 className="text-[0.8rem] font-semibold text-[rgb(var(--ec-page-text))]">Owners</h3>
+              </div>
+              <div className="space-y-1">
+                {owners.map((owner: Owner, idx: number) => (
+                  <a
+                    key={`${owner.id}-${idx}`}
+                    href={owner.href}
+                    className="block rounded-lg px-2 py-1.5 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] transition-colors hover:bg-[rgb(var(--ec-page-bg)/0.55)] hover:text-[rgb(var(--ec-accent))]"
+                  >
+                    {owner.name}
+                  </a>
+                ))}
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Modals */}
+      <VersionHistoryModal
+        isOpen={isDiffModalOpen}
+        onOpenChange={setIsDiffModalOpen}
+        diffs={selectedDiffs}
+        messageName={message.data.name}
+        apiAccessEnabled={apiAccessEnabled}
+      />
+      <SchemaCodeModal
+        isOpen={isCodeModalOpen}
+        onOpenChange={setIsCodeModalOpen}
+        message={message}
+        onCopy={handleCopy}
+        isCopied={isCopied}
+      />
+      <SchemaViewerModal
+        isOpen={isSchemaViewerModalOpen}
+        onOpenChange={setIsSchemaViewerModalOpen}
+        message={message}
+        parsedSchema={parsedSchema}
+        parsedAvroSchema={parsedAvroSchema}
+        parsedProtoSchema={parsedProtoSchema}
+      />
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaExplorer.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaExplorer.tsx
new file mode 100644
index 000000000..7bf584cb4
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaExplorer.tsx
@@ -0,0 +1,614 @@
+import { useState, useMemo, useEffect, useRef } from 'react';
+import { AdjustmentsHorizontalIcon, DocumentTextIcon, MagnifyingGlassIcon } from '@heroicons/react/24/outline';
+import type { CollectionMessageTypes } from '@types';
+import semver from 'semver';
+import SchemaListItem from './SchemaListItem';
+import SchemaDetailsPanel from './SchemaDetailsPanel';
+import Pagination from './Pagination';
+import type { SchemaItem } from './types';
+
+// Specification file types (OpenAPI, AsyncAPI, GraphQL)
+const SPEC_TYPES = ['openapi', 'asyncapi', 'graphql'];
+const HIDDEN_FORMAT_FILTERS = new Set(['graphql', 'gql', 'yaml', 'yml']);
+const SCHEMA_TYPE_LABELS: Record<string, string> = {
+  json: 'JSON Schema',
+  asyncapi: 'AsyncAPI',
+  openapi: 'OpenAPI',
+  graphql: 'GraphQL',
+  avro: 'Avro',
+  avsc: 'Avro',
+  proto: 'Protobuf',
+  protobuf: 'Protobuf',
+  yaml: 'YAML',
+  yml: 'YAML',
+  xml: 'XML',
+  xsd: 'XML Schema',
+};
+
+/** Resolve the spec filename for a schema item, with consistent fallback. */
+function getSpecFile(item: SchemaItem): string {
+  return item.specFilenameWithoutExtension || item.specName || '';
+}
+
+/**
+ * Build a unique group key for a schema item.
+ * For services, includes spec type and filename to disambiguate
+ * multiple specs of the same type (e.g. two OpenAPI specs).
+ */
+function getGroupKey(item: SchemaItem): string {
+  if (item.collection === 'services') {
+    return `${item.data.id}__${item.specType || 'unknown'}__${getSpecFile(item)}`;
+  }
+  return item.data.id;
+}
+
+interface SchemaExplorerProps {
+  schemas: SchemaItem[];
+  apiAccessEnabled?: boolean;
+}
+
+export default function SchemaExplorer({ schemas, apiAccessEnabled = false }: SchemaExplorerProps) {
+  const [searchQuery, setSearchQuery] = useState(() => {
+    if (typeof window !== 'undefined') {
+      const stored = localStorage.getItem('schemaRegistrySearchQuery');
+      return stored !== null ? stored : '';
+    }
+    return '';
+  });
+
+  const [selectedTypes, setSelectedTypes] = useState<Set<CollectionMessageTypes | 'specifications' | 'data-contracts'>>(() => {
+    if (typeof window !== 'undefined') {
+      const stored = localStorage.getItem('schemaRegistrySelectedTypes');
+      if (stored) {
+        try {
+          const parsed = JSON.parse(stored);
+          return new Set(parsed);
+        } catch {
+          return new Set();
+        }
+      }
+    }
+    return new Set();
+  });
+
+  const [selectedSchemaType, setSelectedSchemaType] = useState<'all' | string>(() => {
+    if (typeof window !== 'undefined') {
+      const stored = localStorage.getItem('schemaRegistrySelectedSchemaType');
+      return stored !== null ? stored : 'all';
+    }
+    return 'all';
+  });
+
+  const [showFormatFilters, setShowFormatFilters] = useState(() => {
+    if (typeof window !== 'undefined') {
+      const storedSchemaType = localStorage.getItem('schemaRegistrySelectedSchemaType');
+      if (storedSchemaType !== null && storedSchemaType !== 'all') return true;
+      const storedTypes = localStorage.getItem('schemaRegistrySelectedTypes');
+      if (storedTypes) {
+        try {
+          return JSON.parse(storedTypes).length > 0;
+        } catch {
+          return false;
+        }
+      }
+    }
+    return false;
+  });
+
+  const [selectedMessage, setSelectedMessage] = useState<SchemaItem | null>(null);
+  const [selectedVersion, setSelectedVersion] = useState<string | null>(null);
+  const [currentPage, setCurrentPage] = useState(1);
+  const selectedItemRef = useRef<HTMLButtonElement>(null);
+  const searchInputRef = useRef<HTMLInputElement>(null);
+  const ITEMS_PER_PAGE = 50;
+
+  const updateUrlParams = (message: SchemaItem) => {
+    if (typeof window === 'undefined') return;
+
+    const params = new URLSearchParams();
+    params.set('id', message.data.id);
+    params.set('version', message.data.version);
+    params.set('collection', message.collection);
+
+    if (message.collection === 'services') {
+      params.set('specType', message.specType || 'unknown');
+      const specFile = getSpecFile(message);
+      if (specFile) {
+        params.set('specFilename', specFile);
+      }
+    }
+
+    const newUrl = `${window.location.pathname}?${params.toString()}`;
+    window.history.pushState({}, '', newUrl);
+  };
+
+  const messagesByIdAndVersions = useMemo(() => {
+    const grouped = new Map<string, SchemaItem[]>();
+
+    schemas.forEach((message) => {
+      const groupKey = getGroupKey(message);
+      const existing = grouped.get(groupKey);
+      if (existing) {
+        existing.push(message);
+      } else {
+        grouped.set(groupKey, [message]);
+      }
+    });
+
+    grouped.forEach((versions, id) => {
+      versions.sort((a, b) => {
+        const aVersion = a.data.version;
+        const bVersion = b.data.version;
+        const aValid = semver.valid(semver.coerce(aVersion));
+        const bValid = semver.valid(semver.coerce(bVersion));
+
+        if (aValid && bValid) {
+          return semver.rcompare(aValid, bValid);
+        }
+
+        const aNum = parseFloat(aVersion);
+        const bNum = parseFloat(bVersion);
+        if (!isNaN(aNum) && !isNaN(bNum)) {
+          return bNum - aNum;
+        }
+
+        return bVersion.localeCompare(aVersion);
+      });
+
+      grouped.set(id, versions);
+    });
+
+    return grouped;
+  }, [schemas]);
+
+  const latestMessages = useMemo(() => {
+    return Array.from(messagesByIdAndVersions.values()).map((versions) => versions[0]);
+  }, [messagesByIdAndVersions]);
+
+  const schemaTypes = useMemo(() => {
+    const types = new Set<string>();
+    latestMessages.forEach((msg) => {
+      if (msg.schemaExtension && !HIDDEN_FORMAT_FILTERS.has(msg.schemaExtension.toLowerCase())) {
+        types.add(msg.schemaExtension.toLowerCase());
+      }
+    });
+    return Array.from(types).sort();
+  }, [latestMessages]);
+
+  const filteredMessages = useMemo(() => {
+    let result = [...latestMessages];
+
+    if (selectedTypes.size > 0) {
+      result = result.filter((msg) => {
+        if (selectedTypes.has(msg.collection as CollectionMessageTypes)) {
+          return true;
+        }
+        if (selectedTypes.has('specifications') && SPEC_TYPES.includes(msg.schemaExtension?.toLowerCase() || '')) {
+          return true;
+        }
+        if (selectedTypes.has('data-contracts') && msg.collection === 'data-products') {
+          return true;
+        }
+        return false;
+      });
+    }
+
+    if (selectedSchemaType !== 'all') {
+      result = result.filter((msg) => msg.schemaExtension?.toLowerCase() === selectedSchemaType);
+    }
+
+    if (searchQuery) {
+      const query = searchQuery.toLowerCase();
+      result = result.filter(
+        (msg) =>
+          msg.data.name?.toLowerCase().includes(query) ||
+          msg.data.summary?.toLowerCase().includes(query) ||
+          msg.data.id?.toLowerCase().includes(query)
+      );
+    }
+
+    result.sort((a, b) => {
+      const nameA = a.data.name?.toLowerCase() || '';
+      const nameB = b.data.name?.toLowerCase() || '';
+      return nameA.localeCompare(nameB);
+    });
+
+    return result;
+  }, [latestMessages, searchQuery, selectedTypes, selectedSchemaType]);
+
+  const totalPages = Math.ceil(filteredMessages.length / ITEMS_PER_PAGE);
+  const paginatedMessages = useMemo(() => {
+    const startIndex = (currentPage - 1) * ITEMS_PER_PAGE;
+    return filteredMessages.slice(startIndex, startIndex + ITEMS_PER_PAGE);
+  }, [filteredMessages, currentPage]);
+
+  useEffect(() => {
+    setCurrentPage(1);
+  }, [searchQuery, selectedTypes, selectedSchemaType]);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const params = new URLSearchParams(window.location.search);
+    const id = params.get('id');
+    const version = params.get('version');
+    const collection = params.get('collection');
+    const specType = params.get('specType');
+    const specFilename = params.get('specFilename');
+
+    if (id && version) {
+      const matchingMessage = schemas.find((msg) => {
+        const idMatch = msg.data.id === id;
+        const versionMatch = msg.data.version === version;
+        const collectionMatch = !collection || msg.collection === collection;
+
+        if (msg.collection === 'services') {
+          const specTypeMatch = !specType || msg.specType === specType;
+          const msgSpecFile = getSpecFile(msg);
+          const specFilenameMatch = !specFilename || msgSpecFile === specFilename;
+          return idMatch && versionMatch && collectionMatch && specTypeMatch && specFilenameMatch;
+        }
+
+        return idMatch && versionMatch && collectionMatch;
+      });
+
+      if (matchingMessage) {
+        setSelectedMessage(matchingMessage);
+        setSelectedVersion(matchingMessage.data.version);
+
+        setTimeout(() => {
+          if (selectedItemRef.current) {
+            selectedItemRef.current.scrollIntoView({ behavior: 'smooth', block: 'center' });
+          }
+        }, 100);
+      }
+    }
+  }, [schemas]);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const params = new URLSearchParams(window.location.search);
+    const hasQueryParams = params.has('id');
+
+    if (filteredMessages.length > 0 && !selectedMessage && !hasQueryParams) {
+      const firstMessage = filteredMessages[0];
+      setSelectedMessage(firstMessage);
+      setSelectedVersion(firstMessage.data.version);
+    }
+  }, [filteredMessages, selectedMessage]);
+
+  const displayMessage = useMemo(() => {
+    if (!selectedMessage) return null;
+
+    const groupKey = getGroupKey(selectedMessage);
+    const versions = messagesByIdAndVersions.get(groupKey);
+
+    if (!versions) return selectedMessage;
+    if (!selectedVersion) return versions[0];
+
+    const versionedMessage = versions.find((v) => v.data.version === selectedVersion);
+    return versionedMessage || versions[0];
+  }, [selectedMessage, selectedVersion, messagesByIdAndVersions]);
+
+  useEffect(() => {
+    if (typeof window !== 'undefined') {
+      localStorage.setItem('schemaRegistrySearchQuery', searchQuery);
+    }
+  }, [searchQuery]);
+
+  useEffect(() => {
+    if (typeof window !== 'undefined') {
+      localStorage.setItem('schemaRegistrySelectedTypes', JSON.stringify(Array.from(selectedTypes)));
+    }
+  }, [selectedTypes]);
+
+  useEffect(() => {
+    if (typeof window !== 'undefined') {
+      localStorage.setItem('schemaRegistrySelectedSchemaType', selectedSchemaType);
+    }
+  }, [selectedSchemaType]);
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault();
+        searchInputRef.current?.focus();
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, []);
+
+  const availableVersions = useMemo(() => {
+    if (!displayMessage) return [];
+    const groupKey = getGroupKey(displayMessage);
+    return messagesByIdAndVersions.get(groupKey) || [displayMessage];
+  }, [displayMessage, messagesByIdAndVersions]);
+
+  const selectedGroupKey = useMemo(() => (selectedMessage ? getGroupKey(selectedMessage) : null), [selectedMessage]);
+
+  const handleVersionChange = (newVersion: string) => {
+    setSelectedVersion(newVersion);
+    const versionedMessage = availableVersions.find((v) => v.data.version === newVersion);
+    if (versionedMessage) {
+      updateUrlParams(versionedMessage);
+    }
+  };
+
+  const stats = useMemo(() => {
+    return {
+      total: latestMessages.length,
+      events: latestMessages.filter((m) => m.collection === 'events').length,
+      commands: latestMessages.filter((m) => m.collection === 'commands').length,
+      queries: latestMessages.filter((m) => m.collection === 'queries').length,
+      specifications: latestMessages.filter((m) => SPEC_TYPES.includes(m.schemaExtension?.toLowerCase() || '')).length,
+      dataContracts: latestMessages.filter((m) => m.collection === 'data-products').length,
+    };
+  }, [latestMessages]);
+
+  const toggleType = (type: CollectionMessageTypes | 'specifications' | 'data-contracts') => {
+    setSelectedTypes((prev) => {
+      const next = new Set(prev);
+      if (next.has(type)) {
+        next.delete(type);
+      } else {
+        next.add(type);
+      }
+      return next;
+    });
+  };
+
+  const clearTypeFilters = () => {
+    setSelectedTypes(new Set());
+  };
+
+  const hasActiveFilters = searchQuery.length > 0 || selectedTypes.size > 0 || selectedSchemaType !== 'all';
+  const activeFilterCount = (selectedTypes.size > 0 ? 1 : 0) + (selectedSchemaType !== 'all' ? 1 : 0);
+  const collectionTabs = [
+    { key: 'all', label: 'All', count: stats.total },
+    { key: 'events', label: 'Events', count: stats.events },
+    { key: 'commands', label: 'Commands', count: stats.commands },
+    { key: 'queries', label: 'Queries', count: stats.queries },
+    { key: 'specifications', label: 'Specs', count: stats.specifications },
+    { key: 'data-contracts', label: 'Contracts', count: stats.dataContracts },
+  ].filter((tab) => tab.count > 0);
+
+  return (
+    <div className="flex h-full min-h-0 flex-col overflow-hidden">
+      <style
+        dangerouslySetInnerHTML={{
+          __html: '[data-theme="dark"] .schema-icon { filter: brightness(1.8) saturate(0.8); }',
+        }}
+      />
+      <div className="flex flex-1 min-h-0 gap-0 overflow-hidden">
+        <div
+          className="fixed top-0 z-20 flex h-screen flex-col overflow-hidden border-r border-[rgb(var(--ec-page-border))] bg-linear-to-b from-[rgb(var(--ec-page-bg))] via-[rgb(var(--ec-page-bg))] to-[rgb(var(--ec-accent)/0.06)]"
+          style={{ left: 'var(--ec-vertical-nav-width)', width: 'var(--ec-schema-sidebar-width, 360px)' }}
+        >
+          <div className="flex h-[60px] flex-shrink-0 items-center justify-between gap-2 border-b border-[rgb(var(--ec-page-border))] px-4">
+            <div className="relative min-w-0 flex-1">
+              <div className="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
+                <MagnifyingGlassIcon className="h-4 w-4 text-[rgb(var(--ec-icon-color))]" />
+              </div>
+              <input
+                ref={searchInputRef}
+                type="text"
+                placeholder="Search schemas..."
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                className="w-full rounded-lg border border-[rgb(var(--ec-dropdown-border))] bg-[rgb(var(--ec-dropdown-bg))] py-2 pl-9 pr-3 text-[12px] text-[rgb(var(--ec-page-text))] placeholder:text-[rgb(var(--ec-icon-color))] transition-all focus:border-[rgb(var(--ec-accent))] focus:outline-hidden focus:ring-1 focus:ring-[rgb(var(--ec-accent)/0.3)]"
+              />
+            </div>
+
+            {schemaTypes.length > 0 && (
+              <button
+                onClick={() => setShowFormatFilters((prev) => !prev)}
+                aria-pressed={showFormatFilters}
+                className={`relative inline-flex h-9 w-9 items-center justify-center rounded-lg border transition-all ${
+                  showFormatFilters || activeFilterCount > 0
+                    ? 'border-[rgb(var(--ec-accent)/0.5)] bg-[rgb(var(--ec-accent))] text-white shadow-[0_10px_28px_rgb(var(--ec-accent)/0.3)]'
+                    : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg))] text-[rgb(var(--ec-page-text-muted))] hover:border-[rgb(var(--ec-page-text-muted)/0.45)] hover:text-[rgb(var(--ec-page-text))]'
+                }`}
+              >
+                <AdjustmentsHorizontalIcon className="h-4.5 w-4.5" />
+                {activeFilterCount > 0 && (
+                  <span className="absolute -right-1 -top-1 inline-flex h-5 min-w-5 items-center justify-center rounded-full border border-[rgb(var(--ec-page-bg))] bg-[rgb(var(--ec-page-text))] px-1 text-[10px] font-semibold tabular-nums text-[rgb(var(--ec-page-bg))]">
+                    {activeFilterCount}
+                  </span>
+                )}
+              </button>
+            )}
+          </div>
+
+          {showFormatFilters && latestMessages.length > 0 && (
+            <div className="flex-shrink-0 border-b border-[rgb(var(--ec-page-border))] px-4 py-3">
+              <div className="rounded-xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover)/0.45)] p-3">
+                <div className="mb-3 flex items-center justify-between gap-3">
+                  <span className="text-[11px] font-semibold uppercase tracking-[0.2em] text-[rgb(var(--ec-page-text-muted))]">
+                    Filters
+                  </span>
+                  {hasActiveFilters && (
+                    <button
+                      onClick={() => {
+                        setSearchQuery('');
+                        clearTypeFilters();
+                        setSelectedSchemaType('all');
+                      }}
+                      className="text-[11px] font-medium text-[rgb(var(--ec-accent))] hover:opacity-80"
+                    >
+                      Reset
+                    </button>
+                  )}
+                </div>
+
+                <div>
+                  <div className="mb-2 text-[10px] font-semibold uppercase tracking-[0.18em] text-[rgb(var(--ec-page-text-muted))]">
+                    Type
+                  </div>
+                  <div className="flex flex-wrap gap-1.5">
+                    {collectionTabs.map((tab) => {
+                      const isAll = tab.key === 'all';
+                      const isActive = isAll ? selectedTypes.size === 0 : selectedTypes.has(tab.key as CollectionMessageTypes);
+
+                      return (
+                        <button
+                          key={tab.key}
+                          onClick={() => {
+                            if (isAll) {
+                              clearTypeFilters();
+                              return;
+                            }
+                            toggleType(tab.key as CollectionMessageTypes | 'specifications' | 'data-contracts');
+                          }}
+                          className={`inline-flex items-center gap-1 rounded-md border px-2 py-1 text-[10px] font-medium transition-all ${
+                            isActive
+                              ? 'border-[rgb(var(--ec-accent)/0.5)] bg-[rgb(var(--ec-accent)/0.16)] text-[rgb(var(--ec-page-text))] shadow-[0_0_0_1px_rgb(var(--ec-accent)/0.2)]'
+                              : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg))] text-[rgb(var(--ec-page-text-muted))] hover:border-[rgb(var(--ec-page-text-muted)/0.3)] hover:text-[rgb(var(--ec-page-text))]'
+                          }`}
+                        >
+                          <span>{tab.label}</span>
+                          <span
+                            className={`rounded-sm px-1 py-0.5 text-[8px] font-semibold tabular-nums ${
+                              isActive
+                                ? 'bg-[rgb(var(--ec-accent)/0.18)] text-[rgb(var(--ec-page-text))]'
+                                : 'bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-page-text-muted))]'
+                            }`}
+                          >
+                            {tab.count}
+                          </span>
+                        </button>
+                      );
+                    })}
+                  </div>
+                </div>
+
+                {schemaTypes.length > 0 && (
+                  <div className="mt-3">
+                    <div className="mb-2 flex items-center justify-between gap-3">
+                      <span className="text-[10px] font-semibold uppercase tracking-[0.18em] text-[rgb(var(--ec-page-text-muted))]">
+                        Format
+                      </span>
+                      {selectedSchemaType !== 'all' && (
+                        <button
+                          onClick={() => setSelectedSchemaType('all')}
+                          className="text-[10px] font-medium text-[rgb(var(--ec-accent))] hover:opacity-80"
+                        >
+                          Clear
+                        </button>
+                      )}
+                    </div>
+                    <div className="flex flex-wrap gap-1.5">
+                      <button
+                        onClick={() => setSelectedSchemaType('all')}
+                        className={`rounded-md border px-2 py-1 text-[10px] font-medium transition-all ${
+                          selectedSchemaType === 'all'
+                            ? 'border-[rgb(var(--ec-accent)/0.45)] bg-[rgb(var(--ec-accent)/0.16)] text-[rgb(var(--ec-page-text))]'
+                            : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg))] text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]'
+                        }`}
+                      >
+                        All formats
+                      </button>
+                      {schemaTypes.map((type) => (
+                        <button
+                          key={type}
+                          onClick={() => setSelectedSchemaType(selectedSchemaType === type ? 'all' : type)}
+                          className={`rounded-md border px-2 py-1 text-[10px] font-medium transition-all ${
+                            selectedSchemaType === type
+                              ? 'border-[rgb(var(--ec-accent)/0.45)] bg-[rgb(var(--ec-accent)/0.16)] text-[rgb(var(--ec-page-text))]'
+                              : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg))] text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]'
+                          }`}
+                        >
+                          {SCHEMA_TYPE_LABELS[type] || type.charAt(0).toUpperCase() + type.slice(1)}
+                        </button>
+                      ))}
+                    </div>
+                  </div>
+                )}
+              </div>
+            </div>
+          )}
+
+          <div className="flex-1 overflow-y-auto px-3 py-3">
+            {paginatedMessages.length > 0 ? (
+              <div className="space-y-3">
+                {paginatedMessages.map((message) => {
+                  const groupKey = getGroupKey(message);
+                  const isSelected = selectedGroupKey === groupKey;
+                  const versions = messagesByIdAndVersions.get(groupKey) || [message];
+
+                  return (
+                    <SchemaListItem
+                      key={groupKey}
+                      message={message}
+                      isSelected={isSelected}
+                      versions={versions}
+                      onClick={() => {
+                        setSelectedMessage(message);
+                        setSelectedVersion(message.data.version);
+                        updateUrlParams(message);
+                      }}
+                      itemRef={isSelected ? selectedItemRef : undefined}
+                    />
+                  );
+                })}
+              </div>
+            ) : (
+              <div className="flex h-full flex-col items-center justify-center rounded-[1.5rem] border border-dashed border-[rgb(var(--ec-page-border))] p-8 text-center">
+                <div className="mb-4 flex h-12 w-12 items-center justify-center rounded-2xl bg-[rgb(var(--ec-content-hover))]">
+                  <MagnifyingGlassIcon className="h-5 w-5 text-[rgb(var(--ec-icon-color))]" />
+                </div>
+                <h3 className="mb-1 text-sm font-semibold text-[rgb(var(--ec-page-text))]">No schemas found</h3>
+                <p className="mb-4 max-w-[220px] text-sm leading-relaxed text-[rgb(var(--ec-page-text-muted))]">
+                  {searchQuery ? `No results for "${searchQuery}"` : 'Try adjusting your filters'}
+                </p>
+                {hasActiveFilters && (
+                  <button
+                    onClick={() => {
+                      setSearchQuery('');
+                      clearTypeFilters();
+                      setSelectedSchemaType('all');
+                    }}
+                    className="text-sm font-medium text-[rgb(var(--ec-accent))] hover:underline"
+                  >
+                    Clear filters
+                  </button>
+                )}
+              </div>
+            )}
+          </div>
+
+          <Pagination currentPage={currentPage} totalPages={totalPages} onPageChange={setCurrentPage} />
+        </div>
+
+        <div
+          className="flex-1 min-h-0 min-w-0 overflow-hidden bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))]"
+          style={{ marginLeft: 'var(--ec-schema-sidebar-width, 360px)' }}
+        >
+          {displayMessage ? (
+            <SchemaDetailsPanel
+              message={displayMessage}
+              availableVersions={availableVersions}
+              selectedVersion={selectedVersion}
+              onVersionChange={handleVersionChange}
+              apiAccessEnabled={apiAccessEnabled}
+            />
+          ) : (
+            <div className="flex h-full items-center justify-center">
+              <div className="max-w-xs text-center">
+                <div className="mx-auto mb-4 flex h-14 w-14 items-center justify-center rounded-2xl bg-[rgb(var(--ec-content-hover))]">
+                  <DocumentTextIcon className="h-7 w-7 text-[rgb(var(--ec-icon-color))]" />
+                </div>
+                <h3 className="mb-1 text-base font-semibold text-[rgb(var(--ec-page-text))]">Select a schema</h3>
+                <p className="text-sm leading-relaxed text-[rgb(var(--ec-page-text-muted))]">
+                  Choose a schema from the list to view details, compare versions, and access raw code
+                </p>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaFilters.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaFilters.tsx
new file mode 100644
index 000000000..987bef94e
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaFilters.tsx
@@ -0,0 +1,112 @@
+import { AdjustmentsHorizontalIcon, ChevronUpIcon, ChevronDownIcon } from '@heroicons/react/24/outline';
+import { buildUrl } from '@utils/url-builder';
+import { getSchemaTypeLabel } from './utils';
+import type { SchemaItem } from './types';
+
+interface SchemaFiltersProps {
+  selectedSchemaType: string;
+  onSchemaTypeChange: (type: string) => void;
+  schemaTypes: string[];
+  latestMessages: SchemaItem[];
+  filtersExpanded: boolean;
+  onToggleExpanded: () => void;
+  isMounted: boolean;
+}
+
+export default function SchemaFilters({
+  selectedSchemaType,
+  onSchemaTypeChange,
+  schemaTypes,
+  latestMessages,
+  filtersExpanded,
+  onToggleExpanded,
+  isMounted,
+}: SchemaFiltersProps) {
+  const hasActiveFilters = selectedSchemaType !== 'all';
+
+  // Only show this component if there are schema types to filter
+  if (schemaTypes.length <= 1) {
+    return null;
+  }
+
+  return (
+    <div className="flex-shrink-0 border-b border-gray-100 bg-white">
+      {/* Filter Header */}
+      <button
+        onClick={onToggleExpanded}
+        className="w-full flex items-center justify-between px-3 py-1.5 hover:bg-gray-50 transition-colors"
+      >
+        <div className="flex items-center gap-1.5">
+          <AdjustmentsHorizontalIcon className="h-3.5 w-3.5 text-gray-400" />
+          <span className="text-[11px] font-medium text-gray-600">Format</span>
+          {hasActiveFilters && (
+            <span className="inline-flex items-center justify-center w-4 h-4 rounded-full bg-gray-900 text-[10px] font-medium text-white">
+              1
+            </span>
+          )}
+        </div>
+        {filtersExpanded ? (
+          <ChevronUpIcon className="h-3.5 w-3.5 text-gray-400" />
+        ) : (
+          <ChevronDownIcon className="h-3.5 w-3.5 text-gray-400" />
+        )}
+      </button>
+
+      {/* Collapsible Filter Content */}
+      {isMounted && filtersExpanded && (
+        <div className="px-3 pb-2">
+          {/* Schema Format Filter as chips */}
+          <div className="flex flex-wrap gap-1">
+            <button
+              onClick={() => onSchemaTypeChange('all')}
+              className={`inline-flex items-center px-2 py-0.5 rounded text-[11px] font-medium transition-all ${
+                selectedSchemaType === 'all'
+                  ? 'bg-gray-900 text-white'
+                  : 'bg-gray-50 text-gray-600 border border-gray-200 hover:bg-gray-100'
+              }`}
+            >
+              All
+            </button>
+            {schemaTypes.map((type) => {
+              const count = latestMessages.filter((m) => m.schemaExtension?.toLowerCase() === type).length;
+              const ext = type.toLowerCase();
+              const hasIcon = ['openapi', 'asyncapi', 'graphql', 'avro', 'json', 'proto'].includes(ext);
+              const iconName = ext === 'json' ? 'json-schema' : ext;
+
+              return (
+                <button
+                  key={type}
+                  onClick={() => onSchemaTypeChange(type)}
+                  className={`inline-flex items-center gap-1 px-2 py-0.5 rounded text-[11px] font-medium transition-all ${
+                    selectedSchemaType === type
+                      ? 'bg-gray-900 text-white'
+                      : 'bg-gray-50 text-gray-600 border border-gray-200 hover:bg-gray-100'
+                  }`}
+                >
+                  {hasIcon && (
+                    <img
+                      src={buildUrl(`/icons/${iconName}.svg`, true)}
+                      alt={`${type} icon`}
+                      className={`h-3 w-3 ${selectedSchemaType === type ? 'brightness-0 invert' : 'opacity-60'}`}
+                    />
+                  )}
+                  {getSchemaTypeLabel(type)}
+                  <span className={`text-[10px] tabular-nums ${selectedSchemaType === type ? 'text-white/60' : 'text-gray-400'}`}>
+                    {count}
+                  </span>
+                </button>
+              );
+            })}
+          </div>
+
+          {/* Clear filter */}
+          {hasActiveFilters && (
+            <button onClick={() => onSchemaTypeChange('all')} className="mt-1.5 text-[11px] text-gray-500 hover:text-gray-700">
+              Clear
+            </button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaListItem.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaListItem.tsx
new file mode 100644
index 000000000..1b23c98e7
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaListItem.tsx
@@ -0,0 +1,101 @@
+import { buildUrl } from '@utils/url-builder';
+import type { SchemaItem } from './types';
+import { getSchemaTypeLabel, ICON_SPECS, getFormatBadge, extractServiceName } from './utils';
+
+interface SchemaListItemProps {
+  message: SchemaItem;
+  isSelected: boolean;
+  versions: SchemaItem[];
+  onClick: () => void;
+  itemRef?: React.Ref<HTMLButtonElement>;
+}
+
+function getNamespace(message: SchemaItem): string | null {
+  const producers = message.data.producers || [];
+  const firstProducer = producers[0];
+
+  if (firstProducer) {
+    const serviceName = extractServiceName(firstProducer.id);
+    return serviceName;
+  }
+
+  if (message.collection === 'services' && message.specType) {
+    return `${message.specType} specification`;
+  }
+
+  if (message.collection === 'data-products' && message.dataProductId) {
+    return extractServiceName(message.dataProductId);
+  }
+
+  return null;
+}
+
+export default function SchemaListItem({ message, isSelected, versions, onClick, itemRef }: SchemaListItemProps) {
+  const ext = message.schemaExtension?.toLowerCase() || '';
+  const iconSpec = ICON_SPECS[ext];
+  const { label: formatLabel, color: formatColor } = getFormatBadge(ext);
+  const namespace = getNamespace(message);
+  const summary = message.data.summary || `Browse the ${message.data.name} schema.`;
+  const versionLabel = `v${message.data.version}`;
+
+  return (
+    <button
+      ref={itemRef}
+      onClick={onClick}
+      className={`group w-full rounded-lg border px-2.5 py-2 text-left transition-all duration-150 ${
+        isSelected
+          ? 'border-[rgb(var(--ec-accent)/0.55)] bg-[rgb(var(--ec-accent)/0.1)] shadow-[0_0_0_1px_rgb(var(--ec-accent)/0.3),0_18px_40px_rgb(var(--ec-accent)/0.12)]'
+          : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg)/0.66)] hover:border-[rgb(var(--ec-page-text-muted)/0.3)] hover:bg-[rgb(var(--ec-content-hover)/0.5)]'
+      }`}
+    >
+      <div className="flex items-start justify-between gap-2">
+        <div className="mt-0.5 flex h-4.5 w-4.5 flex-shrink-0 items-center justify-center rounded-sm border border-[rgb(var(--ec-page-border)/0.55)] bg-[rgb(var(--ec-content-hover))]">
+          {iconSpec ? (
+            <img src={buildUrl(`/icons/${iconSpec}.svg`, true)} alt={`${ext} icon`} className="schema-icon h-2.5 w-2.5" />
+          ) : (
+            <span className={`font-mono text-[6px] font-bold uppercase ${formatColor}`}>{formatLabel}</span>
+          )}
+        </div>
+
+        <div className="min-w-0 flex-1">
+          <div className="flex items-start justify-between gap-2">
+            <h3 className="min-w-0 pr-1 text-[11px] font-semibold leading-4 text-[rgb(var(--ec-page-text))] break-words">
+              {message.data.name}
+            </h3>
+            <span
+              className={`mt-0.5 flex-shrink-0 rounded-sm border px-1.5 py-0.5 font-mono text-[8px] font-semibold tabular-nums ${
+                isSelected
+                  ? 'border-[rgb(var(--ec-accent)/0.35)] bg-[rgb(var(--ec-accent)/0.15)] text-[rgb(var(--ec-page-text))]'
+                  : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-page-text-muted))]'
+              }`}
+            >
+              {versionLabel}
+            </span>
+          </div>
+        </div>
+      </div>
+
+      <p className="mt-1.5 text-[10px] leading-4 text-[rgb(var(--ec-page-text-muted))] line-clamp-2">{summary}</p>
+
+      <div className="mt-1.5 flex items-end justify-between gap-2">
+        <div className="min-w-0">
+          <div className="flex flex-wrap items-center gap-x-1.5 gap-y-0.5 text-[9px] text-[rgb(var(--ec-page-text-muted))]">
+            <span className="font-medium text-[rgb(var(--ec-page-text-muted))]">
+              {getSchemaTypeLabel(message.schemaExtension)}
+            </span>
+            {namespace && (
+              <>
+                <span className="opacity-35">&rsaquo;</span>
+                <span className="truncate">{namespace}</span>
+              </>
+            )}
+          </div>
+        </div>
+
+        <span className="flex-shrink-0 text-[9px] font-medium tabular-nums text-[rgb(var(--ec-page-text-muted))]">
+          {versions.length}
+        </span>
+      </div>
+    </button>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaPageViewer.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaPageViewer.tsx
new file mode 100644
index 000000000..fd6cddce8
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaPageViewer.tsx
@@ -0,0 +1,37 @@
+import SchemaDetailsPanel from './SchemaDetailsPanel';
+import type { SchemaItem } from './types';
+
+interface SchemaPageViewerProps {
+  message: SchemaItem;
+  availableVersions: SchemaItem[];
+  apiAccessEnabled?: boolean;
+  showOwners?: boolean;
+  showProducersConsumers?: boolean;
+}
+
+export default function SchemaPageViewer({
+  message,
+  availableVersions,
+  apiAccessEnabled = false,
+  showOwners = true,
+  showProducersConsumers = true,
+}: SchemaPageViewerProps) {
+  const handleVersionChange = (version: string) => {
+    // Construct new URL
+    // URL: /schemas/[collection]/[id]/[version]
+    const url = `/schemas/${message.collection}/${message.data.id}/${version}`;
+    window.location.href = url;
+  };
+
+  return (
+    <SchemaDetailsPanel
+      message={message}
+      availableVersions={availableVersions}
+      selectedVersion={message.data.version}
+      onVersionChange={handleVersionChange}
+      apiAccessEnabled={apiAccessEnabled}
+      showOwners={showOwners}
+      showProducersConsumers={showProducersConsumers}
+    />
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaViewerModal.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaViewerModal.tsx
new file mode 100644
index 000000000..1d3e5cbed
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/SchemaViewerModal.tsx
@@ -0,0 +1,83 @@
+import * as Dialog from '@radix-ui/react-dialog';
+import { XMarkIcon, ArrowsPointingOutIcon } from '@heroicons/react/24/outline';
+import JSONSchemaViewer from './JSONSchemaViewer';
+import AvroSchemaViewer from './AvroSchemaViewer';
+import ProtobufSchemaViewer from './ProtobufSchemaViewer';
+import type { SchemaItem } from './types';
+
+interface SchemaViewerModalProps {
+  isOpen: boolean;
+  onOpenChange: (open: boolean) => void;
+  message: SchemaItem;
+  parsedSchema: any;
+  parsedAvroSchema?: any;
+  parsedProtoSchema?: any;
+}
+
+export default function SchemaViewerModal({
+  isOpen,
+  onOpenChange,
+  message,
+  parsedSchema,
+  parsedAvroSchema,
+  parsedProtoSchema,
+}: SchemaViewerModalProps) {
+  if (!parsedSchema && !parsedAvroSchema && !parsedProtoSchema) return null;
+
+  const isAvro = !!parsedAvroSchema;
+  const isProto = !!parsedProtoSchema;
+
+  return (
+    <Dialog.Root open={isOpen} onOpenChange={onOpenChange}>
+      <Dialog.Portal>
+        <Dialog.Overlay className="fixed inset-0 bg-black/50 data-[state=open]:animate-overlayShow z-50" />
+        <Dialog.Content className="fixed inset-4 md:inset-8 rounded-lg bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] shadow-xl focus:outline-hidden data-[state=open]:animate-contentShow z-[100] flex flex-col">
+          {/* Header */}
+          <div className="flex items-center justify-between p-6 border-b border-[rgb(var(--ec-page-border))] flex-shrink-0">
+            <div className="flex items-center gap-3">
+              <ArrowsPointingOutIcon className="h-6 w-6 text-[rgb(var(--ec-icon-color))]" />
+              <div>
+                <Dialog.Title className="text-xl font-semibold text-[rgb(var(--ec-page-text))]">{message.data.name}</Dialog.Title>
+                <Dialog.Description className="text-sm text-[rgb(var(--ec-page-text-muted))] mt-1">
+                  v{message.data.version} · {isAvro ? 'Avro' : isProto ? 'Protobuf' : 'JSON'} Schema
+                </Dialog.Description>
+              </div>
+            </div>
+            <Dialog.Close asChild>
+              <button
+                type="button"
+                className="p-2 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] rounded-md transition-colors"
+                aria-label="Close"
+              >
+                <XMarkIcon className="h-6 w-6" />
+              </button>
+            </Dialog.Close>
+          </div>
+
+          {/* Content */}
+          <div className="flex-1 overflow-hidden p-6">
+            {isAvro ? (
+              <AvroSchemaViewer schema={parsedAvroSchema} expand={true} search={true} />
+            ) : isProto ? (
+              <ProtobufSchemaViewer schema={parsedProtoSchema} expand={true} search={true} />
+            ) : (
+              <JSONSchemaViewer schema={parsedSchema} expand={true} search={true} />
+            )}
+          </div>
+
+          {/* Footer */}
+          <div className="flex justify-end p-4 border-t border-[rgb(var(--ec-page-border))] flex-shrink-0">
+            <Dialog.Close asChild>
+              <button
+                type="button"
+                className="px-4 py-2 text-sm font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:ring-offset-2 transition-colors"
+              >
+                Close
+              </button>
+            </Dialog.Close>
+          </div>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/VersionHistoryModal.tsx b/packages/core/eventcatalog/src/components/SchemaExplorer/VersionHistoryModal.tsx
new file mode 100644
index 000000000..e3c913fc3
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/VersionHistoryModal.tsx
@@ -0,0 +1,74 @@
+import * as Dialog from '@radix-ui/react-dialog';
+import { XMarkIcon, ArrowsPointingOutIcon } from '@heroicons/react/24/outline';
+import DiffViewer from './DiffViewer';
+import type { VersionDiff } from './types';
+
+interface VersionHistoryModalProps {
+  isOpen: boolean;
+  onOpenChange: (open: boolean) => void;
+  diffs: VersionDiff[];
+  messageName: string;
+  apiAccessEnabled?: boolean;
+}
+
+export default function VersionHistoryModal({
+  isOpen,
+  onOpenChange,
+  diffs,
+  messageName,
+  apiAccessEnabled = false,
+}: VersionHistoryModalProps) {
+  return (
+    <Dialog.Root open={isOpen} onOpenChange={onOpenChange}>
+      <Dialog.Portal>
+        <Dialog.Overlay className="fixed inset-0 bg-black/50 data-[state=open]:animate-overlayShow z-50" />
+        <Dialog.Content className="fixed inset-4 md:inset-8 rounded-lg bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] shadow-xl focus:outline-hidden data-[state=open]:animate-contentShow z-[100] flex flex-col">
+          {/* Header */}
+          <div className="flex items-center justify-between p-6 border-b border-[rgb(var(--ec-page-border))] flex-shrink-0">
+            <div className="flex items-center gap-3">
+              <ArrowsPointingOutIcon className="h-6 w-6 text-[rgb(var(--ec-icon-color))]" />
+              <div>
+                <Dialog.Title className="text-xl font-semibold text-[rgb(var(--ec-page-text))]">Version Comparison</Dialog.Title>
+                <Dialog.Description className="text-sm text-[rgb(var(--ec-page-text-muted))] mt-1">
+                  {messageName}
+                </Dialog.Description>
+              </div>
+            </div>
+            <Dialog.Close asChild>
+              <button
+                type="button"
+                className="p-2 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] rounded-md transition-colors"
+                aria-label="Close"
+              >
+                <XMarkIcon className="h-6 w-6" />
+              </button>
+            </Dialog.Close>
+          </div>
+
+          {/* Content */}
+          <div className="flex-1 overflow-y-auto p-6">
+            {diffs.length > 0 ? (
+              <DiffViewer diffs={diffs} apiAccessEnabled={apiAccessEnabled} />
+            ) : (
+              <div className="flex items-center justify-center h-full">
+                <p className="text-[rgb(var(--ec-page-text-muted))] text-center">No version comparison available</p>
+              </div>
+            )}
+          </div>
+
+          {/* Footer */}
+          <div className="flex justify-end p-4 border-t border-[rgb(var(--ec-page-border))] flex-shrink-0">
+            <Dialog.Close asChild>
+              <button
+                type="button"
+                className="px-4 py-2 text-sm font-medium text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] focus:outline-hidden transition-colors"
+              >
+                Close
+              </button>
+            </Dialog.Close>
+          </div>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/types.ts b/packages/core/eventcatalog/src/components/SchemaExplorer/types.ts
new file mode 100644
index 000000000..15f373b37
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/types.ts
@@ -0,0 +1,53 @@
+import type { CollectionMessageTypes } from '@types';
+import type { MessageExample } from '@utils/collections/examples';
+export type { MessageExample };
+
+export interface Producer {
+  id: string;
+  version: string;
+}
+
+export interface Consumer {
+  id: string;
+  version: string;
+}
+
+export interface Owner {
+  id: string;
+  name: string;
+  type: 'users' | 'teams';
+  href: string;
+}
+
+export interface SchemaItem {
+  collection: CollectionMessageTypes | 'services' | 'data-products';
+  data: {
+    id: string;
+    name: string;
+    version: string;
+    summary?: string;
+    schemaPath?: string;
+    producers?: Producer[];
+    consumers?: Consumer[];
+    owners?: Owner[];
+  };
+  schemaContent?: string;
+  schemaExtension?: string;
+  specType?: string;
+  specName?: string;
+  specFilenameWithoutExtension?: string;
+  // For data contracts
+  contractType?: string;
+  dataProductId?: string;
+  dataProductVersion?: string;
+  // Examples
+  examples?: MessageExample[];
+}
+
+export interface VersionDiff {
+  fromVersion: string;
+  toVersion: string;
+  diffHtml: string;
+  fromContent: string;
+  toContent: string;
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/useDarkMode.ts b/packages/core/eventcatalog/src/components/SchemaExplorer/useDarkMode.ts
new file mode 100644
index 000000000..3868c73bb
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/useDarkMode.ts
@@ -0,0 +1,7 @@
+import { useStore } from '@nanostores/react';
+import { themeStore } from '@stores/theme-store';
+
+export function useDarkMode(): boolean {
+  const theme = useStore(themeStore);
+  return theme === 'dark';
+}
diff --git a/packages/core/eventcatalog/src/components/SchemaExplorer/utils.ts b/packages/core/eventcatalog/src/components/SchemaExplorer/utils.ts
new file mode 100644
index 000000000..b9b03ac01
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SchemaExplorer/utils.ts
@@ -0,0 +1,126 @@
+// Schema types that should use SVG icons
+export const ICON_SPECS: Record<string, string> = {
+  openapi: 'openapi',
+  asyncapi: 'asyncapi',
+  graphql: 'graphql',
+  gql: 'graphql',
+  avro: 'avro',
+  avsc: 'avro',
+  proto: 'proto',
+  protobuf: 'proto',
+  json: 'json-schema',
+};
+
+// Schema format badge config for non-icon types: short label + color
+export function getFormatBadge(ext?: string): { label: string; color: string } {
+  const type = ext?.toLowerCase();
+  switch (type) {
+    case 'json':
+      return { label: '{ }', color: 'text-emerald-400' };
+    case 'avro':
+    case 'avsc':
+      return { label: 'avro', color: 'text-blue-400' };
+    case 'proto':
+    case 'protobuf':
+      return { label: 'proto', color: 'text-orange-400' };
+    case 'yaml':
+    case 'yml':
+      return { label: 'yaml', color: 'text-yellow-400' };
+    case 'xml':
+    case 'xsd':
+      return { label: 'xml', color: 'text-red-400' };
+    default:
+      return { label: '{ }', color: 'text-gray-400' };
+  }
+}
+
+// Extract the service name from a producer/consumer reference ID
+// Content references use format: "{serviceId}-{version}" e.g. "ShippingService-0.0.1"
+export function extractServiceName(refId: string): string {
+  const match = refId.match(/^(.+?)-(\d+\.\d+\.\d+|\d+\.\d+|\d+)$/);
+  return match ? match[1] : refId;
+}
+
+export const getLanguageForHighlight = (extension?: string): string => {
+  if (!extension) return 'json';
+  const ext = extension.toLowerCase();
+  switch (ext) {
+    case 'avro':
+    case 'avsc':
+    case 'json':
+      return 'json';
+    case 'proto':
+    case 'protobuf':
+      return 'protobuf';
+    case 'xsd':
+    case 'xml':
+      return 'xml';
+    case 'graphql':
+    case 'gql':
+      return 'graphql';
+    case 'yaml':
+    case 'yml':
+    case 'openapi':
+    case 'asyncapi':
+      return 'yaml';
+    case 'ts':
+    case 'typescript':
+      return 'typescript';
+    case 'js':
+    case 'javascript':
+      return 'javascript';
+    default:
+      return 'json';
+  }
+};
+
+export const getSchemaTypeLabel = (extension?: string): string => {
+  if (!extension) return 'JSON';
+  const ext = extension.toLowerCase();
+  switch (ext) {
+    case 'avro':
+    case 'avsc':
+      return 'Avro';
+    case 'proto':
+    case 'protobuf':
+      return 'Protobuf';
+    case 'xsd':
+      return 'XML Schema';
+    case 'graphql':
+    case 'gql':
+      return 'GraphQL';
+    case 'yaml':
+    case 'yml':
+      return 'YAML';
+    case 'json':
+      return 'JSON Schema';
+    case 'openapi':
+      return 'OpenAPI';
+    case 'asyncapi':
+      return 'AsyncAPI';
+    default:
+      return ext.toUpperCase();
+  }
+};
+
+export const copyToClipboard = async (content: string): Promise<boolean> => {
+  try {
+    await navigator.clipboard.writeText(content);
+    return true;
+  } catch (err) {
+    console.error('Failed to copy:', err);
+    return false;
+  }
+};
+
+export const downloadSchema = (content: string, filename: string, extension: string) => {
+  const blob = new Blob([content], { type: 'text/plain' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = `${filename}.${extension}`;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+};
diff --git a/packages/core/eventcatalog/src/components/Search/Search.astro b/packages/core/eventcatalog/src/components/Search/Search.astro
new file mode 100644
index 000000000..e87448322
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Search/Search.astro
@@ -0,0 +1,129 @@
+---
+import MagnifyingGlassIcon from '@heroicons/react/24/outline/MagnifyingGlassIcon';
+import SearchModal from './SearchModal.tsx';
+---
+
+<div>
+  <div class="relative flex items-center w-full pr-4 ml-1">
+    <input
+      id="search-dummy-input"
+      type="text"
+      name="search"
+      placeholder="Search EventCatalog"
+      autocomplete="off"
+      class="block w-full rounded-md caret-transparent border-0 py-1.5 pr-14 pl-10! text-[rgb(var(--ec-header-text))] bg-[rgb(var(--ec-header-bg))] shadow-xs ring-1 ring-inset ring-[rgb(var(--ec-dropdown-border))] placeholder:text-[rgb(var(--ec-icon-color))] font-light sm:text-sm sm:leading-6"
+    />
+    <MagnifyingGlassIcon className="absolute inset-y-0 left-0 h-9 w-8 flex items-center pl-4 text-[rgb(var(--ec-icon-color))]" />
+    <div class="absolute inset-y-0 right-0 flex py-1.5 pr-6">
+      <kbd class="inline-flex items-center rounded px-1 font-sans text-xs text-[rgb(var(--ec-icon-color))]">⌘K</kbd>
+    </div>
+  </div>
+</div>
+
+<SearchModal client:idle />
+
+<script>
+  // Create a global state for the search modal
+  (window as any).searchModalState = {
+    isOpen: false,
+    isClosing: false,
+    open: function () {
+      if (this.isClosing) return;
+      this.isOpen = true;
+      this.render();
+    },
+    toggle: function () {
+      if (this.isClosing) return;
+      this.isOpen = !this.isOpen;
+      this.render();
+    },
+    close: function () {
+      this.isOpen = false;
+      this.isClosing = true;
+      this.render();
+      // Reset isClosing after a short delay to prevent immediate reopening by focus restoration
+      // waiting for transition (200ms) + buffer
+      setTimeout(() => {
+        this.isClosing = false;
+      }, 500);
+    },
+    render: function () {
+      // This will be handled by React component
+      const event = new CustomEvent('searchModalToggle', {
+        detail: { isOpen: this.isOpen },
+      });
+      window.dispatchEvent(event);
+    },
+  };
+
+  // Setup function to initialize event listeners
+  function setupSearchListeners() {
+    const dummyInput = document.getElementById('search-dummy-input');
+
+    // Remove existing listeners if any to prevent duplicates
+    if (dummyInput) {
+      const newInput = dummyInput.cloneNode(true) as HTMLElement;
+      dummyInput.parentNode?.replaceChild(newInput, dummyInput);
+      const refreshedInput = document.getElementById('search-dummy-input');
+
+      refreshedInput?.addEventListener('click', function (e) {
+        e.preventDefault();
+        this.blur();
+        (window as any).searchModalState.open();
+      });
+
+      refreshedInput?.addEventListener('focus', function (e) {
+        e.preventDefault();
+        this.blur();
+        (window as any).searchModalState.open();
+      });
+    }
+  }
+
+  // Setup keyboard shortcut (only needs to be done once)
+  window.addEventListener('keydown', (event) => {
+    if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
+      event.preventDefault();
+      (window as any).searchModalState.open();
+    }
+  });
+
+  // Listen for modal state changes to update page elements
+  window.addEventListener('searchModalToggle', (event) => {
+    const header = document.getElementById('eventcatalog-header');
+    const verticalNav = document.getElementById('eventcatalog-vertical-nav');
+    // Handle custom docs sidebars
+    const customDocsSidebars = document.querySelectorAll('aside[class*="fixed"][class*="z-10"]');
+
+    if ((event as any).detail.isOpen) {
+      if (header) header.classList.remove('backdrop-blur-sm');
+      if (verticalNav) verticalNav.style.zIndex = '-100';
+      // Hide custom docs sidebars when modal opens
+      customDocsSidebars.forEach((sidebar: any) => {
+        sidebar.style.zIndex = '-100';
+      });
+    } else {
+      if (header) header.classList.add('backdrop-blur-sm');
+      if (verticalNav) verticalNav.style.zIndex = '10';
+      // Restore custom docs sidebars when modal closes
+      customDocsSidebars.forEach((sidebar: any) => {
+        sidebar.style.zIndex = '10';
+      });
+    }
+  });
+
+  // Setup listeners on initial load
+  setupSearchListeners();
+
+  // Re-setup listeners after client-side navigation
+  document.addEventListener('astro:page-load', setupSearchListeners);
+</script>
+
+<style>
+  .line-clamp-2 {
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/components/Search/SearchDataLoader.astro b/packages/core/eventcatalog/src/components/Search/SearchDataLoader.astro
new file mode 100644
index 000000000..649872002
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Search/SearchDataLoader.astro
@@ -0,0 +1,49 @@
+---
+/**
+ * SearchDataLoader.astro
+ *
+ * This component loads the sidebar/search data independently of the sidebar UI.
+ * It ensures the search functionality works on all pages, even when the nested
+ * sidebar is not rendered (e.g., /discover pages).
+ *
+ * The data is fetched from a static JSON file (/api/sidebar-data.json) instead of
+ * being embedded inline in every HTML page. This significantly reduces build size
+ * for large catalogs.
+ */
+---
+
+<script>
+  import { setSidebarData, sidebarStore } from '@stores/sidebar-store';
+  import { buildUrl } from '@utils/url-builder';
+
+  // Only fetch if we haven't already loaded the data
+  if (!sidebarStore.get()) {
+    const apiUrl = buildUrl('/api/sidebar-data.json', true);
+
+    const loadSidebarData = () => {
+      // Double-check cache in case another component loaded data while waiting for idle
+      if (sidebarStore.get()) return;
+
+      fetch(apiUrl)
+        .then((response) => {
+          if (!response.ok) {
+            throw new Error(`Failed to fetch sidebar data: ${response.status}`);
+          }
+          return response.json();
+        })
+        .then((data) => {
+          setSidebarData(data);
+        })
+        .catch((error) => {
+          console.error('Error loading sidebar data:', error);
+        });
+    };
+
+    // Defer non-critical sidebar payload fetch until browser is idle
+    if (typeof window.requestIdleCallback === 'function') {
+      window.requestIdleCallback(loadSidebarData, { timeout: 1200 });
+    } else {
+      setTimeout(loadSidebarData, 300);
+    }
+  }
+</script>
diff --git a/packages/core/eventcatalog/src/components/Search/SearchModal.tsx b/packages/core/eventcatalog/src/components/Search/SearchModal.tsx
new file mode 100644
index 000000000..50247d105
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Search/SearchModal.tsx
@@ -0,0 +1,696 @@
+import React, { Fragment, useState, useEffect, useMemo, useRef } from 'react';
+import { Combobox, Dialog, Transition } from '@headlessui/react';
+import { MagnifyingGlassIcon } from '@heroicons/react/20/solid';
+import {
+  RectangleGroupIcon,
+  ServerIcon,
+  BoltIcon,
+  ChatBubbleLeftIcon,
+  MagnifyingGlassIcon as QueryIcon,
+  CubeIcon,
+  QueueListIcon,
+  UserGroupIcon,
+  UserIcon,
+  BookOpenIcon,
+  DocumentTextIcon,
+  ExclamationCircleIcon,
+  ArrowRightIcon,
+  ArrowUpIcon,
+  ArrowDownIcon,
+  ArrowUturnLeftIcon,
+  StarIcon,
+  Square2StackIcon,
+  ArrowsRightLeftIcon,
+} from '@heroicons/react/24/outline';
+import { StarIcon as StarIconSolid, CircleStackIcon } from '@heroicons/react/24/solid';
+import { Bot } from 'lucide-react';
+import { useStore } from '@nanostores/react';
+import { favoritesStore, toggleFavorite as toggleFavoriteAction } from '../../stores/favorites-store';
+import { buildUrl } from '@utils/url-builder';
+import { resolveIconUrl } from '@utils/icon';
+import {
+  applyActiveFilter,
+  getSearchFilters,
+  getUrlForSearchItem,
+  highlightQuery,
+  mapPagefindResultsToSearchItems,
+  type SearchItem,
+  type SearchNode,
+} from './search-utils';
+
+const INDEXED_RESULT_LOAD_LIMIT = 50;
+const SEARCH_RESULT_DISPLAY_LIMIT = 25;
+
+const typeIcons: any = {
+  Agent: Bot,
+  Domain: RectangleGroupIcon,
+  Service: ServerIcon,
+  Event: BoltIcon,
+  Command: ChatBubbleLeftIcon,
+  Query: QueryIcon,
+  Entity: CubeIcon,
+  Channel: ArrowsRightLeftIcon,
+  Team: UserGroupIcon,
+  User: UserIcon,
+  Language: BookOpenIcon,
+  OpenAPI: DocumentTextIcon,
+  AsyncAPI: DocumentTextIcon,
+  Design: Square2StackIcon,
+  Container: CircleStackIcon,
+  'Data Product': CubeIcon,
+  Flow: QueueListIcon,
+  'Custom Doc': DocumentTextIcon,
+  'Resource Doc': DocumentTextIcon,
+  Changelog: DocumentTextIcon,
+  default: DocumentTextIcon,
+};
+
+const typeColors: any = {
+  Agent: 'text-sky-500 dark:text-sky-400 bg-sky-50 dark:bg-sky-500/10 ring-sky-200 dark:ring-sky-500/30',
+  Domain: 'text-orange-500 dark:text-orange-400 bg-orange-50 dark:bg-orange-500/10 ring-orange-200 dark:ring-orange-500/30',
+  Service: 'text-pink-500 dark:text-pink-400 bg-pink-50 dark:bg-pink-500/10 ring-pink-200 dark:ring-pink-500/30',
+  Event: 'text-orange-500 dark:text-orange-400 bg-orange-50 dark:bg-orange-500/10 ring-orange-200 dark:ring-orange-500/30',
+  Command: 'text-blue-500 dark:text-blue-400 bg-blue-50 dark:bg-blue-500/10 ring-blue-200 dark:ring-blue-500/30',
+  Query: 'text-green-500 dark:text-green-400 bg-green-50 dark:bg-green-500/10 ring-green-200 dark:ring-green-500/30',
+  Entity: 'text-purple-500 dark:text-purple-400 bg-purple-50 dark:bg-purple-500/10 ring-purple-200 dark:ring-purple-500/30',
+  Channel: 'text-indigo-500 dark:text-indigo-400 bg-indigo-50 dark:bg-indigo-500/10 ring-indigo-200 dark:ring-indigo-500/30',
+  Team: 'text-teal-500 dark:text-teal-400 bg-teal-50 dark:bg-teal-500/10 ring-teal-200 dark:ring-teal-500/30',
+  User: 'text-cyan-500 dark:text-cyan-400 bg-cyan-50 dark:bg-cyan-500/10 ring-cyan-200 dark:ring-cyan-500/30',
+  Language: 'text-amber-500 dark:text-amber-400 bg-amber-50 dark:bg-amber-500/10 ring-amber-200 dark:ring-amber-500/30',
+  OpenAPI:
+    'text-emerald-500 dark:text-emerald-400 bg-emerald-50 dark:bg-emerald-500/10 ring-emerald-200 dark:ring-emerald-500/30',
+  AsyncAPI: 'text-violet-500 dark:text-violet-400 bg-violet-50 dark:bg-violet-500/10 ring-violet-200 dark:ring-violet-500/30',
+  Design: 'text-gray-500 dark:text-gray-400 bg-gray-50 dark:bg-gray-500/10 ring-gray-200 dark:ring-gray-500/30',
+  Container: 'text-indigo-500 dark:text-indigo-400 bg-indigo-50 dark:bg-indigo-500/10 ring-indigo-200 dark:ring-indigo-500/30',
+  'Data Product': 'text-sky-500 dark:text-sky-400 bg-sky-50 dark:bg-sky-500/10 ring-sky-200 dark:ring-sky-500/30',
+  Flow: 'text-fuchsia-500 dark:text-fuchsia-400 bg-fuchsia-50 dark:bg-fuchsia-500/10 ring-fuchsia-200 dark:ring-fuchsia-500/30',
+  'Custom Doc': 'text-gray-500 dark:text-gray-400 bg-gray-50 dark:bg-gray-500/10 ring-gray-200 dark:ring-gray-500/30',
+  'Resource Doc': 'text-gray-500 dark:text-gray-400 bg-gray-50 dark:bg-gray-500/10 ring-gray-200 dark:ring-gray-500/30',
+  Changelog: 'text-gray-500 dark:text-gray-400 bg-gray-50 dark:bg-gray-500/10 ring-gray-200 dark:ring-gray-500/30',
+  default: 'text-gray-500 dark:text-gray-400 bg-gray-50 dark:bg-gray-500/10 ring-gray-200 dark:ring-gray-500/30',
+};
+
+function classNames(...classes: (string | boolean | undefined)[]) {
+  return classes.filter(Boolean).join(' ');
+}
+
+const searchResultHighlightClassName =
+  '[&_mark]:bg-transparent [&_mark]:p-0 [&_mark]:font-semibold [&_mark]:text-[rgb(var(--ec-accent))]';
+
+interface SearchNodeCompact {
+  k: string;
+  t: string;
+  b?: string;
+  s?: string;
+  h?: string;
+  i?: string;
+  li?: string;
+}
+
+interface SearchIndexPayload {
+  i?: SearchNodeCompact[];
+  items?: SearchNode[];
+}
+
+interface PagefindModule {
+  init: () => Promise<void>;
+  options?: (options: Record<string, unknown>) => Promise<void>;
+  debouncedSearch: (term: string) => Promise<{ results: Array<{ id: string; score?: number; data: () => Promise<any> }> } | null>;
+}
+
+const normalizeSearchIndexPayload = (payload: SearchIndexPayload): SearchNode[] => {
+  if (payload.i) {
+    return payload.i.map((item) => ({
+      key: item.k,
+      title: item.t,
+      badge: item.b,
+      summary: item.s,
+      href: item.h,
+      icon: item.i,
+      leftIcon: item.li,
+    }));
+  }
+
+  return payload.items || [];
+};
+
+const loadPagefindModule = (url: string) => {
+  const nativeImport = new Function('url', 'return import(url)') as (url: string) => Promise<PagefindModule>;
+  return nativeImport(url);
+};
+
+export default function SearchModal() {
+  const searchType = typeof __EC_SEARCH_TYPE__ !== 'undefined' ? __EC_SEARCH_TYPE__ : 'resource';
+  const isIndexedSearch = searchType === 'indexed';
+  const [query, setQuery] = useState('');
+  const [open, setOpen] = useState(false);
+  const [activeFilter, setActiveFilter] = useState('all');
+  const [searchNodes, setSearchNodes] = useState<SearchNode[]>([]);
+  const [indexedItems, setIndexedItems] = useState<SearchItem[]>([]);
+  const [pagefind, setPagefind] = useState<PagefindModule | null>(null);
+  const [isSearchingIndexed, setIsSearchingIndexed] = useState(false);
+  const [isLoadingSearchIndex, setIsLoadingSearchIndex] = useState(false);
+  const [searchIndexLoadError, setSearchIndexLoadError] = useState<string | null>(null);
+  const favorites = useStore(favoritesStore);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    const handleModalToggle = (event: CustomEvent) => {
+      setOpen(event.detail.isOpen);
+      if (event.detail.isOpen) {
+        // Focus input when modal opens
+        setTimeout(() => {
+          inputRef.current?.focus();
+        }, 50);
+      }
+    };
+
+    window.addEventListener('searchModalToggle', handleModalToggle as EventListener);
+    return () => window.removeEventListener('searchModalToggle', handleModalToggle as EventListener);
+  }, []);
+
+  useEffect(() => {
+    if (isIndexedSearch || !open || searchNodes.length > 0 || isLoadingSearchIndex) {
+      return;
+    }
+
+    setIsLoadingSearchIndex(true);
+    setSearchIndexLoadError(null);
+
+    const apiUrl = buildUrl('/api/search-index.json', true);
+
+    fetch(apiUrl)
+      .then((response) => {
+        if (!response.ok) {
+          throw new Error(`Failed to fetch search index: ${response.status}`);
+        }
+        return response.json() as Promise<SearchIndexPayload>;
+      })
+      .then((payload) => {
+        setSearchNodes(normalizeSearchIndexPayload(payload));
+      })
+      .catch((error) => {
+        setSearchIndexLoadError(error instanceof Error ? error.message : 'Unable to load search index');
+      })
+      .finally(() => {
+        setIsLoadingSearchIndex(false);
+      });
+  }, [isIndexedSearch, open, searchNodes.length, isLoadingSearchIndex]);
+
+  useEffect(() => {
+    if (!isIndexedSearch || !open || pagefind || isLoadingSearchIndex) {
+      return;
+    }
+
+    setIsLoadingSearchIndex(true);
+    setSearchIndexLoadError(null);
+
+    const pagefindUrl = buildUrl('/pagefind/pagefind.js', true);
+
+    loadPagefindModule(pagefindUrl)
+      .then(async (module: PagefindModule) => {
+        await module.options?.({
+          excerptLength: 30,
+          ranking: {
+            metaWeights: {
+              title: 5.0,
+              id: 4.0,
+              summary: 2.0,
+              type: 1.5,
+            },
+          },
+        });
+        await module.init();
+        setPagefind(module);
+      })
+      .catch((error) => {
+        console.error(error);
+        setSearchIndexLoadError(
+          import.meta.env.DEV
+            ? 'The local indexed search files could not be loaded. Restart the catalog dev server to rebuild the index.'
+            : 'Indexed search is enabled, but the generated search index could not be loaded. Run `eventcatalog build` to create it.'
+        );
+      })
+      .finally(() => {
+        setIsLoadingSearchIndex(false);
+      });
+  }, [isIndexedSearch, open, pagefind, isLoadingSearchIndex]);
+
+  const closeModal = () => {
+    if ((window as any).searchModalState) {
+      (window as any).searchModalState.close();
+    } else {
+      setOpen(false);
+    }
+  };
+
+  const items = useMemo(() => {
+    return searchNodes
+      .map((node) => {
+        const url = getUrlForSearchItem(node as any, node.key);
+        if (!url) return null;
+
+        return {
+          id: url,
+          name: node.title,
+          url,
+          type: node.badge || 'Page',
+          key: node.key,
+          rawNode: node,
+        };
+      })
+      .filter((item): item is NonNullable<typeof item> => item !== null);
+  }, [searchNodes]);
+
+  useEffect(() => {
+    if (!isIndexedSearch || !pagefind || query.trim() === '') {
+      setIndexedItems([]);
+      setIsSearchingIndexed(false);
+      return;
+    }
+
+    let cancelled = false;
+    setIsSearchingIndexed(true);
+
+    const timeout = window.setTimeout(async () => {
+      try {
+        const search = await pagefind.debouncedSearch(query);
+        if (cancelled || !search?.results) {
+          return;
+        }
+
+        const results = await mapPagefindResultsToSearchItems({
+          results: search.results,
+          query,
+          limit: INDEXED_RESULT_LOAD_LIMIT,
+        });
+
+        if (!cancelled) {
+          setIndexedItems(results);
+        }
+      } catch (error) {
+        if (!cancelled) {
+          setSearchIndexLoadError(error instanceof Error ? error.message : 'Unable to search the indexed catalog');
+        }
+      } finally {
+        if (!cancelled) {
+          setIsSearchingIndexed(false);
+        }
+      }
+    }, 120);
+
+    return () => {
+      cancelled = true;
+      window.clearTimeout(timeout);
+    };
+  }, [isIndexedSearch, pagefind, query]);
+
+  // Get searchable items (items that match the query but not filtered by type yet)
+  const searchableItems = useMemo(() => {
+    if (isIndexedSearch) {
+      return indexedItems;
+    }
+
+    if (query === '') {
+      // When no query, show all items for filter counts
+      return items;
+    }
+
+    const lowerQuery = query.toLowerCase();
+    return items.filter((item) => {
+      if (item.name.toLowerCase().includes(lowerQuery)) return true;
+      // Key format is "type:id:version" (e.g. "service:OrdersService:0.0.3").
+      // Match against the id so users can find resources by their raw id too.
+      const keyParts = item.key?.split(':') ?? [];
+      const id = keyParts[1];
+      if (id?.toLowerCase().includes(lowerQuery)) return true;
+      return !!item.rawNode.summary && item.rawNode.summary.toLowerCase().includes(lowerQuery);
+    });
+  }, [indexedItems, isIndexedSearch, items, query]);
+
+  const filters = useMemo(() => {
+    return getSearchFilters({
+      items: query === '' ? items : searchableItems,
+      query,
+    });
+  }, [searchableItems, items, query]);
+
+  const showFilterTabs = filters.some((filter) => filter.count > 0);
+
+  // Reset active filter if it no longer has results
+  useEffect(() => {
+    if (activeFilter !== 'all' && !filters.some((f) => f.id === activeFilter)) {
+      setActiveFilter('all');
+    }
+  }, [filters, activeFilter]);
+
+  const handleToggleFavorite = (e: React.MouseEvent, item: any) => {
+    e.preventDefault();
+    e.stopPropagation();
+
+    if (!item.key) return;
+
+    toggleFavoriteAction({
+      nodeKey: item.key,
+      path: [], // Path is not easily available here, but Sidebar rebuilds it
+      title: item.name,
+      badge: item.rawNode.badge,
+      href: item.url,
+    });
+  };
+
+  const searchNodeLookup = useMemo(() => {
+    return new Map(searchNodes.map((node) => [node.key, node]));
+  }, [searchNodes]);
+
+  const filteredItems = useMemo(() => {
+    if (isIndexedSearch) {
+      if (query === '') {
+        return [];
+      }
+
+      return applyActiveFilter(searchableItems, activeFilter).slice(0, SEARCH_RESULT_DISPLAY_LIMIT);
+    }
+
+    if (query === '') {
+      // Show favorites when search is empty
+      if (favorites.length > 0 && activeFilter === 'all') {
+        return favorites
+          .slice(0, 5)
+          .map((fav) => {
+            const node = searchNodeLookup.get(fav.nodeKey);
+            const url = node ? getUrlForSearchItem(node as any, fav.nodeKey) : fav.href;
+            if (!url) return null;
+
+            return {
+              id: url,
+              name: fav.title,
+              url,
+              type: fav.badge || node?.badge || 'Page',
+              key: fav.nodeKey,
+              rawNode: node || {
+                title: fav.title,
+                badge: fav.badge,
+                summary: undefined,
+                icon: undefined,
+                leftIcon: undefined,
+                matchedExcerpt: undefined,
+              },
+              isFavorite: true,
+            };
+          })
+          .filter((item): item is NonNullable<typeof item> => item !== null);
+      }
+      return [];
+    }
+
+    return applyActiveFilter(searchableItems, activeFilter).slice(0, SEARCH_RESULT_DISPLAY_LIMIT);
+  }, [isIndexedSearch, searchableItems, query, activeFilter, favorites, searchNodeLookup]);
+
+  return (
+    <Transition.Root
+      show={open}
+      as={Fragment}
+      afterLeave={() => {
+        setQuery('');
+        setActiveFilter('all');
+      }}
+      appear
+    >
+      <Dialog as="div" className="relative z-50" onClose={closeModal}>
+        <Transition.Child
+          as={Fragment}
+          enter="ease-out duration-300"
+          enterFrom="opacity-0"
+          enterTo="opacity-100"
+          leave="ease-in duration-200"
+          leaveFrom="opacity-100"
+          leaveTo="opacity-0"
+        >
+          <div className="fixed inset-0 bg-black/40 dark:bg-black/60 transition-opacity backdrop-blur-sm" />
+        </Transition.Child>
+
+        <div className="fixed inset-0 z-10 w-screen overflow-y-auto p-4 sm:p-6 md:p-20">
+          <Transition.Child
+            as={Fragment}
+            enter="ease-out duration-300"
+            enterFrom="opacity-0 scale-95"
+            enterTo="opacity-100 scale-100"
+            leave="ease-in duration-200"
+            leaveFrom="opacity-100 scale-100"
+            leaveTo="opacity-0 scale-95"
+          >
+            <Dialog.Panel className="mx-auto max-w-2xl transform divide-y divide-[rgb(var(--ec-page-border))] overflow-hidden rounded-xl bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] shadow-2xl ring-1 ring-black/10 dark:ring-white/10 transition-all">
+              <Combobox
+                onChange={(item: any) => {
+                  if (item?.url) {
+                    window.location.href = item.url;
+                    closeModal();
+                  }
+                }}
+              >
+                <div className="relative border-b border-[rgb(var(--ec-page-border))]">
+                  <MagnifyingGlassIcon
+                    className="pointer-events-none absolute left-4 top-3.5 h-5 w-5 text-[rgb(var(--ec-icon-color))]"
+                    aria-hidden="true"
+                  />
+                  <Combobox.Input
+                    ref={inputRef}
+                    className={classNames(
+                      'h-12 w-full border-0 bg-transparent pl-11 text-[rgb(var(--ec-page-text))] placeholder:text-[rgb(var(--ec-icon-color))] focus:ring-0 sm:text-sm focus:outline-hidden',
+                      query.trim() !== '' && filteredItems.length > 0 ? 'pr-20' : 'pr-4'
+                    )}
+                    placeholder="Search..."
+                    onChange={(event) => setQuery(event.target.value)}
+                    value={query}
+                    autoFocus
+                    autoComplete="off"
+                  />
+                  {query.trim() !== '' && filteredItems.length > 0 && (
+                    <kbd className="pointer-events-none absolute right-4 top-2.5 rounded-lg bg-[rgb(var(--ec-content-hover))] px-2.5 py-1 text-xs font-semibold text-[rgb(var(--ec-page-text-muted))] ring-1 ring-inset ring-[rgb(var(--ec-page-border))]">
+                      ESC
+                    </kbd>
+                  )}
+                </div>
+
+                {/* Filter Tabs */}
+                {showFilterTabs && (
+                  <div
+                    className="flex items-center gap-2 px-4 pt-3 pb-3.5 overflow-x-auto overscroll-x-contain border-b border-[rgb(var(--ec-page-border))]"
+                    style={{
+                      scrollbarWidth: 'thin',
+                      scrollbarColor: 'rgb(var(--ec-page-border)) transparent',
+                    }}
+                  >
+                    {filters.map((tab) => (
+                      <button
+                        key={tab.id}
+                        onClick={() => setActiveFilter(tab.id)}
+                        className={classNames(
+                          'px-3 py-1 text-xs font-medium rounded-full transition-colors whitespace-nowrap',
+                          activeFilter === tab.id
+                            ? 'bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent-text))]'
+                            : 'bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-content-active))]'
+                        )}
+                      >
+                        {tab.name}
+                      </button>
+                    ))}
+                  </div>
+                )}
+
+                {isLoadingSearchIndex && (
+                  <div className="py-10 px-6 text-center text-sm sm:px-14">
+                    <MagnifyingGlassIcon className="mx-auto h-6 w-6 text-[rgb(var(--ec-icon-color))] animate-pulse" />
+                    <p className="mt-4 font-semibold text-[rgb(var(--ec-page-text))]">Loading search index…</p>
+                    <p className="mt-2 text-[rgb(var(--ec-page-text-muted))]">
+                      {isIndexedSearch ? 'Preparing indexed search.' : 'Preparing resources for search.'}
+                    </p>
+                  </div>
+                )}
+
+                {searchIndexLoadError && !isLoadingSearchIndex && (
+                  <div className="px-6 py-12 text-center text-sm sm:px-14">
+                    <div className="mx-auto flex h-10 w-10 items-center justify-center rounded-lg bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-icon-color))] ring-1 ring-inset ring-[rgb(var(--ec-page-border))]">
+                      <ExclamationCircleIcon className="h-5 w-5" aria-hidden="true" />
+                    </div>
+                    <p className="mt-4 font-semibold text-[rgb(var(--ec-page-text))]">
+                      {isIndexedSearch ? 'Indexed search is not ready' : 'Search is not ready'}
+                    </p>
+                    <p className="mx-auto mt-2 max-w-sm text-[rgb(var(--ec-page-text-muted))]">{searchIndexLoadError}</p>
+                  </div>
+                )}
+
+                {!isLoadingSearchIndex && !searchIndexLoadError && filteredItems.length > 0 && (
+                  <>
+                    {!isIndexedSearch && query === '' && favorites.length > 0 && (
+                      <div className="px-6 pt-3 pb-2">
+                        <p className="text-xs text-[rgb(var(--ec-page-text-muted))]">Favourites</p>
+                      </div>
+                    )}
+                    <Combobox.Options static className="max-h-96 scroll-py-3 overflow-y-auto p-3">
+                      {filteredItems.map((item) => {
+                        const Icon = typeIcons[item.type] || typeIcons.default;
+                        const colors = typeColors[item.type] || typeColors.default;
+
+                        const isFavorite = !!item.key && favorites.some((fav) => fav.nodeKey === item.key);
+
+                        return (
+                          <Combobox.Option
+                            key={item.id}
+                            value={item}
+                            className={({ active }) =>
+                              classNames(
+                                'flex cursor-default select-none rounded-xl p-3 group',
+                                active && 'bg-[rgb(var(--ec-content-active))]'
+                              )
+                            }
+                          >
+                            {({ active }) => (
+                              <>
+                                <div
+                                  className={classNames(
+                                    'flex h-10 w-10 flex-none items-center justify-center rounded-lg ring-1 ring-inset',
+                                    colors
+                                  )}
+                                >
+                                  {item.rawNode?.leftIcon ? (
+                                    <img
+                                      src={resolveIconUrl(item.rawNode.leftIcon)}
+                                      alt=""
+                                      loading="lazy"
+                                      className="h-6 w-6 object-contain"
+                                    />
+                                  ) : (
+                                    <Icon className="h-6 w-6" aria-hidden="true" />
+                                  )}
+                                </div>
+                                <div className="ml-4 flex-auto min-w-0">
+                                  <p
+                                    className={classNames(
+                                      'text-sm font-medium',
+                                      searchResultHighlightClassName,
+                                      active ? 'text-[rgb(var(--ec-page-text))]' : 'text-[rgb(var(--ec-page-text))]'
+                                    )}
+                                    dangerouslySetInnerHTML={{ __html: highlightQuery(item.name, query) }}
+                                  />
+                                  <div className="flex items-center gap-2">
+                                    {!item.rawNode.matchedExcerpt && (
+                                      <p
+                                        className={classNames(
+                                          'text-xs flex-shrink-0',
+                                          active ? 'text-[rgb(var(--ec-page-text))]' : 'text-[rgb(var(--ec-page-text-muted))]'
+                                        )}
+                                      >
+                                        {item.type}
+                                      </p>
+                                    )}
+                                    {item.rawNode.summary && (
+                                      <p
+                                        className={classNames(
+                                          'text-xs truncate',
+                                          active ? 'text-[rgb(var(--ec-page-text-muted))]' : 'text-[rgb(var(--ec-icon-color))]'
+                                        )}
+                                      >
+                                        {!item.rawNode.matchedExcerpt && '• '}
+                                        {item.rawNode.matchedExcerpt ? (
+                                          <span
+                                            className={searchResultHighlightClassName}
+                                            dangerouslySetInnerHTML={{ __html: item.rawNode.matchedExcerpt }}
+                                          />
+                                        ) : (
+                                          item.rawNode.summary
+                                        )}
+                                      </p>
+                                    )}
+                                  </div>
+                                </div>
+                                <div className="flex items-center">
+                                  {!!item.key && (
+                                    <button
+                                      onClick={(e) => handleToggleFavorite(e, item)}
+                                      onMouseDown={(e) => {
+                                        e.preventDefault();
+                                        e.stopPropagation();
+                                      }}
+                                      className={classNames(
+                                        'p-1 rounded-md transition-colors mr-2',
+                                        isFavorite
+                                          ? 'text-amber-400 hover:text-amber-500'
+                                          : 'text-[rgb(var(--ec-icon-color))] opacity-0 group-hover:opacity-100 hover:text-amber-400'
+                                      )}
+                                    >
+                                      {isFavorite ? <StarIconSolid className="h-5 w-5" /> : <StarIcon className="h-5 w-5" />}
+                                    </button>
+                                  )}
+                                  {active && (
+                                    <ArrowRightIcon className="h-5 w-5 text-[rgb(var(--ec-icon-color))]" aria-hidden="true" />
+                                  )}
+                                </div>
+                              </>
+                            )}
+                          </Combobox.Option>
+                        );
+                      })}
+                    </Combobox.Options>
+                  </>
+                )}
+
+                {!isLoadingSearchIndex && !searchIndexLoadError && query !== '' && filteredItems.length === 0 && (
+                  <div className="py-14 px-6 text-center text-sm sm:px-14">
+                    {isSearchingIndexed ? (
+                      <MagnifyingGlassIcon className="mx-auto h-6 w-6 text-[rgb(var(--ec-icon-color))] animate-pulse" />
+                    ) : (
+                      <ExclamationCircleIcon
+                        type="outline"
+                        name="exclamation-circle"
+                        className="mx-auto h-6 w-6 text-[rgb(var(--ec-icon-color))]"
+                      />
+                    )}
+                    <p className="mt-4 font-semibold text-[rgb(var(--ec-page-text))]">
+                      {isSearchingIndexed ? 'Searching…' : 'No results found'}
+                    </p>
+                    <p className="mt-2 text-[rgb(var(--ec-page-text-muted))]">
+                      {isSearchingIndexed
+                        ? 'Searching the indexed catalog.'
+                        : 'No components found for this search term. Please try again.'}
+                    </p>
+                  </div>
+                )}
+
+                {!isLoadingSearchIndex && !searchIndexLoadError && query === '' && filteredItems.length === 0 && (
+                  <div className="py-14 px-6 text-center text-sm sm:px-14">
+                    <MagnifyingGlassIcon className="mx-auto h-6 w-6 text-[rgb(var(--ec-icon-color))]" />
+                    <p className="mt-4 font-semibold text-[rgb(var(--ec-page-text))]">Search for anything</p>
+                    <p className="mt-2 text-[rgb(var(--ec-page-text-muted))]">
+                      {isIndexedSearch
+                        ? 'Search indexed catalog content, custom docs, resources and more.'
+                        : 'Search for domains, services, events, commands, queries, data stores, data products, flows and more.'}
+                    </p>
+                  </div>
+                )}
+
+                {/* Footer */}
+                <div className="flex flex-wrap items-center bg-[rgb(var(--ec-content-hover))] py-2.5 px-4 text-xs text-[rgb(var(--ec-page-text-muted))] border-t border-[rgb(var(--ec-page-border))]">
+                  <div className="flex items-center mr-4">
+                    <ArrowUturnLeftIcon className="h-3 w-3 mr-1" />
+                    to select
+                  </div>
+                  <div className="flex items-center mr-4">
+                    <ArrowDownIcon className="h-3 w-3 mr-1" />
+                    <ArrowUpIcon className="h-3 w-3 mr-1" />
+                    to navigate
+                  </div>
+                  <div className="flex items-center">
+                    <span className="mr-1">esc</span>
+                    to close
+                  </div>
+                </div>
+              </Combobox>
+            </Dialog.Panel>
+          </Transition.Child>
+        </div>
+      </Dialog>
+    </Transition.Root>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/Search/search-utils.spec.ts b/packages/core/eventcatalog/src/components/Search/search-utils.spec.ts
new file mode 100644
index 000000000..050ad07cf
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Search/search-utils.spec.ts
@@ -0,0 +1,173 @@
+import { describe, expect, it, beforeEach } from 'vitest';
+import {
+  applyActiveFilter,
+  getIndexedResultRank,
+  getSearchFilters,
+  getUrlForSearchItem,
+  hasMeaningfulIndexedMatch,
+  highlightQuery,
+  mapPagefindResultsToSearchItems,
+  normalizeResultUrl,
+} from './search-utils';
+
+declare global {
+  interface Window {
+    __EC_TRAILING_SLASH__: boolean;
+  }
+}
+
+describe('getUrlForSearchItem', () => {
+  beforeEach(() => {
+    // @ts-ignore
+    global.__EC_TRAILING_SLASH__ = false;
+  });
+
+  it.each([
+    ['container:OrdersDatabase:1.0.0', '/docs/containers/OrdersDatabase/1.0.0'],
+    ['data-product:Customer360:1.0.0', '/docs/data-products/Customer360/1.0.0'],
+    ['entity:Order:1.0.0', '/docs/entities/Order/1.0.0'],
+    ['flow:CheckoutFlow:1.0.0', '/docs/flows/CheckoutFlow/1.0.0'],
+  ])('builds a docs URL for %s', (key, expected) => {
+    expect(getUrlForSearchItem({}, key)).toBe(expected);
+  });
+
+  it('uses the explicit node href when provided', () => {
+    expect(getUrlForSearchItem({ href: '/custom/search-result' }, 'data-product:Customer360:1.0.0')).toBe(
+      '/custom/search-result'
+    );
+  });
+
+  it('skips aliases and unsupported keys', () => {
+    expect(getUrlForSearchItem({}, 'data-product:Customer360')).toBeNull();
+    expect(getUrlForSearchItem({}, 'list:data-products')).toBeNull();
+    expect(getUrlForSearchItem({}, 'unknown:Customer360:1.0.0')).toBeNull();
+  });
+});
+
+describe('indexed search result helpers', () => {
+  it('filters weak single-character highlighted matches for longer queries', () => {
+    expect(
+      hasMeaningfulIndexedMatch({
+        query: 'random',
+        title: 'Orders Service',
+        content: 'Order Metadata in api service server logs',
+        excerpt: 'Order Metadata in api db L -- <mark>R</mark> server',
+      })
+    ).toBe(false);
+  });
+
+  it('keeps short but meaningful marked terms', () => {
+    expect(
+      hasMeaningfulIndexedMatch({
+        query: 'db',
+        title: 'Orders Service',
+        content: 'Order Metadata in api service server logs',
+        excerpt: 'Order Metadata in api <mark>db</mark>',
+      })
+    ).toBe(true);
+  });
+
+  it('keeps exact title or content matches even without marked excerpts', () => {
+    expect(
+      hasMeaningfulIndexedMatch({
+        query: 'payments',
+        title: 'Payments Database',
+        content: '',
+        excerpt: '',
+      })
+    ).toBe(true);
+
+    expect(
+      hasMeaningfulIndexedMatch({
+        query: 'idempotency',
+        title: 'Payments Database',
+        content: 'Always include an idempotency key in payment creation.',
+        excerpt: '',
+      })
+    ).toBe(true);
+  });
+
+  it('normalizes Pagefind URLs to root-relative paths', () => {
+    expect(normalizeResultUrl('docs/containers/payments-db/0.0.1')).toBe('/docs/containers/payments-db/0.0.1');
+    expect(normalizeResultUrl('/docs/containers/payments-db/0.0.1')).toBe('/docs/containers/payments-db/0.0.1');
+    expect(normalizeResultUrl('https://example.com/docs')).toBe('https://example.com/docs');
+  });
+
+  it('highlights title matches while escaping unsafe title text', () => {
+    expect(highlightQuery('Payment <Service>', 'payment')).toBe('<mark>Payment</mark> &lt;Service&gt;');
+  });
+
+  it('ranks title matches above id/url matches and content matches', () => {
+    const query = 'payment';
+    const contentRank = getIndexedResultRank({
+      query,
+      title: 'Orders Service',
+      url: '/docs/services/OrdersService/1.0.0',
+      content: 'Handles payment retries',
+    });
+    const urlRank = getIndexedResultRank({
+      query,
+      title: 'Orders Service',
+      url: '/docs/services/PaymentService/1.0.0',
+      content: 'Handles orders',
+    });
+    const titleRank = getIndexedResultRank({
+      query,
+      title: 'Payment Service',
+      url: '/docs/services/PaymentService/1.0.0',
+      content: 'Handles orders',
+    });
+
+    expect(titleRank).toBeGreaterThan(urlRank);
+    expect(urlRank).toBeGreaterThan(contentRank);
+  });
+
+  it('applies grouped search filters', () => {
+    const items = [{ type: 'Event' }, { type: 'Command' }, { type: 'Team' }, { type: 'User' }, { type: 'Service' }];
+
+    expect(applyActiveFilter(items, 'Message')).toEqual([{ type: 'Event' }, { type: 'Command' }]);
+    expect(applyActiveFilter(items, 'Team')).toEqual([{ type: 'Team' }, { type: 'User' }]);
+    expect(applyActiveFilter(items, 'Service')).toEqual([{ type: 'Service' }]);
+  });
+
+  it('builds filter metadata without encoding behavior in labels', () => {
+    expect(getSearchFilters({ items: [], query: 'missing' })).toEqual([{ id: 'all', name: 'All (0)', count: 0 }]);
+    expect(getSearchFilters({ items: [{ type: 'Event' }, { type: 'Service' }], query: 'order' })).toEqual([
+      { id: 'all', name: 'All (2)', count: 2 },
+      { id: 'Service', name: 'Services (1)', count: 1 },
+      { id: 'Message', name: 'Messages (1)', count: 1 },
+    ]);
+  });
+
+  it('maps Pagefind results into ranked search items', async () => {
+    const items = await mapPagefindResultsToSearchItems({
+      query: 'payment',
+      limit: 10,
+      results: [
+        {
+          id: 'content',
+          score: 10,
+          data: async () => ({
+            url: 'docs/services/OrdersService/1.0.0',
+            content: 'Handles payment retries',
+            excerpt: 'Handles <mark>payment</mark> retries',
+            meta: { title: 'Orders Service', type: 'Service', id: 'OrdersService' },
+          }),
+        },
+        {
+          id: 'title',
+          score: 1,
+          data: async () => ({
+            url: 'docs/services/PaymentService/1.0.0',
+            content: 'Handles orders',
+            excerpt: '<mark>Payment</mark> service',
+            meta: { title: 'Payment Service', type: 'Service', id: 'PaymentService' },
+          }),
+        },
+      ],
+    });
+
+    expect(items.map((item) => item.id)).toEqual(['title', 'content']);
+    expect(items[0].url).toBe('/docs/services/PaymentService/1.0.0');
+  });
+});
diff --git a/packages/core/eventcatalog/src/components/Search/search-utils.ts b/packages/core/eventcatalog/src/components/Search/search-utils.ts
new file mode 100644
index 000000000..5042031ed
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Search/search-utils.ts
@@ -0,0 +1,308 @@
+import { buildUrl } from '@utils/url-builder';
+
+export interface SearchNode {
+  key: string;
+  title: string;
+  badge?: string;
+  summary?: string;
+  href?: string;
+  icon?: string;
+  leftIcon?: string;
+  matchedExcerpt?: string;
+}
+
+export interface SearchItem {
+  id: string;
+  name: string;
+  url: string;
+  type: string;
+  key?: string;
+  rawNode: {
+    title?: string;
+    badge?: string;
+    summary?: string;
+    icon?: string;
+    leftIcon?: string;
+    matchedExcerpt?: string;
+  };
+  isFavorite?: boolean;
+}
+
+export interface SearchFilter {
+  id: string;
+  name: string;
+  count: number;
+}
+
+interface PagefindResult {
+  id: string;
+  score?: number;
+  data: () => Promise<{
+    url: string;
+    excerpt?: string;
+    content?: string;
+    meta?: Record<string, any>;
+  }>;
+}
+
+const docsPathByType: Record<string, string> = {
+  channel: 'channels',
+  command: 'commands',
+  container: 'containers',
+  'data-product': 'data-products',
+  domain: 'domains',
+  entity: 'entities',
+  event: 'events',
+  flow: 'flows',
+  query: 'queries',
+  service: 'services',
+};
+
+export const getUrlForSearchItem = (node: { href?: string }, key: string) => {
+  const parts = key.split(':');
+  if (parts.length < 2) return null;
+
+  const type = parts[0];
+  const id = parts[1];
+  const version = parts[2];
+
+  if (type === 'list') return null;
+
+  if (!version) return null;
+
+  if (node.href) return node.href;
+
+  const docsPath = docsPathByType[type];
+  if (!docsPath) return null;
+
+  return buildUrl(`/docs/${docsPath}/${id}/${version}`);
+};
+
+export const stripHtml = (value: string) =>
+  value
+    .replace(/<[^>]+>/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+const escapeHtml = (value: string) =>
+  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+
+const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const getSearchTerms = (query: string) => [...new Set(query.trim().toLowerCase().split(/\s+/).filter(Boolean))];
+
+const getMarkedTerms = (value: string) => {
+  return [...value.matchAll(/<mark>(.*?)<\/mark>/gi)].map((match) => stripHtml(match[1]).toLowerCase());
+};
+
+export const highlightQuery = (value: string, query: string) => {
+  const terms = getSearchTerms(query).sort((a, b) => b.length - a.length);
+
+  if (terms.length === 0) {
+    return escapeHtml(value);
+  }
+
+  const termLookup = new Set(terms);
+  const pattern = new RegExp(`(${terms.map(escapeRegExp).join('|')})`, 'gi');
+
+  return value
+    .split(pattern)
+    .map((part) => (termLookup.has(part.toLowerCase()) ? `<mark>${escapeHtml(part)}</mark>` : escapeHtml(part)))
+    .join('');
+};
+
+export const normalizeResultUrl = (url: string) => {
+  if (/^(https?:)?\/\//.test(url) || url.startsWith('/')) {
+    return url;
+  }
+
+  return `/${url}`;
+};
+
+export const hasMeaningfulIndexedMatch = ({
+  query,
+  title,
+  content,
+  excerpt,
+}: {
+  query: string;
+  title: string;
+  content?: string;
+  excerpt: string;
+}) => {
+  const terms = getSearchTerms(query);
+  if (terms.length === 0) {
+    return false;
+  }
+
+  const searchableText = `${title} ${content || ''}`.toLowerCase();
+  if (terms.some((term) => searchableText.includes(term))) {
+    return true;
+  }
+
+  const minimumMarkedLength = Math.min(3, Math.max(...terms.map((term) => term.length)));
+  return getMarkedTerms(excerpt).some((term) => term.length >= minimumMarkedLength);
+};
+
+export const getIndexedResultRank = ({
+  query,
+  title,
+  id,
+  url,
+  content,
+}: {
+  query: string;
+  title: string;
+  id?: string;
+  url: string;
+  content?: string;
+}) => {
+  const terms = getSearchTerms(query);
+  const titleText = title.toLowerCase();
+  const identityText = `${id || ''} ${url}`.toLowerCase();
+  const contentText = (content || '').toLowerCase();
+
+  if (terms.some((term) => titleText.includes(term))) return 3;
+  if (terms.some((term) => identityText.includes(term))) return 2;
+  if (terms.some((term) => contentText.includes(term))) return 1;
+  return 0;
+};
+
+export const applyActiveFilter = <T extends { type: string }>(items: T[], activeFilter: string) => {
+  if (activeFilter === 'all') {
+    return items;
+  }
+
+  if (activeFilter === 'Message') {
+    return items.filter((item) => ['Event', 'Command', 'Query'].includes(item.type));
+  }
+
+  if (activeFilter === 'Team') {
+    return items.filter((item) => ['Team', 'User'].includes(item.type));
+  }
+
+  return items.filter((item) => item.type === activeFilter);
+};
+
+export const getSearchFilters = ({ items, query }: { items: Array<{ type: string }>; query: string }): SearchFilter[] => {
+  if (!items.length && query !== '') {
+    return [{ id: 'all', name: 'All (0)', count: 0 }];
+  }
+
+  const counts: Record<string, number> = {
+    all: items.length,
+    Agent: 0,
+    Domain: 0,
+    Service: 0,
+    Message: 0,
+    Team: 0,
+    Container: 0,
+    Entity: 0,
+    Design: 0,
+    Channel: 0,
+    Flow: 0,
+    'Data Product': 0,
+    'Custom Doc': 0,
+    'Resource Doc': 0,
+    Changelog: 0,
+  };
+
+  items.forEach((item) => {
+    if (counts[item.type] !== undefined) {
+      counts[item.type]++;
+    }
+
+    if (['Event', 'Command', 'Query'].includes(item.type)) {
+      counts.Message++;
+    }
+
+    if (['Team', 'User'].includes(item.type)) {
+      counts.Team++;
+    }
+  });
+
+  const filters: SearchFilter[] = [{ id: 'all', name: `All (${counts.all})`, count: counts.all }];
+  const addFilter = (id: string, name: string) => {
+    if (counts[id] > 0) {
+      filters.push({ id, name: `${name} (${counts[id]})`, count: counts[id] });
+    }
+  };
+
+  addFilter('Domain', 'Domains');
+  addFilter('Agent', 'Agents');
+  addFilter('Service', 'Services');
+  addFilter('Message', 'Messages');
+  addFilter('Container', 'Data Stores');
+  addFilter('Entity', 'Entities');
+  addFilter('Channel', 'Channels');
+  addFilter('Flow', 'Flows');
+  addFilter('Data Product', 'Data Products');
+  addFilter('Custom Doc', 'Custom Docs');
+  addFilter('Resource Doc', 'Resource Docs');
+  addFilter('Changelog', 'Changelogs');
+  addFilter('Design', 'Designs');
+  addFilter('Team', 'Teams & Users');
+
+  return filters;
+};
+
+export const mapPagefindResultsToSearchItems = async ({
+  results,
+  query,
+  limit,
+}: {
+  results: PagefindResult[];
+  query: string;
+  limit: number;
+}): Promise<SearchItem[]> => {
+  const mappedResults = await Promise.all(
+    results.slice(0, limit).map(async (result, resultIndex) => {
+      const data = await result.data();
+      const meta = data.meta || {};
+      const type = meta.type || 'Page';
+      const title = meta.title || data.url || 'Untitled';
+      const summary = meta.summary || stripHtml(data.excerpt || '');
+      const url = normalizeResultUrl(data.url);
+
+      if (
+        !hasMeaningfulIndexedMatch({
+          query,
+          title,
+          content: data.content,
+          excerpt: data.excerpt || '',
+        })
+      ) {
+        return null;
+      }
+
+      return {
+        item: {
+          id: result.id,
+          name: title,
+          url,
+          type,
+          rawNode: {
+            title,
+            badge: type,
+            summary,
+            matchedExcerpt: data.excerpt || summary,
+          },
+        } satisfies SearchItem,
+        resultIndex,
+        rank: getIndexedResultRank({
+          query,
+          title,
+          id: meta.id,
+          url,
+          content: data.content,
+        }),
+        score: typeof result.score === 'number' ? result.score : 0,
+      };
+    })
+  );
+
+  return mappedResults
+    .filter((result): result is NonNullable<typeof result> => result !== null)
+    .sort((a, b) => b.rank - a.rank || b.score - a.score || a.resultIndex - b.resultIndex)
+    .map((result) => result.item);
+};
diff --git a/eventcatalog/src/components/Seo.astro b/packages/core/eventcatalog/src/components/Seo.astro
similarity index 80%
rename from eventcatalog/src/components/Seo.astro
rename to packages/core/eventcatalog/src/components/Seo.astro
index 4189a5f8c..0b0bf60c6 100644
--- a/eventcatalog/src/components/Seo.astro
+++ b/packages/core/eventcatalog/src/components/Seo.astro
@@ -25,7 +25,11 @@ if (typeof _image === 'string') {
 <meta charset="UTF-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 <meta name="viewport" content="width=device-width" />
-<link rel="icon" type="image/svg+xml" href={buildUrl('/favicon.ico', true)} />
+<link rel="icon" href={buildUrl('/favicon.ico', true)} sizes="any" />
+<link rel="icon" type="image/svg+xml" href={buildUrl('/favicon.svg', true)} />
+<link rel="icon" type="image/png" sizes="32x32" href={buildUrl('/favicon-32x32.png', true)} />
+<link rel="icon" type="image/png" sizes="16x16" href={buildUrl('/favicon-16x16.png', true)} />
+<link rel="apple-touch-icon" href={buildUrl('/apple-touch-icon.png', true)} />
 
 <SEO
   title={title}
diff --git a/packages/core/eventcatalog/src/components/Settings/AssistantSettingsForm.tsx b/packages/core/eventcatalog/src/components/Settings/AssistantSettingsForm.tsx
new file mode 100644
index 000000000..16433964a
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Settings/AssistantSettingsForm.tsx
@@ -0,0 +1,218 @@
+import { useEffect, useState } from 'react';
+import { Toaster, toast } from 'sonner';
+import { ExternalLink, MessageSquare, ServerCog, Wrench } from 'lucide-react';
+import { aiSettingsSchema } from '@utils/eventcatalog-config/config-schema';
+import { ReadOnlyBanner } from './ReadOnlyBanner';
+import { Row, cn } from './Row';
+import { ASSISTANT_CONFIGURATION_DOCS_URL, ASSISTANT_DOCS_URL, ToggleRow, UpgradeRequired } from './SettingsShared';
+
+interface Props {
+  canEdit: boolean;
+  initial: { chatEnabled: boolean; llmsTxtEnabled: boolean };
+  chatAvailable: boolean;
+  hasPlan: boolean;
+  inSSR: boolean;
+  hasChatConfigFile: boolean;
+  apiBase: string;
+}
+
+export const AssistantSettingsForm = ({ canEdit, initial, chatAvailable, hasPlan, inSSR, hasChatConfigFile, apiBase }: Props) => {
+  const [chatEnabled, setChatEnabled] = useState(initial.chatEnabled);
+  const [pristine, setPristine] = useState(initial.chatEnabled);
+  const [saving, setSaving] = useState(false);
+
+  const dirty = chatEnabled !== pristine;
+
+  useEffect(() => {
+    if (!dirty) return;
+    const handler = (e: BeforeUnloadEvent) => {
+      e.preventDefault();
+      e.returnValue = '';
+    };
+    window.addEventListener('beforeunload', handler);
+    return () => window.removeEventListener('beforeunload', handler);
+  }, [dirty]);
+
+  const save = async () => {
+    if (!canEdit) return;
+    const candidate = aiSettingsSchema.safeParse({
+      llmsTxtEnabled: initial.llmsTxtEnabled,
+      chatEnabled,
+    });
+    if (!candidate.success) {
+      toast.error('Invalid settings');
+      return;
+    }
+    setSaving(true);
+    try {
+      const res = await fetch(`${apiBase}/ai`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(candidate.data),
+      });
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        toast.error(body.error || 'Could not save');
+        return;
+      }
+      setPristine(chatEnabled);
+      toast.success('Saved to eventcatalog.config.js');
+    } catch (err) {
+      toast.error(`Could not save: ${(err as Error).message}`);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <form onSubmit={(e) => e.preventDefault()} className="divide-y divide-[rgb(var(--ec-page-border))]">
+      <Toaster richColors closeButton position="bottom-right" theme="system" />
+      {!canEdit && (
+        <div className="pb-6">
+          <ReadOnlyBanner />
+        </div>
+      )}
+
+      <Row
+        title="Assistant Agent"
+        description="Assistant agent that answers questions about your architecture directly in your catalog."
+        canEdit={canEdit && chatAvailable}
+        dirty={dirty}
+        saving={saving}
+        onSave={chatAvailable ? save : undefined}
+      >
+        {chatAvailable ? (
+          <div className="space-y-3">
+            <ToggleRow
+              icon={<MessageSquare className="h-4 w-4" aria-hidden />}
+              label={chatEnabled ? 'Enabled' : 'Disabled'}
+              hint={chatEnabled ? 'Chat is available to readers of this catalog.' : 'Chat is hidden from the catalog.'}
+              checked={chatEnabled}
+              disabled={!canEdit}
+              onChange={setChatEnabled}
+            />
+            {chatEnabled && <ConfigurationRequired />}
+          </div>
+        ) : !hasPlan ? (
+          <UpgradeRequired
+            tier="Starter and Scale"
+            blurb="The EventCatalog Assistant is part of our paid plans. Upgrade to give your team a built-in AI agent that answers questions about your architecture."
+            docsUrl={ASSISTANT_DOCS_URL}
+          />
+        ) : !inSSR ? (
+          <AssistantNeedsSSR />
+        ) : !hasChatConfigFile ? (
+          <AssistantNeedsConfigFile />
+        ) : null}
+      </Row>
+    </form>
+  );
+};
+
+const ConfigurationRequired = () => (
+  <div className="rounded-lg border border-[rgb(var(--ec-accent)/0.4)] bg-[rgb(var(--ec-accent)/0.06)] px-4 py-3">
+    <div className="flex items-start gap-3">
+      <span className="flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-md border border-[rgb(var(--ec-accent)/0.4)] bg-[rgb(var(--ec-accent)/0.1)] text-[rgb(var(--ec-accent))]">
+        <Wrench className="h-3.5 w-3.5" aria-hidden />
+      </span>
+      <div className="flex-1 min-w-0">
+        <p className="text-[13px] font-medium text-[rgb(var(--ec-page-text))]">Configuration required</p>
+        <p className="mt-0.5 text-[12px] leading-snug text-[rgb(var(--ec-page-text-muted))]">
+          The Agent needs an{' '}
+          <code className="rounded bg-[rgb(var(--ec-page-bg))] px-1 py-0.5 font-mono text-[11px]">eventcatalog.chat.js</code> file
+          and a model provider (bring your own model). Follow the configuration guide to set it up.
+        </p>
+        <a
+          href={ASSISTANT_CONFIGURATION_DOCS_URL}
+          target="_blank"
+          rel="noreferrer"
+          className={cn(
+            'mt-2 inline-flex items-center gap-1 text-[12px] font-medium text-[rgb(var(--ec-accent))] hover:underline'
+          )}
+        >
+          Configure the Agent
+          <ExternalLink className="h-3 w-3" aria-hidden />
+        </a>
+      </div>
+    </div>
+  </div>
+);
+
+const AssistantNeedsSSR = () => (
+  <div className="overflow-hidden rounded-lg border border-[rgb(var(--ec-accent)/0.4)] bg-gradient-to-br from-[rgb(var(--ec-accent)/0.1)] via-[rgb(var(--ec-accent)/0.05)] to-transparent">
+    <div className="flex items-start gap-3 px-4 py-3.5">
+      <span className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-md border border-[rgb(var(--ec-accent)/0.4)] bg-[rgb(var(--ec-accent)/0.1)] text-[rgb(var(--ec-accent))]">
+        <ServerCog className="h-4 w-4" aria-hidden />
+      </span>
+      <div className="flex-1 min-w-0">
+        <div className="flex items-center gap-2">
+          <p className="text-[13px] font-semibold text-[rgb(var(--ec-page-text))]">Server output mode required</p>
+          <span className="inline-flex items-center gap-1 rounded-full border border-[rgb(var(--ec-accent)/0.4)] bg-[rgb(var(--ec-accent)/0.1)] px-1.5 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-[rgb(var(--ec-accent))]">
+            SSR
+          </span>
+        </div>
+        <p className="mt-1 text-[12px] leading-snug text-[rgb(var(--ec-page-text-muted))]">
+          The Agent requires your catalog to run in server (SSR) mode. Follow the configuration guide to switch.
+        </p>
+        <div className="mt-3 flex flex-wrap items-center gap-3">
+          <a
+            href={ASSISTANT_CONFIGURATION_DOCS_URL}
+            target="_blank"
+            rel="noreferrer"
+            className="inline-flex items-center gap-1 rounded-md bg-[rgb(var(--ec-accent))] px-3 py-1.5 text-[12px] font-semibold text-white shadow-sm transition-colors hover:bg-[rgb(var(--ec-accent-hover))]"
+          >
+            Configuration guide
+            <ExternalLink className="h-3 w-3" aria-hidden />
+          </a>
+          <a
+            href={ASSISTANT_DOCS_URL}
+            target="_blank"
+            rel="noreferrer"
+            className="inline-flex items-center gap-1 text-[12px] font-medium text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]"
+          >
+            Learn more
+            <ExternalLink className="h-3 w-3" aria-hidden />
+          </a>
+        </div>
+      </div>
+    </div>
+  </div>
+);
+
+const AssistantNeedsConfigFile = () => (
+  <div className="overflow-hidden rounded-lg border border-[rgb(var(--ec-accent)/0.4)] bg-gradient-to-br from-[rgb(var(--ec-accent)/0.1)] via-[rgb(var(--ec-accent)/0.05)] to-transparent">
+    <div className="flex items-start gap-3 px-4 py-3.5">
+      <span className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-md border border-[rgb(var(--ec-accent)/0.4)] bg-[rgb(var(--ec-accent)/0.1)] text-[rgb(var(--ec-accent))]">
+        <Wrench className="h-4 w-4" aria-hidden />
+      </span>
+      <div className="flex-1 min-w-0">
+        <p className="text-[13px] font-semibold text-[rgb(var(--ec-page-text))]">Add an eventcatalog.chat.js file</p>
+        <p className="mt-1 text-[12px] leading-snug text-[rgb(var(--ec-page-text-muted))]">
+          The Agent needs an{' '}
+          <code className="rounded bg-[rgb(var(--ec-page-bg))] px-1 py-0.5 font-mono text-[11px]">eventcatalog.chat.js</code> file
+          in your catalog directory and a model provider (bring your own model) before it can answer questions.
+        </p>
+        <div className="mt-3 flex flex-wrap items-center gap-3">
+          <a
+            href={ASSISTANT_CONFIGURATION_DOCS_URL}
+            target="_blank"
+            rel="noreferrer"
+            className="inline-flex items-center gap-1 rounded-md bg-[rgb(var(--ec-accent))] px-3 py-1.5 text-[12px] font-semibold text-white shadow-sm transition-colors hover:bg-[rgb(var(--ec-accent-hover))]"
+          >
+            Configuration guide
+            <ExternalLink className="h-3 w-3" aria-hidden />
+          </a>
+          <a
+            href={ASSISTANT_DOCS_URL}
+            target="_blank"
+            rel="noreferrer"
+            className="inline-flex items-center gap-1 text-[12px] font-medium text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]"
+          >
+            Learn more
+            <ExternalLink className="h-3 w-3" aria-hidden />
+          </a>
+        </div>
+      </div>
+    </div>
+  </div>
+);
diff --git a/packages/core/eventcatalog/src/components/Settings/BillingSettingsForm.tsx b/packages/core/eventcatalog/src/components/Settings/BillingSettingsForm.tsx
new file mode 100644
index 000000000..e46190b03
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Settings/BillingSettingsForm.tsx
@@ -0,0 +1,265 @@
+import { ArrowUpRight, Check } from 'lucide-react';
+import { Row, cn } from './Row';
+import { PRICING_URL } from './SettingsShared';
+
+export type PlanId = 'community' | 'starter' | 'scale' | 'enterprise';
+
+interface Props {
+  currentPlan: PlanId;
+}
+
+interface Plan {
+  id: PlanId;
+  name: string;
+  tagline: string;
+  price: string;
+  priceSuffix?: string;
+  audience: string;
+  features: string[];
+  ctaLabel: string;
+  ctaHref: string;
+  /** Visual accent applied to selected/featured cards. */
+  accent?: 'default' | 'highlight';
+}
+
+const PLANS: Plan[] = [
+  {
+    id: 'community',
+    name: 'Community',
+    tagline: 'Open source. Self-hosted.',
+    price: 'Free',
+    audience: 'For individuals and open source projects.',
+    features: [
+      'Document domains, services, events, commands and queries',
+      'Visualize your architecture',
+      'Public schema fetch & sync',
+      'Schema Explorer (Basic)',
+      'Owners, versioning, and flows',
+      'Community support (Discord)',
+    ],
+    ctaLabel: 'Get started',
+    ctaHref: PRICING_URL,
+  },
+  {
+    id: 'starter',
+    name: 'Starter',
+    tagline: 'For teams customising and scaling.',
+    price: '$199',
+    priceSuffix: '/month',
+    audience: 'Up to 20 active users.',
+    features: [
+      'Everything in Community',
+      'Custom landing page',
+      'Bring your own documentation',
+      'Embed Miro, IcePanel, Lucid, DrawIO, FigJam',
+      'EventCatalog Assistant',
+      'Remove EventCatalog branding',
+      'Custom themes',
+      'Email support',
+    ],
+    ctaLabel: 'Try Starter for 14 days',
+    ctaHref: 'https://eventcatalog.cloud',
+  },
+  {
+    id: 'scale',
+    name: 'Scale',
+    tagline: 'For platform teams managing multiple catalogs.',
+    price: '$399',
+    priceSuffix: '/month',
+    audience: 'Up to 50 active users.',
+    accent: 'highlight',
+    features: [
+      'Everything in Starter',
+      'Field Intelligence',
+      'Resource-level documentation',
+      'EventCatalog MCP server',
+      'Architecture Change Detection',
+      'Private schema fetch & sync',
+      'GitHub authentication',
+      'Federate up to 3 catalogs',
+      'Custom tools for AI Assistant',
+      'Slack bot integration',
+    ],
+    ctaLabel: 'Try Scale for 14 days',
+    ctaHref: 'https://eventcatalog.cloud',
+  },
+  {
+    id: 'enterprise',
+    name: 'Enterprise',
+    tagline: 'For complex systems and regulated environments.',
+    price: 'Contact us',
+    audience: 'Unlimited users, all integrations included.',
+    features: [
+      'Everything in Scale',
+      'Unlimited users',
+      'Unlimited integrations',
+      'SSO & SAML',
+      'Advanced governance & audit logging',
+      'Migration & onboarding support',
+      'Dedicated account manager',
+    ],
+    ctaLabel: 'Schedule a call',
+    ctaHref: 'mailto:hello@eventcatalog.dev?subject=Enterprise%20Plan%20Enquiry',
+  },
+];
+
+const PLAN_LABELS: Record<PlanId, string> = {
+  community: 'Community',
+  starter: 'Starter',
+  scale: 'Scale',
+  enterprise: 'Enterprise',
+};
+
+const PLAN_RANK: Record<PlanId, number> = {
+  community: 0,
+  starter: 1,
+  scale: 2,
+  enterprise: 3,
+};
+
+export const BillingSettingsForm = ({ currentPlan }: Props) => {
+  const isPaid = currentPlan === 'starter' || currentPlan === 'scale' || currentPlan === 'enterprise';
+  const upgradable = currentPlan !== 'enterprise';
+  // Show the current plan and any tier above it. Hides plans the user has already passed.
+  const visiblePlans = PLANS.filter((plan) => PLAN_RANK[plan.id] >= PLAN_RANK[currentPlan]);
+  const gridCols =
+    visiblePlans.length === 1 ? 'grid-cols-1' : visiblePlans.length === 2 ? 'lg:grid-cols-2' : 'lg:grid-cols-2 xl:grid-cols-3';
+
+  return (
+    <div className="divide-y divide-[rgb(var(--ec-page-border))]">
+      <Row
+        title="Billing plan"
+        description="View and manage your billing plan. Paid plans unlock the AI assistant, with MCP server and other advanced features available on Scale."
+        canEdit={false}
+        dirty={false}
+      >
+        <div className="flex flex-wrap items-center gap-3 rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-input-bg,var(--ec-page-bg)))] px-4 py-3">
+          <div className="flex items-center gap-2 text-[13px] text-[rgb(var(--ec-page-text))]">
+            <span className="text-[rgb(var(--ec-page-text-muted))]">Current plan:</span>
+            <span className="font-semibold">{PLAN_LABELS[currentPlan]}</span>
+            {isPaid && (
+              <span className="rounded-full border border-emerald-500/30 bg-emerald-500/10 px-1.5 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-emerald-500">
+                Active
+              </span>
+            )}
+          </div>
+          <div className="ml-auto">
+            {upgradable ? (
+              <a
+                href={PRICING_URL}
+                target="_blank"
+                rel="noreferrer"
+                className="inline-flex items-center gap-1 rounded-md bg-[rgb(var(--ec-page-text))] px-3 py-1.5 text-[12px] font-semibold text-[rgb(var(--ec-page-bg))] transition-opacity hover:opacity-90"
+              >
+                Upgrade
+                <ArrowUpRight className="h-3 w-3" aria-hidden />
+              </a>
+            ) : (
+              <a
+                href={PRICING_URL}
+                target="_blank"
+                rel="noreferrer"
+                className="inline-flex items-center gap-1 rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] px-3 py-1.5 text-[12px] font-medium text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-page-bg)/0.78)]"
+              >
+                Manage billing
+                <ArrowUpRight className="h-3 w-3" aria-hidden />
+              </a>
+            )}
+          </div>
+        </div>
+      </Row>
+
+      <Row
+        title={upgradable ? 'Upgrade' : 'Your plan'}
+        description={
+          upgradable
+            ? 'Plans available to upgrade to. Pricing shown in USD; visit our website for EUR pricing and the full feature comparison.'
+            : 'You are on our highest tier. Visit the website for the full feature comparison.'
+        }
+        canEdit={false}
+        dirty={false}
+      >
+        <div className={cn('grid grid-cols-1 gap-3', gridCols)}>
+          {visiblePlans.map((plan) => (
+            <PlanCard key={plan.id} plan={plan} isCurrent={plan.id === currentPlan} />
+          ))}
+        </div>
+        <p className="mt-4 text-[12px] text-[rgb(var(--ec-page-text-muted))]">
+          Prices update with annual billing.{' '}
+          <a href={PRICING_URL} target="_blank" rel="noreferrer" className="text-[rgb(var(--ec-accent))] hover:underline">
+            See full plan comparison →
+          </a>
+        </p>
+      </Row>
+    </div>
+  );
+};
+
+interface PlanCardProps {
+  plan: Plan;
+  isCurrent: boolean;
+}
+
+const PlanCard = ({ plan, isCurrent }: PlanCardProps) => (
+  <div
+    className={cn(
+      'flex flex-col rounded-xl border p-5 transition-colors',
+      isCurrent
+        ? 'border-[rgb(var(--ec-accent)/0.5)] bg-[rgb(var(--ec-accent-subtle)/0.4)]'
+        : plan.accent === 'highlight'
+          ? 'border-[rgb(var(--ec-page-text)/0.25)] bg-[rgb(var(--ec-input-bg,var(--ec-page-bg)))]'
+          : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-input-bg,var(--ec-page-bg)))]'
+    )}
+  >
+    <div className="flex items-start justify-between gap-2">
+      <div>
+        <p className="text-[13px] font-semibold text-[rgb(var(--ec-page-text))]">{plan.name}</p>
+        <p className="mt-0.5 text-[12px] leading-snug text-[rgb(var(--ec-page-text-muted))]">{plan.tagline}</p>
+      </div>
+      {isCurrent && (
+        <span className="rounded-full border border-[rgb(var(--ec-accent)/0.4)] bg-[rgb(var(--ec-accent-subtle))] px-2 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-[rgb(var(--ec-accent-text))]">
+          Current
+        </span>
+      )}
+      {!isCurrent && plan.accent === 'highlight' && (
+        <span className="rounded-full border border-amber-500/40 bg-amber-500/10 px-2 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-amber-500">
+          Popular
+        </span>
+      )}
+    </div>
+
+    <div className="mt-4">
+      <span className="text-[24px] font-semibold leading-none tracking-tight text-[rgb(var(--ec-page-text))]">{plan.price}</span>
+      {plan.priceSuffix && <span className="ml-1 text-[12px] text-[rgb(var(--ec-page-text-muted))]">{plan.priceSuffix}</span>}
+      <p className="mt-1 text-[11px] text-[rgb(var(--ec-page-text-muted))]">{plan.audience}</p>
+    </div>
+
+    <a
+      href={plan.ctaHref}
+      target="_blank"
+      rel="noreferrer"
+      aria-disabled={isCurrent}
+      onClick={isCurrent ? (e) => e.preventDefault() : undefined}
+      className={cn(
+        'mt-4 inline-flex items-center justify-center gap-1 rounded-md px-3 py-1.5 text-[12px] font-semibold transition-colors',
+        isCurrent
+          ? 'pointer-events-none cursor-default border border-[rgb(var(--ec-page-border))] bg-transparent text-[rgb(var(--ec-page-text-muted))]'
+          : plan.accent === 'highlight'
+            ? 'bg-[rgb(var(--ec-page-text))] text-[rgb(var(--ec-page-bg))] hover:opacity-90'
+            : 'border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-page-bg)/0.78)]'
+      )}
+    >
+      {isCurrent ? 'Current plan' : plan.ctaLabel}
+      {!isCurrent && <ArrowUpRight className="h-3 w-3" aria-hidden />}
+    </a>
+
+    <ul className="mt-5 space-y-1.5">
+      {plan.features.map((feature) => (
+        <li key={feature} className="flex items-start gap-2 text-[12px] leading-snug text-[rgb(var(--ec-page-text))]">
+          <Check className="mt-0.5 h-3 w-3 flex-shrink-0 text-[rgb(var(--ec-page-text-muted))]" aria-hidden />
+          <span>{feature}</span>
+        </li>
+      ))}
+    </ul>
+  </div>
+);
diff --git a/packages/core/eventcatalog/src/components/Settings/GeneralSettingsForm.tsx b/packages/core/eventcatalog/src/components/Settings/GeneralSettingsForm.tsx
new file mode 100644
index 000000000..ae1af408d
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Settings/GeneralSettingsForm.tsx
@@ -0,0 +1,371 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Toaster, toast } from 'sonner';
+import { Check } from 'lucide-react';
+import {
+  generalSettingsSchema,
+  KNOWN_THEMES,
+  isKnownTheme,
+  type GeneralSettings,
+} from '@utils/eventcatalog-config/config-schema';
+import { ReadOnlyBanner } from './ReadOnlyBanner';
+import { LogoUpload } from './LogoUpload';
+import { Row, cn, inputBase, inputError, monoInput } from './Row';
+
+interface Props {
+  canEdit: boolean;
+  initial: GeneralSettings & { logo?: { src?: string } };
+  apiBase: string;
+}
+
+interface FormState {
+  organization: string;
+  tagline: string;
+  homepageLink: string;
+  editUrl: string;
+  repositoryUrl: string;
+  theme: string;
+}
+
+type FieldKey = keyof FormState;
+
+const toFormState = (s: GeneralSettings): FormState => ({
+  organization: s.organizationName ?? s.title ?? s.logo?.text ?? '',
+  tagline: s.tagline ?? '',
+  homepageLink: s.homepageLink ?? '',
+  editUrl: s.editUrl ?? '',
+  repositoryUrl: s.repositoryUrl ?? '',
+  theme: s.theme || 'default',
+});
+
+const themeOptions = (currentTheme: string): string[] => {
+  const known = [...KNOWN_THEMES];
+  if (currentTheme && !isKnownTheme(currentTheme)) {
+    return [...known, currentTheme];
+  }
+  return known;
+};
+
+const THEME_PREVIEWS: Record<string, { accent: string; bg: string; label: string }> = {
+  default: { accent: '#6366f1', bg: '#0b0b0f', label: 'Default' },
+  ocean: { accent: '#06b6d4', bg: '#082431', label: 'Ocean' },
+  sapphire: { accent: '#3b82f6', bg: '#0b1430', label: 'Sapphire' },
+  sunset: { accent: '#f97316', bg: '#2a0f0a', label: 'Sunset' },
+  forest: { accent: '#22c55e', bg: '#0c1f12', label: 'Forest' },
+};
+
+const ensureUrlScheme = (value: string): string => {
+  const v = value.trim();
+  if (!v) return '';
+  if (/^https?:\/\//i.test(v)) return v;
+  return `https://${v}`;
+};
+
+export const GeneralSettingsForm = ({ canEdit, initial, apiBase }: Props) => {
+  const [form, setForm] = useState<FormState>(() => toFormState(initial));
+  const [pristine, setPristine] = useState<FormState>(() => toFormState(initial));
+  const [errors, setErrors] = useState<Partial<Record<FieldKey, string>>>({});
+  const [savingKey, setSavingKey] = useState<FieldKey | null>(null);
+  const originalThemeRef = useRef<string>(initial.theme || 'default');
+
+  const dirtyKeys = useMemo<Set<FieldKey>>(() => {
+    const s = new Set<FieldKey>();
+    (Object.keys(form) as FieldKey[]).forEach((k) => {
+      if (form[k] !== pristine[k]) s.add(k);
+    });
+    return s;
+  }, [form, pristine]);
+
+  const isFormDirty = dirtyKeys.size > 0;
+
+  // Live theme preview; revert on unmount if not saved.
+  useEffect(() => {
+    if (!canEdit) return;
+    document.documentElement.setAttribute('data-catalog-theme', form.theme || 'default');
+    return () => {
+      document.documentElement.setAttribute('data-catalog-theme', originalThemeRef.current || 'default');
+    };
+  }, [form.theme, canEdit]);
+
+  // beforeunload guard while any field is dirty.
+  useEffect(() => {
+    if (!isFormDirty) return;
+    const handler = (e: BeforeUnloadEvent) => {
+      e.preventDefault();
+      e.returnValue = '';
+    };
+    window.addEventListener('beforeunload', handler);
+    return () => window.removeEventListener('beforeunload', handler);
+  }, [isFormDirty]);
+
+  const setField = (key: FieldKey, value: string) => {
+    setForm((prev) => ({ ...prev, [key]: value }));
+    setErrors((prev) => ({ ...prev, [key]: undefined }));
+  };
+
+  const handleChange = (key: FieldKey) => (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) =>
+    setField(key, e.target.value);
+
+  const handleUrlBlur = (key: 'homepageLink' | 'editUrl' | 'repositoryUrl') => () => {
+    setForm((prev) => ({ ...prev, [key]: ensureUrlScheme(prev[key]) }));
+  };
+
+  const validateAll = (): { ok: true } | { ok: false; errors: Partial<Record<FieldKey, string>> } => {
+    const candidate = {
+      title: form.organization,
+      tagline: form.tagline,
+      organizationName: form.organization,
+      homepageLink: form.homepageLink,
+      editUrl: form.editUrl,
+      repositoryUrl: form.repositoryUrl,
+      logo: { text: form.organization },
+      theme: form.theme,
+    };
+    const parsed = generalSettingsSchema.safeParse(candidate);
+    if (parsed.success) return { ok: true };
+    const next: Partial<Record<FieldKey, string>> = {};
+    for (const issue of parsed.error.issues) {
+      const [key] = issue.path as string[];
+      if (key === 'title' || key === 'organizationName' || key === 'logo') next.organization = issue.message;
+      else if (key === 'tagline') next.tagline = issue.message;
+      else if (key === 'homepageLink') next.homepageLink = issue.message;
+      else if (key === 'editUrl') next.editUrl = issue.message;
+      else if (key === 'repositoryUrl') next.repositoryUrl = issue.message;
+      else if (key === 'theme') next.theme = issue.message;
+    }
+    return { ok: false, errors: next };
+  };
+
+  // Per-row save: validate the whole form, but only block on errors that
+  // affect the row being saved. The API still receives the full payload.
+  const saveRow = async (key: FieldKey) => {
+    if (!canEdit) return;
+    const result = validateAll();
+    if (!result.ok && result.errors[key]) {
+      setErrors((prev) => ({ ...prev, [key]: result.errors[key] }));
+      toast.error(result.errors[key] || 'Please fix the highlighted field');
+      return;
+    }
+
+    setSavingKey(key);
+    try {
+      const payload = {
+        title: form.organization,
+        organizationName: form.organization,
+        logo: { text: form.organization },
+        tagline: form.tagline || undefined,
+        homepageLink: form.homepageLink || undefined,
+        editUrl: form.editUrl || undefined,
+        repositoryUrl: form.repositoryUrl || undefined,
+        theme: form.theme,
+      };
+      const res = await fetch(`${apiBase}/general`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+      });
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        toast.error(body.error || 'Could not save');
+        return;
+      }
+      setPristine(form);
+      originalThemeRef.current = form.theme;
+      toast.success('Saved to eventcatalog.config.js');
+    } catch (err) {
+      toast.error(`Could not save: ${(err as Error).message}`);
+    } finally {
+      setSavingKey(null);
+    }
+  };
+
+  return (
+    <form onSubmit={(e) => e.preventDefault()} className="divide-y divide-[rgb(var(--ec-page-border))]">
+      <Toaster richColors closeButton position="bottom-right" theme="system" />
+      {!canEdit && (
+        <div className="pb-6">
+          <ReadOnlyBanner />
+        </div>
+      )}
+
+      <Row
+        title="Theme"
+        description="Pick a built-in colour theme. Selection updates the preview live; click Save to persist."
+        canEdit={canEdit}
+        dirty={dirtyKeys.has('theme')}
+        saving={savingKey === 'theme'}
+        onSave={() => saveRow('theme')}
+        error={errors.theme}
+      >
+        <div className="grid grid-cols-2 gap-3 sm:grid-cols-3">
+          {themeOptions(form.theme).map((t) => {
+            const preview = THEME_PREVIEWS[t] ?? { accent: '#888', bg: '#1a1a1a', label: t };
+            const isActive = form.theme === t;
+            const isCustom = !isKnownTheme(t);
+            return (
+              <button
+                type="button"
+                key={t}
+                onClick={() => setField('theme', t)}
+                disabled={!canEdit}
+                aria-pressed={isActive}
+                className={cn(
+                  'group relative flex flex-col overflow-hidden rounded-lg border text-left transition-all',
+                  'disabled:cursor-not-allowed disabled:opacity-50',
+                  isActive
+                    ? 'border-[rgb(var(--ec-accent))] ring-2 ring-[rgb(var(--ec-accent)/0.25)]'
+                    : 'border-[rgb(var(--ec-page-border))] hover:border-[rgb(var(--ec-page-text-muted)/0.6)]'
+                )}
+              >
+                <div className="relative h-14 w-full overflow-hidden" style={{ background: preview.bg }}>
+                  <div
+                    className="absolute -bottom-2 -right-2 h-12 w-12 rounded-full opacity-90 blur-md"
+                    style={{ background: preview.accent }}
+                    aria-hidden
+                  />
+                  <div
+                    className="absolute left-3 top-3 h-1.5 w-10 rounded-full opacity-90"
+                    style={{ background: preview.accent }}
+                    aria-hidden
+                  />
+                  <div
+                    className="absolute left-3 top-6 h-1 w-7 rounded-full opacity-60"
+                    style={{ background: 'rgba(255,255,255,0.4)' }}
+                    aria-hidden
+                  />
+                  {isActive && (
+                    <span className="absolute right-1.5 top-1.5 flex h-4 w-4 items-center justify-center rounded-full bg-white text-black shadow-sm">
+                      <Check className="h-2.5 w-2.5" aria-hidden />
+                    </span>
+                  )}
+                </div>
+                <div className="flex items-center justify-between gap-2 px-3 py-2">
+                  <span className="text-[12px] font-medium capitalize text-[rgb(var(--ec-page-text))]">{preview.label}</span>
+                  {isCustom && (
+                    <span className="rounded-full border border-[rgb(var(--ec-page-border))] px-1.5 py-0.5 text-[10px] uppercase tracking-wide text-[rgb(var(--ec-page-text-muted))]">
+                      custom
+                    </span>
+                  )}
+                </div>
+              </button>
+            );
+          })}
+        </div>
+      </Row>
+
+      <Row
+        title="Organization"
+        description="Used as the catalog name, the brand line next to the logo, and OpenGraph metadata."
+        canEdit={canEdit}
+        dirty={dirtyKeys.has('organization')}
+        saving={savingKey === 'organization'}
+        onSave={() => saveRow('organization')}
+        error={errors.organization}
+      >
+        <input
+          type="text"
+          value={form.organization}
+          onChange={handleChange('organization')}
+          disabled={!canEdit}
+          maxLength={100}
+          placeholder="Acme Inc."
+          className={cn(inputBase, errors.organization && inputError)}
+          required
+        />
+      </Row>
+
+      <Row
+        title="Tagline"
+        description="A short subtitle shown beneath the organization name on the homepage."
+        canEdit={canEdit}
+        dirty={dirtyKeys.has('tagline')}
+        saving={savingKey === 'tagline'}
+        onSave={() => saveRow('tagline')}
+        error={errors.tagline}
+      >
+        <textarea
+          value={form.tagline}
+          onChange={handleChange('tagline')}
+          disabled={!canEdit}
+          maxLength={500}
+          rows={2}
+          placeholder="Discover and explore our events, services, and architecture."
+          className={cn(inputBase, 'resize-y', errors.tagline && inputError)}
+        />
+      </Row>
+
+      <Row
+        title="Homepage link"
+        description="Where the logo links to. Useful for pointing back to your main site."
+        canEdit={canEdit}
+        dirty={dirtyKeys.has('homepageLink')}
+        saving={savingKey === 'homepageLink'}
+        onSave={() => saveRow('homepageLink')}
+        error={errors.homepageLink}
+      >
+        <input
+          type="url"
+          value={form.homepageLink}
+          onChange={handleChange('homepageLink')}
+          onBlur={handleUrlBlur('homepageLink')}
+          disabled={!canEdit}
+          placeholder="https://example.com"
+          className={cn(inputBase, monoInput, errors.homepageLink && inputError)}
+        />
+      </Row>
+
+      <Row
+        title="Edit URL"
+        description="Base URL for the “Edit on GitHub” links shown on resource pages."
+        canEdit={canEdit}
+        dirty={dirtyKeys.has('editUrl')}
+        saving={savingKey === 'editUrl'}
+        onSave={() => saveRow('editUrl')}
+        error={errors.editUrl}
+      >
+        <input
+          type="url"
+          value={form.editUrl}
+          onChange={handleChange('editUrl')}
+          onBlur={handleUrlBlur('editUrl')}
+          disabled={!canEdit}
+          placeholder="https://github.com/org/repo/edit/main"
+          className={cn(inputBase, monoInput, errors.editUrl && inputError)}
+        />
+      </Row>
+
+      <Row
+        title="Repository URL"
+        description="Link to your catalog's source repository. Shown in the header for quick navigation back to the code."
+        canEdit={canEdit}
+        dirty={dirtyKeys.has('repositoryUrl')}
+        saving={savingKey === 'repositoryUrl'}
+        onSave={() => saveRow('repositoryUrl')}
+        error={errors.repositoryUrl}
+      >
+        <input
+          type="url"
+          value={form.repositoryUrl}
+          onChange={handleChange('repositoryUrl')}
+          onBlur={handleUrlBlur('repositoryUrl')}
+          disabled={!canEdit}
+          placeholder="https://github.com/org/repo"
+          className={cn(inputBase, monoInput, errors.repositoryUrl && inputError)}
+        />
+      </Row>
+
+      <Row
+        title="Logo"
+        description="Image shown in the top-left corner. PNG, JPG, SVG, or WebP up to 2MB."
+        canEdit={canEdit}
+        // Logo upload saves itself directly; no inline Save button needed.
+        dirty={false}
+      >
+        <LogoUpload
+          canEdit={canEdit}
+          initialSrc={initial.logo?.src ? `${initial.logo.src}?t=${Date.now()}` : undefined}
+          apiUrl={`${apiBase}/logo`}
+        />
+      </Row>
+    </form>
+  );
+};
diff --git a/packages/core/eventcatalog/src/components/Settings/LlmAccessSettingsForm.tsx b/packages/core/eventcatalog/src/components/Settings/LlmAccessSettingsForm.tsx
new file mode 100644
index 000000000..b4e78cc5e
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Settings/LlmAccessSettingsForm.tsx
@@ -0,0 +1,181 @@
+import { useEffect, useState } from 'react';
+import { Toaster, toast } from 'sonner';
+import { Bot, FileText } from 'lucide-react';
+import { aiSettingsSchema } from '@utils/eventcatalog-config/config-schema';
+import { ReadOnlyBanner } from './ReadOnlyBanner';
+import { Row } from './Row';
+import { ToggleRow, UpgradeRequired, UrlPanel } from './SettingsShared';
+
+interface Props {
+  canEdit: boolean;
+  initial: { llmsTxtEnabled: boolean; chatEnabled: boolean };
+  hasScalePlan: boolean;
+  apiBase: string;
+  llmsTxtUrl: string;
+  llmsFullTxtUrl: string;
+  schemasTxtUrl: string;
+}
+
+export const LlmAccessSettingsForm = ({
+  canEdit,
+  initial,
+  hasScalePlan,
+  apiBase,
+  llmsTxtUrl,
+  llmsFullTxtUrl,
+  schemasTxtUrl,
+}: Props) => {
+  const [llmsTxtEnabled, setLlmsTxtEnabled] = useState(initial.llmsTxtEnabled);
+  const [pristine, setPristine] = useState(initial.llmsTxtEnabled);
+  const [saving, setSaving] = useState(false);
+
+  const dirty = llmsTxtEnabled !== pristine;
+
+  useEffect(() => {
+    if (!dirty) return;
+    const handler = (e: BeforeUnloadEvent) => {
+      e.preventDefault();
+      e.returnValue = '';
+    };
+    window.addEventListener('beforeunload', handler);
+    return () => window.removeEventListener('beforeunload', handler);
+  }, [dirty]);
+
+  const save = async () => {
+    if (!canEdit) return;
+    const candidate = aiSettingsSchema.safeParse({
+      llmsTxtEnabled,
+      chatEnabled: initial.chatEnabled,
+    });
+    if (!candidate.success) {
+      toast.error('Invalid settings');
+      return;
+    }
+    setSaving(true);
+    try {
+      const res = await fetch(`${apiBase}/ai`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(candidate.data),
+      });
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        toast.error(body.error || 'Could not save');
+        return;
+      }
+      setPristine(llmsTxtEnabled);
+      toast.success('Saved to eventcatalog.config.js');
+    } catch (err) {
+      toast.error(`Could not save: ${(err as Error).message}`);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <form onSubmit={(e) => e.preventDefault()} className="divide-y divide-[rgb(var(--ec-page-border))]">
+      <Toaster richColors closeButton position="bottom-right" theme="system" />
+      {!canEdit && (
+        <div className="pb-6">
+          <ReadOnlyBanner />
+        </div>
+      )}
+
+      <Row
+        title="llms.txt"
+        description="Generate llms.txt files so tools like Claude, ChatGPT, and Cursor can read your catalog at /llms.txt."
+        canEdit={canEdit}
+        dirty={dirty}
+        saving={saving}
+        onSave={save}
+      >
+        <ToggleRow
+          icon={<Bot className="h-4 w-4" aria-hidden />}
+          label={llmsTxtEnabled ? 'Enabled' : 'Disabled'}
+          hint={
+            llmsTxtEnabled ? 'AI tools can read your catalog at /llms.txt.' : 'AI tools will not be able to read your catalog.'
+          }
+          checked={llmsTxtEnabled}
+          disabled={!canEdit}
+          onChange={setLlmsTxtEnabled}
+        />
+        {llmsTxtEnabled && <LlmsTxtPreview url={llmsTxtUrl} fullUrl={llmsFullTxtUrl} />}
+      </Row>
+
+      <Row
+        title="schemas.txt"
+        description="Give LLMs access to every schema across your organization in one place — events, commands, queries, and services."
+        canEdit={false}
+        dirty={false}
+      >
+        {hasScalePlan ? (
+          <SchemasTxtAvailable url={schemasTxtUrl} />
+        ) : (
+          <UpgradeRequired
+            tier="Scale"
+            blurb="The schema index is a Scale-plan feature. Upgrade to publish a machine-readable catalogue of your schemas alongside llms.txt."
+          />
+        )}
+      </Row>
+    </form>
+  );
+};
+
+const LlmsTxtPreview = ({ url, fullUrl }: { url: string; fullUrl: string }) => {
+  const variants = [
+    { label: 'Index', path: url },
+    { label: 'Full', path: fullUrl },
+  ];
+  return (
+    <div className="rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg)/0.4)] px-4 py-3">
+      <p className="text-[12px] font-medium text-[rgb(var(--ec-page-text))]">Point your LLM here</p>
+      <p className="mt-0.5 text-[12px] leading-snug text-[rgb(var(--ec-page-text-muted))]">
+        Drop this URL into Claude, ChatGPT, Cursor, or any AI tool to give it the full context of your catalog.
+      </p>
+      <p className="mt-1 text-[12px] leading-snug text-[rgb(var(--ec-page-text-muted))]">
+        From there you can ask questions about your architecture, services, and events.
+      </p>
+      <div className="mt-2.5">
+        <UrlPanel url={url} />
+      </div>
+      <div className="mt-2.5 flex flex-wrap gap-1.5">
+        {variants.map((v) => (
+          <a
+            key={v.path}
+            href={v.path}
+            target="_blank"
+            rel="noreferrer"
+            className="inline-flex items-center gap-1 rounded-full border border-[rgb(var(--ec-page-border))] px-2 py-0.5 text-[11px] text-[rgb(var(--ec-page-text-muted))] transition-colors hover:border-[rgb(var(--ec-accent)/0.5)] hover:text-[rgb(var(--ec-accent))]"
+          >
+            {v.label}
+          </a>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+const SchemasTxtAvailable = ({ url }: { url: string }) => (
+  <div className="space-y-3">
+    <ToggleRow
+      icon={<FileText className="h-4 w-4" aria-hidden />}
+      label="Enabled"
+      hint="A markdown index of every event, command, query, and service schema in your catalog."
+      checked={true}
+      disabled={true}
+      onChange={() => {}}
+    />
+    <div className="rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg)/0.4)] px-4 py-3">
+      <p className="text-[12px] font-medium text-[rgb(var(--ec-page-text))]">Point your LLM here</p>
+      <p className="mt-0.5 text-[12px] leading-snug text-[rgb(var(--ec-page-text-muted))]">
+        Share this URL with Claude, ChatGPT, Cursor, or any AI tool to give it every schema in your catalog.
+      </p>
+      <p className="mt-1 text-[12px] leading-snug text-[rgb(var(--ec-page-text-muted))]">
+        Perfect for asking about message shapes, fields, and contracts.
+      </p>
+      <div className="mt-2.5">
+        <UrlPanel url={url} />
+      </div>
+    </div>
+  </div>
+);
diff --git a/packages/core/eventcatalog/src/components/Settings/LogoUpload.tsx b/packages/core/eventcatalog/src/components/Settings/LogoUpload.tsx
new file mode 100644
index 000000000..fb4753a29
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Settings/LogoUpload.tsx
@@ -0,0 +1,137 @@
+import { useRef, useState } from 'react';
+import { toast } from 'sonner';
+import { ImageIcon, Trash2, Upload, Loader2 } from 'lucide-react';
+
+interface LogoUploadProps {
+  canEdit: boolean;
+  initialSrc?: string;
+  apiUrl: string;
+  onSrcChange?: (src: string | null) => void;
+}
+
+export const LogoUpload = ({ canEdit, initialSrc, apiUrl, onSrcChange }: LogoUploadProps) => {
+  const [src, setSrc] = useState<string | null>(initialSrc ?? null);
+  const [busy, setBusy] = useState(false);
+  const [dragOver, setDragOver] = useState(false);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const upload = async (file: File) => {
+    setBusy(true);
+    const fd = new FormData();
+    fd.append('logo', file);
+    try {
+      const res = await fetch(apiUrl, { method: 'POST', body: fd });
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        toast.error(body.error || 'Logo upload failed');
+        return;
+      }
+      const next = `${body.src}?t=${Date.now()}`;
+      setSrc(next);
+      onSrcChange?.(body.src);
+      toast.success('Logo uploaded');
+    } catch (err) {
+      toast.error(`Logo upload failed: ${(err as Error).message}`);
+    } finally {
+      setBusy(false);
+      if (inputRef.current) inputRef.current.value = '';
+    }
+  };
+
+  const remove = async () => {
+    setBusy(true);
+    try {
+      const res = await fetch(apiUrl, { method: 'DELETE' });
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        toast.error(body.error || 'Could not remove logo');
+        return;
+      }
+      setSrc(null);
+      onSrcChange?.(null);
+      toast.success('Logo removed');
+    } catch (err) {
+      toast.error(`Could not remove logo: ${(err as Error).message}`);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const onDrop = (e: React.DragEvent) => {
+    e.preventDefault();
+    setDragOver(false);
+    if (!canEdit || busy) return;
+    const file = e.dataTransfer.files?.[0];
+    if (file) void upload(file);
+  };
+
+  return (
+    <div
+      onDragOver={(e) => {
+        e.preventDefault();
+        if (canEdit && !busy) setDragOver(true);
+      }}
+      onDragLeave={() => setDragOver(false)}
+      onDrop={onDrop}
+      className={`relative flex items-center gap-5 rounded-lg border border-dashed px-4 py-4 transition-colors ${
+        dragOver
+          ? 'border-[rgb(var(--ec-accent)/0.6)] bg-[rgb(var(--ec-accent-subtle)/0.4)]'
+          : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg)/0.4)]'
+      }`}
+    >
+      <div className="relative flex h-20 w-20 flex-shrink-0 items-center justify-center overflow-hidden rounded-xl bg-[rgb(var(--ec-page-bg))] ring-1 ring-[rgb(var(--ec-page-border))]">
+        {src ? (
+          <img src={src} alt="Catalog logo preview" className="h-16 w-16 object-contain" />
+        ) : (
+          <ImageIcon className="h-7 w-7 text-[rgb(var(--ec-page-text-muted)/0.7)]" aria-hidden />
+        )}
+        {busy && (
+          <div className="absolute inset-0 flex items-center justify-center bg-[rgb(var(--ec-page-bg)/0.7)] backdrop-blur-sm">
+            <Loader2 className="h-4 w-4 animate-spin text-[rgb(var(--ec-page-text))]" aria-hidden />
+          </div>
+        )}
+      </div>
+
+      <div className="flex-1">
+        <p className="text-[13px] font-medium text-[rgb(var(--ec-page-text))]">{src ? 'Replace logo' : 'Upload a logo'}</p>
+        <p className="text-[12px] text-[rgb(var(--ec-page-text-muted))]">
+          {dragOver ? 'Release to upload' : 'Drag a file here, or click to browse.'}
+        </p>
+      </div>
+
+      <div className="flex items-center gap-2">
+        <input
+          ref={inputRef}
+          type="file"
+          accept="image/png,image/jpeg,image/svg+xml,image/webp"
+          className="hidden"
+          disabled={!canEdit || busy}
+          onChange={(e) => {
+            const file = e.target.files?.[0];
+            if (file) void upload(file);
+          }}
+        />
+        <button
+          type="button"
+          disabled={!canEdit || busy}
+          onClick={() => inputRef.current?.click()}
+          className="inline-flex items-center gap-1.5 rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] px-3 py-1.5 text-[12px] font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:bg-[rgb(var(--ec-page-bg)/0.78)] disabled:cursor-not-allowed disabled:opacity-50"
+        >
+          <Upload className="h-3 w-3" aria-hidden />
+          {src ? 'Replace' : 'Upload'}
+        </button>
+        {src && (
+          <button
+            type="button"
+            disabled={!canEdit || busy}
+            onClick={remove}
+            aria-label="Remove logo"
+            className="inline-flex h-7 w-7 items-center justify-center rounded-md border border-transparent text-[rgb(var(--ec-page-text-muted))] transition-colors hover:border-red-500/40 hover:bg-red-500/10 hover:text-red-500 disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            <Trash2 className="h-3.5 w-3.5" aria-hidden />
+          </button>
+        )}
+      </div>
+    </div>
+  );
+};
diff --git a/packages/core/eventcatalog/src/components/Settings/McpSettingsForm.tsx b/packages/core/eventcatalog/src/components/Settings/McpSettingsForm.tsx
new file mode 100644
index 000000000..cb02f4e4d
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Settings/McpSettingsForm.tsx
@@ -0,0 +1,91 @@
+import { ExternalLink, Server, ServerCog } from 'lucide-react';
+import { Row } from './Row';
+import { LiveCard, MCP_DOCS_URL, UpgradeRequired, UrlPanel } from './SettingsShared';
+
+interface Props {
+  hasScalePlan: boolean;
+  inSSR: boolean;
+  mcpUrl: string;
+}
+
+export const McpSettingsForm = ({ hasScalePlan, inSSR, mcpUrl }: Props) => {
+  const mcpAvailable = hasScalePlan && inSSR;
+
+  return (
+    <div className="divide-y divide-[rgb(var(--ec-page-border))]">
+      <Row
+        title="MCP Server"
+        description="Expose your catalog over the Model Context Protocol so AI agents (Claude Desktop, Cursor, etc.) can query your architecture as a live data source."
+        canEdit={false}
+        dirty={false}
+      >
+        {mcpAvailable ? (
+          <McpAvailable url={mcpUrl} />
+        ) : !hasScalePlan ? (
+          <UpgradeRequired
+            tier="Scale"
+            blurb="The MCP Server is a Scale-plan feature. Upgrade to expose your catalog to AI agents over the Model Context Protocol."
+            docsUrl={MCP_DOCS_URL}
+          />
+        ) : (
+          <McpNeedsSSR />
+        )}
+      </Row>
+    </div>
+  );
+};
+
+const McpAvailable = ({ url }: { url: string }) => (
+  <div className="space-y-3">
+    <LiveCard
+      icon={<Server className="h-4 w-4" aria-hidden />}
+      title="MCP server is live"
+      description="Point Claude Desktop, Cursor, or any MCP-aware client at the endpoint below."
+    />
+    <div className="rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg)/0.4)] px-4 py-3">
+      <p className="text-[12px] font-medium text-[rgb(var(--ec-page-text))]">Endpoint</p>
+      <UrlPanel url={url} />
+      <a
+        href={MCP_DOCS_URL}
+        target="_blank"
+        rel="noreferrer"
+        className="mt-3 inline-flex items-center gap-1 text-[12px] font-medium text-[rgb(var(--ec-accent))] hover:underline"
+      >
+        Connect a client
+        <ExternalLink className="h-3 w-3" aria-hidden />
+      </a>
+    </div>
+  </div>
+);
+
+const McpNeedsSSR = () => (
+  <div className="overflow-hidden rounded-lg border border-[rgb(var(--ec-accent)/0.4)] bg-gradient-to-br from-[rgb(var(--ec-accent)/0.1)] via-[rgb(var(--ec-accent)/0.05)] to-transparent">
+    <div className="flex items-start gap-3 px-4 py-3.5">
+      <span className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-md border border-[rgb(var(--ec-accent)/0.4)] bg-[rgb(var(--ec-accent)/0.1)] text-[rgb(var(--ec-accent))]">
+        <ServerCog className="h-4 w-4" aria-hidden />
+      </span>
+      <div className="flex-1 min-w-0">
+        <div className="flex items-center gap-2">
+          <p className="text-[13px] font-semibold text-[rgb(var(--ec-page-text))]">Server output mode required</p>
+          <span className="inline-flex items-center gap-1 rounded-full border border-[rgb(var(--ec-accent)/0.4)] bg-[rgb(var(--ec-accent)/0.1)] px-1.5 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-[rgb(var(--ec-accent))]">
+            SSR
+          </span>
+        </div>
+        <p className="mt-1 text-[12px] leading-snug text-[rgb(var(--ec-page-text-muted))]">
+          The MCP Server requires your catalog to run in server (SSR) mode. Follow the setup guide to switch.
+        </p>
+        <div className="mt-3 flex flex-wrap items-center gap-3">
+          <a
+            href={MCP_DOCS_URL}
+            target="_blank"
+            rel="noreferrer"
+            className="inline-flex items-center gap-1 rounded-md bg-[rgb(var(--ec-accent))] px-3 py-1.5 text-[12px] font-semibold text-white shadow-sm transition-colors hover:bg-[rgb(var(--ec-accent-hover))]"
+          >
+            MCP setup guide
+            <ExternalLink className="h-3 w-3" aria-hidden />
+          </a>
+        </div>
+      </div>
+    </div>
+  </div>
+);
diff --git a/packages/core/eventcatalog/src/components/Settings/ReadOnlyBanner.tsx b/packages/core/eventcatalog/src/components/Settings/ReadOnlyBanner.tsx
new file mode 100644
index 000000000..395046d19
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Settings/ReadOnlyBanner.tsx
@@ -0,0 +1,18 @@
+import { Lock } from 'lucide-react';
+
+export const ReadOnlyBanner = () => (
+  <div
+    role="status"
+    className="mb-6 flex items-start gap-3 rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] p-4 text-sm text-[rgb(var(--ec-page-text))]"
+  >
+    <Lock className="mt-0.5 h-4 w-4 flex-shrink-0 text-[rgb(var(--ec-page-text-muted))]" aria-hidden />
+    <div className="space-y-1">
+      <p className="font-medium">Read-only</p>
+      <p className="text-[rgb(var(--ec-page-text-muted))]">
+        To edit these settings, run EventCatalog locally or update them in your{' '}
+        <code className="rounded bg-[rgb(var(--ec-page-bg)/0.78)] px-1 py-0.5 font-mono text-xs">eventcatalog.config.js</code>{' '}
+        file.
+      </p>
+    </div>
+  </div>
+);
diff --git a/packages/core/eventcatalog/src/components/Settings/Row.tsx b/packages/core/eventcatalog/src/components/Settings/Row.tsx
new file mode 100644
index 000000000..cfd74b839
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Settings/Row.tsx
@@ -0,0 +1,59 @@
+import { AlertCircle } from 'lucide-react';
+
+export const cn = (...parts: Array<string | false | undefined | null>): string => parts.filter(Boolean).join(' ');
+
+export const inputBase =
+  'block w-full rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-input-bg,var(--ec-page-bg)))] px-3 py-2 text-[13px] text-[rgb(var(--ec-page-text))] placeholder:text-[rgb(var(--ec-page-text-muted)/0.7)] transition-colors focus:border-[rgb(var(--ec-accent)/0.6)] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent)/0.25)] disabled:cursor-not-allowed disabled:opacity-60';
+
+export const monoInput = 'font-mono text-[12.5px] tracking-tight';
+
+export const inputError = 'border-red-500/70 focus:border-red-500 focus:ring-red-500/20';
+
+interface RowProps {
+  title: string;
+  description: string;
+  canEdit: boolean;
+  dirty: boolean;
+  saving?: boolean;
+  onSave?: () => void;
+  error?: string;
+  children: React.ReactNode;
+}
+
+export const Row = ({ title, description, canEdit, dirty, saving, onSave, error, children }: RowProps) => (
+  <section className="grid grid-cols-1 gap-6 py-8 md:grid-cols-[minmax(0,_18rem)_minmax(0,_1fr)] md:gap-12">
+    <header className="space-y-1.5">
+      <h3 className="text-[14px] font-semibold tracking-tight text-[rgb(var(--ec-page-text))]">{title}</h3>
+      <p className="text-[13px] leading-relaxed text-[rgb(var(--ec-content-text-muted,var(--ec-page-text-muted)))]">
+        {description}
+      </p>
+    </header>
+    <div className="space-y-2.5">
+      {children}
+      {error && (
+        <p className="flex items-center gap-1.5 text-[12px] text-red-500">
+          <AlertCircle className="h-3 w-3 flex-shrink-0" aria-hidden />
+          {error}
+        </p>
+      )}
+      {onSave && canEdit && (
+        <div className="pt-1">
+          <button
+            type="button"
+            onClick={onSave}
+            disabled={!dirty || saving}
+            className={cn(
+              'inline-flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-[12px] font-medium transition-colors',
+              dirty && !saving
+                ? 'border-[rgb(var(--ec-accent)/0.5)] bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.8)]'
+                : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text-muted))]',
+              'disabled:cursor-not-allowed disabled:opacity-60'
+            )}
+          >
+            {saving ? 'Saving…' : 'Save changes'}
+          </button>
+        </div>
+      )}
+    </div>
+  </section>
+);
diff --git a/packages/core/eventcatalog/src/components/Settings/SettingsShared.tsx b/packages/core/eventcatalog/src/components/Settings/SettingsShared.tsx
new file mode 100644
index 000000000..8e0b40a17
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Settings/SettingsShared.tsx
@@ -0,0 +1,176 @@
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { ExternalLink, Lock, Sparkles, Copy, Check as CheckIcon } from 'lucide-react';
+import { cn } from './Row';
+
+export const ASSISTANT_DOCS_URL =
+  'https://www.eventcatalog.dev/docs/development/ask-your-architecture/eventcatalog-assistant/what-is-eventcatalog-assistant';
+export const ASSISTANT_CONFIGURATION_DOCS_URL =
+  'https://www.eventcatalog.dev/docs/development/ask-your-architecture/eventcatalog-assistant/configuration';
+export const MCP_DOCS_URL = 'https://www.eventcatalog.dev/docs/development/ask-your-architecture/mcp-server/getting-started';
+export const PRICING_URL = 'https://www.eventcatalog.dev/pricing';
+
+interface UpgradeRequiredProps {
+  tier: string;
+  blurb: string;
+  docsUrl?: string;
+}
+
+export const UpgradeRequired = ({ tier, blurb, docsUrl }: UpgradeRequiredProps) => (
+  <div className="overflow-hidden rounded-lg border border-amber-500/40 bg-gradient-to-br from-amber-500/10 via-amber-500/5 to-transparent">
+    <div className="flex items-start gap-3 px-4 py-3.5">
+      <span className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-md border border-amber-500/40 bg-amber-500/10 text-amber-500">
+        <Lock className="h-4 w-4" aria-hidden />
+      </span>
+      <div className="flex-1 min-w-0">
+        <div className="flex items-center gap-2">
+          <p className="text-[13px] font-semibold text-[rgb(var(--ec-page-text))]">Available on {tier}</p>
+          <span className="inline-flex items-center gap-1 rounded-full border border-amber-500/40 bg-amber-500/10 px-1.5 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-amber-500">
+            <Sparkles className="h-2.5 w-2.5" aria-hidden />
+            Upgrade
+          </span>
+        </div>
+        <p className="mt-1 text-[12px] leading-snug text-[rgb(var(--ec-page-text-muted))]">{blurb}</p>
+        <div className="mt-3 flex flex-wrap items-center gap-3">
+          <a
+            href={PRICING_URL}
+            target="_blank"
+            rel="noreferrer"
+            className="inline-flex items-center gap-1 rounded-md bg-amber-500 px-3 py-1.5 text-[12px] font-semibold text-white shadow-sm transition-colors hover:bg-amber-600"
+          >
+            View plans
+            <ExternalLink className="h-3 w-3" aria-hidden />
+          </a>
+          {docsUrl && (
+            <a
+              href={docsUrl}
+              target="_blank"
+              rel="noreferrer"
+              className="inline-flex items-center gap-1 text-[12px] font-medium text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]"
+            >
+              Learn more
+              <ExternalLink className="h-3 w-3" aria-hidden />
+            </a>
+          )}
+        </div>
+      </div>
+    </div>
+  </div>
+);
+
+interface UrlPanelProps {
+  url: string;
+}
+
+export const UrlPanel = ({ url }: UrlPanelProps) => {
+  const [copied, setCopied] = useState(false);
+  const copy = async () => {
+    try {
+      await navigator.clipboard.writeText(new URL(url, window.location.origin).href);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1600);
+    } catch {
+      toast.error('Could not copy URL');
+    }
+  };
+  return (
+    <div className="mt-2 flex items-center gap-2">
+      <a
+        href={url}
+        target="_blank"
+        rel="noreferrer"
+        className="flex-1 truncate rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] px-2.5 py-1.5 font-mono text-[12px] text-[rgb(var(--ec-page-text))] transition-colors hover:border-[rgb(var(--ec-accent)/0.5)] hover:text-[rgb(var(--ec-accent))]"
+      >
+        {url}
+      </a>
+      <button
+        type="button"
+        onClick={copy}
+        aria-label="Copy URL"
+        className="inline-flex h-7 w-7 items-center justify-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text-muted))] transition-colors hover:bg-[rgb(var(--ec-page-bg)/0.78)] hover:text-[rgb(var(--ec-page-text))]"
+      >
+        {copied ? <CheckIcon className="h-3.5 w-3.5 text-green-500" aria-hidden /> : <Copy className="h-3.5 w-3.5" aria-hidden />}
+      </button>
+      <a
+        href={url}
+        target="_blank"
+        rel="noreferrer"
+        aria-label="Open in new tab"
+        className="inline-flex h-7 w-7 items-center justify-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text-muted))] transition-colors hover:bg-[rgb(var(--ec-page-bg)/0.78)] hover:text-[rgb(var(--ec-page-text))]"
+      >
+        <ExternalLink className="h-3.5 w-3.5" aria-hidden />
+      </a>
+    </div>
+  );
+};
+
+interface LiveCardProps {
+  icon: React.ReactNode;
+  title: string;
+  description: string;
+}
+
+export const LiveCard = ({ icon, title, description }: LiveCardProps) => (
+  <div className="flex items-center gap-3 rounded-lg border border-emerald-500/30 bg-emerald-500/5 px-4 py-3">
+    <span className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-md border border-emerald-500/30 bg-emerald-500/10 text-emerald-500">
+      {icon}
+    </span>
+    <div className="flex-1 min-w-0">
+      <p className="text-[13px] font-medium text-[rgb(var(--ec-page-text))]">{title}</p>
+      <p className="text-[12px] leading-snug text-[rgb(var(--ec-page-text-muted))]">{description}</p>
+    </div>
+    <span className="flex-shrink-0 rounded-full border border-emerald-500/30 bg-emerald-500/10 px-2 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-emerald-500">
+      Live
+    </span>
+  </div>
+);
+
+interface ToggleProps {
+  checked: boolean;
+  disabled?: boolean;
+  onChange: (v: boolean) => void;
+}
+
+export const Toggle = ({ checked, disabled, onChange }: ToggleProps) => (
+  <button
+    type="button"
+    role="switch"
+    aria-checked={checked}
+    disabled={disabled}
+    onClick={() => onChange(!checked)}
+    className={cn(
+      'relative inline-flex h-5 w-9 flex-shrink-0 cursor-pointer items-center rounded-full transition-colors',
+      checked ? 'bg-[rgb(var(--ec-accent))]' : 'bg-[rgb(var(--ec-page-text-muted)/0.35)]',
+      disabled && 'cursor-not-allowed opacity-50'
+    )}
+  >
+    <span
+      className={cn(
+        'inline-block h-3.5 w-3.5 transform rounded-full bg-white shadow-sm transition-transform',
+        checked ? 'translate-x-[1.125rem]' : 'translate-x-[0.1875rem]'
+      )}
+    />
+  </button>
+);
+
+interface ToggleRowProps {
+  icon: React.ReactNode;
+  label: string;
+  hint: string;
+  checked: boolean;
+  disabled?: boolean;
+  onChange: (v: boolean) => void;
+}
+
+export const ToggleRow = ({ icon, label, hint, checked, disabled, onChange }: ToggleRowProps) => (
+  <div className="flex items-center gap-3 rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-input-bg,var(--ec-page-bg)))] px-4 py-3">
+    <span className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text-muted))]">
+      {icon}
+    </span>
+    <div className="flex-1 min-w-0">
+      <p className="text-[13px] font-medium text-[rgb(var(--ec-page-text))]">{label}</p>
+      <p className="text-[12px] leading-snug text-[rgb(var(--ec-page-text-muted))]">{hint}</p>
+    </div>
+    <Toggle checked={checked} disabled={disabled} onChange={onChange} />
+  </div>
+);
diff --git a/eventcatalog/src/components/SideNav/CustomDocsNav.astro b/packages/core/eventcatalog/src/components/SideNav/CustomDocsNav.astro
similarity index 100%
rename from eventcatalog/src/components/SideNav/CustomDocsNav.astro
rename to packages/core/eventcatalog/src/components/SideNav/CustomDocsNav.astro
diff --git a/packages/core/eventcatalog/src/components/SideNav/NestedSideBar/SearchBar.tsx b/packages/core/eventcatalog/src/components/SideNav/NestedSideBar/SearchBar.tsx
new file mode 100644
index 000000000..fbe8f5c87
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SideNav/NestedSideBar/SearchBar.tsx
@@ -0,0 +1,349 @@
+'use client';
+
+import { useState, useCallback, useMemo } from 'react';
+import {
+  Search,
+  X,
+  SlidersHorizontal,
+  ChevronRight,
+  Boxes,
+  Server,
+  Zap,
+  MessageSquare,
+  Search as SearchIcon,
+  Database,
+  Waypoints,
+  SquareMousePointer,
+  ListOrdered,
+  ArrowLeftRight,
+  Package,
+  Box,
+  Bot,
+} from 'lucide-react';
+import type { NavNode } from '@stores/sidebar-store/state';
+import { getBadgeClasses } from './utils';
+
+const cn = (...classes: (string | false | undefined)[]) => classes.filter(Boolean).join(' ');
+
+type SearchResult = {
+  nodeKey: string;
+  node: NavNode;
+  matchType: 'name' | 'id';
+};
+
+type Props = {
+  nodes: Record<string, NavNode | string>;
+  onSelectResult: (nodeKey: string, node: NavNode) => void;
+  onSearchChange?: (isSearching: boolean) => void;
+};
+
+export default function SearchBar({ nodes, onSelectResult, onSearchChange }: Props) {
+  const [searchQuery, setSearchQuery] = useState('');
+  const [searchFilters, setSearchFilters] = useState<Set<string>>(new Set());
+  const [showFilterDropdown, setShowFilterDropdown] = useState(false);
+
+  // Pre-process searchable nodes to avoid iterating object on every render
+  // Filter out unversioned keys (e.g., "domain:OrderService") to avoid duplicates with versioned keys (e.g., "domain:OrderService:1.0.0")
+  const searchableNodes = useMemo((): Array<[string, NavNode]> => {
+    const result: Array<[string, NavNode]> = [];
+    for (const [key, node] of Object.entries(nodes)) {
+      // Skip string references (unversioned aliases that point to versioned keys)
+      if (typeof node === 'string') continue;
+      if (node.type === 'group') continue;
+      // Only include versioned keys (those with 3+ parts like "type:id:version")
+      // Unversioned keys (2 parts like "type:id") are aliases to latest version and would cause duplicates
+      const keyParts = key.split(':');
+      if (keyParts.length >= 3) {
+        result.push([key, node]);
+      }
+    }
+    return result;
+  }, [nodes]);
+
+  // Get available badges from nodes
+  const availableBadges = useMemo(() => {
+    const badges = new Set<string>();
+
+    for (const [_, node] of searchableNodes) {
+      if (node.badge) {
+        badges.add(node.badge);
+      }
+    }
+    return badges;
+  }, [searchableNodes]);
+
+  const handleSearchChange = (value: string) => {
+    setSearchQuery(value);
+    onSearchChange?.(value.trim().length > 0);
+  };
+
+  const clearSearch = () => {
+    setSearchQuery('');
+    onSearchChange?.(false);
+  };
+
+  const filterTypes = [
+    { key: 'channel', label: 'Channels', badge: 'Channel', icon: ArrowLeftRight },
+    { key: 'agent', label: 'Agents', badge: 'Agent', icon: Bot },
+    { key: 'command', label: 'Commands', badge: 'Command', icon: MessageSquare },
+    { key: 'container', label: 'Data Stores', badge: 'Container', icon: Database },
+    { key: 'data-product', label: 'Data Products', badge: 'Data Product', icon: Package },
+    { key: 'design', label: 'Designs', badge: 'Design', icon: SquareMousePointer },
+    { key: 'domain', label: 'Domains', badge: 'Domain', icon: Boxes },
+    { key: 'entity', label: 'Entities', badge: 'Entity', icon: Box },
+    { key: 'event', label: 'Events', badge: 'Event', icon: Zap },
+    { key: 'flow', label: 'Flows', badge: 'Flow', icon: Waypoints },
+    { key: 'query', label: 'Queries', badge: 'Query', icon: SearchIcon },
+    { key: 'service', label: 'Services', badge: 'Service', icon: Server },
+  ].filter((filter) => availableBadges.has(filter.badge));
+
+  const toggleSearchFilter = (filterKey: string) => {
+    setSearchFilters((prev) => {
+      const next = new Set(prev);
+      if (next.has(filterKey)) {
+        next.delete(filterKey);
+      } else {
+        next.add(filterKey);
+      }
+      return next;
+    });
+  };
+
+  const searchResults = useCallback((): SearchResult[] => {
+    if (!searchQuery.trim()) return [];
+
+    const query = searchQuery.toLowerCase();
+    const results: SearchResult[] = [];
+
+    const badgeToFilterKey: Record<string, string> = {
+      Agent: 'agent',
+      Domain: 'domain',
+      Service: 'service',
+      Event: 'event',
+      Command: 'command',
+      Query: 'query',
+      Container: 'container',
+      'Data Product': 'data-product',
+      Flow: 'flow',
+      Design: 'design',
+      Channel: 'channel',
+      Entity: 'entity',
+    };
+
+    // Use the memoized array instead of Object.entries(nodes)
+    for (const [key, node] of searchableNodes) {
+      if (searchFilters.size > 0) {
+        const filterKey = node.badge ? badgeToFilterKey[node.badge] : null;
+        if (!filterKey || !searchFilters.has(filterKey)) continue;
+      }
+
+      if (node.title.toLowerCase().includes(query)) {
+        results.push({ nodeKey: key, node, matchType: 'name' });
+        continue;
+      }
+
+      const keyParts = key.split(':');
+      if (keyParts.length >= 3) {
+        const id = keyParts[1].toLowerCase();
+        if (id.includes(query)) {
+          results.push({ nodeKey: key, node, matchType: 'id' });
+        }
+      }
+    }
+
+    return results
+      .sort((a, b) => {
+        const aExact = a.node.title.toLowerCase() === query;
+        const bExact = b.node.title.toLowerCase() === query;
+        if (aExact && !bExact) return -1;
+        if (!aExact && bExact) return 1;
+        return a.node.title.localeCompare(b.node.title);
+      })
+      .slice(0, 20);
+  }, [searchQuery, searchableNodes, searchFilters]);
+
+  const handleSelectResult = (nodeKey: string, node: NavNode) => {
+    onSelectResult(nodeKey, node);
+    clearSearch();
+  };
+
+  const results = searchResults();
+  const showSearchResults = searchQuery.trim().length > 0;
+
+  // Group results by type (badge), sorted alphabetically
+  const groupedResults = useMemo(() => {
+    const groups: Record<string, SearchResult[]> = {};
+
+    for (const result of results) {
+      const badge = result.node.badge || 'Other';
+      if (!groups[badge]) {
+        groups[badge] = [];
+      }
+      groups[badge].push(result);
+    }
+
+    return Object.entries(groups)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([type, typeResults]) => ({ type, results: typeResults }));
+  }, [results]);
+
+  return (
+    <>
+      {/* Search Input */}
+      <div className="px-4 py-3 bg-[rgb(var(--ec-content-bg))] border-b border-[rgb(var(--ec-content-border))]">
+        <div className="flex gap-2">
+          <div className="relative flex-1">
+            <Search className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-[rgb(var(--ec-input-placeholder))]" />
+            <input
+              type="text"
+              placeholder="Search resources..."
+              value={searchQuery}
+              onChange={(e) => handleSearchChange(e.target.value)}
+              className="w-full pl-9! pr-8! py-2.5! text-sm! bg-[rgb(var(--ec-input-bg))]! border! border-[rgb(var(--ec-input-border))]! rounded-xl! focus:outline-hidden! focus:ring-2! focus:ring-[rgb(var(--ec-accent))]! focus:border-transparent! text-[rgb(var(--ec-input-text))]! placeholder:text-[rgb(var(--ec-input-placeholder))]!"
+            />
+            {searchQuery && (
+              <button
+                onClick={clearSearch}
+                className="absolute right-3 top-1/2 -translate-y-1/2 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-icon-hover))]"
+                aria-label="Clear search"
+              >
+                <X className="w-4 h-4" aria-hidden="true" />
+              </button>
+            )}
+          </div>
+          {/* Filter Button */}
+          <div className="relative">
+            <button
+              onClick={() => setShowFilterDropdown(!showFilterDropdown)}
+              className={cn(
+                'flex items-center justify-center w-10 h-10 rounded-xl border transition-colors',
+                searchFilters.size > 0
+                  ? 'bg-[rgb(var(--ec-accent)/0.1)] border-[rgb(var(--ec-accent)/0.3)] text-[rgb(var(--ec-accent))]'
+                  : 'bg-[rgb(var(--ec-input-bg))] border-[rgb(var(--ec-input-border))] text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-icon-hover))] hover:bg-[rgb(var(--ec-content-hover))]'
+              )}
+              aria-label="Filter search results"
+              aria-expanded={showFilterDropdown}
+            >
+              <SlidersHorizontal className="w-4 h-4" aria-hidden="true" />
+              {searchFilters.size > 0 && (
+                <span className="absolute -top-1 -right-1 w-4 h-4 bg-[rgb(var(--ec-accent))] text-white text-[10px] font-bold rounded-full flex items-center justify-center">
+                  {searchFilters.size}
+                </span>
+              )}
+            </button>
+
+            {/* Filter Dropdown */}
+            {showFilterDropdown && (
+              <>
+                <div className="fixed inset-0 z-20" onClick={() => setShowFilterDropdown(false)} />
+                <div className="absolute right-0 top-full mt-1 w-48 bg-[rgb(var(--ec-dropdown-bg))] rounded-lg shadow-lg border border-[rgb(var(--ec-dropdown-border))] z-30">
+                  <div className="p-2">
+                    <div className="text-[10px] font-medium text-[rgb(var(--ec-content-text-muted))] uppercase tracking-wide px-2 py-1">
+                      Filter by type
+                    </div>
+                    <div className="flex flex-col gap-0.5 mt-1">
+                      {filterTypes.map((filter) => {
+                        const isActive = searchFilters.has(filter.key);
+                        const Icon = filter.icon;
+                        return (
+                          <button
+                            key={filter.key}
+                            onClick={() => toggleSearchFilter(filter.key)}
+                            className={cn(
+                              'flex items-center justify-between px-2 py-1.5 rounded text-sm transition-colors',
+                              isActive
+                                ? 'bg-[rgb(var(--ec-accent)/0.1)] text-[rgb(var(--ec-accent))]'
+                                : 'text-[rgb(var(--ec-dropdown-text))] hover:bg-[rgb(var(--ec-dropdown-hover))]'
+                            )}
+                          >
+                            <span className="flex items-center gap-2">
+                              <Icon className="w-3 h-3" />
+                              {filter.label}
+                            </span>
+                            {isActive && <span className="text-[rgb(var(--ec-accent))]">✓</span>}
+                          </button>
+                        );
+                      })}
+                    </div>
+                    {searchFilters.size > 0 && (
+                      <>
+                        <div className="border-t border-[rgb(var(--ec-content-border))] my-2" />
+                        <button
+                          onClick={() => {
+                            setSearchFilters(new Set());
+                            setShowFilterDropdown(false);
+                          }}
+                          className="w-full px-2 py-1.5 text-sm text-[rgb(var(--ec-content-text-muted))] hover:text-[rgb(var(--ec-content-text))] hover:bg-[rgb(var(--ec-dropdown-hover))] rounded text-left"
+                        >
+                          Reset filters
+                        </button>
+                      </>
+                    )}
+                  </div>
+                </div>
+              </>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/* Search Results */}
+      {showSearchResults && (
+        <div className="flex-1 overflow-y-auto bg-[rgb(var(--ec-content-bg))] border-b border-[rgb(var(--ec-content-border))]">
+          <div className="px-3 py-2">
+            <div className="text-[10px] font-medium text-[rgb(var(--ec-content-text-muted))] uppercase tracking-wide mb-2">
+              {results.length > 0 ? `${results.length} result${results.length > 1 ? 's' : ''}` : 'No results'}
+            </div>
+            {groupedResults.length > 0 && (
+              <div className="flex flex-col gap-3">
+                {groupedResults.map(({ type, results: typeResults }) => (
+                  <div key={type}>
+                    <div className="flex items-center gap-2 mb-1">
+                      <span
+                        className={cn(
+                          'px-1.5 py-0.5 text-[8px] font-semibold uppercase tracking-wide rounded',
+                          getBadgeClasses(type)
+                        )}
+                      >
+                        {type}
+                      </span>
+                      <span className="text-[10px] text-[rgb(var(--ec-content-text-muted))]">({typeResults.length})</span>
+                    </div>
+                    <div className="flex flex-col gap-0.5">
+                      {typeResults.map(({ nodeKey, node, matchType }) => (
+                        <button
+                          key={nodeKey}
+                          onClick={() => handleSelectResult(nodeKey, node)}
+                          className="group flex items-center justify-between w-full px-3 py-2 rounded-lg cursor-pointer text-left transition-colors hover:bg-[rgb(var(--ec-content-hover))]"
+                        >
+                          <div className="flex flex-col min-w-0 flex-1">
+                            <span className="text-sm text-[rgb(var(--ec-content-text))] truncate">{node.title}</span>
+                            {matchType === 'id' && (
+                              <span className="text-xs text-[rgb(var(--ec-content-text-muted))] truncate">
+                                ID: {nodeKey.split(':')[2]}
+                              </span>
+                            )}
+                          </div>
+                          <div className="flex items-center gap-2 flex-shrink-0">
+                            {node.pages && node.pages.length > 0 && (
+                              <ChevronRight className="w-4 h-4 text-[rgb(var(--ec-icon-color))] group-hover:text-[rgb(var(--ec-accent))]" />
+                            )}
+                          </div>
+                        </button>
+                      ))}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            )}
+            {results.length === 0 && searchQuery.trim() && (
+              <div className="text-sm text-[rgb(var(--ec-content-text-muted))] py-4 text-center">
+                No resources found for "{searchQuery}"
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SideNav/NestedSideBar/index.tsx b/packages/core/eventcatalog/src/components/SideNav/NestedSideBar/index.tsx
new file mode 100644
index 000000000..6ae7e186c
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SideNav/NestedSideBar/index.tsx
@@ -0,0 +1,1250 @@
+'use client';
+
+import { useState, useEffect, useCallback, useMemo } from 'react';
+import * as LucideIcons from 'lucide-react';
+import { ChevronRight, ChevronLeft, ChevronDown, Home, Star } from 'lucide-react';
+import type { NavNode, ChildRef } from '@stores/sidebar-store/state';
+import { saveState, loadState, saveCollapsedSections, loadCollapsedSections } from './storage';
+import { useStore } from '@nanostores/react';
+import { sidebarStore } from '@stores/sidebar-store';
+import {
+  favoritesStore,
+  toggleFavorite as toggleFavoriteAction,
+  removeFavorite as removeFavoriteAction,
+  type FavoriteItem,
+} from '@stores/favorites-store';
+import { getBadgeClasses } from './utils';
+import { resolveIconUrl } from '@utils/icon';
+
+const cn = (...classes: (string | false | undefined)[]) => classes.filter(Boolean).join(' ');
+
+/**
+ * Strip the configured base path from a pathname so URL pattern matching works
+ * regardless of the base path setting (e.g. `/eventcatalog/docs/...` → `/docs/...`).
+ */
+const stripBasePath = (pathname: string): string => {
+  const base = __EC_BASE__.replace(/\/$/, ''); // e.g. '/eventcatalog'
+  if (base && pathname.startsWith(base)) {
+    return pathname.slice(base.length) || '/';
+  }
+  return pathname;
+};
+
+// ============================================
+// Component
+// ============================================
+
+type NavigationLevel = {
+  key: string | null; // The key of the node that was drilled into (null for root)
+  entries: ChildRef[];
+  title: string;
+  badge?: string; // Category badge (e.g., "Domain", "Service")
+};
+
+export default function NestedSideBar() {
+  const data = useStore(sidebarStore);
+  const favorites = useStore(favoritesStore);
+
+  // Guard against undefined data (e.g., during hydration)
+  // Use useMemo to ensure stable references for roots and nodes
+  const roots = useMemo(() => data?.roots ?? [], [data?.roots]);
+  const nodes = useMemo(() => data?.nodes ?? {}, [data?.nodes]);
+
+  const [navigationStack, setNavigationStack] = useState<NavigationLevel[]>(() => [
+    { key: null, entries: [], title: 'Documentation' },
+  ]);
+  const [animationKey, setAnimationKey] = useState(0);
+  const [slideDirection, setSlideDirection] = useState<'forward' | 'backward' | null>(null);
+  const [isInitialized, setIsInitialized] = useState(false);
+  const [currentPath, setCurrentPath] = useState<string>('');
+  const [collapsedSections, setCollapsedSections] = useState<Set<string>>(new Set());
+  const [showPathPreview, setShowPathPreview] = useState(false);
+  const [showFullPath, setShowFullPath] = useState(false);
+
+  // Build a lookup map for faster URL navigation
+  // Map format: "type:id" -> "nodeKey"
+  const nodeLookup = useMemo(() => {
+    const lookup = new Map<string, string>();
+
+    Object.entries(nodes).forEach(([key, value]) => {
+      // Skip keys that are references (string values pointing to other keys)
+      // These are unversioned aliases like "domain:E-Commerce" -> "domain:E-Commerce:1.0.0"
+      if (typeof value === 'string') return;
+
+      // Key formats:
+      // - "type:id:version" (e.g., "service:OrdersService:0.0.3")
+      // - "type:id" (e.g., "user:john", "team:backend") - non-versioned resources
+      // - "list:name" (e.g., "list:domains") - skip these
+      const parts = key.split(':');
+
+      // Skip list items
+      if (parts[0] === 'list') return;
+
+      if (parts.length >= 2) {
+        // Store as "type:id"
+        const type = parts[0];
+        const id = parts[1];
+        lookup.set(`${type}:${id}`, key);
+      }
+    });
+
+    return lookup;
+  }, [nodes]);
+
+  /**
+   * Toggle section collapse state
+   */
+  const toggleSectionCollapse = (sectionId: string) => {
+    setCollapsedSections((prev) => {
+      const next = new Set(prev);
+      if (next.has(sectionId)) {
+        next.delete(sectionId);
+      } else {
+        next.add(sectionId);
+      }
+      // Save to localStorage
+      saveCollapsedSections(next);
+      return next;
+    });
+  };
+
+  /**
+   * Load collapsed sections from localStorage on mount
+   */
+  useEffect(() => {
+    const saved = loadCollapsedSections();
+    if (saved.size > 0) {
+      setCollapsedSections(saved);
+    }
+  }, []);
+
+  /**
+   * Update navigation stack when roots become available
+   */
+  useEffect(() => {
+    if (roots.length > 0) {
+      setNavigationStack((prevStack) => {
+        // Only update if the current stack has no entries (initial state)
+        if (prevStack.length === 1 && prevStack[0].entries.length === 0) {
+          return [{ key: null, entries: roots, title: 'Documentation' }];
+        }
+        return prevStack;
+      });
+    }
+  }, [roots]);
+
+  /**
+   * Populate the store with the data when the component mounts or data changes
+   */
+  // useEffect(() => {
+  //   if (data) {
+  //     setSidebarData(data);
+  //   }
+  // }, [data]);
+
+  /**
+   * Resolve a child reference to a NavNode
+   * Handles both direct keys and string references (unversioned aliases pointing to versioned keys)
+   */
+  const resolveRef = useCallback(
+    (ref: ChildRef): NavNode | null => {
+      if (typeof ref === 'string') {
+        const node = nodes[ref];
+        if (!node) return null;
+        // If node is a string, it's a reference to another key (e.g., unversioned alias)
+        if (typeof node === 'string') {
+          return (nodes[node] as NavNode) ?? null;
+        }
+        return node;
+      }
+      return ref;
+    },
+    [nodes]
+  );
+
+  /**
+   * Check if a node is visible (default: true)
+   */
+  const isVisible = useCallback((node: NavNode | null): boolean => {
+    if (!node) return false;
+    return node.visible !== false;
+  }, []);
+
+  /**
+   * Build navigation stack from a path of keys
+   */
+  const buildStackFromPath = useCallback(
+    (path: string[]): NavigationLevel[] => {
+      const stack: NavigationLevel[] = [{ key: null, entries: roots, title: 'Documentation' }];
+
+      for (const key of path) {
+        const node = resolveRef(key);
+        if (node && node.pages) {
+          stack.push({
+            key,
+            entries: node.pages,
+            title: node.title,
+            badge: node.badge,
+          });
+        } else {
+          // Path is invalid (node doesn't exist or has no children), stop here
+          break;
+        }
+      }
+
+      return stack;
+    },
+    [roots, resolveRef]
+  );
+
+  /**
+   * Get current path from navigation stack
+   */
+  const getCurrentPath = useCallback((): string[] => {
+    return navigationStack.filter((level) => level.key !== null).map((level) => level.key as string);
+  }, [navigationStack]);
+
+  /**
+   * Find a node key by matching URL patterns
+   */
+  const findNodeKeyByUrl = useCallback(
+    (url: string): string | null => {
+      // Strip the base path so patterns always match against /docs/..., /visualiser/..., etc.
+      const normalizedUrl = stripBasePath(url);
+
+      // URL patterns to match resources with version
+      const urlPatternsWithVersion = [
+        // Domains
+        { pattern: /^\/docs\/domains\/([^/]+)\/([^/]+)/, type: 'domain' },
+        { pattern: /^\/visualiser\/domains\/([^/]+)\/([^/]+)/, type: 'domain' },
+        { pattern: /^\/architecture\/domains\/([^/]+)\/([^/]+)/, type: 'domain' },
+        // Systems (key prefix is `system`, url segment is `systems`).
+        // The visualiser pattern also matches the System Diagram
+        // (/visualiser/systems/:id/:version/context) since it is not end-anchored.
+        { pattern: /^\/docs\/systems\/([^/]+)\/([^/]+)/, type: 'system' },
+        { pattern: /^\/visualiser\/systems\/([^/]+)\/([^/]+)/, type: 'system' },
+        { pattern: /^\/architecture\/systems\/([^/]+)\/([^/]+)/, type: 'system' },
+        // Agents
+        { pattern: /^\/docs\/agents\/([^/]+)\/([^/]+)/, type: 'agent' },
+        { pattern: /^\/visualiser\/agents\/([^/]+)\/([^/]+)/, type: 'agent' },
+        // Decision Records
+        { pattern: /^\/docs\/adrs\/([^/]+)\/([^/]+)/, type: 'adr' },
+        // Services
+        { pattern: /^\/docs\/services\/([^/]+)\/([^/]+)/, type: 'service' },
+        { pattern: /^\/architecture\/services\/([^/]+)\/([^/]+)/, type: 'service' },
+        { pattern: /^\/visualiser\/services\/([^/]+)\/([^/]+)/, type: 'service' },
+        // Messages (events, commands, queries) - note: keys use singular form
+        { pattern: /^\/docs\/events\/([^/]+)\/([^/]+)/, type: 'event' },
+        { pattern: /^\/docs\/commands\/([^/]+)\/([^/]+)/, type: 'command' },
+        { pattern: /^\/docs\/queries\/([^/]+)\/([^/]+)/, type: 'query' },
+        { pattern: /^\/visualiser\/messages\/([^/]+)\/([^/]+)/, type: 'message' },
+        { pattern: /^\/visualiser\/events\/([^/]+)\/([^/]+)/, type: 'event' },
+        { pattern: /^\/visualiser\/commands\/([^/]+)\/([^/]+)/, type: 'command' },
+        { pattern: /^\/visualiser\/queries\/([^/]+)\/([^/]+)/, type: 'query' },
+        // Containers
+        { pattern: /^\/docs\/containers\/([^/]+)\/([^/]+)/, type: 'container' },
+        { pattern: /^\/visualiser\/containers\/([^/]+)\/([^/]+)/, type: 'container' },
+        // Flows
+        { pattern: /^\/docs\/flows\/([^/]+)\/([^/]+)/, type: 'flow' },
+        { pattern: /^\/visualiser\/flows\/([^/]+)\/([^/]+)/, type: 'flow' },
+        // Data Products
+        { pattern: /^\/docs\/data-products\/([^/]+)\/([^/]+)/, type: 'data-product' },
+        { pattern: /^\/visualiser\/data-products\/([^/]+)\/([^/]+)/, type: 'data-product' },
+        // Entities
+        { pattern: /^\/docs\/entities\/([^/]+)\/([^/]+)/, type: 'entity' },
+      ];
+
+      // URL patterns without version (language pages, etc)
+      const urlPatternsWithoutVersion = [{ pattern: /^\/docs\/domains\/([^/]+)\/language/, type: 'domain' }];
+
+      // First try to match patterns with version
+      for (const { pattern, type } of urlPatternsWithVersion) {
+        const match = normalizedUrl.match(pattern);
+        if (match) {
+          const id = match[1];
+          const version = match[2];
+
+          // First try with version
+          const keyWithVersion = `${type}:${id}:${version}`;
+          if (nodes[keyWithVersion]) {
+            return keyWithVersion;
+          }
+
+          // Fallback to lookup without version (for latest)
+          const foundNodeKey = nodeLookup.get(`${type}:${id}`);
+          if (foundNodeKey) return foundNodeKey;
+        }
+      }
+
+      // Then try patterns without version
+      for (const { pattern, type } of urlPatternsWithoutVersion) {
+        const match = normalizedUrl.match(pattern);
+        if (match) {
+          const id = match[1];
+          const foundNodeKey = nodeLookup.get(`${type}:${id}`);
+          if (foundNodeKey) return foundNodeKey;
+        }
+      }
+
+      return null;
+    },
+    [nodeLookup, nodes]
+  );
+
+  /**
+   * Try to connect a target node to the current stack (drill down, move up, or validate leaf)
+   */
+  const tryConnectStack = useCallback(
+    (targetKey: string, currentStack: NavigationLevel[]): NavigationLevel[] | null => {
+      const targetNode = resolveRef(targetKey);
+      if (!targetNode) return null;
+
+      // 1. Check if we are already at this level (or above)
+      const existingLevelIndex = currentStack.findIndex((level) => level.key === targetKey);
+      if (existingLevelIndex !== -1) {
+        // Truncate stack to this level
+        return currentStack.slice(0, existingLevelIndex + 1);
+      }
+
+      // 2. Check if it's a child of the current last level
+      const lastLevel = currentStack[currentStack.length - 1];
+      const lastNode = lastLevel.key ? resolveRef(lastLevel.key) : null;
+
+      // If root level (key=null), we check against roots
+      const parentChildren = lastLevel.key === null ? roots : lastNode?.pages;
+
+      if (parentChildren) {
+        const isChild = parentChildren.some((ref) => {
+          if (typeof ref === 'string') return ref === targetKey;
+          // Inline nodes don't have global keys usually
+          return false;
+        });
+
+        if (isChild) {
+          // If it has children, we drill down
+          if (targetNode.pages && targetNode.pages.length > 0) {
+            return [
+              ...currentStack,
+              { key: targetKey, entries: targetNode.pages, title: targetNode.title, badge: targetNode.badge },
+            ];
+          }
+          // If it's a leaf, the stack is valid as is
+          return currentStack;
+        }
+      }
+
+      return null;
+    },
+    [resolveRef, roots]
+  );
+
+  /**
+   * Find a node by matching URL patterns and navigate to it
+   */
+  const findAndNavigateToUrl = useCallback(
+    (url: string) => {
+      const foundNodeKey = findNodeKeyByUrl(url);
+
+      if (foundNodeKey) {
+        setNavigationStack((currentStack) => {
+          // Try to connect to current stack first
+          const connectedStack = tryConnectStack(foundNodeKey, currentStack);
+
+          if (connectedStack) {
+            return connectedStack;
+          }
+
+          const foundNode = resolveRef(foundNodeKey);
+          if (foundNode && foundNode.pages && foundNode.pages.length > 0) {
+            // Fallback: Flattened navigation
+            return [
+              { key: null, entries: roots, title: 'Documentation' },
+              { key: foundNodeKey, entries: foundNode.pages, title: foundNode.title, badge: foundNode.badge },
+            ];
+          }
+
+          return currentStack;
+        });
+        return true;
+      } else if (url === '/' || url === '') {
+        // Reset to root if we are on homepage
+        setNavigationStack((currentStack) => {
+          if (currentStack.length > 1) {
+            setSlideDirection('backward');
+            setAnimationKey((prev) => prev + 1);
+          }
+          return [{ key: null, entries: roots, title: 'Documentation' }];
+        });
+        return true;
+      }
+      return false;
+    },
+    [findNodeKeyByUrl, tryConnectStack, resolveRef, roots]
+  );
+
+  /**
+   * Restore state from localStorage on mount, or navigate to URL
+   */
+  useEffect(() => {
+    if (!data || roots.length === 0 || isInitialized) return;
+
+    const currentUrl = window.location.pathname;
+    const normalizedCurrentUrl = stripBasePath(currentUrl);
+
+    // Force root navigation on homepage
+    if (normalizedCurrentUrl === '/' || normalizedCurrentUrl === '') {
+      setNavigationStack([{ key: null, entries: roots, title: 'Documentation' }]);
+      setIsInitialized(true);
+      return;
+    }
+
+    const savedState = loadState();
+    const targetKey = findNodeKeyByUrl(currentUrl);
+
+    let finalStack: NavigationLevel[] | null = null;
+
+    // 1. Try to restore saved state + connect to target
+    if (savedState && savedState.path.length > 0) {
+      const restoredStack = buildStackFromPath(savedState.path);
+
+      if (targetKey) {
+        // Try to connect restored stack to target
+        const connectedStack = tryConnectStack(targetKey, restoredStack);
+        if (connectedStack) {
+          finalStack = connectedStack;
+        }
+      } else {
+        // No target from URL, just restore saved state
+        finalStack = restoredStack;
+      }
+    }
+
+    // 2. If no valid stack from step 1, try just the target (flattened)
+    if (!finalStack && targetKey) {
+      const targetNode = resolveRef(targetKey);
+      if (targetNode && targetNode.pages && targetNode.pages.length > 0) {
+        finalStack = [
+          { key: null, entries: roots, title: 'Documentation' },
+          { key: targetKey, entries: targetNode.pages, title: targetNode.title, badge: targetNode.badge },
+        ];
+      }
+    }
+
+    // 3. Fallback to root
+    if (!finalStack) {
+      setNavigationStack([{ key: null, entries: roots, title: 'Documentation' }]);
+    } else {
+      setNavigationStack(finalStack);
+    }
+
+    setIsInitialized(true);
+  }, [data, roots, isInitialized, buildStackFromPath, findNodeKeyByUrl, tryConnectStack, resolveRef]);
+
+  /**
+   * Save state whenever navigation changes
+   */
+  useEffect(() => {
+    if (!isInitialized) return;
+
+    const path = getCurrentPath();
+    saveState({
+      path,
+      currentUrl: window.location.pathname,
+    });
+  }, [navigationStack, isInitialized, getCurrentPath]);
+
+  /**
+   * Track current URL for highlighting active item and auto-navigation
+   */
+  useEffect(() => {
+    // Set initial path
+    setCurrentPath(window.location.pathname);
+
+    // Listen for URL changes (for client-side navigation)
+    const handleUrlChange = () => {
+      const newPath = window.location.pathname;
+      setCurrentPath(newPath);
+
+      // Try to auto-navigate to the new URL's resource
+      if (isInitialized) {
+        findAndNavigateToUrl(newPath);
+      }
+    };
+
+    window.addEventListener('popstate', handleUrlChange);
+
+    // Also listen for click events on links to catch client-side navigation
+    const handleClick = (e: MouseEvent) => {
+      const target = e.target as HTMLElement;
+      const anchor = target.closest('a');
+      if (anchor && anchor.href && anchor.href.startsWith(window.location.origin)) {
+        // Delay to let the navigation happen first
+        setTimeout(() => {
+          const newPath = window.location.pathname;
+          if (newPath !== currentPath) {
+            setCurrentPath(newPath);
+            if (isInitialized) {
+              findAndNavigateToUrl(newPath);
+            }
+          }
+        }, 100);
+      }
+    };
+
+    document.addEventListener('click', handleClick);
+
+    return () => {
+      window.removeEventListener('popstate', handleUrlChange);
+      document.removeEventListener('click', handleClick);
+    };
+  }, [isInitialized, findAndNavigateToUrl, currentPath]);
+
+  /**
+   * Check if a node is favorited
+   * Note: This hook must be defined before any early returns to comply with Rules of Hooks
+   */
+  const isFavorited = useCallback(
+    (nodeKey: string | null): boolean => {
+      if (!nodeKey) return false;
+      return favorites.some((fav) => fav.nodeKey === nodeKey);
+    },
+    [favorites]
+  );
+
+  const urlsMatch = useCallback((left: string | undefined, right: string | undefined) => {
+    if (!left || !right) return false;
+    return stripBasePath(left).replace(/\/$/, '') === stripBasePath(right).replace(/\/$/, '');
+  }, []);
+
+  const activeNodeKey = useMemo(() => findNodeKeyByUrl(currentPath), [currentPath, findNodeKeyByUrl]);
+
+  // Show loading state if no data yet
+  if (!data || roots.length === 0) {
+    return (
+      <aside className="w-full min-h-full flex-1 flex flex-col font-sans bg-[rgb(var(--ec-rail-bg))]">
+        {/* Search skeleton */}
+        <div className="px-4 py-3 border-b border-[rgb(var(--ec-content-border))] bg-[rgb(var(--ec-rail-bg))]">
+          <div className="h-10 bg-[rgb(var(--ec-content-hover))] rounded-xl animate-pulse" />
+        </div>
+        {/* Content skeleton */}
+        <div className="p-4 space-y-3">
+          {/* Group header skeleton */}
+          <div className="flex items-center gap-2 px-2 py-1.5">
+            <div className="w-3.5 h-3.5 bg-[rgb(var(--ec-content-hover))] rounded animate-pulse" />
+            <div className="h-4 w-24 bg-[rgb(var(--ec-content-hover))] rounded animate-pulse" />
+          </div>
+          {/* Item skeletons */}
+          {[1, 2, 3, 4, 5].map((i) => (
+            <div key={i} className="flex items-center gap-2.5 px-3 py-1.5 ml-3.5 border-l border-[rgb(var(--ec-content-border))]">
+              <div className="w-4 h-4 bg-[rgb(var(--ec-content-hover))] rounded animate-pulse" />
+              <div
+                className="h-4 bg-[rgb(var(--ec-content-hover))] rounded animate-pulse"
+                style={{ width: `${60 + ((i * 15) % 40)}%` }}
+              />
+            </div>
+          ))}
+          {/* Second group skeleton */}
+          <div className="flex items-center gap-2 px-2 py-1.5 mt-4">
+            <div className="w-3.5 h-3.5 bg-[rgb(var(--ec-content-hover))] rounded animate-pulse" />
+            <div className="h-4 w-20 bg-[rgb(var(--ec-content-hover))] rounded animate-pulse" />
+          </div>
+          {[1, 2, 3].map((i) => (
+            <div
+              key={`g2-${i}`}
+              className="flex items-center gap-2.5 px-3 py-1.5 ml-3.5 border-l border-[rgb(var(--ec-content-border))]"
+            >
+              <div className="w-4 h-4 bg-[rgb(var(--ec-content-hover))] rounded animate-pulse" />
+              <div
+                className="h-4 bg-[rgb(var(--ec-content-hover))] rounded animate-pulse"
+                style={{ width: `${50 + ((i * 20) % 35)}%` }}
+              />
+            </div>
+          ))}
+        </div>
+      </aside>
+    );
+  }
+
+  const currentLevel = navigationStack[navigationStack.length - 1];
+
+  /**
+   * Check if a node is a group
+   */
+  const isGroup = (node: NavNode): boolean => node.type === 'group';
+
+  /**
+   * Check if a node has children
+   */
+  const hasChildren = (node: NavNode): boolean => {
+    return (node.pages?.length ?? 0) > 0;
+  };
+
+  /**
+   * Check if a section has any visible children
+   */
+  const hasVisibleChildren = (node: NavNode): boolean => {
+    if (!node.pages) return false;
+    return node.pages.some((childRef) => {
+      const child = resolveRef(childRef);
+      return isVisible(child);
+    });
+  };
+
+  /**
+   * Count entries that actually resolve to a visible node. Some refs (e.g. unresolved
+   * `list:` aliases on an empty catalog) sit in `entries` but render nothing — those
+   * must not count, otherwise the empty state is suppressed and the rail looks blank.
+   * Mirrors the filtering in `renderEntries`.
+   */
+  const hasVisibleEntries = currentLevel.entries.some((ref) => {
+    const node = resolveRef(ref);
+    if (!isVisible(node)) return false;
+    if (isGroup(node!)) return hasVisibleChildren(node!);
+    return true;
+  });
+
+  /**
+   * Handle drilling down into an item with children
+   */
+  const handleDrillDown = (node: NavNode, nodeKey: string | null) => {
+    if (node.pages && node.pages.length > 0) {
+      setSlideDirection('forward');
+      setAnimationKey((prev) => prev + 1);
+      const newStack = [...navigationStack, { key: nodeKey, entries: node.pages, title: node.title, badge: node.badge }];
+      setNavigationStack(newStack);
+      // Reset hover states to prevent showing path preview immediately after navigation
+      setShowPathPreview(false);
+      setShowFullPath(false);
+    }
+  };
+
+  /**
+   * Navigate back one level
+   */
+  const navigateBack = () => {
+    if (navigationStack.length > 1) {
+      setSlideDirection('backward');
+      setAnimationKey((prev) => prev + 1);
+      setNavigationStack(navigationStack.slice(0, -1));
+      // Reset hover states
+      setShowPathPreview(false);
+      setShowFullPath(false);
+    }
+  };
+
+  /**
+   * Navigate to a specific level in the stack
+   */
+  const navigateToLevel = (levelIndex: number) => {
+    if (levelIndex < navigationStack.length - 1) {
+      setSlideDirection('backward');
+      setAnimationKey((prev) => prev + 1);
+      setNavigationStack(navigationStack.slice(0, levelIndex + 1));
+      setShowPathPreview(false);
+      setShowFullPath(false);
+    }
+  };
+
+  /**
+   * Toggle favorite status for a node
+   */
+  const toggleFavorite = (nodeKey: string | null, node: NavNode) => {
+    if (!nodeKey) return;
+
+    const favoriteItem: FavoriteItem = {
+      nodeKey,
+      path: getCurrentPath(),
+      title: node.title,
+      badge: node.badge,
+      href: node.href,
+    };
+
+    toggleFavoriteAction(favoriteItem);
+  };
+
+  /**
+   * Navigate to a favorited item
+   */
+  const navigateToFavorite = (favorite: FavoriteItem) => {
+    // If it has an href and no children, just navigate to the URL
+    const node = resolveRef(favorite.nodeKey);
+    if (favorite.href && (!node?.pages || node.pages.length === 0)) {
+      window.location.href = favorite.href;
+      return;
+    }
+
+    // Build the stack to this favorite
+    const stack = buildStackFromPath(favorite.path);
+
+    // If the node has children, add it to the stack
+    if (node && node.pages && node.pages.length > 0) {
+      stack.push({
+        key: favorite.nodeKey,
+        entries: node.pages,
+        title: node.title,
+        badge: node.badge,
+      });
+    }
+
+    setSlideDirection('forward');
+    setAnimationKey((prev) => prev + 1);
+    setNavigationStack(stack);
+    // Reset hover states
+    setShowPathPreview(false);
+    setShowFullPath(false);
+  };
+
+  const isTopLevel = navigationStack.length === 1;
+
+  /**
+   * Render a list of child refs (resolving keys as needed)
+   */
+  const renderEntries = (refs: ChildRef[]) => {
+    const result: React.ReactNode[] = [];
+    let currentItemGroup: { node: NavNode; key: string | null }[] = [];
+
+    const flushItemGroup = () => {
+      if (currentItemGroup.length > 0) {
+        result.push(
+          <div key={`items-${result.length}`} className="flex flex-col gap-0.5 mb-1.5">
+            {currentItemGroup.map((item, idx) => renderItem(item.node, item.key, idx))}
+          </div>
+        );
+        currentItemGroup = [];
+      }
+    };
+
+    refs.forEach((ref, index) => {
+      const node = resolveRef(ref);
+      if (!node) return;
+
+      // Skip invisible nodes
+      if (!isVisible(node)) return;
+
+      // Track the key if this is a reference
+      const nodeKey = typeof ref === 'string' ? ref : null;
+
+      if (isGroup(node)) {
+        // Skip groups with no visible children
+        if (!hasVisibleChildren(node)) return;
+
+        flushItemGroup();
+        result.push(renderGroup(node, nodeKey, index));
+      } else {
+        currentItemGroup.push({ node, key: nodeKey });
+      }
+    });
+
+    flushItemGroup();
+    return result;
+  };
+
+  /**
+   * Render a group with its children
+   */
+  const renderGroup = (group: NavNode, groupKey: string | null, index: number) => {
+    // Get optional icon for group
+    const GroupIcon = group.icon ? (LucideIcons as unknown as Record<string, LucideIcons.LucideIcon>)[group.icon] : null;
+    const isSubtleGroup = group.subtle === true;
+
+    // Get visible children
+    const visibleChildren =
+      group.pages?.filter((childRef) => {
+        const child = resolveRef(childRef);
+        return child && isVisible(child);
+      }) ?? [];
+
+    const groupId = groupKey || `group-${index}`;
+    const canCollapse = visibleChildren.length > 3;
+    const isCollapsed = collapsedSections.has(groupId);
+
+    // When a group's children are subtle subgroups (e.g. Resources > Services/Flows/Data Stores),
+    // they render flush under the parent icon instead of inside the indented border guide.
+    const hasSubtleChildren = visibleChildren.some((childRef) => {
+      const child = resolveRef(childRef);
+      return child && isGroup(child) && child.subtle === true;
+    });
+
+    const headerContent = (
+      <>
+        <div className="flex items-center gap-2">
+          {GroupIcon && (
+            <span
+              className={cn(
+                'flex items-center justify-center w-5 h-5 rounded',
+                isSubtleGroup
+                  ? 'bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-content-text-muted))]'
+                  : 'bg-[rgb(var(--ec-group-icon-bg))] text-[rgb(var(--ec-group-icon-text))]'
+              )}
+            >
+              <GroupIcon className="w-3 h-3" />
+            </span>
+          )}
+          <span
+            className={cn(
+              isSubtleGroup
+                ? 'text-[9px] font-semibold uppercase tracking-[0.1em] text-[rgb(var(--ec-content-text-muted))]'
+                : 'text-[12px] font-semibold tracking-tight text-[rgb(var(--ec-content-text))]'
+            )}
+          >
+            {group.title}
+          </span>
+        </div>
+        {canCollapse && (
+          <ChevronDown
+            className={cn(
+              isSubtleGroup ? 'w-3.5 h-3.5' : 'w-4 h-4',
+              'text-[rgb(var(--ec-icon-color))] transition-transform',
+              isCollapsed && '-rotate-90'
+            )}
+          />
+        )}
+      </>
+    );
+
+    return (
+      <div key={`group-${groupKey || index}`} className={cn(isSubtleGroup ? 'mb-2 last:mb-1' : 'mb-5 last:mb-2')}>
+        {canCollapse ? (
+          <button
+            onClick={() => toggleSectionCollapse(groupId)}
+            className={cn(
+              'flex items-center justify-between w-full rounded-md transition-colors cursor-pointer',
+              isSubtleGroup
+                ? 'px-2 py-1 hover:bg-[rgb(var(--ec-content-hover))]/60'
+                : 'px-2 py-1.5 hover:bg-[rgb(var(--ec-content-hover))]'
+            )}
+          >
+            {headerContent}
+          </button>
+        ) : (
+          <div className={cn('flex items-center justify-between', isSubtleGroup ? 'px-2 py-1' : 'px-2 py-1.5')}>
+            {headerContent}
+          </div>
+        )}
+        {!isCollapsed && (
+          <div
+            className={cn(
+              'flex flex-col gap-0.5 border-[rgb(var(--ec-content-border))]',
+              isSubtleGroup ? 'border-l ml-4 mt-1' : hasSubtleChildren ? 'mt-1' : 'border-l ml-4 mt-1'
+            )}
+          >
+            {visibleChildren.map((childRef, childIndex) => {
+              const child = resolveRef(childRef);
+              if (!child) return null;
+
+              const childKey = typeof childRef === 'string' ? childRef : null;
+
+              if (isGroup(child)) {
+                // Skip nested groups with no visible children
+                if (!hasVisibleChildren(child)) return null;
+
+                return (
+                  <div
+                    key={`nested-group-${childKey || childIndex}`}
+                    className={cn(child.subtle ? 'mt-1' : 'ml-3 mt-1.5 pl-3 border-l border-[rgb(var(--ec-content-border))]')}
+                  >
+                    {renderGroup(child, childKey, childIndex)}
+                  </div>
+                );
+              }
+              // Inside a subtle subgroup (e.g. a domain's Resources > Services list) the
+              // section header already conveys the resource type, so suppress the default
+              // per-item icon and only keep a custom icon if one is defined.
+              return renderItem(child, childKey, childIndex, isSubtleGroup);
+            })}
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  /**
+   * Render a single item
+   */
+  const renderItem = (item: NavNode, itemKey: string | null, index: number, suppressDefaultIcon = false) => {
+    const itemHasChildren = hasChildren(item);
+    const isActive = urlsMatch(item.href, currentPath) || (itemKey !== null && itemKey === activeNodeKey);
+    const isFav = isFavorited(itemKey);
+    const canFavorite = itemKey !== null; // Only items with keys can be favorited
+
+    // Get icon component from lucide-react. When suppressDefaultIcon is set (e.g. items
+    // listed under a typed subtle subgroup) the default per-collection glyph is hidden;
+    // a custom icon (item.leftIcon) is always still shown.
+    const IconComponent =
+      item.icon && !suppressDefaultIcon ? (LucideIcons as unknown as Record<string, LucideIcons.LucideIcon>)[item.icon] : null;
+    // Some glyphs fill their box more than others, so they read larger at the shared
+    // item size. Render these ~25% smaller (matching the ADR icon) to visually balance:
+    // ClipboardList (ADRs) and the message glyphs (events/commands/queries).
+    const smallerIcons = ['ClipboardList', 'Zap', 'MessageSquare', 'Search', 'Mail'];
+    const iconSizeClass = item.icon && smallerIcons.includes(item.icon) ? 'w-3 h-3' : 'w-4 h-4';
+
+    const handleStarClick = (e: React.MouseEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      toggleFavorite(itemKey, item);
+    };
+
+    const content = (
+      <>
+        <div className="flex items-center gap-2.5 min-w-0 flex-1 ">
+          {IconComponent && (
+            <span
+              className={cn(
+                'flex items-center justify-center w-5 h-5 flex-shrink-0',
+                isActive ? 'text-[rgb(var(--ec-accent-text))]' : 'text-[rgb(var(--ec-content-text-muted))]'
+              )}
+            >
+              <IconComponent className={iconSizeClass} />
+            </span>
+          )}
+          {item.leftIcon && <img src={resolveIconUrl(item.leftIcon)} alt="" loading="lazy" className="w-4 h-4 flex-shrink-0" />}
+          <span
+            className={cn(
+              'text-[12px] truncate',
+              isActive
+                ? 'text-[rgb(var(--ec-accent-text))] font-medium'
+                : 'text-[rgb(var(--ec-content-text-secondary))] group-hover:text-[rgb(var(--ec-content-text))]'
+            )}
+          >
+            {item.title}
+          </span>
+        </div>
+        <div className="flex items-center gap-1 flex-shrink-0">
+          {canFavorite && (
+            <div
+              onClick={handleStarClick}
+              className={cn(
+                'flex items-center justify-center w-5 h-5 rounded transition-colors cursor-pointer',
+                isFav
+                  ? 'text-amber-400 hover:text-amber-500'
+                  : 'text-[rgb(var(--ec-content-text-muted))] opacity-0 group-hover:opacity-100 hover:text-amber-400'
+              )}
+            >
+              <Star className={cn('w-3.5 h-3.5', isFav && 'fill-current')} />
+            </div>
+          )}
+          {itemHasChildren && (
+            <span className="flex items-center justify-center w-5 h-5 text-[rgb(var(--ec-icon-color))] group-hover:text-[rgb(var(--ec-content-text))] group-hover:translate-x-0.5 transition-transform">
+              <ChevronRight className="w-4 h-4" />
+            </span>
+          )}
+        </div>
+      </>
+    );
+
+    const baseClasses =
+      'group flex items-center justify-between w-full px-3 py-1.5 border border-transparent cursor-pointer text-left transition-colors hover:bg-[rgb(var(--ec-content-hover))] active:bg-[rgb(var(--ec-content-hover))]';
+    const parentClasses = itemHasChildren ? 'font-medium' : '';
+    const activeClasses = isActive ? 'bg-[rgb(var(--ec-rail-active-bg))] hover:bg-[rgb(var(--ec-rail-active-bg))]' : '';
+
+    // Leaf item with href → render as link
+    if (item.href && !itemHasChildren) {
+      return (
+        <a
+          key={`item-${itemKey || index}`}
+          href={item.href}
+          title={item.title}
+          target={item.external ? '_blank' : undefined}
+          className={cn(baseClasses, parentClasses, activeClasses)}
+        >
+          {content}
+        </a>
+      );
+    }
+
+    // Item with children → render as button for drill-down
+    return (
+      <button
+        key={`item-${itemKey || index}`}
+        title={item.title}
+        onClick={() => handleDrillDown(item, itemKey)}
+        className={cn(baseClasses, parentClasses, activeClasses)}
+      >
+        {content}
+      </button>
+    );
+  };
+
+  // Animation classes
+  const getAnimationClass = () => {
+    if (slideDirection === 'forward') return 'animate-slide-in-right';
+    if (slideDirection === 'backward') return 'animate-slide-in-left';
+    return '';
+  };
+
+  return (
+    <aside className="w-full min-h-full flex-1 flex flex-col font-sans bg-[rgb(var(--ec-rail-bg))]">
+      {isTopLevel && (
+        <div className="flex h-[60px] items-center px-6 bg-[rgb(var(--ec-rail-bg)/0.98)] backdrop-blur-sm border-b border-[rgb(var(--ec-content-border))] sticky top-0 z-10">
+          <span className="text-[0.65rem] font-semibold uppercase tracking-[0.18em] text-[rgb(var(--ec-sidebar-text)/0.5)] truncate">
+            All resources
+          </span>
+        </div>
+      )}
+
+      {!isTopLevel && (
+        <div
+          className="flex h-[60px] items-center px-4 bg-[rgb(var(--ec-rail-bg)/0.98)] backdrop-blur-sm border-b border-[rgb(var(--ec-content-border))] sticky top-0 z-10"
+          onMouseEnter={() => !isTopLevel && setShowPathPreview(true)}
+          onMouseLeave={() => {
+            setShowPathPreview(false);
+            setShowFullPath(false);
+          }}
+        >
+          <button
+            onClick={navigateBack}
+            disabled={isTopLevel}
+            className={cn(
+              'flex items-center gap-2 w-full px-2 py-1.5 -mx-2 rounded-md transition-colors',
+              !isTopLevel && 'hover:bg-[rgb(var(--ec-content-hover))] cursor-pointer',
+              isTopLevel && 'cursor-default'
+            )}
+          >
+            <span
+              className={cn(
+                'flex items-center justify-center w-5 h-5 text-[rgb(var(--ec-icon-color))] transition-all',
+                isTopLevel && 'opacity-0',
+                !isTopLevel && 'group-hover:-translate-x-0.5'
+              )}
+            >
+              <ChevronLeft className="w-4 h-4" />
+            </span>
+            <span className="text-[0.65rem] font-semibold uppercase tracking-[0.18em] text-[rgb(var(--ec-sidebar-text))] truncate">
+              {currentLevel.title}
+            </span>
+            {currentLevel.badge && (
+              <span
+                className={cn(
+                  'ml-auto px-2 py-0.5 text-[8px] font-semibold uppercase tracking-wide rounded',
+                  getBadgeClasses(currentLevel.badge)
+                )}
+              >
+                {currentLevel.badge}
+              </span>
+            )}
+          </button>
+
+          {/* Path Preview Dropdown */}
+          {showPathPreview && navigationStack.length > 1 && (
+            <div className="absolute left-0 right-0 top-full bg-[rgb(var(--ec-page-bg))] border-b border-[rgb(var(--ec-content-border))] shadow-lg z-20">
+              <div className="px-4 py-3">
+                <div className="text-[9px] font-medium text-[rgb(var(--ec-content-text-muted))] uppercase tracking-wide mb-2">
+                  Navigation Path
+                </div>
+                <div className="flex flex-col gap-0.5">
+                  {(() => {
+                    const SHOW_FIRST = 2; // Show first N items
+                    const SHOW_LAST = 2; // Show last N items (including current)
+                    const totalItems = navigationStack.length;
+                    const hiddenCount = totalItems - SHOW_FIRST - SHOW_LAST;
+                    const shouldTruncate = hiddenCount > 0 && !showFullPath;
+
+                    const renderPathItem = (level: NavigationLevel, index: number, displayIndex: number) => {
+                      const isCurrentLevel = index === navigationStack.length - 1;
+                      return (
+                        <button
+                          key={`path-${index}`}
+                          onClick={() => navigateToLevel(index)}
+                          disabled={isCurrentLevel}
+                          className={cn(
+                            'flex items-center gap-2 px-2 py-1.5 rounded text-left transition-colors',
+                            !isCurrentLevel && 'hover:bg-[rgb(var(--ec-content-hover))] cursor-pointer',
+                            isCurrentLevel && 'bg-[rgb(var(--ec-content-hover))] cursor-default'
+                          )}
+                          style={{ paddingLeft: `${displayIndex * 12 + 8}px` }}
+                        >
+                          {index === 0 ? (
+                            <Home className="w-3.5 h-3.5 text-[rgb(var(--ec-icon-color))] flex-shrink-0" />
+                          ) : (
+                            <ChevronRight className="w-3.5 h-3.5 text-[rgb(var(--ec-content-text-muted))] flex-shrink-0" />
+                          )}
+                          <span
+                            className={cn(
+                              'text-[12px] truncate',
+                              isCurrentLevel
+                                ? 'font-medium text-[rgb(var(--ec-content-text))]'
+                                : 'text-[rgb(var(--ec-content-text-secondary))]'
+                            )}
+                          >
+                            {level.title}
+                          </span>
+                          {level.badge && (
+                            <span
+                              className={cn(
+                                'ml-auto px-1.5 py-0.5 text-[7px] font-semibold uppercase tracking-wide rounded flex-shrink-0',
+                                getBadgeClasses(level.badge)
+                              )}
+                            >
+                              {level.badge}
+                            </span>
+                          )}
+                        </button>
+                      );
+                    };
+
+                    if (shouldTruncate) {
+                      return (
+                        <>
+                          {/* First N items */}
+                          {navigationStack.slice(0, SHOW_FIRST).map((level, index) => renderPathItem(level, index, index))}
+
+                          {/* Collapsed middle section */}
+                          <button
+                            onClick={(e) => {
+                              e.stopPropagation();
+                              setShowFullPath(true);
+                            }}
+                            className="flex items-center gap-2 px-2 py-1.5 rounded text-left transition-colors hover:bg-[rgb(var(--ec-content-hover))] cursor-pointer"
+                            style={{ paddingLeft: `${SHOW_FIRST * 12 + 8}px` }}
+                          >
+                            <span className="flex items-center justify-center w-3.5 h-3.5 text-[rgb(var(--ec-icon-color))]">
+                              <span className="text-xs">•••</span>
+                            </span>
+                            <span className="text-[12px] text-[rgb(var(--ec-content-text-muted))]">
+                              {hiddenCount} more level{hiddenCount > 1 ? 's' : ''}
+                            </span>
+                            <ChevronDown className="w-3.5 h-3.5 text-[rgb(var(--ec-icon-color))] ml-auto" />
+                          </button>
+
+                          {/* Last N items */}
+                          {navigationStack.slice(-SHOW_LAST).map((level, sliceIndex) => {
+                            const actualIndex = totalItems - SHOW_LAST + sliceIndex;
+                            return renderPathItem(level, actualIndex, SHOW_FIRST + 1 + sliceIndex);
+                          })}
+                        </>
+                      );
+                    }
+
+                    // Show full path
+                    return navigationStack.map((level, index) => renderPathItem(level, index, index));
+                  })()}
+                </div>
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Navigation Content */}
+      <nav
+        key={animationKey}
+        className={cn('flex-1 overflow-y-auto overflow-x-hidden p-4 px-2', getAnimationClass())}
+        style={{
+          scrollbarWidth: 'thin',
+          scrollbarColor: 'rgb(var(--ec-content-border)) transparent',
+        }}
+      >
+        {/* Favorites Section */}
+        {favorites.length > 0 && isTopLevel && (
+          <div className="mb-6">
+            <div className="flex items-center px-2 py-1.5">
+              <Star className="w-3.5 h-3.5 mr-2 text-amber-400 fill-current" />
+              <span className="text-[12px] text-[rgb(var(--ec-content-text))] font-semibold">Favorites</span>
+            </div>
+            <div className="flex flex-col gap-0.5 border-l ml-3.5 border-amber-200">
+              {favorites.map((fav, index) => {
+                const node = resolveRef(fav.nodeKey);
+                const isActive = fav.href && currentPath === fav.href;
+
+                return (
+                  <button
+                    key={`fav-${index}`}
+                    onClick={() => navigateToFavorite(fav)}
+                    className={cn(
+                      'group flex items-center justify-between w-full px-3 py-2 border border-transparent cursor-pointer text-left transition-colors hover:bg-amber-500/10 active:bg-amber-500/20',
+                      isActive &&
+                        'border-[rgb(var(--ec-accent)/0.16)] bg-[rgb(var(--ec-accent-subtle))] hover:bg-[rgb(var(--ec-accent-subtle))] shadow-sm'
+                    )}
+                  >
+                    <div className="flex items-center gap-2.5 min-w-0 flex-1">
+                      <span
+                        className={cn(
+                          'text-[12px] truncate',
+                          isActive
+                            ? 'text-[rgb(var(--ec-accent-text))] font-medium'
+                            : 'text-[rgb(var(--ec-content-text-secondary))] group-hover:text-[rgb(var(--ec-content-text))]'
+                        )}
+                      >
+                        {fav.title}
+                      </span>
+                    </div>
+                    <div className="flex items-center gap-1 flex-shrink-0">
+                      {fav.badge && (
+                        <span
+                          className={cn(
+                            'px-1.5 py-0.5 text-[7px] font-semibold uppercase tracking-wide rounded',
+                            getBadgeClasses(fav.badge)
+                          )}
+                        >
+                          {fav.badge}
+                        </span>
+                      )}
+                      <div
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          if (node) {
+                            toggleFavorite(fav.nodeKey, node);
+                          } else {
+                            // Node no longer exists, remove directly using nodeKey
+                            removeFavoriteAction(fav.nodeKey);
+                          }
+                        }}
+                        className="flex items-center justify-center w-5 h-5 text-amber-400 hover:text-amber-500 rounded transition-colors cursor-pointer"
+                      >
+                        <Star className="w-3.5 h-3.5 fill-current" />
+                      </div>
+                      {node?.pages && node.pages.length > 0 && (
+                        <span className="flex items-center justify-center w-5 h-5 text-[rgb(var(--ec-icon-color))] group-hover:text-[rgb(var(--ec-content-text))]">
+                          <ChevronRight className="w-4 h-4" />
+                        </span>
+                      )}
+                    </div>
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Empty State */}
+        {!hasVisibleEntries && favorites.length === 0 && (
+          <div className="flex min-h-full flex-col items-center justify-center p-8 text-center">
+            <h3 className="mb-1 text-sm font-semibold text-[rgb(var(--ec-page-text))]">Your catalog is empty</h3>
+            <p className="max-w-[220px] text-sm font-light leading-relaxed text-[rgb(var(--ec-page-text-muted))]">
+              Navigation will appear here when you add resources.{' '}
+              <a
+                href="https://www.eventcatalog.dev/docs/tutorial/install-eventcatalog"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="font-medium text-[rgb(var(--ec-accent))] hover:underline"
+              >
+                Add your first resource
+              </a>
+              .
+            </p>
+          </div>
+        )}
+
+        {hasVisibleEntries && renderEntries(currentLevel.entries)}
+      </nav>
+
+      {/* Animation keyframes */}
+      <style>{`
+                @keyframes slideInRight {
+                    from { opacity: 0; transform: translateX(40px); }
+                    to { opacity: 1; transform: translateX(0); }
+                }
+                @keyframes slideInLeft {
+                    from { opacity: 0; transform: translateX(-40px); }
+                    to { opacity: 1; transform: translateX(0); }
+                }
+                .animate-slide-in-right {
+                    animation: slideInRight 200ms ease-out forwards;
+                }
+                .animate-slide-in-left {
+                    animation: slideInLeft 200ms ease-out forwards;
+                }
+            `}</style>
+    </aside>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/SideNav/NestedSideBar/storage.ts b/packages/core/eventcatalog/src/components/SideNav/NestedSideBar/storage.ts
new file mode 100644
index 000000000..9972a41e4
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SideNav/NestedSideBar/storage.ts
@@ -0,0 +1,90 @@
+// ============================================
+// Local Storage Persistence
+// ============================================
+
+const STORAGE_KEY = 'eventcatalog-sidebar-nav';
+const COLLAPSED_SECTIONS_KEY = 'eventcatalog-sidebar-collapsed';
+const FAVORITES_KEY = 'eventcatalog-sidebar-favorites';
+
+// ============================================
+// Types
+// ============================================
+
+export type PersistedState = {
+  path: string[]; // Array of node keys representing drill-down path
+  currentUrl: string; // The URL when this state was saved
+};
+
+export type FavoriteItem = {
+  nodeKey: string; // The key of the favorited node
+  path: string[]; // Path of keys to reach this node
+  title: string; // Display title
+  badge?: string; // Type badge (Domain, Service, etc.)
+  href?: string; // Direct link if it's a leaf item
+};
+
+// ============================================
+// Navigation State
+// ============================================
+
+export const saveState = (state: PersistedState): void => {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+  } catch (e) {
+    console.warn('Failed to save sidebar state:', e);
+  }
+};
+
+export const loadState = (): PersistedState | null => {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    return stored ? JSON.parse(stored) : null;
+  } catch (e) {
+    console.warn('Failed to load sidebar state:', e);
+    return null;
+  }
+};
+
+// ============================================
+// Collapsed Sections
+// ============================================
+
+export const saveCollapsedSections = (sections: Set<string>): void => {
+  try {
+    localStorage.setItem(COLLAPSED_SECTIONS_KEY, JSON.stringify([...sections]));
+  } catch (e) {
+    console.warn('Failed to save collapsed sections:', e);
+  }
+};
+
+export const loadCollapsedSections = (): Set<string> => {
+  try {
+    const stored = localStorage.getItem(COLLAPSED_SECTIONS_KEY);
+    return stored ? new Set(JSON.parse(stored)) : new Set();
+  } catch (e) {
+    console.warn('Failed to load collapsed sections:', e);
+    return new Set();
+  }
+};
+
+// ============================================
+// Favorites
+// ============================================
+
+export const saveFavorites = (favorites: FavoriteItem[]): void => {
+  try {
+    localStorage.setItem(FAVORITES_KEY, JSON.stringify(favorites));
+  } catch (e) {
+    console.warn('Failed to save favorites:', e);
+  }
+};
+
+export const loadFavorites = (): FavoriteItem[] => {
+  try {
+    const stored = localStorage.getItem(FAVORITES_KEY);
+    return stored ? JSON.parse(stored) : [];
+  } catch (e) {
+    console.warn('Failed to load favorites:', e);
+    return [];
+  }
+};
diff --git a/packages/core/eventcatalog/src/components/SideNav/NestedSideBar/utils.ts b/packages/core/eventcatalog/src/components/SideNav/NestedSideBar/utils.ts
new file mode 100644
index 000000000..646968e8d
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SideNav/NestedSideBar/utils.ts
@@ -0,0 +1,21 @@
+// Shared utilities for NestedSideBar components
+
+/**
+ * Returns Tailwind classes for badge styling based on badge type.
+ * Uses CSS variables from theme.css for proper theming support.
+ */
+export const getBadgeClasses = (badge: string): string => {
+  const badgeColors: Record<string, string> = {
+    domain: 'bg-[rgb(var(--ec-badge-domain-bg))] text-[rgb(var(--ec-badge-domain-text))]',
+    service: 'bg-[rgb(var(--ec-badge-service-bg))] text-[rgb(var(--ec-badge-service-text))]',
+    event: 'bg-[rgb(var(--ec-badge-event-bg))] text-[rgb(var(--ec-badge-event-text))]',
+    command: 'bg-[rgb(var(--ec-badge-command-bg))] text-[rgb(var(--ec-badge-command-text))]',
+    query: 'bg-[rgb(var(--ec-badge-query-bg))] text-[rgb(var(--ec-badge-query-text))]',
+    message: 'bg-[rgb(var(--ec-badge-message-bg))] text-[rgb(var(--ec-badge-message-text))]',
+    design: 'bg-[rgb(var(--ec-badge-design-bg))] text-[rgb(var(--ec-badge-design-text))]',
+    channel: 'bg-[rgb(var(--ec-badge-channel-bg))] text-[rgb(var(--ec-badge-channel-text))]',
+    container: 'bg-[rgb(var(--ec-badge-container-bg))] text-[rgb(var(--ec-badge-container-text))]',
+    'data product': 'bg-[rgb(var(--ec-badge-data-product-bg))] text-[rgb(var(--ec-badge-data-product-text))]',
+  };
+  return badgeColors[badge.toLowerCase()] || 'bg-[rgb(var(--ec-badge-default-bg))] text-[rgb(var(--ec-badge-default-text))]';
+};
diff --git a/packages/core/eventcatalog/src/components/SideNav/SideNav.astro b/packages/core/eventcatalog/src/components/SideNav/SideNav.astro
new file mode 100644
index 000000000..7fa25a0cc
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/SideNav/SideNav.astro
@@ -0,0 +1,12 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends Omit<HTMLAttributes<'div'>, 'children'> {}
+import NestedSideBar from './NestedSideBar';
+import { ClientRouter } from 'astro:transitions';
+---
+
+<div {...Astro.props}>
+  <ClientRouter />
+  <NestedSideBar client:only="react" />
+</div>
diff --git a/eventcatalog/src/components/Studio/StudioPageModal.tsx b/packages/core/eventcatalog/src/components/Studio/StudioPageModal.tsx
similarity index 97%
rename from eventcatalog/src/components/Studio/StudioPageModal.tsx
rename to packages/core/eventcatalog/src/components/Studio/StudioPageModal.tsx
index c74943396..3a2e91641 100644
--- a/eventcatalog/src/components/Studio/StudioPageModal.tsx
+++ b/packages/core/eventcatalog/src/components/Studio/StudioPageModal.tsx
@@ -52,7 +52,7 @@ const StudioPageModal: React.FC = () => {
     <Dialog.Root open={isOpen} onOpenChange={setIsOpen}>
       <Dialog.Portal>
         <Dialog.Overlay className="fixed inset-0 bg-black/50 data-[state=open]:animate-overlayShow z-50" />
-        <Dialog.Content className="fixed top-1/2 left-1/2 w-[90vw] max-w-md -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6 shadow-xl focus:outline-none data-[state=open]:animate-contentShow z-[100]">
+        <Dialog.Content className="fixed top-1/2 left-1/2 w-[90vw] max-w-md -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6 shadow-xl focus:outline-hidden data-[state=open]:animate-contentShow z-[100]">
           <Dialog.Title className="text-lg font-semibold text-gray-900 mb-3">Open EventCatalog Studio</Dialog.Title>
 
           <Dialog.Description className="text-sm text-gray-600 mb-6">
@@ -134,7 +134,7 @@ const StudioPageModal: React.FC = () => {
             <Dialog.Close asChild>
               <button
                 type="button"
-                className="px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-500 focus:ring-offset-2 transition-colors"
+                className="px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 focus:outline-hidden focus:ring-2 focus:ring-gray-500 focus:ring-offset-2 transition-colors"
                 onClick={() => setIsOpen(false)}
               >
                 Close
diff --git a/eventcatalog/src/components/Tables/DebouncedInput.tsx b/packages/core/eventcatalog/src/components/Tables/DebouncedInput.tsx
similarity index 100%
rename from eventcatalog/src/components/Tables/DebouncedInput.tsx
rename to packages/core/eventcatalog/src/components/Tables/DebouncedInput.tsx
diff --git a/packages/core/eventcatalog/src/components/Tables/Discover/DiscoverTable.tsx b/packages/core/eventcatalog/src/components/Tables/Discover/DiscoverTable.tsx
new file mode 100644
index 000000000..135d1a184
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/Discover/DiscoverTable.tsx
@@ -0,0 +1,1340 @@
+import {
+  flexRender,
+  getCoreRowModel,
+  getFacetedMinMaxValues,
+  getFacetedRowModel,
+  getFacetedUniqueValues,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable,
+  type ColumnFiltersState,
+  type SortingState,
+} from '@tanstack/react-table';
+import { ArrowDown, ArrowUp, ArrowUpDown, ChevronLeft, ChevronRight, SearchX, X, Search, Users } from 'lucide-react';
+import { UserIcon } from '@heroicons/react/24/outline';
+import { useEffect, useMemo, useState } from 'react';
+import type { TableConfiguration } from '@types';
+import { isSameVersion } from '@utils/collections/version-compare';
+import { resolveIconUrl } from '@utils/icon';
+import { FilterDropdown, CheckboxItem } from './FilterComponents';
+import { getDiscoverColumns } from './columns';
+import { formatAdrStatus, type AdrStatus } from '@utils/collections/adr-constants';
+import { buildDiscoverFilterSearch, filterKnownValues, parseDiscoverFilterSearch } from './url-filters';
+
+export type CollectionType =
+  | 'agents'
+  | 'events'
+  | 'commands'
+  | 'queries'
+  | 'adrs'
+  | 'services'
+  | 'external-systems'
+  | 'domains'
+  | 'systems'
+  | 'flows'
+  | 'containers'
+  | 'data-products';
+
+export interface DiscoverTableData {
+  collection: string;
+  domains?: Array<{ id: string; name: string; version: string }>;
+  owners?: Array<{ id: string; name: string; type?: 'user' | 'team' }>;
+  hasSpecifications?: boolean;
+  hasOwners?: boolean;
+  hasRepository?: boolean;
+  isDeprecated?: boolean;
+  hasDataDependencies?: boolean;
+  hasTools?: boolean;
+  hasModel?: boolean;
+  hasAppliesTo?: boolean;
+  hasDecisionMakers?: boolean;
+  hasInputs?: boolean;
+  hasOutputs?: boolean;
+  hasServices?: boolean;
+  hasFlows?: boolean;
+  isSubdomain?: boolean;
+  parentDomains?: Array<{ id: string; name: string; version: string }>;
+  data: {
+    id: string;
+    name: string;
+    summary?: string;
+    icon?: string;
+    version: string;
+    latestVersion?: string;
+    draft?: boolean | { title?: string; message: string };
+    badges?: Array<{
+      id?: string;
+      content: string;
+      backgroundColor?: string;
+      textColor?: string;
+      url?: string;
+    }>;
+    status?: string;
+    date?: string | Date;
+    statusBadge?: {
+      content: string;
+      backgroundColor?: string;
+      textColor?: string;
+    };
+    producers?: Array<any>;
+    consumers?: Array<any>;
+    receives?: Array<any>;
+    sends?: Array<any>;
+    tools?: Array<any>;
+    model?: any;
+    agents?: Array<any>;
+    services?: Array<any>;
+    domains?: Array<any>;
+    flows?: Array<any>;
+    servicesThatWriteToContainer?: Array<any>;
+    servicesThatReadFromContainer?: Array<any>;
+    inputs?: Array<any>;
+    outputs?: Array<any>;
+  };
+}
+
+export interface PropertyOption {
+  id: string;
+  label: string;
+}
+
+export interface CollectionKindOption {
+  id: CollectionType;
+  label: string;
+  href: string;
+  count: number;
+}
+
+export interface DiscoverTableProps<T extends DiscoverTableData> {
+  data: T[];
+  collectionType: CollectionType;
+  collectionLabel: string;
+  collectionDescription?: string;
+  collectionKinds?: CollectionKindOption[];
+  domains?: Array<{ id: string; name: string; version: string }>;
+  owners?: Array<{ id: string; name: string; type?: 'user' | 'team' }>;
+  producers?: Array<{ id: string; name: string }>;
+  consumers?: Array<{ id: string; name: string }>;
+  agentProviders?: Array<{ id: string; name: string }>;
+  agentModels?: Array<{ id: string; name: string }>;
+  propertyOptions?: PropertyOption[];
+  tableConfiguration?: TableConfiguration;
+  showDomainsFilter?: boolean;
+  showOwnersFilter?: boolean;
+  showProducersFilter?: boolean;
+  showConsumersFilter?: boolean;
+}
+
+const getAgentModelId = (model: any) => [model?.name, model?.version].filter(Boolean).join(':');
+
+const getAgentProviderIconUrls = (provider?: string) => {
+  if (!provider) return null;
+  const providerIconName = provider
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '');
+
+  const hasThemedIcon = ['openai', 'anthropic'].includes(providerIconName);
+
+  return hasThemedIcon
+    ? {
+        light: resolveIconUrl(`/icons/agent/${providerIconName}-light.svg`),
+        dark: resolveIconUrl(`/icons/agent/${providerIconName}-dark.svg`),
+      }
+    : {
+        default: resolveIconUrl(`/icons/agent/${providerIconName}.svg`),
+      };
+};
+
+const AgentProviderIcon = ({ provider, className }: { provider: string; className: string }) => {
+  const providerIconUrls = getAgentProviderIconUrls(provider);
+  if (!providerIconUrls) return null;
+
+  if ('light' in providerIconUrls && 'dark' in providerIconUrls) {
+    return (
+      <>
+        <img src={providerIconUrls.light} alt="" className={`${className} dark:hidden`} loading="lazy" />
+        <img src={providerIconUrls.dark} alt="" className={`hidden ${className} dark:inline-block`} loading="lazy" />
+      </>
+    );
+  }
+
+  return <img src={providerIconUrls.default} alt="" className={className} loading="lazy" />;
+};
+
+const areStringArraysEqual = (left: string[], right: string[]) =>
+  left.length === right.length && left.every((value, index) => value === right[index]);
+
+const DOMAIN_TYPE_OPTIONS = [
+  { id: 'root', label: 'Root domains' },
+  { id: 'subdomain', label: 'Subdomains' },
+];
+
+export function DiscoverTable<T extends DiscoverTableData>({
+  data: initialData,
+  collectionType,
+  collectionLabel,
+  collectionDescription,
+  collectionKinds = [],
+  domains = [],
+  owners = [],
+  producers = [],
+  consumers = [],
+  agentProviders = [],
+  agentModels = [],
+  propertyOptions = [],
+  tableConfiguration,
+  showDomainsFilter = true,
+  showOwnersFilter = true,
+  showProducersFilter = false,
+  showConsumersFilter = false,
+}: DiscoverTableProps<T>) {
+  // Generate columns inside the React component to avoid hydration issues
+  const columns = useMemo(
+    () => getDiscoverColumns(collectionType, tableConfiguration ?? { columns: {} }),
+    [collectionType, tableConfiguration]
+  );
+  // Collect unique badges from all items
+  const allBadges = useMemo(() => {
+    const badgeMap = new Map<string, { content: string; backgroundColor?: string; textColor?: string; count: number }>();
+    initialData.forEach((item) => {
+      const badges = item.data?.badges || [];
+      badges.forEach((badge: any) => {
+        const existing = badgeMap.get(badge.content);
+        if (existing) {
+          existing.count++;
+        } else {
+          badgeMap.set(badge.content, {
+            content: badge.content,
+            backgroundColor: badge.backgroundColor,
+            textColor: badge.textColor,
+            count: 1,
+          });
+        }
+      });
+    });
+    return Array.from(badgeMap.values()).sort((a, b) => b.count - a.count);
+  }, [initialData]);
+  const statusCounts = useMemo(() => {
+    const counts: Record<string, number> = {};
+    initialData.forEach((item) => {
+      const status = item.data.status;
+      if (status) counts[status] = (counts[status] || 0) + 1;
+    });
+    return counts;
+  }, [initialData]);
+
+  const statusOptions = useMemo(
+    () =>
+      Object.keys(statusCounts)
+        .map((status) => ({
+          id: status,
+          name: formatAdrStatus(status as AdrStatus),
+          count: statusCounts[status],
+        }))
+        .sort((a, b) => a.name.localeCompare(b.name)),
+    [statusCounts]
+  );
+  const [initialUrlFilters] = useState(() =>
+    parseDiscoverFilterSearch(typeof window === 'undefined' ? '' : window.location.search)
+  );
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
+  const [sorting, setSorting] = useState<SortingState>([]);
+  const [tableFilter, setTableFilter] = useState(initialUrlFilters.q);
+  const PAGE_SIZE_OPTIONS = [10, 25, 50, 100];
+  const PAGE_SIZE_STORAGE_KEY = 'eventcatalog-discover-page-size';
+  const [pageSize, setPageSize] = useState<number>(() => {
+    if (typeof window === 'undefined') return 10;
+    const stored = Number(window.localStorage.getItem(PAGE_SIZE_STORAGE_KEY));
+    return PAGE_SIZE_OPTIONS.includes(stored) ? stored : 10;
+  });
+  useEffect(() => {
+    if (typeof window !== 'undefined') {
+      window.localStorage.setItem(PAGE_SIZE_STORAGE_KEY, String(pageSize));
+    }
+  }, [pageSize]);
+  const [showOnlyLatest, setShowOnlyLatest] = useState(initialUrlFilters.showOnlyLatest);
+  const [onlyShowDrafts, setOnlyShowDrafts] = useState(initialUrlFilters.onlyShowDrafts);
+  const [selectedDomains, setSelectedDomains] = useState<string[]>(() =>
+    showDomainsFilter ? filterKnownValues(initialUrlFilters.domains, new Set(domains.map((domain) => domain.id))) : []
+  );
+  const [selectedOwners, setSelectedOwners] = useState<string[]>(() =>
+    showOwnersFilter ? filterKnownValues(initialUrlFilters.owners, new Set(owners.map((owner) => owner.id))) : []
+  );
+  const [selectedProducers, setSelectedProducers] = useState<string[]>(() =>
+    showProducersFilter ? filterKnownValues(initialUrlFilters.producers, new Set(producers.map((producer) => producer.id))) : []
+  );
+  const [selectedConsumers, setSelectedConsumers] = useState<string[]>(() =>
+    showConsumersFilter ? filterKnownValues(initialUrlFilters.consumers, new Set(consumers.map((consumer) => consumer.id))) : []
+  );
+  const [selectedAgentProviders, setSelectedAgentProviders] = useState<string[]>(() =>
+    collectionType === 'agents'
+      ? filterKnownValues(initialUrlFilters.agentProviders, new Set(agentProviders.map((provider) => provider.id)))
+      : []
+  );
+  const [selectedAgentModels, setSelectedAgentModels] = useState<string[]>(() =>
+    collectionType === 'agents'
+      ? filterKnownValues(initialUrlFilters.agentModels, new Set(agentModels.map((model) => model.id)))
+      : []
+  );
+  const [selectedDomainTypes, setSelectedDomainTypes] = useState<string[]>(() =>
+    collectionType === 'domains'
+      ? initialUrlFilters.domainTypes.length > 0
+        ? filterKnownValues(initialUrlFilters.domainTypes, new Set(DOMAIN_TYPE_OPTIONS.map((option) => option.id)))
+        : ['root']
+      : []
+  );
+  const [selectedBadges, setSelectedBadges] = useState<string[]>(() =>
+    filterKnownValues(initialUrlFilters.badges, new Set(allBadges.map((badge) => badge.content)))
+  );
+  const [selectedProperties, setSelectedProperties] = useState<string[]>(() =>
+    filterKnownValues(initialUrlFilters.properties, new Set(propertyOptions.map((property) => property.id)))
+  );
+  const [selectedStatuses, setSelectedStatuses] = useState<string[]>(() =>
+    collectionType === 'adrs'
+      ? filterKnownValues(initialUrlFilters.statuses, new Set(statusOptions.map((status) => status.id)))
+      : []
+  );
+  const selectedKind = collectionKinds.find((kind) => kind.id === collectionType);
+  const knownFilterValues = useMemo(
+    () => ({
+      domains: showDomainsFilter ? new Set(domains.map((domain) => domain.id)) : new Set<string>(),
+      owners: showOwnersFilter ? new Set(owners.map((owner) => owner.id)) : new Set<string>(),
+      producers: showProducersFilter ? new Set(producers.map((producer) => producer.id)) : new Set<string>(),
+      consumers: showConsumersFilter ? new Set(consumers.map((consumer) => consumer.id)) : new Set<string>(),
+      agentProviders: collectionType === 'agents' ? new Set(agentProviders.map((provider) => provider.id)) : new Set<string>(),
+      agentModels: collectionType === 'agents' ? new Set(agentModels.map((model) => model.id)) : new Set<string>(),
+      domainTypes: collectionType === 'domains' ? new Set(DOMAIN_TYPE_OPTIONS.map((option) => option.id)) : new Set<string>(),
+      badges: new Set(allBadges.map((badge) => badge.content)),
+      properties: new Set(propertyOptions.map((property) => property.id)),
+      statuses: collectionType === 'adrs' ? new Set(statusOptions.map((status) => status.id)) : new Set<string>(),
+    }),
+    [
+      agentModels,
+      agentProviders,
+      allBadges,
+      collectionType,
+      consumers,
+      domains,
+      owners,
+      producers,
+      propertyOptions,
+      showConsumersFilter,
+      showDomainsFilter,
+      showOwnersFilter,
+      showProducersFilter,
+      statusOptions,
+    ]
+  );
+  const currentUrlFilters = useMemo(
+    () => ({
+      q: tableFilter,
+      domains: selectedDomains,
+      owners: selectedOwners,
+      producers: selectedProducers,
+      consumers: selectedConsumers,
+      agentProviders: selectedAgentProviders,
+      agentModels: selectedAgentModels,
+      badges: selectedBadges,
+      properties: selectedProperties,
+      statuses: selectedStatuses,
+      domainTypes: selectedDomainTypes,
+      showOnlyLatest,
+      onlyShowDrafts,
+    }),
+    [
+      onlyShowDrafts,
+      selectedAgentModels,
+      selectedAgentProviders,
+      selectedBadges,
+      selectedConsumers,
+      selectedDomainTypes,
+      selectedDomains,
+      selectedOwners,
+      selectedProducers,
+      selectedProperties,
+      selectedStatuses,
+      showOnlyLatest,
+      tableFilter,
+    ]
+  );
+
+  useEffect(() => {
+    const pruneState = (values: string[], knownValues: Set<string>) => {
+      const nextValues = filterKnownValues(values, knownValues);
+      return areStringArraysEqual(values, nextValues) ? values : nextValues;
+    };
+
+    setSelectedDomains((values) => pruneState(values, knownFilterValues.domains));
+    setSelectedOwners((values) => pruneState(values, knownFilterValues.owners));
+    setSelectedProducers((values) => pruneState(values, knownFilterValues.producers));
+    setSelectedConsumers((values) => pruneState(values, knownFilterValues.consumers));
+    setSelectedAgentProviders((values) => pruneState(values, knownFilterValues.agentProviders));
+    setSelectedAgentModels((values) => pruneState(values, knownFilterValues.agentModels));
+    setSelectedDomainTypes((values) => pruneState(values, knownFilterValues.domainTypes));
+    setSelectedBadges((values) => pruneState(values, knownFilterValues.badges));
+    setSelectedProperties((values) => pruneState(values, knownFilterValues.properties));
+    setSelectedStatuses((values) => pruneState(values, knownFilterValues.statuses));
+  }, [knownFilterValues]);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const nextSearch = buildDiscoverFilterSearch(currentUrlFilters, window.location.search);
+    const nextUrl = `${window.location.pathname}${nextSearch}${window.location.hash}`;
+    const currentUrl = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+
+    if (nextUrl !== currentUrl) {
+      window.history.replaceState(window.history.state, '', nextUrl);
+    }
+  }, [currentUrlFilters]);
+
+  // Filter data based on all filter states
+  const filteredData = useMemo(() => {
+    return initialData.filter((row) => {
+      // Check if item is a draft
+      const isDraft = row.data.draft === true || (typeof row.data.draft === 'object' && row.data.draft !== null);
+
+      // Draft filter
+      if (onlyShowDrafts && !isDraft) {
+        return false;
+      }
+
+      if (onlyShowDrafts) {
+        return true;
+      }
+
+      // Latest version filter
+      if (showOnlyLatest && !isSameVersion(row.data.version, row.data.latestVersion)) {
+        return false;
+      }
+
+      // Domain filter
+      if (selectedDomains.length > 0) {
+        const itemDomains = row.domains || [];
+        const hasMatchingDomain = itemDomains.some((d) => selectedDomains.includes(d.id));
+        if (!hasMatchingDomain) {
+          return false;
+        }
+      }
+
+      // Domain type filter
+      if (collectionType === 'domains' && selectedDomainTypes.length > 0) {
+        const matchesRoot = selectedDomainTypes.includes('root') && !row.isSubdomain;
+        const matchesSubdomain = selectedDomainTypes.includes('subdomain') && row.isSubdomain;
+        if (!matchesRoot && !matchesSubdomain) {
+          return false;
+        }
+      }
+
+      // Owner filter
+      if (selectedOwners.length > 0) {
+        const itemOwners = row.owners || [];
+        const hasMatchingOwner = itemOwners.some((o) => selectedOwners.includes(o.id));
+        if (!hasMatchingOwner) {
+          return false;
+        }
+      }
+
+      // Producer filter
+      if (selectedProducers.length > 0) {
+        const itemProducers = row.data.producers || [];
+        const hasMatchingProducer = itemProducers.some((p: any) => selectedProducers.includes(p.data?.id || p.id));
+        if (!hasMatchingProducer) {
+          return false;
+        }
+      }
+
+      // Consumer filter
+      if (selectedConsumers.length > 0) {
+        const itemConsumers = row.data.consumers || [];
+        const hasMatchingConsumer = itemConsumers.some((c: any) => selectedConsumers.includes(c.data?.id || c.id));
+        if (!hasMatchingConsumer) {
+          return false;
+        }
+      }
+
+      // Agent provider filter
+      if (selectedAgentProviders.length > 0) {
+        const provider = row.data.model?.provider;
+        if (!provider || !selectedAgentProviders.includes(provider)) {
+          return false;
+        }
+      }
+
+      // Agent model filter
+      if (selectedAgentModels.length > 0) {
+        const modelId = getAgentModelId(row.data.model);
+        if (!modelId || !selectedAgentModels.includes(modelId)) {
+          return false;
+        }
+      }
+
+      // Badge filter
+      if (selectedBadges.length > 0) {
+        const itemBadges = row.data?.badges || [];
+        const hasMatchingBadge = itemBadges.some((badge: any) => selectedBadges.includes(badge.content));
+        if (!hasMatchingBadge) {
+          return false;
+        }
+      }
+
+      // ADR status filter
+      if (selectedStatuses.length > 0) {
+        const status = row.data.status;
+        if (!status || !selectedStatuses.includes(status)) {
+          return false;
+        }
+      }
+
+      // Property filters
+      if (selectedProperties.length > 0) {
+        for (const prop of selectedProperties) {
+          // Generic property checks
+          if (prop === 'hasSpecifications' && !row.hasSpecifications) return false;
+          if (prop === 'hasOwners' && !row.hasOwners) return false;
+          if (prop === 'hasRepository' && !row.hasRepository) return false;
+          if (prop === 'hasDataDependencies' && !row.hasDataDependencies) return false;
+          if (prop === 'hasModel' && !row.hasModel) return false;
+          if (prop === 'hasTools' && !row.hasTools) return false;
+          if (prop === 'isDeprecated' && !row.isDeprecated) return false;
+
+          // Message-specific checks
+          if (prop === 'hasProducers') {
+            const producers = row.data.producers || [];
+            if (producers.length === 0) return false;
+          }
+          if (prop === 'hasConsumers') {
+            const consumers = row.data.consumers || [];
+            if (consumers.length === 0) return false;
+          }
+          if (prop === 'hasMessages') {
+            const sends = row.data.sends || [];
+            const receives = row.data.receives || [];
+            if (sends.length === 0 && receives.length === 0) return false;
+          }
+
+          // Service-specific checks
+          if (prop === 'hasServices') {
+            const services = row.data.services || [];
+            if (services.length === 0) return false;
+          }
+          if (prop === 'hasFlows') {
+            const flows = row.data.flows || [];
+            if (flows.length === 0) return false;
+          }
+
+          // Container-specific checks
+          if (prop === 'hasWriters') {
+            const writers = row.data.servicesThatWriteToContainer || [];
+            if (writers.length === 0) return false;
+          }
+          if (prop === 'hasReaders') {
+            const readers = row.data.servicesThatReadFromContainer || [];
+            if (readers.length === 0) return false;
+          }
+
+          // Data-product-specific checks
+          if (prop === 'hasInputs') {
+            const inputs = row.data.inputs || [];
+            if (inputs.length === 0) return false;
+          }
+          if (prop === 'hasOutputs') {
+            const outputs = row.data.outputs || [];
+            if (outputs.length === 0) return false;
+          }
+        }
+      }
+
+      // Table filter (header)
+      if (tableFilter) {
+        const searchLower = tableFilter.toLowerCase();
+        const nameMatch = row.data.name.toLowerCase().includes(searchLower);
+        const summaryMatch = row.data.summary?.toLowerCase().includes(searchLower);
+        if (!nameMatch && !summaryMatch) {
+          return false;
+        }
+      }
+
+      return true;
+    });
+  }, [
+    initialData,
+    showOnlyLatest,
+    onlyShowDrafts,
+    selectedDomains,
+    selectedOwners,
+    selectedProducers,
+    selectedConsumers,
+    selectedDomainTypes,
+    selectedAgentProviders,
+    selectedAgentModels,
+    selectedBadges,
+    selectedStatuses,
+    selectedProperties,
+    tableFilter,
+  ]);
+
+  const columnVisibility = useMemo(
+    () =>
+      Object.fromEntries(Object.entries(tableConfiguration?.columns ?? {}).map(([key, value]) => [key, value.visible ?? true])),
+    [tableConfiguration]
+  );
+
+  const table = useReactTable({
+    data: filteredData,
+    columns,
+    onColumnFiltersChange: setColumnFilters,
+    onSortingChange: setSorting,
+    getCoreRowModel: getCoreRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    getFacetedRowModel: getFacetedRowModel(),
+    getFacetedUniqueValues: getFacetedUniqueValues(),
+    getFacetedMinMaxValues: getFacetedMinMaxValues(),
+    getPaginationRowModel: getPaginationRowModel(),
+    state: {
+      columnFilters,
+      sorting,
+      columnVisibility,
+    },
+    initialState: {
+      pagination: { pageIndex: 0, pageSize },
+    },
+  });
+
+  useEffect(() => {
+    table.setPageSize(pageSize);
+  }, [pageSize, table]);
+
+  const totalResults = table.getPrePaginationRowModel().rows.length;
+  const hasResults = table.getRowModel().rows.length > 0;
+
+  // Count items per domain for the filter
+  const domainCounts = useMemo(() => {
+    const counts: Record<string, number> = {};
+    initialData.forEach((item) => {
+      const itemDomains = item.domains || [];
+      itemDomains.forEach((d) => {
+        counts[d.id] = (counts[d.id] || 0) + 1;
+      });
+    });
+    return counts;
+  }, [initialData]);
+
+  // Count items per owner for the filter
+  const ownerCounts = useMemo(() => {
+    const counts: Record<string, number> = {};
+    initialData.forEach((item) => {
+      const itemOwners = item.owners || [];
+      itemOwners.forEach((o) => {
+        counts[o.id] = (counts[o.id] || 0) + 1;
+      });
+    });
+    return counts;
+  }, [initialData]);
+
+  // Count items per producer for the filter
+  const producerCounts = useMemo(() => {
+    const counts: Record<string, number> = {};
+    initialData.forEach((item) => {
+      const itemProducers = item.data.producers || [];
+      itemProducers.forEach((p: any) => {
+        const id = p.data?.id || p.id;
+        if (id) counts[id] = (counts[id] || 0) + 1;
+      });
+    });
+    return counts;
+  }, [initialData]);
+
+  // Count items per consumer for the filter
+  const consumerCounts = useMemo(() => {
+    const counts: Record<string, number> = {};
+    initialData.forEach((item) => {
+      const itemConsumers = item.data.consumers || [];
+      itemConsumers.forEach((c: any) => {
+        const id = c.data?.id || c.id;
+        if (id) counts[id] = (counts[id] || 0) + 1;
+      });
+    });
+    return counts;
+  }, [initialData]);
+
+  const agentProviderCounts = useMemo(() => {
+    const counts: Record<string, number> = {};
+    initialData.forEach((item) => {
+      const provider = item.data.model?.provider;
+      if (provider) counts[provider] = (counts[provider] || 0) + 1;
+    });
+    return counts;
+  }, [initialData]);
+
+  const agentModelCounts = useMemo(() => {
+    const counts: Record<string, number> = {};
+    initialData.forEach((item) => {
+      const modelId = getAgentModelId(item.data.model);
+      if (modelId) counts[modelId] = (counts[modelId] || 0) + 1;
+    });
+    return counts;
+  }, [initialData]);
+
+  const domainTypeCounts = useMemo(() => {
+    const counts: Record<string, number> = { root: 0, subdomain: 0 };
+    initialData.forEach((item) => {
+      if (item.isSubdomain) {
+        counts.subdomain++;
+      } else {
+        counts.root++;
+      }
+    });
+    return counts;
+  }, [initialData]);
+
+  const toggleDomain = (domainId: string) => {
+    setSelectedDomains((prev) => (prev.includes(domainId) ? prev.filter((id) => id !== domainId) : [...prev, domainId]));
+  };
+
+  const toggleOwner = (ownerId: string) => {
+    setSelectedOwners((prev) => (prev.includes(ownerId) ? prev.filter((id) => id !== ownerId) : [...prev, ownerId]));
+  };
+
+  const toggleProducer = (producerId: string) => {
+    setSelectedProducers((prev) => (prev.includes(producerId) ? prev.filter((id) => id !== producerId) : [...prev, producerId]));
+  };
+
+  const toggleConsumer = (consumerId: string) => {
+    setSelectedConsumers((prev) => (prev.includes(consumerId) ? prev.filter((id) => id !== consumerId) : [...prev, consumerId]));
+  };
+
+  const toggleAgentProvider = (providerId: string) => {
+    setSelectedAgentProviders((prev) =>
+      prev.includes(providerId) ? prev.filter((id) => id !== providerId) : [...prev, providerId]
+    );
+  };
+
+  const toggleAgentModel = (modelId: string) => {
+    setSelectedAgentModels((prev) => (prev.includes(modelId) ? prev.filter((id) => id !== modelId) : [...prev, modelId]));
+  };
+
+  const toggleDomainType = (domainType: string) => {
+    setSelectedDomainTypes((prev) =>
+      prev.includes(domainType) ? prev.filter((id) => id !== domainType) : [...prev, domainType]
+    );
+  };
+
+  const toggleBadge = (badgeContent: string) => {
+    setSelectedBadges((prev) => (prev.includes(badgeContent) ? prev.filter((b) => b !== badgeContent) : [...prev, badgeContent]));
+  };
+
+  const toggleStatus = (status: string) => {
+    setSelectedStatuses((prev) => (prev.includes(status) ? prev.filter((item) => item !== status) : [...prev, status]));
+  };
+
+  const toggleProperty = (propertyId: string) => {
+    setSelectedProperties((prev) => (prev.includes(propertyId) ? prev.filter((p) => p !== propertyId) : [...prev, propertyId]));
+  };
+
+  const navigateToKind = (kindId: CollectionType) => {
+    const selectedKind = collectionKinds.find((kind) => kind.id === kindId);
+    if (!selectedKind || selectedKind.id === collectionType) return;
+    window.location.href = `${selectedKind.href}${buildDiscoverFilterSearch(currentUrlFilters)}`;
+  };
+
+  const clearAllFilters = () => {
+    setSelectedDomains([]);
+    setSelectedOwners([]);
+    setSelectedProducers([]);
+    setSelectedConsumers([]);
+    setSelectedAgentProviders([]);
+    setSelectedAgentModels([]);
+    setSelectedDomainTypes(collectionType === 'domains' ? ['root'] : []);
+    setSelectedBadges([]);
+    setSelectedStatuses([]);
+    setSelectedProperties([]);
+    setShowOnlyLatest(true);
+    setOnlyShowDrafts(false);
+    setTableFilter('');
+    setColumnFilters([]);
+  };
+
+  const activeFilterCount =
+    selectedDomains.length +
+    selectedOwners.length +
+    selectedProducers.length +
+    selectedConsumers.length +
+    selectedAgentProviders.length +
+    selectedAgentModels.length +
+    selectedDomainTypes.length +
+    selectedBadges.length +
+    selectedStatuses.length +
+    selectedProperties.length +
+    (!showOnlyLatest ? 1 : 0) +
+    (onlyShowDrafts ? 1 : 0) +
+    (tableFilter ? 1 : 0);
+
+  // Get selected domain names for display
+  const selectedDomainNames = selectedDomains.map((id) => domains.find((d) => d.id === id)?.name || id);
+
+  // Get selected owner names for display
+  const selectedOwnerNames = selectedOwners.map((id) => owners.find((o) => o.id === id)?.name || id);
+
+  // Get selected producer names for display
+  const selectedProducerNames = selectedProducers.map((id) => producers.find((p) => p.id === id)?.name || id);
+
+  // Get selected consumer names for display
+  const selectedConsumerNames = selectedConsumers.map((id) => consumers.find((c) => c.id === id)?.name || id);
+
+  const selectedAgentProviderNames = selectedAgentProviders.map(
+    (id) => agentProviders.find((provider) => provider.id === id)?.name || id
+  );
+  const selectedAgentModelNames = selectedAgentModels.map((id) => agentModels.find((model) => model.id === id)?.name || id);
+  const selectedDomainTypeNames = selectedDomainTypes.map(
+    (id) => DOMAIN_TYPE_OPTIONS.find((option) => option.id === id)?.label || id
+  );
+  const selectedStatusNames = selectedStatuses.map((id) => statusOptions.find((status) => status.id === id)?.name || id);
+
+  // Filter producers/consumers to only show those with count > 0
+  const filteredProducers = producers.filter((p) => (producerCounts[p.id] || 0) > 0);
+  const filteredConsumers = consumers.filter((c) => (consumerCounts[c.id] || 0) > 0);
+  const filteredAgentProviders = agentProviders.filter((provider) => (agentProviderCounts[provider.id] || 0) > 0);
+  const filteredAgentModels = agentModels.filter((model) => (agentModelCounts[model.id] || 0) > 0);
+
+  // Split owners into users and teams for the filter dropdown
+  const ownerUsers = owners.filter((o) => o.type !== 'team');
+  const ownerTeams = owners.filter((o) => o.type === 'team');
+
+  // Get selected property labels for display
+  const selectedPropertyLabels = selectedProperties.map((id) => propertyOptions.find((p) => p.id === id)?.label || id);
+
+  return (
+    <div className="flex h-full min-h-0" style={{ ['--ec-discover-sidebar-width' as any]: '320px' }}>
+      {/* Filter Sidebar */}
+      <div
+        className="fixed left-[var(--ec-vertical-nav-width)] top-0 z-20 flex h-screen w-[320px] flex-shrink-0 flex-col border-r border-[rgb(var(--ec-content-border))] bg-[rgb(var(--ec-rail-bg))]"
+        style={{ width: 'var(--ec-discover-sidebar-width, 320px)' }}
+      >
+        <div className="flex h-[60px] flex-shrink-0 items-center border-b border-[rgb(var(--ec-page-border))] px-4">
+          <h2 className="text-[0.65rem] font-semibold uppercase tracking-[0.18em] text-[rgb(var(--ec-sidebar-text)/0.5)]">
+            {collectionLabel} Filters
+          </h2>
+        </div>
+
+        {/* Filter sections */}
+        <div className="flex-1 overflow-y-auto px-4 pt-4 pb-4 space-y-6">
+          {collectionKinds.length > 1 && (
+            <div>
+              <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Kind</label>
+              <FilterDropdown
+                label="Select kind..."
+                selectedItems={selectedKind ? [selectedKind.label] : []}
+                onClear={() => {}}
+                clearable={false}
+              >
+                {collectionKinds.map((kind) => (
+                  <CheckboxItem
+                    key={kind.id}
+                    label={kind.label}
+                    checked={kind.id === collectionType}
+                    onChange={() => navigateToKind(kind.id)}
+                    count={kind.count}
+                  />
+                ))}
+              </FilterDropdown>
+            </div>
+          )}
+
+          {/* Message Filters Section */}
+          {(showProducersFilter || showConsumersFilter) && (filteredProducers.length > 0 || filteredConsumers.length > 0) && (
+            <div className="space-y-3">
+              {/* Producers Filter */}
+              {showProducersFilter && filteredProducers.length > 0 && (
+                <div>
+                  <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Producers</label>
+                  <FilterDropdown
+                    label="Select producers..."
+                    selectedItems={selectedProducerNames}
+                    onClear={() => setSelectedProducers([])}
+                    onRemoveItem={(name) => {
+                      const producer = filteredProducers.find((p) => p.name === name);
+                      if (producer) toggleProducer(producer.id);
+                    }}
+                  >
+                    {filteredProducers.map((producer) => (
+                      <CheckboxItem
+                        key={producer.id}
+                        label={producer.name}
+                        checked={selectedProducers.includes(producer.id)}
+                        onChange={() => toggleProducer(producer.id)}
+                        count={producerCounts[producer.id] || 0}
+                      />
+                    ))}
+                  </FilterDropdown>
+                </div>
+              )}
+
+              {/* Consumers Filter */}
+              {showConsumersFilter && filteredConsumers.length > 0 && (
+                <div>
+                  <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Consumers</label>
+                  <FilterDropdown
+                    label="Select consumers..."
+                    selectedItems={selectedConsumerNames}
+                    onClear={() => setSelectedConsumers([])}
+                    onRemoveItem={(name) => {
+                      const consumer = filteredConsumers.find((c) => c.name === name);
+                      if (consumer) toggleConsumer(consumer.id);
+                    }}
+                  >
+                    {filteredConsumers.map((consumer) => (
+                      <CheckboxItem
+                        key={consumer.id}
+                        label={consumer.name}
+                        checked={selectedConsumers.includes(consumer.id)}
+                        onChange={() => toggleConsumer(consumer.id)}
+                        count={consumerCounts[consumer.id] || 0}
+                      />
+                    ))}
+                  </FilterDropdown>
+                </div>
+              )}
+            </div>
+          )}
+
+          {/* Catalog Filters Section */}
+          <div className="space-y-3">
+            {collectionType === 'domains' && (
+              <div>
+                <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">
+                  Filter by Domain type
+                </label>
+                <FilterDropdown
+                  label="All domains"
+                  selectedItems={selectedDomainTypeNames}
+                  onClear={() => setSelectedDomainTypes([])}
+                  onRemoveItem={(label) => {
+                    const option = DOMAIN_TYPE_OPTIONS.find((item) => item.label === label);
+                    if (option) toggleDomainType(option.id);
+                  }}
+                >
+                  {DOMAIN_TYPE_OPTIONS.map((option) => (
+                    <CheckboxItem
+                      key={option.id}
+                      label={option.label}
+                      checked={selectedDomainTypes.includes(option.id)}
+                      onChange={() => toggleDomainType(option.id)}
+                      count={domainTypeCounts[option.id] || 0}
+                    />
+                  ))}
+                </FilterDropdown>
+              </div>
+            )}
+
+            {collectionType === 'agents' && (filteredAgentProviders.length > 0 || filteredAgentModels.length > 0) && (
+              <>
+                {filteredAgentProviders.length > 0 && (
+                  <div>
+                    <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Provider</label>
+                    <FilterDropdown
+                      label="Select providers..."
+                      selectedItems={selectedAgentProviderNames}
+                      onClear={() => setSelectedAgentProviders([])}
+                      onRemoveItem={(name) => {
+                        const provider = filteredAgentProviders.find((p) => p.name === name);
+                        if (provider) toggleAgentProvider(provider.id);
+                      }}
+                    >
+                      {filteredAgentProviders.map((provider) => (
+                        <CheckboxItem
+                          key={provider.id}
+                          label={provider.name}
+                          checked={selectedAgentProviders.includes(provider.id)}
+                          onChange={() => toggleAgentProvider(provider.id)}
+                          count={agentProviderCounts[provider.id] || 0}
+                          icon={<AgentProviderIcon provider={provider.name} className="h-3 w-3 rounded-sm object-contain" />}
+                        />
+                      ))}
+                    </FilterDropdown>
+                  </div>
+                )}
+
+                {filteredAgentModels.length > 0 && (
+                  <div>
+                    <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Model</label>
+                    <FilterDropdown
+                      label="Select models..."
+                      selectedItems={selectedAgentModelNames}
+                      onClear={() => setSelectedAgentModels([])}
+                      onRemoveItem={(name) => {
+                        const model = filteredAgentModels.find((m) => m.name === name);
+                        if (model) toggleAgentModel(model.id);
+                      }}
+                    >
+                      {filteredAgentModels.map((model) => (
+                        <CheckboxItem
+                          key={model.id}
+                          label={model.name}
+                          checked={selectedAgentModels.includes(model.id)}
+                          onChange={() => toggleAgentModel(model.id)}
+                          count={agentModelCounts[model.id] || 0}
+                        />
+                      ))}
+                    </FilterDropdown>
+                  </div>
+                )}
+              </>
+            )}
+
+            {/* Domains Filter */}
+            {showDomainsFilter && domains.length > 0 && (
+              <div>
+                <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Domains</label>
+                <FilterDropdown
+                  label="Select domains..."
+                  selectedItems={selectedDomainNames}
+                  onClear={() => setSelectedDomains([])}
+                  onRemoveItem={(name) => {
+                    const domain = domains.find((d) => d.name === name);
+                    if (domain) toggleDomain(domain.id);
+                  }}
+                >
+                  {domains.map((domain) => (
+                    <CheckboxItem
+                      key={domain.id}
+                      label={domain.name}
+                      checked={selectedDomains.includes(domain.id)}
+                      onChange={() => toggleDomain(domain.id)}
+                      count={domainCounts[domain.id] || 0}
+                    />
+                  ))}
+                </FilterDropdown>
+              </div>
+            )}
+
+            {/* Owners Filter */}
+            {showOwnersFilter && owners.length > 0 && (
+              <div>
+                <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Owners</label>
+                <FilterDropdown
+                  label="Select owners..."
+                  selectedItems={selectedOwnerNames}
+                  onClear={() => setSelectedOwners([])}
+                  onRemoveItem={(name) => {
+                    const owner = owners.find((o) => o.name === name);
+                    if (owner) toggleOwner(owner.id);
+                  }}
+                >
+                  {/* Users section */}
+                  {ownerUsers.length > 0 && (
+                    <>
+                      <div className="px-2 py-1.5 text-[10px] font-semibold uppercase tracking-wider text-[rgb(var(--ec-page-text-muted))] flex items-center gap-1.5">
+                        <UserIcon className="w-3 h-3" />
+                        Users
+                      </div>
+                      {ownerUsers.map((owner) => (
+                        <CheckboxItem
+                          key={owner.id}
+                          label={owner.name}
+                          checked={selectedOwners.includes(owner.id)}
+                          onChange={() => toggleOwner(owner.id)}
+                          count={ownerCounts[owner.id] || 0}
+                        />
+                      ))}
+                    </>
+                  )}
+                  {/* Teams section */}
+                  {ownerTeams.length > 0 && (
+                    <>
+                      <div className="px-2 py-1.5 text-[10px] font-semibold uppercase tracking-wider text-[rgb(var(--ec-page-text-muted))] flex items-center gap-1.5 mt-2 border-t border-[rgb(var(--ec-page-border))] pt-2">
+                        <Users className="w-3 h-3" />
+                        Teams
+                      </div>
+                      {ownerTeams.map((owner) => (
+                        <CheckboxItem
+                          key={owner.id}
+                          label={owner.name}
+                          checked={selectedOwners.includes(owner.id)}
+                          onChange={() => toggleOwner(owner.id)}
+                          count={ownerCounts[owner.id] || 0}
+                        />
+                      ))}
+                    </>
+                  )}
+                </FilterDropdown>
+              </div>
+            )}
+
+            {/* ADR Status Filter */}
+            {collectionType === 'adrs' && statusOptions.length > 0 && (
+              <div>
+                <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Status</label>
+                <FilterDropdown
+                  label="Select statuses..."
+                  selectedItems={selectedStatusNames}
+                  onClear={() => setSelectedStatuses([])}
+                  onRemoveItem={(name) => {
+                    const status = statusOptions.find((item) => item.name === name);
+                    if (status) toggleStatus(status.id);
+                  }}
+                >
+                  {statusOptions.map((status) => (
+                    <CheckboxItem
+                      key={status.id}
+                      label={status.name}
+                      checked={selectedStatuses.includes(status.id)}
+                      onChange={() => toggleStatus(status.id)}
+                      count={status.count}
+                    />
+                  ))}
+                </FilterDropdown>
+              </div>
+            )}
+
+            {/* Badges Filter */}
+            {allBadges.length > 0 && (
+              <div>
+                <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Badges</label>
+                <FilterDropdown
+                  label="Select badges..."
+                  selectedItems={selectedBadges}
+                  onClear={() => setSelectedBadges([])}
+                  onRemoveItem={(badge) => toggleBadge(badge)}
+                >
+                  {allBadges.map((badge) => (
+                    <CheckboxItem
+                      key={badge.content}
+                      label={badge.content}
+                      checked={selectedBadges.includes(badge.content)}
+                      onChange={() => toggleBadge(badge.content)}
+                      count={badge.count}
+                    />
+                  ))}
+                </FilterDropdown>
+              </div>
+            )}
+
+            {/* Properties Filter */}
+            {propertyOptions.length > 0 && (
+              <div>
+                <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Properties</label>
+                <FilterDropdown
+                  label="Select properties..."
+                  selectedItems={selectedPropertyLabels}
+                  onClear={() => setSelectedProperties([])}
+                  onRemoveItem={(label) => {
+                    const prop = propertyOptions.find((p) => p.label === label);
+                    if (prop) toggleProperty(prop.id);
+                  }}
+                >
+                  {propertyOptions.map((option) => (
+                    <CheckboxItem
+                      key={option.id}
+                      label={option.label}
+                      checked={selectedProperties.includes(option.id)}
+                      onChange={() => toggleProperty(option.id)}
+                    />
+                  ))}
+                </FilterDropdown>
+              </div>
+            )}
+
+            {/* Version Filter */}
+            <div>
+              <label className="block text-xs font-medium text-[rgb(var(--ec-page-text)/0.8)] mb-1.5">Version</label>
+              <FilterDropdown
+                label="Select version..."
+                selectedItems={[...(showOnlyLatest ? ['Latest only'] : []), ...(onlyShowDrafts ? ['Drafts only'] : [])]}
+                onClear={() => {
+                  setShowOnlyLatest(true);
+                  setOnlyShowDrafts(false);
+                }}
+                onRemoveItem={(item) => {
+                  if (item === 'Latest only') setShowOnlyLatest(false);
+                  if (item === 'Drafts only') setOnlyShowDrafts(false);
+                }}
+              >
+                <CheckboxItem
+                  label="Latest version only"
+                  checked={showOnlyLatest}
+                  onChange={() => setShowOnlyLatest(!showOnlyLatest)}
+                />
+                <CheckboxItem label="Drafts only" checked={onlyShowDrafts} onChange={() => setOnlyShowDrafts(!onlyShowDrafts)} />
+              </FilterDropdown>
+            </div>
+          </div>
+
+          {/* Results & Clear */}
+          <div className="flex items-center justify-between pt-3 mt-2 border-t border-[rgb(var(--ec-page-border))]">
+            <span className="text-xs text-[rgb(var(--ec-page-text-muted))]">
+              <span className="font-semibold text-[rgb(var(--ec-page-text))]">{totalResults}</span> results
+            </span>
+            {activeFilterCount > 0 && (
+              <button onClick={clearAllFilters} className="text-xs font-medium text-[rgb(var(--ec-accent))] hover:underline">
+                Clear all
+              </button>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/* Main Table */}
+      <div
+        className="flex-1 min-w-0 flex flex-col overflow-hidden"
+        style={{ marginLeft: 'var(--ec-discover-sidebar-width, 320px)' }}
+      >
+        {/* Table Header */}
+        <div className="flex items-end justify-between gap-6 px-6 py-5">
+          <div className="min-w-0">
+            <h2 className="text-2xl font-semibold text-[rgb(var(--ec-page-text))] md:text-4xl">{collectionLabel}</h2>
+            {collectionDescription && (
+              <p className="max-w-3xl pt-2 text-base font-light text-[rgb(var(--ec-page-text-muted))]">{collectionDescription}</p>
+            )}
+          </div>
+          <div className="relative">
+            <Search className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-[rgb(var(--ec-icon-color))]" />
+            <input
+              type="text"
+              value={tableFilter}
+              onChange={(e) => setTableFilter(e.target.value)}
+              placeholder="Filter..."
+              className="w-64 rounded-md border-0 bg-[rgb(var(--ec-page-bg))] py-1.5 pl-9 pr-3 text-sm font-light text-[rgb(var(--ec-header-text))] shadow-xs ring-1 ring-inset ring-[rgb(var(--ec-dropdown-border))] placeholder:text-[rgb(var(--ec-icon-color))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
+            />
+            {tableFilter && (
+              <button
+                onClick={() => setTableFilter('')}
+                className="absolute right-2 top-1/2 -translate-y-1/2 p-0.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))]"
+              >
+                <X className="w-3.5 h-3.5" />
+              </button>
+            )}
+          </div>
+        </div>
+
+        {/* Table */}
+        <div className="min-h-0 flex-1 overflow-auto px-6 pb-5">
+          <div className="overflow-hidden rounded-xl border border-[rgb(var(--ec-page-border)/0.72)] dark:border-white/10 bg-[rgb(var(--ec-dropdown-bg)/0.66)]">
+            <table className="min-w-full divide-y divide-[rgb(var(--ec-page-border)/0.62)] dark:divide-white/10">
+              <thead className="sticky top-0 z-10 bg-[rgb(var(--ec-content-hover)/0.45)]">
+                {table.getHeaderGroups().map((headerGroup, index) => (
+                  <tr key={`${headerGroup}-${index}`}>
+                    {headerGroup.headers.map((header) => (
+                      <th
+                        key={`${header.id}`}
+                        className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider"
+                      >
+                        {header.isPlaceholder ? null : header.column.id === 'date' && header.column.getCanSort() ? (
+                          <button
+                            type="button"
+                            onClick={header.column.getToggleSortingHandler()}
+                            className="flex items-center gap-1.5 rounded-sm text-left uppercase tracking-wider hover:text-[rgb(var(--ec-page-text))] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
+                          >
+                            {flexRender(header.column.columnDef.header, header.getContext())}
+                            {header.column.getIsSorted() === 'asc' ? (
+                              <ArrowUp className="h-3.5 w-3.5" />
+                            ) : header.column.getIsSorted() === 'desc' ? (
+                              <ArrowDown className="h-3.5 w-3.5" />
+                            ) : (
+                              <ArrowUpDown className="h-3.5 w-3.5 opacity-40" />
+                            )}
+                          </button>
+                        ) : (
+                          flexRender(header.column.columnDef.header, header.getContext())
+                        )}
+                      </th>
+                    ))}
+                  </tr>
+                ))}
+              </thead>
+
+              <tbody className="divide-y divide-[rgb(var(--ec-page-border)/0.5)] dark:divide-white/8">
+                {hasResults ? (
+                  table.getRowModel().rows.map((row, index) => (
+                    <tr
+                      key={`${row.id}-${index}`}
+                      className="group bg-transparent transition-colors hover:bg-[rgb(var(--ec-content-hover)/0.38)]"
+                    >
+                      {row.getVisibleCells().map((cell) => (
+                        <td
+                          key={cell.id}
+                          className={`px-4 py-3 text-sm text-[rgb(var(--ec-page-text))] ${cell.column.columnDef.meta?.className || ''}`}
+                        >
+                          {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                        </td>
+                      ))}
+                    </tr>
+                  ))
+                ) : (
+                  <tr>
+                    <td colSpan={table.getAllColumns().length} className="px-4 py-12 text-center">
+                      <div className="flex flex-col items-center justify-center text-[rgb(var(--ec-page-text-muted))]">
+                        <SearchX className="w-10 h-10 text-[rgb(var(--ec-icon-color))] mb-3 opacity-50" />
+                        <p className="text-sm font-medium text-[rgb(var(--ec-page-text-muted))]">No results found</p>
+                        <p className="text-xs text-[rgb(var(--ec-icon-color))] mt-1">Try adjusting your search or filters</p>
+                        {activeFilterCount > 0 && (
+                          <button onClick={clearAllFilters} className="mt-3 text-sm text-[rgb(var(--ec-accent))] hover:underline">
+                            Clear all filters
+                          </button>
+                        )}
+                      </div>
+                    </td>
+                  </tr>
+                )}
+              </tbody>
+            </table>
+          </div>
+        </div>
+
+        {/* Pagination */}
+        <div className="flex-shrink-0 flex items-center justify-between px-6 py-3 border-t border-[rgb(var(--ec-page-border))]">
+          <div className="flex items-center gap-3 text-xs text-[rgb(var(--ec-page-text-muted))]">
+            {totalResults > 0 && (
+              <span>
+                <span className="font-medium text-[rgb(var(--ec-page-text))]">{table.getRowModel().rows.length}</span> of{' '}
+                <span className="font-medium text-[rgb(var(--ec-page-text))]">{totalResults}</span> results
+              </span>
+            )}
+            {totalResults > 0 && <span aria-hidden className="h-3 w-px bg-[rgb(var(--ec-page-border))]" />}
+            <label className="flex items-center gap-1.5">
+              <span>Per page</span>
+              <select
+                value={pageSize}
+                onChange={(e) => setPageSize(Number(e.target.value))}
+                className="cursor-pointer rounded bg-transparent px-1 py-0.5 font-medium text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] focus:bg-[rgb(var(--ec-content-hover))] focus:outline-none"
+              >
+                {PAGE_SIZE_OPTIONS.map((size) => (
+                  <option key={size} value={size}>
+                    {size}
+                  </option>
+                ))}
+              </select>
+            </label>
+          </div>
+          <div className="flex items-center gap-1.5">
+            <button
+              className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] disabled:opacity-30 disabled:cursor-not-allowed transition-colors"
+              onClick={() => table.previousPage()}
+              disabled={!table.getCanPreviousPage()}
+              title="Previous page"
+            >
+              <ChevronLeft className="w-4 h-4" />
+            </button>
+            <span className="text-xs tabular-nums text-[rgb(var(--ec-page-text-muted))] min-w-[60px] text-center">
+              <span className="font-medium text-[rgb(var(--ec-page-text))]">{table.getState().pagination.pageIndex + 1}</span>
+              {' / '}
+              <span>{table.getPageCount() || 1}</span>
+            </span>
+            <button
+              className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] disabled:opacity-30 disabled:cursor-not-allowed transition-colors"
+              onClick={() => table.nextPage()}
+              disabled={!table.getCanNextPage()}
+              title="Next page"
+            >
+              <ChevronRight className="w-4 h-4" />
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/Tables/Discover/FilterComponents.tsx b/packages/core/eventcatalog/src/components/Tables/Discover/FilterComponents.tsx
new file mode 100644
index 000000000..98da1dacb
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/Discover/FilterComponents.tsx
@@ -0,0 +1,169 @@
+import { useState, useRef, useEffect } from 'react';
+import { X, ChevronUp, ChevronDown } from 'lucide-react';
+import { CheckIcon } from '@heroicons/react/24/outline';
+
+// Filter Dropdown Component
+export interface FilterDropdownProps {
+  label: string;
+  selectedItems: string[];
+  onClear: () => void;
+  onRemoveItem?: (item: string) => void;
+  clearable?: boolean;
+  children: React.ReactNode;
+}
+
+export const FilterDropdown = ({
+  label,
+  selectedItems,
+  onClear,
+  onRemoveItem,
+  clearable = true,
+  children,
+}: FilterDropdownProps) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+  const hasSelection = selectedItems.length > 0;
+
+  // Close dropdown when clicking outside
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+        setIsOpen(false);
+      }
+    };
+
+    if (isOpen) {
+      document.addEventListener('mousedown', handleClickOutside);
+    }
+
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside);
+    };
+  }, [isOpen]);
+
+  return (
+    <div className="relative" ref={dropdownRef}>
+      <div
+        role="button"
+        tabIndex={0}
+        onClick={() => setIsOpen(!isOpen)}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            setIsOpen(!isOpen);
+          }
+        }}
+        className={`w-full flex items-center justify-between px-3 py-2 text-xs rounded-lg border transition-colors cursor-pointer ${
+          hasSelection || isOpen
+            ? 'border-[rgb(var(--ec-accent))] bg-[rgb(var(--ec-accent)/0.05)]'
+            : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-input-bg))] hover:border-[rgb(var(--ec-icon-color))]'
+        }`}
+      >
+        <div className="flex items-center gap-2 flex-1 min-w-0 flex-wrap">
+          {hasSelection ? (
+            <div className="flex flex-wrap gap-1 items-center">
+              {selectedItems.map((item) => (
+                <span
+                  key={item}
+                  className="inline-flex items-center gap-1 px-2 py-0.5 text-xs bg-[rgb(var(--ec-accent)/0.15)] text-[rgb(var(--ec-accent))] rounded-full"
+                >
+                  {item}
+                  {onRemoveItem && (
+                    <span
+                      role="button"
+                      tabIndex={0}
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        onRemoveItem(item);
+                      }}
+                      onKeyDown={(e) => {
+                        if (e.key === 'Enter' || e.key === ' ') {
+                          e.preventDefault();
+                          e.stopPropagation();
+                          onRemoveItem(item);
+                        }
+                      }}
+                      className="hover:text-[rgb(var(--ec-page-text))] cursor-pointer"
+                    >
+                      <X className="w-3 h-3" />
+                    </span>
+                  )}
+                </span>
+              ))}
+            </div>
+          ) : (
+            <span className="text-[rgb(var(--ec-page-text-muted))]">{label}</span>
+          )}
+        </div>
+        <div className="flex items-center gap-1 flex-shrink-0 ml-2">
+          {hasSelection && clearable && (
+            <span
+              role="button"
+              tabIndex={0}
+              onClick={(e) => {
+                e.stopPropagation();
+                onClear();
+              }}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter' || e.key === ' ') {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  onClear();
+                }
+              }}
+              className="p-0.5 hover:bg-[rgb(var(--ec-content-hover))] rounded cursor-pointer"
+            >
+              <X className="w-3.5 h-3.5 text-[rgb(var(--ec-icon-color))]" />
+            </span>
+          )}
+          {isOpen ? (
+            <ChevronUp className="w-4 h-4 text-[rgb(var(--ec-icon-color))]" />
+          ) : (
+            <ChevronDown className="w-4 h-4 text-[rgb(var(--ec-icon-color))]" />
+          )}
+        </div>
+      </div>
+
+      {isOpen && (
+        <div className="absolute z-20 left-0 right-0 mt-1 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-lg shadow-lg overflow-hidden">
+          <div className="max-h-64 overflow-y-auto p-2">{children}</div>
+        </div>
+      )}
+    </div>
+  );
+};
+
+// Checkbox Item Component
+export interface CheckboxItemProps {
+  label: string;
+  checked: boolean;
+  onChange: () => void;
+  count?: number;
+  icon?: React.ReactNode;
+}
+
+export const CheckboxItem = ({ label, checked, onChange, count, icon }: CheckboxItemProps) => (
+  <button
+    onClick={onChange}
+    className={`w-full flex items-center gap-2 px-2 py-1.5 rounded-md text-left transition-colors ${
+      checked ? 'bg-[rgb(var(--ec-accent)/0.1)]' : 'hover:bg-[rgb(var(--ec-content-hover))]'
+    }`}
+  >
+    <div
+      className={`w-4 h-4 flex-shrink-0 rounded border flex items-center justify-center transition-colors ${
+        checked
+          ? 'bg-[rgb(var(--ec-accent))] border-[rgb(var(--ec-accent))]'
+          : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-input-bg))]'
+      }`}
+    >
+      {checked && <CheckIcon className="w-3 h-3 text-white" />}
+    </div>
+    {icon && <span className="flex-shrink-0 text-[rgb(var(--ec-icon-color))]">{icon}</span>}
+    <span
+      className={`text-xs flex-1 truncate ${checked ? 'font-medium text-[rgb(var(--ec-page-text))]' : 'text-[rgb(var(--ec-page-text))]'}`}
+    >
+      {label}
+    </span>
+    {count !== undefined && <span className="text-xs text-[rgb(var(--ec-page-text-muted))]">{count}</span>}
+  </button>
+);
diff --git a/packages/core/eventcatalog/src/components/Tables/Discover/__tests__/columns.spec.ts b/packages/core/eventcatalog/src/components/Tables/Discover/__tests__/columns.spec.ts
new file mode 100644
index 000000000..2a717e191
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/Discover/__tests__/columns.spec.ts
@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest';
+import { getDiscoverColumns } from '../columns';
+
+const emptyTableConfiguration = { columns: {} } as any;
+
+// Column definitions carry a stable `id`, so we can assert on the shape of the
+// table for each collection type without rendering React.
+const columnIds = (collectionType: any) =>
+  getDiscoverColumns(collectionType, emptyTableConfiguration).map((column: any) => column.id);
+
+describe('getDiscoverColumns', () => {
+  it('returns the system columns including services and flows', () => {
+    const ids = columnIds('systems');
+
+    expect(ids).toEqual(['name', 'summary', 'services', 'flows', 'badges', 'actions']);
+  });
+
+  it('returns the domain columns for domains', () => {
+    const ids = columnIds('domains');
+
+    expect(ids).toContain('services');
+    expect(ids).toContain('agents');
+  });
+
+  it('returns an empty column set for an unknown collection type', () => {
+    expect(getDiscoverColumns('unknown' as any, emptyTableConfiguration)).toEqual([]);
+  });
+});
diff --git a/packages/core/eventcatalog/src/components/Tables/Discover/__tests__/url-filters.spec.ts b/packages/core/eventcatalog/src/components/Tables/Discover/__tests__/url-filters.spec.ts
new file mode 100644
index 000000000..7bbdeea6c
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/Discover/__tests__/url-filters.spec.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { buildDiscoverFilterSearch, filterKnownValues, parseDiscoverFilterSearch } from '../url-filters';
+
+describe('discover filter URL helpers', () => {
+  it('parses repeated filter params from the URL', () => {
+    expect(
+      parseDiscoverFilterSearch(
+        '?q=orders&domain=Sales&domain=Payments&owner=team-a&domainType=subdomain&property=hasOwners&latest=false&drafts=true'
+      )
+    ).toEqual({
+      q: 'orders',
+      domains: ['Sales', 'Payments'],
+      owners: ['team-a'],
+      producers: [],
+      consumers: [],
+      agentProviders: [],
+      agentModels: [],
+      domainTypes: ['subdomain'],
+      badges: [],
+      properties: ['hasOwners'],
+      statuses: [],
+      showOnlyLatest: false,
+      onlyShowDrafts: true,
+    });
+  });
+
+  it('writes only non-default filter params and preserves unrelated params', () => {
+    expect(
+      buildDiscoverFilterSearch(
+        {
+          q: 'orders',
+          domains: ['Sales'],
+          owners: [],
+          producers: [],
+          consumers: [],
+          agentProviders: [],
+          agentModels: [],
+          domainTypes: ['root'],
+          badges: ['Critical'],
+          properties: ['hasOwners'],
+          statuses: [],
+          showOnlyLatest: false,
+          onlyShowDrafts: false,
+        },
+        '?environment=prod&domain=Old'
+      )
+    ).toBe('?environment=prod&q=orders&domain=Sales&domainType=root&badge=Critical&property=hasOwners&latest=false');
+  });
+
+  it('filters stale values against the options available on the current page', () => {
+    expect(filterKnownValues(['Sales', 'Deleted'], new Set(['Sales', 'Payments']))).toEqual(['Sales']);
+  });
+});
diff --git a/packages/core/eventcatalog/src/components/Tables/Discover/columns.tsx b/packages/core/eventcatalog/src/components/Tables/Discover/columns.tsx
new file mode 100644
index 000000000..20bcf639d
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/Discover/columns.tsx
@@ -0,0 +1,867 @@
+import { createColumnHelper } from '@tanstack/react-table';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { DocumentTextIcon, MapIcon } from '@heroicons/react/24/solid';
+import {
+  ArrowDownIcon,
+  ArrowTopRightOnSquareIcon,
+  ArrowUpIcon,
+  EllipsisVerticalIcon,
+  StarIcon,
+} from '@heroicons/react/24/outline';
+import { buildUrl } from '@utils/url-builder';
+import { getColorAndIconForCollection } from '@utils/collections/icons';
+import { getCollectionTextColorClass } from '@utils/collection-colors';
+import { getBadgeHref, getBadgeReactStyle } from '@utils/badge-styles';
+import { isIconPath, resolveIconUrl } from '@utils/icon';
+import { useStore } from '@nanostores/react';
+import { favoritesStore, toggleFavorite, type FavoriteItem } from '../../../stores/favorites-store';
+import type { DiscoverTableData, CollectionType } from './DiscoverTable';
+import type { TableConfiguration } from '@types';
+import { formatAdrDate, isAdrCollection } from '@utils/collections/adr-constants';
+import { CornerDownRight } from 'lucide-react';
+
+const columnHelper = createColumnHelper<DiscoverTableData>();
+
+const getAgentProviderIconUrls = (provider?: string) => {
+  if (!provider) return null;
+  const providerIconName = provider
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '');
+
+  const hasThemedIcon = ['openai', 'anthropic'].includes(providerIconName);
+
+  return hasThemedIcon
+    ? {
+        light: resolveIconUrl(`/icons/agent/${providerIconName}-light.svg`),
+        dark: resolveIconUrl(`/icons/agent/${providerIconName}-dark.svg`),
+      }
+    : {
+        default: resolveIconUrl(`/icons/agent/${providerIconName}.svg`),
+      };
+};
+
+const AgentProviderIcon = ({ provider, className }: { provider: string; className: string }) => {
+  const providerIconUrls = getAgentProviderIconUrls(provider);
+  if (!providerIconUrls) return null;
+
+  if ('light' in providerIconUrls && 'dark' in providerIconUrls) {
+    return (
+      <>
+        <img src={providerIconUrls.light} alt="" className={`${className} dark:hidden`} loading="lazy" />
+        <img src={providerIconUrls.dark} alt="" className={`hidden ${className} dark:inline-block`} loading="lazy" />
+      </>
+    );
+  }
+
+  return <img src={providerIconUrls.default} alt="" className={className} loading="lazy" />;
+};
+
+// Badge cell component (proper React component to use hooks)
+const BadgesCell = ({
+  badges,
+}: {
+  badges: Array<{ content: string; backgroundColor?: string; textColor?: string; url?: string }>;
+}) => {
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  if (!badges || badges.length === 0) return <span className="text-xs text-[rgb(var(--ec-icon-color))]">-</span>;
+
+  const visibleItems = isExpanded ? badges : badges.slice(0, 3);
+  const hiddenCount = badges.length - 3;
+
+  return (
+    <div className="flex flex-col gap-1 items-start">
+      {visibleItems.map((badge, index) => {
+        const href = getBadgeHref(badge);
+        const className =
+          'inline-flex items-center px-2 py-0.5 text-[11px] font-normal rounded-md max-w-[140px] truncate border border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text-muted))] bg-transparent';
+
+        return href ? (
+          <a
+            key={`${badge.content}-${index}`}
+            href={href}
+            className={className}
+            style={getBadgeReactStyle(badge)}
+            title={badge.content}
+          >
+            <span className="truncate">{badge.content}</span>
+            <ArrowTopRightOnSquareIcon className="ml-1 h-3 w-3 shrink-0 opacity-70" aria-hidden="true" />
+          </a>
+        ) : (
+          <span key={`${badge.content}-${index}`} className={className} style={getBadgeReactStyle(badge)} title={badge.content}>
+            {badge.content}
+          </span>
+        );
+      })}
+      {hiddenCount > 0 && (
+        <button onClick={() => setIsExpanded(!isExpanded)} className="text-xs text-[rgb(var(--ec-accent))] hover:underline">
+          {isExpanded ? 'less' : `+${hiddenCount}`}
+        </button>
+      )}
+    </div>
+  );
+};
+
+// Shared badge column
+const createBadgesColumn = (tableConfiguration: TableConfiguration) =>
+  columnHelper.accessor((row) => row.data.badges, {
+    id: 'badges',
+    header: () => <span>{tableConfiguration?.columns?.badges?.label || 'Badges'}</span>,
+    enableSorting: false,
+    cell: (info) => <BadgesCell badges={info.getValue() || []} />,
+    meta: {
+      showFilter: false,
+    },
+  });
+
+const ResourceNameCell = ({ item }: { item: DiscoverTableData }) => {
+  const isLatestVersion = item.data.version === item.data.latestVersion;
+  const { color, Icon } = getColorAndIconForCollection(item.collection);
+  const resourceIcon = item.data.icon;
+  const resourceIconUrl = isIconPath(resourceIcon) ? resolveIconUrl(resourceIcon) : null;
+  const isDomain = item.collection === 'domains';
+  const subdomains = isDomain ? item.data.domains || [] : [];
+
+  return (
+    <div className="flex min-w-0 flex-col gap-2">
+      <a
+        href={buildUrl(`/docs/${item.collection}/${item.data.id}/${item.data.version}`)}
+        className="group inline-flex items-center gap-2.5 hover:text-[rgb(var(--ec-accent))] transition-colors"
+      >
+        {resourceIconUrl ? (
+          <img src={resourceIconUrl} alt="" className="h-5 w-5 flex-shrink-0 rounded-sm object-contain" />
+        ) : (
+          <Icon className={`h-4 w-4 flex-shrink-0 ${getCollectionTextColorClass(color, 'text-[rgb(var(--ec-icon-color))]')}`} />
+        )}
+        <span className="text-sm font-semibold text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-accent))]">
+          {item.data.name}
+        </span>
+        {!isLatestVersion && <span className="text-xs text-[rgb(var(--ec-icon-color))]">v{item.data.version}</span>}
+        {item.isSubdomain && (
+          <span className="rounded-full border border-[rgb(var(--ec-page-border))] px-1.5 py-0.5 text-[10px] font-medium text-[rgb(var(--ec-page-text-muted))]">
+            Subdomain
+          </span>
+        )}
+      </a>
+
+      {subdomains.length > 0 && (
+        <div className="flex flex-col gap-1 pl-6">
+          {subdomains.map((domain: any) => (
+            <a
+              key={`${domain.data.id}-${domain.data.version}`}
+              href={buildUrl(`/docs/${domain.collection || 'domains'}/${domain.data.id}/${domain.data.version}`)}
+              className="group/subdomain inline-flex w-fit items-center gap-1.5 text-xs text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-accent))]"
+            >
+              <CornerDownRight className="h-3.5 w-3.5 flex-shrink-0 text-[rgb(var(--ec-icon-color))] group-hover/subdomain:text-[rgb(var(--ec-accent))]" />
+              <span className="font-medium text-[rgb(var(--ec-page-text))] group-hover/subdomain:text-[rgb(var(--ec-accent))]">
+                {domain.data.name}
+              </span>
+            </a>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+const MENU_WIDTH = 280;
+const MENU_GAP = 6;
+
+const RowActionsMenu = ({ item, collectionType }: { item: DiscoverTableData; collectionType: CollectionType }) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const menuRef = useRef<HTMLDivElement>(null);
+  const [menuPosition, setMenuPosition] = useState<{ top: number; left: number } | null>(null);
+  const favorites = useStore(favoritesStore);
+  const href = buildUrl(`/docs/${item.collection}/${item.data.id}/${item.data.version}`);
+  const visualiserHref = buildUrl(`/visualiser/${item.collection}/${item.data.id}/${item.data.version}`);
+  const hasVisualiser = !isAdrCollection(item.collection);
+  const nodeKey = `${item.collection}-${item.data.id}-${item.data.version}`;
+  const badgeLabel =
+    collectionType === 'external-systems'
+      ? 'External System'
+      : collectionType.charAt(0).toUpperCase() + collectionType.slice(1, -1);
+  const isFavorite = favorites.some((fav) => fav.nodeKey === nodeKey);
+
+  // The table lives inside scrollable, overflow-hidden containers, so the menu is
+  // rendered in a portal with fixed positioning to avoid being clipped.
+  const updatePosition = () => {
+    const button = buttonRef.current;
+    if (!button) return;
+    const rect = button.getBoundingClientRect();
+    const menuHeight = menuRef.current?.offsetHeight ?? 0;
+    const spaceBelow = window.innerHeight - rect.bottom;
+
+    // Flip above the trigger when there isn't enough room below it.
+    const openUpwards = menuHeight > 0 && spaceBelow < menuHeight + MENU_GAP && rect.top > spaceBelow;
+    const top = openUpwards ? rect.top - menuHeight - MENU_GAP : rect.bottom + MENU_GAP;
+    const left = Math.max(MENU_GAP, rect.right - MENU_WIDTH);
+
+    setMenuPosition({ top, left });
+  };
+
+  useLayoutEffect(() => {
+    if (!isOpen) return;
+    updatePosition();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isOpen]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handlePointerDown = (event: MouseEvent) => {
+      const target = event.target as Node;
+      if (!menuRef.current?.contains(target) && !buttonRef.current?.contains(target)) {
+        setIsOpen(false);
+      }
+    };
+
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        setIsOpen(false);
+      }
+    };
+
+    const handleReposition = () => updatePosition();
+
+    document.addEventListener('mousedown', handlePointerDown);
+    document.addEventListener('keydown', handleEscape);
+    window.addEventListener('resize', handleReposition);
+    window.addEventListener('scroll', handleReposition, true);
+
+    return () => {
+      document.removeEventListener('mousedown', handlePointerDown);
+      document.removeEventListener('keydown', handleEscape);
+      window.removeEventListener('resize', handleReposition);
+      window.removeEventListener('scroll', handleReposition, true);
+    };
+  }, [isOpen]);
+
+  const handleToggleFavorite = () => {
+    const favoriteItem: FavoriteItem = {
+      nodeKey,
+      path: [],
+      title: item.data.name,
+      badge: badgeLabel,
+      href,
+    };
+    toggleFavorite(favoriteItem);
+    setIsOpen(false);
+  };
+
+  return (
+    <div className="relative flex justify-end">
+      <button
+        ref={buttonRef}
+        type="button"
+        aria-haspopup="menu"
+        aria-expanded={isOpen}
+        onClick={() => setIsOpen((prev) => !prev)}
+        className="rounded-md p-1.5 text-[rgb(var(--ec-icon-color))] transition-colors hover:bg-[rgb(var(--ec-content-hover)/0.5)] hover:text-[rgb(var(--ec-page-text))]"
+      >
+        <EllipsisVerticalIcon className="h-4 w-4" />
+      </button>
+
+      {isOpen &&
+        typeof document !== 'undefined' &&
+        createPortal(
+          <div
+            ref={menuRef}
+            role="menu"
+            style={{
+              position: 'fixed',
+              top: menuPosition?.top ?? -9999,
+              left: menuPosition?.left ?? -9999,
+              width: MENU_WIDTH,
+              visibility: menuPosition ? 'visible' : 'hidden',
+            }}
+            className="z-50 overflow-hidden rounded-xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg))] shadow-xl"
+          >
+            <a
+              href={href}
+              className="flex items-center gap-2.5 px-3 py-2.5 text-xs font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-accent))]"
+            >
+              <DocumentTextIcon className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))]" />
+              View documentation
+            </a>
+            {hasVisualiser && (
+              <a
+                href={visualiserHref}
+                className="flex items-center gap-2.5 px-3 py-2.5 text-xs font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-accent))]"
+              >
+                <MapIcon className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))]" />
+                View in visualiser
+              </a>
+            )}
+            <button
+              type="button"
+              onClick={handleToggleFavorite}
+              className="flex w-full items-center gap-2.5 px-3 py-2.5 text-left text-xs font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-accent))]"
+            >
+              <StarIcon className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))]" />
+              {isFavorite ? 'Remove from favorites' : 'Add to favorites'}
+            </button>
+          </div>,
+          document.body
+        )}
+    </div>
+  );
+};
+
+// Shared actions column
+const createActionsColumn = (collectionType: CollectionType, tableConfiguration: TableConfiguration) =>
+  columnHelper.accessor('data.name', {
+    id: 'actions',
+    header: () => <span></span>,
+    enableSorting: false,
+    cell: (info) => {
+      const item = info.row.original;
+      return <RowActionsMenu item={item} collectionType={collectionType} />;
+    },
+    meta: {
+      showFilter: false,
+    },
+  });
+
+// Shared summary column
+const createSummaryColumn = (tableConfiguration: TableConfiguration) =>
+  columnHelper.accessor('data.summary', {
+    id: 'summary',
+    header: () => <span>{tableConfiguration?.columns?.summary?.label || 'Summary'}</span>,
+    cell: (info) => {
+      const summary = info.renderValue() as string;
+      const isDraft = info.row.original.data.draft;
+      const displayText = `${summary || ''}${isDraft ? ' (Draft)' : ''}`;
+      return (
+        <span className="text-[0.8rem] text-[rgb(var(--ec-icon-color))] line-clamp-2" title={displayText}>
+          {displayText}
+        </span>
+      );
+    },
+    meta: {
+      showFilter: false,
+      className: 'max-w-md',
+    },
+  });
+
+// Collection list cell renderer (for producers, consumers, services, etc.)
+const CollectionListCell = ({
+  items,
+  emptyText = '-',
+  maxVisible = 3,
+}: {
+  items: Array<{ collection: string; data: { id: string; name: string; version: string } }> | undefined;
+  emptyText?: string;
+  maxVisible?: number;
+}) => {
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  const itemsWithIcons = useMemo(
+    () =>
+      items?.map((item) => ({
+        ...item,
+        ...getColorAndIconForCollection(item.collection),
+      })) || [],
+    [items]
+  );
+
+  if (!items || items.length === 0) return <span className="text-xs text-[rgb(var(--ec-icon-color))]">{emptyText}</span>;
+
+  const visibleItems = isExpanded ? itemsWithIcons : itemsWithIcons.slice(0, maxVisible);
+  const hiddenCount = itemsWithIcons.length - maxVisible;
+
+  return (
+    <div className="flex flex-col gap-1">
+      {visibleItems.map((item, index: number) => (
+        <a
+          key={`${item.data.id}-${index}`}
+          href={buildUrl(`/docs/${item.collection}/${item.data.id}/${item.data.version}`)}
+          className="group inline-flex items-center gap-1.5 text-[0.8rem] text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-accent))] transition-colors"
+        >
+          <item.Icon className={`h-3.5 w-3.5 ${getCollectionTextColorClass(item.color)} flex-shrink-0`} />
+          <span className="truncate max-w-[120px]" title={item.data.name}>
+            {item.data.name}
+          </span>
+        </a>
+      ))}
+      {hiddenCount > 0 && (
+        <button
+          onClick={() => setIsExpanded(!isExpanded)}
+          className="text-xs text-[rgb(var(--ec-accent))] hover:underline text-left"
+        >
+          {isExpanded ? 'Show less' : `+${hiddenCount} more`}
+        </button>
+      )}
+    </div>
+  );
+};
+
+// ============================================================================
+// AGENT COLUMNS
+// ============================================================================
+export const getAgentColumns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration?.columns?.name?.label || 'Agent'}</span>,
+    cell: (info) => <ResourceNameCell item={info.row.original} />,
+    meta: {
+      filterVariant: 'name',
+    },
+  }),
+  createSummaryColumn(tableConfiguration),
+  columnHelper.accessor((row) => row.data.model?.provider, {
+    id: 'provider',
+    header: () => <span>{tableConfiguration?.columns?.provider?.label || 'Provider'}</span>,
+    cell: (info) => {
+      const provider = info.getValue() as string | undefined;
+      if (!provider) return <span className="text-xs text-[rgb(var(--ec-icon-color))]">-</span>;
+      return (
+        <span className="inline-flex items-center gap-2" title={provider} aria-label={provider}>
+          <AgentProviderIcon provider={provider} className="h-3 w-3 flex-shrink-0 rounded-sm object-contain" />
+          <span className="text-[0.8rem] font-medium text-[rgb(var(--ec-page-text))]">{provider}</span>
+        </span>
+      );
+    },
+    meta: {
+      showFilter: false,
+    },
+  }),
+  columnHelper.accessor('data.model', {
+    id: 'model',
+    header: () => <span>{tableConfiguration?.columns?.model?.label || 'Model'}</span>,
+    cell: (info) => {
+      const model = info.getValue() as any;
+      if (!model?.name) return <span className="text-xs text-[rgb(var(--ec-icon-color))]">-</span>;
+      return (
+        <div className="flex flex-col gap-0.5 text-[0.8rem]">
+          <span className="font-medium text-[rgb(var(--ec-page-text))]">{model.name}</span>
+        </div>
+      );
+    },
+    meta: {
+      showFilter: false,
+    },
+  }),
+  columnHelper.accessor('data.receives', {
+    id: 'receives',
+    header: () => (
+      <span className="flex items-center gap-1">
+        <ArrowDownIcon className="w-3.5 h-3.5" />
+        Receives
+      </span>
+    ),
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  columnHelper.accessor('data.sends', {
+    id: 'sends',
+    header: () => (
+      <span className="flex items-center gap-1">
+        <ArrowUpIcon className="w-3.5 h-3.5" />
+        Sends
+      </span>
+    ),
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  createBadgesColumn(tableConfiguration),
+  createActionsColumn('agents', tableConfiguration),
+];
+
+// ============================================================================
+// ADR COLUMNS
+// ============================================================================
+export const getAdrColumns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration?.columns?.name?.label || 'Decision record'}</span>,
+    cell: (info) => <ResourceNameCell item={info.row.original} />,
+    meta: {
+      filterVariant: 'name',
+    },
+  }),
+  createSummaryColumn(tableConfiguration),
+  columnHelper.accessor('data.statusBadge', {
+    id: 'status',
+    header: () => <span>{tableConfiguration?.columns?.status?.label || 'Status'}</span>,
+    enableSorting: false,
+    cell: (info) => {
+      const badge = info.getValue();
+      if (!badge) return <span className="text-xs text-[rgb(var(--ec-icon-color))]">-</span>;
+      return <BadgesCell badges={[badge]} />;
+    },
+    meta: {
+      showFilter: false,
+    },
+  }),
+  columnHelper.accessor('data.date', {
+    id: 'date',
+    header: () => <span>{tableConfiguration?.columns?.date?.label || 'Date'}</span>,
+    sortingFn: (rowA, rowB) => {
+      const left = rowA.original.data.date ? new Date(rowA.original.data.date).getTime() : 0;
+      const right = rowB.original.data.date ? new Date(rowB.original.data.date).getTime() : 0;
+      return left - right;
+    },
+    cell: (info) => {
+      const date = info.getValue();
+      if (!date) return <span className="text-xs text-[rgb(var(--ec-icon-color))]">-</span>;
+      return <span className="text-[0.8rem] text-[rgb(var(--ec-page-text))]">{formatAdrDate(new Date(date))}</span>;
+    },
+    meta: {
+      showFilter: false,
+    },
+  }),
+  createBadgesColumn(tableConfiguration),
+  createActionsColumn('adrs', tableConfiguration),
+];
+
+// ============================================================================
+// EVENT COLUMNS
+// ============================================================================
+export const getEventColumns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration?.columns?.name?.label || 'Event'}</span>,
+    cell: (info) => <ResourceNameCell item={info.row.original} />,
+    meta: {
+      filterVariant: 'name',
+    },
+  }),
+  createSummaryColumn(tableConfiguration),
+  columnHelper.accessor('data.producers', {
+    id: 'producers',
+    header: () => <span>Producers</span>,
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  columnHelper.accessor('data.consumers', {
+    id: 'consumers',
+    header: () => <span>Consumers</span>,
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  createBadgesColumn(tableConfiguration),
+  createActionsColumn('events', tableConfiguration),
+];
+
+// ============================================================================
+// COMMAND COLUMNS
+// ============================================================================
+export const getCommandColumns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration?.columns?.name?.label || 'Command'}</span>,
+    cell: (info) => <ResourceNameCell item={info.row.original} />,
+    meta: {
+      filterVariant: 'name',
+    },
+  }),
+  createSummaryColumn(tableConfiguration),
+  columnHelper.accessor('data.producers', {
+    id: 'producers',
+    header: () => <span>Producers</span>,
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  columnHelper.accessor('data.consumers', {
+    id: 'consumers',
+    header: () => <span>Consumers</span>,
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  createBadgesColumn(tableConfiguration),
+  createActionsColumn('commands', tableConfiguration),
+];
+
+// ============================================================================
+// QUERY COLUMNS
+// ============================================================================
+export const getQueryColumns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration?.columns?.name?.label || 'Query'}</span>,
+    cell: (info) => <ResourceNameCell item={info.row.original} />,
+    meta: {
+      filterVariant: 'name',
+    },
+  }),
+  createSummaryColumn(tableConfiguration),
+  columnHelper.accessor('data.producers', {
+    id: 'producers',
+    header: () => <span>Producers</span>,
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  columnHelper.accessor('data.consumers', {
+    id: 'consumers',
+    header: () => <span>Consumers</span>,
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  createBadgesColumn(tableConfiguration),
+  createActionsColumn('queries', tableConfiguration),
+];
+
+// ============================================================================
+// SERVICE COLUMNS
+// ============================================================================
+export const getServiceColumns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration?.columns?.name?.label || 'Service'}</span>,
+    cell: (info) => <ResourceNameCell item={info.row.original} />,
+    meta: {
+      filterVariant: 'name',
+    },
+  }),
+  createSummaryColumn(tableConfiguration),
+  columnHelper.accessor('data.receives', {
+    id: 'receives',
+    header: () => (
+      <span className="flex items-center gap-1">
+        <ArrowDownIcon className="w-3.5 h-3.5" />
+        Receives
+      </span>
+    ),
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  columnHelper.accessor('data.sends', {
+    id: 'sends',
+    header: () => (
+      <span className="flex items-center gap-1">
+        <ArrowUpIcon className="w-3.5 h-3.5" />
+        Sends
+      </span>
+    ),
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  createBadgesColumn(tableConfiguration),
+  createActionsColumn('services', tableConfiguration),
+];
+
+// ============================================================================
+// DOMAIN COLUMNS
+// ============================================================================
+export const getDomainColumns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration?.columns?.name?.label || 'Domain'}</span>,
+    cell: (info) => <ResourceNameCell item={info.row.original} />,
+    meta: {
+      filterVariant: 'name',
+    },
+  }),
+  createSummaryColumn(tableConfiguration),
+  columnHelper.accessor('data.services', {
+    id: 'services',
+    header: () => <span>Services</span>,
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  columnHelper.accessor('data.agents', {
+    id: 'agents',
+    header: () => <span>Agents</span>,
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  createBadgesColumn(tableConfiguration),
+  createActionsColumn('domains', tableConfiguration),
+];
+
+// ============================================================================
+// SYSTEM COLUMNS
+// ============================================================================
+export const getSystemColumns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration?.columns?.name?.label || 'System'}</span>,
+    cell: (info) => <ResourceNameCell item={info.row.original} />,
+    meta: {
+      filterVariant: 'name',
+    },
+  }),
+  createSummaryColumn(tableConfiguration),
+  columnHelper.accessor('data.services', {
+    id: 'services',
+    header: () => <span>Services</span>,
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  columnHelper.accessor('data.flows', {
+    id: 'flows',
+    header: () => <span>Flows</span>,
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  createBadgesColumn(tableConfiguration),
+  createActionsColumn('systems', tableConfiguration),
+];
+
+// ============================================================================
+// FLOW COLUMNS
+// ============================================================================
+export const getFlowColumns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration?.columns?.name?.label || 'Flow'}</span>,
+    cell: (info) => <ResourceNameCell item={info.row.original} />,
+    meta: {
+      filterVariant: 'name',
+    },
+  }),
+  createSummaryColumn(tableConfiguration),
+  createBadgesColumn(tableConfiguration),
+  createActionsColumn('flows', tableConfiguration),
+];
+
+// ============================================================================
+// CONTAINER (DATA) COLUMNS
+// ============================================================================
+export const getContainerColumns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration?.columns?.name?.label || 'Data'}</span>,
+    cell: (info) => <ResourceNameCell item={info.row.original} />,
+    meta: {
+      filterVariant: 'name',
+    },
+  }),
+  createSummaryColumn(tableConfiguration),
+  columnHelper.accessor('data.servicesThatWriteToContainer', {
+    id: 'writes',
+    header: () => (
+      <span className="flex items-center gap-1">
+        <ArrowDownIcon className="w-3.5 h-3.5" />
+        Writes
+      </span>
+    ),
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  columnHelper.accessor('data.servicesThatReadFromContainer', {
+    id: 'reads',
+    header: () => (
+      <span className="flex items-center gap-1">
+        <ArrowUpIcon className="w-3.5 h-3.5" />
+        Reads
+      </span>
+    ),
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  createBadgesColumn(tableConfiguration),
+  createActionsColumn('containers', tableConfiguration),
+];
+
+// ============================================================================
+// DATA PRODUCT COLUMNS
+// ============================================================================
+export const getDataProductColumns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration?.columns?.name?.label || 'Data Product'}</span>,
+    cell: (info) => <ResourceNameCell item={info.row.original} />,
+    meta: {
+      filterVariant: 'name',
+    },
+  }),
+  createSummaryColumn(tableConfiguration),
+  columnHelper.accessor('data.inputs', {
+    id: 'inputs',
+    header: () => (
+      <span className="flex items-center gap-1">
+        <ArrowDownIcon className="w-3.5 h-3.5" />
+        Inputs
+      </span>
+    ),
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  columnHelper.accessor('data.outputs', {
+    id: 'outputs',
+    header: () => (
+      <span className="flex items-center gap-1">
+        <ArrowUpIcon className="w-3.5 h-3.5" />
+        Outputs
+      </span>
+    ),
+    cell: (info) => <CollectionListCell items={info.getValue()} />,
+    meta: {
+      showFilter: false,
+    },
+  }),
+  createBadgesColumn(tableConfiguration),
+  createActionsColumn('data-products', tableConfiguration),
+];
+
+// ============================================================================
+// COLUMN GETTER BY COLLECTION TYPE
+// ============================================================================
+export const getDiscoverColumns = (collectionType: CollectionType, tableConfiguration: TableConfiguration) => {
+  switch (collectionType) {
+    case 'agents':
+      return getAgentColumns(tableConfiguration);
+    case 'adrs':
+      return getAdrColumns(tableConfiguration);
+    case 'events':
+      return getEventColumns(tableConfiguration);
+    case 'commands':
+      return getCommandColumns(tableConfiguration);
+    case 'queries':
+      return getQueryColumns(tableConfiguration);
+    case 'services':
+    case 'external-systems':
+      return getServiceColumns(tableConfiguration);
+    case 'domains':
+      return getDomainColumns(tableConfiguration);
+    case 'systems':
+      return getSystemColumns(tableConfiguration);
+    case 'flows':
+      return getFlowColumns(tableConfiguration);
+    case 'containers':
+      return getContainerColumns(tableConfiguration);
+    case 'data-products':
+      return getDataProductColumns(tableConfiguration);
+    default:
+      return [];
+  }
+};
diff --git a/packages/core/eventcatalog/src/components/Tables/Discover/index.ts b/packages/core/eventcatalog/src/components/Tables/Discover/index.ts
new file mode 100644
index 000000000..e7bef8ab1
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/Discover/index.ts
@@ -0,0 +1,10 @@
+export { DiscoverTable } from './DiscoverTable';
+export type {
+  DiscoverTableData,
+  DiscoverTableProps,
+  CollectionType,
+  CollectionKindOption,
+  PropertyOption,
+} from './DiscoverTable';
+export { FilterDropdown, CheckboxItem } from './FilterComponents';
+export type { FilterDropdownProps, CheckboxItemProps } from './FilterComponents';
diff --git a/packages/core/eventcatalog/src/components/Tables/Discover/url-filters.ts b/packages/core/eventcatalog/src/components/Tables/Discover/url-filters.ts
new file mode 100644
index 000000000..6590bd4cc
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/Discover/url-filters.ts
@@ -0,0 +1,89 @@
+export interface DiscoverFilterQueryState {
+  q: string;
+  domains: string[];
+  owners: string[];
+  producers: string[];
+  consumers: string[];
+  agentProviders: string[];
+  agentModels: string[];
+  domainTypes: string[];
+  badges: string[];
+  properties: string[];
+  statuses: string[];
+  showOnlyLatest: boolean;
+  onlyShowDrafts: boolean;
+}
+
+const FILTER_PARAM_NAMES = [
+  'q',
+  'domain',
+  'owner',
+  'producer',
+  'consumer',
+  'agentProvider',
+  'agentModel',
+  'domainType',
+  'badge',
+  'property',
+  'status',
+  'latest',
+  'drafts',
+];
+
+const uniqueNonEmpty = (values: string[]) => Array.from(new Set(values.map((value) => value.trim()).filter(Boolean)));
+
+const getValues = (params: URLSearchParams, paramName: string) => uniqueNonEmpty(params.getAll(paramName));
+
+const isFalse = (value: string | null) => value === 'false' || value === '0';
+
+const isTrue = (value: string | null) => value === 'true' || value === '1';
+
+export const parseDiscoverFilterSearch = (search: string): DiscoverFilterQueryState => {
+  const params = new URLSearchParams(search);
+
+  return {
+    q: params.get('q')?.trim() ?? '',
+    domains: getValues(params, 'domain'),
+    owners: getValues(params, 'owner'),
+    producers: getValues(params, 'producer'),
+    consumers: getValues(params, 'consumer'),
+    agentProviders: getValues(params, 'agentProvider'),
+    agentModels: getValues(params, 'agentModel'),
+    domainTypes: getValues(params, 'domainType'),
+    badges: getValues(params, 'badge'),
+    properties: getValues(params, 'property'),
+    statuses: getValues(params, 'status'),
+    showOnlyLatest: !isFalse(params.get('latest')),
+    onlyShowDrafts: isTrue(params.get('drafts')),
+  };
+};
+
+export const filterKnownValues = (values: string[], knownValues: Set<string>) => values.filter((value) => knownValues.has(value));
+
+export const buildDiscoverFilterSearch = (filters: DiscoverFilterQueryState, currentSearch = '') => {
+  const params = new URLSearchParams(currentSearch);
+  FILTER_PARAM_NAMES.forEach((paramName) => params.delete(paramName));
+
+  const appendValues = (paramName: string, values: string[]) => {
+    uniqueNonEmpty(values).forEach((value) => params.append(paramName, value));
+  };
+
+  const q = filters.q.trim();
+  if (q) params.set('q', q);
+  appendValues('domain', filters.domains);
+  appendValues('owner', filters.owners);
+  appendValues('producer', filters.producers);
+  appendValues('consumer', filters.consumers);
+  appendValues('agentProvider', filters.agentProviders);
+  appendValues('agentModel', filters.agentModels);
+  appendValues('domainType', filters.domainTypes);
+  appendValues('badge', filters.badges);
+  appendValues('property', filters.properties);
+  appendValues('status', filters.statuses);
+
+  if (!filters.showOnlyLatest) params.set('latest', 'false');
+  if (filters.onlyShowDrafts) params.set('drafts', 'true');
+
+  const search = params.toString();
+  return search ? `?${search}` : '';
+};
diff --git a/packages/core/eventcatalog/src/components/Tables/SystemResources/SystemResourcesTable.tsx b/packages/core/eventcatalog/src/components/Tables/SystemResources/SystemResourcesTable.tsx
new file mode 100644
index 000000000..0af778ec9
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/SystemResources/SystemResourcesTable.tsx
@@ -0,0 +1,267 @@
+import { useMemo, useState } from 'react';
+import {
+  createColumnHelper,
+  flexRender,
+  getCoreRowModel,
+  getSortedRowModel,
+  useReactTable,
+  type SortingState,
+} from '@tanstack/react-table';
+import { ArrowDown, ArrowUp, ArrowUpDown, Search, SearchX } from 'lucide-react';
+import { getColorAndIconForCollection } from '@utils/collections/icons';
+import { getCollectionTextColorClass } from '@utils/collection-colors';
+import { isIconPath, resolveIconUrl } from '@utils/icon';
+
+export type SystemResourceCollection = 'services' | 'flows' | 'entities' | 'containers' | 'events' | 'commands' | 'queries';
+
+export interface SystemResourceItem {
+  collection: SystemResourceCollection;
+  id: string;
+  name: string;
+  version: string;
+  summary?: string;
+  icon?: string;
+  href: string;
+}
+
+interface SystemResourcesTableProps {
+  resources: SystemResourceItem[];
+}
+
+const TYPE_LABELS: Record<SystemResourceCollection, string> = {
+  services: 'Services',
+  flows: 'Flows',
+  entities: 'Entities',
+  containers: 'Data Stores',
+  events: 'Events',
+  commands: 'Commands',
+  queries: 'Queries',
+};
+
+// Order the type filter pills follow on the page.
+const TYPE_ORDER: SystemResourceCollection[] = ['services', 'flows', 'entities', 'containers', 'events', 'commands', 'queries'];
+
+// Small icon for a collection type (used in filter pills and the type column).
+const CollectionTypeIcon = ({ collection, className }: { collection: SystemResourceCollection; className?: string }) => {
+  const { color, Icon } = getColorAndIconForCollection(collection);
+  const colorClass = getCollectionTextColorClass(color, 'text-[rgb(var(--ec-icon-color))]');
+  return <Icon className={`${className ?? 'h-3.5 w-3.5'} ${colorClass}`} aria-hidden="true" />;
+};
+
+const ResourceIcon = ({ item }: { item: SystemResourceItem }) => {
+  if (item.icon && isIconPath(item.icon)) {
+    return <img src={resolveIconUrl(item.icon)} alt="" className="h-5 w-5" loading="lazy" />;
+  }
+  return <CollectionTypeIcon collection={item.collection} className="h-5 w-5" />;
+};
+
+const columnHelper = createColumnHelper<SystemResourceItem>();
+
+const SortIcon = ({ direction }: { direction: false | 'asc' | 'desc' }) => {
+  if (direction === 'asc') return <ArrowUp className="h-3.5 w-3.5" aria-hidden="true" />;
+  if (direction === 'desc') return <ArrowDown className="h-3.5 w-3.5" aria-hidden="true" />;
+  return <ArrowUpDown className="h-3.5 w-3.5 opacity-40" aria-hidden="true" />;
+};
+
+export function SystemResourcesTable({ resources }: SystemResourcesTableProps) {
+  const [search, setSearch] = useState('');
+  const [selectedTypes, setSelectedTypes] = useState<SystemResourceCollection[]>([]);
+  const [sorting, setSorting] = useState<SortingState>([{ id: 'name', desc: false }]);
+
+  // Only show type filters that actually have resources in this system.
+  const availableTypes = useMemo(
+    () => TYPE_ORDER.filter((type) => resources.some((resource) => resource.collection === type)),
+    [resources]
+  );
+
+  const filtered = useMemo(() => {
+    const query = search.trim().toLowerCase();
+    return resources.filter((resource) => {
+      if (selectedTypes.length > 0 && !selectedTypes.includes(resource.collection)) {
+        return false;
+      }
+      if (query) {
+        const haystack = `${resource.name} ${resource.id} ${resource.summary ?? ''}`.toLowerCase();
+        if (!haystack.includes(query)) return false;
+      }
+      return true;
+    });
+  }, [resources, search, selectedTypes]);
+
+  const columns = useMemo(
+    () => [
+      columnHelper.accessor('name', {
+        header: 'Name',
+        cell: (info) => {
+          const resource = info.row.original;
+          return (
+            <a href={resource.href} className="group flex items-center gap-3">
+              <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg))]">
+                <ResourceIcon item={resource} />
+              </span>
+              <span className="text-sm font-medium text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-accent))]">
+                {resource.name}
+              </span>
+            </a>
+          );
+        },
+      }),
+      columnHelper.accessor((row) => TYPE_LABELS[row.collection], {
+        id: 'type',
+        header: 'Type',
+        cell: (info) => {
+          const { collection } = info.row.original;
+          return (
+            <span className="inline-flex items-center gap-1.5 text-sm text-[rgb(var(--ec-page-text-muted))]">
+              <CollectionTypeIcon collection={collection} />
+              {TYPE_LABELS[collection]}
+            </span>
+          );
+        },
+      }),
+      columnHelper.accessor('version', {
+        header: 'Version',
+        cell: (info) => (
+          <span className="inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] px-2 py-0.5 text-xs text-[rgb(var(--ec-page-text-muted))]">
+            v{info.getValue()}
+          </span>
+        ),
+      }),
+      columnHelper.accessor((row) => row.summary ?? '', {
+        id: 'summary',
+        header: 'Summary',
+        enableSorting: false,
+        cell: (info) => (
+          <span className="line-clamp-2 text-sm text-[rgb(var(--ec-page-text-muted))]">{info.getValue() || '-'}</span>
+        ),
+      }),
+    ],
+    []
+  );
+
+  const table = useReactTable({
+    data: filtered,
+    columns,
+    state: { sorting },
+    onSortingChange: setSorting,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+  });
+
+  const toggleType = (type: SystemResourceCollection) => {
+    setSelectedTypes((prev) => (prev.includes(type) ? prev.filter((t) => t !== type) : [...prev, type]));
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      {/* Controls: search + type filters */}
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+        <div className="relative w-full sm:max-w-xs">
+          <Search
+            className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-[rgb(var(--ec-icon-color))]"
+            aria-hidden="true"
+          />
+          <input
+            type="text"
+            value={search}
+            onChange={(event) => setSearch(event.target.value)}
+            placeholder="Search resources..."
+            className="w-full rounded-md border border-[rgb(var(--ec-input-border))] bg-[rgb(var(--ec-input-bg))] py-2 pl-9 pr-3 text-sm text-[rgb(var(--ec-input-text))] placeholder:text-[rgb(var(--ec-page-text-muted))] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent)/0.4)]"
+          />
+        </div>
+
+        {availableTypes.length > 1 && (
+          <div className="flex flex-wrap gap-2">
+            {availableTypes.map((type) => {
+              const active = selectedTypes.includes(type);
+              return (
+                <button
+                  key={type}
+                  type="button"
+                  onClick={() => toggleType(type)}
+                  className={[
+                    'inline-flex items-center gap-1.5 rounded-full border px-3 py-1 text-xs font-medium transition-colors',
+                    active
+                      ? 'border-[rgb(var(--ec-accent))] bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent))]'
+                      : 'border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]',
+                  ].join(' ')}
+                >
+                  <CollectionTypeIcon collection={type} />
+                  {TYPE_LABELS[type]}
+                </button>
+              );
+            })}
+          </div>
+        )}
+      </div>
+
+      {/* Table */}
+      <div className="overflow-hidden rounded-lg border border-[rgb(var(--ec-page-border))]">
+        <table className="min-w-full divide-y divide-[rgb(var(--ec-page-border))]">
+          <thead className="bg-[rgb(var(--ec-card-bg))]">
+            {table.getHeaderGroups().map((headerGroup) => (
+              <tr key={headerGroup.id}>
+                {headerGroup.headers.map((header) => {
+                  const canSort = header.column.getCanSort();
+                  const isSummary = header.column.id === 'summary';
+                  return (
+                    <th
+                      key={header.id}
+                      className={[
+                        'px-4 py-3 text-left text-xs font-semibold uppercase tracking-wider text-[rgb(var(--ec-page-text-muted))]',
+                        isSummary ? 'hidden md:table-cell' : '',
+                      ].join(' ')}
+                    >
+                      {canSort ? (
+                        <button
+                          type="button"
+                          onClick={header.column.getToggleSortingHandler()}
+                          className="inline-flex items-center gap-1.5 uppercase tracking-wider hover:text-[rgb(var(--ec-page-text))]"
+                        >
+                          {flexRender(header.column.columnDef.header, header.getContext())}
+                          <SortIcon direction={header.column.getIsSorted()} />
+                        </button>
+                      ) : (
+                        flexRender(header.column.columnDef.header, header.getContext())
+                      )}
+                    </th>
+                  );
+                })}
+              </tr>
+            ))}
+          </thead>
+          <tbody className="divide-y divide-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))]">
+            {table.getRowModel().rows.length === 0 && (
+              <tr>
+                <td colSpan={columns.length} className="px-4 py-12">
+                  <div className="flex flex-col items-center justify-center gap-2 text-center text-[rgb(var(--ec-page-text-muted))]">
+                    <SearchX className="h-6 w-6" aria-hidden="true" />
+                    <p className="text-sm">No resources found.</p>
+                  </div>
+                </td>
+              </tr>
+            )}
+            {table.getRowModel().rows.map((row) => (
+              <tr key={row.id} className="transition-colors hover:bg-[rgb(var(--ec-card-bg))]">
+                {row.getVisibleCells().map((cell) => {
+                  const isSummary = cell.column.id === 'summary';
+                  return (
+                    <td key={cell.id} className={['px-4 py-3', isSummary ? 'hidden max-w-md md:table-cell' : ''].join(' ')}>
+                      {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                    </td>
+                  );
+                })}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+
+      <p className="text-xs text-[rgb(var(--ec-page-text-muted))]">
+        Showing {filtered.length} of {resources.length} resources
+      </p>
+    </div>
+  );
+}
+
+export default SystemResourcesTable;
diff --git a/packages/core/eventcatalog/src/components/Tables/Table.tsx b/packages/core/eventcatalog/src/components/Tables/Table.tsx
new file mode 100644
index 000000000..c1690ee15
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/Table.tsx
@@ -0,0 +1,446 @@
+import {
+  flexRender,
+  getCoreRowModel,
+  getFacetedMinMaxValues,
+  getFacetedRowModel,
+  getFacetedUniqueValues,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  useReactTable,
+  type Column,
+  type ColumnFiltersState,
+} from '@tanstack/react-table';
+import DebouncedInput from './DebouncedInput';
+import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight, SearchX } from 'lucide-react';
+
+import { getColumnsByCollection } from './columns';
+import { useEffect, useMemo, useState } from 'react';
+import type { CollectionMessageTypes, TableConfiguration } from '@types';
+import { isSameVersion } from '@utils/collections/version-compare';
+
+declare module '@tanstack/react-table' {
+  // @ts-ignore
+  interface ColumnMeta<TData extends RowData, TValue> {
+    filterVariant?: 'collection' | 'name' | 'badges' | 'text';
+    collectionFilterKey?:
+      | 'producers'
+      | 'consumers'
+      | 'sends'
+      | 'receives'
+      | 'services'
+      | 'ownedCommands'
+      | 'ownedQueries'
+      | 'ownedEvents'
+      | 'ownedAgents'
+      | 'ownedServices'
+      | 'associatedTeams'
+      | 'servicesThatWriteToContainer'
+      | 'servicesThatReadFromContainer';
+    filteredItemHasVersion?: boolean;
+    showFilter?: boolean;
+    className?: string;
+  }
+}
+
+export type TCollectionTypes = 'domains' | 'services' | CollectionMessageTypes | 'flows' | 'users' | 'teams' | 'containers';
+
+export type TData<T extends TCollectionTypes> = {
+  collection: T;
+  data: {
+    id: string;
+    name: string;
+    summary: string;
+    version: string;
+    source?: {
+      provider: string;
+      url?: string;
+    };
+    latestVersion?: string; // Defined on getter collection utility
+    draft?: boolean | { title?: string; message: string }; // Draft property from base schema
+    badges?: Array<{
+      id: string; // Where is it defined?
+      content: string;
+      backgroundColor: string;
+      textColor: string;
+      icon: any; // Where is it defined?
+      url?: string;
+    }>;
+    // ---------------------------------------------------------------------------
+    // Domains
+    services?: Array<{
+      collection: string; // Be more specific;
+      data: {
+        id: string;
+        name: string;
+        version: string;
+      };
+    }>;
+    // ---------------------------------------------------------------------------
+    // Services
+    receives?: Array<{
+      collection: string; // Be more specific;
+      data: {
+        id: string;
+        name: string;
+        version: string;
+      };
+    }>;
+    sends?: Array<{
+      collection: string; // Be more specific;
+      data: {
+        id: string;
+        name: string;
+        version: string;
+      };
+    }>;
+    // ---------------------------------------------------------------------------
+    // Messages
+    producers?: Array<{
+      collection: string; // Specify only 'services'?
+      data: {
+        id: string;
+        name: string;
+        version: string;
+      };
+    }>;
+    // Only for messages
+    consumers?: Array<{
+      collection: string; // Specify only 'services'?
+      data: {
+        id: string;
+        name: string;
+        version: string;
+      };
+    }>;
+    // Only for containers
+    servicesThatWriteToContainer?: Array<{
+      collection: string; // Specify only 'services'?
+      data: {
+        id: string;
+        name: string;
+        version: string;
+      };
+    }>;
+    // Only for containers
+    servicesThatReadFromContainer?: Array<{
+      collection: string; // Specify only 'services'?
+      data: {
+        id: string;
+        name: string;
+        version: string;
+      };
+    }>;
+    // ---------------------------------------------------------------------------
+    // Users
+    avatarUrl?: string;
+    email?: string;
+    slackDirectMessageUrl?: string;
+    msTeamsDirectMessageUrl?: string;
+    role?: string;
+    ownedCommands: any;
+    ownedEvents: any;
+    ownedAgents: any;
+    ownedServices: any;
+    associatedTeams: any;
+    ownedQueries: any;
+    // Teams
+    members: any;
+  };
+};
+
+export const Table = <T extends TCollectionTypes>({
+  data: initialData,
+  collection,
+  mode = 'simple',
+  checkboxLatestId,
+  checkboxDraftsId,
+  tableConfiguration,
+}: {
+  data: TData<T>[];
+  collection: T;
+  checkboxLatestId: string;
+  checkboxDraftsId: string;
+  mode?: 'simple' | 'full';
+  tableConfiguration?: TableConfiguration;
+}) => {
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
+
+  useEffect(() => {
+    const urlParams = new URLSearchParams(window.location.search);
+    const id = urlParams.get('id');
+    if (id) {
+      setColumnFilters([{ id: 'name', value: id }]);
+    }
+  }, []);
+
+  const [showOnlyLatest, setShowOnlyLatest] = useState(true);
+  const [onlyShowDrafts, setOnlyShowDrafts] = useState(false);
+
+  useEffect(() => {
+    const checkbox = document.getElementById(checkboxLatestId);
+    function handleChange(evt: Event) {
+      const checked = (evt.target as HTMLInputElement).checked;
+      setShowOnlyLatest(checked);
+    }
+
+    checkbox?.addEventListener('change', handleChange);
+
+    return () => checkbox?.removeEventListener('change', handleChange);
+  }, [checkboxLatestId]);
+
+  useEffect(() => {
+    const checkbox = document.getElementById(checkboxDraftsId);
+    function handleChange(evt: Event) {
+      const checked = (evt.target as HTMLInputElement).checked;
+      setOnlyShowDrafts(checked);
+    }
+
+    checkbox?.addEventListener('change', handleChange);
+
+    return () => checkbox?.removeEventListener('change', handleChange);
+  }, [checkboxDraftsId]);
+
+  // Filter data based on checkbox states
+  const filteredData = useMemo(() => {
+    return initialData.filter((row) => {
+      // Check if item is a draft
+      const isDraft = row.data.draft === true || (typeof row.data.draft === 'object' && row.data.draft !== null);
+
+      // If "Only show drafts" is enabled, show only drafts
+      if (onlyShowDrafts && !isDraft) {
+        return false;
+      }
+
+      // If "Only show drafts" is enabled, don't apply other filters
+      if (onlyShowDrafts) {
+        return true;
+      }
+
+      // Check latest version filter (only when not showing only drafts)
+      if (showOnlyLatest) {
+        return isSameVersion(row.data.version, row.data.latestVersion);
+      }
+
+      return true;
+    });
+  }, [initialData, showOnlyLatest, onlyShowDrafts]);
+
+  const columns = useMemo(
+    () => getColumnsByCollection(collection, tableConfiguration ?? ({ columns: {} } as TableConfiguration)),
+    [collection, tableConfiguration]
+  );
+
+  const table = useReactTable({
+    data: filteredData,
+    columns,
+    onColumnFiltersChange: setColumnFilters,
+    getCoreRowModel: getCoreRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getFacetedRowModel: getFacetedRowModel(), // client-side faceting
+    getFacetedUniqueValues: getFacetedUniqueValues(), // generate unique values for select filter/autocomplete
+    getFacetedMinMaxValues: getFacetedMinMaxValues(), // generate min/max values for range filter
+    getPaginationRowModel: getPaginationRowModel(),
+    state: {
+      columnFilters,
+      columnVisibility: Object.fromEntries(
+        Object.entries(tableConfiguration?.columns ?? {}).map(([key, value]) => [key, value.visible ?? true])
+      ),
+    },
+  });
+
+  const totalResults = table.getPrePaginationRowModel().rows.length;
+  const hasResults = table.getRowModel().rows.length > 0;
+
+  return (
+    <div>
+      <div className="overflow-hidden rounded-xl border border-[rgb(var(--ec-page-border)/0.72)] dark:border-white/10 bg-[rgb(var(--ec-dropdown-bg)/0.66)]">
+        <table className="min-w-full divide-y divide-[rgb(var(--ec-page-border)/0.62)] dark:divide-white/10">
+          <thead className="sticky top-0 z-10 bg-[rgb(var(--ec-content-hover)/0.45)]">
+            {table.getHeaderGroups().map((headerGroup, index) => (
+              <tr key={`${headerGroup}-${index}`}>
+                {headerGroup.headers.map((header) => (
+                  <th
+                    key={`${header.id}`}
+                    className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider"
+                  >
+                    <div className="flex flex-col gap-2">
+                      <div>{header.isPlaceholder ? null : flexRender(header.column.columnDef.header, header.getContext())}</div>
+                      <div>
+                        {header.column.columnDef.meta?.showFilter !== false && <Filter column={header.column} />}
+                        {header.column.columnDef.meta?.showFilter == false && <div className="h-9" />}
+                      </div>
+                    </div>
+                  </th>
+                ))}
+              </tr>
+            ))}
+          </thead>
+
+          <tbody className="divide-y divide-[rgb(var(--ec-page-border)/0.5)] dark:divide-white/8">
+            {hasResults ? (
+              table.getRowModel().rows.map((row, index) => (
+                <tr
+                  key={`${row.id}-${index}`}
+                  className="group bg-transparent transition-colors hover:bg-[rgb(var(--ec-content-hover)/0.38)]"
+                >
+                  {row.getVisibleCells().map((cell) => (
+                    <td
+                      key={cell.id}
+                      className={`px-4 py-3 text-sm text-[rgb(var(--ec-page-text))] ${cell.column.columnDef.meta?.className || ''}`}
+                    >
+                      {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                    </td>
+                  ))}
+                </tr>
+              ))
+            ) : (
+              <tr>
+                <td colSpan={table.getAllColumns().length} className="px-4 py-12 text-center">
+                  <div className="flex flex-col items-center justify-center text-[rgb(var(--ec-page-text-muted))]">
+                    <SearchX className="w-10 h-10 text-[rgb(var(--ec-icon-color))] mb-3 opacity-50" />
+                    <p className="text-sm font-medium text-[rgb(var(--ec-page-text-muted))]">No results found</p>
+                    <p className="text-xs text-[rgb(var(--ec-icon-color))] mt-1">Try adjusting your search or filters</p>
+                  </div>
+                </td>
+              </tr>
+            )}
+          </tbody>
+        </table>
+      </div>
+
+      {/* Pagination */}
+      <div className="flex items-center justify-between border-t border-[rgb(var(--ec-page-border))] px-1 py-3">
+        <div className="text-xs text-[rgb(var(--ec-page-text-muted))]">
+          {totalResults > 0 && (
+            <span>
+              Showing <span className="font-medium text-[rgb(var(--ec-page-text))]">{table.getRowModel().rows.length}</span> of{' '}
+              <span className="font-medium text-[rgb(var(--ec-page-text))]">{totalResults}</span> results
+            </span>
+          )}
+        </div>
+        <div className="flex items-center gap-2">
+          <div className="flex items-center rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg)/0.35)]">
+            <button
+              className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] disabled:opacity-40 disabled:cursor-not-allowed disabled:hover:bg-transparent transition-colors rounded-l-lg"
+              onClick={() => table.setPageIndex(0)}
+              disabled={!table.getCanPreviousPage()}
+              title="First page"
+            >
+              <ChevronsLeft className="w-4 h-4" />
+            </button>
+            <button
+              className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] disabled:opacity-40 disabled:cursor-not-allowed disabled:hover:bg-transparent transition-colors border-l border-[rgb(var(--ec-page-border))]"
+              onClick={() => table.previousPage()}
+              disabled={!table.getCanPreviousPage()}
+              title="Previous page"
+            >
+              <ChevronLeft className="w-4 h-4" />
+            </button>
+            <span className="min-w-[72px] px-3 py-1.5 text-center text-xs tabular-nums text-[rgb(var(--ec-page-text-muted))] border-l border-r border-[rgb(var(--ec-page-border))]">
+              <span className="font-medium text-[rgb(var(--ec-page-text))]">{table.getState().pagination.pageIndex + 1}</span>
+              {' / '}
+              <span>{table.getPageCount() || 1}</span>
+            </span>
+            <button
+              className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] disabled:opacity-40 disabled:cursor-not-allowed disabled:hover:bg-transparent transition-colors border-r border-[rgb(var(--ec-page-border))]"
+              onClick={() => table.nextPage()}
+              disabled={!table.getCanNextPage()}
+              title="Next page"
+            >
+              <ChevronRight className="w-4 h-4" />
+            </button>
+            <button
+              className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-content-hover))] disabled:opacity-40 disabled:cursor-not-allowed disabled:hover:bg-transparent transition-colors rounded-r-lg"
+              onClick={() => table.setPageIndex(table.getPageCount() - 1)}
+              disabled={!table.getCanNextPage()}
+              title="Last page"
+            >
+              <ChevronsRight className="w-4 h-4" />
+            </button>
+          </div>
+          <select
+            value={table.getState().pagination.pageSize}
+            onChange={(e) => {
+              table.setPageSize(Number(e.target.value));
+            }}
+            className="rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg)/0.35)] px-3 py-1.5 text-xs text-[rgb(var(--ec-page-text-muted))] hover:border-[rgb(var(--ec-icon-color))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent)/0.2)] transition-colors"
+          >
+            {[10, 20, 30, 40, 50].map((pageSize) => (
+              <option key={pageSize} value={pageSize}>
+                {pageSize} per page
+              </option>
+            ))}
+          </select>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+function Filter<T extends TCollectionTypes>({ column }: { column: Column<TData<T>, unknown> }) {
+  const { filterVariant, collectionFilterKey, filteredItemHasVersion = true } = column.columnDef.meta ?? {};
+
+  const columnFilterValue = column.getFilterValue();
+
+  const sortedUniqueValues = useMemo(() => {
+    if (filterVariant === 'collection' && collectionFilterKey) {
+      const rows = column.getFacetedRowModel().rows;
+      const data = rows.map((row) => row.original.data?.[collectionFilterKey] ?? []).flat();
+
+      const allItems = data.map((item) =>
+        filteredItemHasVersion ? `${item?.data.name} (v${item?.data.version})` : `${item?.data.name}`
+      );
+      const uniqueItemsInList = Array.from(new Set(allItems));
+
+      return uniqueItemsInList.sort().slice(0, 2000);
+    }
+    if (filterVariant === 'name') {
+      const rows = column.getFacetedRowModel().rows;
+      const data = rows
+        .map((row) => {
+          const data = row.original;
+          return data;
+        })
+        .flat();
+
+      const allItems = data.map((item) =>
+        filteredItemHasVersion ? `${item.data.name} (v${item.data.version})` : `${item.data.name}`
+      );
+      const uniqueItemsInList = Array.from(new Set(allItems));
+
+      return uniqueItemsInList.sort().slice(0, 2000);
+    }
+    if (filterVariant === 'badges') {
+      const allBadges = column.getFacetedUniqueValues().keys();
+      // join all badges into a single array
+      const allBadgesArray = Array.from(allBadges)
+        .flat()
+        .filter((b) => !!b);
+      const allBadgesString = allBadgesArray.map((badge) => badge.content);
+      const uniqueBadges = Array.from(new Set(allBadgesString));
+      return uniqueBadges.sort().slice(0, 2000);
+    }
+    return Array.from(column.getFacetedUniqueValues().keys()).sort().slice(0, 2000);
+  }, [column.getFacetedUniqueValues(), filterVariant]);
+
+  const uniqueCount = column.getFacetedUniqueValues().size;
+
+  return (
+    <div>
+      {/* Autocomplete suggestions from faceted values feature */}
+      <datalist id={column.id + 'list'}>
+        {sortedUniqueValues.map((value: any, index) => (
+          <option value={value} key={`${value}-${index}`} />
+        ))}
+      </datalist>
+      <DebouncedInput
+        type="text"
+        value={(columnFilterValue ?? '') as string}
+        onChange={(value) => column.setFilterValue(value)}
+        placeholder={!column?.columnDef?.meta?.filterVariant ? `Search (${uniqueCount})...` : 'Search...'}
+        className="w-full px-3 py-2 text-sm bg-[rgb(var(--ec-input-bg))] text-[rgb(var(--ec-input-text))] border border-[rgb(var(--ec-input-border))] rounded-lg placeholder:text-[rgb(var(--ec-input-placeholder))] focus:outline-hidden focus:ring-2 focus:ring-[rgb(var(--ec-accent)/0.2)] focus:border-[rgb(var(--ec-accent))] transition-colors"
+        list={column.id + 'list'}
+      />
+    </div>
+  );
+}
diff --git a/packages/core/eventcatalog/src/components/Tables/columns/ContainersTableColumns.tsx b/packages/core/eventcatalog/src/components/Tables/columns/ContainersTableColumns.tsx
new file mode 100644
index 000000000..ea6aa9892
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/columns/ContainersTableColumns.tsx
@@ -0,0 +1,194 @@
+import { createColumnHelper } from '@tanstack/react-table';
+import { useState } from 'react';
+import { filterByName } from '../filters/custom-filters';
+import { buildUrl } from '@utils/url-builder';
+import { ServerIcon } from '@heroicons/react/24/solid';
+import { DatabaseIcon } from 'lucide-react';
+import { createBadgesColumn } from './SharedColumns';
+import type { TData } from '../Table';
+import { filterCollectionByName } from '../filters/custom-filters';
+import type { TableConfiguration } from '@types';
+const columnHelper = createColumnHelper<TData<'containers'>>();
+
+export const columns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration.columns?.name?.label || 'Storage'}</span>,
+    cell: (info) => {
+      const containerRaw = info.row.original;
+      return (
+        <a
+          href={buildUrl(`/docs/${containerRaw.collection}/${containerRaw.data.id}/${containerRaw.data.version}`)}
+          className="group inline-flex items-center"
+        >
+          <span className="inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] hover:border-indigo-400 dark:hover:border-indigo-500 hover:bg-indigo-50 dark:hover:bg-indigo-500/10 transition-colors">
+            <span className="flex items-center justify-center w-6 h-6 bg-indigo-500 rounded-l-md">
+              <DatabaseIcon className="h-3 w-3 text-white" />
+            </span>
+            <span className="px-2 py-1 text-xs text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-page-text))]">
+              {containerRaw.data.name}
+              <span className="text-[rgb(var(--ec-icon-color))] ml-1">v{containerRaw.data.version}</span>
+            </span>
+          </span>
+        </a>
+      );
+    },
+    footer: (info) => info.column.id,
+    meta: {
+      filterVariant: 'name',
+    },
+    filterFn: filterByName,
+  }),
+  columnHelper.accessor('data.summary', {
+    id: 'summary',
+    header: () => <span>{tableConfiguration.columns?.summary?.label || 'Summary'}</span>,
+    cell: (info) => {
+      const summary = info.renderValue() as string;
+      return (
+        <span className="text-sm text-[rgb(var(--ec-icon-color))] line-clamp-2" title={summary || ''}>
+          {summary}
+        </span>
+      );
+    },
+    footer: (info) => info.column.id,
+    meta: {
+      showFilter: false,
+      className: 'max-w-md',
+    },
+  }),
+  columnHelper.accessor('data.servicesThatWriteToContainer', {
+    id: 'writes',
+    header: () => <span>{tableConfiguration.columns?.writes?.label || 'Writes'}</span>,
+    meta: {
+      filterVariant: 'collection',
+      collectionFilterKey: 'servicesThatWriteToContainer',
+    },
+    cell: (info) => {
+      const services = info.getValue();
+      const [isExpanded, setIsExpanded] = useState(false);
+
+      if (services?.length === 0 || !services)
+        return (
+          <span className="inline-flex items-center px-2 py-1 text-xs text-[rgb(var(--ec-icon-color))] bg-[rgb(var(--ec-content-hover))] rounded-md border border-[rgb(var(--ec-page-border))]">
+            No services
+          </span>
+        );
+
+      const visibleItems = isExpanded ? services : services.slice(0, 4);
+      const hiddenCount = services.length - 4;
+
+      return (
+        <div className="flex flex-col gap-1.5">
+          {visibleItems.map((service, index) => (
+            <a
+              key={`${service.data.id}-${index}`}
+              href={buildUrl(`/docs/${service.collection}/${service.data.id}/${service.data.version}`)}
+              className="group inline-flex items-center"
+            >
+              <span className="inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] hover:border-pink-400 dark:hover:border-pink-500 hover:bg-pink-50 dark:hover:bg-pink-500/10 transition-colors">
+                <span className="flex items-center justify-center w-6 h-6 bg-pink-500 rounded-l-md">
+                  <ServerIcon className="h-3 w-3 text-white" />
+                </span>
+                <span className="px-2 py-1 text-xs text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-page-text))]">
+                  {service.data.name}
+                  <span className="text-[rgb(var(--ec-icon-color))] ml-1">v{service.data.version}</span>
+                </span>
+              </span>
+            </a>
+          ))}
+          {hiddenCount > 0 && (
+            <button
+              onClick={() => setIsExpanded(!isExpanded)}
+              className="text-xs text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] text-left"
+            >
+              {isExpanded ? 'Show less' : `+${hiddenCount} more`}
+            </button>
+          )}
+        </div>
+      );
+    },
+    footer: (info) => info.column.id,
+    filterFn: filterCollectionByName('servicesThatWriteToContainer'),
+  }),
+  columnHelper.accessor('data.servicesThatReadFromContainer', {
+    id: 'reads',
+    header: () => <span>{tableConfiguration.columns?.reads?.label || 'Reads'}</span>,
+    meta: {
+      filterVariant: 'collection',
+      collectionFilterKey: 'servicesThatReadFromContainer',
+    },
+    cell: (info) => {
+      const services = info.getValue();
+      const [isExpanded, setIsExpanded] = useState(false);
+
+      if (services?.length === 0 || !services)
+        return (
+          <span className="inline-flex items-center px-2 py-1 text-xs text-[rgb(var(--ec-icon-color))] bg-[rgb(var(--ec-content-hover))] rounded-md border border-[rgb(var(--ec-page-border))]">
+            No services
+          </span>
+        );
+
+      const visibleItems = isExpanded ? services : services.slice(0, 4);
+      const hiddenCount = services.length - 4;
+
+      return (
+        <div className="flex flex-col gap-1.5">
+          {visibleItems.map((service, index) => (
+            <a
+              key={`${service.data.id}-${index}`}
+              href={buildUrl(`/docs/${service.collection}/${service.data.id}/${service.data.version}`)}
+              className="group inline-flex items-center"
+            >
+              <span className="inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] hover:border-pink-400 dark:hover:border-pink-500 hover:bg-pink-50 dark:hover:bg-pink-500/10 transition-colors">
+                <span className="flex items-center justify-center w-6 h-6 bg-pink-500 rounded-l-md">
+                  <ServerIcon className="h-3 w-3 text-white" />
+                </span>
+                <span className="px-2 py-1 text-xs text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-page-text))]">
+                  {service.data.name}
+                  <span className="text-[rgb(var(--ec-icon-color))] ml-1">v{service.data.version}</span>
+                </span>
+              </span>
+            </a>
+          ))}
+          {hiddenCount > 0 && (
+            <button
+              onClick={() => setIsExpanded(!isExpanded)}
+              className="text-xs text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] text-left"
+            >
+              {isExpanded ? 'Show less' : `+${hiddenCount} more`}
+            </button>
+          )}
+        </div>
+      );
+    },
+    footer: (info) => info.column.id,
+    filterFn: filterCollectionByName('servicesThatReadFromContainer'),
+  }),
+  createBadgesColumn(columnHelper, tableConfiguration),
+  columnHelper.accessor('data.name', {
+    header: () => <span>{tableConfiguration.columns?.actions?.label || 'Actions'}</span>,
+    cell: (info) => {
+      const item = info.row.original;
+      return (
+        <div className="flex items-center gap-2">
+          <a
+            className="inline-flex items-center px-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] transition-colors whitespace-nowrap"
+            href={buildUrl(`/docs/${item.collection}/${item.data.id}/${item.data.version}`)}
+          >
+            Docs
+          </a>
+          <a
+            className="inline-flex items-center px-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] transition-colors whitespace-nowrap"
+            href={buildUrl(`/visualiser/${item.collection}/${item.data.id}/${item.data.version}`)}
+          >
+            Visualiser
+          </a>
+        </div>
+      );
+    },
+    id: 'actions',
+    meta: {
+      showFilter: false,
+    },
+  }),
+];
diff --git a/packages/core/eventcatalog/src/components/Tables/columns/DirectorySourceColumn.tsx b/packages/core/eventcatalog/src/components/Tables/columns/DirectorySourceColumn.tsx
new file mode 100644
index 000000000..e87b48d59
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/columns/DirectorySourceColumn.tsx
@@ -0,0 +1,84 @@
+import { FileText, Github } from 'lucide-react';
+import { buildUrl } from '@utils/url-builder';
+import type { ReactNode } from 'react';
+
+type DirectorySource = {
+  provider: string;
+  id?: string;
+  url?: string;
+};
+
+const sourceLabels: Record<string, string> = {
+  github: 'GitHub',
+  'microsoft-entra': 'Microsoft Entra ID',
+};
+
+const getSourceLabel = (source: DirectorySource) => sourceLabels[source.provider] ?? source.provider;
+
+const SourceBadge = ({ source, icon }: { source: DirectorySource; icon: ReactNode }) => {
+  const label = getSourceLabel(source);
+  const title = `Synced from ${label}`;
+
+  if (source.url) {
+    return (
+      <a
+        href={source.url}
+        target="_blank"
+        rel="noreferrer"
+        className="group/source inline-flex h-7 w-7 items-center justify-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg)/0.35)] transition-colors hover:bg-[rgb(var(--ec-content-hover))]"
+        title={title}
+        aria-label={title}
+      >
+        {icon}
+      </a>
+    );
+  }
+
+  return (
+    <span
+      className="inline-flex h-7 w-7 items-center justify-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg)/0.35)]"
+      title={title}
+      aria-label={title}
+    >
+      {icon}
+    </span>
+  );
+};
+
+export const DirectorySourceCell = ({ source }: { source?: DirectorySource }) => {
+  if (source?.provider === 'github') {
+    return (
+      <SourceBadge
+        source={source}
+        icon={
+          <Github className="h-4 w-4 text-[rgb(var(--ec-icon-color))] transition-colors group-hover/source:text-[rgb(var(--ec-page-text))]" />
+        }
+      />
+    );
+  }
+
+  if (source?.provider === 'microsoft-entra') {
+    return <SourceBadge source={source} icon={<img src={buildUrl('/icons/azure.svg', true)} alt="" className="h-4 w-4" />} />;
+  }
+
+  if (source) {
+    return (
+      <SourceBadge
+        source={source}
+        icon={
+          <FileText className="h-4 w-4 text-[rgb(var(--ec-icon-color))] transition-colors group-hover/source:text-[rgb(var(--ec-page-text))]" />
+        }
+      />
+    );
+  }
+
+  return (
+    <span
+      className="inline-flex h-7 w-7 items-center justify-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg)/0.35)] text-[rgb(var(--ec-icon-color))]"
+      title="Synced to local file"
+      aria-label="Synced to local file"
+    >
+      <FileText className="h-4 w-4" />
+    </span>
+  );
+};
diff --git a/packages/core/eventcatalog/src/components/Tables/columns/DomainTableColumns.tsx b/packages/core/eventcatalog/src/components/Tables/columns/DomainTableColumns.tsx
new file mode 100644
index 000000000..ba2916dab
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/columns/DomainTableColumns.tsx
@@ -0,0 +1,140 @@
+import { ServerIcon, RectangleGroupIcon } from '@heroicons/react/20/solid';
+import { createColumnHelper } from '@tanstack/react-table';
+import { useState } from 'react';
+import { filterByName, filterCollectionByName } from '../filters/custom-filters';
+import { buildUrl } from '@utils/url-builder';
+import { createBadgesColumn } from './SharedColumns';
+import type { TData } from '../Table';
+import type { TableConfiguration } from '@types';
+
+const columnHelper = createColumnHelper<TData<'domains'>>();
+
+export const columns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration.columns?.name?.label || 'Domain'}</span>,
+    cell: (info) => {
+      const messageRaw = info.row.original;
+      return (
+        <a
+          href={buildUrl(`/docs/${messageRaw.collection}/${messageRaw.data.id}/${messageRaw.data.version}`)}
+          className="group inline-flex items-center"
+        >
+          <span className="inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] hover:border-yellow-400 dark:hover:border-yellow-500 hover:bg-yellow-50 dark:hover:bg-yellow-500/10 transition-colors">
+            <span className="flex items-center justify-center w-6 h-6 bg-yellow-500 rounded-l-md">
+              <RectangleGroupIcon className="h-3 w-3 text-white" />
+            </span>
+            <span className="px-2 py-1 text-xs text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-page-text))]">
+              {messageRaw.data.name}
+              <span className="text-[rgb(var(--ec-icon-color))] ml-1">v{messageRaw.data.version}</span>
+            </span>
+          </span>
+        </a>
+      );
+    },
+    footer: (info) => info.column.id,
+    meta: {
+      filterVariant: 'name',
+    },
+    filterFn: filterByName,
+  }),
+  columnHelper.accessor('data.summary', {
+    id: 'summary',
+    header: () => <span>{tableConfiguration.columns?.summary?.label || 'Summary'}</span>,
+    cell: (info) => {
+      const summary = info.renderValue() as string;
+      const isDraft = info.row.original.data.draft;
+      const displayText = `${summary || ''}${isDraft ? ' (Draft)' : ''}`;
+      return (
+        <span className="text-sm text-[rgb(var(--ec-icon-color))] line-clamp-2" title={displayText}>
+          {displayText}
+        </span>
+      );
+    },
+    footer: (info) => info.column.id,
+    meta: {
+      showFilter: false,
+      className: 'max-w-md',
+    },
+  }),
+  columnHelper.accessor('data.services', {
+    id: 'services',
+    header: () => <span>Services</span>,
+    meta: {
+      filterVariant: 'collection',
+      collectionFilterKey: 'services',
+    },
+    cell: (info) => {
+      const services = info.getValue();
+      const [isExpanded, setIsExpanded] = useState(false);
+
+      if (services?.length === 0 || !services)
+        return (
+          <span className="inline-flex items-center px-2 py-1 text-xs text-[rgb(var(--ec-icon-color))] bg-[rgb(var(--ec-content-hover))] rounded-md border border-[rgb(var(--ec-page-border))]">
+            No services
+          </span>
+        );
+
+      const visibleItems = isExpanded ? services : services.slice(0, 4);
+      const hiddenCount = services.length - 4;
+
+      return (
+        <div className="flex flex-col gap-1.5">
+          {visibleItems.map((service, index) => (
+            <a
+              key={`${service.data.id}-${index}`}
+              href={buildUrl(`/docs/${service.collection}/${service.data.id}/${service.data.version}`)}
+              className="group inline-flex items-center"
+            >
+              <span className="inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] hover:border-pink-400 dark:hover:border-pink-500 hover:bg-pink-50 dark:hover:bg-pink-500/10 transition-colors">
+                <span className="flex items-center justify-center w-6 h-6 bg-pink-500 rounded-l-md">
+                  <ServerIcon className="h-3 w-3 text-white" />
+                </span>
+                <span className="px-2 py-1 text-xs text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-page-text))]">
+                  {service.data.name}
+                  <span className="text-[rgb(var(--ec-icon-color))] ml-1">v{service.data.version}</span>
+                </span>
+              </span>
+            </a>
+          ))}
+          {hiddenCount > 0 && (
+            <button
+              onClick={() => setIsExpanded(!isExpanded)}
+              className="text-xs text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] text-left"
+            >
+              {isExpanded ? 'Show less' : `+${hiddenCount} more`}
+            </button>
+          )}
+        </div>
+      );
+    },
+    filterFn: filterCollectionByName('services'),
+  }),
+  createBadgesColumn(columnHelper, tableConfiguration),
+  columnHelper.accessor('data.name', {
+    id: 'actions',
+    header: () => <span>{tableConfiguration.columns?.actions?.label || 'Actions'}</span>,
+    cell: (info) => {
+      const item = info.row.original;
+      return (
+        <div className="flex items-center gap-2">
+          <a
+            className="inline-flex items-center px-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] transition-colors whitespace-nowrap"
+            href={buildUrl(`/docs/${item.collection}/${item.data.id}/${item.data.version}`)}
+          >
+            Docs
+          </a>
+          <a
+            className="inline-flex items-center px-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] transition-colors whitespace-nowrap"
+            href={buildUrl(`/visualiser/${item.collection}/${item.data.id}/${item.data.version}`)}
+          >
+            Visualiser
+          </a>
+        </div>
+      );
+    },
+    meta: {
+      showFilter: false,
+    },
+  }),
+];
diff --git a/packages/core/eventcatalog/src/components/Tables/columns/FlowTableColumns.tsx b/packages/core/eventcatalog/src/components/Tables/columns/FlowTableColumns.tsx
new file mode 100644
index 000000000..ccb644d4a
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/columns/FlowTableColumns.tsx
@@ -0,0 +1,84 @@
+import { createColumnHelper } from '@tanstack/react-table';
+import { filterByName } from '../filters/custom-filters';
+import { buildUrl } from '@utils/url-builder';
+import { QueueListIcon } from '@heroicons/react/24/solid';
+import { createBadgesColumn } from './SharedColumns';
+import type { TData } from '../Table';
+import type { TableConfiguration } from '@types';
+
+const columnHelper = createColumnHelper<TData<'flows'>>();
+
+export const columns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration.columns?.name?.label || 'Flow'}</span>,
+    cell: (info) => {
+      const flowRaw = info.row.original;
+      return (
+        <a
+          href={buildUrl(`/docs/${flowRaw.collection}/${flowRaw.data.id}/${flowRaw.data.version}`)}
+          className="group inline-flex items-center"
+        >
+          <span className="inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] hover:border-teal-400 dark:hover:border-teal-500 hover:bg-teal-50 dark:hover:bg-teal-500/10 transition-colors">
+            <span className="flex items-center justify-center w-6 h-6 bg-teal-500 rounded-l-md">
+              <QueueListIcon className="h-3 w-3 text-white" />
+            </span>
+            <span className="px-2 py-1 text-xs text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-page-text))]">
+              {flowRaw.data.name}
+              <span className="text-[rgb(var(--ec-icon-color))] ml-1">v{flowRaw.data.version}</span>
+            </span>
+          </span>
+        </a>
+      );
+    },
+    footer: (info) => info.column.id,
+    meta: {
+      filterVariant: 'name',
+    },
+    filterFn: filterByName,
+  }),
+  columnHelper.accessor('data.summary', {
+    id: 'summary',
+    header: () => <span>{tableConfiguration.columns?.summary?.label || 'Summary'}</span>,
+    cell: (info) => {
+      const summary = info.renderValue() as string;
+      return (
+        <span className="text-sm text-[rgb(var(--ec-icon-color))] line-clamp-2" title={summary || ''}>
+          {summary}
+        </span>
+      );
+    },
+    footer: (info) => info.column.id,
+    meta: {
+      showFilter: false,
+      className: 'max-w-md',
+    },
+  }),
+  createBadgesColumn(columnHelper, tableConfiguration),
+  columnHelper.accessor('data.name', {
+    id: 'actions',
+    header: () => <span>{tableConfiguration.columns?.actions?.label || 'Actions'}</span>,
+    cell: (info) => {
+      const item = info.row.original;
+      return (
+        <div className="flex items-center gap-2">
+          <a
+            className="inline-flex items-center px-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] transition-colors whitespace-nowrap"
+            href={buildUrl(`/docs/${item.collection}/${item.data.id}/${item.data.version}`)}
+          >
+            Docs
+          </a>
+          <a
+            className="inline-flex items-center px-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] transition-colors whitespace-nowrap"
+            href={buildUrl(`/visualiser/${item.collection}/${item.data.id}/${item.data.version}`)}
+          >
+            Visualiser
+          </a>
+        </div>
+      );
+    },
+    meta: {
+      showFilter: false,
+    },
+  }),
+];
diff --git a/packages/core/eventcatalog/src/components/Tables/columns/MessageTableColumns.tsx b/packages/core/eventcatalog/src/components/Tables/columns/MessageTableColumns.tsx
new file mode 100644
index 000000000..3bd8f13b5
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/columns/MessageTableColumns.tsx
@@ -0,0 +1,214 @@
+import { ServerIcon, BoltIcon, ChatBubbleLeftIcon, MagnifyingGlassIcon } from '@heroicons/react/24/solid';
+import { createColumnHelper } from '@tanstack/react-table';
+import { useMemo, useState } from 'react';
+import { filterByName, filterCollectionByName } from '../filters/custom-filters';
+import { buildUrl } from '@utils/url-builder';
+import { createBadgesColumn } from './SharedColumns';
+import type { TData } from '../Table';
+import type { CollectionMessageTypes, TableConfiguration } from '@types';
+
+const columnHelper = createColumnHelper<TData<CollectionMessageTypes>>();
+
+export const getColorAndIconForMessageType = (type: string) => {
+  switch (type) {
+    case 'event':
+      return { color: 'orange', Icon: BoltIcon };
+    case 'command':
+      return { color: 'blue', Icon: ChatBubbleLeftIcon };
+    case 'querie':
+    case 'query':
+      return { color: 'green', Icon: MagnifyingGlassIcon };
+    default:
+      return { color: 'gray', Icon: ChatBubbleLeftIcon };
+  }
+};
+
+export const columns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration.columns?.name?.label || 'Name'}</span>,
+    cell: (info) => {
+      const messageRaw = info.row.original;
+      const type = useMemo(() => messageRaw.collection.slice(0, -1), [messageRaw.collection]);
+      const { color, Icon } = getColorAndIconForMessageType(type);
+      return (
+        <a
+          href={buildUrl(`/docs/${messageRaw.collection}/${messageRaw.data.id}/${messageRaw.data.version}`)}
+          className="group inline-flex items-center"
+        >
+          <span
+            className={`inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] hover:border-${color}-400 dark:hover:border-${color}-500 hover:bg-${color}-50 dark:hover:bg-${color}-500/10 transition-colors`}
+          >
+            <span className={`flex items-center justify-center w-6 h-6 bg-${color}-500 rounded-l-md`}>
+              <Icon className="h-3 w-3 text-white" />
+            </span>
+            <span className="px-2 py-1 text-xs text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-page-text))]">
+              {messageRaw.data.name}
+              <span className="text-[rgb(var(--ec-icon-color))] ml-1">v{messageRaw.data.version}</span>
+            </span>
+          </span>
+        </a>
+      );
+    },
+    meta: {
+      filterVariant: 'name',
+    },
+    filterFn: filterByName,
+  }),
+
+  columnHelper.accessor('data.summary', {
+    id: 'summary',
+    header: () => <span>{tableConfiguration.columns?.summary?.label || 'Summary'}</span>,
+    cell: (info) => {
+      const summary = info.renderValue() as string;
+      const isDraft = info.row.original.data.draft;
+      const displayText = `${summary || ''}${isDraft ? ' (Draft)' : ''}`;
+      return (
+        <span className="text-sm text-[rgb(var(--ec-icon-color))] line-clamp-2" title={displayText}>
+          {displayText}
+        </span>
+      );
+    },
+    footer: (info) => info.column.id,
+    meta: {
+      showFilter: false,
+      className: 'max-w-[200px]',
+    },
+  }),
+
+  columnHelper.accessor('data.producers', {
+    id: 'producers',
+    header: () => <span>{tableConfiguration.columns?.producers?.label || 'Producers'}</span>,
+    meta: {
+      filterVariant: 'collection',
+      collectionFilterKey: 'producers',
+    },
+    cell: (info) => {
+      const producers = info.getValue();
+      const [isExpanded, setIsExpanded] = useState(false);
+
+      if (producers?.length === 0 || !producers)
+        return (
+          <span className="inline-flex items-center px-2 py-1 text-xs text-[rgb(var(--ec-icon-color))] bg-[rgb(var(--ec-content-hover))] rounded-md border border-[rgb(var(--ec-page-border))]">
+            No producers
+          </span>
+        );
+
+      const visibleItems = isExpanded ? producers : producers.slice(0, 4);
+      const hiddenCount = producers.length - 4;
+
+      return (
+        <div className="flex flex-col gap-1.5">
+          {visibleItems.map((producer, index) => (
+            <a
+              key={`${producer.data.id}-${index}`}
+              href={buildUrl(`/docs/${producer.collection}/${producer.data.id}/${producer.data.version}`)}
+              className="group inline-flex items-center"
+            >
+              <span className="inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] hover:border-pink-400 dark:hover:border-pink-500 hover:bg-pink-50 dark:hover:bg-pink-500/10 transition-colors">
+                <span className="flex items-center justify-center w-6 h-6 bg-pink-500 rounded-l-md">
+                  <ServerIcon className="h-3 w-3 text-white" />
+                </span>
+                <span className="px-2 py-1 text-xs text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-page-text))]">
+                  {producer.data.name}
+                  <span className="text-[rgb(var(--ec-icon-color))] ml-1">v{producer.data.version}</span>
+                </span>
+              </span>
+            </a>
+          ))}
+          {hiddenCount > 0 && (
+            <button
+              onClick={() => setIsExpanded(!isExpanded)}
+              className="text-xs text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] text-left"
+            >
+              {isExpanded ? 'Show less' : `+${hiddenCount} more`}
+            </button>
+          )}
+        </div>
+      );
+    },
+    footer: (info) => info.column.id,
+    filterFn: filterCollectionByName('producers'),
+  }),
+  columnHelper.accessor('data.consumers', {
+    id: 'consumers',
+    header: () => <span>{tableConfiguration.columns?.consumers?.label || 'Consumers'}</span>,
+    meta: {
+      filterVariant: 'collection',
+      collectionFilterKey: 'consumers',
+    },
+    cell: (info) => {
+      const consumers = info.getValue();
+      const [isExpanded, setIsExpanded] = useState(false);
+
+      if (consumers?.length === 0 || !consumers)
+        return (
+          <span className="inline-flex items-center px-2 py-1 text-xs text-[rgb(var(--ec-icon-color))] bg-[rgb(var(--ec-content-hover))] rounded-md border border-[rgb(var(--ec-page-border))]">
+            No consumers
+          </span>
+        );
+
+      const visibleItems = isExpanded ? consumers : consumers.slice(0, 4);
+      const hiddenCount = consumers.length - 4;
+
+      return (
+        <div className="flex flex-col gap-1.5">
+          {visibleItems.map((consumer, index) => (
+            <a
+              key={`${consumer.data.id}-${index}`}
+              href={buildUrl(`/docs/${consumer.collection}/${consumer.data.id}/${consumer.data.version}`)}
+              className="group inline-flex items-center"
+            >
+              <span className="inline-flex items-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] hover:border-pink-400 dark:hover:border-pink-500 hover:bg-pink-50 dark:hover:bg-pink-500/10 transition-colors">
+                <span className="flex items-center justify-center w-6 h-6 bg-pink-500 rounded-l-md">
+                  <ServerIcon className="h-3 w-3 text-white" />
+                </span>
+                <span className="px-2 py-1 text-xs text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-page-text))]">
+                  {consumer.data.name}
+                  <span className="text-[rgb(var(--ec-icon-color))] ml-1">v{consumer.data.version}</span>
+                </span>
+              </span>
+            </a>
+          ))}
+          {hiddenCount > 0 && (
+            <button
+              onClick={() => setIsExpanded(!isExpanded)}
+              className="text-xs text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-page-text))] text-left"
+            >
+              {isExpanded ? 'Show less' : `+${hiddenCount} more`}
+            </button>
+          )}
+        </div>
+      );
+    },
+    footer: (info) => info.column.id,
+    filterFn: filterCollectionByName('consumers'),
+  }),
+  createBadgesColumn(columnHelper, tableConfiguration),
+  columnHelper.accessor('data.name', {
+    id: 'actions',
+    header: () => <span>{tableConfiguration.columns?.actions?.label || 'Actions'}</span>,
+    cell: (info) => {
+      const item = info.row.original;
+      return (
+        <div className="flex items-center gap-2">
+          <a
+            className="inline-flex items-center px-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] transition-colors whitespace-nowrap"
+            href={buildUrl(`/docs/${item.collection}/${item.data.id}/${item.data.version}`)}
+          >
+            Docs
+          </a>
+          <a
+            className="inline-flex items-center px-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] bg-[rgb(var(--ec-content-hover))] border border-[rgb(var(--ec-page-border))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] transition-colors whitespace-nowrap"
+            href={buildUrl(`/visualiser/${item.collection}/${item.data.id}/${item.data.version}`)}
+          >
+            Visualiser
+          </a>
+        </div>
+      );
+    },
+    meta: {
+      showFilter: false,
+    },
+  }),
+];
diff --git a/packages/core/eventcatalog/src/components/Tables/columns/ServiceTableColumns.tsx b/packages/core/eventcatalog/src/components/Tables/columns/ServiceTableColumns.tsx
new file mode 100644
index 000000000..b5316dd60
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/columns/ServiceTableColumns.tsx
@@ -0,0 +1,209 @@
+import { ServerIcon, DocumentTextIcon, MapIcon } from '@heroicons/react/24/solid';
+import { ArrowDownIcon, ArrowUpIcon } from '@heroicons/react/24/outline';
+import { createColumnHelper } from '@tanstack/react-table';
+import { useMemo, useState } from 'react';
+import { filterByName, filterCollectionByName } from '../filters/custom-filters';
+import { buildUrl } from '@utils/url-builder';
+import { getColorAndIconForCollection } from '@utils/collections/icons';
+import { getCollectionTextColorClass } from '@utils/collection-colors';
+import { createBadgesColumn } from './SharedColumns';
+import FavoriteButton from '@components/FavoriteButton';
+import type { TData } from '../Table';
+import type { TableConfiguration } from '@types';
+const columnHelper = createColumnHelper<TData<'services'>>();
+
+export const columns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration.columns?.name?.label || 'Service'}</span>,
+    cell: (info) => {
+      const service = info.row.original;
+      const isLatestVersion = service.data.version === service.data.latestVersion;
+      return (
+        <a
+          href={buildUrl(`/docs/${service.collection}/${service.data.id}/${service.data.version}`)}
+          className="group inline-flex items-center gap-2 hover:text-[rgb(var(--ec-accent))] transition-colors"
+        >
+          <ServerIcon className="h-4 w-4 text-pink-500 flex-shrink-0" />
+          <span className="text-sm font-medium text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-accent))]">
+            {service.data.name}
+          </span>
+          {!isLatestVersion && <span className="text-xs text-[rgb(var(--ec-icon-color))]">v{service.data.version}</span>}
+        </a>
+      );
+    },
+    meta: {
+      filterVariant: 'name',
+    },
+    filterFn: filterByName,
+  }),
+  columnHelper.accessor('data.summary', {
+    id: 'summary',
+    header: () => <span>{tableConfiguration.columns?.summary?.label || 'Summary'}</span>,
+    cell: (info) => {
+      const summary = info.renderValue() as string;
+      const isDraft = info.row.original.data.draft;
+      const displayText = `${summary || ''}${isDraft ? ' (Draft)' : ''}`;
+      return (
+        <span className="text-sm text-[rgb(var(--ec-icon-color))] line-clamp-2" title={displayText}>
+          {displayText}
+        </span>
+      );
+    },
+    footer: (info) => info.column.id,
+    meta: {
+      showFilter: false,
+      className: 'max-w-md',
+    },
+  }),
+  columnHelper.accessor('data.receives', {
+    id: 'receives',
+    header: () => (
+      <span className="flex items-center gap-1">
+        <ArrowDownIcon className="w-3.5 h-3.5" />
+        Receives
+      </span>
+    ),
+    meta: {
+      filterVariant: 'collection',
+      collectionFilterKey: 'receives',
+    },
+    cell: (info) => {
+      const receives = info.getValue() || [];
+      const [isExpanded, setIsExpanded] = useState(false);
+
+      const receiversWithIcons = useMemo(
+        () =>
+          receives?.map((consumer) => {
+            return {
+              ...consumer,
+              ...getColorAndIconForCollection(consumer.collection),
+            };
+          }) || [],
+        [receives]
+      );
+
+      if (receives?.length === 0 || !receives) return <span className="text-xs text-[rgb(var(--ec-icon-color))]">-</span>;
+
+      const visibleItems = isExpanded ? receiversWithIcons : receiversWithIcons.slice(0, 3);
+      const hiddenCount = receiversWithIcons.length - 3;
+
+      return (
+        <div className="flex flex-col gap-1">
+          {visibleItems.map((consumer, index: number) => (
+            <a
+              key={`${consumer.data.id}-${index}`}
+              href={buildUrl(`/docs/${consumer.collection}/${consumer.data.id}/${consumer.data.version}`)}
+              className="group inline-flex items-center gap-1.5 text-xs hover:text-[rgb(var(--ec-accent))] transition-colors"
+            >
+              <consumer.Icon className={`h-3.5 w-3.5 ${getCollectionTextColorClass(consumer.color)} flex-shrink-0`} />
+              <span className="truncate max-w-[120px]" title={consumer.data.name}>
+                {consumer.data.name}
+              </span>
+            </a>
+          ))}
+          {hiddenCount > 0 && (
+            <button
+              onClick={() => setIsExpanded(!isExpanded)}
+              className="text-xs text-[rgb(var(--ec-accent))] hover:underline text-left"
+            >
+              {isExpanded ? 'Show less' : `+${hiddenCount} more`}
+            </button>
+          )}
+        </div>
+      );
+    },
+    filterFn: filterCollectionByName('receives'),
+  }),
+  columnHelper.accessor('data.sends', {
+    id: 'sends',
+    header: () => (
+      <span className="flex items-center gap-1">
+        <ArrowUpIcon className="w-3.5 h-3.5" />
+        Sends
+      </span>
+    ),
+    meta: {
+      filterVariant: 'collection',
+      collectionFilterKey: 'sends',
+    },
+    cell: (info) => {
+      const sends = info.getValue() || [];
+      const [isExpanded, setIsExpanded] = useState(false);
+
+      const sendersWithIcons = useMemo(
+        () =>
+          sends?.map((sender) => {
+            return {
+              ...sender,
+              ...getColorAndIconForCollection(sender.collection),
+            };
+          }) || [],
+        [sends]
+      );
+
+      if (sends?.length === 0 || !sends) return <span className="text-xs text-[rgb(var(--ec-icon-color))]">-</span>;
+
+      const visibleItems = isExpanded ? sendersWithIcons : sendersWithIcons.slice(0, 3);
+      const hiddenCount = sendersWithIcons.length - 3;
+
+      return (
+        <div className="flex flex-col gap-1">
+          {visibleItems.map((sender, index) => (
+            <a
+              key={`${sender.data.id}-${index}`}
+              href={buildUrl(`/docs/${sender.collection}/${sender.data.id}/${sender.data.version}`)}
+              className="group inline-flex items-center gap-1.5 text-xs hover:text-[rgb(var(--ec-accent))] transition-colors"
+            >
+              <sender.Icon className={`h-3.5 w-3.5 ${getCollectionTextColorClass(sender.color)} flex-shrink-0`} />
+              <span className="truncate max-w-[120px]" title={sender.data.name}>
+                {sender.data.name}
+              </span>
+            </a>
+          ))}
+          {hiddenCount > 0 && (
+            <button
+              onClick={() => setIsExpanded(!isExpanded)}
+              className="text-xs text-[rgb(var(--ec-accent))] hover:underline text-left"
+            >
+              {isExpanded ? 'Show less' : `+${hiddenCount} more`}
+            </button>
+          )}
+        </div>
+      );
+    },
+    filterFn: filterCollectionByName('sends'),
+  }),
+  createBadgesColumn(columnHelper, tableConfiguration),
+  columnHelper.accessor('data.name', {
+    id: 'actions',
+    header: () => <span></span>,
+    cell: (info) => {
+      const item = info.row.original;
+      const href = buildUrl(`/docs/${item.collection}/${item.data.id}/${item.data.version}`);
+      const nodeKey = `${item.collection}-${item.data.id}-${item.data.version}`;
+      return (
+        <div className="flex items-center gap-0.5">
+          <a
+            className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-accent))] hover:bg-[rgb(var(--ec-accent)/0.1)] rounded-md transition-colors"
+            href={href}
+            title="View documentation"
+          >
+            <DocumentTextIcon className="w-4 h-4" />
+          </a>
+          <a
+            className="p-1.5 text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-accent))] hover:bg-[rgb(var(--ec-accent)/0.1)] rounded-md transition-colors"
+            href={buildUrl(`/visualiser/${item.collection}/${item.data.id}/${item.data.version}`)}
+            title="View in visualiser"
+          >
+            <MapIcon className="w-4 h-4" />
+          </a>
+          <FavoriteButton nodeKey={nodeKey} title={item.data.name} badge="Service" href={href} size="sm" />
+        </div>
+      );
+    },
+    meta: {
+      showFilter: false,
+    },
+  }),
+];
diff --git a/packages/core/eventcatalog/src/components/Tables/columns/SharedColumns.tsx b/packages/core/eventcatalog/src/components/Tables/columns/SharedColumns.tsx
new file mode 100644
index 000000000..f391a3c25
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/columns/SharedColumns.tsx
@@ -0,0 +1,63 @@
+import { createColumnHelper } from '@tanstack/react-table';
+import { useState } from 'react';
+import { ArrowTopRightOnSquareIcon } from '@heroicons/react/20/solid';
+import { getBadgeHref, getBadgeReactStyle } from '@utils/badge-styles';
+import { filterByBadge } from '../filters/custom-filters';
+import type { TCollectionTypes, TData } from '../Table';
+import type { TableConfiguration } from '@types';
+
+export const createBadgesColumn = <T extends { data: Pick<TData<U>['data'], 'badges'> }, U extends TCollectionTypes>(
+  columnHelper: ReturnType<typeof createColumnHelper<T>>,
+  tableConfiguration: TableConfiguration
+) => {
+  return columnHelper.accessor((row) => row.data.badges, {
+    id: 'badges',
+    header: () => <span>{tableConfiguration.columns?.badges?.label || 'Badges'}</span>,
+    cell: (info) => {
+      const item = info.row.original;
+      const badges = item.data.badges || [];
+      const [isExpanded, setIsExpanded] = useState(false);
+
+      if (badges?.length === 0 || !badges) return <span className="text-xs text-[rgb(var(--ec-icon-color))]">-</span>;
+
+      const visibleItems = isExpanded ? badges : badges.slice(0, 3);
+      const hiddenCount = badges.length - 3;
+
+      return (
+        <div className="flex flex-wrap gap-1 items-center">
+          {visibleItems.map((badge, index) => {
+            const href = getBadgeHref(badge);
+            const className =
+              'inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-md border border-[rgb(var(--ec-accent)/0.5)] text-[rgb(var(--ec-page-text))] bg-transparent';
+
+            return href ? (
+              <a
+                key={`${badge.id}-${index}`}
+                href={href}
+                className={className}
+                style={getBadgeReactStyle(badge)}
+                title={badge.content}
+              >
+                <span>{badge.content}</span>
+                <ArrowTopRightOnSquareIcon className="ml-1 h-3 w-3 shrink-0 opacity-70" aria-hidden="true" />
+              </a>
+            ) : (
+              <span key={`${badge.id}-${index}`} className={className} style={getBadgeReactStyle(badge)} title={badge.content}>
+                {badge.content}
+              </span>
+            );
+          })}
+          {hiddenCount > 0 && (
+            <button onClick={() => setIsExpanded(!isExpanded)} className="text-xs text-[rgb(var(--ec-accent))] hover:underline">
+              {isExpanded ? 'less' : `+${hiddenCount}`}
+            </button>
+          )}
+        </div>
+      );
+    },
+    meta: {
+      filterVariant: 'badges',
+    },
+    filterFn: filterByBadge,
+  });
+};
diff --git a/packages/core/eventcatalog/src/components/Tables/columns/TeamsTableColumns.tsx b/packages/core/eventcatalog/src/components/Tables/columns/TeamsTableColumns.tsx
new file mode 100644
index 000000000..68981a5d6
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/columns/TeamsTableColumns.tsx
@@ -0,0 +1,152 @@
+import { createColumnHelper } from '@tanstack/react-table';
+import { useState } from 'react';
+import { filterByName, filterCollectionByName } from '../filters/custom-filters';
+import { buildUrl } from '@utils/url-builder';
+import type { TData } from '../Table';
+import type { CollectionUserTypes } from '@types';
+import type { TableConfiguration } from '@types';
+import { getColorAndIconForCollection } from '@utils/collections/icons';
+import { getCollectionTextColorClass } from '@utils/collection-colors';
+import { DirectorySourceCell } from './DirectorySourceColumn';
+const columnHelper = createColumnHelper<TData<CollectionUserTypes>>();
+
+const CollectionListCell = ({
+  items,
+  emptyText,
+}: {
+  items: Array<{ collection: string; data: { id: string; name: string; version?: string } }> | undefined;
+  emptyText: string;
+}) => {
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  if (!items || items.length === 0) {
+    return <span className="text-xs text-[rgb(var(--ec-icon-color))]">{emptyText}</span>;
+  }
+
+  const visibleItems = isExpanded ? items : items.slice(0, 4);
+  const hiddenCount = items.length - 4;
+
+  return (
+    <div className="flex flex-col gap-1">
+      {visibleItems.map((item, index) => {
+        const { color, Icon } = getColorAndIconForCollection(item.collection);
+        const href = buildUrl(`/docs/${item.collection}/${item.data.id}${item.data.version ? `/${item.data.version}` : ''}`);
+
+        return (
+          <a
+            key={`${item.data.id}-${index}`}
+            href={href}
+            className="group inline-flex items-center gap-1.5 text-[0.8rem] text-[rgb(var(--ec-icon-color))] transition-colors hover:text-[rgb(var(--ec-accent))]"
+          >
+            <Icon
+              className={`h-3.5 w-3.5 flex-shrink-0 ${getCollectionTextColorClass(color, 'text-[rgb(var(--ec-icon-color))]')}`}
+            />
+            <span className="max-w-[140px] truncate" title={item.data.name}>
+              {item.data.name}
+            </span>
+            {item.data.version && <span className="text-xs text-[rgb(var(--ec-icon-color))]">v{item.data.version}</span>}
+          </a>
+        );
+      })}
+      {hiddenCount > 0 && (
+        <button
+          onClick={() => setIsExpanded(!isExpanded)}
+          className="text-xs text-[rgb(var(--ec-accent))] hover:underline text-left"
+        >
+          {isExpanded ? 'Show less' : `+${hiddenCount} more`}
+        </button>
+      )}
+    </div>
+  );
+};
+
+export const columns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration.columns?.name?.label || 'Name'}</span>,
+    cell: (info) => {
+      const team = info.row.original;
+      return (
+        <a
+          href={buildUrl(`/docs/${team.collection}/${team.data.id}`)}
+          className="group inline-flex items-center text-sm font-semibold text-[rgb(var(--ec-page-text))] transition-colors hover:text-[rgb(var(--ec-accent))]"
+        >
+          <span>{team.data.name}</span>
+        </a>
+      );
+    },
+    meta: {
+      filterVariant: 'name',
+      filteredItemHasVersion: false,
+    },
+    filterFn: filterByName,
+  }),
+
+  columnHelper.accessor('data.source', {
+    id: 'source',
+    header: () => <span>{tableConfiguration.columns?.source?.label || 'Source'}</span>,
+    cell: (info) => <DirectorySourceCell source={info.getValue() as { provider: string; url?: string } | undefined} />,
+    meta: {
+      showFilter: false,
+      className: 'w-[96px]',
+    },
+  }),
+
+  columnHelper.accessor(
+    (row) => {
+      const events = row.data.ownedEvents || [];
+      const commands = row.data.ownedCommands || [];
+      const queries = row.data.ownedQueries || [];
+      return [...events, ...commands, ...queries];
+    },
+    {
+      id: 'ownedMessages',
+      header: () => <span>{tableConfiguration.columns?.ownedMessages?.label || 'Owned messages'}</span>,
+      meta: {
+        showFilter: false,
+      },
+      cell: (info) => (
+        <CollectionListCell
+          items={
+            info.getValue() as Array<{ collection: string; data: { id: string; name: string; version?: string } }> | undefined
+          }
+          emptyText="No messages"
+        />
+      ),
+    }
+  ),
+
+  columnHelper.accessor('data.ownedServices', {
+    id: 'ownedServices',
+    header: () => <span>{tableConfiguration.columns?.ownedServices?.label || 'Owned services'}</span>,
+    meta: {
+      filterVariant: 'collection',
+      collectionFilterKey: 'ownedServices',
+    },
+    cell: (info) => (
+      <CollectionListCell
+        items={info.getValue() as Array<{ collection: string; data: { id: string; name: string; version?: string } }> | undefined}
+        emptyText="No services"
+      />
+    ),
+    footer: (info) => info.column.id,
+    filterFn: filterCollectionByName('ownedServices'),
+  }),
+
+  columnHelper.accessor('data.ownedAgents', {
+    id: 'ownedAgents',
+    header: () => <span>{tableConfiguration.columns?.ownedAgents?.label || 'Owned agents'}</span>,
+    meta: {
+      filterVariant: 'collection',
+      collectionFilterKey: 'ownedAgents',
+    },
+    cell: (info) => (
+      <CollectionListCell
+        items={info.getValue() as Array<{ collection: string; data: { id: string; name: string; version?: string } }> | undefined}
+        emptyText="No agents"
+      />
+    ),
+    footer: (info) => info.column.id,
+    filterFn: filterCollectionByName('ownedAgents'),
+  }),
+];
diff --git a/packages/core/eventcatalog/src/components/Tables/columns/UserTableColumns.tsx b/packages/core/eventcatalog/src/components/Tables/columns/UserTableColumns.tsx
new file mode 100644
index 000000000..cc7326e64
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/Tables/columns/UserTableColumns.tsx
@@ -0,0 +1,189 @@
+import { createColumnHelper } from '@tanstack/react-table';
+import { useState } from 'react';
+import { filterByName, filterCollectionByName } from '../filters/custom-filters';
+import { buildUrl } from '@utils/url-builder';
+import type { TData } from '../Table';
+import type { CollectionUserTypes } from '@types';
+import type { TableConfiguration } from '@types';
+import { getColorAndIconForCollection } from '@utils/collections/icons';
+import { getCollectionTextColorClass } from '@utils/collection-colors';
+import { DirectorySourceCell } from './DirectorySourceColumn';
+const columnHelper = createColumnHelper<TData<CollectionUserTypes>>();
+
+const CollectionListCell = ({
+  items,
+  emptyText,
+}: {
+  items: Array<{ collection: string; data: { id: string; name: string; version?: string } }> | undefined;
+  emptyText: string;
+}) => {
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  if (!items || items.length === 0) {
+    return <span className="text-xs text-[rgb(var(--ec-icon-color))]">{emptyText}</span>;
+  }
+
+  const visibleItems = isExpanded ? items : items.slice(0, 4);
+  const hiddenCount = items.length - 4;
+
+  return (
+    <div className="flex flex-col gap-1">
+      {visibleItems.map((item, index) => {
+        const { color, Icon } = getColorAndIconForCollection(item.collection);
+        const href =
+          item.collection === 'teams'
+            ? buildUrl(`/docs/teams/${item.data.id}`)
+            : buildUrl(`/docs/${item.collection}/${item.data.id}${item.data.version ? `/${item.data.version}` : ''}`);
+
+        return (
+          <a
+            key={`${item.data.id}-${index}`}
+            href={href}
+            className="group inline-flex items-center gap-1.5 text-[0.8rem] text-[rgb(var(--ec-icon-color))] transition-colors hover:text-[rgb(var(--ec-accent))]"
+          >
+            <Icon
+              className={`h-3.5 w-3.5 flex-shrink-0 ${getCollectionTextColorClass(color, 'text-[rgb(var(--ec-icon-color))]')}`}
+            />
+            <span className="max-w-[140px] truncate" title={item.data.name}>
+              {item.data.name}
+            </span>
+            {item.data.version && <span className="text-xs text-[rgb(var(--ec-icon-color))]">v{item.data.version}</span>}
+          </a>
+        );
+      })}
+      {hiddenCount > 0 && (
+        <button
+          onClick={() => setIsExpanded(!isExpanded)}
+          className="text-xs text-[rgb(var(--ec-accent))] hover:underline text-left"
+        >
+          {isExpanded ? 'Show less' : `+${hiddenCount} more`}
+        </button>
+      )}
+    </div>
+  );
+};
+
+export const columns = (tableConfiguration: TableConfiguration) => [
+  columnHelper.accessor('data.name', {
+    id: 'name',
+    header: () => <span>{tableConfiguration.columns?.name?.label || 'Name'}</span>,
+    cell: (info) => {
+      const user = info.row.original;
+      return (
+        <a
+          href={buildUrl(`/docs/${user.collection}/${user.data.id}`)}
+          className="group inline-flex items-center text-sm font-semibold text-[rgb(var(--ec-page-text))] transition-colors hover:text-[rgb(var(--ec-accent))]"
+        >
+          <span>{user.data.name}</span>
+        </a>
+      );
+    },
+    meta: {
+      filterVariant: 'name',
+      filteredItemHasVersion: false,
+    },
+    filterFn: filterByName,
+  }),
+
+  columnHelper.accessor('data.source', {
+    id: 'source',
+    header: () => <span>{tableConfiguration.columns?.source?.label || 'Source'}</span>,
+    cell: (info) => <DirectorySourceCell source={info.getValue() as { provider: string; url?: string } | undefined} />,
+    meta: {
+      showFilter: false,
+      className: 'w-[96px]',
+    },
+  }),
+
+  columnHelper.accessor('data.role', {
+    id: 'role',
+    header: () => <span>{tableConfiguration.columns?.role?.label || 'Role'}</span>,
+    cell: (info) => {
+      const role = info.getValue() as string | undefined;
+      return role ? (
+        <span className="text-[0.8rem] text-[rgb(var(--ec-icon-color))]">{role}</span>
+      ) : (
+        <span className="text-xs text-[rgb(var(--ec-icon-color))]">-</span>
+      );
+    },
+    meta: {
+      showFilter: false,
+    },
+  }),
+
+  columnHelper.accessor(
+    (row) => {
+      const events = row.data.ownedEvents || [];
+      const commands = row.data.ownedCommands || [];
+      const queries = row.data.ownedQueries || [];
+      return [...events, ...commands, ...queries];
+    },
+    {
+      id: 'ownedMessages',
+      header: () => <span>{tableConfiguration.columns?.ownedMessages?.label || 'Owned messages'}</span>,
+      meta: {
+        showFilter: false,
+      },
+      cell: (info) => (
+        <CollectionListCell
+          items={
+            info.getValue() as Array<{ collection: string; data: { id: string; name: string; version?: string } }> | undefined
+          }
+          emptyText="No messages"
+        />
+      ),
+    }
+  ),
+
+  columnHelper.accessor('data.ownedServices', {
+    id: 'ownedServices',
+    header: () => <span>{tableConfiguration.columns?.ownedServices?.label || 'Owned services'}</span>,
+    meta: {
+      filterVariant: 'collection',
+      collectionFilterKey: 'ownedServices',
+    },
+    cell: (info) => (
+      <CollectionListCell
+        items={info.getValue() as Array<{ collection: string; data: { id: string; name: string; version?: string } }> | undefined}
+        emptyText="No services"
+      />
+    ),
+    footer: (info) => info.column.id,
+    filterFn: filterCollectionByName('ownedServices'),
+  }),
+
+  columnHelper.accessor('data.ownedAgents', {
+    id: 'ownedAgents',
+    header: () => <span>{tableConfiguration.columns?.ownedAgents?.label || 'Owned agents'}</span>,
+    meta: {
+      filterVariant: 'collection',
+      collectionFilterKey: 'ownedAgents',
+    },
+    cell: (info) => (
+      <CollectionListCell
+        items={info.getValue() as Array<{ collection: string; data: { id: string; name: string; version?: string } }> | undefined}
+        emptyText="No agents"
+      />
+    ),
+    footer: (info) => info.column.id,
+    filterFn: filterCollectionByName('ownedAgents'),
+  }),
+
+  columnHelper.accessor('data.associatedTeams', {
+    id: 'associatedTeams',
+    header: () => <span>{tableConfiguration.columns?.associatedTeams?.label || 'Teams'}</span>,
+    meta: {
+      filterVariant: 'collection',
+      collectionFilterKey: 'associatedTeams',
+      filteredItemHasVersion: false,
+    },
+    cell: (info) => (
+      <CollectionListCell
+        items={info.getValue() as Array<{ collection: string; data: { id: string; name: string; version?: string } }> | undefined}
+        emptyText="No teams"
+      />
+    ),
+    footer: (info) => info.column.id,
+    filterFn: filterCollectionByName('associatedTeams'),
+  }),
+];
diff --git a/eventcatalog/src/components/Tables/columns/index.tsx b/packages/core/eventcatalog/src/components/Tables/columns/index.tsx
similarity index 100%
rename from eventcatalog/src/components/Tables/columns/index.tsx
rename to packages/core/eventcatalog/src/components/Tables/columns/index.tsx
diff --git a/eventcatalog/src/components/Tables/filters/custom-filters.ts b/packages/core/eventcatalog/src/components/Tables/filters/custom-filters.ts
similarity index 100%
rename from eventcatalog/src/components/Tables/filters/custom-filters.ts
rename to packages/core/eventcatalog/src/components/Tables/filters/custom-filters.ts
diff --git a/packages/core/eventcatalog/src/components/ThemeToggle.tsx b/packages/core/eventcatalog/src/components/ThemeToggle.tsx
new file mode 100644
index 000000000..c2ff3a75c
--- /dev/null
+++ b/packages/core/eventcatalog/src/components/ThemeToggle.tsx
@@ -0,0 +1,26 @@
+import { useStore } from '@nanostores/react';
+import { useEffect, useState } from 'react';
+import { Moon, Sun } from 'lucide-react';
+import { themeStore, toggleTheme } from '@stores/theme-store';
+
+export default function ThemeToggle() {
+  const theme = useStore(themeStore);
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  const label = mounted ? `Switch to ${theme === 'light' ? 'dark' : 'light'} mode` : 'Toggle theme';
+
+  return (
+    <button
+      onClick={toggleTheme}
+      className="p-2 rounded-md text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-icon-hover))] hover:bg-[rgb(var(--ec-dropdown-hover))] transition-colors"
+      aria-label={label}
+      title={label}
+    >
+      {!mounted ? <Moon className="w-5 h-5" /> : theme === 'light' ? <Moon className="w-5 h-5" /> : <Sun className="w-5 h-5" />}
+    </button>
+  );
+}
diff --git a/eventcatalog/src/content.config-shared-collections.ts b/packages/core/eventcatalog/src/content.config-shared-collections.ts
similarity index 92%
rename from eventcatalog/src/content.config-shared-collections.ts
rename to packages/core/eventcatalog/src/content.config-shared-collections.ts
index b03c1789c..be2a7d6f8 100644
--- a/eventcatalog/src/content.config-shared-collections.ts
+++ b/packages/core/eventcatalog/src/content.config-shared-collections.ts
@@ -1,4 +1,4 @@
-import { z } from 'astro:content';
+import { z } from 'astro/zod';
 
 // Shared schemas used across multiple files
 export const badge = z.object({
@@ -6,6 +6,7 @@ export const badge = z.object({
   backgroundColor: z.string(),
   textColor: z.string(),
   icon: z.string().optional(),
+  url: z.string().optional(),
 });
 
 // Create a union type for owners
diff --git a/packages/core/eventcatalog/src/content.config.ts b/packages/core/eventcatalog/src/content.config.ts
new file mode 100644
index 000000000..228e3bd6a
--- /dev/null
+++ b/packages/core/eventcatalog/src/content.config.ts
@@ -0,0 +1,1172 @@
+import { defineCollection, reference } from 'astro:content';
+import { z } from 'astro/zod';
+import { glob as globPackage } from 'glob';
+import { v4 as uuidv4 } from 'uuid';
+import { badge, ownerReference } from './content.config-shared-collections';
+import { ADR_STATUS_VALUES } from './utils/collections/adr-constants';
+import fs from 'fs';
+import path from 'path';
+import { userTeamDirectoryLoader } from './enterprise/directory/user-team-directory';
+import config from '@config';
+import { schemaLoader } from './utils/collections/schema-loader';
+import { globWithSafeWatcher, withIgnoredBuildArtifacts } from './utils/collections/glob-loader';
+
+// Enterprise Collections
+import { customPagesSchema, resourceDocsSchema, resourceDocCategoriesSchema } from './enterprise/collections';
+
+export const projectDirBase = (() => {
+  const projectDir = process.env.PROJECT_DIR;
+  const catalogDir = process.env.CATALOG_DIR;
+
+  // If CATALOG_DIR is set (monorepo mode), compute relative path from catalog to project
+  // Otherwise fall back to absolute path (standalone mode)
+  if (catalogDir && projectDir) {
+    const relativePath = path.relative(catalogDir, projectDir);
+    // Ensure forward slashes for consistency
+    return relativePath.replace(/\\/g, '/');
+  }
+
+  // Fallback to absolute path
+  if (process.platform === 'win32' && projectDir) {
+    const projectDirPath = projectDir.replace(/\\/g, '/');
+    return projectDirPath.startsWith('/') ? projectDirPath : `/${projectDirPath}`;
+  }
+  return projectDir;
+})();
+
+const pages = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/pages/*.(md|mdx)']),
+    base: projectDirBase,
+  }),
+  schema: z
+    .object({
+      id: z.string(),
+    })
+    .optional(),
+});
+
+const pointer = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+});
+
+const detailPanelPropertySchema = z.object({
+  visible: z.boolean().optional(),
+});
+
+const channelPointer = z
+  .object({
+    parameters: z.record(z.string(), z.string()).optional(),
+  })
+  .extend(pointer.shape);
+
+const schemaPointer = z.object({
+  id: z.string().optional(),
+  ref: z.string().optional(),
+  file: z.string().optional(),
+  path: z.string().optional(),
+  name: z.string().optional(),
+  format: z.string().optional(),
+  environments: z.array(z.string()).optional(),
+  default: z.boolean().optional(),
+});
+
+const sendsPointer = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+  fields: z.array(z.string()).optional(),
+  group: z.string().optional(),
+  to: z
+    .array(
+      z.object({
+        ...channelPointer.shape,
+        delivery_mode: z.enum(['push', 'pull', 'push-pull']).optional().default('push'),
+      })
+    )
+    .optional(),
+});
+
+const receivesPointer = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+  fields: z.array(z.string()).optional(),
+  group: z.string().optional(),
+  from: z
+    .array(
+      z.object({
+        ...channelPointer.shape,
+        delivery_mode: z.enum(['push', 'pull', 'push-pull']).optional().default('push'),
+      })
+    )
+    .optional(),
+});
+
+const resourcePointer = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+  type: z.enum(['agent', 'service', 'event', 'command', 'query', 'flow', 'channel', 'domain', 'user', 'team', 'container']),
+});
+
+const directoryEntrySource = z.object({
+  provider: z.string(),
+  id: z.string().optional(),
+  url: z.string().optional(),
+});
+
+const changelogs = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/changelog.(md|mdx)']),
+    base: projectDirBase,
+  }),
+  schema: z.object({
+    createdAt: z.date().optional(),
+    badges: z.array(badge).optional(),
+    // Used by eventcatalog
+    version: z.string().optional(),
+    versions: z.array(z.string()).optional(),
+    latestVersion: z.string().optional(),
+    catalog: z
+      .object({
+        path: z.string(),
+        filePath: z.string(),
+        publicPath: z.string(),
+        type: z.string(),
+      })
+      .optional(),
+  }),
+});
+
+const baseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  summary: z.string().optional(),
+  // version: z.union([z.string(), z.number()]),
+  version: z.string(),
+  draft: z.union([z.boolean(), z.object({ title: z.string().optional(), message: z.string() })]).optional(),
+  badges: z.array(badge).optional(),
+  owners: z.array(ownerReference).optional(),
+  schemaPath: z.string().optional(),
+  specifications: z
+    .union([
+      z.object({
+        openapiPath: z.string().optional(),
+        asyncapiPath: z.string().optional(),
+        graphqlPath: z.string().optional(),
+      }),
+      z.array(
+        z.object({
+          type: z.enum(['openapi', 'asyncapi', 'graphql']),
+          path: z.string(),
+          name: z.string().optional(),
+          headers: z.record(z.string(), z.string()).optional(),
+        })
+      ),
+    ])
+    .optional(),
+  sidebar: z
+    .object({
+      label: z.string().optional(),
+      badge: z.string().optional(),
+      color: z.string().optional(),
+      backgroundColor: z.string().optional(),
+    })
+    .optional(),
+  repository: z
+    .object({
+      language: z.string().optional(),
+      url: z.string().optional(),
+    })
+    .optional(),
+  hidden: z.boolean().optional(),
+  editUrl: z.string().optional(),
+  resourceGroups: z
+    .array(
+      z.object({
+        id: z.string().optional(),
+        title: z.string().optional(),
+        items: z.array(resourcePointer),
+        limit: z.number().optional().default(10),
+        sidebar: z.boolean().optional().default(true),
+      })
+    )
+    .optional(),
+  styles: z
+    .object({
+      icon: z.string().optional(),
+      node: z
+        .object({
+          color: z.string().optional(),
+          label: z.string().optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+  deprecated: z
+    .union([
+      z.object({
+        message: z.string().optional(),
+        date: z.union([z.string(), z.date()]).optional(),
+      }),
+      z.boolean().optional(),
+    ])
+    .optional(),
+  visualiser: z.boolean().optional(),
+  attachments: z
+    .array(
+      z.union([
+        z.string().url(), // simple case
+        z.object({
+          url: z.string().url(),
+          title: z.string().optional(),
+          type: z.string().optional(), // e.g. "architecture-record", "diagram"
+          description: z.string().optional(),
+          icon: z.string().optional(),
+        }),
+      ])
+    )
+    .optional(),
+  diagrams: z.array(pointer).optional(),
+  // Used by eventcatalog
+  versions: z.array(z.string()).optional(),
+  latestVersion: z.string().optional(),
+  catalog: z
+    .object({
+      path: z.string(),
+      filePath: z.string(),
+      publicPath: z.string(),
+      type: z.string(),
+    })
+    .optional(),
+});
+
+const agentBaseSchema = baseSchema.omit({ specifications: true });
+
+const flowStep = z
+  .union([
+    // Can be a string or a number just to reference a step
+    z.union([z.string(), z.number()]),
+    z
+      .object({
+        id: z.union([z.string(), z.number()]),
+        label: z.string().optional(),
+      })
+      .optional(),
+  ])
+  .optional();
+
+const flows = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/flows/**/index.(md|mdx)', '**/flows/**/versioned/*/index.(md|mdx)']),
+    base: projectDirBase,
+    generateId: ({ data }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      detailsPanel: z
+        .object({
+          owners: detailPanelPropertySchema.optional(),
+          versions: detailPanelPropertySchema.optional(),
+          changelog: detailPanelPropertySchema.optional(),
+        })
+        .optional(),
+      steps: z.array(
+        z
+          .object({
+            id: z.union([z.string(), z.number()]),
+            type: z.enum(['node', 'message', 'agent', 'user', 'actor']).optional(),
+            title: z.string(),
+            summary: z.string().optional(),
+            message: pointer.optional(),
+            agent: pointer.optional(),
+            service: pointer.optional(),
+            flow: pointer.optional(),
+            container: pointer.optional(),
+            dataProduct: pointer.optional(),
+
+            actor: z
+              .object({
+                name: z.string(),
+                summary: z.string().optional(),
+              })
+              .optional(),
+            custom: z
+              .object({
+                title: z.string(),
+                icon: z.string().optional(),
+                type: z.string().optional(),
+                summary: z.string().optional(),
+                url: z.string().url().optional(),
+                color: z.string().optional(),
+                properties: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
+                height: z.number().optional(),
+                menu: z
+                  .array(
+                    z.object({
+                      label: z.string(),
+                      url: z.string().url().optional(),
+                    })
+                  )
+                  .optional(),
+              })
+              .optional(),
+            externalSystem: z
+              .object({
+                name: z.string(),
+                summary: z.string().optional(),
+                url: z.string().url().optional(),
+              })
+              .optional(),
+            next_step: flowStep,
+            next_steps: z.array(flowStep).optional(),
+          })
+          .refine((data) => {
+            // Cant have both next_steps and next_steps
+            if (data.next_step && data.next_steps) return false;
+
+            // Either one or non types can be present
+            const typesUsed = [
+              data.message,
+              data.agent,
+              data.service,
+              data.flow,
+              data.container,
+              data.dataProduct,
+              data.actor,
+              data.custom,
+            ].filter((v) => v).length;
+            return typesUsed === 0 || typesUsed === 1;
+          })
+      ),
+    })
+    .extend(baseSchema.shape),
+});
+
+const operationSchema = z
+  .object({
+    method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).optional(),
+    path: z.string().optional(),
+    statusCodes: z.array(z.string()).optional(),
+  })
+  .optional();
+
+const messageDetailsPanelPropertySchema = z.object({
+  producers: detailPanelPropertySchema.optional(),
+  consumers: detailPanelPropertySchema.optional(),
+  channels: detailPanelPropertySchema.optional(),
+  versions: detailPanelPropertySchema.optional(),
+  repository: detailPanelPropertySchema.optional(),
+  owners: detailPanelPropertySchema.optional(),
+  changelog: detailPanelPropertySchema.optional(),
+  attachments: detailPanelPropertySchema.optional(),
+});
+
+const events = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/events/*/index.(md|mdx)', '**/events/*/versioned/*/index.(md|mdx)']),
+    base: projectDirBase,
+    generateId: ({ data, ...rest }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      // Used by users
+      operation: operationSchema,
+      // Used by eventcatalog
+      producers: z.array(reference('services')).optional(),
+      consumers: z.array(reference('services')).optional(),
+      channels: z.array(channelPointer).optional(),
+      schemas: z.array(schemaPointer).optional(),
+      messageChannels: z.array(reference('channels')).optional(),
+      detailsPanel: messageDetailsPanelPropertySchema.optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+const commands = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/commands/*/index.(md|mdx)', '**/commands/*/versioned/*/index.(md|mdx)']),
+    base: projectDirBase,
+    generateId: ({ data }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      // Used by users
+      operation: operationSchema,
+      // Used by eventcatalog
+      producers: z.array(reference('services')).optional(),
+      consumers: z.array(reference('services')).optional(),
+      channels: z.array(channelPointer).optional(),
+      schemas: z.array(schemaPointer).optional(),
+      detailsPanel: messageDetailsPanelPropertySchema.optional(),
+      messageChannels: z.array(reference('channels')).optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+const queries = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/queries/*/index.(md|mdx)', '**/queries/*/versioned/*/index.(md|mdx)']),
+    base: projectDirBase,
+    generateId: ({ data }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      // Used by users
+      operation: operationSchema,
+      // Used by eventcatalog
+      producers: z.array(reference('services')).optional(),
+      consumers: z.array(reference('services')).optional(),
+      channels: z.array(channelPointer).optional(),
+      schemas: z.array(schemaPointer).optional(),
+      detailsPanel: messageDetailsPanelPropertySchema.optional(),
+      messageChannels: z.array(reference('channels')).optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+const dataProductOutputPointer = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+  contract: z
+    .object({
+      path: z.string(),
+      name: z.string(),
+      type: z.string().optional(),
+    })
+    .optional(),
+});
+
+const dataProducts = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/data-products/*/index.(md|mdx)', '**/data-products/*/versioned/*/index.(md|mdx)']),
+    base: projectDirBase,
+    generateId: ({ data }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      inputs: z.array(pointer).optional(),
+      outputs: z.array(dataProductOutputPointer).optional(),
+      detailsPanel: z
+        .object({
+          domains: detailPanelPropertySchema.optional(),
+          inputs: detailPanelPropertySchema.optional(),
+          outputs: detailPanelPropertySchema.optional(),
+          versions: detailPanelPropertySchema.optional(),
+          repository: detailPanelPropertySchema.optional(),
+          owners: detailPanelPropertySchema.optional(),
+          changelog: detailPanelPropertySchema.optional(),
+          flows: detailPanelPropertySchema.optional(),
+        })
+        .optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+const services = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts([
+      'domains/*/services/*/index.(md|mdx)',
+      'domains/*/services/*/versioned/*/index.(md|mdx)',
+
+      // Capture subdomain folders
+      'domains/*/subdomains/*/services/*/index.(md|mdx)',
+      'domains/*/subdomains/*/services/*/versioned/*/index.(md|mdx)',
+
+      // Capture services inside systems
+      'systems/*/services/*/index.(md|mdx)',
+      'systems/*/services/*/versioned/*/index.(md|mdx)',
+      'domains/*/systems/*/services/*/index.(md|mdx)',
+      'domains/*/systems/*/services/*/versioned/*/index.(md|mdx)',
+
+      // Capture services in the root
+      'services/*/index.(md|mdx)', // ✅ Capture only services markdown files
+      'services/*/versioned/*/index.(md|mdx)', // ✅ Capture versioned files inside services
+    ]),
+    base: projectDirBase,
+    generateId: ({ data, ...rest }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      sends: z.array(sendsPointer).optional(),
+      receives: z.array(receivesPointer).optional(),
+      entities: z.array(pointer).optional(),
+      writesTo: z.array(pointer).optional(),
+      readsFrom: z.array(pointer).optional(),
+      flows: z.array(pointer).optional(),
+      externalSystem: z.boolean().optional(),
+      detailsPanel: z
+        .object({
+          domains: detailPanelPropertySchema.optional(),
+          messages: detailPanelPropertySchema.optional(),
+          versions: detailPanelPropertySchema.optional(),
+          specifications: detailPanelPropertySchema.optional(),
+          entities: detailPanelPropertySchema.optional(),
+          repository: detailPanelPropertySchema.optional(),
+          owners: detailPanelPropertySchema.optional(),
+          changelog: detailPanelPropertySchema.optional(),
+          containers: detailPanelPropertySchema.optional(),
+        })
+        .optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+const agentTool = z.object({
+  name: z.string(),
+  type: z.string(),
+  icon: z.string().optional(),
+  url: z.string().optional(),
+  description: z.string().optional(),
+});
+
+const agentModel = z.object({
+  provider: z.string().optional(),
+  name: z.string().optional(),
+  version: z.string().optional(),
+});
+
+const agents = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/agents/*/index.(md|mdx)', '**/agents/*/versioned/*/index.(md|mdx)']),
+    base: projectDirBase,
+    generateId: ({ data }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      sends: z.array(sendsPointer).optional(),
+      receives: z.array(receivesPointer).optional(),
+      writesTo: z.array(pointer).optional(),
+      readsFrom: z.array(pointer).optional(),
+      flows: z.array(pointer).optional(),
+      model: agentModel.optional(),
+      tools: z.array(agentTool).optional(),
+      specifications: z.undefined().optional(),
+      detailsPanel: z
+        .object({
+          domains: detailPanelPropertySchema.optional(),
+          messages: detailPanelPropertySchema.optional(),
+          versions: detailPanelPropertySchema.optional(),
+          repository: detailPanelPropertySchema.optional(),
+          owners: detailPanelPropertySchema.optional(),
+          changelog: detailPanelPropertySchema.optional(),
+          containers: detailPanelPropertySchema.optional(),
+          tools: detailPanelPropertySchema.optional(),
+          model: detailPanelPropertySchema.optional(),
+        })
+        .optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+const adrStatus = z.enum(ADR_STATUS_VALUES);
+
+const adrPointer = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+});
+
+const adrResourcePointer = adrPointer.extend({
+  type: z.enum([
+    'agent',
+    'service',
+    'event',
+    'command',
+    'query',
+    'flow',
+    'channel',
+    'domain',
+    'system',
+    'user',
+    'team',
+    'container',
+    'entity',
+    'diagram',
+    'data-product',
+  ]),
+});
+
+const adrs = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/adrs/*/index.(md|mdx)', '**/adrs/*/versioned/*/index.(md|mdx)']),
+    base: projectDirBase,
+    generateId: ({ data }) => `${data.id}-${data.version}`,
+  }),
+  schema: z
+    .object({
+      status: adrStatus,
+      date: z.coerce.date(),
+      decisionMakers: z.array(ownerReference).optional(),
+      appliesTo: z.array(adrResourcePointer).optional(),
+      supersedes: z.array(adrPointer).optional(),
+      supersededBy: z.array(adrPointer).optional(),
+      amends: z.array(adrPointer).optional(),
+      amendedBy: z.array(adrPointer).optional(),
+      related: z.array(adrPointer).optional(),
+      detailsPanel: z
+        .object({
+          status: detailPanelPropertySchema.optional(),
+          date: detailPanelPropertySchema.optional(),
+          decisionMakers: detailPanelPropertySchema.optional(),
+          appliesTo: detailPanelPropertySchema.optional(),
+          relationships: detailPanelPropertySchema.optional(),
+          owners: detailPanelPropertySchema.optional(),
+          repository: detailPanelPropertySchema.optional(),
+          changelog: detailPanelPropertySchema.optional(),
+        })
+        .optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+// 1) Put this near your other enums/utilities
+const containerTypeEnum = z.enum([
+  // Core
+  'database',
+  'cache',
+  'objectStore',
+  'searchIndex',
+  'dataWarehouse',
+  'dataLake',
+  'externalSaaS',
+  // Fallback
+  'other',
+]);
+
+const accessModeEnum = z.enum(['read', 'write', 'readWrite', 'appendOnly']);
+const dataClassificationEnum = z.enum(['public', 'internal', 'confidential', 'regulated']);
+
+const containers = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/containers/**/index.(md|mdx)', '**/containers/**/versioned/*/index.(md|mdx)']),
+    base: projectDirBase,
+    generateId: ({ data }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      container_type: containerTypeEnum, // <— the important discriminator inside DataContainer
+      technology: z.string().optional(), // e.g. "postgres@14", "kafka", "s3"
+      authoritative: z.boolean().optional().default(false),
+      access_mode: accessModeEnum.optional(), // read/write/readWrite/appendOnly
+      classification: dataClassificationEnum.optional(),
+      residency: z.string().optional(),
+      retention: z.string().optional(),
+      // details panel toggles (aligns with your pattern)
+      detailsPanel: z
+        .object({
+          versions: detailPanelPropertySchema.optional(),
+          repository: detailPanelPropertySchema.optional(),
+          owners: detailPanelPropertySchema.optional(),
+          changelog: detailPanelPropertySchema.optional(),
+          attachments: detailPanelPropertySchema.optional(),
+          services: detailPanelPropertySchema.optional(),
+          flows: detailPanelPropertySchema.optional(),
+        })
+        .optional(),
+      services: z.array(reference('services')).optional(),
+
+      servicesThatWriteToContainer: z.array(reference('services')).optional(),
+      servicesThatReadFromContainer: z.array(reference('services')).optional(),
+      dataProductsThatWriteToContainer: z.array(reference('data-products')).optional(),
+      dataProductsThatReadFromContainer: z.array(reference('data-products')).optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+const customPages = defineCollection({
+  loader: globWithSafeWatcher({
+    // any number of child folders
+    pattern: withIgnoredBuildArtifacts(['docs/*.(md|mdx)', 'docs/**/*.@(md|mdx)']),
+    base: projectDirBase,
+  }),
+  schema: customPagesSchema,
+});
+
+const resourceDocs = defineCollection({
+  loader: globWithSafeWatcher({
+    // Resource-level docs are restricted to known resource paths.
+    // This avoids scanning external docs such as node_modules/**/docs.
+    pattern: withIgnoredBuildArtifacts([
+      '{agents,events,commands,queries,services,flows,containers,channels,entities,data-products,systems}/**/docs/**/*.@(md|mdx)',
+      '{agents,events,commands,queries,services,flows,containers,channels,entities,data-products,systems}/**/docs/*.@(md|mdx)',
+      '{agents,events,commands,queries,services,flows,containers,channels,entities,data-products,systems}/**/versioned/*/docs/**/*.@(md|mdx)',
+      '{agents,events,commands,queries,services,flows,containers,channels,entities,data-products,systems}/**/versioned/*/docs/*.@(md|mdx)',
+      'domains/**/docs/**/*.@(md|mdx)',
+      'domains/**/docs/*.@(md|mdx)',
+    ]),
+    base: projectDirBase,
+  }),
+  schema: resourceDocsSchema,
+});
+
+const resourceDocCategories = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts([
+      '{agents,events,commands,queries,services,flows,containers,channels,entities,data-products,systems}/**/docs/**/category.json',
+      '{agents,events,commands,queries,services,flows,containers,channels,entities,data-products,systems}/**/docs/**/_category_.json',
+      '{agents,events,commands,queries,services,flows,containers,channels,entities,data-products,systems}/**/versioned/*/docs/**/category.json',
+      '{agents,events,commands,queries,services,flows,containers,channels,entities,data-products,systems}/**/versioned/*/docs/**/_category_.json',
+      'domains/**/docs/**/category.json',
+      'domains/**/docs/**/_category_.json',
+      'domains/**/docs/category.json',
+      'domains/**/docs/_category_.json',
+    ]),
+    base: projectDirBase,
+  }),
+  schema: resourceDocCategoriesSchema,
+});
+
+const domains = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts([
+      // ✅ Strictly include only index.md at the expected levels
+      'domains/*/index.(md|mdx)',
+      'domains/*/versioned/*/index.(md|mdx)',
+
+      // Capture subdomain folders
+      'domains/*/subdomains/*/index.(md|mdx)',
+      'domains/*/subdomains/*/versioned/*/index.(md|mdx)',
+    ]),
+    base: projectDirBase,
+    generateId: ({ data, ...rest }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      services: z.array(pointer).optional(),
+      agents: z.array(pointer).optional(),
+      domains: z.array(pointer).optional(),
+      systems: z.array(pointer).optional(),
+      entities: z.array(pointer).optional(),
+      'data-products': z.array(pointer).optional(),
+      flows: z.array(pointer).optional(),
+      sends: z.array(sendsPointer).optional(),
+      receives: z.array(receivesPointer).optional(),
+      detailsPanel: z
+        .object({
+          parentDomains: detailPanelPropertySchema.optional(),
+          subdomains: detailPanelPropertySchema.optional(),
+          systems: detailPanelPropertySchema.optional(),
+          services: detailPanelPropertySchema.optional(),
+          entities: detailPanelPropertySchema.optional(),
+          messages: detailPanelPropertySchema.optional(),
+          ubiquitousLanguage: detailPanelPropertySchema.optional(),
+          repository: detailPanelPropertySchema.optional(),
+          versions: detailPanelPropertySchema.optional(),
+          owners: detailPanelPropertySchema.optional(),
+          changelog: detailPanelPropertySchema.optional(),
+          attachments: detailPanelPropertySchema.optional(),
+        })
+        .optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+// A relationship from one system to another, used by the System Diagram.
+// Source-declared and one-directional. The `label` describes the edge; a relationship
+// without a label is treated as having no edge (it is skipped when drawing the diagram).
+const systemRelationshipPointer = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+  label: z.string().optional(),
+});
+
+// An actor (a person/role) that interacts with a system on the Context Diagram.
+// Actors are inline (not a collection) — `id` is the actor's node id, used to
+// de-duplicate the same actor referenced from multiple systems.
+// `direction` controls the edge arrow: `inbound` = actor -> system (e.g. "logs into"),
+// `outbound` = system -> actor (e.g. "sends email to"). Defaults to inbound.
+const systemActorRelationship = z.object({
+  id: z.string(),
+  name: z.string().optional(),
+  label: z.string().optional(),
+  direction: z.enum(['inbound', 'outbound']).optional().default('inbound'),
+});
+
+const systems = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts([
+      '**/systems/**/index.(md|mdx)',
+      '**/systems/**/versioned/*/index.(md|mdx)',
+      // Systems can contain nested resource folders (containers, diagrams, services, etc.).
+      // Those nested resources are loaded by their own collections — exclude their index files
+      // here so they are not mistaken for systems. Nested `systems/` folders are still allowed.
+      '!**/systems/**/agents/**',
+      '!**/systems/**/services/**',
+      '!**/systems/**/events/**',
+      '!**/systems/**/commands/**',
+      '!**/systems/**/queries/**',
+      '!**/systems/**/flows/**',
+      '!**/systems/**/channels/**',
+      '!**/systems/**/entities/**',
+      '!**/systems/**/containers/**',
+      '!**/systems/**/diagrams/**',
+      '!**/systems/**/data-products/**',
+      '!**/systems/**/adrs/**',
+      '!**/systems/**/docs/**',
+    ]),
+    base: projectDirBase,
+    generateId: ({ data }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      // Whether the system belongs to your organisation (`internal`) or is a
+      // third-party/SaaS system you integrate with (`external`, e.g. "Resend",
+      // "Stripe"). External systems are shaded in the node-graph. Defaults to internal.
+      scope: z.enum(['internal', 'external']).optional().default('internal'),
+      services: z.array(pointer).optional(),
+      flows: z.array(pointer).optional(),
+      entities: z.array(pointer).optional(),
+      containers: z.array(pointer).optional(),
+      relationships: z.array(systemRelationshipPointer).optional(),
+      actors: z.array(systemActorRelationship).optional(),
+      detailsPanel: z
+        .object({
+          versions: detailPanelPropertySchema.optional(),
+          repository: detailPanelPropertySchema.optional(),
+          owners: detailPanelPropertySchema.optional(),
+          changelog: detailPanelPropertySchema.optional(),
+          attachments: detailPanelPropertySchema.optional(),
+          services: detailPanelPropertySchema.optional(),
+          flows: detailPanelPropertySchema.optional(),
+          entities: detailPanelPropertySchema.optional(),
+          containers: detailPanelPropertySchema.optional(),
+          diagrams: detailPanelPropertySchema.optional(),
+        })
+        .optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+const channels = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/channels/**/index.(md|mdx)', '**/channels/**/versioned/*/index.(md|mdx)']),
+    base: projectDirBase,
+    generateId: ({ data }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      channels: z.array(channelPointer).optional(),
+      address: z.string().optional(),
+      protocols: z.array(z.string()).optional(),
+      deliveryGuarantee: z.enum(['at-most-once', 'at-least-once', 'exactly-once']).optional(),
+      routes: z.array(channelPointer).optional(),
+      parameters: z
+        .record(
+          z.string(),
+          z.object({
+            enum: z.array(z.string()).optional(),
+            default: z.string().optional(),
+            examples: z.array(z.string()).optional(),
+            description: z.string().optional(),
+          })
+        )
+        .optional(),
+      messages: z.array(z.object({ collection: z.string(), name: z.string(), ...pointer.shape })).optional(),
+      detailsPanel: z
+        .object({
+          producers: detailPanelPropertySchema.optional(),
+          consumers: detailPanelPropertySchema.optional(),
+          messages: detailPanelPropertySchema.optional(),
+          protocols: detailPanelPropertySchema.optional(),
+          parameters: detailPanelPropertySchema.optional(),
+          versions: detailPanelPropertySchema.optional(),
+          repository: detailPanelPropertySchema.optional(),
+          owners: detailPanelPropertySchema.optional(),
+          changelog: detailPanelPropertySchema.optional(),
+          attachments: detailPanelPropertySchema.optional(),
+        })
+        .optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+const ubiquitousLanguages = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts([
+      'domains/*/ubiquitous-language.(md|mdx)',
+      'domains/*/subdomains/*/ubiquitous-language.(md|mdx)',
+    ]),
+    base: projectDirBase,
+    generateId: ({ data }) => {
+      // File has no id, so we need to generate one
+      return uuidv4();
+    },
+  }),
+  schema: z.object({
+    dictionary: z
+      .array(
+        z.object({
+          id: z.string(),
+          name: z.string(),
+          summary: z.string().optional(),
+          description: z.string().optional(),
+          icon: z.string().optional(),
+        })
+      )
+      .optional(),
+  }),
+});
+
+const entities = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/entities/*/index.(md|mdx)', '**/entities/*/versioned/*/index.(md|mdx)']),
+    base: projectDirBase,
+    generateId: ({ data, ...rest }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      aggregateRoot: z.boolean().optional(),
+      identifier: z.string().optional(),
+      properties: z
+        .array(
+          z.object({
+            name: z.string(),
+            type: z.string(),
+            required: z.boolean().optional(),
+            description: z.string().optional(),
+            references: z.string().optional(),
+            referencesIdentifier: z.string().optional(),
+            relationType: z.string().optional(),
+            enum: z.array(z.string()).optional(),
+            items: z
+              .object({
+                type: z.string(),
+              })
+              .optional(),
+          })
+        )
+        .optional(),
+      services: z.array(reference('services')).optional(),
+      domains: z.array(reference('domains')).optional(),
+      detailsPanel: z
+        .object({
+          domains: detailPanelPropertySchema.optional(),
+          services: detailPanelPropertySchema.optional(),
+          messages: detailPanelPropertySchema.optional(),
+          versions: detailPanelPropertySchema.optional(),
+          owners: detailPanelPropertySchema.optional(),
+          changelog: detailPanelPropertySchema.optional(),
+          attachments: detailPanelPropertySchema.optional(),
+        })
+        .optional(),
+    })
+
+    .extend(baseSchema.shape),
+});
+
+const users = defineCollection({
+  loader: userTeamDirectoryLoader({
+    collection: 'users',
+    sources: config.directory?.sources,
+    conflictStrategy: config.directory?.conflictStrategy,
+    local: {
+      pattern: withIgnoredBuildArtifacts('users/*.(md|mdx)'),
+      base: projectDirBase,
+      generateId: ({ data }) => data.id as string,
+    },
+  }),
+  schema: z.object({
+    id: z.string(),
+    name: z.string(),
+    avatarUrl: z.string().optional(),
+    role: z.string().optional(),
+    hidden: z.boolean().optional(),
+    source: directoryEntrySource.optional(),
+    readOnly: z.boolean().optional(),
+    email: z.string().optional(),
+    slackDirectMessageUrl: z.string().optional(),
+    msTeamsDirectMessageUrl: z.string().optional(),
+    ownedAgents: z.array(reference('agents')).optional(),
+    ownedDomains: z.array(reference('domains')).optional(),
+    ownedServices: z.array(reference('services')).optional(),
+    ownedEvents: z.array(reference('events')).optional(),
+    ownedCommands: z.array(reference('commands')).optional(),
+    ownedQueries: z.array(reference('queries')).optional(),
+    associatedTeams: z.array(reference('teams')).optional(),
+  }),
+});
+
+const teams = defineCollection({
+  loader: userTeamDirectoryLoader({
+    collection: 'teams',
+    sources: config.directory?.sources,
+    conflictStrategy: config.directory?.conflictStrategy,
+    local: {
+      pattern: withIgnoredBuildArtifacts('teams/*.(md|mdx)'),
+      base: projectDirBase,
+      generateId: ({ data }) => data.id as string,
+    },
+  }),
+  schema: z.object({
+    id: z.string(),
+    name: z.string(),
+    summary: z.string().optional(),
+    email: z.string().optional(),
+    hidden: z.boolean().optional(),
+    source: directoryEntrySource.optional(),
+    readOnly: z.boolean().optional(),
+    slackDirectMessageUrl: z.string().optional(),
+    msTeamsDirectMessageUrl: z.string().optional(),
+    members: z.array(reference('users')).optional(),
+    ownedAgents: z.array(reference('agents')).optional(),
+    ownedCommands: z.array(reference('commands')).optional(),
+    ownedQueries: z.array(reference('queries')).optional(),
+    ownedDomains: z.array(reference('domains')).optional(),
+    ownedServices: z.array(reference('services')).optional(),
+    ownedEvents: z.array(reference('events')).optional(),
+  }),
+});
+
+const designs = defineCollection({
+  loader: async () => {
+    const data = await globPackage('**/**/*.ecstudio', { cwd: projectDirBase, ignore: ['dist/**'] });
+    // File all the files in the designs folder
+    // Limit 3 designs community edition?
+    const files = data.reduce<{ id: string; name: string }[]>((acc, filePath) => {
+      try {
+        const data = fs.readFileSync(path.join(projectDirBase!, filePath), 'utf-8');
+        const json = JSON.parse(data);
+        return [...acc, { ...json }];
+      } catch (error) {
+        console.error('Error loading design', error);
+        return acc;
+      }
+    }, []);
+    return files;
+  },
+  schema: z.object({
+    id: z.string(),
+    name: z.string(),
+    creationDate: z.string(),
+    source: z.string(),
+    nodes: z.any(),
+    edges: z.any(),
+    viewport: z.any(),
+    version: z.string(),
+  }),
+});
+
+const diagrams = defineCollection({
+  loader: globWithSafeWatcher({
+    pattern: withIgnoredBuildArtifacts(['**/diagrams/**/index.(md|mdx)', '**/diagrams/**/versioned/*/index.(md|mdx)']),
+    base: projectDirBase,
+    generateId: ({ data }) => `${data.id}-${data.version}`,
+  }),
+  schema: z
+    .object({
+      id: z.string(),
+      name: z.string(),
+      version: z.string(),
+      summary: z.string().optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+const schemas = defineCollection({
+  loader: schemaLoader({
+    messages: {
+      pattern: withIgnoredBuildArtifacts([
+        '**/events/*/index.{md,mdx}',
+        '**/events/*/versioned/*/index.{md,mdx}',
+        '**/commands/*/index.{md,mdx}',
+        '**/commands/*/versioned/*/index.{md,mdx}',
+        '**/queries/*/index.{md,mdx}',
+        '**/queries/*/versioned/*/index.{md,mdx}',
+      ]) as string[],
+      base: projectDirBase,
+    },
+    sources: config.schemas?.sources ?? [],
+  }),
+  schema: z
+    .object({
+      format: z.string(),
+      schemaId: z.string().optional(),
+      ref: z.string().optional(),
+      content: z.string().optional(),
+      file: z.string().optional(),
+      filePath: z.string().optional(),
+      environments: z.array(z.string()).optional(),
+      default: z.boolean().optional(),
+      latest: z.boolean().optional(),
+      message: z.object({
+        collection: z.enum(['events', 'commands', 'queries']),
+        id: z.string(),
+        name: z.string().optional(),
+        version: z.string(),
+        summary: z.string().optional(),
+        owners: z.array(z.string()).optional(),
+      }),
+      source: z.object({
+        provider: z.string(),
+        id: z.string().optional(),
+        path: z.string().optional(),
+        url: z.string().optional(),
+        ref: z.string().optional(),
+        branch: z.string().optional(),
+      }),
+      readOnly: z.boolean().optional(),
+    })
+    .extend(baseSchema.shape),
+});
+
+export const collections = {
+  events,
+  commands,
+  queries,
+  services,
+  agents,
+  adrs,
+  channels,
+  users,
+  teams,
+  domains,
+  systems,
+  flows,
+  pages,
+  changelogs,
+  containers,
+
+  // Data Product Collections
+  'data-products': dataProducts,
+
+  // DDD Collections
+  ubiquitousLanguages,
+  entities,
+
+  // EventCatalog Pro Collections
+  customPages,
+  resourceDocs,
+  resourceDocCategories,
+
+  // EventCatalog Studio Collections
+  designs,
+
+  // Diagrams Collection
+  diagrams,
+
+  // Generated from message schema references
+  schemas,
+};
diff --git a/packages/core/eventcatalog/src/enterprise/LICENSE b/packages/core/eventcatalog/src/enterprise/LICENSE
new file mode 100644
index 000000000..2fa92dfe4
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/LICENSE
@@ -0,0 +1,57 @@
+The EventCatalog Commercial License (the "Commercial License")
+Copyright (c) 2022-2026 EventCatalog Ltd
+
+With regard to the EventCatalog Software:
+
+This software and associated documentation files (the "Software") may only be
+used in production, if you (and any entity that you represent) have agreed to,
+and are in compliance with, the EventCatalog Terms of Service available
+at https://www.eventcatalog.dev/terms, or other agreements governing the use of
+the Software, as mutually agreed by you and EventCatalog Ltd ("EventCatalog"),
+and otherwise have a valid EventCatalog Starter, Scale, or Enterprise
+subscription ("Commercial Subscription").
+
+Subject to the foregoing sentence, you are free to modify this Software and
+publish patches to the Software. You agree that EventCatalog and/or its
+licensors (as applicable) retain all right, title and interest in and to all
+such modifications and/or patches, and all such modifications and/or patches
+may only be used, copied, modified, displayed, distributed, or otherwise
+exploited with a valid Commercial Subscription.
+
+A 14-day free trial of premium features is available at
+https://eventcatalog.cloud/ to help you evaluate the Software before purchasing
+a Commercial Subscription.
+
+Notwithstanding the foregoing, you may copy and modify the Software for
+development and testing purposes, without requiring a subscription. You agree
+that EventCatalog and/or its licensors (as applicable) retain all right, title
+and interest in and to all such modifications. You are not granted any other
+rights beyond what is expressly stated herein. Subject to the foregoing, it is
+forbidden to copy, merge, publish, distribute, sublicense, and/or sell the
+Software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the Software, and you may not remove or obscure any functionality in the
+Software that is protected by the license key.
+
+This Software is source-available for the purposes of transparency and
+auditability. Source availability does not constitute a grant of rights to use
+the Software in production without a valid Commercial Subscription.
+
+This Commercial License applies only to the part of this Software that is not
+distributed under the MIT license. Any part of this Software distributed under
+the MIT license is copyrighted under the MIT license. The full text of this
+Commercial License shall be included in all copies or substantial portions of
+the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+For all third party components incorporated into the EventCatalog Software,
+those components are licensed under the original license provided by the owner
+of the applicable component.
diff --git a/eventcatalog/src/enterprise/README.md b/packages/core/eventcatalog/src/enterprise/README.md
similarity index 100%
rename from eventcatalog/src/enterprise/README.md
rename to packages/core/eventcatalog/src/enterprise/README.md
diff --git a/packages/core/eventcatalog/src/enterprise/ai/chat-api.ts b/packages/core/eventcatalog/src/enterprise/ai/chat-api.ts
new file mode 100644
index 000000000..c7e13f56c
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/ai/chat-api.ts
@@ -0,0 +1,442 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { APIContext } from 'astro';
+import { convertToModelMessages, stepCountIs, streamText, tool, type LanguageModel, type ModelMessage, type UIMessage } from 'ai';
+import { join } from 'node:path';
+import { isEventCatalogScaleEnabled, isEventCatalogStarterEnabled } from '@utils/feature';
+import { getCollection, getEntry } from 'astro:content';
+import { z } from 'astro/zod';
+import { getConsumersOfMessage, getProducersOfMessage } from '@utils/collections/services';
+import {
+  getResources as getResourcesImpl,
+  getResource as getResourceImpl,
+  getMessagesProducedOrConsumedByResource as getMessagesImpl,
+  getSchemaForResource as getSchemaImpl,
+  getDataProductInputs as getDataProductInputsImpl,
+  getDataProductOutputs as getDataProductOutputsImpl,
+  getArchitectureDiagramAsMermaid as getArchitectureDiagramImpl,
+  getCustomDocs as getCustomDocsImpl,
+  searchCustomDocs as searchCustomDocsImpl,
+  getCustomDoc as getCustomDocImpl,
+  collectionSchema,
+  resourceCollectionSchema,
+  messageCollectionSchema,
+  visualiserCollectionSchema,
+  toolDescriptions,
+} from '@enterprise/tools/catalog-tools';
+
+const catalogDirectory = process.env.PROJECT_DIR || process.cwd();
+
+export const defaultConfiguration = {
+  temperature: 0.4,
+  topP: 0.9,
+  topK: 40,
+  frequencyPenalty: 0.1,
+  presencePenalty: 0.0,
+  maxTokens: 1000,
+};
+
+let hasChatConfiguration = false;
+let model: LanguageModel;
+let modelConfiguration: any;
+let extendedTools: any;
+
+const hasAssistantPlan = () => isEventCatalogStarterEnabled() || isEventCatalogScaleEnabled();
+
+try {
+  const providerConfiguration = await import(/* @vite-ignore */ join(catalogDirectory, 'eventcatalog.chat.js'));
+  model = await providerConfiguration.default();
+  modelConfiguration = providerConfiguration.configuration || defaultConfiguration;
+  hasChatConfiguration = true;
+
+  if (isEventCatalogScaleEnabled()) {
+    extendedTools = providerConfiguration.tools || {};
+  }
+} catch (error) {
+  console.error('[Chat] Error loading chat configuration', error);
+  hasChatConfiguration = false;
+}
+
+// Built-in tools metadata for client visibility
+const builtInToolsMetadata = [
+  {
+    name: 'getResources',
+    description: 'Get events, services, commands, queries, flows, domains, systems, channels, entities from EventCatalog',
+  },
+  { name: 'getResource', description: 'Get a specific resource by its id and version' },
+  { name: 'getProducersAndConsumersFromSchema', description: 'Get the producers and consumers for a schema' },
+  { name: 'getMessagesProducedOrConsumedByResource', description: 'Get messages produced or consumed by a resource' },
+  { name: 'getProducerAndConsumerForMessage', description: 'Get the producers and consumers for a message' },
+  { name: 'getConsumersOfMessage', description: 'Get the consumers for a message' },
+  { name: 'getSchemaForResource', description: 'Get the schema or specifications (OpenAPI, AsyncAPI, GraphQL) for a resource' },
+  { name: 'getDataProductInputs', description: 'Get the inputs (resources consumed) for a data product' },
+  { name: 'getDataProductOutputs', description: 'Get the outputs (resources produced) for a data product with data contracts' },
+  { name: 'getArchitectureDiagramAsMermaid', description: 'Get the architecture diagram for a resource as Mermaid code' },
+  { name: 'getCustomDocs', description: 'List custom documentation pages (guides, runbooks, architecture notes)' },
+  { name: 'searchCustomDocs', description: 'Search the full text of custom documentation pages' },
+  { name: 'getCustomDoc', description: 'Get the markdown content of a custom documentation page' },
+];
+
+// Get extended tools metadata from user configuration
+const getExtendedToolsMetadata = () => {
+  if (!extendedTools || typeof extendedTools !== 'object') return [];
+  return Object.entries(extendedTools).map(([name, toolConfig]: [string, any]) => ({
+    name,
+    description: toolConfig?.description || 'Custom tool',
+    isCustom: true,
+  }));
+};
+
+const getBaseSystemPrompt = (
+  referrer: string
+) => `You are an expert in software architecture and domain-driven design, specializing in the open source tool EventCatalog.
+
+You assist developers, architects, and business stakeholders who need information about their software architecture catalog.
+
+There are many different resource types in EventCatalog, including:
+- Events (collection name 'events') (asynchronous messages that notify about something that has happened)
+  - example docs url: /docs/events/MyEvent/1.0.0
+- Commands (collection name 'commands') (requests to perform an action)
+  - example docs url: /docs/commands/MyCommand/1.0.0
+- Queries (collection name 'queries') (requests for information)
+  - example docs url: /docs/queries/MyQuery/1.0.0
+- Services (collection name 'services') (bounded contexts or applications that produce/consume events)
+  - example docs url: /docs/services/MyService/1.0.0
+- Domains (collection name 'domains') (business capabilities or functional areas)
+  - example docs url: /docs/domains/MyDomain/1.0.0
+- Systems (collection name 'systems') (business capabilities or functional areas)
+  - example docs url: /docs/systems/MySystem/1.0.0
+- Flows (collection name 'flows') (state machines)
+  - example docs url: /docs/flows/MyFlow/1.0.0
+- Channels (collection name 'channels') (communication channels)
+  - example docs url: /docs/channels/MyChannel/1.0.0
+- Entities (collection name 'entities') (data objects)
+  - example docs url: /docs/entities/MyEntity/1.0.0
+- Containers (collection name 'containers') (at the moment these are data stores (databases))
+  - example docs url: /docs/containers/MyContainer/1.0.0
+- Data Products (collection name 'data-products') (data products that have inputs and outputs, and may have data contracts)
+  - example docs url: /docs/data-products/MyDataProduct/1.0.0
+
+The user will ask you some questions about the software architecture catalog, you should use the tools provided to you to get the information they need.
+
+At point the referer url (${referrer}) will be the URL of the page the user is on, you should use this to help you answer the question,
+You may be able to get the resource from the URL
+  - Example if the url is like /docs|visualiser|architecture/{collection}/{id}/{version} 
+    - (e.g /docs/events/MyEvent/1.0.0) in this case the id is MyEvent and the version is 1.0.0 and collection is events.
+    - (e.g /visualiser/domains/MyDomain/1.0.0) in this case the id is MyDomain and the version is 1.0.0 and collection is domains.
+    - (e.g /architecture/services/MyService/1.0.0) in this case the id is MyService and the version is 1.0.0 and collection is services.
+
+The referer URL is: ${referrer}
+
+IMPORTANT: When the user is on a visualiser page (/visualiser/*) or asks about architecture, dependencies, data flow, or connections:
+- Use the getArchitectureDiagramAsMermaid tool to fetch the architecture diagram
+- The mermaid code shows all the connections between resources (services, events, channels, etc.)
+- Use this to provide accurate, contextual answers about the architecture
+
+Sometimes the user will be on the specification page (openapi, asyncapi, graphql) for a resource too 
+- /docs/services/OrdersService/0.0.3/asyncapi/order-service-asyncapi -> id: OrdersService, version: 0.0.3, collection: services, schema (specification): asyncapi
+- /docs/services/OrdersService/0.0.3/spec/openapi-v2 -> id: OrdersService, version: 0.0.3, collection: services, schema (specification): openapi
+
+Your primary goal is to help users understand their software architecture through accurate documentation interpretation.
+
+Use the tools provided to get the context you need to an answer the question.
+
+When responding:
+1.  Explain connections between resources when relevant.
+2. Use appropriate technical terminology.
+3. Use clear formatting with headings and bullet points when helpful.
+4. State clearly when information is missing rather than making assumptions.
+5. Don't provide code examples unless specifically requested.
+6. When you refer to a resource in EventCatalog, try and create a link to the resource in the response
+    - Example, if you return a message in the text, rather than than just the id or version you should return a markdown link to the resource e.g [MyEvent - 1.0.0](/docs/events/MyEvent/1.0.0)
+    - CRITICAL: NEVER use "latest" in any URL or link. Always use the actual semantic version number (e.g., 1.0.0, 2.1.3). The word "latest" is not a valid version and will result in broken links.
+    - The link options are:
+        - If you want to get the documentation for a resource use the /docs/ prefix (e.g /docs/{collection}/{id}/{version})
+        - If you want to let the user know they can visualize a resource use the /visualiser/ prefix (e.g /visualiser/{collection}/{id}/{version})
+        - If you want to let the user know they can see the architecture of a resource use the /architecture/ prefix (e.g /architecture/{collection}/{id}/{version})
+    - If you don't know the version, use the getResource tool to fetch the resource and get the actual version number before creating the link.
+7. When you return a schema, use code blocks to render the schema to the user too, for example if the schema is in JSON format use \`\`\`json and if the schema is in YAML format use \`\`\`yaml
+8. IMPORTANT: After answering each question, ALWAYS use the suggestFollowUpQuestions tool to suggest 2-3 relevant follow-up questions the user might want to ask next. These should be contextual to the conversation and help the user explore related topics.
+
+If you have additional context, use it to answer the question.`;
+
+interface Message {
+  content: string;
+}
+
+export const GET = async ({ request }: APIContext<{ question: string; messages: Message[]; additionalContext?: string }>) => {
+  if (!hasAssistantPlan()) {
+    return new Response(JSON.stringify({ error: 'Chat is not enabled' }), {
+      status: 403,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  if (!hasChatConfiguration) {
+    return new Response(JSON.stringify({ error: 'No chat configuration found' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  // Return available tools metadata
+  const tools = [...builtInToolsMetadata, ...getExtendedToolsMetadata()];
+  return new Response(JSON.stringify({ tools }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  });
+};
+
+export const POST = async ({ request }: APIContext<{ question: string; messages: Message[]; additionalContext?: string }>) => {
+  const { messages }: { messages: UIMessage[] } = await request.json();
+
+  if (!hasAssistantPlan()) {
+    return new Response(JSON.stringify({ error: 'Chat is not enabled, please upgrade to a paid plan to use this feature' }), {
+      status: 403,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  if (!hasChatConfiguration) {
+    return new Response(JSON.stringify({ error: 'No chat configuration found' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  // Get the URL of the request
+  const referrer = request.headers.get('referer');
+
+  try {
+    const result = await streamText({
+      model,
+      system: getBaseSystemPrompt(referrer ?? ''),
+      messages: await convertToModelMessages(messages),
+      temperature: modelConfiguration?.temperature ?? 0.7,
+      stopWhen: stepCountIs(5),
+      // maxTokens: 4000, // Increased to handle large tool results
+      onError: (error) => {
+        console.error('[Chat] On error', error);
+      },
+      // maxOutputTokens: 40000,
+      // tools: tools,
+      tools: {
+        getResources: tool({
+          description: toolDescriptions.getResources,
+          inputSchema: z.object({
+            collection: collectionSchema.describe('The collection to get the resources from'),
+          }),
+          execute: async ({ collection }) => {
+            const result = await getResourcesImpl({ collection });
+            if ('error' in result) return result;
+            return result.resources;
+          },
+        }),
+        getResource: tool({
+          description: toolDescriptions.getResource,
+          inputSchema: z.object({
+            collection: collectionSchema.describe('The collection to get the resource from'),
+            id: z.string().describe('The id of the resource to get'),
+            version: z.string().describe('The version of the resource to get'),
+          }),
+          execute: async ({ collection, id, version }) => {
+            return await getResourceImpl({ collection, id, version });
+          },
+        }),
+        getProducersAndConsumersFromSchema: tool({
+          description: 'Use this tool to get the producers and consumers for a schema by its id and version',
+          inputSchema: z.object({
+            collection: messageCollectionSchema.describe('The collection to get the producers and consumers from'),
+            id: z.string().describe('The id of the message to get the producers and consumers for'),
+            version: z.string().describe('The version of the message to get the producers and consumers for'),
+          }),
+          execute: async ({ collection, id, version }) => {
+            const resource = await getEntry(collection as any, `${id}-${version}`);
+            const producers = resource.data.producers || [];
+            const consumers = resource.data.consumers || [];
+            return {
+              producers,
+              consumers,
+            };
+          },
+        }),
+        getMessagesProducedOrConsumedByResource: tool({
+          description: toolDescriptions.getMessagesProducedOrConsumedByResource,
+          inputSchema: z.object({
+            resourceId: z.string().describe('The id of the resource to get the messages produced or consumed for'),
+            resourceVersion: z.string().describe('The version of the resource to get the messages produced or consumed for'),
+            resourceCollection: resourceCollectionSchema
+              .describe('The collection of the resource to get the messages produced or consumed for')
+              .default('services'),
+          }),
+          execute: async ({ resourceId, resourceVersion, resourceCollection }) => {
+            return await getMessagesImpl({ resourceId, resourceVersion, resourceCollection });
+          },
+        }),
+        getProducerAndConsumerForMessage: tool({
+          description: 'Use this tool to get the producers and consumers for a message by its id and version',
+          inputSchema: z.object({
+            messageId: z.string().describe('The id of the message to get the producers and consumers for'),
+            messageVersion: z.string().describe('The version of the message to get the producers and consumers for'),
+            messageCollection: messageCollectionSchema
+              .describe('The collection of the message to get the producers and consumers for')
+              .default('events'),
+          }),
+          execute: async ({ messageId, messageVersion, messageCollection }) => {
+            const services = await getCollection('services');
+            const message = await getEntry(messageCollection as any, `${messageId}-${messageVersion}`);
+            const consumers = await getProducersOfMessage(services, message as any);
+            return consumers;
+          },
+        }),
+        getConsumersOfMessage: tool({
+          description: 'Use this tool to get the consumers for a message by its id and version',
+          inputSchema: z.object({
+            messageId: z.string().describe('The id of the message to get the consumers for'),
+            messageVersion: z.string().describe('The version of the message to get the consumers for'),
+            messageCollection: messageCollectionSchema
+              .describe('The collection of the message to get the consumers for')
+              .default('events'),
+          }),
+          execute: async ({ messageId, messageVersion, messageCollection }) => {
+            const services = await getCollection('services');
+            const message = await getEntry(messageCollection as any, `${messageId}-${messageVersion}`);
+            const consumers = await getConsumersOfMessage(services, message as any);
+            return consumers;
+          },
+        }),
+        getSchemaForResource: tool({
+          description: toolDescriptions.getSchemaForResource,
+          inputSchema: z.object({
+            resourceId: z.string().describe('The id of the resource to get the schema for'),
+            resourceVersion: z.string().describe('The version of the resource to get the schema for'),
+            resourceCollection: resourceCollectionSchema
+              .describe('The collection of the resource to get the schema for')
+              .default('services'),
+          }),
+          execute: async ({ resourceId, resourceVersion, resourceCollection }) => {
+            return await getSchemaImpl({ resourceId, resourceVersion, resourceCollection });
+          },
+        }),
+        getDataProductInputs: tool({
+          description: toolDescriptions.getDataProductInputs,
+          inputSchema: z.object({
+            dataProductId: z.string().describe('The id of the data product to get the inputs for'),
+            dataProductVersion: z.string().describe('The version of the data product to get the inputs for'),
+          }),
+          execute: async ({ dataProductId, dataProductVersion }) => {
+            return await getDataProductInputsImpl({ dataProductId, dataProductVersion });
+          },
+        }),
+        getDataProductOutputs: tool({
+          description: toolDescriptions.getDataProductOutputs,
+          inputSchema: z.object({
+            dataProductId: z.string().describe('The id of the data product to get the outputs for'),
+            dataProductVersion: z.string().describe('The version of the data product to get the outputs for'),
+          }),
+          execute: async ({ dataProductId, dataProductVersion }) => {
+            return await getDataProductOutputsImpl({ dataProductId, dataProductVersion });
+          },
+        }),
+        getArchitectureDiagramAsMermaid: tool({
+          description: toolDescriptions.getArchitectureDiagramAsMermaid,
+          inputSchema: z.object({
+            resourceId: z.string().describe('The id of the resource to get the architecture diagram for'),
+            resourceVersion: z.string().describe('The version of the resource to get the architecture diagram for'),
+            resourceCollection: visualiserCollectionSchema
+              .describe(
+                'The collection of the resource (events, commands, queries, services, domains, systems, flows, containers, data-products)'
+              )
+              .default('services'),
+          }),
+          execute: async ({ resourceId, resourceVersion, resourceCollection }) => {
+            return await getArchitectureDiagramImpl({ resourceId, resourceVersion, resourceCollection });
+          },
+        }),
+        getCustomDocs: tool({
+          description: toolDescriptions.getCustomDocs,
+          inputSchema: z.object({
+            cursor: z.string().optional().describe('Pagination cursor from previous response'),
+            search: z.string().optional().describe('Search term to filter docs by title, id, or summary (case-insensitive)'),
+          }),
+          execute: async ({ cursor, search }) => {
+            return await getCustomDocsImpl({ cursor, search });
+          },
+        }),
+        searchCustomDocs: tool({
+          description: toolDescriptions.searchCustomDocs,
+          inputSchema: z.object({
+            query: z.string().describe('Full-text search query, e.g. keywords describing the topic to find'),
+            limit: z.number().optional().describe('Maximum number of results to return (default 10)'),
+          }),
+          execute: async ({ query, limit }) => {
+            return await searchCustomDocsImpl({ query, limit });
+          },
+        }),
+        getCustomDoc: tool({
+          description: toolDescriptions.getCustomDoc,
+          inputSchema: z.object({
+            id: z.string().describe('The id or slug of the custom documentation page'),
+            section: z.string().optional().describe('Optional section heading to return only that section of the page'),
+          }),
+          execute: async ({ id, section }) => {
+            return await getCustomDocImpl({ id, section });
+          },
+        }),
+        suggestFollowUpQuestions: tool({
+          description:
+            'Use this tool after answering a question to suggest 2-3 relevant follow-up questions the user might want to ask. These will be displayed as clickable suggestions.',
+          inputSchema: z.object({
+            questions: z
+              .array(z.string())
+              .min(1)
+              .max(3)
+              .describe('Array of 2-3 follow-up questions relevant to the conversation'),
+          }),
+          execute: async ({ questions }) => {
+            // This tool doesn't need to do anything - it just returns the questions
+            // which will be captured by the UI
+            return { suggestions: questions };
+          },
+        }),
+        ...extendedTools,
+      },
+    });
+    return result.toUIMessageStreamResponse({
+      headers: {
+        'Content-Type': 'text/event-stream',
+      },
+    });
+  } catch (err: any) {
+    console.error('[Chat] Error during streaming:', err);
+
+    // Extract a user-friendly error message
+    let errorMessage = 'An unexpected error occurred while processing your request.';
+
+    if (err?.message) {
+      // Check for common error patterns and provide friendlier messages
+      if (err.message.includes('API key') || err.message.includes('authentication') || err.message.includes('401')) {
+        errorMessage = 'Authentication error: Please check your API key configuration.';
+      } else if (err.message.includes('rate limit') || err.message.includes('429')) {
+        errorMessage = 'Rate limit exceeded. Please wait a moment and try again.';
+      } else if (err.message.includes('timeout') || err.message.includes('ETIMEDOUT')) {
+        errorMessage = 'Request timed out. Please try again.';
+      } else if (err.message.includes('model') || err.message.includes('not found')) {
+        errorMessage = 'Model configuration error: ' + err.message;
+      } else {
+        // Use the original message if it's not too technical
+        errorMessage = err.message.length < 200 ? err.message : 'An error occurred while processing your request.';
+      }
+    }
+
+    return new Response(JSON.stringify({ error: errorMessage }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+};
+
+export const prerender = false;
diff --git a/packages/core/eventcatalog/src/enterprise/analytics/__tests__/tracker.test.ts b/packages/core/eventcatalog/src/enterprise/analytics/__tests__/tracker.test.ts
new file mode 100644
index 000000000..5475854c2
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/analytics/__tests__/tracker.test.ts
@@ -0,0 +1,198 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import { describe, it, expect } from 'vitest';
+import { extractPageProperties, AnalyticsManager } from '../tracker';
+
+describe('extractPageProperties', () => {
+  it('extracts service doc page properties', () => {
+    const result = extractPageProperties('/docs/services/OrderService/1.0.0');
+    expect(result).toEqual({
+      url: '/docs/services/OrderService/1.0.0',
+      section: 'docs',
+      resource_type: 'service',
+      resource_id: 'OrderService',
+      resource_version: '1.0.0',
+    });
+  });
+
+  it('extracts event doc page properties', () => {
+    const result = extractPageProperties('/docs/events/OrderCreated/2.1.0');
+    expect(result).toEqual({
+      url: '/docs/events/OrderCreated/2.1.0',
+      section: 'docs',
+      resource_type: 'event',
+      resource_id: 'OrderCreated',
+      resource_version: '2.1.0',
+    });
+  });
+
+  it('extracts visualiser page properties', () => {
+    const result = extractPageProperties('/visualiser/services/OrderService/1.0.0');
+    expect(result).toEqual({
+      url: '/visualiser/services/OrderService/1.0.0',
+      section: 'visualiser',
+      resource_type: 'service',
+      resource_id: 'OrderService',
+      resource_version: '1.0.0',
+    });
+  });
+
+  it('extracts discover page properties', () => {
+    const result = extractPageProperties('/discover/events');
+    expect(result).toEqual({
+      url: '/discover/events',
+      section: 'discover',
+      resource_type: 'event',
+    });
+  });
+
+  it('extracts directory page properties', () => {
+    const result = extractPageProperties('/directory/users');
+    expect(result).toEqual({
+      url: '/directory/users',
+      section: 'directory',
+    });
+  });
+
+  it('extracts schemas page properties', () => {
+    const result = extractPageProperties('/schemas/explorer');
+    expect(result).toEqual({
+      url: '/schemas/explorer',
+      section: 'schemas',
+    });
+  });
+
+  it('extracts home page properties', () => {
+    const result = extractPageProperties('/');
+    expect(result).toEqual({
+      url: '/',
+      section: 'home',
+    });
+  });
+
+  it('extracts custom docs page properties', () => {
+    const result = extractPageProperties('/docs/custom/guides/getting-started');
+    expect(result).toEqual({
+      url: '/docs/custom/guides/getting-started',
+      section: 'custom-docs',
+    });
+  });
+
+  it('handles command pages', () => {
+    const result = extractPageProperties('/docs/commands/CreateOrder/1.0.0');
+    expect(result).toEqual({
+      url: '/docs/commands/CreateOrder/1.0.0',
+      section: 'docs',
+      resource_type: 'command',
+      resource_id: 'CreateOrder',
+      resource_version: '1.0.0',
+    });
+  });
+
+  it('handles domain pages', () => {
+    const result = extractPageProperties('/docs/domains/Payment/1.0.0');
+    expect(result).toEqual({
+      url: '/docs/domains/Payment/1.0.0',
+      section: 'docs',
+      resource_type: 'domain',
+      resource_id: 'Payment',
+      resource_version: '1.0.0',
+    });
+  });
+
+  it('handles URL-encoded resource IDs', () => {
+    const result = extractPageProperties('/docs/services/Order%20Service/1.0.0');
+    expect(result).toEqual({
+      url: '/docs/services/Order%20Service/1.0.0',
+      section: 'docs',
+      resource_type: 'service',
+      resource_id: 'Order Service',
+      resource_version: '1.0.0',
+    });
+  });
+
+  it('handles unknown pages', () => {
+    const result = extractPageProperties('/some/unknown/page');
+    expect(result).toEqual({
+      url: '/some/unknown/page',
+      section: 'other',
+    });
+  });
+});
+
+describe('AnalyticsManager', () => {
+  it('calls track on all registered adapters', () => {
+    const manager = new AnalyticsManager();
+    const calls: string[] = [];
+
+    manager.register({
+      name: 'test1',
+      track: (event) => calls.push(`test1:${event}`),
+      pageView: () => {},
+    });
+    manager.register({
+      name: 'test2',
+      track: (event) => calls.push(`test2:${event}`),
+      pageView: () => {},
+    });
+
+    manager.track('catalog.page.view', { section: 'docs' });
+
+    expect(calls).toEqual(['test1:catalog.page.view', 'test2:catalog.page.view']);
+  });
+
+  it('calls pageView on all registered adapters', () => {
+    const manager = new AnalyticsManager();
+    const calls: string[] = [];
+
+    manager.register({
+      name: 'test1',
+      track: () => {},
+      pageView: (url) => calls.push(`test1:${url}`),
+    });
+
+    manager.pageView('/docs/services/OrderService/1.0.0', { section: 'docs' });
+
+    expect(calls).toEqual(['test1:/docs/services/OrderService/1.0.0']);
+  });
+
+  it('silently catches adapter errors', () => {
+    const manager = new AnalyticsManager();
+    const calls: string[] = [];
+
+    manager.register({
+      name: 'broken',
+      track: () => {
+        throw new Error('broken');
+      },
+      pageView: () => {},
+    });
+    manager.register({
+      name: 'working',
+      track: (event) => calls.push(event),
+      pageView: () => {},
+    });
+
+    manager.track('test.event');
+
+    expect(calls).toEqual(['test.event']);
+  });
+
+  it('logs events when debug is enabled', () => {
+    const manager = new AnalyticsManager({ debug: true });
+    const logs: string[] = [];
+    const originalLog = console.log;
+    console.log = (...args: any[]) => logs.push(args[0]);
+
+    manager.track('test.event', { key: 'value' });
+    manager.pageView('/test', { section: 'docs' });
+
+    console.log = originalLog;
+
+    expect(logs).toContain('[EventCatalog Analytics] track: test.event');
+    expect(logs).toContain('[EventCatalog Analytics] pageView: /test');
+  });
+});
diff --git a/packages/core/eventcatalog/src/enterprise/analytics/adapters/ga4.ts b/packages/core/eventcatalog/src/enterprise/analytics/adapters/ga4.ts
new file mode 100644
index 000000000..97c091490
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/analytics/adapters/ga4.ts
@@ -0,0 +1,26 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { AnalyticsAdapter, EventProperties } from '../tracker';
+
+declare global {
+  interface Window {
+    gtag?: (...args: any[]) => void;
+  }
+}
+
+export const ga4Adapter: AnalyticsAdapter = {
+  name: 'ga4',
+  track(event: string, properties?: EventProperties) {
+    if (typeof window !== 'undefined' && typeof window.gtag === 'function') {
+      window.gtag('event', event, properties);
+    }
+  },
+  pageView(url: string, properties?: EventProperties) {
+    if (typeof window !== 'undefined' && typeof window.gtag === 'function') {
+      window.gtag('event', 'page_view', { page_location: url, ...properties });
+    }
+  },
+};
diff --git a/packages/core/eventcatalog/src/enterprise/analytics/adapters/gtm.ts b/packages/core/eventcatalog/src/enterprise/analytics/adapters/gtm.ts
new file mode 100644
index 000000000..4bef53a80
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/analytics/adapters/gtm.ts
@@ -0,0 +1,26 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { AnalyticsAdapter, EventProperties } from '../tracker';
+
+declare global {
+  interface Window {
+    dataLayer?: Record<string, any>[];
+  }
+}
+
+export const gtmAdapter: AnalyticsAdapter = {
+  name: 'gtm',
+  track(event: string, properties?: EventProperties) {
+    if (typeof window !== 'undefined' && window.dataLayer) {
+      window.dataLayer.push({ event, ...properties });
+    }
+  },
+  pageView(url: string, properties?: EventProperties) {
+    if (typeof window !== 'undefined' && window.dataLayer) {
+      window.dataLayer.push({ event: 'page_view', page_location: url, ...properties });
+    }
+  },
+};
diff --git a/packages/core/eventcatalog/src/enterprise/analytics/adapters/posthog.ts b/packages/core/eventcatalog/src/enterprise/analytics/adapters/posthog.ts
new file mode 100644
index 000000000..08b25c9d5
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/analytics/adapters/posthog.ts
@@ -0,0 +1,28 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { AnalyticsAdapter, EventProperties } from '../tracker';
+
+declare global {
+  interface Window {
+    posthog?: {
+      capture: (event: string, properties?: Record<string, any>) => void;
+    };
+  }
+}
+
+export const posthogAdapter: AnalyticsAdapter = {
+  name: 'posthog',
+  track(event: string, properties?: EventProperties) {
+    if (typeof window !== 'undefined' && window.posthog) {
+      window.posthog.capture(event, properties);
+    }
+  },
+  pageView(url: string, properties?: EventProperties) {
+    if (typeof window !== 'undefined' && window.posthog) {
+      window.posthog.capture('$pageview', { $current_url: url, ...properties });
+    }
+  },
+};
diff --git a/packages/core/eventcatalog/src/enterprise/analytics/components/AnalyticsHead.astro b/packages/core/eventcatalog/src/enterprise/analytics/components/AnalyticsHead.astro
new file mode 100644
index 000000000..dddad5e72
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/analytics/components/AnalyticsHead.astro
@@ -0,0 +1,186 @@
+---
+import config from '@config';
+import { isIntegrationsEnabled } from '@utils/feature';
+
+const integrations = config.integrations;
+const cloudAnalytics = config.cloud?.analytics;
+const enabled = isIntegrationsEnabled() && integrations;
+const hasProviders = enabled && (integrations?.ga4 || integrations?.gtm || integrations?.posthog);
+const debug = integrations?.debug ?? false;
+const cloudDebug = cloudAnalytics?.debug ?? debug;
+const cloudAnalyticsEndpoint = cloudAnalytics?.endpoint || 'https://api.ecingest.dev/v1/analytics/ingest';
+const isCloudAnalyticsEnabled = cloudAnalytics?.enabled === true && !!cloudAnalytics?.trackingId;
+// Render the manager if there are providers OR if debug mode is on (so users can verify the pipeline)
+const shouldRender = isCloudAnalyticsEnabled || (enabled && (hasProviders || debug));
+
+// Build script contents in frontmatter to avoid Prettier/JSX parsing issues with braces in inline scripts
+const ga4ConfigScript = integrations?.ga4
+  ? `window.dataLayer = window.dataLayer || [];
+function gtag(){dataLayer.push(arguments);}
+gtag('js', new Date());
+gtag('config', ${JSON.stringify(integrations.ga4.measurementId)}, { send_page_view: false });`
+  : '';
+
+const gtmScript = integrations?.gtm
+  ? `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
+j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
+'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+})(window,document,'script','dataLayer',${JSON.stringify(integrations.gtm.tagId)});`
+  : '';
+
+const posthogApiKey = JSON.stringify(integrations?.posthog?.apiKey || '');
+const posthogApiHost = JSON.stringify(integrations?.posthog?.apiHost || 'https://us.i.posthog.com');
+const posthogScript = integrations?.posthog
+  ? `!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="init capture register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey identify".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
+posthog.init(${posthogApiKey}, {api_host: ${posthogApiHost}, person_profiles: 'identified_only'});`
+  : '';
+
+const hasGA4 = !!integrations?.ga4;
+const hasGTM = !!integrations?.gtm;
+const hasPostHog = !!integrations?.posthog;
+const hasCloudAnalytics = !!isCloudAnalyticsEnabled;
+
+const managerScript = `(function() {
+function AnalyticsManager(opts) {
+  this.adapters = [];
+  this.debug = opts && opts.debug;
+}
+AnalyticsManager.prototype.register = function(adapter) {
+  this.adapters.push(adapter);
+  if (this.debug) console.log('[EventCatalog Analytics] Registered adapter: ' + adapter.name);
+};
+AnalyticsManager.prototype.track = function(event, props) {
+  if (this.debug) console.log('[EventCatalog Analytics] track: ' + event, props);
+  for (var i = 0; i < this.adapters.length; i++) {
+    try { this.adapters[i].track(event, props); } catch(e) {}
+  }
+};
+AnalyticsManager.prototype.pageView = function(url, props) {
+  if (this.debug) console.log('[EventCatalog Analytics] pageView: ' + url, props);
+  for (var i = 0; i < this.adapters.length; i++) {
+    try { this.adapters[i].pageView(url, props); } catch(e) {}
+  }
+};
+function createId(prefix) {
+  var bytes = new Uint8Array(16);
+  if (window.crypto && window.crypto.getRandomValues) {
+    window.crypto.getRandomValues(bytes);
+  } else {
+    for (var i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  return prefix + '_' + Array.prototype.map.call(bytes, function(byte) {
+    return byte.toString(16).padStart(2, '0');
+  }).join('');
+}
+function getStoredId(storage, key, prefix) {
+  try {
+    var existing = storage.getItem(key);
+    if (existing) return existing;
+    var id = createId(prefix);
+    storage.setItem(key, id);
+    return id;
+  } catch(e) {
+    return createId(prefix);
+  }
+}
+var manager = new AnalyticsManager({ debug: ${debug} });
+${
+  hasGA4
+    ? `manager.register({
+  name: 'ga4',
+  track: function(event, props) { if (typeof gtag === 'function') gtag('event', event, props); },
+  pageView: function(url, props) { if (typeof gtag === 'function') gtag('event', 'page_view', Object.assign({ page_location: url }, props || {})); }
+});`
+    : ''
+}
+${
+  hasGTM
+    ? `manager.register({
+  name: 'gtm',
+  track: function(event, props) { if (window.dataLayer) window.dataLayer.push(Object.assign({ event: event }, props || {})); },
+  pageView: function(url, props) { if (window.dataLayer) window.dataLayer.push(Object.assign({ event: 'page_view', page_location: url }, props || {})); }
+});`
+    : ''
+}
+${
+  hasPostHog
+    ? `manager.register({
+  name: 'posthog',
+  track: function(event, props) { if (window.posthog) window.posthog.capture(event, props); },
+  pageView: function(url, props) { if (window.posthog) window.posthog.capture('$pageview', Object.assign({ '$current_url': url }, props || {})); }
+});`
+    : ''
+}
+${
+  hasCloudAnalytics
+    ? `var eventCatalogCloudLastPath;
+manager.register({
+  name: 'eventcatalog-cloud',
+  track: function(event, props) {
+    if (event !== 'catalog.page_viewed' && event !== 'catalog.built' && event !== 'catalog.resource_inventory_reported') return;
+
+    var payload = Object.assign({
+      trackingId: ${JSON.stringify(cloudAnalytics?.trackingId || '')},
+      event: event,
+      anonymousId: getStoredId(window.localStorage, 'eventcatalog-cloud-anonymous-id', 'anon'),
+      sessionId: getStoredId(window.sessionStorage, 'eventcatalog-cloud-session-id', 'sess'),
+      timestamp: new Date().toISOString()
+    }, props || {});
+
+    var body = JSON.stringify(payload);
+    if (${cloudDebug}) console.log('[EventCatalog Cloud Analytics] track: ' + event, payload);
+
+    try {
+      fetch(${JSON.stringify(cloudAnalyticsEndpoint)}, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: body,
+        keepalive: true,
+        credentials: 'omit'
+      }).catch(function() {});
+    } catch(e) {}
+  },
+  pageView: function(url, props) {
+    props = props || {};
+    var path = props.url || url || window.location.pathname;
+    var payload = {
+      path: path,
+      section: props.section || undefined,
+      referrer: eventCatalogCloudLastPath || document.referrer || undefined
+    };
+    if (props.resource_type && props.resource_id) {
+      payload.resource = {
+        type: props.resource_type,
+        id: props.resource_id,
+        version: props.resource_version || undefined
+      };
+    }
+    eventCatalogCloudLastPath = path;
+    this.track('catalog.page_viewed', payload);
+  }
+});`
+    : ''
+}
+window.__ec_analytics = manager;
+})();`;
+---
+
+{
+  shouldRender && (
+    <>
+      {integrations?.ga4 && (
+        <>
+          <script is:inline src={`https://www.googletagmanager.com/gtag/js?id=${integrations.ga4.measurementId}`} async />
+          <script is:inline set:html={ga4ConfigScript} />
+        </>
+      )}
+
+      {integrations?.gtm && <script is:inline set:html={gtmScript} />}
+
+      {integrations?.posthog && <script is:inline set:html={posthogScript} />}
+
+      <script is:inline set:html={managerScript} />
+    </>
+  )
+}
diff --git a/packages/core/eventcatalog/src/enterprise/analytics/components/AnalyticsTracker.astro b/packages/core/eventcatalog/src/enterprise/analytics/components/AnalyticsTracker.astro
new file mode 100644
index 000000000..ccc2c1884
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/analytics/components/AnalyticsTracker.astro
@@ -0,0 +1,76 @@
+---
+import config from '@config';
+import { isIntegrationsEnabled } from '@utils/feature';
+
+const integrations = config.integrations;
+const cloudAnalytics = config.cloud?.analytics;
+const enabled = isIntegrationsEnabled() && integrations;
+const hasProviders = enabled && (integrations?.ga4 || integrations?.gtm || integrations?.posthog);
+const debug = integrations?.debug ?? false;
+const isCloudAnalyticsEnabled = cloudAnalytics?.enabled === true && !!cloudAnalytics?.trackingId;
+const shouldRender = isCloudAnalyticsEnabled || (enabled && (hasProviders || debug));
+
+const base = (config.base || '/').replace(/\/$/, '');
+const baseJson = JSON.stringify(base);
+
+const COLLECTION_TYPE_MAP_JSON = JSON.stringify({
+  services: 'service',
+  events: 'event',
+  commands: 'command',
+  queries: 'query',
+  domains: 'domain',
+  flows: 'flow',
+  channels: 'channel',
+  entities: 'entity',
+});
+
+const trackerScript = `(function() {
+var BASE_PATH = ${baseJson};
+var COLLECTION_TYPE_MAP = ${COLLECTION_TYPE_MAP_JSON};
+var SECTION_PATTERNS = [
+  [/^\\/visualiser/, 'visualiser'],
+  [/^\\/discover/, 'discover'],
+  [/^\\/directory/, 'directory'],
+  [/^\\/schemas/, 'schemas'],
+  [/^\\/docs\\/custom/, 'custom-docs'],
+  [/^\\/docs/, 'docs'],
+  [/^\\/$/, 'home']
+];
+
+function extractPageProperties(url) {
+  var properties = { url: url };
+  for (var i = 0; i < SECTION_PATTERNS.length; i++) {
+    if (SECTION_PATTERNS[i][0].test(url)) {
+      properties.section = SECTION_PATTERNS[i][1];
+      break;
+    }
+  }
+  if (!properties.section) properties.section = 'other';
+  var parts = url.split('/').filter(Boolean);
+  for (var j = 0; j < parts.length; j++) {
+    var collectionType = COLLECTION_TYPE_MAP[parts[j]];
+    if (collectionType) {
+      properties.resource_type = collectionType;
+      if (parts[j + 1]) properties.resource_id = decodeURIComponent(parts[j + 1]);
+      if (parts[j + 2]) properties.resource_version = parts[j + 2];
+      break;
+    }
+  }
+  return properties;
+}
+
+if (!window.__ec_tracker_initialized) {
+  window.__ec_tracker_initialized = true;
+  document.addEventListener('astro:page-load', function() {
+    if (window.__ec_analytics) {
+      var url = window.location.pathname;
+      var normalizedUrl = (BASE_PATH && url.indexOf(BASE_PATH) === 0) ? url.slice(BASE_PATH.length) || '/' : url;
+      var properties = extractPageProperties(normalizedUrl);
+      window.__ec_analytics.pageView(url, properties);
+    }
+  });
+}
+})();`;
+---
+
+{shouldRender && <script is:inline set:html={trackerScript} />}
diff --git a/packages/core/eventcatalog/src/enterprise/analytics/tracker.ts b/packages/core/eventcatalog/src/enterprise/analytics/tracker.ts
new file mode 100644
index 000000000..ff5c286e6
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/analytics/tracker.ts
@@ -0,0 +1,113 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+export type EventProperties = Record<string, string | number | boolean>;
+
+export interface AnalyticsAdapter {
+  name: string;
+  track(event: string, properties?: EventProperties): void;
+  pageView(url: string, properties?: EventProperties): void;
+}
+
+export class AnalyticsManager {
+  private adapters: AnalyticsAdapter[] = [];
+  private debug: boolean;
+
+  constructor(options?: { debug?: boolean }) {
+    this.debug = options?.debug ?? false;
+  }
+
+  register(adapter: AnalyticsAdapter) {
+    this.adapters.push(adapter);
+    if (this.debug) {
+      console.log(`[EventCatalog Analytics] Registered adapter: ${adapter.name}`);
+    }
+  }
+
+  track(event: string, properties?: EventProperties) {
+    if (this.debug) {
+      console.log(`[EventCatalog Analytics] track: ${event}`, properties);
+    }
+    for (const adapter of this.adapters) {
+      try {
+        adapter.track(event, properties);
+      } catch (e) {
+        // Silently fail — analytics should never break the app
+      }
+    }
+  }
+
+  pageView(url: string, properties?: EventProperties) {
+    if (this.debug) {
+      console.log(`[EventCatalog Analytics] pageView: ${url}`, properties);
+    }
+    for (const adapter of this.adapters) {
+      try {
+        adapter.pageView(url, properties);
+      } catch (e) {
+        // Silently fail
+      }
+    }
+  }
+}
+
+const COLLECTION_TYPE_MAP: Record<string, string> = {
+  services: 'service',
+  events: 'event',
+  commands: 'command',
+  queries: 'query',
+  domains: 'domain',
+  flows: 'flow',
+  channels: 'channel',
+  entities: 'entity',
+};
+
+const SECTION_PATTERNS: [RegExp, string][] = [
+  [/^\/visualiser/, 'visualiser'],
+  [/^\/discover/, 'discover'],
+  [/^\/directory/, 'directory'],
+  [/^\/schemas/, 'schemas'],
+  [/^\/docs\/custom/, 'custom-docs'],
+  [/^\/docs/, 'docs'],
+  [/^\/$/, 'home'],
+];
+
+export function extractPageProperties(url: string): EventProperties {
+  const properties: EventProperties = { url };
+
+  // Determine section
+  for (const [pattern, section] of SECTION_PATTERNS) {
+    if (pattern.test(url)) {
+      properties.section = section;
+      break;
+    }
+  }
+
+  if (!properties.section) {
+    properties.section = 'other';
+  }
+
+  // Extract resource info from URL patterns like:
+  // /docs/services/OrderService/1.0.0
+  // /visualiser/services/OrderService/1.0.0
+  // /discover/events
+  const parts = url.split('/').filter(Boolean);
+
+  for (let i = 0; i < parts.length; i++) {
+    const collectionType = COLLECTION_TYPE_MAP[parts[i]];
+    if (collectionType) {
+      properties.resource_type = collectionType;
+      if (parts[i + 1]) {
+        properties.resource_id = decodeURIComponent(parts[i + 1]);
+      }
+      if (parts[i + 2]) {
+        properties.resource_version = parts[i + 2];
+      }
+      break;
+    }
+  }
+
+  return properties;
+}
diff --git a/packages/core/eventcatalog/src/enterprise/api/catalog.ts b/packages/core/eventcatalog/src/enterprise/api/catalog.ts
new file mode 100644
index 000000000..76ae3df58
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/api/catalog.ts
@@ -0,0 +1,27 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { APIRoute } from 'astro';
+import utils from '@eventcatalog/sdk';
+import { isSSR } from '@utils/feature';
+
+/**
+ * Route that dumps the whole catalog as JSON (without markdown)
+ * Experimental API
+ *
+ * This route is injected only when `api.fullCatalogAPIEnabled` is true.
+ */
+export const GET: APIRoute = async () => {
+  const { dumpCatalog } = utils(process.env.PROJECT_DIR || '');
+  const catalog = await dumpCatalog({ includeMarkdown: false });
+
+  return new Response(JSON.stringify(catalog), {
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  });
+};
+
+export const prerender = !isSSR();
diff --git a/packages/core/eventcatalog/src/enterprise/api/schemas/[collection]/[id]/[version]/index.ts b/packages/core/eventcatalog/src/enterprise/api/schemas/[collection]/[id]/[version]/index.ts
new file mode 100644
index 000000000..229fe088d
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/api/schemas/[collection]/[id]/[version]/index.ts
@@ -0,0 +1,107 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import { isEventCatalogScaleEnabled } from '@utils/feature';
+import { sortVersioned } from '@utils/collections/util';
+
+const findSchema = async (collection: string | undefined, id: string, version: string | undefined) => {
+  const schemas = await getCollection('schemas');
+  const matchingSchemas = schemas.filter(
+    (schema) => schema.data.message.collection === collection && schema.data.message.id === id
+  );
+
+  if (version === 'latest') {
+    return (
+      matchingSchemas.find((schema) => schema.data.latest) ??
+      sortVersioned(matchingSchemas, (schema) => schema.data.message.version)[0]
+    );
+  }
+
+  return matchingSchemas.find((schema) => schema.data.message.version === version);
+};
+
+export async function getStaticPaths() {
+  const schemas = await getCollection('schemas');
+
+  // Generate paths for specific versions
+  const versionedPaths = schemas.map((schema) => ({
+    params: {
+      collection: schema.data.message.collection,
+      id: schema.data.message.id,
+      version: schema.data.message.version,
+    },
+    props: {
+      pathToSchema: schema.data.filePath,
+      schema: schema.data.content,
+    },
+  }));
+
+  // Generate "latest" paths for each unique collection/id combination
+  const latestPaths = schemas
+    .filter((schema) => schema.data.latest)
+    .map((latestSchema) => ({
+      params: {
+        collection: latestSchema.data.message.collection,
+        id: latestSchema.data.message.id,
+        version: 'latest',
+      },
+      props: {
+        pathToSchema: latestSchema.data.filePath,
+        schema: latestSchema.data.content,
+      },
+    }));
+
+  return [...versionedPaths, ...latestPaths];
+}
+
+export const GET: APIRoute = async ({ props, params }) => {
+  if (!isEventCatalogScaleEnabled()) {
+    return new Response(
+      JSON.stringify({
+        error: 'feature_not_available_on_server',
+        message: 'Schema API is not enabled for this deployment and supported in EventCatalog Scale.',
+      }),
+      {
+        status: 501,
+        headers: {
+          'Content-Type': 'application/json',
+          'Cache-Control': 'no-store',
+        },
+      }
+    );
+  }
+
+  // In static mode, props are pre-computed by getStaticPaths
+  if (props.schema !== undefined) {
+    return new Response(props.schema, {
+      headers: { 'Content-Type': 'text/plain' },
+    });
+  }
+
+  // In SSR mode, dynamically resolve the schema using the generated schema collection
+  const { collection, id, version } = params;
+
+  if (!id) {
+    return new Response(JSON.stringify({ error: 'Missing id parameter' }), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  const schema = await findSchema(collection, id, version);
+
+  if (schema?.data.content === undefined) {
+    return new Response(JSON.stringify({ error: 'Schema not found' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  return new Response(schema.data.content, {
+    headers: { 'Content-Type': 'text/plain' },
+  });
+};
diff --git a/packages/core/eventcatalog/src/enterprise/api/schemas/services/[id]/[version]/[specification]/index.ts b/packages/core/eventcatalog/src/enterprise/api/schemas/services/[id]/[version]/[specification]/index.ts
new file mode 100644
index 000000000..aa8501121
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/api/schemas/services/[id]/[version]/[specification]/index.ts
@@ -0,0 +1,104 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import path from 'node:path';
+import fs from 'node:fs';
+import { getSpecificationsForService } from '@utils/collections/services';
+import { isEventCatalogScaleEnabled } from '@utils/feature';
+import { resourceFileExists, readResourceFile } from '@utils/resource-files';
+
+export async function getStaticPaths() {
+  const services = await getCollection('services');
+  const servicesWithSpecifications = services.filter((service) => getSpecificationsForService(service).length > 0);
+  return servicesWithSpecifications.reduce<
+    { params: { collection: string; id: string; version: string; specification: string }; props: { schema: string } }[]
+  >(
+    (acc, service) => {
+      const specifications = getSpecificationsForService(service);
+      return [
+        ...acc,
+        ...specifications.map((specification) => ({
+          params: {
+            collection: service.collection,
+            id: service.data.id,
+            version: service.data.version,
+            specification: specification.type,
+          },
+          props: {
+            schema: fs.readFileSync(path.join(path.dirname(service.filePath ?? ''), specification.path ?? ''), 'utf8'),
+          },
+        })),
+      ];
+    },
+    [] as { params: { collection: string; id: string; version: string; specification: string }; props: { schema: string } }[]
+  );
+}
+
+export const GET: APIRoute = async ({ props, params }) => {
+  if (!isEventCatalogScaleEnabled()) {
+    return new Response(
+      JSON.stringify({
+        error: 'feature_not_available_on_server',
+        message: 'Schema API is not enabled for this deployment and supported in EventCatalog Scale.',
+      }),
+      {
+        status: 501,
+        headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' },
+      }
+    );
+  }
+
+  // In static mode, props are pre-computed by getStaticPaths
+  if (props.schema) {
+    return new Response(props.schema, {
+      headers: { 'Content-Type': 'text/plain' },
+    });
+  }
+
+  // In SSR mode, dynamically resolve the schema from params
+  const { id, version, specification } = params;
+
+  if (!id || !version || !specification) {
+    return new Response(JSON.stringify({ error: 'Missing id, version, or specification parameter' }), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  const services = await getCollection('services');
+  const service = services.find((s) => s.data.id === id && s.data.version === version);
+
+  if (!service) {
+    return new Response(JSON.stringify({ error: 'Service not found' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  const specifications = getSpecificationsForService(service);
+  const spec = specifications.find((s) => s.type === specification);
+
+  if (!spec || !resourceFileExists(service, spec.path)) {
+    return new Response(JSON.stringify({ error: 'Specification not found' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  const schema = readResourceFile(service, spec.path);
+
+  if (!schema) {
+    return new Response(JSON.stringify({ error: 'Specification file could not be read' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  return new Response(schema, {
+    headers: { 'Content-Type': 'text/plain' },
+  });
+};
diff --git a/packages/core/eventcatalog/src/enterprise/auth/[...auth].ts b/packages/core/eventcatalog/src/enterprise/auth/[...auth].ts
new file mode 100644
index 000000000..955e38ace
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/auth/[...auth].ts
@@ -0,0 +1,8 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import { AstroAuth } from 'auth-astro/server';
+export const prerender = false;
+export const { GET, POST } = AstroAuth();
diff --git a/eventcatalog/src/pages/auth/error.astro b/packages/core/eventcatalog/src/enterprise/auth/error.astro
similarity index 81%
rename from eventcatalog/src/pages/auth/error.astro
rename to packages/core/eventcatalog/src/enterprise/auth/error.astro
index f55dbdd24..954a1fe1c 100644
--- a/eventcatalog/src/pages/auth/error.astro
+++ b/packages/core/eventcatalog/src/enterprise/auth/error.astro
@@ -1,4 +1,5 @@
 ---
+import '../../styles/tailwind.css';
 // src/pages/auth/error.astro
 
 const { searchParams } = new URL(Astro.request.url);
@@ -20,7 +21,9 @@ const errorMessage = errorMessages[error] || errorMessages.Default;
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width" />
+    <link rel="icon" href="/favicon.ico" sizes="any" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
     <meta name="generator" content={Astro.generator} />
     <title>Authentication Error - EventCatalog</title>
   </head>
@@ -46,14 +49,14 @@ const errorMessage = errorMessages[error] || errorMessages.Default;
           <div class="space-y-4">
             <a
               href="/auth/login"
-              class="w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
+              class="w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-xs text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:outline-hidden focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
             >
               Try Again
             </a>
 
             <a
               href="/"
-              class="w-full flex justify-center py-2 px-4 border border-gray-300 rounded-md shadow-sm text-sm font-medium text-gray-700 bg-white hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
+              class="w-full flex justify-center py-2 px-4 border border-gray-300 rounded-md shadow-xs text-sm font-medium text-gray-700 bg-white hover:bg-gray-50 focus:outline-hidden focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
             >
               Back to Home
             </a>
diff --git a/packages/core/eventcatalog/src/enterprise/auth/login.astro b/packages/core/eventcatalog/src/enterprise/auth/login.astro
new file mode 100644
index 000000000..d0a201a6f
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/auth/login.astro
@@ -0,0 +1,423 @@
+---
+import '../../styles/tailwind.css';
+import config from '@config';
+const { title, logo } = config;
+import { join } from 'node:path';
+import { isAuthEnabled, isSSR } from '@utils/feature';
+import { buildUrl } from '@utils/url-builder';
+
+const catalogDirectory = process.env.PROJECT_DIR || process.cwd();
+
+let hasAuthConfigurationFile = false;
+let providers: string[] = [];
+
+try {
+  const authConfig = await import(/* @vite-ignore */ join(catalogDirectory, 'eventcatalog.auth.js'));
+  providers = Object.keys(authConfig.default.providers);
+  hasAuthConfigurationFile = true;
+} catch (error) {
+  hasAuthConfigurationFile = false;
+}
+
+// Check if we should show login (auth file exists, SSR enabled, auth enabled, and has providers)
+const shouldShowLogin = hasAuthConfigurationFile && isSSR() && isAuthEnabled() && providers.length > 0;
+
+// Check if configuration exists but no providers are set up
+const hasConfigButNoProviders = hasAuthConfigurationFile && isSSR() && isAuthEnabled() && providers.length === 0;
+
+// If we are not in SSR mode, redirect to home
+if (!isSSR() || !isAuthEnabled()) {
+  return Astro.redirect('/');
+}
+
+// If we are in SSR mode, check if the user is already logged in
+if (isSSR() && isAuthEnabled()) {
+  const { getSession } = await import(/* @vite-ignore */ 'auth-astro/server');
+  const session = await getSession(Astro.request);
+  if (session) {
+    return Astro.redirect('/');
+  }
+}
+
+// Provider configurations
+const providerConfig = {
+  github: {
+    name: 'GitHub',
+    bgColor: 'bg-gray-900',
+    hoverBg: 'hover:bg-gray-800',
+    textColor: 'text-white',
+    icon: `<svg class="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+      <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"></path>
+    </svg>`,
+  },
+  google: {
+    name: 'Google',
+    bgColor: 'bg-white',
+    hoverBg: 'hover:bg-gray-50',
+    textColor: 'text-gray-700',
+    border: true,
+    icon: `<svg class="w-5 h-5" viewBox="0 0 24 24">
+      <path fill="#4285F4" d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"/>
+      <path fill="#34A853" d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"/>
+      <path fill="#FBBC05" d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"/>
+      <path fill="#EA4335" d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"/>
+    </svg>`,
+  },
+  okta: {
+    name: 'Okta',
+    bgColor: 'bg-[#007DC1]',
+    hoverBg: 'hover:bg-[#006BA8]',
+    textColor: 'text-white',
+    icon: `<svg class="w-5 h-5" viewBox="0 0 24 24" fill="currentColor">
+      <path d="M12 0C5.389 0 0 5.389 0 12s5.389 12 12 12 12-5.389 12-12S18.611 0 12 0zm0 18c-3.314 0-6-2.686-6-6s2.686-6 6-6 6 2.686 6 6-2.686 6-6 6z"/>
+    </svg>`,
+  },
+  auth0: {
+    name: 'Auth0',
+    bgColor: 'bg-[#EB5424]',
+    hoverBg: 'hover:bg-[#D44B20]',
+    textColor: 'text-white',
+    icon: `<svg class="w-5 h-5" viewBox="0 0 16 16" fill="currentColor">
+      <path d="M12.549 1h-4.55l1.407 4.38h4.548l-3.68 2.61 1.406 4.405c2.37-1.725 3.143-4.336 2.274-7.016L12.55 1zM2.045 5.38h4.55L8 1H3.45L2.045 5.38c-.868 2.68-.094 5.29 2.275 7.015L5.725 7.99l-3.68-2.612zm2.275 7.015L8 15l3.68-2.605L8 9.745l-3.68 2.65z"/>
+    </svg>`,
+  },
+  entra: {
+    name: 'Microsoft',
+    bgColor: 'bg-white',
+    hoverBg: 'hover:bg-gray-50',
+    textColor: 'text-gray-700',
+    border: true,
+    icon: `<svg class="w-5 h-5" viewBox="0 0 21 21">
+      <rect x="1" y="1" width="9" height="9" fill="#F25022"/>
+      <rect x="11" y="1" width="9" height="9" fill="#7FBA00"/>
+      <rect x="1" y="11" width="9" height="9" fill="#00A4EF"/>
+      <rect x="11" y="11" width="9" height="9" fill="#FFB900"/>
+    </svg>`,
+  },
+};
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width" />
+    <link rel="icon" href="/favicon.ico" sizes="any" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+    <meta name="generator" content={Astro.generator} />
+    <title>Sign In | {title}</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
+    <style>
+      body {
+        font-family: 'Inter', sans-serif;
+      }
+      .login-bg {
+        background-color: #fafafa;
+        background-image:
+          linear-gradient(to right, rgba(0, 0, 0, 0.03) 1px, transparent 1px),
+          linear-gradient(to bottom, rgba(0, 0, 0, 0.03) 1px, transparent 1px);
+        background-size: 40px 40px;
+        position: relative;
+      }
+      .login-bg::before {
+        content: '';
+        position: absolute;
+        inset: 0;
+        background: radial-gradient(ellipse 80% 50% at 50% 50%, transparent 0%, rgba(250, 250, 250, 0.9) 100%);
+        pointer-events: none;
+      }
+      .glass-card {
+        background: rgba(255, 255, 255, 0.98);
+        backdrop-filter: blur(10px);
+      }
+      @keyframes float {
+        0%,
+        100% {
+          transform: translateY(0px);
+        }
+        50% {
+          transform: translateY(-10px);
+        }
+      }
+      .float-animation {
+        animation: float 6s ease-in-out infinite;
+      }
+    </style>
+  </head>
+  <body class="min-h-screen login-bg">
+    <div class="relative flex min-h-screen flex-col items-center justify-center py-12 px-4 sm:px-6 lg:px-8">
+      {
+        shouldShowLogin ? (
+          <div class="w-full max-w-md">
+            {/* Logo and Title */}
+            <div class="text-center mb-8">
+              {logo && logo.src && (
+                <div class="inline-flex items-center justify-center w-16 h-16 rounded-2xl bg-white shadow-lg shadow-gray-200/50 mb-6 float-animation">
+                  <img alt={logo.alt} src={buildUrl(logo.src)} class="w-10 h-10" />
+                </div>
+              )}
+              <h1 class="text-3xl font-bold text-gray-900 mb-2">{title}</h1>
+              <p class="text-gray-600">Sign in to access your catalog</p>
+            </div>
+
+            {/* Login Card */}
+            <div class="glass-card rounded-2xl shadow-xl shadow-gray-200/50 border border-gray-200/50 overflow-hidden">
+              {/* Purple accent bar */}
+              <div class="h-1 bg-gradient-to-r from-purple-500 via-purple-600 to-indigo-600" />
+
+              <div class="p-8">
+                <div class="space-y-3">
+                  {providers.map((provider) => {
+                    const cfg = providerConfig[provider as keyof typeof providerConfig];
+                    if (!cfg) return null;
+
+                    return (
+                      <button
+                        data-provider={provider}
+                        class={`provider-login-btn group relative flex w-full items-center justify-center rounded-xl px-4 py-3.5 text-sm font-medium transition-all duration-200 ${cfg.bgColor} ${cfg.hoverBg} ${cfg.textColor} hover:scale-[1.02] hover:shadow-lg active:scale-[0.98]`}
+                      >
+                        <span class="absolute left-4" set:html={cfg.icon} />
+                        <span>Continue with {cfg.name}</span>
+                      </button>
+                    );
+                  })}
+                </div>
+              </div>
+            </div>
+
+            {/* Footer links */}
+            <div class="mt-8 text-center">
+              <p class="text-sm text-gray-500">
+                Need a different provider?{' '}
+                <a
+                  href="https://github.com/event-catalog/eventcatalog/issues"
+                  target="_blank"
+                  class="text-purple-600 hover:text-purple-700 font-medium hover:underline"
+                >
+                  Let us know
+                </a>
+              </p>
+            </div>
+          </div>
+        ) : hasConfigButNoProviders ? (
+          <div class="w-full max-w-2xl">
+            {/* Logo */}
+            {logo && (
+              <div class="text-center mb-8">
+                <div class="inline-flex items-center justify-center w-16 h-16 rounded-2xl bg-white shadow-lg shadow-gray-200/50 mb-4">
+                  <img alt={logo.alt} src={logo.src} class="w-10 h-10" />
+                </div>
+              </div>
+            )}
+
+            <div class="glass-card rounded-2xl shadow-xl shadow-gray-200/50 border border-gray-200/50 overflow-hidden">
+              <div class="h-1 bg-gradient-to-r from-amber-500 via-orange-500 to-red-500" />
+
+              <div class="p-8 md:p-10">
+                {/* Warning Icon */}
+                <div class="flex justify-center mb-6">
+                  <div class="w-16 h-16 rounded-2xl bg-amber-100 flex items-center justify-center">
+                    <svg class="w-8 h-8 text-amber-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path
+                        stroke-linecap="round"
+                        stroke-linejoin="round"
+                        stroke-width="2"
+                        d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"
+                      />
+                    </svg>
+                  </div>
+                </div>
+
+                <div class="text-center mb-8">
+                  <h2 class="text-2xl font-bold text-gray-900 mb-2">No Providers Configured</h2>
+                  <p class="text-gray-600">Authentication is enabled but no providers are set up in your configuration file.</p>
+                </div>
+
+                <div class="bg-gray-50 rounded-xl p-6 mb-6">
+                  <h3 class="text-sm font-semibold text-gray-900 uppercase tracking-wider mb-4">Setup Instructions</h3>
+                  <ol class="space-y-3">
+                    <li class="flex items-start gap-3">
+                      <span class="flex-shrink-0 w-6 h-6 rounded-full bg-purple-100 text-purple-600 flex items-center justify-center text-sm font-semibold">
+                        1
+                      </span>
+                      <span class="text-sm text-gray-700">
+                        Update your <code class="px-1.5 py-0.5 bg-gray-200 rounded text-xs font-mono">eventcatalog.auth.js</code>{' '}
+                        file
+                      </span>
+                    </li>
+                    <li class="flex items-start gap-3">
+                      <span class="flex-shrink-0 w-6 h-6 rounded-full bg-purple-100 text-purple-600 flex items-center justify-center text-sm font-semibold">
+                        2
+                      </span>
+                      <span class="text-sm text-gray-700">Add at least one provider (GitHub, Google, Okta, etc.)</span>
+                    </li>
+                    <li class="flex items-start gap-3">
+                      <span class="flex-shrink-0 w-6 h-6 rounded-full bg-purple-100 text-purple-600 flex items-center justify-center text-sm font-semibold">
+                        3
+                      </span>
+                      <span class="text-sm text-gray-700">Restart your EventCatalog server</span>
+                    </li>
+                  </ol>
+                </div>
+
+                <div class="flex flex-col sm:flex-row gap-3 justify-center">
+                  <a
+                    href="https://www.eventcatalog.dev/docs/development/authentication/introduction"
+                    target="_blank"
+                    class="inline-flex items-center justify-center gap-2 px-6 py-3 bg-gray-900 text-white rounded-xl font-medium hover:bg-gray-800 transition-all hover:scale-105"
+                  >
+                    <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path
+                        stroke-linecap="round"
+                        stroke-linejoin="round"
+                        stroke-width="2"
+                        d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253"
+                      />
+                    </svg>
+                    View Documentation
+                  </a>
+                  <a
+                    href="/"
+                    class="inline-flex items-center justify-center gap-2 px-6 py-3 bg-white text-gray-700 border-2 border-gray-200 rounded-xl font-medium hover:border-gray-300 hover:bg-gray-50 transition-all"
+                  >
+                    Go to Home
+                  </a>
+                </div>
+              </div>
+            </div>
+          </div>
+        ) : (
+          <div class="w-full max-w-2xl">
+            {/* Logo */}
+            {logo && (
+              <div class="text-center mb-8">
+                <div class="inline-flex items-center justify-center w-16 h-16 rounded-2xl bg-white shadow-lg shadow-gray-200/50 mb-4">
+                  <img alt={logo.alt} src={logo.src} class="w-10 h-10" />
+                </div>
+              </div>
+            )}
+
+            <div class="glass-card rounded-2xl shadow-xl shadow-gray-200/50 border border-gray-200/50 overflow-hidden">
+              <div class="h-1 bg-gradient-to-r from-gray-400 via-gray-500 to-gray-600" />
+
+              <div class="p-8 md:p-10">
+                {/* Info Icon */}
+                <div class="flex justify-center mb-6">
+                  <div class="w-16 h-16 rounded-2xl bg-gray-100 flex items-center justify-center">
+                    <svg class="w-8 h-8 text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path
+                        stroke-linecap="round"
+                        stroke-linejoin="round"
+                        stroke-width="2"
+                        d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
+                      />
+                    </svg>
+                  </div>
+                </div>
+
+                <div class="text-center mb-8">
+                  <h2 class="text-2xl font-bold text-gray-900 mb-2">Authentication Not Configured</h2>
+                  <p class="text-gray-600">
+                    {!hasAuthConfigurationFile
+                      ? 'No authentication configuration file found.'
+                      : 'Authentication is not properly enabled.'}
+                  </p>
+                </div>
+
+                <div class="bg-gray-50 rounded-xl p-6 mb-6">
+                  <h3 class="text-sm font-semibold text-gray-900 uppercase tracking-wider mb-4">Enable Authentication</h3>
+                  <ol class="space-y-3">
+                    {!hasAuthConfigurationFile && (
+                      <li class="flex items-start gap-3">
+                        <span class="flex-shrink-0 w-6 h-6 rounded-full bg-purple-100 text-purple-600 flex items-center justify-center text-sm font-semibold">
+                          1
+                        </span>
+                        <span class="text-sm text-gray-700">
+                          Create <code class="px-1.5 py-0.5 bg-gray-200 rounded text-xs font-mono">eventcatalog.auth.js</code> in
+                          your project root
+                        </span>
+                      </li>
+                    )}
+                    {!isSSR() && (
+                      <li class="flex items-start gap-3">
+                        <span class="flex-shrink-0 w-6 h-6 rounded-full bg-purple-100 text-purple-600 flex items-center justify-center text-sm font-semibold">
+                          {!hasAuthConfigurationFile ? '2' : '1'}
+                        </span>
+                        <span class="text-sm text-gray-700">
+                          Set <code class="px-1.5 py-0.5 bg-gray-200 rounded text-xs font-mono">output: 'server'</code> in your
+                          config
+                        </span>
+                      </li>
+                    )}
+                    {!isAuthEnabled() && (
+                      <li class="flex items-start gap-3">
+                        <span class="flex-shrink-0 w-6 h-6 rounded-full bg-purple-100 text-purple-600 flex items-center justify-center text-sm font-semibold">
+                          {!hasAuthConfigurationFile ? (!isSSR() ? '3' : '2') : !isSSR() ? '2' : '1'}
+                        </span>
+                        <span class="text-sm text-gray-700">
+                          Set <code class="px-1.5 py-0.5 bg-gray-200 rounded text-xs font-mono">auth: {'{ enabled: true }'}</code>{' '}
+                          in your config
+                        </span>
+                      </li>
+                    )}
+                  </ol>
+                </div>
+
+                <div class="flex flex-col sm:flex-row gap-3 justify-center">
+                  <a
+                    href="https://www.eventcatalog.dev/docs/development/authentication/introduction"
+                    target="_blank"
+                    class="inline-flex items-center justify-center gap-2 px-6 py-3 bg-gray-900 text-white rounded-xl font-medium hover:bg-gray-800 transition-all hover:scale-105"
+                  >
+                    <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path
+                        stroke-linecap="round"
+                        stroke-linejoin="round"
+                        stroke-width="2"
+                        d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253"
+                      />
+                    </svg>
+                    View Documentation
+                  </a>
+                  <a
+                    href="/"
+                    class="inline-flex items-center justify-center gap-2 px-6 py-3 bg-white text-gray-700 border-2 border-gray-200 rounded-xl font-medium hover:border-gray-300 hover:bg-gray-50 transition-all"
+                  >
+                    Go to Home
+                  </a>
+                </div>
+              </div>
+            </div>
+          </div>
+        )
+      }
+
+      {/* Footer */}
+      <div class="absolute bottom-6 text-center">
+        <p class="text-xs text-gray-400">
+          Powered by <a href="https://www.eventcatalog.dev" target="_blank" class="hover:text-gray-600 transition-colors"
+            >EventCatalog</a
+          >
+        </p>
+      </div>
+    </div>
+  </body>
+</html>
+
+<script>
+  import { signIn } from 'auth-astro/client';
+
+  // Add event listeners to all provider login buttons
+  const providerButtons = document.querySelectorAll('.provider-login-btn');
+
+  providerButtons.forEach((button) => {
+    const provider = button.getAttribute('data-provider');
+    if (provider) {
+      let providerId = provider === 'entra' ? 'microsoft-entra-id' : provider;
+      button.addEventListener('click', () => signIn(providerId));
+    }
+  });
+</script>
diff --git a/eventcatalog/src/middleware-auth.ts b/packages/core/eventcatalog/src/enterprise/auth/middleware/middleware-auth.ts
similarity index 91%
rename from eventcatalog/src/middleware-auth.ts
rename to packages/core/eventcatalog/src/enterprise/auth/middleware/middleware-auth.ts
index 05c12f757..b0691dc69 100644
--- a/eventcatalog/src/middleware-auth.ts
+++ b/packages/core/eventcatalog/src/enterprise/auth/middleware/middleware-auth.ts
@@ -1,7 +1,12 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
 // src/middleware/auth.ts
 import type { MiddlewareHandler } from 'astro';
 import { getSession } from 'auth-astro/server';
-import { isAuthEnabled } from '@utils/feature';
+import { isAuthEnabled, isEventCatalogMCPAuthEnabled } from '@utils/feature';
 import jwt from 'jsonwebtoken';
 import { isLLMSTxtEnabled } from '@utils/feature';
 
@@ -75,6 +80,27 @@ export function findMatchingRule(rules: Record<string, () => boolean>, pathname:
   return matches.length > 0 ? matches[0].rule : null;
 }
 
+export function getPublicRoutes(isLLMSTextEnabled: boolean) {
+  const publicRoutes = ['/auth/login', '/auth/signout', '/auth/error', '/api/auth'];
+
+  if (!isLLMSTextEnabled) {
+    return publicRoutes;
+  }
+
+  return [
+    ...publicRoutes,
+    '/llms.txt',
+    '/llms-full.txt',
+    '/docs/llm/llms.txt',
+    '/docs/llm/llms-full.txt',
+    '/docs/llm/schemas.txt',
+  ];
+}
+
+export function isMcpRoute(pathname: string) {
+  return pathname === '/docs/mcp' || pathname.startsWith('/docs/mcp/');
+}
+
 export const authMiddleware: MiddlewareHandler = async (context, next) => {
   const { request, redirect, locals } = context;
   const url = new URL(request.url);
@@ -92,16 +118,11 @@ export const authMiddleware: MiddlewareHandler = async (context, next) => {
 
   // Skip system/browser requests
   const systemRoutes = ['/.well-known/', '/favicon.ico', '/robots.txt', '/sitemap.xml', '/_astro/', '/__astro'];
-  let publicRoutes = ['/auth/login', '/auth/signout', '/auth/error', '/api/auth'];
-
-  const llmsRoutes = ['/docs/llm/llms.txt', '/docs/llm/llms-services.txt', '/docs/llm/llms-full.txt'];
-
-  if (isLLMSTextEnabled) {
-    publicRoutes = [...publicRoutes, ...llmsRoutes];
-  }
+  const publicRoutes = getPublicRoutes(isLLMSTextEnabled);
 
   if (
     pathname.startsWith('/_') ||
+    (isEventCatalogMCPAuthEnabled() && isMcpRoute(pathname)) ||
     systemRoutes.some((route) => pathname.startsWith(route)) ||
     pathname.startsWith('/.well-known/') ||
     publicRoutes.some((route) => pathname.startsWith(route)) ||
diff --git a/packages/core/eventcatalog/src/enterprise/auth/middleware/middleware.ts b/packages/core/eventcatalog/src/enterprise/auth/middleware/middleware.ts
new file mode 100644
index 000000000..3dbb000c6
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/auth/middleware/middleware.ts
@@ -0,0 +1,51 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { MiddlewareHandler } from 'astro';
+import { authMiddleware } from './middleware-auth.ts';
+import { sequence } from 'astro:middleware';
+import { join } from 'node:path';
+import { isSSR } from '@utils/feature';
+
+// Try to load customer's custom RBAC middleware
+let customerRbacMiddleware: MiddlewareHandler | null = null;
+
+try {
+  const catalogDirectory = process.env.PROJECT_DIR || process.cwd();
+  const customerMiddleware = await import(/* @vite-ignore */ join(catalogDirectory, 'middleware.ts'));
+  customerRbacMiddleware = customerMiddleware.rbacMiddleware;
+
+  if (!isSSR()) {
+    // Tell user they need to build in SSR mode
+    console.log(
+      '🔴 Found custom middleware.ts file. To use RBAC, you need to build in SSR mode, by setting output: "server" in your eventcatalog.config.js file.'
+    );
+  } else {
+    console.log('✅ Loaded custom RBAC middleware');
+  }
+} catch (error) {
+  // Just silently fail, we don't want to block the app
+}
+
+const errorHandlingMiddleware: MiddlewareHandler = async (context, next) => {
+  const response = await next();
+
+  if (response.status === 403) {
+    const params = new URLSearchParams({
+      path: context.url.pathname,
+      returnTo: context.url.pathname + context.url.search,
+    });
+
+    return context.redirect(`/unauthorized?${params.toString()}`);
+  }
+
+  return response;
+};
+
+const middlewareChain = customerRbacMiddleware
+  ? [errorHandlingMiddleware, authMiddleware, customerRbacMiddleware]
+  : [errorHandlingMiddleware, authMiddleware];
+
+export const onRequest = isSSR() ? sequence(...middlewareChain) : undefined;
diff --git a/packages/core/eventcatalog/src/enterprise/auth/unauthorized.astro b/packages/core/eventcatalog/src/enterprise/auth/unauthorized.astro
new file mode 100644
index 000000000..229e35c39
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/auth/unauthorized.astro
@@ -0,0 +1,84 @@
+---
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+---
+
+<VerticalSideBarLayout title="Unauthorized - EventCatalog" showNestedSideBar={false}>
+  <div class="flex h-[calc(100vh-120px)] bg-white">
+    <main class="flex w-full items-center justify-center bg-white text-center sm:p-12">
+      <div class="w-full max-w-xl text-center">
+        <div class="mb-6 inline-flex h-16 w-16 items-center justify-center rounded-2xl bg-red-100">
+          <svg
+            class="h-9 w-9 text-red-600"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <rect x="3" y="11" width="18" height="11" rx="2" ry="2"></rect>
+            <path d="M7 11V7a5 5 0 0 1 10 0v4"></path>
+          </svg>
+        </div>
+
+        <h1 class="text-3xl font-bold text-gray-800 mb-4">Access Denied</h1>
+
+        <p class="max-w-md mx-auto text-base text-gray-500 mb-8">You don't have permission to access this resource.</p>
+
+        <!-- Client-side path display -->
+        <div
+          id="path-container"
+          class="hidden mb-8 w-full max-w-lg mx-auto rounded-lg border border-gray-200 bg-gray-100 p-4 text-left"
+        >
+          <p class="mb-2 text-sm font-medium text-gray-600">Requested path:</p>
+          <code id="requested-path" class="break-all font-mono text-sm text-gray-800"></code>
+        </div>
+
+        <div class="flex flex-col sm:flex-row gap-4 justify-center">
+          <button
+            onclick="history.back()"
+            class="inline-flex items-center justify-center px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md shadow-xs hover:bg-gray-50 focus:outline-hidden focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
+          >
+            <svg class="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 19l-7-7m0 0l7-7m-7 7h18"></path>
+            </svg>
+            Go Back
+          </button>
+
+          <a
+            href="/dashboard"
+            class="inline-flex items-center justify-center px-4 py-2 text-sm font-medium text-white bg-blue-600 border border-transparent rounded-md shadow-xs hover:bg-blue-700 focus:outline-hidden focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
+          >
+            <svg class="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                stroke-width="2"
+                d="M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2H5a2 2 0 00-2-2z"></path>
+            </svg>
+            Go to Dashboard
+          </a>
+        </div>
+      </div>
+    </main>
+  </div>
+
+  <!-- Client-side script -->
+  <script>
+    document.addEventListener('DOMContentLoaded', () => {
+      // Get query parameters on the client side
+      const url = new URL(window.location.href);
+      const path = url.searchParams.get('path');
+
+      if (path) {
+        const pathContainer = document.getElementById('path-container');
+        const requestedPath = document.getElementById('requested-path');
+
+        if (pathContainer && requestedPath) {
+          requestedPath.textContent = path;
+          pathContainer.classList.remove('hidden');
+        }
+      }
+    });
+  </script>
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/enterprise/collections/__tests__/resource-docs.spec.ts b/packages/core/eventcatalog/src/enterprise/collections/__tests__/resource-docs.spec.ts
new file mode 100644
index 000000000..e36016b89
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/collections/__tests__/resource-docs.spec.ts
@@ -0,0 +1,380 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { CollectionKey } from 'astro:content';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  getGroupedResourceDocsByType,
+  getResourceDocCategories,
+  getResourceDocs,
+  getResourceDocsForResource,
+} from '@enterprise/collections/resource-docs-utils';
+
+const mockDomains = [
+  {
+    collection: 'domains',
+    data: { id: 'Payments', version: '1.0.0', hidden: false },
+    filePath: 'domains/Payments/index.mdx',
+  },
+  {
+    collection: 'domains',
+    data: { id: 'Payments', version: '0.9.0', hidden: false },
+    filePath: 'domains/Payments/versioned/0.9.0/index.mdx',
+  },
+  {
+    collection: 'domains',
+    data: { id: 'random', version: '1.0.0', hidden: false },
+    filePath: 'domains/BoxOffice/index.mdx',
+  },
+];
+
+const mockServices = [
+  {
+    collection: 'services',
+    data: { id: 'BillingService', version: '2.0.0', hidden: false },
+    filePath: 'services/BillingService/index.mdx',
+  },
+  {
+    collection: 'services',
+    data: { id: 'BillingService', version: '1.0.0', hidden: false },
+    filePath: 'services/BillingService/versioned/1.0.0/index.mdx',
+  },
+];
+
+const mockEvents = [
+  {
+    collection: 'events',
+    data: { id: 'InvoiceIssued', version: '3.0.0', hidden: false },
+    filePath: 'events/InvoiceIssued/index.mdx',
+  },
+];
+
+const mockResourceDocs = [
+  {
+    id: 'domains/Payments/docs/runbooks/10-incident.mdx',
+    collection: 'resourceDocs',
+    filePath: 'domains/Payments/docs/runbooks/10-incident.mdx',
+    data: { id: 'incident', type: 'runbooks', version: '1.0.0', order: 2, title: 'Incident Handling' },
+  },
+  {
+    id: 'domains/Payments/docs/runbooks/versioned/0.9.0/10-incident.mdx',
+    collection: 'resourceDocs',
+    filePath: 'domains/Payments/docs/runbooks/versioned/0.9.0/10-incident.mdx',
+    data: { id: 'incident', type: 'runbooks', version: '0.9.0', order: 2, title: 'Incident Handling' },
+  },
+  {
+    id: 'domains/Payments/docs/runbooks/1-playbook.mdx',
+    collection: 'resourceDocs',
+    filePath: 'domains/Payments/docs/runbooks/1-playbook.mdx',
+    data: { id: 'playbook', type: 'runbooks', version: '1.0.0', title: 'Playbook' },
+  },
+  {
+    id: 'domains/Payments/docs/runbooks/checklist.mdx',
+    collection: 'resourceDocs',
+    filePath: 'domains/Payments/docs/runbooks/checklist.mdx',
+    data: { id: 'checklist', type: 'runbooks', version: '1.0.0', title: 'Checklist' },
+  },
+  {
+    id: 'domains/Payments/docs/incident-retrospective.mdx',
+    collection: 'resourceDocs',
+    filePath: 'domains/Payments/docs/incident-retrospective.mdx',
+    data: { id: 'incident-retrospective', version: '1.0.0', title: 'Incident Retrospective Template' },
+  },
+  {
+    id: 'domains/Payments/versioned/0.9.0/docs/runbooks/legacy-ops.mdx',
+    collection: 'resourceDocs',
+    filePath: 'domains/Payments/versioned/0.9.0/docs/runbooks/legacy-ops.mdx',
+    data: { id: 'legacy-ops', type: 'runbooks', title: 'Legacy Operations' },
+  },
+  {
+    id: 'domains/Payments/services/BillingService/docs/guides/on-call.mdx',
+    collection: 'resourceDocs',
+    filePath: 'domains/Payments/services/BillingService/docs/guides/on-call.mdx',
+    data: { id: 'on-call', type: 'guides', title: 'On-call Guide' },
+  },
+  {
+    id: 'domains/Payments/services/BillingService/events/InvoiceIssued/docs/reference/payload.mdx',
+    collection: 'resourceDocs',
+    filePath: 'domains/Payments/services/BillingService/events/InvoiceIssued/docs/reference/payload.mdx',
+    data: { id: 'payload', type: 'references', version: '1.0.0', title: 'Payload Contract' },
+  },
+  {
+    id: 'domains/Unknown/docs/runbooks/ignored.mdx',
+    collection: 'resourceDocs',
+    filePath: 'domains/Unknown/docs/runbooks/ignored.mdx',
+    data: { id: 'ignored', type: 'runbooks', version: '1.0.0', title: 'Ignored' },
+  },
+  {
+    id: 'domains/Payments/docs/runbooks/hidden.mdx',
+    collection: 'resourceDocs',
+    filePath: 'domains/Payments/docs/runbooks/hidden.mdx',
+    data: { id: 'hidden', type: 'runbooks', version: '1.0.0', title: 'Hidden', hidden: true },
+  },
+  {
+    id: 'domains/BoxOffice/docs/meow.mdx',
+    collection: 'resourceDocs',
+    filePath: 'domains/BoxOffice/docs/meow.mdx',
+    data: { id: 'meow', version: '1.0.0', title: 'Meow' },
+  },
+];
+
+const mockResourceDocCategories = [
+  {
+    id: 'domains/Payments/docs/runbooks/_category_.json',
+    collection: 'resourceDocCategories',
+    filePath: 'domains/Payments/docs/runbooks/_category_.json',
+    data: { label: 'Runbooks (Legacy)', position: 99 },
+  },
+  {
+    id: 'domains/Payments/docs/runbooks/category.json',
+    collection: 'resourceDocCategories',
+    filePath: 'domains/Payments/docs/runbooks/category.json',
+    data: { label: 'Runbooks', position: 2 },
+  },
+  {
+    id: 'domains/Payments/docs/category.json',
+    collection: 'resourceDocCategories',
+    filePath: 'domains/Payments/docs/category.json',
+    data: { label: 'General', position: 1 },
+  },
+  {
+    id: 'domains/Payments/docs/reference/category.json',
+    collection: 'resourceDocCategories',
+    filePath: 'domains/Payments/docs/reference/category.json',
+    data: { label: 'Reference', position: 3 },
+  },
+];
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: (key: CollectionKey) => {
+      switch (key) {
+        case 'domains':
+          return Promise.resolve(mockDomains as any[]);
+        case 'services':
+          return Promise.resolve(mockServices as any[]);
+        case 'events':
+          return Promise.resolve(mockEvents as any[]);
+        case 'commands':
+        case 'queries':
+          return Promise.resolve([]);
+        case 'resourceDocs':
+          return Promise.resolve(mockResourceDocs as any[]);
+        case 'resourceDocCategories':
+          return Promise.resolve(mockResourceDocCategories as any[]);
+        default:
+          return Promise.resolve([]);
+      }
+    },
+  };
+});
+
+describe('resource-docs', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    process.env.EVENTCATALOG_SCALE = 'true';
+    delete process.env.EVENTCATALOG_STARTER;
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('infers resource metadata from file paths and resolves latest/versioned resources', async () => {
+    const docs = await getResourceDocs();
+
+    expect(docs).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          data: expect.objectContaining({
+            id: 'incident',
+            type: 'runbooks',
+            resourceCollection: 'domains',
+            resourceId: 'Payments',
+            resourceVersion: '1.0.0',
+            latestVersion: '1.0.0',
+            versions: ['1.0.0', '0.9.0'],
+          }),
+        }),
+        expect.objectContaining({
+          data: expect.objectContaining({
+            id: 'legacy-ops',
+            type: 'runbooks',
+            resourceCollection: 'domains',
+            resourceId: 'Payments',
+            resourceVersion: '0.9.0',
+          }),
+        }),
+        expect.objectContaining({
+          data: expect.objectContaining({
+            id: 'on-call',
+            type: 'guides',
+            resourceCollection: 'services',
+            resourceId: 'BillingService',
+            resourceVersion: '2.0.0',
+          }),
+        }),
+        expect.objectContaining({
+          data: expect.objectContaining({
+            id: 'payload',
+            type: 'references',
+            resourceCollection: 'events',
+            resourceId: 'InvoiceIssued',
+            resourceVersion: '3.0.0',
+          }),
+        }),
+        expect.objectContaining({
+          data: expect.objectContaining({
+            id: 'incident-retrospective',
+            type: 'pages',
+            resourceCollection: 'domains',
+            resourceId: 'Payments',
+            resourceVersion: '1.0.0',
+          }),
+        }),
+      ])
+    );
+
+    // Unknown and hidden docs are skipped
+    expect(docs.find((doc) => doc.data.id === 'ignored')).toBeUndefined();
+    expect(docs.find((doc) => doc.data.id === 'hidden')).toBeUndefined();
+  });
+
+  it('returns docs by resource and groups docs by type alphabetically', async () => {
+    const docsForDomain = await getResourceDocsForResource('domains', 'Payments', '1.0.0');
+
+    expect(docsForDomain.map((doc) => doc.data.id)).toEqual(
+      expect.arrayContaining(['incident', 'playbook', 'checklist', 'incident-retrospective'])
+    );
+    expect(docsForDomain.find((doc) => doc.data.id === 'legacy-ops')).toBeUndefined();
+
+    const grouped = getGroupedResourceDocsByType(docsForDomain, { latestOnly: true });
+
+    expect(grouped.map((group) => group.type)).toEqual(['pages', 'runbooks']);
+    expect(grouped[0].docs.map((doc) => doc.data.id)).toEqual(['incident-retrospective']);
+    expect(grouped[1].docs.map((doc) => doc.data.id)).toEqual(['playbook', 'incident', 'checklist']);
+    expect(grouped[1].docs.map((doc) => doc.data.version)).toEqual(['1.0.0', '1.0.0', '1.0.0']);
+    expect(grouped[1].docs.find((doc) => doc.data.id === 'playbook')?.data.order).toBe(1);
+    expect(grouped[1].docs.find((doc) => doc.data.id === 'incident')?.data.order).toBe(2);
+  });
+
+  it('applies category metadata and prefers category.json over _category_.json', async () => {
+    const categories = await getResourceDocCategories();
+    const categoriesForDomain = categories.filter(
+      (category) =>
+        category.data.resourceCollection === 'domains' &&
+        category.data.resourceId === 'Payments' &&
+        category.data.resourceVersion === '1.0.0'
+    );
+
+    const docsForDomain = await getResourceDocsForResource('domains', 'Payments', '1.0.0');
+    const grouped = getGroupedResourceDocsByType(docsForDomain, {
+      latestOnly: true,
+      categories: categoriesForDomain,
+    });
+
+    expect(grouped.map((group) => group.type)).toEqual(['pages', 'runbooks']);
+    expect(grouped[0]).toMatchObject({
+      type: 'pages',
+      label: 'General',
+      position: 1,
+    });
+    expect(grouped[1]).toMatchObject({
+      type: 'runbooks',
+      label: 'Runbooks',
+      position: 2,
+    });
+  });
+
+  it('matches categories with singular/plural type variants', () => {
+    const grouped = getGroupedResourceDocsByType(
+      [
+        {
+          id: '1',
+          collection: 'resourceDocs',
+          filePath: 'domains/Payments/docs/reference/payload.mdx',
+          data: {
+            id: 'payload',
+            type: 'references',
+            version: '1.0.0',
+            title: 'Payload Contract',
+            resourceCollection: 'domains',
+            resourceId: 'Payments',
+            resourceVersion: '1.0.0',
+            versions: ['1.0.0'],
+            latestVersion: '1.0.0',
+          },
+        } as any,
+      ],
+      {
+        categories: [
+          {
+            id: 'cat-1',
+            collection: 'resourceDocCategories',
+            filePath: 'domains/Payments/docs/reference/category.json',
+            data: {
+              type: 'reference',
+              label: 'Reference',
+              resourceCollection: 'domains',
+              resourceId: 'Payments',
+              resourceVersion: '1.0.0',
+            },
+          } as any,
+        ],
+      }
+    );
+
+    expect(grouped).toHaveLength(1);
+    expect(grouped[0]).toMatchObject({
+      type: 'references',
+      label: 'Reference',
+    });
+  });
+
+  it('resolves docs when folder name differs from resource frontmatter id', async () => {
+    const docs = await getResourceDocs();
+    const meowDoc = docs.find((doc) => doc.data.id === 'meow');
+
+    expect(meowDoc).toBeDefined();
+    expect(meowDoc!.data).toMatchObject({
+      id: 'meow',
+      resourceCollection: 'domains',
+      resourceId: 'random',
+      resourceVersion: '1.0.0',
+    });
+  });
+
+  it('when a resource doc does not specify a version, it inherits the version from its parent resource', async () => {
+    const docs = await getResourceDocs();
+    const versionedDoc = docs.find(
+      (doc) =>
+        doc.data.resourceCollection === 'domains' &&
+        doc.data.resourceId === 'Payments' &&
+        doc.data.resourceVersion === '0.9.0' &&
+        doc.data.id === 'legacy-ops'
+    );
+    const resourceScopedDoc = docs.find(
+      (doc) => doc.data.resourceCollection === 'services' && doc.data.resourceId === 'BillingService' && doc.data.id === 'on-call'
+    );
+
+    expect(versionedDoc).toBeDefined();
+    expect(versionedDoc!.data).toMatchObject({
+      version: '0.9.0',
+      latestVersion: '0.9.0',
+      resourceVersion: '0.9.0',
+    });
+
+    expect(resourceScopedDoc).toBeDefined();
+    expect(resourceScopedDoc!.data).toMatchObject({
+      version: '2.0.0',
+      latestVersion: '2.0.0',
+      resourceVersion: '2.0.0',
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/enterprise/collections/custom-pages.ts b/packages/core/eventcatalog/src/enterprise/collections/custom-pages.ts
new file mode 100644
index 000000000..2005854bd
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/collections/custom-pages.ts
@@ -0,0 +1,21 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import { z } from 'astro/zod';
+import { badge, ownerReference } from '../../content.config-shared-collections';
+
+export const customPagesSchema = z.object({
+  title: z.string(),
+  summary: z.string(),
+  slug: z.string().optional(),
+  sidebar: z
+    .object({
+      label: z.string(),
+      order: z.number(),
+    })
+    .optional(),
+  owners: z.array(ownerReference).optional(),
+  badges: z.array(badge).optional(),
+});
diff --git a/packages/core/eventcatalog/src/enterprise/collections/index.ts b/packages/core/eventcatalog/src/enterprise/collections/index.ts
new file mode 100644
index 000000000..915e66fa1
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/collections/index.ts
@@ -0,0 +1,7 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+export { customPagesSchema } from './custom-pages';
+export { resourceDocsSchema, resourceDocCategoriesSchema } from './resource-docs';
diff --git a/packages/core/eventcatalog/src/enterprise/collections/resource-docs-utils.ts b/packages/core/eventcatalog/src/enterprise/collections/resource-docs-utils.ts
new file mode 100644
index 000000000..a2269b32c
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/collections/resource-docs-utils.ts
@@ -0,0 +1,672 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import { getCollection, type CollectionEntry } from 'astro:content';
+import fs from 'node:fs';
+import path from 'node:path';
+import { coerce, rcompare } from 'semver';
+import { sortVersioned } from '../../utils/collections/util';
+import { isResourceDocsEnabled } from '../feature';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+
+export type ResourceCollection =
+  | 'agents'
+  | 'domains'
+  | 'systems'
+  | 'services'
+  | 'events'
+  | 'commands'
+  | 'queries'
+  | 'flows'
+  | 'containers'
+  | 'channels'
+  | 'entities'
+  | 'data-products';
+
+type BaseResourceDocEntry = CollectionEntry<'resourceDocs'>;
+type BaseResourceDocCategoryEntry = CollectionEntry<'resourceDocCategories'>;
+
+export type ResourceDocEntry = Omit<BaseResourceDocEntry, 'data'> & {
+  data: BaseResourceDocEntry['data'] & {
+    id: string;
+    type: string;
+    version: string;
+    order?: number;
+    resourceCollection: ResourceCollection;
+    resourceId: string;
+    resourceVersion: string;
+    versions: string[];
+    latestVersion: string;
+  };
+};
+
+export type ResourceDocCategoryEntry = Omit<BaseResourceDocCategoryEntry, 'data'> & {
+  data: BaseResourceDocCategoryEntry['data'] & {
+    type: string;
+    resourceCollection: ResourceCollection;
+    resourceId: string;
+    resourceVersion: string;
+  };
+};
+
+export type ResourceDocGroup = {
+  type: string;
+  docs: ResourceDocEntry[];
+  label?: string;
+  position?: number;
+};
+
+type ResourceLookup = {
+  latestById: Map<string, string>;
+  versionsById: Map<string, Set<string>>;
+  folderToId: Map<string, string>;
+};
+
+type InferredResource = {
+  resourceCollection: ResourceCollection;
+  resourceId: string;
+  resourceVersion: string;
+};
+
+let memoryCache: ResourceDocEntry[] | null = null;
+let memoryCategoryCache: ResourceDocCategoryEntry[] | null = null;
+let memoryResourceLookupCache: Record<ResourceCollection, ResourceLookup> | null = null;
+let memoryResourceLookupPromise: Promise<Record<ResourceCollection, ResourceLookup>> | null = null;
+
+const normalizePath = (value: string) => value.replace(/\\/g, '/').replace(/^\.\//, '');
+const normalizeTypeName = (value: string) => value.trim().toLowerCase();
+
+const isMissingGeneratedContentFile = (filePath: string) => {
+  const normalizedPath = normalizePath(filePath);
+
+  if (!path.isAbsolute(filePath) && !normalizedPath.startsWith('../')) {
+    return false;
+  }
+
+  return !fs.existsSync(filePath);
+};
+
+const inferOrderFromFilePath = (filePath: string): number | undefined => {
+  const normalizedPath = normalizePath(filePath);
+  const fileName = normalizedPath.split('/').pop();
+
+  if (!fileName) {
+    return undefined;
+  }
+
+  const fileNameWithoutExtension = fileName.replace(/\.(md|mdx)$/i, '');
+  const orderMatch = fileNameWithoutExtension.match(/^(\d+)(?:[-_.\s]|$)/);
+
+  if (!orderMatch) {
+    return undefined;
+  }
+
+  const parsedOrder = Number.parseInt(orderMatch[1], 10);
+  return Number.isFinite(parsedOrder) ? parsedOrder : undefined;
+};
+
+const inferDocIdFromFilePath = (filePath: string): string | undefined => {
+  const normalizedPath = normalizePath(filePath);
+  const fileName = normalizedPath.split('/').pop();
+
+  if (!fileName) {
+    return undefined;
+  }
+
+  const fileNameWithoutExtension = fileName.replace(/\.(md|mdx)$/i, '');
+  if (!fileNameWithoutExtension) {
+    return undefined;
+  }
+
+  // Support ordered filenames like "01-my-doc" while keeping stable ids.
+  const idWithoutNumericPrefix = fileNameWithoutExtension.replace(/^\d+(?:[-_.\s]+)?/, '');
+  return idWithoutNumericPrefix || fileNameWithoutExtension;
+};
+
+const inferDocTypeFromFilePath = (filePath: string): string | undefined => {
+  const normalizedPath = normalizePath(filePath);
+  const docsMarker = '/docs/';
+  const docsIndex = normalizedPath.indexOf(docsMarker);
+
+  if (docsIndex === -1) {
+    return undefined;
+  }
+
+  const docsRelativePath = normalizedPath.slice(docsIndex + docsMarker.length);
+  const segments = docsRelativePath.split('/').filter(Boolean);
+  const firstSegment = segments[0];
+
+  if (!firstSegment || firstSegment === 'versioned') {
+    return undefined;
+  }
+
+  if (/\.[a-z0-9]+$/i.test(firstSegment)) {
+    return undefined;
+  }
+
+  return firstSegment;
+};
+
+const getCategoryFilePriority = (filePath: string): number => {
+  const fileName = normalizePath(filePath).split('/').pop()?.toLowerCase();
+  if (fileName === 'category.json') {
+    return 2;
+  }
+  if (fileName === '_category_.json') {
+    return 1;
+  }
+  return 0;
+};
+
+const inferResourceFromFilePath = (filePath: string): InferredResource | null => {
+  const normalizedPath = normalizePath(filePath);
+  const docsIndex = normalizedPath.indexOf('/docs/');
+
+  if (docsIndex === -1) {
+    return null;
+  }
+
+  const resourcePath = normalizedPath.slice(0, docsIndex);
+  const segments = resourcePath.split('/').filter(Boolean);
+
+  const parseVersion = (index: number) => {
+    if (segments[index + 2] === 'versioned' && segments[index + 3]) {
+      return segments[index + 3];
+    }
+    return 'latest';
+  };
+
+  const segmentMappings: Array<{ segment: string; collection: ResourceCollection }> = [
+    { segment: 'agents', collection: 'agents' },
+    { segment: 'events', collection: 'events' },
+    { segment: 'commands', collection: 'commands' },
+    { segment: 'queries', collection: 'queries' },
+    { segment: 'services', collection: 'services' },
+    { segment: 'domains', collection: 'domains' },
+    { segment: 'subdomains', collection: 'domains' },
+    { segment: 'flows', collection: 'flows' },
+    { segment: 'containers', collection: 'containers' },
+    { segment: 'channels', collection: 'channels' },
+    { segment: 'entities', collection: 'entities' },
+    { segment: 'data-products', collection: 'data-products' },
+  ];
+
+  let matched: { index: number; collection: ResourceCollection } | null = null;
+
+  for (let index = 0; index < segments.length; index++) {
+    const match = segmentMappings.find((mapping) => mapping.segment === segments[index]);
+    if (!match) {
+      continue;
+    }
+
+    if (!segments[index + 1]) {
+      continue;
+    }
+
+    if (!matched || index > matched.index) {
+      matched = { index, collection: match.collection };
+    }
+  }
+
+  if (!matched) {
+    return null;
+  }
+
+  return {
+    resourceCollection: matched.collection,
+    resourceId: segments[matched.index + 1],
+    resourceVersion: parseVersion(matched.index),
+  };
+};
+
+const getResourceFolderFromFilePath = (filePath: string): string | undefined => {
+  const normalized = normalizePath(filePath);
+  const versionedIndex = normalized.indexOf('/versioned/');
+  if (versionedIndex !== -1) {
+    // e.g. "domains/BoxOffice/versioned/1.0.0/index.mdx" → "domains/BoxOffice"
+    const beforeVersioned = normalized.slice(0, versionedIndex);
+    return path.basename(beforeVersioned) || undefined;
+  }
+  // e.g. "domains/BoxOffice/index.mdx" → "BoxOffice"
+  const dir = path.dirname(normalized);
+  return dir ? path.basename(dir) : undefined;
+};
+
+const buildLookup = (
+  resources: Array<{
+    data: { id: string; version: string; hidden?: boolean };
+    filePath?: string;
+  }>
+): ResourceLookup => {
+  const groupedById = new Map<string, string[]>();
+  const folderToId = new Map<string, string>();
+
+  for (const resource of resources) {
+    if (resource.data.hidden === true) {
+      continue;
+    }
+    const list = groupedById.get(resource.data.id) || [];
+    list.push(resource.data.version);
+    groupedById.set(resource.data.id, list);
+
+    if (resource.filePath) {
+      const folderName = getResourceFolderFromFilePath(resource.filePath);
+      if (folderName && folderName !== resource.data.id) {
+        folderToId.set(folderName, resource.data.id);
+      }
+    }
+  }
+
+  const latestById = new Map<string, string>();
+  const versionsById = new Map<string, Set<string>>();
+
+  for (const [id, versions] of groupedById.entries()) {
+    const sorted = sortVersioned([...new Set(versions)], (version) => version);
+    if (sorted.length > 0) {
+      latestById.set(id, sorted[0]);
+      versionsById.set(id, new Set(sorted));
+    }
+  }
+
+  return { latestById, versionsById, folderToId };
+};
+
+const getResourceLookups = async (): Promise<Record<ResourceCollection, ResourceLookup>> => {
+  if (CACHE_ENABLED && memoryResourceLookupCache) {
+    return memoryResourceLookupCache;
+  }
+
+  if (CACHE_ENABLED && memoryResourceLookupPromise) {
+    return memoryResourceLookupPromise;
+  }
+
+  const lookupPromise = (async () => {
+    const [agents, domains, systems, services, events, commands, queries, flows, containers, channels, entities, dataProducts] =
+      await Promise.all([
+        getCollection('agents'),
+        getCollection('domains'),
+        getCollection('systems'),
+        getCollection('services'),
+        getCollection('events'),
+        getCollection('commands'),
+        getCollection('queries'),
+        getCollection('flows'),
+        getCollection('containers'),
+        getCollection('channels'),
+        getCollection('entities'),
+        getCollection('data-products'),
+      ]);
+
+    return {
+      agents: buildLookup(agents),
+      domains: buildLookup(domains),
+      systems: buildLookup(systems),
+      services: buildLookup(services),
+      events: buildLookup(events),
+      commands: buildLookup(commands),
+      queries: buildLookup(queries),
+      flows: buildLookup(flows),
+      containers: buildLookup(containers),
+      channels: buildLookup(channels),
+      entities: buildLookup(entities),
+      'data-products': buildLookup(dataProducts),
+    };
+  })();
+
+  if (CACHE_ENABLED) {
+    memoryResourceLookupPromise = lookupPromise;
+  }
+
+  try {
+    const lookups = await lookupPromise;
+    if (CACHE_ENABLED) {
+      memoryResourceLookupCache = lookups;
+    }
+    return lookups;
+  } finally {
+    if (CACHE_ENABLED) {
+      memoryResourceLookupPromise = null;
+    }
+  }
+};
+
+const resolveResourceFromPath = (
+  filePath: string,
+  lookups: Record<ResourceCollection, ResourceLookup>
+): InferredResource | null => {
+  const inferredResource = inferResourceFromFilePath(filePath);
+  if (!inferredResource) {
+    return null;
+  }
+
+  const { resourceCollection, resourceVersion } = inferredResource;
+  const lookup = lookups[resourceCollection];
+
+  // The inferred resourceId is the folder name from the file path. It may differ
+  // from the actual frontmatter id, so fall back to the folderToId mapping.
+  const folderName = inferredResource.resourceId;
+  const resolvedId = lookup.versionsById.has(folderName) ? folderName : (lookup.folderToId.get(folderName) ?? folderName);
+
+  const knownVersions = lookup.versionsById.get(resolvedId);
+
+  if (!knownVersions || knownVersions.size === 0) {
+    return null;
+  }
+
+  const resolvedResourceVersion = resourceVersion === 'latest' ? (lookup.latestById.get(resolvedId) ?? null) : resourceVersion;
+
+  if (!resolvedResourceVersion || !knownVersions.has(resolvedResourceVersion)) {
+    return null;
+  }
+
+  return {
+    resourceCollection,
+    resourceId: resolvedId,
+    resourceVersion: resolvedResourceVersion,
+  };
+};
+
+export const getResourceDocs = async (): Promise<ResourceDocEntry[]> => {
+  if (!isResourceDocsEnabled()) {
+    return [];
+  }
+
+  if (memoryCache && CACHE_ENABLED) {
+    return memoryCache;
+  }
+
+  const [docs, lookups] = await Promise.all([getCollection('resourceDocs'), getResourceLookups()]);
+
+  const docsWithResources = docs
+    .filter((doc) => doc.data.hidden !== true)
+    .map((doc) => {
+      if (!doc.filePath) {
+        return null;
+      }
+
+      if (isMissingGeneratedContentFile(doc.filePath)) {
+        return null;
+      }
+
+      const resolvedResource = resolveResourceFromPath(doc.filePath, lookups);
+      if (!resolvedResource) {
+        return null;
+      }
+
+      const inferredOrder = inferOrderFromFilePath(doc.filePath);
+      const resolvedOrder = typeof doc.data.order === 'number' ? doc.data.order : inferredOrder;
+      const inferredType = inferDocTypeFromFilePath(doc.filePath);
+      const resolvedType = doc.data.type || inferredType || 'pages';
+      const resolvedDocId = doc.data.id || inferDocIdFromFilePath(doc.filePath);
+      const { resourceCollection, resourceId, resourceVersion } = resolvedResource;
+      const resolvedDocVersion = doc.data.version || resourceVersion;
+
+      if (!resolvedDocId) {
+        return null;
+      }
+
+      return {
+        ...doc,
+        data: {
+          ...doc.data,
+          id: resolvedDocId,
+          type: resolvedType,
+          version: resolvedDocVersion,
+          order: resolvedOrder,
+          resourceCollection,
+          resourceId,
+          resourceVersion,
+          versions: [],
+          latestVersion: resolvedDocVersion,
+        },
+      } as ResourceDocEntry;
+    })
+    .filter((doc): doc is ResourceDocEntry => doc !== null);
+
+  const docsByResourceAndId = new Map<string, ResourceDocEntry[]>();
+
+  for (const doc of docsWithResources) {
+    const key = `${doc.data.resourceCollection}:${doc.data.resourceId}:${doc.data.resourceVersion}:${doc.data.type}:${doc.data.id}`;
+    const versions = docsByResourceAndId.get(key) || [];
+    versions.push(doc);
+    docsByResourceAndId.set(key, versions);
+  }
+
+  const enrichedDocs: ResourceDocEntry[] = [];
+
+  for (const docsForResource of docsByResourceAndId.values()) {
+    const sortedByVersion = sortVersioned(docsForResource, (doc) => doc.data.version);
+    const allVersions = sortedByVersion.map((doc) => doc.data.version);
+    const latestVersion = allVersions[0];
+
+    for (const doc of sortedByVersion) {
+      enrichedDocs.push({
+        ...doc,
+        data: {
+          ...doc.data,
+          versions: allVersions,
+          latestVersion,
+        },
+      });
+    }
+  }
+
+  enrichedDocs.sort((a, b) => {
+    const resourceKeyA = `${a.data.resourceCollection}:${a.data.resourceId}:${a.data.resourceVersion}`;
+    const resourceKeyB = `${b.data.resourceCollection}:${b.data.resourceId}:${b.data.resourceVersion}`;
+    if (resourceKeyA !== resourceKeyB) {
+      return resourceKeyA.localeCompare(resourceKeyB);
+    }
+
+    const typeCompare = a.data.type.localeCompare(b.data.type);
+    if (typeCompare !== 0) {
+      return typeCompare;
+    }
+
+    const titleA = (a.data.title || a.data.id).toLowerCase();
+    const titleB = (b.data.title || b.data.id).toLowerCase();
+    if (titleA !== titleB) {
+      return titleA.localeCompare(titleB);
+    }
+
+    const semverA = coerce(a.data.version);
+    const semverB = coerce(b.data.version);
+    if (semverA && semverB) {
+      return rcompare(semverA, semverB);
+    }
+    return b.data.version.localeCompare(a.data.version);
+  });
+
+  memoryCache = enrichedDocs;
+  return enrichedDocs;
+};
+
+export const getResourceDocCategories = async (): Promise<ResourceDocCategoryEntry[]> => {
+  if (!isResourceDocsEnabled()) {
+    return [];
+  }
+
+  if (memoryCategoryCache && CACHE_ENABLED) {
+    return memoryCategoryCache;
+  }
+
+  const [categories, lookups] = await Promise.all([getCollection('resourceDocCategories'), getResourceLookups()]);
+  const categoriesByKey = new Map<string, ResourceDocCategoryEntry>();
+
+  for (const category of categories) {
+    if (!category.filePath) {
+      continue;
+    }
+
+    if (isMissingGeneratedContentFile(category.filePath)) {
+      continue;
+    }
+
+    const resolvedResource = resolveResourceFromPath(category.filePath, lookups);
+    if (!resolvedResource) {
+      continue;
+    }
+
+    const categoryType = inferDocTypeFromFilePath(category.filePath) || 'pages';
+    const key = `${resolvedResource.resourceCollection}:${resolvedResource.resourceId}:${resolvedResource.resourceVersion}:${categoryType}`;
+    const existing = categoriesByKey.get(key);
+
+    const nextEntry: ResourceDocCategoryEntry = {
+      ...category,
+      data: {
+        ...category.data,
+        type: categoryType,
+        resourceCollection: resolvedResource.resourceCollection,
+        resourceId: resolvedResource.resourceId,
+        resourceVersion: resolvedResource.resourceVersion,
+      },
+    };
+
+    if (!existing) {
+      categoriesByKey.set(key, nextEntry);
+      continue;
+    }
+
+    const existingPriority = existing.filePath ? getCategoryFilePriority(existing.filePath) : 0;
+    const nextPriority = getCategoryFilePriority(category.filePath);
+
+    if (nextPriority >= existingPriority) {
+      if (
+        existing.filePath &&
+        category.filePath &&
+        getCategoryFilePriority(existing.filePath) !== getCategoryFilePriority(category.filePath)
+      ) {
+        // Prefer category.json over _category_.json when both exist in the same folder.
+        console.warn(
+          `[resource-docs] Both category.json and _category_.json found for ${key}. Using ${
+            nextPriority > existingPriority ? category.filePath : existing.filePath
+          }.`
+        );
+      }
+      categoriesByKey.set(key, nextEntry);
+    }
+  }
+
+  const resolvedCategories = [...categoriesByKey.values()].sort((a, b) => {
+    const resourceKeyA = `${a.data.resourceCollection}:${a.data.resourceId}:${a.data.resourceVersion}`;
+    const resourceKeyB = `${b.data.resourceCollection}:${b.data.resourceId}:${b.data.resourceVersion}`;
+    if (resourceKeyA !== resourceKeyB) {
+      return resourceKeyA.localeCompare(resourceKeyB);
+    }
+
+    const positionA = typeof a.data.position === 'number' ? a.data.position : Number.POSITIVE_INFINITY;
+    const positionB = typeof b.data.position === 'number' ? b.data.position : Number.POSITIVE_INFINITY;
+    if (positionA !== positionB) {
+      return positionA - positionB;
+    }
+
+    return a.data.type.localeCompare(b.data.type);
+  });
+
+  memoryCategoryCache = resolvedCategories;
+  return resolvedCategories;
+};
+
+export const getResourceDocCategoriesForResource = async (
+  resourceCollection: ResourceCollection,
+  resourceId: string,
+  resourceVersion: string
+): Promise<ResourceDocCategoryEntry[]> => {
+  const categories = await getResourceDocCategories();
+  return categories.filter(
+    (category) =>
+      category.data.resourceCollection === resourceCollection &&
+      category.data.resourceId === resourceId &&
+      category.data.resourceVersion === resourceVersion
+  );
+};
+
+export const getResourceDocsForResource = async (
+  resourceCollection: ResourceCollection,
+  resourceId: string,
+  resourceVersion: string
+): Promise<ResourceDocEntry[]> => {
+  const docs = await getResourceDocs();
+  return docs.filter(
+    (doc) =>
+      doc.data.resourceCollection === resourceCollection &&
+      doc.data.resourceId === resourceId &&
+      doc.data.resourceVersion === resourceVersion
+  );
+};
+
+export const getGroupedResourceDocsByType = (
+  docs: ResourceDocEntry[],
+  { latestOnly = true, categories = [] }: { latestOnly?: boolean; categories?: ResourceDocCategoryEntry[] } = {}
+): ResourceDocGroup[] => {
+  const docsByType = new Map<string, ResourceDocEntry[]>();
+  const categoriesByType = new Map(categories.map((category) => [normalizeTypeName(category.data.type), category]));
+
+  const findCategoryForType = (type: string): ResourceDocCategoryEntry | undefined => {
+    const normalizedType = normalizeTypeName(type);
+    const directMatch = categoriesByType.get(normalizedType);
+    if (directMatch) {
+      return directMatch;
+    }
+
+    if (normalizedType.endsWith('s')) {
+      return categoriesByType.get(normalizedType.slice(0, -1));
+    }
+
+    return categoriesByType.get(`${normalizedType}s`);
+  };
+
+  for (const doc of docs) {
+    if (latestOnly && doc.data.version !== doc.data.latestVersion) {
+      continue;
+    }
+    const list = docsByType.get(doc.data.type) || [];
+    list.push(doc);
+    docsByType.set(doc.data.type, list);
+  }
+
+  return [...docsByType.entries()]
+    .map(([type, typeDocs]) => {
+      const category = findCategoryForType(type);
+      return {
+        type,
+        label: category?.data.label,
+        position: category?.data.position,
+        docs: [...typeDocs].sort((a, b) => {
+          const orderA = typeof a.data.order === 'number' ? a.data.order : Number.POSITIVE_INFINITY;
+          const orderB = typeof b.data.order === 'number' ? b.data.order : Number.POSITIVE_INFINITY;
+
+          if (orderA !== orderB) {
+            return orderA - orderB;
+          }
+
+          const titleA = (a.data.title || a.data.id).toLowerCase();
+          const titleB = (b.data.title || b.data.id).toLowerCase();
+          const titleCompare = titleA.localeCompare(titleB);
+          if (titleCompare !== 0) {
+            return titleCompare;
+          }
+
+          const semverA = coerce(a.data.version);
+          const semverB = coerce(b.data.version);
+          if (semverA && semverB) {
+            return rcompare(semverA, semverB);
+          }
+          return b.data.version.localeCompare(a.data.version);
+        }),
+      };
+    })
+    .sort((a, b) => {
+      const positionA = typeof a.position === 'number' ? a.position : Number.POSITIVE_INFINITY;
+      const positionB = typeof b.position === 'number' ? b.position : Number.POSITIVE_INFINITY;
+
+      if (positionA !== positionB) {
+        return positionA - positionB;
+      }
+
+      return a.type.localeCompare(b.type);
+    });
+};
diff --git a/packages/core/eventcatalog/src/enterprise/collections/resource-docs.ts b/packages/core/eventcatalog/src/enterprise/collections/resource-docs.ts
new file mode 100644
index 000000000..163e4a5aa
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/collections/resource-docs.ts
@@ -0,0 +1,24 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import { z } from 'astro/zod';
+import { badge } from '../../content.config-shared-collections';
+
+export const resourceDocsSchema = z.object({
+  id: z.string().optional(),
+  type: z.string().optional(),
+  version: z.string().optional(),
+  order: z.number().optional(),
+  badges: z.array(badge).optional(),
+  title: z.string().optional(),
+  summary: z.string().optional(),
+  slug: z.string().optional(),
+  hidden: z.boolean().optional(),
+});
+
+export const resourceDocCategoriesSchema = z.object({
+  label: z.string().optional(),
+  position: z.number().optional(),
+});
diff --git a/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/adjacent-pages.spec.ts b/packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/adjacent-pages.spec.ts
similarity index 91%
rename from eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/adjacent-pages.spec.ts
rename to packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/adjacent-pages.spec.ts
index 3a127ab8b..668e679dd 100644
--- a/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/adjacent-pages.spec.ts
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/adjacent-pages.spec.ts
@@ -1,7 +1,12 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
 import { getAdjacentPages } from '../../utils/custom-docs';
 import { vi, describe, it, expect, beforeEach } from 'vitest';
 import { mockDocs } from './mocks';
-import type { ContentCollectionKey } from 'astro:content';
+import type { CollectionKey } from 'astro:content';
 import { join } from 'node:path';
 
 const pathToTestCatalog = join(__dirname, 'fake-catalog');
@@ -47,7 +52,7 @@ vi.mock('@config', async () => {
 vi.mock('astro:content', async (importOriginal) => {
   return {
     ...(await importOriginal<typeof import('astro:content')>()),
-    getEntry: (key: ContentCollectionKey, id: string) => {
+    getEntry: (key: CollectionKey, id: string) => {
       switch (key) {
         case 'customPages':
           return Promise.resolve(mockDocs.find((doc) => doc.id === id));
@@ -55,6 +60,10 @@ vi.mock('astro:content', async (importOriginal) => {
           return Promise.resolve([]);
       }
     },
+    getCollection: (key: CollectionKey) => {
+      if (key === 'customPages') return Promise.resolve(mockDocs);
+      return Promise.resolve([]);
+    },
   };
 });
 
diff --git a/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/custom-docs.spec.ts b/packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/custom-docs.spec.ts
similarity index 93%
rename from eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/custom-docs.spec.ts
rename to packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/custom-docs.spec.ts
index ccd6d9985..0942b85d9 100644
--- a/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/custom-docs.spec.ts
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/custom-docs.spec.ts
@@ -1,7 +1,12 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
 import { join } from 'node:path';
 import { getNavigationItems } from '../../utils/custom-docs';
 import { vi, describe, it, expect, beforeEach } from 'vitest';
-import type { ContentCollectionKey } from 'astro:content';
+import type { CollectionKey } from 'astro:content';
 import { mockDocs } from './mocks';
 
 type Badge = {
@@ -117,28 +122,32 @@ vi.mock('node:fs', () => ({
   },
 }));
 
+const nestedMockDocs = [
+  ...mockDocs,
+  {
+    id: 'docs/nested-docs/getting-started/01-intro',
+    data: { title: 'Introduction to Getting Started', slug: '/nested-docs/getting-started/01-intro' },
+  },
+  {
+    id: 'docs/nested-docs/getting-started/02-setup',
+    data: { title: 'Setup Guide', slug: '/nested-docs/getting-started/02-setup' },
+  },
+  {
+    id: 'docs/nested-docs/advanced',
+    data: { title: 'Advanced Topics', slug: '/nested-docs/advanced' },
+  },
+];
+
 vi.mock('astro:content', async (importOriginal) => {
   return {
     ...(await importOriginal<typeof import('astro:content')>()),
-    getEntry: (key: ContentCollectionKey, id: string) => {
-      // Add mock entries for nested directory structure
-      const nestedMockDocs = [
-        ...mockDocs,
-        {
-          id: 'docs/nested-docs/getting-started/01-intro',
-          data: { title: 'Introduction to Getting Started', slug: '/nested-docs/getting-started/01-intro' },
-        },
-        {
-          id: 'docs/nested-docs/getting-started/02-setup',
-          data: { title: 'Setup Guide', slug: '/nested-docs/getting-started/02-setup' },
-        },
-        {
-          id: 'docs/nested-docs/advanced',
-          data: { title: 'Advanced Topics', slug: '/nested-docs/advanced' },
-        },
-      ];
+    getEntry: (key: CollectionKey, id: string) => {
       return Promise.resolve(nestedMockDocs.find((doc) => doc.id === id));
     },
+    getCollection: (key: CollectionKey) => {
+      if (key === 'customPages') return Promise.resolve(nestedMockDocs);
+      return Promise.resolve([]);
+    },
   };
 });
 
diff --git a/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/fake-catalog/docs/auto-generated/01-introduction.mdx b/packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/fake-catalog/docs/auto-generated/01-introduction.mdx
similarity index 100%
rename from eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/fake-catalog/docs/auto-generated/01-introduction.mdx
rename to packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/fake-catalog/docs/auto-generated/01-introduction.mdx
diff --git a/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/fake-catalog/docs/auto-generated/02-hello-world.mdx b/packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/fake-catalog/docs/auto-generated/02-hello-world.mdx
similarity index 100%
rename from eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/fake-catalog/docs/auto-generated/02-hello-world.mdx
rename to packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/fake-catalog/docs/auto-generated/02-hello-world.mdx
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/mocks.ts b/packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/mocks.ts
new file mode 100644
index 000000000..547d560d3
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/custom-docs/mocks.ts
@@ -0,0 +1,23 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+export const mockDocs = [
+  {
+    id: 'docs/auto-generated/01-introduction',
+    collection: 'docs',
+    data: {
+      title: 'Introduction',
+      description: 'Introduction example',
+    },
+  },
+  {
+    id: 'docs/auto-generated/02-hello-world',
+    collection: 'docs',
+    data: {
+      title: 'Hello World',
+      description: 'Hello World example',
+    },
+  },
+];
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/docs-search.spec.ts b/packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/docs-search.spec.ts
new file mode 100644
index 000000000..83fe2d36b
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/__tests__/docs-search.spec.ts
@@ -0,0 +1,135 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import { describe, it, expect } from 'vitest';
+import { chunkMarkdownByHeadings, buildDocsSearchIndex, extractSnippet } from '../utils/docs-search';
+
+describe('chunkMarkdownByHeadings', () => {
+  it('splits markdown into sections by headings, keeping heading text and content', () => {
+    const markdown = [
+      'Some intro text before any heading.',
+      '',
+      '## Refund failures',
+      'How to handle refund failures.',
+      '',
+      '### Escalation',
+      'Escalate to the payments team.',
+      '',
+      '## Chargeback handling',
+      'Chargebacks are handled weekly.',
+    ].join('\n');
+
+    const chunks = chunkMarkdownByHeadings(markdown);
+
+    expect(chunks).toEqual([
+      { heading: null, content: 'Some intro text before any heading.' },
+      { heading: 'Refund failures', content: 'How to handle refund failures.' },
+      { heading: 'Escalation', content: 'Escalate to the payments team.' },
+      { heading: 'Chargeback handling', content: 'Chargebacks are handled weekly.' },
+    ]);
+  });
+
+  it('returns a single chunk with null heading when there are no headings', () => {
+    const chunks = chunkMarkdownByHeadings('Just a short doc with no headings.');
+    expect(chunks).toEqual([{ heading: null, content: 'Just a short doc with no headings.' }]);
+  });
+
+  it('does not treat lines inside fenced code blocks as headings', () => {
+    const markdown = ['## Setup', '```bash', '# this is a comment, not a heading', 'echo hello', '```', 'Done.'].join('\n');
+
+    const chunks = chunkMarkdownByHeadings(markdown);
+
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0].heading).toBe('Setup');
+    expect(chunks[0].content).toContain('# this is a comment, not a heading');
+  });
+
+  it('returns no chunks for empty markdown', () => {
+    expect(chunkMarkdownByHeadings('')).toEqual([]);
+  });
+});
+
+describe('buildDocsSearchIndex', () => {
+  const docs = [
+    {
+      id: 'docs/payments/runbook',
+      title: 'Payment Runbook',
+      summary: 'How we operate payments',
+      body: [
+        '## Refund failures',
+        'When a refund fails, retry the refund three times.',
+        '## Chargeback handling',
+        'Chargebacks are disputed via the acquirer portal.',
+      ].join('\n'),
+    },
+    {
+      id: 'docs/onboarding',
+      title: 'Onboarding Guide',
+      summary: 'Getting started as a new engineer',
+      body: ['## First week', 'Set up your laptop and request access to the acquirer portal.'].join('\n'),
+    },
+    {
+      id: 'docs/chargebacks',
+      title: 'Chargeback Policy',
+      summary: 'Company policy for chargebacks',
+      body: 'We follow the network rules for all disputes.',
+    },
+  ];
+
+  it('finds documents by terms in the body and returns the matched section heading', () => {
+    const index = buildDocsSearchIndex(docs);
+    const results = index.search('refund fails');
+
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].docId).toBe('docs/payments/runbook');
+    expect(results[0].heading).toBe('Refund failures');
+    expect(results[0].title).toBe('Payment Runbook');
+  });
+
+  it('ranks title matches above body-only matches', () => {
+    const index = buildDocsSearchIndex(docs);
+    const results = index.search('chargeback');
+
+    // 'Chargeback Policy' matches on title; runbook only matches in a section
+    expect(results[0].docId).toBe('docs/chargebacks');
+  });
+
+  it('includes a snippet containing the matched term', () => {
+    const index = buildDocsSearchIndex(docs);
+    const results = index.search('acquirer portal');
+
+    expect(results[0].snippet.toLowerCase()).toContain('acquirer portal');
+  });
+
+  it('returns an empty array when nothing matches', () => {
+    const index = buildDocsSearchIndex(docs);
+    expect(index.search('zzzzz-nonexistent-term')).toEqual([]);
+  });
+
+  it('respects the limit option', () => {
+    const index = buildDocsSearchIndex(docs);
+    const results = index.search('chargeback', { limit: 1 });
+    expect(results).toHaveLength(1);
+  });
+});
+
+describe('extractSnippet', () => {
+  it('returns text around the first matched term with ellipses for long content', () => {
+    const padding = 'lorem ipsum dolor sit amet '.repeat(20);
+    const content = `${padding}the acquirer portal is used for disputes ${padding}`;
+
+    const snippet = extractSnippet(content, 'acquirer');
+
+    expect(snippet).toContain('acquirer portal');
+    expect(snippet.length).toBeLessThan(content.length);
+    expect(snippet.startsWith('…')).toBe(true);
+    expect(snippet.endsWith('…')).toBe(true);
+  });
+
+  it('falls back to the start of the content when no term matches', () => {
+    const content = 'A short description of something.';
+    expect(extractSnippet(content, 'nonexistent')).toBe('A short description of something.');
+  });
+});
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/collection.ts b/packages/core/eventcatalog/src/enterprise/custom-documentation/collection.ts
new file mode 100644
index 000000000..2005854bd
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/collection.ts
@@ -0,0 +1,21 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import { z } from 'astro/zod';
+import { badge, ownerReference } from '../../content.config-shared-collections';
+
+export const customPagesSchema = z.object({
+  title: z.string(),
+  summary: z.string(),
+  slug: z.string().optional(),
+  sidebar: z
+    .object({
+      label: z.string(),
+      order: z.number(),
+    })
+    .optional(),
+  owners: z.array(ownerReference).optional(),
+  badges: z.array(badge).optional(),
+});
diff --git a/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNav.astro b/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNav.astro
similarity index 100%
rename from eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNav.astro
rename to packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNav.astro
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNavWrapper.tsx b/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNavWrapper.tsx
new file mode 100644
index 000000000..446f96613
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNavWrapper.tsx
@@ -0,0 +1,16 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import CustomDocsNav from './';
+import type { SidebarSection } from './types';
+
+interface CustomDocsNavWrapperProps {
+  sidebarItems: SidebarSection[];
+  currentPath: string;
+}
+
+export default function CustomDocsNavWrapper(props: CustomDocsNavWrapperProps) {
+  return <CustomDocsNav {...props} />;
+}
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/components/NestedItem.tsx b/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/components/NestedItem.tsx
new file mode 100644
index 000000000..e1daae68b
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/components/NestedItem.tsx
@@ -0,0 +1,163 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import React from 'react';
+import { buildUrl } from '@utils/url-builder';
+import type { SidebarItem } from '../types';
+import { ExternalLinkIcon } from 'lucide-react';
+import { getCustomDocsSidebarBadgeClasses } from '@enterprise/custom-documentation/utils/badge-styles';
+
+interface NestedItemProps {
+  item: SidebarItem;
+  currentPath: string;
+  parentId: string;
+  itemIndex: number;
+  collapsedGroups: { [key: string]: boolean };
+  toggleGroupCollapse: (group: string) => void;
+}
+
+const NestedItem: React.FC<NestedItemProps> = ({
+  item,
+  currentPath,
+  parentId,
+  itemIndex,
+  collapsedGroups,
+  toggleGroupCollapse,
+}) => {
+  const hasNestedItems = item.items && item.items.length > 0;
+  const itemId = `${parentId}-${itemIndex}`;
+
+  if (hasNestedItems && item.items) {
+    // Check if folder has an index file (slug) making it clickable
+    const folderHasLink = !!item.slug;
+    const folderPath = folderHasLink ? buildUrl(`/docs/custom/${item.slug}`) : undefined;
+    const isFolderActive = folderPath && (currentPath === folderPath || currentPath.endsWith(`/${item.slug}`));
+
+    const badgeClassName = getCustomDocsSidebarBadgeClasses(item.badge?.color);
+
+    return (
+      <div className="py-1">
+        <div className="flex items-center">
+          <button
+            className="p-1 hover:bg-[rgb(var(--ec-content-hover))] rounded-md flex-shrink-0"
+            onClick={(e) => {
+              e.stopPropagation();
+              toggleGroupCollapse(`nested-${itemId}`);
+            }}
+          >
+            <div className={`transition-transform duration-150 ${collapsedGroups[`nested-${itemId}`] ? '' : 'rotate-180'}`}>
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                fill="none"
+                viewBox="0 0 24 24"
+                strokeWidth="1.5"
+                stroke="currentColor"
+                aria-hidden="true"
+                data-slot="icon"
+                className="h-3 w-3 text-[rgb(var(--ec-icon-color))]"
+              >
+                <path strokeLinecap="round" strokeLinejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"></path>
+              </svg>
+            </div>
+          </button>
+          {folderHasLink ? (
+            // Folder has an index file - render as clickable link
+            <a
+              href={folderPath}
+              className={`flex items-center px-2 py-1 text-xs font-medium rounded-md min-w-0 flex-1 ${
+                isFolderActive
+                  ? 'bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-page-text))] font-semibold'
+                  : 'text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-content-hover))]'
+              }`}
+              data-active={isFolderActive}
+            >
+              <span className="truncate">{item.label}</span>
+              {item.badge && item?.badge?.text && <span className={badgeClassName}>{item.badge.text}</span>}
+            </a>
+          ) : (
+            // Folder without index file - render as toggle button
+            <button
+              className="flex items-center px-2 py-1 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] rounded-md hover:bg-[rgb(var(--ec-content-hover))] min-w-0 flex-1"
+              onClick={(e) => {
+                e.stopPropagation();
+                toggleGroupCollapse(`nested-${itemId}`);
+              }}
+            >
+              <span className="truncate">{item.label}</span>
+              {item.badge && item?.badge?.text && <span className={badgeClassName}>{item.badge.text}</span>}
+            </button>
+          )}
+        </div>
+
+        <div
+          className={`overflow-hidden transition-[height] duration-150 ease-out ${
+            collapsedGroups[`nested-${itemId}`] ? 'h-0' : 'h-auto'
+          }`}
+        >
+          <div className="space-y-0.5 border-[rgb(var(--ec-page-border))] border-l pl-4 ml-[9px] mt-1">
+            {item.items.map((nestedItem: SidebarItem, nestedIndex: number) => (
+              <NestedItem
+                key={`nested-${itemId}-${nestedIndex}`}
+                item={nestedItem}
+                currentPath={currentPath}
+                parentId={itemId}
+                itemIndex={nestedIndex}
+                collapsedGroups={collapsedGroups}
+                toggleGroupCollapse={toggleGroupCollapse}
+              />
+            ))}
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  let itemPath = item.slug ? buildUrl(`/docs/custom/${item.slug}`) : '#';
+  const isActive = currentPath === itemPath || currentPath.endsWith(`/${item.slug}`);
+
+  // Convert string style to React CSSProperties if needed
+  const attrs = item.attrs
+    ? {
+        ...item.attrs,
+        style:
+          typeof item.attrs.style === 'string'
+            ? item.attrs.style
+                .split(';')
+                .filter((style) => style.trim())
+                .reduce((acc, style) => {
+                  const [key, value] = style.split(':').map((s) => s.trim());
+                  const camelKey = key.replace(/-([a-z])/g, (g) => g[1].toUpperCase());
+                  return { ...acc, [camelKey]: value };
+                }, {})
+            : item.attrs.style,
+      }
+    : null;
+
+  const isExternalLink = item.slug?.startsWith('http');
+
+  if (isExternalLink && item.slug) {
+    itemPath = item.slug;
+  }
+
+  const badgeClassName = getCustomDocsSidebarBadgeClasses(item.badge?.color);
+
+  return (
+    <a
+      href={itemPath}
+      {...(attrs || {})}
+      className={`flex items-center px-2 py-1.5 text-xs ${isActive ? 'bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-page-text))] font-semibold' : 'text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-content-hover))]'} rounded-md`}
+      data-active={isActive}
+      target={isExternalLink ? '_blank' : undefined}
+    >
+      <span className="truncate flex items-center gap-1.5">
+        {item.label}
+        {isExternalLink && <ExternalLinkIcon className="w-3 -mt-0.5 h-3" />}
+      </span>
+      {item.badge && item?.badge?.text && <span className={badgeClassName}>{item.badge.text}</span>}
+    </a>
+  );
+};
+
+export default React.memo(NestedItem);
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/components/NoResultsFound.tsx b/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/components/NoResultsFound.tsx
new file mode 100644
index 000000000..234651f9e
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/components/NoResultsFound.tsx
@@ -0,0 +1,26 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import React from 'react';
+
+interface NoResultsFoundProps {
+  searchTerm: string;
+}
+
+const NoResultsFound: React.FC<NoResultsFoundProps> = ({ searchTerm }) => (
+  <div className="px-4 py-6 text-center">
+    <div className="text-[rgb(var(--ec-page-text-muted))] text-sm mb-2">No results found for "{searchTerm}"</div>
+    <div className="text-[rgb(var(--ec-page-text-muted))] text-xs">
+      Try:
+      <ul className="mt-2 space-y-1 text-left list-disc pl-4">
+        <li>Checking for typos</li>
+        <li>Using fewer keywords</li>
+        <li>Using more general terms</li>
+      </ul>
+    </div>
+  </div>
+);
+
+export default React.memo(NoResultsFound);
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/index.tsx b/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/index.tsx
new file mode 100644
index 000000000..59acfe2ae
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/index.tsx
@@ -0,0 +1,334 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import React, { useState, useRef, useEffect, useCallback, useMemo } from 'react';
+import { ChevronDoubleDownIcon, ChevronDoubleUpIcon } from '@heroicons/react/24/outline';
+import { buildUrl } from '@utils/url-builder';
+import type { CustomDocsNavProps, SidebarSection, SidebarItem } from './types';
+import NestedItem from './components/NestedItem';
+import NoResultsFound from './components/NoResultsFound';
+import { getCustomDocsSidebarBadgeClasses } from '@enterprise/custom-documentation/utils/badge-styles';
+
+const STORAGE_KEY = 'EventCatalog:customDocsSidebarCollapsedGroups';
+const DEBOUNCE_DELAY = 300; // 300ms debounce delay
+
+const CustomDocsNav: React.FC<CustomDocsNavProps> = ({ sidebarItems }) => {
+  const navRef = useRef<HTMLElement>(null);
+  const [searchTerm, setSearchTerm] = useState('');
+  const [debouncedSearchTerm, setDebouncedSearchTerm] = useState('');
+  const [isInitialized, setIsInitialized] = useState(false);
+  const [isExpanded, setIsExpanded] = useState(true);
+  const [collapsedGroups, setCollapsedGroups] = useState<{ [key: string]: boolean }>(() => {
+    if (typeof window !== 'undefined') {
+      const saved = window.localStorage.getItem(STORAGE_KEY);
+      setIsInitialized(true);
+      return saved ? JSON.parse(saved) : {};
+    }
+    return {};
+  });
+
+  const currentPath = window.location.pathname;
+
+  // Set up debounced search
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedSearchTerm(searchTerm.toLowerCase());
+    }, DEBOUNCE_DELAY);
+
+    return () => clearTimeout(timer);
+  }, [searchTerm]);
+
+  // Filter sidebar items based on search term
+  const filteredSidebarItems = useMemo(() => {
+    if (!debouncedSearchTerm) return sidebarItems;
+
+    const matchesSearchTerm = (text: string) => text.toLowerCase().includes(debouncedSearchTerm);
+
+    // Helper function to check if an item or any of its nested items match the search term
+    const itemContainsSearchTerm = (item: SidebarItem): boolean => {
+      if (matchesSearchTerm(item.label)) return true;
+
+      if (item.items && item.items.length > 0) {
+        return item.items.some(itemContainsSearchTerm);
+      }
+
+      return false;
+    };
+
+    return sidebarItems
+      .map((section) => {
+        if (!section.items) {
+          return matchesSearchTerm(section.label) ? section : null;
+        }
+
+        const filteredItems = section.items.filter(itemContainsSearchTerm);
+
+        if (filteredItems.length > 0 || matchesSearchTerm(section.label)) {
+          return {
+            ...section,
+            items: filteredItems,
+          };
+        }
+
+        return null;
+      })
+      .filter(Boolean) as SidebarSection[];
+  }, [sidebarItems, debouncedSearchTerm]);
+
+  // Auto-expand groups when searching
+  useEffect(() => {
+    if (debouncedSearchTerm) {
+      // Expand all groups when searching
+      const newCollapsedState = { ...collapsedGroups };
+      Object.keys(newCollapsedState).forEach((key) => {
+        newCollapsedState[key] = false;
+      });
+      setCollapsedGroups(newCollapsedState);
+    }
+  }, [debouncedSearchTerm]);
+
+  // Store collapsed groups in local storage
+  useEffect(() => {
+    if (typeof window !== 'undefined' && isInitialized) {
+      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(collapsedGroups));
+    }
+  }, [collapsedGroups, isInitialized]);
+
+  // Initialize collapsed state from section config
+  useEffect(() => {
+    if (isInitialized && sidebarItems && sidebarItems.length > 0) {
+      const initialState = { ...collapsedGroups };
+
+      sidebarItems.forEach((section, index) => {
+        const sectionKey = `section-${index}`;
+        if (section.collapsed !== undefined && initialState[sectionKey] === undefined) {
+          initialState[sectionKey] = section.collapsed;
+        }
+      });
+
+      setCollapsedGroups(initialState);
+    }
+  }, [sidebarItems, isInitialized]);
+
+  // If we find a data-active element, scroll to it on mount
+  useEffect(() => {
+    const activeElement = document.querySelector('[data-active="true"]');
+    if (activeElement) {
+      // Add y offset to the scroll position
+      setTimeout(() => {
+        activeElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      }, 300);
+    }
+  }, []);
+
+  const toggleGroupCollapse = useCallback((group: string) => {
+    setCollapsedGroups((prev) => ({
+      ...prev,
+      [group]: !prev[group],
+    }));
+  }, []);
+
+  const handleSearchChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    setSearchTerm(e.target.value);
+  }, []);
+
+  const collapseAll = useCallback(() => {
+    const newCollapsedState: { [key: string]: boolean } = {};
+
+    // Collapse all sections
+    filteredSidebarItems.forEach((section, index) => {
+      const sectionKey = `section-${index}`;
+      newCollapsedState[sectionKey] = true;
+
+      // Collapse all nested items in the section
+      const collapseNestedItems = (items: SidebarItem[], parentId: string) => {
+        items.forEach((item, itemIndex) => {
+          if (item.items && item.items.length > 0) {
+            const itemKey = `${parentId}-${itemIndex}`;
+            newCollapsedState[itemKey] = true;
+            collapseNestedItems(item.items, itemKey);
+          }
+        });
+      };
+
+      if (section.items) {
+        collapseNestedItems(section.items, sectionKey);
+      }
+    });
+
+    setCollapsedGroups(newCollapsedState);
+    setIsExpanded(false);
+  }, [filteredSidebarItems]);
+
+  const expandAll = useCallback(() => {
+    const newCollapsedState: { [key: string]: boolean } = {};
+
+    // Expand all sections
+    filteredSidebarItems.forEach((section, index) => {
+      const sectionKey = `section-${index}`;
+      newCollapsedState[sectionKey] = false;
+
+      // Expand all nested items in the section
+      const expandNestedItems = (items: SidebarItem[], parentId: string) => {
+        items.forEach((item, itemIndex) => {
+          if (item.items && item.items.length > 0) {
+            const itemKey = `${parentId}-${itemIndex}`;
+            newCollapsedState[itemKey] = false;
+            expandNestedItems(item.items, itemKey);
+          }
+        });
+      };
+
+      if (section.items) {
+        expandNestedItems(section.items, sectionKey);
+      }
+    });
+
+    setCollapsedGroups(newCollapsedState);
+    setIsExpanded(true);
+  }, [filteredSidebarItems]);
+
+  const toggleExpandCollapse = useCallback(() => {
+    if (isExpanded) {
+      collapseAll();
+    } else {
+      expandAll();
+    }
+  }, [isExpanded, collapseAll, expandAll]);
+
+  if (!isInitialized) return null;
+
+  const hasNoResults = debouncedSearchTerm && filteredSidebarItems.length === 0;
+
+  return (
+    <nav ref={navRef} className="flex h-full min-h-0 flex-col text-[rgb(var(--ec-page-text))]">
+      <div className="flex h-[60px] flex-shrink-0 items-center border-b border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-rail-bg))] px-3">
+        <div className="flex w-full gap-2">
+          <input
+            type="text"
+            value={searchTerm}
+            onChange={handleSearchChange}
+            placeholder="Quick search..."
+            className="flex-1 min-w-0 p-2 px-2 text-sm rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-input-bg))] text-[rgb(var(--ec-input-text))] placeholder:text-[rgb(var(--ec-icon-color))] h-[30px] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:border-[rgb(var(--ec-accent))]"
+          />
+          <button
+            onClick={toggleExpandCollapse}
+            title={isExpanded ? 'Collapse All' : 'Expand All'}
+            className="px-2 py-1 bg-[rgb(var(--ec-content-hover))] hover:bg-[rgb(var(--ec-content-active))] rounded-md border border-[rgb(var(--ec-page-border))] h-[30px] flex items-center justify-center"
+          >
+            {isExpanded ? (
+              <ChevronDoubleUpIcon className="h-4 w-4 text-[rgb(var(--ec-icon-color))]" />
+            ) : (
+              <ChevronDoubleDownIcon className="h-4 w-4 text-[rgb(var(--ec-icon-color))]" />
+            )}
+          </button>
+        </div>
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-y-auto">
+        <div className="space-y-2 pb-4 pt-2">
+          {hasNoResults ? (
+            <NoResultsFound searchTerm={debouncedSearchTerm} />
+          ) : (
+            filteredSidebarItems.map((section: SidebarSection, index: number) => {
+              const sectionBadgeClassName = getCustomDocsSidebarBadgeClasses(section.badge?.color);
+              return (
+                <div className="pt-2 pb-2 px-3" key={`section-${index}`}>
+                  <div className="space-y-0" data-section={`section-${index}`}>
+                    {section.items ? (
+                      <div className="flex items-center">
+                        <button
+                          className="p-1 hover:bg-[rgb(var(--ec-content-hover))] rounded-md flex-shrink-0"
+                          onClick={(e) => {
+                            e.stopPropagation();
+                            toggleGroupCollapse(`section-${index}`);
+                          }}
+                        >
+                          <div
+                            className={`transition-transform duration-150 ${collapsedGroups[`section-${index}`] ? '' : 'rotate-180'}`}
+                          >
+                            <svg
+                              xmlns="http://www.w3.org/2000/svg"
+                              fill="none"
+                              viewBox="0 0 24 24"
+                              strokeWidth="1.5"
+                              stroke="currentColor"
+                              aria-hidden="true"
+                              data-slot="icon"
+                              className="h-3 w-3 text-[rgb(var(--ec-icon-color))]"
+                            >
+                              <path strokeLinecap="round" strokeLinejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"></path>
+                            </svg>
+                          </div>
+                        </button>
+                        <button
+                          className="flex items-center justify-between px-2 py-0.5 text-xs font-bold rounded-md hover:bg-[rgb(var(--ec-content-hover))] min-w-0 flex-1"
+                          onClick={(e) => {
+                            e.stopPropagation();
+                            toggleGroupCollapse(`section-${index}`);
+                          }}
+                        >
+                          <span className="truncate">{section.label}</span>
+                          {section.badge && section?.badge?.text && (
+                            <span className={sectionBadgeClassName}>{section.badge.text}</span>
+                          )}
+                        </button>
+                      </div>
+                    ) : (
+                      <div className="flex items-center">
+                        <span className="flex-grow flex items-center justify-between px-2 py-0.5 text-xs font-bold rounded-md">
+                          <span className="truncate">{section.label}</span>
+                          <span className={sectionBadgeClassName}>Section</span>
+                        </span>
+                      </div>
+                    )}
+
+                    {section.items && (
+                      <div
+                        className={`overflow-hidden transition-[height] duration-150 ease-out ${
+                          collapsedGroups[`section-${index}`] ? 'h-0' : 'h-auto'
+                        }`}
+                      >
+                        <div className="space-y-0.5 border-[rgb(var(--ec-page-border))] border-l pl-4 ml-[9px] mt-1">
+                          {section.items.map((item: SidebarItem, itemIndex: number) => (
+                            <NestedItem
+                              key={`item-${index}-${itemIndex}`}
+                              item={item}
+                              currentPath={currentPath}
+                              parentId={`${index}`}
+                              itemIndex={itemIndex}
+                              collapsedGroups={collapsedGroups}
+                              toggleGroupCollapse={toggleGroupCollapse}
+                            />
+                          ))}
+                        </div>
+                      </div>
+                    )}
+
+                    {section.slug && !section.items && (
+                      <a
+                        href={buildUrl(`/docs/custom/${section.slug}`)}
+                        className={`flex items-center px-2 py-1.5 text-xs ${
+                          currentPath.endsWith(`/${section.slug}`)
+                            ? 'bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-page-text))] font-semibold'
+                            : 'text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-content-hover))]'
+                        } rounded-md ml-6`}
+                        data-active={currentPath.endsWith(`/${section.slug}`)}
+                      >
+                        <span className="truncate">{section.label}</span>
+                      </a>
+                    )}
+                  </div>
+                </div>
+              );
+            })
+          )}
+        </div>
+      </div>
+    </nav>
+  );
+};
+
+export default React.memo(CustomDocsNav);
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/types.ts b/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/types.ts
new file mode 100644
index 000000000..6297fe671
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/components/CustomDocsNav/types.ts
@@ -0,0 +1,37 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+export interface SidebarItem {
+  label: string;
+  slug?: string;
+  link?: string;
+  attrs?: Record<string, string>;
+  items?: SidebarItem[];
+  badge?: {
+    text: string;
+    color: string;
+  };
+  collapsed?: boolean;
+}
+
+export interface SidebarSection {
+  label: string;
+  items?: SidebarItem[];
+  slug?: string;
+  autogenerated?: {
+    directory: string;
+    collapsed?: boolean;
+  };
+  badge?: {
+    text: string;
+    color: string;
+  };
+  collapsed?: boolean;
+}
+
+export interface CustomDocsNavProps {
+  sidebarItems: SidebarSection[];
+  currentPath: string;
+}
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/[...path].mdx.ts b/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/[...path].mdx.ts
new file mode 100644
index 000000000..1559cf0a8
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/[...path].mdx.ts
@@ -0,0 +1,36 @@
+// This file exposes the markdown for EventCatalog in the Url
+// For example http://localhost:3000/docs/events/OrderAmended/0.0.1 loads the Page and http://localhost:3000/docs/events/OrderAmended/0.0.1.md loads the markdown
+// This is used for the LLMs to load the markdown for the given item (llms.txt);
+
+import type { APIRoute, GetStaticPaths } from 'astro';
+import { getCollection } from 'astro:content';
+import fs from 'fs';
+import { isLLMSTxtEnabled } from '@utils/feature';
+import { filterMarkdownForAgents } from '@utils/llms';
+
+const docs = await getCollection('customPages');
+
+export const getStaticPaths = (async () => {
+  const paths = docs.map((doc) => ({
+    params: { path: doc.id.replace('docs/', '') },
+    props: doc,
+    type: 'custom',
+  }));
+  return paths;
+}) satisfies GetStaticPaths;
+
+export const GET: APIRoute = async ({ params, props }) => {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  const docPath = Array.isArray(params.path) ? params.path.join('/') : params.path;
+  const content = props?.filePath ? props : docs.find((doc) => doc.id.replace('docs/', '') === docPath);
+  if (content?.filePath) {
+    const file = filterMarkdownForAgents(fs.readFileSync(content.filePath, 'utf8'));
+    return new Response(file, { status: 200 });
+  }
+
+  return new Response('Not found', { status: 404 });
+};
diff --git a/eventcatalog/src/pages/docs/custom/[...path]/_index.data.ts b/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/[...path]/_index.data.ts
similarity index 100%
rename from eventcatalog/src/pages/docs/custom/[...path]/_index.data.ts
rename to packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/[...path]/_index.data.ts
diff --git a/eventcatalog/src/pages/docs/custom/[...path]/index.astro b/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/[...path]/index.astro
similarity index 100%
rename from eventcatalog/src/pages/docs/custom/[...path]/index.astro
rename to packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/[...path]/index.astro
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/feature.astro b/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/feature.astro
new file mode 100644
index 000000000..0305fea2c
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/feature.astro
@@ -0,0 +1,171 @@
+---
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { BookOpenIcon, FileText } from 'lucide-react';
+---
+
+<VerticalSideBarLayout title="Custom Documentation" showNestedSideBar={false}>
+  <div class="min-h-[calc(100vh-60px)] bg-[rgb(var(--ec-page-bg))]">
+    <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-16">
+      {/* Hero Section */}
+      <div class="grid grid-cols-1 lg:grid-cols-2 gap-12 items-center mb-16">
+        <div>
+          <div
+            class="inline-flex items-center px-4 py-2 rounded-full bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent))] font-medium text-sm mb-6"
+          >
+            <FileText className="w-4 h-4 mr-2" />
+            New: Bring your documentation into EventCatalog
+          </div>
+          <h1 class="text-4xl font-bold text-[rgb(var(--ec-page-text))] tracking-tight mb-4">
+            Document Everything. Share Knowledge. Build Better.
+          </h1>
+          <p class="text-xl text-[rgb(var(--ec-page-text-muted))] mb-8">
+            Add your own documentation to EventCatalog — from ADRs and system guides to runbooks and onboarding material. Connect
+            your knowledge to your architecture.
+          </p>
+          <div class="flex flex-col sm:flex-row gap-4 mb-8">
+            <a
+              href="https://demo.eventcatalog.dev/docs/custom/guides/creating-new-microservices/01-index"
+              target="_blank"
+              class="inline-flex items-center justify-center px-6 py-3 border border-transparent text-base font-medium rounded-lg text-[rgb(var(--ec-button-text))] bg-[rgb(var(--ec-button-bg))] hover:opacity-90 transition-colors duration-150"
+            >
+              View the demo
+              <svg class="ml-2 w-4 h-4" viewBox="0 0 20 20" fill="currentColor">
+                <path
+                  fill-rule="evenodd"
+                  d="M10.293 3.293a1 1 0 011.414 0l6 6a1 1 0 010 1.414l-6 6a1 1 0 01-1.414-1.414L14.586 11H3a1 1 0 110-2h11.586l-4.293-4.293a1 1 0 010-1.414z"
+                  clip-rule="evenodd"></path>
+              </svg>
+            </a>
+            <a
+              href="https://www.eventcatalog.cloud"
+              target="_blank"
+              class="inline-flex items-center justify-center px-6 py-3 border border-[rgb(var(--ec-page-border))] text-base font-medium rounded-lg text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-card-bg))] hover:bg-[rgb(var(--ec-content-hover))] transition-colors duration-150"
+            >
+              Try for free
+            </a>
+          </div>
+          <p class="text-sm text-[rgb(var(--ec-page-text-muted))]">
+            Available with EventCatalog Starter or Scale plans
+            <a href="https://www.eventcatalog.dev/pricing" class="text-[rgb(var(--ec-accent))] font-medium block"
+              >Try free for 14 days, no credit card required</a
+            >
+          </p>
+        </div>
+
+        <div class="relative">
+          <div class="absolute -inset-4">
+            <div
+              class="w-full h-full max-w-full mx-auto opacity-30 blur-lg filter"
+              style="background: linear-gradient(90deg, #60A5FA 0%, #3B82F6 100%);"
+            >
+            </div>
+          </div>
+          <div class="relative">
+            <img
+              src="/images/custom-docs-placeholder.png"
+              alt="Custom Documentation Preview"
+              class="rounded-xl shadow-xl border border-[rgb(var(--ec-page-border))]"
+            />
+          </div>
+        </div>
+      </div>
+
+      {/* Features Section */}
+      <div class="grid grid-cols-1 md:grid-cols-3 gap-8">
+        <div class="bg-[rgb(var(--ec-card-bg))] rounded-xl p-6 shadow-xs border border-[rgb(var(--ec-page-border))]">
+          <div class="w-12 h-12 bg-[rgb(var(--ec-accent-subtle))] rounded-lg flex items-center justify-center mb-4">
+            <svg class="w-6 h-6 text-[rgb(var(--ec-accent))]" viewBox="0 0 24 24" fill="currentColor">
+              <path d="M14 2H6c-1.1 0-1.99.9-1.99 2L4 20c0 1.1.89 2 1.99 2H18c1.1 0 2-.9 2-2V8l-6-6zM6 20V4h7v5h5v11H6z"></path>
+            </svg>
+          </div>
+          <h3 class="text-lg font-semibold text-[rgb(var(--ec-page-text))] mb-2">Centralized Knowledge</h3>
+          <p class="text-[rgb(var(--ec-page-text-muted))]">
+            Keep architecture decisions, system guides, and runbooks in one place — easy to access, easy to trust.
+          </p>
+        </div>
+
+        <div class="bg-[rgb(var(--ec-card-bg))] rounded-xl p-6 shadow-xs border border-[rgb(var(--ec-page-border))]">
+          <div class="w-12 h-12 bg-[rgb(var(--ec-accent-subtle))] rounded-lg flex items-center justify-center mb-4">
+            <svg class="w-6 h-6 text-[rgb(var(--ec-accent))]" viewBox="0 0 24 24" fill="currentColor">
+              <path
+                d="M19 3H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm-5 14H7v-2h7v2zm3-4H7v-2h10v2zm0-4H7V7h10v2z"
+              ></path>
+            </svg>
+          </div>
+          <h3 class="text-lg font-semibold text-[rgb(var(--ec-page-text))] mb-2">Rich Formatting</h3>
+          <p class="text-[rgb(var(--ec-page-text-muted))]">
+            Use Markdown, diagrams, code blocks, and EventCatalog components to create structured, useful documentation.
+          </p>
+        </div>
+
+        <div class="bg-[rgb(var(--ec-card-bg))] rounded-xl p-6 shadow-xs border border-[rgb(var(--ec-page-border))]">
+          <div class="w-12 h-12 bg-[rgb(var(--ec-accent-subtle))] rounded-lg flex items-center justify-center mb-4">
+            <svg class="w-6 h-6 text-[rgb(var(--ec-accent))]" viewBox="0 0 24 24" fill="currentColor">
+              <path d="M18 2H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2zM6 4h5v8l-2.5-1.5L6 12V4z"
+              ></path>
+            </svg>
+          </div>
+          <h3 class="text-lg font-semibold text-[rgb(var(--ec-page-text))] mb-2">Version Control</h3>
+          <p class="text-[rgb(var(--ec-page-text-muted))]">
+            Track changes and ensure your documentation grows alongside your system.
+          </p>
+        </div>
+
+        <div class="bg-[rgb(var(--ec-card-bg))] rounded-xl p-6 shadow-xs border border-[rgb(var(--ec-page-border))]">
+          <div class="w-12 h-12 bg-[rgb(var(--ec-accent-subtle))] rounded-lg flex items-center justify-center mb-4">
+            <svg class="w-6 h-6 text-[rgb(var(--ec-accent))]" viewBox="0 0 24 24" fill="currentColor">
+              <path
+                d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z"
+              ></path>
+            </svg>
+          </div>
+          <h3 class="text-lg font-semibold text-[rgb(var(--ec-page-text))] mb-2">Documentation Ownership</h3>
+          <p class="text-[rgb(var(--ec-page-text-muted))]">
+            Assign and track document owners, making it easy to find the right person in seconds.
+          </p>
+        </div>
+
+        <div class="bg-[rgb(var(--ec-card-bg))] rounded-xl p-6 shadow-xs border border-[rgb(var(--ec-page-border))]">
+          <div class="w-12 h-12 bg-[rgb(var(--ec-accent-subtle))] rounded-lg flex items-center justify-center mb-4">
+            <svg class="w-6 h-6 text-[rgb(var(--ec-accent))]" viewBox="0 0 24 24" fill="currentColor">
+              <path d="M3 9h14V7H3v2zm0 4h14v-2H3v2zm0 4h14v-2H3v2zm16 0h2v-2h-2v2zm0-10v2h2V7h-2zm0 6h2v-2h-2v2z"></path>
+            </svg>
+          </div>
+          <h3 class="text-lg font-semibold text-[rgb(var(--ec-page-text))] mb-2">Customizable Sidebars</h3>
+          <p class="text-[rgb(var(--ec-page-text-muted))]">
+            Auto-generated and fully customizable navigation sidebars to organize your documentation perfectly.
+          </p>
+        </div>
+
+        <div class="bg-[rgb(var(--ec-card-bg))] rounded-xl p-6 shadow-xs border border-[rgb(var(--ec-page-border))]">
+          <div class="w-12 h-12 bg-[rgb(var(--ec-accent-subtle))] rounded-lg flex items-center justify-center mb-4">
+            <svg class="w-6 h-6 text-[rgb(var(--ec-accent))]" viewBox="0 0 24 24" fill="currentColor">
+              <path d="M20 2H4c-1.1 0-2 .9-2 2v18l4-4h14c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2zm0 14H6l-2 2V4h16v12z"></path>
+            </svg>
+          </div>
+          <h3 class="text-lg font-semibold text-[rgb(var(--ec-page-text))] mb-2">EventCatalog Chat</h3>
+          <p class="text-[rgb(var(--ec-page-text-muted))]">
+            Interact with your documentation using AI-powered chat to find answers quickly and efficiently.
+          </p>
+        </div>
+      </div>
+
+      {/* Bottom Link */}
+      <div class="mt-16 text-center">
+        <a
+          href="https://www.eventcatalog.dev/docs/development/guides/customize-sidebars/application-sidebar"
+          target="_blank"
+          class="text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors duration-150"
+        >
+          Not ready for custom documentation? You can hide this feature in settings
+        </a>
+      </div>
+    </div>
+  </div>
+</VerticalSideBarLayout>
+
+<style>
+  .scroll-smooth {
+    scroll-behavior: smooth;
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/index.astro b/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/index.astro
new file mode 100644
index 000000000..19855ffc1
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/index.astro
@@ -0,0 +1,463 @@
+---
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { getEntry, render } from 'astro:content';
+import config from '@config';
+import { AlignLeftIcon, UserIcon, UsersIcon } from 'lucide-react';
+
+import mdxComponents from '@components/MDX/components';
+import Badge from '@components/Badge.astro';
+
+import { getOwner } from '@utils/collections/owners';
+import { buildUrl, buildEditUrlForResource } from '@utils/url-builder';
+import { resourceToCollectionMap } from '@utils/collections/util';
+import { getMDXComponentsByName, parseMdxBooleanProp } from '@utils/markdown';
+import { getAdjacentPages, getNavigationItems } from '@enterprise/custom-documentation/utils/custom-docs';
+import CustomDocsNav from '@enterprise/custom-documentation/components/CustomDocsNav/CustomDocsNav.astro';
+import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import CopyAsMarkdown from '@components/CopyAsMarkdown';
+
+import { isVisualiserEnabled, isMarkdownDownloadEnabled, isRSSEnabled, isEventCatalogChatEnabled } from '@utils/feature';
+
+const props = Astro.props;
+const doc = props.data;
+const { Content, headings } = await render(props as any);
+const currentSlug = props.id;
+
+const nodeGraphs =
+  getMDXComponentsByName(props.body, 'NodeGraph')?.filter((nodeGraph: any) => {
+    return nodeGraph.id && nodeGraph.version && nodeGraph.type;
+  }) || [];
+
+const resolvedNodeGraphs = await Promise.all(
+  nodeGraphs.map(async (nodeGraph: any) => {
+    const collection = resourceToCollectionMap[nodeGraph.type as keyof typeof resourceToCollectionMap];
+    const domain = collection === 'domains' ? await getEntry('domains', `${nodeGraph.id}-${nodeGraph.version}`) : undefined;
+    const hasSystems = ((domain?.data as any)?.systems || []).length > 0;
+    const graphCollection = hasSystems ? 'domains-systems-context' : collection;
+
+    return {
+      ...nodeGraph,
+      collection,
+      graphCollection,
+      title: nodeGraph.title ?? (hasSystems ? 'System Context Map' : undefined),
+      hrefLabel: hasSystems ? 'Open System Context Map' : 'Open in Visualiser',
+      visualiserUrl: hasSystems
+        ? buildUrl(`/visualiser/domains/${nodeGraph.id}/${nodeGraph.version}/systems-context`)
+        : buildUrl(`/visualiser/${collection}/${nodeGraph.id}/${nodeGraph.version}`),
+    };
+  })
+);
+
+const { prev, next } = await getAdjacentPages(currentSlug);
+
+const ownersRaw = doc?.owners || [];
+const owners = await Promise.all<ReturnType<typeof getOwner>>(ownersRaw.map(getOwner));
+const filteredOwners = owners.filter((o) => o !== undefined);
+
+const ownersList = filteredOwners.map((o) => ({
+  label: o.data.name,
+  type: o.collection,
+  badge: o.collection === 'users' ? o.data.role : 'Team',
+  avatarUrl: o.collection === 'users' ? o.data.avatarUrl : '',
+  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
+}));
+
+const badges = doc?.badges || [];
+
+// Find the immediate parent group label, for the accent header label above the title.
+// Walks the processed navigation tree (which expands `autogenerated` directories into nested groups)
+// so that nested groups like "Creating new microservices" are surfaced rather than only the top-level section.
+const normalizeSlug = (s: string | undefined) => (s || '').replace(/^\//, '').replace(/^docs\//, '');
+const currentSlugNorm = normalizeSlug(currentSlug);
+const navigationItems = await getNavigationItems();
+
+type NavItem = { label: string; slug?: string; items?: NavItem[] };
+
+const findParentLabel = (items: NavItem[], parentLabel: string): string | null => {
+  for (const item of items) {
+    if (item.slug && normalizeSlug(item.slug) === currentSlugNorm) {
+      return parentLabel;
+    }
+    if (item.items?.length) {
+      const found = findParentLabel(item.items, item.label);
+      if (found !== null) return found;
+    }
+  }
+  return null;
+};
+
+const sectionLabel = findParentLabel(navigationItems as NavItem[], '') || '';
+
+const editUrl =
+  (doc as any)?.editUrl ||
+  (config.editUrl && (props as any)?.filePath ? buildEditUrlForResource(config.editUrl, (props as any).filePath) : '');
+---
+
+<VerticalSideBarLayout title={doc.title || 'Documentation'} showNestedSideBar={false}>
+  <div class="custom-docs-shell flex w-full" data-pagefind-body data-pagefind-meta={`title:${doc.title}`}>
+    <!-- Left Sidebar Navigation -->
+    <aside
+      class="sidebar-transition fixed top-0 bottom-0 left-[var(--ec-vertical-nav-width,14rem)] z-10 w-[var(--ec-custom-docs-sidebar-width,20rem)] overflow-hidden border-r border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-rail-bg))]"
+    >
+      <div class="h-full">
+        <CustomDocsNav />
+      </div>
+    </aside>
+
+    <div class="sidebar-transition flex w-full min-w-0" style="margin-left: var(--ec-custom-docs-sidebar-width, 20rem);">
+      <main class="min-w-0 flex-1">
+        <div
+          class="w-full lg:mr-2 pr-10 py-10 bg-[rgb(var(--ec-page-bg))]"
+          style="padding-left: var(--ec-app-content-padding-left, 5rem);"
+        >
+          <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-4">
+            <div class="flex flex-col gap-4">
+              {
+                sectionLabel && (
+                  <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))] capitalize">{sectionLabel}</span>
+                )
+              }
+              <div class="flex items-center gap-4">
+                <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">
+                  {doc.title}
+                </h2>
+              </div>
+              <p class="text-base text-[rgb(var(--ec-page-text-muted))] font-light">{doc.summary}</p>
+              {
+                badges && badges.length > 0 && (
+                  <div class="flex flex-wrap gap-1.5 py-1">
+                    {badges.map((badge: any) => {
+                      return <Badge badge={badge} />;
+                    })}
+                  </div>
+                )
+              }
+              <CopyAsMarkdown
+                client:only="react"
+                variant="toolbar"
+                schemas={[]}
+                chatEnabled={isEventCatalogChatEnabled()}
+                markdownDownloadEnabled={isMarkdownDownloadEnabled()}
+                rssFeedEnabled={isRSSEnabled()}
+                editUrl={editUrl}
+                preferChatAsDefault={isEventCatalogChatEnabled()}
+              />
+            </div>
+          </div>
+          <div class="prose prose-md max-w-none py-4 w-full text-[15px]">
+            <Content components={{ ...mdxComponents(props) }} />
+          </div>
+
+          {
+            resolvedNodeGraphs.length > 0 &&
+              resolvedNodeGraphs.map((nodeGraph: any) => {
+                return (
+                  <NodeGraph
+                    id={nodeGraph.id}
+                    version={nodeGraph.version}
+                    collection={nodeGraph.graphCollection}
+                    title={nodeGraph.title}
+                    mode={nodeGraph.mode || 'simple'}
+                    linksToVisualiser={true}
+                    showSearch={parseMdxBooleanProp(nodeGraph.search, true)}
+                    showLegend={parseMdxBooleanProp(nodeGraph.legend, true)}
+                    href={
+                      isVisualiserEnabled()
+                        ? {
+                            label: nodeGraph.hrefLabel,
+                            url: nodeGraph.visualiserUrl,
+                          }
+                        : undefined
+                    }
+                  />
+                );
+              })
+          }
+
+          <!-- Previous / Next Navigation -->
+          <div class="py-8 border-t border-[rgb(var(--ec-page-border))] mt-8">
+            <div class="flex flex-col sm:flex-row justify-between w-full gap-4">
+              {
+                prev && (
+                  <a
+                    href={buildUrl(`/docs/custom/${prev.slug}`)}
+                    class="group flex flex-col border border-[rgb(var(--ec-page-border))] rounded-lg p-4 hover:border-[rgb(var(--ec-content-text-muted))] hover:bg-[rgb(var(--ec-content-hover))] transition-colors w-full sm:w-1/2"
+                  >
+                    <span class="text-sm text-[rgb(var(--ec-page-text-muted))] mb-1">Previous</span>
+                    <span class="font-medium text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-accent))] transition-colors">
+                      {prev.label}
+                    </span>
+                  </a>
+                )
+              }
+
+              {!prev && <div class="w-full sm:w-1/2" />}
+
+              {
+                next && (
+                  <a
+                    href={buildUrl(`/docs/custom/${next.slug}`)}
+                    class="group flex flex-col items-end text-right border border-[rgb(var(--ec-page-border))] rounded-lg p-4 hover:border-[rgb(var(--ec-content-text-muted))] hover:bg-[rgb(var(--ec-content-hover))] transition-colors w-full sm:w-1/2"
+                  >
+                    <span class="text-sm text-[rgb(var(--ec-page-text-muted))] mb-1">Next</span>
+                    <span class="font-medium text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-accent))] transition-colors">
+                      {next.label}
+                    </span>
+                  </a>
+                )
+              }
+            </div>
+          </div>
+        </div>
+      </main>
+
+      <!-- Right Sidebar TOC -->
+      <aside
+        id="eventcatalog-docs-sidebar"
+        class="hidden xl:block sticky top-[4rem] self-start w-[200px] max-h-[calc(100vh-4rem)] overflow-y-auto py-2 flex-shrink-0 bg-[rgb(var(--ec-page-bg))]"
+      >
+        <div class="mt-8 space-y-8">
+          {
+            headings.length > 0 && (
+              <div>
+                <h3 class="text-xs text-[rgb(var(--ec-page-text))] font-semibold capitalize flex items-center gap-2 mb-4">
+                  <AlignLeftIcon className="w-4 h-4" />
+                  On this page
+                </h3>
+                <nav class="text-xs border-l border-[rgb(var(--ec-page-border))]">
+                  {headings.map((heading) => {
+                    const level = heading.depth > 2 ? heading.depth : 1;
+                    if (heading.depth > 3) {
+                      return null;
+                    }
+                    return (
+                      <a
+                        href={`#${heading.slug}`}
+                        class="block py-1.5 pr-2.5 leading-5 text-[rgb(var(--ec-page-text-muted))] hover:border-[rgb(var(--ec-page-border))] hover:text-[rgb(var(--ec-page-text))] border-l-2 border-transparent -ml-px transition-all duration-200"
+                        style={`padding-left: ${level * 0.75}rem`}
+                      >
+                        {heading.text}
+                      </a>
+                    );
+                  })}
+                </nav>
+              </div>
+            )
+          }
+          {
+            ownersList.length > 0 && (
+              <div>
+                <h3 class="text-xs text-[rgb(var(--ec-page-text))] font-semibold capitalize mb-4">
+                  {`Document Owners (${ownersList.length})`}
+                </h3>
+                <div class="space-y-2">
+                  {ownersList.map((owner) => (
+                    <a
+                      href={owner.href}
+                      class="flex items-center gap-2 text-xs text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                    >
+                      {owner.type === 'users' ? (
+                        <UserIcon className="h-4 w-4 flex-shrink-0 text-[rgb(var(--ec-page-text-muted))]" />
+                      ) : (
+                        <UsersIcon className="h-4 w-4 flex-shrink-0 text-[rgb(var(--ec-page-text-muted))]" />
+                      )}
+                      <span class="truncate">{owner.label}</span>
+                    </a>
+                  ))}
+                </div>
+              </div>
+            )
+          }
+        </div>
+      </aside>
+    </div>
+  </div>
+</VerticalSideBarLayout>
+
+<style is:global>
+  :root {
+    --ec-custom-docs-sidebar-width: 20rem;
+  }
+
+  #eventcatalog-header {
+    left: calc(var(--ec-vertical-nav-width, 14rem) + var(--ec-custom-docs-sidebar-width, 20rem)) !important;
+  }
+
+  .custom-docs-shell {
+    margin-left: calc(var(--ec-app-content-padding-left, 5rem) * -1);
+    margin-right: calc(var(--ec-app-content-padding-right, 5rem) * -1);
+  }
+
+  .mermaid svg {
+    margin: 1em auto 2em;
+  }
+
+  /* Fix for architecture diagrams */
+  .mermaid[data-content*='architecture'] svg {
+    max-width: 350px !important;
+    margin: 0;
+    /* width: 100px !important; */
+  }
+
+  /* TOC active state - uses accent CSS variable */
+  .toc-active-text {
+    color: rgb(var(--ec-accent));
+  }
+
+  .toc-active-border {
+    border-color: rgb(var(--ec-accent));
+  }
+</style>
+
+<script define:vars={{ props, config }}>
+  // Fix to pass information to componets that are client side only
+  // and require catalog information
+  window.eventcatalog = {};
+  // @ts-ignore
+
+  window.eventcatalog.mermaid = config.mermaid;
+</script>
+
+<script>
+  // @ts-nocheck
+  function setupObserver() {
+    try {
+      const observerOptions = {
+        rootMargin: '0px 0px -40% 0px',
+        threshold: 0.1,
+      };
+
+      // Flag to temporarily disable observer after click
+      let observerPaused = false;
+
+      // Function to highlight a TOC item
+      function highlightTocItem(id: string) {
+        // Remove active class from all links
+        document.querySelectorAll('#eventcatalog-docs-sidebar .active-toc-item').forEach((link) => {
+          link.classList.remove('active-toc-item', 'toc-active-text', 'font-medium', 'toc-active-border');
+          link.classList.add('border-transparent');
+        });
+
+        // Add active class to current link
+        const tocLink = document.querySelector(`#eventcatalog-docs-sidebar nav a[href="#${id}"]`);
+        if (tocLink) {
+          tocLink.classList.add('active-toc-item', 'toc-active-text', 'font-medium', 'toc-active-border');
+          tocLink.classList.remove('border-transparent');
+
+          // Scroll the highlighted item into view with a small delay to ensure DOM updates first
+          setTimeout(() => {
+            tocLink.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' });
+          }, 10);
+        }
+      }
+
+      // Set up the intersection observer for scrolling
+      const observer = new IntersectionObserver((entries) => {
+        // If observer is paused, don't process entries
+        if (observerPaused) return;
+
+        entries.forEach((entry) => {
+          try {
+            const id = entry.target.getAttribute('id');
+            if (entry.isIntersecting && id) {
+              highlightTocItem(id);
+            }
+          } catch (entryError) {
+            console.error('Error processing intersection entry:', entryError);
+          }
+        });
+      }, observerOptions);
+
+      // Find all headings in the content area within the .prose container to observe
+      const prose = document.querySelector('.prose');
+      if (!prose) {
+        console.warn('No .prose container found for TOC highlighting');
+        return;
+      }
+
+      // First try to find headings with IDs
+      const headings = prose.querySelectorAll('h1[id], h2[id], h3[id]');
+
+      if (headings.length > 0) {
+        headings.forEach((heading) => {
+          observer.observe(heading);
+        });
+      } else {
+        // Fallback: If no headings with IDs found, attach IDs to them
+        const allHeadings = prose.querySelectorAll('h1, h2, h3');
+
+        allHeadings.forEach((heading) => {
+          // Only add ID if it doesn't exist
+          if (!heading.id) {
+            const text = heading.textContent || '';
+            const slug = text
+              .toLowerCase()
+              .replace(/[^\w\s-]/g, '')
+              .replace(/\s+/g, '-');
+            heading.id = slug;
+          }
+          observer.observe(heading);
+        });
+      }
+
+      // Add click event listeners to all TOC links
+      const tocLinks = document.querySelectorAll('#eventcatalog-docs-sidebar nav a[href^="#"]');
+      tocLinks.forEach((link) => {
+        link.addEventListener('click', (e) => {
+          // Get the ID from the href attribute
+          const hrefAttr = link.getAttribute('href');
+          if (!hrefAttr) return;
+
+          const id = hrefAttr.substring(1);
+
+          // Highlight the clicked item
+          highlightTocItem(id);
+
+          // Temporarily pause the observer to prevent immediate highlighting changes
+          observerPaused = true;
+
+          // Resume the observer after a delay (1.5 seconds)
+          setTimeout(() => {
+            observerPaused = false;
+          }, 500);
+        });
+      });
+    } catch (error) {
+      console.error('Error setting up TOC highlighting:', error);
+    }
+  }
+
+  setupObserver();
+
+  document.addEventListener('astro:page-load', setupObserver);
+</script>
+
+<script>
+  import { destroyZoomInstances, renderMermaidWithZoom, renderPlantUMLWithZoom } from '@utils/mermaid-zoom';
+
+  function initDiagrams() {
+    destroyZoomInstances();
+
+    const mermaidGraphs = document.getElementsByClassName('mermaid');
+    if (mermaidGraphs.length > 0) {
+      renderMermaidWithZoom(mermaidGraphs, window.eventcatalog?.mermaid);
+    }
+
+    const plantumlBlocks = document.getElementsByClassName('plantuml');
+    if (plantumlBlocks.length > 0) {
+      renderPlantUMLWithZoom(plantumlBlocks);
+    }
+  }
+
+  // Run on initial load and page transitions
+  initDiagrams();
+  document.addEventListener('astro:page-load', initDiagrams);
+
+  // Make available globally for accordion component
+  window.renderDiagrams = (graphs: HTMLCollectionOf<Element>) => {
+    renderMermaidWithZoom(graphs, window.eventcatalog?.mermaid);
+  };
+  window.renderPlantUML = (blocks: HTMLCollectionOf<Element>) => {
+    renderPlantUMLWithZoom(blocks);
+  };
+</script>
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/root-index.astro b/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/root-index.astro
new file mode 100644
index 000000000..7a814ce32
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/pages/docs/custom/root-index.astro
@@ -0,0 +1,245 @@
+---
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { Code } from 'astro-expressive-code/components';
+import { isCustomDocsEnabled } from '@utils/feature';
+
+// Example for folder structure
+const folderStructureExample = `my-catalog/
+  └── docs/
+      ├── getting-started/
+      │   ├── 01-introduction.mdx
+      │   └── 02-quick-start.mdx
+      ├── architecture-decisions/
+      │   ├── 01-what-are-architecture-decisions.mdx
+      │   ├── 02-how-to-create-architecture-decisions.mdx
+      │   ├── published/
+      │   │   ├── 01-adr-001-event-driven.mdx
+      │   │   └── 02-adr-002-api-first.mdx
+      │   └── drafts/
+      │       ├── 01-adr-003-microservices.mdx
+      │       └── 02-adr-004-monolith.mdx
+      └`;
+// Example MDX file content
+const mdxFileExample = `---
+title: Getting Started
+summary: How to get started with our event-driven architecture
+---
+
+# Getting Started with our Event-Driven Architecture
+
+This guide will help you understand how our services communicate using events.
+
+## Prerequisites
+
+- Understanding of basic messaging patterns
+- Node.js installed on your machine
+
+## Key Concepts
+
+Events are the backbone of our architecture. They represent facts that have happened in our system.
+`;
+
+// Example config file
+const configExample = `// eventcatalog.config.js
+  
+module.exports = {
+  // Your existing config...
+  
+  customDocs: {
+    sidebar: [
+      {
+        label: 'Getting Started',
+        badge: {
+          text: 'New', color: 'green'
+        },
+        collapsed: false,
+        items: [
+          { label: 'Introduction', slug: 'getting-started/01-introduction' },
+          { label: 'Quick Start', slug: 'getting-started/02-quick-start' }
+        ]
+      },
+      {
+        label: 'Architecture Decisions',
+        badge: {
+          text: 'New', color: 'green'
+        },
+        collapsed: true,
+        items: [
+          { 
+            label: 'What are Architecture Decisions?', 
+            slug: 'architecture-decisions/01-what-are-architecture-decisions' 
+          },
+          { 
+            label: 'How to Create Architecture Decisions', 
+            slug: 'architecture-decisions/02-how-to-create-architecture-decisions' 
+          },
+          {
+            label: 'Published ADRs',
+            autogenerated: { 
+              directory: 'architecture-decisions/published', 
+              collapsed: true 
+            }
+          },
+          {
+            label: 'Draft ADRs',
+            autogenerated: { 
+              directory: 'architecture-decisions/drafts', 
+              collapsed: true 
+            }
+          }
+        ]
+      }
+    ]
+  }
+}`;
+
+if (!isCustomDocsEnabled()) {
+  return Astro.redirect('/docs/custom/feature');
+}
+---
+
+<VerticalSideBarLayout title="Custom Documentation" showNestedSideBar={false}>
+  <body class="min-h-screen font-inter bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text))]">
+    <main class="container px-8 lg:px-8 mx-auto py-8 max-w-[80em]">
+      <div class="mb-12">
+        <div class="flex flex-col md:flex-row md:items-center md:justify-between gap-6">
+          <div>
+            <div class="flex flex-wrap items-center gap-3 mb-3">
+              <h1 class="text-4xl font-semibold text-[rgb(var(--ec-page-text))] font-inter">Custom Documentation</h1>
+              <div
+                class="inline-flex items-center px-3 py-1.5 rounded-full text-xs font-medium bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent-text))] border border-[rgb(var(--ec-accent)/0.3)] shadow-xs"
+              >
+                Pro feature
+              </div>
+            </div>
+            <p class="text-base mb-0 text-[rgb(var(--ec-page-text-muted))] max-w-3xl">
+              Add custom documentation to EventCatalog to create a unified source of truth for your team. Document your
+              architecture decisions, patterns, and guidelines.
+            </p>
+          </div>
+          <div class="flex space-x-4 shrink-0">
+            <a
+              href="https://www.eventcatalog.dev/docs/development/bring-your-own-documentation/custom-pages/introduction"
+              class="inline-flex items-center justify-center px-5 py-2 border border-[rgb(var(--ec-page-border))] text-sm font-medium rounded-md text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-card-bg))] hover:bg-[rgb(var(--ec-content-hover))] transition-colors"
+            >
+              Read documentation &rarr;
+            </a>
+            {
+              !isCustomDocsEnabled() && (
+                <a
+                  href="https://www.eventcatalog.dev/pro/trial"
+                  class="inline-flex items-center justify-center px-5 py-2 border border-transparent text-sm font-medium rounded-md text-[rgb(var(--ec-button-text))] bg-gradient-to-r from-[rgb(var(--ec-accent-gradient-from))] to-[rgb(var(--ec-accent-gradient-to))] hover:opacity-90 shadow-xs"
+                >
+                  Start 14-day trial
+                </a>
+              )
+            }
+          </div>
+        </div>
+      </div>
+
+      <h2 class="text-2xl font-semibold mb-2 text-[rgb(var(--ec-page-text))]">Setup Guide</h2>
+      <p class="text-[rgb(var(--ec-page-text-muted))] mb-8 max-w-3xl">
+        Custom documentation let's you bring any documentation into EventCatalog. This is useful for documenting your architecture
+        decisions, patterns, and guidelines. Follow these steps to get started:
+      </p>
+
+      <div class="space-y-10 mb-12">
+        <div class="bg-[rgb(var(--ec-card-bg))] p-6 rounded-lg shadow-xs border border-[rgb(var(--ec-page-border))]">
+          <div class="flex items-start gap-4">
+            <div
+              class="inline-flex items-center justify-center w-8 h-8 rounded-full bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent))] text-lg font-medium shrink-0 mt-1"
+            >
+              1
+            </div>
+            <div class="w-full">
+              <h3 class="text-xl font-semibold text-[rgb(var(--ec-page-text))] mb-3">Create the content structure</h3>
+              <p class="text-[rgb(var(--ec-page-text-muted))] mb-4">
+                Create a folder structure in your directory to organize your documentation.
+              </p>
+              <Code code={folderStructureExample} lang="bash" frame="terminal" />
+            </div>
+          </div>
+        </div>
+
+        <div class="bg-[rgb(var(--ec-card-bg))] p-6 rounded-lg shadow-xs border border-[rgb(var(--ec-page-border))]">
+          <div class="flex items-start gap-4">
+            <div
+              class="inline-flex items-center justify-center w-8 h-8 rounded-full bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent))] text-lg font-medium shrink-0 mt-1"
+            >
+              2
+            </div>
+            <div class="w-full">
+              <h3 class="text-xl font-semibold text-[rgb(var(--ec-page-text))] mb-3">Add MDX files</h3>
+              <p class="text-[rgb(var(--ec-page-text-muted))] mb-4">Create MDX files with frontmatter and markdown content.</p>
+              <Code code={mdxFileExample} lang="mdx" frame="terminal" />
+            </div>
+          </div>
+        </div>
+
+        <div class="bg-[rgb(var(--ec-card-bg))] p-6 rounded-lg shadow-xs border border-[rgb(var(--ec-page-border))]">
+          <div class="flex items-start gap-4">
+            <div
+              class="inline-flex items-center justify-center w-8 h-8 rounded-full bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent))] text-lg font-medium shrink-0 mt-1"
+            >
+              3
+            </div>
+            <div class="w-full">
+              <h3 class="text-xl font-semibold text-[rgb(var(--ec-page-text))] mb-3">Update your eventcatalog.config.js file</h3>
+              <p class="text-[rgb(var(--ec-page-text-muted))] mb-4">
+                Add the customDocs configuration to your eventcatalog.config.js file to define your sidebar structure.
+              </p>
+              <Code code={configExample} lang="js" frame="terminal" />
+              <p class="text-[rgb(var(--ec-page-text-muted))] mt-4">
+                This configuration defines the sidebar structure for your custom documentation:
+              </p>
+              <ul class="list-disc list-inside text-[rgb(var(--ec-page-text-muted))] mt-2 ml-2 space-y-1">
+                <li>
+                  <strong>label</strong>: The display name for each sidebar section
+                </li>
+                <li>
+                  <strong>badge</strong>: Optional badge to highlight new sections
+                </li>
+                <li>
+                  <strong>collapsed</strong>: Whether the section is collapsed by default
+                </li>
+                <li>
+                  <strong>autogenerated</strong>: Automatically generate sidebar items from a directory
+                </li>
+                <li>
+                  <strong>slug</strong>: Direct link to a specific page
+                </li>
+              </ul>
+            </div>
+          </div>
+        </div>
+
+        <div class="bg-[rgb(var(--ec-card-bg))] p-6 rounded-lg shadow-xs border border-[rgb(var(--ec-page-border))]">
+          <div class="flex items-start gap-4">
+            <div
+              class="inline-flex items-center justify-center w-8 h-8 rounded-full bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent))] text-lg font-medium shrink-0 mt-1"
+            >
+              4
+            </div>
+            <div class="w-full">
+              <h3 class="text-xl font-semibold text-[rgb(var(--ec-page-text))] mb-3">Restart EventCatalog</h3>
+              <p class="text-[rgb(var(--ec-page-text-muted))] mb-4">
+                After configuring your documentation, restart EventCatalog to see your custom documentation.
+              </p>
+              <div class="mb-4">
+                <Code code="npm run dev" lang="bash" frame="terminal" />
+              </div>
+              <p class="text-[rgb(var(--ec-page-text-muted))] mb-4">
+                Once restarted, you'll see your custom documentation displayed with the sidebar structure you defined:
+              </p>
+              <div class="border border-[rgb(var(--ec-page-border))] rounded-lg overflow-hidden">
+                <img src="/images/custom-docs-placeholder.png" alt="Example of custom documentation interface" class="w-full" />
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </main>
+  </body>
+</VerticalSideBarLayout>
+)
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/utils/badge-styles.ts b/packages/core/eventcatalog/src/enterprise/custom-documentation/utils/badge-styles.ts
new file mode 100644
index 000000000..d02c212e9
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/utils/badge-styles.ts
@@ -0,0 +1,56 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+type ThemeBadgeType = 'domain' | 'service' | 'event' | 'command' | 'query' | 'design' | 'channel' | 'default';
+
+const THEME_BADGE_CLASSES: Record<ThemeBadgeType, string> = {
+  domain: 'bg-[rgb(var(--ec-badge-domain-bg))] text-[rgb(var(--ec-badge-domain-text))]',
+  service: 'bg-[rgb(var(--ec-badge-service-bg))] text-[rgb(var(--ec-badge-service-text))]',
+  event: 'bg-[rgb(var(--ec-badge-event-bg))] text-[rgb(var(--ec-badge-event-text))]',
+  command: 'bg-[rgb(var(--ec-badge-command-bg))] text-[rgb(var(--ec-badge-command-text))]',
+  query: 'bg-[rgb(var(--ec-badge-query-bg))] text-[rgb(var(--ec-badge-query-text))]',
+  design: 'bg-[rgb(var(--ec-badge-design-bg))] text-[rgb(var(--ec-badge-design-text))]',
+  channel: 'bg-[rgb(var(--ec-badge-channel-bg))] text-[rgb(var(--ec-badge-channel-text))]',
+  default: 'bg-[rgb(var(--ec-badge-default-bg))] text-[rgb(var(--ec-badge-default-text))]',
+};
+
+const COLOR_TO_THEME_BADGE: Record<string, ThemeBadgeType> = {
+  yellow: 'domain',
+  amber: 'event',
+  orange: 'event',
+  red: 'event',
+  rose: 'event',
+  pink: 'service',
+  fuchsia: 'service',
+  blue: 'command',
+  sky: 'command',
+  purple: 'query',
+  violet: 'query',
+  cyan: 'query',
+  teal: 'design',
+  green: 'design',
+  emerald: 'design',
+  lime: 'design',
+  indigo: 'channel',
+  slate: 'default',
+  gray: 'default',
+  zinc: 'default',
+  neutral: 'default',
+  stone: 'default',
+};
+
+const getThemeBadgeClasses = (color?: string) => {
+  if (!color) return THEME_BADGE_CLASSES.default;
+  const key = color.trim().toLowerCase();
+  return THEME_BADGE_CLASSES[COLOR_TO_THEME_BADGE[key] || 'default'];
+};
+
+export const getCustomDocsSidebarBadgeClasses = (color?: string) => {
+  return `ml-2 text-[10px] font-medium px-2 py-0.5 rounded uppercase border border-[rgb(var(--ec-page-border))] ${getThemeBadgeClasses(color)}`;
+};
+
+export const getCustomDocsContentBadgeClasses = (color?: string) => {
+  return `inline-flex items-center gap-2 px-3 py-1.5 rounded-lg text-sm font-medium border border-[rgb(var(--ec-page-border))] ${getThemeBadgeClasses(color)}`;
+};
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/utils/custom-docs.ts b/packages/core/eventcatalog/src/enterprise/custom-documentation/utils/custom-docs.ts
new file mode 100644
index 000000000..889c4ae02
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/utils/custom-docs.ts
@@ -0,0 +1,277 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import config from '@config';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getCollection } from 'astro:content';
+import matter from 'gray-matter';
+
+// Use getCollection (which returns plain entries) instead of getEntry, which installs
+// Astro's `slug` deprecation accessor on every entry it returns. The accessor fires a
+// `console.error` on each access of `entry.data.slug`, even though our schema legitimately
+// defines `slug` as an optional user field. See packages/core/eventcatalog/src/enterprise/collections/custom-pages.ts.
+const getCustomPagesById = async () => {
+  const all = await getCollection('customPages');
+  const map = new Map<string, (typeof all)[number]>();
+  for (const e of all) map.set(e.id, e);
+  return map;
+};
+
+type Badge = {
+  text: string;
+  color: string;
+};
+
+type SidebarItem = {
+  label: string;
+  slug?: string;
+  items?: SidebarItem[];
+  badge?: Badge;
+  collapsed?: boolean;
+  link?: string;
+  attrs?: Record<string, string>;
+};
+
+type SideBarConfigurationItem = {
+  label: string;
+  items?: SideBarConfigurationItem[];
+  slug?: string;
+  autogenerated?: {
+    directory: string;
+    collapsed?: boolean;
+  };
+  badge?: Badge;
+  collapsed?: boolean;
+  link?: string;
+  attrs?: Record<string, string>;
+};
+
+type AdjacentPage = {
+  label: string;
+  slug: string;
+};
+
+type AdjacentPages = {
+  prev: AdjacentPage | null;
+  next: AdjacentPage | null;
+};
+
+const DOCS_DIR = 'docs';
+
+/**
+ * Processes auto-generated directory and returns navigation items
+ * If an index.mdx or index.md file exists in the directory, it will be used as the
+ * folder's link target (making the folder clickable) and excluded from the items list.
+ */
+type CustomPagesMap = Awaited<ReturnType<typeof getCustomPagesById>>;
+
+const processAutoGeneratedDirectory = async (
+  directory: string,
+  label: string,
+  badge?: Badge,
+  collapsed?: boolean,
+  customPages?: CustomPagesMap
+): Promise<SidebarItem> => {
+  customPages ??= await getCustomPagesById();
+  // @ts-ignore
+  const items = fs.readdirSync(path.join(process.env.PROJECT_DIR || '', DOCS_DIR, directory));
+
+  const allItems: SidebarItem[] = [];
+  let folderSlug: string | undefined;
+
+  // Check for index file first (index.mdx or index.md)
+  const indexFile = items.find((item: string) => item === 'index.mdx' || item === 'index.md');
+
+  if (indexFile) {
+    const indexPath = path.join(process.env.PROJECT_DIR || '', DOCS_DIR, directory, indexFile);
+    const content = fs.readFileSync(indexPath, 'utf8');
+    const { data } = matter(content);
+
+    // Normalize path separators for cross-platform compatibility
+    // Note: Astro's glob loader strips '/index' from the ID, so docs/foo/index.mdx becomes docs/foo
+    const astroId = data.slug || path.join(DOCS_DIR, directory).replace(/\\/g, '/');
+    const entry = customPages.get(astroId.toLowerCase());
+
+    if (entry) {
+      // Use the index file's slug as the folder's link target
+      folderSlug = entry.data.slug || entry.id.replace(DOCS_DIR, '');
+    }
+  }
+
+  for (const item of items) {
+    // Skip index files - they're used for the folder link, not as child items
+    if (item === 'index.mdx' || item === 'index.md') {
+      continue;
+    }
+
+    const fullPath = path.join(process.env.PROJECT_DIR || '', DOCS_DIR, directory, item);
+    const isDirectory = fs.statSync(fullPath).isDirectory();
+
+    if (isDirectory) {
+      // Recursively process subdirectory
+      const subdirResult = await processAutoGeneratedDirectory(
+        path.join(directory, item),
+        item, // Use directory name as label
+        undefined, // No badge for subdirectories
+        collapsed, // Inherit collapsed state
+        customPages
+      );
+      // Only add the directory if it contains valid items (mdx/md files) or has a slug (index file)
+      if ((subdirResult.items && subdirResult.items.length > 0) || subdirResult.slug) {
+        allItems.push(subdirResult);
+      }
+    } else {
+      // Process file
+      const content = fs.readFileSync(fullPath, 'utf8');
+      const { data } = matter(content);
+
+      // Normalize path separators to forward slashes for cross-platform compatibility (Windows uses backslashes)
+      const astroId =
+        data.slug || path.join(DOCS_DIR, directory, item).replace('.mdx', '').replace('.md', '').replace(/\\/g, '/');
+      const entry = customPages.get(astroId.toLowerCase());
+
+      if (entry) {
+        allItems.push({
+          label: entry.data.title,
+          slug: entry.data.slug || entry.id.replace(DOCS_DIR, ''),
+        });
+      }
+    }
+  }
+
+  return {
+    label,
+    badge,
+    collapsed,
+    ...(folderSlug && { slug: folderSlug }),
+    items: allItems,
+  };
+};
+
+/**
+ * Recursively process sidebar items to handle auto-generated content at any nesting level
+ */
+const processSidebarItems = async (items: SideBarConfigurationItem[], customPages?: CustomPagesMap): Promise<SidebarItem[]> => {
+  customPages ??= await getCustomPagesById();
+  const processedItems: SidebarItem[] = [];
+
+  for (const item of items) {
+    // If item has autogenerated property, process it
+    if (item.autogenerated) {
+      const processedItem = await processAutoGeneratedDirectory(
+        item.autogenerated.directory,
+        item.label,
+        item.badge,
+        item.autogenerated.collapsed !== undefined ? item.autogenerated.collapsed : item.collapsed,
+        customPages
+      );
+      processedItems.push(processedItem);
+    }
+    // If item has nested items, process them recursively
+    else if (item.items && item.items.length > 0) {
+      const processedNestedItems = await processSidebarItems(item.items, customPages);
+      processedItems.push({
+        label: item.label,
+        slug: item.slug,
+        items: processedNestedItems,
+        badge: item.badge,
+        collapsed: item.collapsed,
+      });
+    }
+    // Otherwise, it's a regular item
+    else {
+      // if its a link, add it to the processedItems
+      if (item.link) {
+        processedItems.push({
+          label: item.label,
+          slug: item.link,
+          attrs: item.attrs,
+        });
+      } else {
+        processedItems.push(item as SidebarItem);
+      }
+    }
+  }
+
+  return processedItems;
+};
+
+/**
+ * Flatten all navigation items into a single array of pages with slugs
+ * This is used to find previous and next pages for navigation
+ */
+const flattenNavigationItems = (items: SidebarItem[]): AdjacentPage[] => {
+  const flatPages: AdjacentPage[] = [];
+
+  const processItem = (item: SidebarItem) => {
+    // Add the current item if it has a slug
+    if (item.slug) {
+      flatPages.push({
+        label: item.label,
+        slug: item.slug,
+      });
+    }
+
+    // Process nested items if they exist
+    if (item.items && item.items.length > 0) {
+      item.items.forEach(processItem);
+    }
+  };
+
+  items.forEach(processItem);
+  return flatPages;
+};
+
+/**
+ * Get the previous and next pages for a given slug
+ * Returns null for prev if it's the first page, and null for next if it's the last page
+ */
+export const getAdjacentPages = async (slug: string): Promise<AdjacentPages> => {
+  const navigationItems = await getNavigationItems();
+  const flatPages = flattenNavigationItems(navigationItems);
+
+  // Normalize the slug by removing 'docs/' prefix if it exists
+  // and ensure consistent formatting with or without leading slash
+  let normalizedSlug = slug;
+  if (normalizedSlug.startsWith('docs/')) {
+    normalizedSlug = normalizedSlug.substring(5); // Remove 'docs/' prefix
+  }
+
+  // Find the current page by comparing normalized slugs
+  const currentIndex = flatPages.findIndex((page) => {
+    // Normalize page slug for comparison
+    let pageSlug = page.slug;
+    if (pageSlug.startsWith('/')) {
+      pageSlug = pageSlug.substring(1);
+    }
+
+    return pageSlug === normalizedSlug;
+  });
+
+  // If page not found, return null for both prev and next
+  if (currentIndex === -1) {
+    return { prev: null, next: null };
+  }
+
+  // Get previous page if it exists
+  const prev = currentIndex > 0 ? flatPages[currentIndex - 1] : null;
+
+  // Get next page if it exists
+  const next = currentIndex < flatPages.length - 1 ? flatPages[currentIndex + 1] : null;
+
+  return { prev, next };
+};
+
+export const getNavigationItems = async (): Promise<SidebarItem[]> => {
+  const configuredSidebar = config.customDocs?.sidebar || [];
+  return processSidebarItems(configuredSidebar as SideBarConfigurationItem[]);
+};
+
+export const getFirstNavigationPage = async (): Promise<AdjacentPage | null> => {
+  const navigationItems = await getNavigationItems();
+  const flatPages = flattenNavigationItems(navigationItems);
+  return flatPages[0] || null;
+};
diff --git a/packages/core/eventcatalog/src/enterprise/custom-documentation/utils/docs-search.ts b/packages/core/eventcatalog/src/enterprise/custom-documentation/utils/docs-search.ts
new file mode 100644
index 000000000..2c5781914
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-documentation/utils/docs-search.ts
@@ -0,0 +1,144 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import MiniSearch from 'minisearch';
+
+export type MarkdownChunk = {
+  heading: string | null;
+  content: string;
+};
+
+export type DocForIndexing = {
+  id: string;
+  title: string;
+  summary?: string;
+  body?: string;
+};
+
+export type DocsSearchHit = {
+  docId: string;
+  title: string;
+  heading: string | null;
+  snippet: string;
+  score: number;
+};
+
+export type DocsSearchIndex = {
+  search: (query: string, options?: { limit?: number }) => DocsSearchHit[];
+};
+
+const DEFAULT_SEARCH_LIMIT = 10;
+const SNIPPET_RADIUS = 100;
+
+/**
+ * Splits markdown into section chunks at ATX headings (any level).
+ * Content before the first heading becomes a chunk with a null heading.
+ * Headings inside fenced code blocks are ignored.
+ */
+export const chunkMarkdownByHeadings = (markdown: string): MarkdownChunk[] => {
+  const chunks: MarkdownChunk[] = [];
+  let heading: string | null = null;
+  let buffer: string[] = [];
+  let insideCodeFence = false;
+
+  const flush = () => {
+    const content = buffer.join('\n').trim();
+    if (heading !== null || content) {
+      chunks.push({ heading, content });
+    }
+    buffer = [];
+  };
+
+  for (const line of markdown.split('\n')) {
+    if (/^(```|~~~)/.test(line.trim())) {
+      insideCodeFence = !insideCodeFence;
+    }
+
+    const headingMatch = insideCodeFence ? null : line.match(/^#{1,6}\s+(.+)$/);
+    if (headingMatch) {
+      flush();
+      heading = headingMatch[1].trim();
+    } else {
+      buffer.push(line);
+    }
+  }
+
+  flush();
+  return chunks;
+};
+
+/**
+ * Returns a short excerpt of the content centred on the first query term found.
+ * Falls back to the start of the content when no term matches.
+ */
+export const extractSnippet = (content: string, query: string, radius: number = SNIPPET_RADIUS): string => {
+  const normalized = content.replace(/\s+/g, ' ').trim();
+  const lowercased = normalized.toLowerCase();
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+
+  let matchIndex = -1;
+  for (const term of terms) {
+    matchIndex = lowercased.indexOf(term);
+    if (matchIndex !== -1) break;
+  }
+
+  if (matchIndex === -1) {
+    return normalized.length <= radius * 2 ? normalized : `${normalized.slice(0, radius * 2)}…`;
+  }
+
+  const start = Math.max(0, matchIndex - radius);
+  const end = Math.min(normalized.length, matchIndex + radius);
+  return `${start > 0 ? '…' : ''}${normalized.slice(start, end)}${end < normalized.length ? '…' : ''}`;
+};
+
+/**
+ * Builds an in-memory BM25 search index over custom documentation.
+ * Each document is indexed as one entry per markdown section, so search hits
+ * point at the specific section of a document rather than the whole document.
+ */
+export const buildDocsSearchIndex = (docs: DocForIndexing[]): DocsSearchIndex => {
+  const miniSearch = new MiniSearch({
+    fields: ['title', 'summary', 'heading', 'content'],
+    storeFields: ['docId', 'title', 'heading', 'content'],
+    searchOptions: {
+      boost: { title: 3, heading: 2, summary: 2 },
+      prefix: true,
+    },
+  });
+
+  const sections = docs.flatMap((doc) => {
+    const chunks = chunkMarkdownByHeadings(doc.body ?? '');
+    // Documents with an empty body should still be searchable by title/summary
+    const indexableChunks = chunks.length > 0 ? chunks : [{ heading: null, content: '' }];
+
+    return indexableChunks.map((chunk, index) => ({
+      id: `${doc.id}#${index}`,
+      docId: doc.id,
+      title: doc.title,
+      summary: doc.summary,
+      heading: chunk.heading,
+      content: chunk.content,
+    }));
+  });
+
+  miniSearch.addAll(sections);
+
+  return {
+    search: (query, options = {}) => {
+      const limit = options.limit ?? DEFAULT_SEARCH_LIMIT;
+
+      return miniSearch
+        .search(query)
+        .slice(0, limit)
+        .map((result) => ({
+          docId: result.docId,
+          title: result.title,
+          heading: result.heading ?? null,
+          snippet: extractSnippet(result.content ?? '', query),
+          score: result.score,
+        }));
+    },
+  };
+};
diff --git a/packages/core/eventcatalog/src/enterprise/custom-pages/__tests__/routes.spec.ts b/packages/core/eventcatalog/src/enterprise/custom-pages/__tests__/routes.spec.ts
new file mode 100644
index 000000000..d7668823c
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-pages/__tests__/routes.spec.ts
@@ -0,0 +1,135 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { expect, describe, it, beforeEach, afterEach } from 'vitest';
+import { deriveRoutePattern, getCustomPageRoutes, isApiRoute, listCustomPageFiles, resolveCustomPagesPrefix } from '../routes';
+
+describe('custom-pages routes', () => {
+  describe('resolveCustomPagesPrefix', () => {
+    it('defaults to "custom" when no prefix is configured', () => {
+      expect(resolveCustomPagesPrefix(undefined)).toBe('custom');
+    });
+
+    it('normalizes leading and trailing slashes', () => {
+      expect(resolveCustomPagesPrefix('/internal/')).toBe('internal');
+    });
+
+    it('allows nested prefixes', () => {
+      expect(resolveCustomPagesPrefix('internal/tools')).toBe('internal/tools');
+    });
+
+    it('throws when the prefix is empty', () => {
+      expect(() => resolveCustomPagesPrefix('/')).toThrow('cannot be empty');
+    });
+
+    it('throws when the prefix contains unsafe characters', () => {
+      expect(() => resolveCustomPagesPrefix('my pages')).toThrow('invalid');
+    });
+
+    it('throws when the prefix shadows a core route', () => {
+      expect(() => resolveCustomPagesPrefix('docs')).toThrow('reserved');
+      expect(() => resolveCustomPagesPrefix('api/things')).toThrow('reserved');
+      expect(() => resolveCustomPagesPrefix('Visualiser')).toThrow('reserved');
+    });
+  });
+
+  describe('deriveRoutePattern', () => {
+    it('derives patterns under the prefix', () => {
+      expect(deriveRoutePattern('reports.astro', 'custom')).toBe('/custom/reports');
+      expect(deriveRoutePattern(path.join('team', 'oncall.astro'), 'custom')).toBe('/custom/team/oncall');
+    });
+
+    it('maps index files to their directory', () => {
+      expect(deriveRoutePattern('index.astro', 'custom')).toBe('/custom');
+      expect(deriveRoutePattern(path.join('reports', 'index.astro'), 'custom')).toBe('/custom/reports');
+    });
+
+    it('keeps dynamic segments untouched', () => {
+      expect(deriveRoutePattern(path.join('reports', '[id].astro'), 'custom')).toBe('/custom/reports/[id]');
+      expect(deriveRoutePattern(path.join('docs', '[...slug].astro'), 'custom')).toBe('/custom/docs/[...slug]');
+    });
+
+    it('keeps compound extensions for endpoints', () => {
+      expect(deriveRoutePattern('data.json.ts', 'custom')).toBe('/custom/data.json');
+    });
+  });
+
+  describe('getCustomPageRoutes', () => {
+    let customPagesDir: string;
+
+    beforeEach(() => {
+      customPagesDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ec-custom-pages-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(customPagesDir, { recursive: true, force: true });
+    });
+
+    const write = (relativePath: string, content = '') => {
+      const fullPath = path.join(customPagesDir, relativePath);
+      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+      fs.writeFileSync(fullPath, content);
+    };
+
+    it('returns no routes when the directory does not exist', () => {
+      expect(getCustomPageRoutes(path.join(customPagesDir, 'missing'), 'custom')).toEqual([]);
+    });
+
+    it('returns routes for pages and endpoints', () => {
+      write('reports.astro');
+      write('api/teams.ts');
+
+      const routes = getCustomPageRoutes(customPagesDir, 'custom');
+
+      expect(routes).toEqual(
+        expect.arrayContaining([
+          { pattern: '/custom/reports', file: 'reports.astro', type: 'page' },
+          { pattern: '/custom/api/teams', file: path.join('api', 'teams.ts'), type: 'endpoint' },
+        ])
+      );
+      expect(routes).toHaveLength(2);
+    });
+
+    it('skips the custom landing page', () => {
+      write('homepage.astro');
+      expect(getCustomPageRoutes(customPagesDir, 'custom')).toEqual([]);
+    });
+
+    it('skips underscore-prefixed files and directories', () => {
+      write('_partial.astro');
+      write('_components/Card.astro');
+      write('team/_helpers.ts');
+      write('team/index.astro');
+
+      const routes = getCustomPageRoutes(customPagesDir, 'custom');
+      expect(routes).toEqual([{ pattern: '/custom/team', file: path.join('team', 'index.astro'), type: 'page' }]);
+    });
+
+    it('ignores non-code files', () => {
+      write('notes.md');
+      write('diagram.png');
+      expect(getCustomPageRoutes(customPagesDir, 'custom')).toEqual([]);
+    });
+
+    it('lists routable files sorted, excluding partials and non-code files (used for the dev restart manifest)', () => {
+      write('zebra.astro');
+      write('api/teams.ts');
+      write('_partial.astro');
+      write('notes.md');
+
+      expect(listCustomPageFiles(customPagesDir)).toEqual([path.join('api', 'teams.ts'), 'zebra.astro']);
+    });
+  });
+
+  describe('isApiRoute', () => {
+    it('detects routes in the api directory', () => {
+      expect(isApiRoute({ pattern: '/custom/api/teams', file: path.join('api', 'teams.ts'), type: 'endpoint' })).toBe(true);
+      expect(isApiRoute({ pattern: '/custom/reports', file: 'reports.astro', type: 'page' })).toBe(false);
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/enterprise/custom-pages/routes.ts b/packages/core/eventcatalog/src/enterprise/custom-pages/routes.ts
new file mode 100644
index 000000000..3e8aefc2f
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/custom-pages/routes.ts
@@ -0,0 +1,142 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface CustomPageRoute {
+  /** Route pattern including the configured prefix, e.g. /custom/reports/[id] */
+  pattern: string;
+  /** File path relative to the custom pages directory */
+  file: string;
+  type: 'page' | 'endpoint';
+}
+
+export const DEFAULT_CUSTOM_PAGES_PREFIX = 'custom';
+
+/**
+ * Tracks the routable files during dev so route injection re-runs when files
+ * are added or removed. Never a route itself.
+ */
+export const CUSTOM_PAGES_MANIFEST_FILENAME = '.routes-manifest.json';
+
+const CUSTOM_PAGE_EXTENSIONS = /\.(astro|ts|js|mjs|json)$/i;
+
+/**
+ * Top-level route segments owned by EventCatalog. The custom pages prefix
+ * cannot start with any of these — everything else is collision-free because
+ * all user routes live under the prefix.
+ */
+const RESERVED_PREFIXES = [
+  'api',
+  'api-catalog',
+  'architecture',
+  'auth',
+  'diagrams',
+  'directory',
+  'discover',
+  'docs',
+  'icepanel',
+  'miro',
+  'rss',
+  'schemas',
+  'settings',
+  'studio',
+  'unauthorized',
+  'visualiser',
+  '.well-known',
+];
+
+/**
+ * Normalizes and validates the configured prefix (e.g. 'custom', 'internal/tools').
+ * Throws when the prefix is empty, contains unsafe characters or shadows a core route.
+ */
+export const resolveCustomPagesPrefix = (prefix: string | undefined): string => {
+  const normalized = (prefix ?? DEFAULT_CUSTOM_PAGES_PREFIX).replace(/^\/+|\/+$/g, '');
+
+  if (normalized.length === 0) {
+    throw new Error('[EventCatalog] pages.prefix cannot be empty.');
+  }
+
+  if (!/^[a-zA-Z0-9-_]+(\/[a-zA-Z0-9-_]+)*$/.test(normalized)) {
+    throw new Error(
+      `[EventCatalog] pages.prefix "${prefix}" is invalid. Use URL-safe characters (letters, numbers, - and _), optionally separated by "/".`
+    );
+  }
+
+  const firstSegment = normalized.split('/')[0].toLowerCase();
+  if (RESERVED_PREFIXES.includes(firstSegment)) {
+    throw new Error(`[EventCatalog] pages.prefix "${prefix}" is reserved by EventCatalog. Choose a different prefix.`);
+  }
+
+  return normalized;
+};
+
+/**
+ * Derives an Astro route pattern from a file path relative to the custom pages
+ * directory. Dynamic segments ([id], [...slug]) pass through untouched.
+ */
+export const deriveRoutePattern = (relativeFilePath: string, prefix: string): string => {
+  const withoutExtension = relativeFilePath.replace(CUSTOM_PAGE_EXTENSIONS, '');
+  const segments = withoutExtension.split(/[\\/]/).filter(Boolean);
+
+  if (segments[segments.length - 1] === 'index') {
+    segments.pop();
+  }
+
+  return `/${[prefix, ...segments].join('/')}`;
+};
+
+const walkDirectory = (directory: string, relativeTo: string): string[] => {
+  const files: string[] = [];
+
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const fullPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkDirectory(fullPath, relativeTo));
+    } else if (entry.isFile()) {
+      files.push(path.relative(relativeTo, fullPath));
+    }
+  }
+
+  return files;
+};
+
+/**
+ * Lists the routable code files in the custom pages directory (sorted, relative paths).
+ * Underscore-prefixed files and directories follow the Astro convention: they are
+ * never routable (partials, helpers, colocated components).
+ */
+export const listCustomPageFiles = (customPagesDir: string): string[] => {
+  if (!fs.existsSync(customPagesDir)) return [];
+
+  return walkDirectory(customPagesDir, customPagesDir)
+    .filter((file) => CUSTOM_PAGE_EXTENSIONS.test(file))
+    .filter((file) => file !== CUSTOM_PAGES_MANIFEST_FILENAME)
+    .filter((file) => !file.split(path.sep).some((segment) => segment.startsWith('_')))
+    .sort();
+};
+
+/**
+ * Reads the custom pages directory and returns the routes to inject.
+ */
+export const getCustomPageRoutes = (customPagesDir: string, prefix: string): CustomPageRoute[] => {
+  const routes: CustomPageRoute[] = [];
+
+  for (const file of listCustomPageFiles(customPagesDir)) {
+    // pages/homepage.astro is the custom landing page, rendered by src/pages/index.astro
+    if (file === 'homepage.astro') continue;
+
+    routes.push({
+      pattern: deriveRoutePattern(file, prefix),
+      file,
+      type: file.toLowerCase().endsWith('.astro') ? 'page' : 'endpoint',
+    });
+  }
+
+  return routes;
+};
+
+export const isApiRoute = (route: CustomPageRoute): boolean => route.file.split(path.sep)[0] === 'api';
diff --git a/packages/core/eventcatalog/src/enterprise/directory/user-team-directory.spec.ts b/packages/core/eventcatalog/src/enterprise/directory/user-team-directory.spec.ts
new file mode 100644
index 000000000..838bfd6e1
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/directory/user-team-directory.spec.ts
@@ -0,0 +1,527 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const localLoad = vi.fn();
+const isEventCatalogScaleEnabled = vi.fn();
+const consoleLog = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+
+vi.mock('astro/loaders', () => ({
+  glob: vi.fn(() => ({
+    name: 'mock-glob-loader',
+    load: localLoad,
+  })),
+}));
+
+vi.mock('../feature', () => ({
+  isEventCatalogScaleEnabled: () => isEventCatalogScaleEnabled(),
+}));
+
+import { userTeamDirectoryLoader } from './user-team-directory';
+
+const createContentStore = () => {
+  const entries = new Map<string, unknown>();
+
+  return {
+    has: (id: string) => entries.has(id),
+    set: (entry: { id: string; [key: string]: unknown }) => entries.set(entry.id, entry),
+    get: (id: string) => entries.get(id),
+    clear: () => entries.clear(),
+  };
+};
+
+const createContext = () => ({
+  store: createContentStore(),
+  meta: new Map<string, string>(),
+  parseData: vi.fn(async ({ data }) => data),
+  renderMarkdown: vi.fn(async (markdown) => ({
+    html: `<p>${markdown}</p>`,
+    metadata: {
+      headings: [],
+      localImagePaths: [],
+      remoteImagePaths: [],
+      frontmatter: {},
+      imagePaths: [],
+    },
+  })),
+  generateDigest: vi.fn((data) => JSON.stringify(data)),
+  logger: {
+    info: vi.fn(),
+    warn: vi.fn(),
+  },
+});
+
+describe('userTeamDirectoryLoader', () => {
+  beforeEach(() => {
+    localLoad.mockReset();
+    isEventCatalogScaleEnabled.mockReset();
+    isEventCatalogScaleEnabled.mockReturnValue(false);
+    consoleLog.mockClear();
+  });
+
+  it('loads local users without requiring EventCatalog Scale when no directory sources are configured', async () => {
+    const context = createContext();
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: '/catalog',
+      },
+    });
+
+    await loader.load(context as never);
+
+    expect(localLoad).toHaveBeenCalledWith(context);
+    expect(isEventCatalogScaleEnabled).not.toHaveBeenCalled();
+  });
+
+  it('requires EventCatalog Scale when directory sources are configured', async () => {
+    const context = createContext();
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: '/catalog',
+      },
+      storePath: false,
+      sources: [
+        {
+          type: 'directory',
+          name: 'test-source',
+          loadUsers: async () => [],
+        },
+      ],
+    });
+
+    await expect(loader.load(context as never)).rejects.toThrow('Directory sources require EventCatalog Scale.');
+  });
+
+  it('loads users from configured directory sources', async () => {
+    isEventCatalogScaleEnabled.mockReturnValue(true);
+    const context = createContext();
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: '/catalog',
+      },
+      storePath: false,
+      sources: [
+        {
+          type: 'directory',
+          name: 'test-source',
+          loadUsers: async () => [
+            {
+              id: 'jane',
+              name: 'Jane Doe',
+              avatarUrl: 'https://example.com/jane.png',
+              markdown: '# Jane',
+              source: {
+                provider: 'github',
+                id: 'github-user-123',
+                url: 'https://github.com/jane',
+              },
+            },
+          ],
+        },
+      ],
+    });
+
+    await loader.load(context as never);
+
+    expect(context.parseData).toHaveBeenCalledWith({
+      id: 'jane',
+      data: {
+        id: 'jane',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jane.png',
+        source: {
+          provider: 'github',
+          id: 'github-user-123',
+          url: 'https://github.com/jane',
+        },
+        readOnly: true,
+      },
+    });
+    expect(context.store.get('jane')).toEqual({
+      id: 'jane',
+      data: {
+        id: 'jane',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jane.png',
+        source: {
+          provider: 'github',
+          id: 'github-user-123',
+          url: 'https://github.com/jane',
+        },
+        readOnly: true,
+      },
+      body: '# Jane',
+      rendered: {
+        html: '<p># Jane</p>',
+        metadata: {
+          headings: [],
+          localImagePaths: [],
+          remoteImagePaths: [],
+          frontmatter: {},
+          imagePaths: [],
+        },
+      },
+      digest: JSON.stringify({
+        id: 'jane',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jane.png',
+        source: {
+          provider: 'github',
+          id: 'github-user-123',
+          url: 'https://github.com/jane',
+        },
+        readOnly: true,
+        body: '# Jane',
+      }),
+    });
+    expect(consoleLog).toHaveBeenCalledWith(expect.stringContaining('Loading users from directory source "test-source"'));
+    expect(consoleLog).toHaveBeenCalledWith(expect.stringContaining('Synced 1 users from directory source "test-source"'));
+  });
+
+  it('keeps local entries when the conflict strategy is local-wins', async () => {
+    isEventCatalogScaleEnabled.mockReturnValue(true);
+    const context = createContext();
+    context.store.set({
+      id: 'jane',
+      data: {
+        id: 'jane',
+        name: 'Local Jane',
+      },
+    });
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: '/catalog',
+      },
+      storePath: false,
+      sources: [
+        {
+          type: 'directory',
+          name: 'test-source',
+          loadUsers: async () => [
+            {
+              id: 'jane',
+              name: 'Source Jane',
+              avatarUrl: 'https://example.com/jane.png',
+            },
+          ],
+        },
+      ],
+    });
+
+    await loader.load(context as never);
+
+    expect(context.store.get('jane')).toEqual({
+      id: 'jane',
+      data: {
+        id: 'jane',
+        name: 'Local Jane',
+      },
+    });
+    expect(consoleLog).toHaveBeenCalledWith(
+      expect.stringContaining('Synced 0 users from directory source "test-source" (1 skipped due to local conflicts)')
+    );
+  });
+
+  it('throws when the conflict strategy is error and a source returns a local id', async () => {
+    isEventCatalogScaleEnabled.mockReturnValue(true);
+    const context = createContext();
+    context.store.set({
+      id: 'jane',
+      data: {
+        id: 'jane',
+        name: 'Local Jane',
+      },
+    });
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: '/catalog',
+      },
+      conflictStrategy: 'error',
+      storePath: false,
+      sources: [
+        {
+          type: 'directory',
+          name: 'test-source',
+          loadUsers: async () => [
+            {
+              id: 'jane',
+              name: 'Source Jane',
+              avatarUrl: 'https://example.com/jane.png',
+            },
+          ],
+        },
+      ],
+    });
+
+    await expect(loader.load(context as never)).rejects.toThrow(
+      'Directory source "test-source" returned duplicate users id "jane".'
+    );
+  });
+
+  it('refreshes source entries on subsequent loads', async () => {
+    isEventCatalogScaleEnabled.mockReturnValue(true);
+    const context = createContext();
+    const loadUsers = vi
+      .fn()
+      .mockResolvedValueOnce([
+        {
+          id: 'jane',
+          name: 'Jane Doe',
+          avatarUrl: 'https://example.com/jane.png',
+        },
+      ])
+      .mockResolvedValueOnce([
+        {
+          id: 'jane',
+          name: 'Jane Updated',
+          avatarUrl: 'https://example.com/jane-updated.png',
+        },
+      ]);
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: '/catalog',
+      },
+      storePath: false,
+      sources: [
+        {
+          type: 'directory',
+          name: 'test-source',
+          loadUsers,
+        },
+      ],
+    });
+
+    await loader.load(context as never);
+    context.store.clear();
+    await loader.load(context as never);
+
+    expect(loadUsers).toHaveBeenCalledTimes(2);
+    expect(context.store.get('jane')).toMatchObject({
+      data: {
+        name: 'Jane Updated',
+        avatarUrl: 'https://example.com/jane-updated.png',
+      },
+    });
+  });
+
+  it('writes synced source entries to the EventCatalog directory store', async () => {
+    isEventCatalogScaleEnabled.mockReturnValue(true);
+    const context = createContext();
+    const tempDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-directory-store-'));
+    const storePath = path.join(tempDir, '.eventcatalog', 'store', 'directory.json');
+    const loader = userTeamDirectoryLoader({
+      collection: 'teams',
+      local: {
+        pattern: 'teams/*.(md|mdx)',
+        base: tempDir,
+      },
+      storePath,
+      sources: [
+        {
+          type: 'directory',
+          name: 'github:event-catalog',
+          loadTeams: async () => [
+            {
+              id: 'core-maintainers',
+              name: 'Core Maintainers',
+              markdown: '# Core Maintainers',
+              source: {
+                provider: 'github',
+                id: 'github-team-123',
+                url: 'https://github.com/orgs/event-catalog/teams/core-maintainers',
+              },
+            },
+          ],
+        },
+      ],
+    });
+
+    try {
+      await loader.load(context as never);
+
+      const store = JSON.parse(await readFile(storePath, 'utf8'));
+      expect(store).toMatchObject({
+        version: '1',
+        resources: {
+          users: [],
+          teams: [
+            {
+              id: 'core-maintainers',
+              name: 'Core Maintainers',
+              markdown: '# Core Maintainers',
+              readOnly: true,
+              source: {
+                provider: 'github',
+                id: 'github-team-123',
+                url: 'https://github.com/orgs/event-catalog/teams/core-maintainers',
+              },
+            },
+          ],
+        },
+      });
+      expect(store.generatedAt).toEqual(expect.any(String));
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it('deduplicates synced store entries when source-wins replaces an earlier directory source entry', async () => {
+    isEventCatalogScaleEnabled.mockReturnValue(true);
+    const context = createContext();
+    const tempDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-directory-store-'));
+    const storePath = path.join(tempDir, '.eventcatalog', 'store', 'directory.json');
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: tempDir,
+      },
+      conflictStrategy: 'source-wins',
+      storePath,
+      sources: [
+        {
+          type: 'directory',
+          name: 'github:first',
+          loadUsers: async () => [
+            {
+              id: 'jane',
+              name: 'Jane From First Source',
+              markdown: 'First source Jane',
+              source: {
+                provider: 'github',
+                id: 'first-source-jane',
+              },
+            },
+          ],
+        },
+        {
+          type: 'directory',
+          name: 'github:second',
+          loadUsers: async () => [
+            {
+              id: 'jane',
+              name: 'Jane From Second Source',
+              markdown: 'Second source Jane',
+              source: {
+                provider: 'github',
+                id: 'second-source-jane',
+              },
+            },
+          ],
+        },
+      ],
+    });
+
+    try {
+      await loader.load(context as never);
+
+      const store = JSON.parse(await readFile(storePath, 'utf8'));
+      expect(store.resources.users).toEqual([
+        {
+          id: 'jane',
+          name: 'Jane From Second Source',
+          markdown: 'Second source Jane',
+          readOnly: true,
+          source: {
+            provider: 'github',
+            id: 'second-source-jane',
+          },
+        },
+      ]);
+      expect(context.store.get('jane')).toMatchObject({
+        data: {
+          id: 'jane',
+          name: 'Jane From Second Source',
+          source: {
+            provider: 'github',
+            id: 'second-source-jane',
+          },
+          readOnly: true,
+        },
+        body: 'Second source Jane',
+      });
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it('clears an existing directory store collection when sources are removed', async () => {
+    const context = createContext();
+    const tempDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-directory-store-'));
+    const storePath = path.join(tempDir, '.eventcatalog', 'store', 'directory.json');
+    const loader = userTeamDirectoryLoader({
+      collection: 'users',
+      local: {
+        pattern: 'users/*.(md|mdx)',
+        base: tempDir,
+      },
+      storePath,
+    });
+
+    try {
+      await mkdir(path.dirname(storePath), { recursive: true });
+      await writeFile(
+        storePath,
+        JSON.stringify({
+          version: '1',
+          generatedAt: '2026-05-27T00:00:00.000Z',
+          resources: {
+            users: [
+              {
+                id: 'stale-user',
+                name: 'Stale User',
+                markdown: 'Stale directory user',
+                readOnly: true,
+                source: {
+                  provider: 'github',
+                },
+              },
+            ],
+            teams: [
+              {
+                id: 'existing-team',
+                name: 'Existing Team',
+                markdown: 'Existing directory team',
+                readOnly: true,
+                source: {
+                  provider: 'github',
+                },
+              },
+            ],
+          },
+        })
+      );
+
+      await loader.load(context as never);
+
+      const store = JSON.parse(await readFile(storePath, 'utf8'));
+      expect(store.resources.users).toEqual([]);
+      expect(store.resources.teams).toEqual([
+        {
+          id: 'existing-team',
+          name: 'Existing Team',
+          markdown: 'Existing directory team',
+          readOnly: true,
+          source: {
+            provider: 'github',
+          },
+        },
+      ]);
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/core/eventcatalog/src/enterprise/directory/user-team-directory.ts b/packages/core/eventcatalog/src/enterprise/directory/user-team-directory.ts
new file mode 100644
index 000000000..9dedda19b
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/directory/user-team-directory.ts
@@ -0,0 +1,191 @@
+import type { Loader } from 'astro/loaders';
+import pc from 'picocolors';
+import { isEventCatalogScaleEnabled } from '../feature';
+import { EventCatalogStore } from '../../stores/eventcatalog-store';
+import { globWithSafeWatcher, type GlobOptions } from '../../utils/collections/glob-loader';
+
+const colors = pc.createColors(true);
+
+type UserTeamCollection = 'users' | 'teams';
+
+type DirectoryEntry = {
+  id: string;
+  markdown?: string;
+  readOnly?: boolean;
+  source?: {
+    provider?: string;
+    url?: string;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+};
+
+type DirectorySource = {
+  type: 'directory';
+  name: string;
+  loadUsers?: () => Promise<DirectoryEntry[]>;
+  loadTeams?: () => Promise<DirectoryEntry[]>;
+};
+
+type DirectoryConflictStrategy = 'local-wins' | 'source-wins' | 'error';
+
+type UserTeamDirectoryLoaderOptions = {
+  collection: UserTeamCollection;
+  local: GlobOptions;
+  sources?: DirectorySource[];
+  conflictStrategy?: DirectoryConflictStrategy;
+  storePath?: string | false;
+};
+
+type DirectoryStoreResource = DirectoryEntry & {
+  id: string;
+  markdown: string;
+  readOnly: true;
+  source: NonNullable<DirectoryEntry['source']> & {
+    provider: string;
+  };
+};
+
+type DirectoryStoreResources = {
+  users: DirectoryStoreResource[];
+  teams: DirectoryStoreResource[];
+};
+
+export const userTeamDirectoryLoader = ({
+  collection,
+  local,
+  sources = [],
+  conflictStrategy = 'local-wins',
+  storePath,
+}: UserTeamDirectoryLoaderOptions): Loader => {
+  const localLoader = globWithSafeWatcher(local);
+  const directoryStore = createDirectoryStore({ base: local.base, storePath });
+
+  return {
+    name: `eventcatalog-${collection}-directory-loader`,
+    load: async (context) => {
+      await localLoader.load(context);
+
+      if (sources.length === 0) {
+        await directoryStore?.clearCollectionIfStoreExists(collection);
+        return;
+      }
+
+      if (!isEventCatalogScaleEnabled()) {
+        throw new Error('Directory sources require EventCatalog Scale.');
+      }
+
+      const loadEntries = collection === 'users' ? 'loadUsers' : 'loadTeams';
+      const syncedDirectoryStoreResources = new Map<string, DirectoryStoreResource>();
+
+      for (const source of sources) {
+        logDirectoryInfo(`Loading ${collection} from directory source "${source.name}"`);
+        const entries = await loadSourceEntries({ source, loadEntries });
+        let syncedEntries = 0;
+        let skippedEntries = 0;
+
+        for (const entry of entries) {
+          if (context.store.has(entry.id)) {
+            if (conflictStrategy === 'local-wins') {
+              skippedEntries += 1;
+              continue;
+            }
+            if (conflictStrategy === 'error') {
+              throw new Error(`Directory source "${source.name}" returned duplicate ${collection} id "${entry.id}".`);
+            }
+          }
+
+          const { markdown, ...entryData } = entry;
+          const data = {
+            ...withDirectoryEntrySource(entryData, source),
+            id: entry.id,
+            readOnly: true,
+          };
+          const body = markdown ?? '';
+          const rendered = body ? await context.renderMarkdown(body) : undefined;
+          const parsedData = await context.parseData({
+            id: entry.id,
+            data,
+          });
+          syncedDirectoryStoreResources.set(entry.id, {
+            ...data,
+            markdown: body,
+            readOnly: true,
+          });
+
+          context.store.set({
+            id: entry.id,
+            data: parsedData,
+            body,
+            digest: context.generateDigest({ ...data, body }),
+            rendered,
+          });
+          syncedEntries += 1;
+        }
+
+        logDirectoryInfo(
+          `Synced ${syncedEntries} ${collection} from directory source "${source.name}"${
+            skippedEntries > 0 ? ` (${skippedEntries} skipped due to local conflicts)` : ''
+          }`
+        );
+      }
+
+      await directoryStore?.writeCollection(collection, Array.from(syncedDirectoryStoreResources.values()));
+    },
+  };
+};
+
+const loadSourceEntries = async ({
+  source,
+  loadEntries,
+}: {
+  source: DirectorySource;
+  loadEntries: 'loadUsers' | 'loadTeams';
+}) => {
+  return (await source[loadEntries]?.()) ?? [];
+};
+
+const getSourceProvider = (source: DirectorySource) => source.name.split(':')[0] || source.name;
+
+const withDirectoryEntrySource = (entryData: Omit<DirectoryEntry, 'markdown'>, source: DirectorySource) => {
+  const entrySource = entryData.source as DirectoryEntry['source'] | undefined;
+  const provider = entrySource?.provider ?? getSourceProvider(source);
+  const sourceData = {
+    ...entrySource,
+    provider,
+  };
+
+  return {
+    ...entryData,
+    source: sourceData,
+  };
+};
+
+const getDirectoryStorePath = (base: GlobOptions['base']) => {
+  if (!base || typeof base !== 'string') return undefined;
+  return EventCatalogStore.getStorePath(base, 'directory');
+};
+
+const createDirectoryStore = ({ base, storePath }: { base: GlobOptions['base']; storePath?: string | false }) => {
+  if (storePath === false) return undefined;
+
+  const resolvedStorePath = storePath ?? getDirectoryStorePath(base);
+  if (!resolvedStorePath) return undefined;
+
+  return new EventCatalogStore<DirectoryStoreResources>({
+    storePath: resolvedStorePath,
+    resources: {
+      users: [],
+      teams: [],
+    },
+  });
+};
+
+const getTimestamp = () => {
+  const now = new Date();
+  return now.toLocaleTimeString('en-US', { hour12: false });
+};
+
+const logDirectoryInfo = (message: string) => {
+  console.log(`${colors.dim(getTimestamp())} ${colors.blue('[directory]')} ${message}`);
+};
diff --git a/packages/core/eventcatalog/src/enterprise/feature.ts b/packages/core/eventcatalog/src/enterprise/feature.ts
new file mode 100644
index 000000000..3fcbe3979
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/feature.ts
@@ -0,0 +1,74 @@
+/**
+ * This file is licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE for the full terms.
+ *
+ * Modifying, disabling, or circumventing the license key functionality
+ * in this file without a valid Commercial Subscription is prohibited.
+ *
+ * To obtain a license: https://www.eventcatalog.dev/pricing
+ * Free 14-day trial: https://eventcatalog.cloud/
+ */
+
+import fs from 'fs';
+import { join } from 'path';
+import config from '../../eventcatalog.config.js';
+
+// Inline isSSR to avoid circular dependency with ../utils/feature (which re-exports from this file)
+const isSSR = () => config?.output === 'server';
+
+// These functions check for valid, legally obtained access to premium features
+export const isEventCatalogStarterEnabled = () => process.env.EVENTCATALOG_STARTER === 'true';
+export const isEventCatalogScaleEnabled = () => process.env.EVENTCATALOG_SCALE === 'true';
+
+export const isPrivateRemoteSchemaEnabled = () => isEventCatalogScaleEnabled() || isEventCatalogStarterEnabled();
+
+export const isEmbedEnabled = () => process.env.ENABLE_EMBED === 'true';
+
+export const showEventCatalogBranding = () => {
+  const override = process.env.EVENTCATALOG_SHOW_BRANDING;
+  // if any value we return true
+  if (override) {
+    return true;
+  }
+  return !isEventCatalogStarterEnabled() && !isEventCatalogScaleEnabled();
+};
+
+export const showCustomBranding = () => {
+  return isEventCatalogStarterEnabled() || isEventCatalogScaleEnabled();
+};
+
+export const isCustomDocsEnabled = () => isEventCatalogStarterEnabled() || isEventCatalogScaleEnabled();
+export const isResourceDocsEnabled = () => isEventCatalogScaleEnabled();
+
+export const isEventCatalogChatEnabled = () => {
+  const isFeatureEnabledFromPlan = isEventCatalogStarterEnabled() || isEventCatalogScaleEnabled();
+  const directory = process.env.PROJECT_DIR || process.cwd();
+  const hasChatConfigurationFile = fs.existsSync(join(directory, 'eventcatalog.chat.js'));
+  const isEnabledInConfig = config?.chat?.enabled ?? true;
+  return isFeatureEnabledFromPlan && hasChatConfigurationFile && isSSR() && isEnabledInConfig;
+};
+
+export const isEventCatalogUpgradeEnabled = () => !isEventCatalogStarterEnabled() && !isEventCatalogScaleEnabled();
+
+// Custom landing pages are always enabled now.
+export const isCustomLandingPageEnabled = () => true;
+
+// User-defined pages and API routes (pages/*.astro, pages/api/*.ts)
+export const isCustomPagesEnabled = () => isEventCatalogScaleEnabled();
+
+export const isAuthEnabled = () => {
+  const isAuthEnabledInCatalog = config?.auth?.enabled ?? false;
+  const directory = process.env.PROJECT_DIR || process.cwd();
+  const hasAuthConfigurationFile = fs.existsSync(join(directory, 'eventcatalog.auth.js'));
+  return (isAuthEnabledInCatalog && hasAuthConfigurationFile && isSSR() && isEventCatalogScaleEnabled()) || false;
+};
+
+export const isCustomStylesEnabled = () => {
+  return isEventCatalogStarterEnabled() || isEventCatalogScaleEnabled();
+};
+
+export const isEventCatalogMCPEnabled = () => isEventCatalogScaleEnabled() && isSSR();
+
+export const isEventCatalogMCPAuthEnabled = () => isEventCatalogMCPEnabled() && (config?.mcp?.auth?.enabled ?? false);
+
+export const isIntegrationsEnabled = () => isEventCatalogScaleEnabled();
diff --git a/packages/core/eventcatalog/src/enterprise/fields/field-extractor.test.ts b/packages/core/eventcatalog/src/enterprise/fields/field-extractor.test.ts
new file mode 100644
index 000000000..2f20d4f4f
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/fields/field-extractor.test.ts
@@ -0,0 +1,302 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import { describe, it, expect } from 'vitest';
+import { extractSchemaFieldsDeep } from './field-extractor';
+
+describe('extractSchemaFieldsDeep', () => {
+  describe('JSON Schema', () => {
+    it('extracts top-level properties with their types', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          orderId: { type: 'string', description: 'The order ID' },
+          amount: { type: 'number' },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields).toEqual([
+        { path: 'orderId', type: 'string', description: 'The order ID', required: false },
+        { path: 'amount', type: 'number', description: '', required: false },
+      ]);
+    });
+
+    it('marks fields as required when listed in the JSON Schema required array', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        required: ['orderId'],
+        properties: {
+          orderId: { type: 'string' },
+          notes: { type: 'string' },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields[0].required).toBe(true);
+      expect(fields[1].required).toBe(false);
+    });
+
+    it('extracts nested object fields with dot-notation paths', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          address: {
+            type: 'object',
+            properties: {
+              street: { type: 'string' },
+              city: { type: 'string' },
+            },
+          },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields.map((f) => f.path)).toEqual(['address', 'address.street', 'address.city']);
+    });
+
+    it('uses bracket notation for array item fields', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          items: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                productId: { type: 'string' },
+                quantity: { type: 'integer' },
+              },
+            },
+          },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields.map((f) => f.path)).toEqual(['items', 'items[].productId', 'items[].quantity']);
+    });
+
+    it('resolves local $ref references within the same schema', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          billing: { $ref: '#/definitions/Address' },
+        },
+        definitions: {
+          Address: {
+            type: 'object',
+            properties: {
+              street: { type: 'string' },
+              zip: { type: 'string' },
+            },
+          },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields.map((f) => f.path)).toEqual(['billing', 'billing.street', 'billing.zip']);
+    });
+
+    it('skips external $ref references and returns only local fields', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          orderId: { type: 'string' },
+          customer: { $ref: './common.json#/definitions/Customer' },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields).toHaveLength(2);
+      expect(fields[0].path).toBe('orderId');
+      expect(fields[1].path).toBe('customer');
+      expect(fields[1].type).toBe('$ref');
+    });
+
+    it('merges allOf schemas and extracts combined properties', () => {
+      const schema = JSON.stringify({
+        allOf: [
+          { type: 'object', properties: { id: { type: 'string' } } },
+          { type: 'object', properties: { name: { type: 'string' } } },
+        ],
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields.map((f) => f.path)).toEqual(['id', 'name']);
+    });
+
+    it('converts array type values to a sorted pipe-separated string (e.g. nullable fields)', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          userId: { type: 'string', description: 'identifier for a user' },
+          cancellationReason: { type: ['string', 'null'], description: 'optional reason' },
+          renewalDate: { type: ['null', 'integer'], description: 'unix timestamp or null' },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields).toEqual([
+        { path: 'userId', type: 'string', description: 'identifier for a user', required: false },
+        { path: 'cancellationReason', type: 'null | string', description: 'optional reason', required: false },
+        { path: 'renewalDate', type: 'integer | null', description: 'unix timestamp or null', required: false },
+      ]);
+    });
+
+    it('recurses into nested properties when object type is nullable', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          metadata: {
+            type: ['object', 'null'],
+            properties: {
+              source: { type: 'string' },
+              version: { type: 'integer' },
+            },
+          },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields.map((f) => f.path)).toEqual(['metadata', 'metadata.source', 'metadata.version']);
+      expect(fields[0].type).toBe('null | object');
+    });
+
+    it('recurses into array items when array type is nullable', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          tags: {
+            type: ['array', 'null'],
+            items: {
+              type: 'object',
+              properties: {
+                key: { type: 'string' },
+                value: { type: 'string' },
+              },
+            },
+          },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields.map((f) => f.path)).toEqual(['tags', 'tags[].key', 'tags[].value']);
+      expect(fields[0].type).toBe('array | null'); // already sorted alphabetically
+    });
+
+    it('returns empty array when schema content is malformed JSON', () => {
+      const fields = extractSchemaFieldsDeep('not valid json{{{', 'json-schema');
+      expect(fields).toEqual([]);
+    });
+
+    it('returns empty array when schema content is empty', () => {
+      const fields = extractSchemaFieldsDeep('', 'json-schema');
+      expect(fields).toEqual([]);
+    });
+  });
+
+  describe('Avro', () => {
+    it('extracts fields from a simple Avro record', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Order',
+        fields: [
+          { name: 'orderId', type: 'string', doc: 'The order identifier' },
+          { name: 'amount', type: 'double' },
+        ],
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'avro');
+      expect(fields).toEqual([
+        { path: 'orderId', type: 'string', description: 'The order identifier', required: true },
+        { path: 'amount', type: 'double', description: '', required: true },
+      ]);
+    });
+
+    it('handles Avro union types containing null as optional fields', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Customer',
+        fields: [
+          { name: 'id', type: 'string' },
+          { name: 'nickname', type: ['null', 'string'] },
+        ],
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'avro');
+      expect(fields[0].required).toBe(true);
+      expect(fields[1].required).toBe(false);
+      expect(fields[1].type).toBe('null | string');
+    });
+
+    it('extracts nested record fields with dot-notation paths', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Order',
+        fields: [
+          {
+            name: 'customer',
+            type: {
+              type: 'record',
+              name: 'Customer',
+              fields: [
+                { name: 'name', type: 'string' },
+                { name: 'email', type: 'string' },
+              ],
+            },
+          },
+        ],
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'avro');
+      expect(fields.map((f) => f.path)).toEqual(['customer', 'customer.name', 'customer.email']);
+    });
+
+    it('uses bracket notation for Avro array items', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Order',
+        fields: [
+          {
+            name: 'items',
+            type: {
+              type: 'array',
+              items: {
+                type: 'record',
+                name: 'Item',
+                fields: [
+                  { name: 'productId', type: 'string' },
+                  { name: 'qty', type: 'int' },
+                ],
+              },
+            },
+          },
+        ],
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'avro');
+      expect(fields.map((f) => f.path)).toEqual(['items', 'items[].productId', 'items[].qty']);
+    });
+  });
+
+  describe('Protobuf', () => {
+    it('extracts fields from a simple proto3 message', () => {
+      const proto = `
+        syntax = "proto3";
+        message Order {
+          string order_id = 1;
+          double amount = 2; // total amount
+        }
+      `;
+      const fields = extractSchemaFieldsDeep(proto, 'proto');
+      expect(fields).toEqual([
+        { path: 'order_id', type: 'string', description: '', required: false },
+        { path: 'amount', type: 'double', description: 'total amount', required: false },
+      ]);
+    });
+
+    it('marks repeated fields with their modifier in the type', () => {
+      const proto = `
+        syntax = "proto3";
+        message Order {
+          repeated string tags = 1;
+        }
+      `;
+      const fields = extractSchemaFieldsDeep(proto, 'proto');
+      expect(fields[0].type).toBe('repeated string');
+    });
+
+    it('returns empty array for empty proto content', () => {
+      const fields = extractSchemaFieldsDeep('', 'proto');
+      expect(fields).toEqual([]);
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/enterprise/fields/field-extractor.ts b/packages/core/eventcatalog/src/enterprise/fields/field-extractor.ts
new file mode 100644
index 000000000..61eb058bf
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/fields/field-extractor.ts
@@ -0,0 +1,191 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+export interface DeepSchemaField {
+  path: string;
+  type: string;
+  description: string;
+  required: boolean;
+}
+
+export function extractSchemaFieldsDeep(content: string, format: string): DeepSchemaField[] {
+  if (!content) return [];
+
+  if (format === 'json-schema') {
+    return extractJsonSchemaFields(content);
+  }
+
+  if (format === 'avro') {
+    return extractAvroFields(content);
+  }
+
+  if (format === 'proto') {
+    return extractProtoFields(content);
+  }
+
+  return [];
+}
+
+function extractProtoFields(content: string): DeepSchemaField[] {
+  if (!content) return [];
+  const fields: DeepSchemaField[] = [];
+  const fieldRegex = /^\s*(repeated\s+|optional\s+|required\s+)?(\w+)\s+(\w+)\s*=\s*\d+\s*;(?:\s*\/\/\s*(.*))?/gm;
+  let match;
+  while ((match = fieldRegex.exec(content)) !== null) {
+    const modifier = (match[1] || '').trim();
+    const type = modifier ? `${modifier} ${match[2]}` : match[2];
+    fields.push({
+      path: match[3],
+      type,
+      description: match[4]?.trim() || '',
+      required: modifier === 'required',
+    });
+  }
+  return fields;
+}
+
+function extractAvroFields(content: string): DeepSchemaField[] {
+  try {
+    const schema = JSON.parse(content);
+    const fields: DeepSchemaField[] = [];
+    walkAvroRecord(schema, '', fields);
+    return fields;
+  } catch {
+    return [];
+  }
+}
+
+function getAvroTypeName(type: any): string {
+  if (typeof type === 'string') return type;
+  if (Array.isArray(type)) {
+    return type.map((t) => (typeof t === 'string' ? t : t.type || 'complex')).join(' | ');
+  }
+  if (typeof type === 'object' && type !== null) {
+    if (type.type === 'array' && type.items) return `array<${getAvroTypeName(type.items)}>`;
+    if (type.type === 'record') return type.name || 'record';
+    return type.type || 'complex';
+  }
+  return 'unknown';
+}
+
+function walkAvroRecord(schema: any, prefix: string, fields: DeepSchemaField[]): void {
+  if (!schema.fields || !Array.isArray(schema.fields)) return;
+
+  for (const field of schema.fields) {
+    const path = prefix ? `${prefix}.${field.name}` : field.name;
+    const isOptional = Array.isArray(field.type) && field.type.includes('null');
+    const typeName = getAvroTypeName(field.type);
+
+    fields.push({
+      path,
+      type: typeName,
+      description: field.doc || '',
+      required: !isOptional,
+    });
+
+    // Recurse into nested records
+    const innerType = Array.isArray(field.type)
+      ? field.type.find((t: any) => typeof t === 'object' && t.type === 'record')
+      : typeof field.type === 'object' && field.type.type === 'record'
+        ? field.type
+        : null;
+
+    if (innerType) {
+      walkAvroRecord(innerType, path, fields);
+    }
+
+    // Recurse into array items that are records
+    const arrayType = Array.isArray(field.type)
+      ? field.type.find((t: any) => typeof t === 'object' && t.type === 'array')
+      : typeof field.type === 'object' && field.type.type === 'array'
+        ? field.type
+        : null;
+
+    if (arrayType && typeof arrayType.items === 'object' && arrayType.items.type === 'record') {
+      walkAvroRecord(arrayType.items, `${path}[]`, fields);
+    }
+  }
+}
+
+function extractJsonSchemaFields(content: string): DeepSchemaField[] {
+  try {
+    const schema = JSON.parse(content);
+    const fields: DeepSchemaField[] = [];
+    walkJsonSchema(schema, '', schema.required || [], schema, fields);
+    return fields;
+  } catch {
+    return [];
+  }
+}
+
+function walkJsonSchema(node: any, prefix: string, requiredList: string[], rootSchema: any, fields: DeepSchemaField[]): void {
+  // Handle allOf by merging (resolve $ref entries first)
+  if (node.allOf && Array.isArray(node.allOf)) {
+    const merged: any = { type: 'object', properties: {}, required: [] };
+    for (let sub of node.allOf) {
+      if (sub.$ref) {
+        const resolved = resolveLocalRef(sub.$ref, rootSchema);
+        if (resolved) sub = resolved;
+        else continue;
+      }
+      Object.assign(merged.properties, sub.properties || {});
+      merged.required.push(...(sub.required || []));
+    }
+    walkJsonSchema(merged, prefix, merged.required, rootSchema, fields);
+    return;
+  }
+
+  if (!node.properties) return;
+
+  for (const [name, prop] of Object.entries(node.properties) as [string, any][]) {
+    const path = prefix ? `${prefix}.${name}` : name;
+    const isRequired = requiredList.includes(name);
+
+    // Resolve $ref
+    if (prop.$ref) {
+      const resolved = resolveLocalRef(prop.$ref, rootSchema);
+      if (resolved) {
+        const rawRefType = resolved.type || 'object';
+        const type = Array.isArray(rawRefType) ? [...rawRefType].sort().join(' | ') : rawRefType;
+        fields.push({ path, type, description: resolved.description || '', required: isRequired });
+        if (resolved.properties) {
+          walkJsonSchema(resolved, path, resolved.required || [], rootSchema, fields);
+        }
+      } else {
+        // External ref — add as-is
+        fields.push({ path, type: '$ref', description: '', required: isRequired });
+      }
+      continue;
+    }
+
+    const rawType = prop.type || (prop.enum ? 'enum' : prop.$ref ? '$ref' : 'object');
+    const typeList = Array.isArray(rawType) ? rawType : [rawType];
+    const type = Array.isArray(rawType) ? [...rawType].sort().join(' | ') : rawType;
+    fields.push({ path, type, description: prop.description || '', required: isRequired });
+
+    // Recurse into nested objects (handles both "type": "object" and "type": ["object", "null"])
+    if (typeList.includes('object') && prop.properties) {
+      walkJsonSchema(prop, path, prop.required || [], rootSchema, fields);
+    }
+
+    // Recurse into array items (handles both "type": "array" and "type": ["array", "null"])
+    if (typeList.includes('array') && prop.items) {
+      if (prop.items.type === 'object' && prop.items.properties) {
+        walkJsonSchema(prop.items, `${path}[]`, prop.items.required || [], rootSchema, fields);
+      }
+    }
+  }
+}
+
+function resolveLocalRef(ref: string, rootSchema: any): any {
+  if (!ref.startsWith('#/')) return null;
+  const parts = ref.replace('#/', '').split('/');
+  let current = rootSchema;
+  for (const part of parts) {
+    current = current?.[part];
+    if (!current) return null;
+  }
+  return current;
+}
diff --git a/packages/core/eventcatalog/src/enterprise/fields/field-indexer.ts b/packages/core/eventcatalog/src/enterprise/fields/field-indexer.ts
new file mode 100644
index 000000000..250d288d5
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/fields/field-indexer.ts
@@ -0,0 +1,136 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { FieldsDatabase } from './fields-db';
+import { extractSchemaFieldsDeep } from './field-extractor';
+
+function detectFormat(fileName: string): string {
+  const ext = path.extname(fileName).toLowerCase();
+  if (ext === '.proto') return 'proto';
+  if (ext === '.avro' || ext === '.avsc') return 'avro';
+  return 'json-schema';
+}
+
+interface Warning {
+  messageId: string;
+  version: string;
+  error: string;
+}
+
+/**
+ * Build the fields SQLite index using the EventCatalog SDK.
+ * This runs BEFORE Astro starts (no Astro dependencies).
+ *
+ * @param catalogDir - Path to the EventCatalog content directory
+ * @param outputDir - Path to write the .eventcatalog/fields.db (defaults to catalogDir)
+ */
+export async function buildFieldsIndex(catalogDir: string, outputDir?: string): Promise<{ dbPath: string; warnings: Warning[] }> {
+  // Dynamic import to avoid bundling the SDK into the Astro build
+  const sdkModule = await import('@eventcatalog/sdk');
+  const sdk = sdkModule.default(catalogDir);
+
+  const dbDir = path.join(outputDir || catalogDir, '.eventcatalog');
+  const dbPath = path.join(dbDir, 'fields.db');
+
+  if (!fs.existsSync(dbDir)) {
+    fs.mkdirSync(dbDir, { recursive: true });
+  }
+
+  const db = await FieldsDatabase.create(dbPath, { recreate: true });
+  const warnings: Warning[] = [];
+
+  try {
+    // Fetch all messages (latest version only) using the SDK
+    const [events, commands, queries] = await Promise.all([
+      sdk.getEvents({ latestOnly: true }),
+      sdk.getCommands({ latestOnly: true }),
+      sdk.getQueries({ latestOnly: true }),
+    ]);
+
+    const collections = [
+      { entries: events || [], type: 'event' as const },
+      { entries: commands || [], type: 'command' as const },
+      { entries: queries || [], type: 'query' as const },
+    ];
+
+    for (const { entries, type } of collections) {
+      for (const entry of entries) {
+        const msgId = entry.id;
+        const msgVersion = entry.version;
+
+        // Get schema content via SDK
+        let schemaData: { schema: string; fileName: string } | undefined;
+        try {
+          schemaData = await sdk.getSchemaForMessage(msgId, msgVersion);
+        } catch {
+          // No schema for this message
+          continue;
+        }
+
+        if (!schemaData) continue;
+
+        const { schema: content, fileName } = schemaData;
+        const format = detectFormat(fileName);
+
+        try {
+          const fields = extractSchemaFieldsDeep(content, format);
+
+          for (const field of fields) {
+            db.insertField({
+              path: field.path,
+              type: field.type,
+              description: field.description,
+              required: field.required,
+              schemaFormat: format,
+              messageId: msgId,
+              messageVersion: msgVersion,
+              messageType: type,
+              messageName: entry.name || msgId,
+              messageSummary: entry.summary || '',
+              messageOwners: entry.owners || [],
+            });
+          }
+
+          // Get producers and consumers via SDK
+          const { producers, consumers } = await sdk.getProducersAndConsumersForMessage(msgId, msgVersion);
+
+          for (const producer of producers) {
+            db.insertProducer(
+              msgId,
+              msgVersion,
+              producer.id,
+              producer.version,
+              producer.name || producer.id,
+              producer.summary || '',
+              producer.owners || []
+            );
+          }
+          for (const consumer of consumers) {
+            db.insertConsumer(
+              msgId,
+              msgVersion,
+              consumer.id,
+              consumer.version,
+              consumer.name || consumer.id,
+              consumer.summary || '',
+              consumer.owners || []
+            );
+          }
+        } catch (err: any) {
+          warnings.push({ messageId: msgId, version: msgVersion, error: err.message });
+        }
+      }
+    }
+
+    db.save();
+    db.close();
+    return { dbPath, warnings };
+  } catch (err) {
+    db.close();
+    throw err;
+  }
+}
diff --git a/packages/core/eventcatalog/src/enterprise/fields/fields-db.test.ts b/packages/core/eventcatalog/src/enterprise/fields/fields-db.test.ts
new file mode 100644
index 000000000..347054a36
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/fields/fields-db.test.ts
@@ -0,0 +1,185 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { FieldsDatabase } from './fields-db';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+
+describe('FieldsDatabase', () => {
+  let db: FieldsDatabase;
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fields-db-'));
+    db = await FieldsDatabase.create(path.join(tmpDir, 'fields.db'), { recreate: true });
+  });
+
+  afterEach(() => {
+    db.close();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('creates the schema tables on initialization', () => {
+    const rows = db.db.exec("SELECT name FROM sqlite_master WHERE type='table'");
+    const tableNames = rows.length > 0 ? rows[0].values.map((r: any) => r[0]) : [];
+    expect(tableNames).toContain('fields');
+    expect(tableNames).toContain('message_producers');
+    expect(tableNames).toContain('message_consumers');
+  });
+
+  it('inserts fields and retrieves them with pagination', () => {
+    db.insertField({
+      path: 'orderId',
+      type: 'string',
+      description: 'The order ID',
+      required: true,
+      schemaFormat: 'json-schema',
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageType: 'event',
+    });
+    db.insertField({
+      path: 'amount',
+      type: 'number',
+      description: '',
+      required: false,
+      schemaFormat: 'json-schema',
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageType: 'event',
+    });
+    const result = db.queryFields({});
+    expect(result.fields).toHaveLength(2);
+    expect(result.total).toBe(2);
+  });
+
+  it('filters fields by text search matching field path', () => {
+    db.insertField({
+      path: 'orderId',
+      type: 'string',
+      description: '',
+      required: true,
+      schemaFormat: 'json-schema',
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageType: 'event',
+    });
+    db.insertField({
+      path: 'amount',
+      type: 'number',
+      description: '',
+      required: false,
+      schemaFormat: 'json-schema',
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageType: 'event',
+    });
+    const result = db.queryFields({ q: 'orderId' });
+    expect(result.fields).toHaveLength(1);
+    expect(result.fields[0].path).toBe('orderId');
+  });
+
+  it('filters fields that appear in multiple messages when shared flag is set', () => {
+    db.insertField({
+      path: 'customerId',
+      type: 'string',
+      description: '',
+      required: true,
+      schemaFormat: 'json-schema',
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageType: 'event',
+    });
+    db.insertField({
+      path: 'customerId',
+      type: 'string',
+      description: '',
+      required: true,
+      schemaFormat: 'json-schema',
+      messageId: 'PaymentProcessed',
+      messageVersion: '1.0.0',
+      messageType: 'event',
+    });
+    db.insertField({
+      path: 'amount',
+      type: 'number',
+      description: '',
+      required: false,
+      schemaFormat: 'json-schema',
+      messageId: 'PaymentProcessed',
+      messageVersion: '1.0.0',
+      messageType: 'event',
+    });
+    const result = db.queryFields({ shared: true });
+    expect(result.fields.every((f) => f.path === 'customerId')).toBe(true);
+  });
+
+  it('returns facet counts reflecting current filters', () => {
+    db.insertField({
+      path: 'orderId',
+      type: 'string',
+      description: '',
+      required: true,
+      schemaFormat: 'json-schema',
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageType: 'event',
+    });
+    db.insertField({
+      path: 'status',
+      type: 'string',
+      description: '',
+      required: true,
+      schemaFormat: 'avro',
+      messageId: 'OrderUpdated',
+      messageVersion: '1.0.0',
+      messageType: 'event',
+    });
+    const result = db.queryFields({});
+    expect(result.facets.formats).toContainEqual({ value: 'json-schema', count: 1 });
+    expect(result.facets.formats).toContainEqual({ value: 'avro', count: 1 });
+  });
+
+  it('paginates results using keyset cursor', () => {
+    for (let i = 0; i < 5; i++) {
+      db.insertField({
+        path: `field${i}`,
+        type: 'string',
+        description: '',
+        required: false,
+        schemaFormat: 'json-schema',
+        messageId: 'TestMsg',
+        messageVersion: '1.0.0',
+        messageType: 'event',
+      });
+    }
+    const page1 = db.queryFields({ pageSize: 2 });
+    expect(page1.fields).toHaveLength(2);
+    expect(page1.cursor).toBeDefined();
+    const page2 = db.queryFields({ pageSize: 2, cursor: page1.cursor });
+    expect(page2.fields).toHaveLength(2);
+    expect(page2.fields[0].path).not.toBe(page1.fields[0].path);
+  });
+
+  it('joins producer and consumer data for each field', () => {
+    db.insertField({
+      path: 'orderId',
+      type: 'string',
+      description: '',
+      required: true,
+      schemaFormat: 'json-schema',
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageType: 'event',
+    });
+    db.insertProducer('OrderCreated', '1.0.0', 'OrderService', '1.0.0');
+    db.insertConsumer('OrderCreated', '1.0.0', 'InventoryService', '2.0.0');
+    const result = db.queryFields({});
+    expect(result.fields[0].producers).toEqual([{ id: 'OrderService', version: '1.0.0' }]);
+    expect(result.fields[0].consumers).toEqual([{ id: 'InventoryService', version: '2.0.0' }]);
+  });
+});
diff --git a/packages/core/eventcatalog/src/enterprise/fields/fields-db.ts b/packages/core/eventcatalog/src/enterprise/fields/fields-db.ts
new file mode 100644
index 000000000..e5792326f
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/fields/fields-db.ts
@@ -0,0 +1,483 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import initSqlJs, { type Database as SqlJsDatabase } from 'sql.js';
+import fs from 'node:fs';
+
+export interface FieldRow {
+  path: string;
+  type: string;
+  description: string;
+  required: boolean;
+  schemaFormat: string;
+  messageId: string;
+  messageVersion: string;
+  messageType: string;
+}
+
+export interface ServiceRef {
+  id: string;
+  version: string;
+  name?: string;
+  summary?: string;
+  owners?: string[];
+}
+
+export interface TypeConflict {
+  type: string;
+  count: number;
+}
+
+export interface FieldResult {
+  id: number;
+  path: string;
+  type: string;
+  description: string;
+  required: boolean;
+  schemaFormat: string;
+  messageId: string;
+  messageVersion: string;
+  messageType: string;
+  messageOwners?: string[];
+  usedInCount?: number;
+  conflicts?: TypeConflict[];
+  producers: ServiceRef[];
+  consumers: ServiceRef[];
+}
+
+export interface FacetEntry {
+  value: string;
+  count: number;
+}
+
+export interface QueryFieldsResult {
+  fields: FieldResult[];
+  total: number;
+  cursor?: string;
+  facets: {
+    formats: FacetEntry[];
+    types: FacetEntry[];
+    messageTypes: FacetEntry[];
+  };
+}
+
+export interface QueryFieldsParams {
+  q?: string;
+  shared?: boolean;
+  conflicting?: boolean;
+  format?: string;
+  type?: string;
+  messageType?: string;
+  message?: string;
+  producer?: string;
+  consumer?: string;
+  required?: boolean;
+  path?: string;
+  pageSize?: number;
+  cursor?: string;
+}
+
+const SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS fields (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    path TEXT NOT NULL,
+    type TEXT NOT NULL,
+    description TEXT NOT NULL DEFAULT '',
+    required INTEGER NOT NULL DEFAULT 0,
+    schema_format TEXT NOT NULL,
+    message_id TEXT NOT NULL,
+    message_version TEXT NOT NULL,
+    message_type TEXT NOT NULL,
+    message_name TEXT NOT NULL DEFAULT '',
+    message_summary TEXT NOT NULL DEFAULT '',
+    message_owners TEXT NOT NULL DEFAULT '[]'
+  );
+
+  CREATE TABLE IF NOT EXISTS message_producers (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    message_id TEXT NOT NULL,
+    message_version TEXT NOT NULL,
+    service_id TEXT NOT NULL,
+    service_version TEXT NOT NULL,
+    service_name TEXT NOT NULL DEFAULT '',
+    service_summary TEXT NOT NULL DEFAULT '',
+    service_owners TEXT NOT NULL DEFAULT '[]'
+  );
+
+  CREATE TABLE IF NOT EXISTS message_consumers (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    message_id TEXT NOT NULL,
+    message_version TEXT NOT NULL,
+    service_id TEXT NOT NULL,
+    service_version TEXT NOT NULL,
+    service_name TEXT NOT NULL DEFAULT '',
+    service_summary TEXT NOT NULL DEFAULT '',
+    service_owners TEXT NOT NULL DEFAULT '[]'
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_fields_path ON fields(path);
+  CREATE INDEX IF NOT EXISTS idx_fields_message ON fields(message_id, message_version);
+  CREATE INDEX IF NOT EXISTS idx_producers_message ON message_producers(message_id, message_version);
+  CREATE INDEX IF NOT EXISTS idx_consumers_message ON message_consumers(message_id, message_version);
+`;
+
+/** Helper: run a SELECT and return rows as plain objects */
+function queryAll(db: SqlJsDatabase, sql: string, params: any[] = []): any[] {
+  const stmt = db.prepare(sql);
+  stmt.bind(params);
+  const rows: any[] = [];
+  while (stmt.step()) {
+    rows.push(stmt.getAsObject());
+  }
+  stmt.free();
+  return rows;
+}
+
+/** Helper: run a SELECT and return the first row as a plain object */
+function queryOne(db: SqlJsDatabase, sql: string, params: any[] = []): any {
+  const stmt = db.prepare(sql);
+  stmt.bind(params);
+  const result = stmt.step() ? stmt.getAsObject() : null;
+  stmt.free();
+  return result;
+}
+
+export class FieldsDatabase {
+  public db: SqlJsDatabase;
+  private dbPath: string;
+
+  private constructor(db: SqlJsDatabase, dbPath: string) {
+    this.db = db;
+    this.dbPath = dbPath;
+  }
+
+  static async create(dbPath: string, options?: { recreate?: boolean }): Promise<FieldsDatabase> {
+    if (options?.recreate && fs.existsSync(dbPath)) {
+      fs.unlinkSync(dbPath);
+    }
+
+    const SQL = await initSqlJs();
+    let db: SqlJsDatabase;
+
+    if (!options?.recreate && fs.existsSync(dbPath)) {
+      const buffer = fs.readFileSync(dbPath);
+      db = new SQL.Database(buffer);
+    } else {
+      db = new SQL.Database();
+    }
+
+    db.run(SCHEMA_SQL);
+
+    return new FieldsDatabase(db, dbPath);
+  }
+
+  insertField(field: FieldRow & { messageName?: string; messageSummary?: string; messageOwners?: string[] }): void {
+    this.db.run(
+      `INSERT INTO fields (path, type, description, required, schema_format, message_id, message_version, message_type, message_name, message_summary, message_owners)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        field.path,
+        field.type,
+        field.description,
+        field.required ? 1 : 0,
+        field.schemaFormat,
+        field.messageId,
+        field.messageVersion,
+        field.messageType,
+        field.messageName || '',
+        field.messageSummary || '',
+        JSON.stringify(field.messageOwners || []),
+      ]
+    );
+  }
+
+  insertProducer(
+    messageId: string,
+    messageVersion: string,
+    serviceId: string,
+    serviceVersion: string,
+    serviceName?: string,
+    serviceSummary?: string,
+    serviceOwners?: string[]
+  ): void {
+    this.db.run(
+      `INSERT INTO message_producers (message_id, message_version, service_id, service_version, service_name, service_summary, service_owners)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      [
+        messageId,
+        messageVersion,
+        serviceId,
+        serviceVersion,
+        serviceName || '',
+        serviceSummary || '',
+        JSON.stringify(serviceOwners || []),
+      ]
+    );
+  }
+
+  insertConsumer(
+    messageId: string,
+    messageVersion: string,
+    serviceId: string,
+    serviceVersion: string,
+    serviceName?: string,
+    serviceSummary?: string,
+    serviceOwners?: string[]
+  ): void {
+    this.db.run(
+      `INSERT INTO message_consumers (message_id, message_version, service_id, service_version, service_name, service_summary, service_owners)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      [
+        messageId,
+        messageVersion,
+        serviceId,
+        serviceVersion,
+        serviceName || '',
+        serviceSummary || '',
+        JSON.stringify(serviceOwners || []),
+      ]
+    );
+  }
+
+  /** Save the in-memory database to disk */
+  save(): void {
+    const data = this.db.export();
+    const buffer = Buffer.from(data);
+    fs.writeFileSync(this.dbPath, buffer);
+  }
+
+  queryFields(params: QueryFieldsParams): QueryFieldsResult {
+    const {
+      q,
+      shared,
+      conflicting,
+      format,
+      type,
+      messageType,
+      message,
+      producer,
+      consumer,
+      required,
+      path: fieldPath,
+      pageSize = 50,
+      cursor,
+    } = params;
+
+    const conditions: string[] = [];
+    const bindings: any[] = [];
+
+    // Exact field path filter
+    if (fieldPath) {
+      conditions.push(`f.path = ?`);
+      bindings.push(fieldPath);
+    }
+
+    // Text search using LIKE (replaces FTS5)
+    if (q) {
+      conditions.push(`(f.path LIKE ? ESCAPE '\\' OR f.description LIKE ? ESCAPE '\\' OR f.type LIKE ? ESCAPE '\\')`);
+      const escaped = q.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
+      const term = `%${escaped}%`;
+      bindings.push(term, term, term);
+    }
+
+    // Facet filters (support comma-separated multi-select)
+    if (format) {
+      const formats = format
+        .split(',')
+        .map((f) => f.trim())
+        .filter(Boolean);
+      conditions.push(`f.schema_format IN (${formats.map(() => '?').join(', ')})`);
+      bindings.push(...formats);
+    }
+    if (type) {
+      conditions.push(`f.type = ?`);
+      bindings.push(type);
+    }
+    if (messageType) {
+      const types = messageType
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean);
+      conditions.push(`f.message_type IN (${types.map(() => '?').join(', ')})`);
+      bindings.push(...types);
+    }
+    if (message) {
+      conditions.push(`f.message_id = ?`);
+      bindings.push(message);
+    }
+    if (required) {
+      conditions.push(`f.required = 1`);
+    }
+    if (producer) {
+      conditions.push(
+        `EXISTS (SELECT 1 FROM message_producers p WHERE p.message_id = f.message_id AND p.message_version = f.message_version AND p.service_id = ?)`
+      );
+      bindings.push(producer);
+    }
+    if (consumer) {
+      conditions.push(
+        `EXISTS (SELECT 1 FROM message_consumers c WHERE c.message_id = f.message_id AND c.message_version = f.message_version AND c.service_id = ?)`
+      );
+      bindings.push(consumer);
+    }
+
+    // Shared fields filter: only fields whose path appears in more than one distinct message
+    if (shared) {
+      const sharedSubquery = `SELECT path FROM fields GROUP BY path HAVING COUNT(DISTINCT message_id || '/' || message_version) > 1`;
+      conditions.push(`f.path IN (${sharedSubquery})`);
+    }
+
+    // Conflicting fields filter: only fields whose path has multiple distinct types
+    if (conflicting) {
+      const conflictSubquery = `SELECT path FROM fields GROUP BY path HAVING COUNT(DISTINCT type) > 1`;
+      conditions.push(`f.path IN (${conflictSubquery})`);
+    }
+
+    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+    // Cursor-based pagination
+    const cursorConditions: string[] = [];
+    const cursorBindings: any[] = [];
+    if (cursor) {
+      const lastId = decodeCursor(cursor);
+      cursorConditions.push(`f.id > ?`);
+      cursorBindings.push(lastId);
+    }
+
+    const paginationWhere =
+      cursorConditions.length > 0
+        ? whereClause
+          ? `${whereClause} AND ${cursorConditions.join(' AND ')}`
+          : `WHERE ${cursorConditions.join(' AND ')}`
+        : whereClause;
+
+    // Total count (without pagination)
+    const countSql = `SELECT COUNT(*) as cnt FROM fields f ${whereClause}`;
+    const total = (queryOne(this.db, countSql, bindings) as any).cnt;
+
+    // Main query with pagination
+    const mainSql = `SELECT f.* FROM fields f ${paginationWhere} ORDER BY f.id ASC LIMIT ?`;
+    const allBindings = [...bindings, ...cursorBindings, pageSize];
+    const rows = queryAll(this.db, mainSql, allBindings);
+
+    const parseOwners = (raw: string) => {
+      try {
+        return JSON.parse(raw || '[]');
+      } catch {
+        return [];
+      }
+    };
+
+    // Gather producers and consumers for the returned fields
+    const fields: FieldResult[] = rows.map((row) => {
+      const producers = queryAll(
+        this.db,
+        `SELECT service_id, service_version, service_name, service_summary, service_owners FROM message_producers WHERE message_id = ? AND message_version = ?`,
+        [row.message_id, row.message_version]
+      );
+
+      const consumers = queryAll(
+        this.db,
+        `SELECT service_id, service_version, service_name, service_summary, service_owners FROM message_consumers WHERE message_id = ? AND message_version = ?`,
+        [row.message_id, row.message_version]
+      );
+
+      const usedInCount = (
+        queryOne(this.db, `SELECT COUNT(DISTINCT message_id || '/' || message_version) as cnt FROM fields WHERE path = ?`, [
+          row.path,
+        ]) as any
+      ).cnt;
+
+      const typeRows = queryAll(
+        this.db,
+        `SELECT type, COUNT(DISTINCT message_id || '/' || message_version) as count FROM fields WHERE path = ? GROUP BY type`,
+        [row.path]
+      );
+      const conflicts =
+        typeRows.length > 1 ? typeRows.map((r) => ({ type: r.type as string, count: r.count as number })) : undefined;
+
+      return {
+        id: row.id,
+        path: row.path,
+        type: row.type,
+        description: row.description,
+        required: row.required === 1,
+        schemaFormat: row.schema_format,
+        messageId: row.message_id,
+        messageVersion: row.message_version,
+        messageType: row.message_type,
+        messageName: row.message_name || row.message_id,
+        messageSummary: row.message_summary || '',
+        messageOwners: parseOwners(row.message_owners),
+        usedInCount,
+        conflicts,
+        producers: producers.map((p) => ({
+          id: p.service_id,
+          version: p.service_version,
+          name: p.service_name || p.service_id,
+          summary: p.service_summary || '',
+          owners: parseOwners(p.service_owners),
+        })),
+        consumers: consumers.map((c) => ({
+          id: c.service_id,
+          version: c.service_version,
+          name: c.service_name || c.service_id,
+          summary: c.service_summary || '',
+          owners: parseOwners(c.service_owners),
+        })),
+      };
+    });
+
+    // Facets (computed from filtered set, not paginated)
+    const formatsFacetSql = `SELECT f.schema_format as value, COUNT(*) as count FROM fields f ${whereClause} GROUP BY f.schema_format`;
+    const formats = queryAll(this.db, formatsFacetSql, bindings) as FacetEntry[];
+
+    const typesFacetSql = `SELECT f.type as value, COUNT(*) as count FROM fields f ${whereClause} GROUP BY f.type`;
+    const types = queryAll(this.db, typesFacetSql, bindings) as FacetEntry[];
+
+    const messageTypesFacetSql = `SELECT f.message_type as value, COUNT(*) as count FROM fields f ${whereClause} GROUP BY f.message_type`;
+    const messageTypes = queryAll(this.db, messageTypesFacetSql, bindings) as FacetEntry[];
+
+    // Build cursor for next page
+    const lastRow = rows[rows.length - 1];
+    const nextCursor = lastRow && rows.length === pageSize ? encodeCursor(lastRow.id) : undefined;
+
+    return {
+      fields,
+      total,
+      cursor: nextCursor,
+      facets: { formats, types, messageTypes },
+    };
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+function encodeCursor(id: number): string {
+  return Buffer.from(String(id)).toString('base64url');
+}
+
+function decodeCursor(cursor: string): number {
+  return parseInt(Buffer.from(cursor, 'base64url').toString(), 10);
+}
+
+// Singleton management
+let instance: FieldsDatabase | null = null;
+
+export async function getFieldsDatabase(dbPath: string): Promise<FieldsDatabase> {
+  if (!instance) {
+    instance = await FieldsDatabase.create(dbPath);
+  }
+  return instance;
+}
+
+export function closeFieldsDatabase(): void {
+  if (instance) {
+    instance.close();
+    instance = null;
+  }
+}
diff --git a/packages/core/eventcatalog/src/enterprise/fields/pages/api/fields.ts b/packages/core/eventcatalog/src/enterprise/fields/pages/api/fields.ts
new file mode 100644
index 000000000..62a6df21b
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/fields/pages/api/fields.ts
@@ -0,0 +1,48 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { APIRoute } from 'astro';
+import { Hono } from 'hono';
+import { getFieldsDatabase } from '@enterprise/fields/fields-db';
+import path from 'node:path';
+
+const catalogDirectory = process.env.CATALOG_DIR || process.cwd();
+const dbPath = path.join(catalogDirectory, '.eventcatalog', 'fields.db');
+
+const app = new Hono().basePath('/api/schemas/fields');
+
+app.get('/', async (c) => {
+  try {
+    const url = new URL(c.req.raw.url);
+    const sp = url.searchParams;
+
+    const db = await getFieldsDatabase(dbPath);
+    const params = {
+      q: sp.get('q') || undefined,
+      format: sp.get('format') || undefined,
+      messageType: sp.get('messageType') || undefined,
+      message: sp.get('message') || undefined,
+      producer: sp.get('producer') || undefined,
+      consumer: sp.get('consumer') || undefined,
+      required: sp.get('required') === 'true',
+      shared: sp.get('shared') === 'true',
+      conflicting: sp.get('conflicting') === 'true',
+      cursor: sp.get('cursor') || undefined,
+      pageSize: sp.get('pageSize') ? parseInt(sp.get('pageSize')!, 10) : undefined,
+      path: sp.get('path') || undefined,
+    };
+
+    const result = db.queryFields(params);
+    return c.json(result);
+  } catch (err: any) {
+    return c.json({ error: `Failed to query fields: ${err.message}` }, 500);
+  }
+});
+
+export const ALL: APIRoute = async ({ request }) => {
+  return app.fetch(request);
+};
+
+export const prerender = false;
diff --git a/packages/core/eventcatalog/src/enterprise/fields/pages/fields.astro b/packages/core/eventcatalog/src/enterprise/fields/pages/fields.astro
new file mode 100644
index 000000000..f7e30dbde
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/fields/pages/fields.astro
@@ -0,0 +1,21 @@
+---
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import FieldsExplorer from '@components/FieldsExplorer/FieldsExplorer';
+import { isEventCatalogScaleEnabled } from '@utils/feature';
+
+export const prerender = false;
+---
+
+<VerticalSideBarLayout title="Fields Explorer - EventCatalog" showNestedSideBar={false}>
+  <style is:global>
+    #eventcatalog-header {
+      left: calc(var(--ec-vertical-nav-width, 14rem) + var(--ec-fields-sidebar-width, 320px)) !important;
+    }
+  </style>
+  <main
+    class="min-h-0 overflow-hidden bg-[rgb(var(--ec-page-bg))]"
+    style="--ec-fields-sidebar-width: 320px; margin-left: calc(var(--ec-app-content-padding-left, 5rem) * -1); margin-right: calc(var(--ec-app-content-padding-right, 5rem) * -1); height: calc(100dvh - 60px);"
+  >
+    <FieldsExplorer client:load isScaleEnabled={isEventCatalogScaleEnabled()} />
+  </main>
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/enterprise/integrations/eventcatalog-features.ts b/packages/core/eventcatalog/src/enterprise/integrations/eventcatalog-features.ts
new file mode 100644
index 000000000..be1858d3a
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/integrations/eventcatalog-features.ts
@@ -0,0 +1,253 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { AstroIntegration } from 'astro';
+import fs from 'node:fs';
+import path from 'path';
+import config from '../../../eventcatalog.config.js';
+import {
+  isEventCatalogChatEnabled,
+  isAuthEnabled,
+  isEventCatalogScaleEnabled,
+  isEventCatalogMCPEnabled,
+  isEventCatalogMCPAuthEnabled,
+  isFullCatalogAPIEnabled,
+  isDevMode,
+  isIntegrationsEnabled,
+  isCustomDocsEnabled,
+  isCustomPagesEnabled,
+  isSSR,
+} from '../../utils/feature';
+import {
+  CUSTOM_PAGES_MANIFEST_FILENAME,
+  getCustomPageRoutes,
+  isApiRoute,
+  listCustomPageFiles,
+  resolveCustomPagesPrefix,
+} from '../custom-pages/routes';
+
+const catalogDirectory = process.env.CATALOG_DIR || process.cwd();
+const customPagesDirectory = path.join(catalogDirectory, 'src/custom-pages');
+
+// Routes are injected at astro:config:setup, so adding or removing a custom page
+// file needs a full Astro restart before its route exists. This manifest is
+// registered via addWatchFile — rewriting it with a changed file list triggers
+// that restart (a Vite-level server.restart() does NOT re-run route injection).
+const customPagesManifest = path.join(customPagesDirectory, CUSTOM_PAGES_MANIFEST_FILENAME);
+
+const writeCustomPagesManifest = () => {
+  const content = JSON.stringify(listCustomPageFiles(customPagesDirectory));
+
+  try {
+    if (fs.existsSync(customPagesManifest) && fs.readFileSync(customPagesManifest, 'utf-8') === content) {
+      return;
+    }
+
+    fs.mkdirSync(customPagesDirectory, { recursive: true });
+    fs.writeFileSync(customPagesManifest, content);
+  } catch (error: any) {
+    console.warn(`[EventCatalog] Could not update the custom pages manifest: ${error.message}`);
+  }
+};
+
+const configureCustomPages = (params: {
+  command: 'dev' | 'build' | 'preview' | 'sync';
+  injectRoute: (route: { pattern: string; entrypoint: string }) => void;
+}) => {
+  const prefix = resolveCustomPagesPrefix(config.pages?.prefix);
+  const routes = getCustomPageRoutes(customPagesDirectory, prefix);
+
+  const apiRoutes = routes.filter(isApiRoute);
+  if (apiRoutes.length > 0 && !isSSR()) {
+    const message = `Custom API routes (${apiRoutes.map((route) => `pages/${route.file}`).join(', ')}) require EventCatalog to run in server mode. Set output: 'server' in your eventcatalog.config.js or remove the pages/api directory.`;
+
+    // The dev server serves endpoints dynamically regardless of output mode,
+    // so only fail the build — but warn early during development.
+    if (params.command === 'build') {
+      throw new Error(`[EventCatalog] ${message}`);
+    }
+    console.warn(`[EventCatalog] ${message}`);
+  }
+
+  for (const route of routes) {
+    params.injectRoute({
+      pattern: route.pattern,
+      entrypoint: path.join(customPagesDirectory, route.file),
+    });
+  }
+};
+
+const configureAuthentication = (params: {
+  injectRoute: (route: { pattern: string; entrypoint: string }) => void;
+  addMiddleware: (middleware: { entrypoint: string; order: 'pre' }) => void;
+}) => {
+  params.injectRoute({
+    pattern: '/api/[...auth]',
+    entrypoint: path.join(catalogDirectory, 'src/enterprise/auth/[...auth].ts'),
+  });
+  params.injectRoute({
+    pattern: '/auth/login',
+    entrypoint: path.join(catalogDirectory, 'src/enterprise/auth/login.astro'),
+  });
+  params.injectRoute({
+    pattern: '/auth/error',
+    entrypoint: path.join(catalogDirectory, 'src/enterprise/auth/error.astro'),
+  });
+
+  params.injectRoute({
+    pattern: '/unauthorized',
+    entrypoint: path.join(catalogDirectory, 'src/enterprise/auth/unauthorized.astro'),
+  });
+
+  // Add the authentication middleware
+  params.addMiddleware({
+    entrypoint: path.join(catalogDirectory, 'src/enterprise/auth/middleware/middleware.ts'),
+    order: 'pre',
+  });
+};
+
+export default function eventCatalogIntegration(): AstroIntegration {
+  return {
+    name: 'eventcatalog',
+    hooks: {
+      'astro:config:setup': (params) => {
+        // Handle routes for AI features
+        if (isEventCatalogChatEnabled()) {
+          params.injectRoute({
+            pattern: '/api/chat',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/ai/chat-api.ts'),
+          });
+        }
+
+        // Handle routes for MCP Server (requires SSR + Scale)
+        if (isEventCatalogMCPEnabled()) {
+          params.injectRoute({
+            pattern: '/docs/mcp/[...path]',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/mcp/mcp-server.ts'),
+          });
+        }
+
+        if (isEventCatalogMCPAuthEnabled()) {
+          params.injectRoute({
+            pattern: '/.well-known/oauth-protected-resource',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/mcp/oauth-protected-resource.ts'),
+          });
+          params.injectRoute({
+            pattern: '/.well-known/oauth-protected-resource/[...path]',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/mcp/oauth-protected-resource.ts'),
+          });
+        }
+
+        // Handle routes for authentication
+        if (isAuthEnabled()) {
+          configureAuthentication(params);
+        }
+
+        // Custom documentation routes (Starter/Scale plan)
+        if (isCustomDocsEnabled()) {
+          params.injectRoute({
+            pattern: '/docs/custom',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/custom-documentation/pages/docs/custom/root-index.astro'),
+          });
+          params.injectRoute({
+            pattern: '/docs/custom/[...path]',
+            entrypoint: path.join(
+              catalogDirectory,
+              'src/enterprise/custom-documentation/pages/docs/custom/[...path]/index.astro'
+            ),
+          });
+          params.injectRoute({
+            pattern: '/docs/custom/[...path].mdx',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/custom-documentation/pages/docs/custom/[...path].mdx.ts'),
+          });
+        } else {
+          // Show feature page for non-paying users
+          params.injectRoute({
+            pattern: '/docs/custom',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/custom-documentation/pages/docs/custom/feature.astro'),
+          });
+        }
+
+        // Schema API routes (Scale plan)
+        if (isEventCatalogScaleEnabled()) {
+          params.injectRoute({
+            pattern: '/api/schemas/[collection]/[id]/[version]',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/api/schemas/[collection]/[id]/[version]/index.ts'),
+          });
+          params.injectRoute({
+            pattern: '/api/schemas/services/[id]/[version]/[specification]',
+            entrypoint: path.join(
+              catalogDirectory,
+              'src/enterprise/api/schemas/services/[id]/[version]/[specification]/index.ts'
+            ),
+          });
+        }
+
+        // Full catalog API route (opt-in)
+        if (isFullCatalogAPIEnabled()) {
+          params.injectRoute({
+            pattern: '/api/catalog',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/api/catalog.ts'),
+          });
+        }
+
+        // Fields Explorer (requires SSR — pages live outside src/pages to avoid static-mode auto-discovery)
+        if (isSSR()) {
+          params.injectRoute({
+            pattern: '/schemas/fields',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/fields/pages/fields.astro'),
+          });
+          params.injectRoute({
+            pattern: '/api/schemas/fields',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/fields/pages/api/fields.ts'),
+          });
+        }
+
+        // User-defined pages and API routes (Scale plan)
+        if (isCustomPagesEnabled()) {
+          configureCustomPages(params);
+        } else if (listCustomPageFiles(customPagesDirectory).length > 0) {
+          console.warn('[EventCatalog] Custom pages require the Scale plan. The routes for your pages will not be served.');
+        }
+
+        // Keep routes in sync during dev — a manifest change restarts the dev
+        // server so injectRoute runs again with the new file list
+        writeCustomPagesManifest();
+        params.addWatchFile(customPagesManifest);
+
+        // Warn if integrations are configured without Scale plan
+        if (config.integrations && !isIntegrationsEnabled()) {
+          console.warn('[EventCatalog] Integrations require the Scale plan. Analytics integrations will not be loaded.');
+        }
+
+        // Dev-only routes for visualizer layout persistence
+        if (isDevMode()) {
+          params.injectRoute({
+            pattern: '/api/dev/visualizer-layout/save',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/visualizer-layout/save.ts'),
+          });
+          params.injectRoute({
+            pattern: '/api/dev/visualizer-layout/reset',
+            entrypoint: path.join(catalogDirectory, 'src/enterprise/visualizer-layout/reset.ts'),
+          });
+        }
+      },
+      'astro:server:setup': ({ server }) => {
+        // When custom page files appear or disappear, refresh the manifest.
+        // A content change restarts the dev server (via addWatchFile above),
+        // which re-runs route injection. Unchanged content writes nothing,
+        // so events from the watcher's initial scan are no-ops.
+        const onCustomPageChange = (file: string) => {
+          if (!path.resolve(file).startsWith(customPagesDirectory + path.sep)) return;
+          if (!/\.(astro|ts|js|mjs)$/i.test(file)) return;
+          writeCustomPagesManifest();
+        };
+
+        server.watcher.on('add', onCustomPageChange);
+        server.watcher.on('unlink', onCustomPageChange);
+      },
+    },
+  };
+}
diff --git a/packages/core/eventcatalog/src/enterprise/mcp/__tests__/mcp-auth.spec.ts b/packages/core/eventcatalog/src/enterprise/mcp/__tests__/mcp-auth.spec.ts
new file mode 100644
index 000000000..7a0284411
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/mcp/__tests__/mcp-auth.spec.ts
@@ -0,0 +1,117 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import { describe, expect, it } from 'vitest';
+import jwt from 'jsonwebtoken';
+import {
+  createWwwAuthenticateHeader,
+  getMcpProtectedResourceMetadata,
+  type McpAuthConfig,
+  validateMcpRequest,
+} from '../mcp-auth';
+
+const authConfig: McpAuthConfig = {
+  enabled: true,
+  resource: 'https://catalog.example.com/docs/mcp',
+  authorizationServers: ['https://auth.example.com'],
+  issuer: 'https://auth.example.com',
+  audience: 'https://catalog.example.com/docs/mcp',
+  requiredScopes: ['catalog:read'],
+  sharedSecret: 'test-secret',
+};
+
+const createRequest = (token?: string) =>
+  new Request('https://catalog.example.com/docs/mcp', {
+    method: 'POST',
+    headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+  });
+
+const createToken = (overrides: Partial<McpAuthConfig> = {}, payload: Record<string, unknown> = {}) =>
+  jwt.sign({ scope: 'catalog:read', ...payload }, authConfig.sharedSecret!, {
+    issuer: overrides.issuer ?? authConfig.issuer,
+    audience: overrides.audience ?? authConfig.audience,
+    expiresIn: '1h',
+  });
+
+describe('MCP OAuth protected resource metadata', () => {
+  it('returns undefined when MCP auth is disabled', () => {
+    const request = createRequest();
+    expect(getMcpProtectedResourceMetadata(request, { enabled: false })).toBeUndefined();
+  });
+
+  it('returns protected resource metadata for MCP clients', () => {
+    const request = createRequest();
+
+    expect(getMcpProtectedResourceMetadata(request, authConfig)).toEqual({
+      resource: 'https://catalog.example.com/docs/mcp',
+      authorization_servers: ['https://auth.example.com'],
+      scopes_supported: ['catalog:read'],
+    });
+  });
+});
+
+describe('MCP Bearer token validation', () => {
+  it('allows requests when MCP auth is disabled', async () => {
+    const result = await validateMcpRequest(createRequest(), { enabled: false });
+    expect(result.ok).toBe(true);
+  });
+
+  it('returns a 401 challenge when the Bearer token is missing', async () => {
+    const result = await validateMcpRequest(createRequest(), authConfig);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+
+    expect(result.status).toBe(401);
+    expect(createWwwAuthenticateHeader(result)).toContain(
+      'resource_metadata="https://catalog.example.com/.well-known/oauth-protected-resource"'
+    );
+    expect(createWwwAuthenticateHeader(result)).toContain('scope="catalog:read"');
+  });
+
+  it('accepts a valid JWT access token', async () => {
+    const token = createToken();
+    const result = await validateMcpRequest(createRequest(token), authConfig);
+
+    expect(result.ok).toBe(true);
+  });
+
+  it('accepts the Bearer scheme regardless of case', async () => {
+    const token = createToken();
+    const lowercase = new Request('https://catalog.example.com/docs/mcp', {
+      method: 'POST',
+      headers: { Authorization: `bearer ${token}` },
+    });
+    const mixedCase = new Request('https://catalog.example.com/docs/mcp', {
+      method: 'POST',
+      headers: { Authorization: `BeArEr ${token}` },
+    });
+
+    expect((await validateMcpRequest(lowercase, authConfig)).ok).toBe(true);
+    expect((await validateMcpRequest(mixedCase, authConfig)).ok).toBe(true);
+  });
+
+  it('rejects a token with the wrong audience', async () => {
+    const token = createToken({ audience: 'https://api.github.com' });
+    const result = await validateMcpRequest(createRequest(token), authConfig);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+
+    expect(result.status).toBe(401);
+    expect(result.error).toBe('invalid_token');
+  });
+
+  it('returns 403 when the token is valid but missing required scopes', async () => {
+    const token = createToken({}, { scope: 'profile:read' });
+    const result = await validateMcpRequest(createRequest(token), authConfig);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+
+    expect(result.status).toBe(403);
+    expect(result.error).toBe('insufficient_scope');
+  });
+});
diff --git a/packages/core/eventcatalog/src/enterprise/mcp/__tests__/mcp-server.spec.ts b/packages/core/eventcatalog/src/enterprise/mcp/__tests__/mcp-server.spec.ts
new file mode 100644
index 000000000..10201b238
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/mcp/__tests__/mcp-server.spec.ts
@@ -0,0 +1,377 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock astro:content
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: () => Promise.resolve([]),
+    getEntry: () => Promise.resolve(undefined),
+  };
+});
+
+// Mock hono - using regular functions instead of vi.fn() to avoid being reset by resetAllMocks
+vi.mock('hono', () => {
+  const createMockApp = () => {
+    const mockFetch = async (request: Request) => {
+      if (request.method === 'GET') {
+        return new Response(
+          JSON.stringify({
+            status: 'healthy',
+            tools: [],
+            resources: [
+              'eventcatalog://all',
+              'eventcatalog://events',
+              'eventcatalog://commands',
+              'eventcatalog://queries',
+              'eventcatalog://agents',
+              'eventcatalog://services',
+              'eventcatalog://domains',
+              'eventcatalog://entities',
+              'eventcatalog://flows',
+              'eventcatalog://teams',
+              'eventcatalog://users',
+            ],
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } }
+        );
+      }
+      return new Response(JSON.stringify({ jsonrpc: '2.0', result: {} }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    };
+    const mockApp: any = {
+      fetch: mockFetch,
+    };
+    // All chaining methods return the same mockApp - using regular functions to avoid reset
+    mockApp.basePath = () => mockApp;
+    mockApp.get = () => mockApp;
+    mockApp.post = () => mockApp;
+    mockApp.all = () => mockApp;
+    return mockApp;
+  };
+  return {
+    Hono: function () {
+      return createMockApp();
+    },
+  };
+});
+
+// Mock @modelcontextprotocol/sdk
+vi.mock('@modelcontextprotocol/sdk/server/mcp.js', () => ({
+  McpServer: vi.fn().mockImplementation(() => ({
+    tool: vi.fn(),
+    resource: vi.fn(),
+    connect: vi.fn(),
+    registerTool: vi.fn(),
+    registerResource: vi.fn(),
+  })),
+}));
+
+vi.mock('@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js', () => ({
+  WebStandardStreamableHTTPServerTransport: vi.fn().mockImplementation(() => ({})),
+}));
+
+// Mock the feature utilities
+vi.mock('@utils/feature', () => ({
+  isSSR: vi.fn(() => true),
+  isEventCatalogScaleEnabled: vi.fn(() => true),
+  isEventCatalogMCPEnabled: vi.fn(() => true),
+  isEventCatalogMCPAuthEnabled: vi.fn(() => false),
+}));
+
+// Mock getSchemasFromResource
+vi.mock('@utils/collections/schemas', () => ({
+  getSchemasFromResource: vi.fn(() => Promise.resolve([])),
+}));
+
+// Mock getItemsFromCollectionByIdAndSemverOrLatest
+vi.mock('@utils/collections/util', () => ({
+  getItemsFromCollectionByIdAndSemverOrLatest: vi.fn(() => []),
+}));
+
+// Mock fs
+vi.mock('node:fs', () => ({
+  default: {
+    readFileSync: vi.fn(() => '{}'),
+  },
+}));
+
+import { isSSR, isEventCatalogScaleEnabled } from '@utils/feature';
+
+// ============================================
+// createToolHandler Tests (Unit Tests)
+// ============================================
+
+describe('createToolHandler', () => {
+  // We test the behavior of createToolHandler indirectly through the tool implementations
+  // The createToolHandler function is internal to the MCP route
+
+  it('should return isError: true when result has error property', async () => {
+    // This tests the pattern used by createToolHandler
+    const mockResult = { error: 'Something went wrong' };
+    const hasError = 'error' in mockResult;
+    expect(hasError).toBe(true);
+  });
+
+  it('should format successful results as JSON', async () => {
+    const mockResult = { data: 'success' };
+    const formatted = JSON.stringify(mockResult, null, 2);
+    expect(formatted).toContain('"data"');
+    expect(formatted).toContain('"success"');
+  });
+});
+
+// ============================================
+// Health Check Endpoint Tests
+// ============================================
+
+describe('MCP Health Check Endpoint (GET /docs/mcp/)', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(isSSR).mockReturnValue(true);
+    vi.mocked(isEventCatalogScaleEnabled).mockReturnValue(true);
+  });
+
+  it('should handle GET requests', async () => {
+    const { ALL } = await import('../mcp-server');
+
+    // Use the exact URL path that matches the Hono basePath
+    const request = new Request('http://localhost:4321/docs/mcp', {
+      method: 'GET',
+    });
+
+    const response = await ALL({ request } as any);
+
+    // Should return success
+    expect(response.status).toBe(200);
+  });
+
+  it('should verify toolDescriptions contains all expected tools', async () => {
+    const { toolDescriptions } = await import('@enterprise/tools/catalog-tools');
+
+    // 22 built-in tools from toolDescriptions
+    const expectedTools = [
+      'getResources',
+      'getResource',
+      'getMessagesProducedOrConsumedByResource',
+      'getSchemaForResource',
+      'findResourcesByOwner',
+      'getProducersOfMessage',
+      'getConsumersOfMessage',
+      'getC4Diagram',
+      'analyzeChangeImpact',
+      'explainBusinessFlow',
+      'getTeams',
+      'getTeam',
+      'getUsers',
+      'getUser',
+      'findMessageBySchemaId',
+      'explainUbiquitousLanguageTerms',
+      'getDataProductInputs',
+      'getDataProductOutputs',
+      'getArchitectureDiagramAsMermaid',
+      'getCustomDocs',
+      'searchCustomDocs',
+      'getCustomDoc',
+    ];
+
+    for (const tool of expectedTools) {
+      expect(toolDescriptions[tool as keyof typeof toolDescriptions]).toBeDefined();
+    }
+    expect(Object.keys(toolDescriptions).length).toBe(22);
+  });
+});
+
+// ============================================
+// MCP Protocol Endpoint Tests (POST /)
+// ============================================
+
+describe('MCP Protocol Endpoint (POST /docs/mcp/)', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(isSSR).mockReturnValue(true);
+    vi.mocked(isEventCatalogScaleEnabled).mockReturnValue(true);
+  });
+
+  it('should accept POST requests', async () => {
+    const { ALL } = await import('../mcp-server');
+
+    const request = new Request('http://localhost:4321/docs/mcp/', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        method: 'initialize',
+        id: 1,
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: 'test', version: '1.0.0' },
+        },
+      }),
+    });
+
+    const response = await ALL({ request } as any);
+
+    // Should not return 501 error
+    expect(response.status).not.toBe(501);
+  });
+});
+
+// ============================================
+// Tool Registration Tests
+// ============================================
+
+describe('MCP Tool Registration', () => {
+  it('should have correct tool descriptions exported', async () => {
+    const { toolDescriptions } = await import('@enterprise/tools/catalog-tools');
+
+    expect(toolDescriptions.getResources).toBeDefined();
+    expect(toolDescriptions.getResources).toContain('events');
+    expect(toolDescriptions.getResources).toContain('agents');
+    expect(toolDescriptions.analyzeChangeImpact).toBeDefined();
+    expect(toolDescriptions.analyzeChangeImpact).toContain('impact');
+  });
+
+  it('should have correct collection schemas exported', async () => {
+    const { collectionSchema, messageCollectionSchema, resourceCollectionSchema } = await import(
+      '@enterprise/tools/catalog-tools'
+    );
+
+    // Test collection schema includes all types
+    expect(collectionSchema.safeParse('events').success).toBe(true);
+    expect(collectionSchema.safeParse('agents').success).toBe(true);
+    expect(collectionSchema.safeParse('services').success).toBe(true);
+    expect(collectionSchema.safeParse('invalid').success).toBe(false);
+
+    // Test message collection schema
+    expect(messageCollectionSchema.safeParse('events').success).toBe(true);
+    expect(messageCollectionSchema.safeParse('commands').success).toBe(true);
+    expect(messageCollectionSchema.safeParse('queries').success).toBe(true);
+    expect(messageCollectionSchema.safeParse('services').success).toBe(false);
+
+    // Test resource collection schema
+    expect(resourceCollectionSchema.safeParse('agents').success).toBe(true);
+    expect(resourceCollectionSchema.safeParse('services').success).toBe(true);
+    expect(resourceCollectionSchema.safeParse('events').success).toBe(true);
+  });
+});
+
+// ============================================
+// prerender Export Test
+// ============================================
+
+describe('MCP Route Configuration', () => {
+  it('should disable prerendering for SSR', async () => {
+    const routeModule = await import('../mcp-server');
+    expect(routeModule.prerender).toBe(false);
+  });
+
+  it('should export ALL handler', async () => {
+    const routeModule = await import('../mcp-server');
+    expect(routeModule.ALL).toBeDefined();
+    expect(typeof routeModule.ALL).toBe('function');
+  });
+});
+
+// ============================================
+// Feature Gating Integration Tests
+// Note: SSR and Scale checks are now handled at build time
+// by the eventcatalog-features integration. The route is only
+// injected when isEventCatalogMCPEnabled() returns true.
+// ============================================
+
+describe('MCP Feature Gating (Integration Level)', () => {
+  it('should require isEventCatalogMCPEnabled to be true for route injection', async () => {
+    const { isEventCatalogMCPEnabled } = await import('@utils/feature');
+    // When MCP is enabled (SSR + Scale), the route should be injected
+    // This test verifies the feature check function exists and works
+    expect(typeof isEventCatalogMCPEnabled).toBe('function');
+  });
+});
+
+// ============================================
+// MCP Resources Tests
+// ============================================
+
+describe('MCP Resources', () => {
+  it('should define all expected resource URIs', async () => {
+    // Import the mcp-server module to check resources are defined
+    const expectedResources = [
+      'eventcatalog://all',
+      'eventcatalog://events',
+      'eventcatalog://commands',
+      'eventcatalog://queries',
+      'eventcatalog://agents',
+      'eventcatalog://services',
+      'eventcatalog://domains',
+      'eventcatalog://entities',
+      'eventcatalog://flows',
+      'eventcatalog://teams',
+      'eventcatalog://users',
+    ];
+
+    // The resources are exposed via the health check endpoint
+    const { ALL } = await import('../mcp-server');
+
+    const request = new Request('http://localhost:4321/docs/mcp', {
+      method: 'GET',
+    });
+
+    const response = await ALL({ request } as any);
+    const body = await response.json();
+
+    expect(body.resources).toBeDefined();
+    expect(body.resources.length).toBe(11);
+
+    for (const uri of expectedResources) {
+      expect(body.resources).toContain(uri);
+    }
+  });
+
+  it('should return resources in health check response', async () => {
+    const { ALL } = await import('../mcp-server');
+
+    const request = new Request('http://localhost:4321/docs/mcp', {
+      method: 'GET',
+    });
+
+    const response = await ALL({ request } as any);
+    expect(response.status).toBe(200);
+
+    const body = await response.json();
+    expect(body).toHaveProperty('resources');
+    expect(Array.isArray(body.resources)).toBe(true);
+  });
+});
+
+// ============================================
+// Search Filter in getResources Tool
+// ============================================
+
+describe('MCP getResources Tool with Search', () => {
+  it('should have search parameter in getResources tool description', async () => {
+    const { toolDescriptions } = await import('@enterprise/tools/catalog-tools');
+    expect(toolDescriptions.getResources).toContain('search');
+  });
+});
+
+// ============================================
+// Ubiquitous Language Tool
+// ============================================
+
+describe('MCP explainUbiquitousLanguageTerms Tool', () => {
+  it('should have explainUbiquitousLanguageTerms in toolDescriptions', async () => {
+    const { toolDescriptions } = await import('@enterprise/tools/catalog-tools');
+    expect(toolDescriptions.explainUbiquitousLanguageTerms).toBeDefined();
+    expect(toolDescriptions.explainUbiquitousLanguageTerms).toContain('ubiquitous language');
+  });
+});
diff --git a/packages/core/eventcatalog/src/enterprise/mcp/mcp-auth.ts b/packages/core/eventcatalog/src/enterprise/mcp/mcp-auth.ts
new file mode 100644
index 000000000..d5278bbd5
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/mcp/mcp-auth.ts
@@ -0,0 +1,266 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import jwt, { type Algorithm, type JwtPayload } from 'jsonwebtoken';
+import { createPublicKey, type JsonWebKey, type KeyObject } from 'node:crypto';
+import config from '../../../eventcatalog.config.js';
+import type { Config } from '../../../../src/eventcatalog.config';
+
+type ConfiguredMcpAuth = NonNullable<NonNullable<Config['mcp']>['auth']>;
+
+export type McpAuthConfig = ConfiguredMcpAuth;
+
+type TokenClaims = JwtPayload & {
+  scope?: string;
+  scp?: string[];
+};
+
+type JwksKey = JsonWebKey & {
+  kid?: string;
+};
+
+type AuthFailure = {
+  ok: false;
+  status: 401 | 403;
+  error: string;
+  description: string;
+  requiredScopes: string[];
+  metadataUrl: string;
+};
+
+export type McpAuthResult =
+  | {
+      ok: true;
+      claims?: TokenClaims;
+    }
+  | AuthFailure;
+
+const jwksCache = new Map<string, { expiresAt: number; keys: JwksKey[] }>();
+
+const quote = (value: string) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+export const getMcpAuthConfig = (): McpAuthConfig | undefined => config?.mcp?.auth;
+
+export const isMcpAuthEnabled = (
+  authConfig: McpAuthConfig | undefined = getMcpAuthConfig()
+): authConfig is McpAuthConfig & { enabled: true } => authConfig?.enabled === true;
+
+export function getMcpResourceUrl(request: Request, authConfig: McpAuthConfig | undefined = getMcpAuthConfig()) {
+  if (authConfig?.resource) return authConfig.resource;
+  return new URL('/docs/mcp', request.url).href;
+}
+
+export function getMcpProtectedResourceMetadataUrl(request: Request, authConfig: McpAuthConfig | undefined = getMcpAuthConfig()) {
+  if (authConfig?.protectedResourceMetadataUrl) return authConfig.protectedResourceMetadataUrl;
+  return new URL('/.well-known/oauth-protected-resource', request.url).href;
+}
+
+export function getMcpRequiredScopes(authConfig: McpAuthConfig | undefined = getMcpAuthConfig()) {
+  return authConfig?.requiredScopes ?? [];
+}
+
+export function getMcpProtectedResourceMetadata(request: Request, authConfig: McpAuthConfig | undefined = getMcpAuthConfig()) {
+  if (!isMcpAuthEnabled(authConfig)) return undefined;
+
+  return {
+    resource: getMcpResourceUrl(request, authConfig),
+    authorization_servers: authConfig?.authorizationServers ?? [],
+    scopes_supported: getMcpRequiredScopes(authConfig),
+  };
+}
+
+export function createWwwAuthenticateHeader(failure: AuthFailure) {
+  const params = [
+    `realm=${quote('mcp')}`,
+    `resource_metadata=${quote(failure.metadataUrl)}`,
+    failure.requiredScopes.length > 0 ? `scope=${quote(failure.requiredScopes.join(' '))}` : undefined,
+    failure.error ? `error=${quote(failure.error)}` : undefined,
+    failure.description ? `error_description=${quote(failure.description)}` : undefined,
+  ].filter(Boolean);
+
+  return `Bearer ${params.join(', ')}`;
+}
+
+export function createMcpAuthErrorResponse(failure: AuthFailure) {
+  return new Response(JSON.stringify({ error: failure.error, message: failure.description }), {
+    status: failure.status,
+    headers: {
+      'Content-Type': 'application/json',
+      'WWW-Authenticate': createWwwAuthenticateHeader(failure),
+    },
+  });
+}
+
+export async function validateMcpRequest(
+  request: Request,
+  authConfig: McpAuthConfig | undefined = getMcpAuthConfig()
+): Promise<McpAuthResult> {
+  if (!isMcpAuthEnabled(authConfig)) return { ok: true };
+
+  const metadataUrl = getMcpProtectedResourceMetadataUrl(request, authConfig);
+  const requiredScopes = getMcpRequiredScopes(authConfig);
+  const authHeader = request.headers.get('Authorization');
+  const bearerMatch = authHeader?.match(/^Bearer\s+(.*)$/i);
+
+  if (!bearerMatch) {
+    return {
+      ok: false,
+      status: 401,
+      error: 'invalid_token',
+      description: 'Missing Bearer access token',
+      requiredScopes,
+      metadataUrl,
+    };
+  }
+
+  const token = bearerMatch[1].trim();
+
+  if (!token) {
+    return {
+      ok: false,
+      status: 401,
+      error: 'invalid_token',
+      description: 'Missing Bearer access token',
+      requiredScopes,
+      metadataUrl,
+    };
+  }
+
+  try {
+    const claims = await verifyAccessToken(token, request, authConfig);
+    const missingScopes = getMissingScopes(claims, requiredScopes);
+
+    if (missingScopes.length > 0) {
+      return {
+        ok: false,
+        status: 403,
+        error: 'insufficient_scope',
+        description: `Missing required scope${missingScopes.length > 1 ? 's' : ''}: ${missingScopes.join(' ')}`,
+        requiredScopes,
+        metadataUrl,
+      };
+    }
+
+    return { ok: true, claims };
+  } catch {
+    return {
+      ok: false,
+      status: 401,
+      error: 'invalid_token',
+      description: 'Invalid or expired Bearer access token',
+      requiredScopes,
+      metadataUrl,
+    };
+  }
+}
+
+async function verifyAccessToken(token: string, request: Request, authConfig: McpAuthConfig): Promise<TokenClaims> {
+  const decoded = jwt.decode(token, { complete: true });
+  const algorithm = decoded && typeof decoded === 'object' ? (decoded.header.alg as Algorithm | undefined) : undefined;
+
+  if (!algorithm || algorithm === 'none') {
+    throw new Error('Unsupported JWT algorithm');
+  }
+
+  const key = await getVerificationKey(token, authConfig);
+  const audience = getJwtAudience(authConfig.audience ?? getMcpResourceUrl(request, authConfig));
+
+  const payload = jwt.verify(token, key, {
+    audience,
+    issuer: authConfig.issuer,
+    algorithms: [algorithm],
+    clockTolerance: 5,
+  });
+
+  if (!payload || typeof payload === 'string') {
+    throw new Error('Invalid JWT payload');
+  }
+
+  return payload as TokenClaims;
+}
+
+async function getVerificationKey(token: string, authConfig: McpAuthConfig): Promise<string | Buffer | KeyObject> {
+  const sharedSecret = getConfiguredValue(authConfig.sharedSecret, authConfig.sharedSecretEnvVar);
+  if (sharedSecret) return sharedSecret;
+
+  const publicKey = getConfiguredValue(authConfig.publicKey, authConfig.publicKeyEnvVar);
+  if (publicKey) return publicKey;
+
+  if (authConfig.jwksUri) {
+    return getJwksVerificationKey(token, authConfig.jwksUri);
+  }
+
+  throw new Error('MCP auth requires jwksUri, publicKey, publicKeyEnvVar, sharedSecret, or sharedSecretEnvVar');
+}
+
+function getConfiguredValue(value: string | undefined, envVar: string | undefined) {
+  if (value) return value;
+  if (envVar) return process.env[envVar];
+  return undefined;
+}
+
+async function getJwksVerificationKey(token: string, jwksUri: string) {
+  const decoded = jwt.decode(token, { complete: true });
+  const kid = decoded && typeof decoded === 'object' ? decoded.header.kid : undefined;
+  const keys = await getJwksKeys(jwksUri);
+  const jwk = keys.find((key) => (kid ? key.kid === kid : keys.length === 1));
+
+  if (!jwk) {
+    throw new Error('No matching JWKS key found for token');
+  }
+
+  return createPublicKey({ key: jwk, format: 'jwk' });
+}
+
+function getJwtAudience(audience: string | string[]) {
+  if (Array.isArray(audience)) {
+    if (audience.length === 0) return undefined;
+    return audience as [string, ...string[]];
+  }
+
+  return audience;
+}
+
+async function getJwksKeys(jwksUri: string): Promise<JwksKey[]> {
+  const cached = jwksCache.get(jwksUri);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.keys;
+  }
+
+  const response = await fetch(jwksUri, {
+    headers: {
+      Accept: 'application/json',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch JWKS: ${response.status}`);
+  }
+
+  const body = (await response.json()) as { keys?: JwksKey[] };
+  const keys = body.keys ?? [];
+  jwksCache.set(jwksUri, { keys, expiresAt: Date.now() + 5 * 60 * 1000 });
+  return keys;
+}
+
+function getMissingScopes(claims: TokenClaims, requiredScopes: string[]) {
+  if (requiredScopes.length === 0) return [];
+
+  const scopes = new Set<string>();
+
+  if (typeof claims.scope === 'string') {
+    for (const scope of claims.scope.split(/\s+/)) {
+      if (scope) scopes.add(scope);
+    }
+  }
+
+  if (Array.isArray(claims.scp)) {
+    for (const scope of claims.scp) {
+      scopes.add(scope);
+    }
+  }
+
+  return requiredScopes.filter((scope) => !scopes.has(scope));
+}
diff --git a/packages/core/eventcatalog/src/enterprise/mcp/mcp-server.ts b/packages/core/eventcatalog/src/enterprise/mcp/mcp-server.ts
new file mode 100644
index 000000000..7df60972a
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/mcp/mcp-server.ts
@@ -0,0 +1,608 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { APIRoute } from 'astro';
+import { Hono, type Context } from 'hono';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { z } from 'zod';
+import { join } from 'node:path';
+import { isEventCatalogScaleEnabled } from '@utils/feature';
+import {
+  getResources,
+  getResource,
+  getMessagesProducedOrConsumedByResource,
+  getSchemaForResource,
+  findResourcesByOwner,
+  getProducersOfMessage,
+  getConsumersOfMessage,
+  analyzeChangeImpact,
+  explainBusinessFlow,
+  getTeams,
+  getTeam,
+  getUsers,
+  getUser,
+  findMessageBySchemaId,
+  explainUbiquitousLanguageTerms,
+  getCustomDocs,
+  searchCustomDocs,
+  getCustomDoc,
+  collectionSchema,
+  resourceCollectionSchema,
+  messageCollectionSchema,
+  toolDescriptions,
+  getC4Diagram,
+} from '@enterprise/tools/catalog-tools';
+import { getCollection } from 'astro:content';
+import { createMcpAuthErrorResponse, validateMcpRequest } from './mcp-auth';
+
+const catalogDirectory = process.env.PROJECT_DIR || process.cwd();
+
+// Helper to create consistent MCP tool handlers with error handling
+function createToolHandler<T>(fn: (params: T) => Promise<any>, errorMessage: string) {
+  return async (params: T) => {
+    try {
+      const result = await fn(params);
+
+      if (result && 'error' in result) {
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result) }],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify({ error: `${errorMessage}: ${error}` }) }],
+        isError: true,
+      };
+    }
+  };
+}
+
+// Load extended tools from user configuration
+let extendedTools: Record<string, any> = {};
+let extendedToolNames: string[] = [];
+
+try {
+  const providerConfiguration = await import(/* @vite-ignore */ join(catalogDirectory, 'eventcatalog.chat.js'));
+
+  if (isEventCatalogScaleEnabled() && providerConfiguration.tools) {
+    extendedTools = providerConfiguration.tools;
+    extendedToolNames = Object.keys(extendedTools);
+  }
+} catch (error) {
+  // No chat configuration or tools defined - this is fine
+}
+
+// Create MCP Server with tools that access Astro collections
+function createMcpServer() {
+  const server = new McpServer({
+    name: 'EventCatalog MCP Server',
+    version: '1.0.0',
+  });
+
+  // Register all built-in tools using the helper
+  server.registerTool(
+    'getResources',
+    {
+      description: toolDescriptions.getResources,
+      inputSchema: z.object({
+        collection: collectionSchema.describe('The collection to get the resources from'),
+        cursor: z.string().optional().describe('Pagination cursor from previous response'),
+        search: z.string().optional().describe('Search term to filter resources by name, id, or summary (case-insensitive)'),
+      }),
+    },
+    createToolHandler(getResources, 'Failed to get resources')
+  );
+
+  server.registerTool(
+    'getResource',
+    {
+      description: toolDescriptions.getResource,
+      inputSchema: z.object({
+        collection: collectionSchema.describe('The collection to get the resource from'),
+        id: z.string().describe('The id of the resource to get'),
+        version: z.string().describe('The version of the resource to get'),
+      }),
+    },
+    createToolHandler(getResource, 'Failed to get resource')
+  );
+
+  server.registerTool(
+    'getMessagesProducedOrConsumedByResource',
+    {
+      description: toolDescriptions.getMessagesProducedOrConsumedByResource,
+      inputSchema: z.object({
+        resourceId: z.string().describe('The id of the resource to get the messages produced or consumed for'),
+        resourceVersion: z.string().describe('The version of the resource to get the messages produced or consumed for'),
+        resourceCollection: resourceCollectionSchema
+          .describe('The collection of the resource to get the messages produced or consumed for')
+          .default('services'),
+      }),
+    },
+    createToolHandler(getMessagesProducedOrConsumedByResource, 'Failed to get messages')
+  );
+
+  server.registerTool(
+    'getSchemaForResource',
+    {
+      description: toolDescriptions.getSchemaForResource,
+      inputSchema: z.object({
+        resourceId: z.string().describe('The id of the resource to get the schema for'),
+        resourceVersion: z.string().describe('The version of the resource to get the schema for'),
+        resourceCollection: resourceCollectionSchema
+          .describe('The collection of the resource to get the schema for')
+          .default('services'),
+      }),
+    },
+    createToolHandler(getSchemaForResource, 'Failed to get schema')
+  );
+
+  server.registerTool(
+    'findResourcesByOwner',
+    {
+      description: toolDescriptions.findResourcesByOwner,
+      inputSchema: z.object({
+        ownerId: z.string().describe('The id of the owner (team or user) to find resources for'),
+      }),
+    },
+    createToolHandler(findResourcesByOwner, 'Failed to find resources')
+  );
+
+  server.registerTool(
+    'getProducersOfMessage',
+    {
+      description: toolDescriptions.getProducersOfMessage,
+      inputSchema: z.object({
+        messageId: z.string().describe('The id of the message to find producers for'),
+        messageVersion: z.string().describe('The version of the message'),
+        messageCollection: messageCollectionSchema
+          .describe('The collection type of the message (events, commands, or queries)')
+          .default('events'),
+      }),
+    },
+    createToolHandler(getProducersOfMessage, 'Failed to get producers')
+  );
+
+  server.registerTool(
+    'getConsumersOfMessage',
+    {
+      description: toolDescriptions.getConsumersOfMessage,
+      inputSchema: z.object({
+        messageId: z.string().describe('The id of the message to find consumers for'),
+        messageVersion: z.string().describe('The version of the message'),
+        messageCollection: messageCollectionSchema
+          .describe('The collection type of the message (events, commands, or queries)')
+          .default('events'),
+      }),
+    },
+    createToolHandler(getConsumersOfMessage, 'Failed to get consumers')
+  );
+
+  server.registerTool(
+    'getC4Diagram',
+    {
+      description: toolDescriptions.getC4Diagram,
+      inputSchema: z.object({
+        viewId: z.string().describe('The id of the LikeC4 view to return source files for').optional(),
+      }),
+    },
+    createToolHandler(getC4Diagram, 'Failed to get c4 diagram')
+  );
+
+  server.registerTool(
+    'analyzeChangeImpact',
+    {
+      description: toolDescriptions.analyzeChangeImpact,
+      inputSchema: z.object({
+        messageId: z.string().describe('The id of the message to analyze impact for'),
+        messageVersion: z.string().describe('The version of the message'),
+        messageCollection: messageCollectionSchema
+          .describe('The collection type of the message (events, commands, or queries)')
+          .default('events'),
+      }),
+    },
+    createToolHandler(analyzeChangeImpact, 'Failed to analyze impact')
+  );
+
+  server.registerTool(
+    'explainBusinessFlow',
+    {
+      description: toolDescriptions.explainBusinessFlow,
+      inputSchema: z.object({
+        flowId: z.string().describe('The id of the flow to explain'),
+        flowVersion: z.string().describe('The version of the flow'),
+      }),
+    },
+    createToolHandler(explainBusinessFlow, 'Failed to explain flow')
+  );
+
+  server.registerTool(
+    'getTeams',
+    {
+      description: toolDescriptions.getTeams,
+      inputSchema: z.object({
+        cursor: z.string().optional().describe('Pagination cursor from previous response'),
+      }),
+    },
+    createToolHandler(getTeams, 'Failed to get teams')
+  );
+
+  server.registerTool(
+    'getTeam',
+    {
+      description: toolDescriptions.getTeam,
+      inputSchema: z.object({
+        id: z.string().describe('The id of the team to get'),
+      }),
+    },
+    createToolHandler(getTeam, 'Failed to get team')
+  );
+
+  server.registerTool(
+    'getUsers',
+    {
+      description: toolDescriptions.getUsers,
+      inputSchema: z.object({
+        cursor: z.string().optional().describe('Pagination cursor from previous response'),
+      }),
+    },
+    createToolHandler(getUsers, 'Failed to get users')
+  );
+
+  server.registerTool(
+    'getUser',
+    {
+      description: toolDescriptions.getUser,
+      inputSchema: z.object({
+        id: z.string().describe('The id of the user to get'),
+      }),
+    },
+    createToolHandler(getUser, 'Failed to get user')
+  );
+
+  server.registerTool(
+    'findMessageBySchemaId',
+    {
+      description: toolDescriptions.findMessageBySchemaId,
+      inputSchema: z.object({
+        messageId: z.string().describe('The message id (from x-eventcatalog-id in the schema)'),
+        messageVersion: z
+          .string()
+          .optional()
+          .describe(
+            'The message version (from x-eventcatalog-version in the schema). If not provided, returns the latest version.'
+          ),
+        collection: messageCollectionSchema
+          .optional()
+          .describe('Optional hint for which collection to search (events, commands, or queries)'),
+      }),
+    },
+    createToolHandler(findMessageBySchemaId, 'Failed to find message')
+  );
+
+  server.registerTool(
+    'explainUbiquitousLanguageTerms',
+    {
+      description: toolDescriptions.explainUbiquitousLanguageTerms,
+      inputSchema: z.object({
+        domainId: z.string().describe('The id of the domain to get ubiquitous language terms for'),
+        domainVersion: z.string().optional().describe('The version of the domain. If not provided, uses the latest version.'),
+      }),
+    },
+    createToolHandler(explainUbiquitousLanguageTerms, 'Failed to get ubiquitous language terms')
+  );
+
+  server.registerTool(
+    'getCustomDocs',
+    {
+      description: toolDescriptions.getCustomDocs,
+      inputSchema: z.object({
+        cursor: z.string().optional().describe('Pagination cursor from previous response'),
+        search: z.string().optional().describe('Search term to filter docs by title, id, or summary (case-insensitive)'),
+      }),
+    },
+    createToolHandler(getCustomDocs, 'Failed to get custom documentation pages')
+  );
+
+  server.registerTool(
+    'searchCustomDocs',
+    {
+      description: toolDescriptions.searchCustomDocs,
+      inputSchema: z.object({
+        query: z.string().describe('Full-text search query, e.g. keywords describing the topic to find'),
+        limit: z.number().optional().describe('Maximum number of results to return (default 10)'),
+      }),
+    },
+    createToolHandler(searchCustomDocs, 'Failed to search custom documentation')
+  );
+
+  server.registerTool(
+    'getCustomDoc',
+    {
+      description: toolDescriptions.getCustomDoc,
+      inputSchema: z.object({
+        id: z.string().describe('The id or slug of the custom documentation page'),
+        section: z.string().optional().describe('Optional section heading to return only that section of the page'),
+      }),
+    },
+    createToolHandler(getCustomDoc, 'Failed to get custom documentation page')
+  );
+
+  // Register extended tools from user configuration
+  for (const [toolName, toolConfig] of Object.entries(extendedTools)) {
+    if (!toolConfig || typeof toolConfig !== 'object') continue;
+
+    // Extract tool properties (Vercel AI SDK format)
+    // The AI SDK tool() helper uses "inputSchema" for Zod schemas
+    const { description, parameters, inputSchema, execute } = toolConfig;
+
+    if (!description || !execute) {
+      console.warn(`[MCP] Skipping invalid extended tool: ${toolName}`);
+      continue;
+    }
+
+    server.registerTool(
+      toolName,
+      {
+        description: description || `Custom tool: ${toolName}`,
+        inputSchema: inputSchema || parameters || z.object({}),
+      },
+      async (params: any) => {
+        try {
+          const result = await execute(params);
+          return {
+            content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+          };
+        } catch (error) {
+          return {
+            content: [{ type: 'text' as const, text: JSON.stringify({ error: `Failed to execute ${toolName}: ${error}` }) }],
+            isError: true,
+          };
+        }
+      }
+    );
+  }
+
+  // ============================================
+  // Register MCP Resources
+  // ============================================
+
+  const resourceDefinitions = [
+    {
+      name: 'All Resources in EventCatalog',
+      uri: 'eventcatalog://all',
+      description: 'All messages, agents, domains and services in EventCatalog',
+      collections: [
+        'events',
+        'commands',
+        'queries',
+        'agents',
+        'services',
+        'domains',
+        'flows',
+        'channels',
+        'entities',
+        'adrs',
+      ] as const,
+    },
+    {
+      name: 'All Events in EventCatalog',
+      uri: 'eventcatalog://events',
+      description: 'All events in EventCatalog',
+      collections: ['events'] as const,
+    },
+    {
+      name: 'All Commands in EventCatalog',
+      uri: 'eventcatalog://commands',
+      description: 'All commands in EventCatalog',
+      collections: ['commands'] as const,
+    },
+    {
+      name: 'All Queries in EventCatalog',
+      uri: 'eventcatalog://queries',
+      description: 'All queries in EventCatalog',
+      collections: ['queries'] as const,
+    },
+    {
+      name: 'All Services in EventCatalog',
+      uri: 'eventcatalog://services',
+      description: 'All services in EventCatalog',
+      collections: ['services'] as const,
+    },
+    {
+      name: 'All Agents in EventCatalog',
+      uri: 'eventcatalog://agents',
+      description: 'All agents in EventCatalog',
+      collections: ['agents'] as const,
+    },
+    {
+      name: 'All Architecture Decision Records (adrs) in EventCatalog',
+      uri: 'eventcatalog://adrs',
+      description: 'All architecture decision records in EventCatalog',
+      collections: ['adrs'] as const,
+    },
+    {
+      name: 'All Domains in EventCatalog',
+      uri: 'eventcatalog://domains',
+      description: 'All domains in EventCatalog',
+      collections: ['domains'] as const,
+    },
+    {
+      name: 'All Diagrams in EventCatalog',
+      uri: 'eventcatalog://diagrams',
+      description: 'All diagrams in EventCatalog',
+      collections: ['diagrams'] as const,
+    },
+    {
+      name: 'All Channels in EventCatalog',
+      uri: 'eventcatalog://channels',
+      description: 'All channels in EventCatalog',
+      collections: ['channels'] as const,
+    },
+    {
+      name: 'All Entities in EventCatalog',
+      uri: 'eventcatalog://entities',
+      description: 'All entities in EventCatalog',
+      collections: ['entities'] as const,
+    },
+    {
+      name: 'All Containers  in EventCatalog',
+      uri: 'eventcatalog://containers',
+      description: 'All containers in EventCatalog',
+      collections: ['containers'] as const,
+    },
+    {
+      name: 'All Flows in EventCatalog',
+      uri: 'eventcatalog://flows',
+      description: 'All flows in EventCatalog',
+      collections: ['flows'] as const,
+    },
+    {
+      name: 'All Teams in EventCatalog',
+      uri: 'eventcatalog://teams',
+      description: 'All teams in EventCatalog',
+      collections: ['teams'] as const,
+    },
+    {
+      name: 'All Users in EventCatalog',
+      uri: 'eventcatalog://users',
+      description: 'All users in EventCatalog',
+      collections: ['users'] as const,
+    },
+  ];
+
+  for (const resource of resourceDefinitions) {
+    server.registerResource(
+      resource.name,
+      resource.uri,
+      { description: resource.description, mimeType: 'application/json' },
+      async (uri: URL) => {
+        const allResources: any[] = [];
+
+        for (const collectionName of resource.collections) {
+          try {
+            const items = await getCollection(collectionName as any);
+            for (const item of items) {
+              allResources.push({
+                type: collectionName,
+                id: (item as any).data.id,
+                version: (item as any).data.version,
+                name: (item as any).data.name || (item as any).data.id,
+                summary: (item as any).data.summary,
+              });
+            }
+          } catch {
+            // Collection might not exist, skip it
+          }
+        }
+
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              text: JSON.stringify({ resources: allResources }, null, 2),
+              mimeType: 'application/json',
+            },
+          ],
+        };
+      }
+    );
+  }
+
+  return server;
+}
+
+// MCP server and transport are created per-request to avoid
+// "Stateless transport cannot be reused across requests" errors.
+
+// Create Hono app for MCP routes
+const app = new Hono().basePath('/docs/mcp');
+
+// Built-in tool names derived from toolDescriptions
+const builtInTools = Object.keys(toolDescriptions);
+
+// MCP Resource URIs
+const mcpResources = [
+  'eventcatalog://all',
+  'eventcatalog://events',
+  'eventcatalog://commands',
+  'eventcatalog://queries',
+  'eventcatalog://agents',
+  'eventcatalog://adrs',
+  'eventcatalog://services',
+  'eventcatalog://domains',
+  'eventcatalog://entities',
+  'eventcatalog://flows',
+  'eventcatalog://teams',
+  'eventcatalog://users',
+];
+
+// Health check endpoint
+app.get('/', async (c: Context) => {
+  const auth = await validateMcpRequest(c.req.raw);
+
+  if (!auth.ok) {
+    return createMcpAuthErrorResponse(auth);
+  }
+
+  return c.json({
+    name: 'EventCatalog MCP Server',
+    version: '1.1.0',
+    status: 'running',
+    tools: [...builtInTools, ...extendedToolNames],
+    extendedTools: extendedToolNames.length > 0 ? extendedToolNames : undefined,
+    resources: mcpResources,
+  });
+});
+
+// MCP protocol endpoint - handles POST requests for MCP protocol
+app.post('/', async (c: Context) => {
+  try {
+    const auth = await validateMcpRequest(c.req.raw);
+
+    if (!auth.ok) {
+      return createMcpAuthErrorResponse(auth);
+    }
+
+    // Create fresh server and transport per request — the MCP SDK's
+    // WebStandardStreamableHTTPServerTransport is single-use in stateless
+    // mode: it sets _hasHandledRequest=true after the first call and throws
+    // on any subsequent request. McpServer equally rejects reconnection.
+    const server = createMcpServer();
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
+    await server.connect(transport);
+    return await transport.handleRequest(c.req.raw);
+  } catch (error) {
+    console.error('MCP request error:', error);
+    return c.json(
+      {
+        jsonrpc: '2.0',
+        error: {
+          code: -32603,
+          message: 'Internal server error',
+        },
+        id: null,
+      },
+      500
+    );
+  }
+});
+
+// Astro API route handler - delegates all requests to Hono
+// Note: SSR and Scale plan checks are handled at build time by the integration
+// This route is only injected when isEventCatalogMCPEnabled() returns true
+export const ALL: APIRoute = async ({ request }) => {
+  return app.fetch(request);
+};
+
+// Disable prerendering for SSR
+export const prerender = false;
diff --git a/packages/core/eventcatalog/src/enterprise/mcp/oauth-protected-resource.ts b/packages/core/eventcatalog/src/enterprise/mcp/oauth-protected-resource.ts
new file mode 100644
index 000000000..67627a3ea
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/mcp/oauth-protected-resource.ts
@@ -0,0 +1,25 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { APIRoute } from 'astro';
+import { getMcpProtectedResourceMetadata } from './mcp-auth';
+
+export const GET: APIRoute = async ({ request }) => {
+  const metadata = getMcpProtectedResourceMetadata(request);
+
+  if (!metadata) {
+    return new Response(JSON.stringify({ error: 'mcp_auth_not_configured' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  return new Response(JSON.stringify(metadata, null, 2), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  });
+};
+
+export const prerender = false;
diff --git a/packages/core/eventcatalog/src/enterprise/tools/__tests__/catalog-tools.mocks.ts b/packages/core/eventcatalog/src/enterprise/tools/__tests__/catalog-tools.mocks.ts
new file mode 100644
index 000000000..6f47e2aa9
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/tools/__tests__/catalog-tools.mocks.ts
@@ -0,0 +1,652 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+/**
+ * Mock data for catalog-tools tests
+ * Follows the Astro content collection structure
+ */
+
+// ============================================
+// Mock Events
+// ============================================
+export const mockEvents = [
+  {
+    id: 'OrderCreated-1.0.0',
+    slug: 'events/OrderCreated',
+    collection: 'events',
+    body: 'Order created event description',
+    data: {
+      id: 'OrderCreated',
+      name: 'Order Created',
+      version: '1.0.0',
+      summary: 'Fired when an order is created',
+      owners: ['order-team', { id: 'user-jane' }],
+    },
+  },
+  {
+    id: 'OrderCreated-2.0.0',
+    slug: 'events/OrderCreated',
+    collection: 'events',
+    body: 'Order created event v2 description',
+    data: {
+      id: 'OrderCreated',
+      name: 'Order Created V2',
+      version: '2.0.0',
+      summary: 'Updated order created event',
+      owners: ['order-team'],
+    },
+  },
+  {
+    id: 'PaymentProcessed-1.0.0',
+    slug: 'events/PaymentProcessed',
+    collection: 'events',
+    body: 'Payment processed event description',
+    data: {
+      id: 'PaymentProcessed',
+      name: 'Payment Processed',
+      version: '1.0.0',
+      summary: 'Fired when a payment is processed',
+      owners: ['payment-team'],
+    },
+  },
+  {
+    id: 'InventoryUpdated-1.0.0',
+    slug: 'events/InventoryUpdated',
+    collection: 'events',
+    body: 'Inventory updated event description',
+    data: {
+      id: 'InventoryUpdated',
+      name: 'Inventory Updated',
+      version: '1.0.0',
+      summary: 'Fired when inventory is updated',
+      owners: [{ id: 'inventory-team' }],
+    },
+  },
+];
+
+// ============================================
+// Mock Services
+// ============================================
+export const mockServices = [
+  {
+    id: 'OrderService-1.0.0',
+    slug: 'services/OrderService',
+    collection: 'services',
+    body: 'Order service description',
+    data: {
+      id: 'OrderService',
+      name: 'Order Service',
+      version: '1.0.0',
+      summary: 'Handles order processing',
+      owners: ['order-team'],
+      sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      receives: [{ id: 'PaymentProcessed', version: '1.0.0' }],
+      flows: [{ id: 'OrderFlow' }],
+    },
+  },
+  {
+    id: 'PaymentService-1.0.0',
+    slug: 'services/PaymentService',
+    collection: 'services',
+    body: 'Payment service description',
+    data: {
+      id: 'PaymentService',
+      name: 'Payment Service',
+      version: '1.0.0',
+      summary: 'Handles payment processing',
+      owners: ['payment-team', { id: 'user-bob' }],
+      sends: [{ id: 'PaymentProcessed', version: 'latest' }],
+      receives: [{ id: 'OrderCreated' }], // No version = all versions
+    },
+  },
+  {
+    id: 'InventoryService-1.0.0',
+    slug: 'services/InventoryService',
+    collection: 'services',
+    body: 'Inventory service description',
+    data: {
+      id: 'InventoryService',
+      name: 'Inventory Service',
+      version: '1.0.0',
+      summary: 'Handles inventory management',
+      owners: [{ id: 'inventory-team' }],
+      sends: [{ id: 'InventoryUpdated', version: '1.0.0' }],
+      receives: [{ id: 'OrderCreated', version: '1.0.0' }],
+    },
+  },
+  {
+    id: 'NotificationService-1.0.0',
+    slug: 'services/NotificationService',
+    collection: 'services',
+    body: 'Notification service description',
+    data: {
+      id: 'NotificationService',
+      name: 'Notification Service',
+      version: '1.0.0',
+      summary: 'Sends notifications',
+      owners: [],
+      receives: [{ id: 'OrderCreated', version: '2.0.0' }],
+    },
+  },
+];
+
+// ============================================
+// Mock Systems
+// ============================================
+export const mockSystems = [
+  {
+    id: 'CoreSystem-1.0.0',
+    slug: 'systems/CoreSystem',
+    collection: 'systems',
+    body: 'Core system description',
+    data: {
+      id: 'CoreSystem',
+      name: 'Core System',
+      version: '1.0.0',
+      summary: 'Groups core order services',
+      owners: ['order-team'],
+      services: [{ id: 'OrderService', version: '1.0.0' }],
+    },
+  },
+];
+
+// ============================================
+// Mock Agents
+// ============================================
+export const mockAgents = [
+  {
+    id: 'FraudReviewAgent-1.0.0',
+    slug: 'agents/FraudReviewAgent',
+    collection: 'agents',
+    body: 'Fraud review agent description',
+    data: {
+      id: 'FraudReviewAgent',
+      name: 'Fraud Review Agent',
+      version: '1.0.0',
+      summary: 'Reviews risky payments',
+      owners: ['risk-team'],
+      receives: [{ id: 'PaymentProcessed', version: '1.0.0' }],
+      sends: [{ id: 'InventoryUpdated', version: '1.0.0' }],
+      flows: [{ id: 'OrderFlow' }],
+      model: {
+        provider: 'OpenAI',
+        name: 'gpt-4.1',
+        version: '2025-04-14',
+      },
+    },
+  },
+];
+
+// ============================================
+// Mock Commands
+// ============================================
+export const mockCommands = [
+  {
+    id: 'CreateOrder-1.0.0',
+    slug: 'commands/CreateOrder',
+    collection: 'commands',
+    body: 'Create order command description',
+    data: {
+      id: 'CreateOrder',
+      name: 'Create Order',
+      version: '1.0.0',
+      summary: 'Command to create an order',
+      owners: ['order-team'],
+    },
+  },
+];
+
+// ============================================
+// Mock Queries
+// ============================================
+export const mockQueries = [
+  {
+    id: 'GetOrder-1.0.0',
+    slug: 'queries/GetOrder',
+    collection: 'queries',
+    body: 'Get order query description',
+    data: {
+      id: 'GetOrder',
+      name: 'Get Order',
+      version: '1.0.0',
+      summary: 'Query to get an order',
+      owners: ['order-team'],
+    },
+  },
+];
+
+// ============================================
+// Mock Flows
+// ============================================
+export const mockFlows = [
+  {
+    id: 'OrderFlow-1.0.0',
+    slug: 'flows/OrderFlow',
+    collection: 'flows',
+    body: '# Order Processing Flow\n\nDetailed flow description in markdown.',
+    data: {
+      id: 'OrderFlow',
+      name: 'Order Processing Flow',
+      version: '1.0.0',
+      summary: 'End-to-end order processing workflow',
+      owners: ['order-team'],
+      steps: [
+        { id: 1, title: 'Order Placed', next_step: 2 },
+        { id: 2, title: 'Payment Processing', message: { id: 'PaymentProcessed', version: '1.0.0' }, next_step: 3 },
+        { id: 3, title: 'Order Confirmed' },
+      ],
+      mermaid: 'graph TD; A[Order Placed]-->B[Payment Processing]; B-->C[Order Confirmed];',
+    },
+  },
+  {
+    id: 'PaymentFlow-1.0.0',
+    slug: 'flows/PaymentFlow',
+    collection: 'flows',
+    body: 'Payment flow description',
+    data: {
+      id: 'PaymentFlow',
+      name: 'Payment Flow',
+      version: '1.0.0',
+      summary: 'Payment processing workflow',
+      owners: ['payment-team'],
+      steps: [],
+    },
+  },
+];
+
+// ============================================
+// Mock Domains (with subdomains for ubiquitous language testing)
+// ============================================
+export const mockDomains = [
+  {
+    id: 'OrderDomain-1.0.0',
+    slug: 'domains/OrderDomain',
+    collection: 'domains',
+    filePath: '/domains/OrderDomain/index.mdx',
+    body: 'Order domain description',
+    data: {
+      id: 'OrderDomain',
+      name: 'Order Domain',
+      version: '1.0.0',
+      summary: 'Order management domain',
+      owners: ['order-team'],
+      // Subdomains reference
+      domains: [
+        {
+          data: {
+            id: 'FulfillmentSubdomain',
+            name: 'Fulfillment Subdomain',
+            version: '1.0.0',
+          },
+          filePath: '/domains/OrderDomain/FulfillmentSubdomain/index.mdx',
+        },
+      ],
+    },
+  },
+  {
+    id: 'FulfillmentSubdomain-1.0.0',
+    slug: 'domains/FulfillmentSubdomain',
+    collection: 'domains',
+    filePath: '/domains/OrderDomain/FulfillmentSubdomain/index.mdx',
+    body: 'Fulfillment subdomain description',
+    data: {
+      id: 'FulfillmentSubdomain',
+      name: 'Fulfillment Subdomain',
+      version: '1.0.0',
+      summary: 'Handles order fulfillment',
+      owners: ['order-team'],
+    },
+  },
+  {
+    id: 'EmptyDomain-1.0.0',
+    slug: 'domains/EmptyDomain',
+    collection: 'domains',
+    filePath: '/domains/EmptyDomain/index.mdx',
+    body: 'Empty domain description',
+    data: {
+      id: 'EmptyDomain',
+      name: 'Empty Domain',
+      version: '1.0.0',
+      summary: 'Domain with no ubiquitous language',
+      owners: [],
+    },
+  },
+];
+
+// ============================================
+// Mock Ubiquitous Languages
+// ============================================
+export const mockUbiquitousLanguages = [
+  {
+    id: 'OrderDomain-language',
+    slug: 'ubiquitousLanguages/OrderDomain',
+    collection: 'ubiquitousLanguages',
+    filePath: '/domains/OrderDomain/language.mdx',
+    body: 'Order domain ubiquitous language',
+    data: {
+      dictionary: [
+        {
+          id: 'order',
+          name: 'Order',
+          summary: 'A request to purchase goods or services',
+          icon: 'ShoppingCart',
+        },
+        {
+          id: 'line-item',
+          name: 'Line Item',
+          summary: 'An individual product or service within an order',
+          icon: 'Package',
+        },
+        {
+          id: 'customer',
+          name: 'Customer',
+          summary: 'A person or entity placing an order',
+        },
+      ],
+    },
+  },
+  {
+    id: 'FulfillmentSubdomain-language',
+    slug: 'ubiquitousLanguages/FulfillmentSubdomain',
+    collection: 'ubiquitousLanguages',
+    filePath: '/domains/OrderDomain/FulfillmentSubdomain/language.mdx',
+    body: 'Fulfillment subdomain ubiquitous language',
+    data: {
+      dictionary: [
+        {
+          id: 'shipment',
+          name: 'Shipment',
+          summary: 'A package sent to fulfill an order',
+          icon: 'Truck',
+        },
+        {
+          id: 'customer',
+          name: 'Customer',
+          summary: 'Duplicate term - recipient of a shipment',
+        },
+      ],
+    },
+  },
+];
+
+// ============================================
+// Mock Channels
+// ============================================
+export const mockChannels = [
+  {
+    id: 'OrderChannel-1.0.0',
+    slug: 'channels/OrderChannel',
+    collection: 'channels',
+    body: 'Order channel description',
+    data: {
+      id: 'OrderChannel',
+      name: 'Order Channel',
+      version: '1.0.0',
+      summary: 'Channel for order events',
+      owners: ['order-team'],
+    },
+  },
+];
+
+// ============================================
+// Mock Entities
+// ============================================
+export const mockEntities = [
+  {
+    id: 'Order-1.0.0',
+    slug: 'entities/Order',
+    collection: 'entities',
+    body: 'Order entity description',
+    data: {
+      id: 'Order',
+      name: 'Order',
+      version: '1.0.0',
+      summary: 'Order entity',
+      owners: ['order-team'],
+    },
+  },
+];
+
+// ============================================
+// Mock Teams
+// ============================================
+export const mockTeams = [
+  {
+    id: 'order-team',
+    slug: 'teams/order-team',
+    collection: 'teams',
+    body: 'The order team handles all order-related services.',
+    data: {
+      id: 'order-team',
+      name: 'Order Team',
+      email: 'order-team@company.com',
+      slackDirectMessageUrl: 'https://slack.com/dm/order-team',
+      members: ['user-jane', 'user-john'],
+      summary: 'Handles order processing',
+    },
+  },
+  {
+    id: 'payment-team',
+    slug: 'teams/payment-team',
+    collection: 'teams',
+    body: 'The payment team handles all payment-related services.',
+    data: {
+      id: 'payment-team',
+      name: 'Payment Team',
+      email: 'payment-team@company.com',
+      slackDirectMessageUrl: 'https://slack.com/dm/payment-team',
+      members: ['user-bob'],
+      summary: 'Handles payment processing',
+    },
+  },
+  {
+    id: 'inventory-team',
+    slug: 'teams/inventory-team',
+    collection: 'teams',
+    body: 'The inventory team handles all inventory-related services.',
+    data: {
+      id: 'inventory-team',
+      name: 'Inventory Team',
+      email: 'inventory-team@company.com',
+      members: [],
+      summary: 'Handles inventory management',
+    },
+  },
+];
+
+// ============================================
+// Mock Users
+// ============================================
+export const mockUsers = [
+  {
+    id: 'user-jane',
+    slug: 'users/user-jane',
+    collection: 'users',
+    body: 'Jane is the lead engineer on the order team.',
+    data: {
+      id: 'user-jane',
+      name: 'Jane Doe',
+      email: 'jane@company.com',
+      role: 'Lead Engineer',
+      slackDirectMessageUrl: 'https://slack.com/dm/jane',
+      summary: 'Lead engineer on order team',
+    },
+  },
+  {
+    id: 'user-john',
+    slug: 'users/user-john',
+    collection: 'users',
+    body: 'John is a senior engineer on the order team.',
+    data: {
+      id: 'user-john',
+      name: 'John Smith',
+      email: 'john@company.com',
+      role: 'Senior Engineer',
+      slackDirectMessageUrl: 'https://slack.com/dm/john',
+      summary: 'Senior engineer on order team',
+    },
+  },
+  {
+    id: 'user-bob',
+    slug: 'users/user-bob',
+    collection: 'users',
+    body: 'Bob is the lead engineer on the payment team.',
+    data: {
+      id: 'user-bob',
+      name: 'Bob Johnson',
+      email: 'bob@company.com',
+      role: 'Lead Engineer',
+      summary: 'Lead engineer on payment team',
+    },
+  },
+];
+
+// ============================================
+// Mock Containers (for completeness)
+// ============================================
+export const mockContainers = [
+  {
+    id: 'OrderDatabase-1.0.0',
+    slug: 'containers/OrderDatabase',
+    collection: 'containers',
+    body: 'Order database description',
+    data: {
+      id: 'OrderDatabase',
+      name: 'Order Database',
+      version: '1.0.0',
+      summary: 'Order data storage',
+      owners: ['order-team'],
+    },
+  },
+];
+
+// ============================================
+// Mock Diagrams (for completeness)
+// ============================================
+export const mockDiagrams = [
+  {
+    id: 'SystemOverview-1.0.0',
+    slug: 'diagrams/SystemOverview',
+    collection: 'diagrams',
+    body: 'System overview diagram',
+    data: {
+      id: 'SystemOverview',
+      name: 'System Overview',
+      version: '1.0.0',
+      summary: 'High-level system diagram',
+      owners: ['order-team'],
+    },
+  },
+];
+
+// ============================================
+// Mock ADRs
+// ============================================
+export const mockAdrs = [
+  {
+    id: 'adr-001-1.0.0',
+    slug: 'adrs/adr-001',
+    collection: 'adrs',
+    body: 'ADR description',
+    data: {
+      id: 'adr-001',
+      name: 'Choose event-driven orders',
+      version: '1.0.0',
+      summary: 'Decision to use events for order workflows',
+      owners: ['order-team'],
+      status: 'accepted',
+      date: new Date('2025-01-01'),
+    },
+  },
+];
+
+// ============================================
+// Mock Schemas
+// ============================================
+export const mockSchemas = [
+  {
+    id: 'file://schemas/OrderCreated.schema.json',
+    collection: 'schemas',
+    body: '{"type":"object","title":"OrderCreated"}',
+    data: {
+      id: 'file://schemas/OrderCreated.schema.json',
+      ref: 'file://schemas/OrderCreated.schema.json',
+      name: 'OrderCreated.schema.json',
+      format: 'jsonschema',
+      content: '{"type":"object","title":"OrderCreated"}',
+      source: {
+        provider: 'file',
+        path: 'schemas/OrderCreated.schema.json',
+      },
+      message: {
+        collection: 'events',
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Fired when an order is created',
+        owners: ['order-team'],
+      },
+      latest: true,
+    },
+  },
+];
+
+// ============================================
+// Mock Custom Pages (custom documentation)
+// ============================================
+export const mockCustomPages = [
+  {
+    id: 'docs/payments/runbook',
+    collection: 'customPages',
+    body: [
+      'Intro to operating payments.',
+      '',
+      '## Refund failures',
+      'When a refund fails, retry the refund three times.',
+      '',
+      '## Chargeback handling',
+      'Chargebacks are disputed via the acquirer portal.',
+    ].join('\n'),
+    data: {
+      title: 'Payment Runbook',
+      summary: 'How we operate payments',
+      owners: ['payment-team'],
+    },
+  },
+  {
+    id: 'docs/onboarding',
+    collection: 'customPages',
+    body: 'Welcome to the team. Ask the order team for repository access.',
+    data: {
+      title: 'Onboarding Guide',
+      summary: 'Getting started as a new engineer',
+      slug: 'getting-started',
+    },
+  },
+];
+
+// ============================================
+// Helper to get all mocks by collection
+// ============================================
+export const mockCollections: Record<string, any[]> = {
+  events: mockEvents,
+  agents: mockAgents,
+  systems: mockSystems,
+  services: mockServices,
+  commands: mockCommands,
+  queries: mockQueries,
+  flows: mockFlows,
+  domains: mockDomains,
+  channels: mockChannels,
+  entities: mockEntities,
+  adrs: mockAdrs,
+  containers: mockContainers,
+  diagrams: mockDiagrams,
+  schemas: mockSchemas,
+  teams: mockTeams,
+  users: mockUsers,
+  ubiquitousLanguages: mockUbiquitousLanguages,
+  customPages: mockCustomPages,
+};
diff --git a/packages/core/eventcatalog/src/enterprise/tools/__tests__/catalog-tools.spec.ts b/packages/core/eventcatalog/src/enterprise/tools/__tests__/catalog-tools.spec.ts
new file mode 100644
index 000000000..552725e39
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/tools/__tests__/catalog-tools.spec.ts
@@ -0,0 +1,1442 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { CollectionKey } from 'astro:content';
+import fs from 'node:fs';
+import { glob } from 'glob';
+
+// Type definitions for test results
+type ProducerConsumer = { id: string; version: string; name: string };
+type ResourceResult = { collection: string; id: string; version?: string; name: string };
+import { mockEvents, mockTeams, mockUsers, mockCollections } from './catalog-tools.mocks';
+
+// Mock astro:content
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: (key: CollectionKey) => {
+      return Promise.resolve(mockCollections[key as string] ?? []);
+    },
+    getEntry: (collection: string, id: string) => {
+      const items = mockCollections[collection] ?? [];
+      return Promise.resolve(items.find((item) => item.id === id));
+    },
+  };
+});
+
+// Mock getSchemasFromResource
+vi.mock('@utils/collections/schemas', () => ({
+  getSchemasFromResource: vi.fn(),
+}));
+
+// Mock getItemsFromCollectionByIdAndSemverOrLatest
+vi.mock('@utils/collections/util', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@utils/collections/util')>()),
+  getItemsFromCollectionByIdAndSemverOrLatest: vi.fn((collection, id, version) => {
+    // Filter collection by id, and optionally by version
+    const matches = collection.filter((item: any) => item.data.id === id);
+    if (version) {
+      const exactMatch = matches.find((item: any) => item.data.version === version);
+      return exactMatch ? [exactMatch] : [];
+    }
+    // Return latest (highest version) if no version specified
+    return matches.length > 0 ? [matches[matches.length - 1]] : [];
+  }),
+}));
+
+// Mock getUbiquitousLanguageWithSubdomains
+vi.mock('@utils/collections/domains', () => ({
+  getUbiquitousLanguageWithSubdomains: vi.fn((domain) => {
+    // Return mock ubiquitous language data based on domain
+    if (domain.data.id === 'OrderDomain') {
+      return Promise.resolve({
+        domain: {
+          data: {
+            dictionary: [
+              { id: 'order', name: 'Order', summary: 'A request to purchase goods or services', icon: 'ShoppingCart' },
+              {
+                id: 'line-item',
+                name: 'Line Item',
+                summary: 'An individual product or service within an order',
+                icon: 'Package',
+              },
+              { id: 'customer', name: 'Customer', summary: 'A person or entity placing an order' },
+            ],
+          },
+        },
+        subdomains: [
+          {
+            subdomain: { data: { id: 'FulfillmentSubdomain', name: 'Fulfillment Subdomain' } },
+            ubiquitousLanguage: {
+              data: {
+                dictionary: [
+                  { id: 'shipment', name: 'Shipment', summary: 'A package sent to fulfill an order', icon: 'Truck' },
+                  { id: 'customer', name: 'Customer', summary: 'Duplicate term - recipient of a shipment' },
+                ],
+              },
+            },
+          },
+        ],
+        duplicateTerms: new Set(['customer']),
+      });
+    }
+    if (domain.data.id === 'EmptyDomain') {
+      return Promise.resolve({
+        domain: null,
+        subdomains: [],
+        duplicateTerms: new Set(),
+      });
+    }
+    return Promise.resolve({
+      domain: null,
+      subdomains: [],
+      duplicateTerms: new Set(),
+    });
+  }),
+}));
+
+// Mock fs for schema reading
+vi.mock('node:fs', () => ({
+  default: {
+    readFileSync: vi.fn(() => '{"schema": "content"}'),
+  },
+}));
+
+vi.mock('glob', () => ({
+  glob: vi.fn(async () => []),
+}));
+
+import {
+  encodeCursor,
+  decodeCursor,
+  paginate,
+  DEFAULT_PAGE_SIZE,
+  getResources,
+  getResource,
+  getMessagesProducedOrConsumedByResource,
+  getSchemaForResource,
+  findResourcesByOwner,
+  getProducersOfMessage,
+  getConsumersOfMessage,
+  analyzeChangeImpact,
+  explainBusinessFlow,
+  getArchitectureDiagramAsMermaid,
+  getTeams,
+  getTeam,
+  getUsers,
+  getUser,
+  findMessageBySchemaId,
+  explainUbiquitousLanguageTerms,
+  getC4Diagram,
+  getCustomDocs,
+  searchCustomDocs,
+  getCustomDoc,
+} from '../catalog-tools';
+import { getSchemasFromResource } from '@utils/collections/schemas';
+
+beforeEach(() => {
+  vi.mocked(glob).mockResolvedValue([]);
+  vi.mocked(fs.readFileSync).mockReturnValue('{"schema": "content"}');
+  delete process.env.PROJECT_DIR;
+});
+
+// ============================================
+// Pagination Utilities Tests
+// ============================================
+
+describe('Pagination Utilities', () => {
+  describe('encodeCursor / decodeCursor', () => {
+    it('encodes and decodes position correctly', () => {
+      const position = 50;
+      const cursor = encodeCursor(position);
+      expect(cursor).toBeTruthy();
+      expect(decodeCursor(cursor)).toBe(position);
+    });
+
+    it('handles position 0', () => {
+      const cursor = encodeCursor(0);
+      expect(decodeCursor(cursor)).toBe(0);
+    });
+
+    it('handles large positions', () => {
+      const position = 99999;
+      const cursor = encodeCursor(position);
+      expect(decodeCursor(cursor)).toBe(position);
+    });
+
+    it('returns null for invalid cursor', () => {
+      expect(decodeCursor('invalid-cursor')).toBe(null);
+    });
+
+    it('returns null for empty string cursor', () => {
+      // Empty string decodes to NaN
+      expect(decodeCursor('')).toBe(null);
+    });
+
+    it('returns null for cursor that decodes to negative number', () => {
+      // Manually encode a negative number
+      const negativeCursor = Buffer.from('-1').toString('base64url');
+      expect(decodeCursor(negativeCursor)).toBe(null);
+    });
+  });
+
+  describe('paginate', () => {
+    const items = Array.from({ length: 120 }, (_, i) => ({ id: i }));
+
+    it('returns first page of items when no cursor provided', () => {
+      const result = paginate(items);
+      expect('error' in result).toBe(false);
+      if (!('error' in result)) {
+        expect(result.items.length).toBe(DEFAULT_PAGE_SIZE);
+        expect(result.items[0]).toEqual({ id: 0 });
+        expect(result.totalCount).toBe(120);
+        expect(result.nextCursor).toBeTruthy();
+      }
+    });
+
+    it('returns error for invalid cursor', () => {
+      const result = paginate(items, 'invalid-cursor');
+      expect('error' in result).toBe(true);
+      if ('error' in result) {
+        expect(result.error).toContain('Invalid');
+      }
+    });
+
+    it('returns error when cursor exceeds MAX_CURSOR_POSITION', () => {
+      // MAX_CURSOR_POSITION is 100000
+      const cursor = encodeCursor(100001);
+      const result = paginate(items, cursor);
+      expect('error' in result).toBe(true);
+      if ('error' in result) {
+        expect(result.error).toContain('exceeds maximum');
+      }
+    });
+
+    it('returns nextCursor when more items available', () => {
+      const result = paginate(items);
+      expect('error' in result).toBe(false);
+      if (!('error' in result)) {
+        expect(result.nextCursor).toBeTruthy();
+      }
+    });
+
+    it('returns no nextCursor on last page', () => {
+      const cursor = encodeCursor(100); // Start at position 100, only 20 items left
+      const result = paginate(items, cursor);
+      expect('error' in result).toBe(false);
+      if (!('error' in result)) {
+        expect(result.items.length).toBe(20);
+        expect(result.nextCursor).toBeUndefined();
+      }
+    });
+
+    it('handles empty arrays', () => {
+      const result = paginate([]);
+      expect('error' in result).toBe(false);
+      if (!('error' in result)) {
+        expect(result.items).toEqual([]);
+        expect(result.totalCount).toBe(0);
+        expect(result.nextCursor).toBeUndefined();
+      }
+    });
+
+    it('respects custom pageSize', () => {
+      const result = paginate(items, undefined, 10);
+      expect('error' in result).toBe(false);
+      if (!('error' in result)) {
+        expect(result.items.length).toBe(10);
+      }
+    });
+
+    it('continues from cursor position correctly', () => {
+      const firstPage = paginate(items, undefined, 10);
+      expect('error' in firstPage).toBe(false);
+      if (!('error' in firstPage) && firstPage.nextCursor) {
+        const secondPage = paginate(items, firstPage.nextCursor, 10);
+        expect('error' in secondPage).toBe(false);
+        if (!('error' in secondPage)) {
+          expect(secondPage.items[0]).toEqual({ id: 10 });
+        }
+      }
+    });
+  });
+});
+
+// ============================================
+// Resource Access Tools Tests
+// ============================================
+
+describe('getResources', () => {
+  it.each(['events', 'agents', 'services', 'commands', 'queries', 'flows', 'domains', 'channels', 'entities'] as const)(
+    'returns paginated resources from %s collection',
+    async (collection) => {
+      const result = await getResources({ collection });
+      expect('error' in result).toBe(false);
+      if (!('error' in result)) {
+        expect(result.resources).toBeDefined();
+        expect(result.totalCount).toBeGreaterThanOrEqual(0);
+      }
+    }
+  );
+
+  it('returns empty resources for empty collection', async () => {
+    // diagrams has only 1 item in mocks, but let's test with an empty scenario
+    const result = await getResources({ collection: 'diagrams' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.totalCount).toBe(1); // Our mock has 1 diagram
+    }
+  });
+
+  it('supports pagination via cursor', async () => {
+    // Create a collection with enough items to paginate
+    const result = await getResources({ collection: 'events' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.resources.length).toBeLessThanOrEqual(DEFAULT_PAGE_SIZE);
+    }
+  });
+
+  it('returns totalCount', async () => {
+    const result = await getResources({ collection: 'events' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.totalCount).toBe(mockEvents.length);
+    }
+  });
+
+  it('returns resources with correct structure', async () => {
+    const result = await getResources({ collection: 'events' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.resources[0]).toHaveProperty('id');
+      expect(result.resources[0]).toHaveProperty('version');
+      expect(result.resources[0]).toHaveProperty('name');
+    }
+  });
+});
+
+describe('getResource', () => {
+  it('returns resource by id and version', async () => {
+    const result = await getResource({
+      collection: 'events',
+      id: 'OrderCreated',
+      version: '1.0.0',
+    });
+    expect(result).toBeDefined();
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.data.id).toBe('OrderCreated');
+      expect(result.data.version).toBe('1.0.0');
+    }
+  });
+
+  it('returns an agent resource by id and version', async () => {
+    const result = await getResource({
+      collection: 'agents',
+      id: 'FraudReviewAgent',
+      version: '1.0.0',
+    });
+    expect(result).toBeDefined();
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.data.id).toBe('FraudReviewAgent');
+      expect(result.data.model.provider).toBe('OpenAI');
+    }
+  });
+
+  it('returns error when resource not found', async () => {
+    const result = await getResource({
+      collection: 'events',
+      id: 'NonExistent',
+      version: '1.0.0',
+    });
+    expect('error' in result).toBe(true);
+    if ('error' in result) {
+      expect(result.error).toContain('not found');
+    }
+  });
+
+  it('returns error for wrong version', async () => {
+    const result = await getResource({
+      collection: 'events',
+      id: 'OrderCreated',
+      version: '99.0.0',
+    });
+    expect('error' in result).toBe(true);
+  });
+});
+
+describe('getArchitectureDiagramAsMermaid', () => {
+  it('returns a Mermaid diagram for systems', async () => {
+    const result = await getArchitectureDiagramAsMermaid({
+      resourceId: 'CoreSystem',
+      resourceVersion: '1.0.0',
+      resourceCollection: 'systems',
+    });
+
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.mermaidCode).toContain('flowchart LR');
+      expect(result.mermaidCode).toContain('Order Service');
+    }
+  });
+});
+
+describe('getMessagesProducedOrConsumedByResource', () => {
+  it('returns resource with sends and receives properties', async () => {
+    const result = await getMessagesProducedOrConsumedByResource({
+      resourceId: 'OrderService',
+      resourceVersion: '1.0.0',
+      resourceCollection: 'services',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.data.sends).toBeDefined();
+      expect(result.data.receives).toBeDefined();
+    }
+  });
+
+  it('returns an agent resource with sends and receives properties', async () => {
+    const result = await getMessagesProducedOrConsumedByResource({
+      resourceId: 'FraudReviewAgent',
+      resourceVersion: '1.0.0',
+      resourceCollection: 'agents',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.data.sends).toBeDefined();
+      expect(result.data.receives).toBeDefined();
+    }
+  });
+
+  it('returns error when resource not found', async () => {
+    const result = await getMessagesProducedOrConsumedByResource({
+      resourceId: 'NonExistent',
+      resourceVersion: '1.0.0',
+      resourceCollection: 'services',
+    });
+    expect('error' in result).toBe(true);
+  });
+});
+
+// ============================================
+// Message Analysis Tools Tests
+// ============================================
+
+describe('getProducersOfMessage', () => {
+  it('finds services that send exact version', async () => {
+    const result = await getProducersOfMessage({
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.producers.length).toBeGreaterThan(0);
+      expect(result.producers.some((p: ProducerConsumer) => p.id === 'OrderService')).toBe(true);
+    }
+  });
+
+  it('finds services with version: latest', async () => {
+    const result = await getProducersOfMessage({
+      messageId: 'PaymentProcessed',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      // PaymentService sends PaymentProcessed with version: 'latest'
+      expect(result.producers.some((p: ProducerConsumer) => p.id === 'PaymentService')).toBe(true);
+    }
+  });
+
+  it('finds services with no version specified (matches all)', async () => {
+    // PaymentService receives OrderCreated without version specified
+    const result = await getConsumersOfMessage({
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.consumers.some((c: ProducerConsumer) => c.id === 'PaymentService')).toBe(true);
+    }
+  });
+
+  it('returns correct count', async () => {
+    const result = await getProducersOfMessage({
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.count).toBe(result.producers.length);
+    }
+  });
+
+  it('finds agents that send messages', async () => {
+    const result = await getProducersOfMessage({
+      messageId: 'InventoryUpdated',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(
+        result.producers.some(
+          (p: ProducerConsumer & { collection?: string }) => p.id === 'FraudReviewAgent' && p.collection === 'agents'
+        )
+      ).toBe(true);
+    }
+  });
+
+  it('returns error when message not found', async () => {
+    const result = await getProducersOfMessage({
+      messageId: 'NonExistent',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(true);
+    if ('error' in result) {
+      expect(result.error).toContain('not found');
+    }
+  });
+
+  it('returns message details in response', async () => {
+    const result = await getProducersOfMessage({
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.message.id).toBe('OrderCreated');
+      expect(result.message.version).toBe('1.0.0');
+      expect(result.message.collection).toBe('events');
+    }
+  });
+});
+
+describe('getConsumersOfMessage', () => {
+  it('finds services that receive exact version', async () => {
+    const result = await getConsumersOfMessage({
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.consumers.some((c: ProducerConsumer) => c.id === 'InventoryService')).toBe(true);
+    }
+  });
+
+  it('finds services with no version specified', async () => {
+    const result = await getConsumersOfMessage({
+      messageId: 'OrderCreated',
+      messageVersion: '2.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      // PaymentService receives OrderCreated without version (matches any)
+      expect(result.consumers.some((c: ProducerConsumer) => c.id === 'PaymentService')).toBe(true);
+      // NotificationService receives OrderCreated version 2.0.0
+      expect(result.consumers.some((c: ProducerConsumer) => c.id === 'NotificationService')).toBe(true);
+    }
+  });
+
+  it('finds agents that receive messages', async () => {
+    const result = await getConsumersOfMessage({
+      messageId: 'PaymentProcessed',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(
+        result.consumers.some(
+          (c: ProducerConsumer & { collection?: string }) => c.id === 'FraudReviewAgent' && c.collection === 'agents'
+        )
+      ).toBe(true);
+    }
+  });
+
+  it('returns error when message not found', async () => {
+    const result = await getConsumersOfMessage({
+      messageId: 'NonExistent',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(true);
+  });
+});
+
+describe('getC4Diagram', () => {
+  const projectRoot = '/catalog';
+  const sourceFiles = ['architecture/model.c4', 'architecture/views.c4', 'payments/model.c4', 'payments/views.c4'];
+  const fileContents: Record<string, string> = {
+    '/catalog/architecture/model.c4': `specification {
+  element actor
+  element system
+}
+
+model {
+  customer = actor 'Customer'
+  ordering = system 'Ordering service'
+}`,
+    '/catalog/architecture/views.c4': `views {
+  view OrderFlow {
+    include *
+  }
+
+  dynamic view Checkout {
+    customer -> ordering 'places order'
+  }
+}`,
+    '/catalog/payments/model.c4': `model {
+  payment = system 'Payment service'
+}`,
+    '/catalog/payments/views.c4': `views {
+  deployment view PaymentsOverview {
+    include *
+  }
+}`,
+  };
+
+  beforeEach(() => {
+    process.env.PROJECT_DIR = projectRoot;
+    vi.mocked(glob).mockImplementation(async (pattern) => {
+      if (pattern === '**/*.{c4,likec4}') {
+        return sourceFiles;
+      }
+
+      return [];
+    });
+    vi.mocked(fs.readFileSync).mockImplementation((filePath) => fileContents[String(filePath)] ?? '');
+  });
+
+  it('returns all LikeC4 source files when no viewId is provided', async () => {
+    const result = await getC4Diagram({});
+
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.totalSourceFiles).toBe(4);
+      expect(result.totalViews).toBe(3);
+      expect(result.sources.map((source: any) => source.path)).toEqual([
+        'architecture/model.c4',
+        'architecture/views.c4',
+        'payments/model.c4',
+        'payments/views.c4',
+      ]);
+      expect(result.sources[0].content).toContain("customer = actor 'Customer'");
+      expect(result.sources[1].views.map((view: any) => view.id)).toEqual(['OrderFlow', 'Checkout']);
+    }
+  });
+
+  it('returns all source files and the matching view when viewId is provided', async () => {
+    const result = await getC4Diagram({ viewId: 'OrderFlow' });
+
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect((result as any).matchingViews[0]).toMatchObject({
+        id: 'OrderFlow',
+        kind: 'element',
+        filePath: 'architecture/views.c4',
+      });
+      expect(result.sources.map((source: any) => source.path)).toEqual([
+        'architecture/model.c4',
+        'architecture/views.c4',
+        'payments/model.c4',
+        'payments/views.c4',
+      ]);
+      expect(result.sources[0].content).toContain("customer = actor 'Customer'");
+    }
+  });
+
+  it('returns sources for another matching view', async () => {
+    const result = await getC4Diagram({ viewId: 'PaymentsOverview' });
+
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect((result as any).matchingViews[0]).toMatchObject({
+        id: 'PaymentsOverview',
+        kind: 'deployment',
+      });
+    }
+  });
+
+  it('returns available views when the requested view cannot be found', async () => {
+    const result = await getC4Diagram({ viewId: 'MissingView' });
+
+    expect('error' in result).toBe(true);
+    if ('error' in result) {
+      expect(result.error).toContain('MissingView');
+      expect((result as any).availableViews.map((view: any) => view.id)).toContain('OrderFlow');
+    }
+  });
+
+  it('returns an empty result when no LikeC4 source files are found', async () => {
+    vi.mocked(glob).mockResolvedValue([]);
+
+    const result = await getC4Diagram({});
+
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.totalSourceFiles).toBe(0);
+      expect(result.sources).toEqual([]);
+    }
+  });
+});
+
+describe('analyzeChangeImpact', () => {
+  it('returns producers and consumers counts', async () => {
+    const result = await analyzeChangeImpact({
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.impact.producerCount).toBeGreaterThanOrEqual(0);
+      expect(result.impact.consumerCount).toBeGreaterThanOrEqual(0);
+      expect(result.impact.totalResourcesAffected).toBeGreaterThanOrEqual(0);
+      expect(result.impact.totalServicesAffected).toBeGreaterThanOrEqual(0);
+      expect(result.impact.totalAgentsAffected).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it('collects affected owners from string format', async () => {
+    const result = await analyzeChangeImpact({
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.impact.teamsAffected).toContain('order-team');
+    }
+  });
+
+  it('collects affected owners from object format', async () => {
+    const result = await analyzeChangeImpact({
+      messageId: 'InventoryUpdated',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.impact.teamsAffected).toContain('inventory-team');
+    }
+  });
+
+  it('includes message owners in affected teams', async () => {
+    const result = await analyzeChangeImpact({
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      // OrderCreated is owned by 'order-team' and { id: 'user-jane' }
+      expect(result.impact.teamsAffected).toContain('order-team');
+      expect(result.impact.teamsAffected).toContain('user-jane');
+    }
+  });
+
+  it('returns message details', async () => {
+    const result = await analyzeChangeImpact({
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.message.id).toBe('OrderCreated');
+      expect(result.message.name).toBe('Order Created');
+    }
+  });
+
+  it('includes affected agents', async () => {
+    const result = await analyzeChangeImpact({
+      messageId: 'PaymentProcessed',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.impact.totalAgentsAffected).toBeGreaterThan(0);
+      expect(
+        result.consumers.some(
+          (c: ProducerConsumer & { collection?: string }) => c.id === 'FraudReviewAgent' && c.collection === 'agents'
+        )
+      ).toBe(true);
+    }
+  });
+
+  it('returns error when message not found', async () => {
+    const result = await analyzeChangeImpact({
+      messageId: 'NonExistent',
+      messageVersion: '1.0.0',
+      messageCollection: 'events',
+    });
+    expect('error' in result).toBe(true);
+  });
+});
+
+// ============================================
+// Lookup Tools Tests
+// ============================================
+
+describe('findResourcesByOwner', () => {
+  it('finds resources across all collections by string owner', async () => {
+    const result = await findResourcesByOwner({ ownerId: 'order-team' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.totalCount).toBeGreaterThan(0);
+      expect(result.resources.some((r: ResourceResult) => r.collection === 'events')).toBe(true);
+      expect(result.resources.some((r: ResourceResult) => r.collection === 'services')).toBe(true);
+      expect(result.resources.some((r: ResourceResult) => r.collection === 'adrs')).toBe(true);
+      expect(result.resources.some((r: ResourceResult) => r.collection === 'containers')).toBe(true);
+      expect(result.resources.some((r: ResourceResult) => r.collection === 'diagrams')).toBe(true);
+    }
+  });
+
+  it('finds agents owned by a team or user', async () => {
+    const result = await findResourcesByOwner({ ownerId: 'risk-team' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.resources.some((r: ResourceResult) => r.collection === 'agents' && r.id === 'FraudReviewAgent')).toBe(true);
+    }
+  });
+
+  it('handles object owner format', async () => {
+    // InventoryService has owner { id: 'inventory-team' }
+    const result = await findResourcesByOwner({ ownerId: 'inventory-team' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.totalCount).toBeGreaterThan(0);
+      expect(result.resources.some((r: ResourceResult) => r.id === 'InventoryService')).toBe(true);
+    }
+  });
+
+  it('returns message when no resources found', async () => {
+    const result = await findResourcesByOwner({ ownerId: 'non-existent-team' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.message).toContain('No resources found');
+      expect(result.resources).toEqual([]);
+    }
+  });
+
+  it('returns resources with correct structure', async () => {
+    const result = await findResourcesByOwner({ ownerId: 'order-team' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result) && result.resources.length > 0) {
+      expect(result.resources[0]).toHaveProperty('collection');
+      expect(result.resources[0]).toHaveProperty('id');
+      expect(result.resources[0]).toHaveProperty('name');
+    }
+  });
+});
+
+describe('findMessageBySchemaId', () => {
+  it('finds message in specified collection', async () => {
+    const result = await findMessageBySchemaId({
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      collection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.resource.id).toBe('OrderCreated');
+      expect(result.resource.collection).toBe('events');
+    }
+  });
+
+  it('searches all message collections when none specified', async () => {
+    const result = await findMessageBySchemaId({
+      messageId: 'CreateOrder',
+      messageVersion: '1.0.0',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.resource.id).toBe('CreateOrder');
+      expect(result.resource.collection).toBe('commands');
+    }
+  });
+
+  it('returns latest version when no version specified', async () => {
+    const result = await findMessageBySchemaId({
+      messageId: 'OrderCreated',
+      // No version - should return latest
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.resource.id).toBe('OrderCreated');
+      // Latest version is 2.0.0 in our mocks
+      expect(result.resource.version).toBe('2.0.0');
+    }
+  });
+
+  it('includes producers and consumers', async () => {
+    const result = await findMessageBySchemaId({
+      messageId: 'OrderCreated',
+      messageVersion: '1.0.0',
+      collection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.producers).toBeDefined();
+      expect(result.consumers).toBeDefined();
+      expect(Array.isArray(result.producers)).toBe(true);
+      expect(Array.isArray(result.consumers)).toBe(true);
+    }
+  });
+
+  it('includes agents in message producer and consumer lookups', async () => {
+    const result = await findMessageBySchemaId({
+      messageId: 'PaymentProcessed',
+      messageVersion: '1.0.0',
+      collection: 'events',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(
+        result.consumers.some(
+          (c: ProducerConsumer & { collection?: string }) => c.id === 'FraudReviewAgent' && c.collection === 'agents'
+        )
+      ).toBe(true);
+    }
+  });
+
+  it('returns error when message not found', async () => {
+    const result = await findMessageBySchemaId({
+      messageId: 'NonExistent',
+    });
+    expect('error' in result).toBe(true);
+    if ('error' in result) {
+      expect(result.error).toContain('not found');
+    }
+  });
+});
+
+describe('getSchemaForResource', () => {
+  beforeEach(() => {
+    vi.mocked(getSchemasFromResource).mockReset();
+  });
+
+  it('returns message schemas from the generated schemas collection', async () => {
+    const result = await getSchemaForResource({
+      resourceId: 'OrderCreated',
+      resourceVersion: '1.0.0',
+      resourceCollection: 'events',
+    });
+
+    expect(result).toEqual([
+      {
+        id: 'file://schemas/OrderCreated.schema.json',
+        name: 'OrderCreated.schema.json',
+        ref: 'file://schemas/OrderCreated.schema.json',
+        format: 'jsonschema',
+        source: {
+          provider: 'file',
+          path: 'schemas/OrderCreated.schema.json',
+        },
+        code: '{"type":"object","title":"OrderCreated"}',
+      },
+    ]);
+    expect(getSchemasFromResource).not.toHaveBeenCalled();
+  });
+
+  it('falls back to legacy resource schema files when no generated schema entry exists', async () => {
+    vi.mocked(getSchemasFromResource).mockResolvedValue([{ url: '/path/to/schema.json', format: 'json-schema' }]);
+
+    const result = await getSchemaForResource({
+      resourceId: 'PaymentProcessed',
+      resourceVersion: '1.0.0',
+      resourceCollection: 'events',
+    });
+    expect(Array.isArray(result)).toBe(true);
+    if (Array.isArray(result)) {
+      expect(result[0]).toHaveProperty('url');
+      expect(result[0]).toHaveProperty('format');
+      expect(result[0]).toHaveProperty('code');
+    }
+  });
+
+  it('returns message when no schema found', async () => {
+    vi.mocked(getSchemasFromResource).mockResolvedValue([]);
+
+    const result = await getSchemaForResource({
+      resourceId: 'PaymentProcessed',
+      resourceVersion: '1.0.0',
+      resourceCollection: 'events',
+    });
+    expect('message' in result).toBe(true);
+    if ('message' in result) {
+      expect(result.message).toContain('No schemas found');
+    }
+  });
+
+  it('returns error when resource not found', async () => {
+    const result = await getSchemaForResource({
+      resourceId: 'NonExistent',
+      resourceVersion: '1.0.0',
+      resourceCollection: 'events',
+    });
+    expect('error' in result).toBe(true);
+  });
+});
+
+// ============================================
+// Flow Tools Tests
+// ============================================
+
+describe('explainBusinessFlow', () => {
+  it('returns flow with steps and mermaid', async () => {
+    const result = await explainBusinessFlow({
+      flowId: 'OrderFlow',
+      flowVersion: '1.0.0',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.flow.id).toBe('OrderFlow');
+      expect(result.flow.steps).toBeDefined();
+      expect(Array.isArray(result.flow.steps)).toBe(true);
+      expect(result.flow.mermaid).toBeDefined();
+    }
+  });
+
+  it('includes related services', async () => {
+    const result = await explainBusinessFlow({
+      flowId: 'OrderFlow',
+      flowVersion: '1.0.0',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.relatedServices).toBeDefined();
+      expect(Array.isArray(result.relatedServices)).toBe(true);
+      // OrderService has flows: [{ id: 'OrderFlow' }]
+      expect(result.relatedServices.some((s: ProducerConsumer) => s.id === 'OrderService')).toBe(true);
+    }
+  });
+
+  it('includes related agents', async () => {
+    const result = await explainBusinessFlow({
+      flowId: 'OrderFlow',
+      flowVersion: '1.0.0',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.relatedAgents).toBeDefined();
+      expect(Array.isArray(result.relatedAgents)).toBe(true);
+      expect(result.relatedAgents.some((a: ProducerConsumer) => a.id === 'FraudReviewAgent')).toBe(true);
+    }
+  });
+
+  it('returns body content', async () => {
+    const result = await explainBusinessFlow({
+      flowId: 'OrderFlow',
+      flowVersion: '1.0.0',
+    });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.content).toBeDefined();
+      expect(result.content).toContain('Order Processing Flow');
+    }
+  });
+
+  it('returns error when flow not found', async () => {
+    const result = await explainBusinessFlow({
+      flowId: 'NonExistent',
+      flowVersion: '1.0.0',
+    });
+    expect('error' in result).toBe(true);
+    if ('error' in result) {
+      expect(result.error).toContain('not found');
+    }
+  });
+});
+
+// ============================================
+// Team and User Tools Tests
+// ============================================
+
+describe('getTeams', () => {
+  it('returns paginated teams', async () => {
+    const result = await getTeams({});
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.teams).toBeDefined();
+      expect(Array.isArray(result.teams)).toBe(true);
+      expect(result.totalCount).toBe(mockTeams.length);
+    }
+  });
+
+  it('returns teams with correct structure', async () => {
+    const result = await getTeams({});
+    expect('error' in result).toBe(false);
+    if (!('error' in result) && result.teams.length > 0) {
+      expect(result.teams[0]).toHaveProperty('id');
+      expect(result.teams[0]).toHaveProperty('name');
+      expect(result.teams[0]).toHaveProperty('members');
+    }
+  });
+
+  it('supports cursor-based pagination', async () => {
+    const result = await getTeams({ cursor: encodeCursor(1) });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.teams[0].id).toBe('payment-team');
+    }
+  });
+});
+
+describe('getTeam', () => {
+  it('returns team by id with members', async () => {
+    const result = await getTeam({ id: 'order-team' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.id).toBe('order-team');
+      expect(result.name).toBe('Order Team');
+      expect(result.members).toContain('user-jane');
+      expect(result.members).toContain('user-john');
+    }
+  });
+
+  it('returns team content (markdown body)', async () => {
+    const result = await getTeam({ id: 'order-team' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.content).toBeDefined();
+    }
+  });
+
+  it('returns error when team not found', async () => {
+    const result = await getTeam({ id: 'non-existent-team' });
+    expect('error' in result).toBe(true);
+    if ('error' in result) {
+      expect(result.error).toContain('not found');
+    }
+  });
+});
+
+describe('getUsers', () => {
+  it('returns paginated users', async () => {
+    const result = await getUsers({});
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.users).toBeDefined();
+      expect(Array.isArray(result.users)).toBe(true);
+      expect(result.totalCount).toBe(mockUsers.length);
+    }
+  });
+
+  it('returns users with correct structure', async () => {
+    const result = await getUsers({});
+    expect('error' in result).toBe(false);
+    if (!('error' in result) && result.users.length > 0) {
+      expect(result.users[0]).toHaveProperty('id');
+      expect(result.users[0]).toHaveProperty('name');
+      expect(result.users[0]).toHaveProperty('email');
+      expect(result.users[0]).toHaveProperty('role');
+    }
+  });
+});
+
+describe('getUser', () => {
+  it('returns user by id', async () => {
+    const result = await getUser({ id: 'user-jane' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.id).toBe('user-jane');
+      expect(result.name).toBe('Jane Doe');
+      expect(result.email).toBe('jane@company.com');
+      expect(result.role).toBe('Lead Engineer');
+    }
+  });
+
+  it('returns user content (markdown body)', async () => {
+    const result = await getUser({ id: 'user-jane' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.content).toBeDefined();
+    }
+  });
+
+  it('returns error when user not found', async () => {
+    const result = await getUser({ id: 'non-existent-user' });
+    expect('error' in result).toBe(true);
+    if ('error' in result) {
+      expect(result.error).toContain('not found');
+    }
+  });
+});
+
+// ============================================
+// Search Filter Tests
+// ============================================
+
+describe('getResources with search filter', () => {
+  it('filters resources by name', async () => {
+    const result = await getResources({ collection: 'events', search: 'Order' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      // Should match OrderCreated events (both versions)
+      expect(result.resources.length).toBeGreaterThan(0);
+      expect(
+        result.resources.every((r: any) => r.name?.toLowerCase().includes('order') || r.id?.toLowerCase().includes('order'))
+      ).toBe(true);
+    }
+  });
+
+  it('filters resources by id', async () => {
+    const result = await getResources({ collection: 'events', search: 'Payment' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.resources.length).toBeGreaterThan(0);
+      expect(result.resources.some((r: any) => r.id === 'PaymentProcessed')).toBe(true);
+    }
+  });
+
+  it('filters resources by summary', async () => {
+    const result = await getResources({ collection: 'events', search: 'inventory' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.resources.length).toBeGreaterThan(0);
+      expect(result.resources.some((r: any) => r.id === 'InventoryUpdated')).toBe(true);
+    }
+  });
+
+  it('returns empty when no match found', async () => {
+    const result = await getResources({ collection: 'events', search: 'nonexistent' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.resources.length).toBe(0);
+      expect(result.totalCount).toBe(0);
+    }
+  });
+
+  it('is case-insensitive', async () => {
+    const resultLower = await getResources({ collection: 'events', search: 'order' });
+    const resultUpper = await getResources({ collection: 'events', search: 'ORDER' });
+    expect('error' in resultLower).toBe(false);
+    expect('error' in resultUpper).toBe(false);
+    if (!('error' in resultLower) && !('error' in resultUpper)) {
+      expect(resultLower.totalCount).toBe(resultUpper.totalCount);
+    }
+  });
+
+  it('returns all resources when search is empty', async () => {
+    const resultWithSearch = await getResources({ collection: 'events', search: '' });
+    const resultWithoutSearch = await getResources({ collection: 'events' });
+    expect('error' in resultWithSearch).toBe(false);
+    expect('error' in resultWithoutSearch).toBe(false);
+    if (!('error' in resultWithSearch) && !('error' in resultWithoutSearch)) {
+      expect(resultWithSearch.totalCount).toBe(resultWithoutSearch.totalCount);
+    }
+  });
+
+  it('includes summary in returned resources', async () => {
+    const result = await getResources({ collection: 'events' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result) && result.resources.length > 0) {
+      expect(result.resources[0]).toHaveProperty('summary');
+    }
+  });
+});
+
+// ============================================
+// Ubiquitous Language Tests
+// ============================================
+
+describe('explainUbiquitousLanguageTerms', () => {
+  it('returns terms for a domain with ubiquitous language', async () => {
+    const result = await explainUbiquitousLanguageTerms({ domainId: 'OrderDomain' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.domainId).toBe('OrderDomain');
+      expect(result.terms.length).toBeGreaterThan(0);
+      expect(result.totalCount).toBeGreaterThan(0);
+    }
+  });
+
+  it('includes domain terms', async () => {
+    const result = await explainUbiquitousLanguageTerms({ domainId: 'OrderDomain' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.domainTermCount).toBe(3);
+      expect(result.terms.some((t: any) => t.term === 'Order')).toBe(true);
+      expect(result.terms.some((t: any) => t.term === 'Line Item')).toBe(true);
+    }
+  });
+
+  it('includes subdomain terms', async () => {
+    const result = await explainUbiquitousLanguageTerms({ domainId: 'OrderDomain' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.subdomainTermCount).toBe(2);
+      expect(result.terms.some((t: any) => t.term === 'Shipment' && t.isSubdomain === true)).toBe(true);
+    }
+  });
+
+  it('detects duplicate terms', async () => {
+    const result = await explainUbiquitousLanguageTerms({ domainId: 'OrderDomain' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.duplicateTerms).toContain('customer');
+      expect(result.terms.filter((t: any) => t.term === 'Customer' && t.isDuplicate === true).length).toBe(2);
+    }
+  });
+
+  it('includes term metadata (icon, description)', async () => {
+    const result = await explainUbiquitousLanguageTerms({ domainId: 'OrderDomain' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      const orderTerm = result.terms.find((t: any) => t.term === 'Order');
+      expect(orderTerm).toBeDefined();
+      expect(orderTerm?.description).toBeDefined();
+      expect(orderTerm?.icon).toBe('ShoppingCart');
+    }
+  });
+
+  it('returns message when no terms defined', async () => {
+    const result = await explainUbiquitousLanguageTerms({ domainId: 'EmptyDomain' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.message).toContain('No ubiquitous language terms');
+      expect(result.terms.length).toBe(0);
+    }
+  });
+
+  it('returns error when domain not found', async () => {
+    const result = await explainUbiquitousLanguageTerms({ domainId: 'NonExistent' });
+    expect('error' in result).toBe(true);
+    if ('error' in result) {
+      expect(result.error).toContain('not found');
+    }
+  });
+
+  it('returns subdomain count', async () => {
+    const result = await explainUbiquitousLanguageTerms({ domainId: 'OrderDomain' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.subdomainCount).toBe(1);
+    }
+  });
+});
+
+// ============================================
+// Custom Documentation Tools Tests
+// ============================================
+
+describe('getCustomDocs', () => {
+  it('returns all custom docs with metadata but no body', async () => {
+    const result = await getCustomDocs({});
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.totalCount).toBe(2);
+      expect(result.docs[0]).toEqual({
+        id: 'docs/payments/runbook',
+        title: 'Payment Runbook',
+        summary: 'How we operate payments',
+      });
+      expect(result.docs[1]).toEqual({
+        id: 'docs/onboarding',
+        title: 'Onboarding Guide',
+        summary: 'Getting started as a new engineer',
+        slug: 'getting-started',
+      });
+    }
+  });
+
+  it('filters docs with the search param (title, id, summary)', async () => {
+    const result = await getCustomDocs({ search: 'onboarding' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.totalCount).toBe(1);
+      expect(result.docs[0].id).toBe('docs/onboarding');
+    }
+  });
+
+  it('returns no nextCursor when all docs fit on one page', async () => {
+    const result = await getCustomDocs({});
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.nextCursor).toBeUndefined();
+    }
+  });
+});
+
+describe('searchCustomDocs', () => {
+  it('finds docs by body content and returns the matched section with a snippet', async () => {
+    const result = await searchCustomDocs({ query: 'refund fails' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.results.length).toBeGreaterThan(0);
+      expect(result.results[0].docId).toBe('docs/payments/runbook');
+      expect(result.results[0].heading).toBe('Refund failures');
+      expect(result.results[0].snippet.toLowerCase()).toContain('refund');
+    }
+  });
+
+  it('returns empty results when nothing matches', async () => {
+    const result = await searchCustomDocs({ query: 'zzzzz-nonexistent' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.results).toEqual([]);
+    }
+  });
+
+  it('returns an error for an empty query', async () => {
+    const result = await searchCustomDocs({ query: '   ' });
+    expect('error' in result).toBe(true);
+  });
+});
+
+describe('getCustomDoc', () => {
+  it('returns the full markdown and metadata for a doc by id', async () => {
+    const result = await getCustomDoc({ id: 'docs/payments/runbook' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.title).toBe('Payment Runbook');
+      expect(result.markdown).toContain('## Refund failures');
+      expect(result.markdown).toContain('acquirer portal');
+    }
+  });
+
+  it('resolves a doc by its custom slug', async () => {
+    const result = await getCustomDoc({ id: 'getting-started' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.title).toBe('Onboarding Guide');
+    }
+  });
+
+  it('returns only the requested section when a section is provided', async () => {
+    const result = await getCustomDoc({ id: 'docs/payments/runbook', section: 'Chargeback handling' });
+    expect('error' in result).toBe(false);
+    if (!('error' in result)) {
+      expect(result.markdown).toContain('acquirer portal');
+      expect(result.markdown).not.toContain('Refund failures');
+    }
+  });
+
+  it('returns an error listing available sections when the section is not found', async () => {
+    const result = await getCustomDoc({ id: 'docs/payments/runbook', section: 'Nope' });
+    expect('error' in result).toBe(true);
+    if ('error' in result) {
+      expect(result.error).toContain('Chargeback handling');
+    }
+  });
+
+  it('returns an error when the doc is not found', async () => {
+    const result = await getCustomDoc({ id: 'docs/does-not-exist' });
+    expect('error' in result).toBe(true);
+  });
+});
diff --git a/packages/core/eventcatalog/src/enterprise/tools/catalog-tools.ts b/packages/core/eventcatalog/src/enterprise/tools/catalog-tools.ts
new file mode 100644
index 000000000..9caff0d6c
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/tools/catalog-tools.ts
@@ -0,0 +1,1271 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+/**
+ * Shared catalog tools for accessing EventCatalog resources.
+ * Used by both the AI Chat feature and MCP Server.
+ */
+import { getCollection, getEntry } from 'astro:content';
+import { z } from 'zod';
+import { getSchemasFromResource, getSchemaFormatFromURL } from '@utils/collections/schemas';
+import { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
+import { getUbiquitousLanguageWithSubdomains } from '@utils/collections/domains';
+import { getAbsoluteFilePathForAstroFile } from '@utils/files';
+import fs from 'node:fs';
+import { getNodesAndEdges as getNodesAndEdgesForService } from '@utils/node-graphs/services-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForAgent } from '@utils/node-graphs/agents-node-graph';
+import {
+  getNodesAndEdgesForCommands,
+  getNodesAndEdgesForEvents,
+  getNodesAndEdgesForQueries,
+} from '@utils/node-graphs/message-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForDomain } from '@utils/node-graphs/domains-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForFlows } from '@utils/node-graphs/flows-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForDataProduct } from '@utils/node-graphs/data-products-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForContainer } from '@utils/node-graphs/container-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForSystem } from '@utils/node-graphs/systems-node-graph';
+import { convertToMermaid } from '@utils/node-graphs/export-mermaid';
+import config from '@config';
+import { glob } from 'glob';
+import path from 'node:path';
+import {
+  buildDocsSearchIndex,
+  chunkMarkdownByHeadings,
+  type DocsSearchIndex,
+} from '@enterprise/custom-documentation/utils/docs-search';
+
+const MESSAGE_COLLECTIONS = new Set(['events', 'commands', 'queries']);
+const LIKEC4_SOURCE_PATTERN = '**/*.{c4,likec4}';
+
+type LikeC4View = {
+  id: string;
+  kind: 'element' | 'dynamic' | 'deployment';
+  filePath: string;
+  line: number;
+};
+
+type LikeC4SourceFile = {
+  path: string;
+  content: string;
+  views: LikeC4View[];
+};
+
+const toPosixPath = (filePath: string) => filePath.split(path.sep).join(path.posix.sep);
+
+const lineNumberAtIndex = (content: string, index: number) => content.slice(0, index).split(/\r\n|\r|\n/).length;
+
+const stripLikeC4Comments = (content: string) => content.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+
+const parseLikeC4Views = (content: string, filePath: string): LikeC4View[] => {
+  const contentWithoutComments = stripLikeC4Comments(content);
+  const viewDeclarationPattern =
+    /\b(?:(dynamic|deployment)\s+)?view(?:\s+([A-Za-z_][\w.-]*))?(?:\s+of\s+[A-Za-z_][\w.-]*(?:\.[A-Za-z_][\w.-]*)*)?\s*\{/g;
+  const views: LikeC4View[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = viewDeclarationPattern.exec(contentWithoutComments)) !== null) {
+    const [, kind, id] = match;
+
+    if (!id) {
+      continue;
+    }
+
+    views.push({
+      id,
+      kind: kind === 'dynamic' || kind === 'deployment' ? kind : 'element',
+      filePath,
+      line: lineNumberAtIndex(contentWithoutComments, match.index),
+    });
+  }
+
+  return views;
+};
+
+const discoverLikeC4Sources = async (projectRoot: string): Promise<LikeC4SourceFile[]> => {
+  const sourceFiles = await glob(LIKEC4_SOURCE_PATTERN, {
+    cwd: projectRoot,
+    ignore: ['**/node_modules/**'],
+    nodir: true,
+  });
+
+  return sourceFiles
+    .map(toPosixPath)
+    .sort()
+    .map((sourceFile) => {
+      const content = fs.readFileSync(path.join(projectRoot, sourceFile), 'utf-8');
+      return {
+        path: sourceFile,
+        content,
+        views: parseLikeC4Views(content, sourceFile),
+      };
+    });
+};
+
+// ============================================
+// Pagination utilities
+// ============================================
+
+export const DEFAULT_PAGE_SIZE = 50;
+
+/**
+ * Encode position to opaque cursor string.
+ * Uses base64url for URL-safe encoding.
+ */
+export function encodeCursor(position: number): string {
+  return Buffer.from(String(position)).toString('base64url');
+}
+
+/**
+ * Decode cursor string to position.
+ * Returns null if cursor is invalid.
+ */
+export function decodeCursor(cursor: string): number | null {
+  try {
+    const decoded = Buffer.from(cursor, 'base64url').toString('utf8');
+    const position = parseInt(decoded, 10);
+    return isNaN(position) || position < 0 ? null : position;
+  } catch {
+    return null;
+  }
+}
+
+// Maximum cursor position to prevent abuse
+const MAX_CURSOR_POSITION = 100000;
+
+/**
+ * Generic pagination helper for any array of items
+ */
+export function paginate<T>(
+  items: T[],
+  cursor?: string,
+  pageSize: number = DEFAULT_PAGE_SIZE
+): { items: T[]; nextCursor?: string; totalCount: number } | { error: string } {
+  let startIndex = 0;
+
+  if (cursor) {
+    const decoded = decodeCursor(cursor);
+    if (decoded === null) {
+      return { error: 'Invalid or malformed cursor' };
+    }
+    if (decoded > MAX_CURSOR_POSITION) {
+      return { error: 'Cursor position exceeds maximum allowed value' };
+    }
+    startIndex = decoded;
+  }
+
+  const endIndex = startIndex + pageSize;
+  const paginatedItems = items.slice(startIndex, endIndex);
+  const hasMore = endIndex < items.length;
+
+  const result: { items: T[]; nextCursor?: string; totalCount: number } = {
+    items: paginatedItems,
+    totalCount: items.length,
+  };
+
+  if (hasMore) {
+    result.nextCursor = encodeCursor(endIndex);
+  }
+
+  return result;
+}
+
+// ============================================
+// Shared schemas for tool inputs
+// ============================================
+
+export const collectionSchema = z.enum([
+  'events',
+  'agents',
+  'adrs',
+  'services',
+  'commands',
+  'queries',
+  'flows',
+  'domains',
+  'systems',
+  'channels',
+  'entities',
+  'containers',
+  'diagrams',
+  'data-products',
+]);
+
+export const messageCollectionSchema = z.enum(['events', 'commands', 'queries']);
+
+export const resourceCollectionSchema = z.enum([
+  'agents',
+  'services',
+  'adrs',
+  'events',
+  'commands',
+  'queries',
+  'flows',
+  'domains',
+  'systems',
+  'channels',
+  'entities',
+  'data-products',
+]);
+
+export const visualiserCollectionSchema = z.enum([
+  'events',
+  'commands',
+  'queries',
+  'agents',
+  'services',
+  'domains',
+  'systems',
+  'flows',
+  'containers',
+  'data-products',
+]);
+
+// ============================================
+// Tool implementations (core logic)
+// ============================================
+
+/**
+ * Get resources from a collection with optional pagination and search
+ */
+export async function getResources(params: { collection: string; cursor?: string; search?: string }) {
+  const resources = await getCollection(params.collection as any);
+  let allResults = resources.map((resource: any) => ({
+    id: resource.data.id,
+    version: resource.data.version,
+    name: resource.data.name,
+    summary: resource.data.summary,
+  }));
+
+  // Apply search filter if provided
+  if (params.search) {
+    const searchTerm = params.search.toLowerCase().trim();
+    allResults = allResults.filter(
+      (resource) =>
+        resource.id?.toLowerCase().includes(searchTerm) ||
+        resource.name?.toLowerCase().includes(searchTerm) ||
+        resource.summary?.toLowerCase().includes(searchTerm)
+    );
+  }
+
+  const paginatedResult = paginate(allResults, params.cursor);
+
+  if ('error' in paginatedResult) {
+    return paginatedResult;
+  }
+
+  return {
+    resources: paginatedResult.items,
+    nextCursor: paginatedResult.nextCursor,
+    totalCount: paginatedResult.totalCount,
+  };
+}
+
+/**
+ * Get a specific resource by id and version
+ */
+export async function getResource(params: { collection: string; id: string; version: string }) {
+  const resource = await getEntry(params.collection as any, `${params.id}-${params.version}`);
+
+  if (!resource) {
+    return { error: `Resource not found: ${params.id}-${params.version}` };
+  }
+
+  return resource;
+}
+
+/**
+ * Get messages produced or consumed by a resource
+ */
+export async function getMessagesProducedOrConsumedByResource(params: {
+  resourceId: string;
+  resourceVersion: string;
+  resourceCollection: string;
+}) {
+  const resource = await getEntry(params.resourceCollection as any, `${params.resourceId}-${params.resourceVersion}`);
+
+  if (!resource) {
+    return {
+      error: `Resource not found with id ${params.resourceId} and version ${params.resourceVersion} and collection ${params.resourceCollection}`,
+    };
+  }
+
+  return resource;
+}
+
+/**
+ * Get schema or specifications for a resource
+ */
+export async function getSchemaForResource(params: { resourceId: string; resourceVersion: string; resourceCollection: string }) {
+  const resource = await getEntry(params.resourceCollection as any, `${params.resourceId}-${params.resourceVersion}`);
+
+  if (!resource) {
+    return {
+      error: `Resource not found with id ${params.resourceId} and version ${params.resourceVersion} and collection ${params.resourceCollection}`,
+    };
+  }
+
+  if (MESSAGE_COLLECTIONS.has(params.resourceCollection)) {
+    const schemaEntries = await getCollection('schemas');
+    const schemas = schemaEntries.filter(
+      (schema) =>
+        schema.data.message.collection === params.resourceCollection &&
+        schema.data.message.id === params.resourceId &&
+        schema.data.message.version === params.resourceVersion
+    );
+
+    if (schemas.length > 0) {
+      return schemas.map((schema) => ({
+        id: schema.id,
+        name: schema.data.name,
+        ref: schema.data.ref,
+        format: schema.data.format,
+        source: schema.data.source,
+        code: schema.data.content || '',
+      }));
+    }
+  }
+
+  const schema = await getSchemasFromResource(resource);
+
+  if (schema.length > 0) {
+    return schema.map((schemaItem) => ({
+      url: schemaItem.url,
+      format: schemaItem.format,
+      code: fs.readFileSync(schemaItem.url, 'utf-8'),
+    }));
+  }
+
+  return { message: 'No schemas found for this resource' };
+}
+
+/**
+ * Find all resources owned by a specific team or user
+ */
+export async function findResourcesByOwner(params: { ownerId: string }) {
+  const collectionsToSearch = [
+    'events',
+    'commands',
+    'queries',
+    'agents',
+    'services',
+    'domains',
+    'flows',
+    'channels',
+    'entities',
+    'adrs',
+    'containers',
+    'diagrams',
+    'data-products',
+  ] as const;
+
+  const results: Array<{ collection: string; id: string; version?: string; name: string }> = [];
+
+  for (const collectionName of collectionsToSearch) {
+    const resources = await getCollection(collectionName);
+
+    for (const resource of resources) {
+      const owners = (resource.data as any).owners || [];
+      const ownerIds = owners.map((o: any) => (typeof o === 'string' ? o : o.id));
+
+      if (ownerIds.includes(params.ownerId)) {
+        results.push({
+          collection: collectionName,
+          id: (resource.data as any).id,
+          version: (resource.data as any).version,
+          name: (resource.data as any).name || (resource.data as any).id,
+        });
+      }
+    }
+  }
+
+  if (results.length === 0) {
+    return { message: `No resources found owned by: ${params.ownerId}`, resources: [] };
+  }
+
+  return { ownerId: params.ownerId, totalCount: results.length, resources: results };
+}
+
+/**
+ * Get resources that produce (send) a specific message
+ */
+export async function getProducersOfMessage(params: { messageId: string; messageVersion: string; messageCollection: string }) {
+  const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
+  const routableResources = [...services, ...agents];
+  const message = await getEntry(params.messageCollection as any, `${params.messageId}-${params.messageVersion}`);
+
+  if (!message) {
+    return {
+      error: `Message not found: ${params.messageId}-${params.messageVersion} in ${params.messageCollection}`,
+    };
+  }
+
+  const producers = routableResources.filter((resource) => {
+    const sends = (resource.data as any).sends || [];
+    return sends.some((send: any) => {
+      const idMatch = send.id === params.messageId;
+      if (!send.version || send.version === 'latest') return idMatch;
+      return idMatch && send.version === params.messageVersion;
+    });
+  });
+
+  return {
+    message: {
+      id: params.messageId,
+      version: params.messageVersion,
+      collection: params.messageCollection,
+    },
+    producers: producers.map((s) => ({
+      id: (s.data as any).id,
+      version: (s.data as any).version,
+      name: (s.data as any).name || (s.data as any).id,
+      collection: s.collection,
+    })),
+    count: producers.length,
+  };
+}
+
+export async function getC4Diagram(params: { viewId?: string }) {
+  const projectRoot = process.env.PROJECT_DIR || process.cwd();
+  const sources = await discoverLikeC4Sources(projectRoot);
+  const availableViews = sources.flatMap((source) => source.views);
+
+  if (sources.length === 0) {
+    return {
+      message: 'No LikeC4 source files found in this EventCatalog project',
+      sources: [],
+      totalSourceFiles: 0,
+      totalViews: 0,
+    };
+  }
+
+  if (!params.viewId) {
+    return {
+      message: 'LikeC4 source files found',
+      sources,
+      totalSourceFiles: sources.length,
+      totalViews: availableViews.length,
+    };
+  }
+
+  const matchingViews = availableViews.filter((view) => view.id === params.viewId);
+
+  if (matchingViews.length === 0) {
+    return {
+      error: `LikeC4 view not found: ${params.viewId}`,
+      availableViews,
+    };
+  }
+
+  return {
+    viewId: params.viewId,
+    matchingViews,
+    sources,
+    totalSourceFiles: sources.length,
+  };
+}
+
+/**
+ * Get resources that consume (receive) a specific message
+ */
+export async function getConsumersOfMessage(params: { messageId: string; messageVersion: string; messageCollection: string }) {
+  const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
+  const routableResources = [...services, ...agents];
+  const message = await getEntry(params.messageCollection as any, `${params.messageId}-${params.messageVersion}`);
+
+  if (!message) {
+    return {
+      error: `Message not found: ${params.messageId}-${params.messageVersion} in ${params.messageCollection}`,
+    };
+  }
+
+  const consumers = routableResources.filter((resource) => {
+    const receives = (resource.data as any).receives || [];
+    return receives.some((receive: any) => {
+      const idMatch = receive.id === params.messageId;
+      if (!receive.version || receive.version === 'latest') return idMatch;
+      return idMatch && receive.version === params.messageVersion;
+    });
+  });
+
+  return {
+    message: {
+      id: params.messageId,
+      version: params.messageVersion,
+      collection: params.messageCollection,
+    },
+    consumers: consumers.map((s) => ({
+      id: (s.data as any).id,
+      version: (s.data as any).version,
+      name: (s.data as any).name || (s.data as any).id,
+      collection: s.collection,
+    })),
+    count: consumers.length,
+  };
+}
+
+/**
+ * Analyze the impact of changing a message (event, command, query)
+ * Returns all affected services (producers and consumers) and their owners
+ */
+export async function analyzeChangeImpact(params: { messageId: string; messageVersion: string; messageCollection: string }) {
+  const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
+  const routableResources = [...services, ...agents];
+  const message = await getEntry(params.messageCollection as any, `${params.messageId}-${params.messageVersion}`);
+
+  if (!message) {
+    return {
+      error: `Message not found: ${params.messageId}-${params.messageVersion} in ${params.messageCollection}`,
+    };
+  }
+
+  // Find producers
+  const producers = routableResources.filter((resource) => {
+    const sends = (resource.data as any).sends || [];
+    return sends.some((send: any) => send.id === params.messageId);
+  });
+
+  // Find consumers
+  const consumers = routableResources.filter((resource) => {
+    const receives = (resource.data as any).receives || [];
+    return receives.some((receive: any) => receive.id === params.messageId);
+  });
+
+  // Collect all affected teams/owners
+  const affectedOwners = new Set<string>();
+  [...producers, ...consumers].forEach((service) => {
+    const owners = (service.data as any).owners || [];
+    owners.forEach((o: any) => {
+      const ownerId = typeof o === 'string' ? o : o.id;
+      affectedOwners.add(ownerId);
+    });
+  });
+
+  // Also check message owners
+  const messageOwners = (message.data as any).owners || [];
+  messageOwners.forEach((o: any) => {
+    const ownerId = typeof o === 'string' ? o : o.id;
+    affectedOwners.add(ownerId);
+  });
+
+  return {
+    message: {
+      id: params.messageId,
+      version: params.messageVersion,
+      collection: params.messageCollection,
+      name: (message.data as any).name || params.messageId,
+    },
+    impact: {
+      producerCount: producers.length,
+      consumerCount: consumers.length,
+      totalResourcesAffected: new Set([...producers, ...consumers].map((s) => `${s.collection}:${(s.data as any).id}`)).size,
+      totalServicesAffected: new Set(
+        [...producers, ...consumers].filter((s) => s.collection === 'services').map((s) => (s.data as any).id)
+      ).size,
+      totalAgentsAffected: new Set(
+        [...producers, ...consumers].filter((s) => s.collection === 'agents').map((s) => (s.data as any).id)
+      ).size,
+      teamsAffected: Array.from(affectedOwners),
+    },
+    producers: producers.map((s) => ({
+      id: (s.data as any).id,
+      version: (s.data as any).version,
+      name: (s.data as any).name || (s.data as any).id,
+      collection: s.collection,
+      owners: (s.data as any).owners || [],
+    })),
+    consumers: consumers.map((s) => ({
+      id: (s.data as any).id,
+      version: (s.data as any).version,
+      name: (s.data as any).name || (s.data as any).id,
+      collection: s.collection,
+      owners: (s.data as any).owners || [],
+    })),
+  };
+}
+
+/**
+ * Get detailed information about a flow (state machine / business process)
+ * Returns the flow with its steps, description, and related services
+ */
+export async function explainBusinessFlow(params: { flowId: string; flowVersion: string }) {
+  const flow = await getEntry('flows', `${params.flowId}-${params.flowVersion}`);
+
+  if (!flow) {
+    return { error: `Flow not found: ${params.flowId}-${params.flowVersion}` };
+  }
+
+  // Get related services and agents that use this flow
+  const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
+  const relatedServices = services.filter((service) => {
+    const flows = (service.data as any).flows || [];
+    return flows.some((f: any) => f.id === params.flowId);
+  });
+  const relatedAgents = agents.filter((agent) => {
+    const flows = (agent.data as any).flows || [];
+    return flows.some((f: any) => f.id === params.flowId);
+  });
+
+  return {
+    flow: {
+      id: (flow.data as any).id,
+      version: (flow.data as any).version,
+      name: (flow.data as any).name || (flow.data as any).id,
+      summary: (flow.data as any).summary,
+      owners: (flow.data as any).owners || [],
+      steps: (flow.data as any).steps || [],
+      mermaid: (flow.data as any).mermaid,
+    },
+    // Include the markdown content which often contains detailed business logic
+    content: flow.body,
+    relatedServices: relatedServices.map((s) => ({
+      id: (s.data as any).id,
+      version: (s.data as any).version,
+      name: (s.data as any).name || (s.data as any).id,
+    })),
+    relatedAgents: relatedAgents.map((a) => ({
+      id: (a.data as any).id,
+      version: (a.data as any).version,
+      name: (a.data as any).name || (a.data as any).id,
+    })),
+  };
+}
+
+// ============================================
+// Team and User tools (no versions)
+// ============================================
+
+/**
+ * Get all teams with optional pagination
+ */
+export async function getTeams(params: { cursor?: string }) {
+  const teams = await getCollection('teams');
+  const allResults = teams.map((team: any) => ({
+    id: team.data.id,
+    name: team.data.name,
+    email: team.data.email,
+    slackDirectMessageUrl: team.data.slackDirectMessageUrl,
+    members: team.data.members || [],
+  }));
+
+  const paginatedResult = paginate(allResults, params.cursor);
+
+  if ('error' in paginatedResult) {
+    return paginatedResult;
+  }
+
+  return {
+    teams: paginatedResult.items,
+    nextCursor: paginatedResult.nextCursor,
+    totalCount: paginatedResult.totalCount,
+  };
+}
+
+/**
+ * Get a specific team by id
+ */
+export async function getTeam(params: { id: string }) {
+  const teams = await getCollection('teams');
+  const team = teams.find((t: any) => t.data.id === params.id);
+
+  if (!team) {
+    return { error: `Team not found: ${params.id}` };
+  }
+
+  return {
+    id: team.data.id,
+    name: team.data.name,
+    email: team.data.email,
+    slackDirectMessageUrl: team.data.slackDirectMessageUrl,
+    members: team.data.members || [],
+    summary: team.data.summary,
+    content: team.body,
+  };
+}
+
+/**
+ * Get all users with optional pagination
+ */
+export async function getUsers(params: { cursor?: string }) {
+  const users = await getCollection('users');
+  const allResults = users.map((user: any) => ({
+    id: user.data.id,
+    name: user.data.name,
+    email: user.data.email,
+    role: user.data.role,
+    slackDirectMessageUrl: user.data.slackDirectMessageUrl,
+  }));
+
+  const paginatedResult = paginate(allResults, params.cursor);
+
+  if ('error' in paginatedResult) {
+    return paginatedResult;
+  }
+
+  return {
+    users: paginatedResult.items,
+    nextCursor: paginatedResult.nextCursor,
+    totalCount: paginatedResult.totalCount,
+  };
+}
+
+/**
+ * Get a specific user by id
+ */
+export async function getUser(params: { id: string }) {
+  const users = await getCollection('users');
+  const user = users.find((u: any) => u.data.id === params.id);
+
+  if (!user) {
+    return { error: `User not found: ${params.id}` };
+  }
+
+  return {
+    id: user.data.id,
+    name: user.data.name,
+    email: user.data.email,
+    role: user.data.role,
+    slackDirectMessageUrl: user.data.slackDirectMessageUrl,
+    summary: (user.data as any).summary,
+    content: user.body,
+  };
+}
+
+// ============================================
+// Schema-based resource lookup
+// ============================================
+
+/**
+ * Find a message resource and its producers/consumers by id and version
+ * Designed to be used with schema files that contain x-eventcatalog-id extensions
+ * If no version is provided, returns the latest version
+ */
+export async function findMessageBySchemaId(params: {
+  messageId: string;
+  messageVersion?: string;
+  collection?: 'events' | 'commands' | 'queries';
+}) {
+  const collectionsToSearch = params.collection ? [params.collection] : (['events', 'commands', 'queries'] as const);
+
+  for (const collectionName of collectionsToSearch) {
+    const collection = await getCollection(collectionName);
+    const matches = getItemsFromCollectionByIdAndSemverOrLatest(collection, params.messageId, params.messageVersion);
+    const resource = matches[0];
+    if (resource) {
+      // Get producers and consumers
+      const [services, agents] = await Promise.all([getCollection('services'), getCollection('agents')]);
+      const routableResources = [...services, ...agents];
+
+      const producers = routableResources.filter((resource) => {
+        const sends = (resource.data as any).sends || [];
+        return sends.some((send: any) => send.id === params.messageId);
+      });
+
+      const consumers = routableResources.filter((resource) => {
+        const receives = (resource.data as any).receives || [];
+        return receives.some((receive: any) => receive.id === params.messageId);
+      });
+
+      return {
+        resource: {
+          id: (resource.data as any).id,
+          version: (resource.data as any).version,
+          name: (resource.data as any).name,
+          collection: collectionName,
+          summary: (resource.data as any).summary,
+          owners: (resource.data as any).owners || [],
+        },
+        producers: producers.map((s) => ({
+          id: (s.data as any).id,
+          version: (s.data as any).version,
+          name: (s.data as any).name || (s.data as any).id,
+          collection: s.collection,
+        })),
+        consumers: consumers.map((s) => ({
+          id: (s.data as any).id,
+          version: (s.data as any).version,
+          name: (s.data as any).name || (s.data as any).id,
+          collection: s.collection,
+        })),
+      };
+    }
+  }
+
+  return {
+    error: `Message not found: ${params.messageId}${params.messageVersion ? ` (version ${params.messageVersion})` : ''}`,
+  };
+}
+
+// ============================================
+// Ubiquitous Language (DDD)
+// ============================================
+
+/**
+ * Get ubiquitous language terms for a domain (including subdomains)
+ * Returns the domain's language/glossary if defined
+ */
+export async function explainUbiquitousLanguageTerms(params: { domainId: string; domainVersion?: string }) {
+  const domains = await getCollection('domains');
+
+  // Use the existing utility to find the domain by id and version (or latest)
+  const matches = getItemsFromCollectionByIdAndSemverOrLatest(domains, params.domainId, params.domainVersion);
+  const domain = matches[0];
+
+  if (!domain) {
+    return {
+      error: `Domain not found: ${params.domainId}${params.domainVersion ? ` (version ${params.domainVersion})` : ''}`,
+    };
+  }
+
+  // Get ubiquitous language including subdomains
+  const ubiquitousLanguageData = await getUbiquitousLanguageWithSubdomains(domain as any);
+  const { domain: domainUL, subdomains, duplicateTerms } = ubiquitousLanguageData;
+
+  // Extract terms from domain's ubiquitous language
+  const domainTerms =
+    domainUL?.data?.dictionary?.map((term: any) => ({
+      term: term.name,
+      description: term.summary,
+      icon: term.icon,
+      domainId: params.domainId,
+      domainName: (domain.data as any).name || params.domainId,
+      isDuplicate: duplicateTerms.has(term.name.toLowerCase()),
+    })) || [];
+
+  // Extract terms from subdomains
+  const subdomainTerms = subdomains.flatMap(({ subdomain, ubiquitousLanguage }) => {
+    if (!ubiquitousLanguage?.data?.dictionary) return [];
+    return ubiquitousLanguage.data.dictionary.map((term: any) => ({
+      term: term.name,
+      description: term.summary,
+      icon: term.icon,
+      domainId: (subdomain.data as any).id,
+      domainName: (subdomain.data as any).name || (subdomain.data as any).id,
+      isSubdomain: true,
+      isDuplicate: duplicateTerms.has(term.name.toLowerCase()),
+    }));
+  });
+
+  const allTerms = [...domainTerms, ...subdomainTerms];
+
+  if (allTerms.length === 0) {
+    return {
+      domainId: params.domainId,
+      domainVersion: (domain.data as any).version,
+      domainName: (domain.data as any).name || params.domainId,
+      message: 'No ubiquitous language terms defined for this domain or its subdomains',
+      terms: [],
+      subdomainCount: subdomains.length,
+    };
+  }
+
+  return {
+    domainId: params.domainId,
+    domainVersion: (domain.data as any).version,
+    domainName: (domain.data as any).name || params.domainId,
+    terms: allTerms,
+    totalCount: allTerms.length,
+    domainTermCount: domainTerms.length,
+    subdomainTermCount: subdomainTerms.length,
+    subdomainCount: subdomains.length,
+    duplicateTerms: Array.from(duplicateTerms),
+  };
+}
+
+// ============================================
+// Data Product tools
+// ============================================
+
+/**
+ * Get the inputs (resources consumed) for a data product
+ * Returns fully hydrated input resources
+ */
+export async function getDataProductInputs(params: { dataProductId: string; dataProductVersion: string }) {
+  const dataProduct = await getEntry('data-products', `${params.dataProductId}-${params.dataProductVersion}`);
+
+  if (!dataProduct) {
+    return {
+      error: `Data product not found: ${params.dataProductId}-${params.dataProductVersion}`,
+    };
+  }
+
+  const inputPointers = (dataProduct.data as any).inputs || [];
+
+  if (inputPointers.length === 0) {
+    return {
+      dataProductId: params.dataProductId,
+      dataProductVersion: params.dataProductVersion,
+      message: 'No inputs found for this data product',
+      inputs: [],
+    };
+  }
+
+  // Fetch all collections that can be inputs (messages, channels, containers, services)
+  const [allEvents, allCommands, allQueries, allChannels, allContainers, allServices] = await Promise.all([
+    getCollection('events'),
+    getCollection('commands'),
+    getCollection('queries'),
+    getCollection('channels'),
+    getCollection('containers'),
+    getCollection('services'),
+  ]);
+
+  const allResources = [...allEvents, ...allCommands, ...allQueries, ...allChannels, ...allContainers, ...allServices];
+
+  // Hydrate inputs by finding matching resources
+  const hydratedInputs = inputPointers
+    .map((pointer: { id: string; version?: string }) => {
+      const matches = getItemsFromCollectionByIdAndSemverOrLatest(allResources, pointer.id, pointer.version);
+      const resource = matches[0];
+      if (!resource) return null;
+
+      return {
+        id: (resource.data as any).id,
+        version: (resource.data as any).version,
+        name: (resource.data as any).name || (resource.data as any).id,
+        summary: (resource.data as any).summary,
+        collection: resource.collection,
+      };
+    })
+    .filter(Boolean);
+
+  return {
+    dataProductId: params.dataProductId,
+    dataProductVersion: params.dataProductVersion,
+    dataProductName: (dataProduct.data as any).name || params.dataProductId,
+    inputs: hydratedInputs,
+    totalCount: hydratedInputs.length,
+  };
+}
+
+/**
+ * Get the outputs (resources produced) for a data product
+ * Returns fully hydrated output resources with their contracts
+ */
+export async function getDataProductOutputs(params: { dataProductId: string; dataProductVersion: string }) {
+  const dataProduct = await getEntry('data-products', `${params.dataProductId}-${params.dataProductVersion}`);
+
+  if (!dataProduct) {
+    return {
+      error: `Data product not found: ${params.dataProductId}-${params.dataProductVersion}`,
+    };
+  }
+
+  const outputPointers = (dataProduct.data as any).outputs || [];
+
+  if (outputPointers.length === 0) {
+    return {
+      dataProductId: params.dataProductId,
+      dataProductVersion: params.dataProductVersion,
+      message: 'No outputs found for this data product',
+      outputs: [],
+    };
+  }
+
+  // Fetch all collections that can be outputs (messages, channels, containers, services)
+  const [allEvents, allCommands, allQueries, allChannels, allContainers, allServices] = await Promise.all([
+    getCollection('events'),
+    getCollection('commands'),
+    getCollection('queries'),
+    getCollection('channels'),
+    getCollection('containers'),
+    getCollection('services'),
+  ]);
+
+  const allResources = [...allEvents, ...allCommands, ...allQueries, ...allChannels, ...allContainers, ...allServices];
+
+  // Hydrate outputs by finding matching resources and including contract info
+  const hydratedOutputs = outputPointers
+    .map((pointer: { id: string; version?: string; contract?: { path: string; name: string; type?: string } }) => {
+      const matches = getItemsFromCollectionByIdAndSemverOrLatest(allResources, pointer.id, pointer.version);
+      const resource = matches[0];
+      if (!resource) return null;
+
+      const result: any = {
+        id: (resource.data as any).id,
+        version: (resource.data as any).version,
+        name: (resource.data as any).name || (resource.data as any).id,
+        summary: (resource.data as any).summary,
+        collection: resource.collection,
+      };
+
+      // Include contract information if present
+      if (pointer.contract) {
+        const absoluteContractPath = getAbsoluteFilePathForAstroFile(dataProduct.filePath ?? '', pointer.contract.path);
+        let contractContent: string | null = null;
+
+        try {
+          contractContent = fs.readFileSync(absoluteContractPath, 'utf-8');
+        } catch {
+          // File may not be accessible
+        }
+
+        result.contract = {
+          name: pointer.contract.name,
+          path: pointer.contract.path,
+          format: getSchemaFormatFromURL(pointer.contract.path),
+          type: pointer.contract.type,
+          content: contractContent,
+        };
+      }
+
+      return result;
+    })
+    .filter(Boolean);
+
+  return {
+    dataProductId: params.dataProductId,
+    dataProductVersion: params.dataProductVersion,
+    dataProductName: (dataProduct.data as any).name || params.dataProductId,
+    outputs: hydratedOutputs,
+    totalCount: hydratedOutputs.length,
+  };
+}
+
+// ============================================
+// Architecture Diagram (Mermaid) tools
+// ============================================
+
+const getNodesAndEdgesFunctions = {
+  agents: getNodesAndEdgesForAgent,
+  services: getNodesAndEdgesForService,
+  events: getNodesAndEdgesForEvents,
+  commands: getNodesAndEdgesForCommands,
+  queries: getNodesAndEdgesForQueries,
+  domains: getNodesAndEdgesForDomain,
+  flows: getNodesAndEdgesForFlows,
+  containers: getNodesAndEdgesForContainer,
+  'data-products': getNodesAndEdgesForDataProduct,
+  systems: getNodesAndEdgesForSystem,
+};
+
+/**
+ * Get the architecture diagram for a resource as Mermaid code
+ * Returns flowchart syntax that can be rendered or used for understanding architecture
+ */
+export async function getArchitectureDiagramAsMermaid(params: {
+  resourceId: string;
+  resourceVersion: string;
+  resourceCollection: string;
+}) {
+  const { resourceId, resourceVersion, resourceCollection } = params;
+
+  // Validate the collection is supported for visualisation
+  if (!(resourceCollection in getNodesAndEdgesFunctions)) {
+    return {
+      error: `Collection '${resourceCollection}' does not support architecture diagrams. Supported collections: ${Object.keys(getNodesAndEdgesFunctions).join(', ')}`,
+    };
+  }
+
+  try {
+    // Get nodes and edges for this resource
+    const { nodes, edges } = await getNodesAndEdgesFunctions[resourceCollection as keyof typeof getNodesAndEdgesFunctions]({
+      id: resourceId,
+      version: resourceVersion,
+      mode: 'full',
+      channelRenderMode: config.visualiser?.channels?.renderMode === 'single' ? 'single' : 'flat',
+    });
+
+    if (!nodes || nodes.length === 0) {
+      return {
+        error: `No diagram data available for ${resourceCollection}/${resourceId} (v${resourceVersion})`,
+      };
+    }
+
+    // Convert to mermaid
+    const mermaidCode = convertToMermaid(nodes, edges, {
+      includeStyles: true,
+      direction: 'LR',
+    });
+
+    return {
+      resourceId,
+      resourceVersion,
+      resourceCollection,
+      mermaidCode,
+      nodeCount: nodes.length,
+      edgeCount: edges.length,
+      visualiserUrl: `/visualiser/${resourceCollection}/${resourceId}/${resourceVersion}`,
+    };
+  } catch (error) {
+    console.error('Error generating mermaid diagram:', error);
+    return {
+      error: `Failed to generate diagram for ${resourceCollection}/${resourceId} (v${resourceVersion})`,
+    };
+  }
+}
+
+// ============================================
+// Custom Documentation Tools
+// ============================================
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+let cachedDocsSearchIndex: DocsSearchIndex | null = null;
+
+const findCustomDocByIdOrSlug = (docs: any[], idOrSlug: string) => {
+  const normalized = idOrSlug.toLowerCase().trim();
+  return (
+    docs.find((doc) => doc.id.toLowerCase() === normalized) ?? docs.find((doc) => doc.data.slug?.toLowerCase() === normalized)
+  );
+};
+
+const getDocsSearchIndex = async (): Promise<DocsSearchIndex> => {
+  if (CACHE_ENABLED && cachedDocsSearchIndex) {
+    return cachedDocsSearchIndex;
+  }
+
+  const docs = await getCollection('customPages');
+  cachedDocsSearchIndex = buildDocsSearchIndex(
+    docs.map((doc: any) => ({
+      id: doc.id,
+      title: doc.data.title,
+      summary: doc.data.summary,
+      body: doc.body,
+    }))
+  );
+
+  return cachedDocsSearchIndex;
+};
+
+/**
+ * List custom documentation pages (metadata only, no page content)
+ */
+export async function getCustomDocs(params: { cursor?: string; search?: string }) {
+  const docs = await getCollection('customPages');
+  let allResults = docs.map((doc: any) => ({
+    id: doc.id,
+    title: doc.data.title,
+    summary: doc.data.summary,
+    ...(doc.data.slug && { slug: doc.data.slug }),
+  }));
+
+  if (params.search) {
+    const searchTerm = params.search.toLowerCase().trim();
+    allResults = allResults.filter(
+      (doc: any) =>
+        doc.id?.toLowerCase().includes(searchTerm) ||
+        doc.title?.toLowerCase().includes(searchTerm) ||
+        doc.summary?.toLowerCase().includes(searchTerm)
+    );
+  }
+
+  const paginatedResult = paginate(allResults, params.cursor);
+
+  if ('error' in paginatedResult) {
+    return paginatedResult;
+  }
+
+  return {
+    docs: paginatedResult.items,
+    nextCursor: paginatedResult.nextCursor,
+    totalCount: paginatedResult.totalCount,
+  };
+}
+
+/**
+ * Full-text search across custom documentation pages.
+ * Matches at the section level so results point at the relevant part of a page.
+ */
+export async function searchCustomDocs(params: { query: string; limit?: number }) {
+  const query = params.query?.trim();
+
+  if (!query) {
+    return { error: 'A search query is required' };
+  }
+
+  const index = await getDocsSearchIndex();
+  const results = index.search(query, { limit: params.limit });
+
+  return { results, totalCount: results.length };
+}
+
+/**
+ * Get the full markdown content of a custom documentation page by id or slug.
+ * Pass a section heading to get just that section of the page.
+ */
+export async function getCustomDoc(params: { id: string; section?: string }) {
+  const docs = await getCollection('customPages');
+  const doc = findCustomDocByIdOrSlug(docs, params.id);
+
+  if (!doc) {
+    return { error: `Custom documentation page not found: ${params.id}` };
+  }
+
+  const { title, summary, slug, owners } = doc.data;
+  const metadata = {
+    id: doc.id,
+    title,
+    summary,
+    ...(slug && { slug }),
+    ...(owners && { owners }),
+  };
+
+  if (params.section) {
+    const requestedSection = params.section.toLowerCase().trim();
+    const sections = chunkMarkdownByHeadings(doc.body ?? '');
+    const section = sections.find((chunk) => chunk.heading?.toLowerCase() === requestedSection);
+
+    if (!section) {
+      const availableSections = sections
+        .map((chunk) => chunk.heading)
+        .filter(Boolean)
+        .join(', ');
+      return {
+        error: `Section "${params.section}" not found in ${doc.id}. Available sections: ${availableSections || 'none'}`,
+      };
+    }
+
+    return { ...metadata, section: section.heading, markdown: section.content };
+  }
+
+  return { ...metadata, markdown: doc.body ?? '' };
+}
+
+// ============================================
+// Tool metadata (descriptions)
+// ============================================
+
+export const toolDescriptions = {
+  getResources:
+    'Use this tool to get events, agents, services, commands, queries, flows, domains, channels, entities from EventCatalog. Supports pagination via cursor and filtering by search term (searches name, id, and summary).',
+  getResource: 'Use this tool to get a specific resource from EventCatalog by its id and version',
+  getMessagesProducedOrConsumedByResource:
+    'Use this tool to get the messages produced or consumed by a resource by its id and version. Look at the `sends` and `receives` properties to get the messages produced or consumed by the resource',
+  getSchemaForResource:
+    'Use this tool to get the schema or specifications (openapi or asyncapi or graphql) for a resource by its id and version',
+  findResourcesByOwner:
+    'Use this tool to find all resources (agents, services, events, commands, etc.) owned by a specific team or user',
+  getProducersOfMessage:
+    'Use this tool to find which agents or services produce (send) a specific message (event, command, or query)',
+  getConsumersOfMessage:
+    'Use this tool to find which agents or services consume (receive) a specific message (event, command, or query)',
+  getC4Diagram:
+    'Use this tool to get the C4 diagram (or likeC4) in EventCatalog. These files usually have a .c4 extension on them',
+  analyzeChangeImpact:
+    'Use this tool to analyze the impact of changing a message. Returns all affected agents and services (producers and consumers), the teams that own them, and the blast radius of the change',
+  explainBusinessFlow:
+    'Use this tool to get detailed information about a business flow (state machine). Returns the flow definition, steps, mermaid diagram if available, and related agents and services',
+  getTeams:
+    'Use this tool to get all teams in EventCatalog. Teams are groups of users that own resources. Supports pagination via cursor.',
+  getTeam: 'Use this tool to get a specific team by its id. Returns team details including members.',
+  getUsers:
+    'Use this tool to get all users in EventCatalog. Users are individuals who can own resources or be members of teams. Supports pagination via cursor.',
+  getUser: 'Use this tool to get a specific user by their id. Returns user details including role and contact info.',
+  findMessageBySchemaId:
+    'Use this tool when a user shares a schema file (Avro, JSON Schema, Protobuf) and wants to find it in EventCatalog. Look for "x-eventcatalog-id" and "x-eventcatalog-version" in the schema - these may be properties in the schema OR in comments (e.g. // x-eventcatalog-id: OrderCreated). Pass the id as messageId. If version exists, pass it as messageVersion, otherwise omit it to get the latest version. Returns the message resource along with its producers and consumers.',
+  explainUbiquitousLanguageTerms:
+    'Use this tool to explain ubiquitous language terms from Domain-Driven Design for a specific domain. Returns the glossary of terms defined for the domain and its subdomains, including duplicate term detection.',
+  getDataProductInputs:
+    'Use this tool to get the inputs (resources consumed) for a data product. Returns fully hydrated input resources with their id, version, name, summary, and collection type.',
+  getDataProductOutputs:
+    'Use this tool to get the outputs (resources produced) for a data product. Returns fully hydrated output resources with their id, version, name, summary, collection type, and data contracts (if defined). Data contracts include the contract name, path, format, type, and content.',
+  getArchitectureDiagramAsMermaid:
+    'Use this tool to get the architecture diagram for a resource as Mermaid flowchart code. This shows how the resource connects to other resources (agents, services, systems, events, channels, etc.) in the architecture. The mermaid code can be rendered to visualize the architecture or used to understand relationships. Supported collections: events, commands, queries, agents, services, domains, systems, flows, containers, data-products.',
+  getCustomDocs:
+    'Use this tool to list the custom documentation pages in EventCatalog (guides, runbooks, architecture notes, onboarding docs, etc.). Returns page ids, titles, and summaries without page content. Supports pagination via cursor and filtering by search term (searches title, id, and summary).',
+  searchCustomDocs:
+    'Use this tool to search the full text of custom documentation pages in EventCatalog. Returns the best matching sections, each with the page id, section heading, and a short snippet. To read more, call getCustomDoc with the returned page id (and optionally the section heading). Reformulate the query and search again if the first results are not relevant. If you are unsure where to find something, or the structured catalog tools have not answered the question, search here - custom documentation often contains guides, runbooks, and context not captured elsewhere in the catalog. An empty result may simply mean the catalog has no custom documentation on the topic.',
+  getCustomDoc:
+    'Use this tool to get the full markdown content of a custom documentation page by its id or slug. Optionally pass a section heading to get only that section - prefer this for large pages to keep responses small.',
+};
diff --git a/packages/core/eventcatalog/src/enterprise/tools/index.ts b/packages/core/eventcatalog/src/enterprise/tools/index.ts
new file mode 100644
index 000000000..93d0ee9ed
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/tools/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+/**
+ * Enterprise tools for EventCatalog
+ * Shared utilities for AI Chat and MCP Server features
+ */
+export * from './catalog-tools';
diff --git a/packages/core/eventcatalog/src/enterprise/visualizer-layout/reset.ts b/packages/core/eventcatalog/src/enterprise/visualizer-layout/reset.ts
new file mode 100644
index 000000000..8e2d97b0a
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/visualizer-layout/reset.ts
@@ -0,0 +1,50 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { APIRoute } from 'astro';
+import fs from 'node:fs';
+import { getLayoutFilePath } from '@utils/node-graphs/layout-persistence';
+
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const body = await request.json();
+    const { resourceKey } = body;
+
+    // Validate input
+    if (!resourceKey) {
+      return new Response(JSON.stringify({ error: 'Missing required field: resourceKey' }), {
+        status: 400,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    const filePath = getLayoutFilePath(resourceKey);
+
+    // Check if file exists
+    try {
+      await fs.promises.access(filePath);
+    } catch {
+      // File doesn't exist, nothing to delete
+      return new Response(JSON.stringify({ success: true, message: 'No saved layout to reset' }), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    // Delete the layout file
+    await fs.promises.unlink(filePath);
+
+    return new Response(JSON.stringify({ success: true, message: 'Layout reset successfully' }), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    return new Response(JSON.stringify({ error: `Failed to reset layout: ${message}` }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+};
+
+export const prerender = false;
diff --git a/packages/core/eventcatalog/src/enterprise/visualizer-layout/save.ts b/packages/core/eventcatalog/src/enterprise/visualizer-layout/save.ts
new file mode 100644
index 000000000..e13b30360
--- /dev/null
+++ b/packages/core/eventcatalog/src/enterprise/visualizer-layout/save.ts
@@ -0,0 +1,62 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import type { APIRoute } from 'astro';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLayoutFilePath, type SavedLayout } from '@utils/node-graphs/layout-persistence';
+
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const body = await request.json();
+    const { resourceKey, positions } = body;
+
+    // Validate input
+    if (!resourceKey || !positions) {
+      return new Response(JSON.stringify({ error: 'Missing required fields: resourceKey and positions' }), {
+        status: 400,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    // Validate resourceKey doesn't contain path traversal
+    if (resourceKey.includes('..') || resourceKey.includes('~')) {
+      return new Response(JSON.stringify({ error: 'Invalid resourceKey' }), {
+        status: 400,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    // Build file path from resource key using shared utility
+    const filePath = getLayoutFilePath(resourceKey);
+
+    // Create directory structure if needed
+    const fileDir = path.dirname(filePath);
+    await fs.promises.mkdir(fileDir, { recursive: true });
+
+    // Build layout data
+    const layoutData: SavedLayout = {
+      version: 1,
+      savedAt: new Date().toISOString(),
+      resourceKey,
+      positions,
+    };
+
+    // Write file with pretty formatting
+    await fs.promises.writeFile(filePath, JSON.stringify(layoutData, null, 2));
+
+    return new Response(JSON.stringify({ success: true, filePath }), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    return new Response(JSON.stringify({ error: `Failed to save layout: ${message}` }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+};
+
+export const prerender = false;
diff --git a/packages/core/eventcatalog/src/env.d.ts b/packages/core/eventcatalog/src/env.d.ts
new file mode 100644
index 000000000..607abb19d
--- /dev/null
+++ b/packages/core/eventcatalog/src/env.d.ts
@@ -0,0 +1,23 @@
+/// <reference path="../.astro/types.d.ts" />
+/// <reference types="astro/client" />
+
+declare const __EC_TRAILING_SLASH__: boolean;
+declare const __EC_BASE__: string;
+declare const __EC_SEARCH_TYPE__: 'resource' | 'indexed';
+
+declare module 'virtual:likec4-projects' {
+  export const projectRegistry: Record<string, () => Promise<{ LikeC4View: import('react').ComponentType<any> }>>;
+  export const discoveredProjects: string[];
+  export function getProjectLoader(projectName: string): () => Promise<{ LikeC4View: import('react').ComponentType<any> }>;
+}
+
+interface EventCatalogConfig {
+  mermaid?: {
+    iconPacks?: string[];
+    enableSupportForElkLayout?: boolean;
+  };
+}
+
+interface Window {
+  eventcatalog?: EventCatalogConfig;
+}
diff --git a/eventcatalog/src/hooks/eventcatalog-visualizer.ts b/packages/core/eventcatalog/src/hooks/eventcatalog-visualizer.ts
similarity index 100%
rename from eventcatalog/src/hooks/eventcatalog-visualizer.ts
rename to packages/core/eventcatalog/src/hooks/eventcatalog-visualizer.ts
diff --git a/eventcatalog/src/icons/protocols/WebSocket.svg b/packages/core/eventcatalog/src/icons/protocols/WebSocket.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/WebSocket.svg
rename to packages/core/eventcatalog/src/icons/protocols/WebSocket.svg
diff --git a/eventcatalog/src/icons/protocols/amqp.svg b/packages/core/eventcatalog/src/icons/protocols/amqp.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/amqp.svg
rename to packages/core/eventcatalog/src/icons/protocols/amqp.svg
diff --git a/eventcatalog/src/icons/protocols/azure-eventgrid.svg b/packages/core/eventcatalog/src/icons/protocols/azure-eventgrid.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/azure-eventgrid.svg
rename to packages/core/eventcatalog/src/icons/protocols/azure-eventgrid.svg
diff --git a/eventcatalog/src/icons/protocols/azure-eventhubs.svg b/packages/core/eventcatalog/src/icons/protocols/azure-eventhubs.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/azure-eventhubs.svg
rename to packages/core/eventcatalog/src/icons/protocols/azure-eventhubs.svg
diff --git a/eventcatalog/src/icons/protocols/azure-servicebus.svg b/packages/core/eventcatalog/src/icons/protocols/azure-servicebus.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/azure-servicebus.svg
rename to packages/core/eventcatalog/src/icons/protocols/azure-servicebus.svg
diff --git a/eventcatalog/src/icons/protocols/eventbridge.svg b/packages/core/eventcatalog/src/icons/protocols/eventbridge.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/eventbridge.svg
rename to packages/core/eventcatalog/src/icons/protocols/eventbridge.svg
diff --git a/eventcatalog/src/icons/protocols/googlepubsub.svg b/packages/core/eventcatalog/src/icons/protocols/googlepubsub.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/googlepubsub.svg
rename to packages/core/eventcatalog/src/icons/protocols/googlepubsub.svg
diff --git a/eventcatalog/src/icons/protocols/grpc.svg b/packages/core/eventcatalog/src/icons/protocols/grpc.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/grpc.svg
rename to packages/core/eventcatalog/src/icons/protocols/grpc.svg
diff --git a/eventcatalog/src/icons/protocols/http.svg b/packages/core/eventcatalog/src/icons/protocols/http.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/http.svg
rename to packages/core/eventcatalog/src/icons/protocols/http.svg
diff --git a/eventcatalog/src/icons/protocols/index.ts b/packages/core/eventcatalog/src/icons/protocols/index.ts
similarity index 100%
rename from eventcatalog/src/icons/protocols/index.ts
rename to packages/core/eventcatalog/src/icons/protocols/index.ts
diff --git a/eventcatalog/src/icons/protocols/jms.svg b/packages/core/eventcatalog/src/icons/protocols/jms.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/jms.svg
rename to packages/core/eventcatalog/src/icons/protocols/jms.svg
diff --git a/eventcatalog/src/icons/protocols/kafka.svg b/packages/core/eventcatalog/src/icons/protocols/kafka.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/kafka.svg
rename to packages/core/eventcatalog/src/icons/protocols/kafka.svg
diff --git a/eventcatalog/src/icons/protocols/kinesis.svg b/packages/core/eventcatalog/src/icons/protocols/kinesis.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/kinesis.svg
rename to packages/core/eventcatalog/src/icons/protocols/kinesis.svg
diff --git a/eventcatalog/src/icons/protocols/mercure.svg b/packages/core/eventcatalog/src/icons/protocols/mercure.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/mercure.svg
rename to packages/core/eventcatalog/src/icons/protocols/mercure.svg
diff --git a/eventcatalog/src/icons/protocols/mqtt.svg b/packages/core/eventcatalog/src/icons/protocols/mqtt.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/mqtt.svg
rename to packages/core/eventcatalog/src/icons/protocols/mqtt.svg
diff --git a/eventcatalog/src/icons/protocols/nats.svg b/packages/core/eventcatalog/src/icons/protocols/nats.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/nats.svg
rename to packages/core/eventcatalog/src/icons/protocols/nats.svg
diff --git a/eventcatalog/src/icons/protocols/pulsar.svg b/packages/core/eventcatalog/src/icons/protocols/pulsar.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/pulsar.svg
rename to packages/core/eventcatalog/src/icons/protocols/pulsar.svg
diff --git a/eventcatalog/src/icons/protocols/redis.svg b/packages/core/eventcatalog/src/icons/protocols/redis.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/redis.svg
rename to packages/core/eventcatalog/src/icons/protocols/redis.svg
diff --git a/eventcatalog/src/icons/protocols/sns.svg b/packages/core/eventcatalog/src/icons/protocols/sns.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/sns.svg
rename to packages/core/eventcatalog/src/icons/protocols/sns.svg
diff --git a/eventcatalog/src/icons/protocols/solace.svg b/packages/core/eventcatalog/src/icons/protocols/solace.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/solace.svg
rename to packages/core/eventcatalog/src/icons/protocols/solace.svg
diff --git a/eventcatalog/src/icons/protocols/sqs.svg b/packages/core/eventcatalog/src/icons/protocols/sqs.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/sqs.svg
rename to packages/core/eventcatalog/src/icons/protocols/sqs.svg
diff --git a/eventcatalog/src/icons/protocols/tibo-ftl.svg b/packages/core/eventcatalog/src/icons/protocols/tibo-ftl.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/tibo-ftl.svg
rename to packages/core/eventcatalog/src/icons/protocols/tibo-ftl.svg
diff --git a/eventcatalog/src/icons/protocols/tibo-rv.svg b/packages/core/eventcatalog/src/icons/protocols/tibo-rv.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/tibo-rv.svg
rename to packages/core/eventcatalog/src/icons/protocols/tibo-rv.svg
diff --git a/eventcatalog/src/icons/protocols/ws.svg b/packages/core/eventcatalog/src/icons/protocols/ws.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/ws.svg
rename to packages/core/eventcatalog/src/icons/protocols/ws.svg
diff --git a/eventcatalog/src/icons/protocols/zmq.svg b/packages/core/eventcatalog/src/icons/protocols/zmq.svg
similarity index 100%
rename from eventcatalog/src/icons/protocols/zmq.svg
rename to packages/core/eventcatalog/src/icons/protocols/zmq.svg
diff --git a/packages/core/eventcatalog/src/layouts/BaseLayout.astro b/packages/core/eventcatalog/src/layouts/BaseLayout.astro
new file mode 100644
index 000000000..4f4834a04
--- /dev/null
+++ b/packages/core/eventcatalog/src/layouts/BaseLayout.astro
@@ -0,0 +1,52 @@
+---
+import SEO from '../components/Seo.astro';
+import AnalyticsHead from '../enterprise/analytics/components/AnalyticsHead.astro';
+import AnalyticsTracker from '../enterprise/analytics/components/AnalyticsTracker.astro';
+import config from '@config';
+
+interface Props {
+  title: string;
+  description?: string;
+  ogTitle?: string;
+}
+
+const { title, description, ogTitle } = Astro.props;
+const catalogTheme = config.theme || 'default';
+---
+
+<!doctype html>
+<html lang="en" data-catalog-theme={catalogTheme}>
+  <head>
+    <!-- Inline script to prevent flash of wrong theme -->
+    <script is:inline define:vars={{ catalogTheme }}>
+      (function () {
+        function getDefaultTheme() {
+          return 'dark';
+        }
+
+        function applyTheme() {
+          // Check localStorage first, fall back to dark mode
+          const stored = localStorage.getItem('eventcatalog-theme');
+          const theme = stored === 'light' || stored === 'dark' ? stored : getDefaultTheme();
+          document.documentElement.setAttribute('data-theme', theme);
+          // Also ensure catalog theme is set (for page transitions)
+          document.documentElement.setAttribute('data-catalog-theme', catalogTheme);
+        }
+
+        // Apply on initial load
+        applyTheme();
+
+        // Apply after Astro page transitions
+        document.addEventListener('astro:after-swap', applyTheme);
+        document.addEventListener('astro:page-load', applyTheme);
+      })();
+    </script>
+    <SEO title={title} description={description} ogTitle={ogTitle} />
+    <AnalyticsHead />
+    <slot name="head" />
+  </head>
+  <body>
+    <slot />
+    <AnalyticsTracker />
+  </body>
+</html>
diff --git a/packages/core/eventcatalog/src/layouts/DirectoryLayout.astro b/packages/core/eventcatalog/src/layouts/DirectoryLayout.astro
new file mode 100644
index 000000000..bab30d836
--- /dev/null
+++ b/packages/core/eventcatalog/src/layouts/DirectoryLayout.astro
@@ -0,0 +1,50 @@
+---
+import { Table, type TData, type TCollectionTypes } from '@components/Tables/Table';
+import VerticalSideBarLayout from './VerticalSideBarLayout.astro';
+import config from '@config';
+
+export interface Props<T extends TCollectionTypes> {
+  title: string;
+  subtitle: string;
+  data: TData<T>[];
+  type: T;
+}
+
+const { title, subtitle, data, type } = Astro.props;
+
+const checkboxLatestId = 'latest-only';
+const checkboxDraftsId = 'drafts-only';
+
+// @ts-ignore
+const tableConfiguration = config[type as keyof typeof config]?.tableConfiguration ?? { columns: {} };
+---
+
+<VerticalSideBarLayout title={`Explore | ${title}`} showNestedSideBar={false}>
+  <main
+    class="ml-0 bg-[rgb(var(--ec-page-bg))]"
+    style="margin-left: calc(var(--ec-app-content-padding-left, 5rem) * -1); margin-right: calc(var(--ec-app-content-padding-right, 5rem) * -1);"
+  >
+    <div class="p-8 pb-20">
+      <div class="min-w-0">
+        <h1 class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] capitalize md:text-4xl">{title}</h1>
+        <p class="max-w-3xl pt-2 text-base font-light text-[rgb(var(--ec-page-text-muted))]">{subtitle}</p>
+      </div>
+      <div class="mt-2 min-w-0">
+        <Table
+          checkboxLatestId={checkboxLatestId}
+          checkboxDraftsId={checkboxDraftsId}
+          data={data}
+          collection={type}
+          tableConfiguration={tableConfiguration}
+          client:load
+        />
+      </div>
+    </div>
+  </main>
+</VerticalSideBarLayout>
+
+<style>
+  .ec-align-top {
+    vertical-align: top !important;
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/layouts/DiscoverLayout.astro b/packages/core/eventcatalog/src/layouts/DiscoverLayout.astro
new file mode 100644
index 000000000..21e131814
--- /dev/null
+++ b/packages/core/eventcatalog/src/layouts/DiscoverLayout.astro
@@ -0,0 +1,198 @@
+---
+import { Table, type TData, type TCollectionTypes } from '@components/Tables/Table';
+import { QueueListIcon, RectangleGroupIcon, BoltIcon, ChatBubbleLeftIcon } from '@heroicons/react/24/outline';
+import ServerIcon from '@heroicons/react/24/outline/ServerIcon';
+import { getCommands } from '@utils/collections/commands';
+import { getDomains } from '@utils/collections/domains';
+import { getFlows } from '@utils/collections/flows';
+import { getEvents } from '@utils/collections/events';
+import { getServices } from '@utils/collections/services';
+import { buildUrl } from '@utils/url-builder';
+import { getQueries } from '@utils/collections/queries';
+import { getContainers } from '@utils/collections/containers';
+import { BookText, DatabaseIcon } from 'lucide-react';
+import { getAdrs } from '@utils/collections/adrs';
+import { MagnifyingGlassIcon } from '@heroicons/react/20/solid';
+import VerticalSideBarLayout from './VerticalSideBarLayout.astro';
+import Checkbox from '@components/Checkbox.astro';
+import config from '@config';
+
+const events = await getEvents();
+const queries = await getQueries();
+const commands = await getCommands();
+const services = await getServices();
+const domains = await getDomains();
+const flows = await getFlows();
+const containers = await getContainers();
+const adrs = await getAdrs();
+export interface Props<T extends TCollectionTypes> {
+  title: string;
+  subtitle: string;
+  data: TData<T>[];
+  type: T;
+}
+
+const { title, subtitle, data, type } = Astro.props;
+const currentPath = Astro.url.pathname;
+
+const checkboxLatestId = 'latest-only';
+const checkboxDraftsId = 'show-drafts';
+
+// @ts-ignore
+const tableConfiguration = config[type as keyof typeof config]?.tableConfiguration ?? { columns: {} };
+
+const tabs = [
+  {
+    label: `Events (${events.length})`,
+    href: buildUrl('/discover/events'),
+    isActive: currentPath === '/discover/events',
+    icon: BoltIcon,
+    activeColor: 'orange',
+    enabled: events.length > 0,
+    visible: events.length > 0,
+  },
+  {
+    label: `Commands (${commands.length})`,
+    href: buildUrl('/discover/commands'),
+    isActive: currentPath === '/discover/commands',
+    icon: ChatBubbleLeftIcon,
+    activeColor: 'blue',
+    enabled: commands.length > 0,
+    visible: commands.length > 0,
+  },
+  {
+    label: `Queries (${queries.length})`,
+    href: buildUrl('/discover/queries'),
+    isActive: currentPath === '/discover/queries',
+    icon: MagnifyingGlassIcon,
+    activeColor: 'green',
+    enabled: queries.length > 0,
+    visible: queries.length > 0,
+  },
+  {
+    label: `Services (${services.length})`,
+    href: buildUrl('/discover/services'),
+    isActive: currentPath === '/discover/services',
+    icon: ServerIcon,
+    activeColor: 'pink',
+    enabled: services.length > 0,
+    visible: services.length > 0,
+  },
+  {
+    label: `Domains (${domains.length})`,
+    href: buildUrl('/discover/domains'),
+    isActive: currentPath === '/discover/domains',
+    icon: RectangleGroupIcon,
+    activeColor: 'yellow',
+    enabled: domains.length > 0,
+    visible: domains.length > 0,
+  },
+  {
+    label: `Decision Records (${adrs.length})`,
+    href: buildUrl('/discover/adrs'),
+    isActive: currentPath === '/discover/adrs',
+    icon: BookText,
+    activeColor: 'purple',
+    enabled: adrs.length > 0,
+    visible: adrs.length > 0,
+  },
+  {
+    label: `Data (${containers.length})`,
+    href: buildUrl('/discover/containers'),
+    isActive: currentPath === '/discover/containers',
+    icon: DatabaseIcon,
+    activeColor: 'blue',
+    enabled: containers.length > 0,
+    visible: containers.length > 0,
+  },
+  {
+    label: `Flows (${flows.length})`,
+    href: buildUrl('/discover/flows'),
+    isActive: currentPath === '/discover/flows',
+    icon: QueueListIcon,
+    activeColor: 'teal',
+    enabled: flows.length > 0,
+    visible: flows.length > 0,
+  },
+];
+---
+
+<VerticalSideBarLayout title={`Explore | ${title}`} showNestedSideBar={false}>
+  <main class="ml-0 bg-[rgb(var(--ec-page-bg))] min-h-content">
+    <div id="discover-collection-tabs">
+      <div class="hidden sm:block">
+        <div class="border-b border-[rgb(var(--ec-page-border))]">
+          <nav class="flex space-x-8 -mb-0.5 pl-6" aria-label="Tabs">
+            {
+              tabs
+                .filter((tab) => tab.visible)
+                .map((tab) => (
+                  <a
+                    href={tab.href}
+                    class:list={[
+                      'group inline-flex items-center py-4 px-1 text-sm font-light text-[rgb(var(--ec-page-text))]',
+                      tab.isActive && 'border-b-[2px] border-[rgb(var(--ec-accent))] text-[rgb(var(--ec-accent))]',
+                      !tab.isActive && 'opacity-70 hover:opacity-100',
+                      !tab.enabled && 'disabled',
+                    ]}
+                    aria-current="page"
+                  >
+                    <tab.icon
+                      className={`w-6 h-6 -ml-0.5 mr-2 ${tab.isActive ? 'text-[rgb(var(--ec-accent))]' : 'text-[rgb(var(--ec-icon-color))]'}`}
+                    />
+                    <span>{tab.label}</span>
+                  </a>
+                ))
+            }
+          </nav>
+        </div>
+      </div>
+    </div>
+
+    <!-- Table -->
+    <div class="pb-20 ml-6 md:pr-10">
+      <div>
+        <div class="sm:flex sm:items-end py-4 pb-4" id="discover-title">
+          <div class="sm:flex-auto space-y-2">
+            <h1 class="text-4xl font-semibold text-[rgb(var(--ec-page-text))] capitalize">{title}</h1>
+            <p class="text-md text-[rgb(var(--ec-page-text-muted))]">{subtitle}</p>
+          </div>
+          <div class="flex gap-4">
+            <div class="p-4 border border-[rgb(var(--ec-page-border))] rounded-md bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))]">
+              <Checkbox id={checkboxLatestId} name={checkboxLatestId} label="Show latest version only" checked />
+            </div>
+            <div class="p-4 border border-[rgb(var(--ec-page-border))] rounded-md bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))]">
+              <Checkbox id={checkboxDraftsId} name={checkboxDraftsId} label="Show drafts only" />
+            </div>
+          </div>
+        </div>
+        <div class="mt-4 flow-root">
+          <div class="-mx-4 -my-2 overflow-x-auto sm:-mx-6 lg:-mx-8">
+            <div class="inline-block min-w-full align-middle sm:px-6 lg:px-8">
+              <Table
+                checkboxLatestId={checkboxLatestId}
+                checkboxDraftsId={checkboxDraftsId}
+                data={data}
+                collection={type}
+                tableConfiguration={tableConfiguration}
+                client:load
+              />
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </main>
+</VerticalSideBarLayout>
+
+<style>
+  .ec-align-top {
+    vertical-align: top !important;
+  }
+
+  a.disabled {
+    pointer-events: none;
+    cursor: default;
+    opacity: 0.25;
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/layouts/Footer.astro b/packages/core/eventcatalog/src/layouts/Footer.astro
new file mode 100644
index 000000000..5afca1698
--- /dev/null
+++ b/packages/core/eventcatalog/src/layouts/Footer.astro
@@ -0,0 +1,49 @@
+---
+import { buildUrl } from '@utils/url-builder';
+import { showEventCatalogBranding } from '@utils/feature';
+const { className } = Astro.props;
+---
+
+<footer
+  transition:persist="site-footer"
+  class={`relative py-4 space-y-8 border-t border-[rgb(var(--ec-page-border))] ${className}`}
+>
+  {
+    showEventCatalogBranding() && (
+      <div class="flex justify-between items-center py-8 text-[rgb(var(--ec-page-text-muted))] text-sm font-light">
+        <div class="flex space-x-5">
+          <a href="https://github.com/event-catalog/eventcatalog" target="_blank" aria-label="View EventCatalog on GitHub">
+            <svg
+              class="w-5 h-5 bg-[rgb(var(--ec-icon-color))] hover:bg-[rgb(var(--ec-accent))]"
+              style={`mask-image: url("${buildUrl('/icons/github.svg', true)}"); mask-repeat: no-repeat; mask-position: center center;`}
+              aria-hidden="true"
+            />
+          </a>
+          <a href="https://x.com/event_catalog" target="_blank" aria-label="Follow EventCatalog on X (Twitter)">
+            <span class="sr-only">X (Twitter)</span>
+            <svg
+              class="w-5 h-5 bg-[rgb(var(--ec-icon-color))] hover:bg-[rgb(var(--ec-accent))]"
+              style={`mask-image: url("${buildUrl('/icons/x-twitter.svg', true)}"); mask-repeat: no-repeat; mask-position: center center;`}
+              aria-hidden="true"
+            />
+          </a>
+          <a href="https://www.youtube.com/@event-catalog" target="_blank" aria-label="Watch EventCatalog on YouTube">
+            <span class="sr-only">YouTube</span>
+            <svg
+              class="w-5 h-5 bg-[rgb(var(--ec-icon-color))] hover:bg-[rgb(var(--ec-accent))]"
+              style={`mask-image: url("${buildUrl('/icons/youtube.svg', true)}"); mask-repeat: no-repeat; mask-position: center center;`}
+              aria-hidden="true"
+            />
+          </a>
+        </div>
+        <a
+          target="_blank"
+          class="hover:text-[rgb(var(--ec-accent))] hover:underline text-[rgb(var(--ec-icon-color))] font-light not-prose"
+          href="https://eventcatalog.dev"
+        >
+          Powered by EventCatalog
+        </a>
+      </div>
+    )
+  }
+</footer>
diff --git a/packages/core/eventcatalog/src/layouts/SettingsLayout.astro b/packages/core/eventcatalog/src/layouts/SettingsLayout.astro
new file mode 100644
index 000000000..ffff4fb43
--- /dev/null
+++ b/packages/core/eventcatalog/src/layouts/SettingsLayout.astro
@@ -0,0 +1,116 @@
+---
+import VerticalSideBarLayout from './VerticalSideBarLayout.astro';
+import { buildUrl } from '@utils/url-builder';
+import { Settings, Server, Bot, FileText, CreditCard } from 'lucide-react';
+
+export type SettingsSection = 'general' | 'mcp' | 'assistant' | 'llm-access' | 'billing';
+
+interface Props {
+  title: string;
+  active: SettingsSection;
+}
+
+const { title, active } = Astro.props;
+
+interface SectionItem {
+  id: SettingsSection;
+  label: string;
+  href: string;
+  icon: any;
+}
+
+interface SectionGroup {
+  label: string;
+  items: SectionItem[];
+}
+
+const groups: SectionGroup[] = [
+  {
+    label: 'Project Settings',
+    items: [
+      {
+        id: 'general',
+        label: 'General',
+        href: buildUrl('/settings/general'),
+        icon: Settings,
+      },
+    ],
+  },
+  {
+    label: 'AI Settings',
+    items: [
+      {
+        id: 'mcp',
+        label: 'MCP',
+        href: buildUrl('/settings/mcp'),
+        icon: Server,
+      },
+      {
+        id: 'assistant',
+        label: 'Agent',
+        href: buildUrl('/settings/assistant'),
+        icon: Bot,
+      },
+      {
+        id: 'llm-access',
+        label: 'LLM Access',
+        href: buildUrl('/settings/llm-access'),
+        icon: FileText,
+      },
+    ],
+  },
+  {
+    label: 'Workspace',
+    items: [
+      {
+        id: 'billing',
+        label: 'Billing',
+        href: buildUrl('/settings/billing'),
+        icon: CreditCard,
+      },
+    ],
+  },
+];
+---
+
+<VerticalSideBarLayout title={`${title} | Settings`} showNestedSideBar={true}>
+  <Fragment slot="sidebar-content">
+    <div class="settings-rail flex h-full flex-col bg-[rgb(var(--ec-rail-bg))]">
+      <nav class="flex flex-1 flex-col gap-4 overflow-y-auto px-3 pt-6 pb-4">
+        {
+          groups.map((group) => (
+            <div class="space-y-1">
+              <p class="rail-section-label px-3 pb-1 text-[0.65rem] font-semibold uppercase tracking-[0.18em] text-[rgb(var(--ec-sidebar-text)/0.5)]">
+                {group.label}
+              </p>
+              <div class="flex flex-col gap-1">
+                {group.items.map((item) => {
+                  const isActive = item.id === active;
+                  return (
+                    <a
+                      href={item.href}
+                      aria-current={isActive ? 'page' : undefined}
+                      class:list={[
+                        'nav-secondary-item flex items-center gap-3 px-3 py-2.5 text-[13px] font-medium transition-colors duration-150',
+                        isActive
+                          ? 'font-semibold text-[rgb(var(--ec-page-text))]'
+                          : 'text-[rgb(var(--ec-sidebar-text))] hover:text-[rgb(var(--ec-page-text))]',
+                      ]}
+                    >
+                      <item.icon className="h-3.5 w-3.5 flex-shrink-0" aria-hidden="true" />
+                      <span class="nav-item-label">{item.label}</span>
+                    </a>
+                  );
+                })}
+              </div>
+            </div>
+          ))
+        }
+      </nav>
+    </div>
+  </Fragment>
+
+  <div class="settings-page w-full px-8 py-8">
+    <slot />
+  </div>
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/layouts/VerticalSideBarLayout.astro b/packages/core/eventcatalog/src/layouts/VerticalSideBarLayout.astro
new file mode 100644
index 000000000..2038c1aa2
--- /dev/null
+++ b/packages/core/eventcatalog/src/layouts/VerticalSideBarLayout.astro
@@ -0,0 +1,1031 @@
+---
+interface Props {
+  title: string;
+  sidebar?: boolean;
+  description?: string;
+  showNestedSideBar?: boolean;
+  showHeader?: boolean;
+  /** Wrap the page content in EventCatalog's default app content container. Defaults to true. */
+  wrapContent?: boolean;
+  // When true, the main content uses a reduced horizontal padding instead of the
+  // default 5rem. Used by wide pages such as the custom landing page.
+  reducedContentPadding?: boolean;
+}
+
+import * as LucideIcons from 'lucide-react';
+import BaseLayout from './BaseLayout.astro';
+import Header from '../components/Header.astro';
+import SideNav from '../components/SideNav/SideNav.astro';
+import SearchDataLoader from '../components/Search/SearchDataLoader.astro';
+import config from '@config';
+import { getCollection } from 'astro:content';
+import '@fontsource/inter';
+import '@fontsource/inter/400.css'; // Specify weight
+import '@fontsource/inter/700.css'; // Specify weight
+
+// Tailwind CSS v4 (CSS-first config)
+import '../styles/tailwind.css';
+
+// Theme CSS variables (must load before user styles)
+import '../styles/theme.css';
+
+// Theme files - imported so they're available, applied via data-catalog-theme attribute
+import '../styles/themes/ocean.css';
+import '../styles/themes/sapphire.css';
+import '../styles/themes/sunset.css';
+import '../styles/themes/forest.css';
+
+import { ClientRouter } from 'astro:transitions';
+
+import { getCommands } from '@utils/collections/commands';
+import { getDomains } from '@utils/collections/domains';
+import { getSystems } from '@utils/collections/systems';
+import { getEvents } from '@utils/collections/events';
+import { getServices } from '@utils/collections/services';
+import { getAgents } from '@utils/collections/agents';
+import { getFlows } from '@utils/collections/flows';
+import { getAdrs } from '@utils/collections/adrs';
+import { getContainers } from '@utils/collections/containers';
+import { getDataProducts } from '@utils/collections/data-products';
+import { isCollectionVisibleInCatalog } from '@eventcatalog';
+import { buildUrl } from '@utils/url-builder';
+import { getQueries } from '@utils/collections/queries';
+import { getFirstNavigationPage } from '@enterprise/custom-documentation/utils/custom-docs';
+
+import { isEmbedEnabled, isCustomStylesEnabled, isCustomDocsEnabled, isSSR } from '@utils/feature';
+
+const customDocs = await getCollection('customPages');
+const firstCustomDocsPage = isCustomDocsEnabled() && customDocs.length > 0 ? await getFirstNavigationPage() : null;
+
+let events: any[] = [];
+let commands: any[] = [];
+let queries: any[] = [];
+let services: any[] = [];
+let agents: any[] = [];
+let adrs: any[] = [];
+let domains: any[] = [];
+let systems: any[] = [];
+let flows: any[] = [];
+let containers: any[] = [];
+let dataProducts: any[] = [];
+
+[events, commands, queries, services, agents, adrs, domains, systems, flows, containers, dataProducts] = await Promise.all([
+  getEvents({ getAllVersions: false, hydrateServices: false }),
+  getCommands({ getAllVersions: false, hydrateServices: false }),
+  getQueries({ getAllVersions: false, hydrateServices: false }),
+  getServices({ getAllVersions: false }),
+  getAgents({ getAllVersions: false }),
+  getAdrs({ getAllVersions: false }),
+  getDomains({ getAllVersions: false }),
+  getSystems({ getAllVersions: false }),
+  getFlows({ getAllVersions: false }),
+  getContainers({ getAllVersions: false }),
+  getDataProducts({ getAllVersions: false }),
+]);
+
+// Try and load any custom styles if they exist
+if (isCustomStylesEnabled()) {
+  try {
+    await import('../../eventcatalog.styles.css');
+  } catch (error) {}
+}
+
+const currentPath = Astro.url.pathname;
+const wrapContent = Astro.props.wrapContent ?? true;
+
+const getDefaultUrl = (route: string, defaultValue: string) => {
+  if (route === 'docs/custom') {
+    return firstCustomDocsPage ? buildUrl(`/${route}/${firstCustomDocsPage.slug}`) : buildUrl(defaultValue);
+  }
+
+  const collections = [
+    { data: domains, key: 'domains' },
+    { data: services, key: 'services' },
+    { data: agents, key: 'agents' },
+    { data: events, key: 'events' },
+    { data: commands, key: 'commands' },
+    { data: queries, key: 'queries' },
+    { data: flows, key: 'flows' },
+  ];
+
+  for (const { data, key } of collections) {
+    if (data.length > 0 && isCollectionVisibleInCatalog(key)) {
+      // find the first item that has visualiser set to true
+      const item = data.find((item) => item.data.visualiser !== false);
+      if (item) {
+        return buildUrl(`/${route}/${key}/${item.data.id}/${item.data.latestVersion}`);
+      } else {
+        continue;
+      }
+    }
+  }
+
+  return buildUrl(defaultValue);
+};
+
+const internalServices = services.filter((service) => !service.data.externalSystem);
+const externalSystems = services.filter((service) => service.data.externalSystem);
+const discoverTargets = [
+  { id: '/discover/domains', href: buildUrl('/discover/domains'), count: domains.length },
+  { id: '/discover/systems', href: buildUrl('/discover/systems'), count: systems.length },
+  {
+    id: '/discover/services',
+    href: buildUrl('/discover/services'),
+    count: internalServices.length,
+  },
+  {
+    id: '/discover/external-systems',
+    href: buildUrl('/discover/external-systems'),
+    count: externalSystems.length,
+  },
+  { id: '/discover/agents', href: buildUrl('/discover/agents'), count: agents.length },
+  { id: '/discover/adrs', href: buildUrl('/discover/adrs'), count: adrs.length },
+  {
+    id: '/discover/data-products',
+    href: buildUrl('/discover/data-products'),
+    count: dataProducts.length,
+  },
+  { id: '/discover/containers', href: buildUrl('/discover/containers'), count: containers.length },
+  { id: '/discover/events', href: buildUrl('/discover/events'), count: events.length },
+  { id: '/discover/commands', href: buildUrl('/discover/commands'), count: commands.length },
+  { id: '/discover/queries', href: buildUrl('/discover/queries'), count: queries.length },
+  { id: '/discover/flows', href: buildUrl('/discover/flows'), count: flows.length },
+];
+const defaultDiscoverTarget = discoverTargets.find((target) => target.count > 0);
+
+type NavigationItemConfig = {
+  id: string;
+  label?: string;
+  icon?: string;
+  href?: string;
+  visible?: boolean;
+  match?: string | string[];
+};
+
+type NavigationGroupConfig = {
+  id: string;
+  label?: string;
+  visible?: boolean;
+  position?: 'top' | 'bottom';
+  items?: NavigationItemConfig[];
+};
+
+type VerticalNavigationItem = Required<Pick<NavigationItemConfig, 'id' | 'label' | 'href'>> & {
+  icon: string;
+  current: boolean;
+  matchId: string;
+  match?: string | string[];
+  target?: string;
+  rel?: string;
+  Icon: any;
+};
+
+const toPascalCase = (value: string) =>
+  value
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+
+const resolveLucideIcon = (icon?: string) => {
+  if (!icon) return LucideIcons.Circle;
+
+  const icons = LucideIcons as unknown as Record<string, any>;
+  return (
+    icons[icon] || icons[`${icon}Icon`] || icons[toPascalCase(icon)] || icons[`${toPascalCase(icon)}Icon`] || LucideIcons.Circle
+  );
+};
+
+const normalizeNavigationHref = (href: string) => {
+  if (/^(https?:)?\/\//.test(href) || href.startsWith('mailto:') || href.startsWith('#')) {
+    return href;
+  }
+
+  return buildUrl(href);
+};
+
+const isExternalNavigationHref = (href: string) => /^https?:\/\//.test(href);
+
+const normalizeNavigationMatch = (match?: string | string[]) => {
+  if (!match) return undefined;
+
+  const normalizeMatch = (value: string) => (isExternalNavigationHref(value) ? value : buildUrl(value, true));
+  return Array.isArray(match) ? match.map(normalizeMatch) : normalizeMatch(match);
+};
+
+const navigationBuiltinAliases: Record<string, string> = {
+  home: '/',
+  docs: '/docs/custom',
+  catalog: '/discover',
+  schemas: '/schemas/explorer',
+  'schema-insights': '/schemas/fields',
+  teams: '/directory/teams',
+  users: '/directory/users',
+  settings: '/settings/general',
+  studio: '/studio',
+};
+
+const builtinNavigationItems: Record<string, Omit<VerticalNavigationItem, 'current' | 'Icon'>> = {
+  '/': {
+    id: '/',
+    matchId: '/',
+    label: 'Home',
+    icon: 'House',
+    href: buildUrl(config.landingPage || '/'),
+  },
+  '/docs/custom': {
+    id: '/docs/custom',
+    matchId: '/docs/custom',
+    label: 'Docs',
+    icon: 'FileText',
+    href: getDefaultUrl('docs/custom', '/docs/custom'),
+  },
+  '/studio': {
+    id: '/studio',
+    matchId: '/studio',
+    label: 'EventCatalog Studio',
+    icon: 'SquareDashedMousePointer',
+    href: buildUrl('/studio'),
+  },
+  '/discover': {
+    id: '/discover',
+    matchId: '/discover',
+    label: 'Catalog',
+    icon: 'TableProperties',
+    href: defaultDiscoverTarget?.href ?? buildUrl('/discover/domains'),
+  },
+  '/schemas/explorer': {
+    id: '/schemas/explorer',
+    matchId: '/schemas/explorer',
+    label: 'Schemas & APIs',
+    icon: 'FileCode',
+    href: buildUrl('/schemas/explorer'),
+  },
+  '/schemas/fields': {
+    id: '/schemas/fields',
+    matchId: '/schemas/fields',
+    label: 'Schema Insights',
+    icon: 'Waypoints',
+    href: buildUrl('/schemas/fields'),
+  },
+  '/directory/teams': {
+    id: '/directory/teams',
+    matchId: '/directory/teams',
+    label: 'Teams',
+    icon: 'UsersRound',
+    href: buildUrl('/directory/teams'),
+  },
+  '/directory/users': {
+    id: '/directory/users',
+    matchId: '/directory/users',
+    label: 'Users',
+    icon: 'UserRound',
+    href: buildUrl('/directory/users'),
+  },
+  '/settings/general': {
+    id: '/settings/general',
+    matchId: '/settings/general',
+    label: 'Settings',
+    icon: 'Settings',
+    href: buildUrl('/settings/general'),
+  },
+};
+
+const defaultNavigationGroups: NavigationGroupConfig[] = [
+  {
+    id: 'main',
+    items: [{ id: '/' }, { id: '/docs/custom', visible: isCustomDocsEnabled() && customDocs.length > 0 }],
+  },
+  {
+    id: 'browse',
+    label: 'Browse',
+    items: [
+      { id: '/discover', visible: Boolean(defaultDiscoverTarget) },
+      { id: '/schemas/explorer' },
+      { id: '/schemas/fields', visible: isSSR() },
+    ],
+  },
+  {
+    id: 'organization',
+    label: 'Organization',
+    items: [{ id: '/directory/teams' }, { id: '/directory/users' }],
+  },
+  {
+    id: 'settings',
+    position: 'bottom',
+    items: [{ id: '/settings/general' }],
+  },
+];
+
+const isNavigationItemCurrent = (item: Pick<VerticalNavigationItem, 'href' | 'matchId' | 'match'>, pathname: string) => {
+  const matchId = item.matchId;
+
+  if (matchId === '/') {
+    const itemPath = new URL(item.href, Astro.url.origin).pathname;
+    return (
+      pathname === itemPath ||
+      (pathname.includes('/docs') && !pathname.includes('/docs/custom')) ||
+      pathname.includes('/architecture/') ||
+      pathname.includes('/visualiser') ||
+      (pathname.includes('/schemas') && !pathname.includes('/schemas/explorer') && !pathname.includes('/schemas/fields'))
+    );
+  }
+
+  if (matchId === '/schemas/explorer') {
+    return pathname.includes('/schemas/explorer') && !pathname.includes('/schemas/fields');
+  }
+
+  if (matchId === '/schemas/fields') {
+    return pathname.includes('/schemas/fields');
+  }
+
+  if (matchId === '/discover') {
+    return pathname === buildUrl('/discover', true) || pathname.endsWith('/discover') || pathname.includes('/discover/');
+  }
+
+  if (matchId === '/studio') {
+    return pathname.includes('/studio');
+  }
+
+  if (matchId === '/docs/custom') {
+    return pathname.includes('/docs/custom');
+  }
+
+  if (matchId === '/settings/general') {
+    return pathname.startsWith(buildUrl('/settings', true));
+  }
+
+  const configuredMatches = Array.isArray(item.match) ? item.match : item.match ? [item.match] : [];
+  if (configuredMatches.length > 0) {
+    return configuredMatches.some((match) => {
+      if (isExternalNavigationHref(match)) return false;
+
+      return pathname === buildUrl(match, true) || pathname.startsWith(buildUrl(match, true));
+    });
+  }
+
+  if (isExternalNavigationHref(item.href)) return false;
+
+  const itemPath = new URL(item.href, Astro.url.origin).pathname;
+  return pathname === itemPath;
+};
+
+const resolveNavigationItem = (item: NavigationItemConfig): VerticalNavigationItem | null => {
+  if (item.visible === false) return null;
+
+  const builtinId = navigationBuiltinAliases[item.id] || item.id;
+  const builtin = builtinNavigationItems[builtinId];
+  const href = item.href ? normalizeNavigationHref(item.href) : builtin?.href;
+
+  if (!href) return null;
+
+  const resolvedItem = {
+    id: item.id,
+    matchId: builtin?.matchId || item.id,
+    label: item.label || builtin?.label || item.id,
+    icon: item.icon || builtin?.icon || 'Circle',
+    href,
+    match: item.match,
+  };
+
+  return {
+    ...resolvedItem,
+    current: isNavigationItemCurrent(resolvedItem, currentPath),
+    target: isExternalNavigationHref(href) ? '_blank' : undefined,
+    rel: isExternalNavigationHref(href) ? 'noopener noreferrer' : undefined,
+    Icon: resolveLucideIcon(resolvedItem.icon),
+  };
+};
+
+const resolveNavigationGroups = (groups: NavigationGroupConfig[]) =>
+  groups
+    .filter((group) => group.visible !== false)
+    .map((group) => ({
+      id: group.id,
+      label: group.label,
+      position: group.position || 'top',
+      items: (group.items || []).map(resolveNavigationItem).filter((item): item is VerticalNavigationItem => Boolean(item)),
+    }))
+    .filter((group) => group.items.length > 0);
+
+const navigationGroups = resolveNavigationGroups(
+  Array.isArray(config.navigation?.groups) ? (config.navigation.groups as NavigationGroupConfig[]) : defaultNavigationGroups
+);
+const topNavigationGroups = navigationGroups.filter((group) => group.position !== 'bottom');
+const bottomNavigationGroups = navigationGroups.filter((group) => group.position === 'bottom');
+const clientNavigationItems = navigationGroups.flatMap((group) =>
+  group.items.map(({ id, href, matchId, match }) => ({
+    id,
+    href,
+    matchId,
+    match: normalizeNavigationMatch(match),
+  }))
+);
+const { title, description, showNestedSideBar = true, showHeader = true, reducedContentPadding = false } = Astro.props;
+
+const canPageBeEmbedded = isEmbedEnabled();
+const verticalNavAutoCollapsePaths = [buildUrl('/discover', true), buildUrl('/docs', true)];
+---
+
+<BaseLayout title={`EventCatalog | ${title}`} description={description} ogTitle={title}>
+  <Fragment slot="head">
+    <script is:inline define:vars={{ verticalNavAutoCollapsePaths }}>
+      (() => {
+        const verticalNavStorageKey = 'eventcatalog-vertical-nav-collapsed';
+        const routeShouldAutoCollapseVerticalNav = (pathname) =>
+          verticalNavAutoCollapsePaths.some((path) => pathname === path || pathname.startsWith(`${path}/`));
+
+        try {
+          const shouldAutoCollapse = routeShouldAutoCollapseVerticalNav(window.location.pathname);
+          if (shouldAutoCollapse) {
+            localStorage.setItem(verticalNavStorageKey, 'true');
+          }
+
+          const savedState = localStorage.getItem(verticalNavStorageKey);
+          const isCollapsed = shouldAutoCollapse ? true : savedState === null ? true : savedState === 'true';
+          document.documentElement.setAttribute('data-vertical-nav-collapsed', isCollapsed ? 'true' : 'false');
+        } catch (error) {
+          document.documentElement.setAttribute('data-vertical-nav-collapsed', 'true');
+        }
+      })();
+    </script>
+    <style is:global>
+      :root {
+        --ec-vertical-nav-width: 14rem;
+      }
+
+      :root[data-vertical-nav-collapsed='true'] {
+        --ec-vertical-nav-width: 3rem;
+      }
+
+      html,
+      body {
+        background-color: rgb(var(--ec-page-bg));
+      }
+
+      body {
+        min-height: 100vh;
+        min-height: 100dvh;
+      }
+
+      #eventcatalog-application {
+        min-height: 100vh;
+        min-height: 100dvh;
+        background-color: rgb(var(--ec-page-bg));
+        --ec-sidebar-panel-width: 17rem;
+        display: flex;
+        flex-direction: column;
+      }
+
+      .app-content-wrapper {
+        --ec-app-content-padding-left: 5rem;
+        --ec-app-content-padding-right: 5rem;
+        margin-left: auto;
+        margin-right: auto;
+        padding-left: var(--ec-app-content-padding-left);
+        padding-right: var(--ec-app-content-padding-right);
+      }
+      .app-content-wrapper--reduced-padding {
+        --ec-app-content-padding-left: 2rem;
+        --ec-app-content-padding-right: 2rem;
+      }
+      .app-shell {
+        min-height: calc(100vh - 4rem);
+        flex: 1;
+      }
+      .app-shell--rail-only {
+        margin-left: var(--ec-vertical-nav-width);
+      }
+      .app-shell--with-sidebar {
+        margin-left: calc(var(--ec-vertical-nav-width) + var(--ec-sidebar-panel-width));
+      }
+      .vertical-nav-rail {
+        width: var(--ec-vertical-nav-width);
+        border-right: 1px solid rgb(var(--ec-page-border));
+        background-color: rgb(var(--ec-page-bg));
+        box-shadow: 0 24px 44px -34px rgb(var(--ec-page-text) / 0.28);
+        overflow: hidden;
+      }
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail .nav-brand-text,
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail .nav-item-label,
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail .rail-section-label,
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail .nav-count-pill,
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail .nav-label,
+      .vertical-nav-rail[data-collapsed='true'] .nav-brand-text,
+      .vertical-nav-rail[data-collapsed='true'] .nav-item-label,
+      .vertical-nav-rail[data-collapsed='true'] .rail-section-label,
+      .vertical-nav-rail[data-collapsed='true'] .nav-count-pill,
+      .vertical-nav-rail[data-collapsed='true'] .nav-label {
+        display: none;
+      }
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail [data-role='nav-item'],
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail .nav-secondary-item,
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail #vertical-nav-toggle,
+      .vertical-nav-rail[data-collapsed='true'] [data-role='nav-item'],
+      .vertical-nav-rail[data-collapsed='true'] .nav-secondary-item,
+      .vertical-nav-rail[data-collapsed='true'] #vertical-nav-toggle {
+        justify-content: center;
+        width: 2.5rem;
+        height: 2.5rem;
+        padding: 0;
+      }
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail .nav-brand-link,
+      .vertical-nav-rail[data-collapsed='true'] .nav-brand-link {
+        justify-content: center;
+        width: 100%;
+        height: 3.75rem;
+        padding-left: 0;
+        padding-right: 0;
+      }
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail nav,
+      .vertical-nav-rail[data-collapsed='true'] nav {
+        align-items: center;
+        gap: 0.75rem;
+        padding-left: 0.25rem;
+        padding-right: 0.25rem;
+      }
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail .rail-divider,
+      .vertical-nav-rail[data-collapsed='true'] .rail-divider {
+        display: none;
+      }
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail nav > .mt-auto,
+      .vertical-nav-rail[data-collapsed='true'] nav > .mt-auto {
+        margin-top: auto !important;
+        padding-top: 0;
+      }
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail nav + div,
+      .vertical-nav-rail[data-collapsed='true'] nav + div {
+        border-top: 0;
+        display: flex;
+        justify-content: center;
+        padding: 0.75rem 0.25rem;
+      }
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail .nav-premium-icon,
+      .vertical-nav-rail[data-collapsed='true'] .nav-premium-icon {
+        margin-left: 0;
+      }
+      :root[data-vertical-nav-collapsed='true'] .vertical-nav-rail .nav-collapse-icon,
+      .vertical-nav-rail[data-collapsed='true'] .nav-collapse-icon {
+        transform: rotate(180deg);
+      }
+      .sidebar-panel {
+        width: var(--ec-sidebar-panel-width);
+        min-width: var(--ec-sidebar-panel-width);
+        height: 100vh;
+        border-right: 1px solid rgb(var(--ec-content-border));
+        background: rgb(var(--ec-rail-bg));
+        display: flex;
+        flex-direction: column;
+        position: fixed;
+        top: 0;
+        left: var(--ec-vertical-nav-width);
+        z-index: 20;
+        overflow-y: auto;
+      }
+      .content-panel {
+        min-width: 0;
+        flex: 1;
+        min-height: calc(100vh - 4rem);
+      }
+      .sidebar-transition {
+        transition-property: width, transform;
+        transition-duration: 300ms;
+        transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+      }
+      .tooltip {
+        visibility: hidden;
+        position: absolute;
+      }
+      .has-tooltip:hover .tooltip {
+        visibility: visible;
+        z-index: 100;
+      }
+
+      /* Hide anchor link by default */
+      .anchor-link {
+        display: inline-block;
+        width: 1em;
+        height: 1em;
+        margin-left: 0.5rem;
+        margin-top: 0.25rem;
+        background-image: url('data:image/svg+xml,%3Csvg%20width%3D%2216%22%20height%3D%2216%22%20viewBox%3D%220%200%2024%2024%22%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%3E%3Cpath%20fill%3D%22currentColor%22%20d%3D%22m12.11%2015.39-3.88%203.88a2.52%202.52%200%200%201-3.5%200%202.47%202.47%200%200%201%200-3.5l3.88-3.88a1%201%200%200%200-1.42-1.42l-3.88%203.89a4.48%204.48%200%200%200%206.33%206.33l3.89-3.88a1%201%200%201%200-1.42-1.42Zm8.58-12.08a4.49%204.49%200%200%200-6.33%200l-3.89%203.88a1%201%200%200%200%201.42%201.42l3.88-3.88a2.52%202.52%200%200%201%203.5%200%202.47%202.47%200%200%201%200%203.5l-3.88%203.88a1%201%200%201%200%201.42%201.42l3.88-3.89a4.49%204.49%200%200%200%200-6.33ZM8.83%2015.17a1%201%200%200%200%201.1.22%201%201%200%200%200%20.32-.22l4.92-4.92a1%201%200%200%200-1.42-1.42l-4.92%204.92a1%201%200%200%200%200%201.42Z%22/%3E%3C/svg%3E');
+        background-repeat: no-repeat;
+        background-position: center;
+        background-size: 1em 1em;
+        opacity: 0;
+        transition: opacity 0.2s ease-in-out;
+        text-decoration: none;
+        vertical-align: -2px;
+      }
+
+      /* Show icon on heading hover */
+      h1:hover .anchor-link,
+      h2:hover .anchor-link,
+      h3:hover .anchor-link,
+      h4:hover .anchor-link,
+      h5:hover .anchor-link,
+      h6:hover .anchor-link {
+        opacity: 1;
+      }
+
+      /* Show on keyboard focus */
+      .anchor-link:focus {
+        opacity: 1;
+        outline: none;
+      }
+    </style>
+  </Fragment>
+  {/* Load search data even when sidebar is hidden */}
+  <SearchDataLoader />
+  <main id="eventcatalog-application" class="relative">
+    {
+      showHeader && (
+        <div transition:persist="site-header">
+          <Header showNestedSideBar={showNestedSideBar} />
+        </div>
+      )
+    }
+    <div class={`app-shell ${showNestedSideBar ? 'app-shell--with-sidebar' : 'app-shell--rail-only'}`}>
+      <aside class="flex" id="eventcatalog-vertical-nav">
+        <div
+          id="vertical-nav-rail"
+          data-collapsed="true"
+          transition:persist="vertical-nav-rail"
+          class="vertical-nav-rail fixed top-0 left-0 flex flex-col h-screen z-30 transition-[width] duration-200"
+        >
+          <a
+            href={buildUrl(config.landingPage || '/')}
+            aria-label="Home"
+            class="nav-brand-link flex items-center gap-2.5 px-4 h-[3.75rem] border-b border-[rgb(var(--ec-sidebar-border)/0.7)] flex-shrink-0"
+          >
+            <img
+              src={config?.logo?.src ? buildUrl('/' + config.logo.src.replace(/^\/+/, ''), true) : buildUrl('/logo.png', true)}
+              alt={config?.logo?.alt || 'EventCatalog'}
+              class="w-6 h-6 flex-shrink-0"
+            />
+            <span class="nav-brand-text text-[15px] font-semibold text-[rgb(var(--ec-page-text))] tracking-tight">
+              {config?.logo?.text || config?.organizationName || 'EventCatalog'}
+            </span>
+          </a>
+
+          <nav class="flex flex-col flex-1 overflow-y-auto px-3 py-4 gap-1">
+            {
+              topNavigationGroups.map((group, groupIndex) => (
+                <Fragment>
+                  {groupIndex > 0 && <hr class="rail-divider my-3 border-t border-[rgb(var(--ec-sidebar-border)/0.7)]" />}
+
+                  {group.label && (
+                    <div class="rail-section-label px-3 pb-1 text-[0.65rem] font-semibold tracking-[0.18em] uppercase text-[rgb(var(--ec-sidebar-text)/0.5)]">
+                      {group.label}
+                    </div>
+                  )}
+
+                  {group.items.map((item) => (
+                    <a
+                      id={item.id}
+                      href={item.href}
+                      target={item.target}
+                      rel={item.rel}
+                      data-role="vertical-nav-item"
+                      aria-label={item.label}
+                      class={`flex items-center gap-3 px-3 py-2.5 rounded-xl border text-[13px] font-medium transition-all duration-150 ${
+                        item.current
+                          ? 'border-[rgb(var(--ec-accent)/0.2)] bg-[rgb(var(--ec-page-bg)/0.88)] text-[rgb(var(--ec-accent))] shadow-sm'
+                          : 'border-transparent text-[rgb(var(--ec-sidebar-text))] hover:border-[rgb(var(--ec-sidebar-border)/0.65)] hover:bg-[rgb(var(--ec-page-bg)/0.78)] hover:text-[rgb(var(--ec-page-text))]'
+                      }`}
+                      title={item.label}
+                    >
+                      <item.Icon className="h-4 w-4 flex-shrink-0" aria-hidden="true" />
+                      <span class="nav-item-label">{item.label}</span>
+                    </a>
+                  ))}
+                </Fragment>
+              ))
+            }
+
+            <div class="mt-auto pt-3">
+              {
+                bottomNavigationGroups.map((group) => (
+                  <Fragment>
+                    <hr class="rail-divider mb-3 border-t border-[rgb(var(--ec-sidebar-border)/0.7)]" />
+
+                    {group.label && (
+                      <div class="rail-section-label px-3 pb-1 text-[0.65rem] font-semibold tracking-[0.18em] uppercase text-[rgb(var(--ec-sidebar-text)/0.5)]">
+                        {group.label}
+                      </div>
+                    )}
+
+                    {group.items.map((item) => (
+                      <a
+                        id={item.id}
+                        href={item.href}
+                        target={item.target}
+                        rel={item.rel}
+                        data-role="vertical-nav-item"
+                        aria-label={item.label}
+                        class={`flex items-center gap-3 px-3 py-2.5 rounded-xl border text-[13px] font-medium transition-all duration-150 ${
+                          item.current
+                            ? 'border-[rgb(var(--ec-accent)/0.2)] bg-[rgb(var(--ec-page-bg)/0.88)] text-[rgb(var(--ec-accent))] shadow-sm'
+                            : 'border-transparent text-[rgb(var(--ec-sidebar-text))] hover:border-[rgb(var(--ec-sidebar-border)/0.65)] hover:bg-[rgb(var(--ec-page-bg)/0.78)] hover:text-[rgb(var(--ec-page-text))]'
+                        }`}
+                        title={item.label}
+                      >
+                        <item.Icon className="h-4 w-4 flex-shrink-0" aria-hidden="true" />
+                        <span class="nav-item-label">{item.label}</span>
+                      </a>
+                    ))}
+                  </Fragment>
+                ))
+              }
+            </div>
+          </nav>
+
+          <div class="border-t border-[rgb(var(--ec-sidebar-border)/0.7)] px-3 py-3 flex-shrink-0">
+            <button
+              id="vertical-nav-toggle"
+              type="button"
+              aria-label="Collapse sidebar"
+              class="flex items-center gap-3 px-3 py-2.5 rounded-xl border border-transparent text-[13px] font-medium text-[rgb(var(--ec-sidebar-text))] hover:border-[rgb(var(--ec-sidebar-border)/0.65)] hover:bg-[rgb(var(--ec-page-bg)/0.78)] hover:text-[rgb(var(--ec-page-text))] transition-all duration-150 w-full"
+            >
+              <LucideIcons.PanelLeftClose className="h-4 w-4 flex-shrink-0 nav-collapse-icon" aria-hidden="true" />
+              <span class="nav-label">Collapse</span>
+            </button>
+          </div>
+        </div>
+      </aside>
+      {
+        showNestedSideBar &&
+          (Astro.slots.has('sidebar-content') ? (
+            <aside id="sidebar" class="sidebar-panel sidebar-transition">
+              <slot name="sidebar-content" />
+            </aside>
+          ) : (
+            <SideNav id="sidebar" class={`sidebar-panel sidebar-transition`} />
+          ))
+      }
+      <main class="content-panel sidebar-transition w-full bg-[rgb(var(--ec-page-bg))]" id="content">
+        {
+          Astro.slots.has('sidebar-content') || !wrapContent ? (
+            <slot />
+          ) : (
+            <div class={`app-content-wrapper ${reducedContentPadding ? 'app-content-wrapper--reduced-padding' : ''}`}>
+              <slot />
+            </div>
+          )
+        }
+      </main>
+
+      <!-- Create a overlay that tells people to purchase backstage plugin if they want to embed the page -->
+      <div class="absolute inset-0 bg-black items-center justify-center z-50 hidden" id="embed-overlay">
+        <div class="text-white text-center space-y-4">
+          <div>
+            <h1 class="text-2xl font-bold">EventCatalog Backstage Integration</h1>
+            <p class="text-md text-red-500">Missing license key for backstage integration.</p>
+          </div>
+          <div>
+            <p class="text-sm text-gray-500">Please configure the backstage plugin to embed this page into Backstage.</p>
+            <a href="https://www.eventcatalog.dev/integrations/backstage" class="text-blue-500 text-xs"
+              >Configure backstage plugin &rarr;</a
+            >
+          </div>
+        </div>
+      </div>
+    </div>
+  </main>
+</BaseLayout>
+
+<ClientRouter />
+<script
+  define:vars={{
+    clientNavigationItems,
+    canPageBeEmbedded,
+    verticalNavAutoCollapsePaths,
+  }}
+>
+  const VERTICAL_NAV_STORAGE_KEY = 'eventcatalog-vertical-nav-collapsed';
+  const ACTIVE_NAV_CLASSES = [
+    'border-[rgb(var(--ec-accent)/0.2)]',
+    'bg-[rgb(var(--ec-page-bg)/0.88)]',
+    'text-[rgb(var(--ec-accent))]',
+    'shadow-sm',
+  ];
+  const INACTIVE_NAV_CLASSES = [
+    'border-transparent',
+    'text-[rgb(var(--ec-sidebar-text))]',
+    'hover:border-[rgb(var(--ec-sidebar-border)/0.65)]',
+    'hover:bg-[rgb(var(--ec-page-bg)/0.78)]',
+    'hover:text-[rgb(var(--ec-page-text))]',
+  ];
+
+  const isNavItemCurrent = (item, pathname) => {
+    const matchId = item?.matchId || item?.id;
+
+    if (matchId === '/') {
+      const targetPath = item?.href ? new URL(item.href, window.location.origin).pathname : '/';
+      return (
+        pathname === targetPath ||
+        (pathname.includes('/docs') && !pathname.includes('/docs/custom')) ||
+        pathname.includes('/architecture/') ||
+        pathname.includes('/visualiser') ||
+        (pathname.includes('/schemas') && !pathname.includes('/schemas/explorer') && !pathname.includes('/schemas/fields'))
+      );
+    }
+
+    if (matchId === '/schemas/explorer') {
+      return pathname.includes('/schemas/explorer') && !pathname.includes('/schemas/fields');
+    }
+
+    if (matchId === '/schemas/fields') {
+      return pathname.includes('/schemas/fields');
+    }
+
+    if (matchId === '/discover') {
+      return pathname.endsWith('/discover') || pathname.includes('/discover/');
+    }
+
+    if (matchId === '/studio') {
+      return pathname.includes('/studio');
+    }
+
+    if (matchId === '/docs/custom') {
+      return pathname.includes('/docs/custom');
+    }
+
+    if (matchId === '/settings/general') {
+      return pathname.includes('/settings');
+    }
+
+    const matches = Array.isArray(item?.match) ? item.match : item?.match ? [item.match] : [];
+    if (matches.length > 0) {
+      return matches.some((match) => {
+        if (/^https?:\/\//.test(match)) return false;
+
+        return pathname === match || pathname.startsWith(match);
+      });
+    }
+
+    if (item?.href) {
+      if (/^https?:\/\//.test(item.href)) return false;
+
+      const targetPath = new URL(item.href, window.location.origin).pathname;
+      return pathname === targetPath;
+    }
+
+    return false;
+  };
+
+  const syncNavItemStates = () => {
+    const pathname = window.location.pathname;
+    const navItems = document.querySelectorAll('[data-role="vertical-nav-item"]');
+
+    navItems.forEach((item) => {
+      const id = item.getAttribute('id');
+      const navigationItem = clientNavigationItems.find((navItem) => navItem.id === id);
+      const isCurrent = navigationItem ? isNavItemCurrent(navigationItem, pathname) : false;
+
+      if (isCurrent) {
+        item.classList.remove(...INACTIVE_NAV_CLASSES);
+        item.classList.add(...ACTIVE_NAV_CLASSES);
+      } else {
+        item.classList.remove(...ACTIVE_NAV_CLASSES);
+        item.classList.add(...INACTIVE_NAV_CLASSES);
+      }
+    });
+  };
+
+  const routeShouldAutoCollapseVerticalNav = (pathname) =>
+    verticalNavAutoCollapsePaths.some((path) => pathname === path || pathname.startsWith(`${path}/`));
+
+  const persistVerticalNavCollapsedState = (collapsed) => {
+    try {
+      localStorage.setItem(VERTICAL_NAV_STORAGE_KEY, String(collapsed));
+    } catch (error) {}
+  };
+
+  const getPersistedVerticalNavCollapsedState = () => {
+    if (routeShouldAutoCollapseVerticalNav(window.location.pathname)) {
+      persistVerticalNavCollapsedState(true);
+      return true;
+    }
+
+    try {
+      const savedState = localStorage.getItem(VERTICAL_NAV_STORAGE_KEY);
+      return savedState === null ? true : savedState === 'true';
+    } catch (error) {
+      return true;
+    }
+  };
+
+  const applyPersistedVerticalNavState = () => {
+    const isCollapsed = getPersistedVerticalNavCollapsedState();
+    document.documentElement.setAttribute('data-vertical-nav-collapsed', isCollapsed ? 'true' : 'false');
+
+    const verticalNavRail = document.getElementById('vertical-nav-rail');
+    if (verticalNavRail) {
+      verticalNavRail.setAttribute('data-collapsed', isCollapsed ? 'true' : 'false');
+    }
+  };
+
+  // Apply immediately when this script executes so transitions don't briefly re-open the rail.
+  applyPersistedVerticalNavState();
+
+  // Re-apply around Astro view transitions because the incoming document can momentarily drop the root attribute.
+  document.addEventListener('astro:before-preparation', applyPersistedVerticalNavState);
+  document.addEventListener('astro:after-swap', applyPersistedVerticalNavState);
+
+  // Listen for Astro transititions
+  document.addEventListener('astro:page-load', () => {
+    applyPersistedVerticalNavState();
+    document.dispatchEvent(new CustomEvent('contentLoaded'));
+  });
+
+  // Listen for DOM loaded
+  document.addEventListener('DOMContentLoaded', () => {
+    applyPersistedVerticalNavState();
+    document.dispatchEvent(new CustomEvent('contentLoaded'));
+  });
+
+  document.addEventListener('contentLoaded', () => {
+    // Users can add ?embed=true to the URL to hide the navigation
+    const urlSearchParams = new URLSearchParams(window.location.search);
+    const params = Object.fromEntries(urlSearchParams.entries());
+    const embeded = params.embed === 'true' ? true : false;
+    const content = document.getElementById('content');
+    const shell = document.querySelector('.app-shell');
+    const app = document.getElementById('eventcatalog-application');
+    const verticalNavRail = document.getElementById('vertical-nav-rail');
+    const verticalNavToggle = document.getElementById('vertical-nav-toggle');
+    const navToggleLabel = verticalNavToggle?.querySelector('.nav-label');
+    const collapseIcon = verticalNavToggle?.querySelector('.nav-collapse-icon');
+
+    const setVerticalNavCollapsedState = (collapsed) => {
+      if (!app || !verticalNavRail || !verticalNavToggle || !navToggleLabel) return;
+      const railTextElements = verticalNavRail.querySelectorAll(
+        '.nav-brand-text, .nav-item-label, .rail-section-label, .nav-count-pill, .nav-label'
+      );
+
+      document.documentElement.setAttribute('data-vertical-nav-collapsed', collapsed ? 'true' : 'false');
+      verticalNavRail.setAttribute('data-collapsed', collapsed ? 'true' : 'false');
+      verticalNavToggle.setAttribute('aria-label', collapsed ? 'Expand sidebar' : 'Collapse sidebar');
+      verticalNavToggle.setAttribute('aria-expanded', collapsed ? 'false' : 'true');
+      navToggleLabel.textContent = collapsed ? 'Expand' : 'Collapse';
+      railTextElements.forEach((element) => {
+        if (collapsed) {
+          element.setAttribute('hidden', '');
+        } else {
+          element.removeAttribute('hidden');
+        }
+      });
+
+      if (collapseIcon) {
+        collapseIcon.setAttribute('title', collapsed ? 'Expand sidebar' : 'Collapse sidebar');
+      }
+    };
+
+    if (embeded && !canPageBeEmbedded) {
+      const overlay = document.getElementById('embed-overlay');
+      overlay.style.display = 'flex';
+      return;
+    }
+
+    if (embeded) {
+      const elementsToHide = [
+        'eventcatalog-vertical-nav',
+        'eventcatalog-header',
+        'eventcatalog-header-spacer',
+        'visualiser-footer',
+        // /discover page elements
+        'discover-collection-tabs',
+        'discover-title',
+      ];
+
+      elementsToHide.forEach((id) => {
+        const element = document.getElementById(id);
+        if (element) element.style.display = 'none';
+      });
+
+      document.body.style.overflow = '';
+      app.style.overflow = '';
+      if (shell) shell.style.marginLeft = '0';
+      return;
+    }
+
+    if (shell) {
+      shell.style.marginLeft = '';
+    }
+
+    setVerticalNavCollapsedState(getPersistedVerticalNavCollapsedState());
+
+    syncNavItemStates();
+
+    if (verticalNavToggle) {
+      verticalNavToggle.onclick = () => {
+        const isCollapsed = verticalNavRail?.getAttribute('data-collapsed') === 'true';
+        const nextState = !isCollapsed;
+
+        setVerticalNavCollapsedState(nextState);
+        persistVerticalNavCollapsedState(nextState);
+      };
+    }
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/layouts/VisualiserLayout.astro b/packages/core/eventcatalog/src/layouts/VisualiserLayout.astro
new file mode 100644
index 000000000..5208ec804
--- /dev/null
+++ b/packages/core/eventcatalog/src/layouts/VisualiserLayout.astro
@@ -0,0 +1,238 @@
+---
+import { getCommands } from '@utils/collections/commands';
+import { getDomains } from '@utils/collections/domains';
+import { getEvents } from '@utils/collections/events';
+import { getFlows } from '@utils/collections/flows';
+import { getQueries } from '@utils/collections/queries';
+import { getServices } from '@utils/collections/services';
+import VerticalSideBarLayout from './VerticalSideBarLayout.astro';
+
+const [services, events, commands, queries, domains, flows] = await Promise.all([
+  getServices(),
+  getEvents(),
+  getCommands(),
+  getQueries(),
+  getDomains(),
+  getFlows(),
+]);
+
+// @ts-ignore for large catalogs https://github.com/event-catalog/eventcatalog/issues/552
+const navItems = [...domains, ...services, ...events, ...commands, ...queries, ...flows];
+
+const navigation = navItems
+  .filter((item) => item.data.version === item.data.latestVersion)
+  .reduce((acc, item) => {
+    //  @ts-ignore
+    const group = acc[item.collection] || [];
+
+    return {
+      ...acc,
+      [item.collection]: [...group, item],
+    };
+  }, {}) as any;
+
+const currentPath = Astro.url.pathname;
+const { title, description } = Astro.props;
+
+const getColor = (collection: string) => {
+  switch (collection) {
+    case 'services':
+      return 'green';
+    case 'events':
+      return 'red';
+    case 'queries':
+      return 'green';
+    case 'commands':
+      return 'yellow';
+    case 'domains':
+      return 'blue';
+    default:
+      return 'gray';
+  }
+};
+---
+
+<VerticalSideBarLayout title={title} description={description}>
+  <div class="visualiser-full-bleed">
+    <div>
+      <!-- <div class="hidden md:block">
+        <aside class="sm:fixed grow w-56 xl:w-[19em] overflow-y-auto h-full z-10 pb-20" id="visualiser-navigation">
+          <div class="w-full">
+            <div class="sticky top-0 z-10 h-8 pointer-events-none -mt-7">
+              <div class="h-full bg-gradient-to-b from-white to-transparent"></div>
+            </div>
+            {
+              Object.keys(navigation).map((key: any) => {
+                const items = navigation[key]
+                  .map((item: any) => {
+                    const isCurrent = currentPath.includes(`${item.collection}/${item.data.id}/${item.data.version}`);
+                    const isLatest = item.data.version === item.data.latestVersion;
+                    if (!isLatest) return null;
+                    return {
+                      label: item.data.name,
+                      version: item.data.version,
+                      color: getColor(item.collection),
+                      href: buildUrl(`/visualiser/${item.collection}/${item.data.id}/${item.data.version}`),
+                      active: isCurrent,
+                    };
+                  })
+                  .filter((n: any) => n !== null);
+                return (
+                  <BasicList
+                    title={`${key} (${navigation[key].length})`}
+                    items={items}
+                    emptyMessage="Nothing to show"
+                    color="gray"
+                    client:load
+                  />
+                );
+              })
+            }
+          </div>
+        </aside>
+      </div> -->
+
+      <main class="flex-1 h-full w-full relative">
+        <!-- <button
+          id="fullscreen-toggle"
+          class="absolute top-[1em] z-40 left-5 bg-white hover:bg-gray-100/50 border border-gray-200 hover:text-primary text-gray-800 font-semibold py-2 px-4 rounded-lg transition duration-300 ease-in-out flex items-center space-x-2 focus:outline-hidden focus:ring-2 focus:ring-blue-400 focus:ring-opacity-75"
+        >
+          <svg xmlns="http://www.w3.org/2000/svg" class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              stroke-width="2"
+              d="M4 8V4m0 0h4M4 4l5 5m11-1V4m0 0h-4m4 0l-5 5M4 16v4m0 0h4m-4 0l5-5m11 5l-5-5m5 5v-4m0 4h-4"></path>
+          </svg>
+          <span>Toggle Fullscreen</span>
+        </button> -->
+        <slot />
+      </main>
+    </div>
+  </div>
+</VerticalSideBarLayout>
+
+<script>
+  function setupSidebarToggle() {
+    const sidebar = document.getElementById('visualiser-navigation');
+    const toggleButton = document.getElementById('fullscreen-toggle');
+    const eventCatalogHeader = document.getElementById('eventcatalog-header');
+    const eventCatalogHeaderSpacer = document.getElementById('eventcatalog-header-spacer');
+    let isSidebarVisible = true;
+
+    if (!sidebar || !toggleButton) return;
+
+    function toggleSidebar() {
+      isSidebarVisible = !isSidebarVisible;
+      if (sidebar) sidebar.style.display = isSidebarVisible ? 'block' : 'none';
+      if (eventCatalogHeader) eventCatalogHeader.style.display = isSidebarVisible ? 'block' : 'none';
+      if (eventCatalogHeaderSpacer) eventCatalogHeaderSpacer.style.display = isSidebarVisible ? 'block' : 'none';
+    }
+
+    // Remove existing event listener if it exists
+    toggleButton.removeEventListener('click', toggleSidebar);
+
+    // Add the event listener
+    toggleButton.addEventListener('click', toggleSidebar);
+  }
+
+  // Run the setup immediately
+  setupSidebarToggle();
+
+  // Re-run the setup after each navigation
+  document.addEventListener('astro:page-load', setupSidebarToggle);
+</script>
+
+<!--
+  Bridge Astro's view-transition router onto `window` so the standalone
+  visualiser package (which can't import `astro:*`) can trigger soft, animated
+  client navigations instead of hard page reloads. Used by node "drill-in"
+  clicks (e.g. a system node on the System Diagram -> that system's Map).
+-->
+<script>
+  import { navigate } from 'astro:transitions/client';
+
+  function bridgeNavigate() {
+    // @ts-ignore - intentional global bridge for the decoupled visualiser island
+    window.__ecNavigate = (url: string) => navigate(url);
+  }
+
+  bridgeNavigate();
+  document.addEventListener('astro:page-load', bridgeNavigate);
+</script>
+
+<style is:global>
+  /*
+   * "Drill into detail" transition for the visualiser graph container.
+   *
+   * Both the System Diagram and a system's Map render their graph inside
+   * a portal tagged with `transition:name="visualiser-graph"`. When navigating
+   * between them, Astro morphs that shared container: the outgoing graph fades
+   * and scales back, the incoming graph fades and scales up into place — reading
+   * as descending one level deeper rather than a flat cross-fade.
+   */
+  @keyframes ec-visualiser-drill-out {
+    from {
+      opacity: 1;
+      transform: scale(1);
+    }
+    to {
+      opacity: 0;
+      transform: scale(1.04);
+    }
+  }
+
+  @keyframes ec-visualiser-drill-in {
+    from {
+      opacity: 0;
+      transform: scale(0.96);
+    }
+    to {
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+
+  ::view-transition-old(visualiser-graph) {
+    animation: ec-visualiser-drill-out 0.28s ease both;
+  }
+
+  ::view-transition-new(visualiser-graph) {
+    animation: ec-visualiser-drill-in 0.28s ease both;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    ::view-transition-old(visualiser-graph),
+    ::view-transition-new(visualiser-graph) {
+      animation-duration: 0.01ms;
+    }
+  }
+</style>
+
+<style>
+  .visualiser-full-bleed {
+    margin-left: calc(var(--ec-app-content-padding-left, 5rem) * -1);
+    margin-right: calc(var(--ec-app-content-padding-right, 5rem) * -1);
+  }
+
+  #visualiser-navigation {
+    transform: translateX(0);
+  }
+</style>
+
+<style>
+  #visualiser-navigation {
+    transition:
+      transform 0.3s ease-in-out,
+      opacity 0.3s ease-in-out;
+    transform: translateX(0);
+    opacity: 1;
+  }
+  #visualiser-navigation.hidden {
+    transform: translateX(-100%);
+    opacity: 0;
+  }
+  main {
+    transition: margin-left 0.3s ease-in-out;
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/pages/.well-known/api-catalog.ts b/packages/core/eventcatalog/src/pages/.well-known/api-catalog.ts
new file mode 100644
index 000000000..04c313902
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/.well-known/api-catalog.ts
@@ -0,0 +1,191 @@
+import type { APIRoute } from 'astro';
+import yaml from 'js-yaml';
+import { getServices, getSpecificationsForService } from '@utils/collections/services';
+import { getDomains, getSpecificationsForDomain } from '@utils/collections/domains';
+import type { ProcessedSpecification } from '@utils/collections/util';
+import { buildUrl } from '@utils/url-builder';
+import { readResourceFile } from '@utils/resource-files';
+import { isEventCatalogMCPEnabled } from '@utils/feature';
+
+const RFC_9727_PROFILE = 'https://www.rfc-editor.org/info/rfc9727';
+const LINKSET_CONTENT_TYPE = `application/linkset+json; profile="${RFC_9727_PROFILE}"`;
+
+type LinkTarget = {
+  href: string;
+  type?: string;
+  title?: string;
+};
+
+type ApiCatalogEntry = {
+  anchor: string;
+  'service-desc': LinkTarget[];
+  'service-doc'?: LinkTarget[];
+};
+
+type ApiCatalogResource = Awaited<ReturnType<typeof getServices>>[number] | Awaited<ReturnType<typeof getDomains>>[number];
+
+const absoluteUrl = (request: Request, pathOrUrl: string) => new URL(pathOrUrl, request.url).toString();
+
+const getSpecificationMediaType = (specification: ProcessedSpecification) => {
+  const extension = specification.filename.split('.').pop()?.toLowerCase();
+
+  if (specification.type === 'graphql') return 'application/graphql';
+  if (extension === 'json') return 'application/json';
+  if (extension === 'yaml' || extension === 'yml') return 'application/yaml';
+
+  return 'text/plain';
+};
+
+const getSpecificationIdentifier = (specification: ProcessedSpecification) => {
+  return `${specification.type}-${Buffer.from(specification.path).toString('base64url')}`;
+};
+
+const parseSpecification = (rawSpecification: string, path: string): unknown => {
+  if (path.endsWith('.json')) {
+    return JSON.parse(rawSpecification);
+  }
+
+  return yaml.load(rawSpecification);
+};
+
+const toHttpUrl = (value: unknown): string | undefined => {
+  if (typeof value !== 'string' || value.trim() === '') return undefined;
+  if (!/^https?:\/\//i.test(value)) return undefined;
+
+  try {
+    const url = new URL(value);
+    if (url.protocol === 'http:' || url.protocol === 'https:') {
+      return url.toString();
+    }
+  } catch {
+    return undefined;
+  }
+
+  return undefined;
+};
+
+const getSpecificationsForResource = (resource: ApiCatalogResource) => {
+  if (resource.collection === 'domains') {
+    return getSpecificationsForDomain(resource);
+  }
+
+  return getSpecificationsForService(resource);
+};
+
+const getEndpointFromSpecification = (request: Request, resource: ApiCatalogResource) => {
+  const specifications = getSpecificationsForResource(resource);
+
+  for (const specification of specifications) {
+    if (specification.type !== 'openapi' && specification.type !== 'asyncapi') continue;
+
+    const rawSpecification = readResourceFile(resource, specification.path);
+    if (!rawSpecification) continue;
+
+    try {
+      const parsedSpecification = parseSpecification(rawSpecification, specification.path) as any;
+
+      if (specification.type === 'openapi') {
+        const serverUrl = parsedSpecification?.servers?.find((server: any) => typeof server?.url === 'string')?.url;
+        const endpoint = toHttpUrl(serverUrl);
+        if (endpoint) return endpoint;
+      }
+
+      if (specification.type === 'asyncapi') {
+        const servers = Object.values(parsedSpecification?.servers ?? {}) as any[];
+        const serverUrl = servers.find((server) => typeof server?.url === 'string')?.url;
+        const endpoint = toHttpUrl(serverUrl);
+        if (endpoint) return endpoint;
+      }
+    } catch {
+      // Invalid or unsupported specifications should not prevent catalog discovery.
+    }
+  }
+};
+
+const getResourceDocumentationUrl = (request: Request, resource: ApiCatalogResource) => {
+  return absoluteUrl(request, buildUrl(`/docs/${resource.collection}/${resource.data.id}/${resource.data.version}`, true));
+};
+
+const getResourceMarkdownUrl = (request: Request, resource: ApiCatalogResource) => {
+  return absoluteUrl(request, buildUrl(`/docs/${resource.collection}/${resource.data.id}/${resource.data.version}.md`, true));
+};
+
+const toApiCatalogEntry = (request: Request, resource: ApiCatalogResource): ApiCatalogEntry | null => {
+  const specifications = getSpecificationsForResource(resource);
+  if (specifications.length === 0) return null;
+
+  const resourceDocumentationUrl = getResourceDocumentationUrl(request, resource);
+  const resourceMarkdownUrl = getResourceMarkdownUrl(request, resource);
+
+  return {
+    anchor: getEndpointFromSpecification(request, resource) ?? resourceDocumentationUrl,
+    'service-desc': specifications.map((specification) => ({
+      href: absoluteUrl(
+        request,
+        buildUrl(
+          `/api-catalog/specifications/${resource.collection}/${resource.data.id}/${resource.data.version}/${getSpecificationIdentifier(specification)}`,
+          true
+        )
+      ),
+      type: getSpecificationMediaType(specification),
+      title: `${resource.data.name || resource.data.id} ${specification.name}`,
+    })),
+    'service-doc': [
+      {
+        href: resourceMarkdownUrl,
+        type: 'text/markdown',
+        title: `${resource.data.name || resource.data.id} documentation`,
+      },
+      {
+        href: resourceDocumentationUrl,
+        type: 'text/html',
+        title: `${resource.data.name || resource.data.id} documentation`,
+      },
+    ],
+  };
+};
+
+const getMcpCatalogEntry = (request: Request): ApiCatalogEntry | null => {
+  if (!isEventCatalogMCPEnabled()) return null;
+
+  const mcpUrl = absoluteUrl(request, buildUrl('/docs/mcp', true));
+
+  return {
+    anchor: mcpUrl,
+    'service-desc': [
+      {
+        href: mcpUrl,
+        type: 'application/json',
+        title: 'EventCatalog MCP Server',
+      },
+    ],
+  };
+};
+
+export const GET: APIRoute = async ({ request }) => {
+  const [services, domains] = await Promise.all([getServices({ getAllVersions: true }), getDomains({ getAllVersions: true })]);
+  const resources = [...services, ...domains];
+  const linkset = resources
+    .map((resource) => toApiCatalogEntry(request, resource))
+    .filter((entry): entry is ApiCatalogEntry => entry !== null);
+
+  const mcpEntry = getMcpCatalogEntry(request);
+  if (mcpEntry) {
+    linkset.push(mcpEntry);
+  }
+
+  return new Response(JSON.stringify({ linkset }, null, 2), {
+    headers: {
+      'Content-Type': LINKSET_CONTENT_TYPE,
+    },
+  });
+};
+
+export const HEAD: APIRoute = async ({ request }) => {
+  return new Response(null, {
+    headers: {
+      'Content-Type': LINKSET_CONTENT_TYPE,
+      Link: `<${absoluteUrl(request, buildUrl('/.well-known/api-catalog', true))}>; rel="api-catalog"`,
+    },
+  });
+};
diff --git a/packages/core/eventcatalog/src/pages/_index.astro b/packages/core/eventcatalog/src/pages/_index.astro
new file mode 100644
index 000000000..f00e8b0a1
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/_index.astro
@@ -0,0 +1,358 @@
+---
+import { buildUrl } from '@utils/url-builder';
+import config from '@config';
+
+import { getCollection } from 'astro:content';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { BookOpenText, Workflow, TableProperties, BookUser, Code2, FileJson, ArrowUpRight, ArrowRight, Plus } from 'lucide-react';
+
+const { showNestedSideBar = true } = Astro.props;
+
+// Lightweight data fetch: only raw collections, no hydration.
+const [allDomains, allServices, allEvents, allCommands, allQueries, allFlows] = await Promise.all([
+  getCollection('domains'),
+  getCollection('services'),
+  getCollection('events'),
+  getCollection('commands'),
+  getCollection('queries'),
+  getCollection('flows'),
+]);
+
+const isCurrentVersion = (item: { data: { hidden?: boolean }; filePath?: string }) =>
+  item.data.hidden !== true && !item.filePath?.includes('versioned');
+
+const domains = allDomains.filter(isCurrentVersion);
+const services = allServices.filter(isCurrentVersion);
+const events = allEvents.filter(isCurrentVersion);
+const commands = allCommands.filter(isCurrentVersion);
+const queries = allQueries.filter(isCurrentVersion);
+const messages = [...events, ...commands, ...queries];
+const flows = allFlows.filter(isCurrentVersion);
+
+const getDefaultUrl = (route: string, defaultValue: string) => {
+  if (domains.length > 0) return buildUrl(`/${route}/domains/${domains[0].data.id}/${domains[0].data.version}`);
+  if (services.length > 0) return buildUrl(`/${route}/services/${services[0].data.id}/${services[0].data.version}`);
+  if (flows.length > 0) return buildUrl(`/${route}/flows/${flows[0].data.id}/${flows[0].data.version}`);
+  return buildUrl(defaultValue);
+};
+
+interface StatTile {
+  label: string;
+  count: number;
+  href: string;
+  emptyHref: string;
+  tone: string; // CSS color expression — drives accent rail + count gradient
+}
+
+const statTiles: StatTile[] = [
+  {
+    label: 'Domains',
+    count: domains.length,
+    href: buildUrl('/discover/domains'),
+    emptyHref: 'https://www.eventcatalog.dev/docs/domains',
+    tone: '250 204 21', // amber-400
+  },
+  {
+    label: 'Services',
+    count: services.length,
+    href: buildUrl('/discover/services'),
+    emptyHref: 'https://www.eventcatalog.dev/docs/services',
+    tone: '244 114 182', // pink-400
+  },
+  {
+    label: 'Messages',
+    count: messages.length,
+    href: buildUrl('/discover/events'),
+    emptyHref: 'https://www.eventcatalog.dev/docs/messages',
+    tone: '167 139 250', // violet-400
+  },
+  {
+    label: 'Flows',
+    count: flows.length,
+    href: buildUrl('/discover/flows'),
+    emptyHref: 'https://www.eventcatalog.dev/docs/flows',
+    tone: '94 234 212', // teal-300
+  },
+];
+
+interface ExploreCard {
+  title: string;
+  description: string;
+  icon: any;
+  href: string;
+  external?: boolean;
+  /** When true, renders as the lead "feature" card with extra width and CTA styling. */
+  feature?: boolean;
+  tone: string; // RGB triple for the icon tile
+}
+
+const exploreCards: ExploreCard[] = [
+  {
+    title: 'Documentation',
+    description: 'Browse every domain, service, message, and flow your teams have published.',
+    icon: BookOpenText,
+    href: getDefaultUrl('docs', 'domains'),
+    feature: true,
+    tone: '96 165 250', // blue-400
+  },
+  {
+    title: 'Visualizer',
+    description: 'See how services connect — message flows across your architecture.',
+    icon: Workflow,
+    href: getDefaultUrl('visualiser', 'domains'),
+    tone: '167 139 250', // violet-400
+  },
+  {
+    title: 'Discover',
+    description: 'Search every event, service, agent, and team across the catalog.',
+    icon: TableProperties,
+    href: buildUrl('/discover/events'),
+    tone: '94 234 212', // teal-300
+  },
+  {
+    title: 'Schema Explorer',
+    description: 'Track schema evolution, compare versions, and catch breaking changes.',
+    icon: FileJson,
+    href: buildUrl('/schemas/explorer'),
+    tone: '250 204 21', // amber-400
+  },
+  {
+    title: 'Team Directory',
+    description: 'Find owners, on-call contacts, and the team behind every service.',
+    icon: BookUser,
+    href: buildUrl('/directory/users'),
+    tone: '251 146 60', // orange-400
+  },
+  {
+    title: 'API & SDK',
+    description: 'Programmatic access — query and manage your catalog with a typed SDK.',
+    icon: Code2,
+    href: 'https://www.eventcatalog.dev/docs/sdk',
+    external: true,
+    tone: '129 140 248', // indigo-400
+  },
+];
+---
+
+<VerticalSideBarLayout title="EventCatalog" showNestedSideBar={showNestedSideBar}>
+  <div class="ec-home min-h-screen">
+    <!-- Hero -->
+    <header class="ec-hero">
+      <div class="text-[11px] font-semibold uppercase tracking-[0.18em] text-[rgb(var(--ec-accent))]">Catalog</div>
+      <div class="mt-3 flex flex-col gap-3 md:flex-row md:items-end md:justify-between">
+        <div>
+          <h1 class="text-[28px] font-semibold leading-[1.1] tracking-tight text-[rgb(var(--ec-page-text))] md:text-[32px]">
+            {config?.organizationName || 'EventCatalog'}
+          </h1>
+          <p class="mt-2 max-w-2xl text-[14px] leading-relaxed text-[rgb(var(--ec-page-text-muted))]">
+            {config.tagline || 'Explore and understand your event-driven architecture.'}
+          </p>
+        </div>
+        <div class="flex items-center gap-2">
+          <a
+            href={getDefaultUrl('docs', 'domains')}
+            class="ec-btn-primary inline-flex items-center gap-1.5 rounded-md bg-[rgb(var(--ec-page-bg))] border border-[rgb(var(--ec-page-border))] px-3.5 py-2 text-[12.5px] font-semibold text-[rgb(var(--ec-page-text-muted))] transition-colors hover:border-[rgb(var(--ec-accent)/0.5)] hover:text-[rgb(var(--ec-accent))]"
+          >
+            Explore Catalog
+            <ArrowRight className="h-3.5 w-3.5" />
+          </a>
+        </div>
+      </div>
+    </header>
+
+    <div class="ec-divider"></div>
+
+    <!-- Stat strip -->
+    <section class="ec-stats">
+      {
+        statTiles.map((tile) => (
+          <a
+            href={tile.count > 0 ? tile.href : tile.emptyHref}
+            target={tile.count === 0 ? '_blank' : undefined}
+            rel={tile.count === 0 ? 'noreferrer' : undefined}
+            class="ec-stat group"
+            style={`--tone: ${tile.tone};`}
+          >
+            <div class="flex items-baseline justify-between gap-2">
+              <span class="text-[11px] font-medium uppercase tracking-[0.14em] text-[rgb(var(--tone))]">{tile.label}</span>
+              {tile.count > 0 ? (
+                <ArrowUpRight className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))] transition-transform duration-200 group-hover:-translate-y-0.5 group-hover:translate-x-0.5 group-hover:text-[rgb(var(--ec-accent))]" />
+              ) : (
+                <Plus className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))] transition-colors group-hover:text-[rgb(var(--ec-accent))]" />
+              )}
+            </div>
+            <div class="mt-3 flex items-baseline gap-2">
+              <span class="font-mono text-[34px] font-semibold leading-none tracking-tight text-[rgb(var(--ec-page-text))]">
+                {tile.count}
+              </span>
+              {tile.count === 0 && <span class="text-[12px] text-[rgb(var(--ec-page-text-muted))]">— add some</span>}
+            </div>
+          </a>
+        ))
+      }
+    </section>
+
+    <!-- Eyebrow + Explore grid -->
+    <section class="mt-12">
+      <div class="ec-section-eyebrow">
+        <span class="text-[11px] font-semibold uppercase tracking-[0.18em] text-[rgb(var(--ec-accent))]">Explore</span>
+        <span class="ec-section-rule"></span>
+        <span class="font-mono text-[11px] text-[rgb(var(--ec-page-text-muted)/0.7)]">{exploreCards.length} sections</span>
+      </div>
+
+      <div class="ec-explore-grid mt-4">
+        {
+          exploreCards.map((card) => (
+            <a
+              href={card.href}
+              target={card.external ? '_blank' : undefined}
+              rel={card.external ? 'noreferrer' : undefined}
+              class:list={['ec-card group', card.feature ? 'ec-card--feature' : '']}
+              style={`--tone: ${card.tone};`}
+            >
+              <div class="flex items-start justify-between gap-3">
+                <div class="ec-card-icon">
+                  <card.icon className="h-4 w-4" />
+                </div>
+                <ArrowUpRight className="h-3.5 w-3.5 text-[rgb(var(--ec-page-text-muted))] transition-transform duration-200 group-hover:-translate-y-0.5 group-hover:translate-x-0.5 group-hover:text-[rgb(var(--ec-accent))]" />
+              </div>
+              <h3 class="mt-4 text-[15px] font-semibold tracking-tight text-[rgb(var(--ec-page-text))]">{card.title}</h3>
+              <p class="mt-1.5 text-[13px] leading-relaxed text-[rgb(var(--ec-page-text-muted))]">{card.description}</p>
+            </a>
+          ))
+        }
+      </div>
+    </section>
+  </div>
+</VerticalSideBarLayout>
+
+<style is:global>
+  .ec-home {
+    /* Negate the layout wrapper's horizontal padding so the homepage controls its own. */
+    margin-left: calc(var(--ec-app-content-padding-left, 5rem) * -1);
+    margin-right: calc(var(--ec-app-content-padding-right, 5rem) * -1);
+    padding: 2rem 2rem 0;
+  }
+  .ec-hero {
+    padding-bottom: 1.5rem;
+  }
+  .ec-divider {
+    height: 1px;
+    background: linear-gradient(
+      to right,
+      transparent,
+      rgb(var(--ec-page-border)) 12%,
+      rgb(var(--ec-page-border)) 88%,
+      transparent
+    );
+    margin: 0.25rem 0 1.5rem;
+  }
+  .ec-stats {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 0.75rem;
+  }
+  @media (min-width: 768px) {
+    .ec-stats {
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+    }
+  }
+  .ec-stat {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    border: 1px solid rgb(var(--ec-page-border));
+    border-radius: 0.75rem;
+    background:
+      radial-gradient(80% 100% at 0% 0%, rgb(var(--tone) / 0.05), transparent 60%), rgb(var(--ec-card-bg, var(--ec-page-bg)));
+    padding: 1rem 1.1rem 1.1rem;
+    transition:
+      border-color 200ms,
+      transform 200ms,
+      box-shadow 200ms;
+    text-decoration: none;
+  }
+  .ec-stat:hover {
+    border-color: rgb(var(--ec-accent) / 0.5);
+    transform: translateY(-1px);
+  }
+
+  .ec-section-eyebrow {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+  }
+  .ec-section-rule {
+    flex: 1;
+    height: 1px;
+    background: linear-gradient(to right, rgb(var(--ec-accent) / 0.4), rgb(var(--ec-page-border)) 30%);
+  }
+
+  /* Explore grid: bordered cells with breathing room between them. */
+  .ec-explore-grid {
+    display: grid;
+    grid-template-columns: repeat(1, minmax(0, 1fr));
+    gap: 1rem;
+  }
+  @media (min-width: 640px) {
+    .ec-explore-grid {
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+  }
+  @media (min-width: 1024px) {
+    .ec-explore-grid {
+      grid-template-columns: repeat(3, minmax(0, 1fr));
+    }
+  }
+
+  .ec-card {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    padding: 1.5rem 1.5rem 1.4rem;
+    text-decoration: none;
+    border: 1px solid rgb(var(--ec-page-border));
+    border-radius: 0.875rem;
+    background: rgb(var(--ec-card-bg, var(--ec-page-bg)));
+    transition:
+      background 200ms,
+      border-color 200ms;
+    min-height: 9.5rem;
+  }
+  .ec-card:hover {
+    background: rgb(var(--ec-page-bg) / 0.4);
+    border-color: rgb(var(--ec-accent) / 0.5);
+  }
+
+  .ec-card--feature {
+    background:
+      radial-gradient(60% 90% at 0% 0%, rgb(var(--tone) / 0.07), transparent 60%), rgb(var(--ec-card-bg, var(--ec-page-bg)));
+  }
+  .ec-card--feature:hover {
+    background: radial-gradient(60% 90% at 0% 0%, rgb(var(--ec-accent) / 0.12), transparent 60%), rgb(var(--ec-page-bg) / 0.4);
+  }
+
+  .ec-card-icon {
+    display: inline-flex;
+    height: 2.25rem;
+    width: 2.25rem;
+    align-items: center;
+    justify-content: center;
+    border-radius: 0.5rem;
+    background: rgb(var(--tone) / 0.12);
+    color: rgb(var(--tone));
+    transition:
+      background 200ms,
+      color 200ms;
+  }
+  .ec-card:hover .ec-card-icon {
+    background: rgb(var(--ec-accent) / 0.2);
+    color: rgb(var(--ec-accent));
+  }
+  .ec-card--feature .ec-card-icon {
+    height: 2.5rem;
+    width: 2.5rem;
+    border-radius: 0.625rem;
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/pages/api-catalog/specifications/[collection]/[id]/[version]/[specification].ts b/packages/core/eventcatalog/src/pages/api-catalog/specifications/[collection]/[id]/[version]/[specification].ts
new file mode 100644
index 000000000..e53a8c109
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/api-catalog/specifications/[collection]/[id]/[version]/[specification].ts
@@ -0,0 +1,109 @@
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import { getSpecificationsForDomain } from '@utils/collections/domains';
+import { getSpecificationsForService } from '@utils/collections/services';
+import type { ProcessedSpecification } from '@utils/collections/util';
+import { readResourceFile } from '@utils/resource-files';
+
+type SupportedCollection = 'domains' | 'services';
+
+const isSupportedCollection = (collection: string | undefined): collection is SupportedCollection => {
+  return collection === 'domains' || collection === 'services';
+};
+
+const getSpecificationMediaType = (specification: ProcessedSpecification) => {
+  const extension = specification.filename.split('.').pop()?.toLowerCase();
+
+  if (specification.type === 'graphql') return 'application/graphql';
+  if (extension === 'json') return 'application/json';
+  if (extension === 'yaml' || extension === 'yml') return 'application/yaml';
+
+  return 'text/plain';
+};
+
+const getSpecificationIdentifier = (specification: ProcessedSpecification) => {
+  return `${specification.type}-${Buffer.from(specification.path).toString('base64url')}`;
+};
+
+const getSpecificationsForResource = (
+  resource:
+    | Awaited<ReturnType<typeof getCollection<'services'>>>[number]
+    | Awaited<ReturnType<typeof getCollection<'domains'>>>[number]
+) => {
+  if (resource.collection === 'domains') {
+    return getSpecificationsForDomain(resource);
+  }
+
+  return getSpecificationsForService(resource);
+};
+
+export async function getStaticPaths() {
+  const [services, domains] = await Promise.all([getCollection('services'), getCollection('domains')]);
+  const resources = [...services, ...domains].filter((resource) => resource.data.hidden !== true);
+
+  return resources.flatMap((resource) =>
+    getSpecificationsForResource(resource).map((specification) => ({
+      params: {
+        collection: resource.collection,
+        id: resource.data.id,
+        version: resource.data.version,
+        specification: getSpecificationIdentifier(specification),
+      },
+      props: {
+        rawSpecification: readResourceFile(resource, specification.path),
+        contentType: getSpecificationMediaType(specification),
+      },
+    }))
+  );
+}
+
+export const GET: APIRoute = async ({ params, props }) => {
+  if (props.rawSpecification) {
+    return new Response(props.rawSpecification, {
+      headers: { 'Content-Type': props.contentType ?? 'text/plain' },
+    });
+  }
+
+  const { collection, id, version, specification } = params;
+
+  if (!isSupportedCollection(collection) || !id || !version || !specification) {
+    return new Response(JSON.stringify({ error: 'Missing or invalid collection, id, version, or specification parameter' }), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  const resources = await getCollection(collection);
+  const resource = resources.find((item) => item.data.id === id && item.data.version === version && item.data.hidden !== true);
+
+  if (!resource) {
+    return new Response(JSON.stringify({ error: 'Resource not found' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  const spec = getSpecificationsForResource(resource).find(
+    (item) => getSpecificationIdentifier(item) === specification || item.type === specification
+  );
+
+  if (!spec) {
+    return new Response(JSON.stringify({ error: 'Specification not found' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  const rawSpecification = readResourceFile(resource, spec.path);
+
+  if (!rawSpecification) {
+    return new Response(JSON.stringify({ error: 'Specification file could not be read' }), {
+      status: 404,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  return new Response(rawSpecification, {
+    headers: { 'Content-Type': getSpecificationMediaType(spec) },
+  });
+};
diff --git a/packages/core/eventcatalog/src/pages/api/search-index.json.ts b/packages/core/eventcatalog/src/pages/api/search-index.json.ts
new file mode 100644
index 000000000..d488b67ef
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/api/search-index.json.ts
@@ -0,0 +1,50 @@
+import type { APIRoute } from 'astro';
+import { getNestedSideBarData } from '@stores/sidebar-store/state';
+
+const isDev = import.meta.env.DEV;
+
+interface SearchIndexItemCompact {
+  k: string;
+  t: string;
+  b?: string;
+  s?: string;
+  h?: string;
+  i?: string;
+  li?: string;
+}
+
+const SKIPPED_PREFIXES = ['list:'];
+
+export const GET: APIRoute = async () => {
+  const sidebarData = await getNestedSideBarData();
+
+  const items = Object.entries(sidebarData.nodes).reduce<SearchIndexItemCompact[]>((acc, [key, node]) => {
+    if (typeof node === 'string') return acc;
+    if (SKIPPED_PREFIXES.some((prefix) => key.startsWith(prefix))) return acc;
+    if (!node.title) return acc;
+
+    acc.push({
+      k: key,
+      t: node.title,
+      ...(node.badge ? { b: node.badge } : {}),
+      ...(node.summary ? { s: node.summary } : {}),
+      ...(node.href ? { h: node.href } : {}),
+      ...(node.icon ? { i: node.icon } : {}),
+      ...(node.leftIcon ? { li: node.leftIcon } : {}),
+    });
+
+    return acc;
+  }, []);
+
+  return new Response(JSON.stringify({ i: items }), {
+    headers: {
+      'Content-Type': 'application/json',
+      'Cache-Control': isDev
+        ? 'no-cache, no-store, must-revalidate'
+        : 'public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400',
+      Vary: 'Accept-Encoding',
+    },
+  });
+};
+
+export const prerender = !isDev;
diff --git a/packages/core/eventcatalog/src/pages/api/settings/ai.ts b/packages/core/eventcatalog/src/pages/api/settings/ai.ts
new file mode 100644
index 000000000..8ed5b8be7
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/api/settings/ai.ts
@@ -0,0 +1,57 @@
+import type { APIRoute } from 'astro';
+import { isDevMode } from '@utils/feature';
+import { aiSettingsSchema } from '@utils/eventcatalog-config/config-schema';
+import {
+  applyConfigUpdate,
+  readConfigSource,
+  writeConfigUpdate,
+  type ConfigUpdate,
+} from '@utils/eventcatalog-config/config-writer';
+
+export const prerender = !isDevMode();
+
+const json = (status: number, body: unknown) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+
+export const POST: APIRoute = async ({ request }) => {
+  if (!isDevMode()) {
+    return json(403, { error: 'Settings can only be edited when running in dev mode (EVENTCATALOG_DEV_MODE=true).' });
+  }
+
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return json(400, { error: 'Invalid JSON body' });
+  }
+
+  const parsed = aiSettingsSchema.safeParse(body);
+  if (!parsed.success) {
+    return json(400, { error: 'Validation failed', issues: parsed.error.issues });
+  }
+
+  let source: string;
+  try {
+    source = readConfigSource();
+  } catch (err) {
+    return json(500, { error: `Could not read eventcatalog.config.js: ${(err as Error).message}` });
+  }
+
+  const data = parsed.data;
+  const update: ConfigUpdate = {
+    llmsTxt: { enabled: data.llmsTxtEnabled },
+    chat: { enabled: data.chatEnabled },
+  };
+
+  try {
+    applyConfigUpdate(source, update);
+    writeConfigUpdate(update);
+  } catch (err) {
+    return json(500, { error: `Could not update eventcatalog.config.js: ${(err as Error).message}` });
+  }
+
+  return json(200, { ok: true, settings: data });
+};
diff --git a/packages/core/eventcatalog/src/pages/api/settings/general.ts b/packages/core/eventcatalog/src/pages/api/settings/general.ts
new file mode 100644
index 000000000..1f9e91639
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/api/settings/general.ts
@@ -0,0 +1,71 @@
+import type { APIRoute } from 'astro';
+import { isDevMode } from '@utils/feature';
+import { generalSettingsSchema } from '@utils/eventcatalog-config/config-schema';
+import {
+  applyConfigUpdate,
+  readConfigSource,
+  writeConfigUpdate,
+  type ConfigUpdate,
+} from '@utils/eventcatalog-config/config-writer';
+
+export const prerender = !isDevMode();
+
+const json = (status: number, body: unknown) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+
+export const POST: APIRoute = async ({ request }) => {
+  if (!isDevMode()) {
+    return json(403, { error: 'Settings can only be edited when running in dev mode (EVENTCATALOG_DEV_MODE=true).' });
+  }
+
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return json(400, { error: 'Invalid JSON body' });
+  }
+
+  const parsed = generalSettingsSchema.safeParse(body);
+  if (!parsed.success) {
+    return json(400, { error: 'Validation failed', issues: parsed.error.issues });
+  }
+
+  // Verify the config file exists and is parseable before we attempt the write.
+  let source: string;
+  try {
+    source = readConfigSource();
+  } catch (err) {
+    return json(500, { error: `Could not read eventcatalog.config.js: ${(err as Error).message}` });
+  }
+
+  const data = parsed.data;
+  const update: ConfigUpdate = {
+    title: data.title,
+    tagline: data.tagline ?? null,
+    organizationName: data.organizationName ?? null,
+    homepageLink: data.homepageLink ?? null,
+    editUrl: data.editUrl ?? null,
+    repositoryUrl: data.repositoryUrl ?? null,
+    theme: data.theme,
+  };
+
+  if (data.logo) {
+    update.logo = {
+      alt: data.logo.alt ?? null,
+      text: data.logo.text ?? null,
+    };
+  }
+
+  try {
+    // Dry-run the write first to surface parse errors before touching disk.
+    applyConfigUpdate(source, update);
+    writeConfigUpdate(update);
+  } catch (err) {
+    return json(500, { error: `Could not update eventcatalog.config.js: ${(err as Error).message}` });
+  }
+
+  return json(200, { ok: true, settings: data });
+};
diff --git a/packages/core/eventcatalog/src/pages/api/settings/logo.ts b/packages/core/eventcatalog/src/pages/api/settings/logo.ts
new file mode 100644
index 000000000..0279600cc
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/api/settings/logo.ts
@@ -0,0 +1,113 @@
+import type { APIRoute } from 'astro';
+import fs from 'node:fs';
+import path from 'node:path';
+import { isDevMode } from '@utils/feature';
+import { writeConfigUpdate } from '@utils/eventcatalog-config/config-writer';
+
+export const prerender = !isDevMode();
+
+const MAX_BYTES = 2 * 1024 * 1024;
+const ALLOWED: Record<string, string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/svg+xml': 'svg',
+  'image/webp': 'webp',
+};
+
+const json = (status: number, body: unknown) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+
+const projectRoot = () => process.env.PROJECT_DIR ?? process.cwd();
+const publicDir = () => path.join(projectRoot(), 'public');
+const LOGO_BASENAME = 'eventcatalog-logo';
+
+const removeExistingLogos = () => {
+  const dir = publicDir();
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir)) {
+    if (entry.startsWith(`${LOGO_BASENAME}.`)) {
+      fs.unlinkSync(path.join(dir, entry));
+    }
+  }
+};
+
+/**
+ * Best-effort SVG sanitization: strips <script> blocks and on* event handlers.
+ * Not a full sanitizer; we accept this as a v1 limitation for SVG uploads.
+ */
+const sanitizeSvg = (svg: string): string =>
+  svg
+    .replace(/<script[\s\S]*?<\/script>/gi, '')
+    .replace(/\son[a-z]+\s*=\s*"[^"]*"/gi, '')
+    .replace(/\son[a-z]+\s*=\s*'[^']*'/gi, '')
+    .replace(/javascript:/gi, '');
+
+export const POST: APIRoute = async ({ request }) => {
+  if (!isDevMode()) {
+    return json(403, { error: 'Logo can only be changed when running in dev mode (EVENTCATALOG_DEV_MODE=true).' });
+  }
+
+  let form: FormData;
+  try {
+    form = await request.formData();
+  } catch {
+    return json(400, { error: 'Expected multipart/form-data body' });
+  }
+
+  const file = form.get('logo');
+  if (!(file instanceof File)) {
+    return json(400, { error: 'Missing `logo` file field' });
+  }
+
+  const ext = ALLOWED[file.type];
+  if (!ext) {
+    return json(400, { error: `Unsupported logo type: ${file.type}. Allowed: PNG, JPG, SVG, WebP.` });
+  }
+
+  if (file.size > MAX_BYTES) {
+    return json(413, { error: `Logo exceeds 2MB size limit (got ${file.size} bytes).` });
+  }
+
+  const buffer = Buffer.from(await file.arrayBuffer());
+  const dir = publicDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  removeExistingLogos();
+
+  const targetName = `${LOGO_BASENAME}.${ext}`;
+  const targetPath = path.join(dir, targetName);
+
+  if (ext === 'svg') {
+    const sanitized = sanitizeSvg(buffer.toString('utf8'));
+    fs.writeFileSync(targetPath, sanitized, 'utf8');
+  } else {
+    fs.writeFileSync(targetPath, buffer);
+  }
+
+  const src = `/${targetName}`;
+  try {
+    writeConfigUpdate({ logo: { src } });
+  } catch (err) {
+    return json(500, { error: `Logo saved but config update failed: ${(err as Error).message}` });
+  }
+
+  return json(200, { ok: true, src });
+};
+
+export const DELETE: APIRoute = async () => {
+  if (!isDevMode()) {
+    return json(403, { error: 'Logo can only be changed when running in dev mode.' });
+  }
+
+  removeExistingLogos();
+  try {
+    writeConfigUpdate({ logo: { src: null } });
+  } catch (err) {
+    return json(500, { error: `Logo files removed but config update failed: ${(err as Error).message}` });
+  }
+
+  return json(200, { ok: true });
+};
diff --git a/packages/core/eventcatalog/src/pages/api/sidebar-data.json.ts b/packages/core/eventcatalog/src/pages/api/sidebar-data.json.ts
new file mode 100644
index 000000000..0ed5ba3dd
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/api/sidebar-data.json.ts
@@ -0,0 +1,27 @@
+import type { APIRoute } from 'astro';
+import { getNestedSideBarData } from '@stores/sidebar-store/state';
+
+const isDev = import.meta.env.DEV;
+
+/**
+ * API route that returns the sidebar navigation data as JSON.
+ * This is pre-rendered in static mode to avoid embedding the data in every HTML page.
+ * The data is fetched once and cached by the browser.
+ */
+export const GET: APIRoute = async () => {
+  const sidebarData = await getNestedSideBarData();
+
+  return new Response(JSON.stringify(sidebarData), {
+    headers: {
+      'Content-Type': 'application/json',
+      // In dev mode, disable caching to ensure fresh data. In production, cache for 1 hour.
+      'Cache-Control': isDev
+        ? 'no-cache, no-store, must-revalidate'
+        : 'public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400',
+    },
+  });
+};
+
+// Pre-render this route in static mode so it becomes a static JSON file
+// In dev mode, don't pre-render to allow dynamic updates
+export const prerender = !isDev;
diff --git a/packages/core/eventcatalog/src/pages/architecture/[type]/[id]/[version]/_index.data.ts b/packages/core/eventcatalog/src/pages/architecture/[type]/[id]/[version]/_index.data.ts
new file mode 100644
index 000000000..1d87dd8cc
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/architecture/[type]/[id]/[version]/_index.data.ts
@@ -0,0 +1,72 @@
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import type { PageTypes } from '@types';
+import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
+import { getDomains } from '@utils/collections/domains';
+import { getServices } from '@utils/collections/services';
+import { getSystems } from '@utils/collections/systems';
+
+const architecturePageTypes: PageTypes[] = ['services', 'domains', 'systems'];
+
+/**
+ * Documentation page class for all collection types with versioning
+ */
+export class Page extends HybridPage {
+  static async getStaticPaths() {
+    if (isSSR()) {
+      return [];
+    }
+
+    const domains = await getDomains({ enrichServices: true });
+    const services = await getServices();
+    const systems = await getSystems();
+
+    const pageData = [services, domains, systems];
+
+    return pageData.flatMap((items, index) =>
+      items.map((item) => ({
+        params: {
+          type: architecturePageTypes[index],
+          id: item.data.id,
+          version: item.data.version,
+        },
+        props: {
+          type: architecturePageTypes[index],
+          ...item,
+          // Not everything needs the body of the page itself.
+          body: undefined,
+        },
+      }))
+    );
+  }
+
+  protected static async fetchData(params: any) {
+    const { type, id, version } = params;
+
+    if (!type || !id || !version || !architecturePageTypes.includes(type)) {
+      return null;
+    }
+
+    // Get all items of the specified type
+    const items = await pageDataLoader[type as PageTypes]();
+
+    // Find the specific item by id and version
+    const item = items.find((i) => i.data.id === id && i.data.version === version);
+
+    if (!item) {
+      return null;
+    }
+
+    return {
+      type,
+      ...item,
+    };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Documentation not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/architecture/[type]/[id]/[version]/index.astro b/packages/core/eventcatalog/src/pages/architecture/[type]/[id]/[version]/index.astro
new file mode 100644
index 000000000..c4a104f9a
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/architecture/[type]/[id]/[version]/index.astro
@@ -0,0 +1,38 @@
+---
+import DomainGrid from '@components/Grids/DomainGrid';
+import SystemGrid from '@components/Grids/SystemGrid';
+import MessageGrid from '@components/Grids/MessageGrid';
+import { getSpecificationsForService } from '@utils/collections/services';
+
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+let domain = props;
+
+const pageTitle = `${props.type} | ${props.data.name}`.replace(/^\w/, (c) => c.toUpperCase());
+
+const type = props.type;
+
+const specifications = type === 'services' ? getSpecificationsForService(props) : [];
+---
+
+<VerticalSideBarLayout title={pageTitle}>
+  <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]">
+    <div class="flex docs-layout w-full">
+      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        {type === 'domains' && <DomainGrid domain={domain} client:load />}
+        {type === 'systems' && <SystemGrid system={props} client:load />}
+        {
+          (type === 'agents' || type === 'services') && (
+            <MessageGrid service={props} specifications={specifications} client:load />
+          )
+        }
+      </div>
+    </div>
+  </main>
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/pages/diagrams/[id]/[version].mdx.ts b/packages/core/eventcatalog/src/pages/diagrams/[id]/[version].mdx.ts
new file mode 100644
index 000000000..798ec3939
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/diagrams/[id]/[version].mdx.ts
@@ -0,0 +1,48 @@
+// This file exposes the markdown for diagrams in the URL
+// For example http://localhost:3000/diagrams/target-architecture/1.0.0 loads the Page
+// and http://localhost:3000/diagrams/target-architecture/1.0.0.mdx loads the markdown
+// This is used for LLMs to load the markdown for diagrams (llms.txt)
+
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import fs from 'fs';
+import { isLLMSTxtEnabled, isSSR } from '@utils/feature';
+import { filterMarkdownForAgents } from '@utils/llms';
+
+const diagrams = await getCollection('diagrams');
+
+export async function getStaticPaths() {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return [];
+  }
+
+  return diagrams.map((diagram) => ({
+    params: { id: diagram.data.id, version: diagram.data.version },
+    props: { content: diagram },
+  }));
+}
+
+export const GET: APIRoute = async ({ params, props }) => {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  if (isSSR()) {
+    // For SSR mode, find the diagram and read its file
+    const diagram = diagrams.find((d) => d.data.id === params.id && d.data.version === params.version);
+    if (!diagram?.filePath) {
+      return new Response('Not found', { status: 404 });
+    }
+    const file = filterMarkdownForAgents(fs.readFileSync(diagram.filePath, 'utf8'));
+    return new Response(file, { status: 200 });
+  } else {
+    if (props?.content?.filePath) {
+      const file = filterMarkdownForAgents(fs.readFileSync(props.content.filePath, 'utf8'));
+      return new Response(file, { status: 200 });
+    }
+  }
+
+  return new Response('Not found', { status: 404 });
+};
diff --git a/packages/core/eventcatalog/src/pages/diagrams/[id]/[version]/_index.data.ts b/packages/core/eventcatalog/src/pages/diagrams/[id]/[version]/_index.data.ts
new file mode 100644
index 000000000..5c3dd2bee
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/diagrams/[id]/[version]/_index.data.ts
@@ -0,0 +1,57 @@
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import { getDiagrams } from '@utils/collections/diagrams';
+
+/**
+ * Diagrams page class for full-screen diagram viewing
+ */
+export class Page extends HybridPage {
+  static async getStaticPaths() {
+    if (isSSR()) {
+      return [];
+    }
+
+    const diagrams = await getDiagrams();
+
+    return diagrams.map((diagram) => ({
+      params: {
+        id: diagram.data.id,
+        version: diagram.data.version,
+      },
+      props: {},
+    }));
+  }
+
+  protected static async fetchData(params: any) {
+    const { id, version } = params;
+
+    if (!id || !version) {
+      return null;
+    }
+
+    const diagrams = await getDiagrams();
+    const diagram = diagrams.find((d) => d.data.id === id && d.data.version === version);
+
+    if (!diagram) {
+      return null;
+    }
+
+    // Get all versions of this diagram for the version selector
+    const allVersions = diagrams
+      .filter((d) => d.data.id === id)
+      .map((d) => d.data.version)
+      .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+
+    return {
+      ...diagram,
+      allVersions,
+    };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Diagram not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/diagrams/[id]/[version]/embed.astro b/packages/core/eventcatalog/src/pages/diagrams/[id]/[version]/embed.astro
new file mode 100644
index 000000000..4d67958f0
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/diagrams/[id]/[version]/embed.astro
@@ -0,0 +1,692 @@
+---
+import '../../../../styles/tailwind.css';
+import { render } from 'astro:content';
+import components from '@components/MDX/components';
+import config from '@config';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+const props = await Page.getData(Astro);
+const { Content } = await render(props);
+
+const currentVersion = props.data.version;
+const diagramId = props.data.id;
+---
+
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>v{currentVersion}</title>
+    <style is:global>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+
+      :root {
+        --ec-page-bg: 255 255 255;
+        --ec-page-text: 15 23 42;
+        --ec-page-text-muted: 100 116 139;
+        --ec-page-border: 226 232 240;
+        --ec-content-hover: 241 245 249;
+        --ec-card-bg: 255 255 255;
+        --ec-icon-color: 100 116 139;
+        --ec-icon-hover: 15 23 42;
+      }
+
+      :root[data-theme='dark'] {
+        --ec-page-bg: 13 17 23;
+        --ec-page-text: 240 246 252;
+        --ec-page-text-muted: 139 148 158;
+        --ec-page-border: 33 38 45;
+        --ec-content-hover: 33 38 45;
+        --ec-card-bg: 22 27 34;
+        --ec-icon-color: 139 148 158;
+        --ec-icon-hover: 240 246 252;
+      }
+
+      body {
+        font-family:
+          system-ui,
+          -apple-system,
+          BlinkMacSystemFont,
+          'Segoe UI',
+          Roboto,
+          sans-serif;
+        background: rgb(var(--ec-page-bg));
+        color: rgb(var(--ec-page-text));
+      }
+
+      .embed-container {
+        padding: 1.5rem;
+        height: 100vh;
+        overflow: auto;
+      }
+
+      .mermaid svg {
+        margin: 0 auto;
+        display: block;
+      }
+
+      /* Zoom controls styling - must stay as CSS since svg-pan-zoom injects them */
+      .svg-pan-zoom-control {
+        fill: rgb(var(--ec-page-text-muted)) !important;
+        cursor: pointer;
+      }
+
+      .svg-pan-zoom-control:hover {
+        fill: rgb(var(--ec-page-text)) !important;
+      }
+
+      /* Prose styles */
+      .prose {
+        max-width: none;
+        color: rgb(var(--ec-page-text));
+      }
+      .prose h1,
+      .prose h2,
+      .prose h3,
+      .prose h4 {
+        color: rgb(var(--ec-page-text));
+        margin-top: 1.5rem;
+        margin-bottom: 0.75rem;
+        font-weight: 600;
+      }
+      .prose h1 {
+        font-size: 1.875rem;
+      }
+      .prose h2 {
+        font-size: 1.5rem;
+      }
+      .prose h3 {
+        font-size: 1.25rem;
+      }
+      .prose p {
+        color: rgb(var(--ec-page-text));
+        margin-bottom: 1rem;
+        line-height: 1.6;
+      }
+      .prose strong {
+        color: rgb(var(--ec-page-text));
+        font-weight: 600;
+      }
+      .prose a {
+        color: rgb(var(--ec-page-text));
+        text-decoration: underline;
+      }
+      .prose ul,
+      .prose ol {
+        color: rgb(var(--ec-page-text));
+        margin-bottom: 1rem;
+        padding-left: 1.5rem;
+      }
+      .prose li {
+        margin-bottom: 0.25rem;
+      }
+      .prose code {
+        color: rgb(var(--ec-page-text));
+        background: rgb(var(--ec-page-border));
+        padding: 0.125rem 0.25rem;
+        border-radius: 0.25rem;
+        font-size: 0.875rem;
+      }
+      .prose pre {
+        background: rgb(var(--ec-page-border));
+        padding: 1rem;
+        border-radius: 0.5rem;
+        overflow-x: auto;
+        margin-bottom: 1rem;
+      }
+      .prose pre code {
+        background: transparent;
+        padding: 0;
+      }
+      .prose img {
+        max-width: 100%;
+        height: auto;
+      }
+      .prose blockquote {
+        border-left: 4px solid rgb(var(--ec-page-border));
+        padding-left: 1rem;
+        color: rgb(var(--ec-page-text-muted));
+        margin: 1rem 0;
+      }
+    </style>
+  </head>
+  <body>
+    <script is:inline>
+      // Inherit theme from parent window
+      try {
+        const parentTheme = window.parent?.document?.documentElement?.getAttribute('data-theme');
+        if (parentTheme) {
+          document.documentElement.setAttribute('data-theme', parentTheme);
+        }
+      } catch (e) {
+        // Cross-origin, ignore
+      }
+    </script>
+
+    <div class="embed-container">
+      <div class="flex items-center justify-between mb-4 pb-3 border-b border-[rgb(var(--ec-page-border))]">
+        <span class="text-sm font-semibold text-[rgb(var(--ec-page-text))]">v{currentVersion}</span>
+        <a
+          id="go-to-diagram"
+          href="#"
+          target="_top"
+          class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))] border border-[rgb(var(--ec-page-border))] rounded-md px-3 py-1 hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+        >
+          Go to diagram
+        </a>
+      </div>
+      <article class="prose">
+        <Content components={components(props)} />
+      </article>
+    </div>
+
+    <script is:inline define:vars={{ config, baseUrl: import.meta.env.BASE_URL }}>
+      /**
+       * IMPORTANT: Diagram zoom functionality is intentionally duplicated here from mermaid-zoom.ts.
+       *
+       * This embed page is designed to be loaded in iframes and must be fully self-contained.
+       * It uses CDN imports (e.g., https://cdn.jsdelivr.net/npm/mermaid@10) instead of npm
+       * package imports to ensure isolation from the parent application's build process.
+       *
+       * If you need to update the zoom controls or diagram rendering logic, please update
+       * both this file AND eventcatalog/src/utils/mermaid-zoom.ts to keep them in sync.
+       */
+
+      window.eventcatalog = { mermaid: config?.mermaid };
+
+      // Set the go-to-diagram link by parsing URL: /diagrams/{id}/{version}/embed
+      const goToBtn = document.getElementById('go-to-diagram');
+      if (goToBtn) {
+        const pathParts = window.location.pathname.split('/');
+        const diagramsIndex = pathParts.indexOf('diagrams');
+        const diagramId = diagramsIndex !== -1 ? pathParts[diagramsIndex + 1] : '';
+        const version = diagramsIndex !== -1 ? pathParts[diagramsIndex + 2] : '';
+        const base = baseUrl === '/' ? '' : baseUrl;
+        goToBtn.href = `${base}/diagrams/${diagramId}/${version}`;
+      }
+
+      // Store zoom instances for cleanup
+      const zoomInstances = new Map();
+
+      function createZoomControls(onZoomIn, onZoomOut, onFitView) {
+        // Detect dark mode
+        const isDark = document.documentElement.getAttribute('data-theme') === 'dark';
+
+        // Use explicit colors based on theme
+        const bgColor = isDark ? '#161b22' : '#ffffff';
+        const borderColor = isDark ? '#30363d' : '#e2e8f0';
+        const iconColor = isDark ? '#8b949e' : '#64748b';
+        const iconHoverColor = isDark ? '#f0f6fc' : '#0f172a';
+        const hoverBgColor = isDark ? '#21262d' : '#f1f5f9';
+
+        const controls = document.createElement('div');
+        controls.className = 'mermaid-zoom-controls';
+        controls.style.cssText = `
+          position: absolute;
+          bottom: 12px;
+          left: 12px;
+          display: flex;
+          flex-direction: column;
+          background: ${bgColor};
+          border-radius: 6px;
+          box-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
+          border: 1px solid ${borderColor};
+          overflow: hidden;
+          z-index: 10;
+        `;
+
+        const createButton = (svg, title, onClick, isLast = false) => {
+          const btn = document.createElement('button');
+          btn.type = 'button';
+          btn.title = title;
+          btn.innerHTML = svg;
+          btn.onclick = onClick;
+          btn.style.cssText = `
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            width: 26px;
+            height: 26px;
+            padding: 0;
+            margin: 0;
+            border: none;
+            background: ${bgColor};
+            color: ${iconColor};
+            cursor: pointer;
+            transition: background-color 0.15s, color 0.15s;
+            line-height: 1;
+            ${!isLast ? `border-bottom: 1px solid ${borderColor};` : ''}
+          `;
+          // Ensure SVG is properly centered
+          const svgEl = btn.querySelector('svg');
+          if (svgEl) {
+            svgEl.style.display = 'block';
+          }
+          btn.onmouseenter = () => {
+            btn.style.backgroundColor = hoverBgColor;
+            btn.style.color = iconHoverColor;
+          };
+          btn.onmouseleave = () => {
+            btn.style.backgroundColor = bgColor;
+            btn.style.color = iconColor;
+          };
+          return btn;
+        };
+
+        const plusSvg = `<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="12" y1="5" x2="12" y2="19"></line><line x1="5" y1="12" x2="19" y2="12"></line></svg>`;
+        const minusSvg = `<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="5" y1="12" x2="19" y2="12"></line></svg>`;
+        const fitSvg = `<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M8 3H5a2 2 0 0 0-2 2v3m18 0V5a2 2 0 0 0-2-2h-3m0 18h3a2 2 0 0 0 2-2v-3M3 16v3a2 2 0 0 0 2 2h3"></path></svg>`;
+
+        controls.appendChild(createButton(plusSvg, 'Zoom in', onZoomIn));
+        controls.appendChild(createButton(minusSvg, 'Zoom out', onZoomOut));
+        controls.appendChild(createButton(fitSvg, 'Fit view', onFitView, true));
+
+        return controls;
+      }
+
+      // Icons for toolbar
+      const ICONS = {
+        presentation: `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3.75 3v11.25A2.25 2.25 0 006 16.5h2.25M3.75 3h-1.5m1.5 0h16.5m0 0h1.5m-1.5 0v11.25A2.25 2.25 0 0118 16.5h-2.25m-7.5 0h7.5m-7.5 0l-1 3m8.5-3l1 3m0 0l.5 1.5m-.5-1.5h-9.5m0 0l-.5 1.5m.75-9l3-3 2.148 2.148A12.061 12.061 0 0116.5 7.605"></path></svg>`,
+        copy: `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M8.25 7.5V6.108c0-1.135.845-2.098 1.976-2.192.373-.03.748-.057 1.123-.08M15.75 18H18a2.25 2.25 0 002.25-2.25V6.108c0-1.135-.845-2.098-1.976-2.192a48.424 48.424 0 00-1.123-.08M15.75 18.75v-1.875a3.375 3.375 0 00-3.375-3.375h-1.5a1.125 1.125 0 01-1.125-1.125v-1.5A3.375 3.375 0 006.375 7.5H5.25m11.9-3.664A2.251 2.251 0 0015 2.25h-1.5a2.251 2.251 0 00-2.15 1.586m5.8 0c.065.21.1.433.1.664v.75h-6V4.5c0-.231.035-.454.1-.664M6.75 7.5H4.875c-.621 0-1.125.504-1.125 1.125v12c0 .621.504 1.125 1.125 1.125h9.75c.621 0 1.125-.504 1.125-1.125V16.5a9 9 0 00-9-9z"></path></svg>`,
+        check: `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>`,
+      };
+
+      function createToolbarButton(icon, tooltipText, onClick, tooltipPosition = 'bottom') {
+        const isDark = document.documentElement.getAttribute('data-theme') === 'dark';
+        const bgColor = isDark ? '#161b22' : '#ffffff';
+        const iconColor = isDark ? '#8b949e' : '#64748b';
+        const iconHoverColor = isDark ? '#f0f6fc' : '#0f172a';
+        const hoverBgColor = isDark ? '#21262d' : '#f1f5f9';
+
+        const wrapper = document.createElement('div');
+        wrapper.style.cssText = 'position: relative;';
+
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        btn.innerHTML = icon;
+        btn.style.cssText = `
+          all: unset;
+          box-sizing: border-box;
+          display: flex;
+          justify-content: center;
+          align-items: center;
+          width: 40px;
+          height: 40px;
+          min-width: 40px;
+          min-height: 40px;
+          padding: 0;
+          margin: 0;
+          border: none;
+          border-radius: 6px;
+          background: ${bgColor};
+          color: ${iconColor};
+          cursor: pointer;
+          transition: background-color 0.15s, color 0.15s;
+          box-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
+        `;
+
+        const svgEl = btn.querySelector('svg');
+        if (svgEl) svgEl.style.cssText = 'display: block; width: 20px; height: 20px;';
+
+        btn.onmouseenter = () => {
+          btn.style.backgroundColor = hoverBgColor;
+          btn.style.color = iconHoverColor;
+        };
+        btn.onmouseleave = () => {
+          btn.style.backgroundColor = bgColor;
+          btn.style.color = iconColor;
+        };
+        btn.onclick = onClick;
+
+        const tooltip = document.createElement('div');
+        tooltip.textContent = tooltipText;
+
+        // Position tooltip based on tooltipPosition parameter
+        let tooltipStyles = `
+          position: absolute;
+          padding: 4px 8px;
+          background: #1f2937;
+          color: white;
+          font-size: 12px;
+          border-radius: 4px;
+          box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+          white-space: nowrap;
+          pointer-events: none;
+          opacity: 0;
+          transition: opacity 0.15s;
+          z-index: 50;
+        `;
+
+        if (tooltipPosition === 'right') {
+          tooltipStyles += `
+            top: 50%;
+            left: 100%;
+            transform: translateY(-50%);
+            margin-left: 8px;
+          `;
+        } else if (tooltipPosition === 'left') {
+          tooltipStyles += `
+            top: 50%;
+            right: 100%;
+            transform: translateY(-50%);
+            margin-right: 8px;
+          `;
+        } else {
+          // Default: bottom
+          tooltipStyles += `
+            top: 100%;
+            left: 50%;
+            transform: translateX(-50%);
+            margin-top: 8px;
+          `;
+        }
+
+        tooltip.style.cssText = tooltipStyles;
+
+        wrapper.onmouseenter = () => (tooltip.style.opacity = '1');
+        wrapper.onmouseleave = () => (tooltip.style.opacity = '0');
+
+        wrapper.appendChild(btn);
+        wrapper.appendChild(tooltip);
+        return { wrapper, btn, tooltip, iconColor };
+      }
+
+      function createFullscreenButton(onClick) {
+        const { wrapper } = createToolbarButton(ICONS.presentation, 'Presentation Mode', onClick, 'right');
+        wrapper.style.cssText = 'position: absolute; top: 12px; left: 12px; z-index: 10;';
+        return wrapper;
+      }
+
+      function createCopyButton(onCopy) {
+        const copy = createToolbarButton(
+          ICONS.copy,
+          'Copy diagram code',
+          () => {
+            onCopy();
+            copy.btn.innerHTML = ICONS.check;
+            copy.btn.style.color = '#10b981';
+            copy.tooltip.textContent = 'Copied!';
+            const svgEl = copy.btn.querySelector('svg');
+            if (svgEl) svgEl.style.cssText = 'display: block; width: 20px; height: 20px;';
+
+            setTimeout(() => {
+              copy.btn.innerHTML = ICONS.copy;
+              copy.btn.style.color = copy.iconColor;
+              copy.tooltip.textContent = 'Copy diagram code';
+              const svgEl = copy.btn.querySelector('svg');
+              if (svgEl) svgEl.style.cssText = 'display: block; width: 20px; height: 20px;';
+            }, 2000);
+          },
+          'left'
+        );
+        copy.wrapper.style.cssText = 'position: absolute; top: 12px; right: 12px; z-index: 10;';
+        return copy.wrapper;
+      }
+
+      function toggleFullscreen(container) {
+        if (!document.fullscreenElement) {
+          container.requestFullscreen().catch((err) => console.warn('Fullscreen error:', err));
+        } else {
+          document.exitFullscreen();
+        }
+      }
+
+      async function initMermaidZoom(svgElement, container, id, diagramContent) {
+        const { default: svgPanZoom } = await import('https://cdn.jsdelivr.net/npm/svg-pan-zoom@3.6.2/+esm');
+
+        // Get the natural dimensions from viewBox or getBBox
+        let width, height;
+        const viewBox = svgElement.getAttribute('viewBox');
+        if (viewBox) {
+          const parts = viewBox.split(/[\s,]+/).map(Number);
+          width = parts[2];
+          height = parts[3];
+        } else {
+          const bbox = svgElement.getBBox();
+          width = bbox.width;
+          height = bbox.height;
+          if (width > 0 && height > 0) {
+            svgElement.setAttribute('viewBox', `${bbox.x} ${bbox.y} ${width} ${height}`);
+          }
+        }
+
+        // Set container height based on SVG aspect ratio, capped for usability
+        if (width > 0 && height > 0) {
+          const containerWidth = container.clientWidth || 800;
+          const aspectRatio = height / width;
+          const calculatedHeight = Math.min(Math.max(containerWidth * aspectRatio, 200), 500);
+          container.style.height = `${calculatedHeight}px`;
+        }
+
+        // SVG needs to fill the container for svg-pan-zoom
+        svgElement.style.width = '100%';
+        svgElement.style.height = '100%';
+        svgElement.removeAttribute('height');
+        svgElement.removeAttribute('width');
+
+        try {
+          const instance = svgPanZoom(svgElement, {
+            zoomEnabled: true,
+            controlIconsEnabled: false,
+            fit: true,
+            center: true,
+            minZoom: 0.5,
+            maxZoom: 10,
+            zoomScaleSensitivity: 0.15,
+            dblClickZoomEnabled: true,
+            mouseWheelZoomEnabled: false, // Disabled to avoid hijacking page scroll
+            preventMouseEventsDefault: true,
+            panEnabled: true,
+          });
+
+          zoomInstances.set(id, instance);
+
+          // Update cursor during pan
+          container.addEventListener('mousedown', () => {
+            container.style.cursor = 'grabbing';
+          });
+          container.addEventListener('mouseup', () => {
+            container.style.cursor = 'grab';
+          });
+          container.addEventListener('mouseleave', () => {
+            container.style.cursor = 'grab';
+          });
+
+          // Add custom controls
+          const controls = createZoomControls(
+            () => instance.zoomIn(),
+            () => instance.zoomOut(),
+            () => {
+              instance.fit();
+              instance.center();
+            }
+          );
+          container.appendChild(controls);
+
+          // Add fullscreen button (top-left)
+          const fullscreenBtn = createFullscreenButton(() => toggleFullscreen(container));
+          container.appendChild(fullscreenBtn);
+
+          // Add copy button (top-right) if diagram content is available
+          if (diagramContent) {
+            const copyBtn = createCopyButton(() => {
+              navigator.clipboard.writeText(diagramContent).catch((err) => {
+                console.warn('Failed to copy:', err);
+              });
+            });
+            container.appendChild(copyBtn);
+          }
+
+          // Handle fullscreen changes
+          document.addEventListener('fullscreenchange', () => {
+            const isFullscreen = document.fullscreenElement === container;
+            if (isFullscreen) {
+              instance.enableMouseWheelZoom();
+              const isDark = document.documentElement.getAttribute('data-theme') === 'dark';
+              container.style.background = isDark ? '#0d1117' : '#ffffff';
+            } else {
+              instance.disableMouseWheelZoom();
+              container.style.background = '';
+            }
+            setTimeout(() => {
+              if (container.clientWidth > 0 && container.clientHeight > 0) {
+                try {
+                  instance.resize();
+                  instance.fit();
+                  instance.center();
+                } catch (e) {}
+              }
+            }, 100);
+          });
+
+          // Resize handler for responsiveness
+          const resizeObserver = new ResizeObserver(() => {
+            if (container.clientWidth > 0 && container.clientHeight > 0) {
+              try {
+                instance.resize();
+                instance.fit();
+                instance.center();
+              } catch (e) {}
+            }
+          });
+          resizeObserver.observe(container);
+        } catch (e) {
+          console.warn('Failed to initialize zoom on mermaid diagram:', e);
+        }
+      }
+
+      async function renderMermaid() {
+        const graphs = document.getElementsByClassName('mermaid');
+        if (graphs.length === 0) return;
+
+        const { default: mermaid } = await import('https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs');
+        const isDarkMode = document.documentElement.getAttribute('data-theme') === 'dark';
+
+        mermaid.initialize({
+          maxTextSize: window.eventcatalog?.mermaid?.maxTextSize || 100000,
+          startOnLoad: false,
+          theme: isDarkMode ? 'dark' : 'default',
+          fontFamily: 'system-ui, -apple-system, sans-serif',
+        });
+
+        for (const graph of graphs) {
+          const content = graph.getAttribute('data-content');
+          if (!content) continue;
+          const id = 'mermaid-' + Math.round(Math.random() * 100000);
+          try {
+            const result = await mermaid.render(id, content);
+
+            // Create zoom container with inline styles (no Tailwind in embed)
+            const container = document.createElement('div');
+            container.style.cssText =
+              'position: relative; width: 100%; min-height: 200px; overflow: hidden; margin: 1em 0; cursor: grab;';
+
+            // Insert the rendered SVG
+            container.innerHTML = result.svg;
+
+            // Replace the graph content with the container
+            graph.innerHTML = '';
+            graph.appendChild(container);
+
+            // Initialize zoom on the SVG
+            const svgElement = container.querySelector('svg');
+            if (svgElement) {
+              await initMermaidZoom(svgElement, container, id, content);
+            }
+          } catch (e) {
+            console.error('Mermaid render error:', e);
+          }
+        }
+      }
+
+      renderMermaid();
+
+      // PlantUML rendering with zoom
+      async function renderPlantUML() {
+        const blocks = document.getElementsByClassName('plantuml');
+        if (blocks.length === 0) return;
+
+        const { deflate } = await import('https://cdn.jsdelivr.net/npm/pako@2.1.0/+esm');
+        const { default: svgPanZoom } = await import('https://cdn.jsdelivr.net/npm/svg-pan-zoom@3.6.2/+esm');
+
+        function encode64(data) {
+          const chars = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_';
+          let str = '';
+          const len = data.length;
+          for (let i = 0; i < len; i += 3) {
+            const b1 = data[i];
+            const b2 = i + 1 < len ? data[i + 1] : 0;
+            const b3 = i + 2 < len ? data[i + 2] : 0;
+
+            let c1 = b1 >> 2;
+            let c2 = ((b1 & 0x3) << 4) | (b2 >> 4);
+            let c3 = ((b2 & 0xf) << 2) | (b3 >> 6);
+            let c4 = b3 & 0x3f;
+
+            str += chars[c1] + chars[c2] + chars[c3] + chars[c4];
+          }
+          return str;
+        }
+
+        function encodePlantUML(text) {
+          const data = new TextEncoder().encode(text);
+          const compressed = deflate(data, { level: 9, to: 'Uint8Array' });
+          return encode64(compressed);
+        }
+
+        for (const block of blocks) {
+          const content = block.getAttribute('data-content');
+          if (!content) continue;
+
+          const encoded = encodePlantUML(content);
+          const svgUrl = `https://www.plantuml.com/plantuml/svg/~1${encoded}`;
+          const id = 'plantuml-' + Math.round(Math.random() * 100000);
+
+          try {
+            // Fetch SVG content for zoom support
+            const response = await fetch(svgUrl);
+            if (!response.ok) throw new Error('Fetch failed');
+
+            const svgText = await response.text();
+
+            // Create zoom container
+            const container = document.createElement('div');
+            container.style.cssText =
+              'position: relative; width: 100%; min-height: 200px; overflow: hidden; margin: 1em 0; cursor: grab;';
+            container.innerHTML = svgText;
+
+            block.innerHTML = '';
+            block.appendChild(container);
+
+            // Initialize zoom
+            const svgElement = container.querySelector('svg');
+            if (svgElement) {
+              await initMermaidZoom(svgElement, container, id, content);
+            }
+          } catch (e) {
+            // Fallback to img
+            console.warn('PlantUML fetch failed:', e);
+            const img = document.createElement('img');
+            img.src = svgUrl;
+            img.alt = 'PlantUML diagram';
+            img.loading = 'lazy';
+            img.style.margin = '0 auto';
+            img.style.display = 'block';
+            block.innerHTML = '';
+            block.appendChild(img);
+          }
+        }
+      }
+
+      renderPlantUML();
+    </script>
+  </body>
+</html>
diff --git a/packages/core/eventcatalog/src/pages/diagrams/[id]/[version]/index.astro b/packages/core/eventcatalog/src/pages/diagrams/[id]/[version]/index.astro
new file mode 100644
index 000000000..59a6956b9
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/diagrams/[id]/[version]/index.astro
@@ -0,0 +1,407 @@
+---
+import { render } from 'astro:content';
+import { ClientRouter } from 'astro:transitions';
+import VisualiserLayout from '@layouts/VisualiserLayout.astro';
+import components from '@components/MDX/components';
+import config from '@config';
+import { buildUrl } from '@utils/url-builder';
+import { GitCompare, X, AlignLeft, HistoryIcon } from 'lucide-react';
+import CopyAsMarkdown from '@components/CopyAsMarkdown';
+import { isLLMSTxtEnabled, isEventCatalogChatEnabled } from '@utils/feature';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+const props = await Page.getData(Astro);
+const { Content, headings } = await render(props);
+
+const pageTitle = `Diagram | ${props.data.name}`;
+const currentVersion = props.data.version;
+const allVersions = props.allVersions || [currentVersion];
+const hasMultipleVersions = allVersions.length > 1;
+const chatEnabled = isEventCatalogChatEnabled();
+const markdownDownloadEnabled = isLLMSTxtEnabled();
+const chatQuery = `Tell me about the "${props.data.name}" diagram (version ${props.data.version})`;
+---
+
+<VisualiserLayout title={pageTitle} description={props.data.summary}>
+  <div class="diagram-page min-h-[calc(100vh-64px)] bg-[rgb(var(--ec-page-bg))]">
+    <div
+      class="flex docs-layout w-full"
+      style="padding-left: var(--ec-app-content-padding-left, 5rem); padding-right: var(--ec-app-content-padding-right, 5rem);"
+    >
+      <main class="diagram-content w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-2">
+          <div class="flex items-start gap-4">
+            <div class="min-w-0">
+              <h1 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))] truncate">
+                {props.data.name}
+              </h1>
+              {
+                props.data.summary && (
+                  <p class="pt-2 text-base font-light text-[rgb(var(--ec-page-text-muted))]">{props.data.summary}</p>
+                )
+              }
+              <div class="pt-4">
+                <CopyAsMarkdown
+                  client:only="react"
+                  variant="toolbar"
+                  schemas={[]}
+                  chatQuery={chatQuery}
+                  chatEnabled={chatEnabled}
+                  editUrl=""
+                  markdownDownloadEnabled={markdownDownloadEnabled}
+                  rssFeedEnabled={false}
+                  preferChatAsDefault={chatEnabled}
+                  chatButtonText="Ask about this diagram"
+                />
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <article
+          class="diagram-article prose prose-md w-full max-w-none py-4 text-[15px] dark:prose-invert prose-headings:text-[rgb(var(--ec-page-text))] prose-p:text-[rgb(var(--ec-page-text))] prose-strong:text-[rgb(var(--ec-page-text))] prose-code:text-[rgb(var(--ec-page-text))]"
+        >
+          <Content components={components(props)} />
+        </article>
+      </main>
+
+      {
+        headings.length > 0 && (
+          <aside
+            id="eventcatalog-docs-sidebar"
+            class="hidden xl:block sticky top-[4rem] self-start w-[280px] max-h-[calc(100vh-4rem)] overflow-y-auto py-2 flex-shrink-0 pr-10 bg-[rgb(var(--ec-page-bg))]"
+          >
+            <div class="mt-8 space-y-8">
+              <div>
+                <h3 class="text-xs text-[rgb(var(--ec-page-text))] font-semibold capitalize flex items-center gap-2 mb-4">
+                  <AlignLeft className="w-4 h-4" />
+                  On this page
+                </h3>
+                <nav class="text-xs border-l border-[rgb(var(--ec-page-border))]">
+                  {headings.map((heading) => {
+                    const level = heading.depth > 2 ? heading.depth : 1;
+                    if (heading.depth > 3) {
+                      return null;
+                    }
+                    return (
+                      <a
+                        href={`#${heading.slug}`}
+                        class="block py-1.5 pr-2.5 leading-5 text-[rgb(var(--ec-page-text-muted))] hover:border-[rgb(var(--ec-page-border))] hover:text-[rgb(var(--ec-page-text))] border-l-2 border-transparent -ml-px transition-all duration-200"
+                        style={`padding-left: ${level * 0.75}rem`}
+                      >
+                        {heading.text}
+                      </a>
+                    );
+                  })}
+                </nav>
+              </div>
+              {hasMultipleVersions && (
+                <div>
+                  <h3 class="text-xs text-[rgb(var(--ec-page-text))] font-semibold capitalize flex items-center gap-2 mb-4">
+                    <HistoryIcon className="w-4 h-4" />
+                    {`Versions (${allVersions.length})`}
+                  </h3>
+                  <ul role="list" class="space-y-2">
+                    {allVersions.map((version: string) => {
+                      const isCurrent = version === currentVersion;
+                      return (
+                        <li>
+                          <a
+                            href={buildUrl(`/diagrams/${props.data.id}/${version}`)}
+                            class={`flex items-center gap-2 text-xs transition-colors ${
+                              isCurrent
+                                ? 'text-[rgb(var(--ec-accent))] font-medium'
+                                : 'text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]'
+                            }`}
+                          >
+                            <HistoryIcon className="h-4 w-4 flex-shrink-0" />
+                            <span>{version === props.data.latestVersion ? `v${version} (latest)` : `v${version}`}</span>
+                          </a>
+                        </li>
+                      );
+                    })}
+                  </ul>
+                </div>
+              )}
+              {hasMultipleVersions && (
+                <div>
+                  <button
+                    id="compare-btn"
+                    type="button"
+                    class="inline-flex w-full items-center justify-center gap-1.5 rounded-md border border-[rgb(var(--ec-dropdown-border))] bg-[rgb(var(--ec-dropdown-bg))] px-3 py-2 text-sm font-medium text-[rgb(var(--ec-dropdown-text))] shadow-xs transition-colors hover:bg-[rgb(var(--ec-dropdown-hover))] focus:outline-hidden focus:ring-1 focus:ring-[rgb(var(--ec-accent))]"
+                  >
+                    <GitCompare className="w-4 h-4" />
+                    Compare diagram versions
+                  </button>
+                </div>
+              )}
+            </div>
+          </aside>
+        )
+      }
+    </div>
+  </div>
+
+  {/* Compare modal */}
+  {
+    hasMultipleVersions && (
+      <div id="compare-modal" class="hidden fixed inset-0 z-50 bg-[rgb(var(--ec-page-bg))]">
+        <div class="flex items-center justify-between px-6 py-3 border-b border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg))]">
+          <h2 class="text-sm font-semibold text-[rgb(var(--ec-page-text))]">Compare: {props.data.name}</h2>
+          <div class="flex items-center gap-6">
+            <div class="flex items-center gap-2">
+              <span class="text-xs text-[rgb(var(--ec-page-text-muted))]">Left:</span>
+              <select
+                id="compare-left-version"
+                class="appearance-none text-xs font-medium text-[rgb(var(--ec-input-text))] bg-[rgb(var(--ec-input-bg))] border border-[rgb(var(--ec-input-border))] rounded-md pl-2 pr-2 py-1 cursor-pointer"
+              >
+                {allVersions.map((version: string, index: number) => (
+                  <option value={version} selected={index === 1 || allVersions.length === 1}>
+                    v{version}
+                  </option>
+                ))}
+              </select>
+            </div>
+            <div class="flex items-center gap-2">
+              <span class="text-xs text-[rgb(var(--ec-page-text-muted))]">Right:</span>
+              <select
+                id="compare-right-version"
+                class="appearance-none text-xs font-medium text-[rgb(var(--ec-input-text))] bg-[rgb(var(--ec-input-bg))] border border-[rgb(var(--ec-input-border))] rounded-md pl-2 pr-2 py-1 cursor-pointer"
+              >
+                {allVersions.map((version: string, index: number) => (
+                  <option value={version} selected={index === 0}>
+                    v{version}
+                  </option>
+                ))}
+              </select>
+            </div>
+            <button
+              id="compare-close-btn"
+              type="button"
+              class="p-1.5 hover:bg-[rgb(var(--ec-content-hover))] rounded-md text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-icon-hover))]"
+            >
+              <X className="w-5 h-5" />
+            </button>
+          </div>
+        </div>
+        <div class="flex h-[calc(100vh-57px)]">
+          <div class="flex-1 border-r border-[rgb(var(--ec-page-border))]">
+            <iframe id="compare-left-frame" class="w-full h-full border-0" />
+          </div>
+          <div class="flex-1">
+            <iframe id="compare-right-frame" class="w-full h-full border-0" />
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  <ClientRouter />
+</VisualiserLayout>
+
+<style is:global>
+  .diagram-page .prose {
+    max-width: none;
+    overflow: auto;
+  }
+
+  .toc-active-text {
+    color: rgb(var(--ec-accent));
+  }
+
+  .toc-active-border {
+    border-color: rgb(var(--ec-accent));
+  }
+</style>
+
+<script is:inline define:vars={{ config, baseUrl: import.meta.env.BASE_URL }}>
+  window.eventcatalog = window.eventcatalog || {};
+  window.eventcatalog.mermaid = config?.mermaid;
+  window.eventcatalog.baseUrl = baseUrl;
+</script>
+
+<script>
+  import { destroyZoomInstances, renderMermaidWithZoom } from '@utils/mermaid-zoom';
+
+  function initDiagramPage() {
+    // Compare modal
+    const compareBtn = document.getElementById('compare-btn') as HTMLButtonElement;
+    const compareModal = document.getElementById('compare-modal');
+    const compareCloseBtn = document.getElementById('compare-close-btn');
+    const leftVersionSelect = document.getElementById('compare-left-version') as HTMLSelectElement;
+    const rightVersionSelect = document.getElementById('compare-right-version') as HTMLSelectElement;
+    const leftFrame = document.getElementById('compare-left-frame') as HTMLIFrameElement;
+    const rightFrame = document.getElementById('compare-right-frame') as HTMLIFrameElement;
+
+    function buildCompareUrl(version: string) {
+      const pathParts = window.location.pathname.split('/');
+      const diagramsIndex = pathParts.indexOf('diagrams');
+      const diagramId = diagramsIndex !== -1 ? pathParts[diagramsIndex + 1] : '';
+      const baseUrl = (window as any).eventcatalog?.baseUrl || '/';
+      const base = baseUrl === '/' ? '' : baseUrl;
+      return `${window.location.origin}${base}/diagrams/${diagramId}/${version}/embed`;
+    }
+
+    function openCompareModal() {
+      if (!compareModal) return;
+      compareModal.classList.remove('hidden');
+      document.body.style.overflow = 'hidden';
+      if (leftFrame && leftVersionSelect) leftFrame.src = buildCompareUrl(leftVersionSelect.value);
+      if (rightFrame && rightVersionSelect) rightFrame.src = buildCompareUrl(rightVersionSelect.value);
+    }
+
+    function closeCompareModal() {
+      if (!compareModal) return;
+      compareModal.classList.add('hidden');
+      document.body.style.overflow = '';
+      if (leftFrame) leftFrame.src = '';
+      if (rightFrame) rightFrame.src = '';
+    }
+
+    if (compareBtn) {
+      compareBtn.onclick = openCompareModal;
+    }
+
+    if (compareCloseBtn) compareCloseBtn.onclick = closeCompareModal;
+
+    if (leftVersionSelect) {
+      leftVersionSelect.onchange = () => {
+        if (leftFrame) leftFrame.src = buildCompareUrl(leftVersionSelect.value);
+      };
+    }
+    if (rightVersionSelect) {
+      rightVersionSelect.onchange = () => {
+        if (rightFrame) rightFrame.src = buildCompareUrl(rightVersionSelect.value);
+      };
+    }
+
+    document.onkeydown = (e) => {
+      if (e.key === 'Escape') {
+        if (compareModal && !compareModal.classList.contains('hidden')) closeCompareModal();
+      }
+    };
+
+    // Render Mermaid diagrams with zoom
+    destroyZoomInstances();
+    const graphs = document.getElementsByClassName('mermaid');
+    if (graphs.length > 0) {
+      renderMermaidWithZoom(graphs, window.eventcatalog?.mermaid);
+    }
+  }
+
+  // Run immediately and on page transitions
+  initDiagramPage();
+  document.addEventListener('astro:page-load', initDiagramPage);
+</script>
+
+<script>
+  // @ts-nocheck
+  function setupDiagramTocObserver() {
+    try {
+      const tocRoot = document.getElementById('eventcatalog-docs-sidebar');
+      if (!tocRoot) return;
+
+      const observerOptions = {
+        rootMargin: '0px 0px -40% 0px',
+        threshold: 0.1,
+      };
+
+      let observerPaused = false;
+
+      function highlightTocItem(id) {
+        tocRoot.querySelectorAll('.active-toc-item').forEach((link) => {
+          link.classList.remove('active-toc-item', 'toc-active-text', 'font-medium', 'toc-active-border');
+          link.classList.add('border-transparent');
+        });
+
+        const tocLink = tocRoot.querySelector(`nav a[href="#${id}"]`);
+        if (tocLink) {
+          tocLink.classList.add('active-toc-item', 'toc-active-text', 'font-medium', 'toc-active-border');
+          tocLink.classList.remove('border-transparent');
+
+          setTimeout(() => {
+            tocLink.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' });
+          }, 10);
+        }
+      }
+
+      const observer = new IntersectionObserver((entries) => {
+        if (observerPaused) return;
+
+        entries.forEach((entry) => {
+          try {
+            const id = entry.target.getAttribute('id');
+            if (entry.isIntersecting && id) {
+              highlightTocItem(id);
+            }
+          } catch (entryError) {
+            console.error('Error processing intersection entry:', entryError);
+          }
+        });
+      }, observerOptions);
+
+      const prose = document.querySelector('.diagram-article.prose');
+      if (!prose) return;
+
+      const proseHeadings = prose.querySelectorAll('h1[id], h2[id], h3[id]');
+
+      if (proseHeadings.length > 0) {
+        proseHeadings.forEach((heading) => observer.observe(heading));
+      } else {
+        const allHeadings = prose.querySelectorAll('h1, h2, h3');
+
+        allHeadings.forEach((heading) => {
+          if (!heading.id) {
+            const text = heading.textContent || '';
+            const slug = text
+              .toLowerCase()
+              .replace(/[^\w\s-]/g, '')
+              .replace(/\s+/g, '-');
+            heading.id = slug;
+          }
+          observer.observe(heading);
+        });
+      }
+
+      const tocLinks = tocRoot.querySelectorAll('nav a[href^="#"]');
+      tocLinks.forEach((link) => {
+        link.addEventListener('click', () => {
+          const hrefAttr = link.getAttribute('href');
+          if (!hrefAttr) return;
+
+          const id = hrefAttr.substring(1);
+          highlightTocItem(id);
+          observerPaused = true;
+
+          setTimeout(() => {
+            observerPaused = false;
+          }, 500);
+        });
+      });
+    } catch (error) {
+      console.error('Error setting up diagram TOC highlighting:', error);
+    }
+  }
+
+  setupDiagramTocObserver();
+  document.addEventListener('astro:page-load', setupDiagramTocObserver);
+</script>
+
+<script>
+  import { renderPlantUMLWithZoom } from '@utils/mermaid-zoom';
+
+  function initPlantUML() {
+    const blocks = document.getElementsByClassName('plantuml');
+    if (blocks.length > 0) {
+      renderPlantUMLWithZoom(blocks);
+    }
+  }
+
+  // Run on initial load and page transitions
+  initPlantUML();
+  document.addEventListener('astro:page-load', initPlantUML);
+</script>
diff --git a/packages/core/eventcatalog/src/pages/directory/[type]/_index.data.ts b/packages/core/eventcatalog/src/pages/directory/[type]/_index.data.ts
new file mode 100644
index 000000000..e8d27d8b8
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/directory/[type]/_index.data.ts
@@ -0,0 +1,63 @@
+// pages/directory/[type]/index.page.ts
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+
+export class Page extends HybridPage {
+  static get prerender(): boolean {
+    return !isSSR();
+  }
+
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    const { getUsers } = await import('@utils/collections/users');
+    const { getTeams } = await import('@utils/collections/teams');
+
+    const loaders = {
+      users: getUsers,
+      teams: getTeams,
+    };
+
+    const itemTypes = ['users', 'teams'] as const;
+    const allItems = await Promise.all(itemTypes.map((type) => loaders[type]()));
+
+    return allItems.flatMap((items, index) => ({
+      params: {
+        type: itemTypes[index],
+      },
+      props: {
+        data: items,
+        type: itemTypes[index],
+      },
+    }));
+  }
+
+  protected static async fetchData(params: any) {
+    const { type } = params;
+
+    if (!type) {
+      return null;
+    }
+
+    const { getUsers } = await import('@utils/collections/users');
+    const { getTeams } = await import('@utils/collections/teams');
+
+    const loaders = {
+      users: getUsers,
+      teams: getTeams,
+    };
+
+    // Get all items of the specified type
+    const items = await loaders[type as keyof typeof loaders]();
+
+    return {
+      type,
+      data: items,
+    };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Directory type not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/directory/[type]/index.astro b/packages/core/eventcatalog/src/pages/directory/[type]/index.astro
new file mode 100644
index 000000000..c3eba4b3d
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/directory/[type]/index.astro
@@ -0,0 +1,65 @@
+---
+import type { CollectionEntry } from 'astro:content';
+
+import DirectoryLayout, { type Props as DirectoryLayoutProps } from '@layouts/DirectoryLayout.astro';
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+const { type, data } = await Page.getData(Astro);
+
+function mapToItem(i: any) {
+  return {
+    collection: i.collection,
+    data: {
+      id: i.data.id,
+      name: i.data.name,
+      version: i.data.version,
+    },
+  };
+}
+---
+
+<DirectoryLayout
+  title={`${type} (${data.length})`}
+  subtitle={`Find, filter and search for any ${type} in your system.`}
+  data={data.map(
+    (d: CollectionEntry<'users' | 'teams'>) =>
+      ({
+        collection: d.collection,
+        data: {
+          // @ts-ignore
+          id: d.data.id,
+          name: d.data.name,
+          // @ts-ignore
+          source: d.data?.source,
+          // @ts-ignore
+          role: d.data?.role,
+          // @ts-ignore
+          avatarUrl: d.data?.avatarUrl,
+          // @ts-ignore
+          email: d.data?.email,
+          // @ts-ignore
+          slackDirectMessageUrl: d.data?.slackDirectMessageUrl,
+          // @ts-ignore
+          msTeamsDirectMessageUrl: d.data?.msTeamsDirectMessageUrl,
+          // @ts-ignore
+          associatedTeams: d.data?.associatedTeams?.map(mapToItem) ?? [],
+          // @ts-ignore
+          ownedAgents: d.data?.ownedAgents?.map(mapToItem) ?? [],
+          // @ts-ignore
+          ownedCommands: d.data?.ownedCommands?.map(mapToItem) ?? [],
+          // @ts-ignore
+          ownedQueries: d.data?.ownedQueries?.map(mapToItem) ?? [],
+          // @ts-ignore
+          ownedEvents: d.data?.ownedEvents?.map(mapToItem) ?? [],
+          // @ts-ignore
+          ownedServices: d.data?.ownedServices?.map(mapToItem) ?? [],
+          // @ts-ignore
+          members: d.data?.members,
+        },
+      }) as DirectoryLayoutProps<typeof type>['data'][0]
+  )}
+  type={type}
+/>
diff --git a/packages/core/eventcatalog/src/pages/discover/[type]/_index.data.ts b/packages/core/eventcatalog/src/pages/discover/[type]/_index.data.ts
new file mode 100644
index 000000000..4f148f8b4
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/discover/[type]/_index.data.ts
@@ -0,0 +1,99 @@
+// pages/discover/[type]/index.page.ts
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
+
+export class Page extends HybridPage {
+  static get prerender(): boolean {
+    return !isSSR();
+  }
+
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    const { getFlows } = await import('@utils/collections/flows');
+    const { getAgents } = await import('@utils/collections/agents');
+    const { getAdrs } = await import('@utils/collections/adrs');
+    const { getServices } = await import('@utils/collections/services');
+    const { getDataProducts } = await import('@utils/collections/data-products');
+
+    const getInternalServices = async () => (await getServices()).filter((s) => !s.data.externalSystem);
+    const getExternalServices = async () => (await getServices()).filter((s) => s.data.externalSystem);
+
+    const loaders = {
+      ...pageDataLoader,
+      agents: getAgents,
+      adrs: getAdrs,
+      flows: getFlows,
+      services: getInternalServices,
+      'external-systems': getExternalServices,
+      'data-products': getDataProducts,
+    };
+
+    const itemTypes = [
+      'events',
+      'agents',
+      'adrs',
+      'commands',
+      'queries',
+      'domains',
+      'systems',
+      'services',
+      'external-systems',
+      'flows',
+      'containers',
+      'data-products',
+    ] as const;
+    const allItems = await Promise.all(itemTypes.map((type) => loaders[type]()));
+
+    return allItems.flatMap((items, index) => ({
+      params: {
+        type: itemTypes[index],
+      },
+      props: {
+        data: items,
+        type: itemTypes[index],
+      },
+    }));
+  }
+
+  protected static async fetchData(params: any) {
+    const { type } = params;
+
+    if (!type) {
+      return null;
+    }
+
+    const { getFlows } = await import('@utils/collections/flows');
+    const { getAgents } = await import('@utils/collections/agents');
+    const { getAdrs } = await import('@utils/collections/adrs');
+    const { getServices } = await import('@utils/collections/services');
+    const { getDataProducts } = await import('@utils/collections/data-products');
+
+    const getInternalServices = async () => (await getServices()).filter((s) => !s.data.externalSystem);
+    const getExternalServices = async () => (await getServices()).filter((s) => s.data.externalSystem);
+
+    const loaders = {
+      ...pageDataLoader,
+      agents: getAgents,
+      adrs: getAdrs,
+      flows: getFlows,
+      services: getInternalServices,
+      'external-systems': getExternalServices,
+      'data-products': getDataProducts,
+    };
+
+    // @ts-ignore
+    const items = await loaders[type]();
+
+    return {
+      type,
+      data: items,
+    };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Collection type not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/discover/[type]/index.astro b/packages/core/eventcatalog/src/pages/discover/[type]/index.astro
new file mode 100644
index 000000000..d65d448d4
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/discover/[type]/index.astro
@@ -0,0 +1,474 @@
+---
+import { getCommands } from '@utils/collections/commands';
+import { getAgents } from '@utils/collections/agents';
+import { createAdrStatusBadge, getAdrs } from '@utils/collections/adrs';
+import { getDomains, getDomainsForAgent, getDomainsForService } from '@utils/collections/domains';
+import { getEvents } from '@utils/collections/events';
+import { getServices } from '@utils/collections/services';
+import { getQueries } from '@utils/collections/queries';
+import { getContainers } from '@utils/collections/containers';
+import { getDataProducts } from '@utils/collections/data-products';
+import { getFlows } from '@utils/collections/flows';
+import { getUsers } from '@utils/collections/users';
+import { getTeams } from '@utils/collections/teams';
+import { getChannels } from '@utils/collections/channels';
+import { getSystems } from '@utils/collections/systems';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import {
+  DiscoverTable,
+  type CollectionKindOption,
+  type DiscoverTableData,
+  type CollectionType,
+} from '@components/Tables/Discover';
+import config from '@config';
+import { buildUrl } from '@utils/url-builder';
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+const { type, data } = await Page.getData(Astro);
+
+const events = await getEvents();
+const queries = await getQueries();
+const commands = await getCommands();
+const agents = await getAgents();
+const adrs = await getAdrs();
+const services = await getServices();
+const domains = await getDomains({ getAllVersions: false });
+const systems = await getSystems({ getAllVersions: false });
+const containers = await getContainers();
+const dataProducts = await getDataProducts();
+const flows = await getFlows();
+const channels = await getChannels();
+const users = await getUsers();
+const teams = await getTeams();
+
+// Create lookup maps for users and teams
+const userMap = new Map(users.map((u) => [u.data.id, u]));
+const teamMap = new Map(teams.map((t) => [t.data.id, t]));
+
+// Type configuration for property options
+const typeConfig: Record<
+  string,
+  {
+    label: string;
+    description: string;
+    propertyOptions: Array<{ id: string; label: string }>;
+  }
+> = {
+  events: {
+    label: 'Events',
+    description: 'Explore the events flowing through your catalog and understand who produces and consumes them.',
+    propertyOptions: [
+      { id: 'hasProducers', label: 'Has Producers' },
+      { id: 'hasConsumers', label: 'Has Consumers' },
+      { id: 'hasOwners', label: 'Has Owners' },
+      { id: 'isDeprecated', label: 'Is Deprecated' },
+    ],
+  },
+  commands: {
+    label: 'Commands',
+    description: 'Browse the commands in your catalog and see which services issue and respond to them.',
+    propertyOptions: [
+      { id: 'hasProducers', label: 'Has Producers' },
+      { id: 'hasConsumers', label: 'Has Consumers' },
+      { id: 'hasOwners', label: 'Has Owners' },
+      { id: 'isDeprecated', label: 'Is Deprecated' },
+    ],
+  },
+  queries: {
+    label: 'Queries',
+    description: 'Explore the queries available across your catalog and trace the services connected to them.',
+    propertyOptions: [
+      { id: 'hasProducers', label: 'Has Producers' },
+      { id: 'hasConsumers', label: 'Has Consumers' },
+      { id: 'hasOwners', label: 'Has Owners' },
+      { id: 'isDeprecated', label: 'Is Deprecated' },
+    ],
+  },
+  domains: {
+    label: 'Domains',
+    description: 'Organize and explore the business domains that shape your architecture.',
+    propertyOptions: [
+      { id: 'hasServices', label: 'Has Services' },
+      { id: 'hasOwners', label: 'Has Owners' },
+      { id: 'isDeprecated', label: 'Is Deprecated' },
+    ],
+  },
+  systems: {
+    label: 'Systems',
+    description: 'Explore the systems that group services and flows across your architecture, independently of domains.',
+    propertyOptions: [
+      { id: 'hasServices', label: 'Has Services' },
+      { id: 'hasFlows', label: 'Has Flows' },
+      { id: 'hasOwners', label: 'Has Owners' },
+      { id: 'isDeprecated', label: 'Is Deprecated' },
+    ],
+  },
+  services: {
+    label: 'Services',
+    description: 'Browse the internal services in your catalog and inspect the capabilities they expose.',
+    propertyOptions: [
+      { id: 'hasSpecifications', label: 'Has Specifications' },
+      { id: 'hasOwners', label: 'Has Owners' },
+      { id: 'hasRepository', label: 'Has Repository' },
+      { id: 'hasDataDependencies', label: 'Has Data Dependencies' },
+      { id: 'isDeprecated', label: 'Is Deprecated' },
+    ],
+  },
+  agents: {
+    label: 'Agents',
+    description: 'Browse AI agents in your catalog and inspect the models, tools, and messages they use.',
+    propertyOptions: [
+      { id: 'hasModel', label: 'Has Model' },
+      { id: 'hasTools', label: 'Has Tools' },
+      { id: 'hasOwners', label: 'Has Owners' },
+      { id: 'hasRepository', label: 'Has Repository' },
+      { id: 'hasDataDependencies', label: 'Has Data Dependencies' },
+      { id: 'isDeprecated', label: 'Is Deprecated' },
+    ],
+  },
+  adrs: {
+    label: 'Decision Records',
+    description: 'Browse the decision records across your catalog and inspect their status and scope.',
+    propertyOptions: [
+      { id: 'hasOwners', label: 'Has Owners' },
+      { id: 'hasAppliesTo', label: 'Applies To Resources' },
+      { id: 'hasDecisionMakers', label: 'Has Decision Makers' },
+    ],
+  },
+  'external-systems': {
+    label: 'External Systems',
+    description: 'Explore the external systems connected to your architecture and the contracts around them.',
+    propertyOptions: [
+      { id: 'hasSpecifications', label: 'Has Specifications' },
+      { id: 'hasOwners', label: 'Has Owners' },
+      { id: 'hasRepository', label: 'Has Repository' },
+      { id: 'hasDataDependencies', label: 'Has Data Dependencies' },
+      { id: 'isDeprecated', label: 'Is Deprecated' },
+    ],
+  },
+  flows: {
+    label: 'Flows',
+    description: 'Inspect the business and technical flows that connect resources across your catalog.',
+    propertyOptions: [
+      { id: 'hasOwners', label: 'Has Owners' },
+      { id: 'isDeprecated', label: 'Is Deprecated' },
+    ],
+  },
+  containers: {
+    label: 'Data',
+    description: 'Explore the data stores and containers that services read from and write to.',
+    propertyOptions: [
+      { id: 'hasOwners', label: 'Has Owners' },
+      { id: 'hasWriters', label: 'Has Writers' },
+      { id: 'hasReaders', label: 'Has Readers' },
+      { id: 'isDeprecated', label: 'Is Deprecated' },
+    ],
+  },
+  'data-products': {
+    label: 'Data Products',
+    description: 'Browse your data products and understand the inputs, outputs, and ownership behind them.',
+    propertyOptions: [
+      { id: 'hasOwners', label: 'Has Owners' },
+      { id: 'hasInputs', label: 'Has Inputs' },
+      { id: 'hasOutputs', label: 'Has Outputs' },
+      { id: 'isDeprecated', label: 'Is Deprecated' },
+    ],
+  },
+};
+
+const currentTypeConfig = typeConfig[type] || typeConfig.events;
+const internalServices = services.filter((service) => !service.data.externalSystem);
+const externalSystems = services.filter((service) => service.data.externalSystem);
+
+const collectionKinds = [
+  { id: 'domains', label: typeConfig.domains.label, count: domains.length },
+  { id: 'systems', label: typeConfig.systems.label, count: systems.length },
+  { id: 'services', label: typeConfig.services.label, count: internalServices.length },
+  { id: 'external-systems', label: typeConfig['external-systems'].label, count: externalSystems.length },
+  { id: 'agents', label: typeConfig.agents.label, count: agents.length },
+  { id: 'adrs', label: typeConfig.adrs.label, count: adrs.length },
+  { id: 'data-products', label: typeConfig['data-products'].label, count: dataProducts.length },
+  { id: 'containers', label: typeConfig.containers.label, count: containers.length },
+  { id: 'events', label: typeConfig.events.label, count: events.length },
+  { id: 'commands', label: typeConfig.commands.label, count: commands.length },
+  { id: 'queries', label: typeConfig.queries.label, count: queries.length },
+  { id: 'flows', label: typeConfig.flows.label, count: flows.length },
+]
+  .filter((kind) => kind.count > 0)
+  .map((kind) => ({
+    ...kind,
+    href: buildUrl(`/discover/${kind.id}`),
+  })) as CollectionKindOption[];
+
+// External systems reuse the user's `services.tableConfiguration` so customisations apply to both tabs
+const tableConfigurationKey = type === 'external-systems' ? 'services' : type;
+// @ts-ignore
+const tableConfiguration = config[tableConfigurationKey as keyof typeof config]?.tableConfiguration ?? { columns: {} };
+
+// Map data to match the expected structure for the table
+function mapToItem(i: any) {
+  return {
+    collection: i.collection,
+    data: {
+      id: i.data.id,
+      name: i.data.name,
+      version: i.data.version,
+    },
+  };
+}
+
+// Helper to map owner references with type detection
+function mapOwner(o: any) {
+  if (!o) return null;
+  const id = typeof o === 'string' ? o : o.data?.id || o.id || o;
+
+  // Look up in users first, then teams
+  const user = userMap.get(id);
+  if (user) {
+    return { id, name: user.data.name || id, type: 'user' as const };
+  }
+
+  const team = teamMap.get(id);
+  if (team) {
+    return { id, name: team.data.name || id, type: 'team' as const };
+  }
+
+  // Fallback if not found in either
+  const name = typeof o === 'string' ? o : o.data?.name || o.name || id;
+  return { id, name, type: 'user' as const };
+}
+
+// Helper to check if service has specifications
+function hasSpecifications(service: any): boolean {
+  const specs = service.data?.specifications;
+  if (!specs) return false;
+  if (Array.isArray(specs)) return specs.length > 0;
+  return !!(specs.openapiPath || specs.asyncapiPath || specs.graphqlPath);
+}
+
+// Build lookup maps for all collections (for resolving data product inputs/outputs)
+const allCollections = [
+  ...agents.map((a) => ({ ...a, collection: 'agents' })),
+  ...adrs.map((adr) => ({ ...adr, collection: 'adrs' })),
+  ...services.map((s) => ({ ...s, collection: 'services' })),
+  ...containers.map((c) => ({ ...c, collection: 'containers' })),
+  ...channels.map((c) => ({ ...c, collection: 'channels' })),
+  ...events.map((e) => ({ ...e, collection: 'events' })),
+  ...commands.map((c) => ({ ...c, collection: 'commands' })),
+  ...queries.map((q) => ({ ...q, collection: 'queries' })),
+  ...dataProducts.map((dp) => ({ ...dp, collection: 'data-products' })),
+];
+
+// Create a map for quick lookup by id
+const collectionItemMap = new Map(allCollections.map((item) => [item.data.id, item]));
+
+// Helper to resolve a pointer to a collection item
+function resolvePointer(pointer: { id: string; version?: string }) {
+  if (!pointer?.id) return null;
+  const item = collectionItemMap.get(pointer.id);
+  if (!item) return null;
+  return {
+    collection: item.collection,
+    data: {
+      id: item.data.id,
+      name: item.data.name,
+      version: item.data.version,
+    },
+  };
+}
+
+// Build a Set of subdomain IDs (domains that are nested within other domains)
+const allSubdomainIds = new Set(
+  domains.flatMap((d: any) => (d.data?.domains || []).map((sd: any) => sd.data?.id || sd.id)).filter(Boolean)
+);
+const parentDomainsBySubdomainId = domains.reduce((parentsBySubdomain: Map<string, any[]>, domain: any) => {
+  (domain.data?.domains || []).forEach((subdomain: any) => {
+    const subdomainId = subdomain.data?.id || subdomain.id;
+    if (!subdomainId) return;
+
+    const parents = parentsBySubdomain.get(subdomainId) || [];
+    parents.push({
+      id: domain.data.id,
+      name: domain.data.name,
+      version: domain.data.version,
+    });
+    parentsBySubdomain.set(subdomainId, parents);
+  });
+  return parentsBySubdomain;
+}, new Map<string, any[]>());
+
+const isAgentLike = type === 'agents';
+const isServiceLike = type === 'services' || type === 'external-systems';
+const isServiceOrAgentLike = isServiceLike || isAgentLike;
+
+// For services, external systems, and agents, enrich with domain information
+const enrichedData = isServiceOrAgentLike
+  ? await Promise.all(
+      data.map(async (resource: any) => {
+        const resourceDomains = isAgentLike ? await getDomainsForAgent(resource) : await getDomainsForService(resource);
+        return {
+          ...resource,
+          enrichedDomains: resourceDomains.map((d: any) => ({
+            id: d.data.id,
+            name: d.data.name,
+            version: d.data.version,
+          })),
+        };
+      })
+    )
+  : data;
+
+const tableData = enrichedData.map((d: any) => ({
+  collection: d.collection,
+  owners: (d.data?.owners || []).map(mapOwner).filter(Boolean),
+  hasOwners: (d.data?.owners || []).length > 0,
+  hasServices: type === 'domains' || type === 'systems' ? (d.data?.services || []).length > 0 : false,
+  hasFlows: type === 'systems' ? (d.data?.flows || []).length > 0 : false,
+  isSubdomain: type === 'domains' ? allSubdomainIds.has(d.data.id) : false,
+  parentDomains: type === 'domains' ? parentDomainsBySubdomainId.get(d.data.id) || [] : undefined,
+  // Service-specific properties
+  domains: isServiceOrAgentLike ? d.enrichedDomains : undefined,
+  hasSpecifications: isServiceLike ? hasSpecifications(d) : false,
+  hasRepository: isServiceOrAgentLike ? !!d.data?.repository?.url : false,
+  hasDataDependencies: isServiceOrAgentLike ? (d.data?.writesTo || []).length > 0 || (d.data?.readsFrom || []).length > 0 : false,
+  hasModel: type === 'agents' ? !!d.data?.model : false,
+  hasTools: type === 'agents' ? (d.data?.tools || []).length > 0 : false,
+  hasAppliesTo: type === 'adrs' ? (d.data?.appliesTo || []).length > 0 : false,
+  hasDecisionMakers: type === 'adrs' ? (d.data?.decisionMakers || []).length > 0 : false,
+  // Data-product-specific properties
+  hasInputs: type === 'data-products' ? (d.data?.inputs || []).length > 0 : false,
+  hasOutputs: type === 'data-products' ? (d.data?.outputs || []).length > 0 : false,
+  isDeprecated: d.data?.deprecated === true || (typeof d.data?.deprecated === 'object' && d.data?.deprecated !== null),
+  data: {
+    id: d.data.id,
+    name: d.data.name,
+    summary: d.data?.summary,
+    icon: d.data?.styles?.icon,
+    version: d.data.version,
+    latestVersion: d.data?.latestVersion,
+    draft: d.data?.draft,
+    badges: d.data?.badges,
+    status: d.data?.status,
+    date: d.data?.date,
+    statusBadge: d.data?.status ? createAdrStatusBadge(d.data.status) : undefined,
+    producers: d.data?.producers?.map(mapToItem) ?? [],
+    consumers: d.data?.consumers?.map(mapToItem) ?? [],
+    receives: d.data?.receives?.map(mapToItem) ?? [],
+    sends: d.data?.sends?.map(mapToItem) ?? [],
+    model: d.data?.model,
+    tools: d.data?.tools ?? [],
+    agents: d.data?.agents?.map(mapToItem) ?? [],
+    services: d.data?.services?.map(mapToItem) ?? [],
+    domains: d.data?.domains?.map(mapToItem) ?? [],
+    flows: d.data?.flows?.map(mapToItem) ?? [],
+    servicesThatWriteToContainer: d.data?.servicesThatWriteToContainer?.map(mapToItem) ?? [],
+    servicesThatReadFromContainer: d.data?.servicesThatReadFromContainer?.map(mapToItem) ?? [],
+    inputs: d.data?.inputs?.map(resolvePointer).filter(Boolean) ?? [],
+    outputs: d.data?.outputs?.map(resolvePointer).filter(Boolean) ?? [],
+  },
+}));
+
+// Get unique owners from all items
+const uniqueOwners = Array.from(new Map(tableData.flatMap((d: any) => d.owners || []).map((o: any) => [o.id, o])).values()).sort(
+  (a: any, b: any) => a.name.localeCompare(b.name)
+);
+
+// Get unique producers (services) for message types
+// Check for duplicate names and add version if needed
+const producerResources = [...agents, ...services];
+const resourcesByName = new Map<string, typeof producerResources>();
+producerResources.forEach((resource) => {
+  const name = resource.data.name;
+  if (!resourcesByName.has(name)) resourcesByName.set(name, []);
+  resourcesByName.get(name)!.push(resource);
+});
+
+const uniqueProducers = producerResources
+  .map((resource) => {
+    const hasDuplicateName = (resourcesByName.get(resource.data.name)?.length ?? 0) > 1;
+    const isLatest = resource.data.version === resource.data.latestVersion;
+    const versionLabel = isLatest ? 'latest' : `v${resource.data.version}`;
+    return {
+      id: resource.data.id,
+      name: hasDuplicateName ? `${resource.data.name} (${versionLabel})` : resource.data.name,
+    };
+  })
+  .sort((a, b) => a.name.localeCompare(b.name));
+
+// Show producers/consumers filter only for events, commands, queries
+const showProducersFilter = ['events', 'commands', 'queries'].includes(type);
+const showConsumersFilter = ['events', 'commands', 'queries'].includes(type);
+
+// Consumers are the same services list
+const uniqueConsumers = uniqueProducers;
+
+// Get unique domains for the services filter
+const uniqueDomains = domains.map((d) => ({
+  id: d.data.id,
+  name: d.data.name,
+  version: d.data.version,
+}));
+
+const uniqueAgentProviders = Array.from(
+  new Map(
+    tableData
+      .map((d: any) => d.data?.model?.provider)
+      .filter(Boolean)
+      .map((provider: string) => [provider, { id: provider, name: provider }])
+  ).values()
+).sort((a: any, b: any) => a.name.localeCompare(b.name));
+
+const uniqueAgentModels = Array.from(
+  new Map(
+    tableData
+      .map((d: any) => d.data?.model)
+      .filter((model: any) => model?.name)
+      .map((model: any) => {
+        const id = [model.name, model.version].filter(Boolean).join(':');
+        return [id, { id, name: model.name }];
+      })
+  ).values()
+).sort((a: any, b: any) => a.name.localeCompare(b.name));
+
+// Show domains filter only for services and external systems
+const showDomainsFilter = isServiceOrAgentLike;
+
+const title = `${currentTypeConfig.label} (${data.length})`;
+---
+
+<VerticalSideBarLayout title={`Explore | ${title}`} showNestedSideBar={false}>
+  <style is:global>
+    #eventcatalog-header {
+      left: calc(var(--ec-vertical-nav-width, 14rem) + var(--ec-discover-sidebar-width, 320px)) !important;
+    }
+  </style>
+  <main
+    class="ml-0 flex h-full min-h-0 flex-col overflow-hidden bg-[rgb(var(--ec-page-bg))]"
+    style={`--ec-discover-sidebar-width: 320px; margin-left: calc(var(--ec-app-content-padding-left, 5rem) * -1); margin-right: calc(var(--ec-app-content-padding-right, 5rem) * -1); height: calc(100dvh - 60px);`}
+  >
+    <div class="flex-1 min-h-0 overflow-hidden">
+      <DiscoverTable
+        data={tableData as DiscoverTableData[]}
+        collectionType={type as CollectionType}
+        collectionLabel={currentTypeConfig.label}
+        collectionDescription={currentTypeConfig.description}
+        collectionKinds={collectionKinds}
+        domains={uniqueDomains}
+        owners={uniqueOwners as Array<{ id: string; name: string; type?: 'user' | 'team' }>}
+        producers={uniqueProducers}
+        consumers={uniqueConsumers}
+        agentProviders={uniqueAgentProviders as Array<{ id: string; name: string }>}
+        agentModels={uniqueAgentModels as Array<{ id: string; name: string }>}
+        propertyOptions={currentTypeConfig.propertyOptions}
+        tableConfiguration={tableConfiguration}
+        showDomainsFilter={showDomainsFilter}
+        showProducersFilter={showProducersFilter}
+        showConsumersFilter={showConsumersFilter}
+        client:only="react"
+      />
+    </div>
+  </main>
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version].md.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version].md.ts
new file mode 100644
index 000000000..422a4735d
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version].md.ts
@@ -0,0 +1,75 @@
+// This file exposes the markdown for EventCatalog in the Url
+// For example http://localhost:3000/docs/events/OrderAmended/0.0.1 loads the Page and http://localhost:3000/docs/events/OrderAmended/0.0.1.md loads the markdown
+// This is used for the LLMs to load the markdown for the given item (llms.txt);
+
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import { getEntities } from '@utils/collections/entities';
+import config from '@config';
+import fs from 'fs';
+import { isLLMSTxtEnabled } from '@utils/feature';
+import { filterMarkdownForAgents } from '@utils/llms';
+
+const events = await getCollection('events');
+const agents = await getCollection('agents');
+const commands = await getCollection('commands');
+const queries = await getCollection('queries');
+const services = await getCollection('services');
+const dataProducts = await getCollection('data-products');
+const domains = await getCollection('domains');
+const systems = await getCollection('systems');
+const flows = await getCollection('flows');
+const channels = await getCollection('channels');
+const containers = await getCollection('containers');
+const entities = await getEntities();
+
+const collections = {
+  agents,
+  events,
+  commands,
+  queries,
+  services,
+  'data-products': dataProducts,
+  domains,
+  systems,
+  flows,
+  channels,
+  containers,
+  entities,
+};
+
+const findContent = (params: Record<string, string | undefined>) => {
+  const collection = collections[params.type as keyof typeof collections];
+  return collection?.find((item: any) => item.data.id === params.id && item.data.version === params.version);
+};
+
+export async function getStaticPaths() {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return [];
+  }
+
+  const paths = Object.keys(collections).map((type) => {
+    return collections[type as keyof typeof collections].map((item: { data: { id: string; version: string } }) => ({
+      params: { type, id: item.data.id, version: item.data.version },
+      props: { content: item },
+    }));
+  });
+
+  return paths.flat();
+}
+
+export const GET: APIRoute = async ({ params, props }) => {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  const content = props?.content ?? findContent(params);
+  if (content?.filePath) {
+    const file = filterMarkdownForAgents(fs.readFileSync(content.filePath, 'utf8'));
+    return new Response(file, { status: 200 });
+  }
+
+  return new Response('Not found', { status: 404 });
+};
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version].mdx.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version].mdx.ts
new file mode 100644
index 000000000..d8bba0773
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version].mdx.ts
@@ -0,0 +1,92 @@
+// This file exposes the markdown for EventCatalog in the Url
+// For example http://localhost:3000/docs/events/OrderAmended/0.0.1 loads the Page and http://localhost:3000/docs/events/OrderAmended/0.0.1.md loads the markdown
+// This is used for the LLMs to load the markdown for the given item (llms.txt);
+
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import config from '@config';
+import fs from 'fs';
+import { addSchemaToMarkdown, filterMarkdownForAgents } from '@utils/llms';
+import { isLLMSTxtEnabled, isSSR } from '@utils/feature';
+const events = await getCollection('events');
+const agents = await getCollection('agents');
+const commands = await getCollection('commands');
+const queries = await getCollection('queries');
+const services = await getCollection('services');
+const dataProducts = await getCollection('data-products');
+const domains = await getCollection('domains');
+const systems = await getCollection('systems');
+const flows = await getCollection('flows');
+const channels = await getCollection('channels');
+const containers = await getCollection('containers');
+const entities = await getCollection('entities');
+
+import utils from '@eventcatalog/sdk';
+
+const collections = {
+  agents,
+  events,
+  commands,
+  queries,
+  services,
+  'data-products': dataProducts,
+  domains,
+  systems,
+  flows,
+  channels,
+  containers,
+  entities,
+};
+
+const findContent = (params: Record<string, string | undefined>) => {
+  const collection = collections[params.type as keyof typeof collections];
+  return collection?.find((item) => item.data.id === params.id && item.data.version === params.version);
+};
+
+export async function getStaticPaths() {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return [];
+  }
+
+  const paths = Object.keys(collections).map((type) => {
+    return collections[type as keyof typeof collections].map((item: { data: { id: string; version: string } }) => ({
+      params: { type, id: item.data.id, version: item.data.version },
+      props: { content: item },
+    }));
+  });
+
+  return paths.flat();
+}
+
+export const GET: APIRoute = async ({ params, props }) => {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  const content = props?.content ?? findContent(params);
+  if (content?.filePath) {
+    let file = fs.readFileSync(content.filePath, 'utf8');
+
+    try {
+      file = addSchemaToMarkdown(content, file);
+    } catch (error) {
+      console.log('Warning: Cant find the schema for', content.data.id, content.data.version);
+    }
+
+    return new Response(filterMarkdownForAgents(file), { status: 200 });
+  }
+
+  if (isSSR()) {
+    const { getResourcePath } = utils(process.env.PROJECT_DIR ?? '');
+    const filePath = await getResourcePath(process.env.PROJECT_DIR ?? '', params.id ?? '', params.version ?? '');
+    if (!filePath) {
+      return new Response('Not found', { status: 404 });
+    }
+    const file = filterMarkdownForAgents(fs.readFileSync(filePath.fullPath, 'utf8'));
+    return new Response(file, { status: 200 });
+  }
+
+  return new Response('Not found', { status: 404 });
+};
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId].md.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId].md.ts
new file mode 100644
index 000000000..73204e9e1
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId].md.ts
@@ -0,0 +1,76 @@
+// Exposes the raw markdown for a resource doc.
+// Example: /docs/services/OrdersService/1.0.0/adrs/01-some-decision.md
+// Used by llms.txt so LLMs can fetch the markdown directly.
+
+import type { APIRoute } from 'astro';
+import fs from 'fs';
+import { isLLMSTxtEnabled, isResourceDocsEnabled, isSSR } from '@utils/feature';
+import { getResourceDocs, getResourceDocsForResource, type ResourceCollection } from '@utils/collections/resource-docs';
+import { filterMarkdownForAgents } from '@utils/llms';
+
+const supportedResourceCollections = new Set<ResourceCollection>([
+  'domains',
+  'services',
+  'events',
+  'commands',
+  'queries',
+  'flows',
+  'containers',
+  'channels',
+  'entities',
+  'data-products',
+]);
+
+export async function getStaticPaths() {
+  if (isSSR() || !isLLMSTxtEnabled() || !isResourceDocsEnabled()) {
+    return [];
+  }
+
+  const docs = await getResourceDocs();
+  const latestDocs = docs.filter((doc) => doc.data.version === doc.data.latestVersion);
+
+  return latestDocs.map((doc) => ({
+    params: {
+      type: doc.data.resourceCollection,
+      id: doc.data.resourceId,
+      version: doc.data.resourceVersion,
+      docType: doc.data.type,
+      docId: doc.data.id,
+    },
+    props: { filePath: doc.filePath },
+  }));
+}
+
+export const GET: APIRoute = async ({ params, props }) => {
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  if (!isResourceDocsEnabled()) {
+    return new Response('Resource docs are not enabled for this Catalog.', { status: 404 });
+  }
+
+  let filePath = (props as { filePath?: string } | undefined)?.filePath;
+
+  if (!filePath && isSSR()) {
+    const type = params.type as ResourceCollection | undefined;
+    if (!type || !supportedResourceCollections.has(type)) {
+      return new Response('Not found', { status: 404 });
+    }
+    const docsForResource = await getResourceDocsForResource(type, params.id ?? '', params.version ?? '');
+    const doc = docsForResource.find(
+      (resourceDoc) =>
+        resourceDoc.data.type === params.docType &&
+        resourceDoc.data.id === params.docId &&
+        resourceDoc.data.version === resourceDoc.data.latestVersion
+    );
+    filePath = doc?.filePath;
+  }
+
+  if (!filePath) {
+    return new Response('Not found', { status: 404 });
+  }
+
+  const file = filterMarkdownForAgents(fs.readFileSync(filePath, 'utf8'));
+  return new Response(file, { status: 200, headers: { 'Content-Type': 'text/markdown; charset=utf-8' } });
+};
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId].mdx.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId].mdx.ts
new file mode 100644
index 000000000..6528d60df
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId].mdx.ts
@@ -0,0 +1,77 @@
+// Exposes the raw mdx for a resource doc.
+// Example: /docs/services/OrdersService/1.0.0/adrs/01-some-decision.mdx
+// Used by llms.txt so LLMs can fetch the markdown directly.
+
+import type { APIRoute } from 'astro';
+import fs from 'fs';
+import { isLLMSTxtEnabled, isResourceDocsEnabled, isSSR } from '@utils/feature';
+import { getResourceDocs, getResourceDocsForResource, type ResourceCollection } from '@utils/collections/resource-docs';
+import { filterMarkdownForAgents } from '@utils/llms';
+
+const supportedResourceCollections = new Set<ResourceCollection>([
+  'agents',
+  'domains',
+  'services',
+  'events',
+  'commands',
+  'queries',
+  'flows',
+  'containers',
+  'channels',
+  'entities',
+  'data-products',
+]);
+
+export async function getStaticPaths() {
+  if (isSSR() || !isLLMSTxtEnabled() || !isResourceDocsEnabled()) {
+    return [];
+  }
+
+  const docs = await getResourceDocs();
+  const latestDocs = docs.filter((doc) => doc.data.version === doc.data.latestVersion);
+
+  return latestDocs.map((doc) => ({
+    params: {
+      type: doc.data.resourceCollection,
+      id: doc.data.resourceId,
+      version: doc.data.resourceVersion,
+      docType: doc.data.type,
+      docId: doc.data.id,
+    },
+    props: { filePath: doc.filePath },
+  }));
+}
+
+export const GET: APIRoute = async ({ params, props }) => {
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  if (!isResourceDocsEnabled()) {
+    return new Response('Resource docs are not enabled for this Catalog.', { status: 404 });
+  }
+
+  let filePath = (props as { filePath?: string } | undefined)?.filePath;
+
+  if (!filePath && isSSR()) {
+    const type = params.type as ResourceCollection | undefined;
+    if (!type || !supportedResourceCollections.has(type)) {
+      return new Response('Not found', { status: 404 });
+    }
+    const docsForResource = await getResourceDocsForResource(type, params.id ?? '', params.version ?? '');
+    const doc = docsForResource.find(
+      (resourceDoc) =>
+        resourceDoc.data.type === params.docType &&
+        resourceDoc.data.id === params.docId &&
+        resourceDoc.data.version === resourceDoc.data.latestVersion
+    );
+    filePath = doc?.filePath;
+  }
+
+  if (!filePath) {
+    return new Response('Not found', { status: 404 });
+  }
+
+  const file = filterMarkdownForAgents(fs.readFileSync(filePath, 'utf8'));
+  return new Response(file, { status: 200, headers: { 'Content-Type': 'text/markdown; charset=utf-8' } });
+};
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/[docVersion]/_index.data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/[docVersion]/_index.data.ts
new file mode 100644
index 000000000..bd3839a07
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/[docVersion]/_index.data.ts
@@ -0,0 +1,85 @@
+import { isSSR, isResourceDocsEnabled } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import { getResourceDocs, getResourceDocsForResource, type ResourceCollection } from '@utils/collections/resource-docs';
+
+const supportedResourceCollections = new Set<ResourceCollection>([
+  'domains',
+  'services',
+  'events',
+  'commands',
+  'queries',
+  'flows',
+  'containers',
+  'channels',
+  'entities',
+  'data-products',
+]);
+
+export class Page extends HybridPage {
+  static async getStaticPaths() {
+    if (isSSR() || !isResourceDocsEnabled()) {
+      return [];
+    }
+
+    const docs = await getResourceDocs();
+
+    return docs.map((doc) => ({
+      params: {
+        type: doc.data.resourceCollection,
+        id: doc.data.resourceId,
+        version: doc.data.resourceVersion,
+        docType: doc.data.type,
+        docId: doc.data.id,
+        docVersion: doc.data.version,
+      },
+      props: {},
+    }));
+  }
+
+  protected static async fetchData(params: any) {
+    if (!isResourceDocsEnabled()) {
+      return null;
+    }
+
+    const decodeParam = (value: string) => {
+      try {
+        return decodeURIComponent(value);
+      } catch {
+        return value;
+      }
+    };
+
+    const type = decodeParam(params.type);
+    const id = decodeParam(params.id);
+    const version = decodeParam(params.version);
+    const docType = decodeParam(params.docType);
+    const docId = decodeParam(params.docId);
+    const docVersion = decodeParam(params.docVersion);
+    if (!type || !id || !version || !docType || !docId || !docVersion) {
+      return null;
+    }
+
+    if (!supportedResourceCollections.has(type as ResourceCollection)) {
+      return null;
+    }
+
+    const docsForResource = await getResourceDocsForResource(type as ResourceCollection, id, version);
+    const doc = docsForResource.find(
+      (resourceDoc) =>
+        resourceDoc.data.type === docType && resourceDoc.data.id === docId && resourceDoc.data.version === docVersion
+    );
+
+    if (!doc) {
+      return null;
+    }
+
+    return doc;
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Resource documentation not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/[docVersion]/index.astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/[docVersion]/index.astro
new file mode 100644
index 000000000..a48a924f0
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/[docVersion]/index.astro
@@ -0,0 +1,266 @@
+---
+import { render } from 'astro:content';
+
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import Admonition from '@components/MDX/Admonition';
+import components from '@components/MDX/components';
+import CopyAsMarkdown from '@components/CopyAsMarkdown';
+import Badge from '@components/Badge.astro';
+import { buildUrl } from '@utils/url-builder';
+import { AlignLeftIcon, HistoryIcon } from 'lucide-react';
+import { isEventCatalogChatEnabled, isResourceDocsEnabled } from '@utils/feature';
+import { getIcon } from '@utils/badges';
+import { collectionToResourceMap } from '@utils/collections/util';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+if (!isResourceDocsEnabled()) {
+  return Astro.redirect(buildUrl('/docs/custom/feature'));
+}
+
+const props = await Page.getData(Astro);
+const { Content, headings } = await render(props);
+
+const title = props.data.title || props.data.id;
+const pageTitle = `${title} | ${props.data.resourceId}`;
+const versions = props.data.versions || [props.data.version];
+const badges = (props.data.badges || []).map((badge: any) => ({
+  ...badge,
+  iconComponent: badge.icon ? getIcon(badge.icon) : null,
+}));
+
+const docsBasePath = `/docs/${props.data.resourceCollection}/${props.data.resourceId}/${props.data.resourceVersion}/${encodeURIComponent(props.data.type)}/${encodeURIComponent(props.data.id)}`;
+const singularResourceName =
+  collectionToResourceMap[props.data.resourceCollection as keyof typeof collectionToResourceMap] ??
+  props.data.resourceCollection.slice(0, props.data.resourceCollection.length - 1);
+const chatEnabled = isEventCatalogChatEnabled();
+const chatQuery = `Tell me about the ${props.data.type} doc "${title}" for ${props.data.resourceId} (version ${props.data.version})`;
+
+const pagefindAttributes =
+  props.data.version === props.data.latestVersion
+    ? {
+        'data-pagefind-body': '',
+        'data-pagefind-meta': `title:${pageTitle}`,
+      }
+    : {};
+---
+
+<VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
+  <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
+    <div class="flex docs-layout w-full">
+      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-2">
+          <div>
+            <div class="flex items-center">
+              <div class="flex items-center gap-2">
+                <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{title}</h2>
+              </div>
+            </div>
+          </div>
+          {
+            props.data.summary && (
+              <p class="text-base pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>
+            )
+          }
+          {
+            badges.length > 0 && (
+              <div class="flex flex-wrap gap-1.5 py-3">
+                {badges.map((badge: any) => <Badge badge={badge} />)}
+              </div>
+            )
+          }
+          <div class="pt-4">
+            <CopyAsMarkdown
+              client:only="react"
+              variant="toolbar"
+              schemas={[]}
+              chatQuery={chatQuery}
+              chatEnabled={chatEnabled}
+              editUrl=""
+              markdownDownloadEnabled={true}
+              rssFeedEnabled={false}
+              preferChatAsDefault={false}
+            />
+          </div>
+        </div>
+        <div data-pagefind-ignore>
+          {
+            props.data.version !== props.data.latestVersion && (
+              <Admonition type="warning" title="New version found">
+                <p>
+                  You are looking at a previous version of the {singularResourceName} doc <strong>{title}</strong>.{' '}
+                  <a class="underline block pt-2" href={buildUrl(`${docsBasePath}/${props.data.latestVersion}`)}>
+                    The latest version of this doc is <span>v{props.data.latestVersion}</span> &rarr;
+                  </a>
+                </p>
+              </Admonition>
+            )
+          }
+        </div>
+        <div class="prose py-4 max-w-none">
+          <Content components={components(props)} />
+        </div>
+      </div>
+      <aside
+        class="hidden xl:block sticky top-[4rem] self-start w-[280px] max-h-[calc(100vh-4rem)] overflow-y-auto py-2 flex-shrink-0 pr-10 bg-[rgb(var(--ec-page-bg))]"
+      >
+        <div class="mt-8 space-y-8">
+          <h3 class="text-xs text-[rgb(var(--ec-page-text))] font-semibold capitalize flex items-center gap-2 mb-4">
+            <AlignLeftIcon className="w-4 h-4" />
+            On this page
+          </h3>
+          <nav class="text-xs border-l border-[rgb(var(--ec-page-border))]">
+            {
+              headings.map((heading) => {
+                const level = heading.depth > 2 ? heading.depth : 1;
+                if (heading.depth > 3) {
+                  return null;
+                }
+                return (
+                  <a
+                    href={`#${heading.slug}`}
+                    class={`block py-1.5 pr-2.5 leading-5 text-[rgb(var(--ec-page-text-muted))] hover:border-[rgb(var(--ec-page-border))] hover:text-[rgb(var(--ec-page-text))] border-l-2 border-transparent -ml-px transition-all duration-200`}
+                    style={`padding-left: ${level * 0.75}rem`}
+                  >
+                    {heading.text}
+                  </a>
+                );
+              })
+            }
+          </nav>
+          <div class="space-y-2 pb-4">
+            <span class="text-xs text-[rgb(var(--ec-page-text))] font-semibold capitalize">Versions ({versions.length})</span>
+            <ul role="list" class="space-y-2">
+              {
+                versions.map((version: string) => (
+                  <li class="version-item rounded-md px-1 group w-full">
+                    <a class="flex items-center space-x-2" href={buildUrl(`${docsBasePath}/${encodeURIComponent(version)}`)}>
+                      <HistoryIcon
+                        className="h-4 w-4 text-[rgb(var(--ec-page-text-muted))] group-hover:text-[rgb(var(--ec-accent-text))]"
+                        strokeWidth={1}
+                      />
+                      <span
+                        class={`font-light text-xs text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-accent-text))] ${
+                          version === props.data.version ? 'underline' : ''
+                        }`}
+                      >
+                        {version === props.data.latestVersion ? `v${version} (latest)` : `v${version}`}
+                      </span>
+                    </a>
+                  </li>
+                ))
+              }
+            </ul>
+            <div class="border-b border-[rgb(var(--ec-page-border))] pt-2"></div>
+          </div>
+        </div>
+      </aside>
+    </div>
+  </main>
+</VerticalSideBarLayout>
+
+<style is:global>
+  .docs-layout .prose {
+    max-width: none;
+    overflow: auto;
+  }
+
+  .toc-active-text {
+    color: rgb(var(--ec-accent));
+  }
+
+  .toc-active-border {
+    border-color: rgb(var(--ec-accent));
+  }
+
+  .version-item:hover {
+    background: linear-gradient(to left, rgb(var(--ec-accent-gradient-from)), rgb(var(--ec-accent-gradient-to)));
+  }
+</style>
+
+<script>
+  // @ts-nocheck
+  function setupObserver() {
+    try {
+      const observerOptions = {
+        rootMargin: '0px 0px -40% 0px',
+        threshold: 0.1,
+      };
+
+      let observerPaused = false;
+
+      function highlightTocItem(id) {
+        document.querySelectorAll('.active-toc-item').forEach((link) => {
+          link.classList.remove('active-toc-item', 'toc-active-text', 'font-medium', 'toc-active-border');
+          link.classList.add('border-transparent');
+        });
+
+        const tocLink = document.querySelector(`nav a[href="#${id}"]`);
+        if (tocLink) {
+          tocLink.classList.add('active-toc-item', 'toc-active-text', 'font-medium', 'toc-active-border');
+          tocLink.classList.remove('border-transparent');
+
+          setTimeout(() => {
+            tocLink.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' });
+          }, 10);
+        }
+      }
+
+      const observer = new IntersectionObserver((entries) => {
+        if (observerPaused) return;
+
+        entries.forEach((entry) => {
+          const id = entry.target.getAttribute('id');
+          if (entry.isIntersecting && id) {
+            highlightTocItem(id);
+          }
+        });
+      }, observerOptions);
+
+      const prose = document.querySelector('.prose');
+      if (!prose) return;
+
+      const headings = prose.querySelectorAll('h1[id], h2[id], h3[id]');
+
+      if (headings.length > 0) {
+        headings.forEach((heading) => observer.observe(heading));
+      } else {
+        const allHeadings = prose.querySelectorAll('h1, h2, h3');
+        allHeadings.forEach((heading) => {
+          if (!heading.id) {
+            const text = heading.textContent || '';
+            heading.id = text
+              .toLowerCase()
+              .replace(/[^\w\s-]/g, '')
+              .replace(/\s+/g, '-');
+          }
+          observer.observe(heading);
+        });
+      }
+
+      const tocLinks = document.querySelectorAll('nav a[href^="#"]');
+      tocLinks.forEach((link) => {
+        link.addEventListener('click', () => {
+          const hrefAttr = link.getAttribute('href');
+          if (!hrefAttr) return;
+
+          const id = hrefAttr.substring(1);
+          highlightTocItem(id);
+
+          observerPaused = true;
+          setTimeout(() => {
+            observerPaused = false;
+          }, 1000);
+        });
+      });
+    } catch (error) {
+      console.error('Error setting up TOC observer:', error);
+    }
+  }
+
+  setupObserver();
+  document.addEventListener('astro:page-load', setupObserver);
+</script>
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/_index.data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/_index.data.ts
new file mode 100644
index 000000000..fe51f48fc
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/_index.data.ts
@@ -0,0 +1,86 @@
+import { isSSR, isResourceDocsEnabled } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import { getResourceDocs, getResourceDocsForResource, type ResourceCollection } from '@utils/collections/resource-docs';
+
+const supportedResourceCollections = new Set<ResourceCollection>([
+  'domains',
+  'services',
+  'events',
+  'commands',
+  'queries',
+  'flows',
+  'containers',
+  'channels',
+  'entities',
+  'data-products',
+]);
+
+export class Page extends HybridPage {
+  static async getStaticPaths() {
+    if (isSSR() || !isResourceDocsEnabled()) {
+      return [];
+    }
+
+    const docs = await getResourceDocs();
+    const latestDocs = docs.filter((doc) => doc.data.version === doc.data.latestVersion);
+
+    return latestDocs.map((doc) => ({
+      params: {
+        type: doc.data.resourceCollection,
+        id: doc.data.resourceId,
+        version: doc.data.resourceVersion,
+        docType: doc.data.type,
+        docId: doc.data.id,
+      },
+      props: {},
+    }));
+  }
+
+  protected static async fetchData(params: any) {
+    if (!isResourceDocsEnabled()) {
+      return null;
+    }
+
+    const decodeParam = (value: string) => {
+      try {
+        return decodeURIComponent(value);
+      } catch {
+        return value;
+      }
+    };
+
+    const type = decodeParam(params.type);
+    const id = decodeParam(params.id);
+    const version = decodeParam(params.version);
+    const docType = decodeParam(params.docType);
+    const docId = decodeParam(params.docId);
+    if (!type || !id || !version || !docType || !docId) {
+      return null;
+    }
+
+    if (!supportedResourceCollections.has(type as ResourceCollection)) {
+      return null;
+    }
+
+    const docsForResource = await getResourceDocsForResource(type as ResourceCollection, id, version);
+    const doc = docsForResource.find(
+      (resourceDoc) =>
+        resourceDoc.data.type === docType &&
+        resourceDoc.data.id === docId &&
+        resourceDoc.data.version === resourceDoc.data.latestVersion
+    );
+
+    if (!doc) {
+      return null;
+    }
+
+    return doc;
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Resource documentation not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/index.astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/index.astro
new file mode 100644
index 000000000..58ee3434f
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/[docType]/[docId]/index.astro
@@ -0,0 +1,258 @@
+---
+import { render } from 'astro:content';
+
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import Admonition from '@components/MDX/Admonition';
+import components from '@components/MDX/components';
+import CopyAsMarkdown from '@components/CopyAsMarkdown';
+import Badge from '@components/Badge.astro';
+import { buildUrl } from '@utils/url-builder';
+import { AlignLeftIcon, HistoryIcon } from 'lucide-react';
+import { isEventCatalogChatEnabled, isResourceDocsEnabled } from '@utils/feature';
+import { getIcon } from '@utils/badges';
+import { collectionToResourceMap } from '@utils/collections/util';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+if (!isResourceDocsEnabled()) {
+  return Astro.redirect(buildUrl('/docs/custom/feature'));
+}
+
+const props = await Page.getData(Astro);
+const { Content, headings } = await render(props);
+
+const title = props.data.title || props.data.id;
+const pageTitle = `${title} | ${props.data.resourceId}`;
+const versions = props.data.versions || [props.data.version];
+const badges = (props.data.badges || []).map((badge: any) => ({
+  ...badge,
+  iconComponent: badge.icon ? getIcon(badge.icon) : null,
+}));
+
+const docsBasePath = `/docs/${props.data.resourceCollection}/${props.data.resourceId}/${props.data.resourceVersion}/${encodeURIComponent(props.data.type)}/${encodeURIComponent(props.data.id)}`;
+const singularResourceName =
+  collectionToResourceMap[props.data.resourceCollection as keyof typeof collectionToResourceMap] ??
+  props.data.resourceCollection.slice(0, props.data.resourceCollection.length - 1);
+const chatEnabled = isEventCatalogChatEnabled();
+const chatQuery = `Tell me about the ${props.data.type} doc "${title}" for ${props.data.resourceId} (version ${props.data.version})`;
+
+const pagefindAttributes =
+  props.data.version === props.data.latestVersion
+    ? {
+        'data-pagefind-body': '',
+        'data-pagefind-meta': `title:${pageTitle}`,
+      }
+    : {};
+---
+
+<VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
+  <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
+    <div class="flex docs-layout w-full">
+      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-2">
+          <div class="flex flex-col gap-4">
+            <div class="flex items-center gap-4">
+              <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{title}</h2>
+            </div>
+            {props.data.summary && <p class="text-base text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</p>}
+            {
+              badges.length > 0 && (
+                <div class="flex flex-wrap gap-1.5 py-1">
+                  {badges.map((badge: any) => <Badge badge={badge} />)}
+                </div>
+              )
+            }
+            <CopyAsMarkdown
+              client:only="react"
+              variant="toolbar"
+              schemas={[]}
+              chatQuery={chatQuery}
+              chatEnabled={chatEnabled}
+              editUrl=""
+              markdownDownloadEnabled={true}
+              rssFeedEnabled={false}
+              preferChatAsDefault={false}
+            />
+          </div>
+        </div>
+        <div data-pagefind-ignore>
+          {
+            props.data.version !== props.data.latestVersion && (
+              <Admonition type="warning" title="New version found">
+                <p>
+                  You are looking at a previous version of the {singularResourceName} doc <strong>{title}</strong>.{' '}
+                  <a class="underline block pt-2" href={buildUrl(`${docsBasePath}/${props.data.latestVersion}`)}>
+                    The latest version of this doc is <span>v{props.data.latestVersion}</span> &rarr;
+                  </a>
+                </p>
+              </Admonition>
+            )
+          }
+        </div>
+        <div class="prose py-4 max-w-none">
+          <Content components={components(props)} />
+        </div>
+      </div>
+      <aside
+        class="hidden xl:block sticky top-[4rem] self-start w-[280px] max-h-[calc(100vh-4rem)] overflow-y-auto py-2 flex-shrink-0 pr-10 bg-[rgb(var(--ec-page-bg))]"
+      >
+        <div class="mt-8 space-y-8">
+          <h3 class="text-xs text-[rgb(var(--ec-page-text))] font-semibold capitalize flex items-center gap-2 mb-4">
+            <AlignLeftIcon className="w-4 h-4" />
+            On this page
+          </h3>
+          <nav class="text-xs border-l border-[rgb(var(--ec-page-border))]">
+            {
+              headings.map((heading) => {
+                const level = heading.depth > 2 ? heading.depth : 1;
+                if (heading.depth > 3) {
+                  return null;
+                }
+                return (
+                  <a
+                    href={`#${heading.slug}`}
+                    class={`block py-1.5 pr-2.5 leading-5 text-[rgb(var(--ec-page-text-muted))] hover:border-[rgb(var(--ec-page-border))] hover:text-[rgb(var(--ec-page-text))] border-l-2 border-transparent -ml-px transition-all duration-200`}
+                    style={`padding-left: ${level * 0.75}rem`}
+                  >
+                    {heading.text}
+                  </a>
+                );
+              })
+            }
+          </nav>
+          <div class="space-y-2 pb-4">
+            <span class="text-xs text-[rgb(var(--ec-page-text))] font-semibold capitalize">Versions ({versions.length})</span>
+            <ul role="list" class="space-y-2">
+              {
+                versions.map((version: string) => (
+                  <li class="version-item rounded-md px-1 group w-full">
+                    <a class="flex items-center space-x-2" href={buildUrl(`${docsBasePath}/${encodeURIComponent(version)}`)}>
+                      <HistoryIcon
+                        className="h-4 w-4 text-[rgb(var(--ec-page-text-muted))] group-hover:text-[rgb(var(--ec-accent-text))]"
+                        strokeWidth={1}
+                      />
+                      <span
+                        class={`font-light text-xs text-[rgb(var(--ec-page-text))] group-hover:text-[rgb(var(--ec-accent-text))] ${
+                          version === props.data.version ? 'underline' : ''
+                        }`}
+                      >
+                        {version === props.data.latestVersion ? `v${version} (latest)` : `v${version}`}
+                      </span>
+                    </a>
+                  </li>
+                ))
+              }
+            </ul>
+            <div class="border-b border-[rgb(var(--ec-page-border))] pt-2"></div>
+          </div>
+        </div>
+      </aside>
+    </div>
+  </main>
+</VerticalSideBarLayout>
+
+<style is:global>
+  .docs-layout .prose {
+    max-width: none;
+    overflow: auto;
+  }
+
+  .toc-active-text {
+    color: rgb(var(--ec-accent));
+  }
+
+  .toc-active-border {
+    border-color: rgb(var(--ec-accent));
+  }
+
+  .version-item:hover {
+    background: linear-gradient(to left, rgb(var(--ec-accent-gradient-from)), rgb(var(--ec-accent-gradient-to)));
+  }
+</style>
+
+<script>
+  // @ts-nocheck
+  function setupObserver() {
+    try {
+      const observerOptions = {
+        rootMargin: '0px 0px -40% 0px',
+        threshold: 0.1,
+      };
+
+      let observerPaused = false;
+
+      function highlightTocItem(id) {
+        document.querySelectorAll('.active-toc-item').forEach((link) => {
+          link.classList.remove('active-toc-item', 'toc-active-text', 'font-medium', 'toc-active-border');
+          link.classList.add('border-transparent');
+        });
+
+        const tocLink = document.querySelector(`nav a[href="#${id}"]`);
+        if (tocLink) {
+          tocLink.classList.add('active-toc-item', 'toc-active-text', 'font-medium', 'toc-active-border');
+          tocLink.classList.remove('border-transparent');
+
+          setTimeout(() => {
+            tocLink.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' });
+          }, 10);
+        }
+      }
+
+      const observer = new IntersectionObserver((entries) => {
+        if (observerPaused) return;
+
+        entries.forEach((entry) => {
+          const id = entry.target.getAttribute('id');
+          if (entry.isIntersecting && id) {
+            highlightTocItem(id);
+          }
+        });
+      }, observerOptions);
+
+      const prose = document.querySelector('.prose');
+      if (!prose) return;
+
+      const headings = prose.querySelectorAll('h1[id], h2[id], h3[id]');
+
+      if (headings.length > 0) {
+        headings.forEach((heading) => observer.observe(heading));
+      } else {
+        const allHeadings = prose.querySelectorAll('h1, h2, h3');
+        allHeadings.forEach((heading) => {
+          if (!heading.id) {
+            const text = heading.textContent || '';
+            heading.id = text
+              .toLowerCase()
+              .replace(/[^\w\s-]/g, '')
+              .replace(/\s+/g, '-');
+          }
+          observer.observe(heading);
+        });
+      }
+
+      const tocLinks = document.querySelectorAll('nav a[href^="#"]');
+      tocLinks.forEach((link) => {
+        link.addEventListener('click', () => {
+          const hrefAttr = link.getAttribute('href');
+          if (!hrefAttr) return;
+
+          const id = hrefAttr.substring(1);
+          highlightTocItem(id);
+
+          observerPaused = true;
+          setTimeout(() => {
+            observerPaused = false;
+          }, 1000);
+        });
+      });
+    } catch (error) {
+      console.error('Error setting up TOC observer:', error);
+    }
+  }
+
+  setupObserver();
+  document.addEventListener('astro:page-load', setupObserver);
+</script>
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/_index.data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/_index.data.ts
new file mode 100644
index 000000000..37759955c
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/_index.data.ts
@@ -0,0 +1,73 @@
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import type { PageTypes } from '@types';
+import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
+
+/**
+ * Documentation page class for all collection types with versioning
+ */
+export class Page extends HybridPage {
+  static async getStaticPaths() {
+    if (isSSR()) {
+      return [];
+    }
+
+    const itemTypes: PageTypes[] = [
+      'agents',
+      'adrs',
+      'events',
+      'commands',
+      'queries',
+      'services',
+      'domains',
+      'systems',
+      'flows',
+      'channels',
+      'entities',
+      'containers',
+      'data-products',
+    ];
+    const allItems = await Promise.all(itemTypes.map((type) => pageDataLoader[type]()));
+
+    return allItems.flatMap((items, index) =>
+      items.map((item) => ({
+        params: {
+          type: itemTypes[index],
+          id: item.data.id,
+          version: item.data.version,
+        },
+        props: {},
+      }))
+    );
+  }
+
+  protected static async fetchData(params: any) {
+    const { type, id, version } = params;
+
+    if (!type || !id || !version) {
+      return null;
+    }
+
+    // Get all items of the specified type
+    const items = await pageDataLoader[type as PageTypes]();
+
+    // Find the specific item by id and version
+    const item = items.find((i) => i.data.id === id && i.data.version === version);
+
+    if (!item) {
+      return null;
+    }
+
+    return {
+      type,
+      ...item,
+    };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Documentation not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/asyncapi/[filename].astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/asyncapi/[filename].astro
new file mode 100644
index 000000000..92d71beff
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/asyncapi/[filename].astro
@@ -0,0 +1,239 @@
+---
+import { createElement } from 'react';
+import { renderToString } from 'react-dom/server';
+import { Parser } from '@asyncapi/parser';
+import { AvroSchemaParser } from '@asyncapi/avro-schema-parser';
+import fs from 'fs';
+
+import { isSameOrigin, resolveHeaders } from '@utils/remote-spec';
+
+import '@asyncapi/react-component/styles/default.min.css';
+import js from '@asyncapi/react-component/browser/standalone/without-parser.js?url';
+import { AsyncApiComponentWP, type ConfigInterface } from '@asyncapi/react-component';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import CopyAsMarkdown from '@components/CopyAsMarkdown';
+import { isEventCatalogChatEnabled } from '@utils/feature';
+import Config from '@utils/eventcatalog-config/catalog';
+import { Page } from './_[filename].data';
+import { getAbsoluteFilePathForAstroFile } from '@utils/files';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const { collection, data, filePath, filename, path: relativeSpecPath, headers = {} } = await Page.getData(Astro);
+
+const fileName = filename || 'asyncapi.yaml';
+const pathToSpec = getAbsoluteFilePathForAstroFile(filePath, fileName);
+const fileExists = fs.existsSync(pathToSpec);
+const isRemote = relativeSpecPath.includes('https://');
+let content = '';
+
+const allowAnyEnvInSpecHeaders = Config?.asyncAPI?.allowAnyEnvInSpecHeaders ?? false;
+const resolvedHeaders = resolveHeaders(headers, { allowAnyEnvInHeaders: allowAnyEnvInSpecHeaders });
+
+if (fileExists && !isRemote) {
+  content = fs.readFileSync(pathToSpec, 'utf8');
+}
+
+if (isRemote) {
+  const response = await fetch(relativeSpecPath, { headers: resolvedHeaders });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch AsyncAPI spec: ${response.status} ${response.statusText}`);
+  }
+
+  content = await response.text();
+}
+
+// AsyncAPI parser will parse schemas for users, they can turn this off.
+const parseSchemas = Config?.asyncAPI?.renderParsedSchemas ?? true;
+const parserOptions: NonNullable<Parameters<Parser['parse']>[1]> = {
+  parseSchemas,
+  source: isRemote ? relativeSpecPath : pathToSpec,
+};
+
+if (isRemote && Object.keys(resolvedHeaders).length > 0) {
+  // NOTE: AsyncAPI parser exposes resolver wiring via __unstable.
+  // Keep this isolated so parser upgrades can adjust in one place.
+  const resolverWithHeaders = {
+    canRead: true,
+    read: async (uri: { toString: () => string }) => {
+      const targetUrl = uri.toString();
+      const shouldForwardHeaders = isSameOrigin(relativeSpecPath, targetUrl);
+
+      const response = await fetch(targetUrl, {
+        headers: shouldForwardHeaders ? resolvedHeaders : undefined,
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch reference: ${response.status} ${response.statusText}`);
+      }
+
+      return response.text();
+    },
+  };
+
+  parserOptions.__unstable = {
+    resolver: {
+      resolvers: [
+        { schema: 'https', ...resolverWithHeaders },
+        { schema: 'http', ...resolverWithHeaders },
+      ],
+    },
+  };
+}
+
+const parsed = await new Parser({ schemaParsers: [AvroSchemaParser()] }).parse(content, parserOptions);
+
+/**
+ * The AsyncAPI parser resolves all $ref pointers, which can create circular
+ * object references (e.g. oneOf/allOf discriminator patterns where child schemas
+ * reference the parent). We need to break true cycles before Astro's
+ * `define:vars` calls JSON.stringify internally.
+ *
+ * We track ancestors (not all-ever-seen objects) so that shared but
+ * non-circular references are preserved intact.
+ * See: https://github.com/event-catalog/generators/issues/364
+ */
+const deepCopyBreakingCycles = (value: unknown, ancestors = new WeakSet()): unknown => {
+  if (typeof value !== 'object' || value === null) return value;
+
+  if (ancestors.has(value)) {
+    const schemaId = (value as Record<string, unknown>)['x-parser-schema-id'];
+    if (schemaId && typeof schemaId === 'string') {
+      return { $ref: `#/components/schemas/${schemaId}` };
+    }
+    return { $ref: '#' };
+  }
+
+  ancestors.add(value);
+
+  let result: unknown;
+  if (Array.isArray(value)) {
+    result = value.map((item) => deepCopyBreakingCycles(item, ancestors));
+  } else {
+    const obj: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      obj[k] = deepCopyBreakingCycles(v, ancestors);
+    }
+    result = obj;
+  }
+
+  ancestors.delete(value);
+  return result;
+};
+
+const rawJson = parsed.document?.json();
+const stringified = rawJson ? deepCopyBreakingCycles(rawJson) : undefined;
+const config: ConfigInterface = { show: { sidebar: true, errors: true } };
+
+const component = createElement(AsyncApiComponentWP, { schema: { stringified }, config });
+const renderedComponent = renderToString(component);
+
+// Capitalize the first letter of a string
+const pageTitle = `${collection} | ${data.name} | AsyncApi Spec`.replace(/^\w/, (c) => c.toUpperCase());
+
+// Chat configuration
+const chatEnabled = isEventCatalogChatEnabled();
+const chatQuery = `Tell me about the AsyncAPI specification for "${data.name}" (version ${data.version})`;
+
+// Index only the latest version
+const pagefindAttributes =
+  data.version === data.latestVersion
+    ? {
+        'data-pagefind-body': '',
+        'data-pagefind-meta': `title:${pageTitle}`,
+      }
+    : {};
+---
+
+<VerticalSideBarLayout title={pageTitle}>
+  <div
+    {...pagefindAttributes}
+    class="relative"
+    style="margin-left: calc(var(--ec-app-content-padding-left, 5rem) * -1); margin-right: calc(var(--ec-app-content-padding-right, 5rem) * -1);"
+  >
+    {
+      // Currently, Pagefind does not index metadata (such as the title),
+      // so we need to ensure it is included as text on the page.
+      // https://github.com/CloudCannon/pagefind/issues/437
+    }
+    <h2 class="hidden">{pageTitle}</h2>
+    {
+      chatEnabled && (
+        <div class="absolute top-3 right-4 z-10">
+          <CopyAsMarkdown
+            client:only="react"
+            schemas={[]}
+            chatQuery={chatQuery}
+            chatEnabled={chatEnabled}
+            editUrl=""
+            markdownDownloadEnabled={false}
+            rssFeedEnabled={false}
+            preferChatAsDefault={true}
+            chatButtonText="Ask about this specification"
+          />
+        </div>
+      )
+    }
+    <div id="asyncapi" class="not-prose" set:html={renderedComponent} />
+  </div>
+</VerticalSideBarLayout>
+
+<script is:inline src={js}></script>
+<script is:inline define:vars={{ schema: stringified, config }}>
+  function initAsyncApi() {
+    const root = document.getElementById('asyncapi');
+    if (!root || root.dataset.initialized) return;
+
+    if (typeof AsyncApiStandalone !== 'undefined') {
+      AsyncApiStandalone.render({ schema, config }, root);
+      root.dataset.initialized = 'true';
+    } else {
+      setTimeout(initAsyncApi, 50);
+    }
+  }
+
+  document.addEventListener('astro:page-load', initAsyncApi);
+  initAsyncApi();
+</script>
+
+<style>
+  #asyncapi {
+    @media screen and (min-width: 1417px) {
+      .sidebar {
+        z-index: 1 !important;
+      }
+    }
+
+    .burger-menu {
+      display: none;
+    }
+
+    .aui-root .z-10 {
+      z-index: 8;
+    }
+  }
+
+  /* Keep AsyncAPI markdown code blocks isolated from EventCatalog dark prose overrides. */
+  :root[data-theme='dark'] #asyncapi .aui-root .prose code {
+    color: #1a202c;
+    background-color: transparent;
+    border-radius: 0;
+    padding: 0;
+  }
+
+  :root[data-theme='dark'] #asyncapi .aui-root .prose pre {
+    color: #edf2f7;
+    background-color: #1a202c;
+    border: 0;
+  }
+
+  :root[data-theme='dark'] #asyncapi .aui-root .prose pre code {
+    color: inherit;
+    background-color: transparent;
+    border-radius: 0;
+    padding: 0;
+  }
+</style>
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version]/asyncapi/_[filename].data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/asyncapi/_[filename].data.ts
similarity index 100%
rename from eventcatalog/src/pages/docs/[type]/[id]/[version]/asyncapi/_[filename].data.ts
rename to packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/asyncapi/_[filename].data.ts
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/_index.data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/_index.data.ts
new file mode 100644
index 000000000..055166e53
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/_index.data.ts
@@ -0,0 +1,78 @@
+import { isSSR, isChangelogEnabled } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import type { PageTypes } from '@types';
+
+export class Page extends HybridPage {
+  static get prerender(): boolean {
+    return !isSSR();
+  }
+
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isSSR() || !isChangelogEnabled()) {
+      return [];
+    }
+
+    const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
+
+    const itemTypes: PageTypes[] = [
+      'agents',
+      'events',
+      'commands',
+      'queries',
+      'services',
+      'domains',
+      'systems',
+      'flows',
+      'containers',
+    ];
+    const allItems = await Promise.all(itemTypes.map((type) => pageDataLoader[type]()));
+
+    return allItems.flatMap((items, index) =>
+      items.map((item) => ({
+        params: {
+          type: itemTypes[index],
+          id: item.data.id,
+          version: item.data.version,
+        },
+        props: {
+          type: itemTypes[index],
+          allCollectionItems: items,
+          ...item,
+        },
+      }))
+    );
+  }
+
+  protected static async fetchData(params: any) {
+    const { type, id, version } = params;
+
+    if (!type || !id || !version || !isChangelogEnabled()) {
+      return null;
+    }
+
+    const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
+
+    // Get all items of the specified type
+    const items = await pageDataLoader[type as PageTypes]();
+
+    // Find the specific item by id and version
+    const item = items.find((i) => i.data.id === id && i.data.version === version);
+
+    if (!item) {
+      return null;
+    }
+
+    return {
+      type,
+      allCollectionItems: items,
+      ...item,
+    };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Changelog not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/index.astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/index.astro
new file mode 100644
index 000000000..5336b8fb2
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/index.astro
@@ -0,0 +1,210 @@
+---
+import Footer from '@layouts/Footer.astro';
+import { getChangeLogs } from '@utils/collections/changelogs';
+import {
+  RectangleGroupIcon,
+  ServerIcon,
+  BoltIcon,
+  ChatBubbleLeftIcon,
+  MagnifyingGlassIcon,
+  QueueListIcon,
+} from '@heroicons/react/24/outline';
+import { DatabaseIcon } from 'lucide-react';
+import { render, getEntry } from 'astro:content';
+import mdxComponents from '@components/MDX/components';
+import 'diff2html/bundles/css/diff2html.min.css';
+
+import { buildUrl } from '@utils/url-builder';
+import { getPreviousVersion } from '@utils/collections/util';
+import { getDiffsForCurrentAndPreviousVersion } from '@utils/file-diffs';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import Badge from '@components/Badge.astro';
+import { ClientRouter } from 'astro:transitions';
+import { isChangelogEnabled } from '@utils/feature';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+let collectionItem = props;
+const logs = await getChangeLogs(props);
+
+const { data } = props;
+const latestVersion = data.latestVersion;
+
+const renderedLogs = logs.map(async (log) => {
+  const logEntry = await getEntry('changelogs', log.id);
+  const { Content } = await render(logEntry as any);
+  return {
+    Content,
+    ...log,
+  };
+});
+
+const logsToRender = await Promise.all(renderedLogs);
+
+const logListPromise = logsToRender.map(async (log, index) => {
+  const currentLogVersion = log.data.version;
+  const previousLogVersion = log.data.version ? getPreviousVersion(log.data.version, data.versions || []) : '';
+  return {
+    id: log.id,
+    url: buildUrl(`/docs/${props.collection}/${props.data.id}`),
+    isLatest: log.data.version === latestVersion,
+    version: log.data.version,
+    createdAt: log.data.createdAt,
+    badges: log.data.badges || [],
+    Content: log.Content,
+    diffs:
+      currentLogVersion && previousLogVersion
+        ? await getDiffsForCurrentAndPreviousVersion(
+            currentLogVersion,
+            previousLogVersion,
+            collectionItem.data.id,
+            props.allCollectionItems
+          )
+        : [],
+  };
+});
+
+const logList = await Promise.all(logListPromise);
+
+const createResourceBadge = (content: string, icon: any) => ({ content, icon, textColor: 'gray' });
+
+const getBadge = () => {
+  if (props.collection === 'services') {
+    return createResourceBadge('Service', ServerIcon);
+  }
+  if (props.collection === 'events') {
+    return createResourceBadge('Event', BoltIcon);
+  }
+  if (props.collection === 'commands') {
+    return createResourceBadge('Command', ChatBubbleLeftIcon);
+  }
+  if (props.collection === 'queries') {
+    return createResourceBadge('Query', MagnifyingGlassIcon);
+  }
+  if (props.collection === 'domains') {
+    return createResourceBadge('Domain', RectangleGroupIcon);
+  }
+  if (props.collection === 'containers') {
+    return createResourceBadge('Container', DatabaseIcon);
+  }
+  if (props.collection === 'flows') {
+    return createResourceBadge('Flow', QueueListIcon);
+  }
+};
+
+const badges = [getBadge()];
+---
+
+<VerticalSideBarLayout title="ChangeLog">
+  <main class="w-full md:pt-4 px-8 overflow-y-auto h-full max-w-[95%]">
+    <nav aria-label="Breadcrumb" class="flex">
+      <ol role="list" class="flex items-center space-x-2">
+        <li>
+          <div>
+            <a
+              href={buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.version}`)}
+              class="text-sm font-medium text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]"
+            >
+              {props.data.name}
+            </a>
+          </div>
+        </li>
+        <li>
+          <div class="flex items-center">
+            <svg
+              fill="currentColor"
+              viewBox="0 0 20 20"
+              aria-hidden="true"
+              class="h-5 w-5 flex-shrink-0 text-[rgb(var(--ec-page-border))]"
+            >
+              <path d="M5.555 17.776l8-16 .894.448-8 16-.894-.448z"></path>
+            </svg>
+            <a
+              href={buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.version}`)}
+              class="text-sm font-medium text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]"
+            >
+              Changelog
+            </a>
+          </div>
+        </li>
+      </ol>
+    </nav>
+    <div class="border-b border-[rgb(var(--ec-page-border))] flex justify-between items-start py-4 w-full">
+      <div>
+        <h2 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{props.data.name} (Changelog)</h2>
+        <h2 class="text-lg pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</h2>
+        {
+          badges && (
+            <div class="flex flex-wrap py-2 pt-4">
+              {badges.map((badge: any) => (
+                <Badge badge={badge} className="mr-2 px-2 py-1 rounded-md" />
+              ))}
+            </div>
+          )
+        }
+      </div>
+    </div>
+    {
+      logList.length === 0 && (
+        <div class="py-4 text-[rgb(var(--ec-page-text-muted))] prose prose-md">
+          <p>No changelogs found.</p>
+        </div>
+      )
+    }
+    <div class="flow-root py-8 w-full">
+      <ul role="list" class="-mb-8">
+        {
+          logList.map((log, index) => (
+            <li>
+              <div class="relative pb-8">
+                {index !== logList.length - 1 ? (
+                  <span aria-hidden="true" class="absolute left-6 top-4 -ml-px h-full w-0.5 bg-[rgb(var(--ec-page-border))]" />
+                ) : null}
+                <div class="relative flex space-x-3">
+                  <div>
+                    <a
+                      href={buildUrl(`${log.url}/${log.version}`)}
+                      class="bg-primary hover:bg-primary/80 text-white flex h-8 w-14 items-center justify-center rounded-full ring-8 ring-[rgb(var(--ec-page-bg))]"
+                    >
+                      {log.version}
+                    </a>
+                  </div>
+                </div>
+                <div class="pl-[70px] py-2 -mt-10">
+                  {log.createdAt && (
+                    <div class="pb-2">
+                      <h3 class="text-2xl text-[rgb(var(--ec-page-text))] font-bold">
+                        <span>
+                          {log.createdAt.toISOString().split('T')[0]} {`${log.isLatest ? '(latest)' : ''}`}
+                        </span>
+                      </h3>
+                    </div>
+                  )}
+                  {log.badges && (
+                    <div class="flex flex-wrap">
+                      {log.badges.map((badge: any) => (
+                        <Badge badge={badge} className="mr-2 px-2 py-1 rounded-md" />
+                      ))}
+                    </div>
+                  )}
+                  <div class="prose prose-md max-w-none! py-2">
+                    <log.Content components={mdxComponents(props)} />
+                  </div>
+                  {log.diffs && log.diffs.map((diff) => <div class="bg-white rounded-lg p-2 my-2" set:html={diff} />)}
+                </div>
+              </div>
+            </li>
+          ))
+        }
+      </ul>
+    </div>
+    <Footer />
+  </main>
+  <ClientRouter />
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/examples/[...filename].astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/examples/[...filename].astro
new file mode 100644
index 000000000..34f3f7131
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/examples/[...filename].astro
@@ -0,0 +1,48 @@
+---
+import { Code } from 'astro-expressive-code/components';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import Footer from '@layouts/Footer.astro';
+import { Page } from './_[...filename].data';
+import { getLanguageForHighlight } from '@components/SchemaExplorer/utils';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+const props = await Page.getData(Astro);
+const { collection, data, example } = props;
+
+const pageTitle = `${collection} | ${data.name} | ${example.title}`.replace(/^\w/, (c: string) => c.toUpperCase());
+const lang = getLanguageForHighlight(example.extension);
+---
+
+<VerticalSideBarLayout title={pageTitle} description={`Example: ${example.title} for ${data.name}`}>
+  <main class="flex sm:px-8 docs-layout min-h-full">
+    <div class="flex docs-layout w-full">
+      <div class="w-full lg:mr-2 pr-8 py-8">
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-4">
+          <h1 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))] mb-2">
+            {example.title}
+          </h1>
+          <h2 class="text-lg text-[rgb(var(--ec-page-text-muted))] font-medium mb-1">
+            Example for {data.name} <span class="text-[rgb(var(--ec-page-text-muted))]">(v{data.version})</span>
+          </h2>
+        </div>
+
+        <div class="mt-6">
+          <div class="not-prose overflow-x-auto">
+            <Code code={example.content} title={example.fileName} lang={lang} />
+          </div>
+        </div>
+
+        <Footer />
+      </div>
+    </div>
+  </main>
+
+  <style is:global>
+    .docs-layout .prose {
+      max-width: none;
+      overflow: auto;
+    }
+  </style>
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/examples/_[...filename].data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/examples/_[...filename].data.ts
new file mode 100644
index 000000000..f22dbae2b
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/examples/_[...filename].data.ts
@@ -0,0 +1,63 @@
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import type { PageTypes } from '@types';
+import { getExamplesForResource } from '@utils/collections/examples';
+
+const MESSAGE_TYPES: PageTypes[] = ['events', 'commands', 'queries'];
+
+// Normalize path separators to forward slashes for URL matching
+const toUrlPath = (filePath: string) => filePath.replace(/\\/g, '/');
+
+export class Page extends HybridPage {
+  static get prerender(): boolean {
+    return !isSSR();
+  }
+
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isSSR()) {
+      return [];
+    }
+
+    const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
+    const allItems = await Promise.all(MESSAGE_TYPES.map((type) => pageDataLoader[type]()));
+
+    return allItems.flatMap((items, index) =>
+      items.flatMap((item) => {
+        const examples = getExamplesForResource(item);
+        return examples.map((example) => ({
+          params: {
+            type: MESSAGE_TYPES[index],
+            id: item.data.id,
+            version: item.data.version,
+            filename: toUrlPath(example.fileName),
+          },
+          props: {
+            type: MESSAGE_TYPES[index],
+            example,
+            ...item,
+          },
+        }));
+      })
+    );
+  }
+
+  protected static async fetchData(params: any) {
+    const { type, id, version, filename } = params;
+    if (!type || !id || !version || !filename) return null;
+
+    const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
+    const items = await pageDataLoader[type as PageTypes]();
+    const item = items.find((i) => i.data.id === id && i.data.version === version);
+    if (!item) return null;
+
+    const examples = getExamplesForResource(item);
+    const example = examples.find((ex) => toUrlPath(ex.fileName) === filename);
+    if (!example) return null;
+
+    return { type, example, ...item };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, { status: 404, statusText: 'Example not found' });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/field-lineage/_index.data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/field-lineage/_index.data.ts
new file mode 100644
index 000000000..831874ca1
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/field-lineage/_index.data.ts
@@ -0,0 +1,64 @@
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import type { PageTypes } from '@types';
+
+const MESSAGE_TYPES: PageTypes[] = ['events', 'commands', 'queries'];
+
+export class Page extends HybridPage {
+  static get prerender(): boolean {
+    return !isSSR();
+  }
+
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isSSR()) {
+      return [];
+    }
+
+    const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
+
+    const allItems = await Promise.all(MESSAGE_TYPES.map((type) => pageDataLoader[type]()));
+
+    return allItems.flatMap((items, index) =>
+      items.map((item) => ({
+        params: {
+          type: MESSAGE_TYPES[index],
+          id: item.data.id,
+          version: item.data.version,
+        },
+        props: {
+          type: MESSAGE_TYPES[index],
+          ...item,
+        },
+      }))
+    );
+  }
+
+  protected static async fetchData(params: any) {
+    const { type, id, version } = params;
+
+    if (!type || !id || !version || !MESSAGE_TYPES.includes(type)) {
+      return null;
+    }
+
+    const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
+
+    const items = await pageDataLoader[type as PageTypes]();
+    const item = items.find((i) => i.data.id === id && i.data.version === version);
+
+    if (!item) {
+      return null;
+    }
+
+    return {
+      type,
+      ...item,
+    };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Field usage not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/field-lineage/index.astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/field-lineage/index.astro
new file mode 100644
index 000000000..b6fe20b35
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/field-lineage/index.astro
@@ -0,0 +1,368 @@
+---
+import Footer from '@layouts/Footer.astro';
+import { BoltIcon, ChatBubbleLeftIcon, MagnifyingGlassIcon, ServerIcon } from '@heroicons/react/24/outline';
+import { getCollection } from 'astro:content';
+import path from 'node:path';
+
+import { buildUrl } from '@utils/url-builder';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { ClientRouter } from 'astro:transitions';
+import { satisfies } from '@utils/collections/util';
+import { readResourceFile } from '@utils/resource-files';
+import { extractSchemaProperties, type SchemaProperty } from '@utils/schema-utils';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+const { data, collection } = props;
+const messageId = data.id;
+const messageVersion = data.version;
+const latestVersion = data.latestVersion || messageVersion;
+
+// Get all services to find field usage
+const allServices = await getCollection('services');
+
+const matchesVersion = (pointerVersion: string | undefined) => {
+  if (pointerVersion === 'latest' || pointerVersion === undefined) {
+    return messageVersion === latestVersion;
+  }
+  return satisfies(messageVersion, pointerVersion);
+};
+
+// Read schema and extract property metadata
+const schemaPropertyMap = new Map<string, SchemaProperty>();
+if (data.schemaPath) {
+  const schemaContent = readResourceFile(props, data.schemaPath);
+  if (schemaContent) {
+    const format = path.extname(data.schemaPath).slice(1);
+    const properties = extractSchemaProperties(schemaContent, format);
+    for (const prop of properties) {
+      schemaPropertyMap.set(prop.name, prop);
+    }
+  }
+}
+
+// Build field usage: field → list of { service, direction }
+type FieldConsumer = {
+  resourceId: string;
+  resourceName: string;
+  resourceVersion: string;
+  direction: 'receives' | 'sends';
+};
+
+const fieldMap = new Map<string, FieldConsumer[]>();
+
+// Scan services
+for (const service of allServices) {
+  for (const pointer of service.data.receives || []) {
+    if (pointer.id === messageId && matchesVersion(pointer.version) && pointer.fields?.length) {
+      for (const field of pointer.fields) {
+        if (!fieldMap.has(field)) fieldMap.set(field, []);
+        fieldMap.get(field)!.push({
+          resourceId: service.data.id,
+          resourceName: service.data.name || service.data.id,
+          resourceVersion: service.data.version,
+          direction: 'receives',
+        });
+      }
+    }
+  }
+  for (const pointer of service.data.sends || []) {
+    if (pointer.id === messageId && matchesVersion(pointer.version) && pointer.fields?.length) {
+      for (const field of pointer.fields) {
+        if (!fieldMap.has(field)) fieldMap.set(field, []);
+        fieldMap.get(field)!.push({
+          resourceId: service.data.id,
+          resourceName: service.data.name || service.data.id,
+          resourceVersion: service.data.version,
+          direction: 'sends',
+        });
+      }
+    }
+  }
+}
+
+// Ensure all schema properties appear, even without consumers
+for (const [name] of schemaPropertyMap) {
+  if (!fieldMap.has(name)) {
+    fieldMap.set(name, []);
+  }
+}
+
+// Split into matched (in schema or no schema exists) and unmatched (declared but not in schema)
+const hasSchema = schemaPropertyMap.size > 0;
+const matchedFields: [string, FieldConsumer[]][] = [];
+const unmatchedFields: [string, FieldConsumer[]][] = [];
+
+for (const [field, consumers] of fieldMap) {
+  if (!hasSchema || schemaPropertyMap.has(field)) {
+    matchedFields.push([field, consumers]);
+  } else if (consumers.length > 0) {
+    // Only show unmatched if someone actually declared this field
+    unmatchedFields.push([field, consumers]);
+  }
+}
+
+const sortedFields = matchedFields.sort(([a], [b]) => a.localeCompare(b));
+const sortedUnmatchedFields = unmatchedFields.sort(([a], [b]) => a.localeCompare(b));
+
+const getBadge = () => {
+  if (collection === 'events') {
+    return { badgeType: 'event', content: 'Event', icon: BoltIcon };
+  }
+  if (collection === 'commands') {
+    return { badgeType: 'command', content: 'Command', icon: ChatBubbleLeftIcon };
+  }
+  if (collection === 'queries') {
+    return { badgeType: 'query', content: 'Query', icon: MagnifyingGlassIcon };
+  }
+};
+
+const badge = getBadge();
+---
+
+<VerticalSideBarLayout title="Field Usage">
+  <main class="w-full md:pt-4 px-8 overflow-y-auto h-full max-w-[95%]">
+    <nav aria-label="Breadcrumb" class="flex">
+      <ol role="list" class="flex items-center space-x-2">
+        <li>
+          <div>
+            <a
+              href={buildUrl(`/docs/${collection}/${data.id}/${data.version}`)}
+              class="text-sm font-medium text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]"
+            >
+              {data.name}
+            </a>
+          </div>
+        </li>
+        <li>
+          <div class="flex items-center">
+            <svg
+              fill="currentColor"
+              viewBox="0 0 20 20"
+              aria-hidden="true"
+              class="h-5 w-5 flex-shrink-0 text-[rgb(var(--ec-page-border))]"
+            >
+              <path d="M5.555 17.776l8-16 .894.448-8 16-.894-.448z"></path>
+            </svg>
+            <span class="text-sm font-medium text-[rgb(var(--ec-page-text-muted))]"> Field Usage </span>
+          </div>
+        </li>
+      </ol>
+    </nav>
+    <div class="border-b border-[rgb(var(--ec-page-border))] flex justify-between items-start py-4 w-full">
+      <div>
+        <h2 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{data.name} (Field Usage)</h2>
+        <h2 class="text-lg pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">
+          Track which services depend on specific fields of this message.
+        </h2>
+        {
+          badge && (
+            <div class="flex flex-wrap items-center gap-2 py-2 pt-4">
+              <span
+                class="text-sm font-medium px-2 py-1 rounded-md space-x-1 flex items-center"
+                style={`background-color: rgb(var(--ec-badge-${badge.badgeType}-bg)); color: rgb(var(--ec-badge-${badge.badgeType}-text));`}
+              >
+                {badge.icon && <badge.icon className="w-4 h-4 inline-block mr-1" />}
+                <span>{badge.content}</span>
+              </span>
+              <button
+                id="filter-consumed-btn"
+                type="button"
+                class="inline-flex items-center gap-1.5 px-2 py-1 text-xs rounded-md border border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-card-bg))] transition-colors"
+              >
+                <svg
+                  xmlns="http://www.w3.org/2000/svg"
+                  class="h-3.5 w-3.5"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                  stroke="currentColor"
+                  stroke-width="2"
+                >
+                  <path
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                    d="M3 4a1 1 0 011-1h16a1 1 0 011 1v2.586a1 1 0 01-.293.707l-6.414 6.414a1 1 0 00-.293.707V17l-4 4v-6.586a1 1 0 00-.293-.707L3.293 7.293A1 1 0 013 6.586V4z"
+                  />
+                </svg>
+                <span id="filter-consumed-label">Consumed only</span>
+              </button>
+            </div>
+          )
+        }
+      </div>
+    </div>
+
+    {
+      sortedFields.length === 0 && (
+        <div class="py-8 text-[rgb(var(--ec-page-text-muted))]">
+          <p>
+            No field usage data found. Services can declare which fields they depend on using the{' '}
+            <code class="bg-[rgb(var(--ec-card-bg))] px-1.5 py-0.5 rounded text-sm">fields</code> property in their{' '}
+            <code class="bg-[rgb(var(--ec-card-bg))] px-1.5 py-0.5 rounded text-sm">sends</code> or{' '}
+            <code class="bg-[rgb(var(--ec-card-bg))] px-1.5 py-0.5 rounded text-sm">receives</code> configuration.
+          </p>
+        </div>
+      )
+    }
+
+    {
+      sortedFields.length > 0 && (
+        <div class="py-6">
+          <div class="overflow-x-auto">
+            <table id="field-usage-table" class="min-w-full">
+              <thead>
+                <tr class="border-b border-[rgb(var(--ec-page-border))]">
+                  <th class="text-left py-3 px-4 text-sm font-semibold text-[rgb(var(--ec-page-text))]">Field</th>
+                  <th class="text-left py-3 px-4 text-sm font-semibold text-[rgb(var(--ec-page-text))]">Type</th>
+                  <th class="text-left py-3 px-4 text-sm font-semibold text-[rgb(var(--ec-page-text))]">Description</th>
+                  <th class="text-left py-3 px-4 text-sm font-semibold text-[rgb(var(--ec-page-text))]">Consumers</th>
+                </tr>
+              </thead>
+              <tbody>
+                {sortedFields.map(([field, consumers]) => {
+                  const schemaProp = schemaPropertyMap.get(field);
+                  const isRequired = schemaProp?.required ?? false;
+                  return (
+                    <tr
+                      class="field-row border-b border-[rgb(var(--ec-page-border)/0.5)] hover:bg-[rgb(var(--ec-card-bg)/0.3)] transition-colors"
+                      data-has-consumers={consumers.length > 0 ? 'true' : 'false'}
+                    >
+                      <td class="py-3 px-4">
+                        <div class="flex items-baseline gap-2">
+                          <span class="font-semibold text-sm text-[rgb(var(--ec-page-text))]">{field}</span>
+                          {isRequired && <span class="text-xs text-[rgb(var(--ec-accent))]">required</span>}
+                        </div>
+                      </td>
+                      <td class="py-3 px-4">
+                        {schemaProp?.type ? (
+                          <span class="font-mono text-xs text-[rgb(var(--ec-accent))]">{schemaProp.type}</span>
+                        ) : (
+                          <span class="text-xs text-[rgb(var(--ec-page-text-muted))]">—</span>
+                        )}
+                      </td>
+                      <td class="py-3 px-4">
+                        <span class="text-xs text-[rgb(var(--ec-page-text-muted))]">{schemaProp?.description || '—'}</span>
+                      </td>
+                      <td class="py-3 px-4">
+                        <div class="flex flex-col gap-1">
+                          {consumers.length > 0 ? (
+                            consumers.map((consumer) => (
+                              <a
+                                href={buildUrl(`/docs/services/${consumer.resourceId}/${consumer.resourceVersion}`)}
+                                class="inline-flex items-center gap-1.5 text-xs text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-accent))] transition-colors"
+                              >
+                                <ServerIcon className="h-3.5 w-3.5 text-pink-500 shrink-0" />
+                                <span class="truncate">{consumer.resourceName}</span>
+                              </a>
+                            ))
+                          ) : (
+                            <span class="text-xs text-[rgb(var(--ec-page-text-muted))]">—</span>
+                          )}
+                        </div>
+                      </td>
+                    </tr>
+                  );
+                })}
+              </tbody>
+            </table>
+          </div>
+
+          {sortedUnmatchedFields.length > 0 && (
+            <div class="mt-8">
+              <div class="flex items-center gap-2 mb-3">
+                <svg
+                  xmlns="http://www.w3.org/2000/svg"
+                  class="h-5 w-5 text-amber-500"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                  stroke="currentColor"
+                  stroke-width="2"
+                >
+                  <path
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                    d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"
+                  />
+                </svg>
+                <h3 class="text-sm font-semibold text-[rgb(var(--ec-page-text))]">Fields not found in schema</h3>
+              </div>
+              <p class="text-xs text-[rgb(var(--ec-page-text-muted))] mb-4">
+                These fields are declared by consumers but do not exist in the message schema. This may indicate outdated
+                documentation, a typo, or a missing field in the schema.
+              </p>
+              <div class="overflow-x-auto">
+                <table class="min-w-full">
+                  <thead>
+                    <tr class="border-b border-[rgb(var(--ec-page-border))]">
+                      <th class="text-left py-3 px-4 text-sm font-semibold text-[rgb(var(--ec-page-text))]">Field</th>
+                      <th class="text-left py-3 px-4 text-sm font-semibold text-[rgb(var(--ec-page-text))]">Declared by</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {sortedUnmatchedFields.map(([field, consumers]) => (
+                      <tr class="border-b border-[rgb(var(--ec-page-border)/0.5)]">
+                        <td class="py-3 px-4">
+                          <code class="text-sm font-mono font-semibold text-amber-500">{field}</code>
+                        </td>
+                        <td class="py-3 px-4">
+                          <div class="flex flex-col gap-1">
+                            {consumers.map((consumer) => (
+                              <a
+                                href={buildUrl(`/docs/services/${consumer.resourceId}/${consumer.resourceVersion}`)}
+                                class="inline-flex items-center gap-1.5 text-xs text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-accent))] transition-colors"
+                              >
+                                <ServerIcon className="h-3.5 w-3.5 text-pink-500 shrink-0" />
+                                <span class="truncate">{consumer.resourceName}</span>
+                              </a>
+                            ))}
+                          </div>
+                        </td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            </div>
+          )}
+        </div>
+      )
+    }
+
+    <Footer />
+  </main>
+  <ClientRouter />
+</VerticalSideBarLayout>
+
+<script>
+  document.addEventListener('astro:page-load', () => {
+    const btn = document.getElementById('filter-consumed-btn');
+    const label = document.getElementById('filter-consumed-label');
+    if (!btn || !label) return;
+
+    let filtered = false;
+
+    btn.addEventListener('click', () => {
+      filtered = !filtered;
+      const rows = document.querySelectorAll('.field-row');
+      rows.forEach((row) => {
+        const el = row as HTMLElement;
+        if (filtered && el.dataset.hasConsumers === 'false') {
+          el.style.display = 'none';
+        } else {
+          el.style.display = '';
+        }
+      });
+
+      label.textContent = filtered ? 'All fields' : 'Consumed only';
+      btn.classList.toggle('bg-[rgb(var(--ec-accent-subtle))]', filtered);
+      btn.classList.toggle('text-[rgb(var(--ec-accent))]', filtered);
+      btn.classList.toggle('border-[rgb(var(--ec-accent))]', filtered);
+    });
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/[filename].astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/[filename].astro
new file mode 100644
index 000000000..e0715211a
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/[filename].astro
@@ -0,0 +1,153 @@
+---
+import { Code } from 'astro-expressive-code/components';
+import fs from 'fs';
+
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import Footer from '@layouts/Footer.astro';
+import { Page } from './_[filename].data';
+import { getAbsoluteFilePathForAstroFile } from '@utils/files';
+import { buildUrl, buildEditUrlForResource } from '@utils/url-builder';
+import Admonition from '@components/MDX/Admonition';
+import Badge from '@components/Badge.astro';
+
+import { ServerIcon } from '@heroicons/react/24/outline';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const { collection, data, filePath, filename, path: relativeSpecPath } = await Page.getData(Astro);
+
+const fileName = filename || 'schema.graphql';
+const pathToSpec = getAbsoluteFilePathForAstroFile(filePath, fileName);
+const fileExists = fs.existsSync(pathToSpec);
+const isRemote = relativeSpecPath.includes('https://');
+let content = '';
+
+if (fileExists && !isRemote) {
+  content = fs.readFileSync(pathToSpec, 'utf8');
+}
+
+if (isRemote) {
+  // Fetch the content from the remote path
+  content = await fetch(relativeSpecPath).then((res) => res.text());
+}
+
+// Create comprehensive page title
+const pageTitle = `${collection} | ${data.name} | GraphQL Schema`.replace(/^\w/, (c) => c.toUpperCase());
+
+const getServiceBadge = () => {
+  return [{ textColor: 'gray', content: 'Service', icon: ServerIcon }];
+};
+
+const getGraphQLBadge = () => {
+  return [
+    {
+      textColor: 'gray',
+      content: 'GraphQL Schema',
+      iconURL: buildUrl('/icons/graphql.svg', true),
+      id: 'graphql-schema-badge',
+    },
+  ];
+};
+
+const badges = [...getServiceBadge(), ...getGraphQLBadge()];
+
+// Index only the latest version
+const pagefindAttributes =
+  data.version === data.latestVersion
+    ? {
+        'data-pagefind-body': '',
+        'data-pagefind-meta': `title:${pageTitle}`,
+      }
+    : {};
+---
+
+<VerticalSideBarLayout title={pageTitle} description={`GraphQL schema for ${data.name}`}>
+  <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
+    <div class="flex docs-layout w-full">
+      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-2">
+          <div>
+            <div class="flex justify-between items-start">
+              <div class="flex-1">
+                <h1 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))] mb-2">
+                  {data.name}
+                  <span class="text-[rgb(var(--ec-page-text-muted))]">(v{data.version})</span>
+                </h1>
+                <h2 class="text-lg text-[rgb(var(--ec-page-text-muted))] font-medium mb-1">GraphQL Schema</h2>
+              </div>
+            </div>
+
+            {
+              badges && badges.length > 0 && (
+                <div class="flex flex-wrap gap-3 py-4">
+                  {badges.map((badge: any) => {
+                    return <Badge badge={badge} />;
+                  })}
+                </div>
+              )
+            }
+          </div>
+        </div>
+
+        <div data-pagefind-ignore>
+          {
+            data.version !== data.latestVersion && (
+              <Admonition type="warning" title="New version found">
+                <p>
+                  You are looking at a previous version of the service <strong>{data.name}</strong>.{' '}
+                  <a
+                    class="underline block pt-2"
+                    href={buildUrl(`/docs/${collection}/${data.id}/${data.latestVersion}/graphql/${filename}`)}
+                  >
+                    The latest version of this GraphQL schema is
+                    <span>v{data.latestVersion}</span> &rarr;
+                  </a>
+                </p>
+              </Admonition>
+            )
+          }
+        </div>
+
+        {
+          !fileExists && (
+            <Admonition type="warning" title="Schema not found">
+              <p>The GraphQL schema file could not be found at the expected location.</p>
+            </Admonition>
+          )
+        }
+
+        {
+          fileExists && content && (
+            <div class="mt-6">
+              <div class="bg-[rgb(var(--ec-card-bg))] rounded-lg p-4 mb-4 border border-[rgb(var(--ec-page-border))]">
+                <div class="flex items-center gap-2 mb-2">
+                  <img src={buildUrl('/icons/graphql.svg', true)} class="w-5 h-5" alt="GraphQL" />
+                  <h3 class="text-lg font-semibold text-[rgb(var(--ec-page-text))]">GraphQL Schema</h3>
+                </div>
+                <p class="text-sm text-[rgb(var(--ec-page-text-muted))]">
+                  This schema defines the GraphQL API structure including types, queries, mutations, and subscriptions for{' '}
+                  {data.name}.
+                </p>
+              </div>
+
+              <div class="not-prose overflow-x-auto">
+                <Code code={content} title={`${data.name} v${data.version} - Schema`} lang="graphql" />
+              </div>
+            </div>
+          )
+        }
+
+        <Footer />
+      </div>
+    </div>
+  </main>
+
+  <style is:global>
+    .docs-layout .prose {
+      max-width: none;
+      overflow: auto;
+    }
+  </style>
+</VerticalSideBarLayout>
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/_[filename].data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/_[filename].data.ts
similarity index 100%
rename from eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/_[filename].data.ts
rename to packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/graphql/_[filename].data.ts
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/index.astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/index.astro
new file mode 100644
index 000000000..6b7f1c474
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/index.astro
@@ -0,0 +1,898 @@
+---
+// External dependencies
+import { marked } from 'marked';
+
+import { render } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import Footer from '@layouts/Footer.astro';
+
+import components from '@components/MDX/components';
+import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import SchemaViewer from '@components/MDX/SchemaViewer/SchemaViewerRoot.astro';
+import Admonition from '@components/MDX/Admonition';
+import VersionList from '@components/Lists/VersionList.astro';
+import CopyAsMarkdown from '@components/CopyAsMarkdown';
+import FavoriteButton from '@components/FavoriteButton';
+import Badge from '@components/Badge.astro';
+import { shouldRenderSideBarSection } from '@stores/sidebar-store/builders/shared';
+
+import {
+  QueueListIcon,
+  RectangleGroupIcon,
+  ServerIcon,
+  BoltIcon,
+  ChatBubbleLeftIcon,
+  MagnifyingGlassIcon,
+  MapIcon,
+  ClockIcon,
+} from '@heroicons/react/24/outline';
+import { ArrowsRightLeftIcon } from '@heroicons/react/20/solid';
+import {
+  Bot,
+  Box,
+  Boxes,
+  Group,
+  SquarePenIcon,
+  DatabaseIcon,
+  DatabaseZapIcon,
+  ShieldCheckIcon,
+  AlignLeft,
+  Package,
+  ClipboardList,
+  CalendarDays,
+} from 'lucide-react';
+
+import { getSpecificationsForService } from '@utils/collections/services';
+import { resourceToCollectionMap, collectionToResourceMap, getDeprecatedDetails } from '@utils/collections/util';
+import {
+  createAdrStatusBadge,
+  formatAdrDate,
+  getAdrRelationships,
+  getAdrs,
+  isAdrCollection,
+  isDeprecatedAdr,
+  isSupersededAdr,
+} from '@utils/collections/adrs';
+import { getSchemasFromResource } from '@utils/collections/schemas';
+import { getIcon } from '@utils/badges';
+import { buildUrl, buildEditUrlForResource } from '@utils/url-builder';
+import { isIconPath, resolveIconUrl } from '@utils/icon';
+import {
+  isEventCatalogChatEnabled,
+  isMarkdownDownloadEnabled,
+  isVisualiserEnabled,
+  isRSSEnabled,
+} from '@utils/feature';
+import { getMDXComponentsByName, parseMdxBooleanProp } from '@utils/markdown';
+
+import type { CollectionTypes } from '@types';
+
+import config from '@config';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+const { Content, headings } = await render(props);
+const isAdrPage = isAdrCollection(props.collection);
+const allAdrs = isAdrPage ? await getAdrs({ getAllVersions: true }) : [];
+const adrRelationships = isAdrPage ? getAdrRelationships(props as any, allAdrs) : null;
+const supersededByAdrs = adrRelationships?.supersededBy || [];
+
+const pageTitle = `${props.collection} | ${props.data.name}`.replace(/^\w/, (c) => c.toUpperCase());
+const contentBadges = props.data.badges || [];
+const editUrl =
+  props.data.editUrl || (config.editUrl && props?.filePath ? buildEditUrlForResource(config.editUrl, props?.filePath) : '');
+
+const headerIconSrc = isIconPath(props.data.styles?.icon) ? resolveIconUrl(props.data.styles!.icon!) : null;
+
+const getContentBadges = () =>
+  contentBadges.map((badge: any) => ({
+    ...badge,
+    icon: badge.icon ? getIcon(badge.icon) : null,
+  }));
+
+const createResourceBadge = (content: string, icon: any): any => ({ content, icon, textColor: 'gray' });
+
+const getAgentProviderIconURL = (provider: string) => {
+  const providerIconName = provider
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '');
+
+  return buildUrl(`/icons/agent/${providerIconName}.svg`, true);
+};
+
+const getAgentProviderIconURLs = (provider: string) => {
+  const providerIconName = provider
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '');
+
+  const hasThemedIcon = ['openai', 'anthropic'].includes(providerIconName);
+
+  return hasThemedIcon
+    ? {
+        iconURLLight: buildUrl(`/icons/agent/${providerIconName}-light.svg`, true),
+        iconURLDark: buildUrl(`/icons/agent/${providerIconName}-dark.svg`, true),
+      }
+    : {
+        iconURL: getAgentProviderIconURL(provider),
+      };
+};
+
+const getBadge = () => {
+  if (props.collection === 'agents') {
+    const badges = [createResourceBadge('Agent', Bot)];
+    if (props.data?.model?.provider) {
+      badges.push({
+        content: props.data.model.provider,
+        ...getAgentProviderIconURLs(props.data.model.provider),
+        textColor: 'gray',
+      });
+    }
+    const modelBadge = props.data?.model?.name;
+    if (modelBadge) {
+      badges.push(createResourceBadge(modelBadge, Bot));
+    }
+    return badges;
+  }
+
+  if (isAdrPage) {
+    return [
+      createResourceBadge('Decision Record', ClipboardList),
+      createResourceBadge(formatAdrDate(props.data.date), CalendarDays),
+      createAdrStatusBadge(props.data.status),
+    ];
+  }
+
+  if (props.collection === 'services') {
+    return [createResourceBadge('Service', ServerIcon)];
+  }
+  if (props.collection === 'events') {
+    return [createResourceBadge('Event', BoltIcon)];
+  }
+  if (props.collection === 'commands') {
+    return [createResourceBadge('Command', ChatBubbleLeftIcon)];
+  }
+  if (props.collection === 'queries') {
+    return [createResourceBadge('Query', MagnifyingGlassIcon)];
+  }
+  if (props.collection === 'domains') {
+    return [createResourceBadge('Domain', RectangleGroupIcon)];
+  }
+
+  if (props.collection === 'systems') {
+    return [createResourceBadge('System', Group)];
+  }
+
+  if (props.collection === 'flows') {
+    return [createResourceBadge('Flow', QueueListIcon)];
+  }
+
+  if (props.collection === 'channels') {
+    return [createResourceBadge('Channel', ArrowsRightLeftIcon)];
+  }
+
+  if (props.collection === 'containers') {
+    const badges = [];
+    const content = props.data.container_type?.charAt(0).toUpperCase() + props.data.container_type?.slice(1) || 'Database';
+
+    badges.push(createResourceBadge(content, DatabaseIcon));
+
+    if (props.data?.technology) {
+      badges.push(createResourceBadge(`${props.data.technology}`, DatabaseZapIcon));
+    }
+
+    if (props.data?.residency) {
+      badges.push(createResourceBadge(`Residency: ${props.data.residency}`, MapIcon));
+    }
+
+    if (props.data?.retention) {
+      badges.push(createResourceBadge(`Retention: ${props.data.retention}`, ClockIcon));
+    }
+
+    if (props.data?.access_mode) {
+      badges.push(createResourceBadge(`Access Mode: ${props.data.access_mode}`, ShieldCheckIcon));
+    }
+
+    return badges;
+  }
+
+  if (props.collection === 'entities') {
+    const entityBadges = [createResourceBadge('Entity', Box)];
+    if (props.data.aggregateRoot) {
+      entityBadges.push(createResourceBadge('(Aggregate Root)', Boxes));
+    }
+    return entityBadges;
+  }
+
+  if (props.collection === 'data-products') {
+    return [createResourceBadge('Data Product', Package)];
+  }
+
+  return [createResourceBadge('', QueueListIcon)];
+};
+
+const getSpecificationBadges = () => {
+  const badges = [];
+
+  const specifications = getSpecificationsForService(props);
+
+  const asyncapiSpecs = specifications.filter((spec) => spec.type === 'asyncapi');
+  const openapiSpecs = specifications.filter((spec) => spec.type === 'openapi');
+  const graphQLSpecs = specifications.filter((spec) => spec.type === 'graphql');
+
+  if (openapiSpecs.length > 0) {
+    for (const spec of openapiSpecs) {
+      badges.push({
+        content: spec.name || 'OpenAPI Spec',
+        iconURL: buildUrl('/icons/openapi.svg', true),
+        class: 'text-[rgb(var(--ec-page-text))] hover:underline',
+        id: 'open-api-badge',
+        url: buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.version}/spec/${spec.filenameWithoutExtension}`),
+      });
+    }
+  }
+
+  if (asyncapiSpecs.length > 0) {
+    for (const spec of asyncapiSpecs) {
+      badges.push({
+        content: spec.name || 'AsyncAPI Spec',
+        iconURL: buildUrl('/icons/asyncapi.svg', true),
+        class: 'text-[rgb(var(--ec-page-text))] hover:underline',
+        id: 'asyncapi-badge',
+        url: buildUrl(
+          `/docs/${props.collection}/${props.data.id}/${props.data.version}/asyncapi/${spec.filenameWithoutExtension}`
+        ),
+      });
+    }
+  }
+
+  if (graphQLSpecs.length > 0) {
+    for (const spec of graphQLSpecs) {
+      badges.push({
+        content: spec.name || 'GraphQL Spec',
+        iconURL: buildUrl('/icons/graphql.svg', true),
+        class: 'text-[rgb(var(--ec-page-text))] hover:underline',
+        id: 'graphql-badge',
+        url: buildUrl(
+          `/docs/${props.collection}/${props.data.id}/${props.data.version}/graphql/${spec.filenameWithoutExtension}`
+        ),
+      });
+    }
+  }
+
+  return badges;
+};
+
+const badges = [...getBadge(), ...getContentBadges(), ...getSpecificationBadges()];
+
+// Index only the latest version
+const pagefindAttributes =
+  props.data.version === props.data.latestVersion
+    ? {
+        'data-pagefind-body': '',
+        'data-pagefind-meta': `title:${pageTitle}`,
+      }
+    : {};
+
+const {
+  hasDeprecated,
+  message: deprecatedMessage,
+  isMarkedAsDeprecated,
+  deprecatedDate: formattedDate,
+} = getDeprecatedDetails(props as unknown as CollectionEntry<CollectionTypes>);
+
+let friendlyCollectionName = props.collection.slice(0, props.collection.length - 1);
+friendlyCollectionName = friendlyCollectionName === 'querie' ? 'query' : friendlyCollectionName;
+friendlyCollectionName = friendlyCollectionName === 'entitie' ? 'entity' : friendlyCollectionName;
+friendlyCollectionName = friendlyCollectionName === 'adr' ? 'architecture decision' : friendlyCollectionName;
+
+const schemasForResource = getSchemasFromResource(props);
+
+const generatePromptForResource = (props: any) => {
+  return `
+    Please tell me more about the ${props.collection.slice(0, props.collection.length - 1)} -  ${props.data.name} v${props.data.version} in this catalog.
+  `;
+};
+
+// Handle node graphs in the markdown
+const currentPageNodeGraph = {
+  id: props.data.id,
+  version: props.data.version,
+  type: collectionToResourceMap[props.collection as keyof typeof collectionToResourceMap],
+};
+
+let nodeGraphs =
+  getMDXComponentsByName(props.body || '', 'NodeGraph')?.map((nodeGraph: any) => {
+    const graph = nodeGraph.id === undefined ? { ...currentPageNodeGraph, ...nodeGraph } : nodeGraph;
+
+    return {
+      ...graph,
+      search: parseMdxBooleanProp(nodeGraph.search, true),
+      legend: parseMdxBooleanProp(nodeGraph.legend, true),
+    };
+  }) || [];
+const flowEmbeds = getMDXComponentsByName(props.body || '', 'Flow') || [];
+
+// Context Diagrams embedded via <ContextDiagram />. When no id is passed we assume
+// the current page. Valid on system pages (renders the system's context) and domain
+// pages (renders the context across the domain's systems). Each renders into its own
+// portal so it doesn't collide with the page's default diagram.
+//
+// The underlying graph + visualiser link differ per page type:
+//   - systems → `systems-context`, links to /visualiser/systems/:id/:version/context
+//   - domains → `domains-systems-context`, links to /visualiser/domains/:id/:version/systems-context
+const contextDiagramSupported = props.collection === 'systems' || props.collection === 'domains';
+const contextDiagrams = contextDiagramSupported
+  ? (getMDXComponentsByName(props.body || '', 'ContextDiagram') || []).map((diagram: any) => {
+      const id = diagram.id ?? props.data.id;
+      const version = diagram.version ?? props.data.version;
+      return {
+        id,
+        version,
+        search: parseMdxBooleanProp(diagram.search, true),
+        legend: parseMdxBooleanProp(diagram.legend, true),
+        graphCollection: props.collection === 'domains' ? 'domains-systems-context' : 'systems-context',
+        visualiserUrl:
+          props.collection === 'domains'
+            ? buildUrl(`/visualiser/domains/${id}/${version}/systems-context`)
+            : buildUrl(`/visualiser/systems/${id}/${version}/context`),
+      };
+    })
+  : [];
+
+// Get props for the node graph (when no id is passed, we assume its the current page)
+const hasCurrentFlowEmbed =
+  props.collection === 'flows' &&
+  flowEmbeds.some((flowEmbed: any) => {
+    const flowId = flowEmbed.id;
+    const flowVersion = flowEmbed.version || 'latest';
+
+    return flowId === props.data.id && (flowVersion === 'latest' || flowVersion === props.data.version);
+  });
+const hasCurrentPageNodeGraph = nodeGraphs.some((nodeGraph: any) => {
+  return (
+    nodeGraph.id === currentPageNodeGraph.id &&
+    nodeGraph.version === currentPageNodeGraph.version &&
+    nodeGraph.type === currentPageNodeGraph.type
+  );
+});
+
+const shouldRenderVersionList =
+  shouldRenderSideBarSection(props, 'versions') && props.data.versions && props.data.versions.length > 1;
+const httpOperation =
+  ['commands', 'queries'].includes(props.collection) && props.data.operation?.path ? props.data.operation : undefined;
+const httpMethodColors: Record<string, { background: string; color: string }> = {
+  GET: { background: 'rgba(34,197,94,0.15)', color: '#22c55e' },
+  POST: { background: 'rgba(59,130,246,0.15)', color: '#3b82f6' },
+  PUT: { background: 'rgba(245,158,11,0.15)', color: '#f59e0b' },
+  PATCH: { background: 'rgba(245,158,11,0.15)', color: '#f59e0b' },
+  DELETE: { background: 'rgba(239,68,68,0.15)', color: '#ef4444' },
+  OPTIONS: { background: 'rgba(139,92,246,0.15)', color: '#8b5cf6' },
+  HEAD: { background: 'rgba(107,114,128,0.15)', color: '#6b7280' },
+};
+const httpMethodStyle = httpOperation?.method
+  ? httpMethodColors[httpOperation.method.toUpperCase()] || { background: '#6b7280', color: '#ffffff' }
+  : undefined;
+
+// This will render the graph for this page. Flow pages can already render their graph explicitly via <Flow />.
+if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
+  nodeGraphs.push({
+    ...currentPageNodeGraph,
+    search: true,
+    legend: true,
+  });
+}
+---
+
+<VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
+  <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
+    <div class="flex docs-layout w-full">
+      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        <div class="border-b border-[rgb(var(--ec-page-border))] md:pb-6 pt-4">
+          <div>
+            <div>
+              <div class="flex flex-col gap-4">
+                <span class="text-xs md:text-sm font-semibold text-[rgb(var(--ec-accent))] capitalize">
+                  {friendlyCollectionName}
+                </span>
+                <div class="flex items-center gap-3">
+                  {
+                    headerIconSrc && (
+                      <img
+                        src={headerIconSrc}
+                        alt={props.data.name}
+                        class="w-8 h-8 md:w-10 md:h-10 object-contain rounded-md shrink-0"
+                      />
+                    )
+                  }
+                  <div class="flex items-center gap-2">
+                    <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">
+                      {props.data.name}
+                      {props.data.latestVersion !== props.data.version && <span>(v{props.data.version})</span>}
+                    </h2>
+                    <FavoriteButton
+                      client:load
+                      nodeKey={`${collectionToResourceMap[props.collection as keyof typeof collectionToResourceMap]}:${props.data.id}:${props.data.version}`}
+                      title={props.data.name}
+                      badge={collectionToResourceMap[props.collection as keyof typeof collectionToResourceMap]
+                        .charAt(0)
+                        .toUpperCase() +
+                        collectionToResourceMap[props.collection as keyof typeof collectionToResourceMap].slice(1)}
+                      href={buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.version}`)}
+                      size="md"
+                    />
+                  </div>
+                </div>
+              </div>
+            </div>
+
+            <h2 class="text-base pt-4 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</h2>
+            {
+              badges && (
+                <div class="flex flex-wrap gap-1.5 pt-4">
+                  {badges.map((badge: any) => {
+                    return <Badge badge={badge} />;
+                  })}
+                </div>
+              )
+            }
+            <div class="pt-5">
+              <CopyAsMarkdown
+                client:only="react"
+                variant="toolbar"
+                schemas={schemasForResource}
+                chatQuery={generatePromptForResource(props)}
+                chatEnabled={isEventCatalogChatEnabled()}
+                markdownDownloadEnabled={isMarkdownDownloadEnabled()}
+                rssFeedEnabled={isRSSEnabled()}
+                editUrl={editUrl}
+                preferChatAsDefault={isEventCatalogChatEnabled()}
+              />
+            </div>
+            {
+              httpOperation && (
+                <div class="pt-4">
+                  <div
+                    class="inline-flex max-w-full items-start gap-2 rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover))] px-3 py-2 text-sm text-[rgb(var(--ec-page-text))]"
+                    aria-label="HTTP path"
+                  >
+                    {httpOperation.method && (
+                      <span
+                        class="mt-0.5 shrink-0 rounded-md px-2 py-0.5 font-mono text-xs font-semibold"
+                        style={`background: ${httpMethodStyle?.background}; color: ${httpMethodStyle?.color};`}
+                      >
+                        {httpOperation.method}
+                      </span>
+                    )}
+                    <code class="break-all font-mono text-[rgb(var(--ec-page-text))]">{httpOperation.path}</code>
+                  </div>
+                </div>
+              )
+            }
+            {
+              isSupersededAdr(props) && (
+                <Admonition type="warning" title="This architecture decision has been superseded">
+                  <div>
+                    {supersededByAdrs.length > 0 ? (
+                      <p>
+                        You are looking at a previous architecture decision. It has been superseded by{' '}
+                        {supersededByAdrs.map((adr: any, index: number) => (
+                          <>
+                            <a class="underline" href={buildUrl(`/docs/adrs/${adr.data.id}/${adr.data.version}`)}>
+                              {adr.data.name}
+                            </a>
+                            {index < supersededByAdrs.length - 1 ? ', ' : '.'}
+                          </>
+                        ))}
+                      </p>
+                    ) : (
+                      <p>This architecture decision has been marked as superseded.</p>
+                    )}
+                  </div>
+                </Admonition>
+              )
+            }
+
+            {
+              isDeprecatedAdr(props) && (
+                <Admonition type="warning" title="This architecture decision has been deprecated">
+                  <p>This architecture decision has been marked as deprecated.</p>
+                </Admonition>
+              )
+            }
+
+            {
+              isMarkedAsDeprecated && hasDeprecated && (
+                <Admonition
+                  className="w-full"
+                  type="alert"
+                  title={formattedDate ? `This ${friendlyCollectionName} was deprecated on ${formattedDate}` : `Deprecated`}
+                >
+                  <div>
+                    {!deprecatedMessage && (
+                      <p>
+                        The {friendlyCollectionName} has been marked as deprecated
+                        {formattedDate && ` on ${formattedDate}`}.
+                      </p>
+                    )}
+                    {deprecatedMessage && <div class="prose prose-sm max-w-none" set:html={marked.parse(deprecatedMessage)} />}
+                  </div>
+                </Admonition>
+              )
+            }
+            {
+              isMarkedAsDeprecated && !hasDeprecated && (
+                <Admonition type="warning" title={`This ${friendlyCollectionName} will be deprecated on ${formattedDate}`}>
+                  <div>
+                    {!deprecatedMessage && (
+                      <p>
+                        The {friendlyCollectionName} will be deprecated on {formattedDate}.
+                      </p>
+                    )}
+                    {deprecatedMessage && <div class="prose prose-sm max-w-none" set:html={marked.parse(deprecatedMessage)} />}
+                  </div>
+                </Admonition>
+              )
+            }
+
+            {
+              props.data.draft && (
+                <Admonition type="warning" title={props.data?.draft?.title || `Draft ${friendlyCollectionName}`}>
+                  <div>
+                    {!props.data.draft.message && (
+                      <p>This resource has been marked as a draft and may still be under development.</p>
+                    )}
+                    {props.data.draft.message && (
+                      <div class="prose prose-sm max-w-none" set:html={marked.parse(props.data.draft.message)} />
+                    )}
+                  </div>
+                </Admonition>
+              )
+            }
+          </div>
+        </div>
+
+        <div data-pagefind-ignore>
+          {
+            props.data.version !== props.data.latestVersion && (
+              <Admonition type="warning" title="New version found">
+                <p>
+                  You are looking at a previous version of the {props.collection.slice(0, props.collection.length - 1)}{' '}
+                  <strong>{props.data.name}</strong>.{' '}
+                  <a
+                    class="underline block pt-2"
+                    href={buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.latestVersion}`)}
+                  >
+                    The latest version of this {props.collection.slice(0, props.collection.length - 1)} is
+                    <span>v{props.data.latestVersion}</span> &rarr;
+                  </a>
+                </p>
+              </Admonition>
+            )
+          }
+        </div>
+
+        <div class="prose prose-md py-4 w-full text-[15px]">
+          <Content components={components(props)} />
+        </div>
+        <div data-pagefind-ignore>
+          <!-- @ts-ignore -->
+          <!-- <SchemaViewer id={props.data.id} catalog={props.catalog} filePath={props.filePath} /> -->
+          <SchemaViewer id={props.data.id} version={props.data.version} collection={props.collection} filePath={props.filePath} />
+
+          {
+            nodeGraphs.length > 0 &&
+              nodeGraphs.map((nodeGraph: any) => {
+                const collection = resourceToCollectionMap[nodeGraph.type as keyof typeof resourceToCollectionMap];
+                return (
+                  <NodeGraph
+                    id={nodeGraph.id}
+                    version={nodeGraph.version}
+                    collection={collection}
+                    title={nodeGraph.title}
+                    mode={nodeGraph.mode || 'simple'}
+                    linksToVisualiser={true}
+                    showSearch={nodeGraph.search ?? true}
+                    showLegend={nodeGraph.legend ?? true}
+                    href={
+                      isVisualiserEnabled()
+                        ? {
+                            label: 'Open in Visualiser',
+                            url: buildUrl(`/visualiser/${collection}/${nodeGraph.id}/${nodeGraph.version}`),
+                          }
+                        : undefined
+                    }
+                  />
+                );
+              })
+          }
+          {
+            contextDiagrams.length > 0 &&
+              contextDiagrams.map((diagram: any) => (
+                <NodeGraph
+                  id={diagram.id}
+                  version={diagram.version}
+                  collection={diagram.graphCollection}
+                  mode="simple"
+                  linksToVisualiser={true}
+                  showSearch={diagram.search ?? true}
+                  showLegend={diagram.legend ?? true}
+                  portalId={`${diagram.id}-context-diagram-portal`}
+                  href={
+                    isVisualiserEnabled()
+                      ? {
+                          label: 'Open Context Diagram',
+                          url: diagram.visualiserUrl,
+                        }
+                      : undefined
+                  }
+                />
+              ))
+          }
+        </div>
+        <Footer />
+        <!-- Add edit this page button  with icon and text-->
+        <div class="flex justify-end">
+          <!-- Built with EventCatalog -->
+          {
+            editUrl && (
+              <div class="flex justify-end">
+                <a
+                  href={editUrl}
+                  class="text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] border border-[rgb(var(--ec-page-border))] rounded-md p-2"
+                >
+                  <SquarePenIcon className="w-4 h-4 inline-block mr-1" />
+                  Edit this page
+                </a>
+              </div>
+            )
+          }
+        </div>
+      </div>
+      <aside
+        id="eventcatalog-docs-sidebar"
+        class="hidden xl:block sticky top-[4rem] self-start w-[280px] max-h-[calc(100vh-4rem)] overflow-y-auto py-2 flex-shrink-0 pr-10 bg-[rgb(var(--ec-page-bg))]"
+      >
+        <div class="mt-8 space-y-8">
+          {
+            headings.length > 0 && (
+              <div>
+                <h3 class="text-xs text-[rgb(var(--ec-page-text))] font-semibold group-data-[hover]:text-[rgb(var(--ec-page-text))]/80 capitalize flex items-center gap-2 mb-4">
+                  <AlignLeft className="w-4 h-4" />
+                  On this page
+                </h3>
+                <div class="space-y-8">
+                  <nav class="text-xs border-l border-[rgb(var(--ec-page-border))]">
+                    {headings.map((heading) => {
+                      const level = heading.depth > 2 ? heading.depth : 1;
+                      if (heading.depth > 3) {
+                        return null;
+                      }
+                      return (
+                        <a
+                          href={`#${heading.slug}`}
+                          class={`block py-1.5 pr-2.5 leading-5 text-[rgb(var(--ec-page-text-muted))] hover:border-[rgb(var(--ec-page-border))] hover:text-[rgb(var(--ec-page-text))] border-l-2 border-transparent -ml-px transition-all duration-200`}
+                          style={`padding-left: ${level * 0.75}rem`}
+                        >
+                          {heading.text}
+                        </a>
+                      );
+                    })}
+                  </nav>
+                </div>
+              </div>
+            )
+          }
+          {
+            shouldRenderVersionList && (
+              <VersionList
+                title={`Versions (${props.data.versions?.length})`}
+                versions={props.data.versions}
+                collectionItem={props}
+              />
+            )
+          }
+        </div>
+      </aside>
+    </div>
+
+    <style is:global>
+      .docs-layout .prose {
+        max-width: none;
+        overflow: auto;
+      }
+
+      .mermaid svg {
+        margin: 1em auto 2em;
+      }
+
+      /* Fix for architecture diagrams */
+      .mermaid[data-content*='architecture'] svg {
+        max-width: 350px !important;
+        margin: 0;
+        /* width: 100px !important; */
+      }
+
+      /* TOC active state styles using accent variables */
+      .toc-active-text {
+        color: rgb(var(--ec-accent));
+      }
+      .toc-active-border {
+        border-color: rgb(var(--ec-accent));
+      }
+    </style>
+
+    <script define:vars={{ config }}>
+      window.eventcatalog = {};
+      window.eventcatalog.mermaid = config.mermaid;
+    </script>
+
+    <script>
+      import { destroyZoomInstances, renderMermaidWithZoom } from '@utils/mermaid-zoom';
+
+      // Listen for Astro transitions
+      document.addEventListener('astro:page-load', () => {
+        destroyZoomInstances();
+        const graphs = document.getElementsByClassName('mermaid');
+        if (graphs.length > 0) {
+          renderMermaidWithZoom(graphs, window.eventcatalog?.mermaid);
+        }
+      });
+
+      // Initial render
+      const graphs = document.getElementsByClassName('mermaid');
+      if (graphs.length > 0) {
+        renderMermaidWithZoom(graphs, window.eventcatalog?.mermaid);
+      }
+
+      // Make available globally for accordion component
+      window.renderDiagrams = (graphs: HTMLCollectionOf<Element>) => {
+        renderMermaidWithZoom(graphs, window.eventcatalog?.mermaid);
+      };
+    </script>
+
+    <script>
+      import { renderPlantUMLWithZoom } from '@utils/mermaid-zoom';
+
+      function initPlantUML() {
+        const blocks = document.getElementsByClassName('plantuml');
+        if (blocks.length > 0) {
+          renderPlantUMLWithZoom(blocks);
+        }
+      }
+
+      // Run on initial load and page transitions
+      initPlantUML();
+      document.addEventListener('astro:page-load', initPlantUML);
+
+      // Make available globally for accordion component
+      window.renderPlantUML = (blocks: HTMLCollectionOf<Element>) => {
+        renderPlantUMLWithZoom(blocks);
+      };
+    </script>
+    <script>
+      // @ts-nocheck
+      function setupObserver() {
+        try {
+          const observerOptions = {
+            rootMargin: '0px 0px -40% 0px',
+            threshold: 0.1,
+          };
+
+          // Flag to temporarily disable observer after click
+          let observerPaused = false;
+
+          // Function to highlight a TOC item
+          function highlightTocItem(id) {
+            // Remove active class from all links
+            document.querySelectorAll('.active-toc-item').forEach((link) => {
+              link.classList.remove('active-toc-item', 'toc-active-text', 'font-medium', 'toc-active-border');
+              link.classList.add('border-transparent');
+            });
+
+            // Add active class to current link
+            const tocLink = document.querySelector(`nav a[href="#${id}"]`);
+            if (tocLink) {
+              tocLink.classList.add('active-toc-item', 'toc-active-text', 'font-medium', 'toc-active-border');
+              tocLink.classList.remove('border-transparent');
+
+              // Scroll the highlighted item into view with a small delay to ensure DOM updates first
+              setTimeout(() => {
+                tocLink.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' });
+              }, 10);
+            }
+          }
+
+          // Set up the intersection observer for scrolling
+          const observer = new IntersectionObserver((entries) => {
+            // If observer is paused, don't process entries
+            if (observerPaused) return;
+
+            entries.forEach((entry) => {
+              try {
+                const id = entry.target.getAttribute('id');
+                if (entry.isIntersecting && id) {
+                  highlightTocItem(id);
+                }
+              } catch (entryError) {
+                console.error('Error processing intersection entry:', entryError);
+              }
+            });
+          }, observerOptions);
+
+          // Find all headings in the content area within the .prose container to observe
+          const prose = document.querySelector('.prose');
+          if (!prose) {
+            console.warn('No .prose container found for TOC highlighting');
+            return;
+          }
+
+          // First try to find headings with IDs
+          const headings = prose.querySelectorAll('h1[id], h2[id], h3[id]');
+
+          if (headings.length > 0) {
+            headings.forEach((heading) => {
+              observer.observe(heading);
+            });
+          } else {
+            // Fallback: If no headings with IDs found, attach IDs to them
+            const allHeadings = prose.querySelectorAll('h1, h2, h3');
+
+            allHeadings.forEach((heading) => {
+              // Only add ID if it doesn't exist
+              if (!heading.id) {
+                const text = heading.textContent || '';
+                const slug = text
+                  .toLowerCase()
+                  .replace(/[^\w\s-]/g, '')
+                  .replace(/\s+/g, '-');
+                heading.id = slug;
+              }
+              observer.observe(heading);
+            });
+          }
+
+          // Add click event listeners to all TOC links
+          const tocLinks = document.querySelectorAll('nav a[href^="#"]');
+          tocLinks.forEach((link) => {
+            link.addEventListener('click', (e) => {
+              // Get the ID from the href attribute
+              const hrefAttr = link.getAttribute('href');
+              if (!hrefAttr) return;
+
+              const id = hrefAttr.substring(1);
+
+              // Highlight the clicked item
+              highlightTocItem(id);
+
+              // Temporarily pause the observer to prevent immediate highlighting changes
+              observerPaused = true;
+
+              // Resume the observer after a delay (1.5 seconds)
+              setTimeout(() => {
+                observerPaused = false;
+              }, 500);
+            });
+          });
+        } catch (error) {
+          console.error('Error setting up TOC highlighting:', error);
+        }
+      }
+
+      setupObserver();
+
+      document.addEventListener('astro:page-load', setupObserver);
+    </script>
+  </main>
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/resources/_index.data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/resources/_index.data.ts
new file mode 100644
index 000000000..0a83e2d95
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/resources/_index.data.ts
@@ -0,0 +1,89 @@
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+
+// The Resources page lists the top-level resources (services, flows, entities and
+// data stores) attached to a single system or domain. It is only available for
+// systems and domains — every other resource type 404s.
+const SUPPORTED_TYPES = ['systems', 'domains'] as const;
+type SupportedType = (typeof SUPPORTED_TYPES)[number];
+
+const isSupportedType = (type: string): type is SupportedType => SUPPORTED_TYPES.includes(type as SupportedType);
+
+const loadResourceOwner = async (type: SupportedType) => {
+  if (type === 'systems') {
+    const { getSystems } = await import('@utils/collections/systems');
+    return getSystems();
+  }
+  const { getDomains } = await import('@utils/collections/domains');
+  return getDomains();
+};
+
+// A system/domain only gets a Resources page when it actually has resources attached.
+// Mirrors what the page renders: services, flows, entities, data stores and (domains
+// only) the domain's own messages.
+const hasResources = (owner: any): boolean => {
+  const data = owner?.data ?? {};
+  return (
+    (data.services || []).length > 0 ||
+    (data.flows || []).length > 0 ||
+    (data.entities || []).length > 0 ||
+    (data.containers || []).length > 0 ||
+    (data.sends || []).length > 0 ||
+    (data.receives || []).length > 0
+  );
+};
+
+export class Page extends HybridPage {
+  static get prerender(): boolean {
+    return !isSSR();
+  }
+
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isSSR()) {
+      return [];
+    }
+
+    const owners = await Promise.all(SUPPORTED_TYPES.map((type) => loadResourceOwner(type)));
+
+    return SUPPORTED_TYPES.flatMap((type, index) =>
+      owners[index]
+        .filter((owner) => hasResources(owner))
+        .map((owner) => ({
+          params: {
+            type,
+            id: owner.data.id,
+            version: owner.data.version,
+          },
+          props: {
+            ...owner,
+          },
+        }))
+    );
+  }
+
+  protected static async fetchData(params: any) {
+    const { type, id, version } = params;
+
+    if (!type || !id || !version || !isSupportedType(type)) {
+      return null;
+    }
+
+    const owners = await loadResourceOwner(type);
+    const owner = owners.find((o) => o.data.id === id && o.data.version === version);
+
+    if (!owner || !hasResources(owner)) {
+      return null;
+    }
+
+    return {
+      ...owner,
+    };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Resources not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/resources/index.astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/resources/index.astro
new file mode 100644
index 000000000..09ed55968
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/resources/index.astro
@@ -0,0 +1,85 @@
+---
+import Footer from '@layouts/Footer.astro';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { buildUrl } from '@utils/url-builder';
+import {
+  SystemResourcesTable,
+  type SystemResourceItem,
+  type SystemResourceCollection,
+} from '@components/Tables/SystemResources/SystemResourcesTable';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+const resourceOwner = await Page.getData(Astro);
+const { data } = resourceOwner;
+const ownerCollection = resourceOwner.collection as 'systems' | 'domains';
+
+// Domain-level messages come from the domain's own `sends` (Domain Events) and
+// `receives` (External Events). Each resolved entry already carries its own
+// collection (events / commands / queries). Dedupe across sends + receives.
+const messageEntries = (() => {
+  const seen = new Map<string, any>();
+  for (const message of [...(data.sends || []), ...(data.receives || [])]) {
+    if (!message?.data?.id || !message?.collection) continue;
+    seen.set(`${message.collection}:${message.data.id}:${message.data.version}`, message);
+  }
+  return Array.from(seen.values());
+})();
+
+const messagesByCollection = (collection: SystemResourceCollection) =>
+  messageEntries.filter((message: any) => message.collection === collection);
+
+// Only show resources that are directly attached to the system/domain — not resources
+// nested further downstream. Domains can't hold containers directly, so a domain's
+// Resources page shows services, flows, entities and its own messages.
+const resourceGroups: Array<{ collection: SystemResourceCollection; items: any[] }> = [
+  { collection: 'services', items: data.services || [] },
+  { collection: 'flows', items: data.flows || [] },
+  { collection: 'entities', items: data.entities || [] },
+  { collection: 'containers', items: data.containers || [] },
+  { collection: 'events', items: messagesByCollection('events') },
+  { collection: 'commands', items: messagesByCollection('commands') },
+  { collection: 'queries', items: messagesByCollection('queries') },
+];
+
+const hrefForResource = (collection: SystemResourceCollection, id: string, version: string) => {
+  if (collection === 'entities') {
+    return buildUrl(`/docs/entities/${id}/${version}`);
+  }
+  return buildUrl(`/docs/${collection}/${id}/${version}`);
+};
+
+const resources: SystemResourceItem[] = resourceGroups.flatMap(({ collection, items }) =>
+  items.map((item: any) => ({
+    collection,
+    id: item.data.id,
+    name: item.data.name || item.data.id,
+    version: item.data.version,
+    summary: item.data.summary,
+    icon: item.data?.styles?.icon,
+    href: hrefForResource(collection, item.data.id, item.data.version),
+  }))
+);
+---
+
+<VerticalSideBarLayout title={`${data.name} | Resources`}>
+  <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]">
+    <div class="flex docs-layout w-full">
+      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        <div class="border-b border-[rgb(var(--ec-page-border))] pb-4">
+          <h2 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{data.name} Resources</h2>
+          <h2 class="text-lg pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">
+            A group of resources that are mapped to the {data.name} {ownerCollection === 'domains' ? 'domain' : 'system'}.
+          </h2>
+        </div>
+
+        <div class="py-8 w-full">
+          <SystemResourcesTable resources={resources} client:only="react" />
+        </div>
+      </div>
+    </div>
+  </main>
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/[filename].astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/[filename].astro
new file mode 100644
index 000000000..cf5c2797f
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/[filename].astro
@@ -0,0 +1,97 @@
+---
+import fs from 'node:fs';
+import OpenAPISpec from './_OpenAPI.tsx';
+
+import { DocumentMinusIcon } from '@heroicons/react/24/outline';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import CopyAsMarkdown from '@components/CopyAsMarkdown';
+import { isEventCatalogChatEnabled } from '@utils/feature';
+import './_styles.css';
+import { Page } from './_[filename].data.ts';
+import { getAbsoluteFilePathForAstroFile } from '@utils/files';
+import config from '@config';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+// @ts-ignore
+const { collection, data, filePath, filename, path: relativeSpecPath } = props;
+const fileName = filename || 'openapi.yml';
+
+const pathToSpec = getAbsoluteFilePathForAstroFile(filePath, fileName);
+const fileExists = fs.existsSync(pathToSpec);
+const isRemote = relativeSpecPath.includes('https://');
+
+let content = '';
+
+// Capitalize the first letter of a string
+const pageTitle = `${collection} | ${data.name} | OpenAPI Spec`.replace(/^\w/, (c) => c.toUpperCase());
+
+// Chat configuration
+const chatEnabled = isEventCatalogChatEnabled();
+const chatQuery = `Tell me about the OpenAPI specification for "${data.name}" (version ${data.version})`;
+
+// Index only the latest version
+const pagefindAttributes =
+  data.version === data.latestVersion
+    ? {
+        'data-pagefind-body': '',
+        'data-pagefind-meta': `title:${pageTitle}`,
+      }
+    : {};
+
+if (fileExists && !isRemote) {
+  content = fs.readFileSync(pathToSpec, 'utf8');
+}
+
+if (isRemote) {
+  // Fetch the content from the remote path
+  content = await fetch(relativeSpecPath).then((res) => res.text());
+}
+---
+
+<VerticalSideBarLayout title={pageTitle}>
+  {
+    !fileExists && !isRemote ? (
+      <div class="text-center h-screen  flex flex-col justify-center ">
+        <DocumentMinusIcon className="mx-auto h-12 w-12 text-gray-400" />
+        <h3 class="mt-2 text-sm font-semibold text-gray-900">No OpenAPI spec file found</h3>
+        <p class="mt-1 text-xs text-gray-400">
+          Could not find OpenAPI file for {data.name} in {`/${collection}/${data.id}`}
+        </p>
+      </div>
+    ) : (
+      <div
+        {...pagefindAttributes}
+        class="relative"
+        style="margin-left: calc(var(--ec-app-content-padding-left, 5rem) * -1); margin-right: calc(var(--ec-app-content-padding-right, 5rem) * -1);"
+      >
+        {
+          // Currently, Pagefind does not index metadata (such as the title),
+          // so we need to ensure it is included as text on the page.
+          // https://github.com/CloudCannon/pagefind/issues/437
+        }
+        <h2 class="hidden">{pageTitle}</h2>
+        {chatEnabled && (
+          <div class="absolute top-3 right-14 z-10">
+            <CopyAsMarkdown
+              client:only="react"
+              schemas={[]}
+              chatQuery={chatQuery}
+              chatEnabled={chatEnabled}
+              editUrl=""
+              markdownDownloadEnabled={false}
+              rssFeedEnabled={false}
+              preferChatAsDefault={true}
+              chatButtonText="Ask about this specification"
+            />
+          </div>
+        )}
+        <OpenAPISpec client:only="react" configuration={config?.scalarConfiguration} spec={content} />
+      </div>
+    )
+  }
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_OpenAPI.tsx b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_OpenAPI.tsx
new file mode 100644
index 000000000..ab6da71e3
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_OpenAPI.tsx
@@ -0,0 +1,66 @@
+import { useState, useEffect, lazy, Suspense } from 'react';
+import '@scalar/api-reference-react/style.css';
+import './_styles.css';
+
+const ApiReferenceReact = lazy(() =>
+  import('@scalar/api-reference-react').then((module) => ({ default: module.ApiReferenceReact }))
+);
+
+// Any Scalar Configuration for the OpenAPI Component.
+type ScalarConfiguration = any;
+
+const OpenAPISpec = ({ spec, configuration }: { spec: string; configuration?: ScalarConfiguration }) => {
+  const [loaded, setLoaded] = useState(false);
+  const [isDarkMode, setIsDarkMode] = useState(() => {
+    return document.documentElement.getAttribute('data-theme') === 'dark';
+  });
+
+  useEffect(() => {
+    // Watch for theme changes
+    const observer = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        if (mutation.attributeName === 'data-theme') {
+          const theme = document.documentElement.getAttribute('data-theme');
+          setIsDarkMode(theme === 'dark');
+        }
+      });
+    });
+
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['data-theme'],
+    });
+
+    return () => observer.disconnect();
+  }, []);
+
+  return (
+    <div>
+      {!loaded && <div>Loading...</div>}
+      <Suspense fallback={<div>Loading OpenAPI reference...</div>}>
+        <ApiReferenceReact
+          key={isDarkMode ? 'dark' : 'light'}
+          configuration={{
+            spec: {
+              content: spec,
+            },
+            theme: 'fastify',
+            hideClientButton: true,
+            onLoaded: () => {
+              setLoaded(true);
+            },
+            forceDarkModeState: isDarkMode ? 'dark' : 'light',
+            darkMode: isDarkMode,
+            defaultOpenAllTags: true,
+            hideDarkModeToggle: true,
+            searchHotKey: 'p',
+            showSidebar: true,
+            ...configuration,
+          }}
+        />
+      </Suspense>
+    </div>
+  );
+};
+
+export default OpenAPISpec;
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_[filename].data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_[filename].data.ts
similarity index 100%
rename from eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_[filename].data.ts
rename to packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_[filename].data.ts
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_styles.css b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_styles.css
similarity index 100%
rename from eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_styles.css
rename to packages/core/eventcatalog/src/pages/docs/[type]/[id]/[version]/spec/_styles.css
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/_index.data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/_index.data.ts
new file mode 100644
index 000000000..517129245
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/_index.data.ts
@@ -0,0 +1,69 @@
+import type { CollectionTypes, PageTypes } from '@types';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
+import { isSSR } from '@utils/feature';
+
+const itemTypes: PageTypes[] = [
+  'agents',
+  'events',
+  'commands',
+  'queries',
+  'services',
+  'domains',
+  'systems',
+  'flows',
+  'channels',
+  'entities',
+  'containers',
+  'data-products',
+];
+
+export class Page extends HybridPage {
+  static async getStaticPaths() {
+    if (isSSR()) {
+      return [];
+    }
+
+    const allItems = await Promise.all(itemTypes.map((type) => pageDataLoader[type]({ getAllVersions: false })));
+
+    return allItems.flatMap((items, index) =>
+      items.map((item) => ({
+        params: {
+          type: itemTypes[index],
+          id: item.data.id,
+        },
+        props: {
+          type: itemTypes[index],
+          ...item,
+        },
+      }))
+    );
+  }
+
+  protected static async fetchData(params: any) {
+    const { type, id } = params;
+
+    if (!type || !id || !(type in pageDataLoader)) {
+      return null;
+    }
+
+    const items = await pageDataLoader[type as PageTypes]({ getAllVersions: false });
+    const item = items.find((entry) => entry.data.id === id);
+
+    if (!item) {
+      return null;
+    }
+
+    return {
+      type: type as CollectionTypes,
+      ...item,
+    };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Documentation not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/index.astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/index.astro
new file mode 100644
index 000000000..05b222426
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/index.astro
@@ -0,0 +1,33 @@
+---
+import Seo from '@components/Seo.astro';
+import { buildUrl } from '@utils/url-builder';
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+const props = await Page.getData(Astro);
+
+const pageTitle = `${props.collection} | ${props.data.name}`.replace(/^\w/, (c) => c.toUpperCase());
+
+const { pathname } = Astro.url;
+const redirectUrl = buildUrl(pathname + '/' + props.data.latestVersion, false, true);
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <Seo title={`EventCatalog | ${pageTitle}`} ogTitle={pageTitle} />
+  </head>
+  <body>
+    <p>You are being redirected to <a href={redirectUrl}>{redirectUrl}</a></p>
+  </body>
+</html>
+
+<script define:vars={{ redirectUrl }}>
+  document.addEventListener('DOMContentLoaded', () => {
+    const searchParams = window.location.search;
+    const fullRedirectUrl = redirectUrl + searchParams;
+    window.location.href = fullRedirectUrl;
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language.mdx.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language.mdx.ts
new file mode 100644
index 000000000..88f5b102e
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language.mdx.ts
@@ -0,0 +1,61 @@
+import { getDomains, getUbiquitousLanguage, hasUbiquitousLanguageTerms } from '@utils/collections/domains';
+import type { CollectionEntry } from 'astro:content';
+import type { APIRoute } from 'astro';
+import config from '@config';
+import fs from 'fs';
+import { isLLMSTxtEnabled } from '@utils/feature';
+import { filterMarkdownForAgents } from '@utils/llms';
+
+export async function getStaticPaths() {
+  const domains = await getDomains({ getAllVersions: false });
+
+  const buildPages = async (collection: CollectionEntry<'domains'>[]) => {
+    const collectionWithUbiquitousLanguage = await collection.reduce<Promise<CollectionEntry<'domains'>[]>>(async (acc, item) => {
+      const accumulator = await acc;
+      const ubiquitousLanguages = await getUbiquitousLanguage(item);
+
+      if (ubiquitousLanguages.some(hasUbiquitousLanguageTerms)) {
+        return [...accumulator, item];
+      }
+
+      return accumulator;
+    }, Promise.resolve([]));
+
+    return collectionWithUbiquitousLanguage.map((item) => ({
+      params: {
+        type: item.collection,
+        id: item.data.id,
+      },
+      props: {
+        type: item.collection,
+        ...item,
+      },
+    }));
+  };
+
+  return [...(await buildPages(domains))];
+}
+
+export const GET: APIRoute = async ({ params, props }) => {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  const domains = await getDomains({ getAllVersions: false });
+  const domain = props?.data ? (props as CollectionEntry<'domains'>) : domains.find((item) => item.data.id === params.id);
+  if (!domain) {
+    return new Response('Not found', { status: 404 });
+  }
+
+  const ubiquitousLanguages = await getUbiquitousLanguage(domain as CollectionEntry<'domains'>);
+  const ubiquitousLanguage = ubiquitousLanguages[0];
+
+  if (ubiquitousLanguage?.filePath && hasUbiquitousLanguageTerms(ubiquitousLanguage)) {
+    let file = filterMarkdownForAgents(fs.readFileSync(ubiquitousLanguage.filePath, 'utf8'));
+
+    return new Response(file, { status: 200 });
+  }
+
+  return new Response('Not found', { status: 404 });
+};
diff --git a/eventcatalog/src/pages/docs/[type]/[id]/language/[dictionaryId]/_index.data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language/[dictionaryId]/_index.data.ts
similarity index 100%
rename from eventcatalog/src/pages/docs/[type]/[id]/language/[dictionaryId]/_index.data.ts
rename to packages/core/eventcatalog/src/pages/docs/[type]/[id]/language/[dictionaryId]/_index.data.ts
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language/[dictionaryId]/index.astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language/[dictionaryId]/index.astro
new file mode 100644
index 000000000..017d2b20b
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language/[dictionaryId]/index.astro
@@ -0,0 +1,196 @@
+---
+import RectangleGroupIcon from '@heroicons/react/24/outline/RectangleGroupIcon';
+import Badge from '@components/Badge.astro';
+import Footer from '@layouts/Footer.astro';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { buildUrl } from '@utils/url-builder';
+import { ClientRouter } from 'astro:transitions';
+import { marked } from 'marked';
+import * as LucideIcons from 'lucide-react';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+const props = await Page.getData(Astro);
+
+const { ubiquitousLanguage } = props;
+const pageTitle = `${props.type} | ${ubiquitousLanguage.name}`.replace(/^\w/, (c) => c.toUpperCase());
+
+marked.setOptions({
+  breaks: true,
+  gfm: true,
+});
+
+const badges = [
+  {
+    content: props.domain.name,
+    icon: RectangleGroupIcon,
+  },
+];
+---
+
+<VerticalSideBarLayout title={pageTitle} description={ubiquitousLanguage.summary}>
+  <main
+    class="flex sm:px-8 docs-layout min-h-full max-w-7xl bg-[rgb(var(--ec-page-bg))]"
+    data-pagefind-body
+    data-pagefind-meta={`title:${pageTitle}`}
+  >
+    <div class="flex docs-layout w-full">
+      <div class="w-full lg:mr-2 pr-8 py-8 min-h-[50em]">
+        {/* Breadcrumb */}
+        <nav class="mb-4 flex items-center space-x-2 text-sm text-[rgb(var(--ec-page-text-muted))]" aria-label="Breadcrumb">
+          <a
+            href={buildUrl(`/docs/${props.type}/${props.domainId}/${props.domain.latestVersion}`)}
+            class="hover:text-[rgb(var(--ec-page-text))] hover:underline flex items-center gap-2"
+          >
+            <RectangleGroupIcon className="h-4 w-4" />
+            {props.domain.name}
+          </a>
+          <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7"></path>
+          </svg>
+          <a
+            href={buildUrl(`/docs/${props.type}/${props.domainId}/language`)}
+            class="hover:text-[rgb(var(--ec-page-text))] hover:underline flex items-center gap-2"
+          >
+            {
+              (() => {
+                const BookOpen = LucideIcons.BookOpen;
+                //@ts-ignore
+                return <BookOpen className="h-4 w-4" />;
+              })()
+            }
+            Ubiquitous Language Explorer
+          </a>
+          <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7"></path>
+          </svg>
+          <span class="text-[rgb(var(--ec-page-text))]">{ubiquitousLanguage.name}</span>
+        </nav>
+
+        <div class="border-b border-[rgb(var(--ec-page-border))] flex justify-between items-start md:pb-2">
+          <div>
+            <h2 id="doc-page-header" class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">
+              {ubiquitousLanguage.name}
+            </h2>
+            <p class="text-lg pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{ubiquitousLanguage.summary}</p>
+            <!-- Add badge -->
+            {
+              badges && badges.length > 0 && (
+                <div class="flex flex-wrap gap-3 py-4">
+                  {badges.map((badge: any) => {
+                    return <Badge badge={badge} />;
+                  })}
+                </div>
+              )
+            }
+          </div>
+        </div>
+
+        {
+          ubiquitousLanguage.description && (
+            <div class="prose prose-md py-4 max-w-none" set:html={marked.parse(ubiquitousLanguage.description)} />
+          )
+        }
+
+        {
+          !ubiquitousLanguage.description && (
+            <div class="prose prose-md py-4 max-w-none">
+              <p>No description for {ubiquitousLanguage.name} available.</p>
+            </div>
+          )
+        }
+
+        <Footer />
+      </div>
+    </div>
+    <ClientRouter />
+  </main>
+
+  <script>
+    function initializeSearch() {
+      const searchInput = document.getElementById('searchInput');
+      const termCards = document.querySelectorAll('.term-card');
+      const noSearchResults = document.getElementById('noSearchResults');
+
+      searchInput?.addEventListener('input', (e) => {
+        const searchTerm = (e.target as HTMLInputElement).value.toLowerCase();
+        let visibleCount = 0;
+
+        termCards.forEach((card) => {
+          const title = card.querySelector('h3')?.textContent?.toLowerCase() || '';
+          const description = card.querySelector('p')?.textContent?.toLowerCase() || '';
+          const matches = title.includes(searchTerm) || description.includes(searchTerm);
+
+          card.classList.toggle('hidden', !matches);
+          if (matches) visibleCount++;
+        });
+
+        // Show/hide no results message
+        if (noSearchResults) {
+          noSearchResults.classList.toggle('hidden', visibleCount > 0);
+        }
+      });
+    }
+
+    function initializeShowMore() {
+      const cards = document.querySelectorAll('.term-card');
+
+      cards.forEach((card) => {
+        const newCard = card.cloneNode(true);
+        if (card.parentNode) {
+          card.parentNode.replaceChild(newCard, card);
+          // Initially show summary
+          const summary = (newCard as Element).querySelector('.summary-text');
+          summary?.classList.add('visible');
+        }
+        newCard.addEventListener('click', () => {
+          const description = (newCard as Element).querySelector('.description-text');
+          const summary = (newCard as Element).querySelector('.summary-text');
+          const showMoreText = (newCard as Element).querySelector('.show-more-text');
+
+          if (description && summary && showMoreText) {
+            (newCard as Element).classList.toggle('expanded');
+            description.classList.toggle('visible');
+            summary.classList.toggle('visible');
+            showMoreText.textContent = description.classList.contains('visible') ? 'Show less' : 'Show more';
+          }
+        });
+      });
+    }
+
+    function highlightMatchingTerm() {
+      const urlParams = new URLSearchParams(window.location.search);
+      const termId = urlParams.get('id');
+
+      if (termId) {
+        const cards = document.querySelectorAll('.term-card');
+        cards.forEach((card) => {
+          const termName = card.querySelector('h3')?.textContent?.trim();
+          if (termName?.toLowerCase() === termId.toLowerCase()) {
+            // Add highlight class
+            card.classList.add('highlighted');
+            (card as HTMLElement).click();
+
+            setTimeout(() => {
+              // Scroll into view
+              card.scrollIntoView({ behavior: 'smooth', block: 'center' });
+            }, 300);
+          }
+        });
+      }
+    }
+
+    document.addEventListener('astro:page-load', () => {
+      initializeShowMore();
+      initializeSearch();
+      highlightMatchingTerm();
+    });
+
+    initializeShowMore();
+    initializeSearch();
+    highlightMatchingTerm();
+  </script>
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language/_index.data.ts b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language/_index.data.ts
new file mode 100644
index 000000000..93c7deb36
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language/_index.data.ts
@@ -0,0 +1,52 @@
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+
+/**
+ * Domain page class with static methods
+ */
+export class Page extends HybridPage {
+  static async getStaticPaths() {
+    if (isSSR()) {
+      return [];
+    }
+
+    const { getDomains, hasUbiquitousLanguageTermsWithSubdomains } = await import('@utils/collections/domains');
+    const domains = await getDomains({ getAllVersions: false });
+    const domainsWithUbiquitousLanguage = await domains.reduce<Promise<typeof domains>>(async (acc, domain) => {
+      const accumulator = await acc;
+
+      if (await hasUbiquitousLanguageTermsWithSubdomains(domain)) {
+        return [...accumulator, domain];
+      }
+
+      return accumulator;
+    }, Promise.resolve([]));
+
+    return domainsWithUbiquitousLanguage.map((item) => ({
+      params: {
+        type: item.collection,
+        id: item.data.id,
+      },
+      props: {},
+    }));
+  }
+
+  protected static async fetchData(params: any) {
+    const { getDomains, hasUbiquitousLanguageTermsWithSubdomains } = await import('@utils/collections/domains');
+    const domains = await getDomains({ getAllVersions: false });
+    const domain = domains.find((d) => d.data.id === params.id && d.collection === params.type);
+
+    if (!domain || !(await hasUbiquitousLanguageTermsWithSubdomains(domain))) {
+      return null;
+    }
+
+    return domain;
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Domain not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language/index.astro b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language/index.astro
new file mode 100644
index 000000000..eadd6b3a0
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/[type]/[id]/language/index.astro
@@ -0,0 +1,421 @@
+---
+import Footer from '@layouts/Footer.astro';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { getUbiquitousLanguageWithSubdomains } from '@utils/collections/domains';
+import { buildUrl } from '@utils/url-builder';
+import { ClientRouter } from 'astro:transitions';
+import * as LucideIcons from 'lucide-react';
+import { RectangleGroupIcon } from '@heroicons/react/24/outline';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+const pageTitle = `${props.collection} | ${props.data.name}`.replace(/^\w/, (c) => c.toUpperCase());
+const ubiquitousLanguageData = await getUbiquitousLanguageWithSubdomains(props);
+const ubiquitousLanguage = ubiquitousLanguageData.domain;
+const { subdomains, duplicateTerms } = ubiquitousLanguageData;
+---
+
+<VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
+  <main
+    class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]"
+    data-pagefind-body
+    data-pagefind-meta={`title:${pageTitle}`}
+  >
+    <div class="flex docs-layout w-full">
+      <div class="w-full lg:mr-2 pr-24 py-8 min-h-[50em]">
+        {/* Title Section */}
+        <div class="relative border-b border-[rgb(var(--ec-page-border))] mb-6 pb-6">
+          <div class="xl:flex xl:items-start xl:justify-between">
+            <div class="min-w-0 flex-1">
+              <h1 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">Ubiquitous Language</h1>
+              <p class="pt-2 text-base text-[rgb(var(--ec-page-text-muted))] font-light">
+                Browse and discover ubiquitous language terms in the {props.data.name} domain{
+                  subdomains.length > 0 ? ' and its subdomains' : ''
+                }
+              </p>
+            </div>
+
+            <div class="mt-4 xl:mt-0 xl:ml-4 xl:flex-shrink-0">
+              <div class="relative w-full xl:w-80">
+                <input
+                  type="text"
+                  id="searchInput"
+                  placeholder="Search terms..."
+                  class="block w-full rounded-md border-0 py-1.5 pr-4 pl-10 text-sm font-light text-[rgb(var(--ec-header-text))] bg-[rgb(var(--ec-header-bg))] shadow-xs ring-1 ring-inset ring-[rgb(var(--ec-dropdown-border))] placeholder:text-[rgb(var(--ec-icon-color))] focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:outline-none"
+                />
+                <div class="absolute inset-y-0 left-0 pl-3 flex items-center pointer-events-none">
+                  <svg class="h-4 w-4 text-[rgb(var(--ec-icon-color))]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path
+                      stroke-linecap="round"
+                      stroke-linejoin="round"
+                      stroke-width="2"
+                      d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path>
+                  </svg>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {
+          !ubiquitousLanguage && subdomains.length === 0 && (
+            <div class="flex flex-col items-center justify-center py-16 px-4">
+              <div class="flex items-center justify-center w-16 h-16 rounded-full bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] mb-4">
+                {(() => {
+                  const BookOpen = LucideIcons.BookOpen;
+                  //@ts-ignore
+                  return <BookOpen className="w-8 h-8 text-[rgb(var(--ec-icon-color))]" />;
+                })()}
+              </div>
+              <h3 class="text-lg font-medium text-[rgb(var(--ec-page-text))] mb-2">No ubiquitous language defined</h3>
+              <p class="text-sm text-[rgb(var(--ec-page-text-muted))] text-center max-w-md">
+                This domain does not have any defined ubiquitous language terms yet. Consider adding some terms to help establish
+                a common vocabulary for your domain.
+              </p>
+            </div>
+          )
+        }
+
+        <div class="py-4 w-full min-h-[calc(100vh-10em)]">
+          {
+            (ubiquitousLanguage || subdomains.some((s) => s.ubiquitousLanguage)) && (
+              <div>
+                {/* Domain Language Section */}
+                {ubiquitousLanguage && (
+                  <div class="mb-10" data-domain-section="main">
+                    <div class="flex items-center justify-between mb-5">
+                      <div class="flex items-center gap-3">
+                        {/* <div class="flex items-center justify-center w-8 h-8 rounded-lg bg-gray-900">
+                          <RectangleGroupIcon className="w-4 h-4 text-white" />
+                        </div> */}
+                        <h3 class="text-xl font-semibold text-[rgb(var(--ec-page-text))]">
+                          {props.data.name} Domain Language
+                          <span class="ml-1 text-sm font-normal text-[rgb(var(--ec-page-text-muted))]">
+                            ({ubiquitousLanguage?.data?.dictionary?.length || 0} terms)
+                          </span>
+                        </h3>
+                      </div>
+                    </div>
+                    <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4" data-terms-grid="main">
+                      {ubiquitousLanguage?.data?.dictionary?.map((term) => (
+                        <a
+                          href={buildUrl(`/docs/${props.collection}/${props.data.id}/language/${term.id}`)}
+                          class={`term-card group block bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border rounded-lg p-5 transition-all duration-200 hover:shadow-md hover:border-[rgb(var(--ec-accent)/0.5)] hover:-translate-y-0.5 ${duplicateTerms.has(term.name.toLowerCase()) ? 'border-orange-500/50 dark:border-orange-500/30' : 'border-[rgb(var(--ec-page-border))]'}`}
+                          data-domain="main"
+                        >
+                          <div class="flex flex-col h-full">
+                            <div class="flex items-start justify-between gap-3 mb-3">
+                              <div class="flex items-center gap-2.5">
+                                {term.icon ? (
+                                  <div class="flex items-center justify-center w-8 h-8 rounded-md bg-[rgb(var(--ec-accent-subtle))] transition-colors">
+                                    {(() => {
+                                      const Icon = LucideIcons[term.icon as keyof typeof LucideIcons];
+                                      //@ts-ignore
+                                      return Icon ? <Icon className="w-4 h-4 text-[rgb(var(--ec-accent))]" /> : null;
+                                    })()}
+                                  </div>
+                                ) : (
+                                  <div class="flex items-center justify-center w-8 h-8 rounded-md bg-[rgb(var(--ec-accent-subtle))] transition-colors">
+                                    {(() => {
+                                      const BookText = LucideIcons.BookText;
+                                      //@ts-ignore
+                                      return <BookText className="w-4 h-4 text-[rgb(var(--ec-accent))]" />;
+                                    })()}
+                                  </div>
+                                )}
+                                <h4
+                                  class={`text-base font-semibold group-hover:text-[rgb(var(--ec-icon-hover))] transition-colors ${duplicateTerms.has(term.name.toLowerCase()) ? 'text-orange-500 dark:text-orange-400' : 'text-[rgb(var(--ec-page-text))]'}`}
+                                >
+                                  {term.name}
+                                </h4>
+                              </div>
+                              {duplicateTerms.has(term.name.toLowerCase()) && (
+                                <span class="flex-shrink-0 inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-orange-500/10 text-orange-500 dark:text-orange-400 border border-orange-500/20">
+                                  Duplicate
+                                </span>
+                              )}
+                            </div>
+                            <p class="summary-text text-[rgb(var(--ec-page-text-muted))] text-sm leading-relaxed line-clamp-3 flex-grow mb-3">
+                              {term.summary}
+                            </p>
+                            <div class="pt-3 border-t border-[rgb(var(--ec-page-border))]">
+                              <span class="inline-flex items-center text-sm text-[rgb(var(--ec-page-text-muted))] font-medium group-hover:text-[rgb(var(--ec-page-text))]">
+                                View details
+                                <svg
+                                  class="ml-1 w-4 h-4 transition-transform group-hover:translate-x-0.5"
+                                  fill="none"
+                                  stroke="currentColor"
+                                  viewBox="0 0 24 24"
+                                >
+                                  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" />
+                                </svg>
+                              </span>
+                            </div>
+                          </div>
+                        </a>
+                      ))}
+                    </div>
+                    <div
+                      class="hidden domain-no-results text-center py-12 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] rounded-lg border border-[rgb(var(--ec-page-border))] border-dashed"
+                      data-domain-no-results="main"
+                    >
+                      <div class="flex items-center justify-center w-12 h-12 mx-auto mb-4 rounded-full bg-[rgb(var(--ec-content-hover))]">
+                        <svg
+                          class="w-6 h-6 text-[rgb(var(--ec-icon-color))]"
+                          fill="none"
+                          stroke="currentColor"
+                          viewBox="0 0 24 24"
+                        >
+                          <path
+                            stroke-linecap="round"
+                            stroke-linejoin="round"
+                            stroke-width="2"
+                            d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+                          />
+                        </svg>
+                      </div>
+                      <h4 class="text-base font-medium text-[rgb(var(--ec-page-text))]">
+                        No matching terms in {props.data.name}
+                      </h4>
+                      <p class="mt-1 text-sm text-[rgb(var(--ec-page-text-muted))]">Try adjusting your search terms.</p>
+                    </div>
+                  </div>
+                )}
+
+                {/* Subdomain Language Sections */}
+                {subdomains
+                  .filter((s) => s.ubiquitousLanguage)
+                  .map(({ subdomain, ubiquitousLanguage: subdomainUL }) => (
+                    <div class="mb-10" data-domain-section={subdomain.data.id}>
+                      <div class="flex items-center justify-between mb-5">
+                        <div class="flex items-center gap-3">
+                          {/* <div class="flex items-center justify-center w-8 h-8 rounded-lg bg-gray-200">
+                            <RectangleGroupIcon className="w-4 h-4 text-gray-700" />
+                          </div> */}
+                          <h3 class="text-xl font-semibold text-[rgb(var(--ec-page-text))]">
+                            {subdomain.data.name} Domain Language
+                            <span class="ml-1 text-sm font-normal text-[rgb(var(--ec-page-text-muted))]">
+                              ({subdomainUL?.data?.dictionary?.length || 0} terms)
+                            </span>
+                          </h3>
+                        </div>
+                        <a
+                          href={buildUrl(`/docs/domains/${subdomain.data.id}/${subdomain.data.version}`)}
+                          class="inline-flex items-center text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] font-medium transition-colors"
+                        >
+                          View Domain
+                          <svg class="ml-1 w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" />
+                          </svg>
+                        </a>
+                      </div>
+                      <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4" data-terms-grid={subdomain.data.id}>
+                        {subdomainUL?.data?.dictionary?.map((term) => (
+                          <a
+                            href={buildUrl(`/docs/${props.collection}/${subdomain.data.id}/language/${term.id}`)}
+                            class={`term-card group block bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border rounded-lg p-5 transition-all duration-200 hover:shadow-md hover:border-[rgb(var(--ec-accent)/0.5)] hover:-translate-y-0.5 ${duplicateTerms.has(term.name.toLowerCase()) ? 'border-orange-500/50 dark:border-orange-500/30' : 'border-[rgb(var(--ec-page-border))]'}`}
+                            data-domain={subdomain.data.id}
+                          >
+                            <div class="flex flex-col h-full">
+                              <div class="flex items-start justify-between gap-3 mb-3">
+                                <div class="flex items-center gap-2.5">
+                                  {term.icon ? (
+                                    <div class="flex items-center justify-center w-8 h-8 rounded-md bg-[rgb(var(--ec-accent-subtle))] transition-colors">
+                                      {(() => {
+                                        const Icon = LucideIcons[term.icon as keyof typeof LucideIcons];
+                                        //@ts-ignore
+                                        return Icon ? <Icon className="w-4 h-4 text-[rgb(var(--ec-accent))]" /> : null;
+                                      })()}
+                                    </div>
+                                  ) : (
+                                    <div class="flex items-center justify-center w-8 h-8 rounded-md bg-[rgb(var(--ec-accent-subtle))] transition-colors">
+                                      {(() => {
+                                        const BookText = LucideIcons.BookText;
+                                        //@ts-ignore
+                                        return <BookText className="w-4 h-4 text-[rgb(var(--ec-accent))]" />;
+                                      })()}
+                                    </div>
+                                  )}
+                                  <h4
+                                    class={`text-base font-semibold group-hover:text-[rgb(var(--ec-icon-hover))] transition-colors ${duplicateTerms.has(term.name.toLowerCase()) ? 'text-orange-500 dark:text-orange-400' : 'text-[rgb(var(--ec-page-text))]'}`}
+                                  >
+                                    {term.name}
+                                  </h4>
+                                </div>
+                                {duplicateTerms.has(term.name.toLowerCase()) && (
+                                  <span class="flex-shrink-0 inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-orange-500/10 text-orange-500 dark:text-orange-400 border border-orange-500/20">
+                                    Duplicate
+                                  </span>
+                                )}
+                              </div>
+                              <p class="summary-text text-[rgb(var(--ec-page-text-muted))] text-sm leading-relaxed line-clamp-3 flex-grow mb-3">
+                                {term.summary}
+                              </p>
+                              <div class="pt-3 border-t border-[rgb(var(--ec-page-border))]">
+                                <span class="inline-flex items-center text-sm text-[rgb(var(--ec-page-text-muted))] font-medium group-hover:text-[rgb(var(--ec-page-text))]">
+                                  View details
+                                  <svg
+                                    class="ml-1 w-4 h-4 transition-transform group-hover:translate-x-0.5"
+                                    fill="none"
+                                    stroke="currentColor"
+                                    viewBox="0 0 24 24"
+                                  >
+                                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" />
+                                  </svg>
+                                </span>
+                              </div>
+                            </div>
+                          </a>
+                        ))}
+                      </div>
+                      <div
+                        class="hidden domain-no-results text-center py-12 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] rounded-lg border border-[rgb(var(--ec-page-border))] border-dashed"
+                        data-domain-no-results={subdomain.data.id}
+                      >
+                        <div class="flex items-center justify-center w-12 h-12 mx-auto mb-4 rounded-full bg-[rgb(var(--ec-content-hover))]">
+                          <svg
+                            class="w-6 h-6 text-[rgb(var(--ec-icon-color))]"
+                            fill="none"
+                            stroke="currentColor"
+                            viewBox="0 0 24 24"
+                          >
+                            <path
+                              stroke-linecap="round"
+                              stroke-linejoin="round"
+                              stroke-width="2"
+                              d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+                            />
+                          </svg>
+                        </div>
+                        <h4 class="text-base font-medium text-[rgb(var(--ec-page-text))]">
+                          No matching terms in {subdomain.data.name}
+                        </h4>
+                        <p class="mt-1 text-sm text-[rgb(var(--ec-page-text-muted))]">Try adjusting your search terms.</p>
+                      </div>
+                    </div>
+                  ))}
+              </div>
+            )
+          }
+        </div>
+
+        <Footer />
+      </div>
+    </div>
+    <ClientRouter />
+  </main>
+
+  <script>
+    function initializeSearch() {
+      const searchInput = document.getElementById('searchInput');
+      const domainSections = document.querySelectorAll('[data-domain-section]');
+
+      function updateResults() {
+        //@ts-ignore
+        const searchTerm = searchInput?.value.toLowerCase() || '';
+
+        domainSections.forEach((section) => {
+          const domainId = section.getAttribute('data-domain-section');
+          const domainCards = section.querySelectorAll('.term-card');
+          const domainNoResults = section.querySelector(`[data-domain-no-results="${domainId}"]`);
+          let domainVisibleCount = 0;
+
+          domainCards.forEach((card) => {
+            const title = card.querySelector('h4')?.textContent?.toLowerCase() || '';
+            const description = card.querySelector('p')?.textContent?.toLowerCase() || '';
+            const matches = searchTerm === '' || title.includes(searchTerm) || description.includes(searchTerm);
+
+            card.classList.toggle('hidden', !matches);
+            if (matches) domainVisibleCount++;
+          });
+
+          if (domainNoResults) {
+            if (searchTerm.trim() === '') {
+              domainNoResults.classList.add('hidden');
+            } else {
+              domainNoResults.classList.toggle('hidden', domainVisibleCount > 0);
+            }
+          }
+        });
+      }
+
+      searchInput?.addEventListener('input', updateResults);
+      updateResults();
+    }
+
+    function initializeShowMore() {
+      const cards = document.querySelectorAll('.term-card');
+      cards.forEach((card) => {
+        const summary = card.querySelector('.summary-text');
+        if (summary) {
+          summary.classList.add('visible');
+        }
+      });
+    }
+
+    function highlightMatchingTerm() {
+      const urlParams = new URLSearchParams(window.location.search);
+      const termId = urlParams.get('id');
+
+      if (termId) {
+        const cards = document.querySelectorAll('.term-card');
+        cards.forEach((card) => {
+          const termName = card.querySelector('h3')?.textContent?.trim();
+          if (termName?.toLowerCase() === termId.toLowerCase()) {
+            // Add highlight class
+            card.classList.add('highlighted');
+            (card as HTMLElement).click();
+
+            setTimeout(() => {
+              // Scroll into view
+              card.scrollIntoView({ behavior: 'smooth', block: 'center' });
+            }, 300);
+          }
+        });
+      }
+    }
+
+    document.addEventListener('astro:page-load', () => {
+      initializeShowMore();
+      initializeSearch();
+      highlightMatchingTerm();
+    });
+
+    initializeShowMore();
+    initializeSearch();
+    highlightMatchingTerm();
+  </script>
+
+  <style is:global>
+    .term-card.highlighted {
+      border-color: #111827;
+      box-shadow: 0 0 0 2px #111827;
+      animation: pulse 1s;
+    }
+
+    @keyframes pulse {
+      0%,
+      100% {
+        transform: scale(1);
+        box-shadow: 0 0 0 2px #111827;
+      }
+      50% {
+        transform: scale(1.01);
+        box-shadow: 0 0 0 4px #111827;
+      }
+    }
+
+    .line-clamp-3 {
+      display: -webkit-box;
+      -webkit-line-clamp: 3;
+      -webkit-box-orient: vertical;
+      overflow: hidden;
+    }
+  </style>
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/pages/docs/llm/llms-full.txt.ts b/packages/core/eventcatalog/src/pages/docs/llm/llms-full.txt.ts
new file mode 100644
index 000000000..a96d7b1a2
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/llm/llms-full.txt.ts
@@ -0,0 +1,94 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import type { APIRoute } from 'astro';
+import fs from 'fs';
+import { isCustomDocsEnabled, isResourceDocsEnabled, isLLMSTxtEnabled } from '@utils/feature';
+import { addSchemaToMarkdown, filterMarkdownForAgents } from '@utils/llms';
+
+type AllowedCollections =
+  | 'agents'
+  | 'events'
+  | 'commands'
+  | 'queries'
+  | 'services'
+  | 'data-products'
+  | 'domains'
+  | 'teams'
+  | 'users'
+  | 'customPages'
+  | 'channels'
+  | 'entities'
+  | 'flows'
+  | 'containers'
+  | 'ubiquitousLanguages'
+  | 'resourceDocs';
+
+const events = await getCollection('events');
+const commands = await getCollection('commands');
+const queries = await getCollection('queries');
+const agents = await getCollection('agents');
+const services = await getCollection('services');
+const dataProducts = await getCollection('data-products');
+const domains = await getCollection('domains');
+const teams = await getCollection('teams');
+const users = await getCollection('users');
+const entities = await getCollection('entities');
+const channels = await getCollection('channels');
+const flows = await getCollection('flows');
+const containers = await getCollection('containers');
+const ubiquitousLanguages = await getCollection('ubiquitousLanguages');
+const customDocs = await getCollection('customPages');
+const resourceDocs = isResourceDocsEnabled() ? await getCollection('resourceDocs') : [];
+
+export const GET: APIRoute = async ({ params, request }) => {
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  const resources: CollectionEntry<AllowedCollections>[] = [
+    ...events,
+    ...commands,
+    ...queries,
+    ...agents,
+    ...services,
+    ...dataProducts,
+    ...domains,
+    ...teams,
+    ...users,
+    ...entities,
+    ...channels,
+    ...containers,
+    ...flows,
+    ...ubiquitousLanguages,
+  ];
+
+  if (isCustomDocsEnabled()) {
+    resources.push(...(customDocs as CollectionEntry<AllowedCollections>[]));
+  }
+
+  if (isResourceDocsEnabled()) {
+    resources.push(...(resourceDocs as CollectionEntry<AllowedCollections>[]));
+  }
+
+  const content = resources
+    .map((item) => {
+      if (!item.filePath) return '';
+      if (!fs.existsSync(item.filePath)) return '';
+
+      let file = fs.readFileSync(item.filePath, 'utf8');
+
+      try {
+        // Try and add the schemas to the resource
+        // @ts-ignore
+        file = addSchemaToMarkdown(item, file);
+      } catch (error) {
+        // just skip the resource if it has no schema
+      }
+
+      return filterMarkdownForAgents(file);
+    })
+    .join('\n');
+
+  return new Response(content, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};
diff --git a/packages/core/eventcatalog/src/pages/docs/llm/llms.txt.ts b/packages/core/eventcatalog/src/pages/docs/llm/llms.txt.ts
new file mode 100644
index 000000000..1b09fc102
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/llm/llms.txt.ts
@@ -0,0 +1,178 @@
+import { getCollection } from 'astro:content';
+import config from '@config';
+import type { APIRoute } from 'astro';
+
+import { isCustomDocsEnabled, isResourceDocsEnabled, isLLMSTxtEnabled } from '@utils/feature';
+import { getUbiquitousLanguage } from '@utils/collections/domains';
+import { getResourceDocs } from '@utils/collections/resource-docs';
+
+const events = await getCollection('events');
+const commands = await getCollection('commands');
+const queries = await getCollection('queries');
+
+const agents = await getCollection('agents');
+const services = await getCollection('services');
+const dataProducts = await getCollection('data-products');
+const domains = await getCollection('domains');
+
+const teams = await getCollection('teams');
+const users = await getCollection('users');
+
+const flows = await getCollection('flows');
+const channels = await getCollection('channels');
+const containers = await getCollection('containers');
+
+const entities = await getCollection('entities');
+
+const customDocs = await getCollection('customPages');
+const resourceDocsList = isResourceDocsEnabled() ? await getResourceDocs() : [];
+
+const ubiquitousLanguages: Record<string, { id: string; version: string; properties: any }[]> = {};
+
+for (const domain of domains) {
+  const ubiquitousLanguagesForDomain = await getUbiquitousLanguage(domain);
+  if (ubiquitousLanguagesForDomain.length > 0) {
+    ubiquitousLanguages[domain.id] = ubiquitousLanguagesForDomain.map((item) => ({
+      id: domain.id,
+      version: domain.data.version,
+      properties: item.data.dictionary,
+    }));
+  }
+}
+
+// Render the Ubiquitous Languages section
+const renderUbiquitousLanguages = (baseUrl: string) => {
+  return Object.entries(ubiquitousLanguages)
+    .map(([domainId, items]) => {
+      const domainName = domains.find((domain) => domain.id === domainId)?.data.name || domainId;
+      const itemsList = items
+        .map((item) => {
+          // @ts-ignore
+          const propertiesList = Object.entries(item.properties)
+            .map(
+              ([key, value]: any) =>
+                `    - [${value.name}: - ${value.summary}](${baseUrl}/docs/domains/${domainId.split('-')[0]}/language.mdx)`
+            )
+            .join('\n');
+          return propertiesList;
+        })
+        .join('\n');
+      return `- ${domainName} Domain\n${itemsList}`;
+    })
+    .join('\n');
+};
+
+// render the entities from the domain list
+const renderEntities = (baseUrl: string) => {
+  const domainsWithEntities = domains.filter((domain) => domain.data.entities?.length && domain.data.entities.length > 0);
+
+  if (domainsWithEntities.length === 0) {
+    return '';
+  }
+
+  return domainsWithEntities
+    .map((domain) => {
+      const entitiesList = domain.data.entities
+        ?.map((entity) => {
+          const entityItem = entities.find((e) => e.data.id === entity.id);
+          return `    - [${entityItem?.data.name}](${baseUrl}/docs/entities/${entityItem?.data.id}/${entityItem?.data.version}.mdx) - ${entityItem?.data.summary}`;
+        })
+        .join('\n');
+      return `- ${domain.data.name} Domain\n${entitiesList || ''}`;
+    })
+    .join('\n');
+};
+
+export const GET: APIRoute = async ({ params, request }) => {
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  const url = new URL(request.url);
+  const baseUrl = process.env.LLMS_TXT_BASE_URL || `${url.origin}`;
+
+  const formatVersionedItem = (item: any, type: string, extraParams?: string | string[]) => {
+    const params = Array.isArray(extraParams) ? extraParams.join('&') : extraParams || '';
+    return `- [${item.data.name} - ${item.data.id} - ${item.data.version} ${params ? `- ${params}` : ''}](${baseUrl}/docs/${type}/${item.data.id}/${item.data.version}.mdx) ${item.data.summary ? `- ${item.data.summary}` : ''}`;
+  };
+
+  const formatSimpleItem = (item: any, type: string) =>
+    `- [${item.id.replace('.mdx', '')}](${baseUrl}/docs/${type}/${item.data.id}.mdx) - ${item.data.name}`;
+
+  const formatCustomDoc = (item: any, route: string) =>
+    `- [${item.data.title}](${baseUrl}/${route}/${item.id.replace('docs\/', '')}.mdx) - ${item.data.summary || ''}`;
+
+  const formatResourceDoc = (doc: any) => {
+    const { resourceCollection, resourceId, resourceVersion, type, id } = doc.data;
+    const title = doc.data.title || id || doc.id;
+    const docUrl = `${baseUrl}/docs/${resourceCollection}/${resourceId}/${resourceVersion}/${type}/${id}.mdx`;
+    return `- [${title}](${docUrl})${doc.data.summary ? ` - ${doc.data.summary}` : ''}`;
+  };
+
+  const renderResourceDocs = () => {
+    const grouped = new Map<string, { resourceCollection: string; resourceId: string; resourceVersion: string; docs: any[] }>();
+
+    for (const doc of resourceDocsList) {
+      const { resourceCollection, resourceId, resourceVersion } = doc.data;
+      const key = `${resourceCollection}:${resourceId}:${resourceVersion}`;
+      let group = grouped.get(key);
+      if (!group) {
+        group = { resourceCollection, resourceId, resourceVersion, docs: [] };
+        grouped.set(key, group);
+      }
+      group.docs.push(doc);
+    }
+
+    return Array.from(grouped.values())
+      .map((group) => {
+        const parentUrl = `${baseUrl}/docs/${group.resourceCollection}/${group.resourceId}/${group.resourceVersion}.mdx`;
+        const heading = `### [${group.resourceId}](${parentUrl}) (${group.resourceCollection})`;
+        return [heading, group.docs.map(formatResourceDoc).join('\n')].join('\n');
+      })
+      .join('\n\n');
+  };
+
+  const content = [
+    `# ${config.organizationName} EventCatalog Documentation\n`,
+    `> ${config.tagline}\n`,
+    '## Events',
+    events.map((item) => formatVersionedItem(item, 'events')).join(''),
+    '\n## Commands',
+    commands.map((item) => formatVersionedItem(item, 'commands')).join(''),
+    '\n## Queries',
+    queries.map((item) => formatVersionedItem(item, 'queries')).join(''),
+    '\n## Agents',
+    agents.map((item) => formatVersionedItem(item, 'agents')).join(''),
+    '\n## Services',
+    services.map((item) => formatVersionedItem(item, 'services')).join(''),
+    '\n## Data Products',
+    dataProducts.map((item) => formatVersionedItem(item, 'data-products')).join('\n'),
+    '\n## Domains',
+    domains.map((item) => formatVersionedItem(item, 'domains')).join(''),
+    '\n## Flows',
+    flows.map((item) => formatVersionedItem(item, 'flows')).join('\n'),
+    '\n## Channels',
+    channels
+      .map((item) =>
+        formatVersionedItem(item, 'channels', item.data.protocols?.map((protocol) => `protocol - ${protocol}`).join('&'))
+      )
+      .join(''),
+    ...(Object.keys(ubiquitousLanguages).length > 0 ? ['## Ubiquitous Language', renderUbiquitousLanguages(baseUrl)] : []),
+    '\n## Containers (Databases, External Systems)',
+    containers.map((item) => formatVersionedItem(item, 'containers')).join('\n'),
+    '\n## Entities',
+    renderEntities(baseUrl),
+    '\n## Teams',
+    teams.map((item) => formatSimpleItem(item, 'teams')).join('\n'),
+    '\n## Users',
+    users.map((item) => formatSimpleItem(item, 'users')).join('\n'),
+    ...(isCustomDocsEnabled()
+      ? ['\n## Custom Docs', customDocs.map((item) => formatCustomDoc(item, 'docs/custom')).join('\n')]
+      : []),
+    ...(isResourceDocsEnabled() && resourceDocsList.length > 0 ? ['\n## Resource Docs', renderResourceDocs()] : []),
+  ].join('\n');
+
+  return new Response(content, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};
diff --git a/packages/core/eventcatalog/src/pages/docs/llm/schemas.txt.ts b/packages/core/eventcatalog/src/pages/docs/llm/schemas.txt.ts
new file mode 100644
index 000000000..5684ac8da
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/llm/schemas.txt.ts
@@ -0,0 +1,94 @@
+import { getCollection } from 'astro:content';
+import config from '@config';
+import type { APIRoute } from 'astro';
+import { getSpecificationsForService } from '@utils/collections/services';
+import { isEventCatalogScaleEnabled } from '@utils/feature';
+
+type MessageCollection = 'events' | 'commands' | 'queries';
+
+const services = await getCollection('services');
+const schemas = await getCollection('schemas');
+
+type ServiceWithSchema = {
+  collection: string;
+  id: string;
+  version: string;
+  specification: string;
+  summary: string;
+};
+
+const servicesWithSchemas = services.filter((service) => getSpecificationsForService(service).length > 0);
+
+const servicesWithSchemasFlat = servicesWithSchemas.reduce<ServiceWithSchema[]>((acc, service) => {
+  return [
+    ...acc,
+    ...getSpecificationsForService(service).map((specification) => ({
+      collection: 'services',
+      id: service.data.id,
+      version: service.data.version,
+      specification: specification.type,
+      summary: service.data.summary?.trim() || '',
+    })),
+  ];
+}, []) as ServiceWithSchema[];
+
+const getMessagesWithSchemas = (collection: MessageCollection) => {
+  const seenMessages = new Set<string>();
+
+  return schemas
+    .filter((schema) => schema.data.message.collection === collection)
+    .map((schema) => {
+      const key = `${schema.data.message.collection}:${schema.data.message.id}:${schema.data.message.version}`;
+      if (seenMessages.has(key)) return null;
+      seenMessages.add(key);
+
+      return schema;
+    })
+    .filter((schema): schema is NonNullable<typeof schema> => schema !== null);
+};
+
+export const GET: APIRoute = async ({ params, request }) => {
+  if (!isEventCatalogScaleEnabled()) {
+    return new Response(
+      JSON.stringify({
+        error: 'feature_not_available_on_server',
+        message: 'Schema API is not enabled for this deployment and supported in EventCatalog Scale.',
+      }),
+      { status: 501, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' } }
+    );
+  }
+
+  const url = new URL(request.url);
+  const baseUrl = process.env.LLMS_TXT_BASE_URL || `${url.origin}`;
+
+  const formatVersionedItem = (item: (typeof schemas)[number]) => {
+    const message = item.data.message;
+    return `- [${message.name || message.id} - ${message.id} - ${message.version}](${baseUrl}/api/schemas/${message.collection}/${message.id}/${message.version})} ${message.summary ? `- ${message.summary.trim()}` : ''}`;
+  };
+
+  const formatServiceWithSchema = (item: ServiceWithSchema) => {
+    return `- [${item.id} - ${item.version} - ${item.specification} specification](${baseUrl}/api/schemas/${item.collection}/${item.id}/${item.version}/${item.specification}) ${item.summary ? `- Specification for ${item.summary}` : ''}`;
+  };
+
+  const content = [
+    `# ${config.organizationName} EventCatalog Schemas`,
+    `List of schemas for events, commands, queries, and services in EventCatalog.`,
+    '',
+    `## Events\n${getMessagesWithSchemas('events')
+      .map((item) => formatVersionedItem(item))
+      .join('\n')}`,
+    '',
+    `## Commands\n${getMessagesWithSchemas('commands')
+      .map((item) => formatVersionedItem(item))
+      .join('\n')}`,
+    '',
+    `## Queries\n${getMessagesWithSchemas('queries')
+      .map((item) => formatVersionedItem(item))
+      .join('\n')}`,
+    '',
+    `## Services\n${servicesWithSchemasFlat.map((item: any) => formatServiceWithSchema(item)).join('\n')}`,
+  ].join('\n');
+  return new Response(content, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};
diff --git a/packages/core/eventcatalog/src/pages/docs/teams/[id].md.ts b/packages/core/eventcatalog/src/pages/docs/teams/[id].md.ts
new file mode 100644
index 000000000..74ac1806a
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/teams/[id].md.ts
@@ -0,0 +1,39 @@
+// This file exposes the markdown for EventCatalog in the Url
+// For example http://localhost:3000/docs/events/OrderAmended/0.0.1 loads the Page and http://localhost:3000/docs/events/OrderAmended/0.0.1.md loads the markdown
+// This is used for the LLMs to load the markdown for the given item (llms.txt);
+
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import config from '@config';
+import fs from 'fs';
+import { isLLMSTxtEnabled } from '@utils/feature';
+import { filterMarkdownForAgents } from '@utils/llms';
+
+const teams = await getCollection('teams');
+
+export async function getStaticPaths() {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return [];
+  }
+
+  return teams.map((team) => ({
+    params: { type: 'teams', id: team.data.id },
+    props: { content: team },
+  }));
+}
+
+export const GET: APIRoute = async ({ params, props }) => {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  const content = props?.content ?? teams.find((team) => team.data.id === params.id);
+  if (content?.filePath) {
+    const file = filterMarkdownForAgents(fs.readFileSync(content.filePath, 'utf8'));
+    return new Response(file, { status: 200 });
+  }
+
+  return new Response('Not found', { status: 404 });
+};
diff --git a/packages/core/eventcatalog/src/pages/docs/teams/[id].mdx.ts b/packages/core/eventcatalog/src/pages/docs/teams/[id].mdx.ts
new file mode 100644
index 000000000..46e470b72
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/teams/[id].mdx.ts
@@ -0,0 +1,38 @@
+// This file exposes the markdown for EventCatalog in the Url
+// For example http://localhost:3000/docs/teams/full-stack loads the Page and http://localhost:3000/docs/teams/full-stack.mdx loads the markdown
+// This is used for the LLMs to load the markdown for the given item (llms.txt);
+
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import { isLLMSTxtEnabled } from '@utils/feature';
+import fs from 'fs';
+import { filterMarkdownForAgents } from '@utils/llms';
+
+const teams = await getCollection('teams');
+
+export async function getStaticPaths() {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return [];
+  }
+
+  return teams.map((team) => ({
+    params: { type: 'teams', id: team.data.id },
+    props: { content: team },
+  }));
+}
+
+export const GET: APIRoute = async ({ params, props }) => {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  const content = props?.content ?? teams.find((team) => team.data.id === params.id);
+  if (content?.filePath) {
+    const file = filterMarkdownForAgents(fs.readFileSync(content.filePath, 'utf8'));
+    return new Response(file, { status: 200 });
+  }
+
+  return new Response('Not found', { status: 404 });
+};
diff --git a/packages/core/eventcatalog/src/pages/docs/teams/[id]/_index.data.ts b/packages/core/eventcatalog/src/pages/docs/teams/[id]/_index.data.ts
new file mode 100644
index 000000000..c460f3bc0
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/teams/[id]/_index.data.ts
@@ -0,0 +1,46 @@
+// pages/teams/[id]/index.page.ts
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+
+export class Page extends HybridPage {
+  static get prerender(): boolean {
+    return !isSSR();
+  }
+
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isSSR()) {
+      return [];
+    }
+
+    const { getTeams } = await import('@utils/collections/teams');
+    const teams = await getTeams();
+
+    return teams.map((team) => ({
+      params: { id: team.data.id },
+      props: team,
+    }));
+  }
+
+  protected static async fetchData(params: any) {
+    const { id } = params;
+
+    if (!id) {
+      return null;
+    }
+
+    const { getTeams } = await import('@utils/collections/teams');
+    const teams = await getTeams();
+
+    // Find the specific team by id
+    const team = teams.find((t) => t.data.id === id);
+
+    return team || null;
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Team not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/docs/teams/[id]/index.astro b/packages/core/eventcatalog/src/pages/docs/teams/[id]/index.astro
new file mode 100644
index 000000000..043debb21
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/teams/[id]/index.astro
@@ -0,0 +1,312 @@
+---
+import components from '@components/MDX/components';
+
+// SideBars
+import { getEntry, render } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import OwnersList from '@components/Lists/OwnersList';
+import PillListFlat from '@components/Lists/PillListFlat';
+import EnvelopeIcon from '@heroicons/react/16/solid/EnvelopeIcon';
+import { Github } from 'lucide-react';
+import { formatAdrStatus } from '@utils/collections/adrs';
+import { buildUrl } from '@utils/url-builder';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+const { Content } = await render(props);
+
+const membersRaw = props.data.members || [];
+const members = (await Promise.all(membersRaw.map((m: CollectionEntry<'teams'>) => getEntry(m)))).filter(Boolean);
+
+const domains = props.data.ownedDomains as CollectionEntry<'domains'>[];
+const systems = props.data.ownedSystems as CollectionEntry<'systems'>[];
+const agents = props.data.ownedAgents as CollectionEntry<'agents'>[];
+const services = props.data.ownedServices as CollectionEntry<'services'>[];
+const events = props.data.ownedEvents as CollectionEntry<'events'>[];
+const commands = props.data.ownedCommands as CollectionEntry<'commands'>[];
+const queries = props.data.ownedQueries as CollectionEntry<'queries'>[];
+const adrs = props.data.ownedAdrs as CollectionEntry<'adrs'>[];
+
+const membersList = members.map((o) => ({
+  label: o.data.name,
+  type: o.collection,
+  badge: o.collection === 'users' ? o.data.role : 'Team',
+  collection: o.collection,
+  avatarUrl: o.collection === 'users' ? o.data.avatarUrl : '',
+  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
+}));
+
+const ownedDomainsList = domains.map((p) => ({
+  label: `${p.data.name}`,
+  collection: p.collection,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  tag: `v${p.data.version}`,
+}));
+
+const ownedSystemsList = systems.map((p) => ({
+  label: `${p.data.name}`,
+  collection: p.collection,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  tag: `v${p.data.version}`,
+}));
+
+const ownedServicesList = services.map((p) => ({
+  label: `${p.data.name}`,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  collection: p.collection,
+  tag: `v${p.data.version}`,
+}));
+
+const ownedAgentsList = agents.map((p) => ({
+  label: `${p.data.name}`,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  collection: p.collection,
+  tag: `v${p.data.version}`,
+}));
+
+const ownedMessagesList = [...events, ...commands, ...queries].map((p) => ({
+  label: `${p.data.name}`,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  color: p.collection === 'events' ? 'orange' : 'blue',
+  collection: p.collection,
+  tag: `v${p.data.version}`,
+}));
+
+const ownedAdrsList = adrs.map((p) => ({
+  label: `${p.data.name}`,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  collection: p.collection,
+  tag: `v${p.data.version}`,
+  description: formatAdrStatus(p.data.status),
+}));
+
+const pageTitle = `Team | ${props.data.name}`;
+const source = props.data.source;
+const sourceLabels: Record<string, string> = {
+  github: 'GitHub',
+  'microsoft-entra': 'Microsoft Entra ID',
+};
+const sourceLabel = source?.provider ? (sourceLabels[source.provider] ?? source.provider) : undefined;
+const sourceTitle = sourceLabel ? `Synced from ${sourceLabel}` : undefined;
+---
+
+<VerticalSideBarLayout title={pageTitle} description={props.data.summary}>
+  <main
+    class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]"
+    data-pagefind-body
+    data-pagefind-meta={`title:${pageTitle}`}
+  >
+    <div class="flex docs-layout w-full">
+      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        <div class="border-b border-[rgb(var(--ec-page-border))] pb-6">
+          <div class="flex justify-start">
+            <div class="flex flex-col justify-between space-y-3">
+              <div>
+                <h2 class="text-3xl font-bold text-[rgb(var(--ec-page-text))]">{props.data.name}</h2>
+              </div>
+              {
+                props.data.summary && (
+                  <p class="text-base text-[rgb(var(--ec-page-text-muted))] max-w-2xl">{props.data.summary}</p>
+                )
+              }
+              <div class="flex flex-wrap gap-3 pt-1">
+                {
+                  props.data.email && (
+                    <a
+                      href={`mailto:${props.data.email}`}
+                      class="inline-flex items-center gap-1.5 text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                    >
+                      <EnvelopeIcon className="w-4 h-4 text-[rgb(var(--ec-icon-color))]" />
+                      <span>Email</span>
+                    </a>
+                  )
+                }
+                {
+                  props.data.slackDirectMessageUrl && (
+                    <a
+                      href={props.data.slackDirectMessageUrl}
+                      class="inline-flex items-center gap-1.5 text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                    >
+                      <img src={buildUrl('/slack-icon.svg', true)} class="w-4 h-4" alt="Slack" />
+                      <span>Slack</span>
+                    </a>
+                  )
+                }
+                {
+                  props.data.msTeamsDirectMessageUrl && (
+                    <a
+                      href={props.data.msTeamsDirectMessageUrl}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      class="inline-flex items-center gap-1.5 text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                    >
+                      <img src={buildUrl('/icons/ms-teams.svg', true)} class="w-4 h-4" alt="Teams" />
+                      <span>Teams</span>
+                    </a>
+                  )
+                }
+                {
+                  source && sourceLabel && source.url && (
+                    <a
+                      href={source.url}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      title={sourceTitle}
+                      class="inline-flex items-center gap-1.5 text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                    >
+                      {source.provider === 'github' && <Github className="w-4 h-4 text-[rgb(var(--ec-icon-color))]" />}
+                      {source.provider === 'microsoft-entra' && <img src={buildUrl('/icons/azure.svg', true)} class="w-4 h-4" alt="" />}
+                      <span>{sourceLabel}</span>
+                    </a>
+                  )
+                }
+                {
+                  source && sourceLabel && !source.url && (
+                    <span
+                      title={sourceTitle}
+                      class="inline-flex items-center gap-1.5 text-sm text-[rgb(var(--ec-page-text-muted))]"
+                    >
+                      {source.provider === 'github' && <Github className="w-4 h-4 text-[rgb(var(--ec-icon-color))]" />}
+                      {source.provider === 'microsoft-entra' && <img src={buildUrl('/icons/azure.svg', true)} class="w-4 h-4" alt="" />}
+                      <span>{sourceLabel}</span>
+                    </span>
+                  )
+                }
+              </div>
+            </div>
+          </div>
+        </div>
+        <div class="border-b border-[rgb(var(--ec-page-border))] py-4" data-pagefind-ignore>
+          <dl class="grid grid-cols-2 gap-3 sm:grid-cols-7">
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Domains</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedDomainsList.length}</dd>
+            </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Systems</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedSystemsList.length}</dd>
+            </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Services</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedServicesList.length}</dd>
+            </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Agents</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedAgentsList.length}</dd>
+            </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Messages</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedMessagesList.length}</dd>
+            </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Decisions</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedAdrsList.length}</dd>
+            </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Members</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{membersList.length}</dd>
+            </div>
+          </dl>
+        </div>
+        <div class="prose prose-md py-4 w-full">
+          <Content components={components(props)} />
+        </div>
+      </div>
+      <aside
+        class="hidden xl:block sticky top-[5.5rem] self-start w-[280px] max-h-[calc(100vh-5.5rem)] overflow-y-auto py-2 flex-shrink-0 pr-10 bg-[rgb(var(--ec-page-bg))]"
+        data-pagefind-ignore
+      >
+        <div class="py-2">
+          {
+            ownedDomainsList.length > 0 && (
+              <PillListFlat
+                color="pink"
+                title={`Owned domains (${ownedDomainsList.length})`}
+                pills={ownedDomainsList}
+                emptyMessage={`${props.data.name} does not own any domains.`}
+                client:load
+              />
+            )
+          }
+          {
+            ownedSystemsList.length > 0 && (
+              <PillListFlat
+                color="pink"
+                title={`Owned systems (${ownedSystemsList.length})`}
+                pills={ownedSystemsList}
+                emptyMessage={`${props.data.name} does not own any systems.`}
+                client:load
+              />
+            )
+          }
+          {
+            ownedServicesList.length > 0 && (
+              <PillListFlat
+                color="blue"
+                title={`Owned services (${ownedServicesList.length})`}
+                pills={ownedServicesList}
+                emptyMessage={`This team does not own any services.`}
+                client:load
+              />
+            )
+          }
+          {
+            ownedAgentsList.length > 0 && (
+              <PillListFlat
+                color="indigo"
+                title={`Owned agents (${ownedAgentsList.length})`}
+                pills={ownedAgentsList}
+                emptyMessage={`This team does not own any agents.`}
+                client:load
+              />
+            )
+          }
+          {
+            ownedMessagesList.length > 0 && (
+              <PillListFlat
+                color="red"
+                title={`Owned messages (${ownedMessagesList.length})`}
+                pills={ownedMessagesList}
+                emptyMessage={`This team does not own any messages.`}
+                client:load
+              />
+            )
+          }
+          {
+            ownedAdrsList.length > 0 && (
+              <PillListFlat
+                color="orange"
+                title={`Owned ADRs (${ownedAdrsList.length})`}
+                pills={ownedAdrsList}
+                emptyMessage={`This team does not own any decision records.`}
+                client:load
+              />
+            )
+          }
+          {
+            membersList.length > 0 && (
+              <OwnersList
+                title={`Team members (${membersList.length})`}
+                owners={membersList}
+                emptyMessage={`This team does not have any members.`}
+                client:load
+              />
+            )
+          }
+        </div>
+      </aside>
+    </div>
+  </main>
+</VerticalSideBarLayout>
+
+<style>
+  .docs-layout .prose {
+    max-width: none;
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/pages/docs/users/[id].md.ts b/packages/core/eventcatalog/src/pages/docs/users/[id].md.ts
new file mode 100644
index 000000000..e45662681
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/users/[id].md.ts
@@ -0,0 +1,39 @@
+// This file exposes the markdown for EventCatalog in the Url
+// For example http://localhost:3000/docs/events/OrderAmended/0.0.1 loads the Page and http://localhost:3000/docs/events/OrderAmended/0.0.1.md loads the markdown
+// This is used for the LLMs to load the markdown for the given item (llms.txt);
+
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import config from '@config';
+import fs from 'fs';
+import { isLLMSTxtEnabled } from '@utils/feature';
+import { filterMarkdownForAgents } from '@utils/llms';
+
+const users = await getCollection('users');
+
+export async function getStaticPaths() {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return [];
+  }
+
+  return users.map((user) => ({
+    params: { type: 'users', id: user.data.id },
+    props: { content: user },
+  }));
+}
+
+export const GET: APIRoute = async ({ params, props }) => {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  const content = props?.content ?? users.find((user) => user.data.id === params.id);
+  if (content?.filePath) {
+    const file = filterMarkdownForAgents(fs.readFileSync(content.filePath, 'utf8'));
+    return new Response(file, { status: 200 });
+  }
+
+  return new Response('Not found', { status: 404 });
+};
diff --git a/packages/core/eventcatalog/src/pages/docs/users/[id].mdx.ts b/packages/core/eventcatalog/src/pages/docs/users/[id].mdx.ts
new file mode 100644
index 000000000..b0686f519
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/users/[id].mdx.ts
@@ -0,0 +1,38 @@
+// This file exposes the markdown for EventCatalog in the Url
+// For example http://localhost:3000/docs/users/dboyne loads the Page and http://localhost:3000/docs/users/dboyne.mdx loads the markdown
+// This is used for the LLMs to load the markdown for the given item (llms.txt);
+
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import { isLLMSTxtEnabled } from '@utils/feature';
+import fs from 'fs';
+import { filterMarkdownForAgents } from '@utils/llms';
+
+const users = await getCollection('users');
+
+export async function getStaticPaths() {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return [];
+  }
+
+  return users.map((user) => ({
+    params: { type: 'users', id: user.data.id },
+    props: { content: user },
+  }));
+}
+
+export const GET: APIRoute = async ({ params, props }) => {
+  // Just return empty array if LLMs are not enabled
+  if (!isLLMSTxtEnabled()) {
+    return new Response('llms.txt is not enabled for this Catalog.', { status: 404 });
+  }
+
+  const content = props?.content ?? users.find((user) => user.data.id === params.id);
+  if (content?.filePath) {
+    const file = filterMarkdownForAgents(fs.readFileSync(content.filePath, 'utf8'));
+    return new Response(file, { status: 200 });
+  }
+
+  return new Response('Not found', { status: 404 });
+};
diff --git a/packages/core/eventcatalog/src/pages/docs/users/[id]/_index.data.ts b/packages/core/eventcatalog/src/pages/docs/users/[id]/_index.data.ts
new file mode 100644
index 000000000..719033e43
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/users/[id]/_index.data.ts
@@ -0,0 +1,46 @@
+// pages/teams/[id]/index.page.ts
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+
+export class Page extends HybridPage {
+  static get prerender(): boolean {
+    return !isSSR();
+  }
+
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isSSR()) {
+      return [];
+    }
+
+    const { getUsers } = await import('@utils/collections/users');
+    const users = await getUsers();
+
+    return users.map((user) => ({
+      params: { id: user.data.id },
+      props: user,
+    }));
+  }
+
+  protected static async fetchData(params: any) {
+    const { id } = params;
+
+    if (!id) {
+      return null;
+    }
+
+    const { getUsers } = await import('@utils/collections/users');
+    const users = await getUsers();
+
+    // Find the specific team by id
+    const user = users.find((u) => u.data.id === id);
+
+    return user || null;
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'User not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/docs/users/[id]/index.astro b/packages/core/eventcatalog/src/pages/docs/users/[id]/index.astro
new file mode 100644
index 000000000..9fa2aedc2
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/docs/users/[id]/index.astro
@@ -0,0 +1,319 @@
+---
+import components from '@components/MDX/components';
+
+// SideBars
+import { render } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import OwnersList from '@components/Lists/OwnersList';
+import PillListFlat from '@components/Lists/PillListFlat';
+import EnvelopeIcon from '@heroicons/react/16/solid/EnvelopeIcon';
+import { Github } from 'lucide-react';
+import { formatAdrStatus } from '@utils/collections/adrs';
+import { buildUrl } from '@utils/url-builder';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+const { Content } = await render(props);
+
+const domains = props.data.ownedDomains as CollectionEntry<'domains'>[];
+const systems = props.data.ownedSystems as CollectionEntry<'systems'>[];
+const agents = props.data.ownedAgents as CollectionEntry<'agents'>[];
+const services = props.data.ownedServices as CollectionEntry<'services'>[];
+const events = props.data.ownedEvents as CollectionEntry<'events'>[];
+const commands = props.data.ownedCommands as CollectionEntry<'commands'>[];
+const queries = props.data.ownedQueries as CollectionEntry<'queries'>[];
+const adrs = props.data.ownedAdrs as CollectionEntry<'adrs'>[];
+const teams = props.data.associatedTeams as CollectionEntry<'teams'>[];
+
+const ownedDomainsList = domains.map((p) => ({
+  label: `${p.data.name}`,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  collection: p.collection,
+  tag: `v${p.data.version}`,
+}));
+
+const ownedSystemsList = systems.map((p) => ({
+  label: `${p.data.name}`,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  collection: p.collection,
+  tag: `v${p.data.version}`,
+}));
+
+const ownedServicesList = services.map((p) => ({
+  label: `${p.data.name}`,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  collection: p.collection,
+  tag: `v${p.data.version}`,
+}));
+
+const ownedAgentsList = agents.map((p) => ({
+  label: `${p.data.name}`,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  collection: p.collection,
+  tag: `v${p.data.version}`,
+}));
+
+const ownedMessageList = [...events, ...commands, ...queries].map((p) => ({
+  label: `${p.data.name}`,
+  badge: p.collection,
+  color: p.collection === 'events' ? 'orange' : 'blue',
+  collection: p.collection,
+  tag: `v${p.data.version}`,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+}));
+
+const ownedAdrsList = adrs.map((p) => ({
+  label: `${p.data.name}`,
+  href: buildUrl(`/docs/${p.collection}/${p.data.id}/${p.data.version}`),
+  collection: p.collection,
+  tag: `v${p.data.version}`,
+  description: formatAdrStatus(p.data.status),
+}));
+
+const associatedTeams = teams.map((o) => ({
+  label: o.data.name,
+  type: o.collection,
+  badge: 'Team',
+  href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
+}));
+
+const pageTitle = `User | ${props.data.name}`;
+const source = props.data.source;
+const sourceLabels: Record<string, string> = {
+  github: 'GitHub',
+  'microsoft-entra': 'Microsoft Entra ID',
+};
+const sourceLabel = source?.provider ? (sourceLabels[source.provider] ?? source.provider) : undefined;
+const sourceTitle = sourceLabel ? `Synced from ${sourceLabel}` : undefined;
+---
+
+<VerticalSideBarLayout title={pageTitle}>
+  <main
+    class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]"
+    data-pagefind-body
+    data-pagefind-meta={`title:${pageTitle}`}
+  >
+    <div class="flex docs-layout w-full">
+      <div class="w-full lg:mr-2 pr-24 py-8 bg-[rgb(var(--ec-page-bg))]">
+        <div class="border-b border-[rgb(var(--ec-page-border))] pb-6">
+          <div class="flex justify-start gap-6">
+            {
+              props.data.avatarUrl && (
+                <img
+                  src={props.data.avatarUrl}
+                  alt={`${props.data.name}'s profile picture`}
+                  class="w-20 h-20 rounded-md object-cover border-2 border-[rgb(var(--ec-page-border))]"
+                />
+              )
+            }
+            <div class="flex flex-col justify-center space-y-2">
+              <div>
+                <h2 class="text-3xl font-bold text-[rgb(var(--ec-page-text))]">{props.data.name}</h2>
+                {
+                  props.data.role && (
+                    <span class="text-base font-medium text-[rgb(var(--ec-page-text-muted))]">{props.data.role}</span>
+                  )
+                }
+              </div>
+              <div class="flex flex-wrap gap-3">
+                {
+                  props.data.email && (
+                    <a
+                      href={`mailto:${props.data.email}`}
+                      class="inline-flex items-center gap-1.5 text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                    >
+                      <EnvelopeIcon className="w-4 h-4 text-[rgb(var(--ec-icon-color))]" />
+                      <span>Email</span>
+                    </a>
+                  )
+                }
+                {
+                  props.data.slackDirectMessageUrl && (
+                    <a
+                      href={props.data.slackDirectMessageUrl}
+                      class="inline-flex items-center gap-1.5 text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                    >
+                      <img src={buildUrl('/slack-icon.svg', true)} class="w-4 h-4" alt="Slack" />
+                      <span>Slack</span>
+                    </a>
+                  )
+                }
+                {
+                  props.data.msTeamsDirectMessageUrl && (
+                    <a
+                      href={props.data.msTeamsDirectMessageUrl}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      class="inline-flex items-center gap-1.5 text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                    >
+                      <img src={buildUrl('/icons/ms-teams.svg', true)} class="w-4 h-4" alt="Teams" />
+                      <span>Teams</span>
+                    </a>
+                  )
+                }
+                {
+                  source && sourceLabel && source.url && (
+                    <a
+                      href={source.url}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      title={sourceTitle}
+                      class="inline-flex items-center gap-1.5 text-sm text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                    >
+                      {source.provider === 'github' && <Github className="w-4 h-4 text-[rgb(var(--ec-icon-color))]" />}
+                      {source.provider === 'microsoft-entra' && <img src={buildUrl('/icons/azure.svg', true)} class="w-4 h-4" alt="" />}
+                      <span>{sourceLabel}</span>
+                    </a>
+                  )
+                }
+                {
+                  source && sourceLabel && !source.url && (
+                    <span
+                      title={sourceTitle}
+                      class="inline-flex items-center gap-1.5 text-sm text-[rgb(var(--ec-page-text-muted))]"
+                    >
+                      {source.provider === 'github' && <Github className="w-4 h-4 text-[rgb(var(--ec-icon-color))]" />}
+                      {source.provider === 'microsoft-entra' && <img src={buildUrl('/icons/azure.svg', true)} class="w-4 h-4" alt="" />}
+                      <span>{sourceLabel}</span>
+                    </span>
+                  )
+                }
+              </div>
+            </div>
+          </div>
+        </div>
+        <div class="border-b border-[rgb(var(--ec-page-border))] py-4" data-pagefind-ignore>
+          <dl class="grid grid-cols-2 gap-3 sm:grid-cols-7">
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Domains</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedDomainsList.length}</dd>
+            </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Systems</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedSystemsList.length}</dd>
+            </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Services</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedServicesList.length}</dd>
+            </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Agents</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedAgentsList.length}</dd>
+            </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Messages</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedMessageList.length}</dd>
+            </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Decisions</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{ownedAdrsList.length}</dd>
+            </div>
+            <div class="flex flex-col p-4 bg-[rgb(var(--ec-content-hover))] rounded-lg">
+              <dt class="text-xs font-medium text-[rgb(var(--ec-page-text-muted))]">Teams</dt>
+              <dd class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-1">{associatedTeams.length}</dd>
+            </div>
+          </dl>
+        </div>
+        <div class="prose prose-md py-4 w-full">
+          <Content components={components(props)} />
+        </div>
+      </div>
+      <aside
+        class="hidden xl:block sticky top-[5.5rem] self-start w-[280px] max-h-[calc(100vh-5.5rem)] overflow-y-auto py-2 flex-shrink-0 pr-10 bg-[rgb(var(--ec-page-bg))]"
+        data-pagefind-ignore
+      >
+        <div class="py-2">
+          {
+            ownedDomainsList.length > 0 && (
+              <PillListFlat
+                color="pink"
+                title={`Owned domains (${ownedDomainsList.length})`}
+                pills={ownedDomainsList}
+                emptyMessage={`${props.data.name} does not own any domains.`}
+                client:load
+              />
+            )
+          }
+          {
+            ownedSystemsList.length > 0 && (
+              <PillListFlat
+                color="pink"
+                title={`Owned systems (${ownedSystemsList.length})`}
+                pills={ownedSystemsList}
+                emptyMessage={`${props.data.name} does not own any systems.`}
+                client:load
+              />
+            )
+          }
+          {
+            ownedServicesList.length > 0 && (
+              <PillListFlat
+                color="pink"
+                title={`Owned services (${ownedServicesList.length})`}
+                pills={ownedServicesList}
+                emptyMessage={`${props.data.name} does not own any services.`}
+                client:load
+              />
+            )
+          }
+          {
+            ownedAgentsList.length > 0 && (
+              <PillListFlat
+                color="indigo"
+                title={`Owned agents (${ownedAgentsList.length})`}
+                pills={ownedAgentsList}
+                emptyMessage={`${props.data.name} does not own any agents.`}
+                client:load
+              />
+            )
+          }
+          {
+            ownedMessageList.length > 0 && (
+              <PillListFlat
+                color="orange"
+                title={`Owned messages (${ownedMessageList.length})`}
+                pills={ownedMessageList}
+                emptyMessage={`${props.data.name} does not own any messages.`}
+                client:load
+              />
+            )
+          }
+          {
+            ownedAdrsList.length > 0 && (
+              <PillListFlat
+                color="orange"
+                title={`Owned ADRs (${ownedAdrsList.length})`}
+                pills={ownedAdrsList}
+                emptyMessage={`${props.data.name} does not own any decision records.`}
+                client:load
+              />
+            )
+          }
+          {
+            associatedTeams.length > 0 && (
+              <OwnersList
+                title={`Member of team (${associatedTeams.length})`}
+                owners={associatedTeams}
+                emptyMessage={`${props.data.name} is not part of any documented team.`}
+                client:load
+              />
+            )
+          }
+        </div>
+      </aside>
+    </div>
+  </main>
+</VerticalSideBarLayout>
+
+<style>
+  .docs-layout .prose {
+    max-width: none;
+    overflow: auto;
+  }
+</style>
diff --git a/packages/core/eventcatalog/src/pages/icepanel/index.astro b/packages/core/eventcatalog/src/pages/icepanel/index.astro
new file mode 100644
index 000000000..254dfb85b
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/icepanel/index.astro
@@ -0,0 +1,67 @@
+---
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { ClientRouter } from 'astro:transitions';
+---
+
+<VerticalSideBarLayout title="IcePanel">
+  <div class="h-[calc(100vh-80px)] bg-[rgb(var(--ec-page-bg))] p-3">
+    <div class="flex items-center justify-between mb-4">
+      <h1 id="diagramTitle" class="text-2xl font-bold text-[rgb(var(--ec-page-text))]">IcePanel Diagram</h1>
+      <div class="flex items-center gap-3">
+        <button
+          id="backButton"
+          class="hidden items-center gap-2 bg-[rgb(var(--ec-card-bg))] border border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle))] px-4 py-2 rounded-md transition-colors"
+        >
+          <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5" viewBox="0 0 20 20" fill="currentColor">
+            <path
+              fill-rule="evenodd"
+              d="M9.707 16.707a1 1 0 01-1.414 0l-6-6a1 1 0 010-1.414l6-6a1 1 0 011.414 1.414L4.414 9H17a1 1 0 110 2H4.414l5.293 5.293a1 1 0 010 1.414z"
+              clip-rule="evenodd"></path>
+          </svg>
+          <span>Back</span>
+        </button>
+      </div>
+    </div>
+    <div class="w-full bg-[rgb(var(--ec-card-bg))] h-[calc(100%-4rem)] rounded-2xl">
+      <iframe class="w-full h-full rounded-2xl border-none"></iframe>
+    </div>
+  </div>
+</VerticalSideBarLayout>
+
+<ClientRouter />
+<script>
+  function configureIcePanel() {
+    // Get url from query params and then embed into the iframe
+    const pageUrl = new URL(window.location.href);
+    const icePanelUrl = pageUrl.searchParams.get('url');
+    const title = pageUrl.searchParams.get('title') || 'IcePanel Diagram';
+    const backUrl = pageUrl.searchParams.get('back');
+
+    // Configure back button if back URL is provided
+    const backButton = document.querySelector('#backButton');
+    if (backButton && backUrl) {
+      backButton.classList.remove('hidden');
+      backButton.classList.add('flex');
+      backButton.addEventListener('click', () => {
+        window.location.href = `${decodeURIComponent(backUrl)}#${title}-icepanel-title`;
+      });
+    }
+
+    // Update the diagram title
+    const diagramTitleElement = document.querySelector('#diagramTitle');
+    if (diagramTitleElement) {
+      diagramTitleElement.textContent = title;
+    }
+
+    const iframe = document.querySelector('iframe');
+    if (iframe && icePanelUrl) {
+      iframe.src = icePanelUrl;
+      iframe.width = '100%';
+      iframe.height = '100%';
+    }
+  }
+
+  configureIcePanel();
+
+  document.addEventListener('astro:page-load', configureIcePanel);
+</script>
diff --git a/packages/core/eventcatalog/src/pages/index.astro b/packages/core/eventcatalog/src/pages/index.astro
new file mode 100644
index 000000000..b5c5d4623
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/index.astro
@@ -0,0 +1,112 @@
+---
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { getMDXComponentsByName } from '@utils/markdown';
+import { resourceToCollectionMap } from '@utils/collections/util';
+import { buildUrl } from '@utils/url-builder';
+import { isCustomLandingPageEnabled, isVisualiserEnabled } from '@utils/feature';
+import DefaultAstroLandingPage from './_index.astro';
+import config from '@config';
+
+let nodeGraphs: any[] = [];
+let systemContextMaps: any[] = [];
+let CustomContent = null;
+let NodeGraph = null;
+let customHomepageComponents: Record<string, any> = {};
+
+import path from 'path';
+import { existsSync, readFileSync } from 'fs';
+
+const props = Astro.props;
+
+const pathToUserDefinedLandingPage = path.join(process.env.PROJECT_DIR || '', 'pages/homepage.astro');
+
+if (existsSync(pathToUserDefinedLandingPage) && isCustomLandingPageEnabled()) {
+  const customPages = import.meta.glob('/src/custom-pages/homepage.astro', { eager: true });
+  // @ts-ignore
+  CustomContent = Object.values(customPages)[0]?.default || null;
+
+  const [{ default: pageComponents }, { default: mdxComponents }] = await Promise.all([
+    import('@components/MDX/page-components'),
+    import('@components/MDX/components'),
+  ]);
+  customHomepageComponents = { ...pageComponents, ...mdxComponents(props) };
+
+  const rawContent = readFileSync(pathToUserDefinedLandingPage, 'utf-8');
+  nodeGraphs = getMDXComponentsByName(rawContent, 'NodeGraph') || [];
+
+  // The homepage can also embed the global System Context Map via <SystemContextMap />.
+  systemContextMaps = getMDXComponentsByName(rawContent, 'SystemContextMap') || [];
+
+  // Avoid pulling visualizer CSS into the default homepage bundle.
+  // Only load the NodeGraph component when the custom homepage actually uses a graph.
+  if (nodeGraphs.length > 0 || systemContextMaps.length > 0) {
+    NodeGraph = (await import('@components/MDX/NodeGraph/NodeGraph.astro')).default;
+  }
+}
+
+if (config.landingPage) {
+  return Astro.redirect(buildUrl(config.landingPage));
+}
+---
+
+{
+  CustomContent ? (
+    <VerticalSideBarLayout title="EventCatalog" reducedContentPadding>
+      <main class="flex docs-layout h-full">
+        <div class="flex docs-layout w-full">
+          <div class="w-full overflow-y-auto py-8">
+            <div class="w-full max-w-none!">
+              <CustomContent components={customHomepageComponents} />
+            </div>
+          </div>
+        </div>
+        {NodeGraph &&
+          nodeGraphs.length > 0 &&
+          nodeGraphs.map((nodeGraph: any) => {
+            const collection = resourceToCollectionMap[nodeGraph.type as keyof typeof resourceToCollectionMap];
+            return (
+              <NodeGraph
+                id={nodeGraph.id}
+                version={nodeGraph.version}
+                collection={collection}
+                title={nodeGraph.title}
+                mode="simple"
+                linksToVisualiser={true}
+                href={
+                  isVisualiserEnabled()
+                    ? {
+                        label: 'Open in Visualiser',
+                        url: buildUrl(`/visualiser/${collection}/${nodeGraph.id}/${nodeGraph.version}`),
+                      }
+                    : undefined
+                }
+              />
+            );
+          })}
+        {NodeGraph &&
+          systemContextMaps.length > 0 &&
+          systemContextMaps.map(() => (
+            <NodeGraph
+              id="system-context-map"
+              version="1.0.0"
+              collection="system-context-map"
+              title="System context map"
+              mode="simple"
+              linksToVisualiser={true}
+              portalId="system-context-map-portal"
+              href={
+                isVisualiserEnabled()
+                  ? {
+                      label: 'Open in Visualiser',
+                      url: buildUrl('/visualiser/system-context-map'),
+                    }
+                  : undefined
+              }
+            />
+          ))}
+      </main>
+    </VerticalSideBarLayout>
+  ) : (
+    <DefaultAstroLandingPage />
+  )
+}
diff --git a/packages/core/eventcatalog/src/pages/llms-full.txt.ts b/packages/core/eventcatalog/src/pages/llms-full.txt.ts
new file mode 100644
index 000000000..8ad93b2a5
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/llms-full.txt.ts
@@ -0,0 +1 @@
+export { GET } from './docs/llm/llms-full.txt.ts';
diff --git a/packages/core/eventcatalog/src/pages/llms.txt.ts b/packages/core/eventcatalog/src/pages/llms.txt.ts
new file mode 100644
index 000000000..5f03fad8c
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/llms.txt.ts
@@ -0,0 +1 @@
+export { GET } from './docs/llm/llms.txt.ts';
diff --git a/eventcatalog/src/pages/miro/index.astro b/packages/core/eventcatalog/src/pages/miro/index.astro
similarity index 100%
rename from eventcatalog/src/pages/miro/index.astro
rename to packages/core/eventcatalog/src/pages/miro/index.astro
diff --git a/eventcatalog/src/pages/rss/[resource]/rss.xml.js b/packages/core/eventcatalog/src/pages/rss/[resource]/rss.xml.js
similarity index 100%
rename from eventcatalog/src/pages/rss/[resource]/rss.xml.js
rename to packages/core/eventcatalog/src/pages/rss/[resource]/rss.xml.js
diff --git a/packages/core/eventcatalog/src/pages/schemas/[type]/[id]/[version]/_index.data.ts b/packages/core/eventcatalog/src/pages/schemas/[type]/[id]/[version]/_index.data.ts
new file mode 100644
index 000000000..af391ac56
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/schemas/[type]/[id]/[version]/_index.data.ts
@@ -0,0 +1,118 @@
+import { getCollection } from 'astro:content';
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import type { PageTypes } from '@types';
+import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
+
+/**
+ * Documentation page class for all collection types with versioning
+ */
+export class Page extends HybridPage {
+  static async getStaticPaths() {
+    if (isSSR()) {
+      return [];
+    }
+
+    const itemTypes: PageTypes[] = [
+      'events',
+      'commands',
+      'queries',
+      // 'services',
+      // 'domains',
+      // 'flows',
+      // 'channels',
+      // 'entities',
+      // 'containers',
+    ];
+    const [schemas, ...allItems] = await Promise.all([
+      getCollection('schemas'),
+      ...itemTypes.map((type) => pageDataLoader[type]()),
+    ]);
+    const itemsByKey = new Map(allItems.flat().map((item) => [`${item.collection}:${item.data.id}:${item.data.version}`, item]));
+
+    const seenMessageSchemas = new Set<string>();
+    const messageSchemas = schemas.filter((schema) => {
+      const key = `${schema.data.message.collection}:${schema.data.message.id}:${schema.data.message.version}`;
+      if (seenMessageSchemas.has(key)) return false;
+      seenMessageSchemas.add(key);
+      return true;
+    });
+
+    // Generate paths for messages with schemas
+    const messagePaths = messageSchemas
+      .map((schema) => {
+        const item = itemsByKey.get(`${schema.data.message.collection}:${schema.data.message.id}:${schema.data.message.version}`);
+        if (!item) return null;
+
+        return {
+          params: {
+            type: schema.data.message.collection,
+            id: schema.data.message.id,
+            version: schema.data.message.version,
+          },
+          props: {
+            type: schema.data.message.collection,
+            ...item,
+            // Not everything needs the body of the page itself.
+            body: undefined,
+          },
+        };
+      })
+      .filter((path): path is NonNullable<typeof path> => path !== null);
+
+    // Generate paths for data products with contracts
+    const dataProducts = await pageDataLoader['data-products']();
+    const dataProductPaths = dataProducts.flatMap((dataProduct) => {
+      const outputs = (dataProduct.data as any).outputs || [];
+      const outputsWithContracts = outputs.filter((output: any) => output.contract);
+
+      return outputsWithContracts.map((output: any) => ({
+        params: {
+          type: 'data-products',
+          id: dataProduct.data.id,
+          version: dataProduct.data.version,
+        },
+        props: {
+          type: 'data-products',
+          ...dataProduct,
+          contractPath: output.contract.path,
+          contractName: output.contract.name,
+          contractType: output.contract.type,
+          body: undefined,
+        },
+      }));
+    });
+
+    return [...messagePaths, ...dataProductPaths];
+  }
+
+  protected static async fetchData(params: any) {
+    const { type, id, version } = params;
+
+    if (!type || !id || !version) {
+      return null;
+    }
+
+    // Get all items of the specified type
+    const items = await pageDataLoader[type as PageTypes]();
+
+    // Find the specific item by id and version
+    const item = items.find((i) => i.data.id === id && i.data.version === version);
+
+    if (!item) {
+      return null;
+    }
+
+    return {
+      type,
+      ...item,
+    };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Documentation not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/schemas/[type]/[id]/[version]/index.astro b/packages/core/eventcatalog/src/pages/schemas/[type]/[id]/[version]/index.astro
new file mode 100644
index 000000000..46f52a13b
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/schemas/[type]/[id]/[version]/index.astro
@@ -0,0 +1,151 @@
+---
+import type { PageTypes } from '@types';
+import { getCollection } from 'astro:content';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { Page } from './_index.data';
+import SchemaPageViewer from '@components/SchemaExplorer/SchemaPageViewer';
+import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
+import { sortVersioned } from '@utils/collections/util';
+import { isEventCatalogScaleEnabled } from '@utils/feature';
+import { resourceFileExists, readResourceFile } from '@utils/resource-files';
+import path from 'node:path';
+import type { SchemaItem } from '@components/SchemaExplorer/types';
+import { getExamplesForResource } from '@utils/collections/examples';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+const { type, data } = props as { type: PageTypes; data: any };
+
+// Check if this is a data product with a contract
+const isDataProduct = type === 'data-products';
+// Try query param first (SSR mode), then fall back to props (static mode)
+const contractPath = Astro.url.searchParams.get('contract') || (props as any).contractPath;
+
+let currentMessage: SchemaItem | null = null;
+let sortedVersions: SchemaItem[] = [];
+let pageTitle = `${type} | ${data.name}`.replace(/^\w/, (c) => c.toUpperCase());
+
+if (isDataProduct && contractPath) {
+  // Handle data product contracts
+  const allDataProducts = await pageDataLoader['data-products']();
+  const dataProductVersions = allDataProducts.filter((item) => item.data.id === data.id);
+
+  // Find contracts across all versions
+  const contractVersions = dataProductVersions
+    .map((dataProduct) => {
+      const outputs = (dataProduct.data as any).outputs || [];
+      const matchingOutput = outputs.find((output: any) => output.contract?.path === contractPath);
+
+      if (!matchingOutput) return null;
+
+      if (!resourceFileExists(dataProduct, contractPath)) return null;
+
+      try {
+        const schemaContent = readResourceFile(dataProduct, contractPath) ?? '';
+        const schemaExtension = path.extname(contractPath).slice(1);
+
+        return {
+          collection: 'data-products',
+          data: {
+            id: dataProduct.data.id,
+            name: matchingOutput.contract.name,
+            version: dataProduct.data.version,
+            summary: `Data contract for ${dataProduct.data.name}`,
+            schemaPath: contractPath,
+          },
+          schemaContent,
+          schemaExtension,
+          contractType: matchingOutput.contract.type,
+          dataProductId: dataProduct.data.id,
+          dataProductVersion: dataProduct.data.version,
+        } as SchemaItem;
+      } catch (error) {
+        console.error(`Error reading contract for ${dataProduct.data.id}:`, error);
+        return null;
+      }
+    })
+    .filter((v): v is SchemaItem => v !== null);
+
+  sortedVersions = sortVersioned(contractVersions, (item) => item.data.version);
+  currentMessage = sortedVersions.find((v) => v.data.version === data.version) ?? null;
+
+  if (currentMessage) {
+    pageTitle = `Data Contract | ${currentMessage.data.name}`;
+  }
+} else {
+  // Handle regular messages (events, commands, queries)
+  const [allItems, schemaEntries] = await Promise.all([pageDataLoader[type](), getCollection('schemas')]);
+  const versions = allItems.filter((item) => item.data.id === data.id);
+  const schemasForMessage = schemaEntries.filter(
+    (schema) => schema.data.message.collection === type && schema.data.message.id === data.id
+  );
+
+  const getSchemaForVersion = (version: string) => {
+    const schemasForVersion = schemasForMessage.filter((schema) => schema.data.message.version === version);
+    return schemasForVersion.find((schema) => schema.data.default) ?? schemasForVersion[0];
+  };
+
+  // Transform to SchemaItems
+  const availableVersions = versions
+    .map((message) => {
+      try {
+        const schema = getSchemaForVersion(message.data.version);
+        if (!schema) return null;
+
+        const schemaPath = schema.data.file || schema.data.source.path || '';
+        const schemaExtension = path.extname(schemaPath).slice(1);
+
+        return {
+          collection: message.collection,
+          data: {
+            id: message.data.id,
+            name: schema.data.message.name || message.data.name,
+            version: message.data.version,
+            summary: schema.data.message.summary || message.data.summary,
+            schemaPath,
+            // @ts-ignore
+            producers: message.data.producers || [],
+            // @ts-ignore
+            consumers: message.data.consumers || [],
+          },
+          schemaContent: schema.data.content || '',
+          schemaExtension,
+          examples: getExamplesForResource(message),
+        } as SchemaItem;
+      } catch (error) {
+        console.error(`Error reading schema for ${message.data.id}:`, error);
+        return null;
+      }
+    })
+    .filter((v): v is SchemaItem => v !== null);
+
+  sortedVersions = sortVersioned(availableVersions, (item) => item.data.version);
+  currentMessage = sortedVersions.find((v) => v.data.version === data.version) ?? null;
+}
+
+const apiAccessEnabled = isEventCatalogScaleEnabled();
+---
+
+<VerticalSideBarLayout title={pageTitle}>
+  <div class="h-[calc(100vh-4rem)] w-full overflow-hidden flex flex-col">
+    {
+      currentMessage ? (
+        <SchemaPageViewer
+          client:load
+          message={currentMessage}
+          availableVersions={sortedVersions}
+          apiAccessEnabled={apiAccessEnabled}
+          showOwners={false}
+          showProducersConsumers={false}
+        />
+      ) : (
+        <div class="p-8 flex items-center justify-center h-full text-[rgb(var(--ec-page-text-muted))]">
+          Schema not found or could not be loaded.
+        </div>
+      )
+    }
+  </div>
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/pages/schemas/explorer/_index.data.ts b/packages/core/eventcatalog/src/pages/schemas/explorer/_index.data.ts
new file mode 100644
index 000000000..a1ff1f5da
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/schemas/explorer/_index.data.ts
@@ -0,0 +1,310 @@
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import { getEvents } from '@utils/collections/events';
+import { getCommands } from '@utils/collections/commands';
+import { getQueries } from '@utils/collections/queries';
+import { getServices, getSpecificationsForService } from '@utils/collections/services';
+import { getDomains, getSpecificationsForDomain } from '@utils/collections/domains';
+import { getDataProducts } from '@utils/collections/data-products';
+import { getOwner } from '@utils/collections/owners';
+import { buildUrl } from '@utils/url-builder';
+import { resourceFileExists, readResourceFile } from '@utils/resource-files';
+import { getExamplesForResource } from '@utils/collections/examples';
+import { getCollection } from 'astro:content';
+import path from 'path';
+
+// Helper function to enrich owners with full details
+async function enrichOwners(ownersRaw: any[]) {
+  if (!ownersRaw || ownersRaw.length === 0) return [];
+
+  const owners = await Promise.all(ownersRaw.map(getOwner));
+  const filteredOwners = owners.filter((o) => o !== undefined);
+
+  return filteredOwners.map((o) => ({
+    id: o.data.id,
+    name: o.data.name,
+    type: o.collection,
+    href: buildUrl(`/docs/${o.collection}/${o.data.id}`),
+  }));
+}
+
+async function fetchAllSchemas() {
+  // Fetch all messages
+  const events = await getEvents({ getAllVersions: true });
+  const commands = await getCommands({ getAllVersions: true });
+  const queries = await getQueries({ getAllVersions: true });
+  const schemaEntries = await getCollection('schemas');
+
+  // Fetch all services
+  const services = await getServices({ getAllVersions: true });
+
+  // Combine all messages
+  const allMessages = [...events, ...commands, ...queries];
+  const messagesBySchemaReference = new Map(
+    allMessages.map((message) => [`${message.collection}:${message.data.id}:${message.data.version}`, message])
+  );
+
+  // Read message schemas from the generated schemas collection.
+  const messagesWithSchemas = await Promise.all(
+    schemaEntries.map(async (schema) => {
+      const message = messagesBySchemaReference.get(
+        `${schema.data.message.collection}:${schema.data.message.id}:${schema.data.message.version}`
+      );
+      const schemaPath = schema.data.file || schema.data.source.path || '';
+      const schemaExtension = path.extname(schemaPath).slice(1) || schema.data.format;
+
+      if (message) {
+        try {
+          const enrichedOwners = await enrichOwners(schema.data.message.owners || []);
+
+          return {
+            collection: message.collection,
+            data: {
+              id: message.data.id,
+              name: schema.data.message.name || message.data.name,
+              version: message.data.version,
+              summary: schema.data.message.summary || message.data.summary,
+              schemaPath,
+              producers: message.data.producers || [],
+              consumers: message.data.consumers || [],
+              owners: enrichedOwners,
+            },
+            schemaContent: schema.data.content || '',
+            schemaExtension,
+            examples: getExamplesForResource(message),
+          };
+        } catch (error) {
+          console.error(`Error reading schema metadata for ${message.data.id}:`, error);
+          const enrichedOwners = await enrichOwners(schema.data.message.owners || []);
+          return {
+            collection: message.collection,
+            data: {
+              id: message.data.id,
+              name: schema.data.message.name || schema.data.name || message.data.name,
+              version: message.data.version,
+              summary: schema.data.message.summary || message.data.summary,
+              schemaPath,
+              producers: message.data.producers || [],
+              consumers: message.data.consumers || [],
+              owners: enrichedOwners,
+            },
+            schemaContent: schema.data.content || '',
+            schemaExtension,
+          };
+        }
+      }
+
+      return {
+        collection: schema.data.message.collection,
+        data: {
+          id: schema.data.message.id,
+          name: schema.data.message.name || schema.data.name || schema.data.message.id,
+          version: schema.data.message.version,
+          summary: schema.data.message.summary,
+          schemaPath,
+          owners: await enrichOwners(schema.data.message.owners || []),
+          producers: [],
+          consumers: [],
+        },
+        schemaContent: schema.data.content || '',
+        schemaExtension,
+        examples: [],
+      };
+    })
+  );
+
+  // Filter services with specifications and read spec content - only keep essential data
+  const servicesWithSpecs = await Promise.all(
+    services.map(async (service) => {
+      try {
+        const specifications = getSpecificationsForService(service);
+
+        if (specifications.length === 0) {
+          return null;
+        }
+
+        return await Promise.all(
+          specifications.map(async (spec) => {
+            if (!resourceFileExists(service, spec.path)) {
+              return null;
+            }
+
+            const schemaContent = readResourceFile(service, spec.path) ?? '';
+            const schemaExtension = spec.type;
+            const enrichedOwners = await enrichOwners(service.data.owners || []);
+
+            return {
+              collection: 'services',
+              data: {
+                id: `${service.data.id}`,
+                name: `${service.data.name} - ${spec.name}`,
+                version: service.data.version,
+                summary: service.data.summary,
+                schemaPath: spec.path,
+                owners: enrichedOwners,
+              },
+              schemaContent,
+              schemaExtension,
+              specType: spec.type,
+              specName: spec.name,
+              specFilenameWithoutExtension: spec.filenameWithoutExtension,
+            };
+          })
+        );
+      } catch (error) {
+        console.error(`Error reading specifications for service ${service.data.id}:`, error);
+        return null;
+      }
+    })
+  );
+
+  // Flatten and filter out null values
+  const flatServicesWithSpecs = servicesWithSpecs.flat().filter((service) => service !== null);
+
+  // Fetch all domains
+  const domains = await getDomains({ getAllVersions: true });
+
+  // Filter domains with specifications and read spec content - only keep essential data
+  const domainsWithSpecs = await Promise.all(
+    domains.map(async (domain) => {
+      try {
+        const specifications = getSpecificationsForDomain(domain);
+
+        if (specifications.length === 0) {
+          return null;
+        }
+
+        return await Promise.all(
+          specifications.map(async (spec) => {
+            if (!resourceFileExists(domain, spec.path)) {
+              return null;
+            }
+
+            const schemaContent = readResourceFile(domain, spec.path) ?? '';
+            const schemaExtension = spec.type;
+            const enrichedOwners = await enrichOwners(domain.data.owners || []);
+
+            return {
+              collection: 'domains',
+              data: {
+                id: `${domain.data.id}`,
+                name: `${domain.data.name} - ${spec.name}`,
+                version: domain.data.version,
+                summary: domain.data.summary,
+                schemaPath: spec.path,
+                owners: enrichedOwners,
+              },
+              schemaContent,
+              schemaExtension,
+              specType: spec.type,
+              specName: spec.name,
+              specFilenameWithoutExtension: spec.filenameWithoutExtension,
+            };
+          })
+        );
+      } catch (error) {
+        console.error(`Error reading specifications for domain ${domain.data.id}:`, error);
+        return null;
+      }
+    })
+  );
+
+  // Flatten and filter out null values for domains
+  const flatDomainsWithSpecs = domainsWithSpecs.flat().filter((domain) => domain !== null);
+
+  // Fetch all data products and extract contracts from outputs
+  const dataProducts = await getDataProducts({ getAllVersions: true });
+
+  // Filter data products with contracts in outputs and read contract content
+  const dataProductsWithContracts = await Promise.all(
+    dataProducts.map(async (dataProduct) => {
+      try {
+        const outputs = dataProduct.data.outputs || [];
+        const outputsWithContracts = outputs.filter((output) => output.contract);
+
+        if (outputsWithContracts.length === 0) {
+          return null;
+        }
+
+        return await Promise.all(
+          outputsWithContracts.map(async (output) => {
+            const contract = output.contract!;
+            if (!resourceFileExists(dataProduct, contract.path)) {
+              return null;
+            }
+
+            const schemaContent = readResourceFile(dataProduct, contract.path) ?? '';
+            const schemaExtension = path.extname(contract.path).slice(1) || 'json';
+            const enrichedOwners = await enrichOwners(dataProduct.data.owners || []);
+
+            return {
+              collection: 'data-products',
+              data: {
+                id: `${dataProduct.data.id}__${contract.path}`,
+                name: contract.name,
+                version: dataProduct.data.version,
+                summary: `Data contract for ${dataProduct.data.name}`,
+                schemaPath: contract.path,
+                owners: enrichedOwners,
+              },
+              schemaContent,
+              schemaExtension,
+              contractType: contract.type,
+              dataProductId: dataProduct.data.id,
+              dataProductVersion: dataProduct.data.version,
+            };
+          })
+        );
+      } catch (error) {
+        console.error(`Error reading contracts for data product ${dataProduct.data.id}:`, error);
+        return null;
+      }
+    })
+  );
+
+  // Flatten and filter out null values for data product contracts
+  const flatDataProductContracts = dataProductsWithContracts.flat().filter((contract) => contract !== null);
+
+  return [...messagesWithSchemas, ...flatServicesWithSpecs, ...flatDomainsWithSpecs, ...flatDataProductContracts];
+}
+
+export class Page extends HybridPage {
+  static get prerender(): boolean {
+    return !isSSR();
+  }
+
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isSSR()) {
+      return [];
+    }
+
+    const allSchemas = await fetchAllSchemas();
+
+    return [
+      {
+        params: {},
+        props: {
+          schemas: allSchemas,
+        },
+      },
+    ];
+  }
+
+  protected static async fetchData(_params: any) {
+    const allSchemas = await fetchAllSchemas();
+    return {
+      schemas: allSchemas,
+    };
+  }
+
+  protected static hasValidProps(props: any): boolean {
+    return props && props.schemas !== undefined;
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Schema explorer not found',
+    });
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/schemas/explorer/index.astro b/packages/core/eventcatalog/src/pages/schemas/explorer/index.astro
new file mode 100644
index 000000000..1cc39abcf
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/schemas/explorer/index.astro
@@ -0,0 +1,27 @@
+---
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import SchemaExplorer from '@components/SchemaExplorer/SchemaExplorer';
+import { isEventCatalogScaleEnabled } from '@utils/feature';
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+const { schemas } = await Page.getData(Astro);
+
+const apiAccessEnabled = isEventCatalogScaleEnabled();
+---
+
+<VerticalSideBarLayout title="Schema Explorer - EventCatalog" showNestedSideBar={false}>
+  <style is:global>
+    #eventcatalog-header {
+      left: calc(var(--ec-vertical-nav-width, 14rem) + var(--ec-schema-sidebar-width, 360px)) !important;
+    }
+  </style>
+  <main
+    class="min-h-0 overflow-hidden bg-[rgb(var(--ec-page-bg))]"
+    style={`--ec-schema-sidebar-width: 360px; margin-left: calc(var(--ec-app-content-padding-left, 5rem) * -1); margin-right: calc(var(--ec-app-content-padding-right, 5rem) * -1); height: calc(100dvh - 60px);`}
+  >
+    <SchemaExplorer client:load schemas={schemas as any} apiAccessEnabled={apiAccessEnabled} />
+  </main>
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/pages/settings/assistant.astro b/packages/core/eventcatalog/src/pages/settings/assistant.astro
new file mode 100644
index 000000000..db117a053
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/settings/assistant.astro
@@ -0,0 +1,37 @@
+---
+import fs from 'node:fs';
+import path from 'node:path';
+import SettingsLayout from '@layouts/SettingsLayout.astro';
+import { AssistantSettingsForm } from '@components/Settings/AssistantSettingsForm';
+import { isDevMode, isSSR, isEventCatalogStarterEnabled, isEventCatalogScaleEnabled } from '@utils/feature';
+import { buildUrl } from '@utils/url-builder';
+import config from '@config';
+
+const canEdit = isDevMode();
+
+const initial = {
+  llmsTxtEnabled: config?.llmsTxt?.enabled ?? true,
+  chatEnabled: config?.chat?.enabled ?? true,
+};
+
+const projectRoot = process.env.PROJECT_DIR ?? process.cwd();
+const hasChatConfigFile = fs.existsSync(path.join(projectRoot, 'eventcatalog.chat.js'));
+const hasPlan = isEventCatalogStarterEnabled() || isEventCatalogScaleEnabled();
+const inSSR = isSSR();
+const chatAvailable = hasPlan && hasChatConfigFile && inSSR;
+
+const apiBase = buildUrl('/api/settings');
+---
+
+<SettingsLayout title="Assistant Agent" active="assistant">
+  <AssistantSettingsForm
+    client:load
+    canEdit={canEdit}
+    initial={initial}
+    chatAvailable={chatAvailable}
+    hasPlan={hasPlan}
+    inSSR={inSSR}
+    hasChatConfigFile={hasChatConfigFile}
+    apiBase={apiBase}
+  />
+</SettingsLayout>
diff --git a/packages/core/eventcatalog/src/pages/settings/billing.astro b/packages/core/eventcatalog/src/pages/settings/billing.astro
new file mode 100644
index 000000000..70598a5c4
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/settings/billing.astro
@@ -0,0 +1,17 @@
+---
+import SettingsLayout from '@layouts/SettingsLayout.astro';
+import { BillingSettingsForm, type PlanId } from '@components/Settings/BillingSettingsForm';
+import { isEventCatalogStarterEnabled, isEventCatalogScaleEnabled } from '@utils/feature';
+
+// Detect which plan is active. Enterprise has no env flag of its own — it includes
+// Scale features, so an explicit Enterprise toggle would need a separate flag.
+// For now, treat anything Scale-licensed as Scale; Enterprise users will still see
+// upgrade copy on the Scale card but the Plans grid is the canonical source.
+let currentPlan: PlanId = 'community';
+if (isEventCatalogScaleEnabled()) currentPlan = 'scale';
+else if (isEventCatalogStarterEnabled()) currentPlan = 'starter';
+---
+
+<SettingsLayout title="Billing" active="billing">
+  <BillingSettingsForm client:load currentPlan={currentPlan} />
+</SettingsLayout>
diff --git a/packages/core/eventcatalog/src/pages/settings/general.astro b/packages/core/eventcatalog/src/pages/settings/general.astro
new file mode 100644
index 000000000..050f14fd0
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/settings/general.astro
@@ -0,0 +1,32 @@
+---
+import SettingsLayout from '@layouts/SettingsLayout.astro';
+import { GeneralSettingsForm } from '@components/Settings/GeneralSettingsForm';
+import { isDevMode } from '@utils/feature';
+import { buildUrl } from '@utils/url-builder';
+import config from '@config';
+
+const canEdit = isDevMode();
+
+const initial = {
+  title: config?.title ?? '',
+  tagline: config?.tagline,
+  organizationName: config?.organizationName,
+  homepageLink: config?.homepageLink,
+  editUrl: config?.editUrl,
+  repositoryUrl: config?.repositoryUrl,
+  logo: config?.logo
+    ? {
+        alt: config.logo.alt,
+        text: config.logo.text,
+        src: config.logo.src,
+      }
+    : undefined,
+  theme: config?.theme || 'default',
+};
+
+const apiBase = buildUrl('/api/settings');
+---
+
+<SettingsLayout title="General" active="general">
+  <GeneralSettingsForm client:load canEdit={canEdit} initial={initial} apiBase={apiBase} />
+</SettingsLayout>
diff --git a/packages/core/eventcatalog/src/pages/settings/index.astro b/packages/core/eventcatalog/src/pages/settings/index.astro
new file mode 100644
index 000000000..2c8a64e9a
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/settings/index.astro
@@ -0,0 +1,21 @@
+---
+import { buildUrl } from '@utils/url-builder';
+
+const target = buildUrl('/settings/general');
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="refresh" content={`0; url=${target}`} />
+    <link rel="canonical" href={target} />
+    <title>Redirecting…</title>
+  </head>
+  <body>
+    <p>Redirecting to <a href={target}>{target}</a>…</p>
+    <script is:inline define:vars={{ target }}>
+      window.location.replace(target);
+    </script>
+  </body>
+</html>
diff --git a/packages/core/eventcatalog/src/pages/settings/llm-access.astro b/packages/core/eventcatalog/src/pages/settings/llm-access.astro
new file mode 100644
index 000000000..90f7683ed
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/settings/llm-access.astro
@@ -0,0 +1,34 @@
+---
+import SettingsLayout from '@layouts/SettingsLayout.astro';
+import { LlmAccessSettingsForm } from '@components/Settings/LlmAccessSettingsForm';
+import { isDevMode, isEventCatalogScaleEnabled } from '@utils/feature';
+import { buildUrl } from '@utils/url-builder';
+import config from '@config';
+
+const canEdit = isDevMode();
+
+const initial = {
+  llmsTxtEnabled: config?.llmsTxt?.enabled ?? true,
+  chatEnabled: config?.chat?.enabled ?? true,
+};
+
+const hasScalePlan = isEventCatalogScaleEnabled();
+
+const apiBase = buildUrl('/api/settings');
+const llmsTxtUrl = buildUrl('/llms.txt');
+const llmsFullTxtUrl = buildUrl('/llms-full.txt');
+const schemasTxtUrl = buildUrl('/docs/llm/schemas.txt');
+---
+
+<SettingsLayout title="LLM Access" active="llm-access">
+  <LlmAccessSettingsForm
+    client:load
+    canEdit={canEdit}
+    initial={initial}
+    hasScalePlan={hasScalePlan}
+    apiBase={apiBase}
+    llmsTxtUrl={llmsTxtUrl}
+    llmsFullTxtUrl={llmsFullTxtUrl}
+    schemasTxtUrl={schemasTxtUrl}
+  />
+</SettingsLayout>
diff --git a/packages/core/eventcatalog/src/pages/settings/mcp.astro b/packages/core/eventcatalog/src/pages/settings/mcp.astro
new file mode 100644
index 000000000..5d2ac06ff
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/settings/mcp.astro
@@ -0,0 +1,14 @@
+---
+import SettingsLayout from '@layouts/SettingsLayout.astro';
+import { McpSettingsForm } from '@components/Settings/McpSettingsForm';
+import { isSSR, isEventCatalogScaleEnabled } from '@utils/feature';
+import { buildUrl } from '@utils/url-builder';
+
+const hasScalePlan = isEventCatalogScaleEnabled();
+const inSSR = isSSR();
+const mcpUrl = buildUrl('/docs/mcp');
+---
+
+<SettingsLayout title="MCP" active="mcp">
+  <McpSettingsForm client:load hasScalePlan={hasScalePlan} inSSR={inSSR} mcpUrl={mcpUrl} />
+</SettingsLayout>
diff --git a/packages/core/eventcatalog/src/pages/studio.astro b/packages/core/eventcatalog/src/pages/studio.astro
new file mode 100644
index 000000000..b105cc212
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/studio.astro
@@ -0,0 +1,316 @@
+---
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { getEvents } from '@utils/collections/events';
+import { getCommands } from '@utils/collections/commands';
+import { getServices } from '@utils/collections/services';
+import { BoltIcon, ServerIcon } from '@heroicons/react/24/outline';
+import { SquareDashedMousePointerIcon, ArrowLeftRightIcon, ExternalLink } from 'lucide-react';
+import StudioPageModal from '@components/Studio/StudioPageModal';
+import { getChannels } from '@utils/collections/channels';
+
+const [events, commands, services, channels] = await Promise.all([
+  getEvents().catch(() => []),
+  getCommands().catch(() => []),
+  getServices().catch(() => []),
+  getChannels().catch(() => []),
+]);
+
+// Get counts
+const eventCount = events.length;
+const serviceCount = services.length;
+const commandCount = commands.length;
+const channelCount = channels.length;
+const totalResources = eventCount + serviceCount + channelCount + commandCount;
+
+// Get a few sample resources to display
+const sampleEvents = events.slice(0, 2);
+const sampleServices = services.slice(0, 2);
+const sampleChannels = channels.slice(0, 1);
+
+// Determine which resources to show (fallback if some are missing)
+const resourcesToShow = [
+  ...sampleEvents.map((event, index) => ({ type: 'event', data: event, index })),
+  ...sampleServices.map((service, index) => ({ type: 'service', data: service, index: index + 2 })),
+  ...sampleChannels.map((channel, index) => ({ type: 'channel', data: channel, index: index + 4 })),
+].slice(0, 5); // Max 5 resources
+
+const hasResources = resourcesToShow.length > 0;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width" />
+    <link rel="icon" href="/favicon.ico" sizes="any" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+    <meta name="generator" content={Astro.generator} />
+    <title>EventCatalog Studio</title>
+  </head>
+  <body>
+    <VerticalSideBarLayout title="EventCatalog Studio" showNestedSideBar={false}>
+      <div class="min-h-[calc(100vh-60px)] bg-[rgb(var(--ec-page-bg))]">
+        <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-16">
+          {/* Hero Section */}
+          <div class="grid grid-cols-1 lg:grid-cols-2 gap-12 items-center mb-16">
+            <div>
+              <div
+                class="inline-flex items-center px-3 py-1.5 rounded-full bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-page-text))] font-medium text-xs mb-6"
+              >
+                Visual Design Tool
+              </div>
+              <h1 class="text-4xl font-bold text-[rgb(var(--ec-page-text))] tracking-tight mb-4">
+                Turn your resources into designs
+              </h1>
+              <p class="text-lg text-[rgb(var(--ec-page-text-muted))] mb-8">
+                Transform your documented messages, services, and domains into architecture diagrams. Drag, drop, and design with
+                what you already have.
+              </p>
+              <div class="flex flex-col sm:flex-row gap-3 mb-4">
+                <button
+                  id="design-button"
+                  class="inline-flex items-center justify-center px-6 py-3 border border-transparent text-base font-medium rounded-lg text-[rgb(var(--ec-button-text))] bg-[rgb(var(--ec-button-bg))] hover:bg-[rgb(var(--ec-button-bg-hover))] transition-colors duration-150"
+                >
+                  <SquareDashedMousePointerIcon className="w-4 h-4 mr-2" />
+                  Open Studio
+                </button>
+                <a
+                  href="https://www.eventcatalog.dev/docs/development/components/designs"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  class="inline-flex items-center justify-center px-6 py-3 border border-[rgb(var(--ec-page-border))] text-base font-medium rounded-lg text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] hover:bg-[rgb(var(--ec-content-hover))] transition-colors duration-150"
+                >
+                  Learn more
+                  <ExternalLink className="w-4 h-4 ml-2" />
+                </a>
+              </div>
+
+              {
+                totalResources > 0 && (
+                  <p class="text-sm text-[rgb(var(--ec-page-text-muted))]">
+                    <span class="font-medium text-[rgb(var(--ec-page-text))]">{totalResources}</span> resources available to
+                    design with
+                  </p>
+                )
+              }
+            </div>
+
+            <div class="relative hidden lg:block">
+              {/* Animation container */}
+              <div class="relative h-[350px] flex items-center justify-center">
+                {/* Resource cards that animate in */}
+                {
+                  hasResources ? (
+                    <div class="absolute left-0 top-1/2 -translate-y-1/2 space-y-2.5">
+                      {resourcesToShow.map((resource) => {
+                        if (resource.type === 'event') {
+                          return (
+                            <div
+                              class="animate-float-in flex items-center gap-2 text-sm text-[rgb(var(--ec-page-text))] px-4 py-2.5 bg-orange-50 dark:bg-orange-500/10 rounded-lg border border-orange-200 dark:border-orange-500/30 shadow-xs"
+                              style={`animation-delay: ${resource.index * 0.3}s;`}
+                            >
+                              <BoltIcon className="w-4 h-4 text-orange-500" />
+                              <span class="truncate max-w-[140px]">{resource.data.data.name}</span>
+                            </div>
+                          );
+                        } else if (resource.type === 'service') {
+                          return (
+                            <div
+                              class="animate-float-in flex items-center gap-2 text-sm text-[rgb(var(--ec-page-text))] px-4 py-2.5 bg-pink-50 dark:bg-pink-500/10 rounded-lg border border-pink-200 dark:border-pink-500/30 shadow-xs"
+                              style={`animation-delay: ${resource.index * 0.3}s;`}
+                            >
+                              <ServerIcon className="w-4 h-4 text-pink-500" />
+                              <span class="truncate max-w-[140px]">{resource.data.data.name}</span>
+                            </div>
+                          );
+                        } else if (resource.type === 'channel') {
+                          return (
+                            <div
+                              class="animate-float-in flex items-center gap-2 text-sm text-[rgb(var(--ec-page-text))] px-4 py-2.5 bg-indigo-50 dark:bg-indigo-500/10 rounded-lg border border-indigo-200 dark:border-indigo-500/30 shadow-xs"
+                              style={`animation-delay: ${resource.index * 0.3}s;`}
+                            >
+                              <ArrowLeftRightIcon className="w-4 h-4 text-indigo-500" />
+                              <span class="truncate max-w-[140px]">{resource.data.data.name}</span>
+                            </div>
+                          );
+                        }
+                      })}
+                    </div>
+                  ) : (
+                    <div class="absolute left-0 top-1/2 -translate-y-1/2 space-y-2.5">
+                      <div
+                        class="animate-float-in flex items-center gap-2 text-sm text-[rgb(var(--ec-icon-color))] px-4 py-2.5 bg-[rgb(var(--ec-content-hover))] rounded-lg border border-[rgb(var(--ec-page-border))] border-dashed"
+                        style="animation-delay: 0s;"
+                      >
+                        <BoltIcon className="w-4 h-4" />
+                        <span>Your events</span>
+                      </div>
+                      <div
+                        class="animate-float-in flex items-center gap-2 text-sm text-[rgb(var(--ec-icon-color))] px-4 py-2.5 bg-[rgb(var(--ec-content-hover))] rounded-lg border border-[rgb(var(--ec-page-border))] border-dashed"
+                        style="animation-delay: 0.3s;"
+                      >
+                        <ServerIcon className="w-4 h-4" />
+                        <span>Your services</span>
+                      </div>
+                      <div
+                        class="animate-float-in flex items-center gap-2 text-sm text-[rgb(var(--ec-icon-color))] px-4 py-2.5 bg-[rgb(var(--ec-content-hover))] rounded-lg border border-[rgb(var(--ec-page-border))] border-dashed"
+                        style="animation-delay: 0.6s;"
+                      >
+                        <ArrowLeftRightIcon className="w-4 h-4" />
+                        <span>Your channels</span>
+                      </div>
+                    </div>
+                  )
+                }
+
+                {/* Arrow indicator */}
+                <div class="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2">
+                  <svg
+                    class="w-10 h-10 text-[rgb(var(--ec-icon-color))] animate-pulse"
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="currentColor"
+                  >
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 7l5 5m0 0l-5 5m5-5H6"></path>
+                  </svg>
+                </div>
+
+                {/* Design preview */}
+                <div class="absolute right-0 top-1/2 -translate-y-1/2 animate-fade-in-scale" style="animation-delay: 1.5s;">
+                  <img
+                    src="/studio-bg.png"
+                    alt="Studio Design Preview"
+                    class="rounded-xl shadow-lg border border-[rgb(var(--ec-page-border))] w-56 h-auto"
+                  />
+                </div>
+              </div>
+            </div>
+          </div>
+
+          {/* Features Section */}
+          <div class="grid grid-cols-1 md:grid-cols-3 gap-6">
+            <div
+              class="group bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] rounded-xl p-6 border border-[rgb(var(--ec-page-border))] hover:border-[rgb(var(--ec-accent))] hover:shadow-md transition-all duration-200"
+            >
+              <div
+                class="w-10 h-10 bg-[rgb(var(--ec-content-hover))] rounded-lg flex items-center justify-center mb-4 group-hover:bg-[rgb(var(--ec-accent-subtle))] transition-colors"
+              >
+                <svg
+                  class="w-5 h-5 text-[rgb(var(--ec-page-text))]"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="2"
+                >
+                  <rect width="8" height="8" x="3" y="3" rx="2"></rect>
+                  <path d="M7 11v4a2 2 0 0 0 2 2h4"></path>
+                  <rect width="8" height="8" x="13" y="13" rx="2"></rect>
+                </svg>
+              </div>
+              <h3 class="text-base font-semibold text-[rgb(var(--ec-page-text))] mb-2">Real Resources</h3>
+              <p class="text-sm text-[rgb(var(--ec-page-text-muted))] leading-relaxed">
+                Drag and drop messages, services, and domains from your catalog. No more copying names or keeping things in sync.
+              </p>
+            </div>
+
+            <div
+              class="group bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] rounded-xl p-6 border border-[rgb(var(--ec-page-border))] hover:border-[rgb(var(--ec-accent))] hover:shadow-md transition-all duration-200"
+            >
+              <div
+                class="w-10 h-10 bg-[rgb(var(--ec-content-hover))] rounded-lg flex items-center justify-center mb-4 group-hover:bg-[rgb(var(--ec-accent-subtle))] transition-colors"
+              >
+                <svg
+                  class="w-5 h-5 text-[rgb(var(--ec-page-text))]"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="2"
+                >
+                  <path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z"></path>
+                  <polyline points="17 21 17 13 7 13 7 21"></polyline>
+                  <polyline points="7 3 7 8 15 8"></polyline>
+                </svg>
+              </div>
+              <h3 class="text-base font-semibold text-[rgb(var(--ec-page-text))] mb-2">Save & Version</h3>
+              <p class="text-sm text-[rgb(var(--ec-page-text-muted))] leading-relaxed">
+                Save designs locally and store in Git. All designs and data is owned by you.
+              </p>
+            </div>
+
+            <div
+              class="group bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] rounded-xl p-6 border border-[rgb(var(--ec-page-border))] hover:border-[rgb(var(--ec-accent))] hover:shadow-md transition-all duration-200"
+            >
+              <div
+                class="w-10 h-10 bg-[rgb(var(--ec-content-hover))] rounded-lg flex items-center justify-center mb-4 group-hover:bg-[rgb(var(--ec-accent-subtle))] transition-colors"
+              >
+                <svg
+                  class="w-5 h-5 text-[rgb(var(--ec-page-text))]"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="2"
+                >
+                  <polyline points="16 18 22 12 16 6"></polyline>
+                  <polyline points="8 6 2 12 8 18"></polyline>
+                </svg>
+              </div>
+              <h3 class="text-base font-semibold text-[rgb(var(--ec-page-text))] mb-2">Embed Anywhere</h3>
+              <p class="text-sm text-[rgb(var(--ec-page-text-muted))] leading-relaxed">
+                Drop diagrams directly into documentation pages. One source of truth for your architecture.
+              </p>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* Studio Modal */}
+      <StudioPageModal client:only="react" />
+    </VerticalSideBarLayout>
+
+    <script>
+      // Handle opening the studio modal
+      const button = document.getElementById('design-button');
+      if (button) {
+        button.addEventListener('click', () => {
+          // Trigger the modal to open
+          window.dispatchEvent(new CustomEvent('openStudioModal'));
+        });
+      }
+    </script>
+
+    <style>
+      @keyframes float-in {
+        0% {
+          opacity: 0;
+          transform: translateX(-20px);
+        }
+        100% {
+          opacity: 1;
+          transform: translateX(0);
+        }
+      }
+
+      @keyframes fade-in-scale {
+        0% {
+          opacity: 0;
+          transform: translateY(-50%) scale(0.95);
+        }
+        100% {
+          opacity: 1;
+          transform: translateY(-50%) scale(1);
+        }
+      }
+
+      .animate-float-in {
+        animation: float-in 0.5s ease-out forwards;
+        opacity: 0;
+      }
+
+      .animate-fade-in-scale {
+        animation: fade-in-scale 0.6s ease-out forwards;
+        opacity: 0;
+      }
+    </style>
+  </body>
+</html>
diff --git a/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version].mermaid.ts b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version].mermaid.ts
new file mode 100644
index 000000000..4fcc3029a
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version].mermaid.ts
@@ -0,0 +1,131 @@
+/**
+ * API endpoint to return mermaid diagram code for a visualiser page
+ * URL: /visualiser/{type}/{id}/{version}.mermaid
+ *
+ * Returns plain text mermaid flowchart syntax that can be used by LLMs,
+ * documentation tools, or pasted into mermaid-compatible renderers.
+ */
+import type { APIRoute, GetStaticPaths } from 'astro';
+import { isAuthEnabled, isVisualiserEnabled } from '@utils/feature';
+import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
+import { getNodesAndEdges as getNodesAndEdgesForService } from '@utils/node-graphs/services-node-graph';
+import {
+  getNodesAndEdgesForCommands,
+  getNodesAndEdgesForEvents,
+  getNodesAndEdgesForQueries,
+} from '@utils/node-graphs/message-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForDomain } from '@utils/node-graphs/domains-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForFlows } from '@utils/node-graphs/flows-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForDataProduct } from '@utils/node-graphs/data-products-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForContainer } from '@utils/node-graphs/container-node-graph';
+import { getNodesAndEdges as getNodesAndEdgesForSystem } from '@utils/node-graphs/systems-node-graph';
+import { convertToMermaid } from '@utils/node-graphs/export-mermaid';
+import config from '@config';
+import type { PageTypes } from '@types';
+
+type PageTypesWithFlows = PageTypes | 'flows';
+
+// Prerender static pages when auth is disabled, use SSR when auth is enabled
+export const prerender = !isAuthEnabled();
+
+const getNodesAndEdgesFunctions = {
+  services: getNodesAndEdgesForService,
+  events: getNodesAndEdgesForEvents,
+  commands: getNodesAndEdgesForCommands,
+  queries: getNodesAndEdgesForQueries,
+  domains: getNodesAndEdgesForDomain,
+  flows: getNodesAndEdgesForFlows,
+  containers: getNodesAndEdgesForContainer,
+  'data-products': getNodesAndEdgesForDataProduct,
+  systems: getNodesAndEdgesForSystem,
+};
+
+export const getStaticPaths: GetStaticPaths = async () => {
+  if (isAuthEnabled() || !isVisualiserEnabled()) {
+    return [];
+  }
+
+  const { getFlows } = await import('@utils/collections/flows');
+
+  const loaders = {
+    ...pageDataLoader,
+    flows: getFlows,
+  };
+
+  const itemTypes: PageTypesWithFlows[] = [
+    'events',
+    'commands',
+    'queries',
+    'services',
+    'domains',
+    'flows',
+    'containers',
+    'data-products',
+    'systems',
+  ];
+
+  const allItems = await Promise.all(itemTypes.map((type) => loaders[type]()));
+
+  return allItems.flatMap((items, index) =>
+    items
+      .filter((item) => item.data.visualiser !== false)
+      .map((item) => ({
+        params: {
+          type: itemTypes[index],
+          id: item.data.id,
+          version: item.data.version,
+        },
+      }))
+  );
+};
+
+export const GET: APIRoute = async ({ params }) => {
+  const { type, id, version } = params;
+
+  if (!type || !id || !version || !isVisualiserEnabled()) {
+    return new Response('Not found', { status: 404 });
+  }
+
+  // Validate the type is supported
+  if (!(type in getNodesAndEdgesFunctions)) {
+    return new Response(`Unsupported type: ${type}`, { status: 400 });
+  }
+
+  try {
+    // Get nodes and edges for this resource
+    const { nodes, edges } = await getNodesAndEdgesFunctions[type as keyof typeof getNodesAndEdgesFunctions]({
+      id,
+      version,
+      mode: 'full',
+      channelRenderMode: config.visualiser?.channels?.renderMode === 'single' ? 'single' : 'flat',
+    });
+
+    if (!nodes || nodes.length === 0) {
+      return new Response('No diagram data available', { status: 404 });
+    }
+
+    // Convert to mermaid
+    const mermaidCode = convertToMermaid(nodes, edges, {
+      includeStyles: true,
+      direction: 'LR',
+    });
+
+    // Add header comment with metadata
+    const header = `%% EventCatalog Mermaid Diagram
+%% Resource: ${type}/${id} (v${version})
+%% Generated: ${new Date().toISOString()}
+
+`;
+
+    return new Response(header + mermaidCode, {
+      status: 200,
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Cache-Control': 'public, max-age=3600',
+      },
+    });
+  } catch (error) {
+    console.error('Error generating mermaid diagram:', error);
+    return new Response('Failed to generate diagram', { status: 500 });
+  }
+};
diff --git a/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/_index.data.ts b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/_index.data.ts
new file mode 100644
index 000000000..7272dd1d3
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/_index.data.ts
@@ -0,0 +1,111 @@
+// pages/visualiser/[type]/[id]/[version]/index.page.ts
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import { isAuthEnabled } from '@utils/feature';
+import type { PageTypes } from '@types';
+import { pageDataLoader } from '@utils/page-loaders/page-data-loader';
+import { isVisualiserEnabled } from '@utils/feature';
+
+type PageTypesWithFlows = PageTypes | 'flows';
+
+export class Page extends HybridPage {
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isAuthEnabled() || !isVisualiserEnabled()) {
+      return [];
+    }
+
+    const { getFlows } = await import('@utils/collections/flows');
+
+    const loaders = {
+      ...pageDataLoader,
+      flows: getFlows,
+    };
+
+    const itemTypes: PageTypesWithFlows[] = [
+      'agents',
+      'services',
+      'events',
+      'commands',
+      'queries',
+      'domains',
+      'flows',
+      'containers',
+      'data-products',
+      'systems',
+    ];
+    const allItems = await Promise.all(itemTypes.map((type) => loaders[type]()));
+
+    return allItems.flatMap((items, index) =>
+      items
+        .filter((item) => item.data.visualiser !== false)
+        .map((item) => ({
+          params: {
+            type: itemTypes[index],
+            id: item.data.id,
+            version: item.data.version,
+          },
+          props: {
+            type: itemTypes[index],
+            ...item,
+          },
+        }))
+    );
+  }
+
+  protected static async fetchData(params: any) {
+    const { type, id, version } = params;
+
+    if (!type || !id || !version || !isVisualiserEnabled()) {
+      return null;
+    }
+
+    const { getFlows } = await import('@utils/collections/flows');
+
+    const loaders = {
+      ...pageDataLoader,
+      flows: getFlows,
+    };
+
+    // Get all items of the specified type
+    const items = await loaders[type as PageTypesWithFlows]();
+
+    // Find the specific item by id and version
+    const item = items.find((i) => i.data.id === id && i.data.version === version && i.data.visualiser !== false);
+
+    if (!item) {
+      return null;
+    }
+
+    return {
+      type,
+      ...item,
+    };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Visualiser page not found',
+    });
+  }
+
+  static get clientAuthScript(): string {
+    if (!isAuthEnabled() || !isVisualiserEnabled()) {
+      return '';
+    }
+
+    return `
+      if (typeof window !== 'undefined' && !import.meta.env.SSR) {
+        fetch('/api/auth/session')
+          .then(res => res.json())
+          .then(session => {
+            if (!session?.user) {
+              window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
+            }
+          })
+          .catch(() => {
+            window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
+          });
+      }
+    `;
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/data/_index.data.ts b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/data/_index.data.ts
new file mode 100644
index 000000000..afd0ab80f
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/data/_index.data.ts
@@ -0,0 +1,80 @@
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import { isAuthEnabled, isVisualiserEnabled } from '@utils/feature';
+import { getServices, type Service } from '@utils/collections/services';
+
+const serviceHasData = (service: Service) => {
+  return service.data.writesTo?.length || 0 > 0 || service.data.readsFrom?.length || 0 > 0;
+};
+
+export class Page extends HybridPage {
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isAuthEnabled() || !isVisualiserEnabled()) {
+      return [];
+    }
+
+    const services = await getServices();
+    const servicesWithData = services.filter((service) => serviceHasData(service));
+
+    return servicesWithData.flatMap((service) => {
+      return {
+        params: {
+          type: 'services',
+          id: service.data.id,
+          version: service.data.version,
+        },
+        props: {
+          type: 'service',
+          ...service,
+        },
+      };
+    });
+  }
+
+  protected static async fetchData(params: any) {
+    const { id, version } = params;
+
+    if (!id || !version || !isVisualiserEnabled()) {
+      return null;
+    }
+
+    // Get all items of the specified type
+    const items = await getServices();
+
+    // Find the specific item by id and version, and only if it has entities
+    const item = items.find((i) => i.data.id === id && i.data.version === version && serviceHasData(i));
+
+    if (!item) {
+      return null;
+    }
+
+    return item;
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Service data page not found',
+    });
+  }
+
+  static get clientAuthScript(): string {
+    if (!isAuthEnabled() || !isVisualiserEnabled()) {
+      return '';
+    }
+
+    return `
+      if (typeof window !== 'undefined' && !import.meta.env.SSR) {
+        fetch('/api/auth/session')
+          .then(res => res.json())
+          .then(session => {
+            if (!session?.user) {
+              window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
+            }
+          })
+          .catch(() => {
+            window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
+          });
+      }
+    `;
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/data/index.astro b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/data/index.astro
new file mode 100644
index 000000000..01b36a420
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/data/index.astro
@@ -0,0 +1,57 @@
+---
+import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import VisualiserLayout from '@layouts/VisualiserLayout.astro';
+import { buildUrl } from '@utils/url-builder';
+import { ClientRouter } from 'astro:transitions';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+const {
+  data: { id },
+  collection,
+} = props;
+---
+
+<VisualiserLayout title={`Visualiser | ${props.data.name} (${props.collection})`} description={props.data.summary}>
+  <div class="m-4">
+    <div
+      class="h-[calc(100vh-130px)] w-full relative border border-[rgb(var(--ec-page-border))] rounded-md"
+      id={`${id}-portal`}
+      transition:animate="fade"
+    >
+    </div>
+    <NodeGraph
+      id={id}
+      collection={`${collection}-containers`}
+      title={`${props.data.name} (v${props.data.version}) - Data`}
+      mode="full"
+      linkTo="visualiser"
+      version={props.data.version}
+      linksToVisualiser={false}
+      href={{
+        label: `Open documentation for ${props.data.name} v${props.data.version}`,
+        url: buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.version}`),
+      }}
+    />
+  </div>
+  <ClientRouter />
+</VisualiserLayout>
+
+<script define:vars={{ id }}>
+  document.addEventListener('DOMContentLoaded', () => {
+    const urlSearchParams = new URLSearchParams(window.location.search);
+    const params = Object.fromEntries(urlSearchParams.entries());
+    const embeded = params.embed === 'true' ? true : false;
+    const viewport = document.getElementById(`${id}-portal`);
+
+    if (embeded) {
+      viewport.style.height = 'calc(100vh - 30px)';
+    }
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/entity-map/_index.data.ts b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/entity-map/_index.data.ts
new file mode 100644
index 000000000..0638dca54
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/entity-map/_index.data.ts
@@ -0,0 +1,77 @@
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import { isAuthEnabled, isVisualiserEnabled } from '@utils/feature';
+import { getServices, type Service } from '@utils/collections/services';
+
+const serviceHasEntities = (service: Service) => {
+  return (service.data.entities && service.data.entities.length > 0) || false;
+};
+
+export class Page extends HybridPage {
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isAuthEnabled() || !isVisualiserEnabled()) {
+      return [];
+    }
+
+    const services = await getServices();
+    const servicesWithEntities = services.filter((service) => serviceHasEntities(service));
+
+    return servicesWithEntities.flatMap((service) => {
+      return {
+        params: {
+          type: 'services',
+          id: service.data.id,
+          version: service.data.version,
+        },
+        props: {
+          type: 'services',
+          ...service,
+        },
+      };
+    });
+  }
+
+  protected static async fetchData(params: any) {
+    const { id, version } = params;
+
+    if (!id || !version || !isVisualiserEnabled()) {
+      return null;
+    }
+
+    const items = await getServices();
+    const item = items.find((i) => i.data.id === id && i.data.version === version && serviceHasEntities(i));
+
+    if (!item) {
+      return null;
+    }
+
+    return item;
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Service entity map page not found',
+    });
+  }
+
+  static get clientAuthScript(): string {
+    if (!isAuthEnabled() || !isVisualiserEnabled()) {
+      return '';
+    }
+
+    return `
+      if (typeof window !== 'undefined' && !import.meta.env.SSR) {
+        fetch('/api/auth/session')
+          .then(res => res.json())
+          .then(session => {
+            if (!session?.user) {
+              window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
+            }
+          })
+          .catch(() => {
+            window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
+          });
+      }
+    `;
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/entity-map/index.astro b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/entity-map/index.astro
new file mode 100644
index 000000000..b4237cb3f
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/entity-map/index.astro
@@ -0,0 +1,52 @@
+---
+import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import VisualiserLayout from '@layouts/VisualiserLayout.astro';
+import { ClientRouter } from 'astro:transitions';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+const {
+  data: { id },
+  collection,
+} = props;
+---
+
+<VisualiserLayout title={`Visualiser | ${props.data.name} (${props.collection})`} description={props.data.summary}>
+  <div class="p-2">
+    <div
+      class="h-[calc(100vh-5rem)] w-full relative border border-[rgb(var(--ec-page-border))]"
+      id={`${id}-portal`}
+      transition:animate="fade"
+    >
+    </div>
+    <NodeGraph
+      id={id}
+      collection={`${collection}-entities`}
+      title={`${props.data.name} (v${props.data.version}) - Entity Map`}
+      mode="full"
+      linkTo="visualiser"
+      version={props.data.version}
+      linksToVisualiser={false}
+    />
+  </div>
+  <ClientRouter />
+</VisualiserLayout>
+
+<script define:vars={{ id }}>
+  document.addEventListener('DOMContentLoaded', () => {
+    const urlSearchParams = new URLSearchParams(window.location.search);
+    const params = Object.fromEntries(urlSearchParams.entries());
+    const embeded = params.embed === 'true' ? true : false;
+    const viewport = document.getElementById(`${id}-portal`);
+
+    if (embeded) {
+      viewport.style.height = 'calc(100vh - 30px)';
+    }
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/index.astro b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/index.astro
new file mode 100644
index 000000000..73008fcfc
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/[version]/index.astro
@@ -0,0 +1,59 @@
+---
+import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import VisualiserLayout from '@layouts/VisualiserLayout.astro';
+import type { PageTypes } from '@types';
+import { buildUrl } from '@utils/url-builder';
+import { ClientRouter } from 'astro:transitions';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+const {
+  data: { id },
+  collection,
+} = props;
+---
+
+<VisualiserLayout title={`Visualiser | ${props.data.name} (${props.collection})`} description={props.data.summary}>
+  <div class="p-2">
+    <div
+      class="h-[calc(100vh-5rem)] w-full relative border border-[rgb(var(--ec-page-border))]"
+      id={`${id}-portal`}
+      transition:name="visualiser-graph"
+    >
+    </div>
+    <NodeGraph
+      id={id}
+      collection={collection}
+      title={`${props.data.name} (v${props.data.version})`}
+      mode="full"
+      linkTo="visualiser"
+      version={props.data.version}
+      linksToVisualiser={false}
+      zoomOnScroll={true}
+      href={{
+        label: `Open documentation for ${props.data.name} v${props.data.version}`,
+        url: buildUrl(`/docs/${props.collection}/${props.data.id}/${props.data.version}`),
+      }}
+    />
+  </div>
+  <ClientRouter />
+</VisualiserLayout>
+
+<script define:vars={{ id }}>
+  document.addEventListener('DOMContentLoaded', () => {
+    const urlSearchParams = new URLSearchParams(window.location.search);
+    const params = Object.fromEntries(urlSearchParams.entries());
+    const embeded = params.embed === 'true' ? true : false;
+    const viewport = document.getElementById(`${id}-portal`);
+
+    if (embeded) {
+      viewport.style.height = 'calc(100vh - 30px)';
+    }
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/index.astro b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/index.astro
new file mode 100644
index 000000000..c84ea57c2
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/[type]/[id]/index.astro
@@ -0,0 +1,70 @@
+---
+import Seo from '@components/Seo.astro';
+import { buildUrl } from '@utils/url-builder';
+import { getEvents } from '@utils/collections/events';
+import { getCommands } from '@utils/collections/commands';
+import { getServices } from '@utils/collections/services';
+import { getDomains } from '@utils/collections/domains';
+import { getContainers } from '@utils/collections/containers';
+import type { CollectionEntry } from 'astro:content';
+import type { CollectionTypes } from '@types';
+import { isVisualiserEnabled } from '@utils/feature';
+
+export async function getStaticPaths() {
+  if (!isVisualiserEnabled()) {
+    return [];
+  }
+
+  const [events, commands, services, domains, containers] = await Promise.all([
+    getEvents(),
+    getCommands(),
+    getServices(),
+    getDomains(),
+    getContainers(),
+  ]);
+
+  const resources = [...domains, ...events, ...services, ...commands, ...containers];
+  const resourcesWithVisualiserEnabled = resources.filter((resource) => resource.data.visualiser !== false);
+
+  const buildPages = (collection: CollectionEntry<CollectionTypes>[]) => {
+    return collection.map((item) => ({
+      params: {
+        type: item.collection,
+        id: item.data.id,
+      },
+      props: {
+        type: item.collection,
+        ...item,
+      },
+    }));
+  };
+
+  return [...buildPages(resourcesWithVisualiserEnabled)];
+}
+
+const props = Astro.props;
+const pageTitle = `${props.collection} | ${props.data.name}`.replace(/^\w/, (c) => c.toUpperCase());
+
+const { pathname } = Astro.url;
+
+const redirectUrl = buildUrl(pathname + '/' + props.data.latestVersion, false, true);
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <Seo title={`EventCatalog | ${pageTitle}`} ogTitle={pageTitle} />
+  </head>
+  <body>
+    <p>You are being redirected to <a href={redirectUrl}>{redirectUrl}</a></p>
+  </body>
+</html>
+
+<script define:vars={{ redirectUrl }}>
+  document.addEventListener('DOMContentLoaded', () => {
+    // redirect with any search params too
+    const searchParams = window.location.search;
+    const fullRedirectUrl = redirectUrl + searchParams;
+    window.location.href = fullRedirectUrl;
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/pages/visualiser/designs/[id]/_index.data.ts b/packages/core/eventcatalog/src/pages/visualiser/designs/[id]/_index.data.ts
new file mode 100644
index 000000000..dcba54822
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/designs/[id]/_index.data.ts
@@ -0,0 +1,75 @@
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import { isAuthEnabled, isVisualiserEnabled } from '@utils/feature';
+
+export class Page extends HybridPage {
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isAuthEnabled() || !isVisualiserEnabled()) {
+      return [];
+    }
+
+    const { getDesigns } = await import('@utils/collections/designs');
+
+    const designs = await getDesigns();
+
+    return designs.map((item) => ({
+      params: {
+        type: 'designs',
+        id: item.data.id,
+      },
+      props: {
+        type: 'designs',
+        ...item,
+      },
+    }));
+  }
+
+  protected static async fetchData(params: any) {
+    const { id } = params;
+
+    if (!id || !isVisualiserEnabled()) {
+      return null;
+    }
+
+    const { getDesigns } = await import('@utils/collections/designs');
+    const designs = await getDesigns();
+
+    const design = designs.find((design) => design.data.id === id);
+
+    if (!design) {
+      return null;
+    }
+
+    return {
+      type: 'designs',
+      ...design,
+    };
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Design not found',
+    });
+  }
+
+  static get clientAuthScript(): string {
+    if (!isAuthEnabled() || !isVisualiserEnabled()) {
+      return '';
+    }
+
+    return `
+      if (typeof window !== 'undefined' && !import.meta.env.SSR) {
+        fetch('/api/auth/session')
+          .then(res => res.json())
+          .then(session => {
+            if (!session?.user) {
+              window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
+            }
+          })
+          .catch(() => {
+            window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
+          });
+      }
+    `;
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/visualiser/designs/[id]/index.astro b/packages/core/eventcatalog/src/pages/visualiser/designs/[id]/index.astro
new file mode 100644
index 000000000..39a328ac9
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/designs/[id]/index.astro
@@ -0,0 +1,39 @@
+---
+import AstroNodeGraph from '@components/MDX/NodeGraph/AstroNodeGraph';
+import { ClientRouter } from 'astro:transitions';
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import { isEventCatalogChatEnabled } from '@utils/feature';
+
+import { Page } from './_index.data';
+
+const isChatEnabled = isEventCatalogChatEnabled();
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+const props = Astro.props;
+
+const { data } = props;
+---
+
+<VerticalSideBarLayout title={`Visualiser | Bounded context map`}>
+  <div class="m-4">
+    <div
+      class="h-[calc(100vh-130px)] w-full relative border border-[rgb(var(--ec-page-border))] rounded-md"
+      id={`${data.id}-portal`}
+      transition:animate="fade"
+    >
+    </div>
+    <AstroNodeGraph
+      id={data.id}
+      nodes={data.nodes}
+      edges={data.edges}
+      title={data.name}
+      client:only="react"
+      mode="full"
+      linkTo="visualiser"
+      isChatEnabled={isChatEnabled}
+    />
+  </div>
+  <ClientRouter />
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/pages/visualiser/domain-integrations/index.astro b/packages/core/eventcatalog/src/pages/visualiser/domain-integrations/index.astro
new file mode 100644
index 000000000..4444d8dfa
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/domain-integrations/index.astro
@@ -0,0 +1,26 @@
+---
+import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import VisualiserLayout from '@layouts/VisualiserLayout.astro';
+import { ClientRouter } from 'astro:transitions';
+---
+
+<VisualiserLayout title={`Visualiser | Domain Architecture`} description="High-level view of all domains and their relationships">
+  <div class="m-4">
+    <div
+      class="h-[calc(100vh-130px)] w-full relative border border-[rgb(var(--ec-page-border))] rounded-md"
+      id="domains-canvas-portal"
+      transition:animate="fade"
+    >
+    </div>
+    <NodeGraph
+      id="domains-canvas"
+      collection="domains-canvas"
+      title="Domain Integration Map"
+      mode="full"
+      linkTo="visualiser"
+      version="1.0.0"
+      linksToVisualiser={false}
+    />
+  </div>
+  <ClientRouter />
+</VisualiserLayout>
diff --git a/eventcatalog/src/pages/visualiser/domains/[id]/[version]/entity-map/_index.data.ts b/packages/core/eventcatalog/src/pages/visualiser/domains/[id]/[version]/entity-map/_index.data.ts
similarity index 100%
rename from eventcatalog/src/pages/visualiser/domains/[id]/[version]/entity-map/_index.data.ts
rename to packages/core/eventcatalog/src/pages/visualiser/domains/[id]/[version]/entity-map/_index.data.ts
diff --git a/packages/core/eventcatalog/src/pages/visualiser/domains/[id]/[version]/entity-map/index.astro b/packages/core/eventcatalog/src/pages/visualiser/domains/[id]/[version]/entity-map/index.astro
new file mode 100644
index 000000000..b4237cb3f
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/domains/[id]/[version]/entity-map/index.astro
@@ -0,0 +1,52 @@
+---
+import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import VisualiserLayout from '@layouts/VisualiserLayout.astro';
+import { ClientRouter } from 'astro:transitions';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+const {
+  data: { id },
+  collection,
+} = props;
+---
+
+<VisualiserLayout title={`Visualiser | ${props.data.name} (${props.collection})`} description={props.data.summary}>
+  <div class="p-2">
+    <div
+      class="h-[calc(100vh-5rem)] w-full relative border border-[rgb(var(--ec-page-border))]"
+      id={`${id}-portal`}
+      transition:animate="fade"
+    >
+    </div>
+    <NodeGraph
+      id={id}
+      collection={`${collection}-entities`}
+      title={`${props.data.name} (v${props.data.version}) - Entity Map`}
+      mode="full"
+      linkTo="visualiser"
+      version={props.data.version}
+      linksToVisualiser={false}
+    />
+  </div>
+  <ClientRouter />
+</VisualiserLayout>
+
+<script define:vars={{ id }}>
+  document.addEventListener('DOMContentLoaded', () => {
+    const urlSearchParams = new URLSearchParams(window.location.search);
+    const params = Object.fromEntries(urlSearchParams.entries());
+    const embeded = params.embed === 'true' ? true : false;
+    const viewport = document.getElementById(`${id}-portal`);
+
+    if (embeded) {
+      viewport.style.height = 'calc(100vh - 30px)';
+    }
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/pages/visualiser/domains/[id]/[version]/systems-context/_index.data.ts b/packages/core/eventcatalog/src/pages/visualiser/domains/[id]/[version]/systems-context/_index.data.ts
new file mode 100644
index 000000000..dee968841
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/domains/[id]/[version]/systems-context/_index.data.ts
@@ -0,0 +1,94 @@
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import { isAuthEnabled, isVisualiserEnabled } from '@utils/feature';
+import { getDomains } from '@utils/collections/domains';
+import { getSystems } from '@utils/collections/systems';
+
+/**
+ * A domain gets a System Diagram when it has systems and at least one of those
+ * systems takes part in a context graph — i.e. it declares relationships or actors. A
+ * domain whose systems have neither has nothing to show, so we don't generate a page.
+ */
+const domainHasSystemContext = (
+  domain: Awaited<ReturnType<typeof getDomains>>[number],
+  systemMap: Map<string, { data: { relationships?: unknown[]; actors?: unknown[] } }>
+) => {
+  const systemRefs = (domain.data.systems || []) as { id: string }[];
+  if (systemRefs.length === 0) return false;
+
+  return systemRefs.some((ref) => {
+    const system = systemMap.get(ref.id);
+    if (!system) return false;
+    const relationships = (system.data.relationships || []) as unknown[];
+    const actors = (system.data.actors || []) as unknown[];
+    return relationships.length > 0 || actors.length > 0;
+  });
+};
+
+export class Page extends HybridPage {
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isAuthEnabled() || !isVisualiserEnabled()) {
+      return [];
+    }
+
+    const [domains, systems] = await Promise.all([getDomains({ getAllVersions: false }), getSystems()]);
+    const systemMap = new Map(systems.map((system) => [system.data.id, system]));
+
+    return domains
+      .filter((domain) => domainHasSystemContext(domain, systemMap))
+      .map((domain) => ({
+        params: {
+          id: domain.data.id,
+          version: domain.data.version,
+        },
+        props: {
+          type: 'domains',
+          ...domain,
+        },
+      }));
+  }
+
+  protected static async fetchData(params: any) {
+    const { id, version } = params;
+
+    if (!id || !version || !isVisualiserEnabled()) {
+      return null;
+    }
+
+    const domains = await getDomains({ getAllVersions: false });
+    const item = domains.find((i) => i.data.id === id && i.data.version === version);
+
+    if (!item) {
+      return null;
+    }
+
+    return item;
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'Domain System Diagram page not found',
+    });
+  }
+
+  static get clientAuthScript(): string {
+    if (!isAuthEnabled() || !isVisualiserEnabled()) {
+      return '';
+    }
+
+    return `
+      if (typeof window !== 'undefined' && !import.meta.env.SSR) {
+        fetch('/api/auth/session')
+          .then(res => res.json())
+          .then(session => {
+            if (!session?.user) {
+              window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
+            }
+          })
+          .catch(() => {
+            window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
+          });
+      }
+    `;
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/visualiser/domains/[id]/[version]/systems-context/index.astro b/packages/core/eventcatalog/src/pages/visualiser/domains/[id]/[version]/systems-context/index.astro
new file mode 100644
index 000000000..baf2efc05
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/domains/[id]/[version]/systems-context/index.astro
@@ -0,0 +1,51 @@
+---
+import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import VisualiserLayout from '@layouts/VisualiserLayout.astro';
+import { ClientRouter } from 'astro:transitions';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+const {
+  data: { id },
+} = props;
+---
+
+<VisualiserLayout title={`Visualiser | ${props.data.name} - System Context`} description={props.data.summary}>
+  <div class="p-2">
+    <div
+      class="h-[calc(100vh-5rem)] w-full relative border border-[rgb(var(--ec-page-border))]"
+      id={`${id}-portal`}
+      transition:name="visualiser-graph"
+    >
+    </div>
+    <NodeGraph
+      id={id}
+      collection="domains-systems-context"
+      title={`${props.data.name} (v${props.data.version}) - System Context`}
+      mode="full"
+      linkTo="visualiser"
+      version={props.data.version}
+      linksToVisualiser={false}
+    />
+  </div>
+  <ClientRouter />
+</VisualiserLayout>
+
+<script define:vars={{ id }}>
+  document.addEventListener('DOMContentLoaded', () => {
+    const urlSearchParams = new URLSearchParams(window.location.search);
+    const params = Object.fromEntries(urlSearchParams.entries());
+    const embeded = params.embed === 'true' ? true : false;
+    const viewport = document.getElementById(`${id}-portal`);
+
+    if (embeded) {
+      viewport.style.height = 'calc(100vh - 30px)';
+    }
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/pages/visualiser/system-context-map/index.astro b/packages/core/eventcatalog/src/pages/visualiser/system-context-map/index.astro
new file mode 100644
index 000000000..93e54e324
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/system-context-map/index.astro
@@ -0,0 +1,41 @@
+---
+import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import VisualiserLayout from '@layouts/VisualiserLayout.astro';
+import { ClientRouter } from 'astro:transitions';
+
+const id = 'system-context-map';
+---
+
+<VisualiserLayout title={`Visualiser | System context map`}>
+  <div class="p-2">
+    <div
+      class="h-[calc(100vh-5rem)] w-full relative border border-[rgb(var(--ec-page-border))]"
+      id={`${id}-portal`}
+      transition:name="visualiser-graph"
+    >
+    </div>
+    <NodeGraph
+      id={id}
+      collection="system-context-map"
+      title="System context map"
+      mode="full"
+      linkTo="visualiser"
+      version="1.0.0"
+      linksToVisualiser={false}
+    />
+  </div>
+  <ClientRouter />
+</VisualiserLayout>
+
+<script define:vars={{ id }}>
+  document.addEventListener('DOMContentLoaded', () => {
+    const urlSearchParams = new URLSearchParams(window.location.search);
+    const params = Object.fromEntries(urlSearchParams.entries());
+    const embeded = params.embed === 'true' ? true : false;
+    const viewport = document.getElementById(`${id}-portal`);
+
+    if (embeded && viewport) {
+      viewport.style.height = 'calc(100vh - 30px)';
+    }
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/pages/visualiser/systems/[id]/[version]/context/_index.data.ts b/packages/core/eventcatalog/src/pages/visualiser/systems/[id]/[version]/context/_index.data.ts
new file mode 100644
index 000000000..f2971e81a
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/systems/[id]/[version]/context/_index.data.ts
@@ -0,0 +1,91 @@
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import { isAuthEnabled, isVisualiserEnabled } from '@utils/feature';
+import { getSystems } from '@utils/collections/systems';
+
+/**
+ * A system participates in the System Diagram if it declares relationships
+ * (to other systems) or actors, or if another system declares a relationship
+ * pointing at it. Systems with nothing on any side have nothing to show, so we
+ * don't generate a page for them.
+ */
+const buildSystemsInContextGraph = (systems: Awaited<ReturnType<typeof getSystems>>) => {
+  const referenced = new Set<string>();
+
+  for (const system of systems) {
+    const relationships = (system.data.relationships || []) as { id: string }[];
+    const actors = (system.data.actors || []) as { id: string }[];
+    if (relationships.length > 0 || actors.length > 0) referenced.add(system.data.id);
+    for (const relationship of relationships) {
+      referenced.add(relationship.id);
+    }
+  }
+
+  return systems.filter((system) => referenced.has(system.data.id));
+};
+
+export class Page extends HybridPage {
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isAuthEnabled() || !isVisualiserEnabled()) {
+      return [];
+    }
+
+    const systems = await getSystems();
+    const systemsInContext = buildSystemsInContextGraph(systems);
+
+    return systemsInContext.map((system) => ({
+      params: {
+        id: system.data.id,
+        version: system.data.version,
+      },
+      props: {
+        type: 'systems',
+        ...system,
+      },
+    }));
+  }
+
+  protected static async fetchData(params: any) {
+    const { id, version } = params;
+
+    if (!id || !version || !isVisualiserEnabled()) {
+      return null;
+    }
+
+    const systems = await getSystems();
+    const item = systems.find((i) => i.data.id === id && i.data.version === version);
+
+    if (!item) {
+      return null;
+    }
+
+    return item;
+  }
+
+  protected static createNotFoundResponse(): Response {
+    return new Response(null, {
+      status: 404,
+      statusText: 'System Diagram page not found',
+    });
+  }
+
+  static get clientAuthScript(): string {
+    if (!isAuthEnabled() || !isVisualiserEnabled()) {
+      return '';
+    }
+
+    return `
+      if (typeof window !== 'undefined' && !import.meta.env.SSR) {
+        fetch('/api/auth/session')
+          .then(res => res.json())
+          .then(session => {
+            if (!session?.user) {
+              window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
+            }
+          })
+          .catch(() => {
+            window.location.href = '/auth/login?callbackUrl=' + encodeURIComponent(window.location.pathname);
+          });
+      }
+    `;
+  }
+}
diff --git a/packages/core/eventcatalog/src/pages/visualiser/systems/[id]/[version]/context/index.astro b/packages/core/eventcatalog/src/pages/visualiser/systems/[id]/[version]/context/index.astro
new file mode 100644
index 000000000..5612d1ef5
--- /dev/null
+++ b/packages/core/eventcatalog/src/pages/visualiser/systems/[id]/[version]/context/index.astro
@@ -0,0 +1,51 @@
+---
+import NodeGraph from '@components/MDX/NodeGraph/NodeGraph.astro';
+import VisualiserLayout from '@layouts/VisualiserLayout.astro';
+import { ClientRouter } from 'astro:transitions';
+
+import { Page } from './_index.data';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const props = await Page.getData(Astro);
+
+const {
+  data: { id },
+} = props;
+---
+
+<VisualiserLayout title={`Visualiser | ${props.data.name} - System Context`} description={props.data.summary}>
+  <div class="p-2">
+    <div
+      class="h-[calc(100vh-5rem)] w-full relative border border-[rgb(var(--ec-page-border))]"
+      id={`${id}-portal`}
+      transition:name="visualiser-graph"
+    >
+    </div>
+    <NodeGraph
+      id={id}
+      collection="systems-context"
+      title={`${props.data.name} (v${props.data.version}) - System Context`}
+      mode="full"
+      linkTo="visualiser"
+      version={props.data.version}
+      linksToVisualiser={false}
+    />
+  </div>
+  <ClientRouter />
+</VisualiserLayout>
+
+<script define:vars={{ id }}>
+  document.addEventListener('DOMContentLoaded', () => {
+    const urlSearchParams = new URLSearchParams(window.location.search);
+    const params = Object.fromEntries(urlSearchParams.entries());
+    const embeded = params.embed === 'true' ? true : false;
+    const viewport = document.getElementById(`${id}-portal`);
+
+    if (embeded) {
+      viewport.style.height = 'calc(100vh - 30px)';
+    }
+  });
+</script>
diff --git a/packages/core/eventcatalog/src/plugins/__tests__/astro-trailing-slash-endpoint-fix.test.ts b/packages/core/eventcatalog/src/plugins/__tests__/astro-trailing-slash-endpoint-fix.test.ts
new file mode 100644
index 000000000..5d397e69c
--- /dev/null
+++ b/packages/core/eventcatalog/src/plugins/__tests__/astro-trailing-slash-endpoint-fix.test.ts
@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, dirname } from 'node:path';
+import { applyGetParamsTrailingSlashFix } from '../astro-trailing-slash-endpoint-fix';
+
+// From astro 7.0.3 - 7.0.6 (dist/core/render/params-and-props.js)
+const GET_PARAMS_7_0_3 = `function getParams(route, pathname) {
+  if (!route.params.length) return {};
+  const path = pathname.endsWith(".html") && route.type === "page" && !routeHasHtmlExtension(route) ? pathname.slice(0, -5) : pathname;
+  const allPatterns = [route, ...route.fallbackRoutes].map((r) => r.pattern);
+  const paramsMatch = allPatterns.map((pattern) => pattern.exec(path)).find((x) => x);
+  if (!paramsMatch) return {};
+}`;
+
+// From astro 7.0.7 - the same line was refactored to use \`let\`
+const GET_PARAMS_7_0_7 = `function getParams(route, pathname) {
+  if (!route.params.length) return {};
+  const hasHtmlSuffix = pathname.endsWith(".html") && !routeHasHtmlExtension(route);
+  const path = hasHtmlSuffix && route.type === "page" ? pathname.slice(0, -".html".length) : pathname;
+  const allPatterns = [route, ...route.fallbackRoutes].map((r) => r.pattern);
+  let paramsMatch = allPatterns.map((pattern) => pattern.exec(path)).find((x) => x);
+  if (!paramsMatch) return {};
+}`;
+
+describe('astro-trailing-slash-endpoint-fix', () => {
+  it('patches the astro 7.0.3-7.0.6 getParams source (const paramsMatch)', () => {
+    const patched = applyGetParamsTrailingSlashFix(GET_PARAMS_7_0_3);
+    expect(patched).toBeDefined();
+    expect(patched).toContain("path.endsWith('/') ? path.slice(0, -1) : path + '/'");
+    expect(patched).toContain('let paramsMatch = allPatterns');
+  });
+
+  it('patches the astro 7.0.7 getParams source (let paramsMatch)', () => {
+    const patched = applyGetParamsTrailingSlashFix(GET_PARAMS_7_0_7);
+    expect(patched).toBeDefined();
+    expect(patched).toContain("path.endsWith('/') ? path.slice(0, -1) : path + '/'");
+  });
+
+  it('returns undefined when the source does not match', () => {
+    expect(applyGetParamsTrailingSlashFix('const somethingElse = true;')).toBeUndefined();
+  });
+
+  // Canary: if this fails after an astro bump, astro refactored getParams and the
+  // fix in ../astro-trailing-slash-endpoint-fix.ts needs updating (or removing, if
+  // withastro/astro PR #17224's regression has been fixed upstream).
+  it('applies to the installed astro version', () => {
+    const require = createRequire(import.meta.url);
+    const astroRoot = dirname(require.resolve('astro/package.json'));
+    const source = readFileSync(join(astroRoot, 'dist/core/render/params-and-props.js'), 'utf8');
+    expect(applyGetParamsTrailingSlashFix(source)).toBeDefined();
+  });
+});
diff --git a/packages/core/eventcatalog/src/plugins/astro-trailing-slash-endpoint-fix.ts b/packages/core/eventcatalog/src/plugins/astro-trailing-slash-endpoint-fix.ts
new file mode 100644
index 000000000..a7bb05602
--- /dev/null
+++ b/packages/core/eventcatalog/src/plugins/astro-trailing-slash-endpoint-fix.ts
@@ -0,0 +1,52 @@
+import type { Plugin } from 'vite';
+
+// Works around a regression in Astro >= 7.0.4 (withastro/astro PR #17224).
+//
+// With `trailingSlash: 'always'`, Astro's prerender path generation
+// (dist/runtime/prerender/static-paths.js) appends a trailing slash to every
+// generated path, including dynamic file endpoints such as
+// /docs/teams/[id].md -> /docs/teams/customer-platform.md/. Since 7.0.4 the
+// route *pattern* for those endpoints no longer accepts a trailing slash, so
+// at render time `getParams` fails to extract any params and static builds
+// crash with `TypeError: Missing parameter: id`.
+//
+// The generation side runs in the Astro CLI process and cannot be patched
+// here, but `getParams` (dist/core/render/params-and-props.js) is bundled
+// through Vite into the prerender/server entries. This plugin rewrites it to
+// retry with the trailing slash flipped when no route pattern matches - a
+// no-op on unaffected Astro versions and once the regression is fixed
+// upstream.
+//
+// The regex below matches Astro 7.0.3 (`const paramsMatch`) through 7.0.7
+// (`let paramsMatch`). A unit test asserts it still applies to the installed
+// Astro version so a future refactor is caught in CI rather than as a broken
+// user build.
+const GET_PARAMS_PATTERN =
+  /(?:const|let)( paramsMatch = allPatterns\.map\(\(pattern\) => pattern\.exec\(path\)\)\.find\(\(x\) => x\);)/;
+
+export const applyGetParamsTrailingSlashFix = (code: string): string | undefined => {
+  if (!GET_PARAMS_PATTERN.test(code)) return undefined;
+  return code.replace(
+    GET_PARAMS_PATTERN,
+    `let$1
+  if (!paramsMatch) {
+    const flipped = path.endsWith('/') ? path.slice(0, -1) : path + '/';
+    paramsMatch = allPatterns.map((p) => p.exec(flipped)).find((x) => x);
+  }`
+  );
+};
+
+export const astroTrailingSlashEndpointFix = (): Plugin => ({
+  name: 'eventcatalog:astro-trailing-slash-endpoint-fix',
+  transform(code, id) {
+    if (!id.replace(/\\/g, '/').includes('astro/dist/core/render/params-and-props.js')) return;
+    const patched = applyGetParamsTrailingSlashFix(code);
+    if (!patched) {
+      console.warn(
+        '[eventcatalog] Could not apply the Astro trailing-slash endpoint fix; builds with trailingSlash: true may fail. Please raise an issue at https://github.com/event-catalog/eventcatalog/issues'
+      );
+      return;
+    }
+    return { code: patched, map: null };
+  },
+});
diff --git a/packages/core/eventcatalog/src/plugins/likec4.ts b/packages/core/eventcatalog/src/plugins/likec4.ts
new file mode 100644
index 000000000..d87cde8c8
--- /dev/null
+++ b/packages/core/eventcatalog/src/plugins/likec4.ts
@@ -0,0 +1,169 @@
+import type { Plugin } from 'vite';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { glob, globSync } from 'glob';
+
+interface LikeC4Config {
+  name?: string;
+}
+
+const virtualModuleId = 'virtual:likec4-projects';
+const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+
+const likeC4InstallMessage = `LikeC4 diagrams were found, but LikeC4 is not installed.
+
+Install LikeC4 in your EventCatalog project:
+
+  npm install --save-dev likec4@1.55.1 @likec4/icons@1.46.4
+  pnpm add -D likec4@1.55.1 @likec4/icons@1.46.4
+  yarn add -D likec4@1.55.1 @likec4/icons@1.46.4`;
+
+export const eventCatalogLikeC4 = async (workspaceDir: string): Promise<Plugin[]> => {
+  const enabled = hasLikeC4Sources(workspaceDir);
+  const registry = likeC4ProjectRegistry(workspaceDir, enabled);
+
+  if (!enabled) {
+    return [registry];
+  }
+
+  const LikeC4VitePlugin = await loadLikeC4VitePlugin(workspaceDir);
+
+  return [
+    LikeC4VitePlugin({
+      workspace: workspaceDir,
+    }),
+    registry,
+  ];
+};
+
+const hasLikeC4Sources = (workspaceDir: string) => {
+  return (
+    globSync('**/*.{c4,likec4}', {
+      cwd: workspaceDir,
+      ignore: ['**/node_modules/**'],
+    }).length > 0
+  );
+};
+
+const loadLikeC4VitePlugin = async (workspaceDir: string) => {
+  try {
+    const requireFromCatalog = createRequire(join(workspaceDir, 'package.json'));
+    const likeC4VitePluginPath = requireFromCatalog.resolve('likec4/vite-plugin');
+    const likeC4 = await import(/* @vite-ignore */ pathToFileURL(likeC4VitePluginPath).href);
+
+    if (!likeC4.LikeC4VitePlugin) {
+      throw new Error('The installed likec4 package does not export LikeC4VitePlugin from likec4/vite-plugin.');
+    }
+
+    return likeC4.LikeC4VitePlugin;
+  } catch (error) {
+    throw new Error(`${likeC4InstallMessage}\n\n${error instanceof Error ? error.message : String(error)}`);
+  }
+};
+
+const likeC4ProjectRegistry = (workspaceDir: string, enabled: boolean): Plugin => {
+  let discoveredProjects: string[] = [];
+
+  const discoverProjects = async () => {
+    const configFiles = await glob('**/{likec4.config.json,.likec4rc}', {
+      cwd: workspaceDir,
+      ignore: ['**/node_modules/**'],
+      absolute: true,
+    });
+
+    const projectNames = new Set<string>();
+
+    for (const configPath of configFiles) {
+      try {
+        const config = JSON.parse(readFileSync(configPath, 'utf-8')) as LikeC4Config;
+        if (config.name) {
+          projectNames.add(config.name);
+        }
+      } catch (error) {
+        console.warn(`[likec4-registry] Failed to parse ${configPath}:`, error);
+      }
+    }
+
+    discoveredProjects = Array.from(projectNames).sort();
+
+    if (discoveredProjects.length > 0) {
+      console.log(`[likec4-registry] Discovered projects: ${discoveredProjects.join(', ')}`);
+    }
+  };
+
+  return {
+    name: 'eventcatalog-likec4',
+
+    async buildStart() {
+      if (enabled) {
+        await discoverProjects();
+      }
+    },
+
+    resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+    },
+
+    load(id) {
+      if (id !== resolvedVirtualModuleId) {
+        return;
+      }
+
+      if (!enabled) {
+        return `
+export const projectRegistry = {
+  default: () => Promise.resolve({
+    LikeC4View: () => null,
+  }),
+};
+
+export const discoveredProjects = [];
+
+export function getProjectLoader() {
+  return projectRegistry.default;
+}
+`;
+      }
+
+      const imports = discoveredProjects
+        .map((name, index) => `import * as project_${index} from ${JSON.stringify(`likec4:react/${name}`)};`)
+        .join('\n');
+      const registryEntries = discoveredProjects
+        .map((name, index) => `  ${JSON.stringify(name)}: () => Promise.resolve(project_${index}),`)
+        .join('\n');
+
+      return `
+import * as defaultProject from 'likec4:react';
+${imports}
+
+export const projectRegistry = {
+  default: () => Promise.resolve(defaultProject),
+${registryEntries}
+};
+
+export const discoveredProjects = ${JSON.stringify(discoveredProjects)};
+
+export function getProjectLoader(projectName) {
+  return projectRegistry[projectName] || projectRegistry.default;
+}
+`;
+    },
+
+    configureServer(server) {
+      server.watcher.add(join(workspaceDir, '**/likec4.config.json'));
+      server.watcher.on('change', async (path) => {
+        if (path.endsWith('likec4.config.json')) {
+          await discoverProjects();
+          const module = server.moduleGraph.getModuleById(resolvedVirtualModuleId);
+          if (module) {
+            server.moduleGraph.invalidateModule(module);
+          }
+        }
+      });
+    },
+  };
+};
diff --git a/packages/core/eventcatalog/src/remark-plugins/__tests__/resource-ref.spec.ts b/packages/core/eventcatalog/src/remark-plugins/__tests__/resource-ref.spec.ts
new file mode 100644
index 000000000..8fa2f4cfe
--- /dev/null
+++ b/packages/core/eventcatalog/src/remark-plugins/__tests__/resource-ref.spec.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import { remarkResourceRef } from '../resource-ref';
+
+type MdxElement = {
+  type: 'mdxJsxTextElement';
+  name: string;
+  attributes: Array<{ type: string; name: string; value: string }>;
+  children: Array<{ type: string; value: string }>;
+};
+
+const createTree = (value: string) => ({
+  type: 'root',
+  children: [
+    {
+      type: 'paragraph',
+      children: [{ type: 'text', value }],
+    },
+  ],
+});
+
+const getResourceRefs = (node: any, refs: MdxElement[] = []): MdxElement[] => {
+  if (node?.type === 'mdxJsxTextElement' && node?.name === 'ResourceRef') {
+    refs.push(node as MdxElement);
+  }
+
+  if (Array.isArray(node?.children)) {
+    node.children.forEach((child: any) => getResourceRefs(child, refs));
+  }
+
+  return refs;
+};
+
+const getAttributeValue = (node: MdxElement, name: string) => {
+  return node.attributes.find((attr) => attr.name === name)?.value;
+};
+
+describe('remarkResourceRef', () => {
+  it('transforms custom doc references with nested paths', () => {
+    const tree = createTree('See [[doc|runbooks/oncall/intro]].');
+
+    remarkResourceRef()(tree);
+
+    const refs = getResourceRefs(tree);
+
+    expect(refs).toHaveLength(1);
+    expect(getAttributeValue(refs[0], 'type')).toBe('doc');
+    expect(getAttributeValue(refs[0], 'version')).toBeUndefined();
+    expect(refs[0].children[0].value).toBe('runbooks/oncall/intro');
+  });
+
+  it('preserves @ characters in doc references', () => {
+    const tree = createTree('See [[doc|runbooks/oncall@v2]].');
+
+    remarkResourceRef()(tree);
+
+    const refs = getResourceRefs(tree);
+
+    expect(refs).toHaveLength(1);
+    expect(getAttributeValue(refs[0], 'type')).toBe('doc');
+    expect(getAttributeValue(refs[0], 'version')).toBeUndefined();
+    expect(refs[0].children[0].value).toBe('runbooks/oncall@v2');
+  });
+
+  it('keeps version parsing for existing resource references', () => {
+    const tree = createTree('See [[service|OrdersService@1.2.3]].');
+
+    remarkResourceRef()(tree);
+
+    const refs = getResourceRefs(tree);
+
+    expect(refs).toHaveLength(1);
+    expect(getAttributeValue(refs[0], 'type')).toBe('service');
+    expect(getAttributeValue(refs[0], 'version')).toBe('1.2.3');
+    expect(refs[0].children[0].value).toBe('OrdersService');
+  });
+
+  it('transforms agent resource references', () => {
+    const tree = createTree('See [[agent|FraudReviewAgent@0.0.1]].');
+
+    remarkResourceRef()(tree);
+
+    const refs = getResourceRefs(tree);
+
+    expect(refs).toHaveLength(1);
+    expect(getAttributeValue(refs[0], 'type')).toBe('agent');
+    expect(getAttributeValue(refs[0], 'version')).toBe('0.0.1');
+    expect(refs[0].children[0].value).toBe('FraudReviewAgent');
+  });
+});
diff --git a/packages/core/eventcatalog/src/remark-plugins/directives.ts b/packages/core/eventcatalog/src/remark-plugins/directives.ts
new file mode 100644
index 000000000..ca7253ad4
--- /dev/null
+++ b/packages/core/eventcatalog/src/remark-plugins/directives.ts
@@ -0,0 +1,150 @@
+// src/remark-plugins/directives.js
+import { visit } from 'unist-util-visit';
+
+export function remarkDirectives() {
+  return (tree: any) => {
+    visit(tree, (node) => {
+      if (node.type === 'containerDirective') {
+        // Subtle, tinted backgrounds with a coloured left bar and icon.
+        // Body text inherits the page's normal text colour for readability.
+        const blockTypes = {
+          info: 'ec-admonition ec-admonition--info bg-blue-50/60 dark:bg-blue-950/30 border border-blue-200/70 dark:border-blue-900/60',
+          warning:
+            'ec-admonition ec-admonition--warning bg-amber-50/60 dark:bg-amber-950/30 border border-amber-200/70 dark:border-amber-900/60',
+          danger:
+            'ec-admonition ec-admonition--danger bg-red-50/60 dark:bg-red-950/30 border border-red-200/70 dark:border-red-900/60',
+          tip: 'ec-admonition ec-admonition--tip bg-emerald-50/60 dark:bg-emerald-900/40 border border-emerald-200/70 dark:border-emerald-700/80',
+          note: 'ec-admonition ec-admonition--note bg-slate-50/70 dark:bg-slate-900/40 border border-slate-200/70 dark:border-slate-700/60',
+        };
+
+        // Distinct Lucide icons per intent (warning vs danger no longer share).
+        const iconPaths = {
+          // Info — circle with "i"
+          info: 'M12 2a10 10 0 100 20 10 10 0 000-20zM12 8h.01M11 12h1v4h1',
+          // Warning — triangle with !
+          warning: 'M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0zM12 9v4 M12 17h.01',
+          // Danger — octagon with !
+          danger: 'M7.86 2h8.28L22 7.86v8.28L16.14 22H7.86L2 16.14V7.86L7.86 2z M12 8v4 M12 16h.01',
+          // Tip — lightbulb
+          tip: 'M9 18h6 M10 22h4 M12 2a7 7 0 0 0-4 12.74V17h8v-2.26A7 7 0 0 0 12 2z',
+          // Note — pencil-line
+          note: 'M12 20h9 M16.5 3.5a2.121 2.121 0 1 1 3 3L7 19l-4 1 1-4 12.5-12.5z',
+        };
+
+        // Coloured icon + title classes (intent accent colours).
+        const accentTextClasses = {
+          info: 'text-blue-700 dark:text-blue-300',
+          warning: 'text-amber-700 dark:text-amber-300',
+          danger: 'text-red-700 dark:text-red-300',
+          tip: 'text-emerald-700 dark:text-emerald-300',
+          note: 'text-slate-600 dark:text-slate-300',
+        };
+
+        const intent = node.name as keyof typeof blockTypes;
+        const accentClass = accentTextClasses[intent] || accentTextClasses.note;
+
+        node.data = node.data || {};
+        node.data.hName = 'div';
+        node.data.hProperties = {
+          class: `rounded-md px-3 py-2.5 my-4 text-[0.85rem] leading-relaxed ${blockTypes[intent] || ''}`,
+        };
+
+        // Check if there's a custom title (label) provided via :::note[Custom Title]
+        // In remark-directive, the label is stored in node.children as a paragraph node
+        // with data.directiveLabel = true
+        let titleChildren;
+        let contentChildren;
+
+        const firstChild = node.children && node.children.length > 0 ? node.children[0] : null;
+        const hasCustomTitle = firstChild && firstChild.data?.directiveLabel === true;
+
+        if (hasCustomTitle && firstChild) {
+          // Custom title was provided in the label - it contains markdown parsed as inline content
+          titleChildren = firstChild.children || [
+            { type: 'text', value: node.name.charAt(0).toUpperCase() + node.name.slice(1) },
+          ];
+          contentChildren = node.children.slice(1);
+        } else {
+          // No custom title, use default based on directive name
+          titleChildren = [
+            {
+              type: 'text',
+              value: node.name.charAt(0).toUpperCase() + node.name.slice(1),
+            },
+          ];
+          contentChildren = node.children;
+        }
+
+        // Create header div that will contain icon and title
+        const headerNode = {
+          type: 'element',
+          data: {
+            hName: 'div',
+            hProperties: {
+              class: `flex items-center gap-1.5 mb-1 ${accentClass}`,
+            },
+          },
+          children: [
+            // Lucide Icon SVG (smaller, accent-coloured)
+            {
+              type: 'element',
+              data: {
+                hName: 'svg',
+                hProperties: {
+                  xmlns: 'http://www.w3.org/2000/svg',
+                  width: '14',
+                  height: '14',
+                  viewBox: '0 0 24 24',
+                  fill: 'none',
+                  stroke: 'currentColor',
+                  strokeWidth: '2.25',
+                  strokeLinecap: 'round',
+                  strokeLinejoin: 'round',
+                  class: 'lucide shrink-0',
+                },
+              },
+              children: [
+                {
+                  type: 'element',
+                  data: {
+                    hName: 'path',
+                    hProperties: {
+                      d: iconPaths[node.name as keyof typeof iconPaths] || '',
+                    },
+                  },
+                },
+              ],
+            },
+            // Title — small, uppercase, tracked
+            {
+              type: 'element',
+              data: {
+                hName: 'span',
+                hProperties: {
+                  class: 'text-[0.7rem] font-semibold uppercase tracking-wider',
+                },
+              },
+              children: titleChildren,
+            },
+          ],
+        };
+
+        // Create content div for the rest of the children
+        const contentNode = {
+          type: 'element',
+          data: {
+            hName: 'div',
+            hProperties: {
+              class:
+                'prose prose-sm dark:prose-invert w-full max-w-none! prose-p:my-0.5 prose-p:text-inherit prose-p:text-[0.85rem] prose-p:leading-relaxed prose-code:text-[0.8rem]',
+            },
+          },
+          children: contentChildren,
+        };
+
+        // Replace node's children with header and content
+        node.children = [headerNode, contentNode];
+      }
+    });
+  };
+}
diff --git a/packages/core/eventcatalog/src/remark-plugins/mermaid.ts b/packages/core/eventcatalog/src/remark-plugins/mermaid.ts
new file mode 100644
index 000000000..c0725fcb3
--- /dev/null
+++ b/packages/core/eventcatalog/src/remark-plugins/mermaid.ts
@@ -0,0 +1,28 @@
+import type { RemarkPlugin } from '@astrojs/markdown-remark';
+import { visit } from 'unist-util-visit';
+
+const escapeMap: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+};
+
+const escapeHtml = (str: string) => str.replace(/[&<>"']/g, (c) => escapeMap[c]);
+
+export const mermaid: RemarkPlugin<[]> = () => (tree) => {
+  visit(tree, 'code', (node) => {
+    if (node.lang !== 'mermaid') return;
+
+    // @ts-ignore test
+    node.type = 'html';
+    node.value = `
+    <div class="mermaid-block pb-4">
+      <div class="mermaid border border-[rgb(var(--ec-page-border))] rounded-lg p-1" data-content="${escapeHtml(node.value)}">
+        <p class="text-[rgb(var(--ec-page-text-muted))]">Loading graph...</p>
+      </div>
+    </div>
+    `;
+  });
+};
diff --git a/eventcatalog/src/remark-plugins/plantuml.ts b/packages/core/eventcatalog/src/remark-plugins/plantuml.ts
similarity index 100%
rename from eventcatalog/src/remark-plugins/plantuml.ts
rename to packages/core/eventcatalog/src/remark-plugins/plantuml.ts
diff --git a/packages/core/eventcatalog/src/remark-plugins/resource-ref.ts b/packages/core/eventcatalog/src/remark-plugins/resource-ref.ts
new file mode 100644
index 000000000..bb34203ba
--- /dev/null
+++ b/packages/core/eventcatalog/src/remark-plugins/resource-ref.ts
@@ -0,0 +1,65 @@
+import { findAndReplace } from 'mdast-util-find-and-replace';
+
+/**
+ * Remark plugin that transforms [[type|Name]] or [[Name]] syntax into ResourceRef MDX components.
+ *
+ * Supported patterns:
+ * - [[entity|Order]] -> <ResourceRef type="entity">Order</ResourceRef>
+ * - [[service|OrderService@1.0.0]] -> <ResourceRef type="service" version="1.0.0">OrderService</ResourceRef>
+ * - [[diagram|target-architecture]] -> <ResourceRef type="diagram">target-architecture</ResourceRef>
+ * - [[doc|runbooks/oncall]] -> <ResourceRef type="doc">runbooks/oncall</ResourceRef>
+ * - [[Order]] -> <ResourceRef type="entity">Order</ResourceRef> (defaults to entity)
+ * - [[Order@0.0.1]] -> <ResourceRef type="entity" version="0.0.1">Order</ResourceRef>
+ */
+export function remarkResourceRef() {
+  return function (tree: any) {
+    // First pass: match [[type|Name]], [[type|Name@version]], or nested ids like [[doc|guides/getting-started]]
+    findAndReplace(tree, [
+      /\[\[([a-z-]+)\|([^[\]]+?)\]\]/g,
+      // @ts-ignore: Types are complex but it works
+      function (_match: string, type: string, target: string) {
+        const normalizedType = type.trim().toLowerCase();
+        let resourceId = target.trim();
+        let version: string | undefined;
+
+        // Preserve existing @version behavior for resource refs, but keep doc targets as-is.
+        if (normalizedType !== 'doc') {
+          const versionMatch = resourceId.match(/^(.*)@([\d.]+)$/);
+          if (versionMatch) {
+            resourceId = versionMatch[1].trim();
+            version = versionMatch[2];
+          }
+        }
+
+        const attributes: any[] = [{ type: 'mdxJsxAttribute', name: 'type', value: normalizedType }];
+        if (version) {
+          attributes.push({ type: 'mdxJsxAttribute', name: 'version', value: version });
+        }
+        return {
+          type: 'mdxJsxTextElement',
+          name: 'ResourceRef',
+          attributes,
+          children: [{ type: 'text', value: resourceId }],
+        };
+      },
+    ]);
+
+    // Second pass: match [[Name]] or [[Name@version]] pattern (defaults to entity)
+    findAndReplace(tree, [
+      /\[\[([\w-]+)(?:@([\d.]+))?\]\]/g,
+      // @ts-ignore: Types are complex but it works
+      function (_match: string, resourceId: string, version?: string) {
+        const attributes: any[] = [{ type: 'mdxJsxAttribute', name: 'type', value: 'entity' }];
+        if (version) {
+          attributes.push({ type: 'mdxJsxAttribute', name: 'version', value: version });
+        }
+        return {
+          type: 'mdxJsxTextElement',
+          name: 'ResourceRef',
+          attributes,
+          children: [{ type: 'text', value: resourceId }],
+        };
+      },
+    ]);
+  };
+}
diff --git a/packages/core/eventcatalog/src/stores/eventcatalog-store.spec.ts b/packages/core/eventcatalog/src/stores/eventcatalog-store.spec.ts
new file mode 100644
index 000000000..da9217151
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/eventcatalog-store.spec.ts
@@ -0,0 +1,60 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { EventCatalogStore } from './eventcatalog-store';
+
+type TestStoreResources = {
+  users: { id: string; name: string }[];
+  teams: { id: string; name: string }[];
+};
+
+describe('EventCatalogStore', () => {
+  it('writes one collection while preserving the rest of the store', async () => {
+    const tempDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-store-'));
+    const storePath = EventCatalogStore.getStorePath(tempDir, 'directory');
+    const store = new EventCatalogStore<TestStoreResources>({
+      storePath,
+      resources: {
+        users: [],
+        teams: [],
+      },
+    });
+
+    try {
+      await store.writeCollection('teams', [{ id: 'platform', name: 'Platform' }]);
+      await store.writeCollection('users', [{ id: 'jane', name: 'Jane' }]);
+
+      const stored = JSON.parse(await readFile(storePath, 'utf8'));
+      expect(stored).toMatchObject({
+        version: '1',
+        resources: {
+          users: [{ id: 'jane', name: 'Jane' }],
+          teams: [{ id: 'platform', name: 'Platform' }],
+        },
+      });
+      expect(stored.generatedAt).toEqual(expect.any(String));
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it('does not create a store file when clearing a collection that has not been generated', async () => {
+    const tempDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-store-'));
+    const storePath = EventCatalogStore.getStorePath(tempDir, 'directory');
+    const store = new EventCatalogStore<TestStoreResources>({
+      storePath,
+      resources: {
+        users: [],
+        teams: [],
+      },
+    });
+
+    try {
+      await store.clearCollectionIfStoreExists('users');
+      expect(await store.exists()).toBe(false);
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/core/eventcatalog/src/stores/eventcatalog-store.ts b/packages/core/eventcatalog/src/stores/eventcatalog-store.ts
new file mode 100644
index 000000000..53634e93d
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/eventcatalog-store.ts
@@ -0,0 +1,103 @@
+import { access, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+type StoreResource = {
+  id: string;
+};
+
+type StoreResources<TResources> = {
+  [K in keyof TResources]: StoreResource[];
+};
+
+type EventCatalogStoreFile<TResources> = {
+  version: '1';
+  generatedAt: string;
+  resources: TResources;
+};
+
+type EventCatalogStoreOptions<TResources> = {
+  storePath: string;
+  resources: TResources;
+};
+
+const writeQueues = new Map<string, Promise<void>>();
+
+export class EventCatalogStore<TResources extends StoreResources<TResources>> {
+  static getStorePath(projectDir: string, name: string) {
+    return path.join(projectDir, '.eventcatalog', 'store', `${name}.json`);
+  }
+
+  constructor(private options: EventCatalogStoreOptions<TResources>) {}
+
+  async exists() {
+    try {
+      await access(this.options.storePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async read(): Promise<EventCatalogStoreFile<TResources>> {
+    try {
+      const store = JSON.parse(await readFile(this.options.storePath, 'utf8')) as Partial<EventCatalogStoreFile<TResources>>;
+      return {
+        version: '1',
+        generatedAt: store.generatedAt ?? new Date().toISOString(),
+        resources: this.normalizeResources(store.resources),
+      };
+    } catch {
+      return this.createEmptyStore();
+    }
+  }
+
+  async writeCollection<TKey extends keyof TResources & string>(collection: TKey, resources: TResources[TKey]) {
+    await this.queueWrite(async () => {
+      const store = await this.read();
+      store.generatedAt = new Date().toISOString();
+      store.resources[collection] = [...resources].sort((a, b) => a.id.localeCompare(b.id)) as TResources[TKey];
+
+      await this.write(store);
+    });
+  }
+
+  async clearCollectionIfStoreExists<TKey extends keyof TResources & string>(collection: TKey) {
+    if (!(await this.exists())) return;
+    await this.writeCollection(collection, [] as unknown as TResources[TKey]);
+  }
+
+  private createEmptyStore(): EventCatalogStoreFile<TResources> {
+    return {
+      version: '1',
+      generatedAt: new Date().toISOString(),
+      resources: this.normalizeResources(),
+    };
+  }
+
+  private normalizeResources(resources?: Partial<TResources>): TResources {
+    const normalized = {} as TResources;
+
+    for (const collection of Object.keys(this.options.resources) as (keyof TResources & string)[]) {
+      const value = resources?.[collection];
+      normalized[collection] = (
+        Array.isArray(value) ? value : [...this.options.resources[collection]]
+      ) as TResources[typeof collection];
+    }
+
+    return normalized;
+  }
+
+  private async write(store: EventCatalogStoreFile<TResources>) {
+    await mkdir(path.dirname(this.options.storePath), { recursive: true });
+    await writeFile(`${this.options.storePath}.tmp`, `${JSON.stringify(store, null, 2)}\n`);
+    await rename(`${this.options.storePath}.tmp`, this.options.storePath);
+  }
+
+  private async queueWrite(write: () => Promise<void>) {
+    const previousWrite = writeQueues.get(this.options.storePath) ?? Promise.resolve();
+    const nextWrite = previousWrite.catch(() => undefined).then(write);
+
+    writeQueues.set(this.options.storePath, nextWrite);
+    await nextWrite;
+  }
+}
diff --git a/packages/core/eventcatalog/src/stores/favorites-store.ts b/packages/core/eventcatalog/src/stores/favorites-store.ts
new file mode 100644
index 000000000..a79211518
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/favorites-store.ts
@@ -0,0 +1,83 @@
+import { atom } from 'nanostores';
+
+const FAVORITES_KEY = 'eventcatalog-sidebar-favorites';
+
+export type FavoriteItem = {
+  nodeKey: string; // The key of the favorited node
+  path: string[]; // Path of keys to reach this node
+  title: string; // Display title
+  badge?: string; // Type badge (Domain, Service, etc.)
+  href?: string; // Direct link if it's a leaf item
+};
+
+export const favoritesStore = atom<FavoriteItem[]>([]);
+
+// Initialize store from localStorage on client side
+const initStore = () => {
+  if (typeof window !== 'undefined') {
+    try {
+      const stored = localStorage.getItem(FAVORITES_KEY);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        if (JSON.stringify(favoritesStore.get()) !== stored) {
+          favoritesStore.set(parsed);
+        }
+      }
+    } catch (e) {
+      console.warn('Failed to load favorites:', e);
+    }
+  }
+};
+
+if (typeof window !== 'undefined') {
+  initStore();
+
+  // Listen for storage events (cross-tab sync)
+  window.addEventListener('storage', (e) => {
+    if (e.key === FAVORITES_KEY) {
+      initStore();
+    }
+  });
+
+  // Listen for custom events (same-tab sync between instances)
+  window.addEventListener('favorites-updated', () => {
+    initStore();
+  });
+}
+
+export const saveFavorites = (favorites: FavoriteItem[]) => {
+  favoritesStore.set(favorites);
+  if (typeof window !== 'undefined') {
+    try {
+      localStorage.setItem(FAVORITES_KEY, JSON.stringify(favorites));
+      // Dispatch event to notify other store instances/components
+      window.dispatchEvent(new CustomEvent('favorites-updated'));
+    } catch (e) {
+      console.warn('Failed to save favorites:', e);
+    }
+  }
+};
+
+export const addFavorite = (item: FavoriteItem) => {
+  const current = favoritesStore.get();
+  const exists = current.some((fav) => fav.nodeKey === item.nodeKey);
+  if (!exists) {
+    saveFavorites([...current, item]);
+  }
+};
+
+export const removeFavorite = (nodeKey: string) => {
+  const current = favoritesStore.get();
+  saveFavorites(current.filter((fav) => fav.nodeKey !== nodeKey));
+};
+
+export const toggleFavorite = (item: FavoriteItem) => {
+  const current = favoritesStore.get();
+  const exists = current.some((fav) => fav.nodeKey === item.nodeKey);
+
+  if (exists) {
+    removeFavorite(item.nodeKey);
+  } else {
+    addFavorite(item);
+  }
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/__tests__/data-product-builder.spec.ts b/packages/core/eventcatalog/src/stores/sidebar-store/__tests__/data-product-builder.spec.ts
new file mode 100644
index 000000000..fd638d9eb
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/__tests__/data-product-builder.spec.ts
@@ -0,0 +1,529 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { buildDataProductNode } from '../builders/data-product';
+import type { CollectionEntry } from 'astro:content';
+
+// Mock feature utils
+vi.mock('@utils/feature', () => ({
+  isVisualiserEnabled: () => true,
+  isChangelogEnabled: () => false,
+}));
+
+// Mock url-builder
+vi.mock('@utils/url-builder', () => ({
+  buildUrl: (path: string) => path,
+}));
+
+const createMockDataProduct = (
+  overrides: Partial<CollectionEntry<'data-products'>['data']> = {}
+): CollectionEntry<'data-products'> =>
+  ({
+    id: 'data-products/TestDataProduct/index.mdx',
+    slug: 'data-products/TestDataProduct',
+    collection: 'data-products',
+    data: {
+      id: 'TestDataProduct',
+      name: 'Test Data Product',
+      version: '1.0.0',
+      summary: 'A test data product',
+      inputs: [],
+      outputs: [],
+      owners: [],
+      ...overrides,
+    },
+  }) as CollectionEntry<'data-products'>;
+
+const createMockEvent = (id: string, version: string): CollectionEntry<'events'> =>
+  ({
+    id: `events/${id}/index.mdx`,
+    slug: `events/${id}`,
+    collection: 'events',
+    data: { id, version, name: id },
+  }) as CollectionEntry<'events'>;
+
+const createMockCommand = (id: string, version: string): CollectionEntry<'commands'> =>
+  ({
+    id: `commands/${id}/index.mdx`,
+    slug: `commands/${id}`,
+    collection: 'commands',
+    data: { id, version, name: id },
+  }) as CollectionEntry<'commands'>;
+
+const createMockQuery = (id: string, version: string): CollectionEntry<'queries'> =>
+  ({
+    id: `queries/${id}/index.mdx`,
+    slug: `queries/${id}`,
+    collection: 'queries',
+    data: { id, version, name: id },
+  }) as CollectionEntry<'queries'>;
+
+const createMockService = (id: string, version: string): CollectionEntry<'services'> =>
+  ({
+    id: `services/${id}/index.mdx`,
+    slug: `services/${id}`,
+    collection: 'services',
+    data: { id, version, name: id },
+  }) as CollectionEntry<'services'>;
+
+const createMockContainer = (id: string, version: string): CollectionEntry<'containers'> =>
+  ({
+    id: `containers/${id}/index.mdx`,
+    slug: `containers/${id}`,
+    collection: 'containers',
+    data: { id, version, name: id, container_type: 'database', authoritative: true },
+  }) as CollectionEntry<'containers'>;
+
+const createMockChannel = (id: string, version: string): CollectionEntry<'channels'> =>
+  ({
+    id: `channels/${id}/index.mdx`,
+    slug: `channels/${id}`,
+    collection: 'channels',
+    data: { id, version, name: id },
+  }) as CollectionEntry<'channels'>;
+
+const emptyContext = {
+  events: [] as CollectionEntry<'events'>[],
+  commands: [] as CollectionEntry<'commands'>[],
+  queries: [] as CollectionEntry<'queries'>[],
+  services: [] as CollectionEntry<'services'>[],
+  containers: [] as CollectionEntry<'containers'>[],
+  channels: [] as CollectionEntry<'channels'>[],
+  resourceDocs: [],
+  resourceDocCategories: [],
+};
+
+describe('buildDataProductNode', () => {
+  describe('basic structure', () => {
+    it('returns a NavNode with correct basic properties', () => {
+      const dataProduct = createMockDataProduct();
+      const result = buildDataProductNode(dataProduct, [], emptyContext);
+
+      expect(result).toMatchObject({
+        type: 'item',
+        title: 'Test Data Product',
+        badge: 'Data Product',
+        summary: 'A test data product',
+      });
+    });
+
+    it('includes Overview link in Quick Reference section', () => {
+      const dataProduct = createMockDataProduct();
+      const result = buildDataProductNode(dataProduct, [], emptyContext);
+
+      const quickRef = (result.pages as any[])?.find((p: any) => p.title === 'Quick Reference');
+      expect(quickRef).toBeDefined();
+      expect((quickRef as any)?.pages).toContainEqual({
+        type: 'item',
+        title: 'Overview',
+        href: '/docs/data-products/TestDataProduct/1.0.0',
+      });
+    });
+
+    it('includes Architecture section with Map link when visualiser is enabled', () => {
+      const dataProduct = createMockDataProduct();
+      const result = buildDataProductNode(dataProduct, [], emptyContext);
+
+      const archSection = (result.pages as any[])?.find((p: any) => p.title === 'Architecture');
+      expect(archSection).toBeDefined();
+      expect((archSection as any)?.pages).toContainEqual({
+        type: 'item',
+        title: 'Map',
+        href: '/visualiser/data-products/TestDataProduct/1.0.0',
+      });
+    });
+  });
+
+  describe('inputs resolution', () => {
+    it('resolves event inputs with plural key (events:)', () => {
+      const dataProduct = createMockDataProduct({
+        inputs: [{ id: 'OrderCreated', version: '1.0.0' }],
+      });
+      const context = {
+        ...emptyContext,
+        events: [createMockEvent('OrderCreated', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const inputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Inputs');
+
+      expect(inputsSection).toBeDefined();
+      expect((inputsSection as any)?.pages).toContain('events:OrderCreated:1.0.0');
+    });
+
+    it('resolves command inputs with plural key (commands:)', () => {
+      const dataProduct = createMockDataProduct({
+        inputs: [{ id: 'CreateOrder', version: '1.0.0' }],
+      });
+      const context = {
+        ...emptyContext,
+        commands: [createMockCommand('CreateOrder', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const inputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Inputs');
+
+      expect(inputsSection).toBeDefined();
+      expect((inputsSection as any)?.pages).toContain('commands:CreateOrder:1.0.0');
+    });
+
+    it('resolves query inputs with plural key (queries:)', () => {
+      const dataProduct = createMockDataProduct({
+        inputs: [{ id: 'GetOrder', version: '1.0.0' }],
+      });
+      const context = {
+        ...emptyContext,
+        queries: [createMockQuery('GetOrder', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const inputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Inputs');
+
+      expect(inputsSection).toBeDefined();
+      expect((inputsSection as any)?.pages).toContain('queries:GetOrder:1.0.0');
+    });
+
+    it('resolves service inputs with singular key (service:)', () => {
+      const dataProduct = createMockDataProduct({
+        inputs: [{ id: 'OrderService', version: '1.0.0' }],
+      });
+      const context = {
+        ...emptyContext,
+        services: [createMockService('OrderService', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const inputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Inputs');
+
+      expect(inputsSection).toBeDefined();
+      expect((inputsSection as any)?.pages).toContain('service:OrderService:1.0.0');
+    });
+
+    it('resolves container inputs with singular key (container:)', () => {
+      const dataProduct = createMockDataProduct({
+        inputs: [{ id: 'OrderDatabase', version: '1.0.0' }],
+      });
+      const context = {
+        ...emptyContext,
+        containers: [createMockContainer('OrderDatabase', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const inputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Inputs');
+
+      expect(inputsSection).toBeDefined();
+      expect((inputsSection as any)?.pages).toContain('container:OrderDatabase:1.0.0');
+    });
+
+    it('resolves channel inputs with singular key (channel:)', () => {
+      const dataProduct = createMockDataProduct({
+        inputs: [{ id: 'OrderChannel', version: '1.0.0' }],
+      });
+      const context = {
+        ...emptyContext,
+        channels: [createMockChannel('OrderChannel', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const inputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Inputs');
+
+      expect(inputsSection).toBeDefined();
+      expect((inputsSection as any)?.pages).toContain('channel:OrderChannel:1.0.0');
+    });
+
+    it('resolves to latest version in collection when no version specified', () => {
+      const dataProduct = createMockDataProduct({
+        inputs: [{ id: 'OrderCreated', version: 'latest' }], // No explicit version specified, using latest
+      });
+      const context = {
+        ...emptyContext,
+        events: [createMockEvent('OrderCreated', '1.0.0'), createMockEvent('OrderCreated', '2.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const inputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Inputs');
+
+      // Should resolve to the latest version (2.0.0) in the collection
+      expect((inputsSection as any)?.pages).toContain('events:OrderCreated:2.0.0');
+    });
+
+    it('resolves semver ranges to matching version', () => {
+      const dataProduct = createMockDataProduct({
+        inputs: [{ id: 'OrderCreated', version: '^1.0.0' }], // Semver range
+      });
+      const context = {
+        ...emptyContext,
+        events: [
+          createMockEvent('OrderCreated', '1.0.0'),
+          createMockEvent('OrderCreated', '1.2.3'),
+          createMockEvent('OrderCreated', '2.0.0'),
+        ],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const inputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Inputs');
+
+      // ^1.0.0 should match 1.2.3 (highest in range)
+      expect((inputsSection as any)?.pages).toContain('events:OrderCreated:1.2.3');
+    });
+
+    it('skips unknown resources (not in any collection)', () => {
+      const dataProduct = createMockDataProduct({
+        inputs: [{ id: 'UnknownResource', version: '1.0.0' }],
+      });
+
+      const result = buildDataProductNode(dataProduct, [], emptyContext);
+      const inputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Inputs');
+
+      // Inputs section should not exist since all inputs are unknown
+      expect(inputsSection).toBeUndefined();
+    });
+
+    it('does not render Inputs section when no inputs are defined', () => {
+      const dataProduct = createMockDataProduct({ inputs: [] });
+      const result = buildDataProductNode(dataProduct, [], emptyContext);
+
+      const inputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Inputs');
+      expect(inputsSection).toBeUndefined();
+    });
+  });
+
+  describe('outputs resolution', () => {
+    it('resolves event outputs with plural key (events:)', () => {
+      const dataProduct = createMockDataProduct({
+        outputs: [{ id: 'OrderAnalytics', version: '1.0.0' }],
+      });
+      const context = {
+        ...emptyContext,
+        events: [createMockEvent('OrderAnalytics', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const outputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Outputs');
+
+      expect(outputsSection).toBeDefined();
+      expect((outputsSection as any)?.pages).toContain('events:OrderAnalytics:1.0.0');
+    });
+
+    it('resolves service outputs with singular key (service:)', () => {
+      const dataProduct = createMockDataProduct({
+        outputs: [{ id: 'ReportingService', version: '1.0.0' }],
+      });
+      const context = {
+        ...emptyContext,
+        services: [createMockService('ReportingService', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const outputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Outputs');
+
+      expect(outputsSection).toBeDefined();
+      expect((outputsSection as any)?.pages).toContain('service:ReportingService:1.0.0');
+    });
+
+    it('does not render Outputs section when no outputs are defined', () => {
+      const dataProduct = createMockDataProduct({ outputs: [] });
+      const result = buildDataProductNode(dataProduct, [], emptyContext);
+
+      const outputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Outputs');
+      expect(outputsSection).toBeUndefined();
+    });
+  });
+
+  describe('mixed inputs and outputs', () => {
+    it('correctly resolves multiple inputs and outputs of different types', () => {
+      const dataProduct = createMockDataProduct({
+        inputs: [
+          { id: 'OrderCreated', version: '1.0.0' },
+          { id: 'PaymentService', version: '2.0.0' },
+          { id: 'OrderDatabase', version: '1.0.0' },
+        ],
+        outputs: [
+          { id: 'OrderAnalytics', version: '1.0.0' },
+          { id: 'OrderChannel', version: '1.0.0' },
+        ],
+      });
+      const context = {
+        ...emptyContext,
+        events: [createMockEvent('OrderCreated', '1.0.0'), createMockEvent('OrderAnalytics', '1.0.0')],
+        services: [createMockService('PaymentService', '2.0.0')],
+        containers: [createMockContainer('OrderDatabase', '1.0.0')],
+        channels: [createMockChannel('OrderChannel', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+
+      const inputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Inputs');
+      expect((inputsSection as any)?.pages).toEqual(
+        expect.arrayContaining(['events:OrderCreated:1.0.0', 'service:PaymentService:2.0.0', 'container:OrderDatabase:1.0.0'])
+      );
+
+      const outputsSection = (result.pages as any[])?.find((p: any) => p.title === 'Outputs');
+      expect((outputsSection as any)?.pages).toEqual(
+        expect.arrayContaining(['events:OrderAnalytics:1.0.0', 'channel:OrderChannel:1.0.0'])
+      );
+    });
+  });
+
+  describe('data contracts (Data Contracts section)', () => {
+    it('renders Data Contracts section when outputs have contract field', () => {
+      const dataProduct = createMockDataProduct({
+        outputs: [
+          {
+            id: 'OrdersDB',
+            version: '1.0.0',
+            contract: { path: 'fact-orders-contract.json', name: 'Fact Orders Contract', type: 'json-schema' },
+          },
+          {
+            id: 'PaymentsDB',
+            version: '1.0.0',
+            contract: { path: 'payments-schema.json', name: 'Payments Schema', type: 'avro' },
+          },
+        ],
+      }) as any;
+
+      const context = {
+        ...emptyContext,
+        containers: [createMockContainer('OrdersDB', '1.0.0'), createMockContainer('PaymentsDB', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const apiContractsSection = (result.pages as any[])?.find((p: any) => p.title === 'Data Contracts');
+
+      expect(apiContractsSection).toBeDefined();
+      expect((apiContractsSection as any)?.icon).toBe('FileCheck');
+      expect((apiContractsSection as any)?.pages).toHaveLength(2);
+      expect((apiContractsSection as any)?.pages[0]).toMatchObject({
+        type: 'item',
+        title: 'Fact Orders Contract (JSON)',
+        summary: 'Type: json-schema',
+        href: '/schemas/data-products/TestDataProduct/1.0.0?contract=fact-orders-contract.json',
+      });
+      expect((apiContractsSection as any)?.pages[1]).toMatchObject({
+        type: 'item',
+        title: 'Payments Schema (JSON)',
+        summary: 'Type: avro',
+        href: '/schemas/data-products/TestDataProduct/1.0.0?contract=payments-schema.json',
+      });
+    });
+
+    it('does not render Data Contracts section when no outputs have contract field', () => {
+      const dataProduct = createMockDataProduct({
+        outputs: [{ id: 'OrdersDB', version: '1.0.0' }],
+      });
+
+      const context = {
+        ...emptyContext,
+        containers: [createMockContainer('OrdersDB', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const apiContractsSection = result.pages?.find((p: any) => p.title === 'Data Contracts');
+
+      expect(apiContractsSection).toBeUndefined();
+    });
+
+    it('only includes outputs that have contract field in Data Contracts section', () => {
+      const dataProduct = createMockDataProduct({
+        outputs: [
+          { id: 'OrdersDB', version: '1.0.0', contract: { path: 'orders-contract.json', name: 'Orders Contract' } },
+          { id: 'PaymentsDB', version: '1.0.0' }, // No contract
+        ],
+      }) as any;
+
+      const context = {
+        ...emptyContext,
+        containers: [createMockContainer('OrdersDB', '1.0.0'), createMockContainer('PaymentsDB', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const apiContractsSection = (result.pages as any[])?.find((p: any) => p.title === 'Data Contracts');
+
+      expect(apiContractsSection).toBeDefined();
+      expect((apiContractsSection as any)?.pages).toHaveLength(1);
+      expect((apiContractsSection as any)?.pages[0]).toMatchObject({
+        type: 'item',
+        title: 'Orders Contract (JSON)',
+        href: '/schemas/data-products/TestDataProduct/1.0.0?contract=orders-contract.json',
+      });
+    });
+
+    it('renders contract without summary when type is not provided', () => {
+      const dataProduct = createMockDataProduct({
+        outputs: [{ id: 'OrdersDB', version: '1.0.0', contract: { path: 'orders-contract.json', name: 'Orders Contract' } }],
+      }) as any;
+
+      const context = {
+        ...emptyContext,
+        containers: [createMockContainer('OrdersDB', '1.0.0')],
+      };
+
+      const result = buildDataProductNode(dataProduct, [], context);
+      const apiContractsSection = result.pages?.find((p: any) => p.title === 'Data Contracts');
+
+      expect((apiContractsSection as any)?.pages[0]).toMatchObject({
+        type: 'item',
+        title: 'Orders Contract (JSON)',
+        summary: undefined,
+      });
+    });
+  });
+
+  describe('flows section', () => {
+    it('renders Flows section when flow references are provided', () => {
+      const dataProduct = createMockDataProduct();
+
+      const result = buildDataProductNode(dataProduct, [], emptyContext, ['flow:CheckoutFlow:1.0.0']);
+      const flowsSection = (result.pages as any[])?.find((p: any) => p.title === 'Appears in flows');
+
+      expect(flowsSection).toMatchObject({
+        type: 'group',
+        title: 'Appears in flows',
+        icon: 'Waypoints',
+        pages: ['flow:CheckoutFlow:1.0.0'],
+      });
+    });
+
+    it('does not render Flows section when no flow references are provided', () => {
+      const dataProduct = createMockDataProduct();
+
+      const result = buildDataProductNode(dataProduct, [], emptyContext);
+      const flowsSection = (result.pages as any[])?.find((p: any) => p.title === 'Appears in flows');
+
+      expect(flowsSection).toBeUndefined();
+    });
+
+    it('does not render Flows section when the data product details panel hides it', () => {
+      const dataProduct = createMockDataProduct({
+        detailsPanel: {
+          flows: {
+            visible: false,
+          },
+        },
+      });
+
+      const result = buildDataProductNode(dataProduct, [], emptyContext, ['flow:CheckoutFlow:1.0.0']);
+      const flowsSection = (result.pages as any[])?.find((p: any) => p.title === 'Appears in flows');
+
+      expect(flowsSection).toBeUndefined();
+    });
+  });
+
+  describe('owners', () => {
+    it('includes Owners section when owners are provided', () => {
+      const dataProduct = createMockDataProduct({ owners: [{ id: 'user1' }] });
+      const owners = [{ id: 'user1', data: { id: 'user1', name: 'User One' }, collection: 'users' }];
+
+      const result = buildDataProductNode(dataProduct, owners as any, emptyContext);
+      const ownersSection = (result.pages as any[])?.find((p: any) => p.title === 'Owners');
+
+      expect(ownersSection).toBeDefined();
+    });
+
+    it('does not include Owners section when no owners are provided', () => {
+      const dataProduct = createMockDataProduct();
+      const result = buildDataProductNode(dataProduct, [], emptyContext);
+
+      const ownersSection = (result.pages as any[])?.find((p: any) => p.title === 'Owners');
+      expect(ownersSection).toBeUndefined();
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/__tests__/entity-builder.spec.ts b/packages/core/eventcatalog/src/stores/sidebar-store/__tests__/entity-builder.spec.ts
new file mode 100644
index 000000000..eb0af2d6c
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/__tests__/entity-builder.spec.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { CollectionEntry } from 'astro:content';
+import { buildEntityNode } from '../builders/entity';
+
+vi.mock('@utils/feature', () => ({
+  isVisualiserEnabled: () => true,
+  isChangelogEnabled: () => false,
+}));
+
+vi.mock('@utils/url-builder', () => ({
+  buildUrl: (path: string) => path,
+}));
+
+const createEntity = (overrides: Partial<CollectionEntry<'entities'>['data']> = {}): CollectionEntry<'entities'> =>
+  ({
+    id: 'entities/Order/index.mdx',
+    collection: 'entities',
+    data: {
+      id: 'Order',
+      name: 'Order',
+      version: '0.0.1',
+      summary: 'Order aggregate',
+      ...overrides,
+    },
+  }) as CollectionEntry<'entities'>;
+
+const createDomain = (id: string, version: string): CollectionEntry<'domains'> =>
+  ({
+    id: `domains/${id}/index.mdx`,
+    collection: 'domains',
+    data: {
+      id,
+      name: id,
+      version,
+    },
+  }) as CollectionEntry<'domains'>;
+
+const emptyContext = {
+  services: [] as CollectionEntry<'services'>[],
+  domains: [] as CollectionEntry<'domains'>[],
+  events: [] as CollectionEntry<'events'>[],
+  commands: [] as CollectionEntry<'commands'>[],
+  queries: [] as CollectionEntry<'queries'>[],
+  flows: [] as CollectionEntry<'flows'>[],
+  containers: [] as CollectionEntry<'containers'>[],
+  dataProducts: [] as CollectionEntry<'data-products'>[],
+  diagrams: [] as CollectionEntry<'diagrams'>[],
+  adrs: [],
+  resourceDocs: [],
+  resourceDocCategories: [],
+};
+
+describe('buildEntityNode', () => {
+  it('adds an Entity Map architecture link when the entity belongs to one domain', () => {
+    const entity = createEntity({
+      domains: [createDomain('Orders', '0.0.1')] as any,
+    });
+
+    const result = buildEntityNode(entity, [], emptyContext);
+    const architectureSection = (result.pages as any[])?.find((page) => page.title === 'Architecture');
+
+    expect(architectureSection).toEqual({
+      type: 'group',
+      title: 'Architecture',
+      icon: 'Workflow',
+      pages: [
+        {
+          type: 'item',
+          title: 'Entity Map',
+          href: '/visualiser/domains/Orders/0.0.1/entity-map',
+        },
+      ],
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/__tests__/sidebar-builder.spec.ts b/packages/core/eventcatalog/src/stores/sidebar-store/__tests__/sidebar-builder.spec.ts
new file mode 100644
index 000000000..4a23325bb
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/__tests__/sidebar-builder.spec.ts
@@ -0,0 +1,4650 @@
+import { describe, it, expect, vi } from 'vitest';
+import { getNestedSideBarData, type NavigationData, type NavNode } from '../state';
+import type { CollectionKey } from 'astro:content';
+import utils from '@eventcatalog/sdk';
+import path from 'path';
+import fs from 'fs';
+import config from '@config';
+
+const CATALOG_FOLDER = path.join(__dirname, 'catalog');
+const mockFlows: any[] = [];
+// NO SDK support for systems yet, so we provide test fixtures directly.
+const mockSystems: any[] = [];
+const mockResourceDocs: any[] = [];
+const mockResourceDocCategories: any[] = [];
+const mockAgents: any[] = [];
+const mockSchemas: any[] = [];
+const mockUbiquitousLanguages: any[] = [];
+
+declare global {
+  interface Window {
+    __EC_TRAILING_SLASH__: boolean;
+  }
+  namespace NodeJS {
+    interface ImportMeta {
+      env: {
+        BASE_URL: string;
+      };
+    }
+  }
+}
+
+declare module 'vitest' {
+  interface Assertion<T = any> {
+    toHaveNavigationLink(expected: { type: 'item' | 'group'; title: string; href: string }): void;
+  }
+  interface AsymmetricMatchersContaining {
+    toHaveNavigationLink(expected: { type: 'item' | 'group'; title: string; href: string }): void;
+  }
+}
+
+const toAstroCollection = (item: any, collection: string) => {
+  return {
+    id: item.id,
+    collection: collection,
+    data: item,
+  };
+};
+
+const getNavigationConfigurationByKey = (key: string, data: NavigationData): NavNode => {
+  return data.nodes[key] as NavNode;
+};
+
+// mock out astro collection for domains
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: async (key: CollectionKey) => {
+      switch (key) {
+        case 'domains':
+          const { getDomains } = utils(CATALOG_FOLDER);
+          const domains = (await getDomains()) ?? [];
+          return Promise.resolve(domains.map((domain) => toAstroCollection(domain, 'domains')));
+        case 'services':
+          const { getServices } = utils(CATALOG_FOLDER);
+          const services = (await getServices()) ?? [];
+          return Promise.resolve(services.map((service) => toAstroCollection(service, 'services')));
+        case 'agents':
+          return Promise.resolve(mockAgents.map((agent) => toAstroCollection(agent, 'agents')));
+        case 'entities':
+          const { getEntities } = utils(CATALOG_FOLDER);
+          const entities = (await getEntities()) ?? [];
+          return Promise.resolve(entities.map((entity) => toAstroCollection(entity, 'entities')));
+        case 'events':
+          const { getEvents } = utils(CATALOG_FOLDER);
+          const events = (await getEvents()) ?? [];
+          return Promise.resolve(events.map((event) => toAstroCollection(event, 'events')));
+        case 'commands':
+          const { getCommands } = utils(CATALOG_FOLDER);
+          const commands = (await getCommands()) ?? [];
+          return Promise.resolve(commands.map((command) => toAstroCollection(command, 'commands')));
+        case 'queries':
+          const { getQueries } = utils(CATALOG_FOLDER);
+          const queries = (await getQueries()) ?? [];
+          return Promise.resolve(queries.map((query) => toAstroCollection(query, 'queries')));
+        case 'containers':
+          const { getDataStores } = utils(CATALOG_FOLDER);
+          const containers = (await getDataStores()) ?? [];
+          return Promise.resolve(containers.map((container) => toAstroCollection(container, 'containers')));
+        case 'users':
+          const { getUsers } = utils(CATALOG_FOLDER);
+          const users = (await getUsers()) ?? [];
+          return Promise.resolve(users.map((user) => toAstroCollection(user, 'users')));
+        case 'teams':
+          const { getTeams } = utils(CATALOG_FOLDER);
+          const teams = (await getTeams()) ?? [];
+          return Promise.resolve(teams.map((team) => toAstroCollection(team, 'teams')));
+        case 'flows':
+          // NO SDK support for flows yet, so we provide test fixtures directly.
+          return Promise.resolve(mockFlows.map((flow) => toAstroCollection(flow, 'flows')));
+        case 'systems':
+          // NO SDK support for systems yet, so we provide test fixtures directly.
+          return Promise.resolve(mockSystems.map((system) => toAstroCollection(system, 'systems')));
+        case 'diagrams':
+          // NO SDK Support for diagrams yet, so we just mock it out for now
+          return Promise.resolve([]);
+        case 'schemas':
+          return Promise.resolve(mockSchemas.map((schema) => toAstroCollection(schema, 'schemas')));
+        case 'channels':
+          const { getChannels } = utils(CATALOG_FOLDER);
+          const channels = (await getChannels()) ?? [];
+          return Promise.resolve(channels.map((channel) => toAstroCollection(channel, 'channels')));
+        case 'data-products':
+          const { getDataProducts } = utils(CATALOG_FOLDER);
+          const dataProducts = (await getDataProducts()) ?? [];
+          return Promise.resolve(dataProducts.map((dataProduct) => toAstroCollection(dataProduct, 'data-products')));
+        case 'ubiquitousLanguages':
+          return Promise.resolve(
+            mockUbiquitousLanguages.map((ubiquitousLanguage) => toAstroCollection(ubiquitousLanguage, 'ubiquitousLanguages'))
+          );
+        case 'resourceDocs':
+          return Promise.resolve(mockResourceDocs);
+        case 'resourceDocCategories':
+          return Promise.resolve(mockResourceDocCategories);
+        default:
+          return Promise.resolve([]);
+      }
+    },
+  };
+});
+
+const buildDomainQuickReferenceSection = (resource: any, includeUbiquitousLanguage = false, includeResources = false) => {
+  return {
+    type: 'group',
+    title: 'Quick Reference',
+    icon: 'BookOpen',
+    pages: [
+      {
+        type: 'item',
+        title: 'Overview',
+        href: `/docs/${resource.collection}/${resource.data.id}/${resource.data.version}`,
+      },
+      includeResources && {
+        type: 'item',
+        title: 'Domain Resources',
+        href: `/docs/domains/${resource.data.id}/${resource.data.version}/resources`,
+      },
+      includeUbiquitousLanguage && {
+        type: 'item',
+        title: 'Ubiquitous Language',
+        href: `/docs/domains/${resource.data.id}/language`,
+      },
+    ].filter(Boolean),
+  };
+};
+
+const getChildNodeByTitle = (title: string, pages: any[]) => {
+  return pages.find((child: any) => child.title === title);
+};
+
+// Find a subtle subsection (e.g. Services / Flows / Entities) nested inside the
+// top-level "Resources" group of a system/domain node.
+const getResourceSubsection = (title: string, pages: any[]) => {
+  const resources = pages.find((child: any) => child.title === 'Resources');
+  return (resources?.pages ?? []).find((child: any) => child.title === title);
+};
+
+expect.extend({
+  toHaveNavigationLink(received: any, expected: any) {
+    const { type, title, href } = expected;
+    const { pages } = received;
+    const allChildren = pages?.flatMap((child: any) => child.pages ?? []);
+    const hasMatch = allChildren.some((child: any) => child.type === type && child.title === title && child.href === href);
+    return {
+      message: () => `expected ${received.title} to have a navigation link to ${expected.title}`,
+      pass: hasMatch,
+    };
+  },
+});
+
+describe('getNestedSideBarData', () => {
+  beforeEach(() => {
+    // @ts-ignore
+    global.__EC_TRAILING_SLASH__ = false;
+    mockFlows.length = 0;
+    mockSystems.length = 0;
+    mockResourceDocs.length = 0;
+    mockResourceDocCategories.length = 0;
+    mockAgents.length = 0;
+    mockSchemas.length = 0;
+    mockUbiquitousLanguages.length = 0;
+    fs.rmSync(CATALOG_FOLDER, { recursive: true, force: true });
+    fs.mkdirSync(CATALOG_FOLDER, { recursive: true });
+    // Remove any navigation data from teh config
+    delete config.navigation;
+    // Reset changelog config
+    delete config.changelog;
+  });
+
+  describe('root navigation items (default navigation config)', () => {
+    it('renders a list of domains (that are not in a subdomain) as a root navigation item', async () => {
+      const { writeDomain, getDomain } = utils(CATALOG_FOLDER);
+
+      await writeDomain({
+        id: 'Shipping',
+        name: 'Shipping',
+        version: '0.0.1',
+        markdown: 'Shipping',
+      });
+
+      const navigationData = await getNestedSideBarData();
+
+      const domain = toAstroCollection(await getDomain('Shipping', '0.0.1'), 'domains');
+      const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+
+      const subdomainSection = getChildNodeByTitle('Subdomains', domainNode.pages ?? []);
+
+      expect(navigationData.roots).toContain('list:top-level-domains');
+      expect(subdomainSection).toBeUndefined();
+
+      expect(domainNode).toEqual(
+        expect.objectContaining({
+          type: 'item',
+          title: 'Shipping',
+          badge: 'Domain',
+          pages: expect.arrayContaining([buildDomainQuickReferenceSection(domain)]),
+        })
+      );
+      // A domain without a custom icon gets no default icon in the sidebar.
+      expect(domainNode.icon).toBeUndefined();
+      expect(domainNode.leftIcon).toBeUndefined();
+    });
+
+    it('renders top-level diagrams with the System Context Map below top-level domains', async () => {
+      const { writeDomain } = utils(CATALOG_FOLDER);
+
+      await writeDomain({
+        id: 'Shipping',
+        name: 'Shipping',
+        version: '0.0.1',
+        markdown: 'Shipping',
+      });
+
+      mockSystems.push({
+        id: 'CoreMonolith',
+        name: 'Core Monolith',
+        version: '1.0.0',
+        summary: 'The legacy core monolith',
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const diagramsNode = getNavigationConfigurationByKey('list:top-level-diagrams', navigationData);
+
+      expect(navigationData.roots).toEqual(['list:top-level-domains', 'list:top-level-diagrams', 'list:all']);
+      expect(diagramsNode).toEqual({
+        type: 'group',
+        title: 'Top level diagrams',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'System Context Map',
+            href: '/visualiser/system-context-map',
+          },
+        ],
+      });
+    });
+
+    it('uses the domain style icon when one is configured', async () => {
+      const { writeDomain } = utils(CATALOG_FOLDER);
+
+      await writeDomain({
+        id: 'Shipping',
+        name: 'Shipping',
+        version: '0.0.1',
+        markdown: 'Shipping',
+        styles: {
+          icon: '/icons/domain.svg',
+        },
+      });
+
+      const navigationData = await getNestedSideBarData();
+
+      expect(getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData)).toEqual(
+        expect.objectContaining({
+          type: 'item',
+          title: 'Shipping',
+          badge: 'Domain',
+          leftIcon: '/icons/domain.svg',
+        })
+      );
+    });
+
+    it('does not render any subdomain as a root navigation item', async () => {
+      const { writeDomain } = utils(CATALOG_FOLDER);
+
+      // Core domain
+      await writeDomain({
+        id: 'Shipping',
+        name: 'Shipping',
+        version: '0.0.1',
+        markdown: 'Shipping',
+        domains: [{ id: 'Checkout', version: '0.0.1' }],
+      });
+
+      // Subdomain
+      await writeDomain({
+        id: 'Checkout',
+        name: 'Checkout',
+        version: '0.0.1',
+        markdown: 'Checkout',
+      });
+
+      const navigationData = await getNestedSideBarData();
+
+      const rootDomainsToRender = getNavigationConfigurationByKey('list:top-level-domains', navigationData);
+      expect(rootDomainsToRender.pages).toEqual(['domain:Shipping:0.0.1']);
+    });
+
+    it('lists the systems that belong to a domain above its subdomains', async () => {
+      const { writeDomain } = utils(CATALOG_FOLDER);
+
+      mockSystems.push({
+        id: 'CoreMonolith',
+        name: 'Core Monolith',
+        version: '1.0.0',
+        summary: 'The legacy core monolith',
+      });
+
+      // `systems` has no SDK support yet, so cast past the SDK's Domain type.
+      await writeDomain({
+        id: 'Shipping',
+        name: 'Shipping',
+        version: '0.0.1',
+        markdown: 'Shipping',
+        systems: [{ id: 'CoreMonolith', version: '1.0.0' }],
+        domains: [{ id: 'Checkout', version: '0.0.1' }],
+      } as any);
+
+      // Subdomain
+      await writeDomain({
+        id: 'Checkout',
+        name: 'Checkout',
+        version: '0.0.1',
+        markdown: 'Checkout',
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+      const pages = domainNode.pages ?? [];
+
+      const systemsSection = getChildNodeByTitle('Systems', pages);
+      expect(systemsSection).toMatchObject({
+        type: 'group',
+        title: 'Systems',
+        icon: 'Group',
+        pages: ['system:CoreMonolith:1.0.0'],
+      });
+
+      // Systems appear above Subdomains
+      const systemsIndex = pages.findIndex((page: any) => page?.title === 'Systems');
+      const subdomainsIndex = pages.findIndex((page: any) => page?.title === 'Subdomains');
+      expect(systemsIndex).toBeGreaterThanOrEqual(0);
+      expect(subdomainsIndex).toBeGreaterThan(systemsIndex);
+    });
+
+    it('the browser section only lists resources that are in the catalog', async () => {
+      const { writeDomain, writeService } = utils(CATALOG_FOLDER);
+      await writeDomain({
+        id: 'Shipping',
+        name: 'Shipping',
+        version: '0.0.1',
+        markdown: 'Shipping',
+      });
+      await writeService({
+        id: 'ShippingService',
+        name: 'ShippingService',
+        version: '0.0.1',
+        markdown: 'ShippingService',
+      });
+      const navigationData = await getNestedSideBarData();
+      const browseNode = getNavigationConfigurationByKey('list:all', navigationData);
+      expect(browseNode.pages).toEqual(['list:domains', 'list:services']);
+    });
+
+    it('leads the browse section with Domains, Systems, Services then Messages before the rest alphabetically', async () => {
+      const { writeDomain, writeService, writeEvent, writeEntity } = utils(CATALOG_FOLDER);
+      await writeDomain({ id: 'Shipping', name: 'Shipping', version: '0.0.1', markdown: 'Shipping' });
+      await writeService({ id: 'ShippingService', name: 'ShippingService', version: '0.0.1', markdown: 'ShippingService' });
+      await writeEvent({ id: 'OrderPlaced', name: 'OrderPlaced', version: '0.0.1', markdown: 'OrderPlaced' });
+      await writeEntity({ id: 'Order', name: 'Order', version: '0.0.1', markdown: 'Order' });
+
+      const navigationData = await getNestedSideBarData();
+      const browseNode = getNavigationConfigurationByKey('list:all', navigationData);
+
+      // Domains, Services and Messages lead in their fixed priority order; the
+      // remainder (here just Entities) follows alphabetically.
+      expect(browseNode.pages).toEqual(['list:domains', 'list:services', 'list:messages', 'list:entities']);
+    });
+
+    it('orders browse resources by name', async () => {
+      const { writeDomain } = utils(CATALOG_FOLDER);
+
+      await writeDomain({
+        id: 'Shipping',
+        name: 'Shipping',
+        version: '0.0.1',
+        markdown: 'Shipping',
+      });
+      await writeDomain({
+        id: 'Payments',
+        name: 'Payments',
+        version: '0.0.1',
+        markdown: 'Payments',
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const domainsList = getNavigationConfigurationByKey('list:domains', navigationData);
+
+      expect(domainsList.pages).toEqual(['domain:Payments:0.0.1', 'domain:Shipping:0.0.1']);
+    });
+
+    it('lists entities as searchable browse resources when they are in the catalog', async () => {
+      const { writeEntity } = utils(CATALOG_FOLDER);
+
+      await writeEntity({
+        id: 'Order',
+        name: 'Order',
+        version: '0.0.1',
+        summary: 'Order aggregate',
+        markdown: 'Order',
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const browseNode = getNavigationConfigurationByKey('list:all', navigationData);
+      const entitiesList = getNavigationConfigurationByKey('list:entities', navigationData);
+      const entityNode = getNavigationConfigurationByKey('entity:Order:0.0.1', navigationData);
+
+      expect(browseNode.pages).toContain('list:entities');
+      expect(entitiesList.pages).toEqual(['entity:Order:0.0.1']);
+      expect(entityNode).toEqual(
+        expect.objectContaining({
+          type: 'item',
+          title: 'Order',
+          badge: 'Entity',
+          summary: 'Order aggregate',
+          pages: expect.arrayContaining([
+            {
+              type: 'group',
+              title: 'Quick Reference',
+              icon: 'BookOpen',
+              pages: [
+                {
+                  type: 'item',
+                  title: 'Overview',
+                  href: '/docs/entities/Order/0.0.1',
+                },
+              ],
+            },
+          ]),
+        })
+      );
+    });
+
+    it('lists systems as searchable browse resources when they are in the catalog', async () => {
+      mockSystems.push({
+        id: 'CoreMonolith',
+        name: 'Core Monolith',
+        version: '1.0.0',
+        summary: 'The legacy core monolith',
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const browseNode = getNavigationConfigurationByKey('list:all', navigationData);
+      const systemsList = getNavigationConfigurationByKey('list:systems', navigationData);
+      const systemNode = getNavigationConfigurationByKey('system:CoreMonolith:1.0.0', navigationData);
+
+      expect(browseNode.pages).toContain('list:systems');
+      expect(systemsList.pages).toEqual(['system:CoreMonolith:1.0.0']);
+      expect(systemNode).toEqual(
+        expect.objectContaining({
+          type: 'item',
+          title: 'Core Monolith',
+          badge: 'System',
+          summary: 'The legacy core monolith',
+          pages: expect.arrayContaining([
+            {
+              type: 'group',
+              title: 'Quick Reference',
+              icon: 'BookOpen',
+              pages: [
+                {
+                  type: 'item',
+                  title: 'Overview',
+                  href: '/docs/systems/CoreMonolith/1.0.0',
+                },
+              ],
+            },
+          ]),
+        })
+      );
+    });
+
+    it('keeps a flat systems list (no scope sub-sections) when all systems are internal', async () => {
+      mockSystems.push(
+        { id: 'CoreMonolith', name: 'Core Monolith', version: '1.0.0', summary: 'Internal by default' },
+        { id: 'Billing', name: 'Billing', version: '1.0.0', scope: 'internal', summary: 'Explicitly internal' }
+      );
+
+      const navigationData = await getNestedSideBarData();
+      const systemsList = getNavigationConfigurationByKey('list:systems', navigationData);
+
+      // No external systems → single flat list, ordered by name.
+      expect(systemsList.pages).toEqual(['system:Billing:1.0.0', 'system:CoreMonolith:1.0.0']);
+    });
+
+    it('splits the systems list into Internal and External sub-sections (each ordered by name)', async () => {
+      mockSystems.push(
+        { id: 'CoreMonolith', name: 'Core Monolith', version: '1.0.0', summary: 'Internal (default scope)' },
+        { id: 'Identity', name: 'Identity', version: '1.0.0', scope: 'internal', summary: 'Internal' },
+        { id: 'Resend', name: 'Resend', version: '1.0.0', scope: 'external', summary: 'External SaaS' },
+        { id: 'Stripe', name: 'Stripe', version: '1.0.0', scope: 'external', summary: 'External SaaS' }
+      );
+
+      const navigationData = await getNestedSideBarData();
+      const systemsList = getNavigationConfigurationByKey('list:systems', navigationData);
+      const internalList = getNavigationConfigurationByKey('list:systems-internal', navigationData);
+      const externalList = getNavigationConfigurationByKey('list:systems-external', navigationData);
+
+      // Top-level Systems item points at the two scope sub-sections.
+      expect(systemsList.pages).toEqual(['list:systems-internal', 'list:systems-external']);
+
+      // Internal section: systems with scope internal (or unset), ordered by name.
+      expect(internalList).toEqual(
+        expect.objectContaining({
+          type: 'group',
+          title: 'Internal',
+          pages: ['system:CoreMonolith:1.0.0', 'system:Identity:1.0.0'],
+        })
+      );
+
+      // External section: systems with scope external, ordered by name.
+      expect(externalList).toEqual(
+        expect.objectContaining({
+          type: 'group',
+          title: 'External',
+          pages: ['system:Resend:1.0.0', 'system:Stripe:1.0.0'],
+        })
+      );
+    });
+
+    it('lists the services that belong to a system', async () => {
+      const { writeService } = utils(CATALOG_FOLDER);
+
+      await writeService({
+        id: 'OrdersService',
+        name: 'Orders Service',
+        version: '1.0.0',
+        summary: 'Handles orders',
+        markdown: 'Orders Service',
+      });
+
+      mockSystems.push({
+        id: 'CoreMonolith',
+        name: 'Core Monolith',
+        version: '1.0.0',
+        summary: 'The legacy core monolith',
+        services: [{ id: 'OrdersService', version: '1.0.0' }],
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const systemNode = getNavigationConfigurationByKey('system:CoreMonolith:1.0.0', navigationData);
+
+      const servicesSection = getResourceSubsection('Services', systemNode.pages ?? []);
+      expect(servicesSection).toMatchObject({
+        type: 'group',
+        title: 'Services',
+        icon: 'Server',
+        pages: ['service:OrdersService:1.0.0'],
+      });
+
+      // A system with resources gets the System Resources quick-reference link.
+      const quickReference = getChildNodeByTitle('Quick Reference', systemNode.pages ?? []);
+      expect(quickReference.pages).toContainEqual({
+        type: 'item',
+        title: 'System Resources',
+        href: '/docs/systems/CoreMonolith/1.0.0/resources',
+      });
+    });
+
+    it('lists an Architecture section with Overview and Resource Diagram links for the system', async () => {
+      mockSystems.push({
+        id: 'CoreMonolith',
+        name: 'Core Monolith',
+        version: '1.0.0',
+        summary: 'The legacy core monolith',
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const systemNode = getNavigationConfigurationByKey('system:CoreMonolith:1.0.0', navigationData);
+      const architectureSection = getChildNodeByTitle('Architecture', systemNode.pages ?? []);
+
+      expect(architectureSection).toEqual({
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Overview',
+            href: '/architecture/systems/CoreMonolith/1.0.0',
+          },
+          {
+            type: 'item',
+            title: 'Resource Diagram',
+            href: '/visualiser/systems/CoreMonolith/1.0.0',
+          },
+        ],
+      });
+    });
+
+    it('lists the flows that belong to a system', async () => {
+      mockFlows.push({
+        id: 'CheckoutFlow',
+        name: 'Checkout Flow',
+        version: '1.0.0',
+        markdown: 'Checkout Flow',
+        steps: [],
+      });
+
+      mockSystems.push({
+        id: 'CoreMonolith',
+        name: 'Core Monolith',
+        version: '1.0.0',
+        summary: 'The legacy core monolith',
+        flows: [{ id: 'CheckoutFlow', version: '1.0.0' }],
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const systemNode = getNavigationConfigurationByKey('system:CoreMonolith:1.0.0', navigationData);
+
+      const flowsSection = getResourceSubsection('Flows', systemNode.pages ?? []);
+      expect(flowsSection).toMatchObject({
+        type: 'group',
+        title: 'Flows',
+        icon: 'Waypoints',
+        pages: ['flow:CheckoutFlow:1.0.0'],
+      });
+    });
+
+    it('lists the entities that belong to a system', async () => {
+      const { writeEntity } = utils(CATALOG_FOLDER);
+
+      await writeEntity({
+        id: 'Order',
+        name: 'Order',
+        version: '1.0.0',
+        markdown: 'Order',
+      });
+
+      mockSystems.push({
+        id: 'CoreMonolith',
+        name: 'Core Monolith',
+        version: '1.0.0',
+        summary: 'The legacy core monolith',
+        entities: [{ id: 'Order', version: '1.0.0' }],
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const systemNode = getNavigationConfigurationByKey('system:CoreMonolith:1.0.0', navigationData);
+
+      const entitiesSection = getChildNodeByTitle('Entities', systemNode.pages ?? []);
+      expect(entitiesSection).toMatchObject({
+        type: 'group',
+        title: 'Entities',
+        icon: 'Box',
+        pages: [{ type: 'item', title: 'Order', href: '/docs/entities/Order/1.0.0' }],
+      });
+    });
+  });
+
+  describe('entity navigation item', () => {
+    it('lists the domains and services that reference the entity', async () => {
+      const { writeDomain, writeEntity, writeService } = utils(CATALOG_FOLDER);
+
+      await writeEntity({
+        id: 'Order',
+        name: 'Order',
+        version: '0.0.1',
+        markdown: 'Order',
+      });
+
+      await writeDomain({
+        id: 'Shipping',
+        name: 'Shipping',
+        version: '0.0.1',
+        markdown: 'Shipping',
+        entities: [{ id: 'Order', version: '0.0.1' }],
+      });
+
+      await writeService({
+        id: 'OrdersService',
+        name: 'OrdersService',
+        version: '0.0.1',
+        markdown: 'OrdersService',
+        entities: [{ id: 'Order', version: '0.0.1' }],
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const entityNode = getNavigationConfigurationByKey('entity:Order:0.0.1', navigationData);
+      const architectureSection = getChildNodeByTitle('Architecture', entityNode.pages ?? []);
+      const domainsSection = getChildNodeByTitle('Domains', entityNode.pages ?? []);
+      const servicesSection = getChildNodeByTitle('Services', entityNode.pages ?? []);
+
+      expect(architectureSection).toEqual({
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Domain Entity Map',
+            href: '/visualiser/domains/Shipping/0.0.1/entity-map',
+          },
+          {
+            type: 'item',
+            title: 'Service Entity Map',
+            href: '/visualiser/services/OrdersService/0.0.1/entity-map',
+          },
+        ],
+      });
+      expect(domainsSection).toEqual({
+        type: 'group',
+        title: 'Domains',
+        icon: 'Boxes',
+        pages: ['domain:Shipping:0.0.1'],
+      });
+      expect(servicesSection).toEqual({
+        type: 'group',
+        title: 'Services',
+        icon: 'Server',
+        pages: ['service:OrdersService:0.0.1'],
+      });
+    });
+  });
+
+  describe('domain navigation item', () => {
+    it('users can reference the latest version of a resource without passing in the version', async () => {
+      const { writeDomain } = utils(CATALOG_FOLDER);
+      await writeDomain({
+        id: 'Shipping',
+        name: 'Shipping',
+        version: '0.0.1',
+        markdown: 'Shipping',
+      });
+      const navigationData = await getNestedSideBarData();
+      const domainNode = getNavigationConfigurationByKey('domain:Shipping', navigationData);
+      expect(domainNode).toBeDefined();
+    });
+
+    describe('quick reference section', () => {
+      it('the overview link is always listed in the navigation item', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+
+        expect(domainNode).toHaveNavigationLink({ type: 'item', title: 'Overview', href: '/docs/domains/Shipping/0.0.1' });
+      });
+
+      it('the ubiquitous language link is listed when terms are defined', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+        mockUbiquitousLanguages.push({
+          dictionary: [
+            {
+              id: 'Shipment',
+              name: 'Shipment',
+              summary: 'Goods prepared for delivery',
+            },
+          ],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+
+        expect(domainNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Ubiquitous Language',
+          href: '/docs/domains/Shipping/language',
+        });
+      });
+
+      it('the ubiquitous language link is not listed when no terms are defined', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+
+        expect(domainNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Ubiquitous Language',
+          href: '/docs/domains/Shipping/language',
+        });
+      });
+
+      it('the ubiquitous language link is not listed if the domain is configured not to render the page', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          detailsPanel: {
+            ubiquitousLanguage: {
+              visible: false,
+            },
+          },
+        });
+        mockUbiquitousLanguages.push({
+          dictionary: [
+            {
+              id: 'Shipment',
+              name: 'Shipment',
+              summary: 'Goods prepared for delivery',
+            },
+          ],
+        });
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        expect(domainNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Ubiquitous Language',
+          href: '/docs/domains/Shipping/language',
+        });
+      });
+
+      it('the changelog link is listed when changelog is enabled', async () => {
+        config.changelog = { enabled: true };
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        expect(domainNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Changelog',
+          href: '/docs/domains/Shipping/0.0.1/changelog',
+        });
+        config.changelog = { enabled: false };
+      });
+
+      it('the changelog link is not listed when changelog is disabled', async () => {
+        config.changelog = { enabled: false };
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        expect(domainNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Changelog',
+          href: '/docs/domains/Shipping/0.0.1/changelog',
+        });
+      });
+
+      it('the changelog link is not listed when the domain is configured to hide it', async () => {
+        config.changelog = { enabled: true };
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          detailsPanel: {
+            changelog: {
+              visible: false,
+            },
+          },
+        });
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        expect(domainNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Changelog',
+          href: '/docs/domains/Shipping/0.0.1/changelog',
+        });
+        config.changelog = { enabled: false };
+      });
+    });
+
+    describe('Architecture section', () => {
+      it('lists the Overview and Resource Diagram links when the domain has resources to draw', async () => {
+        const { writeDomain, writeService } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          services: [{ id: 'ShippingService', version: '0.0.1' }],
+        });
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        expect(domainNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Resource Diagram',
+          href: '/visualiser/domains/Shipping/0.0.1',
+        });
+        expect(domainNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Overview',
+          href: '/architecture/domains/Shipping/0.0.1',
+        });
+      });
+
+      it('does not list the Resource Diagram link when the domain has no resources to draw', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        expect(domainNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Resource Diagram',
+          href: '/visualiser/domains/Shipping/0.0.1',
+        });
+        // The Architecture Overview link is always present.
+        expect(domainNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Overview',
+          href: '/architecture/domains/Shipping/0.0.1',
+        });
+      });
+
+      it('the visualizer link is not displayed if the visualizer is turned off in the catalog configuration', async () => {
+        // Globally set the visualizer to be disabled in the EventCatalog configuration
+        config.visualiser.enabled = false;
+
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        expect(domainNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Resource Diagram',
+          href: '/visualiser/domains/Shipping/0.0.1',
+        });
+
+        // Turn it back on
+        config.visualiser.enabled = true;
+      });
+
+      it('the entity diagram link is only listed if the domain has entities', async () => {
+        const { writeDomain, writeEntity } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          entities: [{ id: 'Order', version: '0.0.1' }],
+        });
+        await writeEntity({
+          id: 'Order',
+          name: 'Order',
+          version: '0.0.1',
+          markdown: 'Order',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        expect(domainNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Entity Diagram',
+          href: '/visualiser/domains/Shipping/0.0.1/entity-map',
+        });
+      });
+
+      it('lists a Diagrams section if the domain has diagrams', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          diagrams: [{ id: 'system-architecture', version: '1.0.0' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const diagramsSection = getChildNodeByTitle('Diagrams', domainNode.pages ?? []);
+
+        expect(diagramsSection).toBeDefined();
+        expect(diagramsSection.pages).toEqual([
+          { type: 'item', title: 'system-architecture', href: '/diagrams/system-architecture/1.0.0' },
+        ]);
+      });
+
+      it('does not list a Diagrams section if the domain does not have any diagrams', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const diagramsSection = getChildNodeByTitle('Diagrams', domainNode.pages ?? []);
+
+        expect(diagramsSection).toBeUndefined();
+      });
+    });
+
+    describe('Flows section', () => {
+      it('is not listed if the domain does not have any flows', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const flowsSection = getResourceSubsection('Flows', domainNode.pages ?? []);
+        expect(flowsSection).toBeUndefined();
+      });
+    });
+
+    describe('entities section', () => {
+      it('if a domain has entities, the entities section is listed in the navigation item', async () => {
+        const { writeDomain, writeEntity } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          entities: [{ id: 'Order', version: '0.0.1' }],
+        });
+
+        await writeEntity({
+          id: 'Order',
+          name: 'Order',
+          version: '0.0.1',
+          markdown: 'Order',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const entitiesSection = getResourceSubsection('Entities', domainNode.pages ?? []);
+        expect(entitiesSection.pages).toEqual([{ type: 'item', title: 'Order', href: '/docs/entities/Order/0.0.1' }]);
+      });
+
+      it('is not listed if the domain is configured not to render the section', async () => {
+        const { writeDomain, writeEntity } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          entities: [{ id: 'Order', version: '0.0.1' }],
+          detailsPanel: {
+            entities: {
+              visible: false,
+            },
+          },
+        });
+
+        await writeEntity({
+          id: 'Order',
+          name: 'Order',
+          version: '0.0.1',
+          markdown: 'Order',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const entitiesSection = getResourceSubsection('Entities', domainNode.pages ?? []);
+        expect(entitiesSection).toBeUndefined();
+      });
+
+      it('is not listed if the domain does not have any entities', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const entitiesSection = getResourceSubsection('Entities', domainNode.pages ?? []);
+        expect(entitiesSection).toBeUndefined();
+      });
+    });
+
+    describe('subdomains section', () => {
+      it('is not listed if the domain does not have any subdomains', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        expect(domainNode.pages).not.toContain('list:subdomains');
+      });
+
+      it('is not listed if the domain is configured not to render the section', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          domains: [{ id: 'Checkout', version: '0.0.1' }],
+          detailsPanel: {
+            subdomains: {
+              visible: false,
+            },
+          },
+        });
+
+        await writeDomain({
+          id: 'Checkout',
+          name: 'Checkout',
+          version: '0.0.1',
+          markdown: 'Checkout',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const subdomainSection = getChildNodeByTitle('Subdomains', domainNode.pages ?? []);
+        expect(subdomainSection).toBeUndefined();
+      });
+
+      it('lists subdomains if the domain has subdomains', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          domains: [{ id: 'Checkout', version: '0.0.1' }],
+        });
+
+        await writeDomain({
+          id: 'Checkout',
+          name: 'Checkout',
+          version: '0.0.1',
+          markdown: 'Checkout',
+          domains: [{ id: 'Shipping', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const subdomainSection = getChildNodeByTitle('Subdomains', domainNode.pages ?? []);
+        expect(subdomainSection.pages).toEqual(['domain:Checkout:0.0.1']);
+      });
+    });
+
+    describe('resource group section', () => {
+      it('is not listed if the domain does not have any resource groups', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const resourceGroupSection = getChildNodeByTitle('Resource Groups', domainNode.pages ?? []);
+        expect(resourceGroupSection).toBeUndefined();
+      });
+
+      // it.only('if it defines a resource group, these resources are returned', async () => {
+
+      //   const { writeDomain } = utils(CATALOG_FOLDER);
+      //   await writeDomain({
+      //     id: 'Shipping',
+      //     name: 'Shipping',
+      //     version: '0.0.1',
+      //     markdown: 'Shipping',
+      //     resourceGroups: [{
+      //       id: 'ShippingResourceGroup',
+      //       title: 'Shipping Resource Group',
+      //       items: [{ id: 'ShippingResource', version: '0.0.1' }],
+      //     }],
+      //   });
+
+      //   const navigationData = await getNestedSideBarData();
+      //   const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+      //   const resourceGroupSection = getChildNodeByTitle('Resource Groups', domainNode.pages ?? []);
+      //   expect(resourceGroupSection).toBeDefined();
+
+      // });
+    });
+
+    describe('services section', () => {
+      it('does not render any services for the domain if the domain does not have any services', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const servicesInDomainSection = getChildNodeByTitle('Services in Domain', domainNode.pages ?? []);
+        expect(servicesInDomainSection).toBeUndefined();
+      });
+
+      it('is not listed if the domain is configured not to render the section', async () => {
+        const { writeDomain, writeService } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          services: [{ id: 'ShippingService', version: '0.0.1' }],
+          detailsPanel: {
+            services: {
+              visible: false,
+            },
+          },
+        });
+
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const servicesInDomainSection = getResourceSubsection('Services', domainNode.pages ?? []);
+        expect(servicesInDomainSection).toBeUndefined();
+      });
+
+      it('renders services for the domain if the domain has services', async () => {
+        const { writeDomain, writeService } = utils(CATALOG_FOLDER);
+
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          services: [{ id: 'ShippingService', version: '0.0.1' }],
+          domains: [{ id: 'Checkout', version: '0.0.1' }],
+        });
+
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'LocationService',
+        });
+
+        // We create a subdomain that also has services, that should not be listed in the `Services in Domain` section
+        await writeDomain({
+          id: 'Checkout',
+          name: 'Checkout',
+          version: '0.0.1',
+          markdown: 'Checkout',
+          services: [{ id: 'CheckoutService', version: '0.0.1' }],
+        });
+
+        await writeService({
+          id: 'CheckoutService',
+          name: 'CheckoutService',
+          version: '0.0.1',
+          markdown: 'CheckoutService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const servicesInDomainSection = getResourceSubsection('Services', domainNode.pages ?? []);
+
+        expect(servicesInDomainSection.pages).toEqual(['service:ShippingService:0.0.1']);
+      });
+    });
+
+    describe('external systems', () => {
+      it('renders an "External Integrations" section in a domain with services that have externalSystem: true, and excludes them from "Services In Domain"', async () => {
+        const { writeDomain, writeService } = utils(CATALOG_FOLDER);
+
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          services: [
+            { id: 'ShippingService', version: '0.0.1' },
+            { id: 'Stripe', version: '1.0.0' },
+          ],
+        });
+
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        await writeService({
+          id: 'Stripe',
+          name: 'Stripe',
+          version: '1.0.0',
+          markdown: 'Stripe',
+          externalSystem: true,
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+
+        const servicesInDomainSection = getResourceSubsection('Services', domainNode.pages ?? []);
+        const externalIntegrationsSection = getChildNodeByTitle('External Integrations', domainNode.pages ?? []);
+
+        expect(servicesInDomainSection.pages).toEqual(['service:ShippingService:0.0.1']);
+        expect(externalIntegrationsSection).toEqual(
+          expect.objectContaining({
+            type: 'group',
+            title: 'External Integrations',
+            icon: 'Globe',
+            pages: ['service:Stripe:1.0.0'],
+          })
+        );
+      });
+
+      it('renders a separate "list:external-systems" root node and excludes externals from "list:services"', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        await writeService({
+          id: 'Stripe',
+          name: 'Stripe',
+          version: '1.0.0',
+          markdown: 'Stripe',
+          externalSystem: true,
+        });
+
+        const navigationData = await getNestedSideBarData();
+
+        const servicesList = getNavigationConfigurationByKey('list:services', navigationData);
+        const externalSystemsList = getNavigationConfigurationByKey('list:external-systems', navigationData);
+
+        expect(servicesList.pages).toEqual(['service:ShippingService:0.0.1']);
+        expect(externalSystemsList).toEqual(
+          expect.objectContaining({
+            type: 'item',
+            title: 'External Systems',
+            icon: 'Globe',
+            pages: ['service:Stripe:1.0.0'],
+          })
+        );
+      });
+
+      it('renders the per-service nav item with badge "External System" when externalSystem is true', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+
+        await writeService({
+          id: 'Stripe',
+          name: 'Stripe',
+          version: '1.0.0',
+          markdown: 'Stripe',
+          externalSystem: true,
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:Stripe:1.0.0', navigationData);
+
+        expect(serviceNode).toEqual(
+          expect.objectContaining({
+            type: 'item',
+            title: 'Stripe',
+            badge: 'External System',
+          })
+        );
+      });
+    });
+
+    describe('owners section', () => {
+      it('is not listed if the domain does not have any owners', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+      });
+
+      it('is not listed if the domain is configured not to render the section', async () => {
+        const { writeDomain, writeUser } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          owners: ['John Doe'],
+          detailsPanel: {
+            owners: {
+              visible: false,
+            },
+          },
+        });
+
+        await writeUser({
+          id: 'John Doe',
+          name: 'John Doe',
+          markdown: 'John Doe',
+          avatarUrl: 'https://example.com/avatar.png',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const ownersSection = getChildNodeByTitle('Owners', domainNode.pages ?? []);
+        expect(ownersSection).toBeUndefined();
+      });
+
+      it('lists the owners that the domain has if the domain has owners', async () => {
+        const { writeDomain, writeUser } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          owners: ['John Doe'],
+        });
+
+        await writeUser({
+          id: 'John Doe',
+          name: 'John Doe',
+          markdown: 'John Doe',
+          avatarUrl: 'https://example.com/avatar.png',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const ownersSection = getChildNodeByTitle('Owners', domainNode.pages ?? []);
+        expect(ownersSection.pages).toEqual([{ type: 'item', title: 'John Doe', href: '/docs/users/John Doe' }]);
+      });
+    });
+
+    describe('code section', () => {
+      it('is not listed if the domain does not have a repository configured', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const codeSection = getChildNodeByTitle('Code', domainNode.pages ?? []);
+        expect(codeSection).toBeUndefined();
+      });
+
+      it('is not listed if the domain is configured not to render the section', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          repository: {
+            url: 'https://github.com/eventcatalog/eventcatalog',
+            language: 'TypeScript',
+          },
+          detailsPanel: {
+            repository: {
+              visible: false,
+            },
+          },
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const codeSection = getChildNodeByTitle('Code', domainNode.pages ?? []);
+        expect(codeSection).toBeUndefined();
+      });
+
+      it('lists the code repository if the domain has a repository configured', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          repository: {
+            url: 'https://github.com/eventcatalog/eventcatalog',
+            language: 'TypeScript',
+          },
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const codeSection = getChildNodeByTitle('Code', domainNode.pages ?? []);
+        expect(codeSection).toBeDefined();
+      });
+    });
+
+    describe('attachments section', () => {
+      it('is not listed if the domain does not have any attachments', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+      });
+
+      it('lists the attachments if the domain has attachments configured', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          repository: {
+            url: 'https://github.com/eventcatalog/eventcatalog',
+            language: 'TypeScript',
+          },
+          attachments: [
+            {
+              url: 'https://example.com/attachment.pdf',
+              title: 'Attachment 1',
+              type: 'pdf',
+            },
+          ],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const attachmentsSection = getChildNodeByTitle('Attachments', domainNode.pages ?? []);
+        expect(attachmentsSection).toBeDefined();
+        expect(attachmentsSection.pages).toEqual([
+          {
+            type: 'item',
+            title: 'Attachment 1',
+            href: 'https://example.com/attachment.pdf',
+          },
+        ]);
+      });
+    });
+
+    describe('API & Contracts section (domain)', () => {
+      it('is not listed if the domain does not have any specifications', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const apiContractsSection = getChildNodeByTitle('API & Contracts', domainNode.pages ?? []);
+        expect(apiContractsSection).toBeUndefined();
+      });
+
+      it('is not listed if the domain is configured not to render the section', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        // SDK update required to support specifications on domains
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          detailsPanel: {
+            specifications: {
+              visible: false,
+            },
+          } as any,
+          specifications: [{ type: 'openapi', path: 'openapi.yaml', name: 'OpenAPI' }],
+        } as any);
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const apiContractsSection = getChildNodeByTitle('API & Contracts', domainNode.pages ?? []);
+        expect(apiContractsSection).toBeUndefined();
+      });
+
+      it('lists the specifications that the domain has if the domain has specifications', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        // SDK update required to support specifications on domains
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          specifications: [
+            { type: 'openapi', path: 'openapi.yaml', name: 'OpenAPI' },
+            { type: 'asyncapi', path: 'asyncapi.yaml', name: 'AsyncAPI' },
+            { type: 'graphql', path: 'graphql.yaml', name: 'GraphQL' },
+          ],
+        } as any);
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const apiContractsSection = getChildNodeByTitle('API & Contracts', domainNode.pages ?? []);
+        expect(apiContractsSection.pages).toEqual([
+          {
+            type: 'item',
+            title: 'OpenAPI',
+            leftIcon: '/icons/openapi-black.svg',
+            href: '/docs/domains/Shipping/0.0.1/spec/openapi',
+          },
+          {
+            type: 'item',
+            title: 'AsyncAPI',
+            leftIcon: '/icons/asyncapi-black.svg',
+            href: '/docs/domains/Shipping/0.0.1/asyncapi/asyncapi',
+          },
+          {
+            type: 'item',
+            title: 'GraphQL',
+            leftIcon: '/icons/graphql-black.svg',
+            href: '/docs/domains/Shipping/0.0.1/graphql/graphql',
+          },
+        ]);
+      });
+    });
+
+    describe('domain events section (sends)', () => {
+      it('is not listed if the domain does not send any messages', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const domainEventsSection = getResourceSubsection('Domain Events', domainNode.pages ?? []);
+        expect(domainEventsSection).toBeUndefined();
+      });
+
+      it('is not listed if the domain is configured not to render the section', async () => {
+        const { writeDomain, writeEvent } = utils(CATALOG_FOLDER);
+
+        await writeEvent({
+          id: 'OrderShipped',
+          name: 'Order Shipped',
+          version: '0.0.1',
+          markdown: 'Order Shipped',
+        });
+
+        // SDK update required to support sends/receives on domains
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          detailsPanel: {
+            messages: {
+              visible: false,
+            },
+          },
+          sends: [{ id: 'OrderShipped', version: '0.0.1' }],
+        } as any);
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const domainEventsSection = getResourceSubsection('Domain Events', domainNode.pages ?? []);
+        expect(domainEventsSection).toBeUndefined();
+      });
+
+      it('lists the messages that the domain sends if the domain sends messages', async () => {
+        const { writeDomain, writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'OrderShipped',
+          name: 'Order Shipped',
+          version: '0.0.1',
+          markdown: 'Order Shipped',
+        });
+
+        // SDK update required to support sends/receives on domains
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          sends: [{ id: 'OrderShipped', version: '0.0.1' }],
+        } as any);
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const domainEventsSection = getResourceSubsection('Domain Events', domainNode.pages ?? []);
+        expect(domainEventsSection.pages).toEqual(['event:OrderShipped:0.0.1']);
+      });
+    });
+
+    describe('external events section (receives)', () => {
+      it('is not listed if the domain does not receive any messages', async () => {
+        const { writeDomain } = utils(CATALOG_FOLDER);
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const externalEventsSection = getResourceSubsection('External Events', domainNode.pages ?? []);
+        expect(externalEventsSection).toBeUndefined();
+      });
+
+      it('is not listed if the domain is configured not to render the section', async () => {
+        const { writeDomain, writeEvent } = utils(CATALOG_FOLDER);
+
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        // SDK update required to support sends/receives on domains
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          detailsPanel: {
+            messages: {
+              visible: false,
+            },
+          },
+          receives: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        } as any);
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const externalEventsSection = getResourceSubsection('External Events', domainNode.pages ?? []);
+        expect(externalEventsSection).toBeUndefined();
+      });
+
+      it('lists the messages that the domain receives if the domain receives messages', async () => {
+        const { writeDomain, writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        // SDK update required to support sends/receives on domains
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+          receives: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        } as any);
+
+        const navigationData = await getNestedSideBarData();
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const externalEventsSection = getResourceSubsection('External Events', domainNode.pages ?? []);
+        expect(externalEventsSection.pages).toEqual(['event:PaymentProcessed:0.0.1']);
+      });
+    });
+  });
+
+  describe('service navigation items', () => {
+    it('users can reference the latest version of a resource without passing in the version', async () => {
+      const { writeService } = utils(CATALOG_FOLDER);
+      await writeService({
+        id: 'ShippingService',
+        name: 'ShippingService',
+        version: '0.0.1',
+        markdown: 'ShippingService',
+      });
+      const navigationData = await getNestedSideBarData();
+      const serviceNode = getNavigationConfigurationByKey('service:ShippingService', navigationData);
+      expect(serviceNode).toBeDefined();
+    });
+
+    describe('quick reference section', () => {
+      it('the overview link is always listed in the navigation item', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        expect(serviceNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Overview',
+          href: '/docs/services/ShippingService/0.0.1',
+        });
+      });
+
+      it('the changelog link is listed when changelog is enabled', async () => {
+        config.changelog = { enabled: true };
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        expect(serviceNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Changelog',
+          href: '/docs/services/ShippingService/0.0.1/changelog',
+        });
+        config.changelog = { enabled: false };
+      });
+
+      it('the changelog link is not listed when changelog is disabled', async () => {
+        config.changelog = { enabled: false };
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        expect(serviceNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Changelog',
+          href: '/docs/services/ShippingService/0.0.1/changelog',
+        });
+      });
+
+      it('the changelog link is not listed when the service is configured to hide it', async () => {
+        config.changelog = { enabled: true };
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          detailsPanel: {
+            changelog: {
+              visible: false,
+            },
+          },
+        });
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        expect(serviceNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Changelog',
+          href: '/docs/services/ShippingService/0.0.1/changelog',
+        });
+        config.changelog = { enabled: false };
+      });
+    });
+
+    describe('Architecture section', () => {
+      it('the architecture overview and visualizer links are always listed in the navigation item', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        expect(serviceNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Overview',
+          href: '/architecture/services/ShippingService/0.0.1',
+        });
+        expect(serviceNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Map',
+          href: '/visualiser/services/ShippingService/0.0.1',
+        });
+      });
+
+      it('the map link is not displayed if the visualizer is turned off in the catalog configuration', async () => {
+        // Globally set the visualizer to be disabled in the EventCatalog configuration
+        config.visualiser.enabled = false;
+
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        expect(serviceNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Map',
+          href: '/visualiser/services/ShippingService/0.0.1',
+        });
+
+        // Turn it back on
+        config.visualiser.enabled = true;
+      });
+
+      it('lists a Diagrams section if the service has diagrams', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          diagrams: [{ id: 'service-architecture', version: '1.0.0' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const diagramsSection = getChildNodeByTitle('Diagrams', serviceNode.pages ?? []);
+
+        expect(diagramsSection).toBeDefined();
+        expect(diagramsSection.pages).toEqual([
+          { type: 'item', title: 'service-architecture', href: '/diagrams/service-architecture/1.0.0' },
+        ]);
+      });
+
+      it('does not list a Diagrams section if the service does not have any diagrams', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const diagramsSection = getChildNodeByTitle('Diagrams', serviceNode.pages ?? []);
+
+        expect(diagramsSection).toBeUndefined();
+      });
+    });
+
+    describe('API & Contracts section', () => {
+      it('is not listed if the service does not have any specifications', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const apiContractsSection = getChildNodeByTitle('API & Contracts', serviceNode.pages ?? []);
+        expect(apiContractsSection).toBeUndefined();
+      });
+
+      it('is not listed if the service is configured not to render the section', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          detailsPanel: {
+            specifications: {
+              visible: false,
+            },
+          },
+          specifications: [{ type: 'openapi', path: 'openapi.yaml', name: 'OpenAPI' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const apiContractsSection = getChildNodeByTitle('API & Contracts', serviceNode.pages ?? []);
+        expect(apiContractsSection).toBeUndefined();
+      });
+
+      it('lists the specifications that the service has if the service has specifications', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          specifications: [
+            { type: 'openapi', path: 'openapi.yaml', name: 'OpenAPI' },
+            { type: 'asyncapi', path: 'asyncapi.yaml', name: 'AsyncAPI' },
+            { type: 'graphql', path: 'graphql.yaml', name: 'GraphQL' },
+          ],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const apiContractsSection = getChildNodeByTitle('API & Contracts', serviceNode.pages ?? []);
+        expect(apiContractsSection.pages).toEqual([
+          {
+            type: 'item',
+            title: 'OpenAPI',
+            leftIcon: '/icons/openapi-black.svg',
+            href: '/docs/services/ShippingService/0.0.1/spec/openapi',
+          },
+          {
+            type: 'item',
+            title: 'AsyncAPI',
+            leftIcon: '/icons/asyncapi-black.svg',
+            href: '/docs/services/ShippingService/0.0.1/asyncapi/asyncapi',
+          },
+          {
+            type: 'item',
+            title: 'GraphQL',
+            leftIcon: '/icons/graphql-black.svg',
+            href: '/docs/services/ShippingService/0.0.1/graphql/graphql',
+          },
+        ]);
+      });
+    });
+
+    describe('State and Persistence section', () => {
+      it('is not listed if the service does not have any data stores it reads from or writes to', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const stateAndPersistenceSection = getChildNodeByTitle('State and Persistence', serviceNode.pages ?? []);
+        expect(stateAndPersistenceSection).toBeUndefined();
+      });
+
+      it('lists the data stores that the service reads from and writes to if the service has data stores it reads from or writes to', async () => {
+        const { writeService, writeDataStore } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          readsFrom: [{ id: 'Order', version: '0.0.1' }],
+          writesTo: [{ id: 'Order', version: '0.0.1' }],
+        });
+
+        await writeDataStore({
+          id: 'Order',
+          name: 'Order',
+          version: '0.0.1',
+          markdown: 'Order',
+          container_type: 'database',
+          technology: 'PostgreSQL',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const stateAndPersistenceSection = getChildNodeByTitle('State and Persistence', serviceNode.pages ?? []);
+        expect(stateAndPersistenceSection.pages).toEqual(['container:Order:0.0.1']);
+      });
+    });
+
+    describe('entities section', () => {
+      it('is not listed if the service does not have any entities', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+      });
+
+      it('is not listed if the service is configured not to render the section', async () => {
+        const { writeService, writeEntity } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          detailsPanel: {
+            entities: {
+              visible: false,
+            },
+          },
+          entities: [{ id: 'Order', version: '0.0.1' }],
+        });
+
+        await writeEntity({
+          id: 'Order',
+          name: 'Order',
+          version: '0.0.1',
+          markdown: 'Order',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const entitiesSection = getChildNodeByTitle('Entities', serviceNode.pages ?? []);
+        expect(entitiesSection).toBeUndefined();
+      });
+
+      it('lists the entities that the service has if the service has entities', async () => {
+        const { writeService, writeEntity } = utils(CATALOG_FOLDER);
+        await writeEntity({
+          id: 'Order',
+          name: 'Order',
+          version: '0.0.1',
+          markdown: 'Order',
+        });
+
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          entities: [{ id: 'Order', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const entitiesSection = getChildNodeByTitle('Entities', serviceNode.pages ?? []);
+        expect(entitiesSection.pages).toEqual([{ type: 'item', title: 'Order', href: '/docs/entities/Order/0.0.1' }]);
+      });
+    });
+
+    describe('sends messages section', () => {
+      it('is not listed if the service does not send any messages', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const producesMessagesSection = getChildNodeByTitle('Outbound Messages', serviceNode.pages ?? []);
+        expect(producesMessagesSection).toBeUndefined();
+      });
+
+      it('is not listed if the service is configured not to render the section', async () => {
+        const { writeService, writeEvent } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          detailsPanel: {
+            messages: {
+              visible: false,
+            },
+          },
+          sends: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        });
+
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const producesMessagesSection = getChildNodeByTitle('Outbound Messages', serviceNode.pages ?? []);
+        expect(producesMessagesSection).toBeUndefined();
+      });
+
+      it('lists the messages that the service sends if the service sends messages', async () => {
+        const { writeService, writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          sends: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const producesMessagesSection = getChildNodeByTitle('Outbound Messages', serviceNode.pages ?? []);
+        expect(producesMessagesSection.pages).toEqual(['event:PaymentProcessed:0.0.1']);
+      });
+    });
+
+    describe('receives messages section', () => {
+      it('is not listed if the service does not receive any messages', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const receivesMessagesSection = getChildNodeByTitle('Inbound Messages', serviceNode.pages ?? []);
+        expect(receivesMessagesSection).toBeUndefined();
+      });
+
+      it('is not listed if the service is configured not to render the section', async () => {
+        const { writeService, writeEvent } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          detailsPanel: {
+            messages: {
+              visible: false,
+            },
+          },
+          receives: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        });
+
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const receivesMessagesSection = getChildNodeByTitle('Inbound Messages', serviceNode.pages ?? []);
+        expect(receivesMessagesSection).toBeUndefined();
+      });
+
+      it('lists the messages that the service consumes if the service consumes messages', async () => {
+        const { writeService, writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          receives: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const receivesMessagesSection = getChildNodeByTitle('Inbound Messages', serviceNode.pages ?? []);
+        expect(receivesMessagesSection.pages).toEqual(['event:PaymentProcessed:0.0.1']);
+      });
+    });
+
+    describe('flows section', () => {
+      it('is not listed if the service has no flows and no flows reference the service', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Appears in flows', serviceNode.pages ?? []);
+        expect(flowsSection).toBeUndefined();
+      });
+
+      it('lists flows that reference the service in flow steps', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '0.0.1',
+          markdown: 'Payment Service',
+        });
+
+        mockFlows.push({
+          id: 'CheckoutFlow',
+          name: 'Checkout Flow',
+          version: '0.0.1',
+          markdown: 'Checkout Flow',
+          steps: [{ id: 'payment-service', title: 'Payment service', service: { id: 'PaymentService' } }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:PaymentService:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Appears in flows', serviceNode.pages ?? []);
+
+        expect(flowsSection.pages).toEqual(['flow:CheckoutFlow:0.0.1']);
+      });
+
+      it('merges explicit service flows with flows that reference the service and removes duplicates', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '0.0.1',
+          markdown: 'Payment Service',
+          flows: [{ id: 'CheckoutFlow', version: '0.0.1' }, { id: 'FraudFlow' }],
+        });
+
+        mockFlows.push(
+          {
+            id: 'CheckoutFlow',
+            name: 'Checkout Flow',
+            version: '0.0.1',
+            markdown: 'Checkout Flow',
+            steps: [{ id: 'payment-service', title: 'Payment service', service: { id: 'PaymentService' } }],
+          },
+          {
+            id: 'FraudFlow',
+            name: 'Fraud Flow',
+            version: '0.0.1',
+            markdown: 'Fraud Flow',
+            steps: [],
+          }
+        );
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:PaymentService:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Flows', serviceNode.pages ?? []);
+
+        expect(flowsSection.pages).toEqual(['flow:CheckoutFlow:0.0.1', 'flow:FraudFlow:0.0.1']);
+      });
+    });
+
+    describe('owners section', () => {
+      it('is not listed if the service does not have any owners', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+      });
+
+      it('is not listed if the service is configured not to render the section', async () => {
+        const { writeService, writeUser } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          detailsPanel: {
+            owners: {
+              visible: false,
+            },
+          },
+          owners: ['John Doe'],
+        });
+
+        writeUser({
+          id: 'John Doe',
+          name: 'John Doe',
+          markdown: 'John Doe',
+          avatarUrl: 'https://example.com/avatar.png',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const ownersSection = getChildNodeByTitle('Owners', serviceNode.pages ?? []);
+        expect(ownersSection).toBeUndefined();
+      });
+
+      it('lists the owners that the service has if the service has owners', async () => {
+        const { writeService, writeUser } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          owners: ['John Doe'],
+        });
+
+        await writeUser({
+          id: 'John Doe',
+          name: 'John Doe',
+          markdown: 'John Doe',
+          avatarUrl: 'https://example.com/avatar.png',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const ownersSection = getChildNodeByTitle('Owners', serviceNode.pages ?? []);
+        expect(ownersSection.pages).toEqual([{ type: 'item', title: 'John Doe', href: '/docs/users/John Doe' }]);
+      });
+    });
+
+    describe('repository section', () => {
+      it('is not listed if the service does not have a repository', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const repositorySection = getChildNodeByTitle('Code', serviceNode.pages ?? []);
+        expect(repositorySection).toBeUndefined();
+      });
+
+      it('is not listed if the service is configured not to render the section', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          detailsPanel: {
+            repository: {
+              visible: false,
+            },
+          },
+          repository: {
+            url: 'https://github.com/eventcatalog/eventcatalog',
+            language: 'TypeScript',
+          },
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const repositorySection = getChildNodeByTitle('Code', serviceNode.pages ?? []);
+        expect(repositorySection).toBeUndefined();
+      });
+
+      it('lists the repository if the service has a repository configured', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          repository: {
+            url: 'https://github.com/eventcatalog/eventcatalog',
+            language: 'TypeScript',
+          },
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const repositorySection = getChildNodeByTitle('Code', serviceNode.pages ?? []);
+        expect(repositorySection).toBeDefined();
+      });
+    });
+
+    describe('attachments section', () => {
+      it('is not listed if the service does not have any attachments', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'Shipping',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+        });
+      });
+
+      it('lists the attachments if the service has attachments configured', async () => {
+        const { writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          attachments: [
+            {
+              url: 'https://example.com/attachment.pdf',
+              title: 'Attachment 1',
+              type: 'pdf',
+            },
+          ],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const attachmentsSection = getChildNodeByTitle('Attachments', serviceNode.pages ?? []);
+        expect(attachmentsSection).toBeDefined();
+        expect(attachmentsSection.pages).toEqual([
+          {
+            type: 'item',
+            title: 'Attachment 1',
+            href: 'https://example.com/attachment.pdf',
+          },
+        ]);
+      });
+    });
+  });
+
+  describe('agent navigation items', () => {
+    describe('Architecture section', () => {
+      it('lists the visualizer map but not an architecture overview page', async () => {
+        mockAgents.push({
+          id: 'FraudReviewAgent',
+          name: 'Fraud Review Agent',
+          version: '0.0.1',
+          markdown: 'Fraud Review Agent',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const agentNode = getNavigationConfigurationByKey('agent:FraudReviewAgent:0.0.1', navigationData);
+
+        expect(agentNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Overview',
+          href: '/architecture/agents/FraudReviewAgent/0.0.1',
+        });
+        expect(agentNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Map',
+          href: '/visualiser/agents/FraudReviewAgent/0.0.1',
+        });
+      });
+    });
+  });
+
+  describe('message navigation items', () => {
+    it('users can reference the latest version of a resource without passing in the version', async () => {
+      const { writeEvent } = utils(CATALOG_FOLDER);
+      await writeEvent({
+        id: 'PaymentProcessed',
+        name: 'Payment Processed',
+        version: '0.0.1',
+        markdown: 'Payment Processed',
+      });
+      const navigationData = await getNestedSideBarData();
+      const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed', navigationData);
+      expect(messageNode).toBeDefined();
+    });
+
+    describe('quick reference section', () => {
+      it('the overview link is always listed in the navigation item', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Overview',
+          href: '/docs/events/PaymentProcessed/0.0.1',
+        });
+      });
+
+      it('the changelog link is listed when changelog is enabled', async () => {
+        config.changelog = { enabled: true };
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Changelog',
+          href: '/docs/events/PaymentProcessed/0.0.1/changelog',
+        });
+        config.changelog = { enabled: false };
+      });
+
+      it('the changelog link is not listed when changelog is disabled', async () => {
+        config.changelog = { enabled: false };
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Changelog',
+          href: '/docs/events/PaymentProcessed/0.0.1/changelog',
+        });
+      });
+
+      it('the changelog link is not listed when the message is configured to hide it', async () => {
+        config.changelog = { enabled: true };
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          detailsPanel: {
+            changelog: {
+              visible: false,
+            },
+          },
+        });
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Changelog',
+          href: '/docs/events/PaymentProcessed/0.0.1/changelog',
+        });
+        config.changelog = { enabled: false };
+      });
+    });
+
+    describe('API & Contracts section', () => {
+      it('lists a schema link when the message has a resolved schema entry', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          schemas: [{ ref: 'git://contracts/events/PaymentProcessed.schema.json' }],
+        });
+        mockSchemas.push({
+          id: 'git://contracts/events/PaymentProcessed.schema.json',
+          ref: 'git://contracts/events/PaymentProcessed.schema.json',
+          format: 'jsonschema',
+          source: { provider: 'git', path: 'events/PaymentProcessed.schema.json' },
+          message: { collection: 'events', id: 'PaymentProcessed', version: '0.0.1' },
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Schema (JSON)',
+          href: '/schemas/events/PaymentProcessed/0.0.1',
+        });
+      });
+
+      it('does not list a schema link when declared schemas are not resolved', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          schemas: [{ ref: 'git://contracts/events/Missing.schema.json' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Schema (JSON)',
+          href: '/schemas/events/PaymentProcessed/0.0.1',
+        });
+      });
+
+      it('uses a generic schemas label when the message has multiple resolved schemas', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          schemas: [
+            { ref: 'git://contracts/events/PaymentProcessed.schema.json' },
+            { ref: 'git://contracts/events/PaymentProcessed.schema.avsc' },
+          ],
+        });
+        mockSchemas.push(
+          {
+            id: 'git://contracts/events/PaymentProcessed.schema.json',
+            ref: 'git://contracts/events/PaymentProcessed.schema.json',
+            format: 'jsonschema',
+            source: { provider: 'git', path: 'events/PaymentProcessed.schema.json' },
+            message: { collection: 'events', id: 'PaymentProcessed', version: '0.0.1' },
+          },
+          {
+            id: 'git://contracts/events/PaymentProcessed.schema.avsc',
+            ref: 'git://contracts/events/PaymentProcessed.schema.avsc',
+            format: 'avro',
+            source: { provider: 'git', path: 'events/PaymentProcessed.schema.avsc' },
+            message: { collection: 'events', id: 'PaymentProcessed', version: '0.0.1' },
+          }
+        );
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Schemas',
+          href: '/schemas/events/PaymentProcessed/0.0.1',
+        });
+      });
+    });
+
+    describe('architecture & design section', () => {
+      it('the visualizer link is always listed in the navigation item', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Map',
+          href: '/visualiser/events/PaymentProcessed/0.0.1',
+        });
+      });
+
+      it('the visalizer link is not displayed if the visualizer is turned off in the catalog configuration', async () => {
+        // Globally set the visualizer to be disabled in the EventCatalog configuration
+        config.visualiser.enabled = false;
+
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Map',
+          href: '/visualiser/events/PaymentProcessed/0.0.1',
+        });
+
+        // Turn it back on
+        config.visualiser.enabled = true;
+      });
+    });
+
+    describe('field usage section', () => {
+      it('the field usage link is shown when a service declares fields for the message', async () => {
+        const { writeEvent, writeService } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          schemaPath: 'schema.json',
+        });
+        mockSchemas.push({
+          id: 'schema:events:PaymentProcessed:0.0.1:schema.json',
+          format: 'jsonschema',
+          file: 'schema.json',
+          source: { provider: 'file', path: 'schema.json' },
+          message: { collection: 'events', id: 'PaymentProcessed', version: '0.0.1' },
+        });
+        await writeService({
+          id: 'ShippingService',
+          name: 'Shipping Service',
+          version: '0.0.1',
+          markdown: 'Shipping Service',
+          receives: [{ id: 'PaymentProcessed', version: '0.0.1', fields: ['orderId', 'amount'] }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Field Usage',
+          href: '/docs/events/PaymentProcessed/0.0.1/field-lineage',
+        });
+      });
+
+      it('the field usage link is shown when the message declares schemas', async () => {
+        const { writeEvent, writeService } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          schemas: [{ ref: 'git://contracts/events/PaymentProcessed.schema.json' }],
+        });
+        mockSchemas.push({
+          id: 'git://contracts/events/PaymentProcessed.schema.json',
+          ref: 'git://contracts/events/PaymentProcessed.schema.json',
+          format: 'jsonschema',
+          source: { provider: 'git', path: 'events/PaymentProcessed.schema.json' },
+          message: { collection: 'events', id: 'PaymentProcessed', version: '0.0.1' },
+        });
+        await writeService({
+          id: 'ShippingService',
+          name: 'Shipping Service',
+          version: '0.0.1',
+          markdown: 'Shipping Service',
+          receives: [{ id: 'PaymentProcessed', version: '0.0.1', fields: ['orderId', 'amount'] }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Field Usage',
+          href: '/docs/events/PaymentProcessed/0.0.1/field-lineage',
+        });
+      });
+
+      it('the field usage link is not shown when no service declares fields for the message', async () => {
+        const { writeEvent, writeService } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          schemaPath: 'schema.json',
+        });
+        await writeService({
+          id: 'ShippingService',
+          name: 'Shipping Service',
+          version: '0.0.1',
+          markdown: 'Shipping Service',
+          receives: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Field Usage',
+          href: '/docs/events/PaymentProcessed/0.0.1/field-lineage',
+        });
+      });
+
+      it('the field usage link is not shown when the message has no schema', async () => {
+        const { writeEvent, writeService } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+        await writeService({
+          id: 'ShippingService',
+          name: 'Shipping Service',
+          version: '0.0.1',
+          markdown: 'Shipping Service',
+          receives: [{ id: 'PaymentProcessed', version: '0.0.1', fields: ['orderId', 'amount'] }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        expect(messageNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Field Usage',
+          href: '/docs/events/PaymentProcessed/0.0.1/field-lineage',
+        });
+      });
+
+      it('the field usage link is shown when a service declares fields in its sends for the message', async () => {
+        const { writeEvent, writeService } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.0',
+          markdown: 'Inventory Adjusted',
+          schemaPath: 'schema.json',
+        });
+        mockSchemas.push({
+          id: 'schema:events:InventoryAdjusted:1.0.0:schema.json',
+          format: 'jsonschema',
+          file: 'schema.json',
+          source: { provider: 'file', path: 'schema.json' },
+          message: { collection: 'events', id: 'InventoryAdjusted', version: '1.0.0' },
+        });
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          markdown: 'Inventory Service',
+          sends: [{ id: 'InventoryAdjusted', version: '1.0.0', fields: ['productId', 'quantity'] }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:InventoryAdjusted:1.0.0', navigationData);
+        expect(messageNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Field Usage',
+          href: '/docs/events/InventoryAdjusted/1.0.0/field-lineage',
+        });
+      });
+    });
+
+    describe('producers section', () => {
+      it('is not listed if the no services produce the message', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const producesMessagesSection = getChildNodeByTitle('Producers', messageNode.pages ?? []);
+        expect(producesMessagesSection).toBeUndefined();
+      });
+
+      it('is not listed if the message is configured not to render the section', async () => {
+        const { writeEvent, writeService } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          detailsPanel: {
+            producers: {
+              visible: false,
+            },
+          },
+        });
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '0.0.1',
+          markdown: 'Payment Service',
+          sends: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const producesMessagesSection = getChildNodeByTitle('Producers', messageNode.pages ?? []);
+        expect(producesMessagesSection).toBeUndefined();
+      });
+
+      it('lists the producers if the message is produced by any services', async () => {
+        const { writeEvent, writeService } = utils(CATALOG_FOLDER);
+
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '0.0.1',
+          markdown: 'Payment Service',
+          sends: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        });
+
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const producesMessagesSection = getChildNodeByTitle('Producers', messageNode.pages ?? []);
+        expect(producesMessagesSection.pages).toEqual(['service:PaymentService:0.0.1']);
+      });
+
+      it('lists agent producers with agent sidebar references', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+
+        mockAgents.push({
+          id: 'FraudReviewAgent',
+          name: 'Fraud Review Agent',
+          version: '0.0.1',
+          sends: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        });
+
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const producesMessagesSection = getChildNodeByTitle('Producers', messageNode.pages ?? []);
+        expect(producesMessagesSection.pages).toEqual(['agent:FraudReviewAgent:0.0.1']);
+      });
+    });
+
+    describe('consumers section', () => {
+      it('is not listed if the no services consume the message', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const consumersSection = getChildNodeByTitle('Consumers', messageNode.pages ?? []);
+        expect(consumersSection).toBeUndefined();
+      });
+
+      it('is not listed if the message is configured not to render the section', async () => {
+        const { writeEvent, writeService } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          detailsPanel: {
+            consumers: {
+              visible: false,
+            },
+          },
+        });
+
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          receives: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const consumersSection = getChildNodeByTitle('Consumers', messageNode.pages ?? []);
+        expect(consumersSection).toBeUndefined();
+      });
+
+      it('lists the consumers if the message is consumed by any services', async () => {
+        const { writeEvent, writeService } = utils(CATALOG_FOLDER);
+        await writeService({
+          id: 'ShippingService',
+          name: 'ShippingService',
+          version: '0.0.1',
+          markdown: 'ShippingService',
+          receives: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        });
+
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const consumersSection = getChildNodeByTitle('Consumers', messageNode.pages ?? []);
+        expect(consumersSection.pages).toEqual(['service:ShippingService:0.0.1']);
+      });
+
+      it('lists agent consumers with agent sidebar references', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+
+        mockAgents.push({
+          id: 'FraudReviewAgent',
+          name: 'Fraud Review Agent',
+          version: '0.0.1',
+          receives: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+        });
+
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const consumersSection = getChildNodeByTitle('Consumers', messageNode.pages ?? []);
+        expect(consumersSection.pages).toEqual(['agent:FraudReviewAgent:0.0.1']);
+      });
+    });
+
+    describe('flows section', () => {
+      it('is not listed if no flows reference the message', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Appears in flows', messageNode.pages ?? []);
+        expect(flowsSection).toBeUndefined();
+      });
+
+      it('lists flows that reference event, command, and query messages', async () => {
+        const { writeEvent, writeCommand, writeQuery } = utils(CATALOG_FOLDER);
+
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+        await writeCommand({
+          id: 'ReserveInventory',
+          name: 'Reserve Inventory',
+          version: '0.0.1',
+          markdown: 'Reserve Inventory',
+        });
+        await writeQuery({
+          id: 'GetPaymentStatus',
+          name: 'Get Payment Status',
+          version: '0.0.1',
+          markdown: 'Get Payment Status',
+        });
+
+        mockFlows.push({
+          id: 'CheckoutFlow',
+          name: 'Checkout Flow',
+          version: '0.0.1',
+          markdown: 'Checkout Flow',
+          steps: [
+            { id: 'payment-processed', title: 'Payment processed', message: { id: 'PaymentProcessed' } },
+            { id: 'reserve-inventory', title: 'Reserve inventory', message: { id: 'ReserveInventory', version: '0.0.1' } },
+            { id: 'get-payment-status', title: 'Get payment status', message: { id: 'GetPaymentStatus' } },
+          ],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const eventNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const commandNode = getNavigationConfigurationByKey('command:ReserveInventory:0.0.1', navigationData);
+        const queryNode = getNavigationConfigurationByKey('query:GetPaymentStatus:0.0.1', navigationData);
+
+        expect(getChildNodeByTitle('Appears in flows', eventNode.pages ?? []).pages).toEqual(['flow:CheckoutFlow:0.0.1']);
+        expect(getChildNodeByTitle('Appears in flows', commandNode.pages ?? []).pages).toEqual(['flow:CheckoutFlow:0.0.1']);
+        expect(getChildNodeByTitle('Appears in flows', queryNode.pages ?? []).pages).toEqual(['flow:CheckoutFlow:0.0.1']);
+      });
+
+      it('deduplicates flows when multiple steps reference the same message', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        mockFlows.push({
+          id: 'CheckoutFlow',
+          name: 'Checkout Flow',
+          version: '0.0.1',
+          markdown: 'Checkout Flow',
+          steps: [
+            { id: 'payment-processed-1', title: 'Payment processed', message: { id: 'PaymentProcessed' } },
+            { id: 'payment-processed-2', title: 'Payment processed again', message: { id: 'PaymentProcessed' } },
+          ],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Appears in flows', messageNode.pages ?? []);
+
+        expect(flowsSection.pages).toEqual(['flow:CheckoutFlow:0.0.1']);
+      });
+    });
+
+    describe('owners section', () => {
+      it('is not listed if the message does not have any owners', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+      });
+
+      it('is not listed if the message is configured not to render the section', async () => {
+        const { writeEvent, writeUser } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+        await writeUser({
+          id: 'John Doe',
+          name: 'John Doe',
+          markdown: 'John Doe',
+          avatarUrl: 'https://example.com/avatar.png',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const ownersSection = getChildNodeByTitle('Owners', messageNode.pages ?? []);
+        expect(ownersSection).toBeUndefined();
+      });
+
+      it('lists the owners that the message has if the message has owners', async () => {
+        const { writeEvent, writeUser } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          owners: ['John Doe'],
+        });
+
+        await writeUser({
+          id: 'John Doe',
+          name: 'John Doe',
+          markdown: 'John Doe',
+          avatarUrl: 'https://example.com/avatar.png',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const ownersSection = getChildNodeByTitle('Owners', messageNode.pages ?? []);
+        expect(ownersSection.pages).toEqual([{ type: 'item', title: 'John Doe', href: '/docs/users/John Doe' }]);
+      });
+    });
+
+    describe('repository section', () => {
+      it('is not listed if the message does not have a repository', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const repositorySection = getChildNodeByTitle('Code', messageNode.pages ?? []);
+        expect(repositorySection).toBeUndefined();
+      });
+
+      it('is not listed if the message is configured not to render the section', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          detailsPanel: {
+            repository: {
+              visible: false,
+            },
+          },
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const repositorySection = getChildNodeByTitle('Code', messageNode.pages ?? []);
+        expect(repositorySection).toBeUndefined();
+      });
+
+      it('lists the repository if the message has a repository', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          repository: {
+            url: 'https://github.com/eventcatalog/eventcatalog',
+            language: 'TypeScript',
+          },
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const repositorySection = getChildNodeByTitle('Code', messageNode.pages ?? []);
+        expect(repositorySection).toBeDefined();
+      });
+    });
+
+    describe('attachments section', () => {
+      it('is not listed if the message does not have any attachments', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const attachmentsSection = getChildNodeByTitle('Attachments', messageNode.pages ?? []);
+        expect(attachmentsSection).toBeUndefined();
+      });
+
+      it('lists the attachments if the message has attachments configured', async () => {
+        const { writeEvent } = utils(CATALOG_FOLDER);
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+          attachments: [
+            {
+              url: 'https://example.com/attachment.pdf',
+              title: 'Attachment 1',
+              type: 'pdf',
+            },
+          ],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const attachmentsSection = getChildNodeByTitle('Attachments', messageNode.pages ?? []);
+        expect(attachmentsSection).toBeDefined();
+        expect(attachmentsSection.pages).toEqual([
+          {
+            type: 'item',
+            title: 'Attachment 1',
+            href: 'https://example.com/attachment.pdf',
+          },
+        ]);
+      });
+    });
+  });
+
+  describe('container navigation items', () => {
+    it('users can reference the latest version of a resource without passing in the version', async () => {
+      const { writeDataStore } = utils(CATALOG_FOLDER);
+      await writeDataStore({
+        id: 'PaymentDataStore',
+        name: 'Payment DataStore',
+        version: '0.0.1',
+        markdown: 'Payment DataStore',
+        container_type: 'database',
+      });
+      const navigationData = await getNestedSideBarData();
+      const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore', navigationData);
+      expect(containerNode).toBeDefined();
+    });
+
+    describe('quick reference section', () => {
+      it('the overview link is always listed in the navigation item', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        expect(containerNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Overview',
+          href: '/docs/containers/PaymentDataStore/0.0.1',
+        });
+      });
+
+      it('the changelog link is listed when changelog is enabled', async () => {
+        config.changelog = { enabled: true };
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        expect(containerNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Changelog',
+          href: '/docs/containers/PaymentDataStore/0.0.1/changelog',
+        });
+        config.changelog = { enabled: false };
+      });
+
+      it('the changelog link is not listed when changelog is disabled', async () => {
+        config.changelog = { enabled: false };
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        expect(containerNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Changelog',
+          href: '/docs/containers/PaymentDataStore/0.0.1/changelog',
+        });
+      });
+
+      it('the changelog link is not listed when the container is configured to hide it', async () => {
+        config.changelog = { enabled: true };
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+          detailsPanel: {
+            changelog: {
+              visible: false,
+            },
+          },
+        });
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        expect(containerNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Changelog',
+          href: '/docs/containers/PaymentDataStore/0.0.1/changelog',
+        });
+        config.changelog = { enabled: false };
+      });
+    });
+
+    describe('architecture & design section', () => {
+      it('the visualizer link is always listed in the navigation item', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        expect(containerNode).toHaveNavigationLink({
+          type: 'item',
+          title: 'Map',
+          href: '/visualiser/containers/PaymentDataStore/0.0.1',
+        });
+      });
+
+      it('the visualizer link is not displayed if the visualizer is turned off in the catalog configuration', async () => {
+        // Globally set the visualizer to be disabled in the EventCatalog configuration
+        config.visualiser.enabled = false;
+
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        expect(containerNode).not.toHaveNavigationLink({
+          type: 'item',
+          title: 'Map',
+          href: '/visualiser/containers/PaymentDataStore/0.0.1',
+        });
+
+        // Turn it back on
+        config.visualiser.enabled = true;
+      });
+    });
+
+    describe('writes section', () => {
+      it('is not listed if the container does not have any services or data products that write to it', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const writesSection = getChildNodeByTitle('Writes', containerNode.pages ?? []);
+        expect(writesSection).toBeUndefined();
+      });
+
+      it('is not listed if the container is configured not to render the section', async () => {
+        const { writeDataStore, writeService } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+          detailsPanel: {
+            // @ts-ignore
+            services: {
+              visible: false,
+            },
+          },
+        });
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '0.0.1',
+          markdown: 'Payment Service',
+          writesTo: [{ id: 'PaymentDataStore', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const writesSection = getChildNodeByTitle('Writes', containerNode.pages ?? []);
+        expect(writesSection).toBeUndefined();
+      });
+
+      it('lists the services that write to the container', async () => {
+        const { writeDataStore, writeService } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '0.0.1',
+          markdown: 'Payment Service',
+          writesTo: [{ id: 'PaymentDataStore', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const writesSection = getChildNodeByTitle('Writes', containerNode.pages ?? []);
+        expect(writesSection.pages).toContain('service:PaymentService:0.0.1');
+      });
+
+      it('lists the data products that write to the container (have it as output)', async () => {
+        const { writeDataStore, writeDataProduct } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        await writeDataProduct({
+          id: 'PaymentPipeline',
+          name: 'Payment Pipeline',
+          version: '0.0.1',
+          markdown: 'Payment Pipeline',
+          outputs: [{ id: 'PaymentDataStore', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const writesSection = getChildNodeByTitle('Writes', containerNode.pages ?? []);
+        expect(writesSection.pages).toContain('data-product:PaymentPipeline:0.0.1');
+      });
+
+      it('lists both services and data products that write to the container', async () => {
+        const { writeDataStore, writeService, writeDataProduct } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '0.0.1',
+          markdown: 'Payment Service',
+          writesTo: [{ id: 'PaymentDataStore', version: '0.0.1' }],
+        });
+
+        await writeDataProduct({
+          id: 'PaymentPipeline',
+          name: 'Payment Pipeline',
+          version: '0.0.1',
+          markdown: 'Payment Pipeline',
+          outputs: [{ id: 'PaymentDataStore', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const writesSection = getChildNodeByTitle('Writes', containerNode.pages ?? []);
+        expect(writesSection.pages).toContain('service:PaymentService:0.0.1');
+        expect(writesSection.pages).toContain('data-product:PaymentPipeline:0.0.1');
+      });
+    });
+
+    describe('reads section', () => {
+      it('is not listed if the container does not have any services or data products that read from it', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const readsSection = getChildNodeByTitle('Reads', containerNode.pages ?? []);
+        expect(readsSection).toBeUndefined();
+      });
+
+      it('is not listed if the container is configured not to render the section', async () => {
+        const { writeDataStore, writeService } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+          detailsPanel: {
+            // @ts-ignore
+            services: {
+              visible: false,
+            },
+          },
+        });
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '0.0.1',
+          markdown: 'Payment Service',
+          readsFrom: [{ id: 'PaymentDataStore', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const readsSection = getChildNodeByTitle('Reads', containerNode.pages ?? []);
+        expect(readsSection).toBeUndefined();
+      });
+
+      it('lists the services that read from the container', async () => {
+        const { writeDataStore, writeService } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '0.0.1',
+          markdown: 'Payment Service',
+          readsFrom: [{ id: 'PaymentDataStore', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const readsSection = getChildNodeByTitle('Reads', containerNode.pages ?? []);
+        expect(readsSection.pages).toContain('service:PaymentService:0.0.1');
+      });
+
+      it('lists the data products that read from the container (have it as input)', async () => {
+        const { writeDataStore, writeDataProduct } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        await writeDataProduct({
+          id: 'PaymentAnalytics',
+          name: 'Payment Analytics',
+          version: '0.0.1',
+          markdown: 'Payment Analytics',
+          inputs: [{ id: 'PaymentDataStore', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const readsSection = getChildNodeByTitle('Reads', containerNode.pages ?? []);
+        expect(readsSection.pages).toContain('data-product:PaymentAnalytics:0.0.1');
+      });
+
+      it('lists both services and data products that read from the container', async () => {
+        const { writeDataStore, writeService, writeDataProduct } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '0.0.1',
+          markdown: 'Payment Service',
+          readsFrom: [{ id: 'PaymentDataStore', version: '0.0.1' }],
+        });
+
+        await writeDataProduct({
+          id: 'PaymentAnalytics',
+          name: 'Payment Analytics',
+          version: '0.0.1',
+          markdown: 'Payment Analytics',
+          inputs: [{ id: 'PaymentDataStore', version: '0.0.1' }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const readsSection = getChildNodeByTitle('Reads', containerNode.pages ?? []);
+        expect(readsSection.pages).toContain('service:PaymentService:0.0.1');
+        expect(readsSection.pages).toContain('data-product:PaymentAnalytics:0.0.1');
+      });
+    });
+
+    describe('flows section', () => {
+      it('is not listed if no flows reference the container', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Appears in flows', containerNode.pages ?? []);
+        expect(flowsSection).toBeUndefined();
+      });
+
+      it('lists flows that reference the container in flow steps', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        mockFlows.push({
+          id: 'CheckoutFlow',
+          name: 'Checkout Flow',
+          version: '0.0.1',
+          markdown: 'Checkout Flow',
+          steps: [{ id: 'payments-db', title: 'Payments DB', container: { id: 'PaymentDataStore' } }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Appears in flows', containerNode.pages ?? []);
+
+        expect(flowsSection.pages).toEqual(['flow:CheckoutFlow:0.0.1']);
+      });
+
+      it('deduplicates flows when multiple steps reference the same container', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        mockFlows.push({
+          id: 'CheckoutFlow',
+          name: 'Checkout Flow',
+          version: '0.0.1',
+          markdown: 'Checkout Flow',
+          steps: [
+            { id: 'payments-db-read', title: 'Read Payments DB', container: { id: 'PaymentDataStore' } },
+            { id: 'payments-db-write', title: 'Write Payments DB', container: { id: 'PaymentDataStore', version: '0.0.1' } },
+          ],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Appears in flows', containerNode.pages ?? []);
+
+        expect(flowsSection.pages).toEqual(['flow:CheckoutFlow:0.0.1']);
+      });
+
+      it('is not listed if the container is configured not to render the section', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+          detailsPanel: {
+            // @ts-ignore
+            flows: {
+              visible: false,
+            },
+          },
+        });
+
+        mockFlows.push({
+          id: 'CheckoutFlow',
+          name: 'Checkout Flow',
+          version: '0.0.1',
+          markdown: 'Checkout Flow',
+          steps: [{ id: 'payments-db', title: 'Payments DB', container: { id: 'PaymentDataStore' } }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Appears in flows', containerNode.pages ?? []);
+        expect(flowsSection).toBeUndefined();
+      });
+    });
+
+    describe('owners section', () => {
+      it('is not listed if the container does not have any owners', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const ownersSection = getChildNodeByTitle('Owners', containerNode.pages ?? []);
+        expect(ownersSection).toBeUndefined();
+      });
+
+      it('is not listed if the container is configured not to render the section', async () => {
+        const { writeDataStore, writeUser } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+          owners: ['John Doe'],
+          detailsPanel: {
+            owners: {
+              visible: false,
+            },
+          },
+        });
+        await writeUser({
+          id: 'John Doe',
+          name: 'John Doe',
+          markdown: 'John Doe',
+          avatarUrl: 'https://example.com/avatar.png',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const ownersSection = getChildNodeByTitle('Owners', containerNode.pages ?? []);
+        expect(ownersSection).toBeUndefined();
+      });
+
+      it('lists the owners that the container has if the container has owners', async () => {
+        const { writeDataStore, writeUser } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+          owners: ['John Doe'],
+        });
+
+        await writeUser({
+          id: 'John Doe',
+          name: 'John Doe',
+          markdown: 'John Doe',
+          avatarUrl: 'https://example.com/avatar.png',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const ownersSection = getChildNodeByTitle('Owners', containerNode.pages ?? []);
+        expect(ownersSection.pages).toEqual([{ type: 'item', title: 'John Doe', href: '/docs/users/John Doe' }]);
+      });
+    });
+
+    describe('repository section', () => {
+      it('is not listed if the container does not have a repository', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const repositorySection = getChildNodeByTitle('Code', containerNode.pages ?? []);
+        expect(repositorySection).toBeUndefined();
+      });
+    });
+
+    describe('repository section', () => {
+      it('is not listed if the container is configured not to render the section', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+          detailsPanel: {
+            repository: {
+              visible: false,
+            },
+          },
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const repositorySection = getChildNodeByTitle('Code', containerNode.pages ?? []);
+        expect(repositorySection).toBeUndefined();
+      });
+
+      it('lists the repository if the container has a repository', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+          repository: {
+            url: 'https://github.com/eventcatalog/eventcatalog',
+            language: 'TypeScript',
+          },
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+
+        const repositorySection = getChildNodeByTitle('Code', containerNode.pages ?? []);
+
+        expect(repositorySection).toBeDefined();
+        expect(repositorySection.pages).toEqual([
+          {
+            type: 'item',
+            title: 'https://github.com/eventcatalog/eventcatalog',
+            href: 'https://github.com/eventcatalog/eventcatalog',
+          },
+        ]);
+      });
+    });
+
+    describe('attachments section', () => {
+      it('is not listed if the container does not have any attachments', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const attachmentsSection = getChildNodeByTitle('Attachments', containerNode.pages ?? []);
+        expect(attachmentsSection).toBeUndefined();
+      });
+    });
+
+    describe('attachments section', () => {
+      it('lists the attachments if the container has attachments configured', async () => {
+        const { writeDataStore } = utils(CATALOG_FOLDER);
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+          attachments: [
+            {
+              url: 'https://example.com/attachment.pdf',
+              title: 'Attachment 1',
+              type: 'pdf',
+            },
+          ],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const attachmentsSection = getChildNodeByTitle('Attachments', containerNode.pages ?? []);
+        expect(attachmentsSection).toBeDefined();
+        expect(attachmentsSection.pages).toEqual([
+          {
+            type: 'item',
+            title: 'Attachment 1',
+            href: 'https://example.com/attachment.pdf',
+          },
+        ]);
+      });
+    });
+  });
+
+  describe('channel navigation items', () => {
+    it('users can reference the latest version of a resource without passing in the version', async () => {
+      const { writeChannel } = utils(CATALOG_FOLDER);
+      await writeChannel({
+        id: 'PaymentChannel',
+        name: 'Payment Channel',
+        version: '0.0.1',
+        markdown: 'Payment Channel',
+      });
+      const navigationData = await getNestedSideBarData();
+      const channelNode = getNavigationConfigurationByKey('channel:PaymentChannel', navigationData);
+      expect(channelNode).toBeDefined();
+    });
+
+    it('users can reference the latest version of a resource passing in the version', async () => {
+      const { writeChannel } = utils(CATALOG_FOLDER);
+      await writeChannel({
+        id: 'PaymentChannel',
+        name: 'Payment Channel',
+        version: '0.0.1',
+        markdown: 'Payment Channel',
+      });
+      const navigationData = await getNestedSideBarData();
+      const channelNode = getNavigationConfigurationByKey('channel:PaymentChannel:0.0.1', navigationData);
+      expect(channelNode).toBeDefined();
+    });
+
+    it('the changelog link is listed when changelog is enabled', async () => {
+      config.changelog = { enabled: true };
+      const { writeChannel } = utils(CATALOG_FOLDER);
+      await writeChannel({
+        id: 'PaymentChannel',
+        name: 'Payment Channel',
+        version: '0.0.1',
+        markdown: 'Payment Channel',
+      });
+      const navigationData = await getNestedSideBarData();
+      const channelNode = getNavigationConfigurationByKey('channel:PaymentChannel:0.0.1', navigationData);
+      expect(channelNode).toHaveNavigationLink({
+        type: 'item',
+        title: 'Changelog',
+        href: '/docs/channels/PaymentChannel/0.0.1/changelog',
+      });
+      config.changelog = { enabled: false };
+    });
+
+    it('the changelog link is not listed when changelog is disabled', async () => {
+      config.changelog = { enabled: false };
+      const { writeChannel } = utils(CATALOG_FOLDER);
+      await writeChannel({
+        id: 'PaymentChannel',
+        name: 'Payment Channel',
+        version: '0.0.1',
+        markdown: 'Payment Channel',
+      });
+      const navigationData = await getNestedSideBarData();
+      const channelNode = getNavigationConfigurationByKey('channel:PaymentChannel:0.0.1', navigationData);
+      expect(channelNode).not.toHaveNavigationLink({
+        type: 'item',
+        title: 'Changelog',
+        href: '/docs/channels/PaymentChannel/0.0.1/changelog',
+      });
+    });
+  });
+
+  describe('data product navigation items', () => {
+    describe('flows section', () => {
+      it('is not listed if no flows reference the data product', async () => {
+        const { writeDataProduct } = utils(CATALOG_FOLDER);
+        await writeDataProduct({
+          id: 'PaymentAnalytics',
+          name: 'Payment Analytics',
+          version: '0.0.1',
+          markdown: 'Payment Analytics',
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const dataProductNode = getNavigationConfigurationByKey('data-product:PaymentAnalytics:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Appears in flows', dataProductNode.pages ?? []);
+        expect(flowsSection).toBeUndefined();
+      });
+
+      it('lists flows that reference the data product in flow steps', async () => {
+        const { writeDataProduct } = utils(CATALOG_FOLDER);
+        await writeDataProduct({
+          id: 'PaymentAnalytics',
+          name: 'Payment Analytics',
+          version: '0.0.1',
+          markdown: 'Payment Analytics',
+        });
+
+        mockFlows.push({
+          id: 'CheckoutFlow',
+          name: 'Checkout Flow',
+          version: '0.0.1',
+          markdown: 'Checkout Flow',
+          steps: [{ id: 'payment-analytics', title: 'Payment Analytics', dataProduct: { id: 'PaymentAnalytics' } }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const dataProductNode = getNavigationConfigurationByKey('data-product:PaymentAnalytics:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Appears in flows', dataProductNode.pages ?? []);
+
+        expect(flowsSection.pages).toEqual(['flow:CheckoutFlow:0.0.1']);
+      });
+
+      it('deduplicates flows when multiple steps reference the same data product', async () => {
+        const { writeDataProduct } = utils(CATALOG_FOLDER);
+        await writeDataProduct({
+          id: 'PaymentAnalytics',
+          name: 'Payment Analytics',
+          version: '0.0.1',
+          markdown: 'Payment Analytics',
+        });
+
+        mockFlows.push({
+          id: 'CheckoutFlow',
+          name: 'Checkout Flow',
+          version: '0.0.1',
+          markdown: 'Checkout Flow',
+          steps: [
+            { id: 'payment-analytics-ingest', title: 'Ingest Payment Analytics', dataProduct: { id: 'PaymentAnalytics' } },
+            {
+              id: 'payment-analytics-read',
+              title: 'Read Payment Analytics',
+              dataProduct: { id: 'PaymentAnalytics', version: '0.0.1' },
+            },
+          ],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const dataProductNode = getNavigationConfigurationByKey('data-product:PaymentAnalytics:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Appears in flows', dataProductNode.pages ?? []);
+
+        expect(flowsSection.pages).toEqual(['flow:CheckoutFlow:0.0.1']);
+      });
+
+      it('is not listed if the data product is configured not to render the section', async () => {
+        const { writeDataProduct } = utils(CATALOG_FOLDER);
+        await writeDataProduct({
+          id: 'PaymentAnalytics',
+          name: 'Payment Analytics',
+          version: '0.0.1',
+          markdown: 'Payment Analytics',
+          detailsPanel: {
+            flows: {
+              visible: false,
+            },
+          },
+        });
+
+        mockFlows.push({
+          id: 'CheckoutFlow',
+          name: 'Checkout Flow',
+          version: '0.0.1',
+          markdown: 'Checkout Flow',
+          steps: [{ id: 'payment-analytics', title: 'Payment Analytics', dataProduct: { id: 'PaymentAnalytics' } }],
+        });
+
+        const navigationData = await getNestedSideBarData();
+        const dataProductNode = getNavigationConfigurationByKey('data-product:PaymentAnalytics:0.0.1', navigationData);
+        const flowsSection = getChildNodeByTitle('Appears in flows', dataProductNode.pages ?? []);
+        expect(flowsSection).toBeUndefined();
+      });
+    });
+  });
+
+  describe('flow navigation items', () => {
+    it('lists messages, services, flows, data stores, and data products referenced by flow steps', async () => {
+      const { writeEvent, writeCommand, writeQuery, writeService, writeDataStore, writeDataProduct } = utils(CATALOG_FOLDER);
+
+      await writeEvent({
+        id: 'PaymentRequested',
+        name: 'Payment Requested',
+        version: '0.0.1',
+        markdown: 'Payment Requested',
+      });
+      await writeCommand({
+        id: 'ReserveInventory',
+        name: 'Reserve Inventory',
+        version: '0.0.1',
+        markdown: 'Reserve Inventory',
+      });
+      await writeQuery({
+        id: 'GetPaymentStatus',
+        name: 'Get Payment Status',
+        version: '0.0.1',
+        markdown: 'Get Payment Status',
+      });
+      await writeService({
+        id: 'PaymentService',
+        name: 'Payment Service',
+        version: '0.0.1',
+        markdown: 'Payment Service',
+      });
+      await writeDataStore({
+        id: 'PaymentsDB',
+        name: 'Payments DB',
+        version: '0.0.1',
+        markdown: 'Payments DB',
+        container_type: 'database',
+      });
+      await writeDataProduct({
+        id: 'PaymentAnalytics',
+        name: 'Payment Analytics',
+        version: '0.0.1',
+        markdown: 'Payment Analytics',
+      });
+      mockAgents.push({
+        id: 'FraudReviewAgent',
+        name: 'Fraud Review Agent',
+        version: '0.0.1',
+        markdown: 'Fraud Review Agent',
+      });
+
+      mockFlows.push(
+        {
+          id: 'CheckoutFlow',
+          name: 'Checkout Flow',
+          version: '0.0.1',
+          markdown: 'Checkout Flow',
+          steps: [
+            { id: 'payment-requested', title: 'Payment requested', message: { id: 'PaymentRequested' } },
+            { id: 'reserve-inventory', title: 'Reserve inventory', message: { id: 'ReserveInventory', version: '0.0.1' } },
+            { id: 'get-payment-status', title: 'Get payment status', message: { id: 'GetPaymentStatus' } },
+            { id: 'payment-service', title: 'Payment service', service: { id: 'PaymentService' } },
+            { id: 'fraud-review-agent', title: 'Fraud review agent', agent: { id: 'FraudReviewAgent' } },
+            { id: 'fraud-flow', title: 'Fraud flow', flow: { id: 'FraudFlow' } },
+            { id: 'payments-db', title: 'Payments DB', container: { id: 'PaymentsDB' } },
+            { id: 'payment-analytics', title: 'Payment Analytics', dataProduct: { id: 'PaymentAnalytics' } },
+          ],
+        },
+        {
+          id: 'FraudFlow',
+          name: 'Fraud Flow',
+          version: '0.0.1',
+          markdown: 'Fraud Flow',
+          steps: [],
+        }
+      );
+
+      const navigationData = await getNestedSideBarData();
+      const flowNode = getNavigationConfigurationByKey('flow:CheckoutFlow:0.0.1', navigationData);
+      const messagesSection = getChildNodeByTitle('Messages', flowNode.pages ?? []);
+      const servicesSection = getChildNodeByTitle('Services', flowNode.pages ?? []);
+      const agentsSection = getChildNodeByTitle('Agents', flowNode.pages ?? []);
+      const subflowsSection = getChildNodeByTitle('Subflows', flowNode.pages ?? []);
+      const dataStoresSection = getChildNodeByTitle('Data Stores', flowNode.pages ?? []);
+      const dataProductsSection = getChildNodeByTitle('Data Products', flowNode.pages ?? []);
+
+      expect(messagesSection.pages).toEqual([
+        'event:PaymentRequested:0.0.1',
+        'command:ReserveInventory:0.0.1',
+        'query:GetPaymentStatus:0.0.1',
+      ]);
+      expect(servicesSection.pages).toEqual(['service:PaymentService:0.0.1']);
+      expect(agentsSection.pages).toEqual(['agent:FraudReviewAgent:0.0.1']);
+      expect(subflowsSection.pages).toEqual(['flow:FraudFlow:0.0.1']);
+      expect(dataStoresSection.pages).toEqual(['container:PaymentsDB:0.0.1']);
+      expect(dataProductsSection.pages).toEqual(['data-product:PaymentAnalytics:0.0.1']);
+
+      const agentNode = getNavigationConfigurationByKey('agent:FraudReviewAgent:0.0.1', navigationData);
+      const agentFlowsSection = getChildNodeByTitle('Appears in flows', agentNode.pages ?? []);
+      expect(agentFlowsSection.pages).toEqual(['flow:CheckoutFlow:0.0.1']);
+    });
+
+    it('does not list reference sections when a flow has no resource step references', async () => {
+      mockFlows.push({
+        id: 'ManualFlow',
+        name: 'Manual Flow',
+        version: '0.0.1',
+        markdown: 'Manual Flow',
+        steps: [{ id: 'start', title: 'Start' }],
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const flowNode = getNavigationConfigurationByKey('flow:ManualFlow:0.0.1', navigationData);
+
+      expect(getChildNodeByTitle('Messages', flowNode.pages ?? [])).toBeUndefined();
+      expect(getChildNodeByTitle('Services', flowNode.pages ?? [])).toBeUndefined();
+      expect(getChildNodeByTitle('Agents', flowNode.pages ?? [])).toBeUndefined();
+      expect(getChildNodeByTitle('Subflows', flowNode.pages ?? [])).toBeUndefined();
+      expect(getChildNodeByTitle('Data Stores', flowNode.pages ?? [])).toBeUndefined();
+      expect(getChildNodeByTitle('Data Products', flowNode.pages ?? [])).toBeUndefined();
+    });
+  });
+
+  describe('resource documentation sidebar sections', () => {
+    it('renders Documentation sections for domain, service, message, flow, container, channel, and data product', async () => {
+      const previousScale = process.env.EVENTCATALOG_SCALE;
+      process.env.EVENTCATALOG_SCALE = 'true';
+      try {
+        const { writeDomain, writeService, writeEvent, writeDataStore, writeDataProduct, writeChannel } = utils(CATALOG_FOLDER);
+
+        await writeDomain({
+          id: 'Shipping',
+          name: 'Shipping',
+          version: '0.0.1',
+          markdown: 'Shipping',
+        });
+
+        await writeService({
+          id: 'ShippingService',
+          name: 'Shipping Service',
+          version: '0.0.1',
+          markdown: 'Shipping Service',
+        });
+
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: 'Payment Processed',
+        });
+
+        await writeDataStore({
+          id: 'PaymentDataStore',
+          name: 'Payment DataStore',
+          version: '0.0.1',
+          markdown: 'Payment DataStore',
+          container_type: 'database',
+        });
+
+        await writeDataProduct({
+          id: 'PaymentAnalytics',
+          name: 'Payment Analytics',
+          version: '0.0.1',
+          markdown: 'Payment Analytics',
+        });
+
+        await writeChannel({
+          id: 'PaymentChannel',
+          name: 'Payment Channel',
+          version: '0.0.1',
+          markdown: 'Payment Channel',
+        });
+
+        mockFlows.push({
+          id: 'PaymentFlow',
+          name: 'Payment Flow',
+          version: '0.0.1',
+          markdown: 'Payment Flow',
+        });
+
+        mockResourceDocs.push(
+          {
+            id: 'domains/Shipping/docs/adrs/order-boundary.mdx',
+            collection: 'resourceDocs',
+            filePath: 'domains/Shipping/docs/adrs/order-boundary.mdx',
+            data: { id: 'order-boundary', type: 'adrs', version: '1.0.0', title: 'Order Boundary ADR' },
+          },
+          {
+            id: 'domains/Shipping/docs/adrs/versioned/0.9.0/order-boundary.mdx',
+            collection: 'resourceDocs',
+            filePath: 'domains/Shipping/docs/adrs/versioned/0.9.0/order-boundary.mdx',
+            data: { id: 'order-boundary', type: 'adrs', version: '0.9.0', title: 'Order Boundary ADR' },
+          },
+          {
+            id: 'domains/Shipping/docs/operating-model.mdx',
+            collection: 'resourceDocs',
+            filePath: 'domains/Shipping/docs/operating-model.mdx',
+            data: { id: 'operating-model', version: '1.0.0', title: 'Operating Model' },
+          },
+          {
+            id: 'domains/Shipping/services/ShippingService/docs/adrs/service-boundary.mdx',
+            collection: 'resourceDocs',
+            filePath: 'domains/Shipping/services/ShippingService/docs/adrs/service-boundary.mdx',
+            data: { id: 'service-boundary', type: 'adrs', version: '1.0.0', title: 'Service Boundary ADR' },
+          },
+          {
+            id: 'domains/Shipping/services/ShippingService/events/PaymentProcessed/docs/runbooks/retry-failures.mdx',
+            collection: 'resourceDocs',
+            filePath: 'domains/Shipping/services/ShippingService/events/PaymentProcessed/docs/runbooks/retry-failures.mdx',
+            data: { id: 'retry-failures', type: 'runbooks', version: '1.0.0', title: 'Retry Failures' },
+          },
+          {
+            id: 'flows/PaymentFlow/docs/adrs/orchestration-strategy.mdx',
+            collection: 'resourceDocs',
+            filePath: 'flows/PaymentFlow/docs/adrs/orchestration-strategy.mdx',
+            data: { id: 'orchestration-strategy', type: 'adrs', version: '1.0.0', title: 'Orchestration Strategy ADR' },
+          },
+          {
+            id: 'containers/PaymentDataStore/docs/adrs/data-retention.mdx',
+            collection: 'resourceDocs',
+            filePath: 'containers/PaymentDataStore/docs/adrs/data-retention.mdx',
+            data: { id: 'data-retention', type: 'adrs', version: '1.0.0', title: 'Data Retention ADR' },
+          },
+          {
+            id: 'channels/PaymentChannel/docs/guides/channel-usage.mdx',
+            collection: 'resourceDocs',
+            filePath: 'channels/PaymentChannel/docs/guides/channel-usage.mdx',
+            data: { id: 'channel-usage', type: 'guides', version: '1.0.0', title: 'Channel Usage Guide' },
+          },
+          {
+            id: 'data-products/PaymentAnalytics/docs/contracts/fact-table-definition.mdx',
+            collection: 'resourceDocs',
+            filePath: 'data-products/PaymentAnalytics/docs/contracts/fact-table-definition.mdx',
+            data: { id: 'fact-table-definition', type: 'contracts', version: '1.0.0', title: 'Fact Table Definition' },
+          }
+        );
+
+        mockResourceDocCategories.push({
+          id: 'domains/Shipping/docs/category.json',
+          collection: 'resourceDocCategories',
+          filePath: 'domains/Shipping/docs/category.json',
+          data: { label: 'Pages', position: 1 },
+        });
+
+        const navigationData = await getNestedSideBarData();
+
+        const domainNode = getNavigationConfigurationByKey('domain:Shipping:0.0.1', navigationData);
+        const domainDocs = getChildNodeByTitle('Documentation', domainNode.pages ?? []);
+        const domainAdrs = getChildNodeByTitle('ADR', domainDocs.pages ?? []);
+        const domainPages = getChildNodeByTitle('Pages', domainDocs.pages ?? []);
+        expect(domainAdrs.pages).toEqual([
+          { type: 'item', title: 'Order Boundary ADR', href: '/docs/domains/Shipping/0.0.1/adrs/order-boundary' },
+        ]);
+        expect(domainPages.pages).toEqual([
+          { type: 'item', title: 'Operating Model', href: '/docs/domains/Shipping/0.0.1/pages/operating-model' },
+        ]);
+
+        const serviceNode = getNavigationConfigurationByKey('service:ShippingService:0.0.1', navigationData);
+        const serviceDocs = getChildNodeByTitle('Documentation', serviceNode.pages ?? []);
+        const serviceAdrs = getChildNodeByTitle('ADR', serviceDocs.pages ?? []);
+        expect(serviceAdrs.pages).toEqual([
+          {
+            type: 'item',
+            title: 'Service Boundary ADR',
+            href: '/docs/services/ShippingService/0.0.1/adrs/service-boundary',
+          },
+        ]);
+
+        const messageNode = getNavigationConfigurationByKey('event:PaymentProcessed:0.0.1', navigationData);
+        const messageDocs = getChildNodeByTitle('Documentation', messageNode.pages ?? []);
+        const messageRunbooks = getChildNodeByTitle('Runbook', messageDocs.pages ?? []);
+        expect(messageRunbooks.pages).toEqual([
+          {
+            type: 'item',
+            title: 'Retry Failures',
+            href: '/docs/events/PaymentProcessed/0.0.1/runbooks/retry-failures',
+          },
+        ]);
+
+        const flowNode = getNavigationConfigurationByKey('flow:PaymentFlow:0.0.1', navigationData);
+        const flowDocs = getChildNodeByTitle('Documentation', flowNode.pages ?? []);
+        const flowAdrs = getChildNodeByTitle('ADR', flowDocs.pages ?? []);
+        expect(flowAdrs.pages).toEqual([
+          {
+            type: 'item',
+            title: 'Orchestration Strategy ADR',
+            href: '/docs/flows/PaymentFlow/0.0.1/adrs/orchestration-strategy',
+          },
+        ]);
+
+        const containerNode = getNavigationConfigurationByKey('container:PaymentDataStore:0.0.1', navigationData);
+        const containerDocs = getChildNodeByTitle('Documentation', containerNode.pages ?? []);
+        const containerAdrs = getChildNodeByTitle('ADR', containerDocs.pages ?? []);
+        expect(containerAdrs.pages).toEqual([
+          {
+            type: 'item',
+            title: 'Data Retention ADR',
+            href: '/docs/containers/PaymentDataStore/0.0.1/adrs/data-retention',
+          },
+        ]);
+
+        const channelNode = getNavigationConfigurationByKey('channel:PaymentChannel:0.0.1', navigationData);
+        const channelDocs = getChildNodeByTitle('Documentation', channelNode.pages ?? []);
+        const channelGuides = getChildNodeByTitle('Guide', channelDocs.pages ?? []);
+        expect(channelGuides.pages).toEqual([
+          {
+            type: 'item',
+            title: 'Channel Usage Guide',
+            href: '/docs/channels/PaymentChannel/0.0.1/guides/channel-usage',
+          },
+        ]);
+
+        const dataProductNode = getNavigationConfigurationByKey('data-product:PaymentAnalytics:0.0.1', navigationData);
+        const dataProductDocs = getChildNodeByTitle('Documentation', dataProductNode.pages ?? []);
+        const dataProductContracts = getChildNodeByTitle('Contract', dataProductDocs.pages ?? []);
+        expect(dataProductContracts.pages).toEqual([
+          {
+            type: 'item',
+            title: 'Fact Table Definition',
+            href: '/docs/data-products/PaymentAnalytics/0.0.1/contracts/fact-table-definition',
+          },
+        ]);
+      } finally {
+        if (previousScale === undefined) {
+          delete process.env.EVENTCATALOG_SCALE;
+        } else {
+          process.env.EVENTCATALOG_SCALE = previousScale;
+        }
+      }
+    });
+  });
+
+  describe('system navigation items', () => {
+    it('shows the System section with System Context Map when systems exist', async () => {
+      const { writeDomain } = utils(CATALOG_FOLDER);
+      await writeDomain({
+        id: 'Shipping',
+        name: 'Shipping',
+        version: '0.0.1',
+        markdown: 'Shipping',
+      });
+      mockSystems.push({
+        id: 'ShippingSystem',
+        name: 'Shipping System',
+        version: '0.0.1',
+        summary: 'Coordinates shipping',
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const systemNode = navigationData.nodes['list:system'] as NavNode;
+
+      expect(systemNode).toBeDefined();
+      expect(systemNode.title).toBe('System');
+      expect(systemNode.pages).toEqual([
+        {
+          type: 'item',
+          title: 'System Context Map',
+          href: '/visualiser/system-context-map',
+        },
+      ]);
+    });
+
+    it('does not show the System section when visualizer is disabled', async () => {
+      config.visualiser.enabled = false;
+
+      const { writeDomain } = utils(CATALOG_FOLDER);
+      await writeDomain({
+        id: 'Shipping',
+        name: 'Shipping',
+        version: '0.0.1',
+        markdown: 'Shipping',
+      });
+      mockSystems.push({
+        id: 'ShippingSystem',
+        name: 'Shipping System',
+        version: '0.0.1',
+        summary: 'Coordinates shipping',
+      });
+
+      const navigationData = await getNestedSideBarData();
+      const systemNode = navigationData.nodes['list:system'];
+
+      expect(systemNode).toBeUndefined();
+
+      // Turn it back on
+      config.visualiser.enabled = true;
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/__tests__/adr-builder.spec.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/__tests__/adr-builder.spec.ts
new file mode 100644
index 000000000..718389dee
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/__tests__/adr-builder.spec.ts
@@ -0,0 +1,91 @@
+import { describe, it, expect, vi } from 'vitest';
+import { buildAdrNode } from '../adr';
+import type { Adr } from '@utils/collections/adrs';
+
+// Mock feature utils
+vi.mock('@utils/feature', () => ({
+  isChangelogEnabled: () => false,
+}));
+
+// Mock url-builder
+vi.mock('@utils/url-builder', () => ({
+  buildUrl: (path: string) => path,
+}));
+
+const createMockAdr = (overrides: Partial<Adr['data']> = {}): Adr =>
+  ({
+    id: 'adrs/strangle-the-monolith/index.md',
+    slug: 'adrs/strangle-the-monolith',
+    collection: 'adrs',
+    data: {
+      id: 'strangle-the-monolith',
+      name: 'Strangle the monolith',
+      version: '1.0.0',
+      status: 'accepted',
+      date: new Date('2026-01-01'),
+      ...overrides,
+    },
+  }) as Adr;
+
+const createMockSystem = (id: string, version: string) =>
+  ({
+    id: `systems/${id}/index.mdx`,
+    slug: `systems/${id}`,
+    collection: 'systems',
+    data: { id, version, name: id },
+  }) as any;
+
+const emptyContext = {
+  agents: [],
+  services: [],
+  domains: [],
+  systems: [],
+  events: [],
+  commands: [],
+  queries: [],
+  flows: [],
+  channels: [],
+  containers: [],
+  entities: [],
+  dataProducts: [],
+  diagrams: [],
+  adrs: [],
+  users: [],
+  teams: [],
+  resourceDocs: [],
+  resourceDocCategories: [],
+} as any;
+
+describe('buildAdrNode', () => {
+  describe('applies to', () => {
+    it('resolves a system that the decision record applies to', () => {
+      const adr = createMockAdr({
+        appliesTo: [{ type: 'system', id: 'CoreMonolith', version: '1.0.0' }],
+      });
+
+      const context = { ...emptyContext, systems: [createMockSystem('CoreMonolith', '1.0.0')], adrs: [adr] };
+      const result = buildAdrNode(adr, [], [], context);
+
+      const appliesToSection = (result.pages as any[])?.find((p: any) => p.title === 'Applies to');
+
+      expect(appliesToSection).toMatchObject({
+        type: 'group',
+        title: 'Applies to',
+        icon: 'GitBranch',
+        pages: ['system:CoreMonolith:1.0.0'],
+      });
+    });
+
+    it('does not render an Applies to section when the referenced system is not in the catalog', () => {
+      const adr = createMockAdr({
+        appliesTo: [{ type: 'system', id: 'MissingSystem', version: '1.0.0' }],
+      });
+
+      const context = { ...emptyContext, adrs: [adr] };
+      const result = buildAdrNode(adr, [], [], context);
+
+      const appliesToSection = (result.pages as any[])?.find((p: any) => p.title === 'Applies to');
+      expect(appliesToSection).toBeUndefined();
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/__tests__/shared.spec.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/__tests__/shared.spec.ts
new file mode 100644
index 000000000..abd18eba5
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/__tests__/shared.spec.ts
@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest';
+import { withArchitectureDecisionsSection, type NavNode } from '../shared';
+
+describe('withArchitectureDecisionsSection', () => {
+  it('adds Decision Records before Owners when both sections exist', () => {
+    const node: NavNode = {
+      type: 'item',
+      title: 'Orders Service',
+      pages: [
+        { type: 'group', title: 'Quick Reference', pages: [] },
+        { type: 'group', title: 'Appears in flows', pages: [] },
+        { type: 'group', title: 'Owners', pages: [] },
+        { type: 'group', title: 'Code', pages: [] },
+      ],
+    };
+
+    const resource = {
+      collection: 'services',
+      data: { id: 'OrdersService', version: '1.0.0' },
+    };
+
+    const adr = {
+      collection: 'adrs',
+      data: {
+        id: 'use-events-for-order-updates',
+        version: '1.0.0',
+        appliesTo: [{ type: 'service', id: 'OrdersService', version: '1.0.0' }],
+      },
+    };
+
+    const result = withArchitectureDecisionsSection(node, resource as any, [adr as any]);
+
+    expect(result.pages?.map((page) => (typeof page === 'string' ? page : page.title))).toEqual([
+      'Quick Reference',
+      'Appears in flows',
+      'Decision Records',
+      'Owners',
+      'Code',
+    ]);
+  });
+
+  it('adds Decision Records for a system when an ADR applies to it', () => {
+    const node: NavNode = {
+      type: 'item',
+      title: 'Core Monolith',
+      href: '/docs/systems/CoreMonolith/1.0.0',
+    };
+
+    const resource = {
+      collection: 'systems',
+      data: { id: 'CoreMonolith', version: '1.0.0' },
+    };
+
+    const adr = {
+      collection: 'adrs',
+      data: {
+        id: 'strangle-the-monolith',
+        version: '1.0.0',
+        appliesTo: [{ type: 'system', id: 'CoreMonolith', version: '1.0.0' }],
+      },
+    };
+
+    const result = withArchitectureDecisionsSection(node, resource as any, [adr as any]);
+
+    const decisionRecords = result.pages?.find((page) => typeof page !== 'string' && page.title === 'Decision Records');
+
+    expect(decisionRecords && typeof decisionRecords !== 'string' ? decisionRecords.pages : undefined).toEqual([
+      'adr:strangle-the-monolith:1.0.0',
+    ]);
+  });
+
+  it('keeps an overview link when adding Decision Records to href-only nodes', () => {
+    const node: NavNode = {
+      type: 'item',
+      title: 'Dave',
+      href: '/docs/users/dave',
+    };
+
+    const resource = {
+      collection: 'users',
+      data: { id: 'dave' },
+    };
+
+    const adr = {
+      collection: 'adrs',
+      data: {
+        id: 'use-events-for-order-updates',
+        version: '1.0.0',
+        appliesTo: [{ type: 'user', id: 'dave' }],
+      },
+    };
+
+    const result = withArchitectureDecisionsSection(node, resource as any, [adr as any]);
+
+    expect(result.href).toBe('/docs/users/dave');
+    expect(result.pages).toEqual([
+      {
+        type: 'item',
+        title: 'Overview',
+        href: '/docs/users/dave',
+      },
+      {
+        type: 'group',
+        title: 'Decision Records',
+        icon: 'ClipboardList',
+        pages: ['adr:use-events-for-order-updates:1.0.0'],
+      },
+    ]);
+  });
+
+  it('sorts Decision Records by name then id', () => {
+    const node: NavNode = {
+      type: 'item',
+      title: 'Orders Service',
+      href: '/docs/services/OrdersService/1.0.0',
+    };
+
+    const resource = {
+      collection: 'services',
+      data: { id: 'OrdersService', version: '1.0.0' },
+    };
+
+    const createAdr = (id: string, name?: string) => ({
+      collection: 'adrs',
+      data: {
+        id,
+        name,
+        version: '1.0.0',
+        appliesTo: [{ type: 'service', id: 'OrdersService', version: '1.0.0' }],
+      },
+    });
+
+    const result = withArchitectureDecisionsSection(
+      node,
+      resource as any,
+      [
+        createAdr('adr-003', 'Store payment authorization'),
+        createAdr('adr-002', 'Choose event format'),
+        createAdr('adr-001', 'Choose event format'),
+        createAdr('adr-004'),
+      ] as any
+    );
+
+    const decisionRecords = result.pages?.find((page) => typeof page !== 'string' && page.title === 'Decision Records');
+
+    expect(decisionRecords && typeof decisionRecords !== 'string' ? decisionRecords.pages : undefined).toEqual([
+      'adr:adr-004:1.0.0',
+      'adr:adr-001:1.0.0',
+      'adr:adr-002:1.0.0',
+      'adr:adr-003:1.0.0',
+    ]);
+  });
+});
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/__tests__/system-builder.spec.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/__tests__/system-builder.spec.ts
new file mode 100644
index 000000000..4955d082f
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/__tests__/system-builder.spec.ts
@@ -0,0 +1,367 @@
+import { describe, it, expect, vi } from 'vitest';
+import { buildSystemNode } from '../system';
+import type { CollectionEntry } from 'astro:content';
+
+// Mock feature utils
+vi.mock('@utils/feature', () => ({
+  isVisualiserEnabled: () => true,
+  isChangelogEnabled: () => false,
+}));
+
+// Mock url-builder
+vi.mock('@utils/url-builder', () => ({
+  buildUrl: (path: string) => path,
+}));
+
+const createMockSystem = (overrides: Partial<CollectionEntry<'systems'>['data']> = {}): CollectionEntry<'systems'> =>
+  ({
+    id: 'systems/CoreMonolith/index.md',
+    slug: 'systems/CoreMonolith',
+    collection: 'systems',
+    data: {
+      id: 'CoreMonolith',
+      name: 'Core Monolith',
+      version: '1.0.0',
+      summary: 'The legacy core monolith',
+      owners: [],
+      ...overrides,
+    },
+  }) as CollectionEntry<'systems'>;
+
+const createMockService = (id: string, version: string): CollectionEntry<'services'> =>
+  ({
+    id: `services/${id}/index.mdx`,
+    slug: `services/${id}`,
+    collection: 'services',
+    data: { id, version, name: id },
+  }) as CollectionEntry<'services'>;
+
+const createMockFlow = (id: string, version: string): CollectionEntry<'flows'> =>
+  ({
+    id: `flows/${id}/index.mdx`,
+    slug: `flows/${id}`,
+    collection: 'flows',
+    data: { id, version, name: id, steps: [] },
+  }) as unknown as CollectionEntry<'flows'>;
+
+const createMockEntity = (id: string, version: string, name?: string): CollectionEntry<'entities'> =>
+  ({
+    id: `entities/${id}/index.mdx`,
+    slug: `entities/${id}`,
+    collection: 'entities',
+    data: { id, version, name: name ?? id },
+  }) as unknown as CollectionEntry<'entities'>;
+
+const createMockContainer = (id: string, version: string): CollectionEntry<'containers'> =>
+  ({
+    id: `containers/${id}/index.mdx`,
+    slug: `containers/${id}`,
+    collection: 'containers',
+    data: { id, version, name: id },
+  }) as unknown as CollectionEntry<'containers'>;
+
+const createMockDiagram = (id: string, version: string, name?: string): CollectionEntry<'diagrams'> =>
+  ({
+    id: `diagrams/${id}/index.mdx`,
+    slug: `diagrams/${id}`,
+    collection: 'diagrams',
+    data: { id, version, name: name ?? id },
+  }) as unknown as CollectionEntry<'diagrams'>;
+
+const emptyContext = {
+  events: [] as CollectionEntry<'events'>[],
+  commands: [] as CollectionEntry<'commands'>[],
+  queries: [] as CollectionEntry<'queries'>[],
+  services: [] as CollectionEntry<'services'>[],
+  containers: [] as CollectionEntry<'containers'>[],
+  channels: [] as CollectionEntry<'channels'>[],
+  diagrams: [] as CollectionEntry<'diagrams'>[],
+  resourceDocs: [],
+  resourceDocCategories: [],
+} as any;
+
+// Services and Data Stores are nested as subtle subgroups under a top-level "Resources" group.
+const findResourcesSection = (result: any) => (result.pages as any[])?.find((p: any) => p.title === 'Resources');
+const findResourceSubsection = (result: any, title: string) =>
+  (findResourcesSection(result)?.pages as any[])?.find((p: any) => p.title === title);
+
+describe('buildSystemNode', () => {
+  describe('basic structure', () => {
+    it('returns a NavNode with correct basic properties', () => {
+      const system = createMockSystem();
+      const result = buildSystemNode(system, [], emptyContext);
+
+      expect(result).toMatchObject({
+        type: 'item',
+        title: 'Core Monolith',
+        badge: 'System',
+        summary: 'The legacy core monolith',
+      });
+    });
+
+    it('includes Overview link in Quick Reference section', () => {
+      const system = createMockSystem();
+      const result = buildSystemNode(system, [], emptyContext);
+
+      const quickRef = (result.pages as any[])?.find((p: any) => p.title === 'Quick Reference');
+      expect(quickRef).toBeDefined();
+      expect((quickRef as any)?.pages).toContainEqual({
+        type: 'item',
+        title: 'Overview',
+        href: '/docs/systems/CoreMonolith/1.0.0',
+      });
+    });
+
+    it('does not include a Changelog link when changelog is disabled', () => {
+      const system = createMockSystem();
+      const result = buildSystemNode(system, [], emptyContext);
+
+      const quickRef = (result.pages as any[])?.find((p: any) => p.title === 'Quick Reference');
+      expect((quickRef as any)?.pages).not.toContainEqual(
+        expect.objectContaining({ href: '/docs/systems/CoreMonolith/1.0.0/changelog' })
+      );
+    });
+  });
+
+  describe('services', () => {
+    it('renders a Services group with resolved service refs', () => {
+      const system = createMockSystem({
+        services: [createMockService('OrdersService', '1.0.0'), createMockService('PaymentService', '2.0.0')] as any,
+      });
+
+      const result = buildSystemNode(system, [], emptyContext);
+      const servicesSection = findResourceSubsection(result, 'Services');
+
+      expect(servicesSection).toMatchObject({
+        type: 'group',
+        title: 'Services',
+        subtle: true,
+        icon: 'Server',
+        pages: ['service:OrdersService:1.0.0', 'service:PaymentService:2.0.0'],
+      });
+    });
+
+    it('does not render a Services group when there are no services', () => {
+      const system = createMockSystem();
+      const result = buildSystemNode(system, [], emptyContext);
+
+      const servicesSection = findResourceSubsection(result, 'Services');
+      expect(servicesSection).toBeUndefined();
+    });
+
+    it('does not render a Services group when the details panel hides services', () => {
+      const system = createMockSystem({
+        services: [createMockService('OrdersService', '1.0.0')] as any,
+        detailsPanel: { services: { visible: false } },
+      } as any);
+
+      const result = buildSystemNode(system, [], emptyContext);
+      const servicesSection = findResourceSubsection(result, 'Services');
+      expect(servicesSection).toBeUndefined();
+    });
+  });
+
+  describe('flows', () => {
+    it('renders a Flows group with resolved flow refs', () => {
+      const system = createMockSystem({
+        flows: [createMockFlow('OrderFlow', '1.0.0'), createMockFlow('PaymentFlow', '2.0.0')] as any,
+      });
+
+      const result = buildSystemNode(system, [], emptyContext);
+      const flowsSection = findResourceSubsection(result, 'Flows');
+
+      expect(flowsSection).toMatchObject({
+        type: 'group',
+        title: 'Flows',
+        icon: 'Waypoints',
+        pages: ['flow:OrderFlow:1.0.0', 'flow:PaymentFlow:2.0.0'],
+      });
+    });
+
+    it('does not render a Flows group when there are no flows', () => {
+      const system = createMockSystem();
+      const result = buildSystemNode(system, [], emptyContext);
+
+      const flowsSection = findResourceSubsection(result, 'Flows');
+      expect(flowsSection).toBeUndefined();
+    });
+
+    it('does not render a Flows group when the details panel hides flows', () => {
+      const system = createMockSystem({
+        flows: [createMockFlow('OrderFlow', '1.0.0')] as any,
+        detailsPanel: { flows: { visible: false } },
+      } as any);
+
+      const result = buildSystemNode(system, [], emptyContext);
+      const flowsSection = findResourceSubsection(result, 'Flows');
+      expect(flowsSection).toBeUndefined();
+    });
+  });
+
+  describe('entities', () => {
+    it('renders an Entities group with resolved entity refs', () => {
+      const system = createMockSystem({
+        entities: [createMockEntity('Order', '1.0.0', 'Order'), createMockEntity('Payment', '2.0.0', 'Payment')] as any,
+      });
+
+      const result = buildSystemNode(system, [], emptyContext);
+      const entitiesSection = (result.pages as any[])?.find((p: any) => p.title === 'Entities');
+
+      expect(entitiesSection).toMatchObject({
+        type: 'group',
+        title: 'Entities',
+        icon: 'Box',
+        pages: [
+          { type: 'item', title: 'Order', href: '/docs/entities/Order/1.0.0' },
+          { type: 'item', title: 'Payment', href: '/docs/entities/Payment/2.0.0' },
+        ],
+      });
+    });
+
+    it('does not render an Entities group when there are no entities', () => {
+      const system = createMockSystem();
+      const result = buildSystemNode(system, [], emptyContext);
+
+      const entitiesSection = (result.pages as any[])?.find((p: any) => p.title === 'Entities');
+      expect(entitiesSection).toBeUndefined();
+    });
+
+    it('does not render an Entities group when the details panel hides entities', () => {
+      const system = createMockSystem({
+        entities: [createMockEntity('Order', '1.0.0')] as any,
+        detailsPanel: { entities: { visible: false } },
+      } as any);
+
+      const result = buildSystemNode(system, [], emptyContext);
+      const entitiesSection = (result.pages as any[])?.find((p: any) => p.title === 'Entities');
+      expect(entitiesSection).toBeUndefined();
+    });
+  });
+
+  describe('data stores (containers)', () => {
+    it('renders a Data Stores group with resolved container node refs', () => {
+      const system = createMockSystem({
+        containers: [createMockContainer('orders-db', '1.0.0'), createMockContainer('payments-db', '2.0.0')] as any,
+      });
+
+      const result = buildSystemNode(system, [], emptyContext);
+      const dataStoresSection = findResourceSubsection(result, 'Data Stores');
+
+      expect(dataStoresSection).toMatchObject({
+        type: 'group',
+        title: 'Data Stores',
+        subtle: true,
+        icon: 'Database',
+        pages: ['container:orders-db:1.0.0', 'container:payments-db:2.0.0'],
+      });
+    });
+
+    it('does not render a Data Stores group when there are no containers', () => {
+      const system = createMockSystem();
+      const result = buildSystemNode(system, [], emptyContext);
+
+      const dataStoresSection = findResourceSubsection(result, 'Data Stores');
+      expect(dataStoresSection).toBeUndefined();
+    });
+
+    it('does not render a Data Stores group when the details panel hides containers', () => {
+      const system = createMockSystem({
+        containers: [createMockContainer('orders-db', '1.0.0')] as any,
+        detailsPanel: { containers: { visible: false } },
+      } as any);
+
+      const result = buildSystemNode(system, [], emptyContext);
+      const dataStoresSection = findResourceSubsection(result, 'Data Stores');
+      expect(dataStoresSection).toBeUndefined();
+    });
+  });
+
+  describe('diagrams', () => {
+    it('renders a Diagrams group with resolved diagram links', () => {
+      const system = createMockSystem({ diagrams: [{ id: 'target-architecture', version: '1.0.0' }] as any });
+      const context = { ...emptyContext, diagrams: [createMockDiagram('target-architecture', '1.0.0', 'Target Architecture')] };
+
+      const result = buildSystemNode(system, [], context);
+      const diagramsSection = (result.pages as any[])?.find((p: any) => p.title === 'Diagrams');
+
+      expect(diagramsSection).toMatchObject({
+        type: 'group',
+        title: 'Diagrams',
+        icon: 'FileImage',
+      });
+      expect((diagramsSection as any)?.pages).toContainEqual({
+        type: 'item',
+        title: 'Target Architecture',
+        href: '/diagrams/target-architecture/1.0.0',
+      });
+    });
+
+    it('does not render a Diagrams group when there are no diagrams', () => {
+      const system = createMockSystem();
+      const result = buildSystemNode(system, [], emptyContext);
+
+      const diagramsSection = (result.pages as any[])?.find((p: any) => p.title === 'Diagrams');
+      expect(diagramsSection).toBeUndefined();
+    });
+
+    it('does not render a Diagrams group when the details panel hides diagrams', () => {
+      const system = createMockSystem({
+        diagrams: [{ id: 'target-architecture', version: '1.0.0' }] as any,
+        detailsPanel: { diagrams: { visible: false } },
+      } as any);
+      const context = { ...emptyContext, diagrams: [createMockDiagram('target-architecture', '1.0.0')] };
+
+      const result = buildSystemNode(system, [], context);
+      const diagramsSection = (result.pages as any[])?.find((p: any) => p.title === 'Diagrams');
+      expect(diagramsSection).toBeUndefined();
+    });
+  });
+
+  describe('owners', () => {
+    it('includes Owners section when owners are provided', () => {
+      const system = createMockSystem({ owners: [{ id: 'user1' }] as any });
+      const owners = [{ id: 'user1', data: { id: 'user1', name: 'User One' }, collection: 'users' }];
+
+      const result = buildSystemNode(system, owners as any, emptyContext);
+      const ownersSection = (result.pages as any[])?.find((p: any) => p.title === 'Owners');
+
+      expect(ownersSection).toBeDefined();
+    });
+
+    it('does not include Owners section when no owners are provided', () => {
+      const system = createMockSystem();
+      const result = buildSystemNode(system, [], emptyContext);
+
+      const ownersSection = (result.pages as any[])?.find((p: any) => p.title === 'Owners');
+      expect(ownersSection).toBeUndefined();
+    });
+  });
+
+  describe('repository', () => {
+    it('includes a Code section when a repository is configured', () => {
+      const system = createMockSystem({ repository: { url: 'https://github.com/acme/monolith', language: 'TypeScript' } });
+      const result = buildSystemNode(system, [], emptyContext);
+
+      const repositorySection = (result.pages as any[])?.find((p: any) => p.title === 'Code');
+      expect(repositorySection).toBeDefined();
+    });
+
+    it('does not include a Code section when no repository is configured', () => {
+      const system = createMockSystem();
+      const result = buildSystemNode(system, [], emptyContext);
+
+      const repositorySection = (result.pages as any[])?.find((p: any) => p.title === 'Code');
+      expect(repositorySection).toBeUndefined();
+    });
+  });
+
+  describe('attachments', () => {
+    it('does not include an Attachments section when no attachments are provided', () => {
+      const system = createMockSystem();
+      const result = buildSystemNode(system, [], emptyContext);
+
+      const attachmentsSection = (result.pages as any[])?.find((p: any) => p.title === 'Attachments');
+      expect(attachmentsSection).toBeUndefined();
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/adr.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/adr.ts
new file mode 100644
index 000000000..e222de1f7
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/adr.ts
@@ -0,0 +1,152 @@
+import { buildUrl } from '@utils/url-builder';
+import {
+  getAdrRelationships,
+  getAdrNodeKey,
+  getAdrResourceNodeKey,
+  resolveAdrPointers,
+  type Adr,
+  type AdrResource,
+} from '@utils/collections/adrs';
+import { collectionToResourceMap, createVersionedMap, findInMap } from '@utils/collections/util';
+import type { ChildRef, NavNode, ResourceGroupContext } from './shared';
+import {
+  buildAttachmentsSection,
+  buildOwnersSection,
+  buildQuickReferenceSection,
+  buildRepositorySection,
+  shouldRenderSideBarSection,
+} from './shared';
+import { isChangelogEnabled } from '@utils/feature';
+
+const firstClassResourceCollections = [
+  'agents',
+  'services',
+  'events',
+  'commands',
+  'queries',
+  'flows',
+  'channels',
+  'domains',
+  'systems',
+  'users',
+  'teams',
+  'containers',
+  'entities',
+  'diagrams',
+  'data-products',
+] as const;
+
+const getCollectionForAdrResourceType = (type: string) => {
+  const match = Object.entries(collectionToResourceMap).find(([, resourceType]) => resourceType === type);
+  return match?.[0];
+};
+
+const getResourcesForCollection = (collection: string, context: ResourceGroupContext): AdrResource[] => {
+  const resourcesByCollection: Partial<Record<(typeof firstClassResourceCollections)[number], AdrResource[]>> = {
+    agents: context.agents || [],
+    services: context.services,
+    events: context.events,
+    commands: context.commands,
+    queries: context.queries,
+    flows: context.flows,
+    channels: context.channels || [],
+    domains: context.domains,
+    systems: context.systems || [],
+    users: context.users || [],
+    teams: context.teams || [],
+    containers: context.containers,
+    entities: context.entities || [],
+    diagrams: context.diagrams,
+    'data-products': context.dataProducts,
+  };
+
+  return resourcesByCollection[collection as (typeof firstClassResourceCollections)[number]] || [];
+};
+
+const resolveAppliedResourceRefs = (adr: Adr, context: ResourceGroupContext) => {
+  return (adr.data.appliesTo || [])
+    .map((pointer) => {
+      const collection = getCollectionForAdrResourceType(pointer.type);
+      if (!collection) return undefined;
+
+      const resourceMap = createVersionedMap(getResourcesForCollection(collection, context) as any[]);
+      const resource = findInMap(resourceMap, pointer.id, pointer.version) as AdrResource | undefined;
+      return resource ? getAdrResourceNodeKey(resource) : undefined;
+    })
+    .filter((ref): ref is string => !!ref);
+};
+
+const buildAdrRelationshipSection = (title: string, icon: string, refs: Adr[]): NavNode | null => {
+  if (refs.length === 0) return null;
+
+  return {
+    type: 'group',
+    title,
+    icon,
+    pages: refs.map(getAdrNodeKey),
+  };
+};
+
+const buildDecisionMakersSection = (decisionMakers: any[]): NavNode | null => {
+  if (decisionMakers.length === 0) return null;
+
+  return {
+    type: 'group',
+    title: 'Decision makers',
+    icon: 'UserCheck',
+    pages: decisionMakers.map((owner) => ({
+      type: 'item',
+      title: owner?.data.name ?? '',
+      href: buildUrl(`/docs/${owner?.collection}/${owner?.data.id}`),
+    })),
+  };
+};
+
+export const buildAdrNode = (adr: Adr, owners: any[], decisionMakers: any[], context: ResourceGroupContext): NavNode => {
+  const relationships = getAdrRelationships(adr, context.adrs);
+  const appliesToRefs = resolveAppliedResourceRefs(adr, context);
+  const hasAttachments = adr.data.attachments && adr.data.attachments.length > 0;
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(adr, 'owners');
+  const renderDecisionMakers = decisionMakers.length > 0 && shouldRenderSideBarSection(adr, 'decisionMakers');
+  const renderRepository = adr.data.repository && shouldRenderSideBarSection(adr, 'repository');
+
+  return {
+    type: 'item',
+    title: adr.data.name,
+    badge: 'Decision record',
+    summary: adr.data.summary,
+    icon: 'ClipboardList',
+    pages: [
+      buildQuickReferenceSection(
+        [
+          { title: 'Overview', href: buildUrl(`/docs/adrs/${adr.data.id}/${adr.data.version}`) },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(adr, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/adrs/${adr.data.id}/${adr.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      appliesToRefs.length > 0 &&
+        shouldRenderSideBarSection(adr, 'appliesTo') && {
+          type: 'group',
+          title: 'Applies to',
+          icon: 'GitBranch',
+          pages: appliesToRefs,
+        },
+      shouldRenderSideBarSection(adr, 'relationships') &&
+        buildAdrRelationshipSection('Supersedes', 'History', relationships.supersedes),
+      shouldRenderSideBarSection(adr, 'relationships') &&
+        buildAdrRelationshipSection('Superseded by', 'History', relationships.supersededBy),
+      shouldRenderSideBarSection(adr, 'relationships') && buildAdrRelationshipSection('Amends', 'Pencil', relationships.amends),
+      shouldRenderSideBarSection(adr, 'relationships') &&
+        buildAdrRelationshipSection('Amended by', 'Pencil', relationships.amendedBy),
+      shouldRenderSideBarSection(adr, 'relationships') &&
+        buildAdrRelationshipSection('Related decisions', 'Link', resolveAdrPointers(adr.data.related, context.adrs)),
+      renderDecisionMakers && buildDecisionMakersSection(decisionMakers),
+      renderOwners && buildOwnersSection(owners),
+      renderRepository && buildRepositorySection(adr.data.repository as { url: string; language: string }),
+      hasAttachments && buildAttachmentsSection(adr.data.attachments as any[]),
+    ].filter(Boolean) as ChildRef[],
+  };
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/agent.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/agent.ts
new file mode 100644
index 000000000..dc7e081db
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/agent.ts
@@ -0,0 +1,143 @@
+import type { CollectionEntry } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
+import {
+  uniqueBy,
+  buildQuickReferenceSection,
+  buildOwnersSection,
+  shouldRenderSideBarSection,
+  buildResourceGroupSections,
+  buildRepositorySection,
+  buildAttachmentsSection,
+  buildDiagramNavItems,
+  buildResourceDocsSection,
+} from './shared';
+import { isChangelogEnabled } from '@utils/feature';
+import { isVisualiserEnabled } from '@utils/feature';
+import { pluralizeMessageType } from '@utils/collections/messages';
+import { iconFieldsForResource } from '@utils/icon';
+
+const uniqueRefs = (refs: string[]) => [...new Set(refs)];
+
+export const buildAgentNode = (
+  agent: CollectionEntry<'agents'>,
+  owners: any[],
+  context: ResourceGroupContext,
+  agentChannels: CollectionEntry<'channels'>[] = [],
+  flowRefs: string[] = []
+): NavNode => {
+  const sendsMessages = agent.data.sends || [];
+  const receivesMessages = agent.data.receives || [];
+
+  const dataStoresInAgent = uniqueBy([...(agent.data.writesTo || []), ...(agent.data.readsFrom || [])], 'id');
+
+  const agentFlows = agent.data.flows || [];
+  const agentFlowRefs = uniqueRefs([
+    ...agentFlows.map((flow) => `flow:${(flow as any).data.id}:${(flow as any).data.version}`),
+    ...flowRefs,
+  ]);
+  const hasFlows = agentFlowRefs.length > 0;
+
+  const hasAttachments = agent.data.attachments && agent.data.attachments.length > 0;
+  const hasDataStores = dataStoresInAgent.length > 0;
+  const resourceGroups = agent.data.resourceGroups || [];
+  const hasResourceGroups = resourceGroups.length > 0;
+
+  const renderResourceGroups = hasResourceGroups && shouldRenderSideBarSection(agent, 'resourceGroups');
+  const renderMessages = shouldRenderSideBarSection(agent, 'messages');
+  const renderVisualiser = isVisualiserEnabled();
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(agent, 'owners');
+  const renderRepository = agent.data.repository && shouldRenderSideBarSection(agent, 'repository');
+  const docsSection = buildResourceDocsSection(
+    'agents',
+    agent.data.id,
+    agent.data.version,
+    context.resourceDocs,
+    context.resourceDocCategories
+  );
+
+  const agentDiagrams = agent.data.diagrams || [];
+  const diagramNavItems = buildDiagramNavItems(agentDiagrams, context.diagrams);
+  const hasDiagrams = diagramNavItems.length > 0;
+
+  return {
+    type: 'item',
+    title: agent.data.name,
+    badge: 'Agent',
+    summary: agent.data.summary,
+    ...iconFieldsForResource(agent.data, 'Bot'),
+    pages: [
+      buildQuickReferenceSection(
+        [
+          { title: 'Overview', href: buildUrl(`/docs/agents/${agent.data.id}/${agent.data.version}`) },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(agent, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/agents/${agent.data.id}/${agent.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      docsSection,
+      renderVisualiser && {
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Map',
+            href: buildUrl(`/visualiser/agents/${agent.data.id}/${agent.data.version}`),
+          },
+        ].filter(Boolean) as ChildRef[],
+      },
+      hasDiagrams && {
+        type: 'group',
+        title: 'Diagrams',
+        icon: 'FileImage',
+        pages: diagramNavItems,
+      },
+      renderResourceGroups && buildResourceGroupSections(resourceGroups, context),
+      hasDataStores && {
+        type: 'group',
+        title: 'State and Persistence',
+        icon: 'Database',
+        pages: dataStoresInAgent.map((dataStore) => `container:${(dataStore as any).data.id}:${(dataStore as any).data.version}`),
+      },
+      sendsMessages.length > 0 &&
+        renderMessages && {
+          type: 'group',
+          title: 'Outbound Messages',
+          icon: 'Mail',
+          pages: sendsMessages.map(
+            (message) => `${pluralizeMessageType(message as any)}:${(message as any).data.id}:${(message as any).data.version}`
+          ),
+        },
+      receivesMessages.length > 0 &&
+        renderMessages && {
+          type: 'group',
+          title: 'Inbound Messages',
+          icon: 'Mail',
+          pages: receivesMessages.map(
+            (receive) => `${pluralizeMessageType(receive as any)}:${(receive as any).data.id}:${(receive as any).data.version}`
+          ),
+        },
+      agentChannels.length > 0 && {
+        type: 'group',
+        title: 'Channels',
+        icon: 'ArrowRightLeft',
+        pages: agentChannels.map((channel) => `channel:${(channel as any).data.id}:${(channel as any).data.version}`),
+      },
+      hasFlows && {
+        type: 'group',
+        // If the agent declares its own flows it owns them ("Flows"); otherwise it is
+        // only referenced as a step in someone else's flow ("Appears in flows").
+        title: agentFlows.length > 0 ? 'Flows' : 'Appears in flows',
+        icon: 'Waypoints',
+        pages: agentFlowRefs,
+      },
+      renderOwners && buildOwnersSection(owners),
+      renderRepository && buildRepositorySection(agent.data.repository as { url: string; language: string }),
+      hasAttachments && buildAttachmentsSection(agent.data.attachments as any[]),
+    ].filter(Boolean) as ChildRef[],
+  };
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/container.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/container.ts
new file mode 100644
index 000000000..a45586f4a
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/container.ts
@@ -0,0 +1,125 @@
+import type { CollectionEntry } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
+import {
+  buildQuickReferenceSection,
+  buildOwnersSection,
+  shouldRenderSideBarSection,
+  buildRepositorySection,
+  buildAttachmentsSection,
+  buildDiagramNavItems,
+  buildResourceDocsSection,
+} from './shared';
+import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
+import { iconFieldsForResource } from '@utils/icon';
+
+export const buildContainerNode = (
+  container: CollectionEntry<'containers'>,
+  owners: any[],
+  context: ResourceGroupContext,
+  flowRefs: string[] = []
+): NavNode => {
+  const servicesWritingToContainer = container.data.servicesThatWriteToContainer || [];
+  const servicesReadingFromContainer = container.data.servicesThatReadFromContainer || [];
+  const dataProductsWritingToContainer = (container.data as any).dataProductsThatWriteToContainer || [];
+  const dataProductsReadingFromContainer = (container.data as any).dataProductsThatReadFromContainer || [];
+
+  // Combine writes: services + data products
+  const allWrites = [
+    ...servicesWritingToContainer.map((s: any) => `service:${s.data.id}:${s.data.version}`),
+    ...dataProductsWritingToContainer.map((dp: any) => `data-product:${dp.data.id}:${dp.data.version}`),
+  ];
+  const renderWrites = allWrites.length > 0 && shouldRenderSideBarSection(container, 'services');
+
+  // Combine reads: services + data products
+  const allReads = [
+    ...servicesReadingFromContainer.map((s: any) => `service:${s.data.id}:${s.data.version}`),
+    ...dataProductsReadingFromContainer.map((dp: any) => `data-product:${dp.data.id}:${dp.data.version}`),
+  ];
+  const renderReads = allReads.length > 0 && shouldRenderSideBarSection(container, 'services');
+  const renderFlows = flowRefs.length > 0 && shouldRenderSideBarSection(container, 'flows');
+
+  const renderVisualiser = isVisualiserEnabled();
+
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(container, 'owners');
+
+  const hasAttachments = container.data.attachments && container.data.attachments.length > 0;
+
+  const renderRepository = container.data.repository && shouldRenderSideBarSection(container, 'repository');
+  const docsSection = buildResourceDocsSection(
+    'containers',
+    container.data.id,
+    container.data.version,
+    context.resourceDocs,
+    context.resourceDocCategories
+  );
+
+  // Diagrams
+  const containerDiagrams = container.data.diagrams || [];
+  const diagramNavItems = buildDiagramNavItems(containerDiagrams, context.diagrams);
+  const hasDiagrams = diagramNavItems.length > 0;
+
+  return {
+    type: 'item',
+    title: container.data.name,
+    badge: 'Container',
+    summary: container.data.summary,
+    ...iconFieldsForResource(container.data, 'Database'),
+    pages: [
+      buildQuickReferenceSection(
+        [
+          {
+            title: 'Overview',
+            href: buildUrl(`/docs/containers/${container.data.id}/${container.data.version}`),
+          },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(container, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/containers/${container.data.id}/${container.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      docsSection,
+      renderVisualiser && {
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Map',
+            href: buildUrl(`/visualiser/containers/${container.data.id}/${container.data.version}`),
+          },
+        ],
+      },
+      hasDiagrams && {
+        type: 'group',
+        title: 'Diagrams',
+        icon: 'FileImage',
+        pages: diagramNavItems,
+      },
+      renderWrites && {
+        type: 'group',
+        title: 'Writes',
+        icon: 'ArrowUpFromLine',
+        pages: allWrites,
+      },
+      renderReads && {
+        type: 'group',
+        title: 'Reads',
+        icon: 'ArrowDownToLine',
+        pages: allReads,
+      },
+      renderFlows && {
+        type: 'group',
+        title: 'Appears in flows',
+        icon: 'Waypoints',
+        pages: flowRefs,
+        visible: flowRefs.length > 0,
+      },
+      renderOwners && buildOwnersSection(owners),
+      renderRepository && buildRepositorySection(container.data.repository as { url: string; language: string }),
+      hasAttachments && buildAttachmentsSection(container.data.attachments as any[]),
+    ].filter(Boolean) as ChildRef[],
+  };
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/data-product.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/data-product.ts
new file mode 100644
index 000000000..16cf7fe62
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/data-product.ts
@@ -0,0 +1,154 @@
+import type { CollectionEntry } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
+import { buildQuickReferenceSection, buildOwnersSection, shouldRenderSideBarSection, buildResourceDocsSection } from './shared';
+import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
+import { getItemsFromCollectionByIdAndSemverOrLatest, sortVersioned } from '@utils/collections/util';
+import { getSchemaFormatFromURL } from '@utils/collections/schemas';
+import { iconFieldsForResource } from '@utils/icon';
+
+type DataProductContext = Pick<
+  ResourceGroupContext,
+  'events' | 'commands' | 'queries' | 'services' | 'containers' | 'resourceDocs' | 'resourceDocCategories'
+> & {
+  channels: CollectionEntry<'channels'>[];
+};
+
+// Get highest version from matched items (semver ranges may return multiple matches)
+const getHighestVersion = <T extends { data: { version: string } }>(items: T[]): T | undefined => {
+  if (items.length === 0) return undefined;
+  if (items.length === 1) return items[0];
+  const sorted = sortVersioned(items, (item) => item.data.version);
+  return sorted[0];
+};
+
+// Resolve a pointer to its collection type and format as sidebar reference
+// Note: Messages use plural keys (events:, commands:, queries:) while other resources use singular
+const resolvePointerToRef = (pointer: { id: string; version?: string }, context: DataProductContext): string | null => {
+  const { id, version } = pointer;
+
+  // Check each collection type using semver resolution - messages use plural keys in the sidebar
+  const events = getItemsFromCollectionByIdAndSemverOrLatest(context.events, id, version);
+  const event = getHighestVersion(events);
+  if (event) return `events:${id}:${event.data.version}`;
+
+  const commands = getItemsFromCollectionByIdAndSemverOrLatest(context.commands, id, version);
+  const command = getHighestVersion(commands);
+  if (command) return `commands:${id}:${command.data.version}`;
+
+  const queries = getItemsFromCollectionByIdAndSemverOrLatest(context.queries, id, version);
+  const query = getHighestVersion(queries);
+  if (query) return `queries:${id}:${query.data.version}`;
+
+  // Non-message resources use singular keys
+  const services = getItemsFromCollectionByIdAndSemverOrLatest(context.services, id, version);
+  const service = getHighestVersion(services);
+  if (service) return `service:${id}:${service.data.version}`;
+
+  const containers = getItemsFromCollectionByIdAndSemverOrLatest(context.containers, id, version);
+  const container = getHighestVersion(containers);
+  if (container) return `container:${id}:${container.data.version}`;
+
+  const channels = getItemsFromCollectionByIdAndSemverOrLatest(context.channels, id, version);
+  const channel = getHighestVersion(channels);
+  if (channel) return `channel:${id}:${channel.data.version}`;
+
+  // Unknown type - skip it
+  return null;
+};
+
+export const buildDataProductNode = (
+  dataProduct: CollectionEntry<'data-products'>,
+  owners: any[],
+  context: DataProductContext,
+  flowRefs: string[] = []
+): NavNode => {
+  const inputs = dataProduct.data.inputs || [];
+  const outputs = dataProduct.data.outputs || [];
+
+  const renderVisualiser = isVisualiserEnabled();
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(dataProduct, 'owners');
+  const renderFlows = flowRefs.length > 0 && shouldRenderSideBarSection(dataProduct, 'flows');
+  const docsSection = buildResourceDocsSection(
+    'data-products',
+    dataProduct.data.id,
+    dataProduct.data.version,
+    context.resourceDocs,
+    context.resourceDocCategories
+  );
+
+  // Resolve inputs and outputs to their proper sidebar references
+  const resolvedInputs = inputs.map((input) => resolvePointerToRef(input, context)).filter(Boolean) as string[];
+  const resolvedOutputs = outputs.map((output) => resolvePointerToRef(output, context)).filter(Boolean) as string[];
+
+  // Extract data contracts from outputs that have a contract field
+  const dataContracts = outputs
+    .filter((output) => output.contract)
+    .map((output) => ({
+      type: 'item' as const,
+      title: `${output.contract!.name} (${getSchemaFormatFromURL(output.contract!.path).toUpperCase()})`,
+      summary: output.contract!.type ? `Type: ${output.contract!.type}` : undefined,
+      href: buildUrl(
+        `/schemas/data-products/${dataProduct.data.id}/${dataProduct.data.version}?contract=${encodeURIComponent(output.contract!.path)}`
+      ),
+    }));
+
+  return {
+    type: 'item',
+    title: dataProduct.data.name,
+    badge: 'Data Product',
+    summary: dataProduct.data.summary,
+    ...iconFieldsForResource(dataProduct.data, 'Package'),
+    pages: [
+      buildQuickReferenceSection(
+        [
+          { title: 'Overview', href: buildUrl(`/docs/data-products/${dataProduct.data.id}/${dataProduct.data.version}`) },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(dataProduct, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/data-products/${dataProduct.data.id}/${dataProduct.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      docsSection,
+      renderVisualiser && {
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Map',
+            href: buildUrl(`/visualiser/data-products/${dataProduct.data.id}/${dataProduct.data.version}`),
+          },
+        ],
+      },
+      resolvedInputs.length > 0 && {
+        type: 'group',
+        title: 'Inputs',
+        icon: 'ArrowDownToLine',
+        pages: resolvedInputs,
+      },
+      resolvedOutputs.length > 0 && {
+        type: 'group',
+        title: 'Outputs',
+        icon: 'ArrowUpFromLine',
+        pages: resolvedOutputs,
+      },
+      dataContracts.length > 0 && {
+        type: 'group',
+        title: 'Data Contracts',
+        icon: 'FileCheck',
+        pages: dataContracts,
+      },
+      renderFlows && {
+        type: 'group',
+        title: 'Appears in flows',
+        icon: 'Waypoints',
+        pages: flowRefs,
+        visible: flowRefs.length > 0,
+      },
+      renderOwners && buildOwnersSection(owners),
+    ].filter(Boolean) as ChildRef[],
+  };
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/domain.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/domain.ts
new file mode 100644
index 000000000..3c8fdc31a
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/domain.ts
@@ -0,0 +1,313 @@
+import type { CollectionEntry } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
+import {
+  buildResourceGroupSections,
+  buildQuickReferenceSection,
+  buildOwnersSection,
+  shouldRenderSideBarSection,
+  buildRepositorySection,
+  buildAttachmentsSection,
+  buildDiagramNavItems,
+  buildResourceDocsSection,
+} from './shared';
+import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
+import { pluralizeMessageType } from '@utils/collections/messages';
+import { getSpecificationsForDomain, hasUbiquitousLanguageTermsWithSubdomainsInCollection } from '@utils/collections/domains';
+import { customIconFieldsForResource } from '@utils/icon';
+
+// Sort resolved collection entries A-Z by their display name (falling back to id).
+const byResourceName = (a: any, b: any) => (a.data?.name || a.data?.id || '').localeCompare(b.data?.name || b.data?.id || '');
+
+export const buildDomainNode = (domain: CollectionEntry<'domains'>, owners: any[], context: ResourceGroupContext): NavNode => {
+  const agentsInDomain = domain.data.agents || [];
+  const renderAgents = agentsInDomain.length > 0 && shouldRenderSideBarSection(domain, 'agents');
+
+  const allServicesInDomain = domain.data.services || [];
+  const servicesInDomain = allServicesInDomain.filter((service) => !(service as any).data?.externalSystem).sort(byResourceName);
+  const externalSystemsInDomain = allServicesInDomain.filter((service) => (service as any).data?.externalSystem);
+  const renderServices = servicesInDomain.length > 0 && shouldRenderSideBarSection(domain, 'services');
+  const renderExternalSystems = externalSystemsInDomain.length > 0 && shouldRenderSideBarSection(domain, 'services');
+
+  const dataProductsInDomain = domain.data['data-products'] || [];
+  const renderDataProducts = dataProductsInDomain.length > 0 && shouldRenderSideBarSection(domain, 'data-products');
+
+  const systemsInDomain = domain.data.systems || [];
+  const renderSystems = systemsInDomain.length > 0 && shouldRenderSideBarSection(domain, 'systems');
+
+  // The domain's System Diagram only has something to show when at least one of
+  // its systems takes part in a context graph (declares relationships or actors). This
+  // mirrors the guard that generates the visualiser page, so we never link to a page
+  // that wasn't generated.
+  const hasSystemContext = systemsInDomain.some((system: any) => {
+    const data = system?.data || system;
+    return (data?.relationships || []).length > 0 || (data?.actors || []).length > 0;
+  });
+
+  const subDomains = domain.data.domains || [];
+  const renderSubDomains = subDomains.length > 0 && shouldRenderSideBarSection(domain, 'subdomains');
+
+  const entitiesInDomain = [...(domain.data.entities || [])].sort(byResourceName);
+  const renderEntities = entitiesInDomain.length > 0 && shouldRenderSideBarSection(domain, 'entities');
+
+  const domainFlows = [...(domain.data.flows || [])].sort(byResourceName);
+  const hasFlows = domainFlows.length > 0;
+
+  const resourceGroups = domain.data.resourceGroups || [];
+  const hasResourceGroups = resourceGroups.length > 0;
+
+  const renderUbiquitousLanguage =
+    hasUbiquitousLanguageTermsWithSubdomainsInCollection(domain, context.ubiquitousLanguages || []) &&
+    shouldRenderSideBarSection(domain, 'ubiquitousLanguage');
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(domain, 'owners');
+
+  const renderVisualiser = isVisualiserEnabled();
+
+  const hasAttachments = domain.data.attachments && domain.data.attachments.length > 0;
+
+  const renderRepository = domain.data.repository && shouldRenderSideBarSection(domain, 'repository');
+  const docsSection = buildResourceDocsSection(
+    'domains',
+    domain.data.id,
+    domain.data.version,
+    context.resourceDocs,
+    context.resourceDocCategories
+  );
+
+  // Domain-level messages (sends/receives)
+  const sendsMessages = domain.data.sends || [];
+  const receivesMessages = domain.data.receives || [];
+  const sortedSendsMessages = [...sendsMessages].sort(byResourceName);
+  const sortedReceivesMessages = [...receivesMessages].sort(byResourceName);
+  const renderMessages = shouldRenderSideBarSection(domain, 'messages');
+
+  // The Resources page/link only makes sense when the domain actually has resources
+  // attached (services, flows, entities or its own messages). Mirrors what the page renders.
+  const hasResources =
+    servicesInDomain.length > 0 ||
+    domainFlows.length > 0 ||
+    entitiesInDomain.length > 0 ||
+    sendsMessages.length > 0 ||
+    receivesMessages.length > 0;
+
+  // The Resource Diagram renders the domain's services, agents, data products and
+  // subdomains (see domains-node-graph). Only link to it when there's something to
+  // draw — otherwise the visualiser page is empty.
+  const hasResourceDiagram =
+    servicesInDomain.length > 0 ||
+    externalSystemsInDomain.length > 0 ||
+    agentsInDomain.length > 0 ||
+    dataProductsInDomain.length > 0 ||
+    subDomains.length > 0;
+
+  // Diagrams
+  const domainDiagrams = domain.data.diagrams || [];
+  const diagramNavItems = buildDiagramNavItems(domainDiagrams, context.diagrams);
+  const hasDiagrams = diagramNavItems.length > 0;
+
+  // Specifications
+  const specifications = getSpecificationsForDomain(domain);
+  const hasSpecifications = specifications.length > 0;
+  const openAPISpecifications = specifications.filter((specification) => specification.type === 'openapi');
+  const asyncAPISpecifications = specifications.filter((specification) => specification.type === 'asyncapi');
+  const graphQLSpecifications = specifications.filter((specification) => specification.type === 'graphql');
+  const renderSpecifications = hasSpecifications && shouldRenderSideBarSection(domain, 'specifications');
+
+  return {
+    type: 'item',
+    title: domain.data.name,
+    badge: 'Domain',
+    summary: domain.data.summary,
+    // Domains use a custom icon when defined, otherwise none — the surrounding
+    // 'Domains' section header (and Domain badge) already convey the type, so the
+    // default Boxes glyph on every item is redundant.
+    ...customIconFieldsForResource(domain.data),
+    pages: [
+      buildQuickReferenceSection(
+        [
+          { title: 'Overview', href: buildUrl(`/docs/domains/${domain.data.id}/${domain.data.version}`) },
+          hasResources && {
+            title: 'Domain Resources',
+            href: buildUrl(`/docs/domains/${domain.data.id}/${domain.data.version}/resources`),
+          },
+          renderUbiquitousLanguage && {
+            title: 'Ubiquitous Language',
+            href: buildUrl(`/docs/domains/${domain.data.id}/language`),
+          },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(domain, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/domains/${domain.data.id}/${domain.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      docsSection,
+      {
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Overview',
+            href: buildUrl(`/architecture/domains/${domain.data.id}/${domain.data.version}`),
+          },
+          renderSystems &&
+            renderVisualiser &&
+            hasSystemContext && {
+              type: 'item',
+              title: 'System Diagram',
+              href: buildUrl(`/visualiser/domains/${domain.data.id}/${domain.data.version}/systems-context`),
+            },
+          renderVisualiser &&
+            hasResourceDiagram && {
+              type: 'item',
+              title: 'Resource Diagram',
+              href: buildUrl(`/visualiser/domains/${domain.data.id}/${domain.data.version}`),
+            },
+          renderEntities &&
+            renderVisualiser && {
+              type: 'item',
+              title: 'Entity Diagram',
+              href: buildUrl(`/visualiser/domains/${domain.data.id}/${domain.data.version}/entity-map`),
+            },
+        ].filter(Boolean) as ChildRef[],
+      },
+      hasDiagrams && {
+        type: 'group',
+        title: 'Diagrams',
+        icon: 'FileImage',
+        pages: diagramNavItems,
+      },
+      renderSpecifications && {
+        type: 'group',
+        title: 'API & Contracts',
+        icon: 'FileCode',
+        pages: [
+          ...openAPISpecifications.map((specification) => ({
+            type: 'item',
+            title: specification.name,
+            leftIcon: '/icons/openapi-black.svg',
+            href: buildUrl(
+              `/docs/domains/${domain.data.id}/${domain.data.version}/spec/${specification.filenameWithoutExtension}`
+            ),
+          })),
+          ...asyncAPISpecifications.map((specification) => ({
+            type: 'item',
+            title: specification.name,
+            leftIcon: '/icons/asyncapi-black.svg',
+            href: buildUrl(
+              `/docs/domains/${domain.data.id}/${domain.data.version}/asyncapi/${specification.filenameWithoutExtension}`
+            ),
+          })),
+          ...graphQLSpecifications.map((specification) => ({
+            type: 'item',
+            title: specification.name,
+            leftIcon: '/icons/graphql-black.svg',
+            href: buildUrl(
+              `/docs/domains/${domain.data.id}/${domain.data.version}/graphql/${specification.filenameWithoutExtension}`
+            ),
+          })),
+        ],
+      },
+      renderSystems && {
+        type: 'group',
+        title: 'Systems',
+        icon: 'Group',
+        pages: systemsInDomain.map((system) => `system:${(system as any).data.id}:${(system as any).data.version}`),
+      },
+      renderSubDomains && {
+        type: 'group',
+        title: 'Subdomains',
+        icon: 'Boxes',
+        pages: subDomains.map((domain) => `domain:${(domain as any).data.id}:${(domain as any).data.version}`),
+      },
+      (renderServices ||
+        hasFlows ||
+        renderEntities ||
+        (renderMessages && (sendsMessages.length > 0 || receivesMessages.length > 0))) && {
+        type: 'group',
+        title: 'Resources',
+        icon: 'Boxes',
+        // Resource type subsections are ordered A-Z by their title, and the
+        // resources within each subsection are ordered A-Z by name (sorted above).
+        pages: (
+          [
+            renderServices && {
+              type: 'group',
+              title: 'Services',
+              subtle: true,
+              icon: 'Server',
+              pages: servicesInDomain.map((service) => `service:${(service as any).data.id}:${(service as any).data.version}`),
+            },
+            hasFlows && {
+              type: 'group',
+              title: 'Flows',
+              subtle: true,
+              icon: 'Waypoints',
+              pages: domainFlows.map((flow) => `flow:${(flow as any).data.id}:${(flow as any).data.version}`),
+            },
+            renderEntities && {
+              type: 'group',
+              title: 'Entities',
+              subtle: true,
+              icon: 'Box',
+              pages: entitiesInDomain.map((entity) => ({
+                type: 'item',
+                title: (entity as any).data?.name || (entity as any).data.id,
+                href: buildUrl(`/docs/entities/${(entity as any).data.id}/${(entity as any).data.version}`),
+              })),
+            },
+            renderMessages &&
+              sendsMessages.length > 0 && {
+                type: 'group',
+                title: 'Domain Events',
+                subtle: true,
+                icon: 'Mail',
+                pages: sortedSendsMessages.map(
+                  (message) =>
+                    `${pluralizeMessageType(message as any)}:${(message as any).data.id}:${(message as any).data.version}`
+                ),
+              },
+            renderMessages &&
+              receivesMessages.length > 0 && {
+                type: 'group',
+                title: 'External Events',
+                subtle: true,
+                icon: 'Mail',
+                pages: sortedReceivesMessages.map(
+                  (receive) =>
+                    `${pluralizeMessageType(receive as any)}:${(receive as any).data.id}:${(receive as any).data.version}`
+                ),
+              },
+          ].filter(Boolean) as NavNode[]
+        ).sort((a, b) => a.title.localeCompare(b.title)) as ChildRef[],
+      },
+
+      ...(hasResourceGroups ? buildResourceGroupSections(resourceGroups, context) : []),
+      renderAgents && {
+        type: 'group',
+        title: 'Agents In Domain',
+        icon: 'Bot',
+        pages: agentsInDomain.map((agent) => `agent:${(agent as any).data.id}:${(agent as any).data.version}`),
+      },
+      renderExternalSystems && {
+        type: 'group',
+        title: 'External Integrations',
+        icon: 'Globe',
+        pages: externalSystemsInDomain.map((service) => `service:${(service as any).data.id}:${(service as any).data.version}`),
+      },
+      renderDataProducts && {
+        type: 'group',
+        title: 'Data Products',
+        icon: 'Package',
+        pages: dataProductsInDomain.map(
+          (dataProduct) => `data-product:${(dataProduct as any).data.id}:${(dataProduct as any).data.version}`
+        ),
+      },
+      renderOwners && buildOwnersSection(owners),
+      renderRepository && buildRepositorySection(domain.data.repository as { url: string; language: string }),
+      hasAttachments && buildAttachmentsSection(domain.data.attachments as any[]),
+    ].filter(Boolean) as ChildRef[],
+  };
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/entity.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/entity.ts
new file mode 100644
index 000000000..580f436a3
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/entity.ts
@@ -0,0 +1,87 @@
+import type { CollectionEntry } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
+import {
+  buildAttachmentsSection,
+  buildOwnersSection,
+  buildQuickReferenceSection,
+  buildResourceDocsSection,
+  shouldRenderSideBarSection,
+} from './shared';
+import { isChangelogEnabled, isVisualiserEnabled } from '@utils/feature';
+import { iconFieldsForResource } from '@utils/icon';
+
+export const buildEntityNode = (entity: CollectionEntry<'entities'>, owners: any[], context: ResourceGroupContext): NavNode => {
+  const domains = entity.data.domains || [];
+  const services = entity.data.services || [];
+
+  const entityMapTargets = [
+    domains.length === 1 && {
+      label: 'Domain',
+      href: buildUrl(`/visualiser/domains/${(domains[0] as any).data.id}/${(domains[0] as any).data.version}/entity-map`),
+    },
+    services.length === 1 && {
+      label: 'Service',
+      href: buildUrl(`/visualiser/services/${(services[0] as any).data.id}/${(services[0] as any).data.version}/entity-map`),
+    },
+  ].filter(Boolean) as { label: string; href: string }[];
+
+  const renderArchitecture = isVisualiserEnabled() && entityMapTargets.length > 0;
+  const renderDomains = domains.length > 0 && shouldRenderSideBarSection(entity, 'domains');
+  const renderServices = services.length > 0 && shouldRenderSideBarSection(entity, 'services');
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(entity, 'owners');
+  const hasAttachments = entity.data.attachments && entity.data.attachments.length > 0;
+
+  const docsSection = buildResourceDocsSection(
+    'entities',
+    entity.data.id,
+    entity.data.version,
+    context.resourceDocs,
+    context.resourceDocCategories
+  );
+
+  return {
+    type: 'item',
+    title: entity.data.name,
+    badge: 'Entity',
+    summary: entity.data.summary,
+    ...iconFieldsForResource(entity.data, 'Box'),
+    pages: [
+      buildQuickReferenceSection(
+        [
+          { title: 'Overview', href: buildUrl(`/docs/entities/${entity.data.id}/${entity.data.version}`) },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(entity, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/entities/${entity.data.id}/${entity.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      docsSection,
+      renderArchitecture && {
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: entityMapTargets.map((target) => ({
+          type: 'item',
+          title: entityMapTargets.length === 1 ? 'Entity Map' : `${target.label} Entity Map`,
+          href: target.href,
+        })),
+      },
+      renderDomains && {
+        type: 'group',
+        title: 'Domains',
+        icon: 'Boxes',
+        pages: domains.map((domain: any) => `domain:${domain.data.id}:${domain.data.version}`),
+      },
+      renderServices && {
+        type: 'group',
+        title: 'Services',
+        icon: 'Server',
+        pages: services.map((service: any) => `service:${service.data.id}:${service.data.version}`),
+      },
+      renderOwners && buildOwnersSection(owners),
+      hasAttachments && buildAttachmentsSection(entity.data.attachments as any[]),
+    ].filter(Boolean) as ChildRef[],
+  };
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/flow.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/flow.ts
new file mode 100644
index 000000000..27590a487
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/flow.ts
@@ -0,0 +1,182 @@
+import type { CollectionEntry } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
+import { buildQuickReferenceSection, buildResourceDocsSection, shouldRenderSideBarSection } from './shared';
+import { isChangelogEnabled } from '@utils/feature';
+import { createVersionedMap, findInMap } from '@utils/collections/util';
+import { pluralizeMessageType } from '@utils/collections/messages';
+
+type VersionedEntry = { collection?: string; data: { id: string; version: string } };
+type VersionedEntryMap<T extends VersionedEntry> = Map<string, T[]>;
+
+const uniqueRefs = (refs: string[]) => [...new Set(refs)];
+
+const resolvePointer = <T extends VersionedEntry>(
+  map: VersionedEntryMap<T>,
+  pointer: { id: string; version?: string }
+): T | undefined => {
+  return findInMap(map, pointer.id, pointer.version);
+};
+
+const resolveMessageStep = (
+  step: any,
+  maps: {
+    eventMap: VersionedEntryMap<CollectionEntry<'events'>>;
+    commandMap: VersionedEntryMap<CollectionEntry<'commands'>>;
+    queryMap: VersionedEntryMap<CollectionEntry<'queries'>>;
+  }
+): string | null => {
+  if (!step.message) return null;
+
+  const hydratedMessage = Array.isArray(step.message) ? step.message[0] : undefined;
+  if (hydratedMessage?.collection && hydratedMessage?.data) {
+    return `${pluralizeMessageType(hydratedMessage as any)}:${hydratedMessage.data.id}:${hydratedMessage.data.version}`;
+  }
+
+  const pointer = Array.isArray(step.message) ? undefined : step.message;
+  if (!pointer?.id) return null;
+
+  const message =
+    resolvePointer(maps.eventMap, pointer) || resolvePointer(maps.commandMap, pointer) || resolvePointer(maps.queryMap, pointer);
+
+  return message ? `${pluralizeMessageType(message as any)}:${message.data.id}:${message.data.version}` : null;
+};
+
+export const buildFlowNode = (flow: CollectionEntry<'flows'>, context: ResourceGroupContext): NavNode => {
+  const docsSection = buildResourceDocsSection(
+    'flows',
+    flow.data.id,
+    flow.data.version,
+    context.resourceDocs,
+    context.resourceDocCategories
+  );
+  const steps = flow.data.steps || [];
+  const eventMap = createVersionedMap(context.events);
+  const commandMap = createVersionedMap(context.commands);
+  const queryMap = createVersionedMap(context.queries);
+  const agentMap = createVersionedMap(context.agents || []);
+  const serviceMap = createVersionedMap(context.services);
+  const flowMap = createVersionedMap(context.flows);
+  const containerMap = createVersionedMap(context.containers);
+  const dataProductMap = createVersionedMap(context.dataProducts);
+  const messageRefs = uniqueRefs(
+    steps.map((step) => resolveMessageStep(step, { eventMap, commandMap, queryMap })).filter(Boolean) as string[]
+  );
+  const serviceRefs = uniqueRefs(
+    steps
+      .map((step) => (step.service ? resolvePointer(serviceMap, step.service) : undefined))
+      .filter(Boolean)
+      .map((service) => `service:${service!.data.id}:${service!.data.version}`)
+  );
+  const agentRefs = uniqueRefs(
+    steps
+      .map((step: any) => {
+        const hydratedAgent = Array.isArray(step.agent) ? step.agent[0] : undefined;
+        if (hydratedAgent?.collection && hydratedAgent?.data) return hydratedAgent;
+
+        const pointer = Array.isArray(step.agent) ? undefined : step.agent;
+        return pointer ? resolvePointer(agentMap, pointer) : undefined;
+      })
+      .filter(Boolean)
+      .map((agent) => `agent:${agent!.data.id}:${agent!.data.version}`)
+  );
+  const flowRefs = uniqueRefs(
+    steps
+      .map((step) => (step.flow ? resolvePointer(flowMap, step.flow) : undefined))
+      .filter(Boolean)
+      .map((referencedFlow) => `flow:${referencedFlow!.data.id}:${referencedFlow!.data.version}`)
+  );
+  const containerRefs = uniqueRefs(
+    steps
+      .map((step: any) => {
+        const hydratedContainer = Array.isArray(step.container) ? step.container[0] : undefined;
+        if (hydratedContainer?.collection && hydratedContainer?.data) return hydratedContainer;
+
+        const pointer = Array.isArray(step.container) ? undefined : step.container;
+        return pointer ? resolvePointer(containerMap, pointer) : undefined;
+      })
+      .filter(Boolean)
+      .map((container) => `container:${container!.data.id}:${container!.data.version}`)
+  );
+  const dataProductRefs = uniqueRefs(
+    steps
+      .map((step: any) => {
+        const hydratedDataProduct = Array.isArray(step.dataProduct) ? step.dataProduct[0] : undefined;
+        if (hydratedDataProduct?.collection && hydratedDataProduct?.data) return hydratedDataProduct;
+
+        const pointer = Array.isArray(step.dataProduct) ? undefined : step.dataProduct;
+        return pointer ? resolvePointer(dataProductMap, pointer) : undefined;
+      })
+      .filter(Boolean)
+      .map((dataProduct) => `data-product:${dataProduct!.data.id}:${dataProduct!.data.version}`)
+  );
+
+  return {
+    type: 'item',
+    title: flow.data.name,
+    icon: 'Waypoint',
+    badge: 'Flow',
+    summary: flow.data.summary,
+    pages: [
+      buildQuickReferenceSection(
+        [
+          { title: 'Overview', href: buildUrl(`/docs/flows/${flow.data.id}/${flow.data.version}`) },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(flow, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/flows/${flow.data.id}/${flow.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      docsSection,
+      {
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Flow Diagram',
+            href: buildUrl(`/visualiser/flows/${flow.data.id}/${flow.data.version}`),
+          },
+        ].filter(Boolean) as ChildRef[],
+      },
+      messageRefs.length > 0 && {
+        type: 'group',
+        title: 'Messages',
+        icon: 'Mail',
+        pages: messageRefs,
+      },
+      serviceRefs.length > 0 && {
+        type: 'group',
+        title: 'Services',
+        icon: 'Server',
+        pages: serviceRefs,
+      },
+      agentRefs.length > 0 && {
+        type: 'group',
+        title: 'Agents',
+        icon: 'Bot',
+        pages: agentRefs,
+      },
+      flowRefs.length > 0 && {
+        type: 'group',
+        title: 'Subflows',
+        icon: 'Waypoints',
+        pages: flowRefs,
+      },
+      containerRefs.length > 0 && {
+        type: 'group',
+        title: 'Data Stores',
+        icon: 'Database',
+        pages: containerRefs,
+      },
+      dataProductRefs.length > 0 && {
+        type: 'group',
+        title: 'Data Products',
+        icon: 'Package',
+        pages: dataProductRefs,
+      },
+    ].filter(Boolean) as ChildRef[],
+  };
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/message.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/message.ts
new file mode 100644
index 000000000..f55987bed
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/message.ts
@@ -0,0 +1,178 @@
+import type { CollectionEntry } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import { getSchemaFormatFromURL } from '@utils/collections/schemas';
+import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
+import {
+  buildQuickReferenceSection,
+  buildOwnersSection,
+  shouldRenderSideBarSection,
+  buildRepositorySection,
+  buildAttachmentsSection,
+  buildDiagramNavItems,
+  buildResourceDocsSection,
+} from './shared';
+import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
+import { iconFieldsForResource } from '@utils/icon';
+import { collectionToResourceMap } from '@utils/collections/util';
+
+type MessageSchemaEntry = CollectionEntry<'schemas'>;
+
+const getProducerConsumerPageRef = (resource: any) => {
+  const resourceType = collectionToResourceMap[resource.collection as keyof typeof collectionToResourceMap];
+  return `${resourceType}:${resource.data.id}:${resource.data.version}`;
+};
+
+const getSchemasForMessage = (
+  message: CollectionEntry<'events' | 'commands' | 'queries'>,
+  schemas: MessageSchemaEntry[] = []
+) => {
+  return schemas.filter(
+    (schema) =>
+      schema.data.message.collection === message.collection &&
+      schema.data.message.id === message.data.id &&
+      schema.data.message.version === message.data.version
+  );
+};
+
+const getSchemaNavTitle = (schemas: MessageSchemaEntry[]) => {
+  if (schemas.length > 1) return 'Schemas';
+
+  const schemaPath = schemas[0]?.data.file || schemas[0]?.data.source.path || schemas[0]?.data.ref || schemas[0]?.id;
+  const format = schemaPath ? getSchemaFormatFromURL(schemaPath) : schemas[0]?.data.format;
+  return format ? `Schema (${format.toUpperCase()})` : 'Schema';
+};
+
+export const buildMessageNode = (
+  message: CollectionEntry<'events' | 'commands' | 'queries'>,
+  owners: any[],
+  context: ResourceGroupContext,
+  hasFieldUsage: boolean = false,
+  flowRefs: string[] = []
+): NavNode => {
+  const producers = message.data.producers || [];
+  const consumers = message.data.consumers || [];
+  const collection = message.collection;
+
+  const renderProducers = producers.length > 0 && shouldRenderSideBarSection(message, 'producers');
+  const renderConsumers = consumers.length > 0 && shouldRenderSideBarSection(message, 'consumers');
+  const renderFlows = flowRefs.length > 0 && shouldRenderSideBarSection(message, 'flows');
+  const renderRepository = message.data.repository && shouldRenderSideBarSection(message, 'repository');
+
+  // Determine badge based on collection type
+  const badgeMap: Record<string, string> = {
+    events: 'Event',
+    commands: 'Command',
+    queries: 'Query',
+  };
+  const badge = badgeMap[collection] || 'Message';
+
+  const iconMap: Record<string, string> = {
+    events: 'Zap',
+    commands: 'MessageSquare',
+    queries: 'Search',
+  };
+  const defaultIcon = iconMap[collection] || 'Mail';
+
+  const resolvedSchemas = getSchemasForMessage(message, context.schemas);
+  const hasSchema = resolvedSchemas.length > 0;
+  const renderVisualiser = isVisualiserEnabled();
+  const docsSection = buildResourceDocsSection(
+    collection as 'events' | 'commands' | 'queries',
+    message.data.id,
+    message.data.version,
+    context.resourceDocs,
+    context.resourceDocCategories
+  );
+
+  const hasAttachments = message.data.attachments && message.data.attachments.length > 0;
+
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(message, 'owners');
+
+  // Diagrams
+  const messageDiagrams = message.data.diagrams || [];
+  const diagramNavItems = buildDiagramNavItems(messageDiagrams, context.diagrams);
+  const hasDiagrams = diagramNavItems.length > 0;
+
+  return {
+    type: 'item',
+    title: message.data.name,
+    badge,
+    summary: message.data.summary,
+    ...iconFieldsForResource(message.data, defaultIcon),
+    pages: [
+      buildQuickReferenceSection(
+        [
+          {
+            title: 'Overview',
+            href: buildUrl(`/docs/${collection}/${message.data.id}/${message.data.version}`),
+          },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(message, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/${collection}/${message.data.id}/${message.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      docsSection,
+      renderVisualiser && {
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Map',
+            href: buildUrl(`/visualiser/${collection}/${message.data.id}/${message.data.version}`),
+          },
+        ],
+      },
+      hasDiagrams && {
+        type: 'group',
+        title: 'Diagrams',
+        icon: 'FileImage',
+        pages: diagramNavItems,
+      },
+      hasSchema && {
+        type: 'group',
+        title: 'API & Contracts',
+        icon: 'FileJson',
+        pages: [
+          {
+            type: 'item',
+            title: getSchemaNavTitle(resolvedSchemas),
+            href: buildUrl(`/schemas/${collection}/${message.data.id}/${message.data.version}`),
+          },
+          hasFieldUsage && {
+            type: 'item',
+            title: 'Field Usage',
+            href: buildUrl(`/docs/${collection}/${message.data.id}/${message.data.version}/field-lineage`),
+          },
+        ].filter(Boolean),
+      },
+      renderProducers && {
+        type: 'group',
+        title: 'Producers',
+        icon: 'Server',
+        pages: producers.map(getProducerConsumerPageRef),
+        visible: producers.length > 0,
+      },
+      renderConsumers && {
+        type: 'group',
+        title: 'Consumers',
+        icon: 'Server',
+        pages: consumers.map(getProducerConsumerPageRef),
+        visible: consumers.length > 0,
+      },
+      renderFlows && {
+        type: 'group',
+        title: 'Appears in flows',
+        icon: 'Waypoints',
+        pages: flowRefs,
+        visible: flowRefs.length > 0,
+      },
+      renderOwners && buildOwnersSection(owners),
+      renderRepository && buildRepositorySection(message.data.repository as { url: string; language: string }),
+      hasAttachments && buildAttachmentsSection(message.data.attachments as any[]),
+    ].filter(Boolean) as ChildRef[],
+  };
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/service.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/service.ts
new file mode 100644
index 000000000..26b90caf4
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/service.ts
@@ -0,0 +1,216 @@
+import type { CollectionEntry } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import { getSpecificationsForService } from '@utils/collections/services';
+import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
+import {
+  uniqueBy,
+  buildQuickReferenceSection,
+  buildOwnersSection,
+  shouldRenderSideBarSection,
+  buildResourceGroupSections,
+  buildRepositorySection,
+  buildAttachmentsSection,
+  buildDiagramNavItems,
+  buildResourceDocsSection,
+} from './shared';
+import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
+import { pluralizeMessageType } from '@utils/collections/messages';
+import { iconFieldsForResource } from '@utils/icon';
+
+const uniqueRefs = (refs: string[]) => [...new Set(refs)];
+
+export const buildServiceNode = (
+  service: CollectionEntry<'services'>,
+  owners: any[],
+  context: ResourceGroupContext,
+  serviceChannels: CollectionEntry<'channels'>[] = [],
+  flowRefs: string[] = []
+): NavNode => {
+  const sendsMessages = service.data.sends || [];
+  const receivesMessages = service.data.receives || [];
+  const serviceEntities = service.data.entities || [];
+
+  const specifications = getSpecificationsForService(service);
+  const hasSpecifications = specifications.length > 0;
+  const openAPISpecifications = specifications.filter((specification) => specification.type === 'openapi');
+  const asyncAPISpecifications = specifications.filter((specification) => specification.type === 'asyncapi');
+  const graphQLSpecifications = specifications.filter((specification) => specification.type === 'graphql');
+
+  const dataStoresInService = uniqueBy([...(service.data.writesTo || []), ...(service.data.readsFrom || [])], 'id');
+
+  const serviceFlows = service.data.flows || [];
+  const serviceFlowRefs = uniqueRefs([
+    ...serviceFlows.map((flow) => `flow:${(flow as any).data.id}:${(flow as any).data.version}`),
+    ...flowRefs,
+  ]);
+  const hasFlows = serviceFlowRefs.length > 0;
+
+  const hasAttachments = service.data.attachments && service.data.attachments.length > 0;
+
+  const hasDataStores = dataStoresInService.length > 0;
+  const resourceGroups = service.data.resourceGroups || [];
+  const hasResourceGroups = resourceGroups.length > 0;
+
+  const renderResourceGroups = hasResourceGroups && shouldRenderSideBarSection(service, 'resourceGroups');
+  const renderVisualiser = isVisualiserEnabled();
+  const renderMessages = shouldRenderSideBarSection(service, 'messages');
+  const renderSpecifications = hasSpecifications && shouldRenderSideBarSection(service, 'specifications');
+  const renderEntities = serviceEntities.length > 0 && shouldRenderSideBarSection(service, 'entities');
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(service, 'owners');
+  const renderRepository = service.data.repository && shouldRenderSideBarSection(service, 'repository');
+  const docsSection = buildResourceDocsSection(
+    'services',
+    service.data.id,
+    service.data.version,
+    context.resourceDocs,
+    context.resourceDocCategories
+  );
+
+  // Diagrams
+  const serviceDiagrams = service.data.diagrams || [];
+  const diagramNavItems = buildDiagramNavItems(serviceDiagrams, context.diagrams);
+  const hasDiagrams = diagramNavItems.length > 0;
+
+  const isExternalSystem = !!service.data.externalSystem;
+
+  return {
+    type: 'item',
+    title: service.data.name,
+    badge: isExternalSystem ? 'External System' : 'Service',
+    summary: service.data.summary,
+    ...iconFieldsForResource(service.data, isExternalSystem ? 'Globe' : 'Server'),
+    pages: [
+      buildQuickReferenceSection(
+        [
+          { title: 'Overview', href: buildUrl(`/docs/services/${service.data.id}/${service.data.version}`) },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(service, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/services/${service.data.id}/${service.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      docsSection,
+      {
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Overview',
+            href: buildUrl(`/architecture/services/${service.data.id}/${service.data.version}`),
+          },
+          renderVisualiser && {
+            type: 'item',
+            title: 'Map',
+            href: buildUrl(`/visualiser/services/${service.data.id}/${service.data.version}`),
+          },
+          renderVisualiser &&
+            renderEntities && {
+              type: 'item',
+              title: 'Entity Map',
+              href: buildUrl(`/visualiser/services/${service.data.id}/${service.data.version}/entity-map`),
+            },
+          renderVisualiser &&
+            hasDataStores && {
+              type: 'item',
+              title: 'Data Dependency Graph',
+              href: buildUrl(`/visualiser/services/${service.data.id}/${service.data.version}/data`),
+            },
+        ].filter(Boolean) as ChildRef[],
+      },
+      hasDiagrams && {
+        type: 'group',
+        title: 'Diagrams',
+        icon: 'FileImage',
+        pages: diagramNavItems,
+      },
+      renderSpecifications && {
+        type: 'group',
+        title: 'API & Contracts',
+        icon: 'FileCode',
+        pages: [
+          ...openAPISpecifications.map((specification) => ({
+            type: 'item',
+            title: `${specification.name}`,
+            leftIcon: '/icons/openapi-black.svg',
+            href: buildUrl(
+              `/docs/services/${service.data.id}/${service.data.version}/spec/${specification.filenameWithoutExtension}`
+            ),
+          })),
+          ...asyncAPISpecifications.map((specification) => ({
+            type: 'item',
+            title: `${specification.name}`,
+            leftIcon: '/icons/asyncapi-black.svg',
+            href: buildUrl(
+              `/docs/services/${service.data.id}/${service.data.version}/asyncapi/${specification.filenameWithoutExtension}`
+            ),
+          })),
+          ...graphQLSpecifications.map((specification) => ({
+            type: 'item',
+            title: `${specification.name}`,
+            leftIcon: '/icons/graphql-black.svg',
+            href: buildUrl(
+              `/docs/services/${service.data.id}/${service.data.version}/graphql/${specification.filenameWithoutExtension}`
+            ),
+          })),
+        ],
+      },
+      renderResourceGroups && buildResourceGroupSections(resourceGroups, context),
+      hasDataStores && {
+        type: 'group',
+        title: 'State and Persistence',
+        icon: 'Database',
+        pages: dataStoresInService.map(
+          (dataStore) => `container:${(dataStore as any).data.id}:${(dataStore as any).data.version}`
+        ),
+      },
+      renderEntities && {
+        type: 'group',
+        title: 'Entities',
+        icon: 'Box',
+        pages: serviceEntities.map((entity) => ({
+          type: 'item',
+          title: (entity as any).data?.name || (entity as any).data.id,
+          href: buildUrl(`/docs/entities/${(entity as any).data.id}/${(entity as any).data.version}`),
+        })),
+      },
+      sendsMessages.length > 0 &&
+        renderMessages && {
+          type: 'group',
+          title: 'Outbound Messages',
+          icon: 'Mail',
+          pages: sendsMessages.map(
+            (message) => `${pluralizeMessageType(message as any)}:${(message as any).data.id}:${(message as any).data.version}`
+          ),
+        },
+      receivesMessages.length > 0 &&
+        renderMessages && {
+          type: 'group',
+          title: 'Inbound Messages',
+          icon: 'Mail',
+          pages: receivesMessages.map(
+            (receive) => `${pluralizeMessageType(receive as any)}:${(receive as any).data.id}:${(receive as any).data.version}`
+          ),
+        },
+      serviceChannels.length > 0 && {
+        type: 'group',
+        title: 'Channels',
+        icon: 'ArrowRightLeft',
+        pages: serviceChannels.map((channel) => `channel:${(channel as any).data.id}:${(channel as any).data.version}`),
+      },
+      hasFlows && {
+        type: 'group',
+        // If the service declares its own flows it owns them ("Flows"); otherwise it is
+        // only referenced as a step in someone else's flow ("Appears in flows").
+        title: serviceFlows.length > 0 ? 'Flows' : 'Appears in flows',
+        icon: 'Waypoints',
+        pages: serviceFlowRefs,
+      },
+      renderOwners && buildOwnersSection(owners),
+      renderRepository && buildRepositorySection(service.data.repository as { url: string; language: string }),
+      hasAttachments && buildAttachmentsSection(service.data.attachments as any[]),
+    ].filter(Boolean) as ChildRef[],
+  };
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/shared.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/shared.ts
new file mode 100644
index 000000000..08c5c906b
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/shared.ts
@@ -0,0 +1,325 @@
+import type { ResourceGroup } from '@eventcatalog/sdk';
+import type { CollectionEntry } from 'astro:content';
+import { getLatestVersionInCollectionById } from '@utils/collections/util';
+import { getAdrNodeKey, getAdrsForResource, type Adr, type AdrResource } from '@utils/collections/adrs';
+import { buildUrl } from '@utils/url-builder';
+import {
+  getGroupedResourceDocsByType,
+  type ResourceCollection,
+  type ResourceDocEntry,
+  type ResourceDocCategoryEntry,
+} from '@utils/collections/resource-docs';
+
+/**
+ * A child reference can be:
+ * - A string key (resolved from nodes map)
+ * - An inline node definition
+ */
+export type ChildRef = string | NavNode;
+
+/**
+ * A navigation node (can be section or item)
+ */
+export type NavNode = {
+  type: 'group' | 'item';
+  title: string;
+  icon?: string; // Lucide icon name
+  subtle?: boolean; // Render lightweight styling for nested subgroup headers
+  leftIcon?: string; // Path to SVG icon shown on the left of the label
+  href?: string; // URL (for leaf items)
+  external?: boolean; // If true, the item will open in a new tab
+  pages?: ChildRef[]; // Can mix keys and inline nodes
+  visible?: boolean; // If false, hide this node (default: true)
+  badge?: string; // Category badge shown in header (e.g., "Domain", "Service", "Message")
+  summary?: string; // Short description of the item
+};
+
+/**
+ * The flat navigation data structure
+ */
+export type NavigationData = {
+  roots: ChildRef[]; // What to show at top level
+  nodes: Record<string, NavNode | string>; // Flat map of nodes by key, strings are references to other keys (e.g., unversioned aliases)
+};
+
+export const uniqueBy = <T>(array: T[], key: keyof T): T[] => {
+  const seen = new Set();
+  return array.filter((item) => {
+    const value = item[key];
+    if (seen.has(value)) {
+      return false;
+    }
+    seen.add(value);
+    return true;
+  });
+};
+
+export type ResourceGroupContext = {
+  agents?: CollectionEntry<'agents'>[];
+  services: CollectionEntry<'services'>[];
+  domains: CollectionEntry<'domains'>[];
+  systems?: CollectionEntry<'systems'>[];
+  events: CollectionEntry<'events'>[];
+  commands: CollectionEntry<'commands'>[];
+  queries: CollectionEntry<'queries'>[];
+  flows: CollectionEntry<'flows'>[];
+  channels?: CollectionEntry<'channels'>[];
+  containers: CollectionEntry<'containers'>[];
+  entities?: CollectionEntry<'entities'>[];
+  dataProducts: CollectionEntry<'data-products'>[];
+  ubiquitousLanguages?: CollectionEntry<'ubiquitousLanguages'>[];
+  diagrams: CollectionEntry<'diagrams'>[];
+  schemas?: CollectionEntry<'schemas'>[];
+  adrs: Adr[];
+  users?: CollectionEntry<'users'>[];
+  teams?: CollectionEntry<'teams'>[];
+  resourceDocs: ResourceDocEntry[];
+  resourceDocCategories: ResourceDocCategoryEntry[];
+};
+
+export const buildQuickReferenceSection = (items: { title: string; href: string }[]): NavNode => ({
+  type: 'group',
+  title: 'Quick Reference',
+  icon: 'BookOpen',
+  pages: items.map((item) => ({
+    type: 'item',
+    title: item.title,
+    href: item.href,
+  })),
+});
+
+export const buildOwnersSection = (owners: any[]): NavNode | null => {
+  if (owners.length === 0) return null;
+  return {
+    type: 'group',
+    title: 'Owners',
+    icon: 'Users',
+    pages: owners.map((owner) => ({
+      type: 'item',
+      title: owner?.data.name ?? '',
+      href: buildUrl(`/docs/${owner?.collection}/${owner?.data.id}`),
+    })),
+    visible: true,
+  };
+};
+
+const byAdrName = (a: Adr, b: Adr) => {
+  const name = (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  if (name !== 0) return name;
+  return a.data.id.localeCompare(b.data.id);
+};
+
+export const buildArchitectureDecisionsSection = (resource: AdrResource, adrs: Adr[]): NavNode | null => {
+  const relatedAdrs = getAdrsForResource(resource, adrs);
+  if (relatedAdrs.length === 0) return null;
+
+  return {
+    type: 'group',
+    title: 'Decision Records',
+    icon: 'ClipboardList',
+    pages: [...relatedAdrs].sort(byAdrName).map(getAdrNodeKey),
+  };
+};
+
+const isOwnersSection = (page: ChildRef) => typeof page !== 'string' && page.title === 'Owners';
+
+const insertBeforeOwnersSection = (pages: ChildRef[], section: NavNode) => {
+  const ownersSectionIndex = pages.findIndex(isOwnersSection);
+  if (ownersSectionIndex === -1) return [...pages, section];
+
+  return [...pages.slice(0, ownersSectionIndex), section, ...pages.slice(ownersSectionIndex)];
+};
+
+const getPagesForDecisionSection = (node: NavNode): ChildRef[] => {
+  if (node.pages && node.pages.length > 0) return node.pages;
+  if (!node.href) return [];
+
+  return [
+    {
+      type: 'item',
+      title: 'Overview',
+      href: node.href,
+    },
+  ];
+};
+
+export const withArchitectureDecisionsSection = (node: NavNode, resource: AdrResource, adrs: Adr[]): NavNode => {
+  const section = buildArchitectureDecisionsSection(resource, adrs);
+  if (!section || !shouldRenderSideBarSection(resource, 'architectureDecisions')) return node;
+
+  return {
+    ...node,
+    pages: insertBeforeOwnersSection(getPagesForDecisionSection(node), section),
+  };
+};
+
+export const buildRepositorySection = (repository: { url: string; language: string }): NavNode | null => {
+  if (!repository) return null;
+  return {
+    type: 'group',
+    title: 'Code',
+    icon: 'Code',
+    pages: [
+      {
+        type: 'item',
+        title: repository.url,
+        href: repository.url,
+      },
+    ],
+  };
+};
+
+export const buildAttachmentsSection = (attachments: any[]): NavNode | null => {
+  if (!attachments) return null;
+  return {
+    type: 'group',
+    title: 'Attachments',
+    icon: 'File',
+    pages: attachments.map((attachment) => ({
+      type: 'item',
+      title: attachment.title,
+      href: attachment.url,
+    })),
+  };
+};
+
+export const buildResourceDocsSection = (
+  collection: ResourceCollection,
+  id: string,
+  version: string,
+  resourceDocs: ResourceDocEntry[],
+  resourceDocCategories: ResourceDocCategoryEntry[]
+): NavNode | null => {
+  const docsForResource = resourceDocs.filter(
+    (doc) => doc.data.resourceCollection === collection && doc.data.resourceId === id && doc.data.resourceVersion === version
+  );
+
+  if (docsForResource.length === 0) {
+    return null;
+  }
+
+  const categoriesForResource = resourceDocCategories.filter(
+    (category) =>
+      category.data.resourceCollection === collection &&
+      category.data.resourceId === id &&
+      category.data.resourceVersion === version
+  );
+
+  const groupedDocs = getGroupedResourceDocsByType(docsForResource, {
+    latestOnly: true,
+    categories: categoriesForResource,
+  });
+
+  if (groupedDocs.length === 0) {
+    return null;
+  }
+
+  const typeLabelMap: Record<string, string> = {
+    adrs: 'ADR',
+    runbooks: 'Runbook',
+    contracts: 'Contract',
+    troubleshooting: 'Troubleshooting',
+    guides: 'Guide',
+  };
+
+  const toTypeLabel = (value: string) => {
+    if (typeLabelMap[value]) {
+      return typeLabelMap[value];
+    }
+
+    const normalized = value
+      .split(/[-_\s]+/)
+      .filter(Boolean)
+      .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+      .join(' ');
+
+    return normalized || 'Doc';
+  };
+
+  return {
+    type: 'group',
+    title: 'Documentation',
+    icon: 'BookText',
+    pages: groupedDocs.map((group) => ({
+      type: 'group',
+      title: group.label || toTypeLabel(group.type),
+      subtle: true,
+      pages: group.docs.map((doc) => ({
+        type: 'item',
+        title: doc.data.title || doc.data.id,
+        href: buildUrl(
+          `/docs/${collection}/${id}/${version}/${encodeURIComponent(doc.data.type)}/${encodeURIComponent(doc.data.id)}`
+        ),
+      })),
+    })),
+  };
+};
+
+export const buildResourceGroupSections = (resourceGroups: ResourceGroup[], context: ResourceGroupContext) => {
+  return resourceGroups.map((resourceGroup) => buildResourceGroupSection(resourceGroup, context));
+};
+
+const buildResourceGroupSection = (resourceGroup: ResourceGroup, context: ResourceGroupContext) => {
+  // Only render resource groups that have a type
+  const resourcesWithTypes = resourceGroup.items.filter((item) => item.type !== undefined);
+
+  if (resourcesWithTypes.length === 0) {
+    return null;
+  }
+
+  // If no version is provided, we need to get the latest version
+  const resourcesWithVersions = resourcesWithTypes.map((item) => {
+    let collection: any[] = [];
+    const itemType = item.type as string;
+
+    if (itemType === 'agent') collection = context.agents || [];
+    else if (itemType === 'service') collection = context.services;
+    else if (itemType === 'domain') collection = context.domains;
+    else if (itemType === 'event') collection = context.events;
+    else if (itemType === 'command') collection = context.commands;
+    else if (itemType === 'query') collection = context.queries;
+    else if (itemType === 'flow') collection = context.flows;
+    else if (itemType === 'container') collection = context.containers;
+
+    if (item.version === undefined || item.version === 'latest') {
+      return { ...item, version: getLatestVersionInCollectionById(collection, item.id as string) };
+    }
+    return item;
+  });
+
+  return {
+    type: 'group',
+    title: resourceGroup.title,
+    icon: 'Box',
+    pages: resourcesWithVersions.map((item) => {
+      const type = ['event', 'command', 'query'].includes(item.type as string) ? 'message' : item.type;
+      return `${type}:${item.id}:${item.version}`;
+    }),
+  };
+};
+
+export const shouldRenderSideBarSection = (resource: any, section: string) => {
+  if (!resource.data.detailsPanel) {
+    return true;
+  }
+  return resource.data.detailsPanel[section]?.visible ?? true;
+};
+
+export const buildDiagramNavItems = (
+  diagrams: Array<{ id: string; version?: string }> | undefined,
+  allDiagrams: CollectionEntry<'diagrams'>[]
+): NavNode[] => {
+  if (!diagrams || diagrams.length === 0) return [];
+
+  return diagrams.map((ref) => {
+    const diagram = allDiagrams.find(
+      (d) => d.data.id === ref.id && (ref.version === 'latest' || !ref.version || d.data.version === ref.version)
+    );
+    const version = diagram?.data.version || ref.version || 'latest';
+    return {
+      type: 'item' as const,
+      title: diagram?.data.name || ref.id,
+      href: buildUrl(`/diagrams/${ref.id}/${version}`),
+    };
+  });
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/builders/system.ts b/packages/core/eventcatalog/src/stores/sidebar-store/builders/system.ts
new file mode 100644
index 000000000..c60cbfdd2
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/builders/system.ts
@@ -0,0 +1,166 @@
+import type { CollectionEntry } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
+import {
+  buildQuickReferenceSection,
+  buildOwnersSection,
+  shouldRenderSideBarSection,
+  buildRepositorySection,
+  buildAttachmentsSection,
+  buildDiagramNavItems,
+  buildResourceDocsSection,
+} from './shared';
+import { isChangelogEnabled, isVisualiserEnabled } from '@utils/feature';
+import { customIconFieldsForResource } from '@utils/icon';
+
+// Sort resolved collection entries A-Z by their display name (falling back to id).
+const byResourceName = (a: any, b: any) => (a.data?.name || a.data?.id || '').localeCompare(b.data?.name || b.data?.id || '');
+
+export const buildSystemNode = (system: CollectionEntry<'systems'>, owners: any[], context: ResourceGroupContext): NavNode => {
+  const servicesInSystem = [...(system.data.services || [])].sort(byResourceName);
+  const renderServices = servicesInSystem.length > 0 && shouldRenderSideBarSection(system, 'services');
+
+  const flowsInSystem = [...(system.data.flows || [])].sort(byResourceName);
+  const renderFlows = flowsInSystem.length > 0 && shouldRenderSideBarSection(system, 'flows');
+
+  const entitiesInSystem = [...(system.data.entities || [])].sort(byResourceName);
+  const renderEntities = entitiesInSystem.length > 0 && shouldRenderSideBarSection(system, 'entities');
+
+  const containersInSystem = [...(system.data.containers || [])].sort(byResourceName);
+  const renderContainers = containersInSystem.length > 0 && shouldRenderSideBarSection(system, 'containers');
+
+  // The Resources page/link only makes sense when the system actually has resources
+  // attached (services, flows, entities or data stores). Mirrors what the page renders.
+  const hasResources =
+    servicesInSystem.length > 0 || flowsInSystem.length > 0 || entitiesInSystem.length > 0 || containersInSystem.length > 0;
+
+  const systemDiagrams = system.data.diagrams || [];
+  const diagramNavItems = buildDiagramNavItems(systemDiagrams, context.diagrams);
+  const hasDiagrams = diagramNavItems.length > 0 && shouldRenderSideBarSection(system, 'diagrams');
+
+  // A system that declares relationships to other systems, or actors, can be the starting
+  // point of a Context Diagram. (Systems that are only referenced by others still get a
+  // context page; here we surface the link from systems that declare something themselves.)
+  const hasRelationships = (system.data.relationships || []).length > 0 || (system.data.actors || []).length > 0;
+
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(system, 'owners');
+  const renderRepository = system.data.repository && shouldRenderSideBarSection(system, 'repository');
+  const hasAttachments = system.data.attachments && system.data.attachments.length > 0;
+
+  const renderVisualiser = isVisualiserEnabled();
+
+  const docsSection = buildResourceDocsSection(
+    'systems',
+    system.data.id,
+    system.data.version,
+    context.resourceDocs,
+    context.resourceDocCategories
+  );
+
+  return {
+    type: 'item',
+    title: system.data.name,
+    badge: 'System',
+    summary: system.data.summary,
+    // Systems use a custom icon when defined, otherwise none — the surrounding
+    // 'Systems' section header (and System badge) already convey the type, so the
+    // default Group glyph on every item is redundant.
+    ...customIconFieldsForResource(system.data),
+    pages: [
+      buildQuickReferenceSection(
+        [
+          {
+            title: 'Overview',
+            href: buildUrl(`/docs/systems/${system.data.id}/${system.data.version}`),
+          },
+          hasResources && {
+            title: 'System Resources',
+            href: buildUrl(`/docs/systems/${system.data.id}/${system.data.version}/resources`),
+          },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(system, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/systems/${system.data.id}/${system.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      docsSection,
+      {
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Overview',
+            href: buildUrl(`/architecture/systems/${system.data.id}/${system.data.version}`),
+          },
+          renderVisualiser &&
+            hasRelationships && {
+              type: 'item',
+              title: 'Context Diagram',
+              href: buildUrl(`/visualiser/systems/${system.data.id}/${system.data.version}/context`),
+            },
+          renderVisualiser && {
+            type: 'item',
+            title: 'Resource Diagram',
+            href: buildUrl(`/visualiser/systems/${system.data.id}/${system.data.version}`),
+          },
+        ].filter(Boolean) as ChildRef[],
+      },
+      hasDiagrams && {
+        type: 'group',
+        title: 'Diagrams',
+        icon: 'FileImage',
+        pages: diagramNavItems,
+      },
+      (renderServices || renderFlows || renderContainers) && {
+        type: 'group',
+        title: 'Resources',
+        icon: 'Boxes',
+        // Resource type subsections are ordered A-Z by their title, and the
+        // resources within each subsection are ordered A-Z by name (sorted above).
+        pages: (
+          [
+            renderServices && {
+              type: 'group',
+              title: 'Services',
+              subtle: true,
+              icon: 'Server',
+              pages: servicesInSystem.map((service) => `service:${(service as any).data.id}:${(service as any).data.version}`),
+            },
+            renderFlows && {
+              type: 'group',
+              title: 'Flows',
+              subtle: true,
+              icon: 'Waypoints',
+              pages: flowsInSystem.map((flow) => `flow:${(flow as any).data.id}:${(flow as any).data.version}`),
+            },
+            renderContainers && {
+              type: 'group',
+              title: 'Data Stores',
+              subtle: true,
+              icon: 'Database',
+              pages: containersInSystem.map(
+                (container) => `container:${(container as any).data.id}:${(container as any).data.version}`
+              ),
+            },
+          ].filter(Boolean) as NavNode[]
+        ).sort((a, b) => a.title.localeCompare(b.title)) as ChildRef[],
+      },
+      renderEntities && {
+        type: 'group',
+        title: 'Entities',
+        icon: 'Box',
+        pages: entitiesInSystem.map((entity) => ({
+          type: 'item',
+          title: (entity as any).data?.name || (entity as any).data.id,
+          href: buildUrl(`/docs/entities/${(entity as any).data.id}/${(entity as any).data.version}`),
+        })),
+      },
+      renderOwners && buildOwnersSection(owners),
+      renderRepository && buildRepositorySection(system.data.repository as { url: string; language: string }),
+      hasAttachments && buildAttachmentsSection(system.data.attachments as any[]),
+    ].filter(Boolean) as ChildRef[],
+  };
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/index.ts b/packages/core/eventcatalog/src/stores/sidebar-store/index.ts
new file mode 100644
index 000000000..580b69121
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/index.ts
@@ -0,0 +1,8 @@
+import { atom } from 'nanostores';
+import type { NavigationData } from './state';
+
+export const sidebarStore = atom<NavigationData | null>(null);
+
+export const setSidebarData = (data: NavigationData) => {
+  sidebarStore.set(data);
+};
diff --git a/packages/core/eventcatalog/src/stores/sidebar-store/state.ts b/packages/core/eventcatalog/src/stores/sidebar-store/state.ts
new file mode 100644
index 000000000..bc8d2c905
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/sidebar-store/state.ts
@@ -0,0 +1,1157 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { getAgents } from '@utils/collections/agents';
+import { getAdrAliasNodeKey, getAdrNodeKey, getAdrs, type Adr } from '@utils/collections/adrs';
+import { ADR_STATUS_VALUES, formatAdrStatus } from '@utils/collections/adr-constants';
+import { getContainers } from '@utils/collections/containers';
+import { getDomains } from '@utils/collections/domains';
+import { getSystems } from '@utils/collections/systems';
+import { getServices } from '@utils/collections/services';
+import { getMessages, pluralizeMessageType } from '@utils/collections/messages';
+import { getOwner } from '@utils/collections/owners';
+import { getFlows } from '@utils/collections/flows';
+import { getUsers } from '@utils/collections/users';
+import { getTeams } from '@utils/collections/teams';
+import { getDiagrams } from '@utils/collections/diagrams';
+import { getDataProducts } from '@utils/collections/data-products';
+import { getEntities } from '@utils/collections/entities';
+import { getResourceDocCategories, getResourceDocs } from '@utils/collections/resource-docs';
+import { buildUrl } from '@utils/url-builder';
+import type { NavigationData, NavNode, ChildRef } from './builders/shared';
+import { buildAgentNode } from './builders/agent';
+import { buildDomainNode } from './builders/domain';
+import { buildSystemNode } from './builders/system';
+import { buildServiceNode } from './builders/service';
+import { buildMessageNode } from './builders/message';
+import { buildContainerNode } from './builders/container';
+import { buildFlowNode } from './builders/flow';
+import { buildDataProductNode } from './builders/data-product';
+import { buildAdrNode } from './builders/adr';
+import { buildEntityNode } from './builders/entity';
+import config from '@config';
+import { getDesigns } from '@utils/collections/designs';
+import { getChannels } from '@utils/collections/channels';
+import { createVersionedMap, findInMap } from '@utils/collections/util';
+import { iconFieldsForResource } from '@utils/icon';
+import {
+  buildQuickReferenceSection,
+  buildResourceDocsSection,
+  shouldRenderSideBarSection,
+  withArchitectureDecisionsSection,
+} from './builders/shared';
+import { isChangelogEnabled } from '@utils/feature';
+
+export type { NavigationData, NavNode, ChildRef };
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+let memoryCache: NavigationData | null = null;
+
+type MessageEntry = CollectionEntry<'events' | 'commands' | 'queries'>;
+type AgentEntry = CollectionEntry<'agents'>;
+type ServiceEntry = CollectionEntry<'services'>;
+type ContainerEntry = CollectionEntry<'containers'>;
+type DataProductEntry = CollectionEntry<'data-products'>;
+
+const byResourceName = <T extends { data: { name?: string; id: string } }>(a: T, b: T) => {
+  const name = (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  if (name !== 0) return name;
+  return a.data.id.localeCompare(b.data.id);
+};
+
+const sortByResourceName = <T extends { data: { name?: string; id: string } }>(items: T[]) => [...items].sort(byResourceName);
+
+const groupAdrsByStatus = (adrs: Adr[]): NavNode[] =>
+  ADR_STATUS_VALUES.reduce<NavNode[]>((groups, status) => {
+    const adrsForStatus = adrs.filter((adr) => adr.data.status === status);
+    if (adrsForStatus.length === 0) return groups;
+
+    groups.push({
+      type: 'group',
+      title: `${formatAdrStatus(status)} (${adrsForStatus.length})`,
+      subtle: true,
+      pages: [...adrsForStatus].sort(byResourceName).map(getAdrNodeKey),
+    });
+
+    return groups;
+  }, []);
+
+const getMessageNodeKey = (message: MessageEntry) =>
+  `${pluralizeMessageType(message)}:${message.data.id}:${message.data.version}`;
+
+const uniqueRefs = (refs: string[]) => [...new Set(refs)];
+
+const buildFlowReferencesByMessage = ({
+  flows,
+  events,
+  commands,
+  queries,
+}: {
+  flows: CollectionEntry<'flows'>[];
+  events: CollectionEntry<'events'>[];
+  commands: CollectionEntry<'commands'>[];
+  queries: CollectionEntry<'queries'>[];
+}) => {
+  const eventMap = createVersionedMap(events);
+  const commandMap = createVersionedMap(commands);
+  const queryMap = createVersionedMap(queries);
+  const flowRefsByMessage = new Map<string, string[]>();
+
+  const addFlowRef = (message: MessageEntry, flow: CollectionEntry<'flows'>) => {
+    const messageKey = getMessageNodeKey(message);
+    const flowKey = `flow:${flow.data.id}:${flow.data.version}`;
+    flowRefsByMessage.set(messageKey, uniqueRefs([...(flowRefsByMessage.get(messageKey) || []), flowKey]));
+  };
+
+  const resolveMessagePointer = (pointer: { id: string; version?: string }): MessageEntry | undefined => {
+    return (
+      findInMap(eventMap, pointer.id, pointer.version) ||
+      findInMap(commandMap, pointer.id, pointer.version) ||
+      findInMap(queryMap, pointer.id, pointer.version)
+    );
+  };
+
+  for (const flow of flows) {
+    for (const step of flow.data.steps || []) {
+      if (!step.message) continue;
+
+      const hydratedMessage = Array.isArray(step.message) ? step.message[0] : undefined;
+      if (hydratedMessage?.collection && hydratedMessage?.data) {
+        addFlowRef(hydratedMessage as MessageEntry, flow);
+        continue;
+      }
+
+      if (Array.isArray(step.message)) continue;
+
+      const message = resolveMessagePointer(step.message);
+      if (message) addFlowRef(message, flow);
+    }
+  }
+
+  return flowRefsByMessage;
+};
+
+const buildFlowReferencesByService = ({
+  flows,
+  services,
+}: {
+  flows: CollectionEntry<'flows'>[];
+  services: CollectionEntry<'services'>[];
+}) => {
+  const serviceMap = createVersionedMap(services);
+  const flowRefsByService = new Map<string, string[]>();
+
+  const addFlowRef = (service: ServiceEntry, flow: CollectionEntry<'flows'>) => {
+    const serviceKey = `service:${service.data.id}:${service.data.version}`;
+    const flowKey = `flow:${flow.data.id}:${flow.data.version}`;
+    flowRefsByService.set(serviceKey, uniqueRefs([...(flowRefsByService.get(serviceKey) || []), flowKey]));
+  };
+
+  for (const flow of flows) {
+    for (const step of flow.data.steps || []) {
+      if (!step.service) continue;
+
+      const service = findInMap(serviceMap, step.service.id, step.service.version);
+      if (service) addFlowRef(service, flow);
+    }
+  }
+
+  return flowRefsByService;
+};
+
+const buildFlowReferencesByAgent = ({
+  flows,
+  agents,
+}: {
+  flows: CollectionEntry<'flows'>[];
+  agents: CollectionEntry<'agents'>[];
+}) => {
+  const agentMap = createVersionedMap(agents);
+  const flowRefsByAgent = new Map<string, string[]>();
+
+  const addFlowRef = (agent: AgentEntry, flow: CollectionEntry<'flows'>) => {
+    const agentKey = `agent:${agent.data.id}:${agent.data.version}`;
+    const flowKey = `flow:${flow.data.id}:${flow.data.version}`;
+    flowRefsByAgent.set(agentKey, uniqueRefs([...(flowRefsByAgent.get(agentKey) || []), flowKey]));
+  };
+
+  for (const flow of flows) {
+    for (const step of flow.data.steps || []) {
+      if (!(step as any).agent) continue;
+
+      const hydratedAgent = Array.isArray((step as any).agent) ? (step as any).agent[0] : undefined;
+      if (hydratedAgent?.collection && hydratedAgent?.data) {
+        addFlowRef(hydratedAgent as AgentEntry, flow);
+        continue;
+      }
+
+      if (Array.isArray((step as any).agent)) continue;
+
+      const agent = findInMap(agentMap, (step as any).agent.id, (step as any).agent.version);
+      if (agent) addFlowRef(agent, flow);
+    }
+  }
+
+  return flowRefsByAgent;
+};
+
+const buildFlowReferencesByContainer = ({
+  flows,
+  containers,
+}: {
+  flows: CollectionEntry<'flows'>[];
+  containers: CollectionEntry<'containers'>[];
+}) => {
+  const containerMap = createVersionedMap(containers);
+  const flowRefsByContainer = new Map<string, string[]>();
+
+  const addFlowRef = (container: ContainerEntry, flow: CollectionEntry<'flows'>) => {
+    const containerKey = `container:${container.data.id}:${container.data.version}`;
+    const flowKey = `flow:${flow.data.id}:${flow.data.version}`;
+    flowRefsByContainer.set(containerKey, uniqueRefs([...(flowRefsByContainer.get(containerKey) || []), flowKey]));
+  };
+
+  for (const flow of flows) {
+    for (const step of flow.data.steps || []) {
+      if (!step.container) continue;
+
+      const hydratedContainer = Array.isArray(step.container) ? step.container[0] : undefined;
+      if (hydratedContainer?.collection && hydratedContainer?.data) {
+        addFlowRef(hydratedContainer as ContainerEntry, flow);
+        continue;
+      }
+
+      if (Array.isArray(step.container)) continue;
+
+      const container = findInMap(containerMap, step.container.id, step.container.version);
+      if (container) addFlowRef(container as ContainerEntry, flow);
+    }
+  }
+
+  return flowRefsByContainer;
+};
+
+const buildFlowReferencesByDataProduct = ({
+  flows,
+  dataProducts,
+}: {
+  flows: CollectionEntry<'flows'>[];
+  dataProducts: CollectionEntry<'data-products'>[];
+}) => {
+  const dataProductMap = createVersionedMap(dataProducts);
+  const flowRefsByDataProduct = new Map<string, string[]>();
+
+  const addFlowRef = (dataProduct: DataProductEntry, flow: CollectionEntry<'flows'>) => {
+    const dataProductKey = `data-product:${dataProduct.data.id}:${dataProduct.data.version}`;
+    const flowKey = `flow:${flow.data.id}:${flow.data.version}`;
+    flowRefsByDataProduct.set(dataProductKey, uniqueRefs([...(flowRefsByDataProduct.get(dataProductKey) || []), flowKey]));
+  };
+
+  for (const flow of flows) {
+    for (const step of flow.data.steps || []) {
+      if (!step.dataProduct) continue;
+
+      const hydratedDataProduct = Array.isArray(step.dataProduct) ? step.dataProduct[0] : undefined;
+      if (hydratedDataProduct?.collection && hydratedDataProduct?.data) {
+        addFlowRef(hydratedDataProduct as DataProductEntry, flow);
+        continue;
+      }
+
+      if (Array.isArray(step.dataProduct)) continue;
+
+      const dataProduct = findInMap(dataProductMap, step.dataProduct.id, step.dataProduct.version);
+      if (dataProduct) addFlowRef(dataProduct as DataProductEntry, flow);
+    }
+  }
+
+  return flowRefsByDataProduct;
+};
+
+/**
+ * Get the navigation data for the sidebar
+ */
+export const getNestedSideBarData = async (): Promise<NavigationData> => {
+  if (memoryCache && CACHE_ENABLED) {
+    return memoryCache;
+  }
+
+  const [
+    domains,
+    systems,
+    agents,
+    services,
+    { events, commands, queries },
+    containers,
+    flows,
+    users,
+    teams,
+    designs,
+    channels,
+    diagrams,
+    dataProducts,
+    entities,
+    adrs,
+    schemas,
+    ubiquitousLanguages,
+    resourceDocs,
+    resourceDocCategories,
+  ] = await Promise.all([
+    getDomains({ getAllVersions: false, includeServicesInSubdomains: false }),
+    getSystems({ getAllVersions: false }),
+    getAgents({ getAllVersions: false }),
+    getServices({ getAllVersions: false }),
+    getMessages({ getAllVersions: false }),
+    getContainers({ getAllVersions: false }),
+    getFlows({ getAllVersions: false }),
+    getUsers(),
+    getTeams(),
+    getDesigns(),
+    getChannels({ getAllVersions: false }),
+    getDiagrams({ getAllVersions: false }),
+    getDataProducts({ getAllVersions: false }),
+    getEntities({ getAllVersions: false }),
+    getAdrs({ getAllVersions: false }),
+    getCollection('schemas'),
+    getCollection('ubiquitousLanguages'),
+    getResourceDocs(),
+    getResourceDocCategories(),
+  ]);
+
+  // Calculate derived lists to avoid extra fetches
+  const allSubDomainIds = new Set(domains.flatMap((d) => (d.data.domains || []).map((sd: any) => sd.data.id)));
+  const rootDomains = domains.filter((d) => !allSubDomainIds.has(d.data.id));
+
+  const messages = [...events, ...commands, ...queries];
+
+  const context = {
+    agents,
+    services,
+    domains,
+    systems,
+    events,
+    commands,
+    queries,
+    flows,
+    containers,
+    channels,
+    diagrams,
+    schemas,
+    ubiquitousLanguages,
+    dataProducts,
+    entities,
+    adrs,
+    users,
+    teams,
+    resourceDocs,
+    resourceDocCategories,
+  };
+
+  // Process all domains with their owners first (async)
+  const domainsWithOwners = await Promise.all(
+    domains.map(async (domain) => {
+      const ownersInDomain = domain.data.owners || [];
+      const owners = await Promise.all(ownersInDomain.map((owner) => getOwner(owner)));
+      const filteredOwners = owners.filter((o) => o !== undefined) as Array<NonNullable<(typeof owners)[0]>>;
+
+      return {
+        domain,
+        owners: filteredOwners,
+      };
+    })
+  );
+
+  const agentsWithOwners = await Promise.all(
+    agents.map(async (agent) => {
+      const ownersInAgent = agent.data.owners || [];
+      const owners = await Promise.all(ownersInAgent.map((owner) => getOwner(owner)));
+      const filteredOwners = owners.filter((o) => o !== undefined) as Array<NonNullable<(typeof owners)[0]>>;
+      return { agent, owners: filteredOwners };
+    })
+  );
+
+  // Services with owners
+  const servicesWithOwners = await Promise.all(
+    services.map(async (service) => {
+      const ownersInService = service.data.owners || [];
+      const owners = await Promise.all(ownersInService.map((owner) => getOwner(owner)));
+      const filteredOwners = owners.filter((o) => o !== undefined) as Array<NonNullable<(typeof owners)[0]>>;
+      return { service, owners: filteredOwners };
+    })
+  );
+
+  // Messages with owners
+  const messagesWithOwners = await Promise.all(
+    messages.map(async (message) => {
+      const ownersInMessage = message.data.owners || [];
+      const owners = await Promise.all(ownersInMessage.map((owner) => getOwner(owner)));
+      const filteredOwners = owners.filter((o) => o !== undefined) as Array<NonNullable<(typeof owners)[0]>>;
+      return { message, owners: filteredOwners };
+    })
+  );
+
+  const containerWithOwners = await Promise.all(
+    containers.map(async (container) => {
+      const ownersInContainer = container.data.owners || [];
+      const owners = await Promise.all(ownersInContainer.map((owner) => getOwner(owner)));
+      const filteredOwners = owners.filter((o) => o !== undefined) as Array<NonNullable<(typeof owners)[0]>>;
+      return { container, owners: filteredOwners };
+    })
+  );
+
+  const systemWithOwners = await Promise.all(
+    systems.map(async (system) => {
+      const ownersInSystem = system.data.owners || [];
+      const owners = await Promise.all(ownersInSystem.map((owner) => getOwner(owner)));
+      const filteredOwners = owners.filter((o) => o !== undefined) as Array<NonNullable<(typeof owners)[0]>>;
+      return { system, owners: filteredOwners };
+    })
+  );
+
+  const adrsWithOwners = await Promise.all(
+    adrs.map(async (adr) => {
+      const owners = await Promise.all((adr.data.owners || []).map((owner) => getOwner(owner)));
+      const decisionMakers = await Promise.all((adr.data.decisionMakers || []).map((owner) => getOwner(owner)));
+      return {
+        adr,
+        owners: owners.filter((o) => o !== undefined),
+        decisionMakers: decisionMakers.filter((o) => o !== undefined),
+      };
+    })
+  );
+
+  const entitiesWithOwners = await Promise.all(
+    entities.map(async (entity) => {
+      const owners = await Promise.all((entity.data.owners || []).map((owner) => getOwner(owner)));
+      const filteredOwners = owners.filter((o) => o !== undefined) as Array<NonNullable<(typeof owners)[0]>>;
+      return { entity, owners: filteredOwners };
+    })
+  );
+
+  const flowNodes = flows.reduce(
+    (acc, flow) => {
+      acc[`flow:${flow.data.id}:${flow.data.version}`] = withArchitectureDecisionsSection(
+        buildFlowNode(flow, context),
+        flow,
+        adrs
+      );
+      return acc;
+    },
+    {} as Record<string, NavNode>
+  );
+
+  const domainNodes = domainsWithOwners.reduce(
+    (acc, { domain, owners }) => {
+      const versionedKey = `domain:${domain.data.id}:${domain.data.version}`;
+      acc[versionedKey] = withArchitectureDecisionsSection(buildDomainNode(domain, owners, context), domain, adrs);
+      if (domain.data.latestVersion === domain.data.version) {
+        // Store reference to versioned key instead of duplicating the full node
+        acc[`domain:${domain.data.id}`] = versionedKey;
+      }
+      return acc;
+    },
+    {} as Record<string, NavNode | string>
+  );
+
+  const rawAgents = await getCollection('agents');
+
+  // Compute channels for each service from raw sends[].to / receives[].from pointers
+  const rawServices = await getCollection('services');
+  const channelMap = createVersionedMap(channels);
+  const serviceChannelsMap = new Map<string, CollectionEntry<'channels'>[]>();
+
+  for (const service of services) {
+    const rawService = rawServices.find((s) => s.data.id === service.data.id && s.data.version === service.data.version);
+    if (!rawService) continue;
+
+    const pointers: Array<{ id: string; version?: string }> = [];
+    for (const send of rawService.data.sends ?? []) {
+      for (const ch of send.to ?? []) {
+        pointers.push({ id: ch.id, version: ch.version });
+      }
+    }
+    for (const receive of rawService.data.receives ?? []) {
+      for (const ch of receive.from ?? []) {
+        pointers.push({ id: ch.id, version: ch.version });
+      }
+    }
+
+    const seen = new Set<string>();
+    const resolved: CollectionEntry<'channels'>[] = [];
+    for (const pointer of pointers) {
+      const key = `${pointer.id}-${pointer.version ?? 'latest'}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const match = findInMap(channelMap, pointer.id, pointer.version);
+      if (match) resolved.push(match as CollectionEntry<'channels'>);
+    }
+
+    if (resolved.length > 0) {
+      serviceChannelsMap.set(`${service.data.id}:${service.data.version}`, resolved);
+    }
+  }
+
+  const agentChannelsMap = new Map<string, CollectionEntry<'channels'>[]>();
+
+  for (const agent of agents) {
+    const rawAgent = rawAgents.find((a) => a.data.id === agent.data.id && a.data.version === agent.data.version);
+    if (!rawAgent) continue;
+
+    const pointers: Array<{ id: string; version?: string }> = [];
+    for (const send of rawAgent.data.sends ?? []) {
+      for (const ch of send.to ?? []) {
+        pointers.push({ id: ch.id, version: ch.version });
+      }
+    }
+    for (const receive of rawAgent.data.receives ?? []) {
+      for (const ch of receive.from ?? []) {
+        pointers.push({ id: ch.id, version: ch.version });
+      }
+    }
+
+    const seen = new Set<string>();
+    const resolved: CollectionEntry<'channels'>[] = [];
+    for (const pointer of pointers) {
+      const key = `${pointer.id}-${pointer.version ?? 'latest'}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const match = findInMap(channelMap, pointer.id, pointer.version);
+      if (match) resolved.push(match as CollectionEntry<'channels'>);
+    }
+
+    if (resolved.length > 0) {
+      agentChannelsMap.set(`${agent.data.id}:${agent.data.version}`, resolved);
+    }
+  }
+
+  const flowRefsByAgent = buildFlowReferencesByAgent({ flows, agents });
+  const flowRefsByService = buildFlowReferencesByService({ flows, services });
+
+  const agentNodes = agentsWithOwners.reduce(
+    (acc, { agent, owners }) => {
+      const versionedKey = `agent:${agent.data.id}:${agent.data.version}`;
+      const agentChannels = agentChannelsMap.get(`${agent.data.id}:${agent.data.version}`) || [];
+      acc[versionedKey] = withArchitectureDecisionsSection(
+        buildAgentNode(agent, owners, context, agentChannels, flowRefsByAgent.get(versionedKey) || []),
+        agent,
+        adrs
+      );
+      if (agent.data.latestVersion === agent.data.version) {
+        acc[`agent:${agent.data.id}`] = versionedKey;
+      }
+      return acc;
+    },
+    {} as Record<string, NavNode | string>
+  );
+
+  const serviceNodes = servicesWithOwners.reduce(
+    (acc, { service, owners }) => {
+      const versionedKey = `service:${service.data.id}:${service.data.version}`;
+      const serviceChannels = serviceChannelsMap.get(`${service.data.id}:${service.data.version}`) || [];
+      acc[versionedKey] = withArchitectureDecisionsSection(
+        buildServiceNode(service, owners, context, serviceChannels, flowRefsByService.get(versionedKey) || []),
+        service,
+        adrs
+      );
+      if (service.data.latestVersion === service.data.version) {
+        // Store reference to versioned key instead of duplicating the full node
+        acc[`service:${service.data.id}`] = versionedKey;
+      }
+      return acc;
+    },
+    {} as Record<string, NavNode | string>
+  );
+
+  // Build a set of message IDs that have field usage declared by any service or agent.
+  // We use raw collections because the hydrated resources replace
+  // sends/receives pointers with resolved message entries, which strips the fields property.
+  const messagesWithFieldUsage = new Set<string>();
+  for (const agent of rawAgents) {
+    for (const pointer of agent.data.sends || []) {
+      if (pointer.fields?.length) messagesWithFieldUsage.add(pointer.id);
+    }
+    for (const pointer of agent.data.receives || []) {
+      if (pointer.fields?.length) messagesWithFieldUsage.add(pointer.id);
+    }
+  }
+  for (const service of rawServices) {
+    for (const pointer of service.data.sends || []) {
+      if (pointer.fields?.length) messagesWithFieldUsage.add(pointer.id);
+    }
+    for (const pointer of service.data.receives || []) {
+      if (pointer.fields?.length) messagesWithFieldUsage.add(pointer.id);
+    }
+  }
+
+  const flowRefsByMessage = buildFlowReferencesByMessage({ flows, events, commands, queries });
+
+  const messageNodes = messagesWithOwners.reduce(
+    (acc, { message, owners }) => {
+      const type = pluralizeMessageType(message as any);
+      const versionedKey = `${type}:${message.data.id}:${message.data.version}`;
+      const hasFieldUsage = messagesWithFieldUsage.has(message.data.id);
+      acc[versionedKey] = withArchitectureDecisionsSection(
+        buildMessageNode(message, owners, context, hasFieldUsage, flowRefsByMessage.get(versionedKey) || []),
+        message,
+        adrs
+      );
+      if (message.data.latestVersion === message.data.version) {
+        // Store reference to versioned key instead of duplicating the full node
+        acc[`${type}:${message.data.id}`] = versionedKey;
+      }
+      return acc;
+    },
+    {} as Record<string, NavNode | string>
+  );
+
+  const flowRefsByContainer = buildFlowReferencesByContainer({ flows, containers });
+
+  const containerNodes = containerWithOwners.reduce(
+    (acc, { container, owners }) => {
+      const versionedKey = `container:${container.data.id}:${container.data.version}`;
+      acc[versionedKey] = withArchitectureDecisionsSection(
+        buildContainerNode(container, owners, context, flowRefsByContainer.get(versionedKey) || []),
+        container,
+        adrs
+      );
+      if (container.data.latestVersion === container.data.version) {
+        // Store reference to versioned key instead of duplicating the full node
+        acc[`container:${container.data.id}`] = versionedKey;
+      }
+      return acc;
+    },
+    {} as Record<string, NavNode | string>
+  );
+
+  const systemNodes = systemWithOwners.reduce(
+    (acc, { system, owners }) => {
+      const versionedKey = `system:${system.data.id}:${system.data.version}`;
+      acc[versionedKey] = withArchitectureDecisionsSection(buildSystemNode(system, owners, context), system, adrs);
+      if (system.data.latestVersion === system.data.version) {
+        // Store reference to versioned key instead of duplicating the full node
+        acc[`system:${system.data.id}`] = versionedKey;
+      }
+      return acc;
+    },
+    {} as Record<string, NavNode | string>
+  );
+
+  // Get owners for data products
+  const dataProductWithOwners = await Promise.all(
+    dataProducts.map(async (dataProduct) => {
+      const owners = await Promise.all((dataProduct.data.owners || []).map((owner) => getOwner(owner)));
+      return { dataProduct, owners: owners.filter((o) => o !== undefined) };
+    })
+  );
+
+  const dataProductContext = {
+    events,
+    commands,
+    queries,
+    services,
+    containers,
+    channels,
+    resourceDocs,
+    resourceDocCategories,
+  };
+
+  const flowRefsByDataProduct = buildFlowReferencesByDataProduct({ flows, dataProducts });
+
+  const dataProductNodes = dataProductWithOwners.reduce(
+    (acc, { dataProduct, owners }) => {
+      const versionedKey = `data-product:${dataProduct.data.id}:${dataProduct.data.version}`;
+      acc[versionedKey] = withArchitectureDecisionsSection(
+        buildDataProductNode(dataProduct, owners, dataProductContext, flowRefsByDataProduct.get(versionedKey) || []),
+        dataProduct,
+        adrs
+      );
+      if (dataProduct.data.latestVersion === dataProduct.data.version) {
+        acc[`data-product:${dataProduct.data.id}`] = versionedKey;
+      }
+      return acc;
+    },
+    {} as Record<string, NavNode | string>
+  );
+
+  const adrNodes = adrsWithOwners.reduce(
+    (acc, { adr, owners, decisionMakers }) => {
+      const versionedKey = getAdrNodeKey(adr);
+      acc[versionedKey] = buildAdrNode(adr, owners, decisionMakers, context);
+      if (adr.data.latestVersion === adr.data.version) {
+        acc[getAdrAliasNodeKey(adr)] = versionedKey;
+      }
+      return acc;
+    },
+    {} as Record<string, NavNode | string>
+  );
+
+  const entityNodes = entitiesWithOwners.reduce(
+    (acc, { entity, owners }) => {
+      const versionedKey = `entity:${entity.data.id}:${entity.data.version}`;
+      acc[versionedKey] = withArchitectureDecisionsSection(buildEntityNode(entity, owners, context), entity, adrs);
+      if (entity.data.latestVersion === entity.data.version) {
+        acc[`entity:${entity.data.id}`] = versionedKey;
+      }
+      return acc;
+    },
+    {} as Record<string, NavNode | string>
+  );
+
+  const designNodes = designs.reduce(
+    (acc, design) => {
+      acc[`design:${design.data.id}`] = {
+        type: 'item',
+        title: design.data.name,
+        badge: 'Design',
+        href: buildUrl(`/visualiser/designs/${design.data.id}`),
+      };
+      return acc;
+    },
+    {} as Record<string, NavNode>
+  );
+
+  const diagramNodes = diagrams.reduce(
+    (acc, diagram) => {
+      const versionedKey = `diagram:${diagram.data.id}:${diagram.data.version}`;
+      acc[versionedKey] = withArchitectureDecisionsSection(
+        {
+          type: 'item',
+          title: diagram.data.name,
+          badge: 'Diagram',
+          href: buildUrl(`/diagrams/${diagram.data.id}/${diagram.data.version}`),
+        },
+        diagram,
+        adrs
+      );
+      if (diagram.data.latestVersion === diagram.data.version) {
+        acc[`diagram:${diagram.data.id}`] = versionedKey;
+      }
+      return acc;
+    },
+    {} as Record<string, NavNode | string>
+  );
+
+  const userNodes = users.reduce(
+    (acc, user) => {
+      acc[`user:${user.data.id}`] = withArchitectureDecisionsSection(
+        {
+          type: 'item',
+          title: user.data.name,
+          href: buildUrl(`/docs/users/${user.data.id}`),
+        },
+        user,
+        adrs
+      );
+      return acc;
+    },
+    {} as Record<string, NavNode>
+  );
+
+  const channelNodes = channels.reduce(
+    (acc, channel) => {
+      const versionedKey = `channel:${channel.data.id}:${channel.data.version}`;
+      const docsSection = buildResourceDocsSection(
+        'channels',
+        channel.data.id,
+        channel.data.version,
+        resourceDocs,
+        resourceDocCategories
+      );
+      acc[versionedKey] = withArchitectureDecisionsSection(
+        {
+          type: 'item',
+          title: channel.data.name,
+          badge: 'Channel',
+          summary: channel.data.summary,
+          ...iconFieldsForResource(channel.data, 'ArrowRightLeft'),
+          pages: [
+            buildQuickReferenceSection(
+              [
+                {
+                  title: 'Overview',
+                  href: buildUrl(`/docs/${channel.collection}/${channel.data.id}/${channel.data.version}`),
+                },
+                isChangelogEnabled() &&
+                  shouldRenderSideBarSection(channel, 'changelog') && {
+                    title: 'Changelog',
+                    href: buildUrl(`/docs/${channel.collection}/${channel.data.id}/${channel.data.version}/changelog`),
+                  },
+              ].filter(Boolean) as { title: string; href: string }[]
+            ),
+            docsSection,
+          ].filter(Boolean) as ChildRef[],
+        },
+        channel,
+        adrs
+      );
+
+      if (channel.data.latestVersion === channel.data.version) {
+        // Store reference to versioned key instead of duplicating the full node
+        acc[`channel:${channel.data.id}`] = versionedKey;
+      }
+      return acc;
+    },
+    {} as Record<string, NavNode | string>
+  );
+
+  const teamNodes = teams.reduce(
+    (acc, team) => {
+      acc[`team:${team.data.id}`] = withArchitectureDecisionsSection(
+        {
+          type: 'item',
+          title: team.data.name,
+          href: buildUrl(`/docs/teams/${team.data.id}`),
+        },
+        team,
+        adrs
+      );
+      return acc;
+    },
+    {} as Record<string, NavNode>
+  );
+
+  const visualiserEnabled = config?.visualiser?.enabled !== false;
+  const rootDomainsNodes: Record<string, NavNode> = {};
+
+  if (rootDomains.length > 0) {
+    rootDomainsNodes['list:top-level-domains'] = {
+      type: 'group',
+      title: 'Domains',
+      icon: 'Boxes',
+      pages: sortByResourceName(rootDomains).map((domain) => `domain:${domain.data.id}:${domain.data.version}`),
+    };
+  }
+
+  const topLevelDiagramsNode =
+    visualiserEnabled && systems.length > 0
+      ? {
+          type: 'group' as const,
+          title: 'Top level diagrams',
+          icon: 'Workflow',
+          pages: [
+            {
+              type: 'item' as const,
+              title: 'System Context Map',
+              href: buildUrl('/visualiser/system-context-map'),
+            },
+          ],
+        }
+      : undefined;
+
+  const createLeaf = (items: any[], node: NavNode) => (items.length > 0 ? node : undefined);
+
+  const domainsList = createLeaf(domains, {
+    type: 'item',
+    title: 'Domains',
+    icon: 'Boxes',
+    pages: sortByResourceName(domains).map((domain) => `domain:${domain.data.id}:${domain.data.version}`),
+  });
+
+  // Split systems by scope (defaults to internal). When there are systems of both
+  // scopes we show two sub-sections (Internal / External), each ordered by name;
+  // otherwise we keep a flat list so a single-scope catalog isn't over-nested.
+  const internalSystems = systems.filter((system) => (system.data.scope ?? 'internal') !== 'external');
+  const externalSystems = systems.filter((system) => system.data.scope === 'external');
+
+  const systemPageKeys = (items: typeof systems) =>
+    sortByResourceName(items).map((system) => `system:${system.data.id}:${system.data.version}`);
+
+  const internalSystemsList = createLeaf(internalSystems, {
+    type: 'group',
+    title: 'Internal',
+    icon: 'Group',
+    pages: systemPageKeys(internalSystems),
+  });
+
+  const externalSystemsScopedList = createLeaf(externalSystems, {
+    type: 'group',
+    title: 'External',
+    icon: 'Group',
+    pages: systemPageKeys(externalSystems),
+  });
+
+  const hasBothSystemScopes = internalSystems.length > 0 && externalSystems.length > 0;
+
+  const systemsList = createLeaf(systems, {
+    type: 'item',
+    title: 'Systems',
+    icon: 'Group',
+    pages: hasBothSystemScopes ? ['list:systems-internal', 'list:systems-external'] : systemPageKeys(systems),
+  });
+
+  const agentsList = createLeaf(agents, {
+    type: 'item',
+    title: 'Agents',
+    icon: 'Bot',
+    pages: sortByResourceName(agents).map((agent) => `agent:${agent.data.id}:${agent.data.version}`),
+  });
+
+  const adrsList = createLeaf(adrs, {
+    type: 'item',
+    title: 'Decision Records',
+    icon: 'ClipboardList',
+    pages: groupAdrsByStatus(adrs),
+  });
+
+  const internalServices = services.filter((service) => !service.data.externalSystem);
+  const externalServices = services.filter((service) => service.data.externalSystem);
+
+  const servicesList = createLeaf(internalServices, {
+    type: 'item',
+    title: 'Services',
+    icon: 'Server',
+    pages: sortByResourceName(internalServices).map((service) => `service:${service.data.id}:${service.data.version}`),
+  });
+
+  const externalSystemsList = createLeaf(externalServices, {
+    type: 'item',
+    title: 'External Systems',
+    icon: 'Globe',
+    pages: sortByResourceName(externalServices).map((service) => `service:${service.data.id}:${service.data.version}`),
+  });
+
+  const eventsList = createLeaf(events, {
+    type: 'group',
+    title: 'Events',
+    icon: 'Zap',
+    pages: sortByResourceName(events).map((event) => `event:${event.data.id}:${event.data.version}`),
+  });
+
+  const commandsList = createLeaf(commands, {
+    type: 'group',
+    title: 'Commands',
+    icon: 'Terminal',
+    pages: sortByResourceName(commands).map((command) => `command:${command.data.id}:${command.data.version}`),
+  });
+
+  const queriesList = createLeaf(queries, {
+    type: 'group',
+    title: 'Queries',
+    icon: 'Search',
+    pages: sortByResourceName(queries).map((query) => `query:${query.data.id}:${query.data.version}`),
+  });
+
+  const flowsList = createLeaf(flows, {
+    type: 'item',
+    title: 'Flows',
+    icon: 'Waypoints',
+    pages: sortByResourceName(flows).map((flow) => `flow:${flow.data.id}:${flow.data.version}`),
+  });
+
+  const containersList = createLeaf(containers, {
+    type: 'item',
+    title: 'Data Stores',
+    icon: 'Database',
+    pages: sortByResourceName(containers).map((container) => `container:${container.data.id}:${container.data.version}`),
+  });
+
+  const dataProductsList = createLeaf(dataProducts, {
+    type: 'item',
+    title: 'Data Products',
+    icon: 'Package',
+    pages: sortByResourceName(dataProducts).map(
+      (dataProduct) => `data-product:${dataProduct.data.id}:${dataProduct.data.version}`
+    ),
+  });
+
+  const entitiesList = createLeaf(entities, {
+    type: 'item',
+    title: 'Entities',
+    icon: 'Box',
+    pages: sortByResourceName(entities).map((entity) => `entity:${entity.data.id}:${entity.data.version}`),
+  });
+
+  const designsList = createLeaf(designs, {
+    type: 'item',
+    title: 'Designs',
+    icon: 'SquareMousePointer',
+    pages: sortByResourceName(designs).map((design) => `design:${design.data.id}`),
+  });
+
+  const teamsList = createLeaf(teams, {
+    type: 'group',
+    title: 'Teams',
+    icon: 'Users',
+    pages: sortByResourceName(teams).map((team) => `team:${team.data.id}`),
+  });
+
+  const usersList = createLeaf(users, {
+    type: 'group',
+    title: 'Users',
+    icon: 'User',
+    pages: sortByResourceName(users).map((user) => `user:${user.data.id}`),
+  });
+
+  const channelList = createLeaf(channels, {
+    type: 'item',
+    title: 'Channels',
+    icon: 'ArrowRightLeft',
+    pages: sortByResourceName(channels).map((channel) => `channel:${channel.data.id}:${channel.data.version}`),
+  });
+
+  const messagesChildren = ['list:events', 'list:commands', 'list:queries'].filter(
+    (key, index) => [eventsList, commandsList, queriesList][index] !== undefined
+  );
+
+  let messagesList;
+  if (messagesChildren.length > 0) {
+    messagesList = {
+      type: 'item',
+      title: 'Messages',
+      icon: 'Mail',
+      pages: messagesChildren,
+    };
+  }
+
+  const peopleChildren = ['list:teams', 'list:users'].filter((key, index) => [teamsList, usersList][index] !== undefined);
+
+  let peopleList;
+  if (peopleChildren.length > 0) {
+    peopleList = {
+      type: 'item',
+      title: 'Teams & Users',
+      icon: 'Users',
+      pages: peopleChildren,
+    };
+  }
+
+  const allChildrenKeys = [
+    'list:domains',
+    'list:systems',
+    'list:services',
+    'list:agents',
+    'list:adrs',
+    'list:external-systems',
+    'list:messages',
+    'list:channels',
+    'list:flows',
+    'list:containers',
+    'list:data-products',
+    'list:entities',
+    'list:designs',
+    'list:people',
+  ];
+  const allChildrenNodes = [
+    domainsList,
+    systemsList,
+    servicesList,
+    agentsList,
+    adrsList,
+    externalSystemsList,
+    messagesList,
+    channelList,
+    flowsList,
+    containersList,
+    dataProductsList,
+    entitiesList,
+    designsList,
+    peopleList,
+  ];
+
+  // The Browse list leads with the resources people reach for most — Domains,
+  // Systems, Services then Messages — and falls back to A-Z for everything else.
+  const browseOrderPriority = ['list:domains', 'list:systems', 'list:services', 'list:messages'];
+  const browseRank = (key: string) => {
+    const index = browseOrderPriority.indexOf(key);
+    return index === -1 ? browseOrderPriority.length : index;
+  };
+
+  const validAllChildren = allChildrenKeys
+    .map((key, idx) => ({ key, node: allChildrenNodes[idx] }))
+    .filter((item): item is { key: string; node: NavNode } => item.node !== undefined)
+    .sort((a, b) => {
+      const rankDifference = browseRank(a.key) - browseRank(b.key);
+      if (rankDifference !== 0) return rankDifference;
+      return a.node.title.localeCompare(b.node.title);
+    })
+    .map((item) => item.key);
+
+  let allList;
+  if (validAllChildren.length > 0) {
+    allList = {
+      type: 'group',
+      title: 'Browse',
+      icon: 'Telescope',
+      pages: validAllChildren,
+    };
+  }
+
+  const allNodes: Record<string, NavNode> = {
+    ...(domainsList ? { 'list:domains': domainsList } : {}),
+    ...(systemsList ? { 'list:systems': systemsList } : {}),
+    ...(internalSystemsList ? { 'list:systems-internal': internalSystemsList } : {}),
+    ...(externalSystemsScopedList ? { 'list:systems-external': externalSystemsScopedList } : {}),
+    ...(servicesList ? { 'list:services': servicesList } : {}),
+    ...(agentsList ? { 'list:agents': agentsList } : {}),
+    ...(adrsList ? { 'list:adrs': adrsList } : {}),
+    ...(externalSystemsList ? { 'list:external-systems': externalSystemsList } : {}),
+    ...(eventsList ? { 'list:events': eventsList } : {}),
+    ...(commandsList ? { 'list:commands': commandsList } : {}),
+    ...(queriesList ? { 'list:queries': queriesList } : {}),
+    ...(messagesList ? { 'list:messages': messagesList as NavNode } : {}),
+    ...(flowsList ? { 'list:flows': flowsList } : {}),
+    ...(containersList ? { 'list:containers': containersList } : {}),
+    ...(dataProductsList ? { 'list:data-products': dataProductsList } : {}),
+    ...(entitiesList ? { 'list:entities': entitiesList } : {}),
+    ...(designsList ? { 'list:designs': designsList } : {}),
+    ...(teamsList ? { 'list:teams': teamsList } : {}),
+    ...(usersList ? { 'list:users': usersList } : {}),
+    ...(channelList ? { 'list:channels': channelList as NavNode } : {}),
+    ...(peopleList ? { 'list:people': peopleList as NavNode } : {}),
+    ...(allList ? { 'list:all': allList as NavNode } : {}),
+  };
+
+  // System-level views (only show if visualiser is enabled and there are systems)
+  const systemNode: Record<string, NavNode> = {};
+
+  if (visualiserEnabled && systems.length > 0) {
+    systemNode['list:system'] = {
+      type: 'group',
+      title: 'System',
+      icon: 'Globe',
+      pages: [
+        {
+          type: 'item',
+          title: 'System Context Map',
+          href: buildUrl('/visualiser/system-context-map'),
+        },
+      ],
+    };
+  }
+
+  const allGeneratedNodes = {
+    ...rootDomainsNodes,
+    ...(topLevelDiagramsNode ? { 'list:top-level-diagrams': topLevelDiagramsNode } : {}),
+    ...domainNodes,
+    ...systemNodes,
+    ...agentNodes,
+    ...adrNodes,
+    ...serviceNodes,
+    ...messageNodes,
+    ...channelNodes,
+    ...containerNodes,
+    ...dataProductNodes,
+    ...entityNodes,
+    ...flowNodes,
+    ...userNodes,
+    ...teamNodes,
+    ...diagramNodes,
+    ...designNodes,
+    ...systemNode,
+    ...allNodes,
+  };
+
+  // only filter if child is string
+  const defaultPages = ['list:top-level-domains', 'list:all'];
+  if (topLevelDiagramsNode) {
+    defaultPages.splice(1, 0, 'list:top-level-diagrams');
+  }
+  const rootNavigationConfig = config?.navigation?.pages || defaultPages;
+
+  const navigationConfig = {
+    roots: rootNavigationConfig,
+    nodes: allGeneratedNodes,
+  };
+
+  memoryCache = navigationConfig;
+
+  return navigationConfig;
+};
diff --git a/packages/core/eventcatalog/src/stores/theme-store.ts b/packages/core/eventcatalog/src/stores/theme-store.ts
new file mode 100644
index 000000000..115edd8eb
--- /dev/null
+++ b/packages/core/eventcatalog/src/stores/theme-store.ts
@@ -0,0 +1,89 @@
+import { atom } from 'nanostores';
+
+const THEME_KEY = 'eventcatalog-theme';
+
+export type Theme = 'light' | 'dark';
+
+export const themeStore = atom<Theme>('dark');
+
+// Default theme when the user has not explicitly chosen one.
+const getDefaultTheme = (): Theme => {
+  return 'dark';
+};
+
+// Apply theme to document via data-theme attribute
+const applyTheme = (theme: Theme) => {
+  if (typeof document !== 'undefined') {
+    document.documentElement.setAttribute('data-theme', theme);
+  }
+};
+
+// Initialize store from localStorage or system preference
+const initStore = () => {
+  if (typeof window !== 'undefined') {
+    try {
+      const stored = localStorage.getItem(THEME_KEY) as Theme | null;
+      if (stored && (stored === 'light' || stored === 'dark')) {
+        // User has explicitly chosen a theme, use that
+        themeStore.set(stored);
+        applyTheme(stored);
+      } else {
+        // No stored preference, use the catalog default
+        const defaultTheme = getDefaultTheme();
+        themeStore.set(defaultTheme);
+        applyTheme(defaultTheme);
+      }
+    } catch (e) {
+      console.warn('Failed to load theme:', e);
+      applyTheme(getDefaultTheme());
+    }
+  }
+};
+
+if (typeof window !== 'undefined') {
+  initStore();
+
+  // Listen for system preference changes
+  if (window.matchMedia) {
+    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
+      // Only follow system preference if user hasn't explicitly set a theme
+      const stored = localStorage.getItem(THEME_KEY);
+      if (!stored) {
+        const newTheme = e.matches ? 'dark' : 'light';
+        themeStore.set(newTheme);
+        applyTheme(newTheme);
+      }
+    });
+  }
+
+  // Listen for storage events (cross-tab sync)
+  window.addEventListener('storage', (e) => {
+    if (e.key === THEME_KEY) {
+      initStore();
+    }
+  });
+
+  // Listen for custom events (same-tab sync between instances)
+  window.addEventListener('theme-updated', () => {
+    initStore();
+  });
+}
+
+export const setTheme = (theme: Theme) => {
+  themeStore.set(theme);
+  applyTheme(theme);
+  if (typeof window !== 'undefined') {
+    try {
+      localStorage.setItem(THEME_KEY, theme);
+      // Dispatch event to notify other store instances/components
+      window.dispatchEvent(new CustomEvent('theme-updated'));
+    } catch (e) {
+      console.warn('Failed to save theme:', e);
+    }
+  }
+};
+
+export const toggleTheme = () => {
+  const current = themeStore.get();
+  setTheme(current === 'light' ? 'dark' : 'light');
+};
diff --git a/packages/core/eventcatalog/src/styles/tailwind.css b/packages/core/eventcatalog/src/styles/tailwind.css
new file mode 100644
index 000000000..bc445a8b1
--- /dev/null
+++ b/packages/core/eventcatalog/src/styles/tailwind.css
@@ -0,0 +1,120 @@
+@import 'tailwindcss';
+
+@plugin "@tailwindcss/typography";
+
+/*
+ * EventCatalog renders MDX inside Tailwind Typography's `.prose` wrapper.
+ * Typography adds decorative backticks around inline code via pseudo-elements;
+ * docs should show only the code content itself.
+ */
+.prose code::before,
+.prose code::after {
+  content: '';
+}
+
+.prose :not(pre) > code {
+  background-color: oklab(0.97 0 0.0013 / 0.5);
+  border-radius: 0.25rem;
+  font-family: var(--font-mono);
+  padding: 0.125rem 0.375rem;
+  font-weight: 400;
+}
+
+/* Dark mode uses data-theme attribute, not prefers-color-scheme */
+@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));
+
+@theme {
+  --font-sans: 'Inter', sans-serif;
+
+  --breakpoint-xxl: 1990px;
+
+  --color-primary: #a855f7;
+  --color-secondary-light: #ff9980;
+  --color-secondary: #ff6633;
+  --color-secondary-dark: #cc3300;
+
+  --spacing-header: 4rem;
+  --spacing-content: calc(100vh - 4rem);
+
+  --animate-progress-bar: progress-bar 2s linear infinite;
+  --animate-progress-bar-reverse: progress-bar-reverse 2s linear infinite;
+  --animate-overlayShow: overlayShow 200ms ease-out;
+  --animate-contentShow: contentShow 200ms ease-out;
+
+  @keyframes progress-bar {
+    0% {
+      transform: translateX(-100%);
+    }
+    100% {
+      transform: translateX(100%);
+    }
+  }
+
+  @keyframes progress-bar-reverse {
+    0% {
+      transform: translateX(100%);
+    }
+    100% {
+      transform: translateX(-100%);
+    }
+  }
+
+  @keyframes overlayShow {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
+
+  @keyframes contentShow {
+    from {
+      opacity: 0;
+      transform: scale(0.96);
+    }
+    to {
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+}
+
+/*
+ * Safelist: dynamic color classes used in components that construct class names
+ * at runtime (e.g. `bg-${color}-50`). Tailwind v4 can't detect these from source
+ * scanning, so we explicitly declare them here.
+ *
+ * Colors used: orange, blue, green, emerald, amber, violet, pink, purple, gray, yellow, teal, cyan, indigo
+ * Used in: SchemaListItem, Grids/components, SchemaExplorer, MessageGrid
+ */
+@source inline("bg-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-{50,100}");
+@source inline("bg-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-500/{10,20}");
+@source inline("text-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-{400,500,600,700}");
+@source inline("border-l-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-500");
+@source inline("ring-2");
+@source inline("ring-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-500");
+
+/* Border color variants for MessageGrid cards */
+@source inline("border-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-{200,300}");
+@source inline("{dark:,}border-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-500/{30,50}");
+@source inline("{hover:,dark:hover:,}border-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-{300,400,500,500/50}");
+
+/* Explicit safelist classes used in various components */
+@source inline("bg-{blue,orange}-600");
+@source inline("bg-{red,yellow,pink,green,blue,indigo}-50");
+@source inline("bg-{yellow,pink,green,blue,indigo}-100");
+@source inline("border-l-{red,yellow,blue}-500");
+@source inline("text-[5px] text-[9px] min-h-[100px]");
+
+/* Gradient classes for dynamic colors */
+@source inline("from-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-{100,200,300,400,500,600,700}");
+@source inline("to-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-{100,200,300,400,500,600,700}");
+
+/* Dark variant safelist for dynamic colors */
+@source inline("{dark:,}bg-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-{100,200,400,500}");
+@source inline("{dark:,}bg-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-500/{20,30}");
+@source inline("{dark:,}text-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-{100,300,400,500,800}");
+@source inline("{dark:,group-hover:,}text-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-{100,300,400,500,600,800}");
+@source inline("{dark:,}ring-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-500/30");
+@source inline("{group-hover:,dark:group-hover:,}text-{orange,blue,green,emerald,amber,violet,pink,purple,gray,yellow,teal,cyan,indigo}-{400,600}");
diff --git a/packages/core/eventcatalog/src/styles/theme.css b/packages/core/eventcatalog/src/styles/theme.css
new file mode 100644
index 000000000..d0b2b184d
--- /dev/null
+++ b/packages/core/eventcatalog/src/styles/theme.css
@@ -0,0 +1,425 @@
+/**
+ * EventCatalog Theme CSS Variables
+ *
+ * Override these variables in your eventcatalog.styles.css file to customize the theme.
+ * Example:
+ *   :root[data-theme="light"] {
+ *     --ec-header-bg: #1e293b;
+ *     --ec-primary: #3b82f6;
+ *   }
+ *
+ * Supported themes: light, dark (more can be added)
+ */
+
+/* Default/Light theme */
+:root,
+:root[data-theme="light"] {
+  /* Header */
+  --ec-header-bg: 255 255 255; /* #ffffff */
+  --ec-header-text: 15 23 42; /* #0f172a (slate-900) */
+  --ec-header-border: 229 229 229; /* #e5e5e5 (neutral-200) */
+
+  /* Primary brand color */
+  --ec-primary: 126 34 206; /* #7e22ce (purple-700) */
+  --ec-primary-hover: 107 33 168; /* #6b21a8 (purple-800) */
+
+  /* Accent colors - used for selections, highlights, interactive elements */
+  --ec-accent: 126 34 206; /* #7e22ce (purple-700) */
+  --ec-accent-hover: 107 33 168; /* #6b21a8 (purple-800) */
+  --ec-accent-subtle: 233 213 255; /* #e9d5ff (purple-200) */
+  --ec-accent-text: 88 28 135; /* #581c87 (purple-900) */
+  --ec-accent-gradient-from: 126 34 206; /* #7e22ce (purple-700) */
+  --ec-accent-gradient-to: 88 28 135; /* #581c87 (purple-900) */
+
+  /* Buttons */
+  --ec-button-bg: 15 23 42; /* #0f172a */
+  --ec-button-bg-hover: 30 41 59; /* #1e293b */
+  --ec-button-text: 255 255 255; /* #ffffff */
+
+  /* Dropdowns & menus */
+  --ec-dropdown-bg: 255 255 255; /* #ffffff */
+  --ec-dropdown-text: 51 65 85; /* #334155 (slate-700) */
+  --ec-dropdown-hover: 248 250 252; /* #f8fafc (slate-50) */
+  --ec-dropdown-border: 226 232 240; /* #e2e8f0 (slate-200) */
+
+  /* Icons */
+  --ec-icon-color: 100 116 139; /* #64748b (slate-500) */
+  --ec-icon-hover: 51 65 85; /* #334155 (slate-700) */
+
+  /* Sidebar / Vertical Nav (icon bar) */
+  --ec-sidebar-bg: 255 255 255; /* #ffffff */
+  --ec-sidebar-bg-gradient: 248 250 252; /* #f8fafc (slate-50) */
+  --ec-sidebar-border: 229 229 229; /* #e5e5e5 (neutral-200) */
+  --ec-sidebar-text: 71 85 105; /* #475569 (slate-600) */
+  --ec-sidebar-active-bg: 15 23 42; /* #0f172a */
+  --ec-sidebar-active-text: 255 255 255; /* #ffffff */
+  --ec-sidebar-hover-bg: 15 23 42; /* #0f172a - black on hover like active */
+
+  /* Rail / inset-panel surface (5% off the sidebar bg). Use for navigation rails,
+     filter panels, and any inset surface that should sit slightly off the page. */
+  --ec-rail-bg: 250 250 250; /* #fafafa - 2% darker than white */
+  --ec-rail-active-bg: 218 218 218; /* ~10% darker than rail bg */
+
+  /* Nested sidebar content */
+  --ec-content-bg: 255 255 255; /* #ffffff */
+  --ec-content-text: 15 23 42; /* #0f172a (slate-900) */
+  --ec-content-text-muted: 100 116 139; /* #64748b (slate-500) */
+  --ec-content-text-secondary: 71 85 105; /* #475569 (slate-600) */
+  --ec-content-border: 229 229 229; /* #e5e5e5 (neutral-200) */
+  --ec-content-hover: 248 250 252; /* #f8fafc (slate-50) */
+  --ec-content-active: 245 243 255; /* #f5f3ff (violet-50) */
+
+  /* Input fields */
+  --ec-input-bg: 248 250 252; /* #f8fafc (slate-50) */
+  --ec-input-border: 226 232 240; /* #e2e8f0 (slate-200) */
+  --ec-input-text: 15 23 42; /* #0f172a */
+  --ec-input-placeholder: 148 163 184; /* #94a3b8 (slate-400) */
+
+  /* Group headers */
+  --ec-group-icon-bg: 233 213 255; /* #e9d5ff (purple-200) */
+  --ec-group-icon-text: 88 28 135; /* #581c87 (purple-900) */
+
+  /* Main content/docs area */
+  --ec-page-bg: 255 255 255; /* #ffffff */
+  --ec-page-text: 15 23 42; /* #0f172a */
+  --ec-page-text-muted: 100 116 139; /* #64748b */
+  --ec-page-border: 229 229 229; /* #e5e5e5 (neutral-200) */
+
+  /* Card/elevated surfaces */
+  --ec-card-bg: 255 255 255; /* #ffffff */
+
+  /* Code blocks */
+  --ec-code-bg: 250 250 250; /* #fafafa - light for light mode */
+
+  /* Badge colors - light mode */
+  --ec-badge-domain-bg: 254 249 195; /* yellow-100 */
+  --ec-badge-domain-text: 161 98 7; /* yellow-700 */
+  --ec-badge-service-bg: 252 231 243; /* pink-100 */
+  --ec-badge-service-text: 190 24 93; /* pink-700 */
+  --ec-badge-event-bg: 254 243 199; /* amber-100 */
+  --ec-badge-event-text: 180 83 9; /* amber-700 */
+  --ec-badge-command-bg: 252 231 243; /* pink-100 */
+  --ec-badge-command-text: 190 24 93; /* pink-700 */
+  --ec-badge-query-bg: 243 232 255; /* purple-100 */
+  --ec-badge-query-text: 126 34 206; /* purple-700 */
+  --ec-badge-message-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-message-text: 67 56 202; /* indigo-700 */
+  --ec-badge-design-bg: 204 251 241; /* teal-100 */
+  --ec-badge-design-text: 15 118 110; /* teal-700 */
+  --ec-badge-channel-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-channel-text: 67 56 202; /* indigo-700 */
+  --ec-badge-container-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-container-text: 67 56 202; /* indigo-700 */
+  --ec-badge-data-product-bg: 219 234 254; /* blue-100 */
+  --ec-badge-data-product-text: 30 64 175; /* blue-800 */
+  --ec-badge-default-bg: 243 244 246; /* gray-100 */
+  --ec-badge-default-text: 75 85 99; /* gray-600 */
+
+  /* User-defined badge colors - light mode */
+  --ec-badge-color-slate-background: 248 250 252;
+  --ec-badge-color-slate-text: 71 85 105;
+  --ec-badge-color-gray-background: 249 250 251;
+  --ec-badge-color-gray-text: 75 85 99;
+  --ec-badge-color-zinc-background: 250 250 250;
+  --ec-badge-color-zinc-text: 82 82 91;
+  --ec-badge-color-neutral-background: 250 250 250;
+  --ec-badge-color-neutral-text: 82 82 82;
+  --ec-badge-color-stone-background: 250 250 249;
+  --ec-badge-color-stone-text: 87 83 78;
+  --ec-badge-color-red-background: 254 242 242;
+  --ec-badge-color-red-text: 185 28 28;
+  --ec-badge-color-orange-background: 255 247 237;
+  --ec-badge-color-orange-text: 194 65 12;
+  --ec-badge-color-amber-background: 255 251 235;
+  --ec-badge-color-amber-text: 180 83 9;
+  --ec-badge-color-yellow-background: 254 252 232;
+  --ec-badge-color-yellow-text: 161 98 7;
+  --ec-badge-color-lime-background: 247 254 231;
+  --ec-badge-color-lime-text: 77 124 15;
+  --ec-badge-color-green-background: 240 253 244;
+  --ec-badge-color-green-text: 21 128 61;
+  --ec-badge-color-emerald-background: 236 253 245;
+  --ec-badge-color-emerald-text: 4 120 87;
+  --ec-badge-color-teal-background: 240 253 250;
+  --ec-badge-color-teal-text: 15 118 110;
+  --ec-badge-color-cyan-background: 236 254 255;
+  --ec-badge-color-cyan-text: 14 116 144;
+  --ec-badge-color-sky-background: 240 249 255;
+  --ec-badge-color-sky-text: 3 105 161;
+  --ec-badge-color-blue-background: 239 246 255;
+  --ec-badge-color-blue-text: 29 78 216;
+  --ec-badge-color-indigo-background: 238 242 255;
+  --ec-badge-color-indigo-text: 67 56 202;
+  --ec-badge-color-violet-background: 245 243 255;
+  --ec-badge-color-violet-text: 109 40 217;
+  --ec-badge-color-purple-background: 250 245 255;
+  --ec-badge-color-purple-text: 126 34 206;
+  --ec-badge-color-fuchsia-background: 253 244 255;
+  --ec-badge-color-fuchsia-text: 162 28 175;
+  --ec-badge-color-pink-background: 253 242 248;
+  --ec-badge-color-pink-text: 190 24 93;
+  --ec-badge-color-rose-background: 255 241 242;
+  --ec-badge-color-rose-text: 190 18 60;
+}
+
+/* Dark theme */
+:root[data-theme="dark"] {
+  /*
+   * Modern dark theme inspired by Mintlify
+   * Uses deep blacks with subtle cool undertones for a refined look
+   */
+
+  /* Header - deep black with cool border */
+  --ec-header-bg: 9 13 13; /* #090d0d */
+  --ec-header-text: 240 246 252; /* #f0f6fc - soft white */
+  --ec-header-border: 38 41 47; /* #26292f - lifted ~20% */
+
+  /* Primary brand color */
+  --ec-primary: 147 51 234; /* #9333ea (purple-600) */
+  --ec-primary-hover: 126 34 206; /* #7e22ce (purple-700) */
+
+  /* Accent colors - used for selections, highlights, interactive elements */
+  --ec-accent: 147 51 234; /* #9333ea (purple-600) */
+  --ec-accent-hover: 126 34 206; /* #7e22ce (purple-700) */
+  --ec-accent-subtle: 88 28 135 / 0.3; /* purple-900/30 */
+  --ec-accent-text: 192 132 252; /* #c084fc (purple-400) */
+  --ec-accent-gradient-from: 147 51 234; /* #9333ea (purple-600) */
+  --ec-accent-gradient-to: 126 34 206; /* #7e22ce (purple-700) */
+
+  /* Buttons - accent color for better visibility */
+  --ec-button-bg: 147 51 234; /* #9333ea - purple-600 */
+  --ec-button-bg-hover: 168 85 247; /* #a855f7 - purple-500 */
+  --ec-button-text: 255 255 255; /* #ffffff - white text */
+
+  /* Dropdowns & menus - elevated surface */
+  --ec-dropdown-bg: 22 27 34; /* #161b22 - slightly elevated */
+  --ec-dropdown-text: 201 209 217; /* #c9d1d9 */
+  --ec-dropdown-hover: 33 38 45; /* #21262d */
+  --ec-dropdown-border: 48 54 61; /* #30363d */
+
+  /* Icons - muted gray that pops on hover */
+  --ec-icon-color: 139 148 158; /* #8b949e */
+  --ec-icon-hover: 240 246 252; /* #f0f6fc */
+
+  /* Sidebar / Vertical Nav (icon bar) */
+  --ec-sidebar-bg: 9 13 13; /* #090d0d - matches page bg */
+  --ec-sidebar-bg-gradient: 9 13 13; /* #090d0d */
+  --ec-sidebar-border: 51 57 65; /* #333941 - lifted ~20% */
+  --ec-sidebar-text: 139 148 158; /* #8b949e */
+  --ec-sidebar-active-bg: 48 54 61; /* #30363d - subtle highlight */
+  --ec-sidebar-active-text: 240 246 252; /* #f0f6fc */
+  --ec-sidebar-hover-bg: 33 38 45; /* #21262d */
+
+  /* Rail / inset-panel surface (~2% lifted from the page bg) */
+  --ec-rail-bg: 15 19 19; /* ~2% lighter than #090d0d */
+  --ec-rail-active-bg: 35 38 38; /* ~10% lifted off rail bg */
+
+  /* Nested sidebar content */
+  --ec-content-bg: 9 13 13; /* #090d0d - matches page bg */
+  --ec-content-text: 201 209 217; /* #c9d1d9 - softer than pure white */
+  --ec-content-text-muted: 139 148 158; /* #8b949e */
+  --ec-content-text-secondary: 170 178 186; /* #aab2ba - sidebar children text */
+  --ec-content-border: 51 57 65; /* #333941 - lifted ~20% */
+  --ec-content-hover: 22 27 34; /* #161b22 */
+  --ec-content-active: 33 38 45; /* #21262d */
+
+  /* Input fields - subtle inset look */
+  --ec-input-bg: 13 17 23; /* #0d1117 */
+  --ec-input-border: 48 54 61; /* #30363d */
+  --ec-input-text: 240 246 252; /* #f0f6fc */
+  --ec-input-placeholder: 110 118 129; /* #6e7681 */
+
+  /* Group headers */
+  --ec-group-icon-bg: 33 38 45; /* #21262d */
+  --ec-group-icon-text: 192 132 252; /* #c084fc (purple-400) */
+
+  /* Main content/docs area - base dark surface */
+  --ec-page-bg: 9 13 13; /* #090d0d */
+  --ec-page-text: 240 246 252; /* #f0f6fc */
+  --ec-page-text-muted: 163 172 182; /* #a3acb6 */
+  --ec-page-border: 38 41 47; /* #26292f - lifted ~20% */
+
+  /* Card/elevated surfaces - for depth */
+  --ec-card-bg: 22 27 34; /* #161b22 */
+
+  /* Code blocks */
+  --ec-code-bg: 22 27 34; /* #161b22 - elevated dark surface */
+
+  /* Badge colors - dark mode (subtle with good contrast) */
+  --ec-badge-domain-bg: 113 63 18 / 0.3; /* yellow-900/30 */
+  --ec-badge-domain-text: 253 224 71; /* yellow-300 */
+  --ec-badge-service-bg: 131 24 67 / 0.3; /* pink-900/30 */
+  --ec-badge-service-text: 249 168 212; /* pink-300 */
+  --ec-badge-event-bg: 120 53 15 / 0.3; /* amber-900/30 */
+  --ec-badge-event-text: 252 211 77; /* amber-300 */
+  --ec-badge-command-bg: 131 24 67 / 0.3; /* pink-900/30 */
+  --ec-badge-command-text: 249 168 212; /* pink-300 */
+  --ec-badge-query-bg: 88 28 135 / 0.3; /* purple-900/30 */
+  --ec-badge-query-text: 216 180 254; /* purple-300 */
+  --ec-badge-message-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-message-text: 165 180 252; /* indigo-300 */
+  --ec-badge-design-bg: 17 94 89 / 0.3; /* teal-900/30 */
+  --ec-badge-design-text: 94 234 212; /* teal-300 */
+  --ec-badge-channel-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-channel-text: 165 180 252; /* indigo-300 */
+  --ec-badge-container-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-container-text: 165 180 252; /* indigo-300 */
+  --ec-badge-data-product-bg: 30 64 175 / 0.3; /* blue-800/30 */
+  --ec-badge-data-product-text: 147 197 253; /* blue-300 */
+  --ec-badge-default-bg: 63 63 70 / 0.3; /* zinc-700/30 */
+  --ec-badge-default-text: 212 212 216; /* zinc-300 */
+
+  /* User-defined badge colors - dark mode */
+  --ec-badge-color-slate-background: 51 65 85 / 0.28;
+  --ec-badge-color-slate-text: 203 213 225;
+  --ec-badge-color-gray-background: 55 65 81 / 0.28;
+  --ec-badge-color-gray-text: 209 213 219;
+  --ec-badge-color-zinc-background: 63 63 70 / 0.28;
+  --ec-badge-color-zinc-text: 212 212 216;
+  --ec-badge-color-neutral-background: 64 64 64 / 0.28;
+  --ec-badge-color-neutral-text: 212 212 212;
+  --ec-badge-color-stone-background: 68 64 60 / 0.28;
+  --ec-badge-color-stone-text: 214 211 209;
+  --ec-badge-color-red-background: 127 29 29 / 0.28;
+  --ec-badge-color-red-text: 252 165 165;
+  --ec-badge-color-orange-background: 124 45 18 / 0.28;
+  --ec-badge-color-orange-text: 253 186 116;
+  --ec-badge-color-amber-background: 120 53 15 / 0.28;
+  --ec-badge-color-amber-text: 252 211 77;
+  --ec-badge-color-yellow-background: 113 63 18 / 0.28;
+  --ec-badge-color-yellow-text: 253 224 71;
+  --ec-badge-color-lime-background: 54 83 20 / 0.28;
+  --ec-badge-color-lime-text: 190 242 100;
+  --ec-badge-color-green-background: 20 83 45 / 0.28;
+  --ec-badge-color-green-text: 134 239 172;
+  --ec-badge-color-emerald-background: 6 78 59 / 0.28;
+  --ec-badge-color-emerald-text: 110 231 183;
+  --ec-badge-color-teal-background: 17 94 89 / 0.28;
+  --ec-badge-color-teal-text: 94 234 212;
+  --ec-badge-color-cyan-background: 21 94 117 / 0.28;
+  --ec-badge-color-cyan-text: 103 232 249;
+  --ec-badge-color-sky-background: 12 74 110 / 0.28;
+  --ec-badge-color-sky-text: 125 211 252;
+  --ec-badge-color-blue-background: 30 64 175 / 0.28;
+  --ec-badge-color-blue-text: 147 197 253;
+  --ec-badge-color-indigo-background: 49 46 129 / 0.28;
+  --ec-badge-color-indigo-text: 165 180 252;
+  --ec-badge-color-violet-background: 76 29 149 / 0.28;
+  --ec-badge-color-violet-text: 196 181 253;
+  --ec-badge-color-purple-background: 88 28 135 / 0.28;
+  --ec-badge-color-purple-text: 216 180 254;
+  --ec-badge-color-fuchsia-background: 112 26 117 / 0.28;
+  --ec-badge-color-fuchsia-text: 240 171 252;
+  --ec-badge-color-pink-background: 131 24 67 / 0.28;
+  --ec-badge-color-pink-text: 249 168 212;
+  --ec-badge-color-rose-background: 136 19 55 / 0.28;
+  --ec-badge-color-rose-text: 253 164 175;
+}
+
+/* Dark mode prose overrides for documentation content */
+:root[data-theme="dark"] .prose {
+  --tw-prose-body: rgb(139 148 158); /* #8b949e - muted body text */
+  --tw-prose-headings: rgb(201 209 217); /* #c9d1d9 - soft white headings */
+  --tw-prose-lead: rgb(110 118 129); /* #6e7681 */
+  --tw-prose-links: rgb(168 85 247); /* purple-500 */
+  --tw-prose-bold: rgb(201 209 217); /* #c9d1d9 */
+  --tw-prose-counters: rgb(110 118 129); /* #6e7681 */
+  --tw-prose-bullets: rgb(72 79 88); /* #484f58 */
+  --tw-prose-hr: rgb(33 38 45); /* #21262d */
+  --tw-prose-quotes: rgb(201 209 217); /* #c9d1d9 */
+  --tw-prose-quote-borders: rgb(48 54 61); /* #30363d */
+  --tw-prose-captions: rgb(110 118 129); /* #6e7681 */
+  --tw-prose-code: rgb(201 209 217); /* #c9d1d9 */
+  --tw-prose-pre-code: rgb(139 148 158); /* #8b949e */
+  --tw-prose-pre-bg: rgb(22 27 34); /* #161b22 */
+  --tw-prose-th-borders: rgb(48 54 61); /* #30363d */
+  --tw-prose-td-borders: rgb(33 38 45); /* #21262d */
+}
+
+:root[data-theme="dark"] .prose code {
+  background-color: rgb(33 38 45); /* #21262d */
+  border-radius: 0.25rem;
+  padding: 0.125rem 0.375rem;
+}
+
+:root[data-theme="dark"] .prose pre {
+  background-color: rgb(22 27 34); /* #161b22 */
+  border: 1px solid rgb(33 38 45); /* #21262d */
+}
+
+:root[data-theme="dark"] .prose a {
+  color: rgb(168 85 247); /* purple-500 */
+}
+
+:root[data-theme="dark"] .prose a:hover {
+  color: rgb(192 132 252); /* purple-400 */
+}
+
+:root[data-theme="dark"] .prose strong {
+  color: rgb(240 246 252); /* #f0f6fc */
+}
+
+:root[data-theme="dark"] .prose table th {
+  color: rgb(240 246 252); /* #f0f6fc */
+}
+
+:root[data-theme="dark"] .prose table td {
+  border-color: rgb(33 38 45); /* #21262d */
+}
+
+/* Invert dark SVG icons in dark mode so they stay visible */
+:root[data-theme="dark"] .ec-themed-icon {
+  filter: invert(1);
+}
+
+/*
+ * Expressive Code (code blocks) — match the EventCatalog editor look:
+ * single rounded container, generous padding, no scrollbar gutter when wrapping.
+ */
+.expressive-code {
+  margin: 1rem 0;
+  --ec-codeFontSize: 0.88em;
+}
+
+.expressive-code .frame {
+  box-shadow: none !important;
+  background: transparent !important;
+}
+
+.expressive-code .frame pre {
+  border: 1px solid rgb(var(--ec-page-border)) !important;
+  border-radius: 0.5rem !important;
+  padding: 0 !important;
+  overflow: hidden !important;
+  scrollbar-width: none !important;
+}
+
+.expressive-code .frame pre > code {
+  padding: 1rem 0 !important;
+  background: var(--code-background);
+}
+
+.expressive-code .frame pre::-webkit-scrollbar,
+.expressive-code .frame pre::-webkit-scrollbar-track,
+.expressive-code .frame pre::-webkit-scrollbar-thumb {
+  display: none !important;
+  width: 0 !important;
+  height: 0 !important;
+  background: transparent !important;
+}
+
+.expressive-code .frame .copy button {
+  border-radius: 0.375rem;
+}
+
+/* Hide the "Copied!" tooltip and instead swap the copy icon for a checkmark
+   while feedback is active. Reverts back to the copy icon automatically when
+   the feedback element is removed. */
+.expressive-code .frame .copy .feedback {
+  display: none !important;
+}
+
+.expressive-code .frame .copy:has(.feedback) button::after {
+  -webkit-mask-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'><polyline points='20 6 9 17 4 12'/></svg>") !important;
+  mask-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'><polyline points='20 6 9 17 4 12'/></svg>") !important;
+}
diff --git a/packages/core/eventcatalog/src/styles/themes/forest.css b/packages/core/eventcatalog/src/styles/themes/forest.css
new file mode 100644
index 000000000..2cdba6c83
--- /dev/null
+++ b/packages/core/eventcatalog/src/styles/themes/forest.css
@@ -0,0 +1,246 @@
+/**
+ * Forest Theme for EventCatalog
+ *
+ * A natural, grounded theme inspired by deep forest greens.
+ * Dark, rich greens with an earthy, calming presence.
+ */
+
+/* Forest Light Mode */
+:root[data-catalog-theme="forest"],
+:root[data-catalog-theme="forest"][data-theme="light"] {
+  /* Header - clean white */
+  --ec-header-bg: 255 255 255; /* #ffffff */
+  --ec-header-text: 20 20 20; /* #141414 */
+  --ec-header-border: 229 229 229; /* #e5e5e5 (neutral-200) */
+
+  /* Primary brand color - deep forest green */
+  --ec-primary: 22 101 52; /* #166534 green-800 */
+  --ec-primary-hover: 20 83 45; /* #14532d green-900 */
+
+  /* Accent colors - deep forest green */
+  --ec-accent: 22 101 52; /* #166534 (green-800) */
+  --ec-accent-hover: 20 83 45; /* #14532d (green-900) */
+  --ec-accent-subtle: 220 252 231; /* #dcfce7 (green-100) */
+  --ec-accent-text: 20 83 45; /* #14532d (green-900) */
+  --ec-accent-gradient-from: 22 101 52; /* #166534 (green-800) */
+  --ec-accent-gradient-to: 20 83 45; /* #14532d (green-900) */
+
+  /* Buttons */
+  --ec-button-bg: 22 101 52; /* #166534 green-800 */
+  --ec-button-bg-hover: 20 83 45; /* #14532d green-900 */
+  --ec-button-text: 255 255 255; /* #ffffff */
+
+  /* Dropdowns & menus */
+  --ec-dropdown-bg: 255 255 255; /* #ffffff */
+  --ec-dropdown-text: 55 65 81; /* #374151 gray-700 */
+  --ec-dropdown-hover: 240 253 244; /* #f0fdf4 green-50 */
+  --ec-dropdown-border: 229 229 229; /* #e5e5e5 (neutral-200) */
+
+  /* Icons */
+  --ec-icon-color: 75 85 99; /* #4b5563 gray-600 */
+  --ec-icon-hover: 22 101 52; /* #166534 green-800 */
+
+  /* Sidebar / Vertical Nav */
+  --ec-sidebar-bg: 255 255 255; /* #ffffff */
+  --ec-sidebar-bg-gradient: 240 253 244; /* #f0fdf4 green-50 */
+  --ec-sidebar-border: 229 229 229; /* #e5e5e5 (neutral-200) */
+  --ec-sidebar-text: 75 85 99; /* #4b5563 gray-600 */
+  --ec-sidebar-active-bg: 22 101 52; /* #166534 green-800 */
+  --ec-sidebar-active-text: 255 255 255; /* #ffffff */
+  --ec-sidebar-hover-bg: 22 101 52; /* #166534 green-800 */
+
+  /* Rail / inset-panel surface (5% off the sidebar bg) */
+  --ec-rail-bg: 250 250 250; /* #fafafa - 2% darker than white */
+  --ec-rail-active-bg: 218 218 218; /* ~10% darker than rail bg */
+
+  /* Nested sidebar content */
+  --ec-content-bg: 255 255 255; /* #ffffff */
+  --ec-content-text: 17 24 39; /* #111827 gray-900 */
+  --ec-content-text-muted: 75 85 99; /* #4b5563 gray-600 */
+  --ec-content-text-secondary: 107 114 128; /* #6b7280 gray-500 */
+  --ec-content-border: 229 229 229; /* #e5e5e5 (neutral-200) */
+  --ec-content-hover: 249 250 251; /* #f9fafb gray-50 */
+  --ec-content-active: 220 252 231; /* #dcfce7 green-100 */
+
+  /* Input fields */
+  --ec-input-bg: 255 255 255; /* #ffffff */
+  --ec-input-border: 209 213 219; /* #d1d5db gray-300 */
+  --ec-input-text: 17 24 39; /* #111827 gray-900 */
+  --ec-input-placeholder: 156 163 175; /* #9ca3af gray-400 */
+
+  /* Group headers */
+  --ec-group-icon-bg: 220 252 231; /* #dcfce7 green-100 */
+  --ec-group-icon-text: 20 83 45; /* #14532d green-900 */
+
+  /* Main content/docs area */
+  --ec-page-bg: 255 255 255; /* #ffffff */
+  --ec-page-text: 17 24 39; /* #111827 gray-900 */
+  --ec-page-text-muted: 75 85 99; /* #4b5563 gray-600 */
+  --ec-page-border: 229 229 229; /* #e5e5e5 (neutral-200) */
+
+  /* Card/elevated surfaces */
+  --ec-card-bg: 255 255 255; /* #ffffff */
+
+  /* Code blocks */
+  --ec-code-bg: 250 250 250; /* #fafafa */
+
+  /* Badge colors - forest theme */
+  --ec-badge-domain-bg: 254 249 195; /* yellow-100 */
+  --ec-badge-domain-text: 161 98 7; /* yellow-700 */
+  --ec-badge-service-bg: 252 231 243; /* pink-100 */
+  --ec-badge-service-text: 190 24 93; /* pink-700 */
+  --ec-badge-event-bg: 254 243 199; /* amber-100 */
+  --ec-badge-event-text: 180 83 9; /* amber-700 */
+  --ec-badge-command-bg: 220 252 231; /* green-100 */
+  --ec-badge-command-text: 20 83 45; /* green-900 */
+  --ec-badge-query-bg: 207 250 254; /* cyan-100 */
+  --ec-badge-query-text: 21 94 117; /* cyan-800 */
+  --ec-badge-message-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-message-text: 67 56 202; /* indigo-700 */
+  --ec-badge-design-bg: 220 252 231; /* green-100 */
+  --ec-badge-design-text: 22 101 52; /* green-800 */
+  --ec-badge-channel-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-channel-text: 67 56 202; /* indigo-700 */
+  --ec-badge-container-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-container-text: 67 56 202; /* indigo-700 */
+  --ec-badge-data-product-bg: 219 234 254; /* blue-100 */
+  --ec-badge-data-product-text: 30 64 175; /* blue-800 */
+  --ec-badge-default-bg: 240 253 244; /* green-50 */
+  --ec-badge-default-text: 75 85 99; /* gray-600 */
+}
+
+/* Forest Dark Mode */
+:root[data-catalog-theme="forest"][data-theme="dark"] {
+  /* Header - deep forest dark */
+  --ec-header-bg: 3 7 18; /* #030712 gray-950 */
+  --ec-header-text: 243 244 246; /* #f3f4f6 gray-100 */
+  --ec-header-border: 31 41 55; /* #1f2937 gray-800 */
+
+  /* Accent colors - muted forest green for dark */
+  --ec-accent: 74 222 128; /* #4ade80 (green-400) */
+  --ec-accent-hover: 34 197 94; /* #22c55e (green-500) */
+  --ec-accent-subtle: 20 83 45 / 0.3; /* green-900/30 */
+  --ec-accent-text: 134 239 172; /* #86efac (green-300) */
+  --ec-accent-gradient-from: 74 222 128; /* #4ade80 (green-400) */
+  --ec-accent-gradient-to: 34 197 94; /* #22c55e (green-500) */
+
+  /* Buttons */
+  --ec-button-bg: 22 101 52; /* #166534 green-800 */
+  --ec-button-bg-hover: 34 197 94; /* #22c55e green-500 */
+  --ec-button-text: 255 255 255; /* #ffffff */
+
+  /* Dropdowns & menus */
+  --ec-dropdown-bg: 17 24 39; /* #111827 */
+  --ec-dropdown-text: 209 213 219; /* #d1d5db */
+  --ec-dropdown-hover: 31 41 55; /* #1f2937 */
+  --ec-dropdown-border: 31 41 55; /* #1f2937 gray-800 */
+
+  /* Icons */
+  --ec-icon-color: 156 163 175; /* #9ca3af */
+  --ec-icon-hover: 134 239 172; /* #86efac green-300 */
+
+  /* Sidebar / Vertical Nav */
+  --ec-sidebar-bg: 3 7 18; /* #030712 gray-950 */
+  --ec-sidebar-bg-gradient: 3 7 18; /* #030712 */
+  --ec-sidebar-border: 31 41 55; /* #1f2937 gray-800 */
+  --ec-sidebar-text: 156 163 175; /* #9ca3af */
+  --ec-sidebar-active-bg: 22 101 52; /* #166534 green-800 */
+  --ec-sidebar-active-text: 255 255 255; /* #ffffff */
+  --ec-sidebar-hover-bg: 31 41 55; /* #1f2937 */
+
+  /* Rail / inset-panel surface (5% lifted from the sidebar bg) */
+  --ec-rail-bg: 8 12 23; /* ~2% lighter than #030712 */
+  --ec-rail-active-bg: 34 38 49; /* ~10% lifted off rail bg */
+
+  /* Nested sidebar content */
+  --ec-content-bg: 3 7 18; /* #030712 */
+  --ec-content-text: 243 244 246; /* #f3f4f6 */
+  --ec-content-text-muted: 156 163 175; /* #9ca3af */
+  --ec-content-text-secondary: 156 163 175; /* #9ca3af */
+  --ec-content-border: 31 41 55; /* #1f2937 gray-800 */
+  --ec-content-hover: 17 24 39; /* #111827 */
+  --ec-content-active: 31 41 55; /* #1f2937 */
+
+  /* Input fields */
+  --ec-input-bg: 17 24 39; /* #111827 */
+  --ec-input-border: 31 41 55; /* #1f2937 gray-800 */
+  --ec-input-text: 243 244 246; /* #f3f4f6 */
+  --ec-input-placeholder: 107 114 128; /* #6b7280 */
+
+  /* Group headers */
+  --ec-group-icon-bg: 31 41 55; /* #1f2937 */
+  --ec-group-icon-text: 134 239 172; /* #86efac green-300 */
+
+  /* Main content/docs area */
+  --ec-page-bg: 3 7 18; /* #030712 */
+  --ec-page-text: 243 244 246; /* #f3f4f6 */
+  --ec-page-text-muted: 156 163 175; /* #9ca3af */
+  --ec-page-border: 31 41 55; /* #1f2937 gray-800 */
+
+  /* Card/elevated surfaces */
+  --ec-card-bg: 3 7 18; /* #030712 */
+
+  /* Code blocks */
+  --ec-code-bg: 17 24 39; /* #111827 */
+
+  /* Badge colors - forest dark */
+  --ec-badge-domain-bg: 113 63 18 / 0.3; /* yellow-900/30 */
+  --ec-badge-domain-text: 253 224 71; /* yellow-300 */
+  --ec-badge-service-bg: 131 24 67 / 0.3; /* pink-900/30 */
+  --ec-badge-service-text: 249 168 212; /* pink-300 */
+  --ec-badge-event-bg: 120 53 15 / 0.3; /* amber-900/30 */
+  --ec-badge-event-text: 252 211 77; /* amber-300 */
+  --ec-badge-command-bg: 20 83 45 / 0.3; /* green-900/30 */
+  --ec-badge-command-text: 134 239 172; /* green-300 */
+  --ec-badge-query-bg: 21 94 117 / 0.3; /* cyan-800/30 */
+  --ec-badge-query-text: 103 232 249; /* cyan-300 */
+  --ec-badge-message-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-message-text: 165 180 252; /* indigo-300 */
+  --ec-badge-design-bg: 20 83 45 / 0.3; /* green-900/30 */
+  --ec-badge-design-text: 134 239 172; /* green-300 */
+  --ec-badge-channel-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-channel-text: 165 180 252; /* indigo-300 */
+  --ec-badge-container-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-container-text: 165 180 252; /* indigo-300 */
+  --ec-badge-data-product-bg: 30 64 175 / 0.3; /* blue-800/30 */
+  --ec-badge-data-product-text: 147 197 253; /* blue-300 */
+  --ec-badge-default-bg: 55 65 81 / 0.3; /* gray-700/30 */
+  --ec-badge-default-text: 209 213 219; /* gray-300 */
+}
+
+/* Forest theme prose overrides */
+:root[data-catalog-theme="forest"][data-theme="dark"] .prose {
+  --tw-prose-body: rgb(156 163 175); /* gray-400 */
+  --tw-prose-headings: rgb(243 244 246); /* gray-100 */
+  --tw-prose-lead: rgb(107 114 128); /* gray-500 */
+  --tw-prose-links: rgb(74 222 128); /* green-400 */
+  --tw-prose-bold: rgb(243 244 246); /* gray-100 */
+  --tw-prose-counters: rgb(107 114 128); /* gray-500 */
+  --tw-prose-bullets: rgb(75 85 99); /* gray-600 */
+  --tw-prose-hr: rgb(31 41 55); /* gray-800 */
+  --tw-prose-quotes: rgb(243 244 246); /* gray-100 */
+  --tw-prose-quote-borders: rgb(55 65 81); /* gray-700 */
+  --tw-prose-captions: rgb(107 114 128); /* gray-500 */
+  --tw-prose-code: rgb(243 244 246); /* gray-100 */
+  --tw-prose-pre-code: rgb(156 163 175); /* gray-400 */
+  --tw-prose-pre-bg: rgb(17 24 39); /* gray-900 */
+  --tw-prose-th-borders: rgb(55 65 81); /* gray-700 */
+  --tw-prose-td-borders: rgb(31 41 55); /* gray-800 */
+}
+
+:root[data-catalog-theme="forest"][data-theme="dark"] .prose code {
+  background-color: rgb(31 41 55); /* gray-800 */
+}
+
+:root[data-catalog-theme="forest"][data-theme="dark"] .prose pre {
+  background-color: rgb(17 24 39); /* gray-900 */
+  border: 1px solid rgb(31 41 55); /* gray-800 */
+}
+
+:root[data-catalog-theme="forest"][data-theme="dark"] .prose a {
+  color: rgb(74 222 128); /* green-400 */
+}
+
+:root[data-catalog-theme="forest"][data-theme="dark"] .prose a:hover {
+  color: rgb(134 239 172); /* green-300 */
+}
diff --git a/packages/core/eventcatalog/src/styles/themes/ocean.css b/packages/core/eventcatalog/src/styles/themes/ocean.css
new file mode 100644
index 000000000..c7731e0b2
--- /dev/null
+++ b/packages/core/eventcatalog/src/styles/themes/ocean.css
@@ -0,0 +1,251 @@
+/**
+ * Ocean Theme for EventCatalog
+ *
+ * A calm, professional theme inspired by ocean colors.
+ * Deep blues and teals with soft aqua accents.
+ */
+
+/* Ocean Light Mode */
+:root[data-catalog-theme="ocean"],
+:root[data-catalog-theme="ocean"][data-theme="light"] {
+  /* Header - light with subtle teal tint */
+  --ec-header-bg: 255 255 255; /* #ffffff */
+  --ec-header-text: 15 23 42; /* #0f172a */
+  --ec-header-border: 226 232 240; /* #e2e8f0 slate-200 - visible border */
+
+  /* Primary brand color - ocean teal */
+  --ec-primary: 20 184 166; /* #14b8a6 teal-500 */
+  --ec-primary-hover: 13 148 136; /* #0d9488 teal-600 */
+
+  /* Accent colors - teal for ocean theme */
+  --ec-accent: 20 184 166; /* #14b8a6 (teal-500) */
+  --ec-accent-hover: 13 148 136; /* #0d9488 (teal-600) */
+  --ec-accent-subtle: 204 251 241; /* #ccfbf1 (teal-100) */
+  --ec-accent-text: 17 94 89; /* #115e59 (teal-800) */
+  --ec-accent-gradient-from: 20 184 166; /* #14b8a6 (teal-500) */
+  --ec-accent-gradient-to: 15 118 110; /* #0f766e (teal-700) */
+
+  /* Buttons */
+  --ec-button-bg: 15 118 110; /* #0f766e teal-700 */
+  --ec-button-bg-hover: 17 94 89; /* #115e59 teal-800 */
+  --ec-button-text: 255 255 255; /* #ffffff */
+
+  /* Dropdowns & menus */
+  --ec-dropdown-bg: 255 255 255; /* #ffffff */
+  --ec-dropdown-text: 51 65 85; /* #334155 */
+  --ec-dropdown-hover: 240 253 250; /* #f0fdfa teal-50 */
+  --ec-dropdown-border: 226 232 240; /* #e2e8f0 slate-200 */
+
+  /* Icons */
+  --ec-icon-color: 71 85 105; /* #475569 slate-600 */
+  --ec-icon-hover: 15 118 110; /* #0f766e teal-700 */
+
+  /* Sidebar / Vertical Nav - light with teal accent */
+  --ec-sidebar-bg: 255 255 255; /* #ffffff */
+  --ec-sidebar-bg-gradient: 240 253 250; /* #f0fdfa teal-50 */
+  --ec-sidebar-border: 226 232 240; /* #e2e8f0 slate-200 */
+  --ec-sidebar-text: 71 85 105; /* #475569 slate-600 */
+  --ec-sidebar-active-bg: 13 148 136; /* #0d9488 teal-600 */
+  --ec-sidebar-active-text: 255 255 255; /* #ffffff */
+  --ec-sidebar-hover-bg: 13 148 136; /* #0d9488 teal-600 - same as active for consistency */
+
+  /* Rail / inset-panel surface (5% off the sidebar bg) */
+  --ec-rail-bg: 250 250 250; /* #fafafa - 2% darker than white */
+  --ec-rail-active-bg: 218 218 218; /* ~10% darker than rail bg */
+
+  /* Nested sidebar content */
+  --ec-content-bg: 255 255 255; /* #ffffff */
+  --ec-content-text: 15 23 42; /* #0f172a */
+  --ec-content-text-muted: 71 85 105; /* #475569 slate-600 */
+  --ec-content-text-secondary: 100 116 139; /* #64748b slate-500 */
+  --ec-content-border: 226 232 240; /* #e2e8f0 slate-200 */
+  --ec-content-hover: 248 250 252; /* #f8fafc slate-50 - neutral gray for table headers */
+  --ec-content-active: 204 251 241; /* #ccfbf1 teal-100 */
+
+  /* Input fields */
+  --ec-input-bg: 255 255 255; /* #ffffff */
+  --ec-input-border: 203 213 225; /* #cbd5e1 slate-300 */
+  --ec-input-text: 15 23 42; /* #0f172a */
+  --ec-input-placeholder: 148 163 184; /* #94a3b8 */
+
+  /* Group headers */
+  --ec-group-icon-bg: 204 251 241; /* #ccfbf1 teal-100 */
+  --ec-group-icon-text: 17 94 89; /* #115e59 teal-800 */
+
+  /* Main content/docs area */
+  --ec-page-bg: 255 255 255; /* #ffffff */
+  --ec-page-text: 15 23 42; /* #0f172a */
+  --ec-page-text-muted: 71 85 105; /* #475569 slate-600 */
+  --ec-page-border: 226 232 240; /* #e2e8f0 slate-200 */
+
+  /* Card/elevated surfaces */
+  --ec-card-bg: 255 255 255; /* #ffffff */
+
+  /* Code blocks */
+  --ec-code-bg: 250 250 250; /* #fafafa - same as default light */
+
+  /* Badge colors - ocean theme */
+  --ec-badge-domain-bg: 254 249 195; /* yellow-100 */
+  --ec-badge-domain-text: 161 98 7; /* yellow-700 */
+  --ec-badge-service-bg: 252 231 243; /* pink-100 */
+  --ec-badge-service-text: 190 24 93; /* pink-700 */
+  --ec-badge-event-bg: 254 243 199; /* amber-100 */
+  --ec-badge-event-text: 180 83 9; /* amber-700 */
+  --ec-badge-command-bg: 204 251 241; /* teal-100 */
+  --ec-badge-command-text: 17 94 89; /* teal-800 */
+  --ec-badge-query-bg: 207 250 254; /* cyan-100 */
+  --ec-badge-query-text: 21 94 117; /* cyan-800 */
+  --ec-badge-message-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-message-text: 67 56 202; /* indigo-700 */
+  --ec-badge-design-bg: 204 251 241; /* teal-100 */
+  --ec-badge-design-text: 15 118 110; /* teal-700 */
+  --ec-badge-channel-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-channel-text: 67 56 202; /* indigo-700 */
+  --ec-badge-container-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-container-text: 67 56 202; /* indigo-700 */
+  --ec-badge-data-product-bg: 219 234 254; /* blue-100 */
+  --ec-badge-data-product-text: 30 64 175; /* blue-800 */
+  --ec-badge-default-bg: 240 253 250; /* teal-50 */
+  --ec-badge-default-text: 71 85 105; /* slate-600 */
+}
+
+/* Ocean Dark Mode */
+:root[data-catalog-theme="ocean"][data-theme="dark"] {
+  /*
+   * Unified dark background - all major surfaces share the same deep ocean color
+   * Creates a seamless, immersive dark experience
+   */
+
+  /* Header - matches page bg for unified look */
+  --ec-header-bg: 2 6 23; /* #020617 slate-950 - matches page bg */
+  --ec-header-text: 226 232 240; /* #e2e8f0 */
+  --ec-header-border: 30 41 59; /* #1e293b */
+
+  /* Accent colors - teal for ocean dark theme */
+  --ec-accent: 45 212 191; /* #2dd4bf (teal-400) */
+  --ec-accent-hover: 20 184 166; /* #14b8a6 (teal-500) */
+  --ec-accent-subtle: 17 94 89 / 0.3; /* teal-800/30 */
+  --ec-accent-text: 94 234 212; /* #5eead4 (teal-300) */
+  --ec-accent-gradient-from: 45 212 191; /* #2dd4bf (teal-400) */
+  --ec-accent-gradient-to: 20 184 166; /* #14b8a6 (teal-500) */
+
+  /* Buttons */
+  --ec-button-bg: 20 184 166; /* #14b8a6 teal-500 */
+  --ec-button-bg-hover: 45 212 191; /* #2dd4bf teal-400 */
+  --ec-button-text: 2 6 23; /* #020617 */
+
+  /* Dropdowns & menus - slightly elevated */
+  --ec-dropdown-bg: 15 23 42; /* #0f172a */
+  --ec-dropdown-text: 203 213 225; /* #cbd5e1 */
+  --ec-dropdown-hover: 30 41 59; /* #1e293b */
+  --ec-dropdown-border: 51 65 85; /* #334155 */
+
+  /* Icons */
+  --ec-icon-color: 148 163 184; /* #94a3b8 */
+  --ec-icon-hover: 94 234 212; /* #5eead4 teal-300 */
+
+  /* Sidebar / Vertical Nav - same as page bg for unified look */
+  --ec-sidebar-bg: 2 6 23; /* #020617 slate-950 */
+  --ec-sidebar-bg-gradient: 2 6 23; /* #020617 - same as bg for unified look */
+  --ec-sidebar-border: 30 41 59; /* #1e293b */
+  --ec-sidebar-text: 148 163 184; /* #94a3b8 */
+  --ec-sidebar-active-bg: 20 184 166; /* #14b8a6 teal-500 */
+  --ec-sidebar-active-text: 2 6 23; /* #020617 */
+  --ec-sidebar-hover-bg: 30 41 59; /* #1e293b */
+
+  /* Rail / inset-panel surface (5% lifted from the sidebar bg) */
+  --ec-rail-bg: 7 11 28; /* ~2% lighter than #020617 */
+  --ec-rail-active-bg: 33 37 54; /* ~10% lifted off rail bg */
+
+  /* Nested sidebar content - same as page bg */
+  --ec-content-bg: 2 6 23; /* #020617 */
+  --ec-content-text: 226 232 240; /* #e2e8f0 */
+  --ec-content-text-muted: 148 163 184; /* #94a3b8 */
+  --ec-content-text-secondary: 148 163 184; /* #94a3b8 */
+  --ec-content-border: 30 41 59; /* #1e293b */
+  --ec-content-hover: 15 23 42; /* #0f172a */
+  --ec-content-active: 30 41 59; /* #1e293b */
+
+  /* Input fields */
+  --ec-input-bg: 15 23 42; /* #0f172a */
+  --ec-input-border: 51 65 85; /* #334155 */
+  --ec-input-text: 226 232 240; /* #e2e8f0 */
+  --ec-input-placeholder: 100 116 139; /* #64748b */
+
+  /* Group headers */
+  --ec-group-icon-bg: 30 41 59; /* #1e293b */
+  --ec-group-icon-text: 94 234 212; /* #5eead4 teal-300 */
+
+  /* Main content/docs area - base unified color */
+  --ec-page-bg: 2 6 23; /* #020617 */
+  --ec-page-text: 226 232 240; /* #e2e8f0 */
+  --ec-page-text-muted: 148 163 184; /* #94a3b8 */
+  --ec-page-border: 30 41 59; /* #1e293b */
+
+  /* Card/elevated surfaces - same as page for unified look */
+  --ec-card-bg: 2 6 23; /* #020617 */
+
+  /* Code blocks - slightly elevated for contrast */
+  --ec-code-bg: 15 23 42; /* #0f172a */
+
+  /* Badge colors - ocean dark */
+  --ec-badge-domain-bg: 113 63 18 / 0.3; /* yellow-900/30 */
+  --ec-badge-domain-text: 253 224 71; /* yellow-300 */
+  --ec-badge-service-bg: 131 24 67 / 0.3; /* pink-900/30 */
+  --ec-badge-service-text: 249 168 212; /* pink-300 */
+  --ec-badge-event-bg: 120 53 15 / 0.3; /* amber-900/30 */
+  --ec-badge-event-text: 252 211 77; /* amber-300 */
+  --ec-badge-command-bg: 17 94 89 / 0.3; /* teal-800/30 */
+  --ec-badge-command-text: 94 234 212; /* teal-300 */
+  --ec-badge-query-bg: 21 94 117 / 0.3; /* cyan-800/30 */
+  --ec-badge-query-text: 103 232 249; /* cyan-300 */
+  --ec-badge-message-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-message-text: 165 180 252; /* indigo-300 */
+  --ec-badge-design-bg: 17 94 89 / 0.3; /* teal-800/30 */
+  --ec-badge-design-text: 94 234 212; /* teal-300 */
+  --ec-badge-channel-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-channel-text: 165 180 252; /* indigo-300 */
+  --ec-badge-container-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-container-text: 165 180 252; /* indigo-300 */
+  --ec-badge-data-product-bg: 30 64 175 / 0.3; /* blue-800/30 */
+  --ec-badge-data-product-text: 147 197 253; /* blue-300 */
+  --ec-badge-default-bg: 51 65 85 / 0.3; /* slate-700/30 */
+  --ec-badge-default-text: 203 213 225; /* slate-300 */
+}
+
+/* Ocean theme prose overrides */
+:root[data-catalog-theme="ocean"][data-theme="dark"] .prose {
+  --tw-prose-body: rgb(148 163 184); /* slate-400 */
+  --tw-prose-headings: rgb(226 232 240); /* slate-200 */
+  --tw-prose-lead: rgb(100 116 139); /* slate-500 */
+  --tw-prose-links: rgb(45 212 191); /* teal-400 */
+  --tw-prose-bold: rgb(226 232 240); /* slate-200 */
+  --tw-prose-counters: rgb(100 116 139); /* slate-500 */
+  --tw-prose-bullets: rgb(71 85 105); /* slate-600 */
+  --tw-prose-hr: rgb(30 41 59); /* slate-800 */
+  --tw-prose-quotes: rgb(226 232 240); /* slate-200 */
+  --tw-prose-quote-borders: rgb(51 65 85); /* slate-700 */
+  --tw-prose-captions: rgb(100 116 139); /* slate-500 */
+  --tw-prose-code: rgb(226 232 240); /* slate-200 */
+  --tw-prose-pre-code: rgb(148 163 184); /* slate-400 */
+  --tw-prose-pre-bg: rgb(15 23 42); /* slate-900 */
+  --tw-prose-th-borders: rgb(51 65 85); /* slate-700 */
+  --tw-prose-td-borders: rgb(30 41 59); /* slate-800 */
+}
+
+:root[data-catalog-theme="ocean"][data-theme="dark"] .prose code {
+  background-color: rgb(30 41 59); /* slate-800 */
+}
+
+:root[data-catalog-theme="ocean"][data-theme="dark"] .prose pre {
+  background-color: rgb(15 23 42); /* slate-900 */
+  border: 1px solid rgb(30 41 59); /* slate-800 */
+}
+
+:root[data-catalog-theme="ocean"][data-theme="dark"] .prose a {
+  color: rgb(45 212 191); /* teal-400 */
+}
+
+:root[data-catalog-theme="ocean"][data-theme="dark"] .prose a:hover {
+  color: rgb(94 234 212); /* teal-300 */
+}
diff --git a/packages/core/eventcatalog/src/styles/themes/sapphire.css b/packages/core/eventcatalog/src/styles/themes/sapphire.css
new file mode 100644
index 000000000..9ecd29407
--- /dev/null
+++ b/packages/core/eventcatalog/src/styles/themes/sapphire.css
@@ -0,0 +1,246 @@
+/**
+ * Sapphire Theme for EventCatalog
+ *
+ * A professional, premium theme inspired by sapphire gemstones.
+ * Deep blues with elegant accents for enterprise environments.
+ */
+
+/* Sapphire Light Mode */
+:root[data-catalog-theme="sapphire"],
+:root[data-catalog-theme="sapphire"][data-theme="light"] {
+  /* Header - clean white with subtle blue tint */
+  --ec-header-bg: 255 255 255; /* #ffffff */
+  --ec-header-text: 15 23 42; /* #0f172a */
+  --ec-header-border: 226 232 240; /* #e2e8f0 slate-200 */
+
+  /* Primary brand color - sapphire blue */
+  --ec-primary: 59 130 246; /* #3b82f6 blue-500 */
+  --ec-primary-hover: 37 99 235; /* #2563eb blue-600 */
+
+  /* Accent colors - sapphire blue */
+  --ec-accent: 59 130 246; /* #3b82f6 (blue-500) */
+  --ec-accent-hover: 37 99 235; /* #2563eb (blue-600) */
+  --ec-accent-subtle: 219 234 254; /* #dbeafe (blue-100) */
+  --ec-accent-text: 30 64 175; /* #1e40af (blue-800) */
+  --ec-accent-gradient-from: 59 130 246; /* #3b82f6 (blue-500) */
+  --ec-accent-gradient-to: 37 99 235; /* #2563eb (blue-600) */
+
+  /* Buttons */
+  --ec-button-bg: 37 99 235; /* #2563eb blue-600 */
+  --ec-button-bg-hover: 29 78 216; /* #1d4ed8 blue-700 */
+  --ec-button-text: 255 255 255; /* #ffffff */
+
+  /* Dropdowns & menus */
+  --ec-dropdown-bg: 255 255 255; /* #ffffff */
+  --ec-dropdown-text: 51 65 85; /* #334155 */
+  --ec-dropdown-hover: 239 246 255; /* #eff6ff blue-50 */
+  --ec-dropdown-border: 226 232 240; /* #e2e8f0 slate-200 */
+
+  /* Icons */
+  --ec-icon-color: 71 85 105; /* #475569 slate-600 */
+  --ec-icon-hover: 37 99 235; /* #2563eb blue-600 */
+
+  /* Sidebar / Vertical Nav */
+  --ec-sidebar-bg: 255 255 255; /* #ffffff */
+  --ec-sidebar-bg-gradient: 239 246 255; /* #eff6ff blue-50 */
+  --ec-sidebar-border: 226 232 240; /* #e2e8f0 slate-200 */
+  --ec-sidebar-text: 71 85 105; /* #475569 slate-600 */
+  --ec-sidebar-active-bg: 37 99 235; /* #2563eb blue-600 */
+  --ec-sidebar-active-text: 255 255 255; /* #ffffff */
+  --ec-sidebar-hover-bg: 37 99 235; /* #2563eb blue-600 */
+
+  /* Rail / inset-panel surface (5% off the sidebar bg) */
+  --ec-rail-bg: 250 250 250; /* #fafafa - 2% darker than white */
+  --ec-rail-active-bg: 218 218 218; /* ~10% darker than rail bg */
+
+  /* Nested sidebar content */
+  --ec-content-bg: 255 255 255; /* #ffffff */
+  --ec-content-text: 15 23 42; /* #0f172a */
+  --ec-content-text-muted: 71 85 105; /* #475569 slate-600 */
+  --ec-content-text-secondary: 100 116 139; /* #64748b slate-500 */
+  --ec-content-border: 226 232 240; /* #e2e8f0 slate-200 */
+  --ec-content-hover: 248 250 252; /* #f8fafc slate-50 */
+  --ec-content-active: 219 234 254; /* #dbeafe blue-100 */
+
+  /* Input fields */
+  --ec-input-bg: 255 255 255; /* #ffffff */
+  --ec-input-border: 203 213 225; /* #cbd5e1 slate-300 */
+  --ec-input-text: 15 23 42; /* #0f172a */
+  --ec-input-placeholder: 148 163 184; /* #94a3b8 */
+
+  /* Group headers */
+  --ec-group-icon-bg: 219 234 254; /* #dbeafe blue-100 */
+  --ec-group-icon-text: 30 64 175; /* #1e40af blue-800 */
+
+  /* Main content/docs area */
+  --ec-page-bg: 255 255 255; /* #ffffff */
+  --ec-page-text: 15 23 42; /* #0f172a */
+  --ec-page-text-muted: 71 85 105; /* #475569 slate-600 */
+  --ec-page-border: 226 232 240; /* #e2e8f0 slate-200 */
+
+  /* Card/elevated surfaces */
+  --ec-card-bg: 255 255 255; /* #ffffff */
+
+  /* Code blocks */
+  --ec-code-bg: 250 250 250; /* #fafafa */
+
+  /* Badge colors - sapphire theme */
+  --ec-badge-domain-bg: 254 249 195; /* yellow-100 */
+  --ec-badge-domain-text: 161 98 7; /* yellow-700 */
+  --ec-badge-service-bg: 252 231 243; /* pink-100 */
+  --ec-badge-service-text: 190 24 93; /* pink-700 */
+  --ec-badge-event-bg: 254 243 199; /* amber-100 */
+  --ec-badge-event-text: 180 83 9; /* amber-700 */
+  --ec-badge-command-bg: 219 234 254; /* blue-100 */
+  --ec-badge-command-text: 30 64 175; /* blue-800 */
+  --ec-badge-query-bg: 207 250 254; /* cyan-100 */
+  --ec-badge-query-text: 21 94 117; /* cyan-800 */
+  --ec-badge-message-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-message-text: 67 56 202; /* indigo-700 */
+  --ec-badge-design-bg: 219 234 254; /* blue-100 */
+  --ec-badge-design-text: 37 99 235; /* blue-600 */
+  --ec-badge-channel-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-channel-text: 67 56 202; /* indigo-700 */
+  --ec-badge-container-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-container-text: 67 56 202; /* indigo-700 */
+  --ec-badge-data-product-bg: 219 234 254; /* blue-100 */
+  --ec-badge-data-product-text: 30 64 175; /* blue-800 */
+  --ec-badge-default-bg: 239 246 255; /* blue-50 */
+  --ec-badge-default-text: 71 85 105; /* slate-600 */
+}
+
+/* Sapphire Dark Mode */
+:root[data-catalog-theme="sapphire"][data-theme="dark"] {
+  /* Header - matches page bg for unified look */
+  --ec-header-bg: 2 6 23; /* #020617 slate-950 - matches page bg */
+  --ec-header-text: 226 232 240; /* #e2e8f0 */
+  --ec-header-border: 30 41 59; /* #1e293b slate-800 */
+
+  /* Accent colors - sapphire blue for dark */
+  --ec-accent: 96 165 250; /* #60a5fa (blue-400) */
+  --ec-accent-hover: 59 130 246; /* #3b82f6 (blue-500) */
+  --ec-accent-subtle: 30 64 175 / 0.3; /* blue-800/30 */
+  --ec-accent-text: 147 197 253; /* #93c5fd (blue-300) */
+  --ec-accent-gradient-from: 96 165 250; /* #60a5fa (blue-400) */
+  --ec-accent-gradient-to: 59 130 246; /* #3b82f6 (blue-500) */
+
+  /* Buttons */
+  --ec-button-bg: 59 130 246; /* #3b82f6 blue-500 */
+  --ec-button-bg-hover: 96 165 250; /* #60a5fa blue-400 */
+  --ec-button-text: 255 255 255; /* #ffffff */
+
+  /* Dropdowns & menus */
+  --ec-dropdown-bg: 15 23 42; /* #0f172a */
+  --ec-dropdown-text: 203 213 225; /* #cbd5e1 */
+  --ec-dropdown-hover: 30 41 59; /* #1e293b */
+  --ec-dropdown-border: 51 65 85; /* #334155 */
+
+  /* Icons */
+  --ec-icon-color: 148 163 184; /* #94a3b8 */
+  --ec-icon-hover: 147 197 253; /* #93c5fd blue-300 */
+
+  /* Sidebar / Vertical Nav */
+  --ec-sidebar-bg: 2 6 23; /* #020617 slate-950 */
+  --ec-sidebar-bg-gradient: 2 6 23; /* #020617 */
+  --ec-sidebar-border: 30 41 59; /* #1e293b */
+  --ec-sidebar-text: 148 163 184; /* #94a3b8 */
+  --ec-sidebar-active-bg: 59 130 246; /* #3b82f6 blue-500 */
+  --ec-sidebar-active-text: 255 255 255; /* #ffffff */
+  --ec-sidebar-hover-bg: 30 41 59; /* #1e293b */
+
+  /* Rail / inset-panel surface (5% lifted from the sidebar bg) */
+  --ec-rail-bg: 7 11 28; /* ~2% lighter than #020617 */
+  --ec-rail-active-bg: 33 37 54; /* ~10% lifted off rail bg */
+
+  /* Nested sidebar content */
+  --ec-content-bg: 2 6 23; /* #020617 */
+  --ec-content-text: 226 232 240; /* #e2e8f0 */
+  --ec-content-text-muted: 148 163 184; /* #94a3b8 */
+  --ec-content-text-secondary: 148 163 184; /* #94a3b8 */
+  --ec-content-border: 30 41 59; /* #1e293b */
+  --ec-content-hover: 15 23 42; /* #0f172a */
+  --ec-content-active: 30 41 59; /* #1e293b */
+
+  /* Input fields */
+  --ec-input-bg: 15 23 42; /* #0f172a */
+  --ec-input-border: 51 65 85; /* #334155 */
+  --ec-input-text: 226 232 240; /* #e2e8f0 */
+  --ec-input-placeholder: 100 116 139; /* #64748b */
+
+  /* Group headers */
+  --ec-group-icon-bg: 30 41 59; /* #1e293b */
+  --ec-group-icon-text: 147 197 253; /* #93c5fd blue-300 */
+
+  /* Main content/docs area */
+  --ec-page-bg: 2 6 23; /* #020617 */
+  --ec-page-text: 226 232 240; /* #e2e8f0 */
+  --ec-page-text-muted: 148 163 184; /* #94a3b8 */
+  --ec-page-border: 30 41 59; /* #1e293b */
+
+  /* Card/elevated surfaces */
+  --ec-card-bg: 2 6 23; /* #020617 */
+
+  /* Code blocks */
+  --ec-code-bg: 15 23 42; /* #0f172a */
+
+  /* Badge colors - sapphire dark */
+  --ec-badge-domain-bg: 113 63 18 / 0.3; /* yellow-900/30 */
+  --ec-badge-domain-text: 253 224 71; /* yellow-300 */
+  --ec-badge-service-bg: 131 24 67 / 0.3; /* pink-900/30 */
+  --ec-badge-service-text: 249 168 212; /* pink-300 */
+  --ec-badge-event-bg: 120 53 15 / 0.3; /* amber-900/30 */
+  --ec-badge-event-text: 252 211 77; /* amber-300 */
+  --ec-badge-command-bg: 30 64 175 / 0.3; /* blue-800/30 */
+  --ec-badge-command-text: 147 197 253; /* blue-300 */
+  --ec-badge-query-bg: 21 94 117 / 0.3; /* cyan-800/30 */
+  --ec-badge-query-text: 103 232 249; /* cyan-300 */
+  --ec-badge-message-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-message-text: 165 180 252; /* indigo-300 */
+  --ec-badge-design-bg: 30 64 175 / 0.3; /* blue-800/30 */
+  --ec-badge-design-text: 147 197 253; /* blue-300 */
+  --ec-badge-channel-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-channel-text: 165 180 252; /* indigo-300 */
+  --ec-badge-container-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-container-text: 165 180 252; /* indigo-300 */
+  --ec-badge-data-product-bg: 30 64 175 / 0.3; /* blue-800/30 */
+  --ec-badge-data-product-text: 147 197 253; /* blue-300 */
+  --ec-badge-default-bg: 51 65 85 / 0.3; /* slate-700/30 */
+  --ec-badge-default-text: 203 213 225; /* slate-300 */
+}
+
+/* Sapphire theme prose overrides */
+:root[data-catalog-theme="sapphire"][data-theme="dark"] .prose {
+  --tw-prose-body: rgb(148 163 184); /* slate-400 */
+  --tw-prose-headings: rgb(226 232 240); /* slate-200 */
+  --tw-prose-lead: rgb(100 116 139); /* slate-500 */
+  --tw-prose-links: rgb(96 165 250); /* blue-400 */
+  --tw-prose-bold: rgb(226 232 240); /* slate-200 */
+  --tw-prose-counters: rgb(100 116 139); /* slate-500 */
+  --tw-prose-bullets: rgb(71 85 105); /* slate-600 */
+  --tw-prose-hr: rgb(30 41 59); /* slate-800 */
+  --tw-prose-quotes: rgb(226 232 240); /* slate-200 */
+  --tw-prose-quote-borders: rgb(51 65 85); /* slate-700 */
+  --tw-prose-captions: rgb(100 116 139); /* slate-500 */
+  --tw-prose-code: rgb(226 232 240); /* slate-200 */
+  --tw-prose-pre-code: rgb(148 163 184); /* slate-400 */
+  --tw-prose-pre-bg: rgb(15 23 42); /* slate-900 */
+  --tw-prose-th-borders: rgb(51 65 85); /* slate-700 */
+  --tw-prose-td-borders: rgb(30 41 59); /* slate-800 */
+}
+
+:root[data-catalog-theme="sapphire"][data-theme="dark"] .prose code {
+  background-color: rgb(30 41 59); /* slate-800 */
+}
+
+:root[data-catalog-theme="sapphire"][data-theme="dark"] .prose pre {
+  background-color: rgb(15 23 42); /* slate-900 */
+  border: 1px solid rgb(30 41 59); /* slate-800 */
+}
+
+:root[data-catalog-theme="sapphire"][data-theme="dark"] .prose a {
+  color: rgb(96 165 250); /* blue-400 */
+}
+
+:root[data-catalog-theme="sapphire"][data-theme="dark"] .prose a:hover {
+  color: rgb(147 197 253); /* blue-300 */
+}
diff --git a/packages/core/eventcatalog/src/styles/themes/sunset.css b/packages/core/eventcatalog/src/styles/themes/sunset.css
new file mode 100644
index 000000000..3298f40a9
--- /dev/null
+++ b/packages/core/eventcatalog/src/styles/themes/sunset.css
@@ -0,0 +1,246 @@
+/**
+ * Sunset Theme for EventCatalog
+ *
+ * A warm, inviting theme inspired by golden sunsets.
+ * Rich oranges and ambers with a cozy, energetic feel.
+ */
+
+/* Sunset Light Mode */
+:root[data-catalog-theme="sunset"],
+:root[data-catalog-theme="sunset"][data-theme="light"] {
+  /* Header - clean white */
+  --ec-header-bg: 255 255 255; /* #ffffff */
+  --ec-header-text: 23 23 23; /* #171717 neutral-900 */
+  --ec-header-border: 229 229 229; /* #e5e5e5 neutral-200 */
+
+  /* Primary brand color - sunset orange */
+  --ec-primary: 255 106 0; /* #ff6a00 vivid orange */
+  --ec-primary-hover: 232 93 0; /* #e85d00 deeper vivid orange */
+
+  /* Accent colors - sunset orange */
+  --ec-accent: 255 106 0; /* #ff6a00 vivid orange */
+  --ec-accent-hover: 232 93 0; /* #e85d00 deeper vivid orange */
+  --ec-accent-subtle: 255 232 209; /* #ffe8d1 (subtle vivid orange) */
+  --ec-accent-text: 122 46 16; /* #7a2e10 burnt orange */
+  --ec-accent-gradient-from: 255 106 0; /* #ff6a00 */
+  --ec-accent-gradient-to: 232 93 0; /* #e85d00 */
+
+  /* Buttons */
+  --ec-button-bg: 234 88 12; /* #ea580c orange-600 */
+  --ec-button-bg-hover: 194 65 12; /* #c2410c orange-700 */
+  --ec-button-text: 255 255 255; /* #ffffff */
+
+  /* Dropdowns & menus */
+  --ec-dropdown-bg: 255 255 255; /* #ffffff */
+  --ec-dropdown-text: 64 64 64; /* #404040 neutral-700 */
+  --ec-dropdown-hover: 255 247 237; /* #fff7ed orange-50 */
+  --ec-dropdown-border: 229 229 229; /* #e5e5e5 neutral-200 */
+
+  /* Icons */
+  --ec-icon-color: 82 82 82; /* #525252 neutral-600 */
+  --ec-icon-hover: 234 88 12; /* #ea580c orange-600 */
+
+  /* Sidebar / Vertical Nav */
+  --ec-sidebar-bg: 255 255 255; /* #ffffff */
+  --ec-sidebar-bg-gradient: 255 247 237; /* #fff7ed orange-50 */
+  --ec-sidebar-border: 229 229 229; /* #e5e5e5 neutral-200 */
+  --ec-sidebar-text: 82 82 82; /* #525252 neutral-600 */
+  --ec-sidebar-active-bg: 234 88 12; /* #ea580c orange-600 */
+  --ec-sidebar-active-text: 255 255 255; /* #ffffff */
+  --ec-sidebar-hover-bg: 234 88 12; /* #ea580c orange-600 */
+
+  /* Rail / inset-panel surface (5% off the sidebar bg) */
+  --ec-rail-bg: 250 250 250; /* #fafafa - 2% darker than white */
+  --ec-rail-active-bg: 218 218 218; /* ~10% darker than rail bg */
+
+  /* Nested sidebar content */
+  --ec-content-bg: 255 255 255; /* #ffffff */
+  --ec-content-text: 23 23 23; /* #171717 neutral-900 */
+  --ec-content-text-muted: 82 82 82; /* #525252 neutral-600 */
+  --ec-content-text-secondary: 115 115 115; /* #737373 neutral-500 */
+  --ec-content-border: 229 229 229; /* #e5e5e5 neutral-200 */
+  --ec-content-hover: 250 250 250; /* #fafafa neutral-50 */
+  --ec-content-active: 255 237 213; /* #ffedd5 orange-100 */
+
+  /* Input fields */
+  --ec-input-bg: 255 255 255; /* #ffffff */
+  --ec-input-border: 212 212 212; /* #d4d4d4 neutral-300 */
+  --ec-input-text: 23 23 23; /* #171717 neutral-900 */
+  --ec-input-placeholder: 163 163 163; /* #a3a3a3 neutral-400 */
+
+  /* Group headers */
+  --ec-group-icon-bg: 255 237 213; /* #ffedd5 orange-100 */
+  --ec-group-icon-text: 154 52 18; /* #9a3412 orange-800 */
+
+  /* Main content/docs area */
+  --ec-page-bg: 255 255 255; /* #ffffff */
+  --ec-page-text: 23 23 23; /* #171717 neutral-900 */
+  --ec-page-text-muted: 82 82 82; /* #525252 neutral-600 */
+  --ec-page-border: 229 229 229; /* #e5e5e5 neutral-200 */
+
+  /* Card/elevated surfaces */
+  --ec-card-bg: 255 255 255; /* #ffffff */
+
+  /* Code blocks */
+  --ec-code-bg: 250 250 250; /* #fafafa */
+
+  /* Badge colors - sunset theme */
+  --ec-badge-domain-bg: 254 249 195; /* yellow-100 */
+  --ec-badge-domain-text: 161 98 7; /* yellow-700 */
+  --ec-badge-service-bg: 252 231 243; /* pink-100 */
+  --ec-badge-service-text: 190 24 93; /* pink-700 */
+  --ec-badge-event-bg: 255 237 213; /* orange-100 */
+  --ec-badge-event-text: 154 52 18; /* orange-800 */
+  --ec-badge-command-bg: 219 234 254; /* blue-100 */
+  --ec-badge-command-text: 30 64 175; /* blue-800 */
+  --ec-badge-query-bg: 207 250 254; /* cyan-100 */
+  --ec-badge-query-text: 21 94 117; /* cyan-800 */
+  --ec-badge-message-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-message-text: 67 56 202; /* indigo-700 */
+  --ec-badge-design-bg: 255 237 213; /* orange-100 */
+  --ec-badge-design-text: 234 88 12; /* orange-600 */
+  --ec-badge-channel-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-channel-text: 67 56 202; /* indigo-700 */
+  --ec-badge-container-bg: 224 231 255; /* indigo-100 */
+  --ec-badge-container-text: 67 56 202; /* indigo-700 */
+  --ec-badge-data-product-bg: 219 234 254; /* blue-100 */
+  --ec-badge-data-product-text: 30 64 175; /* blue-800 */
+  --ec-badge-default-bg: 255 247 237; /* orange-50 */
+  --ec-badge-default-text: 82 82 82; /* neutral-600 */
+}
+
+/* Sunset Dark Mode */
+:root[data-catalog-theme="sunset"][data-theme="dark"] {
+  /* Header - matches page bg for unified look */
+  --ec-header-bg: 10 10 10; /* #0a0a0a neutral-950 - matches page bg */
+  --ec-header-text: 245 245 245; /* #f5f5f5 neutral-100 */
+  --ec-header-border: 38 38 38; /* #262626 neutral-800 */
+
+  /* Accent colors - sunset orange for dark */
+  --ec-accent: 255 138 61; /* #ff8a3d punchier vivid orange */
+  --ec-accent-hover: 255 106 0; /* #ff6a00 vivid orange */
+  --ec-accent-subtle: 122 46 16 / 0.3; /* burnt orange/30 */
+  --ec-accent-text: 255 119 51; /* #ff7733 deep vivid orange */
+  --ec-accent-gradient-from: 255 138 61; /* #ff8a3d */
+  --ec-accent-gradient-to: 255 106 0; /* #ff6a00 */
+
+  /* Buttons */
+  --ec-button-bg: 249 115 22; /* #f97316 orange-500 */
+  --ec-button-bg-hover: 251 146 60; /* #fb923c orange-400 */
+  --ec-button-text: 255 255 255; /* #ffffff */
+
+  /* Dropdowns & menus */
+  --ec-dropdown-bg: 23 23 23; /* #171717 */
+  --ec-dropdown-text: 212 212 212; /* #d4d4d4 */
+  --ec-dropdown-hover: 38 38 38; /* #262626 */
+  --ec-dropdown-border: 64 64 64; /* #404040 */
+
+  /* Icons */
+  --ec-icon-color: 163 163 163; /* #a3a3a3 */
+  --ec-icon-hover: 253 186 116; /* #fdba74 orange-300 */
+
+  /* Sidebar / Vertical Nav */
+  --ec-sidebar-bg: 10 10 10; /* #0a0a0a neutral-950 */
+  --ec-sidebar-bg-gradient: 10 10 10; /* #0a0a0a */
+  --ec-sidebar-border: 38 38 38; /* #262626 */
+  --ec-sidebar-text: 163 163 163; /* #a3a3a3 */
+  --ec-sidebar-active-bg: 249 115 22; /* #f97316 orange-500 */
+  --ec-sidebar-active-text: 255 255 255; /* #ffffff */
+  --ec-sidebar-hover-bg: 38 38 38; /* #262626 */
+
+  /* Rail / inset-panel surface (5% lifted from the sidebar bg) */
+  --ec-rail-bg: 15 15 15; /* ~2% lighter than #0a0a0a */
+  --ec-rail-active-bg: 41 41 41; /* ~10% lifted off rail bg */
+
+  /* Nested sidebar content */
+  --ec-content-bg: 10 10 10; /* #0a0a0a */
+  --ec-content-text: 245 245 245; /* #f5f5f5 */
+  --ec-content-text-muted: 163 163 163; /* #a3a3a3 */
+  --ec-content-text-secondary: 163 163 163; /* #a3a3a3 */
+  --ec-content-border: 38 38 38; /* #262626 */
+  --ec-content-hover: 23 23 23; /* #171717 */
+  --ec-content-active: 38 38 38; /* #262626 */
+
+  /* Input fields */
+  --ec-input-bg: 23 23 23; /* #171717 */
+  --ec-input-border: 64 64 64; /* #404040 */
+  --ec-input-text: 245 245 245; /* #f5f5f5 */
+  --ec-input-placeholder: 115 115 115; /* #737373 */
+
+  /* Group headers */
+  --ec-group-icon-bg: 38 38 38; /* #262626 */
+  --ec-group-icon-text: 255 119 51; /* #ff7733 deep vivid orange */
+
+  /* Main content/docs area */
+  --ec-page-bg: 10 10 10; /* #0a0a0a */
+  --ec-page-text: 245 245 245; /* #f5f5f5 */
+  --ec-page-text-muted: 163 163 163; /* #a3a3a3 */
+  --ec-page-border: 38 38 38; /* #262626 */
+
+  /* Card/elevated surfaces */
+  --ec-card-bg: 10 10 10; /* #0a0a0a */
+
+  /* Code blocks */
+  --ec-code-bg: 23 23 23; /* #171717 */
+
+  /* Badge colors - sunset dark */
+  --ec-badge-domain-bg: 113 63 18 / 0.3; /* yellow-900/30 */
+  --ec-badge-domain-text: 253 224 71; /* yellow-300 */
+  --ec-badge-service-bg: 131 24 67 / 0.3; /* pink-900/30 */
+  --ec-badge-service-text: 249 168 212; /* pink-300 */
+  --ec-badge-event-bg: 124 45 18 / 0.3; /* orange-900/30 */
+  --ec-badge-event-text: 253 186 116; /* orange-300 */
+  --ec-badge-command-bg: 30 64 175 / 0.3; /* blue-800/30 */
+  --ec-badge-command-text: 147 197 253; /* blue-300 */
+  --ec-badge-query-bg: 21 94 117 / 0.3; /* cyan-800/30 */
+  --ec-badge-query-text: 103 232 249; /* cyan-300 */
+  --ec-badge-message-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-message-text: 165 180 252; /* indigo-300 */
+  --ec-badge-design-bg: 124 45 18 / 0.3; /* orange-900/30 */
+  --ec-badge-design-text: 253 186 116; /* orange-300 */
+  --ec-badge-channel-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-channel-text: 165 180 252; /* indigo-300 */
+  --ec-badge-container-bg: 49 46 129 / 0.3; /* indigo-900/30 */
+  --ec-badge-container-text: 165 180 252; /* indigo-300 */
+  --ec-badge-data-product-bg: 30 64 175 / 0.3; /* blue-800/30 */
+  --ec-badge-data-product-text: 147 197 253; /* blue-300 */
+  --ec-badge-default-bg: 64 64 64 / 0.3; /* neutral-700/30 */
+  --ec-badge-default-text: 212 212 212; /* neutral-300 */
+}
+
+/* Sunset theme prose overrides */
+:root[data-catalog-theme="sunset"][data-theme="dark"] .prose {
+  --tw-prose-body: rgb(163 163 163); /* neutral-400 */
+  --tw-prose-headings: rgb(245 245 245); /* neutral-100 */
+  --tw-prose-lead: rgb(115 115 115); /* neutral-500 */
+  --tw-prose-links: rgb(251 146 60); /* orange-400 */
+  --tw-prose-bold: rgb(245 245 245); /* neutral-100 */
+  --tw-prose-counters: rgb(115 115 115); /* neutral-500 */
+  --tw-prose-bullets: rgb(82 82 82); /* neutral-600 */
+  --tw-prose-hr: rgb(38 38 38); /* neutral-800 */
+  --tw-prose-quotes: rgb(245 245 245); /* neutral-100 */
+  --tw-prose-quote-borders: rgb(64 64 64); /* neutral-700 */
+  --tw-prose-captions: rgb(115 115 115); /* neutral-500 */
+  --tw-prose-code: rgb(245 245 245); /* neutral-100 */
+  --tw-prose-pre-code: rgb(163 163 163); /* neutral-400 */
+  --tw-prose-pre-bg: rgb(23 23 23); /* neutral-900 */
+  --tw-prose-th-borders: rgb(64 64 64); /* neutral-700 */
+  --tw-prose-td-borders: rgb(38 38 38); /* neutral-800 */
+}
+
+:root[data-catalog-theme="sunset"][data-theme="dark"] .prose code {
+  background-color: rgb(38 38 38); /* neutral-800 */
+}
+
+:root[data-catalog-theme="sunset"][data-theme="dark"] .prose pre {
+  background-color: rgb(23 23 23); /* neutral-900 */
+  border: 1px solid rgb(38 38 38); /* neutral-800 */
+}
+
+:root[data-catalog-theme="sunset"][data-theme="dark"] .prose a {
+  color: rgb(251 146 60); /* orange-400 */
+}
+
+:root[data-catalog-theme="sunset"][data-theme="dark"] .prose a:hover {
+  color: rgb(253 186 116); /* orange-300 */
+}
diff --git a/packages/core/eventcatalog/src/toolkit/layouts/Layout.astro b/packages/core/eventcatalog/src/toolkit/layouts/Layout.astro
new file mode 100644
index 000000000..956d7dece
--- /dev/null
+++ b/packages/core/eventcatalog/src/toolkit/layouts/Layout.astro
@@ -0,0 +1,31 @@
+---
+/**
+ * Public layout shell for user-defined custom pages, imported by catalog
+ * authors as `@catalog/layouts/Layout.astro`.
+ *
+ * The props here are a documented, stable interface — internal layouts can
+ * change freely, this contract cannot.
+ */
+interface Props {
+  title: string;
+  description?: string;
+  /** Render the resource sidebar (domains, services, messages). Defaults to true. */
+  sidebar?: boolean;
+  /** Show the EventCatalog header (search, navigation). Defaults to true. */
+  showHeader?: boolean;
+}
+
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+
+const { title, description, sidebar = true, showHeader = true } = Astro.props;
+---
+
+<VerticalSideBarLayout
+  title={title}
+  description={description}
+  showHeader={showHeader}
+  showNestedSideBar={sidebar}
+  wrapContent={false}
+>
+  <slot />
+</VerticalSideBarLayout>
diff --git a/packages/core/eventcatalog/src/toolkit/utils/index.ts b/packages/core/eventcatalog/src/toolkit/utils/index.ts
new file mode 100644
index 000000000..f250c575e
--- /dev/null
+++ b/packages/core/eventcatalog/src/toolkit/utils/index.ts
@@ -0,0 +1,26 @@
+/**
+ * Public utilities for user-defined custom pages, imported by catalog
+ * authors as `@catalog/utils`.
+ *
+ * These re-exports are a documented, stable interface — internal utils can
+ * change freely, this contract cannot. Getters return hydrated, cached
+ * collection entries (pass { getAllVersions: false } for latest versions only).
+ */
+export { getDomains } from '@utils/collections/domains';
+export { getServices } from '@utils/collections/services';
+export { getSystems } from '@utils/collections/systems';
+export { getEvents } from '@utils/collections/events';
+export { getCommands } from '@utils/collections/commands';
+export { getQueries } from '@utils/collections/queries';
+export { getFlows } from '@utils/collections/flows';
+export { getChannels } from '@utils/collections/channels';
+export { getEntities } from '@utils/collections/entities';
+export { getAgents } from '@utils/collections/agents';
+export { getContainers } from '@utils/collections/containers';
+export { getDataProducts } from '@utils/collections/data-products';
+export { getAdrs } from '@utils/collections/adrs';
+export { getTeams } from '@utils/collections/teams';
+export { getUsers } from '@utils/collections/users';
+
+// Resolve a specific version (semver) or the latest version of items in a collection
+export { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
diff --git a/packages/core/eventcatalog/src/types/index.ts b/packages/core/eventcatalog/src/types/index.ts
new file mode 100644
index 000000000..233c2b7d6
--- /dev/null
+++ b/packages/core/eventcatalog/src/types/index.ts
@@ -0,0 +1,41 @@
+export type CollectionTypes =
+  | 'agents'
+  | 'adrs'
+  | 'commands'
+  | 'events'
+  | 'queries'
+  | 'domains'
+  | 'systems'
+  | 'services'
+  | 'flows'
+  | 'channels'
+  | 'entities'
+  | 'containers'
+  | 'diagrams'
+  | 'data-products';
+export type CollectionMessageTypes = 'commands' | 'events' | 'queries';
+export type CollectionUserTypes = 'users' | 'teams';
+export type PageTypes =
+  | 'agents'
+  | 'adrs'
+  | 'events'
+  | 'commands'
+  | 'queries'
+  | 'services'
+  | 'domains'
+  | 'systems'
+  | 'channels'
+  | 'flows'
+  | 'entities'
+  | 'containers'
+  | 'diagrams'
+  | 'data-products';
+
+export type TableConfiguration = {
+  columns: {
+    [key: string]: {
+      label?: string;
+      visible?: boolean;
+    };
+  };
+};
diff --git a/packages/core/eventcatalog/src/types/mcp-modules.d.ts b/packages/core/eventcatalog/src/types/mcp-modules.d.ts
new file mode 100644
index 000000000..5d91dc629
--- /dev/null
+++ b/packages/core/eventcatalog/src/types/mcp-modules.d.ts
@@ -0,0 +1,66 @@
+/**
+ * Type declarations for MCP server dependencies
+ * These are used by the enterprise MCP server feature
+ */
+
+declare module 'hono' {
+  export interface Context {
+    req: {
+      raw: Request;
+    };
+    json: (data: unknown, status?: number) => Response;
+  }
+
+  export class Hono {
+    constructor();
+    basePath(path: string): Hono;
+    get(path: string, handler: (c: Context) => Response | Promise<Response>): void;
+    post(path: string, handler: (c: Context) => Response | Promise<Response>): void;
+    fetch(request: Request): Promise<Response>;
+  }
+}
+
+declare module '@modelcontextprotocol/sdk/server/mcp.js' {
+  import { z } from 'zod';
+
+  export interface ToolConfig {
+    description: string;
+    inputSchema: z.ZodType<any>;
+  }
+
+  export interface ToolResult {
+    content: Array<{ type: 'text'; text: string }>;
+    isError?: boolean;
+  }
+
+  export interface ResourceConfig {
+    description: string;
+    mimeType: string;
+  }
+
+  export interface ResourceResult {
+    contents: Array<{
+      uri: string;
+      text: string;
+      mimeType: string;
+    }>;
+  }
+
+  export class McpServer {
+    constructor(config: { name: string; version: string });
+    registerTool(name: string, config: ToolConfig, handler: (params: any) => Promise<ToolResult>): void;
+    registerResource(name: string, uri: string, config: ResourceConfig, handler: (uri: URL) => Promise<ResourceResult>): void;
+    connect(transport: any): Promise<void>;
+  }
+}
+
+declare module '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js' {
+  export interface WebStandardStreamableHTTPServerTransportConfig {
+    sessionIdGenerator: undefined;
+  }
+
+  export class WebStandardStreamableHTTPServerTransport {
+    constructor(config: WebStandardStreamableHTTPServerTransportConfig);
+    handleRequest(request: Request): Promise<Response>;
+  }
+}
diff --git a/packages/core/eventcatalog/src/types/picomatch.d.ts b/packages/core/eventcatalog/src/types/picomatch.d.ts
new file mode 100644
index 000000000..a7bb9f393
--- /dev/null
+++ b/packages/core/eventcatalog/src/types/picomatch.d.ts
@@ -0,0 +1,13 @@
+declare module 'picomatch' {
+  export interface Options {
+    [key: string]: unknown;
+  }
+
+  interface Picomatch {
+    (globs: string | string[], options?: Options): (input: string) => boolean;
+    isMatch(input: string | string[], glob: string | string[], options?: Options): boolean;
+  }
+
+  const picomatch: Picomatch;
+  export default picomatch;
+}
diff --git a/packages/core/eventcatalog/src/types/react-syntax-highlighter.d.ts b/packages/core/eventcatalog/src/types/react-syntax-highlighter.d.ts
new file mode 100644
index 000000000..6a4d3d967
--- /dev/null
+++ b/packages/core/eventcatalog/src/types/react-syntax-highlighter.d.ts
@@ -0,0 +1,14 @@
+declare module 'react-syntax-highlighter' {
+  import type { ComponentType } from 'react';
+
+  export interface SyntaxHighlighterProps {
+    [key: string]: any;
+  }
+
+  export const Prism: ComponentType<SyntaxHighlighterProps>;
+  const SyntaxHighlighter: ComponentType<SyntaxHighlighterProps>;
+
+  export default SyntaxHighlighter;
+}
+
+declare module 'react-syntax-highlighter/dist/esm/styles/prism/material-light';
diff --git a/packages/core/eventcatalog/src/types/sql-js.d.ts b/packages/core/eventcatalog/src/types/sql-js.d.ts
new file mode 100644
index 000000000..406ba973c
--- /dev/null
+++ b/packages/core/eventcatalog/src/types/sql-js.d.ts
@@ -0,0 +1,24 @@
+declare module 'sql.js' {
+  export interface Database {
+    run(sql: string, params?: unknown[]): Database;
+    prepare(sql: string): {
+      bind(params?: unknown[]): boolean;
+      step(): boolean;
+      getAsObject(): Record<string, unknown>;
+      get(): unknown[];
+      free(): boolean;
+    };
+    exec(sql: string): Array<{ columns: string[]; values: unknown[][] }>;
+    export(): Uint8Array;
+    close(): void;
+  }
+
+  export interface SqlJsStatic {
+    Database: new (data?: Uint8Array) => Database;
+  }
+
+  export default function initSqlJs(config?: {
+    locateFile?: (file: string) => string;
+    wasmBinary?: ArrayBuffer;
+  }): Promise<SqlJsStatic>;
+}
diff --git a/packages/core/eventcatalog/src/utils/__tests__/agents/node-graph.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/agents/node-graph.spec.ts
new file mode 100644
index 000000000..7f8abaa7c
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/agents/node-graph.spec.ts
@@ -0,0 +1,128 @@
+import { getCollection } from 'astro:content';
+import type { CollectionKey } from 'astro:content';
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { getNodesAndEdges } from '../../node-graphs/agents-node-graph';
+import { mockAgents, mockChannels, mockCommands, mockContainers, mockEvents, mockQueries, mockServices } from '../services/mocks';
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: vi.fn(),
+  };
+});
+
+describe('Agents NodeGraph', () => {
+  beforeEach(() => {
+    vi.mocked(getCollection).mockImplementation(((key: CollectionKey) => {
+      switch (key) {
+        case 'agents':
+          return Promise.resolve(mockAgents);
+        case 'services':
+          return Promise.resolve(mockServices);
+        case 'channels':
+          return Promise.resolve(mockChannels);
+        case 'events':
+          return Promise.resolve(mockEvents);
+        case 'commands':
+          return Promise.resolve(mockCommands);
+        case 'queries':
+          return Promise.resolve(mockQueries);
+        case 'containers':
+          return Promise.resolve(mockContainers);
+        default:
+          return Promise.resolve([]);
+      }
+    }) as any);
+  });
+
+  it('returns nodes and edges for a given agent', async () => {
+    const { nodes, edges } = await getNodesAndEdges({ id: 'OrderSupportAgent', version: '1.0.0' });
+
+    expect(nodes).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: 'OrderSupportAgent-1.0.0',
+          type: 'agents',
+          data: expect.objectContaining({
+            mode: 'simple',
+            agent: expect.objectContaining({
+              id: 'OrderSupportAgent',
+              model: {
+                provider: 'OpenAI',
+                name: 'gpt-4.1-mini',
+                version: '2025-04-14',
+              },
+            }),
+          }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        }),
+        expect.objectContaining({
+          id: 'PaymentProcessed-0.0.1',
+          type: 'commands',
+          data: expect.objectContaining({ message: expect.objectContaining({ id: 'PaymentProcessed' }) }),
+        }),
+        expect.objectContaining({
+          id: 'OrderCreatedEvent-0.0.1',
+          type: 'events',
+          data: expect.objectContaining({ message: expect.objectContaining({ id: 'OrderCreatedEvent' }) }),
+        }),
+        expect.objectContaining({
+          id: 'OrderDatabase-1.0.0',
+          type: 'data',
+        }),
+        expect.objectContaining({
+          id: 'PaymentDatabase-1.0.0',
+          type: 'data',
+        }),
+        expect.objectContaining({
+          id: 'OrderSupportAgent-1.0.0-tool-order-history-lookup-mcp',
+          type: 'agentTool',
+          data: expect.objectContaining({
+            mode: 'simple',
+            agentTool: expect.objectContaining({
+              name: 'Order history lookup',
+              type: 'mcp',
+              icon: '/icons/tools/snowflake.svg',
+              url: 'https://mcp.example.com/orders/history',
+              description: 'Retrieves the customer order timeline for support investigations.',
+            }),
+          }),
+        }),
+      ])
+    );
+
+    expect(edges).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: 'PaymentProcessed-0.0.1-OrderSupportAgent-1.0.0-warning',
+          source: 'PaymentProcessed-0.0.1',
+          target: 'OrderSupportAgent-1.0.0',
+        }),
+        expect.objectContaining({
+          id: 'OrderSupportAgent-1.0.0-OrderCreatedEvent-0.0.1',
+          source: 'OrderSupportAgent-1.0.0',
+          target: 'OrderCreatedEvent-0.0.1',
+        }),
+        expect.objectContaining({
+          id: 'OrderSupportAgent-1.0.0-OrderDatabase-1.0.0',
+          source: 'OrderSupportAgent-1.0.0',
+          target: 'OrderDatabase-1.0.0',
+        }),
+        expect.objectContaining({
+          id: 'OrderSupportAgent-1.0.0-OrderSupportAgent-1.0.0-tool-order-history-lookup-mcp',
+          source: 'OrderSupportAgent-1.0.0',
+          target: 'OrderSupportAgent-1.0.0-tool-order-history-lookup-mcp',
+          label: 'calls tool',
+          type: 'step',
+        }),
+      ])
+    );
+  });
+
+  it('returns empty nodes and edges if no agent is found', async () => {
+    const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownAgent', version: '1.0.0' });
+
+    expect(nodes).toEqual([]);
+    expect(edges).toEqual([]);
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/badge-styles.test.ts b/packages/core/eventcatalog/src/utils/__tests__/badge-styles.test.ts
new file mode 100644
index 000000000..21d10bb67
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/badge-styles.test.ts
@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getBadgeHref } from '../badge-styles';
+
+describe('getBadgeHref', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('returns undefined when a badge has no url', () => {
+    expect(getBadgeHref({})).toBeUndefined();
+  });
+
+  it('builds root-relative badge urls through the catalog url builder', () => {
+    expect(getBadgeHref({ url: '/domains/Payments' })).toBe('/domains/Payments');
+  });
+
+  it('keeps safe absolute badge urls unchanged', () => {
+    expect(getBadgeHref({ url: 'https://example.com/docs' })).toBe('https://example.com/docs');
+    expect(getBadgeHref({ url: 'http://example.com/docs' })).toBe('http://example.com/docs');
+    expect(getBadgeHref({ url: 'mailto:hello@example.com' })).toBe('mailto:hello@example.com');
+    expect(getBadgeHref({ url: 'tel:+441234567890' })).toBe('tel:+441234567890');
+  });
+
+  it('rejects unsafe absolute badge url schemes', () => {
+    expect(getBadgeHref({ url: 'javascript:alert(1)' })).toBeUndefined();
+    expect(getBadgeHref({ url: 'data:text/html,<script>alert(1)</script>' })).toBeUndefined();
+    expect(getBadgeHref({ url: 'vbscript:msgbox(1)' })).toBeUndefined();
+  });
+
+  it('does not rebuild badge urls that already include the catalog base url', () => {
+    vi.stubEnv('BASE_URL', '/catalog/');
+
+    expect(getBadgeHref({ url: '/catalog/docs/services/InventoryService/0.0.2/spec/openapi' })).toBe(
+      '/catalog/docs/services/InventoryService/0.0.2/spec/openapi'
+    );
+  });
+
+  it('still base-prefixes root-relative badge urls without the catalog base url', () => {
+    vi.stubEnv('BASE_URL', '/catalog/');
+
+    expect(getBadgeHref({ url: '/docs/services/InventoryService/0.0.2' })).toBe('/catalog/docs/services/InventoryService/0.0.2');
+  });
+});
diff --git a/eventcatalog/src/utils/__tests__/channels/channels.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/channels/channels.spec.ts
similarity index 98%
rename from eventcatalog/src/utils/__tests__/channels/channels.spec.ts
rename to packages/core/eventcatalog/src/utils/__tests__/channels/channels.spec.ts
index 9871e319a..56a2ad75c 100644
--- a/eventcatalog/src/utils/__tests__/channels/channels.spec.ts
+++ b/packages/core/eventcatalog/src/utils/__tests__/channels/channels.spec.ts
@@ -1,13 +1,13 @@
-import type { CollectionEntry, ContentCollectionKey } from 'astro:content';
+import type { CollectionEntry, CollectionKey } from 'astro:content';
 import { expect, describe, it, vi } from 'vitest';
 import { mockCommands, mockEvents, mockQueries, mockServices, mockChannels } from './mocks';
-import { getChannels, getChannelChain, isChannelsConnected } from '@utils/channels';
+import { getChannels, getChannelChain, isChannelsConnected } from '@utils/collections/channels';
 
 vi.mock('astro:content', async (importOriginal) => {
   return {
     ...(await importOriginal<typeof import('astro:content')>()),
     // this will only affect "foo" outside of the original module
-    getCollection: (key: ContentCollectionKey) => {
+    getCollection: (key: CollectionKey) => {
       switch (key) {
         case 'services':
           return Promise.resolve(mockServices);
diff --git a/eventcatalog/src/utils/__tests__/channels/mocks.ts b/packages/core/eventcatalog/src/utils/__tests__/channels/mocks.ts
similarity index 100%
rename from eventcatalog/src/utils/__tests__/channels/mocks.ts
rename to packages/core/eventcatalog/src/utils/__tests__/channels/mocks.ts
diff --git a/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/asyncapi.yml b/packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/asyncapi.yml
similarity index 100%
rename from eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/asyncapi.yml
rename to packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/asyncapi.yml
diff --git a/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/index.mdx b/packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/index.mdx
similarity index 100%
rename from eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/index.mdx
rename to packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/index.mdx
diff --git a/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/schema-unchanged.json b/packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/schema-unchanged.json
similarity index 100%
rename from eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/schema-unchanged.json
rename to packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/schema-unchanged.json
diff --git a/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/schema.json b/packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/schema.json
similarity index 100%
rename from eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/schema.json
rename to packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/schema.json
diff --git a/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/asyncapi.yml b/packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/asyncapi.yml
similarity index 100%
rename from eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/asyncapi.yml
rename to packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/asyncapi.yml
diff --git a/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/index.md b/packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/index.md
similarity index 100%
rename from eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/index.md
rename to packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/index.md
diff --git a/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/schema-unchanged.json b/packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/schema-unchanged.json
similarity index 100%
rename from eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/schema-unchanged.json
rename to packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/schema-unchanged.json
diff --git a/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/schema.json b/packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/schema.json
similarity index 100%
rename from eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/schema.json
rename to packages/core/eventcatalog/src/utils/__tests__/collections/fake-catalog/events/OrderAmended/versioned/0.0.1/schema.json
diff --git a/eventcatalog/src/utils/__tests__/collections/file-diffs.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/collections/file-diffs.spec.ts
similarity index 97%
rename from eventcatalog/src/utils/__tests__/collections/file-diffs.spec.ts
rename to packages/core/eventcatalog/src/utils/__tests__/collections/file-diffs.spec.ts
index e4768b819..e585713ac 100644
--- a/eventcatalog/src/utils/__tests__/collections/file-diffs.spec.ts
+++ b/packages/core/eventcatalog/src/utils/__tests__/collections/file-diffs.spec.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { getDiffsForCurrentAndPreviousVersion } from '@utils/collections/file-diffs';
+import { getDiffsForCurrentAndPreviousVersion } from '@utils/file-diffs';
 import { join } from 'node:path';
 
 const pathToTestCatalog = join(__dirname, 'fake-catalog');
diff --git a/packages/core/eventcatalog/src/utils/__tests__/collections/owners.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/collections/owners.spec.ts
new file mode 100644
index 000000000..fdf348e74
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/collections/owners.spec.ts
@@ -0,0 +1,80 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { getOwnerDetails, getOwnerNames } from '@utils/collections/owners';
+
+vi.mock('astro:content', () => {
+  const users = [
+    { data: { id: 'jdoe', name: 'Jane Doe', role: 'Staff Engineer', hidden: false }, collection: 'users' },
+    { data: { id: 'asmith', name: 'Alice Smith', role: 'Product Manager', hidden: false }, collection: 'users' },
+  ];
+  const teams = [
+    { data: { id: 'platform', name: 'Platform Team', summary: 'Owns platform infra', hidden: false }, collection: 'teams' },
+  ];
+
+  return {
+    getCollection: vi.fn((name: string) => {
+      if (name === 'users') return Promise.resolve(users);
+      if (name === 'teams') return Promise.resolve(teams);
+      return Promise.resolve([]);
+    }),
+  };
+});
+
+describe('owners', () => {
+  describe('getOwnerNames', () => {
+    it('resolves string owner IDs to their display names', async () => {
+      const names = await getOwnerNames(['jdoe', 'platform']);
+      expect(names).toEqual(['Jane Doe', 'Platform Team']);
+    });
+
+    it('resolves {id} object references to their display names', async () => {
+      const names = await getOwnerNames([{ id: 'jdoe' }, { id: 'platform' }]);
+      expect(names).toEqual(['Jane Doe', 'Platform Team']);
+    });
+
+    it('falls back to the raw ID when the owner is not found', async () => {
+      const names = await getOwnerNames(['unknown-user']);
+      expect(names).toEqual(['unknown-user']);
+    });
+
+    it('returns an empty array when given no owners', async () => {
+      const names = await getOwnerNames([]);
+      expect(names).toEqual([]);
+    });
+  });
+
+  describe('getOwnerDetails', () => {
+    it('resolves a user owner with their name, type, and role', async () => {
+      const details = await getOwnerDetails([{ id: 'jdoe' }]);
+      expect(details).toEqual([{ id: 'jdoe', name: 'Jane Doe', type: 'users', role: 'Staff Engineer' }]);
+    });
+
+    it('resolves a team owner with their name, type, and summary as role', async () => {
+      const details = await getOwnerDetails([{ id: 'platform' }]);
+      expect(details).toEqual([{ id: 'platform', name: 'Platform Team', type: 'teams', role: 'Owns platform infra' }]);
+    });
+
+    it('resolves string IDs the same as {id} objects', async () => {
+      const details = await getOwnerDetails(['asmith']);
+      expect(details).toEqual([{ id: 'asmith', name: 'Alice Smith', type: 'users', role: 'Product Manager' }]);
+    });
+
+    it('returns a fallback entry with type "unknown" when the owner is not found', async () => {
+      const details = await getOwnerDetails(['ghost']);
+      expect(details).toEqual([{ id: 'ghost', name: 'ghost', type: 'unknown', role: undefined }]);
+    });
+
+    it('resolves a mix of users, teams, and unknown owners', async () => {
+      const details = await getOwnerDetails(['jdoe', { id: 'platform' }, 'nobody']);
+      expect(details).toEqual([
+        { id: 'jdoe', name: 'Jane Doe', type: 'users', role: 'Staff Engineer' },
+        { id: 'platform', name: 'Platform Team', type: 'teams', role: 'Owns platform infra' },
+        { id: 'nobody', name: 'nobody', type: 'unknown', role: undefined },
+      ]);
+    });
+
+    it('returns an empty array when given no owners', async () => {
+      const details = await getOwnerDetails([]);
+      expect(details).toEqual([]);
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/collections/user-team-adrs.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/collections/user-team-adrs.spec.ts
new file mode 100644
index 000000000..961c2e72c
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/collections/user-team-adrs.spec.ts
@@ -0,0 +1,138 @@
+import type { CollectionKey } from 'astro:content';
+import { describe, expect, it, vi } from 'vitest';
+
+const user = {
+  id: 'users/dave.mdx',
+  collection: 'users',
+  data: {
+    id: 'dave',
+    name: 'Dave',
+    hidden: false,
+  },
+};
+
+const team = {
+  id: 'teams/platform.mdx',
+  collection: 'teams',
+  data: {
+    id: 'platform',
+    name: 'Platform',
+    hidden: false,
+    members: [{ id: 'dave' }],
+  },
+};
+
+const userOwnedAdr = {
+  id: 'adrs/adr-001/index.mdx',
+  collection: 'adrs',
+  filePath: 'adrs/adr-001/index.mdx',
+  data: {
+    id: 'adr-001',
+    name: 'ADR-001: Direct owner decision',
+    version: '1.0.0',
+    status: 'accepted',
+    date: new Date('2026-01-01'),
+    hidden: false,
+    owners: [{ id: 'dave' }],
+  },
+};
+
+const teamOwnedAdr = {
+  id: 'adrs/adr-002/index.mdx',
+  collection: 'adrs',
+  filePath: 'adrs/adr-002/index.mdx',
+  data: {
+    id: 'adr-002',
+    name: 'ADR-002: Team owner decision',
+    version: '1.0.0',
+    status: 'proposed',
+    date: new Date('2026-01-02'),
+    hidden: false,
+    owners: [{ id: 'platform' }],
+  },
+};
+
+const userOwnedSystem = {
+  id: 'systems/CoreMonolith/index.mdx',
+  collection: 'systems',
+  filePath: 'systems/CoreMonolith/index.mdx',
+  data: {
+    id: 'CoreMonolith',
+    name: 'Core Monolith',
+    version: '1.0.0',
+    hidden: false,
+    owners: [{ id: 'dave' }],
+  },
+};
+
+const teamOwnedSystem = {
+  id: 'systems/PaymentsPlatform/index.mdx',
+  collection: 'systems',
+  filePath: 'systems/PaymentsPlatform/index.mdx',
+  data: {
+    id: 'PaymentsPlatform',
+    name: 'Payments Platform',
+    version: '1.0.0',
+    hidden: false,
+    owners: [{ id: 'platform' }],
+  },
+};
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: (key: CollectionKey) => {
+      switch (key) {
+        case 'users':
+          return Promise.resolve([user]);
+        case 'teams':
+          return Promise.resolve([team]);
+        case 'adrs':
+          return Promise.resolve([userOwnedAdr, teamOwnedAdr]);
+        case 'systems':
+          return Promise.resolve([userOwnedSystem, teamOwnedSystem]);
+        default:
+          return Promise.resolve([]);
+      }
+    },
+  };
+});
+
+describe('user and team ADR ownership', () => {
+  it('includes directly owned and team-owned ADRs on user profiles', async () => {
+    const { getUsers } = await import('../../collections/users');
+
+    const users = await getUsers();
+
+    expect((users[0].data as any).ownedAdrs.map((adr: any) => adr.data.id)).toEqual(['adr-001', 'adr-002']);
+  });
+
+  it('includes directly owned ADRs on team profiles', async () => {
+    const { getTeams } = await import('../../collections/teams');
+
+    const teams = await getTeams();
+
+    expect((teams[0].data as any).ownedAdrs.map((adr: any) => adr.data.id)).toEqual(['adr-002']);
+  });
+});
+
+describe('user and team system ownership', () => {
+  it('includes directly owned and team-owned systems on user profiles', async () => {
+    const { getUsers } = await import('../../collections/users');
+
+    const users = await getUsers();
+
+    expect((users[0].data as any).ownedSystems.map((system: any) => system.data.id)).toEqual([
+      'CoreMonolith',
+      'PaymentsPlatform',
+    ]);
+  });
+
+  it('includes directly owned systems on team profiles', async () => {
+    const { getTeams } = await import('../../collections/teams');
+
+    const teams = await getTeams();
+
+    expect((teams[0].data as any).ownedSystems.map((system: any) => system.data.id)).toEqual(['PaymentsPlatform']);
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/collections/util.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/collections/util.spec.ts
new file mode 100644
index 000000000..9fc7656b7
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/collections/util.spec.ts
@@ -0,0 +1,297 @@
+import type { CollectionTypes } from '@types';
+import {
+  getDeprecatedDetails,
+  getPointerField,
+  getResourceTypeLabel,
+  isSameVersion,
+  processSpecifications,
+  satisfies,
+  sortStringVersions,
+  versionMatches,
+} from '@utils/collections/util';
+import type { CollectionEntry } from 'astro:content';
+import { describe, it, expect } from 'vitest';
+
+describe('Collections - utils', () => {
+  describe('satisfies', () => {
+    it.each([
+      [{ version: '1.0.0', range: '1.0.0', expected: true }],
+      [{ version: '1.0.0', range: '^1', expected: true }],
+      [{ version: '1.0.0', range: '1', expected: true }],
+      [{ version: '1.0.0', range: 'v1', expected: true }],
+      [{ version: '1.0.0', range: '>1', expected: false }],
+      [{ version: '1', range: '1', expected: true }],
+      [{ version: '1', range: '^1', expected: true }],
+      [{ version: '1', range: '1.0.0', expected: true }],
+      [{ version: '1', range: 'v1', expected: true }],
+      [{ version: '1', range: '<1', expected: false }],
+      [{ version: '2', range: 'v1', expected: false }],
+      [{ version: 'v1', range: 'v1', expected: true }],
+      [{ version: 'v1', range: '1', expected: true }],
+      [{ version: 'v1', range: '1.0.0', expected: true }],
+      [{ version: 'v1', range: '^1', expected: true }],
+      [{ version: 'v1', range: '2', expected: false }],
+      [{ version: 'v1', range: '>1', expected: false }],
+    ])('should returns $expected to version as $version and range as $range', ({ expected, version, range }) => {
+      expect(satisfies(version, range)).toBe(expected);
+    });
+  });
+
+  describe('sortStringVersions', () => {
+    it.each([
+      [{ versions: ['1', '3', '2'], result: ['3', '2', '1'], latest: '3' }],
+      [{ versions: ['10', '1', '2', '3'], result: ['10', '3', '2', '1'], latest: '10' }],
+      [{ versions: ['1.0.1', '1.1.0', '1.0.2'], result: ['1.1.0', '1.0.2', '1.0.1'], latest: '1.1.0' }],
+      [{ versions: ['a', 'c', 'b'], result: ['c', 'b', 'a'], latest: 'c' }],
+      [{ versions: [], result: [], latest: undefined }],
+    ])('should returns $latest as latest version of $versions', ({ versions, result, latest }) => {
+      expect(sortStringVersions(versions)).toEqual({ versions: result, latestVersion: latest });
+    });
+  });
+
+  describe('isSameVersion', () => {
+    it.each([
+      [{ versions: ['1', '2'], result: false }],
+      [{ versions: ['1', '1'], result: true }],
+      [{ versions: ['2.0.0', '1.1.0'], result: false }],
+      [{ versions: ['2.0.0', '2.0.0'], result: true }],
+      [{ versions: ['a', 'b'], result: false }],
+      [{ versions: ['a', 'a'], result: true }],
+      [{ versions: ['1.0.0', undefined], result: false }],
+    ])('should returns $result when versions is $versions', ({ versions, result }) => {
+      expect(isSameVersion(versions[0], versions[1])).toBe(result);
+    });
+  });
+
+  describe('getDeprecatedDetails', () => {
+    it('returns false when deprecated is false', () => {
+      const result = getDeprecatedDetails({ data: { deprecated: false } } as unknown as CollectionEntry<CollectionTypes>);
+      expect(result).toEqual({ hasDeprecated: false, isMarkedAsDeprecated: false, message: '', deprecatedDate: '' });
+    });
+
+    it('returns true when deprecated is true (boolean)', () => {
+      const result = getDeprecatedDetails({ data: { deprecated: true } } as unknown as CollectionEntry<CollectionTypes>);
+      expect(result).toEqual({ hasDeprecated: true, isMarkedAsDeprecated: true, message: '', deprecatedDate: '' });
+    });
+
+    it('returns true when deprecated is true (object)', () => {
+      const result = getDeprecatedDetails({
+        data: { deprecated: { date: '2021-01-01', message: 'This is a test message' } },
+      } as unknown as CollectionEntry<CollectionTypes>);
+      expect(result).toEqual({
+        hasDeprecated: true,
+        isMarkedAsDeprecated: true,
+        message: 'This is a test message',
+        deprecatedDate: 'January 1, 2021',
+      });
+    });
+  });
+
+  describe('processSpecifications', () => {
+    it('preserves headers in array specification format', () => {
+      const result = processSpecifications([
+        {
+          type: 'asyncapi',
+          path: 'https://example.com/asyncapi.yaml',
+          headers: {
+            Authorization: 'Bearer ${TOKEN}',
+          },
+        },
+      ]);
+
+      expect(result).toEqual([
+        {
+          type: 'asyncapi',
+          path: 'https://example.com/asyncapi.yaml',
+          name: 'AsyncAPI',
+          filename: 'asyncapi.yaml',
+          filenameWithoutExtension: 'asyncapi',
+          headers: {
+            Authorization: 'Bearer ${TOKEN}',
+          },
+        },
+      ]);
+    });
+  });
+
+  describe('versionMatches', () => {
+    describe('should_match_exact_versions', () => {
+      it('matches when version equals rangePattern exactly', () => {
+        expect(versionMatches('1.0.0', '1.0.0')).toBe(true);
+        expect(versionMatches('2.5.3', '2.5.3')).toBe(true);
+        expect(versionMatches('0.0.1', '0.0.1')).toBe(true);
+      });
+    });
+
+    describe('should_match_when_range_has_caret_and_version_satisfies', () => {
+      it('matches version 1.2.3 with rangePattern ^1.0.0', () => {
+        expect(versionMatches('1.2.3', '^1.0.0')).toBe(true);
+      });
+
+      it('matches version 1.0.0 with rangePattern ^1.0.0', () => {
+        expect(versionMatches('1.0.0', '^1.0.0')).toBe(true);
+      });
+
+      it('matches version 1.9.9 with rangePattern ^1.0.0', () => {
+        expect(versionMatches('1.9.9', '^1.0.0')).toBe(true);
+      });
+    });
+
+    describe('should_match_when_range_has_tilde_and_version_satisfies', () => {
+      it('matches version 1.2.5 with rangePattern ~1.2.0', () => {
+        expect(versionMatches('1.2.5', '~1.2.0')).toBe(true);
+      });
+
+      it('matches version 1.2.0 with rangePattern ~1.2.0', () => {
+        expect(versionMatches('1.2.0', '~1.2.0')).toBe(true);
+      });
+
+      it('does not match version 1.3.0 with rangePattern ~1.2.0', () => {
+        expect(versionMatches('1.3.0', '~1.2.0')).toBe(false);
+      });
+    });
+
+    describe('should_not_match_when_version_does_not_satisfy_range', () => {
+      it('does not match version 1.0.0 with rangePattern ^2.0.0', () => {
+        expect(versionMatches('1.0.0', '^2.0.0')).toBe(false);
+      });
+
+      it('does not match version 3.0.0 with rangePattern ^2.0.0', () => {
+        expect(versionMatches('3.0.0', '^2.0.0')).toBe(false);
+      });
+
+      it('does not match version 0.9.9 with rangePattern ^1.0.0', () => {
+        expect(versionMatches('0.9.9', '^1.0.0')).toBe(false);
+      });
+    });
+
+    describe('should_handle_complex_semver_ranges', () => {
+      it('matches version 1.5.0 with rangePattern >=1.0.0 <2.0.0', () => {
+        expect(versionMatches('1.5.0', '>=1.0.0 <2.0.0')).toBe(true);
+      });
+
+      it('matches version 1.0.0 with rangePattern >=1.0.0 <2.0.0', () => {
+        expect(versionMatches('1.0.0', '>=1.0.0 <2.0.0')).toBe(true);
+      });
+
+      it('does not match version 2.0.0 with rangePattern >=1.0.0 <2.0.0', () => {
+        expect(versionMatches('2.0.0', '>=1.0.0 <2.0.0')).toBe(false);
+      });
+
+      it('does not match version 0.9.9 with rangePattern >=1.0.0 <2.0.0', () => {
+        expect(versionMatches('0.9.9', '>=1.0.0 <2.0.0')).toBe(false);
+      });
+    });
+
+    describe('should_return_false_when_version_is_invalid_semver', () => {
+      it('returns false for invalid version with valid rangePattern', () => {
+        expect(versionMatches('not-a-version', '^1.0.0')).toBe(false);
+      });
+
+      it('returns false for invalid version with exact rangePattern', () => {
+        expect(versionMatches('invalid', '1.0.0')).toBe(false);
+      });
+    });
+
+    describe('should_handle_latest_keyword', () => {
+      it('matches any version when rangePattern is latest', () => {
+        expect(versionMatches('1.0.0', 'latest')).toBe(true);
+        expect(versionMatches('2.5.3', 'latest')).toBe(true);
+        expect(versionMatches('0.0.1', 'latest')).toBe(true);
+        expect(versionMatches('99.99.99', 'latest')).toBe(true);
+      });
+    });
+
+    describe('should_match_when_range_has_single_x_pattern', () => {
+      it('matches versions with major version 1 against rangePattern 1.x', () => {
+        expect(versionMatches('1.0.0', '1.x')).toBe(true);
+        expect(versionMatches('1.2.3', '1.x')).toBe(true);
+        expect(versionMatches('1.99.99', '1.x')).toBe(true);
+      });
+
+      it('does not match versions with different major version', () => {
+        expect(versionMatches('2.0.0', '1.x')).toBe(false);
+        expect(versionMatches('0.9.9', '1.x')).toBe(false);
+      });
+    });
+
+    describe('should_match_when_range_has_double_x_pattern', () => {
+      it('matches versions with major.minor 1.2 against rangePattern 1.2.x', () => {
+        expect(versionMatches('1.2.0', '1.2.x')).toBe(true);
+        expect(versionMatches('1.2.5', '1.2.x')).toBe(true);
+        expect(versionMatches('1.2.99', '1.2.x')).toBe(true);
+      });
+
+      it('does not match versions with different major.minor', () => {
+        expect(versionMatches('1.3.0', '1.2.x')).toBe(false);
+        expect(versionMatches('2.2.0', '1.2.x')).toBe(false);
+      });
+    });
+
+    describe('should_not_match_when_x_pattern_differs', () => {
+      it('does not match when major version differs', () => {
+        expect(versionMatches('1.0.0', '2.x')).toBe(false);
+        expect(versionMatches('3.0.0', '2.x')).toBe(false);
+      });
+    });
+
+    describe('should_not_match_when_prefix_matches_but_boundary_incorrect', () => {
+      it('does not match 1.20.0 with rangePattern 1.2.x', () => {
+        expect(versionMatches('1.20.0', '1.2.x')).toBe(false);
+      });
+
+      it('does not match 10.0.0 with rangePattern 1.x', () => {
+        expect(versionMatches('10.0.0', '1.x')).toBe(false);
+      });
+    });
+
+    describe('should_handle_x_at_major_version', () => {
+      it('matches version 2.0.0 with rangePattern 2.x', () => {
+        expect(versionMatches('2.0.0', '2.x')).toBe(true);
+        expect(versionMatches('2.1.0', '2.x')).toBe(true);
+        expect(versionMatches('2.99.99', '2.x')).toBe(true);
+      });
+    });
+  });
+
+  describe('getResourceTypeLabel', () => {
+    it('converts a plural collection name to a capitalized singular label', () => {
+      expect(getResourceTypeLabel('services')).toBe('Service');
+      expect(getResourceTypeLabel('events')).toBe('Event');
+      expect(getResourceTypeLabel('commands')).toBe('Command');
+      expect(getResourceTypeLabel('queries')).toBe('Query');
+      expect(getResourceTypeLabel('domains')).toBe('Domain');
+    });
+
+    it('converts hyphenated collection names to title-cased words', () => {
+      expect(getResourceTypeLabel('data-products')).toBe('Data Product');
+    });
+
+    it('title-cases the raw collection name when not found in collectionToResourceMap', () => {
+      expect(getResourceTypeLabel('unknown-collection')).toBe('Unknown Collection');
+    });
+  });
+
+  describe('getPointerField', () => {
+    it('returns "outputs" for data-products when direction is "sends"', () => {
+      expect(getPointerField('data-products', 'sends')).toBe('outputs');
+    });
+
+    it('returns "inputs" for data-products when direction is "receives"', () => {
+      expect(getPointerField('data-products', 'receives')).toBe('inputs');
+    });
+
+    it('returns "sends" for services when direction is "sends"', () => {
+      expect(getPointerField('services', 'sends')).toBe('sends');
+    });
+
+    it('returns "receives" for services when direction is "receives"', () => {
+      expect(getPointerField('services', 'receives')).toBe('receives');
+    });
+
+    it('returns the direction as-is for domains', () => {
+      expect(getPointerField('domains', 'sends')).toBe('sends');
+      expect(getPointerField('domains', 'receives')).toBe('receives');
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/collections/version-compare.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/collections/version-compare.spec.ts
new file mode 100644
index 000000000..87df22a78
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/collections/version-compare.spec.ts
@@ -0,0 +1,23 @@
+import { isSameVersion } from '@utils/collections/version-compare';
+import { describe, it, expect } from 'vitest';
+
+describe('version-compare', () => {
+  describe('isSameVersion', () => {
+    it.each([
+      [{ v1: '1.0.0', v2: '1.0.0', expected: true }],
+      [{ v1: '1', v2: '1', expected: true }],
+      [{ v1: '1', v2: '1.0.0', expected: true }],
+      [{ v1: 'v1', v2: '1.0.0', expected: true }],
+      [{ v1: '1.0.0', v2: '2.0.0', expected: false }],
+      [{ v1: '2.0.0', v2: '1.1.0', expected: false }],
+      [{ v1: '1', v2: '2', expected: false }],
+      [{ v1: 'a', v2: 'a', expected: true }],
+      [{ v1: 'a', v2: 'b', expected: false }],
+      [{ v1: '1.0.0', v2: undefined, expected: false }],
+      [{ v1: undefined, v2: '1.0.0', expected: false }],
+      [{ v1: undefined, v2: undefined, expected: true }],
+    ])('returns $expected for v1=$v1 v2=$v2', ({ v1, v2, expected }) => {
+      expect(isSameVersion(v1, v2)).toBe(expected);
+    });
+  });
+});
diff --git a/eventcatalog/src/utils/__tests__/commands/commands.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/commands/commands.spec.ts
similarity index 96%
rename from eventcatalog/src/utils/__tests__/commands/commands.spec.ts
rename to packages/core/eventcatalog/src/utils/__tests__/commands/commands.spec.ts
index 3df5273e5..556331a99 100644
--- a/eventcatalog/src/utils/__tests__/commands/commands.spec.ts
+++ b/packages/core/eventcatalog/src/utils/__tests__/commands/commands.spec.ts
@@ -1,13 +1,13 @@
-import type { ContentCollectionKey } from 'astro:content';
+import type { CollectionKey } from 'astro:content';
 import { expect, describe, it, vi } from 'vitest';
 import { mockServices, mockCommands } from './mocks';
-import { getCommands } from '@utils/commands';
+import { getCommands } from '@utils/collections/commands';
 
 vi.mock('astro:content', async (importOriginal) => {
   return {
     ...(await importOriginal<typeof import('astro:content')>()),
     // this will only affect "foo" outside of the original module
-    getCollection: (key: ContentCollectionKey) => {
+    getCollection: (key: CollectionKey) => {
       switch (key) {
         case 'services':
           return Promise.resolve(mockServices);
diff --git a/packages/core/eventcatalog/src/utils/__tests__/commands/mocks.ts b/packages/core/eventcatalog/src/utils/__tests__/commands/mocks.ts
new file mode 100644
index 000000000..63b7af1dd
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/commands/mocks.ts
@@ -0,0 +1,197 @@
+export const mockServices = [
+  {
+    id: 'OrderService',
+    slug: 'OrderService',
+    collection: 'services',
+    data: {
+      id: 'OrderService',
+      version: '0.0.1',
+      sends: [
+        {
+          id: 'AdjustOrder',
+          version: '0.0.1',
+        },
+      ],
+      receives: [
+        {
+          id: 'PlaceOrder',
+          version: '>1.5.0',
+        },
+        {
+          id: 'GetOrder',
+          version: '0.0.1',
+          from: [
+            {
+              id: 'EmailChannel',
+              version: '1.0.0',
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    id: 'PaymentService',
+    slug: 'PaymentService',
+    collection: 'services',
+    data: {
+      id: 'PaymentService',
+      version: '0.0.1',
+      sends: [
+        {
+          id: 'PlaceOrder',
+          version: '0.0.1',
+          to: [
+            {
+              id: 'EmailChannel',
+              version: '1.0.0',
+            },
+          ],
+        },
+        {
+          id: 'GetOrder',
+          version: '0.0.1',
+          to: [
+            {
+              id: 'EmailChannel',
+              version: '1.0.0',
+            },
+          ],
+        },
+      ],
+      receives: [
+        {
+          id: 'AdjustOrder',
+          version: '0.0.1',
+        },
+      ],
+    },
+  },
+  {
+    id: 'InventoryService',
+    slug: 'InventoryService',
+    collection: 'services',
+    data: {
+      id: 'InventoryService',
+      version: '0.0.1',
+      sends: [{ id: 'NotifyLowStock' }],
+    },
+  },
+  {
+    id: 'NotificationService',
+    slug: 'NotificationService',
+    collection: 'services',
+    data: {
+      id: 'NotificationService',
+      version: '0.0.1',
+      receives: [{ id: 'NotifyLowStock', version: 'latest' }],
+    },
+  },
+  {
+    id: 'LegacyOrderService',
+    slug: 'LegacyOrderService',
+    collection: 'services',
+    data: {
+      id: 'LegacyOrderService',
+      version: '0.0.1',
+      receives: [{ id: 'GetOrder', version: 'latest' }],
+      sends: [{ id: 'GetOrder', version: 'latest' }],
+    },
+  },
+];
+
+export const mockCommands = [
+  {
+    id: 'AdjustOrder',
+    slug: 'AdjustOrder',
+    collection: 'commands',
+    data: {
+      id: 'AdjustOrder',
+      version: '0.0.1',
+    },
+  },
+  {
+    id: 'PlaceOrder',
+    slug: 'PlaceOrder',
+    collection: 'commands',
+    data: {
+      id: 'PlaceOrder',
+      version: '1.5.1',
+    },
+  },
+  {
+    id: 'PlaceOrder',
+    slug: 'PlaceOrder',
+    collection: 'commands',
+    data: {
+      id: 'PlaceOrder',
+      version: '2.0.1',
+    },
+  },
+  {
+    id: 'NotifyLowStock',
+    slug: 'NotifyLowStock',
+    collection: 'commands',
+    data: {
+      id: 'NotifyLowStock',
+      version: '2.0.0',
+    },
+  },
+  {
+    id: 'NotifyLowStock',
+    slug: 'NotifyLowStock',
+    collection: 'commands',
+    data: {
+      id: 'NotifyLowStock',
+      version: '2.0.1',
+    },
+  },
+  {
+    id: 'GetOrder',
+    slug: 'GetOrder',
+    collection: 'commands',
+    data: {
+      id: 'GetOrder',
+      version: '0.0.1',
+    },
+  },
+];
+
+export const mockChannels = [
+  {
+    id: 'EmailChannel',
+    slug: 'EmailChannel',
+    collection: 'channels',
+    data: {
+      id: 'EmailChannel',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockDataProducts = [
+  {
+    id: 'OrderAnalytics-1.0.0',
+    slug: 'OrderAnalytics',
+    collection: 'data-products',
+    data: {
+      id: 'OrderAnalytics',
+      name: 'Order Analytics',
+      version: '1.0.0',
+      inputs: [{ id: 'AdjustOrder', version: '0.0.1' }],
+      outputs: [],
+    },
+  },
+  {
+    id: 'OrderDataPipeline-1.0.0',
+    slug: 'OrderDataPipeline',
+    collection: 'data-products',
+    data: {
+      id: 'OrderDataPipeline',
+      name: 'Order Data Pipeline',
+      version: '1.0.0',
+      inputs: [],
+      outputs: [{ id: 'AdjustOrder', version: '0.0.1' }],
+    },
+  },
+];
diff --git a/packages/core/eventcatalog/src/utils/__tests__/commands/node-graph.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/commands/node-graph.spec.ts
new file mode 100644
index 000000000..2ce5c4174
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/commands/node-graph.spec.ts
@@ -0,0 +1,456 @@
+import { MarkerType } from '@xyflow/react';
+import { getNodesAndEdgesForCommands as getNodesAndEdges } from '../../node-graphs/message-node-graph';
+import { expect, describe, it, vi } from 'vitest';
+import { mockCommands, mockServices, mockChannels, mockDataProducts } from './mocks';
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: (key: string) => {
+      if (key === 'services') {
+        return Promise.resolve(mockServices);
+      }
+      if (key === 'commands') {
+        return Promise.resolve(mockCommands);
+      }
+      if (key === 'channels') {
+        return Promise.resolve(mockChannels);
+      }
+      if (key === 'data-products') {
+        return Promise.resolve(mockDataProducts);
+      }
+      return Promise.resolve([]);
+    },
+  };
+});
+
+describe('Commands NodeGraph', () => {
+  describe('getNodesAndEdges', () => {
+    it('should return nodes and edges for a given command', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'AdjustOrder', version: '0.0.1' });
+
+      // The middle node itself, the service
+      const expectedCommandNode = {
+        id: 'AdjustOrder-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        type: 'commands',
+      };
+
+      const expectedProducerNode = {
+        id: 'OrderService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[0].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedConsumerNode = {
+        id: 'PaymentService-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({
+          title: 'PaymentService',
+          mode: 'simple',
+          service: { ...mockServices[1].data },
+        }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        expect.objectContaining({
+          id: 'OrderService-0.0.1-AdjustOrder-0.0.1',
+          source: 'OrderService-0.0.1',
+          target: 'AdjustOrder-0.0.1',
+          label: 'invokes',
+        }),
+        expect.objectContaining({
+          id: 'AdjustOrder-0.0.1-PaymentService-0.0.1',
+          source: 'AdjustOrder-0.0.1',
+          target: 'PaymentService-0.0.1',
+          label: 'accepts',
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedConsumerNode),
+
+          // The command node itself
+          expect.objectContaining(expectedCommandNode),
+
+          // Nodes on the right
+          expect.objectContaining(expectedProducerNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('if the command is produced and consumed by a service it will render a custom edge', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'GetOrder', version: '0.0.1' });
+
+      // The middle node itself, the service
+      const expectedCommandNode = {
+        id: 'GetOrder-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', message: expect.anything() }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'commands',
+      };
+
+      const expectedProducerNode = {
+        id: 'LegacyOrderService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[4].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedConsumerNode = {
+        id: 'LegacyOrderService-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({
+          title: 'LegacyOrderService',
+          mode: 'simple',
+          service: { ...mockServices[4].data },
+        }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        expect.objectContaining({
+          id: 'LegacyOrderService-0.0.1-GetOrder-0.0.1',
+          source: 'LegacyOrderService-0.0.1',
+          target: 'GetOrder-0.0.1',
+          label: 'invokes',
+          animated: false,
+        }),
+        expect.objectContaining({
+          id: 'GetOrder-0.0.1-LegacyOrderService-0.0.1',
+          source: 'GetOrder-0.0.1',
+          target: 'LegacyOrderService-0.0.1',
+          label: 'accepts',
+          animated: false,
+        }),
+        expect.objectContaining({
+          id: 'GetOrder-0.0.1-LegacyOrderService-0.0.1-both',
+          source: 'GetOrder-0.0.1',
+          target: 'LegacyOrderService-0.0.1',
+          label: 'publishes and subscribes',
+          animated: false,
+          markerEnd: {
+            type: MarkerType.ArrowClosed,
+            width: 20,
+            height: 20,
+          },
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedConsumerNode),
+
+          // The event node itself
+          expect.objectContaining(expectedCommandNode),
+
+          // Nodes on the right
+          expect.objectContaining(expectedProducerNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('if the consumer of a command has defined a channel, it will render the channel node and edges', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'GetOrder', version: '0.0.1' });
+
+      const expectedConsumerNode = {
+        id: 'OrderService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[0].data }, title: 'OrderService' }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedChannelNode = {
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        id: 'EmailChannel-1.0.0',
+        type: 'channels',
+      };
+
+      const expectedCommandNode = {
+        id: 'GetOrder-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        type: 'commands',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        // Message to the channel
+        expect.objectContaining({
+          id: 'GetOrder-0.0.1-EmailChannel-1.0.0',
+          source: 'GetOrder-0.0.1',
+          target: 'EmailChannel-1.0.0',
+        }),
+        // Channel to the consumer
+        expect.objectContaining({
+          id: 'EmailChannel-1.0.0-OrderService-0.0.1',
+          source: 'EmailChannel-1.0.0',
+          target: 'OrderService-0.0.1',
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedConsumerNode),
+
+          // channel
+          expect.objectContaining(expectedChannelNode),
+
+          // The command node itself
+          expect.objectContaining(expectedCommandNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('if the producer of an event has defined a channel, it will render the channel node and edges', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'GetOrder', version: '0.0.1' });
+
+      const expectedProducerNode = {
+        id: 'PaymentService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedChannelNode = {
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        id: 'EmailChannel-1.0.0',
+        type: 'channels',
+      };
+
+      const expectedCommandNode = {
+        id: 'GetOrder-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        type: 'commands',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        // Producer to the message
+        expect.objectContaining({
+          id: 'PaymentService-0.0.1-GetOrder-0.0.1',
+          source: 'PaymentService-0.0.1',
+          target: 'GetOrder-0.0.1',
+          label: 'invokes',
+          animated: false,
+        }),
+        // Message to the channel
+        expect.objectContaining({
+          id: 'GetOrder-0.0.1-EmailChannel-1.0.0',
+          source: 'GetOrder-0.0.1',
+          target: 'EmailChannel-1.0.0',
+          label: 'routes to',
+          animated: false,
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedProducerNode),
+
+          // channel
+          expect.objectContaining(expectedChannelNode),
+
+          // The command node itself
+          expect.objectContaining(expectedCommandNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('returns an empty array if no commands are found', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownCommand', version: '1.0.0' });
+
+      expect(nodes).toEqual([]);
+      expect(edges).toEqual([]);
+    });
+
+    it('should return nodes and edges for a given event using semver range', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'PlaceOrder', version: '2.0.1' });
+
+      // The middle node itself, the service
+      const expectedCommandNode = {
+        id: 'PlaceOrder-2.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', message: expect.anything() }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'commands',
+      };
+
+      const expectedConsumerNode = {
+        id: 'OrderService-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({
+          title: 'OrderService',
+          mode: 'simple',
+          service: { ...mockServices[0].data },
+        }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        expect.objectContaining({
+          id: 'PlaceOrder-2.0.1-OrderService-0.0.1',
+          source: 'PlaceOrder-2.0.1',
+          target: 'OrderService-0.0.1',
+          label: 'accepts',
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // The command node itself
+          expect.objectContaining(expectedCommandNode),
+
+          // Nodes on the Right
+          expect.objectContaining(expectedConsumerNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    describe('data products', () => {
+      it('should render data product as a consumer when it has the command as an input', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'AdjustOrder', version: '0.0.1' });
+
+        const expectedDataProductConsumerNode = {
+          id: 'OrderAnalytics-1.0.0',
+          type: 'data-products',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({
+            title: 'OrderAnalytics',
+            mode: 'simple',
+            dataProduct: expect.objectContaining({
+              id: 'OrderAnalytics',
+              version: '1.0.0',
+            }),
+          }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        expect(nodes).toEqual(expect.arrayContaining([expect.objectContaining(expectedDataProductConsumerNode)]));
+
+        expect(edges).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'AdjustOrder-0.0.1-OrderAnalytics-1.0.0',
+              source: 'AdjustOrder-0.0.1',
+              target: 'OrderAnalytics-1.0.0',
+              label: 'consumed by',
+            }),
+          ])
+        );
+      });
+
+      it('should render data product as a producer when it has the command as an output', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'AdjustOrder', version: '0.0.1' });
+
+        const expectedDataProductProducerNode = {
+          id: 'OrderDataPipeline-1.0.0',
+          type: 'data-products',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({
+            mode: 'simple',
+            dataProduct: expect.objectContaining({
+              id: 'OrderDataPipeline',
+              version: '1.0.0',
+            }),
+          }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        expect(nodes).toEqual(expect.arrayContaining([expect.objectContaining(expectedDataProductProducerNode)]));
+
+        expect(edges).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderDataPipeline-1.0.0-AdjustOrder-0.0.1',
+              source: 'OrderDataPipeline-1.0.0',
+              target: 'AdjustOrder-0.0.1',
+              label: 'produces',
+            }),
+          ])
+        );
+      });
+
+      it('should render both services and data products as producers and consumers', async () => {
+        const { nodes } = await getNodesAndEdges({ id: 'AdjustOrder', version: '0.0.1' });
+
+        // Should have service producer
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderService-0.0.1',
+              type: 'services',
+            }),
+          ])
+        );
+
+        // Should have service consumer
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'PaymentService-0.0.1',
+              type: 'services',
+            }),
+          ])
+        );
+
+        // Should have data product producer
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderDataPipeline-1.0.0',
+              type: 'data-products',
+            }),
+          ])
+        );
+
+        // Should have data product consumer
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderAnalytics-1.0.0',
+              type: 'data-products',
+            }),
+          ])
+        );
+      });
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/containers/mocks.ts b/packages/core/eventcatalog/src/utils/__tests__/containers/mocks.ts
new file mode 100644
index 000000000..cae7ce5c0
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/containers/mocks.ts
@@ -0,0 +1,367 @@
+export const mockEvents = [
+  {
+    slug: 'PaymentInitiated',
+    collection: 'events',
+    data: {
+      id: 'PaymentInitiated',
+      version: '0.0.1',
+    },
+  },
+  {
+    slug: 'PaymentProcessed',
+    collection: 'events',
+    data: {
+      id: 'PaymentProcessed',
+      version: '0.0.1',
+    },
+  },
+];
+
+export const mockServices = [
+  {
+    slug: 'SubscriptionService',
+    collection: 'services',
+    data: {
+      id: 'SubscriptionService',
+      version: '0.0.1',
+    },
+  },
+  {
+    slug: 'PaymentService',
+    collection: 'services',
+    data: {
+      id: 'PaymentService',
+      version: '0.0.1',
+    },
+  },
+];
+
+export const mockDataProducts = [
+  {
+    slug: 'OrderAnalytics',
+    collection: 'data-products',
+    data: {
+      id: 'OrderAnalytics',
+      name: 'Order Analytics',
+      version: '1.0.0',
+    },
+  },
+  {
+    slug: 'OrderDataPipeline',
+    collection: 'data-products',
+    data: {
+      id: 'OrderDataPipeline',
+      name: 'Order Data Pipeline',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockContainers = [
+  {
+    id: 'OrderDatabase',
+    collection: 'containers',
+    data: {
+      id: 'OrderDatabase',
+      version: '1.0.0',
+      servicesThatWriteToContainer: [
+        {
+          id: 'SubscriptionService',
+          version: '0.0.1',
+          data: {
+            id: 'SubscriptionService',
+            version: '0.0.1',
+          },
+        },
+      ],
+      servicesThatReadFromContainer: [
+        {
+          id: 'SubscriptionService',
+          version: '0.0.1',
+          data: {
+            id: 'SubscriptionService',
+            version: '0.0.1',
+          },
+        },
+      ],
+      dataProductsThatWriteToContainer: [],
+      dataProductsThatReadFromContainer: [],
+    },
+  },
+  {
+    id: 'AnalyticsDatabase',
+    collection: 'containers',
+    data: {
+      id: 'AnalyticsDatabase',
+      version: '1.0.0',
+      technology: 'PostgreSQL',
+      servicesThatWriteToContainer: [],
+      servicesThatReadFromContainer: [],
+      dataProductsThatWriteToContainer: [
+        {
+          id: 'OrderDataPipeline',
+          collection: 'data-products',
+          version: '1.0.0',
+          data: {
+            id: 'OrderDataPipeline',
+            name: 'Order Data Pipeline',
+            version: '1.0.0',
+          },
+        },
+      ],
+      dataProductsThatReadFromContainer: [
+        {
+          id: 'OrderAnalytics',
+          collection: 'data-products',
+          version: '1.0.0',
+          data: {
+            id: 'OrderAnalytics',
+            name: 'Order Analytics',
+            version: '1.0.0',
+          },
+        },
+      ],
+    },
+  },
+  {
+    id: 'SharedDatabase',
+    collection: 'containers',
+    data: {
+      id: 'SharedDatabase',
+      version: '1.0.0',
+      technology: 'MySQL',
+      servicesThatWriteToContainer: [
+        {
+          id: 'PaymentService',
+          collection: 'services',
+          version: '0.0.1',
+          data: {
+            id: 'PaymentService',
+            version: '0.0.1',
+          },
+        },
+      ],
+      servicesThatReadFromContainer: [],
+      dataProductsThatWriteToContainer: [],
+      dataProductsThatReadFromContainer: [
+        {
+          id: 'OrderAnalytics',
+          collection: 'data-products',
+          version: '1.0.0',
+          data: {
+            id: 'OrderAnalytics',
+            name: 'Order Analytics',
+            version: '1.0.0',
+          },
+        },
+      ],
+    },
+  },
+  {
+    id: 'DataProductBothRW',
+    collection: 'containers',
+    data: {
+      id: 'DataProductBothRW',
+      version: '1.0.0',
+      technology: 'MongoDB',
+      servicesThatWriteToContainer: [],
+      servicesThatReadFromContainer: [],
+      dataProductsThatWriteToContainer: [
+        {
+          id: 'OrderDataPipeline',
+          collection: 'data-products',
+          version: '1.0.0',
+          data: {
+            id: 'OrderDataPipeline',
+            name: 'Order Data Pipeline',
+            version: '1.0.0',
+          },
+        },
+      ],
+      dataProductsThatReadFromContainer: [
+        {
+          id: 'OrderDataPipeline',
+          collection: 'data-products',
+          version: '1.0.0',
+          data: {
+            id: 'OrderDataPipeline',
+            name: 'Order Data Pipeline',
+            version: '1.0.0',
+          },
+        },
+      ],
+    },
+  },
+];
+
+export const mockFlow = [
+  {
+    id: 'Payment/PaymentProcessed/index.mdx',
+    slug: 'payment/paymentprocessed',
+    body: '',
+    collection: 'flows',
+    data: {
+      steps: [
+        {
+          id: 1,
+          type: 'node',
+          title: 'Order Placed',
+          next_step: {
+            id: 2,
+            label: 'Proceed to payment',
+          },
+        },
+        {
+          id: 2,
+          title: 'Payment Initiated',
+          message: {
+            id: 'PaymentInitiated',
+            version: '0.0.1',
+          },
+          next_steps: [
+            {
+              id: 3,
+              label: 'Payment successful',
+            },
+            {
+              id: 4,
+              label: 'Payment failed',
+            },
+          ],
+        },
+        {
+          id: 3,
+          title: 'Payment Processed',
+          message: {
+            id: 'PaymentProcessed',
+            version: '0.0.1',
+          },
+        },
+        {
+          id: 4,
+          type: 'node',
+          title: 'Payment Failed',
+        },
+      ],
+      id: 'PaymentFlow',
+      name: 'Payment Flow for E-commerce',
+      summary: 'Business flow for processing payments in an e-commerce platform',
+      version: '1.0.0',
+      type: 'node',
+    },
+  },
+];
+
+export const mockFlowByIds = [
+  {
+    id: 'Payment/PaymentProcessed/index.mdx',
+    slug: 'payment/paymentprocessed',
+    body: '',
+    collection: 'flows',
+    data: {
+      steps: [
+        {
+          id: 1,
+          type: 'node',
+          title: 'Order Placed',
+          next_step: 2,
+        },
+        {
+          id: 2,
+          title: 'Payment Initiated',
+          message: {
+            id: 'PaymentInitiated',
+            version: '0.0.1',
+          },
+          next_steps: [3, 4],
+        },
+        {
+          id: 3,
+          title: 'Payment Processed',
+          message: {
+            id: 'PaymentProcessed',
+            version: '0.0.1',
+          },
+        },
+        {
+          id: 4,
+          type: 'node',
+          title: 'Payment Failed',
+        },
+      ],
+      id: 'PaymentFlow',
+      name: 'Payment Flow for E-commerce',
+      summary: 'Business flow for processing payments in an e-commerce platform',
+      version: '1.0.0',
+      type: 'node',
+    },
+  },
+  {
+    id: 'Subscriptions/CancelSubscription/index.mdx',
+    slug: 'subscriptions/CancelSubscription',
+    body: '',
+    collection: 'flows',
+    data: {
+      steps: [
+        {
+          id: 'cancel_subscription_initiated',
+          title: 'Cancels Subscription',
+          actor: {
+            name: 'User',
+          },
+          next_step: {
+            id: 'cancel_subscription_request',
+            label: 'Initiate subscription cancellation',
+          },
+        },
+        {
+          id: 'cancel_subscription_request',
+          title: 'Cancel Subscription',
+          message: {
+            id: 'CancelSubscription',
+            version: '0.0.1',
+          },
+          next_step: {
+            id: 'subscription_service',
+            label: 'Proceed to subscription service',
+          },
+        },
+        {
+          id: 'subscription_service',
+          title: 'Subscription Service',
+          service: {
+            id: 'SubscriptionService',
+            version: 'latest',
+          },
+          next_steps: [
+            {
+              id: 'subscription_cancelled',
+              label: 'Successful cancellation',
+            },
+            {
+              id: 'subscription_rejected',
+              label: 'Failed cancellation',
+            },
+          ],
+        },
+        {
+          id: 'subscription_cancelled',
+          title: 'Subscription has been cancelled',
+          message: {
+            id: 'UserSubscriptionCancelled',
+            version: '0.0.1',
+          },
+        },
+        {
+          id: 'subscription_rejected',
+          title: 'Subscription cancellation has been rejected',
+        },
+      ],
+      id: 'CancelSubscription',
+      name: 'User Cancels Subscription',
+      summary: 'Flow for when a user has cancelled a subscription',
+      version: '1.0.0',
+      // type: 'node',
+    },
+  },
+];
diff --git a/packages/core/eventcatalog/src/utils/__tests__/containers/node-graph.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/containers/node-graph.spec.ts
new file mode 100644
index 000000000..f5303bc3f
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/containers/node-graph.spec.ts
@@ -0,0 +1,192 @@
+import { getNodesAndEdges } from '../../node-graphs/container-node-graph';
+import { expect, describe, it, vi, beforeEach } from 'vitest';
+import { mockContainers, mockServices, mockDataProducts } from './mocks';
+
+vi.mock('@utils/collections/containers', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('@utils/collections/containers')>()),
+    getContainers: () => Promise.resolve(mockContainers),
+  };
+});
+
+describe('Containers NodeGraph', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('getNodesAndEdges', () => {
+    it('should return the correct nodes and edges for a given container', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'OrderDatabase', version: '1.0.0' });
+
+      expect(nodes).toEqual([
+        {
+          id: 'SubscriptionService-0.0.1',
+          type: undefined,
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[0].data } }),
+          position: { x: 75, y: 60 },
+        },
+        {
+          id: 'OrderDatabase-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', data: { ...mockContainers[0].data } }),
+          position: { x: 525, y: 60 },
+          type: 'data',
+        },
+        {
+          id: 'SubscriptionService-0.0.1',
+          sourcePosition: 'left',
+          targetPosition: 'right',
+          data: expect.objectContaining({ title: 'SubscriptionService', mode: 'simple', service: { ...mockServices[0].data } }),
+          position: { x: 75, y: 60 },
+          type: undefined,
+        },
+      ]);
+
+      expect(edges).toEqual([
+        {
+          label: 'reads from \n (undefined)',
+          animated: false,
+          style: {
+            strokeWidth: 1,
+            stroke: 'var(--ec-edge-stroke, #6b7280)',
+          },
+          id: 'SubscriptionService-0.0.1-OrderDatabase-1.0.0',
+          source: 'OrderDatabase-1.0.0',
+          target: 'SubscriptionService-0.0.1',
+          data: {
+            service: {
+              id: 'SubscriptionService',
+              version: '0.0.1',
+              data: {
+                id: 'SubscriptionService',
+                version: '0.0.1',
+              },
+            },
+          },
+          type: 'multiline',
+          markerEnd: undefined,
+          markerStart: {
+            type: 'arrowclosed',
+            width: 20,
+            height: 20,
+          },
+        },
+        {
+          label: 'read and writes to \n (undefined)',
+          animated: false,
+          markerEnd: {
+            type: 'arrowclosed',
+            width: 20,
+            height: 20,
+          },
+          style: {
+            strokeWidth: 1,
+            stroke: 'var(--ec-edge-stroke, #6b7280)',
+          },
+          id: 'OrderDatabase-1.0.0-SubscriptionService-0.0.1-both',
+          source: 'SubscriptionService-0.0.1',
+          target: 'OrderDatabase-1.0.0',
+          type: 'multiline',
+          markerStart: {
+            type: 'arrowclosed',
+            width: 20,
+            height: 20,
+          },
+        },
+      ]);
+    });
+
+    it('returns empty nodes and edges if no container is found', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownContainer', version: '1.0.0' });
+
+      expect(nodes).toEqual([]);
+      expect(edges).toEqual([]);
+    });
+
+    describe('data products', () => {
+      it('should render data product nodes that write to the container', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'AnalyticsDatabase', version: '1.0.0' });
+
+        // Check for data product that writes to container
+        const dataProductWriteNode = nodes.find((n: any) => n.id === 'OrderDataPipeline-1.0.0');
+        expect(dataProductWriteNode).toBeDefined();
+        expect(dataProductWriteNode.type).toBe('data-products');
+        expect(dataProductWriteNode.data.dataProduct).toEqual(
+          expect.objectContaining({
+            id: 'OrderDataPipeline',
+            version: '1.0.0',
+          })
+        );
+
+        // Check for the edge
+        const writeEdge = edges.find(
+          (e: any) => e.source === 'OrderDataPipeline-1.0.0' && e.target === 'AnalyticsDatabase-1.0.0'
+        );
+        expect(writeEdge).toBeDefined();
+        expect(writeEdge.label).toBe('writes to');
+      });
+
+      it('should render data product nodes that read from the container', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'AnalyticsDatabase', version: '1.0.0' });
+
+        // Check for data product that reads from container
+        const dataProductReadNode = nodes.find((n: any) => n.id === 'OrderAnalytics-1.0.0');
+        expect(dataProductReadNode).toBeDefined();
+        expect(dataProductReadNode.type).toBe('data-products');
+        expect(dataProductReadNode.data.dataProduct).toEqual(
+          expect.objectContaining({
+            id: 'OrderAnalytics',
+            version: '1.0.0',
+          })
+        );
+
+        // Check for the edge
+        const readEdge = edges.find((e: any) => e.source === 'AnalyticsDatabase-1.0.0' && e.target === 'OrderAnalytics-1.0.0');
+        expect(readEdge).toBeDefined();
+        expect(readEdge.label).toContain('reads from');
+      });
+
+      it('should render both services and data products on the same container', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'SharedDatabase', version: '1.0.0' });
+
+        // Check for service that writes
+        const serviceNode = nodes.find((n: any) => n.id === 'PaymentService-0.0.1');
+        expect(serviceNode).toBeDefined();
+
+        // Check for data product that reads
+        const dataProductNode = nodes.find((n: any) => n.id === 'OrderAnalytics-1.0.0');
+        expect(dataProductNode).toBeDefined();
+        expect(dataProductNode.type).toBe('data-products');
+
+        // Check edges
+        const serviceWriteEdge = edges.find(
+          (e: any) => e.source === 'PaymentService-0.0.1' && e.target === 'SharedDatabase-1.0.0'
+        );
+        expect(serviceWriteEdge).toBeDefined();
+
+        const dataProductReadEdge = edges.find(
+          (e: any) => e.source === 'SharedDatabase-1.0.0' && e.target === 'OrderAnalytics-1.0.0'
+        );
+        expect(dataProductReadEdge).toBeDefined();
+      });
+
+      it('should render a data product that both reads and writes with a bidirectional edge', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'DataProductBothRW', version: '1.0.0' });
+
+        // Check for data product node (should only appear once despite being in both lists)
+        const dataProductNodes = nodes.filter((n: any) => n.id === 'OrderDataPipeline-1.0.0');
+        expect(dataProductNodes.length).toBeGreaterThanOrEqual(1);
+
+        // Check for the bidirectional edge
+        const bothEdge = edges.find((e: any) => e.id.includes('-both'));
+        expect(bothEdge).toBeDefined();
+        expect(bothEdge.label).toContain('read and writes to');
+        expect(bothEdge.markerStart).toBeDefined();
+        expect(bothEdge.markerEnd).toBeDefined();
+      });
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/data-products/mocks.ts b/packages/core/eventcatalog/src/utils/__tests__/data-products/mocks.ts
new file mode 100644
index 000000000..0e5009776
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/data-products/mocks.ts
@@ -0,0 +1,402 @@
+export const mockServices = [
+  {
+    id: 'services/Order/OrderService/index.mdx',
+    slug: 'services/Order/OrderService',
+    collection: 'services',
+    data: {
+      id: 'OrderService',
+      version: '1.0.0',
+      specifications: [
+        {
+          type: 'asyncapi',
+          path: 'asyncapi.yml',
+          name: 'AsyncAPI Custom Name',
+        },
+        {
+          type: 'openapi',
+          path: 'openapi.yml',
+          name: 'OpenAPI Custom Name',
+        },
+      ],
+      sends: [
+        {
+          id: 'OrderCreatedEvent',
+          version: '0.0.1',
+        },
+      ],
+      receives: [
+        {
+          id: 'PaymentProcessed',
+          version: '0.0.1',
+        },
+      ],
+      writesTo: [
+        {
+          id: 'OrderDatabase',
+          version: '1.0.0',
+        },
+      ],
+      readsFrom: [
+        {
+          id: 'PaymentDatabase',
+          version: '1.0.0',
+        },
+      ],
+    },
+  },
+  {
+    id: 'services/Inventory/InventoryService/index.mdx',
+    slug: 'services/Inventory/InventoryService',
+    collection: 'services',
+    data: {
+      id: 'InventoryService',
+      version: '1.0.0',
+      specifications: {
+        asyncapiPath: 'asyncapi.yml',
+        openapiPath: 'openapi.yml',
+      },
+      receives: [
+        {
+          id: 'OrderCreatedEvent',
+          version: '^1.3.0',
+        },
+      ],
+      sends: [
+        {
+          id: 'InventoryAdjusted',
+          version: '~2',
+        },
+      ],
+    },
+  },
+  {
+    id: 'services/Payment/PaymentService/index.mdx',
+    slug: 'services/Payment/PaymentService',
+    collection: 'services',
+    data: {
+      id: 'PaymentService',
+      version: '1.0.0',
+      receives: [
+        {
+          id: 'OrderCreatedEvent',
+        },
+        {
+          id: 'OrderDeletedEvent',
+          from: [
+            {
+              id: 'EmailChannel',
+              version: '1.0.0',
+            },
+          ],
+        },
+      ],
+      sends: [
+        {
+          id: 'PaymentPaid',
+          to: [
+            {
+              id: 'EmailChannel',
+              version: '1.0.0',
+            },
+          ],
+        },
+        {
+          id: 'PaymentFailed',
+          version: 'latest',
+        },
+        {
+          id: 'EmailVerified',
+          version: '1.0.0',
+        },
+      ],
+    },
+  },
+  {
+    id: 'services/Notifications/NotificationsService/index.mdx',
+    slug: 'services/Notifications/NotificationsService',
+    collection: 'services',
+    data: {
+      id: 'NotificationsService',
+      version: '1.0.0',
+      receives: [
+        {
+          id: 'OrderCreatedEvent',
+        },
+      ],
+      sends: [
+        {
+          id: 'OrderCreatedEvent',
+        },
+      ],
+    },
+  },
+  // Service that consumes OrderAnalyticsEvent (for testing data product outputs)
+  {
+    id: 'services/Analytics/AnalyticsService/index.mdx',
+    slug: 'services/Analytics/AnalyticsService',
+    collection: 'services',
+    data: {
+      id: 'AnalyticsService',
+      version: '1.0.0',
+      receives: [
+        {
+          id: 'OrderAnalyticsEvent',
+          version: '1.0.0',
+        },
+      ],
+    },
+  },
+  // Service as direct output from data product
+  {
+    id: 'services/Reporting/ReportingService/index.mdx',
+    slug: 'services/Reporting/ReportingService',
+    collection: 'services',
+    data: {
+      id: 'ReportingService',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockDataProducts = [
+  {
+    id: 'data-products/OrderDataProduct/index.mdx',
+    slug: 'data-products/OrderDataProduct',
+    collection: 'data-products',
+    data: {
+      id: 'OrderDataProduct',
+      version: '1.0.0',
+      inputs: [
+        {
+          id: 'OrderCreatedEvent',
+          version: '0.0.1',
+        },
+        {
+          id: 'InventoryService',
+        },
+        {
+          id: 'OrderDatabase',
+        },
+        {
+          id: 'EmailChannel',
+        },
+      ],
+      outputs: [
+        {
+          id: 'OrderAnalyticsEvent',
+          version: '1.0.0',
+        },
+        {
+          id: 'ReportingService',
+        },
+        {
+          id: 'PaymentDatabase',
+        },
+        {
+          id: 'OrderChannel',
+        },
+      ],
+    },
+  },
+];
+
+export const mockEvents = [
+  {
+    slug: 'OrderCreatedEvent',
+    collection: 'events',
+    data: {
+      id: 'OrderCreatedEvent',
+      version: '0.0.1',
+    },
+  },
+  {
+    slug: 'OrderCreatedEvent',
+    collection: 'events',
+    data: {
+      id: 'OrderCreatedEvent',
+      version: '1.0.0',
+    },
+  },
+  {
+    slug: 'OrderCreatedEvent',
+    collection: 'events',
+    data: {
+      id: 'OrderCreatedEvent',
+      version: '1.3.9',
+    },
+  },
+  {
+    slug: 'OrderCreatedEvent',
+    collection: 'events',
+    data: {
+      id: 'OrderCreatedEvent',
+      version: '2.0.0',
+    },
+  },
+  {
+    slug: 'OrderDeletedEvent',
+    collection: 'events',
+    data: {
+      id: 'OrderDeletedEvent',
+      version: '2.0.0',
+      channels: [
+        {
+          id: 'OrderChannel',
+          version: '1.0.0',
+        },
+      ],
+    },
+  },
+  {
+    slug: 'InventoryAdjusted',
+    collection: 'events',
+    data: {
+      id: 'InventoryAdjusted',
+      version: '0.0.1',
+    },
+  },
+  {
+    slug: 'InventoryAdjusted',
+    collection: 'events',
+    data: {
+      id: 'InventoryAdjusted',
+      version: '1.0.0',
+    },
+  },
+  {
+    slug: 'InventoryAdjusted',
+    collection: 'events',
+    data: {
+      id: 'InventoryAdjusted',
+      version: '2.0.0',
+    },
+  },
+  // 7
+  {
+    slug: 'PaymentPaid',
+    collection: 'events',
+    data: {
+      id: 'PaymentPaid',
+      version: '1.0.0',
+    },
+  },
+  // 9
+  {
+    slug: 'PaymentPaid',
+    collection: 'events',
+    data: {
+      id: 'PaymentPaid',
+      version: '2.0.0',
+    },
+  },
+  // 10
+  {
+    slug: 'PaymentFailed',
+    collection: 'events',
+    data: {
+      id: 'PaymentFailed',
+      version: '1.0.0',
+    },
+  },
+  // 11
+  {
+    slug: 'PaymentFailed',
+    collection: 'events',
+    data: {
+      id: 'PaymentFailed',
+      version: '1.2.3',
+    },
+  },
+  // 12
+  {
+    id: 'EmailVerified',
+    slug: 'EmailVerified',
+    collection: 'events',
+    data: {
+      id: 'EmailVerified',
+      version: '1.0.0',
+      channels: [
+        {
+          id: 'EmailChannel',
+          version: '1.0.0',
+        },
+      ],
+    },
+  },
+  // 13 - Event for data product output testing
+  {
+    slug: 'OrderAnalyticsEvent',
+    collection: 'events',
+    data: {
+      id: 'OrderAnalyticsEvent',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockCommands = [
+  {
+    slug: 'PaymentProcessed',
+    collection: 'commands',
+    data: {
+      id: 'PaymentProcessed',
+      version: '0.0.1',
+    },
+  },
+];
+export const mockQueries = [
+  {
+    slug: 'GetOrder',
+    collection: 'queries',
+    data: {
+      id: 'GetOrder',
+      version: '0.0.1',
+    },
+  },
+];
+
+export const mockContainers = [
+  {
+    id: 'OrderDatabase',
+    collection: 'containers',
+    data: {
+      id: 'OrderDatabase',
+      version: '1.0.0',
+    },
+  },
+  {
+    id: 'PaymentDatabase',
+    collection: 'containers',
+    data: {
+      id: 'PaymentDatabase',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockChannels = [
+  {
+    id: 'EmailChannel',
+    slug: 'EmailChannel',
+    collection: 'channels',
+    data: {
+      id: 'EmailChannel',
+      version: '1.0.0',
+      messages: [
+        {
+          id: 'OrderCreatedEvent',
+          version: '0.0.1',
+        },
+      ],
+    },
+  },
+  {
+    id: 'OrderChannel',
+    slug: 'OrderChannel',
+    collection: 'channels',
+    data: {
+      id: 'OrderChannel',
+      version: '1.0.0',
+    },
+  },
+];
diff --git a/packages/core/eventcatalog/src/utils/__tests__/data-products/node-graph.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/data-products/node-graph.spec.ts
new file mode 100644
index 000000000..be28a573c
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/data-products/node-graph.spec.ts
@@ -0,0 +1,699 @@
+import { MarkerType } from '@xyflow/react';
+import { getNodesAndEdges } from '../../node-graphs/data-products-node-graph';
+import { expect, describe, it, vi, beforeEach } from 'vitest';
+import { mockCommands, mockEvents, mockQueries, mockServices, mockChannels, mockContainers, mockDataProducts } from './mocks';
+import type { CollectionKey } from 'astro:content';
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    // this will only affect "foo" outside of the original module
+    getCollection: (key: CollectionKey) => {
+      switch (key) {
+        case 'data-products':
+          return Promise.resolve(mockDataProducts);
+        case 'services':
+          return Promise.resolve(mockServices);
+        case 'channels':
+          return Promise.resolve(mockChannels);
+        case 'events':
+          return Promise.resolve(mockEvents);
+        case 'commands':
+          return Promise.resolve(mockCommands);
+        case 'queries':
+          return Promise.resolve(mockQueries);
+        case 'containers':
+          return Promise.resolve(mockContainers);
+      }
+    },
+  };
+});
+
+describe('Data Products NodeGraph', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('getNodesAndEdges', () => {
+    describe('input (input ports)', () => {
+      it('should return nodes and edges for messages and their producers when they are a data products inputs', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'OrderDataProduct', version: '1.0.0' });
+
+        // The middle node itself, the data product
+        const expectedDataProductNode = {
+          id: 'OrderDataProduct-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', dataProduct: { ...mockDataProducts[0].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          type: 'data-products',
+        };
+
+        // An Event as an input to the data store
+        const expectedInputNode = {
+          id: 'OrderCreatedEvent-0.0.1',
+          type: 'events',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', message: { ...mockEvents[0].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        const expectedProducerOfInputNode = {
+          id: 'OrderService-1.0.0',
+          type: 'services',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[0].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        const expectedEdges = expect.arrayContaining([
+          // The message directly to the data product
+          expect.objectContaining({
+            label: 'input',
+            animated: false,
+            id: 'OrderCreatedEvent-0.0.1-OrderDataProduct-1.0.0',
+            source: 'OrderCreatedEvent-0.0.1',
+            target: 'OrderDataProduct-1.0.0',
+          }),
+          // The producer of the message to the data product
+          expect.objectContaining({
+            id: 'OrderService-1.0.0-OrderCreatedEvent-0.0.1',
+            source: 'OrderService-1.0.0',
+            target: 'OrderCreatedEvent-0.0.1',
+            label: 'publishes \nevent',
+            animated: false,
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            // Nodes on the left (inputs)
+            expect.objectContaining(expectedInputNode),
+            expect.objectContaining(expectedProducerOfInputNode),
+
+            // The data product node itself
+            expect.objectContaining(expectedDataProductNode),
+          ])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+
+      it('should return nodes and edges for services that are a direct input to the data product', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'OrderDataProduct', version: '1.0.0' });
+
+        // The middle node itself, the data product
+        const expectedDataProductNode = {
+          id: 'OrderDataProduct-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', dataProduct: { ...mockDataProducts[0].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          type: 'data-products',
+        };
+
+        // The Service as an input to the data product (InventoryService is in mockDataProducts inputs)
+        const expectedInputNode = {
+          id: 'InventoryService-1.0.0',
+          type: 'services',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[1].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        const expectedEdges = expect.arrayContaining([
+          // The service directly to the data product
+          expect.objectContaining({
+            label: 'input',
+            id: 'InventoryService-1.0.0-OrderDataProduct-1.0.0',
+            source: 'InventoryService-1.0.0',
+            target: 'OrderDataProduct-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            // Nodes on the left (inputs)
+            expect.objectContaining(expectedInputNode),
+
+            // The data product node itself
+            expect.objectContaining(expectedDataProductNode),
+          ])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+
+      it('should return nodes and edges for containers that are a direct input to the data product', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'OrderDataProduct', version: '1.0.0' });
+
+        // The middle node itself, the data product
+        const expectedDataProductNode = {
+          id: 'OrderDataProduct-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', dataProduct: { ...mockDataProducts[0].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          type: 'data-products',
+        };
+
+        // The Service as an input to the data product
+        const expectedInputNode = {
+          id: 'OrderDatabase-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', data: { ...mockContainers[0].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          // @ts-ignore
+          type: 'data' as any,
+        };
+
+        const expectedEdges = expect.arrayContaining([
+          // The service directly to the data product
+          expect.objectContaining({
+            label: 'input',
+            animated: false,
+            id: 'OrderDatabase-1.0.0-OrderDataProduct-1.0.0',
+            source: 'OrderDatabase-1.0.0',
+            target: 'OrderDataProduct-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            // Nodes on the left (inputs)
+            expect.objectContaining(expectedInputNode),
+
+            // The data product node itself
+            expect.objectContaining(expectedDataProductNode),
+          ])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+
+      it('should return nodes and edges for channels that are a direct input to the data product', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'OrderDataProduct', version: '1.0.0' });
+
+        // The middle node itself, the data product
+        const expectedDataProductNode = {
+          id: 'OrderDataProduct-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', dataProduct: { ...mockDataProducts[0].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          type: 'data-products',
+        };
+
+        // The Channel as an input to the data product (EmailChannel is mockChannels[0])
+        const expectedInputNode = {
+          id: 'EmailChannel-1.0.0',
+          type: 'channels',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', channel: { ...mockChannels[0].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        const expectedEdges = expect.arrayContaining([
+          // The channel directly to the data product
+          expect.objectContaining({
+            label: 'input',
+            id: 'EmailChannel-1.0.0-OrderDataProduct-1.0.0',
+            source: 'EmailChannel-1.0.0',
+            target: 'OrderDataProduct-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            // Nodes on the left (inputs)
+            expect.objectContaining(expectedInputNode),
+
+            // The data product node itself
+            expect.objectContaining(expectedDataProductNode),
+          ])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+    });
+
+    describe('output (output ports)', () => {
+      it('should return nodes and edges for output messages from the data product', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'OrderDataProduct', version: '1.0.0' });
+
+        // The middle node itself, the data product
+        const expectedDataProductNode = {
+          id: 'OrderDataProduct-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', dataProduct: { ...mockDataProducts[0].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          type: 'data-products',
+        };
+
+        // An Event as an output from the data product
+        const expectedOutputNode = {
+          id: 'OrderAnalyticsEvent-1.0.0',
+          type: 'events',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', message: { ...mockEvents[13].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        const expectedEdges = expect.arrayContaining([
+          // The data product to the output message
+          expect.objectContaining({
+            label: 'output',
+            animated: false,
+            id: 'OrderDataProduct-1.0.0-OrderAnalyticsEvent-1.0.0',
+            source: 'OrderDataProduct-1.0.0',
+            target: 'OrderAnalyticsEvent-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            // The data product node itself
+            expect.objectContaining(expectedDataProductNode),
+
+            // Nodes on the right (outputs)
+            expect.objectContaining(expectedOutputNode),
+          ])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+
+      it('should return nodes and edges for services that are a direct output from the data product', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'OrderDataProduct', version: '1.0.0' });
+
+        // The middle node itself, the data product
+        const expectedDataProductNode = {
+          id: 'OrderDataProduct-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', dataProduct: { ...mockDataProducts[0].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          type: 'data-products',
+        };
+
+        // The Service as an output from the data product (ReportingService is mockServices[5])
+        const expectedOutputNode = {
+          id: 'ReportingService-1.0.0',
+          type: 'services',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[5].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        const expectedEdges = expect.arrayContaining([
+          // The data product directly to the service
+          expect.objectContaining({
+            label: 'output',
+            id: 'OrderDataProduct-1.0.0-ReportingService-1.0.0',
+            source: 'OrderDataProduct-1.0.0',
+            target: 'ReportingService-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            // Nodes on the right (outputs)
+            expect.objectContaining(expectedOutputNode),
+
+            // The data product node itself
+            expect.objectContaining(expectedDataProductNode),
+          ])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+
+      it('should return nodes and edges for containers that are a direct output from the data product', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'OrderDataProduct', version: '1.0.0' });
+
+        // The middle node itself, the data product
+        const expectedDataProductNode = {
+          id: 'OrderDataProduct-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', dataProduct: { ...mockDataProducts[0].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          type: 'data-products',
+        };
+
+        // The Container as an output from the data product (PaymentDatabase is mockContainers[1])
+        const expectedOutputNode = {
+          id: 'PaymentDatabase-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', data: { ...mockContainers[1].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          type: 'data' as any,
+        };
+
+        const expectedEdges = expect.arrayContaining([
+          // The data product directly to the container
+          expect.objectContaining({
+            label: 'output',
+            id: 'OrderDataProduct-1.0.0-PaymentDatabase-1.0.0',
+            source: 'OrderDataProduct-1.0.0',
+            target: 'PaymentDatabase-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            // Nodes on the right (outputs)
+            expect.objectContaining(expectedOutputNode),
+
+            // The data product node itself
+            expect.objectContaining(expectedDataProductNode),
+          ])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+
+      it('should return nodes and edges for channels that are a direct output from the data product', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'OrderDataProduct', version: '1.0.0' });
+
+        // The middle node itself, the data product
+        const expectedDataProductNode = {
+          id: 'OrderDataProduct-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', dataProduct: { ...mockDataProducts[0].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          type: 'data-products',
+        };
+
+        // The Channel as an output from the data product (OrderChannel is mockChannels[1])
+        const expectedOutputNode = {
+          id: 'OrderChannel-1.0.0',
+          type: 'channels',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({ mode: 'simple', channel: { ...mockChannels[1].data } }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        const expectedEdges = expect.arrayContaining([
+          // The data product directly to the channel
+          expect.objectContaining({
+            label: 'output',
+            id: 'OrderDataProduct-1.0.0-OrderChannel-1.0.0',
+            source: 'OrderDataProduct-1.0.0',
+            target: 'OrderChannel-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            // Nodes on the right (outputs)
+            expect.objectContaining(expectedOutputNode),
+
+            // The data product node itself
+            expect.objectContaining(expectedDataProductNode),
+          ])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+    });
+
+    // it('if a message is sent and received by the same service it will render a custom edge', async () => {
+    //   const { nodes, edges } = await getNodesAndEdges({ id: 'NotificationsService', version: '1.0.0' });
+
+    //   // The middle node itself, the service
+    //   const expectedServiceNode = {
+    //     id: 'NotificationsService-1.0.0',
+    //     sourcePosition: 'right',
+    //     targetPosition: 'left',
+    //     data: { mode: 'simple', service: { ...mockServices[3].data } },
+    //     position: { x: expect.any(Number), y: expect.any(Number) },
+    //     type: 'services',
+    //   };
+
+    //   // Nodes coming into the service (left)
+    //   const expectedRecivesNode = {
+    //     id: 'OrderCreatedEvent-2.0.0',
+    //     type: 'events',
+    //     sourcePosition: 'right',
+    //     targetPosition: 'left',
+    //     data: { mode: 'simple', message: { ...mockEvents[3].data } },
+    //     position: { x: expect.any(Number), y: expect.any(Number) },
+    //   };
+
+    //   // Nodes going out of the service (right)
+    //   const expectedSendsNode = {
+    //     id: 'OrderCreatedEvent-2.0.0',
+    //     sourcePosition: 'right',
+    //     targetPosition: 'left',
+    //     data: { mode: 'simple', message: { ...mockEvents[3].data } },
+    //     position: { x: expect.any(Number), y: expect.any(Number) },
+    //     type: 'events',
+    //   };
+
+    //   const expectedEdges = expect.arrayContaining([
+    //     expect.objectContaining({
+    //       id: 'OrderCreatedEvent-2.0.0-NotificationsService-1.0.0',
+    //       source: 'OrderCreatedEvent-2.0.0',
+    //       target: 'NotificationsService-1.0.0',
+    //     }),
+    //     expect.objectContaining({
+    //       id: 'NotificationsService-1.0.0-OrderCreatedEvent-2.0.0',
+    //       source: 'NotificationsService-1.0.0',
+    //       target: 'OrderCreatedEvent-2.0.0',
+    //     }),
+    //     expect.objectContaining({
+    //       id: 'NotificationsService-1.0.0-OrderCreatedEvent-2.0.0-both',
+    //       source: 'NotificationsService-1.0.0',
+    //       target: 'OrderCreatedEvent-2.0.0',
+    //     }),
+    //   ]);
+
+    //   expect(nodes).toEqual(
+    //     expect.arrayContaining([
+    //       // Nodes on the left
+    //       expect.objectContaining(expectedRecivesNode),
+
+    //       // The service node itself
+    //       expect.objectContaining(expectedServiceNode),
+
+    //       // Nodes on the right
+    //       expect.objectContaining(expectedSendsNode),
+    //     ])
+    //   );
+
+    //   expect(edges).toEqual(expectedEdges);
+    // });
+
+    // it('returns empty nodes and edges if no service is found', async () => {
+    //   const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownService', version: '1.0.0' });
+
+    //   expect(nodes).toEqual([]);
+    //   expect(edges).toEqual([]);
+    // });
+
+    // it('should return nodes and edges for a given service using semver range', async () => {
+    //   const { nodes, edges } = await getNodesAndEdges({ id: 'InventoryService', version: '1.0.0' });
+
+    //   // The middle node itself, the service
+    //   const expectedServiceNode = {
+    //     id: 'InventoryService-1.0.0',
+    //     sourcePosition: 'right',
+    //     targetPosition: 'left',
+    //     data: { mode: 'simple', service: { ...mockServices[1].data } },
+    //     position: { x: expect.any(Number), y: expect.any(Number) },
+    //     type: 'services',
+    //   };
+
+    //   // Nodes coming into the service (left)
+    //   const expectedRecivesNode = {
+    //     id: 'OrderCreatedEvent-1.3.9',
+    //     type: 'events',
+    //     sourcePosition: 'right',
+    //     targetPosition: 'left',
+    //     data: { mode: 'simple', message: { ...mockEvents[2].data } },
+    //     position: { x: expect.any(Number), y: expect.any(Number) },
+    //   };
+
+    //   // Nodes going out of the service (right)
+    //   const expectedSendsNode = {
+    //     id: 'InventoryAdjusted-2.0.0',
+    //     sourcePosition: 'right',
+    //     targetPosition: 'left',
+    //     data: { mode: 'simple', message: { ...mockEvents[7].data } },
+    //     position: { x: expect.any(Number), y: expect.any(Number) },
+    //     type: 'events',
+    //   };
+
+    //   const expectedEdges = expect.arrayContaining([
+    //     expect.objectContaining({
+    //       id: 'OrderCreatedEvent-1.3.9-InventoryService-1.0.0',
+    //       source: 'OrderCreatedEvent-1.3.9',
+    //       target: 'InventoryService-1.0.0',
+    //     }),
+    //     expect.objectContaining({
+    //       id: 'InventoryService-1.0.0-InventoryAdjusted-2.0.0',
+    //       source: 'InventoryService-1.0.0',
+    //       target: 'InventoryAdjusted-2.0.0',
+    //     }),
+    //   ]);
+
+    //   expect(nodes).toEqual(
+    //     expect.arrayContaining([
+    //       // Nodes on the left
+    //       expect.objectContaining(expectedRecivesNode),
+
+    //       // The service node itself
+    //       expect.objectContaining(expectedServiceNode),
+
+    //       // Nodes on the right
+    //       expect.objectContaining(expectedSendsNode),
+    //     ])
+    //   );
+
+    //   expect(edges).toEqual(expectedEdges);
+    // });
+
+    // it('creates a channel node between the service and message if the service defined a channel', async () => {
+    //   const { nodes, edges } = await getNodesAndEdges({ id: 'PaymentService', version: '1.0.0' });
+
+    //   // The middle node itself, the service
+    //   const expectedServiceNode = {
+    //     id: 'PaymentService-1.0.0',
+    //     sourcePosition: 'right',
+    //     targetPosition: 'left',
+    //     data: { mode: 'simple', service: { ...mockServices[2].data } },
+    //     position: { x: expect.any(Number), y: expect.any(Number) },
+    //     type: 'services',
+    //   };
+
+    //   const expectedConsumedMessageWithoutChannel = {
+    //     id: 'OrderCreatedEvent-2.0.0',
+    //     type: 'events',
+    //     sourcePosition: 'right',
+    //     targetPosition: 'left',
+    //     data: { mode: 'simple', message: expect.anything() },
+    //     position: { x: expect.any(Number), y: expect.any(Number) },
+    //   };
+
+    //   const expectedConsumedMessageWithChannel = {
+    //     id: 'OrderDeletedEvent-2.0.0',
+    //     type: 'events',
+    //     sourcePosition: 'right',
+    //     targetPosition: 'left',
+    //     data: { mode: 'simple', message: expect.anything() },
+    //     position: { x: expect.any(Number), y: expect.any(Number) },
+    //   };
+
+    //   const expectedChannelNode = {
+    //     id: 'EmailChannel-1.0.0',
+    //     type: 'channels',
+    //     sourcePosition: 'right',
+    //     targetPosition: 'left',
+    //     data: { mode: 'simple', channel: expect.anything() },
+    //     position: { x: expect.any(Number), y: expect.any(Number) },
+    //   };
+
+    //   // Message coming into the service with a channel
+    //   const expectedProducedMessage = {
+    //     id: 'PaymentPaid-2.0.0',
+    //     type: 'events',
+    //     sourcePosition: 'right',
+    //     targetPosition: 'left',
+    //     data: { mode: 'simple', message: expect.anything() },
+    //     position: { x: expect.any(Number), y: expect.any(Number) },
+    //   };
+
+    //   // Message coming into the service with a channel
+    //   const expectedChannelAfterProducedMessage = {
+    //     id: 'EmailChannel-1.0.0',
+    //     type: 'channels',
+    //     sourcePosition: 'right',
+    //     targetPosition: 'left',
+    //     data: { mode: 'simple', channel: expect.anything() },
+    //     position: { x: expect.any(Number), y: expect.any(Number) },
+    //   };
+
+    //   const expectedEdges = expect.arrayContaining([
+    //     // The service to the message (it publishes)
+    //     expect.objectContaining({
+    //       id: 'PaymentService-1.0.0-PaymentPaid-2.0.0',
+    //       source: 'PaymentService-1.0.0',
+    //       target: 'PaymentPaid-2.0.0',
+    //     }),
+    //     // The Message to the channel defined by the producing service
+    //     expect.objectContaining({
+    //       id: 'PaymentPaid-2.0.0-EmailChannel-1.0.0',
+    //       source: 'PaymentPaid-2.0.0',
+    //       target: 'EmailChannel-1.0.0',
+    //     }),
+
+    //     // The consumed message with no channel defined
+    //     // We expect to to connect to the service
+    //     expect.objectContaining({
+    //       id: 'OrderCreatedEvent-2.0.0-PaymentService-1.0.0',
+    //       source: 'OrderCreatedEvent-2.0.0',
+    //       target: 'PaymentService-1.0.0',
+    //     }),
+
+    //     // The consume message with a channel defined
+    //     expect.objectContaining({
+    //       id: 'OrderDeletedEvent-2.0.0-EmailChannel-1.0.0',
+    //       source: 'OrderDeletedEvent-2.0.0',
+    //       target: 'EmailChannel-1.0.0',
+    //     }),
+    //   ]);
+
+    //   expect(nodes).toEqual(
+    //     expect.arrayContaining([
+    //       // message the service consumes
+    //       expect.objectContaining(expectedConsumedMessageWithoutChannel),
+
+    //       // message the service consumes with a channel
+    //       expect.objectContaining(expectedConsumedMessageWithChannel),
+
+    //       // The channel node
+    //       expect.objectContaining(expectedChannelNode),
+
+    //       // The service node itself
+    //       expect.objectContaining(expectedServiceNode),
+
+    //       // message on the right of the service
+    //       expect.objectContaining(expectedProducedMessage),
+
+    //       expect.objectContaining(expectedChannelAfterProducedMessage),
+    //     ])
+    //   );
+
+    //   expect(edges).toEqual(expectedEdges);
+    // });
+
+    // it('when `renderMessages` is false it should not render any messages or channels', async () => {
+    //   const { nodes } = await getNodesAndEdges({ id: 'PaymentService', version: '1.0.0', renderMessages: false });
+
+    //   const hasMessages = nodes.some((node) => node.type === 'events' || node.type === 'commands' || node.type === 'queries');
+    //   const hasChannels = nodes.some((node) => node.type === 'channels');
+
+    //   expect(hasMessages).toBe(false);
+    //   expect(hasChannels).toBe(false);
+    // });
+
+    // it('will render any container (data) that the service writes to or reads from', async () => {
+    //   const { nodes } = await getNodesAndEdges({ id: 'OrderService', version: '1.0.0' });
+
+    //   const hasContainers = nodes.some((node) => node.type === 'data');
+    //   expect(hasContainers).toBe(true);
+    // });
+  });
+});
diff --git a/eventcatalog/src/utils/__tests__/domains/domain-entity-map.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/domains/domain-entity-map.spec.ts
similarity index 83%
rename from eventcatalog/src/utils/__tests__/domains/domain-entity-map.spec.ts
rename to packages/core/eventcatalog/src/utils/__tests__/domains/domain-entity-map.spec.ts
index 0c6333924..25189819b 100644
--- a/eventcatalog/src/utils/__tests__/domains/domain-entity-map.spec.ts
+++ b/packages/core/eventcatalog/src/utils/__tests__/domains/domain-entity-map.spec.ts
@@ -2,7 +2,7 @@ import { MarkerType } from '@xyflow/react';
 import { getNodesAndEdges } from '../../node-graphs/domain-entity-map';
 import { expect, describe, it, vi, beforeEach } from 'vitest';
 import { getCollection, getEntry } from 'astro:content';
-import type { ContentCollectionKey } from 'astro:content';
+import type { CollectionKey } from 'astro:content';
 
 // Mock entities for testing
 const mockEntities = [
@@ -156,6 +156,79 @@ const mockEntities = [
       ],
     },
   },
+  // Warehouse entity with array item reference but no explicit references field
+  {
+    id: 'entities/Warehouse/index.mdx',
+    slug: 'entities/Warehouse',
+    collection: 'entities',
+    data: {
+      id: 'Warehouse',
+      name: 'Warehouse',
+      version: '1.0.0',
+      identifier: 'warehouseId',
+      properties: [
+        {
+          name: 'warehouseId',
+          type: 'UUID',
+          required: true,
+        },
+        {
+          name: 'bins',
+          type: 'array',
+          required: false,
+          items: {
+            type: 'Bin',
+          },
+        },
+      ],
+    },
+  },
+  // Product entity with an array of primitives
+  {
+    id: 'entities/Product/index.mdx',
+    slug: 'entities/Product',
+    collection: 'entities',
+    data: {
+      id: 'Product',
+      name: 'Product',
+      version: '1.0.0',
+      identifier: 'productId',
+      properties: [
+        {
+          name: 'productId',
+          type: 'UUID',
+          required: true,
+        },
+        {
+          name: 'imageUrls',
+          type: 'array',
+          required: false,
+          items: {
+            type: 'string',
+          },
+        },
+      ],
+    },
+  },
+  // Bin entity referenced by Warehouse.bins
+  {
+    id: 'entities/Bin/index.mdx',
+    slug: 'entities/Bin',
+    collection: 'entities',
+    data: {
+      id: 'Bin',
+      name: 'Bin',
+      version: '1.0.0',
+      identifier: 'binId',
+      properties: [
+        {
+          name: 'binId',
+          type: 'UUID',
+          required: true,
+        },
+      ],
+    },
+  },
   // Versioned Order entity
   {
     id: 'entities/Order/versioned/200/index.mdx',
@@ -227,6 +300,21 @@ const mockDomains = [
       version: '1.0.0',
     },
   },
+  // Domain with an entity that references another entity via array items.type only
+  {
+    id: 'domains/Warehousing-1.0.0',
+    slug: 'domains/Warehousing',
+    collection: 'domains',
+    data: {
+      id: 'Warehousing',
+      name: 'Warehousing',
+      version: '1.0.0',
+      entities: [
+        { id: 'Warehouse', version: '1.0.0' },
+        { id: 'Product', version: '1.0.0' },
+      ],
+    },
+  },
 ];
 
 const mockServices = [
@@ -245,7 +333,7 @@ const mockServices = [
 vi.mock('astro:content', async (importOriginal) => {
   return {
     ...(await importOriginal<typeof import('astro:content')>()),
-    getCollection: (key: ContentCollectionKey) => {
+    getCollection: (key: CollectionKey) => {
       switch (key) {
         case 'domains':
           return Promise.resolve(mockDomains);
@@ -257,7 +345,7 @@ vi.mock('astro:content', async (importOriginal) => {
           return Promise.resolve([]);
       }
     },
-    getEntry: (collection: ContentCollectionKey, id: string) => {
+    getEntry: (collection: CollectionKey, id: string) => {
       if (collection === 'domains') {
         return Promise.resolve(mockDomains.find((d) => d.id === `domains/${id}`));
       }
@@ -337,13 +425,11 @@ describe('Domain Entity Map NodeGraph', () => {
         label: 'hasOne',
         style: {
           strokeWidth: 2,
-          stroke: '#000',
         },
         markerEnd: {
           type: MarkerType.ArrowClosed,
           width: 20,
           height: 20,
-          color: '#000',
         },
       });
 
@@ -443,6 +529,41 @@ describe('Domain Entity Map NodeGraph', () => {
       });
     });
 
+    it('creates a hasMany edge for array item entity types without explicit references', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'Warehousing', version: '1.0.0' });
+
+      const warehouseNode = nodes.find((n: any) => n.data.entity.data.id === 'Warehouse');
+      const binNode = nodes.find((n: any) => n.data.entity.data.id === 'Bin');
+      const warehouseToBinEdge = edges.find((e: any) => e.source === 'Warehouse-1.0.0' && e.target === 'Bin-1.0.0');
+
+      expect(warehouseNode).toBeDefined();
+      expect(binNode).toMatchObject({
+        id: 'Bin-1.0.0',
+        type: 'entities',
+        data: {
+          label: 'Bin',
+          externalToDomain: true,
+        },
+      });
+      expect(warehouseToBinEdge).toMatchObject({
+        sourceHandle: 'bins-source',
+        targetHandle: 'binId-target',
+        label: 'hasMany',
+      });
+    });
+
+    it('does not create relationships for arrays of primitive types', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'Warehousing', version: '1.0.0' });
+
+      const productNode = nodes.find((n: any) => n.data.entity.data.id === 'Product');
+      const stringNode = nodes.find((n: any) => n.data.entity.data.id === 'string');
+      const productEdges = edges.filter((e: any) => e.source === 'Product-1.0.0' || e.target === 'Product-1.0.0');
+
+      expect(productNode).toBeDefined();
+      expect(stringNode).toBeUndefined();
+      expect(productEdges).toHaveLength(0);
+    });
+
     it('returns empty nodes and edges for domain with no entities', async () => {
       const { nodes, edges } = await getNodesAndEdges({ id: 'Empty', version: '1.0.0' });
 
diff --git a/eventcatalog/src/utils/__tests__/domains/domains-canvas.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/domains/domains-canvas.spec.ts
similarity index 98%
rename from eventcatalog/src/utils/__tests__/domains/domains-canvas.spec.ts
rename to packages/core/eventcatalog/src/utils/__tests__/domains/domains-canvas.spec.ts
index d7120f44b..6eca25e42 100644
--- a/eventcatalog/src/utils/__tests__/domains/domains-canvas.spec.ts
+++ b/packages/core/eventcatalog/src/utils/__tests__/domains/domains-canvas.spec.ts
@@ -1,4 +1,4 @@
-import type { ContentCollectionKey } from 'astro:content';
+import type { CollectionKey } from 'astro:content';
 import { expect, describe, it, vi } from 'vitest';
 import { getDomainsCanvasData } from '@utils/node-graphs/domains-canvas';
 import { MarkerType } from '@xyflow/react';
@@ -135,7 +135,7 @@ const mockEvents = [
 vi.mock('astro:content', async (importOriginal) => {
   return {
     ...(await importOriginal<typeof import('astro:content')>()),
-    getCollection: (key: ContentCollectionKey) => {
+    getCollection: (key: CollectionKey) => {
       switch (key) {
         case 'services':
           return Promise.resolve(mockAllServices);
@@ -221,8 +221,8 @@ describe('Domains Canvas', () => {
         expect(edge.animated).toBe(true);
         expect(edge.markerEnd).toMatchObject({
           type: MarkerType.ArrowClosed,
-          width: 40,
-          height: 40,
+          width: 20,
+          height: 20,
         });
       });
 
diff --git a/packages/core/eventcatalog/src/utils/__tests__/domains/domains.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/domains/domains.spec.ts
new file mode 100644
index 000000000..e07852d34
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/domains/domains.spec.ts
@@ -0,0 +1,371 @@
+import type { CollectionKey } from 'astro:content';
+import { expect, describe, it, vi } from 'vitest';
+import {
+  mockDomains,
+  mockServices,
+  mockEvents,
+  mockCommands,
+  mockUbiquitousLanguages,
+  mockDataProducts,
+  mockSystems,
+} from './mocks';
+import {
+  domainHasEntities,
+  getDomains,
+  getDomainsForService,
+  getParentDomains,
+  hasUbiquitousLanguageTermsWithSubdomains,
+  getUbiquitousLanguage,
+  getUbiquitousLanguageWithSubdomains,
+} from '../../collections/domains';
+import type { Service } from '@utils/collections/services';
+import type { Domain } from '@utils/collections/domains';
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    // this will only affect "foo" outside of the original module
+    getCollection: (key: CollectionKey, filter?: any) => {
+      switch (key) {
+        case 'domains':
+          return Promise.resolve(mockDomains);
+        case 'services':
+          return Promise.resolve(mockServices);
+        case 'events':
+          return Promise.resolve(mockEvents);
+        case 'commands':
+          return Promise.resolve(mockCommands);
+        case 'data-products':
+          return Promise.resolve(mockDataProducts);
+        case 'systems':
+          return Promise.resolve(mockSystems);
+        case 'ubiquitousLanguages':
+          let result = mockUbiquitousLanguages;
+          if (filter) {
+            result = mockUbiquitousLanguages.filter(filter);
+          }
+          return Promise.resolve(result);
+        default:
+          return Promise.resolve([]);
+      }
+    },
+  };
+});
+
+describe('Domains', () => {
+  describe('getDomains', () => {
+    it('should returns an array of domains with services using semver or latest', async () => {
+      const domains = await getDomains();
+
+      const expectedDomains = [
+        // Checkout
+        {
+          ...mockDomains[1],
+          data: expect.objectContaining({ services: [mockServices[2], mockServices[3]] }),
+        },
+        // Notification
+        {
+          ...mockDomains[2],
+          data: expect.objectContaining({ services: [] }),
+        },
+      ];
+
+      expect(domains).toEqual(expect.arrayContaining(expectedDomains.map((d) => expect.objectContaining(d))));
+    });
+
+    it('resolves a domains referenced systems and hydrates their services', async () => {
+      const domains = await getDomains();
+      const logistics = domains.find((d) => d.data.id === 'Logistics');
+
+      const systems = (logistics?.data as any).systems;
+      expect(systems).toHaveLength(1);
+      expect(systems[0].data.id).toEqual('FulfilmentSystem');
+
+      // The system's service pointers are hydrated into full service entries
+      expect(systems[0].data.services).toEqual([
+        expect.objectContaining({ data: expect.objectContaining({ id: 'LocationService' }) }),
+      ]);
+    });
+  });
+
+  describe('ubiquitous-language', () => {
+    it('should return the ubiquitous-language for a domain', async () => {
+      const domains = await getDomains();
+      const shippingDomain = domains.find((d) => d.data.id === 'Shipping');
+      const ubiquitousLanguages = await getUbiquitousLanguage(shippingDomain!);
+      expect(ubiquitousLanguages).toEqual([
+        {
+          id: 'domains/Shipping/ubiquitous-language.mdx',
+          slug: 'domains/Shipping/ubiquitous-language',
+          collection: 'ubiquitousLanguages',
+          filePath: 'domains/Shipping/ubiquitous-language.mdx',
+          data: {
+            id: 'Shipping',
+            dictionary: [
+              {
+                id: 'Payment',
+                name: 'Payment',
+                summary: 'A financial transaction',
+              },
+              {
+                id: 'Order',
+                name: 'Order',
+                summary: 'A customer purchase request',
+              },
+            ],
+          },
+        },
+      ]);
+    });
+  });
+
+  describe('getDomainsForService', () => {
+    it('should return the domains for a service', async () => {
+      const domains = await getDomainsForService(mockServices[0] as unknown as Service);
+      const expectedDomain = mockDomains[0];
+      expect(domains[0].data.id).toEqual(expectedDomain.data.id);
+      expect(domains[0].data.services).toEqual(expect.arrayContaining([mockServices[0]]));
+    });
+
+    it('returns an empty array if the service is not found', async () => {
+      const domains = await getDomainsForService(mockServices[4] as unknown as Service);
+      expect(domains).toEqual([]);
+    });
+  });
+
+  describe('getParentDomains', () => {
+    it('should return the parent domains for a domain', async () => {
+      const checkoutDomain = mockDomains.find((d) => d.data.id === 'Checkout');
+      const domains = await getParentDomains(checkoutDomain as unknown as Domain);
+      const expectedDomain = mockDomains.find((d) => d.data.id === 'Shipping');
+      expect(domains.length).toBeGreaterThan(0);
+      expect(domains[0].data.id).toEqual(expectedDomain!.data.id);
+      // The domains array will contain the processed subdomain objects, not the original mock
+      //@ts-ignore
+      expect(domains[0].data.domains.some((d: any) => d.data.id === 'Checkout')).toBe(true);
+    });
+
+    it('returns an empty array if the domain is not found', async () => {
+      const notificationDomain = mockDomains.find((d) => d.data.id === 'Notification');
+      const domains = await getParentDomains(notificationDomain as unknown as Domain);
+      expect(domains).toEqual([]);
+    });
+  });
+
+  describe('getUbiquitousLanguageWithSubdomains', () => {
+    it('should return domain ubiquitous language with subdomain languages', async () => {
+      const domains = await getDomains();
+      const shippingDomain = domains.find((d) => d.data.id === 'Shipping');
+
+      const result = await getUbiquitousLanguageWithSubdomains(shippingDomain as Domain);
+
+      expect(result.domain).toEqual({
+        id: 'domains/Shipping/ubiquitous-language.mdx',
+        slug: 'domains/Shipping/ubiquitous-language',
+        collection: 'ubiquitousLanguages',
+        filePath: 'domains/Shipping/ubiquitous-language.mdx',
+        data: {
+          id: 'Shipping',
+          dictionary: [
+            { id: 'Payment', name: 'Payment', summary: 'A financial transaction' },
+            { id: 'Order', name: 'Order', summary: 'A customer purchase request' },
+          ],
+        },
+      });
+
+      expect(result.subdomains).toHaveLength(1);
+      expect(result.subdomains[0].subdomain.data.id).toBe('Checkout');
+      expect(result.subdomains[0].ubiquitousLanguage).toEqual({
+        id: 'domains/Checkout/ubiquitous-language.mdx',
+        slug: 'domains/Checkout/ubiquitous-language',
+        collection: 'ubiquitousLanguages',
+        filePath: 'domains/Checkout/ubiquitous-language.mdx',
+        data: {
+          id: 'Checkout',
+          dictionary: [
+            { id: 'Payment', name: 'Payment', summary: 'Processing customer payment' },
+            { id: 'Cart', name: 'Cart', summary: 'Shopping cart items' },
+          ],
+        },
+      });
+    });
+
+    it('should detect duplicate terms across domain and subdomains', async () => {
+      const domains = await getDomains();
+      const shippingDomain = domains.find((d) => d.data.id === 'Shipping');
+
+      const result = await getUbiquitousLanguageWithSubdomains(shippingDomain as Domain);
+
+      // Payment appears in both Shipping domain and Checkout subdomain, so should be a duplicate
+      expect(result.duplicateTerms).toContain('payment');
+      // Order only appears in Shipping domain, Cart only in Checkout - neither should be duplicates
+      expect(result.duplicateTerms).not.toContain('order');
+      expect(result.duplicateTerms).not.toContain('cart');
+    });
+
+    it('should handle domain with no ubiquitous language', async () => {
+      const domains = await getDomains();
+      const notificationDomain = domains.find((d) => d.data.id === 'Notification');
+
+      const result = await getUbiquitousLanguageWithSubdomains(notificationDomain as Domain);
+
+      expect(result.domain).toEqual({
+        id: 'domains/Notification/ubiquitous-language.mdx',
+        slug: 'domains/Notification/ubiquitous-language',
+        collection: 'ubiquitousLanguages',
+        filePath: 'domains/Notification/ubiquitous-language.mdx',
+        data: {
+          id: 'Notification',
+          dictionary: [{ id: 'Email', name: 'Email', summary: 'Electronic mail notification' }],
+        },
+      });
+      expect(result.subdomains).toHaveLength(0);
+      expect(result.duplicateTerms.size).toBe(0);
+    });
+
+    it('should handle domain with subdomains but no ubiquitous language for subdomains', async () => {
+      const domains = await getDomains();
+      const checkoutDomain = domains.find((d) => d.data.id === 'Checkout');
+
+      const result = await getUbiquitousLanguageWithSubdomains(checkoutDomain as Domain);
+
+      expect(result.domain).toEqual({
+        id: 'domains/Checkout/ubiquitous-language.mdx',
+        slug: 'domains/Checkout/ubiquitous-language',
+        collection: 'ubiquitousLanguages',
+        filePath: 'domains/Checkout/ubiquitous-language.mdx',
+        data: {
+          id: 'Checkout',
+          dictionary: [
+            { id: 'Payment', name: 'Payment', summary: 'Processing customer payment' },
+            { id: 'Cart', name: 'Cart', summary: 'Shopping cart items' },
+          ],
+        },
+      });
+      expect(result.subdomains).toHaveLength(0);
+      expect(result.duplicateTerms.size).toBe(0);
+    });
+
+    it('should return empty result when domain has no ubiquitous language and no subdomains', async () => {
+      const mockDomainWithoutLanguage = {
+        id: 'domains/Empty/index.mdx',
+        filePath: 'domains/Empty/index.mdx',
+        data: {
+          id: 'Empty',
+          name: 'Empty',
+          version: '0.0.1',
+          domains: [],
+        },
+      };
+
+      //@ts-ignore
+      const result = await getUbiquitousLanguageWithSubdomains(mockDomainWithoutLanguage as Domain);
+
+      expect(result.domain).toBeNull();
+      expect(result.subdomains).toHaveLength(0);
+      expect(result.duplicateTerms.size).toBe(0);
+    });
+
+    it('should return true when a domain has ubiquitous language terms', async () => {
+      const domains = await getDomains();
+      const shippingDomain = domains.find((d) => d.data.id === 'Shipping');
+
+      const result = await hasUbiquitousLanguageTermsWithSubdomains(shippingDomain as Domain);
+
+      expect(result).toBe(true);
+    });
+
+    it('should return true when a subdomain has ubiquitous language terms', async () => {
+      const checkoutDomain = mockDomains.find((d) => d.data.id === 'Checkout') as unknown as Domain;
+      const mockDomainWithSubdomainLanguage = {
+        id: 'domains/Parent/index.mdx',
+        collection: 'domains',
+        filePath: 'domains/Parent/index.mdx',
+        data: {
+          id: 'Parent',
+          name: 'Parent',
+          version: '0.0.1',
+          domains: [checkoutDomain],
+        },
+      };
+
+      const result = await hasUbiquitousLanguageTermsWithSubdomains(mockDomainWithSubdomainLanguage as unknown as Domain);
+
+      expect(result).toBe(true);
+    });
+
+    it('should return false when a domain and its subdomains have no ubiquitous language terms', async () => {
+      const mockDomainWithoutLanguage = {
+        id: 'domains/Empty/index.mdx',
+        collection: 'domains',
+        filePath: 'domains/Empty/index.mdx',
+        data: {
+          id: 'Empty',
+          name: 'Empty',
+          version: '0.0.1',
+          domains: [],
+        },
+      };
+
+      const result = await hasUbiquitousLanguageTermsWithSubdomains(mockDomainWithoutLanguage as unknown as Domain);
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('domainHasEntities', () => {
+    it('should return true if the domain has entities', async () => {
+      const domains = await getDomains();
+      domains[0].data.entities = [{ id: 'Order', version: '1.0.0' }];
+      expect(domainHasEntities(domains[0])).toBe(true);
+    });
+
+    it('should return false if the domain has no entities', async () => {
+      const domains = await getDomains();
+      expect(domainHasEntities(domains[1])).toBe(false);
+    });
+  });
+
+  describe('data products', () => {
+    it('should hydrate data products for the main domain', async () => {
+      const domains = await getDomains();
+      const shippingDomain = domains.find((d) => d.data.id === 'Shipping');
+
+      expect(shippingDomain).toBeDefined();
+      const dataProducts = shippingDomain!.data['data-products'] as any[];
+      expect(dataProducts).toBeDefined();
+      expect(dataProducts.length).toBe(1);
+      expect(dataProducts[0].data.id).toBe('ShippingAnalytics');
+      expect(dataProducts[0].data.version).toBe('1.0.0');
+    });
+
+    it('should hydrate data products for subdomains', async () => {
+      const domains = await getDomains();
+      const shippingDomain = domains.find((d) => d.data.id === 'Shipping');
+
+      expect(shippingDomain).toBeDefined();
+      const subdomains = shippingDomain!.data.domains as any[];
+      expect(subdomains).toBeDefined();
+      expect(subdomains.length).toBeGreaterThan(0);
+
+      // Checkout is a subdomain of Shipping with data products
+      const checkoutSubdomain = subdomains.find((sd: any) => sd.data.id === 'Checkout');
+      expect(checkoutSubdomain).toBeDefined();
+
+      const subdomainDataProducts = checkoutSubdomain.data['data-products'] as any[];
+      expect(subdomainDataProducts).toBeDefined();
+      expect(subdomainDataProducts.length).toBe(1);
+      expect(subdomainDataProducts[0].data.id).toBe('CheckoutAnalytics');
+      expect(subdomainDataProducts[0].data.version).toBe('1.0.0');
+      expect(subdomainDataProducts[0].data.name).toBe('Checkout Analytics');
+    });
+
+    it('should return empty array when domain has no data products', async () => {
+      const domains = await getDomains();
+      const notificationDomain = domains.find((d) => d.data.id === 'Notification');
+
+      expect(notificationDomain).toBeDefined();
+      const dataProducts = notificationDomain!.data['data-products'] as any[];
+      expect(dataProducts).toEqual([]);
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/domains/mocks.ts b/packages/core/eventcatalog/src/utils/__tests__/domains/mocks.ts
new file mode 100644
index 000000000..55559275a
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/domains/mocks.ts
@@ -0,0 +1,355 @@
+export const mockDomains = [
+  {
+    id: 'domains/Shipping/index.mdx',
+    slug: 'domains/Shipping',
+    collection: 'domains',
+    filePath: 'domains/Shipping/index.mdx',
+    data: {
+      id: 'Shipping',
+      name: 'Shipping',
+      version: '0.0.1',
+      services: [{ id: 'LocationService', version: '0.0.1' }],
+      domains: [{ id: 'Checkout', version: '0.0.1' }],
+      entities: [{ id: 'Shipment', version: '0.0.1' }],
+      'data-products': [{ id: 'ShippingAnalytics', version: '1.0.0' }],
+    },
+  },
+  {
+    id: 'domains/Checkout/index.mdx',
+    slug: 'domains/Checkout',
+    collection: 'domains',
+    filePath: 'domains/Checkout/index.mdx',
+    data: {
+      id: 'Checkout',
+      name: 'Checkout',
+      version: '0.0.1',
+      services: [{ id: 'OrderService' /* version: latest */ }, { id: 'PaymentService', version: '0.0.1' }],
+      'data-products': [{ id: 'CheckoutAnalytics', version: '1.0.0' }],
+    },
+  },
+  {
+    id: 'domains/Notification/index.mdx',
+    slug: 'domains/Notification',
+    collection: 'domains',
+    filePath: 'domains/Notification/index.mdx',
+    data: {
+      id: 'Notification',
+      name: 'Notification',
+      version: '0.0.1',
+      services: [{ id: 'MailService' }],
+    },
+  },
+  {
+    id: 'domains/Automation/index.mdx',
+    slug: 'domains/Automation',
+    collection: 'domains',
+    filePath: 'domains/Automation/index.mdx',
+    data: {
+      id: 'Automation',
+      name: 'Automation',
+      version: '0.0.1',
+      agents: [{ id: 'FraudReviewAgent', version: '1.0.0' }],
+    },
+  },
+  {
+    id: 'domains/Logistics/index.mdx',
+    slug: 'domains/Logistics',
+    collection: 'domains',
+    filePath: 'domains/Logistics/index.mdx',
+    data: {
+      id: 'Logistics',
+      name: 'Logistics',
+      version: '0.0.1',
+      systems: [{ id: 'FulfilmentSystem', version: '1.0.0' }],
+    },
+  },
+];
+
+export const mockSystems = [
+  {
+    id: 'systems/FulfilmentSystem/index.mdx',
+    slug: 'systems/FulfilmentSystem',
+    collection: 'systems',
+    filePath: 'systems/FulfilmentSystem/index.mdx',
+    data: {
+      id: 'FulfilmentSystem',
+      name: 'Fulfilment System',
+      version: '1.0.0',
+      services: [{ id: 'LocationService', version: '0.0.1' }],
+    },
+  },
+];
+
+export const mockServices = [
+  {
+    id: 'services/LocationService/index.mdx',
+    slug: 'services/LocationService',
+    collection: 'services',
+    data: {
+      id: 'LocationService',
+      version: '0.0.1',
+      receives: [{ id: 'OrderPlaced', version: '0.0.1' }],
+    },
+  },
+  {
+    id: 'services/OrderService/versioned/001/index.mdx',
+    slug: 'services/OrderService/versioned/001',
+    collection: 'services',
+    data: {
+      id: 'OrderService',
+      version: '0.0.1',
+      receives: [{ id: 'PlaceOrder', version: '>1.5.0' }],
+      sends: [{ id: 'OrderPlaced', version: '0.0.1' }],
+    },
+  },
+  {
+    id: 'services/OrderService/index.mdx',
+    slug: 'services/OrderService',
+    collection: 'services',
+    data: {
+      id: 'OrderService',
+      version: '1.0.0',
+      receives: [{ id: 'PlaceOrder', version: '>1.5.0' }],
+      sends: [{ id: 'OrderPlaced', version: '0.0.1' }],
+    },
+  },
+  {
+    id: 'services/PaymentService/index.mdx',
+    slug: 'services/PaymentService',
+    collection: 'services',
+    data: {
+      id: 'PaymentService',
+      version: '0.0.1',
+      receives: [{ id: 'OrderPlaced' }],
+      sends: [{ id: 'PaymentPaid', version: 'x' }, { id: 'PaymentRefunded' }, { id: 'PaymentFailed', version: '^1.0.0' }],
+    },
+  },
+  {
+    id: 'services/ServiceWithoutDomains/index.mdx',
+    slug: 'services/ServiceWithoutDomains',
+    collection: 'services',
+    data: {
+      id: 'ServiceWithoutDomains',
+      version: '0.0.1',
+    },
+  },
+];
+
+export const mockAgents = [
+  {
+    id: 'agents/FraudReviewAgent/index.mdx',
+    slug: 'agents/FraudReviewAgent',
+    collection: 'agents',
+    data: {
+      id: 'FraudReviewAgent',
+      name: 'Fraud Review Agent',
+      version: '1.0.0',
+      tools: [
+        {
+          name: 'Risk profile lookup',
+          type: 'mcp',
+          icon: '/icons/tools/datadog.svg',
+          url: 'https://mcp.example.com/fraud/risk-profile',
+          description: 'Looks up fraud and payment risk signals.',
+        },
+      ],
+      receives: [{ id: 'OrderPlaced', version: '0.0.1' }],
+      sends: [{ id: 'PaymentFailed', version: '^1.0.0' }],
+    },
+  },
+];
+
+export const mockCommands = [
+  // PlaceOrder
+  {
+    id: 'commands/PlaceOrder/versioned/100/index.mdx',
+    slug: 'commands/PlaceOrder/versoined/100',
+    collection: 'commands',
+    data: {
+      id: 'PlaceOrder',
+      version: '1.0.0',
+    },
+  },
+  {
+    id: 'commands/PlaceOrder/versioned/150/index.mdx',
+    slug: 'commands/PlaceOrder/versoined/150',
+    collection: 'commands',
+    data: {
+      id: 'PlaceOrder',
+      version: '1.5.0',
+    },
+  },
+  {
+    id: 'commands/PlaceOrder/versioned/177/index.mdx',
+    slug: 'commands/PlaceOrder/versoined/177',
+    collection: 'commands',
+    data: {
+      id: 'PlaceOrder',
+      version: '1.7.7',
+    },
+  },
+];
+
+export const mockEvents = [
+  // OrderPlaced
+  {
+    id: 'events/OrderPlaced/index.mdx',
+    slug: 'events/OrderPlaced',
+    collection: 'events',
+    data: {
+      id: 'OrderPlaced',
+      version: '0.0.1',
+    },
+  },
+
+  // PaymentPaid
+  {
+    id: 'events/PaymentPaid/versioned/001/index.mdx',
+    slug: 'events/PaymentPaid/versioned/001',
+    collection: 'events',
+    data: {
+      id: 'PaymentPaid',
+      version: '0.0.1',
+    },
+  },
+  {
+    id: 'events/PaymentPaid/index.mdx',
+    slug: 'events/PaymentPaid',
+    collection: 'events',
+    data: {
+      id: 'PaymentPaid',
+      version: '0.0.2',
+    },
+  },
+
+  // PaymentRefunded
+  {
+    id: 'events/PaymentRefunded/index.mdx',
+    slug: 'events/PaymentRefunded',
+    collection: 'events',
+    data: {
+      id: 'PaymentRefunded',
+      version: '0.0.1',
+    },
+  },
+  {
+    id: 'events/PaymentRefunded/index.mdx',
+    slug: 'events/PaymentRefunded',
+    collection: 'events',
+    data: {
+      id: 'PaymentRefunded',
+      version: '1.0.0',
+    },
+  },
+
+  // PaymentFailed
+  {
+    id: 'events/PaymentFailed/index.mdx',
+    slug: 'events/PaymentFailed',
+    collection: 'events',
+    data: {
+      id: 'PaymentFailed',
+      version: '0.0.1',
+    },
+  },
+  {
+    id: 'events/PaymentFailed/index.mdx',
+    slug: 'events/PaymentFailed',
+    collection: 'events',
+    data: {
+      id: 'PaymentFailed',
+      version: '1.0.0',
+    },
+  },
+  {
+    id: 'events/PaymentFailed/index.mdx',
+    slug: 'events/PaymentFailed',
+    collection: 'events',
+    data: {
+      id: 'PaymentFailed',
+      version: '2.0.0',
+    },
+  },
+  // ShippingMetricsCalculated - output from data product
+  {
+    id: 'events/ShippingMetricsCalculated/index.mdx',
+    slug: 'events/ShippingMetricsCalculated',
+    collection: 'events',
+    data: {
+      id: 'ShippingMetricsCalculated',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockDataProducts = [
+  {
+    id: 'data-products/ShippingAnalytics/index.mdx',
+    slug: 'data-products/ShippingAnalytics',
+    collection: 'data-products',
+    data: {
+      id: 'ShippingAnalytics',
+      version: '1.0.0',
+      inputs: [{ id: 'OrderPlaced', version: '0.0.1' }],
+      outputs: [{ id: 'ShippingMetricsCalculated', version: '1.0.0' }],
+    },
+  },
+  {
+    id: 'data-products/CheckoutAnalytics/index.mdx',
+    slug: 'data-products/CheckoutAnalytics',
+    collection: 'data-products',
+    data: {
+      id: 'CheckoutAnalytics',
+      version: '1.0.0',
+      name: 'Checkout Analytics',
+      summary: 'Analytics for checkout flow',
+      inputs: [{ id: 'OrderPlaced', version: '0.0.1' }],
+      outputs: [
+        {
+          id: 'PaymentPaid',
+          version: '0.0.1',
+          contract: { path: 'contract.yaml', name: 'Checkout Contract', type: 'odcs' },
+        },
+      ],
+    },
+  },
+];
+
+export const mockUbiquitousLanguages = [
+  {
+    id: 'domains/Shipping/ubiquitous-language.mdx',
+    slug: 'domains/Shipping/ubiquitous-language',
+    collection: 'ubiquitousLanguages',
+    filePath: 'domains/Shipping/ubiquitous-language.mdx',
+    data: {
+      id: 'Shipping',
+      dictionary: [
+        { id: 'Payment', name: 'Payment', summary: 'A financial transaction' },
+        { id: 'Order', name: 'Order', summary: 'A customer purchase request' },
+      ],
+    },
+  },
+  {
+    id: 'domains/Checkout/ubiquitous-language.mdx',
+    slug: 'domains/Checkout/ubiquitous-language',
+    collection: 'ubiquitousLanguages',
+    filePath: 'domains/Checkout/ubiquitous-language.mdx',
+    data: {
+      id: 'Checkout',
+      dictionary: [
+        { id: 'Payment', name: 'Payment', summary: 'Processing customer payment' },
+        { id: 'Cart', name: 'Cart', summary: 'Shopping cart items' },
+      ],
+    },
+  },
+  {
+    id: 'domains/Notification/ubiquitous-language.mdx',
+    slug: 'domains/Notification/ubiquitous-language',
+    collection: 'ubiquitousLanguages',
+    filePath: 'domains/Notification/ubiquitous-language.mdx',
+    data: {
+      id: 'Notification',
+      dictionary: [{ id: 'Email', name: 'Email', summary: 'Electronic mail notification' }],
+    },
+  },
+];
diff --git a/packages/core/eventcatalog/src/utils/__tests__/domains/node-graph.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/domains/node-graph.spec.ts
new file mode 100644
index 000000000..1198eff93
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/domains/node-graph.spec.ts
@@ -0,0 +1,335 @@
+import type { CollectionKey } from 'astro:content';
+import { expect, describe, it, vi } from 'vitest';
+import { mockAgents, mockDomains, mockServices, mockEvents, mockCommands, mockDataProducts, mockSystems } from './mocks';
+import { getNodesAndEdges } from '@utils/node-graphs/domains-node-graph';
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    // this will only affect "foo" outside of the original module
+    getCollection: (key: CollectionKey) => {
+      switch (key) {
+        case 'domains':
+          return Promise.resolve(mockDomains);
+        case 'services':
+          return Promise.resolve(mockServices);
+        case 'agents':
+          return Promise.resolve(mockAgents);
+        case 'events':
+          return Promise.resolve(mockEvents);
+        case 'commands':
+          return Promise.resolve(mockCommands);
+        case 'data-products':
+          return Promise.resolve(mockDataProducts);
+        case 'systems':
+          return Promise.resolve(mockSystems);
+        case 'queries':
+        case 'containers':
+        case 'channels':
+          return Promise.resolve([]);
+        default:
+          return Promise.resolve([]);
+      }
+    },
+  };
+});
+
+describe('Domains NodeGraph', () => {
+  describe('getNodesAndEdges', () => {
+    it('returns an empty array if no domains are found', async () => {
+      // @ts-ignore
+      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownDomain', version: '1.0.0' });
+
+      expect(nodes).toEqual([]);
+      expect(edges).toEqual([]);
+    });
+
+    it('should return nodes and edges for a given domain', async () => {
+      // @ts-ignore
+      const { nodes, edges } = await getNodesAndEdges({ id: 'Shipping', version: '0.0.1' });
+
+      const expectedServiceNode = {
+        id: 'LocationService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[0].data }, group: expect.anything() }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedEventNode = {
+        id: 'OrderPlaced-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({
+          mode: 'simple',
+          message: { ...mockEvents[0].data },
+          group: {
+            type: 'Domain',
+            value: 'Checkout',
+            id: 'Checkout',
+          },
+        }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'events',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        expect.objectContaining({
+          id: 'OrderPlaced-0.0.1-LocationService-0.0.1',
+          source: 'OrderPlaced-0.0.1',
+          target: 'LocationService-0.0.1',
+          label: 'subscribed by',
+          animated: false,
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedEventNode),
+
+          // The command node itself
+          expect.objectContaining(expectedServiceNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('should return a list of nodes and edges with a domain has subdomains', async () => {
+      // @ts-ignore
+      const { nodes, edges } = await getNodesAndEdges({ id: 'Shipping', version: '0.0.1' });
+
+      // Expect the orders service to be rendered (it's a service in a subdomain)
+      const expectedEventNode = {
+        id: 'OrderService-1.0.0',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({
+          mode: 'simple',
+          service: expect.objectContaining({
+            id: 'OrderService',
+            version: '1.0.0',
+          }),
+          group: {
+            type: 'Domain',
+            value: 'Checkout',
+            id: 'Checkout',
+          },
+        }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      expect(nodes).toEqual(expect.arrayContaining([expect.objectContaining(expectedEventNode)]));
+
+      // 9 original nodes + 2 from data product (ShippingAnalytics + ShippingMetricsCalculated) + agent consumer + agent tool
+      expect(nodes.length).toEqual(15);
+      // 8 original edges + 2 from data product (input edge + output edge) + agent consumer edge + agent → tool edge
+      expect(edges.length).toEqual(14);
+    });
+
+    it('does not pull a referenced system (or its services) into the domain resource graph', async () => {
+      // The domain Resource Diagram renders the domain's own resources (services,
+      // agents, data products, subdomains) — not the services that belong to systems
+      // the domain references. Logistics only references FulfilmentSystem, so its
+      // resource graph should be empty.
+      // @ts-ignore
+      const { nodes } = await getNodesAndEdges({ id: 'Logistics', version: '0.0.1' });
+
+      expect(nodes.find((node: any) => node.id === 'LocationService-0.0.1')).toBeUndefined();
+      expect(nodes).toEqual([]);
+    });
+
+    it('should return nodes and edges for data products in a domain', async () => {
+      // @ts-ignore
+      const { nodes, edges } = await getNodesAndEdges({ id: 'Shipping', version: '0.0.1' });
+
+      // Expect the data product node to be rendered (no group property since it's the top-level domain)
+      const expectedDataProductNode = {
+        id: 'ShippingAnalytics-1.0.0',
+        type: 'data-products',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({
+          mode: 'simple',
+          dataProduct: expect.objectContaining({
+            id: 'ShippingAnalytics',
+            version: '1.0.0',
+          }),
+        }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      // Expect the output event from the data product to be rendered
+      const expectedOutputEventNode = {
+        id: 'ShippingMetricsCalculated-1.0.0',
+        type: 'events',
+        data: expect.objectContaining({
+          mode: 'simple',
+          message: expect.objectContaining({
+            id: 'ShippingMetricsCalculated',
+            version: '1.0.0',
+          }),
+        }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      expect(nodes).toEqual(expect.arrayContaining([expect.objectContaining(expectedDataProductNode)]));
+      expect(nodes).toEqual(expect.arrayContaining([expect.objectContaining(expectedOutputEventNode)]));
+
+      // Verify edges exist between data product and its inputs/outputs
+      const dataProductInputEdge = edges.find(
+        (e: any) => e.source === 'OrderPlaced-0.0.1' && e.target === 'ShippingAnalytics-1.0.0'
+      );
+      const dataProductOutputEdge = edges.find(
+        (e: any) => e.source === 'ShippingAnalytics-1.0.0' && e.target === 'ShippingMetricsCalculated-1.0.0'
+      );
+
+      expect(dataProductInputEdge).toBeDefined();
+      expect(dataProductOutputEdge).toBeDefined();
+    });
+
+    it('should return nodes and edges for agents in a domain', async () => {
+      // @ts-ignore
+      const { nodes, edges } = await getNodesAndEdges({ id: 'Automation', version: '0.0.1' });
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            id: 'FraudReviewAgent-1.0.0',
+            type: 'agents',
+            data: expect.objectContaining({
+              mode: 'simple',
+              agent: expect.objectContaining({
+                id: 'FraudReviewAgent',
+                version: '1.0.0',
+              }),
+            }),
+            position: { x: expect.any(Number), y: expect.any(Number) },
+          }),
+          expect.objectContaining({
+            id: 'OrderPlaced-0.0.1',
+            type: 'events',
+            data: expect.objectContaining({ message: expect.objectContaining({ id: 'OrderPlaced' }) }),
+          }),
+          expect.objectContaining({
+            id: 'FraudReviewAgent-1.0.0-tool-risk-profile-lookup-mcp',
+            type: 'agentTool',
+            data: expect.objectContaining({
+              agentTool: expect.objectContaining({
+                name: 'Risk profile lookup',
+                type: 'mcp',
+                icon: '/icons/tools/datadog.svg',
+              }),
+            }),
+          }),
+        ])
+      );
+
+      expect(edges).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            id: 'OrderPlaced-0.0.1-FraudReviewAgent-1.0.0',
+            source: 'OrderPlaced-0.0.1',
+            target: 'FraudReviewAgent-1.0.0',
+          }),
+          expect.objectContaining({
+            id: 'FraudReviewAgent-1.0.0-PaymentFailed-1.0.0',
+            source: 'FraudReviewAgent-1.0.0',
+            target: 'PaymentFailed-1.0.0',
+          }),
+          expect.objectContaining({
+            id: 'FraudReviewAgent-1.0.0-FraudReviewAgent-1.0.0-tool-risk-profile-lookup-mcp',
+            source: 'FraudReviewAgent-1.0.0',
+            target: 'FraudReviewAgent-1.0.0-tool-risk-profile-lookup-mcp',
+            label: 'calls tool',
+            type: 'step',
+          }),
+        ])
+      );
+    });
+
+    // it.only('should return nodes and edges for a given domain with services using semver range or latest version (version undefind)', async () => {
+    //   // @ts-ignore
+    //   const { nodes, edges } = await getNodesAndEdges({ id: 'Checkout', version: '0.0.1' });
+
+    //   const expectedNodes = [
+    //     {
+    //       id: 'PlaceOrder-1.7.7',
+    //       sourcePosition: 'right',
+    //       targetPosition: 'left',
+    //       data: { mode: 'simple', message: { ...mockCommands[2].data } },
+    //       position: { x: expect.any(Number), y: expect.any(Number) },
+    //       type: 'commands',
+    //     },
+    //     {
+    //       id: 'OrderService-1.0.0',
+    //       sourcePosition: 'right',
+    //       targetPosition: 'left',
+    //       data: {
+    //         mode: 'simple',
+    //         service: { ...mockServices[2].data },
+    //       },
+    //       position: expect.anything(),
+    //       type: 'services',
+    //     },
+    //     {
+    //       id: 'OrderPlaced-0.0.1',
+    //       sourcePosition: 'right',
+    //       targetPosition: 'left',
+    //       data: { mode: 'simple', message: { ...mockEvents[0].data } },
+    //       position: expect.anything(),
+    //       type: 'events',
+    //     },
+    //     /** PAYMENT SERVICE */
+    //     {
+    //       id: 'PaymentService-0.0.1',
+    //       sourcePosition: 'right',
+    //       targetPosition: 'left',
+    //       data: {
+    //         mode: 'simple',
+    //         service: { ...mockServices[3].data },
+    //       },
+    //       position: expect.anything(),
+    //       type: 'services',
+    //     },
+    //     {
+    //       id: 'PaymentPaid-0.0.1',
+    //       sourcePosition: 'right',
+    //       targetPosition: 'left',
+    //       data: { mode: 'simple', message: { ...mockEvents[1].data } },
+    //       position: expect.anything(),
+    //       type: 'events',
+    //     },
+    //     {
+    //       id: 'PaymentPaid-0.0.2',
+    //       sourcePosition: 'right',
+    //       targetPosition: 'left',
+    //       data: { mode: 'simple', message: { ...mockEvents[2].data } },
+    //       position: expect.anything(),
+    //       type: 'events',
+    //     },
+    //     {
+    //       id: 'PaymentRefunded-1.0.0',
+    //       sourcePosition: 'right',
+    //       targetPosition: 'left',
+    //       data: { mode: 'simple', message: { ...mockEvents[4].data } },
+    //       position: expect.anything(),
+    //       type: 'events',
+    //     },
+    //     {
+    //       id: 'PaymentFailed-1.0.0',
+    //       sourcePosition: 'right',
+    //       targetPosition: 'left',
+    //       data: { mode: 'simple', message: { ...mockEvents[6].data } },
+    //       position: expect.anything(),
+    //       type: 'events',
+    //     },
+    //   ];
+
+    //   expect(nodes).toStrictEqual(expect.arrayContaining(expectedNodes.map((n) => expect.objectContaining(n))));
+    // });
+  });
+});
diff --git a/eventcatalog/src/utils/__tests__/entities/entities.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/entities/entities.spec.ts
similarity index 88%
rename from eventcatalog/src/utils/__tests__/entities/entities.spec.ts
rename to packages/core/eventcatalog/src/utils/__tests__/entities/entities.spec.ts
index 6ad8eaf05..ce2c6a802 100644
--- a/eventcatalog/src/utils/__tests__/entities/entities.spec.ts
+++ b/packages/core/eventcatalog/src/utils/__tests__/entities/entities.spec.ts
@@ -1,13 +1,13 @@
-import type { ContentCollectionKey } from 'astro:content';
+import type { CollectionKey } from 'astro:content';
 import { expect, describe, it, vi } from 'vitest';
 import { mockServices, mockEntities, mockDomains } from './mocks';
-import { getEntities } from '@utils/entities';
+import { getEntities } from '@utils/collections/entities';
 
 vi.mock('astro:content', async (importOriginal) => {
   return {
     ...(await importOriginal<typeof import('astro:content')>()),
     // this will only affect "foo" outside of the original module
-    getCollection: (key: ContentCollectionKey) => {
+    getCollection: (key: CollectionKey) => {
       switch (key) {
         case 'services':
           return Promise.resolve(mockServices);
diff --git a/eventcatalog/src/utils/__tests__/entities/mocks.ts b/packages/core/eventcatalog/src/utils/__tests__/entities/mocks.ts
similarity index 100%
rename from eventcatalog/src/utils/__tests__/entities/mocks.ts
rename to packages/core/eventcatalog/src/utils/__tests__/entities/mocks.ts
diff --git a/packages/core/eventcatalog/src/utils/__tests__/eventcatalog-config/api-general.test.ts b/packages/core/eventcatalog/src/utils/__tests__/eventcatalog-config/api-general.test.ts
new file mode 100644
index 000000000..8c6277422
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/eventcatalog-config/api-general.test.ts
@@ -0,0 +1,130 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Mock the writer module so tests don't touch the real filesystem.
+vi.mock('@utils/eventcatalog-config/config-writer', () => {
+  return {
+    readConfigSource: vi.fn(),
+    applyConfigUpdate: vi.fn(),
+    writeConfigUpdate: vi.fn(),
+  };
+});
+
+import { POST } from '../../../pages/api/settings/general';
+import { readConfigSource, applyConfigUpdate, writeConfigUpdate } from '@utils/eventcatalog-config/config-writer';
+
+const ORIGINAL_DEV_MODE = process.env.EVENTCATALOG_DEV_MODE;
+
+const buildRequest = (body: unknown): Request =>
+  new Request('http://localhost/api/settings/general', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: typeof body === 'string' ? body : JSON.stringify(body),
+  });
+
+const callPost = async (req: Request): Promise<Response> => {
+  // Astro's APIRoute signature passes a context object; the handler only reads `request`.
+  return (await (POST as any)({ request: req })) as Response;
+};
+
+describe('POST /api/settings/general', () => {
+  beforeEach(() => {
+    vi.mocked(readConfigSource).mockReturnValue("export default { title: 'old' };");
+    vi.mocked(applyConfigUpdate).mockReturnValue("export default { title: 'new' };");
+    vi.mocked(writeConfigUpdate).mockReturnValue("export default { title: 'new' };");
+  });
+
+  afterEach(() => {
+    if (ORIGINAL_DEV_MODE === undefined) delete process.env.EVENTCATALOG_DEV_MODE;
+    else process.env.EVENTCATALOG_DEV_MODE = ORIGINAL_DEV_MODE;
+    vi.clearAllMocks();
+  });
+
+  it('writes the config and returns 200 in dev mode', async () => {
+    process.env.EVENTCATALOG_DEV_MODE = 'true';
+    const res = await callPost(buildRequest({ title: 'New Title', theme: 'default' }));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.ok).toBe(true);
+    expect(body.settings.title).toBe('New Title');
+    expect(writeConfigUpdate).toHaveBeenCalledOnce();
+  });
+
+  it('returns 403 when not in dev mode and does not write', async () => {
+    delete process.env.EVENTCATALOG_DEV_MODE;
+    const res = await callPost(buildRequest({ title: 'New Title', theme: 'default' }));
+    expect(res.status).toBe(403);
+    expect(writeConfigUpdate).not.toHaveBeenCalled();
+  });
+
+  it('returns 400 for invalid JSON body and does not write', async () => {
+    process.env.EVENTCATALOG_DEV_MODE = 'true';
+    const res = await callPost(buildRequest('not-json'));
+    expect(res.status).toBe(400);
+    expect(writeConfigUpdate).not.toHaveBeenCalled();
+  });
+
+  it('returns 400 when title is missing and does not write', async () => {
+    process.env.EVENTCATALOG_DEV_MODE = 'true';
+    const res = await callPost(buildRequest({ theme: 'default' }));
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toBe('Validation failed');
+    expect(writeConfigUpdate).not.toHaveBeenCalled();
+  });
+
+  it('returns 400 when homepageLink is not a valid URL', async () => {
+    process.env.EVENTCATALOG_DEV_MODE = 'true';
+    const res = await callPost(buildRequest({ title: 'X', theme: 'default', homepageLink: 'not-a-url' }));
+    expect(res.status).toBe(400);
+    expect(writeConfigUpdate).not.toHaveBeenCalled();
+  });
+
+  it('returns 500 with sensible error when the config file cannot be read', async () => {
+    process.env.EVENTCATALOG_DEV_MODE = 'true';
+    vi.mocked(readConfigSource).mockImplementation(() => {
+      throw new Error('ENOENT');
+    });
+    const res = await callPost(buildRequest({ title: 'X', theme: 'default' }));
+    expect(res.status).toBe(500);
+    const body = await res.json();
+    expect(body.error).toContain('eventcatalog.config.js');
+    expect(writeConfigUpdate).not.toHaveBeenCalled();
+  });
+
+  it('returns 500 when the config file is malformed and does not write', async () => {
+    process.env.EVENTCATALOG_DEV_MODE = 'true';
+    vi.mocked(applyConfigUpdate).mockImplementation(() => {
+      throw new Error('parse error');
+    });
+    const res = await callPost(buildRequest({ title: 'X', theme: 'default' }));
+    expect(res.status).toBe(500);
+    expect(writeConfigUpdate).not.toHaveBeenCalled();
+  });
+
+  it('passes nested logo update through to the writer', async () => {
+    process.env.EVENTCATALOG_DEV_MODE = 'true';
+    const res = await callPost(
+      buildRequest({
+        title: 'X',
+        theme: 'default',
+        logo: { alt: 'A', text: 'T' },
+      })
+    );
+    expect(res.status).toBe(200);
+    expect(writeConfigUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: 'X',
+        theme: 'default',
+        logo: { alt: 'A', text: 'T' },
+      })
+    );
+  });
+
+  it('omits empty optional fields by sending null to the writer', async () => {
+    process.env.EVENTCATALOG_DEV_MODE = 'true';
+    await callPost(buildRequest({ title: 'X', theme: 'default', tagline: '', organizationName: '   ' }));
+    const arg = vi.mocked(writeConfigUpdate).mock.calls[0][0];
+    expect(arg.tagline).toBeNull();
+    expect(arg.organizationName).toBeNull();
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/eventcatalog-config/config-writer.test.ts b/packages/core/eventcatalog/src/utils/__tests__/eventcatalog-config/config-writer.test.ts
new file mode 100644
index 000000000..1a4d40486
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/eventcatalog-config/config-writer.test.ts
@@ -0,0 +1,178 @@
+import { describe, expect, it } from 'vitest';
+import { applyConfigUpdate } from '@utils/eventcatalog-config/config-writer';
+
+const FULL_EXAMPLE = `import path from "path";
+import url from "url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('../../bin/eventcatalog.config').Config} */
+export default {
+  cId: '8027010c-f3d6-417a-8234-e2f46087fc56',
+  title: 'FlowMart',
+  tagline: 'Demo catalog tagline.',
+  organizationName: 'FlowMart',
+  homepageLink: 'https://eventcatalog.dev',
+  // editUrl is commented out intentionally
+  // editUrl: 'https://github.com/event-catalog/eventcatalog/edit/main',
+  port: 3000,
+  outDir: 'dist',
+  logo: {
+    alt: 'FlowMart',
+    // src: '/logo.png',
+    text: 'FlowMart',
+  },
+  // Theme: 'default', 'ocean', 'sapphire', 'sunset', 'forest'
+  theme: 'default',
+};
+`;
+
+const MINIMAL = `export default {
+  cId: 'abc',
+  title: 'Hello',
+};
+`;
+
+const NO_LOGO = `export default {
+  title: 'Hello',
+  theme: 'ocean',
+};
+`;
+
+const LOGO_NO_ALT = `export default {
+  title: 'Hello',
+  logo: {
+    text: 'Hi',
+  },
+};
+`;
+
+describe('config-writer: applyConfigUpdate', () => {
+  describe('replace existing string property', () => {
+    it('replaces the title and preserves everything else byte-identical', () => {
+      const result = applyConfigUpdate(FULL_EXAMPLE, { title: 'NewTitle' });
+      expect(result).toContain("title: 'NewTitle'");
+      // imports preserved
+      expect(result).toContain('import path from "path"');
+      expect(result).toContain('import url from "url"');
+      // computed dirname preserved
+      expect(result).toContain('const __dirname = path.dirname(url.fileURLToPath(import.meta.url))');
+      // JSDoc preserved
+      expect(result).toContain("/** @type {import('../../bin/eventcatalog.config').Config} */");
+      // commented-out lines preserved
+      expect(result).toContain('// editUrl is commented out intentionally');
+      expect(result).toContain("// editUrl: 'https://github.com/event-catalog/eventcatalog/edit/main'");
+      expect(result).toContain("// src: '/logo.png'");
+      expect(result).toContain("// Theme: 'default', 'ocean', 'sapphire', 'sunset', 'forest'");
+      // unchanged fields preserved verbatim
+      expect(result).toContain("cId: '8027010c-f3d6-417a-8234-e2f46087fc56'");
+      expect(result).toContain('port: 3000');
+      expect(result).toContain("outDir: 'dist'");
+      expect(result).toContain("theme: 'default'");
+    });
+
+    it('replaces nested logo.text', () => {
+      const result = applyConfigUpdate(FULL_EXAMPLE, { logo: { text: 'NewLogo' } });
+      expect(result).toContain("text: 'NewLogo'");
+      expect(result).toContain("alt: 'FlowMart'"); // sibling preserved
+      expect(result).toContain("// src: '/logo.png'"); // comment inside logo preserved
+    });
+  });
+
+  describe('insert missing property', () => {
+    it('inserts editUrl when absent', () => {
+      const result = applyConfigUpdate(MINIMAL, { editUrl: 'https://example.com' });
+      expect(result).toContain("editUrl: 'https://example.com'");
+      expect(result).toContain("title: 'Hello'");
+      expect(result).toContain("cId: 'abc'");
+    });
+
+    it('inserts the entire logo object when absent', () => {
+      const result = applyConfigUpdate(NO_LOGO, { logo: { text: 'New', alt: 'NewAlt' } });
+      expect(result).toContain('logo:');
+      expect(result).toContain("text: 'New'");
+      expect(result).toContain("alt: 'NewAlt'");
+      expect(result).toContain("title: 'Hello'");
+      expect(result).toContain("theme: 'ocean'");
+    });
+
+    it('inserts a missing nested property without disturbing existing ones', () => {
+      const result = applyConfigUpdate(LOGO_NO_ALT, { logo: { alt: 'AddedAlt' } });
+      expect(result).toContain("alt: 'AddedAlt'");
+      expect(result).toContain("text: 'Hi'");
+    });
+  });
+
+  describe('remove property', () => {
+    it('removes a top-level property when value is null', () => {
+      const result = applyConfigUpdate(FULL_EXAMPLE, { tagline: null });
+      expect(result).not.toContain('tagline:');
+      expect(result).toContain("title: 'FlowMart'");
+    });
+
+    it('removes a nested property when value is null', () => {
+      const result = applyConfigUpdate(FULL_EXAMPLE, { logo: { alt: null } });
+      // alt should be gone, text should remain
+      expect(result).not.toMatch(/^\s*alt:/m);
+      expect(result).toContain("text: 'FlowMart'");
+    });
+
+    it('removes the parent object if all its properties become null', () => {
+      const result = applyConfigUpdate(LOGO_NO_ALT, { logo: { text: null } });
+      expect(result).not.toContain('logo:');
+      expect(result).toContain("title: 'Hello'");
+    });
+  });
+
+  describe('no-op write', () => {
+    it('produces functionally equivalent source when setting an existing value to itself', () => {
+      const result = applyConfigUpdate(FULL_EXAMPLE, { title: 'FlowMart' });
+      // Recast may re-print the touched node, but everything else must match
+      expect(result).toContain("title: 'FlowMart'");
+      expect(result).toContain('import path from "path"');
+      expect(result).toContain('// editUrl is commented out intentionally');
+      expect(result).toContain("// src: '/logo.png'");
+      expect(result).toContain('port: 3000');
+    });
+  });
+
+  describe('multiple updates in one call', () => {
+    it('applies a top-level change, a nested change, and a removal together', () => {
+      const result = applyConfigUpdate(FULL_EXAMPLE, {
+        title: 'Bundle',
+        tagline: null,
+        logo: { text: 'BundleLogo' },
+      });
+      expect(result).toContain("title: 'Bundle'");
+      expect(result).not.toContain('tagline:');
+      expect(result).toContain("text: 'BundleLogo'");
+      expect(result).toContain("alt: 'FlowMart'"); // untouched nested sibling
+      expect(result).toContain('import path from "path"'); // imports still here
+    });
+  });
+
+  describe('boolean values', () => {
+    it('inserts a nested boolean property when absent', () => {
+      const result = applyConfigUpdate(MINIMAL, { llmsTxt: { enabled: true } });
+      expect(result).toMatch(/llmsTxt:\s*{[^}]*enabled:\s*true/);
+    });
+
+    it('replaces a nested boolean property in place', () => {
+      const source = `export default {
+  title: 'Hello',
+  llmsTxt: {
+    enabled: true,
+  },
+};
+`;
+      const result = applyConfigUpdate(source, { llmsTxt: { enabled: false } });
+      expect(result).toMatch(/enabled:\s*false/);
+      expect(result).not.toMatch(/enabled:\s*true/);
+    });
+
+    it('sets a top-level boolean property', () => {
+      const result = applyConfigUpdate(MINIMAL, { trailingSlash: true });
+      expect(result).toMatch(/trailingSlash:\s*true/);
+    });
+  });
+});
diff --git a/eventcatalog/src/utils/__tests__/events/events.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/events/events.spec.ts
similarity index 94%
rename from eventcatalog/src/utils/__tests__/events/events.spec.ts
rename to packages/core/eventcatalog/src/utils/__tests__/events/events.spec.ts
index e778380d7..156a6ec82 100644
--- a/eventcatalog/src/utils/__tests__/events/events.spec.ts
+++ b/packages/core/eventcatalog/src/utils/__tests__/events/events.spec.ts
@@ -1,13 +1,13 @@
-import type { ContentCollectionKey } from 'astro:content';
+import type { CollectionKey } from 'astro:content';
 import { expect, describe, it, vi } from 'vitest';
 import { mockServices, mockEvents } from './mocks';
-import { getEvents } from '@utils/events';
+import { getEvents } from '@utils/collections/events';
 
 vi.mock('astro:content', async (importOriginal) => {
   return {
     ...(await importOriginal<typeof import('astro:content')>()),
     // this will only affect "foo" outside of the original module
-    getCollection: (key: ContentCollectionKey) => {
+    getCollection: (key: CollectionKey) => {
       switch (key) {
         case 'services':
           return Promise.resolve(mockServices);
diff --git a/packages/core/eventcatalog/src/utils/__tests__/events/mocks.ts b/packages/core/eventcatalog/src/utils/__tests__/events/mocks.ts
new file mode 100644
index 000000000..ed595ffa2
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/events/mocks.ts
@@ -0,0 +1,232 @@
+export const mockServices = [
+  {
+    id: 'OrderService',
+    slug: 'OrderService',
+    collection: 'services',
+    data: {
+      id: 'OrderService',
+      version: '0.0.1',
+      sends: [
+        {
+          id: 'OrderCreatedEvent',
+          version: '0.0.1',
+          to: [
+            {
+              id: 'EmailChannel',
+              version: '1.0.0',
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    id: 'PaymentService',
+    slug: 'PaymentService',
+    collection: 'services',
+    data: {
+      id: 'PaymentService',
+      version: '0.0.1',
+      receives: [
+        {
+          id: 'OrderCreatedEvent',
+          version: '0.0.1',
+        },
+      ],
+    },
+  },
+  {
+    id: 'InventoryService',
+    slug: 'InventoryService',
+    collection: 'services',
+    data: {
+      id: 'InventoryService',
+      version: '0.0.1',
+      sends: [
+        {
+          id: 'InventoryAdjusted',
+          version: '>1.2.0',
+        },
+        {
+          id: 'ProductOutOfStock',
+        },
+        {
+          id: 'ProductDiscontinued',
+          version: 'latest',
+        },
+      ],
+    },
+  },
+  {
+    id: 'CatalogService',
+    slug: 'CatalogService',
+    collection: 'services',
+    data: {
+      id: 'CatalogService',
+      version: '0.0.1',
+      receives: [
+        {
+          id: 'InventoryAdjusted',
+        },
+        {
+          id: 'ProductDiscontinued',
+          version: '*',
+        },
+      ],
+    },
+  },
+  {
+    id: 'NotificationsService',
+    slug: 'NotificationsService',
+    collection: 'services',
+    data: {
+      id: 'NotificationsService',
+      version: '0.0.1',
+      receives: [
+        {
+          id: 'EmailSent',
+          from: [
+            {
+              id: 'EmailChannel',
+              version: '1.0.0',
+            },
+          ],
+        },
+      ],
+      sends: [
+        {
+          id: 'EmailSent',
+        },
+        {
+          id: 'EmailVerified',
+        },
+      ],
+    },
+  },
+];
+
+export const mockChannels = [
+  {
+    id: 'EmailChannel',
+    slug: 'EmailChannel',
+    collection: 'channels',
+    data: {
+      id: 'EmailChannel',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockEvents = [
+  {
+    id: 'OrderCreatedEvent',
+    slug: 'OrderCreatedEvent',
+    collection: 'events',
+    data: {
+      id: 'OrderCreatedEvent',
+      version: '0.0.1',
+    },
+  },
+  {
+    id: 'InventoryAdjusted',
+    slug: 'InventoryAdjusted',
+    collection: 'events',
+    data: {
+      id: 'InventoryAdjusted',
+      version: '1.5.1',
+    },
+  },
+  {
+    id: 'ProductOutOfStock',
+    slug: 'ProductOutOfStock',
+    collection: 'events',
+    data: {
+      id: 'ProductOutOfStock',
+      version: '1.0.0',
+    },
+  },
+  {
+    id: 'ProductDiscontinued',
+    slug: 'ProductDiscontinued',
+    collection: 'events',
+    data: {
+      id: 'ProductDiscontinued',
+      version: '0.0.1',
+    },
+  },
+  {
+    id: 'ProductDiscontinued',
+    slug: 'ProductDiscontinued',
+    collection: 'events',
+    data: {
+      id: 'ProductDiscontinued',
+      version: '1.0.0',
+    },
+  },
+  {
+    id: 'EmailSent',
+    slug: 'EmailSent',
+    collection: 'events',
+    data: {
+      id: 'EmailSent',
+      version: '1.0.0',
+    },
+  },
+  {
+    id: 'EmailVerified',
+    slug: 'EmailVerified',
+    collection: 'events',
+    data: {
+      id: 'EmailVerified',
+      version: '1.0.0',
+    },
+  },
+  {
+    id: 'DataProductEvent',
+    slug: 'DataProductEvent',
+    collection: 'events',
+    data: {
+      id: 'DataProductEvent',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockDataProducts = [
+  {
+    id: 'OrderAnalytics-1.0.0',
+    slug: 'OrderAnalytics',
+    collection: 'data-products',
+    data: {
+      id: 'OrderAnalytics',
+      name: 'Order Analytics',
+      version: '1.0.0',
+      inputs: [{ id: 'OrderCreatedEvent', version: '0.0.1' }],
+      outputs: [],
+    },
+  },
+  {
+    id: 'OrderDataPipeline-1.0.0',
+    slug: 'OrderDataPipeline',
+    collection: 'data-products',
+    data: {
+      id: 'OrderDataPipeline',
+      name: 'Order Data Pipeline',
+      version: '1.0.0',
+      inputs: [],
+      outputs: [{ id: 'OrderCreatedEvent', version: '0.0.1' }],
+    },
+  },
+  {
+    id: 'DataProductProducerConsumer-1.0.0',
+    slug: 'DataProductProducerConsumer',
+    collection: 'data-products',
+    data: {
+      id: 'DataProductProducerConsumer',
+      name: 'Data Product Producer Consumer',
+      version: '1.0.0',
+      inputs: [{ id: 'DataProductEvent', version: '1.0.0' }],
+      outputs: [{ id: 'DataProductEvent', version: '1.0.0' }],
+    },
+  },
+];
diff --git a/packages/core/eventcatalog/src/utils/__tests__/events/node-graph.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/events/node-graph.spec.ts
new file mode 100644
index 000000000..21d2f54e2
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/events/node-graph.spec.ts
@@ -0,0 +1,530 @@
+import { getNodesAndEdgesForEvents as getNodesAndEdges } from '../../node-graphs/message-node-graph';
+import { expect, describe, it, vi, beforeEach } from 'vitest';
+import { mockEvents, mockServices, mockChannels, mockDataProducts } from './mocks';
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: (key: string) => {
+      if (key === 'services') {
+        return Promise.resolve(mockServices);
+      }
+      if (key === 'channels') {
+        return Promise.resolve(mockChannels);
+      }
+      if (key === 'events') {
+        return Promise.resolve(mockEvents);
+      }
+      if (key === 'data-products') {
+        return Promise.resolve(mockDataProducts);
+      }
+      return Promise.resolve([]);
+    },
+  };
+});
+
+describe('Events NodeGraph', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('getNodesAndEdges', () => {
+    it('should return nodes and edges for a given event', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'OrderCreatedEvent', version: '0.0.1' });
+
+      // The middle node itself, the service
+      const expectedEventNode = {
+        id: 'OrderCreatedEvent-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        // data: { mode: 'simple', message: expect.anything(), showSource: false },
+        data: expect.anything(),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'events',
+      };
+
+      const expectedProducerNode = {
+        id: 'OrderService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[0].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedConsumerNode = {
+        id: 'PaymentService-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({
+          title: 'PaymentService',
+          mode: 'simple',
+          service: { ...mockServices[1].data },
+        }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        expect.objectContaining({
+          id: 'OrderService-0.0.1-OrderCreatedEvent-0.0.1',
+          source: 'OrderService-0.0.1',
+          target: 'OrderCreatedEvent-0.0.1',
+          label: 'publishes \nevent',
+          animated: false,
+        }),
+        // The channel to the event
+        expect.objectContaining({
+          id: 'OrderCreatedEvent-0.0.1-EmailChannel-1.0.0',
+          source: 'OrderCreatedEvent-0.0.1',
+          target: 'EmailChannel-1.0.0',
+          label: 'routes to',
+          animated: false,
+        }),
+        // The event to the consumer
+        expect.objectContaining({
+          id: 'OrderCreatedEvent-0.0.1-PaymentService-0.0.1',
+          source: 'OrderCreatedEvent-0.0.1',
+          target: 'PaymentService-0.0.1',
+          label: 'subscribed by',
+          animated: false,
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedConsumerNode),
+
+          // The event node itself
+          expect.objectContaining(expectedEventNode),
+
+          // Nodes on the right
+          expect.objectContaining(expectedProducerNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('if the event is produced and consumed by a service it will render a custom edge', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'EmailSent', version: '1.0.0' });
+
+      // The middle node itself, the service
+      const expectedEventNode = {
+        id: 'EmailSent-1.0.0',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        // data: { mode: 'simple', message: expect.anything(), showSource: false },
+        data: expect.anything(),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'events',
+      };
+
+      const expectedProducerNode = {
+        id: 'NotificationsService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[4].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedConsumerNode = {
+        id: 'NotificationsService-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({
+          title: 'NotificationsService',
+          mode: 'simple',
+          service: { ...mockServices[4].data },
+        }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        // Producer to the event
+        expect.objectContaining({
+          id: 'NotificationsService-0.0.1-EmailSent-1.0.0',
+          source: 'NotificationsService-0.0.1',
+          target: 'EmailSent-1.0.0',
+          label: 'publishes \nevent',
+        }),
+        // Event to the channel
+        expect.objectContaining({
+          id: 'EmailSent-1.0.0-EmailChannel-1.0.0',
+          source: 'EmailSent-1.0.0',
+          target: 'EmailChannel-1.0.0',
+          label: 'routes to',
+          animated: false,
+        }),
+        expect.objectContaining({
+          id: 'EmailSent-1.0.0-NotificationsService-0.0.1-both',
+          source: 'EmailSent-1.0.0',
+          target: 'NotificationsService-0.0.1',
+          label: 'publishes and subscribes',
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedConsumerNode),
+
+          // The event node itself
+          expect.objectContaining(expectedEventNode),
+
+          // Nodes on the right
+          expect.objectContaining(expectedProducerNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('if the consumer of an event has defined a channel, it will render the channel node and edges', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'EmailSent', version: '1.0.0' });
+
+      const expectedConsumerNode = {
+        id: 'NotificationsService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[4].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedChannelNode = {
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        id: 'EmailChannel-1.0.0',
+        type: 'channels',
+      };
+
+      const expectedEventNode = {
+        id: 'EmailSent-1.0.0',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        type: 'events',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        // Message to the channel
+        expect.objectContaining({
+          id: 'EmailSent-1.0.0-EmailChannel-1.0.0',
+          source: 'EmailSent-1.0.0',
+          target: 'EmailChannel-1.0.0',
+        }),
+        // Channel to the consumer
+        expect.objectContaining({
+          id: 'EmailChannel-1.0.0-NotificationsService-0.0.1',
+          source: 'EmailChannel-1.0.0',
+          target: 'NotificationsService-0.0.1',
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedConsumerNode),
+
+          // channel
+          expect.objectContaining(expectedChannelNode),
+
+          // The event node itself
+          expect.objectContaining(expectedEventNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('if the producer of an event has defined a channel, it will render the channel node and edges', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'OrderCreatedEvent', version: '0.0.1' });
+
+      const expectedProducerNode = {
+        id: 'OrderService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedChannelNode = {
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        id: 'EmailChannel-1.0.0',
+        type: 'channels',
+      };
+
+      const expectedEventNode = {
+        id: 'OrderCreatedEvent-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        type: 'events',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        // Producer to the message
+        expect.objectContaining({
+          id: 'OrderService-0.0.1-OrderCreatedEvent-0.0.1',
+          source: 'OrderService-0.0.1',
+          target: 'OrderCreatedEvent-0.0.1',
+          label: 'publishes \nevent',
+          animated: false,
+        }),
+        // Message to the channel
+        expect.objectContaining({
+          id: 'OrderCreatedEvent-0.0.1-EmailChannel-1.0.0',
+          source: 'OrderCreatedEvent-0.0.1',
+          target: 'EmailChannel-1.0.0',
+          label: 'routes to',
+          animated: false,
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedProducerNode),
+
+          // channel
+          expect.objectContaining(expectedChannelNode),
+
+          // The event node itself
+          expect.objectContaining(expectedEventNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('returns empty nodes and edges if no event is found', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownEvent', version: '1.0.0' });
+
+      expect(nodes).toEqual([]);
+      expect(edges).toEqual([]);
+    });
+
+    it('should return nodes and edges for a given event using semver range', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'InventoryAdjusted', version: '1.5.1' });
+
+      // The middle node itself, the service
+      const expectedEventNode = {
+        id: 'InventoryAdjusted-1.5.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.anything(),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'events',
+      };
+
+      const expectedProducerNode = {
+        id: 'InventoryService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[2].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedConsumerNode = {
+        id: 'CatalogService-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ title: 'CatalogService', mode: 'simple', service: { ...mockServices[3].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        expect.objectContaining({
+          id: 'InventoryService-0.0.1-InventoryAdjusted-1.5.1',
+          source: 'InventoryService-0.0.1',
+          target: 'InventoryAdjusted-1.5.1',
+          label: 'publishes \nevent',
+          animated: false,
+        }),
+        expect.objectContaining({
+          id: 'InventoryAdjusted-1.5.1-CatalogService-0.0.1',
+          source: 'InventoryAdjusted-1.5.1',
+          target: 'CatalogService-0.0.1',
+          label: 'subscribed by',
+          animated: false,
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedProducerNode),
+
+          // The event node itself
+          expect.objectContaining(expectedEventNode),
+
+          // Nodes on the right
+          expect.objectContaining(expectedConsumerNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    describe('data products', () => {
+      it('should render data product as a consumer when it has the event as an input', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'OrderCreatedEvent', version: '0.0.1' });
+
+        const expectedDataProductConsumerNode = {
+          id: 'OrderAnalytics-1.0.0',
+          type: 'data-products',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({
+            title: 'OrderAnalytics',
+            mode: 'simple',
+            dataProduct: expect.objectContaining({
+              id: 'OrderAnalytics',
+              version: '1.0.0',
+            }),
+          }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        expect(nodes).toEqual(expect.arrayContaining([expect.objectContaining(expectedDataProductConsumerNode)]));
+
+        expect(edges).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderCreatedEvent-0.0.1-OrderAnalytics-1.0.0',
+              source: 'OrderCreatedEvent-0.0.1',
+              target: 'OrderAnalytics-1.0.0',
+              label: 'consumed by',
+            }),
+          ])
+        );
+      });
+
+      it('should render data product as a producer when it has the event as an output', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'OrderCreatedEvent', version: '0.0.1' });
+
+        const expectedDataProductProducerNode = {
+          id: 'OrderDataPipeline-1.0.0',
+          type: 'data-products',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({
+            mode: 'simple',
+            dataProduct: expect.objectContaining({
+              id: 'OrderDataPipeline',
+              version: '1.0.0',
+            }),
+          }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        expect(nodes).toEqual(expect.arrayContaining([expect.objectContaining(expectedDataProductProducerNode)]));
+
+        expect(edges).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderDataPipeline-1.0.0-OrderCreatedEvent-0.0.1',
+              source: 'OrderDataPipeline-1.0.0',
+              target: 'OrderCreatedEvent-0.0.1',
+              label: 'produces',
+            }),
+          ])
+        );
+      });
+
+      it('should render data product that is both producer and consumer of the same event', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'DataProductEvent', version: '1.0.0' });
+
+        // Should have data product nodes (may have duplicates from producer and consumer logic)
+        const dataProductNodes = nodes.filter((n: any) => n.id === 'DataProductProducerConsumer-1.0.0');
+        expect(dataProductNodes.length).toBeGreaterThanOrEqual(1);
+        expect(dataProductNodes[0]).toEqual(
+          expect.objectContaining({
+            id: 'DataProductProducerConsumer-1.0.0',
+            type: 'data-products',
+            data: expect.objectContaining({
+              mode: 'simple',
+              dataProduct: expect.objectContaining({
+                id: 'DataProductProducerConsumer',
+                version: '1.0.0',
+              }),
+            }),
+          })
+        );
+
+        // Should have producer edge (data product -> event)
+        expect(edges).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'DataProductProducerConsumer-1.0.0-DataProductEvent-1.0.0',
+              source: 'DataProductProducerConsumer-1.0.0',
+              target: 'DataProductEvent-1.0.0',
+              label: 'produces',
+            }),
+          ])
+        );
+
+        // Should have consumer edge (event -> data product)
+        expect(edges).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'DataProductEvent-1.0.0-DataProductProducerConsumer-1.0.0',
+              source: 'DataProductEvent-1.0.0',
+              target: 'DataProductProducerConsumer-1.0.0',
+              label: 'consumed by',
+            }),
+          ])
+        );
+      });
+
+      it('should render both services and data products as producers and consumers', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'OrderCreatedEvent', version: '0.0.1' });
+
+        // Should have service producer
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderService-0.0.1',
+              type: 'services',
+            }),
+          ])
+        );
+
+        // Should have service consumer
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'PaymentService-0.0.1',
+              type: 'services',
+            }),
+          ])
+        );
+
+        // Should have data product producer
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderDataPipeline-1.0.0',
+              type: 'data-products',
+            }),
+          ])
+        );
+
+        // Should have data product consumer
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderAnalytics-1.0.0',
+              type: 'data-products',
+            }),
+          ])
+        );
+      });
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/examples.test.ts b/packages/core/eventcatalog/src/utils/__tests__/examples.test.ts
new file mode 100644
index 000000000..0fa7b141d
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/examples.test.ts
@@ -0,0 +1,193 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import { getExamplesForResource } from '@utils/collections/examples';
+
+const TEST_DIR = path.join(__dirname, '__test-examples-tmp__');
+
+const createResource = (subdir: string = '') => {
+  const resourceDir = path.join(TEST_DIR, subdir);
+  fs.mkdirSync(resourceDir, { recursive: true });
+  const indexPath = path.join(resourceDir, 'index.mdx');
+  fs.writeFileSync(indexPath, '---\nid: TestEvent\n---\n');
+  return { filePath: indexPath };
+};
+
+const createExamples = (subdir: string, files: Record<string, string>) => {
+  const examplesDir = path.join(TEST_DIR, subdir, 'examples');
+  fs.mkdirSync(examplesDir, { recursive: true });
+  for (const [name, content] of Object.entries(files)) {
+    fs.writeFileSync(path.join(examplesDir, name), content);
+  }
+};
+
+beforeEach(() => {
+  fs.rmSync(TEST_DIR, { recursive: true, force: true });
+  fs.mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe('getExamplesForResource', () => {
+  it('returns examples from a message examples directory sorted alphabetically', () => {
+    const resource = createResource('event1');
+    createExamples('event1', {
+      'beta.json': '{"b": true}',
+      'alpha.json': '{"a": true}',
+    });
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples).toHaveLength(2);
+    expect(examples[0].fileName).toBe('alpha.json');
+    expect(examples[1].fileName).toBe('beta.json');
+  });
+
+  it('returns empty array when no examples directory exists', () => {
+    const resource = createResource('event2');
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples).toEqual([]);
+  });
+
+  it('returns empty array when examples directory is empty', () => {
+    const resource = createResource('event3');
+    fs.mkdirSync(path.join(TEST_DIR, 'event3', 'examples'), { recursive: true });
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples).toEqual([]);
+  });
+
+  it('extracts title from file name by removing extension', () => {
+    const resource = createResource('event4');
+    createExamples('event4', { 'my-example.json': '{}' });
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples[0].title).toBe('my-example');
+    expect(examples[0].extension).toBe('json');
+  });
+
+  it('reads file content for each example', () => {
+    const resource = createResource('event5');
+    createExamples('event5', { 'payload.json': '{"orderId": "abc"}' });
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples[0].content).toBe('{"orderId": "abc"}');
+  });
+
+  it('supports multiple file formats', () => {
+    const resource = createResource('event6');
+    createExamples('event6', {
+      'example.json': '{}',
+      'example.yaml': 'key: value',
+      'example.xml': '<root/>',
+      'example.proto': 'message Test {}',
+    });
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples).toHaveLength(4);
+    expect(examples.map((e) => e.extension)).toEqual(['json', 'proto', 'xml', 'yaml']);
+  });
+
+  it('includes files from nested directories inside examples folder', () => {
+    const resource = createResource('event7');
+    createExamples('event7', { 'root.json': '{}' });
+    fs.mkdirSync(path.join(TEST_DIR, 'event7', 'examples', 'errors'), { recursive: true });
+    fs.writeFileSync(path.join(TEST_DIR, 'event7', 'examples', 'errors', 'not-found.json'), '{"error": true}');
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples).toHaveLength(2);
+    expect(examples[0].fileName).toBe(path.join('errors', 'not-found.json'));
+    expect(examples[0].title).toBe('not-found');
+    expect(examples[0].content).toBe('{"error": true}');
+    expect(examples[1].fileName).toBe('root.json');
+  });
+
+  it('returns empty array when resource has no filePath', () => {
+    const examples = getExamplesForResource({});
+
+    expect(examples).toEqual([]);
+  });
+
+  it('excludes examples.config.yaml from the returned examples', () => {
+    const resource = createResource('event8');
+    createExamples('event8', {
+      'basic.json': '{}',
+      'examples.config.yaml': 'basic.json:\n  name: Basic\n',
+    });
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples).toHaveLength(1);
+    expect(examples[0].fileName).toBe('basic.json');
+  });
+
+  it('uses name from config file as title when provided', () => {
+    const resource = createResource('event9');
+    createExamples('event9', {
+      'basic.json': '{}',
+      'examples.config.yaml': 'basic.json:\n  name: My Custom Name\n',
+    });
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples[0].title).toBe('My Custom Name');
+  });
+
+  it('falls back to file name as title when config has no name', () => {
+    const resource = createResource('event10');
+    createExamples('event10', {
+      'basic.json': '{}',
+      'examples.config.yaml': 'basic.json:\n  summary: Just a summary\n',
+    });
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples[0].title).toBe('basic');
+  });
+
+  it('includes summary and usage from config file', () => {
+    const resource = createResource('event11');
+    createExamples('event11', {
+      'basic.json': '{}',
+      'examples.config.yaml':
+        'basic.json:\n  name: Basic Example\n  summary: A basic payload\n  usage: "curl http://localhost"\n',
+    });
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples[0].summary).toBe('A basic payload');
+    expect(examples[0].usage).toBe('curl http://localhost');
+  });
+
+  it('returns no summary or usage when config file does not exist', () => {
+    const resource = createResource('event12');
+    createExamples('event12', { 'basic.json': '{}' });
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples[0].summary).toBeUndefined();
+    expect(examples[0].usage).toBeUndefined();
+  });
+
+  it('supports examples.config.json as an alternative config format', () => {
+    const resource = createResource('event13');
+    createExamples('event13', {
+      'basic.json': '{}',
+      'examples.config.json': JSON.stringify({ 'basic.json': { name: 'From JSON Config' } }),
+    });
+
+    const examples = getExamplesForResource(resource);
+
+    expect(examples).toHaveLength(1);
+    expect(examples[0].title).toBe('From JSON Config');
+  });
+});
diff --git a/eventcatalog/src/utils/__tests__/features.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/features.spec.ts
similarity index 76%
rename from eventcatalog/src/utils/__tests__/features.spec.ts
rename to packages/core/eventcatalog/src/utils/__tests__/features.spec.ts
index 9ab57a4e9..2984d9fb6 100644
--- a/eventcatalog/src/utils/__tests__/features.spec.ts
+++ b/packages/core/eventcatalog/src/utils/__tests__/features.spec.ts
@@ -1,7 +1,9 @@
+import path from 'path';
 import {
   isEventCatalogStarterEnabled,
   isEventCatalogScaleEnabled,
   isCustomDocsEnabled,
+  isResourceDocsEnabled,
   isEventCatalogChatEnabled,
   isEventCatalogUpgradeEnabled,
   isCustomLandingPageEnabled,
@@ -9,9 +11,11 @@ import {
   showEventCatalogBranding,
   showCustomBranding,
   isPrivateRemoteSchemaEnabled,
+  isCustomStylesEnabled,
 } from '../feature';
 
 import config from '@config';
+import fs from 'fs';
 
 vi.mock('@config', () => ({
   default: {
@@ -30,6 +34,12 @@ describe('features', () => {
   beforeEach(() => {
     // Reset the environment before each test
     process.env = { ...originalEnv };
+
+    // Set the project directory to the examples/default directory
+    process.env.PROJECT_DIR = path.join(__dirname, 'catalog');
+
+    // Create the catalog directory if it doesn't exist
+    fs.mkdirSync(process.env.PROJECT_DIR, { recursive: true });
   });
 
   afterEach(() => {
@@ -106,27 +116,58 @@ describe('features', () => {
     });
   });
 
-  describe('isEventCatalogChatEnabled', () => {
-    it('should return true when EVENTCATALOG_STARTER is true, chat is enabled and isSSR', () => {
+  describe('isResourceDocsEnabled', () => {
+    it('should return false when EVENTCATALOG_STARTER is true', () => {
       process.env.EVENTCATALOG_STARTER = 'true';
-      config.chat.enabled = true;
-      config.output = 'server';
-      expect(isEventCatalogChatEnabled()).toBe(true);
+      expect(isResourceDocsEnabled()).toBe(false);
     });
 
-    it('should return true when EVENTCATALOG_SCALE is true, chat is enabled and isSSR', () => {
+    it('should return true when EVENTCATALOG_SCALE is true', () => {
       process.env.EVENTCATALOG_SCALE = 'true';
-      config.chat.enabled = true;
-      config.output = 'server';
-      expect(isEventCatalogChatEnabled()).toBe(true);
+      expect(isResourceDocsEnabled()).toBe(true);
     });
 
-    it('should return false when neither feature is enabled, chat is enabled and isSSR', () => {
+    it('should return false when neither feature is enabled', () => {
       delete process.env.EVENTCATALOG_STARTER;
       delete process.env.EVENTCATALOG_SCALE;
-      config.chat.enabled = true;
+      expect(isResourceDocsEnabled()).toBe(false);
+    });
+  });
+
+  describe('isEventCatalogChatEnabled', () => {
+    it('should return true when EVENTCATALOG_STARTER is true, the user has a eventcatalog.chat.js file and isSSR', () => {
+      // Create the fake file
+      fs.writeFileSync(
+        path.join(process.env.PROJECT_DIR || '', 'eventcatalog.chat.js'),
+        'export default () => { return { model: "o4-mini" }; }'
+      );
+      process.env.EVENTCATALOG_STARTER = 'true';
       config.output = 'server';
+      expect(isEventCatalogChatEnabled()).toBe(true);
+
+      // Remove the file
+      fs.rmSync(path.join(process.env.PROJECT_DIR || '', 'eventcatalog.chat.js'));
+    });
+
+    // returns false when no file is found
+    it('should return false when no file is found', () => {
+      process.env.EVENTCATALOG_STARTER = 'true';
+      config.output = 'server';
+      expect(isEventCatalogChatEnabled()).toBe(false);
+    });
+
+    it('should return false when output is not server', () => {
+      fs.writeFileSync(
+        path.join(process.env.PROJECT_DIR || '', 'eventcatalog.chat.js'),
+        'export default () => { return { model: "o4-mini" }; }'
+      );
+      process.env.EVENTCATALOG_STARTER = 'true';
+      config.output = 'static';
+
       expect(isEventCatalogChatEnabled()).toBe(false);
+
+      // Remove the file
+      fs.rmSync(path.join(process.env.PROJECT_DIR || '', 'eventcatalog.chat.js'));
     });
   });
 
@@ -149,21 +190,10 @@ describe('features', () => {
   });
 
   describe('isCustomLandingPageEnabled', () => {
-    it('should return true when EVENTCATALOG_STARTER is true', () => {
+    it('should return true', () => {
       process.env.EVENTCATALOG_STARTER = 'true';
       expect(isCustomLandingPageEnabled()).toBe(true);
     });
-
-    it('should return true when EVENTCATALOG_SCALE is true', () => {
-      process.env.EVENTCATALOG_SCALE = 'true';
-      expect(isCustomLandingPageEnabled()).toBe(true);
-    });
-
-    it('should return false when neither feature is enabled', () => {
-      delete process.env.EVENTCATALOG_STARTER;
-      delete process.env.EVENTCATALOG_SCALE;
-      expect(isCustomLandingPageEnabled()).toBe(false);
-    });
   });
 
   describe('isMarkdownDownloadEnabled', () => {
@@ -227,4 +257,22 @@ describe('features', () => {
       expect(showCustomBranding()).toBe(false);
     });
   });
+
+  describe('isCustomStylesEnabled', () => {
+    it('should return true when EVENTCATALOG_STARTER is true', () => {
+      process.env.EVENTCATALOG_STARTER = 'true';
+      expect(isCustomStylesEnabled()).toBe(true);
+    });
+
+    it('should return true when EVENTCATALOG_SCALE is true', () => {
+      process.env.EVENTCATALOG_SCALE = 'true';
+      expect(isCustomStylesEnabled()).toBe(true);
+    });
+
+    it('should return false when neither feature is enabled', () => {
+      delete process.env.EVENTCATALOG_STARTER;
+      delete process.env.EVENTCATALOG_SCALE;
+      expect(isCustomStylesEnabled()).toBe(false);
+    });
+  });
 });
diff --git a/packages/core/eventcatalog/src/utils/__tests__/flows/mocks.ts b/packages/core/eventcatalog/src/utils/__tests__/flows/mocks.ts
new file mode 100644
index 000000000..268cbdd9b
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/flows/mocks.ts
@@ -0,0 +1,565 @@
+export const mockEvents = [
+  {
+    slug: 'PaymentInitiated',
+    collection: 'events',
+    data: {
+      id: 'PaymentInitiated',
+      version: '0.0.1',
+    },
+  },
+  {
+    slug: 'PaymentProcessed',
+    collection: 'events',
+    data: {
+      id: 'PaymentProcessed',
+      version: '0.0.1',
+    },
+  },
+];
+
+export const mockServices = [
+  {
+    slug: 'SubscriptionService',
+    collection: 'services',
+    data: {
+      id: 'SubscriptionService',
+      version: '0.0.1',
+    },
+  },
+];
+
+export const mockAgents = [
+  {
+    slug: 'FraudReviewAgent',
+    collection: 'agents',
+    data: {
+      id: 'FraudReviewAgent',
+      name: 'Fraud Review Agent',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockContainers = [
+  {
+    slug: 'orders-db',
+    collection: 'containers',
+    data: {
+      id: 'OrdersDB',
+      name: 'Orders DB',
+      version: '1.0.0',
+      container_type: 'database',
+    },
+  },
+  {
+    slug: 'orders-db/versioned/0.0.1',
+    collection: 'containers',
+    data: {
+      id: 'OrdersDB',
+      name: 'Orders DB',
+      version: '0.0.1',
+      container_type: 'database',
+    },
+  },
+];
+
+export const mockDataProducts = [
+  {
+    slug: 'order-analytics',
+    collection: 'data-products',
+    data: {
+      id: 'OrderAnalytics',
+      name: 'Order Analytics',
+      version: '1.0.0',
+    },
+  },
+  {
+    slug: 'order-analytics/versioned/0.0.1',
+    collection: 'data-products',
+    data: {
+      id: 'OrderAnalytics',
+      name: 'Order Analytics',
+      version: '0.0.1',
+    },
+  },
+];
+
+export const mockFlow = [
+  {
+    id: 'Payment/PaymentProcessed/index.mdx',
+    slug: 'payment/paymentprocessed',
+    body: '',
+    collection: 'flows',
+    data: {
+      steps: [
+        {
+          id: 1,
+          type: 'node',
+          title: 'Order Placed',
+          next_step: {
+            id: 2,
+            label: 'Proceed to payment',
+          },
+        },
+        {
+          id: 2,
+          title: 'Payment Initiated',
+          message: {
+            id: 'PaymentInitiated',
+            version: '0.0.1',
+          },
+          next_steps: [
+            {
+              id: 3,
+              label: 'Payment successful',
+            },
+            {
+              id: 4,
+              label: 'Payment failed',
+            },
+          ],
+        },
+        {
+          id: 3,
+          title: 'Payment Processed',
+          message: {
+            id: 'PaymentProcessed',
+            version: '0.0.1',
+          },
+        },
+        {
+          id: 4,
+          type: 'node',
+          title: 'Payment Failed',
+        },
+      ],
+      id: 'PaymentFlow',
+      name: 'Payment Flow for E-commerce',
+      summary: 'Business flow for processing payments in an e-commerce platform',
+      version: '1.0.0',
+      type: 'node',
+    },
+  },
+  {
+    id: 'Orders/DataStoreFlow/index.mdx',
+    slug: 'orders/datastoreflow',
+    body: '',
+    collection: 'flows',
+    data: {
+      steps: [
+        {
+          id: 'orders-service',
+          title: 'Orders Service',
+          service: {
+            id: 'SubscriptionService',
+            version: 'latest',
+          },
+          next_step: {
+            id: 'orders-db',
+            label: 'Stores order data',
+          },
+        },
+        {
+          id: 'orders-db',
+          title: 'Orders DB',
+          container: {
+            id: 'OrdersDB',
+          },
+        },
+      ],
+      id: 'DataStoreFlow',
+      name: 'Data Store Flow',
+      summary: 'Flow that includes a data store',
+      version: '1.0.0',
+    },
+  },
+  {
+    id: 'Orders/DataProductFlow/index.mdx',
+    slug: 'orders/dataproductflow',
+    body: '',
+    collection: 'flows',
+    data: {
+      steps: [
+        {
+          id: 'orders-service',
+          title: 'Orders Service',
+          service: {
+            id: 'SubscriptionService',
+            version: 'latest',
+          },
+          next_step: {
+            id: 'order-analytics',
+            label: 'Publishes analytics-ready facts',
+          },
+        },
+        {
+          id: 'order-analytics',
+          title: 'Order Analytics',
+          dataProduct: {
+            id: 'OrderAnalytics',
+          },
+        },
+        {
+          id: 'fraud-review',
+          title: 'Fraud Review',
+          agent: {
+            id: 'FraudReviewAgent',
+          },
+        },
+      ],
+      id: 'DataProductFlow',
+      name: 'Data Product Flow',
+      summary: 'Flow that includes a data product',
+      version: '1.0.0',
+    },
+  },
+];
+
+// Parent flow that references SubFlow as a step, plus the SubFlow itself, for
+// testing inline sub-flow expansion precomputation.
+export const mockFlowsWithSubFlow = [
+  {
+    id: 'Parent/index.mdx',
+    slug: 'parent',
+    body: '',
+    collection: 'flows',
+    data: {
+      id: 'ParentFlow',
+      name: 'Parent Flow',
+      version: '1.0.0',
+      steps: [
+        {
+          id: 'start',
+          type: 'node',
+          title: 'Start',
+          next_step: { id: 'sub', label: 'Run sub-flow' },
+        },
+        {
+          id: 'sub',
+          title: 'Sub Flow Reference',
+          flow: {
+            id: 'SubFlow',
+            version: '1.0.0',
+          },
+          next_step: { id: 'end', label: 'Finish' },
+        },
+        {
+          id: 'end',
+          type: 'node',
+          title: 'End',
+        },
+      ],
+    },
+  },
+  {
+    id: 'Sub/index.mdx',
+    slug: 'sub',
+    body: '',
+    collection: 'flows',
+    data: {
+      id: 'SubFlow',
+      name: 'Sub Flow',
+      version: '1.0.0',
+      steps: [
+        {
+          id: 'inner_1',
+          type: 'node',
+          title: 'Inner Step 1',
+          next_step: { id: 'inner_2' },
+        },
+        {
+          id: 'inner_2',
+          type: 'node',
+          title: 'Inner Step 2',
+        },
+      ],
+    },
+  },
+];
+
+// Three-level nesting: Outer → Middle → Leaf. Used to verify that a deep
+// sub-flow's precomputed expandedNodes/expandedEdges get their ids prefixed
+// recursively when the graph is inlined under the outer parent.
+export const mockFlowsNested = [
+  {
+    id: 'Outer/index.mdx',
+    slug: 'outer',
+    body: '',
+    collection: 'flows',
+    data: {
+      id: 'OuterFlow',
+      name: 'Outer Flow',
+      version: '1.0.0',
+      steps: [
+        {
+          id: 'outer_mid',
+          title: 'Call Middle',
+          flow: { id: 'MiddleFlow', version: '1.0.0' },
+        },
+      ],
+    },
+  },
+  {
+    id: 'Middle/index.mdx',
+    slug: 'middle',
+    body: '',
+    collection: 'flows',
+    data: {
+      id: 'MiddleFlow',
+      name: 'Middle Flow',
+      version: '1.0.0',
+      steps: [
+        {
+          id: 'middle_leaf',
+          title: 'Call Leaf',
+          flow: { id: 'LeafFlow', version: '1.0.0' },
+        },
+      ],
+    },
+  },
+  {
+    id: 'Leaf/index.mdx',
+    slug: 'leaf',
+    body: '',
+    collection: 'flows',
+    data: {
+      id: 'LeafFlow',
+      name: 'Leaf Flow',
+      version: '1.0.0',
+      steps: [
+        {
+          id: 'leaf_step_1',
+          type: 'node',
+          title: 'Leaf Step 1',
+          next_step: { id: 'leaf_step_2' },
+        },
+        {
+          id: 'leaf_step_2',
+          type: 'node',
+          title: 'Leaf Step 2',
+        },
+      ],
+    },
+  },
+];
+
+// Cycle: A references B, B references A. Expansion must terminate.
+export const mockFlowsWithCycle = [
+  {
+    id: 'A/index.mdx',
+    slug: 'a',
+    body: '',
+    collection: 'flows',
+    data: {
+      id: 'FlowA',
+      name: 'Flow A',
+      version: '1.0.0',
+      steps: [
+        {
+          id: 'a_call_b',
+          title: 'Call B',
+          flow: { id: 'FlowB', version: '1.0.0' },
+        },
+      ],
+    },
+  },
+  {
+    id: 'B/index.mdx',
+    slug: 'b',
+    body: '',
+    collection: 'flows',
+    data: {
+      id: 'FlowB',
+      name: 'Flow B',
+      version: '1.0.0',
+      steps: [
+        {
+          id: 'b_call_a',
+          title: 'Call A',
+          flow: { id: 'FlowA', version: '1.0.0' },
+        },
+      ],
+    },
+  },
+];
+
+export const mockFlowByIds = [
+  {
+    id: 'Payment/PaymentProcessed/index.mdx',
+    slug: 'payment/paymentprocessed',
+    body: '',
+    collection: 'flows',
+    data: {
+      steps: [
+        {
+          id: 1,
+          type: 'node',
+          title: 'Order Placed',
+          next_step: 2,
+        },
+        {
+          id: 2,
+          title: 'Payment Initiated',
+          message: {
+            id: 'PaymentInitiated',
+            version: '0.0.1',
+          },
+          next_steps: [3, 4],
+        },
+        {
+          id: 3,
+          title: 'Payment Processed',
+          message: {
+            id: 'PaymentProcessed',
+            version: '0.0.1',
+          },
+        },
+        {
+          id: 4,
+          type: 'node',
+          title: 'Payment Failed',
+        },
+      ],
+      id: 'PaymentFlow',
+      name: 'Payment Flow for E-commerce',
+      summary: 'Business flow for processing payments in an e-commerce platform',
+      version: '1.0.0',
+      type: 'node',
+    },
+  },
+  {
+    id: 'Orders/DataStoreFlow/index.mdx',
+    slug: 'orders/datastoreflow',
+    body: '',
+    collection: 'flows',
+    data: {
+      steps: [
+        {
+          id: 'orders-service',
+          title: 'Orders Service',
+          service: {
+            id: 'SubscriptionService',
+            version: 'latest',
+          },
+          next_step: 'orders-db',
+        },
+        {
+          id: 'orders-db',
+          title: 'Orders DB',
+          container: {
+            id: 'OrdersDB',
+          },
+        },
+      ],
+      id: 'DataStoreFlow',
+      name: 'Data Store Flow',
+      summary: 'Flow that includes a data store',
+      version: '1.0.0',
+    },
+  },
+  {
+    id: 'Orders/DataProductFlow/index.mdx',
+    slug: 'orders/dataproductflow',
+    body: '',
+    collection: 'flows',
+    data: {
+      steps: [
+        {
+          id: 'orders-service',
+          title: 'Orders Service',
+          service: {
+            id: 'SubscriptionService',
+            version: 'latest',
+          },
+          next_step: 'order-analytics',
+        },
+        {
+          id: 'order-analytics',
+          title: 'Order Analytics',
+          dataProduct: {
+            id: 'OrderAnalytics',
+          },
+        },
+        {
+          id: 'fraud-review',
+          title: 'Fraud Review',
+          agent: {
+            id: 'FraudReviewAgent',
+          },
+        },
+      ],
+      id: 'DataProductFlow',
+      name: 'Data Product Flow',
+      summary: 'Flow that includes a data product',
+      version: '1.0.0',
+    },
+  },
+  {
+    id: 'Subscriptions/CancelSubscription/index.mdx',
+    slug: 'subscriptions/CancelSubscription',
+    body: '',
+    collection: 'flows',
+    data: {
+      steps: [
+        {
+          id: 'cancel_subscription_initiated',
+          title: 'Cancels Subscription',
+          actor: {
+            name: 'User',
+          },
+          next_step: {
+            id: 'cancel_subscription_request',
+            label: 'Initiate subscription cancellation',
+          },
+        },
+        {
+          id: 'cancel_subscription_request',
+          title: 'Cancel Subscription',
+          message: {
+            id: 'CancelSubscription',
+            version: '0.0.1',
+          },
+          next_step: {
+            id: 'subscription_service',
+            label: 'Proceed to subscription service',
+          },
+        },
+        {
+          id: 'subscription_service',
+          title: 'Subscription Service',
+          service: {
+            id: 'SubscriptionService',
+            version: 'latest',
+          },
+          next_steps: [
+            {
+              id: 'subscription_cancelled',
+              label: 'Successful cancellation',
+            },
+            {
+              id: 'subscription_rejected',
+              label: 'Failed cancellation',
+            },
+          ],
+        },
+        {
+          id: 'subscription_cancelled',
+          title: 'Subscription has been cancelled',
+          message: {
+            id: 'UserSubscriptionCancelled',
+            version: '0.0.1',
+          },
+        },
+        {
+          id: 'subscription_rejected',
+          title: 'Subscription cancellation has been rejected',
+        },
+      ],
+      id: 'CancelSubscription',
+      name: 'User Cancels Subscription',
+      summary: 'Flow for when a user has cancelled a subscription',
+      version: '1.0.0',
+      // type: 'node',
+    },
+  },
+];
diff --git a/packages/core/eventcatalog/src/utils/__tests__/flows/node-graph.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/flows/node-graph.spec.ts
new file mode 100644
index 000000000..73a6d1222
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/flows/node-graph.spec.ts
@@ -0,0 +1,407 @@
+import { getNodesAndEdges } from '../../node-graphs/flows-node-graph';
+import { expect, describe, it, vi, beforeEach } from 'vitest';
+import { mockAgents, mockContainers, mockDataProducts, mockEvents, mockFlow, mockFlowByIds, mockServices } from './mocks';
+import { getCollection } from 'astro:content';
+let expectedNodes: any;
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    // this will only affect "foo" outside of the original module
+    getCollection: (key: string) => {
+      if (key === 'flows') {
+        return Promise.resolve(mockFlow);
+      }
+      if (key === 'events') {
+        return Promise.resolve(mockEvents);
+      }
+      if (key === 'services') {
+        return Promise.resolve(mockServices);
+      }
+      if (key === 'agents') {
+        return Promise.resolve(mockAgents);
+      }
+      if (key === 'containers') {
+        return Promise.resolve(mockContainers);
+      }
+      if (key === 'data-products') {
+        return Promise.resolve(mockDataProducts);
+      }
+      return Promise.resolve([]);
+    },
+  };
+});
+
+describe('Flows NodeGraph', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    expectedNodes = [
+      {
+        id: 'step-1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.anything(),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'step',
+      },
+      {
+        id: 'step-2',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.anything(),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'events',
+      },
+      {
+        id: 'step-3',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: {
+          mode: 'simple',
+          step: {
+            id: 3,
+            title: 'Payment Processed',
+            message: {
+              slug: 'PaymentProcessed',
+              collection: 'events',
+              data: {
+                id: 'PaymentProcessed',
+                version: '0.0.1',
+              },
+            },
+            type: 'events',
+          },
+          showTarget: true,
+          showSource: true,
+          message: {
+            slug: 'PaymentProcessed',
+            collection: 'events',
+            data: {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+            },
+            id: 'PaymentProcessed',
+            version: '0.0.1',
+          },
+          contextMenu: expect.any(Array),
+        },
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'events',
+      },
+      {
+        id: 'step-4',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: {
+          mode: 'simple',
+          step: {
+            id: 4,
+            type: 'step',
+            title: 'Payment Failed',
+          },
+          showTarget: true,
+          showSource: true,
+        },
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'step',
+      },
+    ];
+  });
+
+  describe('getNodesAndEdges', () => {
+    it('should return the correct nodes and edges for a given flow', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'PaymentFlow', version: '1.0.0' });
+
+      const expectedEdges = [
+        {
+          id: 'step-1-step-2',
+          source: 'step-1',
+          target: 'step-2',
+          type: 'flow-edge',
+          animated: true,
+          markerEnd: expect.objectContaining({ type: 'arrowclosed' }),
+          style: expect.any(Object),
+        },
+      ];
+
+      expect(nodes).toEqual(expect.arrayContaining(expectedNodes));
+
+      expect(edges).toEqual(expect.arrayContaining([expect.objectContaining(expectedEdges[0])]));
+    });
+
+    it('attaches a contextMenu to message step nodes so right-click shows the custom menu (issue #2216)', async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'PaymentFlow', version: '1.0.0' });
+
+      const messageNode = nodes.find((n: any) => n.id === 'step-3');
+      expect(messageNode).toBeDefined();
+      expect(messageNode?.data.contextMenu).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            label: 'Read documentation',
+            href: expect.stringContaining('/docs/events/PaymentProcessed/0.0.1'),
+          }),
+          expect.objectContaining({ label: 'Read changelog' }),
+        ])
+      );
+    });
+
+    it('attaches a contextMenu to service step nodes', async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'CancelSubscription', version: '1.0.0' });
+
+      const serviceNode = nodes.find((n: any) => n.data?.service?.data?.id === 'SubscriptionService');
+      expect(serviceNode).toBeDefined();
+      expect(serviceNode?.data.contextMenu).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            label: 'Read documentation',
+            href: expect.stringContaining('/docs/services/SubscriptionService/0.0.1'),
+          }),
+        ])
+      );
+    });
+
+    it('resolves agent step nodes and attaches an agent context menu', async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'DataProductFlow', version: '1.0.0' });
+
+      const agentNode = nodes.find((n: any) => n.id === 'step-fraud-review');
+
+      expect(agentNode).toEqual(
+        expect.objectContaining({
+          type: 'agents',
+          data: expect.objectContaining({
+            agent: expect.objectContaining({
+              id: 'FraudReviewAgent',
+              version: '1.0.0',
+            }),
+            contextMenu: expect.arrayContaining([
+              expect.objectContaining({
+                label: 'Read documentation',
+                href: expect.stringContaining('/docs/agents/FraudReviewAgent/1.0.0'),
+              }),
+            ]),
+          }),
+        })
+      );
+    });
+
+    it('resolves container step nodes to the latest container version when no version is given', async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'DataStoreFlow', version: '1.0.0' });
+
+      const containerNode = nodes.find((n: any) => n.id === 'step-orders-db');
+
+      expect(containerNode).toEqual(
+        expect.objectContaining({
+          type: 'data',
+          data: expect.objectContaining({
+            data: expect.objectContaining({
+              id: 'OrdersDB',
+              version: '1.0.0',
+              container_type: 'database',
+            }),
+            container: expect.objectContaining({
+              id: 'OrdersDB',
+              version: '1.0.0',
+            }),
+            contextMenu: expect.arrayContaining([
+              expect.objectContaining({
+                label: 'Read documentation',
+                href: expect.stringContaining('/docs/containers/OrdersDB/1.0.0'),
+              }),
+            ]),
+          }),
+        })
+      );
+    });
+
+    it('resolves data product step nodes to the latest data product version when no version is given', async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'DataProductFlow', version: '1.0.0' });
+
+      const dataProductNode = nodes.find((n: any) => n.id === 'step-order-analytics');
+
+      expect(dataProductNode).toEqual(
+        expect.objectContaining({
+          type: 'data-products',
+          data: expect.objectContaining({
+            dataProduct: expect.objectContaining({
+              id: 'OrderAnalytics',
+              version: '1.0.0',
+            }),
+            contextMenu: expect.arrayContaining([
+              expect.objectContaining({
+                label: 'Read documentation',
+                href: expect.stringContaining('/docs/data-products/OrderAnalytics/1.0.0'),
+              }),
+            ]),
+          }),
+        })
+      );
+    });
+
+    it('does not attach a contextMenu to plain step nodes (no resource)', async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'PaymentFlow', version: '1.0.0' });
+
+      const plainStep = nodes.find((n: any) => n.id === 'step-1');
+      expect(plainStep).toBeDefined();
+      expect(plainStep?.data.contextMenu).toBeUndefined();
+    });
+
+    it('should resolves the correct node when it is a service with version as latest', async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'CancelSubscription', version: '1.0.0' });
+
+      expect(nodes).toContainEqual(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            step: expect.objectContaining({
+              type: 'services',
+              service: expect.objectContaining({
+                data: {
+                  id: 'SubscriptionService',
+                  version: '0.0.1',
+                },
+              }),
+            }),
+          }),
+        })
+      );
+    });
+
+    describe('when steps are referenced only by id', () => {
+      it('should return the correct nodes and edges', async () => {
+        // TODO: This mock seems to be overriding the first mock...
+        // Mock
+        vi.mock('astro:content', async (importOriginal) => {
+          return {
+            ...(await importOriginal<typeof import('astro:content')>()),
+            // this will only affect "foo" outside of the original module
+            getCollection: (key: string) => {
+              if (key === 'flows') {
+                return Promise.resolve(mockFlowByIds);
+              }
+              if (key === 'events') {
+                return Promise.resolve(mockEvents);
+              }
+              if (key === 'services') {
+                return Promise.resolve(mockServices);
+              }
+              if (key === 'agents') {
+                return Promise.resolve(mockAgents);
+              }
+              if (key === 'containers') {
+                return Promise.resolve(mockContainers);
+              }
+              if (key === 'data-products') {
+                return Promise.resolve(mockDataProducts);
+              }
+              return Promise.resolve([]);
+            },
+          };
+        });
+
+        const { nodes, edges } = await getNodesAndEdges({ id: 'PaymentFlow', version: '1.0.0' });
+
+        const expectedNodes = [
+          {
+            id: 'step-1',
+            sourcePosition: 'right',
+            targetPosition: 'left',
+            data: expect.anything(),
+            position: { x: expect.any(Number), y: expect.any(Number) },
+            type: 'step',
+          },
+          {
+            id: 'step-2',
+            sourcePosition: 'right',
+            targetPosition: 'left',
+            data: expect.anything(),
+            position: { x: expect.any(Number), y: expect.any(Number) },
+            type: 'events',
+          },
+          {
+            id: 'step-3',
+            sourcePosition: 'right',
+            targetPosition: 'left',
+            data: {
+              mode: 'simple',
+              step: {
+                id: 3,
+                title: 'Payment Processed',
+                message: {
+                  slug: 'PaymentProcessed',
+                  collection: 'events',
+                  data: {
+                    id: 'PaymentProcessed',
+                    version: '0.0.1',
+                  },
+                },
+                type: 'events',
+              },
+              showTarget: true,
+              showSource: true,
+              message: {
+                slug: 'PaymentProcessed',
+                collection: 'events',
+                data: {
+                  id: 'PaymentProcessed',
+                  version: '0.0.1',
+                },
+                id: 'PaymentProcessed',
+                version: '0.0.1',
+              },
+              contextMenu: expect.any(Array),
+            },
+            position: { x: expect.any(Number), y: expect.any(Number) },
+            type: 'events',
+          },
+          {
+            id: 'step-4',
+            sourcePosition: 'right',
+            targetPosition: 'left',
+            data: {
+              mode: 'simple',
+              step: {
+                id: 4,
+                type: 'step',
+                title: 'Payment Failed',
+              },
+              showTarget: true,
+              showSource: true,
+            },
+            position: { x: expect.any(Number), y: expect.any(Number) },
+            type: 'step',
+          },
+        ];
+
+        const expectedEdges = [
+          {
+            id: 'step-1-step-2',
+            source: 'step-1',
+            target: 'step-2',
+            type: 'flow-edge',
+            animated: true,
+            markerEnd: expect.objectContaining({ type: 'arrowclosed' }),
+            style: expect.any(Object),
+          },
+        ];
+
+        expect(nodes).toEqual(expect.arrayContaining(expectedNodes));
+        expect(edges).toEqual(expect.arrayContaining([expect.objectContaining(expectedEdges[0])]));
+      });
+    });
+
+    it('should populate actor node data with name and summary from the actor step', async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'CancelSubscription', version: '1.0.0' });
+
+      const actorNode = nodes.find((node: any) => node.type === 'actor');
+
+      expect(actorNode).toBeDefined();
+      expect(actorNode?.data?.name).toBe('User');
+    });
+
+    it('returns empty nodes and edges if no flow is found', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownFlow', version: '1.0.0' });
+
+      expect(nodes).toEqual([]);
+      expect(edges).toEqual([]);
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/flows/sub-flow-expansion.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/flows/sub-flow-expansion.spec.ts
new file mode 100644
index 000000000..e40cb6d65
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/flows/sub-flow-expansion.spec.ts
@@ -0,0 +1,109 @@
+import { expect, describe, it, vi } from 'vitest';
+import { mockFlowsWithSubFlow, mockFlowsWithCycle, mockFlowsNested } from './mocks';
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: (key: string) => {
+      if (key === 'flows') {
+        // @ts-expect-error runtime swap via globalThis
+        return Promise.resolve(globalThis.__flowsMock ?? []);
+      }
+      return Promise.resolve([]);
+    },
+  };
+});
+
+// Import after vi.mock so the module picks up the mocked astro:content
+const { getNodesAndEdges } = await import('../../node-graphs/flows-node-graph');
+
+const withFlowsMock = async (mock: any[], run: () => Promise<void>) => {
+  // @ts-expect-error test shim
+  globalThis.__flowsMock = mock;
+  try {
+    await run();
+  } finally {
+    // @ts-expect-error test shim
+    delete globalThis.__flowsMock;
+  }
+};
+
+describe('Flows NodeGraph — sub-flow expansion precompute', () => {
+  it('attaches expandedNodes and expandedEdges to a step that references another flow', async () => {
+    await withFlowsMock(mockFlowsWithSubFlow, async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'ParentFlow', version: '1.0.0' });
+
+      const subNode = nodes.find((n: any) => n.id === 'step-sub');
+      expect(subNode).toBeDefined();
+      expect(subNode?.type).toBe('flows');
+      expect(Array.isArray(subNode?.data.expandedNodes)).toBe(true);
+      expect(Array.isArray(subNode?.data.expandedEdges)).toBe(true);
+      expect(subNode?.data.expandedNodes.length).toBe(2);
+      expect(subNode?.data.expandedEdges.length).toBe(1);
+    });
+  });
+
+  it('namespaces child node ids with the parent step node id', async () => {
+    await withFlowsMock(mockFlowsWithSubFlow, async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'ParentFlow', version: '1.0.0' });
+
+      const subNode = nodes.find((n: any) => n.id === 'step-sub');
+      const childIds = subNode?.data.expandedNodes.map((n: any) => n.id);
+      expect(childIds).toEqual(expect.arrayContaining(['step-sub__step-inner_1', 'step-sub__step-inner_2']));
+    });
+  });
+
+  it('namespaces expanded edges to reference the child node ids', async () => {
+    await withFlowsMock(mockFlowsWithSubFlow, async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'ParentFlow', version: '1.0.0' });
+
+      const subNode = nodes.find((n: any) => n.id === 'step-sub');
+      const edge = subNode?.data.expandedEdges[0];
+      expect(edge.source).toBe('step-sub__step-inner_1');
+      expect(edge.target).toBe('step-sub__step-inner_2');
+    });
+  });
+
+  it('prefixes nested expandedNodes recursively so deep sub-flows get unique ids', async () => {
+    await withFlowsMock(mockFlowsNested, async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'OuterFlow', version: '1.0.0' });
+
+      const middleRef = nodes.find((n: any) => n.id === 'step-outer_mid');
+      expect(middleRef).toBeDefined();
+
+      const middleChild = middleRef?.data.expandedNodes[0];
+      expect(middleChild.id).toBe('step-outer_mid__step-middle_leaf');
+
+      // The leaf sub-flow's expansion payload, nested inside MiddleFlow, must
+      // also carry the outer prefix so its ids stay unique across parents.
+      const leafChildren = middleChild.data.expandedNodes;
+      const leafIds = leafChildren.map((c: any) => c.id);
+      expect(leafIds).toEqual(
+        expect.arrayContaining([
+          'step-outer_mid__step-middle_leaf__step-leaf_step_1',
+          'step-outer_mid__step-middle_leaf__step-leaf_step_2',
+        ])
+      );
+      const leafEdges = middleChild.data.expandedEdges;
+      expect(leafEdges[0].source).toBe('step-outer_mid__step-middle_leaf__step-leaf_step_1');
+      expect(leafEdges[0].target).toBe('step-outer_mid__step-middle_leaf__step-leaf_step_2');
+    });
+  });
+
+  it('does not infinitely recurse on flow cycles (A → B → A)', async () => {
+    await withFlowsMock(mockFlowsWithCycle, async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'FlowA', version: '1.0.0' });
+
+      const callB = nodes.find((n: any) => n.id === 'step-a_call_b');
+      expect(callB).toBeDefined();
+      // FlowA → FlowB is expanded (one level deep)
+      expect(Array.isArray(callB?.data.expandedNodes)).toBe(true);
+      expect(callB?.data.expandedNodes.length).toBe(1);
+
+      // The nested FlowB → FlowA reference must not re-expand (it's in visited)
+      const innerCallA = callB?.data.expandedNodes[0];
+      expect(innerCallA.id).toBe('step-a_call_b__step-b_call_a');
+      expect(innerCallA.data.expandedNodes).toBeUndefined();
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/json-schema-refs.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/json-schema-refs.spec.ts
new file mode 100644
index 000000000..5d3bf68cf
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/json-schema-refs.spec.ts
@@ -0,0 +1,117 @@
+import { describe, expect, it, vi } from 'vitest';
+import { resolveSchemaRefs } from '@utils/json-schema-refs';
+
+const createJsonResponse = (body: unknown) =>
+  new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {
+      'content-type': 'application/json',
+    },
+  });
+
+describe('resolveSchemaRefs', () => {
+  it('resolves external JSON schema refs and nested local refs in the external document', async () => {
+    const schema = {
+      type: 'object',
+      required: ['data'],
+      properties: {
+        data: {
+          description: 'Template draft payload.',
+          $ref: 'http://example.com/common-schema.json#/components/schemas/TemplateDraftedData',
+        },
+      },
+    };
+    const commonSchema = {
+      components: {
+        schemas: {
+          TemplateDraftedData: {
+            type: 'object',
+            required: ['templateId', 'content'],
+            properties: {
+              templateId: { type: 'string' },
+              content: {
+                $ref: '#/components/schemas/TemplateContent',
+              },
+            },
+          },
+          TemplateContent: {
+            type: 'object',
+            required: ['subject'],
+            properties: {
+              subject: { type: 'string' },
+            },
+          },
+        },
+      },
+    };
+    const fetcher = vi.fn(async () => createJsonResponse(commonSchema));
+
+    await expect(
+      resolveSchemaRefs(schema, {
+        baseUrl: 'http://example.com/event-schema.json',
+        fetcher,
+      })
+    ).resolves.toEqual({
+      type: 'object',
+      required: ['data'],
+      properties: {
+        data: {
+          type: 'object',
+          description: 'Template draft payload.',
+          required: ['templateId', 'content'],
+          properties: {
+            templateId: { type: 'string' },
+            content: {
+              type: 'object',
+              required: ['subject'],
+              properties: {
+                subject: { type: 'string' },
+              },
+            },
+          },
+        },
+      },
+    });
+    expect(fetcher).toHaveBeenCalledTimes(1);
+    expect(fetcher).toHaveBeenCalledWith('http://example.com/common-schema.json', { headers: undefined });
+  });
+
+  it('resolves relative external refs from the current schema URL', async () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        user: {
+          $ref: './shared/user.json#/User',
+        },
+      },
+    };
+    const fetcher = vi.fn(async () =>
+      createJsonResponse({
+        User: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+          },
+        },
+      })
+    );
+
+    await expect(
+      resolveSchemaRefs(schema, {
+        baseUrl: 'http://example.com/schemas/event.json',
+        fetcher,
+      })
+    ).resolves.toEqual({
+      type: 'object',
+      properties: {
+        user: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+          },
+        },
+      },
+    });
+    expect(fetcher).toHaveBeenCalledWith('http://example.com/schemas/shared/user.json', { headers: undefined });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/llms.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/llms.spec.ts
new file mode 100644
index 000000000..0a0fcd001
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/llms.spec.ts
@@ -0,0 +1,56 @@
+import { filterMarkdownForAgents, filterMarkdownForAudience } from '@utils/llms';
+
+describe('llms', () => {
+  describe('filterMarkdownForAudience', () => {
+    it('keeps agent visibility content and removes human visibility content for markdown endpoints', () => {
+      const markdown = `---
+id: OrderCreated
+---
+
+# Order Created
+
+<Visibility for="humans">
+Click the **Create order** button in the UI.
+</Visibility>
+
+Shared content.
+
+<Visibility for="agents">
+Call \`POST /orders\` with a valid order payload.
+</Visibility>
+`;
+
+      expect(filterMarkdownForAgents(markdown)).toBe(`---
+id: OrderCreated
+---
+
+# Order Created
+
+Shared content.
+
+Call \`POST /orders\` with a valid order payload.`);
+    });
+
+    it('supports single quoted and expression quoted visibility props', () => {
+      const markdown = `<Visibility for='agents'>
+Agent content
+</Visibility>
+
+<Visibility for={"humans"}>
+Human content
+</Visibility>`;
+
+      expect(filterMarkdownForAudience(markdown, 'humans')).toBe('Human content');
+    });
+
+    it('does not change markdown when no visibility components are present', () => {
+      const markdown = `# Plain docs
+
+Content with source formatting preserved.
+
+`;
+
+      expect(filterMarkdownForAgents(markdown)).toBe(markdown);
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/markdown.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/markdown.spec.ts
new file mode 100644
index 000000000..985b21eca
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/markdown.spec.ts
@@ -0,0 +1,26 @@
+import { getMDXComponentsByName, parseMdxBooleanProp } from '@utils/markdown';
+
+describe('markdown', () => {
+  describe('getMDXComponentsByName', () => {
+    it('takes given markdown and returns the components and their props', () => {
+      const markdown = `
+        <SchemaViewer id="test" />
+        <SchemaViewer id="test2" />
+        <SchemaViewer/>
+        `;
+      const components = getMDXComponentsByName(markdown, 'SchemaViewer');
+      expect(components).toEqual([{ id: 'test' }, { id: 'test2' }, {}]);
+    });
+  });
+
+  describe('parseMdxBooleanProp', () => {
+    it('parses boolean and string boolean MDX props with defaults', () => {
+      expect(parseMdxBooleanProp(undefined, true)).toBe(true);
+      expect(parseMdxBooleanProp(undefined, false)).toBe(false);
+      expect(parseMdxBooleanProp(true, false)).toBe(true);
+      expect(parseMdxBooleanProp(false, true)).toBe(false);
+      expect(parseMdxBooleanProp('true', false)).toBe(true);
+      expect(parseMdxBooleanProp('false', true)).toBe(false);
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/messages/messages.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/messages/messages.spec.ts
new file mode 100644
index 000000000..daddf7e7a
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/messages/messages.spec.ts
@@ -0,0 +1,323 @@
+import type { CollectionEntry, CollectionKey } from 'astro:content';
+import { expect, describe, it, vi } from 'vitest';
+import { mockCommands, mockEvents, mockQueries, mockServices, mockChannels, mockDataProducts } from './mocks';
+import { getMessages, hydrateProducersAndConsumers } from '@utils/collections/messages';
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    async getCollection<T extends CollectionKey>(key: T, filterFn: (entry: CollectionEntry<T>) => boolean = () => true) {
+      switch (key) {
+        case 'services':
+          return mockServices.filter(filterFn as any);
+        case 'events':
+          return mockEvents.filter(filterFn as any);
+        case 'commands':
+          return mockCommands.filter(filterFn as any);
+        case 'channels':
+          return mockChannels.filter(filterFn as any);
+        case 'queries':
+          return mockQueries.filter(filterFn);
+      }
+    },
+  };
+});
+
+describe('getMessages', () => {
+  it('should return all versions of messages', async () => {
+    await expect(getMessages({ getAllVersions: true })).resolves.toEqual(
+      expect.objectContaining({
+        events: expect.arrayContaining([
+          expect.objectContaining({
+            collection: 'events',
+            data: expect.objectContaining({
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+            }),
+          }),
+          expect.objectContaining({
+            collection: 'events',
+            data: expect.objectContaining({
+              id: 'PaymentProcessed',
+              version: '0.0.2',
+            }),
+          }),
+          expect.objectContaining({
+            collection: 'events',
+            data: expect.objectContaining({
+              id: 'PaymentProcessed',
+              version: '0.1.0',
+            }),
+          }),
+        ]),
+      })
+    );
+  });
+
+  it('should return current versions of messages', async () => {
+    await expect(getMessages({ getAllVersions: false })).resolves.toEqual(
+      expect.objectContaining({
+        commands: expect.arrayContaining([
+          expect.objectContaining({
+            collection: 'commands',
+            data: expect.objectContaining({
+              id: 'ProcessPayment',
+              version: '0.1.0',
+            }),
+          }),
+        ]),
+        events: expect.arrayContaining([
+          expect.objectContaining({
+            collection: 'events',
+            data: expect.objectContaining({
+              id: 'PaymentProcessed',
+              version: '0.1.0',
+            }),
+          }),
+        ]),
+      })
+    );
+  });
+
+  it('should return current versions even if the first call is to get all versions', async () => {
+    await getMessages({ getAllVersions: true });
+
+    const messages = await getMessages({ getAllVersions: false });
+
+    expect(messages).toEqual(
+      expect.objectContaining({
+        queries: [],
+        commands: expect.arrayContaining([
+          expect.objectContaining({
+            collection: 'commands',
+            data: expect.objectContaining({
+              id: 'ProcessPayment',
+              version: '0.1.0',
+            }),
+          }),
+        ]),
+        events: expect.arrayContaining([
+          expect.objectContaining({
+            collection: 'events',
+            data: expect.objectContaining({
+              id: 'PaymentProcessed',
+              version: '0.1.0',
+            }),
+          }),
+        ]),
+      })
+    );
+  });
+
+  it('should return all version even if the first call is to get current versions', async () => {
+    await getMessages({ getAllVersions: false });
+
+    const messages = await getMessages({ getAllVersions: true });
+
+    expect(messages).toEqual(
+      expect.objectContaining({
+        commands: expect.arrayContaining([
+          expect.objectContaining({
+            collection: 'commands',
+            data: expect.objectContaining({
+              id: 'ProcessPayment',
+              version: '0.0.1',
+            }),
+          }),
+          expect.objectContaining({
+            collection: 'commands',
+            data: expect.objectContaining({
+              id: 'ProcessPayment',
+              version: '0.0.2',
+            }),
+          }),
+          expect.objectContaining({
+            collection: 'commands',
+            data: expect.objectContaining({
+              id: 'ProcessPayment',
+              version: '0.1.0',
+            }),
+          }),
+        ]),
+      })
+    );
+  });
+});
+
+describe('hydrateProducersAndConsumers', () => {
+  describe('service producers', () => {
+    it('should find services that send a message', () => {
+      const message = { data: { id: 'PaymentProcessed', version: '0.0.1', latestVersion: '0.1.0' } };
+
+      const { producers } = hydrateProducersAndConsumers({
+        message,
+        services: mockServices as any,
+        dataProducts: [],
+      });
+
+      expect(producers).toHaveLength(2);
+      expect(producers.map((p: any) => p.data.id)).toContain('ServiceThatProducesMessages');
+      expect(producers.map((p: any) => p.data.id)).toContain('ServiceThatProducesMessagesOverManyChannels');
+    });
+  });
+
+  describe('service consumers', () => {
+    it('should find services that receive a message', () => {
+      const message = { data: { id: 'PaymentProcessed', version: '0.0.1', latestVersion: '0.1.0' } };
+
+      const { consumers } = hydrateProducersAndConsumers({
+        message,
+        services: mockServices as any,
+        dataProducts: [],
+      });
+
+      expect(consumers).toHaveLength(2);
+      expect(consumers.map((c: any) => c.data.id)).toContain('OrdersService');
+      expect(consumers.map((c: any) => c.data.id)).toContain('ServiceThatReceivesMessagesFromAChannel');
+    });
+  });
+
+  describe('data product producers', () => {
+    it('should find data products that output a message', () => {
+      const message = { data: { id: 'PaymentProcessed', version: '0.0.1', latestVersion: '0.1.0' } };
+
+      const { producers } = hydrateProducersAndConsumers({
+        message,
+        services: [],
+        dataProducts: mockDataProducts as any,
+      });
+
+      expect(producers).toHaveLength(1);
+      expect(producers[0]).toMatchObject({
+        data: { id: 'OrderDataPipeline' },
+      });
+    });
+  });
+
+  describe('data product consumers', () => {
+    it('should find data products that input a message', () => {
+      const message = { data: { id: 'PaymentProcessed', version: '0.0.1', latestVersion: '0.1.0' } };
+
+      const { consumers } = hydrateProducersAndConsumers({
+        message,
+        services: [],
+        dataProducts: mockDataProducts as any,
+      });
+
+      expect(consumers).toHaveLength(1);
+      expect(consumers[0]).toMatchObject({
+        data: { id: 'PaymentAnalytics' },
+      });
+    });
+  });
+
+  describe('combined services and data products', () => {
+    it('should find both services and data products as producers and consumers', () => {
+      const message = { data: { id: 'PaymentProcessed', version: '0.0.1', latestVersion: '0.1.0' } };
+
+      const { producers, consumers } = hydrateProducersAndConsumers({
+        message,
+        services: mockServices as any,
+        dataProducts: mockDataProducts as any,
+      });
+
+      // 2 services + 1 data product = 3 producers
+      expect(producers).toHaveLength(3);
+
+      // 2 services + 1 data product = 3 consumers
+      expect(consumers).toHaveLength(3);
+    });
+  });
+
+  describe('version matching', () => {
+    it('should match "latest" version pointer to the latest version of the message', () => {
+      // The message IS the latest version (0.1.0)
+      const message = { data: { id: 'PaymentProcessed', version: '0.1.0', latestVersion: '0.1.0' } };
+
+      const { producers, consumers } = hydrateProducersAndConsumers({
+        message,
+        services: [],
+        dataProducts: mockDataProducts as any,
+      });
+
+      // DataProductWithLatestVersion should match since it points to 'latest'
+      expect(producers.map((p: any) => p.data.id)).toContain('DataProductWithLatestVersion');
+      expect(consumers.map((c: any) => c.data.id)).toContain('DataProductWithLatestVersion');
+    });
+
+    it('should not match "latest" version pointer to non-latest versions', () => {
+      // The message is NOT the latest version
+      const message = { data: { id: 'PaymentProcessed', version: '0.0.1', latestVersion: '0.1.0' } };
+
+      const { producers, consumers } = hydrateProducersAndConsumers({
+        message,
+        services: [],
+        dataProducts: mockDataProducts as any,
+      });
+
+      // DataProductWithLatestVersion should NOT match since 0.0.1 is not latest
+      expect(producers.map((p: any) => p.data.id)).not.toContain('DataProductWithLatestVersion');
+      expect(consumers.map((c: any) => c.data.id)).not.toContain('DataProductWithLatestVersion');
+    });
+  });
+
+  describe('hydration', () => {
+    it('should return full objects when hydrate is true (default)', () => {
+      const message = { data: { id: 'PaymentProcessed', version: '0.0.1', latestVersion: '0.1.0' } };
+
+      const { producers } = hydrateProducersAndConsumers({
+        message,
+        services: mockServices as any,
+        dataProducts: [],
+        hydrate: true,
+      });
+
+      // Should have full service object with all properties
+      expect(producers[0]).toHaveProperty('collection');
+      expect(producers[0]).toHaveProperty('data.pathToFile');
+    });
+
+    it('should return minimal objects when hydrate is false', () => {
+      const message = { data: { id: 'PaymentProcessed', version: '0.0.1', latestVersion: '0.1.0' } };
+
+      const { producers } = hydrateProducersAndConsumers({
+        message,
+        services: mockServices as any,
+        dataProducts: [],
+        hydrate: false,
+      });
+
+      // Should only have id and version
+      expect(producers[0]).toEqual({ id: 'ServiceThatProducesMessages', version: '1.0.0' });
+      expect(producers[0]).not.toHaveProperty('collection');
+    });
+  });
+
+  describe('empty collections', () => {
+    it('should return empty arrays when no services or data products are provided', () => {
+      const message = { data: { id: 'PaymentProcessed', version: '0.0.1', latestVersion: '0.1.0' } };
+
+      const { producers, consumers } = hydrateProducersAndConsumers({
+        message,
+        services: [],
+        dataProducts: [],
+      });
+
+      expect(producers).toEqual([]);
+      expect(consumers).toEqual([]);
+    });
+
+    it('should return empty arrays when message has no matching producers or consumers', () => {
+      const message = { data: { id: 'NonExistentMessage', version: '1.0.0', latestVersion: '1.0.0' } };
+
+      const { producers, consumers } = hydrateProducersAndConsumers({
+        message,
+        services: mockServices as any,
+        dataProducts: mockDataProducts as any,
+      });
+
+      expect(producers).toEqual([]);
+      expect(consumers).toEqual([]);
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/messages/mocks.ts b/packages/core/eventcatalog/src/utils/__tests__/messages/mocks.ts
new file mode 100644
index 000000000..367983ded
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/messages/mocks.ts
@@ -0,0 +1,268 @@
+export const mockCommands = [
+  {
+    id: 'ProcessPayment',
+    collection: 'commands',
+    data: {
+      id: 'ProcessPayment',
+      version: '0.0.1',
+      pathToFile: 'commands/ProcessPayment/versioned/0.0.1/index.md',
+    },
+  },
+  {
+    id: 'ProcessPayment',
+    collection: 'commands',
+    data: {
+      id: 'ProcessPayment',
+      version: '0.0.2',
+      pathToFile: 'commands/ProcessPayment/versioned/0.0.2/index.md',
+    },
+  },
+  {
+    id: 'ProcessPayment',
+    collection: 'commands',
+    data: {
+      id: 'ProcessPayment',
+      version: '0.1.0',
+      pathToFile: 'commands/ProcessPayment/index.md',
+    },
+  },
+];
+
+export const mockEvents = [
+  {
+    id: 'PaymentProcessed',
+    collection: 'events',
+    data: {
+      id: 'PaymentProcessed',
+      version: '0.0.1',
+      pathToFile: 'events/PaymentProcessed/versioned/0.0.1/index.md',
+    },
+  },
+  {
+    id: 'PaymentProcessed',
+    collection: 'events',
+    data: {
+      id: 'PaymentProcessed',
+      version: '0.0.2',
+      pathToFile: 'events/PaymentProcessed/versioned/0.0.2/index.md',
+    },
+  },
+  {
+    id: 'PaymentProcessed',
+    collection: 'events',
+    data: {
+      id: 'PaymentProcessed',
+      version: '0.1.0',
+      pathToFile: 'events/PaymentProcessed/index.md',
+    },
+  },
+  // Additional versions for testing semver pattern matching
+  {
+    id: 'PaymentProcessed',
+    collection: 'events',
+    data: {
+      id: 'PaymentProcessed',
+      version: '1.0.0',
+      pathToFile: 'events/PaymentProcessed/versioned/1.0.0/index.md',
+    },
+  },
+  {
+    id: 'PaymentProcessed',
+    collection: 'events',
+    data: {
+      id: 'PaymentProcessed',
+      version: '1.2.3',
+      pathToFile: 'events/PaymentProcessed/versioned/1.2.3/index.md',
+    },
+  },
+  {
+    id: 'PaymentProcessed',
+    collection: 'events',
+    data: {
+      id: 'PaymentProcessed',
+      version: '1.2.5',
+      pathToFile: 'events/PaymentProcessed/versioned/1.2.5/index.md',
+    },
+  },
+  {
+    id: 'PaymentProcessed',
+    collection: 'events',
+    data: {
+      id: 'PaymentProcessed',
+      version: '1.9.9',
+      pathToFile: 'events/PaymentProcessed/versioned/1.9.9/index.md',
+    },
+  },
+  {
+    id: 'PaymentProcessed',
+    collection: 'events',
+    data: {
+      id: 'PaymentProcessed',
+      version: '2.0.0',
+      pathToFile: 'events/PaymentProcessed/versioned/2.0.0/index.md',
+    },
+  },
+];
+
+export const mockQueries = [];
+
+export const mockAgents = [
+  {
+    id: 'FraudReviewAgent',
+    collection: 'agents',
+    data: {
+      id: 'FraudReviewAgent',
+      version: '1.0.0',
+      receives: [
+        {
+          id: 'PaymentProcessed',
+          version: '0.0.1',
+        },
+      ],
+      tools: [
+        {
+          name: 'Risk profile lookup',
+          type: 'mcp',
+          icon: '/icons/tools/datadog.svg',
+          url: 'https://mcp.example.com/fraud/risk-profile',
+          description: 'Looks up fraud and payment risk signals.',
+        },
+      ],
+    },
+  },
+];
+
+export const mockServices = [
+  {
+    id: 'OrdersService',
+    collection: 'services',
+    data: {
+      id: 'OrdersService',
+      version: '1.0.0',
+      pathToFile: 'services/OrdersService/index.md',
+      receives: [
+        {
+          id: 'PaymentProcessed',
+          version: '0.0.1',
+        },
+      ],
+    },
+  },
+  {
+    id: 'ServiceThatReceivesMessagesFromAChannel',
+    collection: 'services',
+    data: {
+      id: 'ServiceThatReceivesMessagesFromAChannel',
+      version: '1.0.0',
+      pathToFile: 'services/OrdersService/index.md',
+      receives: [
+        {
+          id: 'PaymentProcessed',
+          version: '0.0.1',
+          from: [{ id: 'EmailChannel', version: '1.0.0' }],
+        },
+      ],
+    },
+  },
+  {
+    id: 'ServiceThatProducesMessages',
+    collection: 'services',
+    data: {
+      id: 'ServiceThatProducesMessages',
+      version: '1.0.0',
+      pathToFile: 'services/ServiceThatProducesMessages/index.md',
+      sends: [
+        {
+          id: 'PaymentProcessed',
+          version: '0.0.1',
+        },
+      ],
+    },
+  },
+  {
+    id: 'ServiceThatProducesMessagesOverManyChannels',
+    collection: 'services',
+    data: {
+      id: 'ServiceThatProducesMessagesOverManyChannels',
+      version: '1.0.0',
+      pathToFile: 'services/ServiceThatProducesMessagesOverManyChannels/index.md',
+      sends: [
+        {
+          id: 'PaymentProcessed',
+          version: '0.0.1',
+          to: [
+            { id: 'EmailChannel', version: '1.0.0' },
+            { id: 'SNSChannel', version: '1.0.0' },
+            { id: 'SQSChannel', version: '1.0.0' },
+          ],
+        },
+      ],
+    },
+  },
+];
+
+export const mockChannels = [
+  {
+    id: 'EmailChannel',
+    collection: 'channels',
+    data: {
+      id: 'EmailChannel',
+      version: '1.0.0',
+      pathToFile: 'channels/EmailChannel/index.md',
+    },
+  },
+  {
+    id: 'SNSChannel',
+    collection: 'channels',
+    data: {
+      id: 'SNSChannel',
+      version: '1.0.0',
+      pathToFile: 'channels/SmsChannel/index.md',
+    },
+  },
+  {
+    id: 'SQSChannel',
+    collection: 'channels',
+    data: {
+      id: 'SQSChannel',
+      version: '1.0.0',
+      pathToFile: 'channels/SQSChannel/index.md',
+    },
+  },
+];
+
+export const mockDataProducts = [
+  {
+    id: 'PaymentAnalytics-1.0.0',
+    collection: 'data-products',
+    data: {
+      id: 'PaymentAnalytics',
+      name: 'Payment Analytics',
+      version: '1.0.0',
+      inputs: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+      outputs: [],
+    },
+  },
+  {
+    id: 'OrderDataPipeline-1.0.0',
+    collection: 'data-products',
+    data: {
+      id: 'OrderDataPipeline',
+      name: 'Order Data Pipeline',
+      version: '1.0.0',
+      inputs: [],
+      outputs: [{ id: 'PaymentProcessed', version: '0.0.1' }],
+    },
+  },
+  {
+    id: 'DataProductWithLatestVersion-1.0.0',
+    collection: 'data-products',
+    data: {
+      id: 'DataProductWithLatestVersion',
+      name: 'Data Product With Latest Version',
+      version: '1.0.0',
+      inputs: [{ id: 'PaymentProcessed', version: 'latest' }],
+      outputs: [{ id: 'PaymentProcessed', version: 'latest' }],
+    },
+  },
+];
diff --git a/packages/core/eventcatalog/src/utils/__tests__/messages/node-graph.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/messages/node-graph.spec.ts
new file mode 100644
index 000000000..dc9174d1f
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/messages/node-graph.spec.ts
@@ -0,0 +1,2128 @@
+import { getNodesAndEdgesForConsumedMessage, getNodesAndEdgesForProducedMessage } from '../../node-graphs/message-node-graph';
+import { expect, describe, it, vi, beforeEach } from 'vitest';
+import { mockEvents, mockServices, mockChannels, mockAgents } from './mocks';
+import type { CollectionMessageTypes } from '@types';
+import type { CollectionEntry } from 'astro:content';
+import utils from '@eventcatalog/sdk';
+import path from 'path';
+import fs from 'fs';
+import { getProducersOfMessage, getConsumersOfMessage } from '@utils/collections/services';
+
+const CATALOG_FOLDER = path.join(__dirname, 'catalog');
+
+const toAstroCollection = (item: any, collection: string) => {
+  return {
+    id: item.id,
+    collection: collection,
+    data: item,
+  };
+};
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    // this will only affect "foo" outside of the original module
+    getCollection: (key: string) => {
+      if (key === 'services') {
+        return Promise.resolve(mockServices);
+      }
+      if (key === 'agents') {
+        return Promise.resolve(mockAgents);
+      }
+      if (key === 'channels') {
+        return Promise.resolve(mockChannels);
+      }
+      if (key === 'events') {
+        return Promise.resolve(mockEvents);
+      }
+      return Promise.resolve([]);
+    },
+  };
+});
+
+describe('Message NodeGraph', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    // Clear the catalog folder but not the folder itself
+    fs.rmSync(CATALOG_FOLDER, { recursive: true, force: true });
+    fs.mkdirSync(CATALOG_FOLDER, { recursive: true });
+  });
+
+  describe('getNodesAndEdgesForConsumedMessage', () => {
+    it('renders tools for agent consumers', async () => {
+      const message = mockEvents[0] as unknown as CollectionEntry<CollectionMessageTypes>;
+
+      const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
+        message,
+        services: mockServices as any,
+        agents: mockAgents as any,
+        channels: mockChannels as any,
+        currentNodes: [],
+        currentEdges: [],
+        source: mockServices[2] as any,
+      });
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            id: 'FraudReviewAgent-1.0.0',
+            type: 'agents',
+          }),
+          expect.objectContaining({
+            id: 'FraudReviewAgent-1.0.0-tool-risk-profile-lookup-mcp',
+            type: 'agentTool',
+            data: expect.objectContaining({
+              agentTool: expect.objectContaining({
+                name: 'Risk profile lookup',
+                type: 'mcp',
+                icon: '/icons/tools/datadog.svg',
+              }),
+            }),
+          }),
+        ])
+      );
+
+      expect(edges).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-FraudReviewAgent-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'FraudReviewAgent-1.0.0',
+          }),
+          expect.objectContaining({
+            id: 'FraudReviewAgent-1.0.0-FraudReviewAgent-1.0.0-tool-risk-profile-lookup-mcp',
+            source: 'FraudReviewAgent-1.0.0',
+            target: 'FraudReviewAgent-1.0.0-tool-risk-profile-lookup-mcp',
+            label: 'calls tool',
+            type: 'step',
+          }),
+        ])
+      );
+    });
+
+    describe('when the message is consumed by the consumer and the producer and consumer have no channels defined', () => {
+      it('takes a given message, renders the producer and connects the message to the consumer directly', async () => {
+        const message = mockEvents[0] as unknown as CollectionEntry<CollectionMessageTypes>;
+
+        const { nodes, edges } = await getNodesAndEdgesForConsumedMessage({
+          message,
+          services: mockServices as any,
+          channels: mockChannels as any,
+          currentNodes: [],
+          target: mockServices[0] as any,
+          targetChannels: [],
+        });
+
+        // The message node itself
+        const expectedEventNode = {
+          id: 'PaymentProcessed-0.0.1',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.anything(),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          type: 'events',
+        };
+
+        // The producer node itself
+        const expectedProducerNode = {
+          id: 'ServiceThatProducesMessages-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.anything(),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          type: 'services',
+        };
+
+        // The message should be connected to the given target directly
+        const expectedEdges = expect.arrayContaining([
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-OrdersService-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'OrdersService-1.0.0',
+          }),
+          expect.objectContaining({
+            id: 'ServiceThatProducesMessages-1.0.0-PaymentProcessed-0.0.1',
+            source: 'ServiceThatProducesMessages-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            // The producer that produces the message
+            expect.objectContaining(expectedProducerNode),
+            // The message node itself
+            expect.objectContaining(expectedEventNode),
+          ])
+        );
+        expect(edges).toEqual(expectedEdges);
+      });
+    });
+
+    describe('producer with a channel defined', () => {
+      it('when the producer sends a message over a channel but the consumer does not read from that channel, no channel nodes are created, and the message is connected to the consumer directly', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // The message itself
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: '## Payment Processed',
+        });
+
+        // Email Channel
+        await writeChannel({
+          id: 'SQSChannel',
+          name: 'SQS Channel',
+          version: '1.0.0',
+          markdown: '## SQS Channel',
+        });
+
+        // The Producer
+        await writeService({
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          markdown: '## Order Service',
+          sends: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              to: [{ id: 'SQSChannel', version: '1.0.0' }],
+            },
+          ],
+        });
+
+        // The Consumer
+        await writeService({
+          id: 'PaymentService',
+          name: 'Service That Receives Messages Without Channels',
+          version: '1.0.0',
+          markdown: '## Service That Receives Messages Without Channels',
+          receives: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+            },
+          ],
+        });
+
+        const message = toAstroCollection(
+          await getEvent('PaymentProcessed'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+        const channels = await getChannels().then(
+          (channels) =>
+            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
+        );
+
+        const target = toAstroCollection(
+          await getService('PaymentService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForConsumedMessage({
+          message,
+          services: services,
+          channels: channels,
+          currentNodes: [],
+          target,
+        });
+
+        const channelNodes = nodes.filter((node) => node.type === 'channels');
+
+        expect(channelNodes).toEqual([]);
+
+        const expectedEdges = expect.arrayContaining([
+          expect.objectContaining({
+            id: 'OrderService-1.0.0-PaymentProcessed-0.0.1',
+            source: 'OrderService-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+          }),
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-PaymentService-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'PaymentService-1.0.0',
+          }),
+        ]);
+
+        expect(edges).toEqual(expectedEdges);
+      });
+
+      it('when the producer sends a message over many channels only the matching channels are rendered', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // The message itself
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: '## Payment Processed',
+        });
+
+        // SQS Channel
+        await writeChannel({
+          id: 'SQSChannel',
+          name: 'SQS Channel',
+          version: '1.0.0',
+          markdown: '## SQS Channel',
+        });
+
+        // SNS Channel
+        await writeChannel({
+          id: 'SNSChannel',
+          name: 'SNS Channel',
+          version: '1.0.0',
+          markdown: '## SNS Channel',
+        });
+
+        // The Producer
+        await writeService({
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          markdown: '## Order Service',
+          sends: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              to: [
+                { id: 'SQSChannel', version: '1.0.0' },
+                { id: 'SNSChannel', version: '1.0.0' },
+              ],
+            },
+          ],
+        });
+
+        // The Consumer
+        await writeService({
+          id: 'PaymentService',
+          name: 'Service That Receives Messages Without Channels',
+          version: '1.0.0',
+          markdown: '## Service That Receives Messages Without Channels',
+          receives: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              from: [{ id: 'SQSChannel', version: '1.0.0' }],
+            },
+          ],
+        });
+
+        const message = toAstroCollection(
+          await getEvent('PaymentProcessed'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+        const channels = await getChannels().then(
+          (channels) =>
+            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
+        );
+
+        const target = toAstroCollection(
+          await getService('PaymentService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForConsumedMessage({
+          message,
+          services: services,
+          channels: channels,
+          currentNodes: [],
+          target,
+        });
+
+        const expectedChannelNode = expect.objectContaining({
+          id: 'SQSChannel-1.0.0',
+          type: 'channels',
+          position: { x: expect.any(Number), y: expect.any(Number) },
+          data: expect.anything(),
+          sourcePosition: 'right',
+          targetPosition: 'left',
+        });
+
+        const expectedEdges = expect.arrayContaining([
+          // Producer to the message
+          expect.objectContaining({
+            id: 'OrderService-1.0.0-PaymentProcessed-0.0.1',
+            source: 'OrderService-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+          }),
+          // Message to the channel
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-SQSChannel-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'SQSChannel-1.0.0',
+          }),
+          // Channel to the consumer
+          expect.objectContaining({
+            id: 'SQSChannel-1.0.0-PaymentService-1.0.0',
+            source: 'SQSChannel-1.0.0',
+            target: 'PaymentService-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(expect.arrayContaining([expectedChannelNode]));
+
+        const allChannelNodes = nodes.filter((node) => node.type === 'channels');
+        expect(allChannelNodes).toHaveLength(1);
+
+        expect(edges).toEqual(expectedEdges);
+      });
+
+      it('when the producer sends a message over a channel and the channel chains to the target channel, the channel chain is rendered', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // The message itself
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: '## Payment Processed',
+        });
+
+        // EventBridge Channel
+        await writeChannel({
+          id: 'EventBridgeChannel',
+          name: 'EventBridge Channel',
+          version: '1.0.0',
+          markdown: '## EventBridge Channel',
+          routes: [
+            {
+              id: 'SNSChannel',
+              version: '1.0.0',
+            },
+          ],
+        });
+
+        // SNS Channel
+        await writeChannel({
+          id: 'SNSChannel',
+          name: 'SNS Channel',
+          version: '1.0.0',
+          markdown: '## SNS Channel',
+          routes: [
+            {
+              id: 'SQSChannel',
+              version: '1.0.0',
+            },
+          ],
+        });
+
+        // SQS Channel
+        await writeChannel({
+          id: 'SQSChannel',
+          name: 'SQS Channel',
+          version: '1.0.0',
+          markdown: '## SQS Channel',
+        });
+
+        // The Producer
+        await writeService({
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          markdown: '## Order Service',
+          sends: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              to: [{ id: 'EventBridgeChannel', version: '1.0.0' }],
+            },
+          ],
+        });
+
+        // The Consumer
+        await writeService({
+          id: 'PaymentService',
+          name: 'Service That Receives Messages Without Channels',
+          version: '1.0.0',
+          markdown: '## Service That Receives Messages Without Channels',
+          receives: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              from: [{ id: 'SQSChannel', version: '1.0.0' }],
+            },
+          ],
+        });
+
+        const message = toAstroCollection(
+          await getEvent('PaymentProcessed'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+        const channels = await getChannels().then(
+          (channels) =>
+            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
+        );
+
+        const target = toAstroCollection(
+          await getService('PaymentService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForConsumedMessage({
+          message,
+          services: services,
+          channels: channels,
+          currentNodes: [],
+          target,
+        });
+
+        const channelNodes = nodes.filter((node) => node.type === 'channels');
+        expect(channelNodes).toHaveLength(3);
+
+        const expectedEventBusChannelNode = expect.objectContaining({
+          id: 'EventBridgeChannel-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'channels',
+        });
+
+        const expectedSNSChannelNode = expect.objectContaining({
+          id: 'SNSChannel-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'channels',
+        });
+
+        const expectedSQSChannelNode = expect.objectContaining({
+          id: 'SQSChannel-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'channels',
+        });
+
+        const expectedEdges = expect.arrayContaining([
+          // Producer to the event first....
+          expect.objectContaining({
+            id: 'OrderService-1.0.0-PaymentProcessed-0.0.1',
+            source: 'OrderService-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+          }),
+          // The message to the first channel
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-EventBridgeChannel-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'EventBridgeChannel-1.0.0',
+          }),
+          // // The next channel in the chain
+          expect.objectContaining({
+            id: 'EventBridgeChannel-1.0.0-SNSChannel-1.0.0',
+            source: 'EventBridgeChannel-1.0.0',
+            target: 'SNSChannel-1.0.0',
+          }),
+          // The next channel in the chain
+          expect.objectContaining({
+            id: 'SNSChannel-1.0.0-SQSChannel-1.0.0',
+            source: 'SNSChannel-1.0.0',
+            target: 'SQSChannel-1.0.0',
+          }),
+          // Final channel to the consumer
+          expect.objectContaining({
+            id: 'SQSChannel-1.0.0-PaymentService-1.0.0',
+            source: 'SQSChannel-1.0.0',
+            target: 'PaymentService-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            // Expected channel nodes
+            expectedEventBusChannelNode,
+            expectedSNSChannelNode,
+            expectedSQSChannelNode,
+          ])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+    });
+
+    describe('target with channel defined', () => {
+      it('when the producer does not send the message to a channel, but the target has a channel defined, the message is connected to the channel node and the channel node to the target directly', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // The message itself
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: '## Payment Processed',
+        });
+
+        // Producer
+        await writeService({
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          markdown: '## Order Service',
+          sends: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+            },
+          ],
+        });
+
+        // Target
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '1.0.0',
+          markdown: '## Payment Service',
+          receives: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              from: [{ id: 'SQSChannel', version: '1.0.0' }],
+            },
+          ],
+        });
+
+        await writeChannel({
+          id: 'SQSChannel',
+          name: 'SQS Channel',
+          version: '1.0.0',
+          markdown: '## SQS Channel',
+        });
+
+        const message = toAstroCollection(
+          await getEvent('PaymentProcessed'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+        const channels = await getChannels().then(
+          (channels) =>
+            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
+        );
+
+        const target = toAstroCollection(
+          await getService('PaymentService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForConsumedMessage({
+          message,
+          services: services,
+          channels: channels,
+          currentNodes: [],
+          target,
+          targetChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
+        });
+
+        const expectedChannelNode = expect.objectContaining({
+          id: 'SQSChannel-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'channels',
+        });
+
+        const expectedEdges = expect.arrayContaining([
+          // Producer to the message
+          expect.objectContaining({
+            id: 'OrderService-1.0.0-PaymentProcessed-0.0.1',
+            source: 'OrderService-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+          }),
+          // Message to the channel
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-SQSChannel-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'SQSChannel-1.0.0',
+          }),
+          // // Channel to the target
+          // expect.objectContaining({
+          //     id: 'SQSChannel-1.0.0-PaymentService-1.0.0',
+          //     source: 'SQSChannel-1.0.0',
+          //     target: 'PaymentService-1.0.0',
+          // }),
+        ]);
+
+        expect(nodes).toEqual(expect.arrayContaining([expectedChannelNode]));
+
+        expect(edges).toEqual(expectedEdges);
+      });
+    });
+  });
+
+  describe('getNodesAndEdgesForProducedMessage', () => {
+    describe('when the message is produced by the producer and the producer and consumer have no channels defined', () => {
+      it('renders the producer publishing the message directly to the consumer', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // The message itself
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: '## Payment Processed',
+        });
+
+        // The producer
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '1.0.0',
+          markdown: '## Payment Service',
+          sends: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+            },
+          ],
+        });
+
+        // The Consumer
+        await writeService({
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          markdown: '## Order Service',
+          receives: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+            },
+          ],
+        });
+
+        const message = toAstroCollection(
+          await getEvent('PaymentProcessed'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+
+        const source = toAstroCollection(
+          await getService('PaymentService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
+          message,
+          services: services,
+          channels: [],
+          currentNodes: [],
+          source,
+          currentEdges: [],
+        });
+
+        const expectedProducerNode = expect.objectContaining({
+          id: 'PaymentService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedMessageNode = expect.objectContaining({
+          id: 'PaymentProcessed-0.0.1',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'events',
+        });
+
+        const expectedConsumerNode = expect.objectContaining({
+          id: 'OrderService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedEdges = expect.arrayContaining([
+          // Producer to the message
+          expect.objectContaining({
+            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
+            source: 'PaymentService-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+          }),
+          // Message to the consumer
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-OrderService-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'OrderService-1.0.0',
+          }),
+        ]);
+
+        expect(edges).toEqual(expectedEdges);
+
+        expect(nodes).toEqual(expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedConsumerNode]));
+
+        expect(edges).toEqual(expectedEdges);
+      });
+    });
+
+    describe('when the message is produced by the producer and the producer defines a channel', () => {
+      it('renders the producer publishing the message to the channel', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // The message itself
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: '## Payment Processed',
+        });
+
+        // The producer
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '1.0.0',
+          markdown: '## Payment Service',
+          sends: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              to: [{ id: 'SQSChannel', version: '1.0.0' }],
+            },
+          ],
+        });
+
+        // The channel
+        await writeChannel({
+          id: 'SQSChannel',
+          name: 'SQS Channel',
+          version: '1.0.0',
+          markdown: '## SQS Channel',
+        });
+
+        const message = toAstroCollection(
+          await getEvent('PaymentProcessed'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+        const channels = await getChannels().then(
+          (channels) =>
+            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
+        );
+
+        const source = toAstroCollection(
+          await getService('PaymentService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
+          message,
+          services: services,
+          channels: channels,
+          currentNodes: [],
+          sourceChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
+          source,
+          currentEdges: [],
+        });
+
+        const expectedProducerNode = expect.objectContaining({
+          id: 'PaymentService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedMessageNode = expect.objectContaining({
+          id: 'PaymentProcessed-0.0.1',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'events',
+        });
+
+        const expectedChannelNode = expect.objectContaining({
+          id: 'SQSChannel-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'channels',
+        });
+
+        const expectedEdges = expect.arrayContaining([
+          // Producer to the message
+          expect.objectContaining({
+            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
+            source: 'PaymentService-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+          }),
+          // Message to the channel
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-SQSChannel-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'SQSChannel-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedChannelNode]));
+
+        expect(edges).toEqual(expectedEdges);
+      });
+
+      it('when the producer defines a channel version that does not exist, the message is connected directly from the producer to the message (not reversed)', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // The message itself
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: '## Payment Processed',
+        });
+
+        // The producer with a channel version that doesn't exist
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '1.0.0',
+          markdown: '## Payment Service',
+          sends: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              to: [{ id: 'SQSChannel', version: '99.0.0' }], // Version 99.0.0 does not exist
+            },
+          ],
+        });
+
+        // The channel exists but with a different version
+        await writeChannel({
+          id: 'SQSChannel',
+          name: 'SQS Channel',
+          version: '1.0.0',
+          markdown: '## SQS Channel',
+        });
+
+        const message = toAstroCollection(
+          await getEvent('PaymentProcessed'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+        const channels = await getChannels().then(
+          (channels) =>
+            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
+        );
+
+        const source = toAstroCollection(
+          await getService('PaymentService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
+          message,
+          services: services,
+          channels: channels,
+          currentNodes: [],
+          sourceChannels: [{ id: 'SQSChannel', version: '99.0.0' }], // Non-existent version
+          source,
+          currentEdges: [],
+        });
+
+        const expectedProducerNode = expect.objectContaining({
+          id: 'PaymentService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedMessageNode = expect.objectContaining({
+          id: 'PaymentProcessed-0.0.1',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'events',
+        });
+
+        // The edge should go from producer to message (not reversed)
+        const expectedEdges = expect.arrayContaining([
+          expect.objectContaining({
+            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
+            source: 'PaymentService-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+            label: 'publishes \nevent',
+          }),
+        ]);
+
+        // Should NOT contain a reversed edge (message -> producer)
+        const reversedEdge = edges.find(
+          (edge: any) => edge.source === 'PaymentProcessed-0.0.1' && edge.target === 'PaymentService-1.0.0'
+        );
+        expect(reversedEdge).toBeUndefined();
+
+        // No channel nodes should be created since the version doesn't exist
+        const channelNodes = nodes.filter((node: any) => node.type === 'channels');
+        expect(channelNodes).toHaveLength(0);
+
+        expect(nodes).toEqual(expect.arrayContaining([expectedProducerNode, expectedMessageNode]));
+        expect(edges).toEqual(expectedEdges);
+      });
+    });
+
+    describe('when the message is produced by the producer without a channel, but the consumer defines a channel', () => {
+      it('renders the producer publishing the message to the consumers channel', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // The message itself
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: '## Payment Processed',
+        });
+
+        // The producer
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '1.0.0',
+          markdown: '## Payment Service',
+        });
+
+        // The channel
+        await writeChannel({
+          id: 'SQSChannel',
+          name: 'SQS Channel',
+          version: '1.0.0',
+          markdown: '## SQS Channel',
+        });
+
+        // The consumer
+        await writeService({
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          markdown: '## Order Service',
+          receives: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              from: [{ id: 'SQSChannel', version: '1.0.0' }],
+            },
+          ],
+        });
+
+        const message = toAstroCollection(
+          await getEvent('PaymentProcessed'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+        const channels = await getChannels().then(
+          (channels) =>
+            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
+        );
+
+        const source = toAstroCollection(
+          await getService('PaymentService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
+          message,
+          services: services,
+          channels: channels,
+          currentNodes: [],
+          sourceChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
+          source,
+          currentEdges: [],
+        });
+
+        const expectedProducerNode = expect.objectContaining({
+          id: 'PaymentService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedMessageNode = expect.objectContaining({
+          id: 'PaymentProcessed-0.0.1',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'events',
+        });
+
+        const expectedChannelNode = expect.objectContaining({
+          id: 'SQSChannel-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'channels',
+        });
+
+        const expectedConsumerNode = expect.objectContaining({
+          id: 'OrderService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedEdges = expect.arrayContaining([
+          // Producer to the message
+          expect.objectContaining({
+            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
+            source: 'PaymentService-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+          }),
+          // Message to the channel
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-SQSChannel-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'SQSChannel-1.0.0',
+          }),
+          // Channel to the consumer
+          expect.objectContaining({
+            id: 'SQSChannel-1.0.0-OrderService-1.0.0',
+            source: 'SQSChannel-1.0.0',
+            target: 'OrderService-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedChannelNode, expectedConsumerNode])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+
+      it('if the consumer defines a channel that does not exist in EventCatalog, the message is connected to the consumer directly', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // The message itself
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: '## Payment Processed',
+        });
+
+        // The producer
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '1.0.0',
+          markdown: '## Payment Service',
+        });
+
+        // The consumer
+        await writeService({
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          markdown: '## Order Service',
+          receives: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              from: [{ id: 'NonExistentChannel', version: '1.0.0' }],
+            },
+          ],
+        });
+
+        const message = toAstroCollection(
+          await getEvent('PaymentProcessed'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+
+        const source = toAstroCollection(
+          await getService('PaymentService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
+          message,
+          services: services,
+          channels: [],
+          currentNodes: [],
+          sourceChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
+          source,
+          currentEdges: [],
+        });
+
+        const expectedProducerNode = expect.objectContaining({
+          id: 'PaymentService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedMessageNode = expect.objectContaining({
+          id: 'PaymentProcessed-0.0.1',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'events',
+        });
+
+        const expectedConsumerNode = expect.objectContaining({
+          id: 'OrderService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedEdges = expect.arrayContaining([
+          // Producer to the message
+          expect.objectContaining({
+            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
+            source: 'PaymentService-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+          }),
+          // Message to the consumer directly
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-OrderService-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'OrderService-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedConsumerNode]));
+
+        expect(edges).toEqual(expectedEdges);
+      });
+    });
+
+    describe('When the message is produced with a channel, but the consumer does not define a channel?', () => {
+      it('renders the producer publishing the message to the channel, but the consumer consumes the message directly from the producer', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // The message itself
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: '## Payment Processed',
+        });
+
+        // The producer
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '1.0.0',
+          markdown: '## Payment Service',
+        });
+
+        // The channel
+        await writeChannel({
+          id: 'SQSChannel',
+          name: 'SQS Channel',
+          version: '1.0.0',
+          markdown: '## SQS Channel',
+        });
+
+        // The consumer
+        await writeService({
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          markdown: '## Order Service',
+          receives: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+            },
+          ],
+        });
+
+        const message = toAstroCollection(
+          await getEvent('PaymentProcessed'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+        const channels = await getChannels().then(
+          (channels) =>
+            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
+        );
+
+        const source = toAstroCollection(
+          await getService('PaymentService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
+          message,
+          services: services,
+          channels: channels,
+          currentNodes: [],
+          sourceChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
+          source,
+          currentEdges: [],
+        });
+
+        const expectedProducerNode = expect.objectContaining({
+          id: 'PaymentService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedMessageNode = expect.objectContaining({
+          id: 'PaymentProcessed-0.0.1',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'events',
+        });
+
+        const expectedChannelNode = expect.objectContaining({
+          id: 'SQSChannel-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'channels',
+        });
+
+        const expectedConsumerNode = expect.objectContaining({
+          id: 'OrderService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedEdges = expect.arrayContaining([
+          // Producer to the message
+          expect.objectContaining({
+            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
+            source: 'PaymentService-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+          }),
+          // Message to the channel
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-SQSChannel-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'SQSChannel-1.0.0',
+          }),
+          // Message to the consumer directly
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-OrderService-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'OrderService-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedChannelNode, expectedConsumerNode])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+    });
+
+    describe('when the message is produced by the producer and the producer defines a channel and the consumer also defines the same channel (consuming from the channel)', () => {
+      it('renders the producer publishing the message to the channel and the consumer consuming the message from the channel', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // The message itself
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: '## Payment Processed',
+        });
+
+        // The producer
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '1.0.0',
+          markdown: '## Payment Service',
+          sends: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              to: [{ id: 'SQSChannel', version: '1.0.0' }],
+            },
+          ],
+        });
+
+        // The channel
+        await writeChannel({
+          id: 'SQSChannel',
+          name: 'SQS Channel',
+          version: '1.0.0',
+          markdown: '## SQS Channel',
+        });
+
+        // The consumer
+        await writeService({
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          markdown: '## Order Service',
+          receives: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              from: [{ id: 'SQSChannel', version: '1.0.0' }],
+            },
+          ],
+        });
+
+        const message = toAstroCollection(
+          await getEvent('PaymentProcessed'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+        const channels = await getChannels().then(
+          (channels) =>
+            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
+        );
+
+        const source = toAstroCollection(
+          await getService('PaymentService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
+          message,
+          services: services,
+          channels: channels,
+          currentNodes: [],
+          sourceChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
+          source,
+          currentEdges: [],
+        });
+
+        const expectedProducerNode = expect.objectContaining({
+          id: 'PaymentService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedMessageNode = expect.objectContaining({
+          id: 'PaymentProcessed-0.0.1',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'events',
+        });
+
+        const expectedChannelNode = expect.objectContaining({
+          id: 'SQSChannel-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'channels',
+        });
+
+        const expectedConsumerNode = expect.objectContaining({
+          id: 'OrderService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedEdges = expect.arrayContaining([
+          // Producer to the message
+          expect.objectContaining({
+            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
+            source: 'PaymentService-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+          }),
+          // Message to the channel
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-SQSChannel-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'SQSChannel-1.0.0',
+          }),
+          // Channel to the consumer
+          expect.objectContaining({
+            id: 'SQSChannel-1.0.0-OrderService-1.0.0',
+            source: 'SQSChannel-1.0.0',
+            target: 'OrderService-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedChannelNode, expectedConsumerNode])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+    });
+
+    describe('when a service sends multiple versions of the same message to different version-specific channels', () => {
+      it('renders the correct version-specific channel for each message version', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // Create two versions of the same event
+        await writeEvent({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          markdown: '## Inventory Adjusted v0.0.1',
+        });
+
+        await writeEvent({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.1',
+          markdown: '## Inventory Adjusted v1.0.1',
+        });
+
+        // Create two versions of the same channel (same ID, different versions)
+        await writeChannel({
+          id: 'inventory-adjusted-channel',
+          name: 'Inventory Adjusted Channel',
+          version: '0.0.1',
+          markdown: '## Channel v0.0.1',
+        });
+
+        await writeChannel({
+          id: 'inventory-adjusted-channel',
+          name: 'Inventory Adjusted Channel',
+          version: '1.0.1',
+          markdown: '## Channel v1.0.1',
+        });
+
+        // The producer sends v0.0.1 to channel v0.0.1, and v1.0.1 to channel v1.0.1
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '1.0.0',
+          markdown: '## Inventory Service',
+          sends: [
+            {
+              id: 'InventoryAdjusted',
+              version: '0.0.1',
+              to: [{ id: 'inventory-adjusted-channel', version: '0.0.1' }],
+            },
+            {
+              id: 'InventoryAdjusted',
+              version: '1.0.1',
+              to: [{ id: 'inventory-adjusted-channel', version: '1.0.1' }],
+            },
+          ],
+        });
+
+        const messageV101 = toAstroCollection(
+          await getEvent('InventoryAdjusted', '1.0.1'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+        const channels = await getChannels().then(
+          (channels) =>
+            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
+        );
+
+        const source = toAstroCollection(
+          await getService('InventoryService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
+          message: messageV101,
+          services: services,
+          channels: channels,
+          currentNodes: [],
+          sourceChannels: [{ id: 'inventory-adjusted-channel', version: '1.0.1' }],
+          source,
+          currentEdges: [],
+        });
+
+        // The v1.0.1 message should route to v1.0.1 channel, NOT v0.0.1 channel
+        const expectedChannelNode = expect.objectContaining({
+          id: 'inventory-adjusted-channel-1.0.1',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'channels',
+        });
+
+        const expectedEdges = expect.arrayContaining([
+          // Producer to the message
+          expect.objectContaining({
+            id: 'InventoryService-1.0.0-InventoryAdjusted-1.0.1',
+            source: 'InventoryService-1.0.0',
+            target: 'InventoryAdjusted-1.0.1',
+          }),
+          // Message to the correct version-specific channel (v1.0.1, NOT v0.0.1)
+          expect.objectContaining({
+            id: 'InventoryAdjusted-1.0.1-inventory-adjusted-channel-1.0.1',
+            source: 'InventoryAdjusted-1.0.1',
+            target: 'inventory-adjusted-channel-1.0.1',
+          }),
+        ]);
+
+        expect(nodes).toEqual(expect.arrayContaining([expectedChannelNode]));
+        expect(edges).toEqual(expectedEdges);
+
+        // Verify the wrong channel version is NOT connected
+        const wrongChannelEdge = edges.find(
+          (edge: any) => edge.source === 'InventoryAdjusted-1.0.1' && edge.target === 'inventory-adjusted-channel-0.0.1'
+        );
+        expect(wrongChannelEdge).toBeUndefined();
+      });
+    });
+
+    describe('when the message is produced by the producer and the producer defines a channel and the consumer also defines a channel but its a chain of channels', () => {
+      it('renders the producer publishing the message to the channel and the consumer consuming the message from the channel chain', async () => {
+        const { writeService, writeEvent, getServices, writeChannel, getEvent, getChannels, getService } = utils(CATALOG_FOLDER);
+
+        // The message itself
+        await writeEvent({
+          id: 'PaymentProcessed',
+          name: 'Payment Processed',
+          version: '0.0.1',
+          markdown: '## Payment Processed',
+        });
+
+        // The producer
+        await writeService({
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '1.0.0',
+          markdown: '## Payment Service',
+          sends: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              to: [{ id: 'EventBridgeChannel', version: '1.0.0' }],
+            },
+          ],
+        });
+
+        // The first channel
+        await writeChannel({
+          id: 'EventBridgeChannel',
+          name: 'EventBridge Channel',
+          version: '1.0.0',
+          markdown: '## EventBridge Channel',
+          routes: [{ id: 'SQSChannel', version: '1.0.0' }],
+        });
+
+        // The second channel
+        await writeChannel({
+          id: 'SQSChannel',
+          name: 'SQS Channel',
+          version: '1.0.0',
+          markdown: '## SQS Channel',
+          routes: [{ id: 'SNSChannel', version: '1.0.0' }],
+        });
+
+        // The third channel
+        await writeChannel({
+          id: 'SNSChannel',
+          name: 'SNS Channel',
+          version: '1.0.0',
+          markdown: '## SNS Channel',
+        });
+
+        // The consumer
+        await writeService({
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          markdown: '## Order Service',
+          receives: [
+            {
+              id: 'PaymentProcessed',
+              version: '0.0.1',
+              from: [{ id: 'SNSChannel', version: '1.0.0' }],
+            },
+          ],
+        });
+
+        const message = toAstroCollection(
+          await getEvent('PaymentProcessed'),
+          'events'
+        ) as unknown as CollectionEntry<CollectionMessageTypes>;
+        const services = await getServices().then(
+          (services) =>
+            services.map((service) => toAstroCollection(service, 'services')) as unknown as CollectionEntry<'services'>[]
+        );
+        const channels = await getChannels().then(
+          (channels) =>
+            channels.map((channel) => toAstroCollection(channel, 'channels')) as unknown as CollectionEntry<'channels'>[]
+        );
+
+        const source = toAstroCollection(
+          await getService('PaymentService'),
+          'services'
+        ) as unknown as CollectionEntry<'services'>;
+
+        const { nodes, edges } = await getNodesAndEdgesForProducedMessage({
+          message,
+          services: services,
+          channels: channels,
+          currentNodes: [],
+          sourceChannels: [{ id: 'SQSChannel', version: '1.0.0' }],
+          source,
+          currentEdges: [],
+        });
+
+        const expectedProducerNode = expect.objectContaining({
+          id: 'PaymentService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedMessageNode = expect.objectContaining({
+          id: 'PaymentProcessed-0.0.1',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'events',
+        });
+
+        const expectedChannelNode = expect.objectContaining({
+          id: 'SQSChannel-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'channels',
+        });
+
+        const expectedConsumerNode = expect.objectContaining({
+          id: 'OrderService-1.0.0',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          type: 'services',
+        });
+
+        const expectedEdges = expect.arrayContaining([
+          // Producer to the message
+          expect.objectContaining({
+            id: 'PaymentService-1.0.0-PaymentProcessed-0.0.1',
+            source: 'PaymentService-1.0.0',
+            target: 'PaymentProcessed-0.0.1',
+          }),
+          // Message to the first channel
+          expect.objectContaining({
+            id: 'PaymentProcessed-0.0.1-EventBridgeChannel-1.0.0',
+            source: 'PaymentProcessed-0.0.1',
+            target: 'EventBridgeChannel-1.0.0',
+          }),
+          // First channel to the second channel
+          expect.objectContaining({
+            id: 'EventBridgeChannel-1.0.0-SQSChannel-1.0.0',
+            source: 'EventBridgeChannel-1.0.0',
+            target: 'SQSChannel-1.0.0',
+          }),
+          // Second channel to the third channel
+          expect.objectContaining({
+            id: 'SQSChannel-1.0.0-SNSChannel-1.0.0',
+            source: 'SQSChannel-1.0.0',
+            target: 'SNSChannel-1.0.0',
+          }),
+          // Third channel to the consumer
+          expect.objectContaining({
+            id: 'SNSChannel-1.0.0-OrderService-1.0.0',
+            source: 'SNSChannel-1.0.0',
+            target: 'OrderService-1.0.0',
+          }),
+        ]);
+
+        expect(nodes).toEqual(
+          expect.arrayContaining([expectedProducerNode, expectedMessageNode, expectedChannelNode, expectedConsumerNode])
+        );
+
+        expect(edges).toEqual(expectedEdges);
+      });
+    });
+  });
+
+  describe('Semver Pattern Matching in Graph Generation', () => {
+    describe('should_match_service_with_caret_range_to_compatible_message_versions_when_producing', () => {
+      it('getProducersOfMessage returns service for messages matching ^1.0.0 pattern but not 2.0.0', async () => {
+        // Service that uses caret range pattern (^1.0.0) in sends configuration
+        const mockServiceWithCaretRangeSends = {
+          id: 'OrderProcessingService',
+          collection: 'services',
+          data: {
+            id: 'OrderProcessingService',
+            version: '1.0.0',
+            pathToFile: 'services/OrderProcessingService/index.md',
+            sends: [{ id: 'PaymentProcessed', version: '^1.0.0' }],
+          },
+        };
+
+        // Get PaymentProcessed events at versions 1.0.0, 1.2.3, 1.9.9, 2.0.0
+        const events = mockEvents.filter((e) => e.data.id === 'PaymentProcessed');
+        const v100 = events.find((e) => e.data.version === '1.0.0') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v123 = events.find((e) => e.data.version === '1.2.3') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v199 = events.find((e) => e.data.version === '1.9.9') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v200 = events.find((e) => e.data.version === '2.0.0') as unknown as CollectionEntry<CollectionMessageTypes>;
+
+        const service = mockServiceWithCaretRangeSends as unknown as CollectionEntry<'services'>;
+        const allServices = [service];
+
+        // ^1.0.0 should match 1.0.0, 1.2.3, and 1.9.9
+        const producersV100 = getProducersOfMessage(allServices as any, v100);
+        const producersV123 = getProducersOfMessage(allServices as any, v123);
+        const producersV199 = getProducersOfMessage(allServices as any, v199);
+        const producersV200 = getProducersOfMessage(allServices as any, v200);
+
+        expect(producersV100).toHaveLength(1);
+        expect(producersV100[0].data.id).toBe('OrderProcessingService');
+
+        expect(producersV123).toHaveLength(1);
+        expect(producersV123[0].data.id).toBe('OrderProcessingService');
+
+        expect(producersV199).toHaveLength(1);
+        expect(producersV199[0].data.id).toBe('OrderProcessingService');
+
+        // ^1.0.0 should NOT match 2.0.0
+        expect(producersV200).toHaveLength(0);
+      });
+    });
+
+    describe('should_match_service_with_caret_range_when_receiving_messages', () => {
+      it('getConsumersOfMessage returns service for messages matching ^1.0.0 pattern but not 2.0.0', async () => {
+        // Service that uses caret range pattern (^1.0.0) in receives configuration
+        const mockServiceWithCaretRangeReceives = {
+          id: 'InventoryService',
+          collection: 'services',
+          data: {
+            id: 'InventoryService',
+            version: '1.0.0',
+            pathToFile: 'services/InventoryService/index.md',
+            receives: [{ id: 'PaymentProcessed', version: '^1.0.0' }],
+          },
+        };
+
+        // Get PaymentProcessed events at versions 1.0.0, 1.2.3, 1.9.9, 2.0.0
+        const events = mockEvents.filter((e) => e.data.id === 'PaymentProcessed');
+        const v100 = events.find((e) => e.data.version === '1.0.0') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v123 = events.find((e) => e.data.version === '1.2.3') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v199 = events.find((e) => e.data.version === '1.9.9') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v200 = events.find((e) => e.data.version === '2.0.0') as unknown as CollectionEntry<CollectionMessageTypes>;
+
+        const service = mockServiceWithCaretRangeReceives as unknown as CollectionEntry<'services'>;
+        const allServices = [service];
+
+        // ^1.0.0 should match 1.0.0, 1.2.3, and 1.9.9
+        const consumersV100 = getConsumersOfMessage(allServices as any, v100);
+        const consumersV123 = getConsumersOfMessage(allServices as any, v123);
+        const consumersV199 = getConsumersOfMessage(allServices as any, v199);
+        const consumersV200 = getConsumersOfMessage(allServices as any, v200);
+
+        expect(consumersV100).toHaveLength(1);
+        expect(consumersV100[0].data.id).toBe('InventoryService');
+
+        expect(consumersV123).toHaveLength(1);
+        expect(consumersV123[0].data.id).toBe('InventoryService');
+
+        expect(consumersV199).toHaveLength(1);
+        expect(consumersV199[0].data.id).toBe('InventoryService');
+
+        // ^1.0.0 should NOT match 2.0.0
+        expect(consumersV200).toHaveLength(0);
+      });
+    });
+
+    describe('should_match_service_with_tilde_range_to_compatible_message_versions', () => {
+      it('getConsumersOfMessage returns service for messages matching ~1.2.0 pattern', async () => {
+        // Service that uses tilde range pattern (~1.2.0) in receives configuration
+        const mockServiceWithTildeRange = {
+          id: 'NotificationService',
+          collection: 'services',
+          data: {
+            id: 'NotificationService',
+            version: '1.0.0',
+            pathToFile: 'services/NotificationService/index.md',
+            receives: [{ id: 'PaymentProcessed', version: '~1.2.0' }],
+          },
+        };
+
+        // Get PaymentProcessed events at versions 1.2.3, 1.2.5, 1.9.9
+        const events = mockEvents.filter((e) => e.data.id === 'PaymentProcessed');
+        const v123 = events.find((e) => e.data.version === '1.2.3') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v125 = events.find((e) => e.data.version === '1.2.5') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v199 = events.find((e) => e.data.version === '1.9.9') as unknown as CollectionEntry<CollectionMessageTypes>;
+
+        const service = mockServiceWithTildeRange as unknown as CollectionEntry<'services'>;
+        const allServices = [service];
+
+        // ~1.2.0 should match 1.2.3 and 1.2.5
+        const consumersV123 = getConsumersOfMessage(allServices as any, v123);
+        const consumersV125 = getConsumersOfMessage(allServices as any, v125);
+        const consumersV199 = getConsumersOfMessage(allServices as any, v199);
+
+        expect(consumersV123).toHaveLength(1);
+        expect(consumersV123[0].data.id).toBe('NotificationService');
+
+        expect(consumersV125).toHaveLength(1);
+        expect(consumersV125[0].data.id).toBe('NotificationService');
+
+        // ~1.2.0 should NOT match 1.9.9 (different minor version)
+        expect(consumersV199).toHaveLength(0);
+      });
+    });
+
+    describe('should_match_service_with_x_pattern_to_compatible_message_versions', () => {
+      it('getConsumersOfMessage returns service for messages matching 1.x pattern', async () => {
+        // Service that uses x-pattern (1.x) in receives configuration
+        const mockServiceWithXPattern = {
+          id: 'AnalyticsService',
+          collection: 'services',
+          data: {
+            id: 'AnalyticsService',
+            version: '1.0.0',
+            pathToFile: 'services/AnalyticsService/index.md',
+            receives: [{ id: 'PaymentProcessed', version: '1.x' }],
+          },
+        };
+
+        // Get PaymentProcessed events
+        const events = mockEvents.filter((e) => e.data.id === 'PaymentProcessed');
+        const v100 = events.find((e) => e.data.version === '1.0.0') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v123 = events.find((e) => e.data.version === '1.2.3') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v199 = events.find((e) => e.data.version === '1.9.9') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v200 = events.find((e) => e.data.version === '2.0.0') as unknown as CollectionEntry<CollectionMessageTypes>;
+
+        const service = mockServiceWithXPattern as unknown as CollectionEntry<'services'>;
+        const allServices = [service];
+
+        // 1.x should match 1.0.0, 1.2.3, and 1.9.9
+        const consumersV100 = getConsumersOfMessage(allServices as any, v100);
+        const consumersV123 = getConsumersOfMessage(allServices as any, v123);
+        const consumersV199 = getConsumersOfMessage(allServices as any, v199);
+        const consumersV200 = getConsumersOfMessage(allServices as any, v200);
+
+        expect(consumersV100).toHaveLength(1);
+        expect(consumersV100[0].data.id).toBe('AnalyticsService');
+
+        expect(consumersV123).toHaveLength(1);
+        expect(consumersV123[0].data.id).toBe('AnalyticsService');
+
+        expect(consumersV199).toHaveLength(1);
+        expect(consumersV199[0].data.id).toBe('AnalyticsService');
+
+        // 1.x should NOT match 2.0.0
+        expect(consumersV200).toHaveLength(0);
+      });
+
+      it('getProducersOfMessage returns service for messages matching 1.2.x pattern with correct boundaries', async () => {
+        // Service that uses x-pattern (1.2.x) in sends configuration
+        const mockServiceWithXPatternMinor = {
+          id: 'AuditService',
+          collection: 'services',
+          data: {
+            id: 'AuditService',
+            version: '1.0.0',
+            pathToFile: 'services/AuditService/index.md',
+            sends: [{ id: 'PaymentProcessed', version: '1.2.x' }],
+          },
+        };
+
+        // Get PaymentProcessed events
+        const events = mockEvents.filter((e) => e.data.id === 'PaymentProcessed');
+        const v123 = events.find((e) => e.data.version === '1.2.3') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v125 = events.find((e) => e.data.version === '1.2.5') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v199 = events.find((e) => e.data.version === '1.9.9') as unknown as CollectionEntry<CollectionMessageTypes>;
+
+        const service = mockServiceWithXPatternMinor as unknown as CollectionEntry<'services'>;
+        const allServices = [service];
+
+        // 1.2.x should match 1.2.3 and 1.2.5
+        const producersV123 = getProducersOfMessage(allServices as any, v123);
+        const producersV125 = getProducersOfMessage(allServices as any, v125);
+        const producersV199 = getProducersOfMessage(allServices as any, v199);
+
+        expect(producersV123).toHaveLength(1);
+        expect(producersV123[0].data.id).toBe('AuditService');
+
+        expect(producersV125).toHaveLength(1);
+        expect(producersV125[0].data.id).toBe('AuditService');
+
+        // 1.2.x should NOT match 1.9.9 (different minor version)
+        expect(producersV199).toHaveLength(0);
+      });
+    });
+
+    describe('should_match_service_with_semver_pattern_and_channel_configuration', () => {
+      it('getProducersOfMessage returns service with ^1.0.0 and channel when message matches pattern', async () => {
+        // Service with caret range and channel configuration
+        const mockServiceWithCaretRangeAndChannel = {
+          id: 'OrderServiceWithChannel',
+          collection: 'services',
+          data: {
+            id: 'OrderServiceWithChannel',
+            version: '1.0.0',
+            pathToFile: 'services/OrderServiceWithChannel/index.md',
+            sends: [{ id: 'PaymentProcessed', version: '^1.0.0', to: [{ id: 'SNSChannel', version: '1.0.0' }] }],
+          },
+        };
+
+        // Get PaymentProcessed events
+        const events = mockEvents.filter((e) => e.data.id === 'PaymentProcessed');
+        const v123 = events.find((e) => e.data.version === '1.2.3') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v200 = events.find((e) => e.data.version === '2.0.0') as unknown as CollectionEntry<CollectionMessageTypes>;
+
+        const service = mockServiceWithCaretRangeAndChannel as unknown as CollectionEntry<'services'>;
+        const allServices = [service];
+
+        // Service with ^1.0.0 + channel should match 1.2.3
+        const producersV123 = getProducersOfMessage(allServices as any, v123);
+        expect(producersV123).toHaveLength(1);
+        expect(producersV123[0].data.id).toBe('OrderServiceWithChannel');
+        expect(producersV123[0].data.sends?.[0].to).toEqual([{ id: 'SNSChannel', version: '1.0.0' }]);
+
+        // Service with ^1.0.0 + channel should NOT match 2.0.0
+        const producersV200 = getProducersOfMessage(allServices as any, v200);
+        expect(producersV200).toHaveLength(0);
+      });
+
+      it('getConsumersOfMessage returns service with 1.x and channel when message matches pattern', async () => {
+        // Service with x-pattern and channel configuration
+        const mockServiceWithXPatternAndChannel = {
+          id: 'ConsumerServiceWithChannel',
+          collection: 'services',
+          data: {
+            id: 'ConsumerServiceWithChannel',
+            version: '1.0.0',
+            pathToFile: 'services/ConsumerServiceWithChannel/index.md',
+            receives: [{ id: 'PaymentProcessed', version: '1.x', from: [{ id: 'SQSChannel', version: '1.0.0' }] }],
+          },
+        };
+
+        // Get PaymentProcessed events
+        const events = mockEvents.filter((e) => e.data.id === 'PaymentProcessed');
+        const v100 = events.find((e) => e.data.version === '1.0.0') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v199 = events.find((e) => e.data.version === '1.9.9') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v200 = events.find((e) => e.data.version === '2.0.0') as unknown as CollectionEntry<CollectionMessageTypes>;
+
+        const service = mockServiceWithXPatternAndChannel as unknown as CollectionEntry<'services'>;
+        const allServices = [service];
+
+        // Service with 1.x + channel should match 1.0.0 and 1.9.9
+        const consumersV100 = getConsumersOfMessage(allServices as any, v100);
+        expect(consumersV100).toHaveLength(1);
+        expect(consumersV100[0].data.id).toBe('ConsumerServiceWithChannel');
+        expect(consumersV100[0].data.receives?.[0].from).toEqual([{ id: 'SQSChannel', version: '1.0.0' }]);
+
+        const consumersV199 = getConsumersOfMessage(allServices as any, v199);
+        expect(consumersV199).toHaveLength(1);
+        expect(consumersV199[0].data.id).toBe('ConsumerServiceWithChannel');
+
+        // Service with 1.x + channel should NOT match 2.0.0
+        const consumersV200 = getConsumersOfMessage(allServices as any, v200);
+        expect(consumersV200).toHaveLength(0);
+      });
+    });
+
+    describe('should_match_service_receiving_multiple_versions_of_same_message', () => {
+      it('getConsumersOfMessage returns service for each version it explicitly receives', async () => {
+        // Create a service that receives two specific versions of the same message
+        const multiVersionConsumerService = {
+          collection: 'services',
+          id: 'MultiVersionConsumer',
+          data: {
+            id: 'MultiVersionConsumer',
+            name: 'Multi-Version Consumer Service',
+            version: '1.0.0',
+            receives: [
+              { id: 'PaymentProcessed', version: '1.0.0' },
+              { id: 'PaymentProcessed', version: '1.2.3' },
+            ],
+          },
+        };
+
+        // Get PaymentProcessed events
+        const events = mockEvents.filter((e) => e.data.id === 'PaymentProcessed');
+        const v100 = events.find((e) => e.data.version === '1.0.0') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v123 = events.find((e) => e.data.version === '1.2.3') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v125 = events.find((e) => e.data.version === '1.2.5') as unknown as CollectionEntry<CollectionMessageTypes>;
+        const v200 = events.find((e) => e.data.version === '2.0.0') as unknown as CollectionEntry<CollectionMessageTypes>;
+
+        const allServices = [multiVersionConsumerService as unknown as CollectionEntry<'services'>];
+
+        // Should match both explicitly listed versions
+        const consumersV100 = getConsumersOfMessage(allServices as any, v100);
+        expect(consumersV100).toHaveLength(1);
+        expect(consumersV100[0].data.id).toBe('MultiVersionConsumer');
+
+        const consumersV123 = getConsumersOfMessage(allServices as any, v123);
+        expect(consumersV123).toHaveLength(1);
+        expect(consumersV123[0].data.id).toBe('MultiVersionConsumer');
+
+        // Should NOT match versions that aren't explicitly listed
+        const consumersV125 = getConsumersOfMessage(allServices as any, v125);
+        expect(consumersV125).toHaveLength(0);
+
+        const consumersV200 = getConsumersOfMessage(allServices as any, v200);
+        expect(consumersV200).toHaveLength(0);
+      });
+    });
+  });
+
+  describe('operation fields', () => {
+    it('passes operation method, path, and statusCodes to message node data', async () => {
+      const messageWithOperation = {
+        id: 'CreateOrder',
+        collection: 'events',
+        data: {
+          id: 'CreateOrder',
+          version: '1.0.0',
+          name: 'CreateOrder',
+          operation: {
+            method: 'POST',
+            path: '/orders',
+            statusCodes: ['201', '400'],
+          },
+        },
+      } as unknown as CollectionEntry<CollectionMessageTypes>;
+
+      const { nodes } = await getNodesAndEdgesForConsumedMessage({
+        message: messageWithOperation,
+        services: [] as any,
+        channels: [] as any,
+        currentNodes: [],
+        target: mockServices[0] as any,
+        targetChannels: [],
+      });
+
+      const messageNode = nodes.find((n: any) => n.id === 'CreateOrder-1.0.0');
+      expect(messageNode).toBeDefined();
+      const messageData = (messageNode as any)?.data.message;
+      expect(messageData.method).toBe('POST');
+      expect(messageData.path).toBe('/orders');
+      expect(messageData.statusCodes).toEqual([201, 400]);
+    });
+
+    it('does not add operation fields when no operation is present', async () => {
+      const message = mockEvents[0] as unknown as CollectionEntry<CollectionMessageTypes>;
+
+      const { nodes } = await getNodesAndEdgesForConsumedMessage({
+        message,
+        services: mockServices as any,
+        channels: mockChannels as any,
+        currentNodes: [],
+        target: mockServices[0] as any,
+        targetChannels: [],
+      });
+
+      const messageNode = nodes.find((n: any) => n.id === 'PaymentProcessed-0.0.1');
+      expect(messageNode).toBeDefined();
+      const messageData = (messageNode as any)?.data.message;
+      expect(messageData.method).toBeUndefined();
+      expect(messageData.path).toBeUndefined();
+      expect(messageData.statusCodes).toBeUndefined();
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/node-graphs/utils/utils.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/node-graphs/utils/utils.spec.ts
new file mode 100644
index 000000000..2857fc44c
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/node-graphs/utils/utils.spec.ts
@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest';
+import { versionMatches, getOperationFields } from '../../../node-graphs/utils/utils';
+
+describe('versionMatches', () => {
+  describe('when configVersion is undefined or "latest"', () => {
+    it('returns true when configVersion is undefined (matches any message version)', () => {
+      expect(versionMatches(undefined, '1.0.0')).toBe(true);
+      expect(versionMatches(undefined, '2.0.0')).toBe(true);
+      expect(versionMatches(undefined, 'latest')).toBe(true);
+      expect(versionMatches(undefined, undefined)).toBe(true);
+    });
+
+    it('returns true when configVersion is "latest" (matches any message version)', () => {
+      expect(versionMatches('latest', '1.0.0')).toBe(true);
+      expect(versionMatches('latest', '2.0.0')).toBe(true);
+      expect(versionMatches('latest', 'latest')).toBe(true);
+      expect(versionMatches('latest', undefined)).toBe(true);
+    });
+  });
+
+  describe('when messageVersion is undefined or "latest"', () => {
+    it('returns false when configVersion is specific but messageVersion is undefined', () => {
+      expect(versionMatches('1.0.0', undefined)).toBe(false);
+      expect(versionMatches('2.0.0', undefined)).toBe(false);
+    });
+
+    it('returns false when configVersion is specific but messageVersion is "latest"', () => {
+      expect(versionMatches('1.0.0', 'latest')).toBe(false);
+      expect(versionMatches('2.0.0', 'latest')).toBe(false);
+    });
+  });
+
+  describe('when both versions are specific', () => {
+    it('returns true when versions match exactly', () => {
+      expect(versionMatches('1.0.0', '1.0.0')).toBe(true);
+      expect(versionMatches('2.0.0', '2.0.0')).toBe(true);
+      expect(versionMatches('0.0.1', '0.0.1')).toBe(true);
+      expect(versionMatches('1.0.1', '1.0.1')).toBe(true);
+    });
+
+    it('returns false when versions do not match', () => {
+      expect(versionMatches('1.0.0', '2.0.0')).toBe(false);
+      expect(versionMatches('0.0.1', '1.0.1')).toBe(false);
+      expect(versionMatches('1.0.0', '1.0.1')).toBe(false);
+      expect(versionMatches('1.0.0', '0.0.1')).toBe(false);
+    });
+  });
+
+  describe('should_handle_undefined_accepted_version', () => {
+    it('matches any actualMessageVersion when acceptedVersion is undefined', () => {
+      expect(versionMatches(undefined, '1.0.0')).toBe(true);
+      expect(versionMatches(undefined, '2.5.3')).toBe(true);
+      expect(versionMatches(undefined, '0.0.1')).toBe(true);
+    });
+  });
+
+  describe('should_handle_latest_accepted_version', () => {
+    it('matches any actualMessageVersion when acceptedVersion is latest', () => {
+      expect(versionMatches('latest', '1.0.0')).toBe(true);
+      expect(versionMatches('latest', '2.5.3')).toBe(true);
+      expect(versionMatches('latest', '0.0.1')).toBe(true);
+    });
+  });
+
+  describe('should_handle_undefined_actual_version', () => {
+    it('only matches undefined or latest acceptedVersion when actualMessageVersion is undefined', () => {
+      expect(versionMatches(undefined, undefined)).toBe(true);
+      expect(versionMatches('latest', undefined)).toBe(true);
+      expect(versionMatches('1.0.0', undefined)).toBe(false);
+      expect(versionMatches('^1.0.0', undefined)).toBe(false);
+    });
+  });
+
+  describe('should_delegate_to_generic_utility_for_exact_match', () => {
+    it('matches exact versions through delegation', () => {
+      expect(versionMatches('1.0.0', '1.0.0')).toBe(true);
+      expect(versionMatches('2.5.3', '2.5.3')).toBe(true);
+    });
+  });
+
+  describe('should_delegate_to_generic_utility_for_semver_patterns', () => {
+    it('matches semver ranges through delegation', () => {
+      expect(versionMatches('^1.0.0', '1.2.3')).toBe(true);
+      expect(versionMatches('~1.2.0', '1.2.5')).toBe(true);
+      expect(versionMatches('>=1.0.0 <2.0.0', '1.5.0')).toBe(true);
+    });
+
+    it('does not match when version does not satisfy range', () => {
+      expect(versionMatches('^2.0.0', '1.0.0')).toBe(false);
+      expect(versionMatches('~1.2.0', '1.3.0')).toBe(false);
+    });
+  });
+
+  describe('should_delegate_to_generic_utility_for_x_patterns', () => {
+    it('matches x-patterns through delegation', () => {
+      expect(versionMatches('1.x', '1.2.3')).toBe(true);
+      expect(versionMatches('1.2.x', '1.2.5')).toBe(true);
+      expect(versionMatches('2.x', '2.0.0')).toBe(true);
+    });
+
+    it('does not match when x-pattern differs', () => {
+      expect(versionMatches('2.x', '1.0.0')).toBe(false);
+      expect(versionMatches('1.2.x', '1.3.0')).toBe(false);
+    });
+  });
+});
+
+describe('getOperationFields', () => {
+  it('returns empty object when no operation field exists', () => {
+    expect(getOperationFields({ id: 'test', version: '1.0.0' })).toEqual({});
+  });
+
+  it('returns empty object when operation is undefined', () => {
+    expect(getOperationFields({ operation: undefined })).toEqual({});
+  });
+
+  it('extracts method from operation', () => {
+    const result = getOperationFields({ operation: { method: 'GET' } });
+    expect(result).toEqual({ method: 'GET' });
+  });
+
+  it('extracts path from operation', () => {
+    const result = getOperationFields({ operation: { path: '/orders' } });
+    expect(result).toEqual({ path: '/orders' });
+  });
+
+  it('extracts statusCodes from operation and converts to numbers', () => {
+    const result = getOperationFields({ operation: { statusCodes: ['200', '404', '500'] } });
+    expect(result).toEqual({ statusCodes: [200, 404, 500] });
+  });
+
+  it('extracts all operation fields together', () => {
+    const result = getOperationFields({
+      operation: { method: 'POST', path: '/orders', statusCodes: ['201', '400'] },
+    });
+    expect(result).toEqual({ method: 'POST', path: '/orders', statusCodes: [201, 400] });
+  });
+
+  it('ignores empty statusCodes array', () => {
+    const result = getOperationFields({ operation: { method: 'GET', statusCodes: [] } });
+    expect(result).toEqual({ method: 'GET' });
+  });
+
+  it('filters out non-numeric statusCodes', () => {
+    const result = getOperationFields({ operation: { statusCodes: ['200', 'abc', '404'] } });
+    expect(result).toEqual({ statusCodes: [200, 404] });
+  });
+
+  it('ignores non-relevant operation fields like action and protocol', () => {
+    const result = getOperationFields({
+      operation: { method: 'GET', path: '/orders', action: 'send', protocol: 'http' },
+    });
+    expect(result).toEqual({ method: 'GET', path: '/orders' });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/protobuf-schema.test.ts b/packages/core/eventcatalog/src/utils/__tests__/protobuf-schema.test.ts
new file mode 100644
index 000000000..0853c6bc8
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/protobuf-schema.test.ts
@@ -0,0 +1,238 @@
+import { describe, expect, it } from 'vitest';
+import { parseProtobufSchema } from '../protobuf-schema';
+
+describe('parseProtobufSchema', () => {
+  it('parses a simple proto3 message', () => {
+    const schema = parseProtobufSchema(`
+      syntax = "proto3";
+
+      package com.example.frauddetection;
+
+      message FraudCheckCompleted {
+        string transactionId = 1;
+        int32 riskScore = 2;
+        repeated string reasons = 3;
+        double confidence = 4;
+      }
+    `);
+
+    expect(schema.syntax).toBe('proto3');
+    expect(schema.package).toBe('com.example.frauddetection');
+    expect(schema.messages).toHaveLength(1);
+
+    const message = schema.messages[0];
+    expect(message.name).toBe('FraudCheckCompleted');
+    expect(message.fields).toEqual([
+      { name: 'transactionId', type: 'string', number: 1, label: undefined, oneof: undefined, doc: undefined },
+      { name: 'riskScore', type: 'int32', number: 2, label: undefined, oneof: undefined, doc: undefined },
+      { name: 'reasons', type: 'string', number: 3, label: 'repeated', oneof: undefined, doc: undefined },
+      { name: 'confidence', type: 'double', number: 4, label: undefined, oneof: undefined, doc: undefined },
+    ]);
+  });
+
+  it('parses multiple top-level messages', () => {
+    const schema = parseProtobufSchema(`
+      syntax = "proto3";
+
+      message OrderPlaced {
+        string order_id = 1;
+      }
+
+      message OrderCancelled {
+        string order_id = 1;
+        string reason = 2;
+      }
+    `);
+
+    expect(schema.messages.map((m) => m.name)).toEqual(['OrderPlaced', 'OrderCancelled']);
+  });
+
+  it('parses nested messages and enums', () => {
+    const schema = parseProtobufSchema(`
+      syntax = "proto3";
+
+      message Order {
+        message LineItem {
+          string sku = 1;
+          int32 quantity = 2;
+        }
+
+        enum Status {
+          PENDING = 0;
+          CONFIRMED = 1;
+        }
+
+        string order_id = 1;
+        repeated LineItem items = 2;
+        Status status = 3;
+      }
+    `);
+
+    const order = schema.messages[0];
+    expect(order.messages).toHaveLength(1);
+    expect(order.messages[0].name).toBe('LineItem');
+    expect(order.messages[0].fields.map((f) => f.name)).toEqual(['sku', 'quantity']);
+    expect(order.enums).toHaveLength(1);
+    expect(order.enums[0].name).toBe('Status');
+    expect(order.enums[0].values).toEqual([
+      { name: 'PENDING', value: 0, doc: undefined },
+      { name: 'CONFIRMED', value: 1, doc: undefined },
+    ]);
+    expect(order.fields.map((f) => f.type)).toEqual(['string', 'LineItem', 'Status']);
+  });
+
+  it('captures leading and trailing comments as field docs', () => {
+    const schema = parseProtobufSchema(`
+      syntax = "proto3";
+
+      // Emitted when a fraud check completes.
+      message FraudCheckCompleted {
+        // The unique transaction identifier.
+        string transaction_id = 1;
+        int32 risk_score = 2; // Score between 0 and 100
+        /**
+         * The decision made by the fraud engine.
+         */
+        string decision = 3;
+      }
+    `);
+
+    const message = schema.messages[0];
+    expect(message.doc).toBe('Emitted when a fraud check completes.');
+    expect(message.fields[0].doc).toBe('The unique transaction identifier.');
+    expect(message.fields[1].doc).toBe('Score between 0 and 100');
+    expect(message.fields[2].doc).toBe('The decision made by the fraud engine.');
+  });
+
+  it('parses map fields', () => {
+    const schema = parseProtobufSchema(`
+      syntax = "proto3";
+
+      message Order {
+        map<string, int32> quantities = 1;
+      }
+    `);
+
+    const field = schema.messages[0].fields[0];
+    expect(field.name).toBe('quantities');
+    expect(field.type).toBe('map<string, int32>');
+    expect(field.map).toEqual({ keyType: 'string', valueType: 'int32' });
+  });
+
+  it('parses oneof fields', () => {
+    const schema = parseProtobufSchema(`
+      syntax = "proto3";
+
+      message Payment {
+        oneof payment_method {
+          string card_token = 1;
+          string paypal_id = 2;
+        }
+        string currency = 3;
+      }
+    `);
+
+    const fields = schema.messages[0].fields;
+    expect(fields[0]).toMatchObject({ name: 'card_token', oneof: 'payment_method' });
+    expect(fields[1]).toMatchObject({ name: 'paypal_id', oneof: 'payment_method' });
+    expect(fields[2].oneof).toBeUndefined();
+  });
+
+  it('parses proto2 required and optional labels', () => {
+    const schema = parseProtobufSchema(`
+      syntax = "proto2";
+
+      message User {
+        required string id = 1;
+        optional string nickname = 2;
+      }
+    `);
+
+    const fields = schema.messages[0].fields;
+    expect(fields[0].label).toBe('required');
+    expect(fields[1].label).toBe('optional');
+  });
+
+  it('parses top-level enums', () => {
+    const schema = parseProtobufSchema(`
+      syntax = "proto3";
+
+      // The decision outcome.
+      enum Decision {
+        APPROVED = 0;
+        DECLINED = 1; // Transaction was declined
+        MANUAL_REVIEW = 2;
+      }
+    `);
+
+    expect(schema.enums).toHaveLength(1);
+    expect(schema.enums[0].doc).toBe('The decision outcome.');
+    expect(schema.enums[0].values[1]).toEqual({ name: 'DECLINED', value: 1, doc: 'Transaction was declined' });
+  });
+
+  it('ignores imports, options, reserved fields, field options and services', () => {
+    const schema = parseProtobufSchema(`
+      syntax = "proto3";
+
+      import "google/protobuf/timestamp.proto";
+
+      option java_package = "com.example";
+      option (custom.aggregate) = { foo: 1 };
+
+      message Order {
+        option deprecated = true;
+        reserved 4, 5;
+        reserved "old_field";
+        string order_id = 1 [deprecated = true];
+        google.protobuf.Timestamp created_at = 2;
+      }
+
+      service OrderService {
+        rpc GetOrder (GetOrderRequest) returns (Order);
+      }
+    `);
+
+    const order = schema.messages[0];
+    expect(order.fields.map((f) => f.name)).toEqual(['order_id', 'created_at']);
+    expect(order.fields[1].type).toBe('google.protobuf.Timestamp');
+  });
+
+  it('parses fully-qualified type names with a leading dot', () => {
+    const schema = parseProtobufSchema(`
+      syntax = "proto3";
+
+      package com.example;
+
+      message Order {
+        .google.protobuf.Timestamp created_at = 1;
+        .com.example.LineItem item = 2;
+      }
+
+      message LineItem {
+        string sku = 1;
+      }
+    `);
+
+    const order = schema.messages[0];
+    expect(order.fields[0].type).toBe('.google.protobuf.Timestamp');
+    expect(order.fields[1].type).toBe('.com.example.LineItem');
+  });
+
+  it('throws on empty content', () => {
+    expect(() => parseProtobufSchema('')).toThrow('Protobuf schema is empty');
+  });
+
+  it('throws on non-protobuf content', () => {
+    expect(() => parseProtobufSchema('{"type": "object", "properties": {}}')).toThrow();
+  });
+
+  it('throws on an unclosed message', () => {
+    expect(() =>
+      parseProtobufSchema(`
+        syntax = "proto3";
+        message Order {
+          string order_id = 1;
+      `)
+    ).toThrow('Unexpected end of message "Order"');
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/queries/mocks.ts b/packages/core/eventcatalog/src/utils/__tests__/queries/mocks.ts
new file mode 100644
index 000000000..673c3899e
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/queries/mocks.ts
@@ -0,0 +1,206 @@
+export const mockServices = [
+  {
+    id: 'OrderService',
+    slug: 'OrderService',
+    collection: 'services',
+    data: {
+      id: 'OrderService',
+      version: '0.0.1',
+      sends: [
+        {
+          id: 'GetLatestOrder',
+          version: '0.0.1',
+        },
+      ],
+      receives: [
+        {
+          id: 'GetProductStatus',
+          version: '0.0.1',
+          from: [
+            {
+              id: 'EmailChannel',
+              version: '1.0.0',
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    id: 'PaymentService',
+    slug: 'PaymentService',
+    collection: 'services',
+    data: {
+      id: 'PaymentService',
+      version: '0.0.1',
+      receives: [
+        {
+          id: 'GetLatestOrder',
+          version: '0.0.1',
+        },
+      ],
+    },
+  },
+  {
+    id: 'InventoryService',
+    slug: 'InventoryService',
+    collection: 'services',
+    data: {
+      id: 'InventoryService',
+      version: '0.0.1',
+      sends: [
+        {
+          id: 'GetInventoryItem',
+          version: '>1.2.0',
+        },
+        {
+          id: 'GetProductStatus',
+          version: '0.0.1',
+          from: [
+            {
+              id: 'EmailChannel',
+              version: '1.0.0',
+            },
+          ],
+        },
+        {
+          id: 'GetStockStatus',
+          version: 'latest',
+        },
+      ],
+    },
+  },
+  {
+    id: 'CatalogService',
+    slug: 'CatalogService',
+    collection: 'services',
+    data: {
+      id: 'CatalogService',
+      version: '0.0.1',
+      receives: [
+        {
+          id: 'GetInventoryItem',
+        },
+        {
+          id: 'GetStockStatus',
+          version: '*',
+        },
+      ],
+    },
+  },
+  {
+    id: 'LegacyOrderService',
+    slug: 'LegacyOrderService',
+    collection: 'services',
+    data: {
+      id: 'LegacyOrderService',
+      version: '0.0.1',
+      receives: [
+        {
+          id: 'GetOrderLegacy',
+        },
+      ],
+      sends: [
+        {
+          id: 'GetOrderLegacy',
+        },
+      ],
+    },
+  },
+];
+
+export const mockQueries = [
+  {
+    id: 'GetLatestOrder',
+    slug: 'GetLatestOrder',
+    collection: 'queries',
+    data: {
+      id: 'GetLatestOrder',
+      version: '0.0.1',
+    },
+  },
+  {
+    id: 'GetInventoryItem',
+    slug: 'GetInventoryItem',
+    collection: 'queries',
+    data: {
+      id: 'GetInventoryItem',
+      version: '1.5.1',
+    },
+  },
+  {
+    id: 'GetStockStatus',
+    slug: 'GetStockStatus',
+    collection: 'queries',
+    data: {
+      id: 'GetStockStatus',
+      version: '0.0.1',
+    },
+  },
+  {
+    id: 'GetStockStatus',
+    slug: 'GetStockStatus',
+    collection: 'queries',
+    data: {
+      id: 'GetStockStatus',
+      version: '1.0.0',
+    },
+  },
+  {
+    id: 'GetProductStatus',
+    slug: 'GetProductStatus',
+    collection: 'queries',
+    data: {
+      id: 'GetProductStatus',
+      version: '0.0.1',
+    },
+  },
+  {
+    id: 'GetOrderLegacy',
+    slug: 'GetOrderLegacy',
+    collection: 'queries',
+    data: {
+      id: 'GetOrderLegacy',
+      version: '0.0.1',
+    },
+  },
+];
+
+export const mockChannels = [
+  {
+    id: 'EmailChannel',
+    slug: 'EmailChannel',
+    collection: 'channels',
+    data: {
+      id: 'EmailChannel',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockDataProducts = [
+  {
+    id: 'OrderAnalytics-1.0.0',
+    slug: 'OrderAnalytics',
+    collection: 'data-products',
+    data: {
+      id: 'OrderAnalytics',
+      name: 'Order Analytics',
+      version: '1.0.0',
+      inputs: [{ id: 'GetLatestOrder', version: '0.0.1' }],
+      outputs: [],
+    },
+  },
+  {
+    id: 'OrderDataPipeline-1.0.0',
+    slug: 'OrderDataPipeline',
+    collection: 'data-products',
+    data: {
+      id: 'OrderDataPipeline',
+      name: 'Order Data Pipeline',
+      version: '1.0.0',
+      inputs: [],
+      outputs: [{ id: 'GetLatestOrder', version: '0.0.1' }],
+    },
+  },
+];
diff --git a/packages/core/eventcatalog/src/utils/__tests__/queries/node-graph.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/queries/node-graph.spec.ts
new file mode 100644
index 000000000..56df6d869
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/queries/node-graph.spec.ts
@@ -0,0 +1,475 @@
+import { MarkerType } from '@xyflow/react';
+import { getNodesAndEdgesForQueries as getNodesAndEdges } from '../../node-graphs/message-node-graph';
+import { expect, describe, it, vi, beforeEach } from 'vitest';
+import { mockQueries, mockServices, mockChannels, mockDataProducts } from './mocks';
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: (key: string) => {
+      if (key === 'services') {
+        return Promise.resolve(mockServices);
+      }
+      if (key === 'queries') {
+        return Promise.resolve(mockQueries);
+      }
+      if (key === 'channels') {
+        return Promise.resolve(mockChannels);
+      }
+      if (key === 'data-products') {
+        return Promise.resolve(mockDataProducts);
+      }
+      return Promise.resolve([]);
+    },
+  };
+});
+
+describe('Queries NodeGraph', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('getNodesAndEdges', () => {
+    it('should return nodes and edges for a given query', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'GetLatestOrder', version: '0.0.1' });
+
+      // The middle node itself, the service
+      const expectedQueryNode = {
+        id: 'GetLatestOrder-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        // data: { mode: 'simple', message: expect.anything(), showTarget: false, showSource: false },
+        data: expect.anything(),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'queries',
+      };
+
+      const expectedProducerNode = {
+        id: 'OrderService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[0].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedConsumerNode = {
+        id: 'PaymentService-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({
+          title: 'PaymentService',
+          mode: 'simple',
+          service: { ...mockServices[1].data },
+        }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        expect.objectContaining({
+          id: 'OrderService-0.0.1-GetLatestOrder-0.0.1',
+          source: 'OrderService-0.0.1',
+          target: 'GetLatestOrder-0.0.1',
+          label: 'requests',
+        }),
+        expect.objectContaining({
+          id: 'GetLatestOrder-0.0.1-PaymentService-0.0.1',
+          source: 'GetLatestOrder-0.0.1',
+          target: 'PaymentService-0.0.1',
+          label: 'accepts',
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedConsumerNode),
+
+          // The event node itself
+          expect.objectContaining(expectedQueryNode),
+
+          // Nodes on the right
+          expect.objectContaining(expectedProducerNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('if the query is produced and consumed by a service it will render a custom edge', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'GetOrderLegacy', version: '0.0.1' });
+
+      // The middle node itself, the service
+      const expectedQueryNode = {
+        id: 'GetOrderLegacy-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', message: expect.anything() }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'queries',
+      };
+
+      const expectedProducerNode = {
+        id: 'LegacyOrderService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[4].data }, title: 'LegacyOrderService' }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedConsumerNode = {
+        id: 'LegacyOrderService-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({
+          title: 'LegacyOrderService',
+          mode: 'simple',
+          service: { ...mockServices[4].data },
+        }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        expect.objectContaining({
+          id: 'LegacyOrderService-0.0.1-GetOrderLegacy-0.0.1',
+          source: 'LegacyOrderService-0.0.1',
+          target: 'GetOrderLegacy-0.0.1',
+          label: 'requests',
+        }),
+        expect.objectContaining({
+          id: 'GetOrderLegacy-0.0.1-LegacyOrderService-0.0.1',
+          source: 'GetOrderLegacy-0.0.1',
+          target: 'LegacyOrderService-0.0.1',
+          label: 'accepts',
+        }),
+        expect.objectContaining({
+          id: 'GetOrderLegacy-0.0.1-LegacyOrderService-0.0.1-both',
+          source: 'GetOrderLegacy-0.0.1',
+          target: 'LegacyOrderService-0.0.1',
+          label: 'publishes and subscribes',
+          animated: false,
+          markerEnd: {
+            type: MarkerType.ArrowClosed,
+            width: 20,
+            height: 20,
+          },
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedConsumerNode),
+
+          // The query node itself
+          expect.objectContaining(expectedQueryNode),
+
+          // Nodes on the right
+          expect.objectContaining(expectedProducerNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('if the consumer of a query has defined a channel, it will render the channel node and edges', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'GetProductStatus', version: '0.0.1' });
+
+      const expectedConsumerNode = {
+        id: 'OrderService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[0].data }, title: 'OrderService' }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedChannelNode = {
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        id: 'EmailChannel-1.0.0',
+        type: 'channels',
+      };
+
+      const expectedQueryNode = {
+        id: 'GetProductStatus-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        type: 'queries',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        // Message to the channel
+        expect.objectContaining({
+          id: 'GetProductStatus-0.0.1-EmailChannel-1.0.0',
+          source: 'GetProductStatus-0.0.1',
+          target: 'EmailChannel-1.0.0',
+        }),
+        // Channel to the consumer
+        expect.objectContaining({
+          id: 'EmailChannel-1.0.0-OrderService-0.0.1',
+          source: 'EmailChannel-1.0.0',
+          target: 'OrderService-0.0.1',
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedConsumerNode),
+
+          // channel
+          expect.objectContaining(expectedChannelNode),
+
+          // The query node itself
+          expect.objectContaining(expectedQueryNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('if the producer of a query has defined a channel, it will render the channel node and edges', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'GetProductStatus', version: '0.0.1' });
+
+      const expectedProducerNode = {
+        id: 'InventoryService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedChannelNode = {
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        id: 'EmailChannel-1.0.0',
+        type: 'channels',
+      };
+
+      const expectedQueryNode = {
+        id: 'GetProductStatus-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        type: 'queries',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        // Producer to the message
+        expect.objectContaining({
+          id: 'InventoryService-0.0.1-GetProductStatus-0.0.1',
+          source: 'InventoryService-0.0.1',
+          target: 'GetProductStatus-0.0.1',
+          label: 'requests',
+          animated: false,
+        }),
+        // Message to the channel
+        expect.objectContaining({
+          id: 'GetProductStatus-0.0.1-EmailChannel-1.0.0',
+          source: 'GetProductStatus-0.0.1',
+          target: 'EmailChannel-1.0.0',
+          label: 'routes to',
+          animated: false,
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedProducerNode),
+
+          // channel
+          expect.objectContaining(expectedChannelNode),
+
+          // The query node itself
+          expect.objectContaining(expectedQueryNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('returns empty nodes and edges if no query is found', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownQuery', version: '1.0.0' });
+
+      expect(nodes).toEqual([]);
+      expect(edges).toEqual([]);
+    });
+
+    it('should return nodes and edges for a given query using semver range', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'GetInventoryItem', version: '1.5.1' });
+
+      // The middle node itself, the service
+      const expectedQueryNode = {
+        id: 'GetInventoryItem-1.5.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.anything(),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'queries',
+      };
+
+      const expectedProducerNode = {
+        id: 'InventoryService-0.0.1',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[2].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedConsumerNode = {
+        id: 'CatalogService-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ title: 'CatalogService', mode: 'simple', service: { ...mockServices[3].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        expect.objectContaining({
+          id: 'InventoryService-0.0.1-GetInventoryItem-1.5.1',
+          source: 'InventoryService-0.0.1',
+          target: 'GetInventoryItem-1.5.1',
+          label: 'requests',
+        }),
+        expect.objectContaining({
+          id: 'GetInventoryItem-1.5.1-CatalogService-0.0.1',
+          source: 'GetInventoryItem-1.5.1',
+          target: 'CatalogService-0.0.1',
+          label: 'accepts',
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedProducerNode),
+
+          // The event node itself
+          expect.objectContaining(expectedQueryNode),
+
+          // Nodes on the right
+          expect.objectContaining(expectedConsumerNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    describe('data products', () => {
+      it('should render data product as a consumer when it has the query as an input', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'GetLatestOrder', version: '0.0.1' });
+
+        const expectedDataProductConsumerNode = {
+          id: 'OrderAnalytics-1.0.0',
+          type: 'data-products',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({
+            title: 'OrderAnalytics',
+            mode: 'simple',
+            dataProduct: expect.objectContaining({
+              id: 'OrderAnalytics',
+              version: '1.0.0',
+            }),
+          }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        expect(nodes).toEqual(expect.arrayContaining([expect.objectContaining(expectedDataProductConsumerNode)]));
+
+        expect(edges).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'GetLatestOrder-0.0.1-OrderAnalytics-1.0.0',
+              source: 'GetLatestOrder-0.0.1',
+              target: 'OrderAnalytics-1.0.0',
+              label: 'consumed by',
+            }),
+          ])
+        );
+      });
+
+      it('should render data product as a producer when it has the query as an output', async () => {
+        const { nodes, edges } = await getNodesAndEdges({ id: 'GetLatestOrder', version: '0.0.1' });
+
+        const expectedDataProductProducerNode = {
+          id: 'OrderDataPipeline-1.0.0',
+          type: 'data-products',
+          sourcePosition: 'right',
+          targetPosition: 'left',
+          data: expect.objectContaining({
+            mode: 'simple',
+            dataProduct: expect.objectContaining({
+              id: 'OrderDataPipeline',
+              version: '1.0.0',
+            }),
+          }),
+          position: { x: expect.any(Number), y: expect.any(Number) },
+        };
+
+        expect(nodes).toEqual(expect.arrayContaining([expect.objectContaining(expectedDataProductProducerNode)]));
+
+        expect(edges).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderDataPipeline-1.0.0-GetLatestOrder-0.0.1',
+              source: 'OrderDataPipeline-1.0.0',
+              target: 'GetLatestOrder-0.0.1',
+              label: 'produces',
+            }),
+          ])
+        );
+      });
+
+      it('should render both services and data products as producers and consumers', async () => {
+        const { nodes } = await getNodesAndEdges({ id: 'GetLatestOrder', version: '0.0.1' });
+
+        // Should have service producer
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderService-0.0.1',
+              type: 'services',
+            }),
+          ])
+        );
+
+        // Should have service consumer
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'PaymentService-0.0.1',
+              type: 'services',
+            }),
+          ])
+        );
+
+        // Should have data product producer
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderDataPipeline-1.0.0',
+              type: 'data-products',
+            }),
+          ])
+        );
+
+        // Should have data product consumer
+        expect(nodes).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: 'OrderAnalytics-1.0.0',
+              type: 'data-products',
+            }),
+          ])
+        );
+      });
+    });
+  });
+});
diff --git a/eventcatalog/src/utils/__tests__/queries/queries.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/queries/queries.spec.ts
similarity index 93%
rename from eventcatalog/src/utils/__tests__/queries/queries.spec.ts
rename to packages/core/eventcatalog/src/utils/__tests__/queries/queries.spec.ts
index 6e4907c91..cbb0cb19f 100644
--- a/eventcatalog/src/utils/__tests__/queries/queries.spec.ts
+++ b/packages/core/eventcatalog/src/utils/__tests__/queries/queries.spec.ts
@@ -1,13 +1,13 @@
-import type { ContentCollectionKey } from 'astro:content';
+import type { CollectionKey } from 'astro:content';
 import { expect, describe, it, vi } from 'vitest';
 import { mockServices, mockQueries } from './mocks';
-import { getQueries } from '@utils/queries';
+import { getQueries } from '@utils/collections/queries';
 
 vi.mock('astro:content', async (importOriginal) => {
   return {
     ...(await importOriginal<typeof import('astro:content')>()),
     // this will only affect "foo" outside of the original module
-    getCollection: (key: ContentCollectionKey) => {
+    getCollection: (key: CollectionKey) => {
       switch (key) {
         case 'services':
           return Promise.resolve(mockServices);
diff --git a/packages/core/eventcatalog/src/utils/__tests__/remote-file.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/remote-file.spec.ts
new file mode 100644
index 000000000..2fab4a0bf
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/remote-file.spec.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { resolveTemplateVariables } from '@utils/remote-file';
+
+describe('resolveTemplateVariables', () => {
+  it('resolves placeholders from process.env fallback', () => {
+    process.env.AZURE_DEVOPS_PAT_BASE64 = 'abc123';
+
+    expect(resolveTemplateVariables('Basic ${AZURE_DEVOPS_PAT_BASE64}')).toBe('Basic abc123');
+  });
+
+  it('resolves nested object values', () => {
+    process.env.API_KEY = 'secret';
+
+    expect(resolveTemplateVariables({ headers: { Authorization: 'Bearer ${API_KEY}' } })).toEqual({
+      headers: { Authorization: 'Bearer secret' },
+    });
+  });
+
+  it('returns empty string when variable is missing', () => {
+    delete process.env.MISSING_VAR;
+
+    expect(resolveTemplateVariables('x-${MISSING_VAR}-y')).toBe('x--y');
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/remote-spec.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/remote-spec.spec.ts
new file mode 100644
index 000000000..3371c2844
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/remote-spec.spec.ts
@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { isSameOrigin, resolveHeaderTemplates, resolveHeaders } from '@utils/remote-spec';
+
+describe('remote-spec utils', () => {
+  it('resolves allowed prefixed env vars by default', () => {
+    process.env.EVENTCATALOG_TOKEN = 'abc123';
+
+    expect(resolveHeaderTemplates('Bearer ${EVENTCATALOG_TOKEN}')).toBe('Bearer abc123');
+  });
+
+  it('does not resolve non-prefixed env vars by default', () => {
+    process.env.DATABASE_URL = 'secret';
+
+    expect(resolveHeaderTemplates('Leak ${DATABASE_URL}')).toBe('Leak ');
+  });
+
+  it('resolves any env var when allowAnyEnvInHeaders is enabled', () => {
+    process.env.DATABASE_URL = 'secret';
+
+    expect(resolveHeaderTemplates('Leak ${DATABASE_URL}', { allowAnyEnvInHeaders: true })).toBe('Leak secret');
+  });
+
+  it('resolves all headers in an object', () => {
+    process.env.EC_PAT = 'token';
+
+    expect(resolveHeaders({ Authorization: 'Basic ${EC_PAT}', 'X-Test': 'static' })).toEqual({
+      Authorization: 'Basic token',
+      'X-Test': 'static',
+    });
+  });
+
+  it('checks same-origin accurately', () => {
+    expect(isSameOrigin('https://api.example.com/spec.yaml', 'https://api.example.com/refs/common.yaml')).toBe(true);
+    expect(isSameOrigin('https://api.example.com/spec.yaml', 'https://attacker.example/ref.yaml')).toBe(false);
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/resource-reference-colors.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/resource-reference-colors.spec.ts
new file mode 100644
index 000000000..894032ee2
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/resource-reference-colors.spec.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { getCollectionTextColorClass } from '@utils/collection-colors';
+import { getResourceReferenceColorName, getResourceReferenceStyle } from '@utils/resource-reference-colors';
+
+describe('resource-reference-colors', () => {
+  it('maps resource types to the same colors used in the explore tables', () => {
+    expect(getResourceReferenceColorName('service')).toBe('pink');
+    expect(getResourceReferenceColorName('agent')).toBe('sky');
+    expect(getResourceReferenceColorName('event')).toBe('orange');
+    expect(getResourceReferenceColorName('command')).toBe('blue');
+    expect(getResourceReferenceColorName('query')).toBe('green');
+    expect(getResourceReferenceColorName('domain')).toBe('yellow');
+    expect(getResourceReferenceColorName('flow')).toBe('teal');
+    expect(getResourceReferenceColorName('channel')).toBe('purple');
+    expect(getResourceReferenceColorName('entity')).toBe('purple');
+    expect(getResourceReferenceColorName('container')).toBe('indigo');
+    expect(getResourceReferenceColorName('team')).toBe('gray');
+    expect(getResourceReferenceColorName('user')).toBe('gray');
+    expect(getResourceReferenceColorName('data-product')).toBe('cyan');
+  });
+
+  it('falls back to gray for unknown resource types', () => {
+    expect(getResourceReferenceColorName('unknown')).toBe('gray');
+  });
+
+  it('returns CSS variables using the Tailwind 500 shade', () => {
+    expect(getResourceReferenceStyle('service')).toBe(
+      '--ec-resource-ref-bg: rgb(236 72 153 / 0.12); --ec-resource-ref-color: rgb(236 72 153); color: var(--ec-resource-ref-color); text-decoration-color: var(--ec-resource-ref-color)'
+    );
+  });
+
+  it('uses the active theme accent color for custom documentation references', () => {
+    expect(getResourceReferenceStyle('doc')).toBe(
+      '--ec-resource-ref-bg: rgb(var(--ec-accent) / 0.12); --ec-resource-ref-color: rgb(var(--ec-accent)); color: var(--ec-resource-ref-color); text-decoration-color: var(--ec-resource-ref-color)'
+    );
+  });
+
+  it('returns static Tailwind text classes for collection colors', () => {
+    expect(getCollectionTextColorClass('indigo')).toBe('text-indigo-500');
+    expect(getCollectionTextColorClass('sky')).toBe('text-sky-500');
+    expect(getCollectionTextColorClass('unknown', 'text-[rgb(var(--ec-icon-color))]')).toBe('text-[rgb(var(--ec-icon-color))]');
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/schema-utils.test.ts b/packages/core/eventcatalog/src/utils/__tests__/schema-utils.test.ts
new file mode 100644
index 000000000..c379b4e33
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/schema-utils.test.ts
@@ -0,0 +1,299 @@
+import { describe, it, expect } from 'vitest';
+import { extractSchemaProperties } from '../schema-utils';
+
+describe('extractSchemaProperties', () => {
+  describe('when given empty or invalid content', () => {
+    it('returns an empty array when content is empty', () => {
+      expect(extractSchemaProperties('', 'json')).toEqual([]);
+    });
+
+    it('returns an empty array when JSON is malformed', () => {
+      expect(extractSchemaProperties('{ broken json', 'json')).toEqual([]);
+    });
+
+    it('returns an empty array when JSON has no properties or fields', () => {
+      expect(extractSchemaProperties('{"type": "object"}', 'json')).toEqual([]);
+    });
+  });
+
+  describe('when parsing a JSON Schema', () => {
+    it('extracts field names, types, and descriptions from properties', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          orderId: { type: 'string', description: 'Unique order identifier' },
+          amount: { type: 'number', description: 'Total amount' },
+        },
+      });
+
+      const result = extractSchemaProperties(schema, 'json');
+
+      expect(result).toEqual([
+        { name: 'orderId', type: 'string', description: 'Unique order identifier', required: false },
+        { name: 'amount', type: 'number', description: 'Total amount', required: false },
+      ]);
+    });
+
+    it('marks fields listed in the required array as required', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          orderId: { type: 'string', description: 'Unique order identifier' },
+          notes: { type: 'string', description: 'Optional notes' },
+        },
+        required: ['orderId'],
+      });
+
+      const result = extractSchemaProperties(schema, 'json');
+
+      expect(result[0].required).toBe(true);
+      expect(result[1].required).toBe(false);
+    });
+
+    it('defaults description to empty string when not provided', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          orderId: { type: 'string' },
+        },
+      });
+
+      const result = extractSchemaProperties(schema, 'json');
+
+      expect(result[0].description).toBe('');
+    });
+
+    it('detects enum types when no explicit type is set', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          status: { enum: ['active', 'inactive'], description: 'Current status' },
+        },
+      });
+
+      const result = extractSchemaProperties(schema, 'json');
+
+      expect(result[0].type).toBe('enum');
+    });
+
+    it('detects $ref types when no explicit type is set', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          address: { $ref: '#/definitions/Address', description: 'Shipping address' },
+        },
+      });
+
+      const result = extractSchemaProperties(schema, 'json');
+
+      expect(result[0].type).toBe('$ref');
+    });
+
+    it('falls back to object type when no type, enum, or $ref is set', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          metadata: { description: 'Extra metadata' },
+        },
+      });
+
+      const result = extractSchemaProperties(schema, 'json');
+
+      expect(result[0].type).toBe('object');
+    });
+  });
+
+  describe('when parsing an Avro schema', () => {
+    it('extracts field names, types, and doc descriptions', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'OrderEvent',
+        fields: [
+          { name: 'orderId', type: 'string', doc: 'The order ID' },
+          { name: 'totalAmount', type: 'double', doc: 'Total order amount' },
+        ],
+      });
+
+      const result = extractSchemaProperties(schema, 'avro');
+
+      expect(result).toEqual([
+        { name: 'orderId', type: 'string', description: 'The order ID', required: true },
+        { name: 'totalAmount', type: 'double', description: 'Total order amount', required: true },
+      ]);
+    });
+
+    it('treats simple-typed fields as required', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Event',
+        fields: [{ name: 'id', type: 'string' }],
+      });
+
+      const result = extractSchemaProperties(schema, 'avro');
+
+      expect(result[0].required).toBe(true);
+    });
+
+    it('treats union types that include null as optional', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Event',
+        fields: [{ name: 'notes', type: ['null', 'string'], doc: 'Optional notes' }],
+      });
+
+      const result = extractSchemaProperties(schema, 'avro');
+
+      expect(result[0].required).toBe(false);
+      expect(result[0].type).toBe('null | string');
+    });
+
+    it('treats union types without null as required', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Event',
+        fields: [{ name: 'payload', type: ['string', 'int'] }],
+      });
+
+      const result = extractSchemaProperties(schema, 'avro');
+
+      expect(result[0].required).toBe(true);
+      expect(result[0].type).toBe('string | int');
+    });
+
+    it('formats array types as array<itemType>', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Event',
+        fields: [
+          {
+            name: 'tags',
+            type: { type: 'array', items: 'string' },
+            doc: 'List of tags',
+          },
+        ],
+      });
+
+      const result = extractSchemaProperties(schema, 'avro');
+
+      expect(result[0].type).toBe('array<string>');
+    });
+
+    it('formats nested record types using the record type name', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Event',
+        fields: [
+          {
+            name: 'address',
+            type: { type: 'record', name: 'Address', fields: [] },
+            doc: 'Shipping address',
+          },
+        ],
+      });
+
+      const result = extractSchemaProperties(schema, 'avro');
+
+      expect(result[0].type).toBe('record');
+    });
+
+    it('defaults description to empty string when doc is not provided', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Event',
+        fields: [{ name: 'id', type: 'string' }],
+      });
+
+      const result = extractSchemaProperties(schema, 'avro');
+
+      expect(result[0].description).toBe('');
+    });
+  });
+
+  describe('when parsing a Protobuf schema', () => {
+    it('extracts field names and types from message definitions', () => {
+      const proto = `
+syntax = "proto3";
+
+message PaymentEvent {
+  string transaction_id = 1;
+  double amount = 2;
+  string currency = 3;
+}`;
+
+      const result = extractSchemaProperties(proto, 'proto');
+
+      expect(result).toEqual([
+        { name: 'transaction_id', type: 'string', description: '', required: false },
+        { name: 'amount', type: 'double', description: '', required: false },
+        { name: 'currency', type: 'string', description: '', required: false },
+      ]);
+    });
+
+    it('captures inline comments as field descriptions', () => {
+      const proto = `
+message Event {
+  string id = 1; // Unique event identifier
+  int32 priority = 2; // Processing priority level
+}`;
+
+      const result = extractSchemaProperties(proto, 'proto');
+
+      expect(result[0].description).toBe('Unique event identifier');
+      expect(result[1].description).toBe('Processing priority level');
+    });
+
+    it('includes the modifier in the type for repeated fields', () => {
+      const proto = `
+message Event {
+  repeated string tags = 1;
+}`;
+
+      const result = extractSchemaProperties(proto, 'proto');
+
+      expect(result[0].type).toBe('repeated string');
+    });
+
+    it('includes the modifier in the type for optional fields', () => {
+      const proto = `
+message Event {
+  optional string notes = 1;
+}`;
+
+      const result = extractSchemaProperties(proto, 'proto');
+
+      expect(result[0].type).toBe('optional string');
+    });
+
+    it('returns an empty array when there are no field definitions', () => {
+      const proto = `
+syntax = "proto3";
+
+message Empty {
+}`;
+
+      const result = extractSchemaProperties(proto, 'proto');
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('when the format is unknown', () => {
+    it('attempts JSON parsing and returns results if valid', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'An ID' },
+        },
+      });
+
+      const result = extractSchemaProperties(schema, 'yaml');
+
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe('id');
+    });
+
+    it('returns an empty array if content is not valid JSON', () => {
+      expect(extractSchemaProperties('not json', 'xml')).toEqual([]);
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/schemas/schema-loader.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/schemas/schema-loader.spec.ts
new file mode 100644
index 000000000..325c3e698
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/schemas/schema-loader.spec.ts
@@ -0,0 +1,812 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { getMessageSchemasFromFrontmatter, loadMessageSchemas } from '@utils/collections/schema-loader';
+
+const originalScale = process.env.EVENTCATALOG_SCALE;
+
+describe('schema-loader', () => {
+  beforeEach(() => {
+    delete process.env.EVENTCATALOG_SCALE;
+  });
+
+  afterEach(() => {
+    if (originalScale === undefined) {
+      delete process.env.EVENTCATALOG_SCALE;
+      return;
+    }
+    process.env.EVENTCATALOG_SCALE = originalScale;
+  });
+
+  it('normalizes legacy schemaPath into a generated message schema resource', () => {
+    const schemas = getMessageSchemasFromFrontmatter({
+      collection: 'commands',
+      messageFilePath: '/catalog/commands/CancelShipment/index.mdx',
+      data: {
+        id: 'CancelShipment',
+        name: 'Cancel shipment',
+        version: '0.0.1',
+        summary: 'Cancels a shipment',
+        owners: ['dboyne'],
+        schemaPath: 'schema.json',
+      },
+    });
+
+    expect(schemas).toEqual([
+      {
+        id: 'schema:commands:CancelShipment:0.0.1:schema.json',
+        name: 'Schema',
+        version: '0.0.1',
+        format: 'jsonschema',
+        file: 'schema.json',
+        filePath: '/catalog/commands/CancelShipment/schema.json',
+        environments: undefined,
+        default: true,
+        message: {
+          collection: 'commands',
+          id: 'CancelShipment',
+          name: 'Cancel shipment',
+          version: '0.0.1',
+          summary: 'Cancels a shipment',
+          owners: ['dboyne'],
+        },
+        source: {
+          provider: 'file',
+          path: 'schema.json',
+        },
+      },
+    ]);
+  });
+
+  it('normalizes explicit message schemas with environment metadata', () => {
+    const schemas = getMessageSchemasFromFrontmatter({
+      collection: 'events',
+      messageFilePath: '/catalog/events/ShipmentCancelled/index.mdx',
+      data: {
+        id: 'ShipmentCancelled',
+        name: 'Shipment cancelled',
+        version: '1.0.0',
+        summary: 'A shipment was cancelled',
+        owners: ['shipping-team'],
+        schemas: [
+          {
+            id: 'shipment-cancelled-prod',
+            file: 'schema.prod.avsc',
+            name: 'Production',
+            environments: ['prod'],
+            default: true,
+          },
+          {
+            id: 'shipment-cancelled-uat',
+            file: 'schema.uat.avsc',
+            name: 'UAT',
+            environments: ['uat'],
+          },
+        ],
+      },
+    });
+
+    expect(schemas).toEqual([
+      {
+        id: 'schema:events:ShipmentCancelled:1.0.0:shipment-cancelled-prod',
+        schemaId: 'shipment-cancelled-prod',
+        name: 'Production',
+        version: '1.0.0',
+        format: 'avro',
+        file: 'schema.prod.avsc',
+        filePath: '/catalog/events/ShipmentCancelled/schema.prod.avsc',
+        environments: ['prod'],
+        default: true,
+        message: {
+          collection: 'events',
+          id: 'ShipmentCancelled',
+          name: 'Shipment cancelled',
+          version: '1.0.0',
+          summary: 'A shipment was cancelled',
+          owners: ['shipping-team'],
+        },
+        source: {
+          provider: 'file',
+          path: 'schema.prod.avsc',
+        },
+      },
+      {
+        id: 'schema:events:ShipmentCancelled:1.0.0:shipment-cancelled-uat',
+        schemaId: 'shipment-cancelled-uat',
+        name: 'UAT',
+        version: '1.0.0',
+        format: 'avro',
+        file: 'schema.uat.avsc',
+        filePath: '/catalog/events/ShipmentCancelled/schema.uat.avsc',
+        environments: ['uat'],
+        default: undefined,
+        message: {
+          collection: 'events',
+          id: 'ShipmentCancelled',
+          name: 'Shipment cancelled',
+          version: '1.0.0',
+          summary: 'A shipment was cancelled',
+          owners: ['shipping-team'],
+        },
+        source: {
+          provider: 'file',
+          path: 'schema.uat.avsc',
+        },
+      },
+    ]);
+  });
+
+  it('normalizes external schema references without local file metadata', () => {
+    const schemas = getMessageSchemasFromFrontmatter({
+      collection: 'events',
+      messageFilePath: '/catalog/events/ShipmentCancelled/index.mdx',
+      data: {
+        id: 'ShipmentCancelled',
+        version: '1.0.0',
+        schemas: [{ ref: 'git://contracts/events/ShipmentCancelled.schema.json', environments: ['prod'] }],
+      },
+    });
+
+    expect(schemas).toEqual([
+      {
+        id: 'schema:events:ShipmentCancelled:1.0.0:git://contracts/events/ShipmentCancelled.schema.json',
+        ref: 'git://contracts/events/ShipmentCancelled.schema.json',
+        name: 'ShipmentCancelled.schema.json',
+        version: '1.0.0',
+        format: 'unknown',
+        file: undefined,
+        filePath: undefined,
+        environments: ['prod'],
+        default: undefined,
+        message: {
+          collection: 'events',
+          id: 'ShipmentCancelled',
+          name: undefined,
+          version: '1.0.0',
+          summary: undefined,
+          owners: undefined,
+        },
+        source: {
+          provider: 'git',
+          path: undefined,
+        },
+      },
+    ]);
+  });
+
+  it('normalizes legacy external schema references that use id', () => {
+    const schemas = getMessageSchemasFromFrontmatter({
+      collection: 'events',
+      messageFilePath: '/catalog/events/ShipmentCancelled/index.mdx',
+      data: {
+        id: 'ShipmentCancelled',
+        version: '1.0.0',
+        schemas: [{ id: 'git://contracts/events/ShipmentCancelled.schema.json' }],
+      },
+    });
+
+    expect(schemas).toMatchObject([
+      {
+        id: 'schema:events:ShipmentCancelled:1.0.0:git://contracts/events/ShipmentCancelled.schema.json',
+        ref: 'git://contracts/events/ShipmentCancelled.schema.json',
+        source: {
+          provider: 'git',
+        },
+      },
+    ]);
+  });
+
+  it('normalizes file schema refs relative to the message file', () => {
+    const schemas = getMessageSchemasFromFrontmatter({
+      collection: 'events',
+      messageFilePath: '/catalog/events/OrderPlaced/index.mdx',
+      data: {
+        id: 'OrderPlaced',
+        version: '1.0.0',
+        schemas: [{ ref: 'file://./schemas/OrderPlaced.schema.json' }],
+      },
+    });
+
+    expect(schemas).toEqual([
+      {
+        id: 'schema:events:OrderPlaced:1.0.0:file://./schemas/OrderPlaced.schema.json',
+        ref: 'file://./schemas/OrderPlaced.schema.json',
+        name: 'OrderPlaced.schema.json',
+        version: '1.0.0',
+        format: 'jsonschema',
+        file: undefined,
+        filePath: '/catalog/events/OrderPlaced/schemas/OrderPlaced.schema.json',
+        environments: undefined,
+        default: undefined,
+        message: {
+          collection: 'events',
+          id: 'OrderPlaced',
+          name: undefined,
+          version: '1.0.0',
+          summary: undefined,
+          owners: undefined,
+        },
+        source: {
+          provider: 'file',
+          path: './schemas/OrderPlaced.schema.json',
+        },
+      },
+    ]);
+  });
+
+  it('loads colocated schemas from message files using raw glob patterns', async () => {
+    const catalogDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-loader-'));
+    const messageDir = path.join(catalogDir, 'domains', 'Orders', 'services', 'ShippingService', 'commands', 'CancelShipment');
+
+    await mkdir(messageDir, { recursive: true });
+    await writeFile(path.join(messageDir, 'schema.json'), '{"type":"object"}');
+    await writeFile(
+      path.join(messageDir, 'index.mdx'),
+      `---
+id: CancelShipment
+name: Cancel shipment
+version: 0.0.1
+schemaPath: schema.json
+---
+`
+    );
+
+    const schemas = await loadMessageSchemas({
+      base: catalogDir,
+      pattern: ['**/commands/*/index.{md,mdx}'],
+    });
+
+    expect(schemas).toHaveLength(1);
+    expect(schemas[0]).toMatchObject({
+      id: 'schema:commands:CancelShipment:0.0.1:schema.json',
+      message: {
+        collection: 'commands',
+        id: 'CancelShipment',
+        name: 'Cancel shipment',
+        version: '0.0.1',
+      },
+      file: 'schema.json',
+      format: 'jsonschema',
+      latest: true,
+    });
+  });
+
+  it('does not load schema entries when the referenced schema file is missing', async () => {
+    const catalogDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-loader-'));
+    const messageDir = path.join(catalogDir, 'events', 'OrderPlaced');
+
+    await mkdir(messageDir, { recursive: true });
+    await writeFile(
+      path.join(messageDir, 'index.mdx'),
+      `---
+id: OrderPlaced
+name: Order placed
+version: 1.0.0
+schemaPath: missing-schema.json
+---
+`
+    );
+
+    const schemas = await loadMessageSchemas({
+      base: catalogDir,
+      pattern: ['**/events/*/index.{md,mdx}'],
+    });
+
+    expect(schemas).toEqual([]);
+  });
+
+  it('loads relative file schema refs without a configured schema source', async () => {
+    const catalogDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-loader-'));
+    const messageDir = path.join(catalogDir, 'events', 'OrderPlaced');
+    const schemaDir = path.join(messageDir, 'schemas');
+
+    await mkdir(schemaDir, { recursive: true });
+    await writeFile(path.join(schemaDir, 'OrderPlaced.schema.json'), '{"type":"object"}');
+    await writeFile(
+      path.join(messageDir, 'index.mdx'),
+      `---
+id: OrderPlaced
+name: Order placed
+version: 1.0.0
+schemas:
+  - ref: file://./schemas/OrderPlaced.schema.json
+---
+`
+    );
+
+    const schemas = await loadMessageSchemas({
+      base: catalogDir,
+      pattern: ['**/events/*/index.{md,mdx}'],
+    });
+
+    expect(schemas).toHaveLength(1);
+    expect(schemas[0]).toMatchObject({
+      id: 'schema:events:OrderPlaced:1.0.0:file://./schemas/OrderPlaced.schema.json',
+      ref: 'file://./schemas/OrderPlaced.schema.json',
+      name: 'OrderPlaced.schema.json',
+      format: 'jsonschema',
+      filePath: path.join(schemaDir, 'OrderPlaced.schema.json'),
+      latest: true,
+      source: {
+        provider: 'file',
+        path: './schemas/OrderPlaced.schema.json',
+      },
+    });
+  });
+
+  it('scopes explicit schema ids to the message version while preserving the user provided id', async () => {
+    const catalogDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-loader-'));
+    const eventDir = path.join(catalogDir, 'events', 'OrderPlaced');
+    const versionedEventDir = path.join(eventDir, 'versioned', '2.0.0');
+
+    await mkdir(eventDir, { recursive: true });
+    await mkdir(versionedEventDir, { recursive: true });
+    await writeFile(path.join(eventDir, 'schema.json'), '{"type":"object","title":"v1"}');
+    await writeFile(path.join(versionedEventDir, 'schema.json'), '{"type":"object","title":"v2"}');
+    await writeFile(
+      path.join(eventDir, 'index.mdx'),
+      `---
+id: OrderPlaced
+name: Order placed
+version: 1.0.0
+schemas:
+  - id: prod
+    file: schema.json
+---
+`
+    );
+    await writeFile(
+      path.join(versionedEventDir, 'index.mdx'),
+      `---
+id: OrderPlaced
+name: Order placed
+version: 2.0.0
+schemas:
+  - id: prod
+    file: schema.json
+---
+`
+    );
+
+    const schemas = await loadMessageSchemas({
+      base: catalogDir,
+      pattern: ['**/events/*/index.{md,mdx}', '**/events/*/versioned/*/index.{md,mdx}'],
+    });
+
+    expect(schemas).toHaveLength(2);
+    expect(schemas.map((schema) => schema.id).sort()).toEqual([
+      'schema:events:OrderPlaced:1.0.0:prod',
+      'schema:events:OrderPlaced:2.0.0:prod',
+    ]);
+    expect(schemas.map((schema) => schema.schemaId)).toEqual(['prod', 'prod']);
+  });
+
+  it('loads absolute file schema refs without a configured schema source', async () => {
+    const catalogDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-loader-'));
+    const externalSchemaDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-registry-'));
+    const messageDir = path.join(catalogDir, 'events', 'OrderPlaced');
+    const schemaPath = path.join(externalSchemaDir, 'OrderPlaced.avsc');
+    const schemaRef = pathToFileURL(schemaPath).toString();
+
+    await mkdir(messageDir, { recursive: true });
+    await writeFile(schemaPath, '{"type":"record"}');
+    await writeFile(
+      path.join(messageDir, 'index.mdx'),
+      `---
+id: OrderPlaced
+name: Order placed
+version: 1.0.0
+schemas:
+  - ref: ${schemaRef}
+---
+`
+    );
+
+    const schemas = await loadMessageSchemas({
+      base: catalogDir,
+      pattern: ['**/events/*/index.{md,mdx}'],
+    });
+
+    expect(schemas).toHaveLength(1);
+    expect(schemas[0]).toMatchObject({
+      id: `schema:events:OrderPlaced:1.0.0:${schemaRef}`,
+      ref: schemaRef,
+      name: 'OrderPlaced.avsc',
+      format: 'avro',
+      filePath: schemaPath,
+      latest: true,
+      source: {
+        provider: 'file',
+        path: schemaPath,
+      },
+    });
+  });
+
+  it('requires EventCatalog Scale when schema sources are configured', async () => {
+    const catalogDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-loader-'));
+    const messageDir = path.join(catalogDir, 'events', 'OrderPlaced');
+
+    await mkdir(messageDir, { recursive: true });
+    await writeFile(
+      path.join(messageDir, 'index.mdx'),
+      `---
+id: OrderPlaced
+name: Order placed
+version: 1.0.0
+schemas:
+  - ref: git://contracts/events/OrderPlaced.schema.json
+---
+`
+    );
+
+    await expect(
+      loadMessageSchemas(
+        {
+          base: catalogDir,
+          pattern: ['**/events/*/index.{md,mdx}'],
+        },
+        [
+          {
+            type: 'schemas',
+            name: 'contracts',
+            canResolve: (id) => id.startsWith('git://contracts/'),
+            resolve: async (id) => ({
+              id,
+              content: '{}',
+              source: {
+                provider: 'git',
+              },
+            }),
+          },
+        ]
+      )
+    ).rejects.toThrow('Schema sources require EventCatalog Scale.');
+  });
+
+  it('loads external schema entries from configured schema sources', async () => {
+    process.env.EVENTCATALOG_SCALE = 'true';
+    const consoleLog = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const catalogDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-loader-'));
+    const messageDir = path.join(catalogDir, 'events', 'OrderPlaced');
+
+    await mkdir(messageDir, { recursive: true });
+    await writeFile(
+      path.join(messageDir, 'index.mdx'),
+      `---
+id: OrderPlaced
+name: Order placed
+version: 1.0.0
+schemas:
+  - ref: git://contracts/events/OrderPlaced.schema.json
+    default: true
+---
+`
+    );
+
+    const schemas = await loadMessageSchemas(
+      {
+        base: catalogDir,
+        pattern: ['**/events/*/index.{md,mdx}'],
+      },
+      [
+        {
+          type: 'schemas',
+          name: 'contracts',
+          canResolve: (id) => id.startsWith('git://contracts/'),
+          resolve: async (id) => ({
+            id,
+            name: 'OrderPlaced.schema.json',
+            format: 'jsonschema',
+            content: '{"type":"object"}',
+            source: {
+              provider: 'git',
+              id: 'contracts:events/OrderPlaced.schema.json',
+              url: 'https://github.com/acme/schema-contracts.git',
+              branch: 'main',
+              path: 'schemas/events/OrderPlaced.schema.json',
+            },
+          }),
+        },
+      ]
+    );
+
+    expect(schemas).toHaveLength(1);
+    expect(schemas[0]).toMatchObject({
+      id: 'schema:events:OrderPlaced:1.0.0:git://contracts/events/OrderPlaced.schema.json',
+      ref: 'git://contracts/events/OrderPlaced.schema.json',
+      name: 'OrderPlaced.schema.json',
+      format: 'jsonschema',
+      content: '{"type":"object"}',
+      default: true,
+      latest: true,
+      readOnly: true,
+      message: {
+        collection: 'events',
+        id: 'OrderPlaced',
+        version: '1.0.0',
+      },
+      source: {
+        provider: 'git',
+        id: 'contracts:events/OrderPlaced.schema.json',
+        url: 'https://github.com/acme/schema-contracts.git',
+        branch: 'main',
+        path: 'schemas/events/OrderPlaced.schema.json',
+      },
+    });
+    expect(consoleLog).toHaveBeenCalledWith(expect.stringContaining('Loading 1 schema from schema source "contracts"'));
+    expect(consoleLog).toHaveBeenCalledWith(expect.stringContaining('Synced 1 schema from schema source "contracts"'));
+    consoleLog.mockRestore();
+  });
+
+  it('uses the schema ref basename when an external schema source does not return a name', async () => {
+    process.env.EVENTCATALOG_SCALE = 'true';
+    const consoleLog = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const catalogDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-loader-'));
+    const messageDir = path.join(catalogDir, 'events', 'OrderPlaced');
+
+    await mkdir(messageDir, { recursive: true });
+    await writeFile(
+      path.join(messageDir, 'index.mdx'),
+      `---
+id: OrderPlaced
+name: Order placed
+version: 1.0.0
+schemas:
+  - ref: git://contracts/events/OrderPlaced.schema.json
+---
+`
+    );
+
+    const schemas = await loadMessageSchemas(
+      {
+        base: catalogDir,
+        pattern: ['**/events/*/index.{md,mdx}'],
+      },
+      [
+        {
+          type: 'schemas',
+          name: 'contracts',
+          canResolve: (id) => id.startsWith('git://contracts/'),
+          resolve: async (id) => ({
+            id,
+            format: 'jsonschema',
+            content: '{"type":"object"}',
+            source: {
+              provider: 'git',
+              id: 'contracts:events/OrderPlaced.schema.json',
+              path: 'schemas/events/OrderPlaced.schema.json',
+            },
+          }),
+        },
+      ]
+    );
+
+    expect(schemas[0]).toMatchObject({
+      name: 'OrderPlaced.schema.json',
+      content: '{"type":"object"}',
+      readOnly: true,
+    });
+    consoleLog.mockRestore();
+  });
+
+  it('keeps distinct collection entries when multiple message versions reference the same external schema', async () => {
+    process.env.EVENTCATALOG_SCALE = 'true';
+    const consoleLog = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const catalogDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-loader-'));
+    const eventDir = path.join(catalogDir, 'events', 'UserCreated');
+    const versionedEventDir = path.join(eventDir, 'versioned', '2.0.0');
+
+    await mkdir(eventDir, { recursive: true });
+    await mkdir(versionedEventDir, { recursive: true });
+    await writeFile(
+      path.join(eventDir, 'index.mdx'),
+      `---
+id: UserCreated
+name: User created
+version: 1.0.0
+schemas:
+  - ref: git://contracts/common/User.schema.json
+---
+`
+    );
+    await writeFile(
+      path.join(versionedEventDir, 'index.mdx'),
+      `---
+id: UserCreated
+name: User created
+version: 2.0.0
+schemas:
+  - ref: git://contracts/common/User.schema.json
+---
+`
+    );
+
+    const resolve = vi.fn(async (id: string) => ({
+      id,
+      name: 'User.schema.json',
+      format: 'jsonschema',
+      content: '{"type":"object"}',
+      source: {
+        provider: 'git',
+        path: 'common/User.schema.json',
+      },
+    }));
+
+    const schemas = await loadMessageSchemas(
+      {
+        base: catalogDir,
+        pattern: ['**/events/*/index.{md,mdx}', '**/events/*/versioned/*/index.{md,mdx}'],
+      },
+      [
+        {
+          type: 'schemas',
+          name: 'contracts',
+          canResolve: (id) => id.startsWith('git://contracts/'),
+          resolve,
+        },
+      ]
+    );
+
+    expect(schemas).toHaveLength(2);
+    expect(schemas.map((schema) => schema.id).sort()).toEqual([
+      'schema:events:UserCreated:1.0.0:git://contracts/common/User.schema.json',
+      'schema:events:UserCreated:2.0.0:git://contracts/common/User.schema.json',
+    ]);
+    expect(schemas.map((schema) => schema.ref)).toEqual([
+      'git://contracts/common/User.schema.json',
+      'git://contracts/common/User.schema.json',
+    ]);
+    expect(schemas.map((schema) => schema.message.version).sort()).toEqual(['1.0.0', '2.0.0']);
+    expect(resolve).toHaveBeenCalledTimes(2);
+    expect(resolve).toHaveBeenNthCalledWith(
+      1,
+      'git://contracts/common/User.schema.json',
+      expect.objectContaining({ messageFilePath: expect.stringContaining('index.mdx') })
+    );
+    consoleLog.mockRestore();
+  });
+
+  it('passes the referencing message file path to configured schema sources', async () => {
+    process.env.EVENTCATALOG_SCALE = 'true';
+    const consoleLog = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const catalogDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-loader-'));
+    const messageDir = path.join(catalogDir, 'events', 'OrderPlaced');
+    const messageFilePath = path.join(messageDir, 'index.mdx');
+    const resolve = vi.fn(async (id: string) => ({
+      id,
+      content: '{}',
+      source: {
+        provider: 'git',
+      },
+    }));
+
+    await mkdir(messageDir, { recursive: true });
+    await writeFile(
+      messageFilePath,
+      `---
+id: OrderPlaced
+name: Order placed
+version: 1.0.0
+schemas:
+  - ref: git://contracts/events/OrderPlaced.schema.json
+---
+`
+    );
+
+    const schemas = await loadMessageSchemas(
+      {
+        base: catalogDir,
+        pattern: ['**/events/*/index.{md,mdx}'],
+      },
+      [
+        {
+          type: 'schemas',
+          name: 'contracts',
+          canResolve: (id) => id.startsWith('git://contracts/'),
+          resolve,
+        },
+      ]
+    );
+
+    expect(resolve).toHaveBeenCalledWith('git://contracts/events/OrderPlaced.schema.json', { messageFilePath });
+    expect(schemas[0]).not.toHaveProperty('_context');
+    consoleLog.mockRestore();
+  });
+
+  it('reports the message that referenced an external schema when the source cannot resolve it', async () => {
+    process.env.EVENTCATALOG_SCALE = 'true';
+    const consoleLog = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const catalogDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-loader-'));
+    const messageDir = path.join(catalogDir, 'events', 'DeliveryFailed');
+
+    await mkdir(messageDir, { recursive: true });
+    await writeFile(
+      path.join(messageDir, 'index.mdx'),
+      `---
+id: DeliveryFailed
+name: Delivery failed
+version: 1.0.0
+schemas:
+  - ref: git://contracts/events/Missing.schema.json
+---
+`
+    );
+
+    try {
+      await loadMessageSchemas(
+        {
+          base: catalogDir,
+          pattern: ['**/events/*/index.{md,mdx}'],
+        },
+        [
+          {
+            type: 'schemas',
+            name: 'contracts',
+            canResolve: (id) => id.startsWith('git://contracts/'),
+            resolve: async () => {
+              throw new Error(
+                'Git schema source "contracts" could not find schema file "schemas/events/Missing.schema.json" in "https://github.com/acme/schema-contracts.git" on branch "main".'
+              );
+            },
+          },
+        ]
+      );
+      throw new Error('Expected schema loading to fail.');
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+      const message = (error as Error).message;
+      expect(message).toContain('[schemas] Failed to resolve schema');
+      expect(message).toContain('Message: event "DeliveryFailed" version "1.0.0"');
+      expect(message).toContain('Schema:  git://contracts/events/Missing.schema.json');
+      expect(message).toContain('Source:  contracts');
+      expect(message).toContain('Reason:');
+      expect(message).toContain(
+        'Git schema source "contracts" could not find schema file "schemas/events/Missing.schema.json" in "https://github.com/acme/schema-contracts.git" on branch "main".'
+      );
+    } finally {
+      consoleLog.mockRestore();
+    }
+  });
+
+  it('marks schemas for the latest message version using semver ordering', async () => {
+    const catalogDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-schema-loader-'));
+    const eventDir = path.join(catalogDir, 'events', 'OrderPlaced');
+    const versionedEventDir = path.join(eventDir, 'versioned', '1.10.0');
+
+    await mkdir(eventDir, { recursive: true });
+    await mkdir(versionedEventDir, { recursive: true });
+    await writeFile(path.join(eventDir, 'schema.json'), '{"type":"object","version":"1.9.0"}');
+    await writeFile(path.join(versionedEventDir, 'schema.json'), '{"type":"object","version":"1.10.0"}');
+    await writeFile(
+      path.join(eventDir, 'index.mdx'),
+      `---
+id: OrderPlaced
+name: Order placed
+version: 1.9.0
+schemaPath: schema.json
+---
+`
+    );
+    await writeFile(
+      path.join(versionedEventDir, 'index.mdx'),
+      `---
+id: OrderPlaced
+name: Order placed
+version: 1.10.0
+schemaPath: schema.json
+---
+`
+    );
+
+    const schemas = await loadMessageSchemas({
+      base: catalogDir,
+      pattern: ['**/events/*/index.{md,mdx}', '**/events/*/versioned/*/index.{md,mdx}'],
+    });
+
+    expect(schemas).toHaveLength(2);
+    expect(schemas.find((schema) => schema.message.version === '1.9.0')).toMatchObject({ latest: false });
+    expect(schemas.find((schema) => schema.message.version === '1.10.0')).toMatchObject({ latest: true });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/schemas/schemas.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/schemas/schemas.spec.ts
new file mode 100644
index 000000000..e861da150
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/schemas/schemas.spec.ts
@@ -0,0 +1,152 @@
+import { getSchemasFromResource } from '@utils/collections/schemas';
+
+import { getSchemaURL, getSchemaFormatFromURL } from '@utils/collections/schemas';
+
+describe('schemas', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    // Reset the environment before each test
+    // @ts-ignore
+    global.__EC_TRAILING_SLASH__ = false;
+    process.env = { ...originalEnv };
+  });
+
+  describe('getSchemaURL', () => {
+    it('returns the schema URL for a given resource', () => {
+      // @ts-ignore - partial mock
+      const schemaURL = getSchemaURL({
+        collection: 'services',
+        data: {
+          id: 'MyService',
+          version: '1.0.0',
+          name: 'MyService',
+          schemaPath: 'schemas/service',
+        },
+        filePath: '/some/path/to/MyService/index.mdx',
+      });
+      expect(schemaURL).toEqual('/generated/services/MyService/schemas/service');
+    });
+  });
+
+  describe('getSchemaFormatFromURL', () => {
+    it('returns the format of a given schema URL', () => {
+      const format = getSchemaFormatFromURL('random-url.com/schemas/service.json');
+      expect(format).toEqual('json');
+    });
+  });
+
+  describe('getSchemasFromResource', () => {
+    describe('services', () => {
+      it('returns an openapi, and asyncapi schema if both are present', () => {
+        // @ts-ignore - partial mock
+        const schemas = getSchemasFromResource({
+          collection: 'services',
+          data: {
+            id: 'MyService',
+            version: '1.0.0',
+            name: 'MyService',
+            schemaPath: 'schemas/service',
+            specifications: {
+              asyncapiPath: 'schemas/service.asyncapi.json',
+              openapiPath: 'schemas/service.openapi.json',
+            },
+          },
+          // @ts-ignore
+          filePath: '/some/path/to/MyService/index.mdx',
+        });
+        expect(schemas).toEqual([
+          { url: '/generated/services/MyService/schemas/service.asyncapi.json', format: 'asyncapi' },
+          { url: '/generated/services/MyService/schemas/service.openapi.json', format: 'openapi' },
+        ]);
+      });
+
+      it('returns an asyncapi schema if only asyncapi is present', () => {
+        // @ts-ignore - partial mock
+        const schemas = getSchemasFromResource({
+          collection: 'services',
+          data: {
+            id: 'MyService',
+            version: '1.0.0',
+            name: 'MyService',
+            schemaPath: 'schemas/service',
+            specifications: {
+              asyncapiPath: 'schemas/service.asyncapi.json',
+            },
+          },
+          // @ts-ignore
+          filePath: '/some/path/to/MyService/index.mdx',
+        });
+        expect(schemas).toEqual([{ url: '/generated/services/MyService/schemas/service.asyncapi.json', format: 'asyncapi' }]);
+      });
+
+      it('returns an openapi schema if only openapi is present', () => {
+        // @ts-ignore - partial mock
+        const schemas = getSchemasFromResource({
+          collection: 'services',
+          data: {
+            id: 'MyService',
+            version: '1.0.0',
+            name: 'MyService',
+            schemaPath: 'schemas/service',
+            specifications: {
+              openapiPath: 'schemas/service.openapi.json',
+            },
+          },
+          // @ts-ignore
+          filePath: '/some/path/to/MyService/index.mdx',
+        });
+        expect(schemas).toEqual([{ url: '/generated/services/MyService/schemas/service.openapi.json', format: 'openapi' }]);
+      });
+
+      it('returns an empty array if no schemas are present', () => {
+        // @ts-ignore - partial mock
+        const schemas = getSchemasFromResource({
+          collection: 'services',
+          data: {
+            id: 'MyService',
+            version: '1.0.0',
+            name: 'MyService',
+            schemaPath: 'schemas/service',
+          },
+          // @ts-ignore
+          filePath: '/some/path/to/MyService/index.mdx',
+        });
+        expect(schemas).toEqual([]);
+      });
+    });
+
+    describe('all resources (excluding services)', () => {
+      it('returns a single schema if only one is present', () => {
+        // @ts-ignore - partial mock
+        const schemas = getSchemasFromResource({
+          collection: 'events',
+          data: {
+            id: 'MyEvent',
+            version: '1.0.0',
+            name: 'MyEvent',
+            schemaPath: 'schemas/event.json',
+          },
+          // @ts-ignore
+          filePath: '/some/path/to/MyEvent/index.mdx',
+        });
+        expect(schemas).toEqual([{ url: '/generated/events/MyEvent/schemas/event.json', format: 'json' }]);
+      });
+
+      it('returns an empty array if no schemas are present', () => {
+        // @ts-ignore - partial mock
+        const schemas = getSchemasFromResource({
+          collection: 'events',
+          data: {
+            id: 'MyEvent',
+            version: '1.0.0',
+            name: 'MyEvent',
+          },
+          // @ts-ignore
+          filePath: '/some/path/to/MyEvent/index.mdx',
+        });
+        expect(schemas).toEqual([]);
+      });
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/services/mocks.ts b/packages/core/eventcatalog/src/utils/__tests__/services/mocks.ts
new file mode 100644
index 000000000..f6e24dada
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/services/mocks.ts
@@ -0,0 +1,474 @@
+export const mockServices = [
+  {
+    id: 'services/Order/OrderService/index.mdx',
+    slug: 'services/Order/OrderService',
+    collection: 'services',
+    data: {
+      id: 'OrderService',
+      version: '1.0.0',
+      specifications: [
+        {
+          type: 'asyncapi',
+          path: 'asyncapi.yml',
+          name: 'AsyncAPI Custom Name',
+        },
+        {
+          type: 'openapi',
+          path: 'openapi.yml',
+          name: 'OpenAPI Custom Name',
+        },
+      ],
+      sends: [
+        {
+          id: 'OrderCreatedEvent',
+          version: '0.0.1',
+        },
+      ],
+      receives: [
+        {
+          id: 'PaymentProcessed',
+          version: '0.0.1',
+        },
+      ],
+      writesTo: [
+        {
+          id: 'OrderDatabase',
+          version: '1.0.0',
+        },
+      ],
+      readsFrom: [
+        {
+          id: 'PaymentDatabase',
+          version: '1.0.0',
+        },
+      ],
+    },
+  },
+  {
+    id: 'services/Inventory/InventoryService/index.mdx',
+    slug: 'services/Inventory/InventoryService',
+    collection: 'services',
+    data: {
+      id: 'InventoryService',
+      version: '1.0.0',
+      specifications: {
+        asyncapiPath: 'asyncapi.yml',
+        openapiPath: 'openapi.yml',
+      },
+      receives: [
+        {
+          id: 'OrderCreatedEvent',
+          version: '^1.3.0',
+        },
+      ],
+      sends: [
+        {
+          id: 'InventoryAdjusted',
+          version: '~2',
+        },
+      ],
+    },
+  },
+  {
+    id: 'services/Payment/PaymentService/index.mdx',
+    slug: 'services/Payment/PaymentService',
+    collection: 'services',
+    data: {
+      id: 'PaymentService',
+      version: '1.0.0',
+      receives: [
+        {
+          id: 'OrderCreatedEvent',
+        },
+        {
+          id: 'OrderDeletedEvent',
+          from: [
+            {
+              id: 'EmailChannel',
+              version: '1.0.0',
+            },
+          ],
+        },
+      ],
+      sends: [
+        {
+          id: 'PaymentPaid',
+          to: [
+            {
+              id: 'EmailChannel',
+              version: '1.0.0',
+            },
+          ],
+        },
+        {
+          id: 'PaymentFailed',
+          version: 'latest',
+        },
+        {
+          id: 'EmailVerified',
+          version: '1.0.0',
+        },
+      ],
+    },
+  },
+  {
+    id: 'services/Notifications/NotificationsService/index.mdx',
+    slug: 'services/Notifications/NotificationsService',
+    collection: 'services',
+    data: {
+      id: 'NotificationsService',
+      version: '1.0.0',
+      receives: [
+        {
+          id: 'OrderCreatedEvent',
+        },
+      ],
+      sends: [
+        {
+          id: 'OrderCreatedEvent',
+        },
+      ],
+    },
+  },
+];
+
+export const mockAgents = [
+  {
+    id: 'agents/Support/OrderSupportAgent/index.mdx',
+    slug: 'agents/Support/OrderSupportAgent',
+    collection: 'agents',
+    data: {
+      id: 'OrderSupportAgent',
+      version: '1.0.0',
+      name: 'Order Support Agent',
+      model: {
+        provider: 'OpenAI',
+        name: 'gpt-4.1-mini',
+        version: '2025-04-14',
+      },
+      tools: [
+        {
+          name: 'Order history lookup',
+          type: 'mcp',
+          icon: '/icons/tools/snowflake.svg',
+          url: 'https://mcp.example.com/orders/history',
+          description: 'Retrieves the customer order timeline for support investigations.',
+        },
+      ],
+      sends: [
+        {
+          id: 'OrderCreatedEvent',
+          version: '0.0.1',
+        },
+      ],
+      receives: [
+        {
+          id: 'PaymentProcessed',
+          version: '0.0.1',
+        },
+      ],
+      writesTo: [
+        {
+          id: 'OrderDatabase',
+          version: '1.0.0',
+        },
+      ],
+      readsFrom: [
+        {
+          id: 'PaymentDatabase',
+          version: '1.0.0',
+        },
+      ],
+    },
+  },
+];
+
+export const mockEvents = [
+  {
+    slug: 'OrderCreatedEvent',
+    collection: 'events',
+    data: {
+      id: 'OrderCreatedEvent',
+      version: '0.0.1',
+    },
+  },
+  {
+    slug: 'OrderCreatedEvent',
+    collection: 'events',
+    data: {
+      id: 'OrderCreatedEvent',
+      version: '1.0.0',
+    },
+  },
+  {
+    slug: 'OrderCreatedEvent',
+    collection: 'events',
+    data: {
+      id: 'OrderCreatedEvent',
+      version: '1.3.9',
+    },
+  },
+  {
+    slug: 'OrderCreatedEvent',
+    collection: 'events',
+    data: {
+      id: 'OrderCreatedEvent',
+      version: '2.0.0',
+    },
+  },
+  {
+    slug: 'OrderDeletedEvent',
+    collection: 'events',
+    data: {
+      id: 'OrderDeletedEvent',
+      version: '2.0.0',
+      channels: [
+        {
+          id: 'OrderChannel',
+          version: '1.0.0',
+        },
+      ],
+    },
+  },
+  {
+    slug: 'InventoryAdjusted',
+    collection: 'events',
+    data: {
+      id: 'InventoryAdjusted',
+      version: '0.0.1',
+    },
+  },
+  {
+    slug: 'InventoryAdjusted',
+    collection: 'events',
+    data: {
+      id: 'InventoryAdjusted',
+      version: '1.0.0',
+    },
+  },
+  {
+    slug: 'InventoryAdjusted',
+    collection: 'events',
+    data: {
+      id: 'InventoryAdjusted',
+      version: '2.0.0',
+    },
+  },
+  // 7
+  {
+    slug: 'PaymentPaid',
+    collection: 'events',
+    data: {
+      id: 'PaymentPaid',
+      version: '1.0.0',
+    },
+  },
+  // 9
+  {
+    slug: 'PaymentPaid',
+    collection: 'events',
+    data: {
+      id: 'PaymentPaid',
+      version: '2.0.0',
+    },
+  },
+  // 10
+  {
+    slug: 'PaymentFailed',
+    collection: 'events',
+    data: {
+      id: 'PaymentFailed',
+      version: '1.0.0',
+    },
+  },
+  // 11
+  {
+    slug: 'PaymentFailed',
+    collection: 'events',
+    data: {
+      id: 'PaymentFailed',
+      version: '1.2.3',
+    },
+  },
+  // 12
+  {
+    id: 'EmailVerified',
+    slug: 'EmailVerified',
+    collection: 'events',
+    data: {
+      id: 'EmailVerified',
+      version: '1.0.0',
+      channels: [
+        {
+          id: 'EmailChannel',
+          version: '1.0.0',
+        },
+      ],
+    },
+  },
+];
+
+export const mockCommands = [
+  {
+    slug: 'PaymentProcessed',
+    collection: 'commands',
+    data: {
+      id: 'PaymentProcessed',
+      version: '0.0.1',
+    },
+  },
+];
+export const mockQueries = [
+  {
+    slug: 'GetOrder',
+    collection: 'queries',
+    data: {
+      id: 'GetOrder',
+      version: '0.0.1',
+    },
+  },
+];
+
+export const mockContainers = [
+  {
+    id: 'OrderDatabase',
+    collection: 'containers',
+    data: {
+      id: 'OrderDatabase',
+      version: '1.0.0',
+    },
+  },
+  {
+    id: 'PaymentDatabase',
+    collection: 'containers',
+    data: {
+      id: 'PaymentDatabase',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockChannels = [
+  {
+    id: 'EmailChannel',
+    slug: 'EmailChannel',
+    collection: 'channels',
+    data: {
+      id: 'EmailChannel',
+      version: '1.0.0',
+      messages: [
+        {
+          id: 'OrderCreatedEvent',
+          version: '0.0.1',
+        },
+      ],
+    },
+  },
+  {
+    id: 'OrderChannel',
+    slug: 'OrderChannel',
+    collection: 'channels',
+    data: {
+      id: 'OrderChannel',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockGroupedService = {
+  id: 'services/Student/StudentInfoService/index.mdx',
+  slug: 'services/Student/StudentInfoService',
+  collection: 'services',
+  data: {
+    id: 'StudentInfoService',
+    version: '1.0.0',
+    sends: [
+      { id: 'ProgramCreated', version: '1.0.0', group: 'Academic Structure' },
+      { id: 'ProgramUpdated', version: '1.0.0', group: 'Academic Structure' },
+      { id: 'StudentEnrolled', version: '1.0.0', group: 'Student Lifecycle' },
+      { id: 'GradeRecorded', version: '1.0.0' },
+    ],
+    receives: [
+      { id: 'EnrolmentRequested', version: '1.0.0', group: 'Student Lifecycle' },
+      { id: 'PaymentProcessed', version: '0.0.1' },
+    ],
+  },
+};
+
+export const mockGroupedEvents = [
+  { data: { id: 'ProgramCreated', version: '1.0.0', name: 'ProgramCreated' }, collection: 'events' },
+  { data: { id: 'ProgramUpdated', version: '1.0.0', name: 'ProgramUpdated' }, collection: 'events' },
+  { data: { id: 'StudentEnrolled', version: '1.0.0', name: 'StudentEnrolled' }, collection: 'events' },
+  { data: { id: 'GradeRecorded', version: '1.0.0', name: 'GradeRecorded' }, collection: 'events' },
+];
+
+export const mockGroupedCommands = [
+  { data: { id: 'EnrolmentRequested', version: '1.0.0', name: 'EnrolmentRequested' }, collection: 'commands' },
+];
+
+// Service with grouped messages that have channel routing (for downstream expansion tests)
+export const mockGroupedServiceWithChannels = {
+  id: 'services/Warehouse/WarehouseService/index.mdx',
+  slug: 'services/Warehouse/WarehouseService',
+  collection: 'services',
+  data: {
+    id: 'WarehouseService',
+    version: '1.0.0',
+    sends: [
+      { id: 'ShipmentDispatched', version: '1.0.0', group: 'Shipping', to: [{ id: 'ShippingChannel', version: '1.0.0' }] },
+      { id: 'ShipmentFailed', version: '1.0.0', group: 'Shipping' },
+    ],
+    receives: [
+      { id: 'PickRequested', version: '1.0.0', group: 'Picking', from: [{ id: 'PickChannel', version: '1.0.0' }] },
+      { id: 'PickCancelled', version: '1.0.0', group: 'Picking' },
+    ],
+  },
+};
+
+export const mockGroupedChannelEvents = [
+  { data: { id: 'ShipmentDispatched', version: '1.0.0', name: 'ShipmentDispatched' }, collection: 'events' },
+  { data: { id: 'ShipmentFailed', version: '1.0.0', name: 'ShipmentFailed' }, collection: 'events' },
+  { data: { id: 'PickRequested', version: '1.0.0', name: 'PickRequested' }, collection: 'commands' },
+  { data: { id: 'PickCancelled', version: '1.0.0', name: 'PickCancelled' }, collection: 'commands' },
+];
+
+export const mockGroupedChannels = [
+  {
+    id: 'ShippingChannel',
+    slug: 'ShippingChannel',
+    collection: 'channels',
+    data: { id: 'ShippingChannel', version: '1.0.0' },
+  },
+  {
+    id: 'PickChannel',
+    slug: 'PickChannel',
+    collection: 'channels',
+    data: { id: 'PickChannel', version: '1.0.0' },
+  },
+];
+
+// A consumer of ShipmentDispatched (for testing downstream consumer nodes)
+export const mockShipmentConsumerService = {
+  id: 'services/Delivery/DeliveryService/index.mdx',
+  slug: 'services/Delivery/DeliveryService',
+  collection: 'services',
+  data: {
+    id: 'DeliveryService',
+    version: '1.0.0',
+    receives: [{ id: 'ShipmentDispatched', version: '1.0.0' }],
+    sends: [],
+  },
+};
+
+// A producer of PickRequested (for testing upstream producer nodes)
+export const mockPickProducerService = {
+  id: 'services/WMS/WMSService/index.mdx',
+  slug: 'services/WMS/WMSService',
+  collection: 'services',
+  data: {
+    id: 'WMSService',
+    version: '1.0.0',
+    sends: [{ id: 'PickRequested', version: '1.0.0' }],
+    receives: [],
+  },
+};
diff --git a/packages/core/eventcatalog/src/utils/__tests__/services/node-graph.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/services/node-graph.spec.ts
new file mode 100644
index 000000000..127900aa6
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/services/node-graph.spec.ts
@@ -0,0 +1,706 @@
+import { MarkerType } from '@xyflow/react';
+import { getNodesAndEdges } from '../../node-graphs/services-node-graph';
+import { expect, describe, it, vi, beforeEach } from 'vitest';
+import {
+  mockCommands,
+  mockEvents,
+  mockQueries,
+  mockServices,
+  mockChannels,
+  mockContainers,
+  mockGroupedService,
+  mockGroupedEvents,
+  mockGroupedCommands,
+  mockGroupedServiceWithChannels,
+  mockGroupedChannelEvents,
+  mockGroupedChannels,
+  mockShipmentConsumerService,
+  mockPickProducerService,
+} from './mocks';
+import type { CollectionKey } from 'astro:content';
+import { getCollection } from 'astro:content';
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: vi.fn(),
+  };
+});
+
+describe('Services NodeGraph', () => {
+  beforeEach(() => {
+    vi.mocked(getCollection).mockImplementation(((key: CollectionKey) => {
+      switch (key) {
+        case 'services':
+          return Promise.resolve(mockServices);
+        case 'channels':
+          return Promise.resolve(mockChannels);
+        case 'events':
+          return Promise.resolve(mockEvents);
+        case 'commands':
+          return Promise.resolve(mockCommands);
+        case 'queries':
+          return Promise.resolve(mockQueries);
+        case 'containers':
+          return Promise.resolve(mockContainers);
+        default:
+          return Promise.resolve([]);
+      }
+    }) as any);
+  });
+
+  describe('getNodesAndEdges', () => {
+    it('should return nodes and edges for a given service', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'OrderService', version: '1.0.0' });
+
+      // The middle node itself, the service
+      const expectedServiceNode = {
+        id: 'OrderService-1.0.0',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[0].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      // Nodes coming into the service (left)
+      const expectedRecivesNode = {
+        id: 'PaymentProcessed-0.0.1',
+        type: 'commands',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', message: { ...mockCommands[0].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      // Nodes going out of the service (right)
+      const expectedSendsNode = {
+        id: 'OrderCreatedEvent-0.0.1',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', message: { ...mockEvents[0].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'events',
+      };
+
+      const expectedOrderDatabaseNode = {
+        id: 'OrderDatabase-1.0.0',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', data: { ...mockContainers[0].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'data',
+      };
+
+      const expectedPaymentDatabaseNode = {
+        id: 'PaymentDatabase-1.0.0',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', data: { ...mockContainers[1].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'data',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        expect.objectContaining({
+          label: 'accepts',
+          animated: false,
+          id: 'PaymentProcessed-0.0.1-OrderService-1.0.0-warning',
+          source: 'PaymentProcessed-0.0.1',
+          target: 'OrderService-1.0.0',
+        }),
+        expect.objectContaining({
+          id: 'OrderService-1.0.0-OrderDatabase-1.0.0',
+          source: 'OrderService-1.0.0',
+          target: 'OrderDatabase-1.0.0',
+          type: 'multiline',
+        }),
+        expect.objectContaining({
+          label: 'reads from \n (undefined)',
+          id: 'OrderService-1.0.0-PaymentDatabase-1.0.0',
+          source: 'PaymentDatabase-1.0.0',
+          target: 'OrderService-1.0.0',
+          type: 'multiline',
+        }),
+        expect.objectContaining({
+          label: 'publishes \nevent',
+          animated: false,
+          id: 'OrderService-1.0.0-OrderCreatedEvent-0.0.1',
+          source: 'OrderService-1.0.0',
+          target: 'OrderCreatedEvent-0.0.1',
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedRecivesNode),
+
+          // The data node
+          expect.objectContaining(expectedOrderDatabaseNode),
+          expect.objectContaining(expectedPaymentDatabaseNode),
+
+          // The service node itself
+          expect.objectContaining(expectedServiceNode),
+
+          // Nodes on the right
+          expect.objectContaining(expectedSendsNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('if a message is sent and received by the same service it will render a custom edge', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'NotificationsService', version: '1.0.0' });
+
+      // The middle node itself, the service
+      const expectedServiceNode = {
+        id: 'NotificationsService-1.0.0',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[3].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      // Nodes coming into the service (left)
+      const expectedRecivesNode = {
+        id: 'OrderCreatedEvent-2.0.0',
+        type: 'events',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', message: { ...mockEvents[3].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      // Nodes going out of the service (right)
+      const expectedSendsNode = {
+        id: 'OrderCreatedEvent-2.0.0',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', message: { ...mockEvents[3].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'events',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        expect.objectContaining({
+          id: 'OrderCreatedEvent-2.0.0-NotificationsService-1.0.0',
+          source: 'OrderCreatedEvent-2.0.0',
+          target: 'NotificationsService-1.0.0',
+        }),
+        expect.objectContaining({
+          id: 'NotificationsService-1.0.0-OrderCreatedEvent-2.0.0',
+          source: 'NotificationsService-1.0.0',
+          target: 'OrderCreatedEvent-2.0.0',
+        }),
+        expect.objectContaining({
+          id: 'NotificationsService-1.0.0-OrderCreatedEvent-2.0.0-both',
+          source: 'NotificationsService-1.0.0',
+          target: 'OrderCreatedEvent-2.0.0',
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedRecivesNode),
+
+          // The service node itself
+          expect.objectContaining(expectedServiceNode),
+
+          // Nodes on the right
+          expect.objectContaining(expectedSendsNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('returns empty nodes and edges if no service is found', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownService', version: '1.0.0' });
+
+      expect(nodes).toEqual([]);
+      expect(edges).toEqual([]);
+    });
+
+    it('should return nodes and edges for a given service using semver range', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'InventoryService', version: '1.0.0' });
+
+      // The middle node itself, the service
+      const expectedServiceNode = {
+        id: 'InventoryService-1.0.0',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[1].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      // Nodes coming into the service (left)
+      const expectedRecivesNode = {
+        id: 'OrderCreatedEvent-1.3.9',
+        type: 'events',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', message: { ...mockEvents[2].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      // Nodes going out of the service (right)
+      const expectedSendsNode = {
+        id: 'InventoryAdjusted-2.0.0',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', message: { ...mockEvents[7].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'events',
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        expect.objectContaining({
+          id: 'OrderCreatedEvent-1.3.9-InventoryService-1.0.0',
+          source: 'OrderCreatedEvent-1.3.9',
+          target: 'InventoryService-1.0.0',
+        }),
+        expect.objectContaining({
+          id: 'InventoryService-1.0.0-InventoryAdjusted-2.0.0',
+          source: 'InventoryService-1.0.0',
+          target: 'InventoryAdjusted-2.0.0',
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // Nodes on the left
+          expect.objectContaining(expectedRecivesNode),
+
+          // The service node itself
+          expect.objectContaining(expectedServiceNode),
+
+          // Nodes on the right
+          expect.objectContaining(expectedSendsNode),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('creates a channel node between the service and message if the service defined a channel', async () => {
+      const { nodes, edges } = await getNodesAndEdges({ id: 'PaymentService', version: '1.0.0' });
+
+      // The middle node itself, the service
+      const expectedServiceNode = {
+        id: 'PaymentService-1.0.0',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: { ...mockServices[2].data } }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+        type: 'services',
+      };
+
+      const expectedConsumedMessageWithoutChannel = {
+        id: 'OrderCreatedEvent-2.0.0',
+        type: 'events',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', message: expect.anything() }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedConsumedMessageWithChannel = {
+        id: 'OrderDeletedEvent-2.0.0',
+        type: 'events',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', message: expect.anything() }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedChannelNode = {
+        id: 'EmailChannel-1.0.0',
+        type: 'channels',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', channel: expect.anything() }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      // Message coming into the service with a channel
+      const expectedProducedMessage = {
+        id: 'PaymentPaid-2.0.0',
+        type: 'events',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', message: expect.anything() }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      // Message coming into the service with a channel
+      const expectedChannelAfterProducedMessage = {
+        id: 'EmailChannel-1.0.0',
+        type: 'channels',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', channel: expect.anything() }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedEdges = expect.arrayContaining([
+        // The service to the message (it publishes)
+        expect.objectContaining({
+          id: 'PaymentService-1.0.0-PaymentPaid-2.0.0',
+          source: 'PaymentService-1.0.0',
+          target: 'PaymentPaid-2.0.0',
+        }),
+        // The Message to the channel defined by the producing service
+        expect.objectContaining({
+          id: 'PaymentPaid-2.0.0-EmailChannel-1.0.0',
+          source: 'PaymentPaid-2.0.0',
+          target: 'EmailChannel-1.0.0',
+        }),
+
+        // The consumed message with no channel defined
+        // We expect to to connect to the service
+        expect.objectContaining({
+          id: 'OrderCreatedEvent-2.0.0-PaymentService-1.0.0',
+          source: 'OrderCreatedEvent-2.0.0',
+          target: 'PaymentService-1.0.0',
+        }),
+
+        // The consume message with a channel defined
+        expect.objectContaining({
+          id: 'OrderDeletedEvent-2.0.0-EmailChannel-1.0.0',
+          source: 'OrderDeletedEvent-2.0.0',
+          target: 'EmailChannel-1.0.0',
+        }),
+      ]);
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          // message the service consumes
+          expect.objectContaining(expectedConsumedMessageWithoutChannel),
+
+          // message the service consumes with a channel
+          expect.objectContaining(expectedConsumedMessageWithChannel),
+
+          // The channel node
+          expect.objectContaining(expectedChannelNode),
+
+          // The service node itself
+          expect.objectContaining(expectedServiceNode),
+
+          // message on the right of the service
+          expect.objectContaining(expectedProducedMessage),
+
+          expect.objectContaining(expectedChannelAfterProducedMessage),
+        ])
+      );
+
+      expect(edges).toEqual(expectedEdges);
+    });
+
+    it('when `renderMessages` is false it should not render any messages or channels', async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'PaymentService', version: '1.0.0', renderMessages: false });
+
+      const hasMessages = nodes.some((node) => node.type === 'events' || node.type === 'commands' || node.type === 'queries');
+      const hasChannels = nodes.some((node) => node.type === 'channels');
+
+      expect(hasMessages).toBe(false);
+      expect(hasChannels).toBe(false);
+    });
+
+    it('will render any container (data) that the service writes to or reads from', async () => {
+      const { nodes } = await getNodesAndEdges({ id: 'OrderService', version: '1.0.0' });
+
+      const hasContainers = nodes.some((node) => node.type === 'data');
+      expect(hasContainers).toBe(true);
+    });
+
+    describe('message grouping', () => {
+      it('should collapse grouped sends into messageGroup nodes', async () => {
+        vi.mocked(getCollection).mockImplementation(((key: any) => {
+          switch (key) {
+            case 'services':
+              return Promise.resolve([mockGroupedService]);
+            case 'events':
+              return Promise.resolve([...mockGroupedEvents]);
+            case 'commands':
+              return Promise.resolve([...mockGroupedCommands]);
+            default:
+              return Promise.resolve([]);
+          }
+        }) as any);
+
+        const { nodes } = await getNodesAndEdges({ id: 'StudentInfoService', version: '1.0.0' });
+
+        const groupNodes = nodes.filter((n: any) => n.type === 'messageGroup');
+        expect(groupNodes).toHaveLength(3); // 'Academic Structure' sends, 'Student Lifecycle' sends, 'Student Lifecycle' receives
+
+        const academicGroup = groupNodes.find((n: any) => n.data.groupName === 'Academic Structure');
+        expect(academicGroup).toBeDefined();
+        expect(academicGroup.data.messageCount).toBe(2);
+        expect(academicGroup.data.direction).toBe('sends');
+
+        // GradeRecorded should still be an individual event node (ungrouped)
+        const gradeNode = nodes.find((n: any) => n.id === 'GradeRecorded-1.0.0');
+        expect(gradeNode).toBeDefined();
+        expect(gradeNode.type).toBe('events');
+      });
+
+      it('should create edges from service to group nodes', async () => {
+        vi.mocked(getCollection).mockImplementation(((key: any) => {
+          switch (key) {
+            case 'services':
+              return Promise.resolve([mockGroupedService]);
+            case 'events':
+              return Promise.resolve([...mockGroupedEvents]);
+            case 'commands':
+              return Promise.resolve([...mockGroupedCommands]);
+            default:
+              return Promise.resolve([]);
+          }
+        }) as any);
+
+        const { edges } = await getNodesAndEdges({ id: 'StudentInfoService', version: '1.0.0' });
+
+        const serviceId = 'StudentInfoService-1.0.0';
+        const groupEdges = edges.filter(
+          (e: any) =>
+            (e.source === serviceId || e.target === serviceId) &&
+            (e.source.startsWith('message-group-') || e.target.startsWith('message-group-'))
+        );
+        expect(groupEdges.length).toBeGreaterThanOrEqual(2);
+      });
+
+      it('should skip bothSentAndReceived edge for grouped messages', async () => {
+        const bothWayService = {
+          ...mockGroupedService,
+          data: {
+            ...mockGroupedService.data,
+            id: 'BothWayService',
+            version: '1.0.0',
+            sends: [{ id: 'SharedEvent', version: '1.0.0', group: 'Shared' }],
+            receives: [{ id: 'SharedEvent', version: '1.0.0', group: 'Shared' }],
+          },
+        };
+        const sharedEvent = { data: { id: 'SharedEvent', version: '1.0.0', name: 'SharedEvent' }, collection: 'events' };
+
+        vi.mocked(getCollection).mockImplementation(((key: any) => {
+          switch (key) {
+            case 'services':
+              return Promise.resolve([bothWayService]);
+            case 'events':
+              return Promise.resolve([sharedEvent]);
+            default:
+              return Promise.resolve([]);
+          }
+        }) as any);
+
+        const { edges } = await getNodesAndEdges({ id: 'BothWayService', version: '1.0.0' });
+
+        const bothEdges = edges.filter((e: any) => e.id?.includes('-both'));
+        expect(bothEdges).toHaveLength(0);
+      });
+
+      describe('group node expansion data (downstream channels, producers, consumers)', () => {
+        beforeEach(() => {
+          vi.mocked(getCollection).mockImplementation(((key: any) => {
+            switch (key) {
+              case 'services':
+                return Promise.resolve([mockGroupedServiceWithChannels, mockShipmentConsumerService, mockPickProducerService]);
+              case 'events':
+                return Promise.resolve(mockGroupedChannelEvents.filter((e) => e.collection === 'events'));
+              case 'commands':
+                return Promise.resolve(mockGroupedChannelEvents.filter((e) => e.collection === 'commands'));
+              case 'channels':
+                return Promise.resolve(mockGroupedChannels);
+              default:
+                return Promise.resolve([]);
+            }
+          }) as any);
+        });
+
+        it('group node data should include pre-computed expandedNodes and expandedEdges arrays', async () => {
+          const { nodes } = await getNodesAndEdges({ id: 'WarehouseService', version: '1.0.0' });
+
+          const groupNodes = nodes.filter((n: any) => n.type === 'messageGroup');
+          expect(groupNodes.length).toBeGreaterThanOrEqual(1);
+
+          for (const groupNode of groupNodes) {
+            expect(Array.isArray(groupNode.data.expandedNodes)).toBe(true);
+            expect(Array.isArray(groupNode.data.expandedEdges)).toBe(true);
+          }
+        });
+
+        it('sends group expandedNodes should include the channel node when a message routes to a channel', async () => {
+          const { nodes } = await getNodesAndEdges({ id: 'WarehouseService', version: '1.0.0' });
+
+          const shippingGroup = nodes.find(
+            (n: any) => n.type === 'messageGroup' && n.data.direction === 'sends' && n.data.groupName === 'Shipping'
+          );
+
+          const expandedNodeIds = shippingGroup.data.expandedNodes.map((n: any) => n.id);
+          expect(expandedNodeIds).toContain('ShippingChannel-1.0.0');
+        });
+
+        it('sends group expandedNodes should include consumer services downstream of the grouped messages', async () => {
+          const { nodes } = await getNodesAndEdges({ id: 'WarehouseService', version: '1.0.0' });
+
+          const shippingGroup = nodes.find(
+            (n: any) => n.type === 'messageGroup' && n.data.direction === 'sends' && n.data.groupName === 'Shipping'
+          );
+
+          const expandedNodeIds = shippingGroup.data.expandedNodes.map((n: any) => n.id);
+          expect(expandedNodeIds).toContain('DeliveryService-1.0.0');
+        });
+
+        it('receives group expandedNodes should include the channel node when a message comes from a channel', async () => {
+          const { nodes } = await getNodesAndEdges({ id: 'WarehouseService', version: '1.0.0' });
+
+          const pickingGroup = nodes.find(
+            (n: any) => n.type === 'messageGroup' && n.data.direction === 'receives' && n.data.groupName === 'Picking'
+          );
+
+          const expandedNodeIds = pickingGroup.data.expandedNodes.map((n: any) => n.id);
+          expect(expandedNodeIds).toContain('PickChannel-1.0.0');
+        });
+
+        it('receives group expandedNodes should include producer services upstream of the grouped messages', async () => {
+          const { nodes } = await getNodesAndEdges({ id: 'WarehouseService', version: '1.0.0' });
+
+          const pickingGroup = nodes.find(
+            (n: any) => n.type === 'messageGroup' && n.data.direction === 'receives' && n.data.groupName === 'Picking'
+          );
+
+          const expandedNodeIds = pickingGroup.data.expandedNodes.map((n: any) => n.id);
+          expect(expandedNodeIds).toContain('WMSService-1.0.0');
+        });
+
+        it('sends group expandedEdges should include the edge from message to channel', async () => {
+          const { nodes } = await getNodesAndEdges({ id: 'WarehouseService', version: '1.0.0' });
+
+          const shippingGroup = nodes.find(
+            (n: any) => n.type === 'messageGroup' && n.data.direction === 'sends' && n.data.groupName === 'Shipping'
+          );
+
+          expect(shippingGroup.data.expandedEdges).toEqual(
+            expect.arrayContaining([
+              expect.objectContaining({
+                source: 'ShipmentDispatched-1.0.0',
+                target: 'ShippingChannel-1.0.0',
+              }),
+            ])
+          );
+        });
+
+        it('expandedNodes should never contain the service node itself', async () => {
+          const { nodes } = await getNodesAndEdges({ id: 'WarehouseService', version: '1.0.0' });
+
+          const groupNodes = nodes.filter((n: any) => n.type === 'messageGroup');
+          for (const groupNode of groupNodes) {
+            const expandedNodeIds = groupNode.data.expandedNodes.map((n: any) => n.id);
+            expect(expandedNodeIds).not.toContain('WarehouseService-1.0.0');
+          }
+        });
+
+        it('expandedNodes should never contain the grouped message nodes themselves', async () => {
+          const { nodes } = await getNodesAndEdges({ id: 'WarehouseService', version: '1.0.0' });
+
+          const shippingGroup = nodes.find(
+            (n: any) => n.type === 'messageGroup' && n.data.direction === 'sends' && n.data.groupName === 'Shipping'
+          );
+
+          const expandedNodeIds = shippingGroup.data.expandedNodes.map((n: any) => n.id);
+          expect(expandedNodeIds).not.toContain('ShipmentDispatched-1.0.0');
+          expect(expandedNodeIds).not.toContain('ShipmentFailed-1.0.0');
+        });
+
+        it('expandedEdges should never contain direct service-to-message edges', async () => {
+          const { nodes } = await getNodesAndEdges({ id: 'WarehouseService', version: '1.0.0' });
+
+          const groupNodes = nodes.filter((n: any) => n.type === 'messageGroup');
+          for (const groupNode of groupNodes) {
+            const messageIds = groupNode.data.messages.map((m: any) => `${m.message.data.id}-${m.message.data.version}`);
+            const directEdges = groupNode.data.expandedEdges.filter(
+              (e: any) =>
+                (e.source === 'WarehouseService-1.0.0' && messageIds.includes(e.target)) ||
+                (e.target === 'WarehouseService-1.0.0' && messageIds.includes(e.source))
+            );
+            expect(directEdges).toHaveLength(0);
+          }
+        });
+      });
+
+      it('group node message data should include pre-computed operation fields (method, path)', async () => {
+        const serviceWithOps = {
+          ...mockGroupedServiceWithChannels,
+          data: {
+            ...mockGroupedServiceWithChannels.data,
+            id: 'OpService',
+            version: '1.0.0',
+            sends: [{ id: 'ShipmentDispatched', version: '1.0.0', group: 'Ops' }],
+            receives: [],
+          },
+        };
+        const eventWithOps = {
+          data: {
+            id: 'ShipmentDispatched',
+            version: '1.0.0',
+            name: 'ShipmentDispatched',
+            operation: { method: 'POST', path: '/shipments' },
+          },
+          collection: 'events',
+        };
+
+        vi.mocked(getCollection).mockImplementation(((key: any) => {
+          switch (key) {
+            case 'services':
+              return Promise.resolve([serviceWithOps]);
+            case 'events':
+              return Promise.resolve([eventWithOps]);
+            default:
+              return Promise.resolve([]);
+          }
+        }) as any);
+
+        const { nodes } = await getNodesAndEdges({ id: 'OpService', version: '1.0.0' });
+        const groupNode = nodes.find((n: any) => n.type === 'messageGroup');
+
+        const msgData = groupNode.data.messages[0].message.data;
+        expect(msgData.method).toBe('POST');
+        expect(msgData.path).toBe('/shipments');
+      });
+
+      it('should render a group node even for a single-message group', async () => {
+        const singleGroupService = {
+          ...mockGroupedService,
+          data: {
+            ...mockGroupedService.data,
+            id: 'SingleGroupService',
+            version: '1.0.0',
+            sends: [{ id: 'ProgramCreated', version: '1.0.0', group: 'Lonely Group' }],
+            receives: [],
+          },
+        };
+
+        vi.mocked(getCollection).mockImplementation(((key: any) => {
+          switch (key) {
+            case 'services':
+              return Promise.resolve([singleGroupService]);
+            case 'events':
+              return Promise.resolve([mockGroupedEvents[0]]);
+            default:
+              return Promise.resolve([]);
+          }
+        }) as any);
+
+        const { nodes } = await getNodesAndEdges({ id: 'SingleGroupService', version: '1.0.0' });
+        const groupNodes = nodes.filter((n: any) => n.type === 'messageGroup');
+        expect(groupNodes).toHaveLength(1);
+        expect(groupNodes[0].data.messageCount).toBe(1);
+      });
+    });
+  });
+});
diff --git a/eventcatalog/src/utils/__tests__/services/services.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/services/services.spec.ts
similarity index 88%
rename from eventcatalog/src/utils/__tests__/services/services.spec.ts
rename to packages/core/eventcatalog/src/utils/__tests__/services/services.spec.ts
index 121bc09b4..42968c388 100644
--- a/eventcatalog/src/utils/__tests__/services/services.spec.ts
+++ b/packages/core/eventcatalog/src/utils/__tests__/services/services.spec.ts
@@ -1,4 +1,4 @@
-import type { ContentCollectionKey } from 'astro:content';
+import type { CollectionKey } from 'astro:content';
 import { expect, describe, it, vi } from 'vitest';
 import { mockChannels, mockCommands, mockContainers, mockEvents, mockQueries, mockServices } from './mocks';
 import {
@@ -7,13 +7,14 @@ import {
   getConsumersOfMessage,
   getSpecificationsForService,
   getProducersAndConsumersForChannel,
+  getChannelsForService,
 } from '@utils/collections/services';
 
 vi.mock('astro:content', async (importOriginal) => {
   return {
     ...(await importOriginal<typeof import('astro:content')>()),
     // this will only affect "foo" outside of the original module
-    getCollection: (key: ContentCollectionKey) => {
+    getCollection: (key: CollectionKey) => {
       switch (key) {
         case 'services':
           return Promise.resolve(mockServices);
@@ -25,6 +26,10 @@ vi.mock('astro:content', async (importOriginal) => {
           return Promise.resolve(mockQueries);
         case 'containers':
           return Promise.resolve(mockContainers);
+        case 'channels':
+          return Promise.resolve(mockChannels);
+        default:
+          return Promise.resolve([]);
       }
     },
   };
@@ -451,4 +456,41 @@ describe('Services', () => {
       expect(consumers[2].data.id).toEqual('PaymentService');
     });
   });
+
+  describe('getChannelsForService', () => {
+    it('returns channels referenced in sends[].to for a service', async () => {
+      // PaymentService sends PaymentPaid to EmailChannel
+      const channels = await getChannelsForService('PaymentService');
+
+      expect(channels.length).toBeGreaterThanOrEqual(1);
+      expect(channels.some((c) => c.data.id === 'EmailChannel')).toBe(true);
+    });
+
+    it('returns channels referenced in receives[].from for a service', async () => {
+      // PaymentService receives OrderDeletedEvent from EmailChannel
+      const channels = await getChannelsForService('PaymentService');
+
+      expect(channels.some((c) => c.data.id === 'EmailChannel')).toBe(true);
+    });
+
+    it('deduplicates channels that appear in both sends and receives', async () => {
+      // PaymentService references EmailChannel in both sends[].to and receives[].from
+      const channels = await getChannelsForService('PaymentService');
+
+      const emailChannels = channels.filter((c) => c.data.id === 'EmailChannel');
+      expect(emailChannels).toHaveLength(1);
+    });
+
+    it('returns an empty array when a service has no channel references', async () => {
+      const channels = await getChannelsForService('OrderService');
+
+      expect(channels).toEqual([]);
+    });
+
+    it('returns an empty array when the service does not exist', async () => {
+      const channels = await getChannelsForService('NonExistentService');
+
+      expect(channels).toEqual([]);
+    });
+  });
 });
diff --git a/packages/core/eventcatalog/src/utils/__tests__/systems/context-node-graph.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/systems/context-node-graph.spec.ts
new file mode 100644
index 000000000..9ad143df0
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/systems/context-node-graph.spec.ts
@@ -0,0 +1,114 @@
+import type { CollectionKey } from 'astro:content';
+import { expect, describe, it, vi, beforeEach } from 'vitest';
+import { MarkerType } from '@xyflow/react';
+import { getNodesAndEdges } from '@utils/node-graphs/system-context-node-graph';
+
+// Each test sets its own systems via `setSystems` before calling the builder.
+let systems: any[] = [];
+const setSystems = (next: any[]) => {
+  systems = next;
+};
+
+const makeSystem = (id: string, data: Record<string, any> = {}) => ({
+  id: `systems/${id}/index.mdx`,
+  slug: `systems/${id}`,
+  collection: 'systems',
+  data: { id, name: id, version: '1.0.0', ...data },
+});
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    getCollection: (key: CollectionKey) => {
+      switch (key) {
+        case 'systems':
+          return Promise.resolve(systems);
+        case 'services':
+        default:
+          return Promise.resolve([]);
+      }
+    },
+  };
+});
+
+describe('System Context NodeGraph', () => {
+  beforeEach(() => {
+    systems = [];
+  });
+
+  describe('incoming system relationships', () => {
+    it('includes the source system and edge when the requested system is only a relationship target', async () => {
+      setSystems([
+        makeSystem('Shipping', { relationships: [{ id: 'Carrier', label: 'delivers shipments with' }] }),
+        makeSystem('Carrier'),
+      ]);
+
+      const { nodes, edges } = await getNodesAndEdges({ id: 'Carrier', version: '1.0.0' });
+
+      expect(nodes.map((node: any) => node.id).sort()).toEqual(['Carrier-1.0.0', 'Shipping-1.0.0']);
+      expect(edges).toHaveLength(1);
+      expect(edges[0]).toMatchObject({
+        source: 'Shipping-1.0.0',
+        target: 'Carrier-1.0.0',
+        label: 'delivers shipments with',
+      });
+      expect(edges[0].markerEnd).toEqual({ type: MarkerType.ArrowClosed, width: 20, height: 20 });
+      expect(edges[0].markerStart).toBeUndefined();
+    });
+  });
+
+  describe('reciprocal system relationships', () => {
+    it('collapses two reciprocal relationships into a single double-headed edge', async () => {
+      setSystems([
+        makeSystem('Shipping', { relationships: [{ id: 'Carrier', label: 'delivers shipments for' }] }),
+        makeSystem('Carrier', { relationships: [{ id: 'Shipping', label: 'delivers shipments for' }] }),
+      ]);
+
+      const { edges } = await getNodesAndEdges({ id: 'Shipping', version: '1.0.0' });
+
+      const systemEdges = edges.filter((edge: any) => edge.source.startsWith('Shipping') || edge.source.startsWith('Carrier'));
+
+      // One edge, not two, with arrowheads on both ends.
+      expect(systemEdges).toHaveLength(1);
+      expect(systemEdges[0].markerStart).toEqual({ type: MarkerType.ArrowClosed, width: 20, height: 20 });
+      expect(systemEdges[0].markerEnd).toEqual({ type: MarkerType.ArrowClosed, width: 20, height: 20 });
+    });
+
+    it('joins the two direction labels when they differ', async () => {
+      setSystems([
+        makeSystem('Shipping', { relationships: [{ id: 'Carrier', label: 'sends shipments to' }] }),
+        makeSystem('Carrier', { relationships: [{ id: 'Shipping', label: 'returns tracking to' }] }),
+      ]);
+
+      const { edges } = await getNodesAndEdges({ id: 'Shipping', version: '1.0.0' });
+
+      expect(edges).toHaveLength(1);
+      expect(edges[0].label).toBe('sends shipments to / returns tracking to');
+    });
+
+    it('keeps a single label when both directions share the same label', async () => {
+      setSystems([
+        makeSystem('Shipping', { relationships: [{ id: 'Carrier', label: 'delivers shipments for' }] }),
+        makeSystem('Carrier', { relationships: [{ id: 'Shipping', label: 'delivers shipments for' }] }),
+      ]);
+
+      const { edges } = await getNodesAndEdges({ id: 'Shipping', version: '1.0.0' });
+
+      expect(edges).toHaveLength(1);
+      expect(edges[0].label).toBe('delivers shipments for');
+    });
+
+    it('leaves a one-directional relationship as a single-headed edge', async () => {
+      setSystems([
+        makeSystem('Shipping', { relationships: [{ id: 'Carrier', label: 'delivers shipments for' }] }),
+        makeSystem('Carrier'),
+      ]);
+
+      const { edges } = await getNodesAndEdges({ id: 'Shipping', version: '1.0.0' });
+
+      expect(edges).toHaveLength(1);
+      expect(edges[0].markerEnd).toEqual({ type: MarkerType.ArrowClosed, width: 20, height: 20 });
+      expect(edges[0].markerStart).toBeUndefined();
+    });
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/__tests__/systems/mocks.ts b/packages/core/eventcatalog/src/utils/__tests__/systems/mocks.ts
new file mode 100644
index 000000000..2b45db768
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/systems/mocks.ts
@@ -0,0 +1,87 @@
+export const mockSystems = [
+  {
+    id: 'systems/CoreMonolith/index.mdx',
+    slug: 'systems/CoreMonolith',
+    collection: 'systems',
+    filePath: 'systems/CoreMonolith/index.mdx',
+    data: {
+      id: 'CoreMonolith',
+      name: 'Core Monolith',
+      version: '1.0.0',
+      // OrderService and PaymentService live in different domains but the same system
+      services: [
+        { id: 'OrderService', version: '1.0.0' },
+        { id: 'PaymentService', version: '1.0.0' },
+      ],
+      // The data store (container) mapped directly to the system
+      containers: [{ id: 'OrdersDB', version: '1.0.0' }],
+    },
+  },
+  {
+    id: 'systems/EmptySystem/index.mdx',
+    slug: 'systems/EmptySystem',
+    collection: 'systems',
+    filePath: 'systems/EmptySystem/index.mdx',
+    data: {
+      id: 'EmptySystem',
+      name: 'Empty System',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockServices = [
+  {
+    id: 'services/OrderService/index.mdx',
+    slug: 'services/OrderService',
+    collection: 'services',
+    data: {
+      id: 'OrderService',
+      version: '1.0.0',
+      sends: [{ id: 'OrderPlaced', version: '1.0.0' }],
+      // OrderService writes to the system's data store
+      writesTo: [{ id: 'OrdersDB', version: '1.0.0' }],
+    },
+  },
+  {
+    id: 'services/PaymentService/index.mdx',
+    slug: 'services/PaymentService',
+    collection: 'services',
+    data: {
+      id: 'PaymentService',
+      version: '1.0.0',
+      // PaymentService receives the message OrderService sends, so they connect inside the system
+      receives: [{ id: 'OrderPlaced', version: '1.0.0' }],
+    },
+  },
+];
+
+export const mockEvents = [
+  {
+    id: 'events/OrderPlaced/index.mdx',
+    slug: 'events/OrderPlaced',
+    collection: 'events',
+    data: {
+      id: 'OrderPlaced',
+      version: '1.0.0',
+    },
+  },
+];
+
+export const mockCommands = [];
+export const mockQueries = [];
+export const mockChannels = [];
+export const mockContainers = [
+  {
+    id: 'containers/OrdersDB/index.mdx',
+    slug: 'containers/OrdersDB',
+    collection: 'containers',
+    data: {
+      id: 'OrdersDB',
+      name: 'Orders DB',
+      version: '1.0.0',
+      container_type: 'database',
+      technology: 'postgres@14',
+    },
+  },
+];
diff --git a/packages/core/eventcatalog/src/utils/__tests__/systems/node-graph.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/systems/node-graph.spec.ts
new file mode 100644
index 000000000..824ce6636
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/__tests__/systems/node-graph.spec.ts
@@ -0,0 +1,153 @@
+import type { CollectionKey } from 'astro:content';
+import { expect, describe, it, vi } from 'vitest';
+import { mockSystems, mockServices, mockEvents, mockCommands, mockQueries, mockContainers } from './mocks';
+import { getNodesAndEdges } from '@utils/node-graphs/systems-node-graph';
+
+vi.mock('astro:content', async (importOriginal) => {
+  return {
+    ...(await importOriginal<typeof import('astro:content')>()),
+    // this will only affect "foo" outside of the original module
+    getCollection: (key: CollectionKey) => {
+      switch (key) {
+        case 'systems':
+          return Promise.resolve(mockSystems);
+        case 'services':
+          return Promise.resolve(mockServices);
+        case 'events':
+          return Promise.resolve(mockEvents);
+        case 'commands':
+          return Promise.resolve(mockCommands);
+        case 'queries':
+          return Promise.resolve(mockQueries);
+        case 'containers':
+          return Promise.resolve(mockContainers);
+        case 'channels':
+        case 'data-products':
+          return Promise.resolve([]);
+        default:
+          return Promise.resolve([]);
+      }
+    },
+  };
+});
+
+describe('Systems NodeGraph', () => {
+  describe('getNodesAndEdges', () => {
+    it('returns an empty array if no systems are found', async () => {
+      // @ts-ignore
+      const { nodes, edges } = await getNodesAndEdges({ id: 'UnknownSystem', version: '1.0.0' });
+
+      expect(nodes).toEqual([]);
+      expect(edges).toEqual([]);
+    });
+
+    it('returns an empty array if the system has no services', async () => {
+      // @ts-ignore
+      const { nodes, edges } = await getNodesAndEdges({ id: 'EmptySystem', version: '1.0.0' });
+
+      expect(nodes).toEqual([]);
+      expect(edges).toEqual([]);
+    });
+
+    it('should return the merged nodes and edges for the services in a given system', async () => {
+      // @ts-ignore
+      const { nodes, edges } = await getNodesAndEdges({ id: 'CoreMonolith', version: '1.0.0' });
+
+      const expectedOrderServiceNode = {
+        id: 'OrderService-1.0.0',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: expect.objectContaining({ id: 'OrderService' }) }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedPaymentServiceNode = {
+        id: 'PaymentService-1.0.0',
+        type: 'services',
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: expect.objectContaining({ mode: 'simple', service: expect.objectContaining({ id: 'PaymentService' }) }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      const expectedEventNode = {
+        id: 'OrderPlaced-1.0.0',
+        type: 'events',
+        data: expect.objectContaining({ mode: 'simple', message: expect.objectContaining({ id: 'OrderPlaced' }) }),
+        position: { x: expect.any(Number), y: expect.any(Number) },
+      };
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining(expectedOrderServiceNode),
+          expect.objectContaining(expectedPaymentServiceNode),
+          expect.objectContaining(expectedEventNode),
+        ])
+      );
+
+      // The shared message is only rendered once (the two service graphs are merged, not duplicated)
+      const orderPlacedNodes = nodes.filter((node: any) => node.id === 'OrderPlaced-1.0.0');
+      expect(orderPlacedNodes).toHaveLength(1);
+    });
+
+    it('should connect services in the system through the messages they share', async () => {
+      // @ts-ignore
+      const { edges } = await getNodesAndEdges({ id: 'CoreMonolith', version: '1.0.0' });
+
+      // OrderService sends OrderPlaced...
+      const sendsEdge = edges.find((e: any) => e.source === 'OrderService-1.0.0' && e.target === 'OrderPlaced-1.0.0');
+      // ...and PaymentService receives it
+      const receivesEdge = edges.find((e: any) => e.source === 'OrderPlaced-1.0.0' && e.target === 'PaymentService-1.0.0');
+
+      expect(sendsEdge).toBeDefined();
+      expect(receivesEdge).toBeDefined();
+    });
+
+    it('should render the data stores (containers) mapped to the system', async () => {
+      // @ts-ignore
+      const { nodes } = await getNodesAndEdges({ id: 'CoreMonolith', version: '1.0.0' });
+
+      const dataStoreNode = nodes.find((node: any) => node.id === 'OrdersDB-1.0.0');
+
+      expect(dataStoreNode).toEqual(
+        expect.objectContaining({
+          id: 'OrdersDB-1.0.0',
+          type: 'data',
+          data: expect.objectContaining({ data: expect.objectContaining({ id: 'OrdersDB' }) }),
+        })
+      );
+
+      // The data store is only rendered once even though it is reachable via both the
+      // service node-graph and the container node-graph (they are merged, not duplicated)
+      const dataStoreNodes = nodes.filter((node: any) => node.id === 'OrdersDB-1.0.0');
+      expect(dataStoreNodes).toHaveLength(1);
+    });
+
+    it('should connect the system services to the data stores they write to', async () => {
+      // @ts-ignore
+      const { edges } = await getNodesAndEdges({ id: 'CoreMonolith', version: '1.0.0' });
+
+      // OrderService writes to OrdersDB
+      const writesToEdge = edges.find((e: any) => e.source === 'OrderService-1.0.0' && e.target === 'OrdersDB-1.0.0');
+
+      expect(writesToEdge).toBeDefined();
+    });
+
+    it('should tag nodes with the system group when rendered as a group', async () => {
+      // @ts-ignore
+      const { nodes } = await getNodesAndEdges({ id: 'CoreMonolith', version: '1.0.0', group: true });
+
+      expect(nodes).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            id: 'OrderService-1.0.0',
+            data: expect.objectContaining({
+              group: { type: 'System', value: 'Core Monolith', id: 'CoreMonolith' },
+            }),
+          }),
+        ])
+      );
+    });
+  });
+});
diff --git a/eventcatalog/src/utils/__tests__/url-builder.spec.ts b/packages/core/eventcatalog/src/utils/__tests__/url-builder.spec.ts
similarity index 100%
rename from eventcatalog/src/utils/__tests__/url-builder.spec.ts
rename to packages/core/eventcatalog/src/utils/__tests__/url-builder.spec.ts
diff --git a/packages/core/eventcatalog/src/utils/badge-styles.ts b/packages/core/eventcatalog/src/utils/badge-styles.ts
new file mode 100644
index 000000000..14c67fedb
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/badge-styles.ts
@@ -0,0 +1,237 @@
+import { buildUrl } from './url-builder';
+
+type BadgeColorKind = 'background' | 'text';
+
+type Badge = {
+  backgroundColor?: string;
+  textColor?: string;
+  url?: string;
+};
+
+const URL_SCHEME_PATTERN = /^[a-z][a-z\d+\-.]*:/i;
+const PROTOCOL_RELATIVE_URL_PATTERN = /^\/\//;
+const SAFE_BADGE_URL_SCHEMES = new Set(['http:', 'https:', 'mailto:', 'tel:']);
+
+const isAlreadyBasePrefixed = (url: string) => {
+  const baseUrl = import.meta.env.BASE_URL;
+  if (!baseUrl || baseUrl === '/') return false;
+
+  const normalizedBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+  return url === normalizedBaseUrl || url.startsWith(`${normalizedBaseUrl}/`);
+};
+
+const NAMED_BADGE_COLOR_KEYS = new Set([
+  'slate',
+  'gray',
+  'zinc',
+  'neutral',
+  'stone',
+  'red',
+  'orange',
+  'amber',
+  'yellow',
+  'lime',
+  'green',
+  'emerald',
+  'teal',
+  'cyan',
+  'sky',
+  'blue',
+  'indigo',
+  'violet',
+  'purple',
+  'fuchsia',
+  'pink',
+  'rose',
+]);
+
+const CSS_COLOR_VALUE_PATTERN =
+  /^(#[0-9a-f]{3,8}|(?:rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|color)\(.+\)|var\(--[a-z0-9-_]+\)|transparent|currentColor)$/i;
+
+// Common CSS named colors that callers may use directly (e.g. textColor: "white").
+// Palette tokens above take precedence — names like "red" or "blue" resolve to the
+// theme-aware token rather than the raw CSS keyword.
+const CSS_NAMED_COLORS = new Set([
+  'aliceblue',
+  'antiquewhite',
+  'aqua',
+  'aquamarine',
+  'azure',
+  'beige',
+  'bisque',
+  'black',
+  'blanchedalmond',
+  'blueviolet',
+  'brown',
+  'burlywood',
+  'cadetblue',
+  'chartreuse',
+  'chocolate',
+  'coral',
+  'cornflowerblue',
+  'cornsilk',
+  'crimson',
+  'darkblue',
+  'darkcyan',
+  'darkgoldenrod',
+  'darkgray',
+  'darkgreen',
+  'darkgrey',
+  'darkkhaki',
+  'darkmagenta',
+  'darkolivegreen',
+  'darkorange',
+  'darkorchid',
+  'darkred',
+  'darksalmon',
+  'darkseagreen',
+  'darkslateblue',
+  'darkslategray',
+  'darkslategrey',
+  'darkturquoise',
+  'darkviolet',
+  'deeppink',
+  'deepskyblue',
+  'dimgray',
+  'dimgrey',
+  'dodgerblue',
+  'firebrick',
+  'floralwhite',
+  'forestgreen',
+  'gainsboro',
+  'ghostwhite',
+  'gold',
+  'goldenrod',
+  'greenyellow',
+  'grey',
+  'honeydew',
+  'hotpink',
+  'indianred',
+  'ivory',
+  'khaki',
+  'lavender',
+  'lavenderblush',
+  'lawngreen',
+  'lemonchiffon',
+  'lightblue',
+  'lightcoral',
+  'lightcyan',
+  'lightgoldenrodyellow',
+  'lightgray',
+  'lightgreen',
+  'lightgrey',
+  'lightpink',
+  'lightsalmon',
+  'lightseagreen',
+  'lightskyblue',
+  'lightslategray',
+  'lightslategrey',
+  'lightsteelblue',
+  'lightyellow',
+  'limegreen',
+  'linen',
+  'magenta',
+  'maroon',
+  'mediumaquamarine',
+  'mediumblue',
+  'mediumorchid',
+  'mediumpurple',
+  'mediumseagreen',
+  'mediumslateblue',
+  'mediumspringgreen',
+  'mediumturquoise',
+  'mediumvioletred',
+  'midnightblue',
+  'mintcream',
+  'mistyrose',
+  'moccasin',
+  'navajowhite',
+  'navy',
+  'oldlace',
+  'olive',
+  'olivedrab',
+  'orangered',
+  'orchid',
+  'palegoldenrod',
+  'palegreen',
+  'paleturquoise',
+  'palevioletred',
+  'papayawhip',
+  'peachpuff',
+  'peru',
+  'plum',
+  'powderblue',
+  'rebeccapurple',
+  'rosybrown',
+  'royalblue',
+  'saddlebrown',
+  'salmon',
+  'sandybrown',
+  'seagreen',
+  'seashell',
+  'sienna',
+  'silver',
+  'skyblue',
+  'slateblue',
+  'slategray',
+  'slategrey',
+  'snow',
+  'springgreen',
+  'steelblue',
+  'tan',
+  'thistle',
+  'tomato',
+  'turquoise',
+  'wheat',
+  'white',
+  'whitesmoke',
+  'yellowgreen',
+]);
+
+const resolveBadgeColor = (color: string | undefined, kind: BadgeColorKind) => {
+  if (!color) return undefined;
+
+  const value = color.trim();
+  const namedColorKey = value.toLowerCase();
+
+  if (NAMED_BADGE_COLOR_KEYS.has(namedColorKey)) return `rgb(var(--ec-badge-color-${namedColorKey}-${kind}))`;
+  if (CSS_COLOR_VALUE_PATTERN.test(value)) return value;
+  if (CSS_NAMED_COLORS.has(namedColorKey)) return namedColorKey;
+
+  return undefined;
+};
+
+export const getBadgeStyle = (badge: Badge) => {
+  const backgroundColor = resolveBadgeColor(badge.backgroundColor, 'background');
+  const color = resolveBadgeColor(badge.textColor, 'text');
+
+  return [backgroundColor ? `background-color: ${backgroundColor};` : '', color ? `color: ${color};` : '']
+    .filter(Boolean)
+    .join(' ');
+};
+
+export const getBadgeReactStyle = (badge: Badge) => {
+  const backgroundColor = resolveBadgeColor(badge.backgroundColor, 'background');
+  const color = resolveBadgeColor(badge.textColor, 'text');
+
+  return {
+    ...(backgroundColor ? { backgroundColor } : {}),
+    ...(color ? { color } : {}),
+  };
+};
+
+export const getBadgeHref = (badge: Badge) => {
+  if (!badge.url) return undefined;
+
+  const url = badge.url.trim();
+  if (!url) return undefined;
+  if (url.startsWith('#') || url.startsWith('?') || PROTOCOL_RELATIVE_URL_PATTERN.test(url)) return url;
+
+  const scheme = URL_SCHEME_PATTERN.exec(url)?.[0].toLowerCase();
+  if (scheme) return SAFE_BADGE_URL_SCHEMES.has(scheme) ? url : undefined;
+
+  if (isAlreadyBasePrefixed(url)) return url;
+  if (url.startsWith('/')) return buildUrl(url);
+
+  return url;
+};
diff --git a/eventcatalog/src/utils/badges.tsx b/packages/core/eventcatalog/src/utils/badges.tsx
similarity index 100%
rename from eventcatalog/src/utils/badges.tsx
rename to packages/core/eventcatalog/src/utils/badges.tsx
diff --git a/packages/core/eventcatalog/src/utils/clipboard.ts b/packages/core/eventcatalog/src/utils/clipboard.ts
new file mode 100644
index 000000000..73fbca36f
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/clipboard.ts
@@ -0,0 +1,22 @@
+/**
+ * Copy text to clipboard with fallback for older browsers
+ * @param text - The text to copy to clipboard
+ * @returns Promise that resolves to true if successful
+ */
+export async function copyToClipboard(text: string): Promise<boolean> {
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {
+    // Fallback for older browsers
+    const textarea = document.createElement('textarea');
+    textarea.value = text;
+    textarea.style.position = 'fixed';
+    textarea.style.opacity = '0';
+    document.body.appendChild(textarea);
+    textarea.select();
+    document.execCommand('copy');
+    document.body.removeChild(textarea);
+    return true;
+  }
+}
diff --git a/packages/core/eventcatalog/src/utils/collection-colors.ts b/packages/core/eventcatalog/src/utils/collection-colors.ts
new file mode 100644
index 000000000..edffcd24c
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collection-colors.ts
@@ -0,0 +1,88 @@
+export type CollectionColor =
+  | 'orange'
+  | 'blue'
+  | 'green'
+  | 'pink'
+  | 'yellow'
+  | 'teal'
+  | 'purple'
+  | 'red'
+  | 'gray'
+  | 'cyan'
+  | 'sky'
+  | 'indigo'
+  | 'violet';
+
+export const getColorForCollection = (collection: string): CollectionColor => {
+  switch (collection) {
+    case 'events':
+      return 'orange';
+    case 'commands':
+      return 'blue';
+    case 'queries':
+      return 'green';
+    case 'flows':
+      return 'teal';
+    case 'teams':
+      return 'gray';
+    case 'users':
+      return 'gray';
+    case 'channels':
+      return 'purple';
+    case 'ubiquitousLanguages':
+      return 'green';
+    case 'entities':
+      return 'purple';
+    case 'domains':
+      return 'yellow';
+    case 'systems':
+      return 'violet';
+    case 'agents':
+      return 'sky';
+    case 'adrs':
+      return 'purple';
+    case 'services':
+      return 'pink';
+    case 'data-products':
+      return 'cyan';
+    case 'containers':
+      return 'indigo';
+    default:
+      return 'gray';
+  }
+};
+
+export const tailwind500RgbByColor: Record<CollectionColor, string> = {
+  orange: '249 115 22',
+  blue: '59 130 246',
+  green: '34 197 94',
+  pink: '236 72 153',
+  yellow: '234 179 8',
+  teal: '20 184 166',
+  purple: '168 85 247',
+  red: '239 68 68',
+  gray: '107 114 128',
+  cyan: '6 182 212',
+  sky: '14 165 233',
+  indigo: '99 102 241',
+  violet: '139 92 246',
+};
+
+export const collectionTextColorClassByColor: Record<CollectionColor, string> = {
+  orange: 'text-orange-500',
+  blue: 'text-blue-500',
+  green: 'text-green-500',
+  pink: 'text-pink-500',
+  yellow: 'text-yellow-500',
+  teal: 'text-teal-500',
+  purple: 'text-purple-500',
+  red: 'text-red-500',
+  gray: 'text-gray-500',
+  cyan: 'text-cyan-500',
+  sky: 'text-sky-500',
+  indigo: 'text-indigo-500',
+  violet: 'text-violet-500',
+};
+
+export const getCollectionTextColorClass = (color: string, fallback = 'text-gray-500'): string =>
+  collectionTextColorClassByColor[color as CollectionColor] || fallback;
diff --git a/packages/core/eventcatalog/src/utils/collections/adr-constants.ts b/packages/core/eventcatalog/src/utils/collections/adr-constants.ts
new file mode 100644
index 000000000..e2bd18fa6
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/adr-constants.ts
@@ -0,0 +1,53 @@
+export const ADR_STATUS = {
+  PROPOSED: 'proposed',
+  ACCEPTED: 'accepted',
+  REJECTED: 'rejected',
+  DEPRECATED: 'deprecated',
+  SUPERSEDED: 'superseded',
+} as const;
+
+export const ADR_STATUS_VALUES = [
+  ADR_STATUS.PROPOSED,
+  ADR_STATUS.ACCEPTED,
+  ADR_STATUS.REJECTED,
+  ADR_STATUS.DEPRECATED,
+  ADR_STATUS.SUPERSEDED,
+] as const;
+
+export type AdrStatus = (typeof ADR_STATUS)[keyof typeof ADR_STATUS];
+
+export const adrStatusBadgeColor: Record<AdrStatus, string> = {
+  [ADR_STATUS.PROPOSED]: 'amber',
+  [ADR_STATUS.ACCEPTED]: 'green',
+  [ADR_STATUS.REJECTED]: 'red',
+  [ADR_STATUS.DEPRECATED]: 'gray',
+  [ADR_STATUS.SUPERSEDED]: 'purple',
+};
+
+export const isAdrCollection = (collection: string | undefined): collection is 'adrs' => collection === 'adrs';
+
+export const hasAdrStatus = (adr: { data?: { status?: string } }, status: AdrStatus) => adr.data?.status === status;
+
+export const isDeprecatedAdr = (adr: { data?: { status?: string } }) => hasAdrStatus(adr, ADR_STATUS.DEPRECATED);
+
+export const isSupersededAdr = (adr: { data?: { status?: string } }) => hasAdrStatus(adr, ADR_STATUS.SUPERSEDED);
+
+export const formatAdrStatus = (status: AdrStatus) =>
+  status
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+
+export const formatAdrDate = (date: Date) =>
+  new Intl.DateTimeFormat('en-US', {
+    timeZone: 'UTC',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  }).format(date);
+
+export const createAdrStatusBadge = (status: AdrStatus) => ({
+  content: formatAdrStatus(status),
+  backgroundColor: adrStatusBadgeColor[status],
+  textColor: adrStatusBadgeColor[status],
+});
diff --git a/packages/core/eventcatalog/src/utils/collections/adrs.ts b/packages/core/eventcatalog/src/utils/collections/adrs.ts
new file mode 100644
index 000000000..2e6f65f1f
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/adrs.ts
@@ -0,0 +1,146 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import type { CollectionTypes, CollectionUserTypes } from '@types';
+import { collectionToResourceMap, createVersionedMap, findInMap, versionMatches } from '@utils/collections/util';
+export {
+  ADR_STATUS,
+  adrStatusBadgeColor,
+  createAdrStatusBadge,
+  formatAdrDate,
+  formatAdrStatus,
+  hasAdrStatus,
+  isAdrCollection,
+  isDeprecatedAdr,
+  isSupersededAdr,
+  type AdrStatus,
+} from './adr-constants';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+
+export type Adr = CollectionEntry<'adrs'>;
+export type AdrResourceType = NonNullable<Adr['data']['appliesTo']>[number]['type'];
+export type AdrPointer = { id: string; version?: string };
+export type AdrResource = CollectionEntry<CollectionTypes> | CollectionEntry<CollectionUserTypes>;
+
+interface Props {
+  getAllVersions?: boolean;
+  returnBody?: boolean;
+}
+
+let memoryCache: Record<string, Adr[]> = {};
+
+export const getAdrs = async ({ getAllVersions = true, returnBody = false }: Props = {}): Promise<Adr[]> => {
+  const cacheKey = `${getAllVersions ? 'allVersions' : 'currentVersions'}-${returnBody ? 'withBody' : 'noBody'}`;
+
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    return memoryCache[cacheKey];
+  }
+
+  const allAdrs = await getCollection('adrs');
+  const adrMap = createVersionedMap(allAdrs);
+
+  const targetAdrs = allAdrs.filter((adr) => {
+    if (adr.data.hidden === true) return false;
+    if (!getAllVersions && adr.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  const processedAdrs = targetAdrs.map((adr) => {
+    const adrVersions = adrMap.get(adr.data.id) || [];
+    const latestVersion = adrVersions[0]?.data.version || adr.data.version;
+    const versions = adrVersions.map((entry) => entry.data.version);
+
+    return {
+      ...adr,
+      data: {
+        ...adr.data,
+        versions,
+        latestVersion,
+      },
+      body: returnBody ? adr.body : undefined,
+    };
+  });
+
+  processedAdrs.sort((a, b) => {
+    const dateCompare = Number(b.data.date) - Number(a.data.date);
+    if (dateCompare !== 0) return dateCompare;
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedAdrs;
+
+  return processedAdrs;
+};
+
+export const getAdrNodeKey = (adr: Adr) => `adr:${adr.data.id}:${adr.data.version}`;
+
+export const getAdrAliasNodeKey = (adr: Adr) => `adr:${adr.data.id}`;
+
+export const getAdrResourceNodeKey = (resource: AdrResource) => {
+  const resourceType = collectionToResourceMap[resource.collection as keyof typeof collectionToResourceMap];
+  if (!resourceType) return undefined;
+  if (resource.collection === 'users' || resource.collection === 'teams') return `${resourceType}:${resource.data.id}`;
+  return `${resourceType}:${resource.data.id}:${(resource.data as any).version}`;
+};
+
+const isResourcePointerMatch = (resource: AdrResource, pointer: NonNullable<Adr['data']['appliesTo']>[number]) => {
+  const resourceType = collectionToResourceMap[resource.collection as keyof typeof collectionToResourceMap];
+  if (pointer.type !== resourceType || pointer.id !== resource.data.id) return false;
+
+  const resourceVersion = (resource.data as any).version;
+  if (!resourceVersion) return true;
+  if (!pointer.version || pointer.version === 'latest') return true;
+
+  return versionMatches(resourceVersion, pointer.version);
+};
+
+export const getAdrsForResource = (resource: AdrResource, adrs: Adr[]) => {
+  return adrs.filter((adr) => (adr.data.appliesTo || []).some((pointer) => isResourcePointerMatch(resource, pointer)));
+};
+
+export const resolveAdrPointers = (pointers: AdrPointer[] | undefined, adrs: Adr[]) => {
+  if (!pointers || pointers.length === 0) return [];
+
+  const adrMap = createVersionedMap(adrs);
+  return pointers.map((pointer) => findInMap(adrMap, pointer.id, pointer.version)).filter((adr): adr is Adr => !!adr);
+};
+
+export const getAdrRelationships = (adr: Adr, adrs: Adr[]) => {
+  const supersedes = resolveAdrPointers(adr.data.supersedes, adrs);
+  const explicitSupersededBy = resolveAdrPointers(adr.data.supersededBy, adrs);
+  const derivedSupersededBy = adrs.filter((candidate) =>
+    (candidate.data.supersedes || []).some((pointer) => {
+      if (pointer.id !== adr.data.id) return false;
+      return !pointer.version || pointer.version === 'latest' || versionMatches(adr.data.version, pointer.version);
+    })
+  );
+
+  const amends = resolveAdrPointers(adr.data.amends, adrs);
+  const explicitAmendedBy = resolveAdrPointers(adr.data.amendedBy, adrs);
+  const derivedAmendedBy = adrs.filter((candidate) =>
+    (candidate.data.amends || []).some((pointer) => {
+      if (pointer.id !== adr.data.id) return false;
+      return !pointer.version || pointer.version === 'latest' || versionMatches(adr.data.version, pointer.version);
+    })
+  );
+
+  return {
+    supersedes,
+    supersededBy: uniqueAdrs([...explicitSupersededBy, ...derivedSupersededBy], adr),
+    amends,
+    amendedBy: uniqueAdrs([...explicitAmendedBy, ...derivedAmendedBy], adr),
+    related: resolveAdrPointers(adr.data.related, adrs),
+  };
+};
+
+const uniqueAdrs = (adrs: Adr[], currentAdr?: Adr) => {
+  const seen = new Set<string>();
+
+  return adrs.filter((adr) => {
+    if (currentAdr && adr.data.id === currentAdr.data.id && adr.data.version === currentAdr.data.version) return false;
+
+    const key = `${adr.data.id}:${adr.data.version}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/agents.ts b/packages/core/eventcatalog/src/utils/collections/agents.ts
new file mode 100644
index 000000000..a5138b500
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/agents.ts
@@ -0,0 +1,163 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import type { CollectionMessageTypes } from '@types';
+import { createVersionedMap, findInMap, versionMatches } from '@utils/collections/util';
+import { getChannels } from './channels';
+
+export type Agent = CollectionEntry<'agents'>;
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+
+interface Props {
+  getAllVersions?: boolean;
+  returnBody?: boolean;
+}
+
+let memoryCache: Record<string, Agent[]> = {};
+
+export const getAgents = async ({ getAllVersions = true, returnBody = false }: Props = {}): Promise<Agent[]> => {
+  const cacheKey = `${getAllVersions ? 'allVersions' : 'currentVersions'}-${returnBody ? 'withBody' : 'noBody'}`;
+
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    return memoryCache[cacheKey];
+  }
+
+  const [allAgents, allEvents, allCommands, allQueries, allContainers, allFlows] = await Promise.all([
+    getCollection('agents'),
+    getCollection('events'),
+    getCollection('commands'),
+    getCollection('queries'),
+    getCollection('containers'),
+    getCollection('flows'),
+  ]);
+
+  const allMessages = [...allEvents, ...allCommands, ...allQueries];
+  const agentMap = createVersionedMap(allAgents);
+  const messageMap = createVersionedMap(allMessages);
+  const containerMap = createVersionedMap(allContainers);
+  const flowMap = createVersionedMap(allFlows);
+
+  const targetAgents = allAgents.filter((agent) => {
+    if (agent.data.hidden === true) return false;
+    if (!getAllVersions && agent.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  const processedAgents = await Promise.all(
+    targetAgents.map(async (agent) => {
+      const agentVersions = agentMap.get(agent.data.id) || [];
+      const latestVersion = agentVersions[0]?.data.version || agent.data.version;
+      const versions = agentVersions.map((a) => a.data.version);
+
+      const sends = (agent.data.sends || [])
+        .map((m) => findInMap(messageMap, m.id, m.version))
+        .filter((e): e is CollectionEntry<CollectionMessageTypes> => !!e);
+
+      const receives = (agent.data.receives || [])
+        .map((m) => findInMap(messageMap, m.id, m.version))
+        .filter((e): e is CollectionEntry<CollectionMessageTypes> => !!e);
+
+      const mappedWritesTo = (agent.data.writesTo || [])
+        .map((c) => findInMap(containerMap, c.id, c.version))
+        .filter((e): e is CollectionEntry<'containers'> => !!e);
+
+      const mappedReadsFrom = (agent.data.readsFrom || [])
+        .map((c) => findInMap(containerMap, c.id, c.version))
+        .filter((e): e is CollectionEntry<'containers'> => !!e);
+
+      const mappedFlows = (agent.data.flows || [])
+        .map((f) => findInMap(flowMap, f.id, f.version))
+        .filter((f): f is CollectionEntry<'flows'> => !!f);
+
+      return {
+        ...agent,
+        data: {
+          ...agent.data,
+          writesTo: mappedWritesTo as any,
+          readsFrom: mappedReadsFrom as any,
+          flows: mappedFlows as any,
+          receives: receives as any,
+          sends: sends as any,
+          versions,
+          latestVersion,
+        },
+        nodes: {
+          receives: receives as any,
+          sends: sends as any,
+        },
+        body: returnBody ? agent.body : undefined,
+      };
+    })
+  );
+
+  processedAgents.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedAgents;
+
+  return processedAgents;
+};
+
+export const getProducersOfMessage = (agents: Agent[], message: CollectionEntry<'events' | 'commands' | 'queries'>) => {
+  return agents.filter((agent) => {
+    return agent.data.sends?.some((send) => {
+      const idMatch = send.id === message.data.id;
+      if (!send.version) return idMatch;
+      if (send.version === 'latest') return idMatch;
+      return idMatch && versionMatches(message.data.version, send.version);
+    });
+  });
+};
+
+export const getConsumersOfMessage = (agents: Agent[], message: CollectionEntry<'events' | 'commands' | 'queries'>) => {
+  return agents.filter((agent) => {
+    return agent.data.receives?.some((receive) => {
+      const idMatch = receive.id === message.data.id;
+      if (!receive.version) return idMatch;
+      if (receive.version === 'latest') return idMatch;
+      return idMatch && versionMatches(message.data.version, receive.version);
+    });
+  });
+};
+
+export const getChannelsForAgent = async (agentId: string, version?: string): Promise<CollectionEntry<'channels'>[]> => {
+  const allAgents = await getCollection('agents');
+  const allChannels = await getChannels({ getAllVersions: true });
+
+  const agentMap = createVersionedMap(allAgents);
+  const agent = findInMap(agentMap, agentId, version);
+  if (!agent) return [];
+
+  const sends = agent.data.sends ?? [];
+  const receives = agent.data.receives ?? [];
+
+  const channelPointers: Array<{ id: string; version?: string }> = [];
+
+  for (const send of sends) {
+    for (const channel of send.to ?? []) {
+      channelPointers.push({ id: channel.id, version: channel.version });
+    }
+  }
+
+  for (const receive of receives) {
+    for (const channel of receive.from ?? []) {
+      channelPointers.push({ id: channel.id, version: channel.version });
+    }
+  }
+
+  const channelMap = createVersionedMap(allChannels);
+  const seen = new Set<string>();
+  const channels: CollectionEntry<'channels'>[] = [];
+
+  for (const pointer of channelPointers) {
+    const key = `${pointer.id}-${pointer.version ?? 'latest'}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const match = findInMap(channelMap, pointer.id, pointer.version);
+    if (match) channels.push(match as CollectionEntry<'channels'>);
+  }
+
+  return channels;
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/changelogs.ts b/packages/core/eventcatalog/src/utils/collections/changelogs.ts
new file mode 100644
index 000000000..391682ce3
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/changelogs.ts
@@ -0,0 +1,49 @@
+import type { CollectionTypes } from '@types';
+import { getCollection, type CollectionEntry } from 'astro:content';
+import path from 'node:path';
+import { coerce, rcompare } from 'semver';
+
+export type ChangeLog = CollectionEntry<'changelogs'>;
+
+export const getChangeLogs = async (item: CollectionEntry<CollectionTypes>): Promise<ChangeLog[]> => {
+  const { collection, data, filePath } = item;
+
+  const collectionDirectory = path.dirname(item?.filePath || '');
+  // Ensure the path follows <collectionDirectory>/versioned/<version>/changelog.mdx
+  // Pre-compile regex
+  const versionedPathPattern = new RegExp(`${collectionDirectory}/versioned/[^/]+/changelog\\.mdx$`);
+  const rootChangeLogPath = path.join(collectionDirectory, 'changelog.mdx');
+
+  // Get all logs for collection type and filter by given collection
+  const logs = await getCollection('changelogs', (log) => {
+    const isRootChangeLog = rootChangeLogPath === log.filePath;
+    const isVersionedChangeLog = versionedPathPattern.test(log.filePath!);
+    return log.id.includes(`${collection}/`) && (isRootChangeLog || isVersionedChangeLog);
+  });
+
+  const hydratedLogs = logs.map((log) => {
+    // Check if there is a version in the url
+    const isVersioned = log.id.includes('versioned');
+
+    const parts = log.filePath!.split('/');
+    // hack to get the version of the id (url)
+    const version = parts[parts.length - 2];
+    return {
+      ...log,
+      data: {
+        ...log.data,
+        version: isVersioned ? version : data.latestVersion || 'latest',
+      },
+    };
+  });
+
+  // Order by semver (descending)
+  return hydratedLogs.sort((a, b) => {
+    const semverA = coerce(a.data.version);
+    const semverB = coerce(b.data.version);
+    if (semverA && semverB) {
+      return rcompare(semverA, semverB);
+    }
+    return b.data.version.localeCompare(a.data.version);
+  });
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/channels.ts b/packages/core/eventcatalog/src/utils/collections/channels.ts
new file mode 100644
index 000000000..89f87dd12
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/channels.ts
@@ -0,0 +1,189 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { getItemsFromCollectionByIdAndSemverOrLatest, createVersionedMap, satisfies } from './util';
+import type { CollectionMessageTypes } from '@types';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+
+type Channel = CollectionEntry<'channels'>;
+
+interface Props {
+  getAllVersions?: boolean;
+}
+
+// cache for build time
+let memoryCache: Record<string, Channel[]> = {};
+
+export const getChannels = async ({ getAllVersions = true }: Props = {}): Promise<Channel[]> => {
+  // console.time('✅ New getChannels');
+  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
+
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    // console.timeEnd('✅ New getChannels');
+    return memoryCache[cacheKey];
+  }
+
+  // 1. Fetch collections in parallel
+  const [allChannels, allEvents, allCommands, allQueries] = await Promise.all([
+    getCollection('channels'),
+    getCollection('events'),
+    getCollection('commands'),
+    getCollection('queries'),
+  ]);
+
+  const allMessages = [...allEvents, ...allCommands, ...allQueries];
+
+  // 2. Build optimized maps
+  const channelMap = createVersionedMap(allChannels);
+
+  // 3. Build Message Index by Channel ID (Reverse Index)
+  // Map<ChannelID, Array<{ message: Message, requiredVersion: string | undefined }>>
+  const messagesByChannelId = new Map<
+    string,
+    Array<{ message: CollectionEntry<CollectionMessageTypes>; requiredVersion?: string }>
+  >();
+
+  for (const message of allMessages) {
+    if (message.data.channels) {
+      for (const channelRef of message.data.channels) {
+        if (!messagesByChannelId.has(channelRef.id)) {
+          messagesByChannelId.set(channelRef.id, []);
+        }
+        messagesByChannelId.get(channelRef.id)!.push({
+          message,
+          requiredVersion: channelRef.version,
+        });
+      }
+    }
+  }
+
+  // 4. Filter channels
+  const targetChannels = allChannels.filter((channel) => {
+    if (channel.data.hidden === true) return false;
+    if (!getAllVersions && channel.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  // 5. Enrich channels
+  const processedChannels = await Promise.all(
+    targetChannels.map(async (channel) => {
+      // Version info
+      const channelVersions = channelMap.get(channel.data.id) || [];
+      const latestVersion = channelVersions[0]?.data.version || channel.data.version;
+      const versions = channelVersions.map((c) => c.data.version);
+
+      // Find messages for this channel version
+      const candidateMessages = messagesByChannelId.get(channel.data.id) || [];
+
+      const messagesForChannel = candidateMessages
+        .filter(({ requiredVersion }) => {
+          if (requiredVersion === 'latest' || requiredVersion === undefined) {
+            return channel.data.version === latestVersion;
+          }
+          return satisfies(channel.data.version, requiredVersion);
+        })
+        .map(({ message }) => message);
+
+      const messages = messagesForChannel.map((message) => {
+        return {
+          id: message.data.id,
+          name: message.data.name,
+          version: message.data.version,
+          collection: message.collection,
+        };
+      });
+
+      return {
+        ...channel,
+        data: {
+          ...channel.data,
+          versions,
+          latestVersion,
+          messages,
+        },
+      };
+    })
+  );
+
+  // order them by the name of the channel
+  processedChannels.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedChannels;
+  // console.timeEnd('✅ New getChannels');
+
+  return processedChannels;
+};
+
+// Could be recursive, we need to keep going until we find a loop or until we reach the target channel
+export const isChannelsConnected = (
+  sourceChannel: CollectionEntry<'channels'>,
+  targetChannel: CollectionEntry<'channels'>,
+  channels: CollectionEntry<'channels'>[],
+  visited: Set<string> = new Set()
+) => {
+  // Create a unique key for this channel (id + version to handle multiple versions)
+  const channelKey = `${sourceChannel.data.id}:${sourceChannel.data.version}`;
+
+  // Base case: we've reached the target channel
+  if (sourceChannel.data.id === targetChannel.data.id) {
+    return true;
+  }
+
+  // Prevent infinite loops by tracking visited channels
+  if (visited.has(channelKey)) {
+    return false;
+  }
+
+  // Mark this channel as visited
+  visited.add(channelKey);
+
+  const routes = sourceChannel.data.routes ?? [];
+  for (const route of routes) {
+    const routeChannel = getItemsFromCollectionByIdAndSemverOrLatest(
+      channels,
+      route.id,
+      route.version
+    )[0] as CollectionEntry<'channels'>;
+
+    if (routeChannel) {
+      // Pass the visited set to the recursive call
+      if (isChannelsConnected(routeChannel, targetChannel, channels, visited)) {
+        return true;
+      }
+    }
+  }
+  return false;
+};
+
+// Go from the source to the target channel and return the channel chain
+export const getChannelChain = (
+  sourceChannel: CollectionEntry<'channels'>,
+  targetChannel: CollectionEntry<'channels'>,
+  channels: CollectionEntry<'channels'>[]
+): CollectionEntry<'channels'>[] => {
+  // Base case: we've reached the target channel
+  if (sourceChannel.data.id === targetChannel.data.id && sourceChannel.data.version === targetChannel.data.version) {
+    return [sourceChannel];
+  }
+
+  const routes = sourceChannel.data.routes ?? [];
+
+  if (routes.length > 0 && isChannelsConnected(sourceChannel, targetChannel, channels)) {
+    // Need to check every route and see if any of them are connected to the target channel
+    for (const route of routes) {
+      const routeChannel = getItemsFromCollectionByIdAndSemverOrLatest(
+        channels,
+        route.id,
+        route.version
+      )[0] as CollectionEntry<'channels'>;
+      if (routeChannel) {
+        if (isChannelsConnected(routeChannel, targetChannel, channels)) {
+          return [sourceChannel, ...getChannelChain(routeChannel, targetChannel, channels)];
+        }
+      }
+    }
+  }
+  return [];
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/commands.ts b/packages/core/eventcatalog/src/utils/collections/commands.ts
new file mode 100644
index 000000000..aa961969f
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/commands.ts
@@ -0,0 +1,101 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { createVersionedMap } from './util';
+import { buildProducerConsumerIndex, lookupProducersAndConsumers } from './messages';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+
+type Command = CollectionEntry<'commands'>;
+
+interface Props {
+  getAllVersions?: boolean;
+  hydrateServices?: boolean;
+}
+
+// Simple in-memory cache
+let memoryCache: Record<string, Command[]> = {};
+
+export const getCommands = async ({ getAllVersions = true, hydrateServices = true }: Props = {}): Promise<Command[]> => {
+  // console.time('✅ New getCommands');
+  const cacheKey = `${getAllVersions ? 'allVersions' : 'currentVersions'}-${hydrateServices ? 'hydrated' : 'minimal'}`;
+
+  // Check cache
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0) {
+    // console.timeEnd('✅ New getCommands');
+    return memoryCache[cacheKey];
+  }
+
+  // 1. Fetch collections in parallel
+  const [allCommands, allAgents, allServices, allChannels, allDataProducts] = await Promise.all([
+    getCollection('commands'),
+    getCollection('agents'),
+    getCollection('services'),
+    getCollection('channels'),
+    getCollection('data-products'),
+  ]);
+
+  // 2. Build optimized maps
+  const commandMap = createVersionedMap(allCommands);
+  const pcIndex = buildProducerConsumerIndex(allAgents, allServices, allDataProducts);
+
+  // Build channel lookup map: channelId → channel entries
+  const channelById = new Map<string, typeof allChannels>();
+  for (const ch of allChannels) {
+    let list = channelById.get(ch.data.id);
+    if (!list) {
+      list = [];
+      channelById.set(ch.data.id, list);
+    }
+    list.push(ch);
+  }
+
+  // 3. Filter commands
+  const targetCommands = allCommands.filter((command) => {
+    if (command.data.hidden === true) return false;
+    if (!getAllVersions && command.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  // 4. Enrich commands
+  const processedCommands = await Promise.all(
+    targetCommands.map(async (command) => {
+      // Version info
+      const commandVersions = commandMap.get(command.data.id) || [];
+      const latestVersion = commandVersions[0]?.data.version || command.data.version;
+      const versions = commandVersions.map((e) => e.data.version);
+
+      // Find producers and consumers via reverse index
+      const { producers, consumers } = lookupProducersAndConsumers({
+        message: { data: { ...command.data, latestVersion } },
+        index: pcIndex,
+        hydrate: hydrateServices,
+      });
+
+      // Find Channels via map lookup
+      const messageChannels = command.data.channels || [];
+      const channelsForCommand = messageChannels.flatMap((channel) => channelById.get(channel.id) || []);
+
+      return {
+        ...command,
+        data: {
+          ...command.data,
+          messageChannels: channelsForCommand,
+          producers: producers as any,
+          consumers: consumers as any,
+          versions,
+          latestVersion,
+        },
+      };
+    })
+  );
+
+  // order them by the name of the command
+  processedCommands.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedCommands;
+  // console.timeEnd('✅ New getCommands');
+
+  return processedCommands;
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/containers.ts b/packages/core/eventcatalog/src/utils/collections/containers.ts
new file mode 100644
index 000000000..bddbd0fa2
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/containers.ts
@@ -0,0 +1,113 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { createVersionedMap, satisfies } from './util';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+export type Entity = CollectionEntry<'containers'>;
+
+interface Props {
+  getAllVersions?: boolean;
+}
+
+// cache for build time
+let memoryCache: Record<string, Entity[]> = {};
+
+export const getContainers = async ({ getAllVersions = true }: Props = {}): Promise<Entity[]> => {
+  // console.time('✅ New getContainers');
+  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
+
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    // console.timeEnd('✅ New getContainers');
+    return memoryCache[cacheKey];
+  }
+
+  // 1. Fetch collections in parallel
+  const [allContainers, allServices, allDataProducts] = await Promise.all([
+    getCollection('containers'),
+    getCollection('services'),
+    getCollection('data-products'),
+  ]);
+
+  // 2. Build optimized maps
+  const containerMap = createVersionedMap(allContainers);
+
+  // 3. Filter containers
+  const targetContainers = allContainers.filter((container) => {
+    if (container.data.hidden === true) return false;
+    if (!getAllVersions && container.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  // 4. Enrich containers
+  const processedContainers = await Promise.all(
+    targetContainers.map(async (container) => {
+      // Version info
+      const containerVersions = containerMap.get(container.data.id) || [];
+      const latestVersion = containerVersions[0]?.data.version || container.data.version;
+      const versions = containerVersions.map((c) => c.data.version);
+
+      // Find Services that write to this container
+      const servicesThatWriteToContainer = allServices.filter((service) => {
+        return service.data?.writesTo?.some((item) => {
+          if (item.id !== container.data.id) return false;
+          if (item.version === 'latest' || item.version === undefined) return container.data.version === latestVersion;
+          return satisfies(container.data.version, item.version);
+        });
+      });
+
+      // Find Services that read from this container
+      const servicesThatReadFromContainer = allServices.filter((service) => {
+        return service.data?.readsFrom?.some((item) => {
+          if (item.id !== container.data.id) return false;
+          if (item.version === 'latest' || item.version === undefined) return container.data.version === latestVersion;
+          return satisfies(container.data.version, item.version);
+        });
+      });
+
+      // Find Data Products that write to this container (have it in outputs)
+      const dataProductsThatWriteToContainer = allDataProducts.filter((dataProduct) => {
+        return dataProduct.data?.outputs?.some((item) => {
+          if (item.id !== container.data.id) return false;
+          if (item.version === 'latest' || item.version === undefined) return container.data.version === latestVersion;
+          return satisfies(container.data.version, item.version);
+        });
+      });
+
+      // Find Data Products that read from this container (have it in inputs)
+      const dataProductsThatReadFromContainer = allDataProducts.filter((dataProduct) => {
+        return dataProduct.data?.inputs?.some((item) => {
+          if (item.id !== container.data.id) return false;
+          if (item.version === 'latest' || item.version === undefined) return container.data.version === latestVersion;
+          return satisfies(container.data.version, item.version);
+        });
+      });
+
+      // Combine references
+      const servicesThatReferenceContainer = [...new Set([...servicesThatWriteToContainer, ...servicesThatReadFromContainer])];
+
+      return {
+        ...container,
+        data: {
+          ...container.data,
+          versions,
+          latestVersion,
+          services: servicesThatReferenceContainer,
+          servicesThatWriteToContainer,
+          servicesThatReadFromContainer,
+          dataProductsThatWriteToContainer,
+          dataProductsThatReadFromContainer,
+        },
+      };
+    })
+  );
+
+  // order them by the name of the container
+  processedContainers.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedContainers;
+  // console.timeEnd('✅ New getContainers');
+
+  return processedContainers;
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/data-products.ts b/packages/core/eventcatalog/src/utils/collections/data-products.ts
new file mode 100644
index 000000000..fa2508db1
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/data-products.ts
@@ -0,0 +1,71 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { createVersionedMap, satisfies } from './util';
+
+export type DataProduct = CollectionEntry<'data-products'>;
+
+interface Props {
+  getAllVersions?: boolean;
+}
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+
+// cache for build time
+let memoryCache: Record<string, DataProduct[]> = {};
+
+export const getDataProducts = async ({ getAllVersions = true }: Props = {}): Promise<DataProduct[]> => {
+  // console.time('✅ New getEntities');
+  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
+
+  if (CACHE_ENABLED && memoryCache[cacheKey] && memoryCache[cacheKey].length > 0) {
+    // console.timeEnd('✅ New getEntities');
+    return memoryCache[cacheKey];
+  }
+
+  // 1. Fetch collections in parallel
+  const [allDataProducts, allDomains] = await Promise.all([getCollection('data-products'), getCollection('domains')]);
+
+  // 2. Build optimized maps
+  const dataProductMap = createVersionedMap(allDataProducts);
+
+  // 3. Enrich data products
+  const processedDataProducts = await Promise.all(
+    allDataProducts.map(async (dataProduct) => {
+      // Version info
+      const dataProductVersions = dataProductMap.get(dataProduct.data.id) || [];
+      const latestVersion = dataProductVersions[0]?.data.version || dataProduct.data.version;
+      const versions = dataProductVersions.map((e) => e.data.version);
+
+      // Find Domains that reference this data product
+      const domainsThatReferenceDataProduct = allDomains.filter((domain) =>
+        domain.data['data-products']?.some((item) => {
+          if (item.id !== dataProduct.data.id) return false;
+          if (item.version === 'latest' || item.version === undefined) return dataProduct.data.version === latestVersion;
+          return satisfies(dataProduct.data.version, item.version);
+        })
+      );
+
+      return {
+        ...dataProduct,
+        data: {
+          ...dataProduct.data,
+          versions,
+          latestVersion,
+          domains: domainsThatReferenceDataProduct,
+        },
+      };
+    })
+  );
+
+  // order them by the name of the data product
+  processedDataProducts.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  if (CACHE_ENABLED) {
+    memoryCache[cacheKey] = processedDataProducts;
+  }
+  // console.timeEnd('✅ New getDataProducts');
+
+  return processedDataProducts as DataProduct[];
+};
diff --git a/eventcatalog/src/utils/collections/designs.ts b/packages/core/eventcatalog/src/utils/collections/designs.ts
similarity index 100%
rename from eventcatalog/src/utils/collections/designs.ts
rename to packages/core/eventcatalog/src/utils/collections/designs.ts
diff --git a/packages/core/eventcatalog/src/utils/collections/diagrams.ts b/packages/core/eventcatalog/src/utils/collections/diagrams.ts
new file mode 100644
index 000000000..71cb8630c
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/diagrams.ts
@@ -0,0 +1,57 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { createVersionedMap } from '@utils/collections/util';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+export type Diagram = CollectionEntry<'diagrams'>;
+
+interface Props {
+  getAllVersions?: boolean;
+}
+
+// Cache for build time
+let memoryCache: Record<string, Diagram[]> = {};
+
+export const getDiagrams = async ({ getAllVersions = true }: Props = {}): Promise<Diagram[]> => {
+  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
+
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    return memoryCache[cacheKey];
+  }
+
+  const allDiagrams = await getCollection('diagrams');
+
+  // Build optimized map for version lookups
+  const diagramMap = createVersionedMap(allDiagrams);
+
+  // Filter diagrams
+  const targetDiagrams = allDiagrams.filter((diagram) => {
+    if (!getAllVersions && diagram.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  // Enrich diagrams with version info
+  const processedDiagrams = targetDiagrams.map((diagram) => {
+    const diagramVersions = diagramMap.get(diagram.data.id) || [];
+    const latestVersion = diagramVersions[0]?.data.version || diagram.data.version;
+    const versions = diagramVersions.map((d) => d.data.version);
+
+    return {
+      ...diagram,
+      data: {
+        ...diagram.data,
+        versions,
+        latestVersion,
+      },
+    };
+  });
+
+  // Sort by name
+  processedDiagrams.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedDiagrams;
+
+  return processedDiagrams;
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/domains.ts b/packages/core/eventcatalog/src/utils/collections/domains.ts
new file mode 100644
index 000000000..8ae1f3430
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/domains.ts
@@ -0,0 +1,542 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import path from 'path';
+import type { CollectionMessageTypes } from '@types';
+import type { Agent, Service } from './types';
+import { createVersionedMap, findInMap, processSpecifications } from '@utils/collections/util';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+
+export type Domain = CollectionEntry<'domains'>;
+export type UbiquitousLanguage = CollectionEntry<'ubiquitousLanguages'>;
+
+interface Props {
+  getAllVersions?: boolean;
+  includeServicesInSubdomains?: boolean;
+  enrichServices?: boolean;
+}
+
+// Simple in-memory cache variable
+let memoryCache: Record<string, Domain[]> = {};
+
+// Helper to hydrate services
+const hydrateServices = (
+  servicesList: any[],
+  serviceMap: Map<string, any[]>,
+  messageMap: Map<string, any[]>,
+  containerMap: Map<string, any[]>
+) => {
+  return servicesList
+    .map((service: { id: string; version: string | undefined }) => findInMap(serviceMap, service.id, service.version))
+    .filter((s) => !!s)
+    .map((service) => {
+      // Hydrate service messages and containers
+      const sends = (service.data.sends || [])
+        .map((msg: any) => findInMap(messageMap, msg.id, msg.version))
+        .filter((m: any) => !!m);
+
+      const receives = (service.data.receives || [])
+        .map((msg: any) => findInMap(messageMap, msg.id, msg.version))
+        .filter((m: any) => !!m);
+
+      const readsFrom = (service.data.readsFrom || [])
+        .map((c: any) => findInMap(containerMap, c.id, c.version))
+        .filter((c: any) => !!c);
+
+      const writesTo = (service.data.writesTo || [])
+        .map((c: any) => findInMap(containerMap, c.id, c.version))
+        .filter((c: any) => !!c);
+
+      return {
+        ...service,
+        data: {
+          ...service.data,
+          sends: sends as any,
+          receives: receives as any,
+          readsFrom: readsFrom as any,
+          writesTo: writesTo as any,
+        },
+      };
+    });
+};
+
+const hydrateAgents = (
+  agentsList: any[],
+  agentMap: Map<string, any[]>,
+  messageMap: Map<string, any[]>,
+  containerMap: Map<string, any[]>
+) => {
+  return agentsList
+    .map((agent: { id: string; version: string | undefined }) => findInMap(agentMap, agent.id, agent.version))
+    .filter((a) => !!a)
+    .map((agent) => {
+      const sends = (agent.data.sends || [])
+        .map((msg: any) => findInMap(messageMap, msg.id, msg.version))
+        .filter((m: any) => !!m);
+
+      const receives = (agent.data.receives || [])
+        .map((msg: any) => findInMap(messageMap, msg.id, msg.version))
+        .filter((m: any) => !!m);
+
+      const readsFrom = (agent.data.readsFrom || [])
+        .map((c: any) => findInMap(containerMap, c.id, c.version))
+        .filter((c: any) => !!c);
+
+      const writesTo = (agent.data.writesTo || [])
+        .map((c: any) => findInMap(containerMap, c.id, c.version))
+        .filter((c: any) => !!c);
+
+      return {
+        ...agent,
+        data: {
+          ...agent.data,
+          sends: sends as any,
+          receives: receives as any,
+          readsFrom: readsFrom as any,
+          writesTo: writesTo as any,
+        },
+      };
+    });
+};
+
+// --- MAIN FUNCTION ---
+
+export const getDomains = async ({
+  getAllVersions = true,
+  includeServicesInSubdomains = true,
+  enrichServices = false,
+}: Props = {}): Promise<Domain[]> => {
+  // console.time('✅ New getDomains');
+
+  const cacheKey = `${getAllVersions ? 'allVersions' : 'currentVersions'}-${includeServicesInSubdomains ? 'true' : 'false'}-${enrichServices ? 'enriched' : 'simple'}`;
+
+  // Check cache
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    // console.timeEnd('✅ New getDomains');
+    return memoryCache[cacheKey];
+  }
+
+  // 1. Fetch collections (always fetch messages to hydrate domain-level sends/receives)
+  const [
+    allDomains,
+    allAgents,
+    allServices,
+    allEntities,
+    allFlows,
+    allSystems,
+    allEvents,
+    allCommands,
+    allQueries,
+    allContainers,
+    allDataProducts,
+  ] = await Promise.all([
+    getCollection('domains'),
+    getCollection('agents'),
+    getCollection('services'),
+    getCollection('entities'),
+    getCollection('flows'),
+    getCollection('systems'),
+    getCollection('events'),
+    getCollection('commands'),
+    getCollection('queries'),
+    getCollection('containers'),
+    getCollection('data-products'),
+  ]);
+
+  const allMessages = [...allEvents, ...allCommands, ...allQueries];
+  const messageMap = createVersionedMap(allMessages);
+  const containerMap = createVersionedMap(allContainers);
+
+  // 2. Build optimized maps
+  const domainMap = createVersionedMap(allDomains);
+  const agentMap = createVersionedMap(allAgents);
+  const serviceMap = createVersionedMap(allServices);
+  const entityMap = createVersionedMap(allEntities);
+  const flowMap = createVersionedMap(allFlows);
+  const systemMap = createVersionedMap(allSystems);
+  const dataProductMap = createVersionedMap(allDataProducts);
+
+  // 3. Filter the domains we actually want to process/return
+  const targetDomains = allDomains.filter((domain: Domain) => {
+    // Filter out hidden
+    if (domain.data.hidden === true) return false;
+    // Handle version filtering
+    if (!getAllVersions && domain.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  // 4. Process domains using Map lookups (O(1))
+  const processedDomains = await Promise.all(
+    targetDomains.map(async (domain: Domain) => {
+      // Get version info from the map
+      const domainVersions = domainMap.get(domain.data.id) || [];
+      const latestVersion = domainVersions[0]?.data.version || domain.data.version;
+      const versions = domainVersions.map((d) => d.data.version);
+
+      // Resolve Subdomains
+      const subDomainsInDomain = domain.data.domains || [];
+      const subDomains = subDomainsInDomain
+        .map((sd: { id: string; version: string | undefined }) => findInMap(domainMap, sd.id, sd.version))
+        .filter((sd): sd is Domain => !!sd && sd.data.id !== domain.data.id) // Filter nulls and self-refs
+        .map((subDomain: any) => {
+          // Hydrate services for the subdomain
+          let hydratedServices = subDomain.data.services || [];
+          let hydratedAgents = subDomain.data.agents || [];
+          if (enrichServices) {
+            hydratedServices = hydrateServices(subDomain.data.services || [], serviceMap, messageMap, containerMap);
+            hydratedAgents = hydrateAgents(subDomain.data.agents || [], agentMap, messageMap, containerMap);
+          } else {
+            // Just resolve the service objects without enrichment
+            hydratedServices = (subDomain.data.services || [])
+              .map((service: { id: string; version: string | undefined }) => findInMap(serviceMap, service.id, service.version))
+              .filter((s: any) => !!s);
+            hydratedAgents = (subDomain.data.agents || [])
+              .map((agent: { id: string; version: string | undefined }) => findInMap(agentMap, agent.id, agent.version))
+              .filter((a: any) => !!a);
+          }
+
+          // Hydrate data products for the subdomain
+          const subdomainDataProducts = (subDomain.data['data-products'] || [])
+            .map((dp: { id: string; version: string | undefined }) => findInMap(dataProductMap, dp.id, dp.version))
+            .filter((dp: any) => !!dp);
+
+          return {
+            ...subDomain,
+            data: {
+              ...subDomain.data,
+              services: hydratedServices as any,
+              agents: hydratedAgents as any,
+              'data-products': subdomainDataProducts as any,
+            },
+          };
+        });
+
+      // Resolve Entities
+      const entitiesInDomain = domain.data.entities || [];
+      const entities = entitiesInDomain
+        .map((entity: { id: string; version: string | undefined }) => findInMap(entityMap, entity.id, entity.version))
+        .filter((e): e is CollectionEntry<'entities'> => !!e);
+
+      // Resolve Flows
+      const flowsInDomain = domain.data.flows || [];
+      const flows = flowsInDomain
+        .map((flow: { id: string; version: string | undefined }) => findInMap(flowMap, flow.id, flow.version))
+        .filter((f): f is CollectionEntry<'flows'> => !!f);
+
+      // Resolve Systems (and hydrate each system's services so they can be
+      // rendered in the domain's architecture view, like subdomains)
+      const systemsInDomain = domain.data.systems || [];
+      const systems = systemsInDomain
+        .map((system: { id: string; version: string | undefined }) => findInMap(systemMap, system.id, system.version))
+        .filter((s): s is CollectionEntry<'systems'> => !!s)
+        .map((system: any) => {
+          const systemServices = enrichServices
+            ? hydrateServices(system.data.services || [], serviceMap, messageMap, containerMap)
+            : (system.data.services || [])
+                .map((service: { id: string; version: string | undefined }) => findInMap(serviceMap, service.id, service.version))
+                .filter((s: any) => !!s);
+
+          // Hydrate the system's data stores (containers) so they can be
+          // rendered in the domain's architecture view.
+          const systemContainers = (system.data.containers || [])
+            .map((container: { id: string; version: string | undefined }) =>
+              findInMap(containerMap, container.id, container.version)
+            )
+            .filter((c: any) => !!c);
+
+          return {
+            ...system,
+            data: {
+              ...system.data,
+              services: systemServices as any,
+              containers: systemContainers as any,
+            },
+          };
+        });
+
+      // Resolve Data Products
+      const dataProductsInDomain = domain.data['data-products'] || [];
+      const dataProducts = dataProductsInDomain
+        .map((dataProduct: { id: string; version: string | undefined }) =>
+          findInMap(dataProductMap, dataProduct.id, dataProduct.version)
+        )
+        .filter((dp): dp is CollectionEntry<'data-products'> => !!dp);
+
+      // Resolve Services for Main Domain
+      const servicesInDomain = domain.data.services || [];
+      const agentsInDomain = domain.data.agents || [];
+
+      // Hydrate main domain services
+      let hydratedMainServices = [];
+      let hydratedMainAgents = [];
+      if (enrichServices) {
+        hydratedMainServices = hydrateServices(servicesInDomain, serviceMap, messageMap, containerMap);
+        hydratedMainAgents = hydrateAgents(agentsInDomain, agentMap, messageMap, containerMap);
+      } else {
+        hydratedMainServices = servicesInDomain
+          .map((service: { id: string; version: string | undefined }) => findInMap(serviceMap, service.id, service.version))
+          .filter((s) => !!s);
+        hydratedMainAgents = agentsInDomain
+          .map((agent: { id: string; version: string | undefined }) => findInMap(agentMap, agent.id, agent.version))
+          .filter((a) => !!a);
+      }
+
+      // Get already-hydrated subdomain services
+      const hydratedSubdomainServices = subDomains.flatMap((subDomain: any) => subDomain.data.services || []);
+      const hydratedSubdomainAgents = subDomains.flatMap((subDomain: any) => subDomain.data.agents || []);
+
+      const services = includeServicesInSubdomains
+        ? [...(hydratedMainServices as any), ...(hydratedSubdomainServices as any)]
+        : (hydratedMainServices as any);
+      const agents = includeServicesInSubdomains
+        ? [...(hydratedMainAgents as any), ...(hydratedSubdomainAgents as any)]
+        : (hydratedMainAgents as any);
+
+      // Hydrate domain-level sends and receives
+      const domainSends = (domain.data.sends || [])
+        .map((m: { id: string; version: string | undefined }) => findInMap(messageMap, m.id, m.version))
+        .filter((e): e is CollectionEntry<CollectionMessageTypes> => !!e);
+
+      const domainReceives = (domain.data.receives || [])
+        .map((m: { id: string; version: string | undefined }) => findInMap(messageMap, m.id, m.version))
+        .filter((e): e is CollectionEntry<CollectionMessageTypes> => !!e);
+
+      return {
+        ...domain,
+        data: {
+          ...domain.data,
+          agents: agents as any,
+          services: services as any, // Cast to avoid deep type issues with enriched data
+          domains: subDomains as any,
+          systems: systems as any,
+          entities: entities as any,
+          flows: flows as any,
+          'data-products': dataProducts as any,
+          sends: domainSends as any,
+          receives: domainReceives as any,
+          latestVersion,
+          versions,
+        },
+      };
+    })
+  );
+
+  // Sort by name
+  processedDomains.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  // Cache result
+  memoryCache[cacheKey] = processedDomains;
+
+  // console.timeEnd('✅ New getDomains');
+
+  return processedDomains;
+};
+
+export const getMessagesForDomain = async (
+  domain: Domain
+): Promise<{ sends: CollectionEntry<CollectionMessageTypes>[]; receives: CollectionEntry<CollectionMessageTypes>[] }> => {
+  // We already have the services from the domain
+  const services = domain.data.services as unknown as CollectionEntry<'services'>[];
+  const agents = ((domain.data.agents as unknown as CollectionEntry<'agents'>[]) || []) as CollectionEntry<'agents'>[];
+
+  const [events, commands, queries] = await Promise.all([
+    getCollection('events'),
+    getCollection('commands'),
+    getCollection('queries'),
+  ]);
+
+  const allMessages = [...events, ...commands, ...queries];
+  const messageMap = createVersionedMap(allMessages);
+
+  // Get service-level sends/receives
+  const serviceSends = services.flatMap((service) => service.data.sends || []);
+  const serviceReceives = services.flatMap((service) => service.data.receives || []);
+  const agentSends = agents.flatMap((agent) => agent.data.sends || []);
+  const agentReceives = agents.flatMap((agent) => agent.data.receives || []);
+
+  // Get domain-level sends/receives (already hydrated if domain came from getDomains)
+  const domainSends = domain.data.sends || [];
+  const domainReceives = domain.data.receives || [];
+
+  // Combine and deduplicate - domain-level messages take priority
+  const allSends = [...domainSends, ...serviceSends, ...agentSends];
+  const allReceives = [...domainReceives, ...serviceReceives, ...agentReceives];
+
+  const sendsMessages = allSends
+    .map((send: any) => {
+      // If already hydrated (has data property), return as-is
+      if (send.data) return send;
+      // Otherwise, resolve from map
+      return findInMap(messageMap, send.id, send.version);
+    })
+    .filter((msg): msg is CollectionEntry<CollectionMessageTypes> => !!msg);
+
+  const receivesMessages = allReceives
+    .map((receive: any) => {
+      // If already hydrated (has data property), return as-is
+      if (receive.data) return receive;
+      // Otherwise, resolve from map
+      return findInMap(messageMap, receive.id, receive.version);
+    })
+    .filter((msg): msg is CollectionEntry<CollectionMessageTypes> => !!msg);
+
+  // Deduplicate by id and version
+  const uniqueSends = Array.from(new Map(sendsMessages.map((msg) => [`${msg.data.id}-${msg.data.version}`, msg])).values());
+  const uniqueReceives = Array.from(new Map(receivesMessages.map((msg) => [`${msg.data.id}-${msg.data.version}`, msg])).values());
+
+  return {
+    sends: uniqueSends,
+    receives: uniqueReceives,
+  };
+};
+
+export const getUbiquitousLanguage = async (domain: Domain): Promise<UbiquitousLanguage[]> => {
+  const ubiquitousLanguages = await getCollection('ubiquitousLanguages', (ubiquitousLanguage: UbiquitousLanguage) => {
+    const domainFolder = path.dirname(domain.filePath || '');
+    const ubiquitousLanguageFolder = path.dirname(ubiquitousLanguage.filePath || '');
+    return domainFolder === ubiquitousLanguageFolder;
+  });
+
+  return ubiquitousLanguages;
+};
+
+export const hasUbiquitousLanguageTerms = (ubiquitousLanguage: UbiquitousLanguage | null | undefined): boolean =>
+  (ubiquitousLanguage?.data?.dictionary?.length || 0) > 0;
+
+export const getUbiquitousLanguageFromCollection = (
+  domain: Domain,
+  ubiquitousLanguages: UbiquitousLanguage[]
+): UbiquitousLanguage[] => {
+  const domainFolder = path.dirname(domain.filePath || '');
+
+  return ubiquitousLanguages.filter((ubiquitousLanguage) => {
+    const ubiquitousLanguageFolder = path.dirname(ubiquitousLanguage.filePath || '');
+    return domainFolder === ubiquitousLanguageFolder;
+  });
+};
+
+export const hasUbiquitousLanguageTermsInCollection = (domain: Domain, ubiquitousLanguages: UbiquitousLanguage[]): boolean =>
+  getUbiquitousLanguageFromCollection(domain, ubiquitousLanguages).some(hasUbiquitousLanguageTerms);
+
+export const hasUbiquitousLanguageTermsWithSubdomainsInCollection = (
+  domain: Domain,
+  ubiquitousLanguages: UbiquitousLanguage[]
+): boolean => {
+  const subdomains = (domain.data.domains as unknown as Domain[]) || [];
+
+  return (
+    hasUbiquitousLanguageTermsInCollection(domain, ubiquitousLanguages) ||
+    subdomains.some((subdomain) => hasUbiquitousLanguageTermsInCollection(subdomain, ubiquitousLanguages))
+  );
+};
+
+export const getUbiquitousLanguageWithSubdomains = async (
+  domain: Domain
+): Promise<{
+  domain: UbiquitousLanguage | null;
+  subdomains: Array<{ subdomain: Domain; ubiquitousLanguage: UbiquitousLanguage | null }>;
+  duplicateTerms: Set<string>;
+}> => {
+  // Get domain's own ubiquitous language
+  const domainUbiquitousLanguage = await getUbiquitousLanguage(domain);
+  const domainUL = domainUbiquitousLanguage[0] || null;
+
+  // Get all subdomains
+  const subdomains = (domain.data.domains as unknown as Domain[]) || [];
+
+  // Get ubiquitous language for each subdomain
+  const subdomainULs = await Promise.all(
+    subdomains.map(async (subdomain) => {
+      const subdomainUL = await getUbiquitousLanguage(subdomain);
+      return {
+        subdomain,
+        ubiquitousLanguage: subdomainUL[0] || null,
+      };
+    })
+  );
+
+  // Find duplicate terms across domain and subdomains
+  const duplicateTerms = new Set<string>();
+  const termCounts = new Map<string, number>();
+
+  // Count terms from domain
+  if (domainUL?.data?.dictionary) {
+    domainUL.data.dictionary.forEach((term) => {
+      const termName = term.name.toLowerCase();
+      termCounts.set(termName, (termCounts.get(termName) || 0) + 1);
+    });
+  }
+
+  // Count terms from subdomains
+  subdomainULs.forEach(({ ubiquitousLanguage }) => {
+    if (ubiquitousLanguage?.data?.dictionary) {
+      ubiquitousLanguage.data.dictionary.forEach((term) => {
+        const termName = term.name.toLowerCase();
+        termCounts.set(termName, (termCounts.get(termName) || 0) + 1);
+      });
+    }
+  });
+
+  // Identify duplicates
+  termCounts.forEach((count, termName) => {
+    if (count > 1) {
+      duplicateTerms.add(termName);
+    }
+  });
+
+  return {
+    domain: domainUL,
+    subdomains: subdomainULs,
+    duplicateTerms,
+  };
+};
+
+export const hasUbiquitousLanguageTermsWithSubdomains = async (domain: Domain): Promise<boolean> => {
+  const { domain: domainUbiquitousLanguage, subdomains } = await getUbiquitousLanguageWithSubdomains(domain);
+
+  return (
+    hasUbiquitousLanguageTerms(domainUbiquitousLanguage) ||
+    subdomains.some(({ ubiquitousLanguage }) => hasUbiquitousLanguageTerms(ubiquitousLanguage))
+  );
+};
+
+export const getParentDomains = async (domain: Domain): Promise<Domain[]> => {
+  const domains = await getDomains({ getAllVersions: false });
+  return domains.filter((d) => {
+    const subDomains = (d.data.domains as unknown as Domain[]) || [];
+    return subDomains.some((d) => d.data.id === domain.data.id);
+  });
+};
+
+// Only return domains that are not found any any subdomain configuration
+export const getRootDomains = async (): Promise<Domain[]> => {
+  const domains = await getDomains({ getAllVersions: false });
+  const allSubDomains = domains.flatMap((d) => d.data.domains as unknown as Domain[]);
+  return domains.filter((d) => !allSubDomains.some((sd) => sd.data.id === d.data.id));
+};
+
+export const getDomainsForService = async (service: Service): Promise<Domain[]> => {
+  const domains = await getDomains({ getAllVersions: false });
+  return domains.filter((d) => {
+    const services = d.data.services as unknown as Service[];
+    return services.some((s) => s.data.id === service.data.id);
+  });
+};
+
+export const getDomainsForAgent = async (agent: Agent): Promise<Domain[]> => {
+  const domains = await getDomains({ getAllVersions: false });
+  return domains.filter((d) => {
+    const agents = ((d.data.agents as unknown as Agent[]) || []) as Agent[];
+    return agents.some((a) => a.data.id === agent.data.id);
+  });
+};
+
+export const domainHasEntities = (domain: Domain): boolean => {
+  return (domain.data.entities && domain.data.entities.length > 0) || false;
+};
+
+export const getSpecificationsForDomain = (domain: Domain) => {
+  return processSpecifications(domain.data.specifications as any);
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/entities.ts b/packages/core/eventcatalog/src/utils/collections/entities.ts
new file mode 100644
index 000000000..d2350eab0
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/entities.ts
@@ -0,0 +1,90 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { createVersionedMap, satisfies } from './util';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+
+export type Entity = CollectionEntry<'entities'>;
+
+interface Props {
+  getAllVersions?: boolean;
+}
+
+// cache for build time
+let memoryCache: Record<string, Entity[]> = {};
+
+export const getEntities = async ({ getAllVersions = true }: Props = {}): Promise<Entity[]> => {
+  // console.time('✅ New getEntities');
+  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
+
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    // console.timeEnd('✅ New getEntities');
+    return memoryCache[cacheKey];
+  }
+
+  // 1. Fetch collections in parallel
+  const [allEntities, allServices, allDomains] = await Promise.all([
+    getCollection('entities'),
+    getCollection('services'),
+    getCollection('domains'),
+  ]);
+
+  // 2. Build optimized maps
+  const entityMap = createVersionedMap(allEntities);
+
+  // 3. Filter entities
+  const targetEntities = allEntities.filter((entity) => {
+    if (entity.data.hidden === true) return false;
+    if (!getAllVersions && entity.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  // 4. Enrich entities
+  const processedEntities = await Promise.all(
+    targetEntities.map(async (entity) => {
+      // Version info
+      const entityVersions = entityMap.get(entity.data.id) || [];
+      const latestVersion = entityVersions[0]?.data.version || entity.data.version;
+      const versions = entityVersions.map((e) => e.data.version);
+
+      // Find Services that reference this entity
+      const servicesThatReferenceEntity = allServices.filter((service) =>
+        service.data.entities?.some((item) => {
+          if (item.id !== entity.data.id) return false;
+          if (item.version === 'latest' || item.version === undefined) return entity.data.version === latestVersion;
+          return satisfies(entity.data.version, item.version);
+        })
+      );
+
+      // Find Domains that reference this entity
+      const domainsThatReferenceEntity = allDomains.filter((domain) =>
+        domain.data.entities?.some((item) => {
+          if (item.id !== entity.data.id) return false;
+          if (item.version === 'latest' || item.version === undefined) return entity.data.version === latestVersion;
+          return satisfies(entity.data.version, item.version);
+        })
+      );
+
+      return {
+        ...entity,
+        data: {
+          ...entity.data,
+          versions,
+          latestVersion,
+          services: servicesThatReferenceEntity,
+          domains: domainsThatReferenceEntity,
+        },
+      };
+    })
+  );
+
+  // order them by the name of the entity
+  processedEntities.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedEntities;
+  // console.timeEnd('✅ New getEntities');
+
+  return processedEntities;
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/events.ts b/packages/core/eventcatalog/src/utils/collections/events.ts
new file mode 100644
index 000000000..ae202ae3b
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/events.ts
@@ -0,0 +1,101 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { createVersionedMap } from './util';
+import { buildProducerConsumerIndex, lookupProducersAndConsumers } from './messages';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+
+type Event = CollectionEntry<'events'>;
+
+interface Props {
+  getAllVersions?: boolean;
+  hydrateServices?: boolean;
+}
+
+// Simple in-memory cache
+let memoryCache: Record<string, Event[]> = {};
+
+export const getEvents = async ({ getAllVersions = true, hydrateServices = true }: Props = {}): Promise<Event[]> => {
+  // console.time('✅ New getEvents');
+  const cacheKey = `${getAllVersions ? 'allVersions' : 'currentVersions'}-${hydrateServices ? 'hydrated' : 'minimal'}`;
+
+  // Check cache
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    // console.timeEnd('✅ New getEvents');
+    return memoryCache[cacheKey];
+  }
+
+  // 1. Fetch collections in parallel
+  const [allEvents, allAgents, allServices, allChannels, allDataProducts] = await Promise.all([
+    getCollection('events'),
+    getCollection('agents'),
+    getCollection('services'),
+    getCollection('channels'),
+    getCollection('data-products'),
+  ]);
+
+  // 2. Build optimized maps
+  const eventMap = createVersionedMap(allEvents);
+  const pcIndex = buildProducerConsumerIndex(allAgents, allServices, allDataProducts);
+
+  // Build channel lookup map: channelId → channel entries
+  const channelById = new Map<string, typeof allChannels>();
+  for (const ch of allChannels) {
+    let list = channelById.get(ch.data.id);
+    if (!list) {
+      list = [];
+      channelById.set(ch.data.id, list);
+    }
+    list.push(ch);
+  }
+
+  // 3. Filter events
+  const targetEvents = allEvents.filter((event) => {
+    if (event.data.hidden === true) return false;
+    if (!getAllVersions && event.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  // 4. Enrich events
+  const processedEvents = await Promise.all(
+    targetEvents.map(async (event) => {
+      // Version info
+      const eventVersions = eventMap.get(event.data.id) || [];
+      const latestVersion = eventVersions[0]?.data.version || event.data.version;
+      const versions = eventVersions.map((e) => e.data.version);
+
+      // Find producers and consumers via reverse index
+      const { producers, consumers } = lookupProducersAndConsumers({
+        message: { data: { ...event.data, latestVersion } },
+        index: pcIndex,
+        hydrate: hydrateServices,
+      });
+
+      // Find Channels via map lookup
+      const messageChannels = event.data.channels || [];
+      const channelsForEvent = messageChannels.flatMap((channel) => channelById.get(channel.id) || []);
+
+      return {
+        ...event,
+        data: {
+          ...event.data,
+          messageChannels: channelsForEvent,
+          producers: producers as any,
+          consumers: consumers as any,
+          versions,
+          latestVersion,
+        },
+      };
+    })
+  );
+
+  // order them by the name of the event
+  processedEvents.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedEvents;
+  // console.timeEnd('✅ New getEvents');
+
+  return processedEvents;
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/examples.ts b/packages/core/eventcatalog/src/utils/collections/examples.ts
new file mode 100644
index 000000000..8925db25d
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/examples.ts
@@ -0,0 +1,85 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { getResourceBasePath } from '@utils/resource-files';
+
+export interface MessageExample {
+  fileName: string;
+  title: string;
+  extension: string;
+  content: string;
+  summary?: string;
+  usage?: string;
+}
+
+interface ExampleConfig {
+  name?: string;
+  summary?: string;
+  usage?: string;
+}
+
+function loadConfig(examplesDir: string): Record<string, ExampleConfig> {
+  const yamlPath = path.join(examplesDir, 'examples.config.yaml');
+  const ymlPath = path.join(examplesDir, 'examples.config.yml');
+  const jsonPath = path.join(examplesDir, 'examples.config.json');
+
+  let configPath: string | null = null;
+  if (fs.existsSync(yamlPath)) configPath = yamlPath;
+  else if (fs.existsSync(ymlPath)) configPath = ymlPath;
+  else if (fs.existsSync(jsonPath)) configPath = jsonPath;
+
+  if (!configPath) return {};
+
+  const raw = fs.readFileSync(configPath, 'utf-8');
+  if (configPath.endsWith('.json')) {
+    return JSON.parse(raw) || {};
+  }
+  return (yaml.load(raw) as Record<string, ExampleConfig>) || {};
+}
+
+const CONFIG_FILES = ['examples.config.yaml', 'examples.config.yml', 'examples.config.json'];
+
+function collectFiles(dir: string, baseDir: string): Omit<MessageExample, 'summary' | 'usage'>[] {
+  const results: Omit<MessageExample, 'summary' | 'usage'>[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFiles(fullPath, baseDir));
+    } else if (entry.isFile() && !CONFIG_FILES.includes(entry.name)) {
+      results.push({
+        fileName: path.relative(baseDir, fullPath),
+        title: path.parse(entry.name).name,
+        extension: path.parse(entry.name).ext.slice(1),
+        content: fs.readFileSync(fullPath, 'utf-8'),
+      });
+    }
+  }
+
+  return results;
+}
+
+export function getExamplesForResource(resource: { filePath?: string }): MessageExample[] {
+  const basePath = getResourceBasePath(resource);
+  if (!basePath) return [];
+
+  const examplesDir = path.join(basePath, 'examples');
+  if (!fs.existsSync(examplesDir)) return [];
+
+  const config = loadConfig(examplesDir);
+  const files = collectFiles(examplesDir, examplesDir);
+
+  return files
+    .map((file) => {
+      const key = file.fileName.replace(/\\/g, '/');
+      const meta = config[key] || {};
+      return {
+        ...file,
+        title: meta.name || file.title,
+        summary: meta.summary,
+        usage: meta.usage,
+      };
+    })
+    .sort((a, b) => a.fileName.localeCompare(b.fileName));
+}
diff --git a/packages/core/eventcatalog/src/utils/collections/flows.ts b/packages/core/eventcatalog/src/utils/collections/flows.ts
new file mode 100644
index 000000000..8b6c195d3
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/flows.ts
@@ -0,0 +1,148 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { createVersionedMap, findInMap } from '@utils/collections/util';
+import { getDomains } from './domains';
+import { getServices } from './services';
+import { getAgents } from './agents';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+export type Flow = CollectionEntry<'flows'>;
+
+interface Props {
+  getAllVersions?: boolean;
+}
+
+// Cache for build time
+let memoryCache: Record<string, Flow[]> = {};
+
+export const getFlows = async ({ getAllVersions = true }: Props = {}): Promise<Flow[]> => {
+  // console.time('✅ New getFlows');
+  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
+
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    // console.timeEnd('✅ New getFlows');
+    return memoryCache[cacheKey];
+  }
+
+  // 1. Fetch collections in parallel
+  const [allFlows, allEvents, allCommands, allQueries, allAgents, allContainers, allDataProducts] = await Promise.all([
+    getCollection('flows'),
+    getCollection('events'),
+    getCollection('commands'),
+    getCollection('queries'),
+    getCollection('agents'),
+    getCollection('containers'),
+    getCollection('data-products'),
+  ]);
+
+  const allMessages = [...allEvents, ...allCommands, ...allQueries];
+
+  // 2. Build optimized maps
+  const flowMap = createVersionedMap(allFlows);
+  const messageMap = createVersionedMap(allMessages);
+  const agentMap = createVersionedMap(allAgents);
+  const containerMap = createVersionedMap(allContainers);
+  const dataProductMap = createVersionedMap(allDataProducts);
+
+  // 3. Filter flows
+  const targetFlows = allFlows.filter((flow) => {
+    if (flow.data.hidden === true) return false;
+    if (!getAllVersions && flow.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  // 4. Enrich flows
+  const processedFlows = targetFlows.map((flow) => {
+    // Version info
+    const flowVersions = flowMap.get(flow.data.id) || [];
+    const latestVersion = flowVersions[0]?.data.version || flow.data.version;
+    const versions = flowVersions.map((f) => f.data.version);
+
+    const steps = flow.data.steps || [];
+
+    const hydrateSteps = steps.map((step) => {
+      if (step.container) {
+        const pointer = step.container;
+        if (!pointer) return { ...step, type: 'node' };
+        const container = findInMap(containerMap, pointer.id, pointer.version);
+
+        return {
+          ...step,
+          type: 'container',
+          container: container ? [container] : [],
+        };
+      }
+
+      if (step.dataProduct) {
+        const pointer = step.dataProduct;
+        if (!pointer) return { ...step, type: 'node' };
+        const dataProduct = findInMap(dataProductMap, pointer.id, pointer.version);
+
+        return {
+          ...step,
+          type: 'data-products',
+          dataProduct: dataProduct ? [dataProduct] : [],
+        };
+      }
+
+      if (step.agent) {
+        const pointer = step.agent;
+        if (!pointer) return { ...step, type: 'node' };
+        const agent = findInMap(agentMap, pointer.id, pointer.version);
+
+        return {
+          ...step,
+          type: 'agents',
+          agent: agent ? [agent] : [],
+        };
+      }
+
+      if (!step.message) return { ...step, type: 'node' }; // Preserve existing step data for non-messages
+
+      const message = findInMap(messageMap, step.message.id, step.message.version);
+
+      return {
+        ...step,
+        type: 'message',
+        message: message ? [message] : [], // Keep array structure for compatibility
+      };
+    });
+
+    return {
+      ...flow,
+      data: {
+        ...flow.data,
+        steps: hydrateSteps as any, // Cast to match expected Flow step type
+        versions,
+        latestVersion,
+      },
+    };
+  });
+
+  // order them by the name of the flow
+  processedFlows.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedFlows;
+  // console.timeEnd('✅ New getFlows');
+
+  return processedFlows;
+};
+
+export const getFlowsNotInAnyResource = async (): Promise<Flow[]> => {
+  const [flows, domains, services, agents] = await Promise.all([
+    getFlows({ getAllVersions: false }),
+    getDomains({ getAllVersions: false }),
+    getServices({ getAllVersions: false }),
+    getAgents({ getAllVersions: false }),
+  ]);
+
+  const flowsNotInAnyResource = flows.filter((flow) => {
+    const domainsForFlow = domains.filter((domain) => domain.data.flows?.some((f: any) => f.id === flow.id));
+    const servicesForFlow = services.filter((service) => service.data.flows?.some((f: any) => f.id === flow.id));
+    const agentsForFlow = agents.filter((agent) => agent.data.flows?.some((f: any) => f.id === flow.id));
+    return domainsForFlow.length === 0 && servicesForFlow.length === 0 && agentsForFlow.length === 0;
+  });
+  return flowsNotInAnyResource;
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/glob-loader.ts b/packages/core/eventcatalog/src/utils/collections/glob-loader.ts
new file mode 100644
index 000000000..86c0f0d4e
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/glob-loader.ts
@@ -0,0 +1,70 @@
+import { glob } from 'astro/loaders';
+import picomatch from 'picomatch';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+export type GlobOptions = Parameters<typeof glob>[0];
+
+export const withIgnoredBuildArtifacts = (patterns: string | string[]) => {
+  if (process.env.IGNORE_BUILD_ARTIFACTS === 'true') {
+    const ignoredArtifacts = ['!dist/**', '!**/dist/**'];
+    return Array.isArray(patterns) ? [...patterns, ...ignoredArtifacts] : [patterns, ...ignoredArtifacts];
+  }
+  return patterns;
+};
+
+const toPatterns = (patterns: string | string[]) => (Array.isArray(patterns) ? patterns : [patterns]);
+
+const matchesGlobPattern = (entry: string, patterns: string | string[]) => {
+  const patternList = toPatterns(patterns);
+  const positivePatterns = patternList.filter((pattern) => !pattern.startsWith('!'));
+  const negativePatterns = patternList.filter((pattern) => pattern.startsWith('!')).map((pattern) => pattern.slice(1));
+
+  return picomatch.isMatch(entry, positivePatterns) && !picomatch.isMatch(entry, negativePatterns);
+};
+
+export const globWithSafeWatcher = (options: GlobOptions) => {
+  const loader = glob(options);
+
+  return {
+    ...loader,
+    load: async (context: Parameters<typeof loader.load>[0]) => {
+      if (process.env.EVENTCATALOG_DEV_MODE !== 'true' || !context.watcher) {
+        return loader.load(context);
+      }
+
+      let baseDir = options.base ? new URL(options.base, context.config.root) : context.config.root;
+      if (!baseDir.pathname.endsWith('/')) {
+        baseDir = new URL(`${baseDir.pathname}/`, baseDir);
+      }
+
+      const basePath = fileURLToPath(baseDir);
+      const watcher = new Proxy(context.watcher, {
+        get(target, property, receiver) {
+          if (property !== 'on') {
+            const value = Reflect.get(target, property, receiver);
+            return typeof value === 'function' ? value.bind(target) : value;
+          }
+
+          return (event: string, callback: (changedPath: string) => void) => {
+            if (!['add', 'change', 'unlink'].includes(event)) {
+              return target.on(event, callback);
+            }
+
+            return target.on(event, (changedPath: string) => {
+              const entry = path.relative(basePath, changedPath).split(path.sep).join('/');
+              if (!entry.startsWith('../') && matchesGlobPattern(entry, options.pattern)) {
+                callback(changedPath);
+              }
+            });
+          };
+        },
+      });
+
+      return loader.load({
+        ...context,
+        watcher,
+      });
+    },
+  };
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/icons.ts b/packages/core/eventcatalog/src/utils/collections/icons.ts
new file mode 100644
index 000000000..2b5442e58
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/icons.ts
@@ -0,0 +1,61 @@
+import {
+  ServerIcon,
+  RectangleGroupIcon,
+  BoltIcon,
+  ChatBubbleLeftIcon,
+  MagnifyingGlassIcon,
+  QueueListIcon,
+  UserGroupIcon,
+  UserIcon,
+  ArrowsRightLeftIcon,
+  VariableIcon,
+  CubeIcon,
+} from '@heroicons/react/24/outline';
+import { BookText, Bot, Box, ClipboardList, DatabaseIcon, Group } from 'lucide-react';
+import { getColorForCollection } from '@utils/collection-colors';
+
+export const getIconForCollection = (collection: string) => {
+  switch (collection) {
+    case 'domains':
+      return RectangleGroupIcon;
+    case 'systems':
+      return Group;
+    case 'agents':
+      return Bot;
+    case 'adrs':
+      return ClipboardList;
+    case 'services':
+      return ServerIcon;
+    case 'events':
+      return BoltIcon;
+    case 'commands':
+      return ChatBubbleLeftIcon;
+    case 'queries':
+      return MagnifyingGlassIcon;
+    case 'flows':
+      return QueueListIcon;
+    case 'teams':
+      return UserGroupIcon;
+    case 'users':
+      return UserIcon;
+    case 'channels':
+      return ArrowsRightLeftIcon;
+    case 'channels-parameter':
+      return VariableIcon;
+    case 'ubiquitousLanguages':
+      return BookText;
+    case 'entities':
+      return Box;
+    case 'containers':
+      return DatabaseIcon;
+    case 'data-products':
+      return CubeIcon;
+    default:
+      return ServerIcon;
+  }
+};
+
+export const getColorAndIconForCollection = (collection: string) => {
+  const icon = getIconForCollection(collection);
+  return { color: getColorForCollection(collection), Icon: icon };
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/messages.ts b/packages/core/eventcatalog/src/utils/collections/messages.ts
new file mode 100644
index 000000000..fcf41e9da
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/messages.ts
@@ -0,0 +1,242 @@
+// Exporting getCommands and getEvents directly
+import { getCommands } from '@utils/collections/commands';
+import { getEvents } from '@utils/collections/events';
+import { getQueries } from './queries';
+import type { CollectionEntry } from 'astro:content';
+import { satisfies } from './util';
+export { getCommands } from '@utils/collections/commands';
+export { getEvents } from '@utils/collections/events';
+
+interface Props {
+  getAllVersions?: boolean;
+  hydrateServices?: boolean;
+}
+
+interface HydrateProducersAndConsumersProps {
+  message: {
+    data: {
+      id: string;
+      version: string;
+      latestVersion?: string;
+    };
+  };
+  agents?: CollectionEntry<'agents'>[];
+  services: CollectionEntry<'services'>[];
+  dataProducts: CollectionEntry<'data-products'>[];
+  hydrate?: boolean;
+}
+
+/**
+ * Hydrates producers and consumers for a message (event, command, or query).
+ * Finds services and data products that produce or consume the given message.
+ */
+export const hydrateProducersAndConsumers = ({
+  message,
+  agents = [],
+  services = [],
+  dataProducts = [],
+  hydrate = true,
+}: HydrateProducersAndConsumersProps) => {
+  const { id: messageId, version: messageVersion, latestVersion = messageVersion } = message.data;
+
+  const matchesVersion = (pointerVersion: string | undefined) => {
+    if (pointerVersion === 'latest' || pointerVersion === undefined) {
+      return messageVersion === latestVersion;
+    }
+    return satisfies(messageVersion, pointerVersion);
+  };
+
+  const toResult = <T extends CollectionEntry<'agents'> | CollectionEntry<'services'> | CollectionEntry<'data-products'>>(
+    resource: T
+  ) => {
+    if (!hydrate) return { id: resource.data.id, version: resource.data.version };
+    return resource;
+  };
+
+  // Agents that send this message (producers)
+  const agentProducers = agents
+    .filter((a) => a.data.sends?.some((p) => p.id === messageId && matchesVersion(p.version)))
+    .map(toResult);
+
+  // Agents that receive this message (consumers)
+  const agentConsumers = agents
+    .filter((a) => a.data.receives?.some((p) => p.id === messageId && matchesVersion(p.version)))
+    .map(toResult);
+
+  // Services that send this message (producers)
+  const serviceProducers = services
+    .filter((s) => s.data.sends?.some((p) => p.id === messageId && matchesVersion(p.version)))
+    .map(toResult);
+
+  // Services that receive this message (consumers)
+  const serviceConsumers = services
+    .filter((s) => s.data.receives?.some((p) => p.id === messageId && matchesVersion(p.version)))
+    .map(toResult);
+
+  // Data products that output this message (producers)
+  const dataProductProducers = dataProducts
+    .filter((dp) => dp.data.outputs?.some((p) => p.id === messageId && matchesVersion(p.version)))
+    .map(toResult);
+
+  // Data products that input this message (consumers)
+  const dataProductConsumers = dataProducts
+    .filter((dp) => dp.data.inputs?.some((p) => p.id === messageId && matchesVersion(p.version)))
+    .map(toResult);
+
+  return {
+    producers: [...agentProducers, ...serviceProducers, ...dataProductProducers],
+    consumers: [...agentConsumers, ...serviceConsumers, ...dataProductConsumers],
+  };
+};
+
+// --- Reverse Index for O(1) producer/consumer lookups ---
+
+interface IndexEntry {
+  resource: CollectionEntry<'agents'> | CollectionEntry<'services'> | CollectionEntry<'data-products'>;
+  pointerVersion?: string;
+}
+
+export interface ProducerConsumerIndex {
+  producers: Map<string, IndexEntry[]>;
+  consumers: Map<string, IndexEntry[]>;
+}
+
+/**
+ * Builds a reverse index from message ID → services/data-products that send/receive it.
+ * Call once before the enrichment loop, then use lookupProducersAndConsumers per message.
+ */
+export const buildProducerConsumerIndex = (
+  agents: CollectionEntry<'agents'>[],
+  services: CollectionEntry<'services'>[],
+  dataProducts: CollectionEntry<'data-products'>[]
+): ProducerConsumerIndex => {
+  const producers = new Map<string, IndexEntry[]>();
+  const consumers = new Map<string, IndexEntry[]>();
+
+  const addEntry = (map: Map<string, IndexEntry[]>, messageId: string, entry: IndexEntry) => {
+    let list = map.get(messageId);
+    if (!list) {
+      list = [];
+      map.set(messageId, list);
+    }
+    list.push(entry);
+  };
+
+  for (const agent of agents || []) {
+    if (agent.data.sends) {
+      for (const p of agent.data.sends) {
+        addEntry(producers, p.id, { resource: agent, pointerVersion: p.version });
+      }
+    }
+    if (agent.data.receives) {
+      for (const p of agent.data.receives) {
+        addEntry(consumers, p.id, { resource: agent, pointerVersion: p.version });
+      }
+    }
+  }
+
+  for (const service of services || []) {
+    if (service.data.sends) {
+      for (const p of service.data.sends) {
+        addEntry(producers, p.id, { resource: service, pointerVersion: p.version });
+      }
+    }
+    if (service.data.receives) {
+      for (const p of service.data.receives) {
+        addEntry(consumers, p.id, { resource: service, pointerVersion: p.version });
+      }
+    }
+  }
+
+  for (const dp of dataProducts || []) {
+    if (dp.data.outputs) {
+      for (const p of dp.data.outputs) {
+        addEntry(producers, p.id, { resource: dp, pointerVersion: p.version });
+      }
+    }
+    if (dp.data.inputs) {
+      for (const p of dp.data.inputs) {
+        addEntry(consumers, p.id, { resource: dp, pointerVersion: p.version });
+      }
+    }
+  }
+
+  return { producers, consumers };
+};
+
+interface LookupProps {
+  message: {
+    data: {
+      id: string;
+      version: string;
+      latestVersion?: string;
+    };
+  };
+  index: ProducerConsumerIndex;
+  hydrate?: boolean;
+}
+
+/**
+ * Looks up producers and consumers for a message using the pre-built reverse index.
+ * Only runs version matching on the candidate set instead of all services.
+ */
+export const lookupProducersAndConsumers = ({ message, index, hydrate = true }: LookupProps) => {
+  const { id: messageId, version: messageVersion, latestVersion = messageVersion } = message.data;
+
+  const matchesVersion = (pointerVersion: string | undefined) => {
+    if (pointerVersion === 'latest' || pointerVersion === undefined) {
+      return messageVersion === latestVersion;
+    }
+    return satisfies(messageVersion, pointerVersion);
+  };
+
+  const toResult = <T extends CollectionEntry<'agents'> | CollectionEntry<'services'> | CollectionEntry<'data-products'>>(
+    resource: T
+  ) => {
+    if (!hydrate) return { id: resource.data.id, version: resource.data.version };
+    return resource;
+  };
+
+  const candidateProducers = index.producers.get(messageId) || [];
+  const candidateConsumers = index.consumers.get(messageId) || [];
+
+  const producers = candidateProducers.filter((e) => matchesVersion(e.pointerVersion)).map((e) => toResult(e.resource));
+
+  const consumers = candidateConsumers.filter((e) => matchesVersion(e.pointerVersion)).map((e) => toResult(e.resource));
+
+  return { producers, consumers };
+};
+
+type Messages = {
+  commands: CollectionEntry<'commands'>[];
+  events: CollectionEntry<'events'>[];
+  queries: CollectionEntry<'queries'>[];
+};
+
+export const pluralizeMessageType = (message: CollectionEntry<'events' | 'commands' | 'queries'>) => {
+  const typeMap: Record<string, string> = {
+    events: 'event',
+    commands: 'command',
+    queries: 'query',
+  };
+  return typeMap[message.collection] || 'message';
+};
+
+// Main function that uses the imported functions
+export const getMessages = async ({ getAllVersions = true, hydrateServices = true }: Props = {}): Promise<Messages> => {
+  const [commands, events, queries] = await Promise.all([
+    getCommands({ getAllVersions, hydrateServices }),
+    getEvents({ getAllVersions, hydrateServices }),
+    getQueries({ getAllVersions, hydrateServices }),
+  ]);
+
+  return {
+    commands,
+    events,
+    queries,
+  };
+};
+
+export const isCollectionAMessage = (collection: string): boolean => {
+  return ['events', 'commands', 'queries'].includes(collection);
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/owners.ts b/packages/core/eventcatalog/src/utils/collections/owners.ts
new file mode 100644
index 000000000..67afa2444
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/owners.ts
@@ -0,0 +1,79 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+
+const getOwners = (function () {
+  type Owners = CollectionEntry<'users' | 'teams'>;
+  let cachedOwners: Map<string, Owners> | null = null;
+  let initializingPromise: Promise<Map<string, Owners>> | null = null;
+
+  /**
+   * Initializes and caches the owners by fetching from the 'users' and 'teams' collections.
+   */
+  async function init() {
+    const ownersMap = new Map<string, CollectionEntry<'users' | 'teams'>>();
+
+    const owners = await Promise.all([
+      getCollection('users', (entry) => entry.data.hidden !== true),
+      getCollection('teams', (entry) => entry.data.hidden !== true),
+    ]);
+
+    for (const owner of owners.flat()) {
+      ownersMap.set(owner.data.id, owner);
+    }
+
+    cachedOwners = ownersMap;
+    initializingPromise = null;
+
+    return cachedOwners;
+  }
+
+  return () =>
+    cachedOwners || // Return cached owners if already initialized
+    initializingPromise || // Return the promise if initialization is in progress
+    (initializingPromise = init()); // Initialize if neither cache nor promise exists
+})();
+
+export async function getOwner(lookup: { id: string }): Promise<CollectionEntry<'users' | 'teams'> | undefined> {
+  const lookupId = typeof lookup === 'string' ? lookup : lookup.id;
+
+  const owner = (await getOwners()).get(lookupId);
+
+  if (!owner) console.warn(`Entry ${lookupId} not found in "teams"/"users" collections.`);
+
+  return owner;
+}
+
+export interface OwnerDetail {
+  id: string;
+  name: string;
+  type: 'users' | 'teams' | 'unknown';
+  role: string | undefined;
+}
+
+/**
+ * Resolves a list of raw owner references to detailed owner objects including type and role.
+ * Falls back to a minimal object with the raw ID if the owner cannot be found.
+ */
+export async function getOwnerDetails(rawOwners: (string | { id: string })[]): Promise<OwnerDetail[]> {
+  return Promise.all(
+    rawOwners.map(async (owner) => {
+      const ownerId = typeof owner === 'string' ? owner : owner.id;
+      const resolved = await getOwner({ id: ownerId });
+      if (!resolved) return { id: ownerId, name: ownerId, type: 'unknown' as const, role: undefined };
+      return {
+        id: resolved.data.id,
+        name: resolved.data.name,
+        type: resolved.collection as 'users' | 'teams',
+        role: resolved.collection === 'users' ? (resolved.data as any).role : (resolved.data as any).summary,
+      };
+    })
+  );
+}
+
+/**
+ * Resolves a list of raw owner references (string IDs or {id} objects) to their display names.
+ * Falls back to the raw ID if the owner cannot be found.
+ */
+export async function getOwnerNames(rawOwners: (string | { id: string })[]): Promise<string[]> {
+  const details = await getOwnerDetails(rawOwners);
+  return details.map((d) => d.name);
+}
diff --git a/packages/core/eventcatalog/src/utils/collections/queries.ts b/packages/core/eventcatalog/src/utils/collections/queries.ts
new file mode 100644
index 000000000..f49e2d7ce
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/queries.ts
@@ -0,0 +1,100 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { createVersionedMap } from './util';
+import { buildProducerConsumerIndex, lookupProducersAndConsumers } from './messages';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+
+type Query = CollectionEntry<'queries'>;
+
+interface Props {
+  getAllVersions?: boolean;
+  hydrateServices?: boolean;
+}
+
+// Cache for build time
+let memoryCache: Record<string, Query[]> = {};
+
+export const getQueries = async ({ getAllVersions = true, hydrateServices = true }: Props = {}): Promise<Query[]> => {
+  // console.time('✅ New getQueries');
+  const cacheKey = `${getAllVersions ? 'allVersions' : 'currentVersions'}-${hydrateServices ? 'hydrated' : 'minimal'}`;
+
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    // console.timeEnd('✅ New getQueries');
+    return memoryCache[cacheKey];
+  }
+
+  // 1. Fetch collections in parallel
+  const [allQueries, allAgents, allServices, allChannels, allDataProducts] = await Promise.all([
+    getCollection('queries'),
+    getCollection('agents'),
+    getCollection('services'),
+    getCollection('channels'),
+    getCollection('data-products'),
+  ]);
+
+  // 2. Build optimized maps
+  const queryMap = createVersionedMap(allQueries);
+  const pcIndex = buildProducerConsumerIndex(allAgents, allServices, allDataProducts);
+
+  // Build channel lookup map: channelId → channel entries
+  const channelById = new Map<string, typeof allChannels>();
+  for (const ch of allChannels) {
+    let list = channelById.get(ch.data.id);
+    if (!list) {
+      list = [];
+      channelById.set(ch.data.id, list);
+    }
+    list.push(ch);
+  }
+
+  // 3. Filter queries
+  const targetQueries = allQueries.filter((query) => {
+    if (query.data.hidden === true) return false;
+    if (!getAllVersions && query.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  // 4. Enrich queries
+  const processedQueries = await Promise.all(
+    targetQueries.map(async (query) => {
+      // Version info
+      const queryVersions = queryMap.get(query.data.id) || [];
+      const latestVersion = queryVersions[0]?.data.version || query.data.version;
+      const versions = queryVersions.map((e) => e.data.version);
+
+      // Find producers and consumers via reverse index
+      const { producers, consumers } = lookupProducersAndConsumers({
+        message: { data: { ...query.data, latestVersion } },
+        index: pcIndex,
+        hydrate: hydrateServices,
+      });
+
+      // Find Channels via map lookup
+      const messageChannels = query.data.channels || [];
+      const channelsForQuery = messageChannels.flatMap((channel) => channelById.get(channel.id) || []);
+
+      return {
+        ...query,
+        data: {
+          ...query.data,
+          messageChannels: channelsForQuery,
+          producers: producers as any,
+          consumers: consumers as any,
+          versions,
+          latestVersion,
+        },
+      };
+    })
+  );
+
+  // order them by the name of the query
+  processedQueries.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedQueries;
+  // console.timeEnd('✅ New getQueries');
+
+  return processedQueries;
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/resource-docs.ts b/packages/core/eventcatalog/src/utils/collections/resource-docs.ts
new file mode 100644
index 000000000..01718890f
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/resource-docs.ts
@@ -0,0 +1,13 @@
+// Re-export from enterprise. This module is subject to the EventCatalog Commercial License.
+// See /packages/core/eventcatalog/src/enterprise/LICENSE
+export {
+  getResourceDocs,
+  getResourceDocCategories,
+  getResourceDocCategoriesForResource,
+  getResourceDocsForResource,
+  getGroupedResourceDocsByType,
+  type ResourceCollection,
+  type ResourceDocEntry,
+  type ResourceDocCategoryEntry,
+  type ResourceDocGroup,
+} from '../../enterprise/collections/resource-docs-utils';
diff --git a/packages/core/eventcatalog/src/utils/collections/schema-loader.ts b/packages/core/eventcatalog/src/utils/collections/schema-loader.ts
new file mode 100644
index 000000000..369598cec
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/schema-loader.ts
@@ -0,0 +1,523 @@
+import type { Loader } from 'astro/loaders';
+import { glob } from 'glob';
+import matter from 'gray-matter';
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import pc from 'picocolors';
+import { isEventCatalogScaleEnabled } from '../feature';
+import { sortVersioned } from './util';
+
+const colors = pc.createColors(true);
+
+type MessageCollection = 'events' | 'commands' | 'queries';
+
+type SchemaReference = {
+  id?: string;
+  ref?: string;
+  file?: string;
+  path?: string;
+  name?: string;
+  format?: string;
+  environments?: string[];
+  default?: boolean;
+};
+
+type SchemaSourceEntry = {
+  provider: string;
+  id?: string;
+  path?: string;
+  url?: string;
+  ref?: string;
+  [key: string]: unknown;
+};
+
+type SchemaSource = {
+  type: 'schemas';
+  name: string;
+  canResolve: (ref: string) => boolean;
+  resolve: (
+    ref: string,
+    context?: { messageFilePath?: string }
+  ) => Promise<
+    | {
+        id: string;
+        name?: string;
+        format?: string;
+        content: string;
+        source: SchemaSourceEntry;
+      }
+    | undefined
+  >;
+};
+
+type MessageFrontmatter = {
+  id?: string;
+  name?: string;
+  version?: string;
+  summary?: string;
+  owners?: string[];
+  schemaPath?: string;
+  schemas?: SchemaReference[];
+};
+
+export type MessageSchemaResource = {
+  id: string;
+  schemaId?: string;
+  ref?: string;
+  name?: string;
+  version?: string;
+  format: string;
+  content?: string;
+  file?: string;
+  filePath?: string;
+  environments?: string[];
+  default?: boolean;
+  latest?: boolean;
+  message: {
+    collection: MessageCollection;
+    id: string;
+    name?: string;
+    version: string;
+    summary?: string;
+    owners?: string[];
+  };
+  source: {
+    provider: string;
+    id?: string;
+    path?: string;
+    url?: string;
+    ref?: string;
+    [key: string]: unknown;
+  };
+  readOnly?: boolean;
+};
+
+type InternalMessageSchemaResource = MessageSchemaResource & {
+  _context?: {
+    messageFilePath?: string;
+  };
+};
+
+type SchemaLoaderOptions = {
+  messages: {
+    pattern: string[];
+    base?: string;
+  };
+  sources?: SchemaSource[];
+};
+
+type LoaderContext = Parameters<Loader['load']>[0];
+
+const MESSAGE_COLLECTIONS: MessageCollection[] = ['events', 'commands', 'queries'];
+const FILE_SCHEMA_REF_PREFIX = 'file://';
+
+const normalizePath = (value: string) => value.replace(/\\/g, '/');
+
+const getMessageCollectionFromPath = (filePath: string): MessageCollection | undefined => {
+  const parts = normalizePath(filePath).split('/');
+  return MESSAGE_COLLECTIONS.find((collection) => parts.includes(collection));
+};
+
+const getSchemaFormat = (schemaPath: string) => {
+  const extension = path.extname(schemaPath).replace('.', '').toLowerCase();
+
+  if (extension === 'avsc' || extension === 'avro') return 'avro';
+  if (extension === 'proto') return 'protobuf';
+  if (extension === 'json') return 'jsonschema';
+  if (extension === 'yaml' || extension === 'yml') return 'yaml';
+
+  return extension || 'unknown';
+};
+
+const buildGeneratedSchemaId = (message: { collection: MessageCollection; id: string; version: string }, schemaPath: string) =>
+  `schema:${message.collection}:${message.id}:${message.version}:${schemaPath}`;
+
+const getSchemaCollectionId = ({
+  message,
+  reference,
+  schemaRef,
+  schemaFile,
+}: {
+  message: { collection: MessageCollection; id: string; version: string };
+  reference: SchemaReference;
+  schemaRef?: string;
+  schemaFile?: string;
+}) => {
+  if (schemaRef) return buildGeneratedSchemaId(message, schemaRef);
+  if (reference.id) return buildGeneratedSchemaId(message, reference.id);
+  return buildGeneratedSchemaId(message, schemaFile as string);
+};
+
+const getSchemaFile = (reference: SchemaReference) => reference.file ?? reference.path;
+
+const getSchemaRef = (reference: SchemaReference) => {
+  if (reference.ref) return reference.ref;
+  if (!getSchemaFile(reference)) return reference.id;
+  return undefined;
+};
+
+const getSchemaDisplayName = ({
+  referenceName,
+  resolvedName,
+  schemaFile,
+  filePath,
+  schemaRef,
+  sourcePath,
+  schemaId,
+  messageName,
+}: {
+  referenceName?: string;
+  resolvedName?: string;
+  schemaFile?: string;
+  filePath?: string;
+  schemaRef?: string;
+  sourcePath?: string;
+  schemaId: string;
+  messageName?: string;
+}) => {
+  const pathLikeName = schemaFile ?? filePath ?? sourcePath ?? schemaRef ?? schemaId;
+  return referenceName ?? resolvedName ?? path.basename(pathLikeName) ?? messageName ?? 'Schema';
+};
+
+const schemaFileExists = (schema: MessageSchemaResource): schema is MessageSchemaResource & { filePath: string } =>
+  Boolean(schema.filePath && fsSync.existsSync(schema.filePath));
+
+const getSchemaProvider = (id: string) => {
+  try {
+    const url = new URL(id);
+    return url.protocol.replace(':', '') || 'external';
+  } catch {
+    return 'external';
+  }
+};
+
+const isFileSchemaRef = (ref?: string) => ref?.startsWith(FILE_SCHEMA_REF_PREFIX);
+
+const getFileSchemaRefPath = (ref: string, messageFilePath: string) => {
+  if (ref.startsWith('file:///') || ref.startsWith('file://localhost/')) {
+    try {
+      const filePath = fileURLToPath(ref);
+      return {
+        filePath,
+        sourcePath: filePath,
+      };
+    } catch {
+      throw new Error(`Invalid file schema ref "${ref}". Expected file://<relative-path> or file:///absolute/path.`);
+    }
+  }
+
+  const sourcePath = decodeURIComponent(ref.slice(FILE_SCHEMA_REF_PREFIX.length));
+  if (!sourcePath) {
+    throw new Error(`Invalid file schema ref "${ref}". Expected file://<relative-path> or file:///absolute/path.`);
+  }
+
+  return {
+    filePath: path.resolve(path.dirname(messageFilePath), sourcePath),
+    sourcePath,
+  };
+};
+
+const getTimestamp = () => {
+  const now = new Date();
+  return now.toLocaleTimeString('en-US', { hour12: false });
+};
+
+const logSchemaInfo = (message: string) => {
+  console.log(`${colors.dim(getTimestamp())} ${colors.blue('[schemas]')} ${message}`);
+};
+
+const getMessageTypeLabel = (collection: MessageCollection) => {
+  if (collection === 'events') return 'event';
+  if (collection === 'commands') return 'command';
+  return 'query';
+};
+
+const getErrorMessage = (error: unknown) => {
+  return error instanceof Error ? error.message : String(error);
+};
+
+const getSchemaResolveRef = (schema: MessageSchemaResource) => schema.ref ?? schema.id;
+
+const buildSchemaSourceErrorMessage = ({
+  schema,
+  source,
+  error,
+}: {
+  schema: MessageSchemaResource;
+  source: SchemaSource;
+  error: unknown;
+}) => {
+  const messageType = getMessageTypeLabel(schema.message.collection);
+
+  return [
+    '',
+    colors.red(colors.bold('[schemas] Failed to resolve schema')),
+    '',
+    `  Message: ${messageType} "${schema.message.id}" version "${schema.message.version}"`,
+    `  Schema:  ${getSchemaResolveRef(schema)}`,
+    `  Source:  ${source.name}`,
+    '',
+    colors.bold('Reason:'),
+    `  ${getErrorMessage(error)}`,
+    '',
+  ].join('\n');
+};
+
+const addLatestMetadata = (schemas: MessageSchemaResource[]) => {
+  const schemasByMessage = schemas.reduce(
+    (acc, schema) => {
+      const key = `${schema.message.collection}:${schema.message.id}`;
+      acc[key] = [...(acc[key] ?? []), schema];
+      return acc;
+    },
+    {} as Record<string, MessageSchemaResource[]>
+  );
+
+  const latestVersionsByMessage = Object.entries(schemasByMessage).reduce(
+    (acc, [key, messageSchemas]) => {
+      acc[key] = sortVersioned(messageSchemas, (schema) => schema.message.version)[0]?.message.version;
+      return acc;
+    },
+    {} as Record<string, string | undefined>
+  );
+
+  return schemas.map((schema) => {
+    const key = `${schema.message.collection}:${schema.message.id}`;
+    return {
+      ...schema,
+      latest: schema.message.version === latestVersionsByMessage[key],
+    };
+  });
+};
+
+export const getMessageSchemasFromFrontmatter = ({
+  data,
+  collection,
+  messageFilePath,
+}: {
+  data: MessageFrontmatter;
+  collection: MessageCollection;
+  messageFilePath: string;
+}): MessageSchemaResource[] => {
+  if (!data.id || !data.version) return [];
+
+  const message = {
+    collection,
+    id: data.id,
+    name: data.name,
+    version: data.version,
+    summary: data.summary,
+    owners: data.owners,
+  };
+
+  const schemaReferences =
+    data.schemas?.filter((schema) => getSchemaRef(schema) || getSchemaFile(schema)) ??
+    (data.schemaPath
+      ? [
+          {
+            file: data.schemaPath,
+            name: 'Schema',
+            default: true,
+          },
+        ]
+      : []);
+
+  return schemaReferences.map((reference) => {
+    const schemaFile = getSchemaFile(reference);
+    const schemaRef = getSchemaRef(reference);
+    const fileSchemaRef = isFileSchemaRef(schemaRef) ? getFileSchemaRefPath(schemaRef as string, messageFilePath) : undefined;
+    const schemaFilePath = schemaFile ? path.resolve(path.dirname(messageFilePath), schemaFile) : fileSchemaRef?.filePath;
+    const schemaId = getSchemaCollectionId({ message, reference, schemaRef, schemaFile });
+    const schemaPathForFormat = schemaFile ?? fileSchemaRef?.filePath;
+
+    return {
+      id: schemaId,
+      ...(reference.id && !schemaRef ? { schemaId: reference.id } : {}),
+      ...(schemaRef ? { ref: schemaRef } : {}),
+      name: getSchemaDisplayName({
+        referenceName: reference.name,
+        schemaFile,
+        filePath: fileSchemaRef?.filePath,
+        schemaRef,
+        schemaId,
+        messageName: data.name,
+      }),
+      version: data.version,
+      format: reference.format ?? (schemaPathForFormat ? getSchemaFormat(schemaPathForFormat) : 'unknown'),
+      file: schemaFile,
+      filePath: schemaFilePath,
+      environments: reference.environments,
+      default: reference.default,
+      message,
+      source: {
+        provider: schemaFile || fileSchemaRef ? 'file' : getSchemaProvider(schemaRef ?? schemaId),
+        path: schemaFile ?? fileSchemaRef?.sourcePath,
+      },
+    };
+  });
+};
+
+const resolveSchemaSource = async (
+  schema: InternalMessageSchemaResource,
+  source: SchemaSource
+): Promise<InternalMessageSchemaResource | undefined> => {
+  if (schemaFileExists(schema)) return schema;
+  if (schema.filePath) return undefined;
+
+  let resolvedSchema: Awaited<ReturnType<SchemaSource['resolve']>>;
+  const schemaResolveRef = getSchemaResolveRef(schema);
+
+  try {
+    resolvedSchema = await source.resolve(schemaResolveRef, schema._context);
+  } catch (error) {
+    throw new Error(buildSchemaSourceErrorMessage({ schema, source, error }));
+  }
+
+  if (!resolvedSchema) return undefined;
+
+  const resolvedMessageSchema: InternalMessageSchemaResource = {
+    ...schema,
+    format: schema.format !== 'unknown' ? schema.format : (resolvedSchema.format ?? 'unknown'),
+    content: resolvedSchema.content,
+    source: resolvedSchema.source,
+    readOnly: true,
+  };
+
+  resolvedMessageSchema.name = getSchemaDisplayName({
+    referenceName: schema.name,
+    resolvedName: resolvedSchema.name,
+    schemaRef: schema.ref,
+    sourcePath: resolvedSchema.source.path,
+    schemaId: schema.id,
+    messageName: schema.message.name,
+  });
+
+  return resolvedMessageSchema;
+};
+
+const resolveSchemaSources = async (schemas: InternalMessageSchemaResource[], sources: SchemaSource[] = []) => {
+  if (sources.length > 0 && !isEventCatalogScaleEnabled()) {
+    throw new Error('Schema sources require EventCatalog Scale.');
+  }
+
+  const localSchemas = schemas.filter(schemaFileExists);
+  const externalSchemas = schemas.filter((schema) => !schema.filePath);
+  const resolvedExternalSchemas: InternalMessageSchemaResource[] = [];
+  const resolvedExternalSchemaIds = new Set<string>();
+
+  for (const source of sources) {
+    const sourceSchemas = externalSchemas.filter((schema) => source.canResolve(getSchemaResolveRef(schema)));
+    if (sourceSchemas.length === 0) continue;
+
+    logSchemaInfo(
+      `Loading ${sourceSchemas.length} schema${sourceSchemas.length === 1 ? '' : 's'} from schema source "${source.name}"`
+    );
+
+    const resolvedSchemas = await Promise.all(sourceSchemas.map((schema) => resolveSchemaSource(schema, source)));
+    const syncedSchemas = resolvedSchemas.filter((schema): schema is InternalMessageSchemaResource => schema !== undefined);
+
+    for (const schema of syncedSchemas) {
+      resolvedExternalSchemaIds.add(schema.id);
+      resolvedExternalSchemas.push(schema);
+    }
+
+    const skippedSchemas = sourceSchemas.length - syncedSchemas.length;
+    logSchemaInfo(
+      `Synced ${syncedSchemas.length} schema${syncedSchemas.length === 1 ? '' : 's'} from schema source "${source.name}"${
+        skippedSchemas > 0 ? ` (${skippedSchemas} skipped)` : ''
+      }`
+    );
+  }
+
+  return [
+    ...localSchemas,
+    ...resolvedExternalSchemas,
+    ...schemas.filter((schema) => schema.filePath && !schemaFileExists(schema)),
+  ].filter((schema) => {
+    if (schema.filePath) return schemaFileExists(schema);
+    return resolvedExternalSchemaIds.has(schema.id);
+  });
+};
+
+const loadMessageSchemaResources = async ({ pattern, base }: SchemaLoaderOptions['messages']) => {
+  if (!base) return [];
+
+  const files = await glob(pattern, {
+    cwd: base,
+    absolute: true,
+    nodir: true,
+    ignore: ['dist/**', '**/dist/**'],
+  });
+
+  const schemas = await Promise.all(
+    files.map(async (file) => {
+      const collection = getMessageCollectionFromPath(file);
+      if (!collection) return [];
+
+      const { data } = matter.read(file) as { data: MessageFrontmatter };
+      return getMessageSchemasFromFrontmatter({ data, collection, messageFilePath: file }).map((schema) => ({
+        ...schema,
+        _context: {
+          messageFilePath: file,
+        },
+      }));
+    })
+  );
+
+  return schemas.flat();
+};
+
+const stripSchemaLoaderContext = (schema: InternalMessageSchemaResource): MessageSchemaResource => {
+  const { _context, ...publicSchema } = schema;
+  return publicSchema;
+};
+
+export const loadMessageSchemas = async (messages: SchemaLoaderOptions['messages'], sources: SchemaSource[] = []) => {
+  const schemas = await loadMessageSchemaResources(messages);
+  const resolvedSchemas = await resolveSchemaSources(schemas, sources);
+
+  return addLatestMetadata(resolvedSchemas.map(stripSchemaLoaderContext));
+};
+
+const getSchemaBody = async (schema: MessageSchemaResource) => {
+  if (schema.content !== undefined) return schema.content;
+  if (!schemaFileExists(schema)) return undefined;
+  return fs.readFile(schema.filePath, 'utf8');
+};
+
+const setSchema = async (context: LoaderContext, schema: MessageSchemaResource) => {
+  const body = await getSchemaBody(schema);
+  if (body === undefined) return;
+
+  const schemaWithContent = {
+    ...schema,
+    content: body,
+  };
+  const parsedData = await context.parseData({
+    id: schema.id,
+    data: schemaWithContent,
+  });
+
+  context.store.set({
+    id: schema.id,
+    data: parsedData,
+    body,
+    digest: context.generateDigest(schemaWithContent),
+  });
+};
+
+export const schemaLoader = ({ messages, sources = [] }: SchemaLoaderOptions): Loader => {
+  return {
+    name: 'eventcatalog-schema-loader',
+    load: async (context) => {
+      context.store.clear();
+      const schemas = await loadMessageSchemas(messages, sources);
+
+      for (const schema of schemas) {
+        await setSchema(context, schema);
+      }
+    },
+  };
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/schemas.ts b/packages/core/eventcatalog/src/utils/collections/schemas.ts
new file mode 100644
index 000000000..5d3c00e79
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/schemas.ts
@@ -0,0 +1,108 @@
+import type { CollectionEntry } from 'astro:content';
+import type { PageTypes } from '@types';
+import path from 'path';
+import { buildUrl } from '@utils/url-builder';
+import { getAbsoluteFilePathForAstroFile } from '@utils/files';
+import { getFolderNameFromFilePath } from './util';
+
+export type Schema = {
+  url: string;
+  format: string;
+};
+
+const getPublicPath = (resource: CollectionEntry<PageTypes> | any): string | undefined => {
+  if (!resource.filePath) return undefined;
+  const folderName = getFolderNameFromFilePath(resource.filePath);
+  return path.join('/generated', resource.collection, folderName);
+};
+
+export const getSchemaURL = (resource: CollectionEntry<PageTypes> | any) => {
+  const publicPath = getPublicPath(resource);
+  const schemaFilePath = resource?.data?.schemaPath;
+
+  // No schema file path, return an empty string
+  if (!schemaFilePath) {
+    return;
+  }
+
+  if (!publicPath) {
+    // Then we try and get the absolute file path from the resource
+    const absoluteFilePath = getAbsoluteFilePathForAstroFile(resource.filePath ?? '', schemaFilePath ?? '');
+    if (absoluteFilePath) {
+      return absoluteFilePath;
+    }
+    // Can't find the schema file, return an empty string
+    return;
+  }
+
+  // new URL
+  return path.join(publicPath, schemaFilePath ?? '');
+};
+
+export const getSchemaFormatFromURL = (url: string) => {
+  const pathParts = url.split('.');
+  const format = pathParts[pathParts.length - 1];
+  return format;
+};
+
+export const getSchemasFromResource = (resource: CollectionEntry<PageTypes> | any): Schema[] => {
+  const schemaPublicPath = getSchemaURL(resource);
+
+  if (!schemaPublicPath) {
+    return [];
+  }
+
+  if (resource.collection === 'services') {
+    const specifications = (resource?.data as any)?.specifications;
+    const asyncapiPath = Array.isArray(specifications)
+      ? specifications.find((spec) => spec.type === 'asyncapi')?.path
+      : specifications?.asyncapiPath;
+    const openapiPath = Array.isArray(specifications)
+      ? specifications.find((spec) => spec.type === 'openapi')?.path
+      : specifications?.openapiPath;
+    const graphqlPath = Array.isArray(specifications)
+      ? specifications.find((spec) => spec.type === 'graphql')?.path
+      : specifications?.graphqlPath;
+    let publicPath = getPublicPath(resource);
+    const schemas = [];
+
+    if (asyncapiPath) {
+      if (!publicPath) {
+        // We try and get the absoulate file path from the resource
+        const absoluteFilePath = getAbsoluteFilePathForAstroFile(resource.filePath ?? '', asyncapiPath ?? '');
+        schemas.push({ url: buildUrl(absoluteFilePath), format: 'asyncapi' });
+      } else {
+        // The resource has the public path, so we can use it to build the URL
+        schemas.push({ url: buildUrl(path.join(publicPath, asyncapiPath)), format: 'asyncapi' });
+      }
+    }
+
+    if (openapiPath) {
+      if (!publicPath) {
+        // We try and get the absoulate file path from the resource
+        const absoluteFilePath = getAbsoluteFilePathForAstroFile(resource.filePath ?? '', openapiPath ?? '');
+        schemas.push({ url: buildUrl(absoluteFilePath), format: 'openapi' });
+      } else {
+        // The resource has the public path, so we can use it to build the URL
+        schemas.push({ url: buildUrl(path.join(publicPath, openapiPath)), format: 'openapi' });
+      }
+    }
+
+    if (graphqlPath) {
+      if (!publicPath) {
+        // We try and get the absoulate file path from the resource
+        const absoluteFilePath = getAbsoluteFilePathForAstroFile(resource.filePath ?? '', graphqlPath ?? '');
+        schemas.push({ url: buildUrl(absoluteFilePath), format: 'graphql' });
+      } else {
+        // The resource has the public path, so we can use it to build the URL
+        schemas.push({ url: buildUrl(path.join(publicPath, graphqlPath)), format: 'graphql' });
+      }
+    }
+
+    return schemas;
+  } else {
+    const pathParts = schemaPublicPath.split('.');
+    const format = pathParts[pathParts.length - 1];
+    return [{ url: buildUrl(schemaPublicPath), format }];
+  }
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/services.ts b/packages/core/eventcatalog/src/utils/collections/services.ts
new file mode 100644
index 000000000..d0401438f
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/services.ts
@@ -0,0 +1,245 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import semver from 'semver';
+import type { CollectionMessageTypes, CollectionTypes } from '@types';
+import { getDomains, getDomainsForService } from './domains';
+import {
+  createVersionedMap,
+  findInMap,
+  versionMatches,
+  processSpecifications,
+  getItemsFromCollectionByIdAndSemverOrLatest,
+} from '@utils/collections/util';
+import { getChannels } from './channels';
+
+export type Service = CollectionEntry<'services'>;
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+interface Props {
+  getAllVersions?: boolean;
+  returnBody?: boolean;
+}
+
+// Simple in-memory cache
+let memoryCache: Record<string, Service[]> = {};
+
+export const getServices = async ({ getAllVersions = true, returnBody = false }: Props = {}): Promise<Service[]> => {
+  // console.time('✅ New getServices');
+  const cacheKey = `${getAllVersions ? 'allVersions' : 'currentVersions'}-${returnBody ? 'withBody' : 'noBody'}`;
+
+  // Check if we have cached services
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    // console.timeEnd('✅ New getServices');
+    return memoryCache[cacheKey];
+  }
+
+  // 1. Fetch all collections in parallel
+  const [allServices, allEvents, allCommands, allQueries, allEntities, allContainers, allFlows] = await Promise.all([
+    getCollection('services'),
+    getCollection('events'),
+    getCollection('commands'),
+    getCollection('queries'),
+    getCollection('entities'),
+    getCollection('containers'),
+    getCollection('flows'),
+  ]);
+
+  const allMessages = [...allEvents, ...allCommands, ...allQueries];
+
+  // 2. Build optimized maps
+  const serviceMap = createVersionedMap(allServices);
+  const messageMap = createVersionedMap(allMessages);
+  const entityMap = createVersionedMap(allEntities);
+  const containerMap = createVersionedMap(allContainers);
+  const flowMap = createVersionedMap(allFlows);
+
+  // 3. Filter services
+  const targetServices = allServices.filter((service) => {
+    if (service.data.hidden === true) return false;
+    if (!getAllVersions && service.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  // 4. Enrich services using Map lookups (O(1))
+  const processedServices = await Promise.all(
+    targetServices.map(async (service) => {
+      // Version info
+      const serviceVersions = serviceMap.get(service.data.id) || [];
+      const latestVersion = serviceVersions[0]?.data.version || service.data.version;
+      const versions = serviceVersions.map((s) => s.data.version);
+
+      const sends = (service.data.sends || [])
+        .map((m) => findInMap(messageMap, m.id, m.version))
+        .filter((e): e is CollectionEntry<CollectionMessageTypes> => !!e);
+
+      const receives = (service.data.receives || [])
+        .map((m) => findInMap(messageMap, m.id, m.version))
+        .filter((e): e is CollectionEntry<CollectionMessageTypes> => !!e);
+
+      const mappedEntities = (service.data.entities || [])
+        .map((e) => findInMap(entityMap, e.id, e.version))
+        .filter((e): e is CollectionEntry<'entities'> => !!e);
+
+      const mappedWritesTo = (service.data.writesTo || [])
+        .map((c) => findInMap(containerMap, c.id, c.version))
+        .filter((e): e is CollectionEntry<'containers'> => !!e);
+
+      const mappedReadsFrom = (service.data.readsFrom || [])
+        .map((c) => findInMap(containerMap, c.id, c.version))
+        .filter((e): e is CollectionEntry<'containers'> => !!e);
+
+      const mappedFlows = (service.data.flows || [])
+        .map((f) => findInMap(flowMap, f.id, f.version))
+        .filter((f): f is CollectionEntry<'flows'> => !!f);
+
+      return {
+        ...service,
+        data: {
+          ...service.data,
+          writesTo: mappedWritesTo as any,
+          readsFrom: mappedReadsFrom as any,
+          flows: mappedFlows as any,
+          receives: receives as any,
+          sends: sends as any,
+          versions,
+          latestVersion,
+          entities: mappedEntities as any,
+        },
+        // TODO: verify if it could be deleted.
+        nodes: {
+          receives: receives as any,
+          sends: sends as any,
+        },
+        body: returnBody ? service.body : undefined,
+      };
+    })
+  );
+
+  // order them by the name of the service
+  processedServices.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedServices;
+  // console.timeEnd('✅ New getServices');
+
+  return processedServices;
+};
+
+export const getProducersOfMessage = (services: Service[], message: CollectionEntry<'events' | 'commands' | 'queries'>) => {
+  return services.filter((service) => {
+    return service.data.sends?.some((send) => {
+      const idMatch = send.id === message.data.id;
+
+      // If no version specified in send, treat as 'latest'
+      if (!send.version) return idMatch;
+
+      // If version is 'latest', match any version
+      if (send.version === 'latest') return idMatch;
+
+      // Use versionMatches to support semver ranges and x-patterns
+      return idMatch && versionMatches(message.data.version, send.version);
+    });
+  });
+};
+
+export const getConsumersOfMessage = (services: Service[], message: CollectionEntry<'events' | 'commands' | 'queries'>) => {
+  return services.filter((service) => {
+    return service.data.receives?.some((receive) => {
+      const idMatch = receive.id === message.data.id;
+
+      // If no version specified in receive, treat as 'latest'
+      if (!receive.version) return idMatch;
+
+      // If version is 'latest', match any version
+      if (receive.version === 'latest') return idMatch;
+
+      // Use versionMatches to support semver ranges and x-patterns
+      return idMatch && versionMatches(message.data.version, receive.version);
+    });
+  });
+};
+
+export const getSpecificationsForService = (service: CollectionEntry<CollectionTypes>) => {
+  return processSpecifications((service.data as any).specifications as any);
+};
+// Get services for channel
+export const getProducersAndConsumersForChannel = async (channel: CollectionEntry<'channels'>) => {
+  const messages = channel.data.messages ?? [];
+  const services = await getServices({ getAllVersions: false });
+
+  const producers = services.filter((service) => {
+    const sends = service.data.sends ?? [];
+    return sends.some((send) => {
+      // @ts-ignore
+      return messages.some((m) => m.id === send.data.id);
+    });
+  });
+
+  const consumers = services.filter((service) => {
+    const receives = service.data.receives ?? [];
+    return receives.some((receive) => {
+      // @ts-ignore
+      return messages.some((m) => m.id === receive.data.id);
+    });
+  });
+
+  return {
+    producers: producers ?? [],
+    consumers: consumers ?? [],
+  };
+};
+export const getChannelsForService = async (serviceId: string, version?: string): Promise<CollectionEntry<'channels'>[]> => {
+  const allServices = await getCollection('services');
+  const allChannels = await getChannels({ getAllVersions: true });
+
+  const matched = getItemsFromCollectionByIdAndSemverOrLatest(allServices, serviceId, version);
+  const service = matched[0];
+  if (!service) return [];
+
+  const sends = service.data.sends ?? [];
+  const receives = service.data.receives ?? [];
+
+  const channelPointers: Array<{ id: string; version?: string }> = [];
+
+  for (const send of sends) {
+    for (const channel of send.to ?? []) {
+      channelPointers.push({ id: channel.id, version: channel.version });
+    }
+  }
+
+  for (const receive of receives) {
+    for (const channel of receive.from ?? []) {
+      channelPointers.push({ id: channel.id, version: channel.version });
+    }
+  }
+
+  const channelMap = createVersionedMap(allChannels);
+  const seen = new Set<string>();
+  const channels: CollectionEntry<'channels'>[] = [];
+
+  for (const pointer of channelPointers) {
+    const key = `${pointer.id}-${pointer.version ?? 'latest'}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const match = findInMap(channelMap, pointer.id, pointer.version);
+    if (match) channels.push(match as CollectionEntry<'channels'>);
+  }
+
+  return channels;
+};
+
+export const getServicesNotInAnyDomain = async (): Promise<Service[]> => {
+  const services = await getServices({ getAllVersions: false });
+
+  // We need an async-aware filter: run all lookups, then filter by the results
+  const domainCountsForServices = await Promise.all(
+    services.map(async (service) => {
+      const domainsForService = await getDomainsForService(service);
+      return domainsForService.length;
+    })
+  );
+
+  return services.filter((_, index) => domainCountsForServices[index] === 0);
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/systems.ts b/packages/core/eventcatalog/src/utils/collections/systems.ts
new file mode 100644
index 000000000..96afcfbed
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/systems.ts
@@ -0,0 +1,110 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { createVersionedMap, findInMap } from './util';
+
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+export type System = CollectionEntry<'systems'>;
+
+interface Props {
+  getAllVersions?: boolean;
+}
+
+// cache for build time
+let memoryCache: Record<string, System[]> = {};
+
+export const getSystems = async ({ getAllVersions = true }: Props = {}): Promise<System[]> => {
+  const cacheKey = getAllVersions ? 'allVersions' : 'currentVersions';
+
+  if (memoryCache[cacheKey] && memoryCache[cacheKey].length > 0 && CACHE_ENABLED) {
+    return memoryCache[cacheKey];
+  }
+
+  const [allSystems, allServices, allFlows, allEntities, allContainers] = await Promise.all([
+    getCollection('systems'),
+    getCollection('services'),
+    getCollection('flows'),
+    getCollection('entities'),
+    getCollection('containers'),
+  ]);
+
+  // Build optimized map of id -> versions (sorted latest first)
+  const systemMap = createVersionedMap(allSystems);
+  const serviceMap = createVersionedMap(allServices);
+  const flowMap = createVersionedMap(allFlows);
+  const entityMap = createVersionedMap(allEntities);
+  const containerMap = createVersionedMap(allContainers);
+
+  // Filter systems
+  const targetSystems = allSystems.filter((system) => {
+    if (system.data.hidden === true) return false;
+    if (!getAllVersions && system.filePath?.includes('versioned')) return false;
+    return true;
+  });
+
+  // Enrich systems with version info
+  const processedSystems = targetSystems.map((system) => {
+    const systemVersions = systemMap.get(system.data.id) || [];
+    const latestVersion = systemVersions[0]?.data.version || system.data.version;
+    const versions = systemVersions.map((s) => s.data.version);
+
+    // Resolve service pointers to their full collection entries
+    const services = (system.data.services || [])
+      .map((service: { id: string; version?: string }) => findInMap(serviceMap, service.id, service.version))
+      .filter((s): s is NonNullable<typeof s> => !!s);
+
+    // Resolve flow pointers to their full collection entries
+    const flows = (system.data.flows || [])
+      .map((flow: { id: string; version?: string }) => findInMap(flowMap, flow.id, flow.version))
+      .filter((f): f is NonNullable<typeof f> => !!f);
+
+    // Resolve entity pointers to their full collection entries
+    const entities = (system.data.entities || [])
+      .map((entity: { id: string; version?: string }) => findInMap(entityMap, entity.id, entity.version))
+      .filter((e): e is NonNullable<typeof e> => !!e);
+
+    // Resolve container (data store) pointers to their full collection entries
+    const containers = (system.data.containers || [])
+      .map((container: { id: string; version?: string }) => findInMap(containerMap, container.id, container.version))
+      .filter((c): c is NonNullable<typeof c> => !!c);
+
+    // Resolve system-to-system relationship pointers (used by the System Diagram).
+    // Each relationship resolves to its target system while keeping the edge `label`.
+    // Dangling targets are dropped; relationships keep their label even if absent (the
+    // diagram decides whether to draw an edge based on the presence of a label).
+    const relationships = (system.data.relationships || [])
+      .map((relationship: { id: string; version?: string; label?: string }) => {
+        const target = findInMap(systemMap, relationship.id, relationship.version);
+        if (!target) return null;
+        return {
+          id: target.data.id,
+          version: target.data.version,
+          label: relationship.label,
+          data: target.data,
+        };
+      })
+      .filter((r): r is NonNullable<typeof r> => !!r);
+
+    return {
+      ...system,
+      data: {
+        ...system.data,
+        versions,
+        latestVersion,
+        services: services as any,
+        flows: flows as any,
+        entities: entities as any,
+        containers: containers as any,
+        relationships: relationships as any,
+      },
+    };
+  });
+
+  // order them by the name of the system
+  processedSystems.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache[cacheKey] = processedSystems;
+
+  return processedSystems;
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/teams.ts b/packages/core/eventcatalog/src/utils/collections/teams.ts
new file mode 100644
index 000000000..729314dc6
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/teams.ts
@@ -0,0 +1,102 @@
+import type { CollectionTypes } from '@types';
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { getAdrs } from './adrs';
+
+export type Team = CollectionEntry<'teams'>;
+const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
+// Cache for build time
+let memoryCache: Team[] = [];
+
+export const getTeams = async (): Promise<Team[]> => {
+  // console.time('✅ New getTeams');
+  if (memoryCache.length > 0 && CACHE_ENABLED) {
+    // console.timeEnd('✅ New getTeams');
+    return memoryCache;
+  }
+
+  // 1. Fetch all collections in parallel
+  const [allTeams, allAgents, allDomains, allSystems, allServices, allEvents, allCommands, allQueries, allAdrs] =
+    await Promise.all([
+      getCollection('teams'),
+      getCollection('agents'),
+      getCollection('domains'),
+      getCollection('systems'),
+      getCollection('services'),
+      getCollection('events'),
+      getCollection('commands'),
+      getCollection('queries'),
+      getAdrs({ getAllVersions: false }),
+    ]);
+
+  // 2. Filter teams
+  const targetTeams = allTeams.filter((team) => team.data.hidden !== true);
+
+  // 3. Build Owner Index: Map<OwnerID, Item[]>
+  // This index groups all items (domains, services, etc.) by their owner IDs.
+  // This allows O(1) lookup to find all items owned by a specific team.
+  const ownershipMap = new Map<string, CollectionEntry<CollectionTypes>[]>();
+
+  const addToIndex = (items: CollectionEntry<CollectionTypes>[]) => {
+    for (const item of items) {
+      if (item.data.owners) {
+        for (const owner of item.data.owners) {
+          if (!ownershipMap.has(owner.id)) {
+            ownershipMap.set(owner.id, []);
+          }
+          ownershipMap.get(owner.id)!.push(item);
+        }
+      }
+    }
+  };
+
+  addToIndex(allAgents);
+  addToIndex(allDomains);
+  addToIndex(allSystems);
+  addToIndex(allServices);
+  addToIndex(allEvents);
+  addToIndex(allCommands);
+  addToIndex(allQueries);
+  addToIndex(allAdrs);
+
+  // 4. Enrich teams using the ownership index
+  const processedTeams = targetTeams.map((team) => {
+    const teamId = team.data.id;
+    const ownedItems = ownershipMap.get(teamId) || [];
+
+    // Categorize items
+    const ownedAgents = ownedItems.filter((i) => i.collection === 'agents') as CollectionEntry<'agents'>[];
+    const ownedDomains = ownedItems.filter((i) => i.collection === 'domains') as CollectionEntry<'domains'>[];
+    const ownedSystems = ownedItems.filter((i) => i.collection === 'systems') as CollectionEntry<'systems'>[];
+    const ownedServices = ownedItems.filter((i) => i.collection === 'services') as CollectionEntry<'services'>[];
+    const ownedEvents = ownedItems.filter((i) => i.collection === 'events') as CollectionEntry<'events'>[];
+    const ownedCommands = ownedItems.filter((i) => i.collection === 'commands') as CollectionEntry<'commands'>[];
+    const ownedQueries = ownedItems.filter((i) => i.collection === 'queries') as CollectionEntry<'queries'>[];
+    const ownedAdrs = ownedItems.filter((i) => i.collection === 'adrs') as CollectionEntry<'adrs'>[];
+
+    return {
+      ...team,
+      data: {
+        ...team.data,
+        ownedAgents,
+        ownedDomains,
+        ownedSystems,
+        ownedServices,
+        ownedCommands,
+        ownedQueries,
+        ownedEvents,
+        ownedAdrs,
+      },
+    };
+  });
+
+  // order them by the name of the team
+  processedTeams.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache = processedTeams;
+  // console.timeEnd('✅ New getTeams');
+
+  return processedTeams;
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/types.ts b/packages/core/eventcatalog/src/utils/collections/types.ts
new file mode 100644
index 000000000..05d68f469
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/types.ts
@@ -0,0 +1,7 @@
+import type { CollectionEntry } from 'astro:content';
+
+// Shared types to avoid circular dependencies between domains.ts and services.ts
+export type Service = CollectionEntry<'services'>;
+export type Agent = CollectionEntry<'agents'>;
+export type Domain = CollectionEntry<'domains'>;
+export type UbiquitousLanguage = CollectionEntry<'ubiquitousLanguages'>;
diff --git a/packages/core/eventcatalog/src/utils/collections/users.ts b/packages/core/eventcatalog/src/utils/collections/users.ts
new file mode 100644
index 000000000..626a8ae16
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/users.ts
@@ -0,0 +1,130 @@
+import type { CollectionTypes } from '@types';
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import { getAdrs } from './adrs';
+
+export type User = CollectionEntry<'users'>;
+
+// Simple in-memory cache
+let memoryCache: User[] = [];
+
+export const getUsers = async (): Promise<User[]> => {
+  // console.time('✅ New getUsers');
+
+  if (memoryCache.length > 0) {
+    // console.timeEnd('✅ New getUsers');
+    return memoryCache;
+  }
+
+  // 1. Fetch all collections in parallel
+  const [allUsers, allAgents, allDomains, allSystems, allServices, allEvents, allCommands, allQueries, allTeams, allAdrs] =
+    await Promise.all([
+      getCollection('users'),
+      getCollection('agents'),
+      getCollection('domains'),
+      getCollection('systems'),
+      getCollection('services'),
+      getCollection('events'),
+      getCollection('commands'),
+      getCollection('queries'),
+      getCollection('teams'),
+      getAdrs({ getAllVersions: false }),
+    ]);
+
+  // 2. Filter users
+  const targetUsers = allUsers.filter((user) => user.data.hidden !== true);
+  const visibleTeams = allTeams.filter((team) => team.data.hidden !== true);
+
+  // 3. Process users (Optimization: Iterate once over relationships if possible,
+  // but since we need to check ownership for EACH user against ALL items,
+  // we can't easily invert the map without building an "owner" index first.
+  // Given users/teams count is usually lower than events/services, iterating users and filtering items is acceptable,
+  // OR we can index items by ownerID for O(1) lookup. Let's try indexing items by ownerID.)
+
+  // Build Owner Index: Map<OwnerID, Item[]>
+  const ownershipMap = new Map<string, CollectionEntry<CollectionTypes>[]>();
+
+  const addToIndex = (items: CollectionEntry<CollectionTypes>[]) => {
+    for (const item of items) {
+      if (item.data.owners) {
+        for (const owner of item.data.owners) {
+          if (!ownershipMap.has(owner.id)) {
+            ownershipMap.set(owner.id, []);
+          }
+          ownershipMap.get(owner.id)!.push(item);
+        }
+      }
+    }
+  };
+
+  addToIndex(allAgents);
+  addToIndex(allDomains);
+  addToIndex(allSystems);
+  addToIndex(allServices);
+  addToIndex(allEvents);
+  addToIndex(allCommands);
+  addToIndex(allQueries);
+  addToIndex(allAdrs);
+
+  // Team Membership Index: Map<UserID, Team[]>
+  const teamMembershipMap = new Map<string, typeof visibleTeams>();
+  for (const team of visibleTeams) {
+    if (team.data.members) {
+      for (const member of team.data.members) {
+        if (!teamMembershipMap.has(member.id)) {
+          teamMembershipMap.set(member.id, []);
+        }
+        teamMembershipMap.get(member.id)!.push(team);
+      }
+    }
+  }
+
+  const mappedUsers = targetUsers.map((user) => {
+    const userId = user.data.id;
+    const associatedTeams = teamMembershipMap.get(userId) || [];
+    const associatedTeamIds = associatedTeams.map((t) => t.data.id);
+
+    // Collect all owned items directly owned by user OR by their teams
+    const directOwnedItems = ownershipMap.get(userId) || [];
+    const teamOwnedItems = associatedTeamIds.flatMap((teamId) => ownershipMap.get(teamId) || []);
+
+    // Combine and deduplicate items (by ID+Version or just reference equality since they come from same source arrays)
+    const allOwnedItems = Array.from(new Set([...directOwnedItems, ...teamOwnedItems]));
+
+    // Categorize items
+    const ownedAgents = allOwnedItems.filter((i) => i.collection === 'agents') as CollectionEntry<'agents'>[];
+    const ownedDomains = allOwnedItems.filter((i) => i.collection === 'domains') as CollectionEntry<'domains'>[];
+    const ownedSystems = allOwnedItems.filter((i) => i.collection === 'systems') as CollectionEntry<'systems'>[];
+    const ownedServices = allOwnedItems.filter((i) => i.collection === 'services') as CollectionEntry<'services'>[];
+    const ownedEvents = allOwnedItems.filter((i) => i.collection === 'events') as CollectionEntry<'events'>[];
+    const ownedCommands = allOwnedItems.filter((i) => i.collection === 'commands') as CollectionEntry<'commands'>[];
+    const ownedQueries = allOwnedItems.filter((i) => i.collection === 'queries') as CollectionEntry<'queries'>[];
+    const ownedAdrs = allOwnedItems.filter((i) => i.collection === 'adrs') as CollectionEntry<'adrs'>[];
+
+    return {
+      ...user,
+      data: {
+        ...user.data,
+        ownedAgents,
+        ownedDomains,
+        ownedSystems,
+        ownedServices,
+        ownedEvents,
+        ownedCommands,
+        ownedQueries,
+        ownedAdrs,
+        associatedTeams,
+      },
+    };
+  });
+
+  // order them by the name of the user
+  mappedUsers.sort((a, b) => {
+    return (a.data.name || a.data.id).localeCompare(b.data.name || b.data.id);
+  });
+
+  memoryCache = mappedUsers;
+  // console.timeEnd('✅ New getUsers');
+
+  return mappedUsers;
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/util.ts b/packages/core/eventcatalog/src/utils/collections/util.ts
new file mode 100644
index 000000000..3e4f39cdf
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/util.ts
@@ -0,0 +1,365 @@
+import type { CollectionTypes } from '@types';
+import type { CollectionEntry } from 'astro:content';
+import semver, { coerce, compare, satisfies as satisfiesRange } from 'semver';
+import path from 'node:path';
+
+// --- FILE PATH HELPERS ---
+
+/**
+ * Extract the folder name from an Astro collection entry's filePath.
+ * Replaces the expensive SDK getResourceFolderName which globs + reads every file.
+ */
+export const getFolderNameFromFilePath = (filePath: string): string => {
+  return path.basename(path.dirname(filePath));
+};
+
+// --- SPECIFICATION HELPERS ---
+
+export type SpecificationType = 'asyncapi' | 'openapi' | 'graphql';
+
+export interface SpecificationInput {
+  type: SpecificationType;
+  path: string;
+  name?: string;
+  headers?: Record<string, string>;
+}
+
+export interface ProcessedSpecification {
+  type: SpecificationType;
+  path: string;
+  name: string;
+  filename: string;
+  filenameWithoutExtension: string;
+  headers?: Record<string, string>;
+}
+
+export const getDefaultSpecificationName = (type: string): string => {
+  switch (type) {
+    case 'asyncapi':
+      return 'AsyncAPI';
+    case 'openapi':
+      return 'OpenAPI';
+    case 'graphql':
+      return 'GraphQL';
+    default:
+      return 'Specification';
+  }
+};
+
+interface LegacySpecificationFormat {
+  asyncapiPath?: string;
+  openapiPath?: string;
+  graphqlPath?: string;
+}
+
+export const processSpecifications = (
+  specifications: SpecificationInput[] | LegacySpecificationFormat | undefined
+): ProcessedSpecification[] => {
+  const specs: SpecificationInput[] = Array.isArray(specifications) ? [...specifications] : [];
+
+  // Handle legacy object format
+  if (specifications && !Array.isArray(specifications)) {
+    if (specifications.asyncapiPath) {
+      specs.push({ type: 'asyncapi', path: specifications.asyncapiPath, name: 'AsyncAPI' });
+    }
+    if (specifications.openapiPath) {
+      specs.push({ type: 'openapi', path: specifications.openapiPath, name: 'OpenAPI' });
+    }
+    if (specifications.graphqlPath) {
+      specs.push({ type: 'graphql', path: specifications.graphqlPath, name: 'GraphQL' });
+    }
+  }
+
+  return specs.map((spec) => ({
+    ...spec,
+    name: spec.name || getDefaultSpecificationName(spec.type),
+    filename: path.basename(spec.path),
+    filenameWithoutExtension: path.basename(spec.path, path.extname(spec.path)),
+  }));
+};
+
+export const getPreviousVersion = (version: string, versions: string[]) => {
+  const index = versions.indexOf(version);
+  return index === -1 ? null : versions[index + 1];
+};
+
+export const getVersions = (data: CollectionEntry<CollectionTypes>[]) => {
+  const allVersions = data.map((item) => item.data.version);
+  const versions = [...new Set(allVersions)];
+  return sortStringVersions(versions);
+};
+
+export { isSameVersion } from './version-compare';
+
+/**
+ * Sorts versioned items. Latest version first.
+ */
+export function sortVersioned<T>(versioned: T[], versionExtractor: (e: T) => string): T[] {
+  // try to coerce semver versions from input version
+  const semverVersions = versioned.map((v) => ({ original: v, semver: coerce(versionExtractor(v)) }));
+
+  // if all versions are semver'ish, use semver to sort them
+  if (semverVersions.every((v) => v.semver != null)) {
+    const sorted = semverVersions.sort((a, b) => compare(b.semver!, a.semver!));
+
+    return sorted.map((v) => v.original);
+  } else {
+    // fallback to default sort
+    return versioned.sort((a, b) => versionExtractor(b).localeCompare(versionExtractor(a)));
+  }
+}
+
+// Takes a collection and a id of a resource, and checks if the version is the latest version in the collection
+export const getLatestVersionInCollectionById = (collection: CollectionEntry<CollectionTypes>[], id: string) => {
+  const items = collection.filter((i) => i.data.id === id);
+  const sortedVersions = sortVersioned(items, (v) => v.data.version);
+  return sortedVersions[0]?.data.version ?? id;
+};
+
+export const getVersionForCollectionItem = (
+  item: CollectionEntry<CollectionTypes>,
+  collection: CollectionEntry<CollectionTypes>[]
+) => {
+  const allVersionsForItem = collection.filter((i) => i.data.id === item.data.id);
+
+  return getVersions(allVersionsForItem);
+};
+
+export function sortStringVersions(versions: string[]) {
+  const sorted = sortVersioned(versions, (v) => v);
+
+  return { latestVersion: sorted[0], versions: sorted };
+}
+
+/**
+ * @param {string} version A valid version (number | v{\d+} | semver)
+ * @param {string} range A semver range or exact version to compare
+ * @returns {boolean} Returns true if the version satisfies the range.
+ */
+export const satisfies = (version: string, range: string): boolean => {
+  const coercedVersion = coerce(version);
+  if (!coercedVersion) return false;
+  return satisfiesRange(coercedVersion, range);
+};
+
+export const getItemsFromCollectionByIdAndSemverOrLatest = <T extends { data: { id: string; version: string } }>(
+  collection: T[],
+  id: string,
+  version?: string
+): T[] => {
+  const filteredCollection = collection.filter((c) => c.data.id == id);
+
+  if (version && version != 'latest') {
+    return filteredCollection.filter((c) => satisfies(c.data.version, version));
+  }
+
+  // Order by version
+  const sorted = sortVersioned(filteredCollection, (item) => item.data.version);
+
+  // latest version
+  return sorted[0] != null ? [sorted[0]] : [];
+};
+
+export const findMatchingNodes = (
+  nodesA: CollectionEntry<'events' | 'commands' | 'queries' | 'services' | 'containers' | 'data-products'>[],
+  nodesB: CollectionEntry<'events' | 'commands' | 'queries' | 'services' | 'containers' | 'data-products'>[]
+) => {
+  // Track messages that are both sent and received
+  return nodesA.filter((nodeA) => {
+    return nodesB.some((nodeB) => {
+      return nodeB.data.id === nodeA.data.id && nodeB.data.version === nodeA.data.version;
+    });
+  });
+};
+
+export const resourceToCollectionMap = {
+  adr: 'adrs',
+  agent: 'agents',
+  service: 'services',
+  event: 'events',
+  command: 'commands',
+  query: 'queries',
+  domain: 'domains',
+  system: 'systems',
+  flow: 'flows',
+  channel: 'channels',
+  user: 'users',
+  team: 'teams',
+  container: 'containers',
+  entity: 'entities',
+  diagram: 'diagrams',
+  'data-product': 'data-products',
+} as const;
+
+export const collectionToResourceMap = {
+  adrs: 'adr',
+  agents: 'agent',
+  services: 'service',
+  events: 'event',
+  commands: 'command',
+  queries: 'query',
+  domains: 'domain',
+  systems: 'system',
+  flows: 'flow',
+  channels: 'channel',
+  users: 'user',
+  teams: 'team',
+  containers: 'container',
+  entities: 'entity',
+  diagrams: 'diagram',
+  'data-products': 'data-product',
+} as const;
+
+/**
+ * Converts a collection name to a human-readable resource type label.
+ * e.g. 'data-products' → 'Data Product', 'services' → 'Service'
+ */
+export const getResourceTypeLabel = (collection: string): string => {
+  const raw = (collectionToResourceMap as Record<string, string>)[collection] || collection;
+  return raw
+    .split('-')
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+};
+
+/**
+ * Returns the correct pointer field name for a collection and direction.
+ * Data-products use 'outputs'/'inputs' instead of 'sends'/'receives'.
+ */
+export const getPointerField = (collection: string, direction: 'sends' | 'receives'): string => {
+  if (collection === 'data-products') return direction === 'sends' ? 'outputs' : 'inputs';
+  return direction;
+};
+
+export const getDeprecatedDetails = (item: CollectionEntry<CollectionTypes>) => {
+  let options = {
+    isMarkedAsDeprecated: false,
+    hasDeprecated: false,
+    message: '',
+    deprecatedDate: '',
+  };
+
+  if (!item.data?.deprecated) return options;
+
+  if (typeof item.data.deprecated === 'boolean') {
+    options.hasDeprecated = item.data.deprecated;
+    options.isMarkedAsDeprecated = item.data.deprecated;
+  }
+
+  if (typeof item.data.deprecated === 'object') {
+    options.isMarkedAsDeprecated = true;
+    options.hasDeprecated = item.data.deprecated.date ? new Date(item.data.deprecated.date) < new Date() : false;
+    options.message = item.data.deprecated.message ?? '';
+    options.deprecatedDate = item.data.deprecated.date
+      ? new Date(item.data.deprecated.date).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })
+      : '';
+  }
+
+  return options;
+};
+
+export const removeContentFromCollection = (collection: CollectionEntry<CollectionTypes>[]) => {
+  return collection.map((item) => ({
+    ...item,
+    body: undefined,
+  }));
+};
+
+// --- OPTIMIZATION HELPERS ---
+
+/**
+ * Groups items by ID and sorts them by version (Newest first).
+ * This allows O(1) lookup for "latest" (index 0) and specific versions.
+ */
+export const createVersionedMap = <T extends { data: { id: string; version?: string } }>(items: T[]) => {
+  const map = new Map<string, T[]>();
+
+  for (const item of items) {
+    const id = item.data.id;
+    if (!map.has(id)) map.set(id, []);
+    map.get(id)!.push(item);
+  }
+
+  // Sort every entry so index [0] is always the latest version
+  for (const [key, list] of map.entries()) {
+    list.sort((a, b) => {
+      // specific version sorting logic (fallback to string compare if not valid semver)
+      const vA = a.data.version || '0.0.0';
+      const vB = b.data.version || '0.0.0';
+      return semver.valid(vB) && semver.valid(vA) ? semver.rcompare(vA, vB) : vB.localeCompare(vA);
+    });
+  }
+  return map;
+};
+
+// Merge as many given maps as you want
+export const mergeMaps = <T>(...maps: Map<string, T[]>[]): Map<string, T[]> => {
+  return maps.reduce((acc, map) => {
+    return new Map([...acc, ...map]);
+  }, new Map<string, T[]>());
+};
+
+/**
+ * Fast lookup helper.
+ * If version is provided, find it. If not, return the first (latest) item.
+ */
+export const findInMap = <T extends { data: { version?: string } }>(
+  map: Map<string, T[]>,
+  id: string,
+  version?: string
+): T | undefined => {
+  const items = map.get(id);
+  if (!items || items.length === 0) return undefined;
+
+  // If no version specified or 'latest', return the first item (which is sorted to be latest)
+  if (!version || version === 'latest') return items[0];
+
+  // Try exact match
+  const exactMatch = items.find((i) => i.data.version === version);
+  if (exactMatch) return exactMatch;
+
+  // Try semver match if not exact
+  if (semver.validRange(version)) {
+    return items.find((i) => semver.satisfies(i.data.version || '0.0.0', version));
+  }
+
+  return undefined;
+};
+
+/**
+ * Matches a specific version against a version range pattern.
+ * Supports exact versions, semver ranges, x-patterns, and 'latest'.
+ *
+ * @param version - The specific version to check (e.g., "1.2.3")
+ * @param rangePattern - The pattern to match against (e.g., "^1.0.0", "1.x", "latest")
+ * @returns true if version matches the rangePattern
+ */
+export const versionMatches = (version: string, rangePattern: string): boolean => {
+  // Handle 'latest' keyword
+  if (rangePattern === 'latest') return true;
+
+  // Try exact match first
+  if (version === rangePattern) return true;
+
+  // Try semver range matching
+  try {
+    if (semver.validRange(rangePattern)) {
+      return semver.satisfies(version, rangePattern);
+    }
+  } catch (error) {
+    // Invalid semver, fall through
+  }
+
+  // Handle x-patterns like 1.x, 1.2.x
+  if (rangePattern.includes('.x')) {
+    const prefix = rangePattern.replace(/\.x/g, '');
+    // Check if version starts with the prefix and has a valid boundary
+    // (next character must be '.' or end of string)
+    if (version.startsWith(prefix)) {
+      const nextChar = version[prefix.length];
+      return nextChar === '.' || nextChar === undefined;
+    }
+  }
+
+  return false;
+};
diff --git a/packages/core/eventcatalog/src/utils/collections/version-compare.ts b/packages/core/eventcatalog/src/utils/collections/version-compare.ts
new file mode 100644
index 000000000..8ecaf5d57
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/version-compare.ts
@@ -0,0 +1,12 @@
+import { coerce, eq } from 'semver';
+
+export function isSameVersion(v1: string | undefined, v2: string | undefined) {
+  const semverV1 = coerce(v1);
+  const semverV2 = coerce(v2);
+
+  if (semverV1 != null && semverV2 != null) {
+    return eq(semverV1, semverV2);
+  }
+
+  return v1 === v2;
+}
diff --git a/packages/core/eventcatalog/src/utils/collections/versions.ts b/packages/core/eventcatalog/src/utils/collections/versions.ts
new file mode 100644
index 000000000..891d1fa64
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/collections/versions.ts
@@ -0,0 +1,31 @@
+import type { CollectionTypes } from '@types';
+import type { CollectionEntry } from 'astro:content';
+import { coerce, compare, satisfies, validRange } from 'semver';
+
+export const getVersionFromCollection = (
+  collection: CollectionEntry<CollectionTypes>[],
+  id: string,
+  version?: string
+): CollectionEntry<CollectionTypes>[] => {
+  const data = collection;
+  const semverRange = validRange(version);
+
+  if (semverRange) {
+    return data.filter((msg) => msg.data.id == id).filter((msg) => satisfies(msg.data.version, semverRange));
+  }
+
+  const filteredEvents = data.filter((event) => event.data.id === id);
+
+  // Order by semver
+  const sorted = filteredEvents.sort((a, b) => {
+    const semverA = coerce(a.data.version);
+    const semverB = coerce(b.data.version);
+    if (semverA && semverB) {
+      return compare(semverA, semverB);
+    }
+    return a.data.version.localeCompare(b.data.version);
+  });
+
+  // latest version
+  return [sorted[sorted.length - 1]];
+};
diff --git a/eventcatalog/src/utils/colors.ts b/packages/core/eventcatalog/src/utils/colors.ts
similarity index 100%
rename from eventcatalog/src/utils/colors.ts
rename to packages/core/eventcatalog/src/utils/colors.ts
diff --git a/packages/core/eventcatalog/src/utils/eventcatalog-config/catalog.ts b/packages/core/eventcatalog/src/utils/eventcatalog-config/catalog.ts
new file mode 100644
index 000000000..ff39de31c
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/eventcatalog-config/catalog.ts
@@ -0,0 +1,33 @@
+import * as config from '@config';
+import type { Config } from '../../../../src/eventcatalog.config';
+
+export type CatalogConfig = Config;
+
+const getConfigValue = (obj: any, key: string, defaultValue: any) => {
+  return obj?.[key] ?? defaultValue;
+};
+
+export const isCollectionVisibleInCatalog = (collection: string) => {
+  const sidebarConfig = config?.default?.docs?.sidebar || {};
+  const collections = [
+    'agents',
+    'events',
+    'commands',
+    'queries',
+    'domains',
+    'channels',
+    'flows',
+    'services',
+    'teams',
+    'users',
+    'customDocs',
+  ];
+
+  if (!collections.includes(collection)) return false;
+
+  const collectionConfig =
+    sidebarConfig[collection === 'events' || collection === 'commands' || collection === 'queries' ? 'messages' : collection];
+  return getConfigValue(collectionConfig, 'visible', true);
+};
+
+export default config.default as CatalogConfig;
diff --git a/packages/core/eventcatalog/src/utils/eventcatalog-config/config-schema.ts b/packages/core/eventcatalog/src/utils/eventcatalog-config/config-schema.ts
new file mode 100644
index 000000000..fe09f6618
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/eventcatalog-config/config-schema.ts
@@ -0,0 +1,49 @@
+import { z } from 'zod';
+
+export const KNOWN_THEMES = ['default', 'ocean', 'sapphire', 'sunset', 'forest'] as const;
+export type KnownTheme = (typeof KNOWN_THEMES)[number];
+
+const optionalString = (max: number) =>
+  z
+    .string()
+    .max(max)
+    .optional()
+    .transform((v) => (v === undefined || v.trim() === '' ? undefined : v));
+
+const optionalUrl = z
+  .string()
+  .max(2048)
+  .optional()
+  .transform((v) => (v === undefined || v.trim() === '' ? undefined : v))
+  .refine((v) => v === undefined || /^https?:\/\//i.test(v), {
+    message: 'Must be a valid URL starting with http:// or https://',
+  });
+
+export const generalSettingsSchema = z.object({
+  title: z.string().min(1, 'Title is required').max(100),
+  tagline: optionalString(500),
+  organizationName: optionalString(100),
+  homepageLink: optionalUrl,
+  editUrl: optionalUrl,
+  repositoryUrl: optionalUrl,
+  logo: z
+    .object({
+      alt: optionalString(200),
+      text: optionalString(50),
+    })
+    .partial()
+    .optional(),
+  // Allow unknown current theme value (e.g., user hand-edited) so we don't clobber it.
+  theme: z.string().min(1).max(100),
+});
+
+export type GeneralSettings = z.infer<typeof generalSettingsSchema>;
+
+export const aiSettingsSchema = z.object({
+  llmsTxtEnabled: z.boolean(),
+  chatEnabled: z.boolean(),
+});
+
+export type AiSettings = z.infer<typeof aiSettingsSchema>;
+
+export const isKnownTheme = (value: string): value is KnownTheme => (KNOWN_THEMES as readonly string[]).includes(value);
diff --git a/packages/core/eventcatalog/src/utils/eventcatalog-config/config-writer.ts b/packages/core/eventcatalog/src/utils/eventcatalog-config/config-writer.ts
new file mode 100644
index 000000000..9ea6bb1cc
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/eventcatalog-config/config-writer.ts
@@ -0,0 +1,149 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import * as recast from 'recast';
+import babelParser from 'recast/parsers/babel.js';
+
+const b = recast.types.builders;
+type ASTNode = recast.types.ASTNode;
+type ObjectExpression = recast.types.namedTypes.ObjectExpression;
+type Property = recast.types.namedTypes.Property;
+type ObjectProperty = recast.types.namedTypes.ObjectProperty;
+
+export type ConfigPrimitive = string | boolean;
+
+export type ConfigUpdate = {
+  // Primitive value → set; `null` → remove; object → recurse one level.
+  [key: string]: ConfigPrimitive | null | NestedConfigUpdate;
+};
+
+type NestedConfigUpdate = {
+  [key: string]: ConfigPrimitive | null;
+};
+
+const projectRoot = () => process.env.PROJECT_DIR ?? process.cwd();
+
+export const getConfigPath = () => path.join(projectRoot(), 'eventcatalog.config.js');
+
+export const readConfigSource = (): string => fs.readFileSync(getConfigPath(), 'utf8');
+
+const parse = (source: string) => recast.parse(source, { parser: babelParser });
+
+const isObjectProperty = (n: any): n is Property | ObjectProperty => n && (n.type === 'ObjectProperty' || n.type === 'Property');
+
+const propertyKeyName = (prop: Property | ObjectProperty): string | null => {
+  const key: any = prop.key;
+  if (!key) return null;
+  if (key.type === 'Identifier') return key.name;
+  if (key.type === 'Literal' || key.type === 'StringLiteral') return String(key.value);
+  return null;
+};
+
+const findExportedObject = (ast: ASTNode): ObjectExpression => {
+  let result: ObjectExpression | null = null;
+  recast.visit(ast, {
+    visitExportDefaultDeclaration(p) {
+      const decl: any = p.node.declaration;
+      if (decl?.type === 'ObjectExpression') {
+        result = decl as ObjectExpression;
+      } else if (decl?.type === 'TSAsExpression' && decl.expression?.type === 'ObjectExpression') {
+        result = decl.expression as ObjectExpression;
+      }
+      return false;
+    },
+  });
+  if (!result) throw new Error('Could not find `export default { ... }` in eventcatalog.config.js');
+  return result;
+};
+
+const findProperty = (obj: ObjectExpression, name: string): (Property | ObjectProperty) | null => {
+  for (const prop of obj.properties) {
+    if (isObjectProperty(prop) && propertyKeyName(prop) === name) return prop as Property | ObjectProperty;
+  }
+  return null;
+};
+
+const removeProperty = (obj: ObjectExpression, name: string): boolean => {
+  const idx = obj.properties.findIndex((p) => isObjectProperty(p) && propertyKeyName(p) === name);
+  if (idx === -1) return false;
+  obj.properties.splice(idx, 1);
+  return true;
+};
+
+const buildLiteral = (value: ConfigPrimitive) => (typeof value === 'boolean' ? b.booleanLiteral(value) : b.stringLiteral(value));
+
+const setPrimitiveProperty = (obj: ObjectExpression, name: string, value: ConfigPrimitive) => {
+  const existing = findProperty(obj, name);
+  const literal = buildLiteral(value);
+  if (existing) {
+    (existing as any).value = literal;
+    return;
+  }
+  obj.properties.push(b.property('init', b.identifier(name), literal) as any);
+};
+
+const ensureNestedObject = (obj: ObjectExpression, name: string): ObjectExpression => {
+  const existing = findProperty(obj, name);
+  if (existing && (existing as any).value?.type === 'ObjectExpression') {
+    return (existing as any).value as ObjectExpression;
+  }
+  const fresh = b.objectExpression([]);
+  if (existing) {
+    (existing as any).value = fresh;
+  } else {
+    obj.properties.push(b.property('init', b.identifier(name), fresh) as any);
+  }
+  return fresh;
+};
+
+const removeNestedObjectIfEmpty = (obj: ObjectExpression, name: string) => {
+  const existing = findProperty(obj, name);
+  if (!existing) return;
+  const value: any = (existing as any).value;
+  if (value?.type === 'ObjectExpression' && value.properties.length === 0) {
+    removeProperty(obj, name);
+  }
+};
+
+/**
+ * Apply an update to eventcatalog.config.js, preserving formatting/comments via recast.
+ *
+ * - String value → replace existing or insert new property
+ * - `null` value → remove property if present
+ * - Nested object value → recurse one level (sufficient for v1 fields like `logo`)
+ *
+ * Returns the updated source. Caller is responsible for writing it.
+ */
+export const applyConfigUpdate = (source: string, update: ConfigUpdate): string => {
+  const ast = parse(source);
+  const root = findExportedObject(ast);
+
+  for (const [key, value] of Object.entries(update)) {
+    if (value === null) {
+      removeProperty(root, key);
+      continue;
+    }
+    if (typeof value === 'string' || typeof value === 'boolean') {
+      setPrimitiveProperty(root, key, value);
+      continue;
+    }
+    // nested object update
+    const nested = ensureNestedObject(root, key);
+    for (const [nestedKey, nestedValue] of Object.entries(value)) {
+      if (nestedValue === null) {
+        removeProperty(nested, nestedKey);
+      } else if (typeof nestedValue === 'string' || typeof nestedValue === 'boolean') {
+        setPrimitiveProperty(nested, nestedKey, nestedValue);
+      }
+    }
+    removeNestedObjectIfEmpty(root, key);
+  }
+
+  return recast.print(ast, { quote: 'single' }).code;
+};
+
+export const writeConfigUpdate = (update: ConfigUpdate): string => {
+  const source = readConfigSource();
+  const updated = applyConfigUpdate(source, update);
+  fs.writeFileSync(getConfigPath(), updated, 'utf8');
+  return updated;
+};
diff --git a/packages/core/eventcatalog/src/utils/feature.ts b/packages/core/eventcatalog/src/utils/feature.ts
new file mode 100644
index 000000000..9430ba745
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/feature.ts
@@ -0,0 +1,34 @@
+import config from '../../eventcatalog.config.js';
+
+// Open-source feature flags
+export const isSSR = () => config?.output === 'server';
+export const isVisualiserEnabled = () => config?.visualiser?.enabled ?? true;
+export const isChangelogEnabled = () => config?.changelog?.enabled ?? false;
+export const isRSSEnabled = () => config?.rss?.enabled ?? false;
+export const isLLMSTxtEnabled = () => config?.llmsTxt?.enabled ?? true;
+export const isMarkdownDownloadEnabled = () => config?.llmsTxt?.enabled ?? true;
+export const isFullCatalogAPIEnabled = () => config?.api?.fullCatalogAPIEnabled ?? false;
+export const isDevMode = () => process.env.EVENTCATALOG_DEV_MODE === 'true';
+
+// Re-export enterprise feature flags for backwards compatibility.
+// These functions are subject to the EventCatalog Commercial License.
+// See /packages/core/eventcatalog/src/enterprise/LICENSE
+export {
+  isEventCatalogStarterEnabled,
+  isEventCatalogScaleEnabled,
+  isPrivateRemoteSchemaEnabled,
+  isEmbedEnabled,
+  showEventCatalogBranding,
+  showCustomBranding,
+  isCustomDocsEnabled,
+  isResourceDocsEnabled,
+  isEventCatalogChatEnabled,
+  isEventCatalogUpgradeEnabled,
+  isCustomLandingPageEnabled,
+  isCustomPagesEnabled,
+  isAuthEnabled,
+  isCustomStylesEnabled,
+  isEventCatalogMCPEnabled,
+  isEventCatalogMCPAuthEnabled,
+  isIntegrationsEnabled,
+} from '../enterprise/feature';
diff --git a/eventcatalog/src/utils/collections/file-diffs.ts b/packages/core/eventcatalog/src/utils/file-diffs.ts
similarity index 98%
rename from eventcatalog/src/utils/collections/file-diffs.ts
rename to packages/core/eventcatalog/src/utils/file-diffs.ts
index 4a2345cbd..d1131b86a 100644
--- a/eventcatalog/src/utils/collections/file-diffs.ts
+++ b/packages/core/eventcatalog/src/utils/file-diffs.ts
@@ -2,7 +2,7 @@ import { readdir, readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { formatPatch, structuredPatch } from 'diff';
 import { html, parse } from 'diff2html';
-import { getItemsFromCollectionByIdAndSemverOrLatest } from './util';
+import { getItemsFromCollectionByIdAndSemverOrLatest } from './collections/util';
 import type { CollectionEntry } from 'astro:content';
 import type { CollectionTypes } from '@types';
 
diff --git a/eventcatalog/src/utils/files.ts b/packages/core/eventcatalog/src/utils/files.ts
similarity index 88%
rename from eventcatalog/src/utils/files.ts
rename to packages/core/eventcatalog/src/utils/files.ts
index e7ef7441b..6013d67b3 100644
--- a/eventcatalog/src/utils/files.ts
+++ b/packages/core/eventcatalog/src/utils/files.ts
@@ -1,4 +1,4 @@
-import path from 'node:path';
+import * as path from 'node:path';
 
 /**
  * Resolves a file path relative to PROJECT_DIR, handling ../ paths correctly
@@ -59,3 +59,12 @@ export const getAbsoluteFilePathForAstroFile = (filePath: string, fileName?: str
 export const isAvroSchema = (filePath: string): boolean => {
   return filePath.endsWith('.avro') || filePath.endsWith('.avsc');
 };
+
+/**
+ * Checks if a file path is a Protocol Buffers schema based on its extension
+ * @param filePath - The file path to check
+ * @returns True if the file is a Protocol Buffers schema (.proto)
+ */
+export const isProtobufSchema = (filePath: string): boolean => {
+  return filePath.endsWith('.proto');
+};
diff --git a/eventcatalog/src/utils/git.ts b/packages/core/eventcatalog/src/utils/git.ts
similarity index 100%
rename from eventcatalog/src/utils/git.ts
rename to packages/core/eventcatalog/src/utils/git.ts
diff --git a/packages/core/eventcatalog/src/utils/icon-map.ts b/packages/core/eventcatalog/src/utils/icon-map.ts
new file mode 100644
index 000000000..336ec896e
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/icon-map.ts
@@ -0,0 +1,96 @@
+/**
+ * Shared icon map for dynamic lucide-react icon lookups.
+ *
+ * Components that need to resolve icon names from data (sidebar, pill lists, etc.)
+ * should import from this map instead of using `import * as LucideIcons from 'lucide-react'`.
+ * Wildcard imports force Vite to parse 500+ icon modules on first load, adding seconds
+ * to dev server startup time.
+ *
+ * If a user-specified icon name isn't in this map, it won't render.
+ * Add new entries here when new icon names are introduced in sidebar builders,
+ * content schemas, or other dynamic icon contexts.
+ */
+import {
+  ArrowDownToLine,
+  ArrowRightLeft,
+  ArrowUpFromLine,
+  BotMessageSquare,
+  BookOpen,
+  BookText,
+  Box,
+  Boxes,
+  ClipboardCheck,
+  ClipboardList,
+  Code,
+  Database,
+  File,
+  FileCheck,
+  FileCode,
+  FileImage,
+  FileJson,
+  FileWarning,
+  Globe,
+  ListChecks,
+  Mail,
+  Package,
+  Radar,
+  Radio,
+  Route,
+  Search,
+  Server,
+  ShieldCheck,
+  ShoppingCart,
+  Sparkles,
+  SquareMousePointer,
+  Telescope,
+  Terminal,
+  Truck,
+  User,
+  Users,
+  Waypoints,
+  Workflow,
+  Zap,
+  type LucideIcon,
+} from 'lucide-react';
+
+export const LUCIDE_ICON_MAP: Record<string, LucideIcon> = {
+  ArrowDownToLine,
+  ArrowRightLeft,
+  ArrowUpFromLine,
+  BotMessageSquare,
+  BookOpen,
+  BookText,
+  Box,
+  Boxes,
+  ClipboardCheck,
+  ClipboardList,
+  Code,
+  Database,
+  File,
+  FileCheck,
+  FileCode,
+  FileImage,
+  FileJson,
+  FileWarning,
+  Globe,
+  ListChecks,
+  Mail,
+  Package,
+  Radar,
+  Radio,
+  Route,
+  Search,
+  Server,
+  ShieldCheck,
+  ShoppingCart,
+  Sparkles,
+  SquareMousePointer,
+  Telescope,
+  Terminal,
+  Truck,
+  User,
+  Users,
+  Waypoints,
+  Workflow,
+  Zap,
+};
diff --git a/packages/core/eventcatalog/src/utils/icon.ts b/packages/core/eventcatalog/src/utils/icon.ts
new file mode 100644
index 000000000..e99b6c34a
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/icon.ts
@@ -0,0 +1,30 @@
+import { buildUrl } from '@utils/url-builder';
+
+export function isIconPath(value: string | undefined): value is string {
+  if (!value) return false;
+  return value.startsWith('/') || value.startsWith('http://') || value.startsWith('https://');
+}
+
+export function resolveIconUrl(value: string): string {
+  if (value.startsWith('http://') || value.startsWith('https://')) return value;
+  return buildUrl(value, true);
+}
+
+export function iconFieldsForResource(
+  data: { styles?: { icon?: string } } | undefined,
+  defaultIcon: string
+): { leftIcon: string } | { icon: string } {
+  const styleIcon = data?.styles?.icon;
+  return isIconPath(styleIcon) ? { leftIcon: styleIcon } : { icon: defaultIcon };
+}
+
+/**
+ * Like {@link iconFieldsForResource} but with no default icon: returns the custom
+ * `styles.icon` when one is defined, otherwise no icon at all. Used where the
+ * surrounding context (a typed section header) already conveys the resource type,
+ * so the default per-item icon would be redundant.
+ */
+export function customIconFieldsForResource(data: { styles?: { icon?: string } } | undefined): { leftIcon: string } | {} {
+  const styleIcon = data?.styles?.icon;
+  return isIconPath(styleIcon) ? { leftIcon: styleIcon } : {};
+}
diff --git a/packages/core/eventcatalog/src/utils/json-schema-refs.ts b/packages/core/eventcatalog/src/utils/json-schema-refs.ts
new file mode 100644
index 000000000..e0dcd085a
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/json-schema-refs.ts
@@ -0,0 +1,158 @@
+type Fetcher = (input: string | URL, init?: RequestInit) => Promise<Response>;
+
+type ResolveSchemaRefsOptions = {
+  baseUrl: string;
+  headers?: HeadersInit;
+  fetcher?: Fetcher;
+  maxDepth?: number;
+};
+
+type ResolveContext = Required<Pick<ResolveSchemaRefsOptions, 'baseUrl' | 'fetcher' | 'maxDepth'>> & {
+  headers?: HeadersInit;
+  cache: Map<string, unknown>;
+};
+
+type RefTarget = {
+  schema: unknown;
+  root: unknown;
+  baseUrl: string;
+  refKey: string;
+};
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const decodeJsonPointerSegment = (segment: string) => decodeURIComponent(segment).replace(/~1/g, '/').replace(/~0/g, '~');
+
+const resolveJsonPointer = (document: unknown, pointer: string): unknown => {
+  if (!pointer || pointer === '#') return document;
+
+  const path = pointer.startsWith('#') ? pointer.slice(1) : pointer;
+  if (!path) return document;
+  if (!path.startsWith('/')) return undefined;
+
+  return path
+    .slice(1)
+    .split('/')
+    .map(decodeJsonPointerSegment)
+    .reduce<unknown>((current, segment) => {
+      if (current === undefined || current === null) return undefined;
+      if (Array.isArray(current)) return current[Number(segment)];
+      if (isObject(current)) return current[segment];
+      return undefined;
+    }, document);
+};
+
+const splitRef = (ref: string, baseUrl: string) => {
+  const [urlPart = '', fragmentPart = ''] = ref.split('#');
+  const url = urlPart ? new URL(urlPart, baseUrl).toString() : baseUrl;
+  return {
+    url,
+    fragment: `#${fragmentPart}`,
+    refKey: `${url}#${fragmentPart}`,
+  };
+};
+
+const loadRemoteDocument = async (url: string, context: ResolveContext) => {
+  if (context.cache.has(url)) return context.cache.get(url);
+
+  const response = await context.fetcher(url, {
+    headers: context.headers,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch referenced schema: ${response.status} ${response.statusText}`);
+  }
+
+  const document = await response.json();
+  context.cache.set(url, document);
+  return document;
+};
+
+const resolveRef = async (
+  ref: string,
+  root: unknown,
+  currentBaseUrl: string,
+  context: ResolveContext
+): Promise<RefTarget | undefined> => {
+  const { url, fragment, refKey } = splitRef(ref, currentBaseUrl);
+  const isCurrentDocument = url === currentBaseUrl;
+  const document = isCurrentDocument ? root : await loadRemoteDocument(url, context);
+  const schema = resolveJsonPointer(document, fragment);
+
+  if (schema === undefined) return undefined;
+
+  return {
+    schema,
+    root: document,
+    baseUrl: url,
+    refKey,
+  };
+};
+
+const resolveNode = async (
+  node: unknown,
+  root: unknown,
+  currentBaseUrl: string,
+  context: ResolveContext,
+  seenRefs: Set<string>,
+  depth: number
+): Promise<unknown> => {
+  if (depth > context.maxDepth) return node;
+
+  if (Array.isArray(node)) {
+    return Promise.all(node.map((item) => resolveNode(item, root, currentBaseUrl, context, seenRefs, depth)));
+  }
+
+  if (!isObject(node)) return node;
+
+  const ref = typeof node.$ref === 'string' ? node.$ref : undefined;
+  if (ref) {
+    const target = await resolveRef(ref, root, currentBaseUrl, context);
+    if (!target || seenRefs.has(target.refKey)) return { ...node };
+
+    const nextSeenRefs = new Set(seenRefs);
+    nextSeenRefs.add(target.refKey);
+
+    const resolvedSchema = await resolveNode(target.schema, target.root, target.baseUrl, context, nextSeenRefs, depth + 1);
+    const siblingEntries = Object.entries(node).filter(([key]) => key !== '$ref');
+    const resolvedSiblings = Object.fromEntries(
+      await Promise.all(
+        siblingEntries.map(async ([key, value]) => [
+          key,
+          await resolveNode(value, root, currentBaseUrl, context, seenRefs, depth),
+        ])
+      )
+    );
+
+    if (isObject(resolvedSchema)) {
+      return {
+        ...resolvedSchema,
+        ...resolvedSiblings,
+      };
+    }
+
+    return Object.keys(resolvedSiblings).length > 0 ? resolvedSiblings : resolvedSchema;
+  }
+
+  return Object.fromEntries(
+    await Promise.all(
+      Object.entries(node).map(async ([key, value]) => [
+        key,
+        await resolveNode(value, root, currentBaseUrl, context, seenRefs, depth),
+      ])
+    )
+  );
+};
+
+export const resolveSchemaRefs = async (schema: unknown, options: ResolveSchemaRefsOptions): Promise<unknown> => {
+  const context: ResolveContext = {
+    baseUrl: options.baseUrl,
+    headers: options.headers,
+    fetcher: options.fetcher ?? fetch,
+    maxDepth: options.maxDepth ?? 25,
+    cache: new Map([[options.baseUrl, schema]]),
+  };
+
+  return resolveNode(schema, schema, options.baseUrl, context, new Set(), 0);
+};
diff --git a/packages/core/eventcatalog/src/utils/llms.ts b/packages/core/eventcatalog/src/utils/llms.ts
new file mode 100644
index 000000000..9ffcf9350
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/llms.ts
@@ -0,0 +1,57 @@
+import type { CollectionTypes } from '@types';
+import type { CollectionEntry } from 'astro:content';
+import { dirname } from 'path';
+import { join } from 'path';
+import fs from 'fs';
+
+export const addSchemaToMarkdown = (collection: CollectionEntry<CollectionTypes>, file: string) => {
+  const resourceData = collection?.data as any;
+  const fileToResource = collection.filePath ?? '';
+  let schemas: string[] = [];
+
+  if (!resourceData?.specifications && !resourceData?.schemaPath) {
+    return file;
+  }
+
+  if (Array.isArray(resourceData?.specifications)) {
+    schemas = resourceData?.specifications.map((specification: any) => specification.path);
+  } else {
+    schemas = [resourceData?.schemaPath ?? ''];
+  }
+
+  const filteredSchemas = schemas.filter((schema: any) => schema !== undefined);
+
+  // attach the schema if it has it
+  if (filteredSchemas.length > 0) {
+    for (const pathToSchema of filteredSchemas) {
+      const directory = dirname(fileToResource);
+      const schemaPath = join(directory, pathToSchema);
+      const schemaFile = fs.readFileSync(schemaPath, 'utf8');
+      file = `${file}\n\n ## Raw Schema:${pathToSchema}\n\n${schemaFile}`;
+    }
+  }
+
+  return file;
+};
+
+type VisibilityAudience = 'agents' | 'humans';
+
+const visibilityPattern =
+  /(?:\r?\n){0,2}<Visibility\b(?=[^>]*\bfor=(?:"agents"|'agents'|{["']agents["']}|"humans"|'humans'|{["']humans["']}))[^>]*\bfor=(?:"(agents|humans)"|'(agents|humans)'|{["'](agents|humans)["']})[^>]*>\s*([\s\S]*?)\s*<\/Visibility>(?:\r?\n){0,2}/g;
+
+export const filterMarkdownForAudience = (file: string, audience: VisibilityAudience) => {
+  visibilityPattern.lastIndex = 0;
+  if (!visibilityPattern.test(file)) {
+    return file;
+  }
+  visibilityPattern.lastIndex = 0;
+
+  return file
+    .replace(visibilityPattern, (_match, doubleQuoted, singleQuoted, expressionQuoted, content) => {
+      const visibilityAudience = doubleQuoted || singleQuoted || expressionQuoted;
+      return visibilityAudience === audience ? `\n\n${content.trim()}\n\n` : '\n\n';
+    })
+    .trim();
+};
+
+export const filterMarkdownForAgents = (file: string) => filterMarkdownForAudience(file, 'agents');
diff --git a/packages/core/eventcatalog/src/utils/markdown.ts b/packages/core/eventcatalog/src/utils/markdown.ts
new file mode 100644
index 000000000..111b7deb2
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/markdown.ts
@@ -0,0 +1,35 @@
+// Method returns MDX components and there props in markdown files
+// rarely used, but useful for components that need to know how many times
+// the user wants to render a component in a markdown file
+export const getMDXComponentsByName = (document: string, componentName: string) => {
+  // Define regex pattern to match self-closing MDX components with or without props.
+  const pattern = new RegExp(`<${componentName}(\\s+[^>]*)?\\s*\\/>`, 'g');
+
+  // Find all matches of the pattern
+  const matches = [...document.matchAll(pattern)];
+
+  // Extract the properties of each SchemaViewer
+  const components = matches.map((match) => {
+    const propsString = match[1] || '';
+    const props = {};
+
+    // Use regex to extract key-value pairs from propsString
+    const propsPattern = /(\w+)=["']([^"']+)["']/g;
+    let propMatch;
+    while ((propMatch = propsPattern.exec(propsString)) !== null) {
+      const key = propMatch[1];
+      const value = propMatch[2];
+      // @ts-ignore
+      props[key] = value;
+    }
+
+    return props;
+  });
+
+  return components;
+};
+
+export const parseMdxBooleanProp = (value: unknown, defaultValue: boolean) => {
+  if (value === undefined) return defaultValue;
+  return value === true || value === 'true';
+};
diff --git a/packages/core/eventcatalog/src/utils/mermaid-zoom.ts b/packages/core/eventcatalog/src/utils/mermaid-zoom.ts
new file mode 100644
index 000000000..932be3430
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/mermaid-zoom.ts
@@ -0,0 +1,755 @@
+/**
+ * Diagram Zoom Utility
+ * Provides pan/zoom functionality for Mermaid and PlantUML diagrams with React Flow-style controls
+ *
+ * NOTE: A standalone version of this code also exists in the embed page at:
+ * src/pages/diagrams/[id]/[version]/embed.astro
+ *
+ * The embed page uses CDN imports for isolation in iframes. If you update this file,
+ * please also update the embed page to keep the zoom functionality in sync.
+ */
+
+// Store zoom instances for cleanup
+const zoomInstances = new Map<string, any>();
+const resizeObservers = new Map<string, ResizeObserver>();
+const fullscreenHandlers = new Map<string, () => void>();
+
+// Abort flag for cancelling in-progress renders during cleanup
+let renderingAborted = false;
+
+/**
+ * Destroys all zoom instances and cleans up observers
+ */
+export function destroyZoomInstances(): void {
+  // Set abort flag to cancel any in-progress renders
+  renderingAborted = true;
+
+  zoomInstances.forEach((instance) => {
+    try {
+      instance.destroy();
+    } catch (e) {
+      // Instance may already be destroyed
+    }
+  });
+  zoomInstances.clear();
+
+  resizeObservers.forEach((observer) => {
+    observer.disconnect();
+  });
+  resizeObservers.clear();
+
+  // Clean up fullscreen event listeners
+  fullscreenHandlers.forEach((handler) => {
+    document.removeEventListener('fullscreenchange', handler);
+  });
+  fullscreenHandlers.clear();
+}
+
+/**
+ * Gets an RGB color string from a CSS variable
+ * CSS variables store RGB values as "R G B" format, so we convert to "rgb(R, G, B)"
+ */
+function getCssVariableColor(variableName: string, fallback: string): string {
+  const value = getComputedStyle(document.documentElement).getPropertyValue(variableName).trim();
+  if (value) {
+    // Convert "R G B" format to "rgb(R, G, B)"
+    return `rgb(${value.split(' ').join(', ')})`;
+  }
+  return fallback;
+}
+
+/**
+ * Gets theme colors based on current mode using CSS variables
+ */
+function getThemeColors() {
+  const isDark = document.documentElement.getAttribute('data-theme') === 'dark';
+  return {
+    isDark,
+    bgColor: getCssVariableColor('--ec-card-bg', isDark ? '#161b22' : '#ffffff'),
+    borderColor: getCssVariableColor('--ec-page-border', isDark ? '#30363d' : '#e2e8f0'),
+    iconColor: getCssVariableColor('--ec-icon-color', isDark ? '#8b949e' : '#64748b'),
+    iconHoverColor: getCssVariableColor('--ec-icon-hover', isDark ? '#f0f6fc' : '#0f172a'),
+    hoverBgColor: getCssVariableColor('--ec-content-hover', isDark ? '#21262d' : '#f1f5f9'),
+    overlayBg: getCssVariableColor('--ec-page-bg', isDark ? '#0d1117' : '#ffffff'),
+  };
+}
+
+/**
+ * Creates a styled button with inline CSS
+ */
+function createStyledButton(
+  svg: string,
+  title: string,
+  onClick: () => void,
+  colors: ReturnType<typeof getThemeColors>,
+  options: { isLast?: boolean; isRound?: boolean } = {}
+): HTMLButtonElement {
+  const { isLast = false, isRound = false } = options;
+  const btn = document.createElement('button');
+  btn.type = 'button';
+  btn.title = title;
+  btn.innerHTML = svg;
+  btn.onclick = onClick;
+
+  btn.style.cssText = `
+    all: unset;
+    box-sizing: border-box;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    width: 26px;
+    height: 26px;
+    min-width: 26px;
+    min-height: 26px;
+    padding: 0;
+    margin: 0;
+    border: none;
+    background: ${colors.bgColor};
+    color: ${colors.iconColor};
+    cursor: pointer;
+    transition: background-color 0.15s, color 0.15s;
+    line-height: 1;
+    font-size: 12px;
+    ${!isLast && !isRound ? `border-bottom: 1px solid ${colors.borderColor};` : ''}
+    ${isRound ? 'border-radius: 6px;' : ''}
+  `;
+
+  const svgEl = btn.querySelector('svg');
+  if (svgEl) {
+    svgEl.style.cssText = 'display: block; width: 12px; height: 12px;';
+  }
+
+  btn.onmouseenter = () => {
+    btn.style.backgroundColor = colors.hoverBgColor;
+    btn.style.color = colors.iconHoverColor;
+  };
+  btn.onmouseleave = () => {
+    btn.style.backgroundColor = colors.bgColor;
+    btn.style.color = colors.iconColor;
+  };
+
+  return btn;
+}
+
+/**
+ * SVG icons
+ */
+const ICONS = {
+  plus: `<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="12" y1="5" x2="12" y2="19"></line><line x1="5" y1="12" x2="19" y2="12"></line></svg>`,
+  minus: `<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="5" y1="12" x2="19" y2="12"></line></svg>`,
+  fit: `<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M8 3H5a2 2 0 0 0-2 2v3m18 0V5a2 2 0 0 0-2-2h-3m0 18h3a2 2 0 0 0 2-2v-3M3 16v3a2 2 0 0 0 2 2h3"></path></svg>`,
+  // Heroicons PresentationChartLineIcon (outline)
+  presentation: `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3.75 3v11.25A2.25 2.25 0 006 16.5h2.25M3.75 3h-1.5m1.5 0h16.5m0 0h1.5m-1.5 0v11.25A2.25 2.25 0 0118 16.5h-2.25m-7.5 0h7.5m-7.5 0l-1 3m8.5-3l1 3m0 0l.5 1.5m-.5-1.5h-9.5m0 0l-.5 1.5m.75-9l3-3 2.148 2.148A12.061 12.061 0 0116.5 7.605"></path></svg>`,
+  // Heroicons ClipboardDocumentIcon (outline)
+  copy: `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M8.25 7.5V6.108c0-1.135.845-2.098 1.976-2.192.373-.03.748-.057 1.123-.08M15.75 18H18a2.25 2.25 0 002.25-2.25V6.108c0-1.135-.845-2.098-1.976-2.192a48.424 48.424 0 00-1.123-.08M15.75 18.75v-1.875a3.375 3.375 0 00-3.375-3.375h-1.5a1.125 1.125 0 01-1.125-1.125v-1.5A3.375 3.375 0 006.375 7.5H5.25m11.9-3.664A2.251 2.251 0 0015 2.25h-1.5a2.251 2.251 0 00-2.15 1.586m5.8 0c.065.21.1.433.1.664v.75h-6V4.5c0-.231.035-.454.1-.664M6.75 7.5H4.875c-.621 0-1.125.504-1.125 1.125v12c0 .621.504 1.125 1.125 1.125h9.75c.621 0 1.125-.504 1.125-1.125V16.5a9 9 0 00-9-9z"></path></svg>`,
+  // Heroicons CheckIcon (outline)
+  check: `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>`,
+};
+
+/**
+ * Creates React Flow-style zoom controls
+ */
+function createZoomControls(onZoomIn: () => void, onZoomOut: () => void, onFitView: () => void): HTMLElement {
+  const colors = getThemeColors();
+
+  const controls = document.createElement('div');
+  controls.style.cssText = `
+    position: absolute;
+    bottom: 12px;
+    left: 12px;
+    display: flex;
+    flex-direction: column;
+    background: ${colors.bgColor};
+    border-radius: 6px;
+    box-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
+    border: 1px solid ${colors.borderColor};
+    overflow: hidden;
+    z-index: 10;
+  `;
+
+  controls.appendChild(createStyledButton(ICONS.plus, 'Zoom in', onZoomIn, colors));
+  controls.appendChild(createStyledButton(ICONS.minus, 'Zoom out', onZoomOut, colors));
+  controls.appendChild(createStyledButton(ICONS.fit, 'Fit view', onFitView, colors, { isLast: true }));
+
+  return controls;
+}
+
+/**
+ * Creates a toolbar button with tooltip
+ */
+function createToolbarButton(
+  icon: string,
+  tooltipText: string,
+  onClick: () => void,
+  colors: ReturnType<typeof getThemeColors>,
+  tooltipPosition: 'left' | 'right' | 'bottom' = 'bottom'
+): { wrapper: HTMLElement; btn: HTMLButtonElement; tooltip: HTMLElement } {
+  const wrapper = document.createElement('div');
+  wrapper.style.cssText = `position: relative;`;
+
+  const btn = document.createElement('button');
+  btn.type = 'button';
+  btn.innerHTML = icon;
+  btn.style.cssText = `
+    all: unset;
+    box-sizing: border-box;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    width: 40px;
+    height: 40px;
+    min-width: 40px;
+    min-height: 40px;
+    padding: 0;
+    margin: 0;
+    border: none;
+    border-radius: 6px;
+    background: ${colors.bgColor};
+    color: ${colors.iconColor};
+    cursor: pointer;
+    transition: background-color 0.15s, color 0.15s;
+    box-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
+  `;
+
+  const svgEl = btn.querySelector('svg');
+  if (svgEl) {
+    svgEl.style.cssText = 'display: block; width: 20px; height: 20px;';
+  }
+
+  btn.onmouseenter = () => {
+    btn.style.backgroundColor = colors.hoverBgColor;
+    btn.style.color = colors.iconHoverColor;
+  };
+  btn.onmouseleave = () => {
+    btn.style.backgroundColor = colors.bgColor;
+    btn.style.color = colors.iconColor;
+  };
+  btn.onclick = onClick;
+
+  // Tooltip with position-based styling
+  const tooltip = document.createElement('div');
+  tooltip.textContent = tooltipText;
+
+  let tooltipStyles = `
+    position: absolute;
+    padding: 4px 8px;
+    background: #1f2937;
+    color: white;
+    font-size: 12px;
+    border-radius: 4px;
+    box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+    white-space: nowrap;
+    pointer-events: none;
+    opacity: 0;
+    transition: opacity 0.15s;
+    z-index: 50;
+  `;
+
+  if (tooltipPosition === 'right') {
+    tooltipStyles += `
+      top: 50%;
+      left: 100%;
+      transform: translateY(-50%);
+      margin-left: 8px;
+    `;
+  } else if (tooltipPosition === 'left') {
+    tooltipStyles += `
+      top: 50%;
+      right: 100%;
+      transform: translateY(-50%);
+      margin-right: 8px;
+    `;
+  } else {
+    // Default: bottom
+    tooltipStyles += `
+      top: 100%;
+      left: 50%;
+      transform: translateX(-50%);
+      margin-top: 8px;
+    `;
+  }
+
+  tooltip.style.cssText = tooltipStyles;
+
+  wrapper.onmouseenter = () => {
+    tooltip.style.opacity = '1';
+  };
+  wrapper.onmouseleave = () => {
+    tooltip.style.opacity = '0';
+  };
+
+  wrapper.appendChild(btn);
+  wrapper.appendChild(tooltip);
+
+  return { wrapper, btn, tooltip };
+}
+
+/**
+ * Creates the fullscreen button for top-left (tooltip shows to the right)
+ */
+function createFullscreenButton(onClick: () => void): HTMLElement {
+  const colors = getThemeColors();
+  const { wrapper } = createToolbarButton(ICONS.presentation, 'Presentation Mode', onClick, colors, 'right');
+  wrapper.style.cssText = `
+    position: absolute;
+    top: 12px;
+    left: 12px;
+    z-index: 10;
+  `;
+  return wrapper;
+}
+
+/**
+ * Creates the copy button for top-right (tooltip shows to the left)
+ */
+function createCopyButton(onCopy: () => void): HTMLElement {
+  const colors = getThemeColors();
+  const copy = createToolbarButton(
+    ICONS.copy,
+    'Copy diagram code',
+    () => {
+      onCopy();
+      // Show feedback
+      copy.btn.innerHTML = ICONS.check;
+      copy.btn.style.color = '#10b981'; // Green color for success
+      copy.tooltip.textContent = 'Copied!';
+
+      const svgEl = copy.btn.querySelector('svg');
+      if (svgEl) {
+        svgEl.style.cssText = 'display: block; width: 20px; height: 20px;';
+      }
+
+      setTimeout(() => {
+        copy.btn.innerHTML = ICONS.copy;
+        copy.btn.style.color = colors.iconColor;
+        copy.tooltip.textContent = 'Copy diagram code';
+        const svgEl = copy.btn.querySelector('svg');
+        if (svgEl) {
+          svgEl.style.cssText = 'display: block; width: 20px; height: 20px;';
+        }
+      }, 2000);
+    },
+    colors,
+    'left'
+  );
+
+  copy.wrapper.style.cssText = `
+    position: absolute;
+    top: 12px;
+    right: 12px;
+    z-index: 10;
+  `;
+
+  return copy.wrapper;
+}
+
+/**
+ * Toggles native fullscreen mode on a container
+ */
+function toggleFullscreen(container: HTMLElement): void {
+  if (!document.fullscreenElement) {
+    container.requestFullscreen().catch((err) => {
+      console.warn(`Error entering fullscreen: ${err.message}`);
+    });
+  } else {
+    document.exitFullscreen();
+  }
+}
+
+/**
+ * Creates the zoom container with React Flow-style appearance
+ */
+export function createZoomContainer(): HTMLElement {
+  const container = document.createElement('div');
+  container.className = 'mermaid-zoom-container';
+  container.style.cssText = `
+    position: relative;
+    width: 100%;
+    min-height: 200px;
+    overflow: hidden;
+    margin: 0;
+    cursor: grab;
+  `;
+  return container;
+}
+
+interface ZoomOptions {
+  minZoom?: number;
+  maxZoom?: number;
+  zoomScaleSensitivity?: number;
+  maxHeight?: number;
+  minHeight?: number;
+  diagramContent?: string;
+}
+
+/**
+ * Initializes zoom on a Mermaid SVG element
+ */
+export async function initMermaidZoom(
+  svgElement: SVGElement,
+  container: HTMLElement,
+  id: string,
+  options: ZoomOptions = {}
+): Promise<void> {
+  // Lower zoomScaleSensitivity = smoother but slower zoom
+  const { minZoom = 0.5, maxZoom = 10, zoomScaleSensitivity = 0.15, maxHeight = 500, minHeight = 200, diagramContent } = options;
+
+  // Dynamic import for performance
+  const { default: svgPanZoom } = await import('svg-pan-zoom');
+
+  // Get the natural dimensions from viewBox or getBBox
+  let width: number = 0;
+  let height: number = 0;
+  const viewBox = svgElement.getAttribute('viewBox');
+
+  if (viewBox) {
+    const parts = viewBox.split(/[\s,]+/).map(Number);
+    width = parts[2];
+    height = parts[3];
+  }
+
+  // If viewBox didn't give us dimensions, try getBBox
+  if (width <= 0 || height <= 0) {
+    try {
+      // Cast to SVGGraphicsElement which has getBBox method
+      const bbox = (svgElement as unknown as SVGGraphicsElement).getBBox();
+      width = bbox.width;
+      height = bbox.height;
+      if (width > 0 && height > 0 && !viewBox) {
+        svgElement.setAttribute('viewBox', `${bbox.x} ${bbox.y} ${width} ${height}`);
+      }
+    } catch (e) {
+      // getBBox can fail if SVG isn't in DOM yet
+    }
+  }
+
+  // Fallback to element dimensions if still no size
+  if (width <= 0 || height <= 0) {
+    width = svgElement.clientWidth || parseFloat(svgElement.getAttribute('width') || '0') || 800;
+    height = svgElement.clientHeight || parseFloat(svgElement.getAttribute('height') || '0') || 400;
+  }
+
+  // Set container height based on SVG aspect ratio, capped for usability
+  if (width > 0 && height > 0) {
+    const containerWidth = container.clientWidth || 800;
+    const aspectRatio = height / width;
+    const calculatedHeight = Math.min(Math.max(containerWidth * aspectRatio, minHeight), maxHeight);
+    container.style.height = `${calculatedHeight}px`;
+  } else {
+    container.style.height = `${minHeight}px`;
+  }
+
+  // SVG needs to fill the container for svg-pan-zoom
+  svgElement.style.width = '100%';
+  svgElement.style.height = '100%';
+  svgElement.removeAttribute('height');
+  svgElement.removeAttribute('width');
+
+  try {
+    const instance = svgPanZoom(svgElement, {
+      zoomEnabled: true,
+      controlIconsEnabled: false, // We use custom controls
+      fit: true,
+      center: true,
+      minZoom,
+      maxZoom,
+      zoomScaleSensitivity,
+      dblClickZoomEnabled: true,
+      mouseWheelZoomEnabled: false, // Disabled to avoid hijacking page scroll
+      preventMouseEventsDefault: true,
+      panEnabled: true,
+    });
+
+    zoomInstances.set(id, instance);
+
+    // Update cursor during pan
+    container.addEventListener('mousedown', () => {
+      container.style.cursor = 'grabbing';
+    });
+    container.addEventListener('mouseup', () => {
+      container.style.cursor = 'grab';
+    });
+    container.addEventListener('mouseleave', () => {
+      container.style.cursor = 'grab';
+    });
+
+    // Add custom controls
+    const controls = createZoomControls(
+      () => instance.zoomIn(),
+      () => instance.zoomOut(),
+      () => {
+        instance.fit();
+        instance.center();
+      }
+    );
+    container.appendChild(controls);
+
+    // Add fullscreen button (top-left)
+    const fullscreenBtn = createFullscreenButton(() => toggleFullscreen(container));
+    container.appendChild(fullscreenBtn);
+
+    // Add copy button (top-right) if diagram content is available
+    if (diagramContent) {
+      const copyBtn = createCopyButton(() => {
+        navigator.clipboard.writeText(diagramContent).catch((err) => {
+          console.warn('Failed to copy diagram code:', err);
+        });
+      });
+      container.appendChild(copyBtn);
+    }
+
+    // Handle fullscreen changes - enable scroll zoom in fullscreen, disable when exiting
+    const handleFullscreenChange = () => {
+      const isFullscreen = document.fullscreenElement === container;
+
+      if (isFullscreen) {
+        // Enable scroll zoom in fullscreen
+        instance.enableMouseWheelZoom();
+        // Update container styles for fullscreen
+        container.style.background = getThemeColors().overlayBg;
+      } else {
+        // Disable scroll zoom when not fullscreen
+        instance.disableMouseWheelZoom();
+        // Reset container background
+        container.style.background = '';
+      }
+
+      // Fit and center after transition
+      setTimeout(() => {
+        if (container.clientWidth > 0 && container.clientHeight > 0) {
+          try {
+            instance.resize();
+            instance.fit();
+            instance.center();
+          } catch (e) {
+            // Ignore matrix inversion errors
+          }
+        }
+      }, 100);
+    };
+    document.addEventListener('fullscreenchange', handleFullscreenChange);
+    fullscreenHandlers.set(id, handleFullscreenChange);
+
+    // Resize handler for responsiveness
+    const resizeObserver = new ResizeObserver(() => {
+      // Guard against zero-dimension containers which cause matrix inversion errors
+      if (container.clientWidth > 0 && container.clientHeight > 0) {
+        try {
+          instance.resize();
+          instance.fit();
+          instance.center();
+        } catch (e) {
+          // Ignore matrix inversion errors during resize
+        }
+      }
+    });
+    resizeObserver.observe(container);
+    resizeObservers.set(id, resizeObserver);
+  } catch (e) {
+    console.warn('Failed to initialize zoom on mermaid diagram:', e);
+  }
+}
+
+/**
+ * High-level function to render Mermaid diagrams with zoom
+ */
+export async function renderMermaidWithZoom(graphs: HTMLCollectionOf<Element>, mermaidConfig?: any): Promise<void> {
+  if (graphs.length === 0) return;
+
+  // Reset abort flag at the start of rendering
+  renderingAborted = false;
+
+  const { default: mermaid } = await import('mermaid');
+
+  // Apply any custom mermaid configuration
+  if (mermaidConfig) {
+    const { icons } = await import('@iconify-json/logos');
+    const { iconPacks = [], enableSupportForElkLayout = false } = mermaidConfig;
+
+    if (iconPacks.length > 0) {
+      const iconPacksToRegister = iconPacks.map((name: string) => ({
+        name,
+        icons,
+      }));
+      mermaid.registerIconPacks(iconPacksToRegister);
+    }
+
+    if (enableSupportForElkLayout) {
+      // @ts-ignore
+      const { default: elkLayouts } = await import('@mermaid-js/layout-elk/dist/mermaid-layout-elk.core.mjs');
+      mermaid.registerLayoutLoaders(elkLayouts);
+    }
+  }
+
+  // Detect current theme
+  const isDarkMode = document.documentElement.getAttribute('data-theme') === 'dark';
+  const currentTheme = isDarkMode ? 'dark' : 'default';
+
+  // Custom theme variables for better readability in dark mode
+  const darkThemeVariables = {
+    signalColor: '#f0f6fc',
+    signalTextColor: '#f0f6fc',
+    actorTextColor: '#0d1117',
+    actorBkg: '#f0f6fc',
+    actorBorder: '#484f58',
+    actorLineColor: '#6b7280',
+    primaryTextColor: '#f0f6fc',
+    secondaryTextColor: '#c9d1d9',
+    tertiaryTextColor: '#f0f6fc',
+    lineColor: '#6b7280',
+  };
+
+  mermaid.initialize({
+    maxTextSize: mermaidConfig?.maxTextSize || 100000,
+    flowchart: {
+      curve: 'linear',
+      rankSpacing: 0,
+      nodeSpacing: 0,
+    },
+    startOnLoad: false,
+    fontFamily: 'var(--sans-font)',
+    theme: currentTheme,
+    themeVariables: isDarkMode ? darkThemeVariables : undefined,
+    architecture: {
+      useMaxWidth: true,
+    },
+  });
+
+  // Convert to array to avoid live collection issues when modifying DOM
+  const graphsArray = Array.from(graphs);
+
+  for (const graph of graphsArray) {
+    // Check if rendering was aborted (e.g., user navigated away)
+    if (renderingAborted) return;
+
+    const content = graph.getAttribute('data-content');
+    if (!content) continue;
+
+    const id = 'mermaid-' + Math.round(Math.random() * 100000);
+
+    try {
+      const result = await mermaid.render(id, content);
+
+      // Check again after async operation
+      if (renderingAborted) return;
+
+      // Create zoom container
+      const container = createZoomContainer();
+      container.innerHTML = result.svg;
+
+      // Replace the graph content with the container
+      graph.innerHTML = '';
+      graph.appendChild(container);
+
+      // Initialize zoom on the SVG
+      const svgElement = container.querySelector('svg');
+      if (svgElement) {
+        await initMermaidZoom(svgElement as SVGElement, container, id, { diagramContent: content });
+      }
+    } catch (e) {
+      console.error('Mermaid render error:', e);
+    }
+  }
+}
+
+/**
+ * PlantUML encoding utilities
+ */
+function encode64(data: Uint8Array): string {
+  const chars = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_';
+  let str = '';
+  const len = data.length;
+  for (let i = 0; i < len; i += 3) {
+    const b1 = data[i];
+    const b2 = i + 1 < len ? data[i + 1] : 0;
+    const b3 = i + 2 < len ? data[i + 2] : 0;
+
+    const c1 = b1 >> 2;
+    const c2 = ((b1 & 0x3) << 4) | (b2 >> 4);
+    const c3 = ((b2 & 0xf) << 2) | (b3 >> 6);
+    const c4 = b3 & 0x3f;
+
+    str += chars[c1] + chars[c2] + chars[c3] + chars[c4];
+  }
+  return str;
+}
+
+function encodePlantUML(text: string, deflate: (data: Uint8Array, options: any) => Uint8Array): string {
+  const data = new TextEncoder().encode(text);
+  const compressed = deflate(data, { level: 9, to: 'Uint8Array' });
+  return encode64(compressed);
+}
+
+/**
+ * High-level function to render PlantUML diagrams with zoom
+ */
+export async function renderPlantUMLWithZoom(blocks: HTMLCollectionOf<Element>): Promise<void> {
+  if (blocks.length === 0) return;
+
+  // Dynamic import pako for compression
+  const { deflate } = await import('pako');
+
+  // Reset abort flag AFTER async import to avoid race condition with
+  // destroyZoomInstances() called by astro:page-load handler during the await.
+  // When there are no mermaid diagrams on the page, destroyZoomInstances() sets
+  // renderingAborted=true and renderMermaidWithZoom is never called to reset it,
+  // causing PlantUML rendering to be silently aborted.
+  renderingAborted = false;
+
+  // Convert to array to avoid live collection issues when modifying DOM
+  const blocksArray = Array.from(blocks);
+
+  for (const block of blocksArray) {
+    // Check if rendering was aborted (e.g., user navigated away)
+    if (renderingAborted) return;
+
+    const content = block.getAttribute('data-content');
+    if (!content) continue;
+
+    const id = 'plantuml-' + Math.round(Math.random() * 100000);
+    const encoded = encodePlantUML(content, deflate);
+    const svgUrl = `https://www.plantuml.com/plantuml/svg/~1${encoded}`;
+
+    try {
+      // Fetch SVG content so we can use svg-pan-zoom
+      const response = await fetch(svgUrl);
+
+      // Check again after async operation
+      if (renderingAborted) return;
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch PlantUML diagram: ${response.status}`);
+      }
+
+      const svgText = await response.text();
+
+      // Check again after async operation
+      if (renderingAborted) return;
+
+      // Create zoom container
+      const container = createZoomContainer();
+      container.innerHTML = svgText;
+
+      // Replace the block content with the container
+      block.innerHTML = '';
+      block.appendChild(container);
+
+      // Initialize zoom on the SVG
+      const svgElement = container.querySelector('svg');
+      if (svgElement) {
+        await initMermaidZoom(svgElement as SVGElement, container, id, { diagramContent: content });
+      }
+    } catch (e) {
+      // Fallback to img tag if fetch fails (e.g., CORS issues)
+      console.warn('PlantUML SVG fetch failed, falling back to img:', e);
+      const img = document.createElement('img');
+      img.src = svgUrl;
+      img.alt = 'PlantUML diagram';
+      img.loading = 'lazy';
+      img.style.margin = '0 auto';
+      img.style.display = 'block';
+      block.innerHTML = '';
+      block.appendChild(img);
+    }
+  }
+}
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/agents-node-graph.ts b/packages/core/eventcatalog/src/utils/node-graphs/agents-node-graph.ts
new file mode 100644
index 000000000..673fdcf5c
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/agents-node-graph.ts
@@ -0,0 +1,4 @@
+import { getNodesAndEdges as getServiceLikeNodesAndEdges } from './services-node-graph';
+
+export const getNodesAndEdges = (props: Parameters<typeof getServiceLikeNodesAndEdges>[0]) =>
+  getServiceLikeNodesAndEdges({ ...props, collection: 'agents' });
diff --git a/eventcatalog/src/utils/node-graphs/channel-node-graph.ts b/packages/core/eventcatalog/src/utils/node-graphs/channel-node-graph.ts
similarity index 100%
rename from eventcatalog/src/utils/node-graphs/channel-node-graph.ts
rename to packages/core/eventcatalog/src/utils/node-graphs/channel-node-graph.ts
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/container-node-graph.ts b/packages/core/eventcatalog/src/utils/node-graphs/container-node-graph.ts
new file mode 100644
index 000000000..a5e6df9f5
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/container-node-graph.ts
@@ -0,0 +1,308 @@
+import type { CollectionEntry } from 'astro:content';
+import dagre from 'dagre';
+import {
+  calculatedNodes,
+  createDagreGraph,
+  createEdge,
+  generatedIdForEdge,
+  generateIdForNode,
+  buildContextMenuForService,
+  buildContextMenuForResource,
+  DEFAULT_NODE_WIDTH,
+  DEFAULT_NODE_HEIGHT,
+} from './utils/utils';
+import { MarkerType } from '@xyflow/react';
+import { findMatchingNodes } from '@utils/collections/util';
+import { getContainers } from '@utils/collections/containers';
+
+type DagreGraph = any;
+
+interface Props {
+  id: string;
+  version: string;
+  defaultFlow?: DagreGraph;
+  mode?: 'simple' | 'full';
+  channelRenderMode?: 'flat' | 'single';
+  collection?: CollectionEntry<'containers'>[];
+  layout?: boolean;
+}
+
+export const getNodesAndEdges = async ({
+  id,
+  version,
+  defaultFlow,
+  mode = 'simple',
+  channelRenderMode = 'flat',
+  layout = true,
+}: Props) => {
+  // 1. Fetch data
+  const containers = await getContainers();
+
+  const flow = defaultFlow || createDagreGraph({ ranksep: 300, nodesep: 50 });
+  const nodes = [] as any,
+    edges = [] as any;
+
+  // Optimized: Use find since we're looking for a specific item
+  const container = containers.find((container) => container.data.id === id && container.data.version === version);
+
+  // Nothing found...
+  if (!container) {
+    return {
+      nodes: [],
+      edges: [],
+    };
+  }
+
+  const servicesThatWriteToContainer = (container.data.servicesThatWriteToContainer as CollectionEntry<'services'>[]) || [];
+  const servicesThatReadFromContainer = (container.data.servicesThatReadFromContainer as CollectionEntry<'services'>[]) || [];
+  const dataProductsThatWriteToContainer =
+    (container.data.dataProductsThatWriteToContainer as CollectionEntry<'data-products'>[]) || [];
+  const dataProductsThatReadFromContainer =
+    (container.data.dataProductsThatReadFromContainer as CollectionEntry<'data-products'>[]) || [];
+
+  // Track nodes that are both sent and received
+  const bothSentAndReceived = findMatchingNodes(servicesThatWriteToContainer, servicesThatReadFromContainer);
+  const dataProductsBothSentAndReceived = findMatchingNodes(dataProductsThatWriteToContainer, dataProductsThatReadFromContainer);
+
+  servicesThatWriteToContainer.forEach((service) => {
+    nodes.push({
+      id: generateIdForNode(service),
+      type: service?.collection,
+      sourcePosition: 'right',
+      targetPosition: 'left',
+      data: {
+        mode,
+        service: { ...service.data },
+        contextMenu: buildContextMenuForService({
+          id: service.data.id,
+          version: service.data.version,
+          specifications: (service.data as any).specifications as { type: string; path: string }[],
+          repository: service.data.repository as { url: string },
+        }),
+      },
+      position: { x: 250, y: 0 },
+    });
+
+    if (!bothSentAndReceived.includes(service)) {
+      edges.push({
+        id: generatedIdForEdge(service, container),
+        source: generateIdForNode(service),
+        target: generateIdForNode(container),
+        label: 'writes to',
+        data: { service },
+        animated: false,
+        type: 'default',
+        style: {
+          strokeWidth: 1,
+          stroke: 'var(--ec-edge-stroke, #6b7280)',
+        },
+      });
+    }
+  });
+
+  // Data products that write to the container
+  dataProductsThatWriteToContainer.forEach((dataProduct) => {
+    nodes.push({
+      id: generateIdForNode(dataProduct),
+      type: 'data-products',
+      sourcePosition: 'right',
+      targetPosition: 'left',
+      data: {
+        mode,
+        dataProduct: { ...dataProduct.data },
+        contextMenu: buildContextMenuForResource({
+          collection: 'data-products',
+          id: dataProduct.data.id,
+          version: dataProduct.data.version,
+        }),
+      },
+      position: { x: 250, y: 0 },
+    });
+
+    if (!dataProductsBothSentAndReceived.includes(dataProduct)) {
+      edges.push({
+        id: generatedIdForEdge(dataProduct, container),
+        source: generateIdForNode(dataProduct),
+        target: generateIdForNode(container),
+        label: 'writes to',
+        data: { dataProduct },
+        animated: false,
+        type: 'default',
+        style: {
+          strokeWidth: 1,
+          stroke: 'var(--ec-edge-stroke, #6b7280)',
+        },
+      });
+    }
+  });
+
+  // The container itself
+  nodes.push({
+    id: generateIdForNode(container),
+    sourcePosition: 'right',
+    targetPosition: 'left',
+    data: {
+      mode,
+      data: {
+        ...container.data,
+      },
+      contextMenu: buildContextMenuForResource({
+        collection: 'entities',
+        id: container.data.id,
+        version: container.data.version,
+      }),
+    },
+    position: { x: 0, y: 0 },
+    type: 'data',
+  });
+
+  //   // The messages the service sends
+  servicesThatReadFromContainer.forEach((service) => {
+    nodes.push({
+      id: generateIdForNode(service),
+      sourcePosition: 'left',
+      targetPosition: 'right',
+      data: {
+        title: service?.data.id,
+        mode,
+        service: { ...service.data },
+        contextMenu: buildContextMenuForService({
+          id: service.data.id,
+          version: service.data.version,
+          specifications: (service.data as any).specifications as { type: string; path: string }[],
+          repository: service.data.repository as { url: string },
+        }),
+      },
+      position: { x: 0, y: 0 },
+      type: service?.collection,
+    });
+
+    if (!bothSentAndReceived.includes(service)) {
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(service, container),
+          source: generateIdForNode(container),
+          target: generateIdForNode(service),
+          label: `reads from \n (${container.data.technology})`,
+          data: { service },
+          type: 'multiline',
+          // type: 'animatedData',
+          markerStart: {
+            type: MarkerType.ArrowClosed,
+            width: 20,
+            height: 20,
+          },
+          markerEnd: undefined,
+        })
+      );
+    }
+  });
+
+  // Data products that read from the container
+  dataProductsThatReadFromContainer.forEach((dataProduct) => {
+    nodes.push({
+      id: generateIdForNode(dataProduct),
+      sourcePosition: 'left',
+      targetPosition: 'right',
+      data: {
+        title: dataProduct?.data.id,
+        mode,
+        dataProduct: { ...dataProduct.data },
+        contextMenu: buildContextMenuForResource({
+          collection: 'data-products',
+          id: dataProduct.data.id,
+          version: dataProduct.data.version,
+        }),
+      },
+      position: { x: 0, y: 0 },
+      type: 'data-products',
+    });
+
+    if (!dataProductsBothSentAndReceived.includes(dataProduct)) {
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(dataProduct, container),
+          source: generateIdForNode(container),
+          target: generateIdForNode(dataProduct),
+          label: `reads from \n (${container.data.technology})`,
+          data: { dataProduct },
+          type: 'multiline',
+          markerStart: {
+            type: MarkerType.ArrowClosed,
+            width: 20,
+            height: 20,
+          },
+          markerEnd: undefined,
+        })
+      );
+    }
+  });
+
+  // Handle services that are both sent and received
+  bothSentAndReceived.forEach((_service) => {
+    if (container) {
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(container, _service) + '-both',
+          source: generateIdForNode(_service),
+          target: generateIdForNode(container),
+          label: `read and writes to \n (${container.data.technology})`,
+          type: 'multiline',
+          markerStart: {
+            type: MarkerType.ArrowClosed,
+            width: 20,
+            height: 20,
+          },
+          markerEnd: {
+            type: MarkerType.ArrowClosed,
+            width: 20,
+            height: 20,
+          },
+        })
+      );
+    }
+  });
+
+  // Handle data products that both read and write
+  dataProductsBothSentAndReceived.forEach((_dataProduct) => {
+    if (container) {
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(container, _dataProduct) + '-both',
+          source: generateIdForNode(_dataProduct),
+          target: generateIdForNode(container),
+          label: `read and writes to \n (${container.data.technology})`,
+          type: 'multiline',
+          markerStart: {
+            type: MarkerType.ArrowClosed,
+            width: 20,
+            height: 20,
+          },
+          markerEnd: {
+            type: MarkerType.ArrowClosed,
+            width: 20,
+            height: 20,
+          },
+        })
+      );
+    }
+  });
+
+  nodes.forEach((node: any) => {
+    flow.setNode(node.id, { width: DEFAULT_NODE_WIDTH, height: DEFAULT_NODE_HEIGHT });
+  });
+
+  edges.forEach((edge: any) => {
+    flow.setEdge(edge.source, edge.target);
+  });
+
+  // Render the diagram in memory getting hte X and Y
+  if (layout) {
+    dagre.layout(flow);
+  }
+
+  return {
+    nodes: calculatedNodes(flow, nodes),
+    edges,
+  };
+};
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/data-products-node-graph.ts b/packages/core/eventcatalog/src/utils/node-graphs/data-products-node-graph.ts
new file mode 100644
index 000000000..05919a627
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/data-products-node-graph.ts
@@ -0,0 +1,239 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import dagre from 'dagre';
+import {
+  createDagreGraph,
+  generateIdForNode,
+  generatedIdForEdge,
+  calculatedNodes,
+  createEdge,
+  getColorFromString,
+  buildContextMenuForResource,
+  DEFAULT_NODE_WIDTH,
+  DEFAULT_NODE_HEIGHT,
+} from '@utils/node-graphs/utils/utils';
+
+import { findInMap, createVersionedMap, mergeMaps, collectionToResourceMap } from '@utils/collections/util';
+import { MarkerType } from '@xyflow/react';
+import { getMessages, isCollectionAMessage } from '@utils/collections/messages';
+import { getProducersOfMessage } from '@utils/collections/services';
+import type { CollectionMessageTypes } from '@types';
+import { getNodesAndEdgesForProducedMessage } from './message-node-graph';
+
+type DagreGraph = any;
+
+interface Props {
+  id: string;
+  version: string;
+  defaultFlow?: DagreGraph;
+  mode?: 'simple' | 'full';
+  layout?: boolean;
+}
+
+const getNodePropertyFromCollectionType = (type: string) => {
+  if (isCollectionAMessage(type)) return 'message';
+  if (type === 'containers') return 'data';
+  return collectionToResourceMap[type as keyof typeof collectionToResourceMap];
+};
+
+export const getNodesAndEdges = async ({ id, defaultFlow, version, mode = 'simple', layout = true }: Props) => {
+  const flow = defaultFlow || createDagreGraph({ ranksep: 300, nodesep: 50 });
+  let nodes = [] as any,
+    edges = [] as any;
+
+  const [dataProducts, containers, services, events, queries, commands, channels] = await Promise.all([
+    getCollection('data-products'),
+    getCollection('containers'),
+    getCollection('services'),
+    getCollection('events'),
+    getCollection('queries'),
+    getCollection('commands'),
+    getCollection('channels'),
+  ]);
+
+  const dataProduct = dataProducts.find((dp) => dp.data.id === id && dp.data.version === version);
+
+  // Nothing found...
+  if (!dataProduct) {
+    return {
+      nodes: [],
+      edges: [],
+    };
+  }
+
+  // Build maps for O(1) lookups
+  const messages = [...events, ...commands, ...queries];
+
+  const messageMap = createVersionedMap(messages);
+  const containerMap = createVersionedMap(containers);
+  const serviceMap = createVersionedMap(services);
+  const channelMap = createVersionedMap(channels);
+
+  const inputsRaw = dataProduct?.data.inputs || [];
+  const outputsRaw = dataProduct?.data.outputs || [];
+
+  const resourceMap = mergeMaps<
+    | CollectionEntry<CollectionMessageTypes>
+    | CollectionEntry<'services'>
+    | CollectionEntry<'containers'>
+    | CollectionEntry<'channels'>
+  >(messageMap, serviceMap, containerMap, channelMap);
+
+  // Process inputs - messages, containers, services, channels (etc)
+  inputsRaw.forEach((inputConfig) => {
+    let inputResource = findInMap(resourceMap, inputConfig.id, inputConfig.version) as
+      | CollectionEntry<CollectionMessageTypes>
+      | CollectionEntry<'services'>
+      | CollectionEntry<'containers'>
+      | CollectionEntry<'channels'>;
+
+    const existingNode = nodes.find((n: any) => n.id === generateIdForNode(inputResource));
+
+    if (!existingNode) {
+      const nodeDataKey = getNodePropertyFromCollectionType(inputResource?.collection);
+
+      nodes.push({
+        id: generateIdForNode(inputResource),
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: { mode, [nodeDataKey]: { ...inputResource?.data } },
+        type: (inputResource?.collection as any) === 'containers' ? 'data' : inputResource?.collection,
+      });
+    }
+
+    // If collection is a message we render the producers of the message
+    if (isCollectionAMessage(inputResource?.collection)) {
+      const producersOfMessage = getProducersOfMessage(
+        services as CollectionEntry<'services'>[],
+        inputResource as CollectionEntry<CollectionMessageTypes>
+      ) as CollectionEntry<'services'>[];
+      for (const producer of producersOfMessage) {
+        const { nodes: producerNodes, edges: producerEdges } = getNodesAndEdgesForProducedMessage({
+          message: inputResource as CollectionEntry<CollectionMessageTypes>,
+          // We dont render any other services that consume this event for now
+          services: [],
+          // We dont render channels on this view for now...
+          channels: [],
+          currentNodes: nodes,
+          currentEdges: edges,
+          source: producer,
+          mode,
+        });
+
+        nodes.push(...producerNodes);
+        edges.push(...producerEdges);
+      }
+    }
+
+    // Add edge from resource to data product
+    edges.push(
+      createEdge({
+        id: generatedIdForEdge(inputResource, dataProduct),
+        source: generateIdForNode(inputResource),
+        target: generateIdForNode(dataProduct),
+        label: 'input',
+        type: 'animated',
+        data: {
+          customColor: getColorFromString(inputResource.data.id),
+          rootSourceAndTarget: { source: inputResource, target: dataProduct },
+        },
+        markerEnd: {
+          type: MarkerType.ArrowClosed,
+          color: '#666',
+          width: 20,
+          height: 20,
+        },
+      })
+    );
+  });
+
+  // The data product itself
+  nodes.push({
+    id: generateIdForNode(dataProduct),
+    sourcePosition: 'right',
+    targetPosition: 'left',
+    data: {
+      mode,
+      dataProduct: { ...dataProduct.data },
+      contextMenu: buildContextMenuForResource({
+        collection: 'data-products',
+        id: dataProduct.data.id,
+        version: dataProduct.data.version,
+      }),
+    },
+    type: 'data-products',
+  });
+
+  // Process outputs - messages, services, containers, channels that the data product produces
+  outputsRaw.forEach((outputConfig) => {
+    // Find the output resource (can be message, service, container, or channel)
+    const outputResource = findInMap(resourceMap, outputConfig.id, outputConfig.version) as
+      | CollectionEntry<CollectionMessageTypes>
+      | CollectionEntry<'services'>
+      | CollectionEntry<'containers'>
+      | CollectionEntry<'channels'>;
+
+    if (!outputResource) return;
+
+    // Add the node if it doesn't exist
+    const existingNode = nodes.find((n: any) => n.id === generateIdForNode(outputResource));
+    if (!existingNode) {
+      const nodeDataKey = getNodePropertyFromCollectionType(outputResource?.collection);
+
+      nodes.push({
+        id: generateIdForNode(outputResource),
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: { mode, [nodeDataKey]: { ...outputResource?.data } },
+        type: (outputResource?.collection as any) === 'containers' ? 'data' : outputResource?.collection,
+      });
+    }
+
+    // Add edge from data product to the output resource
+    edges.push(
+      createEdge({
+        id: generatedIdForEdge(dataProduct, outputResource),
+        source: generateIdForNode(dataProduct),
+        target: generateIdForNode(outputResource),
+        label: 'output',
+        type: 'animated',
+        data: {
+          customColor: getColorFromString(outputResource.data.id),
+          rootSourceAndTarget: { source: dataProduct, target: outputResource },
+        },
+        markerEnd: {
+          type: MarkerType.ArrowClosed,
+          color: '#666',
+          width: 20,
+          height: 20,
+        },
+      })
+    );
+  });
+
+  nodes.forEach((node: any) => {
+    flow.setNode(node.id, { width: DEFAULT_NODE_WIDTH, height: DEFAULT_NODE_HEIGHT });
+  });
+
+  edges.forEach((edge: any) => {
+    flow.setEdge(edge.source, edge.target);
+  });
+
+  if (layout) {
+    // Render the diagram in memory getting the X and Y
+    dagre.layout(flow);
+  }
+
+  // Find any duplicated edges, and merge them into one edge
+  const uniqueEdgesById = new Map<string, any>();
+  edges.forEach((edge: any) => {
+    if (!uniqueEdgesById.has(edge.id)) {
+      uniqueEdgesById.set(edge.id, edge);
+    }
+  });
+  const uniqueEdges = Array.from(uniqueEdgesById.values());
+
+  return {
+    nodes: calculatedNodes(flow, nodes),
+    edges: uniqueEdges,
+  };
+};
diff --git a/eventcatalog/src/utils/node-graphs/domain-entity-map.ts b/packages/core/eventcatalog/src/utils/node-graphs/domain-entity-map.ts
similarity index 77%
rename from eventcatalog/src/utils/node-graphs/domain-entity-map.ts
rename to packages/core/eventcatalog/src/utils/node-graphs/domain-entity-map.ts
index 394f42632..d9cda3bda 100644
--- a/eventcatalog/src/utils/node-graphs/domain-entity-map.ts
+++ b/packages/core/eventcatalog/src/utils/node-graphs/domain-entity-map.ts
@@ -2,14 +2,26 @@ import { getCollection, getEntry } from 'astro:content';
 import { generateIdForNode } from './utils/utils';
 import ELK from 'elkjs/lib/elk.bundled.js';
 import { MarkerType } from '@xyflow/react';
-import { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
+import { createVersionedMap, findInMap } from '@utils/collections/util';
 import { getVersionFromCollection } from '@utils/collections/versions';
-import { getEntities, type Entity } from '@utils/entities';
+import { getEntities, type Entity } from '@utils/collections/entities';
 import { getDomains, type Domain } from '@utils/collections/domains';
 import { getServices, type Service } from '@utils/collections/services';
 
 const elk = new ELK();
 
+const getReferencedEntityId = (property: any, entityMap: Map<string, Entity[]>) => {
+  if (property.references) return property.references;
+  if (property.type === 'array' && property.items?.type && entityMap.has(property.items.type)) return property.items.type;
+  return undefined;
+};
+
+const getRelationType = (property: any) => {
+  if (property.relationType) return property.relationType;
+  if (property.type === 'array' && property.items?.type) return 'hasMany';
+  return 'references';
+};
+
 interface Props {
   id: string;
   version: string;
@@ -21,9 +33,9 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
   let nodes = [] as any,
     edges = [] as any;
 
-  const allDomains = await getDomains();
-  const allEntities = await getEntities();
-  const allServices = await getServices();
+  // 1. Fetch all collections in parallel
+  const [allDomains, allEntities, allServices] = await Promise.all([getDomains(), getEntities(), getServices()]);
+  const entityMap = createVersionedMap(allEntities);
 
   let resource = null;
 
@@ -43,7 +55,7 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
   }
 
   const entitiesWithReferences = resourceEntities.filter((entity: Entity) =>
-    entity.data.properties?.some((property: any) => property.references)
+    entity.data.properties?.some((property: any) => getReferencedEntityId(property, entityMap))
   );
   // Creates all the entity nodes for the domain
   for (const entity of resourceEntities) {
@@ -58,21 +70,30 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
 
   // Create entities that are referenced but not owned by this domain
   const listOfReferencedEntities = entitiesWithReferences
-    .map((entity: Entity) => entity.data.properties?.map((property: any) => property.references))
+    .map((entity: Entity) => entity.data.properties?.map((property: any) => getReferencedEntityId(property, entityMap)))
     .flat()
     .filter((ref: any) => ref !== undefined);
 
   const externalToDomain = Array.from(new Set<string>(listOfReferencedEntities as string[])) // Remove duplicates
     .filter((entityId: any) => !resourceEntities.some((domainEntity: any) => domainEntity.id === entityId));
 
+  // 2. Build optimized maps
+  // Only build domain map if we have domains to search
+  // Only build entity map if we have entities to search
   // Helper function to find which domain an entity belongs to
+  // Optimized to use direct iteration over domains (domains usually contain entity arrays)
+  // We can't easily map entity->domain without scanning domains first unless we build a reverse index.
+  // Given domains count is usually manageable, scanning is acceptable, OR we could build an index if needed.
+  // For now, let's keep the scan but make it efficient.
   const findEntityDomain = (entityId: string) => {
     return allDomains.find((domain) => domain.data.entities?.some((domainEntity: any) => domainEntity.data.id === entityId));
   };
 
   const addedExternalEntities = [];
+
   for (const entityId of externalToDomain) {
-    const externalEntity = getItemsFromCollectionByIdAndSemverOrLatest(allEntities, entityId as string, 'latest')[0] as Entity;
+    // 3. Use map lookup
+    const externalEntity = findInMap(entityMap, entityId as string, 'latest') as Entity;
 
     if (externalEntity) {
       const nodeId = generateIdForNode(externalEntity);
@@ -113,12 +134,15 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
   // Go through any entities that are related to other entities
   for (const entity of entitiesWithReferences) {
     // Get a list of properties that reference other entities
-    const allReferencesForEntity = entity.data.properties?.filter((property: any) => property.references) ?? [];
+    const allReferencesForEntity =
+      entity.data.properties?.filter((property: any) => getReferencedEntityId(property, entityMap)) ?? [];
 
     for (const referenceProperty of allReferencesForEntity) {
+      const referencedEntityId = getReferencedEntityId(referenceProperty, entityMap);
+
       // Find the referenced entity by matching the references field with entity IDs
       // Look in both domain entities and external entities
-      const referencedEntity = allEntitiesInGraph.find((targetEntity) => targetEntity.data.id === referenceProperty.references);
+      const referencedEntity = allEntitiesInGraph.find((targetEntity) => targetEntity.data.id === referencedEntityId);
 
       if (referencedEntity) {
         const sourceNodeId = generateIdForNode(entity);
@@ -154,23 +178,19 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
           targetHandle: targetHandle,
           type: 'animated',
           animated: true,
-          label: referenceProperty.relationType || 'references',
+          label: getRelationType(referenceProperty),
           style: {
             strokeWidth: 2,
-            stroke: '#000', // gray color for relationship lines
             strokeDasharray: '5,5', // dashed line
           },
           markerEnd: {
             type: MarkerType.ArrowClosed,
             width: 20,
             height: 20,
-            color: '#000',
           },
         });
       } else {
-        console.warn(
-          `Referenced entity "${referenceProperty.references}" not found for ${entity.data.name}.${referenceProperty.name}`
-        );
+        console.warn(`Referenced entity "${referencedEntityId}" not found for ${entity.data.name}.${referenceProperty.name}`);
       }
     }
   }
@@ -180,10 +200,10 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
   // Separate entities with and without relationships (including external entities)
   const entitiesWithRelationships = allEntitiesInGraph.filter((entity) => {
     // Has outgoing references
-    const hasOutgoingRefs = entity.data.properties?.some((property: any) => property.references);
+    const hasOutgoingRefs = entity.data.properties?.some((property: any) => getReferencedEntityId(property, entityMap));
     // Has incoming references (is referenced by others)
     const hasIncomingRefs = entitiesWithReferences.some((e: any) =>
-      e.data.properties?.some((prop: any) => prop.references === entity.data.id)
+      e.data.properties?.some((prop: any) => getReferencedEntityId(prop, entityMap) === entity.data.id)
     );
     return hasOutgoingRefs || hasIncomingRefs;
   });
diff --git a/eventcatalog/src/utils/node-graphs/domains-canvas.ts b/packages/core/eventcatalog/src/utils/node-graphs/domains-canvas.ts
similarity index 89%
rename from eventcatalog/src/utils/node-graphs/domains-canvas.ts
rename to packages/core/eventcatalog/src/utils/node-graphs/domains-canvas.ts
index 802ca7bba..da8b8b87b 100644
--- a/eventcatalog/src/utils/node-graphs/domains-canvas.ts
+++ b/packages/core/eventcatalog/src/utils/node-graphs/domains-canvas.ts
@@ -1,9 +1,16 @@
 import { getCollection, type CollectionEntry } from 'astro:content';
 import dagre from 'dagre';
-import { generateIdForNode, createDagreGraph, calculatedNodes, createEdge } from '@utils/node-graphs/utils/utils';
-import { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';
+import {
+  generateIdForNode,
+  createDagreGraph,
+  calculatedNodes,
+  createEdge,
+  getOperationFields,
+} from '@utils/node-graphs/utils/utils';
+import { findInMap, createVersionedMap } from '@utils/collections/util';
 import type { Node, Edge } from '@xyflow/react';
 import { getDomains } from '@utils/collections/domains';
+import type { CollectionMessageTypes } from '@types';
 
 interface DomainCanvasData {
   domainNodes: Node[];
@@ -69,10 +76,14 @@ export const getDomainsCanvasData = async (): Promise<DomainCanvasData> => {
     } as Node);
   }
 
-  // Get all messages for version resolution
-  const allMessages = await getCollection('events')
-    .then((events) => Promise.all([events, getCollection('commands'), getCollection('queries')]))
-    .then(([events, commands, queries]) => [...events, ...commands, ...queries]);
+  // Get all messages for version resolution in parallel
+  const [events, commands, queries] = await Promise.all([
+    getCollection('events'),
+    getCollection('commands'),
+    getCollection('queries'),
+  ]);
+  const allMessages = [...events, ...commands, ...queries];
+  const messageMap = createVersionedMap(allMessages);
 
   // Map to track unique messages and their publishers/consumers across domains
   const messageRelationships = new Map<
@@ -89,9 +100,9 @@ export const getDomainsCanvasData = async (): Promise<DomainCanvasData> => {
     domainData.services.forEach((service: any) => {
       // Track messages this service sends
       const sendsRaw = service.data.sends ?? [];
+
       const sendsHydrated = sendsRaw
-        .map((message: any) => getItemsFromCollectionByIdAndSemverOrLatest(allMessages, message.id, message.version))
-        .flat()
+        .map((message: any) => findInMap(messageMap, message.id, message.version))
         .filter((e: any) => e !== undefined);
 
       sendsHydrated.forEach((sentMessage: any) => {
@@ -115,8 +126,7 @@ export const getDomainsCanvasData = async (): Promise<DomainCanvasData> => {
       // Track messages this service receives
       const receivesRaw = service.data.receives ?? [];
       const receivesHydrated = receivesRaw
-        .map((message: any) => getItemsFromCollectionByIdAndSemverOrLatest(allMessages, message.id, message.version))
-        .flat()
+        .map((message: any) => findInMap(messageMap, message.id, message.version))
         .filter((e: any) => e !== undefined);
 
       receivesHydrated.forEach((receivedMessage: any) => {
@@ -154,7 +164,7 @@ export const getDomainsCanvasData = async (): Promise<DomainCanvasData> => {
 
     if (crossesDomainBoundary) {
       // Find the actual message object
-      const messageObject = allMessages.find((m) => m.data.id === message.id && m.data.version === message.version);
+      const messageObject = findInMap(messageMap, message.id, message.version) as CollectionEntry<CollectionMessageTypes>;
 
       if (messageObject) {
         const messageNodeId = `message-${messageKey}`;
@@ -166,7 +176,7 @@ export const getDomainsCanvasData = async (): Promise<DomainCanvasData> => {
           position: { x: 0, y: 0 }, // Temporary position, will be calculated by dagre
           data: {
             mode: 'simple',
-            message: { ...messageObject.data },
+            message: { ...messageObject.data, ...getOperationFields(messageObject.data) },
           },
           sourcePosition: 'right',
           targetPosition: 'left',
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/domains-node-graph.ts b/packages/core/eventcatalog/src/utils/node-graphs/domains-node-graph.ts
new file mode 100644
index 000000000..291d832ef
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/domains-node-graph.ts
@@ -0,0 +1,186 @@
+import { getCollection } from 'astro:content';
+import dagre from 'dagre';
+import {
+  createDagreGraph,
+  calculatedNodes,
+  generateIdForNode,
+  getEdgeLabelForServiceAsTarget,
+  generatedIdForEdge,
+  createEdge,
+} from '@utils/node-graphs/utils/utils';
+import { getNodesAndEdges as getServicesNodeAndEdges } from './services-node-graph';
+import { getNodesAndEdges as getAgentsNodeAndEdges } from './agents-node-graph';
+import { getNodesAndEdges as getDataProductsNodeAndEdges } from './data-products-node-graph';
+import merge from 'lodash.merge';
+import { createVersionedMap, findInMap } from '@utils/collections/util';
+import { getProducersOfMessage } from '@utils/collections/services';
+import { getProducersOfMessage as getAgentProducersOfMessage } from '@utils/collections/agents';
+
+type DagreGraph = any;
+
+interface NodesAndEdgesProps {
+  id: string;
+  version: string;
+  defaultFlow?: DagreGraph;
+  mode: 'simple' | 'full';
+  group?: boolean;
+  channelRenderMode?: 'single' | 'flat';
+  layout?: boolean;
+}
+
+export const getNodesAndEdges = async ({
+  id,
+  version,
+  defaultFlow,
+  mode = 'simple',
+  group = false,
+  channelRenderMode = 'flat',
+  layout = true,
+}: NodesAndEdgesProps) => {
+  const flow = defaultFlow || createDagreGraph({ ranksep: 360, nodesep: 50, edgesep: 50 });
+  let nodes = new Map(),
+    edges = new Map();
+
+  // 1. Parallel Fetching
+  const [domains, services, agents, dataProducts] = await Promise.all([
+    getCollection('domains'),
+    getCollection('services'),
+    getCollection('agents'),
+    getCollection('data-products'),
+  ]);
+
+  const domain = domains.find((service) => service.data.id === id && service.data.version === version);
+
+  // Nothing found...
+  if (!domain) {
+    return {
+      nodes: [],
+      edges: [],
+    };
+  }
+
+  // 2. Build optimized maps
+  const serviceMap = createVersionedMap(services);
+  const agentMap = createVersionedMap(agents);
+  const domainMap = createVersionedMap(domains);
+  const dataProductMap = createVersionedMap(dataProducts);
+
+  const rawServices = domain?.data.services || [];
+  const rawAgents = domain?.data.agents || [];
+  const rawSubDomains = domain?.data.domains || [];
+  const rawDataProducts = (domain?.data as any)['data-products'] || [];
+
+  // Optimized hydration
+  const domainServicesWithVersion = rawServices
+    .map((service) => findInMap(serviceMap, service.id, service.version))
+    .filter((s): s is any => !!s)
+    .map((svc) => ({ id: svc.data.id, version: svc.data.version }));
+
+  const domainAgentsWithVersion = rawAgents
+    .map((agent) => findInMap(agentMap, agent.id, agent.version))
+    .filter((a): a is any => !!a)
+    .map((agent) => ({ id: agent.data.id, version: agent.data.version }));
+
+  const domainSubDomainsWithVersion = rawSubDomains
+    .map((subDomain) => findInMap(domainMap, subDomain.id, subDomain.version))
+    .filter((d): d is any => !!d)
+    .map((svc) => ({ id: svc.data.id, version: svc.data.version }));
+
+  const domainDataProductsWithVersion = rawDataProducts
+    .map((dataProduct: any) => findInMap(dataProductMap, dataProduct.id, dataProduct.version))
+    .filter((dp: any): dp is any => !!dp)
+    .map((dp: any) => ({ id: dp.data.id, version: dp.data.version }));
+
+  // Get all the nodes for everything
+
+  for (const service of domainServicesWithVersion) {
+    const { nodes: serviceNodes, edges: serviceEdges } = await getServicesNodeAndEdges({
+      id: service.id,
+      version: service.version,
+      defaultFlow: flow,
+      mode,
+      renderAllEdges: true,
+      channelRenderMode,
+      layout: false,
+    });
+    serviceNodes.forEach((n) => {
+      /**
+       * A message could be sent by one service and received by another service on the same domain.
+       * So, we need deep merge the message to keep the `showSource` and `showTarget` as true.
+       *
+       * Let's see an example:
+       *  Take an `OrderPlaced` event sent by the `OrderService` `{ showSource: true }` and
+       *  received by `PaymentService` `{ showTarget: true }`.
+       */
+      nodes.set(n.id, nodes.has(n.id) ? merge(nodes.get(n.id), n) : n);
+    });
+    // @ts-ignore
+    serviceEdges.forEach((e) => edges.set(e.id, e));
+  }
+
+  for (const agent of domainAgentsWithVersion) {
+    const { nodes: agentNodes, edges: agentEdges } = await getAgentsNodeAndEdges({
+      id: agent.id,
+      version: agent.version,
+      defaultFlow: flow,
+      mode,
+      renderAllEdges: true,
+      channelRenderMode,
+      layout: false,
+    });
+    agentNodes.forEach((n) => {
+      nodes.set(n.id, nodes.has(n.id) ? merge(nodes.get(n.id), n) : n);
+    });
+    // @ts-ignore
+    agentEdges.forEach((e) => edges.set(e.id, e));
+  }
+
+  for (const dataProduct of domainDataProductsWithVersion) {
+    const { nodes: dataProductNodes, edges: dataProductEdges } = await getDataProductsNodeAndEdges({
+      id: dataProduct.id,
+      version: dataProduct.version,
+      defaultFlow: flow,
+      mode,
+      layout: false,
+    });
+    dataProductNodes.forEach((n: any) => {
+      nodes.set(n.id, nodes.has(n.id) ? merge(nodes.get(n.id), n) : n);
+    });
+    // @ts-ignore
+    dataProductEdges.forEach((e) => edges.set(e.id, e));
+  }
+
+  for (const subDomain of domainSubDomainsWithVersion) {
+    const { nodes: subDomainNodes, edges: subDomainEdges } = await getNodesAndEdges({
+      id: subDomain.id,
+      version: subDomain.version,
+      defaultFlow: flow,
+      mode,
+      group: true,
+      channelRenderMode,
+      layout: false,
+    });
+    subDomainNodes.forEach((n) => {
+      nodes.set(n.id, nodes.has(n.id) ? merge(nodes.get(n.id), n) : n);
+    });
+
+    subDomainEdges.forEach((e) => edges.set(e.id, e));
+  }
+
+  // Add group node to the graph first before calculating positions
+  if (group) {
+    // Update the data of the node to add the group name and color
+    nodes.forEach((n) => {
+      nodes.set(n.id, { ...n, data: { ...n.data, group: { type: 'Domain', value: domain?.data.name, id: domain?.data.id } } });
+    });
+  }
+
+  if (layout) {
+    dagre.layout(flow);
+  }
+
+  return {
+    nodes: calculatedNodes(flow, Array.from(nodes.values())),
+    edges: [...edges.values()],
+  };
+};
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/export-mermaid.ts b/packages/core/eventcatalog/src/utils/node-graphs/export-mermaid.ts
new file mode 100644
index 000000000..2ad302f5c
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/export-mermaid.ts
@@ -0,0 +1,319 @@
+import type { Node, Edge } from '@xyflow/react';
+
+/**
+ * Mermaid Export Utility
+ * Converts React Flow nodes and edges to Mermaid flowchart syntax
+ */
+
+export interface MermaidExportOptions {
+  /** Include class definitions for styling */
+  includeStyles?: boolean;
+  /** Direction of the flowchart: LR (left-right), TB (top-bottom), etc. */
+  direction?: 'LR' | 'TB' | 'RL' | 'BT';
+}
+
+/**
+ * Mapping of node types to their Mermaid shape syntax
+ * Format: [prefix, suffix]
+ */
+const NODE_SHAPE_MAP: Record<string, [string, string]> = {
+  agents: ['[[', ']]'],
+  agent: ['[[', ']]'],
+  agentTool: ['[', ']'],
+  'agent-tool': ['[', ']'],
+  services: ['[[', ']]'], // stadium shape
+  service: ['[[', ']]'],
+  events: ['>', ']'], // flag/asymmetric shape (message-like)
+  event: ['>', ']'],
+  commands: ['>', ']'], // flag/asymmetric shape (message-like)
+  command: ['>', ']'],
+  queries: ['{{', '}}'], // hexagon
+  query: ['{{', '}}'],
+  channels: ['[(', ')]'], // cylinder
+  channel: ['[(', ')]'],
+  domains: ['[', ']'], // rectangle
+  domain: ['[', ']'],
+  flows: ['([', '])'], // stadium (rounded)
+  flow: ['([', '])'],
+  step: ['[', ']'], // rectangle
+  user: ['((', '))'], // circle
+  actor: ['((', '))'], // circle
+  externalSystem: ['[[', ']]'], // stadium
+  'external-system': ['[[', ']]'],
+  data: ['[(', ')]'], // cylinder (database)
+  'data-product': ['[[', ']]'], // stadium
+  'data-products': ['[[', ']]'],
+  entities: ['[', ']'], // rectangle
+  entity: ['[', ']'],
+  custom: ['[', ']'], // rectangle
+  view: ['[', ']'], // rectangle
+  note: ['[', ']'], // rectangle
+};
+
+/**
+ * Mermaid class definitions for styling different node types
+ */
+const NODE_STYLE_CLASSES: Record<string, string> = {
+  agents: 'fill:#0ea5e9,stroke:#0369a1,color:#fff',
+  agent: 'fill:#0ea5e9,stroke:#0369a1,color:#fff',
+  agentTool: 'fill:#8b5cf6,stroke:#6d28d9,color:#fff',
+  'agent-tool': 'fill:#8b5cf6,stroke:#6d28d9,color:#fff',
+  services: 'fill:#ec4899,stroke:#be185d,color:#fff',
+  service: 'fill:#ec4899,stroke:#be185d,color:#fff',
+  events: 'fill:#f97316,stroke:#c2410c,color:#fff',
+  event: 'fill:#f97316,stroke:#c2410c,color:#fff',
+  commands: 'fill:#3b82f6,stroke:#1d4ed8,color:#fff',
+  command: 'fill:#3b82f6,stroke:#1d4ed8,color:#fff',
+  queries: 'fill:#22c55e,stroke:#15803d,color:#fff',
+  query: 'fill:#22c55e,stroke:#15803d,color:#fff',
+  channels: 'fill:#6b7280,stroke:#374151,color:#fff',
+  channel: 'fill:#6b7280,stroke:#374151,color:#fff',
+  domains: 'fill:#eab308,stroke:#a16207,color:#000',
+  domain: 'fill:#eab308,stroke:#a16207,color:#000',
+  flows: 'fill:#14b8a6,stroke:#0f766e,color:#fff',
+  flow: 'fill:#14b8a6,stroke:#0f766e,color:#fff',
+  step: 'fill:#374151,stroke:#1f2937,color:#fff',
+  user: 'fill:#8b5cf6,stroke:#6d28d9,color:#fff',
+  actor: 'fill:#eab308,stroke:#a16207,color:#000',
+  externalSystem: 'fill:#ec4899,stroke:#be185d,color:#fff',
+  'external-system': 'fill:#ec4899,stroke:#be185d,color:#fff',
+  data: 'fill:#3b82f6,stroke:#1d4ed8,color:#fff',
+  'data-product': 'fill:#6366f1,stroke:#4338ca,color:#fff',
+  'data-products': 'fill:#6366f1,stroke:#4338ca,color:#fff',
+  entities: 'fill:#6b7280,stroke:#374151,color:#fff',
+  entity: 'fill:#6b7280,stroke:#374151,color:#fff',
+  custom: 'fill:#9ca3af,stroke:#6b7280,color:#000',
+  view: 'fill:#9ca3af,stroke:#6b7280,color:#000',
+  note: 'fill:#fef3c7,stroke:#d97706,color:#000',
+};
+
+/**
+ * Sanitize a string to be a valid Mermaid node ID
+ * Mermaid IDs should be alphanumeric with underscores
+ */
+export function sanitizeMermaidId(id: string): string {
+  // Replace any non-alphanumeric characters (except underscores) with underscores
+  // Also handle dots and hyphens which are common in version strings
+  return id.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+
+/**
+ * Escape special characters in Mermaid labels
+ */
+function escapeMermaidLabel(label: string): string {
+  // Escape quotes and other special characters
+  return label.replace(/"/g, '#quot;').replace(/\n/g, '<br/>');
+}
+
+/**
+ * Get the Mermaid shape syntax for a node type
+ */
+export function getMermaidNodeShape(type: string): [string, string] {
+  return NODE_SHAPE_MAP[type] || ['[', ']'];
+}
+
+/**
+ * Helper to format label with version
+ */
+function formatLabelWithVersion(name: string, version?: string): string {
+  if (version) {
+    return `${name} (${version})`;
+  }
+  return name;
+}
+
+/**
+ * Extract the display label from a node based on its type and data
+ * Includes version information when available
+ */
+export function getNodeLabel(node: Node): string {
+  const { type, data } = node;
+
+  if (!data) return node.id;
+
+  // Handle different node types and their data structures
+  if (type === 'agents' || type === 'agent') {
+    const agent = (data as any).agent;
+    const name = agent?.name || agent?.id || node.id;
+    const version = agent?.data?.version || agent?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (type === 'agentTool' || type === 'agent-tool') {
+    const agentTool = (data as any).agentTool;
+    return agentTool?.name || agentTool?.id || node.id;
+  }
+
+  if (type === 'services' || type === 'service') {
+    const service = (data as any).service;
+    const name = service?.name || service?.id || node.id;
+    const version = service?.data?.version || service?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (
+    type === 'events' ||
+    type === 'event' ||
+    type === 'commands' ||
+    type === 'command' ||
+    type === 'queries' ||
+    type === 'query'
+  ) {
+    const message = (data as any).message;
+    const name = message?.name || message?.id || node.id;
+    const version = message?.data?.version || message?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (type === 'channels' || type === 'channel') {
+    const channel = (data as any).channel;
+    const name = channel?.name || channel?.id || node.id;
+    const version = channel?.data?.version || channel?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (type === 'domains' || type === 'domain') {
+    const domain = (data as any).domain;
+    // Domain data can be nested in .data
+    const domainData = domain?.data || domain;
+    const name = domainData?.name || domainData?.id || node.id;
+    const version = domainData?.version || domain?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (type === 'flows' || type === 'flow') {
+    const flow = (data as any).flow;
+    const name = flow?.name || flow?.id || node.id;
+    const version = flow?.data?.version || flow?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (type === 'step') {
+    const step = (data as any).step;
+    return step?.title || step?.name || step?.id || node.id;
+  }
+
+  if (type === 'user' || type === 'actor') {
+    return (data as any).name || (data as any).label || (data as any).id || node.id;
+  }
+
+  if (type === 'externalSystem' || type === 'external-system') {
+    const system = (data as any).externalSystem || data;
+    return system?.name || system?.id || node.id;
+  }
+
+  if (type === 'data') {
+    const dataNode = (data as any).data;
+    return dataNode?.name || dataNode?.id || node.id;
+  }
+
+  if (type === 'data-product' || type === 'data-products') {
+    const dataProduct = (data as any).dataProduct;
+    const name = dataProduct?.name || dataProduct?.id || node.id;
+    const version = dataProduct?.data?.version || dataProduct?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (type === 'entities' || type === 'entity') {
+    const entity = (data as any).entity;
+    return entity?.name || entity?.id || node.id;
+  }
+
+  if (type === 'note') {
+    return (data as any).text || (data as any).label || 'Note';
+  }
+
+  // Fallback: try common data patterns
+  return (data as any).name || (data as any).label || (data as any).title || (data as any).id || node.id;
+}
+
+/**
+ * Extract label from an edge
+ */
+function getEdgeLabel(edge: Edge): string | undefined {
+  if (edge.label && typeof edge.label === 'string') {
+    return edge.label;
+  }
+  if (edge.data?.label && typeof edge.data.label === 'string') {
+    return edge.data.label;
+  }
+  return undefined;
+}
+
+/**
+ * Convert React Flow nodes and edges to Mermaid flowchart syntax
+ */
+export function convertToMermaid(nodes: Node[], edges: Edge[], options: MermaidExportOptions = {}): string {
+  const { includeStyles = true, direction = 'LR' } = options;
+
+  const lines: string[] = [];
+
+  // Add flowchart header
+  lines.push(`flowchart ${direction}`);
+
+  // Collect used node types for class definitions
+  const usedTypes = new Set<string>();
+
+  // Add class definitions if styles are enabled
+  if (includeStyles) {
+    lines.push('');
+    lines.push('    %% Style definitions');
+
+    // First pass: collect all used node types
+    nodes.forEach((node) => {
+      if (node.type && NODE_STYLE_CLASSES[node.type]) {
+        usedTypes.add(node.type);
+      }
+    });
+
+    // Add class definitions for used types
+    usedTypes.forEach((type) => {
+      const style = NODE_STYLE_CLASSES[type];
+      if (style) {
+        lines.push(`    classDef ${sanitizeMermaidId(type)} ${style}`);
+      }
+    });
+  }
+
+  // Add node definitions
+  lines.push('');
+  lines.push('    %% Nodes');
+
+  nodes.forEach((node) => {
+    const sanitizedId = sanitizeMermaidId(node.id);
+    const label = escapeMermaidLabel(getNodeLabel(node));
+    const [prefix, suffix] = getMermaidNodeShape(node.type || 'custom');
+
+    let nodeLine = `    ${sanitizedId}${prefix}"${label}"${suffix}`;
+
+    // Add class reference if styles are enabled
+    if (includeStyles && node.type && usedTypes.has(node.type)) {
+      nodeLine += `:::${sanitizeMermaidId(node.type)}`;
+    }
+
+    lines.push(nodeLine);
+  });
+
+  // Add edge definitions
+  lines.push('');
+  lines.push('    %% Edges');
+
+  edges.forEach((edge) => {
+    const sourceId = sanitizeMermaidId(edge.source);
+    const targetId = sanitizeMermaidId(edge.target);
+    const label = getEdgeLabel(edge);
+
+    let edgeLine: string;
+    if (label) {
+      // Clean up multi-line labels
+      const cleanLabel = label.replace(/\n/g, ' ').trim();
+      edgeLine = `    ${sourceId} -->|"${escapeMermaidLabel(cleanLabel)}"| ${targetId}`;
+    } else {
+      edgeLine = `    ${sourceId} --> ${targetId}`;
+    }
+
+    lines.push(edgeLine);
+  });
+
+  return lines.join('\n');
+}
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/export-node-graph.ts b/packages/core/eventcatalog/src/utils/node-graphs/export-node-graph.ts
new file mode 100644
index 000000000..12e88bd4b
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/export-node-graph.ts
@@ -0,0 +1,91 @@
+import type { ReactFlowInstance, Node, ReactFlowJsonObject, Edge } from '@xyflow/react';
+
+// Define the structure of resource data that can be found in nodes
+interface ResourceData {
+  id?: string;
+  name?: string;
+  summary?: string;
+  version?: string;
+}
+
+// Define the possible node data structure
+interface NodeDataWithResources {
+  [key: string]: any;
+  channel?: ResourceData;
+  custom?: ResourceData;
+  data?: ResourceData;
+  domain?: ResourceData;
+  entity?: ResourceData;
+  message?: ResourceData;
+  flow?: ResourceData;
+  agent?: ResourceData;
+  agentTool?: ResourceData;
+  service?: ResourceData;
+  step?: ResourceData;
+  user?: ResourceData;
+}
+
+export const exportNodeGraphForStudio = (data: ReactFlowJsonObject) => {
+  const dataTypes: (keyof NodeDataWithResources)[] = [
+    'channel',
+    'custom',
+    'data',
+    'domain',
+    'entity',
+    'message',
+    'flow',
+    'agent',
+    'agentTool',
+    'service',
+    'step',
+    'user',
+  ];
+
+  // try and remove unwanted data for studio
+  const nodes = data.nodes.map((node: Node) => {
+    let nodeData = node.data as NodeDataWithResources;
+    const dataProperties = Object.keys(nodeData) as (keyof NodeDataWithResources)[];
+
+    // If we find a match.....
+    const hasCustomDataType = dataProperties.find((property) => dataTypes.includes(property));
+
+    if (hasCustomDataType && nodeData[hasCustomDataType]) {
+      const resourceData = nodeData[hasCustomDataType] as ResourceData;
+      nodeData = {
+        ...nodeData,
+        [hasCustomDataType]: {
+          id: resourceData?.id,
+          name: resourceData?.name,
+          summary: resourceData?.summary,
+          version: resourceData?.version,
+        },
+      };
+    }
+
+    return {
+      ...node,
+      data: {
+        ...nodeData,
+        // We dont need these for studio
+        source: undefined,
+        target: undefined,
+        // Studio wants all nodes in full mode
+        mode: 'full',
+      },
+    };
+  });
+
+  const edges = data.edges.map((edge: Edge) => {
+    return {
+      ...edge,
+      data: undefined,
+      type: 'animatedMessage',
+    };
+  });
+
+  return {
+    ...data,
+    nodes,
+    edges,
+  };
+};
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/field-node-graph.ts b/packages/core/eventcatalog/src/utils/node-graphs/field-node-graph.ts
new file mode 100644
index 000000000..10ced908c
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/field-node-graph.ts
@@ -0,0 +1,192 @@
+import type { Node, Edge } from '@xyflow/react';
+import dagre from 'dagre';
+import {
+  createDagreGraph,
+  calculatedNodes,
+  createEdge,
+  createNode,
+  buildContextMenuForMessage,
+  buildContextMenuForService,
+  DEFAULT_NODE_WIDTH,
+  DEFAULT_NODE_HEIGHT,
+} from './utils/utils';
+
+export interface FieldOccurrence {
+  messageId: string;
+  messageVersion: string;
+  messageType: string;
+  messageName?: string;
+  messageSummary?: string;
+  messageOwners?: string[];
+  fieldType?: string;
+  producers: { id: string; version: string; name?: string; summary?: string; owners?: string[] }[];
+  consumers: { id: string; version: string; name?: string; summary?: string; owners?: string[] }[];
+}
+
+interface Props {
+  fieldPath: string;
+  fieldType: string;
+  occurrences: FieldOccurrence[];
+  mode?: 'simple' | 'full';
+}
+
+export const getNodesAndEdges = ({
+  fieldPath,
+  fieldType,
+  occurrences,
+  mode = 'full',
+}: Props): { nodes: Node[]; edges: Edge[] } => {
+  const flow = createDagreGraph({ ranksep: 200, nodesep: 50 });
+  const nodes: Node[] = [];
+  const edges: Edge[] = [];
+  const addedNodes = new Set<string>();
+
+  // Detect distinct types across occurrences
+  const typeCounts = new Map<string, number>();
+  for (const occ of occurrences) {
+    const t = occ.fieldType || fieldType;
+    typeCounts.set(t, (typeCounts.get(t) || 0) + 1);
+  }
+  const hasConflicts = typeCounts.size > 1;
+
+  // Create field node(s) — one per type if conflicts, otherwise a single node
+  const fieldNodeIds = new Map<string, string>();
+
+  if (hasConflicts) {
+    for (const [type] of typeCounts) {
+      const nodeId = `field-${fieldPath}-${type}`;
+      fieldNodeIds.set(type, nodeId);
+      nodes.push(
+        createNode({
+          id: nodeId,
+          type: 'field',
+          position: { x: 0, y: 0 },
+          data: { name: fieldPath, type, mode },
+        })
+      );
+      addedNodes.add(nodeId);
+    }
+  } else {
+    const nodeId = `field-${fieldPath}`;
+    fieldNodeIds.set(fieldType, nodeId);
+    nodes.push(
+      createNode({
+        id: nodeId,
+        type: 'field',
+        position: { x: 0, y: 0 },
+        data: { name: fieldPath, type: fieldType, mode },
+      })
+    );
+    addedNodes.add(nodeId);
+  }
+
+  for (const occ of occurrences) {
+    const msgNodeId = `msg-${occ.messageId}-${occ.messageVersion}`;
+    const occType = occ.fieldType || fieldType;
+    const fieldNodeId = fieldNodeIds.get(occType) || fieldNodeIds.values().next().value!;
+
+    if (!addedNodes.has(msgNodeId)) {
+      nodes.push(
+        createNode({
+          id: msgNodeId,
+          type: occ.messageType,
+          position: { x: 0, y: 0 },
+          data: {
+            message: {
+              name: occ.messageName || occ.messageId,
+              version: occ.messageVersion,
+              summary: occ.messageSummary || '',
+              id: occ.messageId,
+              owners: occ.messageOwners || [],
+            },
+            contextMenu: buildContextMenuForMessage({
+              id: occ.messageId,
+              version: occ.messageVersion,
+              name: occ.messageName || occ.messageId,
+              collection: occ.messageType === 'query' ? 'queries' : `${occ.messageType}s`,
+            }),
+            mode,
+          },
+        })
+      );
+      addedNodes.add(msgNodeId);
+    }
+
+    // Producer services
+    for (const p of occ.producers) {
+      const svcNodeId = `svc-producer-${p.id}-${p.version}`;
+      if (!addedNodes.has(svcNodeId)) {
+        nodes.push(
+          createNode({
+            id: svcNodeId,
+            type: 'service',
+            position: { x: 0, y: 0 },
+            data: {
+              service: { name: p.name || p.id, version: p.version, summary: p.summary || '', id: p.id, owners: p.owners || [] },
+              contextMenu: buildContextMenuForService({ id: p.id, version: p.version }),
+              mode,
+            },
+          })
+        );
+        addedNodes.add(svcNodeId);
+      }
+
+      const prodEdgeId = `e-${svcNodeId}-${msgNodeId}`;
+      if (!edges.find((e) => e.id === prodEdgeId)) {
+        edges.push(createEdge({ id: prodEdgeId, source: svcNodeId, target: msgNodeId, label: 'produces', type: 'smoothstep' }));
+      }
+    }
+
+    // Message → Field (connects to the field node matching this occurrence's type)
+    const msgFieldEdgeId = `e-${msgNodeId}-${fieldNodeId}`;
+    if (!edges.find((e) => e.id === msgFieldEdgeId)) {
+      edges.push(
+        createEdge({
+          id: msgFieldEdgeId,
+          source: msgNodeId,
+          target: fieldNodeId,
+          label: hasConflicts ? `contains (${occType})` : 'contains',
+          type: 'smoothstep',
+        })
+      );
+    }
+
+    // Field → Consumer services (from the specific field type node)
+    for (const c of occ.consumers) {
+      const svcNodeId = `svc-consumer-${c.id}-${c.version}`;
+      if (!addedNodes.has(svcNodeId)) {
+        nodes.push(
+          createNode({
+            id: svcNodeId,
+            type: 'service',
+            position: { x: 0, y: 0 },
+            data: {
+              service: { name: c.name || c.id, version: c.version, summary: c.summary || '', id: c.id, owners: c.owners || [] },
+              contextMenu: buildContextMenuForService({ id: c.id, version: c.version }),
+              mode,
+            },
+          })
+        );
+        addedNodes.add(svcNodeId);
+      }
+
+      const consEdgeId = `e-${fieldNodeId}-${svcNodeId}`;
+      if (!edges.find((e) => e.id === consEdgeId)) {
+        edges.push(
+          createEdge({ id: consEdgeId, source: fieldNodeId, target: svcNodeId, label: 'consumed by', type: 'smoothstep' })
+        );
+      }
+    }
+  }
+
+  // Apply layout
+  for (const node of nodes) {
+    flow.setNode(node.id, { width: DEFAULT_NODE_WIDTH, height: DEFAULT_NODE_HEIGHT });
+  }
+  for (const edge of edges) {
+    flow.setEdge(edge.source, edge.target);
+  }
+  dagre.layout(flow);
+
+  return { nodes: calculatedNodes(flow, nodes), edges };
+};
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/flows-node-graph.ts b/packages/core/eventcatalog/src/utils/node-graphs/flows-node-graph.ts
new file mode 100644
index 000000000..0cd4394f1
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/flows-node-graph.ts
@@ -0,0 +1,330 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import dagre from 'dagre';
+import {
+  createDagreGraph,
+  calculatedNodes,
+  DEFAULT_NODE_WIDTH,
+  DEFAULT_NODE_HEIGHT,
+  buildContextMenuForResource,
+  buildContextMenuForService,
+} from '@utils/node-graphs/utils/utils';
+import { MarkerType } from '@xyflow/react';
+import type { Node as NodeType } from '@xyflow/react';
+import { createVersionedMap, findInMap } from '@utils/collections/util';
+
+type DagreGraph = any;
+
+interface Props {
+  id: string;
+  version: string;
+  defaultFlow?: DagreGraph;
+  mode?: 'simple' | 'full';
+  renderAllEdges?: boolean;
+}
+
+interface Maps {
+  messageMap: Map<string, any[]>;
+  agentMap: Map<string, any[]>;
+  serviceMap: Map<string, any[]>;
+  flowMap: Map<string, any[]>;
+  containerMap: Map<string, any[]>;
+  dataProductMap: Map<string, any[]>;
+}
+
+const getServiceNode = (step: any, serviceMap: Map<string, any[]>) => {
+  const service = findInMap(serviceMap, step.service.id, step.service.version);
+  return {
+    ...step,
+    type: service ? service.collection : 'step',
+    service,
+  };
+};
+
+const getAgentNode = (step: any, agentMap: Map<string, any[]>) => {
+  const agent = findInMap(agentMap, step.agent.id, step.agent.version);
+  return {
+    ...step,
+    type: agent ? agent.collection : 'step',
+    agent,
+  };
+};
+
+const getFlowNode = (step: any, flowMap: Map<string, any[]>) => {
+  const flow = findInMap(flowMap, step.flow.id, step.flow.version);
+  return {
+    ...step,
+    type: flow ? flow.collection : 'step',
+    flow,
+  };
+};
+
+const getContainerNode = (step: any, containerMap: Map<string, any[]>) => {
+  const pointer = step.container;
+  const container = findInMap(containerMap, pointer.id, pointer.version);
+  return {
+    ...step,
+    type: container ? 'data' : 'step',
+    container,
+  };
+};
+
+const getDataProductNode = (step: any, dataProductMap: Map<string, any[]>) => {
+  const pointer = step.dataProduct;
+  const dataProduct = findInMap(dataProductMap, pointer.id, pointer.version);
+  return {
+    ...step,
+    type: dataProduct ? 'data-products' : 'step',
+    dataProduct,
+  };
+};
+
+const getMessageNode = (step: any, messageMap: Map<string, any[]>) => {
+  const message = findInMap(messageMap, step.message.id, step.message.version);
+  return {
+    ...step,
+    type: message ? message.collection : 'step',
+    message,
+  };
+};
+
+// Rewrite every id/source/target in a precomputed sub-flow graph with a
+// namespace prefix so inlined copies don't collide with the parent. Nested
+// `data.expandedNodes` / `data.expandedEdges` payloads are rewritten too so
+// the namespace chain stays unique when the same sub-flow is inlined under
+// multiple parents.
+const prefixGraph = (graph: { nodes: any[]; edges: any[] }, prefix: string) => {
+  if (!prefix) return graph;
+  const nodes = graph.nodes.map((n) => {
+    const next: any = { ...n, id: `${prefix}${n.id}` };
+    if (n.data?.expandedNodes || n.data?.expandedEdges) {
+      const nested = prefixGraph({ nodes: n.data.expandedNodes ?? [], edges: n.data.expandedEdges ?? [] }, prefix);
+      next.data = { ...n.data, expandedNodes: nested.nodes, expandedEdges: nested.edges };
+    }
+    return next;
+  });
+  const edges = graph.edges.map((e) => ({
+    ...e,
+    id: `${prefix}${e.id}`,
+    source: `${prefix}${e.source}`,
+    target: `${prefix}${e.target}`,
+  }));
+  return { nodes, edges };
+};
+
+// `subFlowCache` keys each flow's graph by `id@version` so an N-times
+// referenced sub-flow is built once. `visited` short-circuits cycles.
+const buildFlowGraphInternal = (
+  flow: any,
+  maps: Maps,
+  mode: 'simple' | 'full',
+  subFlowCache: Map<string, { nodes: any[]; edges: any[] }>,
+  visited: Set<string>
+) => {
+  const nodes: any[] = [];
+  const edges: any[] = [];
+
+  const steps = flow?.data?.steps || [];
+  const stepNodeId = (stepId: any) => `step-${stepId}`;
+
+  const hydratedSteps = steps.map((step: any) => {
+    if (step.agent) return getAgentNode(step, maps.agentMap);
+    if (step.service) return getServiceNode(step, maps.serviceMap);
+    if (step.flow) return getFlowNode(step, maps.flowMap);
+    if (step.container) return getContainerNode(step, maps.containerMap);
+    if (step.dataProduct) return getDataProductNode(step, maps.dataProductMap);
+    if (step.message) return getMessageNode(step, maps.messageMap);
+    if (step.actor) return { ...step, type: 'actor', actor: step.actor };
+    if (step.custom) return { ...step, type: 'custom', custom: step.custom };
+    if (step.externalSystem) return { ...step, type: 'externalSystem', externalSystem: step.externalSystem };
+    return { ...step, type: 'step' };
+  });
+
+  hydratedSteps.forEach((step: any, index: number) => {
+    const node: NodeType = {
+      id: stepNodeId(step.id),
+      sourcePosition: 'right',
+      targetPosition: 'left',
+      data: {
+        mode,
+        step: { ...step, ...step.data },
+        showTarget: true,
+        showSource: true,
+      },
+      position: { x: 250, y: index * 150 },
+      type: step.type,
+    } as NodeType;
+
+    if (step.agent) {
+      node.data.agent = { ...step.agent, ...step.agent.data };
+      node.data.contextMenu = buildContextMenuForResource({
+        collection: 'agents',
+        id: step.agent.data.id,
+        version: step.agent.data.version,
+      });
+    }
+    if (step.service) {
+      node.data.service = { ...step.service, ...step.service.data };
+      node.data.contextMenu = buildContextMenuForService({
+        id: step.service.data.id,
+        version: step.service.data.version,
+        specifications: step.service.data.specifications,
+        repository: step.service.data.repository,
+      });
+    }
+    if (step.flow) {
+      node.data.flow = { ...step.flow, ...step.flow.data };
+      node.data.contextMenu = buildContextMenuForResource({
+        collection: 'flows',
+        id: step.flow.data.id,
+        version: step.flow.data.version,
+      });
+
+      // Guard cycles; inline the sub-flow's graph so the client can expand on click.
+      const subFlowKey = `${step.flow.data.id}@${step.flow.data.version}`;
+      if (!visited.has(subFlowKey)) {
+        let cached = subFlowCache.get(subFlowKey);
+        if (!cached) {
+          cached = buildFlowGraphInternal(step.flow, maps, mode, subFlowCache, new Set([...visited, subFlowKey]));
+          subFlowCache.set(subFlowKey, cached);
+        }
+        if (cached.nodes.length > 0) {
+          const { nodes: childNodes, edges: childEdges } = prefixGraph(cached, `${node.id}__`);
+          node.data.expandedNodes = childNodes;
+          node.data.expandedEdges = childEdges;
+        }
+      }
+    }
+    if (step.message) {
+      node.data.message = { ...step.message, ...step.message.data };
+      node.data.contextMenu = buildContextMenuForResource({
+        collection: step.message.collection,
+        id: step.message.data.id,
+        version: step.message.data.version,
+      });
+    }
+    if (step.container?.data) {
+      node.data.data = { ...step.container.data };
+      node.data.container = { ...step.container, ...step.container.data };
+      node.data.contextMenu = buildContextMenuForResource({
+        collection: 'containers',
+        id: step.container.data.id,
+        version: step.container.data.version,
+      });
+    }
+    if (step.dataProduct?.data) {
+      node.data.dataProduct = { ...step.dataProduct, ...step.dataProduct.data };
+      node.data.contextMenu = buildContextMenuForResource({
+        collection: 'data-products',
+        id: step.dataProduct.data.id,
+        version: step.dataProduct.data.version,
+      });
+    }
+    if (step.actor) {
+      node.data.actor = { ...step.actor, ...step.actor.data };
+      node.data = { ...node.data, ...step.actor };
+    }
+    if (step.externalSystem) node.data.externalSystem = { ...step.externalSystem, ...step.externalSystem.data };
+    if (step.custom) node.data.custom = { ...step.custom, ...step.custom.data };
+    nodes.push(node);
+  });
+
+  hydratedSteps.forEach((step: any) => {
+    let paths = step.next_steps || [];
+
+    if (step.next_step) {
+      if (!step.next_step?.id) {
+        paths = [{ id: step.next_step }];
+      } else {
+        paths = [step.next_step];
+      }
+    }
+
+    paths = paths.map((path: any) => {
+      if (typeof path === 'string') {
+        return { id: path };
+      }
+      return path;
+    });
+
+    paths.forEach((path: any) => {
+      edges.push({
+        id: `step-${step.id}-step-${path.id}`,
+        source: stepNodeId(step.id),
+        target: stepNodeId(path.id),
+        type: 'flow-edge',
+        label: path.label,
+        animated: true,
+        markerEnd: {
+          type: MarkerType.ArrowClosed,
+          width: 20,
+          height: 20,
+          color: '#666',
+        },
+        style: {
+          strokeWidth: 2,
+          stroke: '#ccc',
+        },
+      });
+    });
+  });
+
+  return { nodes, edges };
+};
+
+export const getNodesAndEdges = async ({ id, defaultFlow, version, mode = 'simple', renderAllEdges = false }: Props) => {
+  const graph = defaultFlow || createDagreGraph({ ranksep: 360, nodesep: 200 });
+
+  const [flows, events, commands, queries, agents, services, containers, dataProducts] = await Promise.all([
+    getCollection('flows'),
+    getCollection('events'),
+    getCollection('commands'),
+    getCollection('queries'),
+    getCollection('agents'),
+    getCollection('services'),
+    getCollection('containers'),
+    getCollection('data-products'),
+  ]);
+
+  const flow = flows.find((flow) => flow.data.id === id && flow.data.version === version);
+
+  if (!flow) {
+    return {
+      nodes: [],
+      edges: [],
+    };
+  }
+
+  const messages = [...events, ...commands, ...queries];
+  const maps: Maps = {
+    messageMap: createVersionedMap(messages),
+    agentMap: createVersionedMap(agents),
+    serviceMap: createVersionedMap(services),
+    flowMap: createVersionedMap(flows),
+    containerMap: createVersionedMap(containers),
+    dataProductMap: createVersionedMap(dataProducts),
+  };
+
+  const subFlowCache = new Map<string, { nodes: any[]; edges: any[] }>();
+  const { nodes, edges } = buildFlowGraphInternal(
+    flow,
+    maps,
+    mode,
+    subFlowCache,
+    new Set([`${flow.data.id}@${flow.data.version}`])
+  );
+
+  nodes.forEach((node: any) => {
+    graph.setNode(node.id, { width: DEFAULT_NODE_WIDTH, height: DEFAULT_NODE_HEIGHT });
+  });
+
+  edges.forEach((edge: any) => {
+    graph.setEdge(edge.source, edge.target);
+  });
+
+  dagre.layout(graph);
+
+  return {
+    nodes: calculatedNodes(graph, nodes),
+    edges: edges,
+  };
+};
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/layout-persistence.ts b/packages/core/eventcatalog/src/utils/node-graphs/layout-persistence.ts
new file mode 100644
index 000000000..f2ab56167
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/layout-persistence.ts
@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface SavedPosition {
+  x: number;
+  y: number;
+}
+
+export interface SavedLayout {
+  version: number;
+  savedAt: string;
+  resourceKey: string;
+  positions: Record<string, SavedPosition>;
+}
+
+/**
+ * Builds a resource key for layout persistence from collection, id, and version.
+ * e.g., buildResourceKey('services', 'OrderService', '1.0.0') -> 'services/OrderService/1.0.0'
+ */
+export function buildResourceKey(collection: string, id: string, version?: string): string {
+  if (version) {
+    return `${collection}/${id}/${version}`;
+  }
+  return `${collection}/${id}`;
+}
+
+/**
+ * Converts a resource key to a file path for the saved layout
+ * e.g., services/OrderService/1.0.0 -> _data/visualizer-layouts/services/OrderService/1.0.0.json
+ * Uses path.join with spread segments for cross-platform compatibility (Windows/Mac/Linux)
+ */
+export function getLayoutFilePath(resourceKey: string): string {
+  const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd();
+  const cleanKey = resourceKey.replace(/^\//, '').replace(/\/$/, '');
+  // Split path segments and rejoin with platform-specific separator
+  const segments = cleanKey.split('/').filter(Boolean);
+  const fileName = `${segments.pop()}.json`;
+  return path.join(PROJECT_DIR, '_data', 'visualizer-layouts', ...segments, fileName);
+}
+
+/**
+ * Loads saved layout from disk if it exists
+ */
+export async function loadSavedLayout(resourceKey: string): Promise<SavedLayout | null> {
+  const filePath = getLayoutFilePath(resourceKey);
+
+  try {
+    const content = await fs.promises.readFile(filePath, 'utf-8');
+    return JSON.parse(content) as SavedLayout;
+  } catch {
+    // File doesn't exist or parse error - return null
+    return null;
+  }
+}
+
+/**
+ * Applies saved positions to nodes. Nodes with saved positions get them applied,
+ * nodes without saved positions keep their Dagre-calculated positions.
+ */
+export function applyLayoutToNodes<T extends { id: string; position: { x: number; y: number } }>(
+  nodes: T[],
+  savedLayout: SavedLayout | null
+): T[];
+export function applyLayoutToNodes(nodes: any[], savedLayout: SavedLayout | null): any[] {
+  if (!savedLayout) {
+    return nodes; // No saved layout, use original Dagre positions
+  }
+
+  return nodes.map((node) => {
+    const savedPosition = savedLayout.positions[node.id];
+    if (savedPosition) {
+      // Use saved position
+      return {
+        ...node,
+        position: { x: savedPosition.x, y: savedPosition.y },
+      };
+    }
+    // Keep Dagre-calculated position for new/unmatched nodes
+    return node;
+  });
+}
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/message-node-graph.ts b/packages/core/eventcatalog/src/utils/node-graphs/message-node-graph.ts
new file mode 100644
index 000000000..857a521bc
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/message-node-graph.ts
@@ -0,0 +1,1272 @@
+// import { getColor } from '@utils/colors';
+import { getEvents } from '@utils/collections/events';
+import type { CollectionEntry } from 'astro:content';
+import dagre from 'dagre';
+import {
+  calculatedNodes,
+  createDagreGraph,
+  createEdge,
+  generatedIdForEdge,
+  generateIdForNode,
+  getColorFromString,
+  getEdgeLabelForMessageAsSource,
+  getEdgeLabelForServiceAsTarget,
+  versionMatches,
+} from './utils/utils';
+import { MarkerType, type Node, type Edge } from '@xyflow/react';
+import {
+  findMatchingNodes,
+  getItemsFromCollectionByIdAndSemverOrLatest,
+  getLatestVersionInCollectionById,
+  createVersionedMap,
+  findInMap,
+} from '@utils/collections/util';
+import type { CollectionMessageTypes } from '@types';
+import { getCommands } from '@utils/collections/commands';
+import { getQueries } from '@utils/collections/queries';
+import {
+  createNode,
+  buildContextMenuForMessage,
+  buildContextMenuForAgent,
+  buildContextMenuForService,
+  buildContextMenuForResource,
+  getOperationFields,
+  DEFAULT_NODE_WIDTH,
+  DEFAULT_NODE_HEIGHT,
+} from './utils/utils';
+import { getConsumersOfMessage, getProducersOfMessage } from '@utils/collections/services';
+import {
+  getConsumersOfMessage as getAgentConsumersOfMessage,
+  getProducersOfMessage as getAgentProducersOfMessage,
+} from '@utils/collections/agents';
+import { getNodesAndEdgesForChannelChain } from './channel-node-graph';
+import { getChannelChain, isChannelsConnected } from '@utils/collections/channels';
+import { getChannels } from '@utils/collections/channels';
+
+type DagreGraph = any;
+type RoutableResource = CollectionEntry<'agents'> | CollectionEntry<'services'>;
+type ProducerConsumerResource = RoutableResource | CollectionEntry<'data-products'>;
+
+interface Props {
+  id: string;
+  version: string;
+  defaultFlow?: DagreGraph;
+  mode?: 'simple' | 'full';
+  channelRenderMode?: 'flat' | 'single';
+  collection?: CollectionEntry<CollectionMessageTypes>[];
+  channels?: CollectionEntry<'channels'>[];
+}
+
+const isAgent = (resource: ProducerConsumerResource | RoutableResource): resource is CollectionEntry<'agents'> =>
+  resource.collection === 'agents';
+const isDataProduct = (resource: ProducerConsumerResource): resource is CollectionEntry<'data-products'> =>
+  resource.collection === 'data-products';
+
+const getRoutableContextMenu = (resource: RoutableResource) => {
+  if (isAgent(resource)) {
+    return buildContextMenuForAgent({
+      id: resource.data.id,
+      version: resource.data.version,
+      repository: resource.data.repository as { url: string },
+    });
+  }
+
+  return buildContextMenuForService({
+    id: resource.data.id,
+    version: resource.data.version,
+    specifications: (resource.data as any).specifications,
+    repository: (resource.data as any).repository,
+  });
+};
+
+const getRoutableNodeData = (resource: RoutableResource, mode: 'simple' | 'full') => ({
+  title: resource.data.id,
+  mode,
+  ...(isAgent(resource) ? { agent: { ...resource.data } } : { service: { ...resource.data } }),
+  contextMenu: getRoutableContextMenu(resource),
+});
+
+const sanitizeToolId = (name: string) =>
+  name
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '')
+    .toLowerCase();
+
+const generateIdForAgentToolNode = (agent: RoutableResource, tool: { name: string; type: string }) =>
+  `${generateIdForNode(agent)}-tool-${sanitizeToolId(`${tool.name}-${tool.type}`)}`;
+
+const appendAgentToolNodesAndEdges = ({
+  agent,
+  nodes,
+  edges,
+  mode,
+}: {
+  agent: RoutableResource;
+  nodes: Node[];
+  edges: Edge[];
+  mode: 'simple' | 'full';
+}) => {
+  if (!isAgent(agent)) return;
+
+  (agent.data.tools || []).forEach((tool) => {
+    const toolNodeId = generateIdForAgentToolNode(agent, tool);
+
+    nodes.push(
+      createNode({
+        id: toolNodeId,
+        type: 'agentTool',
+        data: {
+          mode,
+          agentTool: {
+            id: sanitizeToolId(`${tool.name}-${tool.type}`),
+            name: tool.name,
+            type: tool.type,
+            icon: tool.icon,
+            url: tool.url,
+            description: tool.description,
+          },
+          contextMenu: tool.url
+            ? [
+                {
+                  label: 'Open tool endpoint',
+                  href: tool.url,
+                  external: true,
+                },
+              ]
+            : undefined,
+        },
+        position: { x: 0, y: 0 },
+      })
+    );
+
+    edges.push(
+      createEdge({
+        id: `${generateIdForNode(agent)}-${toolNodeId}`,
+        source: generateIdForNode(agent),
+        target: toolNodeId,
+        label: 'calls tool',
+        type: 'step',
+        animated: false,
+        data: { animated: false },
+        markerEnd: {
+          type: MarkerType.ArrowClosed,
+          color: '#666',
+          width: 20,
+          height: 20,
+        },
+      })
+    );
+  });
+};
+
+const getDataProductNodeData = (resource: CollectionEntry<'data-products'>, mode: 'simple' | 'full') => ({
+  title: resource.data.id,
+  mode,
+  dataProduct: { ...resource.data },
+  contextMenu: buildContextMenuForResource({ collection: 'data-products', id: resource.data.id, version: resource.data.version }),
+});
+
+const getNodesAndEdges = async ({
+  id,
+  version,
+  defaultFlow,
+  mode = 'simple',
+  channelRenderMode = 'flat',
+  collection = [],
+  channels = [],
+}: Props) => {
+  const flow = defaultFlow || createDagreGraph({ ranksep: 300, nodesep: 50 });
+  const nodes = [] as any,
+    edges = [] as any;
+
+  const message = collection.find((message) => {
+    return message.data.id === id && message.data.version === version;
+  });
+
+  // Nothing found...
+  if (!message) {
+    return {
+      nodes: [],
+      edges: [],
+    };
+  }
+
+  // Pre-calculate channel map for O(1) lookups
+  const channelMap = createVersionedMap(channels);
+
+  // We always render the message itself
+  nodes.push({
+    id: generateIdForNode(message),
+    sourcePosition: 'right',
+    targetPosition: 'left',
+    data: {
+      mode,
+      message: {
+        ...message.data,
+        ...getOperationFields(message.data),
+      },
+      contextMenu: buildContextMenuForMessage({
+        id: message.data.id,
+        version: message.data.version,
+        name: message.data.name,
+        collection: message.collection,
+        schemaPath: (message.data as any).schemaPath,
+      }),
+    },
+    position: { x: 0, y: 0 },
+    type: message.collection,
+  });
+
+  const producers = (message.data.producers as ProducerConsumerResource[]) || [];
+  const consumers = (message.data.consumers as ProducerConsumerResource[]) || [];
+
+  // Track nodes that are both sent and received (only service-like resources)
+  const routableProducers = producers.filter(
+    (p) => p.collection === 'services' || p.collection === 'agents'
+  ) as RoutableResource[];
+  const routableConsumers = consumers.filter(
+    (c) => c.collection === 'services' || c.collection === 'agents'
+  ) as RoutableResource[];
+  const bothSentAndReceived = findMatchingNodes(routableProducers as any, routableConsumers as any);
+
+  for (const producer of producers) {
+    nodes.push({
+      id: generateIdForNode(producer),
+      type: isDataProduct(producer) ? 'data-products' : producer.collection,
+      sourcePosition: 'right',
+      targetPosition: 'left',
+      data: isDataProduct(producer) ? getDataProductNodeData(producer, mode) : getRoutableNodeData(producer, mode),
+      position: { x: 250, y: 0 },
+    });
+    if (!isDataProduct(producer)) {
+      appendAgentToolNodesAndEdges({ agent: producer, nodes, edges, mode });
+    }
+
+    // Data products don't have channel configuration, so connect directly to the message
+    if (isDataProduct(producer)) {
+      const rootSourceAndTarget = {
+        source: { id: generateIdForNode(producer), collection: producer.collection },
+        target: { id: generateIdForNode(message), collection: message.collection },
+      };
+
+      edges.push({
+        id: generatedIdForEdge(producer, message),
+        source: generateIdForNode(producer),
+        target: generateIdForNode(message),
+        label: 'produces',
+        data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+        animated: false,
+        markerEnd: {
+          type: MarkerType.ArrowClosed,
+          width: 20,
+          height: 20,
+        },
+      });
+      continue;
+    }
+
+    // Service/agent-specific channel handling
+    const routableProducer = producer as RoutableResource;
+
+    // Is the producer sending this message to a channel?
+    const producerConfigurationForMessage = routableProducer.data.sends?.find(
+      (send) => send.id === message.data.id && versionMatches(send.version, message.data.version)
+    );
+    const producerChannelConfiguration = producerConfigurationForMessage?.to ?? [];
+
+    const producerHasChannels = producerChannelConfiguration?.length > 0;
+
+    const rootSourceAndTarget = {
+      source: { id: generateIdForNode(producer), collection: producer.collection },
+      target: { id: generateIdForNode(message), collection: message.collection },
+    };
+
+    // If the producer does not have any channels defined, then we just connect the producer to the event directly
+    if (!producerHasChannels) {
+      edges.push({
+        id: generatedIdForEdge(producer, message),
+        source: generateIdForNode(producer),
+        target: generateIdForNode(message),
+        label: getEdgeLabelForServiceAsTarget(message),
+        data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+        animated: false,
+        markerEnd: {
+          type: MarkerType.ArrowClosed,
+          width: 20,
+          height: 20,
+        },
+      });
+      continue;
+    }
+
+    // If the producer has channels defined, we need to render them
+    for (const producerChannel of producerChannelConfiguration) {
+      const channel = findInMap(channelMap, producerChannel.id, producerChannel.version) as CollectionEntry<'channels'>;
+
+      // If we cannot find the channel in EventCatalog, we just connect the producer to the event directly
+      if (!channel) {
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(producer, message),
+            source: generateIdForNode(producer),
+            target: generateIdForNode(message),
+            label: getEdgeLabelForMessageAsSource(message),
+            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+          })
+        );
+        continue;
+      }
+
+      // We render the channel node
+      nodes.push(
+        createNode({
+          id: generateIdForNode(channel),
+          type: channel.collection,
+          data: {
+            mode,
+            channel: { ...channel.data },
+            contextMenu: buildContextMenuForResource({
+              collection: 'channels',
+              id: channel.data.id,
+              version: channel.data.version,
+            }),
+          },
+          position: { x: 0, y: 0 },
+        })
+      );
+
+      // Connect the producer to the message
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(producer, message),
+          source: generateIdForNode(producer),
+          target: generateIdForNode(message),
+          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+          label: getEdgeLabelForServiceAsTarget(message),
+        })
+      );
+
+      // Connect the message to the channel
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(message, channel),
+          source: generateIdForNode(message),
+          target: generateIdForNode(channel),
+          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+          label: 'routes to',
+        })
+      );
+    }
+  }
+
+  // The resources that consume the message
+  for (const consumer of consumers) {
+    nodes.push({
+      id: generateIdForNode(consumer),
+      sourcePosition: 'right',
+      targetPosition: 'left',
+      data: isDataProduct(consumer) ? getDataProductNodeData(consumer, mode) : getRoutableNodeData(consumer, mode),
+      position: { x: 0, y: 0 },
+      type: isDataProduct(consumer) ? 'data-products' : consumer.collection,
+    });
+    if (!isDataProduct(consumer)) {
+      appendAgentToolNodesAndEdges({ agent: consumer, nodes, edges, mode });
+    }
+
+    // Data products don't have channel configuration, so connect directly from the message
+    if (isDataProduct(consumer)) {
+      const rootSourceAndTarget = {
+        source: { id: generateIdForNode(message), collection: message.collection },
+        target: { id: generateIdForNode(consumer), collection: consumer.collection },
+      };
+
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(message, consumer),
+          source: generateIdForNode(message),
+          target: generateIdForNode(consumer),
+          label: 'consumed by',
+          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+        })
+      );
+      continue;
+    }
+
+    // Service/agent-specific channel handling
+    const routableConsumer = consumer as RoutableResource;
+
+    // Is the consumer receiving this message from a channel?
+    const consumerConfigurationForMessage = routableConsumer.data.receives?.find(
+      (receive) => receive.id === message.data.id && versionMatches(receive.version, message.data.version)
+    );
+    const consumerChannelConfiguration = consumerConfigurationForMessage?.from ?? [];
+
+    const consumerHasChannels = consumerChannelConfiguration.length > 0;
+
+    const rootSourceAndTarget = {
+      source: { id: generateIdForNode(message), collection: message.collection },
+      target: { id: generateIdForNode(consumer), collection: consumer.collection },
+    };
+
+    // If the consumer does not have any channels defined, connect the consumer to the event directly
+    if (!consumerHasChannels) {
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(message, consumer),
+          source: generateIdForNode(message),
+          target: generateIdForNode(consumer),
+          label: getEdgeLabelForMessageAsSource(message),
+          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+        })
+      );
+    }
+
+    // If the consumer has channels defined, we try and render them
+    for (const consumerChannel of consumerChannelConfiguration) {
+      const channel = findInMap(channelMap, consumerChannel.id, consumerChannel.version) as CollectionEntry<'channels'>;
+
+      // If we cannot find the channel in EventCatalog, we connect the message directly to the consumer
+      if (!channel) {
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(message, consumer),
+            source: generateIdForNode(message),
+            target: generateIdForNode(consumer),
+            label: getEdgeLabelForMessageAsSource(message),
+            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+          })
+        );
+        continue;
+      }
+
+      // Can any of the consumer channels be linked to any of the producer channels?
+      // Only consider service-like producers for channel linking (data products don't have sends/receives)
+      const producerChannels = routableProducers
+        .map((producer) => {
+          const config = producer.data.sends?.find(
+            (send) => send.id === message.data.id && versionMatches(send.version, message.data.version)
+          );
+          return config?.to ?? [];
+        })
+        .flat();
+      const consumerChannels =
+        routableConsumer.data.receives?.find(
+          (receive) => receive.id === message.data.id && versionMatches(receive.version, message.data.version)
+        )?.from ?? [];
+
+      for (const producerChannel of producerChannels) {
+        const producerChannelValue = findInMap(
+          channelMap,
+          producerChannel.id,
+          producerChannel.version
+        ) as CollectionEntry<'channels'>;
+
+        for (const consumerChannel of consumerChannels) {
+          const consumerChannelValue = findInMap(
+            channelMap,
+            consumerChannel.id,
+            consumerChannel.version
+          ) as CollectionEntry<'channels'>;
+          const channelChainToRender = getChannelChain(producerChannelValue, consumerChannelValue, channels);
+
+          // If there is a chain between them we need to render them al
+          if (channelChainToRender.length > 0) {
+            const { nodes: channelNodes, edges: channelEdges } = getNodesAndEdgesForChannelChain({
+              source: message,
+              target: consumer,
+              channelChain: channelChainToRender,
+              mode,
+            });
+
+            nodes.push(...channelNodes);
+            edges.push(...channelEdges);
+          } else {
+            // There is no chain found, we need to render the channel between message and the consumers
+            nodes.push(
+              createNode({
+                id: generateIdForNode(channel),
+                type: channel.collection,
+                data: { mode, channel: { ...channel.data } },
+                position: { x: 0, y: 0 },
+              })
+            );
+            edges.push(
+              createEdge({
+                id: generatedIdForEdge(message, channel),
+                source: generateIdForNode(message),
+                target: generateIdForNode(channel),
+                label: 'routes to',
+                data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+              })
+            );
+            edges.push(
+              createEdge({
+                id: generatedIdForEdge(channel, consumer),
+                source: generateIdForNode(channel),
+                target: generateIdForNode(consumer),
+                label: getEdgeLabelForMessageAsSource(message),
+                data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+              })
+            );
+          }
+        }
+      }
+
+      // If producer does not have a any channels defined, we need to connect the message to the consumer directly
+      if (producerChannels.length === 0 && channel) {
+        // Create the channel node
+        nodes.push(
+          createNode({
+            id: generateIdForNode(channel),
+            type: channel.collection,
+            data: { mode, channel: { ...channel.data } },
+            position: { x: 0, y: 0 },
+          })
+        );
+
+        // Connect the message to the channel
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(message, channel),
+            source: generateIdForNode(message),
+            target: generateIdForNode(channel),
+            label: 'routes to',
+            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+          })
+        );
+
+        // Connect the channel to the consumer
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(channel, consumer),
+            source: generateIdForNode(channel),
+            target: generateIdForNode(consumer),
+            label: getEdgeLabelForMessageAsSource(message),
+            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+          })
+        );
+      }
+    }
+  }
+
+  // Handle messages that are both sent and received
+  bothSentAndReceived.forEach((_message) => {
+    if (message) {
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(message, _message) + '-both',
+          source: generateIdForNode(message),
+          target: generateIdForNode(_message),
+          label: 'publishes and subscribes',
+          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget: { source: message, target: _message } },
+        })
+      );
+    }
+  });
+
+  nodes.forEach((node: any) => {
+    flow.setNode(node.id, { width: DEFAULT_NODE_WIDTH, height: DEFAULT_NODE_HEIGHT });
+  });
+
+  edges.forEach((edge: any) => {
+    flow.setEdge(edge.source, edge.target);
+  });
+
+  // Render the diagram in memory getting hte X and Y
+  dagre.layout(flow);
+
+  return {
+    nodes: calculatedNodes(flow, nodes),
+    edges,
+  };
+};
+
+export const getNodesAndEdgesForQueries = async ({
+  id,
+  version,
+  defaultFlow,
+  mode = 'simple',
+  channelRenderMode = 'flat',
+}: Props) => {
+  const [queries, channels] = await Promise.all([getQueries(), getChannels()]);
+  return getNodesAndEdges({ id, version, defaultFlow, mode, channelRenderMode, collection: queries, channels });
+};
+
+export const getNodesAndEdgesForCommands = async ({
+  id,
+  version,
+  defaultFlow,
+  mode = 'simple',
+  channelRenderMode = 'flat',
+}: Props) => {
+  const [commands, channels] = await Promise.all([getCommands(), getChannels()]);
+  return getNodesAndEdges({ id, version, defaultFlow, mode, channelRenderMode, collection: commands, channels });
+};
+
+export const getNodesAndEdgesForEvents = async ({
+  id,
+  version,
+  defaultFlow,
+  mode = 'simple',
+  channelRenderMode = 'flat',
+}: Props) => {
+  const [events, channels] = await Promise.all([getEvents(), getChannels()]);
+  return getNodesAndEdges({ id, version, defaultFlow, mode, channelRenderMode, collection: events, channels });
+};
+
+export const getNodesAndEdgesForConsumedMessage = ({
+  message,
+  targetChannels = [],
+  services,
+  agents = [],
+  channels,
+  currentNodes = [],
+  target,
+  mode = 'simple',
+  channelMap,
+}: {
+  message: CollectionEntry<CollectionMessageTypes>;
+  targetChannels?: { id: string; version: string }[];
+  services: CollectionEntry<'services'>[];
+  agents?: CollectionEntry<'agents'>[];
+  channels: CollectionEntry<'channels'>[];
+  currentNodes: Node[];
+  target: RoutableResource;
+  mode?: 'simple' | 'full';
+  channelMap?: Map<string, CollectionEntry<'channels'>[]>;
+}) => {
+  let nodes = [] as Node[],
+    edges = [] as any;
+
+  // Use the provided map or create one if missing
+  const map = channelMap || createVersionedMap(channels);
+
+  const messageId = generateIdForNode(message);
+
+  const rootSourceAndTarget = {
+    source: { id: generateIdForNode(message), collection: message.collection },
+    target: { id: generateIdForNode(target), collection: target.collection },
+  };
+
+  // Render the message node
+  nodes.push(
+    createNode({
+      id: messageId,
+      type: message.collection,
+      data: {
+        mode,
+        message: { ...message.data, ...getOperationFields(message.data) },
+        contextMenu: buildContextMenuForMessage({
+          id: message.data.id,
+          version: message.data.version,
+          name: message.data.name,
+          collection: message.collection,
+          schemaPath: (message.data as any).schemaPath,
+        }),
+      },
+      position: { x: 0, y: 0 },
+    })
+  );
+
+  // Render the target node
+  nodes.push(
+    createNode({
+      id: generateIdForNode(target),
+      type: target.collection,
+      data: getRoutableNodeData(target, mode),
+      position: { x: 0, y: 0 },
+    })
+  );
+  appendAgentToolNodesAndEdges({ agent: target, nodes, edges, mode });
+
+  const targetMessageConfiguration = target.data.receives?.find(
+    (receive) => receive.id === message.data.id && versionMatches(receive.version, message.data.version)
+  );
+  const channelsFromMessageToTarget = targetMessageConfiguration?.from ?? [];
+  const hydratedChannelsFromMessageToTarget = channelsFromMessageToTarget
+    .map((channel) => findInMap(map, channel.id, channel.version))
+    .filter((channel): channel is CollectionEntry<'channels'> => channel !== undefined);
+
+  // Now we get the producers of the message and create nodes and edges for them
+  const producers = [
+    ...getAgentProducersOfMessage(agents, message),
+    ...getProducersOfMessage(services, message),
+  ] as RoutableResource[];
+
+  const hasProducers = producers.length > 0;
+  const targetHasDefinedChannels = targetChannels.length > 0;
+
+  // Warning edge if no producers or target channels are defined
+  if (!hasProducers && !targetHasDefinedChannels) {
+    edges.push(
+      createEdge({
+        id: generatedIdForEdge(message, target) + '-warning',
+        source: messageId,
+        target: generateIdForNode(target),
+        label: getEdgeLabelForMessageAsSource(message),
+        data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+      })
+    );
+  }
+
+  // If the target defined channels they consume the message from, we need to create the channel nodes and edges
+  if (targetHasDefinedChannels) {
+    for (const targetChannel of targetChannels) {
+      const channel = findInMap(map, targetChannel.id, targetChannel.version) as CollectionEntry<'channels'>;
+
+      if (!channel) {
+        // No channe found, we just connect the message to the target directly
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(message, target),
+            source: messageId,
+            target: generateIdForNode(target),
+            label: getEdgeLabelForMessageAsSource(message),
+            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+          })
+        );
+        continue;
+      }
+
+      const channelId = generateIdForNode(channel);
+
+      // Create the channel node
+      nodes.push(
+        createNode({
+          id: channelId,
+          type: channel.collection,
+          data: {
+            mode,
+            channel: { ...channel.data, ...channel, id: channel.data.id },
+            contextMenu: buildContextMenuForResource({
+              collection: 'channels',
+              id: channel.data.id,
+              version: channel.data.version,
+            }),
+          },
+          position: { x: 0, y: 0 },
+        })
+      );
+
+      // Connect the channel to the target
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(channel, target),
+          source: channelId,
+          target: generateIdForNode(target),
+          label: getEdgeLabelForMessageAsSource(message),
+          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+        })
+      );
+
+      // If we dont have any producers, we will connect the message to the channel directly
+      if (producers.length === 0) {
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(message, channel),
+            source: messageId,
+            target: channelId,
+            label: 'routes to',
+            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+          })
+        );
+      }
+    }
+  }
+
+  // Process the producers for the message
+  for (const producer of producers) {
+    const producerId = generateIdForNode(producer);
+
+    // Create the producer node
+    nodes.push(
+      createNode({
+        id: producerId,
+        type: producer.collection,
+        data: getRoutableNodeData(producer, mode),
+        position: { x: 0, y: 0 },
+      })
+    );
+    appendAgentToolNodesAndEdges({ agent: producer, nodes, edges, mode });
+
+    // The message is always connected directly to the producer
+    edges.push(
+      createEdge({
+        id: generatedIdForEdge(producer, message),
+        source: producerId,
+        target: messageId,
+        label: getEdgeLabelForServiceAsTarget(message),
+        data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+      })
+    );
+
+    // Check if the producer is sending the message to a channel
+    const producerConfigurationForMessage = producer.data.sends?.find(
+      (send) => send.id === message.data.id && versionMatches(send.version, message.data.version)
+    );
+    const producerChannelConfiguration = producerConfigurationForMessage?.to ?? [];
+
+    const producerHasChannels = producerChannelConfiguration.length > 0;
+    const targetHasChannels = hydratedChannelsFromMessageToTarget.length > 0;
+
+    // If the producer or target (consumer) has no channels defined, we just connect the message to the consumer directly
+    // of the target has no channels defined, we just connect the message to the target directly
+    if ((!producerHasChannels && !targetHasChannels) || !targetHasChannels) {
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(message, target),
+          source: messageId,
+          target: generateIdForNode(target),
+          label: getEdgeLabelForMessageAsSource(message),
+          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+        })
+      );
+      continue;
+    }
+
+    // If the target has channels but the producer does not
+    // We then connect the message to the channels directly
+    if (targetHasChannels && !producerHasChannels) {
+      for (const targetChannel of hydratedChannelsFromMessageToTarget) {
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(message, targetChannel),
+            source: messageId,
+            target: generateIdForNode(targetChannel),
+            label: 'routes to',
+            data: {
+              customColor: getColorFromString(message.data.id),
+              rootSourceAndTarget: {
+                source: { id: generateIdForNode(message), collection: message.collection },
+                target: { id: generateIdForNode(target), collection: target.collection },
+              },
+            },
+          })
+        );
+      }
+      continue;
+    }
+
+    // Process each producer channel configuration
+    for (const producerChannel of producerChannelConfiguration) {
+      const channel = findInMap(map, producerChannel.id, producerChannel.version) as CollectionEntry<'channels'>;
+
+      // If we cannot find the channel in EventCatalog, we just connect the message to the target directly
+      if (!channel) {
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(message, target),
+            source: messageId,
+            target: generateIdForNode(target),
+            label: getEdgeLabelForMessageAsSource(message),
+            data: {
+              customColor: getColorFromString(message.data.id),
+              rootSourceAndTarget: {
+                source: { id: generateIdForNode(message), collection: message.collection },
+                target: { id: generateIdForNode(target), collection: target.collection },
+              },
+            },
+          })
+        );
+        continue;
+      }
+
+      // Does the producer have any channels defined? If not, we just connect the message to the target directly
+      if (!producerHasChannels) {
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(message, target),
+            source: messageId,
+            target: generateIdForNode(target),
+            label: getEdgeLabelForMessageAsSource(message),
+            data: {
+              customColor: getColorFromString(message.data.id),
+              rootSourceAndTarget: {
+                source: { id: generateIdForNode(message), collection: message.collection },
+                target: { id: generateIdForNode(target), collection: target.collection },
+              },
+            },
+          })
+        );
+        continue;
+      }
+
+      // The producer does have channels defined, we need to try and work out the path the message takes to the target
+      for (const targetChannel of hydratedChannelsFromMessageToTarget) {
+        const channelChainToRender = getChannelChain(channel, targetChannel, channels);
+        if (channelChainToRender.length > 0) {
+          const { nodes: channelNodes, edges: channelEdges } = getNodesAndEdgesForChannelChain({
+            source: message,
+            target: target,
+            channelChain: channelChainToRender,
+            mode,
+          });
+
+          nodes.push(...channelNodes);
+          edges.push(...channelEdges);
+
+          break;
+        } else {
+          // No chain found create the channel, and connect the message to the target channel directly
+          nodes.push(
+            createNode({
+              id: generateIdForNode(targetChannel),
+              type: targetChannel.collection,
+              data: { mode, channel: { ...targetChannel.data, ...targetChannel } },
+              position: { x: 0, y: 0 },
+            })
+          );
+          edges.push(
+            createEdge({
+              id: generatedIdForEdge(message, targetChannel),
+              source: messageId,
+              target: generateIdForNode(targetChannel),
+              label: 'routes to',
+              data: {
+                rootSourceAndTarget: {
+                  source: { id: generateIdForNode(message), collection: message.collection },
+                  target: { id: generateIdForNode(targetChannel), collection: targetChannel.collection },
+                },
+              },
+            })
+          );
+        }
+      }
+    }
+  }
+
+  // Remove any nodes that are already in the current nodes (already on the UI)
+  nodes = nodes.filter((node) => !currentNodes.find((n) => n.id === node.id));
+
+  //  Make sure all nodes are unique
+  const uniqueNodes = nodes.filter((node, index, self) => index === self.findIndex((t) => t.id === node.id));
+
+  const uniqueEdges = edges.filter(
+    (edge: any, index: number, self: any[]) => index === self.findIndex((t: any) => t.id === edge.id)
+  );
+
+  return { nodes: uniqueNodes, edges: uniqueEdges };
+};
+
+export const getNodesAndEdgesForProducedMessage = ({
+  message,
+  sourceChannels,
+  services,
+  agents = [],
+  channels,
+  currentNodes = [],
+  currentEdges = [],
+  source,
+  mode = 'simple',
+  channelMap,
+}: {
+  message: CollectionEntry<CollectionMessageTypes>;
+  sourceChannels?: { id: string; version: string }[];
+  services: CollectionEntry<'services'>[];
+  agents?: CollectionEntry<'agents'>[];
+  channels: CollectionEntry<'channels'>[];
+  currentNodes: Node[];
+  currentEdges: Edge[];
+  source: RoutableResource;
+  mode?: 'simple' | 'full';
+  channelMap?: Map<string, CollectionEntry<'channels'>[]>;
+}) => {
+  let nodes = [] as Node[],
+    edges = [] as any;
+
+  // Use provided map or create one
+  const map = channelMap || createVersionedMap(channels);
+
+  const messageId = generateIdForNode(message);
+
+  const rootSourceAndTarget = {
+    source: { id: generateIdForNode(source), collection: source.collection },
+    target: { id: generateIdForNode(message), collection: message.collection },
+  };
+
+  // Render the message node
+  nodes.push(
+    createNode({
+      id: messageId,
+      type: message.collection,
+      data: {
+        mode,
+        message: { ...message.data, ...getOperationFields(message.data) },
+        contextMenu: buildContextMenuForMessage({
+          id: message.data.id,
+          version: message.data.version,
+          name: message.data.name,
+          collection: message.collection,
+          schemaPath: (message.data as any).schemaPath,
+        }),
+      },
+      position: { x: 0, y: 0 },
+    })
+  );
+
+  // Render the producer node
+  nodes.push(
+    createNode({
+      id: generateIdForNode(source),
+      type: source.collection,
+      data: getRoutableNodeData(source, mode),
+      position: { x: 0, y: 0 },
+    })
+  );
+  appendAgentToolNodesAndEdges({ agent: source, nodes, edges, mode });
+
+  // Render the edge from the producer to the message
+  edges.push(
+    createEdge({
+      id: generatedIdForEdge(source, message),
+      source: generateIdForNode(source),
+      target: messageId,
+      label: getEdgeLabelForServiceAsTarget(message),
+      data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+    })
+  );
+
+  const sourceMessageConfiguration = source.data.sends?.find(
+    (send) => send.id === message.data.id && versionMatches(send.version, message.data.version)
+  );
+  const channelsFromSourceToMessage = sourceMessageConfiguration?.to ?? [];
+
+  const hydratedChannelsFromSourceToMessage = channelsFromSourceToMessage
+    .map((channel) => findInMap(map, channel.id, channel.version))
+    .filter((channel): channel is CollectionEntry<'channels'> => channel !== undefined);
+
+  // If the source defined channels they send the message to, we need to create the channel nodes and edges
+  if (sourceChannels && sourceChannels.length > 0) {
+    for (const sourceChannel of sourceChannels) {
+      const channel = findInMap(map, sourceChannel.id, sourceChannel.version) as CollectionEntry<'channels'>;
+
+      if (!channel) {
+        // No channel found, we just connect the source directly to the message
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(source, message),
+            source: generateIdForNode(source),
+            target: messageId,
+            label: getEdgeLabelForServiceAsTarget(message),
+            data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+          })
+        );
+        continue;
+      }
+
+      const channelId = generateIdForNode(channel);
+
+      // Create the channel node
+      nodes.push(
+        createNode({
+          id: channelId,
+          type: channel.collection,
+          data: {
+            mode,
+            channel: { ...channel.data, ...channel, mode, id: channel.data.id },
+            contextMenu: buildContextMenuForResource({
+              collection: 'channels',
+              id: channel.data.id,
+              version: channel.data.version,
+            }),
+          },
+          position: { x: 0, y: 0 },
+        })
+      );
+
+      // Connect the produced message to the channel
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(message, channel),
+          source: messageId,
+          target: channelId,
+          label: 'routes to',
+          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+        })
+      );
+    }
+  }
+
+  // Now we get the consumers of the message and create nodes and edges for them
+  const consumers = [
+    ...getAgentConsumersOfMessage(agents, message),
+    ...getConsumersOfMessage(services, message),
+  ] as RoutableResource[];
+
+  // TODO: Make this a UI Switch in the future....
+  const latestConsumers = consumers.filter((consumer) => {
+    const collection = consumer.collection === 'agents' ? agents : services;
+    return getLatestVersionInCollectionById(collection as any, consumer.data.id) === consumer.data.version;
+  });
+
+  // Process the consumers for the message
+  for (const consumer of latestConsumers) {
+    const consumerId = generateIdForNode(consumer);
+
+    // Create the consumer node
+    nodes.push(
+      createNode({
+        id: consumerId,
+        type: consumer.collection,
+        data: getRoutableNodeData(consumer, mode),
+        position: { x: 0, y: 0 },
+      })
+    );
+    appendAgentToolNodesAndEdges({ agent: consumer, nodes, edges, mode });
+
+    // Check if the consumer is consuming the message from a channel
+    const consumerConfigurationForMessage = consumer.data.receives?.find(
+      (receive) => receive.id === message.data.id && versionMatches(receive.version, message.data.version)
+    );
+    const consumerChannelConfiguration = consumerConfigurationForMessage?.from ?? [];
+
+    const consumerHasChannels = consumerChannelConfiguration.length > 0;
+    const producerHasChannels = hydratedChannelsFromSourceToMessage.length > 0;
+
+    // If the consumer and producer have no channels defined,
+    // or the consumer has no channels defined, we just connect the message to the consumer directly
+    if ((!consumerHasChannels && !producerHasChannels) || !consumerHasChannels) {
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(message, consumer),
+          source: messageId,
+          target: consumerId,
+          label: getEdgeLabelForMessageAsSource(message),
+          data: { customColor: getColorFromString(message.data.id), rootSourceAndTarget },
+        })
+      );
+      continue;
+    }
+
+    // Process each consumer channel configuration
+    for (const consumerChannel of consumerChannelConfiguration) {
+      const channel = findInMap(map, consumerChannel.id, consumerChannel.version) as CollectionEntry<'channels'>;
+
+      const edgeProps = { customColor: getColorFromString(message.data.id), rootSourceAndTarget };
+
+      // If the channel cannot be found in EventCatalog, we just connect the message to the consumer directly
+      // as a fallback, rather than just an empty node floating around
+      if (!channel) {
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(message, consumer),
+            source: messageId,
+            target: consumerId,
+            label: 'consumes',
+            data: edgeProps,
+          })
+        );
+        continue;
+      }
+
+      // We always add the consumer channel to be rendered
+      nodes.push(
+        createNode({
+          id: generateIdForNode(channel),
+          type: channel.collection,
+          data: {
+            mode,
+            channel: { ...channel.data, ...channel },
+            contextMenu: buildContextMenuForResource({
+              collection: 'channels',
+              id: channel.data.id,
+              version: channel.data.version,
+            }),
+          },
+          position: { x: 0, y: 0 },
+        })
+      );
+
+      // If the producer does not have any channels defined, we connect the message to the consumers channel directly
+      if (!producerHasChannels) {
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(message, channel),
+            source: messageId,
+            target: generateIdForNode(channel),
+            label: 'routes to',
+            data: edgeProps,
+          })
+        );
+        edges.push(
+          createEdge({
+            id: generatedIdForEdge(channel, consumer),
+            source: generateIdForNode(channel),
+            target: generateIdForNode(consumer),
+            label: getEdgeLabelForMessageAsSource(message),
+            data: {
+              ...edgeProps,
+              rootSourceAndTarget: {
+                source: { id: generateIdForNode(message), collection: message.collection },
+                target: { id: generateIdForNode(consumer), collection: consumer.collection },
+              },
+            },
+          })
+        );
+        continue;
+      }
+
+      // The producer has channels defined, we need to try and work out the path the message takes to the consumer
+      for (const sourceChannel of hydratedChannelsFromSourceToMessage) {
+        const channelChainToRender = getChannelChain(sourceChannel, channel, channels);
+
+        if (channelChainToRender.length > 0) {
+          const { nodes: channelNodes, edges: channelEdges } = getNodesAndEdgesForChannelChain({
+            source: message,
+            target: consumer,
+            channelChain: channelChainToRender,
+            mode,
+          });
+
+          nodes.push(...channelNodes);
+          edges.push(...channelEdges);
+        } else {
+          // No chain found, we need to connect to the message to the channel
+          // And the channel to the consumer
+          edges.push(
+            createEdge({
+              id: generatedIdForEdge(message, channel),
+              source: messageId,
+              target: generateIdForNode(channel),
+              label: 'routes to',
+              data: {
+                ...edgeProps,
+                rootSourceAndTarget: {
+                  source: { id: generateIdForNode(message), collection: message.collection },
+                  target: { id: generateIdForNode(consumer), collection: consumer.collection },
+                },
+              },
+            })
+          );
+          edges.push(
+            createEdge({
+              id: generatedIdForEdge(channel, consumer),
+              source: generateIdForNode(channel),
+              target: generateIdForNode(consumer),
+              label: `${getEdgeLabelForMessageAsSource(message, true)} \n ${message.data.name}`,
+              data: {
+                ...edgeProps,
+                rootSourceAndTarget: {
+                  source: { id: generateIdForNode(message), collection: message.collection },
+                  target: { id: generateIdForNode(consumer), collection: consumer.collection },
+                },
+              },
+            })
+          );
+        }
+      }
+    }
+  }
+
+  // Remove any nodes that are already in the current nodes (already on the UI)
+  nodes = nodes.filter((node) => !currentNodes.find((n) => n.id === node.id));
+
+  //  Make sure all nodes are unique
+  const uniqueNodes = nodes.filter((node, index, self) => index === self.findIndex((t) => t.id === node.id));
+
+  const uniqueEdges = edges.filter(
+    (edge: any, index: number, self: any[]) => index === self.findIndex((t: any) => t.id === edge.id)
+  );
+
+  return { nodes: uniqueNodes, edges: uniqueEdges };
+};
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/services-node-graph.ts b/packages/core/eventcatalog/src/utils/node-graphs/services-node-graph.ts
new file mode 100644
index 000000000..6e410ef16
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/services-node-graph.ts
@@ -0,0 +1,650 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import dagre from 'dagre';
+import {
+  createDagreGraph,
+  generateIdForNode,
+  generatedIdForEdge,
+  calculatedNodes,
+  createEdge,
+  buildContextMenuForAgent,
+  buildContextMenuForService,
+  buildContextMenuForResource,
+  versionMatches,
+  DEFAULT_NODE_WIDTH,
+  DEFAULT_NODE_HEIGHT,
+  partitionMessagesByGroup,
+  getOperationFields,
+} from '@utils/node-graphs/utils/utils';
+
+const sanitizeGroupId = (name: string) => name.replace(/[^a-zA-Z0-9]/g, '-').toLowerCase();
+const sanitizeToolId = (name: string) =>
+  name
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '')
+    .toLowerCase();
+
+const generateIdForAgentToolNode = (
+  agent: CollectionEntry<'agents'> | CollectionEntry<'services'>,
+  tool: { name: string; type: string }
+) => `${generateIdForNode(agent)}-tool-${sanitizeToolId(`${tool.name}-${tool.type}`)}`;
+
+import { findMatchingNodes, findInMap, createVersionedMap } from '@utils/collections/util';
+import { MarkerType, type Node, type Edge } from '@xyflow/react';
+import type { CollectionMessageTypes } from '@types';
+import { getNodesAndEdgesForConsumedMessage, getNodesAndEdgesForProducedMessage } from './message-node-graph';
+
+/**
+ * Pre-compute the downstream nodes/edges that should appear when a message group
+ * is expanded. Calls the standard message node-graph function for each grouped
+ * message, then strips out the service and message nodes/edges that the client-side
+ * expand logic handles separately.
+ */
+const precomputeGroupExpansion = (
+  messages: any[],
+  channelPointers: any[],
+  direction: 'sends' | 'receives',
+  opts: {
+    serviceNodeId: string;
+    services: any;
+    agents: any;
+    service: any;
+    mode: string;
+    channels: any;
+    channelMap: any;
+    existingNodes: any[];
+    existingEdges: any[];
+  }
+) => {
+  const expandedNodes: Node[] = [];
+  const expandedEdges: Edge[] = [];
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    const channelRefs = channelPointers[i] || [];
+
+    // Call the same function used by the ungrouped path
+    const args =
+      direction === 'receives'
+        ? {
+            message: msg as any,
+            targetChannels: channelRefs,
+            services: opts.services,
+            agents: opts.agents,
+            currentNodes: [...opts.existingNodes, ...expandedNodes],
+            target: opts.service,
+            mode: opts.mode,
+            channels: opts.channels,
+            channelMap: opts.channelMap,
+          }
+        : {
+            message: msg as any,
+            sourceChannels: channelRefs,
+            services: opts.services,
+            agents: opts.agents,
+            currentNodes: [...opts.existingNodes, ...expandedNodes],
+            source: opts.service,
+            currentEdges: [...opts.existingEdges, ...expandedEdges],
+            mode: opts.mode,
+            channels: opts.channels,
+            channelMap: opts.channelMap,
+          };
+
+    const { nodes: msgNodes, edges: msgEdges } =
+      direction === 'receives'
+        ? getNodesAndEdgesForConsumedMessage(args as any)
+        : getNodesAndEdgesForProducedMessage(args as any);
+
+    // Strip the service node and message node — the client expand logic creates these.
+    // Also strip the direct service↔message edge for the same reason.
+    const msgId = `${msg.data.id}-${msg.data.version}`;
+    const isServiceOrMessage = (id: string) => id === opts.serviceNodeId || id === msgId;
+    const isDirectEdge = (e: any) =>
+      (e.source === opts.serviceNodeId && e.target === msgId) || (e.source === msgId && e.target === opts.serviceNodeId);
+
+    expandedNodes.push(...msgNodes.filter((n: any) => !isServiceOrMessage(n.id)));
+    expandedEdges.push(...msgEdges.filter((e: any) => !isDirectEdge(e)));
+  }
+
+  return { expandedNodes, expandedEdges };
+};
+
+type DagreGraph = any;
+
+interface Props {
+  id: string;
+  version: string;
+  defaultFlow?: DagreGraph;
+  mode?: 'simple' | 'full';
+  renderAllEdges?: boolean;
+  channelRenderMode?: 'single' | 'flat';
+  renderMessages?: boolean;
+  collection?: 'agents' | 'services';
+  layout?: boolean;
+}
+
+const getResourceContextMenu = (resource: CollectionEntry<'agents'> | CollectionEntry<'services'>) => {
+  if (resource.collection === 'agents') {
+    return buildContextMenuForAgent({
+      id: resource.data.id,
+      version: resource.data.version,
+      repository: resource.data.repository as { url: string },
+    });
+  }
+
+  return buildContextMenuForService({
+    id: resource.data.id,
+    version: resource.data.version,
+    specifications: (resource.data as any).specifications as { type: string; path: string }[],
+    repository: resource.data.repository as { url: string },
+  });
+};
+
+const getResourceNodeData = (resource: CollectionEntry<'agents'> | CollectionEntry<'services'>, mode: 'simple' | 'full') => ({
+  mode,
+  ...(resource.collection === 'agents' ? { agent: { ...resource.data } } : { service: { ...resource.data } }),
+  contextMenu: getResourceContextMenu(resource),
+});
+
+const getSendsMessageByMessageType = (messageType: string) => {
+  switch (messageType) {
+    case 'events':
+      return 'publishes event';
+    case 'commands':
+      return 'invokes command';
+    case 'queries':
+      return 'requests';
+    default:
+      return 'invokes message';
+  }
+};
+
+const getReceivesMessageByMessageType = (messageType: string) => {
+  switch (messageType) {
+    case 'events':
+      return 'receives event';
+    case 'commands':
+    case 'queries':
+      return 'accepts';
+    default:
+      return 'accepts message';
+  }
+};
+
+export const getNodesAndEdges = async ({
+  id,
+  defaultFlow,
+  version,
+  mode = 'simple',
+  renderAllEdges = false,
+  channelRenderMode = 'flat',
+  renderMessages = true,
+  collection = 'services',
+  layout = true,
+}: Props) => {
+  const flow = defaultFlow || createDagreGraph({ ranksep: 300, nodesep: 50 });
+  let nodes = [] as any,
+    edges = [] as any;
+
+  // Fetch all collections in parallel
+  const [services, agents, events, commands, queries, channels, containers] = await Promise.all([
+    getCollection('services'),
+    getCollection('agents'),
+    getCollection('events'),
+    getCollection('commands'),
+    getCollection('queries'),
+    getCollection('channels'),
+    getCollection('containers'),
+  ]);
+
+  const resources = collection === 'agents' ? agents : services;
+  const service = resources.find((service) => service.data.id === id && service.data.version === version);
+
+  // Nothing found...
+  if (!service) {
+    return {
+      nodes: [],
+      edges: [],
+    };
+  }
+
+  // Build maps for O(1) lookups
+  const messages = [...events, ...commands, ...queries];
+  const messageMap = createVersionedMap(messages);
+  const containerMap = createVersionedMap(containers);
+  const channelMap = createVersionedMap(channels);
+
+  const receivesRaw = service?.data.receives || [];
+  const sendsRaw = service?.data.sends || [];
+  const writesToRaw = service?.data.writesTo || [];
+  const readsFromRaw = service?.data.readsFrom || [];
+  const toolsRaw: any[] = collection === 'agents' ? (service?.data as any).tools || [] : [];
+
+  const receivesHydrated = receivesRaw
+    .map((message) => findInMap(messageMap, message.id, message.version))
+    .filter((e) => e !== undefined);
+
+  const sendsHydrated = sendsRaw
+    .map((message) => findInMap(messageMap, message.id, message.version))
+    .filter((e) => e !== undefined);
+
+  const writesToHydrated = writesToRaw
+    .map((container) => findInMap(containerMap, container.id, container.version))
+    .filter((e) => e !== undefined);
+
+  const readsFromHydrated = readsFromRaw
+    .map((container) => findInMap(containerMap, container.id, container.version))
+    .filter((e) => e !== undefined);
+
+  const receives = (receivesHydrated as CollectionEntry<CollectionMessageTypes>[]) || [];
+  const sends = (sendsHydrated as CollectionEntry<CollectionMessageTypes>[]) || [];
+  const writesTo = (writesToHydrated as CollectionEntry<'containers'>[]) || [];
+  const readsFrom = (readsFromHydrated as CollectionEntry<'containers'>[]) || [];
+
+  // Track messages that are both sent and received
+  const bothSentAndReceived = findMatchingNodes(receives, sends);
+  const bothReadsAndWrites = findMatchingNodes(readsFrom, writesTo);
+
+  // Partition messages by group
+  const receivesPartition = partitionMessagesByGroup(receivesRaw, receives);
+  const sendsPartition = partitionMessagesByGroup(sendsRaw, sends);
+
+  // Collect grouped message IDs to exclude from bothSentAndReceived
+  const groupedMessageIds = new Set<string>();
+  for (const [, groupData] of receivesPartition.grouped) {
+    groupData.messages.forEach((m: any) => groupedMessageIds.add(`${m.data.id}-${m.data.version}`));
+  }
+  for (const [, groupData] of sendsPartition.grouped) {
+    groupData.messages.forEach((m: any) => groupedMessageIds.add(`${m.data.id}-${m.data.version}`));
+  }
+
+  const filteredBothSentAndReceived = bothSentAndReceived.filter(
+    (m: any) => m && !groupedMessageIds.has(`${m.data.id}-${m.data.version}`)
+  );
+
+  const serviceNodeId = `${service.data.id}-${service.data.version}`;
+
+  if (renderMessages) {
+    // Emit group nodes for grouped receives
+    for (const [groupName, groupData] of receivesPartition.grouped) {
+      const groupNodeId = `message-group-${service.data.id}-${service.data.version}-${sanitizeGroupId(groupName)}-receives`;
+
+      // Match each message to its pointer by id/version (not index) to avoid
+      // misalignment when a pointer fails hydration and is missing from messages.
+      const findPointerForMessage = (msg: any) =>
+        groupData.pointers.find((p: any) => p.id === msg.data.id && versionMatches(p.version, msg.data.version));
+
+      const { expandedNodes, expandedEdges } = precomputeGroupExpansion(
+        groupData.messages,
+        groupData.messages.map((msg: any) => findPointerForMessage(msg)?.from || []),
+        'receives',
+        { serviceNodeId, services, agents, service, mode, channels, channelMap, existingNodes: nodes, existingEdges: edges }
+      );
+
+      nodes.push({
+        id: groupNodeId,
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        type: 'messageGroup',
+        data: {
+          mode,
+          groupName,
+          direction: 'receives' as const,
+          messageCount: groupData.messages.length,
+          messageTypes: [...new Set(groupData.messages.map((m: any) => m.collection))],
+          messages: groupData.messages.map((msg: any) => ({
+            message: { ...msg, data: { ...msg.data, ...getOperationFields(msg.data) } },
+            channels: findPointerForMessage(msg)?.from || [],
+          })),
+          service: { id: service.data.id, version: service.data.version },
+          expandedNodes,
+          expandedEdges,
+        },
+      });
+
+      edges.push(
+        createEdge({
+          id: `${groupNodeId}-to-${serviceNodeId}`,
+          source: groupNodeId,
+          target: serviceNodeId,
+          label: `consumes ${groupData.messages.length}\nmessages`,
+          type: 'multiline',
+          markerEnd: {
+            type: MarkerType.ArrowClosed,
+            color: '#666',
+            width: 20,
+            height: 20,
+          },
+        })
+      );
+    }
+
+    // Ungrouped receives go through existing path
+    receivesPartition.ungrouped.messages.forEach((receive) => {
+      const receiveRaw = receivesRaw.find(
+        (r) => r.id === (receive as any).data.id && versionMatches(r.version, (receive as any).data.version)
+      );
+      const targetChannels = receiveRaw?.from;
+
+      const { nodes: consumedMessageNodes, edges: consumedMessageEdges } = getNodesAndEdgesForConsumedMessage({
+        message: receive as any,
+        targetChannels: targetChannels,
+        services,
+        agents,
+        currentNodes: nodes,
+        target: service,
+        mode,
+        channels,
+        channelMap,
+      });
+
+      nodes.push(...consumedMessageNodes);
+      edges.push(...consumedMessageEdges);
+    });
+  }
+
+  // The service itself
+  nodes.push({
+    id: generateIdForNode(service),
+    sourcePosition: 'right',
+    targetPosition: 'left',
+    data: getResourceNodeData(service, mode),
+    type: service.collection,
+  });
+
+  // Any containers the service writes to
+  writesTo.forEach((writeTo) => {
+    nodes.push({
+      id: generateIdForNode(writeTo),
+      sourcePosition: 'right',
+      targetPosition: 'left',
+      data: {
+        mode,
+        data: { ...writeTo.data },
+        contextMenu: buildContextMenuForResource({ collection: 'entities', id: writeTo.data.id, version: writeTo.data.version }),
+      },
+      type: 'data',
+    });
+
+    // If its not in the reads/and writes to, we need to add the edge
+    if (!bothReadsAndWrites.includes(writeTo)) {
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(service, writeTo),
+          source: generateIdForNode(service),
+          target: generateIdForNode(writeTo),
+          label: `writes to \n (${writeTo.data?.technology})`,
+          type: 'multiline',
+          markerEnd: {
+            type: MarkerType.ArrowClosed,
+            color: '#666',
+            width: 20,
+            height: 20,
+          },
+        })
+      );
+    }
+  });
+
+  if (collection === 'agents') {
+    toolsRaw.forEach((tool) => {
+      const toolNodeId = generateIdForAgentToolNode(service, tool);
+
+      nodes.push({
+        id: toolNodeId,
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        data: {
+          mode,
+          agentTool: {
+            id: sanitizeToolId(`${tool.name}-${tool.type}`),
+            name: tool.name,
+            type: tool.type,
+            icon: tool.icon,
+            url: tool.url,
+            description: tool.description,
+          },
+          contextMenu: tool.url
+            ? [
+                {
+                  label: 'Open tool endpoint',
+                  href: tool.url,
+                  external: true,
+                },
+              ]
+            : undefined,
+        },
+        type: 'agentTool',
+      });
+
+      edges.push(
+        createEdge({
+          id: `${serviceNodeId}-${toolNodeId}`,
+          source: serviceNodeId,
+          target: toolNodeId,
+          label: 'calls tool',
+          type: 'step',
+          animated: false,
+          data: { animated: false },
+          markerEnd: {
+            type: MarkerType.ArrowClosed,
+            color: '#666',
+            width: 20,
+            height: 20,
+          },
+        })
+      );
+    });
+  }
+
+  // Any containers the service reads from
+  readsFrom.forEach((readFrom) => {
+    nodes.push({
+      id: generateIdForNode(readFrom),
+      sourcePosition: 'right',
+      targetPosition: 'left',
+      data: {
+        mode,
+        data: { ...readFrom.data },
+        contextMenu: buildContextMenuForResource({
+          collection: 'entities',
+          id: readFrom.data.id,
+          version: readFrom.data.version,
+        }),
+      },
+      type: 'data',
+    });
+
+    // If its not in the reads/and writes to, we need to add the edge
+    if (!bothReadsAndWrites.includes(readFrom)) {
+      edges.push(
+        createEdge({
+          id: generatedIdForEdge(service, readFrom),
+          source: generateIdForNode(readFrom),
+          target: generateIdForNode(service),
+          label: `reads from \n (${readFrom.data?.technology})`,
+          type: 'multiline',
+          markerStart: {
+            type: MarkerType.ArrowClosed,
+            color: '#666',
+            width: 20,
+            height: 20,
+          },
+          markerEnd: undefined,
+        })
+      );
+    }
+  });
+
+  if (renderMessages) {
+    // Emit group nodes for grouped sends
+    for (const [groupName, groupData] of sendsPartition.grouped) {
+      const groupNodeId = `message-group-${service.data.id}-${service.data.version}-${sanitizeGroupId(groupName)}-sends`;
+
+      // Match each message to its pointer by id/version (not index) — same reason as receives above
+      const findPointerForMessage = (msg: any) =>
+        groupData.pointers.find((p: any) => p.id === msg.data.id && versionMatches(p.version, msg.data.version));
+
+      const { expandedNodes, expandedEdges } = precomputeGroupExpansion(
+        groupData.messages,
+        groupData.messages.map((msg: any) => findPointerForMessage(msg)?.to || []),
+        'sends',
+        { serviceNodeId, services, agents, service, mode, channels, channelMap, existingNodes: nodes, existingEdges: edges }
+      );
+
+      nodes.push({
+        id: groupNodeId,
+        sourcePosition: 'right',
+        targetPosition: 'left',
+        type: 'messageGroup',
+        data: {
+          mode,
+          groupName,
+          direction: 'sends' as const,
+          messageCount: groupData.messages.length,
+          messageTypes: [...new Set(groupData.messages.map((m: any) => m.collection))],
+          messages: groupData.messages.map((msg: any) => ({
+            message: { ...msg, data: { ...msg.data, ...getOperationFields(msg.data) } },
+            channels: findPointerForMessage(msg)?.to || [],
+          })),
+          service: { id: service.data.id, version: service.data.version },
+          expandedNodes,
+          expandedEdges,
+        },
+      });
+
+      edges.push(
+        createEdge({
+          id: `${serviceNodeId}-to-${groupNodeId}`,
+          source: serviceNodeId,
+          target: groupNodeId,
+          label: `publishes ${groupData.messages.length}\nmessages`,
+          type: 'multiline',
+          markerEnd: {
+            type: MarkerType.ArrowClosed,
+            color: '#666',
+            width: 20,
+            height: 20,
+          },
+        })
+      );
+    }
+
+    // Ungrouped sends through existing path
+    sendsPartition.ungrouped.messages.forEach((send) => {
+      const sendRaw = sendsRaw.find(
+        (s) => s.id === (send as any).data.id && versionMatches(s.version, (send as any).data.version)
+      );
+      const sourceChannels = sendRaw?.to;
+
+      const { nodes: producedMessageNodes, edges: producedMessageEdges } = getNodesAndEdgesForProducedMessage({
+        message: send as any,
+        sourceChannels: sourceChannels,
+        services,
+        agents,
+        currentNodes: nodes,
+        source: service,
+        currentEdges: edges,
+        mode,
+        channels,
+        channelMap,
+      });
+
+      nodes.push(...producedMessageNodes);
+      edges.push(...producedMessageEdges);
+    });
+
+    // Handle messages that are both sent and received (filtered to exclude grouped)
+    filteredBothSentAndReceived.forEach((message) => {
+      if (message) {
+        edges.push({
+          id: generatedIdForEdge(service, message) + '-both',
+          source: generateIdForNode(service),
+          target: generateIdForNode(message),
+          label: `${getSendsMessageByMessageType(message?.collection)} & ${getReceivesMessageByMessageType(message?.collection)}`,
+          animated: false,
+          data: { message: { ...message.data } },
+          markerEnd: {
+            type: MarkerType.ArrowClosed,
+            width: 20,
+            height: 20,
+          },
+          style: {
+            strokeWidth: 1,
+            stroke: 'var(--ec-edge-stroke, #6b7280)',
+          },
+        });
+      }
+    });
+  }
+
+  bothReadsAndWrites.forEach((container) => {
+    edges.push({
+      id: generatedIdForEdge(service, container) + '-both',
+      source: generateIdForNode(service),
+      target: generateIdForNode(container),
+      type: 'multiline',
+      // @ts-ignore
+      label: `reads from \n and writes to \n (${container.data.technology})`,
+      markerStart: {
+        type: MarkerType.ArrowClosed,
+        color: '#666',
+        width: 20,
+        height: 20,
+      },
+      markerEnd: {
+        type: MarkerType.ArrowClosed,
+        color: '#666',
+        width: 20,
+        height: 20,
+      },
+    });
+  });
+
+  const uniqueNodesById = new Map<string, any>();
+  nodes.forEach((node: any) => {
+    if (!uniqueNodesById.has(node.id)) {
+      uniqueNodesById.set(node.id, node);
+    }
+  });
+  const uniqueNodes = Array.from(uniqueNodesById.values());
+
+  uniqueNodes.forEach((node: any) => {
+    flow.setNode(node.id, { width: DEFAULT_NODE_WIDTH, height: DEFAULT_NODE_HEIGHT });
+  });
+
+  edges.forEach((edge: any) => {
+    flow.setEdge(edge.source, edge.target);
+  });
+
+  if (layout) {
+    // Render the diagram in memory getting the X and Y
+    dagre.layout(flow);
+  }
+
+  // Find any duplicated edges, and merge them into one edge
+  const uniqueEdgesById = new Map<string, any>();
+  edges.forEach((edge: any) => {
+    const existingEdge = uniqueEdgesById.get(edge.id);
+    if (existingEdge) {
+      if (edge.data?.customColor || existingEdge.data?.customColor) {
+        // Add custom colors to the existing edge when grouped message paths converge.
+        const value = Array.isArray(edge.data?.customColor) ? edge.data.customColor : [edge.data?.customColor].filter(Boolean);
+        const existingValue = Array.isArray(existingEdge.data?.customColor)
+          ? existingEdge.data.customColor
+          : [existingEdge.data?.customColor].filter(Boolean);
+        existingEdge.data = {
+          ...existingEdge.data,
+          customColor: [...value, ...existingValue],
+        };
+      }
+    } else {
+      uniqueEdgesById.set(edge.id, edge);
+    }
+  });
+  const uniqueEdges = Array.from(uniqueEdgesById.values());
+
+  return {
+    nodes: calculatedNodes(flow, uniqueNodes),
+    edges: uniqueEdges,
+  };
+};
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/system-context-node-graph.ts b/packages/core/eventcatalog/src/utils/node-graphs/system-context-node-graph.ts
new file mode 100644
index 000000000..f22f61f88
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/system-context-node-graph.ts
@@ -0,0 +1,400 @@
+import { getCollection } from 'astro:content';
+import type { CollectionEntry } from 'astro:content';
+import dagre from 'dagre';
+import {
+  createDagreGraph,
+  calculatedNodes,
+  createEdge,
+  generateIdForNode,
+  buildContextMenuForSystem,
+  DEFAULT_NODE_HEIGHT,
+} from '@utils/node-graphs/utils/utils';
+import { MarkerType } from '@xyflow/react';
+import { createVersionedMap, findInMap } from '@utils/collections/util';
+
+type DagreGraph = any;
+
+interface NodesAndEdgesProps {
+  id: string;
+  version: string;
+  defaultFlow?: DagreGraph;
+  mode?: 'simple' | 'full';
+  layout?: boolean;
+}
+
+// System nodes are wider than the default to fit the system name + summary comfortably.
+const SYSTEM_NODE_WIDTH = 270;
+// Actor nodes are narrower than systems — a compact pill with an icon + name.
+const ACTOR_NODE_WIDTH = 180;
+
+type SystemActor = {
+  id: string;
+  name?: string;
+  label?: string;
+  direction?: 'inbound' | 'outbound';
+};
+
+type SystemRelationship = {
+  id: string;
+  version?: string;
+  label?: string;
+};
+
+type IncomingSystemRelationship = {
+  source: CollectionEntry<'systems'>;
+  relationship: SystemRelationship;
+};
+
+interface ContextGraphFromSeedsProps {
+  // The systems the breadth-first traversal starts from. The single-system context
+  // diagram seeds with one system; the domain-level diagram seeds with every system
+  // in the domain.
+  seedSystems: CollectionEntry<'systems'>[];
+  systemMap: Map<string, CollectionEntry<'systems'>[]>;
+  serviceMap: Map<string, CollectionEntry<'services'>[]>;
+  defaultFlow?: DagreGraph;
+  mode?: 'simple' | 'full';
+  layout?: boolean;
+}
+
+/**
+ * Shared builder for the System Diagram.
+ *
+ * Starting from the given seed systems, we walk system relationships in both directions
+ * (breadth-first) to the systems it relates to and the systems that relate to it, then
+ * their relationships, and so on — building the reachable neighbourhood. Each system
+ * becomes a node; each relationship that has a `label` becomes a labelled edge
+ * (relationships without a label are intentionally not drawn). Actors are rendered
+ * inline and deduped across all systems.
+ */
+const buildContextGraphFromSeeds = ({
+  seedSystems,
+  systemMap,
+  serviceMap,
+  defaultFlow,
+  mode = 'simple',
+  layout = true,
+}: ContextGraphFromSeedsProps) => {
+  const flow = defaultFlow || createDagreGraph({ ranksep: 280, nodesep: 80, edgesep: 50 });
+  const nodes = new Map<string, any>();
+  const edges = new Map<string, any>();
+
+  // Total messages a system handles = the sum of sends + receives across all of
+  // its services. Used for the "Messages" stat on the system node.
+  const countMessagesForSystem = (system: CollectionEntry<'systems'>) => {
+    return (system.data.services || []).reduce((total, ref) => {
+      const service = findInMap(serviceMap, ref.id, ref.version);
+      if (!service) return total;
+      return total + (service.data.sends || []).length + (service.data.receives || []).length;
+    }, 0);
+  };
+
+  // Actor node ids, tracked so they can be sized differently during layout.
+  const actorNodeIds = new Set<string>();
+  // System node ids, tracked so we can detect reciprocal system-to-system
+  // relationships and collapse them into a single double-headed edge.
+  const systemNodeIds = new Set<string>();
+  const incomingRelationshipsByTargetNodeId = new Map<string, IncomingSystemRelationship[]>();
+
+  for (const versionedSystems of systemMap.values()) {
+    for (const source of versionedSystems) {
+      const relationships = (source.data.relationships || []) as SystemRelationship[];
+
+      for (const relationship of relationships) {
+        const target = findInMap(systemMap, relationship.id, relationship.version);
+        if (!target) continue;
+
+        const targetNodeId = generateIdForNode(target);
+        const incoming = incomingRelationshipsByTargetNodeId.get(targetNodeId) || [];
+        incoming.push({ source, relationship });
+        incomingRelationshipsByTargetNodeId.set(targetNodeId, incoming);
+      }
+    }
+  }
+
+  // Add (or reuse) an actor node. Actors are inline and deduped by `actor:{id}`,
+  // so the same actor referenced from multiple systems appears once.
+  const addActorNode = (actor: SystemActor) => {
+    const nodeId = `actor-${actor.id}`;
+    if (nodes.has(nodeId)) return nodeId;
+
+    actorNodeIds.add(nodeId);
+    nodes.set(nodeId, {
+      id: nodeId,
+      type: 'context-actor',
+      sourcePosition: 'right',
+      targetPosition: 'left',
+      data: {
+        mode,
+        name: actor.name || actor.id,
+      },
+      position: { x: 0, y: 0 },
+    });
+
+    return nodeId;
+  };
+
+  const addSystemNode = (system: CollectionEntry<'systems'>) => {
+    const nodeId = generateIdForNode(system);
+    systemNodeIds.add(nodeId);
+    if (nodes.has(nodeId)) return nodeId;
+
+    nodes.set(nodeId, {
+      id: nodeId,
+      type: 'systems',
+      sourcePosition: 'right',
+      targetPosition: 'left',
+      data: {
+        mode,
+        system: { ...system.data },
+        // Counts of what the system groups, shown as a stats row on the node.
+        // The raw frontmatter arrays are pointer lists, so their length is the count.
+        servicesCount: (system.data.services || []).length,
+        entitiesCount: (system.data.entities || []).length,
+        containersCount: (system.data.containers || []).length,
+        messagesCount: countMessagesForSystem(system),
+        contextMenu: buildContextMenuForSystem({ id: system.data.id, version: system.data.version }),
+      },
+      position: { x: 0, y: 0 },
+    });
+
+    return nodeId;
+  };
+
+  const addSystemRelationshipEdge = ({
+    sourceNodeId,
+    targetNodeId,
+    label,
+  }: {
+    sourceNodeId: string;
+    targetNodeId: string;
+    label?: string;
+  }) => {
+    if (!label) return;
+
+    const edgeId = `${sourceNodeId}-${targetNodeId}`;
+    edges.set(
+      edgeId,
+      createEdge({
+        id: edgeId,
+        source: sourceNodeId,
+        target: targetNodeId,
+        label,
+        type: 'straight',
+        markerEnd: { type: MarkerType.ArrowClosed, width: 20, height: 20 },
+      })
+    );
+  };
+
+  // Breadth-first traversal over the relationship graph, following each system's
+  // `relationships` to other systems and reverse relationships from other systems.
+  // We visit each system once.
+  const visited = new Set<string>();
+  const queue: CollectionEntry<'systems'>[] = [...seedSystems];
+
+  while (queue.length > 0) {
+    const system = queue.shift() as CollectionEntry<'systems'>;
+    const sourceNodeId = generateIdForNode(system);
+
+    if (visited.has(sourceNodeId)) continue;
+    visited.add(sourceNodeId);
+
+    addSystemNode(system);
+
+    const relationships = (system.data.relationships || []) as SystemRelationship[];
+
+    for (const relationship of relationships) {
+      const target = findInMap(systemMap, relationship.id, relationship.version);
+      // Skip dangling targets — degrade gracefully like the other pointer types.
+      if (!target) continue;
+
+      const targetNodeId = addSystemNode(target);
+
+      // Only draw an edge when the relationship declares a label. A relationship without a
+      // label still pulls the target system into the diagram, but has no edge drawn.
+      addSystemRelationshipEdge({ sourceNodeId, targetNodeId, label: relationship.label });
+
+      if (!visited.has(targetNodeId)) {
+        queue.push(target);
+      }
+    }
+
+    const incomingRelationships = incomingRelationshipsByTargetNodeId.get(sourceNodeId) || [];
+    for (const { source, relationship } of incomingRelationships) {
+      const incomingSourceNodeId = addSystemNode(source);
+
+      // Preserve relationship direction: the referring system remains the edge source,
+      // even though this traversal discovered it from the target side.
+      addSystemRelationshipEdge({
+        sourceNodeId: incomingSourceNodeId,
+        targetNodeId: sourceNodeId,
+        label: relationship.label,
+      });
+
+      if (!visited.has(incomingSourceNodeId)) {
+        queue.push(source);
+      }
+    }
+
+    // Actors that interact with this system. Each becomes an actor node with an
+    // edge whose direction depends on `direction` (inbound = actor -> system,
+    // outbound = system -> actor). Actors don't pull other systems into the graph.
+    const actors = (system.data.actors || []) as SystemActor[];
+
+    for (const actor of actors) {
+      const actorNodeId = addActorNode(actor);
+      const direction = actor.direction || 'inbound';
+      const source = direction === 'inbound' ? actorNodeId : sourceNodeId;
+      const target = direction === 'inbound' ? sourceNodeId : actorNodeId;
+
+      const edgeId = `${source}-${target}`;
+      if (edges.has(edgeId)) continue;
+
+      edges.set(
+        edgeId,
+        createEdge({
+          id: edgeId,
+          source,
+          target,
+          label: actor.label,
+          type: 'straight',
+          markerEnd: { type: MarkerType.ArrowClosed, width: 20, height: 20 },
+        })
+      );
+    }
+  }
+
+  // Collapse reciprocal system-to-system relationships. When system A relates to B
+  // and B also relates back to A, we'd otherwise draw two parallel edges. Instead we
+  // keep a single edge with arrowheads on both ends. Each direction's label is
+  // preserved (joined when they differ). Only system↔system edges are merged — actor
+  // edges are left untouched.
+  const mergedEdgeKeys = new Set<string>();
+  for (const edge of Array.from(edges.values())) {
+    if (mergedEdgeKeys.has(edge.id)) continue;
+    if (!systemNodeIds.has(edge.source) || !systemNodeIds.has(edge.target)) continue;
+
+    const reverseId = `${edge.target}-${edge.source}`;
+    const reverse = edges.get(reverseId);
+    if (!reverse || reverseId === edge.id) continue;
+
+    // Merge the two labels, keeping a single value when they match.
+    const labels = [edge.label, reverse.label].filter(Boolean);
+    const mergedLabel = labels.length > 1 && labels[0] !== labels[1] ? labels.join(' / ') : labels[0];
+
+    edges.set(edge.id, {
+      ...edge,
+      label: mergedLabel,
+      markerStart: { type: MarkerType.ArrowClosed, width: 20, height: 20 },
+    });
+    edges.delete(reverseId);
+    mergedEdgeKeys.add(edge.id);
+    mergedEdgeKeys.add(reverseId);
+  }
+
+  // Lay the graph out
+  nodes.forEach((node) =>
+    flow.setNode(node.id, {
+      width: actorNodeIds.has(node.id) ? ACTOR_NODE_WIDTH : SYSTEM_NODE_WIDTH,
+      height: DEFAULT_NODE_HEIGHT,
+    })
+  );
+  edges.forEach((edge) => flow.setEdge(edge.source, edge.target));
+
+  if (layout) {
+    dagre.layout(flow);
+  }
+
+  return {
+    nodes: calculatedNodes(flow, Array.from(nodes.values())),
+    edges: [...edges.values()],
+  };
+};
+
+/**
+ * Builds the System Diagram for a single system, seeding the traversal from
+ * that system and walking its relationships and actors outward.
+ */
+export const getNodesAndEdges = async ({ id, version, defaultFlow, mode = 'simple', layout = true }: NodesAndEdgesProps) => {
+  const [allSystems, allServices] = await Promise.all([getCollection('systems'), getCollection('services')]);
+  const systemMap = createVersionedMap(allSystems);
+  const serviceMap = createVersionedMap(allServices);
+
+  const rootSystem = findInMap(systemMap, id, version);
+
+  // Nothing found...
+  if (!rootSystem) {
+    return { nodes: [], edges: [] };
+  }
+
+  return buildContextGraphFromSeeds({ seedSystems: [rootSystem], systemMap, serviceMap, defaultFlow, mode, layout });
+};
+
+/**
+ * Builds the System Diagram for a whole domain: seeds the traversal with every
+ * system the domain declares, then walks their relationships and actors. The result is
+ * the domain's systems plus any related systems they point at (or that point at them),
+ * with actors rendered inline — giving a single context view across the domain.
+ */
+export const getNodesAndEdgesForDomainSystems = async ({
+  id,
+  version,
+  defaultFlow,
+  mode = 'simple',
+  layout = true,
+}: NodesAndEdgesProps) => {
+  const [allDomains, allSystems, allServices] = await Promise.all([
+    getCollection('domains'),
+    getCollection('systems'),
+    getCollection('services'),
+  ]);
+  const domainMap = createVersionedMap(allDomains);
+  const systemMap = createVersionedMap(allSystems);
+  const serviceMap = createVersionedMap(allServices);
+
+  const domain = findInMap(domainMap, id, version);
+
+  // Nothing found, or the domain has no systems to seed from.
+  if (!domain) {
+    return { nodes: [], edges: [] };
+  }
+
+  const seedSystems = (domain.data.systems || [])
+    .map((ref: { id: string; version?: string }) => findInMap(systemMap, ref.id, ref.version))
+    .filter((system): system is CollectionEntry<'systems'> => !!system);
+
+  if (seedSystems.length === 0) {
+    return { nodes: [], edges: [] };
+  }
+
+  return buildContextGraphFromSeeds({ seedSystems, systemMap, serviceMap, defaultFlow, mode, layout });
+};
+
+interface AllSystemsProps {
+  defaultFlow?: DagreGraph;
+  mode?: 'simple' | 'full';
+  layout?: boolean;
+}
+
+/**
+ * Builds a global System Context Map for the whole catalog: every system becomes a
+ * seed, so the traversal draws all systems, the relationships between them, and the
+ * actors around them — a single map of how every system in the catalog relates.
+ */
+export const getNodesAndEdgesForAllSystems = async ({ defaultFlow, mode = 'simple', layout = true }: AllSystemsProps = {}) => {
+  const [allSystems, allServices] = await Promise.all([getCollection('systems'), getCollection('services')]);
+  const systemMap = createVersionedMap(allSystems);
+  const serviceMap = createVersionedMap(allServices);
+
+  // Seed with the latest version of every system. `systemMap` sorts each entry so
+  // index [0] is the latest, which avoids drawing every historical version.
+  const seedSystems = Array.from(systemMap.values())
+    .map((versions) => versions[0])
+    .filter((system): system is CollectionEntry<'systems'> => !!system);
+
+  if (seedSystems.length === 0) {
+    return { nodes: [], edges: [] };
+  }
+
+  return buildContextGraphFromSeeds({ seedSystems, systemMap, serviceMap, defaultFlow, mode, layout });
+};
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/systems-node-graph.ts b/packages/core/eventcatalog/src/utils/node-graphs/systems-node-graph.ts
new file mode 100644
index 000000000..5c55e7fad
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/systems-node-graph.ts
@@ -0,0 +1,208 @@
+import { getCollection } from 'astro:content';
+import dagre from 'dagre';
+import { createDagreGraph, calculatedNodes, DEFAULT_NODE_WIDTH, DEFAULT_NODE_HEIGHT } from '@utils/node-graphs/utils/utils';
+import { getNodesAndEdges as getServicesNodeAndEdges } from './services-node-graph';
+import { getNodesAndEdges as getContainerNodeAndEdges } from './container-node-graph';
+import merge from 'lodash.merge';
+import { createVersionedMap, findInMap } from '@utils/collections/util';
+
+type DagreGraph = any;
+
+interface NodesAndEdgesProps {
+  id: string;
+  version: string;
+  defaultFlow?: DagreGraph;
+  mode?: 'simple' | 'full';
+  group?: boolean;
+  // When true, wraps the whole system graph in a single parent boundary node
+  // labelled with the system name. Used by the standalone System Diagram.
+  wrapInSystemGroup?: boolean;
+  channelRenderMode?: 'single' | 'flat';
+  layout?: boolean;
+}
+
+export const getNodesAndEdges = async ({
+  id,
+  version,
+  defaultFlow,
+  mode = 'simple',
+  group = false,
+  wrapInSystemGroup = false,
+  channelRenderMode = 'flat',
+  layout = true,
+}: NodesAndEdgesProps) => {
+  const flow = defaultFlow || createDagreGraph({ ranksep: 360, nodesep: 50, edgesep: 50 });
+  let nodes = new Map(),
+    edges = new Map();
+
+  // 1. Parallel Fetching
+  const [systems, services, containers] = await Promise.all([
+    getCollection('systems'),
+    getCollection('services'),
+    getCollection('containers'),
+  ]);
+
+  const system = systems.find((s) => s.data.id === id && s.data.version === version);
+
+  // Nothing found...
+  if (!system) {
+    return {
+      nodes: [],
+      edges: [],
+    };
+  }
+
+  // 2. Build optimized maps
+  const serviceMap = createVersionedMap(services);
+  const containerMap = createVersionedMap(containers);
+
+  const rawServices = system?.data.services || [];
+
+  // Optimized hydration
+  const systemServicesWithVersion = rawServices
+    .map((service) => findInMap(serviceMap, service.id, service.version))
+    .filter((s): s is any => !!s)
+    .map((svc) => ({ id: svc.data.id, version: svc.data.version }));
+
+  // Hydrate the data stores (containers) mapped directly to the system
+  const systemContainersWithVersion = (system?.data.containers || [])
+    .map((container) => findInMap(containerMap, container.id, container.version))
+    .filter((c): c is any => !!c)
+    .map((container) => ({ id: container.data.id, version: container.data.version }));
+
+  // Grab the node-graph for each service in the system and merge them into one graph
+  for (const service of systemServicesWithVersion) {
+    const { nodes: serviceNodes, edges: serviceEdges } = await getServicesNodeAndEdges({
+      id: service.id,
+      version: service.version,
+      defaultFlow: flow,
+      mode,
+      renderAllEdges: true,
+      channelRenderMode,
+      layout: false,
+    });
+
+    serviceNodes.forEach((n) => {
+      /**
+       * A message could be sent by one service and received by another service in the same system.
+       * So, we need to deep merge the message to keep the `showSource` and `showTarget` as true.
+       */
+      nodes.set(n.id, nodes.has(n.id) ? merge(nodes.get(n.id), n) : n);
+    });
+    // @ts-ignore
+    serviceEdges.forEach((e) => edges.set(e.id, e));
+  }
+
+  // Grab the node-graph for each data store (container) in the system and merge them into one graph.
+  // This renders the data store along with the services that read from / write to it, the same way
+  // services are merged above.
+  for (const container of systemContainersWithVersion) {
+    const { nodes: containerNodes, edges: containerEdges } = await getContainerNodeAndEdges({
+      id: container.id,
+      version: container.version,
+      defaultFlow: flow,
+      mode,
+      channelRenderMode,
+      layout: false,
+    });
+
+    containerNodes.forEach((n) => {
+      nodes.set(n.id, nodes.has(n.id) ? merge(nodes.get(n.id), n) : n);
+    });
+    // @ts-ignore
+    containerEdges.forEach((e) => edges.set(e.id, e));
+  }
+
+  // Add group node to the graph (used when a system is rendered inside another view)
+  if (group) {
+    nodes.forEach((n) => {
+      nodes.set(n.id, { ...n, data: { ...n.data, group: { type: 'System', value: system?.data.name, id: system?.data.id } } });
+    });
+  }
+
+  if (layout) {
+    dagre.layout(flow);
+  }
+
+  let laidOutNodes = calculatedNodes(flow, Array.from(nodes.values()));
+
+  // Wrap everything inside a single parent "system group" boundary node, so all
+  // the services / data stores / messages visibly belong to one system. We only
+  // do this when this graph owns its own layout (`layout` true) — when it's
+  // being merged into a larger graph (e.g. a domain view) the host owns grouping.
+  if (wrapInSystemGroup && layout && laidOutNodes.length > 0) {
+    laidOutNodes = wrapNodesInSystemGroup(laidOutNodes, flow, system);
+  }
+
+  return {
+    nodes: laidOutNodes,
+    edges: [...edges.values()],
+  };
+};
+
+// Padding around the children inside the group box, and headroom for the header banner.
+const GROUP_PADDING_X = 100;
+const GROUP_PADDING_Y = 100;
+const GROUP_HEADER_HEIGHT = 64;
+
+/**
+ * Wraps a set of already-laid-out nodes in one parent `system-group` node.
+ *
+ * The rest of the app uses dagre's node position directly as the ReactFlow
+ * position, so we stay in that same coordinate space. Child nodes under a
+ * `parentId` are positioned relative to the parent, so we:
+ *   1. compute the bounding box of all nodes (using dagre position + size),
+ *   2. create a parent group node at the box origin (minus padding/header),
+ *   3. re-home every node as a child, offset by the group origin.
+ */
+const wrapNodesInSystemGroup = (laidOutNodes: any[], flow: DagreGraph, system: any) => {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+
+  for (const node of laidOutNodes) {
+    const dims = flow.node(node.id) || {};
+    const width = dims.width ?? DEFAULT_NODE_WIDTH;
+    const height = dims.height ?? DEFAULT_NODE_HEIGHT;
+
+    minX = Math.min(minX, node.position.x);
+    minY = Math.min(minY, node.position.y);
+    maxX = Math.max(maxX, node.position.x + width);
+    maxY = Math.max(maxY, node.position.y + height);
+  }
+
+  // Origin of the group box (room for padding + the header banner at the top).
+  const groupX = minX - GROUP_PADDING_X;
+  const groupY = minY - GROUP_PADDING_Y - GROUP_HEADER_HEIGHT;
+  const groupWidth = maxX - minX + GROUP_PADDING_X * 2;
+  const groupHeight = maxY - minY + GROUP_PADDING_Y * 2 + GROUP_HEADER_HEIGHT;
+
+  const groupId = `system-group-${system.data.id}-${system.data.version}`;
+
+  const groupNode = {
+    id: groupId,
+    type: 'system-group',
+    position: { x: groupX, y: groupY },
+    draggable: false,
+    selectable: false,
+    style: { width: groupWidth, height: groupHeight },
+    data: {
+      system: { name: system.data.name, version: system.data.version },
+    },
+  };
+
+  // Re-home each node as a child, with its position relative to the group origin.
+  const childNodes = laidOutNodes.map((node) => ({
+    ...node,
+    parentId: groupId,
+    extent: 'parent',
+    position: {
+      x: node.position.x - groupX,
+      y: node.position.y - groupY,
+    },
+  }));
+
+  // Parent must come before its children in the array for ReactFlow.
+  return [groupNode, ...childNodes];
+};
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/utils/__tests__/partition.test.ts b/packages/core/eventcatalog/src/utils/node-graphs/utils/__tests__/partition.test.ts
new file mode 100644
index 000000000..7e543da11
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/utils/__tests__/partition.test.ts
@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import { partitionMessagesByGroup } from '../utils';
+
+const makePointer = (id: string, version: string, group?: string) => ({
+  id,
+  version,
+  ...(group ? { group } : {}),
+});
+
+const makeMessage = (id: string, version: string, collection: string) => ({
+  data: { id, version },
+  collection,
+});
+
+describe('partitionMessagesByGroup', () => {
+  it('returns all messages as ungrouped when no pointers have group', () => {
+    const pointers = [makePointer('Evt1', '1.0.0'), makePointer('Evt2', '2.0.0')];
+    const messages = [makeMessage('Evt1', '1.0.0', 'events'), makeMessage('Evt2', '2.0.0', 'events')];
+
+    const result = partitionMessagesByGroup(pointers, messages);
+
+    expect(result.grouped.size).toBe(0);
+    expect(result.ungrouped.messages).toHaveLength(2);
+    expect(result.ungrouped.pointers).toHaveLength(2);
+  });
+
+  it('groups messages by group name', () => {
+    const pointers = [
+      makePointer('Evt1', '1.0.0', 'GroupA'),
+      makePointer('Evt2', '2.0.0', 'GroupA'),
+      makePointer('Evt3', '1.0.0', 'GroupB'),
+    ];
+    const messages = [
+      makeMessage('Evt1', '1.0.0', 'events'),
+      makeMessage('Evt2', '2.0.0', 'events'),
+      makeMessage('Evt3', '1.0.0', 'commands'),
+    ];
+
+    const result = partitionMessagesByGroup(pointers, messages);
+
+    expect(result.grouped.size).toBe(2);
+    expect(result.grouped.get('GroupA')!.messages).toHaveLength(2);
+    expect(result.grouped.get('GroupA')!.pointers).toHaveLength(2);
+    expect(result.grouped.get('GroupB')!.messages).toHaveLength(1);
+    expect(result.ungrouped.messages).toHaveLength(0);
+  });
+
+  it('handles mix of grouped and ungrouped', () => {
+    const pointers = [makePointer('Evt1', '1.0.0', 'GroupA'), makePointer('Evt2', '2.0.0')];
+    const messages = [makeMessage('Evt1', '1.0.0', 'events'), makeMessage('Evt2', '2.0.0', 'events')];
+
+    const result = partitionMessagesByGroup(pointers, messages);
+
+    expect(result.grouped.size).toBe(1);
+    expect(result.grouped.get('GroupA')!.messages).toHaveLength(1);
+    expect(result.ungrouped.messages).toHaveLength(1);
+  });
+
+  it('same message in multiple groups creates entries in both groups', () => {
+    const pointers = [makePointer('Evt1', '1.0.0', 'GroupA'), makePointer('Evt1', '1.0.0', 'GroupB')];
+    const messages = [makeMessage('Evt1', '1.0.0', 'events'), makeMessage('Evt1', '1.0.0', 'events')];
+
+    const result = partitionMessagesByGroup(pointers, messages);
+
+    expect(result.grouped.get('GroupA')!.messages).toHaveLength(1);
+    expect(result.grouped.get('GroupB')!.messages).toHaveLength(1);
+  });
+
+  it('skips pointers whose message cannot be found (hydration miss)', () => {
+    const pointers = [makePointer('Missing', '1.0.0', 'GroupA')];
+    const messages: any[] = [];
+
+    const result = partitionMessagesByGroup(pointers, messages);
+
+    expect(result.grouped.get('GroupA')!.messages).toHaveLength(0);
+    expect(result.grouped.get('GroupA')!.pointers).toHaveLength(1);
+  });
+});
diff --git a/packages/core/eventcatalog/src/utils/node-graphs/utils/utils.ts b/packages/core/eventcatalog/src/utils/node-graphs/utils/utils.ts
new file mode 100644
index 000000000..79c505965
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/node-graphs/utils/utils.ts
@@ -0,0 +1,430 @@
+// Can't use the CollectionEntry type from astro:content  because a client component is using this util
+
+import { MarkerType, Position, type Edge, type Node } from '@xyflow/react';
+import dagre from 'dagre';
+import { getItemsFromCollectionByIdAndSemverOrLatest, versionMatches as versionMatchesUtil } from '@utils/collections/util';
+import { buildUrl } from '@utils/url-builder';
+
+interface BaseCollectionData {
+  id: string;
+  version: string;
+}
+
+interface CollectionItem {
+  collection: string;
+  data: BaseCollectionData;
+}
+
+interface MessageCollectionItem extends CollectionItem {
+  collection: 'commands' | 'events' | 'queries';
+}
+
+/**
+ * Determines if a service's accepted version pattern matches an actual message version.
+ *
+ * @param acceptedVersion - The version pattern a service declares (in sends/receives config)
+ * @param actualMessageVersion - The specific version of the actual catalogued message
+ * @returns true if the actual message version satisfies the accepted version pattern
+ */
+export const versionMatches = (acceptedVersion: string | undefined, actualMessageVersion: string | undefined): boolean => {
+  if (!acceptedVersion || acceptedVersion === 'latest') return true;
+
+  if (!actualMessageVersion || actualMessageVersion === 'latest') {
+    return !acceptedVersion || acceptedVersion === 'latest';
+  }
+
+  return versionMatchesUtil(actualMessageVersion, acceptedVersion);
+};
+
+export const generateIdForNode = (node: CollectionItem) => {
+  return `${node.data.id}-${node.data.version}`;
+};
+export const generateIdForNodes = (nodes: any) => {
+  return nodes.map((node: any) => `${node.data.id}-${node.data.version}`).join('-');
+};
+export const generatedIdForEdge = (source: CollectionItem, target: CollectionItem) => {
+  return `${source.data.id}-${source.data.version}-${target.data.id}-${target.data.version}`;
+};
+
+export const getColorFromString = (id: string) => {
+  // Takes the given id (string) and returns a custom hex color based on the id
+  // Create a hash from the string
+  let hash = 0;
+  for (let i = 0; i < id.length; i++) {
+    hash = id.charCodeAt(i) + ((hash << 5) - hash);
+  }
+
+  // Convert the hash into a hex color
+  let color = '#';
+  for (let i = 0; i < 3; i++) {
+    const value = (hash >> (i * 8)) & 0xff;
+    color += value.toString(16).padStart(2, '0');
+  }
+
+  return color;
+};
+
+export const getEdgeLabelForServiceAsTarget = (data: MessageCollectionItem) => {
+  const type = data.collection;
+  switch (type) {
+    case 'commands':
+      return 'invokes';
+    case 'events':
+      return 'publishes \nevent';
+    case 'queries':
+      return 'requests';
+    default:
+      return 'sends to';
+  }
+};
+export const getEdgeLabelForMessageAsSource = (data: MessageCollectionItem, throughChannel = false) => {
+  const type = data.collection;
+  switch (type) {
+    case 'commands':
+      return 'accepts';
+    case 'events':
+      return throughChannel ? 'subscribed to' : 'subscribed by';
+    case 'queries':
+      return 'accepts';
+    default:
+      return 'sends to';
+  }
+};
+
+export const calculatedNodes = (flow: dagre.graphlib.Graph, nodes: Node[]) => {
+  return nodes.map((node: any) => {
+    const { x, y } = flow.node(node.id);
+    return { ...node, position: { x, y } };
+  });
+};
+
+export const DEFAULT_NODE_WIDTH = 150;
+export const DEFAULT_NODE_HEIGHT = 120;
+
+// Creates a new dagre graph
+export const createDagreGraph = ({ ranksep = 180, nodesep = 50, ...rest }: any) => {
+  const graph = new dagre.graphlib.Graph({ compound: true });
+  graph.setGraph({ rankdir: 'LR', ranksep, nodesep, ...rest });
+  graph.setDefaultEdgeLabel(() => ({}));
+  return graph;
+};
+
+export const createEdge = (edgeOptions: Edge) => {
+  return {
+    label: 'subscribed by',
+    animated: false,
+    // markerStart: {
+    //   type: MarkerType.Arrow,
+    //   width: 20,
+    //   height: 20,
+    // },
+    markerEnd: {
+      type: MarkerType.ArrowClosed,
+      width: 20,
+      height: 20,
+    },
+    style: {
+      strokeWidth: 1,
+      stroke: 'var(--ec-edge-stroke, #6b7280)',
+    },
+    ...edgeOptions,
+  };
+};
+
+export const createNode = (values: Node): Node => {
+  return {
+    sourcePosition: Position.Right,
+    targetPosition: Position.Left,
+    ...values,
+  };
+};
+
+type DagreGraph = any;
+
+type ContextMenuItem = {
+  label: string;
+  href: string;
+  download?: string;
+  external?: boolean;
+  separator?: boolean;
+};
+
+export const buildContextMenuForMessage = ({
+  id,
+  version,
+  name,
+  collection,
+  schemaPath,
+}: {
+  id: string;
+  version: string;
+  name: string;
+  collection: string;
+  schemaPath?: string;
+}): ContextMenuItem[] => {
+  const items: ContextMenuItem[] = [{ label: 'Read documentation', href: buildUrl(`/docs/${collection}/${id}/${version}`) }];
+
+  if (schemaPath) {
+    items.push({
+      label: 'Download schema',
+      href: buildUrl(`/generated/${collection}/${id}/${schemaPath}`, true),
+      download: `${name}(${version})-${schemaPath}`,
+      external: true,
+      separator: true,
+    });
+  }
+
+  items.push({
+    label: 'Read changelog',
+    href: buildUrl(`/docs/${collection}/${id}/${version}/changelog`),
+    external: true,
+    separator: !schemaPath,
+  });
+
+  return items;
+};
+
+const getSpecMenuItems = (
+  specs: unknown,
+  id: string,
+  version: string
+): { label: string; href: string; separator?: boolean }[] => {
+  const items: { label: string; href: string; separator?: boolean }[] = [];
+
+  const addSpec = (type: string, filePath: string, isFirst: boolean) => {
+    const filename = filePath.split('/').pop() || filePath;
+    const filenameNoExt = filename.replace(/\.[^/.]+$/, '');
+    const typeLower = type.toLowerCase();
+
+    let label = 'View specification';
+    let urlSegment = 'spec';
+    if (typeLower === 'asyncapi') {
+      label = 'View AsyncAPI spec';
+      urlSegment = 'asyncapi';
+    } else if (typeLower === 'openapi') {
+      label = 'View OpenAPI spec';
+      urlSegment = 'spec';
+    } else if (typeLower === 'graphql') {
+      label = 'View GraphQL spec';
+      urlSegment = 'graphql';
+    }
+
+    items.push({
+      label,
+      href: buildUrl(`/docs/services/${id}/${version}/${urlSegment}/${filenameNoExt}`),
+      separator: isFirst,
+    });
+  };
+
+  if (Array.isArray(specs)) {
+    specs.forEach((spec: any, i: number) => {
+      if (spec?.type && spec?.path) addSpec(spec.type, spec.path, i === 0);
+    });
+  } else if (specs && typeof specs === 'object') {
+    const legacy = specs as Record<string, string>;
+    let first = true;
+    if (legacy.asyncapiPath) {
+      addSpec('asyncapi', legacy.asyncapiPath, first);
+      first = false;
+    }
+    if (legacy.openapiPath) {
+      addSpec('openapi', legacy.openapiPath, first);
+      first = false;
+    }
+    if (legacy.graphqlPath) {
+      addSpec('graphql', legacy.graphqlPath, first);
+    }
+  }
+
+  return items;
+};
+
+export const buildContextMenuForService = ({
+  id,
+  version,
+  specifications,
+  repository,
+}: {
+  id: string;
+  version: string;
+  specifications?: unknown;
+  repository?: { url: string };
+}): ContextMenuItem[] => {
+  const items: ContextMenuItem[] = [{ label: 'Read documentation', href: buildUrl(`/docs/services/${id}/${version}`) }];
+
+  const specItems = getSpecMenuItems(specifications, id, version);
+  items.push(...specItems);
+
+  if (repository?.url) {
+    items.push({
+      label: 'View code repository',
+      href: repository.url,
+      external: true,
+      separator: true,
+    });
+  }
+
+  items.push({
+    label: 'Read changelog',
+    href: buildUrl(`/docs/services/${id}/${version}/changelog`),
+    external: true,
+    separator: !repository?.url && specItems.length === 0,
+  });
+
+  return items;
+};
+
+export const buildContextMenuForAgent = ({
+  id,
+  version,
+  repository,
+}: {
+  id: string;
+  version: string;
+  repository?: { url: string };
+}): ContextMenuItem[] => {
+  const items: ContextMenuItem[] = [{ label: 'Read documentation', href: buildUrl(`/docs/agents/${id}/${version}`) }];
+
+  if (repository?.url) {
+    items.push({
+      label: 'View code repository',
+      href: repository.url,
+      external: true,
+      separator: true,
+    });
+  }
+
+  items.push({
+    label: 'Read changelog',
+    href: buildUrl(`/docs/agents/${id}/${version}/changelog`),
+    external: true,
+    separator: !repository?.url,
+  });
+
+  return items;
+};
+
+export const buildContextMenuForResource = ({
+  collection,
+  id,
+  version,
+}: {
+  collection: string;
+  id: string;
+  version: string;
+}): ContextMenuItem[] => {
+  return [
+    { label: 'Read documentation', href: buildUrl(`/docs/${collection}/${id}/${version}`) },
+    {
+      label: 'Read changelog',
+      href: buildUrl(`/docs/${collection}/${id}/${version}/changelog`),
+      external: true,
+      separator: true,
+    },
+  ];
+};
+
+/**
+ * Context menu for a system node on the System Diagram.
+ * Offers the system's documentation, its architecture map, and its own context view.
+ */
+export const buildContextMenuForSystem = ({ id, version }: { id: string; version: string }): ContextMenuItem[] => {
+  return [
+    { label: 'Read documentation', href: buildUrl(`/docs/systems/${id}/${version}`) },
+    { label: 'View map', href: buildUrl(`/visualiser/systems/${id}/${version}`) },
+    { label: 'View context', href: buildUrl(`/visualiser/systems/${id}/${version}/context`) },
+  ];
+};
+
+/**
+ * Extracts operation fields (method, path, statusCodes) from a message's
+ * `operation` frontmatter and returns them as top-level props the visualiser expects.
+ */
+export const getOperationFields = (data: Record<string, any>) => {
+  const op = data.operation;
+  if (!op) return {};
+  return {
+    ...(op.method ? { method: op.method } : {}),
+    ...(op.path ? { path: op.path } : {}),
+    ...(Array.isArray(op.statusCodes) && op.statusCodes.length > 0
+      ? { statusCodes: op.statusCodes.map(Number).filter((n: number) => !isNaN(n)) }
+      : {}),
+  };
+};
+
+interface PointerWithGroup {
+  id: string;
+  version?: string;
+  group?: string;
+  [key: string]: any;
+}
+
+interface PartitionResult {
+  grouped: Map<string, { messages: CollectionItem[]; pointers: PointerWithGroup[] }>;
+  ungrouped: { messages: CollectionItem[]; pointers: PointerWithGroup[] };
+}
+
+/**
+ * Partition raw message pointers and their hydrated messages by group.
+ * Matches each pointer to its hydrated message by id + version.
+ */
+export const partitionMessagesByGroup = (
+  rawPointers: PointerWithGroup[],
+  hydratedMessages: CollectionItem[]
+): PartitionResult => {
+  const grouped = new Map<string, { messages: CollectionItem[]; pointers: PointerWithGroup[] }>();
+  const ungrouped: { messages: CollectionItem[]; pointers: PointerWithGroup[] } = {
+    messages: [],
+    pointers: [],
+  };
+
+  rawPointers.forEach((pointer) => {
+    const message = hydratedMessages.find((m) => m.data.id === pointer.id && versionMatches(pointer.version, m.data.version));
+
+    if (pointer.group) {
+      if (!grouped.has(pointer.group)) {
+        grouped.set(pointer.group, { messages: [], pointers: [] });
+      }
+      const group = grouped.get(pointer.group)!;
+      group.pointers.push(pointer);
+      if (message) {
+        group.messages.push(message);
+      }
+    } else {
+      ungrouped.pointers.push(pointer);
+      if (message) {
+        ungrouped.messages.push(message);
+      }
+    }
+  });
+
+  return { grouped, ungrouped };
+};
+
+export const getNodesAndEdgesFromDagre = ({
+  nodes,
+  edges,
+  defaultFlow,
+}: {
+  nodes: Node[];
+  edges: Edge[];
+  defaultFlow?: DagreGraph;
+}) => {
+  const flow = defaultFlow || createDagreGraph({ ranksep: 300, nodesep: 50 });
+
+  nodes.forEach((node: any) => {
+    flow.setNode(node.id, { width: DEFAULT_NODE_WIDTH, height: DEFAULT_NODE_HEIGHT });
+  });
+
+  edges.forEach((edge: any) => {
+    flow.setEdge(edge.source, edge.target);
+  });
+
+  // Render the diagram in memory getting hte X and Y
+  dagre.layout(flow);
+
+  return {
+    nodes: calculatedNodes(flow, nodes),
+    edges,
+  };
+};
diff --git a/eventcatalog/src/utils/page-loaders/hybrid-page.ts b/packages/core/eventcatalog/src/utils/page-loaders/hybrid-page.ts
similarity index 100%
rename from eventcatalog/src/utils/page-loaders/hybrid-page.ts
rename to packages/core/eventcatalog/src/utils/page-loaders/hybrid-page.ts
diff --git a/packages/core/eventcatalog/src/utils/page-loaders/page-data-loader.ts b/packages/core/eventcatalog/src/utils/page-loaders/page-data-loader.ts
new file mode 100644
index 000000000..f2ffba8b0
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/page-loaders/page-data-loader.ts
@@ -0,0 +1,35 @@
+import type { CollectionTypes, PageTypes } from '@types';
+import { getAgents } from '@utils/collections/agents';
+import { getChannels } from '@utils/collections/channels';
+import { getDomains } from '@utils/collections/domains';
+import { getSystems } from '@utils/collections/systems';
+import { getCommands, getEvents } from '@utils/collections/messages';
+import { getQueries } from '@utils/collections/queries';
+import { getServices } from '@utils/collections/services';
+import { getFlows } from '@utils/collections/flows';
+import { getEntities } from '@utils/collections/entities';
+import { getContainers } from '@utils/collections/containers';
+import { getDiagrams } from '@utils/collections/diagrams';
+import type { CollectionEntry } from 'astro:content';
+import { getDataProducts } from '@utils/collections/data-products';
+import { getAdrs } from '@utils/collections/adrs';
+
+type PageDataLoaderOptions = { getAllVersions?: boolean };
+
+export const pageDataLoader: Record<PageTypes, (options?: PageDataLoaderOptions) => Promise<CollectionEntry<CollectionTypes>[]>> =
+  {
+    agents: getAgents,
+    adrs: getAdrs,
+    events: getEvents,
+    commands: getCommands,
+    queries: getQueries,
+    services: getServices,
+    domains: getDomains,
+    systems: getSystems,
+    channels: getChannels,
+    flows: getFlows,
+    entities: getEntities,
+    containers: getContainers,
+    diagrams: getDiagrams,
+    'data-products': getDataProducts,
+  };
diff --git a/eventcatalog/src/utils/pages.ts b/packages/core/eventcatalog/src/utils/pages.ts
similarity index 100%
rename from eventcatalog/src/utils/pages.ts
rename to packages/core/eventcatalog/src/utils/pages.ts
diff --git a/packages/core/eventcatalog/src/utils/protobuf-schema.ts b/packages/core/eventcatalog/src/utils/protobuf-schema.ts
new file mode 100644
index 000000000..4f3c75eda
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/protobuf-schema.ts
@@ -0,0 +1,476 @@
+/**
+ * Lightweight Protocol Buffers (.proto) parser.
+ *
+ * Parses proto2/proto3 files into a plain JSON tree used by the
+ * ProtobufSchemaViewer component. Runs in both Node (Astro build) and the
+ * browser (Schema Explorer), so it must stay dependency free.
+ *
+ * Captures doc comments (leading `//`, `/* ... *\/` and trailing same-line
+ * comments) so they can be displayed alongside fields, like Avro `doc`.
+ */
+
+export interface ProtobufField {
+  name: string;
+  type: string;
+  number?: number;
+  label?: 'repeated' | 'optional' | 'required';
+  map?: { keyType: string; valueType: string };
+  oneof?: string;
+  doc?: string;
+}
+
+export interface ProtobufEnumValue {
+  name: string;
+  value?: number;
+  doc?: string;
+}
+
+export interface ProtobufEnum {
+  name: string;
+  doc?: string;
+  values: ProtobufEnumValue[];
+}
+
+export interface ProtobufMessage {
+  name: string;
+  doc?: string;
+  fields: ProtobufField[];
+  messages: ProtobufMessage[];
+  enums: ProtobufEnum[];
+}
+
+export interface ProtobufSchema {
+  syntax?: string;
+  package?: string;
+  messages: ProtobufMessage[];
+  enums: ProtobufEnum[];
+}
+
+interface Token {
+  value: string;
+  line: number;
+  doc?: string;
+  isString?: boolean;
+}
+
+const SYMBOLS = new Set(['{', '}', ';', '=', '<', '>', ',', '[', ']', '(', ')', ':']);
+
+const isIdentifierStart = (char: string) => /[A-Za-z_]/.test(char);
+const isIdentifierChar = (char: string) => /[A-Za-z0-9_.]/.test(char);
+const isNumberStart = (char: string) => /[0-9-]/.test(char);
+const isNumberChar = (char: string) => /[0-9a-fA-FxX.+-]/.test(char);
+
+function tokenize(content: string): { tokens: Token[]; trailingComments: Map<number, string> } {
+  const tokens: Token[] = [];
+  const trailingComments = new Map<number, string>();
+  let pendingDoc: string[] = [];
+  let line = 1;
+  let lineHasTokens = false;
+  let i = 0;
+
+  const pushToken = (token: Omit<Token, 'doc'>) => {
+    tokens.push(pendingDoc.length > 0 ? { ...token, doc: pendingDoc.join('\n') } : token);
+    pendingDoc = [];
+    lineHasTokens = true;
+  };
+
+  while (i < content.length) {
+    const char = content[i];
+
+    if (char === '\n') {
+      line++;
+      lineHasTokens = false;
+      i++;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      i++;
+      continue;
+    }
+
+    // Line comment
+    if (char === '/' && content[i + 1] === '/') {
+      let comment = '';
+      i += 2;
+      while (i < content.length && content[i] !== '\n') {
+        comment += content[i];
+        i++;
+      }
+      comment = comment.replace(/^\/*\s?/, '').trim();
+      if (lineHasTokens) {
+        trailingComments.set(line, trailingComments.has(line) ? `${trailingComments.get(line)}\n${comment}` : comment);
+      } else if (comment) {
+        pendingDoc.push(comment);
+      }
+      continue;
+    }
+
+    // Block comment
+    if (char === '/' && content[i + 1] === '*') {
+      let comment = '';
+      i += 2;
+      while (i < content.length && !(content[i] === '*' && content[i + 1] === '/')) {
+        if (content[i] === '\n') line++;
+        comment += content[i];
+        i++;
+      }
+      i += 2;
+      const cleaned = comment
+        .split('\n')
+        .map((commentLine) => commentLine.replace(/^\s*\*?\s?/, '').trim())
+        .filter(Boolean)
+        .join('\n');
+      if (cleaned) pendingDoc.push(cleaned);
+      continue;
+    }
+
+    // String literal
+    if (char === '"' || char === "'") {
+      const quote = char;
+      let value = '';
+      i++;
+      while (i < content.length && content[i] !== quote) {
+        if (content[i] === '\\') {
+          value += content[i + 1];
+          i += 2;
+          continue;
+        }
+        if (content[i] === '\n') line++;
+        value += content[i];
+        i++;
+      }
+      i++;
+      pushToken({ value, line, isString: true });
+      continue;
+    }
+
+    if (SYMBOLS.has(char)) {
+      pushToken({ value: char, line });
+      i++;
+      continue;
+    }
+
+    // Identifiers, including fully-qualified type names with a leading dot
+    // (e.g. ".google.protobuf.Timestamp")
+    if (isIdentifierStart(char) || (char === '.' && isIdentifierStart(content[i + 1] || ''))) {
+      let value = char === '.' ? '.' : '';
+      if (char === '.') i++;
+      while (i < content.length && isIdentifierChar(content[i])) {
+        value += content[i];
+        i++;
+      }
+      pushToken({ value, line });
+      continue;
+    }
+
+    if (isNumberStart(char)) {
+      let value = content[i];
+      i++;
+      while (i < content.length && isNumberChar(content[i])) {
+        value += content[i];
+        i++;
+      }
+      pushToken({ value, line });
+      continue;
+    }
+
+    throw new Error(`Unexpected character "${char}" at line ${line}`);
+  }
+
+  return { tokens, trailingComments };
+}
+
+class ProtobufParser {
+  private tokens: Token[];
+  private trailingComments: Map<number, string>;
+  private pos = 0;
+
+  constructor(content: string) {
+    const { tokens, trailingComments } = tokenize(content);
+    this.tokens = tokens;
+    this.trailingComments = trailingComments;
+  }
+
+  private peek(): Token | undefined {
+    return this.tokens[this.pos];
+  }
+
+  private next(): Token {
+    const token = this.tokens[this.pos];
+    if (!token) throw new Error('Unexpected end of protobuf schema');
+    this.pos++;
+    return token;
+  }
+
+  private expect(value: string): Token {
+    const token = this.next();
+    if (token.value !== value) {
+      throw new Error(`Expected "${value}" but found "${token.value}" at line ${token.line}`);
+    }
+    return token;
+  }
+
+  // Consume tokens until a top-level ";" (skips over nested braces, e.g. aggregate options)
+  private skipStatement() {
+    let depth = 0;
+    while (this.pos < this.tokens.length) {
+      const token = this.next();
+      if (token.value === '{') depth++;
+      if (token.value === '}') depth--;
+      if (token.value === ';' && depth <= 0) return;
+    }
+  }
+
+  private skipBlock() {
+    this.expect('{');
+    let depth = 1;
+    while (this.pos < this.tokens.length && depth > 0) {
+      const token = this.next();
+      if (token.value === '{') depth++;
+      if (token.value === '}') depth--;
+    }
+  }
+
+  // Skip field options like [deprecated = true, (custom) = "value"]
+  private skipFieldOptions() {
+    if (this.peek()?.value !== '[') return;
+    let depth = 0;
+    while (this.pos < this.tokens.length) {
+      const token = this.next();
+      if (token.value === '[') depth++;
+      if (token.value === ']') depth--;
+      if (depth === 0) return;
+    }
+  }
+
+  private getTrailingDoc(line: number): string | undefined {
+    return this.trailingComments.get(line);
+  }
+
+  parse(): ProtobufSchema {
+    const schema: ProtobufSchema = { messages: [], enums: [] };
+
+    while (this.pos < this.tokens.length) {
+      const token = this.peek()!;
+
+      switch (token.value) {
+        case 'syntax':
+        case 'edition': {
+          this.next();
+          this.expect('=');
+          schema.syntax = this.next().value;
+          this.expect(';');
+          break;
+        }
+        case 'package': {
+          this.next();
+          schema.package = this.next().value;
+          this.expect(';');
+          break;
+        }
+        case 'import':
+        case 'option': {
+          this.next();
+          this.skipStatement();
+          break;
+        }
+        case 'message': {
+          schema.messages.push(this.parseMessage());
+          break;
+        }
+        case 'enum': {
+          schema.enums.push(this.parseEnum());
+          break;
+        }
+        case 'service':
+        case 'extend': {
+          this.next();
+          this.next(); // name
+          this.skipBlock();
+          break;
+        }
+        case ';': {
+          this.next();
+          break;
+        }
+        default:
+          throw new Error(`Unexpected token "${token.value}" at line ${token.line}`);
+      }
+    }
+
+    return schema;
+  }
+
+  private parseMessage(): ProtobufMessage {
+    const keyword = this.expect('message');
+    const name = this.next().value;
+    const message: ProtobufMessage = { name, doc: keyword.doc, fields: [], messages: [], enums: [] };
+
+    this.expect('{');
+
+    while (this.pos < this.tokens.length) {
+      const token = this.peek()!;
+
+      if (token.value === '}') {
+        this.next();
+        return message;
+      }
+
+      switch (token.value) {
+        case 'message':
+          message.messages.push(this.parseMessage());
+          break;
+        case 'enum':
+          message.enums.push(this.parseEnum());
+          break;
+        case 'oneof': {
+          this.next();
+          const oneofName = this.next().value;
+          this.expect('{');
+          while (this.peek() && this.peek()!.value !== '}') {
+            if (this.peek()!.value === 'option') {
+              this.next();
+              this.skipStatement();
+              continue;
+            }
+            message.fields.push(this.parseField(oneofName));
+          }
+          this.expect('}');
+          break;
+        }
+        case 'map':
+          message.fields.push(this.parseMapField());
+          break;
+        case 'option':
+        case 'reserved':
+        case 'extensions': {
+          this.next();
+          this.skipStatement();
+          break;
+        }
+        case 'extend': {
+          this.next();
+          this.next(); // type name
+          this.skipBlock();
+          break;
+        }
+        case ';':
+          this.next();
+          break;
+        default:
+          message.fields.push(this.parseField());
+      }
+    }
+
+    throw new Error(`Unexpected end of message "${name}"`);
+  }
+
+  private parseField(oneof?: string): ProtobufField {
+    let firstToken = this.peek()!;
+    let label: ProtobufField['label'];
+
+    if (firstToken.value === 'repeated' || firstToken.value === 'optional' || firstToken.value === 'required') {
+      label = firstToken.value;
+      this.next();
+    }
+
+    if (this.peek()?.value === 'map') {
+      const mapField = this.parseMapField();
+      return { ...mapField, doc: mapField.doc || firstToken.doc, oneof };
+    }
+
+    const typeToken = this.next();
+    const name = this.next().value;
+    this.expect('=');
+    const numberToken = this.next();
+    this.skipFieldOptions();
+    const terminator = this.expect(';');
+
+    const parsedNumber = Number.parseInt(numberToken.value, 10);
+
+    return {
+      name,
+      type: typeToken.value,
+      number: Number.isNaN(parsedNumber) ? undefined : parsedNumber,
+      label,
+      oneof,
+      doc: firstToken.doc || typeToken.doc || this.getTrailingDoc(terminator.line),
+    };
+  }
+
+  private parseMapField(): ProtobufField {
+    const keyword = this.expect('map');
+    this.expect('<');
+    const keyType = this.next().value;
+    this.expect(',');
+    const valueType = this.next().value;
+    this.expect('>');
+    const name = this.next().value;
+    this.expect('=');
+    const numberToken = this.next();
+    this.skipFieldOptions();
+    const terminator = this.expect(';');
+
+    const parsedNumber = Number.parseInt(numberToken.value, 10);
+
+    return {
+      name,
+      type: `map<${keyType}, ${valueType}>`,
+      map: { keyType, valueType },
+      number: Number.isNaN(parsedNumber) ? undefined : parsedNumber,
+      doc: keyword.doc || this.getTrailingDoc(terminator.line),
+    };
+  }
+
+  private parseEnum(): ProtobufEnum {
+    const keyword = this.expect('enum');
+    const name = this.next().value;
+    const protoEnum: ProtobufEnum = { name, doc: keyword.doc, values: [] };
+
+    this.expect('{');
+
+    while (this.pos < this.tokens.length) {
+      const token = this.peek()!;
+
+      if (token.value === '}') {
+        this.next();
+        return protoEnum;
+      }
+
+      if (token.value === 'option' || token.value === 'reserved') {
+        this.next();
+        this.skipStatement();
+        continue;
+      }
+
+      if (token.value === ';') {
+        this.next();
+        continue;
+      }
+
+      const valueToken = this.next();
+      this.expect('=');
+      const numberToken = this.next();
+      this.skipFieldOptions();
+      const terminator = this.expect(';');
+
+      const parsedNumber = Number.parseInt(numberToken.value, 10);
+
+      protoEnum.values.push({
+        name: valueToken.value,
+        value: Number.isNaN(parsedNumber) ? undefined : parsedNumber,
+        doc: valueToken.doc || this.getTrailingDoc(terminator.line),
+      });
+    }
+
+    throw new Error(`Unexpected end of enum "${name}"`);
+  }
+}
+
+export function parseProtobufSchema(content: string): ProtobufSchema {
+  if (!content || content.trim() === '') {
+    throw new Error('Protobuf schema is empty');
+  }
+  return new ProtobufParser(content).parse();
+}
diff --git a/eventcatalog/src/utils/protocols.tsx b/packages/core/eventcatalog/src/utils/protocols.tsx
similarity index 100%
rename from eventcatalog/src/utils/protocols.tsx
rename to packages/core/eventcatalog/src/utils/protocols.tsx
diff --git a/packages/core/eventcatalog/src/utils/remote-file.ts b/packages/core/eventcatalog/src/utils/remote-file.ts
new file mode 100644
index 000000000..7b37980df
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/remote-file.ts
@@ -0,0 +1,15 @@
+export function resolveTemplateVariables(input: unknown): unknown {
+  if (typeof input === 'string') {
+    return input.replace(/\$\{(\w+)\}/g, (_, varName) => {
+      // Vite may statically replace import.meta.env in SSR builds;
+      // process.env keeps runtime env access for dynamic keys.
+      return import.meta.env[varName] || process.env[varName] || '';
+    });
+  }
+
+  if (typeof input === 'object' && input !== null) {
+    return Object.fromEntries(Object.entries(input).map(([key, value]) => [key, resolveTemplateVariables(value)]));
+  }
+
+  return input;
+}
diff --git a/packages/core/eventcatalog/src/utils/remote-spec.ts b/packages/core/eventcatalog/src/utils/remote-spec.ts
new file mode 100644
index 000000000..e319b868c
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/remote-spec.ts
@@ -0,0 +1,45 @@
+export const SAFE_ENV_PREFIXES = ['EVENTCATALOG_', 'EC_'];
+
+const isAllowedEnvVariable = (varName: string, allowAnyEnvInHeaders: boolean): boolean => {
+  if (allowAnyEnvInHeaders) return true;
+  return SAFE_ENV_PREFIXES.some((prefix) => varName.startsWith(prefix));
+};
+
+export const resolveHeaderTemplates = (
+  value: string,
+  {
+    allowAnyEnvInHeaders = false,
+  }: {
+    allowAnyEnvInHeaders?: boolean;
+  } = {}
+): string => {
+  return value.replace(/\$\{(\w+)\}/g, (_, varName) => {
+    if (!isAllowedEnvVariable(varName, allowAnyEnvInHeaders)) {
+      return '';
+    }
+
+    // import.meta.env works in Vite contexts, process.env is the runtime fallback for SSR.
+    return import.meta.env[varName] || process.env[varName] || '';
+  });
+};
+
+export const resolveHeaders = (
+  headers: Record<string, string>,
+  {
+    allowAnyEnvInHeaders = false,
+  }: {
+    allowAnyEnvInHeaders?: boolean;
+  } = {}
+): Record<string, string> => {
+  return Object.fromEntries(
+    Object.entries(headers).map(([key, value]) => [key, resolveHeaderTemplates(String(value), { allowAnyEnvInHeaders })])
+  );
+};
+
+export const isSameOrigin = (sourceUrl: string, targetUrl: string): boolean => {
+  try {
+    return new URL(sourceUrl).origin === new URL(targetUrl).origin;
+  } catch {
+    return false;
+  }
+};
diff --git a/packages/core/eventcatalog/src/utils/resource-files.ts b/packages/core/eventcatalog/src/utils/resource-files.ts
new file mode 100644
index 000000000..2f29bc6dd
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/resource-files.ts
@@ -0,0 +1,86 @@
+import fs from 'fs';
+import path from 'path';
+import { isSSR } from '@utils/feature';
+
+/**
+ * Get the absolute base path for a resource item.
+ *
+ * In SSR mode, filePath is relative to the Astro core directory (e.g., "../examples/default/domains/...").
+ * We need to resolve it using PROJECT_DIR to get the correct absolute path.
+ *
+ * In static mode, filePath is resolved correctly by Astro's build context.
+ *
+ * @param item - The resource item with a filePath property
+ * @returns The absolute path to the directory containing the resource
+ */
+export function getResourceBasePath(item: { filePath?: string }): string {
+  if (!item.filePath) {
+    return '';
+  }
+
+  const filePath = item.filePath;
+
+  // In SSR mode, we need to resolve the relative path using PROJECT_DIR
+  if (isSSR()) {
+    const PROJECT_DIR = process.env.PROJECT_DIR || '';
+
+    if (PROJECT_DIR) {
+      // Get the project folder name from PROJECT_DIR (e.g., "default" from ".../examples/default")
+      const projectFolderName = path.basename(PROJECT_DIR);
+
+      // Find the project folder in the relative path and extract everything after it
+      // Pattern: ../examples/default/domains/... -> domains/...
+      const regex = new RegExp(`.*?${projectFolderName}/(.+)$`);
+      const match = filePath.match(regex);
+
+      if (match && match[1]) {
+        // Join PROJECT_DIR with the relative path within the project
+        return path.join(PROJECT_DIR, path.dirname(match[1]));
+      }
+    }
+  }
+
+  // Static mode: resolve directly using Astro's build context
+  return path.dirname(path.resolve(filePath));
+}
+
+/**
+ * Get the absolute path to a file within a resource directory.
+ *
+ * @param item - The resource item with a filePath property
+ * @param relativePath - The relative path to the file (e.g., "schema.json")
+ * @returns The absolute path to the file
+ */
+export function getResourceFilePath(item: { filePath?: string }, relativePath: string): string {
+  const basePath = getResourceBasePath(item);
+  return path.join(basePath, relativePath);
+}
+
+/**
+ * Check if a file exists within a resource directory.
+ *
+ * @param item - The resource item with a filePath property
+ * @param relativePath - The relative path to the file (e.g., "schema.json")
+ * @returns True if the file exists, false otherwise
+ */
+export function resourceFileExists(item: { filePath?: string }, relativePath: string): boolean {
+  const filePath = getResourceFilePath(item, relativePath);
+  return fs.existsSync(filePath);
+}
+
+/**
+ * Read a file from a resource directory.
+ *
+ * @param item - The resource item with a filePath property
+ * @param relativePath - The relative path to the file (e.g., "schema.json")
+ * @returns The file content as a string, or null if the file doesn't exist
+ */
+export function readResourceFile(item: { filePath?: string }, relativePath: string): string | null {
+  const filePath = getResourceFilePath(item, relativePath);
+
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  return fs.readFileSync(filePath, 'utf-8');
+}
diff --git a/packages/core/eventcatalog/src/utils/resource-reference-colors.ts b/packages/core/eventcatalog/src/utils/resource-reference-colors.ts
new file mode 100644
index 000000000..113eeb2a2
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/resource-reference-colors.ts
@@ -0,0 +1,50 @@
+import { getColorForCollection, tailwind500RgbByColor, type CollectionColor } from './collection-colors';
+import { resourceToCollectionMap } from './collections/util';
+
+export type ResourceReferenceType =
+  | 'agent'
+  | 'entity'
+  | 'service'
+  | 'event'
+  | 'command'
+  | 'query'
+  | 'domain'
+  | 'flow'
+  | 'channel'
+  | 'diagram'
+  | 'container'
+  | 'user'
+  | 'team'
+  | 'doc'
+  | 'data-product';
+
+const resourceTypeToCollection = {
+  ...resourceToCollectionMap,
+  doc: 'customPages',
+} as Record<ResourceReferenceType, string>;
+
+export const getResourceReferenceColorName = (type: string): CollectionColor => {
+  const collection = resourceTypeToCollection[type as ResourceReferenceType] || '';
+  return getColorForCollection(collection);
+};
+
+export const getResourceReferenceStyle = (type: string): string => {
+  if (type === 'doc') {
+    return [
+      '--ec-resource-ref-bg: rgb(var(--ec-accent) / 0.12)',
+      '--ec-resource-ref-color: rgb(var(--ec-accent))',
+      'color: var(--ec-resource-ref-color)',
+      'text-decoration-color: var(--ec-resource-ref-color)',
+    ].join('; ');
+  }
+
+  const color = getResourceReferenceColorName(type);
+  const rgb = tailwind500RgbByColor[color];
+
+  return [
+    `--ec-resource-ref-bg: rgb(${rgb} / 0.12)`,
+    `--ec-resource-ref-color: rgb(${rgb})`,
+    'color: var(--ec-resource-ref-color)',
+    'text-decoration-color: var(--ec-resource-ref-color)',
+  ].join('; ');
+};
diff --git a/packages/core/eventcatalog/src/utils/schema-utils.ts b/packages/core/eventcatalog/src/utils/schema-utils.ts
new file mode 100644
index 000000000..79f38122b
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/schema-utils.ts
@@ -0,0 +1,77 @@
+export interface SchemaProperty {
+  name: string;
+  type: string;
+  description: string;
+  required: boolean;
+}
+
+function getAvroTypeName(type: any): string {
+  if (typeof type === 'string') return type;
+  if (Array.isArray(type)) {
+    return type.map((t) => (typeof t === 'string' ? t : t.type || 'complex')).join(' | ');
+  }
+  if (typeof type === 'object' && type !== null) {
+    if (type.type === 'array' && type.items) {
+      return `array<${getAvroTypeName(type.items)}>`;
+    }
+    return type.type || 'complex';
+  }
+  return 'unknown';
+}
+
+function parseProtoFields(content: string): SchemaProperty[] {
+  const properties: SchemaProperty[] = [];
+  // Match lines like: string field_name = 1; // optional comment
+  // or: repeated string field_name = 2;
+  const fieldRegex = /^\s*(repeated\s+|optional\s+|required\s+)?(\w+)\s+(\w+)\s*=\s*\d+\s*;(?:\s*\/\/\s*(.*))?/gm;
+  let match;
+  while ((match = fieldRegex.exec(content)) !== null) {
+    const modifier = (match[1] || '').trim();
+    const type = modifier ? `${modifier} ${match[2]}` : match[2];
+    properties.push({
+      name: match[3],
+      type,
+      description: match[4]?.trim() || '',
+      required: false,
+    });
+  }
+  return properties;
+}
+
+export function extractSchemaProperties(content: string, format: string): SchemaProperty[] {
+  if (!content) return [];
+
+  if (format === 'proto') {
+    return parseProtoFields(content);
+  }
+
+  // JSON Schema and Avro are both JSON-based
+  try {
+    const schema = JSON.parse(content);
+
+    // Avro: has top-level "fields" array
+    if (schema.fields && Array.isArray(schema.fields)) {
+      return schema.fields.map((field: any) => ({
+        name: field.name,
+        type: getAvroTypeName(field.type),
+        description: field.doc || '',
+        required: !Array.isArray(field.type) || !field.type.includes('null'),
+      }));
+    }
+
+    // JSON Schema: has "properties" object
+    if (schema.properties) {
+      const required = schema.required || [];
+      return Object.entries(schema.properties).map(([name, prop]: [string, any]) => ({
+        name,
+        type: prop.type || (prop.enum ? 'enum' : prop.$ref ? '$ref' : 'object'),
+        description: prop.description || '',
+        required: required.includes(name),
+      }));
+    }
+  } catch {
+    // Failed to parse, return empty
+  }
+
+  return [];
+}
diff --git a/packages/core/eventcatalog/src/utils/url-builder.ts b/packages/core/eventcatalog/src/utils/url-builder.ts
new file mode 100644
index 000000000..f94f2422a
--- /dev/null
+++ b/packages/core/eventcatalog/src/utils/url-builder.ts
@@ -0,0 +1,66 @@
+// Don't import config here, as it breaks in the client, as path cannot be resolved.
+
+const cleanUrl = (url: string) => {
+  return url.replace(/\/+/g, '/');
+};
+
+// Custom URL builder as Astro does not support this stuff out the box
+export const buildUrl = (url: string, ignoreTrailingSlash = false, urlAlreadyIncludesBaseUrl = false) => {
+  // Should a trailingSlash be added to urls?
+  // typeof guard protects against the rare case where Vite's `define` substitution
+  // didn't run (stale dev cache, edge SSR paths) — leaking the identifier to runtime would crash callers.
+  const trailingSlash = typeof __EC_TRAILING_SLASH__ !== 'undefined' ? __EC_TRAILING_SLASH__ : false;
+
+  let newUrl = url;
+
+  // If the base URL is not the root, we need to append it
+  if (import.meta.env.BASE_URL !== '/' && !urlAlreadyIncludesBaseUrl) {
+    newUrl = `${import.meta.env.BASE_URL}${url}`;
+  }
+
+  // Should we add a trailing slash to the url?
+  if (trailingSlash && !ignoreTrailingSlash) {
+    if (url.endsWith('/')) return newUrl;
+    return cleanUrl(`${newUrl}/`);
+  }
+
+  return cleanUrl(newUrl);
+};
+
+// Helper function to build URLs with query parameters
+export const buildUrlWithParams = (baseUrl: string, params: Record<string, string | undefined>) => {
+  // Filter out undefined values and empty strings
+  const validParams = Object.entries(params)
+    .filter(([_, value]) => value !== undefined && value !== '')
+    .reduce<Record<string, string>>((acc, [key, value]) => ({ ...acc, [key]: value as string }), {});
+
+  // If no valid params, just return the base URL
+  if (Object.keys(validParams).length === 0) {
+    return buildUrl(baseUrl);
+  }
+
+  // Build query string with encoded values
+  const queryString = Object.entries(validParams)
+    .map(([key, value]) => `${key}=${value}`)
+    .join('&');
+
+  return `${buildUrl(baseUrl)}?${queryString}`;
+};
+
+export const buildEditUrlForResource = (editUrl: string, filePath: string) => {
+  // filepath may have ../ or ./ in it, so we need to remove it
+  const cleanFilePath = filePath.replace(/^\.\.?\//g, '');
+  return `${editUrl}/${cleanFilePath}`;
+};
+
+// Takes a given url and returns the .mdx url
+export const toMarkdownUrl = (url: string) => {
+  const trailingSlash = typeof __EC_TRAILING_SLASH__ !== 'undefined' ? __EC_TRAILING_SLASH__ : false;
+
+  if (trailingSlash) {
+    const urlWithoutTrailingSlash = url.replace(/\/$/, '');
+    return urlWithoutTrailingSlash + '.mdx/';
+  }
+
+  return url + '.mdx';
+};
diff --git a/packages/core/eventcatalog/tsconfig.json b/packages/core/eventcatalog/tsconfig.json
new file mode 100644
index 000000000..09949c440
--- /dev/null
+++ b/packages/core/eventcatalog/tsconfig.json
@@ -0,0 +1,30 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "strict": true,
+    "baseUrl": ".",
+    "paths": {
+      "@config": ["./eventcatalog.config.js"],
+      "@eventcatalog": ["src/utils/eventcatalog-config/catalog.ts"],
+      "@icons/*": ["src/icons/*"],
+      "@components/*": ["src/components/*"],
+      "@catalog/components/*": ["src/custom-defined-components/*"],
+      "@catalog/layouts/*": ["src/toolkit/layouts/*"],
+      "@catalog/utils": ["src/toolkit/utils/index.ts"],
+      "@catalog/utils/*": ["src/toolkit/utils/*"],
+      "@catalog/snippets/*": ["src/snippets/*"],
+      "@types": ["src/types/index.ts"],
+      "@utils/*": ["src/utils/*"],
+      "@layouts/*": ["src/layouts/*"],
+      "@enterprise/*": ["src/enterprise/*"],
+      "@ai/*": ["src/generated-ai/*"],
+      "auth:config": ["./auth.config.ts"],
+      "@stores/*": ["src/stores/*"]
+    },
+    "jsx": "react-jsx",
+    "jsxImportSource": "react",
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*", "*.config.*"],
+  "exclude": ["src/custom-pages"]
+}
diff --git a/packages/core/package.json b/packages/core/package.json
new file mode 100644
index 000000000..dc24f19ce
--- /dev/null
+++ b/packages/core/package.json
@@ -0,0 +1,173 @@
+{
+  "name": "@eventcatalog/core",
+  "homepage": "https://github.com/event-catalog/eventcatalog",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/event-catalog/eventcatalog.git"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "version": "4.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "eventcatalog": "bin/eventcatalog.js"
+  },
+  "typesVersions": {
+    "*": {
+      "bin/eventcatalog.config": [
+        "bin/eventcatalog.config.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "eventcatalog/",
+    "!eventcatalog/.astro/",
+    "!eventcatalog/dist/",
+    "!eventcatalog/node_modules/",
+    "!eventcatalog/**/__tests__/",
+    "bin/",
+    "dist/"
+  ],
+  "scripts": {
+    "dev": "astro dev",
+    "build:bin": "tsup && node scripts/copy-docs-to-dist.mjs",
+    "prepublishOnly": "pnpm run build:bin",
+    "test": "cross-env DISABLE_EVENTCATALOG_CACHE=true vitest",
+    "test:ci": "node scripts/ci/test.js",
+    "start": "astro dev",
+    "build": "astro build",
+    "build:cd": "node scripts/build-ci.js",
+    "preview": "astro preview",
+    "astro": "astro",
+    "start:catalog": "node scripts/start-catalog-locally.js",
+    "export:catalog": "node scripts/export-catalog-locally.js",
+    "start:catalog:server": "node scripts/start-server-locally.js",
+    "preview:catalog": "node scripts/preview-catalog-locally.js",
+    "generate:catalog": "node scripts/generate-catalog-locally.js",
+    "verify-build:catalog": "rimraf dist && pnpm run build:cd",
+    "generate": "pnpm run build:bin && npx . generate",
+    "format": "prettier --config .prettierrc --write \"**/*.{js,jsx,ts,tsx,json,astro}\"",
+    "format:diff": "prettier --config .prettierrc --list-different \"**/*.{js,jsx,ts,tsx,json,astro}\"",
+    "lint:catalog": "pnpm dlx @eventcatalog/linter examples/default",
+    "check": "node scripts/check-types.js",
+    "turbo:test": "turbo run test",
+    "turbo:build": "turbo run build:bin"
+  },
+  "dependencies": {
+    "@ai-sdk/react": "^3.0.17",
+    "@astrojs/markdown-remark": "^7.2.0",
+    "@astrojs/mdx": "^7.0.0",
+    "@astrojs/node": "^11.0.0",
+    "@astrojs/react": "^6.0.0",
+    "@astrojs/rss": "^4.0.18",
+    "@asyncapi/avro-schema-parser": "3.0.24",
+    "@asyncapi/parser": "^3.6.0",
+    "@asyncapi/react-component": "3.1.0",
+    "@auth/core": "^0.37.4",
+    "@eventcatalog/license": "^0.0.7",
+    "@eventcatalog/linter": "workspace:*",
+    "@eventcatalog/sdk": "workspace:*",
+    "@eventcatalog/visualiser": "workspace:^",
+    "@fontsource/inter": "^5.2.5",
+    "@headlessui/react": "^2.0.3",
+    "@heroicons/react": "^2.1.3",
+    "@iconify-json/logos": "^1.2.4",
+    "@mermaid-js/layout-elk": "^0.2.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@nanostores/react": "^1.0.0",
+    "@parcel/watcher": "^2.4.1",
+    "@radix-ui/react-context-menu": "^2.2.6",
+    "@radix-ui/react-dialog": "^1.1.6",
+    "@radix-ui/react-dropdown-menu": "^2.1.12",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-tooltip": "^1.1.8",
+    "@scalar/api-reference-react": "^0.9.36",
+    "@tailwindcss/typography": "^0.5.16",
+    "@tailwindcss/vite": "^4.3.1",
+    "@tanstack/react-table": "^8.17.3",
+    "@xyflow/react": "^12.3.6",
+    "ai": "^6.0.17",
+    "astro": "^7.0.3",
+    "astro-compress": "^2.4.0",
+    "astro-expressive-code": "^0.44.0",
+    "astro-seo": "^0.8.4",
+    "auth-astro": "^4.2.0",
+    "boxen": "^8.0.1",
+    "commander": "^12.1.0",
+    "cross-env": "^7.0.3",
+    "dagre": "^0.8.5",
+    "diff": "^8.0.3",
+    "diff2html": "^3.4.56",
+    "dotenv": "^16.5.0",
+    "elkjs": "^0.10.0",
+    "glob": "^13.0.6",
+    "gray-matter": "^4.0.3",
+    "hono": "4.12.25",
+    "html-to-image": "^1.11.11",
+    "js-yaml": "^4.2.0",
+    "jsonpath-plus": "^10.4.0",
+    "jsonwebtoken": "^9.0.2",
+    "lodash.debounce": "^4.0.8",
+    "lodash.merge": "4.6.2",
+    "lucide-react": "^0.453.0",
+    "marked": "^15.0.6",
+    "mdast-util-find-and-replace": "^3.0.2",
+    "mermaid": "^11.12.3",
+    "minisearch": "^7.2.0",
+    "nanostores": "^1.1.0",
+    "pagefind": "^1.5.2",
+    "pako": "^2.1.0",
+    "picocolors": "^1.1.1",
+    "picomatch": "^4.0.4",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-markdown": "^10.1.0",
+    "react-syntax-highlighter": "^15.6.6",
+    "recast": "^0.23.11",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-expressive-code": "^0.44.0",
+    "rehype-slug": "^6.0.0",
+    "remark-comment": "^1.0.0",
+    "remark-directive": "^3.0.0",
+    "remark-gfm": "^4.0.1",
+    "rimraf": "^6.1.3",
+    "semver": "7.6.3",
+    "shelljs": "^0.9.0",
+    "sonner": "^2.0.7",
+    "sql.js": "^1.12.0",
+    "svg-pan-zoom": "^3.6.2",
+    "tailwindcss": "^4.3.1",
+    "typescript": "^5.4.5",
+    "unist-util-visit": "^5.0.0",
+    "update-notifier": "^7.3.1",
+    "uuid": "^10.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.9",
+    "@types/dagre": "^0.7.52",
+    "@types/diff": "^5.2.2",
+    "@types/js-yaml": "^4.0.9",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/lodash.debounce": "^4.0.9",
+    "@types/lodash.merge": "4.6.9",
+    "@types/node": "^22.12.0",
+    "@types/pako": "^2.0.3",
+    "@types/react": "^19.2.13",
+    "@types/react-dom": "^19.2.3",
+    "@types/react-syntax-highlighter": "^15.5.13",
+    "@types/semver": "^7.5.8",
+    "@types/shelljs": "^0.8.15",
+    "@types/update-notifier": "^6.0.8",
+    "@types/uuid": "^10.0.0",
+    "prettier": "^3.3.3",
+    "prettier-plugin-astro": "^0.14.1",
+    "tsup": "^8.1.0",
+    "vite": "^8.1.0",
+    "vite-tsconfig-paths": "^4.3.2",
+    "vitest": "^4.0.18"
+  },
+  "packageManager": "pnpm@10.23.0+sha512.21c4e5698002ade97e4efe8b8b4a89a8de3c85a37919f957e7a0f30f38fbc5bbdd05980ffe29179b2fb6e6e691242e098d945d1601772cad0fef5fb6411e2a4b"
+}
diff --git a/playwright.config.ts b/packages/core/playwright.config.ts
similarity index 100%
rename from playwright.config.ts
rename to packages/core/playwright.config.ts
diff --git a/packages/core/scripts/build-ci.js b/packages/core/scripts/build-ci.js
new file mode 100644
index 000000000..38af01597
--- /dev/null
+++ b/packages/core/scripts/build-ci.js
@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+// This is used for CI on vercel. Must copy files before building.
+import { join } from 'node:path';
+import { execFileSync, execSync, spawn } from 'node:child_process';
+const __dirname = import.meta.dirname;
+
+const args = process.argv.slice(2);
+const catalog = args[0] || 'default';
+
+const catalogDir = join(__dirname, '../eventcatalog/');
+const projectDIR = join(__dirname, `../../../examples/${catalog}`);
+const cliEntryPoint = join(__dirname, '../bin/eventcatalog.js');
+
+const shouldFilterAstroLine = (line) => {
+  return line.includes('[glob-loader]') || /The collection.*does not exist/.test(line);
+};
+
+const runWithFilteredOutput = async ({ command, cwd, env }) => {
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      cwd,
+      env: {
+        ...process.env,
+        ...env,
+      },
+      shell: true,
+      stdio: ['inherit', 'pipe', 'pipe'],
+    });
+
+    let stdoutBuffer = '';
+    let stderrBuffer = '';
+
+    const flush = (buffer, writer, isFinal = false) => {
+      const lines = buffer.split('\n');
+      const remaining = isFinal ? '' : (lines.pop() ?? '');
+
+      for (const rawLine of lines) {
+        const line = rawLine.replace(/\r/g, '');
+        if (line.length === 0) {
+          writer.write('\n');
+          continue;
+        }
+        if (!shouldFilterAstroLine(line)) {
+          writer.write(`${rawLine}\n`);
+        }
+      }
+
+      return remaining;
+    };
+
+    child.stdout.on('data', (chunk) => {
+      stdoutBuffer += chunk.toString();
+      stdoutBuffer = flush(stdoutBuffer, process.stdout);
+    });
+
+    child.stderr.on('data', (chunk) => {
+      stderrBuffer += chunk.toString();
+      stderrBuffer = flush(stderrBuffer, process.stderr);
+    });
+
+    child.on('error', (error) => reject(error));
+    child.on('close', (code) => {
+      flush(stdoutBuffer, process.stdout, true);
+      flush(stderrBuffer, process.stderr, true);
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`Command failed with exit code ${code}: ${command}`));
+    });
+  });
+};
+
+const run = async () => {
+  // Build cli (workspace deps already built by turbo before this script runs)
+  execSync('pnpm run build:bin', { stdio: 'inherit' });
+
+  const runCatalogCli = (command, env = {}) => {
+    execFileSync(process.execPath, [cliEntryPoint, command], {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        NODE_ENV: 'CI',
+        PROJECT_DIR: projectDIR,
+        CATALOG_DIR: catalogDir,
+        ...env,
+      },
+    });
+  };
+
+  // Run the generator
+  runCatalogCli('generate');
+
+  // Build catalog
+  runCatalogCli('build', {
+    IGNORE_BUILD_ARTIFACTS: 'true',
+  });
+
+  // Type check
+  await runWithFilteredOutput({
+    command: `pnpm exec astro check --minimumSeverity error --root ${catalogDir}`,
+    cwd: process.cwd(),
+    env: {
+      PATH: process.env.PATH,
+      CATALOG_DIR: catalogDir,
+      PROJECT_DIR: projectDIR,
+      IGNORE_BUILD_ARTIFACTS: 'true',
+      NODE_OPTIONS: '--max-old-space-size=8192',
+    },
+  });
+};
+
+run().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
diff --git a/packages/core/scripts/check-build-size.js b/packages/core/scripts/check-build-size.js
new file mode 100644
index 000000000..a45c6bb4a
--- /dev/null
+++ b/packages/core/scripts/check-build-size.js
@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const __dirname = import.meta.dirname;
+
+/**
+ * Recursively calculate the total size of a directory in bytes
+ */
+function getDirSizeBytes(dirPath) {
+  let totalSize = 0;
+
+  if (!fs.existsSync(dirPath)) {
+    return 0;
+  }
+
+  const items = fs.readdirSync(dirPath);
+
+  for (const item of items) {
+    const itemPath = path.join(dirPath, item);
+    const stats = fs.statSync(itemPath);
+
+    if (stats.isDirectory()) {
+      totalSize += getDirSizeBytes(itemPath);
+    } else {
+      totalSize += stats.size;
+    }
+  }
+
+  return totalSize;
+}
+
+/**
+ * Get directory size in KB
+ */
+function getDirSizeKB(dirPath) {
+  return Math.round(getDirSizeBytes(dirPath) / 1024);
+}
+
+/**
+ * Format size with appropriate units
+ */
+function formatSize(kb) {
+  if (kb >= 1024) {
+    return `${(kb / 1024).toFixed(2)} MB`;
+  }
+  return `${kb} KB`;
+}
+
+/**
+ * Main size check
+ */
+function main() {
+  const args = process.argv.slice(2);
+  const catalog = args[0] || 'default';
+
+  const distPath = path.join(__dirname, `../../../examples/${catalog}/dist`);
+  const baselinePath = path.join(__dirname, '../.size-baseline.json');
+
+  // Check if dist exists
+  if (!fs.existsSync(distPath)) {
+    console.error(`❌ Build output not found at: ${distPath}`);
+    console.error('   Run the build first: pnpm run verify-build:catalog');
+    process.exit(1);
+  }
+
+  // Check if baseline exists
+  if (!fs.existsSync(baselinePath)) {
+    console.error(`❌ Baseline file not found at: ${baselinePath}`);
+    console.error('   Run: node scripts/update-size-baseline.js');
+    process.exit(1);
+  }
+
+  // Read baseline
+  const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf-8'));
+  const baselineSize = baseline.dist.size;
+
+  // Calculate current size
+  const currentSize = getDirSizeKB(distPath);
+
+  // Get threshold from env or default to 5%
+  const threshold = parseFloat(process.env.SIZE_THRESHOLD) || 5;
+  const maxAllowed = Math.round(baselineSize * (1 + threshold / 100));
+
+  // Calculate delta
+  const delta = currentSize - baselineSize;
+  const deltaPercent = ((delta / baselineSize) * 100).toFixed(2);
+  const deltaSign = delta >= 0 ? '+' : '';
+
+  // Output report
+  console.log('\n📦 Build Size Report\n');
+  console.log(`   Baseline:     ${formatSize(baselineSize)}`);
+  console.log(`   Current:      ${formatSize(currentSize)}`);
+  console.log(`   Delta:        ${deltaSign}${formatSize(Math.abs(delta))} (${deltaSign}${deltaPercent}%)`);
+  console.log(`   Threshold:    ${threshold}% (max ${formatSize(maxAllowed)})`);
+  console.log('');
+
+  // Check if over budget
+  if (currentSize > maxAllowed) {
+    console.error(`❌ Build size exceeds budget by ${formatSize(currentSize - maxAllowed)}`);
+    console.error(`   To update baseline: node scripts/update-size-baseline.js`);
+    process.exit(1);
+  }
+
+  console.log('✅ Build size within budget\n');
+  process.exit(0);
+}
+
+main();
diff --git a/packages/core/scripts/check-types.js b/packages/core/scripts/check-types.js
new file mode 100644
index 000000000..a6ccd1dcb
--- /dev/null
+++ b/packages/core/scripts/check-types.js
@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+// Run astro check with proper catalog directory setup
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+const __dirname = import.meta.dirname;
+
+const args = process.argv.slice(2);
+const catalog = args[0] || 'default';
+
+const catalogDir = join(__dirname, '../eventcatalog/');
+const projectDIR = join(__dirname, `../../../examples/${catalog}`);
+
+const shouldFilterAstroLine = (line) => {
+  return line.includes('[glob-loader]') || /The collection.*does not exist/.test(line);
+};
+
+const runWithFilteredOutput = async ({ command, cwd, env }) => {
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      cwd,
+      env: {
+        ...process.env,
+        ...env,
+      },
+      shell: true,
+      stdio: ['inherit', 'pipe', 'pipe'],
+    });
+
+    let stdoutBuffer = '';
+    let stderrBuffer = '';
+
+    const flush = (buffer, writer, isFinal = false) => {
+      const lines = buffer.split('\n');
+      const remaining = isFinal ? '' : (lines.pop() ?? '');
+
+      for (const rawLine of lines) {
+        const line = rawLine.replace(/\r/g, '');
+        if (line.length === 0) {
+          writer.write('\n');
+          continue;
+        }
+        if (!shouldFilterAstroLine(line)) {
+          writer.write(`${rawLine}\n`);
+        }
+      }
+
+      return remaining;
+    };
+
+    child.stdout.on('data', (chunk) => {
+      stdoutBuffer += chunk.toString();
+      stdoutBuffer = flush(stdoutBuffer, process.stdout);
+    });
+
+    child.stderr.on('data', (chunk) => {
+      stderrBuffer += chunk.toString();
+      stderrBuffer = flush(stderrBuffer, process.stderr);
+    });
+
+    child.on('error', (error) => reject(error));
+    child.on('close', (code) => {
+      flush(stdoutBuffer, process.stdout, true);
+      flush(stderrBuffer, process.stderr, true);
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`Command failed with exit code ${code}: ${command}`));
+    });
+  });
+};
+
+await runWithFilteredOutput({
+  command: `pnpm exec astro check --minimumSeverity error  --root ${catalogDir}`,
+  cwd: process.cwd(),
+  env: {
+    PATH: process.env.PATH,
+    CATALOG_DIR: catalogDir,
+    PROJECT_DIR: projectDIR,
+    NODE_OPTIONS: '--max-old-space-size=8192',
+  },
+});
diff --git a/packages/core/scripts/ci/test.js b/packages/core/scripts/ci/test.js
new file mode 100644
index 000000000..3823e42f9
--- /dev/null
+++ b/packages/core/scripts/ci/test.js
@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+/**
+ * Script for GitHub Actions
+ * Sets up the project with required files
+ */
+
+import { join } from 'node:path';
+import fs from 'fs';
+import { execSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const catalog = args[0] || 'default';
+
+// When run from CI, cwd could be repo root or packages/core
+// Use __dirname to compute paths relative to this script's location
+// Script is at: packages/core/scripts/ci/test.js
+// Repo root is: ../../../../ (up 4 levels)
+const __dirname = import.meta.dirname;
+const repoRoot = join(__dirname, '../../../..');
+const catalogDir = join(repoRoot, 'packages/core/eventcatalog/');
+const projectDIR = join(repoRoot, `examples/${catalog}`);
+
+fs.copyFileSync(join(projectDIR, 'eventcatalog.config.js'), join(catalogDir, 'eventcatalog.config.js'));
+fs.copyFileSync(join(projectDIR, 'eventcatalog.styles.css'), join(catalogDir, 'eventcatalog.styles.css'));
+
+execSync(`cross-env NODE_ENV=test PROJECT_DIR=${projectDIR} CATALOG_DIR=${catalogDir} pnpm run test run`, {
+  stdio: 'inherit',
+});
diff --git a/packages/core/scripts/copy-docs-to-dist.mjs b/packages/core/scripts/copy-docs-to-dist.mjs
new file mode 100755
index 000000000..ca3af37eb
--- /dev/null
+++ b/packages/core/scripts/copy-docs-to-dist.mjs
@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const sourceDir = path.join(packageRoot, 'docs');
+const destinationDir = path.join(packageRoot, 'dist', 'docs');
+
+const pathExists = async (target) => {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+if (!(await pathExists(sourceDir))) {
+  console.warn(`Skipping docs package copy. Source directory not found: ${sourceDir}`);
+  process.exit(0);
+}
+
+await fs.rm(destinationDir, { recursive: true, force: true });
+await fs.mkdir(path.dirname(destinationDir), { recursive: true });
+await fs.cp(sourceDir, destinationDir, { recursive: true });
+
+console.log(`Copied bundled docs to ${destinationDir}`);
diff --git a/packages/core/scripts/export-catalog-locally.js b/packages/core/scripts/export-catalog-locally.js
new file mode 100644
index 000000000..63a49c914
--- /dev/null
+++ b/packages/core/scripts/export-catalog-locally.js
@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+async function main() {
+  const __dirname = import.meta.dirname;
+
+  const args = process.argv.slice(2);
+  const catalog = args[0] || 'default';
+
+  const projectDIR = join(__dirname, `../../../examples/${catalog}`);
+
+  execSync('pnpm run build:bin', { stdio: 'inherit' });
+
+  execSync(`cross-env PROJECT_DIR=${projectDIR} npx . export`, {
+    stdio: 'inherit',
+  });
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
diff --git a/scripts/generate-catalog-locally.js b/packages/core/scripts/generate-catalog-locally.js
similarity index 89%
rename from scripts/generate-catalog-locally.js
rename to packages/core/scripts/generate-catalog-locally.js
index b6b5342e5..357b7240e 100644
--- a/scripts/generate-catalog-locally.js
+++ b/packages/core/scripts/generate-catalog-locally.js
@@ -9,7 +9,7 @@ async function main() {
   const catalog = args[0] || 'default';
 
   const catalogDir = join(__dirname, '../eventcatalog/');
-  const projectDIR = join(__dirname, `../examples/${catalog}`);
+  const projectDIR = join(__dirname, `../../../examples/${catalog}`);
 
   execSync('pnpm run build:bin', { stdio: 'inherit' });
 
diff --git a/packages/core/scripts/notify-discord-release.js b/packages/core/scripts/notify-discord-release.js
new file mode 100644
index 000000000..6823012fa
--- /dev/null
+++ b/packages/core/scripts/notify-discord-release.js
@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+
+/**
+ * Discord Release Notification Script
+ *
+ * Sends a nicely formatted release notification to Discord webhook.
+ * Parses changeset release notes and creates an embedded message.
+ *
+ * Environment variables required:
+ * - DISCORD_WEBHOOK_URL: The Discord webhook URL
+ * - RELEASE_TAG: The release tag (e.g., "@eventcatalog/core@3.2.0")
+ * - RELEASE_BODY: The release notes body (markdown)
+ * - RELEASE_URL: The GitHub release URL
+ */
+
+// Constants
+const EVENTCATALOG_AVATAR_URL = 'https://avatars.githubusercontent.com/u/171661582?s=96&v=4';
+
+// Environment variables
+const DISCORD_WEBHOOK_URL = process.env.DISCORD_WEBHOOK_URL;
+const RELEASE_TAG = process.env.RELEASE_TAG || 'Unknown';
+const RELEASE_BODY = process.env.RELEASE_BODY || 'No release notes provided.';
+const RELEASE_URL = process.env.RELEASE_URL || 'https://github.com/event-catalog/eventcatalog/releases';
+
+if (!DISCORD_WEBHOOK_URL) {
+  console.error('Error: DISCORD_WEBHOOK_URL environment variable is required');
+  process.exit(1);
+}
+
+/**
+ * Parse the release body and extract changes by category
+ */
+function parseReleaseNotes(body) {
+  const sections = {
+    features: [],
+    fixes: [],
+    other: [],
+  };
+
+  // Parse only the first top-level release block when multiple versions are present.
+  // This avoids posting historical notes if the body contains several changelog entries.
+  const hasTopLevelVersionHeadings = /^##\s+/m.test(body);
+  const lines = body.split('\n');
+  let currentSection = 'other';
+  let inFirstReleaseBlock = !hasTopLevelVersionHeadings;
+  let seenFirstTopLevelHeading = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (hasTopLevelVersionHeadings && /^##\s+/.test(trimmed)) {
+      if (!seenFirstTopLevelHeading) {
+        seenFirstTopLevelHeading = true;
+        inFirstReleaseBlock = true;
+        continue;
+      }
+      break;
+    }
+
+    if (!inFirstReleaseBlock) continue;
+
+    // Check for section headers (### Minor Changes, ### Patch Changes, etc.)
+    if (trimmed.startsWith('###')) {
+      const lowerLine = trimmed.toLowerCase();
+      if (lowerLine.includes('minor') || lowerLine.includes('feature')) {
+        currentSection = 'features';
+      } else if (lowerLine.includes('patch') || lowerLine.includes('fix')) {
+        currentSection = 'fixes';
+      }
+      continue;
+    }
+
+    // Skip empty lines
+    if (!trimmed) continue;
+
+    // Process bullet points
+    if (/^[-*]\s+/.test(line)) {
+      let content = line.replace(/^[-*]\s+/, '').trim();
+
+      // Extract PR/issue numbers before cleaning
+      const prMatches = content.match(/#(\d+)/g) || [];
+      const prNumbers = [...new Set(prMatches.map((m) => m.slice(1)))]; // Remove # and dedupe
+
+      // Clean up changeset formatting thoroughly
+      // Remove markdown links like [abc123](url) or [#123](url)
+      content = content.replace(/\[[^\]]*\]\([^)]*\)/g, '');
+      // Remove PR references like (#123)
+      content = content.replace(/\(#\d+\)/g, '');
+      // Remove standalone commit hashes
+      content = content.replace(/\b[a-f0-9]{7,40}\b/g, '');
+      // Remove package prefixes like @eventcatalog/core: or just leading colons
+      content = content.replace(/@[\w-]+\/[\w-]+:\s*/g, '');
+      content = content.replace(/^:\s*/, '');
+      // Clean up extra whitespace
+      content = content.replace(/\s+/g, ' ').trim();
+
+      // Append PR links at the end if found (use angle brackets for Discord auto-linking)
+      if (prNumbers.length > 0) {
+        const prLinks = prNumbers.map((n) => `<https://github.com/event-catalog/eventcatalog/pull/${n}>`).join(' ');
+        content = `${content}\n${prLinks}`;
+      }
+
+      // Skip empty or too short after cleanup
+      if (!content || content.length < 3) continue;
+
+      // Categorize based on current section (determined by headers)
+      // Also check content for keywords as fallback
+      const lowerContent = content.toLowerCase();
+      if (currentSection === 'fixes' || lowerContent.startsWith('fix') || lowerContent.includes('bug fix')) {
+        sections.fixes.push(content);
+      } else if (currentSection === 'features' || lowerContent.startsWith('add') || lowerContent.startsWith('feat')) {
+        sections.features.push(content);
+      } else {
+        sections.other.push(content);
+      }
+    }
+  }
+
+  return sections;
+}
+
+/**
+ * Format sections into Discord-friendly text
+ * Uses Discord's underline formatting (__text__) for clean headers
+ */
+function formatSections(sections) {
+  const parts = [];
+
+  if (sections.features.length > 0) {
+    parts.push(`__New Features__\n${sections.features.map((f) => `• ${f}`).join('\n\n')}`);
+  }
+
+  if (sections.fixes.length > 0) {
+    parts.push(`__Bug Fixes__\n${sections.fixes.map((f) => `• ${f}`).join('\n\n')}`);
+  }
+
+  if (sections.other.length > 0) {
+    parts.push(`__Other Changes__\n${sections.other.map((f) => `• ${f}`).join('\n\n')}`);
+  }
+
+  return parts.join('\n\n');
+}
+
+/**
+ * Extract version from release tag
+ */
+function extractVersion(tag) {
+  // Handle tags like "@eventcatalog/core@3.2.0" or "v3.2.0"
+  return tag.match(/(\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)/)?.[1] ?? tag;
+}
+
+/**
+ * Build the Discord payload as plain text (no embed box)
+ */
+function buildDiscordPayload(releaseTag, releaseBody, releaseUrl) {
+  const version = extractVersion(releaseTag);
+  const sections = parseReleaseNotes(releaseBody);
+  const formattedChanges = formatSections(sections);
+
+  let content = `**EventCatalog v${version}**\n\n`;
+  content += formattedChanges || 'Check the release notes for details.';
+  content += `\n\n<${releaseUrl}>`;
+
+  // Discord message limit is 2000 characters
+  if (content.length > 1900) {
+    const truncatedChanges = formattedChanges.slice(0, 1500);
+    content = `**EventCatalog v${version}**\n\n${truncatedChanges}\n\n*... and more*\n\n<${releaseUrl}>`;
+  }
+
+  return {
+    username: 'EventCatalog Release Bot',
+    avatar_url: EVENTCATALOG_AVATAR_URL,
+    content: content,
+  };
+}
+
+/**
+ * Send the notification to Discord
+ */
+async function sendToDiscord(payload) {
+  const response = await fetch(DISCORD_WEBHOOK_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Discord API error: ${response.status} - ${errorText}`);
+  }
+
+  return response;
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  console.log('📣 Preparing Discord release notification...');
+  console.log(`   Release: ${RELEASE_TAG}`);
+
+  try {
+    const payload = buildDiscordPayload(RELEASE_TAG, RELEASE_BODY, RELEASE_URL);
+
+    console.log('📤 Sending to Discord...');
+    await sendToDiscord(payload);
+
+    console.log('✅ Discord notification sent successfully!');
+  } catch (error) {
+    console.error('❌ Failed to send Discord notification:', error.message);
+    process.exit(1);
+  }
+}
+
+main();
diff --git a/scripts/preview-catalog-locally.js b/packages/core/scripts/preview-catalog-locally.js
similarity index 90%
rename from scripts/preview-catalog-locally.js
rename to packages/core/scripts/preview-catalog-locally.js
index 53aeb0a44..189f62950 100644
--- a/scripts/preview-catalog-locally.js
+++ b/packages/core/scripts/preview-catalog-locally.js
@@ -9,7 +9,7 @@ async function main() {
   const catalog = args[0] || 'default';
 
   const catalogDir = join(__dirname, '../eventcatalog/');
-  const projectDIR = join(__dirname, `../examples/${catalog}`);
+  const projectDIR = join(__dirname, `../../../examples/${catalog}`);
 
   execSync('pnpm run build:bin', { stdio: 'inherit' });
 
diff --git a/packages/core/scripts/start-catalog-locally.js b/packages/core/scripts/start-catalog-locally.js
new file mode 100644
index 000000000..dd7d65d4b
--- /dev/null
+++ b/packages/core/scripts/start-catalog-locally.js
@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+async function main() {
+  const __dirname = import.meta.dirname;
+
+  const args = process.argv.slice(2);
+  const catalog = args[0] || 'default';
+
+  const catalogDir = join(__dirname, '../eventcatalog/');
+  const projectDIR = join(__dirname, `../../../examples/${catalog}`);
+  const connectorsPackage = join(__dirname, '../../connectors/package.json');
+
+  if (existsSync(connectorsPackage)) {
+    execSync('pnpm --filter @eventcatalog/connectors run build:bin', { stdio: 'inherit' });
+  }
+
+  execSync('pnpm run build:bin', { stdio: 'inherit' });
+
+  execSync(`cross-env NODE_ENV=development PROJECT_DIR=${projectDIR} CATALOG_DIR=${catalogDir} npx . dev`, {
+    stdio: 'inherit',
+  });
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
diff --git a/packages/core/scripts/start-server-locally.js b/packages/core/scripts/start-server-locally.js
new file mode 100644
index 000000000..374d3a9a5
--- /dev/null
+++ b/packages/core/scripts/start-server-locally.js
@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+async function main() {
+  const __dirname = import.meta.dirname;
+
+  const args = process.argv.slice(2);
+  const catalog = args[0] || 'default';
+
+  const catalogDir = join(__dirname, '../eventcatalog/');
+  const projectDIR = join(__dirname, `../../../examples/${catalog}`);
+
+  // execSync('pnpm run build:bin', { stdio: 'inherit' });
+
+  execSync('pnpm run verify-build:catalog', { stdio: 'inherit' });
+
+  execSync(`cross-env NODE_ENV=development PROJECT_DIR=${projectDIR} CATALOG_DIR=${catalogDir} npx . start`, {
+    stdio: 'inherit',
+  });
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
diff --git a/packages/core/scripts/update-size-baseline.js b/packages/core/scripts/update-size-baseline.js
new file mode 100644
index 000000000..3c0163e63
--- /dev/null
+++ b/packages/core/scripts/update-size-baseline.js
@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const __dirname = import.meta.dirname;
+
+/**
+ * Recursively calculate the total size of a directory in bytes
+ */
+function getDirSizeBytes(dirPath) {
+  let totalSize = 0;
+
+  if (!fs.existsSync(dirPath)) {
+    return 0;
+  }
+
+  const items = fs.readdirSync(dirPath);
+
+  for (const item of items) {
+    const itemPath = path.join(dirPath, item);
+    const stats = fs.statSync(itemPath);
+
+    if (stats.isDirectory()) {
+      totalSize += getDirSizeBytes(itemPath);
+    } else {
+      totalSize += stats.size;
+    }
+  }
+
+  return totalSize;
+}
+
+/**
+ * Get directory size in KB
+ */
+function getDirSizeKB(dirPath) {
+  return Math.round(getDirSizeBytes(dirPath) / 1024);
+}
+
+/**
+ * Format size with appropriate units
+ */
+function formatSize(kb) {
+  if (kb >= 1024) {
+    return `${(kb / 1024).toFixed(2)} MB`;
+  }
+  return `${kb} KB`;
+}
+
+/**
+ * Main update function
+ */
+function main() {
+  const args = process.argv.slice(2);
+  const catalog = args[0] || 'default';
+
+  const distPath = path.join(__dirname, `../../../examples/${catalog}/dist`);
+  const baselinePath = path.join(__dirname, '../.size-baseline.json');
+
+  // Check if dist exists
+  if (!fs.existsSync(distPath)) {
+    console.error(`❌ Build output not found at: ${distPath}`);
+    console.error('   Run the build first: pnpm run verify-build:catalog');
+    process.exit(1);
+  }
+
+  // Calculate current size
+  const currentSize = getDirSizeKB(distPath);
+
+  // Read existing baseline if it exists
+  let oldSize = null;
+  if (fs.existsSync(baselinePath)) {
+    const existing = JSON.parse(fs.readFileSync(baselinePath, 'utf-8'));
+    oldSize = existing.dist.size;
+  }
+
+  // Create new baseline
+  const baseline = {
+    dist: {
+      size: currentSize,
+      unit: 'KB',
+      updatedAt: new Date().toISOString().split('T')[0],
+    },
+  };
+
+  // Write baseline
+  fs.writeFileSync(baselinePath, JSON.stringify(baseline, null, 2) + '\n');
+
+  // Output report
+  console.log('\n📦 Size Baseline Updated\n');
+  if (oldSize !== null) {
+    const delta = currentSize - oldSize;
+    const deltaPercent = ((delta / oldSize) * 100).toFixed(2);
+    const deltaSign = delta >= 0 ? '+' : '';
+    console.log(`   Previous:  ${formatSize(oldSize)}`);
+    console.log(`   New:       ${formatSize(currentSize)}`);
+    console.log(`   Change:    ${deltaSign}${formatSize(Math.abs(delta))} (${deltaSign}${deltaPercent}%)`);
+  } else {
+    console.log(`   Size:      ${formatSize(currentSize)}`);
+  }
+  console.log(`   File:      ${baselinePath}`);
+  console.log("\n✅ Don't forget to commit .size-baseline.json\n");
+}
+
+main();
diff --git a/__mocks__/astro-content.ts b/packages/core/src/__mocks__/astro-content.ts
similarity index 86%
rename from __mocks__/astro-content.ts
rename to packages/core/src/__mocks__/astro-content.ts
index 1f4afcffa..faaed7270 100644
--- a/__mocks__/astro-content.ts
+++ b/packages/core/src/__mocks__/astro-content.ts
@@ -6,7 +6,8 @@ export const getCollection = async (key: string, filter?: (entry: any) => boolea
   return [];
 };
 
-export type ContentCollectionKey =
+export type CollectionKey =
+  | 'agents'
   | 'events'
   | 'services'
   | 'commands'
@@ -18,7 +19,7 @@ export type ContentCollectionKey =
   | 'entities'
   | 'schemas';
 
-export type CollectionEntry<T extends ContentCollectionKey> = {
+export type CollectionEntry<T extends CollectionKey> = {
   id: string;
   slug: string;
   body: string;
diff --git a/src/__tests__/catalog-to-astro-content-directory.spec.ts b/packages/core/src/__tests__/catalog-to-astro-content-directory.spec.ts
similarity index 75%
rename from src/__tests__/catalog-to-astro-content-directory.spec.ts
rename to packages/core/src/__tests__/catalog-to-astro-content-directory.spec.ts
index 54748908e..6940bc797 100644
--- a/src/__tests__/catalog-to-astro-content-directory.spec.ts
+++ b/packages/core/src/__tests__/catalog-to-astro-content-directory.spec.ts
@@ -19,6 +19,12 @@ describe('catalog-to-astro-content-directory', () => {
     // create src/content inside astro directory
     await fs.mkdir(ASTRO_CONTENT_DIRECTORY, { recursive: true });
     await fs.writeFile(path.join(ASTRO_CONTENT_DIRECTORY, 'config.ts'), 'export const config = {};');
+    await fs.writeFile(
+      path.join(CATALOG_DIR, 'events', 'OrderAmended', 'order-flow.c4'),
+      'views { view OrderFlow { include * } }'
+    );
+    await fs.mkdir(path.join(ASTRO_OUTPUT, 'public', 'generated', 'events', 'OrderAmended'), { recursive: true });
+    await fs.writeFile(path.join(ASTRO_OUTPUT, 'public', 'generated', 'events', 'OrderAmended', 'stale.c4'), 'stale');
 
     // Convert the catalog
     await catalogToAstro(CATALOG_DIR, ASTRO_OUTPUT);
@@ -26,6 +32,7 @@ describe('catalog-to-astro-content-directory', () => {
 
   afterAll(async () => {
     await fs.rm(TMP_DIRECTORY, { recursive: true });
+    await fs.rm(path.join(CATALOG_DIR, 'events', 'OrderAmended', 'order-flow.c4'), { force: true });
     // await fs.rm(path.join(__dirname, 'public'), { recursive: true });
     const defaultFile = await fs.readFile(path.join(CATALOG_DIR, 'eventcatalog.config.defaults.js'), 'utf8');
     await fs.writeFile(path.join(CATALOG_DIR, 'eventcatalog.config.js'), defaultFile);
@@ -46,6 +53,11 @@ describe('catalog-to-astro-content-directory', () => {
     it('copies custom files from the public directory into the astro directory', async () => {
       expect(existsSync(path.join(ASTRO_OUTPUT, 'public', 'custom-file.txt'))).toBe(true);
     });
+
+    it('does not copy LikeC4 source files into the public directory', async () => {
+      expect(existsSync(path.join(ASTRO_OUTPUT, 'public', 'generated', 'events', 'OrderAmended', 'order-flow.c4'))).toBe(false);
+      expect(existsSync(path.join(ASTRO_OUTPUT, 'public', 'generated', 'events', 'OrderAmended', 'stale.c4'))).toBe(false);
+    });
   });
 
   describe('eventcatalog.config.js', () => {
diff --git a/packages/core/src/__tests__/core-node-modules.spec.ts b/packages/core/src/__tests__/core-node-modules.spec.ts
new file mode 100644
index 000000000..4fabe194d
--- /dev/null
+++ b/packages/core/src/__tests__/core-node-modules.spec.ts
@@ -0,0 +1,107 @@
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { linkCoreNodeModules, resolveInstalledCoreNodeModules } from '../core-node-modules';
+
+const TMP_DIRECTORY = path.join(__dirname, 'tmp-core-node-modules');
+
+const createAstroDependency = async (nodeModulesDirectory: string) => {
+  await fs.mkdir(path.join(nodeModulesDirectory, 'astro'), { recursive: true });
+  await fs.writeFile(path.join(nodeModulesDirectory, 'astro', 'package.json'), '{}');
+};
+
+const symlinkType = process.platform === 'win32' ? 'junction' : 'dir';
+
+describe('resolveInstalledCoreNodeModules', () => {
+  afterEach(async () => {
+    await fs.rm(TMP_DIRECTORY, { recursive: true, force: true });
+  });
+
+  it('uses the package local node_modules directory when it contains Astro', async () => {
+    const currentDir = path.join(TMP_DIRECTORY, 'node_modules', '@eventcatalog', 'core', 'dist');
+    const packageNodeModules = path.join(TMP_DIRECTORY, 'node_modules', '@eventcatalog', 'core', 'node_modules');
+
+    await fs.mkdir(currentDir, { recursive: true });
+    await createAstroDependency(packageNodeModules);
+
+    expect(resolveInstalledCoreNodeModules(currentDir)).toBe(packageNodeModules);
+  });
+
+  it('resolves the pnpm virtual-store node_modules directory when package local node_modules is absent', async () => {
+    const virtualStoreNodeModules = path.join(
+      TMP_DIRECTORY,
+      'node_modules',
+      '.pnpm',
+      '@eventcatalog+core@3.48.2',
+      'node_modules'
+    );
+    const currentDir = path.join(virtualStoreNodeModules, '@eventcatalog', 'core', 'dist');
+
+    await fs.mkdir(currentDir, { recursive: true });
+    await createAstroDependency(virtualStoreNodeModules);
+
+    expect(resolveInstalledCoreNodeModules(currentDir)).toBe(virtualStoreNodeModules);
+  });
+
+  it('keeps an existing core node_modules symlink when it points at the installed core dependencies', async () => {
+    const coreNodeModules = path.join(TMP_DIRECTORY, '.eventcatalog-core', 'node_modules');
+    const installedCoreNodeModules = path.join(
+      TMP_DIRECTORY,
+      'node_modules',
+      '.pnpm',
+      '@eventcatalog+core@3.48.2',
+      'node_modules'
+    );
+
+    await createAstroDependency(installedCoreNodeModules);
+    await fs.mkdir(path.dirname(coreNodeModules), { recursive: true });
+    await fs.symlink(installedCoreNodeModules, coreNodeModules, symlinkType);
+
+    linkCoreNodeModules({ coreNodeModules, installedCoreNodeModules });
+
+    expect(fsSync.realpathSync.native(coreNodeModules)).toBe(fsSync.realpathSync.native(installedCoreNodeModules));
+  });
+
+  it('replaces an existing core node_modules symlink when it points at stale pnpm dependencies', async () => {
+    const coreNodeModules = path.join(TMP_DIRECTORY, '.eventcatalog-core', 'node_modules');
+    const oldCoreNodeModules = path.join(TMP_DIRECTORY, 'node_modules', '.pnpm', '@eventcatalog+core@3.48.1', 'node_modules');
+    const installedCoreNodeModules = path.join(
+      TMP_DIRECTORY,
+      'node_modules',
+      '.pnpm',
+      '@eventcatalog+core@3.48.2',
+      'node_modules'
+    );
+
+    await createAstroDependency(oldCoreNodeModules);
+    await createAstroDependency(installedCoreNodeModules);
+    await fs.mkdir(path.dirname(coreNodeModules), { recursive: true });
+    await fs.symlink(oldCoreNodeModules, coreNodeModules, symlinkType);
+
+    linkCoreNodeModules({ coreNodeModules, installedCoreNodeModules });
+
+    expect(fsSync.realpathSync.native(coreNodeModules)).toBe(fsSync.realpathSync.native(installedCoreNodeModules));
+  });
+
+  it('replaces a dangling core node_modules symlink', async () => {
+    const coreNodeModules = path.join(TMP_DIRECTORY, '.eventcatalog-core', 'node_modules');
+    const removedCoreNodeModules = path.join(TMP_DIRECTORY, 'node_modules', '.pnpm', '@eventcatalog+core@3.48.1', 'node_modules');
+    const installedCoreNodeModules = path.join(
+      TMP_DIRECTORY,
+      'node_modules',
+      '.pnpm',
+      '@eventcatalog+core@3.48.2',
+      'node_modules'
+    );
+
+    await createAstroDependency(installedCoreNodeModules);
+    await fs.mkdir(path.dirname(removedCoreNodeModules), { recursive: true });
+    await fs.mkdir(path.dirname(coreNodeModules), { recursive: true });
+    await fs.symlink(removedCoreNodeModules, coreNodeModules, symlinkType);
+
+    linkCoreNodeModules({ coreNodeModules, installedCoreNodeModules });
+
+    expect(fsSync.realpathSync.native(coreNodeModules)).toBe(fsSync.realpathSync.native(installedCoreNodeModules));
+  });
+});
diff --git a/src/__tests__/eventcatalog-config-file-utils.spec.ts b/packages/core/src/__tests__/eventcatalog-config-file-utils.spec.ts
similarity index 76%
rename from src/__tests__/eventcatalog-config-file-utils.spec.ts
rename to packages/core/src/__tests__/eventcatalog-config-file-utils.spec.ts
index 28dae4526..4cbb66f64 100644
--- a/src/__tests__/eventcatalog-config-file-utils.spec.ts
+++ b/packages/core/src/__tests__/eventcatalog-config-file-utils.spec.ts
@@ -11,7 +11,6 @@ import {
   verifyRequiredFieldsAreInCatalogConfigFile,
   writeEventCatalogConfigFile,
 } from '../eventcatalog-config-file-utils';
-import { tmpdir } from 'os';
 
 describe('catalog-to-astro-content-directory', () => {
   afterEach(async () => {
@@ -103,12 +102,57 @@ describe('catalog-to-astro-content-directory', () => {
         })
       );
     });
-    it('removes eventcatalog config from the tmpdir', async () => {
+    it('does not create eventcatalog.config.mjs in the project directory', async () => {
       await getEventCatalogConfigFile(CATALOG_DIR);
 
-      const configFile = path.join(tmpdir(), 'eventcatalog.config.mjs');
+      const configFile = path.join(CATALOG_DIR, 'eventcatalog.config.mjs');
       expect(existsSync(configFile)).toBe(false);
     });
+
+    it('resolves packages imported by temporary config files from the project dependency tree', async () => {
+      const packageDirectory = path.join(CATALOG_DIR, 'node_modules', '@eventcatalog', 'connectors');
+      const configFile = path.join(CATALOG_DIR, 'eventcatalog.config.js');
+
+      await fs.mkdir(packageDirectory, { recursive: true });
+      await fs.writeFile(
+        path.join(packageDirectory, 'package.json'),
+        JSON.stringify({
+          name: '@eventcatalog/connectors',
+          type: 'module',
+          exports: './index.js',
+        })
+      );
+      await fs.writeFile(
+        path.join(packageDirectory, 'index.js'),
+        "export const githubDirectory = () => ({ type: 'directory', name: 'github:test' });"
+      );
+      await fs.writeFile(
+        configFile,
+        `
+          import { githubDirectory } from '@eventcatalog/connectors';
+
+          export default {
+            title: 'Package Import Test',
+            directory: {
+              sources: [githubDirectory()],
+            },
+          };
+        `
+      );
+
+      try {
+        const config = await getEventCatalogConfigFile(CATALOG_DIR);
+
+        expect(config).toEqual({
+          title: 'Package Import Test',
+          directory: {
+            sources: [{ type: 'directory', name: 'github:test' }],
+          },
+        });
+      } finally {
+        await fs.rm(path.join(CATALOG_DIR, 'node_modules'), { recursive: true, force: true });
+      }
+    });
   });
 
   describe('writeEventCatalogConfigFile', () => {
diff --git a/packages/core/src/__tests__/example-catalog-dependencies/dependencies/channels/TestingChannelOrder/index.md b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/channels/TestingChannelOrder/index.md
new file mode 100644
index 000000000..2c2f85010
--- /dev/null
+++ b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/channels/TestingChannelOrder/index.md
@@ -0,0 +1,12 @@
+---
+id: TestingChannelOrder
+name: TestingChannelOrder
+version: 5.0.0
+---
+:::warning
+
+You are running EventCatalog with dependencies enabled.
+
+This resource is mocked and is a dependency. This means that the resource is managed and owned by another catalog.
+
+:::
diff --git a/packages/core/src/__tests__/example-catalog-dependencies/dependencies/channels/{env}.testing.channel.order/index.md b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/channels/{env}.testing.channel.order/index.md
new file mode 100644
index 000000000..f57293911
--- /dev/null
+++ b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/channels/{env}.testing.channel.order/index.md
@@ -0,0 +1,12 @@
+---
+id: '{env}.testing.channel.order'
+name: '{env}.testing.channel.order'
+version: 5.0.0
+---
+:::warning
+
+You are running EventCatalog with dependencies enabled.
+
+This resource is mocked and is a dependency. This means that the resource is managed and owned by another catalog.
+
+:::
diff --git a/packages/core/src/__tests__/example-catalog-dependencies/dependencies/commands/TestingCommandOrder/index.md b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/commands/TestingCommandOrder/index.md
new file mode 100644
index 000000000..629a1b7be
--- /dev/null
+++ b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/commands/TestingCommandOrder/index.md
@@ -0,0 +1,12 @@
+---
+id: TestingCommandOrder
+name: TestingCommandOrder
+version: 5.0.0
+---
+:::warning
+
+You are running EventCatalog with dependencies enabled.
+
+This resource is mocked and is a dependency. This means that the resource is managed and owned by another catalog.
+
+:::
diff --git a/packages/core/src/__tests__/example-catalog-dependencies/dependencies/domains/TestingDomainOrder/index.md b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/domains/TestingDomainOrder/index.md
new file mode 100644
index 000000000..f51ce81d7
--- /dev/null
+++ b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/domains/TestingDomainOrder/index.md
@@ -0,0 +1,12 @@
+---
+id: TestingDomainOrder
+name: TestingDomainOrder
+version: 5.0.0
+---
+:::warning
+
+You are running EventCatalog with dependencies enabled.
+
+This resource is mocked and is a dependency. This means that the resource is managed and owned by another catalog.
+
+:::
diff --git a/packages/core/src/__tests__/example-catalog-dependencies/dependencies/events/TestingEventOrder/index.md b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/events/TestingEventOrder/index.md
new file mode 100644
index 000000000..408ef24c1
--- /dev/null
+++ b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/events/TestingEventOrder/index.md
@@ -0,0 +1,12 @@
+---
+id: TestingEventOrder
+name: TestingEventOrder
+version: 5.0.0
+---
+:::warning
+
+You are running EventCatalog with dependencies enabled.
+
+This resource is mocked and is a dependency. This means that the resource is managed and owned by another catalog.
+
+:::
diff --git a/packages/core/src/__tests__/example-catalog-dependencies/dependencies/queries/TestingQueryOrder/index.md b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/queries/TestingQueryOrder/index.md
new file mode 100644
index 000000000..7af5f4422
--- /dev/null
+++ b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/queries/TestingQueryOrder/index.md
@@ -0,0 +1,12 @@
+---
+id: TestingQueryOrder
+name: TestingQueryOrder
+version: 5.0.0
+---
+:::warning
+
+You are running EventCatalog with dependencies enabled.
+
+This resource is mocked and is a dependency. This means that the resource is managed and owned by another catalog.
+
+:::
diff --git a/packages/core/src/__tests__/example-catalog-dependencies/dependencies/services/TestingServiceOrder/index.md b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/services/TestingServiceOrder/index.md
new file mode 100644
index 000000000..0432e76c2
--- /dev/null
+++ b/packages/core/src/__tests__/example-catalog-dependencies/dependencies/services/TestingServiceOrder/index.md
@@ -0,0 +1,12 @@
+---
+id: TestingServiceOrder
+name: TestingServiceOrder
+version: 5.0.0
+---
+:::warning
+
+You are running EventCatalog with dependencies enabled.
+
+This resource is mocked and is a dependency. This means that the resource is managed and owned by another catalog.
+
+:::
diff --git a/src/__tests__/example-catalog-dependencies/eventcatalog.config.js b/packages/core/src/__tests__/example-catalog-dependencies/eventcatalog.config.js
similarity index 100%
rename from src/__tests__/example-catalog-dependencies/eventcatalog.config.js
rename to packages/core/src/__tests__/example-catalog-dependencies/eventcatalog.config.js
diff --git a/src/__tests__/example-catalog-dependencies/package.json b/packages/core/src/__tests__/example-catalog-dependencies/package.json
similarity index 100%
rename from src/__tests__/example-catalog-dependencies/package.json
rename to packages/core/src/__tests__/example-catalog-dependencies/package.json
diff --git a/src/__tests__/example-catalog/commands/AddInventory/index.md b/packages/core/src/__tests__/example-catalog/commands/AddInventory/index.md
similarity index 100%
rename from src/__tests__/example-catalog/commands/AddInventory/index.md
rename to packages/core/src/__tests__/example-catalog/commands/AddInventory/index.md
diff --git a/src/__tests__/example-catalog/commands/AddInventory/schema.json b/packages/core/src/__tests__/example-catalog/commands/AddInventory/schema.json
similarity index 100%
rename from src/__tests__/example-catalog/commands/AddInventory/schema.json
rename to packages/core/src/__tests__/example-catalog/commands/AddInventory/schema.json
diff --git a/src/__tests__/example-catalog/commands/AddInventory/versioned/0.0.1/index.md b/packages/core/src/__tests__/example-catalog/commands/AddInventory/versioned/0.0.1/index.md
similarity index 100%
rename from src/__tests__/example-catalog/commands/AddInventory/versioned/0.0.1/index.md
rename to packages/core/src/__tests__/example-catalog/commands/AddInventory/versioned/0.0.1/index.md
diff --git a/src/__tests__/example-catalog/commands/AddInventory/versioned/0.0.1/schema.json b/packages/core/src/__tests__/example-catalog/commands/AddInventory/versioned/0.0.1/schema.json
similarity index 100%
rename from src/__tests__/example-catalog/commands/AddInventory/versioned/0.0.1/schema.json
rename to packages/core/src/__tests__/example-catalog/commands/AddInventory/versioned/0.0.1/schema.json
diff --git a/src/__tests__/example-catalog/domains/Payment/asyncapi.yml b/packages/core/src/__tests__/example-catalog/domains/Payment/asyncapi.yml
similarity index 100%
rename from src/__tests__/example-catalog/domains/Payment/asyncapi.yml
rename to packages/core/src/__tests__/example-catalog/domains/Payment/asyncapi.yml
diff --git a/src/__tests__/example-catalog/domains/Payment/events/PaymentDomainTestEvent1/index.md b/packages/core/src/__tests__/example-catalog/domains/Payment/events/PaymentDomainTestEvent1/index.md
similarity index 100%
rename from src/__tests__/example-catalog/domains/Payment/events/PaymentDomainTestEvent1/index.md
rename to packages/core/src/__tests__/example-catalog/domains/Payment/events/PaymentDomainTestEvent1/index.md
diff --git a/src/__tests__/example-catalog/domains/Payment/events/PaymentDomainTestEvent1/schema.json b/packages/core/src/__tests__/example-catalog/domains/Payment/events/PaymentDomainTestEvent1/schema.json
similarity index 100%
rename from src/__tests__/example-catalog/domains/Payment/events/PaymentDomainTestEvent1/schema.json
rename to packages/core/src/__tests__/example-catalog/domains/Payment/events/PaymentDomainTestEvent1/schema.json
diff --git a/src/__tests__/example-catalog/domains/Payment/events/PaymentDomainTestEvent1/versioned/0.0.1/index.md b/packages/core/src/__tests__/example-catalog/domains/Payment/events/PaymentDomainTestEvent1/versioned/0.0.1/index.md
similarity index 100%
rename from src/__tests__/example-catalog/domains/Payment/events/PaymentDomainTestEvent1/versioned/0.0.1/index.md
rename to packages/core/src/__tests__/example-catalog/domains/Payment/events/PaymentDomainTestEvent1/versioned/0.0.1/index.md
diff --git a/src/__tests__/example-catalog/domains/Payment/flows/ProcessingOfAnOrder/index.md b/packages/core/src/__tests__/example-catalog/domains/Payment/flows/ProcessingOfAnOrder/index.md
similarity index 100%
rename from src/__tests__/example-catalog/domains/Payment/flows/ProcessingOfAnOrder/index.md
rename to packages/core/src/__tests__/example-catalog/domains/Payment/flows/ProcessingOfAnOrder/index.md
diff --git a/src/__tests__/example-catalog/domains/Payment/flows/ProcessingOfAnOrder/versioned/0.0.1/index.md b/packages/core/src/__tests__/example-catalog/domains/Payment/flows/ProcessingOfAnOrder/versioned/0.0.1/index.md
similarity index 100%
rename from src/__tests__/example-catalog/domains/Payment/flows/ProcessingOfAnOrder/versioned/0.0.1/index.md
rename to packages/core/src/__tests__/example-catalog/domains/Payment/flows/ProcessingOfAnOrder/versioned/0.0.1/index.md
diff --git a/src/__tests__/example-catalog/domains/Payment/index.md b/packages/core/src/__tests__/example-catalog/domains/Payment/index.md
similarity index 100%
rename from src/__tests__/example-catalog/domains/Payment/index.md
rename to packages/core/src/__tests__/example-catalog/domains/Payment/index.md
diff --git a/src/__tests__/example-catalog/domains/Payment/services/ExternalPaymentService/asyncapi.yml b/packages/core/src/__tests__/example-catalog/domains/Payment/services/ExternalPaymentService/asyncapi.yml
similarity index 100%
rename from src/__tests__/example-catalog/domains/Payment/services/ExternalPaymentService/asyncapi.yml
rename to packages/core/src/__tests__/example-catalog/domains/Payment/services/ExternalPaymentService/asyncapi.yml
diff --git a/src/__tests__/example-catalog/domains/Payment/services/ExternalPaymentService/index.md b/packages/core/src/__tests__/example-catalog/domains/Payment/services/ExternalPaymentService/index.md
similarity index 100%
rename from src/__tests__/example-catalog/domains/Payment/services/ExternalPaymentService/index.md
rename to packages/core/src/__tests__/example-catalog/domains/Payment/services/ExternalPaymentService/index.md
diff --git a/src/__tests__/example-catalog/domains/Payment/services/ExternalPaymentService/versioned/0.0.1/index.md b/packages/core/src/__tests__/example-catalog/domains/Payment/services/ExternalPaymentService/versioned/0.0.1/index.md
similarity index 100%
rename from src/__tests__/example-catalog/domains/Payment/services/ExternalPaymentService/versioned/0.0.1/index.md
rename to packages/core/src/__tests__/example-catalog/domains/Payment/services/ExternalPaymentService/versioned/0.0.1/index.md
diff --git a/src/__tests__/example-catalog/domains/Payment/ubiquitous-language.md b/packages/core/src/__tests__/example-catalog/domains/Payment/ubiquitous-language.md
similarity index 100%
rename from src/__tests__/example-catalog/domains/Payment/ubiquitous-language.md
rename to packages/core/src/__tests__/example-catalog/domains/Payment/ubiquitous-language.md
diff --git a/src/__tests__/example-catalog/domains/Payment/versioned/0.0.1/index.md b/packages/core/src/__tests__/example-catalog/domains/Payment/versioned/0.0.1/index.md
similarity index 100%
rename from src/__tests__/example-catalog/domains/Payment/versioned/0.0.1/index.md
rename to packages/core/src/__tests__/example-catalog/domains/Payment/versioned/0.0.1/index.md
diff --git a/src/__tests__/example-catalog/eventcatalog.config.defaults.js b/packages/core/src/__tests__/example-catalog/eventcatalog.config.defaults.js
similarity index 100%
rename from src/__tests__/example-catalog/eventcatalog.config.defaults.js
rename to packages/core/src/__tests__/example-catalog/eventcatalog.config.defaults.js
diff --git a/src/__tests__/example-catalog/eventcatalog.config.js b/packages/core/src/__tests__/example-catalog/eventcatalog.config.js
similarity index 100%
rename from src/__tests__/example-catalog/eventcatalog.config.js
rename to packages/core/src/__tests__/example-catalog/eventcatalog.config.js
diff --git a/src/__tests__/example-catalog/eventcatalog.styles.css b/packages/core/src/__tests__/example-catalog/eventcatalog.styles.css
similarity index 100%
rename from src/__tests__/example-catalog/eventcatalog.styles.css
rename to packages/core/src/__tests__/example-catalog/eventcatalog.styles.css
diff --git a/src/__tests__/example-catalog/events/InventoryAdjusted/changelog.md b/packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/changelog.md
similarity index 100%
rename from src/__tests__/example-catalog/events/InventoryAdjusted/changelog.md
rename to packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/changelog.md
diff --git a/src/__tests__/example-catalog/events/InventoryAdjusted/index.md b/packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/index.md
similarity index 100%
rename from src/__tests__/example-catalog/events/InventoryAdjusted/index.md
rename to packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/index.md
diff --git a/src/__tests__/example-catalog/events/InventoryAdjusted/schema.avro b/packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/schema.avro
similarity index 100%
rename from src/__tests__/example-catalog/events/InventoryAdjusted/schema.avro
rename to packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/schema.avro
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/schema.json b/packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/schema.json
similarity index 100%
rename from examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/schema.json
rename to packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/schema.json
diff --git a/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/0.0.1/changelog.md b/packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/0.0.1/changelog.md
similarity index 100%
rename from src/__tests__/example-catalog/events/InventoryAdjusted/versioned/0.0.1/changelog.md
rename to packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/0.0.1/changelog.md
diff --git a/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/0.0.1/index.md b/packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/0.0.1/index.md
similarity index 100%
rename from src/__tests__/example-catalog/events/InventoryAdjusted/versioned/0.0.1/index.md
rename to packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/0.0.1/index.md
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/schema.avro b/packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/0.0.1/schema.avro
similarity index 100%
rename from examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/schema.avro
rename to packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/0.0.1/schema.avro
diff --git a/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/1.0.0/changelog.md b/packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/1.0.0/changelog.md
similarity index 100%
rename from src/__tests__/example-catalog/events/InventoryAdjusted/versioned/1.0.0/changelog.md
rename to packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/1.0.0/changelog.md
diff --git a/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/1.0.0/index.md b/packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/1.0.0/index.md
similarity index 100%
rename from src/__tests__/example-catalog/events/InventoryAdjusted/versioned/1.0.0/index.md
rename to packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/1.0.0/index.md
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/schema.avro b/packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/1.0.0/schema.avro
similarity index 100%
rename from examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/schema.avro
rename to packages/core/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/1.0.0/schema.avro
diff --git a/src/__tests__/example-catalog/events/OrderAmended/index.md b/packages/core/src/__tests__/example-catalog/events/OrderAmended/index.md
similarity index 100%
rename from src/__tests__/example-catalog/events/OrderAmended/index.md
rename to packages/core/src/__tests__/example-catalog/events/OrderAmended/index.md
diff --git a/src/__tests__/example-catalog/events/OrderAmended/schema.avro b/packages/core/src/__tests__/example-catalog/events/OrderAmended/schema.avro
similarity index 100%
rename from src/__tests__/example-catalog/events/OrderAmended/schema.avro
rename to packages/core/src/__tests__/example-catalog/events/OrderAmended/schema.avro
diff --git a/src/__tests__/example-catalog/events/OrderAmended/schema.json b/packages/core/src/__tests__/example-catalog/events/OrderAmended/schema.json
similarity index 100%
rename from src/__tests__/example-catalog/events/OrderAmended/schema.json
rename to packages/core/src/__tests__/example-catalog/events/OrderAmended/schema.json
diff --git a/src/__tests__/example-catalog/events/OrderCancelled/index.md b/packages/core/src/__tests__/example-catalog/events/OrderCancelled/index.md
similarity index 100%
rename from src/__tests__/example-catalog/events/OrderCancelled/index.md
rename to packages/core/src/__tests__/example-catalog/events/OrderCancelled/index.md
diff --git a/src/__tests__/example-catalog/events/OrderCancelled/schema.json b/packages/core/src/__tests__/example-catalog/events/OrderCancelled/schema.json
similarity index 100%
rename from src/__tests__/example-catalog/events/OrderCancelled/schema.json
rename to packages/core/src/__tests__/example-catalog/events/OrderCancelled/schema.json
diff --git a/src/__tests__/example-catalog/events/OrderConfirmed/index.md b/packages/core/src/__tests__/example-catalog/events/OrderConfirmed/index.md
similarity index 100%
rename from src/__tests__/example-catalog/events/OrderConfirmed/index.md
rename to packages/core/src/__tests__/example-catalog/events/OrderConfirmed/index.md
diff --git a/src/__tests__/example-catalog/events/OrderConfirmed/schema.json b/packages/core/src/__tests__/example-catalog/events/OrderConfirmed/schema.json
similarity index 100%
rename from src/__tests__/example-catalog/events/OrderConfirmed/schema.json
rename to packages/core/src/__tests__/example-catalog/events/OrderConfirmed/schema.json
diff --git a/src/__tests__/example-catalog/events/OutOfStock/index.md b/packages/core/src/__tests__/example-catalog/events/OutOfStock/index.md
similarity index 100%
rename from src/__tests__/example-catalog/events/OutOfStock/index.md
rename to packages/core/src/__tests__/example-catalog/events/OutOfStock/index.md
diff --git a/src/__tests__/example-catalog/events/OutOfStock/versioned/0.0.1/index.md b/packages/core/src/__tests__/example-catalog/events/OutOfStock/versioned/0.0.1/index.md
similarity index 100%
rename from src/__tests__/example-catalog/events/OutOfStock/versioned/0.0.1/index.md
rename to packages/core/src/__tests__/example-catalog/events/OutOfStock/versioned/0.0.1/index.md
diff --git a/src/__tests__/example-catalog/flows/Payment/PaymentProcessed/index.md b/packages/core/src/__tests__/example-catalog/flows/Payment/PaymentProcessed/index.md
similarity index 100%
rename from src/__tests__/example-catalog/flows/Payment/PaymentProcessed/index.md
rename to packages/core/src/__tests__/example-catalog/flows/Payment/PaymentProcessed/index.md
diff --git a/src/__tests__/example-catalog/flows/Payment/PaymentProcessed/versioned/0.0.1/index.md b/packages/core/src/__tests__/example-catalog/flows/Payment/PaymentProcessed/versioned/0.0.1/index.md
similarity index 100%
rename from src/__tests__/example-catalog/flows/Payment/PaymentProcessed/versioned/0.0.1/index.md
rename to packages/core/src/__tests__/example-catalog/flows/Payment/PaymentProcessed/versioned/0.0.1/index.md
diff --git a/src/__tests__/example-catalog/flows/Subscriptions/CancelSubscription/index.md b/packages/core/src/__tests__/example-catalog/flows/Subscriptions/CancelSubscription/index.md
similarity index 100%
rename from src/__tests__/example-catalog/flows/Subscriptions/CancelSubscription/index.md
rename to packages/core/src/__tests__/example-catalog/flows/Subscriptions/CancelSubscription/index.md
diff --git a/src/__tests__/example-catalog/package.json b/packages/core/src/__tests__/example-catalog/package.json
similarity index 100%
rename from src/__tests__/example-catalog/package.json
rename to packages/core/src/__tests__/example-catalog/package.json
diff --git a/src/__tests__/example-catalog/public/custom-file.txt b/packages/core/src/__tests__/example-catalog/public/custom-file.txt
similarity index 100%
rename from src/__tests__/example-catalog/public/custom-file.txt
rename to packages/core/src/__tests__/example-catalog/public/custom-file.txt
diff --git a/src/__tests__/example-catalog/services/PaymentService/asyncapi.yml b/packages/core/src/__tests__/example-catalog/services/PaymentService/asyncapi.yml
similarity index 100%
rename from src/__tests__/example-catalog/services/PaymentService/asyncapi.yml
rename to packages/core/src/__tests__/example-catalog/services/PaymentService/asyncapi.yml
diff --git a/src/__tests__/example-catalog/services/PaymentService/events/PaymentAccepted/index.md b/packages/core/src/__tests__/example-catalog/services/PaymentService/events/PaymentAccepted/index.md
similarity index 100%
rename from src/__tests__/example-catalog/services/PaymentService/events/PaymentAccepted/index.md
rename to packages/core/src/__tests__/example-catalog/services/PaymentService/events/PaymentAccepted/index.md
diff --git a/src/__tests__/example-catalog/services/PaymentService/events/PaymentAccepted/schema.json b/packages/core/src/__tests__/example-catalog/services/PaymentService/events/PaymentAccepted/schema.json
similarity index 100%
rename from src/__tests__/example-catalog/services/PaymentService/events/PaymentAccepted/schema.json
rename to packages/core/src/__tests__/example-catalog/services/PaymentService/events/PaymentAccepted/schema.json
diff --git a/src/__tests__/example-catalog/services/PaymentService/events/PaymentAccepted/versioned/0.0.1/index.md b/packages/core/src/__tests__/example-catalog/services/PaymentService/events/PaymentAccepted/versioned/0.0.1/index.md
similarity index 100%
rename from src/__tests__/example-catalog/services/PaymentService/events/PaymentAccepted/versioned/0.0.1/index.md
rename to packages/core/src/__tests__/example-catalog/services/PaymentService/events/PaymentAccepted/versioned/0.0.1/index.md
diff --git a/src/__tests__/example-catalog/services/PaymentService/flows/PaymentAccepted/index.md b/packages/core/src/__tests__/example-catalog/services/PaymentService/flows/PaymentAccepted/index.md
similarity index 100%
rename from src/__tests__/example-catalog/services/PaymentService/flows/PaymentAccepted/index.md
rename to packages/core/src/__tests__/example-catalog/services/PaymentService/flows/PaymentAccepted/index.md
diff --git a/src/__tests__/example-catalog/services/PaymentService/flows/PaymentAccepted/versioned/0.0.1/index.md b/packages/core/src/__tests__/example-catalog/services/PaymentService/flows/PaymentAccepted/versioned/0.0.1/index.md
similarity index 100%
rename from src/__tests__/example-catalog/services/PaymentService/flows/PaymentAccepted/versioned/0.0.1/index.md
rename to packages/core/src/__tests__/example-catalog/services/PaymentService/flows/PaymentAccepted/versioned/0.0.1/index.md
diff --git a/src/__tests__/example-catalog/services/PaymentService/index.md b/packages/core/src/__tests__/example-catalog/services/PaymentService/index.md
similarity index 100%
rename from src/__tests__/example-catalog/services/PaymentService/index.md
rename to packages/core/src/__tests__/example-catalog/services/PaymentService/index.md
diff --git a/src/__tests__/example-catalog/services/PaymentService/openapi.yaml b/packages/core/src/__tests__/example-catalog/services/PaymentService/openapi.yaml
similarity index 100%
rename from src/__tests__/example-catalog/services/PaymentService/openapi.yaml
rename to packages/core/src/__tests__/example-catalog/services/PaymentService/openapi.yaml
diff --git a/src/__tests__/example-catalog/services/PaymentService/versioned/0.0.1/index.md b/packages/core/src/__tests__/example-catalog/services/PaymentService/versioned/0.0.1/index.md
similarity index 100%
rename from src/__tests__/example-catalog/services/PaymentService/versioned/0.0.1/index.md
rename to packages/core/src/__tests__/example-catalog/services/PaymentService/versioned/0.0.1/index.md
diff --git a/src/__tests__/example-catalog/teams/full-stack.md b/packages/core/src/__tests__/example-catalog/teams/full-stack.md
similarity index 100%
rename from src/__tests__/example-catalog/teams/full-stack.md
rename to packages/core/src/__tests__/example-catalog/teams/full-stack.md
diff --git a/src/__tests__/example-catalog/users/dboyne.md b/packages/core/src/__tests__/example-catalog/users/dboyne.md
similarity index 100%
rename from src/__tests__/example-catalog/users/dboyne.md
rename to packages/core/src/__tests__/example-catalog/users/dboyne.md
diff --git a/packages/core/src/__tests__/map-catalog-to-astro.spec.ts b/packages/core/src/__tests__/map-catalog-to-astro.spec.ts
new file mode 100644
index 000000000..2d71e93fd
--- /dev/null
+++ b/packages/core/src/__tests__/map-catalog-to-astro.spec.ts
@@ -0,0 +1,68 @@
+import path from 'node:path';
+import { expect, describe, it } from 'vitest';
+import { mapCatalogToAstro } from '../map-catalog-to-astro';
+
+const PROJECT_DIR = path.join(__dirname, 'example-catalog');
+const ASTRO_DIR = path.join(__dirname, 'tmp-astro');
+
+const map = (relativeFilePath: string) =>
+  mapCatalogToAstro({
+    filePath: path.join(PROJECT_DIR, relativeFilePath),
+    astroDir: ASTRO_DIR,
+    projectDir: PROJECT_DIR,
+  });
+
+describe('map-catalog-to-astro', () => {
+  describe('custom pages (top-level pages directory)', () => {
+    it('maps .astro files to src/custom-pages instead of the public directory', () => {
+      expect(map('pages/homepage.astro')).toEqual([path.join(ASTRO_DIR, 'src', 'custom-pages', 'homepage.astro')]);
+      expect(map('pages/reports/[id].astro')).toEqual([path.join(ASTRO_DIR, 'src', 'custom-pages', 'reports', '[id].astro')]);
+    });
+
+    it('maps API endpoint files to src/custom-pages', () => {
+      expect(map('pages/api/teams.ts')).toEqual([path.join(ASTRO_DIR, 'src', 'custom-pages', 'api', 'teams.ts')]);
+      expect(map('pages/data.json.js')).toEqual([path.join(ASTRO_DIR, 'src', 'custom-pages', 'data.json.js')]);
+    });
+
+    it('maps directories to both custom-pages and public targets so deletes clean up both', () => {
+      expect(map('pages/reports')).toEqual([
+        path.join(ASTRO_DIR, 'src', 'custom-pages', 'reports'),
+        path.join(ASTRO_DIR, 'public', 'generated', 'pages', 'reports'),
+      ]);
+    });
+
+    it('keeps mapping non-code assets in pages to the public directory', () => {
+      expect(map('pages/diagram.png')).toEqual([path.join(ASTRO_DIR, 'public', 'generated', 'pages', 'diagram.png')]);
+    });
+
+    it('does not treat nested pages directories inside collections as custom pages', () => {
+      expect(map('domains/Orders/pages/overview.astro')).toEqual([
+        path.join(ASTRO_DIR, 'public', 'generated', 'pages', 'overview.astro'),
+      ]);
+    });
+  });
+
+  describe('collections', () => {
+    it('maps collection asset files to the public directory', () => {
+      expect(map('events/OrderAmended/schema.json')).toEqual([
+        path.join(ASTRO_DIR, 'public', 'generated', 'events', 'OrderAmended', 'schema.json'),
+      ]);
+    });
+
+    it('ignores LikeC4 source files', () => {
+      expect(map('events/OrderAmended/order-flow.c4')).toEqual([]);
+    });
+  });
+
+  describe('custom components', () => {
+    it('maps components to src/custom-defined-components', () => {
+      expect(map('components/MyComponent.astro')).toEqual([
+        path.join(ASTRO_DIR, 'src', 'custom-defined-components', 'MyComponent.astro'),
+      ]);
+    });
+  });
+
+  it('ignores files that are not catalog related', () => {
+    expect(map('README.txt')).toEqual([]);
+  });
+});
diff --git a/src/__tests__/migrations/catalog/channels/eventbus/index.mdx b/packages/core/src/__tests__/migrations/catalog/channels/eventbus/index.mdx
similarity index 100%
rename from src/__tests__/migrations/catalog/channels/eventbus/index.mdx
rename to packages/core/src/__tests__/migrations/catalog/channels/eventbus/index.mdx
diff --git a/src/__tests__/migrations/catalog/channels/http-channel/index.mdx b/packages/core/src/__tests__/migrations/catalog/channels/http-channel/index.mdx
similarity index 100%
rename from src/__tests__/migrations/catalog/channels/http-channel/index.mdx
rename to packages/core/src/__tests__/migrations/catalog/channels/http-channel/index.mdx
diff --git a/src/__tests__/migrations/catalog/domains/Orders/services/OrderService/index.mdx b/packages/core/src/__tests__/migrations/catalog/domains/Orders/services/OrderService/index.mdx
similarity index 100%
rename from src/__tests__/migrations/catalog/domains/Orders/services/OrderService/index.mdx
rename to packages/core/src/__tests__/migrations/catalog/domains/Orders/services/OrderService/index.mdx
diff --git a/src/__tests__/migrations/catalog/events/MultiChannelMessage/index.mdx b/packages/core/src/__tests__/migrations/catalog/events/MultiChannelMessage/index.mdx
similarity index 100%
rename from src/__tests__/migrations/catalog/events/MultiChannelMessage/index.mdx
rename to packages/core/src/__tests__/migrations/catalog/events/MultiChannelMessage/index.mdx
diff --git a/packages/core/src/__tests__/migrations/catalog/queries/GetInventoryItem/index.mdx b/packages/core/src/__tests__/migrations/catalog/queries/GetInventoryItem/index.mdx
new file mode 100644
index 000000000..8d59c491a
--- /dev/null
+++ b/packages/core/src/__tests__/migrations/catalog/queries/GetInventoryItem/index.mdx
@@ -0,0 +1,9 @@
+---
+id: GetInventoryItem
+name: Get Inventory Item
+version: 1.0.0
+summary: |
+  Retrieves an inventory item by id
+---
+
+Query with no channels defined.
diff --git a/src/__tests__/migrations/catalog/services/InventoryService/events/InventoryAdjusted/index.mdx b/packages/core/src/__tests__/migrations/catalog/services/InventoryService/events/InventoryAdjusted/index.mdx
similarity index 100%
rename from src/__tests__/migrations/catalog/services/InventoryService/events/InventoryAdjusted/index.mdx
rename to packages/core/src/__tests__/migrations/catalog/services/InventoryService/events/InventoryAdjusted/index.mdx
diff --git a/src/__tests__/migrations/catalog/services/InventoryService/events/OrderAmended/index.mdx b/packages/core/src/__tests__/migrations/catalog/services/InventoryService/events/OrderAmended/index.mdx
similarity index 100%
rename from src/__tests__/migrations/catalog/services/InventoryService/events/OrderAmended/index.mdx
rename to packages/core/src/__tests__/migrations/catalog/services/InventoryService/events/OrderAmended/index.mdx
diff --git a/src/__tests__/migrations/catalog/services/InventoryService/index.mdx b/packages/core/src/__tests__/migrations/catalog/services/InventoryService/index.mdx
similarity index 100%
rename from src/__tests__/migrations/catalog/services/InventoryService/index.mdx
rename to packages/core/src/__tests__/migrations/catalog/services/InventoryService/index.mdx
diff --git a/packages/core/src/__tests__/migrations/catalog/services/MixedSendsService/index.mdx b/packages/core/src/__tests__/migrations/catalog/services/MixedSendsService/index.mdx
new file mode 100644
index 000000000..accf90211
--- /dev/null
+++ b/packages/core/src/__tests__/migrations/catalog/services/MixedSendsService/index.mdx
@@ -0,0 +1,20 @@
+---
+id: MixedSendsService
+version: 1.0.0
+name: Mixed Sends Service
+summary: |
+  Service that sends both a legacy-channel event and a query with no channel
+owners:
+  - inventory-management
+sends:
+  - id: OrderAmended
+    version: 0.0.1
+    to:
+      - id: eventbus
+        version: 1.0.0
+  - id: GetInventoryItem
+    version: 1.0.0
+receives: []
+---
+
+Service used to verify the migration preserves non-channel sends (e.g. queries).
diff --git a/src/__tests__/migrations/catalog/services/MultiChannelService/index.mdx b/packages/core/src/__tests__/migrations/catalog/services/MultiChannelService/index.mdx
similarity index 100%
rename from src/__tests__/migrations/catalog/services/MultiChannelService/index.mdx
rename to packages/core/src/__tests__/migrations/catalog/services/MultiChannelService/index.mdx
diff --git a/src/__tests__/migrations/message-channels-examples/channels/eventbus/index.mdx b/packages/core/src/__tests__/migrations/message-channels-examples/channels/eventbus/index.mdx
similarity index 100%
rename from src/__tests__/migrations/message-channels-examples/channels/eventbus/index.mdx
rename to packages/core/src/__tests__/migrations/message-channels-examples/channels/eventbus/index.mdx
diff --git a/src/__tests__/migrations/message-channels-examples/channels/http-channel/index.mdx b/packages/core/src/__tests__/migrations/message-channels-examples/channels/http-channel/index.mdx
similarity index 100%
rename from src/__tests__/migrations/message-channels-examples/channels/http-channel/index.mdx
rename to packages/core/src/__tests__/migrations/message-channels-examples/channels/http-channel/index.mdx
diff --git a/src/__tests__/migrations/message-channels-examples/domains/Orders/services/OrderService/index.mdx b/packages/core/src/__tests__/migrations/message-channels-examples/domains/Orders/services/OrderService/index.mdx
similarity index 100%
rename from src/__tests__/migrations/message-channels-examples/domains/Orders/services/OrderService/index.mdx
rename to packages/core/src/__tests__/migrations/message-channels-examples/domains/Orders/services/OrderService/index.mdx
diff --git a/src/__tests__/migrations/message-channels-examples/events/MultiChannelMessage/index.mdx b/packages/core/src/__tests__/migrations/message-channels-examples/events/MultiChannelMessage/index.mdx
similarity index 100%
rename from src/__tests__/migrations/message-channels-examples/events/MultiChannelMessage/index.mdx
rename to packages/core/src/__tests__/migrations/message-channels-examples/events/MultiChannelMessage/index.mdx
diff --git a/packages/core/src/__tests__/migrations/message-channels-examples/queries/GetInventoryItem/index.mdx b/packages/core/src/__tests__/migrations/message-channels-examples/queries/GetInventoryItem/index.mdx
new file mode 100644
index 000000000..8d59c491a
--- /dev/null
+++ b/packages/core/src/__tests__/migrations/message-channels-examples/queries/GetInventoryItem/index.mdx
@@ -0,0 +1,9 @@
+---
+id: GetInventoryItem
+name: Get Inventory Item
+version: 1.0.0
+summary: |
+  Retrieves an inventory item by id
+---
+
+Query with no channels defined.
diff --git a/src/__tests__/migrations/message-channels-examples/services/InventoryService/events/InventoryAdjusted/index.mdx b/packages/core/src/__tests__/migrations/message-channels-examples/services/InventoryService/events/InventoryAdjusted/index.mdx
similarity index 100%
rename from src/__tests__/migrations/message-channels-examples/services/InventoryService/events/InventoryAdjusted/index.mdx
rename to packages/core/src/__tests__/migrations/message-channels-examples/services/InventoryService/events/InventoryAdjusted/index.mdx
diff --git a/src/__tests__/migrations/message-channels-examples/services/InventoryService/events/OrderAmended/index.mdx b/packages/core/src/__tests__/migrations/message-channels-examples/services/InventoryService/events/OrderAmended/index.mdx
similarity index 100%
rename from src/__tests__/migrations/message-channels-examples/services/InventoryService/events/OrderAmended/index.mdx
rename to packages/core/src/__tests__/migrations/message-channels-examples/services/InventoryService/events/OrderAmended/index.mdx
diff --git a/src/__tests__/migrations/message-channels-examples/services/InventoryService/index.mdx b/packages/core/src/__tests__/migrations/message-channels-examples/services/InventoryService/index.mdx
similarity index 100%
rename from src/__tests__/migrations/message-channels-examples/services/InventoryService/index.mdx
rename to packages/core/src/__tests__/migrations/message-channels-examples/services/InventoryService/index.mdx
diff --git a/packages/core/src/__tests__/migrations/message-channels-examples/services/MixedSendsService/index.mdx b/packages/core/src/__tests__/migrations/message-channels-examples/services/MixedSendsService/index.mdx
new file mode 100644
index 000000000..38c00030c
--- /dev/null
+++ b/packages/core/src/__tests__/migrations/message-channels-examples/services/MixedSendsService/index.mdx
@@ -0,0 +1,17 @@
+---
+id: MixedSendsService
+version: 1.0.0
+name: Mixed Sends Service
+summary: |
+  Service that sends both a legacy-channel event and a query with no channel
+owners:
+  - inventory-management
+sends:
+  - id: OrderAmended
+    version: 0.0.1
+  - id: GetInventoryItem
+    version: 1.0.0
+receives: []
+---
+
+Service used to verify the migration preserves non-channel sends (e.g. queries).
diff --git a/src/__tests__/migrations/message-channels-examples/services/MultiChannelService/index.mdx b/packages/core/src/__tests__/migrations/message-channels-examples/services/MultiChannelService/index.mdx
similarity index 100%
rename from src/__tests__/migrations/message-channels-examples/services/MultiChannelService/index.mdx
rename to packages/core/src/__tests__/migrations/message-channels-examples/services/MultiChannelService/index.mdx
diff --git a/packages/core/src/__tests__/migrations/message-channels-to-service-channels.spec.ts b/packages/core/src/__tests__/migrations/message-channels-to-service-channels.spec.ts
new file mode 100644
index 000000000..efe7c567a
--- /dev/null
+++ b/packages/core/src/__tests__/migrations/message-channels-to-service-channels.spec.ts
@@ -0,0 +1,123 @@
+/**
+ * This migration script will move EventCatalog channels defined in messages to the new API for services
+ * For example; any catalog that has a message that has defined channels, the channel configuration will be moved to the service the sends or receives the message.
+ */
+
+import messageChannelsToServiceChannels from '../../migrations/message-channels-to-service-channels';
+import { expect, it } from 'vitest';
+import path from 'node:path';
+import fs from 'node:fs';
+import matter from 'gray-matter';
+
+describe('message-channels-to-service-channels', () => {
+  beforeEach(() => {
+    delete process.env.EVENTCATALOG_DISABLE_CHANNEL_MIGRATION;
+    process.env.PROJECT_DIR = path.join(__dirname, 'catalog');
+    // Clear the catalog directory
+    fs.rmSync(path.join(process.env.PROJECT_DIR!), { recursive: true });
+    // Copy test data from previous version of the catalog to a new catalog
+    fs.cpSync(path.join(__dirname, 'message-channels-examples'), path.join(process.env.PROJECT_DIR!), { recursive: true });
+  });
+
+  it('does not update catalog files when EVENTCATALOG_DISABLE_CHANNEL_MIGRATION is true', async () => {
+    process.env.EVENTCATALOG_DISABLE_CHANNEL_MIGRATION = 'true';
+
+    const servicePath = path.join(process.env.PROJECT_DIR!, 'services', 'InventoryService', 'index.mdx');
+    const messagePath = path.join(
+      process.env.PROJECT_DIR!,
+      'services',
+      'InventoryService',
+      'events',
+      'OrderAmended',
+      'index.mdx'
+    );
+
+    const serviceBeforeMigration = fs.readFileSync(servicePath, 'utf8');
+    const messageBeforeMigration = fs.readFileSync(messagePath, 'utf8');
+
+    const result = await messageChannelsToServiceChannels();
+
+    expect(result).toEqual({
+      status: 'skipped',
+      message: 'Channel migration disabled by EVENTCATALOG_DISABLE_CHANNEL_MIGRATION',
+    });
+    expect(fs.readFileSync(servicePath, 'utf8')).toBe(serviceBeforeMigration);
+    expect(fs.readFileSync(messagePath, 'utf8')).toBe(messageBeforeMigration);
+  });
+
+  it('if messages are found in the catalog that use channels, the migration script will move the channel configuration to the service that sends (to) or receives (from) the message', async () => {
+    await messageChannelsToServiceChannels();
+
+    const inventoryServiceFile = fs.readFileSync(
+      path.join(process.env.PROJECT_DIR!, 'services', 'InventoryService', 'index.mdx'),
+      'utf8'
+    );
+    const { data: inventoryServiceData } = matter(inventoryServiceFile);
+
+    const orderServiceFile = fs.readFileSync(
+      path.join(process.env.PROJECT_DIR!, 'domains', 'Orders', 'services', 'OrderService', 'index.mdx'),
+      'utf8'
+    );
+    const { data: orderServiceData } = matter(orderServiceFile);
+
+    expect(orderServiceData.receives[0].from).toEqual([{ id: 'eventbus', version: '1.0.0' }]);
+    expect(orderServiceData.sends[0].to).toEqual([{ id: 'eventbus', version: '1.0.0' }]);
+
+    expect(inventoryServiceData.receives[0].from).toEqual([{ id: 'eventbus', version: '1.0.0' }]);
+    expect(inventoryServiceData.sends[0].to).toEqual([{ id: 'eventbus', version: '1.0.0' }]);
+  });
+
+  it('if messages are found in the catalog that use channels, the migration script will remove the channels from the message', async () => {
+    // Before
+    const messageBeforeMigration = fs.readFileSync(
+      path.join(process.env.PROJECT_DIR!, 'services', 'InventoryService', 'events', 'OrderAmended', 'index.mdx'),
+      'utf8'
+    );
+    const { data: beforeData } = matter(messageBeforeMigration);
+    expect(beforeData.channels).toBeDefined();
+
+    await messageChannelsToServiceChannels();
+
+    const messageAfterMigration = fs.readFileSync(
+      path.join(process.env.PROJECT_DIR!, 'services', 'InventoryService', 'events', 'OrderAmended', 'index.mdx'),
+      'utf8'
+    );
+    const { data: afterData } = matter(messageAfterMigration);
+    expect(afterData.channels).toBeUndefined();
+  });
+
+  it('preserves sends entries whose messages have no channels (e.g. queries) when other sends match messages-with-channels', async () => {
+    await messageChannelsToServiceChannels();
+
+    const mixedServiceFile = fs.readFileSync(
+      path.join(process.env.PROJECT_DIR!, 'services', 'MixedSendsService', 'index.mdx'),
+      'utf8'
+    );
+    const { data } = matter(mixedServiceFile);
+
+    expect(data.sends).toHaveLength(2);
+
+    const orderAmended = data.sends.find((s: any) => s.id === 'OrderAmended');
+    expect(orderAmended).toBeDefined();
+    expect(orderAmended.to).toEqual([{ id: 'eventbus', version: '1.0.0' }]);
+
+    const getInventoryItem = data.sends.find((s: any) => s.id === 'GetInventoryItem');
+    expect(getInventoryItem).toBeDefined();
+    expect(getInventoryItem.version).toBe('1.0.0');
+  });
+
+  it('if messages have multiple channels defined, the migration script will move the channel configuration to the service that sends (to) or receives (from) the message', async () => {
+    await messageChannelsToServiceChannels();
+
+    const multiChannelServiceFile = fs.readFileSync(
+      path.join(process.env.PROJECT_DIR!, 'services', 'MultiChannelService', 'index.mdx'),
+      'utf8'
+    );
+    const { data: multiChannelServiceData } = matter(multiChannelServiceFile);
+
+    expect(multiChannelServiceData.sends[0].to).toEqual([
+      { id: 'eventbus', version: '1.0.0' },
+      { id: 'http-channel', version: '1.0.0' },
+    ]);
+  });
+});
diff --git a/src/__tests__/resolve-catalog-dependencies.spec.ts b/packages/core/src/__tests__/resolve-catalog-dependencies.spec.ts
similarity index 100%
rename from src/__tests__/resolve-catalog-dependencies.spec.ts
rename to packages/core/src/__tests__/resolve-catalog-dependencies.spec.ts
diff --git a/packages/core/src/__tests__/search-indexer.spec.ts b/packages/core/src/__tests__/search-indexer.spec.ts
new file mode 100644
index 000000000..0610ded07
--- /dev/null
+++ b/packages/core/src/__tests__/search-indexer.spec.ts
@@ -0,0 +1,210 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import type { Config } from '../eventcatalog.config';
+import { collectSearchRecords, markdownToSearchText } from '../search-indexer';
+
+const config = {
+  title: 'Test catalog',
+  tagline: false,
+  organizationName: 'EventCatalog',
+  homepageLink: 'https://eventcatalog.dev',
+  editUrl: '',
+  docs: { sidebar: {} },
+} as Config;
+
+let tempDirs: string[] = [];
+
+const createTempCatalog = async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'eventcatalog-search-'));
+  tempDirs.push(dir);
+  return dir;
+};
+
+afterEach(async () => {
+  await Promise.all(tempDirs.map((dir) => fs.rm(dir, { recursive: true, force: true })));
+  tempDirs = [];
+});
+
+describe('markdownToSearchText', () => {
+  it('extracts useful prose from Markdown and MDX without rendering components', () => {
+    const text = markdownToSearchText(`
+import Thing from './Thing.astro';
+
+# Order Processing
+
+<Tile title="Order support" description="Troubleshoot order failures" />
+
+Read [[service|OrdersService]] and [the guide](/docs/custom/guide).
+`);
+
+    expect(text).toContain('Order Processing');
+    expect(text).toContain('Order support');
+    expect(text).toContain('Troubleshoot order failures');
+    expect(text).toContain('OrdersService');
+    expect(text).toContain('the guide');
+    expect(text).not.toContain('import Thing');
+  });
+});
+
+describe('collectSearchRecords', () => {
+  it('indexes resource pages from source Markdown', async () => {
+    const projectDir = await createTempCatalog();
+    await fs.mkdir(path.join(projectDir, 'services', 'OrdersService'), { recursive: true });
+    await fs.writeFile(
+      path.join(projectDir, 'services', 'OrdersService', 'index.mdx'),
+      `---
+id: OrdersService
+name: Orders Service
+version: 1.0.0
+summary: Handles customer orders.
+owners:
+  - platform
+---
+
+Creates and tracks customer orders.
+`
+    );
+
+    const records = await collectSearchRecords({ projectDir, config });
+
+    expect(records).toHaveLength(1);
+    expect(records[0]).toMatchObject({
+      url: '/docs/services/OrdersService/1.0.0',
+      title: 'Orders Service',
+      type: 'Service',
+      collection: 'services',
+      id: 'OrdersService',
+      version: '1.0.0',
+      summary: 'Handles customer orders.',
+    });
+    expect(records[0].content).toContain('Creates and tracks customer orders');
+    expect(records[0].content).toContain('platform');
+  });
+
+  it('does not index draft resources when draft is configured with a message', async () => {
+    const projectDir = await createTempCatalog();
+    await fs.mkdir(path.join(projectDir, 'services', 'DraftService'), { recursive: true });
+    await fs.writeFile(
+      path.join(projectDir, 'services', 'DraftService', 'index.mdx'),
+      `---
+id: DraftService
+name: Draft Service
+version: 1.0.0
+draft:
+  message: Not ready yet.
+---
+
+This should not be searchable.
+`
+    );
+
+    const records = await collectSearchRecords({ projectDir, config });
+
+    expect(records).toHaveLength(0);
+  });
+
+  it('indexes custom docs under /docs/custom', async () => {
+    const projectDir = await createTempCatalog();
+    await fs.mkdir(path.join(projectDir, 'docs', 'runbooks'), { recursive: true });
+    await fs.writeFile(
+      path.join(projectDir, 'docs', 'runbooks', 'orders.mdx'),
+      `---
+title: Orders Runbook
+summary: Operational guide for orders.
+---
+
+Restart the order processor when the queue stalls.
+`
+    );
+
+    const records = await collectSearchRecords({ projectDir, config });
+
+    expect(records).toHaveLength(1);
+    expect(records[0]).toMatchObject({
+      url: '/docs/custom/runbooks/orders',
+      title: 'Orders Runbook',
+      type: 'Custom Doc',
+      collection: 'custom-docs',
+      id: 'runbooks/orders',
+    });
+  });
+
+  it('indexes resource docs against their owning resource URL space', async () => {
+    const projectDir = await createTempCatalog();
+    await fs.mkdir(path.join(projectDir, 'domains', 'Commerce', 'docs', 'adrs'), { recursive: true });
+    await fs.writeFile(
+      path.join(projectDir, 'domains', 'Commerce', 'index.mdx'),
+      `---
+id: Commerce
+name: Commerce
+version: 2.0.0
+summary: Commerce domain.
+---
+
+Commerce overview.
+`
+    );
+    await fs.writeFile(
+      path.join(projectDir, 'domains', 'Commerce', 'docs', 'adrs', '01-events.md'),
+      `---
+title: Use Events
+summary: Why the domain uses events.
+---
+
+Events decouple services.
+`
+    );
+
+    const records = await collectSearchRecords({ projectDir, config });
+    const doc = records.find((record) => record.type === 'Resource Doc');
+
+    expect(doc).toMatchObject({
+      url: '/docs/domains/Commerce/2.0.0/adrs/events',
+      title: 'Use Events',
+      type: 'Resource Doc',
+      collection: 'adrs',
+      id: 'events',
+      version: '2.0.0',
+    });
+  });
+
+  it('indexes resource docs under versioned resource folders with the versioned URL', async () => {
+    const projectDir = await createTempCatalog();
+    await fs.mkdir(path.join(projectDir, 'events', 'OrderCreated', 'versioned', '1.2.0', 'docs', 'guides'), { recursive: true });
+    await fs.writeFile(
+      path.join(projectDir, 'events', 'OrderCreated', 'versioned', '1.2.0', 'index.mdx'),
+      `---
+id: OrderCreated
+name: Order Created
+version: 1.2.0
+summary: Published when an order is created.
+---
+
+Order created overview.
+`
+    );
+    await fs.writeFile(
+      path.join(projectDir, 'events', 'OrderCreated', 'versioned', '1.2.0', 'docs', 'guides', '01-consuming.md'),
+      `---
+title: Consuming Order Created
+---
+
+Use this event to trigger fulfilment.
+`
+    );
+
+    const records = await collectSearchRecords({ projectDir, config });
+    const doc = records.find((record) => record.type === 'Resource Doc');
+
+    expect(doc).toMatchObject({
+      url: '/docs/events/OrderCreated/1.2.0/guides/consuming',
+      title: 'Consuming Order Created',
+      type: 'Resource Doc',
+      collection: 'guides',
+      id: 'consuming',
+      version: '1.2.0',
+    });
+  });
+});
diff --git a/packages/core/src/analytics/analytics.js b/packages/core/src/analytics/analytics.js
new file mode 100644
index 000000000..7564cc45e
--- /dev/null
+++ b/packages/core/src/analytics/analytics.js
@@ -0,0 +1,38 @@
+import os from 'os';
+import { VERSION } from '../constants';
+
+async function raiseEvent(eventData) {
+  const url = 'https://queue.simpleanalyticscdn.com/events';
+  const userAgent = `@eventcatalog/eventcatalog@${VERSION} (${os.platform()}; ${os.arch()}; Node/${process.version})`;
+  const headers = {
+    'Content-Type': 'application/json',
+  };
+
+  const payload = {
+    type: 'event',
+    hostname: 'eventcatalog.dev',
+    event: '@eventcatalog/eventcatalog',
+    metadata: {
+      ...eventData,
+      t: `t;${new Date().toISOString()}`,
+      ua: userAgent,
+    },
+    ua: userAgent,
+  };
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to raise analytics event: ${response.status}`);
+    }
+  } catch (error) {
+    // swallow the error
+  }
+}
+
+export { raiseEvent };
diff --git a/packages/core/src/analytics/count-resources.js b/packages/core/src/analytics/count-resources.js
new file mode 100644
index 000000000..03e21e8fb
--- /dev/null
+++ b/packages/core/src/analytics/count-resources.js
@@ -0,0 +1,61 @@
+import { glob } from 'glob';
+
+const RESOURCE_PATTERNS = {
+  adrs: ['**/adrs/*/index.@(md|mdx)'],
+  agents: ['**/agents/*/index.@(md|mdx)'],
+  events: ['**/events/*/index.@(md|mdx)'],
+  commands: ['**/commands/*/index.@(md|mdx)'],
+  queries: ['**/queries/*/index.@(md|mdx)'],
+  services: ['**/services/*/index.@(md|mdx)'],
+  domains: ['domains/*/index.@(md|mdx)', 'domains/*/subdomains/*/index.@(md|mdx)'],
+  flows: ['**/flows/*/index.@(md|mdx)'],
+  channels: ['**/channels/**/index.@(md|mdx)'],
+  entities: ['**/entities/*/index.@(md|mdx)'],
+  containers: ['**/containers/**/index.@(md|mdx)'],
+  'data-products': ['**/data-products/*/index.@(md|mdx)'],
+  teams: ['teams/*.@(md|mdx)'],
+  users: ['users/*.@(md|mdx)'],
+  designs: ['**/*.ecstudio'],
+  diagrams: ['**/diagrams/**/index.@(md|mdx)'],
+  ubiquitousLanguages: ['domains/*/ubiquitous-language.@(md|mdx)', 'domains/*/subdomains/*/ubiquitous-language.@(md|mdx)'],
+};
+
+const CUSTOM_ROUTE_PATTERNS = {
+  customPages: ['pages/**/*.astro'],
+  customApis: ['pages/**/*.@(ts|js|mjs)'],
+};
+
+const DEFAULT_IGNORES = ['**/versioned/**', '**/dist/**', '**/node_modules/**'];
+const CUSTOM_ROUTE_IGNORES = [...DEFAULT_IGNORES, 'pages/**/_*/**', 'pages/**/_*'];
+
+/**
+ * Count resources in the catalog directory using glob patterns
+ * @param {string} projectDir - Path to the catalog directory
+ * @returns {Promise<Record<string, number>>} - Object with resource type counts
+ */
+export async function countResources(projectDir) {
+  const counts = {};
+  for (const [type, patterns] of Object.entries({ ...RESOURCE_PATTERNS, ...CUSTOM_ROUTE_PATTERNS })) {
+    let total = 0;
+    for (const pattern of patterns) {
+      const files = await glob(pattern, {
+        cwd: projectDir,
+        ignore: type in CUSTOM_ROUTE_PATTERNS ? CUSTOM_ROUTE_IGNORES : DEFAULT_IGNORES,
+      });
+      total += files.length;
+    }
+    counts[type] = total;
+  }
+  return counts;
+}
+
+/**
+ * Serialize resource counts to a string for telemetry
+ * @param {Record<string, number>} counts - Object with resource type counts
+ * @returns {string} - Serialized string like "events:26,commands:11,..."
+ */
+export function serializeCounts(counts) {
+  return Object.entries(counts)
+    .map(([k, v]) => `${k}:${v}`)
+    .join(',');
+}
diff --git a/packages/core/src/analytics/log-build.js b/packages/core/src/analytics/log-build.js
new file mode 100644
index 000000000..fc4a7e50e
--- /dev/null
+++ b/packages/core/src/analytics/log-build.js
@@ -0,0 +1,133 @@
+import { getEventCatalogConfigFile, verifyRequiredFieldsAreInCatalogConfigFile } from '../eventcatalog-config-file-utils.js';
+import { raiseEvent } from './analytics.js';
+import { countResources, serializeCounts } from './count-resources.js';
+
+const getFeatures = async (configFile) => {
+  return {
+    llmsTxt: configFile.llmsTxt?.enabled || false,
+    rss: configFile.rss?.enabled || false,
+    chat: configFile.chat?.enabled || false,
+    changelog: configFile.changelog?.enabled || false,
+    auth: configFile.auth?.enabled || false,
+    environments: Array.isArray(configFile.environments) && configFile.environments.length > 0,
+    output: configFile.output || 'static',
+  };
+};
+
+const getDirectoryProvider = (source) => {
+  if (!source?.name || typeof source.name !== 'string') return 'unknown';
+  return source.name.split(':')[0] || 'unknown';
+};
+
+const serializeDirectorySources = (configFile) => {
+  const sources = configFile.directory?.sources;
+  if (!Array.isArray(sources) || sources.length === 0) return 'none';
+
+  const providerCounts = sources.reduce((counts, source) => {
+    const provider = getDirectoryProvider(source);
+    counts[provider] = (counts[provider] || 0) + 1;
+    return counts;
+  }, {});
+
+  const providers = Object.keys(providerCounts)
+    .sort()
+    .map((provider) => `${provider}:${providerCounts[provider]}`)
+    .join(',');
+
+  const hasUsers = sources.some((source) => typeof source?.loadUsers === 'function');
+  const hasTeams = sources.some((source) => typeof source?.loadTeams === 'function');
+
+  return `sources:${sources.length},providers:${providers},users:${hasUsers},teams:${hasTeams}`;
+};
+
+const CLOUD_ANALYTICS_ENDPOINT = 'https://api.ecingest.dev/v1/analytics/ingest';
+
+const toCloudResourceCounts = (counts) => ({
+  adrs: counts.adrs || 0,
+  agents: counts.agents || 0,
+  domains: counts.domains || 0,
+  services: counts.services || 0,
+  events: counts.events || 0,
+  commands: counts.commands || 0,
+  queries: counts.queries || 0,
+  flows: counts.flows || 0,
+  channels: counts.channels || 0,
+  entities: counts.entities || 0,
+  containers: counts.containers || 0,
+  dataProducts: counts['data-products'] || 0,
+  teams: counts.teams || 0,
+  users: counts.users || 0,
+  designs: counts.designs || 0,
+  diagrams: counts.diagrams || 0,
+  ubiquitousLanguages: counts.ubiquitousLanguages || 0,
+  customPages: counts.customPages || 0,
+  customApis: counts.customApis || 0,
+});
+
+const reportCloudResourceInventory = async (configFile, resourceCounts) => {
+  const analytics = configFile.cloud?.analytics;
+  if (!analytics?.enabled || !analytics.trackingId || !analytics.writeKey) return;
+
+  const endpoint = analytics.endpoint || CLOUD_ANALYTICS_ENDPOINT;
+  await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-EventCatalog-Analytics-Key': analytics.writeKey,
+    },
+    body: JSON.stringify({
+      trackingId: analytics.trackingId,
+      event: 'catalog.resource_inventory_reported',
+      timestamp: new Date().toISOString(),
+      counts: toCloudResourceCounts(resourceCounts),
+    }),
+  });
+};
+
+/**
+ *
+ * @param {string} projectDir
+ */
+const main = async (projectDir, { isEventCatalogStarterEnabled, isEventCatalogScaleEnabled, isBackstagePluginEnabled }) => {
+  // if (process.env.NODE_ENV === 'CI') return;
+  try {
+    await verifyRequiredFieldsAreInCatalogConfigFile(projectDir);
+    const configFile = await getEventCatalogConfigFile(projectDir);
+    const { cId, organizationName, generators = [] } = configFile;
+    let generatorNames = generators.length > 0 ? generators.map((generator) => generator[0]) : ['none'];
+
+    // Check if EventCatalog Pro is enabled
+    if (isEventCatalogStarterEnabled) {
+      generatorNames.push('@eventcatalog/eventcatalog-starter');
+    }
+
+    if (isEventCatalogScaleEnabled) {
+      generatorNames.push('@eventcatalog/eventcatalog-scale');
+    }
+
+    if (isBackstagePluginEnabled) {
+      generatorNames.push('@eventcatalog/backstage-plugin-eventcatalog');
+    }
+
+    const features = await getFeatures(configFile);
+    const resourceCounts = await countResources(projectDir);
+
+    await reportCloudResourceInventory(configFile, resourceCounts);
+
+    await raiseEvent({
+      command: 'build',
+      org: organizationName,
+      cId,
+      generators: generatorNames.toString(),
+      features: Object.keys(features)
+        .map((feature) => `${feature}:${features[feature]}`)
+        .join(','),
+      directorySources: serializeDirectorySources(configFile),
+      resources: serializeCounts(resourceCounts),
+    });
+  } catch (error) {
+    // Just swallow the error
+  }
+};
+
+export default main;
diff --git a/packages/core/src/catalog-to-astro-content-directory.js b/packages/core/src/catalog-to-astro-content-directory.js
new file mode 100644
index 000000000..4bef33022
--- /dev/null
+++ b/packages/core/src/catalog-to-astro-content-directory.js
@@ -0,0 +1,94 @@
+import { glob } from 'glob';
+import * as path from 'node:path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import os from 'node:os';
+import { verifyRequiredFieldsAreInCatalogConfigFile } from './eventcatalog-config-file-utils.js';
+import { mapCatalogToAstro } from './map-catalog-to-astro.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const rootPkg = path.resolve(path.dirname(__filename), '../');
+
+const copyFiles = async (source, target) => {
+  const files = await glob(path.join(source, '**'), {
+    nodir: true,
+    windowsPathsNoEscape: os.platform() == 'win32',
+    ignore: ['node_modules/**', '**/dist/**', '**/teams', '**/users', '**/*.mdx', '**/*.md', '**/package.json', '**/Dockerfile'],
+  });
+
+  // Custom snippets
+  const snippets = await glob(path.join(source, 'snippets/**/*.mdx'), {
+    nodir: true,
+    windowsPathsNoEscape: os.platform() == 'win32',
+  });
+
+  if (snippets.length > 0) {
+    files.push(...snippets);
+  }
+
+  // If we have .env file, copy it to the target
+  if (fs.existsSync(path.join(source, '.env'))) {
+    files.push(path.join(source, '.env'));
+  }
+
+  for (const file of files) {
+    mapCatalogToAstro({
+      filePath: file,
+      astroDir: target,
+      projectDir: source,
+    }).map((astroPath) => {
+      fs.cpSync(file, astroPath);
+      return { oldPath: file, newPath: astroPath };
+    });
+  }
+};
+
+const clearCustomPages = async (target) => {
+  const customPagesDir = path.join(target, 'src', 'custom-pages');
+  if (fs.existsSync(customPagesDir)) fs.rmSync(customPagesDir, { recursive: true });
+
+  // Older versions copied pages/ code files (e.g. homepage.astro) into public/generated,
+  // serving their source as static assets. Clean up any stale copies.
+  const staleCodeFiles = await glob(path.join(target, 'public', 'generated', 'pages', '**/*.{astro,ts,js,mjs}'), {
+    nodir: true,
+    windowsPathsNoEscape: os.platform() == 'win32',
+  });
+
+  for (const file of staleCodeFiles) {
+    fs.rmSync(file);
+  }
+};
+
+const removeGeneratedLikeC4Sources = async (target) => {
+  const generatedDir = path.join(target, 'public', 'generated');
+  const files = await glob(path.join(generatedDir, '**/*.{c4,likec4}'), {
+    nodir: true,
+    windowsPathsNoEscape: os.platform() == 'win32',
+  });
+
+  for (const file of files) {
+    fs.rmSync(file);
+  }
+};
+
+export const catalogToAstro = async (source, astroDir) => {
+  const astroContentDir = path.join(astroDir, 'src/content/');
+
+  // Clear the astro directory before we copy files over
+  if (fs.existsSync(astroContentDir)) fs.rmSync(astroContentDir, { recursive: true });
+
+  // Create the folder again
+  fs.mkdirSync(astroContentDir);
+
+  // Verify required fields are in the catalog config file
+  await verifyRequiredFieldsAreInCatalogConfigFile(source);
+
+  // If there is no eventcatalog.styles.css file, create one
+  if (!fs.existsSync(path.join(source, 'eventcatalog.styles.css'))) {
+    fs.writeFileSync(path.join(source, 'eventcatalog.styles.css'), '');
+  }
+
+  await clearCustomPages(astroDir);
+  await removeGeneratedLikeC4Sources(astroDir);
+  await copyFiles(source, astroDir);
+};
diff --git a/src/constants.ts b/packages/core/src/constants.ts
similarity index 100%
rename from src/constants.ts
rename to packages/core/src/constants.ts
diff --git a/packages/core/src/core-node-modules.ts b/packages/core/src/core-node-modules.ts
new file mode 100644
index 000000000..0b0c842b5
--- /dev/null
+++ b/packages/core/src/core-node-modules.ts
@@ -0,0 +1,91 @@
+import fs from 'fs';
+import path from 'node:path';
+
+const isDirectory = (directory: string) => {
+  try {
+    return fs.statSync(directory).isDirectory();
+  } catch (error) {
+    return false;
+  }
+};
+
+const hasAstroDependency = (nodeModulesDirectory: string) => {
+  const astroBin = process.platform === 'win32' ? 'astro.cmd' : 'astro';
+
+  return (
+    fs.existsSync(path.join(nodeModulesDirectory, 'astro', 'package.json')) ||
+    fs.existsSync(path.join(nodeModulesDirectory, '.bin', astroBin))
+  );
+};
+
+const isSymbolicLink = (targetPath: string) => {
+  try {
+    return fs.lstatSync(targetPath).isSymbolicLink();
+  } catch (error) {
+    return false;
+  }
+};
+
+const isSameDirectory = (a: string, b: string) => {
+  try {
+    return fs.realpathSync.native(a) === fs.realpathSync.native(b);
+  } catch (error) {
+    return false;
+  }
+};
+
+export const resolveInstalledCoreNodeModules = (currentDir: string) => {
+  const candidates: string[] = [];
+  const seen = new Set<string>();
+
+  const addCandidate = (candidate: string) => {
+    const resolvedCandidate = path.resolve(candidate);
+    if (!seen.has(resolvedCandidate)) {
+      candidates.push(resolvedCandidate);
+      seen.add(resolvedCandidate);
+    }
+  };
+
+  addCandidate(path.resolve(currentDir, '..', 'node_modules'));
+
+  let directory = path.resolve(currentDir);
+
+  while (true) {
+    if (path.basename(directory) === 'node_modules') {
+      addCandidate(directory);
+    }
+
+    addCandidate(path.join(directory, 'node_modules'));
+
+    const parentDirectory = path.dirname(directory);
+    if (parentDirectory === directory) {
+      break;
+    }
+
+    directory = parentDirectory;
+  }
+
+  return candidates.find((candidate) => isDirectory(candidate) && hasAstroDependency(candidate)) ?? candidates.find(isDirectory);
+};
+
+export const linkCoreNodeModules = ({
+  coreNodeModules,
+  installedCoreNodeModules,
+}: {
+  coreNodeModules: string;
+  installedCoreNodeModules?: string;
+}) => {
+  if (!installedCoreNodeModules) return;
+
+  if (isSymbolicLink(coreNodeModules)) {
+    if (isSameDirectory(coreNodeModules, installedCoreNodeModules)) {
+      return;
+    }
+
+    fs.unlinkSync(coreNodeModules);
+  } else if (fs.existsSync(coreNodeModules)) {
+    return;
+  }
+
+  fs.symlinkSync(installedCoreNodeModules, coreNodeModules, process.platform === 'win32' ? 'junction' : 'dir');
+};
diff --git a/packages/core/src/eventcatalog-config-file-utils.js b/packages/core/src/eventcatalog-config-file-utils.js
new file mode 100644
index 000000000..16f221f4a
--- /dev/null
+++ b/packages/core/src/eventcatalog-config-file-utils.js
@@ -0,0 +1,141 @@
+import { readFile, writeFile, rm, copyFile, mkdtemp, symlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { v4 as uuidV4 } from 'uuid';
+import { pathToFileURL } from 'url';
+import { tmpdir } from 'node:os';
+import matter from 'gray-matter';
+
+export async function cleanup(projectDirectory) {
+  const filePath = path.join(projectDirectory, 'eventcatalog.config.mjs');
+  if (existsSync(filePath)) {
+    await rm(filePath);
+  }
+}
+
+const findNodeModulesDirectory = (directory) => {
+  let currentDirectory = directory;
+
+  while (true) {
+    const nodeModulesDirectory = path.join(currentDirectory, 'node_modules');
+
+    if (existsSync(nodeModulesDirectory)) {
+      return nodeModulesDirectory;
+    }
+
+    const parentDirectory = path.dirname(currentDirectory);
+
+    if (parentDirectory === currentDirectory) {
+      return undefined;
+    }
+
+    currentDirectory = parentDirectory;
+  }
+};
+
+const linkNodeModulesIntoTempDirectory = async ({ projectDirectory, tempDir }) => {
+  const nodeModulesDirectory = findNodeModulesDirectory(projectDirectory);
+
+  if (!nodeModulesDirectory) {
+    return;
+  }
+
+  await symlink(nodeModulesDirectory, path.join(tempDir, 'node_modules'), 'dir');
+};
+
+const createTemporaryConfigDirectory = async (projectDirectory) => {
+  const nodeModulesDirectory = findNodeModulesDirectory(projectDirectory);
+
+  if (nodeModulesDirectory) {
+    return mkdtemp(path.join(nodeModulesDirectory, '.eventcatalog-config-'));
+  }
+
+  const tempDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-config-'));
+  await linkNodeModulesIntoTempDirectory({ projectDirectory, tempDir });
+  return tempDir;
+};
+
+export const getEventCatalogConfigFile = async (projectDirectory) => {
+  let tempDir;
+
+  try {
+    let configFilePath = path.join(projectDirectory, 'eventcatalog.config.js');
+
+    const filePath = path.join(projectDirectory, 'package.json');
+    const packageJson = JSON.parse(await readFile(filePath, 'utf-8'));
+
+    if (packageJson?.type !== 'module') {
+      // Importing CommonJS config via ESM import requires an .mjs file.
+      // Keep this temp copy outside the project directory so Astro/Vite
+      // file watchers do not trigger a dev-server restart during startup.
+      tempDir = await createTemporaryConfigDirectory(projectDirectory);
+      configFilePath = path.join(tempDir, 'eventcatalog.config.mjs');
+      await copyFile(path.join(projectDirectory, 'eventcatalog.config.js'), configFilePath);
+    }
+
+    const configFileURL = `${pathToFileURL(configFilePath).href}?t=${Date.now()}`;
+    const config = await import(/* @vite-ignore */ configFileURL);
+
+    return config.default;
+  } finally {
+    await cleanup(projectDirectory);
+
+    if (tempDir) {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  }
+};
+
+export const writeEventCatalogConfigFile = async (projectDirectory, newConfig) => {
+  try {
+    const configFilePath = path.join(projectDirectory, 'eventcatalog.config.js');
+    let content = await readFile(configFilePath, 'utf8');
+
+    // Find the start of the config object
+    const startIndex = content.indexOf('export default {');
+    if (startIndex === -1) {
+      // Just fail silently if the config object is not found
+      return;
+    }
+
+    // Update or add each new config item
+    Object.entries(newConfig).forEach(([key, value]) => {
+      const valueString = JSON.stringify(value, null, 2).replace(/"/g, "'").replace(/\n/g, '\n  ');
+
+      // Check if the key already exists
+      const keyRegex = new RegExp(`(${key}\\s*:)([^,}]+)`, 'g');
+      if (content.match(keyRegex)) {
+        // Update existing key
+        content = content.replace(keyRegex, `$1 ${valueString}`);
+      } else {
+        // Add new key-value pair
+        const insertPosition = content.indexOf('{', startIndex) + 1;
+        content = content.slice(0, insertPosition) + `\n  ${key}: ${valueString},` + content.slice(insertPosition);
+      }
+    });
+
+    // Write the updated content back to the file
+    await writeFile(configFilePath, content);
+  } finally {
+    await cleanup(projectDirectory);
+  }
+};
+
+// Check the eventcatalog.config.js and add any missing required fields on it
+export const verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
+  try {
+    const config = await getEventCatalogConfigFile(projectDirectory);
+
+    if (!config.cId) {
+      await writeEventCatalogConfigFile(projectDirectory, { cId: uuidV4() });
+    }
+  } catch (error) {
+    // fail silently, it's overly important
+  }
+};
+
+export function addPropertyToFrontMatter(input, newProperty, newValue) {
+  const file = matter(input);
+
+  return matter.stringify(file.content, { ...file.data, [newProperty]: newValue });
+}
diff --git a/src/eventcatalog.auth.ts b/packages/core/src/eventcatalog.auth.ts
similarity index 100%
rename from src/eventcatalog.auth.ts
rename to packages/core/src/eventcatalog.auth.ts
diff --git a/packages/core/src/eventcatalog.config.ts b/packages/core/src/eventcatalog.config.ts
new file mode 100644
index 000000000..6aa57a06d
--- /dev/null
+++ b/packages/core/src/eventcatalog.config.ts
@@ -0,0 +1,396 @@
+type ResourceDependency = {
+  id: string;
+  version?: string;
+};
+
+type CustomSideBarItem = {
+  label: string;
+  slug: string;
+  items?: CustomSideBarItem[];
+};
+
+type ManualSideBarConfig = {
+  label: string;
+  badge?: {
+    text: string;
+    color: string;
+  };
+  collapsed?: boolean;
+  items: CustomSideBarItem[];
+};
+
+type AutoGeneratedSideBarConfig = {
+  label: string;
+  autogenerated: {
+    directory: string;
+  };
+  badge?: {
+    text: string;
+    color: string;
+  };
+  collapsed?: boolean;
+};
+
+type TableConfiguration = {
+  columns: {
+    [key: string]: {
+      visible?: boolean;
+      label?: string;
+    };
+  };
+};
+
+type PagesConfiguration = {
+  type: 'item' | 'group';
+  title: string;
+  icon?: string;
+  pages?: string[];
+};
+
+type NavigationPage = string | PagesConfiguration;
+
+type VerticalNavigationItemConfig = {
+  /**
+   * Built-in item ids include: home, docs, catalog, schemas, schema-insights,
+   * teams, users, settings, studio. Route ids such as /schemas/explorer are
+   * also supported for built-ins.
+   */
+  id: string;
+  label?: string;
+  /**
+   * Any icon exported by lucide-react, for example House, FileCode, BookOpen.
+   */
+  icon?: string;
+  /**
+   * Required for custom items. Built-in items provide their own href.
+   */
+  href?: string;
+  visible?: boolean;
+  /**
+   * One or more paths that should mark this item active. Defaults to exact href matching
+   * for custom items; built-in items provide their own active matching.
+   */
+  match?: string | string[];
+};
+
+type VerticalNavigationGroupConfig = {
+  id: string;
+  label?: string;
+  visible?: boolean;
+  /**
+   * Defaults to top. Use bottom for settings-style groups anchored below the main nav.
+   */
+  position?: 'top' | 'bottom';
+  items?: VerticalNavigationItemConfig[];
+};
+
+type GeneratorConfig = string | Record<string, unknown> | [string, Record<string, unknown>];
+
+type DirectoryEntry = {
+  id: string;
+  markdown?: string;
+  [key: string]: unknown;
+};
+
+type DirectorySource = {
+  type: 'directory';
+  name: string;
+  loadUsers?: () => Promise<DirectoryEntry[]>;
+  loadTeams?: () => Promise<DirectoryEntry[]>;
+};
+
+type SchemaEntry = {
+  id: string;
+  name?: string;
+  format?: string;
+  content: string;
+  source: {
+    provider: string;
+    id?: string;
+    url?: string;
+    ref?: string;
+    path?: string;
+    [key: string]: unknown;
+  };
+};
+
+type SchemaSource = {
+  type: 'schemas';
+  name: string;
+  canResolve: (id: string) => boolean;
+  resolve: (id: string, context?: { messageFilePath?: string }) => Promise<SchemaEntry | undefined>;
+};
+
+type DirectoryConfig = {
+  /**
+   * External sources that sync users and teams into EventCatalog.
+   * Requires EventCatalog Scale.
+   */
+  sources?: DirectorySource[];
+  /**
+   * Controls what happens when a local Markdown user/team and an external source
+   * return the same id.
+   * @default 'local-wins'
+   */
+  conflictStrategy?: 'local-wins' | 'source-wins' | 'error';
+};
+
+type SchemaConfig = {
+  /**
+   * External sources that resolve message schema references into the generated schemas collection.
+   */
+  sources?: SchemaSource[];
+};
+
+type AuthConfig = {
+  enabled: boolean;
+};
+
+type McpAuthConfig = {
+  /**
+   * Require OAuth Bearer tokens for the built-in MCP server.
+   * EventCatalog acts as the MCP protected resource server; the
+   * configured authorization server remains responsible for login,
+   * consent, token issuance, and client registration.
+   */
+  enabled?: boolean;
+  /**
+   * Absolute URL for the MCP resource. Defaults to the request origin
+   * plus `/docs/mcp`, but production deployments behind proxies should
+   * set this explicitly.
+   */
+  resource?: string;
+  /**
+   * Optional absolute URL for the OAuth Protected Resource Metadata
+   * document. Defaults to `/.well-known/oauth-protected-resource`.
+   */
+  protectedResourceMetadataUrl?: string;
+  /** Authorization server issuer/base URLs advertised to MCP clients. */
+  authorizationServers?: string[];
+  /** Expected token issuer (`iss`). */
+  issuer?: string;
+  /** Expected token audience (`aud`). Defaults to `resource`. */
+  audience?: string | string[];
+  /** Scopes required to call the MCP server. */
+  requiredScopes?: string[];
+  /** JWKS endpoint used to validate asymmetric JWT access tokens. */
+  jwksUri?: string;
+  /** Inline public key for asymmetric JWT validation. */
+  publicKey?: string;
+  /** Environment variable containing the public key. */
+  publicKeyEnvVar?: string;
+  /** Inline shared secret for symmetric JWT validation. Prefer `sharedSecretEnvVar`. */
+  sharedSecret?: string;
+  /** Environment variable containing the shared secret. */
+  sharedSecretEnvVar?: string;
+};
+
+type McpConfig = {
+  auth?: McpAuthConfig;
+};
+
+type GA4Config = {
+  measurementId: string;
+};
+
+type GTMConfig = {
+  tagId: string;
+};
+
+type PostHogConfig = {
+  apiKey: string;
+  apiHost?: string;
+};
+
+type EventCatalogCloudAnalyticsConfig = {
+  enabled: boolean;
+  trackingId: string;
+  writeKey?: string;
+  endpoint?: string;
+  debug?: boolean;
+};
+
+type EventCatalogCloudConfig = {
+  analytics?: EventCatalogCloudAnalyticsConfig;
+};
+
+type IntegrationsConfig = {
+  ga4?: GA4Config;
+  gtm?: GTMConfig;
+  posthog?: PostHogConfig;
+  /** Log all analytics events to the browser console */
+  debug?: boolean;
+};
+
+type CatalogTheme = 'default' | 'ocean' | 'sapphire' | 'sunset' | 'forest' | (string & {});
+
+// Any Scalar Configuration for the OpenAPI Component.
+type ScalarConfiguration = any;
+
+export interface Config {
+  cId: string;
+  title: string;
+  organizationName: string;
+  tagline?: string | false;
+  homepageLink?: string;
+  editUrl?: string;
+  repositoryUrl?: string;
+  landingPage?: string;
+  base?: string;
+  port?: string | number;
+  outDir?: string;
+  host?: string | boolean;
+  trailingSlash?: boolean;
+  output?: 'server' | 'static';
+  server?: {
+    allowedHosts?: string[] | true;
+  };
+  security?: {
+    checkOrigin?: boolean;
+  };
+  /**
+   * Theme for the catalog UI.
+   * - 'default': Default purple/slate theme
+   * - 'ocean': Deep blue/teal ocean-inspired theme
+   * - 'sapphire': Blue/violet theme
+   * - 'sunset': Orange/pink sunset-inspired theme
+   * - 'forest': Green forest-inspired theme
+   * @default 'default'
+   */
+  theme?: CatalogTheme;
+  auth?: AuthConfig;
+  mcp?: McpConfig;
+  rss?: {
+    enabled?: boolean;
+    limit?: number;
+  };
+  search?: {
+    /**
+     * - 'resource': Fast default search across catalog resources.
+     * - 'indexed': Opt-in full-content search index generated at build time.
+     * @default 'resource'
+     */
+    type?: 'resource' | 'indexed';
+  };
+  llmsTxt?: {
+    enabled: boolean;
+  };
+  logo?: {
+    alt: string;
+    src: string;
+    text?: string;
+  };
+  asyncAPI?: {
+    renderParsedSchemas?: boolean;
+    allowAnyEnvInSpecHeaders?: boolean;
+  };
+  mdxOptimize?: boolean;
+  compress?: boolean;
+  pages?: {
+    /**
+     * URL prefix that user-defined pages (pages/*.astro, pages/api/*.ts) are served under,
+     * e.g. pages/reports.astro is served at /custom/reports.
+     * @default 'custom'
+     */
+    prefix?: string;
+  };
+  navigation?: {
+    pages?: NavigationPage[];
+    /**
+     * Replaces the default vertical application navigation rail when provided.
+     * If omitted, EventCatalog renders the default navigation.
+     */
+    groups?: VerticalNavigationGroupConfig[];
+  };
+  docs?: {
+    sidebar: {
+      type?: 'TREE_VIEW' | 'LIST_VIEW';
+      showOrphanedMessages?: boolean;
+    };
+  };
+  dependencies?: {
+    agents?: ResourceDependency[];
+    commands?: ResourceDependency[];
+    events?: ResourceDependency[];
+    services?: ResourceDependency[];
+    domains?: ResourceDependency[];
+  };
+  directory?: DirectoryConfig;
+  schemas?: SchemaConfig;
+  mermaid?: {
+    maxTextSize?: number;
+    iconPacks?: string[];
+  };
+  chat?: {
+    enabled?: boolean;
+    provider?: 'openai' | 'anthropic' | 'google';
+    model?: string;
+    max_tokens?: number;
+    similarityResults?: number;
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+  };
+  customDocs?: {
+    sidebar?: (ManualSideBarConfig | AutoGeneratedSideBarConfig)[];
+  };
+  api?: {
+    /**
+     * Enable or disable the /api/catalog endpoint that dumps the entire catalog as JSON.
+     * Disabling this can significantly reduce memory usage during builds for large catalogs (1000+ files).
+     * @default true
+     */
+    fullCatalogAPIEnabled?: boolean;
+  };
+  changelog?: {
+    enabled: boolean;
+  };
+  visualiser?: {
+    enabled?: boolean;
+    channels?: {
+      renderMode?: 'flat' | 'single';
+    };
+  };
+  environments?: {
+    name: string;
+    url: string;
+    description?: string;
+    shortName?: string;
+  }[];
+  users?: {
+    tableConfiguration?: TableConfiguration;
+  };
+  teams?: {
+    tableConfiguration?: TableConfiguration;
+  };
+  events?: {
+    tableConfiguration?: TableConfiguration;
+  };
+  agents?: {
+    tableConfiguration?: TableConfiguration;
+  };
+  services?: {
+    tableConfiguration?: TableConfiguration;
+  };
+  domains?: {
+    tableConfiguration?: TableConfiguration;
+  };
+  flows?: {
+    tableConfiguration?: TableConfiguration;
+  };
+  containers?: {
+    tableConfiguration?: TableConfiguration;
+  };
+  commands?: {
+    tableConfiguration?: TableConfiguration;
+  };
+  queries?: {
+    tableConfiguration?: TableConfiguration;
+  };
+  cloud?: EventCatalogCloudConfig;
+  integrations?: IntegrationsConfig;
+  scalarConfiguration?: ScalarConfiguration;
+  generators?: GeneratorConfig[];
+}
diff --git a/packages/core/src/eventcatalog.ts b/packages/core/src/eventcatalog.ts
new file mode 100755
index 000000000..426c4e62b
--- /dev/null
+++ b/packages/core/src/eventcatalog.ts
@@ -0,0 +1,734 @@
+import { Command } from 'commander';
+import { execSync, spawn } from 'node:child_process';
+import { join } from 'node:path';
+import http from 'node:http';
+import fs from 'fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { generate } from './generate';
+import logBuild from './analytics/log-build';
+import { VERSION } from './constants';
+import { watch } from './watcher';
+import { catalogToAstro } from './catalog-to-astro-content-directory';
+import { getEventCatalogConfigFile, verifyRequiredFieldsAreInCatalogConfigFile } from './eventcatalog-config-file-utils.js';
+import resolveCatalogDependencies from './resolve-catalog-dependencies';
+import boxen from 'boxen';
+import { getProjectOutDir, isAuthEnabled, isIndexedSearchEnabled, isOutputServer } from './features';
+import updateNotifier from 'update-notifier';
+import dotenv from 'dotenv';
+import { runMigrations } from './migrations';
+import { logger } from './utils/cli-logger';
+import { buildFieldsIndex } from '../eventcatalog/src/enterprise/fields/field-indexer';
+import { buildSearchIndex } from './search-indexer';
+import { linkCoreNodeModules, resolveInstalledCoreNodeModules } from './core-node-modules';
+const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const program = new Command().version(VERSION);
+
+import { isEventCatalogStarterEnabled, isEventCatalogScaleEnabled, isFeatureEnabled } from '@eventcatalog/license';
+
+// The users dierctory
+const dir = path.resolve(process.env.PROJECT_DIR || process.cwd());
+
+// The tmp core directory
+const core = path.resolve(process.env.CATALOG_DIR || join(dir, '.eventcatalog-core'));
+
+// The project itself
+const eventCatalogDir = path.resolve(join(currentDir, '../eventcatalog/'));
+
+const getInstalledEventCatalogVersion = () => {
+  try {
+    const pkg = fs.readFileSync(join(dir, 'package.json'), 'utf8');
+    const json = JSON.parse(pkg);
+    return json.dependencies['@eventcatalog/core'];
+  } catch (error) {
+    return null;
+  }
+};
+
+program.name('eventcatalog').description('Documentation tool for event-driven architectures');
+
+const ensureDir = (dir: string) => {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir);
+  }
+};
+
+const resolveDevPort = async ({ projectDir }: { projectDir: string }): Promise<number> => {
+  try {
+    const config = await getEventCatalogConfigFile(projectDir);
+    const fromConfig = Number(config?.port);
+    if (Number.isFinite(fromConfig) && fromConfig > 0) return fromConfig;
+  } catch (error) {
+    // Ignore config-read errors and fall back to default
+  }
+
+  return 3000;
+};
+
+const startDevPrewarm = ({
+  port = 3000,
+  paths = ['/ping', '/'],
+  retries = 80,
+  intervalMs = 250,
+  initialDelayMs = 500,
+}: {
+  port?: number;
+  paths?: string[];
+  retries?: number;
+  intervalMs?: number;
+  initialDelayMs?: number;
+}) => {
+  let attempt = 0;
+
+  const hit = (requestPath: string) =>
+    new Promise<boolean>((resolve) => {
+      const req = http.get(
+        {
+          hostname: '127.0.0.1',
+          port,
+          path: requestPath,
+          timeout: 1200,
+        },
+        (res) => {
+          res.resume();
+          resolve(true);
+        }
+      );
+
+      req.on('error', () => resolve(false));
+      req.on('timeout', () => {
+        req.destroy();
+        resolve(false);
+      });
+    });
+
+  const tick = async () => {
+    attempt += 1;
+
+    for (const requestPath of paths) {
+      const ok = await hit(requestPath);
+      if (ok) {
+        return;
+      }
+    }
+
+    if (attempt < retries) {
+      setTimeout(tick, intervalMs);
+    }
+  };
+
+  setTimeout(tick, initialDelayMs);
+};
+
+const createAstroLineFilter = () => {
+  return (line: string) => {
+    return line.includes('[glob-loader]') || /The collection.*does not exist/.test(line);
+  };
+};
+
+const createAstroDevLineFilter = () => {
+  const shouldFilterAstroLine = createAstroLineFilter();
+
+  return (line: string) => {
+    return shouldFilterAstroLine(line) || line.includes('[router]');
+  };
+};
+
+const buildDevSearchIndex = async ({ config }: { config: Awaited<ReturnType<typeof getEventCatalogConfigFile>> }) => {
+  const result = await buildSearchIndex({
+    projectDir: dir,
+    outDir: path.join(core, 'public'),
+    searchOutputPath: path.join(core, 'public', 'pagefind'),
+    config,
+    isServer: false,
+  });
+
+  logger.info(`Indexed ${result.records} page(s) into ${path.relative(core, result.outputPath)}`, 'search');
+};
+
+const warnIfIndexedSearchUsesAuth = async () => {
+  if (!(await isAuthEnabled())) {
+    return;
+  }
+
+  logger.info(
+    'Indexed search creates client-readable search files. Make sure your deployment protects /pagefind assets if your catalog is private.',
+    'search'
+  );
+};
+
+const createDevSearchIndexWatcher = ({ config }: { config: Awaited<ReturnType<typeof getEventCatalogConfigFile>> }) => {
+  let timeout: NodeJS.Timeout | undefined;
+  let isBuilding = false;
+  let queued = false;
+
+  const run = async () => {
+    if (isBuilding) {
+      queued = true;
+      return;
+    }
+
+    isBuilding = true;
+    try {
+      await buildDevSearchIndex({ config });
+    } catch (err: any) {
+      logger.info(`Failed to rebuild indexed search: ${err.message}`, 'search');
+    } finally {
+      isBuilding = false;
+      if (queued) {
+        queued = false;
+        run();
+      }
+    }
+  };
+
+  return (_err: Error | null, events: { path: string; type: string }[]) => {
+    if (!events.some((event) => event.path.endsWith('.md') || event.path.endsWith('.mdx'))) {
+      return;
+    }
+
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+
+    timeout = setTimeout(run, 500);
+  };
+};
+
+const replaceAstroReadyVersionLine = (line: string) => {
+  const matches = line.match(/^(\s*)astro(\s+)v\S+(\s+ready.*)$/i);
+
+  if (!matches) {
+    return line;
+  }
+
+  return `${matches[1]}eventcatalog${matches[2]}v${VERSION}${matches[3]}`;
+};
+
+const runCommandWithFilteredOutput = async ({
+  command,
+  cwd,
+  env,
+  shouldFilterLine,
+  transformLine = (line) => line,
+}: {
+  command: string;
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  shouldFilterLine: (line: string) => boolean;
+  transformLine?: (line: string) => string;
+}) => {
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(command, {
+      cwd,
+      env: {
+        ...process.env,
+        ...env,
+      },
+      shell: true,
+      stdio: ['inherit', 'pipe', 'pipe'],
+    });
+
+    let stdoutBuffer = '';
+    let stderrBuffer = '';
+
+    const flush = (buffer: string, writer: NodeJS.WriteStream, isFinal = false) => {
+      const lines = buffer.split('\n');
+      const remaining = isFinal ? '' : (lines.pop() ?? '');
+
+      for (const rawLine of lines) {
+        const line = rawLine.replace(/\r/g, '');
+        if (line.length === 0) {
+          writer.write('\n');
+          continue;
+        }
+        if (!shouldFilterLine(line)) {
+          writer.write(`${transformLine(rawLine)}\n`);
+        }
+      }
+
+      return remaining;
+    };
+
+    child.stdout.on('data', (chunk: Buffer) => {
+      stdoutBuffer += chunk.toString();
+      stdoutBuffer = flush(stdoutBuffer, process.stdout);
+    });
+
+    child.stderr.on('data', (chunk: Buffer) => {
+      stderrBuffer += chunk.toString();
+      stderrBuffer = flush(stderrBuffer, process.stderr);
+    });
+
+    child.on('error', (error) => {
+      reject(error);
+    });
+
+    child.on('close', (code) => {
+      stdoutBuffer = flush(stdoutBuffer, process.stdout, true);
+      stderrBuffer = flush(stderrBuffer, process.stderr, true);
+
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`Command failed with exit code ${code}: ${command}`));
+    });
+  });
+};
+
+const copyCore = () => {
+  // make sure the core folder exists
+  ensureDir(core);
+
+  if (eventCatalogDir === core) {
+    // Still need to copy the .env file
+    // This is used for development purposes as it's not possible cp a dir to itself.
+    // Into development usually core is the root equals to eventCatalogDir.
+    return;
+  }
+
+  // Copy required eventcatlog files into users directory
+  fs.cpSync(eventCatalogDir, core, {
+    recursive: true,
+    filter: (src) => {
+      const relativePath = path.relative(eventCatalogDir, src);
+      const pathParts = relativePath.split(path.sep);
+
+      return !pathParts.some((part) => ['.astro', 'dist', 'node_modules'].includes(part));
+    },
+  });
+
+  const coreNodeModules = path.join(core, 'node_modules');
+  const installedCoreNodeModules = resolveInstalledCoreNodeModules(currentDir);
+
+  linkCoreNodeModules({ coreNodeModules, installedCoreNodeModules });
+};
+
+const clearCore = () => {
+  if (fs.existsSync(core)) fs.rmSync(core, { recursive: true });
+};
+
+const checkForUpdate = () => {
+  const installedVersion = getInstalledEventCatalogVersion();
+
+  if (!installedVersion) return;
+
+  // Check if user is on version < 3 and notify about V3
+  const majorVersion = parseInt(installedVersion.replace(/[^0-9.]/g, '').split('.')[0], 10);
+  if (majorVersion < 3) {
+    const v3Message = `🚀 EventCatalog V3 is now available in beta!
+
+You are currently on version ${installedVersion}.
+V3 brings exciting new features and improvements.
+
+Upgrade now: npm i @eventcatalog/core@beta`;
+    console.log(
+      boxen(v3Message, {
+        padding: 1,
+        margin: 1,
+        align: 'center',
+        borderColor: 'magenta',
+        borderStyle: 'round',
+      })
+    );
+    return;
+  }
+
+  const pkg = { name: '@eventcatalog/core', version: installedVersion };
+  const notifier = updateNotifier({ pkg, updateCheckInterval: 0 });
+
+  if (notifier.update) {
+    const message = `EventCatalog update available ${notifier.update.current} → ${notifier.update.latest}
+Run npm i @eventcatalog/core to update`;
+
+    console.log(
+      boxen(message, {
+        padding: 1,
+        margin: 1,
+        align: 'center',
+        borderColor: 'yellow',
+        borderStyle: {
+          topLeft: ' ',
+          topRight: ' ',
+          bottomLeft: ' ',
+          bottomRight: ' ',
+          right: ' ',
+          top: '-',
+          bottom: '-',
+          left: ' ',
+        },
+      })
+    );
+  }
+};
+
+program
+  .command('dev')
+  .description('Run development server of EventCatalog')
+  .option('-d, --debug', 'Output EventCatalog application information into your terminal')
+  .option('--force-recreate', 'Recreate the eventcatalog-core directory', false)
+  .option('--no-prewarm', 'Disable automatic dev prewarm request')
+  .action(async (options, command: Command) => {
+    // // Copy EventCatalog core over
+    // // Copy EventCatalog core over
+    logger.welcome();
+    logger.info('Setting up EventCatalog...', 'eventcatalog');
+
+    const isServer = await isOutputServer();
+    logger.info(isServer ? 'EventCatalog is running in Server Mode' : 'EventCatalog is running in Static Mode', 'config');
+
+    // Load any .env file in the project directory
+    if (fs.existsSync(path.join(dir, '.env'))) {
+      dotenv.config({ path: path.join(dir, '.env') });
+    }
+
+    if (options.debug) {
+      logger.info('Debug mode enabled', 'debug');
+      logger.info(`PROJECT_DIR: ${dir}`, 'debug');
+      logger.info(`CATALOG_DIR: ${core}`, 'debug');
+    }
+
+    if (options.forceRecreate) clearCore();
+
+    // Verify required fields (e.g. cId) are in the config file before copying to .eventcatalog-core.
+    // This must happen before copyCore() so that the config is stable when Astro starts.
+    // Otherwise, writing the config after the server starts triggers a Vite config dependency
+    // change restart, which races with the initial dependency scan and floods the terminal with errors.
+    await verifyRequiredFieldsAreInCatalogConfigFile(dir);
+
+    copyCore();
+
+    await resolveCatalogDependencies(dir, core);
+
+    // Run any migrations for the catalog
+    await runMigrations(dir);
+
+    // Move files like public directory to the root of the eventcatalog-core directory
+    await catalogToAstro(dir, core);
+    const config = await getEventCatalogConfigFile(dir);
+
+    // Check if backstage is enabled
+    const canEmbedPages = await isFeatureEnabled(
+      '@eventcatalog/backstage-plugin-eventcatalog',
+      process.env.EVENTCATALOG_LICENSE_KEY_BACKSTAGE
+    );
+    const isEventCatalogStarter = await isEventCatalogStarterEnabled();
+    const isEventCatalogScale = await isEventCatalogScaleEnabled();
+
+    // Build fields index if running in SSR mode
+    if (isServer) {
+      try {
+        logger.info('Building fields index...', 'fields');
+        const { warnings } = await buildFieldsIndex(dir, core);
+        if (warnings.length > 0) {
+          logger.info(`Fields index built with ${warnings.length} warning(s)`, 'fields');
+        } else {
+          logger.info('Fields index built successfully', 'fields');
+        }
+      } catch (err: any) {
+        logger.info(`Failed to build fields index: ${err.message}`, 'fields');
+      }
+    }
+
+    const shouldBuildIndexedSearch = await isIndexedSearchEnabled();
+    if (shouldBuildIndexedSearch) {
+      await warnIfIndexedSearchUsesAuth();
+
+      logger.info('Building indexed search for local development...', 'search');
+      await buildDevSearchIndex({ config });
+    }
+
+    // is there an eventcatalog update to install?
+    checkForUpdate();
+
+    let watchUnsub;
+    try {
+      watchUnsub = await watch(dir, core, shouldBuildIndexedSearch ? createDevSearchIndexWatcher({ config }) : undefined);
+
+      const args = command.args.join(' ').trim();
+
+      if (options.prewarm) {
+        const prewarmPort = await resolveDevPort({
+          projectDir: dir,
+        });
+
+        startDevPrewarm({
+          port: prewarmPort,
+          paths: ['/ping', '/'],
+        });
+      }
+
+      await runCommandWithFilteredOutput({
+        command: `npx astro dev ${args}`,
+        cwd: core,
+        env: {
+          PROJECT_DIR: dir,
+          CATALOG_DIR: core,
+          ENABLE_EMBED: String(canEmbedPages || isEventCatalogScale),
+          EVENTCATALOG_STARTER: String(isEventCatalogStarter),
+          EVENTCATALOG_SCALE: String(isEventCatalogScale),
+          EVENTCATALOG_DEV_MODE: 'true',
+          IGNORE_BUILD_ARTIFACTS: 'true',
+          NODE_NO_WARNINGS: '1',
+        },
+        shouldFilterLine: createAstroDevLineFilter(),
+        transformLine: replaceAstroReadyVersionLine,
+      });
+    } catch (err) {
+      console.error(err);
+    } finally {
+      await watchUnsub?.();
+    }
+  });
+
+program
+  .command('build')
+  .description('Run build of EventCatalog')
+  .action(async (options, command: Command) => {
+    logger.welcome();
+    logger.info('Building EventCatalog...', 'build');
+
+    const isServer = await isOutputServer();
+
+    logger.info(isServer ? 'EventCatalog is running in Server Mode' : 'EventCatalog is running in Static Mode', 'config');
+
+    // Load any .env file in the project directory
+    if (fs.existsSync(path.join(dir, '.env'))) {
+      dotenv.config({ path: path.join(dir, '.env') });
+    }
+
+    // Verify required fields (e.g. cId) before copying to .eventcatalog-core
+    await verifyRequiredFieldsAreInCatalogConfigFile(dir);
+
+    copyCore();
+
+    // Check if backstage is enabled
+    const isBackstagePluginEnabled = await isFeatureEnabled(
+      '@eventcatalog/backstage-plugin-eventcatalog',
+      process.env.EVENTCATALOG_LICENSE_KEY_BACKSTAGE
+    );
+    const isEventCatalogStarter = await isEventCatalogStarterEnabled();
+    const isEventCatalogScale = await isEventCatalogScaleEnabled();
+
+    const canEmbedPages = isBackstagePluginEnabled || isEventCatalogScale;
+
+    await logBuild(dir, {
+      isEventCatalogStarterEnabled: isEventCatalogStarter,
+      isEventCatalogScaleEnabled: isEventCatalogScale,
+      isBackstagePluginEnabled: canEmbedPages || isEventCatalogScale,
+    });
+
+    await resolveCatalogDependencies(dir, core);
+
+    // Run any migrations for the catalog
+    await runMigrations(dir);
+
+    await catalogToAstro(dir, core);
+
+    // Build fields index if running in SSR mode
+    if (isServer) {
+      try {
+        logger.info('Building fields index...', 'fields');
+        const { warnings } = await buildFieldsIndex(dir, core);
+        if (warnings.length > 0) {
+          logger.info(`Fields index built with ${warnings.length} warning(s)`, 'fields');
+        } else {
+          logger.info('Fields index built successfully', 'fields');
+        }
+      } catch (err: any) {
+        logger.info(`Failed to build fields index: ${err.message}`, 'fields');
+      }
+    }
+
+    checkForUpdate();
+
+    const args = command.args.join(' ').trim();
+    await runCommandWithFilteredOutput({
+      command: `npx astro build ${args}`,
+      cwd: core,
+      env: {
+        PROJECT_DIR: dir,
+        CATALOG_DIR: core,
+        ENABLE_EMBED: String(canEmbedPages),
+        EVENTCATALOG_STARTER: String(isEventCatalogStarter),
+        EVENTCATALOG_SCALE: String(isEventCatalogScale),
+        IGNORE_BUILD_ARTIFACTS: 'true',
+      },
+      shouldFilterLine: createAstroLineFilter(),
+    });
+
+    if (await isIndexedSearchEnabled()) {
+      await warnIfIndexedSearchUsesAuth();
+
+      const config = await getEventCatalogConfigFile(dir);
+      const outDir = path.resolve(dir, await getProjectOutDir());
+
+      logger.info('Building indexed search...', 'search');
+      const result = await buildSearchIndex({
+        projectDir: dir,
+        outDir,
+        config,
+        isServer,
+      });
+      logger.info(`Indexed ${result.records} page(s) into ${path.relative(dir, result.outputPath)}`, 'search');
+    }
+  });
+
+const previewCatalog = ({
+  command,
+  canEmbedPages = false,
+  isEventCatalogStarter = false,
+  isEventCatalogScale = false,
+}: {
+  command: Command;
+  canEmbedPages: boolean;
+  isEventCatalogStarter: boolean;
+  isEventCatalogScale: boolean;
+}) => {
+  execSync(
+    `cross-env PROJECT_DIR='${dir}' CATALOG_DIR='${core}' ENABLE_EMBED=${canEmbedPages} EVENTCATALOG_STARTER=${isEventCatalogStarter} EVENTCATALOG_SCALE=${isEventCatalogScale} npx astro preview ${command.args.join(' ').trim()}`,
+    {
+      cwd: core,
+      stdio: 'inherit',
+    }
+  );
+};
+
+const startServerCatalog = ({
+  command,
+  canEmbedPages = false,
+  isEventCatalogStarter = false,
+  isEventCatalogScale = false,
+}: {
+  command: Command;
+  canEmbedPages: boolean;
+  isEventCatalogStarter: boolean;
+  isEventCatalogScale: boolean;
+}) => {
+  const serverEntryPath = path.join(dir, 'dist', 'server', 'entry.mjs');
+  execSync(
+    `cross-env PROJECT_DIR='${dir}' CATALOG_DIR='${core}' ENABLE_EMBED=${canEmbedPages} EVENTCATALOG_STARTER=${isEventCatalogStarter} EVENTCATALOG_SCALE=${isEventCatalogScale} node "${serverEntryPath}"`,
+    {
+      cwd: core,
+      stdio: 'inherit',
+    }
+  );
+};
+
+program
+  .command('preview')
+  .description('Serves the contents of your eventcatalog build directory')
+  .action(async (options, command: Command) => {
+    logger.welcome();
+    logger.info('Starting preview of your build...', 'preview');
+
+    // Load any .env file in the project directory
+    if (fs.existsSync(path.join(dir, '.env'))) {
+      dotenv.config({ path: path.join(dir, '.env') });
+    }
+
+    const canEmbedPages = await isFeatureEnabled(
+      '@eventcatalog/backstage-plugin-eventcatalog',
+      process.env.EVENTCATALOG_LICENSE_KEY_BACKSTAGE
+    );
+    const isEventCatalogStarter = await isEventCatalogStarterEnabled();
+    const isEventCatalogScale = await isEventCatalogScaleEnabled();
+
+    previewCatalog({ command, canEmbedPages: canEmbedPages || isEventCatalogScale, isEventCatalogStarter, isEventCatalogScale });
+  });
+
+program
+  .command('start')
+  .description('Serves the contents of your eventcatalog build directory')
+  .action(async (options, command: Command) => {
+    logger.welcome();
+    logger.info('Starting preview of your build...', 'preview');
+
+    // Load any .env file in the project directory
+    if (fs.existsSync(path.join(dir, '.env'))) {
+      dotenv.config({ path: path.join(dir, '.env') });
+    }
+
+    const canEmbedPages = await isFeatureEnabled(
+      '@eventcatalog/backstage-plugin-eventcatalog',
+      process.env.EVENTCATALOG_LICENSE_KEY_BACKSTAGE
+    );
+    const isEventCatalogStarter = await isEventCatalogStarterEnabled();
+    const isEventCatalogScale = await isEventCatalogScaleEnabled();
+
+    const isServerOutput = await isOutputServer();
+
+    if (isServerOutput) {
+      startServerCatalog({
+        command,
+        canEmbedPages: canEmbedPages || isEventCatalogScale,
+        isEventCatalogStarter,
+        isEventCatalogScale,
+      });
+    } else {
+      previewCatalog({
+        command,
+        canEmbedPages: canEmbedPages || isEventCatalogScale,
+        isEventCatalogStarter,
+        isEventCatalogScale,
+      });
+    }
+  });
+
+program
+  .command('export')
+  .description('Export your EventCatalog using the SDK dumpCatalog function')
+  .option('--include-markdown', 'Include markdown content in the export', false)
+  .action(async (options) => {
+    logger.welcome();
+    logger.info('Exporting EventCatalog...', 'export');
+
+    // Load any .env file in the project directory
+    if (fs.existsSync(path.join(dir, '.env'))) {
+      dotenv.config({ path: path.join(dir, '.env') });
+    }
+
+    const { default: initSDK } = await import('@eventcatalog/sdk');
+    const sdk = initSDK(dir);
+
+    const catalog = await sdk.dumpCatalog({ includeMarkdown: options.includeMarkdown });
+
+    const exportsDir = path.join(dir, 'exports');
+    ensureDir(exportsDir);
+
+    const date = new Date().toISOString().split('T')[0];
+    const exportFile = path.join(exportsDir, `catalog-${date}.json`);
+
+    fs.writeFileSync(exportFile, JSON.stringify(catalog, null, 2), 'utf-8');
+
+    logger.info(`Catalog exported to ${exportFile}`, 'export');
+  });
+
+program
+  .command('generate [siteDir]')
+  .description('Start the generator scripts.')
+  .action(async () => {
+    // Load any .env file in the project directory
+    if (fs.existsSync(path.join(dir, '.env'))) {
+      dotenv.config({ path: path.join(dir, '.env') });
+    }
+    await generate(dir);
+  });
+
+program.addHelpText(
+  'after',
+  `
+  Passing Extra Arguments:
+    Use the -- delimiter to forward arguments to the underlying process.
+    Example: npx eventcatalog dev --debug -- --env=production --port=3000
+  `
+);
+
+program
+  .parseAsync()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
diff --git a/src/features.ts b/packages/core/src/features.ts
similarity index 78%
rename from src/features.ts
rename to packages/core/src/features.ts
index 5bde4d95c..30c97b776 100644
--- a/src/features.ts
+++ b/packages/core/src/features.ts
@@ -12,6 +12,11 @@ export const isOutputServer = async () => {
   return config?.output === 'server';
 };
 
+export const isIndexedSearchEnabled = async () => {
+  const config = await getEventCatalogConfigFile(process.env.PROJECT_DIR || '');
+  return config?.search?.type === 'indexed';
+};
+
 export const isAuthEnabled = async () => {
   const directory = process.env.PROJECT_DIR || process.cwd();
   const hasAuthConfig = fs.existsSync(join(directory, 'eventcatalog.auth.js'));
diff --git a/src/generate.js b/packages/core/src/generate.js
similarity index 75%
rename from src/generate.js
rename to packages/core/src/generate.js
index 736db30b2..610fc3cc0 100644
--- a/src/generate.js
+++ b/packages/core/src/generate.js
@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { getEventCatalogConfigFile, cleanup } from './eventcatalog-config-file-utils.js';
+import { logger } from './utils/cli-logger';
 
 function getDefaultExport(importedModule) {
   if (importedModule === null || typeof importedModule !== 'object') {
@@ -24,10 +25,12 @@ export const generate = async (PROJECT_DIRECTORY) => {
     const { generators = [] } = config;
 
     if (!generators.length) {
-      console.log('No configured generators found, skipping generation');
+      logger.info('No configured generators found, skipping generation', 'generator');
       return;
     }
 
+    const errors = [];
+
     for (const generator of generators) {
       let plugin = generator[0];
       const pluginConfig = generator[1];
@@ -47,16 +50,21 @@ export const generate = async (PROJECT_DIRECTORY) => {
         const generator = getDefaultExport(importedGenerator);
 
         await generator({ eventCatalogConfig: {} }, pluginConfig);
-
-        // Use importedGenerator here
       } catch (error) {
-        console.error('Error loading plugin:', error);
-        await cleanup(PROJECT_DIRECTORY);
-        return;
+        logger.error(`Failed to run generator "${plugin}":`, 'generator');
+        console.error(error);
+        errors.push({ plugin, error });
       }
     }
 
     await cleanup(PROJECT_DIRECTORY);
+
+    if (errors.length > 0) {
+      logger.error(`${errors.length} generator(s) failed:`, 'generator');
+      for (const { plugin } of errors) {
+        logger.error(`  - ${plugin}`, 'generator');
+      }
+    }
   } catch (error) {
     // Failed to generate clean up...
     console.error(error);
diff --git a/packages/core/src/map-catalog-to-astro.js b/packages/core/src/map-catalog-to-astro.js
new file mode 100644
index 000000000..a47e57ecb
--- /dev/null
+++ b/packages/core/src/map-catalog-to-astro.js
@@ -0,0 +1,221 @@
+import path from 'node:path';
+
+// Code files in the top-level `pages/` directory become routes in the Astro app
+// (custom pages). Everything else in `pages/` keeps the collection behaviour.
+const CUSTOM_PAGE_EXTENSIONS = ['.astro', '.ts', '.js', '.mjs'];
+
+const COLLECTION_KEYS = [
+  'agents',
+  'events',
+  'commands',
+  'services',
+  'domains',
+  'flows',
+  'pages',
+  'changelogs',
+  'queries',
+  'channels',
+  'ubiquitousLanguages',
+  'dependencies',
+];
+
+/**
+ * @typedef {Object} MapCatalogToAstroParams
+ * @prop {string} filePath The catalog file path
+ * @prop {string} astroDir The astro directory
+ * @prop {string} projectDir The user's project directory
+ */
+
+/**
+ *
+ * @param {MapCatalogToAstroParams} params
+ * @returns {string[]} The astro file paths
+ */
+export function mapCatalogToAstro({ filePath, astroDir, projectDir }) {
+  const relativeFilePath = removeBasePath(filePath, projectDir);
+
+  if (isLikeC4Source(relativeFilePath)) {
+    return [];
+  }
+
+  if (!isCatalogRelated(relativeFilePath)) {
+    return [];
+  }
+
+  const customPageTargetPaths = getCustomPageTargetPaths(relativeFilePath, astroDir);
+  if (customPageTargetPaths) {
+    return customPageTargetPaths;
+  }
+
+  const baseTargetPaths = getBaseTargetPaths(relativeFilePath);
+  const relativeTargetPath = getRelativeTargetPath(relativeFilePath);
+
+  return baseTargetPaths.map((base) => path.join(astroDir, base, relativeTargetPath));
+}
+
+/**
+ *
+ * @param {string} fullPath
+ * @param {string} basePath
+ * @returns {string} The fullPath without the basePath
+ */
+function removeBasePath(fullPath, basePath) {
+  const relativePath = path.relative(basePath, fullPath);
+  return relativePath.startsWith('..') ? fullPath : relativePath;
+}
+
+/**
+ * Check if the key is an ASTRO COLLECTION KEY
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isCollectionKey(key) {
+  return COLLECTION_KEYS.includes(key);
+}
+
+function isLikeC4Source(filePath) {
+  return filePath.endsWith('.c4') || filePath.endsWith('.likec4');
+}
+
+// This is a workaround to differentiate between a file and a directory.
+// Of course this is not the best solution. But how differentiate? `fs.stats`
+// could be used, but sometimes the filePath references a deleted file/directory
+// which causes an error when using `fs.stats`.
+const hasExtension = (str) => /\.[a-zA-Z0-9]{2,}$/.test(str);
+
+/**
+ * Maps files in the user's top-level `pages/` directory.
+ * Code files (.astro/.ts/.js/.mjs) become custom pages (routes) in the Astro app,
+ * they must never land in `public/` where their source would be served.
+ * @param {string} filePath - The file path without the projectDir prefix.
+ * @param {string} astroDir - The astro directory.
+ * @returns {string[]|null} Target paths, or null when the path is not a top-level pages path.
+ */
+function getCustomPageTargetPaths(filePath, astroDir) {
+  const filePathArr = filePath.split(path.sep).filter(Boolean);
+
+  if (filePathArr[0] !== 'pages') {
+    return null;
+  }
+
+  const customPagePath = path.join(astroDir, 'src', 'custom-pages', ...filePathArr.slice(1));
+
+  if (CUSTOM_PAGE_EXTENSIONS.includes(path.extname(filePath).toLowerCase())) {
+    return [customPagePath];
+  }
+
+  // Directories map to both targets so watcher deletes clean up both copies
+  if (!hasExtension(filePath)) {
+    return [customPagePath, path.join(astroDir, 'public', 'generated', ...filePathArr)];
+  }
+
+  // Other assets keep the existing public/generated behaviour
+  return [path.join(astroDir, 'public', 'generated', ...filePathArr)];
+}
+
+/**
+ * Checks whether the given path is a configuration file, styles file, public asset file or collection file.
+ * @param {string} filePath - The file path without the projectDir prefix.
+ * @returns {boolean}
+ */
+function isCatalogRelated(filePath) {
+  const filePathArr = filePath.split(path.sep).filter(Boolean);
+
+  if (
+    [
+      'eventcatalog.config.js', // config file at root
+      'eventcatalog.styles.css', // custom styles file at root
+      'components', // custom components
+      'snippets', // custom snippets
+      'public', // public assets
+      '.env', // env file
+      ...COLLECTION_KEYS,
+    ].includes(filePathArr[0])
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Generates the base target path accordingly to the file path.
+ * @param {string} filePath The path to the file without PROJECT_DIR prefix.
+ * @returns {Array.<'src/content'|'public/generated'|'src/catalog-files'|'/'>} The base target path.
+ */
+function getBaseTargetPaths(filePath) {
+  const filePathArr = filePath.split(path.sep).filter(Boolean);
+
+  // Collection
+  if (isCollectionKey(filePathArr[0])) {
+    // Assets files
+    if (hasExtension(filePath)) {
+      return [path.join('public', 'generated')];
+    }
+
+    /**
+     * @parcel/watcher throttle and coalesce events for performance reasons.
+     *
+     * Consider the following:
+     *    The user deletes a large `services/` dir from eventcatalog.
+     *    The @parcel/watcher could emit only one delete event of the
+     *    `services/` directory.
+     *
+     * In this situation we need delete all files from
+     * - `public/generated/services/`
+     * - `src/catalog-files/services/`
+     * - `src/content/services/`
+     *
+     * TODO: What happens if services contains commands/events inside of it??? How handle this?
+     */
+    // Directories
+    return [path.join('public', 'generated')];
+  }
+
+  // Custom components
+  if (filePathArr[0] == 'components') {
+    return [path.join('src', 'custom-defined-components')];
+  }
+
+  // Custom snippets
+  if (filePathArr[0] == 'snippets') {
+    return [path.join('src')];
+  }
+
+  // Public assets (public/*)
+  if (filePathArr[0] == 'public') {
+    return [path.join('public')];
+  }
+
+  /**
+   * Config files:
+   * - eventcatalog.config.js
+   * - eventcatalog.styles.css
+   */
+  return [path.join('/')];
+}
+
+/**
+ * Generates the path until the ASTRO_COLLECTION_KEY or the PROJECT_DIR root.
+ * @param {string} filePath The path to the file.
+ * @returns {string} The path until the COLLECTION_KEY or PROJECT_DIR root.
+ */
+function getRelativeTargetPath(filePath) {
+  const filePathArr = filePath.split(path.sep).filter(Boolean);
+
+  if (filePathArr[0] == 'public' || filePathArr[0] == 'components') {
+    filePathArr.shift();
+  }
+
+  if (filePathArr[0] == 'snippets') {
+    return path.join('snippets', ...filePathArr.slice(1));
+  }
+
+  const relativePath = [];
+  for (let i = filePathArr.length - 1; i >= 0; i--) {
+    relativePath.unshift(filePathArr[i]);
+    if (isCollectionKey(filePathArr[i]) && filePathArr[i] != 'snippets') break;
+  }
+
+  return path.join(...relativePath);
+}
diff --git a/src/migrations/index.ts b/packages/core/src/migrations/index.ts
similarity index 100%
rename from src/migrations/index.ts
rename to packages/core/src/migrations/index.ts
diff --git a/src/migrations/message-channels-to-service-channels.ts b/packages/core/src/migrations/message-channels-to-service-channels.ts
similarity index 79%
rename from src/migrations/message-channels-to-service-channels.ts
rename to packages/core/src/migrations/message-channels-to-service-channels.ts
index 562dade2a..dc3c3ec9d 100644
--- a/src/migrations/message-channels-to-service-channels.ts
+++ b/packages/core/src/migrations/message-channels-to-service-channels.ts
@@ -4,7 +4,17 @@ import os from 'node:os';
 import matter from 'gray-matter';
 import path from 'node:path';
 
+const DISABLE_CHANNEL_MIGRATION_ENV = 'EVENTCATALOG_DISABLE_CHANNEL_MIGRATION';
+
+const isChannelMigrationDisabled = () => {
+  return ['true', '1', 'yes'].includes((process.env[DISABLE_CHANNEL_MIGRATION_ENV] ?? '').toLowerCase());
+};
+
 export default async (dir?: string) => {
+  if (isChannelMigrationDisabled()) {
+    return { status: 'skipped', message: `Channel migration disabled by ${DISABLE_CHANNEL_MIGRATION_ENV}` };
+  }
+
   const PROJECT_DIR = path.join(dir || process.env.PROJECT_DIR!);
 
   const messages = await glob(
@@ -93,20 +103,16 @@ export default async (dir?: string) => {
       data.receives?.filter((receive: any) => messagesWithChannels.some((message: any) => message.id === receive.id)) ?? [];
 
     if (messagesTheServiceSendsThatNeedUpdating.length > 0 || messagesTheServiceReceivesThatNeedUpdating.length > 0) {
-      const newSends = messagesTheServiceSendsThatNeedUpdating.map((send: any) => ({
-        ...send,
-        to: messagesWithChannels
-          .map((message: any) => (message.id === send.id ? message.channels : []))
-          .flat()
-          .filter((channel: any) => channel !== null),
-      }));
-      const newReceives = messagesTheServiceReceivesThatNeedUpdating.map((receive: any) => ({
-        ...receive,
-        from: messagesWithChannels
-          .map((message: any) => (message.id === receive.id ? message.channels : []))
-          .flat()
-          .filter((channel: any) => channel !== null),
-      }));
+      const newSends = (data.sends ?? []).map((send: any) => {
+        const match = messagesWithChannels.find((message: any) => message.id === send.id);
+        if (!match) return send;
+        return { ...send, to: (match.channels ?? []).filter((channel: any) => channel !== null) };
+      });
+      const newReceives = (data.receives ?? []).map((receive: any) => {
+        const match = messagesWithChannels.find((message: any) => message.id === receive.id);
+        if (!match) return receive;
+        return { ...receive, from: (match.channels ?? []).filter((channel: any) => channel !== null) };
+      });
 
       const newData = {
         ...data,
diff --git a/src/resolve-catalog-dependencies.js b/packages/core/src/resolve-catalog-dependencies.js
similarity index 100%
rename from src/resolve-catalog-dependencies.js
rename to packages/core/src/resolve-catalog-dependencies.js
diff --git a/packages/core/src/search-indexer.ts b/packages/core/src/search-indexer.ts
new file mode 100644
index 000000000..65509db8b
--- /dev/null
+++ b/packages/core/src/search-indexer.ts
@@ -0,0 +1,424 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { glob } from 'glob';
+import matter from 'gray-matter';
+import type { Config } from './eventcatalog.config';
+
+type SearchRecord = {
+  url: string;
+  title: string;
+  content: string;
+  type: string;
+  collection: string;
+  id?: string;
+  version?: string;
+  summary?: string;
+};
+
+type BuildSearchIndexOptions = {
+  projectDir: string;
+  outDir: string;
+  config: Config;
+  isServer: boolean;
+  searchOutputPath?: string;
+};
+
+const RESOURCE_COLLECTIONS: Record<string, { docsPath: string; type: string }> = {
+  adrs: { docsPath: 'adrs', type: 'Architecture Decision' },
+  agents: { docsPath: 'agents', type: 'Agent' },
+  channels: { docsPath: 'channels', type: 'Channel' },
+  commands: { docsPath: 'commands', type: 'Command' },
+  containers: { docsPath: 'containers', type: 'Container' },
+  'data-products': { docsPath: 'data-products', type: 'Data Product' },
+  domains: { docsPath: 'domains', type: 'Domain' },
+  entities: { docsPath: 'entities', type: 'Entity' },
+  events: { docsPath: 'events', type: 'Event' },
+  flows: { docsPath: 'flows', type: 'Flow' },
+  queries: { docsPath: 'queries', type: 'Query' },
+  services: { docsPath: 'services', type: 'Service' },
+  subdomains: { docsPath: 'domains', type: 'Domain' },
+};
+
+const IGNORED_GLOBS = [
+  '**/.git/**',
+  '**/.eventcatalog-core/**',
+  '**/dist/**',
+  '**/node_modules/**',
+  '**/public/**',
+  '**/snippets/**',
+  '**/chat-prompts/**',
+];
+
+const trimSlashes = (value: string) => value.replace(/^\/+|\/+$/g, '');
+
+const normalizePath = (value: string) => value.replace(/\\/g, '/');
+
+const removeExtension = (value: string) => value.replace(/\.(md|mdx)$/i, '');
+
+const stripNumericPrefix = (value: string) => value.replace(/^\d+(?:[-_.\s]+)?/, '') || value;
+
+const normalizeUrlPath = (value: string) => {
+  const withoutIndex = value.replace(/\/index$/i, '');
+  return withoutIndex || '';
+};
+
+const buildUrl = (pathname: string, config: Config) => {
+  const base = config.base ? `/${trimSlashes(config.base)}` : '';
+  const cleanPath = `/${trimSlashes(pathname)}`;
+  const url = `${base}${cleanPath}`.replace(/\/{2,}/g, '/');
+
+  if (config.trailingSlash === true && !url.endsWith('/')) {
+    return `${url}/`;
+  }
+
+  return url || '/';
+};
+
+const valueToSearchText = (value: unknown): string => {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (Array.isArray(value)) return value.map(valueToSearchText).filter(Boolean).join(' ');
+  if (typeof value === 'object') return Object.values(value).map(valueToSearchText).filter(Boolean).join(' ');
+  return '';
+};
+
+export const markdownToSearchText = (content: string) => {
+  return content
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/^\s*import\s+.*$/gm, ' ')
+    .replace(/^\s*export\s+.*$/gm, ' ')
+    .replace(/```[\s\S]*?```/g, (match) => match.replace(/```[a-zA-Z0-9-]*\n?/g, ' ').replace(/```/g, ' '))
+    .replace(/<([A-Z][A-Za-z0-9.]*)\b([^>]*)\/?>/g, (_match, _component, attributes) => {
+      const quotedValues = [...String(attributes).matchAll(/(?:title|label|description|alt|summary)=["'`]([^"'`]+)["'`]/g)];
+      return quotedValues.map((entry) => entry[1]).join(' ');
+    })
+    .replace(/<\/?[A-Za-z][^>]*>/g, ' ')
+    .replace(/\[\[([^|\]]+)\|([^\]]+)\]\]/g, '$2')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/[`*_~>#|{}[\]():]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+};
+
+const inferDocIdFromFile = (relativePath: string, frontmatterId?: string) => {
+  if (frontmatterId) return frontmatterId;
+
+  const fileName = path.posix.basename(removeExtension(relativePath));
+  if (fileName.toLowerCase() === 'index') {
+    return path.posix.basename(path.posix.dirname(relativePath));
+  }
+
+  return stripNumericPrefix(fileName);
+};
+
+const findResourceSegment = (segments: string[]) => {
+  let match: { index: number; segment: string } | null = null;
+
+  for (let index = 0; index < segments.length - 1; index++) {
+    const segment = segments[index];
+    if (segments[index - 1] === 'docs') {
+      continue;
+    }
+    if (RESOURCE_COLLECTIONS[segment] && segments[index + 1]) {
+      match = { index, segment };
+    }
+  }
+
+  return match;
+};
+
+const readResourceFrontmatter = async (projectDir: string, resourcePath: string) => {
+  const candidates = [path.join(projectDir, resourcePath, 'index.mdx'), path.join(projectDir, resourcePath, 'index.md')];
+
+  for (const candidate of candidates) {
+    try {
+      const file = await fs.readFile(candidate, 'utf8');
+      return matter(file).data as Record<string, any>;
+    } catch {
+      // Try the next possible index file.
+    }
+  }
+
+  return {};
+};
+
+const deriveRecordFromPath = async ({
+  projectDir,
+  relativePath,
+  data,
+  config,
+}: {
+  projectDir: string;
+  relativePath: string;
+  data: Record<string, any>;
+  config: Config;
+}): Promise<Omit<SearchRecord, 'content'> | null> => {
+  const normalizedRelativePath = normalizePath(relativePath);
+  const segments = normalizedRelativePath.split('/').filter(Boolean);
+  const fileName = segments[segments.length - 1] || '';
+  const fileNameWithoutExtension = removeExtension(fileName);
+
+  if (data.hidden === true || data.draft) {
+    return null;
+  }
+
+  if (segments[0] === 'docs') {
+    const customPath = normalizeUrlPath(removeExtension(segments.slice(1).join('/')));
+    const title = data.title || data.label || path.posix.basename(customPath) || 'Custom docs';
+
+    return {
+      url: buildUrl(`/docs/custom/${customPath}`, config),
+      title,
+      summary: data.summary,
+      type: 'Custom Doc',
+      collection: 'custom-docs',
+      id: customPath,
+    };
+  }
+
+  if (segments[0] === 'users' || segments[0] === 'teams') {
+    const id = data.id || (fileNameWithoutExtension === 'index' ? segments[1] : fileNameWithoutExtension);
+    const type = segments[0] === 'users' ? 'User' : 'Team';
+
+    return {
+      url: buildUrl(`/docs/${segments[0]}/${id}`, config),
+      title: data.name || data.title || id,
+      summary: data.summary,
+      type,
+      collection: segments[0],
+      id,
+    };
+  }
+
+  const resourceMatch = findResourceSegment(segments);
+  if (!resourceMatch) {
+    return null;
+  }
+
+  const resourceConfig = RESOURCE_COLLECTIONS[resourceMatch.segment];
+  const resourceFolderId = segments[resourceMatch.index + 1];
+  const resourcePathSegments = segments.slice(0, resourceMatch.index + 2);
+  const versionFromPath =
+    segments[resourceMatch.index + 2] === 'versioned' && segments[resourceMatch.index + 3]
+      ? segments[resourceMatch.index + 3]
+      : undefined;
+  if (versionFromPath) {
+    resourcePathSegments.push('versioned', versionFromPath);
+  }
+  const resourcePath = resourcePathSegments.join('/');
+  const resourceData = fileNameWithoutExtension === 'index' ? data : await readResourceFrontmatter(projectDir, resourcePath);
+  const resourceId = resourceData.id || data.resourceId || resourceFolderId;
+  const resourceVersion = versionFromPath || resourceData.version || data.resourceVersion || data.version;
+
+  if (!resourceVersion) {
+    return null;
+  }
+
+  if (fileNameWithoutExtension === 'index') {
+    return {
+      url: buildUrl(`/docs/${resourceConfig.docsPath}/${resourceId}/${resourceVersion}`, config),
+      title: data.name || data.title || resourceId,
+      summary: data.summary,
+      type: resourceConfig.type,
+      collection: resourceConfig.docsPath,
+      id: resourceId,
+      version: resourceVersion,
+    };
+  }
+
+  if (fileNameWithoutExtension === 'ubiquitous-language') {
+    return {
+      url: buildUrl(`/docs/${resourceConfig.docsPath}/${resourceId}/language`, config),
+      title: data.title || `${resourceData.name || resourceId} ubiquitous language`,
+      summary: data.summary,
+      type: 'Language',
+      collection: 'language',
+      id: resourceId,
+      version: resourceVersion,
+    };
+  }
+
+  if (fileNameWithoutExtension === 'changelog') {
+    return {
+      url: buildUrl(`/docs/${resourceConfig.docsPath}/${resourceId}/${resourceVersion}/changelog`, config),
+      title: data.title || `${resourceData.name || resourceId} changelog`,
+      summary: data.summary,
+      type: 'Changelog',
+      collection: 'changelog',
+      id: resourceId,
+      version: resourceVersion,
+    };
+  }
+
+  const docsIndex = segments.indexOf('docs');
+  if (docsIndex > resourceMatch.index) {
+    const docType = data.type || segments[docsIndex + 1] || 'pages';
+    const docId = inferDocIdFromFile(normalizedRelativePath, data.id);
+    const title = data.title || stripNumericPrefix(removeExtension(fileName));
+
+    return {
+      url: buildUrl(`/docs/${resourceConfig.docsPath}/${resourceId}/${resourceVersion}/${docType}/${docId}`, config),
+      title,
+      summary: data.summary,
+      type: 'Resource Doc',
+      collection: docType,
+      id: docId,
+      version: data.version || resourceVersion,
+    };
+  }
+
+  if (segments[0] === 'diagrams') {
+    const id = data.id || resourceFolderId;
+    const version = data.version || resourceVersion;
+
+    return {
+      url: buildUrl(`/diagrams/${id}/${version}`, config),
+      title: data.name || data.title || id,
+      summary: data.summary,
+      type: 'Design',
+      collection: 'diagrams',
+      id,
+      version,
+    };
+  }
+
+  return null;
+};
+
+export const collectSearchRecords = async ({
+  projectDir,
+  config,
+}: {
+  projectDir: string;
+  config: Config;
+}): Promise<SearchRecord[]> => {
+  const files = await glob('**/*.{md,mdx}', {
+    cwd: projectDir,
+    absolute: true,
+    nodir: true,
+    ignore: IGNORED_GLOBS,
+    windowsPathsNoEscape: process.platform === 'win32',
+  });
+
+  const records = await Promise.all(
+    files.map(async (file) => {
+      const raw = await fs.readFile(file, 'utf8');
+      const parsed = matter(raw);
+      const relativePath = normalizePath(path.relative(projectDir, file));
+      const baseRecord = await deriveRecordFromPath({
+        projectDir,
+        relativePath,
+        data: parsed.data,
+        config,
+      });
+
+      if (!baseRecord) {
+        return null;
+      }
+
+      const frontmatterText = valueToSearchText({
+        id: baseRecord.id,
+        title: baseRecord.title,
+        summary: baseRecord.summary,
+        version: baseRecord.version,
+        owners: parsed.data.owners,
+        status: parsed.data.status,
+        date: parsed.data.date,
+        decisionMakers: parsed.data.decisionMakers,
+        appliesTo: parsed.data.appliesTo,
+        badges: parsed.data.badges,
+      });
+
+      const content = [frontmatterText, markdownToSearchText(parsed.content)].filter(Boolean).join('\n\n');
+
+      if (!content.trim()) {
+        return null;
+      }
+
+      return {
+        ...baseRecord,
+        content,
+      };
+    })
+  );
+
+  const uniqueRecords = new Map<string, SearchRecord>();
+  for (const record of records) {
+    if (!record) continue;
+    uniqueRecords.set(record.url, record);
+  }
+
+  return [...uniqueRecords.values()].sort((a, b) => a.url.localeCompare(b.url));
+};
+
+const getSearchOutputPath = ({
+  outDir,
+  isServer,
+  searchOutputPath,
+}: Pick<BuildSearchIndexOptions, 'outDir' | 'isServer' | 'searchOutputPath'>) => {
+  if (searchOutputPath) {
+    return searchOutputPath;
+  }
+
+  return path.join(outDir, isServer ? 'client' : '', 'pagefind');
+};
+
+export const buildSearchIndex = async ({ projectDir, outDir, config, isServer, searchOutputPath }: BuildSearchIndexOptions) => {
+  const records = await collectSearchRecords({ projectDir, config });
+
+  if (records.length === 0) {
+    throw new Error('No searchable Markdown or MDX content was found.');
+  }
+
+  const pagefind = (await import('pagefind')) as any;
+  const { index } = await pagefind.createIndex({
+    keepIndexUrl: false,
+    writePlayground: false,
+  });
+
+  const errors: string[] = [];
+
+  for (const record of records) {
+    const result = await index.addCustomRecord({
+      url: record.url,
+      content: record.content,
+      language: 'en',
+      meta: {
+        title: record.title,
+        summary: record.summary || '',
+        type: record.type,
+        collection: record.collection,
+        id: record.id || '',
+        version: record.version || '',
+      },
+      filters: {
+        type: [record.type],
+        collection: [record.collection],
+      },
+    });
+
+    if (result.errors?.length) {
+      errors.push(...result.errors.map((error: any) => `${record.url}: ${error.message || error}`));
+    }
+  }
+
+  const outputPath = getSearchOutputPath({ outDir, isServer, searchOutputPath });
+  await fs.rm(outputPath, { recursive: true, force: true });
+
+  const writeResult = await index.writeFiles({ outputPath });
+  if (writeResult.errors?.length) {
+    errors.push(...writeResult.errors.map((error: any) => error.message || String(error)));
+  }
+
+  await index.deleteIndex?.();
+  await pagefind.close?.();
+
+  if (errors.length > 0) {
+    throw new Error(`Failed to build indexed search:\n${errors.join('\n')}`);
+  }
+
+  return {
+    records: records.length,
+    outputPath,
+  };
+};
diff --git a/packages/core/src/utils/cli-logger.ts b/packages/core/src/utils/cli-logger.ts
new file mode 100644
index 000000000..bd00ec036
--- /dev/null
+++ b/packages/core/src/utils/cli-logger.ts
@@ -0,0 +1,44 @@
+import pc from 'picocolors';
+import { VERSION } from '../constants';
+
+const getTimestamp = () => {
+  const now = new Date();
+  return now.toLocaleTimeString('en-US', { hour12: false });
+};
+
+const formatMessage = (tag: string, message: string, tagColor: (s: string) => string) => {
+  return `${pc.dim(getTimestamp())} ${tagColor(`[${tag}]`)} ${message}`;
+};
+
+export const logger = {
+  welcome: () => {
+    console.log();
+    console.log(pc.magenta(pc.bold('🚀 EventCatalog')) + pc.dim(`  (v${VERSION})`));
+    console.log(pc.dim('https://eventcatalog.dev'));
+    console.log();
+    console.log(
+      pc.dim('If you like the project, we would appreciate a star on GitHub ❤️ - ') +
+        pc.bold('https://github.com/event-catalog/eventcatalog/stargazers')
+    );
+    console.log(
+      pc.dim('Using AI? Install EventCatalog Skills to help you manage your catalog - ') +
+        pc.bold('https://github.com/event-catalog/skills')
+    );
+    console.log();
+  },
+  info: (message: string, tag: string = 'info') => {
+    console.log(formatMessage(tag, message, pc.blue));
+  },
+  success: (message: string, tag: string = 'success') => {
+    console.log(formatMessage(tag, message, pc.green));
+  },
+  error: (message: string, tag: string = 'error') => {
+    console.log(formatMessage(tag, message, pc.red));
+  },
+  warning: (message: string, tag: string = 'warn') => {
+    console.log(formatMessage(tag, message, pc.yellow));
+  },
+  dim: (message: string) => {
+    console.log(pc.dim(message));
+  },
+};
diff --git a/src/watcher.js b/packages/core/src/watcher.js
similarity index 76%
rename from src/watcher.js
rename to packages/core/src/watcher.js
index c4d5a6f92..119fdb39b 100644
--- a/src/watcher.js
+++ b/packages/core/src/watcher.js
@@ -34,6 +34,13 @@ export async function watch(projectDirectory, catalogDirectory, callback = undef
         for (let event of events) {
           const { path: filePath, type } = event;
 
+          // Transient artifacts from atomic writes (e.g. the SDK's `writeService`
+          // creates a sibling `.lock` file that's removed before the watcher
+          // fires). Skip outright — they're gone by the time we try to stat.
+          if (filePath.endsWith('.lock')) {
+            continue;
+          }
+
           // Ignore any file ending with .mdx or .md, as Astro supports this with the new content collections
           // snippets still need to be copied to the astro directory
           if ((filePath.endsWith('.mdx') || filePath.endsWith('.md')) && !filePath.includes('snippets')) {
@@ -49,14 +56,24 @@ export async function watch(projectDirectory, catalogDirectory, callback = undef
           for (const astroPath of astroPaths) {
             switch (type) {
               case 'create':
-              case 'update':
-                // First copy the file
-                if (fs.statSync(filePath).isDirectory()) {
+              case 'update': {
+                // The file may have disappeared between the watcher firing and
+                // this handler running (atomic writes, editor swap files,
+                // rapid rename/delete). Treat ENOENT as "nothing to copy".
+                let stat;
+                try {
+                  stat = fs.statSync(filePath);
+                } catch (err) {
+                  if (err.code === 'ENOENT') break;
+                  throw err;
+                }
+                if (stat.isDirectory()) {
                   fs.mkdirSync(astroPath, { recursive: true });
                 } else {
                   retryEPERM(fs.cpSync)(filePath, astroPath);
                 }
                 break;
+              }
               case 'delete':
                 retryEPERM(rimrafSync)(astroPath);
                 break;
diff --git a/tsconfig.json b/packages/core/tsconfig.json
similarity index 100%
rename from tsconfig.json
rename to packages/core/tsconfig.json
diff --git a/tsup.config.js b/packages/core/tsup.config.js
similarity index 100%
rename from tsup.config.js
rename to packages/core/tsup.config.js
diff --git a/vitest.config.js b/packages/core/vitest.config.js
similarity index 84%
rename from vitest.config.js
rename to packages/core/vitest.config.js
index 985fcfcff..5b9cbba41 100644
--- a/vitest.config.js
+++ b/packages/core/vitest.config.js
@@ -7,6 +7,9 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 export default defineConfig({
   root: __dirname,
+  define: {
+    __EC_TRAILING_SLASH__: false,
+  },
   plugins: [
     tsconfigPaths({
       projects: [path.resolve(__dirname, 'eventcatalog/tsconfig.json')],
@@ -16,6 +19,7 @@ export default defineConfig({
     globals: true,
     environment: 'node',
     testTimeout: 5000,
+    exclude: ['**/node_modules/**', '**/dist/**', '**/fields-db.test.*'],
     env: {
       PROJECT_DIR: path.resolve(__dirname, 'examples/default'),
     },
@@ -23,8 +27,9 @@ export default defineConfig({
   resolve: {
     conditions: ['import', 'module', 'node', 'default'],
     alias: {
-      'astro:content': path.resolve(__dirname, './__mocks__/astro-content.ts'),
+      'astro:content': path.resolve(__dirname, './src/__mocks__/astro-content.ts'),
       '@config': path.resolve(__dirname, 'eventcatalog/eventcatalog.config.js'),
+      '@eventcatalog/connectors': path.resolve(__dirname, 'node_modules/@eventcatalog/connectors/dist/index.mjs'),
       '@eventcatalog/sdk': path.resolve(__dirname, 'node_modules/@eventcatalog/sdk/dist/index.mjs'),
       '@eventcatalog': path.resolve(__dirname, 'eventcatalog/src/utils/eventcatalog-config/catalog.ts'),
       '@icons': path.resolve(__dirname, 'eventcatalog/src/icons'),
diff --git a/packages/create-eventcatalog/.gitignore b/packages/create-eventcatalog/.gitignore
new file mode 100644
index 000000000..db4c6d9b6
--- /dev/null
+++ b/packages/create-eventcatalog/.gitignore
@@ -0,0 +1,2 @@
+dist
+node_modules
\ No newline at end of file
diff --git a/packages/create-eventcatalog/.prettierrc b/packages/create-eventcatalog/.prettierrc
new file mode 100644
index 000000000..2fbe55cde
--- /dev/null
+++ b/packages/create-eventcatalog/.prettierrc
@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "printWidth": 130,
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true
+}
diff --git a/packages/create-eventcatalog/CHANGELOG.md b/packages/create-eventcatalog/CHANGELOG.md
new file mode 100644
index 000000000..403bab363
--- /dev/null
+++ b/packages/create-eventcatalog/CHANGELOG.md
@@ -0,0 +1,434 @@
+# @eventcatalog/create-catalog
+
+## 4.3.5
+
+### Patch Changes
+
+- c769012: feat(create-eventcatalog): optionally install EventCatalog Skills when scaffolding a new project, and surface the skills repo in the CLI banner
+
+## 4.3.4
+
+### Patch Changes
+
+- bea8571: Rebuild the create-eventcatalog default template with a new e-commerce catalog (domains, systems, services, messages) and fix the collapsed vertical nav brand link alignment.
+
+## 4.3.4-beta.0
+
+### Patch Changes
+
+- bea8571: Rebuild the create-eventcatalog default template with a new e-commerce catalog (domains, systems, services, messages) and fix the collapsed vertical nav brand link alignment.
+
+## 4.3.3
+
+### Patch Changes
+
+- 1c080f5: Refresh README templates and CLI completion output, and add `editor` npm script that runs `@eventcatalog/editor`.
+
+## 4.3.2
+
+### Patch Changes
+
+- cf1647c: Set `theme: 'sunset'` as the default theme across all project templates.
+
+## 4.3.1
+
+### Patch Changes
+
+- 9cf2a80: Polish search result highlight styling and refresh default template branding.
+
+## 4.3.0
+
+### Minor Changes
+
+- 61853ef: Add opt-in indexed full-content search powered by Pagefind. Enable by setting `search: { type: 'indexed' }` in `eventcatalog.config.js` to index markdown content across resources, custom docs, resource docs and changelogs. Resource search remains the default.
+
+## 4.2.8
+
+### Patch Changes
+
+- c6a2625: Simplify E-Commerce domain template by removing target architecture section
+
+## 4.2.7
+
+### Patch Changes
+
+- 5874143: Bundle EventCatalog docs into `@eventcatalog/core` so coding agents can read the source-of-truth documentation locally, and scaffold `AGENTS.md` / `CLAUDE.md` into new projects so agents are pointed at those bundled docs before making changes.
+
+## 4.2.6
+
+### Patch Changes
+
+- b732d09: Refresh logo.png across all project templates to use the new EventCatalog logo.
+
+## 4.2.5
+
+### Patch Changes
+
+- 141b7c1: Add `eventcatalog export` CLI command to export catalog as JSON using dumpCatalog SDK function
+
+## 4.2.4
+
+### Patch Changes
+
+- cb40037: Improve generated README with getting started guide, AI tools, integrations, and learning resources
+
+## 4.2.3
+
+### Patch Changes
+
+- 7a23aa2: add usage examples to all events with schemas in the default template
+
+## 4.2.2
+
+### Patch Changes
+
+- 58fdcf2: fix dark mode for embedded Flow border and footer text by using theme CSS variables instead of hardcoded colors
+
+## 4.2.1
+
+### Patch Changes
+
+- b058439: remove unused got and tar dependencies, bump cross-spawn to 6.0.6
+
+## 4.2.0
+
+### Minor Changes
+
+- 19696f3: migrate sdk and create-eventcatalog packages into monorepo
+
+## 4.2.0-beta.0
+
+### Minor Changes
+
+- 19696f3: migrate sdk and create-eventcatalog packages into monorepo
+
+## 4.1.2
+
+### Patch Changes
+
+- 21b7e86: updated default catalog and added linter
+
+## 4.1.1
+
+### Patch Changes
+
+- 3a15829: Remove default index page from template
+
+## 4.1.0
+
+### Minor Changes
+
+- 2260af7: feat(cli): improve CLI UX with cleaner output
+
+## 4.0.0
+
+### Major Changes
+
+- 1a1e50e: chore(sdk): updated default catalog config files for v3
+
+## 3.1.3
+
+### Patch Changes
+
+- 23b4ad6: chore(cli): added onboarding call option
+
+## 3.1.2
+
+### Patch Changes
+
+- 8a3531c: feat(core): added new channel 2.0 support for new catalogs
+
+## 3.1.1
+
+### Patch Changes
+
+- 788651e: feat(core): added new channel 2.0 support for new catalogs
+- 6470f31: feat(core): added new channel 2.0 support for new catalogs
+
+## 3.1.0
+
+### Minor Changes
+
+- fcc8232: feat(core): added new channel 2.0 support for new catalogs
+
+## 3.0.13
+
+### Patch Changes
+
+- 923aee9: fix(code): fixed graphql template
+
+## 3.0.12
+
+### Patch Changes
+
+- 6d9b43e: feat(code): added new starter template for graphql
+
+## 3.0.11
+
+### Patch Changes
+
+- ef28ab9: chore(core): updated default catalog to include entities
+
+## 3.0.10
+
+### Patch Changes
+
+- d3aa09b: chore(cli): added output to catalog configs
+
+## 3.0.9
+
+### Patch Changes
+
+- c22f0b4: chore(core): updated logs
+
+## 3.0.8
+
+### Patch Changes
+
+- aa1c580: chore(core): updated astro versions
+- e162579: feat(cli): llms txt is now enabled by default on new catalogs
+
+## 3.0.7
+
+### Patch Changes
+
+- 975ba61: chore(cli): added apigateway template for create-catalog
+- 25047cc: chore(cli): added eventbridge template to create-catalog-cli
+
+## 3.0.6
+
+### Patch Changes
+
+- 2cb81d9: feat(cli): added confluent template
+
+## 3.0.5
+
+### Patch Changes
+
+- f46e524: chore(sdk): added docker file for a server catalog
+
+## 3.0.4
+
+### Patch Changes
+
+- ede050c: chore(cli): added .env files to all templates
+
+## 3.0.3
+
+### Patch Changes
+
+- 518bf81: chore(cli): added env files to git ignore
+
+## 3.0.2
+
+### Patch Changes
+
+- f50df4b: Added subdomain to template
+
+## 3.0.1
+
+### Patch Changes
+
+- 7dc0541: chore(cli): adding new flow example
+
+## 3.0.0
+
+### Major Changes
+
+- 7533525: chore(cli): moving to mdx files for catalogs
+
+## 2.2.7
+
+### Patch Changes
+
+- e4fc580: chore(cli): updated default nav bar
+- 1af508d: chore(core): updated the default app for users
+
+## 2.2.6
+
+### Patch Changes
+
+- 27527ad: chore(core): updated the default app for users
+
+## 2.2.5
+
+### Patch Changes
+
+- 9b9dfc0: feat(cli): default sidebar is now tree view
+
+## 2.2.4
+
+### Patch Changes
+
+- 2a0e5b7: feat(core): added rss feed for all templates
+
+## 2.2.3
+
+### Patch Changes
+
+- 5bef981: feat(cli): added users and teams to templates
+
+## 2.2.2
+
+### Patch Changes
+
+- 39a318f: feat(cli): added openapi and asyncapi templates
+
+## 2.2.1
+
+### Patch Changes
+
+- c2a57f6: chore(cli): added npmrc file to new projects
+
+## 2.2.0
+
+### Minor Changes
+
+- e06496b: feat(cli): added ability to create empty project
+
+## 2.1.1
+
+### Patch Changes
+
+- 7ab834c: feat(core): added ubiquitous language support
+
+## 2.1.0
+
+### Minor Changes
+
+- 1ba28b3: chore(cli): updated the demo app that is installed
+
+## 2.0.22
+
+### Patch Changes
+
+- 2c25837: feat(cli): added ability to set org name through CLI command
+
+## 2.0.21
+
+### Patch Changes
+
+- 6ab5d28: chore(cli): added core as a required dep
+
+## 2.0.20
+
+### Patch Changes
+
+- 321a2a0: chore(cli): removing dev deps no longer required
+
+## 2.0.19
+
+### Patch Changes
+
+- 37469aa: fix(cli): fixed broken version of service in the catalog
+
+## 2.0.18
+
+### Patch Changes
+
+- d0eb215: feat(cli): added tiles to the default template
+
+## 2.0.17
+
+### Patch Changes
+
+- d0cc42a: chore(cli): added timestamps
+
+## 2.0.16
+
+### Patch Changes
+
+- 26595e1: fix(cli): added missing dev dependency for diff
+
+## 2.0.15
+
+### Patch Changes
+
+- 0b18c9f: feat(cli): adding analytics support
+
+## 2.0.14
+
+### Patch Changes
+
+- f8aee0d: feat(cli): adding analytics support
+
+## 2.0.13
+
+### Patch Changes
+
+- 3d5af84: chore(cli): removed the OpenAPI MDX component
+
+## 2.0.12
+
+### Patch Changes
+
+- 4280606: Fix small spelling error
+
+## 2.0.11
+
+### Patch Changes
+
+- c538ec7: fix(cli): fixed incorrect example version of inventory service
+
+## 2.0.10
+
+### Patch Changes
+
+- 1c7e0db: fix(cli): fixed docker template for default example
+
+## 2.0.9
+
+### Patch Changes
+
+- 6e392ce: fix(cli): adding missing types
+
+## 2.0.8
+
+### Patch Changes
+
+- 27cd83e: feat(cli): adding flows to default example
+
+## 2.0.7
+
+### Patch Changes
+
+- 64c8b0f: feat(cli): added changelog examples to default template
+
+## 2.0.6
+
+### Patch Changes
+
+- f607f82: fix(cli): adding cross-env to devDeps
+- c5a5117: feat(core):added ability to customize the landing page
+
+## 2.0.5
+
+### Patch Changes
+
+- ad0c7b2: feat(cli): added generators
+- e2e89a5: fix(cli): small fix to config file
+
+## 2.0.4
+
+### Patch Changes
+
+- be82704: feat(cli): adding SchemaViewer component to default catalog on install.
+- 536b6fc: feat(cli): added public folder on new catalog
+
+## 2.0.3
+
+### Patch Changes
+
+- 84b76b4: feat(cli): added types to all config files that are created
+
+## 2.0.2
+
+### Patch Changes
+
+- 11c24d3: feat(cli): adding preview and start commands
+
+## 2.0.1
+
+### Patch Changes
+
+- aa79d69: chore(test): New version of the package
diff --git a/packages/create-eventcatalog/README.md b/packages/create-eventcatalog/README.md
new file mode 100644
index 000000000..84333bf9c
--- /dev/null
+++ b/packages/create-eventcatalog/README.md
@@ -0,0 +1,3 @@
+# @eventcatalog/create-catalog
+
+CLI utility to create new Eventcatalog. Full documentation at https://eventcatalog.dev.
diff --git a/packages/create-eventcatalog/create-app.ts b/packages/create-eventcatalog/create-app.ts
new file mode 100644
index 000000000..66c839da4
--- /dev/null
+++ b/packages/create-eventcatalog/create-app.ts
@@ -0,0 +1,120 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import chalk from 'chalk';
+import path from 'path';
+import { makeDir } from './helpers/make-dir';
+import { tryGitInit } from './helpers/git';
+import { installEventCatalogSkills } from './helpers/install-skills';
+
+import { isFolderEmpty } from './helpers/is-folder-empty';
+import { getOnline } from './helpers/is-online';
+import { isWriteable } from './helpers/is-writeable';
+import type { PackageManager } from './helpers/get-pkg-manager';
+
+import { installTemplate, TemplateMode, TemplateType } from './templates';
+
+export class DownloadError extends Error {}
+
+export async function createApp({
+  appPath,
+  packageManager,
+  example,
+  examplePath,
+  typescript,
+  eslint,
+  experimentalApp,
+  organizationName,
+  initEmptyProject,
+  installSkills,
+  template: templateName,
+}: {
+  appPath: string;
+  packageManager: PackageManager;
+  example?: string;
+  examplePath?: string;
+  typescript: boolean;
+  eslint: boolean;
+  experimentalApp: boolean;
+  organizationName: string;
+  initEmptyProject: boolean;
+  installSkills: boolean;
+  template?: TemplateType;
+}): Promise<void> {
+  let repoInfo: any | undefined;
+  const mode: TemplateMode = typescript ? 'ts' : 'js';
+  const template: TemplateType = initEmptyProject ? 'empty' : templateName || 'default';
+
+  const root = path.resolve(appPath);
+
+  if (!(await isWriteable(path.dirname(root)))) {
+    console.error('The application path is not writable, please check folder permissions and try again.');
+    console.error('It is likely you do not have write permissions for this folder.');
+    process.exit(1);
+  }
+
+  const appName = path.basename(root);
+
+  await makeDir(root);
+  if (!isFolderEmpty(root, appName)) {
+    process.exit(1);
+  }
+
+  const useYarn = packageManager === 'yarn';
+  const isOnline = !useYarn || (await getOnline());
+  const originalDirectory = process.cwd();
+
+  process.chdir(root);
+
+  let hasPackageJson = false;
+
+  /**
+   * If an example repository is not provided for cloning, proceed
+   * by installing from a template.
+   */
+  await installTemplate({
+    appName,
+    root,
+    template,
+    mode,
+    packageManager,
+    isOnline,
+    eslint,
+    organizationName,
+  });
+
+  const skillsInstalled = installSkills ? await installEventCatalogSkills(root) : false;
+
+  const gitInitialized = tryGitInit(root);
+
+  let cdpath: string;
+  if (path.join(originalDirectory, appName) === appPath) {
+    cdpath = appName;
+  } else {
+    cdpath = appPath;
+  }
+
+  // Summary
+  console.log();
+  console.log(chalk.green('  Project initialized!'));
+  console.log(`    ${chalk.dim('■')} Template copied`);
+  console.log(`    ${chalk.dim('■')} Dependencies installed`);
+  if (skillsInstalled) {
+    console.log(`    ${chalk.dim('■')} EventCatalog Skills installed`);
+  }
+  if (gitInitialized) {
+    console.log(`    ${chalk.dim('■')} Git initialized`);
+  }
+
+  // Next steps
+  console.log();
+  console.log(`  You're all set! Explore your catalog!`);
+  console.log();
+  console.log(`    ${chalk.dim('■')} ${chalk.cyan('cd ' + cdpath)}`);
+  console.log(`    ${chalk.dim('■')} Run ${chalk.cyan(`${packageManager} run dev`)} to start the dev server.`);
+  console.log();
+  console.log(`  ${chalk.dim('Star us on GitHub:')} ${chalk.underline('https://github.com/event-catalog/eventcatalog')}`);
+  console.log(`  ${chalk.dim('Join our Discord:')}  ${chalk.underline('https://eventcatalog.dev/discord')}`);
+  console.log();
+  console.log(`  ${chalk.dim('Want a better editing experience?')}`);
+  console.log(`  Run ${chalk.cyan(`${packageManager} run editor`)} to open EventCatalog Editor.`);
+  console.log();
+}
diff --git a/packages/create-eventcatalog/helpers/copy.ts b/packages/create-eventcatalog/helpers/copy.ts
new file mode 100644
index 000000000..4d5a418c4
--- /dev/null
+++ b/packages/create-eventcatalog/helpers/copy.ts
@@ -0,0 +1,44 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import { async as glob } from 'fast-glob';
+import path from 'path';
+import fs from 'fs';
+
+interface CopyOption {
+  cwd?: string;
+  rename?: (basename: string) => string;
+  parents?: boolean;
+}
+
+const identity = (x: string) => x;
+
+export const copy = async (src: string | string[], dest: string, { cwd, rename = identity, parents = true }: CopyOption = {}) => {
+  const source = typeof src === 'string' ? [src] : src;
+
+  if (source.length === 0 || !dest) {
+    throw new TypeError('`src` and `dest` are required');
+  }
+
+  const sourceFiles = await glob(source, {
+    cwd,
+    dot: true,
+    absolute: false,
+    stats: false,
+  });
+
+  const destRelativeToCwd = cwd ? path.resolve(cwd, dest) : dest;
+
+  return Promise.all(
+    sourceFiles.map(async (p) => {
+      const dirname = path.dirname(p);
+      const basename = rename(path.basename(p));
+
+      const from = cwd ? path.resolve(cwd, p) : p;
+      const to = parents ? path.join(destRelativeToCwd, dirname, basename) : path.join(destRelativeToCwd, basename);
+
+      // Ensure the destination directory exists
+      await fs.promises.mkdir(path.dirname(to), { recursive: true });
+
+      return fs.promises.copyFile(from, to);
+    })
+  );
+};
diff --git a/packages/create-eventcatalog/helpers/get-pkg-manager.ts b/packages/create-eventcatalog/helpers/get-pkg-manager.ts
new file mode 100644
index 000000000..f9b3474bd
--- /dev/null
+++ b/packages/create-eventcatalog/helpers/get-pkg-manager.ts
@@ -0,0 +1,17 @@
+export type PackageManager = 'npm' | 'pnpm' | 'yarn';
+
+export function getPkgManager(): PackageManager {
+  const userAgent = process.env.npm_config_user_agent;
+
+  if (userAgent) {
+    if (userAgent.startsWith('yarn')) {
+      return 'yarn';
+    } else if (userAgent.startsWith('pnpm')) {
+      return 'pnpm';
+    } else {
+      return 'npm';
+    }
+  } else {
+    return 'npm';
+  }
+}
diff --git a/packages/create-eventcatalog/helpers/git.ts b/packages/create-eventcatalog/helpers/git.ts
new file mode 100644
index 000000000..aa0d8d61d
--- /dev/null
+++ b/packages/create-eventcatalog/helpers/git.ts
@@ -0,0 +1,48 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import { execSync } from 'child_process';
+import path from 'path';
+import { sync as rimrafSync } from 'rimraf';
+
+function isInGitRepository(): boolean {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', { stdio: 'ignore' });
+    return true;
+  } catch (_) {}
+  return false;
+}
+
+function isInMercurialRepository(): boolean {
+  try {
+    execSync('hg --cwd . root', { stdio: 'ignore' });
+    return true;
+  } catch (_) {}
+  return false;
+}
+
+export function tryGitInit(root: string): boolean {
+  let didInit = false;
+  try {
+    execSync('git --version', { stdio: 'ignore' });
+    if (isInGitRepository() || isInMercurialRepository()) {
+      return false;
+    }
+
+    execSync('git init', { stdio: 'ignore' });
+    didInit = true;
+
+    execSync('git checkout -b main', { stdio: 'ignore' });
+
+    execSync('git add -A', { stdio: 'ignore' });
+    execSync('git commit -m "Initial commit from EventCatalog"', {
+      stdio: 'ignore',
+    });
+    return true;
+  } catch (e) {
+    if (didInit) {
+      try {
+        rimrafSync(path.join(root, '.git'));
+      } catch (_) {}
+    }
+    return false;
+  }
+}
diff --git a/packages/create-eventcatalog/helpers/install-skills.ts b/packages/create-eventcatalog/helpers/install-skills.ts
new file mode 100644
index 000000000..dc78b2451
--- /dev/null
+++ b/packages/create-eventcatalog/helpers/install-skills.ts
@@ -0,0 +1,26 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import spawn from 'cross-spawn';
+
+export function installEventCatalogSkills(root: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+    const child = spawn('npx', ['skills', 'add', 'event-catalog/skills'], {
+      cwd: root,
+      stdio: isInteractive ? 'inherit' : 'ignore',
+      env: {
+        ...process.env,
+        ADBLOCK: '1',
+        DISABLE_OPENCOLLECTIVE: '1',
+      },
+    });
+
+    child.on('error', () => {
+      resolve(false);
+    });
+
+    child.on('close', (code) => {
+      resolve(code === 0);
+    });
+  });
+}
diff --git a/packages/create-eventcatalog/helpers/install.ts b/packages/create-eventcatalog/helpers/install.ts
new file mode 100644
index 000000000..2c6fbd994
--- /dev/null
+++ b/packages/create-eventcatalog/helpers/install.ts
@@ -0,0 +1,127 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import chalk from 'chalk';
+import spawn from 'cross-spawn';
+import ora from 'ora';
+import type { PackageManager } from './get-pkg-manager';
+
+interface InstallArgs {
+  /**
+   * Indicate whether to install packages using npm, pnpm or Yarn.
+   */
+  packageManager: PackageManager;
+  /**
+   * Indicate whether there is an active Internet connection.
+   */
+  isOnline: boolean;
+  /**
+   * Indicate whether the given dependencies are devDependencies.
+   */
+  devDependencies?: boolean;
+}
+
+/**
+ * Spawn a package manager installation with either Yarn or NPM.
+ *
+ * @returns A Promise that resolves once the installation is finished.
+ */
+export function install(
+  root: string,
+  dependencies: string[] | null,
+  { packageManager, isOnline, devDependencies }: InstallArgs
+): Promise<void> {
+  /**
+   * (p)npm-specific command-line flags.
+   */
+  const npmFlags: string[] = [];
+  /**
+   * Yarn-specific command-line flags.
+   */
+  const yarnFlags: string[] = [];
+  /**
+   * Return a Promise that resolves once the installation is finished.
+   */
+  return new Promise((resolve, reject) => {
+    let args: string[];
+    let command = packageManager;
+    const useYarn = packageManager === 'yarn';
+
+    if (dependencies && dependencies.length) {
+      /**
+       * If there are dependencies, run a variation of `{packageManager} add`.
+       */
+      if (useYarn) {
+        /**
+         * Call `yarn add --exact (--offline)? (-D)? ...`.
+         */
+        args = ['add', '--exact'];
+        if (!isOnline) args.push('--offline');
+        args.push('--cwd', root);
+        if (devDependencies) args.push('--dev');
+        args.push(...dependencies);
+      } else {
+        /**
+         * Call `(p)npm install [--save|--save-dev] ...`.
+         */
+        args = ['install', '--save-exact'];
+        args.push(devDependencies ? '--save-dev' : '--save');
+        args.push(...dependencies);
+      }
+    } else {
+      /**
+       * If there are no dependencies, run a variation of `{packageManager}
+       * install`.
+       */
+      args = ['install'];
+      if (!isOnline) {
+        if (useYarn) {
+          args.push('--offline');
+        }
+      }
+    }
+    /**
+     * Add any package manager-specific flags.
+     */
+    if (useYarn) {
+      args.push(...yarnFlags);
+    } else {
+      args.push(...npmFlags);
+    }
+
+    const spinner = ora('Installing dependencies...').start();
+
+    /**
+     * Spawn the installation process.
+     */
+    const child = spawn(command, args, {
+      stdio: 'pipe',
+      env: {
+        ...process.env,
+        ADBLOCK: '1',
+        // we set NODE_ENV to development as pnpm skips dev
+        // dependencies when production
+        NODE_ENV: 'development',
+        DISABLE_OPENCOLLECTIVE: '1',
+      },
+    });
+
+    let stderr = '';
+    if (child.stderr) {
+      child.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+    }
+
+    child.on('close', (code) => {
+      if (code !== 0) {
+        spinner.fail('Failed to install dependencies.');
+        if (stderr) {
+          console.error(chalk.red(stderr));
+        }
+        reject({ command: `${command} ${args.join(' ')}` });
+        return;
+      }
+      spinner.succeed('Dependencies installed.');
+      resolve();
+    });
+  });
+}
diff --git a/packages/create-eventcatalog/helpers/is-folder-empty.ts b/packages/create-eventcatalog/helpers/is-folder-empty.ts
new file mode 100644
index 000000000..25861c42c
--- /dev/null
+++ b/packages/create-eventcatalog/helpers/is-folder-empty.ts
@@ -0,0 +1,58 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+
+export function isFolderEmpty(root: string, name: string): boolean {
+  const validFiles = [
+    '.DS_Store',
+    '.git',
+    '.gitattributes',
+    '.gitignore',
+    '.gitlab-ci.yml',
+    '.hg',
+    '.hgcheck',
+    '.hgignore',
+    '.idea',
+    '.npmignore',
+    '.travis.yml',
+    'LICENSE',
+    'Thumbs.db',
+    'docs',
+    'mkdocs.yml',
+    'npm-debug.log',
+    'yarn-debug.log',
+    'yarn-error.log',
+    'yarnrc.yml',
+    '.yarn',
+  ];
+
+  const conflicts = fs
+    .readdirSync(root)
+    .filter((file) => !validFiles.includes(file))
+    // Support IntelliJ IDEA-based editors
+    .filter((file) => !/\.iml$/.test(file));
+
+  if (conflicts.length > 0) {
+    console.log(`The directory ${chalk.green(name)} contains files that could conflict:`);
+    console.log();
+    for (const file of conflicts) {
+      try {
+        const stats = fs.lstatSync(path.join(root, file));
+        if (stats.isDirectory()) {
+          console.log(`  ${chalk.blue(file)}/`);
+        } else {
+          console.log(`  ${file}`);
+        }
+      } catch {
+        console.log(`  ${file}`);
+      }
+    }
+    console.log();
+    console.log('Either try using a new directory name, or remove the files listed above.');
+    console.log();
+    return false;
+  }
+
+  return true;
+}
diff --git a/packages/create-eventcatalog/helpers/is-online.ts b/packages/create-eventcatalog/helpers/is-online.ts
new file mode 100644
index 000000000..4d7774312
--- /dev/null
+++ b/packages/create-eventcatalog/helpers/is-online.ts
@@ -0,0 +1,40 @@
+import { execSync } from 'child_process';
+import dns from 'dns';
+import url from 'url';
+
+function getProxy(): string | undefined {
+  if (process.env.https_proxy) {
+    return process.env.https_proxy;
+  }
+
+  try {
+    const httpsProxy = execSync('npm config get https-proxy').toString().trim();
+    return httpsProxy !== 'null' ? httpsProxy : undefined;
+  } catch (e) {
+    return;
+  }
+}
+
+export function getOnline(): Promise<boolean> {
+  return new Promise((resolve) => {
+    dns.lookup('registry.yarnpkg.com', (registryErr) => {
+      if (!registryErr) {
+        return resolve(true);
+      }
+
+      const proxy = getProxy();
+      if (!proxy) {
+        return resolve(false);
+      }
+
+      const { hostname } = url.parse(proxy);
+      if (!hostname) {
+        return resolve(false);
+      }
+
+      dns.lookup(hostname, (proxyErr) => {
+        resolve(proxyErr == null);
+      });
+    });
+  });
+}
diff --git a/packages/create-eventcatalog/helpers/is-writeable.ts b/packages/create-eventcatalog/helpers/is-writeable.ts
new file mode 100644
index 000000000..a625c77f0
--- /dev/null
+++ b/packages/create-eventcatalog/helpers/is-writeable.ts
@@ -0,0 +1,10 @@
+import fs from 'fs';
+
+export async function isWriteable(directory: string): Promise<boolean> {
+  try {
+    await fs.promises.access(directory, (fs.constants || fs).W_OK);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
diff --git a/packages/create-eventcatalog/helpers/make-dir.ts b/packages/create-eventcatalog/helpers/make-dir.ts
new file mode 100644
index 000000000..19d61ba05
--- /dev/null
+++ b/packages/create-eventcatalog/helpers/make-dir.ts
@@ -0,0 +1,5 @@
+import fs from 'fs';
+
+export function makeDir(root: string, options = { recursive: true }): Promise<void> {
+  return fs.promises.mkdir(root, options);
+}
diff --git a/packages/create-eventcatalog/helpers/validate-pkg.ts b/packages/create-eventcatalog/helpers/validate-pkg.ts
new file mode 100644
index 000000000..de46df977
--- /dev/null
+++ b/packages/create-eventcatalog/helpers/validate-pkg.ts
@@ -0,0 +1,17 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+import validateProjectName from 'validate-npm-package-name';
+
+export function validateNpmName(name: string): {
+  valid: boolean;
+  problems?: string[];
+} {
+  const nameValidation = validateProjectName(name);
+  if (nameValidation.validForNewPackages) {
+    return { valid: true };
+  }
+
+  return {
+    valid: false,
+    problems: [...(nameValidation.errors || []), ...(nameValidation.warnings || [])],
+  };
+}
diff --git a/packages/create-eventcatalog/images/eventbridge.png b/packages/create-eventcatalog/images/eventbridge.png
new file mode 100644
index 000000000..bbb52dcf7
Binary files /dev/null and b/packages/create-eventcatalog/images/eventbridge.png differ
diff --git a/packages/create-eventcatalog/index.ts b/packages/create-eventcatalog/index.ts
new file mode 100644
index 000000000..5a9fde687
--- /dev/null
+++ b/packages/create-eventcatalog/index.ts
@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+/* eslint-disable import/no-extraneous-dependencies */
+import chalk from 'chalk';
+import Commander from 'commander';
+import path from 'path';
+import prompts from 'prompts';
+import checkForUpdate from 'update-check';
+import { createApp, DownloadError } from './create-app';
+import { getPkgManager } from './helpers/get-pkg-manager';
+import { validateNpmName } from './helpers/validate-pkg';
+import packageJson from './package.json';
+
+let projectPath: string = '';
+let organizationName: string = '';
+let installSkills: boolean = false;
+
+const program = new Commander.Command(packageJson.name)
+  .version(packageJson.version)
+  .arguments('<project-directory>')
+  .usage(`${chalk.green('<project-directory>')} [options]`)
+  .action((name, options) => {
+    projectPath = name;
+    organizationName = options.organizationName || '';
+  })
+  .option(
+    '--ts, --typescript',
+    `
+
+  Initialize as a TypeScript project. (default)
+`
+  )
+  .option(
+    '--js, --javascript',
+    `
+
+  Initialize as a JavaScript project.
+`
+  )
+  .option(
+    '--eslint',
+    `
+
+  Initialize with eslint config.
+`
+  )
+  .option(
+    '--experimental-app',
+    `
+
+  Initialize as a \`app/\` directory project.
+`
+  )
+  .option(
+    '--use-npm',
+    `
+
+  Explicitly tell the CLI to bootstrap the app using npm
+`
+  )
+  .option(
+    '--use-pnpm',
+    `
+
+  Explicitly tell the CLI to bootstrap the app using pnpm
+`
+  )
+  .option(
+    '-e, --example [name]|[github-url]',
+    `
+
+  An example to bootstrap the app with. You can use an example name
+  from the official Next.js repo or a GitHub URL. The URL can use
+  any branch and/or subdirectory
+`
+  )
+  .option(
+    '--example-path <path-to-example>',
+    `
+
+  In a rare case, your GitHub URL might contain a branch name with
+  a slash (e.g. bug/fix-1) and the path to the example (e.g. foo/bar).
+  In this case, you must specify the path to the example separately:
+  --example-path foo/bar
+`
+  )
+  .option(
+    '--organization-name [name]',
+    `
+
+  The organization name.
+`
+  )
+  .option(
+    '--template [name]',
+    `
+
+  The template to use.
+`
+  )
+  .option(
+    '--empty',
+    `
+
+  Initialize the project with an empty template.
+`
+  )
+  .allowUnknownOption()
+  .parse(process.argv);
+
+const packageManager = !!program.useNpm ? 'npm' : !!program.usePnpm ? 'pnpm' : getPkgManager();
+
+async function run(): Promise<void> {
+  console.log();
+  console.log(`  ${chalk.bgCyan.black.bold(' EventCatalog ')}  ${chalk.bold('Setup wizard')}`);
+  console.log();
+
+  if (typeof projectPath === 'string') {
+    projectPath = projectPath.trim();
+  }
+
+  if (!projectPath) {
+    const res = await prompts({
+      type: 'text',
+      name: 'path',
+      message: 'Where should we create your new project?',
+      initial: 'my-event-catalog',
+      validate: (name) => {
+        const validation = validateNpmName(path.basename(path.resolve(name)));
+        if (validation.valid) {
+          return true;
+        }
+        return 'Invalid project name: ' + validation.problems![0];
+      },
+    });
+
+    if (typeof res.path === 'string') {
+      projectPath = res.path.trim();
+    }
+  }
+
+  if (!projectPath) {
+    console.log(
+      '\nPlease specify the project directory:\n' +
+        `  ${chalk.cyan(program.name())} ${chalk.green('<project-directory>')}\n` +
+        'For example:\n' +
+        `  ${chalk.cyan(program.name())} ${chalk.green('my-event-catalog')}\n\n` +
+        `Run ${chalk.cyan(`${program.name()} --help`)} to see all options.`
+    );
+    process.exit(1);
+  }
+
+  if (!organizationName) {
+    const res = await prompts({
+      type: 'text',
+      name: 'organizationName',
+      message: 'What is your organization name?',
+      initial: 'Acme Inc',
+    });
+
+    if (typeof res.organizationName === 'string') {
+      organizationName = res.organizationName.trim();
+    }
+  }
+
+  const installSkillsResponse = await prompts({
+    type: 'confirm',
+    name: 'installSkills',
+    message: 'Would you like to install EventCatalog Skills?',
+    initial: true,
+  });
+
+  installSkills = installSkillsResponse.installSkills ?? false;
+
+  console.log();
+
+  const template = program.template || 'default';
+
+  const resolvedProjectPath = path.resolve(projectPath);
+  const projectName = path.basename(resolvedProjectPath);
+
+  const { valid, problems } = validateNpmName(projectName);
+  if (!valid) {
+    console.error(`Could not create a project called ${chalk.red(`"${projectName}"`)} because of npm naming restrictions:`);
+
+    problems!.forEach((p) => console.error(`    ${chalk.red.bold('*')} ${p}`));
+    process.exit(1);
+  }
+
+  if (program.example === true) {
+    console.error('Please provide an example name or url, otherwise remove the example option.');
+    process.exit(1);
+  }
+
+  const example = typeof program.example === 'string' && program.example.trim();
+
+  const options = program.opts();
+  const initEmptyProject = options.empty ?? false;
+
+  try {
+    await createApp({
+      appPath: resolvedProjectPath,
+      packageManager,
+      example: example && example !== 'default' ? example : undefined,
+      examplePath: program.examplePath,
+      typescript: true,
+      eslint: true,
+      experimentalApp: false,
+      organizationName: organizationName,
+      initEmptyProject,
+      installSkills,
+      template: template,
+    });
+  } catch (reason) {
+    if (!(reason instanceof DownloadError)) {
+      throw reason;
+    }
+
+    const res = await prompts({
+      type: 'confirm',
+      name: 'builtin',
+      message:
+        `Could not download "${example}" because of a connectivity issue between your machine and GitHub.\n` +
+        `Do you want to use the default template instead?`,
+      initial: true,
+    });
+    if (!res.builtin) {
+      throw reason;
+    }
+
+    await createApp({
+      appPath: resolvedProjectPath,
+      packageManager,
+      typescript: program.typescript,
+      eslint: program.eslint,
+      organizationName: organizationName,
+      experimentalApp: program.experimentalApp,
+      initEmptyProject,
+      installSkills,
+    });
+  }
+}
+
+const update = checkForUpdate(packageJson).catch(() => null);
+
+async function notifyUpdate(): Promise<void> {
+  try {
+    const res = await update;
+    if (res?.latest) {
+      const updateMessage =
+        packageManager === 'yarn'
+          ? 'yarn global add @eventcatalog/create-eventcatalog'
+          : packageManager === 'pnpm'
+            ? 'pnpm add -g @eventcatalog/create-eventcatalog'
+            : 'npm i -g @eventcatalog/create-eventcatalog';
+
+      console.log(
+        chalk.yellow.bold('A new version of `@eventcatalog/create-eventcatalog` is available!') +
+          '\n' +
+          'You can update by running: ' +
+          chalk.cyan(updateMessage) +
+          '\n'
+      );
+    }
+    process.exit();
+  } catch {
+    // ignore error
+  }
+}
+
+run()
+  .then(notifyUpdate)
+  .catch(async (reason) => {
+    console.log();
+    console.log('Aborting installation.');
+    if (reason.command) {
+      console.log(`  ${chalk.cyan(reason.command)} has failed.`);
+    } else {
+      console.log(chalk.red('Unexpected error. Please report it as a bug:') + '\n', reason);
+    }
+    console.log();
+
+    await notifyUpdate();
+
+    process.exit(1);
+  });
diff --git a/packages/create-eventcatalog/package.json b/packages/create-eventcatalog/package.json
new file mode 100644
index 000000000..e3b1180b4
--- /dev/null
+++ b/packages/create-eventcatalog/package.json
@@ -0,0 +1,59 @@
+{
+  "name": "@eventcatalog/create-eventcatalog",
+  "description": "Create EventCatalog with one command",
+  "version": "4.3.5",
+  "license": "MIT",
+  "bin": {
+    "create-catalog": "./dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/event-catalog/eventcatalog"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "pnpm run build",
+    "build": "tsup index.ts --format cjs --dts",
+    "build:bin": "tsup index.ts --format cjs --dts",
+    "test:ci": "echo 'No tests for create-eventcatalog yet'",
+    "run": "node dist/index.js",
+    "dev": "pnpm run build --watch",
+    "format": "prettier --write .",
+    "format:diff": "prettier --list-different ."
+  },
+  "devDependencies": {
+    "@types/async-retry": "1.4.2",
+    "@types/ci-info": "2.0.0",
+    "@types/cross-spawn": "6.0.0",
+    "@types/node": "^20.14.10",
+    "@types/prompts": "2.0.1",
+    "@types/rimraf": "3.0.0",
+    "@types/uuid": "^10.0.0",
+    "@types/validate-npm-package-name": "3.0.0",
+    "@vercel/ncc": "0.34.0",
+    "async-retry": "1.3.1",
+    "chalk": "2.4.2",
+    "commander": "2.20.0",
+    "cpy": "^11.0.0",
+    "cross-spawn": "6.0.6",
+    "fast-glob": "^3.3.2",
+    "ora": "^5.4.1",
+    "prettier": "^3.3.3",
+    "prompts": "2.1.0",
+    "rimraf": "^5.0.7",
+    "tsup": "^8.1.0",
+    "typescript": "^5.4.5",
+    "update-check": "1.5.4",
+    "validate-npm-package-name": "3.0.0"
+  },
+  "dependencies": {
+    "uuid": "^10.0.0"
+  },
+  "packageManager": "pnpm@10.23.0+sha512.21c4e5698002ade97e4efe8b8b4a89a8de3c85a37919f957e7a0f30f38fbc5bbdd05980ffe29179b2fb6e6e691242e098d945d1601772cad0fef5fb6411e2a4b"
+}
diff --git a/packages/create-eventcatalog/rewrite-all-md-to-mdx.sh b/packages/create-eventcatalog/rewrite-all-md-to-mdx.sh
new file mode 100644
index 000000000..6b0e4e2ff
--- /dev/null
+++ b/packages/create-eventcatalog/rewrite-all-md-to-mdx.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+
+echo "Searching for .md files to rename to .mdx..."
+
+# Find all .md files recursively and process them
+find . -type f -name "*.md" | while read -r file; do
+    if [ -f "$file" ]; then
+        newfile="${file%.md}.mdx"
+        echo "Renaming: $file -> $newfile"
+        mv "$file" "$newfile"
+    fi
+done
+
+# Check if any files were processed
+if [ -z "$(find . -type f -name "*.md")" ]; then
+    echo "No .md files found to process."
+fi
+
+echo "Done!"
+
diff --git a/packages/create-eventcatalog/templates/amazon-api-gateway/Dockerfile b/packages/create-eventcatalog/templates/amazon-api-gateway/Dockerfile
new file mode 100644
index 000000000..3405a94d2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/amazon-api-gateway/Dockerfile
@@ -0,0 +1,23 @@
+## Stage 1: Build the app
+FROM node:lts AS build
+
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+# Copy source code
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+# Build the app
+RUN npm run build
+
+
+## Stage 2: Serve app with httpd server
+FROM httpd:2.4
+
+# Copy built app to serve
+COPY --from=build /app/dist /usr/local/apache2/htdocs
diff --git a/packages/create-eventcatalog/templates/amazon-api-gateway/Dockerfile.server b/packages/create-eventcatalog/templates/amazon-api-gateway/Dockerfile.server
new file mode 100644
index 000000000..8a7332d64
--- /dev/null
+++ b/packages/create-eventcatalog/templates/amazon-api-gateway/Dockerfile.server
@@ -0,0 +1,23 @@
+# Use this Docker file if your EventCatalog output is set to `server`.
+# When EventCatalog output is set to `server`, the output will be a node server.
+# This server is required for certain features like the EventCatalog Chat (with your own keys).
+
+FROM node:lts AS runtime
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+RUN npm run build
+
+ENV HOST=0.0.0.0
+ENV PORT=3000
+EXPOSE 3000
+
+# Start the server
+CMD npm run start
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/amazon-api-gateway/README-template.md b/packages/create-eventcatalog/templates/amazon-api-gateway/README-template.md
new file mode 100644
index 000000000..ed3d2c5ab
--- /dev/null
+++ b/packages/create-eventcatalog/templates/amazon-api-gateway/README-template.md
@@ -0,0 +1,54 @@
+# Welcome to EventCatalog
+
+[EventCatalog](https://www.eventcatalog.dev/) is your architecture catalog for distributed systems. This template adds the Amazon API Gateway generator so you can import OpenAPI specs from API Gateway and document how they connect to your domains, services, and teams.
+
+## Generate Your Catalog
+
+1. Edit `.env` with your AWS settings.
+2. Configure your APIs in `eventcatalog.config.js`.
+3. Import your OpenAPI specs:
+
+```sh
+npm run generate
+```
+
+4. Start the catalog:
+
+```sh
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view your catalog.
+
+## Edit Your Catalog
+
+Your generated resources are docs-as-code. You can enrich them with ownership, domain context, Markdown, examples, and relationships that are not always available in API Gateway.
+
+Prefer a visual workflow? Run `npm run editor` to open the [EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview) and browse, create, or update catalog resources through a GitHub-backed UI.
+
+## Keep It in Sync
+
+Run `npm run generate` whenever your API Gateway APIs change. You can also run the generator in CI so your catalog stays aligned with AWS.
+
+With this integration you can:
+
+- Document APIs and OpenAPI specs
+- Assign APIs to producers and consumers
+- Connect resources to users and teams
+- Visualize your API Gateway architecture
+
+## Use AI with Architecture Context
+
+EventCatalog gives AI tools structured context about your domains, services, messages, schemas, owners, and flows. Connect an MCP-compatible tool with the [EventCatalog MCP Server](https://www.eventcatalog.dev/docs/development/guides/ai/using-mcp-server).
+
+## Learn by Task
+
+- [Amazon API Gateway integration docs](https://www.eventcatalog.dev/docs/plugins/amazon-apigateway/intro)
+- [Use the EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview)
+- [Document a service](https://www.eventcatalog.dev/docs/development/guides/services)
+- [Add events, commands, and queries](https://www.eventcatalog.dev/docs/development/guides/messages/adding-messages)
+- [Join the community](https://discord.gg/3rjaZMmrAm)
+
+## Found a Problem?
+
+Open an issue on [GitHub](https://github.com/event-catalog/generators).
diff --git a/packages/create-eventcatalog/templates/amazon-api-gateway/dockerignore b/packages/create-eventcatalog/templates/amazon-api-gateway/dockerignore
new file mode 100644
index 000000000..245063830
--- /dev/null
+++ b/packages/create-eventcatalog/templates/amazon-api-gateway/dockerignore
@@ -0,0 +1,8 @@
+.eventcatalog-core/
+.git/
+dist/
+node_modules/
+.gitignore
+.dockerignore
+Dockerfile
+README.md
diff --git a/packages/create-eventcatalog/templates/amazon-api-gateway/env b/packages/create-eventcatalog/templates/amazon-api-gateway/env
new file mode 100644
index 000000000..e2bfa248f
--- /dev/null
+++ b/packages/create-eventcatalog/templates/amazon-api-gateway/env
@@ -0,0 +1,4 @@
+
+# Get 14 day trial license key from https://eventcatalog.cloud/
+EVENTCATALOG_LICENSE_KEY_AMAZON_APIGATEWAY=
+EVENTCATALOG_LICENSE_KEY_OPENAPI=
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/amazon-api-gateway/eventcatalog.auth.js b/packages/create-eventcatalog/templates/amazon-api-gateway/eventcatalog.auth.js
new file mode 100644
index 000000000..f97044604
--- /dev/null
+++ b/packages/create-eventcatalog/templates/amazon-api-gateway/eventcatalog.auth.js
@@ -0,0 +1,44 @@
+/**
+ * This is an optional file that can add authentication to your EventCatalog.
+ *
+ * To enable authentication you need to set `server:output` in your `eventcatalog.config.js` file.
+ * And then pick which provider you want to use.
+ *
+ * You can read more in the documentation:
+ * https://www.eventcatalog.dev/docs/development/guides/authentication/introduction
+ *
+ */
+
+// export default {
+//   debug: false,
+//   providers: {
+//     // GitHub Authentication
+//     github: {
+//       clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+//       clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+//     },
+//     // Azure AD Entra ID
+//     entra: {
+//       clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
+//       clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
+//       issuer: process.env.AUTH_MICROSOFT_ENTRA_ID_ISSUER,
+//     },
+//     // Google Authentication
+//     google: {
+//       clientId: process.env.AUTH_GOOGLE_ID,
+//       clientSecret: process.env.AUTH_GOOGLE_SECRET,
+//     },
+//     // Auth0 Authentication
+//     auth0: {
+//       clientId: process.env.AUTH_AUTH0_ID,
+//       clientSecret: process.env.AUTH_AUTH0_SECRET,
+//       issuer: process.env.AUTH_AUTH0_ISSUER,
+//     },
+//     // Okta Authentication
+//     okta: {
+//       clientId: process.env.AUTH_OKTA_CLIENT_ID,
+//       clientSecret: process.env.AUTH_OKTA_CLIENT_SECRET,
+//       issuer: process.env.AUTH_OKTA_ISSUER,
+//     },
+//   },
+// }
diff --git a/packages/create-eventcatalog/templates/amazon-api-gateway/eventcatalog.config.js b/packages/create-eventcatalog/templates/amazon-api-gateway/eventcatalog.config.js
new file mode 100644
index 000000000..8bb33e9a5
--- /dev/null
+++ b/packages/create-eventcatalog/templates/amazon-api-gateway/eventcatalog.config.js
@@ -0,0 +1,83 @@
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  title: 'EventCatalog',
+  tagline:
+    'This internal platform provides a comprehensive view of our event-driven architecture across all systems. Use this portal to discover EventBridge schemas, services and domains, and understand the message contracts that connect our infrastructure',
+  organizationName: '<organizationName>',
+  theme: 'sunset',
+  homepageLink: 'https://eventcatalog.dev/',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  // Supports static or server. Static renders a static site, server renders a server side rendered site
+  // large catalogs may benefit from server side rendering
+  output: 'static',
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: '/',
+  // Resource search is the default lightweight search. Change this to { type: 'indexed' }
+  // to enable full-content search. Indexed search requires running a build to generate the index.
+  search: {
+    type: 'resource',
+  },
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'EventCatalog',
+  },
+  // Enable RSS feed for your eventcatalog
+  rss: {
+    enabled: true,
+    // number of items to include in the feed per resource (event, service, etc)
+    limit: 20,
+  },
+  docs: {
+    sidebar: {
+      // TREE_VIEW will render the DOCS as a tree view and map your file system folder structure
+      // LIST_VIEW will render the DOCS that look familiar to API documentation websites
+      type: 'LIST_VIEW',
+    },
+  },
+  // This lets you copy markdown contents from EventCatalog to your clipboard
+  // Including schemas for your events and services
+  llmsTxt: {
+    enabled: true,
+  },
+  // required random generated id used by eventcatalog
+  cId: '<cId>',
+  generators: [
+    [
+      '@eventcatalog/generator-amazon-apigateway',
+      {
+        output: 'amazon-api-gateway-output',
+        apis: [
+          {
+            // The name of the API we want to process
+            name: 'EcommerceApi',
+            // Assume it's deployed to us-east-1, change this if you deployed somewhere else
+            region: 'us-east-1',
+            // The API stage name
+            stageName: 'prod',
+            version: '2',
+          },
+        ],
+      },
+    ],
+    // This will process the output of the amazon api gateway generator
+    // it will process the OpenAPI file and map it into a service and domain
+    // All routes are mapped to messages.
+    [
+      '@eventcatalog/generator-openapi',
+      {
+        services: [
+          {
+            path: path.join(__dirname, 'amazon-api-gateway-output', 'EcommerceApi.json'),
+            id: 'ecommerce-api',
+            owners: ['full-stack'],
+          },
+        ],
+      },
+    ],
+  ],
+};
diff --git a/packages/create-eventcatalog/templates/amazon-api-gateway/eventcatalog.styles.css b/packages/create-eventcatalog/templates/amazon-api-gateway/eventcatalog.styles.css
new file mode 100644
index 000000000..0d75d2602
--- /dev/null
+++ b/packages/create-eventcatalog/templates/amazon-api-gateway/eventcatalog.styles.css
@@ -0,0 +1 @@
+/* Custom styling support coming soon. */
diff --git a/packages/create-eventcatalog/templates/amazon-api-gateway/gitignore b/packages/create-eventcatalog/templates/amazon-api-gateway/gitignore
new file mode 100644
index 000000000..b6eaa6d14
--- /dev/null
+++ b/packages/create-eventcatalog/templates/amazon-api-gateway/gitignore
@@ -0,0 +1,29 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.astro
+out
+dist
+
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.eventcatalog-core
+
+.env
+.env-*
+
+exports/*
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/amazon-api-gateway/npmrc b/packages/create-eventcatalog/templates/amazon-api-gateway/npmrc
new file mode 100644
index 000000000..fa4e09523
--- /dev/null
+++ b/packages/create-eventcatalog/templates/amazon-api-gateway/npmrc
@@ -0,0 +1 @@
+strict-peer-dependencies=false
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/amazon-api-gateway/public/logo.png b/packages/create-eventcatalog/templates/amazon-api-gateway/public/logo.png
new file mode 100644
index 000000000..535b5a0e7
Binary files /dev/null and b/packages/create-eventcatalog/templates/amazon-api-gateway/public/logo.png differ
diff --git a/packages/create-eventcatalog/templates/analytics.ts b/packages/create-eventcatalog/templates/analytics.ts
new file mode 100644
index 000000000..c5bb1bc5a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/analytics.ts
@@ -0,0 +1,38 @@
+import os from 'os';
+import pkg from '../package.json';
+
+interface EventMetadata {
+  command: string;
+  org: string;
+  cId: string;
+}
+
+async function raiseEvent(eventData: EventMetadata): Promise<void> {
+  const url = 'https://queue.simpleanalyticscdn.com/events';
+  const userAgent = `@eventcatalog/create-eventcatalog/${pkg.version} (${os.platform()}; ${os.arch()}; Node/${process.version})`;
+
+  const payload = {
+    type: 'event',
+    hostname: 'eventcatalog.dev',
+    event: '@eventcatalog/create-eventcatalog',
+    metadata: {
+      ...eventData,
+      t: `t;${new Date().toISOString()}`,
+      ua: userAgent,
+    },
+    ua: userAgent,
+  };
+
+  try {
+    await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+  } catch (error) {
+    // swallow the error
+  }
+}
+
+// Export the function so it can be used in other parts of the application
+export { raiseEvent };
diff --git a/packages/create-eventcatalog/templates/asyncapi/Dockerfile b/packages/create-eventcatalog/templates/asyncapi/Dockerfile
new file mode 100644
index 000000000..3405a94d2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/Dockerfile
@@ -0,0 +1,23 @@
+## Stage 1: Build the app
+FROM node:lts AS build
+
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+# Copy source code
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+# Build the app
+RUN npm run build
+
+
+## Stage 2: Serve app with httpd server
+FROM httpd:2.4
+
+# Copy built app to serve
+COPY --from=build /app/dist /usr/local/apache2/htdocs
diff --git a/packages/create-eventcatalog/templates/asyncapi/Dockerfile.server b/packages/create-eventcatalog/templates/asyncapi/Dockerfile.server
new file mode 100644
index 000000000..8a7332d64
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/Dockerfile.server
@@ -0,0 +1,23 @@
+# Use this Docker file if your EventCatalog output is set to `server`.
+# When EventCatalog output is set to `server`, the output will be a node server.
+# This server is required for certain features like the EventCatalog Chat (with your own keys).
+
+FROM node:lts AS runtime
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+RUN npm run build
+
+ENV HOST=0.0.0.0
+ENV PORT=3000
+EXPOSE 3000
+
+# Start the server
+CMD npm run start
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/asyncapi/README-template.md b/packages/create-eventcatalog/templates/asyncapi/README-template.md
new file mode 100644
index 000000000..2daa8c517
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/README-template.md
@@ -0,0 +1,63 @@
+# Welcome to EventCatalog
+
+[EventCatalog](https://www.eventcatalog.dev/) is your architecture catalog for distributed systems. Use it to document, govern, and discover your services, domains, APIs, events, commands, queries, schemas, teams, and flows in one place.
+
+## Start the Catalog
+
+```sh
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view your catalog.
+
+Using `pnpm` or `yarn`? Run the same scripts with the package manager you chose when creating this project.
+
+## Edit Your Catalog
+
+Your catalog is docs-as-code. Resources live in folders with an `index.mdx` file for frontmatter metadata and Markdown content.
+
+Good places to start:
+
+- `domains/` - bounded contexts, business capabilities, and ownership
+- `domains/<domain>/services/` - services, APIs, and message producers or consumers
+- `events/`, `commands/`, and `queries/` - the messages flowing through your system
+- `teams/` and `users/` - who owns each part of the architecture
+
+Prefer a visual workflow? Run `npm run editor` to open the [EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview) and browse, create, or update catalog resources through a GitHub-backed UI.
+
+## Make Your First Change
+
+1. Add or edit a domain, service, or message.
+2. Run `npm run dev` and check the generated pages and diagrams.
+3. Commit the MDX and schema files to Git.
+
+## Keep It in Sync
+
+Use `npm run generate` with [EventCatalog integrations](https://www.eventcatalog.dev/integrations) to import architecture data from OpenAPI, AsyncAPI, schema registries, EventBridge, GitHub, internal systems, and more.
+
+Run generators locally while you work, or in CI so your catalog stays aligned with the systems it describes.
+
+## Use AI with Architecture Context
+
+EventCatalog gives AI tools structured context about your domains, services, messages, schemas, owners, and flows.
+
+- Connect Claude, Cursor, VS Code, Windsurf, or another MCP-compatible tool with the [EventCatalog MCP Server](https://www.eventcatalog.dev/docs/development/guides/ai/using-mcp-server).
+- Install [EventCatalog Skills](https://github.com/event-catalog/skills) to help agents document services, create domain models, and map business flows:
+
+```sh
+npx skills add event-catalog/skills
+```
+
+## Learn by Task
+
+- [Create a domain](https://www.eventcatalog.dev/docs/development/guides/domains)
+- [Document a service](https://www.eventcatalog.dev/docs/development/guides/services)
+- [Add events, commands, and queries](https://www.eventcatalog.dev/docs/development/guides/messages/adding-messages)
+- [Use the EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview)
+- [Generate from integrations](https://www.eventcatalog.dev/integrations)
+- [Manage your catalog with the SDK](https://www.eventcatalog.dev/docs/development/sdk)
+- [Join the community](https://discord.gg/3rjaZMmrAm)
+
+## Found a Problem?
+
+Open an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).
diff --git a/packages/create-eventcatalog/templates/asyncapi/asyncapi-files/messages/user-signed-up.yml b/packages/create-eventcatalog/templates/asyncapi/asyncapi-files/messages/user-signed-up.yml
new file mode 100644
index 000000000..c37578702
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/asyncapi-files/messages/user-signed-up.yml
@@ -0,0 +1,44 @@
+UserSignedUp:
+  name: UserSignedUp
+  title: User signup
+  summary: Action to sign a user up.
+  description: A longer description of the signup process
+  contentType: application/json
+  payload:
+    type: object
+    properties:
+      fullName:
+        description: 'The full name of the user.'
+        type: string
+        example: 'John Doe'
+      email:
+        description: "User's email address."
+        type: string
+        format: email
+        example: 'john.doe@example.com'
+      password:
+        description: "User's account password."
+        type: string
+        format: password
+        minLength: 8
+        example: 'password123'
+      dateOfBirth:
+        description: "User's date of birth."
+        type: string
+        format: date
+        example: '1990-01-01'
+      phoneNumber:
+        description: "User's phone number (optional)."
+        type: string
+        pattern: "^\\+?[1-9]\\d{1,14}$"
+        example: '+1234567890'
+      termsAccepted:
+        description: 'Whether the user has accepted the terms and conditions.'
+        type: boolean
+        example: true
+    required:
+      - fullName
+      - email
+      - password
+      - termsAccepted
+    additionalProperties: false
diff --git a/packages/create-eventcatalog/templates/asyncapi/asyncapi-files/orders-service.yml b/packages/create-eventcatalog/templates/asyncapi/asyncapi-files/orders-service.yml
new file mode 100644
index 000000000..03785bee6
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/asyncapi-files/orders-service.yml
@@ -0,0 +1,272 @@
+asyncapi: 3.0.0
+info:
+  title: Orders Service
+  version: 1.0.1
+  description: This service is in charge of processing orders
+
+operations:
+  sendOrderCreated:
+    action: send
+    channel:
+      $ref: '#/channels/orderCreated'
+    messages:
+      - $ref: '#/channels/orderCreated/messages/OrderCreated'
+
+  sendOrderUpdated:
+    action: send
+    channel:
+      $ref: '#/channels/orderUpdated'
+    messages:
+      - $ref: '#/channels/orderUpdated/messages/OrderUpdated'
+
+  sendOrderCancelled:
+    action: send
+    channel:
+      $ref: '#/channels/orderCancelled'
+    messages:
+      - $ref: '#/channels/orderCancelled/messages/OrderCancelled'
+
+  sendOrderCompleted:
+    action: send
+    channel:
+      $ref: '#/channels/orderCompleted'
+    messages:
+      - $ref: '#/channels/orderCompleted/messages/OrderCompleted'
+
+  receivePaymentProcessed:
+    action: receive
+    channel:
+      $ref: '#/channels/paymentProcessed'
+    messages:
+      - $ref: '#/channels/paymentProcessed/messages/PaymentProcessed'
+
+  receiveInventoryReserved:
+    action: receive
+    channel:
+      $ref: '#/channels/inventoryReserved'
+    messages:
+      - $ref: '#/channels/inventoryReserved/messages/InventoryReserved'
+
+  receiveShipmentDelivered:
+    action: receive
+    channel:
+      $ref: '#/channels/shipmentDelivered'
+    messages:
+      - $ref: '#/channels/shipmentDelivered/messages/ShipmentDelivered'
+
+channels:
+  orderCreated:
+    address: order/created
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+
+  orderUpdated:
+    address: order/updated
+    messages:
+      OrderUpdated:
+        $ref: '#/components/messages/OrderUpdated'
+
+  orderCancelled:
+    address: order/cancelled
+    messages:
+      OrderCancelled:
+        $ref: '#/components/messages/OrderCancelled'
+
+  orderCompleted:
+    address: order/completed
+    messages:
+      OrderCompleted:
+        $ref: '#/components/messages/OrderCompleted'
+
+  paymentProcessed:
+    address: payment/processed
+    messages:
+      PaymentProcessed:
+        $ref: '#/components/messages/PaymentProcessed'
+
+  inventoryReserved:
+    address: inventory/reserved
+    messages:
+      InventoryReserved:
+        $ref: '#/components/messages/InventoryReserved'
+
+  shipmentDelivered:
+    address: shipment/delivered
+    messages:
+      ShipmentDelivered:
+        $ref: '#/components/messages/ShipmentDelivered'
+
+components:
+  messages:
+    OrderCreated:
+      description: 'Event triggered when an order is created'
+      x-eventcatalog-message-type: event
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            description: Unique identifier for the order
+          userId:
+            type: string
+            description: Unique identifier for the user who placed the order
+          totalAmount:
+            type: number
+            format: float
+            description: Total amount of the order
+          items:
+            type: array
+            description: List of items in the order
+            items:
+              type: object
+              properties:
+                itemId:
+                  type: string
+                  description: Unique identifier for the item
+                quantity:
+                  type: integer
+                  description: Quantity of the item ordered
+                price:
+                  type: number
+                  format: float
+                  description: Price of the item
+
+    OrderUpdated:
+      description: 'Event triggered when an order is updated'
+      x-eventcatalog-message-type: event
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            description: Unique identifier for the order
+          updatedFields:
+            type: object
+            description: Fields that were updated in the order
+            additionalProperties: true
+
+    OrderCancelled:
+      description: 'Event triggered when an order is cancelled'
+      x-eventcatalog-message-type: event
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            description: Unique identifier for the order
+          reason:
+            type: string
+            description: Reason for the order cancellation
+
+    OrderCompleted:
+      description: 'Event triggered when an order is completed'
+      x-eventcatalog-message-type: event
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            description: Unique identifier for the order
+          completionTime:
+            type: string
+            format: date-time
+            description: Time when the order was completed
+
+    PaymentProcessed:
+      description: 'Event triggered when a payment is processed'
+      x-eventcatalog-message-type: event
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            description: Unique identifier for the order
+          paymentId:
+            type: string
+            description: Unique identifier for the payment
+          status:
+            type: string
+            description: Status of the payment
+
+    InventoryReserved:
+      description: 'Event triggered when inventory is reserved for an order'
+      x-eventcatalog-message-type: event
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            description: Unique identifier for the order
+          reservationId:
+            type: string
+            description: Unique identifier for the inventory reservation
+          status:
+            type: string
+            description: Status of the inventory reservation
+
+    ShipmentDelivered:
+      description: 'Event triggered when a shipment is delivered'
+      x-eventcatalog-message-type: event
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            description: Unique identifier for the order
+          shipmentId:
+            type: string
+            description: Unique identifier for the shipment
+          deliveryTime:
+            type: string
+            format: date-time
+            description: Time when the shipment was delivered
diff --git a/packages/create-eventcatalog/templates/asyncapi/asyncapi-files/payment-service.yml b/packages/create-eventcatalog/templates/asyncapi/asyncapi-files/payment-service.yml
new file mode 100644
index 000000000..1d86e958e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/asyncapi-files/payment-service.yml
@@ -0,0 +1,245 @@
+asyncapi: 3.0.0
+info:
+  title: Payments Service
+  version: 1.0.2
+  description: This service handles the payment processing for various transactions.
+
+operations:
+  sendPaymentInitiated:
+    action: send
+    channel:
+      $ref: '#/channels/paymentInitiated'
+    messages:
+      - $ref: '#/channels/paymentInitiated/messages/PaymentInitiated'
+
+  sendPaymentConfirmed:
+    action: send
+    channel:
+      $ref: '#/channels/paymentConfirmed'
+    messages:
+      - $ref: '#/channels/paymentConfirmed/messages/PaymentConfirmed'
+
+  sendPaymentFailed:
+    action: send
+    channel:
+      $ref: '#/channels/paymentFailed'
+    messages:
+      - $ref: '#/channels/paymentFailed/messages/PaymentFailed'
+
+  sendRefundInitiated:
+    action: send
+    channel:
+      $ref: '#/channels/refundInitiated'
+    messages:
+      - $ref: '#/channels/refundInitiated/messages/RefundInitiated'
+
+  sendRefundCompleted:
+    action: send
+    channel:
+      $ref: '#/channels/refundCompleted'
+    messages:
+      - $ref: '#/channels/refundCompleted/messages/RefundCompleted'
+
+  receiveTransactionVerified:
+    action: receive
+    channel:
+      $ref: '#/channels/transactionVerified'
+    messages:
+      - $ref: '#/channels/transactionVerified/messages/TransactionVerified'
+
+channels:
+  paymentInitiated:
+    address: payment/initiated
+    messages:
+      PaymentInitiated:
+        $ref: '#/components/messages/PaymentInitiated'
+
+  paymentConfirmed:
+    address: payment/confirmed
+    messages:
+      PaymentConfirmed:
+        $ref: '#/components/messages/PaymentConfirmed'
+
+  paymentFailed:
+    address: payment/failed
+    messages:
+      PaymentFailed:
+        $ref: '#/components/messages/PaymentFailed'
+
+  refundInitiated:
+    address: refund/initiated
+    messages:
+      RefundInitiated:
+        $ref: '#/components/messages/RefundInitiated'
+
+  refundCompleted:
+    address: refund/completed
+    messages:
+      RefundCompleted:
+        $ref: '#/components/messages/RefundCompleted'
+
+  transactionVerified:
+    address: transaction/verified
+    messages:
+      TransactionVerified:
+        $ref: '#/components/messages/TransactionVerified'
+
+components:
+  messages:
+    PaymentInitiated:
+      description: 'Event triggered when a payment is initiated'
+      x-eventcatalog-message-type: event
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          paymentId:
+            type: string
+            description: Unique identifier for the payment
+          orderId:
+            type: string
+            description: Unique identifier for the related order
+          amount:
+            type: number
+            format: float
+            description: Amount to be paid
+          currency:
+            type: string
+            description: Currency in which the payment is made
+
+    PaymentConfirmed:
+      description: 'Event triggered when a payment is confirmed'
+      x-eventcatalog-message-type: event
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          paymentId:
+            type: string
+            description: Unique identifier for the payment
+          orderId:
+            type: string
+            description: Unique identifier for the related order
+          confirmationTime:
+            type: string
+            format: date-time
+            description: Time when the payment was confirmed
+          status:
+            type: string
+            description: Status of the payment confirmation
+
+    PaymentFailed:
+      description: 'Event triggered when a payment fails'
+      x-eventcatalog-message-type: event
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          paymentId:
+            type: string
+            description: Unique identifier for the payment
+          orderId:
+            type: string
+            description: Unique identifier for the related order
+          failureReason:
+            type: string
+            description: Reason for the payment failure
+
+    RefundInitiated:
+      description: 'Event triggered when a refund is initiated'
+      x-eventcatalog-message-type: event
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          refundId:
+            type: string
+            description: Unique identifier for the refund
+          paymentId:
+            type: string
+            description: Unique identifier for the related payment
+          amount:
+            type: number
+            format: float
+            description: Amount to be refunded
+          currency:
+            type: string
+            description: Currency in which the refund is made
+          createdAt:
+            type: string
+            description: ISO Date String of when the refund was initiated
+
+    RefundCompleted:
+      description: 'Event triggered when a refund is completed'
+      x-eventcatalog-message-type: event
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: event
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          refundId:
+            type: string
+            description: Unique identifier for the refund
+          paymentId:
+            type: string
+            description: Unique identifier for the related payment
+          completionTime:
+            type: string
+            format: date-time
+            description: Time when the refund was completed
+          status:
+            type: string
+            description: Status of the refund process
+
+    TransactionVerified:
+      description: 'Command triggered when a transaction is verified'
+      x-eventcatalog-message-type: command
+      headers:
+        type: object
+        properties:
+          ec-message-type:
+            type: string
+            default: command
+            description: Type of message for EventCatalog
+      payload:
+        type: object
+        properties:
+          transactionId:
+            type: string
+            description: Unique identifier for the transaction
+          verificationTime:
+            type: string
+            format: date-time
+            description: Time when the transaction was verified
+          status:
+            type: string
+            description: Verification status of the transaction
diff --git a/packages/create-eventcatalog/templates/asyncapi/asyncapi-files/user-service.yml b/packages/create-eventcatalog/templates/asyncapi/asyncapi-files/user-service.yml
new file mode 100644
index 000000000..2d85c347f
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/asyncapi-files/user-service.yml
@@ -0,0 +1,23 @@
+asyncapi: 3.0.0
+info:
+  title: USService
+  description: description
+  version: 1.1.0
+
+channels:
+  randomChannel:
+    address: myAddress
+    messages:
+      UserSignup:
+        $ref: '#/components/schemas/UserSignedUp/schema'
+operations:
+  sendNoise:
+    action: send
+    channel:
+      $ref: '#/channels/randomChannel'
+components:
+  schemas:
+    UserSignedUp:
+      schemaFormat: 'application/schema+json;version=draft-07'
+      schema:
+        '$ref': './messages/user-signed-up.yml#/UserSignedUp'
diff --git a/packages/create-eventcatalog/templates/asyncapi/dockerignore b/packages/create-eventcatalog/templates/asyncapi/dockerignore
new file mode 100644
index 000000000..245063830
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/dockerignore
@@ -0,0 +1,8 @@
+.eventcatalog-core/
+.git/
+dist/
+node_modules/
+.gitignore
+.dockerignore
+Dockerfile
+README.md
diff --git a/packages/create-eventcatalog/templates/asyncapi/env b/packages/create-eventcatalog/templates/asyncapi/env
new file mode 100644
index 000000000..3ca39cda3
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/env
@@ -0,0 +1,9 @@
+# EventCatalog Scale License Key, if you want to unlock the scale features
+# You can get a 14 day trial license key from https://eventcatalog.cloud
+
+EVENTCATALOG_SCALE_LICENSE_KEY=
+
+# Optional key if you are using EventCatalog Chat with OpenAI Models.
+# You need to set `output` to `server` in your eventcatalog.config.js file.
+# See documentation for more details: https://www.eventcatalog.dev/features/ai-assistant
+OPENAI_API_KEY=
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/asyncapi/eventcatalog.auth.js b/packages/create-eventcatalog/templates/asyncapi/eventcatalog.auth.js
new file mode 100644
index 000000000..f97044604
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/eventcatalog.auth.js
@@ -0,0 +1,44 @@
+/**
+ * This is an optional file that can add authentication to your EventCatalog.
+ *
+ * To enable authentication you need to set `server:output` in your `eventcatalog.config.js` file.
+ * And then pick which provider you want to use.
+ *
+ * You can read more in the documentation:
+ * https://www.eventcatalog.dev/docs/development/guides/authentication/introduction
+ *
+ */
+
+// export default {
+//   debug: false,
+//   providers: {
+//     // GitHub Authentication
+//     github: {
+//       clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+//       clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+//     },
+//     // Azure AD Entra ID
+//     entra: {
+//       clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
+//       clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
+//       issuer: process.env.AUTH_MICROSOFT_ENTRA_ID_ISSUER,
+//     },
+//     // Google Authentication
+//     google: {
+//       clientId: process.env.AUTH_GOOGLE_ID,
+//       clientSecret: process.env.AUTH_GOOGLE_SECRET,
+//     },
+//     // Auth0 Authentication
+//     auth0: {
+//       clientId: process.env.AUTH_AUTH0_ID,
+//       clientSecret: process.env.AUTH_AUTH0_SECRET,
+//       issuer: process.env.AUTH_AUTH0_ISSUER,
+//     },
+//     // Okta Authentication
+//     okta: {
+//       clientId: process.env.AUTH_OKTA_CLIENT_ID,
+//       clientSecret: process.env.AUTH_OKTA_CLIENT_SECRET,
+//       issuer: process.env.AUTH_OKTA_ISSUER,
+//     },
+//   },
+// }
diff --git a/packages/create-eventcatalog/templates/asyncapi/eventcatalog.config.js b/packages/create-eventcatalog/templates/asyncapi/eventcatalog.config.js
new file mode 100644
index 000000000..fc3d502d5
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/eventcatalog.config.js
@@ -0,0 +1,89 @@
+import path from 'path';
+import url from 'url';
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  title: 'EventCatalog',
+  tagline:
+    'This internal platform provides a comprehensive view of our event-driven architecture across all systems. Use this portal to discover existing domains, explore services and their dependencies, and understand the message contracts that connect our infrastructure',
+  organizationName: '<organizationName>',
+  theme: 'sunset',
+  homepageLink: 'https://eventcatalog.dev/',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  // Supports static or server. Static renders a static site, server renders a server side rendered site
+  // large catalogs may benefit from server side rendering
+  output: 'static',
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: '/',
+  // Resource search is the default lightweight search. Change this to { type: 'indexed' }
+  // to enable full-content search. Indexed search requires running a build to generate the index.
+  search: {
+    type: 'resource',
+  },
+  // Customize the navigation for your docs sidebar.
+  // read more at https://eventcatalog.dev/docs/development/customization/customize-sidebars/documentation-sidebar
+  navigation: {
+    pages: ['list:all'],
+  },
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'EventCatalog',
+  },
+  // This lets you copy markdown contents from EventCatalog to your clipboard
+  // Including schemas for your events and services
+  llmsTxt: {
+    enabled: true,
+  },
+  generators: [
+    [
+      '@eventcatalog/generator-asyncapi',
+      {
+        services: [
+          {
+            path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'),
+            owners: ['order-management'],
+            id: 'Orders Service',
+          },
+        ],
+        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+      },
+    ],
+    [
+      '@eventcatalog/generator-asyncapi',
+      {
+        services: [
+          {
+            path: path.join(__dirname, 'asyncapi-files', 'payment-service.yml'),
+            owners: ['order-management'],
+            id: 'Payment Service',
+          },
+        ],
+        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
+      },
+    ],
+    [
+      '@eventcatalog/generator-asyncapi',
+      {
+        services: [
+          { path: path.join(__dirname, 'asyncapi-files', 'user-service.yml'), owners: ['user-management'], id: 'User Service' },
+        ],
+        domain: { id: 'user-domain', name: 'User Domain', version: '0.0.1' },
+        debug: true,
+      },
+    ],
+  ],
+  // Enable RSS feed for your eventcatalog
+  rss: {
+    enabled: true,
+    // number of items to include in the feed per resource (event, service, etc)
+    limit: 20,
+  },
+  // required random generated id used by eventcatalog
+  cId: '<cId>',
+};
diff --git a/packages/create-eventcatalog/templates/asyncapi/eventcatalog.styles.css b/packages/create-eventcatalog/templates/asyncapi/eventcatalog.styles.css
new file mode 100644
index 000000000..0d75d2602
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/eventcatalog.styles.css
@@ -0,0 +1 @@
+/* Custom styling support coming soon. */
diff --git a/packages/create-eventcatalog/templates/asyncapi/gitignore b/packages/create-eventcatalog/templates/asyncapi/gitignore
new file mode 100644
index 000000000..b6eaa6d14
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/gitignore
@@ -0,0 +1,29 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.astro
+out
+dist
+
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.eventcatalog-core
+
+.env
+.env-*
+
+exports/*
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/asyncapi/npmrc b/packages/create-eventcatalog/templates/asyncapi/npmrc
new file mode 100644
index 000000000..fa4e09523
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/npmrc
@@ -0,0 +1 @@
+strict-peer-dependencies=false
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/asyncapi/public/logo.png b/packages/create-eventcatalog/templates/asyncapi/public/logo.png
new file mode 100644
index 000000000..535b5a0e7
Binary files /dev/null and b/packages/create-eventcatalog/templates/asyncapi/public/logo.png differ
diff --git a/packages/create-eventcatalog/templates/asyncapi/teams/order-management.mdx b/packages/create-eventcatalog/templates/asyncapi/teams/order-management.mdx
new file mode 100644
index 000000000..586d8cdaf
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/teams/order-management.mdx
@@ -0,0 +1,31 @@
+---
+id: order-management
+name: Order Management
+summmary: Order Management team based in London, UK
+members:
+  - dboyne
+  - asmith
+  - msmith
+  - alee
+  - azhang
+email: test@test.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+---
+
+## Overview
+
+The Order Management team is responsible for managing orders, inventory, shipment and payment.
+
+## Responsibilities
+
+- Manage orders and order processing
+- Manage inventory and inventory processing
+- Manage shipment and shipment processing
+- Manage payment and payment processing
+- Manage user and user processing
+
+## Key Contacts
+
+- David Boyne
+- Alice Smith
+- Mike Smith
diff --git a/packages/create-eventcatalog/templates/asyncapi/teams/user-management.mdx b/packages/create-eventcatalog/templates/asyncapi/teams/user-management.mdx
new file mode 100644
index 000000000..fa32246bb
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/teams/user-management.mdx
@@ -0,0 +1,18 @@
+---
+id: user-management
+name: User Management
+members:
+  - dboyne
+  - jbrown
+  - dkim
+---
+
+The user management team is responsible for managing users and user accounts.
+
+## Responsibilities
+
+- Manage user and user account management
+- Manage user and user account provisioning
+- Manage user and user account deprovisioning
+- Manage user and user account password management
+- Manage user and user account role management
diff --git a/packages/create-eventcatalog/templates/asyncapi/users/aSmith.mdx b/packages/create-eventcatalog/templates/asyncapi/users/aSmith.mdx
new file mode 100644
index 000000000..db9809431
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/users/aSmith.mdx
@@ -0,0 +1,26 @@
+---
+id: asmith
+name: Amy Smith
+avatarUrl: https://randomuser.me/api/portraits/women/48.jpg
+role: Product owner
+---
+
+Hello! I'm Amy Smith, the Product Owner of the innovative Full Stackers team. With a strong focus on delivering exceptional value, I specialize in connecting business objectives with technical solutions to create products that users love.
+
+### About Me
+
+With a comprehensive background in product management and a solid understanding of software development, I bring a unique perspective to the table. My career has been driven by a passion for understanding user needs, defining clear product visions, and leading teams to successful product deliveries.
+
+### What I Do
+
+As the Product Owner for Full Stackers, my role involves a wide range of responsibilities aimed at ensuring our products are both high-quality and user-centric. Key aspects of my role include:
+
+- **Product Vision & Strategy**: Defining and communicating the long-term vision and strategy for our products, ensuring alignment with the company's objectives and market demands.
+- **Roadmap Planning**: Developing and maintaining a product roadmap that highlights key features and milestones, prioritizing tasks based on their business value and user feedback.
+- **Stakeholder Management**: Engaging with stakeholders across the organization to gather requirements, provide updates, and ensure everyone is aligned on the product's direction.
+- **User-Centric Design**: Championing the end-users by conducting user research, analyzing feedback, and ensuring our products effectively solve their problems.
+- **Agile Leadership**: Leading the development process using Agile methodologies, facilitating sprint planning, and ensuring the team has clear priorities and objectives.
+
+My mission is to deliver products that not only meet but exceed customer expectations. I thrive on the challenge of translating complex requirements into simple, intuitive solutions.
+
+If you’re interested in product management, user experience, or discussing the latest trends in technology, feel free to reach out!
diff --git a/packages/create-eventcatalog/templates/asyncapi/users/alee.mdx b/packages/create-eventcatalog/templates/asyncapi/users/alee.mdx
new file mode 100644
index 000000000..ae34f1820
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/users/alee.mdx
@@ -0,0 +1,8 @@
+---
+id: alee
+name: Alice Lee
+avatarUrl: https://randomuser.me/api/portraits/women/91.jpg
+role: Technical Writer
+---
+
+As a Technical Writer on the Documentation team, I create clear, comprehensive documentation for our products and APIs. My focus is on making complex technical concepts accessible to developers and end-users alike. I collaborate with engineering teams to ensure our documentation stays current and accurate.
diff --git a/packages/create-eventcatalog/templates/asyncapi/users/azhang.mdx b/packages/create-eventcatalog/templates/asyncapi/users/azhang.mdx
new file mode 100644
index 000000000..0f0a15616
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/users/azhang.mdx
@@ -0,0 +1,11 @@
+---
+id: azhang
+name: Alice Zhang
+avatarUrl: https://randomuser.me/api/portraits/women/97.jpg
+role: Data Engineer
+email: azhang@company.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/azhang
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=azhang@company.com
+---
+
+Building and maintaining data pipelines and infrastructure...
diff --git a/packages/create-eventcatalog/templates/asyncapi/users/dboyne.mdx b/packages/create-eventcatalog/templates/asyncapi/users/dboyne.mdx
new file mode 100644
index 000000000..26d8eddb4
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/users/dboyne.mdx
@@ -0,0 +1,33 @@
+---
+id: dboyne
+name: David Boyne
+avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png'
+role: Lead developer
+email: test@test.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+---
+
+Hello! I'm David Boyne, the Tech Lead of an amazing team called Full Stackers. With a passion for building robust and scalable systems, I specialize in designing and implementing event-driven architectures that power modern, responsive applications.
+
+### About Me
+
+With over a decade of experience in the tech industry, I have honed my skills in full-stack development, cloud computing, and distributed systems. My journey has taken me through various roles, from software engineer to architect, and now as a tech lead, I am committed to driving innovation and excellence within my team.
+
+### What I Do
+
+At Full Stackers, we focus on creating seamless and efficient event-driven architectures that enhance the performance and scalability of our applications. My role involves:
+
+- **Architecture Design**: Crafting scalable and resilient system architectures using event-driven paradigms.
+- **Team Leadership**: Guiding a talented team of developers, fostering a collaborative and innovative environment.
+- **Code Reviews & Mentorship**: Ensuring code quality and sharing knowledge to help the team grow.
+- **Stakeholder Collaboration**: Working closely with other teams and stakeholders to align our technical solutions with business goals.
+- **Continuous Improvement**: Advocating for best practices in software development, deployment, and monitoring.
+
+I am passionate about leveraging the power of events to build systems that are not only highly responsive but also easier to maintain and extend. In an ever-evolving tech landscape, I strive to stay ahead of the curve, continuously learning and adapting to new technologies and methodologies.
+
+Feel free to connect with me to discuss all things tech, event-driven architectures, or to exchange ideas on building better software systems!
+
+---
+
+_David Boyne_
+_Tech Lead, Full Stackers_
diff --git a/packages/create-eventcatalog/templates/asyncapi/users/dkim.mdx b/packages/create-eventcatalog/templates/asyncapi/users/dkim.mdx
new file mode 100644
index 000000000..bbdf71b61
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/users/dkim.mdx
@@ -0,0 +1,11 @@
+---
+id: dkim
+name: David Kim
+avatarUrl: https://randomuser.me/api/portraits/men/96.jpg
+role: Performance Engineer
+email: dkim@company.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/dkim
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=dkim@company.com
+---
+
+Optimizing application performance and user experience...
diff --git a/packages/create-eventcatalog/templates/asyncapi/users/jbrown.mdx b/packages/create-eventcatalog/templates/asyncapi/users/jbrown.mdx
new file mode 100644
index 000000000..149232154
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/users/jbrown.mdx
@@ -0,0 +1,11 @@
+---
+id: jbrown
+name: Jessica Brown
+avatarUrl: https://randomuser.me/api/portraits/women/95.jpg
+role: UI/UX Designer
+email: jbrown@company.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/jbrown
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=jbrown@company.com
+---
+
+Creating intuitive and engaging user interfaces...
diff --git a/packages/create-eventcatalog/templates/asyncapi/users/mSmith.mdx b/packages/create-eventcatalog/templates/asyncapi/users/mSmith.mdx
new file mode 100644
index 000000000..635e036f1
--- /dev/null
+++ b/packages/create-eventcatalog/templates/asyncapi/users/mSmith.mdx
@@ -0,0 +1,8 @@
+---
+id: msmith
+name: Martin Smith
+avatarUrl: 'https://randomuser.me/api/portraits/men/51.jpg'
+role: Senior software engineer
+---
+
+As a Senior Mobile Developer on The Mobile Devs team, I play a key role in designing, developing, and maintaining our company’s mobile applications. My focus is on creating a seamless and intuitive user experience for our customers on both iOS and Android platforms. I work closely with cross-functional teams, including backend developers, UX/UI designers, and product managers, to deliver high-quality mobile solutions that meet business objectives and exceed user expectations.
diff --git a/packages/create-eventcatalog/templates/confluent/Dockerfile b/packages/create-eventcatalog/templates/confluent/Dockerfile
new file mode 100644
index 000000000..3405a94d2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/confluent/Dockerfile
@@ -0,0 +1,23 @@
+## Stage 1: Build the app
+FROM node:lts AS build
+
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+# Copy source code
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+# Build the app
+RUN npm run build
+
+
+## Stage 2: Serve app with httpd server
+FROM httpd:2.4
+
+# Copy built app to serve
+COPY --from=build /app/dist /usr/local/apache2/htdocs
diff --git a/packages/create-eventcatalog/templates/confluent/Dockerfile.server b/packages/create-eventcatalog/templates/confluent/Dockerfile.server
new file mode 100644
index 000000000..8a7332d64
--- /dev/null
+++ b/packages/create-eventcatalog/templates/confluent/Dockerfile.server
@@ -0,0 +1,23 @@
+# Use this Docker file if your EventCatalog output is set to `server`.
+# When EventCatalog output is set to `server`, the output will be a node server.
+# This server is required for certain features like the EventCatalog Chat (with your own keys).
+
+FROM node:lts AS runtime
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+RUN npm run build
+
+ENV HOST=0.0.0.0
+ENV PORT=3000
+EXPOSE 3000
+
+# Start the server
+CMD npm run start
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/confluent/README-template.md b/packages/create-eventcatalog/templates/confluent/README-template.md
new file mode 100644
index 000000000..8d376bd8f
--- /dev/null
+++ b/packages/create-eventcatalog/templates/confluent/README-template.md
@@ -0,0 +1,55 @@
+# Welcome to EventCatalog
+
+[EventCatalog](https://www.eventcatalog.dev/) is your architecture catalog for distributed systems. This template adds the Confluent Schema Registry generator so you can import schemas and topics, then document how they connect to your domains, services, and teams.
+
+## Generate Your Catalog
+
+1. Edit `.env` with your Confluent settings.
+2. Run Confluent locally, or configure `schemaRegistryUrl` in `eventcatalog.config.js`.
+3. Import your schemas:
+
+```sh
+npm run generate
+```
+
+4. Start the catalog:
+
+```sh
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view your catalog.
+
+## Edit Your Catalog
+
+Your generated resources are docs-as-code. You can enrich them with ownership, domain context, Markdown, examples, and relationships that are not always available in the schema registry.
+
+Prefer a visual workflow? Run `npm run editor` to open the [EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview) and browse, create, or update catalog resources through a GitHub-backed UI.
+
+## Keep It in Sync
+
+Run `npm run generate` whenever your schemas or topics change. You can also run the generator in CI so your catalog stays aligned with Confluent.
+
+With this integration you can:
+
+- Document schemas and topics
+- Assign schemas to producers and consumers
+- Connect resources to users and teams
+- Visualize your Kafka architecture
+- Add semantic meaning to schemas and topics
+
+## Use AI with Architecture Context
+
+EventCatalog gives AI tools structured context about your domains, services, messages, schemas, owners, and flows. Connect an MCP-compatible tool with the [EventCatalog MCP Server](https://www.eventcatalog.dev/docs/development/guides/ai/using-mcp-server).
+
+## Learn by Task
+
+- [Confluent Schema Registry integration docs](https://eventcatalog.dev/docs/plugins/confluent-schema-registry/intro)
+- [Use the EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview)
+- [Document a service](https://www.eventcatalog.dev/docs/development/guides/services)
+- [Add events, commands, and queries](https://www.eventcatalog.dev/docs/development/guides/messages/adding-messages)
+- [Join the community](https://discord.gg/3rjaZMmrAm)
+
+## Found a Problem?
+
+Open an issue on [GitHub](https://github.com/event-catalog/generators).
diff --git a/packages/create-eventcatalog/templates/confluent/dockerignore b/packages/create-eventcatalog/templates/confluent/dockerignore
new file mode 100644
index 000000000..245063830
--- /dev/null
+++ b/packages/create-eventcatalog/templates/confluent/dockerignore
@@ -0,0 +1,8 @@
+.eventcatalog-core/
+.git/
+dist/
+node_modules/
+.gitignore
+.dockerignore
+Dockerfile
+README.md
diff --git a/packages/create-eventcatalog/templates/confluent/env b/packages/create-eventcatalog/templates/confluent/env
new file mode 100644
index 000000000..c5b832dc5
--- /dev/null
+++ b/packages/create-eventcatalog/templates/confluent/env
@@ -0,0 +1,7 @@
+
+# Get 14 day trial license key from https://eventcatalog.cloud/
+EVENTCATALOG_LICENSE_KEY_CONFLUENT_SCHEMA_REGISTRY=
+
+# Confluent Schema Registry API Keys (you can get them from Confluent cloud)
+CONFLUENT_SCHEMA_REGISTRY_KEY=
+CONFLUENT_SCHEMA_REGISTRY_KEY_SECRET=
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/confluent/eventcatalog.auth.js b/packages/create-eventcatalog/templates/confluent/eventcatalog.auth.js
new file mode 100644
index 000000000..f97044604
--- /dev/null
+++ b/packages/create-eventcatalog/templates/confluent/eventcatalog.auth.js
@@ -0,0 +1,44 @@
+/**
+ * This is an optional file that can add authentication to your EventCatalog.
+ *
+ * To enable authentication you need to set `server:output` in your `eventcatalog.config.js` file.
+ * And then pick which provider you want to use.
+ *
+ * You can read more in the documentation:
+ * https://www.eventcatalog.dev/docs/development/guides/authentication/introduction
+ *
+ */
+
+// export default {
+//   debug: false,
+//   providers: {
+//     // GitHub Authentication
+//     github: {
+//       clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+//       clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+//     },
+//     // Azure AD Entra ID
+//     entra: {
+//       clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
+//       clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
+//       issuer: process.env.AUTH_MICROSOFT_ENTRA_ID_ISSUER,
+//     },
+//     // Google Authentication
+//     google: {
+//       clientId: process.env.AUTH_GOOGLE_ID,
+//       clientSecret: process.env.AUTH_GOOGLE_SECRET,
+//     },
+//     // Auth0 Authentication
+//     auth0: {
+//       clientId: process.env.AUTH_AUTH0_ID,
+//       clientSecret: process.env.AUTH_AUTH0_SECRET,
+//       issuer: process.env.AUTH_AUTH0_ISSUER,
+//     },
+//     // Okta Authentication
+//     okta: {
+//       clientId: process.env.AUTH_OKTA_CLIENT_ID,
+//       clientSecret: process.env.AUTH_OKTA_CLIENT_SECRET,
+//       issuer: process.env.AUTH_OKTA_ISSUER,
+//     },
+//   },
+// }
diff --git a/packages/create-eventcatalog/templates/confluent/eventcatalog.config.js b/packages/create-eventcatalog/templates/confluent/eventcatalog.config.js
new file mode 100644
index 000000000..4f4126868
--- /dev/null
+++ b/packages/create-eventcatalog/templates/confluent/eventcatalog.config.js
@@ -0,0 +1,58 @@
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  title: 'EventCatalog',
+  tagline:
+    'This internal platform provides a comprehensive view of our event-driven architecture across all systems. Use this portal to discover kafka schemas, topics, services and domains, and understand the message contracts that connect our infrastructure',
+  organizationName: '<organizationName>',
+  theme: 'sunset',
+  homepageLink: 'https://eventcatalog.dev/',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  // Supports static or server. Static renders a static site, server renders a server side rendered site
+  // large catalogs may benefit from server side rendering
+  output: 'static',
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: '/',
+  // Resource search is the default lightweight search. Change this to { type: 'indexed' }
+  // to enable full-content search. Indexed search requires running a build to generate the index.
+  search: {
+    type: 'resource',
+  },
+  // Customize the navigation for your docs sidebar.
+  // read more at https://eventcatalog.dev/docs/development/customization/customize-sidebars/documentation-sidebar
+  navigation: {
+    pages: ['list:all'],
+  },
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'EventCatalog',
+  },
+  // Enable RSS feed for your eventcatalog
+  rss: {
+    enabled: true,
+    // number of items to include in the feed per resource (event, service, etc)
+    limit: 20,
+  },
+  // required random generated id used by eventcatalog
+  cId: '<cId>',
+  // This lets you copy markdown contents from EventCatalog to your clipboard
+  // Including schemas for your events and services
+  llmsTxt: {
+    enabled: true,
+  },
+  generators: [
+    [
+      '@eventcatalog/generator-confluent-schema-registry',
+      {
+        // The URL for your schema registry
+        schemaRegistryUrl: 'http://localhost:8081',
+        // This will document all the schemas in the registry, not just the latest version (default is false)
+        includeAllVersions: true,
+      },
+    ],
+  ],
+};
diff --git a/packages/create-eventcatalog/templates/confluent/eventcatalog.styles.css b/packages/create-eventcatalog/templates/confluent/eventcatalog.styles.css
new file mode 100644
index 000000000..0d75d2602
--- /dev/null
+++ b/packages/create-eventcatalog/templates/confluent/eventcatalog.styles.css
@@ -0,0 +1 @@
+/* Custom styling support coming soon. */
diff --git a/packages/create-eventcatalog/templates/confluent/gitignore b/packages/create-eventcatalog/templates/confluent/gitignore
new file mode 100644
index 000000000..b6eaa6d14
--- /dev/null
+++ b/packages/create-eventcatalog/templates/confluent/gitignore
@@ -0,0 +1,29 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.astro
+out
+dist
+
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.eventcatalog-core
+
+.env
+.env-*
+
+exports/*
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/confluent/npmrc b/packages/create-eventcatalog/templates/confluent/npmrc
new file mode 100644
index 000000000..fa4e09523
--- /dev/null
+++ b/packages/create-eventcatalog/templates/confluent/npmrc
@@ -0,0 +1 @@
+strict-peer-dependencies=false
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/confluent/public/logo.png b/packages/create-eventcatalog/templates/confluent/public/logo.png
new file mode 100644
index 000000000..535b5a0e7
Binary files /dev/null and b/packages/create-eventcatalog/templates/confluent/public/logo.png differ
diff --git a/packages/create-eventcatalog/templates/default/Dockerfile b/packages/create-eventcatalog/templates/default/Dockerfile
new file mode 100644
index 000000000..3405a94d2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/Dockerfile
@@ -0,0 +1,23 @@
+## Stage 1: Build the app
+FROM node:lts AS build
+
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+# Copy source code
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+# Build the app
+RUN npm run build
+
+
+## Stage 2: Serve app with httpd server
+FROM httpd:2.4
+
+# Copy built app to serve
+COPY --from=build /app/dist /usr/local/apache2/htdocs
diff --git a/packages/create-eventcatalog/templates/default/Dockerfile.server b/packages/create-eventcatalog/templates/default/Dockerfile.server
new file mode 100644
index 000000000..8a7332d64
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/Dockerfile.server
@@ -0,0 +1,23 @@
+# Use this Docker file if your EventCatalog output is set to `server`.
+# When EventCatalog output is set to `server`, the output will be a node server.
+# This server is required for certain features like the EventCatalog Chat (with your own keys).
+
+FROM node:lts AS runtime
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+RUN npm run build
+
+ENV HOST=0.0.0.0
+ENV PORT=3000
+EXPOSE 3000
+
+# Start the server
+CMD npm run start
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/default/README-template.md b/packages/create-eventcatalog/templates/default/README-template.md
new file mode 100644
index 000000000..c0e08a412
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/README-template.md
@@ -0,0 +1,64 @@
+# Welcome to EventCatalog
+
+[EventCatalog](https://www.eventcatalog.dev/) is your architecture catalog for distributed systems. Use it to document, govern, and discover your services, domains, APIs, events, commands, queries, schemas, teams, and flows in one place.
+
+## Start the Catalog
+
+```sh
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view your catalog.
+
+Using `pnpm` or `yarn`? Run the same scripts with the package manager you chose when creating this project.
+
+## Edit Your Catalog
+
+Your catalog is docs-as-code. Resources live in folders with an `index.mdx` file for frontmatter metadata and Markdown content.
+
+Good places to start:
+
+- `domains/` - bounded contexts, business capabilities, and ownership
+- `domains/<domain>/systems/` - systems and containers inside each domain
+- `domains/<domain>/systems/<system>/services/` - services, APIs, and message producers or consumers
+- `commands/`, `events/`, and `queries/` folders under services - the messages flowing through your system
+- `teams/` and `users/` - who owns each part of the architecture
+
+Prefer a visual workflow? Run `npm run editor` to open the [EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview) and browse, create, or update catalog resources through a GitHub-backed UI.
+
+## Make Your First Change
+
+1. Add or edit a domain, service, or message.
+2. Run `npm run dev` and check the generated pages and diagrams.
+3. Commit the MDX and schema files to Git.
+
+## Keep It in Sync
+
+Use `npm run generate` with [EventCatalog integrations](https://www.eventcatalog.dev/integrations) to import architecture data from OpenAPI, AsyncAPI, schema registries, EventBridge, GitHub, internal systems, and more.
+
+Run generators locally while you work, or in CI so your catalog stays aligned with the systems it describes.
+
+## Use AI with Architecture Context
+
+EventCatalog gives AI tools structured context about your domains, services, messages, schemas, owners, and flows.
+
+- Connect Claude, Cursor, VS Code, Windsurf, or another MCP-compatible tool with the [EventCatalog MCP Server](https://www.eventcatalog.dev/docs/development/guides/ai/using-mcp-server).
+- Install [EventCatalog Skills](https://github.com/event-catalog/skills) to help agents document services, create domain models, and map business flows:
+
+```sh
+npx skills add event-catalog/skills
+```
+
+## Learn by Task
+
+- [Create a domain](https://www.eventcatalog.dev/docs/development/guides/domains)
+- [Document a service](https://www.eventcatalog.dev/docs/development/guides/services)
+- [Add events, commands, and queries](https://www.eventcatalog.dev/docs/development/guides/messages/adding-messages)
+- [Use the EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview)
+- [Generate from integrations](https://www.eventcatalog.dev/integrations)
+- [Manage your catalog with the SDK](https://www.eventcatalog.dev/docs/development/sdk)
+- [Join the community](https://discord.gg/3rjaZMmrAm)
+
+## Found a Problem?
+
+Open an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).
diff --git a/packages/create-eventcatalog/templates/default/_data/visualizer-layouts/domains-systems-context/catalog/1.0.0.json b/packages/create-eventcatalog/templates/default/_data/visualizer-layouts/domains-systems-context/catalog/1.0.0.json
new file mode 100644
index 000000000..af8f971d4
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/_data/visualizer-layouts/domains-systems-context/catalog/1.0.0.json
@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "savedAt": "2026-06-29T11:03:00.194Z",
+  "resourceKey": "domains-systems-context/catalog/1.0.0",
+  "positions": {
+    "product-catalog-system-1.0.0": {
+      "x": 654.4139077853363,
+      "y": 77.21012849584278
+    },
+    "search-system-1.0.0": {
+      "x": 1145,
+      "y": 335
+    },
+    "actor-merchandiser": {
+      "x": 90,
+      "y": 60
+    },
+    "actor-catalog-admin": {
+      "x": 90,
+      "y": 260
+    },
+    "actor-shopper": {
+      "x": 595,
+      "y": 360
+    },
+    "actor-storefront-team": {
+      "x": 595,
+      "y": 560
+    }
+  }
+}
diff --git a/packages/create-eventcatalog/templates/default/_data/visualizer-layouts/domains-systems-context/customer/1.0.0.json b/packages/create-eventcatalog/templates/default/_data/visualizer-layouts/domains-systems-context/customer/1.0.0.json
new file mode 100644
index 000000000..10980870e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/_data/visualizer-layouts/domains-systems-context/customer/1.0.0.json
@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "savedAt": "2026-06-26T12:15:29.856Z",
+  "resourceKey": "domains-systems-context/customer/1.0.0",
+  "positions": {
+    "customer-management-system-1.0.0": {
+      "x": 652.3279365079366,
+      "y": 338.73238095238094
+    },
+    "identity-provider-1.0.0": {
+      "x": 745.6812698412698,
+      "y": 71.1025396825397
+    },
+    "actor-customer": {
+      "x": 90,
+      "y": 122.5
+    },
+    "actor-support-agent": {
+      "x": 90,
+      "y": 322.5
+    }
+  }
+}
diff --git a/packages/create-eventcatalog/templates/default/_data/visualizer-layouts/system-context-map/system-context-map/1.0.0.json b/packages/create-eventcatalog/templates/default/_data/visualizer-layouts/system-context-map/system-context-map/1.0.0.json
new file mode 100644
index 000000000..e245cf7b5
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/_data/visualizer-layouts/system-context-map/system-context-map/1.0.0.json
@@ -0,0 +1,91 @@
+{
+  "version": 1,
+  "savedAt": "2026-06-29T08:55:18.430Z",
+  "resourceKey": "system-context-map/system-context-map/1.0.0",
+  "positions": {
+    "carrier-1.0.0": {
+      "x": 1423.6053719008264,
+      "y": 1259.6570247933885
+    },
+    "shipping-system-1.0.0": {
+      "x": 1622.4194214876034,
+      "y": 1702.4814049586778
+    },
+    "cart-system-1.0.0": {
+      "x": 595,
+      "y": 60
+    },
+    "promotion-system-1.0.0": {
+      "x": 1145,
+      "y": 60
+    },
+    "actor-shopper": {
+      "x": 56.553719008264444,
+      "y": 178.41322314049586
+    },
+    "checkout-system-1.0.0": {
+      "x": 595,
+      "y": 260
+    },
+    "order-management-system-1.0.0": {
+      "x": 1145,
+      "y": 260
+    },
+    "customer-management-system-1.0.0": {
+      "x": 812.667132867133,
+      "y": 836.9146853146854
+    },
+    "identity-provider-1.0.0": {
+      "x": 1145,
+      "y": 1085
+    },
+    "actor-customer": {
+      "x": 90,
+      "y": 910
+    },
+    "actor-support-agent": {
+      "x": 90,
+      "y": 1110
+    },
+    "fraud-detection-1.0.0": {
+      "x": -664.9235537190083,
+      "y": 1282.7169421487602
+    },
+    "payment-processing-system-1.0.0": {
+      "x": -145.58264462809922,
+      "y": 1486.1818181818182
+    },
+    "inventory-system-1.0.0": {
+      "x": 366.3367768595041,
+      "y": 1716.0785123966941
+    },
+    "warehouse-system-1.0.0": {
+      "x": 955.3574380165288,
+      "y": 1529.3367768595042
+    },
+    "stripe-1.0.0": {
+      "x": 318.0144628099173,
+      "y": 1260.4194214876034
+    },
+    "product-catalog-system-1.0.0": {
+      "x": 1145,
+      "y": 497.5
+    },
+    "search-system-1.0.0": {
+      "x": 440.8853146853147,
+      "y": 723.5524475524476
+    },
+    "actor-merchandiser": {
+      "x": 447.2405594405594,
+      "y": 530.0979020979021
+    },
+    "actor-catalog-admin": {
+      "x": 561.634965034965,
+      "y": 418.6909090909091
+    },
+    "actor-storefront-team": {
+      "x": -349.5522886204704,
+      "y": 775.1666878575969
+    }
+  }
+}
diff --git a/packages/create-eventcatalog/templates/default/_data/visualizer-layouts/systems-context/customer-management-system/1.0.0.json b/packages/create-eventcatalog/templates/default/_data/visualizer-layouts/systems-context/customer-management-system/1.0.0.json
new file mode 100644
index 000000000..47e68242a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/_data/visualizer-layouts/systems-context/customer-management-system/1.0.0.json
@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "savedAt": "2026-06-29T11:26:03.901Z",
+  "resourceKey": "systems-context/customer-management-system/1.0.0",
+  "positions": {
+    "customer-management-system-1.0.0": {
+      "x": 593.5226571767497,
+      "y": -13.867141162514821
+    },
+    "identity-provider-1.0.0": {
+      "x": 1145,
+      "y": 85
+    },
+    "actor-customer": {
+      "x": 90,
+      "y": 60
+    },
+    "actor-support-agent": {
+      "x": 90,
+      "y": 260
+    }
+  }
+}
diff --git a/packages/create-eventcatalog/templates/default/components/footer.astro b/packages/create-eventcatalog/templates/default/components/footer.astro
new file mode 100644
index 000000000..7284e2724
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/components/footer.astro
@@ -0,0 +1,7 @@
+---
+import config from '@config';
+---
+
+<div class="w-full text-right">
+  <span class="italic text-[rgb(var(--ec-page-text-muted))]">Event-driven architecture documentation: {config.organizationName}</span>
+</div>
diff --git a/packages/create-eventcatalog/templates/default/dockerignore b/packages/create-eventcatalog/templates/default/dockerignore
new file mode 100644
index 000000000..245063830
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/dockerignore
@@ -0,0 +1,8 @@
+.eventcatalog-core/
+.git/
+dist/
+node_modules/
+.gitignore
+.dockerignore
+Dockerfile
+README.md
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/entities/category/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/entities/category/index.mdx
new file mode 100644
index 000000000..0bfb7a052
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/entities/category/index.mdx
@@ -0,0 +1,36 @@
+---
+id: category
+name: Category
+version: 1.0.0
+identifier: categoryId
+aggregateRoot: true
+summary: A merchandising grouping used to organize products for discovery.
+owners:
+  - product-platform
+properties:
+  - name: categoryId
+    type: UUID
+    required: true
+    description: Unique category identifier.
+  - name: slug
+    type: string
+    required: true
+    description: Stable URL-safe category key.
+  - name: displayName
+    type: string
+    required: true
+    description: Customer-facing category name.
+  - name: parentCategoryId
+    type: UUID
+    required: false
+    description: Parent category for hierarchy navigation.
+    references: category
+    relationType: belongsTo
+    referencesIdentifier: categoryId
+---
+
+## Overview
+
+Category defines how products are grouped for browsing. It is owned by the Catalog domain and projected into the Search System for discovery.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/entities/product-variant/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/entities/product-variant/index.mdx
new file mode 100644
index 000000000..365dcd43a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/entities/product-variant/index.mdx
@@ -0,0 +1,35 @@
+---
+id: product-variant
+name: Product Variant
+version: 1.0.0
+identifier: variantId
+summary: A purchasable variation of a product, such as size or color.
+owners:
+  - product-platform
+properties:
+  - name: variantId
+    type: UUID
+    required: true
+    description: Unique variant identifier.
+  - name: productId
+    type: UUID
+    required: true
+    description: Product this variant belongs to.
+    references: product
+    relationType: belongsTo
+    referencesIdentifier: productId
+  - name: sku
+    type: string
+    required: true
+    description: Variant-level SKU.
+  - name: attributes
+    type: object
+    required: true
+    description: Variant dimensions such as size, color or material.
+---
+
+## Overview
+
+Product Variant captures the concrete option a customer can buy. It belongs to a [[entity|product]] and is indexed into search when product data changes.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/entities/product/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/entities/product/index.mdx
new file mode 100644
index 000000000..91826fc3b
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/entities/product/index.mdx
@@ -0,0 +1,37 @@
+---
+id: product
+name: Product
+version: 1.0.0
+identifier: productId
+aggregateRoot: true
+summary: The sellable item Acme manages in the product catalog.
+owners:
+  - product-platform
+properties:
+  - name: productId
+    type: UUID
+    required: true
+    description: Unique product identifier.
+  - name: sku
+    type: string
+    required: true
+    description: Primary merchandising SKU.
+  - name: name
+    type: string
+    required: true
+    description: Customer-facing product name.
+  - name: status
+    type: string
+    required: true
+    description: Product publication state.
+    enum:
+      - draft
+      - active
+      - archived
+---
+
+## Overview
+
+The Product is the Catalog domain's core aggregate. It is created and maintained by [[service|product-api]] and published to downstream consumers through product events.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/entities/search-document/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/entities/search-document/index.mdx
new file mode 100644
index 000000000..d9818c4e9
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/entities/search-document/index.mdx
@@ -0,0 +1,35 @@
+---
+id: search-document
+name: Search Document
+version: 1.0.0
+identifier: documentId
+summary: The denormalized representation of product data indexed by Search.
+owners:
+  - search-platform
+properties:
+  - name: documentId
+    type: string
+    required: true
+    description: Search index document identifier.
+  - name: productId
+    type: UUID
+    required: true
+    description: Product represented by the document.
+    references: product
+    relationType: represents
+    referencesIdentifier: productId
+  - name: searchableText
+    type: string
+    required: true
+    description: Text used for matching and ranking.
+  - name: indexedAt
+    type: datetime
+    required: true
+    description: Time the document was last indexed.
+---
+
+## Overview
+
+Search Document is the read model maintained by [[system|search-system]]. It is eventually consistent with the Product Catalog System.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/index.mdx
new file mode 100644
index 000000000..0ea42b1e0
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/index.mdx
@@ -0,0 +1,65 @@
+---
+id: catalog
+name: Catalog
+version: 1.0.0
+summary: |
+  The Catalog domain owns everything about products — how they are created, maintained and made discoverable across Acme Inc. It is the source of truth for product data and powers product search across the business.
+owners:
+  - product-platform
+systems:
+  - id: product-catalog-system
+    version: 1.0.0
+  - id: search-system
+    version: 1.0.0
+entities:
+  - id: product
+    version: 1.0.0
+  - id: product-variant
+    version: 1.0.0
+  - id: category
+    version: 1.0.0
+  - id: search-document
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Catalog** domain is responsible for the lifecycle of every product Acme Inc sells, and for making those products discoverable. It is split into two internal systems that work together:
+
+<Tiles>
+  <Tile
+    icon="RectangleGroupIcon"
+    href="/docs/systems/product-catalog-system/1.0.0"
+    title="Product Catalog System"
+    description="System of record for product data — create, update, delete and read products."
+  />
+  <Tile
+    icon="MagnifyingGlassIcon"
+    href="/docs/systems/search-system/1.0.0"
+    title="Search System"
+    description="Indexes product changes and serves fast, relevant product search to the rest of the business."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Product Catalog System** is the authoritative source of product data. Whenever a product is created, updated or deleted it publishes a domain event. The **Search System** subscribes to those events, keeps its search index in sync, and exposes a search API so other teams never have to query the catalog database directly.
+
+The diagram below shows the domain's systems, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Component map
+
+These are the components that are part of this domain (parts of the systems in this domain)
+
+<NodeGraph />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/adrs/adr-001-use-transactional-outbox/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/adrs/adr-001-use-transactional-outbox/index.mdx
new file mode 100644
index 000000000..2cd394fde
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/adrs/adr-001-use-transactional-outbox/index.mdx
@@ -0,0 +1,43 @@
+---
+id: adr-001-use-transactional-outbox
+name: 'ADR-001: Publish product events via a transactional outbox'
+summary: Product change events are written to an outbox table in the same transaction as the change, then relayed to the broker, so an event is never lost or published for a rolled-back change.
+version: 1.0.0
+status: accepted
+date: 2026-02-10
+owners:
+  - product-platform
+decisionMakers:
+  - product-platform
+appliesTo:
+  - type: system
+    id: product-catalog-system
+  - type: service
+    id: product-search-publisher
+  - type: container
+    id: product-database
+badges:
+  - content: Messaging
+    backgroundColor: blue
+    textColor: blue
+  - content: Reliability
+    backgroundColor: green
+    textColor: green
+---
+
+## Context
+
+The Product Catalog System is the source of truth for products, and other systems — notably the [[system|search-system]] — depend on a reliable stream of `product-created`, `product-updated` and `product-deleted` events. Publishing to the broker directly from the [[service|product-api]] request path creates a dual-write problem: if the database commit succeeds but the broker publish fails (or vice versa), the catalog and its consumers drift out of sync. Lost or phantom events are hard to detect and expensive to reconcile.
+
+## Decision
+
+The Product API writes every product change **and** a corresponding row in an `outbox` table inside a single database transaction in the [[container|product-database]]. A separate relay, the [[service|product-search-publisher]], reads unpublished outbox rows in order and publishes them to the broker with at-least-once delivery, marking each row published once acknowledged.
+
+This decouples persistence from publishing: the request path only touches the database, and event delivery becomes an independent, retryable concern.
+
+## Consequences
+
+- Events are never lost and never published for a change that rolled back — the change and its event share a transaction boundary.
+- Consumers must be **idempotent**, since at-least-once delivery means an event can be redelivered.
+- There is a small publish latency between the commit and the relay draining the outbox.
+- The outbox table needs a retention/cleanup policy so it doesn't grow unbounded.
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/adrs/adr-002-postgres-as-system-of-record/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/adrs/adr-002-postgres-as-system-of-record/index.mdx
new file mode 100644
index 000000000..a7d5077cb
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/adrs/adr-002-postgres-as-system-of-record/index.mdx
@@ -0,0 +1,40 @@
+---
+id: adr-002-postgres-as-system-of-record
+name: 'ADR-002: Use PostgreSQL as the product system of record'
+summary: Product data is stored in a single PostgreSQL database that acts as the authoritative system of record, with derived stores (like the search index) rebuilt from it.
+version: 1.0.0
+status: accepted
+date: 2026-02-12
+owners:
+  - product-platform
+decisionMakers:
+  - product-platform
+appliesTo:
+  - type: system
+    id: product-catalog-system
+  - type: container
+    id: product-database
+related:
+  - id: adr-001-use-transactional-outbox
+badges:
+  - content: Data
+    backgroundColor: purple
+    textColor: purple
+---
+
+## Context
+
+Products are a small-to-medium, strongly relational dataset (products, categories, pricing, lifecycle status) that needs transactional integrity, an enforceable schema, and the ability to write a change and its outbox event atomically. We also want a single, unambiguous source of truth so that derived stores — such as the [[system|search-system]]'s index — can be treated as disposable and rebuilt at any time.
+
+## Decision
+
+The Product Catalog System uses a single **PostgreSQL** database, the [[container|product-database]], as the authoritative system of record. It holds the `products` table and the outbox table (see [[adr|adr-001-use-transactional-outbox]]). The [[service|product-api]] is the only writer on the request path; the [[service|product-worker]] performs asynchronous enrichment.
+
+Any other representation of product data elsewhere in the business is a **derived read model**, not a source of truth, and must be rebuildable by replaying product events.
+
+## Consequences
+
+- Strong consistency and transactional outbox writes are straightforward with a single relational store.
+- The search index and any future read models can be rebuilt from the catalog, keeping them disposable.
+- The database is a scaling focal point; heavy read traffic should be served from read replicas or downstream read models rather than the primary.
+- Schema changes need migrations and care, since this is the authoritative store.
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/adrs/adr-003-offload-async-work-to-worker/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/adrs/adr-003-offload-async-work-to-worker/index.mdx
new file mode 100644
index 000000000..941e73038
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/adrs/adr-003-offload-async-work-to-worker/index.mdx
@@ -0,0 +1,41 @@
+---
+id: adr-003-offload-async-work-to-worker
+name: 'ADR-003: Offload long-running catalog work to a dedicated worker'
+summary: Slow and asynchronous catalog tasks (enrichment, image processing, bulk imports) run in a separate Product Worker so the Product API stays fast and predictable.
+version: 1.0.0
+status: accepted
+date: 2026-02-18
+owners:
+  - product-platform
+decisionMakers:
+  - product-platform
+appliesTo:
+  - type: system
+    id: product-catalog-system
+  - type: service
+    id: product-worker
+  - type: service
+    id: product-api
+badges:
+  - content: Architecture
+    backgroundColor: blue
+    textColor: blue
+  - content: Performance
+    backgroundColor: green
+    textColor: green
+---
+
+## Context
+
+Some catalog operations are slow or bursty: enriching products with derived attributes, processing and optimising images, and ingesting large supplier feeds. Running this work inline in the [[service|product-api]] request path would make API latency unpredictable and couple the responsiveness of create/update/read operations to whatever heavy job happens to be running.
+
+## Decision
+
+The Product Catalog System runs a dedicated [[service|product-worker]] for long-running and asynchronous tasks. The [[service|product-api]] handles validation, persistence and the outbox write synchronously, then returns; the worker picks up enrichment, media processing and bulk imports independently, reading from and writing back to the [[container|product-database]].
+
+## Consequences
+
+- The Product API has a small, predictable surface and stays fast under load.
+- Heavy work can be scaled, retried and scheduled independently of the API.
+- Some product attributes are **eventually** populated after creation, so consumers must not assume every derived field is present immediately.
+- There are now two services writing to the [[container|product-database]], so write paths must respect the same invariants and avoid conflicting updates.
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/containers/product-database/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/containers/product-database/index.mdx
new file mode 100644
index 000000000..2e3a3ef5e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/containers/product-database/index.mdx
@@ -0,0 +1,45 @@
+---
+id: product-database
+name: Product Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for all product data.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for products, plus the change outbox used to publish events
+classification: internal
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Product Database** is the authoritative store for every product in the catalog. The [[service|product-api]] reads from and writes to it, and the [[service|product-worker]] uses it for asynchronous enrichment. It also holds the **outbox** table that the [[service|product-search-publisher]] reads to publish product change events.
+
+### What does it store?
+
+- **Products** — one row per product: SKU, name, description, price, currency, category and lifecycle status.
+- **Outbox** — one row per product change, used to reliably publish [[event|product-created]], [[event|product-updated]] and [[event|product-deleted]] events.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Product Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Access patterns
+
+- The [[service|product-api]] is the only writer to the `products` table on the request path.
+- The [[service|product-search-publisher]] is a read-only consumer of the `outbox` table.
+- The [[service|product-worker]] reads and writes for asynchronous enrichment jobs.
+
+### Why an outbox?
+
+Writing the product change and the event in the **same transaction** guarantees we never persist a change without an event, or publish an event for a change that rolled back. The publisher reads the outbox and emits events with at-least-once delivery.
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/containers/product-database/schema.sql b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/containers/product-database/schema.sql
new file mode 100644
index 000000000..ad212c2fe
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/containers/product-database/schema.sql
@@ -0,0 +1,33 @@
+-- Product Database — system of record for the product catalog
+
+CREATE TABLE products (
+    product_id   UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    sku          TEXT NOT NULL UNIQUE,
+    name         TEXT NOT NULL,
+    description  TEXT,
+    price_cents  INTEGER NOT NULL CHECK (price_cents >= 0),
+    currency     CHAR(3) NOT NULL,
+    category     TEXT,
+    status       TEXT NOT NULL DEFAULT 'DRAFT'
+                   CHECK (status IN ('DRAFT', 'ACTIVE', 'ARCHIVED')),
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_products_category ON products (category);
+CREATE INDEX idx_products_status   ON products (status);
+
+-- Transactional outbox — change events are written here in the same
+-- transaction as the product change, then drained by the Product Search Publisher.
+CREATE TABLE outbox (
+    id            BIGSERIAL PRIMARY KEY,
+    product_id    UUID NOT NULL REFERENCES products (product_id),
+    event_type    TEXT NOT NULL
+                    CHECK (event_type IN ('ProductCreated', 'ProductUpdated', 'ProductDeleted')),
+    payload       JSONB NOT NULL,
+    occurred_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    published_at  TIMESTAMPTZ
+);
+
+-- Index used by the publisher to find unpublished changes in order.
+CREATE INDEX idx_outbox_unpublished ON outbox (id) WHERE published_at IS NULL;
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/index.mdx
new file mode 100644
index 000000000..9137ac88e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/index.mdx
@@ -0,0 +1,72 @@
+---
+id: product-catalog-system
+name: Product Catalog System
+version: 1.0.0
+summary: |
+  Internal system that is the source of truth for product data. Owns the product database and publishes product change events for the rest of the business to consume.
+owners:
+  - product-platform
+services:
+  - id: product-api
+  - id: product-worker
+  - id: product-search-publisher
+containers:
+  - id: product-database
+relationships:
+  - id: search-system
+    label: notifies of product changes
+actors:
+  - id: merchandiser
+    name: Merchandiser
+    label: creates and updates products
+    direction: inbound
+  - id: catalog-admin
+    name: Catalog Admin
+    label: manages categories and pricing
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Product Catalog System** is the system of record for products at Acme Inc. It accepts commands to create, update and delete products, persists them in the [[container|product-database]], and emits domain events whenever product data changes so downstream systems — like the [[system|search-system]] — can react.
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<ComponentDiagram />
+
+## What's inside
+
+| Component                             | Type       | Responsibility                                                              |
+| ------------------------------------- | ---------- | --------------------------------------------------------------------------- |
+| [[service\|product-api]]              | Service    | Public-facing API. Handles create/update/delete commands and product reads. |
+| [[service\|product-worker]]           | Service    | Processes long-running and asynchronous catalog work off the request path.  |
+| [[service\|product-search-publisher]] | Service    | Publishes product change events for the Search System to consume.           |
+| [[container\|product-database]]       | Data store | PostgreSQL system of record for all product data.                           |
+
+## Messages this system publishes
+
+When product data changes, the system emits these events:
+
+- [[event|product-created]] — a new product has been added to the catalog.
+- [[event|product-updated]] — an existing product's data has changed.
+- [[event|product-deleted]] — a product has been removed from the catalog.
+- [[adr|adr-001-use-transactional-outbox]] — a product has been removed from the catalog.
+
+## Architecture decisions
+
+The key decisions that shaped this system. Search, filter by status, or sort by clicking a column.
+
+<ADRTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/CreateProduct/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/CreateProduct/index.mdx
new file mode 100644
index 000000000..d2b7eff42
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/CreateProduct/index.mdx
@@ -0,0 +1,32 @@
+---
+id: create-product
+name: Create Product
+version: 1.0.0
+summary: |
+  Command to add a new product to the catalog.
+owners:
+  - product-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /products
+  statusCodes: ['201', '400', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CreateProduct` is handled by the [[service|product-api]]. It validates the incoming product, writes it to the [[container|product-database]], and on success publishes a [[event|product-created]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/CreateProduct/schema.json b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/CreateProduct/schema.json
new file mode 100644
index 000000000..e363e2ea2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/CreateProduct/schema.json
@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CreateProduct",
+  "description": "Command to add a new product to the catalog",
+  "type": "object",
+  "properties": {
+    "sku": {
+      "description": "Stock keeping unit — must be unique",
+      "type": "string"
+    },
+    "name": {
+      "description": "Display name of the product",
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "description": "Long-form product description",
+      "type": "string"
+    },
+    "price": {
+      "description": "Price in minor units (e.g. cents)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "currency": {
+      "description": "ISO 4217 currency code",
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "category": {
+      "description": "Category the product belongs to",
+      "type": "string"
+    },
+    "status": {
+      "description": "Initial lifecycle status — defaults to DRAFT",
+      "type": "string",
+      "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+    }
+  },
+  "required": ["sku", "name", "price", "currency"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/DeleteProduct/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/DeleteProduct/index.mdx
new file mode 100644
index 000000000..9188d64e6
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/DeleteProduct/index.mdx
@@ -0,0 +1,32 @@
+---
+id: delete-product
+name: Delete Product
+version: 1.0.0
+summary: |
+  Command to remove a product from the catalog.
+owners:
+  - product-platform
+schemaPath: schema.json
+operation:
+  method: DELETE
+  path: /products/{productId}
+  statusCodes: ['204', '404']
+sidebar:
+  badge: 'DELETE'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`DeleteProduct` is handled by the [[service|product-api]]. It removes a product from the [[container|product-database]] and, on success, publishes a [[event|product-deleted]] event so downstream systems can clean up.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/DeleteProduct/schema.json b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/DeleteProduct/schema.json
new file mode 100644
index 000000000..97efc7c2d
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/DeleteProduct/schema.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "DeleteProduct",
+  "description": "Command to remove a product from the catalog",
+  "type": "object",
+  "properties": {
+    "productId": {
+      "description": "Unique identifier of the product to delete",
+      "type": "string",
+      "format": "uuid"
+    },
+    "reason": {
+      "description": "Optional reason the product is being removed",
+      "type": "string",
+      "enum": ["DISCONTINUED", "DUPLICATE", "MERCHANT_REQUEST", "OTHER"]
+    }
+  },
+  "required": ["productId"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/UpdateProduct/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/UpdateProduct/index.mdx
new file mode 100644
index 000000000..abb07e52f
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/UpdateProduct/index.mdx
@@ -0,0 +1,32 @@
+---
+id: update-product
+name: Update Product
+version: 1.0.0
+summary: |
+  Command to update an existing product in the catalog.
+owners:
+  - product-platform
+schemaPath: schema.json
+operation:
+  method: PATCH
+  path: /products/{productId}
+  statusCodes: ['200', '400', '404']
+sidebar:
+  badge: 'PATCH'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`UpdateProduct` is handled by the [[service|product-api]]. It applies a partial update to an existing product in the [[container|product-database]] and, on success, publishes a [[event|product-updated]] event describing what changed.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/UpdateProduct/schema.json b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/UpdateProduct/schema.json
new file mode 100644
index 000000000..5fcfac505
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/commands/UpdateProduct/schema.json
@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "UpdateProduct",
+  "description": "Command to update an existing product. Only the fields supplied are changed.",
+  "type": "object",
+  "properties": {
+    "productId": {
+      "description": "Unique identifier of the product to update",
+      "type": "string",
+      "format": "uuid"
+    },
+    "name": {
+      "description": "New display name",
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "description": "New long-form description",
+      "type": "string"
+    },
+    "price": {
+      "description": "New price in minor units (e.g. cents)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "currency": {
+      "description": "ISO 4217 currency code",
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "category": {
+      "description": "New category",
+      "type": "string"
+    },
+    "status": {
+      "description": "New lifecycle status",
+      "type": "string",
+      "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+    }
+  },
+  "required": ["productId"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/index.mdx
new file mode 100644
index 000000000..088514800
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: product-created
+name: Product Created
+version: 1.0.0
+summary: |
+  Published when a new product has been added to the catalog.
+owners:
+  - product-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ProductCreated` is published by the [[service|product-search-publisher]] whenever a new product is successfully added to the catalog by the [[service|product-api]]. The [[system|search-system]] consumes this event to index the new product so it becomes discoverable.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/schema.json b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/schema.json
new file mode 100644
index 000000000..25a1f8cd6
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductCreated/schema.json
@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ProductCreated",
+  "description": "Emitted when a new product is added to the catalog",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the product was created",
+      "type": "string",
+      "format": "date-time"
+    },
+    "product": {
+      "description": "The product that was created",
+      "type": "object",
+      "properties": {
+        "productId": {
+          "description": "Unique identifier for the product",
+          "type": "string",
+          "format": "uuid"
+        },
+        "sku": {
+          "description": "Stock keeping unit",
+          "type": "string"
+        },
+        "name": {
+          "description": "Display name of the product",
+          "type": "string"
+        },
+        "description": {
+          "description": "Long-form product description",
+          "type": "string"
+        },
+        "price": {
+          "description": "Price in minor units (e.g. cents)",
+          "type": "integer",
+          "minimum": 0
+        },
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "category": {
+          "description": "Category the product belongs to",
+          "type": "string"
+        },
+        "status": {
+          "description": "Lifecycle status of the product",
+          "type": "string",
+          "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+        }
+      },
+      "required": ["productId", "sku", "name", "price", "currency", "status"]
+    }
+  },
+  "required": ["eventId", "occurredAt", "product"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/index.mdx
new file mode 100644
index 000000000..30473458e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/index.mdx
@@ -0,0 +1,29 @@
+---
+id: product-deleted
+name: Product Deleted
+version: 1.0.0
+summary: |
+  Published when a product has been removed from the catalog.
+owners:
+  - product-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ProductDeleted` is published by the [[service|product-search-publisher]] when a product is removed from the catalog via the [[service|product-api]]. The [[system|search-system]] consumes this event to remove the product from the search index.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/schema.json b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/schema.json
new file mode 100644
index 000000000..26cc9a5dc
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductDeleted/schema.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ProductDeleted",
+  "description": "Emitted when a product is removed from the catalog",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the product was deleted",
+      "type": "string",
+      "format": "date-time"
+    },
+    "productId": {
+      "description": "Unique identifier for the product that was deleted",
+      "type": "string",
+      "format": "uuid"
+    },
+    "reason": {
+      "description": "Optional reason the product was removed",
+      "type": "string",
+      "enum": ["DISCONTINUED", "DUPLICATE", "MERCHANT_REQUEST", "OTHER"]
+    }
+  },
+  "required": ["eventId", "occurredAt", "productId"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/index.mdx
new file mode 100644
index 000000000..44e563b74
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: product-updated
+name: Product Updated
+version: 1.0.0
+summary: |
+  Published when an existing product's data has changed.
+owners:
+  - product-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ProductUpdated` is published by the [[service|product-search-publisher]] whenever an existing product is changed via the [[service|product-api]]. The [[system|search-system]] consumes this event to re-index the product so search results stay accurate.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/schema.json b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/schema.json
new file mode 100644
index 000000000..ce744bcb8
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/events/ProductUpdated/schema.json
@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ProductUpdated",
+  "description": "Emitted when an existing product's data changes",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the product was updated",
+      "type": "string",
+      "format": "date-time"
+    },
+    "productId": {
+      "description": "Unique identifier for the product that changed",
+      "type": "string",
+      "format": "uuid"
+    },
+    "changes": {
+      "description": "The fields that changed and their new values",
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "price": {
+          "description": "Price in minor units (e.g. cents)",
+          "type": "integer",
+          "minimum": 0
+        },
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "category": {
+          "type": "string"
+        },
+        "status": {
+          "description": "Lifecycle status of the product",
+          "type": "string",
+          "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+        }
+      },
+      "minProperties": 1
+    }
+  },
+  "required": ["eventId", "occurredAt", "productId", "changes"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/index.mdx
new file mode 100644
index 000000000..8bd22d298
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/index.mdx
@@ -0,0 +1,69 @@
+---
+id: product-api
+version: 1.0.0
+name: Product API
+summary: |
+  The public-facing API for the product catalog. Handles commands to create, update and delete products, serves product reads, and is the entry point into the Product Catalog System.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - product-platform
+receives:
+  - id: create-product
+    version: 1.0.0
+  - id: update-product
+    version: 1.0.0
+  - id: delete-product
+    version: 1.0.0
+  - id: get-product
+    version: 1.0.0
+writesTo:
+  - id: product-database
+readsFrom:
+  - id: product-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/product-api'
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Product API
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Product API** is the front door to the Product Catalog System. It validates incoming commands, persists product data to the [[container|product-database]], and records every change to the outbox. The [[service|product-search-publisher]] then turns those changes into the domain events the rest of the business consumes.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Commands and queries handled by this service"
+  />
+  <Tile
+    icon="CircleStackIcon"
+    href="/docs/services/product-api/1.0.0"
+    title="System of record"
+    description="Reads from and writes to the product database"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area             | Description                                                                                                                                 |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Command handling | Validates and applies [[command\|create-product]], [[command\|update-product]] and [[command\|delete-product]].                             |
+| Reads            | Serves [[query\|get-product]] directly from the product database.                                                                           |
+| Change capture   | Records every product change to the outbox in the [[container\|product-database]] for the [[service\|product-search-publisher]] to publish. |
+| Persistence      | Reads from and writes to the [[container\|product-database]] (system of record).                                                            |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/openapi.yml b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/openapi.yml
new file mode 100644
index 000000000..695bebdd9
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/openapi.yml
@@ -0,0 +1,219 @@
+openapi: 3.0.3
+info:
+  title: Product API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Product Catalog System. It is the entry point for
+    creating, updating, deleting and reading products. Every change is persisted
+    to the product database and recorded in the outbox so product change events
+    can be published to the rest of the business.
+  contact:
+    name: Product Platform
+    email: product-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+tags:
+  - name: Products
+    description: Manage and read products in the catalog.
+paths:
+  /products:
+    post:
+      operationId: createProduct
+      summary: Create a product
+      description: Adds a new product to the catalog. On success a `ProductCreated` event is published.
+      tags:
+        - Products
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateProductRequest'
+      responses:
+        '201':
+          description: The product was created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Product'
+        '400':
+          description: The request body was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: A product with the same SKU already exists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /products/{productId}:
+    parameters:
+      - $ref: '#/components/parameters/ProductId'
+    get:
+      operationId: getProduct
+      summary: Get a product
+      description: Returns the current state of a single product by its identifier.
+      tags:
+        - Products
+      responses:
+        '200':
+          description: The product was found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Product'
+        '404':
+          description: No product exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    patch:
+      operationId: updateProduct
+      summary: Update a product
+      description: Applies a partial update to an existing product. On success a `ProductUpdated` event is published.
+      tags:
+        - Products
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateProductRequest'
+      responses:
+        '200':
+          description: The product was updated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Product'
+        '400':
+          description: The request body was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: No product exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    delete:
+      operationId: deleteProduct
+      summary: Delete a product
+      description: Removes a product from the catalog. On success a `ProductDeleted` event is published.
+      tags:
+        - Products
+      parameters:
+        - name: reason
+          in: query
+          required: false
+          description: Optional reason the product is being removed.
+          schema:
+            type: string
+            enum: [DISCONTINUED, DUPLICATE, MERCHANT_REQUEST, OTHER]
+      responses:
+        '204':
+          description: The product was deleted.
+        '404':
+          description: No product exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  parameters:
+    ProductId:
+      name: productId
+      in: path
+      required: true
+      description: Unique identifier of the product.
+      schema:
+        type: string
+        format: uuid
+  schemas:
+    Product:
+      type: object
+      required: [productId, sku, name, price, currency, status]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        sku:
+          type: string
+          description: Stock keeping unit.
+        name:
+          type: string
+        description:
+          type: string
+        price:
+          type: integer
+          description: Price in minor units (e.g. cents).
+          minimum: 0
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        category:
+          type: string
+        status:
+          type: string
+          enum: [DRAFT, ACTIVE, ARCHIVED]
+    CreateProductRequest:
+      type: object
+      required: [sku, name, price, currency]
+      properties:
+        sku:
+          type: string
+          description: Stock keeping unit — must be unique.
+        name:
+          type: string
+          minLength: 1
+        description:
+          type: string
+        price:
+          type: integer
+          description: Price in minor units (e.g. cents).
+          minimum: 0
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        category:
+          type: string
+        status:
+          type: string
+          description: Initial lifecycle status — defaults to DRAFT.
+          enum: [DRAFT, ACTIVE, ARCHIVED]
+    UpdateProductRequest:
+      type: object
+      description: Only the fields supplied are changed.
+      minProperties: 1
+      properties:
+        name:
+          type: string
+          minLength: 1
+        description:
+          type: string
+        price:
+          type: integer
+          description: Price in minor units (e.g. cents).
+          minimum: 0
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        category:
+          type: string
+        status:
+          type: string
+          enum: [DRAFT, ACTIVE, ARCHIVED]
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/index.mdx
new file mode 100644
index 000000000..8fec5b3d7
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/index.mdx
@@ -0,0 +1,32 @@
+---
+id: get-product
+name: Get Product
+version: 1.0.0
+summary: |
+  Query to fetch a single product by its identifier.
+owners:
+  - product-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /products/{productId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetProduct` is handled by the [[service|product-api]]. It returns the current state of a single product, read directly from the [[container|product-database]]. Use the [[system|search-system]] when you need to search across many products instead.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/schema.json b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/schema.json
new file mode 100644
index 000000000..651038708
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductAPI/queries/GetProduct/schema.json
@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetProduct",
+  "description": "Query to fetch a single product by its identifier, and the product returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "Parameters used to look up the product",
+      "type": "object",
+      "properties": {
+        "productId": {
+          "description": "Unique identifier of the product to fetch",
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "required": ["productId"]
+    },
+    "response": {
+      "description": "The product returned by the query",
+      "type": "object",
+      "properties": {
+        "productId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "sku": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "price": {
+          "description": "Price in minor units (e.g. cents)",
+          "type": "integer"
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "category": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+        }
+      },
+      "required": ["productId", "sku", "name", "price", "currency", "status"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductSearchPublisher/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductSearchPublisher/index.mdx
new file mode 100644
index 000000000..327699ed7
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductSearchPublisher/index.mdx
@@ -0,0 +1,56 @@
+---
+id: product-search-publisher
+version: 1.0.0
+name: Product Search Publisher
+summary: |
+  Reads product changes from the product database (outbox) and reliably publishes product-created, product-updated and product-deleted events for the Search System to consume.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - product-platform
+readsFrom:
+  - id: product-database
+sends:
+  - id: product-created
+    version: 1.0.0
+  - id: product-updated
+    version: 1.0.0
+  - id: product-deleted
+    version: 1.0.0
+repository:
+  language: Go
+  url: 'https://github.com/acme/product-search-publisher'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Product Search Publisher** is the bridge between the Product Catalog System and the rest of the business. It uses the [transactional outbox pattern](https://microservices.io/patterns/data/transactional-outbox.html): the [[service|product-api]] records every product change in the [[container|product-database]], and this service reliably reads those changes and publishes them as [[event|product-created]], [[event|product-updated]] and [[event|product-deleted]] events.
+
+This guarantees that product changes are never lost and are delivered to the [[system|search-system]] in order.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Product change events published for downstream systems"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area                | Description                                                                                                                  |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Outbox polling      | Reads unpublished product changes from the [[container\|product-database]].                                                  |
+| Reliable publishing | Publishes [[event\|product-created]], [[event\|product-updated]] and [[event\|product-deleted]] with at-least-once delivery. |
+| Ordering            | Preserves per-product ordering of change events.                                                                             |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductWorker/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductWorker/index.mdx
new file mode 100644
index 000000000..255a460e3
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/product-catalog-system/services/ProductWorker/index.mdx
@@ -0,0 +1,48 @@
+---
+id: product-worker
+version: 1.0.0
+name: Product Worker
+summary: |
+  Background worker that handles long-running and asynchronous catalog work off the request path, such as enrichment, image processing and bulk imports.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - product-platform
+readsFrom:
+  - id: product-database
+writesTo:
+  - id: product-database
+repository:
+  language: Go
+  url: 'https://github.com/acme/product-worker'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Product Worker** keeps the [[service|product-api]] fast by taking slow or asynchronous work off the request path. It reads from and writes back to the [[container|product-database]], handling jobs like data enrichment, image processing and bulk catalog imports.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title="View in visualiser"
+    description="See how the Product Worker fits into the system"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area         | Description                                                                   |
+| ------------ | ----------------------------------------------------------------------------- |
+| Enrichment   | Augments product records with derived data after they are created or updated. |
+| Media        | Processes and optimises product images asynchronously.                        |
+| Bulk imports | Ingests large product feeds without blocking the API.                         |
+| Persistence  | Reads from and writes to the [[container\|product-database]].                 |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/containers/search-index/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/containers/search-index/index.mdx
new file mode 100644
index 000000000..7efe54a0c
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/containers/search-index/index.mdx
@@ -0,0 +1,39 @@
+---
+id: search-index
+name: Search Index
+version: 1.0.0
+summary: The denormalised, search-optimised index of products that powers product search.
+container_type: searchIndex
+technology: opensearch@2
+authoritative: false
+access_mode: readWrite
+purpose: Serve fast, relevant product search
+classification: internal
+retention: rebuildable
+residency: eu-west-1
+styles:
+  icon: /icons/analytics/clickhouse.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Search Index** is a denormalised, search-optimised copy of the catalog. It is **not** a source of truth — it can be rebuilt at any time by replaying product events from the [[system|product-catalog-system]]. The [[service|search-indexer]] keeps it up to date, and the [[service|search-api]] reads from it to answer [[query|search-products]] queries.
+
+### What does it store?
+
+One document per product, optimised for search:
+
+- Searchable text — name and description, analysed for full-text matching.
+- Filterable fields — category, status, price, currency.
+- A relevance signal used to rank results.
+
+### Why is it not authoritative?
+
+The system of record is the [[container|product-database]]. The index is a derived read model: if it is ever lost or corrupted, we rebuild it by replaying [[event|product-created]], [[event|product-updated]] and [[event|product-deleted]] events. This keeps search fast without coupling other teams to the catalog database.
+
+### Operational notes
+
+- **Rebuildable**: a full reindex is a supported, routine operation.
+- **Eventually consistent**: changes appear in search shortly after the [[service|search-indexer]] processes the corresponding event.
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/flows/ProductSearchIndexing/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/flows/ProductSearchIndexing/index.mdx
new file mode 100644
index 000000000..1e282fa6f
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/flows/ProductSearchIndexing/index.mdx
@@ -0,0 +1,130 @@
+---
+id: product-search-indexing
+name: Product Search Indexing
+version: 1.0.0
+summary: |
+  How a change to a product in the catalog reliably flows into the search index — via the outbox, product events and the indexer — so search stays in sync without coupling to the catalog database.
+owners:
+  - search-platform
+steps:
+  - id: merchant_edits_product
+    title: Merchant edits a product
+    actor:
+      name: Merchant
+      summary: A merchant creates or updates a product in the catalog.
+    next_step:
+      id: product_api
+      label: Apply change
+
+  - id: product_api
+    title: Product API
+    service:
+      id: product-api
+      version: 1.0.0
+    next_step:
+      id: product_database
+      label: Write change + outbox row
+
+  - id: product_database
+    title: Product Database
+    container:
+      id: product-database
+    next_step:
+      id: outbox_note
+      label: Outbox row committed
+
+  - id: outbox_note
+    title: Outbox pattern
+    custom:
+      title: Transactional outbox
+      color: blue
+      icon: InboxStackIcon
+      type: Pattern
+      summary: The product change and an outbox row are written in the same transaction, so the event can never be lost or out of sync with the data.
+      properties:
+        guarantee: 'change and event are atomic'
+    next_step:
+      id: product_search_publisher
+      label: Drain outbox
+
+  - id: product_search_publisher
+    title: Product Search Publisher
+    service:
+      id: product-search-publisher
+      version: 1.0.0
+    next_steps:
+      - id: product_created
+        label: Created
+      - id: product_updated
+        label: Updated
+      - id: product_deleted
+        label: Deleted
+
+  - id: product_created
+    title: Product Created
+    message:
+      id: product-created
+      version: 1.0.0
+    next_step:
+      id: search_indexer
+      label: Index product
+
+  - id: product_updated
+    title: Product Updated
+    message:
+      id: product-updated
+      version: 1.0.0
+    next_step:
+      id: search_indexer
+      label: Re-index product
+
+  - id: product_deleted
+    title: Product Deleted
+    message:
+      id: product-deleted
+      version: 1.0.0
+    next_step:
+      id: search_indexer
+      label: Remove from index
+
+  - id: search_indexer
+    title: Search Indexer
+    service:
+      id: search-indexer
+      version: 1.0.0
+    next_step:
+      id: search_index
+      label: Apply to index
+
+  - id: search_index
+    title: Search Index
+    container:
+      id: search-index
+    next_step:
+      id: searchable
+      label: Available to search
+
+  - id: searchable
+    title: Product is searchable
+    custom:
+      title: Product is searchable
+      color: green
+      icon: MagnifyingGlassIcon
+      type: Outcome
+      summary: The change is reflected in the search index and immediately available to customers via the Search API.
+      properties:
+        read_model: 'derived, rebuildable from events'
+---
+
+## Overview
+
+**Product Search Indexing** documents how the [[system|search-system]] keeps its index in sync with the catalog. The search index is a derived read model — never a source of truth — so it can be rebuilt at any time by replaying product events.
+
+<NodeGraph />
+
+## How it works
+
+1. A merchant changes a product via the [[service|product-api]], which writes the change and an outbox row to the [[container|product-database]] in one transaction.
+2. The [[service|product-search-publisher]] reliably drains the outbox and publishes [[event|product-created]], [[event|product-updated]] or [[event|product-deleted]].
+3. The [[service|search-indexer]] consumes those events and applies them to the [[container|search-index]].
+4. The change is now searchable via the Search API — with no direct coupling between search and the catalog database.
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/index.mdx
new file mode 100644
index 000000000..2dc332226
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/index.mdx
@@ -0,0 +1,66 @@
+---
+id: search-system
+name: Search System
+version: 1.0.0
+summary: |
+  Internal system that keeps product data searchable. Consumes product change events from the Product Catalog System, maintains a search index, and serves fast product search to the rest of the business.
+owners:
+  - search-platform
+services:
+  - id: search-api
+  - id: search-indexer
+containers:
+  - id: search-index
+flows:
+  - id: product-search-indexing
+    version: 1.0.0
+relationships:
+  - id: product-catalog-system
+    label: indexes product changes from
+actors:
+  - id: shopper
+    name: Shopper
+    label: searches for products
+    direction: inbound
+  - id: storefront-team
+    name: Storefront Team
+    label: integrates product search
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Search System** makes the catalog discoverable. It subscribes to product change events published by the [[system|product-catalog-system]], updates its [[container|search-index]], and exposes a search API so other teams can find products without ever touching the catalog database directly.
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                   | Type       | Responsibility                                                        |
+| --------------------------- | ---------- | --------------------------------------------------------------------- |
+| [[service\|search-api]]     | Service    | Public-facing API. Serves product search queries from the index.      |
+| [[service\|search-indexer]] | Service    | Consumes product change events and keeps the search index up to date. |
+| [[container\|search-index]] | Data store | The index that powers product search.                                 |
+
+## Messages this system consumes
+
+The Search System reacts to product changes published by the Product Catalog System:
+
+- [[event|product-created]] — index the new product.
+- [[event|product-updated]] — re-index the changed product.
+- [[event|product-deleted]] — remove the product from the index.
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/index.mdx
new file mode 100644
index 000000000..65728ea66
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/index.mdx
@@ -0,0 +1,44 @@
+---
+id: search-api
+version: 1.0.0
+name: Search API
+summary: |
+  Public-facing API that serves fast, relevant product search to the rest of the business, reading from the search index.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - search-platform
+receives:
+  - id: search-products
+    version: 1.0.0
+readsFrom:
+  - id: search-index
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/search-api'
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Search API
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Search API** is the front door to the Search System. It answers [[query|search-products]] queries by reading from the [[container|search-index]], which is kept current by the [[service|search-indexer]]. Other teams use this API so they never have to query the catalog database directly.
+
+### Responsibilities
+
+| Area   | Description                                                                          |
+| ------ | ------------------------------------------------------------------------------------ |
+| Search | Serves [[query\|search-products]] with full-text matching, filtering and pagination. |
+| Reads  | Queries the [[container\|search-index]] — never the catalog database.                |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/openapi.yml b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/openapi.yml
new file mode 100644
index 000000000..d90532519
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/openapi.yml
@@ -0,0 +1,138 @@
+openapi: 3.0.3
+info:
+  title: Search API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Search System. Serves fast, relevant product
+    search by reading from the search index, which is kept in sync with the
+    product catalog.
+  contact:
+    name: Search Platform
+    email: search-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+paths:
+  /search/products:
+    get:
+      operationId: searchProducts
+      summary: Search the catalog for products
+      description: |
+        Runs a full-text search over the product index and returns a paginated
+        list of matching products. Supports optional filters and pagination.
+      tags:
+        - Search
+      parameters:
+        - name: query
+          in: query
+          required: true
+          description: Free-text search term.
+          schema:
+            type: string
+            minLength: 1
+          example: wireless headphones
+        - name: category
+          in: query
+          required: false
+          description: Restrict results to a single category.
+          schema:
+            type: string
+          example: audio
+        - name: status
+          in: query
+          required: false
+          description: Restrict results to products with this lifecycle status.
+          schema:
+            type: string
+            enum: [DRAFT, ACTIVE, ARCHIVED]
+        - name: minPrice
+          in: query
+          required: false
+          description: Minimum price in minor units (e.g. cents).
+          schema:
+            type: integer
+            minimum: 0
+        - name: maxPrice
+          in: query
+          required: false
+          description: Maximum price in minor units (e.g. cents).
+          schema:
+            type: integer
+            minimum: 0
+        - name: page
+          in: query
+          required: false
+          description: 1-based page number.
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - name: pageSize
+          in: query
+          required: false
+          description: Number of results per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        '200':
+          description: A paginated list of matching products.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SearchResults'
+        '400':
+          description: The request was invalid (e.g. a missing or empty query).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  schemas:
+    SearchResults:
+      type: object
+      required: [total, page, pageSize, results]
+      properties:
+        total:
+          type: integer
+          description: Total number of products matching the query.
+        page:
+          type: integer
+        pageSize:
+          type: integer
+        results:
+          type: array
+          items:
+            $ref: '#/components/schemas/ProductSearchResult'
+    ProductSearchResult:
+      type: object
+      required: [productId, sku, name]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        sku:
+          type: string
+        name:
+          type: string
+        category:
+          type: string
+        price:
+          type: integer
+          description: Price in minor units (e.g. cents).
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        score:
+          type: number
+          description: Relevance score for this result.
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/index.mdx
new file mode 100644
index 000000000..49184611b
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/index.mdx
@@ -0,0 +1,32 @@
+---
+id: search-products
+name: Search Products
+version: 1.0.0
+summary: |
+  Query to search the catalog for products matching a term, with optional filters and pagination.
+owners:
+  - search-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /search/products
+  statusCodes: ['200', '400']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`SearchProducts` is handled by the [[service|search-api]]. It runs a full-text search over the [[container|search-index]] and returns a paginated list of matching products. Use this whenever you need to find products across the catalog, rather than fetching a single product by id with [[query|get-product]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/schema.json b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/schema.json
new file mode 100644
index 000000000..d9eea41f8
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchAPI/queries/SearchProducts/schema.json
@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SearchProducts",
+  "description": "Query to search the catalog for products, and the paginated result returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "Search parameters",
+      "type": "object",
+      "properties": {
+        "query": {
+          "description": "Free-text search term",
+          "type": "string",
+          "minLength": 1
+        },
+        "filters": {
+          "description": "Optional filters applied to the search",
+          "type": "object",
+          "properties": {
+            "category": {
+              "type": "string"
+            },
+            "status": {
+              "type": "string",
+              "enum": ["DRAFT", "ACTIVE", "ARCHIVED"]
+            },
+            "minPrice": {
+              "description": "Minimum price in minor units (e.g. cents)",
+              "type": "integer",
+              "minimum": 0
+            },
+            "maxPrice": {
+              "description": "Maximum price in minor units (e.g. cents)",
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "page": {
+          "description": "1-based page number",
+          "type": "integer",
+          "minimum": 1,
+          "default": 1
+        },
+        "pageSize": {
+          "description": "Number of results per page",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "default": 20
+        }
+      },
+      "required": ["query"]
+    },
+    "response": {
+      "description": "Paginated search results",
+      "type": "object",
+      "properties": {
+        "total": {
+          "description": "Total number of products matching the query",
+          "type": "integer"
+        },
+        "page": {
+          "type": "integer"
+        },
+        "pageSize": {
+          "type": "integer"
+        },
+        "results": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "productId": {
+                "type": "string",
+                "format": "uuid"
+              },
+              "sku": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              },
+              "category": {
+                "type": "string"
+              },
+              "price": {
+                "description": "Price in minor units (e.g. cents)",
+                "type": "integer"
+              },
+              "currency": {
+                "type": "string",
+                "pattern": "^[A-Z]{3}$"
+              },
+              "score": {
+                "description": "Relevance score for this result",
+                "type": "number"
+              }
+            },
+            "required": ["productId", "sku", "name"]
+          }
+        }
+      },
+      "required": ["total", "page", "pageSize", "results"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchIndexer/index.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchIndexer/index.mdx
new file mode 100644
index 000000000..86043091d
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/systems/search-system/services/SearchIndexer/index.mdx
@@ -0,0 +1,54 @@
+---
+id: search-indexer
+version: 1.0.0
+name: Search Indexer
+summary: |
+  Consumes product change events from the Product Catalog System and keeps the search index up to date so products are discoverable.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - search-platform
+receives:
+  - id: product-created
+    version: 1.0.0
+  - id: product-updated
+    version: 1.0.0
+  - id: product-deleted
+    version: 1.0.0
+writesTo:
+  - id: search-index
+repository:
+  language: Go
+  url: 'https://github.com/acme/search-indexer'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Search Indexer** is how the Search System stays in sync with the catalog. It subscribes to [[event|product-created]], [[event|product-updated]] and [[event|product-deleted]] events published by the [[system|product-catalog-system]] and applies each change to the [[container|search-index]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Product change events consumed from the catalog"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Event                      | Action                                                  |
+| -------------------------- | ------------------------------------------------------- |
+| [[event\|product-created]] | Add the new product to the [[container\|search-index]]. |
+| [[event\|product-updated]] | Re-index the changed product.                           |
+| [[event\|product-deleted]] | Remove the product from the index.                      |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Catalog/ubiquitous-language.mdx b/packages/create-eventcatalog/templates/default/domains/Catalog/ubiquitous-language.mdx
new file mode 100644
index 000000000..db0372f10
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Catalog/ubiquitous-language.mdx
@@ -0,0 +1,54 @@
+---
+dictionary:
+  - id: Product
+    name: Product
+    summary: 'A single item Acme Inc sells, with a name, price, category and lifecycle status.'
+    description: |
+      A product is the central concept of the Catalog domain. It is owned and maintained by the
+      Product Catalog System, which is the source of truth for all product data. A product carries:
+
+      - A unique product id and a unique SKU
+      - Display name, description and category
+      - Price (in minor units) and currency
+      - A lifecycle status (DRAFT, ACTIVE or ARCHIVED)
+
+      Every change to a product publishes a domain event so the rest of the business — including
+      search — can react.
+    icon: Package
+  - id: SKU
+    name: SKU
+    summary: 'Stock Keeping Unit — the unique, human-meaningful code that identifies a product.'
+    description: |
+      A SKU uniquely identifies a product in the catalog and must be unique across all products.
+      Unlike the internal product id (a UUID), the SKU is the code teams and merchants use day to day.
+    icon: Tag
+  - id: Catalog
+    name: Catalog
+    summary: 'The complete, authoritative collection of products Acme Inc offers.'
+    icon: BookOpen
+  - id: Search Index
+    name: Search Index
+    summary: 'A denormalised, search-optimised copy of the catalog that powers product search.'
+    description: |
+      The search index is a derived read model, not a source of truth. It is kept in sync by the
+      Search System consuming product change events, and can be rebuilt at any time by replaying
+      those events. It exists to serve fast, relevant search without coupling consumers to the
+      catalog database.
+    icon: Search
+  - id: Lifecycle Status
+    name: Lifecycle Status
+    summary: 'Where a product sits in its life: DRAFT, ACTIVE or ARCHIVED.'
+    description: |
+      - DRAFT — being prepared, not yet visible to customers.
+      - ACTIVE — live and discoverable.
+      - ARCHIVED — withdrawn from sale but retained for history.
+    icon: Workflow
+  - id: Outbox
+    name: Outbox
+    summary: 'A table where product changes are recorded in the same transaction, then published as events.'
+    description: |
+      The outbox is how the Product Catalog System guarantees that a product change and its event
+      are never out of sync. The Product API writes the change and an outbox row in one transaction;
+      the Product Search Publisher reliably drains the outbox to the broker.
+    icon: Mail
+---
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/entities/authentication-session/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/entities/authentication-session/index.mdx
new file mode 100644
index 000000000..967bdbf94
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/entities/authentication-session/index.mdx
@@ -0,0 +1,35 @@
+---
+id: authentication-session
+name: Authentication Session
+version: 1.0.0
+identifier: sessionId
+summary: A successful customer authentication session.
+owners:
+  - customer-platform
+properties:
+  - name: sessionId
+    type: UUID
+    required: true
+    description: Unique authentication session identifier.
+  - name: accountId
+    type: UUID
+    required: true
+    description: Account authenticated in the session.
+    references: customer-account
+    relationType: belongsTo
+    referencesIdentifier: accountId
+  - name: authenticatedAt
+    type: datetime
+    required: true
+    description: Time authentication succeeded.
+  - name: expiresAt
+    type: datetime
+    required: true
+    description: Time the session expires.
+---
+
+## Overview
+
+Authentication Session represents successful login behavior emitted by [[event|customer-authenticated]].
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/entities/customer-account/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/entities/customer-account/index.mdx
new file mode 100644
index 000000000..032cd7b1a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/entities/customer-account/index.mdx
@@ -0,0 +1,36 @@
+---
+id: customer-account
+name: Customer Account
+version: 1.0.0
+identifier: accountId
+aggregateRoot: true
+summary: The identity account used to authenticate a customer.
+owners:
+  - customer-platform
+properties:
+  - name: accountId
+    type: UUID
+    required: true
+    description: Unique account identifier.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer profile linked to this account.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: provider
+    type: string
+    required: true
+    description: Identity provider name.
+  - name: status
+    type: string
+    required: true
+    description: Account lifecycle state.
+---
+
+## Overview
+
+Customer Account belongs to the Identity Provider boundary and should not be queried directly by order, payment or review services.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/entities/customer-address/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/entities/customer-address/index.mdx
new file mode 100644
index 000000000..cc2b0fa83
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/entities/customer-address/index.mdx
@@ -0,0 +1,35 @@
+---
+id: customer-address
+name: Customer Address
+version: 1.0.0
+identifier: addressId
+summary: A saved address attached to a customer profile.
+owners:
+  - customer-platform
+properties:
+  - name: addressId
+    type: UUID
+    required: true
+    description: Unique address identifier.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer who owns the address.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: countryCode
+    type: string
+    required: true
+    description: ISO country code.
+  - name: postalCode
+    type: string
+    required: true
+    description: Postal or ZIP code.
+---
+
+## Overview
+
+Customer Address supports checkout and fulfilment while remaining owned by the Customer domain.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/entities/customer-profile/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/entities/customer-profile/index.mdx
new file mode 100644
index 000000000..6cf87760e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/entities/customer-profile/index.mdx
@@ -0,0 +1,33 @@
+---
+id: customer-profile
+name: Customer Profile
+version: 1.0.0
+identifier: customerId
+aggregateRoot: true
+summary: The customer details Acme uses for commerce interactions.
+owners:
+  - customer-platform
+properties:
+  - name: customerId
+    type: UUID
+    required: true
+    description: Unique customer identifier.
+  - name: email
+    type: string
+    required: true
+    description: Customer email address.
+  - name: displayName
+    type: string
+    required: false
+    description: Preferred customer display name.
+  - name: status
+    type: string
+    required: true
+    description: Customer profile state.
+---
+
+## Overview
+
+Customer Profile is owned by [[system|customer-management-system]] and is separate from authentication credentials.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/index.mdx
new file mode 100644
index 000000000..ba85455db
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/index.mdx
@@ -0,0 +1,67 @@
+---
+id: customer
+name: Customer
+version: 1.0.0
+summary: |
+  The Customer domain owns who our customers are — how they register, how their profile is maintained, and how they are authenticated across Acme Inc. It is the source of truth for customer identity and profile data.
+owners:
+  - customer-platform
+systems:
+  - id: customer-management-system
+    version: 1.0.0
+  - id: identity-provider
+    version: 1.0.0
+entities:
+  - id: customer-profile
+    version: 1.0.0
+  - id: customer-account
+    version: 1.0.0
+  - id: authentication-session
+    version: 1.0.0
+  - id: customer-address
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Customer** domain is responsible for the lifecycle of every customer account at Acme Inc — registration, profile updates, and authentication. It is split into two systems:
+
+<Tiles>
+  <Tile
+    icon="RectangleGroupIcon"
+    href="/docs/systems/customer-management-system/1.0.0"
+    title="Customer Management System"
+    description="System of record for customer profiles — register, update and read customers."
+  />
+  <Tile
+    icon="LockClosedIcon"
+    href="/docs/systems/identity-provider/1.0.0"
+    title="Identity Provider"
+    description="Authenticates customers and is the source of truth for credentials and login."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Customer Management System** owns customer profile data — it accepts registration and update commands and publishes events when customers change. The **Identity Provider** handles authentication: it verifies credentials and emits an event when a customer successfully authenticates, which the rest of the business can react to.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The components that make up this domain.
+
+<NodeGraph />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/containers/customer-database/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/containers/customer-database/index.mdx
new file mode 100644
index 000000000..f080e0dce
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/containers/customer-database/index.mdx
@@ -0,0 +1,43 @@
+---
+id: customer-database
+name: Customer Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for all customer profile data.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for customer profiles
+classification: confidential
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Customer Database** is the authoritative store for every customer profile at Acme Inc. The [[service|customer-api]] reads from and writes to it. It stores profile data only — credentials and authentication live in the [[system|identity-provider]]'s [[container|user-directory]], not here.
+
+### What does it store?
+
+- **Customers** — one row per customer: id, email, name and account status.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Customer Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Access patterns
+
+- The [[service|customer-api]] is the only writer on the request path.
+- No credentials or passwords are stored here — only profile data. Authentication is owned by the [[system|identity-provider]].
+
+### Classification
+
+Customer profile data is **confidential**. Access is role-based and least-privilege; PII handling follows Acme's data policies.
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/containers/customer-database/schema.sql b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/containers/customer-database/schema.sql
new file mode 100644
index 000000000..dc7cb2851
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/containers/customer-database/schema.sql
@@ -0,0 +1,14 @@
+-- Customer Database — system of record for customer profiles
+-- Note: credentials/authentication are owned by the Identity Provider, not stored here.
+
+CREATE TABLE customers (
+    customer_id  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email        TEXT NOT NULL UNIQUE,
+    name         TEXT,
+    status       TEXT NOT NULL DEFAULT 'ACTIVE'
+                   CHECK (status IN ('ACTIVE', 'SUSPENDED', 'CLOSED')),
+    registered_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_customers_status ON customers (status);
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/index.mdx
new file mode 100644
index 000000000..f4d38f264
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/index.mdx
@@ -0,0 +1,60 @@
+---
+id: customer-management-system
+name: Customer Management System
+version: 1.0.0
+summary: |
+  Internal system that is the source of truth for customer profile data. Owns the customer database and publishes customer change events for the rest of the business to consume.
+owners:
+  - customer-platform
+services:
+  - id: customer-api
+containers:
+  - id: customer-database
+relationships:
+  - id: identity-provider
+    label: delegates authentication to
+actors:
+  - id: customer
+    name: Customer
+    label: registers and updates their profile
+    direction: inbound
+  - id: support-agent
+    name: Support Agent
+    label: looks up customer details
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Customer Management System** is the system of record for customer profiles at Acme Inc. It accepts commands to register and update customers, persists them in the [[container|customer-database]], and emits domain events whenever customer data changes so downstream systems can react. It delegates authentication to the [[system|identity-provider]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                        | Type       | Responsibility                                                                                                |
+| -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
+| [[service\|customer-api]]        | Service    | Public-facing API. Handles register/update commands and customer reads, and publishes customer change events. |
+| [[container\|customer-database]] | Data store | PostgreSQL system of record for all customer profile data.                                                    |
+
+## Messages this system publishes
+
+When customer data changes, the system emits these events:
+
+- [[event|customer-registered]] — a new customer has registered.
+- [[event|customer-updated]] — an existing customer's profile has changed.
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/RegisterCustomer/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/RegisterCustomer/index.mdx
new file mode 100644
index 000000000..e63124576
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/RegisterCustomer/index.mdx
@@ -0,0 +1,32 @@
+---
+id: register-customer
+name: Register Customer
+version: 1.0.0
+summary: |
+  Command to register a new customer.
+owners:
+  - customer-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /customers
+  statusCodes: ['201', '400', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RegisterCustomer` is handled by the [[service|customer-api]]. It validates the new customer, writes it to the [[container|customer-database]], and on success publishes a [[event|customer-registered]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/RegisterCustomer/schema.json b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/RegisterCustomer/schema.json
new file mode 100644
index 000000000..91d5fc594
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/RegisterCustomer/schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RegisterCustomer",
+  "description": "Command to register a new customer",
+  "type": "object",
+  "properties": {
+    "email": {
+      "description": "Customer's email address — must be unique",
+      "type": "string",
+      "format": "email"
+    },
+    "name": {
+      "description": "Customer's full name",
+      "type": "string",
+      "minLength": 1
+    },
+    "password": {
+      "description": "Initial password for the customer's credentials",
+      "type": "string",
+      "minLength": 8
+    }
+  },
+  "required": ["email", "password"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/UpdateCustomer/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/UpdateCustomer/index.mdx
new file mode 100644
index 000000000..136714bb2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/UpdateCustomer/index.mdx
@@ -0,0 +1,32 @@
+---
+id: update-customer
+name: Update Customer
+version: 1.0.0
+summary: |
+  Command to update an existing customer's profile.
+owners:
+  - customer-platform
+schemaPath: schema.json
+operation:
+  method: PATCH
+  path: /customers/{customerId}
+  statusCodes: ['200', '400', '404']
+sidebar:
+  badge: 'PATCH'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`UpdateCustomer` is handled by the [[service|customer-api]]. It applies a partial update to an existing customer in the [[container|customer-database]] and, on success, publishes a [[event|customer-updated]] event describing what changed.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/UpdateCustomer/schema.json b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/UpdateCustomer/schema.json
new file mode 100644
index 000000000..a9360cea1
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/commands/UpdateCustomer/schema.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "UpdateCustomer",
+  "description": "Command to update an existing customer. Only the fields supplied are changed.",
+  "type": "object",
+  "properties": {
+    "customerId": {
+      "description": "Unique identifier of the customer to update",
+      "type": "string",
+      "format": "uuid"
+    },
+    "email": {
+      "description": "New email address",
+      "type": "string",
+      "format": "email"
+    },
+    "name": {
+      "description": "New full name",
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "description": "New account status",
+      "type": "string",
+      "enum": ["ACTIVE", "SUSPENDED", "CLOSED"]
+    }
+  },
+  "required": ["customerId"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerRegistered/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerRegistered/index.mdx
new file mode 100644
index 000000000..b2b9adf91
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerRegistered/index.mdx
@@ -0,0 +1,29 @@
+---
+id: customer-registered
+name: Customer Registered
+version: 1.0.0
+summary: |
+  Published when a new customer has registered.
+owners:
+  - customer-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CustomerRegistered` is published by the [[service|customer-api]] whenever a new customer successfully registers. Downstream systems consume this event to onboard the customer.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerRegistered/schema.json b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerRegistered/schema.json
new file mode 100644
index 000000000..b9e1d6503
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerRegistered/schema.json
@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CustomerRegistered",
+  "description": "Emitted when a new customer registers",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the customer registered",
+      "type": "string",
+      "format": "date-time"
+    },
+    "customer": {
+      "description": "The customer that registered",
+      "type": "object",
+      "properties": {
+        "customerId": {
+          "description": "Unique identifier for the customer",
+          "type": "string",
+          "format": "uuid"
+        },
+        "email": {
+          "description": "Customer's email address",
+          "type": "string",
+          "format": "email"
+        },
+        "name": {
+          "description": "Customer's full name",
+          "type": "string"
+        },
+        "status": {
+          "description": "Lifecycle status of the customer account",
+          "type": "string",
+          "enum": ["ACTIVE", "SUSPENDED", "CLOSED"]
+        }
+      },
+      "required": ["customerId", "email", "status"]
+    }
+  },
+  "required": ["eventId", "occurredAt", "customer"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/index.mdx
new file mode 100644
index 000000000..fee2d39e7
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: customer-updated
+name: Customer Updated
+version: 1.0.0
+summary: |
+  Published when an existing customer's profile has changed.
+owners:
+  - customer-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CustomerUpdated` is published by the [[service|customer-api]] whenever an existing customer's profile changes. Downstream systems consume this event to keep their copy of customer data in sync.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/schema.json b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/schema.json
new file mode 100644
index 000000000..40069594f
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/events/CustomerUpdated/schema.json
@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CustomerUpdated",
+  "description": "Emitted when an existing customer's profile changes",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the customer was updated",
+      "type": "string",
+      "format": "date-time"
+    },
+    "customerId": {
+      "description": "Unique identifier for the customer that changed",
+      "type": "string",
+      "format": "uuid"
+    },
+    "changes": {
+      "description": "The fields that changed and their new values",
+      "type": "object",
+      "properties": {
+        "email": {
+          "type": "string",
+          "format": "email"
+        },
+        "name": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["ACTIVE", "SUSPENDED", "CLOSED"]
+        }
+      },
+      "minProperties": 1
+    }
+  },
+  "required": ["eventId", "occurredAt", "customerId", "changes"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/index.mdx
new file mode 100644
index 000000000..748fd7d53
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/index.mdx
@@ -0,0 +1,72 @@
+---
+id: customer-api
+version: 1.0.0
+name: Customer API
+summary: |
+  The public-facing API for customer profiles. Handles commands to register and update customers, serves customer reads, and publishes customer change events.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - customer-platform
+receives:
+  - id: register-customer
+    version: 1.0.0
+  - id: update-customer
+    version: 1.0.0
+  - id: get-customer
+    version: 1.0.0
+sends:
+  - id: customer-registered
+    version: 1.0.0
+  - id: customer-updated
+    version: 1.0.0
+writesTo:
+  - id: customer-database
+readsFrom:
+  - id: customer-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/customer-api'
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Customer API
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Customer API** is the front door to the Customer Management System. It validates incoming commands, persists customer data to the [[container|customer-database]], and publishes domain events (<ResourceLink id="customer-registered" type="event">CustomerRegistered</ResourceLink>, <ResourceLink id="customer-updated" type="event">CustomerUpdated</ResourceLink>) so the rest of the business can react to changes.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Domain events published when customer data changes"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Commands and queries handled by this service"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area             | Description                                                                            |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| Command handling | Validates and applies [[command\|register-customer]] and [[command\|update-customer]]. |
+| Reads            | Serves [[query\|get-customer]] directly from the customer database.                    |
+| Event publishing | Emits [[event\|customer-registered]] and [[event\|customer-updated]] on every change.  |
+| Persistence      | Reads from and writes to the [[container\|customer-database]] (system of record).      |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/openapi.yml b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/openapi.yml
new file mode 100644
index 000000000..40f6aeb04
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/openapi.yml
@@ -0,0 +1,164 @@
+openapi: 3.0.3
+info:
+  title: Customer API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Customer Management System. It is the entry point
+    for registering, updating and reading customers. Every change is persisted
+    to the customer database and published as a customer change event.
+  contact:
+    name: Customer Platform
+    email: customer-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+tags:
+  - name: Customers
+    description: Manage and read customer profiles.
+paths:
+  /customers:
+    post:
+      operationId: registerCustomer
+      summary: Register a customer
+      description: Registers a new customer. On success a `CustomerRegistered` event is published.
+      tags:
+        - Customers
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegisterCustomerRequest'
+      responses:
+        '201':
+          description: The customer was registered.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Customer'
+        '400':
+          description: The request body was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: A customer with the same email already exists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /customers/{customerId}:
+    parameters:
+      - name: customerId
+        in: path
+        required: true
+        description: Unique identifier of the customer.
+        schema:
+          type: string
+          format: uuid
+    get:
+      operationId: getCustomer
+      summary: Get a customer
+      description: Returns the current state of a single customer by their identifier.
+      tags:
+        - Customers
+      responses:
+        '200':
+          description: The customer was found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Customer'
+        '404':
+          description: No customer exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    patch:
+      operationId: updateCustomer
+      summary: Update a customer
+      description: Applies a partial update to an existing customer. On success a `CustomerUpdated` event is published.
+      tags:
+        - Customers
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateCustomerRequest'
+      responses:
+        '200':
+          description: The customer was updated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Customer'
+        '400':
+          description: The request body was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: No customer exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  schemas:
+    Customer:
+      type: object
+      required: [customerId, email, status]
+      properties:
+        customerId:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+        status:
+          type: string
+          enum: [ACTIVE, SUSPENDED, CLOSED]
+        registeredAt:
+          type: string
+          format: date-time
+    RegisterCustomerRequest:
+      type: object
+      required: [email, password]
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          minLength: 1
+        password:
+          type: string
+          minLength: 8
+    UpdateCustomerRequest:
+      type: object
+      description: Only the fields supplied are changed.
+      minProperties: 1
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          minLength: 1
+        status:
+          type: string
+          enum: [ACTIVE, SUSPENDED, CLOSED]
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/index.mdx
new file mode 100644
index 000000000..02094e07d
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/index.mdx
@@ -0,0 +1,32 @@
+---
+id: get-customer
+name: Get Customer
+version: 1.0.0
+summary: |
+  Query to fetch a single customer by their identifier.
+owners:
+  - customer-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /customers/{customerId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetCustomer` is handled by the [[service|customer-api]]. It returns the current state of a single customer, read directly from the [[container|customer-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/schema.json b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/schema.json
new file mode 100644
index 000000000..f42128b64
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/schema.json
@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetCustomer",
+  "description": "Query to fetch a single customer by their identifier, and the customer returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "Parameters used to look up the customer",
+      "type": "object",
+      "properties": {
+        "customerId": {
+          "description": "Unique identifier of the customer to fetch",
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "required": ["customerId"]
+    },
+    "response": {
+      "description": "The customer returned by the query",
+      "type": "object",
+      "properties": {
+        "customerId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "email": {
+          "type": "string",
+          "format": "email"
+        },
+        "name": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["ACTIVE", "SUSPENDED", "CLOSED"]
+        },
+        "registeredAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "required": ["customerId", "email", "status"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/containers/user-directory/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/containers/user-directory/index.mdx
new file mode 100644
index 000000000..30932eb03
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/containers/user-directory/index.mdx
@@ -0,0 +1,36 @@
+---
+id: user-directory
+name: User Directory
+version: 1.0.0
+summary: The directory of customer credentials and identities — the source of truth for authentication.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for credentials and login identities
+classification: regulated
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **User Directory** is the authoritative store for customer credentials and login identities. The [[service|oauth-api]] reads from it to verify sign-in attempts. It holds **only** authentication data — customer profile data lives separately in the [[system|customer-management-system]]'s [[container|customer-database]].
+
+### What does it store?
+
+- **Identities** — one record per customer: the login email and a securely hashed credential.
+- **Login metadata** — last login time, multi-factor settings, lockout state.
+
+### Why is it separate from the customer profile?
+
+Keeping credentials in a dedicated, **regulated**-classification store isolates the most sensitive data from general profile data. Authentication is owned by the Identity Provider; the Customer Management System never sees raw credentials.
+
+### Security
+
+- Credentials are stored only as salted, hashed values — never in plaintext.
+- Access is tightly restricted to the [[service|oauth-api]] under least-privilege roles.
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/index.mdx
new file mode 100644
index 000000000..158b27f61
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/index.mdx
@@ -0,0 +1,54 @@
+---
+id: identity-provider
+name: Identity Provider
+version: 1.0.0
+summary: |
+  The identity system that authenticates customers. It is the source of truth for credentials and login, verifies sign-in attempts, and emits an event when a customer successfully authenticates.
+scope: external
+owners:
+  - customer-platform
+services:
+  - id: oauth-api
+containers:
+  - id: user-directory
+relationships:
+  - id: customer-management-system
+    label: provides authentication for
+actors:
+  - id: customer
+    name: Customer
+    label: signs in
+    direction: inbound
+badges:
+  - content: Identity
+    backgroundColor: purple
+    textColor: purple
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Identity Provider** authenticates customers for Acme Inc. It exposes an OAuth-style API, verifies credentials against the [[container|user-directory]], and emits a [[event|customer-authenticated]] event on a successful sign-in so other systems can react. It provides authentication for the [[system|customer-management-system]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                     | Type       | Responsibility                                                                                       |
+| ----------------------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
+| [[service\|oauth-api]]        | Service    | OAuth-style authentication API. Handles authentication requests and publishes authentication events. |
+| [[container\|user-directory]] | Data store | The directory of customer credentials and identities.                                                |
+
+## Messages this system publishes
+
+- [[event|customer-authenticated]] — a customer has successfully authenticated.
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/index.mdx
new file mode 100644
index 000000000..b888ded2c
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/index.mdx
@@ -0,0 +1,32 @@
+---
+id: authenticate-customer
+name: Authenticate Customer
+version: 1.0.0
+summary: |
+  Command to authenticate a customer with their credentials.
+owners:
+  - customer-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /oauth/token
+  statusCodes: ['200', '400', '401']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`AuthenticateCustomer` is handled by the [[service|oauth-api]]. It verifies the supplied credentials against the [[container|user-directory]] and, on success, returns an access token and publishes a [[event|customer-authenticated]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/schema.json b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/schema.json
new file mode 100644
index 000000000..c39e22350
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/schema.json
@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AuthenticateCustomer",
+  "description": "Command to authenticate a customer with their credentials, and the token returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "The credentials to authenticate",
+      "type": "object",
+      "properties": {
+        "email": {
+          "type": "string",
+          "format": "email"
+        },
+        "password": {
+          "type": "string"
+        }
+      },
+      "required": ["email", "password"]
+    },
+    "response": {
+      "description": "The access token issued on a successful sign-in",
+      "type": "object",
+      "properties": {
+        "accessToken": {
+          "type": "string"
+        },
+        "tokenType": {
+          "type": "string",
+          "enum": ["Bearer"]
+        },
+        "expiresIn": {
+          "description": "Token lifetime in seconds",
+          "type": "integer"
+        }
+      },
+      "required": ["accessToken", "tokenType", "expiresIn"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/index.mdx
new file mode 100644
index 000000000..9da6701dd
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: customer-authenticated
+name: Customer Authenticated
+version: 1.0.0
+summary: |
+  Published when a customer has successfully authenticated.
+owners:
+  - customer-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CustomerAuthenticated` is published by the [[service|oauth-api]] whenever a customer successfully signs in. Other systems consume this event for auditing, session tracking, and security monitoring.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/schema.json b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/schema.json
new file mode 100644
index 000000000..d9d341b7a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/schema.json
@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CustomerAuthenticated",
+  "description": "Emitted when a customer successfully authenticates",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the customer authenticated",
+      "type": "string",
+      "format": "date-time"
+    },
+    "customerId": {
+      "description": "Unique identifier of the customer that authenticated",
+      "type": "string",
+      "format": "uuid"
+    },
+    "method": {
+      "description": "How the customer authenticated",
+      "type": "string",
+      "enum": ["PASSWORD", "SSO", "MFA"]
+    },
+    "ipAddress": {
+      "description": "IP address the sign-in came from",
+      "type": "string"
+    }
+  },
+  "required": ["eventId", "occurredAt", "customerId", "method"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/index.mdx
new file mode 100644
index 000000000..1fdb561e8
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/index.mdx
@@ -0,0 +1,59 @@
+---
+id: oauth-api
+version: 1.0.0
+name: OAuth API
+summary: |
+  OAuth-style authentication API for the Identity Provider. Verifies customer credentials and publishes an event when a customer successfully authenticates.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - customer-platform
+receives:
+  - id: authenticate-customer
+    version: 1.0.0
+sends:
+  - id: customer-authenticated
+    version: 1.0.0
+readsFrom:
+  - id: user-directory
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/oauth-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **OAuth API** is the authentication entry point for Acme Inc. It verifies credentials against the [[container|user-directory]] and, on a successful sign-in, publishes a [[event|customer-authenticated]] event so other systems can react.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} message`}
+    description="Authentication events published on successful sign-in"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Authentication requests handled by this service"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area             | Description                                                                         |
+| ---------------- | ----------------------------------------------------------------------------------- |
+| Authentication   | Handles [[command\|authenticate-customer]] and verifies credentials.                |
+| Event publishing | Emits [[event\|customer-authenticated]] on a successful sign-in.                    |
+| Credentials      | Reads from the [[container\|user-directory]] — the source of truth for credentials. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Customer/ubiquitous-language.mdx b/packages/create-eventcatalog/templates/default/domains/Customer/ubiquitous-language.mdx
new file mode 100644
index 000000000..46dfdc745
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Customer/ubiquitous-language.mdx
@@ -0,0 +1,48 @@
+---
+dictionary:
+  - id: Customer
+    name: Customer
+    summary: 'A person with an account at Acme Inc, identified by a unique customer id and email.'
+    description: |
+      The customer is the central concept of the Customer domain. Their profile is owned by the
+      Customer Management System, which is the source of truth for who a customer is. A customer has:
+
+      - A unique customer id and a unique email
+      - A display name
+      - An account status (ACTIVE, SUSPENDED or CLOSED)
+
+      A customer's profile data is kept deliberately separate from their credentials, which live in
+      the Identity Provider.
+    icon: User
+  - id: Identity
+    name: Identity
+    summary: 'The credentials and login information used to prove a customer is who they say they are.'
+    description: |
+      An identity is distinct from a customer profile. It lives in the Identity Provider's user
+      directory and holds the login email and a securely hashed credential. Keeping identity separate
+      from profile data isolates the most sensitive information.
+    icon: Fingerprint
+  - id: Authentication
+    name: Authentication
+    summary: 'Verifying that a sign-in attempt belongs to a real customer.'
+    description: |
+      Authentication is owned by the Identity Provider. It verifies credentials against the user
+      directory and, on success, issues an access token and publishes a CustomerAuthenticated event.
+    icon: LockKeyhole
+  - id: Credential
+    name: Credential
+    summary: 'A secret (such as a password) a customer uses to authenticate. Never stored in plain text.'
+    icon: KeyRound
+  - id: Account Status
+    name: Account Status
+    summary: 'Where a customer account sits: ACTIVE, SUSPENDED or CLOSED.'
+    description: |
+      - ACTIVE — the account is in good standing and can be used.
+      - SUSPENDED — temporarily blocked (e.g. for review).
+      - CLOSED — permanently deactivated.
+    icon: Workflow
+  - id: User Directory
+    name: User Directory
+    summary: 'The authoritative store of customer credentials and login identities.'
+    icon: Users
+---
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/entities/inventory-reservation/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/entities/inventory-reservation/index.mdx
new file mode 100644
index 000000000..90be074fc
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/entities/inventory-reservation/index.mdx
@@ -0,0 +1,39 @@
+---
+id: inventory-reservation
+name: Inventory Reservation
+version: 1.0.0
+identifier: reservationId
+aggregateRoot: true
+summary: Stock held for a checkout or order before fulfilment.
+owners:
+  - fulfilment-platform
+properties:
+  - name: reservationId
+    type: UUID
+    required: true
+    description: Unique reservation identifier.
+  - name: orderId
+    type: UUID
+    required: false
+    description: Order associated with the reservation once created.
+    references: order
+    relationType: reservedFor
+    referencesIdentifier: orderId
+  - name: productId
+    type: UUID
+    required: true
+    description: Product being reserved.
+    references: product
+    relationType: reserves
+    referencesIdentifier: productId
+  - name: expiresAt
+    type: datetime
+    required: true
+    description: Time the reservation expires if not committed.
+---
+
+## Overview
+
+Inventory Reservation is created during checkout by [[command|reserve-inventory]] and released if the saga fails.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/entities/shipment/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/entities/shipment/index.mdx
new file mode 100644
index 000000000..112fc465e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/entities/shipment/index.mdx
@@ -0,0 +1,36 @@
+---
+id: shipment
+name: Shipment
+version: 1.0.0
+identifier: shipmentId
+aggregateRoot: true
+summary: A carrier delivery for a packed customer order.
+owners:
+  - fulfilment-platform
+properties:
+  - name: shipmentId
+    type: UUID
+    required: true
+    description: Unique shipment identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order being shipped.
+    references: order
+    relationType: ships
+    referencesIdentifier: orderId
+  - name: carrierReference
+    type: string
+    required: false
+    description: External carrier tracking reference.
+  - name: status
+    type: string
+    required: true
+    description: Shipment delivery status.
+---
+
+## Overview
+
+Shipment is created by the Shipping System and updated from carrier events such as [[event|shipment-created]] and [[event|shipment-delivered]].
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/entities/stock-item/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/entities/stock-item/index.mdx
new file mode 100644
index 000000000..5fc776df4
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/entities/stock-item/index.mdx
@@ -0,0 +1,36 @@
+---
+id: stock-item
+name: Stock Item
+version: 1.0.0
+identifier: stockItemId
+aggregateRoot: true
+summary: The inventory record for a product variant at a location.
+owners:
+  - fulfilment-platform
+properties:
+  - name: stockItemId
+    type: UUID
+    required: true
+    description: Unique stock item identifier.
+  - name: productId
+    type: UUID
+    required: true
+    description: Product held in stock.
+    references: product
+    relationType: stocks
+    referencesIdentifier: productId
+  - name: locationId
+    type: string
+    required: true
+    description: Warehouse or fulfilment location.
+  - name: availableQuantity
+    type: integer
+    required: true
+    description: Quantity available to reserve.
+---
+
+## Overview
+
+Stock Item is the Inventory System's view of available stock for a product at a fulfilment location.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/entities/warehouse-pick/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/entities/warehouse-pick/index.mdx
new file mode 100644
index 000000000..8629f8403
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/entities/warehouse-pick/index.mdx
@@ -0,0 +1,35 @@
+---
+id: warehouse-pick
+name: Warehouse Pick
+version: 1.0.0
+identifier: pickId
+summary: A warehouse task to pick items for a completed order.
+owners:
+  - fulfilment-platform
+properties:
+  - name: pickId
+    type: UUID
+    required: true
+    description: Unique warehouse pick identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order being picked.
+    references: order
+    relationType: fulfils
+    referencesIdentifier: orderId
+  - name: assignedTo
+    type: string
+    required: false
+    description: Warehouse worker or automation lane assigned.
+  - name: status
+    type: string
+    required: true
+    description: Pick task status.
+---
+
+## Overview
+
+Warehouse Pick represents the operational task handled by the Warehouse System before an order can be packed and shipped.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/index.mdx
new file mode 100644
index 000000000..804091abb
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/index.mdx
@@ -0,0 +1,83 @@
+---
+id: fulfilment
+name: Fulfilment
+version: 1.0.0
+summary: |
+  The Fulfilment domain gets a confirmed order to the customer. It reserves stock, picks and packs orders in the warehouse, and hands them to carriers for delivery.
+owners:
+  - fulfilment-platform
+systems:
+  - id: inventory-system
+    version: 1.0.0
+  - id: warehouse-system
+    version: 1.0.0
+  - id: shipping-system
+    version: 1.0.0
+  - id: carrier
+    version: 1.0.0
+entities:
+  - id: stock-item
+    version: 1.0.0
+  - id: inventory-reservation
+    version: 1.0.0
+  - id: warehouse-pick
+    version: 1.0.0
+  - id: shipment
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Fulfilment** domain is responsible for the physical side of an order — making sure stock is available, picking and packing it, and shipping it to the customer. It owns three internal systems and integrates with external carriers:
+
+<Tiles>
+  <Tile
+    icon="ArchiveBoxIcon"
+    href="/docs/systems/inventory-system/1.0.0"
+    title="Inventory System"
+    description="Tracks and reserves stock for orders."
+  />
+  <Tile
+    icon="BuildingStorefrontIcon"
+    href="/docs/systems/warehouse-system/1.0.0"
+    title="Warehouse System"
+    description="Picks and packs orders ready for shipping."
+  />
+  <Tile
+    icon="TruckIcon"
+    href="/docs/systems/shipping-system/1.0.0"
+    title="Shipping System"
+    description="Hands packed orders to carriers for delivery."
+  />
+  <Tile
+    icon="GlobeAltIcon"
+    href="/docs/systems/carrier/1.0.0"
+    title="Carrier"
+    description="External carrier that delivers shipments to customers."
+  />
+</Tiles>
+
+### How the systems work together
+
+When an order is completed, the **Warehouse System** picks and packs it, having relied on the **Inventory System** to reserve stock earlier in checkout. Once packed, the **Shipping System** creates a shipment with an external **Carrier**, which delivers it to the customer and reports progress back.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The components that make up this domain.
+
+<NodeGraph />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/index.mdx
new file mode 100644
index 000000000..777ec1c9b
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/index.mdx
@@ -0,0 +1,52 @@
+---
+id: carrier
+name: Carrier
+version: 1.0.0
+scope: external
+summary: |
+  External carrier that delivers shipments to customers. It accepts shipment requests and reports delivery progress back.
+owners:
+  - fulfilment-platform
+services:
+  - id: carrier-shipping-api
+  - id: carrier-tracking-api
+relationships:
+  - id: shipping-system
+    label: delivers shipments for
+badges:
+  - content: External
+    backgroundColor: yellow
+    textColor: yellow
+    icon: GlobeAltIcon
+---
+
+## Overview
+
+The **Carrier** is the external delivery company Acme Inc uses to ship orders to customers. It is owned and operated by a third party — modelled here as an **external system** so the catalog shows how the [[system|shipping-system]] integrates with it.
+
+It receives [[command|create-shipment]] and reports progress back via [[event|shipment-created]], [[event|shipment-delivered]] and [[event|shipment-failed]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                         | Type    | Responsibility                                    |
+| --------------------------------- | ------- | ------------------------------------------------- |
+| [[service\|carrier-shipping-api]] | Service | Accepts shipment requests and dispatches parcels. |
+| [[service\|carrier-tracking-api]] | Service | Reports delivery progress back to Acme Inc.       |
+
+## Messages this system publishes
+
+- [[event\|shipment-created]] — a shipment has been created and dispatched.
+- [[event\|shipment-delivered]] — a shipment was delivered to the customer.
+- [[event\|shipment-failed]] — a shipment could not be delivered.
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierShippingAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierShippingAPI/index.mdx
new file mode 100644
index 000000000..ce51758fb
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierShippingAPI/index.mdx
@@ -0,0 +1,40 @@
+---
+id: carrier-shipping-api
+version: 1.0.0
+name: Shipping API
+summary: |
+  The carrier's API for creating shipments. Acme Inc's Shipping System calls it to dispatch packed orders.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: create-shipment
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/acme/carrier-integration'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Shipping API** is the carrier's external interface for creating shipments. The [[system|shipping-system]] sends [[command|create-shipment]], and the carrier dispatches the parcel and begins reporting progress through its [[service|carrier-tracking-api]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Shipment creation requests"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/index.mdx
new file mode 100644
index 000000000..70f90f5de
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: shipment-created
+name: Shipment Created
+version: 1.0.0
+summary: |
+  Published by the carrier when a shipment has been created and dispatched.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ShipmentCreated` is published by the carrier's [[service|carrier-tracking-api]] when a shipment has been created and dispatched. Acme Inc consumes it to give the customer a tracking number and expected delivery date.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/schema.json b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/schema.json
new file mode 100644
index 000000000..872fd4173
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/schema.json
@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ShipmentCreated",
+  "description": "Published when a shipment has been created and dispatched",
+  "type": "object",
+  "properties": {
+    "shipmentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "trackingNumber": { "type": "string" },
+    "carrier": { "type": "string" },
+    "estimatedDelivery": { "type": "string", "format": "date" },
+    "createdAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["shipmentId", "orderId", "trackingNumber", "createdAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/index.mdx
new file mode 100644
index 000000000..9ff7eb04f
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/index.mdx
@@ -0,0 +1,29 @@
+---
+id: shipment-delivered
+name: Shipment Delivered
+version: 1.0.0
+summary: |
+  Published by the carrier when a shipment has been delivered to the customer.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ShipmentDelivered` is published by the carrier's [[service|carrier-tracking-api]] when a shipment reaches the customer. This is the happy-path end of the fulfilment journey — Acme Inc consumes it to close out the order and prompt the customer for feedback.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/schema.json b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/schema.json
new file mode 100644
index 000000000..d8966a5d4
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/schema.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ShipmentDelivered",
+  "description": "Published when a shipment has been delivered to the customer",
+  "type": "object",
+  "properties": {
+    "shipmentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "deliveredAt": { "type": "string", "format": "date-time" },
+    "signedBy": { "type": "string", "description": "Name of the person who accepted delivery, if captured" }
+  },
+  "required": ["shipmentId", "orderId", "deliveredAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/index.mdx
new file mode 100644
index 000000000..a008409c5
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/index.mdx
@@ -0,0 +1,29 @@
+---
+id: shipment-failed
+name: Shipment Failed
+version: 1.0.0
+summary: |
+  Published by the carrier when a shipment could not be delivered.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ShipmentFailed` is published by the carrier's [[service|carrier-tracking-api]] when a shipment cannot be delivered — for example a failed delivery attempt or a lost parcel. Acme Inc consumes it to trigger a redelivery, refund, or customer follow-up.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/schema.json b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/schema.json
new file mode 100644
index 000000000..56691ec17
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/schema.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ShipmentFailed",
+  "description": "Published when a shipment could not be delivered",
+  "type": "object",
+  "properties": {
+    "shipmentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "reason": {
+      "type": "string",
+      "enum": ["FAILED_DELIVERY", "LOST", "DAMAGED", "RETURNED_TO_SENDER"]
+    },
+    "failedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["shipmentId", "orderId", "reason", "failedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/index.mdx
new file mode 100644
index 000000000..07b6edaf1
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/index.mdx
@@ -0,0 +1,44 @@
+---
+id: carrier-tracking-api
+version: 1.0.0
+name: Tracking API
+summary: |
+  The carrier's API for reporting delivery progress. It notifies Acme Inc when a shipment is created, delivered, or fails.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - fulfilment-platform
+sends:
+  - id: shipment-created
+    version: 1.0.0
+  - id: shipment-delivered
+    version: 1.0.0
+  - id: shipment-failed
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/acme/carrier-integration'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Tracking API** is how the carrier reports delivery progress back to Acme Inc. After a shipment is created via the [[service|carrier-shipping-api]], it emits [[event|shipment-created]], then [[event|shipment-delivered]] on success or [[event|shipment-failed]] if delivery cannot be completed.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Shipment lifecycle events"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/index.mdx
new file mode 100644
index 000000000..bd2a00b8b
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/index.mdx
@@ -0,0 +1,35 @@
+---
+id: inventory-database
+name: Inventory Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for stock levels and reservations.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for stock levels and reservations
+classification: internal
+retention: 3y
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Inventory Database** is the authoritative store for stock levels at Acme Inc. The [[service|inventory-service]] reads from and writes to it as stock is reserved and released.
+
+### What does it store?
+
+- **Stock** — one row per product: available quantity and reserved quantity.
+- **Reservations** — one row per reservation: id, order, items and status.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Inventory Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/schema.sql b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/schema.sql
new file mode 100644
index 000000000..ff2a97fbb
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/schema.sql
@@ -0,0 +1,26 @@
+-- Inventory Database — system of record for stock levels and reservations
+
+CREATE TABLE stock (
+    product_id  UUID PRIMARY KEY,
+    available   INTEGER NOT NULL DEFAULT 0 CHECK (available >= 0),
+    reserved    INTEGER NOT NULL DEFAULT 0 CHECK (reserved >= 0),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE reservations (
+    reservation_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    order_id       UUID,
+    cart_id        UUID,
+    status         TEXT NOT NULL DEFAULT 'HELD'
+                     CHECK (status IN ('HELD', 'RELEASED', 'CONSUMED')),
+    created_at     TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE reservation_items (
+    reservation_id UUID NOT NULL REFERENCES reservations (reservation_id) ON DELETE CASCADE,
+    product_id     UUID NOT NULL,
+    quantity       INTEGER NOT NULL CHECK (quantity > 0),
+    PRIMARY KEY (reservation_id, product_id)
+);
+
+CREATE INDEX idx_reservations_order ON reservations (order_id);
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/index.mdx
new file mode 100644
index 000000000..9886a2a46
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/index.mdx
@@ -0,0 +1,49 @@
+---
+id: inventory-system
+name: Inventory System
+version: 1.0.0
+summary: |
+  Internal system that tracks stock and reserves it for orders. It is the source of truth for available inventory and confirms whether stock can be reserved.
+owners:
+  - fulfilment-platform
+services:
+  - id: inventory-service
+containers:
+  - id: inventory-database
+relationships:
+  - id: warehouse-system
+    label: provides stock for
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Inventory System** owns stock levels at Acme Inc. During checkout it receives [[command|reserve-inventory]] and confirms whether stock is available — replying with [[event|inventory-reserved]] or [[event|inventory-unavailable]]. It also handles [[command|release-inventory]] (when a reservation is no longer needed) and serves [[query|get-stock-level]] lookups from the [[container|inventory-database]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                         | Type       | Responsibility                                                                           |
+| --------------------------------- | ---------- | ---------------------------------------------------------------------------------------- |
+| [[service\|inventory-service]]    | Service    | Reserves and releases stock, serves stock-level queries, and publishes inventory events. |
+| [[container\|inventory-database]] | Data store | PostgreSQL system of record for stock levels and reservations.                           |
+
+## Messages this system publishes
+
+- [[event\|inventory-reserved]] — stock was successfully reserved for an order.
+- [[event\|inventory-unavailable]] — stock could not be reserved.
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/index.mdx
new file mode 100644
index 000000000..38112a099
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/index.mdx
@@ -0,0 +1,32 @@
+---
+id: release-inventory
+name: Release Inventory
+version: 1.0.0
+summary: |
+  Command to release a previously held inventory reservation.
+owners:
+  - fulfilment-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /reservations/{reservationId}/release
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReleaseInventory` is handled by the [[service|inventory-service]]. It releases a reservation that is no longer needed — for example when checkout fails after stock was reserved, or an order is cancelled.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/schema.json b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/schema.json
new file mode 100644
index 000000000..6cdf190e5
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/schema.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReleaseInventory",
+  "description": "Command to release a previously held inventory reservation",
+  "type": "object",
+  "properties": {
+    "reservationId": { "type": "string", "format": "uuid" },
+    "reason": {
+      "type": "string",
+      "enum": ["CHECKOUT_FAILED", "ORDER_CANCELLED", "EXPIRED"]
+    }
+  },
+  "required": ["reservationId"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/index.mdx
new file mode 100644
index 000000000..eb43f0380
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/index.mdx
@@ -0,0 +1,29 @@
+---
+id: inventory-reserved
+name: Inventory Reserved
+version: 1.0.0
+summary: |
+  Published when stock has been successfully reserved for an order.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`InventoryReserved` is published by the [[service|inventory-service]] when stock for an order has been successfully reserved. The Ordering domain's checkout saga relies on this to continue placing the order.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/schema.json b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/schema.json
new file mode 100644
index 000000000..c659aa8ad
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "InventoryReserved",
+  "description": "Published when stock has been successfully reserved for an order",
+  "type": "object",
+  "properties": {
+    "reservationId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "cartId": { "type": "string", "format": "uuid" },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": { "type": "string", "format": "uuid" },
+          "quantity": { "type": "integer", "minimum": 1 }
+        },
+        "required": ["productId", "quantity"]
+      }
+    },
+    "reservedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reservationId", "items", "reservedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/index.mdx
new file mode 100644
index 000000000..a9adad0c0
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/index.mdx
@@ -0,0 +1,29 @@
+---
+id: inventory-unavailable
+name: Inventory Unavailable
+version: 1.0.0
+summary: |
+  Published when stock could not be reserved for an order.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`InventoryUnavailable` is published by the [[service|inventory-service]] when stock for an order cannot be reserved. The Ordering domain's checkout saga uses it to fail checkout and cancel the order.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/schema.json b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/schema.json
new file mode 100644
index 000000000..f57559daf
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryUnavailable/schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "InventoryUnavailable",
+  "description": "Published when stock could not be reserved for an order",
+  "type": "object",
+  "properties": {
+    "orderId": { "type": "string", "format": "uuid" },
+    "cartId": { "type": "string", "format": "uuid" },
+    "unavailableItems": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": { "type": "string", "format": "uuid" },
+          "requested": { "type": "integer", "minimum": 1 },
+          "available": { "type": "integer", "minimum": 0 }
+        },
+        "required": ["productId", "requested", "available"]
+      }
+    },
+    "checkedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["unavailableItems", "checkedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/index.mdx
new file mode 100644
index 000000000..18c3a2ad3
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/index.mdx
@@ -0,0 +1,67 @@
+---
+id: inventory-service
+version: 1.0.0
+name: Inventory Service
+summary: |
+  The system of record for stock. Reserves and releases inventory, serves stock-level queries, and publishes events when stock is reserved or unavailable.
+styles:
+  icon: /icons/languages/java.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: reserve-inventory
+    version: 1.0.0
+  - id: release-inventory
+    version: 1.0.0
+  - id: get-stock-level
+    version: 1.0.0
+sends:
+  - id: inventory-reserved
+    version: 1.0.0
+  - id: inventory-unavailable
+    version: 1.0.0
+writesTo:
+  - id: inventory-database
+readsFrom:
+  - id: inventory-database
+repository:
+  language: Java
+  url: 'https://github.com/acme/inventory-service'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Inventory Service** is the heart of the Inventory System. It receives [[command|reserve-inventory]] during checkout and replies with [[event|inventory-reserved]] or [[event|inventory-unavailable]]. It also handles [[command|release-inventory]] and serves [[query|get-stock-level]] reads, all backed by the [[container|inventory-database]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Inventory outcomes"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Inventory commands and queries"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area             | Description                                                                   |
+| ---------------- | ----------------------------------------------------------------------------- |
+| Reservations     | Handles [[command\|reserve-inventory]] and [[command\|release-inventory]].    |
+| Lookups          | Serves [[query\|get-stock-level]] from the [[container\|inventory-database]]. |
+| Event publishing | Emits [[event\|inventory-reserved]] and [[event\|inventory-unavailable]].     |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/index.mdx
new file mode 100644
index 000000000..67c740a7a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/index.mdx
@@ -0,0 +1,32 @@
+---
+id: get-stock-level
+name: Get Stock Level
+version: 1.0.0
+summary: |
+  Query to fetch the current available stock level for a product.
+owners:
+  - fulfilment-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /stock/{productId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetStockLevel` is handled by the [[service|inventory-service]]. It returns the current available stock for a product, read directly from the [[container|inventory-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/schema.json b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/schema.json
new file mode 100644
index 000000000..3e947c58e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/schema.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetStockLevel",
+  "description": "Query to fetch the current available stock level for a product, and the level returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "type": "object",
+      "properties": {
+        "productId": { "type": "string", "format": "uuid" }
+      },
+      "required": ["productId"]
+    },
+    "response": {
+      "type": "object",
+      "properties": {
+        "productId": { "type": "string", "format": "uuid" },
+        "available": { "type": "integer", "minimum": 0 },
+        "reserved": { "type": "integer", "minimum": 0 }
+      },
+      "required": ["productId", "available"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/index.mdx
new file mode 100644
index 000000000..ec0f21bf2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/index.mdx
@@ -0,0 +1,47 @@
+---
+id: shipping-system
+name: Shipping System
+version: 1.0.0
+summary: |
+  Internal system that hands packed orders to carriers. It reacts to ready-for-shipping orders and creates shipments with an external carrier.
+owners:
+  - fulfilment-platform
+services:
+  - id: shipping-api
+  - id: carrier-adapter
+relationships:
+  - id: carrier
+    label: creates shipments with
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Shipping System** connects Acme Inc to its carriers. When the [[system|warehouse-system]] publishes [[event|order-ready-for-shipping]], the [[service|shipping-api]] selects a carrier and the [[service|carrier-adapter]] sends a [[command|create-shipment]] to the external [[system|carrier]] to dispatch the parcel.
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                    | Type    | Responsibility                                                  |
+| ---------------------------- | ------- | --------------------------------------------------------------- |
+| [[service\|shipping-api]]    | Service | Receives ready-for-shipping orders and selects a carrier.       |
+| [[service\|carrier-adapter]] | Service | Translates and sends shipment requests to the external carrier. |
+
+## Messages this system sends
+
+- [[command\|create-shipment]] — create a shipment with the carrier.
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/index.mdx
new file mode 100644
index 000000000..ec50cdffd
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/index.mdx
@@ -0,0 +1,32 @@
+---
+id: create-shipment
+name: Create Shipment
+version: 1.0.0
+summary: |
+  Command to create a shipment with a carrier for a packed order.
+owners:
+  - fulfilment-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /shipments
+  statusCodes: ['201', '400', '422']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CreateShipment` is sent by the [[service|carrier-adapter]] to the external [[system|carrier]] to dispatch a packed order. The carrier responds asynchronously with [[event|shipment-created]] and later [[event|shipment-delivered]] or [[event|shipment-failed]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/schema.json b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/schema.json
new file mode 100644
index 000000000..7e111d8dd
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/schema.json
@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CreateShipment",
+  "description": "Command to create a shipment with a carrier for a packed order",
+  "type": "object",
+  "properties": {
+    "orderId": { "type": "string", "format": "uuid" },
+    "carrier": { "type": "string", "description": "The carrier to ship with" },
+    "service": {
+      "type": "string",
+      "enum": ["STANDARD", "EXPRESS", "NEXT_DAY"]
+    },
+    "parcelCount": { "type": "integer", "minimum": 1 },
+    "destination": {
+      "type": "object",
+      "properties": {
+        "line1": { "type": "string" },
+        "city": { "type": "string" },
+        "postcode": { "type": "string" },
+        "country": { "type": "string", "pattern": "^[A-Z]{2}$" }
+      },
+      "required": ["line1", "city", "postcode", "country"]
+    }
+  },
+  "required": ["orderId", "destination"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/index.mdx
new file mode 100644
index 000000000..008daca1e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/index.mdx
@@ -0,0 +1,40 @@
+---
+id: carrier-adapter
+version: 1.0.0
+name: Carrier Adapter
+summary: |
+  Translates Acme Inc shipment requests into the external carrier's format and sends them to create a shipment.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - fulfilment-platform
+sends:
+  - id: create-shipment
+    version: 1.0.0
+repository:
+  language: Go
+  url: 'https://github.com/acme/carrier-adapter'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Carrier Adapter** is the anti-corruption layer between Acme Inc and its carriers. It takes a shipment request from the [[service|shipping-api]], maps it to the external [[system|carrier]]'s API, and sends a [[command|create-shipment]] to dispatch the parcel.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} message`}
+    description="The create-shipment command"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/services/ShippingAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/services/ShippingAPI/index.mdx
new file mode 100644
index 000000000..127cb4f86
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/shipping-system/services/ShippingAPI/index.mdx
@@ -0,0 +1,40 @@
+---
+id: shipping-api
+version: 1.0.0
+name: Shipping API
+summary: |
+  Receives ready-for-shipping orders, selects a carrier, and kicks off shipment creation.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: order-ready-for-shipping
+    version: 1.0.0
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/shipping-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Shipping API** is the entry point to the Shipping System. It consumes [[event|order-ready-for-shipping]] from the [[system|warehouse-system]], selects an appropriate carrier, and hands off to the [[service|carrier-adapter]] to create the shipment.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Ready-for-shipping orders"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/containers/warehouse-database/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/containers/warehouse-database/index.mdx
new file mode 100644
index 000000000..8386572f5
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/containers/warehouse-database/index.mdx
@@ -0,0 +1,35 @@
+---
+id: warehouse-database
+name: Warehouse Database
+version: 1.0.0
+summary: PostgreSQL database that stores picking jobs and their status.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for picking and packing jobs
+classification: internal
+retention: 1y
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Warehouse Database** stores the picking and packing jobs for the warehouse. The [[service|warehouse-service]] creates jobs and the [[service|picking-worker]] updates them as orders are picked.
+
+### What does it store?
+
+- **Picking Jobs** — one row per order being fulfilled: order, status and timestamps.
+- **Picking Job Items** — the items to pick for each job.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Warehouse Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/containers/warehouse-database/schema.sql b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/containers/warehouse-database/schema.sql
new file mode 100644
index 000000000..742b44d30
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/containers/warehouse-database/schema.sql
@@ -0,0 +1,21 @@
+-- Warehouse Database — picking and packing jobs
+
+CREATE TABLE picking_jobs (
+    job_id      UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    order_id    UUID NOT NULL,
+    status      TEXT NOT NULL DEFAULT 'CREATED'
+                  CHECK (status IN ('CREATED', 'PICKING', 'PACKED')),
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE picking_job_items (
+    job_id      UUID NOT NULL REFERENCES picking_jobs (job_id) ON DELETE CASCADE,
+    product_id  UUID NOT NULL,
+    quantity    INTEGER NOT NULL CHECK (quantity > 0),
+    picked      BOOLEAN NOT NULL DEFAULT false,
+    PRIMARY KEY (job_id, product_id)
+);
+
+CREATE INDEX idx_picking_jobs_order  ON picking_jobs (order_id);
+CREATE INDEX idx_picking_jobs_status ON picking_jobs (status);
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/index.mdx
new file mode 100644
index 000000000..77b29ce3b
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/index.mdx
@@ -0,0 +1,53 @@
+---
+id: warehouse-system
+name: Warehouse System
+version: 1.0.0
+summary: |
+  Internal system that picks and packs orders in the warehouse. It reacts to completed orders, organises picking, and signals when an order is packed and ready to ship.
+owners:
+  - fulfilment-platform
+services:
+  - id: warehouse-service
+  - id: picking-worker
+containers:
+  - id: warehouse-database
+relationships:
+  - id: shipping-system
+    label: hands packed orders to
+  - id: inventory-system
+    label: consumes reserved stock from
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Warehouse System** turns a completed order into a packed parcel. When the Ordering domain publishes [[event|order-completed]], the [[service|warehouse-service]] creates a picking job, the [[service|picking-worker]] works through it, and the system publishes [[event|order-packed]] and then [[event|order-ready-for-shipping]] for the [[system|shipping-system]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                         | Type       | Responsibility                                                  |
+| --------------------------------- | ---------- | --------------------------------------------------------------- |
+| [[service\|warehouse-service]]    | Service    | Receives completed orders and orchestrates picking and packing. |
+| [[service\|picking-worker]]       | Service    | Works through picking jobs on the warehouse floor.              |
+| [[container\|warehouse-database]] | Data store | PostgreSQL store of picking jobs and their status.              |
+
+## Messages this system publishes
+
+- [[event\|order-packed]] — an order has been picked and packed.
+- [[event\|order-ready-for-shipping]] — a packed order is ready to be shipped.
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/index.mdx
new file mode 100644
index 000000000..5036db236
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/index.mdx
@@ -0,0 +1,29 @@
+---
+id: order-packed
+name: Order Packed
+version: 1.0.0
+summary: |
+  Published when an order has been picked and packed in the warehouse.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderPacked` is published by the [[service|picking-worker]] when an order has been fully picked and packed. The [[service|warehouse-service]] consumes it to mark the order ready and publish [[event|order-ready-for-shipping]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/schema.json b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/schema.json
new file mode 100644
index 000000000..f588ac7f7
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/schema.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderPacked",
+  "description": "Published when an order has been picked and packed in the warehouse",
+  "type": "object",
+  "properties": {
+    "orderId": { "type": "string", "format": "uuid" },
+    "pickingJobId": { "type": "string", "format": "uuid" },
+    "parcelCount": { "type": "integer", "minimum": 1 },
+    "packedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["orderId", "packedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/index.mdx
new file mode 100644
index 000000000..c6f39ffb0
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/index.mdx
@@ -0,0 +1,44 @@
+---
+id: picking-worker
+version: 1.0.0
+name: Picking Worker
+summary: |
+  Works through picking jobs on the warehouse floor and signals when an order has been picked and packed.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - fulfilment-platform
+sends:
+  - id: order-packed
+    version: 1.0.0
+readsFrom:
+  - id: warehouse-database
+writesTo:
+  - id: warehouse-database
+repository:
+  language: Go
+  url: 'https://github.com/acme/picking-worker'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Picking Worker** processes picking jobs created by the [[service|warehouse-service]]. As warehouse staff pick and pack each order, the worker updates the job in the [[container|warehouse-database]] and publishes [[event|order-packed]] when the order is complete.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} message`}
+    description="The order-packed event"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/index.mdx
new file mode 100644
index 000000000..58a86231c
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/index.mdx
@@ -0,0 +1,29 @@
+---
+id: order-ready-for-shipping
+name: Order Ready For Shipping
+version: 1.0.0
+summary: |
+  Published when a packed order is ready to be handed to a carrier for shipping.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderReadyForShipping` is published by the [[service|warehouse-service]] once an order has been packed. The [[system|shipping-system]] consumes it to create a shipment with a carrier.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/schema.json b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/schema.json
new file mode 100644
index 000000000..f903e40aa
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/schema.json
@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderReadyForShipping",
+  "description": "Published when a packed order is ready to be handed to a carrier",
+  "type": "object",
+  "properties": {
+    "orderId": { "type": "string", "format": "uuid" },
+    "customerId": { "type": "string", "format": "uuid" },
+    "parcelCount": { "type": "integer", "minimum": 1 },
+    "shippingAddress": {
+      "type": "object",
+      "properties": {
+        "line1": { "type": "string" },
+        "city": { "type": "string" },
+        "postcode": { "type": "string" },
+        "country": { "type": "string", "pattern": "^[A-Z]{2}$" }
+      },
+      "required": ["line1", "city", "postcode", "country"]
+    },
+    "readyAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["orderId", "shippingAddress", "readyAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/index.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/index.mdx
new file mode 100644
index 000000000..f685de959
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/index.mdx
@@ -0,0 +1,53 @@
+---
+id: warehouse-service
+version: 1.0.0
+name: Warehouse Service
+summary: |
+  Orchestrates picking and packing in the warehouse. It reacts to completed orders, creates picking jobs, and signals when an order is ready to ship.
+styles:
+  icon: /icons/languages/java.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: order-completed
+    version: 1.0.0
+sends:
+  - id: order-ready-for-shipping
+    version: 1.0.0
+writesTo:
+  - id: warehouse-database
+readsFrom:
+  - id: warehouse-database
+repository:
+  language: Java
+  url: 'https://github.com/acme/warehouse-service'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Warehouse Service** runs warehousing. When the Ordering domain publishes [[event|order-completed]], it creates a picking job in the [[container|warehouse-database]] for the [[service|picking-worker]] to work through. Once the order is packed it publishes [[event|order-ready-for-shipping]] for the [[system|shipping-system]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} message`}
+    description="Ready-for-shipping signal"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Completed orders to fulfil"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Fulfilment/ubiquitous-language.mdx b/packages/create-eventcatalog/templates/default/domains/Fulfilment/ubiquitous-language.mdx
new file mode 100644
index 000000000..ebd22992b
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Fulfilment/ubiquitous-language.mdx
@@ -0,0 +1,44 @@
+---
+dictionary:
+  - id: Fulfilment
+    name: Fulfilment
+    summary: 'Everything that gets a confirmed order physically to the customer — stock, packing and shipping.'
+    icon: PackageCheck
+  - id: Stock
+    name: Stock
+    summary: 'The quantity of a product physically available to sell.'
+    description: |
+      Stock is owned by the Inventory System. Each product has an available quantity and a reserved
+      quantity. Stock is the source of truth for whether an order can be fulfilled.
+    icon: Boxes
+  - id: Reservation
+    name: Reservation
+    summary: 'A temporary hold on stock for a specific order, taken during checkout.'
+    description: |
+      A reservation guarantees stock is set aside for an order while payment is taken. It is held,
+      then either consumed when the order ships or released if checkout fails.
+    icon: BookmarkCheck
+  - id: Picking
+    name: Picking
+    summary: "Collecting an order's items from the warehouse shelves."
+    icon: Hand
+  - id: Packing
+    name: Packing
+    summary: 'Boxing up a picked order into one or more parcels ready for shipping.'
+    icon: Package
+  - id: Shipment
+    name: Shipment
+    summary: 'A packed order handed to a carrier for delivery, tracked from dispatch to delivery.'
+    description: |
+      A shipment is created with an external carrier once an order is packed. Its lifecycle —
+      created, delivered or failed — is reported back by the carrier.
+    icon: Truck
+  - id: Carrier
+    name: Carrier
+    summary: 'The external delivery company that transports shipments to customers.'
+    icon: Globe
+  - id: Tracking Number
+    name: Tracking Number
+    summary: "A code from the carrier that lets the customer follow a shipment's progress."
+    icon: ScanBarcode
+---
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/entities/checkout-session/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/entities/checkout-session/index.mdx
new file mode 100644
index 000000000..b247c6c8a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/entities/checkout-session/index.mdx
@@ -0,0 +1,36 @@
+---
+id: checkout-session
+name: Checkout Session
+version: 1.0.0
+identifier: checkoutSessionId
+aggregateRoot: true
+summary: The orchestration state for turning a checked-out cart into an order.
+owners:
+  - ordering-platform
+properties:
+  - name: checkoutSessionId
+    type: UUID
+    required: true
+    description: Unique checkout session identifier.
+  - name: cartId
+    type: UUID
+    required: true
+    description: Cart being checked out.
+    references: cart
+    relationType: startsFrom
+    referencesIdentifier: cartId
+  - name: status
+    type: string
+    required: true
+    description: Current checkout state.
+  - name: startedAt
+    type: datetime
+    required: true
+    description: Time checkout orchestration started.
+---
+
+## Overview
+
+Checkout Session tracks the saga managed by [[service|checkout-orchestrator]] across inventory reservation, payment authorization and order creation.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/entities/order-line/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/entities/order-line/index.mdx
new file mode 100644
index 000000000..f0159af8d
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/entities/order-line/index.mdx
@@ -0,0 +1,38 @@
+---
+id: order-line
+name: Order Line
+version: 1.0.0
+identifier: orderLineId
+summary: A purchased product and quantity within an order.
+owners:
+  - ordering-platform
+properties:
+  - name: orderLineId
+    type: UUID
+    required: true
+    description: Unique order line identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order this line belongs to.
+    references: order
+    relationType: belongsTo
+    referencesIdentifier: orderId
+  - name: productId
+    type: UUID
+    required: true
+    description: Product purchased.
+    references: product
+    relationType: references
+    referencesIdentifier: productId
+  - name: quantity
+    type: integer
+    required: true
+    description: Quantity purchased.
+---
+
+## Overview
+
+Order Line snapshots the products bought at checkout. It should not replace the Catalog domain's authoritative product data.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/entities/order-status-history/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/entities/order-status-history/index.mdx
new file mode 100644
index 000000000..384955a68
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/entities/order-status-history/index.mdx
@@ -0,0 +1,35 @@
+---
+id: order-status-history
+name: Order Status History
+version: 1.0.0
+identifier: orderStatusHistoryId
+summary: Audit history of order lifecycle state changes.
+owners:
+  - ordering-platform
+properties:
+  - name: orderStatusHistoryId
+    type: UUID
+    required: true
+    description: Unique status history record.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order whose status changed.
+    references: order
+    relationType: belongsTo
+    referencesIdentifier: orderId
+  - name: status
+    type: string
+    required: true
+    description: New order status.
+  - name: changedAt
+    type: datetime
+    required: true
+    description: Time the status changed.
+---
+
+## Overview
+
+Order Status History provides an audit trail for customer support, fulfilment exceptions and order lifecycle debugging.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/entities/order/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/entities/order/index.mdx
new file mode 100644
index 000000000..685a479ca
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/entities/order/index.mdx
@@ -0,0 +1,36 @@
+---
+id: order
+name: Order
+version: 1.0.0
+identifier: orderId
+aggregateRoot: true
+summary: The durable customer order created after successful checkout.
+owners:
+  - ordering-platform
+properties:
+  - name: orderId
+    type: UUID
+    required: true
+    description: Unique order identifier.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer who placed the order.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: status
+    type: string
+    required: true
+    description: Current order lifecycle state.
+  - name: totalAmount
+    type: decimal
+    required: true
+    description: Total order value at creation.
+---
+
+## Overview
+
+Order is the main aggregate in [[system|order-management-system]]. It emits order lifecycle events used by Fulfilment and support workflows.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/flows/PlaceAnOrder/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/flows/PlaceAnOrder/index.mdx
new file mode 100644
index 000000000..97eaca900
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/flows/PlaceAnOrder/index.mdx
@@ -0,0 +1,158 @@
+---
+id: place-an-order
+name: Place an Order
+version: 1.0.0
+summary: |
+  The end-to-end journey from a customer checking out their cart to a confirmed order — spanning the Shopping and Ordering domains, including the checkout saga and its failure path.
+owners:
+  - ordering-platform
+steps:
+  - id: shopper_checks_out
+    title: Shopper checks out
+    actor:
+      name: Shopper
+      summary: The customer confirms their cart and starts checkout.
+    next_step:
+      id: checkout_cart_command
+      label: Check out cart
+
+  - id: checkout_cart_command
+    title: Checkout Cart
+    message:
+      id: checkout-cart
+      version: 1.0.0
+    next_step:
+      id: cart_api
+      label: Price and finalise cart
+
+  - id: cart_api
+    title: Cart API
+    service:
+      id: cart-api
+      version: 1.0.0
+    next_step:
+      id: cart_checked_out
+      label: Publish checkout
+
+  - id: cart_checked_out
+    title: Cart Checked Out
+    message:
+      id: cart-checked-out
+      version: 1.0.0
+    next_step:
+      id: checkout_api
+      label: Start checkout flow
+
+  - id: checkout_api
+    title: Checkout API
+    service:
+      id: checkout-api
+      version: 1.0.0
+    next_step:
+      id: checkout_orchestrator
+      label: Run checkout saga
+
+  - id: checkout_orchestrator
+    title: Checkout Orchestrator
+    service:
+      id: checkout-orchestrator
+      version: 1.0.0
+    next_steps:
+      - id: reserve_inventory
+        label: Reserve inventory
+      - id: authorize_payment
+        label: Authorize payment
+
+  - id: reserve_inventory
+    title: Reserve Inventory
+    message:
+      id: reserve-inventory
+      version: 1.0.0
+    next_step:
+      id: authorize_payment
+      label: Inventory held
+
+  - id: authorize_payment
+    title: Authorize Payment
+    message:
+      id: authorize-payment
+      version: 1.0.0
+    next_steps:
+      - id: create_order
+        label: Payment authorized
+      - id: checkout_failed
+        label: Authorization declined
+
+  - id: create_order
+    title: Create Order
+    message:
+      id: create-order
+      version: 1.0.0
+    next_step:
+      id: order_service
+      label: Persist order
+
+  - id: order_service
+    title: Order Service
+    service:
+      id: order-service
+      version: 1.0.0
+    next_step:
+      id: order_created
+      label: Publish order created
+
+  - id: order_created
+    title: Order Created
+    message:
+      id: order-created
+      version: 1.0.0
+    next_step:
+      id: order_confirmed
+      label: Confirm to customer
+
+  - id: order_confirmed
+    title: Order confirmed
+    custom:
+      title: Order confirmed
+      color: green
+      icon: CheckCircleIcon
+      type: Outcome
+      summary: The customer's order is placed and confirmed. Fulfilment begins.
+      properties:
+        happy_path: 'true'
+
+  - id: checkout_failed
+    title: Checkout failed
+    custom:
+      title: Checkout failed
+      color: red
+      icon: ExclamationTriangleIcon
+      type: Exception
+      summary: A checkout step failed (e.g. payment declined). The orchestrator compensates earlier steps and cancels the order.
+      properties:
+        common_causes: 'payment declined, out of stock'
+        next_action: 'release reservation, void authorization, cancel order'
+    next_step:
+      id: order_cancelled
+      label: Cancel order
+
+  - id: order_cancelled
+    title: Order Cancelled
+    message:
+      id: order-cancelled
+      version: 1.0.0
+---
+
+## Overview
+
+**Place an Order** is the headline business flow at Acme Inc. It begins in the [[domain|shopping]] domain, when a shopper checks out their cart, and finishes in the [[domain|ordering]] domain, with a confirmed order — or a compensated, cancelled one if a step fails.
+
+<NodeGraph />
+
+## How it works
+
+1. The shopper checks out — the [[service|cart-api]] prices the cart and publishes [[event|cart-checked-out]].
+2. The [[service|checkout-api]] picks this up and hands it to the [[service|checkout-orchestrator]].
+3. The orchestrator runs the saga: [[command|reserve-inventory]] then [[command|authorize-payment]].
+4. On success it sends [[command|create-order]] to the [[service|order-service]], which publishes [[event|order-created]].
+5. If any step fails, the orchestrator compensates the earlier steps and the order is cancelled via [[event|order-cancelled]].
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/index.mdx
new file mode 100644
index 000000000..3c7418b90
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/index.mdx
@@ -0,0 +1,70 @@
+---
+id: ordering
+name: Ordering
+version: 1.0.0
+summary: |
+  The Ordering domain turns a checked-out cart into a confirmed order. It orchestrates checkout — reserving inventory, authorizing payment and creating the order — and owns the lifecycle of every order.
+owners:
+  - ordering-platform
+systems:
+  - id: checkout-system
+    version: 1.0.0
+  - id: order-management-system
+    version: 1.0.0
+flows:
+  - id: place-an-order
+    version: 1.0.0
+entities:
+  - id: checkout-session
+    version: 1.0.0
+  - id: order
+    version: 1.0.0
+  - id: order-line
+    version: 1.0.0
+  - id: order-status-history
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Ordering** domain is responsible for everything that happens once a customer commits to buy — from the moment their cart is checked out to a confirmed, fulfilled order. It is split into two systems:
+
+<Tiles>
+  <Tile
+    icon="CreditCardIcon"
+    href="/docs/systems/checkout-system/1.0.0"
+    title="Checkout System"
+    description="Orchestrates checkout — reserves inventory, authorizes payment and creates the order."
+  />
+  <Tile
+    icon="ClipboardDocumentListIcon"
+    href="/docs/systems/order-management-system/1.0.0"
+    title="Order Management System"
+    description="System of record for orders and their lifecycle."
+  />
+</Tiles>
+
+### How the systems work together
+
+When the [[domain|shopping]] domain checks out a cart, the **Checkout System** takes over. It orchestrates the steps needed to place an order — reserving inventory, authorizing payment, and finally asking the **Order Management System** to create the order. The Order Management System then owns that order for the rest of its life, publishing events as it is created, completed or cancelled.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The components that make up this domain.
+
+<NodeGraph />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/flows/CheckoutSaga/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/flows/CheckoutSaga/index.mdx
new file mode 100644
index 000000000..90fa12e5d
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/flows/CheckoutSaga/index.mdx
@@ -0,0 +1,101 @@
+---
+id: checkout-saga
+name: Checkout Saga
+version: 1.0.0
+summary: |
+  How the Checkout Orchestrator turns a checked-out cart into an order — reserving inventory, authorizing payment and creating the order, with compensation when a step fails.
+owners:
+  - ordering-platform
+steps:
+  - id: cart_checked_out
+    title: Cart Checked Out
+    message:
+      id: cart-checked-out
+      version: 1.0.0
+    next_step:
+      id: checkout_api
+      label: Receive checkout
+
+  - id: checkout_api
+    title: Checkout API
+    service:
+      id: checkout-api
+      version: 1.0.0
+    next_step:
+      id: orchestrator
+      label: Start saga
+
+  - id: orchestrator
+    title: Checkout Orchestrator
+    service:
+      id: checkout-orchestrator
+      version: 1.0.0
+    next_step:
+      id: reserve_inventory
+      label: Step 1 — reserve inventory
+
+  - id: reserve_inventory
+    title: Reserve Inventory
+    message:
+      id: reserve-inventory
+      version: 1.0.0
+    next_steps:
+      - id: authorize_payment
+        label: Reserved
+      - id: compensate_release
+        label: Out of stock
+
+  - id: authorize_payment
+    title: Authorize Payment
+    message:
+      id: authorize-payment
+      version: 1.0.0
+    next_steps:
+      - id: create_order
+        label: Authorized
+      - id: compensate_release
+        label: Declined
+
+  - id: create_order
+    title: Create Order
+    message:
+      id: create-order
+      version: 1.0.0
+    next_step:
+      id: saga_complete
+      label: Order created
+
+  - id: saga_complete
+    title: Saga complete
+    custom:
+      title: Saga complete
+      color: green
+      icon: CheckCircleIcon
+      type: Outcome
+      summary: Inventory reserved, payment authorized and order created. The saga succeeds.
+
+  - id: compensate_release
+    title: Compensate
+    custom:
+      title: Compensate and abort
+      color: red
+      icon: ArrowUturnLeftIcon
+      type: Compensation
+      summary: A step failed. The orchestrator releases any reservation and voids any authorization, then aborts the saga without creating an order.
+      properties:
+        actions: 'release reservation, void authorization'
+---
+
+## Overview
+
+The **Checkout Saga** is the heart of the [[system|checkout-system]]. It coordinates the steps that turn a checked-out cart into a confirmed order. Each step has a compensating action so a failure never leaves the customer in an inconsistent state.
+
+<NodeGraph />
+
+## Steps
+
+1. **Reserve inventory** — [[command|reserve-inventory]] holds stock for the cart's items.
+2. **Authorize payment** — [[command|authorize-payment]] places a hold on the order total.
+3. **Create order** — [[command|create-order]] persists the order in the [[system|order-management-system]].
+
+If reservation or authorization fails, the orchestrator **compensates** — releasing the reservation and voiding the authorization — and aborts without creating an order.
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/index.mdx
new file mode 100644
index 000000000..68db4894e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/index.mdx
@@ -0,0 +1,57 @@
+---
+id: checkout-system
+name: Checkout System
+version: 1.0.0
+summary: |
+  Internal system that orchestrates checkout. When a cart is checked out it reserves inventory, authorizes payment, and asks the Order Management System to create the order.
+owners:
+  - ordering-platform
+services:
+  - id: checkout-api
+  - id: checkout-orchestrator
+flows:
+  - id: checkout-saga
+    version: 1.0.0
+relationships:
+  - id: order-management-system
+    label: creates orders via
+actors:
+  - id: shopper
+    name: Shopper
+    label: confirms checkout
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Checkout System** drives the checkout flow at Acme Inc. When the [[domain|shopping]] domain checks out a cart, the [[service|checkout-api]] receives the [[command|checkout-cart]] command and hands it to the [[service|checkout-orchestrator]]. The orchestrator runs the checkout saga — reserving inventory via [[command|reserve-inventory]], authorizing payment via [[command|authorize-payment]], and finally creating the order via [[command|create-order]] against the [[system|order-management-system]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                          | Type    | Responsibility                                                               |
+| ---------------------------------- | ------- | ---------------------------------------------------------------------------- |
+| [[service\|checkout-api]]          | Service | Entry point for checkout. Receives the checkout command and starts the flow. |
+| [[service\|checkout-orchestrator]] | Service | Runs the checkout saga — reserve inventory, authorize payment, create order. |
+
+## Messages this system sends
+
+- [[command\|reserve-inventory]] — reserve stock for the items in the cart.
+- [[command\|authorize-payment]] — authorize payment for the order total.
+- [[command\|create-order]] — create the order in the Order Management System.
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutAPI/index.mdx
new file mode 100644
index 000000000..f22b03fb3
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutAPI/index.mdx
@@ -0,0 +1,53 @@
+---
+id: checkout-api
+version: 1.0.0
+name: Checkout API
+summary: |
+  The entry point to the Checkout System. Receives the checkout command from the Shopping domain and starts the checkout flow.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - ordering-platform
+receives:
+  - id: checkout-cart
+    version: 1.0.0
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/checkout-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Checkout API** is the front door to the Checkout System. When the [[domain|shopping]] domain checks out a cart, this service receives the [[command|checkout-cart]] command, validates it, and hands the work to the [[service|checkout-orchestrator]] to run the checkout saga.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="The checkout command from Shopping"
+  />
+  <Tile
+    icon="RectangleGroupIcon"
+    href="/docs/services/checkout-orchestrator/1.0.0"
+    title="Delegates to the Orchestrator"
+    description="The saga that runs checkout"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area                  | Description                                                                 |
+| --------------------- | --------------------------------------------------------------------------- |
+| Checkout entry        | Receives and validates [[command\|checkout-cart]] from the Shopping domain. |
+| Orchestration handoff | Starts a checkout saga in the [[service\|checkout-orchestrator]].           |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/index.mdx
new file mode 100644
index 000000000..d0489ec1e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/index.mdx
@@ -0,0 +1,32 @@
+---
+id: authorize-payment
+name: Authorize Payment
+version: 1.0.0
+summary: |
+  Command to authorize payment for the total of a checked-out cart.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /payments/authorize
+  statusCodes: ['201', '400', '402', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`AuthorizePayment` is sent by the [[service|checkout-orchestrator]] to authorize payment for the order total. Authorization places a hold on the customer's payment method; the funds are captured once the order is created. If a later step fails, the authorization is voided.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/schema.json b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/schema.json
new file mode 100644
index 000000000..f6cc128e4
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/AuthorizePayment/schema.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AuthorizePayment",
+  "description": "Command to authorize payment for the total of a checked-out cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Identifier of the cart being checked out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "description": "Identifier of the customer paying",
+      "type": "string",
+      "format": "uuid"
+    },
+    "amount": {
+      "description": "Amount to authorize, in minor units (e.g. cents)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "currency": {
+      "description": "ISO 4217 currency code",
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    }
+  },
+  "required": ["cartId", "amount", "currency"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/index.mdx
new file mode 100644
index 000000000..a713a0228
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/index.mdx
@@ -0,0 +1,32 @@
+---
+id: reserve-inventory
+name: Reserve Inventory
+version: 1.0.0
+summary: |
+  Command to reserve stock for the items in a checked-out cart.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /reservations
+  statusCodes: ['201', '400', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReserveInventory` is sent by the [[service|checkout-orchestrator]] to hold stock for the items in a checked-out cart. A successful reservation guarantees the inventory is available while payment is authorized. If a later checkout step fails, the reservation is released.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/schema.json b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/schema.json
new file mode 100644
index 000000000..c7702c1df
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/commands/ReserveInventory/schema.json
@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReserveInventory",
+  "description": "Command to reserve stock for the items in a checked-out cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Identifier of the cart being checked out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "description": "Identifier of the customer checking out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "items": {
+      "description": "The items to reserve",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "quantity": {
+            "type": "integer",
+            "minimum": 1
+          }
+        },
+        "required": ["productId", "quantity"]
+      }
+    }
+  },
+  "required": ["cartId", "items"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/index.mdx
new file mode 100644
index 000000000..ed2265620
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/checkout-system/services/CheckoutOrchestrator/index.mdx
@@ -0,0 +1,59 @@
+---
+id: checkout-orchestrator
+version: 1.0.0
+name: Checkout Orchestrator
+summary: |
+  Runs the checkout saga. Reserves inventory, authorizes payment and creates the order, coordinating the steps that turn a checked-out cart into a confirmed order.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - ordering-platform
+sends:
+  - id: reserve-inventory
+    version: 1.0.0
+  - id: authorize-payment
+    version: 1.0.0
+  - id: create-order
+    version: 1.0.0
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/checkout-orchestrator'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Checkout Orchestrator** is the brain of the Checkout System. Once the [[service|checkout-api]] hands it a checkout, it runs the checkout saga step by step:
+
+1. **Reserve inventory** — sends [[command|reserve-inventory]] to hold stock for the cart's items.
+2. **Authorize payment** — sends [[command|authorize-payment]] to authorize the order total.
+3. **Create the order** — sends [[command|create-order]] to the [[system|order-management-system]].
+
+If any step fails, the orchestrator compensates the earlier steps (releasing the reservation, voiding the authorization) so the customer is never left in an inconsistent state.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Reserve inventory, authorize payment, create order"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area           | Description                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------------ |
+| Inventory      | Reserves stock via [[command\|reserve-inventory]].                                               |
+| Payment        | Authorizes the order total via [[command\|authorize-payment]].                                   |
+| Order creation | Creates the order via [[command\|create-order]] against the [[system\|order-management-system]]. |
+| Compensation   | Rolls back earlier steps if a later step fails.                                                  |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/containers/order-database/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/containers/order-database/index.mdx
new file mode 100644
index 000000000..11dd5802d
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/containers/order-database/index.mdx
@@ -0,0 +1,39 @@
+---
+id: order-database
+name: Order Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for orders and their items.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for orders
+classification: confidential
+retention: 7y
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Order Database** is the authoritative store for orders at Acme Inc. The [[service|order-service]] reads from and writes to it as orders are created, cancelled and completed.
+
+### What does it store?
+
+- **Orders** — one row per order: id, customer, status, total and timestamps.
+- **Order Items** — one row per item in an order: product, quantity and unit price.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Order Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Retention
+
+Orders are financial records and are retained for **7 years** (see frontmatter) to meet accounting and audit requirements.
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/containers/order-database/schema.sql b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/containers/order-database/schema.sql
new file mode 100644
index 000000000..554b70834
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/containers/order-database/schema.sql
@@ -0,0 +1,24 @@
+-- Order Database — system of record for orders
+
+CREATE TABLE orders (
+    order_id     UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    cart_id      UUID,
+    customer_id  UUID NOT NULL,
+    status       TEXT NOT NULL DEFAULT 'CREATED'
+                   CHECK (status IN ('CREATED', 'COMPLETED', 'CANCELLED')),
+    total_cents  INTEGER NOT NULL CHECK (total_cents >= 0),
+    currency     CHAR(3) NOT NULL DEFAULT 'USD',
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE order_items (
+    order_id         UUID NOT NULL REFERENCES orders (order_id) ON DELETE CASCADE,
+    product_id       UUID NOT NULL,
+    quantity         INTEGER NOT NULL CHECK (quantity > 0),
+    unit_price_cents INTEGER NOT NULL CHECK (unit_price_cents >= 0),
+    PRIMARY KEY (order_id, product_id)
+);
+
+CREATE INDEX idx_orders_customer ON orders (customer_id);
+CREATE INDEX idx_orders_status   ON orders (status);
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/flows/OrderCancellation/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/flows/OrderCancellation/index.mdx
new file mode 100644
index 000000000..b13d842b2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/flows/OrderCancellation/index.mdx
@@ -0,0 +1,105 @@
+---
+id: order-cancellation
+name: Order Cancellation
+version: 1.0.0
+summary: |
+  How an order is cancelled — whether requested by the customer or triggered by a failure — and the events that tell the rest of the business to unwind it.
+owners:
+  - ordering-platform
+steps:
+  - id: cancellation_trigger
+    title: Cancellation requested
+    actor:
+      name: Shopper or System
+      summary: A customer asks to cancel, or a downstream failure (payment, inventory) forces a cancellation.
+    next_step:
+      id: cancel_order_command
+      label: Cancel order
+
+  - id: cancel_order_command
+    title: Cancel Order
+    message:
+      id: cancel-order
+      version: 1.0.0
+    next_step:
+      id: order_service
+      label: Handle cancellation
+
+  - id: order_service
+    title: Order Service
+    service:
+      id: order-service
+      version: 1.0.0
+    next_steps:
+      - id: eligibility_check
+        label: Check eligibility
+      - id: not_cancellable
+        label: Already completed
+
+  - id: eligibility_check
+    title: Cancellation policy check
+    custom:
+      title: Cancellation policy
+      color: blue
+      icon: ClipboardDocumentCheckIcon
+      type: Policy
+      summary: An order can only be cancelled before it is completed. Completed orders must go through returns instead.
+      properties:
+        rule: 'status must be CREATED'
+    next_step:
+      id: order_database
+      label: Mark cancelled
+
+  - id: order_database
+    title: Order Database
+    container:
+      id: order-database
+    next_step:
+      id: order_cancelled
+      label: Persist + publish
+
+  - id: order_cancelled
+    title: Order Cancelled
+    message:
+      id: order-cancelled
+      version: 1.0.0
+    next_step:
+      id: downstream_unwind
+      label: Unwind downstream
+
+  - id: downstream_unwind
+    title: Downstream unwind
+    custom:
+      title: Release and refund
+      color: orange
+      icon: ArrowUturnLeftIcon
+      type: Compensation
+      summary: Consumers of OrderCancelled release reserved inventory, void or refund the payment, and stop fulfilment.
+      properties:
+        consumers: 'inventory, payment, fulfilment'
+
+  - id: not_cancellable
+    title: Cannot cancel
+    custom:
+      title: Cannot cancel
+      color: red
+      icon: ExclamationTriangleIcon
+      type: Exception
+      summary: The order has already been completed and cannot be cancelled. The customer is directed to the returns process.
+      properties:
+        next_action: 'start a return'
+---
+
+## Overview
+
+**Order Cancellation** documents how the [[system|order-management-system]] cancels an order. Cancellation can be requested by a shopper or forced by a downstream failure during checkout. Only orders that have not yet completed can be cancelled.
+
+<NodeGraph />
+
+## How it works
+
+1. A [[command|cancel-order]] command reaches the [[service|order-service]].
+2. The service checks the cancellation policy — only `CREATED` orders are cancellable.
+3. If eligible, the order is marked cancelled in the [[container|order-database]] and [[event|order-cancelled]] is published.
+4. Downstream consumers react to [[event|order-cancelled]] to release inventory, refund payment and stop fulfilment.
+5. If the order is already completed, cancellation is rejected and the customer is sent to the returns process.
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/index.mdx
new file mode 100644
index 000000000..a2610d921
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/index.mdx
@@ -0,0 +1,53 @@
+---
+id: order-management-system
+name: Order Management System
+version: 1.0.0
+summary: |
+  Internal system that is the source of truth for orders. It creates orders, tracks their lifecycle, and publishes events as orders are created, completed and cancelled.
+owners:
+  - ordering-platform
+services:
+  - id: order-service
+containers:
+  - id: order-database
+flows:
+  - id: order-cancellation
+    version: 1.0.0
+relationships:
+  - id: checkout-system
+    label: receives orders from
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Order Management System** owns the order at Acme Inc. It accepts the [[command|create-order]] command from the [[system|checkout-system]], persists orders in the [[container|order-database]], and serves order lookups via [[query|get-order]]. As an order moves through its lifecycle it publishes [[event|order-created]], [[event|order-completed]] and [[event|order-cancelled]] events for the rest of the business to react to.
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                     | Type       | Responsibility                                                            |
+| ----------------------------- | ---------- | ------------------------------------------------------------------------- |
+| [[service\|order-service]]    | Service    | Creates, cancels and serves orders, and publishes order lifecycle events. |
+| [[container\|order-database]] | Data store | PostgreSQL system of record for orders and their items.                   |
+
+## Messages this system publishes
+
+- [[event\|order-created]] — a new order has been created.
+- [[event\|order-completed]] — an order has been fulfilled and completed.
+- [[event\|order-cancelled]] — an order has been cancelled.
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/asyncapi.yml b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/asyncapi.yml
new file mode 100644
index 000000000..ff77c2538
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/asyncapi.yml
@@ -0,0 +1,233 @@
+asyncapi: 3.0.0
+
+info:
+  title: Order Service
+  version: 1.0.0
+  description: |
+    The event-driven interface of the Order Service — the system of record for orders.
+
+    The service consumes commands to create and cancel orders, and publishes events as
+    orders move through their lifecycle (created, completed, cancelled). Query access
+    (`GetOrder`) is served over the REST API and is not part of this AsyncAPI document.
+  contact:
+    name: Ordering Platform
+    email: ordering-platform@acme.test
+
+defaultContentType: application/json
+
+servers:
+  production:
+    host: broker.acme.test:9092
+    protocol: kafka
+    description: Production Kafka cluster.
+
+channels:
+  orderCommands:
+    address: ordering.commands
+    title: Order commands
+    description: Commands the Order Service consumes to create and cancel orders.
+    messages:
+      CreateOrder:
+        $ref: '#/components/messages/CreateOrder'
+      CancelOrder:
+        $ref: '#/components/messages/CancelOrder'
+
+  orderEvents:
+    address: ordering.orders
+    title: Order lifecycle events
+    description: Events the Order Service publishes as orders move through their lifecycle.
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+      OrderCompleted:
+        $ref: '#/components/messages/OrderCompleted'
+      OrderCancelled:
+        $ref: '#/components/messages/OrderCancelled'
+
+operations:
+  receiveCreateOrder:
+    action: receive
+    title: Create Order
+    summary: Create a new order from a checked-out cart.
+    channel:
+      $ref: '#/channels/orderCommands'
+    messages:
+      - $ref: '#/channels/orderCommands/messages/CreateOrder'
+
+  receiveCancelOrder:
+    action: receive
+    title: Cancel Order
+    summary: Cancel an existing order.
+    channel:
+      $ref: '#/channels/orderCommands'
+    messages:
+      - $ref: '#/channels/orderCommands/messages/CancelOrder'
+
+  publishOrderCreated:
+    action: send
+    title: Order Created
+    summary: Published when a new order has been created.
+    channel:
+      $ref: '#/channels/orderEvents'
+    messages:
+      - $ref: '#/channels/orderEvents/messages/OrderCreated'
+
+  publishOrderCompleted:
+    action: send
+    title: Order Completed
+    summary: Published when an order has been fulfilled and completed.
+    channel:
+      $ref: '#/channels/orderEvents'
+    messages:
+      - $ref: '#/channels/orderEvents/messages/OrderCompleted'
+
+  publishOrderCancelled:
+    action: send
+    title: Order Cancelled
+    summary: Published when an order has been cancelled.
+    channel:
+      $ref: '#/channels/orderEvents'
+    messages:
+      - $ref: '#/channels/orderEvents/messages/OrderCancelled'
+
+components:
+  messages:
+    CreateOrder:
+      name: CreateOrder
+      title: Create Order
+      summary: Command to create a new order from a checked-out cart.
+      payload:
+        $ref: '#/components/schemas/CreateOrder'
+    CancelOrder:
+      name: CancelOrder
+      title: Cancel Order
+      summary: Command to cancel an existing order.
+      payload:
+        $ref: '#/components/schemas/CancelOrder'
+    OrderCreated:
+      name: OrderCreated
+      title: Order Created
+      summary: Published when a new order has been created.
+      payload:
+        $ref: '#/components/schemas/OrderCreated'
+    OrderCompleted:
+      name: OrderCompleted
+      title: Order Completed
+      summary: Published when an order has been fulfilled and completed.
+      payload:
+        $ref: '#/components/schemas/OrderCompleted'
+    OrderCancelled:
+      name: OrderCancelled
+      title: Order Cancelled
+      summary: Published when an order has been cancelled.
+      payload:
+        $ref: '#/components/schemas/OrderCancelled'
+
+  schemas:
+    OrderItem:
+      type: object
+      required: [productId, quantity, unitPrice]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        quantity:
+          type: integer
+          minimum: 1
+        unitPrice:
+          type: integer
+          description: Price per unit in minor units (e.g. cents).
+
+    CancellationReason:
+      type: string
+      enum: [CUSTOMER_REQUESTED, PAYMENT_FAILED, OUT_OF_STOCK, FRAUD]
+
+    CreateOrder:
+      type: object
+      description: Command to create a new order from a checked-out cart.
+      required: [cartId, customerId, items, total, currency]
+      properties:
+        cartId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/OrderItem'
+        total:
+          type: integer
+          minimum: 0
+          description: Order total in minor units (e.g. cents).
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        paymentAuthorizationId:
+          type: string
+          description: Identifier of the payment authorization for this order.
+
+    CancelOrder:
+      type: object
+      description: Command to cancel an existing order.
+      required: [orderId, reason]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        reason:
+          $ref: '#/components/schemas/CancellationReason'
+
+    OrderCreated:
+      type: object
+      description: Published when a new order has been created.
+      required: [orderId, customerId, total, currency, createdAt]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        total:
+          type: integer
+          description: Order total in minor units (e.g. cents).
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        createdAt:
+          type: string
+          format: date-time
+
+    OrderCompleted:
+      type: object
+      description: Published when an order has been fulfilled and completed.
+      required: [orderId, customerId, completedAt]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        completedAt:
+          type: string
+          format: date-time
+
+    OrderCancelled:
+      type: object
+      description: Published when an order has been cancelled.
+      required: [orderId, reason, cancelledAt]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        reason:
+          $ref: '#/components/schemas/CancellationReason'
+        cancelledAt:
+          type: string
+          format: date-time
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/index.mdx
new file mode 100644
index 000000000..3d109146a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/index.mdx
@@ -0,0 +1,32 @@
+---
+id: cancel-order
+name: Cancel Order
+version: 1.0.0
+summary: |
+  Command to cancel an existing order.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /orders/{orderId}/cancel
+  statusCodes: ['200', '404', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CancelOrder` is handled by the [[service|order-service]]. It cancels an order that has not yet been completed — releasing any reservations and voiding the payment authorization where needed. On success the Order Service publishes an [[event|order-cancelled]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/schema.json b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/schema.json
new file mode 100644
index 000000000..a67eede17
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CancelOrder/schema.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CancelOrder",
+  "description": "Command to cancel an existing order",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "description": "Identifier of the order to cancel",
+      "type": "string",
+      "format": "uuid"
+    },
+    "reason": {
+      "description": "Why the order is being cancelled",
+      "type": "string",
+      "enum": ["CUSTOMER_REQUESTED", "PAYMENT_FAILED", "OUT_OF_STOCK", "FRAUD"]
+    }
+  },
+  "required": ["orderId", "reason"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/index.mdx
new file mode 100644
index 000000000..86eaff6b9
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/index.mdx
@@ -0,0 +1,32 @@
+---
+id: create-order
+name: Create Order
+version: 1.0.0
+summary: |
+  Command to create a new order from a checked-out cart.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /orders
+  statusCodes: ['201', '400', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CreateOrder` is sent by the [[service|checkout-orchestrator]] and handled by the [[service|order-service]]. It is the final step of the checkout saga — once inventory is reserved and payment is authorized, this command creates the order. On success the Order Service publishes an [[event|order-created]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/schema.json b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/schema.json
new file mode 100644
index 000000000..796d29dc7
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/commands/CreateOrder/schema.json
@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CreateOrder",
+  "description": "Command to create a new order from a checked-out cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Identifier of the cart this order was created from",
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "description": "Identifier of the customer placing the order",
+      "type": "string",
+      "format": "uuid"
+    },
+    "items": {
+      "description": "The items in the order",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "quantity": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "unitPrice": {
+            "type": "integer",
+            "description": "Price per unit in minor units (e.g. cents)"
+          }
+        },
+        "required": ["productId", "quantity", "unitPrice"]
+      }
+    },
+    "total": {
+      "description": "Order total in minor units (e.g. cents)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "currency": {
+      "description": "ISO 4217 currency code",
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "paymentAuthorizationId": {
+      "description": "Identifier of the payment authorization for this order",
+      "type": "string"
+    }
+  },
+  "required": ["cartId", "customerId", "items", "total", "currency"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/index.mdx
new file mode 100644
index 000000000..6a5c9fb4e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/index.mdx
@@ -0,0 +1,29 @@
+---
+id: order-cancelled
+name: Order Cancelled
+version: 1.0.0
+summary: |
+  Published when an order has been cancelled.
+owners:
+  - ordering-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderCancelled` is published by the [[service|order-service]] when an order is cancelled — whether at the customer's request or because a downstream step (payment, inventory) failed. Downstream systems consume it to release inventory, refund or void payment, and stop fulfilment.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/schema.json b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/schema.json
new file mode 100644
index 000000000..d01f5531a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCancelled/schema.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderCancelled",
+  "description": "Published when an order has been cancelled",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "reason": {
+      "type": "string",
+      "enum": ["CUSTOMER_REQUESTED", "PAYMENT_FAILED", "OUT_OF_STOCK", "FRAUD"]
+    },
+    "cancelledAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": ["orderId", "reason", "cancelledAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/index.mdx
new file mode 100644
index 000000000..e78b1611e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/index.mdx
@@ -0,0 +1,29 @@
+---
+id: order-completed
+name: Order Completed
+version: 1.0.0
+summary: |
+  Published when an order has been fulfilled and completed.
+owners:
+  - ordering-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderCompleted` is published by the [[service|order-service]] when an order has been fully fulfilled. It marks the end of the happy path for an order. Downstream systems consume it to close out fulfilment, capture payment, and update reporting.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/schema.json b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/schema.json
new file mode 100644
index 000000000..9fc2b0049
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCompleted/schema.json
@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderCompleted",
+  "description": "Published when an order has been fulfilled and completed",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "completedAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": ["orderId", "customerId", "completedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/index.mdx
new file mode 100644
index 000000000..b87b1e969
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: order-created
+name: Order Created
+version: 1.0.0
+summary: |
+  Published when a new order has been created.
+owners:
+  - ordering-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderCreated` is published by the [[service|order-service]] when a new order is created from a checked-out cart. Downstream systems consume this event to begin fulfilment, send confirmation to the customer, and update reporting.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/schema.json b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/schema.json
new file mode 100644
index 000000000..44c4686ca
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/events/OrderCreated/schema.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderCreated",
+  "description": "Published when a new order has been created",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "total": {
+      "type": "integer",
+      "description": "Order total in minor units (e.g. cents)"
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": ["orderId", "customerId", "total", "currency", "createdAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/index.mdx
new file mode 100644
index 000000000..b9377de90
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/index.mdx
@@ -0,0 +1,74 @@
+---
+id: order-service
+version: 1.0.0
+name: Order Service
+summary: |
+  The system of record for orders. Creates and cancels orders, serves order lookups, and publishes events as orders move through their lifecycle.
+styles:
+  icon: /icons/languages/java.svg
+owners:
+  - ordering-platform
+receives:
+  - id: create-order
+    version: 1.0.0
+  - id: cancel-order
+    version: 1.0.0
+  - id: get-order
+    version: 1.0.0
+sends:
+  - id: order-created
+    version: 1.0.0
+  - id: order-completed
+    version: 1.0.0
+  - id: order-cancelled
+    version: 1.0.0
+writesTo:
+  - id: order-database
+readsFrom:
+  - id: order-database
+repository:
+  language: Java
+  url: 'https://github.com/acme/order-service'
+specifications:
+  - type: asyncapi
+    path: asyncapi.yml
+    name: Order Service AsyncAPI
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Order Service** is the heart of the Order Management System. It receives [[command|create-order]] from the [[system|checkout-system]], persists orders to the [[container|order-database]], and serves order lookups via [[query|get-order]]. It also handles [[command|cancel-order]]. As orders move through their lifecycle it publishes [[event|order-created]], [[event|order-completed]] and [[event|order-cancelled]] events.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Order lifecycle events"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Order commands and queries"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area               | Description                                                                                |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| Order creation     | Handles [[command\|create-order]] from the Checkout System and persists the order.         |
+| Order cancellation | Handles [[command\|cancel-order]] and compensates downstream where needed.                 |
+| Order lookups      | Serves [[query\|get-order]] from the [[container\|order-database]].                        |
+| Event publishing   | Emits [[event\|order-created]], [[event\|order-completed]] and [[event\|order-cancelled]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/queries/GetOrder/index.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/queries/GetOrder/index.mdx
new file mode 100644
index 000000000..7659bac71
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/queries/GetOrder/index.mdx
@@ -0,0 +1,32 @@
+---
+id: get-order
+name: Get Order
+version: 1.0.0
+summary: |
+  Query to fetch a single order by its identifier.
+owners:
+  - ordering-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /orders/{orderId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetOrder` is handled by the [[service|order-service]]. It returns the current state of a single order, read directly from the [[container|order-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/queries/GetOrder/schema.json b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/queries/GetOrder/schema.json
new file mode 100644
index 000000000..40582a9be
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/systems/order-management-system/services/OrderService/queries/GetOrder/schema.json
@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetOrder",
+  "description": "Query to fetch a single order by its identifier, and the order returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "Parameters used to look up the order",
+      "type": "object",
+      "properties": {
+        "orderId": {
+          "description": "Unique identifier of the order to fetch",
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "required": ["orderId"]
+    },
+    "response": {
+      "description": "The order returned by the query",
+      "type": "object",
+      "properties": {
+        "orderId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "customerId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["CREATED", "COMPLETED", "CANCELLED"]
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "productId": { "type": "string", "format": "uuid" },
+              "quantity": { "type": "integer", "minimum": 1 },
+              "unitPrice": { "type": "integer" }
+            },
+            "required": ["productId", "quantity", "unitPrice"]
+          }
+        },
+        "total": {
+          "type": "integer",
+          "description": "Order total in minor units (e.g. cents)"
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "required": ["orderId", "customerId", "status", "items", "total", "currency"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Ordering/ubiquitous-language.mdx b/packages/create-eventcatalog/templates/default/domains/Ordering/ubiquitous-language.mdx
new file mode 100644
index 000000000..9278e241d
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Ordering/ubiquitous-language.mdx
@@ -0,0 +1,53 @@
+---
+dictionary:
+  - id: Order
+    name: Order
+    summary: 'A confirmed intent to purchase, created from a checked-out cart and owned for its whole lifecycle.'
+    description: |
+      The order is the central concept of the Ordering domain. It is owned by the Order Management
+      System, which is the source of truth for orders. An order has:
+
+      - A unique order id and the customer it belongs to
+      - A set of order items (product, quantity and unit price)
+      - A total and currency
+      - A status (CREATED, COMPLETED or CANCELLED)
+
+      An order is immutable in its essentials once created — its lifecycle is expressed through events,
+      not by editing it in place.
+    icon: ClipboardList
+  - id: Checkout
+    name: Checkout
+    summary: 'The flow that turns a checked-out cart into a confirmed order.'
+    description: |
+      Checkout is owned by the Checkout System. It is the orchestration that runs after the Shopping
+      domain checks out a cart — reserving inventory, authorizing payment and creating the order.
+    icon: CreditCard
+  - id: Saga
+    name: Saga
+    summary: 'A multi-step process with compensating actions, used to coordinate checkout across systems.'
+    description: |
+      The Checkout Orchestrator runs checkout as a saga: a sequence of steps (reserve inventory,
+      authorize payment, create order) where each step has a compensating action that undoes it if a
+      later step fails. This keeps the customer consistent without distributed transactions.
+    icon: Workflow
+  - id: Reservation
+    name: Reservation
+    summary: 'A temporary hold on stock for the items in a cart, taken during checkout.'
+    icon: PackageCheck
+  - id: Authorization
+    name: Authorization
+    summary: "A hold placed on a customer's payment method for the order total, captured when the order is created."
+    icon: ShieldCheck
+  - id: Order Item
+    name: Order Item
+    summary: 'A single product line within an order: a product, a quantity and the price paid per unit.'
+    icon: ListOrdered
+  - id: Order Status
+    name: Order Status
+    summary: 'Where an order sits in its life: CREATED, COMPLETED or CANCELLED.'
+    description: |
+      - CREATED — the order exists and is being fulfilled.
+      - COMPLETED — the order has been fully fulfilled.
+      - CANCELLED — the order was cancelled before completion.
+    icon: Workflow
+---
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/entities/fraud-check/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/entities/fraud-check/index.mdx
new file mode 100644
index 000000000..f700c2a2f
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/entities/fraud-check/index.mdx
@@ -0,0 +1,39 @@
+---
+id: fraud-check
+name: Fraud Check
+version: 1.0.0
+identifier: fraudCheckId
+summary: Fraud screening result associated with a payment attempt.
+owners:
+  - payments-platform
+properties:
+  - name: fraudCheckId
+    type: UUID
+    required: true
+    description: Unique fraud check identifier.
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Payment attempt being screened.
+    references: payment
+    relationType: screens
+    referencesIdentifier: paymentId
+  - name: result
+    type: string
+    required: true
+    description: Screening result.
+    enum:
+      - passed
+      - failed
+      - review
+  - name: checkedAt
+    type: datetime
+    required: true
+    description: Time screening completed.
+---
+
+## Overview
+
+Fraud Check documents the screening outcome from [[system|fraud-detection]] so payment decisions are auditable.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/entities/payment-authorization/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/entities/payment-authorization/index.mdx
new file mode 100644
index 000000000..29413fc6d
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/entities/payment-authorization/index.mdx
@@ -0,0 +1,35 @@
+---
+id: payment-authorization
+name: Payment Authorization
+version: 1.0.0
+identifier: authorizationId
+summary: Approval from a payment provider to reserve funds for an order.
+owners:
+  - payments-platform
+properties:
+  - name: authorizationId
+    type: UUID
+    required: true
+    description: Unique authorization identifier.
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Payment this authorization belongs to.
+    references: payment
+    relationType: belongsTo
+    referencesIdentifier: paymentId
+  - name: providerReference
+    type: string
+    required: true
+    description: External payment provider reference.
+  - name: authorizedAt
+    type: datetime
+    required: true
+    description: Time authorization was granted.
+---
+
+## Overview
+
+Payment Authorization captures the result of [[command|authorize-payment]] and links Acme payment state to provider state.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/entities/payment/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/entities/payment/index.mdx
new file mode 100644
index 000000000..889df22e3
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/entities/payment/index.mdx
@@ -0,0 +1,36 @@
+---
+id: payment
+name: Payment
+version: 1.0.0
+identifier: paymentId
+aggregateRoot: true
+summary: Acme's internal record of payment intent and outcome for an order.
+owners:
+  - payments-platform
+properties:
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Unique payment identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order being paid for.
+    references: order
+    relationType: paysFor
+    referencesIdentifier: orderId
+  - name: amount
+    type: decimal
+    required: true
+    description: Amount requested.
+  - name: status
+    type: string
+    required: true
+    description: Payment lifecycle status.
+---
+
+## Overview
+
+Payment is the Payments domain aggregate. It records Acme's view of payment state regardless of external provider retries or webhook order.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/entities/refund/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/entities/refund/index.mdx
new file mode 100644
index 000000000..36ff90861
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/entities/refund/index.mdx
@@ -0,0 +1,36 @@
+---
+id: refund
+name: Refund
+version: 1.0.0
+identifier: refundId
+aggregateRoot: true
+summary: A request to return money to a customer after payment.
+owners:
+  - payments-platform
+properties:
+  - name: refundId
+    type: UUID
+    required: true
+    description: Unique refund identifier.
+  - name: paymentId
+    type: UUID
+    required: true
+    description: Payment being refunded.
+    references: payment
+    relationType: refunds
+    referencesIdentifier: paymentId
+  - name: amount
+    type: decimal
+    required: true
+    description: Refund amount.
+  - name: status
+    type: string
+    required: true
+    description: Refund lifecycle state.
+---
+
+## Overview
+
+Refund is owned by Payments and records refund requests and provider outcomes such as [[event|refund-processed]].
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/index.mdx
new file mode 100644
index 000000000..55bac4a1b
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/index.mdx
@@ -0,0 +1,69 @@
+---
+id: payments
+name: Payments
+version: 1.0.0
+summary: |
+  The Payments domain takes payment for orders and processes refunds. It orchestrates authorization and capture through an external payment processor, and screens payments for fraud.
+owners:
+  - payments-platform
+systems:
+  - id: payment-processing-system
+    version: 1.0.0
+  - id: stripe
+    version: 1.0.0
+  - id: fraud-detection
+    version: 1.0.0
+entities:
+  - id: payment
+    version: 1.0.0
+  - id: payment-authorization
+    version: 1.0.0
+  - id: refund
+    version: 1.0.0
+  - id: fraud-check
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Payments** domain is responsible for moving money. It authorizes and captures payment for orders, issues refunds, and screens payments for fraud. It owns one internal system and integrates with two external providers:
+
+<Tiles>
+  <Tile
+    icon="CreditCardIcon"
+    href="/docs/systems/payment-processing-system/1.0.0"
+    title="Payment Processing System"
+    description="Orchestrates authorization, capture and refunds for orders."
+  />
+  <Tile
+    icon="BuildingLibraryIcon"
+    href="/docs/systems/stripe/1.0.0"
+    title="Stripe"
+    description="External payment processor that charges cards and issues refunds."
+  />
+  <Tile
+    icon="ShieldExclamationIcon"
+    href="/docs/systems/fraud-detection/1.0.0"
+    title="Fraud Detection"
+    description="External provider that screens payments for fraud."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Payment Processing System** is the internal orchestrator. When the Ordering domain authorizes a payment, it requests payment via the external **Stripe** system and, in parallel, asks **Fraud Detection** to screen the payment. Stripe reports back whether the payment succeeded or failed, and the Payment Processing System records the outcome.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/index.mdx
new file mode 100644
index 000000000..d7263003e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/index.mdx
@@ -0,0 +1,49 @@
+---
+id: fraud-detection
+name: Fraud Detection
+version: 1.0.0
+scope: external
+summary: |
+  External provider that screens payments for fraud. It consumes payment requests and returns a pass or fail verdict.
+owners:
+  - payments-platform
+services:
+  - id: fraud-api
+relationships:
+  - id: payment-processing-system
+    label: screens payments for
+badges:
+  - content: External
+    backgroundColor: yellow
+    textColor: yellow
+    icon: GlobeAltIcon
+---
+
+## Overview
+
+**Fraud Detection** is an external provider Acme Inc uses to screen payments for fraud. It is owned and operated by a third party — modelled here as an **external system** so the catalog shows how the [[system|payment-processing-system]] integrates with it.
+
+It consumes [[event|payment-requested]] and returns a verdict via [[event|fraud-check-passed]] or [[event|fraud-check-failed]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component              | Type    | Responsibility                                               |
+| ---------------------- | ------- | ------------------------------------------------------------ |
+| [[service\|fraud-api]] | Service | Screens a payment for fraud and returns a pass/fail verdict. |
+
+## Messages this system publishes
+
+- [[event\|fraud-check-passed]] — a payment passed fraud screening.
+- [[event\|fraud-check-failed]] — a payment failed fraud screening.
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/index.mdx
new file mode 100644
index 000000000..ec4dcf580
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/index.mdx
@@ -0,0 +1,29 @@
+---
+id: fraud-check-failed
+name: Fraud Check Failed
+version: 1.0.0
+summary: |
+  Published when a payment fails fraud screening.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`FraudCheckFailed` is published by the [[service|fraud-api]] when a payment is flagged as fraudulent. The [[system|payment-processing-system]] uses it to block the charge and cancel the order.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/schema.json b/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/schema.json
new file mode 100644
index 000000000..8deb7fd1a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckFailed/schema.json
@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FraudCheckFailed",
+  "description": "Published when a payment fails fraud screening",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraud risk score; higher is riskier"
+    },
+    "reason": {
+      "type": "string",
+      "enum": ["HIGH_RISK_SCORE", "BLOCKLISTED", "VELOCITY", "MISMATCH"]
+    },
+    "checkedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "reason", "checkedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/index.mdx
new file mode 100644
index 000000000..551254e24
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/index.mdx
@@ -0,0 +1,29 @@
+---
+id: fraud-check-passed
+name: Fraud Check Passed
+version: 1.0.0
+summary: |
+  Published when a payment passes fraud screening.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`FraudCheckPassed` is published by the [[service|fraud-api]] when a payment clears fraud screening. The [[system|payment-processing-system]] uses it to allow the charge to proceed.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/schema.json b/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/schema.json
new file mode 100644
index 000000000..979e2cab9
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/events/FraudCheckPassed/schema.json
@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FraudCheckPassed",
+  "description": "Published when a payment passes fraud screening",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Fraud risk score; lower is safer"
+    },
+    "checkedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "checkedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/index.mdx
new file mode 100644
index 000000000..6a7e4293a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/fraud-detection/services/FraudAPI/index.mdx
@@ -0,0 +1,51 @@
+---
+id: fraud-api
+version: 1.0.0
+name: Fraud API
+summary: |
+  External fraud screening API. It consumes payment requests and returns a pass or fail verdict for each.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - payments-platform
+receives:
+  - id: payment-requested
+    version: 1.0.0
+sends:
+  - id: fraud-check-passed
+    version: 1.0.0
+  - id: fraud-check-failed
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/acme/fraud-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Fraud API** screens payments for fraud. It consumes [[event|payment-requested]] from the [[system|payment-processing-system]] and returns a verdict — [[event|fraud-check-passed]] or [[event|fraud-check-failed]] — which the Payments domain uses to allow or block the charge.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Fraud verdicts"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Payment requests to screen"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/containers/payment-database/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/containers/payment-database/index.mdx
new file mode 100644
index 000000000..2422aa6b2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/containers/payment-database/index.mdx
@@ -0,0 +1,39 @@
+---
+id: payment-database
+name: Payment Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for payments and refunds.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for payments and refunds
+classification: confidential
+retention: 7y
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Payment Database** is the authoritative store for payments and refunds at Acme Inc. The [[service|payment-api]] and [[service|payment-worker]] read from and write to it as payments are authorized, charged and refunded.
+
+### What does it store?
+
+- **Payments** — one row per payment: id, order, amount, status and timestamps.
+- **Refunds** — one row per refund: id, payment, amount, status and timestamps.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Payment Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Retention
+
+Payments and refunds are financial records and are retained for **7 years** (see frontmatter) to meet accounting and audit requirements.
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/containers/payment-database/schema.sql b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/containers/payment-database/schema.sql
new file mode 100644
index 000000000..a53415c14
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/containers/payment-database/schema.sql
@@ -0,0 +1,25 @@
+-- Payment Database — system of record for payments and refunds
+
+CREATE TABLE payments (
+    payment_id   UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    order_id     UUID NOT NULL,
+    customer_id  UUID,
+    amount_cents INTEGER NOT NULL CHECK (amount_cents >= 0),
+    currency     CHAR(3) NOT NULL DEFAULT 'USD',
+    status       TEXT NOT NULL DEFAULT 'REQUESTED'
+                   CHECK (status IN ('REQUESTED', 'SUCCEEDED', 'FAILED')),
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE refunds (
+    refund_id    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    payment_id   UUID NOT NULL REFERENCES payments (payment_id),
+    amount_cents INTEGER NOT NULL CHECK (amount_cents >= 0),
+    status       TEXT NOT NULL DEFAULT 'REQUESTED'
+                   CHECK (status IN ('REQUESTED', 'PROCESSED', 'FAILED')),
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_payments_order  ON payments (order_id);
+CREATE INDEX idx_payments_status ON payments (status);
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/index.mdx
new file mode 100644
index 000000000..e8e180e02
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/index.mdx
@@ -0,0 +1,53 @@
+---
+id: payment-processing-system
+name: Payment Processing System
+version: 1.0.0
+summary: |
+  Internal system that orchestrates payment for orders. It authorizes payments, requests charges from the external payment processor, handles the outcome, and issues refunds.
+owners:
+  - payments-platform
+services:
+  - id: payment-api
+  - id: payment-worker
+containers:
+  - id: payment-database
+relationships:
+  - id: stripe
+    label: requests charges from
+  - id: fraud-detection
+    label: screens payments with
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Payment Processing System** is the internal heart of the Payments domain. When the Ordering domain sends [[command|authorize-payment]], the [[service|payment-api]] records the intent in the [[container|payment-database]] and the [[service|payment-worker]] requests a charge from the external [[system|stripe]] via [[event|payment-requested]]. Stripe reports the outcome back as [[event|payment-succeeded]] or [[event|payment-failed]], which the worker records. The system also issues refunds via [[event|refund-requested]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                       | Type       | Responsibility                                                  |
+| ------------------------------- | ---------- | --------------------------------------------------------------- |
+| [[service\|payment-api]]        | Service    | Receives authorization requests and records payment intent.     |
+| [[service\|payment-worker]]     | Service    | Drives charges and refunds against Stripe and records outcomes. |
+| [[container\|payment-database]] | Data store | PostgreSQL system of record for payments and refunds.           |
+
+## Messages this system publishes
+
+- [[event\|payment-requested]] — a charge has been requested from the payment processor.
+- [[event\|refund-requested]] — a refund has been requested from the payment processor.
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentAPI/index.mdx
new file mode 100644
index 000000000..a2bb511fe
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentAPI/index.mdx
@@ -0,0 +1,51 @@
+---
+id: payment-api
+version: 1.0.0
+name: Payment API
+summary: |
+  Receives payment authorization requests from the Ordering domain and records the payment intent, kicking off the charge against the payment processor.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - payments-platform
+receives:
+  - id: authorize-payment
+    version: 1.0.0
+writesTo:
+  - id: payment-database
+readsFrom:
+  - id: payment-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/payment-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Payment API** is the entry point to the Payment Processing System. It receives [[command|authorize-payment]] from the Ordering domain, records the payment intent in the [[container|payment-database]], and leaves the [[service|payment-worker]] to drive the charge against [[system|stripe]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="The authorize-payment command from Ordering"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area          | Description                                                    |
+| ------------- | -------------------------------------------------------------- |
+| Authorization | Receives and validates [[command\|authorize-payment]].         |
+| Persistence   | Records payment intent in the [[container\|payment-database]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/index.mdx
new file mode 100644
index 000000000..425194162
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/index.mdx
@@ -0,0 +1,29 @@
+---
+id: payment-requested
+name: Payment Requested
+version: 1.0.0
+summary: |
+  Published when the Payment Processing System requests a charge from the payment processor.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`PaymentRequested` is published by the [[service|payment-worker]] to ask the external [[system|stripe]] to charge a customer for an order. Stripe responds with [[event|payment-succeeded]] or [[event|payment-failed]]. The [[system|fraud-detection]] system also consumes this event to screen the payment.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/schema.json b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/schema.json
new file mode 100644
index 000000000..b25ed842b
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/PaymentRequested/schema.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PaymentRequested",
+  "description": "Published when a charge is requested from the payment processor",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "customerId": { "type": "string", "format": "uuid" },
+    "amount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Amount to charge, in minor units (e.g. cents)"
+    },
+    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+    "requestedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "amount", "currency", "requestedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/index.mdx
new file mode 100644
index 000000000..ffedefba9
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/index.mdx
@@ -0,0 +1,29 @@
+---
+id: refund-requested
+name: Refund Requested
+version: 1.0.0
+summary: |
+  Published when the Payment Processing System requests a refund from the payment processor.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RefundRequested` is published by the [[service|payment-worker]] to ask the external [[system|stripe]] to refund a previous charge — for example when an order is cancelled after payment. Stripe responds with [[event|refund-processed]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/schema.json b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/schema.json
new file mode 100644
index 000000000..db69eb603
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/schema.json
@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RefundRequested",
+  "description": "Published when a refund is requested from the payment processor",
+  "type": "object",
+  "properties": {
+    "refundId": { "type": "string", "format": "uuid" },
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "amount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Amount to refund, in minor units (e.g. cents)"
+    },
+    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+    "reason": { "type": "string" },
+    "requestedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["refundId", "paymentId", "amount", "currency", "requestedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/index.mdx
new file mode 100644
index 000000000..abe0fb1dd
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/index.mdx
@@ -0,0 +1,66 @@
+---
+id: payment-worker
+version: 1.0.0
+name: Payment Worker
+summary: |
+  Drives charges and refunds against the external payment processor and records the outcomes. It requests payments and refunds, and consumes the success/failure events Stripe returns.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - payments-platform
+receives:
+  - id: payment-succeeded
+    version: 1.0.0
+  - id: payment-failed
+    version: 1.0.0
+sends:
+  - id: payment-requested
+    version: 1.0.0
+  - id: refund-requested
+    version: 1.0.0
+writesTo:
+  - id: payment-database
+readsFrom:
+  - id: payment-database
+repository:
+  language: Go
+  url: 'https://github.com/acme/payment-worker'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Payment Worker** drives money movement. It requests charges from the external [[system|stripe]] via [[event|payment-requested]] and refunds via [[event|refund-requested]], then consumes the [[event|payment-succeeded]] and [[event|payment-failed]] events Stripe returns and records the outcome in the [[container|payment-database]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Payment and refund requests"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Payment outcomes from Stripe"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area        | Description                                                                         |
+| ----------- | ----------------------------------------------------------------------------------- |
+| Charging    | Requests charges via [[event\|payment-requested]].                                  |
+| Refunds     | Requests refunds via [[event\|refund-requested]].                                   |
+| Outcomes    | Consumes [[event\|payment-succeeded]] / [[event\|payment-failed]] and records them. |
+| Persistence | Reads from and writes to the [[container\|payment-database]].                       |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/index.mdx
new file mode 100644
index 000000000..b9ada3857
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/index.mdx
@@ -0,0 +1,52 @@
+---
+id: stripe
+name: Stripe
+version: 1.0.0
+scope: external
+summary: |
+  External payment processor used by Acme Inc to charge cards and issue refunds. It receives payment and refund requests and reports outcomes back via webhook events.
+owners:
+  - payments-platform
+services:
+  - id: stripe-payments-api
+  - id: stripe-webhook-endpoint
+relationships:
+  - id: payment-processing-system
+    label: processes payments for
+badges:
+  - content: External
+    backgroundColor: yellow
+    textColor: yellow
+    icon: GlobeAltIcon
+---
+
+## Overview
+
+[Stripe](https://stripe.com) is the external payment processor Acme Inc uses to charge customer cards and issue refunds. It is owned and operated by Stripe — modelled here as an **external system** so the catalog shows how the [[system|payment-processing-system]] integrates with it.
+
+Stripe receives [[event|payment-requested]] and [[event|refund-requested]], and reports outcomes back via [[event|payment-succeeded]], [[event|payment-failed]] and [[event|refund-processed]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                            | Type    | Responsibility                                                           |
+| ------------------------------------ | ------- | ------------------------------------------------------------------------ |
+| [[service\|stripe-payments-api]]     | Service | Accepts charge and refund requests and processes them.                   |
+| [[service\|stripe-webhook-endpoint]] | Service | Delivers payment and refund outcomes back to Acme Inc as webhook events. |
+
+## Messages this system publishes
+
+- [[event\|payment-succeeded]] — a charge succeeded.
+- [[event\|payment-failed]] — a charge failed.
+- [[event\|refund-processed]] — a refund was processed.
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripePaymentsAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripePaymentsAPI/index.mdx
new file mode 100644
index 000000000..a138c6c15
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripePaymentsAPI/index.mdx
@@ -0,0 +1,42 @@
+---
+id: stripe-payments-api
+version: 1.0.0
+name: Payments API
+summary: |
+  Stripe's API for charging cards and issuing refunds. Acme Inc's Payment Processing System calls it to request payments and refunds.
+styles:
+  icon: /icons/payments/stripe.svg
+owners:
+  - payments-platform
+receives:
+  - id: payment-requested
+    version: 1.0.0
+  - id: refund-requested
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/stripe/stripe-node'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Payments API** is Stripe's external interface for charging cards and issuing refunds. The [[system|payment-processing-system]] sends [[event|payment-requested]] and [[event|refund-requested]], and Stripe processes them and reports the outcome back through its [[service|stripe-webhook-endpoint]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Payment and refund requests"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/index.mdx
new file mode 100644
index 000000000..5dfbcb287
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/index.mdx
@@ -0,0 +1,29 @@
+---
+id: payment-failed
+name: Payment Failed
+version: 1.0.0
+summary: |
+  Published by Stripe when a charge fails.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`PaymentFailed` is delivered by Stripe's [[service|stripe-webhook-endpoint]] when a requested charge fails — for example a declined card. The [[service|payment-worker]] consumes it and records the payment as failed, which ultimately leads the order to be cancelled.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/schema.json b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/schema.json
new file mode 100644
index 000000000..fd0e83885
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/schema.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PaymentFailed",
+  "description": "Published when a charge fails",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "reason": {
+      "type": "string",
+      "enum": ["CARD_DECLINED", "INSUFFICIENT_FUNDS", "EXPIRED_CARD", "PROCESSING_ERROR"]
+    },
+    "failedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "reason", "failedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/index.mdx
new file mode 100644
index 000000000..ed59c5311
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/index.mdx
@@ -0,0 +1,29 @@
+---
+id: payment-succeeded
+name: Payment Succeeded
+version: 1.0.0
+summary: |
+  Published by Stripe when a charge succeeds.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`PaymentSucceeded` is delivered by Stripe's [[service|stripe-webhook-endpoint]] when a requested charge succeeds. The [[service|payment-worker]] consumes it and records the payment as succeeded.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/schema.json b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/schema.json
new file mode 100644
index 000000000..91755e4b3
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/schema.json
@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PaymentSucceeded",
+  "description": "Published when a charge succeeds",
+  "type": "object",
+  "properties": {
+    "paymentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "amount": { "type": "integer", "description": "Amount charged, in minor units (e.g. cents)" },
+    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+    "processorReference": { "type": "string", "description": "Stripe's charge identifier" },
+    "succeededAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["paymentId", "orderId", "amount", "currency", "succeededAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/index.mdx
new file mode 100644
index 000000000..3c9fa3a24
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/index.mdx
@@ -0,0 +1,29 @@
+---
+id: refund-processed
+name: Refund Processed
+version: 1.0.0
+summary: |
+  Published by Stripe when a refund has been processed.
+owners:
+  - payments-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RefundProcessed` is delivered by Stripe's [[service|stripe-webhook-endpoint]] when a requested refund has been processed. The [[service|payment-worker]] consumes it and records the refund as complete.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/schema.json b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/schema.json
new file mode 100644
index 000000000..70e376974
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/RefundProcessed/schema.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RefundProcessed",
+  "description": "Published when a refund has been processed",
+  "type": "object",
+  "properties": {
+    "refundId": { "type": "string", "format": "uuid" },
+    "paymentId": { "type": "string", "format": "uuid" },
+    "amount": { "type": "integer", "description": "Amount refunded, in minor units (e.g. cents)" },
+    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+    "processedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["refundId", "paymentId", "amount", "currency", "processedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/index.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/index.mdx
new file mode 100644
index 000000000..99e964260
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/index.mdx
@@ -0,0 +1,44 @@
+---
+id: stripe-webhook-endpoint
+version: 1.0.0
+name: Webhook Endpoint
+summary: |
+  Stripe's webhook delivery for payment and refund outcomes. It notifies Acme Inc whether a charge succeeded or failed, and when a refund is processed.
+styles:
+  icon: /icons/payments/stripe.svg
+owners:
+  - payments-platform
+sends:
+  - id: payment-succeeded
+    version: 1.0.0
+  - id: payment-failed
+    version: 1.0.0
+  - id: refund-processed
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/stripe/stripe-node'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Webhook Endpoint** is how Stripe reports outcomes back to Acme Inc. After processing a request from the [[service|stripe-payments-api]], it delivers [[event|payment-succeeded]], [[event|payment-failed]] or [[event|refund-processed]] to the [[system|payment-processing-system]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Payment and refund outcomes"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Payments/ubiquitous-language.mdx b/packages/create-eventcatalog/templates/default/domains/Payments/ubiquitous-language.mdx
new file mode 100644
index 000000000..cba7e45e9
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Payments/ubiquitous-language.mdx
@@ -0,0 +1,41 @@
+---
+dictionary:
+  - id: Payment
+    name: Payment
+    summary: 'A charge taken from a customer to pay for an order.'
+    description: |
+      A payment is the central concept of the Payments domain. It is owned by the Payment Processing
+      System, which records every payment's status (REQUESTED, SUCCEEDED or FAILED). The actual money
+      movement happens at the external payment processor.
+    icon: CreditCard
+  - id: Authorization
+    name: Authorization
+    summary: "A hold placed on a customer's payment method, confirming funds are available before capture."
+    icon: ShieldCheck
+  - id: Capture
+    name: Capture
+    summary: 'Taking the held funds from an authorized payment — turning an authorization into an actual charge.'
+    icon: Banknote
+  - id: Refund
+    name: Refund
+    summary: 'Returning money to a customer for a previous payment, in full or in part.'
+    icon: Undo2
+  - id: Payment Processor
+    name: Payment Processor
+    summary: "The external provider (Stripe) that charges cards and issues refunds on Acme Inc's behalf."
+    description: |
+      The payment processor is a third party. Acme Inc never stores raw card details — it delegates
+      the actual charge and refund to the processor and reacts to the outcomes it reports back.
+    icon: Building2
+  - id: Fraud Screening
+    name: Fraud Screening
+    summary: 'Checking a payment for signs of fraud before allowing the charge to proceed.'
+    description: |
+      Fraud screening is performed by an external Fraud Detection provider. It returns a verdict —
+      passed or failed — that determines whether a payment is allowed or blocked.
+    icon: ShieldAlert
+  - id: Webhook
+    name: Webhook
+    summary: 'A callback the payment processor sends to report the outcome of a charge or refund.'
+    icon: Webhook
+---
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/asyncapi.yml b/packages/create-eventcatalog/templates/default/domains/Reviews/asyncapi.yml
new file mode 100644
index 000000000..b85d9b379
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/asyncapi.yml
@@ -0,0 +1,181 @@
+asyncapi: 3.0.0
+
+info:
+  title: Review Moderation Worker
+  version: 1.0.0
+  description: |
+    The event-driven interface of the Review Moderation Worker.
+
+    The worker consumes submitted and flagged reviews, screens them for spam, abuse
+    and policy violations, and publishes the outcome (published or rejected).
+  contact:
+    name: Reviews Platform
+    email: reviews-platform@acme.test
+
+defaultContentType: application/json
+
+servers:
+  production:
+    host: broker.acme.test:9092
+    protocol: kafka
+    description: Production Kafka cluster.
+
+channels:
+  reviewIntake:
+    address: reviews.intake
+    title: Reviews to moderate
+    description: Reviews that need screening — newly submitted or flagged for re-moderation.
+    messages:
+      ReviewSubmitted:
+        $ref: '#/components/messages/ReviewSubmitted'
+      ReviewFlagged:
+        $ref: '#/components/messages/ReviewFlagged'
+
+  reviewOutcomes:
+    address: reviews.outcomes
+    title: Moderation outcomes
+    description: The decisions the worker publishes after screening a review.
+    messages:
+      ReviewPublished:
+        $ref: '#/components/messages/ReviewPublished'
+      ReviewRejected:
+        $ref: '#/components/messages/ReviewRejected'
+
+operations:
+  receiveReviewSubmitted:
+    action: receive
+    title: Review Submitted
+    summary: Screen a newly submitted review.
+    channel:
+      $ref: '#/channels/reviewIntake'
+    messages:
+      - $ref: '#/channels/reviewIntake/messages/ReviewSubmitted'
+
+  receiveReviewFlagged:
+    action: receive
+    title: Review Flagged
+    summary: Re-screen a previously published review that has been flagged.
+    channel:
+      $ref: '#/channels/reviewIntake'
+    messages:
+      - $ref: '#/channels/reviewIntake/messages/ReviewFlagged'
+
+  publishReviewPublished:
+    action: send
+    title: Review Published
+    summary: Published when a review passes moderation.
+    channel:
+      $ref: '#/channels/reviewOutcomes'
+    messages:
+      - $ref: '#/channels/reviewOutcomes/messages/ReviewPublished'
+
+  publishReviewRejected:
+    action: send
+    title: Review Rejected
+    summary: Published when a review fails moderation.
+    channel:
+      $ref: '#/channels/reviewOutcomes'
+    messages:
+      - $ref: '#/channels/reviewOutcomes/messages/ReviewRejected'
+
+components:
+  messages:
+    ReviewSubmitted:
+      name: ReviewSubmitted
+      title: Review Submitted
+      summary: A customer submitted a review; it awaits moderation.
+      payload:
+        $ref: '#/components/schemas/ReviewSubmitted'
+    ReviewFlagged:
+      name: ReviewFlagged
+      title: Review Flagged
+      summary: A published review was flagged and needs re-screening.
+      payload:
+        $ref: '#/components/schemas/ReviewFlagged'
+    ReviewPublished:
+      name: ReviewPublished
+      title: Review Published
+      summary: A review passed moderation and is visible on the storefront.
+      payload:
+        $ref: '#/components/schemas/ReviewPublished'
+    ReviewRejected:
+      name: ReviewRejected
+      title: Review Rejected
+      summary: A review failed moderation and will not be shown.
+      payload:
+        $ref: '#/components/schemas/ReviewRejected'
+
+  schemas:
+    ReviewSubmitted:
+      type: object
+      properties:
+        reviewId:
+          type: string
+          format: uuid
+        productId:
+          type: string
+        customerId:
+          type: string
+        rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        title:
+          type: string
+        body:
+          type: string
+        submittedAt:
+          type: string
+          format: date-time
+      required: [reviewId, productId, customerId, rating, submittedAt]
+    ReviewFlagged:
+      type: object
+      properties:
+        reviewId:
+          type: string
+          format: uuid
+        productId:
+          type: string
+        reason:
+          type: string
+          enum: [spam, abuse, off_topic, inappropriate, other]
+        flagCount:
+          type: integer
+          minimum: 1
+        flaggedAt:
+          type: string
+          format: date-time
+      required: [reviewId, productId, reason, flaggedAt]
+    ReviewPublished:
+      type: object
+      properties:
+        reviewId:
+          type: string
+          format: uuid
+        productId:
+          type: string
+        customerId:
+          type: string
+        rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        publishedAt:
+          type: string
+          format: date-time
+      required: [reviewId, productId, rating, publishedAt]
+    ReviewRejected:
+      type: object
+      properties:
+        reviewId:
+          type: string
+          format: uuid
+        productId:
+          type: string
+        reason:
+          type: string
+          enum: [spam, abuse, off_topic, policy_violation]
+        rejectedAt:
+          type: string
+          format: date-time
+      required: [reviewId, productId, reason, rejectedAt]
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/containers/rating-cache/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/containers/rating-cache/index.mdx
new file mode 100644
index 000000000..d52dc76ed
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/containers/rating-cache/index.mdx
@@ -0,0 +1,29 @@
+---
+id: rating-cache
+name: Rating Cache
+version: 1.0.0
+summary: Redis cache that serves each product's aggregate star rating with low latency.
+container_type: cache
+technology: redis@7
+authoritative: false
+access_mode: readWrite
+purpose: Fast read store for aggregate product ratings
+classification: internal
+retention: transient
+residency: eu-west-1
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Rating Cache** holds the aggregate rating (average score and review count) for each product. It is a derived read model — never a source of truth — so it can be rebuilt at any time by replaying published reviews.
+
+### What does it store?
+
+- **Aggregate rating** — one entry per product: average rating, review count and last-updated timestamp.
+
+### Access patterns
+
+- The [[service|rating-aggregator]] writes the aggregate rating whenever a review is published.
+- The [[service|review-api]] reads it to serve [[query|get-product-reviews]].
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/containers/review-database/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/containers/review-database/index.mdx
new file mode 100644
index 000000000..6b61a44ac
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/containers/review-database/index.mdx
@@ -0,0 +1,33 @@
+---
+id: review-database
+name: Review Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for reviews and their moderation state.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for reviews, ratings and moderation decisions
+classification: internal
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Review Database** is the authoritative store for every review in the Reviews & Ratings domain. The [[service|review-api]] writes new reviews to it, and the [[service|review-moderation-worker]] records each moderation decision against the stored review.
+
+### What does it store?
+
+- **Reviews** — one row per review: product, customer, rating, title, body and lifecycle status (`submitted`, `published`, `rejected`).
+- **Moderation decisions** — the outcome and reason for each moderated review, kept for audit.
+
+### Access patterns
+
+- The [[service|review-api]] writes new reviews and reads published reviews.
+- The [[service|review-moderation-worker]] reads submitted reviews and writes moderation outcomes.
+- The [[service|rating-aggregator]] reads published reviews to recompute aggregates.
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/entities/moderation-decision/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/entities/moderation-decision/index.mdx
new file mode 100644
index 000000000..610f9a0f4
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/entities/moderation-decision/index.mdx
@@ -0,0 +1,38 @@
+---
+id: moderation-decision
+name: Moderation Decision
+version: 1.0.0
+identifier: moderationDecisionId
+summary: The outcome of reviewing submitted customer feedback.
+owners:
+  - reviews-platform
+properties:
+  - name: moderationDecisionId
+    type: UUID
+    required: true
+    description: Unique moderation decision identifier.
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Review being moderated.
+    references: review
+    relationType: decides
+    referencesIdentifier: reviewId
+  - name: outcome
+    type: string
+    required: true
+    description: Moderation result.
+    enum:
+      - published
+      - rejected
+  - name: decidedAt
+    type: datetime
+    required: true
+    description: Time the decision was made.
+---
+
+## Overview
+
+Moderation Decision records why a review became published or rejected and supports audit of [[service|review-moderation-worker]] behavior.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/entities/rating-summary/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/entities/rating-summary/index.mdx
new file mode 100644
index 000000000..40871dcf4
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/entities/rating-summary/index.mdx
@@ -0,0 +1,35 @@
+---
+id: rating-summary
+name: Rating Summary
+version: 1.0.0
+identifier: productId
+summary: Aggregated review statistics for a product.
+owners:
+  - reviews-platform
+properties:
+  - name: productId
+    type: UUID
+    required: true
+    description: Product being summarized.
+    references: product
+    relationType: summarizes
+    referencesIdentifier: productId
+  - name: averageRating
+    type: decimal
+    required: true
+    description: Average published rating.
+  - name: reviewCount
+    type: integer
+    required: true
+    description: Number of published reviews.
+  - name: updatedAt
+    type: datetime
+    required: true
+    description: Time the summary was recalculated.
+---
+
+## Overview
+
+Rating Summary is the read model maintained by [[service|rating-aggregator]] and stored in [[container|rating-cache]].
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/entities/review-flag/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/entities/review-flag/index.mdx
new file mode 100644
index 000000000..bff385fd4
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/entities/review-flag/index.mdx
@@ -0,0 +1,35 @@
+---
+id: review-flag
+name: Review Flag
+version: 1.0.0
+identifier: flagId
+summary: A customer report that a review may violate policy.
+owners:
+  - reviews-platform
+properties:
+  - name: flagId
+    type: UUID
+    required: true
+    description: Unique review flag identifier.
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Review being reported.
+    references: review
+    relationType: flags
+    referencesIdentifier: reviewId
+  - name: reason
+    type: string
+    required: true
+    description: Reason selected by the customer.
+  - name: flaggedAt
+    type: datetime
+    required: true
+    description: Time the review was flagged.
+---
+
+## Overview
+
+Review Flag captures [[command|flag-review]] interactions and can send a published review back through moderation.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/entities/review-vote/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/entities/review-vote/index.mdx
new file mode 100644
index 000000000..f9cd217f7
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/entities/review-vote/index.mdx
@@ -0,0 +1,38 @@
+---
+id: review-vote
+name: Review Vote
+version: 1.0.0
+identifier: voteId
+summary: A customer's helpfulness vote on a product review.
+owners:
+  - reviews-platform
+properties:
+  - name: voteId
+    type: UUID
+    required: true
+    description: Unique review vote identifier.
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Review being voted on.
+    references: review
+    relationType: votesOn
+    referencesIdentifier: reviewId
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer who voted.
+    references: customer-profile
+    relationType: submittedBy
+    referencesIdentifier: customerId
+  - name: votedAt
+    type: datetime
+    required: true
+    description: Time the vote was submitted.
+---
+
+## Overview
+
+Review Vote captures [[command|vote-review-helpful]] interactions and contributes to review helpfulness ranking.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/entities/review/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/entities/review/index.mdx
new file mode 100644
index 000000000..d9872f4fc
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/entities/review/index.mdx
@@ -0,0 +1,63 @@
+---
+id: review
+name: Review
+version: 1.0.0
+identifier: reviewId
+aggregateRoot: true
+summary: A customer's review and rating of a product, including its moderation lifecycle.
+owners:
+  - reviews-platform
+properties:
+  - name: reviewId
+    type: UUID
+    required: true
+    description: Unique identifier for the review.
+  - name: productId
+    type: string
+    required: true
+    description: The product being reviewed.
+    references: product
+    relationType: reviews
+    referencesIdentifier: productId
+  - name: customerId
+    type: string
+    required: true
+    description: The customer who wrote the review.
+    references: customer-profile
+    relationType: writtenBy
+    referencesIdentifier: customerId
+  - name: rating
+    type: integer
+    required: true
+    description: Star rating from 1 to 5.
+  - name: title
+    type: string
+    required: false
+    description: Short headline for the review.
+  - name: body
+    type: string
+    required: true
+    description: The review text.
+  - name: status
+    type: string
+    required: true
+    description: Lifecycle status of the review.
+    enum:
+      - submitted
+      - published
+      - rejected
+  - name: submittedAt
+    type: datetime
+    required: true
+    description: When the review was submitted.
+---
+
+## Overview
+
+The **Review** is the core aggregate of the Reviews & Ratings domain. It captures a customer's rating and written feedback for a product, along with the moderation `status` that controls whether it is visible on the storefront.
+
+A review moves through three states:
+
+1. **submitted** — stored by the [[service|review-api]], awaiting moderation.
+2. **published** — passed moderation and visible (the [[service|rating-aggregator]] folds it into the product's rating).
+3. **rejected** — failed moderation and never shown, but kept for audit.
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/flows/review-submission/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/flows/review-submission/index.mdx
new file mode 100644
index 000000000..f6797dd1a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/flows/review-submission/index.mdx
@@ -0,0 +1,120 @@
+---
+id: review-submission
+name: Review Submission
+version: 1.0.0
+summary: |
+  How a customer's product review travels from submission, through moderation, to being published and folded into the product's aggregate rating.
+owners:
+  - reviews-platform
+steps:
+  - id: customer_submits
+    title: Customer submits a review
+    actor:
+      name: Customer
+      summary: A customer writes a review and rating for a product they purchased.
+    next_step:
+      id: review_api
+      label: Submit review
+
+  - id: review_api
+    title: Review API
+    service:
+      id: review-api
+      version: 1.0.0
+    next_step:
+      id: review_database
+      label: Store review
+
+  - id: review_database
+    title: Review Database
+    container:
+      id: review-database
+    next_step:
+      id: review_submitted
+      label: Review stored
+
+  - id: review_submitted
+    title: Review Submitted
+    message:
+      id: review-submitted
+      version: 1.0.0
+    next_step:
+      id: moderation_worker
+      label: Screen review
+
+  - id: moderation_worker
+    title: Review Moderation Worker
+    service:
+      id: review-moderation-worker
+      version: 1.0.0
+    next_steps:
+      - id: review_published
+        label: Approved
+      - id: review_rejected
+        label: Rejected
+
+  - id: review_published
+    title: Review Published
+    message:
+      id: review-published
+      version: 1.0.0
+    next_step:
+      id: rating_aggregator
+      label: Update rating
+
+  - id: review_rejected
+    title: Review Rejected
+    message:
+      id: review-rejected
+      version: 1.0.0
+    next_step:
+      id: rejected_outcome
+      label: Not shown
+
+  - id: rating_aggregator
+    title: Rating Aggregator
+    service:
+      id: rating-aggregator
+      version: 1.0.0
+    next_step:
+      id: rating_cache
+      label: Write aggregate
+
+  - id: rating_cache
+    title: Rating Cache
+    container:
+      id: rating-cache
+    next_step:
+      id: published_outcome
+      label: Visible on storefront
+
+  - id: published_outcome
+    title: Review is live
+    custom:
+      title: Review is live
+      color: green
+      icon: StarIcon
+      type: Outcome
+      summary: The review is published and the product's aggregate rating is updated and served from the cache.
+
+  - id: rejected_outcome
+    title: Review rejected
+    custom:
+      title: Review rejected
+      color: red
+      icon: NoSymbolIcon
+      type: Outcome
+      summary: The review failed moderation. It is kept for audit but never shown on the storefront.
+---
+
+## Overview
+
+**Review Submission** documents the journey of a customer review from submission through moderation to publication. A review is only ever folded into a product's rating once it has been approved.
+
+<NodeGraph />
+
+## How it works
+
+1. A customer submits a review via the [[service|review-api]], which stores it in the [[container|review-database]] and publishes [[event|review-submitted]].
+2. The [[service|review-moderation-worker]] screens the review and publishes either [[event|review-published]] or [[event|review-rejected]].
+3. On approval, the [[service|rating-aggregator]] updates the product's aggregate rating in the [[container|rating-cache]] and the review goes live.
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/index.mdx
new file mode 100644
index 000000000..75ce5bd48
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/index.mdx
@@ -0,0 +1,93 @@
+---
+id: reviews
+name: Reviews & Ratings
+version: 1.0.0
+summary: |
+  The Reviews & Ratings domain owns customer feedback on products — how reviews are submitted, moderated, published and aggregated into the star ratings shown across the storefront.
+owners:
+  - reviews-platform
+services:
+  - id: review-api
+    version: 1.0.0
+  - id: review-moderation-worker
+    version: 1.0.0
+  - id: rating-aggregator
+    version: 1.0.0
+entities:
+  - id: review
+    version: 1.0.0
+  - id: moderation-decision
+    version: 1.0.0
+  - id: rating-summary
+    version: 1.0.0
+  - id: review-vote
+    version: 1.0.0
+  - id: review-flag
+    version: 1.0.0
+flows:
+  - id: review-submission
+    version: 1.0.0
+receives:
+  - id: submit-review
+    version: 1.0.0
+  - id: flag-review
+    version: 1.0.0
+  - id: vote-review-helpful
+    version: 1.0.0
+  - id: get-product-reviews
+    version: 1.0.0
+sends:
+  - id: review-submitted
+    version: 1.0.0
+  - id: review-published
+    version: 1.0.0
+  - id: review-rejected
+    version: 1.0.0
+  - id: review-flagged
+    version: 1.0.0
+  - id: review-helpful-voted
+    version: 1.0.0
+  - id: rating-updated
+    version: 1.0.0
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Review API
+  - type: asyncapi
+    path: asyncapi.yml
+    name: Reviews Eventing
+badges:
+  - content: Supporting domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+---
+
+## Overview
+
+The **Reviews & Ratings** domain is responsible for everything to do with customer feedback on products: accepting reviews, moderating them for quality and abuse, publishing the approved ones, and aggregating them into the star ratings shown across the storefront.
+
+Unlike most other domains in the catalog, Reviews & Ratings is modelled **without systems** — its services, data stores and flows hang directly off the domain.
+
+### What's inside
+
+| Component                             | Type       | Responsibility                                                          |
+| ------------------------------------- | ---------- | ----------------------------------------------------------------------- |
+| [[service\|review-api]]               | Service    | Accepts review submissions and serves product reviews.                  |
+| [[service\|review-moderation-worker]] | Service    | Screens submitted reviews and publishes or rejects them.                |
+| [[service\|rating-aggregator]]        | Service    | Keeps each product's aggregate rating in sync as reviews are published. |
+| [[container\|review-database]]        | Data Store | System of record for reviews and their moderation state.                |
+| [[container\|rating-cache]]           | Data Store | Fast read store for aggregate product ratings.                          |
+| [[entity\|review]]                    | Entity     | The core review aggregate.                                              |
+
+The diagram below shows the services, data stores and messages that make up this domain.
+
+<NodeGraph />
+
+## How it works
+
+1. A customer submits a review via the [[service\|review-api]], which stores it and publishes [[event\|review-submitted]].
+2. The [[service\|review-moderation-worker]] screens the review and publishes either [[event\|review-published]] or [[event\|review-rejected]].
+3. The [[service\|rating-aggregator]] consumes [[event\|review-published]] and updates the product's aggregate rating, publishing [[event\|rating-updated]].
+
+Once a review is live, customers can interact with it: [[command\|vote-review-helpful]] updates its helpful count (publishing [[event\|review-helpful-voted]]), and [[command\|flag-review]] reports it for re-moderation (publishing [[event\|review-flagged]], which the [[service\|review-moderation-worker]] re-screens).
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/openapi.yml b/packages/create-eventcatalog/templates/default/domains/Reviews/openapi.yml
new file mode 100644
index 000000000..4f1046a66
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/openapi.yml
@@ -0,0 +1,209 @@
+openapi: 3.0.3
+info:
+  title: Review API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Reviews & Ratings domain. It is the entry point for
+    submitting reviews, flagging reviews, voting reviews helpful, and reading the
+    published reviews and aggregate rating for a product.
+  contact:
+    name: Reviews Platform
+    email: reviews-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+tags:
+  - name: Reviews
+    description: Submit, read and interact with product reviews.
+paths:
+  /products/{productId}/reviews:
+    get:
+      operationId: getProductReviews
+      summary: Get product reviews
+      description: Returns the published reviews and aggregate rating for a product.
+      tags:
+        - Reviews
+      parameters:
+        - name: productId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: page
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - name: pageSize
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+        - name: sort
+          in: query
+          schema:
+            type: string
+            enum: [newest, highest, lowest, most_helpful]
+            default: newest
+      responses:
+        '200':
+          description: The published reviews and aggregate rating for the product.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProductReviews'
+    post:
+      operationId: submitReview
+      summary: Submit a review
+      description: Submits a review for a product. On success a `ReviewSubmitted` event is published and the review awaits moderation.
+      tags:
+        - Reviews
+      parameters:
+        - name: productId
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SubmitReviewRequest'
+      responses:
+        '202':
+          description: The review was accepted and is awaiting moderation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Review'
+        '400':
+          description: The request was invalid.
+  /reviews/{reviewId}/flags:
+    post:
+      operationId: flagReview
+      summary: Flag a review
+      description: Flags a published review for re-moderation. On success a `ReviewFlagged` event is published.
+      tags:
+        - Reviews
+      parameters:
+        - name: reviewId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FlagReviewRequest'
+      responses:
+        '202':
+          description: The flag was recorded.
+  /reviews/{reviewId}/helpful:
+    post:
+      operationId: voteReviewHelpful
+      summary: Vote a review helpful
+      description: Marks a review as helpful (or removes the vote). On success a `ReviewHelpfulVoted` event is published.
+      tags:
+        - Reviews
+      parameters:
+        - name: reviewId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VoteReviewHelpfulRequest'
+      responses:
+        '200':
+          description: The helpful count was updated.
+components:
+  schemas:
+    Review:
+      type: object
+      properties:
+        reviewId:
+          type: string
+          format: uuid
+        productId:
+          type: string
+        customerId:
+          type: string
+        rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        title:
+          type: string
+        body:
+          type: string
+        status:
+          type: string
+          enum: [submitted, published, rejected]
+        helpfulCount:
+          type: integer
+          minimum: 0
+        submittedAt:
+          type: string
+          format: date-time
+    ProductReviews:
+      type: object
+      properties:
+        productId:
+          type: string
+        averageRating:
+          type: number
+          minimum: 0
+          maximum: 5
+        reviewCount:
+          type: integer
+          minimum: 0
+        reviews:
+          type: array
+          items:
+            $ref: '#/components/schemas/Review'
+    SubmitReviewRequest:
+      type: object
+      required: [customerId, rating, body]
+      properties:
+        customerId:
+          type: string
+        rating:
+          type: integer
+          minimum: 1
+          maximum: 5
+        title:
+          type: string
+        body:
+          type: string
+    FlagReviewRequest:
+      type: object
+      required: [flaggedBy, reason]
+      properties:
+        flaggedBy:
+          type: string
+        reason:
+          type: string
+          enum: [spam, abuse, off_topic, inappropriate, other]
+        notes:
+          type: string
+    VoteReviewHelpfulRequest:
+      type: object
+      required: [customerId, vote]
+      properties:
+        customerId:
+          type: string
+        vote:
+          type: string
+          enum: [helpful, remove]
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/RatingAggregator/events/rating-updated/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/RatingAggregator/events/rating-updated/index.mdx
new file mode 100644
index 000000000..22feb3771
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/RatingAggregator/events/rating-updated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: rating-updated
+name: Rating Updated
+version: 1.0.0
+summary: |
+  Published when a product's aggregate rating changes as a result of a newly published review.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RatingUpdated` is published by the [[service|rating-aggregator]] whenever a product's aggregate rating changes. Other domains (such as the storefront and search) can consume it to keep displayed ratings fresh.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/RatingAggregator/events/rating-updated/schema.json b/packages/create-eventcatalog/templates/default/domains/Reviews/services/RatingAggregator/events/rating-updated/schema.json
new file mode 100644
index 000000000..27ce8dfbf
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/RatingAggregator/events/rating-updated/schema.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RatingUpdated",
+  "type": "object",
+  "properties": {
+    "productId": { "type": "string" },
+    "averageRating": { "type": "number", "minimum": 0, "maximum": 5 },
+    "reviewCount": { "type": "integer", "minimum": 0 },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["productId", "averageRating", "reviewCount", "updatedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/RatingAggregator/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/RatingAggregator/index.mdx
new file mode 100644
index 000000000..53148f66b
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/RatingAggregator/index.mdx
@@ -0,0 +1,47 @@
+---
+id: rating-aggregator
+version: 1.0.0
+name: Rating Aggregator
+summary: |
+  Keeps each product's aggregate star rating up to date as reviews are published, and serves it fast from a cache.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - reviews-platform
+receives:
+  - id: review-published
+    version: 1.0.0
+sends:
+  - id: rating-updated
+    version: 1.0.0
+writesTo:
+  - id: rating-cache
+readsFrom:
+  - id: review-database
+  - id: rating-cache
+repository:
+  language: Go
+  url: 'https://github.com/acme/rating-aggregator'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Rating Aggregator** consumes [[event|review-published]] and recomputes the affected product's aggregate rating (average score and review count). It writes the result to the [[container|rating-cache]] for fast reads and publishes [[event|rating-updated]] so other domains can stay in sync.
+
+### Responsibilities
+
+| Area        | Description                                                  |
+| ----------- | ------------------------------------------------------------ |
+| Aggregation | Recomputes average rating and review count per product.      |
+| Caching     | Writes aggregate ratings to the [[container\|rating-cache]]. |
+| Eventing    | Publishes [[event\|rating-updated]] on every change.         |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/flag-review/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/flag-review/index.mdx
new file mode 100644
index 000000000..74d1fbcef
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/flag-review/index.mdx
@@ -0,0 +1,29 @@
+---
+id: flag-review
+name: Flag Review
+version: 1.0.0
+summary: |
+  Command issued by a customer or moderator to flag a published review for re-moderation.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`FlagReview` is sent to the [[service|review-api]] when someone reports a published review as inappropriate. The API records the flag and publishes [[event|review-flagged]] so the review can be screened again.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/flag-review/schema.json b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/flag-review/schema.json
new file mode 100644
index 000000000..488407d6d
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/flag-review/schema.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FlagReview",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "flaggedBy": { "type": "string", "description": "Customer or moderator id raising the flag." },
+    "reason": { "type": "string", "enum": ["spam", "abuse", "off_topic", "inappropriate", "other"] },
+    "notes": { "type": "string", "maxLength": 1000 },
+    "flaggedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "flaggedBy", "reason", "flaggedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/submit-review/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/submit-review/index.mdx
new file mode 100644
index 000000000..965b0f4f6
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/submit-review/index.mdx
@@ -0,0 +1,29 @@
+---
+id: submit-review
+name: Submit Review
+version: 1.0.0
+summary: |
+  Command issued by a customer to submit a review and rating for a product.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`SubmitReview` is sent to the [[service|review-api]] when a customer submits a review for a product they have purchased. The API validates and stores the review, then publishes [[event|review-submitted]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/submit-review/schema.json b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/submit-review/schema.json
new file mode 100644
index 000000000..8b360e06f
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/submit-review/schema.json
@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SubmitReview",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid", "description": "Client-generated id for the review." },
+    "productId": { "type": "string", "description": "The product being reviewed." },
+    "customerId": { "type": "string", "description": "The customer submitting the review." },
+    "rating": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Star rating from 1 to 5." },
+    "title": { "type": "string", "maxLength": 120 },
+    "body": { "type": "string", "maxLength": 5000 },
+    "submittedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "customerId", "rating", "body", "submittedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/index.mdx
new file mode 100644
index 000000000..9ce8ca853
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/index.mdx
@@ -0,0 +1,29 @@
+---
+id: vote-review-helpful
+name: Vote Review Helpful
+version: 1.0.0
+summary: |
+  Command issued by a customer to mark a published review as helpful (or remove their vote).
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`VoteReviewHelpful` is sent to the [[service|review-api]] when a customer marks a review as helpful. The API updates the helpful count and publishes [[event|review-helpful-voted]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/schema.json b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/schema.json
new file mode 100644
index 000000000..9707f3d6b
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/commands/vote-review-helpful/schema.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "VoteReviewHelpful",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "customerId": { "type": "string" },
+    "vote": { "type": "string", "enum": ["helpful", "remove"], "description": "Add a helpful vote or remove an existing one." },
+    "votedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "customerId", "vote", "votedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-flagged/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-flagged/index.mdx
new file mode 100644
index 000000000..e009c522d
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-flagged/index.mdx
@@ -0,0 +1,29 @@
+---
+id: review-flagged
+name: Review Flagged
+version: 1.0.0
+summary: |
+  Published when a published review is flagged and needs to be screened again.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReviewFlagged` is published by the [[service|review-api]] when a published review is flagged. The [[service|review-moderation-worker]] consumes it and re-screens the review, which may lead to it being rejected.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-flagged/schema.json b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-flagged/schema.json
new file mode 100644
index 000000000..b38a182b0
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-flagged/schema.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewFlagged",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "productId": { "type": "string" },
+    "reason": { "type": "string", "enum": ["spam", "abuse", "off_topic", "inappropriate", "other"] },
+    "flagCount": { "type": "integer", "minimum": 1, "description": "Total flags this review has now received." },
+    "flaggedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "reason", "flaggedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-helpful-voted/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-helpful-voted/index.mdx
new file mode 100644
index 000000000..7eef3fa54
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-helpful-voted/index.mdx
@@ -0,0 +1,29 @@
+---
+id: review-helpful-voted
+name: Review Helpful Voted
+version: 1.0.0
+summary: |
+  Published when a review's helpful count changes as a result of a customer vote.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReviewHelpfulVoted` is published by the [[service|review-api]] whenever a review's helpful count changes. It lets other surfaces (such as the storefront) keep "most helpful" ordering fresh.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-helpful-voted/schema.json b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-helpful-voted/schema.json
new file mode 100644
index 000000000..b8e2413ce
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-helpful-voted/schema.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewHelpfulVoted",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "productId": { "type": "string" },
+    "helpfulCount": { "type": "integer", "minimum": 0 },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "helpfulCount", "updatedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-submitted/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-submitted/index.mdx
new file mode 100644
index 000000000..ac2dfabd5
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-submitted/index.mdx
@@ -0,0 +1,29 @@
+---
+id: review-submitted
+name: Review Submitted
+version: 1.0.0
+summary: |
+  Published when a customer submits a review. The review is stored but not yet visible — it awaits moderation.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReviewSubmitted` is published by the [[service|review-api]] once a review has been accepted and stored. The [[service|review-moderation-worker]] consumes it to screen the review before it can be published.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-submitted/schema.json b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-submitted/schema.json
new file mode 100644
index 000000000..308f882b0
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/events/review-submitted/schema.json
@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewSubmitted",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "productId": { "type": "string" },
+    "customerId": { "type": "string" },
+    "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
+    "title": { "type": "string" },
+    "body": { "type": "string" },
+    "submittedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "customerId", "rating", "submittedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/index.mdx
new file mode 100644
index 000000000..c4f143a24
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/index.mdx
@@ -0,0 +1,58 @@
+---
+id: review-api
+version: 1.0.0
+name: Review API
+summary: |
+  The public-facing API for product reviews. Accepts review submissions, serves published reviews, and is the entry point into the Reviews & Ratings domain.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - reviews-platform
+receives:
+  - id: submit-review
+    version: 1.0.0
+  - id: flag-review
+    version: 1.0.0
+  - id: vote-review-helpful
+    version: 1.0.0
+  - id: get-product-reviews
+    version: 1.0.0
+sends:
+  - id: review-submitted
+    version: 1.0.0
+  - id: review-flagged
+    version: 1.0.0
+  - id: review-helpful-voted
+    version: 1.0.0
+writesTo:
+  - id: review-database
+readsFrom:
+  - id: review-database
+  - id: rating-cache
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/review-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Review API** is the front door to the Reviews & Ratings domain. It validates incoming [[command|submit-review]] commands, persists reviews to the [[container|review-database]], and publishes [[event|review-submitted]]. It also serves [[query|get-product-reviews]], reading published reviews from the [[container|review-database]] and aggregate ratings from the [[container|rating-cache]].
+
+### Responsibilities
+
+| Area             | Description                                                                                                                  |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Command handling | Validates and applies [[command\|submit-review]].                                                                            |
+| Reads            | Serves [[query\|get-product-reviews]] from the review database and rating cache.                                             |
+| Eventing         | Publishes [[event\|review-submitted]] for moderation.                                                                        |
+| Persistence      | Writes to the [[container\|review-database]]; reads from the [[container\|review-database]] and [[container\|rating-cache]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/index.mdx
new file mode 100644
index 000000000..a218643d7
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/index.mdx
@@ -0,0 +1,24 @@
+---
+id: get-product-reviews
+name: Get Product Reviews
+version: 1.0.0
+summary: |
+  Query to fetch the published reviews and aggregate rating for a product.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetProductReviews` is served by the [[service|review-api]]. It returns the published reviews for a product along with its aggregate rating, read from the [[container|review-database]] and the [[container|rating-cache]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/schema.json b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/schema.json
new file mode 100644
index 000000000..a65eb3384
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewAPI/queries/get-product-reviews/schema.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetProductReviews",
+  "type": "object",
+  "properties": {
+    "productId": { "type": "string", "description": "The product to fetch reviews for." },
+    "page": { "type": "integer", "minimum": 1, "default": 1 },
+    "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 },
+    "sort": { "type": "string", "enum": ["newest", "highest", "lowest", "most_helpful"], "default": "newest" }
+  },
+  "required": ["productId"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/index.mdx
new file mode 100644
index 000000000..774093e22
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/index.mdx
@@ -0,0 +1,29 @@
+---
+id: review-published
+name: Review Published
+version: 1.0.0
+summary: |
+  Published when a submitted review passes moderation and becomes visible on the storefront.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReviewPublished` is published by the [[service|review-moderation-worker]] when a review passes moderation. The [[service|rating-aggregator]] consumes it to update the product's aggregate rating.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/schema.json b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/schema.json
new file mode 100644
index 000000000..6420fec00
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-published/schema.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewPublished",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "productId": { "type": "string" },
+    "customerId": { "type": "string" },
+    "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
+    "publishedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "rating", "publishedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/index.mdx
new file mode 100644
index 000000000..1074977a6
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/index.mdx
@@ -0,0 +1,29 @@
+---
+id: review-rejected
+name: Review Rejected
+version: 1.0.0
+summary: |
+  Published when a submitted review fails moderation (spam, abuse or policy violation) and will not be shown.
+owners:
+  - reviews-platform
+schemaPath: schema.json
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReviewRejected` is published by the [[service|review-moderation-worker]] when a review fails moderation. The review is kept for audit but never published to the storefront.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/schema.json b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/schema.json
new file mode 100644
index 000000000..aa777cc49
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/events/review-rejected/schema.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewRejected",
+  "type": "object",
+  "properties": {
+    "reviewId": { "type": "string", "format": "uuid" },
+    "productId": { "type": "string" },
+    "reason": { "type": "string", "enum": ["spam", "abuse", "off_topic", "policy_violation"] },
+    "rejectedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reviewId", "productId", "reason", "rejectedAt"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/index.mdx b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/index.mdx
new file mode 100644
index 000000000..7dda94332
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Reviews/services/ReviewModerationWorker/index.mdx
@@ -0,0 +1,50 @@
+---
+id: review-moderation-worker
+version: 1.0.0
+name: Review Moderation Worker
+summary: |
+  Asynchronous worker that screens submitted reviews for spam, abuse and policy violations, then publishes or rejects them.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - reviews-platform
+receives:
+  - id: review-submitted
+    version: 1.0.0
+  - id: review-flagged
+    version: 1.0.0
+sends:
+  - id: review-published
+    version: 1.0.0
+  - id: review-rejected
+    version: 1.0.0
+writesTo:
+  - id: review-database
+readsFrom:
+  - id: review-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/review-moderation-worker'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Review Moderation Worker** consumes [[event|review-submitted]] (and [[event|review-flagged]] for already-published reviews), screens each review (automated checks plus thresholds for manual review), and records the outcome on the [[container|review-database]]. It then publishes either [[event|review-published]] or [[event|review-rejected]].
+
+### Responsibilities
+
+| Area        | Description                                                            |
+| ----------- | ---------------------------------------------------------------------- |
+| Moderation  | Screens reviews for spam, abuse and policy violations.                 |
+| Outcome     | Publishes [[event\|review-published]] or [[event\|review-rejected]].   |
+| Persistence | Records the moderation decision on the [[container\|review-database]]. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/entities/cart-item/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/entities/cart-item/index.mdx
new file mode 100644
index 000000000..0f6a7b38e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/entities/cart-item/index.mdx
@@ -0,0 +1,38 @@
+---
+id: cart-item
+name: Cart Item
+version: 1.0.0
+identifier: cartItemId
+summary: A product variant and quantity inside a cart.
+owners:
+  - shopping-platform
+properties:
+  - name: cartItemId
+    type: UUID
+    required: true
+    description: Unique cart item identifier.
+  - name: cartId
+    type: UUID
+    required: true
+    description: Cart this item belongs to.
+    references: cart
+    relationType: belongsTo
+    referencesIdentifier: cartId
+  - name: productId
+    type: UUID
+    required: true
+    description: Product selected by the customer.
+    references: product
+    relationType: references
+    referencesIdentifier: productId
+  - name: quantity
+    type: integer
+    required: true
+    description: Quantity requested.
+---
+
+## Overview
+
+Cart Item records the customer's intent to buy a product variant before checkout. It is owned by [[entity|cart]].
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/entities/cart/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/entities/cart/index.mdx
new file mode 100644
index 000000000..bd298f675
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/entities/cart/index.mdx
@@ -0,0 +1,40 @@
+---
+id: cart
+name: Cart
+version: 1.0.0
+identifier: cartId
+aggregateRoot: true
+summary: The customer's active collection of items before an order exists.
+owners:
+  - shopping-platform
+properties:
+  - name: cartId
+    type: UUID
+    required: true
+    description: Unique cart identifier.
+  - name: customerId
+    type: UUID
+    required: false
+    description: Customer that owns the cart, if authenticated.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: status
+    type: string
+    required: true
+    description: Current cart state.
+    enum:
+      - active
+      - checked-out
+      - abandoned
+  - name: updatedAt
+    type: datetime
+    required: true
+    description: Time the cart last changed.
+---
+
+## Overview
+
+Cart is the Shopping domain aggregate. It accepts item changes and emits [[event|cart-checked-out]] when the customer commits to buy.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/entities/discount/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/entities/discount/index.mdx
new file mode 100644
index 000000000..94f68325a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/entities/discount/index.mdx
@@ -0,0 +1,35 @@
+---
+id: discount
+name: Discount
+version: 1.0.0
+identifier: discountId
+summary: The calculated benefit applied to a cart or cart item.
+owners:
+  - shopping-platform
+properties:
+  - name: discountId
+    type: UUID
+    required: true
+    description: Unique discount identifier.
+  - name: promotionId
+    type: UUID
+    required: false
+    description: Promotion that produced the discount.
+    references: promotion
+    relationType: derivedFrom
+    referencesIdentifier: promotionId
+  - name: amount
+    type: decimal
+    required: true
+    description: Monetary value of the discount.
+  - name: reason
+    type: string
+    required: true
+    description: Human-readable explanation for the discount.
+---
+
+## Overview
+
+Discount is a calculated result from [[command|calculate-discount]]. It is separate from cart persistence so promotion logic can evolve independently.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/entities/promotion/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/entities/promotion/index.mdx
new file mode 100644
index 000000000..052c9bf04
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/entities/promotion/index.mdx
@@ -0,0 +1,40 @@
+---
+id: promotion
+name: Promotion
+version: 1.0.0
+identifier: promotionId
+aggregateRoot: true
+summary: A commercial offer evaluated against a cart.
+owners:
+  - shopping-platform
+properties:
+  - name: promotionId
+    type: UUID
+    required: true
+    description: Unique promotion identifier.
+  - name: code
+    type: string
+    required: false
+    description: Optional customer-entered promotion code.
+  - name: categoryId
+    type: UUID
+    required: false
+    description: Category the promotion applies to when scoped.
+    references: category
+    relationType: appliesTo
+    referencesIdentifier: categoryId
+  - name: status
+    type: string
+    required: true
+    description: Promotion lifecycle state.
+  - name: startsAt
+    type: datetime
+    required: true
+    description: When the promotion becomes active.
+---
+
+## Overview
+
+Promotion is owned by the Promotion System and is evaluated when Shopping calculates discounts for a cart.
+
+<EntityPropertiesTable />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/index.mdx
new file mode 100644
index 000000000..83673c9b0
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/index.mdx
@@ -0,0 +1,67 @@
+---
+id: shopping
+name: Shopping
+version: 1.0.0
+summary: |
+  The Shopping domain owns the customer's path to purchase — building a cart, applying promotions, and checking out. It coordinates the cart and the discounts that apply to it.
+owners:
+  - shopping-platform
+systems:
+  - id: cart-system
+    version: 1.0.0
+  - id: promotion-system
+    version: 1.0.0
+entities:
+  - id: cart
+    version: 1.0.0
+  - id: cart-item
+    version: 1.0.0
+  - id: promotion
+    version: 1.0.0
+  - id: discount
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Shopping** domain is responsible for everything between browsing and buying — the shopping cart and the promotions applied to it. It is split into two systems:
+
+<Tiles>
+  <Tile
+    icon="ShoppingCartIcon"
+    href="/docs/systems/cart-system/1.0.0"
+    title="Cart System"
+    description="System of record for shopping carts — add, remove and check out items."
+  />
+  <Tile
+    icon="TagIcon"
+    href="/docs/systems/promotion-system/1.0.0"
+    title="Promotion System"
+    description="Calculates the discounts and promotions that apply to a cart."
+  />
+</Tiles>
+
+### How the systems work together
+
+The **Cart System** owns the customer's cart and the checkout flow. When pricing a cart, it asks the **Promotion System** to calculate the discounts that apply. When the customer checks out, the Cart System publishes an event the rest of the business reacts to.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The components that make up this domain.
+
+<NodeGraph />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/containers/cart-database/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/containers/cart-database/index.mdx
new file mode 100644
index 000000000..8e1e634f0
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/containers/cart-database/index.mdx
@@ -0,0 +1,39 @@
+---
+id: cart-database
+name: Cart Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for shopping carts and their items.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for shopping carts
+classification: internal
+retention: 90d
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Cart Database** is the authoritative store for shopping carts at Acme Inc. The [[service|cart-api]] reads from and writes to it as customers add, remove and check out items.
+
+### What does it store?
+
+- **Carts** — one row per cart: id, customer, status and timestamps.
+- **Cart Items** — one row per item in a cart: product, quantity and unit price.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Cart Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Retention
+
+Carts are transient. Abandoned carts are pruned after **90 days** (see frontmatter). A checked-out cart's contents live on in the [[event|cart-checked-out]] event and downstream order records.
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/containers/cart-database/schema.sql b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/containers/cart-database/schema.sql
new file mode 100644
index 000000000..113fc17f4
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/containers/cart-database/schema.sql
@@ -0,0 +1,22 @@
+-- Cart Database — system of record for shopping carts
+
+CREATE TABLE carts (
+    cart_id      UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    customer_id  UUID,
+    status       TEXT NOT NULL DEFAULT 'OPEN'
+                   CHECK (status IN ('OPEN', 'CHECKED_OUT', 'ABANDONED')),
+    currency     CHAR(3) NOT NULL DEFAULT 'USD',
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE cart_items (
+    cart_id          UUID NOT NULL REFERENCES carts (cart_id) ON DELETE CASCADE,
+    product_id       UUID NOT NULL,
+    quantity         INTEGER NOT NULL CHECK (quantity > 0),
+    unit_price_cents INTEGER NOT NULL CHECK (unit_price_cents >= 0),
+    PRIMARY KEY (cart_id, product_id)
+);
+
+CREATE INDEX idx_carts_customer ON carts (customer_id);
+CREATE INDEX idx_carts_status   ON carts (status);
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/index.mdx
new file mode 100644
index 000000000..ec71af876
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/index.mdx
@@ -0,0 +1,53 @@
+---
+id: cart-system
+name: Cart System
+version: 1.0.0
+summary: |
+  Internal system that owns the customer's shopping cart and the checkout flow. It is the source of truth for cart contents and publishes an event when a cart is checked out.
+owners:
+  - shopping-platform
+services:
+  - id: cart-api
+containers:
+  - id: cart-database
+relationships:
+  - id: promotion-system
+    label: calculates discounts via
+actors:
+  - id: shopper
+    name: Shopper
+    label: adds items and checks out
+    direction: inbound
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Cart System** owns the shopping cart at Acme Inc. It accepts commands to add and remove items and to check out, persists cart contents in the [[container|cart-database]], and asks the [[system|promotion-system]] to calculate the discounts that apply. When a cart is checked out it publishes a [[event|cart-checked-out]] event.
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                    | Type       | Responsibility                                                                            |
+| ---------------------------- | ---------- | ----------------------------------------------------------------------------------------- |
+| [[service\|cart-api]]        | Service    | Public-facing API. Handles add/remove/checkout commands and publishes the checkout event. |
+| [[container\|cart-database]] | Data store | PostgreSQL system of record for shopping carts and their items.                           |
+
+## Messages this system publishes
+
+- [[event|cart-checked-out]] — a customer has checked out their cart.
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/index.mdx
new file mode 100644
index 000000000..0d310bef9
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/index.mdx
@@ -0,0 +1,32 @@
+---
+id: add-item-to-cart
+name: Add Item To Cart
+version: 1.0.0
+summary: |
+  Command to add an item to a shopping cart.
+owners:
+  - shopping-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /carts/{cartId}/items
+  statusCodes: ['200', '400', '404']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`AddItemToCart` is handled by the [[service|cart-api]]. It adds an item (or increases its quantity) in the cart and persists the change to the [[container|cart-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/schema.json b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/schema.json
new file mode 100644
index 000000000..2ff550e23
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/AddItemToCart/schema.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AddItemToCart",
+  "description": "Command to add an item to a shopping cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Unique identifier of the cart",
+      "type": "string",
+      "format": "uuid"
+    },
+    "productId": {
+      "description": "Identifier of the product to add",
+      "type": "string",
+      "format": "uuid"
+    },
+    "quantity": {
+      "description": "Number of units to add",
+      "type": "integer",
+      "minimum": 1,
+      "default": 1
+    }
+  },
+  "required": ["cartId", "productId", "quantity"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/index.mdx
new file mode 100644
index 000000000..8b2dde56c
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/index.mdx
@@ -0,0 +1,32 @@
+---
+id: checkout-cart
+name: Checkout Cart
+version: 1.0.0
+summary: |
+  Command to check out a shopping cart.
+owners:
+  - shopping-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /carts/{cartId}/checkout
+  statusCodes: ['200', '400', '404', '409']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CheckoutCart` is handled by the [[service|cart-api]]. It finalises the cart — pricing it (including discounts from the [[system|promotion-system]]) — and on success publishes a [[event|cart-checked-out]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/schema.json b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/schema.json
new file mode 100644
index 000000000..57c74aed5
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/CheckoutCart/schema.json
@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CheckoutCart",
+  "description": "Command to check out a shopping cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Unique identifier of the cart to check out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "description": "Identifier of the customer checking out",
+      "type": "string",
+      "format": "uuid"
+    },
+    "promotionCode": {
+      "description": "Optional promotion code to apply at checkout",
+      "type": "string"
+    }
+  },
+  "required": ["cartId", "customerId"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/index.mdx
new file mode 100644
index 000000000..6fd484071
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/index.mdx
@@ -0,0 +1,32 @@
+---
+id: remove-item-from-cart
+name: Remove Item From Cart
+version: 1.0.0
+summary: |
+  Command to remove an item from a shopping cart.
+owners:
+  - shopping-platform
+schemaPath: schema.json
+operation:
+  method: DELETE
+  path: /carts/{cartId}/items/{productId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'DELETE'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`RemoveItemFromCart` is handled by the [[service|cart-api]]. It removes an item from the cart (or decreases its quantity) and persists the change to the [[container|cart-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/schema.json b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/schema.json
new file mode 100644
index 000000000..d3dcbfe60
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/commands/RemoveItemFromCart/schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RemoveItemFromCart",
+  "description": "Command to remove an item from a shopping cart",
+  "type": "object",
+  "properties": {
+    "cartId": {
+      "description": "Unique identifier of the cart",
+      "type": "string",
+      "format": "uuid"
+    },
+    "productId": {
+      "description": "Identifier of the product to remove",
+      "type": "string",
+      "format": "uuid"
+    },
+    "quantity": {
+      "description": "Number of units to remove. If omitted, removes the item entirely.",
+      "type": "integer",
+      "minimum": 1
+    }
+  },
+  "required": ["cartId", "productId"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/index.mdx
new file mode 100644
index 000000000..fc2b7875c
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/index.mdx
@@ -0,0 +1,29 @@
+---
+id: cart-checked-out
+name: Cart Checked Out
+version: 1.0.0
+summary: |
+  Published when a customer has checked out their cart.
+owners:
+  - shopping-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CartCheckedOut` is published by the [[service|cart-api]] when a customer checks out. Downstream systems consume this event to create an order, take payment, and begin fulfilment.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/schema.json b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/schema.json
new file mode 100644
index 000000000..3242b297e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/events/CartCheckedOut/schema.json
@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CartCheckedOut",
+  "description": "Emitted when a customer checks out their cart",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "cartId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "customerId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "quantity": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "unitPrice": {
+            "description": "Price per unit in minor units (e.g. cents)",
+            "type": "integer"
+          }
+        },
+        "required": ["productId", "quantity", "unitPrice"]
+      }
+    },
+    "subtotal": {
+      "description": "Total before discounts, in minor units (e.g. cents)",
+      "type": "integer"
+    },
+    "discount": {
+      "description": "Total discount applied, in minor units (e.g. cents)",
+      "type": "integer"
+    },
+    "total": {
+      "description": "Final total, in minor units (e.g. cents)",
+      "type": "integer"
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    }
+  },
+  "required": ["eventId", "occurredAt", "cartId", "customerId", "items", "total", "currency"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/index.mdx
new file mode 100644
index 000000000..c0815b0db
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/index.mdx
@@ -0,0 +1,72 @@
+---
+id: cart-api
+version: 1.0.0
+name: Cart API
+summary: |
+  The public-facing API for shopping carts. Handles commands to add and remove items and to check out, and publishes an event when a cart is checked out.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - shopping-platform
+receives:
+  - id: add-item-to-cart
+    version: 1.0.0
+  - id: remove-item-from-cart
+    version: 1.0.0
+  - id: checkout-cart
+    version: 1.0.0
+sends:
+  - id: cart-checked-out
+    version: 1.0.0
+  - id: calculate-discount
+    version: 1.0.0
+writesTo:
+  - id: cart-database
+readsFrom:
+  - id: cart-database
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/cart-api'
+specifications:
+  - type: openapi
+    path: openapi.yml
+    name: Cart API
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Cart API** is the front door to the Cart System. It validates incoming commands, persists cart contents to the [[container|cart-database]], asks the [[system|promotion-system]] to calculate discounts via [[command|calculate-discount]], and publishes a [[event|cart-checked-out]] event when the customer checks out.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Checkout event and discount requests"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Cart commands handled by this service"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area             | Description                                                                                                             |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Cart management  | Validates and applies [[command\|add-item-to-cart]], [[command\|remove-item-from-cart]] and [[command\|checkout-cart]]. |
+| Discounts        | Requests pricing from the Promotion System via [[command\|calculate-discount]].                                         |
+| Event publishing | Emits [[event\|cart-checked-out]] when a cart is checked out.                                                           |
+| Persistence      | Reads from and writes to the [[container\|cart-database]] (system of record).                                           |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/openapi.yml b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/openapi.yml
new file mode 100644
index 000000000..3671bc55c
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/cart-system/services/CartAPI/openapi.yml
@@ -0,0 +1,200 @@
+openapi: 3.0.3
+info:
+  title: Cart API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Cart System. Customers use it to build a cart —
+    adding and removing items — and to check out. At checkout the cart is priced
+    (including discounts from the Promotion System) and a `CartCheckedOut` event
+    is published.
+  contact:
+    name: Shopping Platform
+    email: shopping-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+tags:
+  - name: Cart
+    description: Build and check out a shopping cart.
+paths:
+  /carts/{cartId}/items:
+    parameters:
+      - $ref: '#/components/parameters/CartId'
+    post:
+      operationId: addItemToCart
+      summary: Add an item to the cart
+      tags:
+        - Cart
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AddItemRequest'
+      responses:
+        '200':
+          description: The item was added; the updated cart is returned.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Cart'
+        '400':
+          description: The request was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: The cart was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /carts/{cartId}/items/{productId}:
+    parameters:
+      - $ref: '#/components/parameters/CartId'
+      - name: productId
+        in: path
+        required: true
+        description: Identifier of the product to remove.
+        schema:
+          type: string
+          format: uuid
+    delete:
+      operationId: removeItemFromCart
+      summary: Remove an item from the cart
+      tags:
+        - Cart
+      responses:
+        '200':
+          description: The item was removed; the updated cart is returned.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Cart'
+        '404':
+          description: The cart or item was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /carts/{cartId}/checkout:
+    parameters:
+      - $ref: '#/components/parameters/CartId'
+    post:
+      operationId: checkoutCart
+      summary: Check out the cart
+      description: Prices the cart (including discounts) and, on success, publishes a `CartCheckedOut` event.
+      tags:
+        - Cart
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CheckoutRequest'
+      responses:
+        '200':
+          description: The cart was checked out.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Cart'
+        '400':
+          description: The request was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: The cart was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: The cart is empty or already checked out.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  parameters:
+    CartId:
+      name: cartId
+      in: path
+      required: true
+      description: Unique identifier of the cart.
+      schema:
+        type: string
+        format: uuid
+  schemas:
+    Cart:
+      type: object
+      required: [cartId, status, items, currency]
+      properties:
+        cartId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [OPEN, CHECKED_OUT, ABANDONED]
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/CartItem'
+        subtotal:
+          type: integer
+          description: Total before discounts, in minor units (e.g. cents).
+        discount:
+          type: integer
+          description: Total discount applied, in minor units (e.g. cents).
+        total:
+          type: integer
+          description: Final total, in minor units (e.g. cents).
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+    CartItem:
+      type: object
+      required: [productId, quantity, unitPrice]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        quantity:
+          type: integer
+          minimum: 1
+        unitPrice:
+          type: integer
+          description: Price per unit in minor units (e.g. cents).
+    AddItemRequest:
+      type: object
+      required: [productId, quantity]
+      properties:
+        productId:
+          type: string
+          format: uuid
+        quantity:
+          type: integer
+          minimum: 1
+    CheckoutRequest:
+      type: object
+      required: [customerId]
+      properties:
+        customerId:
+          type: string
+          format: uuid
+        promotionCode:
+          type: string
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/containers/promotion-database/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/containers/promotion-database/index.mdx
new file mode 100644
index 000000000..f552037eb
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/containers/promotion-database/index.mdx
@@ -0,0 +1,40 @@
+---
+id: promotion-database
+name: Promotion Database
+version: 1.0.0
+summary: PostgreSQL store of promotion and discount rules.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for promotion and discount rules
+classification: internal
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Promotion Database** holds the promotion and discount rules that the [[service|promotion-service]] evaluates when pricing a cart. It is the source of truth for what promotions exist, who they apply to, and when they are valid.
+
+### What does it store?
+
+- **Promotions** — one row per promotion: code, type (percentage / fixed amount), value, and validity window.
+- **Eligibility rules** — the conditions under which a promotion applies (minimum spend, customer segment, etc.).
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Promotion Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>
+
+### Access patterns
+
+- The [[service|promotion-service]] reads rules when handling [[command|calculate-discount]].
+- Rules are managed by the promotions team and change infrequently relative to read volume.
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/containers/promotion-database/schema.sql b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/containers/promotion-database/schema.sql
new file mode 100644
index 000000000..125d58a1b
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/containers/promotion-database/schema.sql
@@ -0,0 +1,21 @@
+-- Promotion Database — system of record for promotion and discount rules
+
+CREATE TABLE promotions (
+    promotion_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    code         TEXT NOT NULL UNIQUE,
+    description  TEXT,
+    type         TEXT NOT NULL CHECK (type IN ('PERCENTAGE', 'FIXED_AMOUNT')),
+    value        INTEGER NOT NULL CHECK (value >= 0),
+    starts_at    TIMESTAMPTZ NOT NULL,
+    ends_at      TIMESTAMPTZ,
+    active       BOOLEAN NOT NULL DEFAULT true
+);
+
+CREATE TABLE eligibility_rules (
+    promotion_id     UUID NOT NULL REFERENCES promotions (promotion_id) ON DELETE CASCADE,
+    min_spend_cents  INTEGER CHECK (min_spend_cents >= 0),
+    customer_segment TEXT,
+    PRIMARY KEY (promotion_id)
+);
+
+CREATE INDEX idx_promotions_active ON promotions (active) WHERE active = true;
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/index.mdx
new file mode 100644
index 000000000..fc7eb3809
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/index.mdx
@@ -0,0 +1,48 @@
+---
+id: promotion-system
+name: Promotion System
+version: 1.0.0
+summary: |
+  Internal system that calculates the discounts and promotions that apply to a cart. It owns promotion rules and returns calculated discounts to the Cart System.
+owners:
+  - shopping-platform
+services:
+  - id: promotion-service
+containers:
+  - id: promotion-database
+relationships:
+  - id: cart-system
+    label: provides discounts to
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Promotion System** owns the discount and promotion rules at Acme Inc. It receives requests to calculate the discount for a cart, evaluates the applicable rules from the [[container|promotion-database]], and publishes a [[event|discount-calculated]] event with the result. It provides discounts to the [[system|cart-system]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                         | Type       | Responsibility                                                 |
+| --------------------------------- | ---------- | -------------------------------------------------------------- |
+| [[service\|promotion-service]]    | Service    | Evaluates promotion rules and calculates discounts for a cart. |
+| [[container\|promotion-database]] | Data store | PostgreSQL store of promotion and discount rules.              |
+
+## Messages this system publishes
+
+- [[event|discount-calculated]] — a discount has been calculated for a cart.
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/index.mdx
new file mode 100644
index 000000000..70fc6186f
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/index.mdx
@@ -0,0 +1,32 @@
+---
+id: calculate-discount
+name: Calculate Discount
+version: 1.0.0
+summary: |
+  Command to calculate the discount that applies to a cart.
+owners:
+  - shopping-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /discounts/calculate
+  statusCodes: ['200', '400']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CalculateDiscount` is handled by the [[service|promotion-service]]. It is sent by the [[service|cart-api]] when pricing a cart. The service evaluates the applicable promotion rules and returns the discount, also publishing a [[event|discount-calculated]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/schema.json b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/schema.json
new file mode 100644
index 000000000..8fb6c243c
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/commands/CalculateDiscount/schema.json
@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CalculateDiscount",
+  "description": "Command to calculate the discount for a cart, and the discount returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "type": "object",
+      "properties": {
+        "cartId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "customerId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "subtotal": {
+          "description": "Cart subtotal before discounts, in minor units (e.g. cents)",
+          "type": "integer",
+          "minimum": 0
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "promotionCode": {
+          "description": "Optional promotion code supplied by the customer",
+          "type": "string"
+        }
+      },
+      "required": ["cartId", "subtotal", "currency"]
+    },
+    "response": {
+      "type": "object",
+      "properties": {
+        "discount": {
+          "description": "Total discount to apply, in minor units (e.g. cents)",
+          "type": "integer",
+          "minimum": 0
+        },
+        "appliedPromotions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": ["discount"]
+    }
+  },
+  "required": ["request", "response"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/index.mdx
new file mode 100644
index 000000000..eb2dc0182
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/index.mdx
@@ -0,0 +1,29 @@
+---
+id: discount-calculated
+name: Discount Calculated
+version: 1.0.0
+summary: |
+  Published when a discount has been calculated for a cart.
+owners:
+  - shopping-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`DiscountCalculated` is published by the [[service|promotion-service]] after evaluating the promotion rules for a cart. The [[system|cart-system]] uses the result to price the cart, and other systems can consume it for analytics.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/schema.json b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/schema.json
new file mode 100644
index 000000000..a4f22b48a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/events/DiscountCalculated/schema.json
@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "DiscountCalculated",
+  "description": "Emitted when a discount has been calculated for a cart",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "cartId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "discount": {
+      "description": "Total discount applied, in minor units (e.g. cents)",
+      "type": "integer",
+      "minimum": 0
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "appliedPromotions": {
+      "description": "Identifiers of the promotions that were applied",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": ["eventId", "occurredAt", "cartId", "discount", "currency"]
+}
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/index.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/index.mdx
new file mode 100644
index 000000000..7b08887a0
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/systems/promotion-system/services/PromotionService/index.mdx
@@ -0,0 +1,59 @@
+---
+id: promotion-service
+version: 1.0.0
+name: Promotion Service
+summary: |
+  Evaluates promotion rules and calculates the discount that applies to a cart. Receives discount requests and publishes the calculated result.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - shopping-platform
+receives:
+  - id: calculate-discount
+    version: 1.0.0
+sends:
+  - id: discount-calculated
+    version: 1.0.0
+readsFrom:
+  - id: promotion-database
+repository:
+  language: Go
+  url: 'https://github.com/acme/promotion-service'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Promotion Service** is the heart of the Promotion System. It receives [[command|calculate-discount]] requests from the [[system|cart-system]], evaluates the applicable rules from the [[container|promotion-database]], and publishes a [[event|discount-calculated]] event with the result.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} message`}
+    description="The calculated discount, published as an event"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Discount calculation requests"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area                 | Description                                                                    |
+| -------------------- | ------------------------------------------------------------------------------ |
+| Discount calculation | Handles [[command\|calculate-discount]] and evaluates promotion rules.         |
+| Rules                | Reads promotion and discount rules from the [[container\|promotion-database]]. |
+| Event publishing     | Emits [[event\|discount-calculated]] with the calculated result.               |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />
diff --git a/packages/create-eventcatalog/templates/default/domains/Shopping/ubiquitous-language.mdx b/packages/create-eventcatalog/templates/default/domains/Shopping/ubiquitous-language.mdx
new file mode 100644
index 000000000..00cd8e85b
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/domains/Shopping/ubiquitous-language.mdx
@@ -0,0 +1,48 @@
+---
+dictionary:
+  - id: Cart
+    name: Cart
+    summary: "A customer's in-progress collection of items they intend to buy."
+    description: |
+      The cart is the central concept of the Shopping domain. It is owned by the Cart System, which
+      is the source of truth for cart contents. A cart has a status (OPEN, CHECKED_OUT or ABANDONED),
+      a customer, a currency, and a set of cart items. Carts are transient — abandoned carts are
+      pruned after a retention window.
+    icon: ShoppingCart
+  - id: Cart Item
+    name: Cart Item
+    summary: 'A single product line within a cart: a product, a quantity and a unit price.'
+    icon: ListOrdered
+  - id: Checkout
+    name: Checkout
+    summary: 'The act of finalising a cart — pricing it and committing to purchase.'
+    description: |
+      At checkout the Cart System prices the cart (including any discounts from the Promotion System)
+      and, on success, publishes a CartCheckedOut event that the rest of the business reacts to —
+      creating an order, taking payment and beginning fulfilment.
+    icon: CreditCard
+  - id: Promotion
+    name: Promotion
+    summary: 'A rule that reduces the price of a cart, such as a percentage off or a fixed amount.'
+    description: |
+      Promotions are owned by the Promotion System. Each promotion has a code, a type (PERCENTAGE or
+      FIXED_AMOUNT), a value, a validity window, and eligibility rules (e.g. minimum spend or customer
+      segment) that determine when it applies.
+    icon: Tag
+  - id: Discount
+    name: Discount
+    summary: 'The actual amount taken off a specific cart after evaluating the applicable promotions.'
+    description: |
+      A discount is the calculated result of applying promotions to a cart. The Cart System asks the
+      Promotion System to calculate it; the Promotion System evaluates the rules and returns the
+      discount, also publishing a DiscountCalculated event.
+    icon: Percent
+  - id: Subtotal
+    name: Subtotal
+    summary: "The total value of a cart's items before any discounts are applied."
+    icon: Calculator
+  - id: Promotion Code
+    name: Promotion Code
+    summary: 'A code a customer enters at checkout to apply a specific promotion.'
+    icon: Ticket
+---
diff --git a/packages/create-eventcatalog/templates/default/env b/packages/create-eventcatalog/templates/default/env
new file mode 100644
index 000000000..3ca39cda3
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/env
@@ -0,0 +1,9 @@
+# EventCatalog Scale License Key, if you want to unlock the scale features
+# You can get a 14 day trial license key from https://eventcatalog.cloud
+
+EVENTCATALOG_SCALE_LICENSE_KEY=
+
+# Optional key if you are using EventCatalog Chat with OpenAI Models.
+# You need to set `output` to `server` in your eventcatalog.config.js file.
+# See documentation for more details: https://www.eventcatalog.dev/features/ai-assistant
+OPENAI_API_KEY=
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/default/eventcatalog.auth.js b/packages/create-eventcatalog/templates/default/eventcatalog.auth.js
new file mode 100644
index 000000000..f97044604
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/eventcatalog.auth.js
@@ -0,0 +1,44 @@
+/**
+ * This is an optional file that can add authentication to your EventCatalog.
+ *
+ * To enable authentication you need to set `server:output` in your `eventcatalog.config.js` file.
+ * And then pick which provider you want to use.
+ *
+ * You can read more in the documentation:
+ * https://www.eventcatalog.dev/docs/development/guides/authentication/introduction
+ *
+ */
+
+// export default {
+//   debug: false,
+//   providers: {
+//     // GitHub Authentication
+//     github: {
+//       clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+//       clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+//     },
+//     // Azure AD Entra ID
+//     entra: {
+//       clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
+//       clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
+//       issuer: process.env.AUTH_MICROSOFT_ENTRA_ID_ISSUER,
+//     },
+//     // Google Authentication
+//     google: {
+//       clientId: process.env.AUTH_GOOGLE_ID,
+//       clientSecret: process.env.AUTH_GOOGLE_SECRET,
+//     },
+//     // Auth0 Authentication
+//     auth0: {
+//       clientId: process.env.AUTH_AUTH0_ID,
+//       clientSecret: process.env.AUTH_AUTH0_SECRET,
+//       issuer: process.env.AUTH_AUTH0_ISSUER,
+//     },
+//     // Okta Authentication
+//     okta: {
+//       clientId: process.env.AUTH_OKTA_CLIENT_ID,
+//       clientSecret: process.env.AUTH_OKTA_CLIENT_SECRET,
+//       issuer: process.env.AUTH_OKTA_ISSUER,
+//     },
+//   },
+// }
diff --git a/packages/create-eventcatalog/templates/default/eventcatalog.config.js b/packages/create-eventcatalog/templates/default/eventcatalog.config.js
new file mode 100644
index 000000000..aa74a1ab6
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/eventcatalog.config.js
@@ -0,0 +1,54 @@
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  title: '<organizationName>',
+  tagline:
+    'This internal platform provides a comprehensive view of our event-driven architecture across all systems. Use this portal to discover existing domains, explore services and their dependencies, and understand the message contracts that connect our infrastructure',
+  organizationName: '<organizationName>',
+  theme: 'sunset',
+  homepageLink: 'https://eventcatalog.dev/',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  // Supports static or server. Static renders a static site, server renders a server side rendered site
+  // large catalogs may benefit from server side rendering
+  output: 'static',
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: '/',
+  // Resource search is the default lightweight search. Change this to { type: 'indexed' }
+  // to enable full-content search. Indexed search requires running a build to generate the index.
+  search: {
+    type: 'resource',
+  },
+  // Customize the navigation for your docs sidebar.
+  // read more at https://eventcatalog.dev/docs/development/customization/customize-sidebars/documentation-sidebar
+  navigation: {
+    pages: ['list:top-level-domains', 'list:all'],
+  },
+  mermaid: {
+    enableSupportForElkLayout: true,
+    iconPacks: ['logos'],
+  },
+  rss: {
+    enabled: true,
+    limit: 15,
+  },
+  visualiser: {
+    channels: {
+      renderMode: 'flat',
+    },
+  },
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: '<organizationName> Logo',
+    src: '/logo.png',
+    text: '<organizationName>',
+  },
+  // This lets you copy markdown contents from EventCatalog to your clipboard
+  // Including schemas for your events and services
+  llmsTxt: {
+    enabled: true,
+  },
+  // required random generated id used by eventcatalog
+  cId: '<cId>',
+};
diff --git a/packages/create-eventcatalog/templates/default/eventcatalog.styles.css b/packages/create-eventcatalog/templates/default/eventcatalog.styles.css
new file mode 100644
index 000000000..0d75d2602
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/eventcatalog.styles.css
@@ -0,0 +1 @@
+/* Custom styling support coming soon. */
diff --git a/packages/create-eventcatalog/templates/default/gitignore b/packages/create-eventcatalog/templates/default/gitignore
new file mode 100644
index 000000000..b6eaa6d14
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/gitignore
@@ -0,0 +1,29 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.astro
+out
+dist
+
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.eventcatalog-core
+
+.env
+.env-*
+
+exports/*
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/default/npmrc b/packages/create-eventcatalog/templates/default/npmrc
new file mode 100644
index 000000000..fa4e09523
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/npmrc
@@ -0,0 +1 @@
+strict-peer-dependencies=false
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/default/pages/homepage.astro b/packages/create-eventcatalog/templates/default/pages/homepage.astro
new file mode 100644
index 000000000..c29cc0bef
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/pages/homepage.astro
@@ -0,0 +1,109 @@
+---
+import { getCollection } from 'astro:content';
+
+// EventCatalog injects its components via Astro.props.components. Destructure the ones
+// this landing page uses (including the SystemContextMap embed).
+const { Tile, Tiles, SystemContextMap } = Astro.props.components;
+
+// Count the catalog's top-level resources. We filter out versioned/ entries so each
+// resource is counted once (by its latest version).
+const isCurrent = (entry) => !entry.filePath?.includes('/versioned/');
+
+const [domains, systems, services] = await Promise.all([
+  getCollection('domains'),
+  getCollection('systems'),
+  getCollection('services'),
+]);
+
+const stats = [
+  { label: 'Domains', value: domains.filter(isCurrent).length, href: '/discover/domains' },
+  { label: 'Systems', value: systems.filter(isCurrent).length, href: '/visualiser/system-context-map' },
+  { label: 'Services', value: services.filter(isCurrent).length, href: '/discover/services' },
+];
+---
+
+<div class="not-prose">
+  {/* Hero */}
+  <div class="pb-8 border-b border-[rgb(var(--ec-page-border))]">
+    <h1 class="text-4xl md:text-5xl font-bold text-[rgb(var(--ec-page-text))]">Acme Inc Catalog</h1>
+    <p class="mt-3 text-lg text-[rgb(var(--ec-page-text-muted))] max-w-3xl font-light">
+      Discover, explore and document the event-driven architecture that powers Acme Inc — our
+      domains, the systems inside them, and the services and messages that connect everything.
+    </p>
+  </div>
+
+  {/* Stat cards */}
+  <div class="grid grid-cols-1 sm:grid-cols-3 gap-4 mt-8">
+    {
+      stats.map((stat) => (
+        <a
+          href={stat.href}
+          class="group rounded-xl border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] p-6 shadow-xs hover:shadow-md hover:border-[rgb(var(--ec-accent)/0.5)] transition-all"
+        >
+          <div class="text-4xl font-bold text-[rgb(var(--ec-page-text))]">{stat.value}</div>
+          <div class="mt-1 text-sm font-medium uppercase tracking-wide text-[rgb(var(--ec-page-text-muted))]">
+            {stat.label}
+          </div>
+        </a>
+      ))
+    }
+  </div>
+
+  {/* System context map */}
+  <h2 class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-12 mb-2">System context map</h2>
+  <p class="text-[rgb(var(--ec-page-text-muted))] font-light mb-2">
+    How every system in the catalog relates — and the people who interact with them.
+  </p>
+</div>
+
+<SystemContextMap />
+
+<div class="not-prose">
+  {/* Domains */}
+  <h2 class="text-2xl font-semibold text-[rgb(var(--ec-page-text))] mt-12 mb-4">Explore the domains</h2>
+</div>
+
+<Tiles columns={3}>
+  <Tile
+    icon="RectangleGroupIcon"
+    href="/docs/domains/catalog/1.0.0"
+    title="Catalog"
+    description="Source of truth for product data and the search that makes it discoverable."
+  />
+  <Tile
+    icon="UserGroupIcon"
+    href="/docs/domains/customer/1.0.0"
+    title="Customer"
+    description="Customer profiles and authentication across Acme Inc."
+  />
+  <Tile
+    icon="ShoppingCartIcon"
+    href="/docs/domains/shopping/1.0.0"
+    title="Shopping"
+    description="The shopping cart and the promotions applied to it at checkout."
+  />
+  <Tile
+    icon="ClipboardDocumentListIcon"
+    href="/docs/domains/ordering/1.0.0"
+    title="Ordering"
+    description="Turning a checked-out cart into a confirmed order, from checkout to fulfilment."
+  />
+  <Tile
+    icon="CreditCardIcon"
+    href="/docs/domains/payments/1.0.0"
+    title="Payments"
+    description="Taking payment and processing refunds, with external payment and fraud providers."
+  />
+  <Tile
+    icon="TruckIcon"
+    href="/docs/domains/fulfilment/1.0.0"
+    title="Fulfilment"
+    description="Reserving stock, picking and packing orders, and shipping them to customers."
+  />
+  <Tile
+    icon="StarIcon"
+    href="/docs/domains/reviews/1.0.0"
+    title="Reviews & Ratings"
+    description="Collecting, moderating and publishing customer reviews, and aggregating them into product ratings."
+  />
+</Tiles>
diff --git a/packages/create-eventcatalog/templates/default/public/icons/analytics/clickhouse.svg b/packages/create-eventcatalog/templates/default/public/icons/analytics/clickhouse.svg
new file mode 100644
index 000000000..95c0bef80
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/public/icons/analytics/clickhouse.svg
@@ -0,0 +1 @@
+<svg fill="#FFCC01" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>ClickHouse</title><path d="M21.333 10H24v4h-2.667ZM16 1.335h2.667v21.33H16Zm-5.333 0h2.666v21.33h-2.666ZM0 22.665V1.335h2.667v21.33zm5.333-21.33H8v21.33H5.333Z"/></svg>
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/default/public/icons/cache/redis.svg b/packages/create-eventcatalog/templates/default/public/icons/cache/redis.svg
new file mode 100644
index 000000000..61480c931
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/public/icons/cache/redis.svg
@@ -0,0 +1 @@
+<svg fill="#FF4438" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Redis</title><path d="M22.71 13.145c-1.66 2.092-3.452 4.483-7.038 4.483-3.203 0-4.397-2.825-4.48-5.12.701 1.484 2.073 2.685 4.214 2.63 4.117-.133 6.94-3.852 6.94-7.239 0-4.05-3.022-6.972-8.268-6.972-3.752 0-8.4 1.428-11.455 3.685C2.59 6.937 3.885 9.958 4.35 9.626c2.648-1.904 4.748-3.13 6.784-3.744C8.12 9.244.886 17.05 0 18.425c.1 1.261 1.66 4.648 2.424 4.648.232 0 .431-.133.664-.365a100.49 100.49 0 0 0 5.54-6.765c.222 3.104 1.748 6.898 6.014 6.898 3.819 0 7.604-2.756 9.33-8.965.2-.764-.73-1.361-1.261-.73zm-4.349-5.013c0 1.959-1.926 2.922-3.685 2.922-.941 0-1.664-.247-2.235-.568 1.051-1.592 2.092-3.225 3.21-4.973 1.972.334 2.71 1.43 2.71 2.619z"/></svg>
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/default/public/icons/database/postgresql.svg b/packages/create-eventcatalog/templates/default/public/icons/database/postgresql.svg
new file mode 100644
index 000000000..931bdae18
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/public/icons/database/postgresql.svg
@@ -0,0 +1 @@
+<svg fill="#4169E1" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>PostgreSQL</title><path d="M23.5594 14.7228a.5269.5269 0 0 0-.0563-.1191c-.139-.2632-.4768-.3418-1.0074-.2321-1.6533.3411-2.2935.1312-2.5256-.0191 1.342-2.0482 2.445-4.522 3.0411-6.8297.2714-1.0507.7982-3.5237.1222-4.7316a1.5641 1.5641 0 0 0-.1509-.235C21.6931.9086 19.8007.0248 17.5099.0005c-1.4947-.0158-2.7705.3461-3.1161.4794a9.449 9.449 0 0 0-.5159-.0816 8.044 8.044 0 0 0-1.3114-.1278c-1.1822-.0184-2.2038.2642-3.0498.8406-.8573-.3211-4.7888-1.645-7.2219.0788C.9359 2.1526.3086 3.8733.4302 6.3043c.0409.818.5069 3.334 1.2423 5.7436.4598 1.5065.9387 2.7019 1.4334 3.582.553.9942 1.1259 1.5933 1.7143 1.7895.4474.1491 1.1327.1441 1.8581-.7279.8012-.9635 1.5903-1.8258 1.9446-2.2069.4351.2355.9064.3625 1.39.3772a.0569.0569 0 0 0 .0004.0041 11.0312 11.0312 0 0 0-.2472.3054c-.3389.4302-.4094.5197-1.5002.7443-.3102.064-1.1344.2339-1.1464.8115-.0025.1224.0329.2309.0919.3268.2269.4231.9216.6097 1.015.6331 1.3345.3335 2.5044.092 3.3714-.6787-.017 2.231.0775 4.4174.3454 5.0874.2212.5529.7618 1.9045 2.4692 1.9043.2505 0 .5263-.0291.8296-.0941 1.7819-.3821 2.5557-1.1696 2.855-2.9059.1503-.8707.4016-2.8753.5388-4.1012.0169-.0703.0357-.1207.057-.1362.0007-.0005.0697-.0471.4272.0307a.3673.3673 0 0 0 .0443.0068l.2539.0223.0149.001c.8468.0384 1.9114-.1426 2.5312-.4308.6438-.2988 1.8057-1.0323 1.5951-1.6698zM2.371 11.8765c-.7435-2.4358-1.1779-4.8851-1.2123-5.5719-.1086-2.1714.4171-3.6829 1.5623-4.4927 1.8367-1.2986 4.8398-.5408 6.108-.13-.0032.0032-.0066.0061-.0098.0094-2.0238 2.044-1.9758 5.536-1.9708 5.7495-.0002.0823.0066.1989.0162.3593.0348.5873.0996 1.6804-.0735 2.9184-.1609 1.1504.1937 2.2764.9728 3.0892.0806.0841.1648.1631.2518.2374-.3468.3714-1.1004 1.1926-1.9025 2.1576-.5677.6825-.9597.5517-1.0886.5087-.3919-.1307-.813-.5871-1.2381-1.3223-.4796-.839-.9635-2.0317-1.4155-3.5126zm6.0072 5.0871c-.1711-.0428-.3271-.1132-.4322-.1772.0889-.0394.2374-.0902.4833-.1409 1.2833-.2641 1.4815-.4506 1.9143-1.0002.0992-.126.2116-.2687.3673-.4426a.3549.3549 0 0 0 .0737-.1298c.1708-.1513.2724-.1099.4369-.0417.156.0646.3078.26.3695.4752.0291.1016.0619.2945-.0452.4444-.9043 1.2658-2.2216 1.2494-3.1676 1.0128zm2.094-3.988-.0525.141c-.133.3566-.2567.6881-.3334 1.003-.6674-.0021-1.3168-.2872-1.8105-.8024-.6279-.6551-.9131-1.5664-.7825-2.5004.1828-1.3079.1153-2.4468.079-3.0586-.005-.0857-.0095-.1607-.0122-.2199.2957-.2621 1.6659-.9962 2.6429-.7724.4459.1022.7176.4057.8305.928.5846 2.7038.0774 3.8307-.3302 4.7363-.084.1866-.1633.3629-.2311.5454zm7.3637 4.5725c-.0169.1768-.0358.376-.0618.5959l-.146.4383a.3547.3547 0 0 0-.0182.1077c-.0059.4747-.054.6489-.115.8693-.0634.2292-.1353.4891-.1794 1.0575-.11 1.4143-.8782 2.2267-2.4172 2.5565-1.5155.3251-1.7843-.4968-2.0212-1.2217a6.5824 6.5824 0 0 0-.0769-.2266c-.2154-.5858-.1911-1.4119-.1574-2.5551.0165-.5612-.0249-1.9013-.3302-2.6462.0044-.2932.0106-.5909.019-.8918a.3529.3529 0 0 0-.0153-.1126 1.4927 1.4927 0 0 0-.0439-.208c-.1226-.4283-.4213-.7866-.7797-.9351-.1424-.059-.4038-.1672-.7178-.0869.067-.276.1831-.5875.309-.9249l.0529-.142c.0595-.16.134-.3257.213-.5012.4265-.9476 1.0106-2.2453.3766-5.1772-.2374-1.0981-1.0304-1.6343-2.2324-1.5098-.7207.0746-1.3799.3654-1.7088.5321a5.6716 5.6716 0 0 0-.1958.1041c.0918-1.1064.4386-3.1741 1.7357-4.4823a4.0306 4.0306 0 0 1 .3033-.276.3532.3532 0 0 0 .1447-.0644c.7524-.5706 1.6945-.8506 2.802-.8325.4091.0067.8017.0339 1.1742.081 1.939.3544 3.2439 1.4468 4.0359 2.3827.8143.9623 1.2552 1.9315 1.4312 2.4543-1.3232-.1346-2.2234.1268-2.6797.779-.9926 1.4189.543 4.1729 1.2811 5.4964.1353.2426.2522.4522.2889.5413.2403.5825.5515.9713.7787 1.2552.0696.087.1372.1714.1885.245-.4008.1155-1.1208.3825-1.0552 1.717-.0123.1563-.0423.4469-.0834.8148-.0461.2077-.0702.4603-.0994.7662zm.8905-1.6211c-.0405-.8316.2691-.9185.5967-1.0105a2.8566 2.8566 0 0 0 .135-.0406 1.202 1.202 0 0 0 .1342.103c.5703.3765 1.5823.4213 3.0068.1344-.2016.1769-.5189.3994-.9533.6011-.4098.1903-1.0957.333-1.7473.3636-.7197.0336-1.0859-.0807-1.1721-.151zm.5695-9.2712c-.0059.3508-.0542.6692-.1054 1.0017-.055.3576-.112.7274-.1264 1.1762-.0142.4368.0404.8909.0932 1.3301.1066.887.216 1.8003-.2075 2.7014a3.5272 3.5272 0 0 1-.1876-.3856c-.0527-.1276-.1669-.3326-.3251-.6162-.6156-1.1041-2.0574-3.6896-1.3193-4.7446.3795-.5427 1.3408-.5661 2.1781-.463zm.2284 7.0137a12.3762 12.3762 0 0 0-.0853-.1074l-.0355-.0444c.7262-1.1995.5842-2.3862.4578-3.4385-.0519-.4318-.1009-.8396-.0885-1.2226.0129-.4061.0666-.7543.1185-1.0911.0639-.415.1288-.8443.1109-1.3505.0134-.0531.0188-.1158.0118-.1902-.0457-.4855-.5999-1.938-1.7294-3.253-.6076-.7073-1.4896-1.4972-2.6889-2.0395.5251-.1066 1.2328-.2035 2.0244-.1859 2.0515.0456 3.6746.8135 4.8242 2.2824a.908.908 0 0 1 .0667.1002c.7231 1.3556-.2762 6.2751-2.9867 10.5405zm-8.8166-6.1162c-.025.1794-.3089.4225-.6211.4225a.5821.5821 0 0 1-.0809-.0056c-.1873-.026-.3765-.144-.5059-.3156-.0458-.0605-.1203-.178-.1055-.2844.0055-.0401.0261-.0985.0925-.1488.1182-.0894.3518-.1226.6096-.0867.3163.0441.6426.1938.6113.4186zm7.9305-.4114c.0111.0792-.049.201-.1531.3102-.0683.0717-.212.1961-.4079.2232a.5456.5456 0 0 1-.075.0052c-.2935 0-.5414-.2344-.5607-.3717-.024-.1765.2641-.3106.5611-.352.297-.0414.6111.0088.6356.1851z"/></svg>
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/default/public/icons/languages/go.svg b/packages/create-eventcatalog/templates/default/public/icons/languages/go.svg
new file mode 100644
index 000000000..51990bd01
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/public/icons/languages/go.svg
@@ -0,0 +1 @@
+<svg fill="#00ADD8" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Go</title><path d="M1.811 10.231c-.047 0-.058-.023-.035-.059l.246-.315c.023-.035.081-.058.128-.058h4.172c.046 0 .058.035.035.07l-.199.303c-.023.036-.082.07-.117.07zM.047 11.306c-.047 0-.059-.023-.035-.058l.245-.316c.023-.035.082-.058.129-.058h5.328c.047 0 .07.035.058.07l-.093.28c-.012.047-.058.07-.105.07zm2.828 1.075c-.047 0-.059-.035-.035-.07l.163-.292c.023-.035.07-.07.117-.07h2.337c.047 0 .07.035.07.082l-.023.28c0 .047-.047.082-.082.082zm12.129-2.36c-.736.187-1.239.327-1.963.514-.176.046-.187.058-.34-.117-.174-.199-.303-.327-.548-.444-.737-.362-1.45-.257-2.115.175-.795.514-1.204 1.274-1.192 2.22.011.935.654 1.706 1.577 1.835.795.105 1.46-.175 1.987-.77.105-.13.198-.27.315-.434H10.47c-.245 0-.304-.152-.222-.35.152-.362.432-.97.596-1.274a.315.315 0 01.292-.187h4.253c-.023.316-.023.631-.07.947a4.983 4.983 0 01-.958 2.29c-.841 1.11-1.94 1.8-3.33 1.986-1.145.152-2.209-.07-3.143-.77-.865-.655-1.356-1.52-1.484-2.595-.152-1.274.222-2.419.993-3.424.83-1.086 1.928-1.776 3.272-2.02 1.098-.2 2.15-.07 3.096.571.62.41 1.063.97 1.356 1.648.07.105.023.164-.117.2m3.868 6.461c-1.064-.024-2.034-.328-2.852-1.029a3.665 3.665 0 01-1.262-2.255c-.21-1.32.152-2.489.947-3.529.853-1.122 1.881-1.706 3.272-1.95 1.192-.21 2.314-.095 3.33.595.923.63 1.496 1.484 1.648 2.605.198 1.578-.257 2.863-1.344 3.962-.771.783-1.718 1.273-2.805 1.495-.315.06-.63.07-.934.106zm2.78-4.72c-.011-.153-.011-.27-.034-.387-.21-1.157-1.274-1.81-2.384-1.554-1.087.245-1.788.935-2.045 2.033-.21.912.234 1.835 1.075 2.21.643.28 1.285.244 1.905-.07.923-.48 1.425-1.228 1.484-2.233z"/></svg>
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/default/public/icons/languages/java.svg b/packages/create-eventcatalog/templates/default/public/icons/languages/java.svg
new file mode 100644
index 000000000..c72c27432
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/public/icons/languages/java.svg
@@ -0,0 +1 @@
+<svg fill="#ED8B00" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Java</title><path d="M8.851 18.56s-.917.534.653.714c1.902.218 2.874.187 4.969-.211 0 0 .552.346 1.321.646-4.699 2.013-10.633-.118-6.943-1.149M8.276 15.933s-1.028.761.542.924c2.032.209 3.636.227 6.413-.308 0 0 .384.389.987.602-5.679 1.661-12.007.13-7.942-1.218M13.116 11.475c1.158 1.333-.304 2.533-.304 2.533s2.939-1.518 1.589-3.418c-1.261-1.772-2.228-2.652 3.007-5.688 0-.001-8.216 2.051-4.292 6.573M19.33 20.504s.679.559-.747.991c-2.712.822-11.288 1.069-13.669.033-.856-.373.75-.89 1.254-.998.527-.114.828-.093.828-.093-.953-.671-6.156 1.317-2.643 1.887 9.58 1.553 17.462-.7 14.977-1.82M9.292 13.21s-4.362 1.036-1.544 1.412c1.189.159 3.561.123 5.77-.062 1.806-.152 3.618-.477 3.618-.477s-.637.272-1.098.587c-4.429 1.165-12.986.623-10.522-.568 2.082-1.006 3.776-.892 3.776-.892M17.116 17.584c4.503-2.34 2.421-4.589.968-4.285-.355.074-.515.138-.515.138s.132-.207.385-.297c2.875-1.011 5.086 2.981-.928 4.562 0-.001.07-.062.09-.118M13.408 0s2.494 2.494-2.365 6.33c-3.896 3.077-.888 4.832-.001 6.836-2.274-2.053-3.943-3.858-2.824-5.539 1.644-2.469 6.197-3.665 5.19-7.627M9.734 23.924c4.322.277 10.959-.153 11.116-2.198 0 0-.302.775-3.572 1.391-3.688.694-8.239.613-10.937.168 0-.001.553.457 3.393.639"/></svg>
diff --git a/packages/create-eventcatalog/templates/default/public/icons/languages/nodejs.svg b/packages/create-eventcatalog/templates/default/public/icons/languages/nodejs.svg
new file mode 100644
index 000000000..3cc5893e0
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/public/icons/languages/nodejs.svg
@@ -0,0 +1 @@
+<svg fill="#5FA04E" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Node.js</title><path d="M11.998,24c-0.321,0-0.641-0.084-0.922-0.247l-2.936-1.737c-0.438-0.245-0.224-0.332-0.08-0.383 c0.585-0.203,0.703-0.25,1.328-0.604c0.065-0.037,0.151-0.023,0.218,0.017l2.256,1.339c0.082,0.045,0.197,0.045,0.272,0l8.795-5.076 c0.082-0.047,0.134-0.141,0.134-0.238V6.921c0-0.099-0.053-0.192-0.137-0.242l-8.791-5.072c-0.081-0.047-0.189-0.047-0.271,0 L3.075,6.68C2.99,6.729,2.936,6.825,2.936,6.921v10.15c0,0.097,0.054,0.189,0.139,0.235l2.409,1.392 c1.307,0.654,2.108-0.116,2.108-0.89V7.787c0-0.142,0.114-0.253,0.256-0.253h1.115c0.139,0,0.255,0.112,0.255,0.253v10.021 c0,1.745-0.95,2.745-2.604,2.745c-0.508,0-0.909,0-2.026-0.551L2.28,18.675c-0.57-0.329-0.922-0.945-0.922-1.604V6.921 c0-0.659,0.353-1.275,0.922-1.603l8.795-5.082c0.557-0.315,1.296-0.315,1.848,0l8.794,5.082c0.57,0.329,0.924,0.944,0.924,1.603 v10.15c0,0.659-0.354,1.273-0.924,1.604l-8.794,5.078C12.643,23.916,12.324,24,11.998,24z M19.099,13.993 c0-1.9-1.284-2.406-3.987-2.763c-2.731-0.361-3.009-0.548-3.009-1.187c0-0.528,0.235-1.233,2.258-1.233 c1.807,0,2.473,0.389,2.747,1.607c0.024,0.115,0.129,0.199,0.247,0.199h1.141c0.071,0,0.138-0.031,0.186-0.081 c0.048-0.054,0.074-0.123,0.067-0.196c-0.177-2.098-1.571-3.076-4.388-3.076c-2.508,0-4.004,1.058-4.004,2.833 c0,1.925,1.488,2.457,3.895,2.695c2.88,0.282,3.103,0.703,3.103,1.269c0,0.983-0.789,1.402-2.642,1.402 c-2.327,0-2.839-0.584-3.011-1.742c-0.02-0.124-0.126-0.215-0.253-0.215h-1.137c-0.141,0-0.254,0.112-0.254,0.253 c0,1.482,0.806,3.248,4.655,3.248C17.501,17.007,19.099,15.91,19.099,13.993z"/></svg>
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/default/public/icons/payments/stripe.svg b/packages/create-eventcatalog/templates/default/public/icons/payments/stripe.svg
new file mode 100644
index 000000000..77e678c71
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/public/icons/payments/stripe.svg
@@ -0,0 +1 @@
+<svg fill="#635BFF" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Stripe</title><path d="M13.976 9.15c-2.172-.806-3.356-1.426-3.356-2.409 0-.831.683-1.305 1.901-1.305 2.227 0 4.515.858 6.090 1.631l.890-5.494C18.252.975 15.687 0 12.585 0 10.469 0 8.703.555 7.439 1.583 6.123 2.658 5.444 4.208 5.444 6.078c0 3.39 2.072 4.839 5.446 6.057 2.172.78 2.901 1.331 2.901 2.179 0 .825-.707 1.306-1.978 1.306-1.575 0-4.18-.78-5.886-1.768L5.04 19.601c1.46.831 4.157 1.673 6.952 1.673 2.235 0 4.098-.527 5.355-1.523 1.406-1.085 2.135-2.682 2.135-4.764 0-3.471-2.118-4.926-5.507-6.117v.28z"/></svg>
diff --git a/packages/create-eventcatalog/templates/default/public/logo.png b/packages/create-eventcatalog/templates/default/public/logo.png
new file mode 100644
index 000000000..670057fbb
Binary files /dev/null and b/packages/create-eventcatalog/templates/default/public/logo.png differ
diff --git a/packages/create-eventcatalog/templates/default/teams/customer-platform.mdx b/packages/create-eventcatalog/templates/default/teams/customer-platform.mdx
new file mode 100644
index 000000000..d7902b036
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/teams/customer-platform.mdx
@@ -0,0 +1,18 @@
+---
+id: customer-platform
+name: Customer Platform
+summary: Owns the Customer domain — customer profiles and authentication across Acme Inc.
+members:
+  - dboyne
+email: customer-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/customer-platform
+---
+
+## Overview
+
+The **Customer Platform** team owns the [[domain|customer]] domain. They are responsible for how customers register, how their profiles are maintained, and how they authenticate.
+
+## Responsibilities
+
+- **Customer Management System** — registering, updating and reading customer profiles, and publishing customer change events.
+- **Identity Provider** — authenticating customers and owning credentials in the user directory.
diff --git a/packages/create-eventcatalog/templates/default/teams/fulfilment-platform.mdx b/packages/create-eventcatalog/templates/default/teams/fulfilment-platform.mdx
new file mode 100644
index 000000000..d13738aac
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/teams/fulfilment-platform.mdx
@@ -0,0 +1,20 @@
+---
+id: fulfilment-platform
+name: Fulfilment Platform
+summary: Owns the Fulfilment domain — reserving stock, picking and packing orders, and shipping them to customers.
+members:
+  - dboyne
+email: fulfilment-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/fulfilment-platform
+---
+
+## Overview
+
+The **Fulfilment Platform** team owns the [[domain|fulfilment]] domain. They are responsible for inventory, warehousing and shipping — everything that gets a confirmed order physically to the customer.
+
+## Responsibilities
+
+- **Inventory System** — tracking and reserving stock.
+- **Warehouse System** — picking and packing orders.
+- **Shipping System** — handing packed orders to carriers.
+- Integration with external **Carriers** for delivery.
diff --git a/packages/create-eventcatalog/templates/default/teams/ordering-platform.mdx b/packages/create-eventcatalog/templates/default/teams/ordering-platform.mdx
new file mode 100644
index 000000000..ee58d62ab
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/teams/ordering-platform.mdx
@@ -0,0 +1,18 @@
+---
+id: ordering-platform
+name: Ordering Platform
+summary: Owns the Ordering domain — turning a checked-out cart into a confirmed order.
+members:
+  - dboyne
+email: ordering-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/ordering-platform
+---
+
+## Overview
+
+The **Ordering Platform** team owns the [[domain|ordering]] domain. They are responsible for the checkout flow that turns a checked-out cart into a confirmed order, and for the lifecycle of orders once they exist.
+
+## Responsibilities
+
+- **Checkout System** — orchestrating checkout: reserving inventory, authorizing payment and creating the order.
+- **Order Management System** — the system of record for orders and their lifecycle.
diff --git a/packages/create-eventcatalog/templates/default/teams/payments-platform.mdx b/packages/create-eventcatalog/templates/default/teams/payments-platform.mdx
new file mode 100644
index 000000000..3a9d135d1
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/teams/payments-platform.mdx
@@ -0,0 +1,18 @@
+---
+id: payments-platform
+name: Payments Platform
+summary: Owns the Payments domain — authorizing payments, processing refunds, and integrating with external payment and fraud providers.
+members:
+  - dboyne
+email: payments-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/payments-platform
+---
+
+## Overview
+
+The **Payments Platform** team owns the [[domain|payments]] domain. They are responsible for taking payment for orders, processing refunds, and integrating with the external payment processor and fraud provider.
+
+## Responsibilities
+
+- **Payment Processing System** — orchestrating authorization, capture and refunds.
+- Integrations with **Stripe** (payment processing) and **Fraud Detection** (fraud screening).
diff --git a/packages/create-eventcatalog/templates/default/teams/product-platform.mdx b/packages/create-eventcatalog/templates/default/teams/product-platform.mdx
new file mode 100644
index 000000000..43846b74d
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/teams/product-platform.mdx
@@ -0,0 +1,20 @@
+---
+id: product-platform
+name: Product Platform
+summary: Owns the Product Catalog System — the source of truth for product data at Acme Inc.
+members:
+  - dboyne
+email: product-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/product-platform
+---
+
+## Overview
+
+The **Product Platform** team owns the [[system|product-catalog-system]]. They are responsible for how products are created, maintained and stored, and for reliably publishing product change events to the rest of the business.
+
+## Responsibilities
+
+- **Product API** — the public-facing API for creating, updating, deleting and reading products.
+- **Product Worker** — asynchronous catalog processing (enrichment, media, bulk imports).
+- **Product Search Publisher** — reliable, ordered delivery of product change events.
+- **Product Database** — the PostgreSQL system of record for all product data.
diff --git a/packages/create-eventcatalog/templates/default/teams/reviews-platform.mdx b/packages/create-eventcatalog/templates/default/teams/reviews-platform.mdx
new file mode 100644
index 000000000..19a5bb07d
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/teams/reviews-platform.mdx
@@ -0,0 +1,20 @@
+---
+id: reviews-platform
+name: Reviews Platform
+summary: Owns the Reviews & Ratings domain — how customers review products and how those reviews are moderated, published and aggregated into ratings.
+members:
+  - dboyne
+email: reviews-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/reviews-platform
+---
+
+## Overview
+
+The **Reviews Platform** team owns the [[domain|reviews]] domain. They are responsible for collecting customer reviews, moderating them, publishing the approved ones, and turning ratings into the aggregate scores shown across the storefront.
+
+## Responsibilities
+
+- **Review API** — accepts review submissions and serves product reviews.
+- **Review Moderation Worker** — screens submitted reviews and decides whether to publish or reject them.
+- **Rating Aggregator** — keeps each product's aggregate rating up to date as reviews are published.
+- **Review Database** — the system of record for reviews and their moderation state.
diff --git a/packages/create-eventcatalog/templates/default/teams/search-platform.mdx b/packages/create-eventcatalog/templates/default/teams/search-platform.mdx
new file mode 100644
index 000000000..9b10a2bfb
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/teams/search-platform.mdx
@@ -0,0 +1,19 @@
+---
+id: search-platform
+name: Search Platform
+summary: Owns the Search System — keeps the catalog discoverable through fast, relevant product search.
+members:
+  - dboyne
+email: search-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/search-platform
+---
+
+## Overview
+
+The **Search Platform** team owns the [[system|search-system]]. They consume product change events, keep the search index in sync, and serve product search to the rest of Acme Inc.
+
+## Responsibilities
+
+- **Search API** — the public-facing API that serves product search queries.
+- **Search Indexer** — consumes product change events and keeps the index current.
+- **Search Index** — the search-optimised, rebuildable read model of the catalog.
diff --git a/packages/create-eventcatalog/templates/default/teams/shopping-platform.mdx b/packages/create-eventcatalog/templates/default/teams/shopping-platform.mdx
new file mode 100644
index 000000000..bd972fa05
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/teams/shopping-platform.mdx
@@ -0,0 +1,18 @@
+---
+id: shopping-platform
+name: Shopping Platform
+summary: Owns the Shopping domain — the cart and the promotions applied to it.
+members:
+  - dboyne
+email: shopping-platform@acme.test
+slackDirectMessageUrl: https://acme.slack.com/channels/shopping-platform
+---
+
+## Overview
+
+The **Shopping Platform** team owns the [[domain|shopping]] domain. They are responsible for the shopping cart, the checkout flow, and the promotions and discounts applied to a cart.
+
+## Responsibilities
+
+- **Cart System** — building, pricing and checking out shopping carts.
+- **Promotion System** — evaluating promotion rules and calculating discounts.
diff --git a/packages/create-eventcatalog/templates/default/users/dboyne.mdx b/packages/create-eventcatalog/templates/default/users/dboyne.mdx
new file mode 100644
index 000000000..a7a9ae5ea
--- /dev/null
+++ b/packages/create-eventcatalog/templates/default/users/dboyne.mdx
@@ -0,0 +1,34 @@
+---
+id: dboyne
+name: David Boyne
+avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png'
+role: Lead developer
+email: test@test.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=test@test.com
+---
+
+Hello! I'm David Boyne, the Tech Lead of an amazing team called Full Stackers. With a passion for building robust and scalable systems, I specialize in designing and implementing event-driven architectures that power modern, responsive applications.
+
+### About Me
+
+With over a decade of experience in the tech industry, I have honed my skills in full-stack development, cloud computing, and distributed systems. My journey has taken me through various roles, from software engineer to architect, and now as a tech lead, I am committed to driving innovation and excellence within my team.
+
+### What I Do
+
+At Full Stackers, we focus on creating seamless and efficient event-driven architectures that enhance the performance and scalability of our applications. My role involves:
+
+- **Architecture Design**: Crafting scalable and resilient system architectures using event-driven paradigms.
+- **Team Leadership**: Guiding a talented team of developers, fostering a collaborative and innovative environment.
+- **Code Reviews & Mentorship**: Ensuring code quality and sharing knowledge to help the team grow.
+- **Stakeholder Collaboration**: Working closely with other teams and stakeholders to align our technical solutions with business goals.
+- **Continuous Improvement**: Advocating for best practices in software development, deployment, and monitoring.
+
+I am passionate about leveraging the power of events to build systems that are not only highly responsive but also easier to maintain and extend. In an ever-evolving tech landscape, I strive to stay ahead of the curve, continuously learning and adapting to new technologies and methodologies.
+
+Feel free to connect with me to discuss all things tech, event-driven architectures, or to exchange ideas on building better software systems!
+
+---
+
+_David Boyne_
+_Tech Lead, Full Stackers_
diff --git a/packages/create-eventcatalog/templates/empty/Dockerfile b/packages/create-eventcatalog/templates/empty/Dockerfile
new file mode 100644
index 000000000..3405a94d2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/empty/Dockerfile
@@ -0,0 +1,23 @@
+## Stage 1: Build the app
+FROM node:lts AS build
+
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+# Copy source code
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+# Build the app
+RUN npm run build
+
+
+## Stage 2: Serve app with httpd server
+FROM httpd:2.4
+
+# Copy built app to serve
+COPY --from=build /app/dist /usr/local/apache2/htdocs
diff --git a/packages/create-eventcatalog/templates/empty/Dockerfile.server b/packages/create-eventcatalog/templates/empty/Dockerfile.server
new file mode 100644
index 000000000..8a7332d64
--- /dev/null
+++ b/packages/create-eventcatalog/templates/empty/Dockerfile.server
@@ -0,0 +1,23 @@
+# Use this Docker file if your EventCatalog output is set to `server`.
+# When EventCatalog output is set to `server`, the output will be a node server.
+# This server is required for certain features like the EventCatalog Chat (with your own keys).
+
+FROM node:lts AS runtime
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+RUN npm run build
+
+ENV HOST=0.0.0.0
+ENV PORT=3000
+EXPOSE 3000
+
+# Start the server
+CMD npm run start
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/empty/README-template.md b/packages/create-eventcatalog/templates/empty/README-template.md
new file mode 100644
index 000000000..2daa8c517
--- /dev/null
+++ b/packages/create-eventcatalog/templates/empty/README-template.md
@@ -0,0 +1,63 @@
+# Welcome to EventCatalog
+
+[EventCatalog](https://www.eventcatalog.dev/) is your architecture catalog for distributed systems. Use it to document, govern, and discover your services, domains, APIs, events, commands, queries, schemas, teams, and flows in one place.
+
+## Start the Catalog
+
+```sh
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view your catalog.
+
+Using `pnpm` or `yarn`? Run the same scripts with the package manager you chose when creating this project.
+
+## Edit Your Catalog
+
+Your catalog is docs-as-code. Resources live in folders with an `index.mdx` file for frontmatter metadata and Markdown content.
+
+Good places to start:
+
+- `domains/` - bounded contexts, business capabilities, and ownership
+- `domains/<domain>/services/` - services, APIs, and message producers or consumers
+- `events/`, `commands/`, and `queries/` - the messages flowing through your system
+- `teams/` and `users/` - who owns each part of the architecture
+
+Prefer a visual workflow? Run `npm run editor` to open the [EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview) and browse, create, or update catalog resources through a GitHub-backed UI.
+
+## Make Your First Change
+
+1. Add or edit a domain, service, or message.
+2. Run `npm run dev` and check the generated pages and diagrams.
+3. Commit the MDX and schema files to Git.
+
+## Keep It in Sync
+
+Use `npm run generate` with [EventCatalog integrations](https://www.eventcatalog.dev/integrations) to import architecture data from OpenAPI, AsyncAPI, schema registries, EventBridge, GitHub, internal systems, and more.
+
+Run generators locally while you work, or in CI so your catalog stays aligned with the systems it describes.
+
+## Use AI with Architecture Context
+
+EventCatalog gives AI tools structured context about your domains, services, messages, schemas, owners, and flows.
+
+- Connect Claude, Cursor, VS Code, Windsurf, or another MCP-compatible tool with the [EventCatalog MCP Server](https://www.eventcatalog.dev/docs/development/guides/ai/using-mcp-server).
+- Install [EventCatalog Skills](https://github.com/event-catalog/skills) to help agents document services, create domain models, and map business flows:
+
+```sh
+npx skills add event-catalog/skills
+```
+
+## Learn by Task
+
+- [Create a domain](https://www.eventcatalog.dev/docs/development/guides/domains)
+- [Document a service](https://www.eventcatalog.dev/docs/development/guides/services)
+- [Add events, commands, and queries](https://www.eventcatalog.dev/docs/development/guides/messages/adding-messages)
+- [Use the EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview)
+- [Generate from integrations](https://www.eventcatalog.dev/integrations)
+- [Manage your catalog with the SDK](https://www.eventcatalog.dev/docs/development/sdk)
+- [Join the community](https://discord.gg/3rjaZMmrAm)
+
+## Found a Problem?
+
+Open an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).
diff --git a/packages/create-eventcatalog/templates/empty/dockerignore b/packages/create-eventcatalog/templates/empty/dockerignore
new file mode 100644
index 000000000..245063830
--- /dev/null
+++ b/packages/create-eventcatalog/templates/empty/dockerignore
@@ -0,0 +1,8 @@
+.eventcatalog-core/
+.git/
+dist/
+node_modules/
+.gitignore
+.dockerignore
+Dockerfile
+README.md
diff --git a/packages/create-eventcatalog/templates/empty/env b/packages/create-eventcatalog/templates/empty/env
new file mode 100644
index 000000000..3ca39cda3
--- /dev/null
+++ b/packages/create-eventcatalog/templates/empty/env
@@ -0,0 +1,9 @@
+# EventCatalog Scale License Key, if you want to unlock the scale features
+# You can get a 14 day trial license key from https://eventcatalog.cloud
+
+EVENTCATALOG_SCALE_LICENSE_KEY=
+
+# Optional key if you are using EventCatalog Chat with OpenAI Models.
+# You need to set `output` to `server` in your eventcatalog.config.js file.
+# See documentation for more details: https://www.eventcatalog.dev/features/ai-assistant
+OPENAI_API_KEY=
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/empty/eventcatalog.auth.js b/packages/create-eventcatalog/templates/empty/eventcatalog.auth.js
new file mode 100644
index 000000000..f97044604
--- /dev/null
+++ b/packages/create-eventcatalog/templates/empty/eventcatalog.auth.js
@@ -0,0 +1,44 @@
+/**
+ * This is an optional file that can add authentication to your EventCatalog.
+ *
+ * To enable authentication you need to set `server:output` in your `eventcatalog.config.js` file.
+ * And then pick which provider you want to use.
+ *
+ * You can read more in the documentation:
+ * https://www.eventcatalog.dev/docs/development/guides/authentication/introduction
+ *
+ */
+
+// export default {
+//   debug: false,
+//   providers: {
+//     // GitHub Authentication
+//     github: {
+//       clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+//       clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+//     },
+//     // Azure AD Entra ID
+//     entra: {
+//       clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
+//       clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
+//       issuer: process.env.AUTH_MICROSOFT_ENTRA_ID_ISSUER,
+//     },
+//     // Google Authentication
+//     google: {
+//       clientId: process.env.AUTH_GOOGLE_ID,
+//       clientSecret: process.env.AUTH_GOOGLE_SECRET,
+//     },
+//     // Auth0 Authentication
+//     auth0: {
+//       clientId: process.env.AUTH_AUTH0_ID,
+//       clientSecret: process.env.AUTH_AUTH0_SECRET,
+//       issuer: process.env.AUTH_AUTH0_ISSUER,
+//     },
+//     // Okta Authentication
+//     okta: {
+//       clientId: process.env.AUTH_OKTA_CLIENT_ID,
+//       clientSecret: process.env.AUTH_OKTA_CLIENT_SECRET,
+//       issuer: process.env.AUTH_OKTA_ISSUER,
+//     },
+//   },
+// }
diff --git a/packages/create-eventcatalog/templates/empty/eventcatalog.config.js b/packages/create-eventcatalog/templates/empty/eventcatalog.config.js
new file mode 100644
index 000000000..b3850dcdc
--- /dev/null
+++ b/packages/create-eventcatalog/templates/empty/eventcatalog.config.js
@@ -0,0 +1,41 @@
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  title: 'EventCatalog',
+  tagline:
+    'This internal platform provides a comprehensive view of our event-driven architecture across all systems. Use this portal to discover existing domains, explore services and their dependencies, and understand the message contracts that connect our infrastructure',
+  organizationName: '<organizationName>',
+  theme: 'sunset',
+  homepageLink: 'https://eventcatalog.dev/',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  // Supports static or server. Static renders a static site, server renders a server side rendered site
+  // large catalogs may benefit from server side rendering
+  output: 'static',
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: '/',
+  // Resource search is the default lightweight search. Change this to { type: 'indexed' }
+  // to enable full-content search. Indexed search requires running a build to generate the index.
+  search: {
+    type: 'resource',
+  },
+  // Customize the navigation for your docs sidebar.
+  // read more at https://eventcatalog.dev/docs/development/customization/customize-sidebars/documentation-sidebar
+  navigation: {
+    pages: ['list:all'],
+  },
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'EventCatalog',
+  },
+  // This lets you copy markdown contents from EventCatalog to your clipboard
+  // Including schemas for your events and services
+  llmsTxt: {
+    enabled: true,
+  },
+  // required random generated id used by eventcatalog
+  cId: '<cId>',
+};
diff --git a/packages/create-eventcatalog/templates/empty/eventcatalog.styles.css b/packages/create-eventcatalog/templates/empty/eventcatalog.styles.css
new file mode 100644
index 000000000..0d75d2602
--- /dev/null
+++ b/packages/create-eventcatalog/templates/empty/eventcatalog.styles.css
@@ -0,0 +1 @@
+/* Custom styling support coming soon. */
diff --git a/packages/create-eventcatalog/templates/empty/gitignore b/packages/create-eventcatalog/templates/empty/gitignore
new file mode 100644
index 000000000..b6eaa6d14
--- /dev/null
+++ b/packages/create-eventcatalog/templates/empty/gitignore
@@ -0,0 +1,29 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.astro
+out
+dist
+
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.eventcatalog-core
+
+.env
+.env-*
+
+exports/*
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/empty/npmrc b/packages/create-eventcatalog/templates/empty/npmrc
new file mode 100644
index 000000000..fa4e09523
--- /dev/null
+++ b/packages/create-eventcatalog/templates/empty/npmrc
@@ -0,0 +1 @@
+strict-peer-dependencies=false
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/empty/public/logo.png b/packages/create-eventcatalog/templates/empty/public/logo.png
new file mode 100644
index 000000000..535b5a0e7
Binary files /dev/null and b/packages/create-eventcatalog/templates/empty/public/logo.png differ
diff --git a/packages/create-eventcatalog/templates/eventbridge/Dockerfile b/packages/create-eventcatalog/templates/eventbridge/Dockerfile
new file mode 100644
index 000000000..3405a94d2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/eventbridge/Dockerfile
@@ -0,0 +1,23 @@
+## Stage 1: Build the app
+FROM node:lts AS build
+
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+# Copy source code
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+# Build the app
+RUN npm run build
+
+
+## Stage 2: Serve app with httpd server
+FROM httpd:2.4
+
+# Copy built app to serve
+COPY --from=build /app/dist /usr/local/apache2/htdocs
diff --git a/packages/create-eventcatalog/templates/eventbridge/Dockerfile.server b/packages/create-eventcatalog/templates/eventbridge/Dockerfile.server
new file mode 100644
index 000000000..8a7332d64
--- /dev/null
+++ b/packages/create-eventcatalog/templates/eventbridge/Dockerfile.server
@@ -0,0 +1,23 @@
+# Use this Docker file if your EventCatalog output is set to `server`.
+# When EventCatalog output is set to `server`, the output will be a node server.
+# This server is required for certain features like the EventCatalog Chat (with your own keys).
+
+FROM node:lts AS runtime
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+RUN npm run build
+
+ENV HOST=0.0.0.0
+ENV PORT=3000
+EXPOSE 3000
+
+# Start the server
+CMD npm run start
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/eventbridge/README-template.md b/packages/create-eventcatalog/templates/eventbridge/README-template.md
new file mode 100644
index 000000000..db6c1e042
--- /dev/null
+++ b/packages/create-eventcatalog/templates/eventbridge/README-template.md
@@ -0,0 +1,54 @@
+# Welcome to EventCatalog
+
+[EventCatalog](https://www.eventcatalog.dev/) is your architecture catalog for distributed systems. This template adds the EventBridge generator so you can import schemas from Amazon EventBridge and document how they connect to your domains, services, and teams.
+
+## Generate Your Catalog
+
+1. Edit `.env` with your AWS settings.
+2. Configure the region and schema registry name in `eventcatalog.config.js`.
+3. Import your EventBridge schemas:
+
+```sh
+npm run generate
+```
+
+4. Start the catalog:
+
+```sh
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view your catalog.
+
+## Edit Your Catalog
+
+Your generated resources are docs-as-code. You can enrich them with ownership, domain context, Markdown, examples, and relationships that are not always available in the source schema.
+
+Prefer a visual workflow? Run `npm run editor` to open the [EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview) and browse, create, or update catalog resources through a GitHub-backed UI.
+
+## Keep It in Sync
+
+Run `npm run generate` whenever your EventBridge schemas change. You can also run the generator in CI so your catalog stays aligned with your registry.
+
+With this integration you can:
+
+- Document EventBridge schemas and events
+- Assign schemas to producers and consumers
+- Connect resources to users and teams
+- Visualize your EventBridge architecture
+
+## Use AI with Architecture Context
+
+EventCatalog gives AI tools structured context about your domains, services, messages, schemas, owners, and flows. Connect an MCP-compatible tool with the [EventCatalog MCP Server](https://www.eventcatalog.dev/docs/development/guides/ai/using-mcp-server).
+
+## Learn by Task
+
+- [EventBridge integration docs](https://www.eventcatalog.dev/docs/plugins/eventbridge/intro)
+- [Use the EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview)
+- [Document a service](https://www.eventcatalog.dev/docs/development/guides/services)
+- [Add events, commands, and queries](https://www.eventcatalog.dev/docs/development/guides/messages/adding-messages)
+- [Join the community](https://discord.gg/3rjaZMmrAm)
+
+## Found a Problem?
+
+Open an issue on [GitHub](https://github.com/event-catalog/generators).
diff --git a/packages/create-eventcatalog/templates/eventbridge/dockerignore b/packages/create-eventcatalog/templates/eventbridge/dockerignore
new file mode 100644
index 000000000..245063830
--- /dev/null
+++ b/packages/create-eventcatalog/templates/eventbridge/dockerignore
@@ -0,0 +1,8 @@
+.eventcatalog-core/
+.git/
+dist/
+node_modules/
+.gitignore
+.dockerignore
+Dockerfile
+README.md
diff --git a/packages/create-eventcatalog/templates/eventbridge/env b/packages/create-eventcatalog/templates/eventbridge/env
new file mode 100644
index 000000000..369ad2602
--- /dev/null
+++ b/packages/create-eventcatalog/templates/eventbridge/env
@@ -0,0 +1,3 @@
+
+# Get 14 day trial license key from https://eventcatalog.cloud/
+EVENTCATALOG_LICENSE_KEY_EVENTBRIDGE=
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/eventbridge/eventcatalog.auth.js b/packages/create-eventcatalog/templates/eventbridge/eventcatalog.auth.js
new file mode 100644
index 000000000..f97044604
--- /dev/null
+++ b/packages/create-eventcatalog/templates/eventbridge/eventcatalog.auth.js
@@ -0,0 +1,44 @@
+/**
+ * This is an optional file that can add authentication to your EventCatalog.
+ *
+ * To enable authentication you need to set `server:output` in your `eventcatalog.config.js` file.
+ * And then pick which provider you want to use.
+ *
+ * You can read more in the documentation:
+ * https://www.eventcatalog.dev/docs/development/guides/authentication/introduction
+ *
+ */
+
+// export default {
+//   debug: false,
+//   providers: {
+//     // GitHub Authentication
+//     github: {
+//       clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+//       clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+//     },
+//     // Azure AD Entra ID
+//     entra: {
+//       clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
+//       clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
+//       issuer: process.env.AUTH_MICROSOFT_ENTRA_ID_ISSUER,
+//     },
+//     // Google Authentication
+//     google: {
+//       clientId: process.env.AUTH_GOOGLE_ID,
+//       clientSecret: process.env.AUTH_GOOGLE_SECRET,
+//     },
+//     // Auth0 Authentication
+//     auth0: {
+//       clientId: process.env.AUTH_AUTH0_ID,
+//       clientSecret: process.env.AUTH_AUTH0_SECRET,
+//       issuer: process.env.AUTH_AUTH0_ISSUER,
+//     },
+//     // Okta Authentication
+//     okta: {
+//       clientId: process.env.AUTH_OKTA_CLIENT_ID,
+//       clientSecret: process.env.AUTH_OKTA_CLIENT_SECRET,
+//       issuer: process.env.AUTH_OKTA_ISSUER,
+//     },
+//   },
+// }
diff --git a/packages/create-eventcatalog/templates/eventbridge/eventcatalog.config.js b/packages/create-eventcatalog/templates/eventbridge/eventcatalog.config.js
new file mode 100644
index 000000000..63fd12060
--- /dev/null
+++ b/packages/create-eventcatalog/templates/eventbridge/eventcatalog.config.js
@@ -0,0 +1,57 @@
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  title: 'EventCatalog',
+  tagline:
+    'This internal platform provides a comprehensive view of our event-driven architecture across all systems. Use this portal to discover EventBridge schemas, services and domains, and understand the message contracts that connect our infrastructure',
+  organizationName: '<organizationName>',
+  theme: 'sunset',
+  homepageLink: 'https://eventcatalog.dev/',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  // Supports static or server. Static renders a static site, server renders a server side rendered site
+  // large catalogs may benefit from server side rendering
+  output: 'static',
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: '/',
+  // Resource search is the default lightweight search. Change this to { type: 'indexed' }
+  // to enable full-content search. Indexed search requires running a build to generate the index.
+  search: {
+    type: 'resource',
+  },
+  // Customize the navigation for your docs sidebar.
+  // read more at https://eventcatalog.dev/docs/development/customization/customize-sidebars/documentation-sidebar
+  navigation: {
+    pages: ['list:all'],
+  },
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'EventCatalog',
+  },
+  // Enable RSS feed for your eventcatalog
+  rss: {
+    enabled: true,
+    // number of items to include in the feed per resource (event, service, etc)
+    limit: 20,
+  },
+  // This lets you copy markdown contents from EventCatalog to your clipboard
+  // Including schemas for your events and services
+  llmsTxt: {
+    enabled: true,
+  },
+  // required random generated id used by eventcatalog
+  cId: '<cId>',
+  // Just import all events into the Catalog from a registry
+  generators: [
+    '@eventcatalog/generator-eventbridge',
+    {
+      // The region of your EventBridge registry
+      region: 'us-east-1',
+      // The name of your EventBridge registry
+      registryName: 'discovered-schemas',
+    },
+  ],
+};
diff --git a/packages/create-eventcatalog/templates/eventbridge/eventcatalog.styles.css b/packages/create-eventcatalog/templates/eventbridge/eventcatalog.styles.css
new file mode 100644
index 000000000..0d75d2602
--- /dev/null
+++ b/packages/create-eventcatalog/templates/eventbridge/eventcatalog.styles.css
@@ -0,0 +1 @@
+/* Custom styling support coming soon. */
diff --git a/packages/create-eventcatalog/templates/eventbridge/gitignore b/packages/create-eventcatalog/templates/eventbridge/gitignore
new file mode 100644
index 000000000..b6eaa6d14
--- /dev/null
+++ b/packages/create-eventcatalog/templates/eventbridge/gitignore
@@ -0,0 +1,29 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.astro
+out
+dist
+
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.eventcatalog-core
+
+.env
+.env-*
+
+exports/*
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/eventbridge/npmrc b/packages/create-eventcatalog/templates/eventbridge/npmrc
new file mode 100644
index 000000000..fa4e09523
--- /dev/null
+++ b/packages/create-eventcatalog/templates/eventbridge/npmrc
@@ -0,0 +1 @@
+strict-peer-dependencies=false
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/eventbridge/public/logo.png b/packages/create-eventcatalog/templates/eventbridge/public/logo.png
new file mode 100644
index 000000000..535b5a0e7
Binary files /dev/null and b/packages/create-eventcatalog/templates/eventbridge/public/logo.png differ
diff --git a/packages/create-eventcatalog/templates/graphql/Dockerfile b/packages/create-eventcatalog/templates/graphql/Dockerfile
new file mode 100644
index 000000000..3405a94d2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/Dockerfile
@@ -0,0 +1,23 @@
+## Stage 1: Build the app
+FROM node:lts AS build
+
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+# Copy source code
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+# Build the app
+RUN npm run build
+
+
+## Stage 2: Serve app with httpd server
+FROM httpd:2.4
+
+# Copy built app to serve
+COPY --from=build /app/dist /usr/local/apache2/htdocs
diff --git a/packages/create-eventcatalog/templates/graphql/Dockerfile.server b/packages/create-eventcatalog/templates/graphql/Dockerfile.server
new file mode 100644
index 000000000..8a7332d64
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/Dockerfile.server
@@ -0,0 +1,23 @@
+# Use this Docker file if your EventCatalog output is set to `server`.
+# When EventCatalog output is set to `server`, the output will be a node server.
+# This server is required for certain features like the EventCatalog Chat (with your own keys).
+
+FROM node:lts AS runtime
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+RUN npm run build
+
+ENV HOST=0.0.0.0
+ENV PORT=3000
+EXPOSE 3000
+
+# Start the server
+CMD npm run start
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/graphql/README-template.md b/packages/create-eventcatalog/templates/graphql/README-template.md
new file mode 100644
index 000000000..2daa8c517
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/README-template.md
@@ -0,0 +1,63 @@
+# Welcome to EventCatalog
+
+[EventCatalog](https://www.eventcatalog.dev/) is your architecture catalog for distributed systems. Use it to document, govern, and discover your services, domains, APIs, events, commands, queries, schemas, teams, and flows in one place.
+
+## Start the Catalog
+
+```sh
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view your catalog.
+
+Using `pnpm` or `yarn`? Run the same scripts with the package manager you chose when creating this project.
+
+## Edit Your Catalog
+
+Your catalog is docs-as-code. Resources live in folders with an `index.mdx` file for frontmatter metadata and Markdown content.
+
+Good places to start:
+
+- `domains/` - bounded contexts, business capabilities, and ownership
+- `domains/<domain>/services/` - services, APIs, and message producers or consumers
+- `events/`, `commands/`, and `queries/` - the messages flowing through your system
+- `teams/` and `users/` - who owns each part of the architecture
+
+Prefer a visual workflow? Run `npm run editor` to open the [EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview) and browse, create, or update catalog resources through a GitHub-backed UI.
+
+## Make Your First Change
+
+1. Add or edit a domain, service, or message.
+2. Run `npm run dev` and check the generated pages and diagrams.
+3. Commit the MDX and schema files to Git.
+
+## Keep It in Sync
+
+Use `npm run generate` with [EventCatalog integrations](https://www.eventcatalog.dev/integrations) to import architecture data from OpenAPI, AsyncAPI, schema registries, EventBridge, GitHub, internal systems, and more.
+
+Run generators locally while you work, or in CI so your catalog stays aligned with the systems it describes.
+
+## Use AI with Architecture Context
+
+EventCatalog gives AI tools structured context about your domains, services, messages, schemas, owners, and flows.
+
+- Connect Claude, Cursor, VS Code, Windsurf, or another MCP-compatible tool with the [EventCatalog MCP Server](https://www.eventcatalog.dev/docs/development/guides/ai/using-mcp-server).
+- Install [EventCatalog Skills](https://github.com/event-catalog/skills) to help agents document services, create domain models, and map business flows:
+
+```sh
+npx skills add event-catalog/skills
+```
+
+## Learn by Task
+
+- [Create a domain](https://www.eventcatalog.dev/docs/development/guides/domains)
+- [Document a service](https://www.eventcatalog.dev/docs/development/guides/services)
+- [Add events, commands, and queries](https://www.eventcatalog.dev/docs/development/guides/messages/adding-messages)
+- [Use the EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview)
+- [Generate from integrations](https://www.eventcatalog.dev/integrations)
+- [Manage your catalog with the SDK](https://www.eventcatalog.dev/docs/development/sdk)
+- [Join the community](https://discord.gg/3rjaZMmrAm)
+
+## Found a Problem?
+
+Open an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).
diff --git a/packages/create-eventcatalog/templates/graphql/dockerignore b/packages/create-eventcatalog/templates/graphql/dockerignore
new file mode 100644
index 000000000..245063830
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/dockerignore
@@ -0,0 +1,8 @@
+.eventcatalog-core/
+.git/
+dist/
+node_modules/
+.gitignore
+.dockerignore
+Dockerfile
+README.md
diff --git a/packages/create-eventcatalog/templates/graphql/env b/packages/create-eventcatalog/templates/graphql/env
new file mode 100644
index 000000000..3ca39cda3
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/env
@@ -0,0 +1,9 @@
+# EventCatalog Scale License Key, if you want to unlock the scale features
+# You can get a 14 day trial license key from https://eventcatalog.cloud
+
+EVENTCATALOG_SCALE_LICENSE_KEY=
+
+# Optional key if you are using EventCatalog Chat with OpenAI Models.
+# You need to set `output` to `server` in your eventcatalog.config.js file.
+# See documentation for more details: https://www.eventcatalog.dev/features/ai-assistant
+OPENAI_API_KEY=
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/graphql/eventcatalog.auth.js b/packages/create-eventcatalog/templates/graphql/eventcatalog.auth.js
new file mode 100644
index 000000000..f97044604
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/eventcatalog.auth.js
@@ -0,0 +1,44 @@
+/**
+ * This is an optional file that can add authentication to your EventCatalog.
+ *
+ * To enable authentication you need to set `server:output` in your `eventcatalog.config.js` file.
+ * And then pick which provider you want to use.
+ *
+ * You can read more in the documentation:
+ * https://www.eventcatalog.dev/docs/development/guides/authentication/introduction
+ *
+ */
+
+// export default {
+//   debug: false,
+//   providers: {
+//     // GitHub Authentication
+//     github: {
+//       clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+//       clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+//     },
+//     // Azure AD Entra ID
+//     entra: {
+//       clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
+//       clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
+//       issuer: process.env.AUTH_MICROSOFT_ENTRA_ID_ISSUER,
+//     },
+//     // Google Authentication
+//     google: {
+//       clientId: process.env.AUTH_GOOGLE_ID,
+//       clientSecret: process.env.AUTH_GOOGLE_SECRET,
+//     },
+//     // Auth0 Authentication
+//     auth0: {
+//       clientId: process.env.AUTH_AUTH0_ID,
+//       clientSecret: process.env.AUTH_AUTH0_SECRET,
+//       issuer: process.env.AUTH_AUTH0_ISSUER,
+//     },
+//     // Okta Authentication
+//     okta: {
+//       clientId: process.env.AUTH_OKTA_CLIENT_ID,
+//       clientSecret: process.env.AUTH_OKTA_CLIENT_SECRET,
+//       issuer: process.env.AUTH_OKTA_ISSUER,
+//     },
+//   },
+// }
diff --git a/packages/create-eventcatalog/templates/graphql/eventcatalog.config.js b/packages/create-eventcatalog/templates/graphql/eventcatalog.config.js
new file mode 100644
index 000000000..263034c84
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/eventcatalog.config.js
@@ -0,0 +1,76 @@
+import path from 'path';
+import url from 'url';
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  title: 'EventCatalog',
+  tagline:
+    'This internal platform provides a comprehensive view of our event-driven architecture across all systems. Use this portal to discover existing domains, explore services and their dependencies, and understand the message contracts that connect our infrastructure',
+  organizationName: '<organizationName>',
+  theme: 'sunset',
+  homepageLink: 'https://eventcatalog.dev/',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  // Supports static or server. Static renders a static site, server renders a server side rendered site
+  // large catalogs may benefit from server side rendering
+  output: 'static',
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: '/',
+  // Resource search is the default lightweight search. Change this to { type: 'indexed' }
+  // to enable full-content search. Indexed search requires running a build to generate the index.
+  search: {
+    type: 'resource',
+  },
+  // Customize the navigation for your docs sidebar.
+  // read more at https://eventcatalog.dev/docs/development/customization/customize-sidebars/documentation-sidebar
+  navigation: {
+    pages: ['list:all'],
+  },
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'EventCatalog',
+  },
+  // This lets you copy markdown contents from EventCatalog to your clipboard
+  // Including schemas for your events and services
+  llmsTxt: {
+    enabled: true,
+  },
+  generators: [
+    [
+      '@eventcatalog/generator-graphql',
+      {
+        services: [
+          {
+            path: path.join(__dirname, 'graphql-files', 'orders-service.graphql'),
+            id: 'orders-service',
+            version: '0.0.1',
+            owners: ['order-management'],
+          },
+        ],
+        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+      },
+    ],
+    [
+      '@eventcatalog/generator-graphql',
+      {
+        services: [
+          {
+            path: path.join(__dirname, 'graphql-files', 'payment-service.graphql'),
+            id: 'payment-service',
+            version: '0.0.1',
+            owners: ['payment-management'],
+          },
+        ],
+        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
+      },
+    ],
+  ],
+  // required random generated id used by eventcatalog
+  cId: '<cId>',
+};
diff --git a/packages/create-eventcatalog/templates/graphql/eventcatalog.styles.css b/packages/create-eventcatalog/templates/graphql/eventcatalog.styles.css
new file mode 100644
index 000000000..0d75d2602
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/eventcatalog.styles.css
@@ -0,0 +1 @@
+/* Custom styling support coming soon. */
diff --git a/packages/create-eventcatalog/templates/graphql/gitignore b/packages/create-eventcatalog/templates/graphql/gitignore
new file mode 100644
index 000000000..b6eaa6d14
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/gitignore
@@ -0,0 +1,29 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.astro
+out
+dist
+
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.eventcatalog-core
+
+.env
+.env-*
+
+exports/*
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/graphql/graphql-files/orders-service.graphql b/packages/create-eventcatalog/templates/graphql/graphql-files/orders-service.graphql
new file mode 100644
index 000000000..32e22940f
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/graphql-files/orders-service.graphql
@@ -0,0 +1,76 @@
+type Query {
+  """
+  Fetch a user by their unique ID
+  """
+  getUser(id: ID!): User
+  """
+  Retrieve all users from the system
+  """
+  getUsers: [User!]!
+  """
+  Get user profile information by user ID
+  """
+  getProfile(userId: ID!): Profile
+}
+
+type Mutation {
+  """
+  Create a new user account
+  """
+  createUser(input: CreateUserInput!): User
+  """
+  Update an existing user's information
+  """
+  updateUser(id: ID!, input: UpdateUserInput!): User
+  """
+  Delete a user from the system
+  """
+  deleteUser(id: ID!): Boolean
+  """
+  Update user profile details
+  """
+  updateProfile(userId: ID!, input: UpdateProfileInput!): Profile
+}
+
+type Subscription {
+  """
+  Subscribe to user creation events
+  """
+  userCreated: User
+  """
+  Subscribe to user update events
+  """
+  userUpdated: User
+  """
+  Triggered when a user is deleted
+  """
+  userDeleted: ID
+}
+
+type User {
+  id: ID!
+  name: String!
+  email: String!
+  profile: Profile
+}
+
+type Profile {
+  id: ID!
+  bio: String
+  avatar: String
+}
+
+input CreateUserInput {
+  name: String!
+  email: String!
+}
+
+input UpdateUserInput {
+  name: String
+  email: String
+}
+
+input UpdateProfileInput {
+  bio: String
+  avatar: String
+}
diff --git a/packages/create-eventcatalog/templates/graphql/graphql-files/payment-service.graphql b/packages/create-eventcatalog/templates/graphql/graphql-files/payment-service.graphql
new file mode 100644
index 000000000..3fa25372e
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/graphql-files/payment-service.graphql
@@ -0,0 +1,327 @@
+type Query {
+  """
+  Fetch a payment by its unique ID
+  """
+  getPayment(id: ID!): Payment
+  """
+  Retrieve all payments for a specific user
+  """
+  getPaymentsByUser(userId: ID!): [Payment!]!
+  """
+  Get payment history with optional filtering
+  """
+  getPaymentHistory(
+    userId: ID
+    status: PaymentStatus
+    dateFrom: String
+    dateTo: String
+    limit: Int = 10
+    offset: Int = 0
+  ): PaymentConnection!
+  """
+  Fetch payment methods for a user
+  """
+  getPaymentMethods(userId: ID!): [PaymentMethod!]!
+  """
+  Get a specific payment method by ID
+  """
+  getPaymentMethod(id: ID!): PaymentMethod
+  """
+  Retrieve transaction details by ID
+  """
+  getTransaction(id: ID!): Transaction
+  """
+  Get all transactions for a payment
+  """
+  getTransactionsByPayment(paymentId: ID!): [Transaction!]!
+  """
+  Check payment status and details
+  """
+  getPaymentStatus(paymentId: ID!): PaymentStatusResponse!
+}
+
+type Mutation {
+  """
+  Process a new payment
+  """
+  processPayment(input: ProcessPaymentInput!): PaymentResult!
+  """
+  Refund a payment (full or partial)
+  """
+  refundPayment(input: RefundPaymentInput!): RefundResult!
+  """
+  Add a new payment method for a user
+  """
+  addPaymentMethod(input: AddPaymentMethodInput!): PaymentMethod!
+  """
+  Update an existing payment method
+  """
+  updatePaymentMethod(id: ID!, input: UpdatePaymentMethodInput!): PaymentMethod!
+  """
+  Remove a payment method
+  """
+  removePaymentMethod(id: ID!): Boolean!
+  """
+  Set a payment method as default
+  """
+  setDefaultPaymentMethod(userId: ID!, paymentMethodId: ID!): PaymentMethod!
+  """
+  Cancel a pending payment
+  """
+  cancelPayment(paymentId: ID!): Payment!
+  """
+  Retry a failed payment
+  """
+  retryPayment(paymentId: ID!): PaymentResult!
+  """
+  Capture an authorized payment
+  """
+  capturePayment(paymentId: ID!, amount: Float): Payment!
+}
+
+type Subscription {
+  """
+  Subscribe to payment status updates
+  """
+  paymentStatusUpdated(paymentId: ID!): Payment!
+  """
+  Subscribe to all payment events for a user
+  """
+  userPaymentEvents(userId: ID!): PaymentEvent!
+  """
+  Subscribe to transaction updates
+  """
+  transactionUpdated(transactionId: ID!): Transaction!
+  """
+  Subscribe to refund status changes
+  """
+  refundStatusUpdated(refundId: ID!): Refund!
+}
+
+type Payment {
+  id: ID!
+  userId: ID!
+  amount: Float!
+  currency: String!
+  status: PaymentStatus!
+  description: String
+  paymentMethod: PaymentMethod!
+  transactions: [Transaction!]!
+  refunds: [Refund!]!
+  metadata: PaymentMetadata
+  createdAt: String!
+  updatedAt: String!
+  expiresAt: String
+}
+
+type PaymentMethod {
+  id: ID!
+  userId: ID!
+  type: PaymentMethodType!
+  isDefault: Boolean!
+  card: CardDetails
+  bankAccount: BankAccountDetails
+  digitalWallet: DigitalWalletDetails
+  isActive: Boolean!
+  createdAt: String!
+  updatedAt: String!
+}
+
+type CardDetails {
+  last4: String!
+  brand: String!
+  expiryMonth: Int!
+  expiryYear: Int!
+  fingerprint: String!
+  country: String
+}
+
+type BankAccountDetails {
+  last4: String!
+  bankName: String!
+  accountType: String!
+  country: String!
+}
+
+type DigitalWalletDetails {
+  provider: String!
+  email: String
+}
+
+type Transaction {
+  id: ID!
+  paymentId: ID!
+  type: TransactionType!
+  amount: Float!
+  currency: String!
+  status: TransactionStatus!
+  gateway: String!
+  gatewayTransactionId: String
+  failureReason: String
+  createdAt: String!
+  updatedAt: String!
+}
+
+type Refund {
+  id: ID!
+  paymentId: ID!
+  amount: Float!
+  currency: String!
+  status: RefundStatus!
+  reason: String
+  createdAt: String!
+  updatedAt: String!
+}
+
+type PaymentConnection {
+  edges: [PaymentEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type PaymentEdge {
+  node: Payment!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+
+type PaymentMetadata {
+  orderId: String
+  customerId: String
+  invoiceId: String
+  tags: [String!]
+  notes: String
+}
+
+type PaymentResult {
+  payment: Payment
+  success: Boolean!
+  error: PaymentError
+  requiresAction: Boolean!
+  actionUrl: String
+}
+
+type RefundResult {
+  refund: Refund
+  success: Boolean!
+  error: PaymentError
+}
+
+type PaymentStatusResponse {
+  payment: Payment!
+  canRefund: Boolean!
+  canCapture: Boolean!
+  canCancel: Boolean!
+}
+
+type PaymentEvent {
+  id: ID!
+  type: PaymentEventType!
+  paymentId: ID!
+  data: String!
+  createdAt: String!
+}
+
+type PaymentError {
+  code: String!
+  message: String!
+  details: String
+}
+
+enum PaymentStatus {
+  PENDING
+  PROCESSING
+  AUTHORIZED
+  CAPTURED
+  SUCCEEDED
+  FAILED
+  CANCELLED
+  EXPIRED
+  REFUNDED
+  PARTIALLY_REFUNDED
+}
+
+enum PaymentMethodType {
+  CREDIT_CARD
+  DEBIT_CARD
+  BANK_ACCOUNT
+  DIGITAL_WALLET
+  CRYPTOCURRENCY
+}
+
+enum TransactionType {
+  AUTHORIZATION
+  CAPTURE
+  SALE
+  REFUND
+  VOID
+}
+
+enum TransactionStatus {
+  PENDING
+  SUCCEEDED
+  FAILED
+  CANCELLED
+}
+
+enum RefundStatus {
+  PENDING
+  PROCESSING
+  SUCCEEDED
+  FAILED
+  CANCELLED
+}
+
+enum PaymentEventType {
+  PAYMENT_CREATED
+  PAYMENT_AUTHORIZED
+  PAYMENT_CAPTURED
+  PAYMENT_SUCCEEDED
+  PAYMENT_FAILED
+  PAYMENT_CANCELLED
+  REFUND_CREATED
+  REFUND_SUCCEEDED
+  REFUND_FAILED
+}
+
+input ProcessPaymentInput {
+  userId: ID!
+  amount: Float!
+  currency: String!
+  paymentMethodId: ID!
+  description: String
+  captureImmediately: Boolean = true
+  metadata: PaymentMetadataInput
+}
+
+input RefundPaymentInput {
+  paymentId: ID!
+  amount: Float
+  reason: String
+}
+
+input AddPaymentMethodInput {
+  userId: ID!
+  type: PaymentMethodType!
+  token: String!
+  setAsDefault: Boolean = false
+}
+
+input UpdatePaymentMethodInput {
+  isActive: Boolean
+  setAsDefault: Boolean
+}
+
+input PaymentMetadataInput {
+  orderId: String
+  customerId: String
+  invoiceId: String
+  tags: [String!]
+  notes: String
+}
diff --git a/packages/create-eventcatalog/templates/graphql/npmrc b/packages/create-eventcatalog/templates/graphql/npmrc
new file mode 100644
index 000000000..fa4e09523
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/npmrc
@@ -0,0 +1 @@
+strict-peer-dependencies=false
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/graphql/public/logo.png b/packages/create-eventcatalog/templates/graphql/public/logo.png
new file mode 100644
index 000000000..535b5a0e7
Binary files /dev/null and b/packages/create-eventcatalog/templates/graphql/public/logo.png differ
diff --git a/packages/create-eventcatalog/templates/graphql/teams/order-management.mdx b/packages/create-eventcatalog/templates/graphql/teams/order-management.mdx
new file mode 100644
index 000000000..586d8cdaf
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/teams/order-management.mdx
@@ -0,0 +1,31 @@
+---
+id: order-management
+name: Order Management
+summmary: Order Management team based in London, UK
+members:
+  - dboyne
+  - asmith
+  - msmith
+  - alee
+  - azhang
+email: test@test.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+---
+
+## Overview
+
+The Order Management team is responsible for managing orders, inventory, shipment and payment.
+
+## Responsibilities
+
+- Manage orders and order processing
+- Manage inventory and inventory processing
+- Manage shipment and shipment processing
+- Manage payment and payment processing
+- Manage user and user processing
+
+## Key Contacts
+
+- David Boyne
+- Alice Smith
+- Mike Smith
diff --git a/packages/create-eventcatalog/templates/graphql/teams/payment-management.mdx b/packages/create-eventcatalog/templates/graphql/teams/payment-management.mdx
new file mode 100644
index 000000000..da065ec2c
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/teams/payment-management.mdx
@@ -0,0 +1,18 @@
+---
+id: payment-management
+name: Payment Management
+members:
+  - dboyne
+  - jbrown
+  - dkim
+---
+
+The payment management team is responsible for managing payments and payment accounts.
+
+## Responsibilities
+
+- Manage payment and payment account management
+- Manage payment and payment account provisioning
+- Manage payment and payment account deprovisioning
+- Manage user and user account password management
+- Manage user and user account role management
diff --git a/packages/create-eventcatalog/templates/graphql/teams/product-management.mdx b/packages/create-eventcatalog/templates/graphql/teams/product-management.mdx
new file mode 100644
index 000000000..e9ae9db13
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/teams/product-management.mdx
@@ -0,0 +1,18 @@
+---
+id: product-management
+name: Product Management
+members:
+  - dboyne
+  - jbrown
+  - dkim
+---
+
+The product management team is responsible for managing products and product accounts.
+
+## Responsibilities
+
+- Manage product and product account management
+- Manage product and product account provisioning
+- Manage product and product account deprovisioning
+- Manage product and product account password management
+- Manage product and product account role management
diff --git a/packages/create-eventcatalog/templates/graphql/users/aSmith.mdx b/packages/create-eventcatalog/templates/graphql/users/aSmith.mdx
new file mode 100644
index 000000000..db9809431
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/users/aSmith.mdx
@@ -0,0 +1,26 @@
+---
+id: asmith
+name: Amy Smith
+avatarUrl: https://randomuser.me/api/portraits/women/48.jpg
+role: Product owner
+---
+
+Hello! I'm Amy Smith, the Product Owner of the innovative Full Stackers team. With a strong focus on delivering exceptional value, I specialize in connecting business objectives with technical solutions to create products that users love.
+
+### About Me
+
+With a comprehensive background in product management and a solid understanding of software development, I bring a unique perspective to the table. My career has been driven by a passion for understanding user needs, defining clear product visions, and leading teams to successful product deliveries.
+
+### What I Do
+
+As the Product Owner for Full Stackers, my role involves a wide range of responsibilities aimed at ensuring our products are both high-quality and user-centric. Key aspects of my role include:
+
+- **Product Vision & Strategy**: Defining and communicating the long-term vision and strategy for our products, ensuring alignment with the company's objectives and market demands.
+- **Roadmap Planning**: Developing and maintaining a product roadmap that highlights key features and milestones, prioritizing tasks based on their business value and user feedback.
+- **Stakeholder Management**: Engaging with stakeholders across the organization to gather requirements, provide updates, and ensure everyone is aligned on the product's direction.
+- **User-Centric Design**: Championing the end-users by conducting user research, analyzing feedback, and ensuring our products effectively solve their problems.
+- **Agile Leadership**: Leading the development process using Agile methodologies, facilitating sprint planning, and ensuring the team has clear priorities and objectives.
+
+My mission is to deliver products that not only meet but exceed customer expectations. I thrive on the challenge of translating complex requirements into simple, intuitive solutions.
+
+If you’re interested in product management, user experience, or discussing the latest trends in technology, feel free to reach out!
diff --git a/packages/create-eventcatalog/templates/graphql/users/alee.mdx b/packages/create-eventcatalog/templates/graphql/users/alee.mdx
new file mode 100644
index 000000000..ae34f1820
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/users/alee.mdx
@@ -0,0 +1,8 @@
+---
+id: alee
+name: Alice Lee
+avatarUrl: https://randomuser.me/api/portraits/women/91.jpg
+role: Technical Writer
+---
+
+As a Technical Writer on the Documentation team, I create clear, comprehensive documentation for our products and APIs. My focus is on making complex technical concepts accessible to developers and end-users alike. I collaborate with engineering teams to ensure our documentation stays current and accurate.
diff --git a/packages/create-eventcatalog/templates/graphql/users/azhang.mdx b/packages/create-eventcatalog/templates/graphql/users/azhang.mdx
new file mode 100644
index 000000000..0f0a15616
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/users/azhang.mdx
@@ -0,0 +1,11 @@
+---
+id: azhang
+name: Alice Zhang
+avatarUrl: https://randomuser.me/api/portraits/women/97.jpg
+role: Data Engineer
+email: azhang@company.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/azhang
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=azhang@company.com
+---
+
+Building and maintaining data pipelines and infrastructure...
diff --git a/packages/create-eventcatalog/templates/graphql/users/dboyne.mdx b/packages/create-eventcatalog/templates/graphql/users/dboyne.mdx
new file mode 100644
index 000000000..26d8eddb4
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/users/dboyne.mdx
@@ -0,0 +1,33 @@
+---
+id: dboyne
+name: David Boyne
+avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png'
+role: Lead developer
+email: test@test.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+---
+
+Hello! I'm David Boyne, the Tech Lead of an amazing team called Full Stackers. With a passion for building robust and scalable systems, I specialize in designing and implementing event-driven architectures that power modern, responsive applications.
+
+### About Me
+
+With over a decade of experience in the tech industry, I have honed my skills in full-stack development, cloud computing, and distributed systems. My journey has taken me through various roles, from software engineer to architect, and now as a tech lead, I am committed to driving innovation and excellence within my team.
+
+### What I Do
+
+At Full Stackers, we focus on creating seamless and efficient event-driven architectures that enhance the performance and scalability of our applications. My role involves:
+
+- **Architecture Design**: Crafting scalable and resilient system architectures using event-driven paradigms.
+- **Team Leadership**: Guiding a talented team of developers, fostering a collaborative and innovative environment.
+- **Code Reviews & Mentorship**: Ensuring code quality and sharing knowledge to help the team grow.
+- **Stakeholder Collaboration**: Working closely with other teams and stakeholders to align our technical solutions with business goals.
+- **Continuous Improvement**: Advocating for best practices in software development, deployment, and monitoring.
+
+I am passionate about leveraging the power of events to build systems that are not only highly responsive but also easier to maintain and extend. In an ever-evolving tech landscape, I strive to stay ahead of the curve, continuously learning and adapting to new technologies and methodologies.
+
+Feel free to connect with me to discuss all things tech, event-driven architectures, or to exchange ideas on building better software systems!
+
+---
+
+_David Boyne_
+_Tech Lead, Full Stackers_
diff --git a/packages/create-eventcatalog/templates/graphql/users/dkim.mdx b/packages/create-eventcatalog/templates/graphql/users/dkim.mdx
new file mode 100644
index 000000000..bbdf71b61
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/users/dkim.mdx
@@ -0,0 +1,11 @@
+---
+id: dkim
+name: David Kim
+avatarUrl: https://randomuser.me/api/portraits/men/96.jpg
+role: Performance Engineer
+email: dkim@company.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/dkim
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=dkim@company.com
+---
+
+Optimizing application performance and user experience...
diff --git a/packages/create-eventcatalog/templates/graphql/users/jbrown.mdx b/packages/create-eventcatalog/templates/graphql/users/jbrown.mdx
new file mode 100644
index 000000000..149232154
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/users/jbrown.mdx
@@ -0,0 +1,11 @@
+---
+id: jbrown
+name: Jessica Brown
+avatarUrl: https://randomuser.me/api/portraits/women/95.jpg
+role: UI/UX Designer
+email: jbrown@company.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/jbrown
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=jbrown@company.com
+---
+
+Creating intuitive and engaging user interfaces...
diff --git a/packages/create-eventcatalog/templates/graphql/users/mSmith.mdx b/packages/create-eventcatalog/templates/graphql/users/mSmith.mdx
new file mode 100644
index 000000000..635e036f1
--- /dev/null
+++ b/packages/create-eventcatalog/templates/graphql/users/mSmith.mdx
@@ -0,0 +1,8 @@
+---
+id: msmith
+name: Martin Smith
+avatarUrl: 'https://randomuser.me/api/portraits/men/51.jpg'
+role: Senior software engineer
+---
+
+As a Senior Mobile Developer on The Mobile Devs team, I play a key role in designing, developing, and maintaining our company’s mobile applications. My focus is on creating a seamless and intuitive user experience for our customers on both iOS and Android platforms. I work closely with cross-functional teams, including backend developers, UX/UI designers, and product managers, to deliver high-quality mobile solutions that meet business objectives and exceed user expectations.
diff --git a/packages/create-eventcatalog/templates/index.ts b/packages/create-eventcatalog/templates/index.ts
new file mode 100644
index 000000000..3de7b5569
--- /dev/null
+++ b/packages/create-eventcatalog/templates/index.ts
@@ -0,0 +1,166 @@
+import { copy } from '../helpers/copy';
+import { install } from '../helpers/install';
+
+import os from 'os';
+import fs from 'fs';
+import path from 'path';
+import { v4 } from 'uuid';
+
+import { GetTemplateFileArgs, InstallTemplateArgs } from './types';
+import { raiseEvent } from './analytics';
+
+/**
+ * Get the file path for a given file in a template, e.g. "next.config.js".
+ */
+export const getTemplateFile = ({ template, mode, file }: GetTemplateFileArgs): string => {
+  return path.join(__dirname, template, mode, file);
+};
+
+const AGENT_RULES = `<!-- BEGIN:eventcatalog-agent-rules -->
+# EventCatalog: ALWAYS read docs before coding
+
+Before any EventCatalog work, find and read the relevant doc in \`node_modules/@eventcatalog/core/dist/docs/\`. Your training data may be outdated. The bundled docs are the source of truth.
+
+<!-- END:eventcatalog-agent-rules -->
+`;
+
+const CLAUDE_RULES = '@AGENTS.md\n';
+
+/**
+ * Install a Next.js internal template to a given `root` directory.
+ */
+export const installTemplate = async ({
+  appName,
+  root,
+  packageManager,
+  isOnline,
+  template,
+  mode,
+  eslint,
+  organizationName,
+}: InstallTemplateArgs) => {
+  /**
+   * Create a package.json for the new project
+   */
+  const packageJson = {
+    name: appName,
+    version: '0.1.0',
+    private: true,
+    scripts: {
+      dev: 'eventcatalog dev',
+      editor: 'npx @eventcatalog/editor@latest',
+      build: 'eventcatalog build',
+      start: 'eventcatalog start',
+      preview: 'eventcatalog preview',
+      generate: 'eventcatalog generate',
+      export: 'eventcatalog export',
+      lint: 'eventcatalog-linter',
+      test: 'echo "Error: no test specified" && exit 1',
+    },
+  };
+  /**
+   * Write it to disk.
+   */
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify(packageJson, null, 2) + os.EOL);
+  /**
+   * These flags will be passed to `install()`, which calls the package manager
+   * install process.
+   */
+  const installFlags = { packageManager, isOnline };
+
+  /**
+   * Default dependencies.
+   */
+  // const dependencies = ["@eventcatalog/eventcatalog-2"];
+  const dependencies = ['@eventcatalog/core', '@eventcatalog/linter'] as any;
+
+  // if asyncapi is selected, add the asyncapi dependencies
+  if (template === 'asyncapi') {
+    dependencies.push('@eventcatalog/generator-asyncapi');
+  }
+
+  if (template === 'openapi') {
+    dependencies.push('@eventcatalog/generator-openapi');
+  }
+
+  if (template === 'graphql') {
+    dependencies.push('@eventcatalog/generator-graphql');
+  }
+
+  if (template === 'confluent') {
+    dependencies.push('@eventcatalog/generator-confluent-schema-registry');
+  }
+
+  if (template === 'eventbridge') {
+    dependencies.push('@eventcatalog/generator-eventbridge');
+  }
+
+  if (template === 'amazon-apigateway') {
+    dependencies.push('@eventcatalog/generator-amazon-apigateway');
+    dependencies.push('@eventcatalog/generator-openapi');
+  }
+
+  // "@myuser/my-package": "file:../lib"
+  const devDependencies = [] as any;
+
+  /**
+   * Install package.json dependencies if they exist.
+   */
+  if (dependencies.length) {
+    await install(root, dependencies, installFlags);
+  }
+
+  if (devDependencies.length) {
+    const devInstallFlags = { devDependencies: true, ...installFlags };
+    await install(root, devDependencies, devInstallFlags);
+  }
+  /**
+   * Copy the template files to the target directory.
+   */
+  const templatePath = path.join(__dirname, '../templates', template);
+  // console.log("templatePath", templatePath, __dirname, template);
+  await copy('**', root, {
+    parents: true,
+    cwd: templatePath,
+    rename: (name) => {
+      switch (name) {
+        case 'env':
+        case 'gitignore':
+        case 'npmrc':
+        case 'dockerignore':
+        case 'eslintrc.json': {
+          return '.'.concat(name);
+        }
+        // README.md is ignored by webpack-asset-relocator-loader used by ncc:
+        // https://github.com/vercel/webpack-asset-relocator-loader/blob/e9308683d47ff507253e37c9bcbb99474603192b/src/asset-relocator.js#L227
+        case 'README-template.md': {
+          return 'README.md';
+        }
+        default: {
+          return name;
+        }
+      }
+    },
+  });
+
+  fs.writeFileSync(path.join(root, 'AGENTS.md'), AGENT_RULES);
+  fs.writeFileSync(path.join(root, 'CLAUDE.md'), CLAUDE_RULES);
+
+  const cId = v4();
+
+  // update the properties in the eventcatalog.config.js
+  const eventCatalogConfigPath = path.join(root, 'eventcatalog.config.js');
+  let eventCatalogConfig = fs.readFileSync(eventCatalogConfigPath, 'utf8');
+  eventCatalogConfig = eventCatalogConfig.replace(/<organizationName>/g, organizationName);
+  eventCatalogConfig = eventCatalogConfig.replace(/<cId>/g, cId);
+  fs.writeFileSync(eventCatalogConfigPath, eventCatalogConfig);
+
+  await raiseEvent({ command: 'create', org: organizationName, cId });
+
+  if (!eslint) {
+    // remove un-necessary template file if eslint is not desired
+    await fs.promises.unlink(path.join(root, '.eslintrc.json'));
+  }
+};
+
+export * from './types';
diff --git a/packages/create-eventcatalog/templates/openapi/Dockerfile b/packages/create-eventcatalog/templates/openapi/Dockerfile
new file mode 100644
index 000000000..3405a94d2
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/Dockerfile
@@ -0,0 +1,23 @@
+## Stage 1: Build the app
+FROM node:lts AS build
+
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+# Copy source code
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+# Build the app
+RUN npm run build
+
+
+## Stage 2: Serve app with httpd server
+FROM httpd:2.4
+
+# Copy built app to serve
+COPY --from=build /app/dist /usr/local/apache2/htdocs
diff --git a/packages/create-eventcatalog/templates/openapi/Dockerfile.server b/packages/create-eventcatalog/templates/openapi/Dockerfile.server
new file mode 100644
index 000000000..8a7332d64
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/Dockerfile.server
@@ -0,0 +1,23 @@
+# Use this Docker file if your EventCatalog output is set to `server`.
+# When EventCatalog output is set to `server`, the output will be a node server.
+# This server is required for certain features like the EventCatalog Chat (with your own keys).
+
+FROM node:lts AS runtime
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm install
+
+COPY . .
+
+# Fix for Astro in Docker: https://github.com/withastro/astro/issues/2596
+ENV NODE_OPTIONS=--max_old_space_size=2048
+RUN npm run build
+
+ENV HOST=0.0.0.0
+ENV PORT=3000
+EXPOSE 3000
+
+# Start the server
+CMD npm run start
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/openapi/README-template.md b/packages/create-eventcatalog/templates/openapi/README-template.md
new file mode 100644
index 000000000..2daa8c517
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/README-template.md
@@ -0,0 +1,63 @@
+# Welcome to EventCatalog
+
+[EventCatalog](https://www.eventcatalog.dev/) is your architecture catalog for distributed systems. Use it to document, govern, and discover your services, domains, APIs, events, commands, queries, schemas, teams, and flows in one place.
+
+## Start the Catalog
+
+```sh
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view your catalog.
+
+Using `pnpm` or `yarn`? Run the same scripts with the package manager you chose when creating this project.
+
+## Edit Your Catalog
+
+Your catalog is docs-as-code. Resources live in folders with an `index.mdx` file for frontmatter metadata and Markdown content.
+
+Good places to start:
+
+- `domains/` - bounded contexts, business capabilities, and ownership
+- `domains/<domain>/services/` - services, APIs, and message producers or consumers
+- `events/`, `commands/`, and `queries/` - the messages flowing through your system
+- `teams/` and `users/` - who owns each part of the architecture
+
+Prefer a visual workflow? Run `npm run editor` to open the [EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview) and browse, create, or update catalog resources through a GitHub-backed UI.
+
+## Make Your First Change
+
+1. Add or edit a domain, service, or message.
+2. Run `npm run dev` and check the generated pages and diagrams.
+3. Commit the MDX and schema files to Git.
+
+## Keep It in Sync
+
+Use `npm run generate` with [EventCatalog integrations](https://www.eventcatalog.dev/integrations) to import architecture data from OpenAPI, AsyncAPI, schema registries, EventBridge, GitHub, internal systems, and more.
+
+Run generators locally while you work, or in CI so your catalog stays aligned with the systems it describes.
+
+## Use AI with Architecture Context
+
+EventCatalog gives AI tools structured context about your domains, services, messages, schemas, owners, and flows.
+
+- Connect Claude, Cursor, VS Code, Windsurf, or another MCP-compatible tool with the [EventCatalog MCP Server](https://www.eventcatalog.dev/docs/development/guides/ai/using-mcp-server).
+- Install [EventCatalog Skills](https://github.com/event-catalog/skills) to help agents document services, create domain models, and map business flows:
+
+```sh
+npx skills add event-catalog/skills
+```
+
+## Learn by Task
+
+- [Create a domain](https://www.eventcatalog.dev/docs/development/guides/domains)
+- [Document a service](https://www.eventcatalog.dev/docs/development/guides/services)
+- [Add events, commands, and queries](https://www.eventcatalog.dev/docs/development/guides/messages/adding-messages)
+- [Use the EventCatalog Editor](https://www.eventcatalog.dev/docs/editor/overview)
+- [Generate from integrations](https://www.eventcatalog.dev/integrations)
+- [Manage your catalog with the SDK](https://www.eventcatalog.dev/docs/development/sdk)
+- [Join the community](https://discord.gg/3rjaZMmrAm)
+
+## Found a Problem?
+
+Open an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).
diff --git a/packages/create-eventcatalog/templates/openapi/dockerignore b/packages/create-eventcatalog/templates/openapi/dockerignore
new file mode 100644
index 000000000..245063830
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/dockerignore
@@ -0,0 +1,8 @@
+.eventcatalog-core/
+.git/
+dist/
+node_modules/
+.gitignore
+.dockerignore
+Dockerfile
+README.md
diff --git a/packages/create-eventcatalog/templates/openapi/env b/packages/create-eventcatalog/templates/openapi/env
new file mode 100644
index 000000000..3ca39cda3
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/env
@@ -0,0 +1,9 @@
+# EventCatalog Scale License Key, if you want to unlock the scale features
+# You can get a 14 day trial license key from https://eventcatalog.cloud
+
+EVENTCATALOG_SCALE_LICENSE_KEY=
+
+# Optional key if you are using EventCatalog Chat with OpenAI Models.
+# You need to set `output` to `server` in your eventcatalog.config.js file.
+# See documentation for more details: https://www.eventcatalog.dev/features/ai-assistant
+OPENAI_API_KEY=
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/openapi/eventcatalog.auth.js b/packages/create-eventcatalog/templates/openapi/eventcatalog.auth.js
new file mode 100644
index 000000000..f97044604
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/eventcatalog.auth.js
@@ -0,0 +1,44 @@
+/**
+ * This is an optional file that can add authentication to your EventCatalog.
+ *
+ * To enable authentication you need to set `server:output` in your `eventcatalog.config.js` file.
+ * And then pick which provider you want to use.
+ *
+ * You can read more in the documentation:
+ * https://www.eventcatalog.dev/docs/development/guides/authentication/introduction
+ *
+ */
+
+// export default {
+//   debug: false,
+//   providers: {
+//     // GitHub Authentication
+//     github: {
+//       clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+//       clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+//     },
+//     // Azure AD Entra ID
+//     entra: {
+//       clientId: process.env.AUTH_MICROSOFT_ENTRA_ID_ID,
+//       clientSecret: process.env.AUTH_MICROSOFT_ENTRA_ID_SECRET,
+//       issuer: process.env.AUTH_MICROSOFT_ENTRA_ID_ISSUER,
+//     },
+//     // Google Authentication
+//     google: {
+//       clientId: process.env.AUTH_GOOGLE_ID,
+//       clientSecret: process.env.AUTH_GOOGLE_SECRET,
+//     },
+//     // Auth0 Authentication
+//     auth0: {
+//       clientId: process.env.AUTH_AUTH0_ID,
+//       clientSecret: process.env.AUTH_AUTH0_SECRET,
+//       issuer: process.env.AUTH_AUTH0_ISSUER,
+//     },
+//     // Okta Authentication
+//     okta: {
+//       clientId: process.env.AUTH_OKTA_CLIENT_ID,
+//       clientSecret: process.env.AUTH_OKTA_CLIENT_SECRET,
+//       issuer: process.env.AUTH_OKTA_ISSUER,
+//     },
+//   },
+// }
diff --git a/packages/create-eventcatalog/templates/openapi/eventcatalog.config.js b/packages/create-eventcatalog/templates/openapi/eventcatalog.config.js
new file mode 100644
index 000000000..66d1f596a
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/eventcatalog.config.js
@@ -0,0 +1,88 @@
+import path from 'path';
+import url from 'url';
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  title: 'EventCatalog',
+  tagline:
+    'This internal platform provides a comprehensive view of our event-driven architecture across all systems. Use this portal to discover existing domains, explore services and their dependencies, and understand the message contracts that connect our infrastructure',
+  organizationName: '<organizationName>',
+  theme: 'sunset',
+  homepageLink: 'https://eventcatalog.dev/',
+  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
+  // Supports static or server. Static renders a static site, server renders a server side rendered site
+  // large catalogs may benefit from server side rendering
+  output: 'static',
+  // By default set to false, add true to get urls ending in /
+  trailingSlash: false,
+  // Change to make the base url of the site different, by default https://{website}.com/docs,
+  // changing to /company would be https://{website}.com/company/docs,
+  base: '/',
+  // Resource search is the default lightweight search. Change this to { type: 'indexed' }
+  // to enable full-content search. Indexed search requires running a build to generate the index.
+  search: {
+    type: 'resource',
+  },
+  // Customize the navigation for your docs sidebar.
+  // read more at https://eventcatalog.dev/docs/development/customization/customize-sidebars/documentation-sidebar
+  navigation: {
+    pages: ['list:all'],
+  },
+  // Customize the logo, add your logo to public/ folder
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'EventCatalog',
+  },
+  // This lets you copy markdown contents from EventCatalog to your clipboard
+  // Including schemas for your events and services
+  llmsTxt: {
+    enabled: true,
+  },
+  generators: [
+    [
+      '@eventcatalog/generator-openapi',
+      {
+        services: [
+          {
+            path: path.join(__dirname, 'openapi-files', 'product-api.yml'),
+            id: 'product-service',
+            owners: ['product-management'],
+          },
+        ],
+        domain: { id: 'products', name: 'Products', version: '0.0.1' },
+      },
+    ],
+    [
+      '@eventcatalog/generator-openapi',
+      {
+        services: [
+          { path: path.join(__dirname, 'openapi-files', 'order-api.yml'), id: 'order-service', owners: ['order-management'] },
+          { path: path.join(__dirname, 'openapi-files', 'order-history.yml'), id: 'order-history', owners: ['order-management'] },
+        ],
+        domain: {
+          id: 'order-management',
+          name: 'Order management',
+          version: '0.0.1',
+        },
+      },
+    ],
+    [
+      '@eventcatalog/generator-openapi',
+      {
+        services: [
+          {
+            path: path.join(__dirname, 'openapi-files', 'payment-api.yml'),
+            id: 'payment-service',
+            owners: ['payment-management'],
+          },
+        ],
+        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
+      },
+    ],
+  ],
+  // required random generated id used by eventcatalog
+  cId: '<cId>',
+};
diff --git a/packages/create-eventcatalog/templates/openapi/eventcatalog.styles.css b/packages/create-eventcatalog/templates/openapi/eventcatalog.styles.css
new file mode 100644
index 000000000..0d75d2602
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/eventcatalog.styles.css
@@ -0,0 +1 @@
+/* Custom styling support coming soon. */
diff --git a/packages/create-eventcatalog/templates/openapi/gitignore b/packages/create-eventcatalog/templates/openapi/gitignore
new file mode 100644
index 000000000..b6eaa6d14
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/gitignore
@@ -0,0 +1,29 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.astro
+out
+dist
+
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+.eventcatalog-core
+
+.env
+.env-*
+
+exports/*
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/openapi/npmrc b/packages/create-eventcatalog/templates/openapi/npmrc
new file mode 100644
index 000000000..fa4e09523
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/npmrc
@@ -0,0 +1 @@
+strict-peer-dependencies=false
\ No newline at end of file
diff --git a/packages/create-eventcatalog/templates/openapi/openapi-files/cart-api.yml b/packages/create-eventcatalog/templates/openapi/openapi-files/cart-api.yml
new file mode 100644
index 000000000..76e667a44
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/openapi-files/cart-api.yml
@@ -0,0 +1,107 @@
+openapi: 3.0.0
+info:
+  title: Cart API
+  description: API for managing shopping cart operations.
+  version: 1.0.0
+servers:
+  - url: https://api.yourshoppingapp.com/cart
+    description: Cart API Server
+paths:
+  /:
+    get:
+      summary: Retrieve shopping cart
+      description: Get the contents of the user's shopping cart.
+      x-eventcatalog-message-type: query
+      operationId: getCart
+      responses:
+        '200':
+          description: Shopping cart details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Cart'
+    post:
+      summary: Add item to cart
+      description: Add a product to the shopping cart.
+      x-eventcatalog-message-type: command
+      requestBody:
+        description: Product information to add to the cart.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CartItem'
+      responses:
+        '201':
+          description: Product added to cart
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Cart'
+  /{productId}:
+    patch:
+      summary: Update item quantity
+      description: Update the quantity of an item in the cart.
+      x-eventcatalog-message-type: command
+      operationId: updateCartItem
+      parameters:
+        - name: productId
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: Updated quantity
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                quantity:
+                  type: integer
+                  minimum: 1
+      responses:
+        '200':
+          description: Quantity updated
+        '404':
+          description: Product not found in cart
+    delete:
+      summary: Remove item from cart
+      description: Remove a product from the shopping cart.
+      x-eventcatalog-message-type: command
+      parameters:
+        - name: productId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '204':
+          description: Product removed from cart
+components:
+  schemas:
+    Cart:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/CartItem'
+    CartItem:
+      type: object
+      properties:
+        productId:
+          type: string
+        name:
+          type: string
+        quantity:
+          type: integer
+        price:
+          type: number
+          format: float
+      required:
+        - productId
+        - name
+        - quantity
+        - price
diff --git a/packages/create-eventcatalog/templates/openapi/openapi-files/order-api.yml b/packages/create-eventcatalog/templates/openapi/openapi-files/order-api.yml
new file mode 100644
index 000000000..1d927ad63
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/openapi-files/order-api.yml
@@ -0,0 +1,148 @@
+openapi: 3.0.0
+info:
+  title: Order API
+  description: API for managing orders in the shopping application.
+  version: 1.0.0
+servers:
+  - url: https://api.yourshoppingapp.com/orders
+    description: Order API Server
+paths:
+  /:
+    get:
+      summary: Get list of orders
+      description: Retrieve a list of all orders made by the user.
+      x-eventcatalog-message-type: query
+      operationId: listOrders
+      responses:
+        '200':
+          description: A list of orders
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Order'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /{orderId}:
+    get:
+      summary: Get order by ID
+      description: Retrieve details of a specific order.
+      operationId: getOrderById
+      x-eventcatalog-message-type: query
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Order details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+        '404':
+          description: Order not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+    patch:
+      summary: Update order status
+      description: Update the status of an order (e.g., cancel).
+      x-eventcatalog-message-type: command
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: Updated order status
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                status:
+                  type: string
+                  enum: [pending, shipped, delivered, canceled]
+      responses:
+        '200':
+          description: Order status updated
+        '404':
+          description: Order not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+components:
+  schemas:
+    Order:
+      type: object
+      properties:
+        id:
+          type: string
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/CartItem'
+        status:
+          type: string
+          enum: [pending, shipped, delivered, canceled]
+        totalAmount:
+          type: number
+          format: float
+      required:
+        - id
+        - items
+        - status
+        - totalAmount
+    CartItem:
+      type: object
+      properties:
+        productId:
+          type: string
+        name:
+          type: string
+        quantity:
+          type: integer
+        price:
+          type: number
+          format: float
+      required:
+        - productId
+        - name
+        - quantity
+        - price
+    ErrorResponse:
+      type: object
+      properties:
+        code:
+          type: integer
+          description: Error code representing the issue
+        message:
+          type: string
+          description: A description of the error
+      required:
+        - code
+        - message
diff --git a/packages/create-eventcatalog/templates/openapi/openapi-files/order-history.yml b/packages/create-eventcatalog/templates/openapi/openapi-files/order-history.yml
new file mode 100644
index 000000000..4e479d688
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/openapi-files/order-history.yml
@@ -0,0 +1,93 @@
+openapi: 3.0.0
+info:
+  title: Order History API
+  description: API for retrieving a history of past orders.
+  version: 1.0.0
+servers:
+  - url: https://api.yourshoppingapp.com/order-history
+    description: Order History API Server
+paths:
+  /:
+    get:
+      summary: Retrieve order history
+      description: Fetch a list of past orders with optional filters like date range and status.
+      x-eventcatalog-message-type: query
+      operationId: getOrderHistory
+      parameters:
+        - name: startDate
+          in: query
+          description: Start date for the order history range (YYYY-MM-DD)
+          schema:
+            type: string
+            format: date
+        - name: endDate
+          in: query
+          description: End date for the order history range (YYYY-MM-DD)
+          schema:
+            type: string
+            format: date
+        - name: status
+          in: query
+          description: Filter orders by status (pending, shipped, delivered, canceled)
+          schema:
+            type: string
+            enum: [pending, shipped, delivered, canceled]
+        - name: customerId
+          in: query
+          description: Customer ID for retrieving specific customer order history (optional if authenticated user)
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A list of past orders
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Order'
+        '400':
+          description: Invalid date range or other input
+components:
+  schemas:
+    Order:
+      type: object
+      properties:
+        id:
+          type: string
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/CartItem'
+        status:
+          type: string
+          enum: [pending, shipped, delivered, canceled]
+        totalAmount:
+          type: number
+          format: float
+        orderDate:
+          type: string
+          format: date
+      required:
+        - id
+        - items
+        - status
+        - totalAmount
+        - orderDate
+    CartItem:
+      type: object
+      properties:
+        productId:
+          type: string
+        name:
+          type: string
+        quantity:
+          type: integer
+        price:
+          type: number
+          format: float
+      required:
+        - productId
+        - name
+        - quantity
+        - price
diff --git a/packages/create-eventcatalog/templates/openapi/openapi-files/payment-api.yml b/packages/create-eventcatalog/templates/openapi/openapi-files/payment-api.yml
new file mode 100644
index 000000000..1b6f20622
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/openapi-files/payment-api.yml
@@ -0,0 +1,74 @@
+openapi: 3.0.0
+info:
+  title: Payment API
+  description: API for handling payment transactions.
+  version: 1.0.0
+servers:
+  - url: https://api.yourshoppingapp.com/payments
+    description: Payment API Server
+paths:
+  /:
+    post:
+      summary: Initiate payment
+      description: Start a payment process for an order.
+      x-eventcatalog-message-type: command
+      operationId: initiatePayment
+      requestBody:
+        description: Payment details
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PaymentRequest'
+      responses:
+        '201':
+          description: Payment initiated
+        '400':
+          description: Invalid payment request
+  /{paymentId}:
+    get:
+      summary: Get payment status
+      operationId: getPaymentStatus
+      description: Check the status of a specific payment by its ID.
+      x-eventcatalog-message-type: query
+      parameters:
+        - name: paymentId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Payment status details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PaymentStatus'
+components:
+  schemas:
+    PaymentRequest:
+      type: object
+      properties:
+        orderId:
+          type: string
+        amount:
+          type: number
+          format: float
+        paymentMethod:
+          type: string
+          enum: [credit_card, paypal, bank_transfer]
+      required:
+        - orderId
+        - amount
+        - paymentMethod
+    PaymentStatus:
+      type: object
+      properties:
+        id:
+          type: string
+        status:
+          type: string
+          enum: [pending, successful, failed]
+      required:
+        - id
+        - status
diff --git a/packages/create-eventcatalog/templates/openapi/openapi-files/product-api.yml b/packages/create-eventcatalog/templates/openapi/openapi-files/product-api.yml
new file mode 100644
index 000000000..001d76ccc
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/openapi-files/product-api.yml
@@ -0,0 +1,68 @@
+openapi: 3.0.0
+info:
+  title: Product API
+  description: API for managing and retrieving product details in the shopping application.
+  version: 1.0.0
+servers:
+  - url: https://api.yourshoppingapp.com/products
+    description: Product API Server
+paths:
+  /:
+    get:
+      summary: List all products
+      description: Retrieve a list of all available products.
+      x-eventcatalog-message-type: query
+      operationId: listProducts
+      responses:
+        '200':
+          description: A list of products
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Product'
+  /{productId}:
+    get:
+      summary: Get a product by ID
+      description: Retrieve details of a specific product by its ID.
+      x-eventcatalog-message-type: query
+      operationId: getProductById
+      parameters:
+        - name: productId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A single product
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Product'
+        '404':
+          description: Product not found
+components:
+  schemas:
+    Product:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        price:
+          type: number
+          format: float
+        category:
+          type: string
+        imageUrl:
+          type: string
+      required:
+        - id
+        - name
+        - price
+        - category
diff --git a/packages/create-eventcatalog/templates/openapi/public/logo.png b/packages/create-eventcatalog/templates/openapi/public/logo.png
new file mode 100644
index 000000000..535b5a0e7
Binary files /dev/null and b/packages/create-eventcatalog/templates/openapi/public/logo.png differ
diff --git a/packages/create-eventcatalog/templates/openapi/teams/order-management.mdx b/packages/create-eventcatalog/templates/openapi/teams/order-management.mdx
new file mode 100644
index 000000000..586d8cdaf
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/teams/order-management.mdx
@@ -0,0 +1,31 @@
+---
+id: order-management
+name: Order Management
+summmary: Order Management team based in London, UK
+members:
+  - dboyne
+  - asmith
+  - msmith
+  - alee
+  - azhang
+email: test@test.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+---
+
+## Overview
+
+The Order Management team is responsible for managing orders, inventory, shipment and payment.
+
+## Responsibilities
+
+- Manage orders and order processing
+- Manage inventory and inventory processing
+- Manage shipment and shipment processing
+- Manage payment and payment processing
+- Manage user and user processing
+
+## Key Contacts
+
+- David Boyne
+- Alice Smith
+- Mike Smith
diff --git a/packages/create-eventcatalog/templates/openapi/teams/payment-management.mdx b/packages/create-eventcatalog/templates/openapi/teams/payment-management.mdx
new file mode 100644
index 000000000..da065ec2c
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/teams/payment-management.mdx
@@ -0,0 +1,18 @@
+---
+id: payment-management
+name: Payment Management
+members:
+  - dboyne
+  - jbrown
+  - dkim
+---
+
+The payment management team is responsible for managing payments and payment accounts.
+
+## Responsibilities
+
+- Manage payment and payment account management
+- Manage payment and payment account provisioning
+- Manage payment and payment account deprovisioning
+- Manage user and user account password management
+- Manage user and user account role management
diff --git a/packages/create-eventcatalog/templates/openapi/teams/product-management.mdx b/packages/create-eventcatalog/templates/openapi/teams/product-management.mdx
new file mode 100644
index 000000000..e9ae9db13
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/teams/product-management.mdx
@@ -0,0 +1,18 @@
+---
+id: product-management
+name: Product Management
+members:
+  - dboyne
+  - jbrown
+  - dkim
+---
+
+The product management team is responsible for managing products and product accounts.
+
+## Responsibilities
+
+- Manage product and product account management
+- Manage product and product account provisioning
+- Manage product and product account deprovisioning
+- Manage product and product account password management
+- Manage product and product account role management
diff --git a/packages/create-eventcatalog/templates/openapi/users/aSmith.mdx b/packages/create-eventcatalog/templates/openapi/users/aSmith.mdx
new file mode 100644
index 000000000..db9809431
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/users/aSmith.mdx
@@ -0,0 +1,26 @@
+---
+id: asmith
+name: Amy Smith
+avatarUrl: https://randomuser.me/api/portraits/women/48.jpg
+role: Product owner
+---
+
+Hello! I'm Amy Smith, the Product Owner of the innovative Full Stackers team. With a strong focus on delivering exceptional value, I specialize in connecting business objectives with technical solutions to create products that users love.
+
+### About Me
+
+With a comprehensive background in product management and a solid understanding of software development, I bring a unique perspective to the table. My career has been driven by a passion for understanding user needs, defining clear product visions, and leading teams to successful product deliveries.
+
+### What I Do
+
+As the Product Owner for Full Stackers, my role involves a wide range of responsibilities aimed at ensuring our products are both high-quality and user-centric. Key aspects of my role include:
+
+- **Product Vision & Strategy**: Defining and communicating the long-term vision and strategy for our products, ensuring alignment with the company's objectives and market demands.
+- **Roadmap Planning**: Developing and maintaining a product roadmap that highlights key features and milestones, prioritizing tasks based on their business value and user feedback.
+- **Stakeholder Management**: Engaging with stakeholders across the organization to gather requirements, provide updates, and ensure everyone is aligned on the product's direction.
+- **User-Centric Design**: Championing the end-users by conducting user research, analyzing feedback, and ensuring our products effectively solve their problems.
+- **Agile Leadership**: Leading the development process using Agile methodologies, facilitating sprint planning, and ensuring the team has clear priorities and objectives.
+
+My mission is to deliver products that not only meet but exceed customer expectations. I thrive on the challenge of translating complex requirements into simple, intuitive solutions.
+
+If you’re interested in product management, user experience, or discussing the latest trends in technology, feel free to reach out!
diff --git a/packages/create-eventcatalog/templates/openapi/users/alee.mdx b/packages/create-eventcatalog/templates/openapi/users/alee.mdx
new file mode 100644
index 000000000..ae34f1820
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/users/alee.mdx
@@ -0,0 +1,8 @@
+---
+id: alee
+name: Alice Lee
+avatarUrl: https://randomuser.me/api/portraits/women/91.jpg
+role: Technical Writer
+---
+
+As a Technical Writer on the Documentation team, I create clear, comprehensive documentation for our products and APIs. My focus is on making complex technical concepts accessible to developers and end-users alike. I collaborate with engineering teams to ensure our documentation stays current and accurate.
diff --git a/packages/create-eventcatalog/templates/openapi/users/azhang.mdx b/packages/create-eventcatalog/templates/openapi/users/azhang.mdx
new file mode 100644
index 000000000..0f0a15616
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/users/azhang.mdx
@@ -0,0 +1,11 @@
+---
+id: azhang
+name: Alice Zhang
+avatarUrl: https://randomuser.me/api/portraits/women/97.jpg
+role: Data Engineer
+email: azhang@company.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/azhang
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=azhang@company.com
+---
+
+Building and maintaining data pipelines and infrastructure...
diff --git a/packages/create-eventcatalog/templates/openapi/users/dboyne.mdx b/packages/create-eventcatalog/templates/openapi/users/dboyne.mdx
new file mode 100644
index 000000000..26d8eddb4
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/users/dboyne.mdx
@@ -0,0 +1,33 @@
+---
+id: dboyne
+name: David Boyne
+avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png'
+role: Lead developer
+email: test@test.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+---
+
+Hello! I'm David Boyne, the Tech Lead of an amazing team called Full Stackers. With a passion for building robust and scalable systems, I specialize in designing and implementing event-driven architectures that power modern, responsive applications.
+
+### About Me
+
+With over a decade of experience in the tech industry, I have honed my skills in full-stack development, cloud computing, and distributed systems. My journey has taken me through various roles, from software engineer to architect, and now as a tech lead, I am committed to driving innovation and excellence within my team.
+
+### What I Do
+
+At Full Stackers, we focus on creating seamless and efficient event-driven architectures that enhance the performance and scalability of our applications. My role involves:
+
+- **Architecture Design**: Crafting scalable and resilient system architectures using event-driven paradigms.
+- **Team Leadership**: Guiding a talented team of developers, fostering a collaborative and innovative environment.
+- **Code Reviews & Mentorship**: Ensuring code quality and sharing knowledge to help the team grow.
+- **Stakeholder Collaboration**: Working closely with other teams and stakeholders to align our technical solutions with business goals.
+- **Continuous Improvement**: Advocating for best practices in software development, deployment, and monitoring.
+
+I am passionate about leveraging the power of events to build systems that are not only highly responsive but also easier to maintain and extend. In an ever-evolving tech landscape, I strive to stay ahead of the curve, continuously learning and adapting to new technologies and methodologies.
+
+Feel free to connect with me to discuss all things tech, event-driven architectures, or to exchange ideas on building better software systems!
+
+---
+
+_David Boyne_
+_Tech Lead, Full Stackers_
diff --git a/packages/create-eventcatalog/templates/openapi/users/dkim.mdx b/packages/create-eventcatalog/templates/openapi/users/dkim.mdx
new file mode 100644
index 000000000..bbdf71b61
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/users/dkim.mdx
@@ -0,0 +1,11 @@
+---
+id: dkim
+name: David Kim
+avatarUrl: https://randomuser.me/api/portraits/men/96.jpg
+role: Performance Engineer
+email: dkim@company.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/dkim
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=dkim@company.com
+---
+
+Optimizing application performance and user experience...
diff --git a/packages/create-eventcatalog/templates/openapi/users/jbrown.mdx b/packages/create-eventcatalog/templates/openapi/users/jbrown.mdx
new file mode 100644
index 000000000..149232154
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/users/jbrown.mdx
@@ -0,0 +1,11 @@
+---
+id: jbrown
+name: Jessica Brown
+avatarUrl: https://randomuser.me/api/portraits/women/95.jpg
+role: UI/UX Designer
+email: jbrown@company.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/jbrown
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=jbrown@company.com
+---
+
+Creating intuitive and engaging user interfaces...
diff --git a/packages/create-eventcatalog/templates/openapi/users/mSmith.mdx b/packages/create-eventcatalog/templates/openapi/users/mSmith.mdx
new file mode 100644
index 000000000..635e036f1
--- /dev/null
+++ b/packages/create-eventcatalog/templates/openapi/users/mSmith.mdx
@@ -0,0 +1,8 @@
+---
+id: msmith
+name: Martin Smith
+avatarUrl: 'https://randomuser.me/api/portraits/men/51.jpg'
+role: Senior software engineer
+---
+
+As a Senior Mobile Developer on The Mobile Devs team, I play a key role in designing, developing, and maintaining our company’s mobile applications. My focus is on creating a seamless and intuitive user experience for our customers on both iOS and Android platforms. I work closely with cross-functional teams, including backend developers, UX/UI designers, and product managers, to deliver high-quality mobile solutions that meet business objectives and exceed user expectations.
diff --git a/packages/create-eventcatalog/templates/types.ts b/packages/create-eventcatalog/templates/types.ts
new file mode 100644
index 000000000..b326dde46
--- /dev/null
+++ b/packages/create-eventcatalog/templates/types.ts
@@ -0,0 +1,30 @@
+import { PackageManager } from '../helpers/get-pkg-manager';
+
+export type TemplateType =
+  | 'default'
+  | 'app'
+  | 'empty'
+  | 'asyncapi'
+  | 'openapi'
+  | 'confluent'
+  | 'eventbridge'
+  | 'amazon-apigateway'
+  | 'graphql';
+export type TemplateMode = 'js' | 'ts';
+
+export interface GetTemplateFileArgs {
+  template: TemplateType;
+  mode: TemplateMode;
+  file: string;
+}
+
+export interface InstallTemplateArgs {
+  appName: string;
+  root: string;
+  packageManager: PackageManager;
+  isOnline: boolean;
+  organizationName: string;
+  template: TemplateType;
+  mode: TemplateMode;
+  eslint: boolean;
+}
diff --git a/packages/create-eventcatalog/tsconfig.json b/packages/create-eventcatalog/tsconfig.json
new file mode 100644
index 000000000..1b68f4d42
--- /dev/null
+++ b/packages/create-eventcatalog/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "moduleResolution": "node",
+    "preserveWatchOutput": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "strict": true,
+    "resolveJsonModule": true
+  },
+  "exclude": ["node_modules"]
+}
diff --git a/packages/language-server/.prettierignore b/packages/language-server/.prettierignore
new file mode 100644
index 000000000..4d837a4c3
--- /dev/null
+++ b/packages/language-server/.prettierignore
@@ -0,0 +1,2 @@
+docs/src/content/**/*.mdx
+src/generated
diff --git a/packages/language-server/CHANGELOG.md b/packages/language-server/CHANGELOG.md
new file mode 100644
index 000000000..e258f5224
--- /dev/null
+++ b/packages/language-server/CHANGELOG.md
@@ -0,0 +1,271 @@
+# @eventcatalog/language-server
+
+## 0.8.23
+
+### Patch Changes
+
+- Updated dependencies [9949f9f]
+- Updated dependencies [d64cfab]
+  - @eventcatalog/sdk@2.25.0
+
+## 0.8.23-beta.1
+
+### Patch Changes
+
+- Updated dependencies [9949f9f]
+  - @eventcatalog/sdk@2.25.0-beta.1
+
+## 0.8.23-beta.0
+
+### Patch Changes
+
+- Updated dependencies [d64cfab]
+  - @eventcatalog/sdk@2.25.0-beta.0
+
+## 0.8.22
+
+### Patch Changes
+
+- Updated dependencies [29dc055]
+  - @eventcatalog/sdk@2.24.2
+
+## 0.8.21
+
+### Patch Changes
+
+- Updated dependencies [3334ab1]
+  - @eventcatalog/sdk@2.24.1
+
+## 0.8.20
+
+### Patch Changes
+
+- Updated dependencies [6b7fc3c]
+  - @eventcatalog/sdk@2.24.0
+
+## 0.8.19
+
+### Patch Changes
+
+- Updated dependencies [2801b3e]
+  - @eventcatalog/sdk@2.23.1
+
+## 0.8.18
+
+### Patch Changes
+
+- Updated dependencies [3ad00ad]
+  - @eventcatalog/sdk@2.23.0
+
+## 0.8.17
+
+### Patch Changes
+
+- Updated dependencies [50b38f6]
+  - @eventcatalog/sdk@2.22.0
+
+## 0.8.16
+
+### Patch Changes
+
+- 67940c4: Add optional `url` support to badges so they can render as clickable links.
+- Updated dependencies [67940c4]
+  - @eventcatalog/sdk@2.21.2
+
+## 0.8.15
+
+### Patch Changes
+
+- Updated dependencies [1c9c217]
+  - @eventcatalog/sdk@2.21.1
+
+## 0.8.14
+
+### Patch Changes
+
+- Updated dependencies [3a7b096]
+  - @eventcatalog/sdk@2.21.0
+
+## 0.8.13
+
+### Patch Changes
+
+- Updated dependencies [8f724a7]
+  - @eventcatalog/sdk@2.20.0
+
+## 0.8.12
+
+### Patch Changes
+
+- Updated dependencies [52b4f24]
+  - @eventcatalog/sdk@2.19.0
+
+## 0.8.11
+
+### Patch Changes
+
+- Updated dependencies [ee142e4]
+  - @eventcatalog/sdk@2.18.4
+
+## 0.8.10
+
+### Patch Changes
+
+- Updated dependencies [88795d0]
+  - @eventcatalog/sdk@2.18.3
+
+## 0.8.9
+
+### Patch Changes
+
+- Updated dependencies [4639ec3]
+  - @eventcatalog/sdk@2.18.2
+
+## 0.8.8
+
+### Patch Changes
+
+- Updated dependencies [e2b0460]
+  - @eventcatalog/sdk@2.18.1
+
+## 0.8.7
+
+### Patch Changes
+
+- Updated dependencies [913ca20]
+  - @eventcatalog/sdk@2.18.0
+
+## 0.8.6
+
+### Patch Changes
+
+- Updated dependencies [83aca74]
+  - @eventcatalog/sdk@2.17.4
+
+## 0.8.5
+
+### Patch Changes
+
+- Updated dependencies [46a2292]
+  - @eventcatalog/sdk@2.17.3
+
+## 0.8.4
+
+### Patch Changes
+
+- Updated dependencies [0514bb1]
+  - @eventcatalog/sdk@2.17.2
+
+## 0.8.3
+
+### Patch Changes
+
+- Updated dependencies [6456054]
+  - @eventcatalog/sdk@2.17.1
+
+## 0.8.2
+
+### Patch Changes
+
+- Updated dependencies [af2d4f4]
+  - @eventcatalog/sdk@2.17.0
+
+## 0.8.1
+
+### Patch Changes
+
+- Updated dependencies [283c147]
+  - @eventcatalog/sdk@2.16.0
+
+## 0.8.0
+
+### Minor Changes
+
+- a461a9b: Add cross-file resource name completions, improve spec resolver path handling for nested folders, and support workspace-aware multi-file parsing in VS Code extension preview
+
+## 0.7.0
+
+### Minor Changes
+
+- b86daae: Support inline flow definitions inside domain blocks in the DSL
+
+## 0.6.2
+
+### Patch Changes
+
+- cb0235a: Replace playground.eventcatalog.dev URLs with compass.eventcatalog.dev
+
+## 0.6.1
+
+### Patch Changes
+
+- a43021e: Refactor language server, playground, and visualiser: extract shared helpers to reduce duplication, add browser entrypoint, definition/hover/formatter providers, resource index, catalog resolver, restructure docs, simplify layout utils, and add VSCode extension scaffold
+
+## 0.6.0
+
+### Minor Changes
+
+- 2663850: Add OpenAPI spec import support to the DSL language server. Parses OpenAPI v3.0/v3.1 specs and maps GET operations to queries and POST/PUT/PATCH/DELETE to commands. Auto-detects AsyncAPI vs OpenAPI from file content. Supports local and remote imports, JSON and YAML formats. Includes playground examples for OpenAPI import, service import, remote import, and mixed AsyncAPI+OpenAPI usage.
+
+## 0.5.0
+
+### Minor Changes
+
+- a85a4d7: Add AsyncAPI service import resolution and playground autocompletion for sends/receives and channel references
+
+## 0.4.1
+
+### Patch Changes
+
+- 6122f93: Add "Download as Catalog" export option to the playground that generates a ready-to-run EventCatalog project zip with package.json, config, and compiled content files
+
+## 0.4.0
+
+### Minor Changes
+
+- a1c5012: Add versioned message references (event, command, query) in visualizer blocks and hydrate related services in domain DSL export
+
+## 0.3.0
+
+### Minor Changes
+
+- c4104a1: Support template parameters in channel names (e.g. `inventory.{env}.events`) in the DSL grammar
+
+### Patch Changes
+
+- cf7fcac: add DSL-managed key merging for import to preserve non-DSL frontmatter, fix deprecated/draft falsy value handling in compiler
+
+## 0.2.3
+
+### Patch Changes
+
+- 6a4e582: Improve DSL import with container ref support, resource stubs, and cache upsert; add writes-to and reads-from compilation in the language server.
+
+## 0.2.2
+
+### Patch Changes
+
+- d703923: Replace base64 logo blob with actual logo.png asset, add import DSL command, and improve compiler with nested output support and domain/subdomain service pointer generation
+
+## 0.2.1
+
+### Patch Changes
+
+- ca5c1d8: Remove redundant direct message-to-channel routes-to edges when an indirect path exists through channel routing chains, and simplify user/team DSL spec by removing owns statement
+
+## 0.2.0
+
+### Minor Changes
+
+- c782129: feat(cli): add export command for DSL (.ec) format
+
+## 0.1.1
+
+### Patch Changes
+
+- c178b75: Beta release of @eventcatalog/language-server package
+  - Langium-based DSL parser for EventCatalog DSL
+  - Language server protocol (LSP) implementation
+  - Syntax validation and diagnostics
+  - DSL graph builder for visualiser integration
+  - Code formatting support
diff --git a/packages/language-server/README.md b/packages/language-server/README.md
new file mode 100644
index 000000000..7c9d65f4b
--- /dev/null
+++ b/packages/language-server/README.md
@@ -0,0 +1,71 @@
+# @eventcatalog/language-server
+
+> **Beta** - This package is in active development and the DSL syntax may change between releases.
+
+A language server and parser for the EventCatalog DSL (`.ec` files) - a human-readable, declarative language for defining event-driven architectures.
+
+## What is the EventCatalog DSL?
+
+The EventCatalog DSL is a complementary language for [EventCatalog](https://eventcatalog.dev) that brings architecture-as-code to your event-driven systems. Write your domains, services, events, commands, channels, and their relationships in a concise, human-readable format.
+
+The DSL is designed to work hand-in-hand with EventCatalog — import existing resources from your catalog into `.ec` files, design and iterate on your architecture as code, and push changes back into EventCatalog. It's a two-way workflow: catalog to code, code to catalog.
+
+```
+domain Payment {
+  version 1.0.0
+  owner payment-team
+
+  service PaymentService {
+    version 1.0.0
+
+    sends event PaymentProcessed {
+      version 1.0.0
+      summary "Emitted when a payment completes successfully"
+    }
+
+    receives command ProcessPayment
+    receives event OrderCreated
+  }
+}
+```
+
+## Features
+
+- Full language server with diagnostics, completions, and hover information
+- Parses `.ec` files into a structured graph representation
+- Supports all EventCatalog resource types: domains, services, events, commands, queries, channels, containers, data products, flows, users, and teams
+- Inline and referenced resource definitions
+- Formatter for consistent code style
+
+## Supported Resource Types
+
+| Resource        | Keyword           |
+| --------------- | ----------------- |
+| Domain          | `domain`          |
+| Service         | `service`         |
+| Event           | `event`           |
+| Command         | `command`         |
+| Query           | `query`           |
+| Channel         | `channel`         |
+| Container       | `container`       |
+| Data Product    | `data-product`    |
+| Flow            | `flow`            |
+| User            | `user`            |
+| Team            | `team`            |
+| Actor           | `actor`           |
+| External System | `external-system` |
+| Visualizer      | `visualizer`      |
+
+## Roadmap
+
+- Schema support (inline and referenced schemas for messages)
+- Entities
+- Schemas as first-class resources
+
+## Specification
+
+See [SPEC.md](./SPEC.md) for the full language specification including grammar, syntax details, and examples.
+
+## License
+
+See the root [LICENSE](../../LICENSE) file.
diff --git a/packages/language-server/SPEC.md b/packages/language-server/SPEC.md
new file mode 100644
index 000000000..e6002bf7a
--- /dev/null
+++ b/packages/language-server/SPEC.md
@@ -0,0 +1,1918 @@
+# EventCatalog DSL — Language Specification
+
+> Version: 1.0.0-draft
+> Status: Draft
+> Date: 2026-02-08
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Domain](#domain)
+3. [Service](#service)
+4. [Event](#event)
+5. [Command](#command)
+6. [Query](#query)
+7. [Channel](#channel)
+8. [Container](#container)
+9. [Data Product](#data-product)
+10. [Flow](#flow)
+11. [User](#user)
+12. [Team](#team)
+13. [Relationships & Pointers](#relationships--pointers)
+14. [Versioning](#versioning)
+15. [Metadata & Annotations](#metadata--annotations)
+16. [Complete Examples](#complete-examples)
+17. [Full Grammar (EBNF)](#full-grammar-ebnf)
+
+---
+
+# Overview
+
+The EventCatalog DSL (ECDSL) is a human-readable, declarative language for defining event-driven architectures. It compiles to EventCatalog's frontmatter/markdown format, enabling teams to define domains, services, messages, channels, and their relationships in a single coherent source.
+
+```
+domain Payment {
+  version 1.0.0
+  owner payment-team
+
+  service PaymentService {
+    version 1.0.0
+
+    sends event PaymentProcessed {
+      version 1.0.0
+      summary "Emitted when a payment completes successfully"
+    }
+
+    receives command ProcessPayment
+    receives event OrderCreated
+  }
+}
+```
+
+## Design Principles
+
+1. **Readable** — Reads like English; minimal punctuation
+2. **Hierarchical** — Nesting reflects domain ownership and relationships
+3. **Concise** — Sane defaults; only specify what you need
+4. **Complete** — Can express everything EventCatalog supports
+5. **Composable** — Resources can be defined inline or referenced by ID
+
+## Lexical Structure
+
+### Comments
+
+```
+// Single-line comment
+
+/* Multi-line
+   comment */
+```
+
+### Strings
+
+```
+"double-quoted string"
+```
+
+Strings are required for values containing spaces, special characters, or multi-word text. Bare identifiers (no spaces, alphanumeric + hyphens + dots) can be unquoted. Strings follow JSON-style escaping (`\"`, `\\`, `\n`, etc.); raw `"` inside a string is not allowed.
+
+### Identifiers
+
+Identifiers are bare words used for resource IDs and type names. Keywords are reserved and cannot be used as identifiers.
+
+```
+OrderCreated          // simple
+Payment.OrderCreated  // namespaced
+my-service-name       // kebab-case
+```
+
+### Version Literals
+
+Semantic versions are bare (unquoted):
+
+```
+version 1.0.0
+version 2.1.0-beta.1
+```
+
+### Blocks
+
+Curly braces delimit blocks. Properties inside blocks are newline-separated (no commas).
+
+```
+resource Foo {
+  property value
+  property "value with spaces"
+}
+```
+
+### Property Multiplicity
+
+The grammar allows any property to appear multiple times inside a block. The semantic rules are:
+
+**Single-value properties** — if repeated, the last occurrence wins:
+
+`version`, `name`, `summary`, `address`, `protocol`, `deprecated`, `draft`, `container-type`, `technology`, `authoritative`, `access-mode`, `classification`, `residency`, `retention`
+
+`schema` is also single-value but only valid on messages (`event`, `command`, `query`, and inline message definitions).
+
+**Repeatable properties** — each occurrence appends a value:
+
+`owner`, `sends`, `receives`, `writes-to`, `reads-from`, `flow`, `service` (ref), `subdomain`, `data-product`, `route`, `input`, `output`, `member`, `parameter`
+
+`parameter` names must be unique within a channel; duplicate names are an error.
+
+Annotations are repeatable by default (see Metadata & Annotations).
+
+Unknown properties are parse errors — only the properties listed in each resource's grammar are valid. Duplicate single-value properties are syntactically valid (last wins) but tooling may warn.
+
+---
+
+# Domain
+
+Top-level bounded context. Can contain services, subdomains, data products, and flows.
+
+```
+domain <id> {
+  // Required
+  version <semver>
+  name "<display name>"          // optional, defaults to id
+
+  // Optional metadata
+  summary "<text>"
+  owner <owner-ref>              // repeatable
+  deprecated true
+  draft true
+
+  // Relationships
+  service <service-ref>          // repeatable (reference to external service)
+  subdomain <domain-ref>         // repeatable
+  data-product <dp-ref>          // repeatable
+  flow <flow-ref>                // repeatable
+
+  // Domain-level message routing
+  sends <message-type> <id> [to <channel-ref>]
+  receives <message-type> <id> [from <channel-ref>]
+
+  // Inline definitions
+  service <id> { ... }
+  subdomain <id> { ... }
+
+  // Annotations (see Metadata section)
+  @badge(...)
+  @repository(...)
+}
+```
+
+## Subdomains
+
+Domains can contain nested subdomains:
+
+```
+domain Logistics {
+  version 1.0.0
+
+  subdomain Shipping {
+    version 1.0.0
+    summary "Package shipping and tracking"
+
+    service ShippingService {
+      version 1.0.0
+      receives event OrderCreated
+      sends event ShipmentCreated
+    }
+  }
+
+  subdomain Returns {
+    version 1.0.0
+    summary "Return merchandise authorization"
+
+    service ReturnsService {
+      version 1.0.0
+      receives command InitiateReturn
+      sends event ReturnApproved
+    }
+  }
+}
+```
+
+## EBNF
+
+```ebnf
+domain_decl      = "domain" identifier "{" common_props
+                   { domain_body_item } "}" ;
+domain_body_item = service_decl | subdomain_decl | service_ref_stmt
+                 | data_product_ref_stmt | flow_ref_stmt
+                 | sends_stmt | receives_stmt
+                 | annotation ;
+subdomain_decl   = "subdomain" identifier "{" common_props
+                   { domain_body_item } "}" ;
+```
+
+---
+
+# Service
+
+A microservice or application.
+
+```
+service <id> {
+  // Required
+  version <semver>
+  name "<display name>"
+
+  // Optional metadata
+  summary "<text>"
+  owner <owner-ref>              // repeatable
+  deprecated true
+  draft true
+
+  // Message relationships
+  sends <message-type> <id>[@<version>] [to <channel-list>]
+  receives <message-type> <id>[@<version>] [from <channel-list>]
+
+  // Data relationships
+  writes-to container <container-ref>      // repeatable
+  reads-from container <container-ref>     // repeatable
+
+  // Flow relationships
+  flow <flow-ref>                // repeatable
+
+  // Inline message definitions
+  sends event <id> { ... }
+  sends command <id> { ... }
+  receives query <id> { ... }
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+**Message types:** `event`, `command`, `query`
+
+## EBNF
+
+```ebnf
+service_decl     = "service" identifier "{" common_props
+                   { service_body_item } "}" ;
+service_body_item= sends_stmt | receives_stmt
+                 | writes_to_stmt | reads_from_stmt
+                 | flow_ref_stmt
+                 | annotation ;
+```
+
+---
+
+# Event
+
+A domain event — something that happened.
+
+```
+event <id> {
+  // Required
+  version <semver>
+  name "<display name>"
+
+  // Optional metadata
+  summary "<text>"
+  owner <owner-ref>
+  schema "<path>"
+  deprecated true
+  draft true
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+## EBNF
+
+```ebnf
+event_decl       = "event" identifier "{" message_props "}" ;
+```
+
+---
+
+# Command
+
+An instruction to perform an action.
+
+```
+command <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+  schema "<path>"
+  deprecated true
+  draft true
+
+  channel <channel-ref>
+
+  // Same annotations as event
+}
+```
+
+## EBNF
+
+```ebnf
+command_decl     = "command" identifier "{" message_props "}" ;
+```
+
+---
+
+# Query
+
+A request for information.
+
+```
+query <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+  schema "<path>"
+  deprecated true
+  draft true
+
+  channel <channel-ref>
+
+  // Same annotations as event
+}
+```
+
+## EBNF
+
+```ebnf
+query_decl       = "query" identifier "{" message_props "}" ;
+```
+
+---
+
+# Channel
+
+A communication channel (topic, queue, exchange, etc.).
+
+```
+channel <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+
+  address "<address-string>"
+  protocol "<protocol>"
+
+  // Channel parameters
+  parameter <name> {
+    description "<text>"
+    default "<value>"
+    enum ["<val1>", "<val2>"]
+    examples ["<ex1>", "<ex2>"]
+  }
+
+  // Routing
+  route <channel-ref>            // repeatable
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+## Channel-to-Channel Routing
+
+Channels can route to other channels using the `route` statement. This models message pipelines where data flows through multiple channels (e.g., Kafka topic → Kafka topic → MQTT broker):
+
+```
+channel SensorIngestion {
+  version 1.0.0
+  protocol "Kafka"
+  route SensorFiltered
+}
+
+channel SensorFiltered {
+  version 1.0.0
+  protocol "Kafka"
+  route MqttDevices
+}
+
+channel MqttDevices {
+  version 1.0.0
+  protocol "MQTT"
+}
+```
+
+This creates a chain: `SensorIngestion → SensorFiltered → MqttDevices`.
+
+A channel can route to multiple targets (fan-out):
+
+```
+channel Ingestion {
+  version 1.0.0
+  route Analytics
+  route Archive
+}
+```
+
+Routes can include versioned references:
+
+```
+channel Source {
+  version 1.0.0
+  route Target@2.0.0
+}
+```
+
+## Service-to-Channel Routing
+
+Services send/receive messages through channels:
+
+```
+service OrderService {
+  version 1.0.0
+
+  // Simple — no channel
+  sends event OrderCreated
+
+  // To a single channel
+  sends event OrderCreated to orders-topic
+
+  // To a channel with version (using @ syntax)
+  sends event OrderCreated to orders-topic@1.0.0
+
+  // To multiple channels (comma-separated)
+  sends event OrderCreated to orders-topic, orders-backup-topic
+
+  // To multiple channels with versions
+  sends event OrderCreated to orders-topic@1.0.0, orders-backup-topic@2.0.0
+
+  // Receiving from a single channel
+  receives event PaymentProcessed from payment-events
+
+  // Receiving from multiple channels
+  receives event PaymentProcessed from payment-events, payment-retry-queue
+
+  // Receiving from channels with versions
+  receives event PaymentProcessed from payment-events@1.0.0, payment-retry-queue@2.1.0
+}
+```
+
+## EBNF
+
+```ebnf
+channel_decl     = "channel" identifier "{" common_props
+                   { channel_body_item } "}" ;
+channel_body_item= address_prop | protocol_prop | parameter_decl
+                 | route_stmt | annotation ;
+address_prop     = "address" string_lit ;
+protocol_prop    = "protocol" string_lit ;
+parameter_decl   = "parameter" identifier "{" { param_prop } "}" ;
+param_prop       = "description" string_lit
+                 | "default" string_lit
+                 | "enum" "[" string_lit { "," string_lit } "]"
+                 | "examples" "[" string_lit { "," string_lit } "]" ;
+route_stmt       = "route" resource_ref ;
+
+channel_clause   = to_clause | from_clause ;
+to_clause        = "to" channel_ref_list ;
+from_clause      = "from" channel_ref_list ;
+channel_ref_list = channel_ref { "," channel_ref } ;
+channel_ref      = identifier [ "@" version_lit ] ;
+```
+
+---
+
+# Container
+
+A data store, cache, or external system.
+
+```
+container <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+
+  // Required
+  container-type <database | cache | objectStore | searchIndex
+                 | dataWarehouse | dataLake | externalSaaS | other>
+
+  // Optional
+  deprecated true
+  draft true
+  technology "<tech-string>"     // e.g., "postgres@15", "redis@7"
+  authoritative true
+  access-mode <read | write | readWrite | appendOnly>
+  classification <public | internal | confidential | regulated>
+  residency "<location>"
+  retention "<duration>"         // e.g., "90d", "10y"
+
+  // Relationships
+  service <service-ref>          // repeatable
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+## EBNF
+
+```ebnf
+container_decl   = "container" identifier "{" common_props
+                   { container_body_item } "}" ;
+container_body_item = container_type_prop | technology_prop
+                    | authoritative_prop | access_mode_prop
+                    | classification_prop | residency_prop
+                    | retention_prop
+                    | service_ref_stmt | annotation ;
+container_type_prop   = "container-type" container_type_enum ;
+container_type_enum   = "database" | "cache" | "objectStore" | "searchIndex"
+                      | "dataWarehouse" | "dataLake" | "externalSaaS" | "other" ;
+technology_prop       = "technology" string_lit ;
+authoritative_prop    = "authoritative" bool_lit ;
+access_mode_prop      = "access-mode" ( "read" | "write" | "readWrite" | "appendOnly" ) ;
+classification_prop   = "classification" ( "public" | "internal" | "confidential" | "regulated" ) ;
+residency_prop        = "residency" string_lit ;
+retention_prop        = "retention" string_lit ;
+```
+
+---
+
+# Data Product
+
+An analytical data product.
+
+```
+data-product <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+  deprecated true
+  draft true
+
+  // Data lineage
+  input <message-type> <resource-ref>      // repeatable
+  output <message-type> <resource-ref> {   // repeatable, with optional contract
+    contract {
+      path "<path>"
+      name "<name>"
+      type "<type>"
+    }
+  }
+
+  // Annotations
+  @badge(...)
+}
+```
+
+## EBNF
+
+```ebnf
+data_product_decl = "data-product" identifier "{" common_props
+                    { dp_body_item } "}" ;
+dp_body_item      = input_stmt | output_stmt | annotation ;
+input_stmt        = "input" message_type resource_ref ;
+output_stmt       = "output" message_type resource_ref [ "{" contract_block "}" ] ;
+contract_block    = "contract" "{" "path" string_lit "name" string_lit
+                    [ "type" string_lit ] "}" ;
+```
+
+---
+
+# Flow
+
+Flows define step-by-step business processes using a PM-friendly `when`-block syntax. Resources are referenced by name only — types are resolved from the catalog.
+
+```
+flow <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+
+  // Entry chain — the starting sequence
+  <Name> ["<label>"] -> <Name> ["<label>"] -> ...
+
+  // When blocks — react to events
+  when <TriggerName>
+    <ServiceName> "<description>"
+      -> "<label>": <OutputName>
+
+  // Convergence — multiple triggers must complete
+  when <TriggerA> and <TriggerB>
+    <ServiceName> "<description>"
+}
+```
+
+## Actors and External Systems
+
+To use actors and external systems in flows, define them as top-level resources. The flow resolves their type automatically by name:
+
+```
+actor Customer {
+  name "Customer"
+  summary "End user on the storefront"
+}
+
+external-system WarehouseWMS {
+  name "Warehouse WMS"
+  summary "Legacy warehouse management system"
+}
+```
+
+Both support optional bodies with `name`, `summary`, and annotations. They can also be bare (no body):
+
+```
+actor Customer
+external-system WarehouseWMS
+```
+
+## Flow References
+
+Resources in flows are referenced by name only (no type keywords like `service` or `event`). Types are resolved from catalog definitions or sibling `.ec` files. If no matching definition is found, the default type is `step`. Compilers may warn on unresolved flow references.
+
+Each reference can include an optional label:
+
+- `Customer "places an order"` — name with display label
+- `PlaceOrder` — bare name (no label)
+- `PaymentService "processes the payment"` — service with description
+
+## Entry Chains
+
+The entry chain defines the starting sequence of a flow. It uses arrow (`->`) syntax:
+
+```
+Customer "places an order"
+  -> PlaceOrder
+  -> OrderService "creates the order"
+  -> OrderCreated
+```
+
+Multiple sources can converge into a chain using commas:
+
+```
+EventA, EventB -> MergingService
+```
+
+## When Blocks
+
+`when` blocks define reactions to events. Each block starts with one or more trigger names, followed by actions:
+
+```
+when OrderCreated
+  PaymentService "processes the payment"
+    -> "success": PaymentProcessed
+    -> "failure": PaymentFailed
+  InventoryService "reserves stock"
+    -> StockReserved
+```
+
+### Labeled Outputs
+
+Action outputs can have optional labels (quoted strings followed by a colon):
+
+```
+-> "success": PaymentProcessed    // labeled output
+-> StockReserved                   // unlabeled output
+```
+
+### Convergence
+
+Use `and` to require multiple triggers before actions execute:
+
+```
+when PaymentProcessed and StockReserved
+  FulfillmentService "ships the order"
+    -> OrderShipped
+```
+
+### Terminal Actions
+
+Actions without outputs are terminal steps:
+
+```
+when OrderShipped
+  WarehouseWMS "syncs with legacy WMS"
+  NotificationService "notifies the customer"
+```
+
+## Example
+
+```
+flow OrderFulfillment {
+  version 1.0.0
+  name "Order Fulfillment"
+  summary "End-to-end order processing from placement to delivery"
+  owner fulfillment-team
+
+  Customer "places an order"
+    -> PlaceOrder
+    -> OrderService "creates the order"
+    -> OrderCreated
+
+  when OrderCreated
+    PaymentService "processes the payment"
+      -> "success": PaymentProcessed
+      -> "failure": PaymentFailed
+    InventoryService "reserves stock"
+      -> StockReserved
+
+  when PaymentFailed
+    NotificationService "notifies the customer of failure"
+
+  when PaymentProcessed and StockReserved
+    FulfillmentService "ships the order"
+      -> OrderShipped
+
+  when OrderShipped
+    WarehouseWMS "syncs with legacy WMS"
+    NotificationService "notifies the customer"
+      -> CustomerNotified
+}
+```
+
+## EBNF
+
+```ebnf
+flow_decl         = "flow" identifier "{" common_props
+                    { flow_entry_chain | flow_when_block } "}" ;
+flow_entry_chain  = flow_ref { "," flow_ref } ( "->" flow_ref )+ ;
+flow_when_block   = "when" flow_ref { "and" flow_ref } flow_action+ ;
+flow_action       = flow_ref { flow_output } ;
+flow_output       = "->" [ string_lit ":" ] flow_ref ;
+flow_ref          = identifier [ string_lit ] ;
+```
+
+---
+
+# Diagram
+
+_Removed from V1. May be added in a future version._
+
+---
+
+# User
+
+A user definition for team members.
+
+```
+user <id> {
+  name "<display name>"
+  avatar "<url>"
+  role "<role>"
+  email "<email>"
+  slack "<url>"
+  ms-teams "<url>"
+}
+```
+
+## Example
+
+```
+user dboyne {
+  name "David Boyne"
+  avatar "https://avatars.githubusercontent.com/u/3268013"
+  role "Principal Engineer"
+  email "david@company.com"
+}
+```
+
+## EBNF
+
+```ebnf
+user_decl         = "user" identifier "{" user_props "}" ;
+user_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit ;
+```
+
+---
+
+# Team
+
+A team definition for ownership and membership.
+
+```
+team <id> {
+  name "<display name>"
+  avatar "<url>"
+  role "<role>"
+  summary "<text>"
+  email "<email>"
+  slack "<url>"
+  ms-teams "<url>"
+
+  // Members
+  member <user-id>               // repeatable
+}
+```
+
+## Owner References
+
+Owners are referenced by team or user ID:
+
+```
+service OrderService {
+  version 1.0.0
+  owner payment-team              // team reference
+  owner dboyne                   // user reference
+}
+```
+
+## Example
+
+```
+team orders-team {
+  name "Orders Team"
+  avatar "https://example.com/orders-team.png"
+  role "Platform Engineering"
+  summary "Responsible for order lifecycle"
+  email "orders@company.com"
+  slack "https://company.slack.com/channels/orders"
+
+  member dboyne
+  member jane-doe
+}
+```
+
+## EBNF
+
+```ebnf
+team_decl         = "team" identifier "{" team_props "}" ;
+team_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "summary" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit
+                  | "member" identifier ;
+```
+
+---
+
+# Relationships & Pointers
+
+## Resource References
+
+Resources can be referenced by ID alone (resolves to `latest`) or with an explicit version:
+
+```
+// Reference by ID only (latest version)
+receives event OrderCreated
+
+// Reference by ID + version using @ syntax
+receives event OrderCreated@2.0.0
+
+// Reference with single channel routing
+sends event OrderCreated to orders-topic
+
+// Reference with channel version
+sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+
+// Reference with multiple channels
+sends event OrderCreated to orders-topic, backup-topic
+receives event PaymentProcessed from payment-events, payment-retry
+```
+
+## Inline vs. Reference
+
+Resources can be defined inline (creating them) or referenced (linking to existing):
+
+```
+service OrderService {
+  version 1.0.0
+
+  // Inline definition — creates the event
+  sends event OrderCreated {
+    version 1.0.0
+    summary "A new order was placed"
+  }
+
+  // Reference only — links to an existing event
+  receives event PaymentProcessed
+  receives event PaymentProcessed@2.0.0
+}
+```
+
+Inline messages do not support the `channel` statement — use `to`/`from` on the `sends`/`receives` statement for channel routing.
+
+## Pointer Syntax Summary
+
+| Syntax                        | Meaning                       |
+| ----------------------------- | ----------------------------- |
+| `<id>`                        | Latest version of resource    |
+| `<id>@<version>`              | Specific version              |
+| `<id> to <channel>`           | With single channel routing   |
+| `<id> to <channel>@<version>` | Channel with specific version |
+| `<id> to <ch1>, <ch2>, <ch3>` | Multiple channels             |
+| `<id> from <channel>`         | Received from channel         |
+| `<id> from <ch1>, <ch2>`      | Received from multiple        |
+
+## Data Relationships
+
+```
+writes-to container <container-ref>
+reads-from container <container-ref>
+```
+
+## EBNF
+
+```ebnf
+resource_ref     = identifier [ "@" version_lit ] ;
+message_type     = "event" | "command" | "query" ;
+
+sends_stmt       = "sends" message_type resource_ref [ channel_clause ]
+                 | "sends" message_type identifier inline_block ;
+receives_stmt    = "receives" message_type resource_ref [ channel_clause ]
+                 | "receives" message_type identifier inline_block ;
+
+channel_clause   = to_clause | from_clause ;
+to_clause        = "to" channel_ref_list ;
+from_clause      = "from" channel_ref_list ;
+channel_ref_list = channel_ref { "," channel_ref } ;
+channel_ref      = identifier [ "@" version_lit ] ;
+
+writes_to_stmt   = "writes-to" "container" resource_ref ;
+reads_from_stmt  = "reads-from" "container" resource_ref ;
+flow_ref_stmt    = "flow" resource_ref ;
+data_product_ref_stmt      = "data-product" resource_ref ;
+
+inline_block     = "{" message_props "}" ;
+```
+
+---
+
+# Versioning
+
+## Declaring Versions
+
+Every versioned resource requires a version:
+
+```
+event OrderCreated {
+  version 1.0.0
+}
+```
+
+## Referencing Versions
+
+```
+// Latest (default - no version specified)
+receives event OrderCreated
+
+// Specific version using @ syntax
+receives event OrderCreated@2.0.0
+
+// Channel with version
+sends event OrderProcessed to payments-channel@1.0.0
+
+// Multiple channels with versions
+receives event PaymentFailed from channel-a@1.0.0, channel-b@2.1.0
+```
+
+## Version Defaults
+
+When no version is specified in a reference, it resolves to `latest`.
+
+## EBNF
+
+```ebnf
+int              = digit { digit } ;
+version_lit      = int "." int "." int [ "-" prerelease ] ;
+version_prop     = "version" version_lit ;
+version_ref      = "@" version_lit ;
+resource_ref     = identifier [ version_ref ] ;
+```
+
+---
+
+# Metadata & Annotations
+
+Annotations use the `@` prefix and provide additional metadata. They can appear inside any resource block. All annotations are repeatable by default — multiple instances of the same annotation may appear on a single resource.
+
+## @badge
+
+```
+@badge("Production", bg: "#22c55e", text: "#fff")
+@badge("Beta", bg: "#f59e0b", text: "#000", icon: "flask")
+```
+
+## @repository
+
+```
+@repository(url: "https://github.com/org/repo", language: "TypeScript")
+```
+
+## @editUrl
+
+```
+@editUrl("https://github.com/org/repo/edit/main/docs/orders.md")
+```
+
+## @note
+
+Adds free-form developer notes or reminders to any resource. Notes are repeatable — multiple `@note` annotations can appear on a single resource. Supported on services, events, commands, queries, channels, and inline message definitions.
+
+```
+// Simple note
+@note("Come back later — needs review")
+
+// With optional parameters
+@note("Align schema with PaymentService team", author: "dboyne", priority: "high")
+
+// Multiple notes on a service
+service OrderService {
+  version 1.0.0
+  @note("TODO: add retry logic")
+  @note("Waiting on team alignment", priority: "medium")
+}
+
+// Notes on events, commands, and queries
+event OrderCreated {
+  version 1.0.0
+  @note("Schema v2 adds shippingAddress field", author: "alice")
+}
+
+command CreateOrder {
+  version 1.0.0
+  @note("Validate idempotency key", author: "bob", priority: "high")
+}
+
+// Notes on channels
+channel OrderEvents {
+  version 1.0.0
+  address "orders.events"
+  protocol "kafka"
+  @note("Partition key is orderId", author: "infra-team")
+}
+
+// Notes on inline messages (inside sends/receives)
+service PaymentService {
+  version 1.0.0
+  sends event PaymentProcessed to PaymentEvents {
+    version 1.0.0
+    @note("Includes refund reference when applicable", author: "dave")
+  }
+}
+```
+
+## @detailsPanel
+
+Controls visibility of detail panel sections:
+
+```
+@detailsPanel {
+  owners visible
+  versions visible
+  changelog hidden
+  producers visible
+  consumers hidden
+  channels visible
+  repository hidden
+  specifications hidden
+  messages hidden
+  domains hidden
+  services hidden
+  containers hidden
+}
+```
+
+## EBNF
+
+```ebnf
+annotation       = "@" ann_name [ "(" ann_args ")" ] [ ann_block ] ;
+ann_name         = identifier ;
+ann_args         = ann_arg { "," ann_arg } ;
+ann_arg          = [ identifier ":" ] ( string_lit | bool_lit | number_lit | identifier ) ;
+ann_block        = "{" { ann_body_item } "}" ;
+```
+
+---
+
+# Complete Examples
+
+## Example 1: E-Commerce Platform
+
+```
+// ============================================================
+// Teams & Users
+// ============================================================
+
+user dboyne {
+  name "David Boyne"
+  avatar "https://avatars.githubusercontent.com/u/3268013"
+  role "Principal Engineer"
+  email "david@company.com"
+}
+
+user jane-doe {
+  name "Jane Doe"
+  avatar "https://avatars.githubusercontent.com/u/12345"
+  role "Staff Engineer"
+}
+
+team orders-team {
+  name "Orders Team"
+  summary "Responsible for order lifecycle"
+  email "orders@company.com"
+  slack "https://company.slack.com/channels/orders"
+
+  member dboyne
+  member jane-doe
+}
+
+team payment-team {
+  name "Payment Team"
+  summary "Handles payment processing and fraud detection"
+  email "payments@company.com"
+
+  member jane-doe
+}
+
+// ============================================================
+// Channels
+// ============================================================
+
+channel orders-topic {
+  version 1.0.0
+  name "Orders Topic"
+  summary "Kafka topic for all order-related events"
+  address "kafka://production/orders"
+  protocol "Kafka"
+
+  parameter environment {
+    description "Deployment environment"
+    default "production"
+    enum ["production", "staging", "development"]
+  }
+
+}
+
+channel payment-queue {
+  version 1.0.0
+  name "Payment Queue"
+  summary "SQS queue for payment commands"
+  address "sqs://us-east-1/payment-processing"
+  protocol "SQS"
+}
+
+// ============================================================
+// Containers
+// ============================================================
+
+container orders-db {
+  version 1.0.0
+  name "Orders Database"
+  summary "Primary datastore for order data"
+  owner orders-team
+
+  container-type database
+  technology "postgres@15"
+  authoritative true
+  access-mode readWrite
+  classification confidential
+  residency "us-east-1"
+  retention "7y"
+
+  @repository(url: "https://github.com/company/orders-db")
+}
+
+container orders-cache {
+  version 1.0.0
+  name "Orders Cache"
+  summary "Redis cache for hot order lookups"
+
+  container-type cache
+  technology "redis@7"
+  access-mode readWrite
+  retention "24h"
+}
+
+// ============================================================
+// Domain
+// ============================================================
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  summary "Everything related to order management"
+  owner orders-team
+
+  @badge("Core", bg: "#3b82f6", text: "#fff")
+  @repository(url: "https://github.com/company/orders-domain")
+
+  service OrderService {
+    version 1.0.0
+    name "Order Service"
+    summary "Manages the order lifecycle"
+    owner orders-team
+
+    @repository(url: "https://github.com/company/order-service", language: "TypeScript")
+    @badge("Production", bg: "#22c55e", text: "#fff")
+
+    sends event OrderCreated {
+      version 1.0.0
+      summary "Emitted when a new order is placed"
+      schema "./schemas/order-created.avro"
+    }
+
+    sends event OrderUpdated {
+      version 1.0.0
+      summary "Emitted when order details change"
+    }
+
+    sends command ProcessPayment to payment-queue {
+      version 1.0.0
+      summary "Triggers payment processing for an order"
+    }
+
+    receives event PaymentProcessed from payment-queue
+    receives event InventoryReserved
+
+    writes-to container orders-db
+    reads-from container orders-db
+    writes-to container orders-cache
+    reads-from container orders-cache
+
+    flow OrderFulfillment@1.0.0
+  }
+
+  service NotificationService {
+    version 1.0.0
+    name "Notification Service"
+    summary "Sends email and push notifications for order updates"
+
+    receives event OrderCreated
+    receives event OrderUpdated
+
+    sends command SendEmail {
+      version 1.0.0
+      summary "Dispatches an email notification"
+    }
+  }
+}
+
+domain Payment {
+  version 1.0.0
+  name "Payment Domain"
+  summary "Payment processing and fraud detection"
+  owner payment-team
+
+  service PaymentService {
+    version 1.0.0
+    name "Payment Service"
+    summary "Processes payments via Stripe"
+    owner payment-team
+
+    @repository(url: "https://github.com/company/payment-service", language: "Go")
+
+    receives command ProcessPayment from payment-queue
+
+    sends event PaymentProcessed {
+      version 1.0.0
+      summary "Payment completed successfully"
+    }
+
+    sends event PaymentFailed {
+      version 1.0.0
+      summary "Payment was declined or errored"
+    }
+  }
+}
+
+// ============================================================
+// Standalone events (defined outside services)
+// ============================================================
+
+event InventoryReserved {
+  version 1.0.0
+  name "Inventory Reserved"
+  summary "Stock has been reserved for an order"
+  owner orders-team
+
+  @badge("Critical", bg: "#ef4444", text: "#fff")
+}
+
+// ============================================================
+// Data Product
+// ============================================================
+
+data-product OrderAnalytics {
+  version 1.0.0
+  name "Order Analytics"
+  summary "Real-time and batch analytics for order metrics"
+  owner orders-team
+
+  input event OrderCreated@1.0.0
+  input event PaymentProcessed@1.0.0
+  input event InventoryReserved@1.0.0
+
+  output event OrderMetrics {
+    contract {
+      path "./contracts/order-metrics.json"
+      name "Order Metrics Schema"
+      type "json-schema"
+    }
+  }
+}
+
+// ============================================================
+// Actors & External Systems
+// ============================================================
+
+actor Customer {
+  name "Customer"
+  summary "End user on the storefront"
+}
+
+external-system WarehouseWMS {
+  name "Warehouse WMS"
+  summary "Legacy warehouse management system via SOAP API"
+}
+
+// ============================================================
+// Flow
+// ============================================================
+
+flow OrderFulfillment {
+  version 1.0.0
+  name "Order Fulfillment"
+  summary "End-to-end order processing from placement to delivery"
+  owner orders-team
+
+  Customer "End user on the storefront"
+    -> PlaceOrder
+    -> OrderService
+    -> OrderCreated
+
+  when OrderCreated
+    PaymentService "processes the payment"
+      -> "success": PaymentProcessed
+      -> "failure": PaymentFailed
+    InventoryService "reserves inventory"
+      -> InventoryReserved
+
+  when InventoryReserved
+    WarehouseWMS "Legacy WMS via SOAP API"
+}
+
+```
+
+## Example 2: Minimal Service Definition
+
+The DSL supports minimal definitions where defaults are sufficient:
+
+```
+service OrderService {
+  version 1.0.0
+  sends event OrderCreated
+  receives command ProcessPayment
+  receives event PaymentProcessed
+}
+```
+
+## Example 3: Multi-Channel Routing
+
+```
+service EventRouter {
+  version 1.0.0
+  summary "Routes events across multiple channels"
+
+  // Send to multiple channels (comma-separated)
+  sends event OrderCreated to orders-topic, orders-archive-topic
+
+  // Receive from multiple channels
+  receives event PaymentProcessed from payment-events, payment-retry-queue
+}
+```
+
+## Example 4: Channel Routing (IoT Pipeline)
+
+```
+channel SensorIngestion {
+  version 1.0.0
+  address "sensors.raw"
+  protocol "Kafka"
+  summary "Raw sensor data ingestion"
+  route SensorFiltered
+}
+
+channel SensorFiltered {
+  version 1.0.0
+  address "sensors.filtered"
+  protocol "Kafka"
+  summary "Validated sensor data"
+  route DeviceCommands
+}
+
+channel DeviceCommands {
+  version 1.0.0
+  address "devices/+/commands"
+  protocol "MQTT"
+  summary "MQTT topic for device commands"
+}
+
+service SensorGateway {
+  version 1.0.0
+  summary "Ingests raw sensor readings"
+  sends event SensorReading to SensorIngestion
+}
+
+service FilterService {
+  version 1.0.0
+  summary "Validates and filters sensor data"
+  receives event SensorReading from SensorIngestion
+  sends event DeviceAlert to SensorFiltered
+}
+
+service DeviceBridge {
+  version 1.0.0
+  summary "Bridges Kafka to MQTT"
+  receives event DeviceAlert from SensorFiltered
+  sends command RecalibrateDevice to DeviceCommands
+}
+```
+
+## Example 5: Subdomains
+
+```
+domain Logistics {
+  version 1.0.0
+
+  subdomain Shipping {
+    version 1.0.0
+    summary "Package shipping and tracking"
+
+    service ShippingService {
+      version 1.0.0
+      receives event OrderCreated
+      sends event ShipmentCreated
+    }
+  }
+
+  subdomain Returns {
+    version 1.0.0
+    summary "Return merchandise authorization"
+
+    service ReturnsService {
+      version 1.0.0
+      receives command InitiateReturn
+      sends event ReturnApproved
+    }
+  }
+}
+```
+
+---
+
+# Full Grammar (EBNF)
+
+```ebnf
+(* Top-level *)
+program          = { top_level_decl } ;
+top_level_decl   = domain_decl | service_decl | event_decl | command_decl
+                 | query_decl | channel_decl | container_decl
+                 | data_product_decl | flow_decl
+                 | user_decl | team_decl | visualizer_decl
+                 | actor_decl | external_system_decl ;
+
+(* Identifiers and literals *)
+identifier       = letter { letter | digit | "-" | "." | "_" } ;
+int              = digit { digit } ;
+version_lit      = int "." int "." int [ "-" prerelease ] ;
+string_lit       = '"' { any_char } '"' ;
+bool_lit         = "true" | "false" ;
+number_lit       = digit { digit } ;
+
+(* Common properties *)
+common_props     = { version_prop | name_prop | summary_prop | owner_prop
+                   | deprecated_prop | draft_prop | annotation } ;
+message_props    = { version_prop | name_prop | summary_prop | owner_prop
+                   | schema_prop | deprecated_prop | draft_prop | annotation } ;
+version_prop     = "version" version_lit ;
+name_prop        = "name" string_lit ;
+summary_prop     = "summary" string_lit ;
+owner_prop       = "owner" identifier ;
+schema_prop      = "schema" string_lit ;
+deprecated_prop  = "deprecated" bool_lit ;
+draft_prop       = "draft" bool_lit ;
+
+(* Annotations *)
+annotation       = "@" ann_name [ "(" ann_args ")" ] [ ann_block ] ;
+ann_name         = identifier ;
+ann_args         = ann_arg { "," ann_arg } ;
+ann_arg          = [ identifier ":" ] ( string_lit | bool_lit | number_lit | identifier ) ;
+ann_block        = "{" { ann_body_item } "}" ;
+
+(* Resource references *)
+resource_ref     = identifier [ "@" version_lit ] ;
+message_type     = "event" | "command" | "query" ;
+
+(* Domain *)
+domain_decl      = "domain" identifier "{" common_props
+                   { domain_body_item } "}" ;
+domain_body_item = service_decl | subdomain_decl
+                 | data_product_ref_stmt | flow_ref_stmt
+                 | sends_stmt | receives_stmt
+                 | annotation ;
+subdomain_decl   = "subdomain" identifier "{" common_props
+                   { domain_body_item } "}" ;
+
+(* Service *)
+service_decl     = "service" identifier "{" common_props
+                   { service_body_item } "}" ;
+service_body_item= sends_stmt | receives_stmt
+                 | writes_to_stmt | reads_from_stmt
+                 | flow_ref_stmt
+                 | annotation ;
+
+(* Sends / Receives *)
+sends_stmt       = "sends" message_type resource_ref [ channel_clause ]
+                 | "sends" message_type identifier inline_block ;
+receives_stmt    = "receives" message_type resource_ref [ channel_clause ]
+                 | "receives" message_type identifier inline_block ;
+
+channel_clause   = to_clause | from_clause ;
+to_clause        = "to" channel_ref_list ;
+from_clause      = "from" channel_ref_list ;
+channel_ref_list = channel_ref { "," channel_ref } ;
+channel_ref      = identifier [ "@" version_lit ] ;
+
+(* Data relationships *)
+writes_to_stmt   = "writes-to" "container" resource_ref ;
+reads_from_stmt  = "reads-from" "container" resource_ref ;
+flow_ref_stmt    = "flow" resource_ref ;
+data_product_ref_stmt      = "data-product" resource_ref ;
+
+(* Inline message block *)
+inline_block     = "{" message_props "}" ;
+
+(* Messages: Event, Command, Query *)
+event_decl       = "event" identifier "{" message_props "}" ;
+command_decl     = "command" identifier "{" message_props "}" ;
+query_decl       = "query" identifier "{" message_props "}" ;
+
+(* Channel *)
+channel_decl     = "channel" identifier "{" common_props
+                   { channel_body_item } "}" ;
+channel_body_item= address_prop | protocol_prop | parameter_decl
+                 | route_stmt | annotation ;
+address_prop     = "address" string_lit ;
+protocol_prop    = "protocol" string_lit ;
+parameter_decl   = "parameter" identifier "{" { param_prop } "}" ;
+param_prop       = "description" string_lit
+                 | "default" string_lit
+                 | "enum" "[" string_lit { "," string_lit } "]"
+                 | "examples" "[" string_lit { "," string_lit } "]" ;
+route_stmt       = "route" resource_ref ;
+
+(* Container *)
+container_decl   = "container" identifier "{" common_props
+                   { container_body_item } "}" ;
+container_body_item = container_type_prop | technology_prop
+                    | authoritative_prop | access_mode_prop
+                    | classification_prop | residency_prop
+                    | retention_prop
+                    | service_ref_stmt | annotation ;
+container_type_prop   = "container-type" container_type_enum ;
+container_type_enum   = "database" | "cache" | "objectStore" | "searchIndex"
+                      | "dataWarehouse" | "dataLake" | "externalSaaS" | "other" ;
+technology_prop       = "technology" string_lit ;
+authoritative_prop    = "authoritative" bool_lit ;
+access_mode_prop      = "access-mode" ( "read" | "write" | "readWrite" | "appendOnly" ) ;
+classification_prop   = "classification" ( "public" | "internal" | "confidential" | "regulated" ) ;
+residency_prop        = "residency" string_lit ;
+retention_prop        = "retention" string_lit ;
+
+(* Data Product *)
+data_product_decl = "data-product" identifier "{" common_props
+                    { dp_body_item } "}" ;
+dp_body_item      = input_stmt | output_stmt | annotation ;
+input_stmt        = "input" message_type resource_ref ;
+output_stmt       = "output" message_type resource_ref [ "{" contract_block "}" ] ;
+contract_block    = "contract" "{" "path" string_lit "name" string_lit
+                    [ "type" string_lit ] "}" ;
+
+(* Flow *)
+flow_decl         = "flow" identifier "{" common_props
+                    { flow_entry_chain | flow_when_block } "}" ;
+flow_entry_chain  = flow_ref { "," flow_ref } ( "->" flow_ref )+ ;
+flow_when_block   = "when" flow_ref { "and" flow_ref } flow_action+ ;
+flow_action       = flow_ref { flow_output } ;
+flow_output       = "->" [ string_lit ":" ] flow_ref ;
+flow_ref          = identifier [ string_lit ] ;
+
+(* Actor *)
+actor_decl        = "actor" identifier [ "{" { actor_body_item } "}" ] ;
+actor_body_item   = name_prop | summary_prop | annotation ;
+
+(* External System *)
+external_system_decl = "external-system" identifier [ "{" { ext_sys_body_item } "}" ] ;
+ext_sys_body_item    = name_prop | summary_prop | annotation ;
+
+(* Visualizer *)
+visualizer_decl   = "visualizer" identifier "{" { visualizer_body } "}" ;
+visualizer_body   = name_prop | summary_prop | annotation
+                  | legend_prop | search_prop | toolbar_prop
+                  | focus_mode_prop | animated_prop | style_prop
+                  | domain_decl | service_decl | event_decl | command_decl
+                  | query_decl | channel_decl | container_decl
+                  | data_product_decl | flow_decl
+                  | actor_decl | external_system_decl
+                  | service_ref_stmt | domain_ref_stmt
+                  | event_ref_stmt | command_ref_stmt | query_ref_stmt
+                  | channel_ref_stmt | data_product_ref_stmt | flow_ref_stmt
+                  | container_ref_stmt ;
+legend_prop       = "legend" bool_lit ;
+search_prop       = "search" bool_lit ;
+toolbar_prop      = "toolbar" bool_lit ;
+focus_mode_prop   = "focus-mode" bool_lit ;
+animated_prop     = "animated" bool_lit ;
+style_prop        = "style" ( "default" | "post-it" ) ;
+
+(* User *)
+user_decl         = "user" identifier "{" user_props "}" ;
+user_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit ;
+
+(* Team *)
+team_decl         = "team" identifier "{" team_props "}" ;
+team_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "summary" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit
+                  | "member" identifier ;
+
+(* Resource references *)
+versioned_resource_ref  = identifier "@" version_lit ;
+service_ref_stmt    = "service" resource_ref ;
+domain_ref_stmt     = "domain" resource_ref ;
+event_ref_stmt      = "event" versioned_resource_ref ;
+command_ref_stmt    = "command" versioned_resource_ref ;
+query_ref_stmt      = "query" versioned_resource_ref ;
+channel_ref_stmt    = "channel" resource_ref ;
+container_ref_stmt  = "container" resource_ref ;
+```
+
+## Reserved Keywords
+
+```
+domain     service     event       command      query
+channel    container   data-product flow
+user       team        sends       receives
+writes-to  reads-from  owns        to           from
+version    name        summary     owner        schema
+deprecated draft       true        false
+type       actor       external-system
+parameter  route       member
+input      output      contract
+subdomain  visualizer  legend      search       toolbar      focus-mode
+animated   style       when        and
+```
+
+## File Extension
+
+EventCatalog DSL files use the `.ec` extension:
+
+```
+catalog.ec
+orders-domain.ec
+payment-service.ec
+```
+
+Multiple `.ec` files can be used and are merged during compilation. Resources can reference each other across files.
+
+## Compilation
+
+The DSL compiles to EventCatalog's directory structure:
+
+```
+catalog.ec  -->  domains/Orders/index.mdx
+                    domains/Orders/services/OrderService/index.mdx
+                    events/OrderCreated/index.mdx
+                    commands/ProcessPayment/index.mdx
+                    channels/orders-topic/index.mdx
+                    users/dboyne.mdx
+                    teams/orders-team.mdx
+                    ...
+```
+
+Each resource becomes a markdown file with YAML frontmatter matching EventCatalog's content collection schemas.
+
+---
+
+# Visualizer
+
+The `visualizer` block separates **resource definition** from **visualization**. Resources defined outside a visualizer block exist in the catalog but are not rendered visually. Only resources placed inside a `visualizer` block (or referenced from one) appear in the visual graph.
+
+This separation lets teams maintain a single source of truth for all resources while controlling exactly what gets visualized and how.
+
+```
+visualizer <id> {
+  name "<display name>"
+  summary "<text>"
+
+  // Display options
+  legend true|false
+  search true|false
+  toolbar true|false
+  focus-mode true|false
+  animated true|false
+  style default|post-it
+
+  // Resources to visualize (inline or reference)
+  <resource definitions or references>
+}
+```
+
+## Why Visualizer Exists
+
+A `.ec` file can define dozens of resources — domains, services, events, channels, and more. Without a visualizer block, there is no way to control which resources appear in the visual graph or how they are presented.
+
+The visualizer block makes visualization **explicit**:
+
+- Define resources anywhere (top-level, imported files)
+- Choose what to visualize by placing resources inside a `visualizer` block
+- Configure display options per visualization
+
+## Multiple Visualizer Blocks
+
+A file can contain multiple `visualizer` blocks, each presenting a different view over the same resources. Tools (e.g. the playground) allow switching between them.
+
+```
+// Shared resources
+event OrderCreated {
+  version 1.0.0
+}
+
+event PaymentProcessed {
+  version 1.0.0
+}
+
+service OrderService {
+  version 1.0.0
+  sends event OrderCreated
+}
+
+service PaymentService {
+  version 1.0.0
+  receives event OrderCreated
+  sends event PaymentProcessed
+}
+
+// View 1: Order flow only
+visualizer orders {
+  name "Order Flow"
+
+  service OrderService
+  event OrderCreated
+}
+
+// View 2: Full payment pipeline
+visualizer payments {
+  name "Payment Pipeline"
+
+  service OrderService
+  service PaymentService
+  event OrderCreated
+  event PaymentProcessed
+}
+```
+
+## Resources Without a Visualizer
+
+Resources defined outside any `visualizer` block are valid. They can be:
+
+- Imported by other `.ec` files
+- Referenced from within a `visualizer` block
+- Used for compilation to EventCatalog's markdown format
+
+If a file contains no `visualizer` block, no visual graph is produced.
+
+## Inline vs. Reference
+
+Resources inside a visualizer can be defined inline (full definition) or referenced by name:
+
+**Inline** — defines and visualizes the resource:
+
+```
+visualizer main {
+  name "My Architecture"
+
+  service OrderService {
+    version 1.0.0
+    sends event OrderCreated
+  }
+}
+```
+
+**Reference** — visualizes a resource defined elsewhere:
+
+```
+service OrderService {
+  version 1.0.0
+  sends event OrderCreated
+}
+
+visualizer main {
+  name "My Architecture"
+  service OrderService
+}
+```
+
+When a resource is referenced, the visualizer enriches the node with metadata from the matching top-level definition.
+
+## Display Options
+
+| Property     | Type    | Default   | Description                            |
+| ------------ | ------- | --------- | -------------------------------------- |
+| `name`       | string  | —         | Display title for the visualization    |
+| `summary`    | string  | —         | Description of the visualization       |
+| `legend`     | boolean | `true`    | Show the node type legend              |
+| `search`     | boolean | `true`    | Show the search bar                    |
+| `toolbar`    | boolean | `true`    | Show the toolbar (export, zoom, etc.)  |
+| `focus-mode` | boolean | `true`    | Enable focus mode for individual nodes |
+| `animated`   | boolean | `true`    | Animate edges                          |
+| `style`      | enum    | `default` | Visual style: `default` or `post-it`   |
+
+## Example
+
+```
+// Teams
+team orders-team {
+  name "Orders Team"
+}
+
+// Resources
+channel orders-topic {
+  version 1.0.0
+  protocol "Kafka"
+}
+
+// Visualizer with display options
+visualizer order-architecture {
+  name "Order Architecture"
+  summary "Core order processing services"
+  legend true
+  search true
+  animated false
+  style post-it
+
+  domain Orders {
+    version 1.0.0
+    owner orders-team
+
+    service OrderService {
+      version 1.0.0
+      sends event OrderCreated to orders-topic
+      receives command CreateOrder
+    }
+
+    service NotificationService {
+      version 1.0.0
+      receives event OrderCreated
+    }
+  }
+}
+```
+
+## EBNF
+
+```ebnf
+visualizer_decl   = "visualizer" identifier "{" { visualizer_body } "}" ;
+visualizer_body   = name_prop | summary_prop | annotation
+                  | legend_prop | search_prop | toolbar_prop
+                  | focus_mode_prop | animated_prop | style_prop
+                  | domain_decl | service_decl | event_decl | command_decl
+                  | query_decl | channel_decl | container_decl
+                  | data_product_decl | flow_decl
+                  | actor_decl | external_system_decl
+                  | service_ref_stmt | domain_ref_stmt
+                  | event_ref_stmt | command_ref_stmt | query_ref_stmt
+                  | channel_ref_stmt | data_product_ref_stmt | flow_ref_stmt
+                  | container_ref_stmt ;
+legend_prop       = "legend" bool_lit ;
+search_prop       = "search" bool_lit ;
+toolbar_prop      = "toolbar" bool_lit ;
+focus_mode_prop   = "focus-mode" bool_lit ;
+animated_prop     = "animated" bool_lit ;
+style_prop        = "style" ( "default" | "post-it" ) ;
+```
+
+---
diff --git a/packages/language-server/docs/astro.config.mjs b/packages/language-server/docs/astro.config.mjs
new file mode 100644
index 000000000..6b4faaced
--- /dev/null
+++ b/packages/language-server/docs/astro.config.mjs
@@ -0,0 +1,92 @@
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+
+export default defineConfig({
+  base: "/docs",
+  integrations: [
+    starlight({
+      title: "EventCatalog Compass",
+      description:
+        "Use .ec files to model architecture quickly and sync to and from EventCatalog with the CLI.",
+      social: {
+        github: "https://github.com/event-catalog/eventcatalog",
+      },
+      head: [
+        {
+          tag: "script",
+          content: `!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys getNextSurveyStep onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);posthog.init('phc_HQZncKORYsXgO87WuSjSdKbQSTzylljE6HTtUw0fBIH',{api_host:'https://e.eventcatalog.dev/relay-fBIH',capture_performance:false})`,
+        },
+      ],
+      components: {
+        PageTitle: "./src/components/PageTitle.astro",
+        MarkdownContent: "./src/components/MarkdownContent.astro",
+        SiteTitle: "./src/components/SiteTitle.astro",
+        Header: "./src/components/Header.astro",
+      },
+      sidebar: [
+        {
+          label: "Getting Started",
+          items: [{ slug: "get-started/tutorial" }],
+        },
+        {
+          label: "EventCatalog Compass",
+          items: [{ label: "Overview", link: "/" }],
+        },
+        {
+          label: "Models",
+          items: [
+            { slug: "resources/domains" },
+            { slug: "resources/services" },
+            { slug: "resources/messages" },
+            { slug: "resources/channels" },
+            { label: "Containers", slug: "resources/databases" },
+            { slug: "resources/flows" },
+            { label: "Data Products", slug: "resources/data-products" },
+            { slug: "resources/teams-and-users" },
+          ],
+        },
+        {
+          label: "Annotations",
+          items: [{ slug: "annotations/notes" }],
+        },
+        {
+          label: "Importing Resources",
+          items: [
+            { slug: "guides/import-from-asyncapi" },
+            { slug: "guides/import-from-openapi" },
+            { slug: "guides/import-from-eventcatalog" },
+            { slug: "guides/import-from-ec-files" },
+          ],
+        },
+        {
+          label: "Exporting Resources",
+          items: [
+            { slug: "guides/export-to-eventcatalog" },
+            { slug: "guides/export-to-static-site" },
+          ],
+        },
+        {
+          label: "Tooling",
+          items: [{ slug: "tooling/editors" }, { slug: "tooling/cli" }],
+        },
+        {
+          label: "Specification",
+          items: [
+            { slug: "reference/dsl-spec" },
+            { slug: "reference/command-cheatsheet" },
+          ],
+        },
+        {
+          label: "Changelog",
+          items: [
+            {
+              label: "Releases",
+              link: "https://github.com/event-catalog/eventcatalog/releases",
+              attrs: { target: "_blank", rel: "noopener noreferrer" },
+            },
+          ],
+        },
+      ],
+    }),
+  ],
+});
diff --git a/packages/language-server/docs/ec.config.mjs b/packages/language-server/docs/ec.config.mjs
new file mode 100644
index 000000000..be362d88c
--- /dev/null
+++ b/packages/language-server/docs/ec.config.mjs
@@ -0,0 +1,19 @@
+import { defineEcConfig } from "@astrojs/starlight/expressive-code";
+import { readFileSync } from "node:fs";
+
+const ecLanguageGrammar = JSON.parse(
+  readFileSync(
+    new URL("../syntaxes/ec.tmLanguage.json", import.meta.url),
+    "utf-8",
+  ),
+);
+
+export default defineEcConfig({
+  shiki: {
+    langs: [ecLanguageGrammar],
+    langAlias: {
+      eventcatalog: "ec",
+      ebnf: "txt",
+    },
+  },
+});
diff --git a/packages/language-server/docs/src/components/ChannelTransportSelector.astro b/packages/language-server/docs/src/components/ChannelTransportSelector.astro
new file mode 100644
index 000000000..c19b15d92
--- /dev/null
+++ b/packages/language-server/docs/src/components/ChannelTransportSelector.astro
@@ -0,0 +1,187 @@
+---
+import { Code } from '@astrojs/starlight/components';
+import { Buffer } from 'node:buffer';
+
+type ChannelOption = {
+  id: string;
+  label: string;
+  detail: string;
+  address: string;
+  protocol: string;
+};
+
+const options: ChannelOption[] = [
+  {
+    id: 'kafka',
+    label: 'Kafka',
+    detail: 'Topic-based streaming (append-only event log).',
+    address: 'orders.events',
+    protocol: 'Kafka',
+  },
+  {
+    id: 'mqtt',
+    label: 'MQTT',
+    detail: 'Lightweight pub/sub for devices and edge systems.',
+    address: 'orders/events',
+    protocol: 'MQTT',
+  },
+  {
+    id: 'http',
+    label: 'HTTP',
+    detail: 'Request/response or webhook-style delivery.',
+    address: '/orders/events',
+    protocol: 'HTTP',
+  },
+  {
+    id: 'sqs',
+    label: 'SQS',
+    detail: 'Queue-based delivery with managed buffering.',
+    address: 'orders-events',
+    protocol: 'SQS',
+  },
+];
+
+const [defaultOption] = options;
+const instanceId = `channel-selector-${Math.random().toString(36).slice(2, 8)}`;
+const playgroundBaseUrl = 'https://compass.eventcatalog.dev/?code=';
+
+const buildModelCode = (option: ChannelOption) => `service OrdersService {
+  version 1.0.0
+  name "Orders Service"
+  sends event OrderCreated@1.0.0 to OrdersChannel@1.0.0
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "Raised when an order is created"
+}
+
+channel OrdersChannel {
+  version 1.0.0
+  name "Orders Channel"
+  address "${option.address}"
+  protocol "${option.protocol}"
+}`;
+
+const buildDiffCode = (option: ChannelOption) => `service OrdersService {
+  version 1.0.0
+  name "Orders Service"
+-  sends event OrderCreated@1.0.0
++  sends event OrderCreated@1.0.0 to OrdersChannel@1.0.0
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "Raised when an order is created"
+}
+
++channel OrdersChannel {
++  version 1.0.0
++  name "Orders Channel"
++  address "${option.address}"
++  protocol "${option.protocol}"
++}`;
+
+const toPlaygroundUrl = (option: ChannelOption) => {
+  const encoded = encodeURIComponent(Buffer.from(buildModelCode(option), 'utf-8').toString('base64'));
+  return `${playgroundBaseUrl}${encoded}`;
+};
+---
+
+<ec-channel-selector class="ec-channel-selector">
+  <div class="ec-channel-selector__controls">
+    <label for={`${instanceId}-transport`} class="ec-channel-selector__label">Channel transport</label>
+    <select id={`${instanceId}-transport`} data-channel-select class="ec-channel-selector__select">
+      {
+        options.map((option) => (
+          <option value={option.id} data-detail={option.detail} selected={option.id === defaultOption.id}>
+            {option.label}
+          </option>
+        ))
+      }
+    </select>
+    <p class="ec-channel-selector__description">
+      {defaultOption.detail}
+    </p>
+  </div>
+
+  {
+    options.map((option) => (
+      <div data-channel-panel={option.id} hidden={option.id !== defaultOption.id}>
+        <p class="ec-channel-selector__actions">
+          <a href={toPlaygroundUrl(option)} target="_blank" rel="noopener noreferrer">
+            Open this version in EventCatalog Compass
+          </a>
+        </p>
+        <Code code={buildDiffCode(option)} lang="diff" meta='title="main.ec"' />
+      </div>
+    ))
+  }
+</ec-channel-selector>
+
+<script>
+  class EcChannelSelector extends HTMLElement {
+    connectedCallback() {
+      const select = this.querySelector('[data-channel-select]');
+      const panels = Array.from(this.querySelectorAll('[data-channel-panel]'));
+      const description = this.querySelector('.ec-channel-selector__description');
+
+      if (!(select instanceof HTMLSelectElement) || !description) return;
+
+      const render = () => {
+        for (const panel of panels) {
+          panel.toggleAttribute('hidden', panel.getAttribute('data-channel-panel') !== select.value);
+        }
+
+        description.textContent = select.selectedOptions[0]?.dataset.detail || '';
+      };
+
+      select.addEventListener('change', render);
+      render();
+    }
+  }
+
+  if (!customElements.get('ec-channel-selector')) {
+    customElements.define('ec-channel-selector', EcChannelSelector);
+  }
+</script>
+
+<style>
+  .ec-channel-selector {
+    display: grid;
+    gap: 0.75rem;
+  }
+
+  .ec-channel-selector__controls {
+    display: grid;
+    gap: 0.35rem;
+    max-width: 22rem;
+  }
+
+  .ec-channel-selector__label {
+    font-size: var(--sl-text-sm);
+    font-weight: 600;
+  }
+
+  .ec-channel-selector__select {
+    border: 1px solid var(--sl-color-hairline-shade);
+    border-radius: 0.5rem;
+    background: var(--sl-color-bg);
+    color: var(--sl-color-text);
+    padding: 0.5rem 0.7rem;
+    font: inherit;
+  }
+
+  .ec-channel-selector__description {
+    margin: 0;
+    color: var(--sl-color-text-accent);
+    font-size: var(--sl-text-sm);
+  }
+
+  .ec-channel-selector__actions {
+    margin: 0 0 0.35rem;
+    font-size: var(--sl-text-sm);
+  }
+</style>
diff --git a/packages/language-server/docs/src/components/Header.astro b/packages/language-server/docs/src/components/Header.astro
new file mode 100644
index 000000000..d6a575ee6
--- /dev/null
+++ b/packages/language-server/docs/src/components/Header.astro
@@ -0,0 +1,112 @@
+---
+import config from 'virtual:starlight/user-config';
+
+import LanguageSelect from 'virtual:starlight/components/LanguageSelect';
+import Search from 'virtual:starlight/components/Search';
+import SiteTitle from 'virtual:starlight/components/SiteTitle';
+import SocialIcons from 'virtual:starlight/components/SocialIcons';
+import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
+
+const shouldRenderSearch =
+	config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
+---
+
+<div class="header sl-flex">
+	<div class="title-wrapper sl-flex">
+		<SiteTitle />
+		<nav class="header-nav">
+			<a href="/">Docs</a>
+			<a href="https://compass.eventcatalog.dev/playground" target="_blank" rel="noopener noreferrer">Playground</a>
+		</nav>
+	</div>
+	<div class="sl-flex print:hidden">
+		{shouldRenderSearch && <Search />}
+	</div>
+	<div class="sl-hidden md:sl-flex print:hidden right-group">
+		<div class="sl-flex social-icons">
+			<SocialIcons />
+		</div>
+		<ThemeSelect />
+		<LanguageSelect />
+	</div>
+</div>
+
+<style>
+	.header {
+		gap: var(--sl-nav-gap);
+		justify-content: space-between;
+		align-items: center;
+		height: 100%;
+	}
+
+	.title-wrapper {
+		overflow: clip;
+		padding: 0.25rem;
+		margin: -0.25rem;
+		min-width: 0;
+		align-items: center;
+		gap: 1.5rem;
+	}
+
+	.header-nav {
+		display: none;
+		gap: 1rem;
+		align-items: center;
+	}
+
+	.header-nav a {
+		font-size: var(--sl-text-sm);
+		color: var(--sl-color-gray-2);
+		text-decoration: none;
+		white-space: nowrap;
+	}
+
+	.header-nav a:hover {
+		color: var(--sl-color-text-accent);
+	}
+
+	@media (min-width: 50rem) {
+		.header-nav {
+			display: flex;
+		}
+	}
+
+	.right-group,
+	.social-icons {
+		gap: 1rem;
+		align-items: center;
+	}
+	.social-icons::after {
+		content: '';
+		height: 2rem;
+		border-inline-end: 1px solid var(--sl-color-gray-5);
+	}
+
+	@media (min-width: 50rem) {
+		:global(:root[data-has-sidebar]) {
+			--__sidebar-pad: calc(2 * var(--sl-nav-pad-x));
+		}
+		:global(:root:not([data-has-toc])) {
+			--__toc-width: 0rem;
+		}
+		.header {
+			--__sidebar-width: max(0rem, var(--sl-content-inline-start, 0rem) - var(--sl-nav-pad-x));
+			--__main-column-fr: calc(
+				(
+						100% + var(--__sidebar-pad, 0rem) - var(--__toc-width, var(--sl-sidebar-width)) -
+							(2 * var(--__toc-width, var(--sl-nav-pad-x))) - var(--sl-content-inline-start, 0rem) -
+							var(--sl-content-width)
+					) / 2
+			);
+			display: grid;
+			grid-template-columns:
+				minmax(
+					calc(var(--__sidebar-width) + max(0rem, var(--__main-column-fr) - var(--sl-nav-gap))),
+					auto
+				)
+				1fr
+				auto;
+			align-content: center;
+		}
+	}
+</style>
diff --git a/packages/language-server/docs/src/components/MarkdownContent.astro b/packages/language-server/docs/src/components/MarkdownContent.astro
new file mode 100644
index 000000000..998b9f174
--- /dev/null
+++ b/packages/language-server/docs/src/components/MarkdownContent.astro
@@ -0,0 +1,169 @@
+---
+import '@astrojs/starlight/style/markdown.css';
+---
+<div class="sl-markdown-content"><slot /></div>
+
+<script>
+  let mermaidLoader;
+
+  const decodeBase64Utf8 = (value) => {
+    const binary = atob(value);
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+  };
+
+  const copyText = async (value) => {
+    if (navigator.clipboard?.writeText) {
+      await navigator.clipboard.writeText(value);
+      return;
+    }
+
+    const textarea = document.createElement('textarea');
+    textarea.value = value;
+    textarea.setAttribute('readonly', '');
+    textarea.style.position = 'absolute';
+    textarea.style.left = '-9999px';
+    document.body.appendChild(textarea);
+    textarea.select();
+    document.execCommand('copy');
+    document.body.removeChild(textarea);
+  };
+
+  const initCopyMarkdownButtons = () => {
+    document.querySelectorAll('.copy-markdown-button').forEach((button) => {
+      if (!(button instanceof HTMLButtonElement)) return;
+      if (button.dataset.copyBound === 'true') return;
+      button.dataset.copyBound = 'true';
+
+      button.addEventListener('click', async () => {
+        const encoded = button.dataset.markdown || '';
+        const markdownFromSource = encoded ? decodeBase64Utf8(encoded) : '';
+
+        let markdown = markdownFromSource;
+        if (!markdown.trim()) {
+          const content = button.parentElement?.nextElementSibling;
+          if (content instanceof HTMLElement) {
+            markdown = content.innerText.trim();
+          }
+        }
+
+        if (!markdown.trim()) return;
+
+        try {
+          await copyText(markdown);
+          button.textContent = 'Copied!';
+          window.setTimeout(() => {
+            button.textContent = button.dataset.defaultLabel || 'Copy as Markdown';
+          }, 1400);
+        } catch {
+          button.textContent = 'Copy failed';
+          window.setTimeout(() => {
+            button.textContent = button.dataset.defaultLabel || 'Copy as Markdown';
+          }, 1800);
+        }
+      });
+    });
+  };
+
+  const loadMermaid = async () => {
+    if (!mermaidLoader) {
+      mermaidLoader = import('https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs')
+        .then((module) => module.default || module)
+        .catch(() => null);
+    }
+    return mermaidLoader;
+  };
+
+  const renderMermaidBlocks = async () => {
+    const mermaidBlocks = Array.from(document.querySelectorAll('.sl-markdown-content pre[data-language="mermaid"]'));
+    if (mermaidBlocks.length === 0) return;
+
+    const mermaid = await loadMermaid();
+    if (!mermaid) return;
+
+    mermaid.initialize({
+      startOnLoad: false,
+      securityLevel: 'loose',
+      theme: window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'default',
+    });
+
+    for (const pre of mermaidBlocks) {
+      const figure = pre.closest('figure');
+      if (!(figure instanceof HTMLElement)) continue;
+      if (figure.dataset.mermaidRendered === 'true') continue;
+
+      const source = pre.innerText.trim();
+      if (!source) continue;
+
+      try {
+        const output = document.createElement('div');
+        output.className = 'ec-mermaid-diagram';
+        const id = `mermaid-${Math.random().toString(36).slice(2, 10)}`;
+        const { svg } = await mermaid.render(id, source);
+        output.innerHTML = svg;
+        figure.classList.add('has-mermaid-diagram');
+        figure.appendChild(output);
+        figure.dataset.mermaidRendered = 'true';
+      } catch {
+        // Leave the source block visible if rendering fails.
+      }
+    }
+  };
+
+  const initializeMarkdownEnhancements = () => {
+    initCopyMarkdownButtons();
+    renderMermaidBlocks();
+  };
+
+  initializeMarkdownEnhancements();
+  document.addEventListener('astro:page-load', initializeMarkdownEnhancements);
+</script>
+
+<style>
+  :global(.sl-markdown-content .sl-link-button[href*='compass.eventcatalog.dev']) {
+    border-color: color-mix(in srgb, var(--sl-color-accent-high) 35%, transparent);
+    background:
+      linear-gradient(
+        135deg,
+        color-mix(in srgb, var(--sl-color-accent) 22%, var(--sl-color-black)),
+        color-mix(in srgb, var(--sl-color-accent-high) 30%, var(--sl-color-black))
+      );
+    color: var(--sl-color-white);
+    font-weight: 650;
+    box-shadow: 0 6px 16px color-mix(in srgb, var(--sl-color-accent) 28%, transparent);
+    transition: transform 0.18s ease, box-shadow 0.18s ease, border-color 0.18s ease;
+  }
+
+  :global(.sl-markdown-content .sl-link-button[href*='compass.eventcatalog.dev']:hover) {
+    color: var(--sl-color-white);
+    transform: translateY(-1px);
+    border-color: color-mix(in srgb, var(--sl-color-accent-high) 60%, transparent);
+    box-shadow: 0 10px 22px color-mix(in srgb, var(--sl-color-accent) 35%, transparent);
+  }
+
+  :global(.sl-markdown-content .sl-link-button[href*='compass.eventcatalog.dev']::after) {
+    content: ' ->';
+    font-size: 0.92em;
+  }
+
+  :global(.sl-markdown-content figure.has-mermaid-diagram pre[data-language='mermaid']) {
+    display: none;
+  }
+
+  :global(.sl-markdown-content figure.has-mermaid-diagram .copy) {
+    display: none;
+  }
+
+  :global(.sl-markdown-content .ec-mermaid-diagram) {
+    border: 1px solid var(--sl-color-hairline-shade);
+    border-radius: 0.75rem;
+    background: var(--sl-color-bg-inline-code);
+    padding: 0.75rem;
+    overflow-x: auto;
+  }
+
+  :global(.sl-markdown-content .ec-mermaid-diagram svg) {
+    max-width: 100%;
+    height: auto;
+  }
+</style>
diff --git a/packages/language-server/docs/src/components/PageTitle.astro b/packages/language-server/docs/src/components/PageTitle.astro
new file mode 100644
index 000000000..839ab2f1f
--- /dev/null
+++ b/packages/language-server/docs/src/components/PageTitle.astro
@@ -0,0 +1,66 @@
+---
+import { Buffer } from 'node:buffer';
+
+const title = Astro.locals.starlightRoute.entry.data.title;
+const sourceMarkdown = Astro.locals.starlightRoute.entry.body ?? '';
+const encodedMarkdown = Buffer.from(sourceMarkdown, 'utf-8').toString('base64');
+---
+
+<div class="page-title-row">
+  <h1 id="_top">{title}</h1>
+  <button
+    type="button"
+    class="copy-markdown-button"
+    data-markdown={encodedMarkdown}
+    data-default-label="Copy as Markdown"
+  >
+    Copy as Markdown
+  </button>
+</div>
+
+<style>
+  .page-title-row {
+    margin-top: 1rem;
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 1rem;
+  }
+
+  h1 {
+    margin: 0;
+    font-size: var(--sl-text-h1);
+    line-height: var(--sl-line-height-headings);
+    font-weight: 600;
+    color: var(--sl-color-white);
+  }
+
+  .copy-markdown-button {
+    margin-top: 0.2rem;
+    border: 1px solid var(--sl-color-hairline-shade);
+    border-radius: 0.5rem;
+    background: var(--sl-color-bg-nav);
+    color: var(--sl-color-text);
+    padding: 0.45rem 0.8rem;
+    font-size: var(--sl-text-sm);
+    line-height: 1.2;
+    white-space: nowrap;
+    cursor: pointer;
+  }
+
+  .copy-markdown-button:hover {
+    background: color-mix(in srgb, var(--sl-color-bg-nav) 80%, white);
+  }
+
+  @media (max-width: 50rem) {
+    .page-title-row {
+      flex-direction: column;
+      align-items: flex-start;
+      gap: 0.65rem;
+    }
+
+    .copy-markdown-button {
+      margin-top: 0;
+    }
+  }
+</style>
diff --git a/packages/language-server/docs/src/components/SiteTitle.astro b/packages/language-server/docs/src/components/SiteTitle.astro
new file mode 100644
index 000000000..d00fa1712
--- /dev/null
+++ b/packages/language-server/docs/src/components/SiteTitle.astro
@@ -0,0 +1,19 @@
+---
+const { siteTitle } = Astro.locals.starlightRoute;
+---
+
+<a href="https://compass.eventcatalog.dev" class="site-title sl-flex">
+	<span translate="no">{siteTitle}</span>
+</a>
+
+<style>
+	.site-title {
+		align-items: center;
+		gap: var(--sl-nav-gap);
+		font-size: var(--sl-text-h4);
+		font-weight: 600;
+		color: var(--sl-color-text-accent);
+		text-decoration: none;
+		white-space: nowrap;
+	}
+</style>
diff --git a/packages/language-server/docs/src/content.config.ts b/packages/language-server/docs/src/content.config.ts
new file mode 100644
index 000000000..7fbcf2c33
--- /dev/null
+++ b/packages/language-server/docs/src/content.config.ts
@@ -0,0 +1,7 @@
+import { defineCollection } from "astro:content";
+import { docsLoader } from "@astrojs/starlight/loaders";
+import { docsSchema } from "@astrojs/starlight/schema";
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};
diff --git a/packages/language-server/docs/src/content/docs/annotations/notes.mdx b/packages/language-server/docs/src/content/docs/annotations/notes.mdx
new file mode 100644
index 000000000..c50bfee9d
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/annotations/notes.mdx
@@ -0,0 +1,37 @@
+---
+title: Notes
+description: Capture design feedback and open questions with @note annotations.
+---
+
+Use `@note` to attach review context directly to models. Notes are repeatable, so you can add multiple notes to the same resource.
+
+> The keyword is `@note` (singular), even if you are adding many notes.
+
+## Example
+
+```ec title="main.ec"
+service CheckoutService {
+  version 2.0.0
+  owner checkout-team
+
+  @note("Should retries live here or in PaymentsService?")
+  @note("Need SRE sign-off for timeout policy", author: "platform-team", priority: "high")
+
+  sends event CheckoutSubmitted@2.0.0 to CheckoutEvents@1.0.0
+}
+```
+
+## Parameters
+
+| Parameter      | Type   | Required | Description                       | Example               |
+| -------------- | ------ | -------- | --------------------------------- | --------------------- |
+| first argument | string | Yes      | The note text.                    | `"Need SRE sign-off"` |
+| `author`       | string | No       | Person or team who left the note. | `"platform-team"`     |
+| `priority`     | string | No       | Priority label for triage.        | `"high"`              |
+
+## Where you can use notes
+
+- services
+- messages (`event`, `command`, `query`)
+- channels
+- inline messages inside `sends` and `receives`
diff --git a/packages/language-server/docs/src/content/docs/get-started/quickstart.mdx b/packages/language-server/docs/src/content/docs/get-started/quickstart.mdx
new file mode 100644
index 000000000..b313d6ab3
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/get-started/quickstart.mdx
@@ -0,0 +1,8 @@
+---
+title: Quickstart
+description: This page moved to the new tutorial.
+---
+
+The quickstart has been replaced with a fuller step-by-step tutorial.
+
+Go to [Get Started Tutorial](/get-started/tutorial/).
diff --git a/packages/language-server/docs/src/content/docs/get-started/tutorial.mdx b/packages/language-server/docs/src/content/docs/get-started/tutorial.mdx
new file mode 100644
index 000000000..c3c2020fb
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/get-started/tutorial.mdx
@@ -0,0 +1,270 @@
+---
+title: Tutorial
+description: Build your first EventCatalog model and move it into and out of EventCatalog.
+---
+
+import { Steps } from "@astrojs/starlight/components";
+
+In this tutorial, we will build a small architecture model from scratch and see it visually.
+
+You have two options to follow this tutorial:
+1. Open the [EventCatalog Compass Playground](https://compass.eventcatalog.dev/playground)
+    - This will give you a blank canvas to work on.
+2. Use the [EventCatalog VSCode Extension](https://compass.eventcatalog.dev/docs/tooling/editors/)
+    - You will need to install the plugin and create your first `main.ec` file.
+    - You can run the `EventCatalog: Open Preview` command to see your model visually.
+
+---
+
+## Creating your first model
+
+In this example we will create a simple model of an order processing system.
+
+<Steps>
+
+1. ### Create a visualizer
+
+   The `visualizer` block is your canvas. Everything you want to see in the diagram goes inside it.
+   - Start by creating a visualizer block.
+
+   ```diff lang=ec
+   +visualizer main {
+   +  name "Order Processing"
+   +}
+   ```
+
+2. ### Add a service
+
+   A service is a runtime capability in your system, for example a microservice or application.
+   - Add a service inside the visualizer block.
+
+   ```diff lang=ec
+   visualizer main {
+     name "Order Processing"
+
+   +  service OrdersService {
+   +    version 1.0.0
+   +    name "Orders Service"
+   +    summary "Handles order lifecycle"
+   +  }
+   }
+   ```
+
+3. ### Publish an event from the service
+
+   Services can `send` (publish) messages. These can be events, commands, or queries.
+   These messages can be sent `to` a channel (e.g. Kafka, MQTT, HTTP, SQS, etc.).
+   - Add a `sends` statement to the service to publish an event.
+   - Add a channel to send the event to (_this is optional_).
+
+   ```diff lang=ec
+   visualizer main {
+     name "Order Processing"
+
+     service OrdersService {
+       version 1.0.0
+       name "Orders Service"
+       summary "Handles order lifecycle"
+   +    sends event OrderCreated@1.0.0 to KafkaOrdersTopic
+     }
+
+   +  event OrderCreated {
+   +    version 1.0.0
+   +    name "Order Created"
+   +    summary "Raised when an order is created"
+   +  }
+
+   +  channel KafkaOrdersTopic {
+   +    version 1.0.0
+   +    name "Kafka Orders Topic"
+   +    summary "Primary channel for order events"
+   +    address "orders.events"
+   +    protocol "kafka"
+   +  }
+   }
+   ```
+
+4. ### Consume messages
+
+   Services can also `receive` (consume) messages. These can be events, commands, or queries.
+   These messages can be received `from` a channel (e.g. Kafka, MQTT, HTTP, SQS, etc.).
+   - Add a `receives` statement to consume a command.
+   - This time we don't specify a version and latest version is used.
+
+   ```diff lang=ec
+   visualizer main {
+     name "Order Processing"
+
+     service OrdersService {
+       version 1.0.0
+       name "Orders Service"
+       summary "Handles order lifecycle"
+       sends event OrderCreated@1.0.0 to KafkaOrdersTopic
+   +    receives command ProcessOrder
+     }
+
+     event OrderCreated {
+       version 1.0.0
+       name "Order Created"
+       summary "Raised when an order is created"
+     }
+
+     channel KafkaOrdersTopic {
+       version 1.0.0
+       name "Kafka Orders Topic"
+       summary "Primary channel for order events"
+       address "orders.events"
+       protocol "kafka"
+     }
+
+   +  command ProcessOrder {
+   +    version 1.0.0
+   +    name "Process Order"
+   +    summary "Processes an order"
+   +  }
+   }
+   ```
+
+5. ### Add more services
+
+   Add as many services as you need. When multiple services produce or consume the same event through the same channel, the diagram connects them automatically.
+
+   ```diff lang=ec
+   visualizer main {
+     name "Order Processing"
+
+     service OrdersService {
+       version 1.0.0
+       name "Orders Service"
+       summary "Handles order lifecycle"
+       sends event OrderCreated@1.0.0 to KafkaOrdersTopic
+       receives command ProcessOrder
+     }
+
+   +  service PaymentService {
+   +    version 1.0.0
+   +    summary "Processes payments for orders"
+   +    receives event OrderCreated from KafkaOrdersTopic
+   +    sends event PaymentProcessed to KafkaOrdersTopic {
+   +      version 1.0.0
+   +      summary "Payment completed successfully"
+   +    }
+   +  }
+
+   +  service InventoryService {
+   +    version 1.0.0
+   +    summary "Manages product stock levels"
+   +    receives event OrderCreated from KafkaOrdersTopic
+   +    sends event InventoryReserved {
+   +      version 1.0.0
+   +      summary "Stock reserved for an order"
+   +    }
+   +  }
+
+   +  service NotificationService {
+   +    version 1.0.0
+   +    summary "Sends notifications to users"
+   +    receives event OrderCreated from KafkaOrdersTopic
+   +    receives event PaymentProcessed from KafkaOrdersTopic
+   +  }
+
+     event OrderCreated {
+       version 1.0.0
+       name "Order Created"
+       summary "Raised when an order is created"
+     }
+
+     channel KafkaOrdersTopic {
+       version 1.0.0
+       name "Kafka Orders Topic"
+       summary "Primary channel for order events"
+       address "orders.events"
+       protocol "kafka"
+     }
+
+     command ProcessOrder {
+       version 1.0.0
+       name "Process Order"
+       summary "Processes an order"
+     }
+   }
+   ```
+
+6. ### Wrap it in a domain
+
+   Domains group related services together. Wrap your services inside a `domain` block to show ownership and boundaries.
+
+   ```diff lang=ec
+   visualizer main {
+     name "Order Processing"
+
+   +  domain Orders {
+   +    version 1.0.0
+   +    summary "Everything related to order processing"
+
+       service OrdersService {
+         version 1.0.0
+         name "Orders Service"
+         summary "Handles order lifecycle"
+         sends event OrderCreated@1.0.0 to KafkaOrdersTopic
+         receives command ProcessOrder
+       }
+
+       service PaymentService {
+         version 1.0.0
+         summary "Processes payments for orders"
+         receives event OrderCreated from KafkaOrdersTopic
+         sends event PaymentProcessed to KafkaOrdersTopic {
+           version 1.0.0
+           summary "Payment completed successfully"
+         }
+       }
+
+       service InventoryService {
+         version 1.0.0
+         summary "Manages product stock levels"
+         receives event OrderCreated from KafkaOrdersTopic
+         sends event InventoryReserved {
+           version 1.0.0
+           summary "Stock reserved for an order"
+         }
+       }
+   +  }
+
+     service NotificationService {
+       version 1.0.0
+       summary "Sends notifications to users"
+       receives event OrderCreated from KafkaOrdersTopic
+       receives event PaymentProcessed from KafkaOrdersTopic
+     }
+
+     event OrderCreated {
+       version 1.0.0
+       name "Order Created"
+       summary "Raised when an order is created"
+     }
+
+     channel KafkaOrdersTopic {
+       version 1.0.0
+       name "Kafka Orders Topic"
+       summary "Primary channel for order events"
+       address "orders.events"
+       protocol "kafka"
+     }
+
+     command ProcessOrder {
+       version 1.0.0
+       name "Process Order"
+       summary "Processes an order"
+     }
+   }
+   ```
+
+7. ### Next steps
+   - Learn about [domains](/docs/resources/domains/), [services](/docs/resources/services/), [messages](/docs/resources/messages/), and [channels](/docs/resources/channels/)
+   - Import from [AsyncAPI](/docs/guides/import-from-asyncapi/) or [OpenAPI](/docs/guides/import-from-openapi/) specs
+   - [Import from an existing EventCatalog](/docs/guides/import-from-eventcatalog/)
+   - [Export your model to EventCatalog](/docs/guides/export-to-eventcatalog/)
+   - Use the [VSCode extension or CLI](/docs/tooling/editors/) for a local workflow
+
+</Steps>
diff --git a/packages/language-server/docs/src/content/docs/guides/export-to-eventcatalog.mdx b/packages/language-server/docs/src/content/docs/guides/export-to-eventcatalog.mdx
new file mode 100644
index 000000000..edef887ba
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/guides/export-to-eventcatalog.mdx
@@ -0,0 +1,80 @@
+---
+title: Export to EventCatalog
+description: Turn your .ec models into EventCatalog documentation with the CLI.
+---
+
+Once you have modeled your architecture in `.ec` files, you can export them back into EventCatalog. This turns your models into browsable, versioned documentation that your whole team can discover.
+
+## How it works
+
+The CLI reads your `.ec` files and creates or updates matching resources in your EventCatalog directory. Services become service pages, events become event pages, and so on.
+
+```bash
+npx @eventcatalog/cli --dir ./catalog import ./main.ec
+```
+
+## Import a single file
+
+```bash
+npx @eventcatalog/cli --dir ./catalog import ./main.ec
+```
+
+## Import multiple files
+
+```bash
+npx @eventcatalog/cli --dir ./catalog import ./core.ec ./payments.ec ./shipping.ec
+```
+
+## Import from stdin
+
+Pipe `.ec` content directly into the CLI:
+
+```bash
+cat ./main.ec | npx @eventcatalog/cli --dir ./catalog import --stdin
+```
+
+## Preview changes first
+
+Use `--dry-run` to see what would be created or updated without writing anything:
+
+```bash
+npx @eventcatalog/cli --dir ./catalog import ./main.ec --dry-run
+```
+
+## What gets created
+
+The CLI creates EventCatalog resources for everything defined in your `.ec` files:
+
+| .ec definition | EventCatalog resource |
+| -------------- | --------------------- |
+| `service`      | Service page          |
+| `event`        | Event page            |
+| `command`      | Command page          |
+| `query`        | Query page            |
+| `domain`       | Domain page           |
+| `channel`      | Channel page          |
+| `container`    | Container page        |
+| `data-product` | Data Product page     |
+| `user`         | User page             |
+| `team`         | Team page             |
+
+If a resource already exists, it gets updated. If you are importing a newer version, the CLI versions the previous content automatically.
+
+## Flags
+
+| Flag        | What it does                                              |
+| ----------- | --------------------------------------------------------- |
+| `--dry-run` | Preview creates, updates, and versioning without writing  |
+| `--flat`    | Write resources in top-level folders instead of nesting   |
+| `--no-init` | Skip initialization prompts (useful in CI/CD)             |
+
+## The design-to-documentation workflow
+
+This is the core loop for keeping models and documentation in sync:
+
+1. **Model** your architecture in `.ec` files
+2. **Review** the changes in a pull request
+3. **Export** to EventCatalog with the CLI
+4. **Browse** the updated documentation in your catalog
+
+Your `.ec` files become the source of truth for architectural decisions. EventCatalog becomes the place where everyone discovers and reads them.
diff --git a/packages/language-server/docs/src/content/docs/guides/export-to-static-site.mdx b/packages/language-server/docs/src/content/docs/guides/export-to-static-site.mdx
new file mode 100644
index 000000000..d73374101
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/guides/export-to-static-site.mdx
@@ -0,0 +1,19 @@
+---
+title: Export to static site
+description: Export your .ec models as static diagrams and websites you can share anywhere.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="caution" title="Coming soon">
+  Static site export is not yet available. This page describes the planned feature.
+</Aside>
+
+Export your `.ec` files as standalone static diagrams and pages. Share architecture visualizations without requiring anyone to install tooling or run a server.
+
+## Planned capabilities
+
+- Export `.ec` files as static HTML pages with interactive diagrams
+- Generate PNG or SVG images of your architecture
+- Share a link to a self-contained page that anyone can view in a browser
+- Embed diagrams in wikis, READMEs, or slide decks
diff --git a/packages/language-server/docs/src/content/docs/guides/import-from-asyncapi.mdx b/packages/language-server/docs/src/content/docs/guides/import-from-asyncapi.mdx
new file mode 100644
index 000000000..36d695d88
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/guides/import-from-asyncapi.mdx
@@ -0,0 +1,170 @@
+---
+title: Import from AsyncAPI
+description: Import events, channels, and operations from your AsyncAPI specs into .ec models.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+If you already have AsyncAPI specs, you can import resources directly into your `.ec` files. No need to re-type what your specs already describe.
+
+## What gets imported
+
+From an AsyncAPI file, you can import:
+
+| Resource type | What it maps to                                             |
+| ------------- | ----------------------------------------------------------- |
+| `events`      | Messages defined in the spec (publish/subscribe operations) |
+| `channels`    | Channel definitions with addresses and protocols            |
+
+## Import specific resources
+
+Pick exactly the events and channels you need:
+
+<Tabs>
+<TabItem label="main.ec">
+```ec
+import events { OrderCreated, OrderShipped } from "./orders-asyncapi.yml"
+import channels { orderCreated, orderShipped } from "./orders-asyncapi.yml"
+
+visualizer main {
+  name "Order Processing"
+
+  service OrderService {
+    version 1.0.0
+    sends event OrderCreated to orderCreated
+    sends event OrderShipped to orderShipped
+  }
+
+  service ShippingService {
+    version 1.0.0
+    receives event OrderCreated from orderCreated
+    sends event OrderShipped to orderShipped
+  }
+}
+```
+</TabItem>
+<TabItem label="orders-asyncapi.yml">
+```yaml
+asyncapi: 3.0.0
+info:
+  title: Order Service
+  version: 1.0.0
+
+channels:
+  orderCreated:
+    address: orders.created
+    messages:
+      OrderCreated:
+        payload:
+          type: object
+          properties:
+            orderId:
+              type: string
+            customerId:
+              type: string
+            totalAmount:
+              type: number
+  orderShipped:
+    address: orders.shipped
+    messages:
+      OrderShipped:
+        payload:
+          type: object
+          properties:
+            orderId:
+              type: string
+            trackingNumber:
+              type: string
+```
+</TabItem>
+</Tabs>
+
+## Import a service from a spec
+
+You can import a full service directly from a spec. This brings in the service with all its events, channels, and operations resolved from the file:
+
+<Tabs>
+<TabItem label="main.ec">
+```ec
+import OrderService from "./orders-asyncapi.yml"
+
+visualizer main {
+  name "Order Processing"
+
+  service OrderService
+
+  service NotificationService {
+    version 1.0.0
+    receives event OrderShipped
+    receives event OrderCancelled
+  }
+}
+```
+</TabItem>
+<TabItem label="orders-asyncapi.yml">
+```yaml
+asyncapi: 3.0.0
+info:
+  title: Order Service
+  version: 1.0.0
+
+channels:
+  orderCreated:
+    address: orders.created
+    messages:
+      OrderCreated:
+        payload:
+          type: object
+  orderShipped:
+    address: orders.shipped
+    messages:
+      OrderShipped:
+        payload:
+          type: object
+  orderCancelled:
+    address: orders.cancelled
+    messages:
+      OrderCancelled:
+        payload:
+          type: object
+```
+</TabItem>
+</Tabs>
+
+The imported `OrderService` comes in with everything the spec defines. You can then model new services around it.
+
+## Build on imported resources
+
+Once imported, use the resources in your model like any other. Add domains, ownership, and new services around them:
+
+```ec title="main.ec"
+import events { OrderCreated, OrderShipped, OrderCancelled } from "./orders-asyncapi.yml"
+import channels { orderCreated, orderShipped, orderCancelled } from "./orders-asyncapi.yml"
+
+visualizer main {
+  name "Order Management"
+
+  domain OrderManagement {
+    version 1.0.0
+    owner @order-team
+
+    service OrderService {
+      version 1.0.0
+      sends event OrderCreated to orderCreated
+      sends event OrderShipped to orderShipped
+      sends event OrderCancelled to orderCancelled
+    }
+
+    service NotificationService {
+      version 1.0.0
+      summary "Sends customer notifications"
+      receives event OrderShipped from orderShipped
+      receives event OrderCancelled from orderCancelled
+    }
+  }
+}
+```
+
+## Supported AsyncAPI versions
+
+Compass supports AsyncAPI 2.x and 3.x specs in YAML and JSON formats.
diff --git a/packages/language-server/docs/src/content/docs/guides/import-from-ec-files.mdx b/packages/language-server/docs/src/content/docs/guides/import-from-ec-files.mdx
new file mode 100644
index 000000000..073777579
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/guides/import-from-ec-files.mdx
@@ -0,0 +1,250 @@
+---
+title: Import from .ec files
+description: Split your architecture across multiple .ec files and import resources between them.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+As your architecture grows, you can split your model across multiple `.ec` files and import resources between them. This keeps files focused and avoids duplication.
+
+## Import resources
+
+Pull any resources from another `.ec` file by name. No type keywords needed:
+
+<Tabs>
+<TabItem label="main.ec">
+```ec
+import { OrderService } from "./services/orders.ec"
+import { OrderCreated, OrderShipped } from "./events/order-events.ec"
+import { orderEvents } from "./channels.ec"
+
+visualizer main {
+  name "Order System"
+
+  service OrderService
+
+  service ShippingService {
+    version 1.0.0
+    receives event OrderCreated from orderEvents
+    sends event OrderShipped to orderEvents
+  }
+}
+```
+</TabItem>
+<TabItem label="services/orders.ec">
+```ec
+service OrderService {
+  version 1.0.0
+  summary "Manages order lifecycle"
+  owner @order-team
+  sends event OrderCreated to orderEvents
+  sends event OrderShipped to orderEvents
+}
+```
+</TabItem>
+<TabItem label="events/order-events.ec">
+```ec
+event OrderCreated {
+  version 1.0.0
+  summary "Raised when a new order is placed"
+}
+
+event OrderShipped {
+  version 1.0.0
+  summary "Raised when an order ships"
+}
+```
+</TabItem>
+</Tabs>
+
+## Import many resources at once
+
+Group all the resources you need in a single import block:
+
+<Tabs>
+<TabItem label="main.ec">
+```ec
+import {
+  OrderCreated, OrderShipped, OrderCancelled,
+  PaymentProcessed, PaymentFailed,
+  CreateOrder, GetOrderStatus
+} from "./messages.ec"
+
+import {
+  OrderService, PaymentService, InventoryService,
+  NotificationService
+} from "./services.ec"
+
+visualizer main {
+  name "Order Processing"
+
+  service OrderService
+  service PaymentService
+  service InventoryService
+  service NotificationService
+}
+```
+</TabItem>
+<TabItem label="messages.ec">
+```ec
+event OrderCreated {
+  version 1.0.0
+  summary "Raised when a new order is placed"
+}
+
+event OrderShipped {
+  version 1.0.0
+  summary "Raised when an order ships"
+}
+
+event OrderCancelled {
+  version 1.0.0
+  summary "Raised when an order is cancelled"
+}
+
+event PaymentProcessed {
+  version 1.0.0
+  summary "Raised when payment completes"
+}
+
+event PaymentFailed {
+  version 1.0.0
+  summary "Raised when payment fails"
+}
+
+command CreateOrder {
+  version 1.0.0
+  summary "Creates a new order"
+}
+
+query GetOrderStatus {
+  version 1.0.0
+  summary "Returns current order status"
+}
+```
+</TabItem>
+<TabItem label="services.ec">
+```ec
+service OrderService {
+  version 1.0.0
+  summary "Manages order lifecycle"
+  sends event OrderCreated
+  sends event OrderShipped
+  receives command CreateOrder
+  receives query GetOrderStatus
+}
+
+service PaymentService {
+  version 1.0.0
+  summary "Handles payments"
+  receives event OrderCreated
+  sends event PaymentProcessed
+  sends event PaymentFailed
+}
+
+service InventoryService {
+  version 1.0.0
+  summary "Tracks stock levels"
+  receives event OrderCreated
+}
+
+service NotificationService {
+  version 1.0.0
+  summary "Sends customer notifications"
+  receives event OrderShipped
+  receives event OrderCancelled
+}
+```
+</TabItem>
+</Tabs>
+
+## Organize by domain
+
+A common pattern is one file per domain or bounded context:
+
+<Tabs>
+<TabItem label="main.ec">
+```ec
+import { OrderService, PaymentService, OrderCreated, PaymentProcessed } from "./domains/commerce.ec"
+import { ShippingService } from "./domains/logistics.ec"
+
+visualizer main {
+  name "Full System Overview"
+
+  domain Commerce {
+    version 1.0.0
+    service OrderService
+    service PaymentService
+  }
+
+  domain Logistics {
+    version 1.0.0
+    service ShippingService
+  }
+}
+```
+</TabItem>
+<TabItem label="domains/commerce.ec">
+```ec
+service OrderService {
+  version 1.0.0
+  sends event OrderCreated
+}
+
+service PaymentService {
+  version 1.0.0
+  receives event OrderCreated
+  sends event PaymentProcessed
+}
+
+event OrderCreated {
+  version 1.0.0
+}
+
+event PaymentProcessed {
+  version 1.0.0
+}
+```
+</TabItem>
+<TabItem label="domains/logistics.ec">
+```ec
+service ShippingService {
+  version 1.0.0
+  receives event PaymentProcessed
+  sends event ShipmentDispatched
+}
+```
+</TabItem>
+</Tabs>
+
+## Mix .ec imports with spec imports
+
+You can import from `.ec` files and spec files in the same model:
+
+```ec title="main.ec"
+import { PaymentService } from "./domains/payments.ec"
+import OrderService from "./orders-openapi.yml"
+import events { InventoryReserved } from "./inventory-asyncapi.yml"
+
+visualizer main {
+  name "Checkout Flow"
+
+  service OrderService
+  service PaymentService
+
+  service InventoryService {
+    version 1.0.0
+    receives event OrderCreated
+    sends event InventoryReserved
+  }
+}
+```
+
+## When to split files
+
+| Scenario                      | Approach                                                      |
+| ----------------------------- | ------------------------------------------------------------- |
+| Small system (< 5 services)   | One `main.ec` file is fine                                    |
+| Medium system (5-15 services) | Split by domain or team                                       |
+| Large system (15+ services)   | One file per domain, shared events/channels in separate files |
+| Multi-team collaboration      | Each team owns their `.ec` files, main file imports from all  |
diff --git a/packages/language-server/docs/src/content/docs/guides/import-from-eventcatalog.mdx b/packages/language-server/docs/src/content/docs/guides/import-from-eventcatalog.mdx
new file mode 100644
index 000000000..9f111d4ad
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/guides/import-from-eventcatalog.mdx
@@ -0,0 +1,113 @@
+---
+title: Import from EventCatalog
+description: Pull existing services, events, and other resources from your EventCatalog into .ec models.
+---
+
+If you have an existing EventCatalog, you can import resources directly into your `.ec` files. This lets you build on what's already documented instead of starting from scratch.
+
+## Import resources
+
+Pull in any documented resource by name from your catalog directory:
+
+```ec title="main.ec"
+import { OrderService, PaymentService } from "./my-catalog"
+import { OrderCreated, PaymentProcessed } from "./my-catalog"
+
+visualizer main {
+  name "Shipping Design"
+
+  service OrderService
+  service PaymentService
+
+  service ShippingService {
+    version 1.0.0
+    summary "New service we're designing"
+    receives event OrderCreated
+    receives event PaymentProcessed
+    sends event ShipmentDispatched
+  }
+}
+```
+
+The imported `OrderService` and `PaymentService` come in with their existing properties (version, summary, sends/receives). You can then model new services around them.
+
+## Import many resources at once
+
+Group everything you need in a single import:
+
+```ec title="main.ec"
+import {
+  OrderService, PaymentService, InventoryService,
+  OrderCreated, PaymentProcessed,
+  orderEvents, paymentEvents
+} from "./my-catalog"
+
+visualizer main {
+  name "Current Architecture"
+
+  service OrderService
+  service PaymentService
+  service InventoryService
+}
+```
+
+## Design future state from current state
+
+This is the core workflow for architects. Import your current system, then model what comes next:
+
+```ec title="main.ec"
+import {
+  OrderService, PaymentService, InventoryService,
+  OrderCreated, PaymentProcessed,
+  orderEvents, paymentEvents
+} from "./my-catalog"
+
+visualizer main {
+  name "Fulfillment — Future State"
+
+  // Design what we're adding
+  domain Fulfillment {
+    version 1.0.0
+    owner @logistics-team
+
+    // Existing service, now part of this domain
+    service InventoryService
+
+    // New service we're proposing
+    service ShippingService {
+      version 1.0.0
+      summary "Proposed shipping orchestrator"
+      receives event OrderCreated from orderEvents
+      receives event PaymentProcessed from paymentEvents
+      sends event ShipmentDispatched to shippingEvents
+      @note("Pending SRE review for retry strategy")
+    }
+  }
+
+  channel shippingEvents {
+    version 1.0.0
+    protocol "Kafka"
+    address "fulfillment.shipping.v1"
+  }
+}
+```
+
+## The circular workflow
+
+Importing from EventCatalog is one half of a loop:
+
+1. **Export** your catalog to `.ec` files (or import specific resources as shown above)
+2. **Model** changes: add new services, restructure domains, plan migrations
+3. **Review** the `.ec` diff in a pull request
+4. **Import back** into EventCatalog to update your documentation
+
+This keeps your documentation and your models in sync. Neither goes stale because each feeds into the other.
+
+## Export vs import
+
+| Approach                             | When to use                                                   |
+| ------------------------------------ | ------------------------------------------------------------- |
+| `import { ... } from "./my-catalog"` | You want specific resources as building blocks in a new model |
+| `npx @eventcatalog/cli export --all` | You want your entire catalog as `.ec` files to edit directly  |
+
+Both are valid. Use imports for targeted modeling work. Use CLI export for a full baseline.
diff --git a/packages/language-server/docs/src/content/docs/guides/import-from-openapi.mdx b/packages/language-server/docs/src/content/docs/guides/import-from-openapi.mdx
new file mode 100644
index 000000000..c45e9f2aa
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/guides/import-from-openapi.mdx
@@ -0,0 +1,167 @@
+---
+title: Import from OpenAPI
+description: Import operations and endpoints from your OpenAPI specs into .ec models.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+If you have OpenAPI specs, you can import operations directly into your `.ec` files and start modeling how your REST services connect.
+
+## What gets imported
+
+From an OpenAPI file, you can import:
+
+| Resource type | What it maps to                                 |
+| ------------- | ----------------------------------------------- |
+| `operations`  | API operations (mapped to commands and queries) |
+
+## Import specific operations
+
+Pick the operations you need from a spec:
+
+<Tabs>
+<TabItem label="main.ec">
+```ec
+import operations { CreateOrder, GetOrder, ListOrders } from "./orders-openapi.yml"
+
+visualizer main {
+  name "Order API"
+
+  service OrderService {
+    version 1.0.0
+    receives command CreateOrder
+    receives query GetOrder
+    receives query ListOrders
+  }
+}
+```
+</TabItem>
+<TabItem label="orders-openapi.yml">
+```yaml
+openapi: 3.0.0
+info:
+  title: Order API
+  version: 1.0.0
+
+paths:
+  /orders:
+    post:
+      operationId: CreateOrder
+      summary: Create a new order
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                customerId:
+                  type: string
+                items:
+                  type: array
+    get:
+      operationId: ListOrders
+      summary: List all orders
+      parameters:
+        - name: status
+          in: query
+          schema:
+            type: string
+  /orders/{orderId}:
+    get:
+      operationId: GetOrder
+      summary: Get order by ID
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          schema:
+            type: string
+```
+</TabItem>
+</Tabs>
+
+## Import a service from a spec
+
+You can import a full service directly from a spec. This brings in the service with all its operations resolved from the file:
+
+<Tabs>
+<TabItem label="main.ec">
+```ec
+import OrderService from "./orders-openapi.yml"
+
+visualizer main {
+  name "Order Management"
+
+  service OrderService
+
+  service FulfillmentService {
+    version 1.0.0
+    receives query GetOrder
+    sends event OrderFulfilled
+  }
+}
+```
+</TabItem>
+<TabItem label="orders-openapi.yml">
+```yaml
+openapi: 3.0.0
+info:
+  title: Order Service
+  version: 1.0.0
+
+paths:
+  /orders:
+    post:
+      operationId: CreateOrder
+      summary: Create a new order
+    get:
+      operationId: ListOrders
+      summary: List all orders
+  /orders/{orderId}:
+    get:
+      operationId: GetOrder
+      summary: Get order by ID
+    put:
+      operationId: UpdateOrder
+      summary: Update an existing order
+```
+</TabItem>
+</Tabs>
+
+The imported `OrderService` comes in with all its operations. You can then model new services around it.
+
+## Combine with AsyncAPI imports
+
+A real system often has both REST APIs and async messaging. You can import from both in the same model:
+
+```ec title="main.ec"
+import operations { CreateOrder, GetOrder } from "./orders-openapi.yml"
+import events { OrderCreated, OrderShipped } from "./orders-asyncapi.yml"
+import channels { orderEvents } from "./orders-asyncapi.yml"
+
+visualizer main {
+  name "Order System"
+
+  service OrderService {
+    version 1.0.0
+    summary "Manages order lifecycle"
+
+    // REST operations
+    receives command CreateOrder
+    receives query GetOrder
+
+    // Async messaging
+    sends event OrderCreated to orderEvents
+    sends event OrderShipped to orderEvents
+  }
+
+  service ShippingService {
+    version 1.0.0
+    receives event OrderCreated from orderEvents
+  }
+}
+```
+
+## Supported OpenAPI versions
+
+Compass supports OpenAPI 3.x specs in YAML and JSON formats.
diff --git a/packages/language-server/docs/src/content/docs/index.md b/packages/language-server/docs/src/content/docs/index.md
new file mode 100644
index 000000000..8b7139e15
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/index.md
@@ -0,0 +1,54 @@
+---
+title: EventCatalog Compass
+description: Model your event-driven architecture in .ec files and keep it in sync with EventCatalog.
+---
+
+Architecture design usually starts in Miro boards, Confluence pages, and Slack threads.
+They’re great for brainstorming — but they go stale the moment implementation begins.
+
+Compass exists to answer a simple question:
+
+- Why can’t we design using the specs and documentation we already have?
+- Why can’t we model future ideas from what already exists?
+- Why can’t architecture evolve alongside the system?
+
+Compass lets you model architecture in .ec files.
+
+Import resources from AsyncAPI, OpenAPI, or EventCatalog.
+Compose new domains, services, and flows.
+Export your model back to EventCatalog and give your team a living architecture portal.
+
+:::caution[Beta]
+Compass and the `.ec` docs experience are in beta.
+Share feedback in [GitHub Issues](https://github.com/event-catalog/eventcatalog/issues/new).
+:::
+
+## Why `.ec` files
+
+.ec is a text-based format for modeling distributed systems.
+
+Define services, messages, domains, and channels in a single readable file.
+
+Because it’s plain text, you get things diagrams and wikis can’t:
+
+- **Start from what you already have**. Import events, operations, and channels from AsyncAPI and OpenAPI. No retyping what your specs already describe.
+- **Build on existing documentation.** Pull services, messages, and domains from EventCatalog and use them as building blocks for new designs.
+- **Review changes like code.** Architecture updates become Git diffs and pull requests.
+- **Iterate without friction.** Model and refine future-state ideas directly in your repository.
+- **Keep docs and models aligned.** Move between EventCatalog and .ec without drift.
+- **Structured and machine-readable.** .ec is constrained and parseable, making it easy to analyze, generate, or refactor programmatically.
+
+## How it works
+
+- **Model** resources in .ec files using a readable DSL.
+- **Review** changes through Git diffs and pull requests.
+- **Publish** models to EventCatalog to generate documentation.
+- **Refine** the next change from your .ec files.
+
+Your documentation is never a static snapshot. It becomes the starting point for the next iteration.
+
+## Get started
+
+- **New to Compass?** Start with the [Tutorial](/docs/get-started/tutorial/) to build your first model.
+- **Want the full reference?** Read the [DSL Specification](/docs/reference/dsl-spec/).
+- **Explore resources:** [Services](/docs/resources/services/) | [Messages](/docs/resources/messages/) | [Domains](/docs/resources/domains/) | [Channels](/docs/resources/channels/)
diff --git a/packages/language-server/docs/src/content/docs/reference/command-cheatsheet.md b/packages/language-server/docs/src/content/docs/reference/command-cheatsheet.md
new file mode 100644
index 000000000..11095f0d5
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/reference/command-cheatsheet.md
@@ -0,0 +1,47 @@
+---
+title: Command Cheatsheet
+description: Quick copy/paste commands for .ec import and export workflows.
+---
+
+## Import
+
+```bash
+# Import one file
+npx @eventcatalog/cli --dir ./catalog import ./catalog.ec
+
+# Import multiple files
+npx @eventcatalog/cli --dir ./catalog import ./core.ec ./payments.ec
+
+# Dry run
+npx @eventcatalog/cli --dir ./catalog import ./catalog.ec --dry-run
+
+# Flat write mode
+npx @eventcatalog/cli --dir ./catalog import ./catalog.ec --flat
+
+# Read from stdin
+cat ./catalog.ec | npx @eventcatalog/cli --dir ./catalog import --stdin
+```
+
+## Export
+
+```bash
+# Export all resources
+npx @eventcatalog/cli --dir ./catalog export --all --stdout
+
+# Export all services
+npx @eventcatalog/cli --dir ./catalog export --resource service --stdout
+
+# Export one event
+npx @eventcatalog/cli --dir ./catalog export --resource event --id OrderCreated --stdout
+
+# Hydrated export
+npx @eventcatalog/cli --dir ./catalog export --resource service --id OrdersService --hydrate --stdout
+```
+
+## Build docs site
+
+```bash
+pnpm --filter @eventcatalog/cli docs:dev
+pnpm --filter @eventcatalog/cli docs:build
+pnpm --filter @eventcatalog/cli docs:preview
+```
diff --git a/packages/language-server/docs/src/content/docs/reference/dsl-spec.md b/packages/language-server/docs/src/content/docs/reference/dsl-spec.md
new file mode 100644
index 000000000..3fe811989
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/reference/dsl-spec.md
@@ -0,0 +1,1923 @@
+---
+title: Specification
+description: Full EventCatalog DSL reference from the language server spec.
+---
+
+# EventCatalog DSL — Language Specification
+
+> Version: 1.0.0-draft
+> Status: Draft
+> Date: 2026-02-08
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Domain](#domain)
+3. [Service](#service)
+4. [Event](#event)
+5. [Command](#command)
+6. [Query](#query)
+7. [Channel](#channel)
+8. [Container](#container)
+9. [Data Product](#data-product)
+10. [Flow](#flow)
+11. [User](#user)
+12. [Team](#team)
+13. [Relationships & Pointers](#relationships--pointers)
+14. [Versioning](#versioning)
+15. [Metadata & Annotations](#metadata--annotations)
+16. [Complete Examples](#complete-examples)
+17. [Full Grammar (EBNF)](#full-grammar-ebnf)
+
+---
+
+# Overview
+
+The EventCatalog DSL (ECDSL) is a human-readable, declarative language for defining event-driven architectures. It compiles to EventCatalog's frontmatter/markdown format, enabling teams to define domains, services, messages, channels, and their relationships in a single coherent source.
+
+```
+domain Payment {
+  version 1.0.0
+  owner payment-team
+
+  service PaymentService {
+    version 1.0.0
+
+    sends event PaymentProcessed {
+      version 1.0.0
+      summary "Emitted when a payment completes successfully"
+    }
+
+    receives command ProcessPayment
+    receives event OrderCreated
+  }
+}
+```
+
+## Design Principles
+
+1. **Readable** — Reads like English; minimal punctuation
+2. **Hierarchical** — Nesting reflects domain ownership and relationships
+3. **Concise** — Sane defaults; only specify what you need
+4. **Complete** — Can express everything EventCatalog supports
+5. **Composable** — Resources can be defined inline or referenced by ID
+
+## Lexical Structure
+
+### Comments
+
+```
+// Single-line comment
+
+/* Multi-line
+   comment */
+```
+
+### Strings
+
+```
+"double-quoted string"
+```
+
+Strings are required for values containing spaces, special characters, or multi-word text. Bare identifiers (no spaces, alphanumeric + hyphens + dots) can be unquoted. Strings follow JSON-style escaping (`\"`, `\\`, `\n`, etc.); raw `"` inside a string is not allowed.
+
+### Identifiers
+
+Identifiers are bare words used for resource IDs and type names. Keywords are reserved and cannot be used as identifiers.
+
+```
+OrderCreated          // simple
+Payment.OrderCreated  // namespaced
+my-service-name       // kebab-case
+```
+
+### Version Literals
+
+Semantic versions are bare (unquoted):
+
+```
+version 1.0.0
+version 2.1.0-beta.1
+```
+
+### Blocks
+
+Curly braces delimit blocks. Properties inside blocks are newline-separated (no commas).
+
+```
+resource Foo {
+  property value
+  property "value with spaces"
+}
+```
+
+### Property Multiplicity
+
+The grammar allows any property to appear multiple times inside a block. The semantic rules are:
+
+**Single-value properties** — if repeated, the last occurrence wins:
+
+`version`, `name`, `summary`, `address`, `protocol`, `deprecated`, `draft`, `container-type`, `technology`, `authoritative`, `access-mode`, `classification`, `residency`, `retention`
+
+`schema` is also single-value but only valid on messages (`event`, `command`, `query`, and inline message definitions).
+
+**Repeatable properties** — each occurrence appends a value:
+
+`owner`, `sends`, `receives`, `writes-to`, `reads-from`, `flow`, `service` (ref), `subdomain`, `data-product`, `route`, `input`, `output`, `member`, `parameter`
+
+`parameter` names must be unique within a channel; duplicate names are an error.
+
+Annotations are repeatable by default (see Metadata & Annotations).
+
+Unknown properties are parse errors — only the properties listed in each resource's grammar are valid. Duplicate single-value properties are syntactically valid (last wins) but tooling may warn.
+
+---
+
+# Domain
+
+Top-level bounded context. Can contain services, subdomains, data products, and flows.
+
+```
+domain <id> {
+  // Required
+  version <semver>
+  name "<display name>"          // optional, defaults to id
+
+  // Optional metadata
+  summary "<text>"
+  owner <owner-ref>              // repeatable
+  deprecated true
+  draft true
+
+  // Relationships
+  service <service-ref>          // repeatable (reference to external service)
+  subdomain <domain-ref>         // repeatable
+  data-product <dp-ref>          // repeatable
+  flow <flow-ref>                // repeatable
+
+  // Domain-level message routing
+  sends <message-type> <id> [to <channel-ref>]
+  receives <message-type> <id> [from <channel-ref>]
+
+  // Inline definitions
+  service <id> { ... }
+  subdomain <id> { ... }
+
+  // Annotations (see Metadata section)
+  @badge(...)
+  @repository(...)
+}
+```
+
+## Subdomains
+
+Domains can contain nested subdomains:
+
+```
+domain Logistics {
+  version 1.0.0
+
+  subdomain Shipping {
+    version 1.0.0
+    summary "Package shipping and tracking"
+
+    service ShippingService {
+      version 1.0.0
+      receives event OrderCreated
+      sends event ShipmentCreated
+    }
+  }
+
+  subdomain Returns {
+    version 1.0.0
+    summary "Return merchandise authorization"
+
+    service ReturnsService {
+      version 1.0.0
+      receives command InitiateReturn
+      sends event ReturnApproved
+    }
+  }
+}
+```
+
+## EBNF
+
+```ebnf
+domain_decl      = "domain" identifier "{" common_props
+                   { domain_body_item } "}" ;
+domain_body_item = service_decl | subdomain_decl | service_ref_stmt
+                 | data_product_ref_stmt | flow_ref_stmt
+                 | sends_stmt | receives_stmt
+                 | annotation ;
+subdomain_decl   = "subdomain" identifier "{" common_props
+                   { domain_body_item } "}" ;
+```
+
+---
+
+# Service
+
+A microservice or application.
+
+```
+service <id> {
+  // Required
+  version <semver>
+  name "<display name>"
+
+  // Optional metadata
+  summary "<text>"
+  owner <owner-ref>              // repeatable
+  deprecated true
+  draft true
+
+  // Message relationships
+  sends <message-type> <id>[@<version>] [to <channel-list>]
+  receives <message-type> <id>[@<version>] [from <channel-list>]
+
+  // Data relationships
+  writes-to container <container-ref>      // repeatable
+  reads-from container <container-ref>     // repeatable
+
+  // Flow relationships
+  flow <flow-ref>                // repeatable
+
+  // Inline message definitions
+  sends event <id> { ... }
+  sends command <id> { ... }
+  receives query <id> { ... }
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+**Message types:** `event`, `command`, `query`
+
+## EBNF
+
+```ebnf
+service_decl     = "service" identifier "{" common_props
+                   { service_body_item } "}" ;
+service_body_item= sends_stmt | receives_stmt
+                 | writes_to_stmt | reads_from_stmt
+                 | flow_ref_stmt
+                 | annotation ;
+```
+
+---
+
+# Event
+
+A domain event — something that happened.
+
+```
+event <id> {
+  // Required
+  version <semver>
+  name "<display name>"
+
+  // Optional metadata
+  summary "<text>"
+  owner <owner-ref>
+  schema "<path>"
+  deprecated true
+  draft true
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+## EBNF
+
+```ebnf
+event_decl       = "event" identifier "{" message_props "}" ;
+```
+
+---
+
+# Command
+
+An instruction to perform an action.
+
+```
+command <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+  schema "<path>"
+  deprecated true
+  draft true
+
+  channel <channel-ref>
+
+  // Same annotations as event
+}
+```
+
+## EBNF
+
+```ebnf
+command_decl     = "command" identifier "{" message_props "}" ;
+```
+
+---
+
+# Query
+
+A request for information.
+
+```
+query <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+  schema "<path>"
+  deprecated true
+  draft true
+
+  channel <channel-ref>
+
+  // Same annotations as event
+}
+```
+
+## EBNF
+
+```ebnf
+query_decl       = "query" identifier "{" message_props "}" ;
+```
+
+---
+
+# Channel
+
+A communication channel (topic, queue, exchange, etc.).
+
+```
+channel <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+
+  address "<address-string>"
+  protocol "<protocol>"
+
+  // Channel parameters
+  parameter <name> {
+    description "<text>"
+    default "<value>"
+    enum ["<val1>", "<val2>"]
+    examples ["<ex1>", "<ex2>"]
+  }
+
+  // Routing
+  route <channel-ref>            // repeatable
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+## Channel-to-Channel Routing
+
+Channels can route to other channels using the `route` statement. This models message pipelines where data flows through multiple channels (e.g., Kafka topic → Kafka topic → MQTT broker):
+
+```
+channel SensorIngestion {
+  version 1.0.0
+  protocol "Kafka"
+  route SensorFiltered
+}
+
+channel SensorFiltered {
+  version 1.0.0
+  protocol "Kafka"
+  route MqttDevices
+}
+
+channel MqttDevices {
+  version 1.0.0
+  protocol "MQTT"
+}
+```
+
+This creates a chain: `SensorIngestion → SensorFiltered → MqttDevices`.
+
+A channel can route to multiple targets (fan-out):
+
+```
+channel Ingestion {
+  version 1.0.0
+  route Analytics
+  route Archive
+}
+```
+
+Routes can include versioned references:
+
+```
+channel Source {
+  version 1.0.0
+  route Target@2.0.0
+}
+```
+
+## Service-to-Channel Routing
+
+Services send/receive messages through channels:
+
+```
+service OrderService {
+  version 1.0.0
+
+  // Simple — no channel
+  sends event OrderCreated
+
+  // To a single channel
+  sends event OrderCreated to orders-topic
+
+  // To a channel with version (using @ syntax)
+  sends event OrderCreated to orders-topic@1.0.0
+
+  // To multiple channels (comma-separated)
+  sends event OrderCreated to orders-topic, orders-backup-topic
+
+  // To multiple channels with versions
+  sends event OrderCreated to orders-topic@1.0.0, orders-backup-topic@2.0.0
+
+  // Receiving from a single channel
+  receives event PaymentProcessed from payment-events
+
+  // Receiving from multiple channels
+  receives event PaymentProcessed from payment-events, payment-retry-queue
+
+  // Receiving from channels with versions
+  receives event PaymentProcessed from payment-events@1.0.0, payment-retry-queue@2.1.0
+}
+```
+
+## EBNF
+
+```ebnf
+channel_decl     = "channel" identifier "{" common_props
+                   { channel_body_item } "}" ;
+channel_body_item= address_prop | protocol_prop | parameter_decl
+                 | route_stmt | annotation ;
+address_prop     = "address" string_lit ;
+protocol_prop    = "protocol" string_lit ;
+parameter_decl   = "parameter" identifier "{" { param_prop } "}" ;
+param_prop       = "description" string_lit
+                 | "default" string_lit
+                 | "enum" "[" string_lit { "," string_lit } "]"
+                 | "examples" "[" string_lit { "," string_lit } "]" ;
+route_stmt       = "route" resource_ref ;
+
+channel_clause   = to_clause | from_clause ;
+to_clause        = "to" channel_ref_list ;
+from_clause      = "from" channel_ref_list ;
+channel_ref_list = channel_ref { "," channel_ref } ;
+channel_ref      = identifier [ "@" version_lit ] ;
+```
+
+---
+
+# Container
+
+A data store, cache, or external system.
+
+```
+container <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+
+  // Required
+  container-type <database | cache | objectStore | searchIndex
+                 | dataWarehouse | dataLake | externalSaaS | other>
+
+  // Optional
+  deprecated true
+  draft true
+  technology "<tech-string>"     // e.g., "postgres@15", "redis@7"
+  authoritative true
+  access-mode <read | write | readWrite | appendOnly>
+  classification <public | internal | confidential | regulated>
+  residency "<location>"
+  retention "<duration>"         // e.g., "90d", "10y"
+
+  // Relationships
+  service <service-ref>          // repeatable
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+## EBNF
+
+```ebnf
+container_decl   = "container" identifier "{" common_props
+                   { container_body_item } "}" ;
+container_body_item = container_type_prop | technology_prop
+                    | authoritative_prop | access_mode_prop
+                    | classification_prop | residency_prop
+                    | retention_prop
+                    | service_ref_stmt | annotation ;
+container_type_prop   = "container-type" container_type_enum ;
+container_type_enum   = "database" | "cache" | "objectStore" | "searchIndex"
+                      | "dataWarehouse" | "dataLake" | "externalSaaS" | "other" ;
+technology_prop       = "technology" string_lit ;
+authoritative_prop    = "authoritative" bool_lit ;
+access_mode_prop      = "access-mode" ( "read" | "write" | "readWrite" | "appendOnly" ) ;
+classification_prop   = "classification" ( "public" | "internal" | "confidential" | "regulated" ) ;
+residency_prop        = "residency" string_lit ;
+retention_prop        = "retention" string_lit ;
+```
+
+---
+
+# Data Product
+
+An analytical data product.
+
+```
+data-product <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+  deprecated true
+  draft true
+
+  // Data lineage
+  input <message-type> <resource-ref>      // repeatable
+  output <message-type> <resource-ref> {   // repeatable, with optional contract
+    contract {
+      path "<path>"
+      name "<name>"
+      type "<type>"
+    }
+  }
+
+  // Annotations
+  @badge(...)
+}
+```
+
+## EBNF
+
+```ebnf
+data_product_decl = "data-product" identifier "{" common_props
+                    { dp_body_item } "}" ;
+dp_body_item      = input_stmt | output_stmt | annotation ;
+input_stmt        = "input" message_type resource_ref ;
+output_stmt       = "output" message_type resource_ref [ "{" contract_block "}" ] ;
+contract_block    = "contract" "{" "path" string_lit "name" string_lit
+                    [ "type" string_lit ] "}" ;
+```
+
+---
+
+# Flow
+
+Flows define step-by-step business processes using a PM-friendly `when`-block syntax. Resources are referenced by name only — types are resolved from the catalog.
+
+```
+flow <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+
+  // Entry chain — the starting sequence
+  <Name> ["<label>"] -> <Name> ["<label>"] -> ...
+
+  // When blocks — react to events
+  when <TriggerName>
+    <ServiceName> "<description>"
+      -> "<label>": <OutputName>
+
+  // Convergence — multiple triggers must complete
+  when <TriggerA> and <TriggerB>
+    <ServiceName> "<description>"
+}
+```
+
+## Actors and External Systems
+
+To use actors and external systems in flows, define them as top-level resources. The flow resolves their type automatically by name:
+
+```
+actor Customer {
+  name "Customer"
+  summary "End user on the storefront"
+}
+
+external-system WarehouseWMS {
+  name "Warehouse WMS"
+  summary "Legacy warehouse management system"
+}
+```
+
+Both support optional bodies with `name`, `summary`, and annotations. They can also be bare (no body):
+
+```
+actor Customer
+external-system WarehouseWMS
+```
+
+## Flow References
+
+Resources in flows are referenced by name only (no type keywords like `service` or `event`). Types are resolved from catalog definitions or sibling `.ec` files. If no matching definition is found, the default type is `step`. Compilers may warn on unresolved flow references.
+
+Each reference can include an optional label:
+
+- `Customer "places an order"` — name with display label
+- `PlaceOrder` — bare name (no label)
+- `PaymentService "processes the payment"` — service with description
+
+## Entry Chains
+
+The entry chain defines the starting sequence of a flow. It uses arrow (`->`) syntax:
+
+```
+Customer "places an order"
+  -> PlaceOrder
+  -> OrderService "creates the order"
+  -> OrderCreated
+```
+
+Multiple sources can converge into a chain using commas:
+
+```
+EventA, EventB -> MergingService
+```
+
+## When Blocks
+
+`when` blocks define reactions to events. Each block starts with one or more trigger names, followed by actions:
+
+```
+when OrderCreated
+  PaymentService "processes the payment"
+    -> "success": PaymentProcessed
+    -> "failure": PaymentFailed
+  InventoryService "reserves stock"
+    -> StockReserved
+```
+
+### Labeled Outputs
+
+Action outputs can have optional labels (quoted strings followed by a colon):
+
+```
+-> "success": PaymentProcessed    // labeled output
+-> StockReserved                   // unlabeled output
+```
+
+### Convergence
+
+Use `and` to require multiple triggers before actions execute:
+
+```
+when PaymentProcessed and StockReserved
+  FulfillmentService "ships the order"
+    -> OrderShipped
+```
+
+### Terminal Actions
+
+Actions without outputs are terminal steps:
+
+```
+when OrderShipped
+  WarehouseWMS "syncs with legacy WMS"
+  NotificationService "notifies the customer"
+```
+
+## Example
+
+```
+flow OrderFulfillment {
+  version 1.0.0
+  name "Order Fulfillment"
+  summary "End-to-end order processing from placement to delivery"
+  owner fulfillment-team
+
+  Customer "places an order"
+    -> PlaceOrder
+    -> OrderService "creates the order"
+    -> OrderCreated
+
+  when OrderCreated
+    PaymentService "processes the payment"
+      -> "success": PaymentProcessed
+      -> "failure": PaymentFailed
+    InventoryService "reserves stock"
+      -> StockReserved
+
+  when PaymentFailed
+    NotificationService "notifies the customer of failure"
+
+  when PaymentProcessed and StockReserved
+    FulfillmentService "ships the order"
+      -> OrderShipped
+
+  when OrderShipped
+    WarehouseWMS "syncs with legacy WMS"
+    NotificationService "notifies the customer"
+      -> CustomerNotified
+}
+```
+
+## EBNF
+
+```ebnf
+flow_decl         = "flow" identifier "{" common_props
+                    { flow_entry_chain | flow_when_block } "}" ;
+flow_entry_chain  = flow_ref { "," flow_ref } ( "->" flow_ref )+ ;
+flow_when_block   = "when" flow_ref { "and" flow_ref } flow_action+ ;
+flow_action       = flow_ref { flow_output } ;
+flow_output       = "->" [ string_lit ":" ] flow_ref ;
+flow_ref          = identifier [ string_lit ] ;
+```
+
+---
+
+# Diagram
+
+_Removed from V1. May be added in a future version._
+
+---
+
+# User
+
+A user definition for team members.
+
+```
+user <id> {
+  name "<display name>"
+  avatar "<url>"
+  role "<role>"
+  email "<email>"
+  slack "<url>"
+  ms-teams "<url>"
+}
+```
+
+## Example
+
+```
+user dboyne {
+  name "David Boyne"
+  avatar "https://avatars.githubusercontent.com/u/3268013"
+  role "Principal Engineer"
+  email "david@company.com"
+}
+```
+
+## EBNF
+
+```ebnf
+user_decl         = "user" identifier "{" user_props "}" ;
+user_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit ;
+```
+
+---
+
+# Team
+
+A team definition for ownership and membership.
+
+```
+team <id> {
+  name "<display name>"
+  avatar "<url>"
+  role "<role>"
+  summary "<text>"
+  email "<email>"
+  slack "<url>"
+  ms-teams "<url>"
+
+  // Members
+  member <user-id>               // repeatable
+}
+```
+
+## Owner References
+
+Owners are referenced by team or user ID:
+
+```
+service OrderService {
+  version 1.0.0
+  owner payment-team              // team reference
+  owner dboyne                   // user reference
+}
+```
+
+## Example
+
+```
+team orders-team {
+  name "Orders Team"
+  avatar "https://example.com/orders-team.png"
+  role "Platform Engineering"
+  summary "Responsible for order lifecycle"
+  email "orders@company.com"
+  slack "https://company.slack.com/channels/orders"
+
+  member dboyne
+  member jane-doe
+}
+```
+
+## EBNF
+
+```ebnf
+team_decl         = "team" identifier "{" team_props "}" ;
+team_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "summary" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit
+                  | "member" identifier ;
+```
+
+---
+
+# Relationships & Pointers
+
+## Resource References
+
+Resources can be referenced by ID alone (resolves to `latest`) or with an explicit version:
+
+```
+// Reference by ID only (latest version)
+receives event OrderCreated
+
+// Reference by ID + version using @ syntax
+receives event OrderCreated@2.0.0
+
+// Reference with single channel routing
+sends event OrderCreated to orders-topic
+
+// Reference with channel version
+sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+
+// Reference with multiple channels
+sends event OrderCreated to orders-topic, backup-topic
+receives event PaymentProcessed from payment-events, payment-retry
+```
+
+## Inline vs. Reference
+
+Resources can be defined inline (creating them) or referenced (linking to existing):
+
+```
+service OrderService {
+  version 1.0.0
+
+  // Inline definition — creates the event
+  sends event OrderCreated {
+    version 1.0.0
+    summary "A new order was placed"
+  }
+
+  // Reference only — links to an existing event
+  receives event PaymentProcessed
+  receives event PaymentProcessed@2.0.0
+}
+```
+
+Inline messages do not support the `channel` statement — use `to`/`from` on the `sends`/`receives` statement for channel routing.
+
+## Pointer Syntax Summary
+
+| Syntax                        | Meaning                       |
+| ----------------------------- | ----------------------------- |
+| `<id>`                        | Latest version of resource    |
+| `<id>@<version>`              | Specific version              |
+| `<id> to <channel>`           | With single channel routing   |
+| `<id> to <channel>@<version>` | Channel with specific version |
+| `<id> to <ch1>, <ch2>, <ch3>` | Multiple channels             |
+| `<id> from <channel>`         | Received from channel         |
+| `<id> from <ch1>, <ch2>`      | Received from multiple        |
+
+## Data Relationships
+
+```
+writes-to container <container-ref>
+reads-from container <container-ref>
+```
+
+## EBNF
+
+```ebnf
+resource_ref     = identifier [ "@" version_lit ] ;
+message_type     = "event" | "command" | "query" ;
+
+sends_stmt       = "sends" message_type resource_ref [ channel_clause ]
+                 | "sends" message_type identifier inline_block ;
+receives_stmt    = "receives" message_type resource_ref [ channel_clause ]
+                 | "receives" message_type identifier inline_block ;
+
+channel_clause   = to_clause | from_clause ;
+to_clause        = "to" channel_ref_list ;
+from_clause      = "from" channel_ref_list ;
+channel_ref_list = channel_ref { "," channel_ref } ;
+channel_ref      = identifier [ "@" version_lit ] ;
+
+writes_to_stmt   = "writes-to" "container" resource_ref ;
+reads_from_stmt  = "reads-from" "container" resource_ref ;
+flow_ref_stmt    = "flow" resource_ref ;
+data_product_ref_stmt      = "data-product" resource_ref ;
+
+inline_block     = "{" message_props "}" ;
+```
+
+---
+
+# Versioning
+
+## Declaring Versions
+
+Every versioned resource requires a version:
+
+```
+event OrderCreated {
+  version 1.0.0
+}
+```
+
+## Referencing Versions
+
+```
+// Latest (default - no version specified)
+receives event OrderCreated
+
+// Specific version using @ syntax
+receives event OrderCreated@2.0.0
+
+// Channel with version
+sends event OrderProcessed to payments-channel@1.0.0
+
+// Multiple channels with versions
+receives event PaymentFailed from channel-a@1.0.0, channel-b@2.1.0
+```
+
+## Version Defaults
+
+When no version is specified in a reference, it resolves to `latest`.
+
+## EBNF
+
+```ebnf
+int              = digit { digit } ;
+version_lit      = int "." int "." int [ "-" prerelease ] ;
+version_prop     = "version" version_lit ;
+version_ref      = "@" version_lit ;
+resource_ref     = identifier [ version_ref ] ;
+```
+
+---
+
+# Metadata & Annotations
+
+Annotations use the `@` prefix and provide additional metadata. They can appear inside any resource block. All annotations are repeatable by default — multiple instances of the same annotation may appear on a single resource.
+
+## @badge
+
+```
+@badge("Production", bg: "#22c55e", text: "#fff")
+@badge("Beta", bg: "#f59e0b", text: "#000", icon: "flask")
+```
+
+## @repository
+
+```
+@repository(url: "https://github.com/org/repo", language: "TypeScript")
+```
+
+## @editUrl
+
+```
+@editUrl("https://github.com/org/repo/edit/main/docs/orders.md")
+```
+
+## @note
+
+Adds free-form developer notes or reminders to any resource. Notes are repeatable — multiple `@note` annotations can appear on a single resource. Supported on services, events, commands, queries, channels, and inline message definitions.
+
+```
+// Simple note
+@note("Come back later — needs review")
+
+// With optional parameters
+@note("Align schema with PaymentService team", author: "dboyne", priority: "high")
+
+// Multiple notes on a service
+service OrderService {
+  version 1.0.0
+  @note("TODO: add retry logic")
+  @note("Waiting on team alignment", priority: "medium")
+}
+
+// Notes on events, commands, and queries
+event OrderCreated {
+  version 1.0.0
+  @note("Schema v2 adds shippingAddress field", author: "alice")
+}
+
+command CreateOrder {
+  version 1.0.0
+  @note("Validate idempotency key", author: "bob", priority: "high")
+}
+
+// Notes on channels
+channel OrderEvents {
+  version 1.0.0
+  address "orders.events"
+  protocol "kafka"
+  @note("Partition key is orderId", author: "infra-team")
+}
+
+// Notes on inline messages (inside sends/receives)
+service PaymentService {
+  version 1.0.0
+  sends event PaymentProcessed to PaymentEvents {
+    version 1.0.0
+    @note("Includes refund reference when applicable", author: "dave")
+  }
+}
+```
+
+## @detailsPanel
+
+Controls visibility of detail panel sections:
+
+```
+@detailsPanel {
+  owners visible
+  versions visible
+  changelog hidden
+  producers visible
+  consumers hidden
+  channels visible
+  repository hidden
+  specifications hidden
+  messages hidden
+  domains hidden
+  services hidden
+  containers hidden
+}
+```
+
+## EBNF
+
+```ebnf
+annotation       = "@" ann_name [ "(" ann_args ")" ] [ ann_block ] ;
+ann_name         = identifier ;
+ann_args         = ann_arg { "," ann_arg } ;
+ann_arg          = [ identifier ":" ] ( string_lit | bool_lit | number_lit | identifier ) ;
+ann_block        = "{" { ann_body_item } "}" ;
+```
+
+---
+
+# Complete Examples
+
+## Example 1: E-Commerce Platform
+
+```
+// ============================================================
+// Teams & Users
+// ============================================================
+
+user dboyne {
+  name "David Boyne"
+  avatar "https://avatars.githubusercontent.com/u/3268013"
+  role "Principal Engineer"
+  email "david@company.com"
+}
+
+user jane-doe {
+  name "Jane Doe"
+  avatar "https://avatars.githubusercontent.com/u/12345"
+  role "Staff Engineer"
+}
+
+team orders-team {
+  name "Orders Team"
+  summary "Responsible for order lifecycle"
+  email "orders@company.com"
+  slack "https://company.slack.com/channels/orders"
+
+  member dboyne
+  member jane-doe
+}
+
+team payment-team {
+  name "Payment Team"
+  summary "Handles payment processing and fraud detection"
+  email "payments@company.com"
+
+  member jane-doe
+}
+
+// ============================================================
+// Channels
+// ============================================================
+
+channel orders-topic {
+  version 1.0.0
+  name "Orders Topic"
+  summary "Kafka topic for all order-related events"
+  address "kafka://production/orders"
+  protocol "Kafka"
+
+  parameter environment {
+    description "Deployment environment"
+    default "production"
+    enum ["production", "staging", "development"]
+  }
+
+}
+
+channel payment-queue {
+  version 1.0.0
+  name "Payment Queue"
+  summary "SQS queue for payment commands"
+  address "sqs://us-east-1/payment-processing"
+  protocol "SQS"
+}
+
+// ============================================================
+// Containers
+// ============================================================
+
+container orders-db {
+  version 1.0.0
+  name "Orders Database"
+  summary "Primary datastore for order data"
+  owner orders-team
+
+  container-type database
+  technology "postgres@15"
+  authoritative true
+  access-mode readWrite
+  classification confidential
+  residency "us-east-1"
+  retention "7y"
+
+  @repository(url: "https://github.com/company/orders-db")
+}
+
+container orders-cache {
+  version 1.0.0
+  name "Orders Cache"
+  summary "Redis cache for hot order lookups"
+
+  container-type cache
+  technology "redis@7"
+  access-mode readWrite
+  retention "24h"
+}
+
+// ============================================================
+// Domain
+// ============================================================
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  summary "Everything related to order management"
+  owner orders-team
+
+  @badge("Core", bg: "#3b82f6", text: "#fff")
+  @repository(url: "https://github.com/company/orders-domain")
+
+  service OrderService {
+    version 1.0.0
+    name "Order Service"
+    summary "Manages the order lifecycle"
+    owner orders-team
+
+    @repository(url: "https://github.com/company/order-service", language: "TypeScript")
+    @badge("Production", bg: "#22c55e", text: "#fff")
+
+    sends event OrderCreated {
+      version 1.0.0
+      summary "Emitted when a new order is placed"
+      schema "./schemas/order-created.avro"
+    }
+
+    sends event OrderUpdated {
+      version 1.0.0
+      summary "Emitted when order details change"
+    }
+
+    sends command ProcessPayment to payment-queue {
+      version 1.0.0
+      summary "Triggers payment processing for an order"
+    }
+
+    receives event PaymentProcessed from payment-queue
+    receives event InventoryReserved
+
+    writes-to container orders-db
+    reads-from container orders-db
+    writes-to container orders-cache
+    reads-from container orders-cache
+
+    flow OrderFulfillment@1.0.0
+  }
+
+  service NotificationService {
+    version 1.0.0
+    name "Notification Service"
+    summary "Sends email and push notifications for order updates"
+
+    receives event OrderCreated
+    receives event OrderUpdated
+
+    sends command SendEmail {
+      version 1.0.0
+      summary "Dispatches an email notification"
+    }
+  }
+}
+
+domain Payment {
+  version 1.0.0
+  name "Payment Domain"
+  summary "Payment processing and fraud detection"
+  owner payment-team
+
+  service PaymentService {
+    version 1.0.0
+    name "Payment Service"
+    summary "Processes payments via Stripe"
+    owner payment-team
+
+    @repository(url: "https://github.com/company/payment-service", language: "Go")
+
+    receives command ProcessPayment from payment-queue
+
+    sends event PaymentProcessed {
+      version 1.0.0
+      summary "Payment completed successfully"
+    }
+
+    sends event PaymentFailed {
+      version 1.0.0
+      summary "Payment was declined or errored"
+    }
+  }
+}
+
+// ============================================================
+// Standalone events (defined outside services)
+// ============================================================
+
+event InventoryReserved {
+  version 1.0.0
+  name "Inventory Reserved"
+  summary "Stock has been reserved for an order"
+  owner orders-team
+
+  @badge("Critical", bg: "#ef4444", text: "#fff")
+}
+
+// ============================================================
+// Data Product
+// ============================================================
+
+data-product OrderAnalytics {
+  version 1.0.0
+  name "Order Analytics"
+  summary "Real-time and batch analytics for order metrics"
+  owner orders-team
+
+  input event OrderCreated@1.0.0
+  input event PaymentProcessed@1.0.0
+  input event InventoryReserved@1.0.0
+
+  output event OrderMetrics {
+    contract {
+      path "./contracts/order-metrics.json"
+      name "Order Metrics Schema"
+      type "json-schema"
+    }
+  }
+}
+
+// ============================================================
+// Actors & External Systems
+// ============================================================
+
+actor Customer {
+  name "Customer"
+  summary "End user on the storefront"
+}
+
+external-system WarehouseWMS {
+  name "Warehouse WMS"
+  summary "Legacy warehouse management system via SOAP API"
+}
+
+// ============================================================
+// Flow
+// ============================================================
+
+flow OrderFulfillment {
+  version 1.0.0
+  name "Order Fulfillment"
+  summary "End-to-end order processing from placement to delivery"
+  owner orders-team
+
+  Customer "End user on the storefront"
+    -> PlaceOrder
+    -> OrderService
+    -> OrderCreated
+
+  when OrderCreated
+    PaymentService "processes the payment"
+      -> "success": PaymentProcessed
+      -> "failure": PaymentFailed
+    InventoryService "reserves inventory"
+      -> InventoryReserved
+
+  when InventoryReserved
+    WarehouseWMS "Legacy WMS via SOAP API"
+}
+
+```
+
+## Example 2: Minimal Service Definition
+
+The DSL supports minimal definitions where defaults are sufficient:
+
+```
+service OrderService {
+  version 1.0.0
+  sends event OrderCreated
+  receives command ProcessPayment
+  receives event PaymentProcessed
+}
+```
+
+## Example 3: Multi-Channel Routing
+
+```
+service EventRouter {
+  version 1.0.0
+  summary "Routes events across multiple channels"
+
+  // Send to multiple channels (comma-separated)
+  sends event OrderCreated to orders-topic, orders-archive-topic
+
+  // Receive from multiple channels
+  receives event PaymentProcessed from payment-events, payment-retry-queue
+}
+```
+
+## Example 4: Channel Routing (IoT Pipeline)
+
+```
+channel SensorIngestion {
+  version 1.0.0
+  address "sensors.raw"
+  protocol "Kafka"
+  summary "Raw sensor data ingestion"
+  route SensorFiltered
+}
+
+channel SensorFiltered {
+  version 1.0.0
+  address "sensors.filtered"
+  protocol "Kafka"
+  summary "Validated sensor data"
+  route DeviceCommands
+}
+
+channel DeviceCommands {
+  version 1.0.0
+  address "devices/+/commands"
+  protocol "MQTT"
+  summary "MQTT topic for device commands"
+}
+
+service SensorGateway {
+  version 1.0.0
+  summary "Ingests raw sensor readings"
+  sends event SensorReading to SensorIngestion
+}
+
+service FilterService {
+  version 1.0.0
+  summary "Validates and filters sensor data"
+  receives event SensorReading from SensorIngestion
+  sends event DeviceAlert to SensorFiltered
+}
+
+service DeviceBridge {
+  version 1.0.0
+  summary "Bridges Kafka to MQTT"
+  receives event DeviceAlert from SensorFiltered
+  sends command RecalibrateDevice to DeviceCommands
+}
+```
+
+## Example 5: Subdomains
+
+```
+domain Logistics {
+  version 1.0.0
+
+  subdomain Shipping {
+    version 1.0.0
+    summary "Package shipping and tracking"
+
+    service ShippingService {
+      version 1.0.0
+      receives event OrderCreated
+      sends event ShipmentCreated
+    }
+  }
+
+  subdomain Returns {
+    version 1.0.0
+    summary "Return merchandise authorization"
+
+    service ReturnsService {
+      version 1.0.0
+      receives command InitiateReturn
+      sends event ReturnApproved
+    }
+  }
+}
+```
+
+---
+
+# Full Grammar (EBNF)
+
+```ebnf
+(* Top-level *)
+program          = { top_level_decl } ;
+top_level_decl   = domain_decl | service_decl | event_decl | command_decl
+                 | query_decl | channel_decl | container_decl
+                 | data_product_decl | flow_decl
+                 | user_decl | team_decl | visualizer_decl
+                 | actor_decl | external_system_decl ;
+
+(* Identifiers and literals *)
+identifier       = letter { letter | digit | "-" | "." | "_" } ;
+int              = digit { digit } ;
+version_lit      = int "." int "." int [ "-" prerelease ] ;
+string_lit       = '"' { any_char } '"' ;
+bool_lit         = "true" | "false" ;
+number_lit       = digit { digit } ;
+
+(* Common properties *)
+common_props     = { version_prop | name_prop | summary_prop | owner_prop
+                   | deprecated_prop | draft_prop | annotation } ;
+message_props    = { version_prop | name_prop | summary_prop | owner_prop
+                   | schema_prop | deprecated_prop | draft_prop | annotation } ;
+version_prop     = "version" version_lit ;
+name_prop        = "name" string_lit ;
+summary_prop     = "summary" string_lit ;
+owner_prop       = "owner" identifier ;
+schema_prop      = "schema" string_lit ;
+deprecated_prop  = "deprecated" bool_lit ;
+draft_prop       = "draft" bool_lit ;
+
+(* Annotations *)
+annotation       = "@" ann_name [ "(" ann_args ")" ] [ ann_block ] ;
+ann_name         = identifier ;
+ann_args         = ann_arg { "," ann_arg } ;
+ann_arg          = [ identifier ":" ] ( string_lit | bool_lit | number_lit | identifier ) ;
+ann_block        = "{" { ann_body_item } "}" ;
+
+(* Resource references *)
+resource_ref     = identifier [ "@" version_lit ] ;
+message_type     = "event" | "command" | "query" ;
+
+(* Domain *)
+domain_decl      = "domain" identifier "{" common_props
+                   { domain_body_item } "}" ;
+domain_body_item = service_decl | subdomain_decl
+                 | data_product_ref_stmt | flow_ref_stmt
+                 | sends_stmt | receives_stmt
+                 | annotation ;
+subdomain_decl   = "subdomain" identifier "{" common_props
+                   { domain_body_item } "}" ;
+
+(* Service *)
+service_decl     = "service" identifier "{" common_props
+                   { service_body_item } "}" ;
+service_body_item= sends_stmt | receives_stmt
+                 | writes_to_stmt | reads_from_stmt
+                 | flow_ref_stmt
+                 | annotation ;
+
+(* Sends / Receives *)
+sends_stmt       = "sends" message_type resource_ref [ channel_clause ]
+                 | "sends" message_type identifier inline_block ;
+receives_stmt    = "receives" message_type resource_ref [ channel_clause ]
+                 | "receives" message_type identifier inline_block ;
+
+channel_clause   = to_clause | from_clause ;
+to_clause        = "to" channel_ref_list ;
+from_clause      = "from" channel_ref_list ;
+channel_ref_list = channel_ref { "," channel_ref } ;
+channel_ref      = identifier [ "@" version_lit ] ;
+
+(* Data relationships *)
+writes_to_stmt   = "writes-to" "container" resource_ref ;
+reads_from_stmt  = "reads-from" "container" resource_ref ;
+flow_ref_stmt    = "flow" resource_ref ;
+data_product_ref_stmt      = "data-product" resource_ref ;
+
+(* Inline message block *)
+inline_block     = "{" message_props "}" ;
+
+(* Messages: Event, Command, Query *)
+event_decl       = "event" identifier "{" message_props "}" ;
+command_decl     = "command" identifier "{" message_props "}" ;
+query_decl       = "query" identifier "{" message_props "}" ;
+
+(* Channel *)
+channel_decl     = "channel" identifier "{" common_props
+                   { channel_body_item } "}" ;
+channel_body_item= address_prop | protocol_prop | parameter_decl
+                 | route_stmt | annotation ;
+address_prop     = "address" string_lit ;
+protocol_prop    = "protocol" string_lit ;
+parameter_decl   = "parameter" identifier "{" { param_prop } "}" ;
+param_prop       = "description" string_lit
+                 | "default" string_lit
+                 | "enum" "[" string_lit { "," string_lit } "]"
+                 | "examples" "[" string_lit { "," string_lit } "]" ;
+route_stmt       = "route" resource_ref ;
+
+(* Container *)
+container_decl   = "container" identifier "{" common_props
+                   { container_body_item } "}" ;
+container_body_item = container_type_prop | technology_prop
+                    | authoritative_prop | access_mode_prop
+                    | classification_prop | residency_prop
+                    | retention_prop
+                    | service_ref_stmt | annotation ;
+container_type_prop   = "container-type" container_type_enum ;
+container_type_enum   = "database" | "cache" | "objectStore" | "searchIndex"
+                      | "dataWarehouse" | "dataLake" | "externalSaaS" | "other" ;
+technology_prop       = "technology" string_lit ;
+authoritative_prop    = "authoritative" bool_lit ;
+access_mode_prop      = "access-mode" ( "read" | "write" | "readWrite" | "appendOnly" ) ;
+classification_prop   = "classification" ( "public" | "internal" | "confidential" | "regulated" ) ;
+residency_prop        = "residency" string_lit ;
+retention_prop        = "retention" string_lit ;
+
+(* Data Product *)
+data_product_decl = "data-product" identifier "{" common_props
+                    { dp_body_item } "}" ;
+dp_body_item      = input_stmt | output_stmt | annotation ;
+input_stmt        = "input" message_type resource_ref ;
+output_stmt       = "output" message_type resource_ref [ "{" contract_block "}" ] ;
+contract_block    = "contract" "{" "path" string_lit "name" string_lit
+                    [ "type" string_lit ] "}" ;
+
+(* Flow *)
+flow_decl         = "flow" identifier "{" common_props
+                    { flow_entry_chain | flow_when_block } "}" ;
+flow_entry_chain  = flow_ref { "," flow_ref } ( "->" flow_ref )+ ;
+flow_when_block   = "when" flow_ref { "and" flow_ref } flow_action+ ;
+flow_action       = flow_ref { flow_output } ;
+flow_output       = "->" [ string_lit ":" ] flow_ref ;
+flow_ref          = identifier [ string_lit ] ;
+
+(* Actor *)
+actor_decl        = "actor" identifier [ "{" { actor_body_item } "}" ] ;
+actor_body_item   = name_prop | summary_prop | annotation ;
+
+(* External System *)
+external_system_decl = "external-system" identifier [ "{" { ext_sys_body_item } "}" ] ;
+ext_sys_body_item    = name_prop | summary_prop | annotation ;
+
+(* Visualizer *)
+visualizer_decl   = "visualizer" identifier "{" { visualizer_body } "}" ;
+visualizer_body   = name_prop | summary_prop | annotation
+                  | legend_prop | search_prop | toolbar_prop
+                  | focus_mode_prop | animated_prop | style_prop
+                  | domain_decl | service_decl | event_decl | command_decl
+                  | query_decl | channel_decl | container_decl
+                  | data_product_decl | flow_decl
+                  | actor_decl | external_system_decl
+                  | service_ref_stmt | domain_ref_stmt
+                  | event_ref_stmt | command_ref_stmt | query_ref_stmt
+                  | channel_ref_stmt | data_product_ref_stmt | flow_ref_stmt
+                  | container_ref_stmt ;
+legend_prop       = "legend" bool_lit ;
+search_prop       = "search" bool_lit ;
+toolbar_prop      = "toolbar" bool_lit ;
+focus_mode_prop   = "focus-mode" bool_lit ;
+animated_prop     = "animated" bool_lit ;
+style_prop        = "style" ( "default" | "post-it" ) ;
+
+(* User *)
+user_decl         = "user" identifier "{" user_props "}" ;
+user_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit ;
+
+(* Team *)
+team_decl         = "team" identifier "{" team_props "}" ;
+team_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "summary" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit
+                  | "member" identifier ;
+
+(* Resource references *)
+versioned_resource_ref  = identifier "@" version_lit ;
+service_ref_stmt    = "service" resource_ref ;
+domain_ref_stmt     = "domain" resource_ref ;
+event_ref_stmt      = "event" versioned_resource_ref ;
+command_ref_stmt    = "command" versioned_resource_ref ;
+query_ref_stmt      = "query" versioned_resource_ref ;
+channel_ref_stmt    = "channel" resource_ref ;
+container_ref_stmt  = "container" resource_ref ;
+```
+
+## Reserved Keywords
+
+```
+domain     service     event       command      query
+channel    container   data-product flow
+user       team        sends       receives
+writes-to  reads-from  owns        to           from
+version    name        summary     owner        schema
+deprecated draft       true        false
+type       actor       external-system
+parameter  route       member
+input      output      contract
+subdomain  visualizer  legend      search       toolbar      focus-mode
+animated   style       when        and
+```
+
+## File Extension
+
+EventCatalog DSL files use the `.ec` extension:
+
+```
+catalog.ec
+orders-domain.ec
+payment-service.ec
+```
+
+Multiple `.ec` files can be used and are merged during compilation. Resources can reference each other across files.
+
+## Compilation
+
+The DSL compiles to EventCatalog's directory structure:
+
+```
+catalog.ec  -->  domains/Orders/index.mdx
+                    domains/Orders/services/OrderService/index.mdx
+                    events/OrderCreated/index.mdx
+                    commands/ProcessPayment/index.mdx
+                    channels/orders-topic/index.mdx
+                    users/dboyne.mdx
+                    teams/orders-team.mdx
+                    ...
+```
+
+Each resource becomes a markdown file with YAML frontmatter matching EventCatalog's content collection schemas.
+
+---
+
+# Visualizer
+
+The `visualizer` block separates **resource definition** from **visualization**. Resources defined outside a visualizer block exist in the catalog but are not rendered visually. Only resources placed inside a `visualizer` block (or referenced from one) appear in the visual graph.
+
+This separation lets teams maintain a single source of truth for all resources while controlling exactly what gets visualized and how.
+
+```
+visualizer <id> {
+  name "<display name>"
+  summary "<text>"
+
+  // Display options
+  legend true|false
+  search true|false
+  toolbar true|false
+  focus-mode true|false
+  animated true|false
+  style default|post-it
+
+  // Resources to visualize (inline or reference)
+  <resource definitions or references>
+}
+```
+
+## Why Visualizer Exists
+
+A `.ec` file can define dozens of resources — domains, services, events, channels, and more. Without a visualizer block, there is no way to control which resources appear in the visual graph or how they are presented.
+
+The visualizer block makes visualization **explicit**:
+
+- Define resources anywhere (top-level, imported files)
+- Choose what to visualize by placing resources inside a `visualizer` block
+- Configure display options per visualization
+
+## Multiple Visualizer Blocks
+
+A file can contain multiple `visualizer` blocks, each presenting a different view over the same resources. Tools (e.g. the playground) allow switching between them.
+
+```
+// Shared resources
+event OrderCreated {
+  version 1.0.0
+}
+
+event PaymentProcessed {
+  version 1.0.0
+}
+
+service OrderService {
+  version 1.0.0
+  sends event OrderCreated
+}
+
+service PaymentService {
+  version 1.0.0
+  receives event OrderCreated
+  sends event PaymentProcessed
+}
+
+// View 1: Order flow only
+visualizer orders {
+  name "Order Flow"
+
+  service OrderService
+  event OrderCreated
+}
+
+// View 2: Full payment pipeline
+visualizer payments {
+  name "Payment Pipeline"
+
+  service OrderService
+  service PaymentService
+  event OrderCreated
+  event PaymentProcessed
+}
+```
+
+## Resources Without a Visualizer
+
+Resources defined outside any `visualizer` block are valid. They can be:
+
+- Imported by other `.ec` files
+- Referenced from within a `visualizer` block
+- Used for compilation to EventCatalog's markdown format
+
+If a file contains no `visualizer` block, no visual graph is produced.
+
+## Inline vs. Reference
+
+Resources inside a visualizer can be defined inline (full definition) or referenced by name:
+
+**Inline** — defines and visualizes the resource:
+
+```
+visualizer main {
+  name "My Architecture"
+
+  service OrderService {
+    version 1.0.0
+    sends event OrderCreated
+  }
+}
+```
+
+**Reference** — visualizes a resource defined elsewhere:
+
+```
+service OrderService {
+  version 1.0.0
+  sends event OrderCreated
+}
+
+visualizer main {
+  name "My Architecture"
+  service OrderService
+}
+```
+
+When a resource is referenced, the visualizer enriches the node with metadata from the matching top-level definition.
+
+## Display Options
+
+| Property     | Type    | Default   | Description                            |
+| ------------ | ------- | --------- | -------------------------------------- |
+| `name`       | string  | —         | Display title for the visualization    |
+| `summary`    | string  | —         | Description of the visualization       |
+| `legend`     | boolean | `true`    | Show the node type legend              |
+| `search`     | boolean | `true`    | Show the search bar                    |
+| `toolbar`    | boolean | `true`    | Show the toolbar (export, zoom, etc.)  |
+| `focus-mode` | boolean | `true`    | Enable focus mode for individual nodes |
+| `animated`   | boolean | `true`    | Animate edges                          |
+| `style`      | enum    | `default` | Visual style: `default` or `post-it`   |
+
+## Example
+
+```
+// Teams
+team orders-team {
+  name "Orders Team"
+}
+
+// Resources
+channel orders-topic {
+  version 1.0.0
+  protocol "Kafka"
+}
+
+// Visualizer with display options
+visualizer order-architecture {
+  name "Order Architecture"
+  summary "Core order processing services"
+  legend true
+  search true
+  animated false
+  style post-it
+
+  domain Orders {
+    version 1.0.0
+    owner orders-team
+
+    service OrderService {
+      version 1.0.0
+      sends event OrderCreated to orders-topic
+      receives command CreateOrder
+    }
+
+    service NotificationService {
+      version 1.0.0
+      receives event OrderCreated
+    }
+  }
+}
+```
+
+## EBNF
+
+```ebnf
+visualizer_decl   = "visualizer" identifier "{" { visualizer_body } "}" ;
+visualizer_body   = name_prop | summary_prop | annotation
+                  | legend_prop | search_prop | toolbar_prop
+                  | focus_mode_prop | animated_prop | style_prop
+                  | domain_decl | service_decl | event_decl | command_decl
+                  | query_decl | channel_decl | container_decl
+                  | data_product_decl | flow_decl
+                  | actor_decl | external_system_decl
+                  | service_ref_stmt | domain_ref_stmt
+                  | event_ref_stmt | command_ref_stmt | query_ref_stmt
+                  | channel_ref_stmt | data_product_ref_stmt | flow_ref_stmt
+                  | container_ref_stmt ;
+legend_prop       = "legend" bool_lit ;
+search_prop       = "search" bool_lit ;
+toolbar_prop      = "toolbar" bool_lit ;
+focus_mode_prop   = "focus-mode" bool_lit ;
+animated_prop     = "animated" bool_lit ;
+style_prop        = "style" ( "default" | "post-it" ) ;
+```
+
+---
diff --git a/packages/language-server/docs/src/content/docs/resources/channels.mdx b/packages/language-server/docs/src/content/docs/resources/channels.mdx
new file mode 100644
index 000000000..84fad4818
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/resources/channels.mdx
@@ -0,0 +1,96 @@
+---
+title: Channels
+description: Model topics, queues, and other transport layers with channel resources.
+---
+
+`channel` models the transport path messages flow through (for example Kafka, MQTT, SQS, or HTTP streams).
+
+## Example
+
+This example defines a Kafka channel and shows a service sending an event through that channel.
+
+```ec title="main.ec"
+channel OrdersChannel {
+  version 1.0.0
+  name "Orders Channel"
+  summary "Carries order events"
+  protocol "Kafka"
+  address "orders.events.v1"
+  owner platform-team
+  route AnalyticsChannel@1.0.0
+}
+
+service OrdersService {
+  version 1.0.0
+  sends event OrderCreated@1.0.0 to OrdersChannel@1.0.0
+}
+```
+
+## Properties
+
+| Property     | Type      | Required        | Description                        | Example                        |
+| ------------ | --------- | --------------- | ---------------------------------- | ------------------------------ |
+| `version`    | semver    | Yes             | Resource version.                  | `1.0.0`                        |
+| `name`       | string    | No              | Display name (defaults to id).     | `"Orders Channel"`             |
+| `summary`    | string    | No              | Short description.                 | `"Carries order events"`       |
+| `owner`      | reference | No (repeatable) | Team/user owner reference.         | `owner platform-team`          |
+| `protocol`   | string    | No              | Transport technology/protocol.     | `"Kafka"`                      |
+| `address`    | string    | No              | Broker/topic/queue address.        | `"orders.events.v1"`           |
+| `route`      | reference | No (repeatable) | Route from one channel to another. | `route AnalyticsChannel@1.0.0` |
+| `parameter`  | block     | No (repeatable) | Dynamic address parameter.         | `parameter sensorId { ... }`   |
+| `draft`      | boolean   | No              | Marks resource as draft.           | `draft true`                   |
+| `deprecated` | boolean   | No              | Marks resource as deprecated.      | `deprecated true`              |
+
+## Channel parameters
+
+Use `parameter` to define dynamic segments in channel addresses:
+
+```ec title="main.ec"
+channel sensor-data {
+  version 1.0.0
+  address "sensors/{sensorId}/data"
+  protocol "MQTT"
+
+  parameter sensorId {
+    description "Unique sensor identifier"
+    default "sensor-001"
+    enum ["sensor-001", "sensor-042", "sensor-099"]
+    examples ["sensor-001", "sensor-042"]
+  }
+}
+```
+
+### Parameter properties
+
+| Property      | Type     | Required | Description                   | Example                        |
+| ------------- | -------- | -------- | ----------------------------- | ------------------------------ |
+| `description` | string   | No       | What the parameter represents | `"Unique sensor identifier"`   |
+| `default`     | string   | No       | Default value                 | `"sensor-001"`                 |
+| `enum`        | string[] | No       | Allowed values                | `["sensor-001", "sensor-042"]` |
+| `examples`    | string[] | No       | Example values                | `["sensor-001", "sensor-042"]` |
+
+## Channel routing
+
+Channels can route to other channels, modeling message pipelines:
+
+```ec title="main.ec"
+channel Ingestion {
+  version 1.0.0
+  protocol "Kafka"
+  route Filtered
+  route Archive
+}
+
+channel Filtered {
+  version 1.0.0
+  protocol "Kafka"
+  route Analytics
+}
+```
+
+## Used by services
+
+| Usage                  | Example                                                      |
+| ---------------------- | ------------------------------------------------------------ |
+| Send through a channel | `sends event OrderCreated to OrdersChannel@1.0.0`            |
+| Receive from a channel | `receives event PaymentProcessed from PaymentsChannel@1.0.0` |
diff --git a/packages/language-server/docs/src/content/docs/resources/data-products.mdx b/packages/language-server/docs/src/content/docs/resources/data-products.mdx
new file mode 100644
index 000000000..4a86ebdf0
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/resources/data-products.mdx
@@ -0,0 +1,46 @@
+---
+title: Data Products
+description: Model analytical and curated data outputs with data-product resources.
+---
+
+`data-product` models a governed, consumable data output and its lineage.
+
+## Example
+
+This example defines a data product with upstream input events and an output event that includes a contract.
+
+```ec title="main.ec"
+data-product CommerceInsights {
+  version 1.0.0
+  name "Commerce Insights"
+  summary "Curated commerce analytics"
+  owner data-platform-team
+
+  input event OrderCreated@1.0.0
+  input event PaymentProcessed@1.0.0
+
+  output event RevenueMetrics {
+    contract {
+      path "./schemas/revenue-metrics.json"
+      name "RevenueMetricsSchema"
+      type "json-schema"
+    }
+  }
+}
+```
+
+## Properties
+
+| Property        | Type      | Required        | Description                         | Example                            |
+| --------------- | --------- | --------------- | ----------------------------------- | ---------------------------------- |
+| `version`       | semver    | Yes             | Resource version.                   | `1.0.0`                            |
+| `name`          | string    | No              | Display name (defaults to id).      | `"Commerce Insights"`              |
+| `summary`       | string    | No              | Short description.                  | `"Curated commerce analytics"`     |
+| `owner`         | reference | No (repeatable) | Team/user owner reference.          | `owner data-platform-team`         |
+| `input`         | statement | No (repeatable) | Upstream message sources.           | `input event OrderCreated@1.0.0`   |
+| `output`        | statement | No (repeatable) | Data outputs as message references. | `output event RevenueMetrics`      |
+| `contract.path` | string    | No              | Contract/schema file path.          | `"./schemas/revenue-metrics.json"` |
+| `contract.name` | string    | No              | Contract name.                      | `"RevenueMetricsSchema"`           |
+| `contract.type` | string    | No              | Contract type.                      | `"json-schema"`                    |
+| `draft`         | boolean   | No              | Marks resource as draft.            | `draft true`                       |
+| `deprecated`    | boolean   | No              | Marks resource as deprecated.       | `deprecated true`                  |
diff --git a/packages/language-server/docs/src/content/docs/resources/databases.mdx b/packages/language-server/docs/src/content/docs/resources/databases.mdx
new file mode 100644
index 000000000..ad7881b4a
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/resources/databases.mdx
@@ -0,0 +1,99 @@
+---
+title: Containers
+description: Model databases, caches, and data stores with container resources.
+---
+
+`container` models a data store, cache, or external system that services read from or write to.
+
+## Example
+
+This example models a database container and shows a service writing to and reading from it.
+
+```ec title="main.ec"
+container orders-db {
+  version 1.0.0
+  name "Orders DB"
+  summary "Primary transactional store"
+  container-type database
+  technology "PostgreSQL 15"
+  access-mode readWrite
+  classification internal
+  residency "eu-west-1"
+  retention "7y"
+}
+
+service OrdersService {
+  version 1.0.0
+  writes-to container orders-db@1.0.0
+  reads-from container orders-db@1.0.0
+}
+```
+
+## Properties
+
+| Property         | Type      | Required        | Description                                                  | Example                         |
+| ---------------- | --------- | --------------- | ------------------------------------------------------------ | ------------------------------- |
+| `version`        | semver    | Yes             | Resource version.                                            | `1.0.0`                         |
+| `name`           | string    | No              | Display name (defaults to id).                               | `"Orders DB"`                   |
+| `summary`        | string    | No              | Short description.                                           | `"Primary transactional store"` |
+| `container-type` | enum      | Yes             | Container category (see types below).                        | `database`                      |
+| `technology`     | string    | No              | Implementation detail/version.                               | `"PostgreSQL 15"`               |
+| `authoritative`  | boolean   | No              | Whether it is source of truth.                               | `authoritative true`            |
+| `access-mode`    | enum      | No              | Access pattern (`read`, `write`, `readWrite`, `appendOnly`). | `readWrite`                     |
+| `classification` | enum      | No              | Data sensitivity class.                                      | `internal`                      |
+| `residency`      | string    | No              | Data residency/region.                                       | `"eu-west-1"`                   |
+| `retention`      | string    | No              | Retention policy/duration.                                   | `"7y"`                          |
+| `owner`          | reference | No (repeatable) | Team/user owner reference.                                   | `owner data-team`               |
+| `service`        | reference | No (repeatable) | Service references to this container.                        | `service OrdersService@1.0.0`   |
+| `draft`          | boolean   | No              | Marks resource as draft.                                     | `draft true`                    |
+| `deprecated`     | boolean   | No              | Marks resource as deprecated.                                | `deprecated true`               |
+
+## Container types
+
+| Type            | Use for                          |
+| --------------- | -------------------------------- |
+| `database`      | Relational or document databases |
+| `cache`         | Redis, Memcached, etc.           |
+| `objectStore`   | S3, GCS, Azure Blob              |
+| `searchIndex`   | Elasticsearch, OpenSearch        |
+| `dataWarehouse` | BigQuery, Snowflake, Redshift    |
+| `dataLake`      | Delta Lake, Iceberg              |
+| `externalSaaS`  | Third-party managed services     |
+| `other`         | Anything that doesn't fit above  |
+
+## Examples by type
+
+```ec title="main.ec"
+container orders-db {
+  version 1.0.0
+  container-type database
+  technology "PostgreSQL 15"
+}
+
+container session-cache {
+  version 1.0.0
+  container-type cache
+  technology "Redis 7"
+  retention "24h"
+}
+
+container assets-bucket {
+  version 1.0.0
+  container-type objectStore
+  technology "AWS S3"
+  classification internal
+}
+
+container product-search {
+  version 1.0.0
+  container-type searchIndex
+  technology "Elasticsearch 8"
+}
+```
+
+## Used by services
+
+| Usage                 | Example                                |
+| --------------------- | -------------------------------------- |
+| Write to a container  | `writes-to container orders-db@1.0.0`  |
+| Read from a container | `reads-from container orders-db@1.0.0` |
diff --git a/packages/language-server/docs/src/content/docs/resources/domains.mdx b/packages/language-server/docs/src/content/docs/resources/domains.mdx
new file mode 100644
index 000000000..8e071b9a6
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/resources/domains.mdx
@@ -0,0 +1,49 @@
+---
+title: Domains
+description: Model bounded contexts and ownership boundaries with domains.
+---
+
+`domain` models a bounded context and groups related resources.
+
+## Example
+
+This example models a `Commerce` domain with an inline service and a nested `Payments` subdomain.
+
+```ec title="main.ec"
+domain Commerce {
+  version 1.0.0
+  name "Commerce Domain"
+  summary "Order and payment capabilities"
+  owner commerce-team
+
+  service OrdersService {
+    version 1.0.0
+    sends event OrderCreated@1.0.0
+  }
+
+  subdomain Payments {
+    version 1.0.0
+    service PaymentService {
+      version 1.0.0
+      receives event OrderCreated@1.0.0
+    }
+  }
+}
+```
+
+## Properties
+
+| Property       | Type             | Required        | Description                               | Example                               |
+| -------------- | ---------------- | --------------- | ----------------------------------------- | ------------------------------------- |
+| `version`      | semver           | Yes             | Resource version.                         | `1.0.0`                               |
+| `name`         | string           | No              | Display name (defaults to id).            | `"Commerce Domain"`                   |
+| `summary`      | string           | No              | Short description.                        | `"Order and payment capabilities"`    |
+| `owner`        | reference        | No (repeatable) | Team/user owner reference.                | `owner commerce-team`                 |
+| `service`      | reference/inline | No (repeatable) | Include or define services in the domain. | `service OrdersService@1.0.0`         |
+| `subdomain`    | reference/inline | No (repeatable) | Include or define subdomains.             | `subdomain Payments { ... }`          |
+| `data-product` | reference        | No (repeatable) | Related data products.                    | `data-product CommerceInsights@1.0.0` |
+| `flow`         | reference        | No (repeatable) | Related flows.                            | `flow OrderFulfillment@1.0.0`         |
+| `sends`        | statement        | No (repeatable) | Domain-level produced messages.           | `sends event OrderCreated`            |
+| `receives`     | statement        | No (repeatable) | Domain-level consumed messages.           | `receives event PaymentProcessed`     |
+| `draft`        | boolean          | No              | Marks resource as draft.                  | `draft true`                          |
+| `deprecated`   | boolean          | No              | Marks resource as deprecated.             | `deprecated true`                     |
diff --git a/packages/language-server/docs/src/content/docs/resources/flows.mdx b/packages/language-server/docs/src/content/docs/resources/flows.mdx
new file mode 100644
index 000000000..a8d2264e4
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/resources/flows.mdx
@@ -0,0 +1,186 @@
+---
+title: Flows
+description: Model step-by-step business processes with flow resources.
+---
+
+`flow` models a business process as a sequence of steps, triggers, and reactions. Flows read like a narrative of what happens in your system.
+
+## Example
+
+This example models an order fulfillment flow from placement through to shipping.
+
+```ec title="main.ec"
+flow OrderFulfillment {
+  version 1.0.0
+  name "Order Fulfillment"
+  summary "End-to-end order processing from placement to delivery"
+  owner fulfillment-team
+
+  Customer "places an order"
+    -> PlaceOrder
+    -> OrderService "creates the order"
+    -> OrderCreated
+
+  when OrderCreated
+    PaymentService "processes the payment"
+      -> "success": PaymentProcessed
+      -> "failure": PaymentFailed
+    InventoryService "reserves stock"
+      -> StockReserved
+
+  when PaymentFailed
+    NotificationService "notifies the customer of failure"
+
+  when PaymentProcessed and StockReserved
+    FulfillmentService "ships the order"
+      -> OrderShipped
+
+  when OrderShipped
+    WarehouseWMS "syncs with legacy WMS"
+    NotificationService "notifies the customer"
+      -> CustomerNotified
+}
+```
+
+## Properties
+
+| Property     | Type      | Required        | Description                    | Example                         |
+| ------------ | --------- | --------------- | ------------------------------ | ------------------------------- |
+| `version`    | semver    | Yes             | Resource version.              | `1.0.0`                         |
+| `name`       | string    | No              | Display name (defaults to id). | `"Order Fulfillment"`           |
+| `summary`    | string    | No              | Short description.             | `"End-to-end order processing"` |
+| `owner`      | reference | No (repeatable) | Team/user owner reference.     | `owner fulfillment-team`        |
+| `draft`      | boolean   | No              | Marks resource as draft.       | `draft true`                    |
+| `deprecated` | boolean   | No              | Marks resource as deprecated.  | `deprecated true`               |
+
+## Entry chains
+
+The entry chain defines the starting sequence of a flow using arrow (`->`) syntax. This is where the process begins.
+
+```ec title="main.ec"
+flow CheckoutFlow {
+  version 1.0.0
+
+  Customer "places an order"
+    -> PlaceOrder
+    -> OrderService "creates the order"
+    -> OrderCreated
+}
+```
+
+Multiple sources can converge into a single chain:
+
+```ec title="main.ec"
+flow MergeFlow {
+  version 1.0.0
+
+  WebOrder, MobileOrder -> OrderService "processes the order"
+    -> OrderCreated
+}
+```
+
+## When blocks
+
+`when` blocks define what happens in reaction to an event. Each block starts with a trigger, followed by one or more actions.
+
+```ec title="main.ec"
+flow PaymentFlow {
+  version 1.0.0
+
+  OrderService "creates order" -> OrderCreated
+
+  when OrderCreated
+    PaymentService "processes the payment"
+      -> "success": PaymentProcessed
+      -> "failure": PaymentFailed
+}
+```
+
+### Labeled outputs
+
+Action outputs can have labels to describe the outcome:
+
+```ec
+-> "success": PaymentProcessed    // labeled output
+-> StockReserved                   // unlabeled output
+```
+
+### Convergence
+
+Use `and` to require multiple triggers before actions execute:
+
+```ec
+when PaymentProcessed and StockReserved
+  FulfillmentService "ships the order"
+    -> OrderShipped
+```
+
+### Terminal actions
+
+Actions without outputs are terminal steps in the flow:
+
+```ec
+when OrderShipped
+  WarehouseWMS "syncs with legacy WMS"
+  NotificationService "notifies the customer"
+```
+
+## Actors and external systems
+
+Use `actor` and `external-system` to represent people and third-party systems in your flows. Define them as top-level resources alongside your flow.
+
+```ec title="main.ec"
+actor Customer {
+  name "Customer"
+  summary "End user on the storefront"
+}
+
+external-system WarehouseWMS {
+  name "Warehouse WMS"
+  summary "Legacy warehouse management system"
+}
+
+flow OrderFulfillment {
+  version 1.0.0
+
+  Customer "places an order"
+    -> PlaceOrder
+    -> OrderService "creates the order"
+    -> OrderCreated
+
+  when OrderShipped
+    WarehouseWMS "syncs with legacy WMS"
+}
+```
+
+Actors and external systems can also be bare (no body):
+
+```ec
+actor Customer
+external-system WarehouseWMS
+```
+
+## Flow references
+
+Resources in flows are referenced by name only. You don't need type keywords like `service` or `event`. Types are resolved automatically from other definitions in your `.ec` files or catalog.
+
+Each reference can include an optional label:
+
+| Reference                                | Description              |
+| ---------------------------------------- | ------------------------ |
+| `Customer "places an order"`             | Name with display label  |
+| `PlaceOrder`                             | Bare name (no label)     |
+| `PaymentService "processes the payment"` | Service with description |
+
+If no matching definition is found for a reference, it defaults to a `step` type.
+
+## Referencing flows from services
+
+Services can reference related flows:
+
+```ec
+service OrderService {
+  version 1.0.0
+  flow OrderFulfillment@1.0.0
+}
+```
diff --git a/packages/language-server/docs/src/content/docs/resources/messages.mdx b/packages/language-server/docs/src/content/docs/resources/messages.mdx
new file mode 100644
index 000000000..6f654c56c
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/resources/messages.mdx
@@ -0,0 +1,56 @@
+---
+title: Messages
+description: Model events, commands, and queries in EventCatalog Compass.
+---
+
+Messages are facts, intents, or requests that move between services.
+
+- `event`: something that happened
+- `command`: a request to do something
+- `query`: a request for information
+
+## Example
+
+This example shows the three message types: one `event`, one `command`, and one `query`.
+
+```ec title="main.ec"
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "Raised when an order is created"
+  schema "./schemas/order-created.json"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+  summary "Requests order creation"
+}
+
+query GetOrderById {
+  version 1.0.0
+  name "Get Order By ID"
+  summary "Returns one order"
+}
+```
+
+## Common properties
+
+| Property     | Type      | Required        | Description                    | Example                             |
+| ------------ | --------- | --------------- | ------------------------------ | ----------------------------------- |
+| `version`    | semver    | Yes             | Resource version.              | `1.0.0`                             |
+| `name`       | string    | No              | Display name (defaults to id). | `"Order Created"`                   |
+| `summary`    | string    | No              | Short description.             | `"Raised when an order is created"` |
+| `owner`      | reference | No (repeatable) | Team/user owner reference.     | `owner orders-team`                 |
+| `schema`     | string    | No              | Contract/schema location.      | `"./schemas/order-created.json"`    |
+| `draft`      | boolean   | No              | Marks resource as draft.       | `draft true`                        |
+| `deprecated` | boolean   | No              | Marks resource as deprecated.  | `deprecated true`                   |
+
+## Usage in services
+
+| Usage             | Example                                         |
+| ----------------- | ----------------------------------------------- |
+| Produce an event  | `sends event OrderCreated@1.0.0`                |
+| Consume a command | `receives command CreateOrder@1.0.0`            |
+| Consume a query   | `receives query GetOrderById@1.0.0`             |
+| Route via channel | `sends event OrderCreated to OrdersTopic@1.0.0` |
diff --git a/packages/language-server/docs/src/content/docs/resources/services.mdx b/packages/language-server/docs/src/content/docs/resources/services.mdx
new file mode 100644
index 000000000..fbaa755de
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/resources/services.mdx
@@ -0,0 +1,42 @@
+---
+title: Services
+description: Model application and runtime capabilities with service resources.
+---
+
+`service` models a runtime capability in your system (for example an API, worker, or microservice).
+
+## Example
+
+This example defines one service that sends and receives messages and reads from and writes to a database container.
+
+```ec title="main.ec"
+service OrdersService {
+  version 1.0.0
+  name "Orders Service"
+  summary "Handles order lifecycle"
+  owner orders-team
+
+  sends event OrderCreated@1.0.0 to OrdersEvents@1.0.0
+  receives command CreateOrder@1.0.0
+  receives query GetOrderById@1.0.0
+
+  writes-to container orders-db@1.0.0
+  reads-from container orders-db@1.0.0
+}
+```
+
+## Properties
+
+| Property     | Type      | Required        | Description                         | Example                          |
+| ------------ | --------- | --------------- | ----------------------------------- | -------------------------------- |
+| `version`    | semver    | Yes             | Resource version.                   | `1.0.0`                          |
+| `name`       | string    | No              | Display name (defaults to id).      | `"Orders Service"`               |
+| `summary`    | string    | No              | Short description.                  | `"Handles order lifecycle"`      |
+| `owner`      | reference | No (repeatable) | Team/user owner reference.          | `owner orders-team`              |
+| `sends`      | statement | No (repeatable) | Messages produced by the service.   | `sends event OrderCreated`       |
+| `receives`   | statement | No (repeatable) | Messages consumed by the service.   | `receives command CreateOrder`   |
+| `writes-to`  | statement | No (repeatable) | Containers written by this service. | `writes-to container orders-db`  |
+| `reads-from` | statement | No (repeatable) | Containers read by this service.    | `reads-from container orders-db` |
+| `flow`       | reference | No (repeatable) | Related flow references.            | `flow OrderFulfillment@1.0.0`    |
+| `draft`      | boolean   | No              | Marks resource as draft.            | `draft true`                     |
+| `deprecated` | boolean   | No              | Marks resource as deprecated.       | `deprecated true`                |
diff --git a/packages/language-server/docs/src/content/docs/resources/teams-and-users.mdx b/packages/language-server/docs/src/content/docs/resources/teams-and-users.mdx
new file mode 100644
index 000000000..49b1d5ed0
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/resources/teams-and-users.mdx
@@ -0,0 +1,68 @@
+---
+title: Teams and Users
+description: Define ownership and people metadata with team and user resources.
+---
+
+Use `team` and `user` to model ownership and contributor context in your catalog.
+
+## Example
+
+This example defines a user, a team with a member, and then assigns the team as the owner of a service.
+
+```ec title="main.ec"
+user dboyne {
+  name "David Boyne"
+  role "Principal Engineer"
+  email "david@company.com"
+  slack "https://company.slack.com/team/U12345"
+}
+
+team platform-team {
+  name "Platform Team"
+  summary "Owns platform-level architecture and standards"
+  email "platform@company.com"
+  slack "https://company.slack.com/channels/platform-team"
+  member dboyne
+}
+
+service OrdersService {
+  version 1.0.0
+  owner platform-team
+}
+```
+
+## `user` properties
+
+| Property   | Type   | Required | Description                | Example                                   |
+| ---------- | ------ | -------- | -------------------------- | ----------------------------------------- |
+| `name`     | string | No       | Display name.              | `"David Boyne"`                           |
+| `avatar`   | string | No       | Avatar/image URL.          | `"https://example.com/avatar.png"`        |
+| `role`     | string | No       | Job role/title.            | `"Principal Engineer"`                    |
+| `email`    | string | No       | Contact email.             | `"david@company.com"`                     |
+| `slack`    | string | No       | Slack profile/message URL. | `"https://company.slack.com/team/U12345"` |
+| `ms-teams` | string | No       | Microsoft Teams URL.       | `"https://teams.microsoft.com/..."`       |
+
+## `team` properties
+
+| Property   | Type    | Required        | Description                | Example                                              |
+| ---------- | ------- | --------------- | -------------------------- | ---------------------------------------------------- |
+| `name`     | string  | No              | Display name.              | `"Platform Team"`                                    |
+| `avatar`   | string  | No              | Avatar/image URL.          | `"https://example.com/platform-team.png"`            |
+| `role`     | string  | No              | Team role/function.        | `"Architecture"`                                     |
+| `summary`  | string  | No              | Short description.         | `"Owns platform standards"`                          |
+| `email`    | string  | No              | Team contact email.        | `"platform@company.com"`                             |
+| `slack`    | string  | No              | Team Slack URL.            | `"https://company.slack.com/channels/platform-team"` |
+| `ms-teams` | string  | No              | Team Microsoft Teams URL.  | `"https://teams.microsoft.com/..."`                  |
+| `member`   | user id | No (repeatable) | User membership reference. | `member dboyne`                                      |
+
+## Referencing ownership
+
+Any resource can reference team/user ownership:
+
+```ec
+service OrdersService {
+  version 1.0.0
+  owner platform-team
+  owner dboyne
+}
+```
diff --git a/packages/language-server/docs/src/content/docs/tooling/cli.mdx b/packages/language-server/docs/src/content/docs/tooling/cli.mdx
new file mode 100644
index 000000000..c11500d39
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/tooling/cli.mdx
@@ -0,0 +1,85 @@
+---
+title: CLI
+description: Use the EventCatalog CLI to import and export .ec files.
+---
+
+The EventCatalog CLI connects your `.ec` files to your EventCatalog. Import models into your catalog, export existing resources to `.ec` files, and automate workflows in CI/CD.
+
+## Install
+
+The CLI runs via `npx` with no install required:
+
+```bash
+npx @eventcatalog/cli --help
+```
+
+## Command pattern
+
+```bash
+npx @eventcatalog/cli --dir <catalog-path> <command> [options]
+```
+
+The `--dir` flag points to your EventCatalog directory.
+
+## Import .ec files into EventCatalog
+
+Take your `.ec` models and create or update resources in your catalog:
+
+```bash
+# Import a single file
+npx @eventcatalog/cli --dir ./catalog import ./main.ec
+
+# Import multiple files
+npx @eventcatalog/cli --dir ./catalog import ./core.ec ./payments.ec
+
+# Preview changes without writing
+npx @eventcatalog/cli --dir ./catalog import ./main.ec --dry-run
+
+# Read from stdin
+cat ./main.ec | npx @eventcatalog/cli --dir ./catalog import --stdin
+```
+
+### Import flags
+
+| Flag        | What it does                                             |
+| ----------- | -------------------------------------------------------- |
+| `--dry-run` | Preview creates, updates, and versioning without writing |
+| `--flat`    | Write resources in top-level folders instead of nesting  |
+| `--no-init` | Skip initialization prompts (useful in CI/CD)            |
+
+## Export EventCatalog to .ec files
+
+Pull existing resources out of your catalog as `.ec` files:
+
+```bash
+# Export everything
+npx @eventcatalog/cli --dir ./catalog export --all --stdout
+
+# Export one resource type
+npx @eventcatalog/cli --dir ./catalog export --resource service --stdout
+
+# Export a specific resource
+npx @eventcatalog/cli --dir ./catalog export --resource event --id OrderCreated --version 1.0.0 --stdout
+```
+
+### Export flags
+
+| Flag               | What it does                                    |
+| ------------------ | ----------------------------------------------- |
+| `--all`            | Export every resource in the catalog             |
+| `--resource <type>`| Filter by resource type (service, event, etc.)   |
+| `--id <name>`      | Export a specific resource by ID                 |
+| `--version <ver>`  | Target a specific version                        |
+| `--hydrate`        | Include referenced resources in output           |
+| `--output <path>`  | Write to a file instead of stdout                |
+| `--playground`     | Open exported DSL in EventCatalog Compass        |
+
+## CI/CD usage
+
+Run imports in your pipeline to keep documentation in sync with `.ec` file changes:
+
+```bash
+npx @eventcatalog/cli --dir ./catalog import ./main.ec --no-init
+```
+
+Use `--no-init` to skip interactive prompts in automated environments.
diff --git a/packages/language-server/docs/src/content/docs/tooling/editors.mdx b/packages/language-server/docs/src/content/docs/tooling/editors.mdx
new file mode 100644
index 000000000..40ad9808d
--- /dev/null
+++ b/packages/language-server/docs/src/content/docs/tooling/editors.mdx
@@ -0,0 +1,35 @@
+---
+title: Editors (IDE)
+description: Get syntax highlighting, autocompletion, live preview, and diagnostics for .ec files in VS Code.
+---
+
+## VS Code extension
+
+The **EventCatalog DSL** extension gives you a full editing experience for `.ec` files inside VS Code.
+
+### Features
+
+| Feature              | What it does                                                        |
+| -------------------- | ------------------------------------------------------------------- |
+| Syntax highlighting  | Keywords, strings, annotations, and comments are color-coded        |
+| Autocompletion       | Suggests resource types, properties, and imported names as you type |
+| Live preview         | Opens an interactive architecture diagram alongside your `.ec` file |
+| Diagnostics          | Underlines errors and warnings as you edit                          |
+| Go to definition     | Jump to where a resource is defined                                 |
+| Hover information    | See resource details on hover                                       |
+
+### Install
+
+[Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=EventCatalog.eventcatalog-dsl), search for **EventCatalog DSL** in the VS Code extensions panel, or install from the command line:
+
+```bash
+code --install-extension eventcatalog.eventcatalog-dsl
+```
+
+### Live preview
+
+Open any `.ec` file and click the preview icon in the editor title bar (or run **EventCatalog: Open Preview** from the command palette). A side panel renders your architecture diagram in real time as you type.
+
+### File association
+
+The extension automatically activates for any file with the `.ec` extension. No additional configuration is needed.
diff --git a/packages/language-server/docs/tsconfig.json b/packages/language-server/docs/tsconfig.json
new file mode 100644
index 000000000..bcbf8b509
--- /dev/null
+++ b/packages/language-server/docs/tsconfig.json
@@ -0,0 +1,3 @@
+{
+  "extends": "astro/tsconfigs/strict"
+}
diff --git a/packages/language-server/langium-config.json b/packages/language-server/langium-config.json
new file mode 100644
index 000000000..44c627be5
--- /dev/null
+++ b/packages/language-server/langium-config.json
@@ -0,0 +1,14 @@
+{
+  "projectName": "Ec",
+  "languages": [
+    {
+      "id": "ec",
+      "grammar": "src/ec.langium",
+      "fileExtensions": [".ec"],
+      "textMate": {
+        "out": "syntaxes/ec.tmLanguage.json"
+      }
+    }
+  ],
+  "out": "src/generated"
+}
diff --git a/packages/language-server/package.json b/packages/language-server/package.json
new file mode 100644
index 000000000..b3478e0ff
--- /dev/null
+++ b/packages/language-server/package.json
@@ -0,0 +1,69 @@
+{
+  "name": "@eventcatalog/language-server",
+  "version": "0.8.23",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
+    "./language-server": {
+      "import": "./dist/main.js"
+    }
+  },
+  "files": [
+    "dist",
+    "syntaxes",
+    "specification",
+    "SPEC.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/event-catalog/eventcatalog",
+    "directory": "packages/language-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "generate": "langium generate",
+    "build": "tsc",
+    "build:bin": "langium generate && tsc",
+    "docs:dev": "astro dev --root docs",
+    "docs:build": "astro build --root docs",
+    "docs:preview": "astro preview --root docs",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:ci": "vitest run",
+    "spec": "bash specification/build-spec.sh",
+    "format": "prettier --write .",
+    "format:diff": "prettier --check ."
+  },
+  "dependencies": {
+    "@eventcatalog/sdk": "workspace:*",
+    "js-yaml": "^4.1.1",
+    "langium": "^3.3.1",
+    "semver": "^7.7.4",
+    "vscode-languageclient": "^9.0.1",
+    "vscode-languageserver": "^9.0.1",
+    "vscode-languageserver-textdocument": "^1.0.12",
+    "vscode-uri": "^3.0.8"
+  },
+  "devDependencies": {
+    "@astrojs/starlight": "^0.38.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/semver": "^7.7.1",
+    "astro": "^6.0.2",
+    "langium-cli": "^3.3.1",
+    "prettier": "^3.2.5",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}
diff --git a/packages/language-server/specification/00-overview.md b/packages/language-server/specification/00-overview.md
new file mode 100644
index 000000000..d2ee86a6e
--- /dev/null
+++ b/packages/language-server/specification/00-overview.md
@@ -0,0 +1,99 @@
+# Overview
+
+The EventCatalog DSL (ECDSL) is a human-readable, declarative language for defining event-driven architectures. It compiles to EventCatalog's frontmatter/markdown format, enabling teams to define domains, services, messages, channels, and their relationships in a single coherent source.
+
+```
+domain Payment {
+  version 1.0.0
+  owner payment-team
+
+  service PaymentService {
+    version 1.0.0
+
+    sends event PaymentProcessed {
+      version 1.0.0
+      summary "Emitted when a payment completes successfully"
+    }
+
+    receives command ProcessPayment
+    receives event OrderCreated
+  }
+}
+```
+
+## Design Principles
+
+1. **Readable** — Reads like English; minimal punctuation
+2. **Hierarchical** — Nesting reflects domain ownership and relationships
+3. **Concise** — Sane defaults; only specify what you need
+4. **Complete** — Can express everything EventCatalog supports
+5. **Composable** — Resources can be defined inline or referenced by ID
+
+## Lexical Structure
+
+### Comments
+
+```
+// Single-line comment
+
+/* Multi-line
+   comment */
+```
+
+### Strings
+
+```
+"double-quoted string"
+```
+
+Strings are required for values containing spaces, special characters, or multi-word text. Bare identifiers (no spaces, alphanumeric + hyphens + dots) can be unquoted. Strings follow JSON-style escaping (`\"`, `\\`, `\n`, etc.); raw `"` inside a string is not allowed.
+
+### Identifiers
+
+Identifiers are bare words used for resource IDs and type names. Keywords are reserved and cannot be used as identifiers.
+
+```
+OrderCreated          // simple
+Payment.OrderCreated  // namespaced
+my-service-name       // kebab-case
+```
+
+### Version Literals
+
+Semantic versions are bare (unquoted):
+
+```
+version 1.0.0
+version 2.1.0-beta.1
+```
+
+### Blocks
+
+Curly braces delimit blocks. Properties inside blocks are newline-separated (no commas).
+
+```
+resource Foo {
+  property value
+  property "value with spaces"
+}
+```
+
+### Property Multiplicity
+
+The grammar allows any property to appear multiple times inside a block. The semantic rules are:
+
+**Single-value properties** — if repeated, the last occurrence wins:
+
+`version`, `name`, `summary`, `address`, `protocol`, `deprecated`, `draft`, `container-type`, `technology`, `authoritative`, `access-mode`, `classification`, `residency`, `retention`
+
+`schema` is also single-value but only valid on messages (`event`, `command`, `query`, and inline message definitions).
+
+**Repeatable properties** — each occurrence appends a value:
+
+`owner`, `sends`, `receives`, `writes-to`, `reads-from`, `flow`, `service` (ref), `subdomain`, `data-product`, `route`, `input`, `output`, `member`, `parameter`
+
+`parameter` names must be unique within a channel; duplicate names are an error.
+
+Annotations are repeatable by default (see Metadata & Annotations).
+
+Unknown properties are parse errors — only the properties listed in each resource's grammar are valid. Duplicate single-value properties are syntactically valid (last wins) but tooling may warn.
diff --git a/packages/language-server/specification/01-domain.md b/packages/language-server/specification/01-domain.md
new file mode 100644
index 000000000..d76b87b2a
--- /dev/null
+++ b/packages/language-server/specification/01-domain.md
@@ -0,0 +1,80 @@
+# Domain
+
+Top-level bounded context. Can contain services, subdomains, data products, and flows.
+
+```
+domain <id> {
+  // Required
+  version <semver>
+  name "<display name>"          // optional, defaults to id
+
+  // Optional metadata
+  summary "<text>"
+  owner <owner-ref>              // repeatable
+  deprecated true
+  draft true
+
+  // Relationships
+  service <service-ref>          // repeatable (reference to external service)
+  subdomain <domain-ref>         // repeatable
+  data-product <dp-ref>          // repeatable
+  flow <flow-ref>                // repeatable
+
+  // Domain-level message routing
+  sends <message-type> <id> [to <channel-ref>]
+  receives <message-type> <id> [from <channel-ref>]
+
+  // Inline definitions
+  service <id> { ... }
+  subdomain <id> { ... }
+
+  // Annotations (see Metadata section)
+  @badge(...)
+  @repository(...)
+}
+```
+
+## Subdomains
+
+Domains can contain nested subdomains:
+
+```
+domain Logistics {
+  version 1.0.0
+
+  subdomain Shipping {
+    version 1.0.0
+    summary "Package shipping and tracking"
+
+    service ShippingService {
+      version 1.0.0
+      receives event OrderCreated
+      sends event ShipmentCreated
+    }
+  }
+
+  subdomain Returns {
+    version 1.0.0
+    summary "Return merchandise authorization"
+
+    service ReturnsService {
+      version 1.0.0
+      receives command InitiateReturn
+      sends event ReturnApproved
+    }
+  }
+}
+```
+
+## EBNF
+
+```ebnf
+domain_decl      = "domain" identifier "{" common_props
+                   { domain_body_item } "}" ;
+domain_body_item = service_decl | subdomain_decl | service_ref_stmt
+                 | data_product_ref_stmt | flow_ref_stmt
+                 | sends_stmt | receives_stmt
+                 | annotation ;
+subdomain_decl   = "subdomain" identifier "{" common_props
+                   { domain_body_item } "}" ;
+```
diff --git a/packages/language-server/specification/02-service.md b/packages/language-server/specification/02-service.md
new file mode 100644
index 000000000..91bc6b88b
--- /dev/null
+++ b/packages/language-server/specification/02-service.md
@@ -0,0 +1,50 @@
+# Service
+
+A microservice or application.
+
+```
+service <id> {
+  // Required
+  version <semver>
+  name "<display name>"
+
+  // Optional metadata
+  summary "<text>"
+  owner <owner-ref>              // repeatable
+  deprecated true
+  draft true
+
+  // Message relationships
+  sends <message-type> <id>[@<version>] [to <channel-list>]
+  receives <message-type> <id>[@<version>] [from <channel-list>]
+
+  // Data relationships
+  writes-to container <container-ref>      // repeatable
+  reads-from container <container-ref>     // repeatable
+
+  // Flow relationships
+  flow <flow-ref>                // repeatable
+
+  // Inline message definitions
+  sends event <id> { ... }
+  sends command <id> { ... }
+  receives query <id> { ... }
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+**Message types:** `event`, `command`, `query`
+
+## EBNF
+
+```ebnf
+service_decl     = "service" identifier "{" common_props
+                   { service_body_item } "}" ;
+service_body_item= sends_stmt | receives_stmt
+                 | writes_to_stmt | reads_from_stmt
+                 | flow_ref_stmt
+                 | annotation ;
+```
diff --git a/packages/language-server/specification/03-event.md b/packages/language-server/specification/03-event.md
new file mode 100644
index 000000000..f35dd05f2
--- /dev/null
+++ b/packages/language-server/specification/03-event.md
@@ -0,0 +1,29 @@
+# Event
+
+A domain event — something that happened.
+
+```
+event <id> {
+  // Required
+  version <semver>
+  name "<display name>"
+
+  // Optional metadata
+  summary "<text>"
+  owner <owner-ref>
+  schema "<path>"
+  deprecated true
+  draft true
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+  @api(method: "...", path: "...", statusCodes: "...")
+}
+```
+
+## EBNF
+
+```ebnf
+event_decl       = "event" identifier "{" message_props "}" ;
+```
diff --git a/packages/language-server/specification/04-command.md b/packages/language-server/specification/04-command.md
new file mode 100644
index 000000000..33d07112b
--- /dev/null
+++ b/packages/language-server/specification/04-command.md
@@ -0,0 +1,28 @@
+# Command
+
+An instruction to perform an action.
+
+```
+command <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+  schema "<path>"
+  deprecated true
+  draft true
+
+  channel <channel-ref>
+
+  // Annotations (same as event)
+  @badge(...)
+  @repository(...)
+  @api(method: "...", path: "...", statusCodes: "...")
+}
+```
+
+## EBNF
+
+```ebnf
+command_decl     = "command" identifier "{" message_props "}" ;
+```
diff --git a/packages/language-server/specification/05-query.md b/packages/language-server/specification/05-query.md
new file mode 100644
index 000000000..81e120a1b
--- /dev/null
+++ b/packages/language-server/specification/05-query.md
@@ -0,0 +1,28 @@
+# Query
+
+A request for information.
+
+```
+query <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+  schema "<path>"
+  deprecated true
+  draft true
+
+  channel <channel-ref>
+
+  // Annotations (same as event)
+  @badge(...)
+  @repository(...)
+  @api(method: "...", path: "...", statusCodes: "...")
+}
+```
+
+## EBNF
+
+```ebnf
+query_decl       = "query" identifier "{" message_props "}" ;
+```
diff --git a/packages/language-server/specification/06-channel.md b/packages/language-server/specification/06-channel.md
new file mode 100644
index 000000000..f4c8505d8
--- /dev/null
+++ b/packages/language-server/specification/06-channel.md
@@ -0,0 +1,151 @@
+# Channel
+
+A communication channel (topic, queue, exchange, etc.).
+
+```
+channel <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+
+  address "<address-string>"
+  protocol "<protocol>"
+  deliveryGuarantee at-most-once|at-least-once|exactly-once
+
+  // Channel parameters
+  parameter <name> {
+    description "<text>"
+    default "<value>"
+    enum ["<val1>", "<val2>"]
+    examples ["<ex1>", "<ex2>"]
+  }
+
+  // Routing
+  route <channel-ref>            // repeatable
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+## Delivery guarantee
+
+The `deliveryGuarantee` property declares the message delivery semantics of a channel. The visualiser renders a colored badge on the channel node to make the guarantee visible at a glance.
+
+```
+channel OrderEvents {
+  version 1.0.0
+  protocol "Kafka"
+  deliveryGuarantee exactly-once
+}
+```
+
+| Value           | Meaning                                                     |
+| --------------- | ----------------------------------------------------------- |
+| `at-most-once`  | Messages may be lost; never delivered more than once        |
+| `at-least-once` | Messages are never lost but may be delivered more than once |
+| `exactly-once`  | Messages are delivered exactly once with no duplicates      |
+
+## Channel-to-Channel Routing
+
+Channels can route to other channels using the `route` statement. This models message pipelines where data flows through multiple channels (e.g., Kafka topic → Kafka topic → MQTT broker):
+
+```
+channel SensorIngestion {
+  version 1.0.0
+  protocol "Kafka"
+  route SensorFiltered
+}
+
+channel SensorFiltered {
+  version 1.0.0
+  protocol "Kafka"
+  route MqttDevices
+}
+
+channel MqttDevices {
+  version 1.0.0
+  protocol "MQTT"
+}
+```
+
+This creates a chain: `SensorIngestion → SensorFiltered → MqttDevices`.
+
+A channel can route to multiple targets (fan-out):
+
+```
+channel Ingestion {
+  version 1.0.0
+  route Analytics
+  route Archive
+}
+```
+
+Routes can include versioned references:
+
+```
+channel Source {
+  version 1.0.0
+  route Target@2.0.0
+}
+```
+
+## Service-to-Channel Routing
+
+Services send/receive messages through channels:
+
+```
+service OrderService {
+  version 1.0.0
+
+  // Simple — no channel
+  sends event OrderCreated
+
+  // To a single channel
+  sends event OrderCreated to orders-topic
+
+  // To a channel with version (using @ syntax)
+  sends event OrderCreated to orders-topic@1.0.0
+
+  // To multiple channels (comma-separated)
+  sends event OrderCreated to orders-topic, orders-backup-topic
+
+  // To multiple channels with versions
+  sends event OrderCreated to orders-topic@1.0.0, orders-backup-topic@2.0.0
+
+  // Receiving from a single channel
+  receives event PaymentProcessed from payment-events
+
+  // Receiving from multiple channels
+  receives event PaymentProcessed from payment-events, payment-retry-queue
+
+  // Receiving from channels with versions
+  receives event PaymentProcessed from payment-events@1.0.0, payment-retry-queue@2.1.0
+}
+```
+
+## EBNF
+
+```ebnf
+channel_decl     = "channel" identifier "{" common_props
+                   { channel_body_item } "}" ;
+channel_body_item= address_prop | protocol_prop | delivery_guarantee_prop
+                 | parameter_decl | route_stmt | annotation ;
+address_prop              = "address" string_lit ;
+protocol_prop             = "protocol" string_lit ;
+delivery_guarantee_prop   = "deliveryGuarantee" ( "at-most-once" | "at-least-once" | "exactly-once" ) ;
+parameter_decl   = "parameter" identifier "{" { param_prop } "}" ;
+param_prop       = "description" string_lit
+                 | "default" string_lit
+                 | "enum" "[" string_lit { "," string_lit } "]"
+                 | "examples" "[" string_lit { "," string_lit } "]" ;
+route_stmt       = "route" resource_ref ;
+
+channel_clause   = to_clause | from_clause ;
+to_clause        = "to" channel_ref_list ;
+from_clause      = "from" channel_ref_list ;
+channel_ref_list = channel_ref { "," channel_ref } ;
+channel_ref      = identifier [ "@" version_lit ] ;
+```
diff --git a/packages/language-server/specification/08-container.md b/packages/language-server/specification/08-container.md
new file mode 100644
index 000000000..88ddde725
--- /dev/null
+++ b/packages/language-server/specification/08-container.md
@@ -0,0 +1,54 @@
+# Container
+
+A data store, cache, or external system.
+
+```
+container <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+
+  // Required
+  container-type <database | cache | objectStore | searchIndex
+                 | dataWarehouse | dataLake | externalSaaS | other>
+
+  // Optional
+  deprecated true
+  draft true
+  technology "<tech-string>"     // e.g., "postgres@15", "redis@7"
+  authoritative true
+  access-mode <read | write | readWrite | appendOnly>
+  classification <public | internal | confidential | regulated>
+  residency "<location>"
+  retention "<duration>"         // e.g., "90d", "10y"
+
+  // Relationships
+  service <service-ref>          // repeatable
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+## EBNF
+
+```ebnf
+container_decl   = "container" identifier "{" common_props
+                   { container_body_item } "}" ;
+container_body_item = container_type_prop | technology_prop
+                    | authoritative_prop | access_mode_prop
+                    | classification_prop | residency_prop
+                    | retention_prop
+                    | service_ref_stmt | annotation ;
+container_type_prop   = "container-type" container_type_enum ;
+container_type_enum   = "database" | "cache" | "objectStore" | "searchIndex"
+                      | "dataWarehouse" | "dataLake" | "externalSaaS" | "other" ;
+technology_prop       = "technology" string_lit ;
+authoritative_prop    = "authoritative" bool_lit ;
+access_mode_prop      = "access-mode" ( "read" | "write" | "readWrite" | "appendOnly" ) ;
+classification_prop   = "classification" ( "public" | "internal" | "confidential" | "regulated" ) ;
+residency_prop        = "residency" string_lit ;
+retention_prop        = "retention" string_lit ;
+```
diff --git a/packages/language-server/specification/09-data-product.md b/packages/language-server/specification/09-data-product.md
new file mode 100644
index 000000000..556daaf7e
--- /dev/null
+++ b/packages/language-server/specification/09-data-product.md
@@ -0,0 +1,39 @@
+# Data Product
+
+An analytical data product.
+
+```
+data-product <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+  deprecated true
+  draft true
+
+  // Data lineage
+  input <message-type> <resource-ref>      // repeatable
+  output <message-type> <resource-ref> {   // repeatable, with optional contract
+    contract {
+      path "<path>"
+      name "<name>"
+      type "<type>"
+    }
+  }
+
+  // Annotations
+  @badge(...)
+}
+```
+
+## EBNF
+
+```ebnf
+data_product_decl = "data-product" identifier "{" common_props
+                    { dp_body_item } "}" ;
+dp_body_item      = input_stmt | output_stmt | annotation ;
+input_stmt        = "input" message_type resource_ref ;
+output_stmt       = "output" message_type resource_ref [ "{" contract_block "}" ] ;
+contract_block    = "contract" "{" "path" string_lit "name" string_lit
+                    [ "type" string_lit ] "}" ;
+```
diff --git a/packages/language-server/specification/10-flow.md b/packages/language-server/specification/10-flow.md
new file mode 100644
index 000000000..7b1f6ec1a
--- /dev/null
+++ b/packages/language-server/specification/10-flow.md
@@ -0,0 +1,163 @@
+# Flow
+
+Flows define step-by-step business processes using a PM-friendly `when`-block syntax. Resources are referenced by name only — types are resolved from the catalog.
+
+```
+flow <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+
+  // Entry chain — the starting sequence
+  <Name> ["<label>"] -> <Name> ["<label>"] -> ...
+
+  // When blocks — react to events
+  when <TriggerName>
+    <ServiceName> "<description>"
+      -> "<label>": <OutputName>
+
+  // Convergence — multiple triggers must complete
+  when <TriggerA> and <TriggerB>
+    <ServiceName> "<description>"
+}
+```
+
+## Actors and External Systems
+
+To use actors and external systems in flows, define them as top-level resources. The flow resolves their type automatically by name:
+
+```
+actor Customer {
+  name "Customer"
+  summary "End user on the storefront"
+}
+
+external-system WarehouseWMS {
+  name "Warehouse WMS"
+  summary "Legacy warehouse management system"
+}
+```
+
+Both support optional bodies with `name`, `summary`, and annotations. They can also be bare (no body):
+
+```
+actor Customer
+external-system WarehouseWMS
+```
+
+## Flow References
+
+Resources in flows are referenced by name only (no type keywords like `service` or `event`). Types are resolved from catalog definitions or sibling `.ec` files. If no matching definition is found, the default type is `step`. Compilers may warn on unresolved flow references.
+
+Each reference can include an optional label:
+
+- `Customer "places an order"` — name with display label
+- `PlaceOrder` — bare name (no label)
+- `PaymentService "processes the payment"` — service with description
+
+## Entry Chains
+
+The entry chain defines the starting sequence of a flow. It uses arrow (`->`) syntax:
+
+```
+Customer "places an order"
+  -> PlaceOrder
+  -> OrderService "creates the order"
+  -> OrderCreated
+```
+
+Multiple sources can converge into a chain using commas:
+
+```
+EventA, EventB -> MergingService
+```
+
+## When Blocks
+
+`when` blocks define reactions to events. Each block starts with one or more trigger names, followed by actions:
+
+```
+when OrderCreated
+  PaymentService "processes the payment"
+    -> "success": PaymentProcessed
+    -> "failure": PaymentFailed
+  InventoryService "reserves stock"
+    -> StockReserved
+```
+
+### Labeled Outputs
+
+Action outputs can have optional labels (quoted strings followed by a colon):
+
+```
+-> "success": PaymentProcessed    // labeled output
+-> StockReserved                   // unlabeled output
+```
+
+### Convergence
+
+Use `and` to require multiple triggers before actions execute:
+
+```
+when PaymentProcessed and StockReserved
+  FulfillmentService "ships the order"
+    -> OrderShipped
+```
+
+### Terminal Actions
+
+Actions without outputs are terminal steps:
+
+```
+when OrderShipped
+  WarehouseWMS "syncs with legacy WMS"
+  NotificationService "notifies the customer"
+```
+
+## Example
+
+```
+flow OrderFulfillment {
+  version 1.0.0
+  name "Order Fulfillment"
+  summary "End-to-end order processing from placement to delivery"
+  owner fulfillment-team
+
+  Customer "places an order"
+    -> PlaceOrder
+    -> OrderService "creates the order"
+    -> OrderCreated
+
+  when OrderCreated
+    PaymentService "processes the payment"
+      -> "success": PaymentProcessed
+      -> "failure": PaymentFailed
+    InventoryService "reserves stock"
+      -> StockReserved
+
+  when PaymentFailed
+    NotificationService "notifies the customer of failure"
+
+  when PaymentProcessed and StockReserved
+    FulfillmentService "ships the order"
+      -> OrderShipped
+
+  when OrderShipped
+    WarehouseWMS "syncs with legacy WMS"
+    NotificationService "notifies the customer"
+      -> CustomerNotified
+}
+```
+
+## EBNF
+
+```ebnf
+flow_decl         = "flow" identifier "{" common_props
+                    { flow_entry_chain | flow_when_block } "}" ;
+flow_entry_chain  = flow_ref { "," flow_ref } ( "->" flow_ref )+ ;
+flow_when_block   = "when" flow_ref { "and" flow_ref } flow_action+ ;
+flow_action       = flow_ref { flow_output } ;
+flow_output       = "->" [ string_lit ":" ] flow_ref ;
+flow_ref          = identifier [ string_lit ] ;
+```
diff --git a/packages/language-server/specification/11-diagram.md b/packages/language-server/specification/11-diagram.md
new file mode 100644
index 000000000..c0711d725
--- /dev/null
+++ b/packages/language-server/specification/11-diagram.md
@@ -0,0 +1,3 @@
+# Diagram
+
+_Removed from V1. May be added in a future version._
diff --git a/packages/language-server/specification/12-user.md b/packages/language-server/specification/12-user.md
new file mode 100644
index 000000000..4457b5ef0
--- /dev/null
+++ b/packages/language-server/specification/12-user.md
@@ -0,0 +1,37 @@
+# User
+
+A user definition for team members.
+
+```
+user <id> {
+  name "<display name>"
+  avatar "<url>"
+  role "<role>"
+  email "<email>"
+  slack "<url>"
+  ms-teams "<url>"
+}
+```
+
+## Example
+
+```
+user dboyne {
+  name "David Boyne"
+  avatar "https://avatars.githubusercontent.com/u/3268013"
+  role "Principal Engineer"
+  email "david@company.com"
+}
+```
+
+## EBNF
+
+```ebnf
+user_decl         = "user" identifier "{" user_props "}" ;
+user_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit ;
+```
diff --git a/packages/language-server/specification/13-team.md b/packages/language-server/specification/13-team.md
new file mode 100644
index 000000000..4f5566588
--- /dev/null
+++ b/packages/language-server/specification/13-team.md
@@ -0,0 +1,60 @@
+# Team
+
+A team definition for ownership and membership.
+
+```
+team <id> {
+  name "<display name>"
+  avatar "<url>"
+  role "<role>"
+  summary "<text>"
+  email "<email>"
+  slack "<url>"
+  ms-teams "<url>"
+
+  // Members
+  member <user-id>               // repeatable
+}
+```
+
+## Owner References
+
+Owners are referenced by team or user ID:
+
+```
+service OrderService {
+  version 1.0.0
+  owner payment-team              // team reference
+  owner dboyne                   // user reference
+}
+```
+
+## Example
+
+```
+team orders-team {
+  name "Orders Team"
+  avatar "https://example.com/orders-team.png"
+  role "Platform Engineering"
+  summary "Responsible for order lifecycle"
+  email "orders@company.com"
+  slack "https://company.slack.com/channels/orders"
+
+  member dboyne
+  member jane-doe
+}
+```
+
+## EBNF
+
+```ebnf
+team_decl         = "team" identifier "{" team_props "}" ;
+team_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "summary" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit
+                  | "member" identifier ;
+```
diff --git a/packages/language-server/specification/14-relationships.md b/packages/language-server/specification/14-relationships.md
new file mode 100644
index 000000000..320f492dc
--- /dev/null
+++ b/packages/language-server/specification/14-relationships.md
@@ -0,0 +1,89 @@
+# Relationships & Pointers
+
+## Resource References
+
+Resources can be referenced by ID alone (resolves to `latest`) or with an explicit version:
+
+```
+// Reference by ID only (latest version)
+receives event OrderCreated
+
+// Reference by ID + version using @ syntax
+receives event OrderCreated@2.0.0
+
+// Reference with single channel routing
+sends event OrderCreated to orders-topic
+
+// Reference with channel version
+sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+
+// Reference with multiple channels
+sends event OrderCreated to orders-topic, backup-topic
+receives event PaymentProcessed from payment-events, payment-retry
+```
+
+## Inline vs. Reference
+
+Resources can be defined inline (creating them) or referenced (linking to existing):
+
+```
+service OrderService {
+  version 1.0.0
+
+  // Inline definition — creates the event
+  sends event OrderCreated {
+    version 1.0.0
+    summary "A new order was placed"
+  }
+
+  // Reference only — links to an existing event
+  receives event PaymentProcessed
+  receives event PaymentProcessed@2.0.0
+}
+```
+
+Inline messages do not support the `channel` statement — use `to`/`from` on the `sends`/`receives` statement for channel routing.
+
+## Pointer Syntax Summary
+
+| Syntax                        | Meaning                       |
+| ----------------------------- | ----------------------------- |
+| `<id>`                        | Latest version of resource    |
+| `<id>@<version>`              | Specific version              |
+| `<id> to <channel>`           | With single channel routing   |
+| `<id> to <channel>@<version>` | Channel with specific version |
+| `<id> to <ch1>, <ch2>, <ch3>` | Multiple channels             |
+| `<id> from <channel>`         | Received from channel         |
+| `<id> from <ch1>, <ch2>`      | Received from multiple        |
+
+## Data Relationships
+
+```
+writes-to container <container-ref>
+reads-from container <container-ref>
+```
+
+## EBNF
+
+```ebnf
+resource_ref     = identifier [ "@" version_lit ] ;
+message_type     = "event" | "command" | "query" ;
+
+sends_stmt       = "sends" message_type resource_ref [ channel_clause ]
+                 | "sends" message_type identifier inline_block ;
+receives_stmt    = "receives" message_type resource_ref [ channel_clause ]
+                 | "receives" message_type identifier inline_block ;
+
+channel_clause   = to_clause | from_clause ;
+to_clause        = "to" channel_ref_list ;
+from_clause      = "from" channel_ref_list ;
+channel_ref_list = channel_ref { "," channel_ref } ;
+channel_ref      = identifier [ "@" version_lit ] ;
+
+writes_to_stmt   = "writes-to" "container" resource_ref ;
+reads_from_stmt  = "reads-from" "container" resource_ref ;
+flow_ref_stmt    = "flow" resource_ref ;
+data_product_ref_stmt      = "data-product" resource_ref ;
+
+inline_block     = "{" message_props "}" ;
+```
diff --git a/packages/language-server/specification/15-versioning.md b/packages/language-server/specification/15-versioning.md
new file mode 100644
index 000000000..a3efb063d
--- /dev/null
+++ b/packages/language-server/specification/15-versioning.md
@@ -0,0 +1,41 @@
+# Versioning
+
+## Declaring Versions
+
+Every versioned resource requires a version:
+
+```
+event OrderCreated {
+  version 1.0.0
+}
+```
+
+## Referencing Versions
+
+```
+// Latest (default - no version specified)
+receives event OrderCreated
+
+// Specific version using @ syntax
+receives event OrderCreated@2.0.0
+
+// Channel with version
+sends event OrderProcessed to payments-channel@1.0.0
+
+// Multiple channels with versions
+receives event PaymentFailed from channel-a@1.0.0, channel-b@2.1.0
+```
+
+## Version Defaults
+
+When no version is specified in a reference, it resolves to `latest`.
+
+## EBNF
+
+```ebnf
+int              = digit { digit } ;
+version_lit      = int "." int "." int [ "-" prerelease ] ;
+version_prop     = "version" version_lit ;
+version_ref      = "@" version_lit ;
+resource_ref     = identifier [ version_ref ] ;
+```
diff --git a/packages/language-server/specification/16-annotations.md b/packages/language-server/specification/16-annotations.md
new file mode 100644
index 000000000..b719e3f57
--- /dev/null
+++ b/packages/language-server/specification/16-annotations.md
@@ -0,0 +1,152 @@
+# Metadata & Annotations
+
+Annotations use the `@` prefix and provide additional metadata. They can appear inside any resource block. All annotations are repeatable by default — multiple instances of the same annotation may appear on a single resource.
+
+## @badge
+
+```
+@badge("Production", bg: "#22c55e", text: "#fff")
+@badge("Beta", bg: "#f59e0b", text: "#000", icon: "flask")
+```
+
+## @repository
+
+```
+@repository(url: "https://github.com/org/repo", language: "TypeScript")
+```
+
+## @editUrl
+
+```
+@editUrl("https://github.com/org/repo/edit/main/docs/orders.md")
+```
+
+## @note
+
+Adds free-form developer notes or reminders to any resource. Notes are repeatable — multiple `@note` annotations can appear on a single resource. Supported on services, events, commands, queries, channels, and inline message definitions.
+
+```
+// Simple note
+@note("Come back later — needs review")
+
+// With optional parameters
+@note("Align schema with PaymentService team", author: "dboyne", priority: "high")
+
+// Multiple notes on a service
+service OrderService {
+  version 1.0.0
+  @note("TODO: add retry logic")
+  @note("Waiting on team alignment", priority: "medium")
+}
+
+// Notes on events, commands, and queries
+event OrderCreated {
+  version 1.0.0
+  @note("Schema v2 adds shippingAddress field", author: "alice")
+}
+
+command CreateOrder {
+  version 1.0.0
+  @note("Validate idempotency key", author: "bob", priority: "high")
+}
+
+// Notes on channels
+channel OrderEvents {
+  version 1.0.0
+  address "orders.events"
+  protocol "kafka"
+  @note("Partition key is orderId", author: "infra-team")
+}
+
+// Notes on inline messages (inside sends/receives)
+service PaymentService {
+  version 1.0.0
+  sends event PaymentProcessed to PaymentEvents {
+    version 1.0.0
+    @note("Includes refund reference when applicable", author: "dave")
+  }
+}
+```
+
+## @api
+
+Attaches HTTP API metadata to a message (event, command, or query). Typically generated automatically when importing an OpenAPI spec, but can also be written manually. The visualiser displays the method badge, API path, and response status codes on the node.
+
+```
+// Basic usage with method and path
+command CreateOrder {
+  version 1.0.0
+  summary "Create a new order"
+  @api(method: "POST", path: "/orders")
+}
+
+// With status codes
+query GetOrders {
+  version 1.0.0
+  summary "List all orders"
+  @api(method: "GET", path: "/orders", statusCodes: "200,401")
+}
+
+// On inline message definitions
+service PaymentService {
+  version 2.0.0
+  receives command CreatePayment {
+    version 2.0.0
+    summary "Process a new payment"
+    @api(method: "POST", path: "/payments", statusCodes: "201,400,422")
+  }
+  receives query GetPayment {
+    version 2.0.0
+    @api(method: "GET", path: "/payments/{paymentId}", statusCodes: "200,404")
+  }
+}
+```
+
+### Parameters
+
+| Parameter     | Type   | Description                                              |
+| ------------- | ------ | -------------------------------------------------------- |
+| `method`      | string | HTTP method (GET, POST, PUT, PATCH, DELETE)              |
+| `path`        | string | API path (e.g. `/orders`, `/users/{id}`)                 |
+| `statusCodes` | string | Comma-separated HTTP status codes (e.g. `"200,401,500"`) |
+
+### Auto-generated from OpenAPI
+
+When importing an OpenAPI spec, `@api` annotations are automatically added to the generated `.ec` definitions:
+
+```
+import PaymentService from "./payments-openapi.yml"
+```
+
+This generates commands and queries with `@api` annotations populated from the OpenAPI paths, methods, and response codes.
+
+## @detailsPanel
+
+Controls visibility of detail panel sections:
+
+```
+@detailsPanel {
+  owners visible
+  versions visible
+  changelog hidden
+  producers visible
+  consumers hidden
+  channels visible
+  repository hidden
+  specifications hidden
+  messages hidden
+  domains hidden
+  services hidden
+  containers hidden
+}
+```
+
+## EBNF
+
+```ebnf
+annotation       = "@" ann_name [ "(" ann_args ")" ] [ ann_block ] ;
+ann_name         = identifier ;
+ann_args         = ann_arg { "," ann_arg } ;
+ann_arg          = [ identifier ":" ] ( string_lit | bool_lit | number_lit | identifier ) ;
+ann_block        = "{" { ann_body_item } "}" ;
+```
diff --git a/packages/language-server/specification/17-examples.md b/packages/language-server/specification/17-examples.md
new file mode 100644
index 000000000..abb696b01
--- /dev/null
+++ b/packages/language-server/specification/17-examples.md
@@ -0,0 +1,373 @@
+# Complete Examples
+
+## Example 1: E-Commerce Platform
+
+```
+// ============================================================
+// Teams & Users
+// ============================================================
+
+user dboyne {
+  name "David Boyne"
+  avatar "https://avatars.githubusercontent.com/u/3268013"
+  role "Principal Engineer"
+  email "david@company.com"
+}
+
+user jane-doe {
+  name "Jane Doe"
+  avatar "https://avatars.githubusercontent.com/u/12345"
+  role "Staff Engineer"
+}
+
+team orders-team {
+  name "Orders Team"
+  summary "Responsible for order lifecycle"
+  email "orders@company.com"
+  slack "https://company.slack.com/channels/orders"
+
+  member dboyne
+  member jane-doe
+}
+
+team payment-team {
+  name "Payment Team"
+  summary "Handles payment processing and fraud detection"
+  email "payments@company.com"
+
+  member jane-doe
+}
+
+// ============================================================
+// Channels
+// ============================================================
+
+channel orders-topic {
+  version 1.0.0
+  name "Orders Topic"
+  summary "Kafka topic for all order-related events"
+  address "kafka://production/orders"
+  protocol "Kafka"
+
+  parameter environment {
+    description "Deployment environment"
+    default "production"
+    enum ["production", "staging", "development"]
+  }
+
+}
+
+channel payment-queue {
+  version 1.0.0
+  name "Payment Queue"
+  summary "SQS queue for payment commands"
+  address "sqs://us-east-1/payment-processing"
+  protocol "SQS"
+}
+
+// ============================================================
+// Containers
+// ============================================================
+
+container orders-db {
+  version 1.0.0
+  name "Orders Database"
+  summary "Primary datastore for order data"
+  owner orders-team
+
+  container-type database
+  technology "postgres@15"
+  authoritative true
+  access-mode readWrite
+  classification confidential
+  residency "us-east-1"
+  retention "7y"
+
+  @repository(url: "https://github.com/company/orders-db")
+}
+
+container orders-cache {
+  version 1.0.0
+  name "Orders Cache"
+  summary "Redis cache for hot order lookups"
+
+  container-type cache
+  technology "redis@7"
+  access-mode readWrite
+  retention "24h"
+}
+
+// ============================================================
+// Domain
+// ============================================================
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  summary "Everything related to order management"
+  owner orders-team
+
+  @badge("Core", bg: "#3b82f6", text: "#fff")
+  @repository(url: "https://github.com/company/orders-domain")
+
+  service OrderService {
+    version 1.0.0
+    name "Order Service"
+    summary "Manages the order lifecycle"
+    owner orders-team
+
+    @repository(url: "https://github.com/company/order-service", language: "TypeScript")
+    @badge("Production", bg: "#22c55e", text: "#fff")
+
+    sends event OrderCreated {
+      version 1.0.0
+      summary "Emitted when a new order is placed"
+      schema "./schemas/order-created.avro"
+    }
+
+    sends event OrderUpdated {
+      version 1.0.0
+      summary "Emitted when order details change"
+    }
+
+    sends command ProcessPayment to payment-queue {
+      version 1.0.0
+      summary "Triggers payment processing for an order"
+    }
+
+    receives event PaymentProcessed from payment-queue
+    receives event InventoryReserved
+
+    writes-to container orders-db
+    reads-from container orders-db
+    writes-to container orders-cache
+    reads-from container orders-cache
+
+    flow OrderFulfillment@1.0.0
+  }
+
+  service NotificationService {
+    version 1.0.0
+    name "Notification Service"
+    summary "Sends email and push notifications for order updates"
+
+    receives event OrderCreated
+    receives event OrderUpdated
+
+    sends command SendEmail {
+      version 1.0.0
+      summary "Dispatches an email notification"
+    }
+  }
+}
+
+domain Payment {
+  version 1.0.0
+  name "Payment Domain"
+  summary "Payment processing and fraud detection"
+  owner payment-team
+
+  service PaymentService {
+    version 1.0.0
+    name "Payment Service"
+    summary "Processes payments via Stripe"
+    owner payment-team
+
+    @repository(url: "https://github.com/company/payment-service", language: "Go")
+
+    receives command ProcessPayment from payment-queue
+
+    sends event PaymentProcessed {
+      version 1.0.0
+      summary "Payment completed successfully"
+    }
+
+    sends event PaymentFailed {
+      version 1.0.0
+      summary "Payment was declined or errored"
+    }
+  }
+}
+
+// ============================================================
+// Standalone events (defined outside services)
+// ============================================================
+
+event InventoryReserved {
+  version 1.0.0
+  name "Inventory Reserved"
+  summary "Stock has been reserved for an order"
+  owner orders-team
+
+  @badge("Critical", bg: "#ef4444", text: "#fff")
+}
+
+// ============================================================
+// Data Product
+// ============================================================
+
+data-product OrderAnalytics {
+  version 1.0.0
+  name "Order Analytics"
+  summary "Real-time and batch analytics for order metrics"
+  owner orders-team
+
+  input event OrderCreated@1.0.0
+  input event PaymentProcessed@1.0.0
+  input event InventoryReserved@1.0.0
+
+  output event OrderMetrics {
+    contract {
+      path "./contracts/order-metrics.json"
+      name "Order Metrics Schema"
+      type "json-schema"
+    }
+  }
+}
+
+// ============================================================
+// Actors & External Systems
+// ============================================================
+
+actor Customer {
+  name "Customer"
+  summary "End user on the storefront"
+}
+
+external-system WarehouseWMS {
+  name "Warehouse WMS"
+  summary "Legacy warehouse management system via SOAP API"
+}
+
+// ============================================================
+// Flow
+// ============================================================
+
+flow OrderFulfillment {
+  version 1.0.0
+  name "Order Fulfillment"
+  summary "End-to-end order processing from placement to delivery"
+  owner orders-team
+
+  Customer "End user on the storefront"
+    -> PlaceOrder
+    -> OrderService
+    -> OrderCreated
+
+  when OrderCreated
+    PaymentService "processes the payment"
+      -> "success": PaymentProcessed
+      -> "failure": PaymentFailed
+    InventoryService "reserves inventory"
+      -> InventoryReserved
+
+  when InventoryReserved
+    WarehouseWMS "Legacy WMS via SOAP API"
+}
+
+```
+
+## Example 2: Minimal Service Definition
+
+The DSL supports minimal definitions where defaults are sufficient:
+
+```
+service OrderService {
+  version 1.0.0
+  sends event OrderCreated
+  receives command ProcessPayment
+  receives event PaymentProcessed
+}
+```
+
+## Example 3: Multi-Channel Routing
+
+```
+service EventRouter {
+  version 1.0.0
+  summary "Routes events across multiple channels"
+
+  // Send to multiple channels (comma-separated)
+  sends event OrderCreated to orders-topic, orders-archive-topic
+
+  // Receive from multiple channels
+  receives event PaymentProcessed from payment-events, payment-retry-queue
+}
+```
+
+## Example 4: Channel Routing (IoT Pipeline)
+
+```
+channel SensorIngestion {
+  version 1.0.0
+  address "sensors.raw"
+  protocol "Kafka"
+  summary "Raw sensor data ingestion"
+  route SensorFiltered
+}
+
+channel SensorFiltered {
+  version 1.0.0
+  address "sensors.filtered"
+  protocol "Kafka"
+  summary "Validated sensor data"
+  route DeviceCommands
+}
+
+channel DeviceCommands {
+  version 1.0.0
+  address "devices/+/commands"
+  protocol "MQTT"
+  summary "MQTT topic for device commands"
+}
+
+service SensorGateway {
+  version 1.0.0
+  summary "Ingests raw sensor readings"
+  sends event SensorReading to SensorIngestion
+}
+
+service FilterService {
+  version 1.0.0
+  summary "Validates and filters sensor data"
+  receives event SensorReading from SensorIngestion
+  sends event DeviceAlert to SensorFiltered
+}
+
+service DeviceBridge {
+  version 1.0.0
+  summary "Bridges Kafka to MQTT"
+  receives event DeviceAlert from SensorFiltered
+  sends command RecalibrateDevice to DeviceCommands
+}
+```
+
+## Example 5: Subdomains
+
+```
+domain Logistics {
+  version 1.0.0
+
+  subdomain Shipping {
+    version 1.0.0
+    summary "Package shipping and tracking"
+
+    service ShippingService {
+      version 1.0.0
+      receives event OrderCreated
+      sends event ShipmentCreated
+    }
+  }
+
+  subdomain Returns {
+    version 1.0.0
+    summary "Return merchandise authorization"
+
+    service ReturnsService {
+      version 1.0.0
+      receives command InitiateReturn
+      sends event ReturnApproved
+    }
+  }
+}
+```
diff --git a/packages/language-server/specification/18-grammar.md b/packages/language-server/specification/18-grammar.md
new file mode 100644
index 000000000..fd94b3918
--- /dev/null
+++ b/packages/language-server/specification/18-grammar.md
@@ -0,0 +1,240 @@
+# Full Grammar (EBNF)
+
+```ebnf
+(* Top-level *)
+program          = { top_level_decl } ;
+top_level_decl   = domain_decl | service_decl | event_decl | command_decl
+                 | query_decl | channel_decl | container_decl
+                 | data_product_decl | flow_decl
+                 | user_decl | team_decl | visualizer_decl
+                 | actor_decl | external_system_decl ;
+
+(* Identifiers and literals *)
+identifier       = letter { letter | digit | "-" | "." | "_" } ;
+int              = digit { digit } ;
+version_lit      = int "." int "." int [ "-" prerelease ] ;
+string_lit       = '"' { any_char } '"' ;
+bool_lit         = "true" | "false" ;
+number_lit       = digit { digit } ;
+
+(* Common properties *)
+common_props     = { version_prop | name_prop | summary_prop | owner_prop
+                   | deprecated_prop | draft_prop | annotation } ;
+message_props    = { version_prop | name_prop | summary_prop | owner_prop
+                   | schema_prop | deprecated_prop | draft_prop | annotation } ;
+version_prop     = "version" version_lit ;
+name_prop        = "name" string_lit ;
+summary_prop     = "summary" string_lit ;
+owner_prop       = "owner" identifier ;
+schema_prop      = "schema" string_lit ;
+deprecated_prop  = "deprecated" bool_lit ;
+draft_prop       = "draft" bool_lit ;
+
+(* Annotations *)
+annotation       = "@" ann_name [ "(" ann_args ")" ] [ ann_block ] ;
+ann_name         = identifier ;
+ann_args         = ann_arg { "," ann_arg } ;
+ann_arg          = [ identifier ":" ] ( string_lit | bool_lit | number_lit | identifier ) ;
+ann_block        = "{" { ann_body_item } "}" ;
+
+(* Resource references *)
+resource_ref     = identifier [ "@" version_lit ] ;
+message_type     = "event" | "command" | "query" ;
+
+(* Domain *)
+domain_decl      = "domain" identifier "{" common_props
+                   { domain_body_item } "}" ;
+domain_body_item = service_decl | subdomain_decl
+                 | data_product_ref_stmt | flow_ref_stmt
+                 | sends_stmt | receives_stmt
+                 | annotation ;
+subdomain_decl   = "subdomain" identifier "{" common_props
+                   { domain_body_item } "}" ;
+
+(* Service *)
+service_decl     = "service" identifier "{" common_props
+                   { service_body_item } "}" ;
+service_body_item= sends_stmt | receives_stmt
+                 | writes_to_stmt | reads_from_stmt
+                 | flow_ref_stmt
+                 | annotation ;
+
+(* Sends / Receives *)
+sends_stmt       = "sends" message_type resource_ref [ channel_clause ]
+                 | "sends" message_type identifier inline_block ;
+receives_stmt    = "receives" message_type resource_ref [ channel_clause ]
+                 | "receives" message_type identifier inline_block ;
+
+channel_clause   = to_clause | from_clause ;
+to_clause        = "to" channel_ref_list ;
+from_clause      = "from" channel_ref_list ;
+channel_ref_list = channel_ref { "," channel_ref } ;
+channel_ref      = identifier [ "@" version_lit ] ;
+
+(* Data relationships *)
+writes_to_stmt   = "writes-to" "container" resource_ref ;
+reads_from_stmt  = "reads-from" "container" resource_ref ;
+flow_ref_stmt    = "flow" resource_ref ;
+data_product_ref_stmt      = "data-product" resource_ref ;
+
+(* Inline message block *)
+inline_block     = "{" message_props "}" ;
+
+(* Messages: Event, Command, Query *)
+event_decl       = "event" identifier "{" message_props "}" ;
+command_decl     = "command" identifier "{" message_props "}" ;
+query_decl       = "query" identifier "{" message_props "}" ;
+
+(* Channel *)
+channel_decl     = "channel" identifier "{" common_props
+                   { channel_body_item } "}" ;
+channel_body_item= address_prop | protocol_prop | parameter_decl
+                 | route_stmt | annotation ;
+address_prop     = "address" string_lit ;
+protocol_prop    = "protocol" string_lit ;
+parameter_decl   = "parameter" identifier "{" { param_prop } "}" ;
+param_prop       = "description" string_lit
+                 | "default" string_lit
+                 | "enum" "[" string_lit { "," string_lit } "]"
+                 | "examples" "[" string_lit { "," string_lit } "]" ;
+route_stmt       = "route" resource_ref ;
+
+(* Container *)
+container_decl   = "container" identifier "{" common_props
+                   { container_body_item } "}" ;
+container_body_item = container_type_prop | technology_prop
+                    | authoritative_prop | access_mode_prop
+                    | classification_prop | residency_prop
+                    | retention_prop
+                    | service_ref_stmt | annotation ;
+container_type_prop   = "container-type" container_type_enum ;
+container_type_enum   = "database" | "cache" | "objectStore" | "searchIndex"
+                      | "dataWarehouse" | "dataLake" | "externalSaaS" | "other" ;
+technology_prop       = "technology" string_lit ;
+authoritative_prop    = "authoritative" bool_lit ;
+access_mode_prop      = "access-mode" ( "read" | "write" | "readWrite" | "appendOnly" ) ;
+classification_prop   = "classification" ( "public" | "internal" | "confidential" | "regulated" ) ;
+residency_prop        = "residency" string_lit ;
+retention_prop        = "retention" string_lit ;
+
+(* Data Product *)
+data_product_decl = "data-product" identifier "{" common_props
+                    { dp_body_item } "}" ;
+dp_body_item      = input_stmt | output_stmt | annotation ;
+input_stmt        = "input" message_type resource_ref ;
+output_stmt       = "output" message_type resource_ref [ "{" contract_block "}" ] ;
+contract_block    = "contract" "{" "path" string_lit "name" string_lit
+                    [ "type" string_lit ] "}" ;
+
+(* Flow *)
+flow_decl         = "flow" identifier "{" common_props
+                    { flow_entry_chain | flow_when_block } "}" ;
+flow_entry_chain  = flow_ref { "," flow_ref } ( "->" flow_ref )+ ;
+flow_when_block   = "when" flow_ref { "and" flow_ref } flow_action+ ;
+flow_action       = flow_ref { flow_output } ;
+flow_output       = "->" [ string_lit ":" ] flow_ref ;
+flow_ref          = identifier [ string_lit ] ;
+
+(* Actor *)
+actor_decl        = "actor" identifier [ "{" { actor_body_item } "}" ] ;
+actor_body_item   = name_prop | summary_prop | annotation ;
+
+(* External System *)
+external_system_decl = "external-system" identifier [ "{" { ext_sys_body_item } "}" ] ;
+ext_sys_body_item    = name_prop | summary_prop | annotation ;
+
+(* Visualizer *)
+visualizer_decl   = "visualizer" identifier "{" { visualizer_body } "}" ;
+visualizer_body   = name_prop | summary_prop | annotation
+                  | legend_prop | search_prop | toolbar_prop
+                  | focus_mode_prop | animated_prop | style_prop
+                  | domain_decl | service_decl | event_decl | command_decl
+                  | query_decl | channel_decl | container_decl
+                  | data_product_decl | flow_decl
+                  | actor_decl | external_system_decl
+                  | service_ref_stmt | domain_ref_stmt
+                  | event_ref_stmt | command_ref_stmt | query_ref_stmt
+                  | channel_ref_stmt | data_product_ref_stmt | flow_ref_stmt
+                  | container_ref_stmt ;
+legend_prop       = "legend" bool_lit ;
+search_prop       = "search" bool_lit ;
+toolbar_prop      = "toolbar" bool_lit ;
+focus_mode_prop   = "focus-mode" bool_lit ;
+animated_prop     = "animated" bool_lit ;
+style_prop        = "style" ( "default" | "post-it" ) ;
+
+(* User *)
+user_decl         = "user" identifier "{" user_props "}" ;
+user_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit ;
+
+(* Team *)
+team_decl         = "team" identifier "{" team_props "}" ;
+team_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "summary" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit
+                  | "member" identifier ;
+
+(* Resource references *)
+versioned_resource_ref  = identifier "@" version_lit ;
+service_ref_stmt    = "service" resource_ref ;
+domain_ref_stmt     = "domain" resource_ref ;
+event_ref_stmt      = "event" versioned_resource_ref ;
+command_ref_stmt    = "command" versioned_resource_ref ;
+query_ref_stmt      = "query" versioned_resource_ref ;
+channel_ref_stmt    = "channel" resource_ref ;
+container_ref_stmt  = "container" resource_ref ;
+```
+
+## Reserved Keywords
+
+```
+domain     service     event       command      query
+channel    container   data-product flow
+user       team        sends       receives
+writes-to  reads-from  owns        to           from
+version    name        summary     owner        schema
+deprecated draft       true        false
+type       actor       external-system
+parameter  route       member
+input      output      contract
+subdomain  visualizer  legend      search       toolbar      focus-mode
+animated   style       when        and
+```
+
+## File Extension
+
+EventCatalog DSL files use the `.ec` extension:
+
+```
+catalog.ec
+orders-domain.ec
+payment-service.ec
+```
+
+Multiple `.ec` files can be used and are merged during compilation. Resources can reference each other across files.
+
+## Compilation
+
+The DSL compiles to EventCatalog's directory structure:
+
+```
+catalog.ec  -->  domains/Orders/index.mdx
+                    domains/Orders/services/OrderService/index.mdx
+                    events/OrderCreated/index.mdx
+                    commands/ProcessPayment/index.mdx
+                    channels/orders-topic/index.mdx
+                    users/dboyne.mdx
+                    teams/orders-team.mdx
+                    ...
+```
+
+Each resource becomes a markdown file with YAML frontmatter matching EventCatalog's content collection schemas.
diff --git a/packages/language-server/specification/19-visualizer.md b/packages/language-server/specification/19-visualizer.md
new file mode 100644
index 000000000..9e1379992
--- /dev/null
+++ b/packages/language-server/specification/19-visualizer.md
@@ -0,0 +1,204 @@
+# Visualizer
+
+The `visualizer` block separates **resource definition** from **visualization**. Resources defined outside a visualizer block exist in the catalog but are not rendered visually. Only resources placed inside a `visualizer` block (or referenced from one) appear in the visual graph.
+
+This separation lets teams maintain a single source of truth for all resources while controlling exactly what gets visualized and how.
+
+```
+visualizer <id> {
+  name "<display name>"
+  summary "<text>"
+
+  // Display options
+  legend true|false
+  search true|false
+  toolbar true|false
+  focus-mode true|false
+  animated true|false
+  style default|post-it
+
+  // Resources to visualize (inline or reference)
+  <resource definitions or references>
+}
+```
+
+## Why Visualizer Exists
+
+A `.ec` file can define dozens of resources — domains, services, events, channels, and more. Without a visualizer block, there is no way to control which resources appear in the visual graph or how they are presented.
+
+The visualizer block makes visualization **explicit**:
+
+- Define resources anywhere (top-level, imported files)
+- Choose what to visualize by placing resources inside a `visualizer` block
+- Configure display options per visualization
+
+## Multiple Visualizer Blocks
+
+A file can contain multiple `visualizer` blocks, each presenting a different view over the same resources. Tools (e.g. the playground) allow switching between them.
+
+```
+// Shared resources
+event OrderCreated {
+  version 1.0.0
+}
+
+event PaymentProcessed {
+  version 1.0.0
+}
+
+service OrderService {
+  version 1.0.0
+  sends event OrderCreated
+}
+
+service PaymentService {
+  version 1.0.0
+  receives event OrderCreated
+  sends event PaymentProcessed
+}
+
+// View 1: Order flow only
+visualizer orders {
+  name "Order Flow"
+
+  service OrderService
+  event OrderCreated
+}
+
+// View 2: Full payment pipeline
+visualizer payments {
+  name "Payment Pipeline"
+
+  service OrderService
+  service PaymentService
+  event OrderCreated
+  event PaymentProcessed
+}
+```
+
+## Resources Without a Visualizer
+
+Resources defined outside any `visualizer` block are valid. They can be:
+
+- Imported by other `.ec` files
+- Referenced from within a `visualizer` block
+- Used for compilation to EventCatalog's markdown format
+
+If a file contains no `visualizer` block, no visual graph is produced.
+
+## Inline vs. Reference
+
+Resources inside a visualizer can be defined inline (full definition) or referenced by name:
+
+**Inline** — defines and visualizes the resource:
+
+```
+visualizer main {
+  name "My Architecture"
+
+  service OrderService {
+    version 1.0.0
+    sends event OrderCreated
+  }
+}
+```
+
+**Reference** — visualizes a resource defined elsewhere:
+
+```
+service OrderService {
+  version 1.0.0
+  sends event OrderCreated@1.0.0
+}
+
+event OrderCreated {
+  version 1.0.0
+}
+
+visualizer main {
+  name "My Architecture"
+  service OrderService
+  event OrderCreated@1.0.0
+}
+```
+
+When a resource is referenced, the visualizer enriches the node with metadata from the matching top-level definition.
+
+**Note:** For events, commands, and queries, versioned references require `@version` syntax (e.g., `event OrderCreated@1.0.0`). Without a version, `event OrderCreated` is treated as an inline definition. Services, domains, channels, containers, and other resource types support both versioned (`@version`) and unversioned references.
+
+## Display Options
+
+| Property     | Type    | Default   | Description                            |
+| ------------ | ------- | --------- | -------------------------------------- |
+| `name`       | string  | —         | Display title for the visualization    |
+| `summary`    | string  | —         | Description of the visualization       |
+| `legend`     | boolean | `true`    | Show the node type legend              |
+| `search`     | boolean | `true`    | Show the search bar                    |
+| `toolbar`    | boolean | `true`    | Show the toolbar (export, zoom, etc.)  |
+| `focus-mode` | boolean | `true`    | Enable focus mode for individual nodes |
+| `animated`   | boolean | `true`    | Animate edges                          |
+| `style`      | enum    | `default` | Visual style: `default` or `post-it`   |
+
+## Example
+
+```
+// Teams
+team orders-team {
+  name "Orders Team"
+}
+
+// Resources
+channel orders-topic {
+  version 1.0.0
+  protocol "Kafka"
+}
+
+// Visualizer with display options
+visualizer order-architecture {
+  name "Order Architecture"
+  summary "Core order processing services"
+  legend true
+  search true
+  animated false
+  style post-it
+
+  domain Orders {
+    version 1.0.0
+    owner orders-team
+
+    service OrderService {
+      version 1.0.0
+      sends event OrderCreated to orders-topic
+      receives command CreateOrder
+    }
+
+    service NotificationService {
+      version 1.0.0
+      receives event OrderCreated
+    }
+  }
+}
+```
+
+## EBNF
+
+```ebnf
+visualizer_decl   = "visualizer" identifier "{" { visualizer_body } "}" ;
+visualizer_body   = name_prop | summary_prop | annotation
+                  | legend_prop | search_prop | toolbar_prop
+                  | focus_mode_prop | animated_prop | style_prop
+                  | domain_decl | service_decl | event_decl | command_decl
+                  | query_decl | channel_decl | container_decl
+                  | data_product_decl | flow_decl
+                  | actor_decl | external_system_decl
+                  | service_ref_stmt | domain_ref_stmt
+                  | event_ref_stmt | command_ref_stmt | query_ref_stmt
+                  | channel_ref_stmt | data_product_ref_stmt | flow_ref_stmt
+                  | container_ref_stmt ;
+legend_prop       = "legend" bool_lit ;
+search_prop       = "search" bool_lit ;
+toolbar_prop      = "toolbar" bool_lit ;
+focus_mode_prop   = "focus-mode" bool_lit ;
+animated_prop     = "animated" bool_lit ;
+style_prop        = "style" ( "default" | "post-it" ) ;
+```
diff --git a/packages/language-server/specification/build-spec.sh b/packages/language-server/specification/build-spec.sh
new file mode 100755
index 000000000..0cb4ac41d
--- /dev/null
+++ b/packages/language-server/specification/build-spec.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+#
+# Assembles the individual specification files into a single SPEC.md
+# Usage: ./specification/build-spec.sh
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+OUTPUT="$SCRIPT_DIR/../SPEC.md"
+
+cat > "$OUTPUT" << 'HEADER'
+# EventCatalog DSL — Language Specification
+
+> Version: 1.0.0-draft
+> Status: Draft
+> Date: 2026-02-08
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Domain](#domain)
+3. [Service](#service)
+4. [Event](#event)
+5. [Command](#command)
+6. [Query](#query)
+7. [Channel](#channel)
+8. [Container](#container)
+9. [Data Product](#data-product)
+10. [Flow](#flow)
+11. [User](#user)
+12. [Team](#team)
+13. [Relationships & Pointers](#relationships--pointers)
+14. [Versioning](#versioning)
+15. [Metadata & Annotations](#metadata--annotations)
+16. [Complete Examples](#complete-examples)
+17. [Full Grammar (EBNF)](#full-grammar-ebnf)
+
+---
+
+HEADER
+
+# Append each spec file in order, separated by ---
+for file in "$SCRIPT_DIR"/[0-9][0-9]-*.md; do
+  cat "$file" >> "$OUTPUT"
+  printf '\n---\n\n' >> "$OUTPUT"
+done
+
+echo "Built $OUTPUT from $(ls "$SCRIPT_DIR"/[0-9][0-9]-*.md | wc -l | tr -d ' ') specification files."
diff --git a/packages/language-server/src/ast-utils.ts b/packages/language-server/src/ast-utils.ts
new file mode 100644
index 000000000..ec4a7dea5
--- /dev/null
+++ b/packages/language-server/src/ast-utils.ts
@@ -0,0 +1,373 @@
+import type { AstNode } from "langium";
+import {
+  isVersionStmt,
+  isNameStmt,
+  isSummaryStmt,
+  isOwnerStmt,
+  isDeprecatedStmt,
+  isDraftStmt,
+  isLegendStmt,
+  isSearchStmt,
+  isToolbarStmt,
+  isFocusModeStmt,
+  isAnimatedStmt,
+  isStyleStmt,
+  isSchemaStmt,
+  isServiceDef,
+  isSubdomainDef,
+  isContainerDef,
+  isFlowRefStmt,
+  isDataProductRefStmt,
+  isSendsStmt,
+  isReceivesStmt,
+  isWritesToStmt,
+  isReadsFromStmt,
+  isAnnotation,
+  isChannelRefStmt,
+  isAddressStmt,
+  isProtocolStmt,
+  isParameterDecl,
+  isRouteStmt,
+  isServiceRefStmt,
+  isDomainRefStmt,
+  isContainerRefStmt,
+  isContainerTypeStmt,
+  isTechnologyStmt,
+  isAuthoritativeStmt,
+  isAccessModeStmt,
+  isClassificationStmt,
+  isResidencyStmt,
+  isRetentionStmt,
+  isInputStmt,
+  isOutputStmt,
+  isFlowDef,
+  isFlowEntryChain,
+  isFlowWhenBlock,
+  isToClause,
+  isFromClause,
+} from "./generated/ast.js";
+import type {
+  Annotation,
+  ChannelRefStmt,
+  DataProductRefStmt,
+  ContainerDef,
+  ContainerRefStmt,
+  DomainRefStmt,
+  FlowDef,
+  FlowEntryChain,
+  FlowWhenBlock,
+  FlowRefStmt,
+  FromClause,
+  InputStmt,
+  OutputStmt,
+  ParameterDecl,
+  ReadsFromStmt,
+  ReceivesStmt,
+  RouteStmt,
+  SendsStmt,
+  ServiceDef,
+  ServiceRefStmt,
+  SubdomainDef,
+  ToClause,
+  WritesToStmt,
+} from "./generated/ast.js";
+
+// ---------------------------------------------------------------------------
+// String helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip surrounding double-quotes from a STRING terminal value.
+ * Langium keeps the quotes in the parsed string – this helper removes them.
+ */
+export function stripQuotes(s: string): string {
+  if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+// ---------------------------------------------------------------------------
+// Common body helpers
+// ---------------------------------------------------------------------------
+
+/** Return the first VersionStmt value found in `body`, or `undefined`. */
+export function getVersion(body: AstNode[]): string | undefined {
+  const stmt = body.find(isVersionStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first NameStmt value (quotes stripped) found in `body`, or `undefined`. */
+export function getName(body: AstNode[]): string | undefined {
+  const stmt = body.find(isNameStmt);
+  return stmt ? stripQuotes(stmt.value) : undefined;
+}
+
+/** Return the first SummaryStmt value (quotes stripped) found in `body`, or `undefined`. */
+export function getSummary(body: AstNode[]): string | undefined {
+  const stmt = body.find(isSummaryStmt);
+  return stmt ? stripQuotes(stmt.value) : undefined;
+}
+
+/** Collect all OwnerStmt `ownerRef` values from `body`. */
+export function getOwners(body: AstNode[]): string[] {
+  return body.filter(isOwnerStmt).map((s) => s.ownerRef);
+}
+
+/** Return the first DeprecatedStmt value found in `body`, or `undefined`. */
+export function getDeprecated(body: AstNode[]): boolean | undefined {
+  const stmt = body.find(isDeprecatedStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first DraftStmt value found in `body`, or `undefined`. */
+export function getDraft(body: AstNode[]): boolean | undefined {
+  const stmt = body.find(isDraftStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first LegendStmt value found in `body`, or `undefined`. */
+export function getLegend(body: AstNode[]): boolean | undefined {
+  const stmt = body.find(isLegendStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first SearchStmt value found in `body`, or `undefined`. */
+export function getSearch(body: AstNode[]): boolean | undefined {
+  const stmt = body.find(isSearchStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first ToolbarStmt value found in `body`, or `undefined`. */
+export function getToolbar(body: AstNode[]): boolean | undefined {
+  const stmt = body.find(isToolbarStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first FocusModeStmt value found in `body`, or `undefined`. */
+export function getFocusMode(body: AstNode[]): boolean | undefined {
+  const stmt = body.find(isFocusModeStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first AnimatedStmt value found in `body`, or `undefined`. */
+export function getAnimated(body: AstNode[]): boolean | undefined {
+  const stmt = body.find(isAnimatedStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first StyleStmt value found in `body`, or `undefined`. */
+export function getStyle(body: AstNode[]): string | undefined {
+  const stmt = body.find(isStyleStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first SchemaStmt value (quotes stripped) found in `body`, or `undefined`. */
+export function getSchema(body: AstNode[]): string | undefined {
+  const stmt = body.find(isSchemaStmt);
+  return stmt ? stripQuotes(stmt.value) : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Domain body helpers
+// ---------------------------------------------------------------------------
+
+/** Return all inline ServiceDef nodes from `body`. */
+export function getServices(body: AstNode[]): ServiceDef[] {
+  return body.filter(isServiceDef);
+}
+
+/** Return all SubdomainDef nodes from `body`. */
+export function getSubdomains(body: AstNode[]): SubdomainDef[] {
+  return body.filter(isSubdomainDef);
+}
+
+/** Return all inline ContainerDef nodes from `body`. */
+export function getContainers(body: AstNode[]): ContainerDef[] {
+  return body.filter(isContainerDef);
+}
+
+/** Return all FlowRefStmt nodes from `body`. */
+export function getFlowRefs(body: AstNode[]): FlowRefStmt[] {
+  return body.filter(isFlowRefStmt);
+}
+
+/** Return all inline FlowDef nodes from `body`. */
+export function getFlows(body: AstNode[]): FlowDef[] {
+  return body.filter(isFlowDef);
+}
+
+/** Return all DataProductRefStmt nodes from `body`. */
+export function getDataProductRefs(body: AstNode[]): DataProductRefStmt[] {
+  return body.filter(isDataProductRefStmt);
+}
+
+/** Return all SendsStmt nodes from `body`. */
+export function getSends(body: AstNode[]): SendsStmt[] {
+  return body.filter(isSendsStmt);
+}
+
+/** Return all ReceivesStmt nodes from `body`. */
+export function getReceives(body: AstNode[]): ReceivesStmt[] {
+  return body.filter(isReceivesStmt);
+}
+
+/** Return all Annotation nodes from `body`. */
+export function getAnnotations(body: AstNode[]): Annotation[] {
+  return body.filter(isAnnotation);
+}
+
+// ---------------------------------------------------------------------------
+// Service body helpers
+// ---------------------------------------------------------------------------
+
+/** Return all WritesToStmt nodes from `body`. */
+export function getWritesToRefs(body: AstNode[]): WritesToStmt[] {
+  return body.filter(isWritesToStmt);
+}
+
+/** Return all ReadsFromStmt nodes from `body`. */
+export function getReadsFromRefs(body: AstNode[]): ReadsFromStmt[] {
+  return body.filter(isReadsFromStmt);
+}
+
+// ---------------------------------------------------------------------------
+// Message body helpers
+// ---------------------------------------------------------------------------
+
+/** Return all ChannelRefStmt nodes from `body`. */
+export function getChannelRefs(body: AstNode[]): ChannelRefStmt[] {
+  return body.filter(isChannelRefStmt);
+}
+
+// ---------------------------------------------------------------------------
+// Channel body helpers
+// ---------------------------------------------------------------------------
+
+/** Return the first AddressStmt value (quotes stripped) from `body`, or `undefined`. */
+export function getAddress(body: AstNode[]): string | undefined {
+  const stmt = body.find(isAddressStmt);
+  return stmt ? stripQuotes(stmt.value) : undefined;
+}
+
+/** Collect all ProtocolStmt values (quotes stripped) from `body`. */
+export function getProtocols(body: AstNode[]): string[] {
+  return body.filter(isProtocolStmt).map((s) => stripQuotes(s.value));
+}
+
+/** Return all ParameterDecl nodes from `body`. */
+export function getParameters(body: AstNode[]): ParameterDecl[] {
+  return body.filter(isParameterDecl);
+}
+
+/** Return all RouteStmt nodes from `body`. */
+export function getRoutes(body: AstNode[]): RouteStmt[] {
+  return body.filter(isRouteStmt);
+}
+
+// ---------------------------------------------------------------------------
+// Relationship helpers
+// ---------------------------------------------------------------------------
+
+/** Return all ServiceRefStmt nodes from `body`. */
+export function getServiceRefs(body: AstNode[]): ServiceRefStmt[] {
+  return body.filter(isServiceRefStmt);
+}
+
+/** Return all DomainRefStmt nodes from `body`. */
+export function getDomainRefs(body: AstNode[]): DomainRefStmt[] {
+  return body.filter(isDomainRefStmt);
+}
+
+/** Return all ContainerRefStmt nodes from `body`. */
+export function getContainerRefs(body: AstNode[]): ContainerRefStmt[] {
+  return body.filter(isContainerRefStmt);
+}
+
+// ---------------------------------------------------------------------------
+// Container body helpers
+// ---------------------------------------------------------------------------
+
+/** Return the first ContainerTypeStmt value from `body`, or `undefined`. */
+export function getContainerType(body: AstNode[]): string | undefined {
+  const stmt = body.find(isContainerTypeStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first TechnologyStmt value (quotes stripped) from `body`, or `undefined`. */
+export function getTechnology(body: AstNode[]): string | undefined {
+  const stmt = body.find(isTechnologyStmt);
+  return stmt ? stripQuotes(stmt.value) : undefined;
+}
+
+/** Return the first AuthoritativeStmt value from `body`, or `undefined`. */
+export function getAuthoritative(body: AstNode[]): boolean | undefined {
+  const stmt = body.find(isAuthoritativeStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first AccessModeStmt value from `body`, or `undefined`. */
+export function getAccessMode(body: AstNode[]): string | undefined {
+  const stmt = body.find(isAccessModeStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first ClassificationStmt value from `body`, or `undefined`. */
+export function getClassification(body: AstNode[]): string | undefined {
+  const stmt = body.find(isClassificationStmt);
+  return stmt ? stmt.value : undefined;
+}
+
+/** Return the first ResidencyStmt value (quotes stripped) from `body`, or `undefined`. */
+export function getResidency(body: AstNode[]): string | undefined {
+  const stmt = body.find(isResidencyStmt);
+  return stmt ? stripQuotes(stmt.value) : undefined;
+}
+
+/** Return the first RetentionStmt value (quotes stripped) from `body`, or `undefined`. */
+export function getRetention(body: AstNode[]): string | undefined {
+  const stmt = body.find(isRetentionStmt);
+  return stmt ? stripQuotes(stmt.value) : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Data-product body helpers
+// ---------------------------------------------------------------------------
+
+/** Return all InputStmt nodes from `body`. */
+export function getInputs(body: AstNode[]): InputStmt[] {
+  return body.filter(isInputStmt);
+}
+
+/** Return all OutputStmt nodes from `body`. */
+export function getOutputs(body: AstNode[]): OutputStmt[] {
+  return body.filter(isOutputStmt);
+}
+
+// ---------------------------------------------------------------------------
+// Flow body helpers
+// ---------------------------------------------------------------------------
+
+/** Return all FlowEntryChain nodes from `body`. */
+export function getFlowEntryChains(body: AstNode[]): FlowEntryChain[] {
+  return body.filter(isFlowEntryChain);
+}
+
+/** Return all FlowWhenBlock nodes from `body`. */
+export function getFlowWhenBlocks(body: AstNode[]): FlowWhenBlock[] {
+  return body.filter(isFlowWhenBlock);
+}
+
+// ---------------------------------------------------------------------------
+// Sends / Receives body helpers
+// ---------------------------------------------------------------------------
+
+/** Return the first ToClause from `body`, or `undefined`. */
+export function getToClause(body: AstNode[]): ToClause | undefined {
+  return body.find(isToClause) as ToClause | undefined;
+}
+
+/** Return the first FromClause from `body`, or `undefined`. */
+export function getFromClause(body: AstNode[]): FromClause | undefined {
+  return body.find(isFromClause) as FromClause | undefined;
+}
diff --git a/packages/language-server/src/browser.ts b/packages/language-server/src/browser.ts
new file mode 100644
index 000000000..f73d34d3a
--- /dev/null
+++ b/packages/language-server/src/browser.ts
@@ -0,0 +1,72 @@
+/**
+ * Browser-safe exports from the language server.
+ * This entry point excludes Node.js-only modules (EcCompletionProvider, Langium LSP).
+ * Use `@eventcatalog/language-server/browser` in browser environments (playground, etc.).
+ */
+
+// Completion data (snippets, annotations, context suggestions)
+export {
+  RESOURCE_KEYWORDS,
+  COMMON_PROPS,
+  ANNOTATION_SUGGESTIONS,
+  CONTEXT_SUGGESTIONS,
+  MESSAGE_TYPE_PLURAL,
+} from "./completion-data.js";
+export type { Suggestion } from "./completion-data.js";
+
+// Completion utils (browser-safe helpers)
+export {
+  collectRegexMatches,
+  collectChannelNames,
+  collectMessageNames,
+  extractResourceVersions,
+  extractResourceNamesFromText,
+  parseSpecAuto,
+  findEnclosingResource,
+} from "./completion-utils.js";
+export type { ParsedSpecResult } from "./completion-utils.js";
+
+// Core services (browser-safe — no LSP/CompletionProvider dependency)
+export { createEcServices } from "./ec-module.js";
+export type { EcServices, EcAddedServices } from "./ec-module.js";
+
+// AST, graph, compiler, formatter
+export * from "./generated/ast.js";
+export { astToGraph } from "./graph.js";
+export type { GraphNode, GraphEdge, DslGraph } from "./graph-types.js";
+export { compile } from "./compiler.js";
+export type { CompiledOutput, CompileOptions } from "./compiler.js";
+export * from "./ast-utils.js";
+export { formatEc } from "./formatter.js";
+
+// Resolvers
+export {
+  parseSpec,
+  extractMessages,
+  extractChannels,
+  extractService,
+  messageToEc,
+  channelToEc,
+  serviceToEc,
+  parseOpenApiSpec,
+  extractOpenApiService,
+  openApiServiceToEc,
+  openApiMessageToEc,
+  resolveSpecImports,
+  resolveSpecImportsAsync,
+  detectSpecType,
+  isSpecFile,
+  resolveAsyncApiImports,
+  resolveAsyncApiImportsAsync,
+} from "./resolvers/index.js";
+export type { ParsedOpenApiSpec } from "./resolvers/index.js";
+export type {
+  SpecMessage,
+  SpecChannel,
+  SpecOperation,
+  SpecService,
+  ResourceType,
+  ResolveError,
+  SpecResolveResult,
+  FetchFn,
+} from "./resolvers/index.js";
diff --git a/packages/language-server/src/compiler.ts b/packages/language-server/src/compiler.ts
new file mode 100644
index 000000000..28caf7f86
--- /dev/null
+++ b/packages/language-server/src/compiler.ts
@@ -0,0 +1,995 @@
+import type { AstNode } from "langium";
+import type {
+  Program,
+  ResourceDefinition,
+  DomainDef,
+  ServiceDef,
+  EventDef,
+  CommandDef,
+  QueryDef,
+  ChannelDef,
+  ContainerDef,
+  DataProductDef,
+  FlowDef,
+  DiagramDef,
+  UserDef,
+  TeamDef,
+  VisualizerDef,
+  Annotation,
+  SendsStmt,
+  ReceivesStmt,
+  FlowRef,
+  NamedAnnotationArg,
+  PositionalAnnotationArg,
+  ResourceAnnotationBlockItem,
+  KeyValueAnnotationBlockItem,
+} from "./generated/ast.js";
+import {
+  isDomainDef,
+  isServiceDef,
+  isEventDef,
+  isCommandDef,
+  isQueryDef,
+  isChannelDef,
+  isContainerDef,
+  isDataProductDef,
+  isFlowDef,
+  isDiagramDef,
+  isUserDef,
+  isTeamDef,
+  isVisualizerDef,
+  isActorDef,
+  isExternalSystemDef,
+  isNamedAnnotationArg,
+  isPositionalAnnotationArg,
+  isResourceAnnotationBlockItem,
+  isKeyValueAnnotationBlockItem,
+  isParameterDescriptionProp,
+  isParameterDefaultProp,
+  isParameterEnumProp,
+  isParameterExamplesProp,
+  isToClause,
+  isFromClause,
+  isStringAnnotationValue,
+  isIdAnnotationValue,
+  isNumberAnnotationValue,
+  isBoolAnnotationValue,
+  isVersionAnnotationValue,
+  isKeywordAnnotationValue,
+} from "./generated/ast.js";
+import {
+  stripQuotes,
+  getVersion,
+  getName,
+  getSummary,
+  getOwners,
+  getDeprecated,
+  getDraft,
+  getSchema,
+  getServices,
+  getSubdomains,
+  getFlowRefs,
+  getDataProductRefs,
+  getSends,
+  getReceives,
+  getWritesToRefs,
+  getReadsFromRefs,
+  getChannelRefs,
+  getAnnotations,
+  getAddress,
+  getProtocols,
+  getParameters,
+  getRoutes,
+  getContainerType,
+  getTechnology,
+  getAuthoritative,
+  getAccessMode,
+  getClassification,
+  getResidency,
+  getRetention,
+  getInputs,
+  getOutputs,
+  getFlowEntryChains,
+  getFlowWhenBlocks,
+  getServiceRefs,
+  getDomainRefs,
+  getToClause,
+  getFromClause,
+} from "./ast-utils.js";
+
+export interface CompiledOutput {
+  path: string;
+  content: string;
+}
+
+export interface CompileOptions {
+  nested?: boolean;
+}
+
+export function compile(
+  program: Program,
+  options?: CompileOptions,
+): CompiledOutput[] {
+  const nested = options?.nested ?? false;
+  const outputs: CompiledOutput[] = [];
+  for (const def of program.definitions) {
+    compileDefinition(def, outputs, nested, "");
+  }
+  return outputs;
+}
+
+function compileDefinition(
+  def: ResourceDefinition,
+  outputs: CompiledOutput[],
+  nested: boolean,
+  parentPath: string,
+): void {
+  if (isDomainDef(def)) compileDomain(def, outputs, nested);
+  else if (isServiceDef(def)) {
+    compileService(def, outputs, nested, parentPath);
+    compileInlineMessages(def, outputs, nested, parentPath);
+  } else if (isEventDef(def))
+    compileMessage(def, "events", outputs, nested, parentPath);
+  else if (isCommandDef(def))
+    compileMessage(def, "commands", outputs, nested, parentPath);
+  else if (isQueryDef(def))
+    compileMessage(def, "queries", outputs, nested, parentPath);
+  else if (isChannelDef(def)) compileChannel(def, outputs, nested, parentPath);
+  else if (isContainerDef(def))
+    compileContainer(def, outputs, nested, parentPath);
+  else if (isDataProductDef(def)) compileDataProduct(def, outputs);
+  else if (isFlowDef(def)) compileFlow(def, outputs);
+  else if (isDiagramDef(def)) compileDiagram(def, outputs);
+  else if (isUserDef(def)) compileUser(def, outputs);
+  else if (isTeamDef(def)) compileTeam(def, outputs);
+  else if (isVisualizerDef(def)) compileVisualizer(def, outputs, nested);
+  // ActorDef and ExternalSystemDef are flow-only — no markdown output
+}
+
+// --- YAML helpers ---
+
+function yamlValue(val: unknown): string {
+  if (typeof val === "string") return JSON.stringify(val);
+  if (typeof val === "boolean" || typeof val === "number") return String(val);
+  return String(val);
+}
+
+function buildFrontmatter(fields: Record<string, unknown>): string {
+  const lines: string[] = ["---"];
+  writeFrontmatterFields(lines, fields, 0);
+  lines.push("---");
+  return lines.join("\n");
+}
+
+function writeFrontmatterFields(
+  lines: string[],
+  fields: Record<string, unknown>,
+  indent: number,
+): void {
+  const prefix = "  ".repeat(indent);
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) {
+      if (value.length === 0) continue;
+      lines.push(`${prefix}${key}:`);
+      for (const item of value) {
+        if (typeof item === "object" && item !== null) {
+          const entries = Object.entries(item).filter(
+            ([, v]) => v !== undefined && v !== null,
+          );
+          if (entries.length > 0) {
+            const [firstKey, firstVal] = entries[0];
+            if (typeof firstVal === "object" && firstVal !== null) {
+              lines.push(`${prefix}  - ${firstKey}:`);
+              writeFrontmatterFields(
+                lines,
+                firstVal as Record<string, unknown>,
+                indent + 3,
+              );
+            } else {
+              lines.push(`${prefix}  - ${firstKey}: ${yamlValue(firstVal)}`);
+            }
+            for (let i = 1; i < entries.length; i++) {
+              const [k, v] = entries[i];
+              if (typeof v === "object" && v !== null && !Array.isArray(v)) {
+                lines.push(`${prefix}    ${k}:`);
+                writeFrontmatterFields(
+                  lines,
+                  v as Record<string, unknown>,
+                  indent + 3,
+                );
+              } else if (Array.isArray(v)) {
+                lines.push(`${prefix}    ${k}:`);
+                for (const subItem of v) {
+                  if (typeof subItem === "object" && subItem !== null) {
+                    const subEntries = Object.entries(subItem).filter(
+                      ([, sv]) => sv !== undefined && sv !== null,
+                    );
+                    if (subEntries.length > 0) {
+                      const [sk, sv] = subEntries[0];
+                      lines.push(`${prefix}      - ${sk}: ${yamlValue(sv)}`);
+                      for (let j = 1; j < subEntries.length; j++) {
+                        const [sk2, sv2] = subEntries[j];
+                        lines.push(
+                          `${prefix}        ${sk2}: ${yamlValue(sv2)}`,
+                        );
+                      }
+                    }
+                  } else {
+                    lines.push(`${prefix}      - ${yamlValue(subItem)}`);
+                  }
+                }
+              } else {
+                lines.push(`${prefix}    ${k}: ${yamlValue(v)}`);
+              }
+            }
+          }
+        } else {
+          lines.push(`${prefix}  - ${yamlValue(item)}`);
+        }
+      }
+    } else if (typeof value === "object" && value !== null) {
+      lines.push(`${prefix}${key}:`);
+      writeFrontmatterFields(
+        lines,
+        value as Record<string, unknown>,
+        indent + 1,
+      );
+    } else {
+      lines.push(`${prefix}${key}: ${yamlValue(value)}`);
+    }
+  }
+}
+
+// --- Annotation mapping ---
+
+function getAnnotationArgValue(
+  arg: NamedAnnotationArg | PositionalAnnotationArg,
+): string | boolean | number {
+  const v = arg.value;
+  if (isStringAnnotationValue(v)) return stripQuotes(v.value);
+  if (isIdAnnotationValue(v)) return v.value;
+  if (isNumberAnnotationValue(v)) return parseInt(v.value, 10);
+  if (isBoolAnnotationValue(v)) return v.value;
+  if (isVersionAnnotationValue(v)) return v.value;
+  if (isKeywordAnnotationValue(v)) return v.value;
+  return "";
+}
+
+function mapAnnotations(annotations: Annotation[]): Record<string, unknown> {
+  if (annotations.length === 0) return {};
+  const result: Record<string, unknown> = {};
+
+  for (const ann of annotations) {
+    switch (ann.name) {
+      case "badge": {
+        if (!result.badges) result.badges = [];
+        const badge: Record<string, string> = {};
+        const contentArg = ann.args.find((a) => isPositionalAnnotationArg(a));
+        if (contentArg)
+          badge.content = String(getAnnotationArgValue(contentArg));
+        const bgArg = ann.args.find(
+          (a) => isNamedAnnotationArg(a) && a.key === "bg",
+        ) as NamedAnnotationArg | undefined;
+        if (bgArg) badge.backgroundColor = String(getAnnotationArgValue(bgArg));
+        const textArg = ann.args.find(
+          (a) => isNamedAnnotationArg(a) && a.key === "text",
+        ) as NamedAnnotationArg | undefined;
+        if (textArg) badge.textColor = String(getAnnotationArgValue(textArg));
+        const urlArg = ann.args.find(
+          (a) => isNamedAnnotationArg(a) && a.key === "url",
+        ) as NamedAnnotationArg | undefined;
+        if (urlArg) badge.url = String(getAnnotationArgValue(urlArg));
+        (result.badges as Record<string, string>[]).push(badge);
+        break;
+      }
+      case "note": {
+        if (!result.notes) result.notes = [];
+        const note: Record<string, string> = {};
+        const noteContentArg = ann.args.find((a) =>
+          isPositionalAnnotationArg(a),
+        );
+        if (noteContentArg)
+          note.content = String(getAnnotationArgValue(noteContentArg));
+        const authorArg = ann.args.find(
+          (a) => isNamedAnnotationArg(a) && a.key === "author",
+        ) as NamedAnnotationArg | undefined;
+        if (authorArg) note.author = String(getAnnotationArgValue(authorArg));
+        const priorityArg = ann.args.find(
+          (a) => isNamedAnnotationArg(a) && a.key === "priority",
+        ) as NamedAnnotationArg | undefined;
+        if (priorityArg)
+          note.priority = String(getAnnotationArgValue(priorityArg));
+        (result.notes as Record<string, string>[]).push(note);
+        break;
+      }
+      case "repository": {
+        const repo: Record<string, string> = {};
+        const urlArg = ann.args.find(
+          (a) =>
+            (isNamedAnnotationArg(a) && a.key === "url") ||
+            isPositionalAnnotationArg(a),
+        );
+        if (urlArg) repo.url = String(getAnnotationArgValue(urlArg));
+        const langArg = ann.args.find(
+          (a) => isNamedAnnotationArg(a) && a.key === "language",
+        ) as NamedAnnotationArg | undefined;
+        if (langArg) repo.language = String(getAnnotationArgValue(langArg));
+        result.repository = repo;
+        break;
+      }
+      case "externalId": {
+        const idArg = ann.args.find((a) => isPositionalAnnotationArg(a));
+        if (idArg) result.externalId = String(getAnnotationArgValue(idArg));
+        break;
+      }
+      case "specification":
+      case "specifications": {
+        if (!result.specifications) result.specifications = [];
+        const spec: Record<string, string> = {};
+        const typeArg = ann.args.find(
+          (a) => isNamedAnnotationArg(a) && a.key === "type",
+        ) as NamedAnnotationArg | undefined;
+        if (typeArg) spec.type = String(getAnnotationArgValue(typeArg));
+        const pathArg = ann.args.find(
+          (a) => isNamedAnnotationArg(a) && a.key === "path",
+        ) as NamedAnnotationArg | undefined;
+        if (pathArg) spec.path = String(getAnnotationArgValue(pathArg));
+        const titleArg = ann.args.find(
+          (a) => isNamedAnnotationArg(a) && a.key === "title",
+        ) as NamedAnnotationArg | undefined;
+        if (titleArg) spec.title = String(getAnnotationArgValue(titleArg));
+        const urlArg = ann.args.find(
+          (a) =>
+            (isNamedAnnotationArg(a) && a.key === "url") ||
+            isPositionalAnnotationArg(a),
+        );
+        if (urlArg && !spec.path)
+          spec.url = String(getAnnotationArgValue(urlArg));
+        (result.specifications as Record<string, string>[]).push(spec);
+        break;
+      }
+      case "sidebar": {
+        const sidebar: Record<string, unknown> = {};
+        for (const arg of ann.args) {
+          if (isNamedAnnotationArg(arg))
+            sidebar[arg.key] = getAnnotationArgValue(arg);
+        }
+        if (ann.block) {
+          for (const item of ann.block) {
+            if (isKeyValueAnnotationBlockItem(item)) {
+              sidebar[item.key] = item.value;
+            }
+          }
+        }
+        result.sidebar = sidebar;
+        break;
+      }
+      case "styles": {
+        const styles: Record<string, unknown> = {};
+        for (const arg of ann.args) {
+          if (isNamedAnnotationArg(arg))
+            styles[arg.key] = getAnnotationArgValue(arg);
+        }
+        result.styles = styles;
+        break;
+      }
+      default: {
+        if (ann.args.length === 1 && isPositionalAnnotationArg(ann.args[0])) {
+          result[ann.name] = getAnnotationArgValue(ann.args[0]);
+        } else if (ann.args.length > 0) {
+          const obj: Record<string, unknown> = {};
+          for (const arg of ann.args) {
+            if (isNamedAnnotationArg(arg))
+              obj[arg.key] = getAnnotationArgValue(arg);
+          }
+          result[ann.name] = obj;
+        }
+        break;
+      }
+    }
+  }
+
+  return result;
+}
+
+function commonFrontmatter(
+  id: string,
+  body: AstNode[],
+): Record<string, unknown> {
+  const fm: Record<string, unknown> = {
+    id,
+    name: getName(body) || id,
+  };
+  const version = getVersion(body);
+  if (version) fm.version = version;
+  const owners = getOwners(body);
+  if (owners.length > 0) {
+    fm.owners = owners;
+  }
+  const schema = getSchema(body);
+  if (schema) fm.schemaPath = schema;
+  const deprecated = getDeprecated(body);
+  if (deprecated !== undefined) fm.deprecated = deprecated;
+  const draft = getDraft(body);
+  if (draft !== undefined) fm.draft = draft;
+
+  const annFields = mapAnnotations(getAnnotations(body));
+  Object.assign(fm, annFields);
+
+  return fm;
+}
+
+function withSummary(
+  fm: Record<string, unknown>,
+  body: AstNode[],
+): Record<string, unknown> {
+  const summary = getSummary(body);
+  if (summary) fm.summary = summary;
+  return fm;
+}
+
+function makeOutput(path: string, fm: Record<string, unknown>): CompiledOutput {
+  const frontmatter = buildFrontmatter(fm);
+  return { path, content: `${frontmatter}\n` };
+}
+
+// Build a versioned output path: "<folder>/<name>/versioned/<version>/index.md"
+// Falls back to "<folder>/<name>/index.md" when no version is present.
+function versionedPath(folder: string, name: string, body: AstNode[]): string {
+  const version = getVersion(body);
+  if (version) return `${folder}/${name}/versioned/${version}/index.md`;
+  return `${folder}/${name}/index.md`;
+}
+
+// --- Resource compilers ---
+
+function compileDomain(
+  domain: DomainDef,
+  outputs: CompiledOutput[],
+  nested: boolean,
+): void {
+  const body = domain.body as AstNode[];
+  const fm = withSummary(commonFrontmatter(domain.name, body), body);
+
+  // Add services pointers
+  const services = getServices(body);
+  if (services.length > 0) {
+    fm.services = services.map((svc) => {
+      const ref: Record<string, unknown> = { id: svc.name };
+      const v = getVersion(svc.body as AstNode[]);
+      if (v) ref.version = v;
+      return ref;
+    });
+  }
+
+  // Add subdomain pointers (listed as "domains" in frontmatter)
+  const subdomains = getSubdomains(body);
+  if (subdomains.length > 0) {
+    fm.domains = subdomains.map((sub) => {
+      const ref: Record<string, unknown> = { id: sub.name };
+      const v = getVersion(sub.body as AstNode[]);
+      if (v) ref.version = v;
+      return ref;
+    });
+  }
+
+  outputs.push(makeOutput(versionedPath("domains", domain.name, body), fm));
+
+  const domainPath = nested ? `domains/${domain.name}` : "";
+
+  for (const svc of services) {
+    compileService(svc, outputs, nested, domainPath);
+    compileInlineMessages(svc, outputs, nested, domainPath);
+  }
+
+  for (const ch of body.filter((n) => isChannelDef(n)) as ChannelDef[]) {
+    compileChannel(ch, outputs, nested, domainPath);
+  }
+
+  for (const cont of body.filter((n) => isContainerDef(n)) as ContainerDef[]) {
+    compileContainer(cont, outputs, nested, domainPath);
+  }
+
+  for (const sub of subdomains) {
+    const subBody = sub.body as AstNode[];
+    const subFm = withSummary(commonFrontmatter(sub.name, subBody), subBody);
+
+    // Add services pointers to subdomain
+    const subServices = getServices(subBody);
+    if (subServices.length > 0) {
+      subFm.services = subServices.map((svc) => {
+        const ref: Record<string, unknown> = { id: svc.name };
+        const v = getVersion(svc.body as AstNode[]);
+        if (v) ref.version = v;
+        return ref;
+      });
+    }
+
+    const subdomainFolder = nested
+      ? `domains/${domain.name}/subdomains`
+      : `domains/${domain.name}/domains`;
+    outputs.push(
+      makeOutput(versionedPath(subdomainFolder, sub.name, subBody), subFm),
+    );
+
+    const subdomainPath = nested
+      ? `domains/${domain.name}/subdomains/${sub.name}`
+      : "";
+
+    for (const svc of subServices) {
+      compileService(svc, outputs, nested, subdomainPath);
+      compileInlineMessages(svc, outputs, nested, subdomainPath);
+    }
+  }
+}
+
+function compileService(
+  svc: ServiceDef,
+  outputs: CompiledOutput[],
+  nested: boolean,
+  parentPath: string,
+): void {
+  const body = svc.body as AstNode[];
+  const fm = commonFrontmatter(svc.name, body);
+  const sends = getSends(body);
+  if (sends.length > 0) {
+    fm.sends = sends.map((s) => buildMessageRef(s));
+  }
+  const receives = getReceives(body);
+  if (receives.length > 0) {
+    fm.receives = receives.map((r) => buildMessageRef(r));
+  }
+  const writesTo = getWritesToRefs(body);
+  if (writesTo.length > 0) {
+    fm.writesTo = writesTo.map((stmt) => buildResourceRef(stmt.ref));
+  }
+  const readsFrom = getReadsFromRefs(body);
+  if (readsFrom.length > 0) {
+    fm.readsFrom = readsFrom.map((stmt) => buildResourceRef(stmt.ref));
+  }
+  withSummary(fm, body);
+  const folder = nested && parentPath ? `${parentPath}/services` : "services";
+  outputs.push(makeOutput(versionedPath(folder, svc.name, body), fm));
+}
+
+function buildResourceRef(ref: {
+  name: string;
+  version?: string;
+}): Record<string, unknown> {
+  const out: Record<string, unknown> = { id: ref.name };
+  if (ref.version) out.version = ref.version;
+  return out;
+}
+
+function buildMessageRef(
+  clause: SendsStmt | ReceivesStmt,
+): Record<string, unknown> {
+  const ref: Record<string, unknown> = { id: clause.messageName };
+  if (clause.version) ref.version = clause.version;
+  // Check inline body for version
+  if (clause.body.length > 0) {
+    const inlineVersion = getVersion(clause.body as AstNode[]);
+    if (inlineVersion) ref.version = inlineVersion;
+  }
+  // Add channel routing (to/from) when present
+  if (clause.channelClause) {
+    const cc = clause.channelClause;
+    const channelRefs = cc.channels.map((ch) => {
+      const entry: Record<string, unknown> = { id: ch.channelName };
+      if (ch.channelVersion) entry.version = ch.channelVersion;
+      return entry;
+    });
+    if (cc.deliveryMode) {
+      for (const entry of channelRefs) {
+        entry.delivery_mode = cc.deliveryMode;
+      }
+    }
+    if (isToClause(cc)) {
+      ref.to = channelRefs;
+    } else if (isFromClause(cc)) {
+      ref.from = channelRefs;
+    }
+  }
+  return ref;
+}
+
+function compileInlineMessages(
+  svc: ServiceDef,
+  outputs: CompiledOutput[],
+  nested: boolean,
+  parentPath: string,
+): void {
+  const body = svc.body as AstNode[];
+  // Compute the service path to nest messages under
+  const servicePath =
+    nested && parentPath
+      ? `${parentPath}/services/${svc.name}`
+      : nested
+        ? `services/${svc.name}`
+        : "";
+  const allClauses = [...getSends(body), ...getReceives(body)];
+  for (const clause of allClauses) {
+    if (clause.body.length > 0) {
+      const inlineBody = clause.body as AstNode[];
+      const msgType = clause.messageType;
+      const msgFolder =
+        msgType === "event"
+          ? "events"
+          : msgType === "command"
+            ? "commands"
+            : "queries";
+      const folder =
+        nested && servicePath ? `${servicePath}/${msgFolder}` : msgFolder;
+      const fm = withSummary(
+        commonFrontmatter(clause.messageName, inlineBody),
+        inlineBody,
+      );
+      outputs.push(
+        makeOutput(versionedPath(folder, clause.messageName, inlineBody), fm),
+      );
+    }
+  }
+}
+
+function compileMessage(
+  msg: EventDef | CommandDef | QueryDef,
+  folder: string,
+  outputs: CompiledOutput[],
+  nested: boolean,
+  parentPath: string,
+): void {
+  const body = msg.body as AstNode[];
+  const fm = withSummary(commonFrontmatter(msg.name, body), body);
+  const resolvedFolder =
+    nested && parentPath ? `${parentPath}/${folder}` : folder;
+  outputs.push(makeOutput(versionedPath(resolvedFolder, msg.name, body), fm));
+}
+
+function compileChannel(
+  ch: ChannelDef,
+  outputs: CompiledOutput[],
+  nested: boolean = false,
+  parentPath: string = "",
+): void {
+  const body = ch.body as AstNode[];
+  const fm = commonFrontmatter(ch.name, body);
+  const address = getAddress(body);
+  if (address) fm.address = address;
+  const protocols = getProtocols(body);
+  if (protocols.length > 0) fm.protocols = protocols;
+  const params = getParameters(body);
+  if (params.length > 0) {
+    fm.parameters = params.map((p) => {
+      const param: Record<string, unknown> = { name: p.name };
+      for (const prop of p.props) {
+        if (isParameterDescriptionProp(prop))
+          param.description = stripQuotes(prop.value);
+        if (isParameterDefaultProp(prop))
+          param.default = stripQuotes(prop.value);
+        if (isParameterEnumProp(prop))
+          param.enum = prop.value.items.map(stripQuotes);
+        if (isParameterExamplesProp(prop))
+          param.examples = prop.value.items.map(stripQuotes);
+      }
+      return param;
+    });
+  }
+  withSummary(fm, body);
+  const folder = nested && parentPath ? `${parentPath}/channels` : "channels";
+  outputs.push(makeOutput(versionedPath(folder, ch.name, body), fm));
+}
+
+function compileContainer(
+  cont: ContainerDef,
+  outputs: CompiledOutput[],
+  nested: boolean = false,
+  parentPath: string = "",
+): void {
+  const body = cont.body as AstNode[];
+  const fm = commonFrontmatter(cont.name, body);
+  const ct = getContainerType(body);
+  if (ct) fm.container_type = ct;
+  const tech = getTechnology(body);
+  if (tech) fm.technology = tech;
+  const auth = getAuthoritative(body);
+  if (auth !== undefined) fm.authoritative = auth;
+  const am = getAccessMode(body);
+  if (am) fm.access_mode = am;
+  const cl = getClassification(body);
+  if (cl) fm.classification = cl;
+  const res = getResidency(body);
+  if (res) fm.residency = res;
+  const ret = getRetention(body);
+  if (ret) fm.retention = ret;
+  withSummary(fm, body);
+  const folder =
+    nested && parentPath ? `${parentPath}/containers` : "containers";
+  outputs.push(makeOutput(versionedPath(folder, cont.name, body), fm));
+}
+
+function compileDataProduct(
+  dp: DataProductDef,
+  outputs: CompiledOutput[],
+): void {
+  const body = dp.body as AstNode[];
+  const fm = commonFrontmatter(dp.name, body);
+  const inputs = getInputs(body);
+  if (inputs.length > 0) {
+    fm.inputs = inputs.map((inp) => ({
+      id: inp.ref.name,
+      version: inp.ref.version,
+    }));
+  }
+  const outs = getOutputs(body);
+  if (outs.length > 0) {
+    fm.outputs = outs.map((out) => {
+      const o: Record<string, unknown> = { id: out.name };
+      if (out.contract) {
+        o.contract = {
+          path: stripQuotes(out.contract.path),
+          name: stripQuotes(out.contract.contractName),
+          ...(out.contract.contractType
+            ? { type: stripQuotes(out.contract.contractType) }
+            : {}),
+        };
+      }
+      return o;
+    });
+  }
+  withSummary(fm, body);
+  outputs.push(makeOutput(versionedPath("data-products", dp.name, body), fm));
+}
+
+function compileFlow(flow: FlowDef, outputs: CompiledOutput[]): void {
+  const body = flow.body as AstNode[];
+  const fm = commonFrontmatter(flow.name, body);
+  const entryChains = getFlowEntryChains(body);
+  const whenBlocks = getFlowWhenBlocks(body);
+  if (entryChains.length > 0 || whenBlocks.length > 0) {
+    const steps = compileFlowBody(entryChains, whenBlocks);
+    if (steps.length > 0) {
+      fm.steps = steps;
+    }
+  }
+  withSummary(fm, body);
+  outputs.push(makeOutput(versionedPath("flows", flow.name, body), fm));
+}
+
+function flowRefToStep(ref: FlowRef): Record<string, unknown> {
+  return {
+    id: ref.name,
+    title: ref.label ? stripQuotes(ref.label) : ref.name,
+  };
+}
+
+function ensureStep(
+  stepMap: Map<string, Record<string, unknown>>,
+  nextMap: Map<string, Array<{ id: string; label?: string }>>,
+  ref: FlowRef,
+): void {
+  if (!stepMap.has(ref.name)) {
+    stepMap.set(ref.name, flowRefToStep(ref));
+  }
+  if (!nextMap.has(ref.name)) {
+    nextMap.set(ref.name, []);
+  }
+}
+
+function addNext(
+  nextMap: Map<string, Array<{ id: string; label?: string }>>,
+  fromId: string,
+  toId: string,
+  label?: string,
+): void {
+  const nexts = nextMap.get(fromId)!;
+  if (!nexts.some((n) => n.id === toId && n.label === label)) {
+    nexts.push({ id: toId, ...(label ? { label } : {}) });
+  }
+}
+
+function compileFlowBody(
+  entryChains: import("./generated/ast.js").FlowEntryChain[],
+  whenBlocks: import("./generated/ast.js").FlowWhenBlock[],
+): Record<string, unknown>[] {
+  const stepMap = new Map<string, Record<string, unknown>>();
+  const nextMap = new Map<string, Array<{ id: string; label?: string }>>();
+
+  // Process entry chains (arrow sequences without 'when')
+  for (const chain of entryChains) {
+    const allRefs = [...chain.sources, ...chain.targets];
+    for (const ref of allRefs) {
+      ensureStep(stepMap, nextMap, ref);
+    }
+    const firstTarget = chain.targets[0];
+    if (firstTarget) {
+      for (const src of chain.sources) {
+        addNext(nextMap, src.name, firstTarget.name);
+      }
+    }
+    for (let i = 0; i < chain.targets.length - 1; i++) {
+      addNext(nextMap, chain.targets[i].name, chain.targets[i + 1].name);
+    }
+  }
+
+  // Process when blocks
+  for (const block of whenBlocks) {
+    // Ensure trigger refs exist
+    for (const trigger of block.triggers) {
+      ensureStep(stepMap, nextMap, trigger);
+    }
+
+    // Process each action in the when block
+    for (const action of block.actions) {
+      ensureStep(stepMap, nextMap, action.ref);
+
+      // Triggers connect to each action
+      for (const trigger of block.triggers) {
+        addNext(nextMap, trigger.name, action.ref.name);
+      }
+
+      // Action outputs (labeled or unlabeled)
+      for (const output of action.outputs) {
+        ensureStep(stepMap, nextMap, output.target);
+        addNext(
+          nextMap,
+          action.ref.name,
+          output.target.name,
+          output.label ? stripQuotes(output.label) : undefined,
+        );
+      }
+    }
+  }
+
+  // Build final steps array
+  const steps: Record<string, unknown>[] = [];
+  for (const [, step] of stepMap) {
+    const id = step.id as string;
+    const nexts = nextMap.get(id) || [];
+    if (nexts.length === 1 && !nexts[0].label) {
+      step.next_step = { id: nexts[0].id };
+    } else if (nexts.length > 0) {
+      step.next_steps = nexts;
+    }
+    steps.push(step);
+  }
+  return steps;
+}
+
+function compileDiagram(diag: DiagramDef, outputs: CompiledOutput[]): void {
+  const body = diag.body as AstNode[];
+  const fm = withSummary(commonFrontmatter(diag.name, body), body);
+  outputs.push(makeOutput(versionedPath("diagrams", diag.name, body), fm));
+}
+
+function compileUser(user: UserDef, outputs: CompiledOutput[]): void {
+  const fm: Record<string, unknown> = {
+    id: user.name,
+    name: user.name,
+  };
+  const annotations: Annotation[] = [];
+  for (const prop of user.props) {
+    switch (prop.$type) {
+      case "UserNameProp":
+        fm.name = stripQuotes(prop.value);
+        break;
+      case "UserAvatarProp":
+        fm.avatar = stripQuotes(prop.value);
+        break;
+      case "UserRoleProp":
+        fm.role = stripQuotes(prop.value);
+        break;
+      case "UserEmailProp":
+        fm.email = stripQuotes(prop.value);
+        break;
+      case "UserSlackProp":
+        fm.slack = stripQuotes(prop.value);
+        break;
+      case "UserMsTeamsProp":
+        fm.msTeams = stripQuotes(prop.value);
+        break;
+      case "UserAnnotationProp":
+        annotations.push(prop.annotation);
+        break;
+    }
+  }
+  const annFields = mapAnnotations(annotations);
+  Object.assign(fm, annFields);
+  outputs.push(makeOutput(`users/${user.name}.md`, fm));
+}
+
+function compileTeam(team: TeamDef, outputs: CompiledOutput[]): void {
+  const fm: Record<string, unknown> = {
+    id: team.name,
+    name: team.name,
+  };
+  let summary: string | undefined;
+  const members: string[] = [];
+  const annotations: Annotation[] = [];
+
+  for (const prop of team.props) {
+    switch (prop.$type) {
+      case "TeamNameProp":
+        fm.name = stripQuotes(prop.value);
+        break;
+      case "TeamSummaryProp":
+        summary = stripQuotes(prop.value);
+        fm.summary = summary;
+        break;
+      case "TeamAvatarProp":
+        fm.avatar = stripQuotes(prop.value);
+        break;
+      case "TeamRoleProp":
+        fm.role = stripQuotes(prop.value);
+        break;
+      case "TeamEmailProp":
+        fm.email = stripQuotes(prop.value);
+        break;
+      case "TeamSlackProp":
+        fm.slack = stripQuotes(prop.value);
+        break;
+      case "TeamMsTeamsProp":
+        fm.msTeams = stripQuotes(prop.value);
+        break;
+      case "TeamMemberProp":
+        members.push(prop.memberRef);
+        break;
+      case "TeamAnnotationProp":
+        annotations.push(prop.annotation);
+        break;
+    }
+  }
+  if (members.length > 0) fm.members = members;
+
+  const annFields = mapAnnotations(annotations);
+  Object.assign(fm, annFields);
+  outputs.push(makeOutput(`teams/${team.name}.md`, fm));
+}
+
+function compileVisualizer(
+  viz: VisualizerDef,
+  outputs: CompiledOutput[],
+  nested: boolean,
+): void {
+  // Visualizer wrapper does NOT produce its own markdown.
+  // Inline definitions inside it compile normally.
+  for (const item of viz.body) {
+    if (isDomainDef(item)) {
+      compileDomain(item, outputs, nested);
+      continue;
+    }
+    if (isServiceDef(item)) {
+      compileService(item, outputs, nested, "");
+      compileInlineMessages(item, outputs, nested, "");
+      continue;
+    }
+    if (isEventDef(item) && item.body.length > 0) {
+      compileMessage(item, "events", outputs, nested, "");
+      continue;
+    }
+    if (isCommandDef(item) && item.body.length > 0) {
+      compileMessage(item, "commands", outputs, nested, "");
+      continue;
+    }
+    if (isQueryDef(item) && item.body.length > 0) {
+      compileMessage(item, "queries", outputs, nested, "");
+      continue;
+    }
+    if (isChannelDef(item)) {
+      compileChannel(item, outputs, nested, "");
+      continue;
+    }
+    if (isContainerDef(item)) {
+      compileContainer(item, outputs, nested, "");
+      continue;
+    }
+    if (isDataProductDef(item)) {
+      compileDataProduct(item, outputs);
+      continue;
+    }
+    if (isFlowDef(item)) {
+      compileFlow(item, outputs);
+      continue;
+    }
+  }
+}
diff --git a/packages/language-server/src/completion-data.ts b/packages/language-server/src/completion-data.ts
new file mode 100644
index 000000000..6d5aaa0d1
--- /dev/null
+++ b/packages/language-server/src/completion-data.ts
@@ -0,0 +1,495 @@
+/**
+ * Shared completion data used by both the language server (LSP) and the playground (Monaco).
+ * This is the single source of truth for all snippet templates, annotations, and context-aware suggestions.
+ */
+
+export interface Suggestion {
+  label: string;
+  detail: string;
+  insertText: string;
+}
+
+// ─── Message type → plural form ─────────────────────────
+
+export const MESSAGE_TYPE_PLURAL: Record<string, string> = {
+  event: "events",
+  command: "commands",
+  query: "queries",
+};
+
+// ─── Top-level resource keyword snippets ─────────────────
+
+export const RESOURCE_KEYWORDS: Suggestion[] = [
+  {
+    label: "domain",
+    detail: "Top-level bounded context",
+    insertText:
+      'domain ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Bounded context responsible for $1}"\n\n  $0\n}',
+  },
+  {
+    label: "service",
+    detail: "Microservice or application",
+    insertText:
+      'service ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Service that manages and processes $1 operations}"\n\n  $0\n}',
+  },
+  {
+    label: "event",
+    detail: "Domain event",
+    insertText:
+      'event ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Triggered when a significant change occurs in the domain}"\n}',
+  },
+  {
+    label: "command",
+    detail: "Command message",
+    insertText:
+      'command ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Requests an action to be performed in the system}"\n}',
+  },
+  {
+    label: "query",
+    detail: "Query message",
+    insertText:
+      'query ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Retrieves data from the system without side effects}"\n}',
+  },
+  {
+    label: "channel",
+    detail: "Communication channel",
+    insertText:
+      'channel ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Message channel for routing events between services}"\n  address "${4:topic}"\n\n  $0\n}',
+  },
+  {
+    label: "user",
+    detail: "User definition",
+    insertText: 'user ${1:username} {\n  name "${2:Full Name}"\n\n  $0\n}',
+  },
+  {
+    label: "team",
+    detail: "Team definition",
+    insertText: 'team ${1:team-name} {\n  name "${2:Team Name}"\n\n  $0\n}',
+  },
+  {
+    label: "flow",
+    detail: "Flow definition",
+    insertText:
+      'flow ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:End-to-end flow describing how messages move through the system}"\n\n  $0\n}',
+  },
+  {
+    label: "container",
+    detail: "Data container",
+    insertText:
+      'container ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Data store that persists and manages $1 data}"\n\n  $0\n}',
+  },
+  {
+    label: "data-product",
+    detail: "Data product",
+    insertText:
+      'data-product ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Data product that provides curated data for consumers}"\n\n  $0\n}',
+  },
+  {
+    label: "visualizer",
+    detail: "Visualizer view",
+    insertText: 'visualizer ${1:main} {\n  name "${2:View Name}"\n\n  $0\n}',
+  },
+  {
+    label: "actor",
+    detail: "Human actor (for flows)",
+    insertText:
+      'actor ${1:Name} {\n  name "${2:Display Name}"\n  summary "${3:User or persona that interacts with the system}"\n}',
+  },
+  {
+    label: "external-system",
+    detail: "External system (for flows)",
+    insertText:
+      'external-system ${1:Name} {\n  name "${2:Display Name}"\n  summary "${3:Third-party system that integrates with the platform}"\n}',
+  },
+];
+
+// ─── Common properties (shared across most resource types) ──
+
+export const COMMON_PROPS: Suggestion[] = [
+  {
+    label: "version",
+    detail: "Semantic version",
+    insertText: "version ${1:1.0.0}",
+  },
+  {
+    label: "name",
+    detail: "Display name",
+    insertText: 'name "${1:Display Name}"',
+  },
+  {
+    label: "summary",
+    detail: "Short description",
+    insertText: 'summary "${1:description}"',
+  },
+  {
+    label: "owner",
+    detail: "Owner reference",
+    insertText: "owner ${1:MyTeam}",
+  },
+  {
+    label: "deprecated",
+    detail: "Mark as deprecated",
+    insertText: "deprecated true",
+  },
+  { label: "draft", detail: "Mark as draft", insertText: "draft true" },
+];
+
+// ─── Annotation snippets with full argument scaffolding ──
+
+export const ANNOTATION_SUGGESTIONS: Suggestion[] = [
+  {
+    label: "@api",
+    detail: "HTTP API metadata",
+    insertText:
+      'api(method: "${1|GET,POST,PUT,PATCH,DELETE|}", path: "${2:/resource}", statusCodes: "${3:200}")',
+  },
+  {
+    label: "@badge",
+    detail: "Visual badge",
+    insertText: 'badge("${1:label}", bg: "${2:#22c55e}", text: "${3:#fff}")',
+  },
+  {
+    label: "@note",
+    detail: "Developer note or reminder",
+    insertText: 'note("${1:note text}")',
+  },
+  {
+    label: "@note (with params)",
+    detail: "Note with author and priority",
+    insertText:
+      'note("${1:note text}", author: "${2:name}", priority: "${3|low,medium,high|}")',
+  },
+  {
+    label: "@repository",
+    detail: "Source code repository",
+    insertText:
+      'repository(url: "${1:https://github.com/...}", language: "${2:TypeScript}")',
+  },
+  {
+    label: "@specification",
+    detail: "API specification",
+    insertText:
+      'specification(type: ${1|openapi,asyncapi,graphql|}, path: "${2:./spec.yml}")',
+  },
+  {
+    label: "@externalId",
+    detail: "External identifier",
+    insertText: 'externalId("${1:id}")',
+  },
+  {
+    label: "@tag",
+    detail: "Add a tag to the resource",
+    insertText: 'tag("${1:tag-name}")',
+  },
+];
+
+// ─── Context-aware completions per resource type ─────────
+
+export const CONTEXT_SUGGESTIONS: Record<string, Suggestion[]> = {
+  service: [
+    ...COMMON_PROPS,
+    {
+      label: "sends",
+      detail: "Service sends a message",
+      insertText: "sends ${1|event,command,query|} ${2:Name}",
+    },
+    {
+      label: "receives",
+      detail: "Service receives a message",
+      insertText: "receives ${1|event,command,query|} ${2:Name}",
+    },
+    {
+      label: "writes-to",
+      detail: "Writes to a container",
+      insertText: "writes-to container ${1:Container}",
+    },
+    {
+      label: "reads-from",
+      detail: "Reads from a container",
+      insertText: "reads-from container ${1:Container}",
+    },
+  ],
+  domain: [
+    ...COMMON_PROPS,
+    {
+      label: "service",
+      detail: "Nested service",
+      insertText: "service ${1:Name} {\n  version ${2:1.0.0}\n\n  $0\n}",
+    },
+    {
+      label: "subdomain",
+      detail: "Nested subdomain",
+      insertText: "subdomain ${1:Name} {\n  version ${2:1.0.0}\n\n  $0\n}",
+    },
+  ],
+  event: [
+    ...COMMON_PROPS,
+    {
+      label: "schema",
+      detail: "Schema path",
+      insertText: 'schema "${1:path}"',
+    },
+  ],
+  command: [
+    ...COMMON_PROPS,
+    {
+      label: "schema",
+      detail: "Schema path",
+      insertText: 'schema "${1:path}"',
+    },
+  ],
+  query: [
+    ...COMMON_PROPS,
+    {
+      label: "schema",
+      detail: "Schema path",
+      insertText: 'schema "${1:path}"',
+    },
+  ],
+  channel: [
+    ...COMMON_PROPS,
+    {
+      label: "address",
+      detail: "Channel address/topic",
+      insertText: 'address "${1:topic}"',
+    },
+    {
+      label: "protocol",
+      detail: "Channel protocol",
+      insertText: 'protocol "${1:protocol}"',
+    },
+    {
+      label: "route",
+      detail: "Route to another channel",
+      insertText: "route ${1:ChannelName}",
+    },
+  ],
+  user: [
+    {
+      label: "name",
+      detail: "Display name",
+      insertText: 'name "${1:Full Name}"',
+    },
+    {
+      label: "avatar",
+      detail: "Avatar URL",
+      insertText: 'avatar "${1:https://example.com/avatar.png}"',
+    },
+    { label: "role", detail: "User role", insertText: 'role "${1:role}"' },
+  ],
+  team: [
+    {
+      label: "name",
+      detail: "Team display name",
+      insertText: 'name "${1:Team Name}"',
+    },
+    {
+      label: "avatar",
+      detail: "Avatar URL",
+      insertText: 'avatar "${1:https://example.com/avatar.png}"',
+    },
+    { label: "role", detail: "Team role", insertText: 'role "${1:role}"' },
+    {
+      label: "member",
+      detail: "Team member",
+      insertText: "member ${1:username}",
+    },
+  ],
+  flow: [
+    ...COMMON_PROPS,
+    {
+      label: "entry chain",
+      detail: "Starting arrow chain",
+      insertText: '${1:Source} "${2:description}" -> ${3:Target}',
+    },
+    {
+      label: "when block",
+      detail: "React to an event",
+      insertText:
+        'when ${1:TriggerName}\n  ${2:ServiceName} "${3:description}"\n    -> ${0:OutputName}',
+    },
+    {
+      label: "when (convergence)",
+      detail: "React to multiple events",
+      insertText:
+        'when ${1:EventA} and ${2:EventB}\n  ${3:ServiceName} "${4:description}"\n    -> ${0:OutputName}',
+    },
+    {
+      label: "labeled output",
+      detail: "Output with label",
+      insertText: '-> "${1:label}": ${2:TargetName}',
+    },
+  ],
+  container: [
+    ...COMMON_PROPS,
+    {
+      label: "container-type",
+      detail: "Type of container",
+      insertText:
+        "container-type ${1|database,cache,objectStore,searchIndex,dataWarehouse,dataLake,externalSaaS,other|}",
+    },
+    {
+      label: "technology",
+      detail: "Technology/implementation",
+      insertText: 'technology "${1:postgres@14}"',
+    },
+    {
+      label: "authoritative",
+      detail: "Authoritative source",
+      insertText: "authoritative ${1|true,false|}",
+    },
+    {
+      label: "access-mode",
+      detail: "Access pattern",
+      insertText: "access-mode ${1|read,write,readWrite,appendOnly|}",
+    },
+    {
+      label: "classification",
+      detail: "Data classification",
+      insertText: "classification ${1|public,internal,confidential,regulated|}",
+    },
+    {
+      label: "residency",
+      detail: "Data residency",
+      insertText: 'residency "${1:region}"',
+    },
+    {
+      label: "retention",
+      detail: "Data retention policy",
+      insertText: 'retention "${1:policy}"',
+    },
+  ],
+  "data-product": [
+    ...COMMON_PROPS,
+    {
+      label: "input",
+      detail: "Input data source",
+      insertText: "input ${1|event,command,query|} ${2:ResourceName}",
+    },
+    {
+      label: "output",
+      detail: "Output dataset",
+      insertText: "output ${1|event,command,query|} ${2:DatasetName}",
+    },
+    {
+      label: "output (with contract)",
+      detail: "Output with schema contract",
+      insertText:
+        'output ${1|event,command,query|} ${2:DatasetName} {\n  contract {\n    path "${3:./schemas/schema.json}"\n    name "${4:SchemaName}"\n    type "${5:json-schema}"\n  }\n}',
+    },
+  ],
+  actor: [
+    {
+      label: "name",
+      detail: "Display name",
+      insertText: 'name "${1:Display Name}"',
+    },
+    {
+      label: "summary",
+      detail: "Short description",
+      insertText: 'summary "${1:description}"',
+    },
+  ],
+  "external-system": [
+    {
+      label: "name",
+      detail: "Display name",
+      insertText: 'name "${1:Display Name}"',
+    },
+    {
+      label: "summary",
+      detail: "Short description",
+      insertText: 'summary "${1:description}"',
+    },
+  ],
+  visualizer: [
+    {
+      label: "name",
+      detail: "Display name",
+      insertText: 'name "${1:View Name}"',
+    },
+    {
+      label: "summary",
+      detail: "Short description",
+      insertText: 'summary "${1:description}"',
+    },
+    {
+      label: "legend",
+      detail: "Show/hide legend",
+      insertText: "legend ${1|true,false|}",
+    },
+    {
+      label: "search",
+      detail: "Show/hide search",
+      insertText: "search ${1|true,false|}",
+    },
+    {
+      label: "toolbar",
+      detail: "Show/hide toolbar",
+      insertText: "toolbar ${1|true,false|}",
+    },
+    {
+      label: "focus-mode",
+      detail: "Enable/disable focus mode",
+      insertText: "focus-mode ${1|true,false|}",
+    },
+    {
+      label: "animated",
+      detail: "Simulate message flow animation",
+      insertText: "animated ${1|true,false|}",
+    },
+    {
+      label: "style",
+      detail: "Node rendering style",
+      insertText: "style ${1|default,post-it|}",
+    },
+    {
+      label: "service",
+      detail: "Include a service",
+      insertText:
+        'service ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Service that manages and processes $1 operations}"\n\n  $0\n}',
+    },
+    {
+      label: "domain",
+      detail: "Include a domain",
+      insertText:
+        'domain ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Bounded context responsible for $1}"\n\n  $0\n}',
+    },
+    {
+      label: "event",
+      detail: "Include an event",
+      insertText:
+        'event ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Triggered when a significant change occurs in the domain}"\n}',
+    },
+    {
+      label: "command",
+      detail: "Include a command",
+      insertText:
+        'command ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Requests an action to be performed in the system}"\n}',
+    },
+    {
+      label: "query",
+      detail: "Include a query",
+      insertText:
+        'query ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Retrieves data from the system without side effects}"\n}',
+    },
+    {
+      label: "channel",
+      detail: "Include a channel",
+      insertText:
+        'channel ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Message channel for routing events between services}"\n  address "${4:topic}"\n\n  $0\n}',
+    },
+    {
+      label: "container",
+      detail: "Include a container",
+      insertText:
+        'container ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:Data store that persists and manages $1 data}"\n}',
+    },
+    {
+      label: "flow",
+      detail: "Include a flow",
+      insertText:
+        'flow ${1:Name} {\n  version ${2:1.0.0}\n  summary "${3:End-to-end flow describing how messages move through the system}"\n}',
+    },
+  ],
+};
diff --git a/packages/language-server/src/completion-utils.ts b/packages/language-server/src/completion-utils.ts
new file mode 100644
index 000000000..99aa7546b
--- /dev/null
+++ b/packages/language-server/src/completion-utils.ts
@@ -0,0 +1,212 @@
+import { parseSpec } from "./resolvers/asyncapi.js";
+import { parseOpenApiSpec } from "./resolvers/openapi.js";
+import { detectSpecType } from "./resolvers/resolve.js";
+import type { SpecMessage, SpecChannel } from "./resolvers/types.js";
+
+export interface ParsedSpecResult {
+  messages: Map<string, SpecMessage>;
+  channels: Map<string, SpecChannel>;
+}
+
+export function collectRegexMatches(pattern: RegExp, text: string): string[] {
+  const results: string[] = [];
+  let m;
+  while ((m = pattern.exec(text)) !== null) {
+    results.push(m[1]);
+  }
+  return results;
+}
+
+/**
+ * Extract version numbers for resources from workspace text.
+ * Optionally filter to a single resource type for efficiency.
+ */
+export function extractResourceVersions(
+  text: string,
+  filterType?: string,
+): Map<string, string[]> {
+  const versions = new Map<string, string[]>();
+  const allTypes = [
+    "event",
+    "command",
+    "query",
+    "channel",
+    "service",
+    "domain",
+    "flow",
+    "container",
+    "data-product",
+  ];
+  const resourceTypes = filterType
+    ? allTypes.filter((t) => t === filterType)
+    : allTypes;
+
+  for (const type of resourceTypes) {
+    const defRegex = new RegExp(
+      `\\b${type}\\s+([a-zA-Z_][a-zA-Z0-9_.{}\\-]*)\\s*\\{[^}]*?version\\s+(\\d+\\.\\d+\\.\\d+(?:-[a-zA-Z0-9_.]+)*)`,
+      "g",
+    );
+    let match;
+    const seen = new Set<string>();
+    while ((match = defRegex.exec(text)) !== null) {
+      const key = `${type}:${match[1]}`;
+      const ver = match[2];
+      const dedup = `${key}:${ver}`;
+      if (seen.has(dedup)) continue;
+      seen.add(dedup);
+      const arr = versions.get(key) ?? [];
+      arr.push(ver);
+      versions.set(key, arr);
+    }
+
+    const inlineRegex = new RegExp(
+      `\\b(?:sends|receives)\\s+${type}\\s+([a-zA-Z_][a-zA-Z0-9_.\\-]*)\\s*\\{[^}]*?version\\s+(\\d+\\.\\d+\\.\\d+(?:-[a-zA-Z0-9_.]+)*)`,
+      "g",
+    );
+    while ((match = inlineRegex.exec(text)) !== null) {
+      const key = `${type}:${match[1]}`;
+      const ver = match[2];
+      const dedup = `${key}:${ver}`;
+      if (seen.has(dedup)) continue;
+      seen.add(dedup);
+      const arr = versions.get(key) ?? [];
+      arr.push(ver);
+      versions.set(key, arr);
+    }
+  }
+
+  return versions;
+}
+
+/**
+ * Parse a spec file, auto-detecting AsyncAPI vs OpenAPI format.
+ */
+export function parseSpecAuto(content: string): ParsedSpecResult {
+  const specType = detectSpecType(content);
+  if (specType === "openapi") {
+    const parsed = parseOpenApiSpec(content);
+    return {
+      messages: parsed.messages as Map<string, SpecMessage>,
+      channels: new Map(),
+    };
+  }
+  const parsed = parseSpec(content);
+  return { messages: parsed.messages, channels: parsed.channels };
+}
+
+/**
+ * Collect all channel names from workspace text via regex patterns.
+ */
+export function collectChannelNames(allText: string): Set<string> {
+  return new Set([
+    ...collectRegexMatches(
+      /\bchannel\s+([a-zA-Z_][a-zA-Z0-9_.\-]*)\s*\{/g,
+      allText,
+    ),
+    ...collectRegexMatches(
+      /\b(?:sends|receives)\s+(?:event|command|query)\s+[a-zA-Z_][a-zA-Z0-9_.\-]*(?:@[^\s]*)?\s+(?:to|from)\s+([a-zA-Z_][a-zA-Z0-9_.\-]*)/g,
+      allText,
+    ),
+    ...collectRegexMatches(
+      /import\s+channels\s*\{([^}]*)\}\s*from\s*"[^"]+"/g,
+      allText,
+    ).flatMap((match) =>
+      match
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean),
+    ),
+  ]);
+}
+
+/**
+ * Collect all message names of a given type from workspace text via regex patterns.
+ */
+export function collectMessageNames(
+  allText: string,
+  msgType: string,
+  pluralType: string,
+): Set<string> {
+  return new Set([
+    ...collectRegexMatches(
+      new RegExp(`\\b${msgType}\\s+([a-zA-Z_][a-zA-Z0-9_.\\-]*)\\s*\\{`, "g"),
+      allText,
+    ),
+    ...collectRegexMatches(
+      new RegExp(
+        `\\b(?:sends|receives)\\s+${msgType}\\s+([a-zA-Z_][a-zA-Z0-9_.\\-]*)`,
+        "g",
+      ),
+      allText,
+    ),
+    ...collectRegexMatches(
+      new RegExp(
+        `import\\s+${pluralType}\\s*\\{([^}]*)\\}\\s*from\\s*"[^"]+"`,
+        "g",
+      ),
+      allText,
+    ).flatMap((match) =>
+      match
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean),
+    ),
+  ]);
+}
+
+/**
+ * Walk text tracking brace depth to determine which resource block the cursor is inside.
+ * Returns the resource type string (e.g. "service", "domain") or null if at top level.
+ */
+export function findEnclosingResource(text: string): string | null {
+  const stack: string[] = [];
+  const tokenRegex =
+    /\b(domain|service|event|command|query|channel|user|team|flow|container|data-product|subdomain|visualizer|actor|external-system)\b(?:[^{}]|\{[a-zA-Z0-9_]+\})*\{|\{|\}/g;
+  let match;
+
+  while ((match = tokenRegex.exec(text)) !== null) {
+    const token = match[0];
+    if (token === "}") {
+      stack.pop();
+    } else if (token === "{") {
+      stack.push("unknown");
+    } else {
+      stack.push(match[1]);
+    }
+  }
+
+  if (stack.length === 0) return null;
+  const top = stack[stack.length - 1];
+  return top === "subdomain" ? "domain" : top;
+}
+
+const EC_RESOURCE_TYPES = [
+  "service",
+  "event",
+  "command",
+  "query",
+  "domain",
+  "channel",
+  "flow",
+  "container",
+  "data-product",
+  "actor",
+  "external-system",
+];
+
+/**
+ * Extract top-level resource names defined in a single .ec file's text.
+ */
+export function extractResourceNamesFromText(text: string): Set<string> {
+  const names = new Set<string>();
+  for (const type of EC_RESOURCE_TYPES) {
+    const regex = new RegExp(
+      `\\b${type}\\s+([a-zA-Z_][a-zA-Z0-9_.\\-]*)\\s*\\{`,
+      "g",
+    );
+    for (const name of collectRegexMatches(regex, text)) {
+      names.add(name);
+    }
+  }
+  return names;
+}
diff --git a/packages/language-server/src/ec-completion-provider.ts b/packages/language-server/src/ec-completion-provider.ts
new file mode 100644
index 000000000..8ca28b864
--- /dev/null
+++ b/packages/language-server/src/ec-completion-provider.ts
@@ -0,0 +1,767 @@
+import { DefaultCompletionProvider } from "langium/lsp";
+import type { LangiumServices } from "langium/lsp";
+import type { MaybePromise, LangiumDocument } from "langium";
+import { GrammarAST } from "langium";
+import {
+  CompletionItemKind,
+  CompletionList,
+  InsertTextFormat,
+} from "vscode-languageserver";
+import type {
+  CompletionParams,
+  CancellationToken,
+} from "vscode-languageserver";
+import type {
+  CompletionAcceptor,
+  CompletionContext,
+  CompletionProviderOptions,
+} from "langium/lsp";
+import type { NextFeature } from "langium/lsp";
+import { isSpecFile } from "./resolvers/resolve.js";
+import { isCatalogPath } from "./resolvers/types.js";
+import {
+  parseCatalogResources,
+  parseCatalogChannels,
+  parseCatalogServices,
+} from "./resolvers/catalog.js";
+import {
+  collectRegexMatches,
+  extractResourceVersions,
+  extractResourceNamesFromText,
+  parseSpecAuto,
+  findEnclosingResource,
+  collectChannelNames,
+  collectMessageNames,
+} from "./completion-utils.js";
+import type { ParsedSpecResult } from "./completion-utils.js";
+import {
+  RESOURCE_KEYWORDS,
+  ANNOTATION_SUGGESTIONS,
+  CONTEXT_SUGGESTIONS,
+  MESSAGE_TYPE_PLURAL,
+} from "./completion-data.js";
+import type { Suggestion } from "./completion-data.js";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Build a lookup from keyword label → Suggestion for resource snippets */
+const RESOURCE_SUGGESTION_MAP = new Map<string, Suggestion>(
+  RESOURCE_KEYWORDS.map((r) => [r.label, r]),
+);
+
+// ─── Per-request workspace snapshot ──────────────────────
+// Computed lazily on first access per completion request, then reused.
+
+interface WorkspaceSnapshot {
+  allText?: string;
+  parsedSpecs?: Map<string, ParsedSpecResult>;
+  dirListing?: { dir: string; files: string[]; dirs: string[] };
+}
+
+// ─── Completion provider ─────────────────────────────────
+
+export class EcCompletionProvider extends DefaultCompletionProvider {
+  override readonly completionOptions: CompletionProviderOptions = {
+    triggerCharacters: ["@", '"', "{"],
+  };
+
+  private langiumServices: LangiumServices;
+
+  /** Snapshot for the current completion request. Reset on each `completionFor` call. */
+  private snapshot: WorkspaceSnapshot = {};
+
+  constructor(services: LangiumServices) {
+    super(services);
+    this.langiumServices = services;
+  }
+
+  override async getCompletion(
+    document: LangiumDocument,
+    params: CompletionParams,
+    cancelToken?: CancellationToken,
+  ): Promise<CompletionList | undefined> {
+    // Reset per-request cache
+    this.snapshot = {};
+
+    // Let Langium handle grammar-driven completions first
+    const result = await super.getCompletion(document, params, cancelToken);
+
+    // If Langium produced results, return them (tryDynamicCompletion was called via completionFor)
+    if (result && result.items.length > 0) {
+      return result;
+    }
+
+    // Langium's parser couldn't determine next features (common for deeply nested resources).
+    // Provide context-aware completions as a fallback.
+    const textDocument = document.textDocument;
+    const offset = textDocument.offsetAt(params.position);
+    const textBefore = textDocument.getText().substring(0, offset);
+    const enclosing = findEnclosingResource(textBefore);
+
+    if (!enclosing) {
+      return result;
+    }
+
+    const suggestions = CONTEXT_SUGGESTIONS[enclosing];
+    if (!suggestions || suggestions.length === 0) {
+      return result;
+    }
+
+    const fallbackItems = suggestions.map((s) => ({
+      label: s.label,
+      kind: CompletionItemKind.Snippet,
+      detail: s.detail,
+      insertText: s.insertText,
+      insertTextFormat: InsertTextFormat.Snippet,
+      sortText: "1" + s.label,
+    }));
+
+    const existingItems = result?.items ?? [];
+    return CompletionList.create([...existingItems, ...fallbackItems], true);
+  }
+
+  protected override async completionFor(
+    context: CompletionContext,
+    next: NextFeature,
+    acceptor: CompletionAcceptor,
+  ): Promise<void> {
+    // When completing after '@', offer annotation snippets
+    if (this.isAnnotationNameContext(context, next)) {
+      this.completeAnnotationNames(context, acceptor);
+      return;
+    }
+    // Try dynamic cross-file completions before grammar-driven ones
+    if (await this.tryDynamicCompletion(context, acceptor)) {
+      return;
+    }
+    return super.completionFor(context, next, acceptor);
+  }
+
+  protected override completionForKeyword(
+    context: CompletionContext,
+    keyword: GrammarAST.Keyword,
+    acceptor: CompletionAcceptor,
+  ): MaybePromise<void> {
+    const kw = keyword.value;
+
+    // Skip '@' itself — we handle annotation names in completionFor
+    if (kw === "@") {
+      return;
+    }
+
+    // Determine what resource block the cursor is inside (if any)
+    const text = context.textDocument.getText();
+    const textBefore = text.substring(0, context.offset);
+    const enclosing = findEnclosingResource(textBefore);
+
+    // Inside a non-visualizer resource block: only show context-appropriate items
+    if (enclosing && enclosing !== "visualizer") {
+      const suggestions = CONTEXT_SUGGESTIONS[enclosing];
+      if (suggestions) {
+        const match = suggestions.find((s) => s.label === kw);
+        if (match) {
+          acceptor(context, {
+            label: kw,
+            kind: CompletionItemKind.Snippet,
+            detail: match.detail,
+            insertText: match.insertText,
+            insertTextFormat: InsertTextFormat.Snippet,
+            sortText: "0" + kw,
+          });
+        }
+      }
+      // Don't show resource keywords or unrelated keywords inside resource blocks
+      return;
+    }
+
+    // At top level or inside a visualizer: offer resource keyword snippets
+    const resourceSuggestion = RESOURCE_SUGGESTION_MAP.get(kw);
+    if (resourceSuggestion) {
+      acceptor(context, {
+        label: kw,
+        kind: CompletionItemKind.Snippet,
+        detail: resourceSuggestion.detail,
+        insertText: resourceSuggestion.insertText,
+        insertTextFormat: InsertTextFormat.Snippet,
+        sortText: "0" + kw,
+      });
+      return;
+    }
+
+    // Inside a visualizer: also check visualizer-specific context suggestions
+    if (enclosing === "visualizer") {
+      const suggestions = CONTEXT_SUGGESTIONS[enclosing];
+      if (suggestions) {
+        const match = suggestions.find((s) => s.label === kw);
+        if (match) {
+          acceptor(context, {
+            label: kw,
+            kind: CompletionItemKind.Snippet,
+            detail: match.detail,
+            insertText: match.insertText,
+            insertTextFormat: InsertTextFormat.Snippet,
+            sortText: "0" + kw,
+          });
+          return;
+        }
+      }
+    }
+
+    // Fallback: plain keyword
+    acceptor(context, {
+      label: kw,
+      kind: CompletionItemKind.Keyword,
+    });
+  }
+
+  // ─── Dynamic cross-file completions ──────────────────
+
+  private async tryDynamicCompletion(
+    context: CompletionContext,
+    acceptor: CompletionAcceptor,
+  ): Promise<boolean> {
+    const text = context.textDocument.getText();
+    const offset = context.offset;
+
+    // Get the current line text before cursor
+    const textBefore = text.substring(0, offset);
+    const lastNewline = textBefore.lastIndexOf("\n");
+    const lineText = textBefore.substring(lastNewline + 1);
+
+    // 1. Import file paths: from "..."
+    if (lineText.includes("import")) {
+      const importFromMatch = lineText.match(
+        /import\s+(?:(?:events|commands|queries|channels|services)\s+)?\{[^}]*\}\s*from\s*"([^"]*)$/,
+      );
+      if (importFromMatch) {
+        this.completeImportPaths(context, acceptor);
+        return true;
+      }
+
+      // 2. Resource names in import braces: import { ... }
+      const importBracesMatch = lineText.match(
+        /import\s+(?:(events|commands|queries|channels|services|containers)\s+)?\{([^}]*)$/,
+      );
+      if (importBracesMatch) {
+        const fullLineContent = this.getFullLineContent(text, offset);
+        await this.completeImportNames(
+          context,
+          acceptor,
+          importBracesMatch[1] as
+            | "events"
+            | "commands"
+            | "queries"
+            | "channels"
+            | "containers"
+            | undefined,
+          importBracesMatch[2] || "",
+          fullLineContent,
+        );
+        return true;
+      }
+    }
+
+    if (lineText.includes("sends") || lineText.includes("receives")) {
+      // 3. Channel names: sends event X to ...
+      const channelRefMatch = lineText.match(
+        /\b(?:sends|receives)\s+(?:event|command|query)\s+[a-zA-Z_][a-zA-Z0-9_.\-]*(?:@[\d]+\.[\d]+\.[\d]+[a-zA-Z0-9_.\-]*)?\s+(?:to|from)\s+(?:.*,\s*)?([a-zA-Z_][a-zA-Z0-9_.\-]*)?$/,
+      );
+      if (channelRefMatch) {
+        this.completeChannelNames(context, acceptor);
+        return true;
+      }
+
+      // 4. Message names: sends event ...
+      const sendsReceivesMatch = lineText.match(
+        /\b(?:sends|receives)\s+(event|command|query)\s+([a-zA-Z_][a-zA-Z0-9_.\-]*)?$/,
+      );
+      if (sendsReceivesMatch && !sendsReceivesMatch[0].endsWith("@")) {
+        this.completeMessageNames(context, acceptor, sendsReceivesMatch[1]);
+        return true;
+      }
+
+      // 5. Version after @: sends event Name@
+      const atMatch = lineText.match(
+        /\b(?:sends|receives)\s+(event|command|query)\s+([a-zA-Z_][a-zA-Z0-9_.\-]*)@$/,
+      );
+      if (atMatch) {
+        this.completeVersions(context, acceptor, atMatch[1], atMatch[2]);
+        return true;
+      }
+    }
+
+    // 6. Context-aware completions for the enclosing resource block
+    // Offer all suggestions for the current context — this ensures items like
+    // sends, receives, writes-to, reads-from, and scaffold snippets are always
+    // available, even when Langium's grammar analysis doesn't offer them.
+    const enclosing = findEnclosingResource(textBefore);
+    if (enclosing) {
+      const suggestions = CONTEXT_SUGGESTIONS[enclosing];
+      if (suggestions) {
+        for (const s of suggestions) {
+          acceptor(context, {
+            label: s.label,
+            kind: CompletionItemKind.Snippet,
+            detail: s.detail,
+            insertText: s.insertText,
+            insertTextFormat: InsertTextFormat.Snippet,
+            sortText: "1" + s.label,
+          });
+        }
+      }
+    }
+
+    return false;
+  }
+
+  // ─── Lazy per-request helpers ─────────────────────────
+
+  private getAllWorkspaceText(): string {
+    if (this.snapshot.allText !== undefined) return this.snapshot.allText;
+    const docs = this.langiumServices.shared.workspace.LangiumDocuments.all;
+    this.snapshot.allText = docs
+      .filter((d) => d.uri.path.endsWith(".ec"))
+      .map((d) => d.textDocument.getText())
+      .toArray()
+      .join("\n");
+    return this.snapshot.allText;
+  }
+
+  private getFullLineContent(text: string, offset: number): string {
+    const start = text.lastIndexOf("\n", offset - 1) + 1;
+    let end = text.indexOf("\n", offset);
+    if (end === -1) end = text.length;
+    return text.substring(start, end);
+  }
+
+  private getDocumentDir(uri: string): string {
+    return dirname(fileURLToPath(uri));
+  }
+
+  /**
+   * Read the workspace directory listing once per request.
+   * Returns files (spec + .ec), directories, and the base dir.
+   */
+  private getDirListing(currentUri: string): {
+    dir: string;
+    files: string[];
+    dirs: string[];
+  } {
+    if (this.snapshot.dirListing) return this.snapshot.dirListing;
+    try {
+      const currentPath = fileURLToPath(currentUri);
+      const dir = dirname(currentPath);
+      const currentFilename = currentPath.substring(
+        currentPath.lastIndexOf("/") + 1,
+      );
+      const files: string[] = [];
+      const dirs: string[] = [];
+      for (const entry of readdirSync(dir)) {
+        if (entry === currentFilename) continue;
+        if (entry.startsWith(".") || entry === "node_modules") continue;
+        try {
+          if (statSync(resolve(dir, entry)).isDirectory()) {
+            dirs.push(entry);
+          } else if (entry.endsWith(".ec") || isSpecFile(entry)) {
+            files.push(entry);
+          }
+        } catch {
+          // skip unreadable entries
+        }
+      }
+      this.snapshot.dirListing = { dir, files, dirs };
+      return this.snapshot.dirListing;
+    } catch {
+      this.snapshot.dirListing = { dir: "", files: [], dirs: [] };
+      return this.snapshot.dirListing;
+    }
+  }
+
+  private getWorkspaceFilenames(currentUri: string): string[] {
+    const listing = this.getDirListing(currentUri);
+    if (listing.files.length > 0) return listing.files;
+    const docs = this.langiumServices.shared.workspace.LangiumDocuments.all;
+    return docs
+      .filter((d) => d.uri.toString() !== currentUri)
+      .map((d) => {
+        const p = d.uri.path;
+        return p.substring(p.lastIndexOf("/") + 1);
+      })
+      .toArray();
+  }
+
+  private readSpecFile(
+    specPath: string,
+    currentDocUri: string,
+  ): string | undefined {
+    try {
+      const dir = this.getDocumentDir(currentDocUri);
+      const normalizedPath = specPath.replace(/^\.\//, "");
+      const fullPath = resolve(dir, normalizedPath);
+      return readFileSync(fullPath, "utf-8");
+    } catch {
+      return undefined;
+    }
+  }
+
+  private parseWorkspaceSpecs(
+    currentDocUri: string,
+  ): Map<string, ParsedSpecResult> {
+    if (this.snapshot.parsedSpecs) return this.snapshot.parsedSpecs;
+    const parsed = new Map<string, ParsedSpecResult>();
+    const listing = this.getDirListing(currentDocUri);
+
+    for (const filename of listing.files) {
+      if (!isSpecFile(filename)) continue;
+      try {
+        const content = readFileSync(resolve(listing.dir, filename), "utf-8");
+        parsed.set(filename, parseSpecAuto(content));
+      } catch {
+        // skip unreadable or invalid files
+      }
+    }
+    this.snapshot.parsedSpecs = parsed;
+    return parsed;
+  }
+
+  // 1. Complete import file paths
+  private completeImportPaths(
+    context: CompletionContext,
+    acceptor: CompletionAcceptor,
+  ): void {
+    const filenames = this.getWorkspaceFilenames(context.textDocument.uri);
+    for (const filename of filenames) {
+      acceptor(context, {
+        label: `./${filename}`,
+        kind: CompletionItemKind.File,
+        detail: `Import from ${filename}`,
+        insertText: `./${filename}`,
+        sortText: `0${filename}`,
+      });
+    }
+
+    // Also suggest directories as potential catalog imports
+    const listing = this.getDirListing(context.textDocument.uri);
+    for (const dirName of listing.dirs) {
+      acceptor(context, {
+        label: `./${dirName}`,
+        kind: CompletionItemKind.Folder,
+        detail: `Import from catalog directory ${dirName}`,
+        insertText: `./${dirName}`,
+        sortText: `1${dirName}`,
+      });
+    }
+  }
+
+  // 2. Complete resource names inside import { ... }
+  private async completeImportNames(
+    context: CompletionContext,
+    acceptor: CompletionAcceptor,
+    resourceKind:
+      | "events"
+      | "commands"
+      | "queries"
+      | "channels"
+      | "services"
+      | "containers"
+      | undefined,
+    alreadyTyped: string,
+    fullLineContent: string,
+  ): Promise<void> {
+    const alreadyImported = new Set(
+      alreadyTyped
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean),
+    );
+
+    const fromSpecMatch = fullLineContent.match(
+      /from\s*"([^"]+\.(?:ya?ml|json))"/,
+    );
+    if (resourceKind && fromSpecMatch) {
+      const specContent = this.readSpecFile(
+        fromSpecMatch[1],
+        context.textDocument.uri,
+      );
+
+      if (specContent) {
+        try {
+          const parsed = parseSpecAuto(specContent);
+          const catalog =
+            resourceKind === "channels" ? parsed.channels : parsed.messages;
+          for (const [name, resource] of catalog) {
+            if (!alreadyImported.has(name)) {
+              acceptor(context, {
+                label: name,
+                kind: CompletionItemKind.Field,
+                detail: resource.summary || `Import from ${fromSpecMatch[1]}`,
+                insertText: name,
+                sortText: `0${name}`,
+              });
+            }
+          }
+          return;
+        } catch {
+          // Fall through to generic suggestions
+        }
+      }
+    }
+
+    // Catalog directory imports: import events { ... } from "./my-catalog"
+    const fromCatalogMatch = fullLineContent.match(/from\s*"([^"]+)"/);
+    if (
+      resourceKind &&
+      fromCatalogMatch &&
+      isCatalogPath(fromCatalogMatch[1])
+    ) {
+      await this.completeCatalogImportNames(
+        context,
+        acceptor,
+        resourceKind,
+        fromCatalogMatch[1],
+        alreadyImported,
+      );
+      return;
+    }
+
+    // .ec file imports: only suggest resources defined in the target file
+    const fromEcMatch = fullLineContent.match(/from\s*"([^"]+\.ec)"/);
+    if (fromEcMatch) {
+      const ecContent = this.readSpecFile(
+        fromEcMatch[1],
+        context.textDocument.uri,
+      );
+      if (ecContent) {
+        const names = extractResourceNamesFromText(ecContent);
+        for (const name of names) {
+          if (!alreadyImported.has(name)) {
+            acceptor(context, {
+              label: name,
+              kind: CompletionItemKind.Class,
+              detail: `Import from ${fromEcMatch[1]}`,
+              insertText: name,
+              sortText: `0${name}`,
+            });
+          }
+        }
+        return;
+      }
+    }
+
+    // Fallback: suggest resource names from all workspace .ec files
+    const allText = this.getAllWorkspaceText();
+    const resources = extractResourceNamesFromText(allText);
+
+    for (const name of resources) {
+      if (!alreadyImported.has(name)) {
+        acceptor(context, {
+          label: name,
+          kind: CompletionItemKind.Class,
+          detail: "Resource to import",
+          insertText: name,
+          sortText: `0${name}`,
+        });
+      }
+    }
+  }
+
+  // 2b. Complete resource names from a catalog directory import
+  private async completeCatalogImportNames(
+    context: CompletionContext,
+    acceptor: CompletionAcceptor,
+    resourceKind:
+      | "events"
+      | "commands"
+      | "queries"
+      | "channels"
+      | "services"
+      | "containers",
+    catalogPath: string,
+    alreadyImported: Set<string>,
+  ): Promise<void> {
+    try {
+      const dir = this.getDocumentDir(context.textDocument.uri);
+      const catalogDir = resolve(dir, catalogPath);
+
+      if (resourceKind === "services") {
+        const { services } = await parseCatalogServices(catalogDir);
+        for (const [name, svc] of services) {
+          if (!alreadyImported.has(name)) {
+            acceptor(context, {
+              label: name,
+              kind: CompletionItemKind.Class,
+              detail: svc.summary || `Import from catalog ${catalogPath}`,
+              insertText: name,
+              sortText: `0${name}`,
+            });
+          }
+        }
+        return;
+      }
+
+      if (resourceKind === "channels") {
+        const { channels } = await parseCatalogChannels(catalogDir);
+        for (const [name, ch] of channels) {
+          if (!alreadyImported.has(name)) {
+            acceptor(context, {
+              label: name,
+              kind: CompletionItemKind.Field,
+              detail: ch.summary || `Import from catalog ${catalogPath}`,
+              insertText: name,
+              sortText: `0${name}`,
+            });
+          }
+        }
+        return;
+      }
+
+      const { messages } = await parseCatalogResources(
+        catalogDir,
+        resourceKind,
+      );
+
+      for (const [name, resource] of messages) {
+        if (!alreadyImported.has(name)) {
+          acceptor(context, {
+            label: name,
+            kind: CompletionItemKind.Field,
+            detail: resource.summary || `Import from catalog ${catalogPath}`,
+            insertText: name,
+            sortText: `0${name}`,
+          });
+        }
+      }
+    } catch {
+      // Silently ignore errors in completions
+    }
+  }
+
+  // 3. Complete channel names
+  private completeChannelNames(
+    context: CompletionContext,
+    acceptor: CompletionAcceptor,
+  ): void {
+    const allText = this.getAllWorkspaceText();
+    const channels = collectChannelNames(allText);
+
+    const parsedSpecs = this.parseWorkspaceSpecs(context.textDocument.uri);
+    const channelSummaries = new Map<string, string>();
+    for (const [, parsed] of parsedSpecs) {
+      for (const [name, resource] of parsed.channels) {
+        channels.add(name);
+        if (resource.summary) channelSummaries.set(name, resource.summary);
+      }
+    }
+
+    for (const name of channels) {
+      acceptor(context, {
+        label: name,
+        kind: CompletionItemKind.Field,
+        detail: channelSummaries.get(name) || `channel ${name}`,
+        insertText: name,
+        sortText: `0${name}`,
+      });
+    }
+  }
+
+  // 4. Complete message names (event/command/query)
+  private completeMessageNames(
+    context: CompletionContext,
+    acceptor: CompletionAcceptor,
+    msgType: string,
+  ): void {
+    const pluralType = MESSAGE_TYPE_PLURAL[msgType] || "events";
+    const allText = this.getAllWorkspaceText();
+    const names = collectMessageNames(allText, msgType, pluralType);
+
+    const parsedSpecs = this.parseWorkspaceSpecs(context.textDocument.uri);
+    const msgSummaries = new Map<string, string>();
+    for (const [, parsed] of parsedSpecs) {
+      for (const [name, resource] of parsed.messages) {
+        names.add(name);
+        if (resource.summary) msgSummaries.set(name, resource.summary);
+      }
+    }
+
+    for (const name of names) {
+      acceptor(context, {
+        label: name,
+        kind: CompletionItemKind.Field,
+        detail: msgSummaries.get(name) || `${msgType} ${name}`,
+        insertText: name,
+        sortText: `0${name}`,
+      });
+    }
+  }
+
+  // 5. Complete versions after @
+  private completeVersions(
+    context: CompletionContext,
+    acceptor: CompletionAcceptor,
+    msgType: string,
+    resourceName: string,
+  ): void {
+    const allText = this.getAllWorkspaceText();
+    const key = `${msgType}:${resourceName}`;
+    const versions = extractResourceVersions(allText, msgType).get(key) || [];
+
+    for (const ver of versions) {
+      acceptor(context, {
+        label: ver,
+        kind: CompletionItemKind.Value,
+        detail: `Version ${ver} of ${resourceName}`,
+        insertText: ver,
+        sortText: `0${ver}`,
+      });
+    }
+  }
+
+  // ─── Annotation completions ────────────────────────────
+
+  private isAnnotationNameContext(
+    context: CompletionContext,
+    next: NextFeature,
+  ): boolean {
+    const feature = next.feature;
+    if ("rule" in feature && "$type" in feature) {
+      const ruleCall = feature as {
+        $type: string;
+        rule: { ref?: { name?: string } };
+      };
+      if (
+        ruleCall.$type === "RuleCall" &&
+        ruleCall.rule.ref?.name === "AnnotationName"
+      ) {
+        return true;
+      }
+    }
+
+    const text = context.textDocument.getText();
+    const beforeCursor = text.substring(
+      Math.max(0, context.offset - 1),
+      context.offset,
+    );
+    if (beforeCursor === "@") {
+      return true;
+    }
+
+    return false;
+  }
+
+  private completeAnnotationNames(
+    context: CompletionContext,
+    acceptor: CompletionAcceptor,
+  ): void {
+    for (const annotation of ANNOTATION_SUGGESTIONS) {
+      acceptor(context, {
+        label: annotation.label,
+        kind: CompletionItemKind.Snippet,
+        detail: annotation.detail,
+        insertText: annotation.insertText,
+        insertTextFormat: InsertTextFormat.Snippet,
+        sortText: "0" + annotation.label,
+      });
+    }
+  }
+}
diff --git a/packages/language-server/src/ec-definition-provider.ts b/packages/language-server/src/ec-definition-provider.ts
new file mode 100644
index 000000000..6c2ae24e6
--- /dev/null
+++ b/packages/language-server/src/ec-definition-provider.ts
@@ -0,0 +1,178 @@
+import { DefaultDefinitionProvider } from "langium/lsp";
+import type { LangiumServices } from "langium/lsp";
+import type { DefinitionParams } from "vscode-languageserver";
+import { LocationLink, Range } from "vscode-languageserver";
+import type { MaybePromise, LangiumDocument } from "langium";
+import { CstUtils, isCompositeCstNode } from "langium";
+import { existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  extractReference,
+  findResourceDefinition,
+} from "./ec-resource-index.js";
+
+/**
+ * Patterns that contain file paths we want to make clickable.
+ * Each regex must have a single capture group for the path string (with quotes).
+ */
+const PATH_PATTERNS = [
+  /from\s+("(?:[^"\\]|\\.)*")/g, // import ... from "./file.ec"
+  /path:\s*("(?:[^"\\]|\\.)*")/g, // @specification(path: "./spec.yml")
+];
+
+export class EcDefinitionProvider extends DefaultDefinitionProvider {
+  private langiumServices: LangiumServices;
+
+  constructor(services: LangiumServices) {
+    super(services);
+    this.langiumServices = services;
+  }
+
+  override getDefinition(
+    document: LangiumDocument,
+    params: DefinitionParams,
+  ): MaybePromise<LocationLink[] | undefined> {
+    // 1. File path links (import from, @specification path)
+    const pathLink = this.resolvePathLink(document, params);
+    if (pathLink) {
+      return [pathLink];
+    }
+
+    // 2. Resource reference links (sends event X, service Y, etc.)
+    const resourceLink = this.resolveResourceLink(document, params);
+    if (resourceLink) {
+      return [resourceLink];
+    }
+
+    return super.getDefinition(document, params);
+  }
+
+  private resolveResourceLink(
+    document: LangiumDocument,
+    params: DefinitionParams,
+  ): LocationLink | undefined {
+    const rootCst = document.parseResult?.value?.$cstNode;
+    if (!rootCst) return undefined;
+
+    const offset = document.textDocument.offsetAt(params.position);
+    const leaf = CstUtils.findLeafNodeAtOffset(rootCst, offset);
+    if (!leaf) return undefined;
+
+    // Walk up to find the AST node that represents a reference
+    let astNode = leaf.astNode;
+    const ref = extractReference(astNode);
+    if (!ref) {
+      // Try parent — cursor might be on the name inside a ResourceRef
+      if (astNode.$container) {
+        const parentRef = extractReference(astNode.$container);
+        if (parentRef) {
+          astNode = astNode.$container;
+        } else {
+          return undefined;
+        }
+      } else {
+        return undefined;
+      }
+    }
+
+    const reference = extractReference(astNode);
+    if (!reference) return undefined;
+
+    const resolved = findResourceDefinition(
+      this.langiumServices,
+      reference.name,
+      reference.resourceType,
+    );
+    if (!resolved) return undefined;
+
+    // Don't navigate to self
+    const targetCst = resolved.node.$cstNode;
+    if (!targetCst) return undefined;
+    if (
+      resolved.document.uri.toString() === document.uri.toString() &&
+      targetCst.offset === astNode.$cstNode?.offset
+    ) {
+      return undefined;
+    }
+
+    const targetUri = resolved.document.uri.toString();
+    const targetDoc = resolved.document.textDocument;
+    const targetRange = Range.create(
+      targetDoc.positionAt(targetCst.offset),
+      targetDoc.positionAt(targetCst.end),
+    );
+
+    // Try to narrow to the name token for targetSelectionRange
+    let nameRange = targetRange;
+    if (
+      "name" in resolved.node &&
+      typeof resolved.node.name === "string" &&
+      isCompositeCstNode(targetCst)
+    ) {
+      for (const child of targetCst.content) {
+        if ("tokenType" in child && child.text === resolved.node.name) {
+          nameRange = Range.create(
+            targetDoc.positionAt(child.offset),
+            targetDoc.positionAt(child.end),
+          );
+          break;
+        }
+      }
+    }
+
+    const sourceRange = Range.create(
+      document.textDocument.positionAt(leaf.offset),
+      document.textDocument.positionAt(leaf.end),
+    );
+
+    return LocationLink.create(targetUri, targetRange, nameRange, sourceRange);
+  }
+
+  private resolvePathLink(
+    document: LangiumDocument,
+    params: DefinitionParams,
+  ): LocationLink | undefined {
+    const text = document.textDocument.getText();
+    const offset = document.textDocument.offsetAt(params.position);
+
+    for (const pattern of PATH_PATTERNS) {
+      pattern.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = pattern.exec(text)) !== null) {
+        const pathWithQuotes = match[1];
+        const pathStart = match.index + match[0].indexOf(pathWithQuotes);
+        const pathEnd = pathStart + pathWithQuotes.length;
+
+        if (offset >= pathStart && offset <= pathEnd) {
+          const filePath = pathWithQuotes.slice(1, -1);
+          return this.createFileLink(document, filePath, pathStart, pathEnd);
+        }
+      }
+    }
+    return undefined;
+  }
+
+  private createFileLink(
+    document: LangiumDocument,
+    filePath: string,
+    sourceStart: number,
+    sourceEnd: number,
+  ): LocationLink | undefined {
+    const docPath = fileURLToPath(document.uri.toString());
+    const resolved = resolve(dirname(docPath), filePath);
+
+    if (!existsSync(resolved)) {
+      return undefined;
+    }
+
+    const targetUri = pathToFileURL(resolved).toString();
+    const zeroRange = Range.create(0, 0, 0, 0);
+    const sourceRange = Range.create(
+      document.textDocument.positionAt(sourceStart),
+      document.textDocument.positionAt(sourceEnd),
+    );
+
+    return LocationLink.create(targetUri, zeroRange, zeroRange, sourceRange);
+  }
+}
diff --git a/packages/language-server/src/ec-formatter-provider.ts b/packages/language-server/src/ec-formatter-provider.ts
new file mode 100644
index 000000000..90b9157b3
--- /dev/null
+++ b/packages/language-server/src/ec-formatter-provider.ts
@@ -0,0 +1,50 @@
+import type { Formatter } from "langium/lsp";
+import type {
+  DocumentFormattingParams,
+  DocumentOnTypeFormattingOptions,
+  DocumentOnTypeFormattingParams,
+  DocumentRangeFormattingParams,
+  TextEdit,
+} from "vscode-languageserver";
+import { Range } from "vscode-languageserver";
+import type { LangiumDocument } from "langium";
+import { formatEc } from "./formatter.js";
+
+export class EcFormatterProvider implements Formatter {
+  formatDocument(
+    document: LangiumDocument,
+    _params: DocumentFormattingParams,
+  ): TextEdit[] {
+    const text = document.textDocument.getText();
+    const formatted = formatEc(text);
+    if (formatted === text) return [];
+
+    const end = document.textDocument.positionAt(text.length);
+
+    return [
+      {
+        range: Range.create(0, 0, end.line, end.character),
+        newText: formatted,
+      },
+    ];
+  }
+
+  formatDocumentRange(
+    document: LangiumDocument,
+    _params: DocumentRangeFormattingParams,
+  ): TextEdit[] {
+    // For simplicity, format the full document
+    return this.formatDocument(document, _params as DocumentFormattingParams);
+  }
+
+  formatDocumentOnType(
+    _document: LangiumDocument,
+    _params: DocumentOnTypeFormattingParams,
+  ): TextEdit[] {
+    return [];
+  }
+
+  get formatOnTypeOptions(): DocumentOnTypeFormattingOptions | undefined {
+    return undefined;
+  }
+}
diff --git a/packages/language-server/src/ec-hover-provider.ts b/packages/language-server/src/ec-hover-provider.ts
new file mode 100644
index 000000000..09822772b
--- /dev/null
+++ b/packages/language-server/src/ec-hover-provider.ts
@@ -0,0 +1,59 @@
+import type { HoverProvider } from "langium/lsp";
+import type { LangiumServices } from "langium/lsp";
+import type { HoverParams, Hover } from "vscode-languageserver";
+import { MarkupKind } from "vscode-languageserver";
+import type { MaybePromise, LangiumDocument } from "langium";
+import { CstUtils } from "langium";
+import {
+  extractReference,
+  findResourceDefinition,
+  extractResourceInfo,
+  formatResourceHover,
+} from "./ec-resource-index.js";
+
+export class EcHoverProvider implements HoverProvider {
+  private services: LangiumServices;
+
+  constructor(services: LangiumServices) {
+    this.services = services;
+  }
+
+  getHoverContent(
+    document: LangiumDocument,
+    params: HoverParams,
+  ): MaybePromise<Hover | undefined> {
+    const rootCst = document.parseResult?.value?.$cstNode;
+    if (!rootCst) return undefined;
+
+    const offset = document.textDocument.offsetAt(params.position);
+    const leaf = CstUtils.findLeafNodeAtOffset(rootCst, offset);
+    if (!leaf) return undefined;
+
+    // Try the AST node at cursor, then its parent
+    let astNode = leaf.astNode;
+    let ref = extractReference(astNode);
+    if (!ref && astNode.$container) {
+      ref = extractReference(astNode.$container);
+      if (ref) astNode = astNode.$container;
+    }
+    if (!ref) return undefined;
+
+    const resolved = findResourceDefinition(
+      this.services,
+      ref.name,
+      ref.resourceType,
+    );
+    if (!resolved) return undefined;
+
+    const info = extractResourceInfo(resolved);
+    const markdown = formatResourceHover(info);
+
+    return {
+      contents: { kind: MarkupKind.Markdown, value: markdown },
+      range: {
+        start: document.textDocument.positionAt(leaf.offset),
+        end: document.textDocument.positionAt(leaf.end),
+      },
+    };
+  }
+}
diff --git a/packages/language-server/src/ec-module.ts b/packages/language-server/src/ec-module.ts
new file mode 100644
index 000000000..d10b62d0c
--- /dev/null
+++ b/packages/language-server/src/ec-module.ts
@@ -0,0 +1,49 @@
+import {
+  type Module,
+  type LangiumCoreServices,
+  type LangiumSharedCoreServices,
+  type PartialLangiumCoreServices,
+  type DefaultSharedCoreModuleContext,
+  createDefaultCoreModule,
+  createDefaultSharedCoreModule,
+  inject,
+} from "langium";
+import {
+  EcGeneratedModule,
+  EcGeneratedSharedModule,
+} from "./generated/module.js";
+import { registerValidationChecks } from "./ec-validator.js";
+
+export type EcAddedServices = {
+  // Will be extended for custom validators, scoping, etc.
+};
+
+export type EcServices = LangiumCoreServices & EcAddedServices;
+
+export const EcModule: Module<
+  EcServices,
+  PartialLangiumCoreServices & EcAddedServices
+> = {
+  // Custom service overrides go here
+};
+
+/**
+ * Create core (non-LSP) services. Use this for tests, CLI, and compiler.
+ */
+export function createEcServices(context: DefaultSharedCoreModuleContext): {
+  shared: LangiumSharedCoreServices;
+  Ec: EcServices;
+} {
+  const shared = inject(
+    createDefaultSharedCoreModule(context),
+    EcGeneratedSharedModule,
+  );
+  const Ec = inject(
+    createDefaultCoreModule({ shared }),
+    EcGeneratedModule,
+    EcModule,
+  );
+  shared.ServiceRegistry.register(Ec);
+  registerValidationChecks(Ec);
+  return { shared, Ec };
+}
diff --git a/packages/language-server/src/ec-resource-index.ts b/packages/language-server/src/ec-resource-index.ts
new file mode 100644
index 000000000..bfe526cbd
--- /dev/null
+++ b/packages/language-server/src/ec-resource-index.ts
@@ -0,0 +1,438 @@
+/**
+ * Shared resource index: resolves resource names to their definitions
+ * across all workspace .ec documents. Used by both DefinitionProvider and HoverProvider.
+ */
+import type { AstNode, LangiumDocument } from "langium";
+import type { LangiumServices } from "langium/lsp";
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseSpecAuto } from "./completion-utils.js";
+import { isSpecFile } from "./resolvers/resolve.js";
+import { stripQuotes } from "./ast-utils.js";
+import { RESOURCE_TYPE_SINGULAR } from "./resolvers/asyncapi.js";
+import {
+  isProgram,
+  isSendsStmt,
+  isReceivesStmt,
+  isWritesToStmt,
+  isReadsFromStmt,
+  isServiceRefStmt,
+  isDomainRefStmt,
+  isFlowRefStmt,
+  isDataProductRefStmt,
+  isContainerRefStmt,
+  isEventRefStmt,
+  isCommandRefStmt,
+  isQueryRefStmt,
+  isOwnerStmt,
+  isTeamMemberProp,
+  isInputStmt,
+  isResourceRef,
+  isVersionedResourceRef,
+  isEventDef,
+  isCommandDef,
+  isQueryDef,
+  isServiceDef,
+  isDomainDef,
+  isChannelDef,
+  isContainerDef,
+  isDataProductDef,
+  isFlowDef,
+  isUserDef,
+  isTeamDef,
+  isActorDef,
+  isExternalSystemDef,
+  isSubdomainDef,
+  isVisualizerDef,
+  isVersionStmt,
+  isSummaryStmt,
+  isNameStmt,
+  isDeprecatedStmt,
+  isDraftStmt,
+} from "./generated/ast.js";
+import type {
+  EventDef,
+  CommandDef,
+  QueryDef,
+  ServiceDef,
+  DomainDef,
+  ChannelDef,
+  ContainerDef,
+  DataProductDef,
+  FlowDef,
+  UserDef,
+  TeamDef,
+  ActorDef,
+  ExternalSystemDef,
+  SubdomainDef,
+  ImportDecl,
+  Program,
+} from "./generated/ast.js";
+
+/** A resolved resource definition with its containing document. */
+export interface ResolvedResource {
+  node: AstNode;
+  document: LangiumDocument;
+  resourceType: string;
+  name: string;
+  /** For spec-imported resources: metadata from the spec file */
+  specInfo?: SpecImportInfo;
+}
+
+/** Info about a resource imported from a spec file (OpenAPI/AsyncAPI). */
+interface SpecImportInfo {
+  specPath: string;
+  summary?: string;
+  version?: string;
+  description?: string;
+  method?: string;
+  path?: string;
+}
+
+/** Info extracted from a resource reference at the cursor. */
+export interface ResourceReference {
+  name: string;
+  resourceType?: string; // e.g., "event", "service", "container"
+}
+
+// ─── Resource type from AST $type ──────────────────────
+
+type ResourceDefNode =
+  | EventDef
+  | CommandDef
+  | QueryDef
+  | ServiceDef
+  | DomainDef
+  | SubdomainDef
+  | ChannelDef
+  | ContainerDef
+  | DataProductDef
+  | FlowDef
+  | UserDef
+  | TeamDef
+  | ActorDef
+  | ExternalSystemDef;
+
+const DEF_TYPE_MAP: Record<string, string> = {
+  EventDef: "event",
+  CommandDef: "command",
+  QueryDef: "query",
+  ServiceDef: "service",
+  DomainDef: "domain",
+  SubdomainDef: "subdomain",
+  ChannelDef: "channel",
+  ContainerDef: "container",
+  DataProductDef: "data-product",
+  FlowDef: "flow",
+  UserDef: "user",
+  TeamDef: "team",
+  ActorDef: "actor",
+  ExternalSystemDef: "external-system",
+};
+
+function isResourceDef(node: AstNode): node is ResourceDefNode {
+  return node.$type in DEF_TYPE_MAP;
+}
+
+// ─── Extract reference info from an AST node ──────────
+
+/**
+ * Given an AST node, determine if it represents (or contains) a resource reference.
+ * Returns the referenced name + type, or undefined if not a reference context.
+ */
+export function extractReference(node: AstNode): ResourceReference | undefined {
+  if (isSendsStmt(node)) {
+    return { name: node.messageName, resourceType: node.messageType };
+  }
+  if (isReceivesStmt(node)) {
+    return { name: node.messageName, resourceType: node.messageType };
+  }
+  if (isWritesToStmt(node)) {
+    return { name: node.ref.name, resourceType: "container" };
+  }
+  if (isReadsFromStmt(node)) {
+    return { name: node.ref.name, resourceType: "container" };
+  }
+  if (isServiceRefStmt(node)) {
+    return { name: node.ref.name, resourceType: "service" };
+  }
+  if (isDomainRefStmt(node)) {
+    return { name: node.ref.name, resourceType: "domain" };
+  }
+  if (isFlowRefStmt(node)) {
+    return { name: node.ref.name, resourceType: "flow" };
+  }
+  if (isDataProductRefStmt(node)) {
+    return { name: node.ref.name, resourceType: "data-product" };
+  }
+  if (isContainerRefStmt(node)) {
+    return { name: node.ref.name, resourceType: "container" };
+  }
+  if (isEventRefStmt(node)) {
+    return { name: node.ref.name, resourceType: "event" };
+  }
+  if (isCommandRefStmt(node)) {
+    return { name: node.ref.name, resourceType: "command" };
+  }
+  if (isQueryRefStmt(node)) {
+    return { name: node.ref.name, resourceType: "query" };
+  }
+  if (isOwnerStmt(node)) {
+    return { name: node.ownerRef };
+  }
+  if (isTeamMemberProp(node)) {
+    return { name: node.memberRef };
+  }
+  if (isInputStmt(node)) {
+    return { name: node.ref.name, resourceType: node.type };
+  }
+  // ResourceRef / VersionedResourceRef — check parent context
+  if (isResourceRef(node) || isVersionedResourceRef(node)) {
+    const parent = node.$container;
+    if (parent) {
+      const parentRef = extractReference(parent);
+      if (parentRef) return parentRef;
+    }
+    return { name: node.name };
+  }
+  // Check if it's a resource definition itself
+  if (isResourceDef(node)) {
+    return { name: node.name, resourceType: DEF_TYPE_MAP[node.$type] };
+  }
+  return undefined;
+}
+
+// ─── Find resource definitions across workspace ───────
+
+/**
+ * Collect all resource definitions from all .ec documents in the workspace.
+ */
+function collectDefinitions(services: LangiumServices): ResolvedResource[] {
+  const results: ResolvedResource[] = [];
+  const docs = services.shared.workspace.LangiumDocuments.all;
+
+  for (const doc of docs) {
+    if (!doc.uri.path.endsWith(".ec")) continue;
+    const root = doc.parseResult?.value;
+    if (!isProgram(root)) continue;
+    collectFromProgram(root, doc, results);
+  }
+  return results;
+}
+
+function collectFromProgram(
+  program: Program,
+  doc: LangiumDocument,
+  results: ResolvedResource[],
+): void {
+  // Collect DSL-defined resources
+  for (const def of program.definitions) {
+    if (isVisualizerDef(def)) {
+      for (const item of def.body) {
+        collectFromNode(item as AstNode, doc, results);
+      }
+    } else {
+      collectFromNode(def, doc, results);
+    }
+  }
+
+  // Collect resources from import declarations (spec files)
+  for (const imp of program.imports) {
+    collectFromImport(imp, doc, results);
+  }
+}
+
+function collectFromImport(
+  imp: ImportDecl,
+  doc: LangiumDocument,
+  results: ResolvedResource[],
+): void {
+  const specPath = stripQuotes(imp.path);
+  if (!isSpecFile(specPath)) return;
+
+  // Bare imports (no resourceType) use the `import Name from "spec"` form,
+  // which is the grammar's service import syntax.
+  const resourceType = imp.resourceType
+    ? RESOURCE_TYPE_SINGULAR[imp.resourceType]
+    : "service";
+
+  // Read and parse the spec file
+  let specContent: string;
+  try {
+    const docPath = fileURLToPath(doc.uri.toString());
+    const fullPath = resolve(dirname(docPath), specPath);
+    specContent = readFileSync(fullPath, "utf-8");
+  } catch {
+    return;
+  }
+
+  try {
+    const parsed = parseSpecAuto(specContent);
+
+    // Build a lookup of spec resources by name
+    const specResources = new Map<
+      string,
+      {
+        summary?: string;
+        version?: string;
+        description?: string;
+        method?: string;
+        path?: string;
+      }
+    >();
+    for (const [name, msg] of parsed.messages) {
+      specResources.set(name, msg);
+    }
+    for (const [name, ch] of parsed.channels) {
+      specResources.set(name, ch);
+    }
+
+    // Create a ResolvedResource for each imported name
+    for (const item of imp.imports) {
+      const specMsg = specResources.get(item.name);
+      results.push({
+        node: item, // The ImportItem AST node
+        document: doc,
+        resourceType,
+        name: item.name,
+        specInfo: {
+          specPath,
+          summary: specMsg?.summary,
+          version: specMsg?.version,
+          description: specMsg?.description,
+          method: specMsg && "method" in specMsg ? specMsg.method : undefined,
+          path: specMsg && "path" in specMsg ? specMsg.path : undefined,
+        },
+      });
+    }
+  } catch {
+    // Spec parsing failed — still register the imported names without metadata
+    for (const item of imp.imports) {
+      results.push({
+        node: item,
+        document: doc,
+        resourceType,
+        name: item.name,
+        specInfo: { specPath },
+      });
+    }
+  }
+}
+
+function collectFromNode(
+  node: AstNode,
+  doc: LangiumDocument,
+  results: ResolvedResource[],
+): void {
+  if (!isResourceDef(node)) return;
+  const resourceType = DEF_TYPE_MAP[node.$type];
+  results.push({ node, document: doc, resourceType, name: node.name });
+
+  // Recurse into nested definitions (domain → subdomain, etc.)
+  if (isDomainDef(node) || isSubdomainDef(node)) {
+    for (const item of node.body) {
+      collectFromNode(item as AstNode, doc, results);
+    }
+  }
+}
+
+/**
+ * Find a resource definition by name and optional type.
+ */
+export function findResourceDefinition(
+  services: LangiumServices,
+  name: string,
+  resourceType?: string,
+): ResolvedResource | undefined {
+  const defs = collectDefinitions(services);
+  // Prefer exact type match
+  if (resourceType) {
+    const exact = defs.find(
+      (d) => d.name === name && d.resourceType === resourceType,
+    );
+    if (exact) return exact;
+  }
+  // Fall back to name-only match
+  return defs.find((d) => d.name === name);
+}
+
+// ─── Extract metadata from a resource definition ──────
+
+export interface ResourceInfo {
+  resourceType: string;
+  name: string;
+  displayName?: string;
+  version?: string;
+  summary?: string;
+  owner?: string;
+  deprecated?: boolean;
+  draft?: boolean;
+  /** Source spec file for imported resources */
+  specPath?: string;
+  /** HTTP method (OpenAPI imports) */
+  method?: string;
+  /** API path (OpenAPI imports) */
+  apiPath?: string;
+}
+
+/**
+ * Extract human-readable info from a resource definition AST node.
+ */
+export function extractResourceInfo(resolved: ResolvedResource): ResourceInfo {
+  const info: ResourceInfo = {
+    resourceType: resolved.resourceType,
+    name: resolved.name,
+  };
+
+  // Spec-imported resources: use metadata from the spec file
+  if (resolved.specInfo) {
+    info.specPath = resolved.specInfo.specPath;
+    info.summary = resolved.specInfo.summary;
+    info.version = resolved.specInfo.version;
+    info.method = resolved.specInfo.method;
+    info.apiPath = resolved.specInfo.path;
+    return info;
+  }
+
+  const node = resolved.node;
+  // Get body items — most defs have `body`, User/Team have `props`
+  let items: AstNode[] = [];
+  if ("body" in node && Array.isArray(node.body)) {
+    items = node.body;
+  } else if ("props" in node && Array.isArray(node.props)) {
+    items = node.props;
+  }
+
+  for (const item of items) {
+    if (isVersionStmt(item)) info.version = item.value;
+    else if (isSummaryStmt(item)) info.summary = stripQuotes(item.value);
+    else if (isOwnerStmt(item)) info.owner = item.ownerRef;
+    else if (isNameStmt(item)) info.displayName = stripQuotes(item.value);
+    else if (isDeprecatedStmt(item) && item.value) info.deprecated = true;
+    else if (isDraftStmt(item) && item.value) info.draft = true;
+  }
+
+  return info;
+}
+
+/**
+ * Format resource info as a markdown hover tooltip.
+ */
+export function formatResourceHover(info: ResourceInfo): string {
+  const lines: string[] = [];
+
+  const label = info.displayName || info.name;
+  lines.push(`**${info.resourceType}** ${label}`);
+
+  if (info.deprecated) lines.push("\n\n*deprecated*");
+  if (info.draft) lines.push("\n\n*draft*");
+  if (info.method && info.apiPath)
+    lines.push(`\n\n\`${info.method.toUpperCase()} ${info.apiPath}\``);
+  if (info.version) lines.push(`\n\n**Version:** ${info.version}`);
+  if (info.summary) lines.push(`\n\n**Summary:** ${info.summary}`);
+  if (info.owner) lines.push(`\n\n**Owner:** ${info.owner}`);
+  if (info.specPath) lines.push(`\n\n*from ${info.specPath}*`);
+
+  return lines.join("");
+}
diff --git a/packages/language-server/src/ec-scope-provider.ts b/packages/language-server/src/ec-scope-provider.ts
new file mode 100644
index 000000000..3f769a4e8
--- /dev/null
+++ b/packages/language-server/src/ec-scope-provider.ts
@@ -0,0 +1,3 @@
+// Placeholder for custom scope provider
+// Will be implemented for import resolution in multi-file scenarios
+export {};
diff --git a/packages/language-server/src/ec-scope.ts b/packages/language-server/src/ec-scope.ts
new file mode 100644
index 000000000..b9e790459
--- /dev/null
+++ b/packages/language-server/src/ec-scope.ts
@@ -0,0 +1,24 @@
+import type { AstNodeDescription, LangiumDocument } from "langium";
+import { DefaultScopeComputation } from "langium";
+import type { Program } from "./generated/ast.js";
+
+/**
+ * Custom ScopeComputation that exports all top-level ResourceDefinitions.
+ * This enables cross-file reference resolution when imports are used.
+ */
+export class EcScopeComputation extends DefaultScopeComputation {
+  override async computeExports(
+    document: LangiumDocument,
+  ): Promise<AstNodeDescription[]> {
+    const program = document.parseResult.value as Program;
+    const descriptions: AstNodeDescription[] = [];
+    for (const def of program.definitions) {
+      if ("name" in def && typeof def.name === "string") {
+        descriptions.push(
+          this.descriptions.createDescription(def, def.name, document),
+        );
+      }
+    }
+    return descriptions;
+  }
+}
diff --git a/packages/language-server/src/ec-validator.ts b/packages/language-server/src/ec-validator.ts
new file mode 100644
index 000000000..39f9039a0
--- /dev/null
+++ b/packages/language-server/src/ec-validator.ts
@@ -0,0 +1,319 @@
+import type { ValidationAcceptor, ValidationChecks } from "langium";
+import type {
+  EcAstType,
+  Program,
+  ResourceDefinition,
+  DomainDef,
+  SubdomainDef,
+  ServiceDef,
+  SendsStmt,
+  ReceivesStmt,
+} from "./generated/ast.js";
+import type { EcServices } from "./ec-module.js";
+import type { AstNode } from "langium";
+import {
+  isActorDef,
+  isDomainDef,
+  isExternalSystemDef,
+  isSubdomainDef,
+  isServiceDef,
+  isUserDef,
+  isTeamDef,
+  isVisualizerDef,
+  isSendsStmt,
+  isReceivesStmt,
+  isEventDef,
+  isCommandDef,
+  isQueryDef,
+  isChannelDef,
+  isContainerDef,
+  isDataProductDef,
+  isFlowDef,
+} from "./generated/ast.js";
+import { getVersion } from "./ast-utils.js";
+
+export function registerValidationChecks(services: EcServices): void {
+  const registry = services.validation.ValidationRegistry;
+  const validator = new EcValidator();
+  const checks: ValidationChecks<EcAstType> = {
+    Program: [
+      validator.checkDuplicateDefinitions,
+      validator.checkRequiredVersions,
+    ],
+  };
+  registry.register(checks, validator);
+}
+
+export class EcValidator {
+  checkDuplicateDefinitions(
+    program: Program,
+    accept: ValidationAcceptor,
+  ): void {
+    // Resources are uniquely identified by name + version (cross-type).
+    // E.g. event Foo 1.0.0 and query Foo 1.0.0 is a duplicate,
+    // but event Foo 1.0.0 and event Foo 2.0.0 is allowed.
+    const seen = new Map<string, AstNode>();
+
+    for (const def of program.definitions) {
+      if ("name" in def && typeof def.name === "string") {
+        checkAndRegisterDuplicate(
+          seen,
+          def.name,
+          "body" in def && Array.isArray(def.body)
+            ? getVersion(def.body)
+            : undefined,
+          def,
+          "name",
+          accept,
+        );
+
+        // Also check inline definitions nested inside domains/services
+        if (isDomainDef(def) || isSubdomainDef(def)) {
+          checkNestedDuplicates(def.body, seen, accept);
+        }
+        if (isServiceDef(def)) {
+          checkInlineDuplicates(def.body, seen, accept);
+        }
+        if (isVisualizerDef(def)) {
+          checkVisualizerDuplicates(def.body, seen, accept);
+        }
+      }
+    }
+  }
+
+  checkRequiredVersions(program: Program, accept: ValidationAcceptor): void {
+    for (const def of program.definitions) {
+      checkVersionRecursive(def, accept);
+    }
+  }
+}
+
+/** Check if a name+version pair is already in `seen`; if so, emit an error. */
+function checkAndRegisterDuplicate(
+  seen: Map<string, AstNode>,
+  name: string,
+  version: string | undefined,
+  node: AstNode,
+  property: string,
+  accept: ValidationAcceptor,
+): void {
+  const key = version ? `${name}@${version}` : name;
+  if (seen.has(key)) {
+    const label = version ? `'${name}' version ${version}` : `'${name}'`;
+    accept("error", `Duplicate resource definition: ${label}`, {
+      node,
+      property,
+    });
+  } else {
+    seen.set(key, node);
+  }
+}
+
+function checkNestedDuplicates(
+  body: AstNode[],
+  seen: Map<string, AstNode>,
+  accept: ValidationAcceptor,
+): void {
+  for (const item of body) {
+    if (isServiceDef(item)) {
+      checkAndRegisterDuplicate(
+        seen,
+        item.name,
+        getVersion(item.body as AstNode[]),
+        item,
+        "name",
+        accept,
+      );
+      checkInlineDuplicates(item.body as AstNode[], seen, accept);
+    }
+    if (isFlowDef(item)) {
+      checkAndRegisterDuplicate(
+        seen,
+        item.name,
+        getVersion(item.body as AstNode[]),
+        item,
+        "name",
+        accept,
+      );
+    }
+    if (isSubdomainDef(item)) {
+      checkAndRegisterDuplicate(
+        seen,
+        item.name,
+        getVersion(item.body as AstNode[]),
+        item,
+        "name",
+        accept,
+      );
+      checkNestedDuplicates(item.body as AstNode[], seen, accept);
+    }
+  }
+}
+
+function checkInlineDuplicates(
+  body: AstNode[],
+  seen: Map<string, AstNode>,
+  accept: ValidationAcceptor,
+): void {
+  for (const item of body) {
+    if ((isSendsStmt(item) || isReceivesStmt(item)) && item.body.length > 0) {
+      checkAndRegisterDuplicate(
+        seen,
+        item.messageName,
+        getVersion(item.body as AstNode[]),
+        item,
+        "messageName",
+        accept,
+      );
+    }
+  }
+}
+
+function checkVersionRecursive(
+  def: ResourceDefinition | SubdomainDef,
+  accept: ValidationAcceptor,
+): void {
+  // Users, teams, actors, external-systems, and visualizers don't need versions
+  if (
+    isUserDef(def) ||
+    isTeamDef(def) ||
+    isActorDef(def) ||
+    isExternalSystemDef(def) ||
+    isVisualizerDef(def)
+  ) {
+    // But check inline resources inside visualizers
+    if (isVisualizerDef(def)) {
+      for (const item of def.body) {
+        if (
+          isDomainDef(item) ||
+          isServiceDef(item) ||
+          isChannelDef(item) ||
+          isContainerDef(item) ||
+          isDataProductDef(item) ||
+          isFlowDef(item)
+        ) {
+          checkVersionRecursive(item, accept);
+        }
+        if (isEventDef(item) || isCommandDef(item) || isQueryDef(item)) {
+          if (item.body && item.body.length > 0) {
+            const version = getVersion(item.body as AstNode[]);
+            if (!version) {
+              const typeName = item.$type.replace("Def", "");
+              accept(
+                "error",
+                `${typeName} '${item.name}' is missing a required 'version' statement`,
+                {
+                  node: item,
+                  property: "name",
+                },
+              );
+            }
+          }
+        }
+      }
+    }
+    return;
+  }
+
+  if ("body" in def && Array.isArray(def.body)) {
+    const version = getVersion(def.body as AstNode[]);
+    if (!version) {
+      const typeName = def.$type.replace("Def", "");
+      accept(
+        "error",
+        `${typeName} '${def.name}' is missing a required 'version' statement`,
+        {
+          node: def,
+          property: "name",
+        },
+      );
+    }
+
+    // Check nested resources
+    if (isDomainDef(def) || isSubdomainDef(def)) {
+      for (const item of def.body) {
+        if (isServiceDef(item)) checkVersionRecursive(item, accept);
+        if (isFlowDef(item)) checkVersionRecursive(item, accept);
+        if (isSubdomainDef(item)) checkVersionRecursive(item, accept);
+      }
+    }
+
+    if (isServiceDef(def)) {
+      for (const item of def.body) {
+        if (isSendsStmt(item) || isReceivesStmt(item)) {
+          checkInlineMessage(item, accept);
+        }
+      }
+    }
+  }
+}
+
+function checkInlineMessage(
+  clause: SendsStmt | ReceivesStmt,
+  accept: ValidationAcceptor,
+): void {
+  if (clause.body.length > 0) {
+    const version = getVersion(clause.body as AstNode[]);
+    if (!version) {
+      const typeName =
+        clause.messageType.charAt(0).toUpperCase() +
+        clause.messageType.slice(1);
+      accept(
+        "error",
+        `${typeName} '${clause.messageName}' is missing a required 'version' statement`,
+        {
+          node: clause,
+          property: "messageName",
+        },
+      );
+    }
+  }
+}
+
+function checkVisualizerDuplicates(
+  body: AstNode[],
+  seen: Map<string, AstNode>,
+  accept: ValidationAcceptor,
+): void {
+  for (const item of body) {
+    if (
+      isDomainDef(item) ||
+      isServiceDef(item) ||
+      isChannelDef(item) ||
+      isContainerDef(item) ||
+      isDataProductDef(item) ||
+      isFlowDef(item)
+    ) {
+      const itemBody =
+        "body" in item && Array.isArray(item.body)
+          ? (item.body as AstNode[])
+          : [];
+      checkAndRegisterDuplicate(
+        seen,
+        item.name,
+        getVersion(itemBody),
+        item,
+        "name",
+        accept,
+      );
+      if (isServiceDef(item)) {
+        checkInlineDuplicates(item.body as AstNode[], seen, accept);
+      }
+      if (isDomainDef(item)) {
+        checkNestedDuplicates(item.body as AstNode[], seen, accept);
+      }
+    }
+    if (isEventDef(item) || isCommandDef(item) || isQueryDef(item)) {
+      if (item.body && item.body.length > 0) {
+        checkAndRegisterDuplicate(
+          seen,
+          item.name,
+          getVersion(item.body as AstNode[]),
+          item,
+          "name",
+          accept,
+        );
+      }
+    }
+  }
+}
diff --git a/packages/language-server/src/ec.langium b/packages/language-server/src/ec.langium
new file mode 100644
index 000000000..522955ba0
--- /dev/null
+++ b/packages/language-server/src/ec.langium
@@ -0,0 +1,486 @@
+grammar Ec
+
+// ─── Entry ──────────────────────────────────────────────
+entry Program:
+  (imports+=ImportDecl)* (definitions+=ResourceDefinition)*;
+
+ImportDecl:
+  'import' (resourceType=ImportResourceType)? '{' imports+=ImportItem (',' imports+=ImportItem)* '}' 'from' path=STRING
+  | 'import' imports+=ImportItem 'from' path=STRING;
+
+ImportResourceType returns string:
+  'events' | 'commands' | 'queries' | 'channels' | 'services' | 'containers';
+
+ImportItem:
+  name=ID;
+
+// ─── Resource definitions ───────────────────────────────
+ResourceDefinition:
+  DomainDef | ServiceDef | EventDef | CommandDef | QueryDef |
+  ChannelDef | ContainerDef | DataProductDef |
+  FlowDef | DiagramDef | UserDef | TeamDef | VisualizerDef |
+  ActorDef | ExternalSystemDef;
+
+// ─── Domain ─────────────────────────────────────────────
+DomainDef:
+  'domain' name=ID '{' (body+=DomainBodyItem)* '}';
+
+DomainBodyItem:
+  VersionStmt | NameStmt | SummaryStmt | OwnerStmt |
+  DeprecatedStmt | DraftStmt |
+  ServiceDef | SubdomainDef | ContainerDef | ChannelDef | FlowDef |
+  ServiceRefStmt | DataProductRefStmt | FlowRefStmt |
+  SendsStmt | ReceivesStmt | Annotation;
+
+SubdomainDef:
+  'subdomain' name=ID '{' (body+=DomainBodyItem)* '}';
+
+// ─── Service ────────────────────────────────────────────
+ServiceDef:
+  'service' name=ID '{' (body+=ServiceBodyItem)* '}';
+
+ServiceBodyItem:
+  VersionStmt | NameStmt | SummaryStmt | OwnerStmt |
+  DeprecatedStmt | DraftStmt |
+  SendsStmt | ReceivesStmt | WritesToStmt | ReadsFromStmt |
+  FlowRefStmt | Annotation;
+
+// ─── Messages (Event, Command, Query) ───────────────────
+EventDef:
+  'event' name=ID ('{' (body+=MessageBodyItem)* '}')?;
+
+CommandDef:
+  'command' name=ID ('{' (body+=MessageBodyItem)* '}')?;
+
+QueryDef:
+  'query' name=ID ('{' (body+=MessageBodyItem)* '}')?;
+
+MessageBodyItem:
+  VersionStmt | NameStmt | SummaryStmt | OwnerStmt |
+  SchemaStmt | DeprecatedStmt | DraftStmt |
+  Annotation;
+
+// ─── Channel ────────────────────────────────────────────
+ChannelDef:
+  'channel' name=ChannelName '{' (body+=ChannelBodyItem)* '}';
+
+ChannelBodyItem:
+  VersionStmt | NameStmt | SummaryStmt | OwnerStmt |
+  AddressStmt | ProtocolStmt | ParameterDecl |
+  RouteStmt | Annotation;
+
+AddressStmt:
+  'address' value=STRING;
+
+ProtocolStmt:
+  'protocol' value=STRING;
+
+ParameterDecl:
+  'parameter' name=ID '{' (props+=ParameterProp)* '}';
+
+ParameterProp:
+  ParameterDescriptionProp | ParameterDefaultProp | ParameterEnumProp | ParameterExamplesProp;
+
+ParameterDescriptionProp:
+  'description' value=STRING;
+
+ParameterDefaultProp:
+  'default' value=STRING;
+
+ParameterEnumProp:
+  'enum' value=StringArray;
+
+ParameterExamplesProp:
+  'examples' value=StringArray;
+
+StringArray:
+  '[' items+=STRING (',' items+=STRING)* ']';
+
+RouteStmt:
+  'route' ref=ResourceRef;
+
+// ─── Container ──────────────────────────────────────────
+ContainerDef:
+  'container' name=ID '{' (body+=ContainerBodyItem)* '}';
+
+ContainerBodyItem:
+  VersionStmt | NameStmt | SummaryStmt | OwnerStmt | DeprecatedStmt | DraftStmt |
+  ContainerTypeStmt | TechnologyStmt | AuthoritativeStmt |
+  AccessModeStmt | ClassificationStmt | ResidencyStmt |
+  RetentionStmt | ServiceRefStmt | Annotation;
+
+ContainerTypeStmt:
+  'container-type' value=ContainerTypeEnum;
+
+ContainerTypeEnum returns string:
+  'database' | 'cache' | 'objectStore' | 'searchIndex' |
+  'dataWarehouse' | 'dataLake' | 'externalSaaS' | 'other';
+
+TechnologyStmt:
+  'technology' value=STRING;
+
+AuthoritativeStmt:
+  'authoritative' value=BoolLiteral;
+
+AccessModeStmt:
+  'access-mode' value=AccessModeEnum;
+
+AccessModeEnum returns string:
+  'read' | 'write' | 'readWrite' | 'appendOnly';
+
+ClassificationStmt:
+  'classification' value=ClassificationEnum;
+
+ClassificationEnum returns string:
+  'public' | 'internal' | 'confidential' | 'regulated';
+
+ResidencyStmt:
+  'residency' value=STRING;
+
+RetentionStmt:
+  'retention' value=STRING;
+
+// ─── Data Product ───────────────────────────────────────
+DataProductDef:
+  'data-product' name=ID '{' (body+=DataProductBodyItem)* '}';
+
+DataProductBodyItem:
+  VersionStmt | NameStmt | SummaryStmt | OwnerStmt |
+  DeprecatedStmt | DraftStmt |
+  InputStmt | OutputStmt | Annotation;
+
+InputStmt:
+  'input' type=MessageType ref=ResourceRef;
+
+OutputStmt:
+  'output' type=MessageType name=ID ('{' contract=ContractBlock '}')?;
+
+ContractBlock:
+  'contract' '{' 'path' path=STRING 'name' contractName=STRING ('type' contractType=STRING)? '}';
+
+// ─── Flow ───────────────────────────────────────────────
+FlowDef:
+  'flow' name=ID '{' (body+=FlowBodyItem)* '}';
+
+FlowBodyItem:
+  VersionStmt | NameStmt | SummaryStmt | OwnerStmt |
+  FlowWhenBlock | FlowEntryChain | Annotation;
+
+FlowEntryChain:
+  sources+=FlowRef (',' sources+=FlowRef)*
+  ('->' targets+=FlowRef)+;
+
+FlowWhenBlock:
+  'when' triggers+=FlowRef ('and' triggers+=FlowRef)*
+  (actions+=FlowAction)+;
+
+FlowAction:
+  ref=FlowRef (outputs+=FlowOutput)*;
+
+FlowOutput:
+  '->' (label=STRING ':')? target=FlowRef;
+
+FlowRef:
+  name=ID (label=STRING)?;
+
+// ─── Visualizer ─────────────────────────────────────────
+VisualizerDef:
+  'visualizer' name=ID '{' (body+=VisualizerBodyItem)* '}';
+
+VisualizerBodyItem:
+  NameStmt | SummaryStmt | Annotation |
+  LegendStmt | SearchStmt | ToolbarStmt | FocusModeStmt | AnimatedStmt | StyleStmt |
+  DomainDef | ServiceDef | EventDef | CommandDef | QueryDef |
+  ChannelDef | ContainerDef | DataProductDef | FlowDef |
+  ActorDef | ExternalSystemDef |
+  ServiceRefStmt | DomainRefStmt | ChannelRefStmt |
+  EventRefStmt | CommandRefStmt | QueryRefStmt |
+  DataProductRefStmt | FlowRefStmt | ContainerRefStmt;
+
+// ─── Diagram ────────────────────────────────────────────
+DiagramDef:
+  'diagram' name=ID '{' (body+=DiagramBodyItem)* '}';
+
+DiagramBodyItem:
+  VersionStmt | NameStmt | SummaryStmt | OwnerStmt | Annotation;
+
+// ─── User ───────────────────────────────────────────────
+UserDef:
+  'user' name=ID '{' (props+=UserProp)* '}';
+
+UserProp:
+  UserNameProp | UserAvatarProp | UserRoleProp | UserEmailProp |
+  UserSlackProp | UserMsTeamsProp |
+  UserAnnotationProp;
+
+UserNameProp:
+  'name' value=STRING;
+
+UserAvatarProp:
+  'avatar' value=STRING;
+
+UserRoleProp:
+  'role' value=STRING;
+
+UserEmailProp:
+  'email' value=STRING;
+
+UserSlackProp:
+  'slack' value=STRING;
+
+UserMsTeamsProp:
+  'ms-teams' value=STRING;
+
+UserAnnotationProp:
+  annotation=Annotation;
+
+// ─── Team ───────────────────────────────────────────────
+TeamDef:
+  'team' name=ID '{' (props+=TeamProp)* '}';
+
+TeamProp:
+  TeamNameProp | TeamAvatarProp | TeamRoleProp | TeamSummaryProp | TeamEmailProp | TeamSlackProp |
+  TeamMsTeamsProp | TeamMemberProp | TeamAnnotationProp;
+
+TeamNameProp:
+  'name' value=STRING;
+
+TeamAvatarProp:
+  'avatar' value=STRING;
+
+TeamRoleProp:
+  'role' value=STRING;
+
+TeamSummaryProp:
+  'summary' value=STRING;
+
+TeamEmailProp:
+  'email' value=STRING;
+
+TeamSlackProp:
+  'slack' value=STRING;
+
+TeamMsTeamsProp:
+  'ms-teams' value=STRING;
+
+TeamMemberProp:
+  'member' memberRef=ID;
+
+TeamAnnotationProp:
+  annotation=Annotation;
+
+// ─── Actor ─────────────────────────────────────────────
+ActorDef:
+  'actor' name=ID ('{' (body+=ActorBodyItem)* '}')?;
+
+ActorBodyItem:
+  NameStmt | SummaryStmt | Annotation;
+
+// ─── External System ───────────────────────────────────
+ExternalSystemDef:
+  'external-system' name=ID ('{' (body+=ExternalSystemBodyItem)* '}')?;
+
+ExternalSystemBodyItem:
+  NameStmt | SummaryStmt | Annotation;
+
+// ─── Sends / Receives ──────────────────────────────────
+SendsStmt:
+  'sends' messageType=MessageType messageName=ID ('@' version=VERSION)?
+  (channelClause=ChannelClause)?
+  ('{' (body+=SendsReceivesBodyItem)* '}')?;
+
+ReceivesStmt:
+  'receives' messageType=MessageType messageName=ID ('@' version=VERSION)?
+  (channelClause=ChannelClause)?
+  ('{' (body+=SendsReceivesBodyItem)* '}')?;
+
+SendsReceivesBodyItem:
+  VersionStmt | NameStmt | SummaryStmt | OwnerStmt |
+  SchemaStmt | ToClause | FromClause | Annotation;
+
+ChannelClause:
+  ToClause | FromClause;
+
+ToClause:
+  'to' channels+=ChannelRef (',' channels+=ChannelRef)*
+  ('delivery' deliveryMode=DeliveryMode)?;
+
+FromClause:
+  'from' channels+=ChannelRef (',' channels+=ChannelRef)*
+  ('delivery' deliveryMode=DeliveryMode)?;
+
+ChannelRef:
+  channelName=ChannelName ('@' channelVersion=VERSION)?;
+
+DeliveryMode returns string:
+  'push' | 'pull' | 'push-pull';
+
+// ─── Writes-to / Reads-from ────────────────────────────
+WritesToStmt:
+  'writes-to' 'container' ref=ResourceRef;
+
+ReadsFromStmt:
+  'reads-from' 'container' ref=ResourceRef;
+
+// ─── Common statements ─────────────────────────────────
+VersionStmt:
+  'version' value=VERSION;
+
+NameStmt:
+  'name' value=STRING;
+
+SummaryStmt:
+  'summary' value=STRING;
+
+OwnerStmt:
+  'owner' ownerRef=ID;
+
+SchemaStmt:
+  'schema' value=STRING;
+
+DeprecatedStmt:
+  'deprecated' value=BoolLiteral;
+
+DraftStmt:
+  'draft' value=BoolLiteral;
+
+LegendStmt:
+  'legend' value=BoolLiteral;
+
+SearchStmt:
+  'search' value=BoolLiteral;
+
+ToolbarStmt:
+  'toolbar' value=BoolLiteral;
+
+FocusModeStmt:
+  'focus-mode' value=BoolLiteral;
+
+AnimatedStmt:
+  'animated' value=BoolLiteral;
+
+StyleStmt:
+  'style' value=StyleEnum;
+
+StyleEnum returns string:
+  'default' | 'post-it';
+
+ChannelRefStmt:
+  'channel' ref=ChannelResourceRef;
+
+ChannelResourceRef:
+  name=ChannelName ('@' version=VERSION)?;
+
+FlowRefStmt:
+  'flow' ref=ResourceRef;
+
+DataProductRefStmt:
+  'data-product' ref=ResourceRef;
+
+ServiceRefStmt:
+  'service' ref=ResourceRef;
+
+DomainRefStmt:
+  'domain' ref=ResourceRef;
+
+EventRefStmt:
+  'event' ref=VersionedResourceRef;
+
+CommandRefStmt:
+  'command' ref=VersionedResourceRef;
+
+QueryRefStmt:
+  'query' ref=VersionedResourceRef;
+
+ContainerRefStmt:
+  'container' ref=ResourceRef;
+
+ResourceTypeKw returns string:
+  'domain' | 'service' | 'event' | 'command' | 'query';
+
+// ─── Annotations ────────────────────────────────────────
+Annotation:
+  '@' name=AnnotationName
+  ('(' args+=AnnotationArg (',' args+=AnnotationArg)* ')')?
+  ('{' (block+=AnnotationBlockItem)* '}')?;
+
+AnnotationName returns string:
+  ID;
+
+AnnotationArg:
+  NamedAnnotationArg | PositionalAnnotationArg;
+
+NamedAnnotationArg:
+  key=AnnotationKey ':' value=AnnotationValue;
+
+PositionalAnnotationArg:
+  value=AnnotationValue;
+
+AnnotationKey returns string:
+  ID | 'url' | 'type' | 'name' | 'path' | 'label' | 'icon' | 'title' |
+  'color' | 'description' | 'message' | 'version' | 'summary' |
+  'email' | 'slack' | 'role' | 'default';
+
+AnnotationValue:
+  StringAnnotationValue | IdAnnotationValue | NumberAnnotationValue |
+  BoolAnnotationValue | VersionAnnotationValue | KeywordAnnotationValue;
+
+StringAnnotationValue:
+  value=STRING;
+
+IdAnnotationValue:
+  value=ID;
+
+NumberAnnotationValue:
+  value=NUMBER;
+
+BoolAnnotationValue:
+  value=BoolLiteral;
+
+VersionAnnotationValue:
+  value=VERSION;
+
+KeywordAnnotationValue:
+  value=AnnotationKeywordAsValue;
+
+AnnotationKeywordAsValue returns string:
+  'type' | 'name' | 'path' | 'url';
+
+AnnotationBlockItem:
+  ResourceAnnotationBlockItem | KeyValueAnnotationBlockItem;
+
+ResourceAnnotationBlockItem:
+  resourceType=ResourceTypeKw resourceName=ID ('@' version=VERSION)?;
+
+KeyValueAnnotationBlockItem:
+  key=ID value=AnnotationBlockValue;
+
+AnnotationBlockValue returns string:
+  'visible' | 'hidden' | ID | VERSION;
+
+// ─── Shared helpers ─────────────────────────────────────
+MessageType returns string:
+  'event' | 'command' | 'query';
+
+ResourceRef:
+  name=ID ('@' version=VERSION)?;
+
+VersionedResourceRef:
+  name=ID '@' version=VERSION;
+
+BoolLiteral returns boolean:
+  'true' | 'false';
+
+// ─── Channel name (supports template parameters like {env}) ─
+ChannelName returns string:
+  TEMPLATE_ID | ID;
+
+// ─── Terminals ──────────────────────────────────────────
+hidden terminal WS: /\s+/;
+hidden terminal SL_COMMENT: /\/\/[^\n\r]*/;
+hidden terminal ML_COMMENT: /\/\*[\s\S]*?\*\//;
+terminal VERSION: /\d+\.\d+\.\d+(-[a-zA-Z0-9_.]+)*/;
+terminal STRING: /"(?:[^"\\]|\\.)*"/;
+terminal NUMBER: /\d+/;
+terminal TEMPLATE_ID: /[a-zA-Z_][a-zA-Z0-9_.-]*\{[a-zA-Z0-9_]+\}[a-zA-Z0-9_.{}-]*/;
+terminal ID: /[a-zA-Z_][a-zA-Z0-9_.-]*/;
diff --git a/packages/language-server/src/formatter.ts b/packages/language-server/src/formatter.ts
new file mode 100644
index 000000000..ab800253f
--- /dev/null
+++ b/packages/language-server/src/formatter.ts
@@ -0,0 +1,104 @@
+/**
+ * Simple text-based formatter for .ec DSL files.
+ * Uses brace-depth tracking for indentation — no AST needed.
+ */
+export function formatEc(source: string): string {
+  const lines = source.split("\n");
+  const result: string[] = [];
+  const indent = "  "; // 2-space indentation
+  let depth = 0;
+  let prevBlank = false;
+  let inBlockComment = false;
+
+  for (const rawLine of lines) {
+    const trimmed = rawLine.trim();
+
+    // Handle blank lines — collapse multiple into one
+    if (trimmed === "") {
+      if (!prevBlank) {
+        result.push("");
+        prevBlank = true;
+      }
+      continue;
+    }
+    prevBlank = false;
+
+    // Track block comment state
+    if (inBlockComment) {
+      // Inside a block comment, preserve content with current depth
+      result.push(indent.repeat(depth) + trimmed);
+      if (trimmed.includes("*/")) {
+        inBlockComment = false;
+      }
+      continue;
+    }
+
+    if (trimmed.startsWith("/*")) {
+      if (!trimmed.includes("*/")) {
+        inBlockComment = true;
+      }
+      // Decrease depth before printing if line starts with }
+      // (unlikely in a comment opener, but handle gracefully)
+      result.push(indent.repeat(depth) + trimmed);
+      continue;
+    }
+
+    // Decrease depth for closing braces before writing the line
+    if (trimmed.startsWith("}")) {
+      depth = Math.max(0, depth - 1);
+    }
+
+    result.push(indent.repeat(depth) + trimmed);
+
+    // Increase depth for opening braces
+    // Count braces outside of strings and comments
+    const stripped = stripStringsAndComments(trimmed);
+    const opens = (stripped.match(/{/g) || []).length;
+    const closes = (stripped.match(/}/g) || []).length;
+
+    // We already decremented for a leading }, so adjust
+    if (trimmed.startsWith("}")) {
+      // Re-add the one we already subtracted, let the net calculation handle it
+      depth = depth + 1;
+    }
+    depth = Math.max(0, depth + opens - closes);
+  }
+
+  // Remove trailing blank lines
+  while (result.length > 0 && result[result.length - 1] === "") {
+    result.pop();
+  }
+
+  return result.join("\n") + "\n";
+}
+
+/** Strip string literals and line comments from a line for brace counting */
+function stripStringsAndComments(line: string): string {
+  let result = "";
+  let inString: string | null = null;
+
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+
+    if (inString) {
+      if (ch === inString && line[i - 1] !== "\\") {
+        inString = null;
+      }
+      continue;
+    }
+
+    if (ch === '"' || ch === "'") {
+      inString = ch;
+      continue;
+    }
+
+    // Line comment — skip rest
+    if (ch === "/" && line[i + 1] === "/") {
+      break;
+    }
+
+    result += ch;
+  }
+
+  return result;
+}
diff --git a/packages/language-server/src/generated/ast.ts b/packages/language-server/src/generated/ast.ts
new file mode 100644
index 000000000..23f896c6a
--- /dev/null
+++ b/packages/language-server/src/generated/ast.ts
@@ -0,0 +1,2820 @@
+/******************************************************************************
+ * This file was generated by langium-cli 3.5.2.
+ * DO NOT EDIT MANUALLY!
+ ******************************************************************************/
+
+/* eslint-disable */
+import * as langium from 'langium';
+
+export const EcTerminals = {
+    WS: /\s+/,
+    SL_COMMENT: /\/\/[^\n\r]*/,
+    ML_COMMENT: /\/\*[\s\S]*?\*\//,
+    VERSION: /\d+\.\d+\.\d+(-[a-zA-Z0-9_.]+)*/,
+    STRING: /"(?:[^"\\]|\\.)*"/,
+    NUMBER: /\d+/,
+    TEMPLATE_ID: /[a-zA-Z_][a-zA-Z0-9_.-]*\{[a-zA-Z0-9_]+\}[a-zA-Z0-9_.{}-]*/,
+    ID: /[a-zA-Z_][a-zA-Z0-9_.-]*/,
+};
+
+export type EcTerminalNames = keyof typeof EcTerminals;
+
+export type EcKeywordNames =
+    | "("
+    | ")"
+    | ","
+    | "->"
+    | ":"
+    | "@"
+    | "["
+    | "]"
+    | "access-mode"
+    | "actor"
+    | "address"
+    | "and"
+    | "animated"
+    | "appendOnly"
+    | "authoritative"
+    | "avatar"
+    | "cache"
+    | "channel"
+    | "channels"
+    | "classification"
+    | "color"
+    | "command"
+    | "commands"
+    | "confidential"
+    | "container"
+    | "container-type"
+    | "containers"
+    | "contract"
+    | "data-product"
+    | "dataLake"
+    | "dataWarehouse"
+    | "database"
+    | "default"
+    | "delivery"
+    | "deprecated"
+    | "description"
+    | "diagram"
+    | "domain"
+    | "draft"
+    | "email"
+    | "enum"
+    | "event"
+    | "events"
+    | "examples"
+    | "external-system"
+    | "externalSaaS"
+    | "false"
+    | "flow"
+    | "focus-mode"
+    | "from"
+    | "hidden"
+    | "icon"
+    | "import"
+    | "input"
+    | "internal"
+    | "label"
+    | "legend"
+    | "member"
+    | "message"
+    | "ms-teams"
+    | "name"
+    | "objectStore"
+    | "other"
+    | "output"
+    | "owner"
+    | "parameter"
+    | "path"
+    | "post-it"
+    | "protocol"
+    | "public"
+    | "pull"
+    | "push"
+    | "push-pull"
+    | "queries"
+    | "query"
+    | "read"
+    | "readWrite"
+    | "reads-from"
+    | "receives"
+    | "regulated"
+    | "residency"
+    | "retention"
+    | "role"
+    | "route"
+    | "schema"
+    | "search"
+    | "searchIndex"
+    | "sends"
+    | "service"
+    | "services"
+    | "slack"
+    | "style"
+    | "subdomain"
+    | "summary"
+    | "team"
+    | "technology"
+    | "title"
+    | "to"
+    | "toolbar"
+    | "true"
+    | "type"
+    | "url"
+    | "user"
+    | "version"
+    | "visible"
+    | "visualizer"
+    | "when"
+    | "write"
+    | "writes-to"
+    | "{"
+    | "}";
+
+export type EcTokenNames = EcTerminalNames | EcKeywordNames;
+
+export type AccessModeEnum = 'appendOnly' | 'read' | 'readWrite' | 'write';
+
+export function isAccessModeEnum(item: unknown): item is AccessModeEnum {
+    return item === 'read' || item === 'write' || item === 'readWrite' || item === 'appendOnly';
+}
+
+export type ActorBodyItem = Annotation | NameStmt | SummaryStmt;
+
+export const ActorBodyItem = 'ActorBodyItem';
+
+export function isActorBodyItem(item: unknown): item is ActorBodyItem {
+    return reflection.isInstance(item, ActorBodyItem);
+}
+
+export type AnnotationArg = NamedAnnotationArg | PositionalAnnotationArg;
+
+export const AnnotationArg = 'AnnotationArg';
+
+export function isAnnotationArg(item: unknown): item is AnnotationArg {
+    return reflection.isInstance(item, AnnotationArg);
+}
+
+export type AnnotationBlockItem = KeyValueAnnotationBlockItem | ResourceAnnotationBlockItem;
+
+export const AnnotationBlockItem = 'AnnotationBlockItem';
+
+export function isAnnotationBlockItem(item: unknown): item is AnnotationBlockItem {
+    return reflection.isInstance(item, AnnotationBlockItem);
+}
+
+export type AnnotationBlockValue = 'hidden' | 'visible' | string;
+
+export function isAnnotationBlockValue(item: unknown): item is AnnotationBlockValue {
+    return item === 'visible' || item === 'hidden' || (typeof item === 'string' && (/[a-zA-Z_][a-zA-Z0-9_.-]*/.test(item) || /\d+\.\d+\.\d+(-[a-zA-Z0-9_.]+)*/.test(item)));
+}
+
+export type AnnotationKey = 'color' | 'default' | 'description' | 'email' | 'icon' | 'label' | 'message' | 'name' | 'path' | 'role' | 'slack' | 'summary' | 'title' | 'type' | 'url' | 'version' | string;
+
+export function isAnnotationKey(item: unknown): item is AnnotationKey {
+    return item === 'url' || item === 'type' || item === 'name' || item === 'path' || item === 'label' || item === 'icon' || item === 'title' || item === 'color' || item === 'description' || item === 'message' || item === 'version' || item === 'summary' || item === 'email' || item === 'slack' || item === 'role' || item === 'default' || (typeof item === 'string' && (/[a-zA-Z_][a-zA-Z0-9_.-]*/.test(item)));
+}
+
+export type AnnotationKeywordAsValue = 'name' | 'path' | 'type' | 'url';
+
+export function isAnnotationKeywordAsValue(item: unknown): item is AnnotationKeywordAsValue {
+    return item === 'type' || item === 'name' || item === 'path' || item === 'url';
+}
+
+export type AnnotationName = string;
+
+export function isAnnotationName(item: unknown): item is AnnotationName {
+    return (typeof item === 'string' && (/[a-zA-Z_][a-zA-Z0-9_.-]*/.test(item)));
+}
+
+export type AnnotationValue = BoolAnnotationValue | IdAnnotationValue | KeywordAnnotationValue | NumberAnnotationValue | StringAnnotationValue | VersionAnnotationValue;
+
+export const AnnotationValue = 'AnnotationValue';
+
+export function isAnnotationValue(item: unknown): item is AnnotationValue {
+    return reflection.isInstance(item, AnnotationValue);
+}
+
+export type BoolLiteral = boolean;
+
+export function isBoolLiteral(item: unknown): item is BoolLiteral {
+    return typeof item === 'boolean';
+}
+
+export type ChannelBodyItem = AddressStmt | Annotation | NameStmt | OwnerStmt | ParameterDecl | ProtocolStmt | RouteStmt | SummaryStmt | VersionStmt;
+
+export const ChannelBodyItem = 'ChannelBodyItem';
+
+export function isChannelBodyItem(item: unknown): item is ChannelBodyItem {
+    return reflection.isInstance(item, ChannelBodyItem);
+}
+
+export type ChannelClause = FromClause | ToClause;
+
+export const ChannelClause = 'ChannelClause';
+
+export function isChannelClause(item: unknown): item is ChannelClause {
+    return reflection.isInstance(item, ChannelClause);
+}
+
+export type ChannelName = string;
+
+export function isChannelName(item: unknown): item is ChannelName {
+    return (typeof item === 'string' && (/[a-zA-Z_][a-zA-Z0-9_.-]*\{[a-zA-Z0-9_]+\}[a-zA-Z0-9_.{}-]*/.test(item) || /[a-zA-Z_][a-zA-Z0-9_.-]*/.test(item)));
+}
+
+export type ClassificationEnum = 'confidential' | 'internal' | 'public' | 'regulated';
+
+export function isClassificationEnum(item: unknown): item is ClassificationEnum {
+    return item === 'public' || item === 'internal' || item === 'confidential' || item === 'regulated';
+}
+
+export type ContainerBodyItem = AccessModeStmt | Annotation | AuthoritativeStmt | ClassificationStmt | ContainerTypeStmt | DeprecatedStmt | DraftStmt | NameStmt | OwnerStmt | ResidencyStmt | RetentionStmt | ServiceRefStmt | SummaryStmt | TechnologyStmt | VersionStmt;
+
+export const ContainerBodyItem = 'ContainerBodyItem';
+
+export function isContainerBodyItem(item: unknown): item is ContainerBodyItem {
+    return reflection.isInstance(item, ContainerBodyItem);
+}
+
+export type ContainerTypeEnum = 'cache' | 'dataLake' | 'dataWarehouse' | 'database' | 'externalSaaS' | 'objectStore' | 'other' | 'searchIndex';
+
+export function isContainerTypeEnum(item: unknown): item is ContainerTypeEnum {
+    return item === 'database' || item === 'cache' || item === 'objectStore' || item === 'searchIndex' || item === 'dataWarehouse' || item === 'dataLake' || item === 'externalSaaS' || item === 'other';
+}
+
+export type DataProductBodyItem = Annotation | DeprecatedStmt | DraftStmt | InputStmt | NameStmt | OutputStmt | OwnerStmt | SummaryStmt | VersionStmt;
+
+export const DataProductBodyItem = 'DataProductBodyItem';
+
+export function isDataProductBodyItem(item: unknown): item is DataProductBodyItem {
+    return reflection.isInstance(item, DataProductBodyItem);
+}
+
+export type DeliveryMode = 'pull' | 'push' | 'push-pull';
+
+export function isDeliveryMode(item: unknown): item is DeliveryMode {
+    return item === 'push' || item === 'pull' || item === 'push-pull';
+}
+
+export type DiagramBodyItem = Annotation | NameStmt | OwnerStmt | SummaryStmt | VersionStmt;
+
+export const DiagramBodyItem = 'DiagramBodyItem';
+
+export function isDiagramBodyItem(item: unknown): item is DiagramBodyItem {
+    return reflection.isInstance(item, DiagramBodyItem);
+}
+
+export type DomainBodyItem = Annotation | ChannelDef | ContainerDef | DataProductRefStmt | DeprecatedStmt | DraftStmt | FlowDef | FlowRefStmt | NameStmt | OwnerStmt | ReceivesStmt | SendsStmt | ServiceDef | ServiceRefStmt | SubdomainDef | SummaryStmt | VersionStmt;
+
+export const DomainBodyItem = 'DomainBodyItem';
+
+export function isDomainBodyItem(item: unknown): item is DomainBodyItem {
+    return reflection.isInstance(item, DomainBodyItem);
+}
+
+export type ExternalSystemBodyItem = Annotation | NameStmt | SummaryStmt;
+
+export const ExternalSystemBodyItem = 'ExternalSystemBodyItem';
+
+export function isExternalSystemBodyItem(item: unknown): item is ExternalSystemBodyItem {
+    return reflection.isInstance(item, ExternalSystemBodyItem);
+}
+
+export type FlowBodyItem = Annotation | FlowEntryChain | FlowWhenBlock | NameStmt | OwnerStmt | SummaryStmt | VersionStmt;
+
+export const FlowBodyItem = 'FlowBodyItem';
+
+export function isFlowBodyItem(item: unknown): item is FlowBodyItem {
+    return reflection.isInstance(item, FlowBodyItem);
+}
+
+export type ImportResourceType = 'channels' | 'commands' | 'containers' | 'events' | 'queries' | 'services';
+
+export function isImportResourceType(item: unknown): item is ImportResourceType {
+    return item === 'events' || item === 'commands' || item === 'queries' || item === 'channels' || item === 'services' || item === 'containers';
+}
+
+export type MessageBodyItem = Annotation | DeprecatedStmt | DraftStmt | NameStmt | OwnerStmt | SchemaStmt | SummaryStmt | VersionStmt;
+
+export const MessageBodyItem = 'MessageBodyItem';
+
+export function isMessageBodyItem(item: unknown): item is MessageBodyItem {
+    return reflection.isInstance(item, MessageBodyItem);
+}
+
+export type MessageType = 'command' | 'event' | 'query';
+
+export function isMessageType(item: unknown): item is MessageType {
+    return item === 'event' || item === 'command' || item === 'query';
+}
+
+export type ParameterProp = ParameterDefaultProp | ParameterDescriptionProp | ParameterEnumProp | ParameterExamplesProp;
+
+export const ParameterProp = 'ParameterProp';
+
+export function isParameterProp(item: unknown): item is ParameterProp {
+    return reflection.isInstance(item, ParameterProp);
+}
+
+export type ResourceDefinition = ActorDef | ChannelDef | CommandDef | ContainerDef | DataProductDef | DiagramDef | DomainDef | EventDef | ExternalSystemDef | FlowDef | QueryDef | ServiceDef | TeamDef | UserDef | VisualizerDef;
+
+export const ResourceDefinition = 'ResourceDefinition';
+
+export function isResourceDefinition(item: unknown): item is ResourceDefinition {
+    return reflection.isInstance(item, ResourceDefinition);
+}
+
+export type ResourceTypeKw = 'command' | 'domain' | 'event' | 'query' | 'service';
+
+export function isResourceTypeKw(item: unknown): item is ResourceTypeKw {
+    return item === 'domain' || item === 'service' || item === 'event' || item === 'command' || item === 'query';
+}
+
+export type SendsReceivesBodyItem = Annotation | FromClause | NameStmt | OwnerStmt | SchemaStmt | SummaryStmt | ToClause | VersionStmt;
+
+export const SendsReceivesBodyItem = 'SendsReceivesBodyItem';
+
+export function isSendsReceivesBodyItem(item: unknown): item is SendsReceivesBodyItem {
+    return reflection.isInstance(item, SendsReceivesBodyItem);
+}
+
+export type ServiceBodyItem = Annotation | DeprecatedStmt | DraftStmt | FlowRefStmt | NameStmt | OwnerStmt | ReadsFromStmt | ReceivesStmt | SendsStmt | SummaryStmt | VersionStmt | WritesToStmt;
+
+export const ServiceBodyItem = 'ServiceBodyItem';
+
+export function isServiceBodyItem(item: unknown): item is ServiceBodyItem {
+    return reflection.isInstance(item, ServiceBodyItem);
+}
+
+export type StyleEnum = 'default' | 'post-it';
+
+export function isStyleEnum(item: unknown): item is StyleEnum {
+    return item === 'default' || item === 'post-it';
+}
+
+export type TeamProp = TeamAnnotationProp | TeamAvatarProp | TeamEmailProp | TeamMemberProp | TeamMsTeamsProp | TeamNameProp | TeamRoleProp | TeamSlackProp | TeamSummaryProp;
+
+export const TeamProp = 'TeamProp';
+
+export function isTeamProp(item: unknown): item is TeamProp {
+    return reflection.isInstance(item, TeamProp);
+}
+
+export type UserProp = UserAnnotationProp | UserAvatarProp | UserEmailProp | UserMsTeamsProp | UserNameProp | UserRoleProp | UserSlackProp;
+
+export const UserProp = 'UserProp';
+
+export function isUserProp(item: unknown): item is UserProp {
+    return reflection.isInstance(item, UserProp);
+}
+
+export type VisualizerBodyItem = ActorDef | AnimatedStmt | Annotation | ChannelDef | ChannelRefStmt | CommandDef | CommandRefStmt | ContainerDef | ContainerRefStmt | DataProductDef | DataProductRefStmt | DomainDef | DomainRefStmt | EventDef | EventRefStmt | ExternalSystemDef | FlowDef | FlowRefStmt | FocusModeStmt | LegendStmt | NameStmt | QueryDef | QueryRefStmt | SearchStmt | ServiceDef | ServiceRefStmt | StyleStmt | SummaryStmt | ToolbarStmt;
+
+export const VisualizerBodyItem = 'VisualizerBodyItem';
+
+export function isVisualizerBodyItem(item: unknown): item is VisualizerBodyItem {
+    return reflection.isInstance(item, VisualizerBodyItem);
+}
+
+export interface AccessModeStmt extends langium.AstNode {
+    readonly $container: ContainerDef;
+    readonly $type: 'AccessModeStmt';
+    value: AccessModeEnum;
+}
+
+export const AccessModeStmt = 'AccessModeStmt';
+
+export function isAccessModeStmt(item: unknown): item is AccessModeStmt {
+    return reflection.isInstance(item, AccessModeStmt);
+}
+
+export interface ActorDef extends langium.AstNode {
+    readonly $container: Program | VisualizerDef;
+    readonly $type: 'ActorDef';
+    body: Array<ActorBodyItem>;
+    name: string;
+}
+
+export const ActorDef = 'ActorDef';
+
+export function isActorDef(item: unknown): item is ActorDef {
+    return reflection.isInstance(item, ActorDef);
+}
+
+export interface AddressStmt extends langium.AstNode {
+    readonly $container: ChannelDef;
+    readonly $type: 'AddressStmt';
+    value: string;
+}
+
+export const AddressStmt = 'AddressStmt';
+
+export function isAddressStmt(item: unknown): item is AddressStmt {
+    return reflection.isInstance(item, AddressStmt);
+}
+
+export interface AnimatedStmt extends langium.AstNode {
+    readonly $container: VisualizerDef;
+    readonly $type: 'AnimatedStmt';
+    value: BoolLiteral;
+}
+
+export const AnimatedStmt = 'AnimatedStmt';
+
+export function isAnimatedStmt(item: unknown): item is AnimatedStmt {
+    return reflection.isInstance(item, AnimatedStmt);
+}
+
+export interface Annotation extends langium.AstNode {
+    readonly $container: ActorDef | ChannelDef | CommandDef | ContainerDef | DataProductDef | DiagramDef | DomainDef | EventDef | ExternalSystemDef | FlowDef | QueryDef | ReceivesStmt | SendsStmt | ServiceDef | SubdomainDef | TeamAnnotationProp | UserAnnotationProp | VisualizerDef;
+    readonly $type: 'Annotation';
+    args: Array<AnnotationArg>;
+    block: Array<AnnotationBlockItem>;
+    name: AnnotationName;
+}
+
+export const Annotation = 'Annotation';
+
+export function isAnnotation(item: unknown): item is Annotation {
+    return reflection.isInstance(item, Annotation);
+}
+
+export interface AuthoritativeStmt extends langium.AstNode {
+    readonly $container: ContainerDef;
+    readonly $type: 'AuthoritativeStmt';
+    value: BoolLiteral;
+}
+
+export const AuthoritativeStmt = 'AuthoritativeStmt';
+
+export function isAuthoritativeStmt(item: unknown): item is AuthoritativeStmt {
+    return reflection.isInstance(item, AuthoritativeStmt);
+}
+
+export interface BoolAnnotationValue extends langium.AstNode {
+    readonly $container: NamedAnnotationArg | PositionalAnnotationArg;
+    readonly $type: 'BoolAnnotationValue';
+    value: BoolLiteral;
+}
+
+export const BoolAnnotationValue = 'BoolAnnotationValue';
+
+export function isBoolAnnotationValue(item: unknown): item is BoolAnnotationValue {
+    return reflection.isInstance(item, BoolAnnotationValue);
+}
+
+export interface ChannelDef extends langium.AstNode {
+    readonly $container: DomainDef | Program | SubdomainDef | VisualizerDef;
+    readonly $type: 'ChannelDef';
+    body: Array<ChannelBodyItem>;
+    name: ChannelName;
+}
+
+export const ChannelDef = 'ChannelDef';
+
+export function isChannelDef(item: unknown): item is ChannelDef {
+    return reflection.isInstance(item, ChannelDef);
+}
+
+export interface ChannelRef extends langium.AstNode {
+    readonly $container: FromClause | ToClause;
+    readonly $type: 'ChannelRef';
+    channelName: ChannelName;
+    channelVersion?: string;
+}
+
+export const ChannelRef = 'ChannelRef';
+
+export function isChannelRef(item: unknown): item is ChannelRef {
+    return reflection.isInstance(item, ChannelRef);
+}
+
+export interface ChannelRefStmt extends langium.AstNode {
+    readonly $container: VisualizerDef;
+    readonly $type: 'ChannelRefStmt';
+    ref: ChannelResourceRef;
+}
+
+export const ChannelRefStmt = 'ChannelRefStmt';
+
+export function isChannelRefStmt(item: unknown): item is ChannelRefStmt {
+    return reflection.isInstance(item, ChannelRefStmt);
+}
+
+export interface ChannelResourceRef extends langium.AstNode {
+    readonly $container: ChannelRefStmt;
+    readonly $type: 'ChannelResourceRef';
+    name: ChannelName;
+    version?: string;
+}
+
+export const ChannelResourceRef = 'ChannelResourceRef';
+
+export function isChannelResourceRef(item: unknown): item is ChannelResourceRef {
+    return reflection.isInstance(item, ChannelResourceRef);
+}
+
+export interface ClassificationStmt extends langium.AstNode {
+    readonly $container: ContainerDef;
+    readonly $type: 'ClassificationStmt';
+    value: ClassificationEnum;
+}
+
+export const ClassificationStmt = 'ClassificationStmt';
+
+export function isClassificationStmt(item: unknown): item is ClassificationStmt {
+    return reflection.isInstance(item, ClassificationStmt);
+}
+
+export interface CommandDef extends langium.AstNode {
+    readonly $container: Program | VisualizerDef;
+    readonly $type: 'CommandDef';
+    body: Array<MessageBodyItem>;
+    name: string;
+}
+
+export const CommandDef = 'CommandDef';
+
+export function isCommandDef(item: unknown): item is CommandDef {
+    return reflection.isInstance(item, CommandDef);
+}
+
+export interface CommandRefStmt extends langium.AstNode {
+    readonly $container: VisualizerDef;
+    readonly $type: 'CommandRefStmt';
+    ref: VersionedResourceRef;
+}
+
+export const CommandRefStmt = 'CommandRefStmt';
+
+export function isCommandRefStmt(item: unknown): item is CommandRefStmt {
+    return reflection.isInstance(item, CommandRefStmt);
+}
+
+export interface ContainerDef extends langium.AstNode {
+    readonly $container: DomainDef | Program | SubdomainDef | VisualizerDef;
+    readonly $type: 'ContainerDef';
+    body: Array<ContainerBodyItem>;
+    name: string;
+}
+
+export const ContainerDef = 'ContainerDef';
+
+export function isContainerDef(item: unknown): item is ContainerDef {
+    return reflection.isInstance(item, ContainerDef);
+}
+
+export interface ContainerRefStmt extends langium.AstNode {
+    readonly $container: VisualizerDef;
+    readonly $type: 'ContainerRefStmt';
+    ref: ResourceRef;
+}
+
+export const ContainerRefStmt = 'ContainerRefStmt';
+
+export function isContainerRefStmt(item: unknown): item is ContainerRefStmt {
+    return reflection.isInstance(item, ContainerRefStmt);
+}
+
+export interface ContainerTypeStmt extends langium.AstNode {
+    readonly $container: ContainerDef;
+    readonly $type: 'ContainerTypeStmt';
+    value: ContainerTypeEnum;
+}
+
+export const ContainerTypeStmt = 'ContainerTypeStmt';
+
+export function isContainerTypeStmt(item: unknown): item is ContainerTypeStmt {
+    return reflection.isInstance(item, ContainerTypeStmt);
+}
+
+export interface ContractBlock extends langium.AstNode {
+    readonly $container: OutputStmt;
+    readonly $type: 'ContractBlock';
+    contractName: string;
+    contractType?: string;
+    path: string;
+}
+
+export const ContractBlock = 'ContractBlock';
+
+export function isContractBlock(item: unknown): item is ContractBlock {
+    return reflection.isInstance(item, ContractBlock);
+}
+
+export interface DataProductDef extends langium.AstNode {
+    readonly $container: Program | VisualizerDef;
+    readonly $type: 'DataProductDef';
+    body: Array<DataProductBodyItem>;
+    name: string;
+}
+
+export const DataProductDef = 'DataProductDef';
+
+export function isDataProductDef(item: unknown): item is DataProductDef {
+    return reflection.isInstance(item, DataProductDef);
+}
+
+export interface DataProductRefStmt extends langium.AstNode {
+    readonly $container: DomainDef | SubdomainDef | VisualizerDef;
+    readonly $type: 'DataProductRefStmt';
+    ref: ResourceRef;
+}
+
+export const DataProductRefStmt = 'DataProductRefStmt';
+
+export function isDataProductRefStmt(item: unknown): item is DataProductRefStmt {
+    return reflection.isInstance(item, DataProductRefStmt);
+}
+
+export interface DeprecatedStmt extends langium.AstNode {
+    readonly $container: CommandDef | ContainerDef | DataProductDef | DomainDef | EventDef | QueryDef | ServiceDef | SubdomainDef;
+    readonly $type: 'DeprecatedStmt';
+    value: BoolLiteral;
+}
+
+export const DeprecatedStmt = 'DeprecatedStmt';
+
+export function isDeprecatedStmt(item: unknown): item is DeprecatedStmt {
+    return reflection.isInstance(item, DeprecatedStmt);
+}
+
+export interface DiagramDef extends langium.AstNode {
+    readonly $container: Program;
+    readonly $type: 'DiagramDef';
+    body: Array<DiagramBodyItem>;
+    name: string;
+}
+
+export const DiagramDef = 'DiagramDef';
+
+export function isDiagramDef(item: unknown): item is DiagramDef {
+    return reflection.isInstance(item, DiagramDef);
+}
+
+export interface DomainDef extends langium.AstNode {
+    readonly $container: Program | VisualizerDef;
+    readonly $type: 'DomainDef';
+    body: Array<DomainBodyItem>;
+    name: string;
+}
+
+export const DomainDef = 'DomainDef';
+
+export function isDomainDef(item: unknown): item is DomainDef {
+    return reflection.isInstance(item, DomainDef);
+}
+
+export interface DomainRefStmt extends langium.AstNode {
+    readonly $container: VisualizerDef;
+    readonly $type: 'DomainRefStmt';
+    ref: ResourceRef;
+}
+
+export const DomainRefStmt = 'DomainRefStmt';
+
+export function isDomainRefStmt(item: unknown): item is DomainRefStmt {
+    return reflection.isInstance(item, DomainRefStmt);
+}
+
+export interface DraftStmt extends langium.AstNode {
+    readonly $container: CommandDef | ContainerDef | DataProductDef | DomainDef | EventDef | QueryDef | ServiceDef | SubdomainDef;
+    readonly $type: 'DraftStmt';
+    value: BoolLiteral;
+}
+
+export const DraftStmt = 'DraftStmt';
+
+export function isDraftStmt(item: unknown): item is DraftStmt {
+    return reflection.isInstance(item, DraftStmt);
+}
+
+export interface EventDef extends langium.AstNode {
+    readonly $container: Program | VisualizerDef;
+    readonly $type: 'EventDef';
+    body: Array<MessageBodyItem>;
+    name: string;
+}
+
+export const EventDef = 'EventDef';
+
+export function isEventDef(item: unknown): item is EventDef {
+    return reflection.isInstance(item, EventDef);
+}
+
+export interface EventRefStmt extends langium.AstNode {
+    readonly $container: VisualizerDef;
+    readonly $type: 'EventRefStmt';
+    ref: VersionedResourceRef;
+}
+
+export const EventRefStmt = 'EventRefStmt';
+
+export function isEventRefStmt(item: unknown): item is EventRefStmt {
+    return reflection.isInstance(item, EventRefStmt);
+}
+
+export interface ExternalSystemDef extends langium.AstNode {
+    readonly $container: Program | VisualizerDef;
+    readonly $type: 'ExternalSystemDef';
+    body: Array<ExternalSystemBodyItem>;
+    name: string;
+}
+
+export const ExternalSystemDef = 'ExternalSystemDef';
+
+export function isExternalSystemDef(item: unknown): item is ExternalSystemDef {
+    return reflection.isInstance(item, ExternalSystemDef);
+}
+
+export interface FlowAction extends langium.AstNode {
+    readonly $container: FlowWhenBlock;
+    readonly $type: 'FlowAction';
+    outputs: Array<FlowOutput>;
+    ref: FlowRef;
+}
+
+export const FlowAction = 'FlowAction';
+
+export function isFlowAction(item: unknown): item is FlowAction {
+    return reflection.isInstance(item, FlowAction);
+}
+
+export interface FlowDef extends langium.AstNode {
+    readonly $container: DomainDef | Program | SubdomainDef | VisualizerDef;
+    readonly $type: 'FlowDef';
+    body: Array<FlowBodyItem>;
+    name: string;
+}
+
+export const FlowDef = 'FlowDef';
+
+export function isFlowDef(item: unknown): item is FlowDef {
+    return reflection.isInstance(item, FlowDef);
+}
+
+export interface FlowEntryChain extends langium.AstNode {
+    readonly $container: FlowDef;
+    readonly $type: 'FlowEntryChain';
+    sources: Array<FlowRef>;
+    targets: Array<FlowRef>;
+}
+
+export const FlowEntryChain = 'FlowEntryChain';
+
+export function isFlowEntryChain(item: unknown): item is FlowEntryChain {
+    return reflection.isInstance(item, FlowEntryChain);
+}
+
+export interface FlowOutput extends langium.AstNode {
+    readonly $container: FlowAction;
+    readonly $type: 'FlowOutput';
+    label?: string;
+    target: FlowRef;
+}
+
+export const FlowOutput = 'FlowOutput';
+
+export function isFlowOutput(item: unknown): item is FlowOutput {
+    return reflection.isInstance(item, FlowOutput);
+}
+
+export interface FlowRef extends langium.AstNode {
+    readonly $container: FlowAction | FlowEntryChain | FlowOutput | FlowWhenBlock;
+    readonly $type: 'FlowRef';
+    label?: string;
+    name: string;
+}
+
+export const FlowRef = 'FlowRef';
+
+export function isFlowRef(item: unknown): item is FlowRef {
+    return reflection.isInstance(item, FlowRef);
+}
+
+export interface FlowRefStmt extends langium.AstNode {
+    readonly $container: DomainDef | ServiceDef | SubdomainDef | VisualizerDef;
+    readonly $type: 'FlowRefStmt';
+    ref: ResourceRef;
+}
+
+export const FlowRefStmt = 'FlowRefStmt';
+
+export function isFlowRefStmt(item: unknown): item is FlowRefStmt {
+    return reflection.isInstance(item, FlowRefStmt);
+}
+
+export interface FlowWhenBlock extends langium.AstNode {
+    readonly $container: FlowDef;
+    readonly $type: 'FlowWhenBlock';
+    actions: Array<FlowAction>;
+    triggers: Array<FlowRef>;
+}
+
+export const FlowWhenBlock = 'FlowWhenBlock';
+
+export function isFlowWhenBlock(item: unknown): item is FlowWhenBlock {
+    return reflection.isInstance(item, FlowWhenBlock);
+}
+
+export interface FocusModeStmt extends langium.AstNode {
+    readonly $container: VisualizerDef;
+    readonly $type: 'FocusModeStmt';
+    value: BoolLiteral;
+}
+
+export const FocusModeStmt = 'FocusModeStmt';
+
+export function isFocusModeStmt(item: unknown): item is FocusModeStmt {
+    return reflection.isInstance(item, FocusModeStmt);
+}
+
+export interface FromClause extends langium.AstNode {
+    readonly $container: ReceivesStmt | SendsStmt;
+    readonly $type: 'FromClause';
+    channels: Array<ChannelRef>;
+    deliveryMode?: DeliveryMode;
+}
+
+export const FromClause = 'FromClause';
+
+export function isFromClause(item: unknown): item is FromClause {
+    return reflection.isInstance(item, FromClause);
+}
+
+export interface IdAnnotationValue extends langium.AstNode {
+    readonly $container: NamedAnnotationArg | PositionalAnnotationArg;
+    readonly $type: 'IdAnnotationValue';
+    value: string;
+}
+
+export const IdAnnotationValue = 'IdAnnotationValue';
+
+export function isIdAnnotationValue(item: unknown): item is IdAnnotationValue {
+    return reflection.isInstance(item, IdAnnotationValue);
+}
+
+export interface ImportDecl extends langium.AstNode {
+    readonly $container: Program;
+    readonly $type: 'ImportDecl';
+    imports: Array<ImportItem>;
+    path: string;
+    resourceType?: ImportResourceType;
+}
+
+export const ImportDecl = 'ImportDecl';
+
+export function isImportDecl(item: unknown): item is ImportDecl {
+    return reflection.isInstance(item, ImportDecl);
+}
+
+export interface ImportItem extends langium.AstNode {
+    readonly $container: ImportDecl;
+    readonly $type: 'ImportItem';
+    name: string;
+}
+
+export const ImportItem = 'ImportItem';
+
+export function isImportItem(item: unknown): item is ImportItem {
+    return reflection.isInstance(item, ImportItem);
+}
+
+export interface InputStmt extends langium.AstNode {
+    readonly $container: DataProductDef;
+    readonly $type: 'InputStmt';
+    ref: ResourceRef;
+    type: MessageType;
+}
+
+export const InputStmt = 'InputStmt';
+
+export function isInputStmt(item: unknown): item is InputStmt {
+    return reflection.isInstance(item, InputStmt);
+}
+
+export interface KeyValueAnnotationBlockItem extends langium.AstNode {
+    readonly $container: Annotation;
+    readonly $type: 'KeyValueAnnotationBlockItem';
+    key: string;
+    value: AnnotationBlockValue;
+}
+
+export const KeyValueAnnotationBlockItem = 'KeyValueAnnotationBlockItem';
+
+export function isKeyValueAnnotationBlockItem(item: unknown): item is KeyValueAnnotationBlockItem {
+    return reflection.isInstance(item, KeyValueAnnotationBlockItem);
+}
+
+export interface KeywordAnnotationValue extends langium.AstNode {
+    readonly $container: NamedAnnotationArg | PositionalAnnotationArg;
+    readonly $type: 'KeywordAnnotationValue';
+    value: AnnotationKeywordAsValue;
+}
+
+export const KeywordAnnotationValue = 'KeywordAnnotationValue';
+
+export function isKeywordAnnotationValue(item: unknown): item is KeywordAnnotationValue {
+    return reflection.isInstance(item, KeywordAnnotationValue);
+}
+
+export interface LegendStmt extends langium.AstNode {
+    readonly $container: VisualizerDef;
+    readonly $type: 'LegendStmt';
+    value: BoolLiteral;
+}
+
+export const LegendStmt = 'LegendStmt';
+
+export function isLegendStmt(item: unknown): item is LegendStmt {
+    return reflection.isInstance(item, LegendStmt);
+}
+
+export interface NamedAnnotationArg extends langium.AstNode {
+    readonly $container: Annotation;
+    readonly $type: 'NamedAnnotationArg';
+    key: AnnotationKey;
+    value: AnnotationValue;
+}
+
+export const NamedAnnotationArg = 'NamedAnnotationArg';
+
+export function isNamedAnnotationArg(item: unknown): item is NamedAnnotationArg {
+    return reflection.isInstance(item, NamedAnnotationArg);
+}
+
+export interface NameStmt extends langium.AstNode {
+    readonly $container: ActorDef | ChannelDef | CommandDef | ContainerDef | DataProductDef | DiagramDef | DomainDef | EventDef | ExternalSystemDef | FlowDef | QueryDef | ReceivesStmt | SendsStmt | ServiceDef | SubdomainDef | VisualizerDef;
+    readonly $type: 'NameStmt';
+    value: string;
+}
+
+export const NameStmt = 'NameStmt';
+
+export function isNameStmt(item: unknown): item is NameStmt {
+    return reflection.isInstance(item, NameStmt);
+}
+
+export interface NumberAnnotationValue extends langium.AstNode {
+    readonly $container: NamedAnnotationArg | PositionalAnnotationArg;
+    readonly $type: 'NumberAnnotationValue';
+    value: string;
+}
+
+export const NumberAnnotationValue = 'NumberAnnotationValue';
+
+export function isNumberAnnotationValue(item: unknown): item is NumberAnnotationValue {
+    return reflection.isInstance(item, NumberAnnotationValue);
+}
+
+export interface OutputStmt extends langium.AstNode {
+    readonly $container: DataProductDef;
+    readonly $type: 'OutputStmt';
+    contract?: ContractBlock;
+    name: string;
+    type: MessageType;
+}
+
+export const OutputStmt = 'OutputStmt';
+
+export function isOutputStmt(item: unknown): item is OutputStmt {
+    return reflection.isInstance(item, OutputStmt);
+}
+
+export interface OwnerStmt extends langium.AstNode {
+    readonly $container: ChannelDef | CommandDef | ContainerDef | DataProductDef | DiagramDef | DomainDef | EventDef | FlowDef | QueryDef | ReceivesStmt | SendsStmt | ServiceDef | SubdomainDef;
+    readonly $type: 'OwnerStmt';
+    ownerRef: string;
+}
+
+export const OwnerStmt = 'OwnerStmt';
+
+export function isOwnerStmt(item: unknown): item is OwnerStmt {
+    return reflection.isInstance(item, OwnerStmt);
+}
+
+export interface ParameterDecl extends langium.AstNode {
+    readonly $container: ChannelDef;
+    readonly $type: 'ParameterDecl';
+    name: string;
+    props: Array<ParameterProp>;
+}
+
+export const ParameterDecl = 'ParameterDecl';
+
+export function isParameterDecl(item: unknown): item is ParameterDecl {
+    return reflection.isInstance(item, ParameterDecl);
+}
+
+export interface ParameterDefaultProp extends langium.AstNode {
+    readonly $container: ParameterDecl;
+    readonly $type: 'ParameterDefaultProp';
+    value: string;
+}
+
+export const ParameterDefaultProp = 'ParameterDefaultProp';
+
+export function isParameterDefaultProp(item: unknown): item is ParameterDefaultProp {
+    return reflection.isInstance(item, ParameterDefaultProp);
+}
+
+export interface ParameterDescriptionProp extends langium.AstNode {
+    readonly $container: ParameterDecl;
+    readonly $type: 'ParameterDescriptionProp';
+    value: string;
+}
+
+export const ParameterDescriptionProp = 'ParameterDescriptionProp';
+
+export function isParameterDescriptionProp(item: unknown): item is ParameterDescriptionProp {
+    return reflection.isInstance(item, ParameterDescriptionProp);
+}
+
+export interface ParameterEnumProp extends langium.AstNode {
+    readonly $container: ParameterDecl;
+    readonly $type: 'ParameterEnumProp';
+    value: StringArray;
+}
+
+export const ParameterEnumProp = 'ParameterEnumProp';
+
+export function isParameterEnumProp(item: unknown): item is ParameterEnumProp {
+    return reflection.isInstance(item, ParameterEnumProp);
+}
+
+export interface ParameterExamplesProp extends langium.AstNode {
+    readonly $container: ParameterDecl;
+    readonly $type: 'ParameterExamplesProp';
+    value: StringArray;
+}
+
+export const ParameterExamplesProp = 'ParameterExamplesProp';
+
+export function isParameterExamplesProp(item: unknown): item is ParameterExamplesProp {
+    return reflection.isInstance(item, ParameterExamplesProp);
+}
+
+export interface PositionalAnnotationArg extends langium.AstNode {
+    readonly $container: Annotation;
+    readonly $type: 'PositionalAnnotationArg';
+    value: AnnotationValue;
+}
+
+export const PositionalAnnotationArg = 'PositionalAnnotationArg';
+
+export function isPositionalAnnotationArg(item: unknown): item is PositionalAnnotationArg {
+    return reflection.isInstance(item, PositionalAnnotationArg);
+}
+
+export interface Program extends langium.AstNode {
+    readonly $type: 'Program';
+    definitions: Array<ResourceDefinition>;
+    imports: Array<ImportDecl>;
+}
+
+export const Program = 'Program';
+
+export function isProgram(item: unknown): item is Program {
+    return reflection.isInstance(item, Program);
+}
+
+export interface ProtocolStmt extends langium.AstNode {
+    readonly $container: ChannelDef;
+    readonly $type: 'ProtocolStmt';
+    value: string;
+}
+
+export const ProtocolStmt = 'ProtocolStmt';
+
+export function isProtocolStmt(item: unknown): item is ProtocolStmt {
+    return reflection.isInstance(item, ProtocolStmt);
+}
+
+export interface QueryDef extends langium.AstNode {
+    readonly $container: Program | VisualizerDef;
+    readonly $type: 'QueryDef';
+    body: Array<MessageBodyItem>;
+    name: string;
+}
+
+export const QueryDef = 'QueryDef';
+
+export function isQueryDef(item: unknown): item is QueryDef {
+    return reflection.isInstance(item, QueryDef);
+}
+
+export interface QueryRefStmt extends langium.AstNode {
+    readonly $container: VisualizerDef;
+    readonly $type: 'QueryRefStmt';
+    ref: VersionedResourceRef;
+}
+
+export const QueryRefStmt = 'QueryRefStmt';
+
+export function isQueryRefStmt(item: unknown): item is QueryRefStmt {
+    return reflection.isInstance(item, QueryRefStmt);
+}
+
+export interface ReadsFromStmt extends langium.AstNode {
+    readonly $container: ServiceDef;
+    readonly $type: 'ReadsFromStmt';
+    ref: ResourceRef;
+}
+
+export const ReadsFromStmt = 'ReadsFromStmt';
+
+export function isReadsFromStmt(item: unknown): item is ReadsFromStmt {
+    return reflection.isInstance(item, ReadsFromStmt);
+}
+
+export interface ReceivesStmt extends langium.AstNode {
+    readonly $container: DomainDef | ServiceDef | SubdomainDef;
+    readonly $type: 'ReceivesStmt';
+    body: Array<SendsReceivesBodyItem>;
+    channelClause?: ChannelClause;
+    messageName: string;
+    messageType: MessageType;
+    version?: string;
+}
+
+export const ReceivesStmt = 'ReceivesStmt';
+
+export function isReceivesStmt(item: unknown): item is ReceivesStmt {
+    return reflection.isInstance(item, ReceivesStmt);
+}
+
+export interface ResidencyStmt extends langium.AstNode {
+    readonly $container: ContainerDef;
+    readonly $type: 'ResidencyStmt';
+    value: string;
+}
+
+export const ResidencyStmt = 'ResidencyStmt';
+
+export function isResidencyStmt(item: unknown): item is ResidencyStmt {
+    return reflection.isInstance(item, ResidencyStmt);
+}
+
+export interface ResourceAnnotationBlockItem extends langium.AstNode {
+    readonly $container: Annotation;
+    readonly $type: 'ResourceAnnotationBlockItem';
+    resourceName: string;
+    resourceType: ResourceTypeKw;
+    version?: string;
+}
+
+export const ResourceAnnotationBlockItem = 'ResourceAnnotationBlockItem';
+
+export function isResourceAnnotationBlockItem(item: unknown): item is ResourceAnnotationBlockItem {
+    return reflection.isInstance(item, ResourceAnnotationBlockItem);
+}
+
+export interface ResourceRef extends langium.AstNode {
+    readonly $container: ContainerRefStmt | DataProductRefStmt | DomainRefStmt | FlowRefStmt | InputStmt | ReadsFromStmt | RouteStmt | ServiceRefStmt | WritesToStmt;
+    readonly $type: 'ResourceRef';
+    name: string;
+    version?: string;
+}
+
+export const ResourceRef = 'ResourceRef';
+
+export function isResourceRef(item: unknown): item is ResourceRef {
+    return reflection.isInstance(item, ResourceRef);
+}
+
+export interface RetentionStmt extends langium.AstNode {
+    readonly $container: ContainerDef;
+    readonly $type: 'RetentionStmt';
+    value: string;
+}
+
+export const RetentionStmt = 'RetentionStmt';
+
+export function isRetentionStmt(item: unknown): item is RetentionStmt {
+    return reflection.isInstance(item, RetentionStmt);
+}
+
+export interface RouteStmt extends langium.AstNode {
+    readonly $container: ChannelDef;
+    readonly $type: 'RouteStmt';
+    ref: ResourceRef;
+}
+
+export const RouteStmt = 'RouteStmt';
+
+export function isRouteStmt(item: unknown): item is RouteStmt {
+    return reflection.isInstance(item, RouteStmt);
+}
+
+export interface SchemaStmt extends langium.AstNode {
+    readonly $container: CommandDef | EventDef | QueryDef | ReceivesStmt | SendsStmt;
+    readonly $type: 'SchemaStmt';
+    value: string;
+}
+
+export const SchemaStmt = 'SchemaStmt';
+
+export function isSchemaStmt(item: unknown): item is SchemaStmt {
+    return reflection.isInstance(item, SchemaStmt);
+}
+
+export interface SearchStmt extends langium.AstNode {
+    readonly $container: VisualizerDef;
+    readonly $type: 'SearchStmt';
+    value: BoolLiteral;
+}
+
+export const SearchStmt = 'SearchStmt';
+
+export function isSearchStmt(item: unknown): item is SearchStmt {
+    return reflection.isInstance(item, SearchStmt);
+}
+
+export interface SendsStmt extends langium.AstNode {
+    readonly $container: DomainDef | ServiceDef | SubdomainDef;
+    readonly $type: 'SendsStmt';
+    body: Array<SendsReceivesBodyItem>;
+    channelClause?: ChannelClause;
+    messageName: string;
+    messageType: MessageType;
+    version?: string;
+}
+
+export const SendsStmt = 'SendsStmt';
+
+export function isSendsStmt(item: unknown): item is SendsStmt {
+    return reflection.isInstance(item, SendsStmt);
+}
+
+export interface ServiceDef extends langium.AstNode {
+    readonly $container: DomainDef | Program | SubdomainDef | VisualizerDef;
+    readonly $type: 'ServiceDef';
+    body: Array<ServiceBodyItem>;
+    name: string;
+}
+
+export const ServiceDef = 'ServiceDef';
+
+export function isServiceDef(item: unknown): item is ServiceDef {
+    return reflection.isInstance(item, ServiceDef);
+}
+
+export interface ServiceRefStmt extends langium.AstNode {
+    readonly $container: ContainerDef | DomainDef | SubdomainDef | VisualizerDef;
+    readonly $type: 'ServiceRefStmt';
+    ref: ResourceRef;
+}
+
+export const ServiceRefStmt = 'ServiceRefStmt';
+
+export function isServiceRefStmt(item: unknown): item is ServiceRefStmt {
+    return reflection.isInstance(item, ServiceRefStmt);
+}
+
+export interface StringAnnotationValue extends langium.AstNode {
+    readonly $container: NamedAnnotationArg | PositionalAnnotationArg;
+    readonly $type: 'StringAnnotationValue';
+    value: string;
+}
+
+export const StringAnnotationValue = 'StringAnnotationValue';
+
+export function isStringAnnotationValue(item: unknown): item is StringAnnotationValue {
+    return reflection.isInstance(item, StringAnnotationValue);
+}
+
+export interface StringArray extends langium.AstNode {
+    readonly $container: ParameterEnumProp | ParameterExamplesProp;
+    readonly $type: 'StringArray';
+    items: Array<string>;
+}
+
+export const StringArray = 'StringArray';
+
+export function isStringArray(item: unknown): item is StringArray {
+    return reflection.isInstance(item, StringArray);
+}
+
+export interface StyleStmt extends langium.AstNode {
+    readonly $container: VisualizerDef;
+    readonly $type: 'StyleStmt';
+    value: StyleEnum;
+}
+
+export const StyleStmt = 'StyleStmt';
+
+export function isStyleStmt(item: unknown): item is StyleStmt {
+    return reflection.isInstance(item, StyleStmt);
+}
+
+export interface SubdomainDef extends langium.AstNode {
+    readonly $container: DomainDef | SubdomainDef;
+    readonly $type: 'SubdomainDef';
+    body: Array<DomainBodyItem>;
+    name: string;
+}
+
+export const SubdomainDef = 'SubdomainDef';
+
+export function isSubdomainDef(item: unknown): item is SubdomainDef {
+    return reflection.isInstance(item, SubdomainDef);
+}
+
+export interface SummaryStmt extends langium.AstNode {
+    readonly $container: ActorDef | ChannelDef | CommandDef | ContainerDef | DataProductDef | DiagramDef | DomainDef | EventDef | ExternalSystemDef | FlowDef | QueryDef | ReceivesStmt | SendsStmt | ServiceDef | SubdomainDef | VisualizerDef;
+    readonly $type: 'SummaryStmt';
+    value: string;
+}
+
+export const SummaryStmt = 'SummaryStmt';
+
+export function isSummaryStmt(item: unknown): item is SummaryStmt {
+    return reflection.isInstance(item, SummaryStmt);
+}
+
+export interface TeamAnnotationProp extends langium.AstNode {
+    readonly $container: TeamDef;
+    readonly $type: 'TeamAnnotationProp';
+    annotation: Annotation;
+}
+
+export const TeamAnnotationProp = 'TeamAnnotationProp';
+
+export function isTeamAnnotationProp(item: unknown): item is TeamAnnotationProp {
+    return reflection.isInstance(item, TeamAnnotationProp);
+}
+
+export interface TeamAvatarProp extends langium.AstNode {
+    readonly $container: TeamDef;
+    readonly $type: 'TeamAvatarProp';
+    value: string;
+}
+
+export const TeamAvatarProp = 'TeamAvatarProp';
+
+export function isTeamAvatarProp(item: unknown): item is TeamAvatarProp {
+    return reflection.isInstance(item, TeamAvatarProp);
+}
+
+export interface TeamDef extends langium.AstNode {
+    readonly $container: Program;
+    readonly $type: 'TeamDef';
+    name: string;
+    props: Array<TeamProp>;
+}
+
+export const TeamDef = 'TeamDef';
+
+export function isTeamDef(item: unknown): item is TeamDef {
+    return reflection.isInstance(item, TeamDef);
+}
+
+export interface TeamEmailProp extends langium.AstNode {
+    readonly $container: TeamDef;
+    readonly $type: 'TeamEmailProp';
+    value: string;
+}
+
+export const TeamEmailProp = 'TeamEmailProp';
+
+export function isTeamEmailProp(item: unknown): item is TeamEmailProp {
+    return reflection.isInstance(item, TeamEmailProp);
+}
+
+export interface TeamMemberProp extends langium.AstNode {
+    readonly $container: TeamDef;
+    readonly $type: 'TeamMemberProp';
+    memberRef: string;
+}
+
+export const TeamMemberProp = 'TeamMemberProp';
+
+export function isTeamMemberProp(item: unknown): item is TeamMemberProp {
+    return reflection.isInstance(item, TeamMemberProp);
+}
+
+export interface TeamMsTeamsProp extends langium.AstNode {
+    readonly $container: TeamDef;
+    readonly $type: 'TeamMsTeamsProp';
+    value: string;
+}
+
+export const TeamMsTeamsProp = 'TeamMsTeamsProp';
+
+export function isTeamMsTeamsProp(item: unknown): item is TeamMsTeamsProp {
+    return reflection.isInstance(item, TeamMsTeamsProp);
+}
+
+export interface TeamNameProp extends langium.AstNode {
+    readonly $container: TeamDef;
+    readonly $type: 'TeamNameProp';
+    value: string;
+}
+
+export const TeamNameProp = 'TeamNameProp';
+
+export function isTeamNameProp(item: unknown): item is TeamNameProp {
+    return reflection.isInstance(item, TeamNameProp);
+}
+
+export interface TeamRoleProp extends langium.AstNode {
+    readonly $container: TeamDef;
+    readonly $type: 'TeamRoleProp';
+    value: string;
+}
+
+export const TeamRoleProp = 'TeamRoleProp';
+
+export function isTeamRoleProp(item: unknown): item is TeamRoleProp {
+    return reflection.isInstance(item, TeamRoleProp);
+}
+
+export interface TeamSlackProp extends langium.AstNode {
+    readonly $container: TeamDef;
+    readonly $type: 'TeamSlackProp';
+    value: string;
+}
+
+export const TeamSlackProp = 'TeamSlackProp';
+
+export function isTeamSlackProp(item: unknown): item is TeamSlackProp {
+    return reflection.isInstance(item, TeamSlackProp);
+}
+
+export interface TeamSummaryProp extends langium.AstNode {
+    readonly $container: TeamDef;
+    readonly $type: 'TeamSummaryProp';
+    value: string;
+}
+
+export const TeamSummaryProp = 'TeamSummaryProp';
+
+export function isTeamSummaryProp(item: unknown): item is TeamSummaryProp {
+    return reflection.isInstance(item, TeamSummaryProp);
+}
+
+export interface TechnologyStmt extends langium.AstNode {
+    readonly $container: ContainerDef;
+    readonly $type: 'TechnologyStmt';
+    value: string;
+}
+
+export const TechnologyStmt = 'TechnologyStmt';
+
+export function isTechnologyStmt(item: unknown): item is TechnologyStmt {
+    return reflection.isInstance(item, TechnologyStmt);
+}
+
+export interface ToClause extends langium.AstNode {
+    readonly $container: ReceivesStmt | SendsStmt;
+    readonly $type: 'ToClause';
+    channels: Array<ChannelRef>;
+    deliveryMode?: DeliveryMode;
+}
+
+export const ToClause = 'ToClause';
+
+export function isToClause(item: unknown): item is ToClause {
+    return reflection.isInstance(item, ToClause);
+}
+
+export interface ToolbarStmt extends langium.AstNode {
+    readonly $container: VisualizerDef;
+    readonly $type: 'ToolbarStmt';
+    value: BoolLiteral;
+}
+
+export const ToolbarStmt = 'ToolbarStmt';
+
+export function isToolbarStmt(item: unknown): item is ToolbarStmt {
+    return reflection.isInstance(item, ToolbarStmt);
+}
+
+export interface UserAnnotationProp extends langium.AstNode {
+    readonly $container: UserDef;
+    readonly $type: 'UserAnnotationProp';
+    annotation: Annotation;
+}
+
+export const UserAnnotationProp = 'UserAnnotationProp';
+
+export function isUserAnnotationProp(item: unknown): item is UserAnnotationProp {
+    return reflection.isInstance(item, UserAnnotationProp);
+}
+
+export interface UserAvatarProp extends langium.AstNode {
+    readonly $container: UserDef;
+    readonly $type: 'UserAvatarProp';
+    value: string;
+}
+
+export const UserAvatarProp = 'UserAvatarProp';
+
+export function isUserAvatarProp(item: unknown): item is UserAvatarProp {
+    return reflection.isInstance(item, UserAvatarProp);
+}
+
+export interface UserDef extends langium.AstNode {
+    readonly $container: Program;
+    readonly $type: 'UserDef';
+    name: string;
+    props: Array<UserProp>;
+}
+
+export const UserDef = 'UserDef';
+
+export function isUserDef(item: unknown): item is UserDef {
+    return reflection.isInstance(item, UserDef);
+}
+
+export interface UserEmailProp extends langium.AstNode {
+    readonly $container: UserDef;
+    readonly $type: 'UserEmailProp';
+    value: string;
+}
+
+export const UserEmailProp = 'UserEmailProp';
+
+export function isUserEmailProp(item: unknown): item is UserEmailProp {
+    return reflection.isInstance(item, UserEmailProp);
+}
+
+export interface UserMsTeamsProp extends langium.AstNode {
+    readonly $container: UserDef;
+    readonly $type: 'UserMsTeamsProp';
+    value: string;
+}
+
+export const UserMsTeamsProp = 'UserMsTeamsProp';
+
+export function isUserMsTeamsProp(item: unknown): item is UserMsTeamsProp {
+    return reflection.isInstance(item, UserMsTeamsProp);
+}
+
+export interface UserNameProp extends langium.AstNode {
+    readonly $container: UserDef;
+    readonly $type: 'UserNameProp';
+    value: string;
+}
+
+export const UserNameProp = 'UserNameProp';
+
+export function isUserNameProp(item: unknown): item is UserNameProp {
+    return reflection.isInstance(item, UserNameProp);
+}
+
+export interface UserRoleProp extends langium.AstNode {
+    readonly $container: UserDef;
+    readonly $type: 'UserRoleProp';
+    value: string;
+}
+
+export const UserRoleProp = 'UserRoleProp';
+
+export function isUserRoleProp(item: unknown): item is UserRoleProp {
+    return reflection.isInstance(item, UserRoleProp);
+}
+
+export interface UserSlackProp extends langium.AstNode {
+    readonly $container: UserDef;
+    readonly $type: 'UserSlackProp';
+    value: string;
+}
+
+export const UserSlackProp = 'UserSlackProp';
+
+export function isUserSlackProp(item: unknown): item is UserSlackProp {
+    return reflection.isInstance(item, UserSlackProp);
+}
+
+export interface VersionAnnotationValue extends langium.AstNode {
+    readonly $container: NamedAnnotationArg | PositionalAnnotationArg;
+    readonly $type: 'VersionAnnotationValue';
+    value: string;
+}
+
+export const VersionAnnotationValue = 'VersionAnnotationValue';
+
+export function isVersionAnnotationValue(item: unknown): item is VersionAnnotationValue {
+    return reflection.isInstance(item, VersionAnnotationValue);
+}
+
+export interface VersionedResourceRef extends langium.AstNode {
+    readonly $container: CommandRefStmt | EventRefStmt | QueryRefStmt;
+    readonly $type: 'VersionedResourceRef';
+    name: string;
+    version: string;
+}
+
+export const VersionedResourceRef = 'VersionedResourceRef';
+
+export function isVersionedResourceRef(item: unknown): item is VersionedResourceRef {
+    return reflection.isInstance(item, VersionedResourceRef);
+}
+
+export interface VersionStmt extends langium.AstNode {
+    readonly $container: ChannelDef | CommandDef | ContainerDef | DataProductDef | DiagramDef | DomainDef | EventDef | FlowDef | QueryDef | ReceivesStmt | SendsStmt | ServiceDef | SubdomainDef;
+    readonly $type: 'VersionStmt';
+    value: string;
+}
+
+export const VersionStmt = 'VersionStmt';
+
+export function isVersionStmt(item: unknown): item is VersionStmt {
+    return reflection.isInstance(item, VersionStmt);
+}
+
+export interface VisualizerDef extends langium.AstNode {
+    readonly $container: Program;
+    readonly $type: 'VisualizerDef';
+    body: Array<VisualizerBodyItem>;
+    name: string;
+}
+
+export const VisualizerDef = 'VisualizerDef';
+
+export function isVisualizerDef(item: unknown): item is VisualizerDef {
+    return reflection.isInstance(item, VisualizerDef);
+}
+
+export interface WritesToStmt extends langium.AstNode {
+    readonly $container: ServiceDef;
+    readonly $type: 'WritesToStmt';
+    ref: ResourceRef;
+}
+
+export const WritesToStmt = 'WritesToStmt';
+
+export function isWritesToStmt(item: unknown): item is WritesToStmt {
+    return reflection.isInstance(item, WritesToStmt);
+}
+
+export type EcAstType = {
+    AccessModeStmt: AccessModeStmt
+    ActorBodyItem: ActorBodyItem
+    ActorDef: ActorDef
+    AddressStmt: AddressStmt
+    AnimatedStmt: AnimatedStmt
+    Annotation: Annotation
+    AnnotationArg: AnnotationArg
+    AnnotationBlockItem: AnnotationBlockItem
+    AnnotationValue: AnnotationValue
+    AuthoritativeStmt: AuthoritativeStmt
+    BoolAnnotationValue: BoolAnnotationValue
+    ChannelBodyItem: ChannelBodyItem
+    ChannelClause: ChannelClause
+    ChannelDef: ChannelDef
+    ChannelRef: ChannelRef
+    ChannelRefStmt: ChannelRefStmt
+    ChannelResourceRef: ChannelResourceRef
+    ClassificationStmt: ClassificationStmt
+    CommandDef: CommandDef
+    CommandRefStmt: CommandRefStmt
+    ContainerBodyItem: ContainerBodyItem
+    ContainerDef: ContainerDef
+    ContainerRefStmt: ContainerRefStmt
+    ContainerTypeStmt: ContainerTypeStmt
+    ContractBlock: ContractBlock
+    DataProductBodyItem: DataProductBodyItem
+    DataProductDef: DataProductDef
+    DataProductRefStmt: DataProductRefStmt
+    DeprecatedStmt: DeprecatedStmt
+    DiagramBodyItem: DiagramBodyItem
+    DiagramDef: DiagramDef
+    DomainBodyItem: DomainBodyItem
+    DomainDef: DomainDef
+    DomainRefStmt: DomainRefStmt
+    DraftStmt: DraftStmt
+    EventDef: EventDef
+    EventRefStmt: EventRefStmt
+    ExternalSystemBodyItem: ExternalSystemBodyItem
+    ExternalSystemDef: ExternalSystemDef
+    FlowAction: FlowAction
+    FlowBodyItem: FlowBodyItem
+    FlowDef: FlowDef
+    FlowEntryChain: FlowEntryChain
+    FlowOutput: FlowOutput
+    FlowRef: FlowRef
+    FlowRefStmt: FlowRefStmt
+    FlowWhenBlock: FlowWhenBlock
+    FocusModeStmt: FocusModeStmt
+    FromClause: FromClause
+    IdAnnotationValue: IdAnnotationValue
+    ImportDecl: ImportDecl
+    ImportItem: ImportItem
+    InputStmt: InputStmt
+    KeyValueAnnotationBlockItem: KeyValueAnnotationBlockItem
+    KeywordAnnotationValue: KeywordAnnotationValue
+    LegendStmt: LegendStmt
+    MessageBodyItem: MessageBodyItem
+    NameStmt: NameStmt
+    NamedAnnotationArg: NamedAnnotationArg
+    NumberAnnotationValue: NumberAnnotationValue
+    OutputStmt: OutputStmt
+    OwnerStmt: OwnerStmt
+    ParameterDecl: ParameterDecl
+    ParameterDefaultProp: ParameterDefaultProp
+    ParameterDescriptionProp: ParameterDescriptionProp
+    ParameterEnumProp: ParameterEnumProp
+    ParameterExamplesProp: ParameterExamplesProp
+    ParameterProp: ParameterProp
+    PositionalAnnotationArg: PositionalAnnotationArg
+    Program: Program
+    ProtocolStmt: ProtocolStmt
+    QueryDef: QueryDef
+    QueryRefStmt: QueryRefStmt
+    ReadsFromStmt: ReadsFromStmt
+    ReceivesStmt: ReceivesStmt
+    ResidencyStmt: ResidencyStmt
+    ResourceAnnotationBlockItem: ResourceAnnotationBlockItem
+    ResourceDefinition: ResourceDefinition
+    ResourceRef: ResourceRef
+    RetentionStmt: RetentionStmt
+    RouteStmt: RouteStmt
+    SchemaStmt: SchemaStmt
+    SearchStmt: SearchStmt
+    SendsReceivesBodyItem: SendsReceivesBodyItem
+    SendsStmt: SendsStmt
+    ServiceBodyItem: ServiceBodyItem
+    ServiceDef: ServiceDef
+    ServiceRefStmt: ServiceRefStmt
+    StringAnnotationValue: StringAnnotationValue
+    StringArray: StringArray
+    StyleStmt: StyleStmt
+    SubdomainDef: SubdomainDef
+    SummaryStmt: SummaryStmt
+    TeamAnnotationProp: TeamAnnotationProp
+    TeamAvatarProp: TeamAvatarProp
+    TeamDef: TeamDef
+    TeamEmailProp: TeamEmailProp
+    TeamMemberProp: TeamMemberProp
+    TeamMsTeamsProp: TeamMsTeamsProp
+    TeamNameProp: TeamNameProp
+    TeamProp: TeamProp
+    TeamRoleProp: TeamRoleProp
+    TeamSlackProp: TeamSlackProp
+    TeamSummaryProp: TeamSummaryProp
+    TechnologyStmt: TechnologyStmt
+    ToClause: ToClause
+    ToolbarStmt: ToolbarStmt
+    UserAnnotationProp: UserAnnotationProp
+    UserAvatarProp: UserAvatarProp
+    UserDef: UserDef
+    UserEmailProp: UserEmailProp
+    UserMsTeamsProp: UserMsTeamsProp
+    UserNameProp: UserNameProp
+    UserProp: UserProp
+    UserRoleProp: UserRoleProp
+    UserSlackProp: UserSlackProp
+    VersionAnnotationValue: VersionAnnotationValue
+    VersionStmt: VersionStmt
+    VersionedResourceRef: VersionedResourceRef
+    VisualizerBodyItem: VisualizerBodyItem
+    VisualizerDef: VisualizerDef
+    WritesToStmt: WritesToStmt
+}
+
+export class EcAstReflection extends langium.AbstractAstReflection {
+
+    getAllTypes(): string[] {
+        return [AccessModeStmt, ActorBodyItem, ActorDef, AddressStmt, AnimatedStmt, Annotation, AnnotationArg, AnnotationBlockItem, AnnotationValue, AuthoritativeStmt, BoolAnnotationValue, ChannelBodyItem, ChannelClause, ChannelDef, ChannelRef, ChannelRefStmt, ChannelResourceRef, ClassificationStmt, CommandDef, CommandRefStmt, ContainerBodyItem, ContainerDef, ContainerRefStmt, ContainerTypeStmt, ContractBlock, DataProductBodyItem, DataProductDef, DataProductRefStmt, DeprecatedStmt, DiagramBodyItem, DiagramDef, DomainBodyItem, DomainDef, DomainRefStmt, DraftStmt, EventDef, EventRefStmt, ExternalSystemBodyItem, ExternalSystemDef, FlowAction, FlowBodyItem, FlowDef, FlowEntryChain, FlowOutput, FlowRef, FlowRefStmt, FlowWhenBlock, FocusModeStmt, FromClause, IdAnnotationValue, ImportDecl, ImportItem, InputStmt, KeyValueAnnotationBlockItem, KeywordAnnotationValue, LegendStmt, MessageBodyItem, NameStmt, NamedAnnotationArg, NumberAnnotationValue, OutputStmt, OwnerStmt, ParameterDecl, ParameterDefaultProp, ParameterDescriptionProp, ParameterEnumProp, ParameterExamplesProp, ParameterProp, PositionalAnnotationArg, Program, ProtocolStmt, QueryDef, QueryRefStmt, ReadsFromStmt, ReceivesStmt, ResidencyStmt, ResourceAnnotationBlockItem, ResourceDefinition, ResourceRef, RetentionStmt, RouteStmt, SchemaStmt, SearchStmt, SendsReceivesBodyItem, SendsStmt, ServiceBodyItem, ServiceDef, ServiceRefStmt, StringAnnotationValue, StringArray, StyleStmt, SubdomainDef, SummaryStmt, TeamAnnotationProp, TeamAvatarProp, TeamDef, TeamEmailProp, TeamMemberProp, TeamMsTeamsProp, TeamNameProp, TeamProp, TeamRoleProp, TeamSlackProp, TeamSummaryProp, TechnologyStmt, ToClause, ToolbarStmt, UserAnnotationProp, UserAvatarProp, UserDef, UserEmailProp, UserMsTeamsProp, UserNameProp, UserProp, UserRoleProp, UserSlackProp, VersionAnnotationValue, VersionStmt, VersionedResourceRef, VisualizerBodyItem, VisualizerDef, WritesToStmt];
+    }
+
+    protected override computeIsSubtype(subtype: string, supertype: string): boolean {
+        switch (subtype) {
+            case AccessModeStmt:
+            case AuthoritativeStmt:
+            case ClassificationStmt:
+            case ContainerTypeStmt:
+            case ResidencyStmt:
+            case RetentionStmt:
+            case TechnologyStmt: {
+                return this.isSubtype(ContainerBodyItem, supertype);
+            }
+            case ActorDef:
+            case CommandDef:
+            case DataProductDef:
+            case DomainDef:
+            case EventDef:
+            case ExternalSystemDef:
+            case QueryDef: {
+                return this.isSubtype(ResourceDefinition, supertype) || this.isSubtype(VisualizerBodyItem, supertype);
+            }
+            case AddressStmt:
+            case ParameterDecl:
+            case ProtocolStmt:
+            case RouteStmt: {
+                return this.isSubtype(ChannelBodyItem, supertype);
+            }
+            case AnimatedStmt:
+            case ChannelRefStmt:
+            case CommandRefStmt:
+            case ContainerRefStmt:
+            case DomainRefStmt:
+            case EventRefStmt:
+            case FocusModeStmt:
+            case LegendStmt:
+            case QueryRefStmt:
+            case SearchStmt:
+            case StyleStmt:
+            case ToolbarStmt: {
+                return this.isSubtype(VisualizerBodyItem, supertype);
+            }
+            case Annotation:
+            case NameStmt:
+            case SummaryStmt: {
+                return this.isSubtype(ActorBodyItem, supertype) || this.isSubtype(ChannelBodyItem, supertype) || this.isSubtype(ContainerBodyItem, supertype) || this.isSubtype(DataProductBodyItem, supertype) || this.isSubtype(DiagramBodyItem, supertype) || this.isSubtype(DomainBodyItem, supertype) || this.isSubtype(ExternalSystemBodyItem, supertype) || this.isSubtype(FlowBodyItem, supertype) || this.isSubtype(MessageBodyItem, supertype) || this.isSubtype(SendsReceivesBodyItem, supertype) || this.isSubtype(ServiceBodyItem, supertype) || this.isSubtype(VisualizerBodyItem, supertype);
+            }
+            case BoolAnnotationValue:
+            case IdAnnotationValue:
+            case KeywordAnnotationValue:
+            case NumberAnnotationValue:
+            case StringAnnotationValue:
+            case VersionAnnotationValue: {
+                return this.isSubtype(AnnotationValue, supertype);
+            }
+            case ChannelDef:
+            case ContainerDef:
+            case FlowDef:
+            case ServiceDef: {
+                return this.isSubtype(DomainBodyItem, supertype) || this.isSubtype(ResourceDefinition, supertype) || this.isSubtype(VisualizerBodyItem, supertype);
+            }
+            case DataProductRefStmt: {
+                return this.isSubtype(DomainBodyItem, supertype) || this.isSubtype(VisualizerBodyItem, supertype);
+            }
+            case DeprecatedStmt:
+            case DraftStmt: {
+                return this.isSubtype(ContainerBodyItem, supertype) || this.isSubtype(DataProductBodyItem, supertype) || this.isSubtype(DomainBodyItem, supertype) || this.isSubtype(MessageBodyItem, supertype) || this.isSubtype(ServiceBodyItem, supertype);
+            }
+            case DiagramDef:
+            case TeamDef:
+            case UserDef:
+            case VisualizerDef: {
+                return this.isSubtype(ResourceDefinition, supertype);
+            }
+            case FlowEntryChain:
+            case FlowWhenBlock: {
+                return this.isSubtype(FlowBodyItem, supertype);
+            }
+            case FlowRefStmt: {
+                return this.isSubtype(DomainBodyItem, supertype) || this.isSubtype(ServiceBodyItem, supertype) || this.isSubtype(VisualizerBodyItem, supertype);
+            }
+            case FromClause:
+            case ToClause: {
+                return this.isSubtype(ChannelClause, supertype) || this.isSubtype(SendsReceivesBodyItem, supertype);
+            }
+            case InputStmt:
+            case OutputStmt: {
+                return this.isSubtype(DataProductBodyItem, supertype);
+            }
+            case KeyValueAnnotationBlockItem:
+            case ResourceAnnotationBlockItem: {
+                return this.isSubtype(AnnotationBlockItem, supertype);
+            }
+            case NamedAnnotationArg:
+            case PositionalAnnotationArg: {
+                return this.isSubtype(AnnotationArg, supertype);
+            }
+            case OwnerStmt:
+            case VersionStmt: {
+                return this.isSubtype(ChannelBodyItem, supertype) || this.isSubtype(ContainerBodyItem, supertype) || this.isSubtype(DataProductBodyItem, supertype) || this.isSubtype(DiagramBodyItem, supertype) || this.isSubtype(DomainBodyItem, supertype) || this.isSubtype(FlowBodyItem, supertype) || this.isSubtype(MessageBodyItem, supertype) || this.isSubtype(SendsReceivesBodyItem, supertype) || this.isSubtype(ServiceBodyItem, supertype);
+            }
+            case ParameterDefaultProp:
+            case ParameterDescriptionProp:
+            case ParameterEnumProp:
+            case ParameterExamplesProp: {
+                return this.isSubtype(ParameterProp, supertype);
+            }
+            case ReadsFromStmt:
+            case WritesToStmt: {
+                return this.isSubtype(ServiceBodyItem, supertype);
+            }
+            case ReceivesStmt:
+            case SendsStmt: {
+                return this.isSubtype(DomainBodyItem, supertype) || this.isSubtype(ServiceBodyItem, supertype);
+            }
+            case SchemaStmt: {
+                return this.isSubtype(MessageBodyItem, supertype) || this.isSubtype(SendsReceivesBodyItem, supertype);
+            }
+            case ServiceRefStmt: {
+                return this.isSubtype(ContainerBodyItem, supertype) || this.isSubtype(DomainBodyItem, supertype) || this.isSubtype(VisualizerBodyItem, supertype);
+            }
+            case SubdomainDef: {
+                return this.isSubtype(DomainBodyItem, supertype);
+            }
+            case TeamAnnotationProp:
+            case TeamAvatarProp:
+            case TeamEmailProp:
+            case TeamMemberProp:
+            case TeamMsTeamsProp:
+            case TeamNameProp:
+            case TeamRoleProp:
+            case TeamSlackProp:
+            case TeamSummaryProp: {
+                return this.isSubtype(TeamProp, supertype);
+            }
+            case UserAnnotationProp:
+            case UserAvatarProp:
+            case UserEmailProp:
+            case UserMsTeamsProp:
+            case UserNameProp:
+            case UserRoleProp:
+            case UserSlackProp: {
+                return this.isSubtype(UserProp, supertype);
+            }
+            default: {
+                return false;
+            }
+        }
+    }
+
+    getReferenceType(refInfo: langium.ReferenceInfo): string {
+        const referenceId = `${refInfo.container.$type}:${refInfo.property}`;
+        switch (referenceId) {
+            default: {
+                throw new Error(`${referenceId} is not a valid reference id.`);
+            }
+        }
+    }
+
+    getTypeMetaData(type: string): langium.TypeMetaData {
+        switch (type) {
+            case AccessModeStmt: {
+                return {
+                    name: AccessModeStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case ActorDef: {
+                return {
+                    name: ActorDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case AddressStmt: {
+                return {
+                    name: AddressStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case AnimatedStmt: {
+                return {
+                    name: AnimatedStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case Annotation: {
+                return {
+                    name: Annotation,
+                    properties: [
+                        { name: 'args', defaultValue: [] },
+                        { name: 'block', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case AuthoritativeStmt: {
+                return {
+                    name: AuthoritativeStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case BoolAnnotationValue: {
+                return {
+                    name: BoolAnnotationValue,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case ChannelDef: {
+                return {
+                    name: ChannelDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case ChannelRef: {
+                return {
+                    name: ChannelRef,
+                    properties: [
+                        { name: 'channelName' },
+                        { name: 'channelVersion' }
+                    ]
+                };
+            }
+            case ChannelRefStmt: {
+                return {
+                    name: ChannelRefStmt,
+                    properties: [
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            case ChannelResourceRef: {
+                return {
+                    name: ChannelResourceRef,
+                    properties: [
+                        { name: 'name' },
+                        { name: 'version' }
+                    ]
+                };
+            }
+            case ClassificationStmt: {
+                return {
+                    name: ClassificationStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case CommandDef: {
+                return {
+                    name: CommandDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case CommandRefStmt: {
+                return {
+                    name: CommandRefStmt,
+                    properties: [
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            case ContainerDef: {
+                return {
+                    name: ContainerDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case ContainerRefStmt: {
+                return {
+                    name: ContainerRefStmt,
+                    properties: [
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            case ContainerTypeStmt: {
+                return {
+                    name: ContainerTypeStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case ContractBlock: {
+                return {
+                    name: ContractBlock,
+                    properties: [
+                        { name: 'contractName' },
+                        { name: 'contractType' },
+                        { name: 'path' }
+                    ]
+                };
+            }
+            case DataProductDef: {
+                return {
+                    name: DataProductDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case DataProductRefStmt: {
+                return {
+                    name: DataProductRefStmt,
+                    properties: [
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            case DeprecatedStmt: {
+                return {
+                    name: DeprecatedStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case DiagramDef: {
+                return {
+                    name: DiagramDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case DomainDef: {
+                return {
+                    name: DomainDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case DomainRefStmt: {
+                return {
+                    name: DomainRefStmt,
+                    properties: [
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            case DraftStmt: {
+                return {
+                    name: DraftStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case EventDef: {
+                return {
+                    name: EventDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case EventRefStmt: {
+                return {
+                    name: EventRefStmt,
+                    properties: [
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            case ExternalSystemDef: {
+                return {
+                    name: ExternalSystemDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case FlowAction: {
+                return {
+                    name: FlowAction,
+                    properties: [
+                        { name: 'outputs', defaultValue: [] },
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            case FlowDef: {
+                return {
+                    name: FlowDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case FlowEntryChain: {
+                return {
+                    name: FlowEntryChain,
+                    properties: [
+                        { name: 'sources', defaultValue: [] },
+                        { name: 'targets', defaultValue: [] }
+                    ]
+                };
+            }
+            case FlowOutput: {
+                return {
+                    name: FlowOutput,
+                    properties: [
+                        { name: 'label' },
+                        { name: 'target' }
+                    ]
+                };
+            }
+            case FlowRef: {
+                return {
+                    name: FlowRef,
+                    properties: [
+                        { name: 'label' },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case FlowRefStmt: {
+                return {
+                    name: FlowRefStmt,
+                    properties: [
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            case FlowWhenBlock: {
+                return {
+                    name: FlowWhenBlock,
+                    properties: [
+                        { name: 'actions', defaultValue: [] },
+                        { name: 'triggers', defaultValue: [] }
+                    ]
+                };
+            }
+            case FocusModeStmt: {
+                return {
+                    name: FocusModeStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case FromClause: {
+                return {
+                    name: FromClause,
+                    properties: [
+                        { name: 'channels', defaultValue: [] },
+                        { name: 'deliveryMode' }
+                    ]
+                };
+            }
+            case IdAnnotationValue: {
+                return {
+                    name: IdAnnotationValue,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case ImportDecl: {
+                return {
+                    name: ImportDecl,
+                    properties: [
+                        { name: 'imports', defaultValue: [] },
+                        { name: 'path' },
+                        { name: 'resourceType' }
+                    ]
+                };
+            }
+            case ImportItem: {
+                return {
+                    name: ImportItem,
+                    properties: [
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case InputStmt: {
+                return {
+                    name: InputStmt,
+                    properties: [
+                        { name: 'ref' },
+                        { name: 'type' }
+                    ]
+                };
+            }
+            case KeyValueAnnotationBlockItem: {
+                return {
+                    name: KeyValueAnnotationBlockItem,
+                    properties: [
+                        { name: 'key' },
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case KeywordAnnotationValue: {
+                return {
+                    name: KeywordAnnotationValue,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case LegendStmt: {
+                return {
+                    name: LegendStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case NamedAnnotationArg: {
+                return {
+                    name: NamedAnnotationArg,
+                    properties: [
+                        { name: 'key' },
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case NameStmt: {
+                return {
+                    name: NameStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case NumberAnnotationValue: {
+                return {
+                    name: NumberAnnotationValue,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case OutputStmt: {
+                return {
+                    name: OutputStmt,
+                    properties: [
+                        { name: 'contract' },
+                        { name: 'name' },
+                        { name: 'type' }
+                    ]
+                };
+            }
+            case OwnerStmt: {
+                return {
+                    name: OwnerStmt,
+                    properties: [
+                        { name: 'ownerRef' }
+                    ]
+                };
+            }
+            case ParameterDecl: {
+                return {
+                    name: ParameterDecl,
+                    properties: [
+                        { name: 'name' },
+                        { name: 'props', defaultValue: [] }
+                    ]
+                };
+            }
+            case ParameterDefaultProp: {
+                return {
+                    name: ParameterDefaultProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case ParameterDescriptionProp: {
+                return {
+                    name: ParameterDescriptionProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case ParameterEnumProp: {
+                return {
+                    name: ParameterEnumProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case ParameterExamplesProp: {
+                return {
+                    name: ParameterExamplesProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case PositionalAnnotationArg: {
+                return {
+                    name: PositionalAnnotationArg,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case Program: {
+                return {
+                    name: Program,
+                    properties: [
+                        { name: 'definitions', defaultValue: [] },
+                        { name: 'imports', defaultValue: [] }
+                    ]
+                };
+            }
+            case ProtocolStmt: {
+                return {
+                    name: ProtocolStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case QueryDef: {
+                return {
+                    name: QueryDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case QueryRefStmt: {
+                return {
+                    name: QueryRefStmt,
+                    properties: [
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            case ReadsFromStmt: {
+                return {
+                    name: ReadsFromStmt,
+                    properties: [
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            case ReceivesStmt: {
+                return {
+                    name: ReceivesStmt,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'channelClause' },
+                        { name: 'messageName' },
+                        { name: 'messageType' },
+                        { name: 'version' }
+                    ]
+                };
+            }
+            case ResidencyStmt: {
+                return {
+                    name: ResidencyStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case ResourceAnnotationBlockItem: {
+                return {
+                    name: ResourceAnnotationBlockItem,
+                    properties: [
+                        { name: 'resourceName' },
+                        { name: 'resourceType' },
+                        { name: 'version' }
+                    ]
+                };
+            }
+            case ResourceRef: {
+                return {
+                    name: ResourceRef,
+                    properties: [
+                        { name: 'name' },
+                        { name: 'version' }
+                    ]
+                };
+            }
+            case RetentionStmt: {
+                return {
+                    name: RetentionStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case RouteStmt: {
+                return {
+                    name: RouteStmt,
+                    properties: [
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            case SchemaStmt: {
+                return {
+                    name: SchemaStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case SearchStmt: {
+                return {
+                    name: SearchStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case SendsStmt: {
+                return {
+                    name: SendsStmt,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'channelClause' },
+                        { name: 'messageName' },
+                        { name: 'messageType' },
+                        { name: 'version' }
+                    ]
+                };
+            }
+            case ServiceDef: {
+                return {
+                    name: ServiceDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case ServiceRefStmt: {
+                return {
+                    name: ServiceRefStmt,
+                    properties: [
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            case StringAnnotationValue: {
+                return {
+                    name: StringAnnotationValue,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case StringArray: {
+                return {
+                    name: StringArray,
+                    properties: [
+                        { name: 'items', defaultValue: [] }
+                    ]
+                };
+            }
+            case StyleStmt: {
+                return {
+                    name: StyleStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case SubdomainDef: {
+                return {
+                    name: SubdomainDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case SummaryStmt: {
+                return {
+                    name: SummaryStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case TeamAnnotationProp: {
+                return {
+                    name: TeamAnnotationProp,
+                    properties: [
+                        { name: 'annotation' }
+                    ]
+                };
+            }
+            case TeamAvatarProp: {
+                return {
+                    name: TeamAvatarProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case TeamDef: {
+                return {
+                    name: TeamDef,
+                    properties: [
+                        { name: 'name' },
+                        { name: 'props', defaultValue: [] }
+                    ]
+                };
+            }
+            case TeamEmailProp: {
+                return {
+                    name: TeamEmailProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case TeamMemberProp: {
+                return {
+                    name: TeamMemberProp,
+                    properties: [
+                        { name: 'memberRef' }
+                    ]
+                };
+            }
+            case TeamMsTeamsProp: {
+                return {
+                    name: TeamMsTeamsProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case TeamNameProp: {
+                return {
+                    name: TeamNameProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case TeamRoleProp: {
+                return {
+                    name: TeamRoleProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case TeamSlackProp: {
+                return {
+                    name: TeamSlackProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case TeamSummaryProp: {
+                return {
+                    name: TeamSummaryProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case TechnologyStmt: {
+                return {
+                    name: TechnologyStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case ToClause: {
+                return {
+                    name: ToClause,
+                    properties: [
+                        { name: 'channels', defaultValue: [] },
+                        { name: 'deliveryMode' }
+                    ]
+                };
+            }
+            case ToolbarStmt: {
+                return {
+                    name: ToolbarStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case UserAnnotationProp: {
+                return {
+                    name: UserAnnotationProp,
+                    properties: [
+                        { name: 'annotation' }
+                    ]
+                };
+            }
+            case UserAvatarProp: {
+                return {
+                    name: UserAvatarProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case UserDef: {
+                return {
+                    name: UserDef,
+                    properties: [
+                        { name: 'name' },
+                        { name: 'props', defaultValue: [] }
+                    ]
+                };
+            }
+            case UserEmailProp: {
+                return {
+                    name: UserEmailProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case UserMsTeamsProp: {
+                return {
+                    name: UserMsTeamsProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case UserNameProp: {
+                return {
+                    name: UserNameProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case UserRoleProp: {
+                return {
+                    name: UserRoleProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case UserSlackProp: {
+                return {
+                    name: UserSlackProp,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case VersionAnnotationValue: {
+                return {
+                    name: VersionAnnotationValue,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case VersionedResourceRef: {
+                return {
+                    name: VersionedResourceRef,
+                    properties: [
+                        { name: 'name' },
+                        { name: 'version' }
+                    ]
+                };
+            }
+            case VersionStmt: {
+                return {
+                    name: VersionStmt,
+                    properties: [
+                        { name: 'value' }
+                    ]
+                };
+            }
+            case VisualizerDef: {
+                return {
+                    name: VisualizerDef,
+                    properties: [
+                        { name: 'body', defaultValue: [] },
+                        { name: 'name' }
+                    ]
+                };
+            }
+            case WritesToStmt: {
+                return {
+                    name: WritesToStmt,
+                    properties: [
+                        { name: 'ref' }
+                    ]
+                };
+            }
+            default: {
+                return {
+                    name: type,
+                    properties: []
+                };
+            }
+        }
+    }
+}
+
+export const reflection = new EcAstReflection();
diff --git a/packages/language-server/src/generated/grammar.ts b/packages/language-server/src/generated/grammar.ts
new file mode 100644
index 000000000..89b6767a3
--- /dev/null
+++ b/packages/language-server/src/generated/grammar.ts
@@ -0,0 +1,6349 @@
+/******************************************************************************
+ * This file was generated by langium-cli 3.5.2.
+ * DO NOT EDIT MANUALLY!
+ ******************************************************************************/
+
+import type { Grammar } from 'langium';
+import { loadGrammarFromJson } from 'langium';
+
+let loadedEcGrammar: Grammar | undefined;
+export const EcGrammar = (): Grammar => loadedEcGrammar ?? (loadedEcGrammar = loadGrammarFromJson(`{
+  "$type": "Grammar",
+  "isDeclared": true,
+  "name": "Ec",
+  "rules": [
+    {
+      "$type": "ParserRule",
+      "entry": true,
+      "name": "Program",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Assignment",
+            "feature": "imports",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@1"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "definitions",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@4"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ImportDecl",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "import"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "resourceType",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@2"
+                  },
+                  "arguments": []
+                },
+                "cardinality": "?"
+              },
+              {
+                "$type": "Keyword",
+                "value": "{"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "imports",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@3"
+                  },
+                  "arguments": []
+                }
+              },
+              {
+                "$type": "Group",
+                "elements": [
+                  {
+                    "$type": "Keyword",
+                    "value": ","
+                  },
+                  {
+                    "$type": "Assignment",
+                    "feature": "imports",
+                    "operator": "+=",
+                    "terminal": {
+                      "$type": "RuleCall",
+                      "rule": {
+                        "$ref": "#/rules@3"
+                      },
+                      "arguments": []
+                    }
+                  }
+                ],
+                "cardinality": "*"
+              },
+              {
+                "$type": "Keyword",
+                "value": "}"
+              },
+              {
+                "$type": "Keyword",
+                "value": "from"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "path",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@140"
+                  },
+                  "arguments": []
+                }
+              }
+            ]
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "import"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "imports",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@3"
+                  },
+                  "arguments": []
+                }
+              },
+              {
+                "$type": "Keyword",
+                "value": "from"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "path",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@140"
+                  },
+                  "arguments": []
+                }
+              }
+            ]
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ImportResourceType",
+      "dataType": "string",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "events"
+          },
+          {
+            "$type": "Keyword",
+            "value": "commands"
+          },
+          {
+            "$type": "Keyword",
+            "value": "queries"
+          },
+          {
+            "$type": "Keyword",
+            "value": "channels"
+          },
+          {
+            "$type": "Keyword",
+            "value": "services"
+          },
+          {
+            "$type": "Keyword",
+            "value": "containers"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ImportItem",
+      "definition": {
+        "$type": "Assignment",
+        "feature": "name",
+        "operator": "=",
+        "terminal": {
+          "$type": "RuleCall",
+          "rule": {
+            "$ref": "#/rules@143"
+          },
+          "arguments": []
+        }
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ResourceDefinition",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@5"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@8"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@10"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@11"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@12"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@14"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@26"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@38"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@43"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@52"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@54"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@63"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@50"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@74"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@76"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "DomainDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "domain"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "body",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@6"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "DomainBodyItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@88"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@89"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@90"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@91"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@93"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@94"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@8"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@7"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@26"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@14"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@43"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@106"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@105"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@104"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@78"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@79"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@113"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "SubdomainDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "subdomain"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "body",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@6"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ServiceDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "service"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "body",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@9"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ServiceBodyItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@88"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@89"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@90"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@91"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@93"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@94"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@78"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@79"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@86"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@87"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@104"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@113"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "EventDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "event"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "{"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "body",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@13"
+                  },
+                  "arguments": []
+                },
+                "cardinality": "*"
+              },
+              {
+                "$type": "Keyword",
+                "value": "}"
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "CommandDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "command"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "{"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "body",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@13"
+                  },
+                  "arguments": []
+                },
+                "cardinality": "*"
+              },
+              {
+                "$type": "Keyword",
+                "value": "}"
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "QueryDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "query"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "{"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "body",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@13"
+                  },
+                  "arguments": []
+                },
+                "cardinality": "*"
+              },
+              {
+                "$type": "Keyword",
+                "value": "}"
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "MessageBodyItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@88"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@89"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@90"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@91"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@92"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@93"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@94"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@113"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ChannelDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "channel"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@135"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "body",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@15"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ChannelBodyItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@88"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@89"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@90"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@91"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@16"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@17"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@18"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@25"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@113"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "AddressStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "address"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ProtocolStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "protocol"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ParameterDecl",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "parameter"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "props",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@19"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ParameterProp",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@20"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@21"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@22"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@23"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ParameterDescriptionProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "description"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ParameterDefaultProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "default"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ParameterEnumProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "enum"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@24"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ParameterExamplesProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "examples"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@24"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "StringArray",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "["
+          },
+          {
+            "$type": "Assignment",
+            "feature": "items",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": ","
+              },
+              {
+                "$type": "Assignment",
+                "feature": "items",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@140"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "]"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "RouteStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "route"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@132"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ContainerDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "container"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "body",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@27"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ContainerBodyItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@88"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@89"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@90"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@91"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@93"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@94"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@28"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@30"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@31"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@32"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@34"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@36"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@37"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@106"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@113"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ContainerTypeStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "container-type"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@29"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ContainerTypeEnum",
+      "dataType": "string",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "database"
+          },
+          {
+            "$type": "Keyword",
+            "value": "cache"
+          },
+          {
+            "$type": "Keyword",
+            "value": "objectStore"
+          },
+          {
+            "$type": "Keyword",
+            "value": "searchIndex"
+          },
+          {
+            "$type": "Keyword",
+            "value": "dataWarehouse"
+          },
+          {
+            "$type": "Keyword",
+            "value": "dataLake"
+          },
+          {
+            "$type": "Keyword",
+            "value": "externalSaaS"
+          },
+          {
+            "$type": "Keyword",
+            "value": "other"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "TechnologyStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "technology"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "AuthoritativeStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "authoritative"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@134"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "AccessModeStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "access-mode"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@33"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "AccessModeEnum",
+      "dataType": "string",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "read"
+          },
+          {
+            "$type": "Keyword",
+            "value": "write"
+          },
+          {
+            "$type": "Keyword",
+            "value": "readWrite"
+          },
+          {
+            "$type": "Keyword",
+            "value": "appendOnly"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ClassificationStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "classification"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@35"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ClassificationEnum",
+      "dataType": "string",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "public"
+          },
+          {
+            "$type": "Keyword",
+            "value": "internal"
+          },
+          {
+            "$type": "Keyword",
+            "value": "confidential"
+          },
+          {
+            "$type": "Keyword",
+            "value": "regulated"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ResidencyStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "residency"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "RetentionStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "retention"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "DataProductDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "data-product"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "body",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@39"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "DataProductBodyItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@88"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@89"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@90"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@91"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@93"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@94"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@40"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@41"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@113"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "InputStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "input"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "type",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@131"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@132"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "OutputStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "output"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "type",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@131"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "{"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "contract",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@42"
+                  },
+                  "arguments": []
+                }
+              },
+              {
+                "$type": "Keyword",
+                "value": "}"
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ContractBlock",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "contract"
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Keyword",
+            "value": "path"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "path",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "name"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "contractName",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "type"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "contractType",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@140"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "?"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "FlowDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "flow"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "body",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@44"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "FlowBodyItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@88"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@89"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@90"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@91"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@46"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@45"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@113"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "FlowEntryChain",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Assignment",
+            "feature": "sources",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@49"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": ","
+              },
+              {
+                "$type": "Assignment",
+                "feature": "sources",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@49"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "*"
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "->"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "targets",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@49"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "+"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "FlowWhenBlock",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "when"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "triggers",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@49"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "and"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "triggers",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@49"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "*"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "actions",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@47"
+              },
+              "arguments": []
+            },
+            "cardinality": "+"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "FlowAction",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@49"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Assignment",
+            "feature": "outputs",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@48"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "FlowOutput",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "->"
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Assignment",
+                "feature": "label",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@140"
+                  },
+                  "arguments": []
+                }
+              },
+              {
+                "$type": "Keyword",
+                "value": ":"
+              }
+            ],
+            "cardinality": "?"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "target",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@49"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "FlowRef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Assignment",
+            "feature": "label",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            },
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "VisualizerDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "visualizer"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "body",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@51"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "VisualizerBodyItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@89"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@90"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@113"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@95"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@96"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@97"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@98"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@99"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@100"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@5"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@8"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@10"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@11"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@12"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@14"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@26"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@38"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@43"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@74"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@76"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@106"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@107"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@102"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@108"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@109"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@110"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@105"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@104"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@111"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "DiagramDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "diagram"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "body",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@53"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "DiagramBodyItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@88"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@89"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@90"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@91"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@113"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "UserDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "user"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "props",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@55"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "UserProp",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@56"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@57"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@58"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@59"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@60"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@61"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@62"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "UserNameProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "name"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "UserAvatarProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "avatar"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "UserRoleProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "role"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "UserEmailProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "email"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "UserSlackProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "slack"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "UserMsTeamsProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "ms-teams"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "UserAnnotationProp",
+      "definition": {
+        "$type": "Assignment",
+        "feature": "annotation",
+        "operator": "=",
+        "terminal": {
+          "$type": "RuleCall",
+          "rule": {
+            "$ref": "#/rules@113"
+          },
+          "arguments": []
+        }
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "TeamDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "team"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "{"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "props",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@64"
+              },
+              "arguments": []
+            },
+            "cardinality": "*"
+          },
+          {
+            "$type": "Keyword",
+            "value": "}"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "TeamProp",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@65"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@66"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@67"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@68"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@69"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@70"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@71"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@72"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@73"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "TeamNameProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "name"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "TeamAvatarProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "avatar"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "TeamRoleProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "role"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "TeamSummaryProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "summary"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "TeamEmailProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "email"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "TeamSlackProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "slack"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "TeamMsTeamsProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "ms-teams"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "TeamMemberProp",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "member"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "memberRef",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "TeamAnnotationProp",
+      "definition": {
+        "$type": "Assignment",
+        "feature": "annotation",
+        "operator": "=",
+        "terminal": {
+          "$type": "RuleCall",
+          "rule": {
+            "$ref": "#/rules@113"
+          },
+          "arguments": []
+        }
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ActorDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "actor"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "{"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "body",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@75"
+                  },
+                  "arguments": []
+                },
+                "cardinality": "*"
+              },
+              {
+                "$type": "Keyword",
+                "value": "}"
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ActorBodyItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@89"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@90"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@113"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ExternalSystemDef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "external-system"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "{"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "body",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@77"
+                  },
+                  "arguments": []
+                },
+                "cardinality": "*"
+              },
+              {
+                "$type": "Keyword",
+                "value": "}"
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ExternalSystemBodyItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@89"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@90"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@113"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "SendsStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "sends"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "messageType",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@131"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Assignment",
+            "feature": "messageName",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "@"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "version",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@139"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "?"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "channelClause",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@81"
+              },
+              "arguments": []
+            },
+            "cardinality": "?"
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "{"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "body",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@80"
+                  },
+                  "arguments": []
+                },
+                "cardinality": "*"
+              },
+              {
+                "$type": "Keyword",
+                "value": "}"
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ReceivesStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "receives"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "messageType",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@131"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Assignment",
+            "feature": "messageName",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "@"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "version",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@139"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "?"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "channelClause",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@81"
+              },
+              "arguments": []
+            },
+            "cardinality": "?"
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "{"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "body",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@80"
+                  },
+                  "arguments": []
+                },
+                "cardinality": "*"
+              },
+              {
+                "$type": "Keyword",
+                "value": "}"
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "SendsReceivesBodyItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@88"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@89"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@90"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@91"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@92"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@82"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@83"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@113"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ChannelClause",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@82"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@83"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ToClause",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "to"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "channels",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@84"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": ","
+              },
+              {
+                "$type": "Assignment",
+                "feature": "channels",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@84"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "*"
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "delivery"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "deliveryMode",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@85"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "FromClause",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "from"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "channels",
+            "operator": "+=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@84"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": ","
+              },
+              {
+                "$type": "Assignment",
+                "feature": "channels",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@84"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "*"
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "delivery"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "deliveryMode",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@85"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ChannelRef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Assignment",
+            "feature": "channelName",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@135"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "@"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "channelVersion",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@139"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "DeliveryMode",
+      "dataType": "string",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "push"
+          },
+          {
+            "$type": "Keyword",
+            "value": "pull"
+          },
+          {
+            "$type": "Keyword",
+            "value": "push-pull"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "WritesToStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "writes-to"
+          },
+          {
+            "$type": "Keyword",
+            "value": "container"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@132"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ReadsFromStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "reads-from"
+          },
+          {
+            "$type": "Keyword",
+            "value": "container"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@132"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "VersionStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "version"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@139"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "NameStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "name"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "SummaryStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "summary"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "OwnerStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "owner"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ownerRef",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "SchemaStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "schema"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@140"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "DeprecatedStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "deprecated"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@134"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "DraftStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "draft"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@134"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "LegendStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "legend"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@134"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "SearchStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "search"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@134"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ToolbarStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "toolbar"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@134"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "FocusModeStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "focus-mode"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@134"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "AnimatedStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "animated"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@134"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "StyleStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "style"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@101"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "StyleEnum",
+      "dataType": "string",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "default"
+          },
+          {
+            "$type": "Keyword",
+            "value": "post-it"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ChannelRefStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "channel"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@103"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ChannelResourceRef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@135"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "@"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "version",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@139"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "FlowRefStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "flow"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@132"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "DataProductRefStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "data-product"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@132"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ServiceRefStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "service"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@132"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "DomainRefStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "domain"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@132"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "EventRefStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "event"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@133"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "CommandRefStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "command"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@133"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "QueryRefStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "query"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@133"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ContainerRefStmt",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "container"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "ref",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@132"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ResourceTypeKw",
+      "dataType": "string",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "domain"
+          },
+          {
+            "$type": "Keyword",
+            "value": "service"
+          },
+          {
+            "$type": "Keyword",
+            "value": "event"
+          },
+          {
+            "$type": "Keyword",
+            "value": "command"
+          },
+          {
+            "$type": "Keyword",
+            "value": "query"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "Annotation",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "@"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@114"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "("
+              },
+              {
+                "$type": "Assignment",
+                "feature": "args",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@115"
+                  },
+                  "arguments": []
+                }
+              },
+              {
+                "$type": "Group",
+                "elements": [
+                  {
+                    "$type": "Keyword",
+                    "value": ","
+                  },
+                  {
+                    "$type": "Assignment",
+                    "feature": "args",
+                    "operator": "+=",
+                    "terminal": {
+                      "$type": "RuleCall",
+                      "rule": {
+                        "$ref": "#/rules@115"
+                      },
+                      "arguments": []
+                    }
+                  }
+                ],
+                "cardinality": "*"
+              },
+              {
+                "$type": "Keyword",
+                "value": ")"
+              }
+            ],
+            "cardinality": "?"
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "{"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "block",
+                "operator": "+=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@127"
+                  },
+                  "arguments": []
+                },
+                "cardinality": "*"
+              },
+              {
+                "$type": "Keyword",
+                "value": "}"
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "AnnotationName",
+      "dataType": "string",
+      "definition": {
+        "$type": "RuleCall",
+        "rule": {
+          "$ref": "#/rules@143"
+        },
+        "arguments": []
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "AnnotationArg",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@116"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@117"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "NamedAnnotationArg",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Assignment",
+            "feature": "key",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@118"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": ":"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@119"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "PositionalAnnotationArg",
+      "definition": {
+        "$type": "Assignment",
+        "feature": "value",
+        "operator": "=",
+        "terminal": {
+          "$type": "RuleCall",
+          "rule": {
+            "$ref": "#/rules@119"
+          },
+          "arguments": []
+        }
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "AnnotationKey",
+      "dataType": "string",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@143"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "Keyword",
+            "value": "url"
+          },
+          {
+            "$type": "Keyword",
+            "value": "type"
+          },
+          {
+            "$type": "Keyword",
+            "value": "name"
+          },
+          {
+            "$type": "Keyword",
+            "value": "path"
+          },
+          {
+            "$type": "Keyword",
+            "value": "label"
+          },
+          {
+            "$type": "Keyword",
+            "value": "icon"
+          },
+          {
+            "$type": "Keyword",
+            "value": "title"
+          },
+          {
+            "$type": "Keyword",
+            "value": "color"
+          },
+          {
+            "$type": "Keyword",
+            "value": "description"
+          },
+          {
+            "$type": "Keyword",
+            "value": "message"
+          },
+          {
+            "$type": "Keyword",
+            "value": "version"
+          },
+          {
+            "$type": "Keyword",
+            "value": "summary"
+          },
+          {
+            "$type": "Keyword",
+            "value": "email"
+          },
+          {
+            "$type": "Keyword",
+            "value": "slack"
+          },
+          {
+            "$type": "Keyword",
+            "value": "role"
+          },
+          {
+            "$type": "Keyword",
+            "value": "default"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "AnnotationValue",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@120"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@121"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@122"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@123"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@124"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@125"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "StringAnnotationValue",
+      "definition": {
+        "$type": "Assignment",
+        "feature": "value",
+        "operator": "=",
+        "terminal": {
+          "$type": "RuleCall",
+          "rule": {
+            "$ref": "#/rules@140"
+          },
+          "arguments": []
+        }
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "IdAnnotationValue",
+      "definition": {
+        "$type": "Assignment",
+        "feature": "value",
+        "operator": "=",
+        "terminal": {
+          "$type": "RuleCall",
+          "rule": {
+            "$ref": "#/rules@143"
+          },
+          "arguments": []
+        }
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "NumberAnnotationValue",
+      "definition": {
+        "$type": "Assignment",
+        "feature": "value",
+        "operator": "=",
+        "terminal": {
+          "$type": "RuleCall",
+          "rule": {
+            "$ref": "#/rules@141"
+          },
+          "arguments": []
+        }
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "BoolAnnotationValue",
+      "definition": {
+        "$type": "Assignment",
+        "feature": "value",
+        "operator": "=",
+        "terminal": {
+          "$type": "RuleCall",
+          "rule": {
+            "$ref": "#/rules@134"
+          },
+          "arguments": []
+        }
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "VersionAnnotationValue",
+      "definition": {
+        "$type": "Assignment",
+        "feature": "value",
+        "operator": "=",
+        "terminal": {
+          "$type": "RuleCall",
+          "rule": {
+            "$ref": "#/rules@139"
+          },
+          "arguments": []
+        }
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "KeywordAnnotationValue",
+      "definition": {
+        "$type": "Assignment",
+        "feature": "value",
+        "operator": "=",
+        "terminal": {
+          "$type": "RuleCall",
+          "rule": {
+            "$ref": "#/rules@126"
+          },
+          "arguments": []
+        }
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "AnnotationKeywordAsValue",
+      "dataType": "string",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "type"
+          },
+          {
+            "$type": "Keyword",
+            "value": "name"
+          },
+          {
+            "$type": "Keyword",
+            "value": "path"
+          },
+          {
+            "$type": "Keyword",
+            "value": "url"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "AnnotationBlockItem",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@128"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@129"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ResourceAnnotationBlockItem",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Assignment",
+            "feature": "resourceType",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@112"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Assignment",
+            "feature": "resourceName",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "@"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "version",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@139"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "KeyValueAnnotationBlockItem",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Assignment",
+            "feature": "key",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Assignment",
+            "feature": "value",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@130"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "AnnotationBlockValue",
+      "dataType": "string",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "visible"
+          },
+          {
+            "$type": "Keyword",
+            "value": "hidden"
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@143"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@139"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "MessageType",
+      "dataType": "string",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "event"
+          },
+          {
+            "$type": "Keyword",
+            "value": "command"
+          },
+          {
+            "$type": "Keyword",
+            "value": "query"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ResourceRef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Group",
+            "elements": [
+              {
+                "$type": "Keyword",
+                "value": "@"
+              },
+              {
+                "$type": "Assignment",
+                "feature": "version",
+                "operator": "=",
+                "terminal": {
+                  "$type": "RuleCall",
+                  "rule": {
+                    "$ref": "#/rules@139"
+                  },
+                  "arguments": []
+                }
+              }
+            ],
+            "cardinality": "?"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "VersionedResourceRef",
+      "definition": {
+        "$type": "Group",
+        "elements": [
+          {
+            "$type": "Assignment",
+            "feature": "name",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@143"
+              },
+              "arguments": []
+            }
+          },
+          {
+            "$type": "Keyword",
+            "value": "@"
+          },
+          {
+            "$type": "Assignment",
+            "feature": "version",
+            "operator": "=",
+            "terminal": {
+              "$type": "RuleCall",
+              "rule": {
+                "$ref": "#/rules@139"
+              },
+              "arguments": []
+            }
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "BoolLiteral",
+      "dataType": "boolean",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "Keyword",
+            "value": "true"
+          },
+          {
+            "$type": "Keyword",
+            "value": "false"
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "ParserRule",
+      "name": "ChannelName",
+      "dataType": "string",
+      "definition": {
+        "$type": "Alternatives",
+        "elements": [
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@142"
+            },
+            "arguments": []
+          },
+          {
+            "$type": "RuleCall",
+            "rule": {
+              "$ref": "#/rules@143"
+            },
+            "arguments": []
+          }
+        ]
+      },
+      "definesHiddenTokens": false,
+      "entry": false,
+      "fragment": false,
+      "hiddenTokens": [],
+      "parameters": [],
+      "wildcard": false
+    },
+    {
+      "$type": "TerminalRule",
+      "hidden": true,
+      "name": "WS",
+      "definition": {
+        "$type": "RegexToken",
+        "regex": "/\\\\s+/"
+      },
+      "fragment": false
+    },
+    {
+      "$type": "TerminalRule",
+      "hidden": true,
+      "name": "SL_COMMENT",
+      "definition": {
+        "$type": "RegexToken",
+        "regex": "/\\\\/\\\\/[^\\\\n\\\\r]*/"
+      },
+      "fragment": false
+    },
+    {
+      "$type": "TerminalRule",
+      "hidden": true,
+      "name": "ML_COMMENT",
+      "definition": {
+        "$type": "RegexToken",
+        "regex": "/\\\\/\\\\*[\\\\s\\\\S]*?\\\\*\\\\//"
+      },
+      "fragment": false
+    },
+    {
+      "$type": "TerminalRule",
+      "name": "VERSION",
+      "definition": {
+        "$type": "RegexToken",
+        "regex": "/\\\\d+\\\\.\\\\d+\\\\.\\\\d+(-[a-zA-Z0-9_.]+)*/"
+      },
+      "fragment": false,
+      "hidden": false
+    },
+    {
+      "$type": "TerminalRule",
+      "name": "STRING",
+      "definition": {
+        "$type": "RegexToken",
+        "regex": "/\\"(?:[^\\"\\\\\\\\]|\\\\\\\\.)*\\"/"
+      },
+      "fragment": false,
+      "hidden": false
+    },
+    {
+      "$type": "TerminalRule",
+      "name": "NUMBER",
+      "definition": {
+        "$type": "RegexToken",
+        "regex": "/\\\\d+/"
+      },
+      "fragment": false,
+      "hidden": false
+    },
+    {
+      "$type": "TerminalRule",
+      "name": "TEMPLATE_ID",
+      "definition": {
+        "$type": "RegexToken",
+        "regex": "/[a-zA-Z_][a-zA-Z0-9_.-]*\\\\{[a-zA-Z0-9_]+\\\\}[a-zA-Z0-9_.{}-]*/"
+      },
+      "fragment": false,
+      "hidden": false
+    },
+    {
+      "$type": "TerminalRule",
+      "name": "ID",
+      "definition": {
+        "$type": "RegexToken",
+        "regex": "/[a-zA-Z_][a-zA-Z0-9_.-]*/"
+      },
+      "fragment": false,
+      "hidden": false
+    }
+  ],
+  "definesHiddenTokens": false,
+  "hiddenTokens": [],
+  "imports": [],
+  "interfaces": [],
+  "types": [],
+  "usedGrammars": []
+}`));
diff --git a/packages/language-server/src/generated/module.ts b/packages/language-server/src/generated/module.ts
new file mode 100644
index 000000000..a6ffb4181
--- /dev/null
+++ b/packages/language-server/src/generated/module.ts
@@ -0,0 +1,25 @@
+/******************************************************************************
+ * This file was generated by langium-cli 3.5.2.
+ * DO NOT EDIT MANUALLY!
+ ******************************************************************************/
+
+import type { LangiumSharedCoreServices, LangiumCoreServices, LangiumGeneratedCoreServices, LangiumGeneratedSharedCoreServices, LanguageMetaData, Module } from 'langium';
+import { EcAstReflection } from './ast.js';
+import { EcGrammar } from './grammar.js';
+
+export const EcLanguageMetaData = {
+    languageId: 'ec',
+    fileExtensions: ['.ec'],
+    caseInsensitive: false,
+    mode: 'development'
+} as const satisfies LanguageMetaData;
+
+export const EcGeneratedSharedModule: Module<LangiumSharedCoreServices, LangiumGeneratedSharedCoreServices> = {
+    AstReflection: () => new EcAstReflection()
+};
+
+export const EcGeneratedModule: Module<LangiumCoreServices, LangiumGeneratedCoreServices> = {
+    Grammar: () => EcGrammar(),
+    LanguageMetaData: () => EcLanguageMetaData,
+    parser: {}
+};
diff --git a/packages/language-server/src/graph-types.ts b/packages/language-server/src/graph-types.ts
new file mode 100644
index 000000000..3e8317596
--- /dev/null
+++ b/packages/language-server/src/graph-types.ts
@@ -0,0 +1,79 @@
+export interface GraphNode {
+  id: string;
+  type:
+    | "domain"
+    | "service"
+    | "event"
+    | "command"
+    | "query"
+    | "channel"
+    | "entity"
+    | "container"
+    | "data"
+    | "data-product"
+    | "flow"
+    | "actor"
+    | "external-system"
+    | "user"
+    | "team"
+    | "diagram"
+    | "step";
+  label: string;
+  parentId?: string;
+  metadata: Record<string, unknown>;
+}
+
+export type GraphEdgeType =
+  | "sends"
+  | "receives"
+  | "publishes"
+  | "subscribes"
+  | "writes-to"
+  | "reads-from"
+  | "reads-writes"
+  | "contains"
+  | "owns"
+  | "member-of"
+  | "routes-to"
+  | "flow-step";
+
+export interface GraphEdge {
+  id: string;
+  source: string;
+  target: string;
+  type: GraphEdgeType;
+  label?: string;
+}
+
+/**
+ * Returns the display label for a "receives" edge based on the message type.
+ * Commands and queries use "accepts"; events fall back to the edge type.
+ */
+export function getReceivesLabel(
+  messageType: GraphNode["type"],
+): string | undefined {
+  switch (messageType) {
+    case "command":
+    case "query":
+      return "accepts";
+    default:
+      return undefined;
+  }
+}
+
+export interface DslGraph {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  visualizers?: string[];
+  activeVisualizer?: string;
+  title?: string;
+  empty?: boolean;
+  options?: {
+    legend?: boolean;
+    search?: boolean;
+    toolbar?: boolean;
+    focusMode?: boolean;
+    animated?: boolean;
+    style?: string;
+  };
+}
diff --git a/packages/language-server/src/graph.ts b/packages/language-server/src/graph.ts
new file mode 100644
index 000000000..5e59cec2b
--- /dev/null
+++ b/packages/language-server/src/graph.ts
@@ -0,0 +1,1443 @@
+import semver from "semver";
+import type { AstNode } from "langium";
+import type {
+  Program,
+  DomainDef,
+  ServiceDef,
+  EventDef,
+  CommandDef,
+  QueryDef,
+  ChannelDef,
+  ContainerDef,
+  DataProductDef,
+  FlowDef,
+  DiagramDef,
+  UserDef,
+  TeamDef,
+  SubdomainDef,
+  SendsStmt,
+  ReceivesStmt,
+  ResourceDefinition,
+  VisualizerDef,
+  VisualizerBodyItem,
+  FlowRef,
+} from "./generated/ast.js";
+import {
+  isDomainDef,
+  isServiceDef,
+  isEventDef,
+  isCommandDef,
+  isQueryDef,
+  isChannelDef,
+  isContainerDef,
+  isDataProductDef,
+  isFlowDef,
+  isDiagramDef,
+  isUserDef,
+  isTeamDef,
+  isVisualizerDef,
+  isToClause,
+  isFromClause,
+  isServiceRefStmt,
+  isDomainRefStmt,
+  isChannelRefStmt,
+  isDataProductRefStmt,
+  isFlowRefStmt,
+  isContainerRefStmt,
+  isEventRefStmt,
+  isCommandRefStmt,
+  isQueryRefStmt,
+  isActorDef,
+  isExternalSystemDef,
+  isPositionalAnnotationArg,
+  isNamedAnnotationArg,
+  isStringAnnotationValue,
+  isIdAnnotationValue,
+} from "./generated/ast.js";
+import {
+  stripQuotes,
+  getVersion,
+  getName,
+  getSummary,
+  getOwners,
+  getServices,
+  getSubdomains,
+  getContainers,
+  getServiceRefs,
+  getFlowRefs,
+  getFlows,
+  getDataProductRefs,
+  getSends,
+  getReceives,
+  getWritesToRefs,
+  getReadsFromRefs,
+  getChannelRefs,
+  getAddress,
+  getProtocols,
+  getContainerType,
+  getInputs,
+  getOutputs,
+  getAnnotations,
+  getToClause,
+  getFromClause,
+  getLegend,
+  getSearch,
+  getToolbar,
+  getFocusMode,
+  getAnimated,
+  getStyle,
+  getDeprecated,
+  getDraft,
+  getSchema,
+  getRoutes,
+  getFlowEntryChains,
+  getFlowWhenBlocks,
+} from "./ast-utils.js";
+import type { GraphNode, GraphEdge, DslGraph } from "./graph-types.js";
+import { getReceivesLabel } from "./graph-types.js";
+
+function extractNotes(
+  body: AstNode[],
+): Array<{ content: string; author?: string; priority?: string }> {
+  const annotations = getAnnotations(body);
+  const notes: Array<{ content: string; author?: string; priority?: string }> =
+    [];
+  for (const ann of annotations) {
+    if (ann.name !== "note") continue;
+    const note: { content: string; author?: string; priority?: string } = {
+      content: "",
+    };
+    const contentArg = ann.args.find((a) => isPositionalAnnotationArg(a));
+    if (contentArg) {
+      const v = isPositionalAnnotationArg(contentArg)
+        ? contentArg.value
+        : undefined;
+      if (v && isStringAnnotationValue(v)) note.content = stripQuotes(v.value);
+      else if (v && isIdAnnotationValue(v)) note.content = v.value;
+    }
+    for (const arg of ann.args) {
+      if (isNamedAnnotationArg(arg)) {
+        const val = isStringAnnotationValue(arg.value)
+          ? stripQuotes(arg.value.value)
+          : isIdAnnotationValue(arg.value)
+            ? arg.value.value
+            : undefined;
+        if (val && arg.key === "author") note.author = val;
+        if (val && arg.key === "priority") note.priority = val;
+      }
+    }
+    if (note.content) notes.push(note);
+  }
+  return notes;
+}
+
+function extractApiInfo(body: AstNode[]): {
+  method?: string;
+  path?: string;
+  statusCodes?: number[];
+} {
+  const annotations = getAnnotations(body);
+  for (const ann of annotations) {
+    if (ann.name !== "api") continue;
+    const result: { method?: string; path?: string; statusCodes?: number[] } =
+      {};
+    for (const arg of ann.args) {
+      if (isNamedAnnotationArg(arg)) {
+        const val = isStringAnnotationValue(arg.value)
+          ? stripQuotes(arg.value.value)
+          : isIdAnnotationValue(arg.value)
+            ? arg.value.value
+            : undefined;
+        if (!val) continue;
+        if (arg.key === "method") result.method = val;
+        else if (arg.key === "path") result.path = val;
+        else if (arg.key === "statusCodes") {
+          result.statusCodes = val
+            .split(",")
+            .map(Number)
+            .filter((c) => !isNaN(c));
+        }
+      }
+    }
+    return result;
+  }
+  return {};
+}
+
+export function astToGraph(
+  program: Program,
+  visualizerName?: string,
+): DslGraph {
+  // Find all visualizer definitions
+  const visualizerDefs = program.definitions.filter(isVisualizerDef);
+  const visualizerNames = visualizerDefs.map((v) => v.name);
+
+  // If no visualizers exist, return empty graph
+  if (visualizerDefs.length === 0) {
+    return { nodes: [], edges: [], visualizers: [], empty: true };
+  }
+
+  // Select the active visualizer
+  const activeViz = visualizerName
+    ? visualizerDefs.find((v) => v.name === visualizerName) || visualizerDefs[0]
+    : visualizerDefs[0];
+
+  // Extract title and display options from visualizer body
+  const vizBody = activeViz.body as AstNode[];
+  const vizTitle = getName(vizBody) || activeViz.name;
+  const options = {
+    legend: getLegend(vizBody),
+    search: getSearch(vizBody),
+    toolbar: getToolbar(vizBody),
+    focusMode: getFocusMode(vizBody),
+    animated: getAnimated(vizBody),
+    style: getStyle(vizBody),
+  };
+
+  // Build a lookup map of all definitions (including nested ones) for resolving refs
+  // Key format: "name" for unversioned, "name@version" for versioned
+  const topLevelDefs = new Map<string, ResourceDefinition>();
+
+  function defKey(name: string, version?: string): string {
+    return version ? `${name}@${version}` : name;
+  }
+
+  function addToDefMap(def: ResourceDefinition): void {
+    if ("name" in def) {
+      const body = ("body" in def ? def.body : []) as AstNode[];
+      const version = getVersion(body);
+      // Store under name@version for exact lookups
+      if (version) {
+        topLevelDefs.set(defKey(def.name, version), def);
+      }
+      // Store under bare name only if it's the latest version seen so far
+      const existing = topLevelDefs.get(def.name);
+      if (!existing) {
+        topLevelDefs.set(def.name, def);
+      } else if (version) {
+        const existingBody = (
+          "body" in existing ? existing.body : []
+        ) as AstNode[];
+        const existingVersion = getVersion(existingBody);
+        if (
+          !existingVersion ||
+          (semver.valid(version) &&
+            semver.valid(existingVersion) &&
+            semver.compare(version, existingVersion) > 0)
+        ) {
+          topLevelDefs.set(def.name, def);
+        }
+      }
+    }
+
+    // Also add nested definitions (services, containers, etc. inside domains)
+    if (isDomainDef(def) && def.body) {
+      const body = def.body as AstNode[];
+      for (const svc of getServices(body)) {
+        addToDefMap(svc);
+      }
+      for (const container of getContainers(body)) {
+        addToDefMap(container);
+      }
+      for (const ch of body.filter(isChannelDef)) {
+        addToDefMap(ch as ResourceDefinition);
+      }
+      for (const flow of getFlows(body)) {
+        addToDefMap(flow as ResourceDefinition);
+      }
+      // Subdomains are handled separately (they have their own services/containers)
+      for (const subdomain of getSubdomains(body)) {
+        const subBody = subdomain.body as AstNode[];
+        for (const svc of getServices(subBody)) {
+          addToDefMap(svc);
+        }
+        for (const container of getContainers(subBody)) {
+          addToDefMap(container);
+        }
+        for (const ch of subBody.filter(isChannelDef)) {
+          addToDefMap(ch as ResourceDefinition);
+        }
+      }
+    }
+  }
+
+  for (const def of program.definitions) {
+    if (!isVisualizerDef(def)) {
+      addToDefMap(def);
+    }
+  }
+
+  const nodes: GraphNode[] = [];
+  const edges: GraphEdge[] = [];
+
+  /** Set parentId on a node, guarding against self-reference */
+  function assignParent(
+    node: GraphNode,
+    nodeId: string,
+    parentId: string | undefined,
+  ): void {
+    if (parentId && parentId !== nodeId && !node.parentId) {
+      node.parentId = parentId;
+    }
+  }
+
+  // Build a versioned node ID: type:name@version or type:name (unversioned)
+  function nid(name: string, type: string, version?: string): string {
+    if (version) return `${type}:${name}@${version}`;
+    return `${type}:${name}`;
+  }
+
+  // Infer the graph node type for a flow ref by looking up definitions.
+  // Uses topLevelDefs which includes nested defs (services/events inside domains).
+  function inferTypeFromCatalog(name: string): GraphNode["type"] {
+    const def = topLevelDefs.get(name);
+    if (def) {
+      if (isServiceDef(def)) return "service";
+      if (isEventDef(def)) return "event";
+      if (isCommandDef(def)) return "command";
+      if (isQueryDef(def)) return "query";
+      if (isChannelDef(def)) return "channel";
+      if (isContainerDef(def)) return "container";
+      if (isDataProductDef(def)) return "data-product";
+      if (isFlowDef(def)) return "flow";
+      if (isActorDef(def)) return "actor";
+      if (isExternalSystemDef(def)) return "external-system";
+    }
+    // Also check if it already exists as a node (from earlier processing)
+    for (const n of nodes) {
+      if (n.id.startsWith(`${name}`) || n.id.includes(`:${name}`)) {
+        return n.type;
+      }
+    }
+    // Default: treat as step (unresolved flow refs are process steps)
+    return "step";
+  }
+
+  // Find the best matching node for a type+name, optionally with a specific version.
+  // If version is given, look for that exact versioned node first.
+  // If no version, resolve to the latest version per the DSL spec.
+  function resolveNodeId(
+    name: string,
+    type: string,
+    version?: string,
+  ): string | undefined {
+    if (version) {
+      // When a specific version is requested, only return an exact match
+      const exact = nodes.find((n) => n.id === nid(name, type, version));
+      return exact?.id;
+    }
+    // No version: per spec, bare refs resolve to the latest version.
+    // Collect all matching nodes and pick the one with the highest semver.
+    const prefix = `${type}:${name}`;
+    const candidates = nodes.filter(
+      (n) => n.id === prefix || n.id.startsWith(prefix + "@"),
+    );
+    if (candidates.length === 0) return undefined;
+    if (candidates.length === 1) return candidates[0].id;
+
+    // Pick the candidate with the highest semver version
+    let latest = candidates[0];
+    for (let i = 1; i < candidates.length; i++) {
+      const cv = (candidates[i].metadata.version as string) || "";
+      const lv = (latest.metadata.version as string) || "";
+      if (
+        semver.valid(cv) &&
+        (!semver.valid(lv) || semver.compare(cv, lv) > 0)
+      ) {
+        latest = candidates[i];
+      }
+    }
+    return latest.id;
+  }
+
+  function addNode(
+    name: string,
+    type: GraphNode["type"],
+    label: string,
+    parentId?: string,
+    metadata: Record<string, unknown> = {},
+  ): string {
+    const version = metadata.version as string | undefined;
+    const id = nid(name, type, version);
+    const existing = nodes.find((n) => n.id === id);
+    if (existing) {
+      assignParent(existing, id, parentId);
+      // Merge metadata: fill in values the existing node is missing
+      for (const [key, value] of Object.entries(metadata)) {
+        if (value != null && existing.metadata[key] == null) {
+          existing.metadata[key] = value;
+        }
+      }
+      if (label !== name && existing.label === name) {
+        existing.label = label;
+      }
+      return id;
+    }
+
+    // For unversioned references, check if a versioned node already exists
+    if (!version) {
+      const resolved = resolveNodeId(name, type);
+      if (resolved) {
+        const existingNode = nodes.find((n) => n.id === resolved)!;
+        assignParent(existingNode, resolved, parentId);
+        return resolved;
+      }
+    }
+
+    // For versioned definitions, check if an unversioned stub already exists and upgrade it
+    if (version) {
+      const unversionedId = nid(name, type);
+      const stub = nodes.find((n) => n.id === unversionedId);
+      if (stub) {
+        // Upgrade: change the stub's ID to include the version
+        const oldId = stub.id;
+        stub.id = id;
+        stub.metadata.version = version;
+        for (const [key, value] of Object.entries(metadata)) {
+          if (value != null && stub.metadata[key] == null) {
+            stub.metadata[key] = value;
+          }
+        }
+        if (label !== name && stub.label === name) {
+          stub.label = label;
+        }
+        if (parentId && !stub.parentId) {
+          stub.parentId = parentId;
+        }
+        // Update all edges that referenced the old unversioned ID
+        for (const edge of edges) {
+          if (edge.source === oldId) {
+            edge.source = id;
+            edge.id = `${edge.source}-${edge.type}-${edge.target}`;
+          }
+          if (edge.target === oldId) {
+            edge.target = id;
+            edge.id = `${edge.source}-${edge.type}-${edge.target}`;
+          }
+        }
+        return id;
+      }
+    }
+
+    nodes.push({ id, type, label, parentId, metadata });
+    return id;
+  }
+
+  function addEdge(
+    sourceId: string,
+    targetId: string,
+    type: GraphEdge["type"],
+    label?: string,
+  ): void {
+    const id = `${sourceId}-${type}-${targetId}`;
+    if (edges.some((e) => e.id === id)) return;
+    edges.push({ id, source: sourceId, target: targetId, type, label });
+  }
+
+  // Check if `source` can reach `target` via "routes-to" edges (BFS),
+  // optionally excluding a specific edge (to test if an alternative path exists).
+  function canReachViaRoutes(
+    source: string,
+    target: string,
+    edgeList: GraphEdge[],
+    excludeEdgeId?: string,
+  ): boolean {
+    const visited = new Set<string>();
+    const queue = [source];
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      if (current === target) return true;
+      if (visited.has(current)) continue;
+      visited.add(current);
+      for (const e of edgeList) {
+        if (
+          e.source === current &&
+          e.type === "routes-to" &&
+          e.id !== excludeEdgeId
+        ) {
+          queue.push(e.target);
+        }
+      }
+    }
+    return false;
+  }
+
+  // Enrich a node with metadata from matching top-level definitions (e.g. channel defined outside visualizer)
+  function enrichFromTopLevel(
+    nodeId: string,
+    name: string,
+    type: GraphNode["type"],
+  ): void {
+    const node = nodes.find((n) => n.id === nodeId);
+    if (!node) return;
+
+    // Find all top-level defs with this name (there can be multiple versions)
+    const matchingDefs = program.definitions.filter(
+      (d) => !isVisualizerDef(d) && "name" in d && d.name === name,
+    );
+
+    for (const def of matchingDefs) {
+      const body = ("body" in def ? def.body : []) as AstNode[];
+      const defVersion = getVersion(body);
+
+      // If the node has a version, only enrich from the matching version def
+      if (
+        node.metadata.version &&
+        defVersion &&
+        node.metadata.version !== defVersion
+      ) {
+        continue;
+      }
+
+      const enrichOwners = getOwners(body);
+      const enrichNotes = extractNotes(body);
+      const enrichApiInfo = extractApiInfo(body);
+      const meta: Record<string, unknown> = {
+        version: defVersion,
+        summary: getSummary(body),
+        deprecated: getDeprecated(body),
+        draft: getDraft(body),
+        schema: getSchema(body),
+        ...(enrichOwners.length > 0 ? { owners: enrichOwners } : {}),
+        ...(enrichNotes.length > 0 ? { notes: enrichNotes } : {}),
+        ...(enrichApiInfo.method ? { method: enrichApiInfo.method } : {}),
+        ...(enrichApiInfo.path ? { path: enrichApiInfo.path } : {}),
+        ...(enrichApiInfo.statusCodes && enrichApiInfo.statusCodes.length > 0
+          ? { statusCodes: enrichApiInfo.statusCodes }
+          : {}),
+      };
+      if (isChannelDef(def)) {
+        meta.address = getAddress(body);
+        meta.protocols = getProtocols(body);
+      }
+      if (isContainerDef(def)) {
+        meta.containerType = getContainerType(body);
+      }
+      for (const [key, value] of Object.entries(meta)) {
+        if (value != null && node.metadata[key] == null) {
+          node.metadata[key] = value;
+        }
+      }
+      const label = getName(body);
+      if (label && node.label === name) {
+        node.label = label;
+      }
+
+      // Process route statements for channels discovered via sends/receives
+      if (isChannelDef(def)) {
+        for (const route of getRoutes(body)) {
+          const targetChId = resolveOrCreateMsg(
+            route.ref.name,
+            "channel",
+            route.ref.version,
+          );
+          addEdge(nodeId, targetChId, "routes-to");
+        }
+      }
+    }
+  }
+
+  /** Enrich an existing node with metadata from an inline sends/receives body. */
+  function enrichNodeFromInlineBody(nodeId: string, body: AstNode[]): void {
+    const existing = nodes.find((n) => n.id === nodeId);
+    if (!existing) return;
+    const summary = getSummary(body);
+    if (summary && !existing.metadata.summary)
+      existing.metadata.summary = summary;
+    const schema = getSchema(body);
+    if (schema && !existing.metadata.schema) existing.metadata.schema = schema;
+    const inlineNotes = extractNotes(body);
+    if (inlineNotes.length > 0 && !existing.metadata.notes)
+      existing.metadata.notes = inlineNotes;
+    const inlineApi = extractApiInfo(body);
+    if (inlineApi.method && !existing.metadata.method)
+      existing.metadata.method = inlineApi.method;
+    if (inlineApi.path && !existing.metadata.path)
+      existing.metadata.path = inlineApi.path;
+    if (
+      inlineApi.statusCodes &&
+      inlineApi.statusCodes.length > 0 &&
+      !existing.metadata.statusCodes
+    )
+      existing.metadata.statusCodes = inlineApi.statusCodes;
+  }
+
+  // For sends/receives references: resolve to versioned node if it exists, otherwise create
+  function resolveOrCreateMsg(
+    name: string,
+    type: GraphNode["type"],
+    version?: string,
+    parentId?: string,
+  ): string {
+    // If a specific version is requested, try to find that exact node
+    if (version) {
+      const existingId = resolveNodeId(name, type, version);
+      if (existingId) {
+        const node = nodes.find((n) => n.id === existingId)!;
+        assignParent(node, existingId, parentId);
+        enrichFromTopLevel(existingId, name, type);
+        return existingId;
+      }
+      const id = addNode(name, type, name, parentId, { version });
+      enrichFromTopLevel(id, name, type);
+      return id;
+    }
+
+    // No version: try to find any existing node for this type+name
+    const existingId = resolveNodeId(name, type);
+    if (existingId) {
+      const node = nodes.find((n) => n.id === existingId)!;
+      assignParent(node, existingId, parentId);
+      enrichFromTopLevel(existingId, name, type);
+      return existingId;
+    }
+    const id = addNode(name, type, name, parentId, {});
+    enrichFromTopLevel(id, name, type);
+    return id;
+  }
+
+  function processSends(
+    serviceId: string,
+    sendsList: SendsStmt[],
+    domainId?: string,
+  ): void {
+    for (const s of sendsList) {
+      const msgType = s.messageType as GraphNode["type"];
+
+      // Determine version: from inline body, or from the statement itself
+      let version = s.version;
+      if (!version && s.body.length > 0) {
+        version = getVersion(s.body as AstNode[]);
+      }
+
+      const msgNodeId = resolveOrCreateMsg(
+        s.messageName,
+        msgType,
+        version,
+        domainId,
+      );
+      if (domainId) {
+        addEdge(domainId, msgNodeId, "contains");
+      }
+      addEdge(serviceId, msgNodeId, "sends");
+
+      // Inline body summary + schema + notes + api info
+      if (s.body.length > 0) {
+        enrichNodeFromInlineBody(msgNodeId, s.body as AstNode[]);
+      }
+
+      // Channel clause (on the sends statement itself)
+      if (s.channelClause) {
+        const clause = s.channelClause;
+        if (isToClause(clause) || isFromClause(clause)) {
+          for (const ch of clause.channels) {
+            const chId = resolveOrCreateMsg(
+              ch.channelName,
+              "channel",
+              ch.channelVersion,
+              domainId,
+            );
+            if (domainId) addEdge(domainId, chId, "contains");
+            addEdge(msgNodeId, chId, "routes-to");
+          }
+        }
+      }
+
+      // Channel clauses inside body
+      const bodyTo = getToClause(s.body as AstNode[]);
+      if (bodyTo) {
+        for (const ch of bodyTo.channels) {
+          const chId = resolveOrCreateMsg(
+            ch.channelName,
+            "channel",
+            ch.channelVersion,
+            domainId,
+          );
+          if (domainId) addEdge(domainId, chId, "contains");
+          addEdge(msgNodeId, chId, "routes-to");
+        }
+      }
+      const bodyFrom = getFromClause(s.body as AstNode[]);
+      if (bodyFrom) {
+        for (const ch of bodyFrom.channels) {
+          const chId = resolveOrCreateMsg(
+            ch.channelName,
+            "channel",
+            ch.channelVersion,
+            domainId,
+          );
+          if (domainId) addEdge(domainId, chId, "contains");
+          addEdge(msgNodeId, chId, "routes-to");
+        }
+      }
+    }
+  }
+
+  function processReceives(
+    serviceId: string,
+    receivesList: ReceivesStmt[],
+    domainId?: string,
+  ): void {
+    for (const r of receivesList) {
+      const msgType = r.messageType as GraphNode["type"];
+
+      let version = r.version;
+      if (!version && r.body.length > 0) {
+        version = getVersion(r.body as AstNode[]);
+      }
+
+      const msgNodeId = resolveOrCreateMsg(
+        r.messageName,
+        msgType,
+        version,
+        domainId,
+      );
+      if (domainId) {
+        addEdge(domainId, msgNodeId, "contains");
+      }
+      addEdge(msgNodeId, serviceId, "receives", getReceivesLabel(msgType));
+
+      if (r.body.length > 0) {
+        enrichNodeFromInlineBody(msgNodeId, r.body as AstNode[]);
+      }
+
+      // Channel clause: "from ChannelX" means the service receives via that channel.
+      // Only create Channel → Service edge. The Message → Channel edge is handled
+      // by the sends side or by channel route statements.
+      const channelRefs: { name: string; version?: string }[] = [];
+
+      if (r.channelClause) {
+        const clause = r.channelClause;
+        if (isToClause(clause) || isFromClause(clause)) {
+          for (const ch of clause.channels) {
+            channelRefs.push({
+              name: ch.channelName,
+              version: ch.channelVersion,
+            });
+          }
+        }
+      }
+
+      const bodyTo = getToClause(r.body as AstNode[]);
+      if (bodyTo) {
+        for (const ch of bodyTo.channels) {
+          channelRefs.push({
+            name: ch.channelName,
+            version: ch.channelVersion,
+          });
+        }
+      }
+      const bodyFrom = getFromClause(r.body as AstNode[]);
+      if (bodyFrom) {
+        for (const ch of bodyFrom.channels) {
+          channelRefs.push({
+            name: ch.channelName,
+            version: ch.channelVersion,
+          });
+        }
+      }
+
+      if (channelRefs.length > 0) {
+        // Remove the direct Message → Service edge since the channel mediates
+        const directEdgeIdx = edges.findIndex(
+          (e) =>
+            e.source === msgNodeId &&
+            e.target === serviceId &&
+            e.type === "receives",
+        );
+        if (directEdgeIdx !== -1) edges.splice(directEdgeIdx, 1);
+
+        for (const ch of channelRefs) {
+          const chId = resolveOrCreateMsg(
+            ch.name,
+            "channel",
+            ch.version,
+            domainId,
+          );
+          if (domainId) addEdge(domainId, chId, "contains");
+          // Only add Message → Channel edge if no route path already exists
+          // from the message to this specific channel (via sends + channel routes).
+          const msgHasEdgeToThisChannel = edges.some(
+            (e) =>
+              e.source === msgNodeId &&
+              e.target === chId &&
+              e.type === "routes-to",
+          );
+          if (!msgHasEdgeToThisChannel) {
+            addEdge(msgNodeId, chId, "routes-to");
+          }
+          addEdge(chId, serviceId, "receives", getReceivesLabel(msgType));
+        }
+      }
+    }
+  }
+
+  function processService(svc: ServiceDef, parentId?: string): void {
+    const body = svc.body as AstNode[];
+    const svcName = getName(body) || svc.name;
+    const notes = extractNotes(body);
+    const svcOwners = getOwners(body);
+    const svcId = addNode(svc.name, "service", svcName, parentId, {
+      version: getVersion(body),
+      summary: getSummary(body),
+      deprecated: getDeprecated(body),
+      draft: getDraft(body),
+      ...(svcOwners.length > 0 ? { owners: svcOwners } : {}),
+      ...(notes.length > 0 ? { notes } : {}),
+    });
+
+    if (parentId) {
+      addEdge(parentId, svcId, "contains");
+    }
+
+    // Messages sent/received by a service inside a domain should be parented to the same domain
+    processSends(svcId, getSends(body), parentId);
+    processReceives(svcId, getReceives(body), parentId);
+
+    for (const ref of getWritesToRefs(body)) {
+      const containerId = resolveOrCreateMsg(
+        ref.ref.name,
+        "container",
+        ref.ref.version,
+      );
+      addEdge(svcId, containerId, "writes-to");
+    }
+
+    for (const ref of getReadsFromRefs(body)) {
+      const containerId = resolveOrCreateMsg(
+        ref.ref.name,
+        "container",
+        ref.ref.version,
+      );
+      addEdge(containerId, svcId, "reads-from");
+    }
+  }
+
+  function processSubdomain(sub: SubdomainDef, parentId: string): void {
+    const body = sub.body as AstNode[];
+    const subName = getName(body) || sub.name;
+    const subOwners = getOwners(body);
+    const subId = addNode(sub.name, "domain", subName, parentId, {
+      version: getVersion(body),
+      summary: getSummary(body),
+      deprecated: getDeprecated(body),
+      draft: getDraft(body),
+      ...(subOwners.length > 0 ? { owners: subOwners } : {}),
+    });
+    addEdge(parentId, subId, "contains");
+
+    for (const svc of getServices(body)) {
+      processService(svc, subId);
+    }
+
+    for (const ref of getServiceRefs(body)) {
+      const def = lookupDef(ref.ref.name, ref.ref.version);
+      if (def && isServiceDef(def)) {
+        processService(def, subId);
+      } else {
+        const svcId = resolveOrCreateMsg(
+          ref.ref.name,
+          "service",
+          ref.ref.version,
+          subId,
+        );
+        addEdge(subId, svcId, "contains");
+      }
+    }
+
+    for (const nested of getSubdomains(body)) {
+      processSubdomain(nested, subId);
+    }
+  }
+
+  function processDomain(domain: DomainDef): void {
+    const body = domain.body as AstNode[];
+    const domainName = getName(body) || domain.name;
+    const domOwners = getOwners(body);
+    const domId = addNode(domain.name, "domain", domainName, undefined, {
+      version: getVersion(body),
+      summary: getSummary(body),
+      deprecated: getDeprecated(body),
+      draft: getDraft(body),
+      ...(domOwners.length > 0 ? { owners: domOwners } : {}),
+    });
+
+    for (const svc of getServices(body)) {
+      processService(svc, domId);
+    }
+
+    for (const ref of getServiceRefs(body)) {
+      const def = lookupDef(ref.ref.name, ref.ref.version);
+      if (def && isServiceDef(def)) {
+        processService(def, domId);
+      } else {
+        const svcId = resolveOrCreateMsg(
+          ref.ref.name,
+          "service",
+          ref.ref.version,
+          domId,
+        );
+        addEdge(domId, svcId, "contains");
+      }
+    }
+
+    for (const container of getContainers(body)) {
+      const containerBody = container.body as AstNode[];
+      const containerId = addNode(
+        container.name,
+        "container",
+        getName(containerBody) || container.name,
+        domId,
+        {
+          version: getVersion(containerBody),
+          summary: getSummary(containerBody),
+          deprecated: getDeprecated(containerBody),
+          draft: getDraft(containerBody),
+          containerType: getContainerType(containerBody),
+        },
+      );
+      addEdge(domId, containerId, "contains");
+    }
+
+    for (const item of body.filter(isChannelDef)) {
+      const chBody = item.body as AstNode[];
+      const chBodyNotes = extractNotes(chBody);
+      const chId = addNode(
+        item.name,
+        "channel",
+        getName(chBody) || item.name,
+        domId,
+        {
+          version: getVersion(chBody),
+          summary: getSummary(chBody),
+          deprecated: getDeprecated(chBody),
+          draft: getDraft(chBody),
+          address: getAddress(chBody),
+          protocols: getProtocols(chBody),
+          ...(chBodyNotes.length > 0 ? { notes: chBodyNotes } : {}),
+        },
+      );
+      addEdge(domId, chId, "contains");
+
+      for (const route of getRoutes(chBody)) {
+        const targetChId = resolveOrCreateMsg(
+          route.ref.name,
+          "channel",
+          route.ref.version,
+        );
+        addEdge(chId, targetChId, "routes-to");
+      }
+    }
+
+    for (const sub of getSubdomains(body)) {
+      processSubdomain(sub, domId);
+    }
+
+    for (const flow of getFlows(body)) {
+      processFlow(flow, domId);
+    }
+
+    for (const ref of getFlowRefs(body)) {
+      const def = lookupDef(ref.ref.name, ref.ref.version);
+      if (def && isFlowDef(def)) {
+        processFlow(def, domId);
+      } else {
+        const flowId = resolveOrCreateMsg(
+          ref.ref.name,
+          "flow",
+          ref.ref.version,
+          domId,
+        );
+        addEdge(domId, flowId, "contains");
+      }
+    }
+
+    for (const ref of getDataProductRefs(body)) {
+      const dpId = resolveOrCreateMsg(
+        ref.ref.name,
+        "data-product",
+        ref.ref.version,
+        domId,
+      );
+      addEdge(domId, dpId, "contains");
+    }
+
+    processSends(domId, getSends(body));
+    processReceives(domId, getReceives(body));
+  }
+
+  function processFlow(def: FlowDef, parentId?: string): void {
+    const body = def.body as AstNode[];
+    const entryChains = getFlowEntryChains(body);
+    const whenBlocks = getFlowWhenBlocks(body);
+
+    if (entryChains.length > 0 || whenBlocks.length > 0) {
+      // Resolve a FlowRef to a graph node, inferring type from catalog
+      function resolveFlowRef(ref: FlowRef): string {
+        return resolveOrCreateMsg(
+          ref.name,
+          inferTypeFromCatalog(ref.name),
+          undefined,
+          parentId,
+        );
+      }
+
+      // Get the edge label from a FlowRef (the quoted string after the name)
+      function flowRefLabel(ref: FlowRef): string | undefined {
+        return ref.label ? stripQuotes(ref.label) : undefined;
+      }
+
+      // Process entry chains
+      for (const chain of entryChains) {
+        for (const ref of [...chain.sources, ...chain.targets]) {
+          resolveFlowRef(ref);
+        }
+        const firstTarget = chain.targets[0];
+        if (firstTarget) {
+          const firstTargetId = resolveFlowRef(firstTarget);
+          for (const src of chain.sources) {
+            addEdge(
+              resolveFlowRef(src),
+              firstTargetId,
+              "flow-step",
+              flowRefLabel(src),
+            );
+          }
+        }
+        for (let i = 0; i < chain.targets.length - 1; i++) {
+          addEdge(
+            resolveFlowRef(chain.targets[i]),
+            resolveFlowRef(chain.targets[i + 1]),
+            "flow-step",
+            flowRefLabel(chain.targets[i]),
+          );
+        }
+      }
+
+      // Process when blocks
+      for (const block of whenBlocks) {
+        for (const trigger of block.triggers) {
+          resolveFlowRef(trigger);
+        }
+        for (const action of block.actions) {
+          const actionId = resolveFlowRef(action.ref);
+          for (const trigger of block.triggers) {
+            addEdge(
+              resolveFlowRef(trigger),
+              actionId,
+              "flow-step",
+              flowRefLabel(action.ref),
+            );
+          }
+          for (const output of action.outputs) {
+            const targetId = resolveFlowRef(output.target);
+            addEdge(
+              actionId,
+              targetId,
+              "flow-step",
+              output.label ? stripQuotes(output.label) : undefined,
+            );
+          }
+        }
+      }
+    } else {
+      // No flow body — just show as a single node
+      const flowId = addNode(
+        def.name,
+        "flow",
+        getName(body) || def.name,
+        parentId,
+        {
+          version: getVersion(body),
+          summary: getSummary(body),
+          deprecated: getDeprecated(body),
+          draft: getDraft(body),
+        },
+      );
+      if (parentId) {
+        addEdge(parentId, flowId, "contains");
+      }
+    }
+  }
+
+  function processMessage(def: EventDef | CommandDef | QueryDef): void {
+    const nodeType: GraphNode["type"] = isEventDef(def)
+      ? "event"
+      : isCommandDef(def)
+        ? "command"
+        : "query";
+    const body = def.body as AstNode[];
+    const msgName = getName(body) || def.name;
+    const notes = extractNotes(body);
+    const msgOwners = getOwners(body);
+    const apiInfo = extractApiInfo(body);
+    addNode(def.name, nodeType, msgName, undefined, {
+      version: getVersion(body),
+      summary: getSummary(body),
+      deprecated: getDeprecated(body),
+      draft: getDraft(body),
+      schema: getSchema(body),
+      ...(msgOwners.length > 0 ? { owners: msgOwners } : {}),
+      ...(notes.length > 0 ? { notes } : {}),
+      ...(apiInfo.method ? { method: apiInfo.method } : {}),
+      ...(apiInfo.path ? { path: apiInfo.path } : {}),
+      ...(apiInfo.statusCodes && apiInfo.statusCodes.length > 0
+        ? { statusCodes: apiInfo.statusCodes }
+        : {}),
+    });
+
+    for (const ref of getChannelRefs(body)) {
+      resolveOrCreateMsg(ref.ref.name, "channel", ref.ref.version);
+    }
+  }
+
+  function processDefinition(def: ResourceDefinition): void {
+    if (isDomainDef(def)) {
+      processDomain(def);
+    } else if (isServiceDef(def)) {
+      processService(def);
+    } else if (isEventDef(def) || isCommandDef(def) || isQueryDef(def)) {
+      processMessage(def);
+    } else if (isChannelDef(def)) {
+      const body = def.body as AstNode[];
+      const chNotes = extractNotes(body);
+      const chOwners = getOwners(body);
+      const chId = addNode(
+        def.name,
+        "channel",
+        getName(body) || def.name,
+        undefined,
+        {
+          version: getVersion(body),
+          summary: getSummary(body),
+          deprecated: getDeprecated(body),
+          draft: getDraft(body),
+          address: getAddress(body),
+          protocols: getProtocols(body),
+          ...(chOwners.length > 0 ? { owners: chOwners } : {}),
+          ...(chNotes.length > 0 ? { notes: chNotes } : {}),
+        },
+      );
+
+      // Process route statements: channel → channel edges
+      for (const route of getRoutes(body)) {
+        const targetChId = resolveOrCreateMsg(
+          route.ref.name,
+          "channel",
+          route.ref.version,
+        );
+        addEdge(chId, targetChId, "routes-to");
+      }
+    } else if (isContainerDef(def)) {
+      const body = def.body as AstNode[];
+      const contOwners = getOwners(body);
+      addNode(def.name, "container", getName(body) || def.name, undefined, {
+        version: getVersion(body),
+        summary: getSummary(body),
+        deprecated: getDeprecated(body),
+        draft: getDraft(body),
+        containerType: getContainerType(body),
+        ...(contOwners.length > 0 ? { owners: contOwners } : {}),
+      });
+    } else if (isDataProductDef(def)) {
+      const body = def.body as AstNode[];
+      const dpOwners = getOwners(body);
+      const dpId = addNode(
+        def.name,
+        "data-product",
+        getName(body) || def.name,
+        undefined,
+        {
+          version: getVersion(body),
+          summary: getSummary(body),
+          deprecated: getDeprecated(body),
+          draft: getDraft(body),
+          ...(dpOwners.length > 0 ? { owners: dpOwners } : {}),
+        },
+      );
+      for (const inp of getInputs(body)) {
+        const inpType = inp.type as GraphNode["type"];
+        const existing =
+          resolveNodeId(inp.ref.name, "event", inp.ref.version) ||
+          resolveNodeId(inp.ref.name, "command", inp.ref.version) ||
+          resolveNodeId(inp.ref.name, "query", inp.ref.version);
+        const inpId =
+          existing ||
+          addNode(inp.ref.name, inpType, inp.ref.name, undefined, {
+            version: inp.ref.version,
+          });
+        addEdge(inpId, dpId, "sends");
+      }
+      for (const out of getOutputs(body)) {
+        const outType = out.type as GraphNode["type"];
+        const existing =
+          resolveNodeId(out.name, "event") ||
+          resolveNodeId(out.name, "command") ||
+          resolveNodeId(out.name, "query");
+        const outId = existing || addNode(out.name, outType, out.name);
+        addEdge(dpId, outId, "sends");
+      }
+    } else if (isFlowDef(def)) {
+      processFlow(def);
+    } else if (isDiagramDef(def)) {
+      const body = def.body as AstNode[];
+      addNode(def.name, "diagram", getName(body) || def.name, undefined, {
+        version: getVersion(body),
+        summary: getSummary(body),
+        deprecated: getDeprecated(body),
+        draft: getDraft(body),
+      });
+    } else if (isUserDef(def)) {
+      const props = def.props as AstNode[];
+      const userName = getName(props) || def.name;
+      let role: string | undefined;
+      let email: string | undefined;
+      for (const p of def.props) {
+        if ("value" in p && p.$type === "UserRoleProp")
+          role = stripQuotes(p.value);
+        if ("value" in p && p.$type === "UserEmailProp")
+          email = stripQuotes(p.value);
+      }
+
+      addNode(def.name, "user", userName, undefined, {
+        role,
+        email,
+      });
+    } else if (isTeamDef(def)) {
+      const props = def.props as AstNode[];
+      const teamName = getName(props) || def.name;
+      let summary: string | undefined;
+      let email: string | undefined;
+      const members: string[] = [];
+
+      for (const p of def.props) {
+        if (p.$type === "TeamSummaryProp") summary = stripQuotes(p.value);
+        if (p.$type === "TeamEmailProp") email = stripQuotes(p.value);
+        if (p.$type === "TeamMemberProp") members.push(p.memberRef);
+      }
+
+      const teamId = addNode(def.name, "team", teamName, undefined, {
+        summary,
+        email,
+      });
+      for (const m of members) {
+        const memberId = resolveNodeId(m, "user") || nid(m, "user");
+        addEdge(memberId, teamId, "member-of");
+      }
+    } else if (isActorDef(def)) {
+      const body = (def.body || []) as AstNode[];
+      addNode(def.name, "actor", getName(body) || def.name, undefined, {
+        summary: getSummary(body),
+      });
+    } else if (isExternalSystemDef(def)) {
+      const body = (def.body || []) as AstNode[];
+      addNode(
+        def.name,
+        "external-system",
+        getName(body) || def.name,
+        undefined,
+        {
+          summary: getSummary(body),
+        },
+      );
+    }
+  }
+
+  // Look up a top-level def by name, preferring an exact name+version match
+  function lookupDef(
+    name: string,
+    version?: string,
+  ): ResourceDefinition | undefined {
+    if (version) {
+      const exact = topLevelDefs.get(defKey(name, version));
+      if (exact) return exact;
+    }
+    return topLevelDefs.get(name);
+  }
+
+  function processVisualizerItem(item: VisualizerBodyItem): void {
+    // Ref statements → look up top-level def and process it
+    if (isServiceRefStmt(item)) {
+      const def = lookupDef(item.ref.name, item.ref.version);
+      if (def && isServiceDef(def)) {
+        processService(def);
+      } else {
+        addNode(item.ref.name, "service", item.ref.name, undefined, {
+          version: item.ref.version,
+        });
+      }
+      return;
+    }
+    if (isDomainRefStmt(item)) {
+      const def = lookupDef(item.ref.name, item.ref.version);
+      if (def && isDomainDef(def)) {
+        processDomain(def);
+      } else {
+        addNode(item.ref.name, "domain", item.ref.name, undefined, {
+          version: item.ref.version,
+        });
+      }
+      return;
+    }
+    if (isChannelRefStmt(item)) {
+      const def = lookupDef(item.ref.name, item.ref.version);
+      if (def && isChannelDef(def)) {
+        processDefinition(def);
+      } else {
+        addNode(item.ref.name, "channel", item.ref.name, undefined, {
+          version: item.ref.version,
+        });
+      }
+      return;
+    }
+    if (isDataProductRefStmt(item)) {
+      const def = lookupDef(item.ref.name, item.ref.version);
+      if (def && isDataProductDef(def)) {
+        processDefinition(def);
+      } else {
+        addNode(item.ref.name, "data-product", item.ref.name, undefined, {
+          version: item.ref.version,
+        });
+      }
+      return;
+    }
+    if (isFlowRefStmt(item)) {
+      const def = lookupDef(item.ref.name, item.ref.version);
+      if (def && isFlowDef(def)) {
+        processDefinition(def);
+      } else {
+        addNode(item.ref.name, "flow", item.ref.name, undefined, {
+          version: item.ref.version,
+        });
+      }
+      return;
+    }
+    if (isContainerRefStmt(item)) {
+      const def = lookupDef(item.ref.name, item.ref.version);
+      if (def && isContainerDef(def)) {
+        processDefinition(def);
+      } else {
+        addNode(item.ref.name, "container", item.ref.name, undefined, {
+          version: item.ref.version,
+        });
+      }
+      return;
+    }
+    if (
+      isEventRefStmt(item) ||
+      isCommandRefStmt(item) ||
+      isQueryRefStmt(item)
+    ) {
+      const nodeType: GraphNode["type"] = isEventRefStmt(item)
+        ? "event"
+        : isCommandRefStmt(item)
+          ? "command"
+          : "query";
+      const def = lookupDef(item.ref.name, item.ref.version);
+      if (def && (isEventDef(def) || isCommandDef(def) || isQueryDef(def))) {
+        processMessage(def);
+      } else {
+        addNode(item.ref.name, nodeType, item.ref.name, undefined, {
+          version: item.ref.version,
+        });
+      }
+      return;
+    }
+
+    // EventDef/CommandDef/QueryDef with empty body → treat as reference
+    if (
+      (isEventDef(item) || isCommandDef(item) || isQueryDef(item)) &&
+      (!item.body || item.body.length === 0)
+    ) {
+      const nodeType: GraphNode["type"] = isEventDef(item)
+        ? "event"
+        : isCommandDef(item)
+          ? "command"
+          : "query";
+      const def = topLevelDefs.get(item.name);
+      if (def && (isEventDef(def) || isCommandDef(def) || isQueryDef(def))) {
+        processMessage(def);
+      } else {
+        addNode(item.name, nodeType, item.name);
+      }
+      return;
+    }
+
+    // Inline definitions → use existing process functions
+    if (isDomainDef(item)) {
+      processDomain(item);
+      return;
+    }
+    if (isServiceDef(item)) {
+      processService(item);
+      return;
+    }
+    if (isEventDef(item) || isCommandDef(item) || isQueryDef(item)) {
+      processMessage(item);
+      return;
+    }
+    if (
+      isChannelDef(item) ||
+      isContainerDef(item) ||
+      isDataProductDef(item) ||
+      isFlowDef(item) ||
+      isActorDef(item) ||
+      isExternalSystemDef(item)
+    ) {
+      processDefinition(item as ResourceDefinition);
+      return;
+    }
+  }
+
+  // Process only items inside the active visualizer body
+  for (const item of activeViz.body) {
+    processVisualizerItem(item);
+  }
+
+  // Merge writes-to + reads-from pairs into a single bidirectional reads-writes edge
+  const writesToEdges = edges.filter((e) => e.type === "writes-to");
+  for (const wEdge of writesToEdges) {
+    // A writes-to edge goes service→container; a matching reads-from goes container→service
+    const rIdx = edges.findIndex(
+      (e) =>
+        e.type === "reads-from" &&
+        e.source === wEdge.target &&
+        e.target === wEdge.source,
+    );
+    if (rIdx !== -1) {
+      // Remove the reads-from edge
+      edges.splice(rIdx, 1);
+      // Replace the writes-to edge with a reads-writes edge (service→container)
+      wEdge.type = "reads-writes";
+      wEdge.id = `${wEdge.source}-reads-writes-${wEdge.target}`;
+    }
+  }
+
+  // Post-processing: remove redundant direct message → channel "routes-to" edges
+  // when an indirect path already exists through channel routing chains.
+  // This handles cases where processReceives creates a direct edge before
+  // channel route edges are fully resolved (due to processing order).
+  for (let i = edges.length - 1; i >= 0; i--) {
+    const e = edges[i];
+    if (e.type !== "routes-to") continue;
+    const sourceNode = nodes.find((n) => n.id === e.source);
+    const targetNode = nodes.find((n) => n.id === e.target);
+    if (!sourceNode || !targetNode) continue;
+    // Only check message → channel edges (not channel → channel routes)
+    if (sourceNode.type === "channel") continue;
+    if (targetNode.type !== "channel") continue;
+    // Check if there's an indirect path from this message to the target channel
+    if (canReachViaRoutes(e.source, e.target, edges, e.id)) {
+      edges.splice(i, 1);
+    }
+  }
+
+  return {
+    nodes,
+    edges,
+    visualizers: visualizerNames,
+    activeVisualizer: activeViz.name,
+    title: vizTitle,
+    options,
+  };
+}
diff --git a/packages/language-server/src/index.ts b/packages/language-server/src/index.ts
new file mode 100644
index 000000000..31eab6687
--- /dev/null
+++ b/packages/language-server/src/index.ts
@@ -0,0 +1,59 @@
+// Public API exports
+export { createEcServices } from "./ec-module.js";
+export type { EcServices, EcAddedServices } from "./ec-module.js";
+export { EcCompletionProvider } from "./ec-completion-provider.js";
+export {
+  collectRegexMatches,
+  collectChannelNames,
+  collectMessageNames,
+  extractResourceVersions,
+  parseSpecAuto,
+  findEnclosingResource,
+} from "./completion-utils.js";
+export type { ParsedSpecResult } from "./completion-utils.js";
+export {
+  RESOURCE_KEYWORDS,
+  COMMON_PROPS,
+  ANNOTATION_SUGGESTIONS,
+  CONTEXT_SUGGESTIONS,
+  MESSAGE_TYPE_PLURAL,
+} from "./completion-data.js";
+export type { Suggestion } from "./completion-data.js";
+export { EcLanguageMetaData } from "./generated/module.js";
+export * from "./generated/ast.js";
+export { astToGraph } from "./graph.js";
+export type { GraphNode, GraphEdge, DslGraph } from "./graph-types.js";
+export { compile } from "./compiler.js";
+export type { CompiledOutput, CompileOptions } from "./compiler.js";
+export * from "./ast-utils.js";
+export { formatEc } from "./formatter.js";
+export {
+  parseSpec,
+  extractMessages,
+  extractChannels,
+  extractService,
+  messageToEc,
+  channelToEc,
+  serviceToEc,
+  parseOpenApiSpec,
+  extractOpenApiService,
+  openApiServiceToEc,
+  openApiMessageToEc,
+  resolveSpecImports,
+  resolveSpecImportsAsync,
+  detectSpecType,
+  isSpecFile,
+  resolveAsyncApiImports,
+  resolveAsyncApiImportsAsync,
+} from "./resolvers/index.js";
+export type { ParsedOpenApiSpec } from "./resolvers/index.js";
+export type {
+  SpecMessage,
+  SpecChannel,
+  SpecOperation,
+  SpecService,
+  ResourceType,
+  ResolveError,
+  SpecResolveResult,
+  FetchFn,
+} from "./resolvers/index.js";
diff --git a/packages/language-server/src/main-browser.ts b/packages/language-server/src/main-browser.ts
new file mode 100644
index 000000000..b4c0433a4
--- /dev/null
+++ b/packages/language-server/src/main-browser.ts
@@ -0,0 +1,30 @@
+import { startLanguageServer } from "langium/lsp";
+import { createDefaultModule, createDefaultSharedModule } from "langium/lsp";
+import { EmptyFileSystem, inject } from "langium";
+import {
+  BrowserMessageReader,
+  BrowserMessageWriter,
+  createConnection,
+} from "vscode-languageserver/browser.js";
+import {
+  EcGeneratedModule,
+  EcGeneratedSharedModule,
+} from "./generated/module.js";
+import { EcModule } from "./ec-module.js";
+import { registerValidationChecks } from "./ec-validator.js";
+
+declare const self: any;
+
+const reader = new BrowserMessageReader(self);
+const writer = new BrowserMessageWriter(self);
+const connection = createConnection(reader, writer);
+
+const shared = inject(
+  createDefaultSharedModule({ connection, ...EmptyFileSystem }),
+  EcGeneratedSharedModule,
+);
+const Ec = inject(createDefaultModule({ shared }), EcGeneratedModule, EcModule);
+shared.ServiceRegistry.register(Ec);
+registerValidationChecks(Ec);
+
+startLanguageServer(shared);
diff --git a/packages/language-server/src/main.ts b/packages/language-server/src/main.ts
new file mode 100644
index 000000000..096208390
--- /dev/null
+++ b/packages/language-server/src/main.ts
@@ -0,0 +1,48 @@
+import { startLanguageServer } from "langium/lsp";
+import { createDefaultModule, createDefaultSharedModule } from "langium/lsp";
+import type { LangiumServices, PartialLangiumLSPServices } from "langium/lsp";
+import { type Module, inject } from "langium";
+import { NodeFileSystem } from "langium/node";
+import {
+  createConnection,
+  ProposedFeatures,
+} from "vscode-languageserver/node.js";
+import {
+  EcGeneratedModule,
+  EcGeneratedSharedModule,
+} from "./generated/module.js";
+import { EcModule } from "./ec-module.js";
+import { EcCompletionProvider } from "./ec-completion-provider.js";
+import { EcDefinitionProvider } from "./ec-definition-provider.js";
+import { EcHoverProvider } from "./ec-hover-provider.js";
+import { EcFormatterProvider } from "./ec-formatter-provider.js";
+import { registerValidationChecks } from "./ec-validator.js";
+
+/**
+ * LSP module that overrides default providers with EC-specific implementations.
+ */
+const EcLspModule: Module<LangiumServices, PartialLangiumLSPServices> = {
+  lsp: {
+    CompletionProvider: (services) => new EcCompletionProvider(services),
+    DefinitionProvider: (services) => new EcDefinitionProvider(services),
+    HoverProvider: (services) => new EcHoverProvider(services),
+    Formatter: () => new EcFormatterProvider(),
+  },
+};
+
+const connection = createConnection(ProposedFeatures.all);
+
+const shared = inject(
+  createDefaultSharedModule({ connection, ...NodeFileSystem }),
+  EcGeneratedSharedModule,
+);
+const Ec = inject(
+  createDefaultModule({ shared }),
+  EcGeneratedModule,
+  EcModule,
+  EcLspModule,
+);
+shared.ServiceRegistry.register(Ec);
+registerValidationChecks(Ec);
+
+startLanguageServer(shared);
diff --git a/packages/language-server/src/resolvers/asyncapi.ts b/packages/language-server/src/resolvers/asyncapi.ts
new file mode 100644
index 000000000..255b6730b
--- /dev/null
+++ b/packages/language-server/src/resolvers/asyncapi.ts
@@ -0,0 +1,646 @@
+import yaml from "js-yaml";
+import type {
+  SpecMessage,
+  SpecChannel,
+  SpecOperation,
+  SpecService,
+  ResourceType,
+  ResolveError,
+} from "./types.js";
+
+export const RESOURCE_TYPE_SINGULAR: Record<ResourceType, string> = {
+  events: "event",
+  commands: "command",
+  queries: "query",
+  channels: "channel",
+  services: "service",
+  containers: "container",
+};
+
+function resolveRef(doc: any, ref: string): any {
+  if (!ref.startsWith("#/")) return null;
+  return ref
+    .slice(2)
+    .split("/")
+    .reduce(
+      (current, part) =>
+        current != null && typeof current === "object" ? current[part] : null,
+      doc as any,
+    );
+}
+
+interface ParsedSpec {
+  doc: any;
+  messages: Map<string, SpecMessage>;
+  channels: Map<string, SpecChannel>;
+  errors: ResolveError[];
+}
+
+/**
+ * Parse an AsyncAPI v2 or v3 document and extract both messages and channels.
+ */
+export function parseSpec(content: string): ParsedSpec {
+  let doc: any;
+  try {
+    doc = yaml.load(content);
+  } catch (e) {
+    return {
+      doc: null,
+      messages: new Map(),
+      channels: new Map(),
+      errors: [
+        {
+          message: `Failed to parse AsyncAPI YAML: ${String(e)}`,
+          line: 1,
+          column: 1,
+        },
+      ],
+    };
+  }
+
+  if (!doc || typeof doc !== "object") {
+    return {
+      doc: null,
+      messages: new Map(),
+      channels: new Map(),
+      errors: [
+        { message: "AsyncAPI file is empty or invalid", line: 1, column: 1 },
+      ],
+    };
+  }
+
+  const asyncApiVersion = doc.asyncapi || "";
+
+  const [messages, channels] = asyncApiVersion.startsWith("3.")
+    ? [extractV3Messages(doc), extractV3Channels(doc)]
+    : asyncApiVersion.startsWith("2.")
+      ? [extractV2Messages(doc), extractV2Channels(doc)]
+      : [new Map<string, SpecMessage>(), new Map<string, SpecChannel>()];
+
+  // Apply spec-level version to resources that don't have their own
+  if (doc.info?.version) {
+    const specVersion = doc.info.version;
+    for (const msg of messages.values()) {
+      if (!msg.version) msg.version = specVersion;
+    }
+    for (const ch of channels.values()) {
+      if (!ch.version) ch.version = specVersion;
+    }
+  }
+
+  return { doc, messages, channels, errors: [] };
+}
+
+/**
+ * Extract a full service definition from an AsyncAPI spec.
+ * Infers the service name, channels, messages, and send/receive operations.
+ */
+export function extractService(
+  content: string,
+  serviceName?: string,
+): { service: SpecService; errors: ResolveError[] } {
+  const emptyService = (name: string): SpecService => ({
+    name,
+    operations: [],
+    channels: [],
+    messages: [],
+  });
+
+  const parsed = parseSpec(content);
+  if (parsed.errors.length > 0 || !parsed.doc) {
+    return {
+      service: emptyService(serviceName || "UnknownService"),
+      errors:
+        parsed.errors.length > 0
+          ? parsed.errors
+          : [
+              {
+                message: "AsyncAPI file is empty or invalid",
+                line: 1,
+                column: 1,
+              },
+            ],
+    };
+  }
+
+  const doc = parsed.doc;
+  const name =
+    serviceName || sanitizeServiceName(doc.info?.title) || "UnknownService";
+  const version = doc.info?.version;
+  const summary = doc.info?.description?.trim().split("\n")[0];
+  const asyncApiVersion = doc.asyncapi || "";
+
+  const operations = asyncApiVersion.startsWith("3.")
+    ? extractV3Operations(doc)
+    : asyncApiVersion.startsWith("2.")
+      ? extractV2Operations(doc)
+      : [];
+
+  // Collect channels and messages referenced by operations
+  const usedChannelNames = new Set(operations.map((op) => op.channelName));
+  const usedMessageNames = new Set(operations.map((op) => op.messageName));
+
+  const channels = [...parsed.channels.values()].filter((ch) =>
+    usedChannelNames.has(ch.name),
+  );
+  const messages = [...parsed.messages.values()].filter((msg) =>
+    usedMessageNames.has(msg.name),
+  );
+
+  return {
+    service: { name, version, summary, operations, channels, messages },
+    errors: [],
+  };
+}
+
+export function sanitizeServiceName(
+  title: string | undefined,
+): string | undefined {
+  if (!title) return undefined;
+  // Remove trailing words like "API", "Service", "Events" if they'd be redundant
+  // Then PascalCase the result
+  return title
+    .replace(/[^a-zA-Z0-9\s]/g, "")
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("");
+}
+
+/**
+ * Extract messages from an AsyncAPI document.
+ * Convenience wrapper around parseSpec for callers that only need messages.
+ */
+export function extractMessages(content: string): {
+  messages: Map<string, SpecMessage>;
+  errors: ResolveError[];
+} {
+  const { messages, errors } = parseSpec(content);
+  return { messages, errors };
+}
+
+/**
+ * Extract channels from an AsyncAPI document.
+ * Convenience wrapper around parseSpec for callers that only need channels.
+ */
+export function extractChannels(content: string): {
+  channels: Map<string, SpecChannel>;
+  errors: ResolveError[];
+} {
+  const { channels, errors } = parseSpec(content);
+  return { channels, errors };
+}
+
+// ─── V3 extractors ──────────────────────────────────────
+
+function extractV3Messages(doc: any): Map<string, SpecMessage> {
+  const messages = new Map<string, SpecMessage>();
+
+  if (doc.components?.messages) {
+    for (const [name, msg] of Object.entries<any>(doc.components.messages)) {
+      messages.set(name, {
+        name,
+        summary: msg.summary || msg.title,
+        description: msg.description,
+      });
+    }
+  }
+
+  if (doc.channels) {
+    for (const channel of Object.values<any>(doc.channels)) {
+      if (!channel.messages) continue;
+      for (const [name, msg] of Object.entries<any>(channel.messages)) {
+        if (messages.has(name)) continue;
+        const resolved = msg.$ref ? resolveRef(doc, msg.$ref) : msg;
+        if (resolved) {
+          messages.set(name, {
+            name,
+            summary: resolved.summary || resolved.title,
+            description: resolved.description,
+          });
+        }
+      }
+    }
+  }
+
+  return messages;
+}
+
+function extractV3Channels(doc: any): Map<string, SpecChannel> {
+  const channels = new Map<string, SpecChannel>();
+  if (!doc.channels) return channels;
+
+  const defaultProtocol = guessProtocol(doc);
+
+  for (const [name, ch] of Object.entries<any>(doc.channels)) {
+    channels.set(name, {
+      name,
+      address: ch.address,
+      protocol: getChannelProtocol(ch, doc) || defaultProtocol,
+      summary: ch.summary || ch.description || ch.title,
+    });
+  }
+
+  return channels;
+}
+
+function extractV3Operations(doc: any): SpecOperation[] {
+  if (!doc.operations) return [];
+
+  const operations: SpecOperation[] = [];
+
+  for (const [, op] of Object.entries<any>(doc.operations)) {
+    const action = op.action as "send" | "receive";
+    if (!action) continue;
+
+    // Resolve channel reference
+    const channelRef = op.channel?.$ref;
+    const channelName = channelRef
+      ? channelRef.replace("#/channels/", "")
+      : undefined;
+    if (!channelName) continue;
+
+    // If the operation specifies its own messages, use only those
+    const opMessages = resolveV3OperationMessages(op, doc);
+    if (opMessages.length > 0) {
+      for (const { name, resolved } of opMessages) {
+        operations.push({
+          action,
+          channelName,
+          messageName: name,
+          summary: resolved?.summary || resolved?.title || op.summary,
+        });
+      }
+      continue;
+    }
+
+    // Fall back to all messages on the referenced channel
+    const channel = doc.channels?.[channelName];
+    if (!channel?.messages) continue;
+
+    for (const [messageName, msg] of Object.entries<any>(channel.messages)) {
+      const resolved = msg.$ref ? resolveRef(doc, msg.$ref) : msg;
+      operations.push({
+        action,
+        channelName,
+        messageName,
+        summary: resolved?.summary || resolved?.title || op.summary,
+      });
+    }
+  }
+
+  return deduplicateOperations(operations);
+}
+
+/**
+ * Resolve the `messages` array on a v3 operation.
+ * Each entry can be a `$ref` to a channel message or a component message.
+ */
+function resolveV3OperationMessages(
+  op: any,
+  doc: any,
+): { name: string; resolved: any }[] {
+  if (!Array.isArray(op.messages) || op.messages.length === 0) return [];
+
+  const results: { name: string; resolved: any }[] = [];
+  for (const msgEntry of op.messages) {
+    const ref = msgEntry.$ref;
+    if (!ref) continue;
+
+    // Refs like "#/channels/orderCreated/messages/OrderCreated"
+    const channelMsgMatch = ref.match(
+      /^#\/channels\/[^/]+\/messages\/([^/]+)$/,
+    );
+    if (channelMsgMatch) {
+      const resolved = resolveRef(doc, ref);
+      const finalResolved = resolved?.$ref
+        ? resolveRef(doc, resolved.$ref)
+        : resolved;
+      results.push({ name: channelMsgMatch[1], resolved: finalResolved });
+      continue;
+    }
+
+    // Refs like "#/components/messages/OrderCreated"
+    const componentMsgMatch = ref.match(/^#\/components\/messages\/([^/]+)$/);
+    if (componentMsgMatch) {
+      const resolved = resolveRef(doc, ref);
+      results.push({ name: componentMsgMatch[1], resolved });
+    }
+  }
+  return results;
+}
+
+// ─── V2 extractors ──────────────────────────────────────
+
+function extractV2Messages(doc: any): Map<string, SpecMessage> {
+  const messages = new Map<string, SpecMessage>();
+
+  if (doc.components?.messages) {
+    for (const [name, msg] of Object.entries<any>(doc.components.messages)) {
+      messages.set(name, {
+        name,
+        summary: msg.summary || msg.title,
+        description: msg.description,
+      });
+    }
+  }
+
+  if (doc.channels) {
+    for (const channel of Object.values<any>(doc.channels)) {
+      for (const op of [channel.publish, channel.subscribe]) {
+        const msg = op?.message;
+        if (!msg) continue;
+        for (const resolved of resolveV2MessageEntries(msg, doc)) {
+          if (!messages.has(resolved.name)) {
+            messages.set(resolved.name, resolved);
+          }
+        }
+      }
+    }
+  }
+
+  return messages;
+}
+
+function extractV2Channels(doc: any): Map<string, SpecChannel> {
+  const channels = new Map<string, SpecChannel>();
+  if (!doc.channels) return channels;
+
+  const defaultProtocol = guessProtocol(doc);
+
+  for (const [address, ch] of Object.entries<any>(doc.channels)) {
+    const name = address.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-");
+    channels.set(name, {
+      name,
+      address,
+      protocol: ch.bindings ? Object.keys(ch.bindings)[0] : defaultProtocol,
+      summary: ch.description || ch.summary,
+    });
+  }
+
+  return channels;
+}
+
+function extractV2Operations(doc: any): SpecOperation[] {
+  if (!doc.channels) return [];
+
+  const operations: SpecOperation[] = [];
+
+  for (const [address, ch] of Object.entries<any>(doc.channels)) {
+    const channelName = address
+      .replace(/[^a-zA-Z0-9_-]/g, "-")
+      .replace(/-+/g, "-");
+
+    if (ch.publish?.message) {
+      for (const { name, summary } of resolveV2Message(
+        ch.publish.message,
+        doc,
+      )) {
+        operations.push({
+          action: "send",
+          channelName,
+          messageName: name,
+          summary,
+        });
+      }
+    }
+
+    if (ch.subscribe?.message) {
+      for (const { name, summary } of resolveV2Message(
+        ch.subscribe.message,
+        doc,
+      )) {
+        operations.push({
+          action: "receive",
+          channelName,
+          messageName: name,
+          summary,
+        });
+      }
+    }
+  }
+
+  return operations;
+}
+
+/**
+ * Resolve a v2 message object, handling $ref and oneOf.
+ * Returns an array because oneOf can expand to multiple messages.
+ */
+function resolveV2Message(
+  msg: any,
+  doc: any,
+): { name: string; summary?: string }[] {
+  return resolveV2MessageEntries(msg, doc).map(({ name, summary }) => ({
+    name,
+    summary,
+  }));
+}
+
+/**
+ * Resolve a v2 message to full SpecMessage entries (with description).
+ * Handles $ref, oneOf, and name extraction from $ref paths.
+ */
+function resolveV2MessageEntries(msg: any, doc: any): SpecMessage[] {
+  if (!msg) return [];
+
+  // Resolve $ref first
+  const resolved = msg.$ref ? resolveRef(doc, msg.$ref) : msg;
+  if (!resolved) return [];
+
+  // Handle oneOf: each entry is a separate message
+  if (Array.isArray(resolved.oneOf)) {
+    return resolved.oneOf.flatMap((entry: any) =>
+      resolveV2MessageEntries(entry, doc),
+    );
+  }
+
+  let name = resolved.name || resolved.messageId;
+  if (!name && msg.$ref) {
+    // Extract name from $ref path (e.g. "#/components/messages/OrderCreated")
+    const refMatch = msg.$ref.match(/\/([^/]+)$/);
+    if (refMatch) name = refMatch[1];
+  }
+  if (!name) return [];
+
+  return [
+    {
+      name,
+      summary: resolved.summary || resolved.title,
+      description: resolved.description,
+    },
+  ];
+}
+
+/**
+ * Deduplicate operations that reference the same message on the same channel.
+ * Can happen when multiple v3 operations point to the same channel+message.
+ */
+function deduplicateOperations(ops: SpecOperation[]): SpecOperation[] {
+  const seen = new Set<string>();
+  return ops.filter((op) => {
+    const key = `${op.action}:${op.channelName}:${op.messageName}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+// ─── Protocol helpers ───────────────────────────────────
+
+function guessProtocol(doc: any): string | undefined {
+  const servers = doc.servers ? Object.values<any>(doc.servers) : [];
+  return servers[0]?.protocol;
+}
+
+function getChannelProtocol(channel: any, doc: any): string | undefined {
+  if (channel.bindings) {
+    const protocols = Object.keys(channel.bindings);
+    if (protocols.length > 0) return protocols[0];
+  }
+  if (Array.isArray(channel.servers) && channel.servers.length > 0) {
+    const serverRef = channel.servers[0];
+    const server = serverRef.$ref ? resolveRef(doc, serverRef.$ref) : serverRef;
+    if (server?.protocol) return server.protocol;
+  }
+  return undefined;
+}
+
+// ─── EC code generation ─────────────────────────────────
+
+/**
+ * Convert a SpecMessage to an .ec definition string.
+ */
+export function messageToEc(
+  msg: SpecMessage,
+  resourceType: ResourceType,
+): string {
+  return ecBlock(RESOURCE_TYPE_SINGULAR[resourceType], msg.name, [
+    msg.displayName && `name "${escapeEc(msg.displayName)}"`,
+    msg.version && `version ${msg.version}`,
+    msg.summary && `summary "${escapeEc(msg.summary)}"`,
+  ]);
+}
+
+/**
+ * Convert a SpecChannel to an .ec channel definition string.
+ */
+export function channelToEc(ch: SpecChannel): string {
+  return ecBlock("channel", ch.name, [
+    ch.displayName && `name "${escapeEc(ch.displayName)}"`,
+    ch.version && `version ${ch.version}`,
+    ch.address && `address "${escapeEc(ch.address)}"`,
+    ch.protocol && `protocol "${escapeEc(ch.protocol)}"`,
+    ch.summary && `summary "${escapeEc(ch.summary)}"`,
+  ]);
+}
+
+/**
+ * Convert a SpecMessage (container) to an .ec container definition string.
+ */
+export function containerToEc(msg: SpecMessage): string {
+  return ecBlock("container", msg.name, [
+    msg.displayName && `name "${escapeEc(msg.displayName)}"`,
+    msg.version && `version ${msg.version}`,
+    msg.summary && `summary "${escapeEc(msg.summary)}"`,
+  ]);
+}
+
+/**
+ * Convert a SpecService to a full .ec definition string.
+ * Generates channel definitions, event definitions, and the service block
+ * with sends/receives routed through channels.
+ */
+export function serviceToEc(service: SpecService): string {
+  const parts: string[] = [];
+
+  // Generate channel definitions
+  for (const ch of service.channels) {
+    parts.push(channelToEc(ch));
+  }
+
+  // Generate standalone message definitions so metadata (summary, version) is available.
+  // Deduplicate: a message that appears in both sends and receives should only be emitted once.
+  const msgTypeLookup = new Map(
+    service.operations.map((op) => [op.messageName, op.messageType || "event"]),
+  );
+  const emittedMessages = new Set<string>();
+  for (const msg of service.messages) {
+    if (emittedMessages.has(msg.name)) continue;
+    emittedMessages.add(msg.name);
+    const resourceType = msgTypeLookup.get(msg.name) || "event";
+    const singular =
+      RESOURCE_TYPE_SINGULAR[`${resourceType}s` as ResourceType] ||
+      resourceType;
+    parts.push(
+      ecBlock(singular, msg.name, [
+        msg.version && `version ${msg.version}`,
+        msg.summary && `summary "${escapeEc(msg.summary)}"`,
+      ]),
+    );
+  }
+
+  // Build the service block
+  const serviceProps: (string | false | undefined | null)[] = [
+    service.version && `version ${service.version}`,
+    service.summary && `summary "${escapeEc(service.summary)}"`,
+  ];
+
+  // Group operations by action for readability
+  const sends = service.operations.filter((op) => op.action === "send");
+  const receives = service.operations.filter((op) => op.action === "receive");
+
+  // Add blank line before sends/receives if we have version/summary
+  if (serviceProps.some(Boolean) && (sends.length > 0 || receives.length > 0)) {
+    serviceProps.push("");
+  }
+
+  const messageVersions = new Map(
+    service.messages.map((m) => [m.name, m.version]),
+  );
+
+  for (const op of sends) {
+    const version = messageVersions.get(op.messageName);
+    const versionSuffix = version ? `@${version}` : "";
+    const msgType = op.messageType || "event";
+    const channelClause = op.channelName ? ` to ${op.channelName}` : "";
+    serviceProps.push(
+      `sends ${msgType} ${op.messageName}${versionSuffix}${channelClause}`,
+    );
+  }
+
+  for (const op of receives) {
+    const version = messageVersions.get(op.messageName);
+    const versionSuffix = version ? `@${version}` : "";
+    const msgType = op.messageType || "event";
+    const channelClause = op.channelName ? ` from ${op.channelName}` : "";
+    serviceProps.push(
+      `receives ${msgType} ${op.messageName}${versionSuffix}${channelClause}`,
+    );
+  }
+
+  parts.push(ecBlock("service", service.name, serviceProps));
+
+  return parts.join("\n\n");
+}
+
+export function ecBlock(
+  keyword: string,
+  name: string,
+  props: (string | false | undefined | null)[],
+): string {
+  const body = props.filter(
+    (p) => p !== false && p !== undefined && p !== null,
+  ) as string[];
+  const indented = body.map((line) => (line === "" ? "" : `  ${line}`));
+  return [`${keyword} ${name} {`, ...indented, "}"].join("\n");
+}
+
+export function escapeEc(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, " ")
+    .replace(/\r/g, "")
+    .trim();
+}
diff --git a/packages/language-server/src/resolvers/catalog.ts b/packages/language-server/src/resolvers/catalog.ts
new file mode 100644
index 000000000..53a74746e
--- /dev/null
+++ b/packages/language-server/src/resolvers/catalog.ts
@@ -0,0 +1,381 @@
+import {
+  isCatalogPath,
+  type SpecMessage,
+  type SpecChannel,
+  type SpecService,
+  type SpecOperation,
+  type ResourceType,
+  type ResolveError,
+} from "./types.js";
+
+// All Node.js imports are lazy to avoid breaking browser builds.
+// The functions in this module are only called in Node.js contexts
+// (VSCode LSP, CLI) — never in the browser playground.
+type SdkFactory = (dir: string) => Record<string, any>;
+let _sdk: SdkFactory | undefined;
+
+async function getSdk(): Promise<SdkFactory> {
+  if (!_sdk) {
+    // @ts-ignore - SDK types may not be available during build; runtime-only import
+    const mod = await import("@eventcatalog/sdk");
+    _sdk = mod.default as unknown as SdkFactory;
+  }
+  return _sdk;
+}
+
+const MESSAGE_SDK_METHODS: Record<string, string> = {
+  events: "getEvents",
+  commands: "getCommands",
+  queries: "getQueries",
+  containers: "getDataStores",
+};
+
+export interface CatalogResolveResult {
+  messages: Map<string, SpecMessage>;
+  errors: ResolveError[];
+}
+
+export interface CatalogChannelResolveResult {
+  channels: Map<string, SpecChannel>;
+  errors: ResolveError[];
+}
+
+export interface CatalogServiceResolveResult {
+  services: Map<string, SpecService>;
+  errors: ResolveError[];
+}
+
+export { isCatalogPath } from "./types.js";
+
+async function validateCatalogDir(
+  catalogDir: string,
+): Promise<ResolveError | null> {
+  try {
+    const { statSync } = await import("node:fs");
+    if (!statSync(catalogDir).isDirectory()) {
+      return {
+        message: `Catalog directory not found: "${catalogDir}"`,
+        line: 1,
+        column: 1,
+      };
+    }
+    return null;
+  } catch {
+    return {
+      message: `Catalog directory not found: "${catalogDir}"`,
+      line: 1,
+      column: 1,
+    };
+  }
+}
+
+// ─── TTL cache ───────────────────────────────────────────
+// Catalogs can be large. We cache SDK results for a short TTL so that
+// multiple import lines pointing at the same catalog (or rapid completion
+// keystrokes) don't each trigger a full filesystem scan.
+
+const CACHE_TTL_MS = 5_000; // 5 seconds
+const CACHE_MAX_SIZE = 50; // max entries per cache map
+
+interface CacheEntry<T> {
+  data: T;
+  ts: number;
+}
+
+const resourceCache = new Map<string, CacheEntry<CatalogResolveResult>>();
+const channelCache = new Map<string, CacheEntry<CatalogChannelResolveResult>>();
+const serviceCache = new Map<string, CacheEntry<CatalogServiceResolveResult>>();
+
+function getCached<T>(
+  cache: Map<string, CacheEntry<T>>,
+  key: string,
+): T | undefined {
+  const entry = cache.get(key);
+  if (!entry) return undefined;
+  if (Date.now() - entry.ts > CACHE_TTL_MS) {
+    cache.delete(key);
+    return undefined;
+  }
+  return entry.data;
+}
+
+function setCached<T>(
+  cache: Map<string, CacheEntry<T>>,
+  key: string,
+  data: T,
+): void {
+  if (cache.size >= CACHE_MAX_SIZE) {
+    // Evict oldest entry
+    let oldestKey: string | undefined;
+    let oldestTs = Infinity;
+    for (const [k, v] of cache) {
+      if (v.ts < oldestTs) {
+        oldestTs = v.ts;
+        oldestKey = k;
+      }
+    }
+    if (oldestKey) cache.delete(oldestKey);
+  }
+  cache.set(key, { data, ts: Date.now() });
+}
+
+/** Clear all catalog caches. Useful when the catalog directory changes. */
+export function clearCatalogCache(): void {
+  resourceCache.clear();
+  channelCache.clear();
+  serviceCache.clear();
+}
+
+// ─── Public API ──────────────────────────────────────────
+
+/**
+ * Scan an EventCatalog directory and return all resources of a given type as SpecMessages.
+ * Works for events, commands, and queries.
+ * Results are cached for CACHE_TTL_MS to avoid redundant filesystem scans.
+ */
+export async function parseCatalogResources(
+  catalogDir: string,
+  resourceType: ResourceType,
+): Promise<CatalogResolveResult> {
+  const cacheKey = `${catalogDir}::${resourceType}`;
+  const cached = getCached(resourceCache, cacheKey);
+  if (cached) return cached;
+
+  const errors: ResolveError[] = [];
+
+  const dirError = await validateCatalogDir(catalogDir);
+  if (dirError) return { messages: new Map(), errors: [dirError] };
+
+  const sdkMethodName = MESSAGE_SDK_METHODS[resourceType];
+  if (!sdkMethodName) {
+    errors.push({
+      message: `Catalog imports do not support resource type "${resourceType}" yet.`,
+      line: 1,
+      column: 1,
+    });
+    return { messages: new Map(), errors };
+  }
+
+  try {
+    const sdkFactory = await getSdk();
+    const catalog = sdkFactory(catalogDir);
+    const resources: any[] = await catalog[sdkMethodName]({
+      latestOnly: true,
+    });
+
+    const messages = new Map<string, SpecMessage>();
+    for (const resource of resources) {
+      if (!resource.id) continue;
+      messages.set(resource.id, {
+        name: resource.id,
+        displayName: resource.name !== resource.id ? resource.name : undefined,
+        version: resource.version,
+        summary: resource.summary,
+      });
+    }
+
+    const result: CatalogResolveResult = { messages, errors };
+    setCached(resourceCache, cacheKey, result);
+    return result;
+  } catch (err) {
+    errors.push({
+      message: `Failed to read catalog at "${catalogDir}": ${String(err)}`,
+      line: 1,
+      column: 1,
+    });
+    return { messages: new Map(), errors };
+  }
+}
+
+/**
+ * Scan an EventCatalog directory and return all channels as SpecChannels.
+ * Results are cached for CACHE_TTL_MS to avoid redundant filesystem scans.
+ */
+export async function parseCatalogChannels(
+  catalogDir: string,
+): Promise<CatalogChannelResolveResult> {
+  const cached = getCached(channelCache, catalogDir);
+  if (cached) return cached;
+
+  const errors: ResolveError[] = [];
+
+  const dirError = await validateCatalogDir(catalogDir);
+  if (dirError) return { channels: new Map(), errors: [dirError] };
+
+  try {
+    const sdkFactory = await getSdk();
+    const catalog = sdkFactory(catalogDir);
+    const rawChannels: any[] = await catalog.getChannels({
+      latestOnly: true,
+    });
+
+    const channels = new Map<string, SpecChannel>();
+    for (const ch of rawChannels) {
+      if (!ch.id) continue;
+      channels.set(ch.id, {
+        name: ch.id,
+        displayName: ch.name !== ch.id ? ch.name : undefined,
+        version: ch.version,
+        summary: ch.summary,
+        address: ch.address,
+        protocol: Array.isArray(ch.protocols) ? ch.protocols[0] : undefined,
+      });
+    }
+
+    const result: CatalogChannelResolveResult = { channels, errors };
+    setCached(channelCache, catalogDir, result);
+    return result;
+  } catch (err) {
+    errors.push({
+      message: `Failed to read catalog channels at "${catalogDir}": ${String(err)}`,
+      line: 1,
+      column: 1,
+    });
+    return { channels: new Map(), errors };
+  }
+}
+
+/**
+ * Build a lookup map from message id to its type ("event", "command", or "query")
+ * by scanning all three message collections once. This is much more reliable than
+ * guessing — the SDK scans the correct directories for each type.
+ */
+interface MessageInfo {
+  type: string;
+  summary?: string;
+  version?: string;
+}
+
+async function buildMessageInfoMap(
+  catalog: Record<string, any>,
+): Promise<Map<string, MessageInfo>> {
+  const infoMap = new Map<string, MessageInfo>();
+
+  const safe = (p: Promise<any>) =>
+    p.then((r: any) => (Array.isArray(r) ? r : [])).catch(() => []);
+
+  const [events, commands, queries] = await Promise.all([
+    safe(catalog.getEvents({ latestOnly: true })),
+    safe(catalog.getCommands({ latestOnly: true })),
+    safe(catalog.getQueries({ latestOnly: true })),
+  ]);
+
+  for (const e of events)
+    if (e.id)
+      infoMap.set(e.id, {
+        type: "event",
+        summary: e.summary,
+        version: e.version,
+      });
+  for (const c of commands)
+    if (c.id)
+      infoMap.set(c.id, {
+        type: "command",
+        summary: c.summary,
+        version: c.version,
+      });
+  for (const q of queries)
+    if (q.id)
+      infoMap.set(q.id, {
+        type: "query",
+        summary: q.summary,
+        version: q.version,
+      });
+
+  return infoMap;
+}
+
+/**
+ * Scan an EventCatalog directory and return services as SpecServices.
+ * Each service includes its sends/receives operations so a full service block can be generated.
+ * Results are cached for CACHE_TTL_MS to avoid redundant filesystem scans.
+ */
+export async function parseCatalogServices(
+  catalogDir: string,
+): Promise<CatalogServiceResolveResult> {
+  const cached = getCached(serviceCache, catalogDir);
+  if (cached) return cached;
+
+  const errors: ResolveError[] = [];
+
+  const dirError = await validateCatalogDir(catalogDir);
+  if (dirError) return { services: new Map(), errors: [dirError] };
+
+  try {
+    const sdkFactory = await getSdk();
+    const catalog = sdkFactory(catalogDir);
+
+    // Build an info map once by scanning all message collections
+    const messageInfoMap = await buildMessageInfoMap(catalog);
+
+    const rawServices: any[] = await catalog.getServices({
+      latestOnly: true,
+    });
+
+    const services = new Map<string, SpecService>();
+    for (const svc of rawServices) {
+      if (!svc.id) continue;
+
+      const operations: SpecOperation[] = [];
+      const messages: SpecMessage[] = [];
+
+      // Process sends pointers
+      if (Array.isArray(svc.sends)) {
+        for (const pointer of svc.sends) {
+          const info = messageInfoMap.get(pointer.id);
+          const msgType = info?.type || "event";
+          operations.push({
+            action: "send",
+            channelName: "",
+            messageName: pointer.id,
+            messageType: msgType as "event" | "command" | "query",
+          });
+          messages.push({
+            name: pointer.id,
+            version: pointer.version || info?.version,
+            summary: info?.summary,
+          });
+        }
+      }
+
+      // Process receives pointers
+      if (Array.isArray(svc.receives)) {
+        for (const pointer of svc.receives) {
+          const info = messageInfoMap.get(pointer.id);
+          const msgType = info?.type || "event";
+          operations.push({
+            action: "receive",
+            channelName: "",
+            messageName: pointer.id,
+            messageType: msgType as "event" | "command" | "query",
+          });
+          messages.push({
+            name: pointer.id,
+            version: pointer.version || info?.version,
+            summary: info?.summary,
+          });
+        }
+      }
+
+      services.set(svc.id, {
+        name: svc.id,
+        version: svc.version,
+        summary: svc.summary,
+        operations,
+        channels: [],
+        messages,
+      });
+    }
+
+    const result: CatalogServiceResolveResult = { services, errors };
+    setCached(serviceCache, catalogDir, result);
+    return result;
+  } catch (err) {
+    errors.push({
+      message: `Failed to read catalog services at "${catalogDir}": ${String(err)}`,
+      line: 1,
+      column: 1,
+    });
+    return { services: new Map(), errors };
+  }
+}
diff --git a/packages/language-server/src/resolvers/index.ts b/packages/language-server/src/resolvers/index.ts
new file mode 100644
index 000000000..161cd9f54
--- /dev/null
+++ b/packages/language-server/src/resolvers/index.ts
@@ -0,0 +1,44 @@
+export type {
+  SpecMessage,
+  SpecChannel,
+  SpecOperation,
+  SpecService,
+  ResourceType,
+  ResolveError,
+  SpecResolveResult,
+  FetchFn,
+} from "./types.js";
+export {
+  parseSpec,
+  extractMessages,
+  extractChannels,
+  extractService,
+  messageToEc,
+  channelToEc,
+  serviceToEc,
+  escapeEc,
+} from "./asyncapi.js";
+export {
+  parseOpenApiSpec,
+  extractOpenApiService,
+  openApiServiceToEc,
+  openApiMessageToEc,
+} from "./openapi.js";
+export type { ParsedOpenApiSpec } from "./openapi.js";
+export {
+  resolveSpecImports,
+  resolveSpecImportsAsync,
+  detectSpecType,
+  isSpecFile,
+} from "./resolve.js";
+export {
+  parseCatalogResources,
+  parseCatalogServices,
+  clearCatalogCache,
+} from "./catalog.js";
+export { isCatalogPath } from "./types.js";
+/** @deprecated Use `resolveSpecImports` / `resolveSpecImportsAsync` instead. These aliases now handle both AsyncAPI and OpenAPI specs. */
+export {
+  resolveSpecImports as resolveAsyncApiImports,
+  resolveSpecImportsAsync as resolveAsyncApiImportsAsync,
+} from "./resolve.js";
diff --git a/packages/language-server/src/resolvers/openapi.ts b/packages/language-server/src/resolvers/openapi.ts
new file mode 100644
index 000000000..a107f561a
--- /dev/null
+++ b/packages/language-server/src/resolvers/openapi.ts
@@ -0,0 +1,261 @@
+import yaml from "js-yaml";
+import type {
+  SpecMessage,
+  SpecOperation,
+  SpecService,
+  ResolveError,
+} from "./types.js";
+import {
+  ecBlock,
+  escapeEc,
+  sanitizeServiceName,
+  serviceToEc,
+} from "./asyncapi.js";
+
+export interface ParsedOpenApiSpec {
+  messages: Map<string, SpecMessage & { messageType: "command" | "query" }>;
+  info?: { title?: string; version?: string; description?: string };
+  errors: ResolveError[];
+}
+
+/**
+ * Derive a PascalCase operation name from an HTTP method and path.
+ * e.g. GET /orders/{id}/items -> GetOrdersIdItems
+ */
+export function operationNameFromPath(method: string, path: string): string {
+  const parts = path
+    .split("/")
+    .filter(Boolean)
+    .map((segment) => {
+      // Strip braces from path params
+      const clean = segment.replace(/[{}]/g, "");
+      // PascalCase each segment
+      return clean.charAt(0).toUpperCase() + clean.slice(1);
+    });
+
+  const methodPart =
+    method.charAt(0).toUpperCase() + method.slice(1).toLowerCase();
+  return methodPart + parts.join("");
+}
+
+/**
+ * Parse an OpenAPI v3.0 or v3.1 document and extract operations as messages.
+ */
+export function parseOpenApiSpec(content: string): ParsedOpenApiSpec {
+  let doc: any;
+  try {
+    // Try JSON first for .json files
+    try {
+      doc = JSON.parse(content);
+    } catch {
+      doc = yaml.load(content);
+    }
+  } catch (e) {
+    return {
+      messages: new Map(),
+      errors: [
+        {
+          message: `Failed to parse OpenAPI spec: ${String(e)}`,
+          line: 1,
+          column: 1,
+        },
+      ],
+    };
+  }
+
+  if (!doc || typeof doc !== "object") {
+    return {
+      messages: new Map(),
+      errors: [
+        { message: "OpenAPI file is empty or invalid", line: 1, column: 1 },
+      ],
+    };
+  }
+
+  const openApiVersion = String(doc.openapi || "");
+  if (!openApiVersion.startsWith("3.0") && !openApiVersion.startsWith("3.1")) {
+    return {
+      messages: new Map(),
+      errors: [
+        {
+          message: `Unsupported OpenAPI version: "${openApiVersion}". Only 3.0.x and 3.1.x are supported.`,
+          line: 1,
+          column: 1,
+        },
+      ],
+    };
+  }
+
+  const messages = new Map<
+    string,
+    SpecMessage & { messageType: "command" | "query" }
+  >();
+
+  const paths = doc.paths || {};
+  const specVersion = doc.info?.version;
+
+  for (const [path, pathItem] of Object.entries<any>(paths)) {
+    if (!pathItem || typeof pathItem !== "object") continue;
+
+    for (const method of ["get", "post", "put", "patch", "delete"]) {
+      const op = pathItem[method];
+      if (!op) continue;
+
+      const name = op.operationId || operationNameFromPath(method, path);
+      const overrideType = op["x-eventcatalog-message-type"];
+      const messageType: "command" | "query" =
+        overrideType === "command" || overrideType === "query"
+          ? overrideType
+          : method === "get"
+            ? "query"
+            : "command";
+
+      // Extract response status codes
+      const statusCodes: number[] = op.responses
+        ? Object.keys(op.responses)
+            .map(Number)
+            .filter((c) => !isNaN(c))
+        : [];
+
+      messages.set(name, {
+        name,
+        summary: op.summary,
+        description: op.description,
+        version: specVersion,
+        messageType,
+        method: method.toUpperCase(),
+        path,
+        ...(statusCodes.length > 0 ? { statusCodes } : {}),
+      });
+    }
+  }
+
+  const info = doc.info
+    ? {
+        title: doc.info.title,
+        version: doc.info.version,
+        description: doc.info.description,
+      }
+    : undefined;
+
+  return { messages, info, errors: [] };
+}
+
+/**
+ * Extract a full service definition from an OpenAPI spec.
+ * All operations are "receives" (the service receives HTTP requests).
+ * No channels are generated for OpenAPI specs.
+ */
+export function extractOpenApiService(
+  content: string,
+  serviceName?: string,
+): { service: SpecService; errors: ResolveError[] } {
+  const emptyService = (name: string): SpecService => ({
+    name,
+    operations: [],
+    channels: [],
+    messages: [],
+  });
+
+  const parsed = parseOpenApiSpec(content);
+  if (parsed.errors.length > 0) {
+    return {
+      service: emptyService(serviceName || "UnknownService"),
+      errors: parsed.errors,
+    };
+  }
+
+  const name =
+    serviceName || sanitizeServiceName(parsed.info?.title) || "UnknownService";
+  const version = parsed.info?.version;
+  const summary = parsed.info?.description?.trim().split("\n")[0];
+
+  const operations: SpecOperation[] = [];
+  const messages: SpecMessage[] = [];
+
+  for (const msg of parsed.messages.values()) {
+    operations.push({
+      action: "receive",
+      channelName: "",
+      messageName: msg.name,
+      messageType: msg.messageType,
+      summary: msg.summary,
+    });
+    messages.push({
+      name: msg.name,
+      summary: msg.summary,
+      description: msg.description,
+      version: msg.version,
+      method: msg.method,
+      path: msg.path,
+      statusCodes: msg.statusCodes,
+    });
+  }
+
+  return {
+    service: { name, version, summary, operations, channels: [], messages },
+    errors: [],
+  };
+}
+
+/**
+ * Convert an OpenAPI SpecService to a full .ec definition string.
+ * Generates standalone command/query definitions with summaries,
+ * followed by the service block with receives statements.
+ */
+export function openApiServiceToEc(service: SpecService): string {
+  const parts: string[] = [];
+
+  // Build a map of messageName -> messageType from operations
+  const messageTypeMap = new Map<string, "command" | "query">();
+  for (const op of service.operations) {
+    if (op.messageType === "command" || op.messageType === "query") {
+      messageTypeMap.set(op.messageName, op.messageType);
+    }
+  }
+
+  // Generate standalone message definitions with summaries
+  for (const msg of service.messages) {
+    const msgType = messageTypeMap.get(msg.name) || "command";
+    parts.push(
+      ecBlock(msgType, msg.name, [
+        msg.version && `version ${msg.version}`,
+        msg.summary && `summary "${escapeEc(msg.summary)}"`,
+        apiAnnotation(msg),
+      ]),
+    );
+  }
+
+  // Generate the service block
+  parts.push(serviceToEc(service));
+
+  return parts.join("\n\n");
+}
+
+/**
+ * Build an @api annotation string from method, path, and statusCodes.
+ */
+function apiAnnotation(msg: SpecMessage): string | false {
+  if (!msg.method && !msg.path) return false;
+  const args: string[] = [];
+  if (msg.method) args.push(`method: "${msg.method}"`);
+  if (msg.path) args.push(`path: "${escapeEc(msg.path)}"`);
+  if (msg.statusCodes && msg.statusCodes.length > 0) {
+    args.push(`statusCodes: "${msg.statusCodes.join(",")}"`);
+  }
+  return `@api(${args.join(", ")})`;
+}
+
+/**
+ * Convert an OpenAPI message to an .ec definition string.
+ * Uses the message's messageType to determine whether it's a command or query.
+ */
+export function openApiMessageToEc(
+  msg: SpecMessage & { messageType: "command" | "query" },
+): string {
+  return ecBlock(msg.messageType, msg.name, [
+    msg.version && `version ${msg.version}`,
+    msg.summary && `summary "${escapeEc(msg.summary)}"`,
+    apiAnnotation(msg),
+  ]);
+}
diff --git a/packages/language-server/src/resolvers/resolve.ts b/packages/language-server/src/resolvers/resolve.ts
new file mode 100644
index 000000000..c55c0104c
--- /dev/null
+++ b/packages/language-server/src/resolvers/resolve.ts
@@ -0,0 +1,670 @@
+import yaml from "js-yaml";
+import {
+  isCatalogPath,
+  type SpecMessage,
+  type SpecChannel,
+  type ResourceType,
+  type ResolveError,
+  type SpecResolveResult,
+  type FetchFn,
+} from "./types.js";
+import {
+  parseSpec,
+  extractService,
+  messageToEc,
+  channelToEc,
+  containerToEc,
+  serviceToEc,
+} from "./asyncapi.js";
+import {
+  parseOpenApiSpec,
+  extractOpenApiService,
+  openApiServiceToEc,
+  openApiMessageToEc,
+} from "./openapi.js";
+// Matches: import events { OrderCreated } from "./spec.yml"
+// Matches: import channels { orderEvents } from "./spec.yml"
+// Matches: import events { OrderCreated } from "https://example.com/spec.yml"
+// Also matches .json files for OpenAPI specs
+const SPEC_IMPORT_RE =
+  /^\s*import\s+(events|commands|queries|channels)\s*\{([^}]*)\}\s*from\s*"([^"]+\.(?:ya?ml|json))"\s*(?:\/\/.*)?$/gm;
+
+// Matches: import OrderService from "./spec.yml"
+// A bare identifier (no braces, no resource type keyword) imports a full service
+// Also matches .json files for OpenAPI specs
+const SERVICE_IMPORT_RE =
+  /^\s*import\s+([A-Z][a-zA-Z0-9_]*)\s+from\s*"([^"]+\.(?:ya?ml|json))"\s*(?:\/\/.*)?$/gm;
+
+// Matches: import events { OrderCreated } from "./my-catalog"
+// Matches: import services { OrderService } from "./my-catalog"
+// Matches: import containers { PaymentsDB } from "./my-catalog"
+// Catches any typed import whose path is NOT a spec file and NOT a URL (i.e., a directory path).
+// Uses the same shape as SPEC_IMPORT_RE but with a generic path capture.
+const CATALOG_IMPORT_RE =
+  /^\s*import\s+(events|commands|queries|channels|services|containers)\s*\{([^}]*)\}\s*from\s*"([^"]+)"\s*(?:\/\/.*)?$/gm;
+
+type SpecType = "asyncapi" | "openapi" | "unknown";
+
+/**
+ * Detect whether a spec document is AsyncAPI or OpenAPI based on its content.
+ */
+export function detectSpecType(content: string): SpecType {
+  try {
+    let doc: any;
+    try {
+      doc = JSON.parse(content);
+    } catch {
+      doc = yaml.load(content);
+    }
+    if (!doc || typeof doc !== "object") return "unknown";
+    if (doc.asyncapi) return "asyncapi";
+    if (doc.openapi) return "openapi";
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+interface ImportMatch {
+  full: string;
+  resourceType: ResourceType;
+  importNames: string[];
+  specPath: string;
+}
+
+interface ServiceImportMatch {
+  full: string;
+  serviceName: string;
+  specPath: string;
+}
+
+function findImports(source: string): ImportMatch[] {
+  const imports: ImportMatch[] = [];
+  SPEC_IMPORT_RE.lastIndex = 0;
+  let match;
+  while ((match = SPEC_IMPORT_RE.exec(source)) !== null) {
+    imports.push({
+      full: match[0],
+      resourceType: match[1] as ResourceType,
+      importNames: match[2]
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean),
+      specPath: match[3],
+    });
+  }
+  return imports;
+}
+
+function findServiceImports(source: string): ServiceImportMatch[] {
+  const imports: ServiceImportMatch[] = [];
+  SERVICE_IMPORT_RE.lastIndex = 0;
+  let match;
+  while ((match = SERVICE_IMPORT_RE.exec(source)) !== null) {
+    imports.push({
+      full: match[0],
+      serviceName: match[1],
+      specPath: match[2],
+    });
+  }
+  return imports;
+}
+
+function findCatalogImports(source: string): ImportMatch[] {
+  const imports: ImportMatch[] = [];
+  CATALOG_IMPORT_RE.lastIndex = 0;
+  let match;
+  while ((match = CATALOG_IMPORT_RE.exec(source)) !== null) {
+    const specPath = match[3];
+    // Only keep matches that are catalog paths (not spec files, not URLs)
+    if (!isCatalogPath(specPath)) continue;
+    imports.push({
+      full: match[0],
+      resourceType: match[1] as ResourceType,
+      importNames: match[2]
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean),
+      specPath,
+    });
+  }
+  return imports;
+}
+
+async function resolveCatalogImportToEc(
+  imp: ImportMatch,
+  basePath: string,
+  importingFile?: string,
+): Promise<ImportResolution> {
+  // Dynamic imports to avoid pulling Node.js/SDK deps into browser builds
+  const { resolve, dirname, isAbsolute } = await import("node:path");
+  // Resolve relative paths against the importing file's directory when available,
+  // falling back to basePath for absolute paths or when the file is unknown.
+  let catalogDir: string;
+  if (importingFile && !isAbsolute(imp.specPath)) {
+    const fileDir = resolve(basePath, dirname(importingFile));
+    catalogDir = resolve(fileDir, imp.specPath);
+  } else {
+    catalogDir = resolve(basePath, imp.specPath);
+  }
+
+  // Service imports use a different code path
+  if (imp.resourceType === "services") {
+    const { parseCatalogServices } = await import("./catalog.js");
+    const { services, errors } = await parseCatalogServices(catalogDir);
+
+    const ecDefs = imp.importNames.map((name) => {
+      const svc = services.get(name);
+      if (!svc) {
+        errors.push({
+          message: `Service "${name}" not found in catalog "${imp.specPath}". Available: ${[...services.keys()].join(", ") || "(none)"}`,
+          line: 1,
+          column: 1,
+        });
+        return `// ERROR: Service "${name}" not found in catalog ${imp.specPath}`;
+      }
+      return serviceToEc(svc);
+    });
+
+    return { ec: ecDefs.join("\n\n"), errors };
+  }
+
+  // Channel imports use a dedicated resolver to capture address/protocol
+  if (imp.resourceType === "channels") {
+    const { parseCatalogChannels } = await import("./catalog.js");
+    const { channels, errors } = await parseCatalogChannels(catalogDir);
+
+    const ecDefs = imp.importNames.map((name) => {
+      const ch = channels.get(name);
+      if (!ch) {
+        errors.push({
+          message: `Channel "${name}" not found in catalog "${imp.specPath}". Available: ${[...channels.keys()].join(", ") || "(none)"}`,
+          line: 1,
+          column: 1,
+        });
+        return `// ERROR: Channel "${name}" not found in catalog ${imp.specPath}`;
+      }
+      return channelToEc(ch);
+    });
+
+    return { ec: ecDefs.join("\n\n"), errors };
+  }
+
+  const { parseCatalogResources } = await import("./catalog.js");
+  const { messages, errors } = await parseCatalogResources(
+    catalogDir,
+    imp.resourceType,
+  );
+
+  const ecDefs = imp.importNames.map((name) => {
+    const msg = messages.get(name);
+    if (!msg) {
+      errors.push({
+        message: `"${name}" not found in catalog "${imp.specPath}". Available: ${[...messages.keys()].join(", ") || "(none)"}`,
+        line: 1,
+        column: 1,
+      });
+      return `// ERROR: "${name}" not found in catalog ${imp.specPath}`;
+    }
+    return imp.resourceType === "containers"
+      ? containerToEc(msg)
+      : messageToEc(msg, imp.resourceType);
+  });
+
+  return { ec: ecDefs.join("\n\n"), errors };
+}
+
+interface ImportResolution {
+  ec: string;
+  errors: ResolveError[];
+}
+
+function resolveAsyncApiImportToEc(
+  imp: ImportMatch,
+  specContent: string,
+  cachedParsedSpecs: Map<string, ReturnType<typeof parseSpec>>,
+): ImportResolution {
+  const errors: ResolveError[] = [];
+
+  const cacheKey = normalizeSpecKey(imp.specPath);
+
+  if (!cachedParsedSpecs.has(cacheKey)) {
+    const parsed = parseSpec(specContent);
+    cachedParsedSpecs.set(cacheKey, parsed);
+    errors.push(...parsed.errors);
+  }
+  const parsed = cachedParsedSpecs.get(cacheKey)!;
+
+  const isChannelImport = imp.resourceType === "channels";
+  const catalog = isChannelImport ? parsed.channels : parsed.messages;
+  const typeName = isChannelImport ? "Channel" : "Message";
+
+  const ecDefs = imp.importNames.map((name) => {
+    const resource = catalog.get(name);
+    if (!resource) {
+      errors.push({
+        message: `${typeName} "${name}" not found in AsyncAPI spec "${imp.specPath}". Available: ${[...catalog.keys()].join(", ") || "(none)"}`,
+        line: 1,
+        column: 1,
+      });
+      return `// ERROR: "${name}" not found in ${imp.specPath}`;
+    }
+    return isChannelImport
+      ? channelToEc(resource as SpecChannel)
+      : messageToEc(resource as SpecMessage, imp.resourceType);
+  });
+
+  return { ec: ecDefs.join("\n\n"), errors };
+}
+
+function resolveOpenApiImportToEc(
+  imp: ImportMatch,
+  specContent: string,
+  cachedParsedSpecs: Map<string, ReturnType<typeof parseOpenApiSpec>>,
+): ImportResolution {
+  const errors: ResolveError[] = [];
+
+  // OpenAPI does not support event or channel imports
+  if (imp.resourceType === "events") {
+    errors.push({
+      message: `OpenAPI specs contain commands and queries, not events. Use "import commands" or "import queries" instead for "${imp.specPath}".`,
+      line: 1,
+      column: 1,
+    });
+    return {
+      ec: `// ERROR: OpenAPI specs do not contain events`,
+      errors,
+    };
+  }
+  if (imp.resourceType === "channels") {
+    errors.push({
+      message: `OpenAPI specs do not contain channels for "${imp.specPath}".`,
+      line: 1,
+      column: 1,
+    });
+    return {
+      ec: `// ERROR: OpenAPI specs do not contain channels`,
+      errors,
+    };
+  }
+
+  const cacheKey = normalizeSpecKey(imp.specPath);
+
+  if (!cachedParsedSpecs.has(cacheKey)) {
+    const parsed = parseOpenApiSpec(specContent);
+    cachedParsedSpecs.set(cacheKey, parsed);
+    errors.push(...parsed.errors);
+  }
+  const parsed = cachedParsedSpecs.get(cacheKey)!;
+
+  // Map the import keyword to the expected message type
+  const expectedType: "command" | "query" =
+    imp.resourceType === "commands" ? "command" : "query";
+
+  const ecDefs = imp.importNames.map((name) => {
+    const msg = parsed.messages.get(name);
+    if (!msg) {
+      errors.push({
+        message: `Message "${name}" not found in OpenAPI spec "${imp.specPath}". Available: ${[...parsed.messages.keys()].join(", ") || "(none)"}`,
+        line: 1,
+        column: 1,
+      });
+      return `// ERROR: "${name}" not found in ${imp.specPath}`;
+    }
+    // Enforce that the message type matches the import keyword
+    if (msg.messageType !== expectedType) {
+      errors.push({
+        message: `"${name}" is a ${msg.messageType} but was imported as "${imp.resourceType}" in "${imp.specPath}". Use "import ${msg.messageType === "command" ? "commands" : "queries"} { ${name} }" instead.`,
+        line: 1,
+        column: 1,
+      });
+      return `// ERROR: "${name}" is a ${msg.messageType}, not a ${expectedType}`;
+    }
+    return openApiMessageToEc(msg);
+  });
+
+  return { ec: ecDefs.join("\n\n"), errors };
+}
+
+function resolveServiceImportToEc(
+  imp: ServiceImportMatch,
+  specContent: string,
+  specType: SpecType,
+): ImportResolution {
+  if (specType === "openapi") {
+    const { service, errors } = extractOpenApiService(
+      specContent,
+      imp.serviceName,
+    );
+    return { ec: openApiServiceToEc(service), errors };
+  }
+  // Default to AsyncAPI
+  const { service, errors } = extractService(specContent, imp.serviceName);
+  return { ec: serviceToEc(service), errors };
+}
+
+function isUrl(path: string): boolean {
+  return path.startsWith("https://") || path.startsWith("http://");
+}
+
+function normalizeSpecKey(specPath: string): string {
+  return isUrl(specPath) ? specPath : specPath.replace(/^\.\//, "");
+}
+
+function lookupLocalSpec(
+  specPath: string,
+  files: Record<string, string>,
+  importingFile?: string,
+): string | undefined {
+  // If the importing file is known, resolve the spec path relative to it
+  if (importingFile && !isUrl(specPath)) {
+    const importingDir = importingFile.includes("/")
+      ? importingFile.substring(0, importingFile.lastIndexOf("/"))
+      : "";
+    const resolved = importingDir
+      ? normalizePosixPath(`${importingDir}/${specPath}`)
+      : specPath;
+    const normalizedResolved = resolved.replace(/^\.\//, "");
+    const found =
+      files[resolved] ??
+      files[normalizedResolved] ??
+      files[`./${normalizedResolved}`];
+    if (found) return found;
+  }
+  // Fallback: direct lookup (for root-level files or when importing file is unknown)
+  const normalizedPath = specPath.replace(/^\.\//, "");
+  return (
+    files[specPath] ?? files[normalizedPath] ?? files[`./${normalizedPath}`]
+  );
+}
+
+/**
+ * Normalize a POSIX-style path by resolving `.` and `..` segments.
+ */
+function normalizePosixPath(p: string): string {
+  const parts = p.split("/");
+  const result: string[] = [];
+  for (const part of parts) {
+    if (part === "." || part === "") continue;
+    if (part === "..") {
+      result.pop();
+    } else {
+      result.push(part);
+    }
+  }
+  return result.join("/");
+}
+
+export function isSpecFile(filename: string): boolean {
+  return (
+    filename.endsWith(".yml") ||
+    filename.endsWith(".yaml") ||
+    filename.endsWith(".json")
+  );
+}
+
+const SKIP = Symbol("skip");
+type SpecLookup = (
+  specPath: string,
+  importingFile: string,
+) => string | typeof SKIP | undefined;
+
+/**
+ * Core resolution logic shared by sync and async resolvers.
+ * Given a spec content lookup function, resolves all imports in .ec files.
+ * Auto-detects whether each spec is AsyncAPI or OpenAPI.
+ * Return `SKIP` from the callback to leave an import untouched;
+ * return `undefined` to replace it with an error comment.
+ */
+function resolveFileImports(
+  files: Record<string, string>,
+  getSpecContent: SpecLookup,
+): SpecResolveResult {
+  const errors: ResolveError[] = [];
+  const newFiles: Record<string, string> = {};
+  const cachedAsyncApiSpecs = new Map<string, ReturnType<typeof parseSpec>>();
+  const cachedOpenApiSpecs = new Map<
+    string,
+    ReturnType<typeof parseOpenApiSpec>
+  >();
+  const specTypeCache = new Map<string, SpecType>();
+
+  function getSpecType(specPath: string, content: string): SpecType {
+    const cacheKey = normalizeSpecKey(specPath);
+    if (!specTypeCache.has(cacheKey)) {
+      specTypeCache.set(cacheKey, detectSpecType(content));
+    }
+    return specTypeCache.get(cacheKey)!;
+  }
+
+  for (const [filename, source] of Object.entries(files)) {
+    if (isSpecFile(filename)) continue;
+
+    const imports = findImports(source);
+    const serviceImports = findServiceImports(source);
+
+    if (imports.length === 0 && serviceImports.length === 0) {
+      newFiles[filename] = source;
+      continue;
+    }
+
+    let result = source;
+
+    // Resolve resource imports (import events { ... } from "spec.yml")
+    for (const imp of imports) {
+      const specContent = getSpecContent(imp.specPath, filename);
+      if (specContent === SKIP) continue;
+      if (!specContent) {
+        result = result.replace(
+          imp.full,
+          `// ERROR: Spec file not available: ${imp.specPath}`,
+        );
+        continue;
+      }
+
+      const specType = getSpecType(imp.specPath, specContent);
+
+      let resolution: ImportResolution;
+      if (specType === "openapi") {
+        resolution = resolveOpenApiImportToEc(
+          imp,
+          specContent,
+          cachedOpenApiSpecs,
+        );
+      } else {
+        resolution = resolveAsyncApiImportToEc(
+          imp,
+          specContent,
+          cachedAsyncApiSpecs,
+        );
+      }
+      errors.push(...resolution.errors);
+      result = result.replace(imp.full, resolution.ec);
+    }
+
+    // Resolve service imports (import ServiceName from "spec.yml")
+    for (const imp of serviceImports) {
+      const specContent = getSpecContent(imp.specPath, filename);
+      if (specContent === SKIP) continue;
+      if (!specContent) {
+        result = result.replace(
+          imp.full,
+          `// ERROR: Spec file not available: ${imp.specPath}`,
+        );
+        continue;
+      }
+
+      const specType = getSpecType(imp.specPath, specContent);
+      const resolution = resolveServiceImportToEc(imp, specContent, specType);
+      errors.push(...resolution.errors);
+      result = result.replace(imp.full, resolution.ec);
+    }
+
+    newFiles[filename] = result;
+  }
+
+  return { files: newFiles, errors };
+}
+
+/**
+ * Resolve all spec imports in a set of files (sync, local files only).
+ * Scans .ec files for `import <type> { ... } from "*.yml"` and
+ * `import ServiceName from "*.yml"` statements, auto-detects whether
+ * each spec is AsyncAPI or OpenAPI, and replaces the imports with
+ * synthesized .ec definitions.
+ * Spec files (YAML/JSON) are excluded from the output.
+ * URL imports are left untouched - use resolveSpecImportsAsync for those.
+ */
+export function resolveSpecImports(
+  files: Record<string, string>,
+): SpecResolveResult {
+  const notFoundErrors: ResolveError[] = [];
+
+  const result = resolveFileImports(files, (specPath, importingFile) => {
+    if (isUrl(specPath)) return SKIP;
+    const content = lookupLocalSpec(specPath, files, importingFile);
+    if (!content) {
+      notFoundErrors.push({
+        message: `Spec file not found: "${specPath}"`,
+        line: 1,
+        column: 1,
+      });
+    }
+    return content;
+  });
+
+  return {
+    files: result.files,
+    errors: [...notFoundErrors, ...result.errors],
+  };
+}
+
+/**
+ * Resolve all spec imports including remote URLs (async).
+ * Fetches remote specs via the provided fetchFn, then resolves all imports.
+ * Auto-detects AsyncAPI vs OpenAPI from file content.
+ * For local file imports, looks them up in the files map.
+ * When basePath is provided, also resolves catalog directory imports
+ * (e.g., `import events { OrderCreated } from "./my-catalog"`).
+ */
+export async function resolveSpecImportsAsync(
+  files: Record<string, string>,
+  fetchFn: FetchFn,
+  basePath?: string,
+): Promise<SpecResolveResult> {
+  // Collect all unique remote URLs that need fetching
+  const urlsToFetch = new Set<string>();
+  for (const [filename, source] of Object.entries(files)) {
+    if (isSpecFile(filename)) continue;
+    for (const imp of findImports(source)) {
+      if (isUrl(imp.specPath)) urlsToFetch.add(imp.specPath);
+    }
+    for (const imp of findServiceImports(source)) {
+      if (isUrl(imp.specPath)) urlsToFetch.add(imp.specPath);
+    }
+  }
+
+  // Fetch all remote specs in parallel
+  const fetchErrors: ResolveError[] = [];
+  const fetchedSpecs = new Map<string, string>();
+  await Promise.all(
+    [...urlsToFetch].map(async (url) => {
+      try {
+        fetchedSpecs.set(url, await fetchFn(url));
+      } catch (err) {
+        fetchErrors.push({
+          message: `Failed to fetch spec "${url}": ${String(err)}`,
+          line: 1,
+          column: 1,
+        });
+      }
+    }),
+  );
+
+  const notFoundErrors: ResolveError[] = [];
+
+  const result = resolveFileImports(files, (specPath, importingFile) => {
+    if (isUrl(specPath)) return fetchedSpecs.get(specPath);
+    const content = lookupLocalSpec(specPath, files, importingFile);
+    if (!content) {
+      notFoundErrors.push({
+        message: `Spec file not found: "${specPath}"`,
+        line: 1,
+        column: 1,
+      });
+    }
+    return content;
+  });
+
+  // Resolve catalog directory imports (import events { ... } from "./my-catalog")
+  // Only when basePath is provided (Node.js/VSCode context, not browser)
+  if (basePath) {
+    const catalogErrors: ResolveError[] = [];
+
+    // Collect files that have catalog imports so we can resolve them in parallel.
+    // The TTL cache in catalog.ts ensures that multiple imports pointing at
+    // the same catalog directory only trigger one SDK scan.
+    const filesToResolve: { filename: string; imports: ImportMatch[] }[] = [];
+    for (const [filename, source] of Object.entries(result.files)) {
+      const catalogImports = findCatalogImports(source);
+      if (catalogImports.length > 0) {
+        filesToResolve.push({ filename, imports: catalogImports });
+      }
+    }
+
+    // Resolve all files and their imports in parallel.
+    // Imports within a file are also resolved concurrently since they may
+    // point at different catalog directories.
+    const catalogResolutions = new Map<string, string>();
+    await Promise.all(
+      filesToResolve.map(async ({ filename, imports }) => {
+        const resolutions = await Promise.all(
+          imports.map(async (imp) => {
+            try {
+              return await resolveCatalogImportToEc(imp, basePath, filename);
+            } catch (err) {
+              return {
+                ec: `// ERROR: Failed to resolve catalog "${imp.specPath}": ${String(err)}`,
+                errors: [
+                  {
+                    message: `Failed to resolve catalog "${imp.specPath}": ${String(err)}`,
+                    line: 1,
+                    column: 1,
+                  },
+                ],
+              } as ImportResolution;
+            }
+          }),
+        );
+        let resolved = result.files[filename];
+        for (let i = 0; i < imports.length; i++) {
+          catalogErrors.push(...resolutions[i].errors);
+          resolved = resolved.replace(imports[i].full, resolutions[i].ec);
+        }
+        catalogResolutions.set(filename, resolved);
+      }),
+    );
+
+    // Build output preserving the original file order from result.files
+    const resolvedFiles: Record<string, string> = {};
+    for (const filename of Object.keys(result.files)) {
+      resolvedFiles[filename] =
+        catalogResolutions.get(filename) ?? result.files[filename];
+    }
+
+    return {
+      files: resolvedFiles,
+      errors: [
+        ...fetchErrors,
+        ...notFoundErrors,
+        ...result.errors,
+        ...catalogErrors,
+      ],
+    };
+  }
+
+  return {
+    files: result.files,
+    errors: [...fetchErrors, ...notFoundErrors, ...result.errors],
+  };
+}
diff --git a/packages/language-server/src/resolvers/types.ts b/packages/language-server/src/resolvers/types.ts
new file mode 100644
index 000000000..49639eb04
--- /dev/null
+++ b/packages/language-server/src/resolvers/types.ts
@@ -0,0 +1,77 @@
+export type ResourceType =
+  | "events"
+  | "commands"
+  | "queries"
+  | "channels"
+  | "services"
+  | "containers";
+
+export interface SpecMessage {
+  name: string;
+  /** Human-readable display name (from catalog `name` field) */
+  displayName?: string;
+  summary?: string;
+  description?: string;
+  version?: string;
+  /** HTTP method (from OpenAPI) */
+  method?: string;
+  /** API path (from OpenAPI) */
+  path?: string;
+  /** HTTP status codes (from OpenAPI) */
+  statusCodes?: number[];
+}
+
+export interface SpecChannel {
+  name: string;
+  /** Human-readable display name (from catalog `name` field) */
+  displayName?: string;
+  address?: string;
+  protocol?: string;
+  summary?: string;
+  version?: string;
+}
+
+export interface SpecOperation {
+  action: "send" | "receive";
+  channelName: string;
+  messageName: string;
+  messageType?: "event" | "command" | "query";
+  summary?: string;
+}
+
+export interface SpecService {
+  name: string;
+  version?: string;
+  summary?: string;
+  operations: SpecOperation[];
+  channels: SpecChannel[];
+  messages: SpecMessage[];
+}
+
+export interface ResolveError {
+  message: string;
+  line: number;
+  column: number;
+}
+
+export interface SpecResolveResult {
+  files: Record<string, string>;
+  errors: ResolveError[];
+}
+
+/**
+ * A fetch function that takes a URL and returns the response text.
+ * Allows callers to provide their own fetch implementation (browser fetch, node-fetch, etc.)
+ */
+export type FetchFn = (url: string) => Promise<string>;
+
+/**
+ * Check whether a path looks like a catalog directory (not a spec file, not a URL).
+ * Browser-safe — no Node.js dependencies.
+ */
+export function isCatalogPath(specPath: string): boolean {
+  if (specPath.startsWith("http://") || specPath.startsWith("https://"))
+    return false;
+  if (/\.(?:ya?ml|json)$/i.test(specPath)) return false;
+  return true;
+}
diff --git a/packages/language-server/syntaxes/ec.tmLanguage.json b/packages/language-server/syntaxes/ec.tmLanguage.json
new file mode 100644
index 000000000..2486ab47d
--- /dev/null
+++ b/packages/language-server/syntaxes/ec.tmLanguage.json
@@ -0,0 +1,59 @@
+{
+  "name": "ec",
+  "scopeName": "source.ec",
+  "fileTypes": [".ec"],
+  "patterns": [
+    {
+      "include": "#comments"
+    },
+    {
+      "name": "keyword.control.ec",
+      "match": "\\b(access-mode|actor|address|and|animated|appendOnly|authoritative|avatar|cache|channel|channels|classification|color|command|commands|confidential|container|container-type|containers|contract|data-product|dataLake|dataWarehouse|database|default|delivery|deprecated|description|diagram|domain|draft|email|enum|event|events|examples|external-system|externalSaaS|false|flow|focus-mode|from|hidden|icon|import|input|internal|label|legend|member|message|ms-teams|name|objectStore|other|output|owner|parameter|path|post-it|protocol|public|pull|push|push-pull|queries|query|read|readWrite|reads-from|receives|regulated|residency|retention|role|route|schema|search|searchIndex|sends|service|services|slack|style|subdomain|summary|team|technology|title|to|toolbar|true|type|url|user|version|visible|visualizer|when|write|writes-to)\\b"
+    },
+    {
+      "name": "string.quoted.double.ec",
+      "begin": "\"",
+      "end": "\"",
+      "patterns": [
+        {
+          "include": "#string-character-escape"
+        }
+      ]
+    }
+  ],
+  "repository": {
+    "comments": {
+      "patterns": [
+        {
+          "begin": "//",
+          "beginCaptures": {
+            "1": {
+              "name": "punctuation.whitespace.comment.leading.ec"
+            }
+          },
+          "end": "(?=$)",
+          "name": "comment.line.ec"
+        },
+        {
+          "name": "comment.block.ec",
+          "begin": "/\\*",
+          "beginCaptures": {
+            "0": {
+              "name": "punctuation.definition.comment.ec"
+            }
+          },
+          "end": "\\*/",
+          "endCaptures": {
+            "0": {
+              "name": "punctuation.definition.comment.ec"
+            }
+          }
+        }
+      ]
+    },
+    "string-character-escape": {
+      "name": "constant.character.escape.ec",
+      "match": "\\\\(x[0-9A-Fa-f]{2}|u[0-9A-Fa-f]{4}|u\\{[0-9A-Fa-f]+\\}|[0-2][0-7]{0,2}|3[0-6][0-7]?|37[0-7]?|[4-7][0-7]?|.|$)"
+    }
+  }
+}
diff --git a/packages/language-server/test/__snapshots__/examples-snapshot.test.ts.snap b/packages/language-server/test/__snapshots__/examples-snapshot.test.ts.snap
new file mode 100644
index 000000000..30a1d5650
--- /dev/null
+++ b/packages/language-server/test/__snapshots__/examples-snapshot.test.ts.snap
@@ -0,0 +1,8529 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`playground examples snapshot tests > AWS Event Pipeline > AWS Event Pipeline - edges 1`] = `
+[
+  {
+    "id": "domain:Orders@1.0.0-contains-service:OrderService@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-channel:OrderEventBus@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "channel:OrderEventBus@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0-routes-to-channel:OrderEventBus@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated@1.0.0",
+    "target": "channel:OrderEventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderShipped@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderShipped@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderShipped@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderShipped@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderShipped@1.0.0-routes-to-channel:OrderEventBus@1.0.0",
+    "label": undefined,
+    "source": "event:OrderShipped@1.0.0",
+    "target": "channel:OrderEventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderCancelled@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderCancelled@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCancelled@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCancelled@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderCancelled@1.0.0-routes-to-channel:OrderEventBus@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCancelled@1.0.0",
+    "target": "channel:OrderEventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:MainEventBus-routes-to-channel:FulfillmentEventBus@1.0.0",
+    "label": undefined,
+    "source": "channel:MainEventBus",
+    "target": "channel:FulfillmentEventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:MainEventBus-routes-to-channel:NotificationsEventBus@1.0.0",
+    "label": undefined,
+    "source": "channel:MainEventBus",
+    "target": "channel:NotificationsEventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:MainEventBus-routes-to-channel:AnalyticsEventBus@1.0.0",
+    "label": undefined,
+    "source": "channel:MainEventBus",
+    "target": "channel:AnalyticsEventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:OrderEventBus@1.0.0-routes-to-channel:MainEventBus",
+    "label": undefined,
+    "source": "channel:OrderEventBus@1.0.0",
+    "target": "channel:MainEventBus",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-service:WarehouseService@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "service:WarehouseService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-channel:PickingQueue@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "channel:PickingQueue@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:PickingQueue@1.0.0-receives-service:WarehouseService@1.0.0",
+    "label": undefined,
+    "source": "channel:PickingQueue@1.0.0",
+    "target": "service:WarehouseService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-event:OrderCancelled@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "event:OrderCancelled@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-service:ShippingService@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "service:ShippingService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-channel:ShippingQueue@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "channel:ShippingQueue@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:ShippingQueue@1.0.0-receives-service:ShippingService@1.0.0",
+    "label": undefined,
+    "source": "channel:ShippingQueue@1.0.0",
+    "target": "service:ShippingService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-channel:FulfillmentEventBus@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "channel:FulfillmentEventBus@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:FulfillmentEventBus@1.0.0-routes-to-channel:PickingQueue@1.0.0",
+    "label": undefined,
+    "source": "channel:FulfillmentEventBus@1.0.0",
+    "target": "channel:PickingQueue@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:FulfillmentEventBus@1.0.0-routes-to-channel:ShippingQueue@1.0.0",
+    "label": undefined,
+    "source": "channel:FulfillmentEventBus@1.0.0",
+    "target": "channel:ShippingQueue@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-service:EmailService@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "service:EmailService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-channel:EmailQueue@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "channel:EmailQueue@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:EmailQueue@1.0.0-receives-service:EmailService@1.0.0",
+    "label": undefined,
+    "source": "channel:EmailQueue@1.0.0",
+    "target": "service:EmailService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-event:OrderShipped@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "event:OrderShipped@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-event:OrderCancelled@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "event:OrderCancelled@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-service:PushNotificationService@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "service:PushNotificationService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-channel:PushQueue@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "channel:PushQueue@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:PushQueue@1.0.0-receives-service:PushNotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:PushQueue@1.0.0",
+    "target": "service:PushNotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-service:SmsService@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "service:SmsService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-channel:SmsQueue@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "channel:SmsQueue@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:SmsQueue@1.0.0-receives-service:SmsService@1.0.0",
+    "label": undefined,
+    "source": "channel:SmsQueue@1.0.0",
+    "target": "service:SmsService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-channel:NotificationsEventBus@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "channel:NotificationsEventBus@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:NotificationsEventBus@1.0.0-routes-to-channel:EmailQueue@1.0.0",
+    "label": undefined,
+    "source": "channel:NotificationsEventBus@1.0.0",
+    "target": "channel:EmailQueue@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:NotificationsEventBus@1.0.0-routes-to-channel:PushQueue@1.0.0",
+    "label": undefined,
+    "source": "channel:NotificationsEventBus@1.0.0",
+    "target": "channel:PushQueue@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:NotificationsEventBus@1.0.0-routes-to-channel:SmsQueue@1.0.0",
+    "label": undefined,
+    "source": "channel:NotificationsEventBus@1.0.0",
+    "target": "channel:SmsQueue@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-service:MetricsService@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "service:MetricsService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-channel:MetricsQueue@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "channel:MetricsQueue@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:MetricsQueue@1.0.0-receives-service:MetricsService@1.0.0",
+    "label": undefined,
+    "source": "channel:MetricsQueue@1.0.0",
+    "target": "service:MetricsService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-event:OrderShipped@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "event:OrderShipped@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-event:OrderCancelled@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "event:OrderCancelled@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-service:SearchService@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "service:SearchService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-channel:SearchIndexQueue@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "channel:SearchIndexQueue@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:SearchIndexQueue@1.0.0-receives-service:SearchService@1.0.0",
+    "label": undefined,
+    "source": "channel:SearchIndexQueue@1.0.0",
+    "target": "service:SearchService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-channel:AnalyticsEventBus@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "channel:AnalyticsEventBus@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:AnalyticsEventBus@1.0.0-routes-to-channel:MetricsQueue@1.0.0",
+    "label": undefined,
+    "source": "channel:AnalyticsEventBus@1.0.0",
+    "target": "channel:MetricsQueue@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:AnalyticsEventBus@1.0.0-routes-to-channel:SearchIndexQueue@1.0.0",
+    "label": undefined,
+    "source": "channel:AnalyticsEventBus@1.0.0",
+    "target": "channel:SearchIndexQueue@1.0.0",
+    "type": "routes-to",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > AWS Event Pipeline > AWS Event Pipeline - nodes 1`] = `
+[
+  {
+    "id": "domain:Orders@1.0.0",
+    "label": "Orders",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Order management domain",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:OrderService@1.0.0",
+    "label": "OrderService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Handles order creation and lifecycle",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0",
+    "label": "OrderCreated",
+    "metadata": {
+      "summary": "Emitted when a customer places an order",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "channel:OrderEventBus@1.0.0",
+    "label": "OrderEventBus",
+    "metadata": {
+      "address": "arn:aws:events:us-east-1:123456789:event-bus/orders",
+      "protocols": [
+        "EventBridge",
+      ],
+      "summary": "Event bus for the orders domain",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "event:OrderShipped@1.0.0",
+    "label": "OrderShipped",
+    "metadata": {
+      "summary": "Emitted when an order is shipped",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:OrderCancelled@1.0.0",
+    "label": "OrderCancelled",
+    "metadata": {
+      "summary": "Emitted when an order is cancelled",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "channel:MainEventBus",
+    "label": "MainEventBus",
+    "metadata": {
+      "address": "arn:aws:events:us-east-1:123456789:event-bus/main",
+      "protocols": [
+        "EventBridge",
+      ],
+      "summary": "Central company-wide event bus",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "channel:FulfillmentEventBus@1.0.0",
+    "label": "FulfillmentEventBus",
+    "metadata": {
+      "address": "arn:aws:events:us-east-1:123456789:event-bus/fulfillment",
+      "protocols": [
+        "EventBridge",
+      ],
+      "summary": "Event bus for the fulfillment domain",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "channel:NotificationsEventBus@1.0.0",
+    "label": "NotificationsEventBus",
+    "metadata": {
+      "address": "arn:aws:events:us-east-1:123456789:event-bus/notifications",
+      "protocols": [
+        "EventBridge",
+      ],
+      "summary": "Event bus for the notifications domain",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Notifications@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "channel:AnalyticsEventBus@1.0.0",
+    "label": "AnalyticsEventBus",
+    "metadata": {
+      "address": "arn:aws:events:us-east-1:123456789:event-bus/analytics",
+      "protocols": [
+        "EventBridge",
+      ],
+      "summary": "Event bus for the analytics domain",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Analytics@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0",
+    "label": "Fulfillment",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Warehouse and shipping operations",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:WarehouseService@1.0.0",
+    "label": "WarehouseService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages warehouse picking and packing",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "channel:PickingQueue@1.0.0",
+    "label": "PickingQueue",
+    "metadata": {
+      "address": "arn:aws:sqs:us-east-1:123456789:warehouse-picking",
+      "protocols": [
+        "SQS",
+      ],
+      "summary": "Queue for warehouse pick-list generation",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "service:ShippingService@1.0.0",
+    "label": "ShippingService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Handles carrier selection and label generation",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "channel:ShippingQueue@1.0.0",
+    "label": "ShippingQueue",
+    "metadata": {
+      "address": "arn:aws:sqs:us-east-1:123456789:shipping-labels",
+      "protocols": [
+        "SQS",
+      ],
+      "summary": "Queue for shipping label creation",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "domain:Notifications@1.0.0",
+    "label": "Notifications",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Customer communication channels",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:EmailService@1.0.0",
+    "label": "EmailService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends transactional emails to customers",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Notifications@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "channel:EmailQueue@1.0.0",
+    "label": "EmailQueue",
+    "metadata": {
+      "address": "arn:aws:sqs:us-east-1:123456789:email-delivery",
+      "protocols": [
+        "SQS",
+      ],
+      "summary": "Queue for transactional email delivery",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Notifications@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "service:PushNotificationService@1.0.0",
+    "label": "PushNotificationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends mobile push notifications",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Notifications@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "channel:PushQueue@1.0.0",
+    "label": "PushQueue",
+    "metadata": {
+      "address": "arn:aws:sqs:us-east-1:123456789:push-notifications",
+      "protocols": [
+        "SQS",
+      ],
+      "summary": "Queue for mobile push notifications",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Notifications@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "service:SmsService@1.0.0",
+    "label": "SmsService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends SMS order updates",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Notifications@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "channel:SmsQueue@1.0.0",
+    "label": "SmsQueue",
+    "metadata": {
+      "address": "arn:aws:sqs:us-east-1:123456789:sms-notifications",
+      "protocols": [
+        "SQS",
+      ],
+      "summary": "Queue for SMS notifications",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Notifications@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "domain:Analytics@1.0.0",
+    "label": "Analytics",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Business intelligence and search",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:MetricsService@1.0.0",
+    "label": "MetricsService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Tracks order metrics and business KPIs",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Analytics@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "channel:MetricsQueue@1.0.0",
+    "label": "MetricsQueue",
+    "metadata": {
+      "address": "arn:aws:sqs:us-east-1:123456789:metrics-ingestion",
+      "protocols": [
+        "SQS",
+      ],
+      "summary": "Queue for metrics and KPI ingestion",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Analytics@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "service:SearchService@1.0.0",
+    "label": "SearchService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Maintains product and order search indexes",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Analytics@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "channel:SearchIndexQueue@1.0.0",
+    "label": "SearchIndexQueue",
+    "metadata": {
+      "address": "arn:aws:sqs:us-east-1:123456789:search-indexing",
+      "protocols": [
+        "SQS",
+      ],
+      "summary": "Queue for search index updates",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Analytics@1.0.0",
+    "type": "channel",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > AsyncAPI Import > AsyncAPI Import - edges 1`] = `
+[
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCreated",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCreated",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderCreated-routes-to-channel:orderCreated",
+    "label": undefined,
+    "source": "event:OrderCreated",
+    "target": "channel:orderCreated",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderShipped",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderShipped",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderShipped-routes-to-channel:orderShipped",
+    "label": undefined,
+    "source": "event:OrderShipped",
+    "target": "channel:orderShipped",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCancelled",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCancelled",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderCancelled-routes-to-channel:orderCancelled",
+    "label": undefined,
+    "source": "event:OrderCancelled",
+    "target": "channel:orderCancelled",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:ShippingService@1.0.0-sends-event:OrderShipped",
+    "label": undefined,
+    "source": "service:ShippingService@1.0.0",
+    "target": "event:OrderShipped",
+    "type": "sends",
+  },
+  {
+    "id": "channel:orderCreated-receives-service:ShippingService@1.0.0",
+    "label": undefined,
+    "source": "channel:orderCreated",
+    "target": "service:ShippingService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "channel:orderShipped-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:orderShipped",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "channel:orderCancelled-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:orderCancelled",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > AsyncAPI Import > AsyncAPI Import - nodes 1`] = `
+[
+  {
+    "id": "service:OrderService@1.0.0",
+    "label": "OrderService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages order lifecycle",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:OrderCreated",
+    "label": "OrderCreated",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "channel:orderCreated",
+    "label": "orderCreated",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "event:OrderShipped",
+    "label": "OrderShipped",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "channel:orderShipped",
+    "label": "orderShipped",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "event:OrderCancelled",
+    "label": "OrderCancelled",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "channel:orderCancelled",
+    "label": "orderCancelled",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "service:ShippingService@1.0.0",
+    "label": "ShippingService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Handles shipping and delivery",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:NotificationService@1.0.0",
+    "label": "NotificationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends customer notifications",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > AsyncAPI Multi-Service > AsyncAPI Multi-Service - edges 1`] = `[]`;
+
+exports[`playground examples snapshot tests > AsyncAPI Multi-Service > AsyncAPI Multi-Service - nodes 1`] = `
+[
+  {
+    "id": "service:OrderService",
+    "label": "OrderService",
+    "metadata": {
+      "version": undefined,
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:ShippingService",
+    "label": "ShippingService",
+    "metadata": {
+      "version": undefined,
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:NotificationService",
+    "label": "NotificationService",
+    "metadata": {
+      "version": undefined,
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > AsyncAPI Remote Import > AsyncAPI Remote Import - edges 1`] = `
+[
+  {
+    "id": "service:StreetlightsAPI@1.0.0-sends-event:lightMeasured",
+    "label": undefined,
+    "source": "service:StreetlightsAPI@1.0.0",
+    "target": "event:lightMeasured",
+    "type": "sends",
+  },
+  {
+    "id": "event:lightMeasured-routes-to-channel:lightingMeasured",
+    "label": undefined,
+    "source": "event:lightMeasured",
+    "target": "channel:lightingMeasured",
+    "type": "routes-to",
+  },
+  {
+    "id": "event:turnOnOff-routes-to-channel:lightTurnOn",
+    "label": undefined,
+    "source": "event:turnOnOff",
+    "target": "channel:lightTurnOn",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:lightTurnOn-receives-service:StreetlightsAPI@1.0.0",
+    "label": undefined,
+    "source": "channel:lightTurnOn",
+    "target": "service:StreetlightsAPI@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "event:dimLight-routes-to-channel:lightsDim",
+    "label": undefined,
+    "source": "event:dimLight",
+    "target": "channel:lightsDim",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:lightsDim-receives-service:StreetlightsAPI@1.0.0",
+    "label": undefined,
+    "source": "channel:lightsDim",
+    "target": "service:StreetlightsAPI@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "channel:lightingMeasured-receives-service:LightingDashboard@1.0.0",
+    "label": undefined,
+    "source": "channel:lightingMeasured",
+    "target": "service:LightingDashboard@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:LightController@1.0.0-sends-event:turnOnOff",
+    "label": undefined,
+    "source": "service:LightController@1.0.0",
+    "target": "event:turnOnOff",
+    "type": "sends",
+  },
+  {
+    "id": "service:LightController@1.0.0-sends-event:dimLight",
+    "label": undefined,
+    "source": "service:LightController@1.0.0",
+    "target": "event:dimLight",
+    "type": "sends",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > AsyncAPI Remote Import > AsyncAPI Remote Import - nodes 1`] = `
+[
+  {
+    "id": "service:StreetlightsAPI@1.0.0",
+    "label": "StreetlightsAPI",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Controls city streetlight infrastructure",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:lightMeasured",
+    "label": "lightMeasured",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "channel:lightingMeasured",
+    "label": "lightingMeasured",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "event:turnOnOff",
+    "label": "turnOnOff",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "channel:lightTurnOn",
+    "label": "lightTurnOn",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "event:dimLight",
+    "label": "dimLight",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "channel:lightsDim",
+    "label": "lightsDim",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "service:LightingDashboard@1.0.0",
+    "label": "LightingDashboard",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Monitoring dashboard for streetlights",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:LightController@1.0.0",
+    "label": "LightController",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Automated light control system",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > AsyncAPI Service Import > AsyncAPI Service Import - edges 1`] = `
+[
+  {
+    "id": "event:OrderCreated-routes-to-channel:orderCreated",
+    "label": undefined,
+    "source": "event:OrderCreated",
+    "target": "channel:orderCreated",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:orderCreated-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:orderCreated",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "event:OrderShipped-routes-to-channel:orderShipped",
+    "label": undefined,
+    "source": "event:OrderShipped",
+    "target": "channel:orderShipped",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:orderShipped-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:orderShipped",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > AsyncAPI Service Import > AsyncAPI Service Import - nodes 1`] = `
+[
+  {
+    "id": "service:OrderService",
+    "label": "OrderService",
+    "metadata": {
+      "version": undefined,
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:NotificationService@1.0.0",
+    "label": "NotificationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends customer notifications",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:OrderCreated",
+    "label": "OrderCreated",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "channel:orderCreated",
+    "label": "orderCreated",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "event:OrderShipped",
+    "label": "OrderShipped",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "channel:orderShipped",
+    "label": "orderShipped",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "channel",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Banking with Subdomains > Banking with Subdomains - edges 1`] = `
+[
+  {
+    "id": "domain:Banking@1.0.0-contains-domain:Accounts@1.0.0",
+    "label": undefined,
+    "source": "domain:Banking@1.0.0",
+    "target": "domain:Accounts@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Accounts@1.0.0-contains-service:AccountService@1.0.0",
+    "label": undefined,
+    "source": "domain:Accounts@1.0.0",
+    "target": "service:AccountService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Accounts@1.0.0-contains-event:AccountOpened@1.0.0",
+    "label": undefined,
+    "source": "domain:Accounts@1.0.0",
+    "target": "event:AccountOpened@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:AccountService@1.0.0-sends-event:AccountOpened@1.0.0",
+    "label": undefined,
+    "source": "service:AccountService@1.0.0",
+    "target": "event:AccountOpened@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Accounts@1.0.0-contains-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "domain:Accounts@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:AccountOpened@1.0.0-routes-to-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "event:AccountOpened@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Accounts@1.0.0-contains-event:AccountClosed@1.0.0",
+    "label": undefined,
+    "source": "domain:Accounts@1.0.0",
+    "target": "event:AccountClosed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:AccountService@1.0.0-sends-event:AccountClosed@1.0.0",
+    "label": undefined,
+    "source": "service:AccountService@1.0.0",
+    "target": "event:AccountClosed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:AccountClosed@1.0.0-routes-to-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "event:AccountClosed@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Accounts@1.0.0-contains-event:BalanceUpdated@1.0.0",
+    "label": undefined,
+    "source": "domain:Accounts@1.0.0",
+    "target": "event:BalanceUpdated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:AccountService@1.0.0-sends-event:BalanceUpdated@1.0.0",
+    "label": undefined,
+    "source": "service:AccountService@1.0.0",
+    "target": "event:BalanceUpdated@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:BalanceUpdated@1.0.0-routes-to-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "event:BalanceUpdated@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Accounts@1.0.0-contains-command:OpenAccount@1.0.0",
+    "label": undefined,
+    "source": "domain:Accounts@1.0.0",
+    "target": "command:OpenAccount@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Accounts@1.0.0-contains-channel:BankingCommands@1.0.0",
+    "label": undefined,
+    "source": "domain:Accounts@1.0.0",
+    "target": "channel:BankingCommands@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:OpenAccount@1.0.0-routes-to-channel:BankingCommands@1.0.0",
+    "label": undefined,
+    "source": "command:OpenAccount@1.0.0",
+    "target": "channel:BankingCommands@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:BankingCommands@1.0.0-receives-service:AccountService@1.0.0",
+    "label": "accepts",
+    "source": "channel:BankingCommands@1.0.0",
+    "target": "service:AccountService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Accounts@1.0.0-contains-command:CloseAccount@1.0.0",
+    "label": undefined,
+    "source": "domain:Accounts@1.0.0",
+    "target": "command:CloseAccount@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:CloseAccount@1.0.0-routes-to-channel:BankingCommands@1.0.0",
+    "label": undefined,
+    "source": "command:CloseAccount@1.0.0",
+    "target": "channel:BankingCommands@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Accounts@1.0.0-contains-event:TransactionCompleted@1.0.0",
+    "label": undefined,
+    "source": "domain:Accounts@1.0.0",
+    "target": "event:TransactionCompleted@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:TransactionCompleted@1.0.0-routes-to-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "event:TransactionCompleted@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:BankingEvents@1.0.0-receives-service:AccountService@1.0.0",
+    "label": undefined,
+    "source": "channel:BankingEvents@1.0.0",
+    "target": "service:AccountService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Accounts@1.0.0-contains-event:LoanDisbursed@1.0.0",
+    "label": undefined,
+    "source": "domain:Accounts@1.0.0",
+    "target": "event:LoanDisbursed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:LoanDisbursed@1.0.0-routes-to-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "event:LoanDisbursed@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:AccountService@1.0.0-reads-writes-container:AccountsDB",
+    "label": undefined,
+    "source": "service:AccountService@1.0.0",
+    "target": "container:AccountsDB",
+    "type": "reads-writes",
+  },
+  {
+    "id": "domain:Banking@1.0.0-contains-domain:Payments@1.0.0",
+    "label": undefined,
+    "source": "domain:Banking@1.0.0",
+    "target": "domain:Payments@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payments@1.0.0-contains-service:PaymentService@1.0.0",
+    "label": undefined,
+    "source": "domain:Payments@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payments@1.0.0-contains-event:PaymentInitiated@1.0.0",
+    "label": undefined,
+    "source": "domain:Payments@1.0.0",
+    "target": "event:PaymentInitiated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentInitiated@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentInitiated@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Payments@1.0.0-contains-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "domain:Payments@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:PaymentInitiated@1.0.0-routes-to-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentInitiated@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Payments@1.0.0-contains-event:TransactionCompleted@1.0.0",
+    "label": undefined,
+    "source": "domain:Payments@1.0.0",
+    "target": "event:TransactionCompleted@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:TransactionCompleted@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:TransactionCompleted@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Payments@1.0.0-contains-event:TransactionFailed@1.0.0",
+    "label": undefined,
+    "source": "domain:Payments@1.0.0",
+    "target": "event:TransactionFailed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:TransactionFailed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:TransactionFailed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:TransactionFailed@1.0.0-routes-to-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "event:TransactionFailed@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Payments@1.0.0-contains-command:ProcessPayment@1.0.0",
+    "label": undefined,
+    "source": "domain:Payments@1.0.0",
+    "target": "command:ProcessPayment@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payments@1.0.0-contains-channel:BankingCommands@1.0.0",
+    "label": undefined,
+    "source": "domain:Payments@1.0.0",
+    "target": "channel:BankingCommands@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:ProcessPayment@1.0.0-routes-to-channel:BankingCommands@1.0.0",
+    "label": undefined,
+    "source": "command:ProcessPayment@1.0.0",
+    "target": "channel:BankingCommands@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:BankingCommands@1.0.0-receives-service:PaymentService@1.0.0",
+    "label": "accepts",
+    "source": "channel:BankingCommands@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Payments@1.0.0-contains-command:TransferFunds@1.0.0",
+    "label": undefined,
+    "source": "domain:Payments@1.0.0",
+    "target": "command:TransferFunds@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:TransferFunds@1.0.0-routes-to-channel:BankingCommands@1.0.0",
+    "label": undefined,
+    "source": "command:TransferFunds@1.0.0",
+    "target": "channel:BankingCommands@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Payments@1.0.0-contains-event:AccountOpened@1.0.0",
+    "label": undefined,
+    "source": "domain:Payments@1.0.0",
+    "target": "event:AccountOpened@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:BankingEvents@1.0.0-receives-service:PaymentService@1.0.0",
+    "label": undefined,
+    "source": "channel:BankingEvents@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-reads-writes-container:PaymentsDB",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "container:PaymentsDB",
+    "type": "reads-writes",
+  },
+  {
+    "id": "domain:Banking@1.0.0-contains-domain:Loans@1.0.0",
+    "label": undefined,
+    "source": "domain:Banking@1.0.0",
+    "target": "domain:Loans@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Loans@1.0.0-contains-service:LoanService@1.0.0",
+    "label": undefined,
+    "source": "domain:Loans@1.0.0",
+    "target": "service:LoanService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Loans@1.0.0-contains-event:LoanApplicationSubmitted@1.0.0",
+    "label": undefined,
+    "source": "domain:Loans@1.0.0",
+    "target": "event:LoanApplicationSubmitted@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:LoanService@1.0.0-sends-event:LoanApplicationSubmitted@1.0.0",
+    "label": undefined,
+    "source": "service:LoanService@1.0.0",
+    "target": "event:LoanApplicationSubmitted@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Loans@1.0.0-contains-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "domain:Loans@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:LoanApplicationSubmitted@1.0.0-routes-to-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "event:LoanApplicationSubmitted@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Loans@1.0.0-contains-event:LoanApproved@1.0.0",
+    "label": undefined,
+    "source": "domain:Loans@1.0.0",
+    "target": "event:LoanApproved@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:LoanService@1.0.0-sends-event:LoanApproved@1.0.0",
+    "label": undefined,
+    "source": "service:LoanService@1.0.0",
+    "target": "event:LoanApproved@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:LoanApproved@1.0.0-routes-to-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "event:LoanApproved@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Loans@1.0.0-contains-event:LoanRejected@1.0.0",
+    "label": undefined,
+    "source": "domain:Loans@1.0.0",
+    "target": "event:LoanRejected@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:LoanService@1.0.0-sends-event:LoanRejected@1.0.0",
+    "label": undefined,
+    "source": "service:LoanService@1.0.0",
+    "target": "event:LoanRejected@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:LoanRejected@1.0.0-routes-to-channel:BankingEvents@1.0.0",
+    "label": undefined,
+    "source": "event:LoanRejected@1.0.0",
+    "target": "channel:BankingEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Loans@1.0.0-contains-event:LoanDisbursed@1.0.0",
+    "label": undefined,
+    "source": "domain:Loans@1.0.0",
+    "target": "event:LoanDisbursed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:LoanService@1.0.0-sends-event:LoanDisbursed@1.0.0",
+    "label": undefined,
+    "source": "service:LoanService@1.0.0",
+    "target": "event:LoanDisbursed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Loans@1.0.0-contains-command:ApplyForLoan@1.0.0",
+    "label": undefined,
+    "source": "domain:Loans@1.0.0",
+    "target": "command:ApplyForLoan@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Loans@1.0.0-contains-channel:BankingCommands@1.0.0",
+    "label": undefined,
+    "source": "domain:Loans@1.0.0",
+    "target": "channel:BankingCommands@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:ApplyForLoan@1.0.0-routes-to-channel:BankingCommands@1.0.0",
+    "label": undefined,
+    "source": "command:ApplyForLoan@1.0.0",
+    "target": "channel:BankingCommands@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:BankingCommands@1.0.0-receives-service:LoanService@1.0.0",
+    "label": "accepts",
+    "source": "channel:BankingCommands@1.0.0",
+    "target": "service:LoanService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Loans@1.0.0-contains-command:ApproveLoan@1.0.0",
+    "label": undefined,
+    "source": "domain:Loans@1.0.0",
+    "target": "command:ApproveLoan@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:ApproveLoan@1.0.0-routes-to-channel:BankingCommands@1.0.0",
+    "label": undefined,
+    "source": "command:ApproveLoan@1.0.0",
+    "target": "channel:BankingCommands@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Loans@1.0.0-contains-event:AccountOpened@1.0.0",
+    "label": undefined,
+    "source": "domain:Loans@1.0.0",
+    "target": "event:AccountOpened@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:BankingEvents@1.0.0-receives-service:LoanService@1.0.0",
+    "label": undefined,
+    "source": "channel:BankingEvents@1.0.0",
+    "target": "service:LoanService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Loans@1.0.0-contains-event:BalanceUpdated@1.0.0",
+    "label": undefined,
+    "source": "domain:Loans@1.0.0",
+    "target": "event:BalanceUpdated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:LoanService@1.0.0-reads-writes-container:LoansDB",
+    "label": undefined,
+    "source": "service:LoanService@1.0.0",
+    "target": "container:LoansDB",
+    "type": "reads-writes",
+  },
+  {
+    "id": "service:NotificationService@1.0.0-sends-event:EmailSent@1.0.0",
+    "label": undefined,
+    "source": "service:NotificationService@1.0.0",
+    "target": "event:EmailSent@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "service:NotificationService@1.0.0-sends-event:SMSSent@1.0.0",
+    "label": undefined,
+    "source": "service:NotificationService@1.0.0",
+    "target": "event:SMSSent@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "channel:BankingEvents@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:BankingEvents@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:FraudDetectionService@1.0.0-sends-event:FraudAlertRaised@1.0.0",
+    "label": undefined,
+    "source": "service:FraudDetectionService@1.0.0",
+    "target": "event:FraudAlertRaised@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "channel:BankingEvents@1.0.0-receives-service:FraudDetectionService@1.0.0",
+    "label": undefined,
+    "source": "channel:BankingEvents@1.0.0",
+    "target": "service:FraudDetectionService@1.0.0",
+    "type": "receives",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Banking with Subdomains > Banking with Subdomains - nodes 1`] = `
+[
+  {
+    "id": "channel:BankingEvents@1.0.0",
+    "label": "BankingEvents",
+    "metadata": {
+      "address": "banking.events",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "kafka",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Accounts@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "channel:BankingCommands@1.0.0",
+    "label": "BankingCommands",
+    "metadata": {
+      "address": "/api/v1",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "http",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Accounts@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "domain:Banking@1.0.0",
+    "label": "Banking",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Core banking domain with customer accounts, payments, and loans",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "domain:Accounts@1.0.0",
+    "label": "Accounts",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Customer account management and transactions",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Banking@1.0.0",
+    "type": "domain",
+  },
+  {
+    "id": "service:AccountService@1.0.0",
+    "label": "AccountService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages customer accounts and balances",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Accounts@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:AccountOpened@1.0.0",
+    "label": "AccountOpened",
+    "metadata": {
+      "summary": "New customer account created",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Accounts@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:AccountClosed@1.0.0",
+    "label": "AccountClosed",
+    "metadata": {
+      "summary": "Customer account closed",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Accounts@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:BalanceUpdated@1.0.0",
+    "label": "BalanceUpdated",
+    "metadata": {
+      "summary": "Account balance changed",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Accounts@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "command:OpenAccount@1.0.0",
+    "label": "OpenAccount",
+    "metadata": {
+      "summary": "Open a new customer account",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Accounts@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "command:CloseAccount@1.0.0",
+    "label": "CloseAccount",
+    "metadata": {
+      "summary": "Close an existing account",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Accounts@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "event:TransactionCompleted@1.0.0",
+    "label": "TransactionCompleted",
+    "metadata": {
+      "summary": "Payment successfully completed",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Accounts@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:LoanDisbursed@1.0.0",
+    "label": "LoanDisbursed",
+    "metadata": {
+      "summary": "Loan funds disbursed to account",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Accounts@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "container:AccountsDB",
+    "label": "AccountsDB",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "container",
+  },
+  {
+    "id": "domain:Payments@1.0.0",
+    "label": "Payments",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Payment processing and transfers",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Banking@1.0.0",
+    "type": "domain",
+  },
+  {
+    "id": "service:PaymentService@1.0.0",
+    "label": "PaymentService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Processes payments and transfers between accounts",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payments@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:PaymentInitiated@1.0.0",
+    "label": "PaymentInitiated",
+    "metadata": {
+      "summary": "Payment process started",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payments@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:TransactionFailed@1.0.0",
+    "label": "TransactionFailed",
+    "metadata": {
+      "summary": "Payment failed",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payments@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "command:ProcessPayment@1.0.0",
+    "label": "ProcessPayment",
+    "metadata": {
+      "summary": "Process a payment transaction",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payments@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "command:TransferFunds@1.0.0",
+    "label": "TransferFunds",
+    "metadata": {
+      "summary": "Transfer funds between accounts",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payments@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "container:PaymentsDB",
+    "label": "PaymentsDB",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "container",
+  },
+  {
+    "id": "domain:Loans@1.0.0",
+    "label": "Loans",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Loan origination and management",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Banking@1.0.0",
+    "type": "domain",
+  },
+  {
+    "id": "service:LoanService@1.0.0",
+    "label": "LoanService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages loan applications and disbursements",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Loans@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:LoanApplicationSubmitted@1.0.0",
+    "label": "LoanApplicationSubmitted",
+    "metadata": {
+      "summary": "Customer submitted loan application",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Loans@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:LoanApproved@1.0.0",
+    "label": "LoanApproved",
+    "metadata": {
+      "summary": "Loan application approved",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Loans@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:LoanRejected@1.0.0",
+    "label": "LoanRejected",
+    "metadata": {
+      "summary": "Loan application rejected",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Loans@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "command:ApplyForLoan@1.0.0",
+    "label": "ApplyForLoan",
+    "metadata": {
+      "summary": "Submit a new loan application",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Loans@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "command:ApproveLoan@1.0.0",
+    "label": "ApproveLoan",
+    "metadata": {
+      "summary": "Approve a loan application",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Loans@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "container:LoansDB",
+    "label": "LoansDB",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "container",
+  },
+  {
+    "id": "service:NotificationService@1.0.0",
+    "label": "NotificationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends notifications to customers",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:EmailSent@1.0.0",
+    "label": "EmailSent",
+    "metadata": {
+      "summary": "Email notification sent to customer",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:SMSSent@1.0.0",
+    "label": "SMSSent",
+    "metadata": {
+      "summary": "SMS notification sent to customer",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:FraudDetectionService@1.0.0",
+    "label": "FraudDetectionService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Monitors transactions for fraudulent activity",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:FraudAlertRaised@1.0.0",
+    "label": "FraudAlertRaised",
+    "metadata": {
+      "summary": "Suspicious activity detected",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Channel Routing > Channel Routing - edges 1`] = `
+[
+  {
+    "id": "channel:SensorIngestion@1.0.0-routes-to-channel:SensorFiltered@1.0.0",
+    "label": undefined,
+    "source": "channel:SensorIngestion@1.0.0",
+    "target": "channel:SensorFiltered@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:SensorFiltered@1.0.0-routes-to-channel:DeviceCommands@1.0.0",
+    "label": undefined,
+    "source": "channel:SensorFiltered@1.0.0",
+    "target": "channel:DeviceCommands@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:SensorGateway@1.0.0-sends-event:SensorReading@1.0.0",
+    "label": undefined,
+    "source": "service:SensorGateway@1.0.0",
+    "target": "event:SensorReading@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:SensorReading@1.0.0-routes-to-channel:SensorIngestion@1.0.0",
+    "label": undefined,
+    "source": "event:SensorReading@1.0.0",
+    "target": "channel:SensorIngestion@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:SensorGateway@1.0.0-sends-event:DeviceHeartbeat@1.0.0",
+    "label": undefined,
+    "source": "service:SensorGateway@1.0.0",
+    "target": "event:DeviceHeartbeat@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:DeviceHeartbeat@1.0.0-routes-to-channel:SensorIngestion@1.0.0",
+    "label": undefined,
+    "source": "event:DeviceHeartbeat@1.0.0",
+    "target": "channel:SensorIngestion@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:FilterService@1.0.0-sends-event:SensorReading@1.0.0",
+    "label": undefined,
+    "source": "service:FilterService@1.0.0",
+    "target": "event:SensorReading@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "service:FilterService@1.0.0-sends-event:DeviceAlert@1.0.0",
+    "label": undefined,
+    "source": "service:FilterService@1.0.0",
+    "target": "event:DeviceAlert@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:DeviceAlert@1.0.0-routes-to-channel:SensorFiltered@1.0.0",
+    "label": undefined,
+    "source": "event:DeviceAlert@1.0.0",
+    "target": "channel:SensorFiltered@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:SensorIngestion@1.0.0-receives-service:FilterService@1.0.0",
+    "label": undefined,
+    "source": "channel:SensorIngestion@1.0.0",
+    "target": "service:FilterService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:DeviceBridge@1.0.0-sends-command:RecalibrateDevice@1.0.0",
+    "label": undefined,
+    "source": "service:DeviceBridge@1.0.0",
+    "target": "command:RecalibrateDevice@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "command:RecalibrateDevice@1.0.0-routes-to-channel:DeviceCommands@1.0.0",
+    "label": undefined,
+    "source": "command:RecalibrateDevice@1.0.0",
+    "target": "channel:DeviceCommands@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:SensorFiltered@1.0.0-receives-service:DeviceBridge@1.0.0",
+    "label": undefined,
+    "source": "channel:SensorFiltered@1.0.0",
+    "target": "service:DeviceBridge@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "channel:SensorFiltered@1.0.0-receives-service:DashboardService@1.0.0",
+    "label": undefined,
+    "source": "channel:SensorFiltered@1.0.0",
+    "target": "service:DashboardService@1.0.0",
+    "type": "receives",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Channel Routing > Channel Routing - nodes 1`] = `
+[
+  {
+    "id": "channel:SensorIngestion@1.0.0",
+    "label": "SensorIngestion",
+    "metadata": {
+      "address": "sensors.raw",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "Kafka",
+      ],
+      "summary": "Raw sensor data ingestion topic",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "channel:SensorFiltered@1.0.0",
+    "label": "SensorFiltered",
+    "metadata": {
+      "address": "sensors.filtered",
+      "protocols": [
+        "Kafka",
+      ],
+      "summary": "Filtered and validated sensor data",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "channel:DeviceCommands@1.0.0",
+    "label": "DeviceCommands",
+    "metadata": {
+      "address": "devices/+/commands",
+      "protocols": [
+        "MQTT",
+      ],
+      "summary": "MQTT topic for device command delivery",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "service:SensorGateway@1.0.0",
+    "label": "SensorGateway",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Ingests raw sensor readings from IoT devices",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:SensorReading@1.0.0",
+    "label": "SensorReading",
+    "metadata": {
+      "summary": "Raw sensor reading from a device",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:DeviceHeartbeat@1.0.0",
+    "label": "DeviceHeartbeat",
+    "metadata": {
+      "summary": "Periodic device health check",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:FilterService@1.0.0",
+    "label": "FilterService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Validates and filters raw sensor data",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:DeviceAlert@1.0.0",
+    "label": "DeviceAlert",
+    "metadata": {
+      "summary": "Alert when device readings are anomalous",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:DeviceBridge@1.0.0",
+    "label": "DeviceBridge",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Bridges Kafka events to MQTT for device delivery",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "command:RecalibrateDevice@1.0.0",
+    "label": "RecalibrateDevice",
+    "metadata": {
+      "summary": "Instructs a device to recalibrate its sensors",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "service:DashboardService@1.0.0",
+    "label": "DashboardService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Real-time monitoring dashboard",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Data Products > Data Products - edges 1`] = `
+[
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0-routes-to-channel:EventBus@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated@1.0.0",
+    "target": "channel:EventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCompleted@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCompleted@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderCompleted@1.0.0-routes-to-channel:EventBus@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCompleted@1.0.0",
+    "target": "channel:EventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-routes-to-channel:EventBus@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "channel:EventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0-sends-data-product:OrderAnalytics@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated@1.0.0",
+    "target": "data-product:OrderAnalytics@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderCompleted@1.0.0-sends-data-product:OrderAnalytics@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCompleted@1.0.0",
+    "target": "data-product:OrderAnalytics@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-sends-data-product:OrderAnalytics@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "data-product:OrderAnalytics@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "data-product:OrderAnalytics@1.0.0-sends-event:OrderMetrics",
+    "label": undefined,
+    "source": "data-product:OrderAnalytics@1.0.0",
+    "target": "event:OrderMetrics",
+    "type": "sends",
+  },
+  {
+    "id": "data-product:OrderAnalytics@1.0.0-sends-event:CustomerInsights",
+    "label": undefined,
+    "source": "data-product:OrderAnalytics@1.0.0",
+    "target": "event:CustomerInsights",
+    "type": "sends",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-sends-data-product:RevenueReporting@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "data-product:RevenueReporting@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "data-product:RevenueReporting@1.0.0-sends-event:DailyRevenue",
+    "label": undefined,
+    "source": "data-product:RevenueReporting@1.0.0",
+    "target": "event:DailyRevenue",
+    "type": "sends",
+  },
+  {
+    "id": "data-product:RevenueReporting@1.0.0-sends-event:MonthlyRevenue",
+    "label": undefined,
+    "source": "data-product:RevenueReporting@1.0.0",
+    "target": "event:MonthlyRevenue",
+    "type": "sends",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Data Products > Data Products - nodes 1`] = `
+[
+  {
+    "id": "channel:EventBus@1.0.0",
+    "label": "EventBus",
+    "metadata": {
+      "address": "analytics.events",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "kafka",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "service:OrderService@1.0.0",
+    "label": "OrderService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages order lifecycle",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0",
+    "label": "OrderCreated",
+    "metadata": {
+      "summary": "New order has been placed",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:OrderCompleted@1.0.0",
+    "label": "OrderCompleted",
+    "metadata": {
+      "summary": "Order has been fulfilled",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:PaymentService@1.0.0",
+    "label": "PaymentService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Handles payment processing",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0",
+    "label": "PaymentProcessed",
+    "metadata": {
+      "summary": "Payment completed successfully",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "data-product:OrderAnalytics@1.0.0",
+    "label": "Order Analytics Dataset",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Aggregated order and payment data for business intelligence",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "data-product",
+  },
+  {
+    "id": "event:OrderMetrics",
+    "label": "OrderMetrics",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:CustomerInsights",
+    "label": "CustomerInsights",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "data-product:RevenueReporting@1.0.0",
+    "label": "RevenueReporting",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Revenue analysis and reporting",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "data-product",
+  },
+  {
+    "id": "event:DailyRevenue",
+    "label": "DailyRevenue",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:MonthlyRevenue",
+    "label": "MonthlyRevenue",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > E-Commerce Platform > E-Commerce Platform - edges 1`] = `
+[
+  {
+    "id": "domain:Orders@1.0.0-contains-service:OrderService@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-channel:OrderEvents@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "channel:OrderEvents@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0-routes-to-channel:OrderEvents@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated@1.0.0",
+    "target": "channel:OrderEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderUpdated@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderUpdated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderUpdated@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderUpdated@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderUpdated@1.0.0-routes-to-channel:OrderEvents@1.0.0",
+    "label": undefined,
+    "source": "event:OrderUpdated@1.0.0",
+    "target": "channel:OrderEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-command:ProcessPayment@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "command:ProcessPayment@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-command:ProcessPayment@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "command:ProcessPayment@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-channel:CommandAPI@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "channel:CommandAPI@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:ProcessPayment@1.0.0-routes-to-channel:CommandAPI@1.0.0",
+    "label": undefined,
+    "source": "command:ProcessPayment@1.0.0",
+    "target": "channel:CommandAPI@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-routes-to-channel:OrderEvents@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "channel:OrderEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:OrderEvents@1.0.0-receives-service:OrderService@1.0.0",
+    "label": undefined,
+    "source": "channel:OrderEvents@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:InventoryReserved@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:InventoryReserved@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:InventoryReserved@1.0.0-receives-service:OrderService@1.0.0",
+    "label": undefined,
+    "source": "event:InventoryReserved@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-service:PaymentService@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-channel:OrderEvents@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "channel:OrderEvents@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-event:PaymentFailed@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "event:PaymentFailed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentFailed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentFailed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:PaymentFailed@1.0.0-routes-to-channel:OrderEvents@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentFailed@1.0.0",
+    "target": "channel:OrderEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-command:ProcessPayment@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "command:ProcessPayment@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-channel:CommandAPI@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "channel:CommandAPI@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:CommandAPI@1.0.0-receives-service:PaymentService@1.0.0",
+    "label": "accepts",
+    "source": "channel:CommandAPI@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:InventoryService@1.0.0-sends-event:InventoryReserved@1.0.0",
+    "label": undefined,
+    "source": "service:InventoryService@1.0.0",
+    "target": "event:InventoryReserved@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "service:InventoryService@1.0.0-sends-event:InventoryReleased@1.0.0",
+    "label": undefined,
+    "source": "service:InventoryService@1.0.0",
+    "target": "event:InventoryReleased@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "channel:OrderEvents@1.0.0-receives-service:InventoryService@1.0.0",
+    "label": undefined,
+    "source": "channel:OrderEvents@1.0.0",
+    "target": "service:InventoryService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "channel:OrderEvents@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:OrderEvents@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > E-Commerce Platform > E-Commerce Platform - nodes 1`] = `
+[
+  {
+    "id": "channel:OrderEvents@1.0.0",
+    "label": "OrderEvents",
+    "metadata": {
+      "address": "orders.events",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "kafka",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "channel:CommandAPI@1.0.0",
+    "label": "CommandAPI",
+    "metadata": {
+      "address": "/api/v1",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "http",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "domain:Orders@1.0.0",
+    "label": "Orders",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Everything related to order management",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:OrderService@1.0.0",
+    "label": "OrderService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages order lifecycle",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0",
+    "label": "OrderCreated",
+    "metadata": {
+      "summary": "New order has been placed",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:OrderUpdated@1.0.0",
+    "label": "OrderUpdated",
+    "metadata": {
+      "summary": "Order details have changed",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "command:ProcessPayment@1.0.0",
+    "label": "ProcessPayment",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0",
+    "label": "PaymentProcessed",
+    "metadata": {
+      "summary": "Payment completed successfully",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:InventoryReserved@1.0.0",
+    "label": "InventoryReserved",
+    "metadata": {
+      "summary": "Inventory reserved for order",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "domain:Payment@1.0.0",
+    "label": "Payment",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Payment processing domain",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:PaymentService@1.0.0",
+    "label": "PaymentService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Handles payment transactions",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:PaymentFailed@1.0.0",
+    "label": "PaymentFailed",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "service:InventoryService@1.0.0",
+    "label": "InventoryService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages product inventory",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:InventoryReleased@1.0.0",
+    "label": "InventoryReleased",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:NotificationService@1.0.0",
+    "label": "NotificationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends email and push notifications",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Enterprise E-Commerce > Enterprise E-Commerce - edges 1`] = `
+[
+  {
+    "id": "domain:Orders@1.0.0-contains-service:OrderService@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderShipped@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderShipped@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderShipped@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderShipped@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderCancelled@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderCancelled@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCancelled@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCancelled@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-command:ProcessPayment@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "command:ProcessPayment@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-command:ProcessPayment@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "command:ProcessPayment@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-command:ReserveStock@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "command:ReserveStock@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-command:ReserveStock@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "command:ReserveStock@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-receives-service:OrderService@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:PaymentFailed@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:PaymentFailed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:PaymentFailed@1.0.0-receives-service:OrderService@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentFailed@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:StockReserved@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:StockReserved@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:StockReserved@1.0.0-receives-service:OrderService@1.0.0",
+    "label": undefined,
+    "source": "event:StockReserved@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-command:CancelOrder@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "command:CancelOrder@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:CancelOrder@1.0.0-receives-service:OrderService@1.0.0",
+    "label": "accepts",
+    "source": "command:CancelOrder@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:OrderService@1.0.0-reads-writes-container:OrdersDB@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "container:OrdersDB@1.0.0",
+    "type": "reads-writes",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-container:OrdersDB@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "container:OrdersDB@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-service:PaymentService@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-event:PaymentFailed@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "event:PaymentFailed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentFailed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentFailed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-command:ProcessPayment@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "command:ProcessPayment@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:ProcessPayment@1.0.0-receives-service:PaymentService@1.0.0",
+    "label": "accepts",
+    "source": "command:ProcessPayment@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-command:RefundPayment@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "command:RefundPayment@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:RefundPayment@1.0.0-receives-service:PaymentService@1.0.0",
+    "label": "accepts",
+    "source": "command:RefundPayment@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-writes-to-container:PaymentDB@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "container:PaymentDB@1.0.0",
+    "type": "writes-to",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-reads-writes-container:PaymentCache@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "container:PaymentCache@1.0.0",
+    "type": "reads-writes",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-container:PaymentDB@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "container:PaymentDB@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-container:PaymentCache@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "container:PaymentCache@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Inventory@1.0.0-contains-service:InventoryService@1.0.0",
+    "label": undefined,
+    "source": "domain:Inventory@1.0.0",
+    "target": "service:InventoryService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Inventory@1.0.0-contains-event:StockReserved@1.0.0",
+    "label": undefined,
+    "source": "domain:Inventory@1.0.0",
+    "target": "event:StockReserved@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:InventoryService@1.0.0-sends-event:StockReserved@1.0.0",
+    "label": undefined,
+    "source": "service:InventoryService@1.0.0",
+    "target": "event:StockReserved@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Inventory@1.0.0-contains-event:StockReleased@1.0.0",
+    "label": undefined,
+    "source": "domain:Inventory@1.0.0",
+    "target": "event:StockReleased@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:InventoryService@1.0.0-sends-event:StockReleased@1.0.0",
+    "label": undefined,
+    "source": "service:InventoryService@1.0.0",
+    "target": "event:StockReleased@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Inventory@1.0.0-contains-event:LowStockAlert@1.0.0",
+    "label": undefined,
+    "source": "domain:Inventory@1.0.0",
+    "target": "event:LowStockAlert@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:InventoryService@1.0.0-sends-event:LowStockAlert@1.0.0",
+    "label": undefined,
+    "source": "service:InventoryService@1.0.0",
+    "target": "event:LowStockAlert@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Inventory@1.0.0-contains-command:ReserveStock@1.0.0",
+    "label": undefined,
+    "source": "domain:Inventory@1.0.0",
+    "target": "command:ReserveStock@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:ReserveStock@1.0.0-receives-service:InventoryService@1.0.0",
+    "label": "accepts",
+    "source": "command:ReserveStock@1.0.0",
+    "target": "service:InventoryService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Inventory@1.0.0-contains-command:ReleaseStock@1.0.0",
+    "label": undefined,
+    "source": "domain:Inventory@1.0.0",
+    "target": "command:ReleaseStock@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:ReleaseStock@1.0.0-receives-service:InventoryService@1.0.0",
+    "label": "accepts",
+    "source": "command:ReleaseStock@1.0.0",
+    "target": "service:InventoryService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Inventory@1.0.0-contains-event:OrderCancelled@1.0.0",
+    "label": undefined,
+    "source": "domain:Inventory@1.0.0",
+    "target": "event:OrderCancelled@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderCancelled@1.0.0-receives-service:InventoryService@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCancelled@1.0.0",
+    "target": "service:InventoryService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:InventoryService@1.0.0-reads-writes-container:InventoryDB@1.0.0",
+    "label": undefined,
+    "source": "service:InventoryService@1.0.0",
+    "target": "container:InventoryDB@1.0.0",
+    "type": "reads-writes",
+  },
+  {
+    "id": "domain:Inventory@1.0.0-contains-container:InventoryDB@1.0.0",
+    "label": undefined,
+    "source": "domain:Inventory@1.0.0",
+    "target": "container:InventoryDB@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Shipping@1.0.0-contains-service:ShippingService@1.0.0",
+    "label": undefined,
+    "source": "domain:Shipping@1.0.0",
+    "target": "service:ShippingService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Shipping@1.0.0-contains-event:ShipmentCreated@1.0.0",
+    "label": undefined,
+    "source": "domain:Shipping@1.0.0",
+    "target": "event:ShipmentCreated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:ShippingService@1.0.0-sends-event:ShipmentCreated@1.0.0",
+    "label": undefined,
+    "source": "service:ShippingService@1.0.0",
+    "target": "event:ShipmentCreated@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Shipping@1.0.0-contains-event:ShipmentDelivered@1.0.0",
+    "label": undefined,
+    "source": "domain:Shipping@1.0.0",
+    "target": "event:ShipmentDelivered@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:ShippingService@1.0.0-sends-event:ShipmentDelivered@1.0.0",
+    "label": undefined,
+    "source": "service:ShippingService@1.0.0",
+    "target": "event:ShipmentDelivered@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Shipping@1.0.0-contains-event:OrderShipped@1.0.0",
+    "label": undefined,
+    "source": "domain:Shipping@1.0.0",
+    "target": "event:OrderShipped@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderShipped@1.0.0-receives-service:ShippingService@1.0.0",
+    "label": undefined,
+    "source": "event:OrderShipped@1.0.0",
+    "target": "service:ShippingService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Shipping@1.0.0-contains-query:GetShipmentStatus@1.0.0",
+    "label": undefined,
+    "source": "domain:Shipping@1.0.0",
+    "target": "query:GetShipmentStatus@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "query:GetShipmentStatus@1.0.0-receives-service:ShippingService@1.0.0",
+    "label": "accepts",
+    "source": "query:GetShipmentStatus@1.0.0",
+    "target": "service:ShippingService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:ShippingService@1.0.0-reads-writes-container:ShippingDB@1.0.0",
+    "label": undefined,
+    "source": "service:ShippingService@1.0.0",
+    "target": "container:ShippingDB@1.0.0",
+    "type": "reads-writes",
+  },
+  {
+    "id": "domain:Shipping@1.0.0-contains-container:ShippingDB@1.0.0",
+    "label": undefined,
+    "source": "domain:Shipping@1.0.0",
+    "target": "container:ShippingDB@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Customer@1.0.0-contains-service:CustomerService@1.0.0",
+    "label": undefined,
+    "source": "domain:Customer@1.0.0",
+    "target": "service:CustomerService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Customer@1.0.0-contains-event:CustomerRegistered@1.0.0",
+    "label": undefined,
+    "source": "domain:Customer@1.0.0",
+    "target": "event:CustomerRegistered@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:CustomerService@1.0.0-sends-event:CustomerRegistered@1.0.0",
+    "label": undefined,
+    "source": "service:CustomerService@1.0.0",
+    "target": "event:CustomerRegistered@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Customer@1.0.0-contains-event:CustomerUpdated@1.0.0",
+    "label": undefined,
+    "source": "domain:Customer@1.0.0",
+    "target": "event:CustomerUpdated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:CustomerService@1.0.0-sends-event:CustomerUpdated@1.0.0",
+    "label": undefined,
+    "source": "service:CustomerService@1.0.0",
+    "target": "event:CustomerUpdated@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Customer@1.0.0-contains-command:RegisterCustomer@1.0.0",
+    "label": undefined,
+    "source": "domain:Customer@1.0.0",
+    "target": "command:RegisterCustomer@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:RegisterCustomer@1.0.0-receives-service:CustomerService@1.0.0",
+    "label": "accepts",
+    "source": "command:RegisterCustomer@1.0.0",
+    "target": "service:CustomerService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Customer@1.0.0-contains-command:UpdateCustomer@1.0.0",
+    "label": undefined,
+    "source": "domain:Customer@1.0.0",
+    "target": "command:UpdateCustomer@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:UpdateCustomer@1.0.0-receives-service:CustomerService@1.0.0",
+    "label": "accepts",
+    "source": "command:UpdateCustomer@1.0.0",
+    "target": "service:CustomerService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Customer@1.0.0-contains-query:GetCustomerProfile@1.0.0",
+    "label": undefined,
+    "source": "domain:Customer@1.0.0",
+    "target": "query:GetCustomerProfile@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "query:GetCustomerProfile@1.0.0-receives-service:CustomerService@1.0.0",
+    "label": "accepts",
+    "source": "query:GetCustomerProfile@1.0.0",
+    "target": "service:CustomerService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:CustomerService@1.0.0-reads-writes-container:CustomerDB@1.0.0",
+    "label": undefined,
+    "source": "service:CustomerService@1.0.0",
+    "target": "container:CustomerDB@1.0.0",
+    "type": "reads-writes",
+  },
+  {
+    "id": "domain:Customer@1.0.0-contains-container:CustomerDB@1.0.0",
+    "label": undefined,
+    "source": "domain:Customer@1.0.0",
+    "target": "container:CustomerDB@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Marketing@1.0.0-contains-service:CampaignService@1.0.0",
+    "label": undefined,
+    "source": "domain:Marketing@1.0.0",
+    "target": "service:CampaignService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Marketing@1.0.0-contains-event:CampaignStarted@1.0.0",
+    "label": undefined,
+    "source": "domain:Marketing@1.0.0",
+    "target": "event:CampaignStarted@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:CampaignService@1.0.0-sends-event:CampaignStarted@1.0.0",
+    "label": undefined,
+    "source": "service:CampaignService@1.0.0",
+    "target": "event:CampaignStarted@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Marketing@1.0.0-contains-event:EmailSent@1.0.0",
+    "label": undefined,
+    "source": "domain:Marketing@1.0.0",
+    "target": "event:EmailSent@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:CampaignService@1.0.0-sends-event:EmailSent@1.0.0",
+    "label": undefined,
+    "source": "service:CampaignService@1.0.0",
+    "target": "event:EmailSent@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Marketing@1.0.0-contains-event:CustomerRegistered@1.0.0",
+    "label": undefined,
+    "source": "domain:Marketing@1.0.0",
+    "target": "event:CustomerRegistered@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:CustomerRegistered@1.0.0-receives-service:CampaignService@1.0.0",
+    "label": undefined,
+    "source": "event:CustomerRegistered@1.0.0",
+    "target": "service:CampaignService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Marketing@1.0.0-contains-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "domain:Marketing@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0-receives-service:CampaignService@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated@1.0.0",
+    "target": "service:CampaignService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:CampaignService@1.0.0-reads-writes-container:CampaignDB@1.0.0",
+    "label": undefined,
+    "source": "service:CampaignService@1.0.0",
+    "target": "container:CampaignDB@1.0.0",
+    "type": "reads-writes",
+  },
+  {
+    "id": "domain:Marketing@1.0.0-contains-container:CampaignDB@1.0.0",
+    "label": undefined,
+    "source": "domain:Marketing@1.0.0",
+    "target": "container:CampaignDB@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-service:AnalyticsService@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "service:AnalyticsService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0-receives-service:AnalyticsService@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated@1.0.0",
+    "target": "service:AnalyticsService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-receives-service:AnalyticsService@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "service:AnalyticsService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-event:ShipmentDelivered@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "event:ShipmentDelivered@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:ShipmentDelivered@1.0.0-receives-service:AnalyticsService@1.0.0",
+    "label": undefined,
+    "source": "event:ShipmentDelivered@1.0.0",
+    "target": "service:AnalyticsService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-event:CustomerRegistered@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "event:CustomerRegistered@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:CustomerRegistered@1.0.0-receives-service:AnalyticsService@1.0.0",
+    "label": undefined,
+    "source": "event:CustomerRegistered@1.0.0",
+    "target": "service:AnalyticsService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:AnalyticsService@1.0.0-writes-to-container:AnalyticsDB@1.0.0",
+    "label": undefined,
+    "source": "service:AnalyticsService@1.0.0",
+    "target": "container:AnalyticsDB@1.0.0",
+    "type": "writes-to",
+  },
+  {
+    "id": "domain:Analytics@1.0.0-contains-container:AnalyticsDB@1.0.0",
+    "label": undefined,
+    "source": "domain:Analytics@1.0.0",
+    "target": "container:AnalyticsDB@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-event:NotificationSent@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "event:NotificationSent@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:NotificationService@1.0.0-sends-event:NotificationSent@1.0.0",
+    "label": undefined,
+    "source": "service:NotificationService@1.0.0",
+    "target": "event:NotificationSent@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-event:OrderShipped@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "event:OrderShipped@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderShipped@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "event:OrderShipped@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-event:PaymentFailed@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "event:PaymentFailed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:PaymentFailed@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentFailed@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-event:ShipmentDelivered@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "event:ShipmentDelivered@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:ShipmentDelivered@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "event:ShipmentDelivered@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:NotificationService@1.0.0-reads-writes-container:NotificationQueue@1.0.0",
+    "label": undefined,
+    "source": "service:NotificationService@1.0.0",
+    "target": "container:NotificationQueue@1.0.0",
+    "type": "reads-writes",
+  },
+  {
+    "id": "domain:Notifications@1.0.0-contains-container:NotificationQueue@1.0.0",
+    "label": undefined,
+    "source": "domain:Notifications@1.0.0",
+    "target": "container:NotificationQueue@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0-sends-data-product:CustomerInsights@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated@1.0.0",
+    "target": "data-product:CustomerInsights@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-sends-data-product:CustomerInsights@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "data-product:CustomerInsights@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:CustomerRegistered@1.0.0-sends-data-product:CustomerInsights@1.0.0",
+    "label": undefined,
+    "source": "event:CustomerRegistered@1.0.0",
+    "target": "data-product:CustomerInsights@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "data-product:CustomerInsights@1.0.0-sends-event:CustomerMetrics",
+    "label": undefined,
+    "source": "data-product:CustomerInsights@1.0.0",
+    "target": "event:CustomerMetrics",
+    "type": "sends",
+  },
+  {
+    "id": "data-product:CustomerInsights@1.0.0-sends-event:PurchasePatterns",
+    "label": undefined,
+    "source": "data-product:CustomerInsights@1.0.0",
+    "target": "event:PurchasePatterns",
+    "type": "sends",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-sends-data-product:RevenueAnalytics@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "data-product:RevenueAnalytics@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderShipped@1.0.0-sends-data-product:RevenueAnalytics@1.0.0",
+    "label": undefined,
+    "source": "event:OrderShipped@1.0.0",
+    "target": "data-product:RevenueAnalytics@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "data-product:RevenueAnalytics@1.0.0-sends-event:DailyRevenue",
+    "label": undefined,
+    "source": "data-product:RevenueAnalytics@1.0.0",
+    "target": "event:DailyRevenue",
+    "type": "sends",
+  },
+  {
+    "id": "data-product:RevenueAnalytics@1.0.0-sends-event:MonthlySalesReport",
+    "label": undefined,
+    "source": "data-product:RevenueAnalytics@1.0.0",
+    "target": "event:MonthlySalesReport",
+    "type": "sends",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Enterprise E-Commerce > Enterprise E-Commerce - nodes 1`] = `
+[
+  {
+    "id": "domain:Orders@1.0.0",
+    "label": "Orders",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Order management and lifecycle",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:OrderService@1.0.0",
+    "label": "OrderService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages order creation, updates, and fulfillment",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0",
+    "label": "OrderCreated",
+    "metadata": {
+      "summary": "New order has been placed by customer",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:OrderShipped@1.0.0",
+    "label": "OrderShipped",
+    "metadata": {
+      "summary": "Order has been shipped to customer",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:OrderCancelled@1.0.0",
+    "label": "OrderCancelled",
+    "metadata": {
+      "summary": "Order has been cancelled",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "command:ProcessPayment@1.0.0",
+    "label": "ProcessPayment",
+    "metadata": {
+      "summary": "Request payment processing",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "command:ReserveStock@1.0.0",
+    "label": "ReserveStock",
+    "metadata": {
+      "summary": "Request inventory reservation",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0",
+    "label": "PaymentProcessed",
+    "metadata": {
+      "summary": "Payment completed successfully",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:PaymentFailed@1.0.0",
+    "label": "PaymentFailed",
+    "metadata": {
+      "summary": "Payment processing failed",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:StockReserved@1.0.0",
+    "label": "StockReserved",
+    "metadata": {
+      "summary": "Stock has been reserved for an order",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "command:CancelOrder@1.0.0",
+    "label": "CancelOrder",
+    "metadata": {
+      "summary": "Cancel an existing order",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "container:OrdersDB@1.0.0",
+    "label": "OrdersDB",
+    "metadata": {
+      "containerType": "database",
+      "summary": "Stores all order data and state",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "container",
+  },
+  {
+    "id": "domain:Payment@1.0.0",
+    "label": "Payment",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Payment processing and billing",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:PaymentService@1.0.0",
+    "label": "PaymentService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Processes payments and manages billing",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "command:RefundPayment@1.0.0",
+    "label": "RefundPayment",
+    "metadata": {
+      "summary": "Process a refund",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "container:PaymentDB@1.0.0",
+    "label": "PaymentDB",
+    "metadata": {
+      "containerType": "database",
+      "summary": "Stores payment transactions",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "container",
+  },
+  {
+    "id": "container:PaymentCache@1.0.0",
+    "label": "PaymentCache",
+    "metadata": {
+      "containerType": "cache",
+      "summary": "Caches payment status for quick lookups",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "container",
+  },
+  {
+    "id": "domain:Inventory@1.0.0",
+    "label": "Inventory",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Inventory and stock management",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:InventoryService@1.0.0",
+    "label": "InventoryService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages product stock levels and reservations",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Inventory@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:StockReleased@1.0.0",
+    "label": "StockReleased",
+    "metadata": {
+      "summary": "Reserved stock has been released",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Inventory@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:LowStockAlert@1.0.0",
+    "label": "LowStockAlert",
+    "metadata": {
+      "summary": "Stock level is below threshold",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Inventory@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "command:ReleaseStock@1.0.0",
+    "label": "ReleaseStock",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Inventory@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "container:InventoryDB@1.0.0",
+    "label": "InventoryDB",
+    "metadata": {
+      "containerType": "database",
+      "summary": "Stores product inventory levels",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Inventory@1.0.0",
+    "type": "container",
+  },
+  {
+    "id": "domain:Shipping@1.0.0",
+    "label": "Shipping",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Shipping and logistics management",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:ShippingService@1.0.0",
+    "label": "ShippingService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages shipment creation and tracking",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Shipping@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:ShipmentCreated@1.0.0",
+    "label": "ShipmentCreated",
+    "metadata": {
+      "summary": "Shipment has been created",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Shipping@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:ShipmentDelivered@1.0.0",
+    "label": "ShipmentDelivered",
+    "metadata": {
+      "summary": "Shipment delivered to customer",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Shipping@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "query:GetShipmentStatus@1.0.0",
+    "label": "GetShipmentStatus",
+    "metadata": {
+      "summary": "Query shipment tracking status",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Shipping@1.0.0",
+    "type": "query",
+  },
+  {
+    "id": "container:ShippingDB@1.0.0",
+    "label": "ShippingDB",
+    "metadata": {
+      "containerType": "database",
+      "summary": "Stores shipment tracking information",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Shipping@1.0.0",
+    "type": "container",
+  },
+  {
+    "id": "domain:Customer@1.0.0",
+    "label": "Customer",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Customer identity and profile management",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:CustomerService@1.0.0",
+    "label": "CustomerService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages customer accounts and profiles",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Customer@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:CustomerRegistered@1.0.0",
+    "label": "CustomerRegistered",
+    "metadata": {
+      "summary": "New customer account created",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Customer@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:CustomerUpdated@1.0.0",
+    "label": "CustomerUpdated",
+    "metadata": {
+      "summary": "Customer profile updated",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Customer@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "command:RegisterCustomer@1.0.0",
+    "label": "RegisterCustomer",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Customer@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "command:UpdateCustomer@1.0.0",
+    "label": "UpdateCustomer",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Customer@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "query:GetCustomerProfile@1.0.0",
+    "label": "GetCustomerProfile",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Customer@1.0.0",
+    "type": "query",
+  },
+  {
+    "id": "container:CustomerDB@1.0.0",
+    "label": "CustomerDB",
+    "metadata": {
+      "containerType": "database",
+      "summary": "Stores customer profiles and preferences",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Customer@1.0.0",
+    "type": "container",
+  },
+  {
+    "id": "domain:Marketing@1.0.0",
+    "label": "Marketing",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Marketing campaigns and customer engagement",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:CampaignService@1.0.0",
+    "label": "CampaignService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages marketing campaigns",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Marketing@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:CampaignStarted@1.0.0",
+    "label": "CampaignStarted",
+    "metadata": {
+      "summary": "Marketing campaign has started",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Marketing@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:EmailSent@1.0.0",
+    "label": "EmailSent",
+    "metadata": {
+      "summary": "Marketing email sent to customer",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Marketing@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "container:CampaignDB@1.0.0",
+    "label": "CampaignDB",
+    "metadata": {
+      "containerType": "database",
+      "summary": "Stores campaign data and metrics",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Marketing@1.0.0",
+    "type": "container",
+  },
+  {
+    "id": "domain:Analytics@1.0.0",
+    "label": "Analytics",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Business intelligence and analytics",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:AnalyticsService@1.0.0",
+    "label": "AnalyticsService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Processes and aggregates business metrics",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Analytics@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "container:AnalyticsDB@1.0.0",
+    "label": "AnalyticsDB",
+    "metadata": {
+      "containerType": "dataWarehouse",
+      "summary": "Data warehouse for analytics",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Analytics@1.0.0",
+    "type": "container",
+  },
+  {
+    "id": "domain:Notifications@1.0.0",
+    "label": "Notifications",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Multi-channel notification delivery",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:NotificationService@1.0.0",
+    "label": "NotificationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends notifications via email, SMS, and push",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Notifications@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:NotificationSent@1.0.0",
+    "label": "NotificationSent",
+    "metadata": {
+      "summary": "Notification delivered to customer",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Notifications@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "container:NotificationQueue@1.0.0",
+    "label": "NotificationQueue",
+    "metadata": {
+      "containerType": "cache",
+      "summary": "Queue for pending notifications",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Notifications@1.0.0",
+    "type": "container",
+  },
+  {
+    "id": "channel:OrdersChannel@1.0.0",
+    "label": "OrdersChannel",
+    "metadata": {
+      "address": "orders.events",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "kafka",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "channel:PaymentsChannel@1.0.0",
+    "label": "PaymentsChannel",
+    "metadata": {
+      "address": "payments.events",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "kafka",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "channel:ShippingChannel@1.0.0",
+    "label": "ShippingChannel",
+    "metadata": {
+      "address": "shipping.events",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "kafka",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "channel:CommandAPI@1.0.0",
+    "label": "CommandAPI",
+    "metadata": {
+      "address": "/api/v1",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "http",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "data-product:CustomerInsights@1.0.0",
+    "label": "CustomerInsights",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Customer behavior and purchase analytics",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "data-product",
+  },
+  {
+    "id": "event:CustomerMetrics",
+    "label": "CustomerMetrics",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:PurchasePatterns",
+    "label": "PurchasePatterns",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "data-product:RevenueAnalytics@1.0.0",
+    "label": "RevenueAnalytics",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Real-time revenue and sales analytics",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "data-product",
+  },
+  {
+    "id": "event:DailyRevenue",
+    "label": "DailyRevenue",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:MonthlySalesReport",
+    "label": "MonthlySalesReport",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Event-Driven Saga > Event-Driven Saga - edges 1`] = `
+[
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderPlaced@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderPlaced@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderPlaced@1.0.0-routes-to-channel:SagaEvents@1.0.0",
+    "label": undefined,
+    "source": "event:OrderPlaced@1.0.0",
+    "target": "channel:SagaEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderConfirmed@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderConfirmed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderConfirmed@1.0.0-routes-to-channel:SagaEvents@1.0.0",
+    "label": undefined,
+    "source": "event:OrderConfirmed@1.0.0",
+    "target": "channel:SagaEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderRejected@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderRejected@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderRejected@1.0.0-routes-to-channel:SagaEvents@1.0.0",
+    "label": undefined,
+    "source": "event:OrderRejected@1.0.0",
+    "target": "channel:SagaEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "event:PaymentConfirmed@1.0.0-routes-to-channel:SagaEvents@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentConfirmed@1.0.0",
+    "target": "channel:SagaEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:SagaEvents@1.0.0-receives-service:OrderService@1.0.0",
+    "label": undefined,
+    "source": "channel:SagaEvents@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "event:PaymentRejected@1.0.0-routes-to-channel:SagaEvents@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentRejected@1.0.0",
+    "target": "channel:SagaEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "event:StockReserved@1.0.0-routes-to-channel:SagaEvents@1.0.0",
+    "label": undefined,
+    "source": "event:StockReserved@1.0.0",
+    "target": "channel:SagaEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "event:StockUnavailable@1.0.0-routes-to-channel:SagaEvents@1.0.0",
+    "label": undefined,
+    "source": "event:StockUnavailable@1.0.0",
+    "target": "channel:SagaEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentConfirmed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentConfirmed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentRejected@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentRejected@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "channel:SagaEvents@1.0.0-receives-service:PaymentService@1.0.0",
+    "label": undefined,
+    "source": "channel:SagaEvents@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:InventoryService@1.0.0-sends-event:StockReserved@1.0.0",
+    "label": undefined,
+    "source": "service:InventoryService@1.0.0",
+    "target": "event:StockReserved@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "service:InventoryService@1.0.0-sends-event:StockUnavailable@1.0.0",
+    "label": undefined,
+    "source": "service:InventoryService@1.0.0",
+    "target": "event:StockUnavailable@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "channel:SagaEvents@1.0.0-receives-service:InventoryService@1.0.0",
+    "label": undefined,
+    "source": "channel:SagaEvents@1.0.0",
+    "target": "service:InventoryService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "channel:SagaEvents@1.0.0-receives-service:EmailService@1.0.0",
+    "label": undefined,
+    "source": "channel:SagaEvents@1.0.0",
+    "target": "service:EmailService@1.0.0",
+    "type": "receives",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Event-Driven Saga > Event-Driven Saga - nodes 1`] = `
+[
+  {
+    "id": "channel:SagaEvents@1.0.0",
+    "label": "SagaEvents",
+    "metadata": {
+      "address": "saga.events",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "nservicebus",
+      ],
+      "summary": "NServiceBus for saga coordination",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "service:OrderService@1.0.0",
+    "label": "OrderService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Order orchestration",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:OrderPlaced@1.0.0",
+    "label": "OrderPlaced",
+    "metadata": {
+      "summary": "Customer placed a new order",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:OrderConfirmed@1.0.0",
+    "label": "OrderConfirmed",
+    "metadata": {
+      "summary": "Order fully confirmed",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:OrderRejected@1.0.0",
+    "label": "OrderRejected",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:PaymentConfirmed@1.0.0",
+    "label": "PaymentConfirmed",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:PaymentRejected@1.0.0",
+    "label": "PaymentRejected",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:StockReserved@1.0.0",
+    "label": "StockReserved",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:StockUnavailable@1.0.0",
+    "label": "StockUnavailable",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:PaymentService@1.0.0",
+    "label": "PaymentService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Payment processing",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:InventoryService@1.0.0",
+    "label": "InventoryService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Stock management",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:EmailService@1.0.0",
+    "label": "EmailService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Customer communications",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Flow: E-Commerce Checkout > Flow: E-Commerce Checkout - edges 1`] = `
+[
+  {
+    "id": "actor:Customer-flow-step-command:InitiateCheckout",
+    "label": "initiates checkout",
+    "source": "actor:Customer",
+    "target": "command:InitiateCheckout",
+    "type": "flow-step",
+  },
+  {
+    "id": "command:InitiateCheckout-flow-step-service:CartService",
+    "label": undefined,
+    "source": "command:InitiateCheckout",
+    "target": "service:CartService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:CartService-flow-step-event:CheckoutValidated",
+    "label": "validates cart",
+    "source": "service:CartService",
+    "target": "event:CheckoutValidated",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:CheckoutValidated-flow-step-service:ValidationService",
+    "label": "validates customer data",
+    "source": "event:CheckoutValidated",
+    "target": "service:ValidationService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:ValidationService-flow-step-event:FraudCheckPassed",
+    "label": "valid",
+    "source": "service:ValidationService",
+    "target": "event:FraudCheckPassed",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:ValidationService-flow-step-event:ValidationFailed",
+    "label": "invalid",
+    "source": "service:ValidationService",
+    "target": "event:ValidationFailed",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:CheckoutValidated-flow-step-service:FraudDetectionService",
+    "label": "runs fraud analysis",
+    "source": "event:CheckoutValidated",
+    "target": "service:FraudDetectionService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:FraudDetectionService-flow-step-event:FraudCheckPassed",
+    "label": "pass",
+    "source": "service:FraudDetectionService",
+    "target": "event:FraudCheckPassed",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:FraudDetectionService-flow-step-event:FraudDetected",
+    "label": "fail",
+    "source": "service:FraudDetectionService",
+    "target": "event:FraudDetected",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:ValidationFailed-flow-step-service:EmailService",
+    "label": "notifies customer of validation errors",
+    "source": "event:ValidationFailed",
+    "target": "service:EmailService",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:FraudDetected-flow-step-service:EmailService",
+    "label": "notifies fraud team",
+    "source": "event:FraudDetected",
+    "target": "service:EmailService",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:FraudDetected-flow-step-service:AnalyticsService",
+    "label": "logs fraud attempt",
+    "source": "event:FraudDetected",
+    "target": "service:AnalyticsService",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:FraudCheckPassed-flow-step-external-system:PaymentGateway",
+    "label": "authorizes payment",
+    "source": "event:FraudCheckPassed",
+    "target": "external-system:PaymentGateway",
+    "type": "flow-step",
+  },
+  {
+    "id": "external-system:PaymentGateway-flow-step-event:PaymentAuthorized",
+    "label": "authorized",
+    "source": "external-system:PaymentGateway",
+    "target": "event:PaymentAuthorized",
+    "type": "flow-step",
+  },
+  {
+    "id": "external-system:PaymentGateway-flow-step-event:PaymentFailed",
+    "label": "declined",
+    "source": "external-system:PaymentGateway",
+    "target": "event:PaymentFailed",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:PaymentFailed-flow-step-service:CartService",
+    "label": "restores cart",
+    "source": "event:PaymentFailed",
+    "target": "service:CartService",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:PaymentFailed-flow-step-service:EmailService",
+    "label": "notifies customer of payment failure",
+    "source": "event:PaymentFailed",
+    "target": "service:EmailService",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:PaymentAuthorized-flow-step-service:InventoryService",
+    "label": "reserves stock",
+    "source": "event:PaymentAuthorized",
+    "target": "service:InventoryService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:InventoryService-flow-step-event:InventoryReserved",
+    "label": "reserved",
+    "source": "service:InventoryService",
+    "target": "event:InventoryReserved",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:InventoryService-flow-step-event:InventoryUnavailable",
+    "label": "unavailable",
+    "source": "service:InventoryService",
+    "target": "event:InventoryUnavailable",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:PaymentAuthorized-flow-step-service:TaxService",
+    "label": "calculates tax via API",
+    "source": "event:PaymentAuthorized",
+    "target": "service:TaxService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:TaxService-flow-step-event:TaxCalculated",
+    "label": undefined,
+    "source": "service:TaxService",
+    "target": "event:TaxCalculated",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:PaymentAuthorized-flow-step-service:ShippingService",
+    "label": "calculates shipping cost",
+    "source": "event:PaymentAuthorized",
+    "target": "service:ShippingService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:ShippingService-flow-step-event:ShippingCalculated",
+    "label": undefined,
+    "source": "service:ShippingService",
+    "target": "event:ShippingCalculated",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:InventoryUnavailable-flow-step-external-system:PaymentGateway",
+    "label": "refunds payment",
+    "source": "event:InventoryUnavailable",
+    "target": "external-system:PaymentGateway",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:InventoryUnavailable-flow-step-service:EmailService",
+    "label": "notifies customer of unavailable items",
+    "source": "event:InventoryUnavailable",
+    "target": "service:EmailService",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:InventoryReserved-flow-step-service:CartService",
+    "label": "confirms order",
+    "source": "event:InventoryReserved",
+    "target": "service:CartService",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:TaxCalculated-flow-step-service:CartService",
+    "label": "confirms order",
+    "source": "event:TaxCalculated",
+    "target": "service:CartService",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:ShippingCalculated-flow-step-service:CartService",
+    "label": "confirms order",
+    "source": "event:ShippingCalculated",
+    "target": "service:CartService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:CartService-flow-step-event:OrderConfirmed",
+    "label": undefined,
+    "source": "service:CartService",
+    "target": "event:OrderConfirmed",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:OrderConfirmed-flow-step-service:WarehouseService",
+    "label": "creates pick ticket",
+    "source": "event:OrderConfirmed",
+    "target": "service:WarehouseService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:WarehouseService-flow-step-event:ShipmentCreated",
+    "label": undefined,
+    "source": "service:WarehouseService",
+    "target": "event:ShipmentCreated",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:OrderConfirmed-flow-step-service:AccountingService",
+    "label": "generates invoice",
+    "source": "event:OrderConfirmed",
+    "target": "service:AccountingService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:AccountingService-flow-step-event:InvoiceGenerated",
+    "label": undefined,
+    "source": "service:AccountingService",
+    "target": "event:InvoiceGenerated",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:OrderConfirmed-flow-step-service:EmailService",
+    "label": "sends confirmation email",
+    "source": "event:OrderConfirmed",
+    "target": "service:EmailService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:EmailService-flow-step-event:ConfirmationEmailSent",
+    "label": undefined,
+    "source": "service:EmailService",
+    "target": "event:ConfirmationEmailSent",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:OrderConfirmed-flow-step-service:AnalyticsService",
+    "label": "tracks conversion",
+    "source": "event:OrderConfirmed",
+    "target": "service:AnalyticsService",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:ShipmentCreated-flow-step-external-system:ShippingCarrier",
+    "label": "creates shipping label",
+    "source": "event:ShipmentCreated",
+    "target": "external-system:ShippingCarrier",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:ShipmentCreated-flow-step-service:WarehouseService",
+    "label": "assigns to picker",
+    "source": "event:ShipmentCreated",
+    "target": "service:WarehouseService",
+    "type": "flow-step",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Flow: E-Commerce Checkout > Flow: E-Commerce Checkout - nodes 1`] = `
+[
+  {
+    "id": "actor:Customer",
+    "label": "Customer",
+    "metadata": {
+      "summary": "End user completing purchase",
+    },
+    "parentId": undefined,
+    "type": "actor",
+  },
+  {
+    "id": "command:InitiateCheckout",
+    "label": "Initiate Checkout",
+    "metadata": {
+      "summary": "Customer starts checkout process",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "service:CartService",
+    "label": "Cart Service",
+    "metadata": {
+      "summary": "Manages shopping cart and checkout",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:CheckoutValidated",
+    "label": "Checkout Validated",
+    "metadata": {
+      "summary": "Cart and checkout data validated",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:ValidationService",
+    "label": "Validation Service",
+    "metadata": {
+      "summary": "Validates customer and order data",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:FraudCheckPassed",
+    "label": "Fraud Check Passed",
+    "metadata": {
+      "summary": "Order passed fraud detection",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:ValidationFailed",
+    "label": "Validation Failed",
+    "metadata": {
+      "summary": "Customer or order data validation failed",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:FraudDetectionService",
+    "label": "Fraud Detection Service",
+    "metadata": {
+      "summary": "Analyzes orders for fraud patterns",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:FraudDetected",
+    "label": "Fraud Detected",
+    "metadata": {
+      "summary": "Potential fraud detected",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:EmailService",
+    "label": "Email Service",
+    "metadata": {
+      "summary": "Sends transactional emails",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:AnalyticsService",
+    "label": "Analytics Service",
+    "metadata": {
+      "summary": "Tracks events and conversions",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "external-system:PaymentGateway",
+    "label": "Stripe Payment Gateway",
+    "metadata": {
+      "summary": "Third-party payment processor",
+    },
+    "parentId": undefined,
+    "type": "external-system",
+  },
+  {
+    "id": "event:PaymentAuthorized",
+    "label": "Payment Authorized",
+    "metadata": {
+      "summary": "Payment successfully authorized",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:PaymentFailed",
+    "label": "Payment Failed",
+    "metadata": {
+      "summary": "Payment declined or failed",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:InventoryService",
+    "label": "Inventory Service",
+    "metadata": {
+      "summary": "Manages stock and reservations",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:InventoryReserved",
+    "label": "Inventory Reserved",
+    "metadata": {
+      "summary": "Stock reserved for order",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:InventoryUnavailable",
+    "label": "Inventory Unavailable",
+    "metadata": {
+      "summary": "Insufficient stock available",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:TaxService",
+    "label": "Tax Service",
+    "metadata": {
+      "summary": "Calculates taxes via external API",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:TaxCalculated",
+    "label": "Tax Calculated",
+    "metadata": {
+      "summary": "Tax amount calculated",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:ShippingService",
+    "label": "Shipping Service",
+    "metadata": {
+      "summary": "Calculates shipping costs and methods",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:ShippingCalculated",
+    "label": "Shipping Calculated",
+    "metadata": {
+      "summary": "Shipping cost and method determined",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:OrderConfirmed",
+    "label": "Order Confirmed",
+    "metadata": {
+      "summary": "Order fully confirmed and ready for fulfillment",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:WarehouseService",
+    "label": "Warehouse Service",
+    "metadata": {
+      "summary": "Manages warehouse operations",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:ShipmentCreated",
+    "label": "Shipment Created",
+    "metadata": {
+      "summary": "Warehouse shipment created",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:AccountingService",
+    "label": "Accounting Service",
+    "metadata": {
+      "summary": "Handles invoicing and accounting",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:InvoiceGenerated",
+    "label": "Invoice Generated",
+    "metadata": {
+      "summary": "Invoice created for order",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:ConfirmationEmailSent",
+    "label": "Confirmation Email Sent",
+    "metadata": {
+      "summary": "Customer received order confirmation",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "external-system:ShippingCarrier",
+    "label": "FedEx API",
+    "metadata": {
+      "summary": "Shipping carrier integration",
+    },
+    "parentId": undefined,
+    "type": "external-system",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Flow: Order Fulfillment > Flow: Order Fulfillment - edges 1`] = `
+[
+  {
+    "id": "actor:Customer-flow-step-command:PlaceOrder",
+    "label": "places an order",
+    "source": "actor:Customer",
+    "target": "command:PlaceOrder",
+    "type": "flow-step",
+  },
+  {
+    "id": "command:PlaceOrder-flow-step-service:OrderService",
+    "label": undefined,
+    "source": "command:PlaceOrder",
+    "target": "service:OrderService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:OrderService-flow-step-event:OrderCreated",
+    "label": "creates the order",
+    "source": "service:OrderService",
+    "target": "event:OrderCreated",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:OrderCreated-flow-step-service:PaymentService",
+    "label": "processes the payment",
+    "source": "event:OrderCreated",
+    "target": "service:PaymentService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:PaymentService-flow-step-event:PaymentProcessed",
+    "label": "success",
+    "source": "service:PaymentService",
+    "target": "event:PaymentProcessed",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:PaymentService-flow-step-event:PaymentFailed",
+    "label": "failure",
+    "source": "service:PaymentService",
+    "target": "event:PaymentFailed",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:OrderCreated-flow-step-service:InventoryService",
+    "label": "reserves stock",
+    "source": "event:OrderCreated",
+    "target": "service:InventoryService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:InventoryService-flow-step-event:StockReserved",
+    "label": undefined,
+    "source": "service:InventoryService",
+    "target": "event:StockReserved",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:PaymentFailed-flow-step-service:NotificationService",
+    "label": "notifies the customer of failure",
+    "source": "event:PaymentFailed",
+    "target": "service:NotificationService",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:PaymentProcessed-flow-step-service:FulfillmentService",
+    "label": "ships the order",
+    "source": "event:PaymentProcessed",
+    "target": "service:FulfillmentService",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:StockReserved-flow-step-service:FulfillmentService",
+    "label": "ships the order",
+    "source": "event:StockReserved",
+    "target": "service:FulfillmentService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:FulfillmentService-flow-step-event:OrderShipped",
+    "label": undefined,
+    "source": "service:FulfillmentService",
+    "target": "event:OrderShipped",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:OrderShipped-flow-step-external-system:WarehouseWMS",
+    "label": "syncs with legacy WMS",
+    "source": "event:OrderShipped",
+    "target": "external-system:WarehouseWMS",
+    "type": "flow-step",
+  },
+  {
+    "id": "event:OrderShipped-flow-step-service:NotificationService",
+    "label": "notifies the customer",
+    "source": "event:OrderShipped",
+    "target": "service:NotificationService",
+    "type": "flow-step",
+  },
+  {
+    "id": "service:NotificationService-flow-step-event:CustomerNotified",
+    "label": undefined,
+    "source": "service:NotificationService",
+    "target": "event:CustomerNotified",
+    "type": "flow-step",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Flow: Order Fulfillment > Flow: Order Fulfillment - nodes 1`] = `
+[
+  {
+    "id": "actor:Customer",
+    "label": "Customer",
+    "metadata": {
+      "summary": "End user on the storefront",
+    },
+    "parentId": undefined,
+    "type": "actor",
+  },
+  {
+    "id": "command:PlaceOrder",
+    "label": "Place Order",
+    "metadata": {
+      "summary": "Customer places a new order",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "service:OrderService",
+    "label": "Order Service",
+    "metadata": {
+      "summary": "Manages the order lifecycle",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:OrderCreated",
+    "label": "Order Created",
+    "metadata": {
+      "summary": "Emitted when a new order is placed",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:PaymentService",
+    "label": "Payment Service",
+    "metadata": {
+      "summary": "Processes payments via Stripe",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:PaymentProcessed",
+    "label": "Payment Processed",
+    "metadata": {
+      "summary": "Payment completed successfully",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:PaymentFailed",
+    "label": "Payment Failed",
+    "metadata": {
+      "summary": "Payment was declined or errored",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:InventoryService",
+    "label": "Inventory Service",
+    "metadata": {
+      "summary": "Manages stock and reservations",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:StockReserved",
+    "label": "Stock Reserved",
+    "metadata": {
+      "summary": "Inventory reserved for order",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:NotificationService",
+    "label": "Notification Service",
+    "metadata": {
+      "summary": "Sends email and push notifications",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:FulfillmentService",
+    "label": "Fulfillment Service",
+    "metadata": {
+      "summary": "Coordinates order shipping",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:OrderShipped",
+    "label": "Order Shipped",
+    "metadata": {
+      "summary": "Order has been dispatched",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "external-system:WarehouseWMS",
+    "label": "Warehouse WMS",
+    "metadata": {
+      "summary": "Legacy warehouse management system",
+    },
+    "parentId": undefined,
+    "type": "external-system",
+  },
+  {
+    "id": "event:CustomerNotified",
+    "label": "Customer Notified",
+    "metadata": {
+      "summary": "Customer received notification",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Minimal Service > Minimal Service - edges 1`] = `
+[
+  {
+    "id": "service:UserService@1.0.0-sends-event:UserCreated",
+    "label": undefined,
+    "source": "service:UserService@1.0.0",
+    "target": "event:UserCreated",
+    "type": "sends",
+  },
+  {
+    "id": "service:UserService@1.0.0-sends-event:UserUpdated",
+    "label": undefined,
+    "source": "service:UserService@1.0.0",
+    "target": "event:UserUpdated",
+    "type": "sends",
+  },
+  {
+    "id": "command:CreateUser-receives-service:UserService@1.0.0",
+    "label": "accepts",
+    "source": "command:CreateUser",
+    "target": "service:UserService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "command:UpdateUser-receives-service:UserService@1.0.0",
+    "label": "accepts",
+    "source": "command:UpdateUser",
+    "target": "service:UserService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "query:GetUser-receives-service:UserService@1.0.0",
+    "label": "accepts",
+    "source": "query:GetUser",
+    "target": "service:UserService@1.0.0",
+    "type": "receives",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Minimal Service > Minimal Service - nodes 1`] = `
+[
+  {
+    "id": "service:UserService@1.0.0",
+    "label": "UserService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages user accounts",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:UserCreated",
+    "label": "UserCreated",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:UserUpdated",
+    "label": "UserUpdated",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "command:CreateUser",
+    "label": "CreateUser",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "command:UpdateUser",
+    "label": "UpdateUser",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "query:GetUser",
+    "label": "GetUser",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "query",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Multi-File with Imports > Multi-File with Imports - edges 1`] = `
+[
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentFailed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentFailed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "command:ProcessPayment@1.0.0-receives-service:PaymentService@1.0.0",
+    "label": "accepts",
+    "source": "command:ProcessPayment@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-command:ProcessPayment@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "command:ProcessPayment@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-receives-service:OrderService@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:NotificationService@1.0.0-sends-event:NotificationSent@1.0.0",
+    "label": undefined,
+    "source": "service:NotificationService@1.0.0",
+    "target": "event:NotificationSent@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-routes-to-channel:MessageBus@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "channel:MessageBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:MessageBus@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:MessageBus@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "event:PaymentFailed@1.0.0-routes-to-channel:MessageBus@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentFailed@1.0.0",
+    "target": "channel:MessageBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0-routes-to-channel:MessageBus@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated@1.0.0",
+    "target": "channel:MessageBus@1.0.0",
+    "type": "routes-to",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Multi-File with Imports > Multi-File with Imports - nodes 1`] = `
+[
+  {
+    "id": "channel:MessageBus@1.0.0",
+    "label": "MessageBus",
+    "metadata": {
+      "address": "events.stream",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "kafka",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "service:PaymentService@1.0.0",
+    "label": "PaymentService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Handles payment transactions",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0",
+    "label": "PaymentProcessed",
+    "metadata": {
+      "summary": "Payment completed successfully",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:PaymentFailed@1.0.0",
+    "label": "PaymentFailed",
+    "metadata": {
+      "summary": "Payment processing failed",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "command:ProcessPayment@1.0.0",
+    "label": "ProcessPayment",
+    "metadata": {
+      "summary": "Initiate payment processing",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "service:OrderService@1.0.0",
+    "label": "OrderService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages order lifecycle",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0",
+    "label": "OrderCreated",
+    "metadata": {
+      "summary": "New order created",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:NotificationService@1.0.0",
+    "label": "NotificationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends notifications for important events",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:NotificationSent@1.0.0",
+    "label": "NotificationSent",
+    "metadata": {
+      "summary": "Notification delivered to user",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Notes & Annotations > Notes & Annotations - edges 1`] = `
+[
+  {
+    "id": "domain:Orders@1.0.0-contains-service:OrderService@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-channel:OrderEvents@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "channel:OrderEvents@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0-routes-to-channel:OrderEvents@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated@1.0.0",
+    "target": "channel:OrderEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderCancelled@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderCancelled@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCancelled@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCancelled@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderCancelled@1.0.0-routes-to-channel:OrderEvents@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCancelled@1.0.0",
+    "target": "channel:OrderEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-command:CreateOrder@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "command:CreateOrder@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:CreateOrder@1.0.0-receives-service:OrderService@1.0.0",
+    "label": "accepts",
+    "source": "command:CreateOrder@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-service:LegacyOrderService@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "service:LegacyOrderService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:LegacyOrderService@1.0.0-sends-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "service:LegacyOrderService@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "command:CreateOrder@1.0.0-receives-service:LegacyOrderService@1.0.0",
+    "label": "accepts",
+    "source": "command:CreateOrder@1.0.0",
+    "target": "service:LegacyOrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-service:PaymentService@2.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "service:PaymentService@2.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:PaymentService@2.0.0-sends-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@2.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-channel:PaymentEvents@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "channel:PaymentEvents@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-routes-to-channel:PaymentEvents@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "channel:PaymentEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-event:PaymentFailed@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "event:PaymentFailed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:PaymentService@2.0.0-sends-event:PaymentFailed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@2.0.0",
+    "target": "event:PaymentFailed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:PaymentFailed@1.0.0-routes-to-channel:PaymentEvents@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentFailed@1.0.0",
+    "target": "channel:PaymentEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-event:OrderCreated@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "event:OrderCreated@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-channel:OrderEvents@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "channel:OrderEvents@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:OrderEvents@1.0.0-receives-service:PaymentService@2.0.0",
+    "label": undefined,
+    "source": "channel:OrderEvents@1.0.0",
+    "target": "service:PaymentService@2.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "channel:PaymentEvents@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:PaymentEvents@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "channel:OrderEvents@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:OrderEvents@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Notes & Annotations > Notes & Annotations - nodes 1`] = `
+[
+  {
+    "id": "channel:OrderEvents@1.0.0",
+    "label": "OrderEvents",
+    "metadata": {
+      "address": "orders.events",
+      "deprecated": undefined,
+      "draft": undefined,
+      "notes": [
+        {
+          "author": "infra-team",
+          "content": "Partition key is orderId",
+        },
+        {
+          "content": "Retention set to 7 days",
+        },
+      ],
+      "protocols": [
+        "kafka",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "channel:PaymentEvents@1.0.0",
+    "label": "PaymentEvents",
+    "metadata": {
+      "address": "payments.events",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "kafka",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "domain:Orders@1.0.0",
+    "label": "Orders",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Order management",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:OrderService@1.0.0",
+    "label": "OrderService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "notes": [
+        {
+          "author": "alice",
+          "content": "Needs rate limiting before Black Friday",
+          "priority": "high",
+        },
+        {
+          "author": "bob",
+          "content": "Migrating to event sourcing in Q3",
+        },
+      ],
+      "summary": "Handles order lifecycle",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:OrderCreated@1.0.0",
+    "label": "OrderCreated",
+    "metadata": {
+      "notes": [
+        {
+          "author": "alice",
+          "content": "Schema v2 adds shippingAddress field",
+        },
+      ],
+      "summary": "New order placed",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:OrderCancelled@1.0.0",
+    "label": "OrderCancelled",
+    "metadata": {
+      "summary": "Order was cancelled",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "command:CreateOrder@1.0.0",
+    "label": "CreateOrder",
+    "metadata": {
+      "notes": [
+        {
+          "author": "bob",
+          "content": "Validate idempotency key before processing",
+          "priority": "high",
+        },
+      ],
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "service:LegacyOrderService@1.0.0",
+    "label": "LegacyOrderService",
+    "metadata": {
+      "deprecated": true,
+      "draft": undefined,
+      "notes": [
+        {
+          "content": "Decommission by Q4 2026",
+          "priority": "high",
+        },
+        {
+          "content": "See migration runbook: https://wiki.internal/orders-migration",
+        },
+        {
+          "author": "carol",
+          "content": "Only handles EU region traffic now",
+        },
+      ],
+      "summary": "Old monolith — being decommissioned",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "domain:Payment@1.0.0",
+    "label": "Payment",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Payment processing",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:PaymentService@2.0.0",
+    "label": "PaymentService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "notes": [
+        {
+          "author": "dave",
+          "content": "v2 adds support for crypto payments",
+        },
+      ],
+      "summary": "Processes payments and refunds",
+      "version": "2.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0",
+    "label": "PaymentProcessed",
+    "metadata": {
+      "notes": [
+        {
+          "author": "dave",
+          "content": "Includes refund reference when applicable",
+        },
+      ],
+      "summary": "Payment completed",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:PaymentFailed@1.0.0",
+    "label": "PaymentFailed",
+    "metadata": {
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "service:NotificationService@1.0.0",
+    "label": "NotificationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends customer notifications",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > OpenAPI + AsyncAPI Mixed > OpenAPI + AsyncAPI Mixed - edges 1`] = `
+[
+  {
+    "id": "service:WebApp@1.0.0-sends-command:CreateOrder",
+    "label": undefined,
+    "source": "service:WebApp@1.0.0",
+    "target": "command:CreateOrder",
+    "type": "sends",
+  },
+  {
+    "id": "service:WebApp@1.0.0-sends-query:GetOrders",
+    "label": undefined,
+    "source": "service:WebApp@1.0.0",
+    "target": "query:GetOrders",
+    "type": "sends",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > OpenAPI + AsyncAPI Mixed > OpenAPI + AsyncAPI Mixed - nodes 1`] = `
+[
+  {
+    "id": "service:OrderService",
+    "label": "OrderService",
+    "metadata": {
+      "version": undefined,
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:InventoryService",
+    "label": "InventoryService",
+    "metadata": {
+      "version": undefined,
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:WebApp@1.0.0",
+    "label": "WebApp",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Customer-facing web application",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "command:CreateOrder",
+    "label": "CreateOrder",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "query:GetOrders",
+    "label": "GetOrders",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "query",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > OpenAPI Import > OpenAPI Import - edges 1`] = `
+[
+  {
+    "id": "command:CreateOrder-receives-service:OrderService@1.0.0",
+    "label": "accepts",
+    "source": "command:CreateOrder",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "command:UpdateOrder-receives-service:OrderService@1.0.0",
+    "label": "accepts",
+    "source": "command:UpdateOrder",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "command:DeleteOrder-receives-service:OrderService@1.0.0",
+    "label": "accepts",
+    "source": "command:DeleteOrder",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "query:GetOrders-receives-service:OrderService@1.0.0",
+    "label": "accepts",
+    "source": "query:GetOrders",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "query:GetOrder-receives-service:OrderService@1.0.0",
+    "label": "accepts",
+    "source": "query:GetOrder",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:AdminDashboard@1.0.0-sends-query:GetOrders",
+    "label": undefined,
+    "source": "service:AdminDashboard@1.0.0",
+    "target": "query:GetOrders",
+    "type": "sends",
+  },
+  {
+    "id": "service:AdminDashboard@1.0.0-sends-query:GetOrder",
+    "label": undefined,
+    "source": "service:AdminDashboard@1.0.0",
+    "target": "query:GetOrder",
+    "type": "sends",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > OpenAPI Import > OpenAPI Import - nodes 1`] = `
+[
+  {
+    "id": "service:OrderService@1.0.0",
+    "label": "OrderService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages order CRUD operations",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "command:CreateOrder",
+    "label": "CreateOrder",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "command:UpdateOrder",
+    "label": "UpdateOrder",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "command:DeleteOrder",
+    "label": "DeleteOrder",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "query:GetOrders",
+    "label": "GetOrders",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "query",
+  },
+  {
+    "id": "query:GetOrder",
+    "label": "GetOrder",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "query",
+  },
+  {
+    "id": "service:AdminDashboard@1.0.0",
+    "label": "AdminDashboard",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Internal admin tool",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > OpenAPI Remote Import > OpenAPI Remote Import - edges 1`] = `
+[
+  {
+    "id": "command:addPet-receives-service:PetStoreAPI@1.0.0",
+    "label": "accepts",
+    "source": "command:addPet",
+    "target": "service:PetStoreAPI@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "command:updatePet-receives-service:PetStoreAPI@1.0.0",
+    "label": "accepts",
+    "source": "command:updatePet",
+    "target": "service:PetStoreAPI@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "command:deletePet-receives-service:PetStoreAPI@1.0.0",
+    "label": "accepts",
+    "source": "command:deletePet",
+    "target": "service:PetStoreAPI@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "query:findPetsByStatus-receives-service:PetStoreAPI@1.0.0",
+    "label": "accepts",
+    "source": "query:findPetsByStatus",
+    "target": "service:PetStoreAPI@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "query:getPetById-receives-service:PetStoreAPI@1.0.0",
+    "label": "accepts",
+    "source": "query:getPetById",
+    "target": "service:PetStoreAPI@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:PetAdoptionApp@1.0.0-sends-query:findPetsByStatus",
+    "label": undefined,
+    "source": "service:PetAdoptionApp@1.0.0",
+    "target": "query:findPetsByStatus",
+    "type": "sends",
+  },
+  {
+    "id": "service:PetAdoptionApp@1.0.0-sends-query:getPetById",
+    "label": undefined,
+    "source": "service:PetAdoptionApp@1.0.0",
+    "target": "query:getPetById",
+    "type": "sends",
+  },
+  {
+    "id": "service:PetAdoptionApp@1.0.0-sends-command:addPet",
+    "label": undefined,
+    "source": "service:PetAdoptionApp@1.0.0",
+    "target": "command:addPet",
+    "type": "sends",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > OpenAPI Remote Import > OpenAPI Remote Import - nodes 1`] = `
+[
+  {
+    "id": "service:PetStoreAPI@1.0.0",
+    "label": "PetStoreAPI",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages pets in the store",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "command:addPet",
+    "label": "addPet",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "command:updatePet",
+    "label": "updatePet",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "command:deletePet",
+    "label": "deletePet",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "query:findPetsByStatus",
+    "label": "findPetsByStatus",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "query",
+  },
+  {
+    "id": "query:getPetById",
+    "label": "getPetById",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "query",
+  },
+  {
+    "id": "service:PetAdoptionApp@1.0.0",
+    "label": "PetAdoptionApp",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Customer-facing pet adoption application",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > OpenAPI Service Import > OpenAPI Service Import - edges 1`] = `
+[
+  {
+    "id": "service:CheckoutService@1.0.0-sends-command:CreatePayment",
+    "label": undefined,
+    "source": "service:CheckoutService@1.0.0",
+    "target": "command:CreatePayment",
+    "type": "sends",
+  },
+  {
+    "id": "service:CheckoutService@1.0.0-sends-query:GetPayment",
+    "label": undefined,
+    "source": "service:CheckoutService@1.0.0",
+    "target": "query:GetPayment",
+    "type": "sends",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > OpenAPI Service Import > OpenAPI Service Import - nodes 1`] = `
+[
+  {
+    "id": "service:PaymentService",
+    "label": "PaymentService",
+    "metadata": {
+      "version": undefined,
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:CheckoutService@1.0.0",
+    "label": "CheckoutService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Handles the checkout flow",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "command:CreatePayment",
+    "label": "CreatePayment",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "query:GetPayment",
+    "label": "GetPayment",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "query",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Order Service Showcase > Order Service Showcase - edges 1`] = `
+[
+  {
+    "id": "service:OrderService@2.0.0-sends-event:OrderCreated",
+    "label": undefined,
+    "source": "service:OrderService@2.0.0",
+    "target": "event:OrderCreated",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderCreated-routes-to-channel:OrderStream@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated",
+    "target": "channel:OrderStream@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:OrderService@2.0.0-sends-event:OrderConfirmed",
+    "label": undefined,
+    "source": "service:OrderService@2.0.0",
+    "target": "event:OrderConfirmed",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderConfirmed-routes-to-channel:OrderStream@1.0.0",
+    "label": undefined,
+    "source": "event:OrderConfirmed",
+    "target": "channel:OrderStream@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:OrderService@2.0.0-sends-event:OrderShipped",
+    "label": undefined,
+    "source": "service:OrderService@2.0.0",
+    "target": "event:OrderShipped",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderShipped-routes-to-channel:OrderStream@1.0.0",
+    "label": undefined,
+    "source": "event:OrderShipped",
+    "target": "channel:OrderStream@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:OrderService@2.0.0-sends-event:OrderCancelled",
+    "label": undefined,
+    "source": "service:OrderService@2.0.0",
+    "target": "event:OrderCancelled",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderCancelled-routes-to-channel:OrderStream@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCancelled",
+    "target": "channel:OrderStream@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:OrderService@2.0.0-sends-event:OrderCancelledV2",
+    "label": undefined,
+    "source": "service:OrderService@2.0.0",
+    "target": "event:OrderCancelledV2",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderCancelledV2-routes-to-channel:OrderStream@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCancelledV2",
+    "target": "channel:OrderStream@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "command:CreateOrder-receives-service:OrderService@2.0.0",
+    "label": "accepts",
+    "source": "command:CreateOrder",
+    "target": "service:OrderService@2.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "command:CancelOrder-receives-service:OrderService@2.0.0",
+    "label": "accepts",
+    "source": "command:CancelOrder",
+    "target": "service:OrderService@2.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "query:GetOrderStatus-receives-service:OrderService@2.0.0",
+    "label": "accepts",
+    "source": "query:GetOrderStatus",
+    "target": "service:OrderService@2.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentProcessed",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentProcessed",
+    "type": "sends",
+  },
+  {
+    "id": "event:PaymentProcessed-routes-to-channel:OrderStream@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed",
+    "target": "channel:OrderStream@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentFailed",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentFailed",
+    "type": "sends",
+  },
+  {
+    "id": "event:PaymentFailed-routes-to-channel:OrderStream@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentFailed",
+    "target": "channel:OrderStream@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:OrderStream@1.0.0-receives-service:PaymentService@1.0.0",
+    "label": undefined,
+    "source": "channel:OrderStream@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:InventoryService@1.0.0-sends-event:StockReserved",
+    "label": undefined,
+    "source": "service:InventoryService@1.0.0",
+    "target": "event:StockReserved",
+    "type": "sends",
+  },
+  {
+    "id": "event:StockReserved-routes-to-channel:OrderStream@1.0.0",
+    "label": undefined,
+    "source": "event:StockReserved",
+    "target": "channel:OrderStream@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:InventoryService@1.0.0-sends-event:StockUnavailable",
+    "label": undefined,
+    "source": "service:InventoryService@1.0.0",
+    "target": "event:StockUnavailable",
+    "type": "sends",
+  },
+  {
+    "id": "event:StockUnavailable-routes-to-channel:OrderStream@1.0.0",
+    "label": undefined,
+    "source": "event:StockUnavailable",
+    "target": "channel:OrderStream@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:OrderStream@1.0.0-receives-service:InventoryService@1.0.0",
+    "label": undefined,
+    "source": "channel:OrderStream@1.0.0",
+    "target": "service:InventoryService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:NotificationService@1.0.0-sends-event:NotificationSent",
+    "label": undefined,
+    "source": "service:NotificationService@1.0.0",
+    "target": "event:NotificationSent",
+    "type": "sends",
+  },
+  {
+    "id": "event:NotificationSent-routes-to-channel:NotificationQueue@1.0.0",
+    "label": undefined,
+    "source": "event:NotificationSent",
+    "target": "channel:NotificationQueue@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:OrderStream@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:OrderStream@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:LegacyOrderAdapter@1.0.0-sends-event:LegacyOrderCreated",
+    "label": undefined,
+    "source": "service:LegacyOrderAdapter@1.0.0",
+    "target": "event:LegacyOrderCreated",
+    "type": "sends",
+  },
+  {
+    "id": "event:LegacyOrderCreated-routes-to-channel:LegacyOrderQueue@1.0.0",
+    "label": undefined,
+    "source": "event:LegacyOrderCreated",
+    "target": "channel:LegacyOrderQueue@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:OrderStream@1.0.0-receives-service:LegacyOrderAdapter@1.0.0",
+    "label": undefined,
+    "source": "channel:OrderStream@1.0.0",
+    "target": "service:LegacyOrderAdapter@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "channel:OrderStream@1.0.0-receives-service:AnalyticsIngestion@1.0.0",
+    "label": undefined,
+    "source": "channel:OrderStream@1.0.0",
+    "target": "service:AnalyticsIngestion@1.0.0",
+    "type": "receives",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Order Service Showcase > Order Service Showcase - nodes 1`] = `
+[
+  {
+    "id": "channel:OrderStream@1.0.0",
+    "label": "OrderStream",
+    "metadata": {
+      "address": "orders.stream",
+      "deprecated": undefined,
+      "draft": undefined,
+      "notes": [
+        {
+          "author": "infra-team",
+          "content": "Partition key is orderId — 12 partitions",
+        },
+        {
+          "author": "infra-team",
+          "content": "Retention: 14 days",
+        },
+      ],
+      "protocols": [
+        "kafka",
+      ],
+      "summary": "Kafka topic for all order-related events",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "channel:NotificationQueue@1.0.0",
+    "label": "NotificationQueue",
+    "metadata": {
+      "address": "notifications.queue",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "rabbitmq",
+      ],
+      "summary": "RabbitMQ queue for notification delivery",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "channel:LegacyOrderQueue@1.0.0",
+    "label": "LegacyOrderQueue",
+    "metadata": {
+      "address": "legacy.orders",
+      "deprecated": undefined,
+      "draft": undefined,
+      "notes": [
+        {
+          "content": "No new consumers should connect to this queue",
+          "priority": "high",
+        },
+      ],
+      "protocols": [
+        "rabbitmq",
+      ],
+      "summary": "Legacy queue — being decommissioned",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "channel",
+  },
+  {
+    "id": "service:OrderService@2.0.0",
+    "label": "OrderService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "notes": [
+        {
+          "author": "alice",
+          "content": "v2 adds support for multi-currency orders",
+        },
+        {
+          "author": "bob",
+          "content": "Load test before Black Friday — target 5k req/s",
+          "priority": "high",
+        },
+        {
+          "author": "alice",
+          "content": "Migrating from REST to gRPC for internal calls",
+        },
+      ],
+      "summary": "Core service for managing the order lifecycle",
+      "version": "2.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:OrderCreated",
+    "label": "OrderCreated",
+    "metadata": {
+      "notes": [
+        {
+          "author": "alice",
+          "content": "Schema v2 adds shippingAddress field — deploy consumer updates first",
+        },
+      ],
+      "summary": "Emitted when a customer places a new order",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:OrderConfirmed",
+    "label": "OrderConfirmed",
+    "metadata": {
+      "summary": "Order confirmed after payment and stock checks",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:OrderShipped",
+    "label": "OrderShipped",
+    "metadata": {
+      "summary": "Order dispatched from the warehouse",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:OrderCancelled",
+    "label": "OrderCancelled",
+    "metadata": {
+      "deprecated": true,
+      "notes": [
+        {
+          "content": "Use OrderCancelledV2 instead — this lacks cancellation reason",
+          "priority": "high",
+        },
+      ],
+      "summary": "Order cancelled by customer or system",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:OrderCancelledV2",
+    "label": "OrderCancelledV2",
+    "metadata": {
+      "draft": true,
+      "notes": [
+        {
+          "author": "carol",
+          "content": "Rolling out to EU region first",
+        },
+      ],
+      "summary": "Order cancelled with structured reason codes",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "command:CreateOrder",
+    "label": "CreateOrder",
+    "metadata": {
+      "notes": [
+        {
+          "author": "bob",
+          "content": "Validate idempotency key before processing",
+          "priority": "high",
+        },
+      ],
+      "summary": "Place a new order",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "command:CancelOrder",
+    "label": "CancelOrder",
+    "metadata": {
+      "summary": "Request order cancellation",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "command",
+  },
+  {
+    "id": "query:GetOrderStatus",
+    "label": "GetOrderStatus",
+    "metadata": {
+      "draft": true,
+      "notes": [
+        {
+          "author": "alice",
+          "content": "Will replace polling with push notifications in v2",
+        },
+      ],
+      "summary": "Retrieve current order status",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "query",
+  },
+  {
+    "id": "service:PaymentService@1.0.0",
+    "label": "PaymentService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "notes": [
+        {
+          "author": "dave",
+          "content": "Integrates with Stripe and Adyen",
+        },
+      ],
+      "summary": "Processes payments and refunds",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:PaymentProcessed",
+    "label": "PaymentProcessed",
+    "metadata": {
+      "summary": "Payment completed successfully",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:PaymentFailed",
+    "label": "PaymentFailed",
+    "metadata": {
+      "summary": "Payment was declined or errored",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:InventoryService@1.0.0",
+    "label": "InventoryService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Manages stock levels and reservations",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:StockReserved",
+    "label": "StockReserved",
+    "metadata": {
+      "summary": "Inventory reserved for an order",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "event:StockUnavailable",
+    "label": "StockUnavailable",
+    "metadata": {
+      "summary": "Requested items are out of stock",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:NotificationService@1.0.0",
+    "label": "NotificationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends email, SMS, and push notifications",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:NotificationSent",
+    "label": "NotificationSent",
+    "metadata": {
+      "summary": "Notification delivered to customer",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:LegacyOrderAdapter@1.0.0",
+    "label": "LegacyOrderAdapter",
+    "metadata": {
+      "deprecated": true,
+      "draft": undefined,
+      "notes": [
+        {
+          "content": "Decommission by Q3 2026",
+          "priority": "high",
+        },
+        {
+          "author": "carol",
+          "content": "Only handles APAC region traffic",
+        },
+        {
+          "author": "bob",
+          "content": "See migration runbook: https://wiki.internal/legacy-orders",
+        },
+      ],
+      "summary": "Bridges events to the legacy order system",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:LegacyOrderCreated",
+    "label": "LegacyOrderCreated",
+    "metadata": {
+      "deprecated": true,
+      "summary": "Legacy format order event",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:AnalyticsIngestion@1.0.0",
+    "label": "AnalyticsIngestion",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": true,
+      "notes": [
+        {
+          "author": "dave",
+          "content": "Planned for Q2 2026 — depends on new Snowflake cluster",
+        },
+      ],
+      "summary": "Ingests order events into the data warehouse",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Payment Domain > Payment Domain - edges 1`] = `
+[
+  {
+    "id": "domain:Payment@1.0.0-contains-service:PaymentService@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentProcessed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentProcessed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-channel:PaymentEvents@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "channel:PaymentEvents@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0-routes-to-channel:PaymentEvents@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentProcessed@1.0.0",
+    "target": "channel:PaymentEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-event:PaymentFailed@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "event:PaymentFailed@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentFailed@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentFailed@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "event:PaymentFailed@1.0.0-routes-to-channel:PaymentEvents@1.0.0",
+    "label": undefined,
+    "source": "event:PaymentFailed@1.0.0",
+    "target": "channel:PaymentEvents@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-command:ProcessPayment@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "command:ProcessPayment@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-channel:PaymentCommands@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "channel:PaymentCommands@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:ProcessPayment@1.0.0-routes-to-channel:PaymentCommands@1.0.0",
+    "label": undefined,
+    "source": "command:ProcessPayment@1.0.0",
+    "target": "channel:PaymentCommands@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:PaymentCommands@1.0.0-receives-service:PaymentService@1.0.0",
+    "label": "accepts",
+    "source": "channel:PaymentCommands@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-reads-writes-container:PaymentsDB@1.0.0",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "container:PaymentsDB@1.0.0",
+    "type": "reads-writes",
+  },
+  {
+    "id": "domain:Payment@1.0.0-contains-container:PaymentsDB@1.0.0",
+    "label": undefined,
+    "source": "domain:Payment@1.0.0",
+    "target": "container:PaymentsDB@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:NotificationService@1.0.0-sends-event:NotificationSent@1.0.0",
+    "label": undefined,
+    "source": "service:NotificationService@1.0.0",
+    "target": "event:NotificationSent@1.0.0",
+    "type": "sends",
+  },
+  {
+    "id": "channel:PaymentEvents@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:PaymentEvents@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Payment Domain > Payment Domain - nodes 1`] = `
+[
+  {
+    "id": "channel:PaymentEvents@1.0.0",
+    "label": "PaymentEvents",
+    "metadata": {
+      "address": "payments.events",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "rabbitmq",
+      ],
+      "summary": "RabbitMQ exchange for payment events",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "channel:PaymentCommands@1.0.0",
+    "label": "PaymentCommands",
+    "metadata": {
+      "address": "payments.commands",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "http",
+      ],
+      "summary": "HTTP API for payment commands",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "domain:Payment@1.0.0",
+    "label": "Payment",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Handles all payment processing",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:PaymentService@1.0.0",
+    "label": "PaymentService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Processes payments and refunds",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:PaymentProcessed@1.0.0",
+    "label": "PaymentProcessed",
+    "metadata": {
+      "summary": "Emitted when a payment completes successfully",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:PaymentFailed@1.0.0",
+    "label": "PaymentFailed",
+    "metadata": {
+      "summary": "Emitted when a payment fails",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "command:ProcessPayment@1.0.0",
+    "label": "ProcessPayment",
+    "metadata": {
+      "summary": "Command to initiate payment processing",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "container:PaymentsDB@1.0.0",
+    "label": "PaymentsDB",
+    "metadata": {
+      "containerType": "database",
+      "summary": "Stores all payment transactions and state",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Payment@1.0.0",
+    "type": "container",
+  },
+  {
+    "id": "service:NotificationService@1.0.0",
+    "label": "NotificationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends notifications to users",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:NotificationSent@1.0.0",
+    "label": "NotificationSent",
+    "metadata": {
+      "summary": "Notification delivered to customer",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "event",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Planning Future Services > Planning Future Services - edges 1`] = `
+[
+  {
+    "id": "domain:Orders@1.0.0-contains-service:LegacyOrderService@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "service:LegacyOrderService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderCreated",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderCreated",
+    "type": "contains",
+  },
+  {
+    "id": "service:LegacyOrderService@1.0.0-sends-event:OrderCreated",
+    "label": undefined,
+    "source": "service:LegacyOrderService@1.0.0",
+    "target": "event:OrderCreated",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-channel:LegacyQueue@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "channel:LegacyQueue@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderCreated-routes-to-channel:LegacyQueue@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated",
+    "target": "channel:LegacyQueue@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderProcessed",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderProcessed",
+    "type": "contains",
+  },
+  {
+    "id": "service:LegacyOrderService@1.0.0-sends-event:OrderProcessed",
+    "label": undefined,
+    "source": "service:LegacyOrderService@1.0.0",
+    "target": "event:OrderProcessed",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderProcessed-routes-to-channel:LegacyQueue@1.0.0",
+    "label": undefined,
+    "source": "event:OrderProcessed",
+    "target": "channel:LegacyQueue@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-command:CreateOrder",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "command:CreateOrder",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-channel:RESTAPI@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "channel:RESTAPI@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "command:CreateOrder-routes-to-channel:RESTAPI@1.0.0",
+    "label": undefined,
+    "source": "command:CreateOrder",
+    "target": "channel:RESTAPI@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:RESTAPI@1.0.0-receives-service:LegacyOrderService@1.0.0",
+    "label": "accepts",
+    "source": "channel:RESTAPI@1.0.0",
+    "target": "service:LegacyOrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-service:OrderService@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderCreated",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderCreated",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-channel:EventBus@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "channel:EventBus@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderCreated-routes-to-channel:EventBus@1.0.0",
+    "label": undefined,
+    "source": "event:OrderCreated",
+    "target": "channel:EventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderValidated",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderValidated",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderValidated",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderValidated",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderValidated-routes-to-channel:EventBus@1.0.0",
+    "label": undefined,
+    "source": "event:OrderValidated",
+    "target": "channel:EventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-event:OrderSubmitted",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "event:OrderSubmitted",
+    "type": "contains",
+  },
+  {
+    "id": "service:OrderService@1.0.0-sends-event:OrderSubmitted",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "event:OrderSubmitted",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderSubmitted-routes-to-channel:EventBus@1.0.0",
+    "label": undefined,
+    "source": "event:OrderSubmitted",
+    "target": "channel:EventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:RESTAPI@1.0.0-receives-service:OrderService@1.0.0",
+    "label": "accepts",
+    "source": "channel:RESTAPI@1.0.0",
+    "target": "service:OrderService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-command:ValidateOrder",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "command:ValidateOrder",
+    "type": "contains",
+  },
+  {
+    "id": "command:ValidateOrder-routes-to-channel:RESTAPI@1.0.0",
+    "label": undefined,
+    "source": "command:ValidateOrder",
+    "target": "channel:RESTAPI@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:OrderService@1.0.0-reads-writes-container:OrdersDB@1.0.0",
+    "label": undefined,
+    "source": "service:OrderService@1.0.0",
+    "target": "container:OrdersDB@1.0.0",
+    "type": "reads-writes",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-service:OrderQueryService@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "service:OrderQueryService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:EventBus@1.0.0-receives-service:OrderQueryService@1.0.0",
+    "label": undefined,
+    "source": "channel:EventBus@1.0.0",
+    "target": "service:OrderQueryService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-query:GetOrder",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "query:GetOrder",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-channel:GraphQLAPI@1.0.0",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "channel:GraphQLAPI@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "query:GetOrder-routes-to-channel:GraphQLAPI@1.0.0",
+    "label": undefined,
+    "source": "query:GetOrder",
+    "target": "channel:GraphQLAPI@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:GraphQLAPI@1.0.0-receives-service:OrderQueryService@1.0.0",
+    "label": "accepts",
+    "source": "channel:GraphQLAPI@1.0.0",
+    "target": "service:OrderQueryService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Orders@1.0.0-contains-query:SearchOrders",
+    "label": undefined,
+    "source": "domain:Orders@1.0.0",
+    "target": "query:SearchOrders",
+    "type": "contains",
+  },
+  {
+    "id": "query:SearchOrders-routes-to-channel:GraphQLAPI@1.0.0",
+    "label": undefined,
+    "source": "query:SearchOrders",
+    "target": "channel:GraphQLAPI@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "service:OrderQueryService@1.0.0-reads-writes-container:OrderReadDB@1.0.0",
+    "label": undefined,
+    "source": "service:OrderQueryService@1.0.0",
+    "target": "container:OrderReadDB@1.0.0",
+    "type": "reads-writes",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-service:FulfillmentService@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "service:FulfillmentService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-event:OrderFulfilled",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "event:OrderFulfilled",
+    "type": "contains",
+  },
+  {
+    "id": "service:FulfillmentService@1.0.0-sends-event:OrderFulfilled",
+    "label": undefined,
+    "source": "service:FulfillmentService@1.0.0",
+    "target": "event:OrderFulfilled",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-channel:EventBus@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "channel:EventBus@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderFulfilled-routes-to-channel:EventBus@1.0.0",
+    "label": undefined,
+    "source": "event:OrderFulfilled",
+    "target": "channel:EventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-event:OrderShipped",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "event:OrderShipped",
+    "type": "contains",
+  },
+  {
+    "id": "service:FulfillmentService@1.0.0-sends-event:OrderShipped",
+    "label": undefined,
+    "source": "service:FulfillmentService@1.0.0",
+    "target": "event:OrderShipped",
+    "type": "sends",
+  },
+  {
+    "id": "event:OrderShipped-routes-to-channel:EventBus@1.0.0",
+    "label": undefined,
+    "source": "event:OrderShipped",
+    "target": "channel:EventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-event:OrderSubmitted",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "event:OrderSubmitted",
+    "type": "contains",
+  },
+  {
+    "id": "channel:EventBus@1.0.0-receives-service:FulfillmentService@1.0.0",
+    "label": undefined,
+    "source": "channel:EventBus@1.0.0",
+    "target": "service:FulfillmentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-service:InventoryReservationService@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "service:InventoryReservationService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-event:InventoryReserved",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "event:InventoryReserved",
+    "type": "contains",
+  },
+  {
+    "id": "service:InventoryReservationService@1.0.0-sends-event:InventoryReserved",
+    "label": undefined,
+    "source": "service:InventoryReservationService@1.0.0",
+    "target": "event:InventoryReserved",
+    "type": "sends",
+  },
+  {
+    "id": "event:InventoryReserved-routes-to-channel:EventBus@1.0.0",
+    "label": undefined,
+    "source": "event:InventoryReserved",
+    "target": "channel:EventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-event:InventoryUnavailable",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "event:InventoryUnavailable",
+    "type": "contains",
+  },
+  {
+    "id": "service:InventoryReservationService@1.0.0-sends-event:InventoryUnavailable",
+    "label": undefined,
+    "source": "service:InventoryReservationService@1.0.0",
+    "target": "event:InventoryUnavailable",
+    "type": "sends",
+  },
+  {
+    "id": "event:InventoryUnavailable-routes-to-channel:EventBus@1.0.0",
+    "label": undefined,
+    "source": "event:InventoryUnavailable",
+    "target": "channel:EventBus@1.0.0",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-event:OrderValidated",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "event:OrderValidated",
+    "type": "contains",
+  },
+  {
+    "id": "channel:EventBus@1.0.0-receives-service:InventoryReservationService@1.0.0",
+    "label": undefined,
+    "source": "channel:EventBus@1.0.0",
+    "target": "service:InventoryReservationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:InventoryReservationService@1.0.0-reads-writes-container:InventoryDB@1.0.0",
+    "label": undefined,
+    "source": "service:InventoryReservationService@1.0.0",
+    "target": "container:InventoryDB@1.0.0",
+    "type": "reads-writes",
+  },
+  {
+    "id": "service:NotificationService@1.0.0-sends-event:EmailSent",
+    "label": undefined,
+    "source": "service:NotificationService@1.0.0",
+    "target": "event:EmailSent",
+    "type": "sends",
+  },
+  {
+    "id": "channel:EventBus@1.0.0-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:EventBus@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "channel:EventBus@1.0.0-receives-service:AnalyticsService@1.0.0",
+    "label": undefined,
+    "source": "channel:EventBus@1.0.0",
+    "target": "service:AnalyticsService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "service:AnalyticsService@1.0.0-writes-to-container:AnalyticsDB@1.0.0",
+    "label": undefined,
+    "source": "service:AnalyticsService@1.0.0",
+    "target": "container:AnalyticsDB@1.0.0",
+    "type": "writes-to",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Planning Future Services > Planning Future Services - nodes 1`] = `
+[
+  {
+    "id": "channel:EventBus@1.0.0",
+    "label": "EventBus",
+    "metadata": {
+      "address": "events.stream",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "Kafka",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "channel:LegacyQueue@1.0.0",
+    "label": "LegacyQueue",
+    "metadata": {
+      "address": "legacy.queue",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "RabbitMQ",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "channel:RESTAPI@1.0.0",
+    "label": "RESTAPI",
+    "metadata": {
+      "address": "/api/v1",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "HTTP",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "channel:GraphQLAPI@1.0.0",
+    "label": "GraphQLAPI",
+    "metadata": {
+      "address": "/graphql",
+      "deprecated": undefined,
+      "draft": undefined,
+      "protocols": [
+        "HTTP",
+      ],
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "container:OrdersDB@1.0.0",
+    "label": "OrdersDB",
+    "metadata": {
+      "containerType": "database",
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Stores order data",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "container",
+  },
+  {
+    "id": "container:OrderReadDB@1.0.0",
+    "label": "OrderReadDB",
+    "metadata": {
+      "containerType": "database",
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Denormalized read model for fast queries",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "container",
+  },
+  {
+    "id": "container:InventoryDB@1.0.0",
+    "label": "InventoryDB",
+    "metadata": {
+      "containerType": "database",
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Tracks inventory levels",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "container",
+  },
+  {
+    "id": "container:AnalyticsDB@1.0.0",
+    "label": "AnalyticsDB",
+    "metadata": {
+      "containerType": "dataWarehouse",
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Data warehouse for analytics",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "container",
+  },
+  {
+    "id": "domain:Orders@1.0.0",
+    "label": "Orders",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Order management domain - currently being modernized",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:LegacyOrderService@1.0.0",
+    "label": "LegacyOrderService",
+    "metadata": {
+      "deprecated": true,
+      "draft": undefined,
+      "notes": [
+        {
+          "content": "Decommission by Q3 2026",
+          "priority": "high",
+        },
+        {
+          "content": "Migration guide: https://wiki.internal/legacy-migration",
+        },
+      ],
+      "summary": "Legacy monolithic order service - being phased out",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:OrderCreated",
+    "label": "OrderCreated",
+    "metadata": {},
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:OrderProcessed",
+    "label": "OrderProcessed",
+    "metadata": {},
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "command:CreateOrder",
+    "label": "CreateOrder",
+    "metadata": {},
+    "parentId": "domain:Orders@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "service:OrderService@1.0.0",
+    "label": "OrderService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "notes": [
+        {
+          "content": "Needs load testing before handling legacy traffic",
+        },
+      ],
+      "summary": "Modern order service - currently in production",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:OrderValidated",
+    "label": "OrderValidated",
+    "metadata": {},
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:OrderSubmitted",
+    "label": "OrderSubmitted",
+    "metadata": {},
+    "parentId": "domain:Orders@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "command:ValidateOrder",
+    "label": "ValidateOrder",
+    "metadata": {},
+    "parentId": "domain:Orders@1.0.0",
+    "type": "command",
+  },
+  {
+    "id": "service:OrderQueryService@1.0.0",
+    "label": "OrderQueryService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": true,
+      "summary": "Query service for order data - planned for Q2 2026",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Orders@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "query:GetOrder",
+    "label": "GetOrder",
+    "metadata": {},
+    "parentId": "domain:Orders@1.0.0",
+    "type": "query",
+  },
+  {
+    "id": "query:SearchOrders",
+    "label": "SearchOrders",
+    "metadata": {},
+    "parentId": "domain:Orders@1.0.0",
+    "type": "query",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0",
+    "label": "Fulfillment",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Order fulfillment and shipping",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:FulfillmentService@1.0.0",
+    "label": "FulfillmentService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Handles order fulfillment - currently in production",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:OrderFulfilled",
+    "label": "OrderFulfilled",
+    "metadata": {},
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:OrderShipped",
+    "label": "OrderShipped",
+    "metadata": {},
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "service:InventoryReservationService@1.0.0",
+    "label": "InventoryReservationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": true,
+      "summary": "Reserves inventory for orders - planned for Q3 2026",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:InventoryReserved",
+    "label": "InventoryReserved",
+    "metadata": {},
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "event:InventoryUnavailable",
+    "label": "InventoryUnavailable",
+    "metadata": {},
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "service:NotificationService@1.0.0",
+    "label": "NotificationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Sends customer notifications",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "event:EmailSent",
+    "label": "EmailSent",
+    "metadata": {},
+    "parentId": undefined,
+    "type": "event",
+  },
+  {
+    "id": "service:AnalyticsService@1.0.0",
+    "label": "AnalyticsService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": true,
+      "summary": "Real-time analytics and reporting - planned for Q2 2026",
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Sample Event-Driven System > Sample Event-Driven System - edges 1`] = `
+[
+  {
+    "id": "domain:Commerce@1.0.0-contains-service:CommerceOrchestrator@1.0.0",
+    "label": undefined,
+    "source": "domain:Commerce@1.0.0",
+    "target": "service:CommerceOrchestrator@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Commerce@1.0.0-contains-event:OrderPlaced",
+    "label": undefined,
+    "source": "domain:Commerce@1.0.0",
+    "target": "event:OrderPlaced",
+    "type": "contains",
+  },
+  {
+    "id": "service:CommerceOrchestrator@1.0.0-sends-event:OrderPlaced",
+    "label": undefined,
+    "source": "service:CommerceOrchestrator@1.0.0",
+    "target": "event:OrderPlaced",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Commerce@1.0.0-contains-channel:ordersRequested",
+    "label": undefined,
+    "source": "domain:Commerce@1.0.0",
+    "target": "channel:ordersRequested",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderPlaced-routes-to-channel:ordersRequested",
+    "label": undefined,
+    "source": "event:OrderPlaced",
+    "target": "channel:ordersRequested",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Commerce@1.0.0-contains-event:PaymentCaptured",
+    "label": undefined,
+    "source": "domain:Commerce@1.0.0",
+    "target": "event:PaymentCaptured",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Commerce@1.0.0-contains-channel:paymentsCaptured",
+    "label": undefined,
+    "source": "domain:Commerce@1.0.0",
+    "target": "channel:paymentsCaptured",
+    "type": "contains",
+  },
+  {
+    "id": "event:PaymentCaptured-routes-to-channel:paymentsCaptured",
+    "label": undefined,
+    "source": "event:PaymentCaptured",
+    "target": "channel:paymentsCaptured",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:paymentsCaptured-receives-service:CommerceOrchestrator@1.0.0",
+    "label": undefined,
+    "source": "channel:paymentsCaptured",
+    "target": "service:CommerceOrchestrator@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Commerce@1.0.0-contains-event:InventoryReserved",
+    "label": undefined,
+    "source": "domain:Commerce@1.0.0",
+    "target": "event:InventoryReserved",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Commerce@1.0.0-contains-channel:inventoryReserved",
+    "label": undefined,
+    "source": "domain:Commerce@1.0.0",
+    "target": "channel:inventoryReserved",
+    "type": "contains",
+  },
+  {
+    "id": "event:InventoryReserved-routes-to-channel:inventoryReserved",
+    "label": undefined,
+    "source": "event:InventoryReserved",
+    "target": "channel:inventoryReserved",
+    "type": "routes-to",
+  },
+  {
+    "id": "channel:inventoryReserved-receives-service:CommerceOrchestrator@1.0.0",
+    "label": undefined,
+    "source": "channel:inventoryReserved",
+    "target": "service:CommerceOrchestrator@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Commerce@1.0.0-contains-service:PaymentService@1.0.0",
+    "label": undefined,
+    "source": "domain:Commerce@1.0.0",
+    "target": "service:PaymentService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:PaymentService@1.0.0-sends-event:PaymentCaptured",
+    "label": undefined,
+    "source": "service:PaymentService@1.0.0",
+    "target": "event:PaymentCaptured",
+    "type": "sends",
+  },
+  {
+    "id": "channel:ordersRequested-receives-service:PaymentService@1.0.0",
+    "label": undefined,
+    "source": "channel:ordersRequested",
+    "target": "service:PaymentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Commerce@1.0.0-contains-service:InventoryService@1.0.0",
+    "label": undefined,
+    "source": "domain:Commerce@1.0.0",
+    "target": "service:InventoryService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "service:InventoryService@1.0.0-sends-event:InventoryReserved",
+    "label": undefined,
+    "source": "service:InventoryService@1.0.0",
+    "target": "event:InventoryReserved",
+    "type": "sends",
+  },
+  {
+    "id": "channel:ordersRequested-receives-service:InventoryService@1.0.0",
+    "label": undefined,
+    "source": "channel:ordersRequested",
+    "target": "service:InventoryService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-service:FulfillmentService@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "service:FulfillmentService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-event:OrderReadyForShipment",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "event:OrderReadyForShipment",
+    "type": "contains",
+  },
+  {
+    "id": "service:FulfillmentService@1.0.0-sends-event:OrderReadyForShipment",
+    "label": undefined,
+    "source": "service:FulfillmentService@1.0.0",
+    "target": "event:OrderReadyForShipment",
+    "type": "sends",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-channel:fulfillmentReady",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "channel:fulfillmentReady",
+    "type": "contains",
+  },
+  {
+    "id": "event:OrderReadyForShipment-routes-to-channel:fulfillmentReady",
+    "label": undefined,
+    "source": "event:OrderReadyForShipment",
+    "target": "channel:fulfillmentReady",
+    "type": "routes-to",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-event:PaymentCaptured",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "event:PaymentCaptured",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-channel:paymentsCaptured",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "channel:paymentsCaptured",
+    "type": "contains",
+  },
+  {
+    "id": "channel:paymentsCaptured-receives-service:FulfillmentService@1.0.0",
+    "label": undefined,
+    "source": "channel:paymentsCaptured",
+    "target": "service:FulfillmentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-event:InventoryReserved",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "event:InventoryReserved",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-channel:inventoryReserved",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "channel:inventoryReserved",
+    "type": "contains",
+  },
+  {
+    "id": "channel:inventoryReserved-receives-service:FulfillmentService@1.0.0",
+    "label": undefined,
+    "source": "channel:inventoryReserved",
+    "target": "service:FulfillmentService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "service:NotificationService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "channel:fulfillmentReady-receives-service:NotificationService@1.0.0",
+    "label": undefined,
+    "source": "channel:fulfillmentReady",
+    "target": "service:NotificationService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-service:AnalyticsService@1.0.0",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "service:AnalyticsService@1.0.0",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-event:OrderPlaced",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "event:OrderPlaced",
+    "type": "contains",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0-contains-channel:ordersRequested",
+    "label": undefined,
+    "source": "domain:Fulfillment@1.0.0",
+    "target": "channel:ordersRequested",
+    "type": "contains",
+  },
+  {
+    "id": "channel:ordersRequested-receives-service:AnalyticsService@1.0.0",
+    "label": undefined,
+    "source": "channel:ordersRequested",
+    "target": "service:AnalyticsService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "channel:paymentsCaptured-receives-service:AnalyticsService@1.0.0",
+    "label": undefined,
+    "source": "channel:paymentsCaptured",
+    "target": "service:AnalyticsService@1.0.0",
+    "type": "receives",
+  },
+  {
+    "id": "channel:fulfillmentReady-receives-service:AnalyticsService@1.0.0",
+    "label": undefined,
+    "source": "channel:fulfillmentReady",
+    "target": "service:AnalyticsService@1.0.0",
+    "type": "receives",
+  },
+]
+`;
+
+exports[`playground examples snapshot tests > Sample Event-Driven System > Sample Event-Driven System - nodes 1`] = `
+[
+  {
+    "id": "service:CheckoutApi",
+    "label": "CheckoutApi",
+    "metadata": {
+      "version": undefined,
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "service:CustomerApi",
+    "label": "CustomerApi",
+    "metadata": {
+      "version": undefined,
+    },
+    "parentId": undefined,
+    "type": "service",
+  },
+  {
+    "id": "domain:Commerce@1.0.0",
+    "label": "Commerce",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:CommerceOrchestrator@1.0.0",
+    "label": "CommerceOrchestrator",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Coordinates checkout workflow across domains",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Commerce@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:OrderPlaced",
+    "label": "OrderPlaced",
+    "metadata": {},
+    "parentId": "domain:Commerce@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "channel:ordersRequested",
+    "label": "ordersRequested",
+    "metadata": {},
+    "parentId": "domain:Commerce@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "event:PaymentCaptured",
+    "label": "PaymentCaptured",
+    "metadata": {},
+    "parentId": "domain:Commerce@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "channel:paymentsCaptured",
+    "label": "paymentsCaptured",
+    "metadata": {},
+    "parentId": "domain:Commerce@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "event:InventoryReserved",
+    "label": "InventoryReserved",
+    "metadata": {},
+    "parentId": "domain:Commerce@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "channel:inventoryReserved",
+    "label": "inventoryReserved",
+    "metadata": {},
+    "parentId": "domain:Commerce@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "service:PaymentService@1.0.0",
+    "label": "PaymentService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Captures payments and emits outcomes",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Commerce@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "service:InventoryService@1.0.0",
+    "label": "InventoryService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Reserves stock and reports availability",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Commerce@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "domain:Fulfillment@1.0.0",
+    "label": "Fulfillment",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": undefined,
+      "version": "1.0.0",
+    },
+    "parentId": undefined,
+    "type": "domain",
+  },
+  {
+    "id": "service:FulfillmentService@1.0.0",
+    "label": "FulfillmentService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Plans shipment after payment and inventory are confirmed",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "event:OrderReadyForShipment",
+    "label": "OrderReadyForShipment",
+    "metadata": {},
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "event",
+  },
+  {
+    "id": "channel:fulfillmentReady",
+    "label": "fulfillmentReady",
+    "metadata": {},
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "channel",
+  },
+  {
+    "id": "service:NotificationService@1.0.0",
+    "label": "NotificationService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Notifies customers with order status updates",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "service",
+  },
+  {
+    "id": "service:AnalyticsService@1.0.0",
+    "label": "AnalyticsService",
+    "metadata": {
+      "deprecated": undefined,
+      "draft": undefined,
+      "summary": "Builds operational dashboards from lifecycle events",
+      "version": "1.0.0",
+    },
+    "parentId": "domain:Fulfillment@1.0.0",
+    "type": "service",
+  },
+]
+`;
diff --git a/packages/language-server/test/compiler.test.ts b/packages/language-server/test/compiler.test.ts
new file mode 100644
index 000000000..6b5a0bd52
--- /dev/null
+++ b/packages/language-server/test/compiler.test.ts
@@ -0,0 +1,473 @@
+import { describe, it, expect } from "vitest";
+import { createEcServices } from "../src/ec-module.js";
+import { EmptyFileSystem } from "langium";
+import { parseDocument } from "langium/test";
+import type { Program } from "../src/generated/ast.js";
+import { compile } from "../src/compiler.js";
+
+const services = createEcServices(EmptyFileSystem);
+
+async function parseProgram(input: string): Promise<Program> {
+  const doc = await parseDocument<Program>(services.Ec, input);
+  expect(doc.parseResult.parserErrors).toHaveLength(0);
+  return doc.parseResult.value;
+}
+
+describe("compile", () => {
+  it("compiles a domain with version and owner", async () => {
+    const program = await parseProgram(`
+      domain Orders {
+        version 1.0.0
+        name "Orders Domain"
+        summary "Handles all order operations"
+        owner orders-team
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const domainOutput = outputs.find(
+      (o) => o.path === "domains/Orders/versioned/1.0.0/index.md",
+    );
+    expect(domainOutput).toBeDefined();
+    expect(domainOutput!.content).toContain('id: "Orders"');
+    expect(domainOutput!.content).toContain('version: "1.0.0"');
+    expect(domainOutput!.content).toContain("orders-team");
+  });
+
+  it("compiles a domain with services listed in frontmatter", async () => {
+    const program = await parseProgram(`
+      domain Orders {
+        version 1.0.0
+        name "Orders Domain"
+        service OrderService {
+          version 2.0.0
+        }
+        service InventoryService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const domainOutput = outputs.find(
+      (o) => o.path === "domains/Orders/versioned/1.0.0/index.md",
+    );
+    expect(domainOutput).toBeDefined();
+    expect(domainOutput!.content).toContain("services:");
+    expect(domainOutput!.content).toContain('id: "OrderService"');
+    expect(domainOutput!.content).toContain('version: "2.0.0"');
+    expect(domainOutput!.content).toContain('id: "InventoryService"');
+    expect(domainOutput!.content).toContain('version: "1.0.0"');
+  });
+
+  it("compiles a domain with subdomains listed in frontmatter", async () => {
+    const program = await parseProgram(`
+      domain Ecommerce {
+        version 1.0.0
+        subdomain Payments {
+          version 1.0.0
+          service PaymentService {
+            version 1.0.0
+          }
+        }
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const domainOutput = outputs.find(
+      (o) => o.path === "domains/Ecommerce/versioned/1.0.0/index.md",
+    );
+    expect(domainOutput).toBeDefined();
+    // Subdomains are listed as "domains" in frontmatter
+    expect(domainOutput!.content).toContain("domains:");
+    expect(domainOutput!.content).toContain('id: "Payments"');
+
+    // Subdomain should list its services
+    const subdomainOutput = outputs.find((o) =>
+      o.path.includes("Payments/versioned/1.0.0/index.md"),
+    );
+    expect(subdomainOutput).toBeDefined();
+    expect(subdomainOutput!.content).toContain("services:");
+    expect(subdomainOutput!.content).toContain('id: "PaymentService"');
+  });
+
+  it("compiles a service with sends and receives", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        sends event OrderCreated
+        receives command PlaceOrder
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const svcOutput = outputs.find(
+      (o) => o.path === "services/OrderService/versioned/1.0.0/index.md",
+    );
+    expect(svcOutput).toBeDefined();
+    expect(svcOutput!.content).toContain("sends:");
+    expect(svcOutput!.content).toContain("OrderCreated");
+    expect(svcOutput!.content).toContain("receives:");
+    expect(svcOutput!.content).toContain("PlaceOrder");
+  });
+
+  it("compiles a service with writes-to and reads-from container refs", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        writes-to container orders-db@2.0.0
+        reads-from container orders-cache
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const svcOutput = outputs.find(
+      (o) => o.path === "services/OrderService/versioned/1.0.0/index.md",
+    );
+    expect(svcOutput).toBeDefined();
+    expect(svcOutput!.content).toContain("writesTo:");
+    expect(svcOutput!.content).toContain('id: "orders-db"');
+    expect(svcOutput!.content).toContain('version: "2.0.0"');
+    expect(svcOutput!.content).toContain("readsFrom:");
+    expect(svcOutput!.content).toContain('id: "orders-cache"');
+  });
+
+  it("compiles a standalone event", async () => {
+    const program = await parseProgram(`
+      event OrderCreated {
+        version 1.0.0
+        name "Order Created"
+        summary "Emitted when an order is placed"
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const eventOutput = outputs.find(
+      (o) => o.path === "events/OrderCreated/versioned/1.0.0/index.md",
+    );
+    expect(eventOutput).toBeDefined();
+    expect(eventOutput!.content).toContain('id: "OrderCreated"');
+    expect(eventOutput!.content).toContain('name: "Order Created"');
+    expect(eventOutput!.content).toContain('version: "1.0.0"');
+  });
+
+  it("compiles inline messages into separate output files", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        sends event OrderCreated {
+          version 1.0.0
+          summary "A new order was placed"
+        }
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const svcOutput = outputs.find(
+      (o) => o.path === "services/OrderService/versioned/1.0.0/index.md",
+    );
+    expect(svcOutput).toBeDefined();
+
+    const eventOutput = outputs.find(
+      (o) => o.path === "events/OrderCreated/versioned/1.0.0/index.md",
+    );
+    expect(eventOutput).toBeDefined();
+    expect(eventOutput!.content).toContain('id: "OrderCreated"');
+  });
+
+  it("compiles @badge annotation into badges array", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        @badge("Core", bg: "#3b82f6", text: "#fff", url: "/domains/Payments")
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const svcOutput = outputs.find(
+      (o) => o.path === "services/OrderService/versioned/1.0.0/index.md",
+    );
+    expect(svcOutput).toBeDefined();
+    expect(svcOutput!.content).toContain("badges:");
+    expect(svcOutput!.content).toContain('content: "Core"');
+    expect(svcOutput!.content).toContain('backgroundColor: "#3b82f6"');
+    expect(svcOutput!.content).toContain('textColor: "#fff"');
+    expect(svcOutput!.content).toContain('url: "/domains/Payments"');
+  });
+
+  it("compiles @note annotation into notes array", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        @note("Come back later")
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const svcOutput = outputs.find(
+      (o) => o.path === "services/OrderService/versioned/1.0.0/index.md",
+    );
+    expect(svcOutput).toBeDefined();
+    expect(svcOutput!.content).toContain("notes:");
+    expect(svcOutput!.content).toContain('content: "Come back later"');
+  });
+
+  it("compiles multiple @note annotations", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        @note("First note")
+        @note("Second note", author: "dboyne", priority: "high")
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const svcOutput = outputs.find(
+      (o) => o.path === "services/OrderService/versioned/1.0.0/index.md",
+    );
+    expect(svcOutput).toBeDefined();
+    expect(svcOutput!.content).toContain('content: "First note"');
+    expect(svcOutput!.content).toContain('content: "Second note"');
+    expect(svcOutput!.content).toContain('author: "dboyne"');
+    expect(svcOutput!.content).toContain('priority: "high"');
+  });
+
+  it("compiles @note on event resource", async () => {
+    const program = await parseProgram(`
+      event OrderCreated {
+        version 1.0.0
+        @note("Needs schema review")
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const eventOutput = outputs.find(
+      (o) => o.path === "events/OrderCreated/versioned/1.0.0/index.md",
+    );
+    expect(eventOutput).toBeDefined();
+    expect(eventOutput!.content).toContain("notes:");
+    expect(eventOutput!.content).toContain('content: "Needs schema review"');
+  });
+
+  it("compiles @repository annotation", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        @repository(url: "https://github.com/org/repo", language: "TypeScript")
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const svcOutput = outputs.find(
+      (o) => o.path === "services/OrderService/versioned/1.0.0/index.md",
+    );
+    expect(svcOutput).toBeDefined();
+    expect(svcOutput!.content).toContain("repository:");
+    expect(svcOutput!.content).toContain('url: "https://github.com/org/repo"');
+    expect(svcOutput!.content).toContain('language: "TypeScript"');
+  });
+
+  it("compiles a channel with address and protocols", async () => {
+    const program = await parseProgram(`
+      channel orders-topic {
+        version 1.0.0
+        name "Orders Topic"
+        address "orders/events"
+        protocol "Kafka"
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const channelOutput = outputs.find(
+      (o) => o.path === "channels/orders-topic/versioned/1.0.0/index.md",
+    );
+    expect(channelOutput).toBeDefined();
+    expect(channelOutput!.content).toContain('address: "orders/events"');
+    expect(channelOutput!.content).toContain("protocols:");
+    expect(channelOutput!.content).toContain("Kafka");
+  });
+
+  it("compiles a container using container_type and access_mode frontmatter keys", async () => {
+    const program = await parseProgram(`
+      container PaymentsDB {
+        version 1.0.0
+        container-type database
+        technology "PostgreSQL 15"
+        access-mode readWrite
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const containerOutput = outputs.find(
+      (o) => o.path === "containers/PaymentsDB/versioned/1.0.0/index.md",
+    );
+    expect(containerOutput).toBeDefined();
+    expect(containerOutput!.content).toContain('container_type: "database"');
+    expect(containerOutput!.content).toContain('access_mode: "readWrite"');
+    expect(containerOutput!.content).not.toContain("containerType:");
+    expect(containerOutput!.content).not.toContain("accessMode:");
+  });
+
+  it("compiles a user", async () => {
+    const program = await parseProgram(`
+      user dboyne {
+        name "David Boyne"
+        role "Principal Engineer"
+        email "david@example.com"
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const userOutput = outputs.find((o) => o.path === "users/dboyne.md");
+    expect(userOutput).toBeDefined();
+    expect(userOutput!.content).toContain('id: "dboyne"');
+    expect(userOutput!.content).toContain('name: "David Boyne"');
+    expect(userOutput!.content).toContain('role: "Principal Engineer"');
+    expect(userOutput!.content).toContain('email: "david@example.com"');
+  });
+
+  it("compiles a team with members", async () => {
+    const program = await parseProgram(`
+      team orders-team {
+        name "Orders Team"
+        summary "Handles order processing"
+        email "orders@company.com"
+        member dboyne
+        member jane-doe
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const teamOutput = outputs.find((o) => o.path === "teams/orders-team.md");
+    expect(teamOutput).toBeDefined();
+    expect(teamOutput!.content).toContain("members:");
+    expect(teamOutput!.content).toContain("dboyne");
+    expect(teamOutput!.content).toContain("jane-doe");
+  });
+
+  it("compiles a flow with when blocks", async () => {
+    const program = await parseProgram(`
+      flow OrderFulfillment {
+        version 1.0.0
+        name "Order Fulfillment"
+        summary "End-to-end order fulfillment"
+
+        Customer "places an order" -> PlaceOrder -> OrderService -> OrderCreated
+
+        when OrderCreated
+          PaymentService "processes the payment"
+            -> "success": PaymentProcessed
+            -> "failure": PaymentFailed
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const flowOutput = outputs.find(
+      (o) => o.path === "flows/OrderFulfillment/versioned/1.0.0/index.md",
+    );
+    expect(flowOutput).toBeDefined();
+    expect(flowOutput!.content).toContain("steps:");
+    expect(flowOutput!.content).toContain('id: "Customer"');
+    expect(flowOutput!.content).toContain('id: "PlaceOrder"');
+    expect(flowOutput!.content).toContain('id: "OrderService"');
+    expect(flowOutput!.content).toContain('id: "OrderCreated"');
+    expect(flowOutput!.content).toContain('id: "PaymentService"');
+    expect(flowOutput!.content).toContain("success");
+    expect(flowOutput!.content).toContain("failure");
+  });
+
+  it("compiles command and query into separate directories", async () => {
+    const program = await parseProgram(`
+      command PlaceOrder {
+        version 1.0.0
+        summary "Places a new order"
+      }
+
+      query GetOrder {
+        version 1.0.0
+        summary "Retrieves order details"
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const commandOutput = outputs.find(
+      (o) => o.path === "commands/PlaceOrder/versioned/1.0.0/index.md",
+    );
+    expect(commandOutput).toBeDefined();
+    expect(commandOutput!.content).toContain('id: "PlaceOrder"');
+
+    const queryOutput = outputs.find(
+      (o) => o.path === "queries/GetOrder/versioned/1.0.0/index.md",
+    );
+    expect(queryOutput).toBeDefined();
+    expect(queryOutput!.content).toContain('id: "GetOrder"');
+  });
+
+  it("visualizer wrapper does NOT produce its own markdown", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          summary "Manages orders"
+        }
+      }
+    `);
+
+    const outputs = compile(program);
+
+    // The service inside should compile
+    const serviceOutput = outputs.find(
+      (o) => o.path === "services/OrderService/versioned/1.0.0/index.md",
+    );
+    expect(serviceOutput).toBeDefined();
+
+    // No output for the visualizer itself
+    const vizOutput = outputs.find((o) => o.path.includes("visualizer"));
+    expect(vizOutput).toBeUndefined();
+  });
+
+  it("inline definitions inside visualizer compile normally", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service PaymentService {
+          version 1.0.0
+          sends event PaymentProcessed {
+            version 1.0.0
+            summary "Payment completed"
+          }
+        }
+      }
+    `);
+
+    const outputs = compile(program);
+
+    const serviceOutput = outputs.find(
+      (o) => o.path === "services/PaymentService/versioned/1.0.0/index.md",
+    );
+    expect(serviceOutput).toBeDefined();
+
+    const eventOutput = outputs.find(
+      (o) => o.path === "events/PaymentProcessed/versioned/1.0.0/index.md",
+    );
+    expect(eventOutput).toBeDefined();
+    expect(eventOutput!.content).toContain("Payment completed");
+  });
+});
diff --git a/packages/language-server/test/completion-utils.test.ts b/packages/language-server/test/completion-utils.test.ts
new file mode 100644
index 000000000..485c7ee17
--- /dev/null
+++ b/packages/language-server/test/completion-utils.test.ts
@@ -0,0 +1,151 @@
+import { describe, it, expect } from "vitest";
+import {
+  findEnclosingResource,
+  extractResourceNamesFromText,
+} from "../src/completion-utils.js";
+
+describe("findEnclosingResource", () => {
+  it("returns null at top level", () => {
+    const text = ``;
+    expect(findEnclosingResource(text)).toBe(null);
+  });
+
+  it("returns 'visualizer' inside a visualizer block", () => {
+    const text = `visualizer main {
+  name "Test"
+  `;
+    expect(findEnclosingResource(text)).toBe("visualizer");
+  });
+
+  it("returns 'service' inside a top-level service block", () => {
+    const text = `visualizer main {
+  name "Test"
+  service Foo {
+    version 1.0.0
+    `;
+    expect(findEnclosingResource(text)).toBe("service");
+  });
+
+  it("returns 'domain' inside a domain block", () => {
+    const text = `visualizer main {
+  name "Test"
+  domain MyDomain {
+    version 1.0.0
+    `;
+    expect(findEnclosingResource(text)).toBe("domain");
+  });
+
+  it("returns 'service' inside a service nested in a domain", () => {
+    const text = `visualizer main {
+  name "Test"
+  domain HelloWorld {
+    version 1.0.0
+    summary "Bounded context responsible for HelloWorld"
+    service MyService {
+      version 1.0.0
+      `;
+    expect(findEnclosingResource(text)).toBe("service");
+  });
+
+  it("returns 'event' inside an event nested in a domain", () => {
+    const text = `visualizer main {
+  name "Test"
+  domain HelloWorld {
+    version 1.0.0
+    event OrderCreated {
+      version 1.0.0
+      `;
+    expect(findEnclosingResource(text)).toBe("event");
+  });
+
+  it("returns 'service' inside a service nested in a domain inside a visualizer", () => {
+    const text = `visualizer main {
+  name "View Name"
+  service Name {
+    version 1.0.0
+    summary "Service that manages and processes Name operations"
+  }
+  domain HelloWorld {
+    version 1.0.0
+    summary "Bounded context responsible for HelloWorld"
+    service MyService {
+      version 1.0.0
+      `;
+    expect(findEnclosingResource(text)).toBe("service");
+  });
+
+  it("handles sends/receives blocks correctly", () => {
+    const text = `visualizer main {
+  name "Test"
+  service Foo {
+    version 1.0.0
+    sends { event Bar }
+    `;
+    expect(findEnclosingResource(text)).toBe("service");
+  });
+
+  it("returns 'domain' after closing a nested service", () => {
+    const text = `visualizer main {
+  name "Test"
+  domain HelloWorld {
+    version 1.0.0
+    service MyService {
+      version 1.0.0
+    }
+    `;
+    expect(findEnclosingResource(text)).toBe("domain");
+  });
+});
+
+describe("extractResourceNamesFromText", () => {
+  it("extracts service names", () => {
+    const text = `service OrderService { version 1.0.0 }`;
+    expect(extractResourceNamesFromText(text)).toEqual(
+      new Set(["OrderService"]),
+    );
+  });
+
+  it("extracts multiple resource types", () => {
+    const text = `
+      service OrderService { version 1.0.0 }
+      event OrderCreated { version 1.0.0 }
+      actor User { name "User" }
+    `;
+    const names = extractResourceNamesFromText(text);
+    expect(names).toContain("OrderService");
+    expect(names).toContain("OrderCreated");
+    expect(names).toContain("User");
+  });
+
+  it("only extracts from the given text, not other files", () => {
+    const actorsFile = `
+      actor Admin { name "Admin" }
+      actor User { name "User" }
+    `;
+    const servicesFile = `
+      service OrderService { version 1.0.0 }
+      service PaymentService { version 1.0.0 }
+    `;
+    const actorNames = extractResourceNamesFromText(actorsFile);
+    expect(actorNames).toContain("Admin");
+    expect(actorNames).toContain("User");
+    expect(actorNames).not.toContain("OrderService");
+    expect(actorNames).not.toContain("PaymentService");
+
+    const serviceNames = extractResourceNamesFromText(servicesFile);
+    expect(serviceNames).toContain("OrderService");
+    expect(serviceNames).toContain("PaymentService");
+    expect(serviceNames).not.toContain("Admin");
+    expect(serviceNames).not.toContain("User");
+  });
+
+  it("extracts external-system and data-product names", () => {
+    const text = `
+      external-system Stripe { name "Stripe" }
+      data-product Analytics { version 1.0.0 }
+    `;
+    const names = extractResourceNamesFromText(text);
+    expect(names).toContain("Stripe");
+    expect(names).toContain("Analytics");
+  });
+});
diff --git a/packages/language-server/test/examples-snapshot.test.ts b/packages/language-server/test/examples-snapshot.test.ts
new file mode 100644
index 000000000..474794522
--- /dev/null
+++ b/packages/language-server/test/examples-snapshot.test.ts
@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { createEcServices } from "../src/ec-module.js";
+import { EmptyFileSystem } from "langium";
+import { parseDocument } from "langium/test";
+import type { Program } from "../src/generated/ast.js";
+import { astToGraph } from "../src/graph.js";
+import { examples } from "../../playground/src/examples/index.js";
+
+const services = createEcServices(EmptyFileSystem);
+
+const LOCAL_IMPORT_RE =
+  /import\s*\{[^}]*\}\s*from\s*"(?!https?:\/\/)([^"]+)"\s*\n?/g;
+
+function combineSourceFiles(source: Record<string, string>): string {
+  const mainFile = "main.ec";
+  const supportingFiles = Object.keys(source).filter((f) => f !== mainFile);
+  const concatOrder = [...supportingFiles, mainFile];
+
+  const parts: string[] = [];
+  for (const filename of concatOrder) {
+    let content = source[filename];
+    // Strip local file imports since we're concatenating all files
+    content = content.replace(LOCAL_IMPORT_RE, "");
+    parts.push(content);
+  }
+
+  return parts.join("\n");
+}
+
+function hasRemoteImports(source: Record<string, string>): boolean {
+  const urlImportRe = /import\s*\{[^}]*\}\s*from\s*"(https?:\/\/[^"]+)"/;
+  return Object.values(source).some((content) => urlImportRe.test(content));
+}
+
+async function parseProgram(input: string): Promise<Program> {
+  const doc = await parseDocument<Program>(services.Ec, input);
+  return doc.parseResult.value;
+}
+
+describe("playground examples snapshot tests", () => {
+  for (const example of examples) {
+    if (hasRemoteImports(example.source)) {
+      it.skip(`${example.name} (skipped: remote URL imports)`, () => {});
+      continue;
+    }
+
+    it(`${example.name}`, async () => {
+      const combined = combineSourceFiles(example.source);
+      const program = await parseProgram(combined);
+      const graph = astToGraph(program);
+
+      // Snapshot nodes and edges separately for clearer diffs
+      expect(graph.nodes).toMatchSnapshot(`${example.name} - nodes`);
+      expect(graph.edges).toMatchSnapshot(`${example.name} - edges`);
+    });
+  }
+});
diff --git a/packages/language-server/test/fixtures/test-catalog/channels/order-events/index.mdx b/packages/language-server/test/fixtures/test-catalog/channels/order-events/index.mdx
new file mode 100644
index 000000000..975c1ce91
--- /dev/null
+++ b/packages/language-server/test/fixtures/test-catalog/channels/order-events/index.mdx
@@ -0,0 +1,11 @@
+---
+id: order-events
+name: Order Events
+version: 1.0.0
+summary: EventBus for order domain events
+address: orders.events
+protocols:
+  - kafka
+---
+
+Channel for all order-related domain events.
diff --git a/packages/language-server/test/fixtures/test-catalog/channels/payment-queue/index.mdx b/packages/language-server/test/fixtures/test-catalog/channels/payment-queue/index.mdx
new file mode 100644
index 000000000..9de30369a
--- /dev/null
+++ b/packages/language-server/test/fixtures/test-catalog/channels/payment-queue/index.mdx
@@ -0,0 +1,11 @@
+---
+id: payment-queue
+name: Payment Queue
+version: 2.0.0
+summary: SQS queue for payment processing
+address: payments.queue
+protocols:
+  - sqs
+---
+
+Queue for processing payment commands.
diff --git a/packages/language-server/test/fixtures/test-catalog/containers/order-cache/index.mdx b/packages/language-server/test/fixtures/test-catalog/containers/order-cache/index.mdx
new file mode 100644
index 000000000..97a464789
--- /dev/null
+++ b/packages/language-server/test/fixtures/test-catalog/containers/order-cache/index.mdx
@@ -0,0 +1,9 @@
+---
+id: order-cache
+name: Order Cache
+version: 2.0.0
+container_type: cache
+summary: Redis cache for order lookups
+---
+
+Order Cache provides fast lookups for recent orders.
diff --git a/packages/language-server/test/fixtures/test-catalog/containers/payments-db/index.mdx b/packages/language-server/test/fixtures/test-catalog/containers/payments-db/index.mdx
new file mode 100644
index 000000000..f713bc3d0
--- /dev/null
+++ b/packages/language-server/test/fixtures/test-catalog/containers/payments-db/index.mdx
@@ -0,0 +1,9 @@
+---
+id: payments-db
+name: Payments DB
+version: 1.0.0
+container_type: database
+summary: Primary database for payment transactions
+---
+
+Payments DB stores all payment transaction records.
diff --git a/packages/language-server/test/fixtures/test-catalog/events/OrderCancelled/index.mdx b/packages/language-server/test/fixtures/test-catalog/events/OrderCancelled/index.mdx
new file mode 100644
index 000000000..d1008ae66
--- /dev/null
+++ b/packages/language-server/test/fixtures/test-catalog/events/OrderCancelled/index.mdx
@@ -0,0 +1,10 @@
+---
+id: OrderCancelled
+name: Order Cancelled
+version: 1.5.0
+summary: Fired when an order is cancelled
+---
+
+## Overview
+
+The OrderCancelled event is fired when a customer cancels their order.
diff --git a/packages/language-server/test/fixtures/test-catalog/events/OrderCancelled/versioned/0.0.1/index.mdx b/packages/language-server/test/fixtures/test-catalog/events/OrderCancelled/versioned/0.0.1/index.mdx
new file mode 100644
index 000000000..ac03f83a5
--- /dev/null
+++ b/packages/language-server/test/fixtures/test-catalog/events/OrderCancelled/versioned/0.0.1/index.mdx
@@ -0,0 +1,10 @@
+---
+id: OrderCancelled
+name: Order Cancelled
+version: 0.0.1
+summary: Old version of order cancelled event
+---
+
+## Overview
+
+Legacy version.
diff --git a/packages/language-server/test/fixtures/test-catalog/events/OrderCreated/index.mdx b/packages/language-server/test/fixtures/test-catalog/events/OrderCreated/index.mdx
new file mode 100644
index 000000000..f33575ef7
--- /dev/null
+++ b/packages/language-server/test/fixtures/test-catalog/events/OrderCreated/index.mdx
@@ -0,0 +1,12 @@
+---
+id: OrderCreated
+name: Order Created
+version: 1.0.0
+summary: Fired when a new order is placed by a customer
+owners:
+  - dboyne
+---
+
+## Overview
+
+The OrderCreated event is fired when a new order is placed.
diff --git a/packages/language-server/test/fixtures/test-catalog/events/OrderShipped/index.mdx b/packages/language-server/test/fixtures/test-catalog/events/OrderShipped/index.mdx
new file mode 100644
index 000000000..52eec657c
--- /dev/null
+++ b/packages/language-server/test/fixtures/test-catalog/events/OrderShipped/index.mdx
@@ -0,0 +1,10 @@
+---
+id: OrderShipped
+name: Order Shipped
+version: 2.0.0
+summary: Fired when an order has been shipped
+---
+
+## Overview
+
+The OrderShipped event is fired when an order ships.
diff --git a/packages/language-server/test/fixtures/test-catalog/services/OrderService/index.mdx b/packages/language-server/test/fixtures/test-catalog/services/OrderService/index.mdx
new file mode 100644
index 000000000..71b95de46
--- /dev/null
+++ b/packages/language-server/test/fixtures/test-catalog/services/OrderService/index.mdx
@@ -0,0 +1,18 @@
+---
+id: OrderService
+name: Order Service
+version: 1.0.0
+summary: Manages order lifecycle
+sends:
+  - id: OrderCreated
+    version: 1.0.0
+  - id: OrderShipped
+    version: 2.0.0
+receives:
+  - id: OrderCancelled
+    version: 1.5.0
+---
+
+## Overview
+
+The Order Service handles order creation, shipping, and cancellation.
diff --git a/packages/language-server/test/formatter.test.ts b/packages/language-server/test/formatter.test.ts
new file mode 100644
index 000000000..c1f4aeb8e
--- /dev/null
+++ b/packages/language-server/test/formatter.test.ts
@@ -0,0 +1,196 @@
+import { describe, it, expect } from "vitest";
+import { formatEc } from "../src/formatter.js";
+
+describe("formatEc", () => {
+  it("indents nested blocks with 2 spaces", () => {
+    const input = `service OrderService {
+version "1.0.0"
+summary "Handles orders"
+}`;
+    const expected = `service OrderService {
+  version "1.0.0"
+  summary "Handles orders"
+}
+`;
+    expect(formatEc(input)).toBe(expected);
+  });
+
+  it("handles deeply nested blocks", () => {
+    const input = `domain Retail {
+service OrderService {
+version "1.0.0"
+sends {
+event OrderPlaced {
+version "1.0.0"
+}
+}
+}
+}`;
+    const expected = `domain Retail {
+  service OrderService {
+    version "1.0.0"
+    sends {
+      event OrderPlaced {
+        version "1.0.0"
+      }
+    }
+  }
+}
+`;
+    expect(formatEc(input)).toBe(expected);
+  });
+
+  it("collapses multiple blank lines into one", () => {
+    const input = `service A {
+  version "1.0.0"
+
+
+
+  summary "test"
+}`;
+    const expected = `service A {
+  version "1.0.0"
+
+  summary "test"
+}
+`;
+    expect(formatEc(input)).toBe(expected);
+  });
+
+  it("trims trailing whitespace", () => {
+    const input = `service A {
+  version "1.0.0"
+}   `;
+    const expected = `service A {
+  version "1.0.0"
+}
+`;
+    expect(formatEc(input)).toBe(expected);
+  });
+
+  it("preserves line comments", () => {
+    const input = `// This is a service
+service A {
+// version
+version "1.0.0"
+}`;
+    const expected = `// This is a service
+service A {
+  // version
+  version "1.0.0"
+}
+`;
+    expect(formatEc(input)).toBe(expected);
+  });
+
+  it("preserves block comments", () => {
+    const input = `/* Multi-line
+comment */
+service A {
+version "1.0.0"
+}`;
+    const expected = `/* Multi-line
+comment */
+service A {
+  version "1.0.0"
+}
+`;
+    expect(formatEc(input)).toBe(expected);
+  });
+
+  it("does not count braces inside strings", () => {
+    const input = `service A {
+summary "has { braces } inside"
+version "1.0.0"
+}`;
+    const expected = `service A {
+  summary "has { braces } inside"
+  version "1.0.0"
+}
+`;
+    expect(formatEc(input)).toBe(expected);
+  });
+
+  it("does not count braces inside line comments", () => {
+    const input = `service A {
+// something { with braces }
+version "1.0.0"
+}`;
+    const expected = `service A {
+  // something { with braces }
+  version "1.0.0"
+}
+`;
+    expect(formatEc(input)).toBe(expected);
+  });
+
+  it("handles already formatted code", () => {
+    const input = `service A {
+  version "1.0.0"
+  summary "test"
+}
+`;
+    expect(formatEc(input)).toBe(input);
+  });
+
+  it("handles empty input", () => {
+    expect(formatEc("")).toBe("\n");
+  });
+
+  it("handles annotations", () => {
+    const input = `service OrderService {
+version "1.0.0"
+@badge "Core"
+@resourceGroup "Details" {
+content "Some info"
+}
+}`;
+    const expected = `service OrderService {
+  version "1.0.0"
+  @badge "Core"
+  @resourceGroup "Details" {
+    content "Some info"
+  }
+}
+`;
+    expect(formatEc(input)).toBe(expected);
+  });
+
+  it("handles closing brace on same line as content", () => {
+    const input = `service A {
+version "1.0.0"
+}`;
+    const expected = `service A {
+  version "1.0.0"
+}
+`;
+    expect(formatEc(input)).toBe(expected);
+  });
+
+  it("removes trailing blank lines", () => {
+    const input = `service A {
+  version "1.0.0"
+}
+
+
+`;
+    const expected = `service A {
+  version "1.0.0"
+}
+`;
+    expect(formatEc(input)).toBe(expected);
+  });
+
+  it("formats visualizer blocks", () => {
+    const input = `visualizer {
+include OrderService
+include PaymentService
+}`;
+    const expected = `visualizer {
+  include OrderService
+  include PaymentService
+}
+`;
+    expect(formatEc(input)).toBe(expected);
+  });
+});
diff --git a/packages/language-server/test/graph.test.ts b/packages/language-server/test/graph.test.ts
new file mode 100644
index 000000000..e7a37371f
--- /dev/null
+++ b/packages/language-server/test/graph.test.ts
@@ -0,0 +1,2698 @@
+import { describe, it, expect } from "vitest";
+import { createEcServices } from "../src/ec-module.js";
+import { EmptyFileSystem } from "langium";
+import { parseDocument } from "langium/test";
+import type { Program } from "../src/generated/ast.js";
+import { astToGraph } from "../src/graph.js";
+
+const services = createEcServices(EmptyFileSystem);
+
+async function parseProgram(input: string): Promise<Program> {
+  const doc = await parseDocument<Program>(services.Ec, input);
+  expect(doc.parseResult.parserErrors).toHaveLength(0);
+  return doc.parseResult.value;
+}
+
+describe("astToGraph", () => {
+  it("no visualizer returns empty graph", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.empty).toBe(true);
+    expect(graph.nodes).toHaveLength(0);
+    expect(graph.edges).toHaveLength(0);
+    expect(graph.visualizers).toHaveLength(0);
+  });
+
+  it("domain with a service produces nodes and contains edge", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        domain Orders {
+          version 1.0.0
+          service OrderService {
+            version 1.0.0
+          }
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const domainNode = graph.nodes.find(
+      (n) => n.id === "domain:Orders@1.0.0" && n.type === "domain",
+    );
+    const serviceNode = graph.nodes.find(
+      (n) => n.id === "service:OrderService@1.0.0" && n.type === "service",
+    );
+    expect(domainNode).toBeDefined();
+    expect(serviceNode).toBeDefined();
+
+    const containsEdge = graph.edges.find(
+      (e) =>
+        e.source === "domain:Orders@1.0.0" &&
+        e.target === "service:OrderService@1.0.0" &&
+        e.type === "contains",
+    );
+    expect(containsEdge).toBeDefined();
+  });
+
+  it("service sends event produces sends edge", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          sends event OrderCreated
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const serviceNode = graph.nodes.find(
+      (n) => n.id === "service:OrderService@1.0.0" && n.type === "service",
+    );
+    const eventNode = graph.nodes.find(
+      (n) => n.type === "event" && n.label === "OrderCreated",
+    );
+    expect(serviceNode).toBeDefined();
+    expect(eventNode).toBeDefined();
+
+    const sendsEdge = graph.edges.find(
+      (e) =>
+        e.source === serviceNode!.id &&
+        e.target === eventNode!.id &&
+        e.type === "sends",
+    );
+    expect(sendsEdge).toBeDefined();
+  });
+
+  it("service receives event produces receives edge from event to service", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          receives event PaymentProcessed
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const serviceNode = graph.nodes.find(
+      (n) => n.type === "service" && n.label === "OrderService",
+    );
+    const eventNode = graph.nodes.find(
+      (n) => n.type === "event" && n.label === "PaymentProcessed",
+    );
+    expect(serviceNode).toBeDefined();
+    expect(eventNode).toBeDefined();
+
+    const receivesEdge = graph.edges.find(
+      (e) =>
+        e.source === eventNode!.id &&
+        e.target === serviceNode!.id &&
+        e.type === "receives",
+    );
+    expect(receivesEdge).toBeDefined();
+  });
+
+  it("channel routing to produces channel node and edges through channel", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service PaymentService {
+          version 1.0.0
+          sends command ProcessPayment to payment-queue
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const channelNode = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "payment-queue",
+    );
+    expect(channelNode).toBeDefined();
+
+    const serviceNode = graph.nodes.find(
+      (n) => n.type === "service" && n.label === "PaymentService",
+    );
+    const cmdNode = graph.nodes.find(
+      (n) => n.type === "command" && n.label === "ProcessPayment",
+    );
+
+    // service -> message (sends)
+    const svcToMsg = graph.edges.find(
+      (e) =>
+        e.source === serviceNode!.id &&
+        e.target === cmdNode!.id &&
+        e.type === "sends",
+    );
+    expect(svcToMsg).toBeDefined();
+
+    // message -> channel (routes-to)
+    const msgToChannel = graph.edges.find(
+      (e) =>
+        e.source === cmdNode!.id &&
+        e.target === channelNode!.id &&
+        e.type === "routes-to",
+    );
+    expect(msgToChannel).toBeDefined();
+
+    // No direct service -> channel edge
+    const svcToChannel = graph.edges.find(
+      (e) =>
+        e.source === serviceNode!.id &&
+        e.target === channelNode!.id &&
+        e.type === "sends",
+    );
+    expect(svcToChannel).toBeUndefined();
+  });
+
+  it("channel routing from produces channel node and edges through channel for receives", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service NotificationService {
+          version 1.0.0
+          receives event OrderCreated from order-events
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const channelNode = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "order-events",
+    );
+    expect(channelNode).toBeDefined();
+
+    const serviceNode = graph.nodes.find(
+      (n) => n.type === "service" && n.label === "NotificationService",
+    );
+    const eventNode = graph.nodes.find(
+      (n) => n.type === "event" && n.label === "OrderCreated",
+    );
+
+    // "from" on receives also creates message -> channel to ensure connectivity
+    // even when no sends side defines the route
+    const msgToChannel = graph.edges.find(
+      (e) =>
+        e.source === eventNode!.id &&
+        e.target === channelNode!.id &&
+        e.type === "routes-to",
+    );
+    expect(msgToChannel).toBeDefined();
+
+    // channel -> service (receives)
+    const channelToSvc = graph.edges.find(
+      (e) =>
+        e.source === channelNode!.id &&
+        e.target === serviceNode!.id &&
+        e.type === "receives",
+    );
+    expect(channelToSvc).toBeDefined();
+
+    // No direct message -> service edge when channel is present
+    const directEdge = graph.edges.find(
+      (e) =>
+        e.source === eventNode!.id &&
+        e.target === serviceNode!.id &&
+        e.type === "receives",
+    );
+    expect(directEdge).toBeUndefined();
+  });
+
+  it("channel used inside domain is parented to that domain", async () => {
+    const program = await parseProgram(`
+      channel MyChannel {
+        version 1.0.0
+        address "topic"
+      }
+
+      visualizer main {
+        domain Payment {
+          version 1.0.0
+
+          service Random {
+            version 1.0.0
+            sends event Name to MyChannel
+          }
+
+          service OrderService {
+            version 1.0.0
+            receives event Name from MyChannel
+          }
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const domainNode = graph.nodes.find(
+      (n) => n.type === "domain" && n.label === "Payment",
+    );
+    const channelNode = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "MyChannel",
+    );
+    expect(domainNode).toBeDefined();
+    expect(channelNode).toBeDefined();
+
+    // Channel is parented to the domain
+    expect(channelNode!.parentId).toBe(domainNode!.id);
+
+    // Contains edge from domain to channel
+    const containsEdge = graph.edges.find(
+      (e) =>
+        e.source === domainNode!.id &&
+        e.target === channelNode!.id &&
+        e.type === "contains",
+    );
+    expect(containsEdge).toBeDefined();
+
+    // Event is also parented to the domain
+    const eventNode = graph.nodes.find(
+      (n) => n.type === "event" && n.label === "Name",
+    );
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.parentId).toBe(domainNode!.id);
+  });
+
+  it("writes-to and reads-from produce correct edge types", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          writes-to container orders-db
+          reads-from container orders-cache
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const serviceNode = graph.nodes.find(
+      (n) => n.type === "service" && n.label === "OrderService",
+    );
+    const dbNode = graph.nodes.find(
+      (n) => n.type === "container" && n.label === "orders-db",
+    );
+    const cacheNode = graph.nodes.find(
+      (n) => n.type === "container" && n.label === "orders-cache",
+    );
+
+    const writesEdge = graph.edges.find(
+      (e) =>
+        e.source === serviceNode!.id &&
+        e.target === dbNode!.id &&
+        e.type === "writes-to",
+    );
+    expect(writesEdge).toBeDefined();
+
+    const readsEdge = graph.edges.find(
+      (e) =>
+        e.source === cacheNode!.id &&
+        e.target === serviceNode!.id &&
+        e.type === "reads-from",
+    );
+    expect(readsEdge).toBeDefined();
+  });
+
+  it("writes-to and reads-from same container merge into reads-writes edge", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          writes-to container orders-db
+          reads-from container orders-db
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const serviceNode = graph.nodes.find(
+      (n) => n.id === "service:OrderService@1.0.0",
+    );
+    const dbNode = graph.nodes.find((n) => n.type === "container");
+    expect(serviceNode).toBeDefined();
+    expect(dbNode).toBeDefined();
+
+    // Should have a single reads-writes edge instead of separate writes-to and reads-from
+    const readsWritesEdge = graph.edges.find(
+      (e) =>
+        e.source === serviceNode!.id &&
+        e.target === dbNode!.id &&
+        e.type === "reads-writes",
+    );
+    expect(readsWritesEdge).toBeDefined();
+
+    // No separate writes-to or reads-from edges should remain
+    const writesToEdge = graph.edges.find(
+      (e) => e.type === "writes-to" && e.target === dbNode!.id,
+    );
+    const readsFromEdge = graph.edges.find(
+      (e) => e.type === "reads-from" && e.source === dbNode!.id,
+    );
+    expect(writesToEdge).toBeUndefined();
+    expect(readsFromEdge).toBeUndefined();
+  });
+
+  it("writes-to container inherits summary and containerType from top-level definition", async () => {
+    const program = await parseProgram(`
+      container orders-db {
+        name "Orders Database"
+        version 1.0.0
+        summary "Primary database for orders"
+        container-type database
+      }
+
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          writes-to container orders-db
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    const dbNode = graph.nodes.find((n) => n.type === "container");
+    expect(dbNode).toBeDefined();
+    expect(dbNode!.label).toBe("Orders Database");
+    expect(dbNode!.metadata.summary).toBe("Primary database for orders");
+    expect(dbNode!.metadata.version).toBe("1.0.0");
+    expect(dbNode!.metadata.containerType).toBe("database");
+  });
+
+  it("subdomain hierarchy produces correct parentIds and contains edges", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        domain Commerce {
+          version 1.0.0
+          subdomain Ordering {
+            version 1.0.0
+            service OrderService {
+              version 1.0.0
+            }
+          }
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const domainNode = graph.nodes.find(
+      (n) => n.id === "domain:Commerce@1.0.0" && n.type === "domain",
+    );
+    const subdomainNode = graph.nodes.find(
+      (n) => n.id === "domain:Ordering@1.0.0" && n.type === "domain",
+    );
+    const serviceNode = graph.nodes.find(
+      (n) => n.id === "service:OrderService@1.0.0" && n.type === "service",
+    );
+
+    expect(domainNode).toBeDefined();
+    expect(subdomainNode).toBeDefined();
+    expect(serviceNode).toBeDefined();
+
+    expect(subdomainNode!.parentId).toBe("domain:Commerce@1.0.0");
+    expect(serviceNode!.parentId).toBe("domain:Ordering@1.0.0");
+
+    const domainToSub = graph.edges.find(
+      (e) =>
+        e.source === "domain:Commerce@1.0.0" &&
+        e.target === "domain:Ordering@1.0.0" &&
+        e.type === "contains",
+    );
+    expect(domainToSub).toBeDefined();
+
+    const subToService = graph.edges.find(
+      (e) =>
+        e.source === "domain:Ordering@1.0.0" &&
+        e.target === "service:OrderService@1.0.0" &&
+        e.type === "contains",
+    );
+    expect(subToService).toBeDefined();
+  });
+
+  it("standalone event inside visualizer produces node", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        event InventoryReserved {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const eventNode = graph.nodes.find(
+      (n) => n.id === "event:InventoryReserved@1.0.0" && n.type === "event",
+    );
+    expect(eventNode).toBeDefined();
+  });
+
+  it("user and team without visualizer returns empty graph", async () => {
+    const program = await parseProgram(`
+      user dboyne {
+        name "David Boyne"
+        role "Engineer"
+      }
+
+      team orders-team {
+        name "Orders Team"
+        member dboyne
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.empty).toBe(true);
+    expect(graph.nodes).toHaveLength(0);
+  });
+
+  it("edge IDs are deterministic using source-type-target format", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          sends event OrderCreated
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const serviceNode = graph.nodes.find(
+      (n) => n.type === "service" && n.label === "OrderService",
+    );
+    const eventNode = graph.nodes.find(
+      (n) => n.type === "event" && n.label === "OrderCreated",
+    );
+
+    const sendsEdge = graph.edges.find(
+      (e) =>
+        e.source === serviceNode!.id &&
+        e.target === eventNode!.id &&
+        e.type === "sends",
+    );
+    expect(sendsEdge).toBeDefined();
+    expect(sendsEdge!.id).toBe(`${serviceNode!.id}-sends-${eventNode!.id}`);
+  });
+
+  it("messages sent by service inside domain are parented to that domain", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        domain Payment {
+          version 1.0.0
+          service PaymentService {
+            version 1.0.0
+            sends event PaymentProcessed
+          }
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const domainNode = graph.nodes.find(
+      (n) => n.type === "domain" && n.label === "Payment",
+    );
+    const eventNode = graph.nodes.find(
+      (n) => n.type === "event" && n.label === "PaymentProcessed",
+    );
+    expect(domainNode).toBeDefined();
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.parentId).toBe(domainNode!.id);
+
+    // Contains edge from domain to event
+    const containsEdge = graph.edges.find(
+      (e) =>
+        e.source === domainNode!.id &&
+        e.target === eventNode!.id &&
+        e.type === "contains",
+    );
+    expect(containsEdge).toBeDefined();
+  });
+
+  // ─── Multi-version and @version syntax tests ──────────────────
+
+  it("sends event with @version creates a versioned node", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          sends event OrderCreated@1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const eventNode = graph.nodes.find(
+      (n) => n.id === "event:OrderCreated@1.0.0",
+    );
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.type).toBe("event");
+
+    const sendsEdge = graph.edges.find(
+      (e) =>
+        e.source === "service:OrderService@1.0.0" &&
+        e.target === "event:OrderCreated@1.0.0" &&
+        e.type === "sends",
+    );
+    expect(sendsEdge).toBeDefined();
+  });
+
+  it("receives event with @version creates a versioned node", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service NotificationService {
+          version 1.0.0
+          receives event OrderCreated@2.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const eventNode = graph.nodes.find(
+      (n) => n.id === "event:OrderCreated@2.0.0",
+    );
+    expect(eventNode).toBeDefined();
+
+    const receivesEdge = graph.edges.find(
+      (e) =>
+        e.source === "event:OrderCreated@2.0.0" &&
+        e.target === "service:NotificationService@1.0.0" &&
+        e.type === "receives",
+    );
+    expect(receivesEdge).toBeDefined();
+  });
+
+  it("multiple versions of the same event create separate nodes with correct edges", async () => {
+    const program = await parseProgram(`
+      event OrderCreated {
+        version 1.0.0
+        summary "Original order event"
+      }
+
+      event OrderCreated {
+        version 2.0.0
+        summary "Extended order event"
+      }
+
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          sends event OrderCreated@1.0.0
+          sends event OrderCreated@2.0.0
+        }
+
+        service LegacyConsumer {
+          version 1.0.0
+          receives event OrderCreated@1.0.0
+        }
+
+        service ModernConsumer {
+          version 1.0.0
+          receives event OrderCreated@2.0.0
+        }
+
+        event OrderCreated {
+          version 1.0.0
+          summary "Original order event"
+        }
+
+        event OrderCreated {
+          version 2.0.0
+          summary "Extended order event"
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    // Two separate event nodes
+    const v1 = graph.nodes.find((n) => n.id === "event:OrderCreated@1.0.0");
+    const v2 = graph.nodes.find((n) => n.id === "event:OrderCreated@2.0.0");
+    expect(v1).toBeDefined();
+    expect(v2).toBeDefined();
+    expect(v1!.id).not.toBe(v2!.id);
+
+    // Metadata merged from standalone definitions
+    expect(v1!.metadata.summary).toBe("Original order event");
+    expect(v2!.metadata.summary).toBe("Extended order event");
+
+    // OrderService sends to both versions
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "service:OrderService@1.0.0" &&
+          e.target === "event:OrderCreated@1.0.0" &&
+          e.type === "sends",
+      ),
+    ).toBeDefined();
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "service:OrderService@1.0.0" &&
+          e.target === "event:OrderCreated@2.0.0" &&
+          e.type === "sends",
+      ),
+    ).toBeDefined();
+
+    // LegacyConsumer receives v1 only
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "event:OrderCreated@1.0.0" &&
+          e.target === "service:LegacyConsumer@1.0.0" &&
+          e.type === "receives",
+      ),
+    ).toBeDefined();
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "event:OrderCreated@2.0.0" &&
+          e.target === "service:LegacyConsumer@1.0.0",
+      ),
+    ).toBeUndefined();
+
+    // ModernConsumer receives v2 only
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "event:OrderCreated@2.0.0" &&
+          e.target === "service:ModernConsumer@1.0.0" &&
+          e.type === "receives",
+      ),
+    ).toBeDefined();
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "event:OrderCreated@1.0.0" &&
+          e.target === "service:ModernConsumer@1.0.0",
+      ),
+    ).toBeUndefined();
+  });
+
+  it("unversioned bare reference resolves to existing versioned node", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service PaymentService {
+          version 1.0.0
+          sends event PaymentProcessed {
+            version 1.0.0
+            summary "Payment completed"
+          }
+        }
+
+        service NotificationService {
+          version 1.0.0
+          receives event PaymentProcessed
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    // Only one PaymentProcessed node (the versioned one)
+    const ppNodes = graph.nodes.filter((n) => n.label === "PaymentProcessed");
+    expect(ppNodes).toHaveLength(1);
+    expect(ppNodes[0].id).toBe("event:PaymentProcessed@1.0.0");
+
+    // NotificationService receives from the versioned node
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "event:PaymentProcessed@1.0.0" &&
+          e.target === "service:NotificationService@1.0.0" &&
+          e.type === "receives",
+      ),
+    ).toBeDefined();
+  });
+
+  it("stub upgrade: bare reference is upgraded when versioned definition appears later", async () => {
+    const program = await parseProgram(`
+      command CreateOrder {
+        version 1.0.0
+        summary "Place a new order"
+      }
+
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          receives command CreateOrder
+        }
+
+        command CreateOrder {
+          version 1.0.0
+          summary "Place a new order"
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    // Only one CreateOrder node, upgraded to versioned
+    const coNodes = graph.nodes.filter((n) => n.label === "CreateOrder");
+    expect(coNodes).toHaveLength(1);
+    expect(coNodes[0].id).toBe("command:CreateOrder@1.0.0");
+    expect(coNodes[0].metadata.version).toBe("1.0.0");
+    expect(coNodes[0].metadata.summary).toBe("Place a new order");
+
+    // Edge still points to the upgraded node
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "command:CreateOrder@1.0.0" &&
+          e.target === "service:OrderService@1.0.0" &&
+          e.type === "receives",
+      ),
+    ).toBeDefined();
+  });
+
+  it("metadata merges when same versioned node is encountered again", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          sends event OrderCreated {
+            version 1.0.0
+          }
+        }
+
+        event OrderCreated {
+          version 1.0.0
+          summary "A new order has been placed"
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const eventNode = graph.nodes.find(
+      (n) => n.id === "event:OrderCreated@1.0.0",
+    );
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.metadata.summary).toBe("A new order has been placed");
+  });
+
+  it("domain service referencing top-level event resolves to same node", async () => {
+    const program = await parseProgram(`
+      event PaymentProcessed {
+        version 1.0.0
+        summary "Payment completed successfully"
+      }
+
+      visualizer main {
+        domain Payment {
+          version 1.0.0
+          service PaymentService {
+            version 1.0.0
+            sends event PaymentProcessed
+          }
+        }
+
+        event PaymentProcessed {
+          version 1.0.0
+          summary "Payment completed successfully"
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    // Single PaymentProcessed node with metadata from the definition
+    const ppNodes = graph.nodes.filter((n) => n.label === "PaymentProcessed");
+    expect(ppNodes).toHaveLength(1);
+    expect(ppNodes[0].id).toBe("event:PaymentProcessed@1.0.0");
+    expect(ppNodes[0].metadata.summary).toBe("Payment completed successfully");
+
+    // Sends edge from service to event
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "service:PaymentService@1.0.0" &&
+          e.target === "event:PaymentProcessed@1.0.0" &&
+          e.type === "sends",
+      ),
+    ).toBeDefined();
+  });
+
+  it("command with @version in sends and receives", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          sends command ProcessPayment@1.0.0
+        }
+
+        service PaymentService {
+          version 1.0.0
+          receives command ProcessPayment@1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const cmdNode = graph.nodes.find(
+      (n) => n.id === "command:ProcessPayment@1.0.0",
+    );
+    expect(cmdNode).toBeDefined();
+
+    // OrderService sends the command
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "service:OrderService@1.0.0" &&
+          e.target === "command:ProcessPayment@1.0.0" &&
+          e.type === "sends",
+      ),
+    ).toBeDefined();
+
+    // PaymentService receives the command
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "command:ProcessPayment@1.0.0" &&
+          e.target === "service:PaymentService@1.0.0" &&
+          e.type === "receives",
+      ),
+    ).toBeDefined();
+  });
+
+  it("service reference inside domain places service node inside domain", async () => {
+    const program = await parseProgram(`
+      service Random {
+        version 1.0.0
+        summary "Hello world"
+      }
+
+      visualizer main {
+        domain Name {
+          version 1.0.0
+          service Random@1.0.0
+        }
+
+        service Random {
+          version 1.0.0
+          summary "Hello world"
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const domainNode = graph.nodes.find((n) => n.id === "domain:Name@1.0.0");
+    expect(domainNode).toBeDefined();
+
+    const serviceNode = graph.nodes.find(
+      (n) => n.id === "service:Random@1.0.0",
+    );
+    expect(serviceNode).toBeDefined();
+    expect(serviceNode!.parentId).toBe("domain:Name@1.0.0");
+    expect(serviceNode!.metadata.summary).toBe("Hello world");
+
+    // Contains edge from domain to service
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "domain:Name@1.0.0" &&
+          e.target === "service:Random@1.0.0" &&
+          e.type === "contains",
+      ),
+    ).toBeDefined();
+  });
+
+  it("service reference inside domain includes sends/receives messages", async () => {
+    const program = await parseProgram(`
+      service InventoryService {
+        version 0.0.2
+        name "Inventory Service"
+        summary "Service that handles the inventory"
+        sends event InventoryAdjusted
+      }
+
+      domain Orders {
+        version 0.0.3
+        name "Orders"
+        summary "The Orders domain"
+        service InventoryService
+      }
+
+      visualizer main {
+        domain Orders
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    // Service should be inside the domain
+    const serviceNode = graph.nodes.find(
+      (n) => n.id === "service:InventoryService@0.0.2",
+    );
+    expect(serviceNode).toBeDefined();
+    expect(serviceNode!.parentId).toBe("domain:Orders@0.0.3");
+
+    // The sent event should appear in the graph
+    const eventNode = graph.nodes.find(
+      (n) => n.id === "event:InventoryAdjusted",
+    );
+    expect(eventNode).toBeDefined();
+
+    // Sends edge from service to event
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "service:InventoryService@0.0.2" &&
+          e.target === "event:InventoryAdjusted" &&
+          e.type === "sends",
+      ),
+    ).toBeDefined();
+  });
+
+  it("service reference without version inside domain resolves to versioned definition", async () => {
+    const program = await parseProgram(`
+      service Random {
+        version 1.0.0
+        summary "Hello world"
+      }
+
+      visualizer main {
+        domain Name {
+          version 1.0.0
+          service Random
+        }
+
+        service Random {
+          version 1.0.0
+          summary "Hello world"
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const serviceNode = graph.nodes.find(
+      (n) => n.id === "service:Random@1.0.0",
+    );
+    expect(serviceNode).toBeDefined();
+    expect(serviceNode!.parentId).toBe("domain:Name@1.0.0");
+
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "domain:Name@1.0.0" &&
+          e.target === "service:Random@1.0.0" &&
+          e.type === "contains",
+      ),
+    ).toBeDefined();
+  });
+
+  it("query with @version syntax", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service UserService {
+          version 1.0.0
+          receives query GetUser@1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const queryNode = graph.nodes.find((n) => n.id === "query:GetUser@1.0.0");
+    expect(queryNode).toBeDefined();
+
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "query:GetUser@1.0.0" &&
+          e.target === "service:UserService@1.0.0" &&
+          e.type === "receives",
+      ),
+    ).toBeDefined();
+  });
+
+  // ─── Visualizer-specific tests ──────────────────
+
+  it("visualizer with service reference resolves top-level definition", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        summary "Manages orders"
+        sends event OrderCreated
+      }
+
+      visualizer main {
+        service OrderService@1.0.0
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.visualizers).toEqual(["main"]);
+    expect(graph.activeVisualizer).toBe("main");
+
+    const serviceNode = graph.nodes.find(
+      (n) => n.id === "service:OrderService@1.0.0",
+    );
+    expect(serviceNode).toBeDefined();
+    expect(serviceNode!.metadata.summary).toBe("Manages orders");
+
+    // Sends edge from resolving the top-level def
+    const sendsEdge = graph.edges.find((e) => e.type === "sends");
+    expect(sendsEdge).toBeDefined();
+  });
+
+  it("multiple visualizers with name selection", async () => {
+    const program = await parseProgram(`
+      visualizer overview {
+        service OrderService {
+          version 1.0.0
+        }
+      }
+
+      visualizer detailed {
+        service OrderService {
+          version 1.0.0
+          sends event OrderCreated
+        }
+        service PaymentService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const overviewGraph = astToGraph(program, "overview");
+    expect(overviewGraph.visualizers).toEqual(["overview", "detailed"]);
+    expect(overviewGraph.activeVisualizer).toBe("overview");
+    expect(overviewGraph.nodes).toHaveLength(1);
+
+    const detailedGraph = astToGraph(program, "detailed");
+    expect(detailedGraph.activeVisualizer).toBe("detailed");
+    expect(detailedGraph.nodes.length).toBeGreaterThan(1);
+  });
+
+  it("visualizer with container reference creates data node", async () => {
+    const program = await parseProgram(`
+      container OrdersDB {
+        version 1.0.0
+        container-type database
+      }
+
+      visualizer main {
+        container OrdersDB@1.0.0
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const dataNode = graph.nodes.find(
+      (n) => n.type === "container" && n.label === "OrdersDB",
+    );
+    expect(dataNode).toBeDefined();
+  });
+
+  it("container with deprecated includes metadata", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        container TestDB {
+          version 1.0.0
+          container-type database
+          deprecated true
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const node = graph.nodes.find(
+      (n) => n.type === "container" && n.label === "TestDB",
+    );
+    expect(node).toBeDefined();
+    expect(node!.metadata.deprecated).toBe(true);
+  });
+
+  // ─── Visualizer display options tests ──────────────────
+
+  it("visualizer with legend false returns options.legend === false", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        legend false
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.options?.legend).toBe(false);
+  });
+
+  it("visualizer with search false returns options.search === false", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        search false
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.options?.search).toBe(false);
+  });
+
+  it("visualizer with no display options returns undefined for all options", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.options?.legend).toBeUndefined();
+    expect(graph.options?.search).toBeUndefined();
+    expect(graph.options?.toolbar).toBeUndefined();
+    expect(graph.options?.focusMode).toBeUndefined();
+    expect(graph.options?.animated).toBeUndefined();
+    expect(graph.options?.style).toBeUndefined();
+  });
+
+  it("visualizer with toolbar false and focus-mode false", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        toolbar false
+        focus-mode false
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.options?.toolbar).toBe(false);
+    expect(graph.options?.focusMode).toBe(false);
+    expect(graph.options?.legend).toBeUndefined();
+    expect(graph.options?.search).toBeUndefined();
+  });
+
+  it("visualizer with all display options set to true", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        legend true
+        search true
+        toolbar true
+        focus-mode true
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.options?.legend).toBe(true);
+    expect(graph.options?.search).toBe(true);
+    expect(graph.options?.toolbar).toBe(true);
+    expect(graph.options?.focusMode).toBe(true);
+  });
+
+  it("visualizer with style post-it returns options.style === post-it", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        style post-it
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.options?.style).toBe("post-it");
+  });
+
+  it("visualizer with style default returns options.style === default", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        style default
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.options?.style).toBe("default");
+  });
+
+  it("visualizer with no style returns options.style === undefined", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.options?.style).toBeUndefined();
+  });
+
+  it("visualizer with animated true returns options.animated === true", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        animated true
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.options?.animated).toBe(true);
+  });
+
+  it("visualizer with animated false returns options.animated === false", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        animated false
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.options?.animated).toBe(false);
+  });
+
+  it("visualizer with no animated returns options.animated === undefined", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    expect(graph.options?.animated).toBeUndefined();
+  });
+
+  it("visualizer with event ref (empty body) resolves to top-level def", async () => {
+    const program = await parseProgram(`
+      event OrderCreated {
+        version 1.0.0
+        summary "A new order"
+      }
+
+      visualizer main {
+        event OrderCreated
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const eventNode = graph.nodes.find(
+      (n) => n.type === "event" && n.label === "OrderCreated",
+    );
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.metadata.summary).toBe("A new order");
+    expect(eventNode!.metadata.version).toBe("1.0.0");
+  });
+
+  it("channel defined outside visualizer has its metadata resolved via sends/receives", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        name "View Name"
+
+        domain Ordering {
+          version 1.0.0
+
+          service OrderService {
+            version 1.0.0
+            sends event OrderCreated to RabbitMQ
+          }
+        }
+      }
+
+      channel RabbitMQ {
+        version 1.0.0
+        address "orders.topic"
+        summary "Main message broker"
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const channelNode = graph.nodes.find((n) => n.type === "channel");
+    expect(channelNode).toBeDefined();
+    expect(channelNode!.label).toBe("RabbitMQ");
+    expect(channelNode!.metadata.version).toBe("1.0.0");
+    expect(channelNode!.metadata.address).toBe("orders.topic");
+    expect(channelNode!.metadata.summary).toBe("Main message broker");
+  });
+
+  it("channel node includes protocol metadata when defined inline", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        name "View Name"
+
+        channel KafkaTopic {
+          version 1.0.0
+          address "events.orders"
+          protocol "Kafka"
+          summary "Order events topic"
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const channelNode = graph.nodes.find((n) => n.type === "channel");
+    expect(channelNode).toBeDefined();
+    expect(channelNode!.metadata.protocols).toEqual(["Kafka"]);
+    expect(channelNode!.metadata.address).toBe("events.orders");
+  });
+
+  it("channel node includes protocol metadata when defined outside visualizer", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        name "View Name"
+
+        service OrderService {
+          version 1.0.0
+          sends event OrderCreated to KafkaTopic
+        }
+      }
+
+      channel KafkaTopic {
+        version 1.0.0
+        address "events.orders"
+        protocol "Kafka"
+        summary "Order events topic"
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const channelNode = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "KafkaTopic",
+    );
+    expect(channelNode).toBeDefined();
+    expect(channelNode!.metadata.protocols).toEqual(["Kafka"]);
+    expect(channelNode!.metadata.address).toBe("events.orders");
+  });
+
+  it("event defined outside visualizer has its metadata resolved via sends", async () => {
+    const program = await parseProgram(`
+      event OrderCreated {
+        version 2.0.0
+        summary "Order was created"
+      }
+
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          sends event OrderCreated
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const eventNode = graph.nodes.find((n) => n.type === "event");
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.metadata.summary).toBe("Order was created");
+    expect(eventNode!.metadata.version).toBe("2.0.0");
+  });
+
+  // ─── Channel route tests ──────────────────────────────
+
+  it("channel with route creates routes-to edge between channels", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        channel KafkaRaw {
+          version 1.0.0
+          address "sensors.raw"
+          protocol "Kafka"
+          route KafkaFiltered
+        }
+
+        channel KafkaFiltered {
+          version 1.0.0
+          address "sensors.filtered"
+          protocol "Kafka"
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const rawNode = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "KafkaRaw",
+    );
+    const filteredNode = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "KafkaFiltered",
+    );
+    expect(rawNode).toBeDefined();
+    expect(filteredNode).toBeDefined();
+
+    const routeEdge = graph.edges.find(
+      (e) =>
+        e.source === rawNode!.id &&
+        e.target === filteredNode!.id &&
+        e.type === "routes-to",
+    );
+    expect(routeEdge).toBeDefined();
+  });
+
+  it("channel chain with multiple routes creates sequential edges", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        channel KafkaRaw {
+          version 1.0.0
+          protocol "Kafka"
+          route KafkaFiltered
+        }
+
+        channel KafkaFiltered {
+          version 1.0.0
+          protocol "Kafka"
+          route MqttBridge
+        }
+
+        channel MqttBridge {
+          version 1.0.0
+          protocol "MQTT"
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    expect(graph.nodes.filter((n) => n.type === "channel")).toHaveLength(3);
+
+    // KafkaRaw -> KafkaFiltered
+    const edge1 = graph.edges.find(
+      (e) =>
+        e.source === "channel:KafkaRaw@1.0.0" &&
+        e.target === "channel:KafkaFiltered@1.0.0" &&
+        e.type === "routes-to",
+    );
+    expect(edge1).toBeDefined();
+
+    // KafkaFiltered -> MqttBridge
+    const edge2 = graph.edges.find(
+      (e) =>
+        e.source === "channel:KafkaFiltered@1.0.0" &&
+        e.target === "channel:MqttBridge@1.0.0" &&
+        e.type === "routes-to",
+    );
+    expect(edge2).toBeDefined();
+  });
+
+  it("channel route with versioned target resolves correctly", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        channel SourceTopic {
+          version 1.0.0
+          route TargetTopic@2.0.0
+        }
+
+        channel TargetTopic {
+          version 2.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const routeEdge = graph.edges.find(
+      (e) =>
+        e.source === "channel:SourceTopic@1.0.0" &&
+        e.target === "channel:TargetTopic@2.0.0" &&
+        e.type === "routes-to",
+    );
+    expect(routeEdge).toBeDefined();
+  });
+
+  it("channel with multiple routes creates multiple edges", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        channel Ingestion {
+          version 1.0.0
+          route Analytics
+          route Archive
+        }
+
+        channel Analytics {
+          version 1.0.0
+        }
+
+        channel Archive {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const toAnalytics = graph.edges.find(
+      (e) =>
+        e.source === "channel:Ingestion@1.0.0" &&
+        e.target === "channel:Analytics@1.0.0" &&
+        e.type === "routes-to",
+    );
+    const toArchive = graph.edges.find(
+      (e) =>
+        e.source === "channel:Ingestion@1.0.0" &&
+        e.target === "channel:Archive@1.0.0" &&
+        e.type === "routes-to",
+    );
+    expect(toAnalytics).toBeDefined();
+    expect(toArchive).toBeDefined();
+  });
+
+  it("end-to-end: service sends to channel chain, another service receives from last channel", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        channel KafkaRaw {
+          version 1.0.0
+          protocol "Kafka"
+          route KafkaFiltered
+        }
+
+        channel KafkaFiltered {
+          version 1.0.0
+          protocol "Kafka"
+          route MqttDevices
+        }
+
+        channel MqttDevices {
+          version 1.0.0
+          protocol "MQTT"
+        }
+
+        service SensorGateway {
+          version 1.0.0
+          sends event SensorReading to KafkaRaw
+        }
+
+        service Dashboard {
+          version 1.0.0
+          receives event SensorReading from MqttDevices
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    // Service -> Event (sends)
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "service:SensorGateway@1.0.0" &&
+          e.target === "event:SensorReading" &&
+          e.type === "sends",
+      ),
+    ).toBeDefined();
+
+    // Event -> KafkaRaw (routes-to from sends)
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "event:SensorReading" &&
+          e.target === "channel:KafkaRaw@1.0.0" &&
+          e.type === "routes-to",
+      ),
+    ).toBeDefined();
+
+    // KafkaRaw -> KafkaFiltered (routes-to from route stmt)
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "channel:KafkaRaw@1.0.0" &&
+          e.target === "channel:KafkaFiltered@1.0.0" &&
+          e.type === "routes-to",
+      ),
+    ).toBeDefined();
+
+    // KafkaFiltered -> MqttDevices (routes-to from route stmt)
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "channel:KafkaFiltered@1.0.0" &&
+          e.target === "channel:MqttDevices@1.0.0" &&
+          e.type === "routes-to",
+      ),
+    ).toBeDefined();
+
+    // MqttDevices -> Dashboard (receives, from "receives ... from MqttDevices")
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "channel:MqttDevices@1.0.0" &&
+          e.target === "service:Dashboard@1.0.0" &&
+          e.type === "receives",
+      ),
+    ).toBeDefined();
+
+    // The direct Message → Channel edge should NOT exist because the message
+    // already reaches MqttDevices via the channel chain (KafkaRaw → KafkaFiltered → MqttDevices)
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "event:SensorReading" &&
+          e.target === "channel:MqttDevices@1.0.0" &&
+          e.type === "routes-to",
+      ),
+    ).toBeUndefined();
+  });
+
+  it("cross-domain channel routing removes redundant direct message-to-channel edges", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        channel MainEventBus {
+          version 1.0.0
+          protocol "EventBridge"
+          route NotificationsEventBus
+        }
+
+        domain Orders {
+          version 1.0.0
+
+          channel OrderEventBus {
+            version 1.0.0
+            protocol "EventBridge"
+            route MainEventBus
+          }
+
+          service OrderService {
+            version 1.0.0
+            sends event OrderCreated to OrderEventBus {
+              version 1.0.0
+            }
+          }
+        }
+
+        domain Notifications {
+          version 1.0.0
+
+          channel NotificationsEventBus {
+            version 1.0.0
+            protocol "EventBridge"
+            route EmailQueue
+          }
+
+          channel EmailQueue {
+            version 1.0.0
+            protocol "SQS"
+          }
+
+          service EmailService {
+            version 1.0.0
+            receives event OrderCreated from EmailQueue
+          }
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    // Full chain should exist: OrderCreated -> OrderEventBus -> MainEventBus -> NotificationsEventBus -> EmailQueue
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "event:OrderCreated@1.0.0" &&
+          e.target === "channel:OrderEventBus@1.0.0" &&
+          e.type === "routes-to",
+      ),
+    ).toBeDefined();
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "channel:OrderEventBus@1.0.0" &&
+          e.target === "channel:MainEventBus@1.0.0" &&
+          e.type === "routes-to",
+      ),
+    ).toBeDefined();
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "channel:MainEventBus@1.0.0" &&
+          e.target === "channel:NotificationsEventBus@1.0.0" &&
+          e.type === "routes-to",
+      ),
+    ).toBeDefined();
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "channel:NotificationsEventBus@1.0.0" &&
+          e.target === "channel:EmailQueue@1.0.0" &&
+          e.type === "routes-to",
+      ),
+    ).toBeDefined();
+
+    // Direct OrderCreated -> EmailQueue edge should NOT exist (redundant with chain)
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "event:OrderCreated@1.0.0" &&
+          e.target === "channel:EmailQueue@1.0.0" &&
+          e.type === "routes-to",
+      ),
+    ).toBeUndefined();
+
+    // EmailQueue -> EmailService receives edge should still exist
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === "channel:EmailQueue@1.0.0" &&
+          e.target === "service:EmailService@1.0.0" &&
+          e.type === "receives",
+      ),
+    ).toBeDefined();
+  });
+
+  it("receives from channel without sends side still creates message-to-channel edge", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service NotificationService {
+          version 1.0.0
+          receives event OrderCreated from order-events
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    // When there's no sends side, receives should still create message -> channel edge
+    const eventNode = graph.nodes.find(
+      (n) => n.type === "event" && n.label === "OrderCreated",
+    );
+    const channelNode = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "order-events",
+    );
+    expect(eventNode).toBeDefined();
+    expect(channelNode).toBeDefined();
+
+    expect(
+      graph.edges.find(
+        (e) =>
+          e.source === eventNode!.id &&
+          e.target === channelNode!.id &&
+          e.type === "routes-to",
+      ),
+    ).toBeDefined();
+  });
+
+  it("service with @note annotations includes notes in metadata", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          @note("Come back later")
+          @note("Needs review", author: "dboyne", priority: "high")
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const serviceNode = graph.nodes.find(
+      (n) => n.type === "service" && n.label === "OrderService",
+    );
+    expect(serviceNode).toBeDefined();
+    expect(serviceNode!.metadata.notes).toBeDefined();
+    const notes = serviceNode!.metadata.notes as Array<{
+      content: string;
+      author?: string;
+      priority?: string;
+    }>;
+    expect(notes).toHaveLength(2);
+    expect(notes[0].content).toBe("Come back later");
+    expect(notes[1].content).toBe("Needs review");
+    expect(notes[1].author).toBe("dboyne");
+    expect(notes[1].priority).toBe("high");
+  });
+
+  it("service without @note annotations has no notes in metadata", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const serviceNode = graph.nodes.find(
+      (n) => n.type === "service" && n.label === "OrderService",
+    );
+    expect(serviceNode).toBeDefined();
+    expect(serviceNode!.metadata.notes).toBeUndefined();
+  });
+
+  it("event with @note annotations includes notes in metadata", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        event OrderCreated {
+          version 1.0.0
+          @note("Schema v2 adds shippingAddress", author: "alice")
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const eventNode = graph.nodes.find(
+      (n) => n.type === "event" && n.label === "OrderCreated",
+    );
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.metadata.notes).toBeDefined();
+    const notes = eventNode!.metadata.notes as Array<{
+      content: string;
+      author?: string;
+      priority?: string;
+    }>;
+    expect(notes).toHaveLength(1);
+    expect(notes[0].content).toBe("Schema v2 adds shippingAddress");
+    expect(notes[0].author).toBe("alice");
+  });
+
+  it("command with @note annotations includes notes in metadata", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        command CreateOrder {
+          version 1.0.0
+          @note("Validate idempotency key", author: "bob", priority: "high")
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const cmdNode = graph.nodes.find(
+      (n) => n.type === "command" && n.label === "CreateOrder",
+    );
+    expect(cmdNode).toBeDefined();
+    expect(cmdNode!.metadata.notes).toBeDefined();
+    const notes = cmdNode!.metadata.notes as Array<{
+      content: string;
+      author?: string;
+      priority?: string;
+    }>;
+    expect(notes).toHaveLength(1);
+    expect(notes[0].content).toBe("Validate idempotency key");
+    expect(notes[0].author).toBe("bob");
+    expect(notes[0].priority).toBe("high");
+  });
+
+  it("query with @note annotations includes notes in metadata", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        query GetOrder {
+          version 1.0.0
+          @note("Consider caching", author: "carol")
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const queryNode = graph.nodes.find(
+      (n) => n.type === "query" && n.label === "GetOrder",
+    );
+    expect(queryNode).toBeDefined();
+    expect(queryNode!.metadata.notes).toBeDefined();
+    const notes = queryNode!.metadata.notes as Array<{
+      content: string;
+      author?: string;
+      priority?: string;
+    }>;
+    expect(notes).toHaveLength(1);
+    expect(notes[0].content).toBe("Consider caching");
+    expect(notes[0].author).toBe("carol");
+  });
+
+  it("channel with @note annotations includes notes in metadata", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        channel OrderEvents {
+          version 1.0.0
+          address "orders.events"
+          protocol "kafka"
+          @note("Partition key is orderId", author: "infra-team")
+          @note("Retention set to 7 days")
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const channelNode = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "OrderEvents",
+    );
+    expect(channelNode).toBeDefined();
+    expect(channelNode!.metadata.notes).toBeDefined();
+    const notes = channelNode!.metadata.notes as Array<{
+      content: string;
+      author?: string;
+      priority?: string;
+    }>;
+    expect(notes).toHaveLength(2);
+    expect(notes[0].content).toBe("Partition key is orderId");
+    expect(notes[0].author).toBe("infra-team");
+    expect(notes[1].content).toBe("Retention set to 7 days");
+    expect(notes[1].author).toBeUndefined();
+  });
+
+  it("inline message with @note annotations includes notes in metadata", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          sends event OrderCreated {
+            version 1.0.0
+            @note("Schema v2 adds shippingAddress", author: "alice")
+          }
+          receives command CreateOrder {
+            version 1.0.0
+            @note("Validate idempotency key", priority: "high")
+          }
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const eventNode = graph.nodes.find(
+      (n) => n.type === "event" && n.label === "OrderCreated",
+    );
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.metadata.notes).toBeDefined();
+    const eventNotes = eventNode!.metadata.notes as Array<{
+      content: string;
+      author?: string;
+      priority?: string;
+    }>;
+    expect(eventNotes).toHaveLength(1);
+    expect(eventNotes[0].content).toBe("Schema v2 adds shippingAddress");
+    expect(eventNotes[0].author).toBe("alice");
+
+    const cmdNode = graph.nodes.find(
+      (n) => n.type === "command" && n.label === "CreateOrder",
+    );
+    expect(cmdNode).toBeDefined();
+    expect(cmdNode!.metadata.notes).toBeDefined();
+    const cmdNotes = cmdNode!.metadata.notes as Array<{
+      content: string;
+      author?: string;
+      priority?: string;
+    }>;
+    expect(cmdNotes).toHaveLength(1);
+    expect(cmdNotes[0].content).toBe("Validate idempotency key");
+    expect(cmdNotes[0].priority).toBe("high");
+  });
+
+  it("channel inside domain with @note annotations includes notes in metadata", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        domain Orders {
+          version 1.0.0
+          channel OrderEvents {
+            version 1.0.0
+            address "orders.events"
+            @note("Owned by platform team", author: "dave")
+          }
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const channelNode = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "OrderEvents",
+    );
+    expect(channelNode).toBeDefined();
+    expect(channelNode!.metadata.notes).toBeDefined();
+    const notes = channelNode!.metadata.notes as Array<{
+      content: string;
+      author?: string;
+    }>;
+    expect(notes).toHaveLength(1);
+    expect(notes[0].content).toBe("Owned by platform team");
+    expect(notes[0].author).toBe("dave");
+  });
+
+  it("channel route defined outside visualizer is resolved when channel is discovered via sends", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        name "View Name"
+
+        service Hello {
+          version 1.0.0
+          sends event HelloWorld to ChannelOne
+        }
+      }
+
+      channel ChannelOne {
+        version 1.0.0
+        address "topic"
+        route ChannelTwo
+      }
+
+      channel ChannelTwo {
+        version 1.0.0
+        address "topic"
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    // ChannelOne should exist (from sends to)
+    const ch1 = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "ChannelOne",
+    );
+    expect(ch1).toBeDefined();
+    expect(ch1!.metadata.address).toBe("topic");
+
+    // ChannelTwo should exist (from route)
+    const ch2 = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "ChannelTwo",
+    );
+    expect(ch2).toBeDefined();
+
+    // ChannelOne -> ChannelTwo (routes-to)
+    const routeEdge = graph.edges.find(
+      (e) =>
+        e.source === ch1!.id && e.target === ch2!.id && e.type === "routes-to",
+    );
+    expect(routeEdge).toBeDefined();
+  });
+
+  it("includes owners in node metadata", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        name "Test"
+
+        service OrderService {
+          version 1.0.0
+          owner orders-team
+          owner platform-team
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+    const svc = graph.nodes.find((n) => n.type === "service");
+    expect(svc).toBeDefined();
+    expect(svc!.metadata.owners).toEqual(["orders-team", "platform-team"]);
+  });
+
+  it("@api annotation enriched from top-level def via service receives", async () => {
+    const program = await parseProgram(`
+      query getHealth {
+        version 1.0.0
+        summary "Health check"
+        @api(method: "GET", path: "/health", statusCodes: "200")
+      }
+
+      service StatusAPI {
+        version 1.0.0
+        receives query getHealth@1.0.0
+      }
+
+      visualizer main {
+        name "Test"
+        service StatusAPI
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const queryNode = graph.nodes.find(
+      (n) => n.type === "query" && n.label === "getHealth",
+    );
+    expect(queryNode).toBeDefined();
+    expect(queryNode!.metadata.method).toBe("GET");
+    expect(queryNode!.metadata.path).toBe("/health");
+    expect(queryNode!.metadata.statusCodes).toEqual([200]);
+  });
+
+  it("command with @api annotation includes method, path, and statusCodes in metadata", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        command CreateOrder {
+          version 1.0.0
+          summary "Create a new order"
+          @api(method: "POST", path: "/orders", statusCodes: "200,401")
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const cmdNode = graph.nodes.find(
+      (n) => n.type === "command" && n.label === "CreateOrder",
+    );
+    expect(cmdNode).toBeDefined();
+    expect(cmdNode!.metadata.method).toBe("POST");
+    expect(cmdNode!.metadata.path).toBe("/orders");
+    expect(cmdNode!.metadata.statusCodes).toEqual([200, 401]);
+  });
+
+  it("query with @api annotation includes method and path in metadata", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        query GetOrders {
+          version 1.0.0
+          @api(method: "GET", path: "/orders")
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const queryNode = graph.nodes.find(
+      (n) => n.type === "query" && n.label === "GetOrders",
+    );
+    expect(queryNode).toBeDefined();
+    expect(queryNode!.metadata.method).toBe("GET");
+    expect(queryNode!.metadata.path).toBe("/orders");
+    expect(queryNode!.metadata.statusCodes).toBeUndefined();
+  });
+
+  // ─── Version resolution tests ──────────────────────────────
+
+  it("bare ref resolves to latest version when multiple versions exist", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        name "Order Service (Legacy)"
+        sends event OrderCreatedV1
+      }
+
+      service OrderService {
+        version 2.0.0
+        name "Order Service (New)"
+        sends event OrderCreatedV2
+      }
+
+      visualizer main {
+        service OrderService
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    // Bare ref should resolve to v2.0.0 (latest)
+    const svcNode = graph.nodes.find((n) => n.type === "service");
+    expect(svcNode).toBeDefined();
+    expect(svcNode!.metadata.version).toBe("2.0.0");
+    expect(svcNode!.label).toBe("Order Service (New)");
+  });
+
+  it("versioned ref resolves to exact version, not latest", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        name "Order Service (Legacy)"
+        sends event OrderCreatedV1
+      }
+
+      service OrderService {
+        version 2.0.0
+        name "Order Service (New)"
+        sends event OrderCreatedV2
+      }
+
+      visualizer main {
+        service OrderService@1.0.0
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const svcNode = graph.nodes.find((n) => n.type === "service");
+    expect(svcNode).toBeDefined();
+    expect(svcNode!.metadata.version).toBe("1.0.0");
+    expect(svcNode!.label).toBe("Order Service (Legacy)");
+  });
+
+  it("both versioned refs resolve to their correct definitions", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        name "Order Service (Legacy)"
+        summary "The original order service"
+        sends event OrderCreatedV1
+      }
+
+      service OrderService {
+        version 2.0.0
+        name "Order Service (New)"
+        summary "Rebuilt order service"
+        sends event OrderCreatedV2
+      }
+
+      visualizer main {
+        service OrderService@1.0.0
+        service OrderService@2.0.0
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const v1 = graph.nodes.find((n) => n.id === "service:OrderService@1.0.0");
+    const v2 = graph.nodes.find((n) => n.id === "service:OrderService@2.0.0");
+    expect(v1).toBeDefined();
+    expect(v2).toBeDefined();
+    expect(v1!.label).toBe("Order Service (Legacy)");
+    expect(v2!.label).toBe("Order Service (New)");
+    expect(v1!.metadata.summary).toBe("The original order service");
+    expect(v2!.metadata.summary).toBe("Rebuilt order service");
+
+    // Each should have correct sends edges
+    const v1Sends = graph.edges.find(
+      (e) => e.source === v1!.id && e.type === "sends",
+    );
+    const v2Sends = graph.edges.find(
+      (e) => e.source === v2!.id && e.type === "sends",
+    );
+    expect(v1Sends).toBeDefined();
+    expect(v2Sends).toBeDefined();
+    expect(v1Sends!.target).toContain("OrderCreatedV1");
+    expect(v2Sends!.target).toContain("OrderCreatedV2");
+  });
+
+  it("bare ref resolves to latest even when older version is defined last", async () => {
+    const program = await parseProgram(`
+      service OrderService {
+        version 3.0.0
+        name "Order Service V3"
+      }
+
+      service OrderService {
+        version 1.0.0
+        name "Order Service V1"
+      }
+
+      service OrderService {
+        version 2.0.0
+        name "Order Service V2"
+      }
+
+      visualizer main {
+        service OrderService
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const svcNode = graph.nodes.find((n) => n.type === "service");
+    expect(svcNode).toBeDefined();
+    expect(svcNode!.metadata.version).toBe("3.0.0");
+    expect(svcNode!.label).toBe("Order Service V3");
+  });
+
+  // ─── Nested definition inference tests ──────────────────────────────
+
+  it("flow ref infers type from service nested inside a domain", async () => {
+    const program = await parseProgram(`
+      domain Orders {
+        version 1.0.0
+        service OrderService {
+          version 1.0.0
+        }
+      }
+
+      event OrderCreated {
+        version 1.0.0
+      }
+
+      visualizer main {
+        flow OrderFlow {
+          version 1.0.0
+          OrderService -> OrderCreated
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const svcNode = graph.nodes.find((n) => n.label === "OrderService");
+    expect(svcNode).toBeDefined();
+    // Without the fix, this would be "step" because OrderService is nested in a domain
+    expect(svcNode!.type).toBe("service");
+
+    const eventNode = graph.nodes.find((n) => n.label === "OrderCreated");
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.type).toBe("event");
+  });
+
+  it("flow ref infers type from container nested inside a domain", async () => {
+    const program = await parseProgram(`
+      domain Inventory {
+        version 1.0.0
+        container InventoryDB {
+          version 1.0.0
+        }
+      }
+
+      service InventoryService {
+        version 1.0.0
+      }
+
+      visualizer main {
+        flow InventoryFlow {
+          version 1.0.0
+          InventoryService -> InventoryDB
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const containerNode = graph.nodes.find((n) => n.label === "InventoryDB");
+    expect(containerNode).toBeDefined();
+    // Without the fix, this would be "step" because InventoryDB is nested in a domain
+    expect(containerNode!.type).toBe("container");
+  });
+
+  // ─── Flow inside domain tests ─────────────────────────────────────
+
+  it("inline flow inside domain expands entry chain steps parented to domain", async () => {
+    const program = await parseProgram(`
+      event OrderCreated { version 1.0.0 }
+      service OrderService { version 1.0.0 }
+
+      visualizer main {
+        domain Orders {
+          version 1.0.0
+          flow OrderFlow {
+            version 1.0.0
+            OrderService -> OrderCreated
+          }
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const domainNode = graph.nodes.find((n) => n.type === "domain");
+    expect(domainNode).toBeDefined();
+
+    const svcNode = graph.nodes.find((n) => n.label === "OrderService");
+    expect(svcNode).toBeDefined();
+    expect(svcNode!.type).toBe("service");
+    expect(svcNode!.parentId).toBe(domainNode!.id);
+
+    const eventNode = graph.nodes.find((n) => n.label === "OrderCreated");
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.type).toBe("event");
+    expect(eventNode!.parentId).toBe(domainNode!.id);
+
+    const flowEdge = graph.edges.find((e) => e.type === "flow-step");
+    expect(flowEdge).toBeDefined();
+  });
+
+  it("inline flow inside domain with no steps renders as single flow node", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        domain Orders {
+          version 1.0.0
+          flow OrderFlow {
+            version 1.0.0
+            summary "A flow without steps"
+          }
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const flowNode = graph.nodes.find((n) => n.type === "flow");
+    expect(flowNode).toBeDefined();
+    expect(flowNode!.label).toBe("OrderFlow");
+    expect(flowNode!.metadata.summary).toBe("A flow without steps");
+
+    const domainNode = graph.nodes.find((n) => n.type === "domain");
+    expect(flowNode!.parentId).toBe(domainNode!.id);
+
+    const containsEdge = graph.edges.find(
+      (e) => e.type === "contains" && e.target === flowNode!.id,
+    );
+    expect(containsEdge).toBeDefined();
+  });
+
+  it("flow ref inside domain resolves and expands the flow definition", async () => {
+    const program = await parseProgram(`
+      event OrderCreated { version 1.0.0 }
+      service OrderService { version 1.0.0 }
+
+      flow OrderFlow {
+        version 1.0.0
+        OrderService -> OrderCreated
+      }
+
+      visualizer main {
+        domain Orders {
+          version 1.0.0
+          flow OrderFlow
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const domainNode = graph.nodes.find((n) => n.type === "domain");
+    expect(domainNode).toBeDefined();
+
+    const svcNode = graph.nodes.find((n) => n.label === "OrderService");
+    expect(svcNode).toBeDefined();
+    expect(svcNode!.parentId).toBe(domainNode!.id);
+
+    const eventNode = graph.nodes.find((n) => n.label === "OrderCreated");
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.parentId).toBe(domainNode!.id);
+
+    const flowEdge = graph.edges.find((e) => e.type === "flow-step");
+    expect(flowEdge).toBeDefined();
+  });
+
+  // ─── Data-product message type tests ──────────────────────────────
+
+  it("data-product input command creates a command node, not event", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        data-product OrderAnalytics {
+          version 1.0.0
+          input command PlaceOrder
+          input event OrderCreated
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const cmdNode = graph.nodes.find((n) => n.label === "PlaceOrder");
+    expect(cmdNode).toBeDefined();
+    expect(cmdNode!.type).toBe("command");
+
+    const eventNode = graph.nodes.find((n) => n.label === "OrderCreated");
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.type).toBe("event");
+  });
+
+  it("data-product input query creates a query node, not event", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        data-product OrderAnalytics {
+          version 1.0.0
+          input query GetOrders
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const queryNode = graph.nodes.find((n) => n.label === "GetOrders");
+    expect(queryNode).toBeDefined();
+    expect(queryNode!.type).toBe("query");
+  });
+
+  it("data-product output command creates a command node, not event", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        data-product OrderAnalytics {
+          version 1.0.0
+          output command ProcessOrder
+          output event OrderProcessed
+          output query GetAnalytics
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const cmdNode = graph.nodes.find((n) => n.label === "ProcessOrder");
+    expect(cmdNode).toBeDefined();
+    expect(cmdNode!.type).toBe("command");
+
+    const eventNode = graph.nodes.find((n) => n.label === "OrderProcessed");
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.type).toBe("event");
+
+    const queryNode = graph.nodes.find((n) => n.label === "GetAnalytics");
+    expect(queryNode).toBeDefined();
+    expect(queryNode!.type).toBe("query");
+  });
+
+  // ─── Receives from multiple channels tests ──────────────────────────────
+
+  it("receives from multiple channels creates routes-to edges for all channels", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        service NotificationService {
+          version 1.0.0
+          receives event OrderCreated from channel-a, channel-b
+        }
+      }
+    `);
+
+    const graph = astToGraph(program);
+
+    const eventNode = graph.nodes.find(
+      (n) => n.type === "event" && n.label === "OrderCreated",
+    );
+    const chA = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "channel-a",
+    );
+    const chB = graph.nodes.find(
+      (n) => n.type === "channel" && n.label === "channel-b",
+    );
+    expect(eventNode).toBeDefined();
+    expect(chA).toBeDefined();
+    expect(chB).toBeDefined();
+
+    // Both channels should have a routes-to edge from the message
+    const routeToA = graph.edges.find(
+      (e) =>
+        e.source === eventNode!.id &&
+        e.target === chA!.id &&
+        e.type === "routes-to",
+    );
+    const routeToB = graph.edges.find(
+      (e) =>
+        e.source === eventNode!.id &&
+        e.target === chB!.id &&
+        e.type === "routes-to",
+    );
+    expect(routeToA).toBeDefined();
+    // Without the fix, this would be undefined because the dedupe check was too broad
+    expect(routeToB).toBeDefined();
+
+    // Both channels should have receives edges to the service
+    const svcNode = graph.nodes.find((n) => n.type === "service");
+    const chAReceives = graph.edges.find(
+      (e) =>
+        e.source === chA!.id &&
+        e.target === svcNode!.id &&
+        e.type === "receives",
+    );
+    const chBReceives = graph.edges.find(
+      (e) =>
+        e.source === chB!.id &&
+        e.target === svcNode!.id &&
+        e.type === "receives",
+    );
+    expect(chAReceives).toBeDefined();
+    expect(chBReceives).toBeDefined();
+  });
+
+  it("versioned event ref in visualizer resolves to top-level definition", async () => {
+    const program = await parseProgram(`
+      event OrderCreated {
+        version 1.0.0
+        summary "An order was created"
+      }
+
+      visualizer main {
+        event OrderCreated@1.0.0
+      }
+    `);
+
+    const graph = astToGraph(program);
+    const eventNode = graph.nodes.find(
+      (n) => n.id === "event:OrderCreated@1.0.0",
+    );
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.type).toBe("event");
+    expect(eventNode!.metadata.version).toBe("1.0.0");
+    expect(eventNode!.metadata.summary).toBe("An order was created");
+  });
+
+  it("versioned command ref in visualizer creates node", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        command CreateOrder@2.0.0
+      }
+    `);
+
+    const graph = astToGraph(program);
+    const cmdNode = graph.nodes.find(
+      (n) => n.id === "command:CreateOrder@2.0.0",
+    );
+    expect(cmdNode).toBeDefined();
+    expect(cmdNode!.type).toBe("command");
+    expect(cmdNode!.metadata.version).toBe("2.0.0");
+  });
+
+  it("versioned query ref in visualizer creates node", async () => {
+    const program = await parseProgram(`
+      visualizer main {
+        query GetOrder@1.0.0
+      }
+    `);
+
+    const graph = astToGraph(program);
+    const queryNode = graph.nodes.find((n) => n.id === "query:GetOrder@1.0.0");
+    expect(queryNode).toBeDefined();
+    expect(queryNode!.type).toBe("query");
+    expect(queryNode!.metadata.version).toBe("1.0.0");
+  });
+
+  it("unversioned event ref resolves to latest top-level definition", async () => {
+    const program = await parseProgram(`
+      event OrderCreated {
+        version 1.0.0
+        summary "v1"
+      }
+      event OrderCreated {
+        version 2.0.0
+        summary "v2"
+      }
+
+      visualizer main {
+        event OrderCreated
+      }
+    `);
+
+    const graph = astToGraph(program);
+    const eventNode = graph.nodes.find(
+      (n) => n.type === "event" && n.id.startsWith("event:OrderCreated"),
+    );
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.metadata.version).toBe("2.0.0");
+    expect(eventNode!.metadata.summary).toBe("v2");
+  });
+});
diff --git a/packages/language-server/test/parsing.test.ts b/packages/language-server/test/parsing.test.ts
new file mode 100644
index 000000000..817639e36
--- /dev/null
+++ b/packages/language-server/test/parsing.test.ts
@@ -0,0 +1,1539 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { createEcServices } from "../src/ec-module.js";
+import { EmptyFileSystem } from "langium";
+import { parseDocument } from "langium/test";
+import type { Program } from "../src/generated/ast.js";
+import {
+  isDomainDef,
+  isServiceDef,
+  isSendsStmt,
+  isReceivesStmt,
+  isToClause,
+  isFromClause,
+  isChannelDef,
+  isContainerDef,
+  isFlowDef,
+  isUserDef,
+  isTeamDef,
+  isDataProductDef,
+  isDiagramDef,
+  isEventDef,
+  isCommandDef,
+  isQueryDef,
+  isSubdomainDef,
+  isServiceRefStmt,
+  isActorDef,
+  isExternalSystemDef,
+} from "../src/generated/ast.js";
+import * as utils from "../src/ast-utils.js";
+
+const services = createEcServices(EmptyFileSystem);
+
+async function parseProgram(input: string) {
+  const doc = await parseDocument<Program>(services.Ec, input);
+  return doc;
+}
+
+// ---------------------------------------------------------------------------
+// 1. Simple domain
+// ---------------------------------------------------------------------------
+describe("Simple domain", () => {
+  it("parses a domain with version and summary", async () => {
+    const doc = await parseProgram(`
+      domain Orders {
+        version 1.0.0
+        summary "Order management"
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const program = doc.parseResult.value;
+    expect(program.definitions).toHaveLength(1);
+
+    const def = program.definitions[0];
+    expect(isDomainDef(def)).toBe(true);
+    if (isDomainDef(def)) {
+      expect(def.name).toBe("Orders");
+      expect(utils.getVersion(def.body)).toBe("1.0.0");
+      expect(utils.getSummary(def.body)).toBe("Order management");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Domain with services
+// ---------------------------------------------------------------------------
+describe("Domain with services", () => {
+  it("parses a nested service inside a domain", async () => {
+    const doc = await parseProgram(`
+      domain Payment {
+        version 1.0.0
+
+        service PaymentService {
+          version 2.0.0
+          summary "Handles payments"
+        }
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const domain = doc.parseResult.value.definitions[0];
+    expect(isDomainDef(domain)).toBe(true);
+    if (isDomainDef(domain)) {
+      const svcs = utils.getServices(domain.body);
+      expect(svcs).toHaveLength(1);
+      expect(svcs[0].name).toBe("PaymentService");
+      expect(utils.getVersion(svcs[0].body)).toBe("2.0.0");
+      expect(utils.getSummary(svcs[0].body)).toBe("Handles payments");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. Sends with inline definition
+// ---------------------------------------------------------------------------
+describe("Sends with inline definition", () => {
+  it("parses sends event with an inline body", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+
+        sends event OrderCreated {
+          version 1.0.0
+          summary "A new order"
+        }
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    expect(isServiceDef(svc)).toBe(true);
+    if (isServiceDef(svc)) {
+      const sends = utils.getSends(svc.body);
+      expect(sends).toHaveLength(1);
+      expect(sends[0].messageName).toBe("OrderCreated");
+      expect(sends[0].messageType).toBe("event");
+      expect(sends[0].body.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Channel routing (to and from)
+// ---------------------------------------------------------------------------
+describe("Channel routing", () => {
+  it("parses sends to channel", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        sends event OrderCreated to orders-topic
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const sends = utils.getSends(svc.body);
+      expect(sends).toHaveLength(1);
+      expect(sends[0].channelClause).toBeDefined();
+      expect(isToClause(sends[0].channelClause)).toBe(true);
+      if (isToClause(sends[0].channelClause)) {
+        expect(sends[0].channelClause.channels).toHaveLength(1);
+        expect(sends[0].channelClause.channels[0].channelName).toBe(
+          "orders-topic",
+        );
+      }
+    }
+  });
+
+  it("parses receives from channel with delivery mode", async () => {
+    const doc = await parseProgram(`
+      service PaymentService {
+        version 1.0.0
+        receives event PaymentProcessed from payment-queue delivery pull
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const receives = utils.getReceives(svc.body);
+      expect(receives).toHaveLength(1);
+      expect(receives[0].channelClause).toBeDefined();
+      expect(isFromClause(receives[0].channelClause)).toBe(true);
+      if (isFromClause(receives[0].channelClause)) {
+        expect(receives[0].channelClause.channels).toHaveLength(1);
+        expect(receives[0].channelClause.channels[0].channelName).toBe(
+          "payment-queue",
+        );
+        expect(receives[0].channelClause.deliveryMode).toBe("pull");
+      }
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4b. Template channel names (e.g. inventory.{env}.events)
+// ---------------------------------------------------------------------------
+describe("Template channel names", () => {
+  it("parses a channel definition with template parameters in the name", async () => {
+    const doc = await parseProgram(`
+      channel inventory.{env}.events {
+        version 1.0.0
+        name "Inventory Events Channel"
+        address "inventory.{env}.events"
+        protocol "kafka"
+        summary "Central event stream for inventory events"
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const ch = doc.parseResult.value.definitions[0];
+    if (isChannelDef(ch)) {
+      expect(ch.name).toBe("inventory.{env}.events");
+    }
+  });
+
+  it("parses sends to a template channel name", async () => {
+    const doc = await parseProgram(`
+      service InventoryService {
+        version 1.0.0
+        sends event InventoryAdjusted to inventory.{env}.events
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const sends = utils.getSends(svc.body);
+      expect(sends).toHaveLength(1);
+      if (isToClause(sends[0].channelClause)) {
+        expect(sends[0].channelClause.channels[0].channelName).toBe(
+          "inventory.{env}.events",
+        );
+      }
+    }
+  });
+
+  it("parses receives from a template channel name with version", async () => {
+    const doc = await parseProgram(`
+      service InventoryService {
+        version 1.0.0
+        receives command UpdateInventory from inventory.{env}.events@1.0.0
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const receives = utils.getReceives(svc.body);
+      expect(receives).toHaveLength(1);
+      if (isFromClause(receives[0].channelClause)) {
+        expect(receives[0].channelClause.channels[0].channelName).toBe(
+          "inventory.{env}.events",
+        );
+        expect(receives[0].channelClause.channels[0].channelVersion).toBe(
+          "1.0.0",
+        );
+      }
+    }
+  });
+
+  it("parses a template channel name with multiple template segments", async () => {
+    const doc = await parseProgram(`
+      channel topic.{region}.{env}.orders {
+        version 1.0.0
+        summary "Multi-region orders topic"
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const ch = doc.parseResult.value.definitions[0];
+    if (isChannelDef(ch)) {
+      expect(ch.name).toBe("topic.{region}.{env}.orders");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. Sends to channel with inline body
+// ---------------------------------------------------------------------------
+describe("Sends to channel with inline body", () => {
+  it("parses sends with both channel clause and inline body", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        sends event OrderCancelled to order-events {
+          version 1.0.0
+        }
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const sends = utils.getSends(svc.body);
+      expect(sends).toHaveLength(1);
+      expect(sends[0].channelClause).toBeDefined();
+      expect(isToClause(sends[0].channelClause)).toBe(true);
+      expect(sends[0].body.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. Channel definition
+// ---------------------------------------------------------------------------
+describe("Channel definition", () => {
+  it("parses a channel with address, protocol, and parameter", async () => {
+    const doc = await parseProgram(`
+      channel orders-topic {
+        version 1.0.0
+        summary "Order events topic"
+        address "orders.events.v1"
+        protocol "Kafka"
+
+        parameter region {
+          description "AWS region"
+          default "us-east-1"
+          enum ["us-east-1", "eu-west-1"]
+        }
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const ch = doc.parseResult.value.definitions[0];
+    expect(isChannelDef(ch)).toBe(true);
+    if (isChannelDef(ch)) {
+      expect(ch.name).toBe("orders-topic");
+      expect(utils.getAddress(ch.body)).toBe("orders.events.v1");
+      expect(utils.getProtocols(ch.body)).toContain("Kafka");
+      expect(utils.getParameters(ch.body)).toHaveLength(1);
+    }
+  });
+
+  it("rejects message statement inside a channel", async () => {
+    const doc = await parseProgram(`
+      channel orders-topic {
+        version 1.0.0
+        message event OrderCreated@1.0.0
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors.length).toBeGreaterThan(0);
+  });
+
+  it("parses a channel with route statements", async () => {
+    const doc = await parseProgram(`
+      channel KafkaRaw {
+        version 1.0.0
+        protocol "Kafka"
+        route KafkaFiltered
+        route MqttBridge@2.0.0
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const ch = doc.parseResult.value.definitions[0];
+    expect(isChannelDef(ch)).toBe(true);
+    if (isChannelDef(ch)) {
+      const routes = utils.getRoutes(ch.body);
+      expect(routes).toHaveLength(2);
+      expect(routes[0].ref.name).toBe("KafkaFiltered");
+      expect(routes[0].ref.version).toBeUndefined();
+      expect(routes[1].ref.name).toBe("MqttBridge");
+      expect(routes[1].ref.version).toBe("2.0.0");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 7. Container
+// ---------------------------------------------------------------------------
+describe("Container definition", () => {
+  it("parses a container with container-type, technology, access-mode, classification", async () => {
+    const doc = await parseProgram(`
+      container orders-db {
+        version 1.0.0
+        summary "Orders database"
+        container-type database
+        technology "postgres@15"
+        access-mode readWrite
+        classification internal
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const container = doc.parseResult.value.definitions[0];
+    expect(isContainerDef(container)).toBe(true);
+    if (isContainerDef(container)) {
+      expect(container.name).toBe("orders-db");
+      expect(utils.getContainerType(container.body)).toBe("database");
+      expect(utils.getTechnology(container.body)).toBe("postgres@15");
+      expect(utils.getAccessMode(container.body)).toBe("readWrite");
+      expect(utils.getClassification(container.body)).toBe("internal");
+    }
+  });
+
+  it("parses a container with deprecated", async () => {
+    const doc = await parseProgram(`
+      container testing-db {
+        version 1.0.0
+        summary "Testing database"
+        container-type database
+        deprecated true
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const container = doc.parseResult.value.definitions[0];
+    expect(isContainerDef(container)).toBe(true);
+    if (isContainerDef(container)) {
+      expect(utils.getDeprecated(container.body)).toBe(true);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 9. Flow with arrow-based chains
+// ---------------------------------------------------------------------------
+describe("Flow with when blocks", () => {
+  it("parses a flow with an entry chain", async () => {
+    const doc = await parseProgram(`
+      flow OrderFulfillment {
+        version 1.0.0
+        summary "Order fulfillment process"
+
+        Customer "places an order" -> PlaceOrder -> OrderService "creates the order" -> OrderCreated
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const flow = doc.parseResult.value.definitions[0];
+    expect(isFlowDef(flow)).toBe(true);
+    if (isFlowDef(flow)) {
+      expect(flow.name).toBe("OrderFulfillment");
+      const chains = utils.getFlowEntryChains(flow.body);
+      expect(chains).toHaveLength(1);
+      expect(chains[0].sources).toHaveLength(1);
+      expect(chains[0].sources[0].name).toBe("Customer");
+      expect(chains[0].sources[0].label).toBe("places an order");
+      expect(chains[0].targets).toHaveLength(3);
+    }
+  });
+
+  it("parses a when block with actions", async () => {
+    const doc = await parseProgram(`
+      flow PaymentFlow {
+        version 1.0.0
+
+        when OrderCreated
+          PaymentService "processes the payment"
+            -> PaymentProcessed
+          InventoryService "reserves stock"
+            -> StockReserved
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const flow = doc.parseResult.value.definitions[0];
+    if (isFlowDef(flow)) {
+      const blocks = utils.getFlowWhenBlocks(flow.body);
+      expect(blocks).toHaveLength(1);
+      expect(blocks[0].triggers).toHaveLength(1);
+      expect(blocks[0].triggers[0].name).toBe("OrderCreated");
+      expect(blocks[0].actions).toHaveLength(2);
+      expect(blocks[0].actions[0].ref.name).toBe("PaymentService");
+      expect(blocks[0].actions[0].outputs).toHaveLength(1);
+      expect(blocks[0].actions[0].outputs[0].target.name).toBe(
+        "PaymentProcessed",
+      );
+    }
+  });
+
+  it("parses labeled outputs (success/failure)", async () => {
+    const doc = await parseProgram(`
+      flow BranchFlow {
+        version 1.0.0
+
+        when OrderCreated
+          PaymentService "processes payment"
+            -> "success": PaymentProcessed
+            -> "failure": PaymentFailed
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const flow = doc.parseResult.value.definitions[0];
+    if (isFlowDef(flow)) {
+      const blocks = utils.getFlowWhenBlocks(flow.body);
+      const action = blocks[0].actions[0];
+      expect(action.outputs).toHaveLength(2);
+      expect(action.outputs[0].label).toBe("success");
+      expect(action.outputs[0].target.name).toBe("PaymentProcessed");
+      expect(action.outputs[1].label).toBe("failure");
+
+      expect(action.outputs[1].target.name).toBe("PaymentFailed");
+    }
+  });
+
+  it("parses convergence with 'and' keyword", async () => {
+    const doc = await parseProgram(`
+      flow ConvergeFlow {
+        version 1.0.0
+
+        when PaymentProcessed and StockReserved
+          FulfillmentService "ships the order"
+            -> OrderShipped
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const flow = doc.parseResult.value.definitions[0];
+    if (isFlowDef(flow)) {
+      const blocks = utils.getFlowWhenBlocks(flow.body);
+      expect(blocks[0].triggers).toHaveLength(2);
+      expect(blocks[0].triggers[0].name).toBe("PaymentProcessed");
+      expect(blocks[0].triggers[1].name).toBe("StockReserved");
+    }
+  });
+
+  it("parses a terminal action with no output", async () => {
+    const doc = await parseProgram(`
+      flow NotifyFlow {
+        version 1.0.0
+
+        when PaymentFailed
+          NotificationService "notifies the customer of failure"
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const flow = doc.parseResult.value.definitions[0];
+    if (isFlowDef(flow)) {
+      const blocks = utils.getFlowWhenBlocks(flow.body);
+      expect(blocks[0].actions).toHaveLength(1);
+      expect(blocks[0].actions[0].ref.name).toBe("NotificationService");
+      expect(blocks[0].actions[0].outputs).toHaveLength(0);
+    }
+  });
+
+  it("parses a full flow with entry chain and multiple when blocks", async () => {
+    const doc = await parseProgram(`
+      flow OrderFulfillment {
+        version 1.0.0
+        name "Order Fulfillment"
+
+        Customer "places an order" -> PlaceOrder -> OrderService -> OrderCreated
+
+        when OrderCreated
+          PaymentService "processes the payment"
+            -> "success": PaymentProcessed
+            -> "failure": PaymentFailed
+          InventoryService "reserves stock"
+            -> StockReserved
+
+        when PaymentFailed
+          NotificationService "notifies the customer"
+
+        when PaymentProcessed and StockReserved
+          FulfillmentService "ships the order" -> OrderShipped
+
+        when OrderShipped
+          WarehouseWMS "syncs with legacy WMS"
+          NotificationService "notifies the customer" -> CustomerNotified
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const flow = doc.parseResult.value.definitions[0];
+    if (isFlowDef(flow)) {
+      const chains = utils.getFlowEntryChains(flow.body);
+      const blocks = utils.getFlowWhenBlocks(flow.body);
+      expect(chains).toHaveLength(1);
+      expect(blocks).toHaveLength(4);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 10. User and team
+// ---------------------------------------------------------------------------
+describe("User and team definitions", () => {
+  it("parses a user with name, email, and role", async () => {
+    const doc = await parseProgram(`
+      user dboyne {
+        name "David Boyne"
+        email "david@example.com"
+        role "Principal Engineer"
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const user = doc.parseResult.value.definitions[0];
+    expect(isUserDef(user)).toBe(true);
+    if (isUserDef(user)) {
+      expect(user.name).toBe("dboyne");
+    }
+  });
+
+  it("parses a team with members", async () => {
+    const doc = await parseProgram(`
+      team payment-team {
+        name "Payment Team"
+        summary "Handles all payment processing"
+        email "payments@company.com"
+        member dboyne
+        member jane-doe
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const team = doc.parseResult.value.definitions[0];
+    expect(isTeamDef(team)).toBe(true);
+    if (isTeamDef(team)) {
+      expect(team.name).toBe("payment-team");
+    }
+  });
+
+  it("parses a user with avatar", async () => {
+    const doc = await parseProgram(`
+      user jdoe {
+        name "Jane Doe"
+        avatar "https://example.com/jdoe.png"
+        role "Engineer"
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const user = doc.parseResult.value.definitions[0];
+    expect(isUserDef(user)).toBe(true);
+  });
+
+  it("parses a team with avatar and role", async () => {
+    const doc = await parseProgram(`
+      team platform-team {
+        name "Platform Team"
+        avatar "https://example.com/platform.png"
+        role "Platform Engineering"
+        summary "Platform infrastructure"
+        member dboyne
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const team = doc.parseResult.value.definitions[0];
+    expect(isTeamDef(team)).toBe(true);
+    if (isTeamDef(team)) {
+      expect(team.name).toBe("platform-team");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 11. Annotations
+// ---------------------------------------------------------------------------
+describe("Annotations", () => {
+  it("parses an annotation with positional and named args", async () => {
+    const doc = await parseProgram(`
+      domain Orders {
+        version 1.0.0
+        @badge("Production", bg: "#22c55e", text: "#fff")
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const domain = doc.parseResult.value.definitions[0];
+    if (isDomainDef(domain)) {
+      const annotations = utils.getAnnotations(domain.body);
+      expect(annotations).toHaveLength(1);
+      expect(annotations[0].name).toBe("badge");
+      expect(annotations[0].args).toHaveLength(3);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 12. Data product
+// ---------------------------------------------------------------------------
+describe("Data product definition", () => {
+  it("parses a data product with input and output with contract", async () => {
+    const doc = await parseProgram(`
+      data-product customer-analytics {
+        version 1.0.0
+        summary "Customer analytics data product"
+
+        input event OrderCreated
+        output event CustomerReport {
+          contract {
+            path "schemas/report.avro"
+            name "CustomerReport"
+            type "avro"
+          }
+        }
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const dp = doc.parseResult.value.definitions[0];
+    expect(isDataProductDef(dp)).toBe(true);
+    if (isDataProductDef(dp)) {
+      expect(dp.name).toBe("customer-analytics");
+      expect(utils.getInputs(dp.body)).toHaveLength(1);
+      expect(utils.getOutputs(dp.body)).toHaveLength(1);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 13. Diagram
+// ---------------------------------------------------------------------------
+describe("Diagram definition", () => {
+  it("parses a simple diagram with name and summary", async () => {
+    const doc = await parseProgram(`
+      diagram system-overview {
+        version 1.0.0
+        name "System Overview"
+        summary "High-level architecture diagram"
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const diag = doc.parseResult.value.definitions[0];
+    expect(isDiagramDef(diag)).toBe(true);
+    if (isDiagramDef(diag)) {
+      expect(diag.name).toBe("system-overview");
+      expect(utils.getSummary(diag.body)).toBe(
+        "High-level architecture diagram",
+      );
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 14. Writes-to and reads-from
+// ---------------------------------------------------------------------------
+describe("Writes-to and reads-from", () => {
+  it("parses writes-to and reads-from statements in a service", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        writes-to container orders-db
+        reads-from container analytics-db
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const writesTo = utils.getWritesToRefs(svc.body);
+      expect(writesTo).toHaveLength(1);
+      const readsFrom = utils.getReadsFromRefs(svc.body);
+      expect(readsFrom).toHaveLength(1);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 15. Subdomains
+// ---------------------------------------------------------------------------
+describe("Subdomains", () => {
+  it("parses a subdomain inside a domain with a service", async () => {
+    const doc = await parseProgram(`
+      domain Commerce {
+        version 1.0.0
+
+        subdomain Checkout {
+          version 1.0.0
+          summary "Checkout subdomain"
+
+          service CheckoutService {
+            version 1.0.0
+          }
+        }
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const domain = doc.parseResult.value.definitions[0];
+    if (isDomainDef(domain)) {
+      const subdomains = utils.getSubdomains(domain.body);
+      expect(subdomains).toHaveLength(1);
+      expect(subdomains[0].name).toBe("Checkout");
+      const subServices = utils.getServices(subdomains[0].body);
+      expect(subServices).toHaveLength(1);
+      expect(subServices[0].name).toBe("CheckoutService");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 16. Standalone events
+// ---------------------------------------------------------------------------
+describe("Standalone events", () => {
+  it("parses a standalone event without channel refs", async () => {
+    const doc = await parseProgram(`
+      event OrderCreated {
+        version 1.0.0
+        summary "Order was created"
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const evt = doc.parseResult.value.definitions[0];
+    expect(isEventDef(evt)).toBe(true);
+    if (isEventDef(evt)) {
+      expect(evt.name).toBe("OrderCreated");
+    }
+  });
+
+  it("rejects channel statement inside a message", async () => {
+    const doc = await parseProgram(`
+      event OrderCreated {
+        version 1.0.0
+        channel orders-topic
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors.length).toBeGreaterThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 17. Owner statements
+// ---------------------------------------------------------------------------
+describe("Owner statements", () => {
+  it("parses owner references in a service", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        owner orders-team
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const owners = utils.getOwners(svc.body);
+      expect(owners).toHaveLength(1);
+      expect(owners[0]).toBe("orders-team");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 18. Draft statements
+// ---------------------------------------------------------------------------
+describe("Draft statements", () => {
+  it("parses draft in a service", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        draft true
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+  });
+
+  it("parses draft in a domain", async () => {
+    const doc = await parseProgram(`
+      domain Orders {
+        version 1.0.0
+        draft true
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+  });
+
+  it("parses draft in an event", async () => {
+    const doc = await parseProgram(`
+      event OrderCreated {
+        version 1.0.0
+        draft true
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+  });
+
+  it("parses draft in a container", async () => {
+    const doc = await parseProgram(`
+      container orders-db {
+        version 1.0.0
+        draft true
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+  });
+
+  it("parses draft in a data product", async () => {
+    const doc = await parseProgram(`
+      data-product OrderAnalytics {
+        version 1.0.0
+        draft true
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 19. Service references inside domains
+// ---------------------------------------------------------------------------
+describe("Service references inside domains", () => {
+  it("parses a service reference with version inside a domain", async () => {
+    const doc = await parseProgram(`
+      domain Name {
+        version 1.0.0
+        service Random@1.0.0
+      }
+
+      service Random {
+        version 1.0.0
+        summary "This is really cool"
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const domain = doc.parseResult.value.definitions[0];
+    expect(isDomainDef(domain)).toBe(true);
+    if (isDomainDef(domain)) {
+      const serviceRefs = utils.getServiceRefs(domain.body);
+      expect(serviceRefs).toHaveLength(1);
+      expect(serviceRefs[0].ref.name).toBe("Random");
+      expect(serviceRefs[0].ref.version).toBe("1.0.0");
+    }
+  });
+
+  it("parses a service reference without version inside a domain", async () => {
+    const doc = await parseProgram(`
+      domain Name {
+        version 1.0.0
+        service Random
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const domain = doc.parseResult.value.definitions[0];
+    if (isDomainDef(domain)) {
+      const serviceRefs = utils.getServiceRefs(domain.body);
+      expect(serviceRefs).toHaveLength(1);
+      expect(serviceRefs[0].ref.name).toBe("Random");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 20. Visualizer
+// ---------------------------------------------------------------------------
+describe("Visualizer", () => {
+  it("parses a visualizer with inline definitions", async () => {
+    const doc = await parseProgram(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+          sends event OrderCreated
+        }
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const viz = doc.parseResult.value.definitions[0];
+    expect(viz.$type).toBe("VisualizerDef");
+    expect(viz.name).toBe("main");
+  });
+
+  it("parses a visualizer with service references", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+      }
+
+      visualizer main {
+        service OrderService@1.0.0
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    expect(doc.parseResult.value.definitions).toHaveLength(2);
+    const viz = doc.parseResult.value.definitions[1];
+    expect(viz.$type).toBe("VisualizerDef");
+  });
+
+  it("parses a visualizer with container reference", async () => {
+    const doc = await parseProgram(`
+      visualizer main {
+        container OrdersDB@1.0.0
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+  });
+
+  it("parses multiple visualizer blocks", async () => {
+    const doc = await parseProgram(`
+      visualizer overview {
+        service OrderService {
+          version 1.0.0
+        }
+      }
+
+      visualizer detailed {
+        service OrderService {
+          version 1.0.0
+          sends event OrderCreated
+        }
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const defs = doc.parseResult.value.definitions;
+    expect(defs).toHaveLength(2);
+    expect(defs[0].$type).toBe("VisualizerDef");
+    expect(defs[1].$type).toBe("VisualizerDef");
+    expect(defs[0].name).toBe("overview");
+    expect(defs[1].name).toBe("detailed");
+  });
+
+  it("parses a visualizer with animated property", async () => {
+    const doc = await parseProgram(`
+      visualizer main {
+        animated true
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+  });
+
+  it("parses a visualizer with versioned event reference", async () => {
+    const doc = await parseProgram(`
+      visualizer main {
+        event OrderCreated@1.0.0
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+  });
+
+  it("parses a visualizer with versioned command reference", async () => {
+    const doc = await parseProgram(`
+      visualizer main {
+        command CreateOrder@2.0.0
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+  });
+
+  it("parses a visualizer with versioned query reference", async () => {
+    const doc = await parseProgram(`
+      visualizer main {
+        query GetOrder@1.0.0
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+  });
+
+  it("parses a visualizer mixing versioned message refs and inline defs", async () => {
+    const doc = await parseProgram(`
+      event OrderCreated {
+        version 1.0.0
+      }
+
+      visualizer main {
+        event OrderCreated@1.0.0
+        service OrderService {
+          version 1.0.0
+          sends event OrderCreated@1.0.0
+        }
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Multiple channels and @ version syntax
+// ---------------------------------------------------------------------------
+describe("Multiple channels with comma-separated syntax", () => {
+  it("parses sends to multiple channels", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        sends event OrderCreated to orders-topic, backup-topic, audit-topic
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const sends = utils.getSends(svc.body);
+      expect(sends).toHaveLength(1);
+      expect(sends[0].channelClause).toBeDefined();
+      expect(isToClause(sends[0].channelClause)).toBe(true);
+      if (isToClause(sends[0].channelClause)) {
+        expect(sends[0].channelClause.channels).toHaveLength(3);
+        expect(sends[0].channelClause.channels[0].channelName).toBe(
+          "orders-topic",
+        );
+        expect(sends[0].channelClause.channels[1].channelName).toBe(
+          "backup-topic",
+        );
+        expect(sends[0].channelClause.channels[2].channelName).toBe(
+          "audit-topic",
+        );
+      }
+    }
+  });
+
+  it("parses receives from multiple channels", async () => {
+    const doc = await parseProgram(`
+      service PaymentService {
+        version 1.0.0
+        receives event PaymentProcessed from payment-events, payment-retry
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const receives = utils.getReceives(svc.body);
+      expect(receives).toHaveLength(1);
+      expect(receives[0].channelClause).toBeDefined();
+      expect(isFromClause(receives[0].channelClause)).toBe(true);
+      if (isFromClause(receives[0].channelClause)) {
+        expect(receives[0].channelClause.channels).toHaveLength(2);
+        expect(receives[0].channelClause.channels[0].channelName).toBe(
+          "payment-events",
+        );
+        expect(receives[0].channelClause.channels[1].channelName).toBe(
+          "payment-retry",
+        );
+      }
+    }
+  });
+
+  it("parses multiple channels with delivery mode", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        sends event OrderCreated to orders-topic, backup-topic delivery push
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const sends = utils.getSends(svc.body);
+      expect(sends).toHaveLength(1);
+      expect(isToClause(sends[0].channelClause)).toBe(true);
+      if (isToClause(sends[0].channelClause)) {
+        expect(sends[0].channelClause.channels).toHaveLength(2);
+        expect(sends[0].channelClause.deliveryMode).toBe("push");
+      }
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// @note annotation
+// ---------------------------------------------------------------------------
+describe("@note annotation", () => {
+  it("parses @note with simple string", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        @note("Come back later")
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const annotations = utils.getAnnotations(svc.body);
+      expect(annotations).toHaveLength(1);
+      expect(annotations[0].name).toBe("note");
+    }
+  });
+
+  it("parses @note with named parameters", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        @note("Needs review", author: "dboyne", priority: "high")
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const annotations = utils.getAnnotations(svc.body);
+      expect(annotations).toHaveLength(1);
+      expect(annotations[0].args).toHaveLength(3);
+    }
+  });
+
+  it("parses multiple @note annotations on same resource", async () => {
+    const doc = await parseProgram(`
+      event OrderCreated {
+        version 1.0.0
+        @note("First note")
+        @note("Second note")
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+
+    const evt = doc.parseResult.value.definitions[0];
+    if (isEventDef(evt)) {
+      const annotations = utils.getAnnotations(evt.body);
+      expect(annotations).toHaveLength(2);
+      expect(annotations[0].name).toBe("note");
+      expect(annotations[1].name).toBe("note");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// @api annotation
+// ---------------------------------------------------------------------------
+describe("@api annotation", () => {
+  it("parses @api with method and path on a command", async () => {
+    const doc = await parseProgram(`
+      command CreateOrder {
+        version 1.0.0
+        @api(method: "POST", path: "/orders")
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+
+    const cmd = doc.parseResult.value.definitions[0];
+    if (isCommandDef(cmd)) {
+      const annotations = utils.getAnnotations(cmd.body);
+      expect(annotations).toHaveLength(1);
+      expect(annotations[0].name).toBe("api");
+      expect(annotations[0].args).toHaveLength(2);
+    }
+  });
+
+  it("parses @api with method, path, and statusCodes on a query", async () => {
+    const doc = await parseProgram(`
+      query GetOrders {
+        version 1.0.0
+        @api(method: "GET", path: "/orders", statusCodes: "200,401")
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+
+    const qry = doc.parseResult.value.definitions[0];
+    if (isQueryDef(qry)) {
+      const annotations = utils.getAnnotations(qry.body);
+      expect(annotations).toHaveLength(1);
+      expect(annotations[0].name).toBe("api");
+      expect(annotations[0].args).toHaveLength(3);
+    }
+  });
+
+  it("parses @api on an inline message inside sends", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        sends command CreateOrder {
+          version 1.0.0
+          @api(method: "POST", path: "/orders", statusCodes: "201")
+        }
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const sends = utils.getSends(svc.body);
+      expect(sends).toHaveLength(1);
+      const annotations = utils.getAnnotations(sends[0].body);
+      expect(annotations).toHaveLength(1);
+      expect(annotations[0].name).toBe("api");
+    }
+  });
+
+  it("parses @api with path containing parameters", async () => {
+    const doc = await parseProgram(`
+      query GetOrder {
+        version 1.0.0
+        @api(method: "GET", path: "/orders/{orderId}")
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+
+    const qry = doc.parseResult.value.definitions[0];
+    if (isQueryDef(qry)) {
+      const annotations = utils.getAnnotations(qry.body);
+      expect(annotations).toHaveLength(1);
+      expect(annotations[0].name).toBe("api");
+    }
+  });
+});
+
+describe("@ version syntax", () => {
+  it("parses message reference with @ version", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        sends event OrderCreated@2.0.0
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const sends = utils.getSends(svc.body);
+      expect(sends).toHaveLength(1);
+      expect(sends[0].messageName).toBe("OrderCreated");
+      expect(sends[0].version).toBe("2.0.0");
+    }
+  });
+
+  it("parses channel reference with @ version", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        sends event OrderCreated to orders-topic@1.0.0
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const sends = utils.getSends(svc.body);
+      expect(sends).toHaveLength(1);
+      expect(isToClause(sends[0].channelClause)).toBe(true);
+      if (isToClause(sends[0].channelClause)) {
+        expect(sends[0].channelClause.channels[0].channelName).toBe(
+          "orders-topic",
+        );
+        expect(sends[0].channelClause.channels[0].channelVersion).toBe("1.0.0");
+      }
+    }
+  });
+
+  it("parses multiple channels with mixed versions", async () => {
+    const doc = await parseProgram(`
+      service PaymentService {
+        version 1.0.0
+        receives event PaymentProcessed from payment-events@1.0.0, payment-retry@2.1.0, payment-dlq
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const receives = utils.getReceives(svc.body);
+      expect(receives).toHaveLength(1);
+      expect(isFromClause(receives[0].channelClause)).toBe(true);
+      if (isFromClause(receives[0].channelClause)) {
+        expect(receives[0].channelClause.channels).toHaveLength(3);
+        expect(receives[0].channelClause.channels[0].channelName).toBe(
+          "payment-events",
+        );
+        expect(receives[0].channelClause.channels[0].channelVersion).toBe(
+          "1.0.0",
+        );
+        expect(receives[0].channelClause.channels[1].channelName).toBe(
+          "payment-retry",
+        );
+        expect(receives[0].channelClause.channels[1].channelVersion).toBe(
+          "2.1.0",
+        );
+        expect(receives[0].channelClause.channels[2].channelName).toBe(
+          "payment-dlq",
+        );
+        expect(
+          receives[0].channelClause.channels[2].channelVersion,
+        ).toBeUndefined();
+      }
+    }
+  });
+
+  it("parses message with @ version and multiple channels with @ versions", async () => {
+    const doc = await parseProgram(`
+      service OrderService {
+        version 1.0.0
+        sends event OrderCreated@2.0.0 to orders-topic@1.0.0, backup-topic@2.0.0
+      }
+    `);
+    const errors = doc.parseResult.parserErrors;
+    expect(errors).toHaveLength(0);
+
+    const svc = doc.parseResult.value.definitions[0];
+    if (isServiceDef(svc)) {
+      const sends = utils.getSends(svc.body);
+      expect(sends).toHaveLength(1);
+      expect(sends[0].messageName).toBe("OrderCreated");
+      expect(sends[0].version).toBe("2.0.0");
+      expect(isToClause(sends[0].channelClause)).toBe(true);
+      if (isToClause(sends[0].channelClause)) {
+        expect(sends[0].channelClause.channels).toHaveLength(2);
+        expect(sends[0].channelClause.channels[0].channelName).toBe(
+          "orders-topic",
+        );
+        expect(sends[0].channelClause.channels[0].channelVersion).toBe("1.0.0");
+        expect(sends[0].channelClause.channels[1].channelName).toBe(
+          "backup-topic",
+        );
+        expect(sends[0].channelClause.channels[1].channelVersion).toBe("2.0.0");
+      }
+    }
+  });
+});
+
+describe("Actor definition", () => {
+  it("should parse a bare actor (no body)", async () => {
+    const doc = await parseProgram(`
+      actor Customer
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+    const program = doc.parseResult.value;
+    expect(program.definitions).toHaveLength(1);
+    const def = program.definitions[0];
+    expect(isActorDef(def)).toBe(true);
+    if (isActorDef(def)) {
+      expect(def.name).toBe("Customer");
+    }
+  });
+
+  it("should parse an actor with body", async () => {
+    const doc = await parseProgram(`
+      actor Customer {
+        name "End User"
+        summary "A customer placing orders"
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+    const program = doc.parseResult.value;
+    const def = program.definitions[0];
+    expect(isActorDef(def)).toBe(true);
+    if (isActorDef(def)) {
+      expect(def.name).toBe("Customer");
+      const body = def.body as any[];
+      expect(utils.getName(body)).toBe("End User");
+      expect(utils.getSummary(body)).toBe("A customer placing orders");
+    }
+  });
+
+  it("should resolve actor type in flows", async () => {
+    const doc = await parseProgram(`
+      actor Customer {
+        name "Customer"
+      }
+
+      flow OrderFlow {
+        version 1.0.0
+        Customer "places an order" -> PlaceOrder
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+    const program = doc.parseResult.value;
+    expect(program.definitions).toHaveLength(2);
+    expect(isActorDef(program.definitions[0])).toBe(true);
+    expect(isFlowDef(program.definitions[1])).toBe(true);
+  });
+});
+
+describe("External system definition", () => {
+  it("should parse a bare external-system (no body)", async () => {
+    const doc = await parseProgram(`
+      external-system WarehouseWMS
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+    const program = doc.parseResult.value;
+    expect(program.definitions).toHaveLength(1);
+    const def = program.definitions[0];
+    expect(isExternalSystemDef(def)).toBe(true);
+    if (isExternalSystemDef(def)) {
+      expect(def.name).toBe("WarehouseWMS");
+    }
+  });
+
+  it("should parse an external-system with body", async () => {
+    const doc = await parseProgram(`
+      external-system WarehouseWMS {
+        name "Warehouse WMS"
+        summary "Legacy warehouse management system"
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+    const program = doc.parseResult.value;
+    const def = program.definitions[0];
+    expect(isExternalSystemDef(def)).toBe(true);
+    if (isExternalSystemDef(def)) {
+      expect(def.name).toBe("WarehouseWMS");
+      const body = def.body as any[];
+      expect(utils.getName(body)).toBe("Warehouse WMS");
+      expect(utils.getSummary(body)).toBe("Legacy warehouse management system");
+    }
+  });
+
+  it("should resolve external-system type in flows", async () => {
+    const doc = await parseProgram(`
+      external-system WarehouseWMS {
+        name "Warehouse WMS"
+      }
+
+      flow ShippingFlow {
+        version 1.0.0
+        when OrderShipped
+          WarehouseWMS "syncs inventory"
+      }
+    `);
+    expect(doc.parseResult.parserErrors).toHaveLength(0);
+    const program = doc.parseResult.value;
+    expect(program.definitions).toHaveLength(2);
+    expect(isExternalSystemDef(program.definitions[0])).toBe(true);
+    expect(isFlowDef(program.definitions[1])).toBe(true);
+  });
+});
diff --git a/packages/language-server/test/resolvers/asyncapi.test.ts b/packages/language-server/test/resolvers/asyncapi.test.ts
new file mode 100644
index 000000000..6ef986c3e
--- /dev/null
+++ b/packages/language-server/test/resolvers/asyncapi.test.ts
@@ -0,0 +1,1378 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  parseSpec,
+  extractMessages,
+  extractChannels,
+  extractService,
+  messageToEc,
+  channelToEc,
+  serviceToEc,
+  escapeEc,
+  resolveAsyncApiImports as resolveImports,
+  resolveAsyncApiImportsAsync as resolveImportsAsync,
+} from "../../src/resolvers/index.js";
+
+// ─── Fixtures ───────────────────────────────────────────
+
+const v3Spec = `
+asyncapi: 3.0.0
+info:
+  title: Orders API
+  version: 1.0.0
+servers:
+  production:
+    host: kafka.example.com:9092
+    protocol: kafka
+channels:
+  orderCreated:
+    address: orders.created
+    summary: Topic for new orders
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+    bindings:
+      kafka:
+        topic: orders.created
+  orderShipped:
+    address: orders.shipped
+    summary: Topic for shipped orders
+    messages:
+      OrderShipped:
+        $ref: '#/components/messages/OrderShipped'
+components:
+  messages:
+    OrderCreated:
+      summary: Fired when a new order is placed
+    OrderShipped:
+      summary: Fired when an order ships
+`;
+
+const v2Spec = `
+asyncapi: 2.6.0
+info:
+  title: Payments API
+  version: 2.0.0
+servers:
+  production:
+    url: amqp://rabbitmq.example.com
+    protocol: amqp
+channels:
+  payments/processed:
+    description: Channel for processed payments
+    bindings:
+      amqp:
+        is: routingKey
+    publish:
+      message:
+        name: PaymentProcessed
+        summary: Payment completed successfully
+  payments/failed:
+    description: Channel for failed payments
+    subscribe:
+      message:
+        name: PaymentFailed
+        summary: Payment was declined
+`;
+
+const v3SpecNoServers = `
+asyncapi: 3.0.0
+info:
+  title: Minimal API
+  version: 0.1.0
+channels:
+  notifications:
+    address: notifications
+    summary: Notification channel
+    messages:
+      NotificationSent:
+        summary: A notification was sent
+components:
+  messages:
+    NotificationSent:
+      summary: A notification was sent
+`;
+
+const v3SpecWithOps = `
+asyncapi: 3.0.0
+info:
+  title: Order Service
+  version: 2.0.0
+  description: This service handles order events.
+servers:
+  production:
+    host: kafka.example.com:9092
+    protocol: kafka
+channels:
+  orderCreated:
+    address: orders.created
+    summary: Topic for new orders
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+  orderShipped:
+    address: orders.shipped
+    summary: Topic for shipped orders
+    messages:
+      OrderShipped:
+        $ref: '#/components/messages/OrderShipped'
+  orderCancelled:
+    address: orders.cancelled
+    summary: Topic for cancelled orders
+    messages:
+      OrderCancelled:
+        $ref: '#/components/messages/OrderCancelled'
+operations:
+  sendOrderCreated:
+    action: send
+    channel:
+      $ref: '#/channels/orderCreated'
+    summary: Publishes when a new order is placed
+  sendOrderShipped:
+    action: send
+    channel:
+      $ref: '#/channels/orderShipped'
+  receiveOrderCancelled:
+    action: receive
+    channel:
+      $ref: '#/channels/orderCancelled'
+    summary: Handles order cancellation
+components:
+  messages:
+    OrderCreated:
+      summary: Fired when a new order is placed
+    OrderShipped:
+      summary: Fired when an order ships
+    OrderCancelled:
+      summary: Fired when an order is cancelled
+`;
+
+const v2SpecWithOps = `
+asyncapi: 2.6.0
+info:
+  title: Payment Service
+  version: 1.0.0
+  description: Handles payment processing events.
+servers:
+  production:
+    url: amqp://rabbitmq.example.com
+    protocol: amqp
+channels:
+  payments/processed:
+    description: Channel for processed payments
+    bindings:
+      amqp:
+        is: routingKey
+    publish:
+      message:
+        name: PaymentProcessed
+        summary: Payment completed successfully
+  payments/failed:
+    description: Channel for failed payments
+    subscribe:
+      message:
+        name: PaymentFailed
+        summary: Payment was declined
+`;
+
+const v3SpecWithOpMessages = `
+asyncapi: 3.0.0
+info:
+  title: Filtered Ops Service
+  version: 1.0.0
+channels:
+  orders:
+    address: orders
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+      OrderUpdated:
+        $ref: '#/components/messages/OrderUpdated'
+      OrderCancelled:
+        $ref: '#/components/messages/OrderCancelled'
+operations:
+  sendOrderCreated:
+    action: send
+    channel:
+      $ref: '#/channels/orders'
+    messages:
+      - $ref: '#/channels/orders/messages/OrderCreated'
+  receiveOrderCancelled:
+    action: receive
+    channel:
+      $ref: '#/channels/orders'
+    messages:
+      - $ref: '#/channels/orders/messages/OrderCancelled'
+components:
+  messages:
+    OrderCreated:
+      summary: New order placed
+    OrderUpdated:
+      summary: Order was updated
+    OrderCancelled:
+      summary: Order was cancelled
+`;
+
+const v2SpecWithRefs = `
+asyncapi: 2.6.0
+info:
+  title: Ref Service
+  version: 1.0.0
+channels:
+  orders/created:
+    publish:
+      message:
+        $ref: '#/components/messages/OrderCreated'
+  orders/cancelled:
+    subscribe:
+      message:
+        $ref: '#/components/messages/OrderCancelled'
+components:
+  messages:
+    OrderCreated:
+      name: OrderCreated
+      summary: Order was created
+    OrderCancelled:
+      name: OrderCancelled
+      summary: Order was cancelled
+`;
+
+const v2SpecWithRefsNoName = `
+asyncapi: 2.6.0
+info:
+  title: Ref No Name Service
+  version: 1.0.0
+channels:
+  orders/created:
+    publish:
+      message:
+        $ref: '#/components/messages/OrderCreated'
+components:
+  messages:
+    OrderCreated:
+      summary: Order was created
+`;
+
+const v2SpecWithOneOf = `
+asyncapi: 2.6.0
+info:
+  title: OneOf Service
+  version: 1.0.0
+channels:
+  orders/events:
+    publish:
+      message:
+        oneOf:
+          - $ref: '#/components/messages/OrderCreated'
+          - $ref: '#/components/messages/OrderShipped'
+  orders/commands:
+    subscribe:
+      message:
+        oneOf:
+          - name: CancelOrder
+            summary: Cancel an order
+          - name: RefundOrder
+            summary: Refund an order
+components:
+  messages:
+    OrderCreated:
+      name: OrderCreated
+      summary: New order placed
+    OrderShipped:
+      name: OrderShipped
+      summary: Order shipped
+`;
+
+// ─── parseSpec ──────────────────────────────────────────
+
+describe("parseSpec", () => {
+  describe("AsyncAPI v3", () => {
+    it("extracts messages from components.messages", () => {
+      const { messages, errors } = parseSpec(v3Spec);
+      expect(errors).toHaveLength(0);
+      expect(messages.size).toBe(2);
+      expect(messages.get("OrderCreated")).toEqual({
+        name: "OrderCreated",
+        summary: "Fired when a new order is placed",
+        description: undefined,
+        version: "1.0.0",
+      });
+      expect(messages.get("OrderShipped")).toEqual({
+        name: "OrderShipped",
+        summary: "Fired when an order ships",
+        description: undefined,
+        version: "1.0.0",
+      });
+    });
+
+    it("extracts channels with address, protocol, and summary", () => {
+      const { channels, errors } = parseSpec(v3Spec);
+      expect(errors).toHaveLength(0);
+      expect(channels.size).toBe(2);
+      expect(channels.get("orderCreated")).toEqual({
+        name: "orderCreated",
+        address: "orders.created",
+        protocol: "kafka",
+        summary: "Topic for new orders",
+        version: "1.0.0",
+      });
+    });
+
+    it("resolves $ref messages from channels", () => {
+      const specWithOnlyChannelRefs = `
+asyncapi: 3.0.0
+info:
+  title: Test
+  version: 1.0.0
+channels:
+  events:
+    address: events
+    messages:
+      MyEvent:
+        $ref: '#/components/messages/MyEvent'
+components:
+  messages:
+    MyEvent:
+      summary: A test event
+`;
+      const { messages } = parseSpec(specWithOnlyChannelRefs);
+      expect(messages.get("MyEvent")?.summary).toBe("A test event");
+    });
+
+    it("falls back to server protocol when channel has no bindings", () => {
+      const { channels } = parseSpec(v3SpecNoServers);
+      expect(channels.get("notifications")?.protocol).toBeUndefined();
+    });
+
+    it("uses server protocol as fallback", () => {
+      const specWithServer = `
+asyncapi: 3.0.0
+info:
+  title: Test
+  version: 1.0.0
+servers:
+  prod:
+    host: nats.example.com
+    protocol: nats
+channels:
+  myChannel:
+    address: my.subject
+    summary: A NATS channel
+`;
+      const { channels } = parseSpec(specWithServer);
+      expect(channels.get("myChannel")?.protocol).toBe("nats");
+    });
+  });
+
+  describe("AsyncAPI v2", () => {
+    it("extracts messages from publish/subscribe operations", () => {
+      const { messages, errors } = parseSpec(v2Spec);
+      expect(errors).toHaveLength(0);
+      expect(messages.size).toBe(2);
+      expect(messages.get("PaymentProcessed")).toEqual({
+        name: "PaymentProcessed",
+        summary: "Payment completed successfully",
+        description: undefined,
+        version: "2.0.0",
+      });
+      expect(messages.get("PaymentFailed")).toEqual({
+        name: "PaymentFailed",
+        summary: "Payment was declined",
+        description: undefined,
+        version: "2.0.0",
+      });
+    });
+
+    it("extracts channels with address derived from channel key", () => {
+      const { channels } = parseSpec(v2Spec);
+      expect(channels.size).toBe(2);
+      const processed = channels.get("payments-processed");
+      expect(processed).toEqual({
+        name: "payments-processed",
+        address: "payments/processed",
+        protocol: "amqp",
+        summary: "Channel for processed payments",
+        version: "2.0.0",
+      });
+    });
+
+    it("uses server protocol when channel has no bindings", () => {
+      const v2NoBind = `
+asyncapi: 2.6.0
+info:
+  title: Test
+  version: 1.0.0
+servers:
+  prod:
+    url: mqtt://broker.example.com
+    protocol: mqtt
+channels:
+  devices/telemetry:
+    description: Device telemetry
+    publish:
+      message:
+        name: Telemetry
+        summary: Device telemetry data
+`;
+      const { channels } = parseSpec(v2NoBind);
+      expect(channels.get("devices-telemetry")?.protocol).toBe("mqtt");
+    });
+
+    it("extracts messages from components.messages", () => {
+      const v2Components = `
+asyncapi: 2.6.0
+info:
+  title: Test
+  version: 1.0.0
+components:
+  messages:
+    UserCreated:
+      summary: New user registered
+    UserDeleted:
+      summary: User account deleted
+`;
+      const { messages } = parseSpec(v2Components);
+      expect(messages.size).toBe(2);
+      expect(messages.get("UserCreated")?.summary).toBe("New user registered");
+    });
+  });
+
+  describe("error handling", () => {
+    it("returns error for invalid YAML", () => {
+      const { messages, channels, errors } = parseSpec("{{invalid yaml");
+      expect(errors).toHaveLength(1);
+      expect(errors[0].message).toContain("Failed to parse AsyncAPI YAML");
+      expect(messages.size).toBe(0);
+      expect(channels.size).toBe(0);
+    });
+
+    it("returns error for empty content", () => {
+      const { errors } = parseSpec("");
+      expect(errors).toHaveLength(1);
+      expect(errors[0].message).toBe("AsyncAPI file is empty or invalid");
+    });
+
+    it("returns error for non-object content", () => {
+      const { errors } = parseSpec('"just a string"');
+      expect(errors).toHaveLength(1);
+      expect(errors[0].message).toBe("AsyncAPI file is empty or invalid");
+    });
+
+    it("returns empty maps for unrecognized asyncapi version", () => {
+      const { messages, channels, errors } = parseSpec(`
+asyncapi: 99.0.0
+info:
+  title: Future
+  version: 1.0.0
+`);
+      expect(errors).toHaveLength(0);
+      expect(messages.size).toBe(0);
+      expect(channels.size).toBe(0);
+    });
+  });
+
+  describe("version inheritance", () => {
+    it("applies info.version to messages without their own version", () => {
+      const { messages } = parseSpec(v3Spec);
+      expect(messages.get("OrderCreated")?.version).toBe("1.0.0");
+    });
+
+    it("applies info.version to channels without their own version", () => {
+      const { channels } = parseSpec(v3Spec);
+      expect(channels.get("orderCreated")?.version).toBe("1.0.0");
+    });
+
+    it("returns no version when info.version is missing", () => {
+      const noVersion = `
+asyncapi: 3.0.0
+info:
+  title: No Version
+components:
+  messages:
+    Evt:
+      summary: An event
+`;
+      const { messages } = parseSpec(noVersion);
+      expect(messages.get("Evt")?.version).toBeUndefined();
+    });
+  });
+});
+
+// ─── extractMessages / extractChannels ──────────────────
+
+describe("extractMessages", () => {
+  it("returns only messages and errors", () => {
+    const result = extractMessages(v3Spec);
+    expect(result.messages.size).toBe(2);
+    expect(result.errors).toHaveLength(0);
+    expect(result).not.toHaveProperty("channels");
+  });
+});
+
+describe("extractChannels", () => {
+  it("returns only channels and errors", () => {
+    const result = extractChannels(v3Spec);
+    expect(result.channels.size).toBe(2);
+    expect(result.errors).toHaveLength(0);
+    expect(result).not.toHaveProperty("messages");
+  });
+});
+
+// ─── messageToEc ────────────────────────────────────────
+
+describe("messageToEc", () => {
+  it("generates event definition", () => {
+    const ec = messageToEc(
+      { name: "OrderCreated", summary: "Order was created", version: "1.0.0" },
+      "events",
+    );
+    expect(ec).toBe(
+      `event OrderCreated {\n  version 1.0.0\n  summary "Order was created"\n}`,
+    );
+  });
+
+  it("generates command definition", () => {
+    const ec = messageToEc(
+      { name: "PlaceOrder", summary: "Place an order", version: "2.0.0" },
+      "commands",
+    );
+    expect(ec).toBe(
+      `command PlaceOrder {\n  version 2.0.0\n  summary "Place an order"\n}`,
+    );
+  });
+
+  it("generates query definition", () => {
+    const ec = messageToEc({ name: "GetOrder", version: "1.0.0" }, "queries");
+    expect(ec).toBe(`query GetOrder {\n  version 1.0.0\n}`);
+  });
+
+  it("omits version when not provided", () => {
+    const ec = messageToEc({ name: "Evt", summary: "Test" }, "events");
+    expect(ec).toBe(`event Evt {\n  summary "Test"\n}`);
+  });
+
+  it("escapes quotes in summary", () => {
+    const ec = messageToEc(
+      { name: "Evt", summary: 'Said "hello"', version: "1.0.0" },
+      "events",
+    );
+    expect(ec).toContain('summary "Said \\"hello\\""');
+  });
+
+  it("strips newlines from summary to produce valid .ec", () => {
+    const ec = messageToEc(
+      { name: "Evt", summary: "Line one\nLine two\n", version: "1.0.0" },
+      "events",
+    );
+    // Summary should be on a single line with no embedded newlines inside the quotes
+    const summaryLine = ec.split("\n").find((l) => l.includes("summary"));
+    expect(summaryLine).toBeDefined();
+    expect(summaryLine).toMatch(/^\s*summary "[^"]*"$/);
+    expect(summaryLine).toContain("Line one Line two");
+  });
+
+  it("handles summary with trailing newline from catalog frontmatter", () => {
+    const ec = messageToEc(
+      {
+        name: "DeliveryFailed",
+        summary: "Event that is emitted when a shipment delivery fails.\n",
+        version: "0.0.1",
+      },
+      "events",
+    );
+    expect(ec).toContain(
+      'summary "Event that is emitted when a shipment delivery fails."',
+    );
+    expect(ec).not.toMatch(/summary "[^"]*\n/);
+  });
+});
+
+// ─── escapeEc ───────────────────────────────────────────
+
+describe("escapeEc", () => {
+  it("escapes double quotes", () => {
+    expect(escapeEc('say "hi"')).toBe('say \\"hi\\"');
+  });
+
+  it("replaces newlines with spaces", () => {
+    expect(escapeEc("line one\nline two")).toBe("line one line two");
+  });
+
+  it("strips carriage returns", () => {
+    expect(escapeEc("line one\r\nline two")).toBe("line one line two");
+  });
+
+  it("trims leading and trailing whitespace", () => {
+    expect(escapeEc("  hello  \n")).toBe("hello");
+  });
+
+  it("escapes backslashes", () => {
+    expect(escapeEc("back\\slash")).toBe("back\\\\slash");
+  });
+
+  it("handles combined special characters", () => {
+    expect(escapeEc('He said "hi"\nand left\n')).toBe(
+      'He said \\"hi\\" and left',
+    );
+  });
+});
+
+// ─── channelToEc ────────────────────────────────────────
+
+describe("channelToEc", () => {
+  it("generates full channel definition", () => {
+    const ec = channelToEc({
+      name: "orderEvents",
+      version: "1.0.0",
+      address: "orders.events",
+      protocol: "kafka",
+      summary: "Kafka topic for orders",
+    });
+    expect(ec).toBe(
+      `channel orderEvents {\n  version 1.0.0\n  address "orders.events"\n  protocol "kafka"\n  summary "Kafka topic for orders"\n}`,
+    );
+  });
+
+  it("omits optional fields when not provided", () => {
+    const ec = channelToEc({ name: "minimal", version: "1.0.0" });
+    expect(ec).toBe(`channel minimal {\n  version 1.0.0\n}`);
+  });
+
+  it("escapes quotes in address", () => {
+    const ec = channelToEc({ name: "ch", address: 'topic/"special"' });
+    expect(ec).toContain('address "topic/\\"special\\""');
+  });
+});
+
+// ─── resolveImports ─────────────────────────────────────
+
+describe("resolveImports", () => {
+  it("replaces event imports with synthesized .ec definitions", () => {
+    const files = {
+      "main.ec": `import events { OrderCreated } from "./spec.yml"\n\nservice Test {}`,
+      "spec.yml": v3Spec,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved).not.toHaveProperty("spec.yml");
+    expect(resolved["main.ec"]).toContain("event OrderCreated {");
+    expect(resolved["main.ec"]).toContain("version 1.0.0");
+    expect(resolved["main.ec"]).toContain("service Test {}");
+    expect(resolved["main.ec"]).not.toContain("import events");
+  });
+
+  it("replaces channel imports with synthesized .ec definitions", () => {
+    const files = {
+      "main.ec": `import channels { orderCreated } from "./spec.yml"\n\nservice Test {}`,
+      "spec.yml": v3Spec,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("channel orderCreated {");
+    expect(resolved["main.ec"]).toContain('address "orders.created"');
+    expect(resolved["main.ec"]).toContain('protocol "kafka"');
+  });
+
+  it("handles multiple import statements from the same file", () => {
+    const files = {
+      "main.ec": `import events { OrderCreated, OrderShipped } from "./spec.yml"\nimport channels { orderCreated, orderShipped } from "./spec.yml"\n`,
+      "spec.yml": v3Spec,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("event OrderCreated {");
+    expect(resolved["main.ec"]).toContain("event OrderShipped {");
+    expect(resolved["main.ec"]).toContain("channel orderCreated {");
+    expect(resolved["main.ec"]).toContain("channel orderShipped {");
+  });
+
+  it("reports error for missing spec file", () => {
+    const files = {
+      "main.ec": `import events { Foo } from "./missing.yml"\n`,
+    };
+    const { errors } = resolveImports(files);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("Spec file not found");
+  });
+
+  it("reports error for message not found in spec", () => {
+    const files = {
+      "main.ec": `import events { NonExistent } from "./spec.yml"\n`,
+      "spec.yml": v3Spec,
+    };
+    const { errors } = resolveImports(files);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain('Message "NonExistent" not found');
+    expect(errors[0].message).toContain(
+      "Available: OrderCreated, OrderShipped",
+    );
+  });
+
+  it("reports error for channel not found in spec", () => {
+    const files = {
+      "main.ec": `import channels { nonExistent } from "./spec.yml"\n`,
+      "spec.yml": v3Spec,
+    };
+    const { errors } = resolveImports(files);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain('Channel "nonExistent" not found');
+    expect(errors[0].message).toContain(
+      "Available: orderCreated, orderShipped",
+    );
+  });
+
+  it("strips YAML files from output", () => {
+    const files = {
+      "main.ec": `import events { OrderCreated } from "./spec.yml"\n`,
+      "spec.yml": v3Spec,
+      "other.yml": "asyncapi: 3.0.0",
+    };
+    const { files: resolved } = resolveImports(files);
+    expect(Object.keys(resolved)).toEqual(["main.ec"]);
+  });
+
+  it("passes through .ec files without async imports unchanged", () => {
+    const files = {
+      "main.ec": `import { Foo } from "./other.ec"\nservice Test {}`,
+      "other.ec": "event Foo {}",
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toBe(files["main.ec"]);
+    expect(resolved["other.ec"]).toBe(files["other.ec"]);
+  });
+
+  it("resolves path with and without ./ prefix", () => {
+    const files = {
+      "main.ec": `import events { OrderCreated } from "spec.yml"\n`,
+      "spec.yml": v3Spec,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("event OrderCreated {");
+  });
+
+  it("handles command imports", () => {
+    const spec = `
+asyncapi: 3.0.0
+info:
+  title: Test
+  version: 1.0.0
+components:
+  messages:
+    DoSomething:
+      summary: A command message
+`;
+    const files = {
+      "main.ec": `import commands { DoSomething } from "./spec.yml"\n`,
+      "spec.yml": spec,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("command DoSomething {");
+  });
+
+  it("skips URL imports in sync mode", () => {
+    const files = {
+      "main.ec": `import events { OrderCreated } from "https://example.com/spec.yml"\n`,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    // URL import is left untouched
+    expect(resolved["main.ec"]).toContain("import events");
+    expect(resolved["main.ec"]).toContain("https://example.com/spec.yml");
+  });
+
+  it("resolves spec imports from a nested .ec file", () => {
+    const files = {
+      "sub/main.ec": `import events { OrderCreated } from "./spec.yml"\n`,
+      "sub/spec.yml": v3Spec,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["sub/main.ec"]).toContain("event OrderCreated {");
+  });
+
+  it("resolves spec imports to a parent directory", () => {
+    const files = {
+      "sub/main.ec": `import events { OrderCreated } from "../spec.yml"\n`,
+      "spec.yml": v3Spec,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["sub/main.ec"]).toContain("event OrderCreated {");
+  });
+
+  it("resolves spec imports from a nested folder path", () => {
+    const files = {
+      "main.ec": `import events { OrderCreated } from "./asyncapi-files/spec.yml"\n`,
+      "asyncapi-files/spec.yml": v3Spec,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("event OrderCreated {");
+  });
+
+  it("resolves service imports from nested folders", () => {
+    const files = {
+      "sub/main.ec": `import OrderService from "./specs/api.yml"\n`,
+      "sub/specs/api.yml": v3SpecWithOps,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["sub/main.ec"]).toContain("service OrderService {");
+  });
+
+  it("resolves deeply nested .ec importing from sibling folder", () => {
+    const files = {
+      "src/dsl/main.ec": `import events { OrderCreated } from "../specs/api.yml"\n`,
+      "src/specs/api.yml": v3Spec,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["src/dsl/main.ec"]).toContain("event OrderCreated {");
+  });
+
+  it("resolves multi-level nested spec imports from root .ec file", () => {
+    const files = {
+      "main.ec": `import events { OrderCreated } from "./services/pricing/api.yml"\nimport commands { OrderCreated } from "./services/booking/api.yml"\n`,
+      "services/pricing/api.yml": v3Spec,
+      "services/booking/api.yml": v3Spec,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("event OrderCreated {");
+  });
+
+  it("resolves service imports from multi-level nested paths", () => {
+    const files = {
+      "main.ec": `import PricingAPI from "./services/pricing/api.yml"\n`,
+      "services/pricing/api.yml": v3SpecWithOps,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("service PricingAPI {");
+  });
+});
+
+// ─── resolveImportsAsync ────────────────────────────────
+
+describe("resolveImportsAsync", () => {
+  const remoteSpec = `
+asyncapi: 3.0.0
+info:
+  title: Remote Orders API
+  version: 2.0.0
+servers:
+  prod:
+    host: kafka.example.com:9092
+    protocol: kafka
+channels:
+  remoteChannel:
+    address: remote.events
+    summary: A remote Kafka topic
+    messages:
+      RemoteEvent:
+        $ref: '#/components/messages/RemoteEvent'
+    bindings:
+      kafka:
+        topic: remote.events
+components:
+  messages:
+    RemoteEvent:
+      summary: An event from a remote spec
+`;
+
+  it("fetches and resolves events from a remote URL", async () => {
+    const mockFetch = vi.fn().mockResolvedValue(remoteSpec);
+    const files = {
+      "main.ec": `import events { RemoteEvent } from "https://example.com/spec.yml"\n\nservice Test {}`,
+    };
+    const { files: resolved, errors } = await resolveImportsAsync(
+      files,
+      mockFetch,
+    );
+    expect(errors).toHaveLength(0);
+    expect(mockFetch).toHaveBeenCalledWith("https://example.com/spec.yml");
+    expect(resolved["main.ec"]).toContain("event RemoteEvent {");
+    expect(resolved["main.ec"]).toContain("version 2.0.0");
+    expect(resolved["main.ec"]).toContain("service Test {}");
+    expect(resolved["main.ec"]).not.toContain("import events");
+  });
+
+  it("fetches and resolves channels from a remote URL", async () => {
+    const mockFetch = vi.fn().mockResolvedValue(remoteSpec);
+    const files = {
+      "main.ec": `import channels { remoteChannel } from "https://example.com/spec.yml"\n`,
+    };
+    const { files: resolved, errors } = await resolveImportsAsync(
+      files,
+      mockFetch,
+    );
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("channel remoteChannel {");
+    expect(resolved["main.ec"]).toContain('address "remote.events"');
+    expect(resolved["main.ec"]).toContain('protocol "kafka"');
+    expect(resolved["main.ec"]).toContain('summary "A remote Kafka topic"');
+  });
+
+  it("handles mixed local and remote imports", async () => {
+    const mockFetch = vi.fn().mockResolvedValue(remoteSpec);
+    const files = {
+      "main.ec": `import events { OrderCreated } from "./local.yml"\nimport events { RemoteEvent } from "https://example.com/spec.yml"\n`,
+      "local.yml": v3Spec,
+    };
+    const { files: resolved, errors } = await resolveImportsAsync(
+      files,
+      mockFetch,
+    );
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("event OrderCreated {");
+    expect(resolved["main.ec"]).toContain("event RemoteEvent {");
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("caches repeated fetches to the same URL", async () => {
+    const mockFetch = vi.fn().mockResolvedValue(remoteSpec);
+    const files = {
+      "main.ec": `import events { RemoteEvent } from "https://example.com/spec.yml"\nimport channels { remoteChannel } from "https://example.com/spec.yml"\n`,
+    };
+    const { files: resolved, errors } = await resolveImportsAsync(
+      files,
+      mockFetch,
+    );
+    expect(errors).toHaveLength(0);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(resolved["main.ec"]).toContain("event RemoteEvent {");
+    expect(resolved["main.ec"]).toContain("channel remoteChannel {");
+  });
+
+  it("reports error when fetch fails", async () => {
+    const mockFetch = vi.fn().mockRejectedValue(new Error("Network error"));
+    const files = {
+      "main.ec": `import events { Foo } from "https://example.com/broken.yml"\n`,
+    };
+    const { files: resolved, errors } = await resolveImportsAsync(
+      files,
+      mockFetch,
+    );
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("Failed to fetch spec");
+    expect(errors[0].message).toContain("Network error");
+    expect(resolved["main.ec"]).toContain("// ERROR");
+  });
+
+  it("reports error when message not found in remote spec", async () => {
+    const mockFetch = vi.fn().mockResolvedValue(remoteSpec);
+    const files = {
+      "main.ec": `import events { NonExistent } from "https://example.com/spec.yml"\n`,
+    };
+    const { errors } = await resolveImportsAsync(files, mockFetch);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain('Message "NonExistent" not found');
+    expect(errors[0].message).toContain("Available: RemoteEvent");
+  });
+
+  it("still resolves local files without a fetchFn call", async () => {
+    const mockFetch = vi.fn();
+    const files = {
+      "main.ec": `import events { OrderCreated } from "./spec.yml"\n`,
+      "spec.yml": v3Spec,
+    };
+    const { files: resolved, errors } = await resolveImportsAsync(
+      files,
+      mockFetch,
+    );
+    expect(errors).toHaveLength(0);
+    expect(mockFetch).not.toHaveBeenCalled();
+    expect(resolved["main.ec"]).toContain("event OrderCreated {");
+  });
+
+  it("resolves local spec imports from nested .ec files", async () => {
+    const mockFetch = vi.fn();
+    const files = {
+      "sub/main.ec": `import events { OrderCreated } from "./spec.yml"\n`,
+      "sub/spec.yml": v3Spec,
+    };
+    const { files: resolved, errors } = await resolveImportsAsync(
+      files,
+      mockFetch,
+    );
+    expect(errors).toHaveLength(0);
+    expect(mockFetch).not.toHaveBeenCalled();
+    expect(resolved["sub/main.ec"]).toContain("event OrderCreated {");
+  });
+
+  it("resolves local spec imports from nested folder paths", async () => {
+    const mockFetch = vi.fn();
+    const files = {
+      "main.ec": `import events { OrderCreated } from "./asyncapi-files/spec.yml"\n`,
+      "asyncapi-files/spec.yml": v3Spec,
+    };
+    const { files: resolved, errors } = await resolveImportsAsync(
+      files,
+      mockFetch,
+    );
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("event OrderCreated {");
+  });
+
+  it("resolves local service imports from nested folders", async () => {
+    const mockFetch = vi.fn();
+    const files = {
+      "sub/main.ec": `import OrderService from "./specs/api.yml"\n`,
+      "sub/specs/api.yml": v3SpecWithOps,
+    };
+    const { files: resolved, errors } = await resolveImportsAsync(
+      files,
+      mockFetch,
+    );
+    expect(errors).toHaveLength(0);
+    expect(mockFetch).not.toHaveBeenCalled();
+    expect(resolved["sub/main.ec"]).toContain("service OrderService {");
+  });
+
+  it("fetches multiple different URLs in parallel", async () => {
+    const spec2 = `
+asyncapi: 3.0.0
+info:
+  title: Other
+  version: 3.0.0
+components:
+  messages:
+    OtherEvent:
+      summary: From another spec
+`;
+    const mockFetch = vi.fn().mockImplementation((url: string) => {
+      if (url.includes("spec1")) return Promise.resolve(remoteSpec);
+      if (url.includes("spec2")) return Promise.resolve(spec2);
+      return Promise.reject(new Error("Unknown URL"));
+    });
+    const files = {
+      "main.ec": `import events { RemoteEvent } from "https://example.com/spec1.yml"\nimport events { OtherEvent } from "https://example.com/spec2.yml"\n`,
+    };
+    const { files: resolved, errors } = await resolveImportsAsync(
+      files,
+      mockFetch,
+    );
+    expect(errors).toHaveLength(0);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    expect(resolved["main.ec"]).toContain("event RemoteEvent {");
+    expect(resolved["main.ec"]).toContain("event OtherEvent {");
+  });
+});
+
+// ─── extractService ────────────────────────────────────
+
+describe("extractService", () => {
+  describe("AsyncAPI v3 with operations", () => {
+    it("extracts service with sends and receives", () => {
+      const { service, errors } = extractService(v3SpecWithOps);
+      expect(errors).toHaveLength(0);
+      expect(service.name).toBe("OrderService");
+      expect(service.version).toBe("2.0.0");
+      expect(service.summary).toBe("This service handles order events.");
+
+      const sends = service.operations.filter((o) => o.action === "send");
+      const receives = service.operations.filter((o) => o.action === "receive");
+
+      expect(sends).toHaveLength(2);
+      expect(receives).toHaveLength(1);
+
+      expect(sends[0].messageName).toBe("OrderCreated");
+      expect(sends[0].channelName).toBe("orderCreated");
+      expect(sends[1].messageName).toBe("OrderShipped");
+      expect(sends[1].channelName).toBe("orderShipped");
+
+      expect(receives[0].messageName).toBe("OrderCancelled");
+      expect(receives[0].channelName).toBe("orderCancelled");
+    });
+
+    it("includes channels referenced by operations", () => {
+      const { service } = extractService(v3SpecWithOps);
+      expect(service.channels).toHaveLength(3);
+      expect(service.channels.map((c) => c.name).sort()).toEqual([
+        "orderCancelled",
+        "orderCreated",
+        "orderShipped",
+      ]);
+      expect(service.channels[0].protocol).toBe("kafka");
+    });
+
+    it("includes messages referenced by operations", () => {
+      const { service } = extractService(v3SpecWithOps);
+      expect(service.messages).toHaveLength(3);
+      expect(service.messages.map((m) => m.name).sort()).toEqual([
+        "OrderCancelled",
+        "OrderCreated",
+        "OrderShipped",
+      ]);
+    });
+
+    it("uses provided service name over spec title", () => {
+      const { service } = extractService(v3SpecWithOps, "MyCustomService");
+      expect(service.name).toBe("MyCustomService");
+    });
+
+    it("respects op.messages filter and only includes scoped messages", () => {
+      const { service, errors } = extractService(v3SpecWithOpMessages);
+      expect(errors).toHaveLength(0);
+
+      const sends = service.operations.filter((o) => o.action === "send");
+      const receives = service.operations.filter((o) => o.action === "receive");
+
+      // Only OrderCreated should be sent (not OrderUpdated or OrderCancelled)
+      expect(sends).toHaveLength(1);
+      expect(sends[0].messageName).toBe("OrderCreated");
+
+      // Only OrderCancelled should be received (not OrderCreated or OrderUpdated)
+      expect(receives).toHaveLength(1);
+      expect(receives[0].messageName).toBe("OrderCancelled");
+
+      // Messages should only include the two referenced by operations
+      expect(service.messages.map((m) => m.name).sort()).toEqual([
+        "OrderCancelled",
+        "OrderCreated",
+      ]);
+    });
+  });
+
+  describe("AsyncAPI v2 with publish/subscribe", () => {
+    it("maps publish to send and subscribe to receive", () => {
+      const { service, errors } = extractService(v2SpecWithOps);
+      expect(errors).toHaveLength(0);
+      expect(service.name).toBe("PaymentService");
+      expect(service.version).toBe("1.0.0");
+
+      const sends = service.operations.filter((o) => o.action === "send");
+      const receives = service.operations.filter((o) => o.action === "receive");
+
+      expect(sends).toHaveLength(1);
+      expect(sends[0].messageName).toBe("PaymentProcessed");
+      expect(sends[0].channelName).toBe("payments-processed");
+
+      expect(receives).toHaveLength(1);
+      expect(receives[0].messageName).toBe("PaymentFailed");
+      expect(receives[0].channelName).toBe("payments-failed");
+    });
+
+    it("includes channels with v2 address format", () => {
+      const { service } = extractService(v2SpecWithOps);
+      const ch = service.channels.find((c) => c.name === "payments-processed");
+      expect(ch).toBeDefined();
+      expect(ch!.address).toBe("payments/processed");
+      expect(ch!.protocol).toBe("amqp");
+    });
+
+    it("resolves v2 message $ref to derive operation names", () => {
+      const { service, errors } = extractService(v2SpecWithRefs);
+      expect(errors).toHaveLength(0);
+
+      const sends = service.operations.filter((o) => o.action === "send");
+      const receives = service.operations.filter((o) => o.action === "receive");
+
+      expect(sends).toHaveLength(1);
+      expect(sends[0].messageName).toBe("OrderCreated");
+
+      expect(receives).toHaveLength(1);
+      expect(receives[0].messageName).toBe("OrderCancelled");
+    });
+
+    it("extracts name from $ref path when message has no name field", () => {
+      const { service, errors } = extractService(v2SpecWithRefsNoName);
+      expect(errors).toHaveLength(0);
+
+      const sends = service.operations.filter((o) => o.action === "send");
+      expect(sends).toHaveLength(1);
+      expect(sends[0].messageName).toBe("OrderCreated");
+    });
+
+    it("handles v2 message.oneOf to extract multiple operations", () => {
+      const { service, errors } = extractService(v2SpecWithOneOf);
+      expect(errors).toHaveLength(0);
+
+      const sends = service.operations.filter((o) => o.action === "send");
+      const receives = service.operations.filter((o) => o.action === "receive");
+
+      expect(sends).toHaveLength(2);
+      expect(sends.map((s) => s.messageName).sort()).toEqual([
+        "OrderCreated",
+        "OrderShipped",
+      ]);
+
+      expect(receives).toHaveLength(2);
+      expect(receives.map((r) => r.messageName).sort()).toEqual([
+        "CancelOrder",
+        "RefundOrder",
+      ]);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles spec with no operations", () => {
+      const { service, errors } = extractService(v3Spec);
+      expect(errors).toHaveLength(0);
+      expect(service.operations).toHaveLength(0);
+      expect(service.channels).toHaveLength(0);
+      expect(service.messages).toHaveLength(0);
+    });
+
+    it("handles invalid YAML", () => {
+      const { service, errors } = extractService("{{invalid yaml");
+      expect(errors).toHaveLength(1);
+      expect(errors[0].message).toContain("Failed to parse");
+      expect(service.name).toBe("UnknownService");
+    });
+
+    it("sanitizes service name from spec title", () => {
+      const spec = `
+asyncapi: 3.0.0
+info:
+  title: My Orders API
+  version: 1.0.0
+`;
+      const { service } = extractService(spec);
+      expect(service.name).toBe("MyOrdersAPI");
+    });
+  });
+});
+
+// ─── serviceToEc ───────────────────────────────────────
+
+describe("serviceToEc", () => {
+  it("generates channels and service with sends/receives", () => {
+    const { service } = extractService(v3SpecWithOps);
+    const ec = serviceToEc(service);
+
+    // Channel definitions
+    expect(ec).toContain("channel orderCreated {");
+    expect(ec).toContain('address "orders.created"');
+    expect(ec).toContain('protocol "kafka"');
+    expect(ec).toContain("channel orderShipped {");
+    expect(ec).toContain("channel orderCancelled {");
+
+    // Service block
+    expect(ec).toContain("service OrderService {");
+    expect(ec).toContain("version 2.0.0");
+    expect(ec).toContain("sends event OrderCreated@2.0.0 to orderCreated");
+    expect(ec).toContain("sends event OrderShipped@2.0.0 to orderShipped");
+    expect(ec).toContain(
+      "receives event OrderCancelled@2.0.0 from orderCancelled",
+    );
+  });
+
+  it("generates v2 service with correct send/receive mapping", () => {
+    const { service } = extractService(v2SpecWithOps);
+    const ec = serviceToEc(service);
+
+    expect(ec).toContain("service PaymentService {");
+    expect(ec).toContain(
+      "sends event PaymentProcessed@1.0.0 to payments-processed",
+    );
+    expect(ec).toContain(
+      "receives event PaymentFailed@1.0.0 from payments-failed",
+    );
+  });
+
+  it("includes service summary", () => {
+    const { service } = extractService(v3SpecWithOps);
+    const ec = serviceToEc(service);
+    expect(ec).toContain('summary "This service handles order events."');
+  });
+});
+
+// ─── resolveImports with service imports ────────────────
+
+describe("resolveImports (service imports)", () => {
+  it("resolves import ServiceName from spec.yml", () => {
+    const files = {
+      "main.ec": `import OrderService from "./orders-asyncapi.yml"\n\nvisualizer main {\n  service OrderService\n}\n`,
+      "orders-asyncapi.yml": v3SpecWithOps,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("service OrderService {");
+    expect(resolved["main.ec"]).toContain("channel orderCreated {");
+    expect(resolved["main.ec"]).toContain(
+      "sends event OrderCreated@2.0.0 to orderCreated",
+    );
+    expect(resolved["main.ec"]).toContain(
+      "receives event OrderCancelled@2.0.0 from orderCancelled",
+    );
+    expect(resolved["main.ec"]).toContain("visualizer main {");
+  });
+
+  it("uses the import name as the service name", () => {
+    const files = {
+      "main.ec": `import MyService from "./spec.yml"\n`,
+      "spec.yml": v3SpecWithOps,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("service MyService {");
+  });
+
+  it("works alongside resource imports", () => {
+    const files = {
+      "main.ec": `import OrderService from "./orders.yml"\nimport events { PaymentProcessed } from "./payments.yml"\n`,
+      "orders.yml": v3SpecWithOps,
+      "payments.yml": v2SpecWithOps,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("service OrderService {");
+    expect(resolved["main.ec"]).toContain("event PaymentProcessed {");
+  });
+
+  it("handles v2 spec service import", () => {
+    const files = {
+      "main.ec": `import PaymentService from "./payments.yml"\n`,
+      "payments.yml": v2SpecWithOps,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("service PaymentService {");
+    expect(resolved["main.ec"]).toContain("sends event PaymentProcessed");
+    expect(resolved["main.ec"]).toContain("receives event PaymentFailed");
+  });
+
+  it("skips URL service imports in sync mode", () => {
+    const files = {
+      "main.ec": `import OrderService from "https://example.com/spec.yml"\n`,
+    };
+    const { files: resolved, errors } = resolveImports(files);
+    expect(errors).toHaveLength(0);
+    expect(resolved["main.ec"]).toContain("import OrderService");
+  });
+});
+
+// ─── resolveImportsAsync with service imports ───────────
+
+describe("resolveImportsAsync (service imports)", () => {
+  it("resolves remote service import", async () => {
+    const mockFetch = vi.fn().mockResolvedValue(v3SpecWithOps);
+    const files = {
+      "main.ec": `import OrderService from "https://example.com/spec.yml"\n`,
+    };
+    const { files: resolved, errors } = await resolveImportsAsync(
+      files,
+      mockFetch,
+    );
+    expect(errors).toHaveLength(0);
+    expect(mockFetch).toHaveBeenCalledWith("https://example.com/spec.yml");
+    expect(resolved["main.ec"]).toContain("service OrderService {");
+    expect(resolved["main.ec"]).toContain("channel orderCreated {");
+    expect(resolved["main.ec"]).toContain(
+      "sends event OrderCreated@2.0.0 to orderCreated",
+    );
+  });
+
+  it("handles fetch error for service import", async () => {
+    const mockFetch = vi.fn().mockRejectedValue(new Error("Network error"));
+    const files = {
+      "main.ec": `import OrderService from "https://example.com/broken.yml"\n`,
+    };
+    const { errors } = await resolveImportsAsync(files, mockFetch);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("Failed to fetch");
+  });
+});
diff --git a/packages/language-server/test/resolvers/catalog.test.ts b/packages/language-server/test/resolvers/catalog.test.ts
new file mode 100644
index 000000000..e8977f3b0
--- /dev/null
+++ b/packages/language-server/test/resolvers/catalog.test.ts
@@ -0,0 +1,582 @@
+import { describe, it, expect } from "vitest";
+import { resolve } from "node:path";
+import {
+  parseCatalogResources,
+  parseCatalogChannels,
+  parseCatalogServices,
+  isCatalogPath,
+} from "../../src/resolvers/catalog.js";
+import { resolveSpecImportsAsync } from "../../src/resolvers/resolve.js";
+
+const FIXTURES = resolve(__dirname, "../fixtures");
+const TEST_CATALOG = resolve(FIXTURES, "test-catalog");
+
+// ─── isCatalogPath ──────────────────────────────────────
+
+describe("isCatalogPath", () => {
+  it("returns true for directory-like paths", () => {
+    expect(isCatalogPath("./my-catalog")).toBe(true);
+    expect(isCatalogPath("../other-catalog")).toBe(true);
+    expect(isCatalogPath("catalogs/production")).toBe(true);
+  });
+
+  it("returns false for spec file paths", () => {
+    expect(isCatalogPath("./spec.yml")).toBe(false);
+    expect(isCatalogPath("./spec.yaml")).toBe(false);
+    expect(isCatalogPath("./spec.json")).toBe(false);
+  });
+
+  it("returns false for URLs", () => {
+    expect(isCatalogPath("https://example.com/catalog")).toBe(false);
+    expect(isCatalogPath("http://example.com/catalog")).toBe(false);
+  });
+});
+
+// ─── parseCatalogResources ──────────────────────────────
+
+describe("parseCatalogResources", () => {
+  it("reads events from a catalog directory", async () => {
+    const { messages, errors } = await parseCatalogResources(
+      TEST_CATALOG,
+      "events",
+    );
+    expect(errors).toEqual([]);
+    expect(messages.size).toBeGreaterThanOrEqual(3);
+    expect(messages.has("OrderCreated")).toBe(true);
+    expect(messages.has("OrderShipped")).toBe(true);
+    expect(messages.has("OrderCancelled")).toBe(true);
+  });
+
+  it("returns correct SpecMessage fields", async () => {
+    const { messages } = await parseCatalogResources(TEST_CATALOG, "events");
+    const orderCreated = messages.get("OrderCreated");
+    expect(orderCreated).toEqual({
+      name: "OrderCreated",
+      displayName: "Order Created",
+      version: "1.0.0",
+      summary: "Fired when a new order is placed by a customer",
+    });
+  });
+
+  it("returns error for non-existent directory", async () => {
+    const { messages, errors } = await parseCatalogResources(
+      "/non/existent/path",
+      "events",
+    );
+    expect(messages.size).toBe(0);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("Catalog directory not found");
+  });
+
+  it("returns error for unsupported resource type", async () => {
+    const { messages, errors } = await parseCatalogResources(
+      TEST_CATALOG,
+      "channels",
+    );
+    expect(messages.size).toBe(0);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("do not support resource type");
+  });
+});
+
+// ─── End-to-end: resolveSpecImportsAsync with catalog ───
+
+describe("resolveSpecImportsAsync with catalog imports", () => {
+  const noopFetch = async () => "";
+
+  it("resolves catalog event imports to .ec code", async () => {
+    const files = {
+      "main.ec": `import events { OrderCreated, OrderShipped } from "${TEST_CATALOG}"
+
+visualizer main {
+  service OrderService {
+    sends event OrderCreated
+    sends event OrderShipped
+  }
+}`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    const mainContent = result.files["main.ec"];
+
+    expect(mainContent).toContain("event OrderCreated {");
+    expect(mainContent).toContain('name "Order Created"');
+    expect(mainContent).toContain("version 1.0.0");
+    expect(mainContent).toContain(
+      'summary "Fired when a new order is placed by a customer"',
+    );
+    expect(mainContent).toContain("event OrderShipped {");
+    expect(mainContent).toContain('name "Order Shipped"');
+    expect(mainContent).toContain("version 2.0.0");
+    expect(mainContent).not.toContain("import events");
+  });
+
+  it("produces error for missing event in catalog", async () => {
+    const files = {
+      "main.ec": `import events { NonExistentEvent } from "${TEST_CATALOG}"`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(
+      result.errors.some((e) => e.message.includes("NonExistentEvent")),
+    ).toBe(true);
+    expect(result.files["main.ec"]).toContain("// ERROR:");
+  });
+
+  it("does not resolve catalog imports when basePath is not provided", async () => {
+    const files = {
+      "main.ec": `import events { OrderCreated } from "./test-catalog"`,
+    };
+
+    // Without basePath, catalog imports should be left untouched
+    const result = await resolveSpecImportsAsync(files, noopFetch);
+    expect(result.files["main.ec"]).toContain("import events");
+  });
+
+  it("handles mixed spec and catalog imports", async () => {
+    const specContent = `
+asyncapi: 3.0.0
+info:
+  title: Test API
+  version: 1.0.0
+channels:
+  testChannel:
+    address: test.channel
+    messages:
+      TestEvent:
+        payload:
+          type: object
+components:
+  messages:
+    TestEvent:
+      name: TestEvent
+      summary: A test event from spec
+`;
+
+    const files = {
+      "spec.yml": specContent,
+      "main.ec": `import events { TestEvent } from "./spec.yml"
+import events { OrderCreated } from "${TEST_CATALOG}"
+
+visualizer main {
+  service MyService {
+    sends event TestEvent
+    sends event OrderCreated
+  }
+}`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    const mainContent = result.files["main.ec"];
+
+    // Both spec import and catalog import should be resolved
+    expect(mainContent).toContain("event TestEvent {");
+    expect(mainContent).toContain("event OrderCreated {");
+    expect(mainContent).not.toContain("import events");
+  });
+
+  it("resolves relative catalog path against the importing file's directory", async () => {
+    const files = {
+      "main.ec": `import events { OrderCreated } from "./test-catalog"`,
+    };
+
+    // basePath is the fixtures directory, so "./test-catalog" relative to
+    // the file at "main.ec" (in basePath) should resolve to FIXTURES/test-catalog
+    const result = await resolveSpecImportsAsync(files, noopFetch, FIXTURES);
+    expect(result.files["main.ec"]).toContain("event OrderCreated {");
+    expect(result.files["main.ec"]).not.toContain("import events");
+  });
+
+  it("resolves relative catalog path for files in subdirectories", async () => {
+    const files = {
+      "sub/main.ec": `import events { OrderCreated } from "../test-catalog"`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, FIXTURES);
+    expect(result.files["sub/main.ec"]).toContain("event OrderCreated {");
+    expect(result.files["sub/main.ec"]).not.toContain("import events");
+  });
+
+  it("preserves file order when catalog imports are resolved", async () => {
+    // The active file (main.ec) should remain first even when it has a catalog
+    // import that requires async resolution. Files without catalog imports
+    // must not jump ahead in the output.
+    const files = {
+      "main.ec": `import events { OrderCreated } from "${TEST_CATALOG}"
+
+visualizer main {
+  event OrderCreated
+}`,
+      "other.ec": `service SomeService {
+  version 1.0.0
+}`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    const keys = Object.keys(result.files);
+    expect(keys[0]).toBe("main.ec");
+    expect(keys[1]).toBe("other.ec");
+  });
+
+  it("preserves file order with multiple files and catalog imports", async () => {
+    const files = {
+      "first.ec": `import events { OrderCreated } from "${TEST_CATALOG}"`,
+      "second.ec": `service MyService { version 1.0.0 }`,
+      "third.ec": `import events { OrderShipped } from "${TEST_CATALOG}"`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    const keys = Object.keys(result.files);
+    expect(keys).toEqual(["first.ec", "second.ec", "third.ec"]);
+    // Verify catalog imports were actually resolved
+    expect(result.files["first.ec"]).toContain("event OrderCreated {");
+    expect(result.files["third.ec"]).toContain("event OrderShipped {");
+  });
+
+  it("gracefully handles catalog resolution errors without crashing", async () => {
+    const files = {
+      "main.ec": `import events { OrderCreated } from "./nonexistent-catalog"`,
+    };
+
+    // Should not throw — errors should be captured
+    const result = await resolveSpecImportsAsync(files, noopFetch, FIXTURES);
+    expect(result.files["main.ec"]).toBeDefined();
+    // Should have either an error comment or an error in the errors array
+    const hasError =
+      result.errors.length > 0 || result.files["main.ec"].includes("// ERROR:");
+    expect(hasError).toBe(true);
+  });
+});
+
+// ─── parseCatalogServices ───────────────────────────────
+
+describe("parseCatalogServices", () => {
+  it("reads services from a catalog directory", async () => {
+    const { services, errors } = await parseCatalogServices(TEST_CATALOG);
+    expect(errors).toEqual([]);
+    expect(services.has("OrderService")).toBe(true);
+  });
+
+  it("returns correct SpecService fields", async () => {
+    const { services } = await parseCatalogServices(TEST_CATALOG);
+    const svc = services.get("OrderService")!;
+    expect(svc.name).toBe("OrderService");
+    expect(svc.version).toBe("1.0.0");
+    expect(svc.summary).toBe("Manages order lifecycle");
+  });
+
+  it("includes sends and receives operations", async () => {
+    const { services } = await parseCatalogServices(TEST_CATALOG);
+    const svc = services.get("OrderService")!;
+    const sends = svc.operations.filter((op) => op.action === "send");
+    const receives = svc.operations.filter((op) => op.action === "receive");
+    expect(sends.length).toBe(2);
+    expect(receives.length).toBe(1);
+    expect(sends.map((s) => s.messageName)).toContain("OrderCreated");
+    expect(sends.map((s) => s.messageName)).toContain("OrderShipped");
+    expect(receives[0].messageName).toBe("OrderCancelled");
+  });
+
+  it("includes message summaries from the catalog", async () => {
+    const { services } = await parseCatalogServices(TEST_CATALOG);
+    const svc = services.get("OrderService")!;
+    const orderCreated = svc.messages.find((m) => m.name === "OrderCreated");
+    expect(orderCreated).toBeDefined();
+    expect(orderCreated!.summary).toBe(
+      "Fired when a new order is placed by a customer",
+    );
+  });
+
+  it("returns error for non-existent directory", async () => {
+    const { services, errors } =
+      await parseCatalogServices("/non/existent/path");
+    expect(services.size).toBe(0);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("Catalog directory not found");
+  });
+});
+
+// ─── End-to-end: service catalog imports ────────────────
+
+describe("resolveSpecImportsAsync with service catalog imports", () => {
+  const noopFetch = async () => "";
+
+  it("resolves catalog service imports to .ec code", async () => {
+    const files = {
+      "main.ec": `import services { OrderService } from "${TEST_CATALOG}"
+
+visualizer main {
+  service OrderService
+}`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    const mainContent = result.files["main.ec"];
+
+    expect(mainContent).toContain("service OrderService {");
+    expect(mainContent).toContain("version 1.0.0");
+    expect(mainContent).toContain('summary "Manages order lifecycle"');
+    expect(mainContent).toContain("sends event OrderCreated");
+    expect(mainContent).toContain("sends event OrderShipped");
+    expect(mainContent).toContain("receives event OrderCancelled");
+    expect(mainContent).not.toContain("import services");
+  });
+
+  it("generates standalone message definitions with summaries", async () => {
+    const files = {
+      "main.ec": `import services { OrderService } from "${TEST_CATALOG}"
+
+visualizer main {
+  service OrderService
+}`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    const mainContent = result.files["main.ec"];
+
+    // Should contain standalone event definitions with summaries
+    expect(mainContent).toContain("event OrderCreated {");
+    expect(mainContent).toContain(
+      'summary "Fired when a new order is placed by a customer"',
+    );
+    expect(mainContent).toContain("event OrderShipped {");
+    expect(mainContent).toContain("event OrderCancelled {");
+  });
+
+  it("produces error for missing service in catalog", async () => {
+    const files = {
+      "main.ec": `import services { NonExistentService } from "${TEST_CATALOG}"`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(
+      result.errors.some((e) => e.message.includes("NonExistentService")),
+    ).toBe(true);
+  });
+});
+
+// ─── parseCatalogResources for containers ────────────────
+
+describe("parseCatalogResources for containers", () => {
+  it("reads containers from a catalog directory", async () => {
+    const { messages, errors } = await parseCatalogResources(
+      TEST_CATALOG,
+      "containers",
+    );
+    expect(errors).toEqual([]);
+    expect(messages.size).toBeGreaterThanOrEqual(2);
+    expect(messages.has("payments-db")).toBe(true);
+    expect(messages.has("order-cache")).toBe(true);
+  });
+
+  it("returns correct SpecMessage fields for containers", async () => {
+    const { messages } = await parseCatalogResources(
+      TEST_CATALOG,
+      "containers",
+    );
+    const paymentsDb = messages.get("payments-db");
+    expect(paymentsDb).toEqual({
+      name: "payments-db",
+      displayName: "Payments DB",
+      version: "1.0.0",
+      summary: "Primary database for payment transactions",
+    });
+  });
+
+  it("returns error for non-existent directory", async () => {
+    const { messages, errors } = await parseCatalogResources(
+      "/non/existent/path",
+      "containers",
+    );
+    expect(messages.size).toBe(0);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("Catalog directory not found");
+  });
+});
+
+// ─── End-to-end: container catalog imports ───────────────
+
+describe("resolveSpecImportsAsync with container catalog imports", () => {
+  const noopFetch = async () => "";
+
+  it("resolves catalog container imports to .ec code", async () => {
+    const files = {
+      "main.ec": `import containers { payments-db, order-cache } from "${TEST_CATALOG}"
+
+visualizer main {
+  container payments-db
+  container order-cache
+}`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    const mainContent = result.files["main.ec"];
+
+    expect(mainContent).toContain("container payments-db {");
+    expect(mainContent).toContain('name "Payments DB"');
+    expect(mainContent).toContain("version 1.0.0");
+    expect(mainContent).toContain(
+      'summary "Primary database for payment transactions"',
+    );
+    expect(mainContent).toContain("container order-cache {");
+    expect(mainContent).toContain('name "Order Cache"');
+    expect(mainContent).toContain("version 2.0.0");
+    expect(mainContent).not.toContain("import containers");
+  });
+
+  it("produces error for missing container in catalog", async () => {
+    const files = {
+      "main.ec": `import containers { NonExistentContainer } from "${TEST_CATALOG}"`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(
+      result.errors.some((e) => e.message.includes("NonExistentContainer")),
+    ).toBe(true);
+    expect(result.files["main.ec"]).toContain("// ERROR:");
+  });
+
+  it("handles mixed container and event imports", async () => {
+    const files = {
+      "main.ec": `import events { OrderCreated } from "${TEST_CATALOG}"
+import containers { payments-db } from "${TEST_CATALOG}"
+
+visualizer main {
+  service OrderService {
+    sends event OrderCreated
+    writes-to container payments-db
+  }
+}`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    const mainContent = result.files["main.ec"];
+
+    expect(mainContent).toContain("event OrderCreated {");
+    expect(mainContent).toContain("container payments-db {");
+    expect(mainContent).not.toContain("import events");
+    expect(mainContent).not.toContain("import containers");
+  });
+
+  it("resolves relative catalog path for container imports", async () => {
+    const files = {
+      "main.ec": `import containers { payments-db } from "./test-catalog"`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, FIXTURES);
+    expect(result.files["main.ec"]).toContain("container payments-db {");
+    expect(result.files["main.ec"]).not.toContain("import containers");
+  });
+});
+
+// ─── parseCatalogChannels ────────────────────────────────
+
+describe("parseCatalogChannels", () => {
+  it("reads channels from a catalog directory", async () => {
+    const { channels, errors } = await parseCatalogChannels(TEST_CATALOG);
+    expect(errors).toEqual([]);
+    expect(channels.size).toBeGreaterThanOrEqual(2);
+    expect(channels.has("order-events")).toBe(true);
+    expect(channels.has("payment-queue")).toBe(true);
+  });
+
+  it("returns correct SpecChannel fields", async () => {
+    const { channels } = await parseCatalogChannels(TEST_CATALOG);
+    const orderEvents = channels.get("order-events");
+    expect(orderEvents).toEqual({
+      name: "order-events",
+      displayName: "Order Events",
+      version: "1.0.0",
+      summary: "EventBus for order domain events",
+      address: "orders.events",
+      protocol: "kafka",
+    });
+  });
+
+  it("returns error for non-existent directory", async () => {
+    const { channels, errors } =
+      await parseCatalogChannels("/non/existent/path");
+    expect(channels.size).toBe(0);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("Catalog directory not found");
+  });
+});
+
+// ─── End-to-end: channel catalog imports ─────────────────
+
+describe("resolveSpecImportsAsync with channel catalog imports", () => {
+  const noopFetch = async () => "";
+
+  it("resolves catalog channel imports to .ec code", async () => {
+    const files = {
+      "main.ec": `import channels { order-events, payment-queue } from "${TEST_CATALOG}"
+
+visualizer main {
+  service OrderService {
+    sends event OrderCreated to order-events
+  }
+}`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    const mainContent = result.files["main.ec"];
+
+    expect(mainContent).toContain("channel order-events {");
+    expect(mainContent).toContain('name "Order Events"');
+    expect(mainContent).toContain("version 1.0.0");
+    expect(mainContent).toContain('summary "EventBus for order domain events"');
+    expect(mainContent).toContain('address "orders.events"');
+    expect(mainContent).toContain('protocol "kafka"');
+    expect(mainContent).toContain("channel payment-queue {");
+    expect(mainContent).toContain('name "Payment Queue"');
+    expect(mainContent).toContain("version 2.0.0");
+    expect(mainContent).not.toContain("import channels");
+  });
+
+  it("produces error for missing channel in catalog", async () => {
+    const files = {
+      "main.ec": `import channels { NonExistentChannel } from "${TEST_CATALOG}"`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(
+      result.errors.some((e) => e.message.includes("NonExistentChannel")),
+    ).toBe(true);
+    expect(result.files["main.ec"]).toContain("// ERROR:");
+  });
+
+  it("handles mixed channel and event imports", async () => {
+    const files = {
+      "main.ec": `import events { OrderCreated } from "${TEST_CATALOG}"
+import channels { order-events } from "${TEST_CATALOG}"
+
+visualizer main {
+  service OrderService {
+    sends event OrderCreated to order-events
+  }
+}`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, "/");
+    const mainContent = result.files["main.ec"];
+
+    expect(mainContent).toContain("event OrderCreated {");
+    expect(mainContent).toContain("channel order-events {");
+    expect(mainContent).not.toContain("import events");
+    expect(mainContent).not.toContain("import channels");
+  });
+
+  it("resolves relative catalog path for channel imports", async () => {
+    const files = {
+      "main.ec": `import channels { order-events } from "./test-catalog"`,
+    };
+
+    const result = await resolveSpecImportsAsync(files, noopFetch, FIXTURES);
+    expect(result.files["main.ec"]).toContain("channel order-events {");
+    expect(result.files["main.ec"]).not.toContain("import channels");
+  });
+});
diff --git a/packages/language-server/test/resolvers/openapi.test.ts b/packages/language-server/test/resolvers/openapi.test.ts
new file mode 100644
index 000000000..d47f7b578
--- /dev/null
+++ b/packages/language-server/test/resolvers/openapi.test.ts
@@ -0,0 +1,718 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  parseOpenApiSpec,
+  extractOpenApiService,
+  openApiServiceToEc,
+  openApiMessageToEc,
+  resolveAsyncApiImports as resolveImports,
+  resolveAsyncApiImportsAsync as resolveImportsAsync,
+  detectSpecType,
+  parseSpec,
+} from "../../src/resolvers/index.js";
+
+// ─── Fixtures ───────────────────────────────────────────
+
+const openApiV30Spec = `
+openapi: 3.0.3
+info:
+  title: Orders API
+  version: 1.0.0
+  description: API for managing orders
+paths:
+  /orders:
+    get:
+      operationId: GetOrders
+      summary: List all orders
+    post:
+      operationId: CreateOrder
+      summary: Create a new order
+  /orders/{id}:
+    get:
+      operationId: GetOrder
+      summary: Get order by ID
+    put:
+      operationId: UpdateOrder
+      summary: Update an existing order
+    delete:
+      operationId: DeleteOrder
+      summary: Delete an order
+`;
+
+const openApiV31Spec = `
+openapi: 3.1.0
+info:
+  title: Users API
+  version: 2.0.0
+  description: API for managing users
+paths:
+  /users:
+    get:
+      operationId: ListUsers
+      summary: List all users
+    post:
+      operationId: CreateUser
+      summary: Create a new user
+  /users/{userId}:
+    get:
+      operationId: GetUser
+      summary: Get a single user
+    patch:
+      operationId: UpdateUser
+      summary: Update user details
+    delete:
+      operationId: DeleteUser
+      summary: Remove a user
+`;
+
+const openApiNoOperationIds = `
+openapi: 3.0.3
+info:
+  title: Products API
+  version: 1.0.0
+paths:
+  /products:
+    get:
+      summary: List products
+    post:
+      summary: Create product
+  /products/{id}/reviews:
+    get:
+      summary: Get reviews for a product
+`;
+
+const openApiWithOverrides = `
+openapi: 3.0.3
+info:
+  title: Hybrid API
+  version: 1.0.0
+paths:
+  /webhooks:
+    post:
+      operationId: HandleWebhook
+      summary: Handle incoming webhook
+      x-eventcatalog-message-type: query
+  /data:
+    get:
+      operationId: FetchData
+      summary: Fetch data
+      x-eventcatalog-message-type: command
+`;
+
+const asyncApiV3Spec = `
+asyncapi: 3.0.0
+info:
+  title: Orders Async API
+  version: 1.0.0
+servers:
+  production:
+    host: kafka.example.com:9092
+    protocol: kafka
+channels:
+  orderCreated:
+    address: orders.created
+    summary: Topic for new orders
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+operations:
+  onOrderCreated:
+    action: send
+    channel:
+      $ref: '#/channels/orderCreated'
+components:
+  messages:
+    OrderCreated:
+      summary: Fired when a new order is placed
+`;
+
+// ─── detectSpecType ─────────────────────────────────────
+
+describe("detectSpecType", () => {
+  it("detects OpenAPI spec", () => {
+    expect(detectSpecType(openApiV30Spec)).toBe("openapi");
+    expect(detectSpecType(openApiV31Spec)).toBe("openapi");
+  });
+
+  it("detects AsyncAPI spec", () => {
+    expect(detectSpecType(asyncApiV3Spec)).toBe("asyncapi");
+  });
+
+  it("returns unknown for non-spec content", () => {
+    expect(detectSpecType("just some text")).toBe("unknown");
+    expect(detectSpecType("{}")).toBe("unknown");
+  });
+
+  it("detects JSON OpenAPI spec", () => {
+    const jsonSpec = JSON.stringify({
+      openapi: "3.0.3",
+      info: { title: "Test", version: "1.0.0" },
+      paths: {},
+    });
+    expect(detectSpecType(jsonSpec)).toBe("openapi");
+  });
+
+  it("returns unknown for invalid content", () => {
+    expect(detectSpecType("{{invalid")).toBe("unknown");
+  });
+});
+
+// ─── parseOpenApiSpec ───────────────────────────────────
+
+describe("parseOpenApiSpec", () => {
+  it("extracts operations from v3.0 spec", () => {
+    const { messages, errors } = parseOpenApiSpec(openApiV30Spec);
+    expect(errors).toHaveLength(0);
+    expect(messages.size).toBe(5);
+    expect(messages.has("GetOrders")).toBe(true);
+    expect(messages.has("CreateOrder")).toBe(true);
+    expect(messages.has("GetOrder")).toBe(true);
+    expect(messages.has("UpdateOrder")).toBe(true);
+    expect(messages.has("DeleteOrder")).toBe(true);
+  });
+
+  it("extracts operations from v3.1 spec", () => {
+    const { messages, errors } = parseOpenApiSpec(openApiV31Spec);
+    expect(errors).toHaveLength(0);
+    expect(messages.size).toBe(5);
+    expect(messages.has("ListUsers")).toBe(true);
+    expect(messages.has("CreateUser")).toBe(true);
+  });
+
+  it("maps GET to query and others to command", () => {
+    const { messages } = parseOpenApiSpec(openApiV30Spec);
+    expect(messages.get("GetOrders")!.messageType).toBe("query");
+    expect(messages.get("GetOrder")!.messageType).toBe("query");
+    expect(messages.get("CreateOrder")!.messageType).toBe("command");
+    expect(messages.get("UpdateOrder")!.messageType).toBe("command");
+    expect(messages.get("DeleteOrder")!.messageType).toBe("command");
+  });
+
+  it("uses operationId when available", () => {
+    const { messages } = parseOpenApiSpec(openApiV30Spec);
+    expect(messages.has("GetOrders")).toBe(true);
+    expect(messages.has("CreateOrder")).toBe(true);
+  });
+
+  it("derives name from method+path when no operationId", () => {
+    const { messages } = parseOpenApiSpec(openApiNoOperationIds);
+    expect(messages.has("GetProducts")).toBe(true);
+    expect(messages.has("PostProducts")).toBe(true);
+    expect(messages.has("GetProductsIdReviews")).toBe(true);
+  });
+
+  it("applies info.version to all messages", () => {
+    const { messages } = parseOpenApiSpec(openApiV30Spec);
+    for (const msg of messages.values()) {
+      expect(msg.version).toBe("1.0.0");
+    }
+  });
+
+  it("preserves summary and description", () => {
+    const { messages } = parseOpenApiSpec(openApiV30Spec);
+    expect(messages.get("GetOrders")!.summary).toBe("List all orders");
+    expect(messages.get("CreateOrder")!.summary).toBe("Create a new order");
+  });
+
+  it("respects x-eventcatalog-message-type override", () => {
+    const { messages } = parseOpenApiSpec(openApiWithOverrides);
+    expect(messages.get("HandleWebhook")!.messageType).toBe("query");
+    expect(messages.get("FetchData")!.messageType).toBe("command");
+  });
+
+  it("returns error for invalid YAML", () => {
+    const { messages, errors } = parseOpenApiSpec("{{invalid yaml");
+    expect(messages.size).toBe(0);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("Failed to parse OpenAPI spec");
+  });
+
+  it("returns error for empty content", () => {
+    const { messages, errors } = parseOpenApiSpec("");
+    expect(messages.size).toBe(0);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("empty or invalid");
+  });
+
+  it("returns error for unsupported version", () => {
+    const spec = `openapi: 2.0.0\ninfo:\n  title: Test\n  version: 1.0.0\npaths: {}`;
+    const { errors } = parseOpenApiSpec(spec);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("Unsupported OpenAPI version");
+  });
+
+  it("parses JSON OpenAPI spec", () => {
+    const jsonSpec = JSON.stringify({
+      openapi: "3.0.3",
+      info: { title: "JSON API", version: "1.0.0" },
+      paths: {
+        "/items": {
+          get: { operationId: "ListItems", summary: "List items" },
+        },
+      },
+    });
+    const { messages, errors } = parseOpenApiSpec(jsonSpec);
+    expect(errors).toHaveLength(0);
+    expect(messages.has("ListItems")).toBe(true);
+    expect(messages.get("ListItems")!.messageType).toBe("query");
+  });
+
+  it("handles spec with no paths", () => {
+    const spec = `openapi: 3.0.3\ninfo:\n  title: Empty\n  version: 1.0.0`;
+    const { messages, errors } = parseOpenApiSpec(spec);
+    expect(errors).toHaveLength(0);
+    expect(messages.size).toBe(0);
+  });
+
+  it("handles numeric openapi version (YAML parses 3.1 as number)", () => {
+    // YAML `openapi: 3.1` parses as a number, not a string
+    const spec = `openapi: 3.1\ninfo:\n  title: Numeric\n  version: 1.0.0\npaths:\n  /items:\n    get:\n      operationId: ListItems\n      summary: List items`;
+    const { messages, errors } = parseOpenApiSpec(spec);
+    expect(errors).toHaveLength(0);
+    expect(messages.has("ListItems")).toBe(true);
+  });
+
+  it("handles numeric openapi version that is unsupported", () => {
+    const spec = `openapi: 2.0\ninfo:\n  title: Old\n  version: 1.0.0\npaths: {}`;
+    const { errors } = parseOpenApiSpec(spec);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain("Unsupported OpenAPI version");
+  });
+});
+
+// ─── extractOpenApiService ──────────────────────────────
+
+describe("extractOpenApiService", () => {
+  it("extracts service with name from info.title", () => {
+    const { service, errors } = extractOpenApiService(openApiV30Spec);
+    expect(errors).toHaveLength(0);
+    expect(service.name).toBe("OrdersAPI");
+    expect(service.version).toBe("1.0.0");
+    expect(service.summary).toBe("API for managing orders");
+  });
+
+  it("uses provided serviceName override", () => {
+    const { service } = extractOpenApiService(openApiV30Spec, "MyOrderService");
+    expect(service.name).toBe("MyOrderService");
+  });
+
+  it("all operations are receive action", () => {
+    const { service } = extractOpenApiService(openApiV30Spec);
+    for (const op of service.operations) {
+      expect(op.action).toBe("receive");
+    }
+  });
+
+  it("generates no channels", () => {
+    const { service } = extractOpenApiService(openApiV30Spec);
+    expect(service.channels).toHaveLength(0);
+  });
+
+  it("operations have empty channelName", () => {
+    const { service } = extractOpenApiService(openApiV30Spec);
+    for (const op of service.operations) {
+      expect(op.channelName).toBe("");
+    }
+  });
+
+  it("operations have correct messageType", () => {
+    const { service } = extractOpenApiService(openApiV30Spec);
+    const getOps = service.operations.filter(
+      (op) => op.messageType === "query",
+    );
+    const cmdOps = service.operations.filter(
+      (op) => op.messageType === "command",
+    );
+    expect(getOps.length).toBe(2); // GetOrders, GetOrder
+    expect(cmdOps.length).toBe(3); // CreateOrder, UpdateOrder, DeleteOrder
+  });
+
+  it("includes all messages", () => {
+    const { service } = extractOpenApiService(openApiV30Spec);
+    expect(service.messages).toHaveLength(5);
+  });
+
+  it("returns errors for invalid spec", () => {
+    const { service, errors } = extractOpenApiService("{{invalid");
+    expect(errors.length).toBeGreaterThan(0);
+    expect(service.name).toBe("UnknownService");
+  });
+});
+
+// ─── openApiServiceToEc ────────────────────────────────
+
+describe("openApiServiceToEc", () => {
+  it("generates EC DSL without channels", () => {
+    const { service } = extractOpenApiService(openApiV30Spec);
+    const ec = openApiServiceToEc(service);
+
+    expect(ec).toContain("service OrdersAPI {");
+    expect(ec).toContain("version 1.0.0");
+    expect(ec).toContain('summary "API for managing orders"');
+    expect(ec).toContain("receives query GetOrders@1.0.0");
+    expect(ec).toContain("receives command CreateOrder@1.0.0");
+    expect(ec).toContain("receives command UpdateOrder@1.0.0");
+    expect(ec).toContain("receives command DeleteOrder@1.0.0");
+    expect(ec).toContain("receives query GetOrder@1.0.0");
+    // No channel definitions
+    expect(ec).not.toContain("channel ");
+    // No to/from clauses
+    expect(ec).not.toContain(" to ");
+    expect(ec).not.toContain(" from ");
+  });
+
+  it("generates standalone message definitions with summaries", () => {
+    const { service } = extractOpenApiService(openApiV30Spec);
+    const ec = openApiServiceToEc(service);
+
+    // Standalone query definitions with @api annotations
+    expect(ec).toContain(
+      'query GetOrders {\n  version 1.0.0\n  summary "List all orders"\n  @api(method: "GET", path: "/orders")\n}',
+    );
+    expect(ec).toContain(
+      'query GetOrder {\n  version 1.0.0\n  summary "Get order by ID"\n  @api(method: "GET", path: "/orders/{id}")\n}',
+    );
+    // Standalone command definitions with @api annotations
+    expect(ec).toContain(
+      'command CreateOrder {\n  version 1.0.0\n  summary "Create a new order"\n  @api(method: "POST", path: "/orders")\n}',
+    );
+    expect(ec).toContain(
+      'command UpdateOrder {\n  version 1.0.0\n  summary "Update an existing order"\n  @api(method: "PUT", path: "/orders/{id}")\n}',
+    );
+    expect(ec).toContain(
+      'command DeleteOrder {\n  version 1.0.0\n  summary "Delete an order"\n  @api(method: "DELETE", path: "/orders/{id}")\n}',
+    );
+  });
+});
+
+// ─── openApiMessageToEc ────────────────────────────────
+
+describe("openApiMessageToEc", () => {
+  it("generates command definition", () => {
+    const ec = openApiMessageToEc({
+      name: "CreateOrder",
+      summary: "Create a new order",
+      version: "1.0.0",
+      messageType: "command",
+    });
+    expect(ec).toContain("command CreateOrder {");
+    expect(ec).toContain("version 1.0.0");
+    expect(ec).toContain('summary "Create a new order"');
+  });
+
+  it("generates query definition", () => {
+    const ec = openApiMessageToEc({
+      name: "GetOrders",
+      summary: "List all orders",
+      version: "1.0.0",
+      messageType: "query",
+    });
+    expect(ec).toContain("query GetOrders {");
+    expect(ec).toContain("version 1.0.0");
+    expect(ec).toContain('summary "List all orders"');
+  });
+});
+
+// ─── resolveImports (unified, sync) with OpenAPI ───────
+
+describe("resolveImports with OpenAPI", () => {
+  it("resolves command import from OpenAPI spec", () => {
+    const { files, errors } = resolveImports({
+      "main.ec": `import commands { CreateOrder } from "./api.yml"\n`,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain("command CreateOrder {");
+    expect(files["main.ec"]).toContain("version 1.0.0");
+    expect(files["main.ec"]).toContain('summary "Create a new order"');
+  });
+
+  it("resolves query import from OpenAPI spec", () => {
+    const { files, errors } = resolveImports({
+      "main.ec": `import queries { GetOrders } from "./api.yml"\n`,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain("query GetOrders {");
+  });
+
+  it("resolves multiple imports from OpenAPI spec", () => {
+    const { files, errors } = resolveImports({
+      "main.ec": `import commands { CreateOrder, UpdateOrder } from "./api.yml"\n`,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain("command CreateOrder {");
+    expect(files["main.ec"]).toContain("command UpdateOrder {");
+  });
+
+  it("ignores commented import lines", () => {
+    const { files, errors } = resolveImports({
+      "main.ec": [
+        `// import commands { CreateOrder } from "./api.yml"`,
+        `// import queries { GetOrder } from "./api.yml"`,
+        `visualizer main {`,
+        `  name "Test"`,
+        `}`,
+        "",
+      ].join("\n"),
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain(
+      `// import commands { CreateOrder } from "./api.yml"`,
+    );
+    expect(files["main.ec"]).toContain(
+      `// import queries { GetOrder } from "./api.yml"`,
+    );
+    expect(files["main.ec"]).not.toContain("command CreateOrder {");
+  });
+
+  it("returns error for event import from OpenAPI spec", () => {
+    const { errors } = resolveImports({
+      "main.ec": `import events { CreateOrder } from "./api.yml"\n`,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0].message).toContain("commands and queries, not events");
+  });
+
+  it("returns error for channel import from OpenAPI spec", () => {
+    const { errors } = resolveImports({
+      "main.ec": `import channels { orders } from "./api.yml"\n`,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0].message).toContain("do not contain channels");
+  });
+
+  it("returns error for missing message in OpenAPI spec", () => {
+    const { errors } = resolveImports({
+      "main.ec": `import commands { NonExistent } from "./api.yml"\n`,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0].message).toContain('"NonExistent" not found');
+    expect(errors[0].message).toContain("Available:");
+  });
+
+  it("returns error when importing a query as a command", () => {
+    const { errors } = resolveImports({
+      "main.ec": `import commands { GetOrders } from "./api.yml"\n`,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0].message).toContain('"GetOrders" is a query');
+    expect(errors[0].message).toContain("import queries { GetOrders }");
+  });
+
+  it("returns error when importing a command as a query", () => {
+    const { errors } = resolveImports({
+      "main.ec": `import queries { CreateOrder } from "./api.yml"\n`,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0].message).toContain('"CreateOrder" is a command');
+    expect(errors[0].message).toContain("import commands { CreateOrder }");
+  });
+
+  it("resolves service import from OpenAPI spec", () => {
+    const { files, errors } = resolveImports({
+      "main.ec": `import OrdersAPI from "./api.yml"\n`,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain("service OrdersAPI {");
+    expect(files["main.ec"]).toContain("receives command CreateOrder@1.0.0");
+    expect(files["main.ec"]).toContain("receives query GetOrders@1.0.0");
+    expect(files["main.ec"]).not.toContain("channel ");
+  });
+
+  it("resolves service import with custom name", () => {
+    const { files, errors } = resolveImports({
+      "main.ec": `import MyService from "./api.yml"\n`,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain("service MyService {");
+  });
+
+  it("resolves command import from multi-level nested OpenAPI spec", () => {
+    const { files, errors } = resolveImports({
+      "main.ec": `import commands { CreateOrder } from "./services/pricing/api.yml"\n`,
+      "services/pricing/api.yml": openApiV30Spec,
+    });
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain("command CreateOrder {");
+  });
+
+  it("resolves service import from multi-level nested OpenAPI spec", () => {
+    const { files, errors } = resolveImports({
+      "main.ec": `import PricingAPI from "./services/pricing/api.yml"\n`,
+      "services/pricing/api.yml": openApiV30Spec,
+    });
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain("service PricingAPI {");
+  });
+
+  it("excludes spec files from output", () => {
+    const { files } = resolveImports({
+      "main.ec": `import commands { CreateOrder } from "./api.yml"\n`,
+      "api.yml": openApiV30Spec,
+    });
+    expect(files["api.yml"]).toBeUndefined();
+  });
+
+  it("resolves JSON OpenAPI spec", () => {
+    const jsonSpec = JSON.stringify({
+      openapi: "3.0.3",
+      info: { title: "JSON API", version: "1.0.0" },
+      paths: {
+        "/items": {
+          get: { operationId: "ListItems", summary: "List items" },
+          post: { operationId: "CreateItem", summary: "Create item" },
+        },
+      },
+    });
+    const { files, errors } = resolveImports({
+      "main.ec": `import queries { ListItems } from "./api.json"\n`,
+      "api.json": jsonSpec,
+    });
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain("query ListItems {");
+  });
+});
+
+// ─── resolveImportsAsync with OpenAPI ───────────────────
+
+describe("resolveImportsAsync with OpenAPI", () => {
+  it("resolves remote OpenAPI spec", async () => {
+    const fetchFn = vi.fn().mockResolvedValue(openApiV30Spec);
+
+    const { files, errors } = await resolveImportsAsync(
+      {
+        "main.ec": `import commands { CreateOrder } from "https://example.com/api.yml"\n`,
+      },
+      fetchFn,
+    );
+    expect(errors).toHaveLength(0);
+    expect(fetchFn).toHaveBeenCalledWith("https://example.com/api.yml");
+    expect(files["main.ec"]).toContain("command CreateOrder {");
+  });
+
+  it("resolves remote OpenAPI service import", async () => {
+    const fetchFn = vi.fn().mockResolvedValue(openApiV30Spec);
+
+    const { files, errors } = await resolveImportsAsync(
+      {
+        "main.ec": `import OrdersAPI from "https://example.com/api.yml"\n`,
+      },
+      fetchFn,
+    );
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain("service OrdersAPI {");
+    expect(files["main.ec"]).toContain("receives command CreateOrder@1.0.0");
+  });
+
+  it("handles fetch errors", async () => {
+    const fetchFn = vi.fn().mockRejectedValue(new Error("Network error"));
+
+    const { errors } = await resolveImportsAsync(
+      {
+        "main.ec": `import commands { CreateOrder } from "https://example.com/api.yml"\n`,
+      },
+      fetchFn,
+    );
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0].message).toContain("Failed to fetch");
+  });
+});
+
+// ─── Mixed AsyncAPI + OpenAPI ───────────────────────────
+
+describe("mixed AsyncAPI + OpenAPI imports", () => {
+  it("resolves imports from both spec types in same file", () => {
+    const { files, errors } = resolveImports({
+      "main.ec": [
+        `import events { OrderCreated } from "./async.yml"`,
+        `import commands { CreateOrder } from "./api.yml"`,
+        "",
+      ].join("\n"),
+      "async.yml": asyncApiV3Spec,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain("event OrderCreated {");
+    expect(files["main.ec"]).toContain("command CreateOrder {");
+  });
+
+  it("resolves service imports from both spec types", () => {
+    const { files, errors } = resolveImports({
+      "main.ec": [
+        `import OrdersAsyncService from "./async.yml"`,
+        `import OrdersRestAPI from "./api.yml"`,
+        "",
+      ].join("\n"),
+      "async.yml": asyncApiV3Spec,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors).toHaveLength(0);
+    // AsyncAPI service has channels
+    expect(files["main.ec"]).toContain("service OrdersAsyncService {");
+    expect(files["main.ec"]).toContain("channel orderCreated {");
+    // OpenAPI service has no channels
+    expect(files["main.ec"]).toContain("service OrdersRestAPI {");
+    expect(files["main.ec"]).toContain("receives command CreateOrder@1.0.0");
+  });
+
+  it("handles mixed resource and service imports", () => {
+    const { files, errors } = resolveImports({
+      "main.ec": [
+        `import events { OrderCreated } from "./async.yml"`,
+        `import OrdersRestAPI from "./api.yml"`,
+        "",
+      ].join("\n"),
+      "async.yml": asyncApiV3Spec,
+      "api.yml": openApiV30Spec,
+    });
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain("event OrderCreated {");
+    expect(files["main.ec"]).toContain("service OrdersRestAPI {");
+  });
+
+  it("async resolves mixed remote specs", async () => {
+    const fetchFn = vi.fn().mockImplementation((url: string) => {
+      if (url.includes("async")) return Promise.resolve(asyncApiV3Spec);
+      if (url.includes("openapi")) return Promise.resolve(openApiV30Spec);
+      return Promise.reject(new Error("Unknown URL"));
+    });
+
+    const { files, errors } = await resolveImportsAsync(
+      {
+        "main.ec": [
+          `import events { OrderCreated } from "https://example.com/async.yml"`,
+          `import commands { CreateOrder } from "https://example.com/openapi.yml"`,
+          "",
+        ].join("\n"),
+      },
+      fetchFn,
+    );
+    expect(errors).toHaveLength(0);
+    expect(files["main.ec"]).toContain("event OrderCreated {");
+    expect(files["main.ec"]).toContain("command CreateOrder {");
+  });
+
+  it("excludes both spec file types from output", () => {
+    const { files } = resolveImports({
+      "main.ec": [
+        `import events { OrderCreated } from "./async.yml"`,
+        `import commands { CreateOrder } from "./api.yml"`,
+        "",
+      ].join("\n"),
+      "async.yml": asyncApiV3Spec,
+      "api.yml": openApiV30Spec,
+    });
+    expect(files["async.yml"]).toBeUndefined();
+    expect(files["api.yml"]).toBeUndefined();
+    expect(files["main.ec"]).toBeDefined();
+  });
+});
diff --git a/packages/language-server/test/validator.test.ts b/packages/language-server/test/validator.test.ts
new file mode 100644
index 000000000..9238a1a08
--- /dev/null
+++ b/packages/language-server/test/validator.test.ts
@@ -0,0 +1,204 @@
+import { describe, it, expect } from "vitest";
+import { createEcServices } from "../src/ec-module.js";
+import { EmptyFileSystem } from "langium";
+import { parseDocument } from "langium/test";
+import type { Program } from "../src/generated/ast.js";
+
+const services = createEcServices(EmptyFileSystem);
+
+async function getValidationErrors(input: string): Promise<string[]> {
+  const doc = await parseDocument<Program>(services.Ec, input, {
+    validation: true,
+  });
+  const allDiags = doc.diagnostics ?? [];
+  return allDiags
+    .filter((d) => d.severity === 1) // 1 = Error in LSP
+    .map((d) => d.message);
+}
+
+// ---------------------------------------------------------------------------
+// Duplicate definitions — name + version uniqueness
+// ---------------------------------------------------------------------------
+describe("Duplicate definition validation", () => {
+  it("allows same name with different versions", async () => {
+    const errors = await getValidationErrors(`
+      event OrderCreated {
+        version 1.0.0
+        summary "v1"
+      }
+      event OrderCreated {
+        version 2.0.0
+        summary "v2"
+      }
+    `);
+    const dupes = errors.filter((e) => e.includes("Duplicate"));
+    expect(dupes).toHaveLength(0);
+  });
+
+  it("rejects same name with same version", async () => {
+    const errors = await getValidationErrors(`
+      event OrderCreated {
+        version 1.0.0
+      }
+      event OrderCreated {
+        version 1.0.0
+      }
+    `);
+    const dupes = errors.filter((e) => e.includes("Duplicate"));
+    expect(dupes).toHaveLength(1);
+    expect(dupes[0]).toContain("OrderCreated");
+    expect(dupes[0]).toContain("1.0.0");
+  });
+
+  it("rejects same name+version across different resource types", async () => {
+    const errors = await getValidationErrors(`
+      event MyResource {
+        version 1.0.0
+      }
+      query MyResource {
+        version 1.0.0
+      }
+    `);
+    const dupes = errors.filter((e) => e.includes("Duplicate"));
+    expect(dupes).toHaveLength(1);
+    expect(dupes[0]).toContain("MyResource");
+  });
+
+  it("rejects duplicate inline message definitions", async () => {
+    const errors = await getValidationErrors(`
+      service A {
+        version 1.0.0
+        sends event Foo {
+          version 1.0.0
+        }
+      }
+      service B {
+        version 2.0.0
+        sends event Foo {
+          version 1.0.0
+        }
+      }
+    `);
+    const dupes = errors.filter((e) => e.includes("Duplicate"));
+    expect(dupes).toHaveLength(1);
+    expect(dupes[0]).toContain("Foo");
+  });
+
+  it("allows different services with different versions", async () => {
+    const errors = await getValidationErrors(`
+      service OrderService {
+        version 1.0.0
+      }
+      service OrderService {
+        version 2.0.0
+      }
+    `);
+    const dupes = errors.filter((e) => e.includes("Duplicate"));
+    expect(dupes).toHaveLength(0);
+  });
+
+  it("rejects duplicate service inside domain with same version as top-level", async () => {
+    const errors = await getValidationErrors(`
+      service MyService {
+        version 1.0.0
+      }
+      domain MyDomain {
+        version 1.0.0
+        service MyService {
+          version 1.0.0
+        }
+      }
+    `);
+    const dupes = errors.filter((e) => e.includes("Duplicate"));
+    expect(dupes).toHaveLength(1);
+    expect(dupes[0]).toContain("MyService");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Visualizer validation
+// ---------------------------------------------------------------------------
+describe("Visualizer validation", () => {
+  it("visualizer without version does not produce error", async () => {
+    const errors = await getValidationErrors(`
+      visualizer main {
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+    const versionErrors = errors.filter((e) => e.includes("version"));
+    expect(versionErrors).toHaveLength(0);
+  });
+
+  it("inline resource inside visualizer without version produces error", async () => {
+    const errors = await getValidationErrors(`
+      visualizer main {
+        service OrderService {
+        }
+      }
+    `);
+    const versionErrors = errors.filter((e) => e.includes("version"));
+    expect(versionErrors).toHaveLength(1);
+    expect(versionErrors[0]).toContain("OrderService");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Actor and ExternalSystem validation — no version required
+// ---------------------------------------------------------------------------
+describe("Actor and ExternalSystem validation", () => {
+  it("actor without version does not produce error", async () => {
+    const errors = await getValidationErrors(`
+      actor User {
+        name "The User"
+        summary "User persona"
+      }
+    `);
+    const versionErrors = errors.filter((e) => e.includes("version"));
+    expect(versionErrors).toHaveLength(0);
+  });
+
+  it("external-system without version does not produce error", async () => {
+    const errors = await getValidationErrors(`
+      external-system Random {
+        name "Display Name"
+        summary "Third-party system that integrates with the platform"
+      }
+    `);
+    const versionErrors = errors.filter((e) => e.includes("version"));
+    expect(versionErrors).toHaveLength(0);
+  });
+
+  it("actor inside visualizer without version does not produce error", async () => {
+    const errors = await getValidationErrors(`
+      visualizer main {
+        actor User {
+          name "The User"
+          summary "User persona"
+        }
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+    const versionErrors = errors.filter((e) => e.includes("version"));
+    expect(versionErrors).toHaveLength(0);
+  });
+
+  it("external-system inside visualizer without version does not produce error", async () => {
+    const errors = await getValidationErrors(`
+      visualizer main {
+        external-system PaymentGateway {
+          name "Payment Gateway"
+          summary "External payment processor"
+        }
+        service OrderService {
+          version 1.0.0
+        }
+      }
+    `);
+    const versionErrors = errors.filter((e) => e.includes("version"));
+    expect(versionErrors).toHaveLength(0);
+  });
+});
diff --git a/packages/language-server/tsconfig.json b/packages/language-server/tsconfig.json
new file mode 100644
index 000000000..b591833f6
--- /dev/null
+++ b/packages/language-server/tsconfig.json
@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/language-server/vitest.config.ts b/packages/language-server/vitest.config.ts
new file mode 100644
index 000000000..140033993
--- /dev/null
+++ b/packages/language-server/vitest.config.ts
@@ -0,0 +1,19 @@
+import { defineConfig } from "vitest/config";
+import path from "node:path";
+
+export default defineConfig({
+  plugins: [
+    {
+      name: "resolve-js-to-ts",
+      resolveId(source, importer) {
+        if (source.endsWith(".js") && importer?.includes("/language-server/")) {
+          const tsSource = source.replace(/\.js$/, ".ts");
+          return path.resolve(path.dirname(importer), tsSource);
+        }
+      },
+    },
+  ],
+  test: {
+    include: ["test/**/*.test.ts"],
+  },
+});
diff --git a/packages/linter/.gitignore b/packages/linter/.gitignore
new file mode 100644
index 000000000..6d3f3669b
--- /dev/null
+++ b/packages/linter/.gitignore
@@ -0,0 +1,8 @@
+node_modules
+dist
+.DS_Store
+*.log
+.vscode
+.idea
+coverage
+*.tgz
diff --git a/packages/linter/.prettierignore b/packages/linter/.prettierignore
new file mode 100644
index 000000000..b07a2c5c2
--- /dev/null
+++ b/packages/linter/.prettierignore
@@ -0,0 +1,4 @@
+dist
+node_modules
+pnpm-lock.yaml
+.changeset/*
\ No newline at end of file
diff --git a/packages/linter/.prettierrc b/packages/linter/.prettierrc
new file mode 100644
index 000000000..2fbe55cde
--- /dev/null
+++ b/packages/linter/.prettierrc
@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "printWidth": 130,
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true
+}
diff --git a/packages/linter/CHANGELOG.md b/packages/linter/CHANGELOG.md
new file mode 100644
index 000000000..7128ce6fd
--- /dev/null
+++ b/packages/linter/CHANGELOG.md
@@ -0,0 +1,264 @@
+# @eventcatalog/linter
+
+## 1.1.4
+
+### Patch Changes
+
+- 0983132: Fix loading dependencies from ESM `eventcatalog.config.js` files.
+
+## 1.1.3
+
+### Patch Changes
+
+- 44f4bcf: Add support for linting `system` resources, including schema validation, scanner path patterns, and reference validation for services, flows, entities, containers, relationships, and owned systems.
+
+## 1.1.2
+
+### Patch Changes
+
+- Updated dependencies [9949f9f]
+- Updated dependencies [d64cfab]
+  - @eventcatalog/sdk@2.25.0
+
+## 1.1.2-beta.1
+
+### Patch Changes
+
+- Updated dependencies [9949f9f]
+  - @eventcatalog/sdk@2.25.0-beta.1
+
+## 1.1.2-beta.0
+
+### Patch Changes
+
+- Updated dependencies [d64cfab]
+  - @eventcatalog/sdk@2.25.0-beta.0
+
+## 1.1.1
+
+### Patch Changes
+
+- Updated dependencies [29dc055]
+  - @eventcatalog/sdk@2.24.2
+
+## 1.1.0
+
+### Minor Changes
+
+- 956d324: Add linter support for agents, ADRs, containers, data products, and diagrams, expand reference validation across resource types, and update the LikeC4 install message to pin compatible versions.
+
+## 1.0.29
+
+### Patch Changes
+
+- Updated dependencies [3334ab1]
+  - @eventcatalog/sdk@2.24.1
+
+## 1.0.28
+
+### Patch Changes
+
+- Updated dependencies [6b7fc3c]
+  - @eventcatalog/sdk@2.24.0
+
+## 1.0.27
+
+### Patch Changes
+
+- Updated dependencies [2801b3e]
+  - @eventcatalog/sdk@2.23.1
+
+## 1.0.26
+
+### Patch Changes
+
+- Updated dependencies [3ad00ad]
+  - @eventcatalog/sdk@2.23.0
+
+## 1.0.25
+
+### Patch Changes
+
+- Updated dependencies [50b38f6]
+  - @eventcatalog/sdk@2.22.0
+
+## 1.0.24
+
+### Patch Changes
+
+- 67940c4: Add optional `url` support to badges so they can render as clickable links.
+- Updated dependencies [67940c4]
+  - @eventcatalog/sdk@2.21.2
+
+## 1.0.23
+
+### Patch Changes
+
+- Updated dependencies [1c9c217]
+  - @eventcatalog/sdk@2.21.1
+
+## 1.0.22
+
+### Patch Changes
+
+- Updated dependencies [3a7b096]
+  - @eventcatalog/sdk@2.21.0
+
+## 1.0.21
+
+### Patch Changes
+
+- Updated dependencies [8f724a7]
+  - @eventcatalog/sdk@2.20.0
+
+## 1.0.20
+
+### Patch Changes
+
+- Updated dependencies [52b4f24]
+  - @eventcatalog/sdk@2.19.0
+
+## 1.0.19
+
+### Patch Changes
+
+- Updated dependencies [ee142e4]
+  - @eventcatalog/sdk@2.18.4
+
+## 1.0.18
+
+### Patch Changes
+
+- Updated dependencies [88795d0]
+  - @eventcatalog/sdk@2.18.3
+
+## 1.0.17
+
+### Patch Changes
+
+- Updated dependencies [4639ec3]
+  - @eventcatalog/sdk@2.18.2
+
+## 1.0.16
+
+### Patch Changes
+
+- Updated dependencies [e2b0460]
+  - @eventcatalog/sdk@2.18.1
+
+## 1.0.15
+
+### Patch Changes
+
+- Updated dependencies [913ca20]
+  - @eventcatalog/sdk@2.18.0
+
+## 1.0.14
+
+### Patch Changes
+
+- Updated dependencies [83aca74]
+  - @eventcatalog/sdk@2.17.4
+
+## 1.0.13
+
+### Patch Changes
+
+- Updated dependencies [46a2292]
+  - @eventcatalog/sdk@2.17.3
+
+## 1.0.12
+
+### Patch Changes
+
+- Updated dependencies [0514bb1]
+  - @eventcatalog/sdk@2.17.2
+
+## 1.0.11
+
+### Patch Changes
+
+- Updated dependencies [6456054]
+  - @eventcatalog/sdk@2.17.1
+
+## 1.0.10
+
+### Patch Changes
+
+- Updated dependencies [af2d4f4]
+  - @eventcatalog/sdk@2.17.0
+
+## 1.0.9
+
+### Patch Changes
+
+- Updated dependencies [283c147]
+  - @eventcatalog/sdk@2.16.0
+
+## 1.0.8
+
+### Patch Changes
+
+- Updated dependencies [b5bbb3d]
+  - @eventcatalog/sdk@2.15.1
+
+## 1.0.8
+
+### Patch Changes
+
+- Updated dependencies [7531be8]
+- Updated dependencies [a1c5012]
+- Updated dependencies [25acfdd]
+  - @eventcatalog/sdk@2.15.0
+
+## 1.0.7
+
+### Patch Changes
+
+- Updated dependencies [f3685b6]
+  - @eventcatalog/sdk@2.14.3
+
+## 1.0.6
+
+### Patch Changes
+
+- Updated dependencies [6a4e582]
+  - @eventcatalog/sdk@2.14.2
+
+## 1.0.5
+
+### Patch Changes
+
+- Updated dependencies [69cb966]
+  - @eventcatalog/sdk@2.14.1
+
+## 1.0.4
+
+### Patch Changes
+
+- Updated dependencies [c782129]
+- Updated dependencies [c782129]
+  - @eventcatalog/sdk@2.14.0
+
+## 1.0.3
+
+### Patch Changes
+
+- b466daf: fix: add build step to release workflow to ensure dist/ is included in published packages
+- Updated dependencies [b466daf]
+  - @eventcatalog/sdk@2.13.2
+
+## 1.0.2
+
+### Patch Changes
+
+- Updated dependencies [0b35904]
+  - @eventcatalog/sdk@2.13.1
+
+## 1.0.1
+
+### Patch Changes
+
+- 6f3e03f: Migrate linter package to monorepo structure
+- Updated dependencies [19696f3]
+  - @eventcatalog/sdk@2.13.0
diff --git a/packages/linter/README.md b/packages/linter/README.md
new file mode 100644
index 000000000..ff9554ed5
--- /dev/null
+++ b/packages/linter/README.md
@@ -0,0 +1,949 @@
+# EventCatalog Linter
+
+A comprehensive linter for EventCatalog that validates frontmatter schemas and resource references to ensure your event-driven architecture documentation is correct and consistent.
+
+[![npm version](https://badge.fury.io/js/@eventcatalog%2Flinter.svg)](https://badge.fury.io/js/@eventcatalog%2Flinter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🚀 Features
+
+- **📋 Schema Validation**: Validates all resource frontmatter against defined schemas using Zod
+- **🔗 Reference Validation**: Ensures all referenced resources (services, events, domains, etc.) actually exist
+- **📦 Semver Version Support**: Supports semantic versions, ranges (`^1.0.0`, `~1.2.0`), x-patterns (`0.0.x`), and `latest`
+- **⚙️ Configurable Rules**: Optional `.eventcatalogrc.js` config file for customizing rule severity and behavior
+- **🚫 Ignore Patterns**: Skip validation for specific file patterns (archived, drafts, etc.)
+- **🎯 Rule Overrides**: Apply different rules to different file patterns for flexible team workflows
+- **🎯 Comprehensive Coverage**: Supports all EventCatalog resource types
+- **⚡ Fast Performance**: Efficiently scans large catalogs
+- **🎨 ESLint-Inspired Output**: Clean, file-grouped error reporting with severity levels
+- **⚠️ Warnings Support**: Distinguish between errors and warnings with `--fail-on-warning` option
+- **🧪 Well Tested**: Comprehensive test suite with 100% coverage
+
+### Supported Resource Types
+
+- 🏢 **Domains** (including subdomains)
+- 🧩 **Systems**
+- ⚙️ **Services**
+- 📨 **Events**
+- 📤 **Commands**
+- ❓ **Queries**
+- 📡 **Channels**
+- 🔄 **Flows**
+- 📊 **Entities**
+- 🤖 **Agents**
+- 🧱 **Containers** (including the legacy data store alias)
+- 📈 **Data Products**
+- 🧭 **Diagrams**
+- 📝 **ADRs**
+- 👤 **Users**
+- 👥 **Teams**
+
+## 📦 Installation
+
+### Use with npx (Recommended)
+
+```bash
+npx @eventcatalog/linter
+```
+
+### Global Installation
+
+```bash
+npm install -g @eventcatalog/linter
+```
+
+### Add to your project
+
+```bash
+npm install --save-dev @eventcatalog/linter
+```
+
+### Quick Start
+
+1. **Install and run**: Start linting immediately with npx
+
+   ```bash
+   npx @eventcatalog/linter
+   ```
+
+2. **Add configuration**: Create a `.eventcatalogrc.js` file to customize rules
+
+   ```javascript
+   module.exports = {
+     rules: {
+       'best-practices/summary-required': 'warn',
+       'refs/owner-exists': 'error',
+     },
+   };
+   ```
+
+3. **Integrate with CI/CD**: Add to your GitHub Actions or GitLab CI
+   ```yaml
+   - run: npx @eventcatalog/linter
+   ```
+
+## 🛠️ Usage
+
+### Basic Usage
+
+Run the linter in your EventCatalog directory:
+
+```bash
+# Lint current directory
+eventcatalog-linter
+
+# Lint specific directory
+eventcatalog-linter ./my-eventcatalog
+
+# Verbose output with detailed information
+eventcatalog-linter --verbose
+
+# Show help
+eventcatalog-linter --help
+```
+
+### CLI Options
+
+```
+Usage: eventcatalog-linter [options] [directory]
+
+Arguments:
+  directory              EventCatalog directory to lint (default: ".")
+
+Options:
+  -V, --version          output the version number
+  -v, --verbose          Show verbose output (default: false)
+  --fail-on-warning      Exit with non-zero code on warnings (default: false)
+  -h, --help             display help for command
+```
+
+### Package.json Integration
+
+Add to your `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "lint:eventcatalog": "eventcatalog-linter",
+    "lint:eventcatalog:verbose": "eventcatalog-linter --verbose"
+  }
+}
+```
+
+### CI/CD Integration
+
+#### GitHub Actions
+
+```yaml
+name: EventCatalog Lint
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - run: npx @eventcatalog/linter
+```
+
+#### GitLab CI
+
+```yaml
+eventcatalog-lint:
+  stage: test
+  image: node:18
+  script:
+    - npx @eventcatalog/linter
+```
+
+## ⚙️ Configuration
+
+The EventCatalog Linter supports optional configuration through a `.eventcatalogrc.js` file in your catalog root directory. This allows you to:
+
+- Turn rules on/off
+- Configure rule severity levels (error, warn, off)
+- Ignore specific file patterns
+- Override rules for specific file patterns
+
+### Configuration File
+
+Create a `.eventcatalogrc.js` file in your EventCatalog root directory:
+
+```javascript
+// .eventcatalogrc.js
+module.exports = {
+  rules: {
+    // Schema validation rules
+    'schema/required-fields': 'error',
+    'schema/valid-semver': 'error',
+    'schema/valid-email': 'warn',
+
+    // Reference validation rules
+    'refs/owner-exists': 'error',
+    'refs/valid-version-range': 'error',
+
+    // Best practice rules
+    'best-practices/summary-required': 'warn',
+    'best-practices/owner-required': 'error',
+  },
+
+  // Ignore certain paths
+  ignorePatterns: ['**/archived/**', '**/drafts/**'],
+
+  // Override rules for specific file patterns
+  overrides: [
+    {
+      files: ['**/experimental/**'],
+      rules: {
+        'best-practices/owner-required': 'off',
+      },
+    },
+  ],
+};
+```
+
+### Rule Severity Levels
+
+- **`'error'`** - Causes the linter to exit with error code 1
+- **`'warn'`** - Shows warnings but allows the linter to pass (unless `--fail-on-warning` is used)
+- **`'off'`** - Disables the rule completely
+
+### Available Rules
+
+| Rule Name                             | Description                                                       | Accepted Values        | Default |
+| ------------------------------------- | ----------------------------------------------------------------- | ---------------------- | ------- |
+| **Schema Validation Rules**           |
+| `schema/required-fields`              | Validates that required fields are present in frontmatter         | `error`, `warn`, `off` | `error` |
+| `schema/valid-type`                   | Validates that field types are correct (strings, arrays, objects) | `error`, `warn`, `off` | `error` |
+| `schema/valid-semver`                 | Validates semantic version format (1.0.0, 2.1.3-beta)             | `error`, `warn`, `off` | `error` |
+| `schema/valid-email`                  | Validates email address format in user frontmatter                | `error`, `warn`, `off` | `error` |
+| `schema/validation-error`             | General schema validation errors                                  | `error`, `warn`, `off` | `error` |
+| **Reference Validation Rules**        |
+| `refs/owner-exists`                   | Ensures referenced owners (users/teams) exist                     | `error`, `warn`, `off` | `error` |
+| `refs/valid-version-range`            | Validates version references and patterns                         | `error`, `warn`, `off` | `error` |
+| `refs/resource-exists`                | Ensures referenced resources exist                                | `error`, `warn`, `off` | `error` |
+| `refs/channel-exists`                 | Ensures channels referenced in sends/receives `to`/`from` exist   | `error`, `warn`, `off` | `error` |
+| `refs/container-exists`               | Ensures containers referenced in `writesTo`/`readsFrom` exist     | `error`, `warn`, `off` | `error` |
+| `refs/orphan-messages`                | Detects events/commands/queries with no producer and no consumer  | `error`, `warn`, `off` | `warn`  |
+| **Best Practice Rules**               |
+| `best-practices/summary-required`     | Requires summary field for better documentation                   | `error`, `warn`, `off` | `error` |
+| `best-practices/owner-required`       | Requires at least one owner for accountability                    | `error`, `warn`, `off` | `error` |
+| `best-practices/description-required` | Requires markdown body content beyond just frontmatter            | `error`, `warn`, `off` | `warn`  |
+| `best-practices/schema-required`      | Requires `schemaPath` on events, commands, and queries            | `error`, `warn`, `off` | `warn`  |
+| **Versioning Rules**                  |
+| `versions/no-deprecated-references`   | Warns when referencing a deprecated resource                      | `error`, `warn`, `off` | `warn`  |
+| **Structural Rules**                  |
+| `structure/duplicate-resource-ids`    | Detects duplicate resources with same type, id, and version       | `error`, `warn`, `off` | `error` |
+
+**Note**: Rules defaulting to `warn` will show warnings but won't fail the linter unless `--fail-on-warning` is used. You can promote them to `error` for stricter validation.
+
+### Configuration Examples
+
+#### Relaxed Configuration for Development
+
+```javascript
+module.exports = {
+  rules: {
+    'best-practices/summary-required': 'warn',
+    'best-practices/owner-required': 'warn',
+    'refs/owner-exists': 'warn',
+  },
+  ignorePatterns: ['**/drafts/**', '**/experimental/**'],
+};
+```
+
+#### Strict Configuration for Production
+
+```javascript
+module.exports = {
+  rules: {
+    'schema/required-fields': 'error',
+    'refs/owner-exists': 'error',
+    'best-practices/summary-required': 'error',
+    'best-practices/owner-required': 'error',
+  },
+};
+```
+
+#### Team-Specific Overrides
+
+```javascript
+module.exports = {
+  rules: {
+    'best-practices/owner-required': 'error',
+    'best-practices/summary-required': 'error',
+  },
+  overrides: [
+    {
+      files: ['**/legacy/**'],
+      rules: {
+        'best-practices/owner-required': 'warn',
+        'best-practices/summary-required': 'off',
+      },
+    },
+    {
+      files: ['**/critical/**'],
+      rules: {
+        'best-practices/summary-required': 'error',
+        'refs/owner-exists': 'error',
+      },
+    },
+  ],
+};
+```
+
+### Using with CI/CD
+
+The configuration file allows you to have different validation rules for different environments:
+
+```bash
+# Development - warnings allowed
+npx @eventcatalog/linter
+
+# Production - fail on warnings
+npx @eventcatalog/linter --fail-on-warning
+```
+
+### Default Behavior
+
+If no `.eventcatalogrc.js` file is found, the linter uses the default rules listed above. Most validations are errors by default, while documentation quality checks such as orphan messages, missing descriptions, missing schemas, and deprecated references default to warnings.
+
+## ✅ What It Validates
+
+### Frontmatter Schema Validation
+
+- ✅ Required fields are present (`id`, `name`, `version`)
+- ✅ Field types are correct (strings, arrays, objects)
+- ✅ Semantic versions follow proper format (`1.0.0`, `2.1.3-beta`)
+- ✅ Version patterns supported (`latest`, `^1.0.0`, `~1.2.0`, `0.0.x`)
+- ✅ URLs are valid format
+- ✅ Email addresses are valid format
+- ✅ Enum values are from allowed lists
+- ✅ Nested object structures are correct
+- ✅ Common resource configuration is supported, including `attachments`, `editUrl`, `diagrams`, `detailsPanel`, sidebar colors, and GraphQL specifications
+
+### Reference Validation
+
+- ✅ Services and systems referenced in domains exist
+- ✅ Agents, data products, flows, entities, and subdomains referenced in domains exist
+- ✅ Services, flows, entities, containers, and relationships referenced in systems exist
+- ✅ Events/Commands/Queries referenced in services exist
+- ✅ Events/Commands/Queries referenced in agents exist
+- ✅ Data product inputs and outputs reference existing resources
+- ✅ ADR relationships and typed `appliesTo` references exist
+- ✅ Entities referenced in domains/services exist
+- ✅ Channels referenced in sends/receives `to`/`from`, routes, messages, and message channels exist
+- ✅ Containers referenced in `writesTo`/`readsFrom` exist
+- ✅ Diagrams referenced from other resources exist
+- ✅ Users/Teams referenced as owners exist
+- ✅ Flow steps reference existing services/messages/agents/containers/data products
+- ✅ Entity properties reference existing entities
+- ✅ User/team owned resources and team members exist
+- ✅ Version-specific references are valid
+- ✅ Orphan messages (no producer and no consumer) are detected
+- ✅ References to deprecated resources are flagged
+- ✅ Duplicate resource IDs (same type, id, and version) are detected
+
+### Documentation Quality
+
+- ✅ Resources have markdown body content (not just frontmatter)
+- ✅ Events/Commands/Queries have a `schemaPath` defined
+
+### Example EventCatalog Structure
+
+```
+my-eventcatalog/
+├── adrs/
+│   └── adr-001/
+│       └── index.mdx
+├── domains/
+│   └── sales/
+│       ├── index.mdx
+│       ├── agents/
+│       │   └── refund-agent/
+│       │       └── index.mdx
+│       ├── channels/
+│       │   └── refunds/
+│       │       └── index.mdx
+│       ├── data-products/
+│       │   └── refund-analytics/
+│       │       └── index.mdx
+│       ├── diagrams/
+│       │   └── refund-flow/
+│       │       └── index.mdx
+│       └── services/
+│           └── order-service/
+│               ├── index.mdx
+│               └── containers/
+│                   └── orders-db/
+│                       └── index.mdx
+├── services/
+│   ├── user-service/
+│   │   └── index.mdx
+│   └── order-service/
+│       ├── index.mdx
+│       └── versioned/
+│           └── 2.0.0/
+│               └── index.mdx
+├── channels/
+│   └── public-events/
+│       └── orders/
+│           └── index.mdx
+├── events/
+│   ├── user-created/
+│   │   └── index.mdx
+│   └── order-placed/
+│       └── index.mdx
+├── commands/
+│   └── create-user/
+│       └── index.mdx
+├── flows/
+│   └── user-registration/
+│       └── index.mdx
+├── entities/
+│   ├── user/
+│   │   └── index.mdx
+│   └── order/
+│       └── index.mdx
+├── users/
+│   ├── john-doe.mdx
+│   └── jane-smith.mdx
+└── teams/
+    └── platform-team.mdx
+```
+
+## 📊 Example Output
+
+### ✅ Success Output
+
+```bash
+$ eventcatalog-linter
+
+✔ No problems found!
+
+  42 files checked
+```
+
+### ❌ Error Output
+
+```bash
+$ eventcatalog-linter
+
+services/user-service/index.mdx
+  ✖ error version: Invalid semantic version format [version] (schema/valid-semver)
+  ⚠ warning Summary is required for better documentation [summary] (best-practices/summary-required)
+
+✖ 2 problems
+
+domains/sales/index.mdx
+  ✖ error Referenced service "order-service" does not exist [services] (refs/resource-exists)
+
+✖ 1 problem
+
+flows/user-registration/index.mdx
+  ✖ error Referenced service "notification-service" (version: 2.0.0) does not exist [steps[1].service] (refs/valid-version-range)
+
+✖ 1 problem
+
+✖ 4 problems (3 errors, 1 warning)
+  3 files checked
+```
+
+### 🔍 Verbose Output
+
+```bash
+$ eventcatalog-linter --verbose
+
+services/user-service/index.mdx
+  ✖ error version: Invalid semantic version format [version] (schema/valid-semver)
+
+✖ 1 problem
+
+domains/sales/index.mdx
+  ✖ error Referenced service "order-service" does not exist [services] (refs/resource-exists)
+
+✖ 1 problem
+
+✖ 2 problems (2 errors, 0 warnings)
+  2 files checked
+```
+
+## 🧪 Validation Examples
+
+### Valid Frontmatter Examples
+
+#### Domain
+
+```yaml
+---
+id: sales
+name: Sales Domain
+version: 1.0.0
+summary: Handles all sales-related operations
+owners:
+  - sales-team
+services:
+  - id: order-service
+    version: 2.0.0
+  - id: payment-service
+agents:
+  - id: refund-agent
+entities:
+  - id: order
+  - id: customer
+    version: 1.2.0
+dataProducts:
+  - id: refund-analytics
+flows:
+  - id: refund-flow
+---
+```
+
+#### Service
+
+```yaml
+---
+id: user-service
+name: User Service
+version: 2.1.0
+summary: Manages user accounts and authentication
+owners:
+  - platform-team
+  - john-doe
+sends:
+  - id: user-created
+    version: 1.0.0
+  - id: user-updated
+receives:
+  - id: create-user
+  - id: update-user
+entities:
+  - id: user
+repository:
+  language: TypeScript
+  url: https://github.com/company/user-service
+---
+```
+
+#### Agent
+
+```yaml
+---
+id: refund-agent
+name: Refund Agent
+version: 1.0.0
+summary: Coordinates customer refund decisions
+owners:
+  - platform-team
+receives:
+  - id: refund-requested
+    from:
+      - id: refunds
+sends:
+  - id: refund-approved
+    to:
+      - id: public-events/orders
+readsFrom:
+  - id: orders-db
+model:
+  provider: OpenAI
+  name: gpt-4.1-mini
+tools:
+  - name: Payment lookup
+    type: mcp
+---
+```
+
+#### Container
+
+```yaml
+---
+id: orders-db
+name: Orders DB
+version: 1.0.0
+summary: Stores order records
+container_type: database
+technology: PostgreSQL
+classification: internal
+access_mode: readWrite
+authoritative: true
+---
+```
+
+#### Data Product
+
+```yaml
+---
+id: refund-analytics
+name: Refund Analytics
+version: 1.0.0
+summary: Curated refund metrics for finance teams
+inputs:
+  - id: refund-approved
+  - id: orders-db
+outputs:
+  - id: public-events/orders
+    contract:
+      path: contracts/refund-analytics.json
+      name: Refund Analytics Contract
+---
+```
+
+#### ADR
+
+```yaml
+---
+id: adr-001
+name: Use event-driven refunds
+version: 1.0.0
+summary: Records the decision to coordinate refunds through events
+status: accepted
+date: 2026-05-26
+decisionMakers:
+  - id: platform-team
+    collection: teams
+appliesTo:
+  - type: service
+    id: order-service
+  - type: data-product
+    id: refund-analytics
+related:
+  - id: adr-000
+---
+```
+
+#### Diagram
+
+```yaml
+---
+id: refund-flow
+name: Refund Flow Diagram
+version: 1.0.0
+summary: Shows the refund workflow across services and agents
+owners:
+  - platform-team
+---
+```
+
+#### Event
+
+```yaml
+---
+id: user-created
+name: User Created
+version: 1.0.0
+summary: Triggered when a new user account is created
+owners:
+  - platform-team
+sidebar:
+  badge: POST
+  label: User Events
+draft: false
+deprecated: false
+---
+```
+
+#### Flow
+
+```yaml
+---
+id: user-registration
+name: User Registration Flow
+version: 1.0.0
+summary: Complete user registration process
+steps:
+  - id: step1
+    title: User submits registration form
+    actor:
+      name: User
+    next_step: step2
+  - id: step2
+    title: Validate user data
+    service:
+      id: user-service
+      version: 2.0.0
+    next_step: step3
+  - id: step3
+    title: Send welcome email
+    message:
+      id: user-created
+      version: 1.0.0
+  - id: step4
+    title: Update analytics
+    dataProduct:
+      id: refund-analytics
+---
+```
+
+## 📦 Version Pattern Support
+
+The linter supports flexible version patterns for resource references, making it easy to work with different versioning strategies:
+
+### Supported Version Patterns
+
+#### Exact Versions
+
+```yaml
+sends:
+  - id: user-created
+    version: 1.0.0 # Exact semantic version
+```
+
+#### Latest Version
+
+```yaml
+sends:
+  - id: user-created
+    version: latest # Always use the latest available version
+```
+
+#### Semver Ranges
+
+```yaml
+sends:
+  - id: user-created
+    version: ^1.0.0 # Compatible with 1.x.x (1.0.0, 1.2.3, but not 2.0.0)
+  - id: user-updated
+    version: ~1.2.0 # Compatible with 1.2.x (1.2.0, 1.2.5, but not 1.3.0)
+```
+
+#### X-Pattern Matching
+
+```yaml
+sends:
+  - id: user-created
+    version: 0.0.x # Matches 0.0.1, 0.0.5, 0.0.12, etc.
+  - id: order-placed
+    version: 1.x # Matches 1.0.0, 1.5.3, 1.99.0, etc.
+```
+
+#### Real-World Example
+
+```yaml
+---
+id: inventory-service
+name: Inventory Service
+version: 2.1.0
+sends:
+  - id: OutOfStock
+    version: latest # Always use latest version
+  - id: GetInventoryList
+    version: 0.0.x # Use any 0.0.x version
+  - id: StockUpdated
+    version: ^1.0.0 # Use compatible 1.x versions
+---
+```
+
+### Common Validation Errors
+
+#### ❌ Missing Required Fields
+
+```yaml
+---
+# Missing 'id' field
+name: User Service
+version: 1.0.0
+---
+```
+
+#### ❌ Invalid Semantic Version
+
+```yaml
+---
+id: user-service
+name: User Service
+version: v1.0 # Should be 1.0.0
+---
+```
+
+#### ❌ Invalid Reference
+
+```yaml
+---
+id: sales-domain
+name: Sales Domain
+version: 1.0.0
+services:
+  - id: non-existent-service # Service doesn't exist
+---
+```
+
+#### ❌ Invalid Email Format
+
+```yaml
+---
+id: john-doe
+name: John Doe
+email: invalid-email # Should be john@example.com
+---
+```
+
+## 🏷️ Rule Names and Error Codes
+
+The linter provides descriptive rule names in parentheses to help identify and fix issues quickly. Each error shows the specific rule that was violated:
+
+### Schema Validation Rules
+
+- `(schema/required-fields)` - Required field is missing
+- `(schema/valid-type)` - Field has wrong data type
+- `(schema/valid-semver)` - Invalid semantic version format
+- `(schema/valid-email)` - Invalid email address format
+- `(schema/validation-error)` - General schema validation error
+
+### Reference Validation Rules
+
+- `(refs/owner-exists)` - Referenced owner (user/team) doesn't exist
+- `(refs/valid-version-range)` - Referenced version doesn't exist or invalid pattern
+- `(refs/resource-exists)` - Referenced resource doesn't exist
+- `(refs/channel-exists)` - Referenced channel in sends/receives to/from, routes, messages, or message channels doesn't exist
+- `(refs/container-exists)` - Referenced container in writesTo/readsFrom or flow steps doesn't exist
+- `(refs/orphan-messages)` - Event/command/query has no producer and no consumer
+
+### Best Practice Rules
+
+- `(best-practices/summary-required)` - Summary field is missing
+- `(best-practices/owner-required)` - At least one owner is required
+- `(best-practices/description-required)` - Markdown body content is missing
+- `(best-practices/schema-required)` - schemaPath is missing on event/command/query
+
+### Versioning Rules
+
+- `(versions/no-deprecated-references)` - Referencing a deprecated resource
+
+### Structural Rules
+
+- `(structure/duplicate-resource-ids)` - Duplicate resource with same type, id, and version
+
+### Parse Errors
+
+- `(@eventcatalog/parse-error)` - YAML/frontmatter parsing error
+
+### Example with Rule Names
+
+```bash
+services/user-service/index.mdx
+  ✖ error name: Expected string, but received undefined [name] (schema/valid-type)
+  ✖ error version: Invalid semantic version format [version] (schema/valid-semver)
+  ✖ error Referenced user/team "missing-owner" does not exist [owners] (refs/owner-exists)
+  ✖ error Summary is required for better documentation [summary] (best-practices/summary-required)
+
+✖ 4 problems
+```
+
+## ⚠️ Warnings Support
+
+The linter can distinguish between errors (which break functionality) and warnings (which suggest improvements):
+
+- **Errors**: Critical issues that must be fixed
+- **Warnings**: Suggestions for better documentation
+
+Use `--fail-on-warning` to treat warnings as errors in CI/CD pipelines:
+
+```bash
+# Exit with error code if warnings are found
+eventcatalog-linter --fail-on-warning
+```
+
+## 🔧 Development
+
+### Setup
+
+```bash
+git clone https://github.com/event-catalog/eventcatalog-linter
+cd eventcatalog-linter
+npm install
+```
+
+### Available Scripts
+
+```bash
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Build the project
+npm run build
+
+# Run in development mode
+npm run dev
+
+# Type checking
+npm run typecheck
+
+# Linting
+npm run lint
+```
+
+### Testing
+
+The linter includes comprehensive tests using Vitest:
+
+- **Schema validation tests** - Ensures all Zod schemas work correctly
+- **Reference validation tests** - Tests cross-reference checking
+- **File scanning tests** - Tests file discovery and parsing
+- **CLI tests** - Tests command-line interface
+- **Integration tests** - End-to-end validation scenarios
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm test -- --coverage
+
+# Run specific test file
+npm test schema-validator.test.ts
+```
+
+### Project Structure
+
+```
+src/
+├── cli/           # Command-line interface
+├── config/        # Configuration loading and rule management
+├── schemas/       # Zod validation schemas
+├── scanner/       # File system scanning
+├── parser/        # Frontmatter parsing
+├── validators/    # Validation logic (schema, reference, best practices)
+├── reporters/     # Error reporting
+└── types/         # TypeScript definitions
+
+tests/
+├── config.test.ts
+├── cli-integration.test.ts
+├── schema-validator.test.ts
+├── reference-validator.test.ts
+├── scanner.test.ts
+└── utils/
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- 📖 [EventCatalog Documentation](https://eventcatalog.dev)
+- 🐛 [Report Issues](https://github.com/event-catalog/eventcatalog-linter/issues)
+- 💬 [Discussions](https://github.com/event-catalog/eventcatalog-linter/discussions)
+
+## 🙏 Acknowledgments
+
+- Built for the [EventCatalog](https://eventcatalog.dev) community
+- Powered by [Zod](https://zod.dev) for schema validation
+- Tested with [Vitest](https://vitest.dev)
diff --git a/packages/linter/package.json b/packages/linter/package.json
new file mode 100644
index 000000000..a11e2c8aa
--- /dev/null
+++ b/packages/linter/package.json
@@ -0,0 +1,59 @@
+{
+  "name": "@eventcatalog/linter",
+  "version": "1.1.4",
+  "description": "A linter for EventCatalog to validate frontmatter and resource references",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/event-catalog/eventcatalog"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "eventcatalog-linter": "./dist/cli/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:bin": "tsup",
+    "test": "vitest --run",
+    "test:ci": "vitest --run",
+    "format": "prettier --write .",
+    "format:diff": "prettier --list-different ."
+  },
+  "keywords": [
+    "eventcatalog",
+    "linter",
+    "validation",
+    "event-driven",
+    "architecture"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@eventcatalog/sdk": "workspace:*",
+    "@types/semver": "^7.7.0",
+    "chalk": "^5.6.2",
+    "commander": "^11.1.0",
+    "fast-glob": "^3.3.2",
+    "gray-matter": "^4.0.3",
+    "ora": "^8.0.1",
+    "semver": "^7.7.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "prettier": "^3.3.3",
+    "tsup": "^8.1.0",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.4"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}
diff --git a/packages/linter/src/cli/index.ts b/packages/linter/src/cli/index.ts
new file mode 100644
index 000000000..04afbeed3
--- /dev/null
+++ b/packages/linter/src/cli/index.ts
@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import path from 'path';
+import { scanCatalogFiles } from '../scanner';
+import { parseAllFiles } from '../parser';
+import { validateCatalog } from '../validators';
+import { reportErrors } from '../reporters';
+import { LinterOptions } from '../types';
+import { loadConfig, loadEventCatalogConfig, shouldIgnoreFile, getEffectiveRules, applyRuleSeverity } from '../config';
+
+const program = new Command();
+
+program
+  .name('eventcatalog-linter')
+  .description('Lint your EventCatalog for frontmatter and reference validation')
+  .version('0.1.0')
+  .argument('[directory]', 'EventCatalog directory to lint', '.')
+  .option('-v, --verbose', 'Show verbose output', false)
+  .option('--fail-on-warning', 'Exit with non-zero code on warnings', false)
+  .action(async (directory: string, options: Partial<LinterOptions>) => {
+    const rootDir = path.resolve(directory);
+    const spinner = ora('Loading configuration...').start();
+
+    try {
+      // Load configuration
+      const config = loadConfig(rootDir);
+      const dependencies = loadEventCatalogConfig(rootDir);
+
+      spinner.text = 'Scanning EventCatalog files...';
+      const allFiles = await scanCatalogFiles(rootDir);
+
+      // Filter out ignored files
+      const files = allFiles.filter((file) => !shouldIgnoreFile(file.relativePath, config.ignorePatterns || []));
+
+      const ignoredCount = allFiles.length - files.length;
+      if (ignoredCount > 0) {
+        spinner.text = `Found ${files.length} catalog files (${ignoredCount} ignored)`;
+      } else {
+        spinner.text = `Found ${files.length} catalog files`;
+      }
+
+      if (files.length === 0) {
+        spinner.warn('No EventCatalog files found');
+        process.exit(0);
+      }
+
+      spinner.text = 'Parsing frontmatter...';
+      const { parsed, errors: parseErrors } = await parseAllFiles(files);
+
+      spinner.text = 'Validating catalog...';
+      const rawValidationErrors = validateCatalog(parsed, dependencies);
+
+      // Apply rule configuration to each file's errors
+      const validationErrors = parsed.flatMap((parsedFile) => {
+        const fileErrors = rawValidationErrors.filter((error) => error.file === parsedFile.file.relativePath);
+        const effectiveRules = getEffectiveRules(parsedFile.file.relativePath, config);
+        return applyRuleSeverity(fileErrors, effectiveRules);
+      });
+
+      spinner.stop();
+
+      const summary = reportErrors(validationErrors, parseErrors, options.verbose);
+
+      // Show scan summary
+      if (summary.totalErrors === 0) {
+        console.log(chalk.dim(`\n  ${files.length} files checked`));
+      }
+
+      if (summary.totalErrors > 0 || (options.failOnWarning && summary.totalWarnings > 0)) {
+        process.exit(1);
+      }
+    } catch (error) {
+      spinner.fail('An error occurred');
+      console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+      process.exit(1);
+    }
+  });
+
+program.parse();
diff --git a/packages/linter/src/config/index.ts b/packages/linter/src/config/index.ts
new file mode 100644
index 000000000..47dabecf2
--- /dev/null
+++ b/packages/linter/src/config/index.ts
@@ -0,0 +1,271 @@
+import fs from 'fs';
+import path from 'path';
+import { ValidationError } from '../types';
+
+export type RuleSeverity = 'error' | 'warn' | 'off';
+
+export interface RuleConfig {
+  severity: RuleSeverity;
+  options?: Record<string, any>;
+}
+
+export interface ConfigOverride {
+  files: string[];
+  rules: Record<string, RuleSeverity | [RuleSeverity, Record<string, any>]>;
+}
+
+export interface LinterConfig {
+  rules: Record<string, RuleSeverity | [RuleSeverity, Record<string, any>]>;
+  ignorePatterns?: string[];
+  overrides?: ConfigOverride[];
+}
+
+export const DEFAULT_IGNORE_PATTERNS: string[] = ['dependencies/**'];
+
+export const DEFAULT_RULES: Record<string, RuleSeverity> = {
+  'schema/required-fields': 'error',
+  'schema/valid-semver': 'error',
+  'schema/valid-email': 'error',
+  'refs/owner-exists': 'error',
+  'refs/valid-version-range': 'error',
+  'refs/resource-exists': 'error',
+  'refs/channel-exists': 'error',
+  'refs/container-exists': 'error',
+  'refs/orphan-messages': 'warn',
+  'best-practices/summary-required': 'error',
+  'best-practices/owner-required': 'error',
+  'best-practices/description-required': 'warn',
+  'best-practices/schema-required': 'warn',
+  'naming/service-id-format': 'error',
+  'naming/event-id-format': 'error',
+  'versions/consistent-format': 'error',
+  'versions/no-deprecated': 'error',
+  'versions/no-deprecated-references': 'warn',
+  'structure/duplicate-resource-ids': 'error',
+};
+
+export interface DependencyEntry {
+  id: string;
+  version?: string;
+}
+
+export type CatalogDependencies = Record<string, DependencyEntry[]>;
+
+const PLURAL_TO_SINGULAR: Record<string, string> = {
+  events: 'event',
+  commands: 'command',
+  queries: 'query',
+  services: 'service',
+  agents: 'agent',
+  adrs: 'adr',
+  domains: 'domain',
+  systems: 'system',
+  entities: 'entity',
+  channels: 'channel',
+  flows: 'flow',
+  users: 'user',
+  teams: 'team',
+  containers: 'container',
+  'data-products': 'dataProduct',
+  diagrams: 'diagram',
+};
+
+const unwrapDefaultExport = (config: unknown): Record<string, any> => {
+  if (config && typeof config === 'object' && 'default' in config) {
+    const defaultExport = (config as Record<string, unknown>).default;
+    if (defaultExport && typeof defaultExport === 'object') {
+      return defaultExport as Record<string, any>;
+    }
+  }
+
+  return config as Record<string, any>;
+};
+
+export const loadEventCatalogConfig = (rootDir: string): CatalogDependencies => {
+  const configPath = path.join(rootDir, 'eventcatalog.config.js');
+
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+
+  try {
+    delete require.cache[require.resolve(configPath)];
+    const config = unwrapDefaultExport(require(configPath));
+
+    if (!config.dependencies || typeof config.dependencies !== 'object') {
+      return {};
+    }
+
+    const dependencies: CatalogDependencies = {};
+
+    for (const [pluralKey, entries] of Object.entries(config.dependencies)) {
+      const singularType = PLURAL_TO_SINGULAR[pluralKey];
+      if (!singularType || !Array.isArray(entries)) continue;
+
+      dependencies[singularType] = (entries as any[])
+        .filter((entry) => entry && typeof entry.id === 'string')
+        .map((entry) => ({ id: entry.id, version: entry.version }));
+    }
+
+    return dependencies;
+  } catch (error) {
+    console.warn(`Warning: Could not load eventcatalog.config.js: ${error instanceof Error ? error.message : String(error)}`);
+    return {};
+  }
+};
+
+export const loadConfig = (rootDir: string): LinterConfig => {
+  const configPath = path.join(rootDir, '.eventcatalogrc.js');
+
+  if (!fs.existsSync(configPath)) {
+    // Return default config if no config file exists
+    return {
+      rules: DEFAULT_RULES,
+      ignorePatterns: DEFAULT_IGNORE_PATTERNS,
+      overrides: [],
+    };
+  }
+
+  try {
+    // Clear module cache to ensure fresh load
+    delete require.cache[require.resolve(configPath)];
+    const config = unwrapDefaultExport(require(configPath));
+
+    // Merge with defaults
+    const mergedConfig: LinterConfig = {
+      rules: { ...DEFAULT_RULES, ...config.rules },
+      ignorePatterns: [...DEFAULT_IGNORE_PATTERNS, ...(config.ignorePatterns || [])],
+      overrides: config.overrides || [],
+    };
+
+    return mergedConfig;
+  } catch (error) {
+    console.warn(`Warning: Could not load .eventcatalogrc.js: ${error instanceof Error ? error.message : String(error)}`);
+    return {
+      rules: DEFAULT_RULES,
+      ignorePatterns: DEFAULT_IGNORE_PATTERNS,
+      overrides: [],
+    };
+  }
+};
+
+export const parseRuleConfig = (rule: RuleSeverity | [RuleSeverity, Record<string, any>]): RuleConfig => {
+  if (Array.isArray(rule)) {
+    return {
+      severity: rule[0],
+      options: rule[1],
+    };
+  }
+  return {
+    severity: rule,
+    options: {},
+  };
+};
+
+export const shouldIgnoreFile = (filePath: string, ignorePatterns: string[]): boolean => {
+  if (!ignorePatterns || ignorePatterns.length === 0) {
+    return false;
+  }
+
+  const normalizedPath = filePath.replace(/\\/g, '/');
+
+  for (const pattern of ignorePatterns) {
+    // Simple glob matching for now
+    const regex = new RegExp(pattern.replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*'));
+    if (regex.test(normalizedPath)) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+export const getEffectiveRules = (filePath: string, config: LinterConfig): Record<string, RuleConfig> => {
+  let effectiveRules = { ...config.rules };
+
+  // Apply overrides
+  if (config.overrides) {
+    for (const override of config.overrides) {
+      const matchesFile = override.files.some((pattern) => {
+        const regex = new RegExp(pattern.replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*'));
+        return regex.test(filePath);
+      });
+
+      if (matchesFile) {
+        effectiveRules = { ...effectiveRules, ...override.rules };
+      }
+    }
+  }
+
+  // Parse rules into RuleConfig objects
+  const parsedRules: Record<string, RuleConfig> = {};
+  for (const [ruleName, ruleValue] of Object.entries(effectiveRules)) {
+    parsedRules[ruleName] = parseRuleConfig(ruleValue);
+  }
+
+  return parsedRules;
+};
+
+export const applyRuleSeverity = (errors: ValidationError[], rules: Record<string, RuleConfig>): ValidationError[] => {
+  const result: ValidationError[] = [];
+
+  for (const error of errors) {
+    // Map validation errors to rule names
+    const ruleName = mapErrorToRuleName(error);
+    const rule = rules[ruleName];
+
+    if (!rule || rule.severity === 'off') {
+      continue; // Skip disabled rules
+    }
+
+    result.push({
+      ...error,
+      severity: rule.severity === 'warn' ? ('warning' as const) : ('error' as const),
+    });
+  }
+
+  return result;
+};
+
+const mapErrorToRuleName = (error: ValidationError): string => {
+  // Use explicit rule if set by the validator
+  if (error.rule) {
+    return error.rule;
+  }
+
+  // Map validation errors to rule names based on the error type and content
+  if (error.type === 'schema') {
+    // Check field-specific rules first
+    if (error.field === 'summary') {
+      return 'best-practices/summary-required';
+    }
+    if (error.field === 'owners') {
+      return 'best-practices/owner-required';
+    }
+
+    // Check message content for specific validation types
+    if (error.message.includes('email') || error.message.includes('Invalid email')) {
+      return 'schema/valid-email';
+    }
+    if (error.message.includes('version') || error.message.includes('semantic')) {
+      return 'schema/valid-semver';
+    }
+    if (error.message.includes('Required') || error.message.includes('Expected')) {
+      return 'schema/required-fields';
+    }
+
+    return 'schema/required-fields';
+  }
+
+  if (error.type === 'reference') {
+    if (error.message.includes('user') || error.message.includes('team')) {
+      return 'refs/owner-exists';
+    }
+    if (error.message.includes('version')) {
+      return 'refs/valid-version-range';
+    }
+    return 'refs/resource-exists';
+  }
+
+  return 'schema/required-fields';
+};
diff --git a/packages/linter/src/index.ts b/packages/linter/src/index.ts
new file mode 100644
index 000000000..6e04b2352
--- /dev/null
+++ b/packages/linter/src/index.ts
@@ -0,0 +1,7 @@
+export * from './types';
+export * from './schemas';
+export * from './scanner';
+export * from './parser';
+export * from './validators';
+export * from './reporters';
+export * from './config';
diff --git a/packages/linter/src/parser/index.ts b/packages/linter/src/parser/index.ts
new file mode 100644
index 000000000..416b6dd09
--- /dev/null
+++ b/packages/linter/src/parser/index.ts
@@ -0,0 +1,56 @@
+import fs from 'fs/promises';
+import matter from 'gray-matter';
+import { CatalogFile } from '../scanner';
+
+export interface ParsedFile {
+  file: CatalogFile;
+  frontmatter: Record<string, unknown>;
+  content: string;
+  raw: string;
+}
+
+export interface ParseError {
+  file: CatalogFile;
+  error: Error;
+}
+
+export const parseFrontmatter = async (file: CatalogFile): Promise<ParsedFile | ParseError> => {
+  try {
+    const fileContent = await fs.readFile(file.path, 'utf-8');
+    const { data, content } = matter(fileContent);
+
+    return {
+      file,
+      frontmatter: data,
+      content,
+      raw: fileContent,
+    };
+  } catch (error) {
+    return {
+      file,
+      error: error instanceof Error ? error : new Error(String(error)),
+    };
+  }
+};
+
+export const parseAllFiles = async (
+  files: CatalogFile[]
+): Promise<{
+  parsed: ParsedFile[];
+  errors: ParseError[];
+}> => {
+  const results = await Promise.all(files.map(parseFrontmatter));
+
+  const parsed: ParsedFile[] = [];
+  const errors: ParseError[] = [];
+
+  for (const result of results) {
+    if ('error' in result) {
+      errors.push(result);
+    } else {
+      parsed.push(result);
+    }
+  }
+
+  return { parsed, errors };
+};
diff --git a/packages/linter/src/reporters/index.ts b/packages/linter/src/reporters/index.ts
new file mode 100644
index 000000000..5f786e475
--- /dev/null
+++ b/packages/linter/src/reporters/index.ts
@@ -0,0 +1,185 @@
+import chalk from 'chalk';
+import { ValidationError } from '../types';
+import { ParseError } from '../parser';
+
+export interface ReportSummary {
+  totalErrors: number;
+  totalWarnings: number;
+  schemaErrors: number;
+  referenceErrors: number;
+  parseErrors: number;
+  filesChecked: number;
+  filesWithErrors: number;
+}
+
+export const formatError = (error: ValidationError, showFilename: boolean = true): string => {
+  const lineInfo = error.line ? chalk.dim(`:${error.line}:1`) : '';
+  const filename = showFilename ? `${chalk.dim(error.file)}${lineInfo}` : '';
+
+  const isWarning = error.severity === 'warning';
+  const severity = isWarning ? chalk.yellow('warning') : chalk.red('error');
+  const icon = isWarning ? chalk.yellow('⚠') : chalk.red('✖');
+  const errorCode = getErrorCode(error);
+  const field = error.field ? chalk.dim(`[${error.field}]`) : '';
+
+  const parts = [];
+  if (filename) parts.push(filename);
+  parts.push(icon, severity, error.message, field, chalk.dim(errorCode));
+
+  return parts.filter(Boolean).join(' ');
+};
+
+const getErrorCode = (error: ValidationError): string => {
+  if (error.rule) {
+    return `(${error.rule})`;
+  }
+
+  // Fallback to generic error codes
+  if (error.type === 'schema') {
+    if (error.field) {
+      if (error.message.includes('Required')) return '(@eventcatalog/required-field)';
+      if (error.message.includes('Expected')) return '(@eventcatalog/invalid-type)';
+      return '(@eventcatalog/schema-validation)';
+    }
+    return '(@eventcatalog/schema)';
+  }
+  if (error.type === 'reference') {
+    return '(@eventcatalog/invalid-reference)';
+  }
+  return '(@eventcatalog/unknown)';
+};
+
+export const formatParseError = (error: ParseError, showFilename: boolean = true): string => {
+  const filename = showFilename ? chalk.dim(error.file.relativePath) : '';
+  const severity = chalk.red('error');
+  const message = `Parse error: ${error.error.message}`;
+  const errorCode = chalk.dim('(@eventcatalog/parse-error)');
+
+  const parts = [];
+  if (filename) parts.push(filename);
+  parts.push(chalk.red('✖'), severity, message, errorCode);
+
+  return parts.filter(Boolean).join(' ');
+};
+
+export const groupErrorsByFile = (errors: ValidationError[]): Map<string, ValidationError[]> => {
+  const grouped = new Map<string, ValidationError[]>();
+
+  for (const error of errors) {
+    if (!grouped.has(error.file)) {
+      grouped.set(error.file, []);
+    }
+    grouped.get(error.file)!.push(error);
+  }
+
+  return grouped;
+};
+
+export const reportErrors = (
+  validationErrors: ValidationError[],
+  parseErrors: ParseError[],
+  verbose: boolean = false
+): ReportSummary => {
+  const allErrors = [
+    ...validationErrors,
+    ...parseErrors.map((pe) => ({
+      type: 'parse' as const,
+      resource: pe.file.resourceType || 'unknown',
+      message: pe.error.message,
+      file: pe.file.relativePath,
+      line: undefined,
+    })),
+  ];
+
+  const schemaErrors = validationErrors.filter((e) => e.type === 'schema');
+  const referenceErrors = validationErrors.filter((e) => e.type === 'reference');
+  const warnings = validationErrors.filter((e) => e.severity === 'warning');
+  const errors = [...validationErrors.filter((e) => e.severity !== 'warning'), ...parseErrors];
+  const totalErrors = errors.length;
+  const totalWarnings = warnings.length;
+
+  if (totalErrors === 0 && totalWarnings === 0) {
+    console.log(chalk.green('✔ No problems found!'));
+    return {
+      totalErrors: 0,
+      totalWarnings: 0,
+      schemaErrors: 0,
+      referenceErrors: 0,
+      parseErrors: 0,
+      filesChecked: 0,
+      filesWithErrors: 0,
+    };
+  }
+
+  const grouped = groupErrorsByFile(validationErrors);
+  const parseErrorsGrouped = groupParseErrorsByFile(parseErrors);
+  const allFiles = new Set([...grouped.keys(), ...parseErrorsGrouped.keys()]);
+
+  console.log(); // Empty line
+
+  // Report by file for better readability
+  for (const file of Array.from(allFiles).sort()) {
+    const fileErrors = grouped.get(file) || [];
+    const fileParseErrors = parseErrorsGrouped.get(file) || [];
+    const fileErrorCount = fileErrors.length + fileParseErrors.length;
+
+    if (fileErrorCount === 0) continue;
+
+    // File header (ESLint-style)
+    console.log(chalk.underline(file));
+
+    // Parse errors first
+    for (const error of fileParseErrors) {
+      console.log(`  ${formatParseError(error, false)}`);
+    }
+
+    // Then validation errors
+    for (const error of fileErrors) {
+      console.log(`  ${formatError(error, false)}`);
+    }
+
+    // File summary
+    const fileWarnings = fileErrors.filter((e) => e.severity === 'warning').length;
+    const fileActualErrors = fileErrorCount - fileWarnings;
+    const problemText = fileErrorCount === 1 ? 'problem' : 'problems';
+    const summaryColor = fileActualErrors > 0 ? chalk.red : chalk.yellow;
+    const summaryIcon = fileActualErrors > 0 ? '✖' : '⚠';
+    console.log(summaryColor(`\n${summaryIcon} ${fileErrorCount} ${problemText}\n`));
+  }
+
+  // Overall summary (ESLint-style)
+  const filesWithErrors = allFiles.size;
+  const totalProblems = totalErrors + totalWarnings;
+  const problemText = totalProblems === 1 ? 'problem' : 'problems';
+  const fileText = filesWithErrors === 1 ? 'file' : 'files';
+
+  const summaryColor = totalErrors > 0 ? chalk.red.bold : chalk.yellow.bold;
+  const summaryIcon = totalErrors > 0 ? '✖' : '⚠';
+
+  console.log(summaryColor(`${summaryIcon} ${totalProblems} ${problemText} (${totalErrors} errors, ${totalWarnings} warnings)`));
+  console.log(chalk.dim(`  ${filesWithErrors} ${fileText} checked`));
+
+  return {
+    totalErrors,
+    totalWarnings,
+    schemaErrors: schemaErrors.length,
+    referenceErrors: referenceErrors.length,
+    parseErrors: parseErrors.length,
+    filesChecked: allFiles.size,
+    filesWithErrors,
+  };
+};
+
+const groupParseErrorsByFile = (errors: ParseError[]): Map<string, ParseError[]> => {
+  const grouped = new Map<string, ParseError[]>();
+
+  for (const error of errors) {
+    const file = error.file.relativePath;
+    if (!grouped.has(file)) {
+      grouped.set(file, []);
+    }
+    grouped.get(file)!.push(error);
+  }
+
+  return grouped;
+};
diff --git a/packages/linter/src/scanner/index.ts b/packages/linter/src/scanner/index.ts
new file mode 100644
index 000000000..ab373a9b5
--- /dev/null
+++ b/packages/linter/src/scanner/index.ts
@@ -0,0 +1,148 @@
+import fg from 'fast-glob';
+import path from 'path';
+import { ResourceType } from '../schemas';
+
+export interface CatalogFile {
+  path: string;
+  relativePath: string;
+  resourceType: ResourceType;
+  resourceId: string;
+  version?: string;
+}
+
+const RESOURCE_DIRECTORY_NAMES: Partial<Record<ResourceType, string>> = {
+  dataProduct: 'data-products',
+  dataStore: 'containers',
+  container: 'containers',
+  adr: 'adrs',
+};
+
+const RESOURCE_PATTERNS: Partial<Record<ResourceType, string[]>> = {
+  domain: [
+    'domains/*/index.{md,mdx}',
+    'domains/*/versioned/*/index.{md,mdx}',
+    'domains/*/subdomains/*/index.{md,mdx}',
+    'domains/*/subdomains/*/versioned/*/index.{md,mdx}',
+  ],
+  system: [
+    '**/systems/**/index.{md,mdx}',
+    '**/systems/**/versioned/*/index.{md,mdx}',
+    '!**/systems/**/agents/**',
+    '!**/systems/**/services/**',
+    '!**/systems/**/events/**',
+    '!**/systems/**/commands/**',
+    '!**/systems/**/queries/**',
+    '!**/systems/**/flows/**',
+    '!**/systems/**/channels/**',
+    '!**/systems/**/entities/**',
+    '!**/systems/**/containers/**',
+    '!**/systems/**/diagrams/**',
+    '!**/systems/**/data-products/**',
+    '!**/systems/**/adrs/**',
+    '!**/systems/**/docs/**',
+  ],
+  service: [
+    'domains/*/services/*/index.{md,mdx}',
+    'domains/*/services/*/versioned/*/index.{md,mdx}',
+    'domains/*/subdomains/*/services/*/index.{md,mdx}',
+    'domains/*/subdomains/*/services/*/versioned/*/index.{md,mdx}',
+    '**/systems/**/services/*/index.{md,mdx}',
+    '**/systems/**/services/*/versioned/*/index.{md,mdx}',
+    'services/*/index.{md,mdx}',
+    'services/*/versioned/*/index.{md,mdx}',
+  ],
+  agent: ['**/agents/*/index.{md,mdx}', '**/agents/*/versioned/*/index.{md,mdx}'],
+  adr: ['**/adrs/*/index.{md,mdx}', '**/adrs/*/versioned/*/index.{md,mdx}'],
+  event: ['**/events/*/index.{md,mdx}', '**/events/*/versioned/*/index.{md,mdx}'],
+  command: ['**/commands/*/index.{md,mdx}', '**/commands/*/versioned/*/index.{md,mdx}'],
+  query: ['**/queries/*/index.{md,mdx}', '**/queries/*/versioned/*/index.{md,mdx}'],
+  channel: ['**/channels/**/index.{md,mdx}', '**/channels/**/versioned/*/index.{md,mdx}'],
+  flow: ['**/flows/**/index.{md,mdx}', '**/flows/**/versioned/*/index.{md,mdx}'],
+  entity: ['**/entities/*/index.{md,mdx}', '**/entities/*/versioned/*/index.{md,mdx}'],
+  container: ['**/containers/**/index.{md,mdx}', '**/containers/**/versioned/*/index.{md,mdx}'],
+  dataProduct: ['**/data-products/*/index.{md,mdx}', '**/data-products/*/versioned/*/index.{md,mdx}'],
+  diagram: ['**/diagrams/**/index.{md,mdx}', '**/diagrams/**/versioned/*/index.{md,mdx}'],
+  user: ['users/*.{md,mdx}'],
+  team: ['teams/*.{md,mdx}'],
+};
+
+export const extractResourceInfo = (filePath: string, resourceType: ResourceType): { id: string; version?: string } => {
+  // Normalize path separators to forward slashes for consistent parsing across platforms
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  const relativePath = normalizedPath.split('/');
+
+  if (resourceType === 'user' || resourceType === 'team') {
+    const filename = path.basename(filePath, path.extname(filePath));
+    return { id: filename };
+  }
+
+  // Find the resource type directory in the path
+  const resourceTypePattern = RESOURCE_DIRECTORY_NAMES[resourceType] || `${resourceType}s`;
+  const resourceTypeIndex = relativePath.findIndex((part) => part === resourceTypePattern);
+
+  if (resourceTypeIndex === -1) {
+    // Fallback to original logic if pattern not found
+    const parts = relativePath.slice(1, -1);
+    return { id: parts[parts.length - 1] };
+  }
+
+  // Extract parts after the resource type directory, excluding index.mdx
+  const parts = relativePath.slice(resourceTypeIndex + 1, -1);
+
+  if (parts.length === 0) {
+    return { id: 'unknown' };
+  }
+
+  // Check for versioned structure: resourceId/versioned/version/index.mdx
+  if (parts.length >= 3 && parts[parts.length - 2] === 'versioned') {
+    const version = parts[parts.length - 1];
+    const resourceId = parts.slice(0, -2).join('/');
+    return { id: resourceId, version };
+  }
+
+  // Check for domain versioned structure: domains/domainId/versioned/version/index.mdx
+  if (resourceType === 'domain' && parts.length >= 2) {
+    const versionedIndex = parts.findIndex((part) => part === 'versioned');
+    if (versionedIndex !== -1 && versionedIndex < parts.length - 1) {
+      const version = parts[versionedIndex + 1];
+      const resourceId = parts.slice(0, versionedIndex).join('/');
+      return { id: resourceId, version };
+    }
+  }
+
+  // Standard structure: resourceId/index.mdx
+  if (parts.length === 1) {
+    return { id: parts[0] };
+  }
+
+  // Handle subdomain structure or nested resources
+  return { id: parts.join('/') };
+};
+
+export const scanCatalogFiles = async (rootDir: string): Promise<CatalogFile[]> => {
+  const files: CatalogFile[] = [];
+
+  for (const [resourceType, patterns] of Object.entries(RESOURCE_PATTERNS)) {
+    const foundFiles = await fg(patterns, {
+      cwd: rootDir,
+      absolute: true,
+      onlyFiles: true,
+      followSymbolicLinks: false,
+    });
+
+    for (const filePath of foundFiles) {
+      const relativePath = path.relative(rootDir, filePath);
+      const { id, version } = extractResourceInfo(relativePath, resourceType as ResourceType);
+
+      files.push({
+        path: filePath,
+        relativePath,
+        resourceType: resourceType as ResourceType,
+        resourceId: id,
+        version,
+      });
+    }
+  }
+
+  return files;
+};
diff --git a/packages/linter/src/schemas/adr.ts b/packages/linter/src/schemas/adr.ts
new file mode 100644
index 000000000..cefc317ef
--- /dev/null
+++ b/packages/linter/src/schemas/adr.ts
@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { baseSchema, detailPanelPropertySchema, pointerSchema, resourcePointerSchema } from './common';
+
+export const adrSchema = z
+  .object({
+    status: z.enum(['proposed', 'accepted', 'rejected', 'deprecated', 'superseded']),
+    date: z.coerce.date(),
+    decisionMakers: z.array(z.any()).optional(),
+    appliesTo: z.array(resourcePointerSchema).optional(),
+    supersedes: z.array(pointerSchema).optional(),
+    supersededBy: z.array(pointerSchema).optional(),
+    amends: z.array(pointerSchema).optional(),
+    amendedBy: z.array(pointerSchema).optional(),
+    related: z.array(pointerSchema).optional(),
+    detailsPanel: z
+      .object({
+        status: detailPanelPropertySchema,
+        date: detailPanelPropertySchema,
+        decisionMakers: detailPanelPropertySchema,
+        appliesTo: detailPanelPropertySchema,
+        relationships: detailPanelPropertySchema,
+        owners: detailPanelPropertySchema,
+        repository: detailPanelPropertySchema,
+        changelog: detailPanelPropertySchema,
+      })
+      .optional(),
+  })
+  .merge(baseSchema);
diff --git a/packages/linter/src/schemas/agent.ts b/packages/linter/src/schemas/agent.ts
new file mode 100644
index 000000000..9454ee51b
--- /dev/null
+++ b/packages/linter/src/schemas/agent.ts
@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { baseSchema, detailPanelPropertySchema, pointerSchema, receivesPointerSchema, sendsPointerSchema } from './common';
+
+const agentToolSchema = z.object({
+  name: z.string(),
+  type: z.string(),
+  icon: z.string().optional(),
+  url: z.string().optional(),
+  description: z.string().optional(),
+});
+
+const agentModelSchema = z.object({
+  provider: z.string().optional(),
+  name: z.string().optional(),
+  version: z.string().optional(),
+});
+
+export const agentSchema = z
+  .object({
+    sends: z.array(sendsPointerSchema).optional(),
+    receives: z.array(receivesPointerSchema).optional(),
+    writesTo: z.array(pointerSchema).optional(),
+    readsFrom: z.array(pointerSchema).optional(),
+    flows: z.array(pointerSchema).optional(),
+    model: agentModelSchema.optional(),
+    tools: z.array(agentToolSchema).optional(),
+    specifications: z.undefined().optional(),
+    detailsPanel: z
+      .object({
+        domains: detailPanelPropertySchema,
+        messages: detailPanelPropertySchema,
+        versions: detailPanelPropertySchema,
+        repository: detailPanelPropertySchema,
+        owners: detailPanelPropertySchema,
+        changelog: detailPanelPropertySchema,
+        containers: detailPanelPropertySchema,
+        tools: detailPanelPropertySchema,
+        model: detailPanelPropertySchema,
+      })
+      .optional(),
+  })
+  .merge(baseSchema.omit({ specifications: true }));
diff --git a/packages/linter/src/schemas/channel.ts b/packages/linter/src/schemas/channel.ts
new file mode 100644
index 000000000..5baab6aa8
--- /dev/null
+++ b/packages/linter/src/schemas/channel.ts
@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { baseSchema, detailPanelPropertySchema, pointerSchema, channelPointerSchema } from './common';
+
+const parameterSchema = z.object({
+  enum: z.array(z.string()).optional(),
+  default: z.string().optional(),
+  examples: z.array(z.string()).optional(),
+  description: z.string().optional(),
+});
+
+export const channelSchema = z
+  .object({
+    channels: z.array(channelPointerSchema).optional(),
+    address: z.string().optional(),
+    protocols: z.array(z.string()).optional(),
+    deliveryGuarantee: z.enum(['at-most-once', 'at-least-once', 'exactly-once']).optional(),
+    routes: z.array(channelPointerSchema).optional(),
+    parameters: z.record(parameterSchema).optional(),
+    messages: z.array(z.object({ collection: z.string(), name: z.string(), ...pointerSchema.shape })).optional(),
+    detailsPanel: z
+      .object({
+        producers: detailPanelPropertySchema,
+        consumers: detailPanelPropertySchema,
+        messages: detailPanelPropertySchema,
+        protocols: detailPanelPropertySchema,
+        parameters: detailPanelPropertySchema,
+        versions: detailPanelPropertySchema,
+        repository: detailPanelPropertySchema,
+        owners: detailPanelPropertySchema,
+        changelog: detailPanelPropertySchema,
+        attachments: detailPanelPropertySchema,
+      })
+      .optional(),
+  })
+  .merge(baseSchema);
diff --git a/packages/linter/src/schemas/common.ts b/packages/linter/src/schemas/common.ts
new file mode 100644
index 000000000..36079679b
--- /dev/null
+++ b/packages/linter/src/schemas/common.ts
@@ -0,0 +1,235 @@
+import { z } from 'zod';
+
+export const badgeSchema = z.object({
+  content: z.string(),
+  backgroundColor: z.string(),
+  textColor: z.string(),
+  icon: z.string().optional(),
+  url: z.string().optional(),
+});
+
+export const ownerReferenceSchema = z
+  .union([
+    // The ID of the user or team
+    z.string(),
+    // The full object with the ID and collection (keep compatibility with `reference`)
+    z.object({
+      id: z.string(),
+      collection: z.enum(['users', 'teams']),
+    }),
+  ])
+  .transform(
+    // This transformation is needed to keep compatibility with `reference`.
+    // The utilities `getTeams` and `getUsers` rely on this transformation.
+    (lookup) => ({ id: typeof lookup === 'string' ? lookup : lookup.id })
+  );
+
+export const specificationSchema = z.union([
+  z.object({
+    openapiPath: z.string().optional(),
+    asyncapiPath: z.string().optional(),
+    graphqlPath: z.string().optional(),
+  }),
+  z.array(
+    z.object({
+      type: z.enum(['openapi', 'asyncapi', 'graphql']),
+      path: z.string(),
+      name: z.string().optional(),
+      headers: z.record(z.string()).optional(),
+    })
+  ),
+]);
+
+export const repositorySchema = z.object({
+  language: z.string().optional(),
+  url: z.string().optional(),
+});
+
+export const draftSchema = z.union([
+  z.boolean(),
+  z.object({
+    title: z.string().optional(),
+    message: z.string(),
+  }),
+]);
+
+export const deprecatedSchema = z.union([
+  z.object({
+    message: z.string().optional(),
+    date: z.union([z.string(), z.date()]).optional(),
+  }),
+  z.boolean().optional(),
+]);
+
+export const pointerSchema = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+});
+
+export const resourcePointerSchema = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+  type: z.enum([
+    'agent',
+    'service',
+    'event',
+    'command',
+    'query',
+    'flow',
+    'channel',
+    'domain',
+    'system',
+    'user',
+    'team',
+    'container',
+    'entity',
+    'diagram',
+    'data-product',
+    'adr',
+  ]),
+});
+
+export const channelPointerSchema = z
+  .object({
+    parameters: z.record(z.string()).optional(),
+  })
+  .merge(pointerSchema);
+
+export const detailPanelPropertySchema = z
+  .object({
+    visible: z.boolean().optional(),
+  })
+  .optional();
+
+export const sendsPointerSchema = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+  fields: z.array(z.string()).optional(),
+  group: z.string().optional(),
+  to: z
+    .array(
+      channelPointerSchema.extend({
+        delivery_mode: z.enum(['push', 'pull', 'push-pull']).optional().default('push'),
+      })
+    )
+    .optional(),
+});
+
+export const receivesPointerSchema = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+  fields: z.array(z.string()).optional(),
+  group: z.string().optional(),
+  from: z
+    .array(
+      channelPointerSchema.extend({
+        delivery_mode: z.enum(['push', 'pull', 'push-pull']).optional().default('push'),
+      })
+    )
+    .optional(),
+});
+
+export const resourceReferenceSchema = pointerSchema;
+
+export const semverSchema = z.string().refine((version) => {
+  // Allow common patterns used in EventCatalog
+  if (version === 'latest') return true;
+
+  // Allow x patterns like 0.0.x, 1.x, 2.1.x but not x.x.x
+  if (version.includes('.x')) {
+    const xPattern = /^\d+(\.\d+)*\.x$/;
+    return xPattern.test(version);
+  }
+
+  // Allow semver ranges like ^1.0.0, ~1.2.0
+  if (version.startsWith('^') || version.startsWith('~')) {
+    const rangeVersion = version.substring(1);
+    const semverRegex = /^\d+\.\d+\.\d+(-[\w\d-.]+)?(\+[\w\d-.]+)?$/;
+    return semverRegex.test(rangeVersion);
+  }
+
+  // For strict semver, use a regex that matches the semver spec
+  const semverRegex = /^\d+\.\d+\.\d+(-[\w\d-.]+)?(\+[\w\d-.]+)?$/;
+  return semverRegex.test(version);
+}, 'Invalid semantic version format');
+
+export const sidebarSchema = z
+  .object({
+    label: z.string().optional(),
+    badge: z.string().optional(),
+    color: z.string().optional(),
+    backgroundColor: z.string().optional(),
+  })
+  .optional();
+
+export const stylesSchema = z
+  .object({
+    icon: z.string().optional(),
+    node: z
+      .object({
+        color: z.string().optional(),
+        label: z.string().optional(),
+      })
+      .optional(),
+  })
+  .optional();
+
+export const resourceGroupSchema = z
+  .array(
+    z.object({
+      id: z.string().optional(),
+      title: z.string().optional(),
+      items: z.array(resourcePointerSchema),
+      limit: z.number().optional().default(10),
+      sidebar: z.boolean().optional().default(true),
+    })
+  )
+  .optional();
+
+export const catalogMetadataSchema = z
+  .object({
+    path: z.string(),
+    filePath: z.string(),
+    astroContentFilePath: z.string(),
+    publicPath: z.string(),
+    type: z.string(),
+  })
+  .optional();
+
+export const baseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  summary: z.string().optional(),
+  version: semverSchema,
+  draft: z.union([z.boolean(), z.object({ title: z.string().optional(), message: z.string() })]).optional(),
+  badges: z.array(badgeSchema).optional(),
+  owners: z.array(ownerReferenceSchema).optional(),
+  schemaPath: z.string().optional(),
+  sidebar: sidebarSchema,
+  repository: repositorySchema.optional(),
+  specifications: specificationSchema.optional(),
+  hidden: z.boolean().optional(),
+  editUrl: z.string().optional(),
+  resourceGroups: resourceGroupSchema,
+  styles: stylesSchema,
+  deprecated: deprecatedSchema.optional(),
+  visualiser: z.boolean().optional(),
+  attachments: z
+    .array(
+      z.union([
+        z.string().url(),
+        z.object({
+          url: z.string().url(),
+          title: z.string().optional(),
+          type: z.string().optional(),
+          description: z.string().optional(),
+          icon: z.string().optional(),
+        }),
+      ])
+    )
+    .optional(),
+  diagrams: z.array(pointerSchema).optional(),
+  versions: z.array(z.string()).optional(),
+  latestVersion: z.string().optional(),
+  catalog: catalogMetadataSchema,
+});
diff --git a/packages/linter/src/schemas/container.ts b/packages/linter/src/schemas/container.ts
new file mode 100644
index 000000000..7dda4378c
--- /dev/null
+++ b/packages/linter/src/schemas/container.ts
@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { baseSchema, detailPanelPropertySchema } from './common';
+
+export const containerSchema = z
+  .object({
+    container_type: z.enum([
+      'database',
+      'cache',
+      'objectStore',
+      'searchIndex',
+      'dataWarehouse',
+      'dataLake',
+      'externalSaaS',
+      'other',
+    ]),
+    technology: z.string().optional(),
+    authoritative: z.boolean().optional().default(false),
+    access_mode: z.enum(['read', 'write', 'readWrite', 'appendOnly']).optional(),
+    classification: z.enum(['public', 'internal', 'confidential', 'regulated']).optional(),
+    residency: z.string().optional(),
+    retention: z.string().optional(),
+    detailsPanel: z
+      .object({
+        versions: detailPanelPropertySchema,
+        repository: detailPanelPropertySchema,
+        owners: detailPanelPropertySchema,
+        changelog: detailPanelPropertySchema,
+        attachments: detailPanelPropertySchema,
+        services: detailPanelPropertySchema,
+        flows: detailPanelPropertySchema,
+      })
+      .optional(),
+    services: z.array(z.any()).optional(),
+    servicesThatWriteToContainer: z.array(z.any()).optional(),
+    servicesThatReadFromContainer: z.array(z.any()).optional(),
+    dataProductsThatWriteToContainer: z.array(z.any()).optional(),
+    dataProductsThatReadFromContainer: z.array(z.any()).optional(),
+  })
+  .merge(baseSchema);
diff --git a/packages/linter/src/schemas/data-product.ts b/packages/linter/src/schemas/data-product.ts
new file mode 100644
index 000000000..15d62360d
--- /dev/null
+++ b/packages/linter/src/schemas/data-product.ts
@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { baseSchema, detailPanelPropertySchema, pointerSchema } from './common';
+
+const dataProductOutputPointerSchema = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+  contract: z
+    .object({
+      path: z.string(),
+      name: z.string(),
+      type: z.string().optional(),
+    })
+    .optional(),
+});
+
+export const dataProductSchema = z
+  .object({
+    inputs: z.array(pointerSchema).optional(),
+    outputs: z.array(dataProductOutputPointerSchema).optional(),
+    detailsPanel: z
+      .object({
+        domains: detailPanelPropertySchema,
+        inputs: detailPanelPropertySchema,
+        outputs: detailPanelPropertySchema,
+        versions: detailPanelPropertySchema,
+        repository: detailPanelPropertySchema,
+        owners: detailPanelPropertySchema,
+        changelog: detailPanelPropertySchema,
+        flows: detailPanelPropertySchema,
+      })
+      .optional(),
+  })
+  .merge(baseSchema);
diff --git a/packages/linter/src/schemas/data-store.ts b/packages/linter/src/schemas/data-store.ts
new file mode 100644
index 000000000..108531a51
--- /dev/null
+++ b/packages/linter/src/schemas/data-store.ts
@@ -0,0 +1 @@
+export { containerSchema as dataStoreSchema } from './container';
diff --git a/packages/linter/src/schemas/diagram.ts b/packages/linter/src/schemas/diagram.ts
new file mode 100644
index 000000000..890bfd4da
--- /dev/null
+++ b/packages/linter/src/schemas/diagram.ts
@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { baseSchema, detailPanelPropertySchema } from './common';
+
+export const diagramSchema = z
+  .object({
+    detailsPanel: z
+      .object({
+        versions: detailPanelPropertySchema,
+        owners: detailPanelPropertySchema,
+        changelog: detailPanelPropertySchema,
+        attachments: detailPanelPropertySchema,
+      })
+      .optional(),
+  })
+  .merge(baseSchema);
diff --git a/packages/linter/src/schemas/domain.ts b/packages/linter/src/schemas/domain.ts
new file mode 100644
index 000000000..4fc04af5e
--- /dev/null
+++ b/packages/linter/src/schemas/domain.ts
@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { baseSchema, pointerSchema, receivesPointerSchema, sendsPointerSchema, detailPanelPropertySchema } from './common';
+
+export const domainSchema = z
+  .object({
+    services: z.array(pointerSchema).optional(),
+    agents: z.array(pointerSchema).optional(),
+    domains: z.array(pointerSchema).optional(),
+    systems: z.array(pointerSchema).optional(),
+    entities: z.array(pointerSchema).optional(),
+    'data-products': z.array(pointerSchema).optional(),
+    dataProducts: z.array(pointerSchema).optional(),
+    flows: z.array(pointerSchema).optional(),
+    sends: z.array(sendsPointerSchema).optional(),
+    receives: z.array(receivesPointerSchema).optional(),
+    detailsPanel: z
+      .object({
+        parentDomains: detailPanelPropertySchema,
+        subdomains: detailPanelPropertySchema,
+        systems: detailPanelPropertySchema,
+        services: detailPanelPropertySchema,
+        agents: detailPanelPropertySchema,
+        entities: detailPanelPropertySchema,
+        messages: detailPanelPropertySchema,
+        ubiquitousLanguage: detailPanelPropertySchema,
+        repository: detailPanelPropertySchema,
+        versions: detailPanelPropertySchema,
+        owners: detailPanelPropertySchema,
+        changelog: detailPanelPropertySchema,
+        attachments: detailPanelPropertySchema,
+      })
+      .optional(),
+  })
+  .merge(baseSchema);
diff --git a/packages/linter/src/schemas/entity.ts b/packages/linter/src/schemas/entity.ts
new file mode 100644
index 000000000..c26f4b3d1
--- /dev/null
+++ b/packages/linter/src/schemas/entity.ts
@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { baseSchema, detailPanelPropertySchema } from './common';
+
+const propertySchema = z.object({
+  name: z.string(),
+  type: z.string(),
+  required: z.boolean().optional(),
+  description: z.string().optional(),
+  references: z.string().optional(),
+  referencesIdentifier: z.string().optional(),
+  relationType: z.string().optional(),
+  enum: z.array(z.string()).optional(),
+  items: z
+    .object({
+      type: z.string(),
+    })
+    .optional(),
+});
+
+export const entitySchema = z
+  .object({
+    aggregateRoot: z.boolean().optional(),
+    identifier: z.string().optional(),
+    properties: z.array(propertySchema).optional(),
+    services: z.array(z.any()).optional(), // reference('services')
+    domains: z.array(z.any()).optional(), // reference('domains')
+    detailsPanel: z
+      .object({
+        domains: detailPanelPropertySchema,
+        services: detailPanelPropertySchema,
+        messages: detailPanelPropertySchema,
+        versions: detailPanelPropertySchema,
+        owners: detailPanelPropertySchema,
+        changelog: detailPanelPropertySchema,
+        attachments: detailPanelPropertySchema,
+      })
+      .optional(),
+  })
+  .merge(baseSchema);
diff --git a/packages/linter/src/schemas/flow.ts b/packages/linter/src/schemas/flow.ts
new file mode 100644
index 000000000..650635ea1
--- /dev/null
+++ b/packages/linter/src/schemas/flow.ts
@@ -0,0 +1,83 @@
+import { z } from 'zod';
+import { baseSchema, pointerSchema } from './common';
+
+const flowStep = z
+  .union([
+    z.union([z.string(), z.number()]),
+    z
+      .object({
+        id: z.union([z.string(), z.number()]),
+        label: z.string().optional(),
+      })
+      .optional(),
+  ])
+  .optional();
+
+const flowStepSchema = z
+  .object({
+    id: z.union([z.string(), z.number()]),
+    type: z.enum(['node', 'message', 'agent', 'user', 'actor']).optional(),
+    title: z.string(),
+    summary: z.string().optional(),
+    message: pointerSchema.optional(),
+    agent: pointerSchema.optional(),
+    service: pointerSchema.optional(),
+    flow: pointerSchema.optional(),
+    container: pointerSchema.optional(),
+    dataProduct: pointerSchema.optional(),
+    actor: z
+      .object({
+        name: z.string(),
+        summary: z.string().optional(),
+      })
+      .optional(),
+    custom: z
+      .object({
+        title: z.string(),
+        icon: z.string().optional(),
+        type: z.string().optional(),
+        summary: z.string().optional(),
+        url: z.string().url().optional(),
+        color: z.string().optional(),
+        properties: z.record(z.union([z.string(), z.number()])).optional(),
+        height: z.number().optional(),
+        menu: z
+          .array(
+            z.object({
+              label: z.string(),
+              url: z.string().url().optional(),
+            })
+          )
+          .optional(),
+      })
+      .optional(),
+    externalSystem: z
+      .object({
+        name: z.string(),
+        summary: z.string().optional(),
+        url: z.string().url().optional(),
+      })
+      .optional(),
+    next_step: flowStep,
+    next_steps: z.array(flowStep).optional(),
+  })
+  .refine((data) => {
+    if (data.next_step && data.next_steps) return false;
+    const typesUsed = [
+      data.message,
+      data.agent,
+      data.service,
+      data.flow,
+      data.container,
+      data.dataProduct,
+      data.actor,
+      data.custom,
+    ].filter((v) => v).length;
+    return typesUsed === 0 || typesUsed === 1;
+  });
+
+export const flowSchema = z
+  .object({
+    steps: z.array(flowStepSchema),
+  })
+  .merge(baseSchema);
diff --git a/packages/linter/src/schemas/index.ts b/packages/linter/src/schemas/index.ts
new file mode 100644
index 000000000..d07083922
--- /dev/null
+++ b/packages/linter/src/schemas/index.ts
@@ -0,0 +1,55 @@
+export * from './common';
+export * from './domain';
+export * from './system';
+export * from './service';
+export * from './message';
+export * from './channel';
+export * from './flow';
+export * from './entity';
+export * from './user';
+export * from './team';
+export * from './agent';
+export * from './adr';
+export * from './container';
+export * from './data-product';
+export * from './diagram';
+export * from './data-store';
+
+import { domainSchema } from './domain';
+import { systemSchema } from './system';
+import { serviceSchema } from './service';
+import { eventSchema, commandSchema, querySchema } from './message';
+import { channelSchema } from './channel';
+import { flowSchema } from './flow';
+import { entitySchema } from './entity';
+import { userSchema } from './user';
+import { teamSchema } from './team';
+import { agentSchema } from './agent';
+import { adrSchema } from './adr';
+import { containerSchema } from './container';
+import { dataProductSchema } from './data-product';
+import { diagramSchema } from './diagram';
+import { dataStoreSchema } from './data-store';
+
+export const schemas = {
+  domain: domainSchema,
+  system: systemSchema,
+  service: serviceSchema,
+  agent: agentSchema,
+  adr: adrSchema,
+  event: eventSchema,
+  command: commandSchema,
+  query: querySchema,
+  channel: channelSchema,
+  flow: flowSchema,
+  entity: entitySchema,
+  container: containerSchema,
+  dataProduct: dataProductSchema,
+  diagram: diagramSchema,
+  user: userSchema,
+  team: teamSchema,
+  // Backwards-compatible alias for older linter integrations.
+  dataStore: dataStoreSchema,
+} as const;
+
+export type ResourceType = keyof typeof schemas;
diff --git a/packages/linter/src/schemas/message.ts b/packages/linter/src/schemas/message.ts
new file mode 100644
index 000000000..ae6590ffc
--- /dev/null
+++ b/packages/linter/src/schemas/message.ts
@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { baseSchema, channelPointerSchema, detailPanelPropertySchema } from './common';
+
+const operationSchema = z
+  .object({
+    method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).optional(),
+    path: z.string().optional(),
+    statusCodes: z.array(z.string()).optional(),
+  })
+  .optional();
+
+const messageDetailsPanelSchema = z
+  .object({
+    producers: detailPanelPropertySchema,
+    consumers: detailPanelPropertySchema,
+    channels: detailPanelPropertySchema,
+    versions: detailPanelPropertySchema,
+    repository: detailPanelPropertySchema,
+    owners: detailPanelPropertySchema,
+    changelog: detailPanelPropertySchema,
+    attachments: detailPanelPropertySchema,
+  })
+  .optional();
+
+const baseMessageSchema = z
+  .object({
+    operation: operationSchema,
+    producers: z.array(z.any()).optional(), // reference('services')
+    consumers: z.array(z.any()).optional(), // reference('services')
+    channels: z.array(channelPointerSchema).optional(),
+    schemas: z
+      .array(
+        z.object({
+          id: z.string().optional(),
+          ref: z.string().optional(),
+          file: z.string().optional(),
+          path: z.string().optional(),
+          name: z.string().optional(),
+          format: z.string().optional(),
+          environments: z.array(z.string()).optional(),
+          default: z.boolean().optional(),
+        })
+      )
+      .optional(),
+    messageChannels: z.array(z.any()).optional(), // reference('channels')
+    detailsPanel: messageDetailsPanelSchema,
+  })
+  .merge(baseSchema);
+
+export const eventSchema = baseMessageSchema;
+export const commandSchema = baseMessageSchema;
+export const querySchema = baseMessageSchema;
diff --git a/packages/linter/src/schemas/service.ts b/packages/linter/src/schemas/service.ts
new file mode 100644
index 000000000..040219325
--- /dev/null
+++ b/packages/linter/src/schemas/service.ts
@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { baseSchema, pointerSchema, receivesPointerSchema, sendsPointerSchema, detailPanelPropertySchema } from './common';
+
+export const serviceSchema = z
+  .object({
+    sends: z.array(sendsPointerSchema).optional(),
+    receives: z.array(receivesPointerSchema).optional(),
+    entities: z.array(pointerSchema).optional(),
+    writesTo: z.array(pointerSchema).optional(),
+    readsFrom: z.array(pointerSchema).optional(),
+    flows: z.array(pointerSchema).optional(),
+    externalSystem: z.boolean().optional(),
+    detailsPanel: z
+      .object({
+        domains: detailPanelPropertySchema,
+        messages: detailPanelPropertySchema,
+        versions: detailPanelPropertySchema,
+        specifications: detailPanelPropertySchema,
+        entities: detailPanelPropertySchema,
+        repository: detailPanelPropertySchema,
+        owners: detailPanelPropertySchema,
+        changelog: detailPanelPropertySchema,
+        containers: detailPanelPropertySchema,
+      })
+      .optional(),
+  })
+  .merge(baseSchema);
diff --git a/packages/linter/src/schemas/system.ts b/packages/linter/src/schemas/system.ts
new file mode 100644
index 000000000..1d784495e
--- /dev/null
+++ b/packages/linter/src/schemas/system.ts
@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { baseSchema, detailPanelPropertySchema, pointerSchema } from './common';
+
+const systemRelationshipPointerSchema = z.object({
+  id: z.string(),
+  version: z.string().optional().default('latest'),
+  label: z.string().optional(),
+});
+
+const systemActorRelationshipSchema = z.object({
+  id: z.string(),
+  name: z.string().optional(),
+  label: z.string().optional(),
+  direction: z.enum(['inbound', 'outbound']).optional().default('inbound'),
+});
+
+export const systemSchema = z
+  .object({
+    scope: z.enum(['internal', 'external']).optional().default('internal'),
+    services: z.array(pointerSchema).optional(),
+    flows: z.array(pointerSchema).optional(),
+    entities: z.array(pointerSchema).optional(),
+    containers: z.array(pointerSchema).optional(),
+    relationships: z.array(systemRelationshipPointerSchema).optional(),
+    actors: z.array(systemActorRelationshipSchema).optional(),
+    detailsPanel: z
+      .object({
+        versions: detailPanelPropertySchema,
+        repository: detailPanelPropertySchema,
+        owners: detailPanelPropertySchema,
+        changelog: detailPanelPropertySchema,
+        attachments: detailPanelPropertySchema,
+        services: detailPanelPropertySchema,
+        flows: detailPanelPropertySchema,
+        entities: detailPanelPropertySchema,
+        containers: detailPanelPropertySchema,
+        diagrams: detailPanelPropertySchema,
+      })
+      .optional(),
+  })
+  .merge(baseSchema);
diff --git a/packages/linter/src/schemas/team.ts b/packages/linter/src/schemas/team.ts
new file mode 100644
index 000000000..7867e665f
--- /dev/null
+++ b/packages/linter/src/schemas/team.ts
@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+export const teamSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  summary: z.string().optional(),
+  email: z.string().email().optional(),
+  hidden: z.boolean().optional(),
+  source: z
+    .object({
+      provider: z.string(),
+      id: z.string().optional(),
+      url: z.string().optional(),
+    })
+    .optional(),
+  readOnly: z.boolean().optional(),
+  slackDirectMessageUrl: z.string().optional(),
+  msTeamsDirectMessageUrl: z.string().optional(),
+  members: z.array(z.any()).optional(), // reference('users')
+  ownedAgents: z.array(z.any()).optional(), // reference('agents')
+  ownedCommands: z.array(z.any()).optional(), // reference('commands')
+  ownedQueries: z.array(z.any()).optional(), // reference('queries')
+  ownedDomains: z.array(z.any()).optional(), // reference('domains')
+  ownedSystems: z.array(z.any()).optional(), // reference('systems')
+  ownedServices: z.array(z.any()).optional(), // reference('services')
+  ownedEvents: z.array(z.any()).optional(), // reference('events')
+});
diff --git a/packages/linter/src/schemas/user.ts b/packages/linter/src/schemas/user.ts
new file mode 100644
index 000000000..53348ab85
--- /dev/null
+++ b/packages/linter/src/schemas/user.ts
@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+export const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  avatarUrl: z.string().optional(),
+  role: z.string().optional(),
+  hidden: z.boolean().optional(),
+  source: z
+    .object({
+      provider: z.string(),
+      id: z.string().optional(),
+      url: z.string().optional(),
+    })
+    .optional(),
+  readOnly: z.boolean().optional(),
+  email: z.string().email().optional(),
+  slackDirectMessageUrl: z.string().optional(),
+  msTeamsDirectMessageUrl: z.string().optional(),
+  ownedAgents: z.array(z.any()).optional(), // reference('agents')
+  ownedDomains: z.array(z.any()).optional(), // reference('domains')
+  ownedSystems: z.array(z.any()).optional(), // reference('systems')
+  ownedServices: z.array(z.any()).optional(), // reference('services')
+  ownedEvents: z.array(z.any()).optional(), // reference('events')
+  ownedCommands: z.array(z.any()).optional(), // reference('commands')
+  ownedQueries: z.array(z.any()).optional(), // reference('queries')
+  associatedTeams: z.array(z.any()).optional(), // reference('teams')
+});
diff --git a/packages/linter/src/types/index.ts b/packages/linter/src/types/index.ts
new file mode 100644
index 000000000..c720f4034
--- /dev/null
+++ b/packages/linter/src/types/index.ts
@@ -0,0 +1,91 @@
+export interface Badge {
+  content: string;
+  backgroundColor: string;
+  textColor: string;
+  icon?: string;
+  url?: string;
+}
+
+export interface Specification {
+  type: 'asyncapi' | 'openapi';
+  path: string;
+  name?: string;
+}
+
+export interface Repository {
+  language: string;
+  url: string;
+}
+
+export interface DraftObject {
+  title: string;
+  message: string;
+}
+
+export interface DeprecatedObject {
+  date: string;
+  message?: string;
+}
+
+export interface ResourceReference {
+  id: string;
+  version?: string;
+}
+
+export interface Parameter {
+  enum?: string[];
+  description?: string;
+  examples?: string[];
+  default?: string;
+}
+
+export interface FlowStep {
+  id: string;
+  title: string;
+  summary?: string;
+  actor?: {
+    name: string;
+  };
+  message?: {
+    id: string;
+    version: string;
+  };
+  service?: {
+    id: string;
+    version: string;
+  };
+  externalSystem?: {
+    name: string;
+    summary?: string;
+    url?: string;
+  };
+  next_step?: string;
+  next_steps?: string[];
+}
+
+export interface EntityProperty {
+  name: string;
+  type: string;
+  required?: boolean;
+  description?: string;
+  references?: string;
+  referencesIdentifier?: string;
+  relationType?: 'one-to-one' | 'one-to-many';
+}
+
+export interface ValidationError {
+  type: 'schema' | 'reference';
+  resource: string;
+  field?: string;
+  message: string;
+  file: string;
+  line?: number;
+  severity?: 'error' | 'warning';
+  rule?: string;
+}
+
+export interface LinterOptions {
+  rootDir: string;
+  failOnWarning?: boolean;
+  verbose?: boolean;
+}
diff --git a/packages/linter/src/validators/best-practices-validator.ts b/packages/linter/src/validators/best-practices-validator.ts
new file mode 100644
index 000000000..1a7815840
--- /dev/null
+++ b/packages/linter/src/validators/best-practices-validator.ts
@@ -0,0 +1,71 @@
+import { ParsedFile } from '../parser';
+import { ValidationError } from '../types';
+
+export const validateBestPractices = (parsedFiles: ParsedFile[]): ValidationError[] => {
+  const errors: ValidationError[] = [];
+
+  for (const parsedFile of parsedFiles) {
+    const { file, frontmatter, content } = parsedFile;
+
+    // Check for required summary
+    if (!frontmatter.summary || (typeof frontmatter.summary === 'string' && frontmatter.summary.trim() === '')) {
+      errors.push({
+        type: 'schema',
+        resource: `${file.resourceType}/${file.resourceId}`,
+        field: 'summary',
+        message: 'Summary is required for better documentation',
+        file: file.relativePath,
+        severity: 'error',
+        rule: 'best-practices/summary-required',
+      });
+    }
+
+    // Check for required owners (skip users and teams - they are owners, not owned)
+    if (
+      file.resourceType !== 'user' &&
+      file.resourceType !== 'team' &&
+      (!frontmatter.owners || !Array.isArray(frontmatter.owners) || frontmatter.owners.length === 0)
+    ) {
+      errors.push({
+        type: 'schema',
+        resource: `${file.resourceType}/${file.resourceId}`,
+        field: 'owners',
+        message: 'At least one owner is required',
+        file: file.relativePath,
+        severity: 'error',
+        rule: 'best-practices/owner-required',
+      });
+    }
+
+    // Check for required description (markdown body content)
+    if (!content || content.trim() === '') {
+      errors.push({
+        type: 'schema',
+        resource: `${file.resourceType}/${file.resourceId}`,
+        field: 'description',
+        message: 'Resource should have a markdown description (body content) beyond just frontmatter',
+        file: file.relativePath,
+        severity: 'warning',
+        rule: 'best-practices/description-required',
+      });
+    }
+
+    // Check for required schemaPath on messages (events, commands, queries)
+    if (
+      (file.resourceType === 'event' || file.resourceType === 'command' || file.resourceType === 'query') &&
+      !frontmatter.schemaPath
+    ) {
+      errors.push({
+        type: 'schema',
+        resource: `${file.resourceType}/${file.resourceId}`,
+        field: 'schemaPath',
+        message: `${file.resourceType} should have a schemaPath defined for consumers to understand the contract`,
+        file: file.relativePath,
+        severity: 'warning',
+        rule: 'best-practices/schema-required',
+      });
+    }
+  }
+
+  return errors;
+};
diff --git a/packages/linter/src/validators/index.ts b/packages/linter/src/validators/index.ts
new file mode 100644
index 000000000..07f3e9524
--- /dev/null
+++ b/packages/linter/src/validators/index.ts
@@ -0,0 +1,33 @@
+export * from './schema-validator';
+export * from './reference-validator';
+export * from './best-practices-validator';
+
+import { ParsedFile } from '../parser';
+import { ValidationError } from '../types';
+import { CatalogDependencies } from '../config';
+import { validateAllSchemas } from './schema-validator';
+import {
+  validateReferences,
+  validateOrphanMessages,
+  validateDeprecatedReferences,
+  validateDuplicateResourceIds,
+} from './reference-validator';
+import { validateBestPractices } from './best-practices-validator';
+
+export const validateCatalog = (parsedFiles: ParsedFile[], dependencies?: CatalogDependencies): ValidationError[] => {
+  const schemaErrors = validateAllSchemas(parsedFiles);
+  const referenceErrors = validateReferences(parsedFiles, dependencies);
+  const orphanErrors = validateOrphanMessages(parsedFiles, dependencies);
+  const deprecatedRefErrors = validateDeprecatedReferences(parsedFiles);
+  const duplicateErrors = validateDuplicateResourceIds(parsedFiles);
+  const bestPracticeErrors = validateBestPractices(parsedFiles);
+
+  return [
+    ...schemaErrors,
+    ...referenceErrors,
+    ...orphanErrors,
+    ...deprecatedRefErrors,
+    ...duplicateErrors,
+    ...bestPracticeErrors,
+  ];
+};
diff --git a/packages/linter/src/validators/reference-validator.ts b/packages/linter/src/validators/reference-validator.ts
new file mode 100644
index 000000000..20a874e3f
--- /dev/null
+++ b/packages/linter/src/validators/reference-validator.ts
@@ -0,0 +1,697 @@
+import { ParsedFile } from '../parser';
+import { ValidationError, ResourceReference } from '../types';
+import { ResourceType } from '../schemas';
+import { CatalogDependencies } from '../config';
+import semver from 'semver';
+
+interface ResourceIndex {
+  [resourceType: string]: {
+    [resourceId: string]: Set<string>;
+  };
+}
+
+const MESSAGE_TYPES: ResourceType[] = ['event', 'command', 'query'];
+
+const RESOURCE_TYPE_ALIASES: Partial<Record<ResourceType, ResourceType[]>> = {
+  container: ['container', 'dataStore'],
+  dataStore: ['container', 'dataStore'],
+};
+
+const normalizeResourceType = (type: unknown): ResourceType | undefined => {
+  if (typeof type !== 'string') return undefined;
+
+  const normalizedTypes: Record<string, ResourceType> = {
+    agent: 'agent',
+    agents: 'agent',
+    adr: 'adr',
+    adrs: 'adr',
+    service: 'service',
+    services: 'service',
+    event: 'event',
+    events: 'event',
+    command: 'command',
+    commands: 'command',
+    query: 'query',
+    queries: 'query',
+    flow: 'flow',
+    flows: 'flow',
+    channel: 'channel',
+    channels: 'channel',
+    domain: 'domain',
+    domains: 'domain',
+    system: 'system',
+    systems: 'system',
+    user: 'user',
+    users: 'user',
+    team: 'team',
+    teams: 'team',
+    container: 'container',
+    containers: 'container',
+    dataStore: 'container',
+    dataStores: 'container',
+    'data-product': 'dataProduct',
+    'data-products': 'dataProduct',
+    dataProduct: 'dataProduct',
+    dataProducts: 'dataProduct',
+    entity: 'entity',
+    entities: 'entity',
+    diagram: 'diagram',
+    diagrams: 'diagram',
+  };
+
+  return normalizedTypes[type];
+};
+
+const getReference = (value: unknown): ResourceReference | undefined => {
+  if (typeof value === 'string') {
+    return { id: value };
+  }
+
+  if (!value || typeof value !== 'object') {
+    return undefined;
+  }
+
+  const ref = value as Record<string, unknown>;
+  if (typeof ref.id !== 'string') {
+    return undefined;
+  }
+
+  return {
+    id: ref.id,
+    version: typeof ref.version === 'string' ? ref.version : undefined,
+  };
+};
+
+const addReference = (references: ReferenceInfo[], value: unknown, possibleTypes: ResourceType[], field: string): void => {
+  const ref = getReference(value);
+  if (ref) {
+    references.push({ ref, possibleTypes, field });
+  }
+};
+
+const addReferences = (references: ReferenceInfo[], values: unknown, possibleTypes: ResourceType[], field: string): void => {
+  if (!Array.isArray(values)) return;
+  values.forEach((value) => {
+    addReference(references, value, possibleTypes, field);
+  });
+};
+
+const addTypedReference = (references: ReferenceInfo[], value: unknown, field: string): void => {
+  if (!value || typeof value !== 'object') return;
+  const resourceType = normalizeResourceType((value as Record<string, unknown>).type);
+  if (!resourceType) return;
+  addReference(references, value, [resourceType], field);
+};
+
+export const buildResourceIndex = (parsedFiles: ParsedFile[], dependencies?: CatalogDependencies): ResourceIndex => {
+  const index: ResourceIndex = {};
+
+  for (const parsedFile of parsedFiles) {
+    const { file, frontmatter } = parsedFile;
+    const { resourceType } = file;
+
+    // Use the frontmatter id field if present, otherwise fall back to filename/directory
+    // This handles cases where:
+    // - Filename is "aSmith.mdx" but frontmatter has id: "asmith"
+    // - Directory is "e-commerce" but frontmatter has id: "E-Commerce"
+    // - Directory is "UserService" but frontmatter has id: "user-service" (SentenceCase vs kebab-case)
+    let resourceId = file.resourceId;
+    if (frontmatter.id && typeof frontmatter.id === 'string') {
+      resourceId = frontmatter.id;
+    }
+
+    if (!index[resourceType]) {
+      index[resourceType] = {};
+    }
+
+    if (!index[resourceType][resourceId]) {
+      index[resourceType][resourceId] = new Set();
+    }
+
+    if (frontmatter.version && typeof frontmatter.version === 'string') {
+      index[resourceType][resourceId].add(frontmatter.version);
+    } else {
+      index[resourceType][resourceId].add('latest');
+    }
+  }
+
+  // Add dependency entries to the index
+  if (dependencies) {
+    for (const [resourceType, entries] of Object.entries(dependencies)) {
+      if (!index[resourceType]) {
+        index[resourceType] = {};
+      }
+      for (const entry of entries) {
+        if (!index[resourceType][entry.id]) {
+          index[resourceType][entry.id] = new Set();
+        }
+        index[resourceType][entry.id].add(entry.version || 'latest');
+      }
+    }
+  }
+
+  return index;
+};
+
+const checkResourceExists = (ref: ResourceReference, resourceType: ResourceType, index: ResourceIndex): boolean => {
+  const resourceTypes = RESOURCE_TYPE_ALIASES[resourceType] || [resourceType];
+  const resourceVersions = new Set<string>();
+
+  for (const type of resourceTypes) {
+    const versions = index[type]?.[ref.id];
+    if (versions) {
+      versions.forEach((version) => resourceVersions.add(version));
+    }
+  }
+
+  if (!resourceVersions || resourceVersions.size === 0) {
+    return false;
+  }
+
+  if (!ref.version) {
+    return true;
+  }
+
+  const refVersion = ref.version === 'latest' ? ref.version : ref.version;
+  const availableVersions = Array.from(resourceVersions);
+
+  // Handle 'latest' specifically
+  if (refVersion === 'latest') {
+    return availableVersions.includes('latest') || availableVersions.length > 0;
+  }
+
+  // Check for exact match first
+  if (availableVersions.includes(refVersion)) {
+    return true;
+  }
+
+  // Handle semver patterns like '0.0.x', '^1.0.0', '~1.2.0', etc.
+  try {
+    // Filter out 'latest' from available versions for semver matching
+    const semverVersions = availableVersions.filter((v) => v !== 'latest' && semver.valid(v));
+
+    // Check if any available version satisfies the requested version pattern
+    for (const availableVersion of semverVersions) {
+      if (semver.satisfies(availableVersion, refVersion)) {
+        return true;
+      }
+    }
+
+    // Special handling for patterns like '0.0.x' which aren't standard semver ranges
+    if (refVersion.includes('.x')) {
+      const pattern = refVersion.replace(/\.x/g, '');
+      for (const availableVersion of semverVersions) {
+        if (availableVersion.startsWith(pattern)) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  } catch (error) {
+    // If semver parsing fails, fall back to exact string match
+    return availableVersions.includes(refVersion);
+  }
+};
+
+interface ReferenceInfo {
+  ref: ResourceReference;
+  possibleTypes: ResourceType[];
+  field: string;
+}
+
+const extractReferences = (parsedFile: ParsedFile): ReferenceInfo[] => {
+  const { file, frontmatter } = parsedFile;
+  const references: ReferenceInfo[] = [];
+
+  if (frontmatter.owners && Array.isArray(frontmatter.owners)) {
+    frontmatter.owners.forEach((owner: unknown, index: number) => {
+      if (owner && typeof owner === 'object' && 'collection' in owner) {
+        const ownerType = normalizeResourceType((owner as Record<string, unknown>).collection);
+        if (ownerType) {
+          addReference(references, owner, [ownerType], `owners[${index}]`);
+          return;
+        }
+      }
+      addReference(references, owner, ['user', 'team'], `owners[${index}]`);
+    });
+  }
+
+  addReferences(references, frontmatter.diagrams, ['diagram'], 'diagrams');
+
+  if (frontmatter.resourceGroups && Array.isArray(frontmatter.resourceGroups)) {
+    frontmatter.resourceGroups.forEach((group: unknown, groupIndex: number) => {
+      if (!group || typeof group !== 'object') return;
+      const items = (group as Record<string, unknown>).items;
+      if (!Array.isArray(items)) return;
+      items.forEach((item, itemIndex) =>
+        addTypedReference(references, item, `resourceGroups[${groupIndex}].items[${itemIndex}]`)
+      );
+    });
+  }
+
+  if (file.resourceType === 'domain') {
+    addReferences(references, frontmatter.services, ['service'], 'services');
+    addReferences(references, frontmatter.agents, ['agent'], 'agents');
+    addReferences(references, frontmatter.domains, ['domain'], 'domains');
+    addReferences(references, frontmatter.systems, ['system'], 'systems');
+    addReferences(references, frontmatter.entities, ['entity'], 'entities');
+    addReferences(references, frontmatter['data-products'], ['dataProduct'], 'data-products');
+    addReferences(references, frontmatter.dataProducts, ['dataProduct'], 'dataProducts');
+    addReferences(references, frontmatter.flows, ['flow'], 'flows');
+    addReferences(references, frontmatter.sends, MESSAGE_TYPES, 'sends');
+    addReferences(references, frontmatter.receives, MESSAGE_TYPES, 'receives');
+  }
+
+  if (file.resourceType === 'service' || file.resourceType === 'agent') {
+    addReferences(references, frontmatter.sends, MESSAGE_TYPES, 'sends');
+    addReferences(references, frontmatter.receives, MESSAGE_TYPES, 'receives');
+    if (frontmatter.writesTo && Array.isArray(frontmatter.writesTo)) {
+      frontmatter.writesTo.forEach((ref: unknown) => addReference(references, ref, ['container'], 'writesTo'));
+    }
+    if (frontmatter.readsFrom && Array.isArray(frontmatter.readsFrom)) {
+      frontmatter.readsFrom.forEach((ref: unknown) => addReference(references, ref, ['container'], 'readsFrom'));
+    }
+    addReferences(references, frontmatter.flows, ['flow'], 'flows');
+  }
+
+  if (file.resourceType === 'service') {
+    addReferences(references, frontmatter.entities, ['entity'], 'entities');
+  }
+
+  if (file.resourceType === 'system') {
+    addReferences(references, frontmatter.services, ['service'], 'services');
+    addReferences(references, frontmatter.flows, ['flow'], 'flows');
+    addReferences(references, frontmatter.entities, ['entity'], 'entities');
+    addReferences(references, frontmatter.containers, ['container'], 'containers');
+    addReferences(references, frontmatter.relationships, ['system'], 'relationships');
+  }
+
+  if (file.resourceType === 'flow' && frontmatter.steps && Array.isArray(frontmatter.steps)) {
+    frontmatter.steps.forEach((step: Record<string, unknown>, index: number) => {
+      if (step.message) {
+        addReference(references, step.message, MESSAGE_TYPES, `steps[${index}].message`);
+      }
+      if (step.service) {
+        addReference(references, step.service, ['service'], `steps[${index}].service`);
+      }
+      if (step.agent) {
+        addReference(references, step.agent, ['agent'], `steps[${index}].agent`);
+      }
+      if (step.flow) {
+        addReference(references, step.flow, ['flow'], `steps[${index}].flow`);
+      }
+      if (step.container) {
+        addReference(references, step.container, ['container'], `steps[${index}].container`);
+      }
+      if (step.dataProduct) {
+        addReference(references, step.dataProduct, ['dataProduct'], `steps[${index}].dataProduct`);
+      }
+    });
+  }
+
+  if (file.resourceType === 'entity' && frontmatter.properties && Array.isArray(frontmatter.properties)) {
+    frontmatter.properties.forEach((prop: Record<string, unknown>, index: number) => {
+      if (prop.references) {
+        references.push({
+          ref: { id: prop.references as string },
+          possibleTypes: ['entity'],
+          field: `properties[${index}].references`,
+        });
+      }
+    });
+    addReferences(references, frontmatter.services, ['service'], 'services');
+    addReferences(references, frontmatter.domains, ['domain'], 'domains');
+  }
+
+  if (MESSAGE_TYPES.includes(file.resourceType)) {
+    addReferences(references, frontmatter.producers, ['service'], 'producers');
+    addReferences(references, frontmatter.consumers, ['service'], 'consumers');
+    addReferences(references, frontmatter.channels, ['channel'], 'channels');
+    addReferences(references, frontmatter.messageChannels, ['channel'], 'messageChannels');
+  }
+
+  if (file.resourceType === 'channel') {
+    addReferences(references, frontmatter.channels, ['channel'], 'channels');
+    addReferences(references, frontmatter.routes, ['channel'], 'routes');
+    if (frontmatter.messages && Array.isArray(frontmatter.messages)) {
+      frontmatter.messages.forEach((message: unknown, index: number) => {
+        if (!message || typeof message !== 'object') return;
+        const messageType = normalizeResourceType((message as Record<string, unknown>).collection);
+        if (messageType && MESSAGE_TYPES.includes(messageType)) {
+          addReference(references, message, [messageType], `messages[${index}]`);
+        }
+      });
+    }
+  }
+
+  if (file.resourceType === 'container' || file.resourceType === 'dataStore') {
+    addReferences(references, frontmatter.services, ['service'], 'services');
+    addReferences(references, frontmatter.servicesThatWriteToContainer, ['service'], 'servicesThatWriteToContainer');
+    addReferences(references, frontmatter.servicesThatReadFromContainer, ['service'], 'servicesThatReadFromContainer');
+    addReferences(references, frontmatter.dataProductsThatWriteToContainer, ['dataProduct'], 'dataProductsThatWriteToContainer');
+    addReferences(
+      references,
+      frontmatter.dataProductsThatReadFromContainer,
+      ['dataProduct'],
+      'dataProductsThatReadFromContainer'
+    );
+  }
+
+  if (file.resourceType === 'dataProduct') {
+    const dataProductLinkTypes: ResourceType[] = [
+      'event',
+      'command',
+      'query',
+      'service',
+      'agent',
+      'system',
+      'container',
+      'channel',
+      'dataProduct',
+    ];
+    addReferences(references, frontmatter.inputs, dataProductLinkTypes, 'inputs');
+    addReferences(references, frontmatter.outputs, dataProductLinkTypes, 'outputs');
+  }
+
+  if (file.resourceType === 'adr') {
+    if (frontmatter.decisionMakers && Array.isArray(frontmatter.decisionMakers)) {
+      frontmatter.decisionMakers.forEach((owner: unknown, index: number) => {
+        addReference(references, owner, ['user', 'team'], `decisionMakers[${index}]`);
+      });
+    }
+    if (frontmatter.appliesTo && Array.isArray(frontmatter.appliesTo)) {
+      frontmatter.appliesTo.forEach((target: unknown, index: number) => {
+        addTypedReference(references, target, `appliesTo[${index}]`);
+      });
+    }
+    addReferences(references, frontmatter.supersedes, ['adr'], 'supersedes');
+    addReferences(references, frontmatter.supersededBy, ['adr'], 'supersededBy');
+    addReferences(references, frontmatter.amends, ['adr'], 'amends');
+    addReferences(references, frontmatter.amendedBy, ['adr'], 'amendedBy');
+    addReferences(references, frontmatter.related, ['adr'], 'related');
+  }
+
+  if (file.resourceType === 'team' && frontmatter.members && Array.isArray(frontmatter.members)) {
+    frontmatter.members.forEach((member: unknown, index: number) => {
+      addReference(references, member, ['user'], `members[${index}]`);
+    });
+  }
+
+  if (file.resourceType === 'user' || file.resourceType === 'team') {
+    addReferences(references, frontmatter.ownedAgents, ['agent'], 'ownedAgents');
+    addReferences(references, frontmatter.ownedDomains, ['domain'], 'ownedDomains');
+    addReferences(references, frontmatter.ownedSystems, ['system'], 'ownedSystems');
+    addReferences(references, frontmatter.ownedServices, ['service'], 'ownedServices');
+    addReferences(references, frontmatter.ownedEvents, ['event'], 'ownedEvents');
+    addReferences(references, frontmatter.ownedCommands, ['command'], 'ownedCommands');
+    addReferences(references, frontmatter.ownedQueries, ['query'], 'ownedQueries');
+  }
+
+  if (file.resourceType === 'user') {
+    addReferences(references, frontmatter.associatedTeams, ['team'], 'associatedTeams');
+  }
+
+  return references;
+};
+
+// Extract channel references from sends/receives to/from arrays
+const extractChannelReferences = (parsedFile: ParsedFile): ReferenceInfo[] => {
+  const { file, frontmatter } = parsedFile;
+  const references: ReferenceInfo[] = [];
+
+  if (file.resourceType !== 'service' && file.resourceType !== 'domain' && file.resourceType !== 'agent') {
+    return references;
+  }
+
+  const extractFromPointers = (pointers: any[], parentField: string) => {
+    if (!Array.isArray(pointers)) return;
+    pointers.forEach((pointer: any, idx: number) => {
+      if (pointer.to && Array.isArray(pointer.to)) {
+        pointer.to.forEach((channelRef: any, cIdx: number) => {
+          if (channelRef && channelRef.id) {
+            references.push({
+              ref: { id: channelRef.id, version: channelRef.version },
+              possibleTypes: ['channel'],
+              field: `${parentField}[${idx}].to[${cIdx}]`,
+            });
+          }
+        });
+      }
+      if (pointer.from && Array.isArray(pointer.from)) {
+        pointer.from.forEach((channelRef: any, cIdx: number) => {
+          if (channelRef && channelRef.id) {
+            references.push({
+              ref: { id: channelRef.id, version: channelRef.version },
+              possibleTypes: ['channel'],
+              field: `${parentField}[${idx}].from[${cIdx}]`,
+            });
+          }
+        });
+      }
+    });
+  };
+
+  if (frontmatter.sends && Array.isArray(frontmatter.sends)) {
+    extractFromPointers(frontmatter.sends, 'sends');
+  }
+  if (frontmatter.receives && Array.isArray(frontmatter.receives)) {
+    extractFromPointers(frontmatter.receives, 'receives');
+  }
+
+  return references;
+};
+
+export const validateReferences = (parsedFiles: ParsedFile[], dependencies?: CatalogDependencies): ValidationError[] => {
+  const index = buildResourceIndex(parsedFiles, dependencies);
+  const errors: ValidationError[] = [];
+
+  for (const parsedFile of parsedFiles) {
+    const references = extractReferences(parsedFile);
+
+    for (const { ref, possibleTypes, field } of references) {
+      const found = possibleTypes.some((type) => checkResourceExists(ref, type, index));
+
+      if (!found) {
+        const versionStr = ref.version ? ` (version: ${ref.version})` : '';
+        const typeStr = possibleTypes.length === 1 ? possibleTypes[0] : possibleTypes.join('/');
+
+        let rule = 'refs/resource-exists';
+        if (field === 'owners' || field.startsWith('owners[') || field.startsWith('decisionMakers[')) {
+          rule = 'refs/owner-exists';
+        } else if (field === 'writesTo' || field === 'readsFrom' || field.includes('container') || field.includes('Container')) {
+          rule = 'refs/container-exists';
+        } else if (
+          field.includes('channel') ||
+          field.includes('Channel') ||
+          field.includes('.to[') ||
+          field.includes('.from[') ||
+          field === 'routes' ||
+          field.startsWith('routes[')
+        ) {
+          rule = 'refs/channel-exists';
+        } else if (ref.version) {
+          rule = 'refs/valid-version-range';
+        }
+
+        errors.push({
+          type: 'reference',
+          resource: `${parsedFile.file.resourceType}/${parsedFile.file.resourceId}`,
+          field,
+          message: `Referenced ${typeStr} "${ref.id}"${versionStr} does not exist`,
+          file: parsedFile.file.relativePath,
+          rule,
+        });
+      }
+    }
+
+    // Validate channel references from sends/receives to/from
+    const channelRefs = extractChannelReferences(parsedFile);
+    for (const { ref, possibleTypes, field } of channelRefs) {
+      const found = possibleTypes.some((type) => checkResourceExists(ref, type, index));
+
+      if (!found) {
+        const versionStr = ref.version ? ` (version: ${ref.version})` : '';
+        errors.push({
+          type: 'reference',
+          resource: `${parsedFile.file.resourceType}/${parsedFile.file.resourceId}`,
+          field,
+          message: `Referenced channel "${ref.id}"${versionStr} does not exist`,
+          file: parsedFile.file.relativePath,
+          rule: 'refs/channel-exists',
+        });
+      }
+    }
+  }
+
+  return errors;
+};
+
+// Detect messages (events/commands/queries) with no producer and no consumer
+export const validateOrphanMessages = (parsedFiles: ParsedFile[], dependencies?: CatalogDependencies): ValidationError[] => {
+  const errors: ValidationError[] = [];
+  const messageTypes: ResourceType[] = ['event', 'command', 'query'];
+
+  // Collect all message IDs
+  const messageFiles = parsedFiles.filter((pf) => messageTypes.includes(pf.file.resourceType));
+
+  if (messageFiles.length === 0) return errors;
+
+  // Build sets of produced and consumed message IDs
+  const producedMessages = new Set<string>();
+  const consumedMessages = new Set<string>();
+
+  for (const parsedFile of parsedFiles) {
+    const { file, frontmatter } = parsedFile;
+
+    if (file.resourceType === 'service' || file.resourceType === 'domain' || file.resourceType === 'agent') {
+      if (frontmatter.sends && Array.isArray(frontmatter.sends)) {
+        frontmatter.sends.forEach((ref: any) => {
+          if (ref && ref.id) producedMessages.add(ref.id);
+        });
+      }
+      if (frontmatter.receives && Array.isArray(frontmatter.receives)) {
+        frontmatter.receives.forEach((ref: any) => {
+          if (ref && ref.id) consumedMessages.add(ref.id);
+        });
+      }
+    }
+
+    // Also check producers/consumers fields on messages themselves
+    if (messageTypes.includes(file.resourceType)) {
+      if (frontmatter.producers && Array.isArray(frontmatter.producers) && frontmatter.producers.length > 0) {
+        const msgId = (frontmatter.id as string) || file.resourceId;
+        producedMessages.add(msgId);
+      }
+      if (frontmatter.consumers && Array.isArray(frontmatter.consumers) && frontmatter.consumers.length > 0) {
+        const msgId = (frontmatter.id as string) || file.resourceId;
+        consumedMessages.add(msgId);
+      }
+    }
+  }
+
+  // Also consider dependency messages as having producers/consumers
+  if (dependencies) {
+    for (const [type, entries] of Object.entries(dependencies)) {
+      if (messageTypes.includes(type as ResourceType)) {
+        entries.forEach((entry) => {
+          // Dependencies are external, treat them as having both producers and consumers
+          producedMessages.add(entry.id);
+          consumedMessages.add(entry.id);
+        });
+      }
+    }
+  }
+
+  // Check each message for orphan status
+  for (const parsedFile of messageFiles) {
+    const msgId = (parsedFile.frontmatter.id as string) || parsedFile.file.resourceId;
+    const isProduced = producedMessages.has(msgId);
+    const isConsumed = consumedMessages.has(msgId);
+
+    if (!isProduced && !isConsumed) {
+      errors.push({
+        type: 'reference',
+        resource: `${parsedFile.file.resourceType}/${parsedFile.file.resourceId}`,
+        field: 'id',
+        message: `${parsedFile.file.resourceType} "${msgId}" has no producer and no consumer`,
+        file: parsedFile.file.relativePath,
+        rule: 'refs/orphan-messages',
+      });
+    }
+  }
+
+  return errors;
+};
+
+// Detect references to deprecated resources
+export const validateDeprecatedReferences = (parsedFiles: ParsedFile[]): ValidationError[] => {
+  const errors: ValidationError[] = [];
+
+  // Build an index of deprecated resources
+  const deprecatedIndex: Record<string, Set<string>> = {};
+  for (const parsedFile of parsedFiles) {
+    const { file, frontmatter } = parsedFile;
+    if (frontmatter.deprecated && frontmatter.deprecated !== false) {
+      const resourceId = (frontmatter.id as string) || file.resourceId;
+      const key = `${file.resourceType}:${resourceId}`;
+      if (!deprecatedIndex[key]) {
+        deprecatedIndex[key] = new Set();
+      }
+      if (frontmatter.version && typeof frontmatter.version === 'string') {
+        deprecatedIndex[key].add(frontmatter.version);
+      } else {
+        deprecatedIndex[key].add('*'); // All versions deprecated
+      }
+    }
+  }
+
+  if (Object.keys(deprecatedIndex).length === 0) return errors;
+
+  const isDeprecated = (type: string, id: string, version?: string): boolean => {
+    const key = `${type}:${id}`;
+    const versions = deprecatedIndex[key];
+    if (!versions) return false;
+    if (versions.has('*')) return true;
+    if (version && versions.has(version)) return true;
+    // For 'latest' or no version, check if any version is deprecated
+    if (!version || version === 'latest') return versions.size > 0;
+    return false;
+  };
+
+  for (const parsedFile of parsedFiles) {
+    const references = extractReferences(parsedFile);
+
+    for (const { ref, possibleTypes, field } of references) {
+      // Skip owner references for this check
+      if (field === 'owners' || field.startsWith('owners[') || field === 'members' || field.startsWith('members[')) continue;
+
+      for (const type of possibleTypes) {
+        if (isDeprecated(type, ref.id, ref.version)) {
+          const versionStr = ref.version ? ` (version: ${ref.version})` : '';
+          errors.push({
+            type: 'reference',
+            resource: `${parsedFile.file.resourceType}/${parsedFile.file.resourceId}`,
+            field,
+            message: `Referenced ${type} "${ref.id}"${versionStr} is deprecated`,
+            file: parsedFile.file.relativePath,
+            rule: 'versions/no-deprecated-references',
+          });
+          break; // Only report once per reference
+        }
+      }
+    }
+  }
+
+  return errors;
+};
+
+// Detect duplicate resource IDs (same type, same id, same version)
+export const validateDuplicateResourceIds = (parsedFiles: ParsedFile[]): ValidationError[] => {
+  const errors: ValidationError[] = [];
+
+  // Track seen resources: key = "type:id:version", value = file path
+  const seen: Record<string, string> = {};
+
+  for (const parsedFile of parsedFiles) {
+    const { file, frontmatter } = parsedFile;
+    const resourceId = (frontmatter.id as string) || file.resourceId;
+    const version = (frontmatter.version as string) || 'latest';
+    const key = `${file.resourceType}:${resourceId}:${version}`;
+
+    if (seen[key]) {
+      errors.push({
+        type: 'reference',
+        resource: `${file.resourceType}/${file.resourceId}`,
+        field: 'id',
+        message: `Duplicate ${file.resourceType} "${resourceId}" (version: ${version}) — also defined in ${seen[key]}`,
+        file: file.relativePath,
+        rule: 'structure/duplicate-resource-ids',
+      });
+    } else {
+      seen[key] = file.relativePath;
+    }
+  }
+
+  return errors;
+};
diff --git a/packages/linter/src/validators/schema-validator.ts b/packages/linter/src/validators/schema-validator.ts
new file mode 100644
index 000000000..7f1004206
--- /dev/null
+++ b/packages/linter/src/validators/schema-validator.ts
@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { schemas } from '../schemas';
+import { ParsedFile } from '../parser';
+import { ValidationError } from '../types';
+
+export const validateSchema = (parsedFile: ParsedFile): ValidationError[] => {
+  const { file, frontmatter } = parsedFile;
+  const schema = schemas[file.resourceType];
+  const errors: ValidationError[] = [];
+
+  try {
+    schema.parse(frontmatter);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      for (const issue of error.issues) {
+        const field = issue.path.join('.');
+        let message = issue.message;
+
+        if (issue.code === 'invalid_type') {
+          message = `Expected ${issue.expected}, but received ${issue.received}`;
+        }
+
+        let rule = 'schema/required-fields';
+        if (issue.code === 'invalid_type') {
+          rule = 'schema/valid-type';
+        } else if (issue.code === 'invalid_string' && issue.validation === 'email') {
+          rule = 'schema/valid-email';
+        } else if (field && field.includes('version')) {
+          rule = 'schema/valid-semver';
+        }
+
+        errors.push({
+          type: 'schema',
+          resource: `${file.resourceType}/${file.resourceId}`,
+          field: field || undefined,
+          message: field ? `${field}: ${message}` : message,
+          file: file.relativePath,
+          rule,
+        });
+      }
+    } else {
+      errors.push({
+        type: 'schema',
+        resource: `${file.resourceType}/${file.resourceId}`,
+        message: error instanceof Error ? error.message : String(error),
+        file: file.relativePath,
+        rule: 'schema/validation-error',
+      });
+    }
+  }
+
+  return errors;
+};
+
+export const validateAllSchemas = (parsedFiles: ParsedFile[]): ValidationError[] => {
+  const errors: ValidationError[] = [];
+
+  for (const parsedFile of parsedFiles) {
+    errors.push(...validateSchema(parsedFile));
+  }
+
+  return errors;
+};
diff --git a/packages/linter/tests/cli-integration.test.ts b/packages/linter/tests/cli-integration.test.ts
new file mode 100644
index 000000000..68ec05e70
--- /dev/null
+++ b/packages/linter/tests/cli-integration.test.ts
@@ -0,0 +1,348 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+describe('CLI Integration with Configuration', () => {
+  let tempDir: string;
+  let servicesDir: string;
+  let eventsDir: string;
+  let usersDir: string;
+  let configPath: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'eventcatalog-cli-test-'));
+    servicesDir = path.join(tempDir, 'services');
+    eventsDir = path.join(tempDir, 'events');
+    usersDir = path.join(tempDir, 'users');
+    configPath = path.join(tempDir, '.eventcatalogrc.js');
+
+    fs.mkdirSync(servicesDir, { recursive: true });
+    fs.mkdirSync(eventsDir, { recursive: true });
+    fs.mkdirSync(usersDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  const createServiceFile = (name: string, content: string) => {
+    const serviceDir = path.join(servicesDir, name);
+    fs.mkdirSync(serviceDir, { recursive: true });
+    fs.writeFileSync(path.join(serviceDir, 'index.mdx'), content);
+  };
+
+  const createEventFile = (name: string, content: string) => {
+    const eventDir = path.join(eventsDir, name);
+    fs.mkdirSync(eventDir, { recursive: true });
+    fs.writeFileSync(path.join(eventDir, 'index.mdx'), content);
+  };
+
+  const createUserFile = (name: string, content: string) => {
+    fs.writeFileSync(path.join(usersDir, `${name}.mdx`), content);
+  };
+
+  const runLinter = async (args: string = '') => {
+    const cliPath = path.join(__dirname, '../dist/cli/index.js');
+    try {
+      const result = await execAsync(`node ${cliPath} ${tempDir} ${args}`);
+      return { success: true, stdout: result.stdout, stderr: result.stderr };
+    } catch (error: any) {
+      return { success: false, stdout: error.stdout, stderr: error.stderr };
+    }
+  };
+
+  it('should use default rules when no config file exists', async () => {
+    // Create a service with missing required fields
+    createServiceFile(
+      'user-service',
+      `---
+id: user-service
+name: User Service
+version: 1.0.0
+---
+# User Service
+`
+    );
+
+    const result = await runLinter();
+
+    expect(result.success).toBe(false);
+    expect(result.stdout).toContain('error');
+    expect(result.stdout).toContain('summary');
+  });
+
+  it('should apply rule configuration from .eventcatalogrc.js', async () => {
+    // Create config that turns summary requirement to warning
+    const configContent = `
+module.exports = {
+  rules: {
+    'best-practices/summary-required': 'warn',
+    'best-practices/owner-required': 'off',
+  }
+};
+`;
+    fs.writeFileSync(configPath, configContent);
+
+    // Create a service with missing summary and owners
+    createServiceFile(
+      'user-service',
+      `---
+id: user-service
+name: User Service
+version: 1.0.0
+---
+# User Service
+`
+    );
+
+    const result = await runLinter();
+
+    expect(result.success).toBe(true); // Should pass because we only have warnings
+    expect(result.stdout).toContain('warning');
+    expect(result.stdout).toContain('summary');
+    expect(result.stdout).not.toContain('owner'); // Should be off
+  });
+
+  it('should ignore files matching ignorePatterns', async () => {
+    // Create config with ignore patterns
+    const configContent = `
+module.exports = {
+  ignorePatterns: ['**/archived/**', '**/drafts/**']
+};
+`;
+    fs.writeFileSync(configPath, configContent);
+
+    // Create services in different directories
+    createServiceFile(
+      'user-service',
+      `---
+id: user-service
+name: User Service
+version: 1.0.0
+---
+# User Service
+`
+    );
+
+    const archivedDir = path.join(servicesDir, 'archived');
+    fs.mkdirSync(archivedDir, { recursive: true });
+    createServiceFile(
+      'archived/old-service',
+      `---
+id: old-service
+name: Old Service
+version: 1.0.0
+---
+# Old Service
+`
+    );
+
+    const result = await runLinter();
+
+    expect(result.success).toBe(false);
+    expect(result.stdout).toContain('1 file checked'); // Should only check user-service
+    expect(result.stdout).not.toContain('archived'); // Should not see archived service in output
+  });
+
+  it('should apply overrides for specific file patterns', async () => {
+    // Create config with overrides
+    const configContent = `
+module.exports = {
+  rules: {
+    'best-practices/summary-required': 'error',
+    'best-practices/owner-required': 'error',
+  },
+  overrides: [
+    {
+      files: ['**/experimental/**'],
+      rules: {
+        'best-practices/summary-required': 'warn',
+        'best-practices/owner-required': 'off',
+      }
+    }
+  ]
+};
+`;
+    fs.writeFileSync(configPath, configContent);
+
+    // Create regular service
+    createServiceFile(
+      'user-service',
+      `---
+id: user-service
+name: User Service
+version: 1.0.0
+---
+# User Service
+`
+    );
+
+    // Create experimental service
+    const experimentalDir = path.join(servicesDir, 'experimental');
+    fs.mkdirSync(experimentalDir, { recursive: true });
+    createServiceFile(
+      'experimental/new-service',
+      `---
+id: new-service
+name: New Service
+version: 1.0.0
+---
+# New Service
+`
+    );
+
+    const result = await runLinter();
+
+    expect(result.success).toBe(false);
+    expect(result.stdout).toContain('error'); // Regular service should have errors
+    expect(result.stdout).toContain('warning'); // Experimental service should have warnings
+  });
+
+  it('should handle complex rule configurations', async () => {
+    // Create comprehensive config
+    const configContent = `
+module.exports = {
+  rules: {
+    'schema/required-fields': 'error',
+    'refs/owner-exists': 'warn',
+    'best-practices/summary-required': 'warn',
+    'best-practices/owner-required': 'off',
+  },
+  ignorePatterns: ['**/test/**'],
+  overrides: [
+    {
+      files: ['**/critical/**'],
+      rules: {
+        'best-practices/summary-required': 'error',
+        'best-practices/owner-required': 'error',
+      }
+    },
+    {
+      files: ['**/experimental/**'],
+      rules: {
+        'schema/required-fields': 'off',
+        'refs/owner-exists': 'off',
+      }
+    }
+  ]
+};
+`;
+    fs.writeFileSync(configPath, configContent);
+
+    // Create services in different categories
+    createServiceFile(
+      'user-service',
+      `---
+id: user-service
+name: User Service
+version: 1.0.0
+sends:
+  - id: nonexistent-event
+---
+# User Service
+`
+    );
+
+    const criticalDir = path.join(servicesDir, 'critical');
+    fs.mkdirSync(criticalDir, { recursive: true });
+    createServiceFile(
+      'critical/payment-service',
+      `---
+id: payment-service
+name: Payment Service
+version: 1.0.0
+---
+# Payment Service
+`
+    );
+
+    const experimentalDir = path.join(servicesDir, 'experimental');
+    fs.mkdirSync(experimentalDir, { recursive: true });
+    createServiceFile(
+      'experimental/ai-service',
+      `---
+id: ai-service
+name: AI Service
+version: 1.0.0
+sends:
+  - id: nonexistent-event
+---
+# AI Service
+`
+    );
+
+    const testDir = path.join(servicesDir, 'test');
+    fs.mkdirSync(testDir, { recursive: true });
+    createServiceFile(
+      'test/mock-service',
+      `---
+id: mock-service
+name: Mock Service
+version: 1.0.0
+---
+# Mock Service
+`
+    );
+
+    const result = await runLinter();
+
+    // Check that files were processed correctly
+    expect(result.stdout).toContain('file checked'); // Should check files (exact count may vary)
+  });
+
+  it('does not report missing service message references when they are declared as external dependencies in an ESM eventcatalog.config.js', async () => {
+    fs.writeFileSync(
+      path.join(tempDir, 'eventcatalog.config.js'),
+      `
+export default {
+  dependencies: {
+    events: [
+      { id: 'my.company.LocationSyncEvent' },
+      { id: 'my.company.CarrierSyncEvent' },
+    ],
+  },
+};
+`
+    );
+
+    createUserFile(
+      'catalog-owner',
+      `---
+id: catalog-owner
+name: Catalog Owner
+summary: Owns the catalog
+---
+# Catalog Owner
+`
+    );
+
+    createServiceFile(
+      'oms-scs',
+      `---
+id: oms-scs
+name: OMS SCS
+summary: OMS SCS
+owners:
+  - catalog-owner
+receives:
+  - id: my.company.LocationSyncEvent
+  - id: my.company.CarrierSyncEvent
+---
+# OMS SCS
+`
+    );
+
+    const result = await runLinter();
+
+    expect(result.success).toBe(true);
+    expect(result.stdout).not.toContain('Referenced event/command/query');
+    expect(result.stdout).toContain('2 files checked');
+  });
+});
diff --git a/packages/linter/tests/config.test.ts b/packages/linter/tests/config.test.ts
new file mode 100644
index 000000000..1716af70e
--- /dev/null
+++ b/packages/linter/tests/config.test.ts
@@ -0,0 +1,397 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import {
+  loadConfig,
+  loadEventCatalogConfig,
+  shouldIgnoreFile,
+  getEffectiveRules,
+  applyRuleSeverity,
+  parseRuleConfig,
+  DEFAULT_RULES,
+  DEFAULT_IGNORE_PATTERNS,
+} from '../src/config';
+import { ValidationError } from '../src/types';
+
+describe('Configuration', () => {
+  let tempDir: string;
+  let configPath: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'eventcatalog-test-'));
+    configPath = path.join(tempDir, '.eventcatalogrc.js');
+  });
+
+  afterEach(() => {
+    // Clean up temp directory
+    if (fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  describe('loadConfig', () => {
+    it('should return default config when no config file exists', () => {
+      const config = loadConfig(tempDir);
+
+      expect(config).toEqual({
+        rules: DEFAULT_RULES,
+        ignorePatterns: DEFAULT_IGNORE_PATTERNS,
+        overrides: [],
+      });
+    });
+
+    it('should load and merge config from .eventcatalogrc.js', () => {
+      const configContent = `
+        module.exports = {
+          rules: {
+            'schema/required-fields': 'warn',
+            'refs/owner-exists': 'off',
+          },
+          ignorePatterns: ['**/archived/**', '**/drafts/**'],
+          overrides: [
+            {
+              files: ['**/experimental/**'],
+              rules: {
+                'best-practices/owner-required': 'off'
+              }
+            }
+          ]
+        };
+      `;
+
+      fs.writeFileSync(configPath, configContent);
+
+      const config = loadConfig(tempDir);
+
+      expect(config.rules['schema/required-fields']).toBe('warn');
+      expect(config.rules['refs/owner-exists']).toBe('off');
+      expect(config.rules['schema/valid-email']).toBe('error'); // Should keep default
+      expect(config.ignorePatterns).toEqual([...DEFAULT_IGNORE_PATTERNS, '**/archived/**', '**/drafts/**']);
+      expect(config.overrides).toHaveLength(1);
+      expect(config.overrides![0].files).toEqual(['**/experimental/**']);
+    });
+
+    it('should handle invalid config file gracefully', () => {
+      fs.writeFileSync(configPath, 'invalid javascript content {');
+
+      const config = loadConfig(tempDir);
+
+      expect(config).toEqual({
+        rules: DEFAULT_RULES,
+        ignorePatterns: DEFAULT_IGNORE_PATTERNS,
+        overrides: [],
+      });
+    });
+  });
+
+  describe('loadEventCatalogConfig', () => {
+    it('should return empty object when no eventcatalog.config.js exists', () => {
+      const result = loadEventCatalogConfig(tempDir);
+      expect(result).toEqual({});
+    });
+
+    it('should parse dependencies from eventcatalog.config.js', () => {
+      const ecConfigPath = path.join(tempDir, 'eventcatalog.config.js');
+      fs.writeFileSync(
+        ecConfigPath,
+        `module.exports = {
+          dependencies: {
+            events: [{ id: 'OrderPlaced', version: '1.0.0' }],
+            commands: [{ id: 'CreateOrder' }],
+            queries: [{ id: 'GetOrder' }],
+            services: [{ id: 'PaymentService' }],
+            domains: [{ id: 'Order', version: '1.0.0' }],
+            systems: [{ id: 'OrderManagementSystem', version: '1.0.0' }],
+          }
+        };`
+      );
+
+      const result = loadEventCatalogConfig(tempDir);
+
+      expect(result.event).toEqual([{ id: 'OrderPlaced', version: '1.0.0' }]);
+      expect(result.command).toEqual([{ id: 'CreateOrder', version: undefined }]);
+      expect(result.query).toEqual([{ id: 'GetOrder', version: undefined }]);
+      expect(result.service).toEqual([{ id: 'PaymentService', version: undefined }]);
+      expect(result.domain).toEqual([{ id: 'Order', version: '1.0.0' }]);
+      expect(result.system).toEqual([{ id: 'OrderManagementSystem', version: '1.0.0' }]);
+    });
+
+    it('should return empty object when config has no dependencies', () => {
+      const ecConfigPath = path.join(tempDir, 'eventcatalog.config.js');
+      fs.writeFileSync(ecConfigPath, `module.exports = { title: 'My Catalog' };`);
+
+      const result = loadEventCatalogConfig(tempDir);
+      expect(result).toEqual({});
+    });
+
+    it('should handle invalid eventcatalog.config.js gracefully', () => {
+      const ecConfigPath = path.join(tempDir, 'eventcatalog.config.js');
+      fs.writeFileSync(ecConfigPath, 'invalid javascript {');
+
+      const result = loadEventCatalogConfig(tempDir);
+      expect(result).toEqual({});
+    });
+
+    it('should skip unknown plural keys in dependencies', () => {
+      const ecConfigPath = path.join(tempDir, 'eventcatalog.config.js');
+      fs.writeFileSync(
+        ecConfigPath,
+        `module.exports = {
+          dependencies: {
+            events: [{ id: 'OrderPlaced' }],
+            unknownThings: [{ id: 'Something' }],
+          }
+        };`
+      );
+
+      const result = loadEventCatalogConfig(tempDir);
+      expect(result.event).toEqual([{ id: 'OrderPlaced', version: undefined }]);
+      expect(result['unknownThing']).toBeUndefined();
+    });
+
+    it('should filter out entries without a valid id', () => {
+      const ecConfigPath = path.join(tempDir, 'eventcatalog.config.js');
+      fs.writeFileSync(
+        ecConfigPath,
+        `module.exports = {
+          dependencies: {
+            events: [{ id: 'OrderPlaced' }, { version: '1.0.0' }, null, { id: 123 }],
+          }
+        };`
+      );
+
+      const result = loadEventCatalogConfig(tempDir);
+      expect(result.event).toEqual([{ id: 'OrderPlaced', version: undefined }]);
+    });
+  });
+
+  describe('parseRuleConfig', () => {
+    it('should parse string severity', () => {
+      const result = parseRuleConfig('warn');
+      expect(result).toEqual({
+        severity: 'warn',
+        options: {},
+      });
+    });
+
+    it('should parse array with severity and options', () => {
+      const result = parseRuleConfig(['error', { max: 500 }]);
+      expect(result).toEqual({
+        severity: 'error',
+        options: { max: 500 },
+      });
+    });
+  });
+
+  describe('shouldIgnoreFile', () => {
+    it('should return false when no ignore patterns', () => {
+      expect(shouldIgnoreFile('services/user-service/index.mdx', [])).toBe(false);
+    });
+
+    it('should ignore files matching patterns', () => {
+      const patterns = ['**/archived/**', '**/drafts/**'];
+
+      expect(shouldIgnoreFile('services/archived/old-service/index.mdx', patterns)).toBe(true);
+      expect(shouldIgnoreFile('events/drafts/new-event/index.mdx', patterns)).toBe(true);
+      expect(shouldIgnoreFile('services/user-service/index.mdx', patterns)).toBe(false);
+    });
+
+    it('should ignore files in dependencies directory by default', () => {
+      expect(shouldIgnoreFile('dependencies/events/my.company.LocationSyncEvent/index.md', DEFAULT_IGNORE_PATTERNS)).toBe(true);
+      expect(shouldIgnoreFile('dependencies/events/my.company.CarrierSyncEvent/index.md', DEFAULT_IGNORE_PATTERNS)).toBe(true);
+      expect(shouldIgnoreFile('events/OrderPlaced/index.mdx', DEFAULT_IGNORE_PATTERNS)).toBe(false);
+      expect(shouldIgnoreFile('services/user-service/index.mdx', DEFAULT_IGNORE_PATTERNS)).toBe(false);
+    });
+
+    it('should handle single wildcard patterns', () => {
+      const patterns = ['*.tmp', 'test-*'];
+
+      expect(shouldIgnoreFile('services/temp.tmp', patterns)).toBe(true);
+      expect(shouldIgnoreFile('events/test-event.mdx', patterns)).toBe(true);
+      expect(shouldIgnoreFile('services/user-service.mdx', patterns)).toBe(false);
+    });
+  });
+
+  describe('getEffectiveRules', () => {
+    it('should return base rules when no overrides match', () => {
+      const config = {
+        rules: {
+          'schema/required-fields': 'warn',
+          'refs/owner-exists': 'error',
+        },
+        ignorePatterns: [],
+        overrides: [],
+      };
+
+      const rules = getEffectiveRules('services/user-service/index.mdx', config);
+
+      expect(rules['schema/required-fields']).toEqual({
+        severity: 'warn',
+        options: {},
+      });
+      expect(rules['refs/owner-exists']).toEqual({
+        severity: 'error',
+        options: {},
+      });
+    });
+
+    it('should apply overrides when file matches pattern', () => {
+      const config = {
+        rules: {
+          'schema/required-fields': 'warn',
+          'refs/owner-exists': 'error',
+        },
+        ignorePatterns: [],
+        overrides: [
+          {
+            files: ['**/experimental/**'],
+            rules: {
+              'refs/owner-exists': 'off',
+              'best-practices/owner-required': 'warn',
+            },
+          },
+        ],
+      };
+
+      const rules = getEffectiveRules('services/experimental/new-service/index.mdx', config);
+
+      expect(rules['schema/required-fields']).toEqual({
+        severity: 'warn',
+        options: {},
+      });
+      expect(rules['refs/owner-exists']).toEqual({
+        severity: 'off',
+        options: {},
+      });
+      expect(rules['best-practices/owner-required']).toEqual({
+        severity: 'warn',
+        options: {},
+      });
+    });
+
+    it('should apply multiple matching overrides', () => {
+      const config = {
+        rules: {
+          'schema/required-fields': 'error',
+        },
+        ignorePatterns: [],
+        overrides: [
+          {
+            files: ['**/experimental/**'],
+            rules: {
+              'schema/required-fields': 'warn',
+            },
+          },
+          {
+            files: ['**/experimental/new-**'],
+            rules: {
+              'schema/required-fields': 'off',
+            },
+          },
+        ],
+      };
+
+      const rules = getEffectiveRules('services/experimental/new-service/index.mdx', config);
+
+      expect(rules['schema/required-fields']).toEqual({
+        severity: 'off',
+        options: {},
+      });
+    });
+  });
+
+  describe('applyRuleSeverity', () => {
+    const sampleErrors: ValidationError[] = [
+      {
+        type: 'schema',
+        resource: 'service/user-service',
+        field: 'summary',
+        message: 'Summary is required for better documentation',
+        file: 'services/user-service/index.mdx',
+        severity: 'error',
+      },
+      {
+        type: 'reference',
+        resource: 'service/user-service',
+        field: 'owners',
+        message: 'Referenced user/team "missing-owner" does not exist',
+        file: 'services/user-service/index.mdx',
+        severity: 'error',
+      },
+    ];
+
+    it('should filter out disabled rules', () => {
+      const rules = {
+        'best-practices/summary-required': { severity: 'off' as const, options: {} },
+        'refs/owner-exists': { severity: 'error' as const, options: {} },
+      };
+
+      const result = applyRuleSeverity(sampleErrors, rules);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].message).toContain('Referenced user/team');
+    });
+
+    it('should convert warn severity to warning', () => {
+      const rules = {
+        'best-practices/summary-required': { severity: 'warn' as const, options: {} },
+        'refs/owner-exists': { severity: 'error' as const, options: {} },
+      };
+
+      const result = applyRuleSeverity(sampleErrors, rules);
+
+      expect(result).toHaveLength(2);
+      expect(result[0].severity).toBe('warning');
+      expect(result[1].severity).toBe('error');
+    });
+
+    it('should keep error severity as error', () => {
+      const rules = {
+        'best-practices/summary-required': { severity: 'error' as const, options: {} },
+        'refs/owner-exists': { severity: 'error' as const, options: {} },
+      };
+
+      const result = applyRuleSeverity(sampleErrors, rules);
+
+      expect(result).toHaveLength(2);
+      expect(result[0].severity).toBe('error');
+      expect(result[1].severity).toBe('error');
+    });
+
+    it('should handle mixed known and unknown rules', () => {
+      const rules = {
+        'best-practices/summary-required': { severity: 'warn' as const, options: {} },
+        'refs/owner-exists': { severity: 'error' as const, options: {} },
+        'unknown/rule': { severity: 'off' as const, options: {} },
+      };
+
+      const result = applyRuleSeverity(sampleErrors, rules);
+
+      // Both errors should be kept - summary as warning, reference as error
+      expect(result).toHaveLength(2);
+      expect(result[0].severity).toBe('warning'); // summary rule was set to warn
+      expect(result[1].severity).toBe('error'); // reference rule was set to error
+    });
+
+    it('should map email validation errors correctly', () => {
+      const emailError: ValidationError = {
+        type: 'schema',
+        resource: 'user/john-doe',
+        field: 'email',
+        message: 'email: Invalid email',
+        file: 'users/john-doe.mdx',
+        severity: 'error',
+      };
+
+      const rules = {
+        'schema/valid-email': { severity: 'warn' as const, options: {} },
+      };
+
+      const result = applyRuleSeverity([emailError], rules);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].severity).toBe('warning'); // email rule was set to warn
+    });
+  });
+});
diff --git a/packages/linter/tests/new-rules.test.ts b/packages/linter/tests/new-rules.test.ts
new file mode 100644
index 000000000..50dbeb912
--- /dev/null
+++ b/packages/linter/tests/new-rules.test.ts
@@ -0,0 +1,758 @@
+import { describe, it, expect } from 'vitest';
+import {
+  validateReferences,
+  validateOrphanMessages,
+  validateDeprecatedReferences,
+  validateDuplicateResourceIds,
+} from '../src/validators/reference-validator';
+import { validateBestPractices } from '../src/validators/best-practices-validator';
+import { ParsedFile } from '../src/parser';
+import { CatalogFile } from '../src/scanner';
+
+const createParsedFile = (resourceType: any, resourceId: string, frontmatter: any, content: string = ''): ParsedFile => {
+  const file: CatalogFile = {
+    path: `/test/${resourceType}s/${resourceId}/index.mdx`,
+    relativePath: `${resourceType}s/${resourceId}/index.mdx`,
+    resourceType,
+    resourceId,
+  };
+
+  return {
+    file,
+    frontmatter,
+    content,
+    raw: '',
+  };
+};
+
+describe('refs/channel-exists', () => {
+  it('should not report errors when channels in sends.to exist', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        sends: [
+          {
+            id: 'OrderPlaced',
+            to: [{ id: 'orders-channel' }],
+          },
+        ],
+      }),
+      createParsedFile('event', 'OrderPlaced', { id: 'OrderPlaced', version: '1.0.0' }),
+      createParsedFile('channel', 'orders-channel', { id: 'orders-channel', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should report error when channel in sends.to does not exist', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        sends: [
+          {
+            id: 'OrderPlaced',
+            to: [{ id: 'missing-channel' }],
+          },
+        ],
+      }),
+      createParsedFile('event', 'OrderPlaced', { id: 'OrderPlaced', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    const channelErrors = errors.filter((e) => e.rule === 'refs/channel-exists');
+    expect(channelErrors).toHaveLength(1);
+    expect(channelErrors[0].message).toContain('missing-channel');
+    expect(channelErrors[0].field).toBe('sends[0].to[0]');
+  });
+
+  it('should report error when channel in receives.from does not exist', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        receives: [
+          {
+            id: 'OrderPlaced',
+            from: [{ id: 'nonexistent-channel' }],
+          },
+        ],
+      }),
+      createParsedFile('event', 'OrderPlaced', { id: 'OrderPlaced', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    const channelErrors = errors.filter((e) => e.rule === 'refs/channel-exists');
+    expect(channelErrors).toHaveLength(1);
+    expect(channelErrors[0].message).toContain('nonexistent-channel');
+    expect(channelErrors[0].field).toBe('receives[0].from[0]');
+  });
+
+  it('should validate channel version references', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        sends: [
+          {
+            id: 'OrderPlaced',
+            to: [{ id: 'orders-channel', version: '2.0.0' }],
+          },
+        ],
+      }),
+      createParsedFile('event', 'OrderPlaced', { id: 'OrderPlaced', version: '1.0.0' }),
+      createParsedFile('channel', 'orders-channel', { id: 'orders-channel', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    const channelErrors = errors.filter((e) => e.rule === 'refs/channel-exists');
+    expect(channelErrors).toHaveLength(1);
+    expect(channelErrors[0].message).toContain('version: 2.0.0');
+  });
+
+  it('should validate channel references from domains', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('domain', 'sales', {
+        version: '1.0.0',
+        sends: [
+          {
+            id: 'OrderPlaced',
+            to: [{ id: 'missing-channel' }],
+          },
+        ],
+      }),
+      createParsedFile('event', 'OrderPlaced', { id: 'OrderPlaced', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    const channelErrors = errors.filter((e) => e.rule === 'refs/channel-exists');
+    expect(channelErrors).toHaveLength(1);
+  });
+
+  it('should handle multiple channels in a single sends entry', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        sends: [
+          {
+            id: 'OrderPlaced',
+            to: [{ id: 'channel-a' }, { id: 'channel-b' }],
+          },
+        ],
+      }),
+      createParsedFile('event', 'OrderPlaced', { id: 'OrderPlaced', version: '1.0.0' }),
+      createParsedFile('channel', 'channel-a', { id: 'channel-a', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    const channelErrors = errors.filter((e) => e.rule === 'refs/channel-exists');
+    expect(channelErrors).toHaveLength(1);
+    expect(channelErrors[0].message).toContain('channel-b');
+  });
+});
+
+describe('refs/container-exists', () => {
+  it('should not report errors when containers in writesTo exist', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        writesTo: [{ id: 'orders-db' }],
+      }),
+      createParsedFile('dataStore', 'orders-db', { id: 'orders-db', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should report error when container in writesTo does not exist', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        writesTo: [{ id: 'missing-db' }],
+      }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    const containerErrors = errors.filter((e) => e.rule === 'refs/container-exists');
+    expect(containerErrors).toHaveLength(1);
+    expect(containerErrors[0].message).toContain('missing-db');
+    expect(containerErrors[0].field).toBe('writesTo');
+  });
+
+  it('should report error when container in readsFrom does not exist', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        readsFrom: [{ id: 'missing-cache' }],
+      }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    const containerErrors = errors.filter((e) => e.rule === 'refs/container-exists');
+    expect(containerErrors).toHaveLength(1);
+    expect(containerErrors[0].message).toContain('missing-cache');
+    expect(containerErrors[0].field).toBe('readsFrom');
+  });
+
+  it('should validate container version references', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        writesTo: [{ id: 'orders-db', version: '2.0.0' }],
+      }),
+      createParsedFile('dataStore', 'orders-db', { id: 'orders-db', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    // This will be refs/container-exists since writesTo field triggers it,
+    // but version mismatch may trigger refs/valid-version-range depending on rule mapping
+    expect(errors.length).toBeGreaterThanOrEqual(1);
+    expect(errors[0].message).toContain('orders-db');
+  });
+
+  it('should handle both writesTo and readsFrom', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        writesTo: [{ id: 'orders-db' }],
+        readsFrom: [{ id: 'products-cache' }],
+      }),
+      createParsedFile('dataStore', 'orders-db', { id: 'orders-db', version: '1.0.0' }),
+      createParsedFile('dataStore', 'products-cache', { id: 'products-cache', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+});
+
+describe('refs/orphan-messages', () => {
+  it('should report orphan messages with no producer and no consumer', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('event', 'OrphanEvent', { id: 'OrphanEvent', version: '1.0.0' }),
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderPlaced' }],
+      }),
+      createParsedFile('event', 'OrderPlaced', { id: 'OrderPlaced', version: '1.0.0' }),
+    ];
+
+    const errors = validateOrphanMessages(parsedFiles);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].rule).toBe('refs/orphan-messages');
+    expect(errors[0].message).toContain('OrphanEvent');
+    expect(errors[0].message).toContain('no producer and no consumer');
+  });
+
+  it('should not report messages that have a producer (via sends)', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('event', 'OrderPlaced', { id: 'OrderPlaced', version: '1.0.0' }),
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderPlaced' }],
+      }),
+    ];
+
+    const errors = validateOrphanMessages(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should not report messages that have a consumer (via receives)', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('command', 'CreateOrder', { id: 'CreateOrder', version: '1.0.0' }),
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        receives: [{ id: 'CreateOrder' }],
+      }),
+    ];
+
+    const errors = validateOrphanMessages(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should not report messages that have producers field set on the message itself', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('event', 'OrderPlaced', {
+        id: 'OrderPlaced',
+        version: '1.0.0',
+        producers: ['order-service'],
+      }),
+    ];
+
+    const errors = validateOrphanMessages(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should not report messages that have consumers field set on the message itself', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('event', 'OrderPlaced', {
+        id: 'OrderPlaced',
+        version: '1.0.0',
+        consumers: ['notification-service'],
+      }),
+    ];
+
+    const errors = validateOrphanMessages(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should detect orphan commands and queries too', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('command', 'OrphanCommand', { id: 'OrphanCommand', version: '1.0.0' }),
+      createParsedFile('query', 'OrphanQuery', { id: 'OrphanQuery', version: '1.0.0' }),
+    ];
+
+    const errors = validateOrphanMessages(parsedFiles);
+    expect(errors).toHaveLength(2);
+    expect(errors[0].message).toContain('OrphanCommand');
+    expect(errors[1].message).toContain('OrphanQuery');
+  });
+
+  it('should not report orphans for messages that exist in dependencies', () => {
+    const parsedFiles: ParsedFile[] = [createParsedFile('event', 'ExternalEvent', { id: 'ExternalEvent', version: '1.0.0' })];
+
+    const dependencies = {
+      event: [{ id: 'ExternalEvent', version: '1.0.0' }],
+    };
+
+    const errors = validateOrphanMessages(parsedFiles, dependencies);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should not report when domain sends the message', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('event', 'DomainEvent', { id: 'DomainEvent', version: '1.0.0' }),
+      createParsedFile('domain', 'sales', {
+        version: '1.0.0',
+        sends: [{ id: 'DomainEvent' }],
+      }),
+    ];
+
+    const errors = validateOrphanMessages(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+});
+
+describe('best-practices/description-required', () => {
+  it('should report when resource has no markdown body content', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile(
+        'service',
+        'order-service',
+        {
+          id: 'order-service',
+          version: '1.0.0',
+          summary: 'A service',
+          owners: ['team-a'],
+        },
+        ''
+      ),
+    ];
+
+    const errors = validateBestPractices(parsedFiles);
+    const descErrors = errors.filter((e) => e.rule === 'best-practices/description-required');
+    expect(descErrors).toHaveLength(1);
+    expect(descErrors[0].field).toBe('description');
+  });
+
+  it('should report when resource has only whitespace body content', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile(
+        'service',
+        'order-service',
+        {
+          id: 'order-service',
+          version: '1.0.0',
+          summary: 'A service',
+          owners: ['team-a'],
+        },
+        '   \n  \n  '
+      ),
+    ];
+
+    const errors = validateBestPractices(parsedFiles);
+    const descErrors = errors.filter((e) => e.rule === 'best-practices/description-required');
+    expect(descErrors).toHaveLength(1);
+  });
+
+  it('should not report when resource has markdown body content', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile(
+        'service',
+        'order-service',
+        {
+          id: 'order-service',
+          version: '1.0.0',
+          summary: 'A service',
+          owners: ['team-a'],
+        },
+        '\n## Overview\n\nThis service handles orders.'
+      ),
+    ];
+
+    const errors = validateBestPractices(parsedFiles);
+    const descErrors = errors.filter((e) => e.rule === 'best-practices/description-required');
+    expect(descErrors).toHaveLength(0);
+  });
+});
+
+describe('best-practices/schema-required', () => {
+  it('should report when event has no schemaPath', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile(
+        'event',
+        'OrderPlaced',
+        {
+          id: 'OrderPlaced',
+          version: '1.0.0',
+          summary: 'An event',
+          owners: ['team-a'],
+        },
+        'Some content'
+      ),
+    ];
+
+    const errors = validateBestPractices(parsedFiles);
+    const schemaErrors = errors.filter((e) => e.rule === 'best-practices/schema-required');
+    expect(schemaErrors).toHaveLength(1);
+    expect(schemaErrors[0].field).toBe('schemaPath');
+    expect(schemaErrors[0].message).toContain('schemaPath');
+  });
+
+  it('should report when command has no schemaPath', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile(
+        'command',
+        'CreateOrder',
+        {
+          id: 'CreateOrder',
+          version: '1.0.0',
+          summary: 'A command',
+          owners: ['team-a'],
+        },
+        'Some content'
+      ),
+    ];
+
+    const errors = validateBestPractices(parsedFiles);
+    const schemaErrors = errors.filter((e) => e.rule === 'best-practices/schema-required');
+    expect(schemaErrors).toHaveLength(1);
+  });
+
+  it('should report when query has no schemaPath', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile(
+        'query',
+        'GetOrder',
+        {
+          id: 'GetOrder',
+          version: '1.0.0',
+          summary: 'A query',
+          owners: ['team-a'],
+        },
+        'Some content'
+      ),
+    ];
+
+    const errors = validateBestPractices(parsedFiles);
+    const schemaErrors = errors.filter((e) => e.rule === 'best-practices/schema-required');
+    expect(schemaErrors).toHaveLength(1);
+  });
+
+  it('should not report when event has schemaPath', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile(
+        'event',
+        'OrderPlaced',
+        {
+          id: 'OrderPlaced',
+          version: '1.0.0',
+          summary: 'An event',
+          owners: ['team-a'],
+          schemaPath: 'schema.json',
+        },
+        'Some content'
+      ),
+    ];
+
+    const errors = validateBestPractices(parsedFiles);
+    const schemaErrors = errors.filter((e) => e.rule === 'best-practices/schema-required');
+    expect(schemaErrors).toHaveLength(0);
+  });
+
+  it('should not report for services (non-message types)', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile(
+        'service',
+        'order-service',
+        {
+          id: 'order-service',
+          version: '1.0.0',
+          summary: 'A service',
+          owners: ['team-a'],
+        },
+        'Some content'
+      ),
+    ];
+
+    const errors = validateBestPractices(parsedFiles);
+    const schemaErrors = errors.filter((e) => e.rule === 'best-practices/schema-required');
+    expect(schemaErrors).toHaveLength(0);
+  });
+});
+
+describe('versions/no-deprecated-references', () => {
+  it('should warn when referencing a deprecated resource', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        sends: [{ id: 'OldEvent' }],
+      }),
+      createParsedFile('event', 'OldEvent', {
+        id: 'OldEvent',
+        version: '1.0.0',
+        deprecated: true,
+      }),
+    ];
+
+    const errors = validateDeprecatedReferences(parsedFiles);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].rule).toBe('versions/no-deprecated-references');
+    expect(errors[0].message).toContain('OldEvent');
+    expect(errors[0].message).toContain('deprecated');
+  });
+
+  it('should not warn when referencing a non-deprecated resource', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        sends: [{ id: 'ActiveEvent' }],
+      }),
+      createParsedFile('event', 'ActiveEvent', {
+        id: 'ActiveEvent',
+        version: '1.0.0',
+      }),
+    ];
+
+    const errors = validateDeprecatedReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should handle deprecated: false as not deprecated', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        sends: [{ id: 'ActiveEvent' }],
+      }),
+      createParsedFile('event', 'ActiveEvent', {
+        id: 'ActiveEvent',
+        version: '1.0.0',
+        deprecated: false,
+      }),
+    ];
+
+    const errors = validateDeprecatedReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should handle deprecated object format', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        sends: [{ id: 'OldEvent' }],
+      }),
+      createParsedFile('event', 'OldEvent', {
+        id: 'OldEvent',
+        version: '1.0.0',
+        deprecated: { message: 'Use NewEvent instead', date: '2024-01-01' },
+      }),
+    ];
+
+    const errors = validateDeprecatedReferences(parsedFiles);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].rule).toBe('versions/no-deprecated-references');
+  });
+
+  it('should warn for deprecated service references from domains', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('domain', 'sales', {
+        version: '1.0.0',
+        services: [{ id: 'old-service' }],
+      }),
+      createParsedFile('service', 'old-service', {
+        id: 'old-service',
+        version: '1.0.0',
+        deprecated: true,
+      }),
+    ];
+
+    const errors = validateDeprecatedReferences(parsedFiles);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain('old-service');
+  });
+
+  it('should not warn for owner references to deprecated users/teams', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        owners: ['old-user'],
+      }),
+      createParsedFile('user', 'old-user', {
+        id: 'old-user',
+        deprecated: true,
+      }),
+    ];
+
+    const errors = validateDeprecatedReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should return empty when no deprecated resources exist', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderPlaced' }],
+      }),
+      createParsedFile('event', 'OrderPlaced', {
+        id: 'OrderPlaced',
+        version: '1.0.0',
+      }),
+    ];
+
+    const errors = validateDeprecatedReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should match version-specific deprecated references', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderPlaced', version: '1.0.0' }],
+      }),
+      createParsedFile('event', 'OrderPlaced', {
+        id: 'OrderPlaced',
+        version: '1.0.0',
+        deprecated: true,
+      }),
+      createParsedFile('event', 'OrderPlaced', {
+        id: 'OrderPlaced',
+        version: '2.0.0',
+      }),
+    ];
+
+    const errors = validateDeprecatedReferences(parsedFiles);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain('version: 1.0.0');
+  });
+});
+
+describe('structure/duplicate-resource-ids', () => {
+  it('should report duplicate resources with same type, id, and version', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', { id: 'order-service', version: '1.0.0' }),
+      {
+        ...createParsedFile('service', 'order-service', { id: 'order-service', version: '1.0.0' }),
+        file: {
+          path: '/test/domains/sales/services/order-service/index.mdx',
+          relativePath: 'domains/sales/services/order-service/index.mdx',
+          resourceType: 'service' as any,
+          resourceId: 'order-service',
+        },
+      },
+    ];
+
+    const errors = validateDuplicateResourceIds(parsedFiles);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].rule).toBe('structure/duplicate-resource-ids');
+    expect(errors[0].message).toContain('order-service');
+    expect(errors[0].message).toContain('version: 1.0.0');
+    expect(errors[0].message).toContain('also defined in');
+  });
+
+  it('should not report resources with same id but different versions', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', { id: 'order-service', version: '1.0.0' }),
+      createParsedFile('service', 'order-service', { id: 'order-service', version: '2.0.0' }),
+    ];
+
+    const errors = validateDuplicateResourceIds(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should not report resources with same id but different types', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order', { id: 'order', version: '1.0.0' }),
+      createParsedFile('entity', 'order', { id: 'order', version: '1.0.0' }),
+    ];
+
+    const errors = validateDuplicateResourceIds(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should detect duplicates using frontmatter.id over file resourceId', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('event', 'OrderPlaced', { id: 'order-placed', version: '1.0.0' }),
+      {
+        ...createParsedFile('event', 'order-placed', { id: 'order-placed', version: '1.0.0' }),
+        file: {
+          path: '/test/events/order-placed/index.mdx',
+          relativePath: 'events/order-placed/index.mdx',
+          resourceType: 'event' as any,
+          resourceId: 'order-placed',
+        },
+      },
+    ];
+
+    const errors = validateDuplicateResourceIds(parsedFiles);
+    expect(errors).toHaveLength(1);
+  });
+
+  it('should handle resources without version as "latest"', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('user', 'john-doe', { id: 'john-doe' }),
+      {
+        ...createParsedFile('user', 'john', { id: 'john-doe' }),
+        file: {
+          path: '/test/users/john.mdx',
+          relativePath: 'users/john.mdx',
+          resourceType: 'user' as any,
+          resourceId: 'john',
+        },
+      },
+    ];
+
+    const errors = validateDuplicateResourceIds(parsedFiles);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain('version: latest');
+  });
+
+  it('should not report when all resources are unique', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', { id: 'order-service', version: '1.0.0' }),
+      createParsedFile('service', 'user-service', { id: 'user-service', version: '1.0.0' }),
+      createParsedFile('event', 'OrderPlaced', { id: 'OrderPlaced', version: '1.0.0' }),
+    ];
+
+    const errors = validateDuplicateResourceIds(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+});
diff --git a/packages/linter/tests/reference-validator-latest.test.ts b/packages/linter/tests/reference-validator-latest.test.ts
new file mode 100644
index 000000000..9b6cbf8cc
--- /dev/null
+++ b/packages/linter/tests/reference-validator-latest.test.ts
@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { validateReferences } from '../src/validators/reference-validator';
+import { ParsedFile } from '../src/parser';
+import { CatalogFile } from '../src/scanner';
+
+const createParsedFile = (resourceType: any, resourceId: string, frontmatter: any): ParsedFile => {
+  const file: CatalogFile = {
+    path: `/test/${resourceType}s/${resourceId}/index.mdx`,
+    relativePath: `${resourceType}s/${resourceId}/index.mdx`,
+    resourceType,
+    resourceId,
+  };
+
+  return {
+    file,
+    frontmatter,
+    content: '',
+    raw: '',
+  };
+};
+
+describe('validateReferences - latest version handling', () => {
+  it('should allow references without version (latest)', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('domain', 'sales', {
+        version: '1.0.0',
+        services: [{ id: 'InventoryService' }, { id: 'OrdersService' }, { id: 'NotificationService' }, { id: 'ShippingService' }],
+      }),
+      createParsedFile('service', 'InventoryService', { version: '2.1.0' }),
+      createParsedFile('service', 'OrdersService', { version: '1.5.0' }),
+      createParsedFile('service', 'NotificationService', { version: '3.0.0' }),
+      createParsedFile('service', 'ShippingService', { version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should allow mixed version references (some with version, some without)', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'user-service', {
+        version: '1.0.0',
+        sends: [
+          { id: 'user-created' }, // no version - should use latest
+          { id: 'user-updated', version: '2.0.0' }, // specific version
+        ],
+      }),
+      createParsedFile('event', 'user-created', { version: '1.5.0' }),
+      createParsedFile('event', 'user-updated', { version: '2.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should handle services without versions in frontmatter', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('domain', 'sales', {
+        version: '1.0.0',
+        services: [{ id: 'InventoryService' }],
+      }),
+      // Service without version in frontmatter - should be treated as 'latest'
+      createParsedFile('service', 'InventoryService', {}),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+});
diff --git a/packages/linter/tests/reference-validator.test.ts b/packages/linter/tests/reference-validator.test.ts
new file mode 100644
index 000000000..fbf3d9989
--- /dev/null
+++ b/packages/linter/tests/reference-validator.test.ts
@@ -0,0 +1,1048 @@
+import { describe, it, expect } from 'vitest';
+import { buildResourceIndex, validateReferences } from '../src/validators/reference-validator';
+import { ParsedFile } from '../src/parser';
+import { CatalogFile } from '../src/scanner';
+
+const createParsedFile = (resourceType: any, resourceId: string, frontmatter: any): ParsedFile => {
+  const file: CatalogFile = {
+    path: `/test/${resourceType}s/${resourceId}/index.mdx`,
+    relativePath: `${resourceType}s/${resourceId}/index.mdx`,
+    resourceType,
+    resourceId,
+  };
+
+  return {
+    file,
+    frontmatter,
+    content: '',
+    raw: '',
+  };
+};
+
+describe('buildResourceIndex', () => {
+  it('should build index with resources and versions', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'user-service', { id: 'user-service', version: '1.0.0' }),
+      createParsedFile('service', 'user-service', { id: 'user-service', version: '2.0.0' }),
+      createParsedFile('event', 'user-created', { id: 'user-created', version: '1.0.0' }),
+      createParsedFile('user', 'john-doe', {}),
+    ];
+
+    const index = buildResourceIndex(parsedFiles);
+
+    expect(index.service['user-service']).toBeDefined();
+    expect(index.service['user-service'].has('1.0.0')).toBe(true);
+    expect(index.service['user-service'].has('2.0.0')).toBe(true);
+    expect(index.event['user-created'].has('1.0.0')).toBe(true);
+    expect(index.user['john-doe']).toBeDefined();
+  });
+
+  it('should fall back to file.resourceId when frontmatter.id is not defined', () => {
+    const parsedFiles: ParsedFile[] = [
+      // No frontmatter.id, should use file.resourceId from path
+      createParsedFile('service', 'user-service', { version: '1.0.0' }),
+      createParsedFile('event', 'order-created', { version: '2.0.0' }),
+    ];
+
+    const index = buildResourceIndex(parsedFiles);
+
+    // Should use file.resourceId when frontmatter.id is not present
+    expect(index.service['user-service']).toBeDefined();
+    expect(index.service['user-service'].has('1.0.0')).toBe(true);
+    expect(index.event['order-created']).toBeDefined();
+    expect(index.event['order-created'].has('2.0.0')).toBe(true);
+  });
+
+  it('should use frontmatter.id for services/events/channels when different from file path', () => {
+    const parsedFiles: ParsedFile[] = [
+      // file.resourceId from path is 'UserService' (SentenceCase), but frontmatter.id is 'user-service' (kebab-case)
+      createParsedFile('service', 'UserService', { id: 'user-service', version: '1.0.0' }),
+      // file.resourceId from path is 'UserCreated' (SentenceCase), but frontmatter.id is 'user-created' (kebab-case)
+      createParsedFile('event', 'UserCreated', { id: 'user-created', version: '1.0.0' }),
+      // file.resourceId from path is 'OrderCreatedChannel' (SentenceCase), but frontmatter.id is 'order-created-channel' (kebab-case)
+      createParsedFile('channel', 'OrderCreatedChannel', { id: 'order-created-channel', version: '1.0.0' }),
+    ];
+
+    const index = buildResourceIndex(parsedFiles);
+
+    // Should use frontmatter.id, not file.resourceId
+    expect(index.service['user-service']).toBeDefined();
+    expect(index.service['user-service'].has('1.0.0')).toBe(true);
+    expect(index.event['user-created']).toBeDefined();
+    expect(index.event['user-created'].has('1.0.0')).toBe(true);
+    expect(index.channel['order-created-channel']).toBeDefined();
+    expect(index.channel['order-created-channel'].has('1.0.0')).toBe(true);
+
+    // Should NOT have entries for the path-based IDs
+    expect(index.service['UserService']).toBeUndefined();
+    expect(index.event['UserCreated']).toBeUndefined();
+    expect(index.channel['OrderCreatedChannel']).toBeUndefined();
+  });
+
+  it('should use frontmatter.id for commands/queries when different from file path', () => {
+    const parsedFiles: ParsedFile[] = [
+      // file.resourceId from path is 'CreateUser' (SentenceCase), but frontmatter.id is 'create-user' (kebab-case)
+      createParsedFile('command', 'CreateUser', { id: 'create-user', version: '1.0.0' }),
+      // file.resourceId from path is 'GetUserProfile' (SentenceCase), but frontmatter.id is 'get-user-profile' (kebab-case)
+      createParsedFile('query', 'GetUserProfile', { id: 'get-user-profile', version: '1.0.0' }),
+    ];
+
+    const index = buildResourceIndex(parsedFiles);
+
+    // Should use frontmatter.id, not file.resourceId
+    expect(index.command['create-user']).toBeDefined();
+    expect(index.command['create-user'].has('1.0.0')).toBe(true);
+    expect(index.query['get-user-profile']).toBeDefined();
+    expect(index.query['get-user-profile'].has('1.0.0')).toBe(true);
+
+    // Should NOT have entries for the path-based IDs
+    expect(index.command['CreateUser']).toBeUndefined();
+    expect(index.query['GetUserProfile']).toBeUndefined();
+  });
+
+  it('should use frontmatter.id for entities when different from file path', () => {
+    const parsedFiles: ParsedFile[] = [
+      // file.resourceId from path is 'UserEntity' (SentenceCase), but frontmatter.id is 'user-entity' (kebab-case)
+      createParsedFile('entity', 'UserEntity', { id: 'user-entity', version: '1.0.0' }),
+    ];
+
+    const index = buildResourceIndex(parsedFiles);
+
+    // Should use frontmatter.id, not file.resourceId
+    expect(index.entity['user-entity']).toBeDefined();
+    expect(index.entity['user-entity'].has('1.0.0')).toBe(true);
+
+    // Should NOT have entries for the path-based IDs
+    expect(index.entity['UserEntity']).toBeUndefined();
+  });
+
+  it('should use frontmatter.id for flows when different from file path', () => {
+    const parsedFiles: ParsedFile[] = [
+      // file.resourceId from path is 'OrderFlow' (SentenceCase), but frontmatter.id is 'order-flow' (kebab-case)
+      createParsedFile('flow', 'OrderFlow', { id: 'order-flow', version: '1.0.0' }),
+    ];
+
+    const index = buildResourceIndex(parsedFiles);
+
+    // Should use frontmatter.id, not file.resourceId
+    expect(index.flow['order-flow']).toBeDefined();
+    expect(index.flow['order-flow'].has('1.0.0')).toBe(true);
+
+    // Should NOT have entries for the path-based IDs
+    expect(index.flow['OrderFlow']).toBeUndefined();
+  });
+
+  it('should build index for newer resource types', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('agent', 'RefundAgent', { id: 'refund-agent', version: '1.0.0' }),
+      createParsedFile('system', 'CustomerManagementSystem', { id: 'customer-management-system', version: '1.0.0' }),
+      createParsedFile('container', 'PaymentsDb', { id: 'payments-db', version: '1.0.0' }),
+      createParsedFile('dataProduct', 'PaymentAnalytics', { id: 'payment-analytics', version: '1.0.0' }),
+      createParsedFile('diagram', 'OrderFlow', { id: 'order-flow', version: '1.0.0' }),
+      createParsedFile('adr', 'ADR001', { id: 'adr-001', version: '1.0.0' }),
+    ];
+
+    const index = buildResourceIndex(parsedFiles);
+
+    expect(index.agent['refund-agent']).toBeDefined();
+    expect(index.system['customer-management-system']).toBeDefined();
+    expect(index.container['payments-db']).toBeDefined();
+    expect(index.dataProduct['payment-analytics']).toBeDefined();
+    expect(index.diagram['order-flow']).toBeDefined();
+    expect(index.adr['adr-001']).toBeDefined();
+  });
+});
+
+describe('validateReferences', () => {
+  it('should not report errors for valid references', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('domain', 'sales', {
+        version: '1.0.0',
+        services: [{ id: 'order-service' }],
+        entities: [{ id: 'order', version: '1.0.0' }],
+      }),
+      createParsedFile('service', 'order-service', { id: 'order-service', version: '1.0.0' }),
+      createParsedFile('entity', 'order', { id: 'order', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should use frontmatter.id for service references when different from file path', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('domain', 'sales', {
+        version: '1.0.0',
+        services: [{ id: 'order-service' }], // References frontmatter.id (kebab-case)
+      }),
+      // file.resourceId is 'OrderService' (SentenceCase), but frontmatter.id is 'order-service' (kebab-case)
+      createParsedFile('service', 'OrderService', { id: 'order-service', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    // Should pass because frontmatter.id matches the reference
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should use frontmatter.id for entity references when different from file path', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('domain', 'sales', {
+        version: '1.0.0',
+        entities: [{ id: 'order-entity', version: '1.0.0' }], // References frontmatter.id (kebab-case)
+      }),
+      // file.resourceId is 'OrderEntity' (SentenceCase), but frontmatter.id is 'order-entity' (kebab-case)
+      createParsedFile('entity', 'OrderEntity', { id: 'order-entity', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    // Should pass because frontmatter.id matches the reference
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should use frontmatter.id for entity property references when different from file path', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('entity', 'user-entity', {
+        id: 'user-entity',
+        version: '1.0.0',
+        properties: [
+          {
+            name: 'address',
+            references: 'address-entity', // References frontmatter.id (kebab-case)
+          },
+        ],
+      }),
+      // file.resourceId is 'AddressEntity' (SentenceCase), but frontmatter.id is 'address-entity' (kebab-case)
+      createParsedFile('entity', 'AddressEntity', { id: 'address-entity', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    // Should pass because frontmatter.id matches the reference
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should report errors for missing references', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('domain', 'sales', {
+        version: '1.0.0',
+        services: [{ id: 'missing-service' }],
+      }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].type).toBe('reference');
+    expect(errors[0].message).toContain('missing-service');
+  });
+
+  it('should report errors for wrong version references', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'user-service', {
+        id: 'user-service',
+        version: '1.0.0',
+        sends: [{ id: 'user-created', version: '2.0.0' }],
+      }),
+      createParsedFile('event', 'user-created', { id: 'user-created', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain('version: 2.0.0');
+  });
+
+  it('should check message references in multiple types', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'user-service', {
+        id: 'user-service',
+        version: '1.0.0',
+        sends: [{ id: 'user-updated' }],
+      }),
+      createParsedFile('event', 'user-updated', { id: 'user-updated', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate domain references to agents, systems, data products, and flows', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('domain', 'sales', {
+        version: '1.0.0',
+        agents: [{ id: 'refund-agent' }],
+        systems: [{ id: 'order-management-system' }],
+        'data-products': [{ id: 'payment-analytics' }],
+        flows: [{ id: 'refund-flow' }],
+      }),
+      createParsedFile('agent', 'refund-agent', { id: 'refund-agent', version: '1.0.0' }),
+      createParsedFile('system', 'order-management-system', { id: 'order-management-system', version: '1.0.0' }),
+      createParsedFile('dataProduct', 'payment-analytics', { id: 'payment-analytics', version: '1.0.0' }),
+      createParsedFile('flow', 'refund-flow', { id: 'refund-flow', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should report missing domain references to agents, systems, and data products', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('domain', 'sales', {
+        version: '1.0.0',
+        agents: [{ id: 'missing-agent' }],
+        systems: [{ id: 'missing-system' }],
+        'data-products': [{ id: 'missing-product' }],
+      }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(3);
+    expect(errors.map((error) => error.message)).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining('missing-agent'),
+        expect.stringContaining('missing-system'),
+        expect.stringContaining('missing-product'),
+      ])
+    );
+  });
+
+  it('should validate system references to resources and relationships', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('system', 'customer-management-system', {
+        id: 'customer-management-system',
+        version: '1.0.0',
+        services: [{ id: 'customer-api' }],
+        flows: [{ id: 'customer-registration' }],
+        entities: [{ id: 'customer' }],
+        containers: [{ id: 'customer-db' }],
+        relationships: [{ id: 'identity-provider', version: '1.0.0', label: 'delegates authentication to' }],
+      }),
+      createParsedFile('service', 'customer-api', { id: 'customer-api', version: '1.0.0' }),
+      createParsedFile('flow', 'customer-registration', { id: 'customer-registration', version: '1.0.0' }),
+      createParsedFile('entity', 'customer', { id: 'customer', version: '1.0.0' }),
+      createParsedFile('container', 'customer-db', { id: 'customer-db', version: '1.0.0' }),
+      createParsedFile('system', 'identity-provider', { id: 'identity-provider', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should report missing system resource references', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('system', 'customer-management-system', {
+        id: 'customer-management-system',
+        version: '1.0.0',
+        services: [{ id: 'missing-service' }],
+        flows: [{ id: 'missing-flow' }],
+        entities: [{ id: 'missing-entity' }],
+        containers: [{ id: 'missing-container' }],
+        relationships: [{ id: 'missing-system', label: 'depends on' }],
+      }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(5);
+    expect(errors.map((error) => error.field)).toEqual(
+      expect.arrayContaining(['services', 'flows', 'entities', 'containers', 'relationships'])
+    );
+  });
+
+  it('should validate data product input and output references across resource types', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('dataProduct', 'order-metrics', {
+        id: 'order-metrics',
+        version: '1.0.0',
+        inputs: [{ id: 'OrderConfirmed' }, { id: 'order-service' }, { id: 'orders-db' }],
+        outputs: [{ id: 'metrics-channel' }],
+      }),
+      createParsedFile('event', 'OrderConfirmed', { id: 'OrderConfirmed', version: '1.0.0' }),
+      createParsedFile('service', 'order-service', { id: 'order-service', version: '1.0.0' }),
+      createParsedFile('container', 'orders-db', { id: 'orders-db', version: '1.0.0' }),
+      createParsedFile('channel', 'metrics-channel', { id: 'metrics-channel', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should use frontmatter.id for command references when different from file path', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'user-service', {
+        id: 'user-service',
+        version: '1.0.0',
+        receives: [{ id: 'create-user' }], // References frontmatter.id (kebab-case)
+      }),
+      // file.resourceId is 'CreateUser' (SentenceCase), but frontmatter.id is 'create-user' (kebab-case)
+      createParsedFile('command', 'CreateUser', { id: 'create-user', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    // Should pass because frontmatter.id matches the reference
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should use frontmatter.id for query references when different from file path', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'user-service', {
+        id: 'user-service',
+        version: '1.0.0',
+        receives: [{ id: 'get-user-profile' }], // References frontmatter.id (kebab-case)
+      }),
+      // file.resourceId is 'GetUserProfile' (SentenceCase), but frontmatter.id is 'get-user-profile' (kebab-case)
+      createParsedFile('query', 'GetUserProfile', { id: 'get-user-profile', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    // Should pass because frontmatter.id matches the reference
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate flow step references', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('flow', 'user-registration', {
+        version: '1.0.0',
+        steps: [
+          {
+            id: 'step1',
+            title: 'Send command',
+            message: { id: 'create-user', version: '1.0.0' },
+          },
+          {
+            id: 'step2',
+            title: 'Process in service',
+            service: { id: 'missing-service', version: '1.0.0' },
+          },
+        ],
+      }),
+      createParsedFile('command', 'create-user', { id: 'create-user', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].field).toContain('steps[1].service');
+  });
+
+  it('should use frontmatter.id for flow step message references when different from file path', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('flow', 'order-flow', {
+        id: 'order-flow',
+        version: '1.0.0',
+        steps: [
+          {
+            id: 'step1',
+            title: 'Create order',
+            message: { id: 'order-created', version: '1.0.0' }, // References frontmatter.id (kebab-case)
+          },
+        ],
+      }),
+      // file.resourceId is 'OrderCreated' (SentenceCase), but frontmatter.id is 'order-created' (kebab-case)
+      createParsedFile('event', 'OrderCreated', { id: 'order-created', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    // Should pass because frontmatter.id matches the reference
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate flow step references to agents, containers, and data products', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('flow', 'refund-flow', {
+        id: 'refund-flow',
+        version: '1.0.0',
+        steps: [
+          { id: 'agent', title: 'Refund Agent', agent: { id: 'refund-agent' } },
+          { id: 'container', title: 'Payments DB', container: { id: 'payments-db' } },
+          { id: 'data-product', title: 'Payment Analytics', dataProduct: { id: 'payment-analytics' } },
+        ],
+      }),
+      createParsedFile('agent', 'refund-agent', { id: 'refund-agent', version: '1.0.0' }),
+      createParsedFile('container', 'payments-db', { id: 'payments-db', version: '1.0.0' }),
+      createParsedFile('dataProduct', 'payment-analytics', { id: 'payment-analytics', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should report missing flow step references to agents, containers, and data products', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('flow', 'refund-flow', {
+        id: 'refund-flow',
+        version: '1.0.0',
+        steps: [
+          { id: 'agent', title: 'Refund Agent', agent: { id: 'missing-agent' } },
+          { id: 'container', title: 'Payments DB', container: { id: 'missing-db' } },
+          { id: 'data-product', title: 'Payment Analytics', dataProduct: { id: 'missing-product' } },
+        ],
+      }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(3);
+    expect(errors.map((error) => error.field)).toEqual(
+      expect.arrayContaining(['steps[0].agent', 'steps[1].container', 'steps[2].dataProduct'])
+    );
+  });
+
+  it('should use frontmatter.id for flow step service references when different from file path', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('flow', 'order-flow', {
+        id: 'order-flow',
+        version: '1.0.0',
+        steps: [
+          {
+            id: 'step1',
+            title: 'Process order',
+            service: { id: 'order-service', version: '1.0.0' }, // References frontmatter.id (kebab-case)
+          },
+        ],
+      }),
+      // file.resourceId is 'OrderService' (SentenceCase), but frontmatter.id is 'order-service' (kebab-case)
+      createParsedFile('service', 'OrderService', { id: 'order-service', version: '1.0.0' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    // Should pass because frontmatter.id matches the reference
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate owner references', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'user-service', {
+        id: 'user-service',
+        version: '1.0.0',
+        owners: ['john-doe', 'platform-team'],
+      }),
+      createParsedFile('user', 'john-doe', {}),
+      createParsedFile('team', 'platform-team', {}),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate owner object references', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'order-service', {
+        id: 'order-service',
+        version: '1.0.0',
+        owners: [{ id: 'platform-team', collection: 'teams' }],
+      }),
+      createParsedFile('team', 'platform-team', { id: 'platform-team' }),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate team member references', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('team', 'platform-team', {
+        members: ['john-doe', 'jane-doe'],
+      }),
+      createParsedFile('user', 'john-doe', {}),
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain('jane-doe');
+  });
+
+  it('should use frontmatter id for user and team references instead of filename', () => {
+    const parsedFiles: ParsedFile[] = [
+      createParsedFile('service', 'user-service', {
+        version: '1.0.0',
+        owners: ['asmith', 'msmith'], // lowercase refs
+      }),
+      createParsedFile('team', 'platform-team', {
+        members: ['asmith'], // lowercase ref
+      }),
+      // User files with filename mismatch - filename has capital letters, frontmatter has lowercase
+      {
+        ...createParsedFile('user', 'aSmith', { id: 'asmith' }), // filename: aSmith, frontmatter: asmith
+        file: {
+          ...createParsedFile('user', 'aSmith', {}).file,
+          path: '/test/users/aSmith.mdx',
+          relativePath: 'users/aSmith.mdx',
+        },
+      },
+      {
+        ...createParsedFile('user', 'mSmith', { id: 'msmith' }), // filename: mSmith, frontmatter: msmith
+        file: {
+          ...createParsedFile('user', 'mSmith', {}).file,
+          path: '/test/users/mSmith.mdx',
+          relativePath: 'users/mSmith.mdx',
+        },
+      },
+    ];
+
+    const errors = validateReferences(parsedFiles);
+    expect(errors).toHaveLength(0); // Should not report any errors
+  });
+
+  describe('semver version matching', () => {
+    it('should support "latest" version references', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'inventory-service', {
+          id: 'inventory-service',
+          version: '1.0.0',
+          sends: [{ id: 'OutOfStock', version: 'latest' }],
+        }),
+        createParsedFile('event', 'OutOfStock', { id: 'OutOfStock', version: '2.0.0' }),
+        createParsedFile('event', 'OutOfStock', { id: 'OutOfStock', version: '1.5.0' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate channel routes', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('channel', 'domain-bus', {
+          id: 'domain-bus',
+          version: '1.0.0',
+          routes: [{ id: 'orders-channel' }],
+        }),
+        createParsedFile('channel', 'orders-channel', { id: 'orders-channel', version: '1.0.0' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate ADR typed resource references and relationships', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('adr', 'adr-002', {
+          id: 'adr-002',
+          version: '1.0.0',
+          appliesTo: [
+            { type: 'service', id: 'order-service' },
+            { type: 'system', id: 'order-management-system' },
+            { type: 'data-product', id: 'order-metrics' },
+          ],
+          supersedes: [{ id: 'adr-001' }],
+        }),
+        createParsedFile('adr', 'adr-001', { id: 'adr-001', version: '1.0.0' }),
+        createParsedFile('service', 'order-service', { id: 'order-service', version: '1.0.0' }),
+        createParsedFile('system', 'order-management-system', { id: 'order-management-system', version: '1.0.0' }),
+        createParsedFile('dataProduct', 'order-metrics', { id: 'order-metrics', version: '1.0.0' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate user and team owned agent and system references', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('user', 'dboyne', {
+          id: 'dboyne',
+          ownedAgents: [{ id: 'support-agent' }],
+          ownedSystems: [{ id: 'customer-management-system' }],
+        }),
+        createParsedFile('team', 'platform', {
+          id: 'platform',
+          ownedAgents: [{ id: 'support-agent' }],
+          ownedSystems: [{ id: 'customer-management-system' }],
+        }),
+        createParsedFile('agent', 'support-agent', { id: 'support-agent', version: '1.0.0' }),
+        createParsedFile('system', 'customer-management-system', { id: 'customer-management-system', version: '1.0.0' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should support x-pattern version matching like "0.0.x"', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'inventory-service', {
+          id: 'inventory-service',
+          version: '1.0.0',
+          sends: [{ id: 'GetInventoryList', version: '0.0.x' }],
+        }),
+        createParsedFile('command', 'GetInventoryList', { id: 'GetInventoryList', version: '0.0.1' }),
+        createParsedFile('command', 'GetInventoryList', { id: 'GetInventoryList', version: '0.0.5' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should support semver range patterns like "^1.0.0"', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'user-service', {
+          id: 'user-service',
+          version: '1.0.0',
+          sends: [{ id: 'UserCreated', version: '^1.0.0' }],
+        }),
+        createParsedFile('event', 'UserCreated', { id: 'UserCreated', version: '1.2.0' }),
+        createParsedFile('event', 'UserCreated', { id: 'UserCreated', version: '1.0.5' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should support tilde range patterns like "~1.2.0"', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'user-service', {
+          id: 'user-service',
+          version: '1.0.0',
+          sends: [{ id: 'UserUpdated', version: '~1.2.0' }],
+        }),
+        createParsedFile('event', 'UserUpdated', { id: 'UserUpdated', version: '1.2.3' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should reject invalid version patterns', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'inventory-service', {
+          id: 'inventory-service',
+          version: '1.0.0',
+          sends: [{ id: 'GetInventoryList', version: '0.1.x' }], // No 0.1.x available
+        }),
+        createParsedFile('command', 'GetInventoryList', { id: 'GetInventoryList', version: '0.0.1' }),
+        createParsedFile('command', 'GetInventoryList', { id: 'GetInventoryList', version: '0.2.1' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(1);
+      expect(errors[0].message).toContain('version: 0.1.x');
+    });
+
+    it('should reject semver patterns that do not match any available versions', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'user-service', {
+          id: 'user-service',
+          version: '1.0.0',
+          sends: [{ id: 'UserCreated', version: '^2.0.0' }], // No 2.x versions available
+        }),
+        createParsedFile('event', 'UserCreated', { id: 'UserCreated', version: '1.2.0' }),
+        createParsedFile('event', 'UserCreated', { id: 'UserCreated', version: '1.5.0' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(1);
+      expect(errors[0].message).toContain('version: ^2.0.0');
+    });
+
+    it('should handle resources with "latest" version when requested with patterns', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'inventory-service', {
+          id: 'inventory-service',
+          version: '1.0.0',
+          sends: [{ id: 'StockUpdate', version: '^1.0.0' }],
+        }),
+        createParsedFile('event', 'StockUpdate', { id: 'StockUpdate' }), // No version specified, defaults to 'latest'
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(1); // Should fail because 'latest' doesn't match semver pattern
+    });
+
+    it('should allow exact version matches even when semver patterns fail', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'inventory-service', {
+          id: 'inventory-service',
+          version: '1.0.0',
+          sends: [{ id: 'OutOfStock', version: '1.0.0' }], // Exact match
+        }),
+        createParsedFile('event', 'OutOfStock', { id: 'OutOfStock', version: '1.0.0' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0);
+    });
+  });
+
+  describe('domain-to-domain references', () => {
+    it('should not report errors for valid domain references', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('domain', 'e-commerce', {
+          version: '1.0.0',
+          domains: [
+            { id: 'orders', version: '1.0.0' },
+            { id: 'payments' }, // No version specified, should use latest
+          ],
+          services: [{ id: 'user-service' }],
+        }),
+        createParsedFile('domain', 'orders', { version: '1.0.0' }),
+        createParsedFile('domain', 'payments', { version: '2.0.0' }),
+        createParsedFile('service', 'user-service', { id: 'user-service', version: '1.0.0' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should report errors for missing domain references', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('domain', 'e-commerce', {
+          version: '1.0.0',
+          domains: [
+            { id: 'orders' },
+            { id: 'missing-domain' }, // This domain doesn't exist
+          ],
+        }),
+        createParsedFile('domain', 'orders', { version: '1.0.0' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(1);
+      expect(errors[0].type).toBe('reference');
+      expect(errors[0].field).toBe('domains');
+      expect(errors[0].message).toContain('missing-domain');
+      expect(errors[0].message).toContain('does not exist');
+    });
+
+    it('should report errors for domain references with wrong versions', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('domain', 'e-commerce', {
+          version: '1.0.0',
+          domains: [
+            { id: 'orders', version: '2.0.0' }, // Version 2.0.0 doesn't exist
+          ],
+        }),
+        createParsedFile('domain', 'orders', { version: '1.0.0' }), // Only 1.0.0 exists
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(1);
+      expect(errors[0].type).toBe('reference');
+      expect(errors[0].field).toBe('domains');
+      expect(errors[0].message).toContain('orders');
+      expect(errors[0].message).toContain('version: 2.0.0');
+    });
+
+    it('should support semver patterns in domain references', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('domain', 'parent-domain', {
+          version: '1.0.0',
+          domains: [
+            { id: 'child-domain', version: '^1.0.0' }, // Should match 1.2.0
+          ],
+        }),
+        createParsedFile('domain', 'child-domain', { version: '1.2.0' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate complex domain hierarchies', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('domain', 'enterprise', {
+          version: '1.0.0',
+          domains: [{ id: 'e-commerce' }, { id: 'analytics' }],
+        }),
+        createParsedFile('domain', 'e-commerce', {
+          version: '1.0.0',
+          domains: [{ id: 'orders' }, { id: 'payments' }],
+          services: [{ id: 'user-service' }],
+        }),
+        createParsedFile('domain', 'analytics', { version: '1.0.0' }),
+        createParsedFile('domain', 'orders', { version: '1.0.0' }),
+        createParsedFile('domain', 'payments', { version: '1.0.0' }),
+        createParsedFile('service', 'user-service', { id: 'user-service', version: '1.0.0' }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should catch circular domain references', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('domain', 'domain-a', {
+          version: '1.0.0',
+          domains: [{ id: 'domain-b' }],
+        }),
+        createParsedFile('domain', 'domain-b', {
+          version: '1.0.0',
+          domains: [{ id: 'domain-a' }], // Circular reference
+        }),
+      ];
+
+      // The validator doesn't prevent circular references, it just validates they exist
+      // This should pass because both domains exist
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should resolve domain references without versions to latest', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('domain', 'e-commerce', {
+          id: 'E-Commerce', // Different case from directory name
+          version: '1.0.0',
+          domains: [
+            { id: 'Orders' }, // No version specified - should resolve to latest
+            { id: 'Payments' }, // No version specified - should resolve to latest
+          ],
+        }),
+        createParsedFile('domain', 'orders', {
+          id: 'Orders', // Different case from directory name
+          version: '2.0.0',
+        }),
+        createParsedFile('domain', 'payments', {
+          id: 'Payments', // Different case from directory name
+          version: '1.5.0',
+        }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0); // Should pass - latest versions found
+    });
+
+    it('should handle case sensitivity between directory names and frontmatter IDs', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('domain', 'e-commerce', {
+          id: 'E-Commerce', // Uppercase ID in lowercase directory
+          version: '1.0.0',
+          domains: [
+            { id: 'Order-Management', version: '1.0.0' }, // Reference with specific version
+          ],
+        }),
+        createParsedFile('domain', 'order-management', {
+          id: 'Order-Management', // Different case from directory name
+          version: '1.0.0',
+        }),
+      ];
+
+      const errors = validateReferences(parsedFiles);
+      expect(errors).toHaveLength(0); // Should pass - IDs match frontmatter, not directory names
+    });
+  });
+
+  describe('eventcatalog.config.js dependencies', () => {
+    it('should not report errors for references that exist in dependencies', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'order-service', {
+          id: 'order-service',
+          version: '1.0.0',
+          sends: [{ id: 'OrderPlaced' }],
+          receives: [{ id: 'CreateOrder' }],
+        }),
+      ];
+
+      const dependencies = {
+        event: [{ id: 'OrderPlaced', version: '1.0.0' }],
+        command: [{ id: 'CreateOrder' }],
+      };
+
+      const errors = validateReferences(parsedFiles, dependencies);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should still report errors for references not in dependencies or parsed files', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'order-service', {
+          id: 'order-service',
+          version: '1.0.0',
+          sends: [{ id: 'OrderPlaced' }, { id: 'NonExistentEvent' }],
+        }),
+      ];
+
+      const dependencies = {
+        event: [{ id: 'OrderPlaced', version: '1.0.0' }],
+      };
+
+      const errors = validateReferences(parsedFiles, dependencies);
+      expect(errors).toHaveLength(1);
+      expect(errors[0].message).toContain('NonExistentEvent');
+    });
+
+    it('should resolve version-specific references from dependencies', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'order-service', {
+          id: 'order-service',
+          version: '1.0.0',
+          sends: [{ id: 'OrderPlaced', version: '1.0.0' }],
+        }),
+      ];
+
+      const dependencies = {
+        event: [{ id: 'OrderPlaced', version: '1.0.0' }],
+      };
+
+      const errors = validateReferences(parsedFiles, dependencies);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should report errors when dependency version does not match reference version', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'order-service', {
+          id: 'order-service',
+          version: '1.0.0',
+          sends: [{ id: 'OrderPlaced', version: '2.0.0' }],
+        }),
+      ];
+
+      const dependencies = {
+        event: [{ id: 'OrderPlaced', version: '1.0.0' }],
+      };
+
+      const errors = validateReferences(parsedFiles, dependencies);
+      expect(errors).toHaveLength(1);
+      expect(errors[0].message).toContain('version: 2.0.0');
+    });
+
+    it('should handle dependencies without version as latest', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('service', 'order-service', {
+          id: 'order-service',
+          version: '1.0.0',
+          sends: [{ id: 'OrderPlaced' }],
+        }),
+      ];
+
+      const dependencies = {
+        event: [{ id: 'OrderPlaced' }],
+      };
+
+      const errors = validateReferences(parsedFiles, dependencies);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should support all dependency resource types', () => {
+      const parsedFiles: ParsedFile[] = [
+        createParsedFile('domain', 'e-commerce', {
+          version: '1.0.0',
+          services: [{ id: 'PaymentService' }],
+          domains: [{ id: 'Order' }],
+          entities: [{ id: 'OrderEntity' }],
+        }),
+        createParsedFile('service', 'my-service', {
+          id: 'my-service',
+          version: '1.0.0',
+          sends: [{ id: 'OrderPlaced' }],
+          receives: [{ id: 'GetOrder' }],
+        }),
+      ];
+
+      const dependencies = {
+        service: [{ id: 'PaymentService', version: '1.0.0' }],
+        domain: [{ id: 'Order', version: '1.0.0' }],
+        entity: [{ id: 'OrderEntity', version: '1.0.0' }],
+        event: [{ id: 'OrderPlaced', version: '1.0.0' }],
+        query: [{ id: 'GetOrder' }],
+      };
+
+      const errors = validateReferences(parsedFiles, dependencies);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should add dependency index entries to buildResourceIndex', () => {
+      const parsedFiles: ParsedFile[] = [];
+      const dependencies = {
+        event: [{ id: 'OrderPlaced', version: '1.0.0' }],
+        service: [{ id: 'PaymentService' }],
+      };
+
+      const index = buildResourceIndex(parsedFiles, dependencies);
+
+      expect(index.event['OrderPlaced']).toBeDefined();
+      expect(index.event['OrderPlaced'].has('1.0.0')).toBe(true);
+      expect(index.service['PaymentService']).toBeDefined();
+      expect(index.service['PaymentService'].has('latest')).toBe(true);
+    });
+  });
+});
diff --git a/packages/linter/tests/scanner.test.ts b/packages/linter/tests/scanner.test.ts
new file mode 100644
index 000000000..f8088c63f
--- /dev/null
+++ b/packages/linter/tests/scanner.test.ts
@@ -0,0 +1,139 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { extractResourceInfo, scanCatalogFiles } from '../src/scanner';
+
+describe('extractResourceInfo', () => {
+  it('should extract simple resource id', () => {
+    const result = extractResourceInfo('services/user-service/index.mdx', 'service');
+    expect(result).toEqual({ id: 'user-service' });
+  });
+
+  it('should extract resource id with versioned structure', () => {
+    const result = extractResourceInfo('services/user-service/versioned/1.0.0/index.mdx', 'service');
+    expect(result).toEqual({ id: 'user-service', version: '1.0.0' });
+  });
+
+  it('should extract subdomain service id', () => {
+    const result = extractResourceInfo('domains/sales/subdomains/orders/services/inventory-service/index.mdx', 'service');
+    expect(result).toEqual({ id: 'inventory-service' });
+  });
+
+  it('should extract subdomain service with version', () => {
+    const result = extractResourceInfo(
+      'domains/sales/subdomains/orders/services/inventory-service/versioned/2.1.0/index.mdx',
+      'service'
+    );
+    expect(result).toEqual({ id: 'inventory-service', version: '2.1.0' });
+  });
+
+  it('should extract domain with subdomain', () => {
+    const result = extractResourceInfo('domains/sales/subdomains/orders/index.mdx', 'domain');
+    expect(result).toEqual({ id: 'sales/subdomains/orders' });
+  });
+
+  it('should extract domain with versioned structure', () => {
+    const result = extractResourceInfo('domains/sales/versioned/2.1.0/index.mdx', 'domain');
+    expect(result).toEqual({ id: 'sales', version: '2.1.0' });
+  });
+
+  it('should extract user id from filename', () => {
+    const result = extractResourceInfo('users/john-doe.mdx', 'user');
+    expect(result).toEqual({ id: 'john-doe' });
+  });
+
+  it('should extract team id from filename', () => {
+    const result = extractResourceInfo('teams/platform-team.mdx', 'team');
+    expect(result).toEqual({ id: 'platform-team' });
+  });
+
+  it('should extract nested container id', () => {
+    const result = extractResourceInfo('domains/sales/services/order-service/containers/orders-db/index.mdx', 'container');
+    expect(result).toEqual({ id: 'orders-db' });
+  });
+
+  it('should extract data product id from data-products folders', () => {
+    const result = extractResourceInfo('domains/sales/data-products/order-metrics/versioned/1.0.0/index.mdx', 'dataProduct');
+    expect(result).toEqual({ id: 'order-metrics', version: '1.0.0' });
+  });
+
+  it('should extract nested diagram id', () => {
+    const result = extractResourceInfo('domains/sales/diagrams/order-flow/versioned/1.0.0/index.mdx', 'diagram');
+    expect(result).toEqual({ id: 'order-flow', version: '1.0.0' });
+  });
+
+  it('should extract adr id', () => {
+    const result = extractResourceInfo('adrs/adr-001/index.md', 'adr');
+    expect(result).toEqual({ id: 'adr-001' });
+  });
+
+  it('should extract nested system id', () => {
+    const result = extractResourceInfo('domains/customer/systems/customer-management-system/index.mdx', 'system');
+    expect(result).toEqual({ id: 'customer-management-system' });
+  });
+
+  it('should extract versioned system id', () => {
+    const result = extractResourceInfo('systems/customer-management-system/versioned/1.0.0/index.mdx', 'system');
+    expect(result).toEqual({ id: 'customer-management-system', version: '1.0.0' });
+  });
+
+  it('should scan newer resource types', async () => {
+    const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), 'eventcatalog-linter-scanner-'));
+    const files = [
+      'domains/sales/agents/refund-agent/index.mdx',
+      'domains/sales/data-products/order-metrics/index.mdx',
+      'domains/sales/services/order-service/containers/orders-db/index.mdx',
+      'domains/sales/systems/order-management-system/index.mdx',
+      'domains/sales/diagrams/order-flow/index.mdx',
+      'adrs/adr-001/index.md',
+    ];
+
+    await Promise.all(
+      files.map(async (file) => {
+        const filePath = path.join(rootDir, file);
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, '---\nid: test\nname: Test\nversion: 1.0.0\n---\n');
+      })
+    );
+
+    const catalogFiles = await scanCatalogFiles(rootDir);
+    expect(catalogFiles.map((file) => file.resourceType).sort()).toEqual([
+      'adr',
+      'agent',
+      'container',
+      'dataProduct',
+      'diagram',
+      'system',
+    ]);
+  });
+
+  it('should scan systems without treating nested resources as systems', async () => {
+    const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), 'eventcatalog-linter-scanner-'));
+    const files = [
+      'domains/customer/systems/customer-management-system/index.mdx',
+      'domains/customer/systems/customer-management-system/versioned/1.0.0/index.mdx',
+      'domains/customer/systems/customer-management-system/services/customer-api/index.mdx',
+      'domains/customer/systems/customer-management-system/containers/customer-db/index.mdx',
+    ];
+
+    await Promise.all(
+      files.map(async (file) => {
+        const filePath = path.join(rootDir, file);
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, '---\nid: test\nname: Test\nversion: 1.0.0\n---\n');
+      })
+    );
+
+    const catalogFiles = await scanCatalogFiles(rootDir);
+    const systemFiles = catalogFiles.filter((file) => file.resourceType === 'system');
+
+    expect(systemFiles).toHaveLength(2);
+    expect(systemFiles.map((file) => file.resourceId).sort()).toEqual([
+      'customer-management-system',
+      'customer-management-system',
+    ]);
+    expect(catalogFiles.some((file) => file.resourceType === 'service' && file.resourceId === 'customer-api')).toBe(true);
+    expect(catalogFiles.some((file) => file.resourceType === 'container' && file.resourceId === 'customer-db')).toBe(true);
+  });
+});
diff --git a/packages/linter/tests/schema-validator.test.ts b/packages/linter/tests/schema-validator.test.ts
new file mode 100644
index 000000000..1f3a4e0a7
--- /dev/null
+++ b/packages/linter/tests/schema-validator.test.ts
@@ -0,0 +1,408 @@
+import { describe, it, expect } from 'vitest';
+import { validateSchema } from '../src/validators/schema-validator';
+import { ParsedFile } from '../src/parser';
+import { CatalogFile } from '../src/scanner';
+
+const createParsedFile = (resourceType: any, frontmatter: any, resourceId = 'test-resource'): ParsedFile => {
+  const file: CatalogFile = {
+    path: `/test/${resourceType}s/${resourceId}/index.mdx`,
+    relativePath: `${resourceType}s/${resourceId}/index.mdx`,
+    resourceType,
+    resourceId,
+  };
+
+  return {
+    file,
+    frontmatter,
+    content: '',
+    raw: '',
+  };
+};
+
+describe('validateSchema', () => {
+  describe('domain validation', () => {
+    it('should pass with valid domain frontmatter', () => {
+      const parsedFile = createParsedFile('domain', {
+        id: 'sales',
+        name: 'Sales Domain',
+        version: '1.0.0',
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should fail with missing required fields', () => {
+      const parsedFile = createParsedFile('domain', {
+        id: 'sales',
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors[0].type).toBe('schema');
+    });
+
+    it('should fail with invalid version format', () => {
+      const parsedFile = createParsedFile('domain', {
+        id: 'sales',
+        name: 'Sales Domain',
+        version: 'invalid-version',
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors[0].message).toContain('semantic version');
+    });
+  });
+
+  describe('service validation', () => {
+    it('should pass with valid service frontmatter', () => {
+      const parsedFile = createParsedFile('service', {
+        id: 'user-service',
+        name: 'User Service',
+        version: '2.1.0',
+        sends: [{ id: 'user-created' }],
+        receives: [{ id: 'create-user', version: '1.0.0' }],
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should pass with deprecated field', () => {
+      const parsedFile = createParsedFile('service', {
+        id: 'user-service',
+        name: 'User Service',
+        version: '2.1.0',
+        deprecated: {
+          date: '2024-01-01',
+          message: 'Use new-user-service instead',
+        },
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+  });
+
+  describe('event validation', () => {
+    it('should pass with valid event frontmatter', () => {
+      const parsedFile = createParsedFile('event', {
+        id: 'user-created',
+        name: 'User Created',
+        version: '1.0.0',
+        draft: true,
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should pass with draft object', () => {
+      const parsedFile = createParsedFile('event', {
+        id: 'user-created',
+        name: 'User Created',
+        version: '1.0.0',
+        draft: {
+          title: 'Work in Progress',
+          message: 'This event is still being designed',
+        },
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+  });
+
+  describe('flow validation', () => {
+    it('should pass with valid flow frontmatter', () => {
+      const parsedFile = createParsedFile('flow', {
+        id: 'user-registration',
+        name: 'User Registration Flow',
+        version: '1.0.0',
+        steps: [
+          {
+            id: 'step1',
+            title: 'User submits form',
+            actor: { name: 'User' },
+            next_step: 'step2',
+          },
+          {
+            id: 'step2',
+            title: 'Service creates user',
+            service: { id: 'user-service', version: '1.0.0' },
+          },
+        ],
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should pass with agent, container, and data product flow steps', () => {
+      const parsedFile = createParsedFile('flow', {
+        id: 'refund-flow',
+        name: 'Refund Flow',
+        version: '1.0.0',
+        steps: [
+          {
+            id: 'agent',
+            type: 'agent',
+            title: 'Refund Agent',
+            agent: { id: 'refund-agent' },
+            next_step: 'container',
+          },
+          {
+            id: 'container',
+            title: 'Payments DB',
+            container: { id: 'payments-db' },
+            next_step: 'data-product',
+          },
+          {
+            id: 'data-product',
+            title: 'Payment Analytics',
+            dataProduct: { id: 'payment-analytics' },
+          },
+        ],
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+  });
+
+  describe('entity validation', () => {
+    it('should pass with valid entity frontmatter', () => {
+      const parsedFile = createParsedFile('entity', {
+        id: 'user',
+        name: 'User',
+        version: '1.0.0',
+        aggregateRoot: true,
+        identifier: 'userId',
+        properties: [
+          {
+            name: 'userId',
+            type: 'string',
+            required: true,
+            description: 'Unique identifier',
+          },
+          {
+            name: 'orders',
+            type: 'Order[]',
+            references: 'order',
+            relationType: 'one-to-many',
+          },
+        ],
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+  });
+
+  describe('user validation', () => {
+    it('should pass with valid user frontmatter', () => {
+      const parsedFile = createParsedFile('user', {
+        id: 'john-doe',
+        name: 'John Doe',
+        email: 'john.doe@example.com',
+        role: 'Developer',
+        ownedSystems: [{ id: 'customer-management-system' }],
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should pass with minimal user frontmatter', () => {
+      const parsedFile = createParsedFile('user', {
+        id: 'jane-doe',
+        name: 'Jane Doe',
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should fail with invalid email format', () => {
+      const parsedFile = createParsedFile('user', {
+        id: 'john-doe',
+        name: 'John Doe',
+        email: 'invalid-email-format',
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors[0].type).toBe('schema');
+      expect(errors[0].field).toBe('email');
+      expect(errors[0].message).toContain('Invalid email');
+    });
+
+    it('should fail with empty email string', () => {
+      const parsedFile = createParsedFile('user', {
+        id: 'john-doe',
+        name: 'John Doe',
+        email: '',
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors[0].field).toBe('email');
+    });
+  });
+
+  describe('team validation', () => {
+    it('should pass with valid team frontmatter', () => {
+      const parsedFile = createParsedFile('team', {
+        id: 'platform-team',
+        name: 'Platform Team',
+        email: 'platform-team@example.com',
+        summary: 'Handles platform infrastructure',
+        members: ['john-doe', 'jane-doe'],
+        ownedSystems: [{ id: 'customer-management-system' }],
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should pass with minimal team frontmatter', () => {
+      const parsedFile = createParsedFile('team', {
+        id: 'platform-team',
+        name: 'Platform Team',
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should fail with invalid email format', () => {
+      const parsedFile = createParsedFile('team', {
+        id: 'platform-team',
+        name: 'Platform Team',
+        email: 'not-an-email',
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors[0].type).toBe('schema');
+      expect(errors[0].field).toBe('email');
+      expect(errors[0].message).toContain('Invalid email');
+    });
+  });
+
+  describe('data store validation', () => {
+    it('should pass with valid data store frontmatter', () => {
+      const parsedFile = createParsedFile('dataStore', {
+        id: 'user-data-store',
+        name: 'User Data Store',
+        version: '1.0.0',
+        container_type: 'database',
+        technology: 'PostgreSQL',
+        authoritative: true,
+        access_mode: 'readWrite',
+        classification: 'public',
+        residency: 'US',
+        retention: '1 year',
+      });
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should fail with invalid container type', () => {
+      const parsedFile = createParsedFile('dataStore', {
+        id: 'user-data-store',
+        name: 'User Data Store',
+        version: '1.0.0',
+        container_type: 'invalid-container-type',
+      });
+      const errors = validateSchema(parsedFile);
+      expect(errors.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('newer resource validation', () => {
+    it('should pass with valid agent frontmatter', () => {
+      const parsedFile = createParsedFile('agent', {
+        id: 'refund-agent',
+        name: 'Refund Agent',
+        version: '1.0.0',
+        receives: [{ id: 'RefundRequested' }],
+        readsFrom: [{ id: 'payments-db' }],
+        tools: [{ name: 'Payment lookup', type: 'mcp' }],
+        model: { provider: 'OpenAI', name: 'gpt-4.1-mini' },
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should pass with valid system frontmatter', () => {
+      const parsedFile = createParsedFile('system', {
+        id: 'customer-management-system',
+        name: 'Customer Management System',
+        version: '1.0.0',
+        scope: 'internal',
+        services: [{ id: 'customer-api' }],
+        flows: [{ id: 'customer-registration' }],
+        entities: [{ id: 'customer' }],
+        containers: [{ id: 'customer-database' }],
+        relationships: [{ id: 'identity-provider', label: 'delegates authentication to' }],
+        actors: [{ id: 'customer', name: 'Customer', label: 'registers', direction: 'inbound' }],
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should pass with valid container frontmatter', () => {
+      const parsedFile = createParsedFile('container', {
+        id: 'payments-db',
+        name: 'Payments DB',
+        version: '1.0.0',
+        container_type: 'other',
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should pass with valid data product frontmatter', () => {
+      const parsedFile = createParsedFile('dataProduct', {
+        id: 'payment-analytics',
+        name: 'Payment Analytics',
+        version: '1.0.0',
+        inputs: [{ id: 'PaymentProcessed' }],
+        outputs: [{ id: 'payments-db', contract: { path: 'contract.json', name: 'Payments Contract' } }],
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should pass with valid adr frontmatter', () => {
+      const parsedFile = createParsedFile('adr', {
+        id: 'adr-001',
+        name: 'Use events',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2026-05-26',
+        appliesTo: [{ type: 'service', id: 'OrderService' }],
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should pass with valid diagram frontmatter', () => {
+      const parsedFile = createParsedFile('diagram', {
+        id: 'order-flow',
+        name: 'Order Flow',
+        version: '1.0.0',
+      });
+
+      const errors = validateSchema(parsedFile);
+      expect(errors).toHaveLength(0);
+    });
+  });
+});
diff --git a/packages/linter/tests/utils/semver.test.ts b/packages/linter/tests/utils/semver.test.ts
new file mode 100644
index 000000000..8775d68de
--- /dev/null
+++ b/packages/linter/tests/utils/semver.test.ts
@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { semverSchema } from '../../src/schemas/common';
+
+describe('semverSchema', () => {
+  it('should accept valid semantic versions and patterns', () => {
+    const validVersions = [
+      // Standard semver
+      '0.0.0',
+      '1.0.0',
+      '1.2.3',
+      '10.20.30',
+      '1.0.0-alpha',
+      '1.0.0-alpha.1',
+      '1.0.0-0.3.7',
+      '1.0.0-x.7.z.92',
+      '1.0.0+20130313144700',
+      '1.0.0-beta+exp.sha.5114f85',
+      '1.0.0+21AF26D3-117B474E93B',
+      // EventCatalog patterns
+      'latest',
+      '0.0.x',
+      '1.x',
+      '2.1.x',
+      '^1.0.0',
+      '~1.2.0',
+      '^2.0.0-alpha',
+    ];
+
+    for (const version of validVersions) {
+      expect(() => semverSchema.parse(version)).not.toThrow();
+    }
+  });
+
+  it('should reject invalid semantic versions', () => {
+    const invalidVersions = [
+      '1',
+      '1.2',
+      'v1.0.0',
+      '1.0',
+      '1.0.0.0',
+      'not-a-version',
+      '1.0.0 beta',
+      '', // empty string
+      'x.x.x', // invalid x pattern
+      'latest-alpha', // invalid latest variant
+    ];
+
+    for (const version of invalidVersions) {
+      expect(() => semverSchema.parse(version), `Expected "${version}" to throw`).toThrow();
+    }
+  });
+});
diff --git a/packages/linter/tsconfig.json b/packages/linter/tsconfig.json
new file mode 100644
index 000000000..64c7de85f
--- /dev/null
+++ b/packages/linter/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "moduleResolution": "bundler"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
diff --git a/packages/linter/tsup.config.ts b/packages/linter/tsup.config.ts
new file mode 100644
index 000000000..75bccdd20
--- /dev/null
+++ b/packages/linter/tsup.config.ts
@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts', 'src/cli/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  shims: true,
+});
diff --git a/packages/linter/vitest.config.ts b/packages/linter/vitest.config.ts
new file mode 100644
index 000000000..b81b8a535
--- /dev/null
+++ b/packages/linter/vitest.config.ts
@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules/', 'dist/'],
+    },
+  },
+});
diff --git a/packages/playground/README.md b/packages/playground/README.md
new file mode 100644
index 000000000..d0f430193
--- /dev/null
+++ b/packages/playground/README.md
@@ -0,0 +1,17 @@
+# EventCatalog Compass
+
+> **Beta** - This package is in active development.
+
+A browser-based EventCatalog Compass workspace for the [EventCatalog DSL](../language-server/README.md). Write `.ec` code in a Monaco editor with syntax highlighting, completions, and diagnostics, and see your architecture visualised in real time.
+
+## Getting Started
+
+```bash
+pnpm dev
+```
+
+Open `http://localhost:5173/new` to start from a blank workspace with no template selected.
+
+## How It Works
+
+EventCatalog Compass uses the `@eventcatalog/language-server` to parse DSL input and the `@eventcatalog/visualiser` to render the resulting architecture graph. As you type, your DSL is parsed and the visualisation updates live.
diff --git a/packages/playground/index.html b/packages/playground/index.html
new file mode 100644
index 000000000..226211c9c
--- /dev/null
+++ b/packages/playground/index.html
@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet" />
+    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='6' fill='%236C3FEF'/%3E%3Cpath d='M17.5 5L10 18h5.5L14.5 27 22 14h-5.5z' fill='%23FFF' stroke='%23FFF' stroke-width='1.5' stroke-linejoin='round'/%3E%3C/svg%3E" />
+    <title>EventCatalog Compass</title>
+
+    <!-- OpenGraph -->
+    <meta property="og:title" content="EventCatalog Compass" />
+    <meta property="og:description" content="Model, visualize, and share your architecture. Design event-driven systems, import from AsyncAPI & OpenAPI specs, and give your team a living architecture view." />
+    <meta property="og:image" content="https://compass.eventcatalog.dev/og-image.png" />
+    <meta property="og:url" content="https://compass.eventcatalog.dev" />
+    <meta property="og:type" content="website" />
+
+    <!-- Twitter -->
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content="EventCatalog Compass" />
+    <meta name="twitter:description" content="Model, visualize, and share your architecture. Design event-driven systems, import from AsyncAPI & OpenAPI specs, and give your team a living architecture view." />
+    <meta name="twitter:image" content="https://compass.eventcatalog.dev/og-image.png" />
+
+    <!-- General -->
+    <meta name="description" content="Model, visualize, and share your architecture. Design event-driven systems, import from AsyncAPI & OpenAPI specs, and give your team a living architecture view." />
+
+    <!-- PostHog -->
+    <script>
+      !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys getNextSurveyStep onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
+      posthog.init('phc_HQZncKORYsXgO87WuSjSdKbQSTzylljE6HTtUw0fBIH', {
+        api_host: 'https://e.eventcatalog.dev/relay-fBIH',
+        capture_performance: false,
+      })
+    </script>
+  </head>
+  <body style="margin: 0">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/packages/playground/package.json b/packages/playground/package.json
new file mode 100644
index 000000000..c59c5d866
--- /dev/null
+++ b/packages/playground/package.json
@@ -0,0 +1,38 @@
+{
+  "name": "@eventcatalog/dsl-playground",
+  "version": "0.1.0",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@eventcatalog/language-server": "workspace:*",
+    "@eventcatalog/visualiser": "workspace:*",
+    "@monaco-editor/react": "^4.7.0",
+    "@nanostores/persistent": "^1.3.3",
+    "@nanostores/react": "^1.0.0",
+    "@xyflow/react": "^12.4.0",
+    "cmdk": "^1.1.1",
+    "langium": "^3.3.1",
+    "lucide-react": "^0.563.0",
+    "nanostores": "^1.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.13.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.1.18",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "postcss": "^8.5.6",
+    "react-scan": "^0.4.3",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.7.0",
+    "vite": "^6.1.0"
+  }
+}
diff --git a/packages/playground/postcss.config.js b/packages/playground/postcss.config.js
new file mode 100644
index 000000000..c2ddf7482
--- /dev/null
+++ b/packages/playground/postcss.config.js
@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
diff --git a/packages/playground/public/asyncapi.svg b/packages/playground/public/asyncapi.svg
new file mode 100644
index 000000000..871d8faae
--- /dev/null
+++ b/packages/playground/public/asyncapi.svg
@@ -0,0 +1,2 @@
+
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 155.51 155.51"><defs><style>.cls-1{fill:url(#linear-gradient);}.cls-2{fill:url(#linear-gradient-2);}.cls-3{fill:url(#linear-gradient-3);}.cls-4{fill:url(#linear-gradient-4);}.cls-5{fill:#fff;}</style><linearGradient id="linear-gradient" x1="133.74" y1="21.76" x2="24.84" y2="130.67" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#2dccfd"/><stop offset="1" stop-color="#ad20e2"/></linearGradient><linearGradient id="linear-gradient-2" x1="6471.36" y1="6969.64" x2="6362.46" y2="7078.54" gradientTransform="translate(7103.38 -6337.62) rotate(90)" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#a829e2"/><stop offset="0.05" stop-color="#a829e2" stop-opacity="0.84"/><stop offset="0.11" stop-color="#a829e2" stop-opacity="0.67"/><stop offset="0.18" stop-color="#a829e2" stop-opacity="0.51"/><stop offset="0.25" stop-color="#a829e2" stop-opacity="0.38"/><stop offset="0.33" stop-color="#a829e2" stop-opacity="0.28"/><stop offset="0.43" stop-color="#a829e2" stop-opacity="0.2"/><stop offset="0.54" stop-color="#a829e2" stop-opacity="0.14"/><stop offset="0.68" stop-color="#a829e2" stop-opacity="0.11"/><stop offset="1" stop-color="#a829e2" stop-opacity="0.1"/></linearGradient><linearGradient id="linear-gradient-3" x1="13419.24" y1="632.02" x2="13310.33" y2="740.92" gradientTransform="translate(13441 765.76) rotate(180)" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#e50e99"/><stop offset="1" stop-color="#a829e2" stop-opacity="0.1"/></linearGradient><linearGradient id="linear-gradient-4" x1="138.74" y1="-7.39" x2="29.84" y2="101.52" gradientTransform="translate(-5 29.16)" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#21d4fd"/><stop offset="0.03" stop-color="#27cdfc" stop-opacity="0.96"/><stop offset="0.23" stop-color="#4e9cf4" stop-opacity="0.7"/><stop offset="0.43" stop-color="#6e73ee" stop-opacity="0.49"/><stop offset="0.61" stop-color="#8753e9" stop-opacity="0.32"/><stop offset="0.77" stop-color="#993ce5" stop-opacity="0.2"/><stop offset="0.9" stop-color="#a42ee3" stop-opacity="0.13"/><stop offset="1" stop-color="#a829e2" stop-opacity="0.1"/></linearGradient></defs><rect class="cls-1" x="8.88" y="8.88" width="137.75" height="137.75" rx="32.58"/><rect class="cls-2" x="8.88" y="8.88" width="137.75" height="137.75" rx="32.58"/><rect class="cls-3" x="8.88" y="8.88" width="137.75" height="137.75" rx="32.58"/><rect class="cls-4" x="8.88" y="8.88" width="137.75" height="137.75" rx="32.58"/><g id="New_lines" data-name="New lines"><polygon class="cls-5" points="53.35 63.21 49.25 68.86 81.27 92.1 81.49 92.26 85.59 86.61 53.57 63.37 53.35 63.21"/><polygon class="cls-5" points="74.27 63.37 74.05 63.21 69.95 68.86 101.97 92.1 102.19 92.26 106.29 86.61 74.27 63.37"/><path class="cls-5" d="M77.78,34.29c-17.35,0-31.48,10.79-31.48,24.06v.27h7v-.27c0-9.42,11-17.08,24.5-17.08s24.51,7.66,24.51,17.08v.27h7v-.27C109.27,45.08,95.14,34.29,77.78,34.29Z"/><path class="cls-5" d="M102.23,97.16c0,9.42-11,17.08-24.51,17.08s-24.5-7.66-24.5-17.08v-.27h-7v.27c0,13.26,14.13,24,31.48,24s31.49-10.79,31.49-24v-.27h-7Z"/></g></svg>
\ No newline at end of file
diff --git a/packages/playground/public/eventcatalog-logo.png b/packages/playground/public/eventcatalog-logo.png
new file mode 100644
index 000000000..6bba78c43
Binary files /dev/null and b/packages/playground/public/eventcatalog-logo.png differ
diff --git a/packages/playground/public/og-image.png b/packages/playground/public/og-image.png
new file mode 100644
index 000000000..c795bb619
Binary files /dev/null and b/packages/playground/public/og-image.png differ
diff --git a/packages/playground/public/openapi.svg b/packages/playground/public/openapi.svg
new file mode 100644
index 000000000..0dc0f545e
--- /dev/null
+++ b/packages/playground/public/openapi.svg
@@ -0,0 +1 @@
+<svg viewBox="0 0 256 256" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid" fill="#000000"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"> <g> <path d="M127.059657,255.996921 C58.8506544,255.526472 -0.457073619,198.918442 0.00265506057,126.998303 C0.444649399,57.7958628 57.9516598,-0.468967577 129.11002,0.00284555012 C198.267128,0.462386081 256.613109,57.8667711 255.995136,128.194199 C256.568091,197.883453 197.934268,256.489189 127.059657,255.996921 Z M127.059657,255.996921 C58.8506544,255.526472 -0.457073619,198.918442 0.00265506057,126.998303 C0.444649399,57.7958628 57.9516598,-0.468967577 129.11002,0.00284555012 C198.267128,0.462386081 256.613109,57.8667711 255.995136,128.194199 C256.568091,197.883453 197.934268,256.489189 127.059657,255.996921 Z" fill="#FFFFFF"> </path> <path d="M127.184644,238.997327 C68.0323765,238.589271 16.6036091,189.498744 17.0023028,127.131428 C17.3860285,67.1185953 67.2554,16.5917106 128.963117,17.0024872 C188.934544,17.4010221 239.531905,67.1825241 238.995778,128.169251 C239.492444,188.602381 188.64743,239.424426 127.184644,238.997327 Z M127.184644,238.997327 C68.0323765,238.589271 16.6036091,189.498744 17.0023028,127.131428 C17.3860285,67.1185953 67.2554,16.5917106 128.963117,17.0024872 C188.934544,17.4010221 239.531905,67.1825241 238.995778,128.169251 C239.492444,188.602381 188.64743,239.424426 127.184644,238.997327 Z" fill="#49A32B"> </path> <path d="M169.327319,127.956161 C169.042723,133.246373 164.421106,137.639224 159.866213,136.872586 C159.844426,136.872586 159.821277,136.872586 159.798128,136.872586 C154.753021,136.879395 150.658383,132.794288 150.652936,127.749182 C150.824511,122.690458 155.019915,118.703395 160.08,118.789182 C165.125106,118.813692 169.59966,123.077182 169.327319,127.956161 Z M88.2011915,179.220161 C90.1034894,179.27599 92.0071489,179.235139 94.2008511,179.235139 L94.2008511,193.021012 C80.5661277,195.326373 69.3348085,191.455054 66.5787234,179.929607 C65.6350638,175.69199 65.0549787,171.380841 64.8425532,167.04382 C64.5497872,162.452161 65.0563404,157.808756 64.706383,153.225267 C63.7368511,140.613182 62.1028085,136.30748 50,135.711054 L50,120.014714 C50.8674043,119.81182 51.7470638,119.662033 52.6321702,119.562629 C59.2677447,119.23582 62.0646809,117.201437 63.5489362,110.665267 C64.2243404,106.992756 64.6246809,103.275309 64.7431489,99.5428839 C65.268766,92.3258627 65.0822128,84.991735 66.2845957,77.8918201 C68.0221277,67.6245861 74.3962553,62.6366712 84.9249362,62.0783733 C87.9206809,61.9176925 90.9259574,62.0538627 94.3206809,62.0538627 L94.3206809,76.1447563 C92.9235745,76.2441605 91.6435745,76.4470542 90.3717447,76.4089265 C81.7916596,76.146118 81.3477447,79.0683308 80.7213617,86.1709691 C80.3305532,90.6250967 80.8697872,95.1554797 80.5661277,99.6245861 C80.2488511,104.071905 79.6537872,108.496075 78.7850213,112.869863 C77.547234,119.208586 73.6500426,123.922799 68.2495319,127.92348 C78.7332766,134.745607 79.9261277,145.346458 80.6069787,156.110714 C80.9732766,161.895224 80.8057872,167.720586 81.3926809,173.476501 C81.8502128,177.944246 83.5877447,179.08399 88.2011915,179.220161 Z M97.0372766,118.789182 C97.0917447,118.789182 97.1448511,118.789182 97.1993191,118.789182 C102.211745,118.872246 106.209702,123.002288 106.126638,128.016075 C106.126638,128.180841 106.121191,128.344246 106.11166,128.50765 C105.829787,133.407054 101.630298,137.149012 96.7308936,136.867139 C96.5334468,136.871224 96.3373617,136.867139 96.1399149,136.857607 C91.1506383,136.609778 87.3065532,132.36399 87.554383,127.374714 C87.8022128,122.385437 92.048,118.541352 97.0372766,118.789182 Z M128.273362,118.789182 C133.755574,118.746969 137.396766,122.29965 137.425362,127.719224 C137.455319,133.284501 134.003404,136.845352 128.556596,136.868501 C123.017191,136.893012 119.370553,133.389352 119.340596,128.002458 C119.324255,127.727395 119.32017,127.452331 119.32834,127.177267 C119.482213,122.390884 123.486979,118.635309 128.273362,118.789182 Z M193.673191,111.92348 C195.131574,117.370288 197.970723,119.284841 203.704851,119.546288 C204.644426,119.589863 205.579915,119.749182 206.868085,119.892161 L206.868085,135.584416 C206.170894,135.813182 205.456,135.984756 204.730213,136.096416 C197.046128,136.574373 193.54383,139.726714 192.76766,147.431224 C192.272,152.349692 192.312851,157.322629 191.972426,162.258799 C191.829447,167.678373 191.336511,173.082969 190.49634,178.438544 C188.535489,188.142033 182.477277,192.982884 172.467404,193.573863 C169.245617,193.764501 166.000681,193.60382 162.526979,193.60382 L162.526979,179.578288 C164.396596,179.462544 166.046979,179.303224 167.701447,179.263735 C173.682043,179.120756 175.796766,177.192586 176.089532,171.252841 C176.413617,164.727565 176.555234,158.194118 176.846638,151.66748 C177.270128,142.233607 179.853277,133.806033 188.641702,127.922118 C183.612936,124.336756 179.575489,119.994288 178.529702,114.138969 C177.264681,107.041778 176.85617,99.7879903 176.175319,92.5913946 C175.838979,88.9937776 175.855319,85.3648414 175.504,81.7699478 C175.125447,77.8890967 172.459234,76.5464584 168.926979,76.4593095 C166.903489,76.4102882 164.87183,76.4497776 162.284596,76.4497776 L162.284596,62.7537776 C178.793872,60.0126712 190.198128,65.5057776 191.257532,81.3015222 C191.701447,87.9343733 191.636085,94.5985435 192.060936,101.231395 C192.247489,104.839905 192.786723,108.421182 193.673191,111.92348 Z" fill="#FFFFFF"> </path> </g> </g></svg>
\ No newline at end of file
diff --git a/packages/playground/src/App.tsx b/packages/playground/src/App.tsx
new file mode 100644
index 000000000..a0aa57ad8
--- /dev/null
+++ b/packages/playground/src/App.tsx
@@ -0,0 +1,1097 @@
+import { useState, useCallback, useRef, useEffect, memo } from "react";
+import { useParams } from "react-router-dom";
+import { useStore } from "@nanostores/react";
+import { Editor } from "./components/Editor";
+import { Visualizer } from "./components/Visualizer";
+import { TabBar } from "./components/TabBar";
+import { StatusBar } from "./components/StatusBar";
+import { CommandPalette } from "./components/CommandPalette";
+import type { EditorHandle } from "./components/Editor";
+import { useDslParser, compileDsl } from "./hooks/useDslParser";
+import { getErrorsForFile } from "./monaco/ec-diagnostics";
+import { examples } from "./examples/index";
+import { createZipBlob } from "./utils/zip";
+import { normalizeCompiledCatalogFiles } from "./utils/catalog-export";
+import { track } from "./utils/analytics";
+import { NextStepsGuide } from "./components/NextStepsGuide";
+import {
+  $theme,
+  $workspace,
+  loadWorkspace,
+  saveWorkspace,
+  clearWorkspace,
+  loadDraft as loadDraftStore,
+  saveDraft as saveDraftStore,
+  clearDraft as clearDraftStore,
+  getSpecFile,
+  peekDraft,
+  peekWorkspaceFiles,
+} from "./stores/workspace";
+import {
+  ChevronDown,
+  AlignLeft,
+  Check,
+  Download,
+  Share2,
+  Sun,
+  Moon,
+  X,
+  Copy,
+  FolderDown,
+} from "lucide-react";
+import { TemplateDropdown } from "./components/TemplateDropdown";
+import { formatEc } from "@eventcatalog/language-server/browser";
+
+const MIN_PANEL_PCT = 20;
+const MAX_PANEL_PCT = 80;
+const DEFAULT_SPLIT = 45;
+const EXPORT_EXTRACT_DIR = "./ec-model";
+
+interface ExportResult {
+  fileName: string;
+  isZip: boolean;
+  ecFiles: string[];
+}
+
+const AppHeader = memo(function AppHeader({
+  selectedExample,
+  templateUnselected,
+  onExampleChange,
+  loadedFromUrl,
+  workspaceTitle,
+  onExport,
+  onExportCatalog,
+  exportRecentlyDownloaded,
+  onShare,
+  vizTheme,
+  onToggleVizTheme,
+}: {
+  selectedExample: number;
+  templateUnselected: boolean;
+  onExampleChange: (index: number) => void;
+  loadedFromUrl: boolean;
+  workspaceTitle?: string;
+  onExport: () => void;
+  onExportCatalog: () => void;
+  exportRecentlyDownloaded: boolean;
+  onShare: () => void;
+  vizTheme: "light" | "dark";
+  onToggleVizTheme: () => void;
+}) {
+  const currentName = workspaceTitle
+    ? workspaceTitle
+    : loadedFromUrl
+      ? "Shared Link"
+      : templateUnselected
+        ? ""
+        : (examples[selectedExample]?.name ?? "");
+
+  const [exportOpen, setExportOpen] = useState(false);
+  const exportRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!exportOpen) return;
+    const onClick = (e: MouseEvent) => {
+      if (exportRef.current && !exportRef.current.contains(e.target as Node)) {
+        setExportOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", onClick);
+    return () => document.removeEventListener("mousedown", onClick);
+  }, [exportOpen]);
+
+  return (
+    <header className="header">
+      <div className="header-logo">
+        <a
+          href="/"
+          className="header-home-link"
+          aria-label="Go to EventCatalog Compass homepage"
+        >
+          <h1>
+            EventCatalog Compass
+            {currentName ? (
+              <span className="header-template-name"> — {currentName}</span>
+            ) : (
+              ""
+            )}
+          </h1>
+        </a>
+      </div>
+      <div className="header-actions">
+        <TemplateDropdown
+          selectedExample={selectedExample}
+          templateUnselected={templateUnselected}
+          loadedFromUrl={loadedFromUrl}
+          onSelectExample={onExampleChange}
+        />
+        <button
+          className="header-icon-btn"
+          onClick={onToggleVizTheme}
+          title={
+            vizTheme === "light"
+              ? "Switch to dark theme"
+              : "Switch to light theme"
+          }
+        >
+          {vizTheme === "light" ? <Moon size={15} /> : <Sun size={15} />}
+        </button>
+        <button
+          className="header-icon-btn"
+          onClick={onShare}
+          title="Share model link"
+        >
+          <Share2 size={15} />
+        </button>
+        <div className="export-dropdown-wrapper" ref={exportRef}>
+          <button
+            className="export-btn-header"
+            onClick={() => setExportOpen((v) => !v)}
+          >
+            {exportRecentlyDownloaded ? (
+              <Check size={14} />
+            ) : (
+              <Download size={14} />
+            )}
+            Export
+            <ChevronDown size={12} />
+          </button>
+          {exportOpen && (
+            <div className="export-dropdown">
+              <button
+                className="export-dropdown-item"
+                onClick={() => {
+                  setExportOpen(false);
+                  onExport();
+                }}
+              >
+                <Download size={14} />
+                <div>
+                  <span className="export-dropdown-item-title">
+                    Download DSL files
+                  </span>
+                  <span className="export-dropdown-item-desc">
+                    Export .ec files for use with the CLI
+                  </span>
+                </div>
+              </button>
+              <button
+                className="export-dropdown-item"
+                onClick={() => {
+                  setExportOpen(false);
+                  onExportCatalog();
+                }}
+              >
+                <FolderDown size={14} />
+                <div>
+                  <span className="export-dropdown-item-title">
+                    Download as Catalog
+                  </span>
+                  <span className="export-dropdown-item-desc">
+                    Ready-to-run project — just npm install and start
+                  </span>
+                </div>
+              </button>
+            </div>
+          )}
+        </div>
+      </div>
+    </header>
+  );
+});
+
+const ShareLinkModal = memo(function ShareLinkModal({
+  shareUrl,
+  onClose,
+}: {
+  shareUrl: string;
+  onClose: () => void;
+}) {
+  const [copied, setCopied] = useState(false);
+
+  const copy = useCallback(() => {
+    navigator.clipboard.writeText(shareUrl).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    });
+  }, [shareUrl]);
+
+  return (
+    <div className="export-modal-overlay" onClick={onClose} role="presentation">
+      <div
+        className="export-modal"
+        role="dialog"
+        aria-modal="true"
+        aria-label="Share model"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="export-modal-header">
+          <h2>Share this model</h2>
+          <button
+            className="export-modal-close"
+            onClick={onClose}
+            title="Close"
+          >
+            <X size={16} />
+          </button>
+        </div>
+
+        <p className="export-modal-lead">
+          Share this URL with your team so they can open the same model in
+          EventCatalog Compass.
+        </p>
+
+        <div className="command-row">
+          <code>{shareUrl}</code>
+          <button className="command-copy-btn" onClick={copy}>
+            {copied ? <Check size={13} /> : <Copy size={13} />}
+            {copied ? "Copied" : "Copy"}
+          </button>
+        </div>
+
+        <p className="share-modal-note">Data is local and not stored.</p>
+      </div>
+    </div>
+  );
+});
+
+const ExportHelpModal = memo(function ExportHelpModal({
+  exportResult,
+  onClose,
+}: {
+  exportResult: ExportResult;
+  onClose: () => void;
+}) {
+  const [copiedValue, setCopiedValue] = useState<string>("");
+  const hasMultiple = exportResult.isZip;
+  const importedFiles = hasMultiple
+    ? exportResult.ecFiles
+        .map((file) => `${EXPORT_EXTRACT_DIR}/${file}`)
+        .join(" ")
+    : `./${exportResult.ecFiles[0] ?? "main.ec"}`;
+  const unzipCommand = `unzip ${exportResult.fileName} -d ${EXPORT_EXTRACT_DIR}`;
+  const createCommand = `npx @eventcatalog/cli --dir ./my-catalog import ${importedFiles}`;
+  const updateCommand = `npx @eventcatalog/cli --dir ./existing-catalog import ${importedFiles}`;
+
+  const copy = useCallback((value: string) => {
+    navigator.clipboard.writeText(value).then(() => {
+      setCopiedValue(value);
+      setTimeout(() => setCopiedValue(""), 2000);
+    });
+  }, []);
+
+  return (
+    <div className="export-modal-overlay" onClick={onClose} role="presentation">
+      <div
+        className="export-modal"
+        role="dialog"
+        aria-modal="true"
+        aria-label="Import into EventCatalog"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="export-modal-header">
+          <h2>Export downloaded</h2>
+          <button
+            className="export-modal-close"
+            onClick={onClose}
+            title="Close"
+          >
+            <X size={16} />
+          </button>
+        </div>
+        <p className="export-modal-lead">
+          Your model is saved as <code>{exportResult.fileName}</code>. Run these
+          commands to turn it into an EventCatalog project.
+        </p>
+
+        {hasMultiple && (
+          <div className="command-section">
+            <p>1. Unzip the model files</p>
+            <div className="command-row">
+              <code>{unzipCommand}</code>
+              <button
+                className="command-copy-btn"
+                onClick={() => copy(unzipCommand)}
+              >
+                {copiedValue === unzipCommand ? (
+                  <Check size={13} />
+                ) : (
+                  <Copy size={13} />
+                )}
+                Copy
+              </button>
+            </div>
+          </div>
+        )}
+
+        <div className="command-section">
+          <p>
+            {hasMultiple ? "2" : "1"}. Import into a new EventCatalog project
+          </p>
+          <div className="command-row">
+            <code>{createCommand}</code>
+            <button
+              className="command-copy-btn"
+              onClick={() => copy(createCommand)}
+            >
+              {copiedValue === createCommand ? (
+                <Check size={13} />
+              ) : (
+                <Copy size={13} />
+              )}
+              Copy
+            </button>
+          </div>
+        </div>
+
+        <div className="command-section">
+          <p>
+            {hasMultiple ? "3" : "2"}. Import into an existing EventCatalog
+            project
+          </p>
+          <div className="command-row">
+            <code>{updateCommand}</code>
+            <button
+              className="command-copy-btn"
+              onClick={() => copy(updateCommand)}
+            >
+              {copiedValue === updateCommand ? (
+                <Check size={13} />
+              ) : (
+                <Copy size={13} />
+              )}
+              Copy
+            </button>
+          </div>
+        </div>
+
+        <p className="export-modal-tip">
+          Tip: add <code>--dry-run</code> first to preview changes before
+          writing files.
+        </p>
+      </div>
+    </div>
+  );
+});
+
+const CatalogExportModal = memo(function CatalogExportModal({
+  organizationName,
+  onOrganizationNameChange,
+  onCreateCatalog,
+  isExporting,
+  onClose,
+}: {
+  organizationName: string;
+  onOrganizationNameChange: (value: string) => void;
+  onCreateCatalog: () => void;
+  isExporting: boolean;
+  onClose: () => void;
+}) {
+  return (
+    <div className="export-modal-overlay" onClick={onClose} role="presentation">
+      <div
+        className="export-modal export-modal--compact"
+        role="dialog"
+        aria-modal="true"
+        aria-label="Export catalog"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="export-modal-header">
+          <h2>Customize Your Catalog</h2>
+          <button
+            className="export-modal-close"
+            onClick={onClose}
+            title="Close"
+          >
+            <X size={16} />
+          </button>
+        </div>
+        <p className="export-modal-lead">
+          We will customize your catalog for your organization.
+        </p>
+        <form
+          className="catalog-export-form"
+          onSubmit={(event) => {
+            event.preventDefault();
+            onCreateCatalog();
+          }}
+        >
+          <label htmlFor="organization-name" className="catalog-export-label">
+            Organization Name
+          </label>
+          <input
+            id="organization-name"
+            className="catalog-export-input"
+            type="text"
+            value={organizationName}
+            onChange={(e) => onOrganizationNameChange(e.target.value)}
+            placeholder="My Organization"
+            autoFocus
+            disabled={isExporting}
+          />
+          <button
+            className="catalog-export-submit"
+            type="submit"
+            disabled={isExporting || organizationName.trim().length === 0}
+          >
+            {isExporting ? "Creating Zip..." : "Create Catalog Zip"}
+          </button>
+        </form>
+      </div>
+    </div>
+  );
+});
+
+let newFileCounter = 1;
+
+function getCodeFromUrl(): string | null {
+  try {
+    const params = new URLSearchParams(window.location.search);
+    const code = params.get("code");
+    if (code) return decodeURIComponent(escape(atob(code)));
+  } catch {}
+  return null;
+}
+
+function isNewRoute(): boolean {
+  const path = window.location.pathname.replace(/\/+$/, "");
+  return path.endsWith("/new") || path === "/playground";
+}
+
+function getBasePathname(): string {
+  // Strip /new or any workspace ID suffix so share links use the base /playground path
+  const basePath = window.location.pathname
+    .replace(/\/new\/?$/, "")
+    .replace(/\/playground\/[^/]+\/?$/, "/playground");
+  return basePath || "/playground";
+}
+
+function hasExampleHash(): boolean {
+  return /example=\d+/.test(window.location.hash);
+}
+
+function getInitialExample(): number {
+  // Restore from URL hash (e.g. #example=3)
+  const hash = window.location.hash;
+  const match = hash.match(/example=(\d+)/);
+  if (match) {
+    const idx = Number(match[1]);
+    if (idx >= 0 && idx < examples.length) return idx;
+  }
+  return 0;
+}
+
+function getInitialState(workspaceId?: string): { files: Record<string, string>; activeFile: string } {
+  const defaultState = { files: { "main.ec": "" }, activeFile: "main.ec" };
+  if (workspaceId) {
+    return peekWorkspaceFiles(workspaceId) ?? defaultState;
+  }
+  const code = getCodeFromUrl();
+  if (code) return { files: { "main.ec": code }, activeFile: "main.ec" };
+  if (hasExampleHash()) {
+    const source = examples[getInitialExample()].source;
+    return { files: { ...source }, activeFile: Object.keys(source)[0] };
+  }
+  if (isNewRoute()) return defaultState;
+  const draft = peekDraft();
+  if (draft) return draft;
+  const source = examples[getInitialExample()].source;
+  return { files: { ...source }, activeFile: Object.keys(source)[0] };
+}
+
+function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+
+export default function App() {
+  const { workspaceId } = useParams<{ workspaceId?: string }>();
+  const ws = useStore($workspace);
+  const vizTheme = useStore($theme);
+
+  // Load workspace store on mount (once)
+  const wsLoadedRef = useRef(false);
+  if (!wsLoadedRef.current && workspaceId) {
+    loadWorkspace(workspaceId);
+    wsLoadedRef.current = true;
+  }
+
+  const [selectedExample, setSelectedExample] = useState(getInitialExample);
+  const [loadedFromUrl, setLoadedFromUrl] = useState(
+    () => getCodeFromUrl() !== null,
+  );
+  const [templateUnselected, setTemplateUnselected] = useState(
+    () => isNewRoute() && getCodeFromUrl() === null && !hasExampleHash(),
+  );
+  const [initialState] = useState(() => getInitialState(workspaceId));
+  const [files, setFiles] = useState<Record<string, string>>(
+    initialState.files,
+  );
+  const [activeFile, setActiveFile] = useState(initialState.activeFile);
+  // Track whether the current session is user-authored content that should be saved
+  const isUserDraft = useRef(
+    !!workspaceId || !!getCodeFromUrl() || isNewRoute() || !!peekDraft(),
+  );
+  const [activeVisualizer, setActiveVisualizer] = useState<string | undefined>(
+    undefined,
+  );
+  const { graph, errors, fileOffsets } = useDslParser(files, activeVisualizer);
+  const [splitPct, setSplitPct] = useState(DEFAULT_SPLIT);
+
+  // Workspace-derived values from the store
+  const showGuide = workspaceId ? ws.showGuide : false;
+  const workspaceKind = workspaceId ? ws.kind : undefined;
+  const workspaceSpecFile = workspaceId ? getSpecFile(ws.files) : "spec.yml";
+  const workspaceServiceNames = workspaceId ? ws.services : [];
+
+  // Set data-theme on mount and when theme changes
+  useEffect(() => {
+    document.documentElement.setAttribute("data-theme", vizTheme);
+  }, [vizTheme]);
+
+  // Set document title based on workspace
+  useEffect(() => {
+    if (workspaceId && ws.title) {
+      document.title = `EventCatalog Compass — ${ws.title}`;
+    } else {
+      document.title = "EventCatalog Compass";
+    }
+    return () => {
+      document.title = "EventCatalog Compass";
+    };
+  }, [workspaceId, ws.title]);
+
+  const [cmdkOpen, setCmdkOpen] = useState(false);
+  const [focusRequest, setFocusRequest] = useState<{
+    nodeId: string;
+    requestId: number;
+  } | null>(null);
+  const [fitRequestId, setFitRequestId] = useState(0);
+  const editorRef = useRef<EditorHandle>(null);
+  const isDragging = useRef(false);
+  const mainRef = useRef<HTMLDivElement>(null);
+
+  const toggleVizTheme = useCallback(() => {
+    const next = $theme.get() === "light" ? "dark" : "light";
+    $theme.set(next);
+  }, []);
+
+  const loadExample = useCallback(
+    (idx: number) => {
+      setSelectedExample(idx);
+      setTemplateUnselected(false);
+      setLoadedFromUrl(false);
+      isUserDraft.current = false;
+      if (workspaceId) {
+        clearWorkspace(workspaceId);
+      } else {
+        clearDraftStore();
+      }
+      const url = new URL(window.location.href);
+      url.pathname = getBasePathname();
+      url.search = "";
+      url.hash = `example=${idx}`;
+      window.history.replaceState(null, "", url.toString());
+      const newFiles = { ...examples[idx].source };
+      setFiles(newFiles);
+      setActiveFile(Object.keys(newFiles)[0]);
+      setActiveVisualizer(undefined);
+      track("example_loaded", { example: examples[idx].name, index: idx });
+    },
+    [workspaceId],
+  );
+
+  const handleExampleChange = useCallback(
+    (index: number) => {
+      loadExample(index);
+    },
+    [loadExample],
+  );
+
+  const [shareUrl, setShareUrl] = useState<string | null>(null);
+  const [exportRecentlyDownloaded, setExportRecentlyDownloaded] =
+    useState(false);
+  const [latestExport, setLatestExport] = useState<ExportResult | null>(null);
+  const [showCatalogExport, setShowCatalogExport] = useState(false);
+  const [catalogOrganizationName, setCatalogOrganizationName] =
+    useState("My Organization");
+  const [isCatalogExporting, setIsCatalogExporting] = useState(false);
+  const handleShare = useCallback(() => {
+    const allContent = Object.values(files).join("\n");
+    const encoded = btoa(unescape(encodeURIComponent(allContent)));
+    const url = new URL(window.location.href);
+    url.pathname = getBasePathname();
+    url.search = `?code=${encodeURIComponent(encoded)}`;
+    url.hash = "";
+    setShareUrl(url.toString());
+    track("share_link_created");
+  }, [files]);
+
+  const handleExportForImport = useCallback(() => {
+    const ecFiles = Object.entries(files)
+      .filter(([filename]) => filename.toLowerCase().endsWith(".ec"))
+      .map(([filename, content]) => ({ name: filename, content }));
+
+    const ecFileNames = ecFiles.map((file) => file.name);
+
+    if (ecFiles.length <= 1) {
+      const oneFile = ecFiles[0] ?? { name: "main.ec", content: "" };
+      const blob = new Blob([oneFile.content], {
+        type: "text/plain;charset=utf-8",
+      });
+      downloadBlob(blob, oneFile.name);
+      setLatestExport({
+        fileName: oneFile.name,
+        isZip: false,
+        ecFiles: [oneFile.name],
+      });
+    } else {
+      const zip = createZipBlob(ecFiles);
+      downloadBlob(zip, "ec-model.zip");
+      setLatestExport({
+        fileName: "ec-model.zip",
+        isZip: true,
+        ecFiles: ecFileNames,
+      });
+    }
+
+    track("ec_files_exported", { file_count: ecFiles.length });
+    setExportRecentlyDownloaded(true);
+    setTimeout(() => setExportRecentlyDownloaded(false), 2000);
+  }, [files]);
+
+  const handleOpenCatalogExport = useCallback(() => {
+    setShowCatalogExport(true);
+    track("catalog_export_opened");
+  }, []);
+
+  const handleExportCatalog = useCallback(async () => {
+    const organizationName = catalogOrganizationName.trim();
+    if (!organizationName) return;
+    const organizationSlug =
+      organizationName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "my-organization";
+    const catalogFolderName = `${organizationSlug}-catalog`;
+
+    setIsCatalogExporting(true);
+
+    try {
+      const compiled = normalizeCompiledCatalogFiles(await compileDsl(files));
+
+      if (compiled.length === 0) {
+        return;
+      }
+
+      const catalogId = crypto.randomUUID();
+
+      const packageJson = JSON.stringify(
+        {
+          name: catalogFolderName,
+          version: "0.1.0",
+          private: true,
+          scripts: {
+            dev: "eventcatalog dev",
+            build: "eventcatalog build",
+            start: "eventcatalog start",
+            preview: "eventcatalog preview",
+          },
+          dependencies: {
+            "@eventcatalog/core": "latest",
+          },
+        },
+        null,
+        2,
+      );
+
+      const configJs = `/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
+export default {
+  title: 'EventCatalog',
+  tagline: 'Discover, Explore and Document your Event Driven Architectures.',
+  organizationName: ${JSON.stringify(organizationName)},
+  homepageLink: 'https://eventcatalog.dev/',
+  output: 'static',
+  trailingSlash: false,
+  base: '/',
+  navigation: {
+    pages: ['list:all'],
+  },
+  logo: {
+    alt: 'EventCatalog Logo',
+    src: '/logo.png',
+    text: 'EventCatalog',
+  },
+  cId: '${catalogId}',
+};
+`;
+      const readmeMd = `# ${organizationName} Catalog
+
+Welcome to your generated EventCatalog project.
+
+## Helpful Links
+
+- [Fundamentals of EventCatalog](https://www.eventcatalog.dev/docs/development/getting-started/fundamentals)
+- [Documenting your first domain](https://www.eventcatalog.dev/docs/development/guides/domains/creating-domains/adding-domains)
+- [Documenting services](https://www.eventcatalog.dev/docs/development/guides/services/introduction)
+- [Integrating with OpenAPI and AsyncAPI](https://www.eventcatalog.dev/integrations)
+- [Join the Discord community](https://eventcatalog.dev/discord)
+`;
+
+      const zipFiles = [
+        { name: `${catalogFolderName}/package.json`, content: packageJson },
+        {
+          name: `${catalogFolderName}/eventcatalog.config.js`,
+          content: configJs,
+        },
+        { name: `${catalogFolderName}/README.md`, content: readmeMd },
+        ...compiled.map((file) => ({
+          name: `${catalogFolderName}/${file.path}`,
+          content: file.content,
+        })),
+      ];
+
+      const blob = createZipBlob(zipFiles);
+      downloadBlob(blob, `${catalogFolderName}.zip`);
+
+      setShowCatalogExport(false);
+      setExportRecentlyDownloaded(true);
+      setTimeout(() => setExportRecentlyDownloaded(false), 2000);
+    } catch (err) {
+      console.error("Catalog export error:", err);
+    } finally {
+      setIsCatalogExporting(false);
+    }
+  }, [catalogOrganizationName, files]);
+
+  useEffect(() => {
+    if (!latestExport && !shareUrl && !showCatalogExport) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        setLatestExport(null);
+        setShareUrl(null);
+        setShowCatalogExport(false);
+      }
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [latestExport, shareUrl, showCatalogExport]);
+
+  // Persist files to localStorage so user work survives page refreshes
+  useEffect(() => {
+    if (!isUserDraft.current) return;
+    if (workspaceId) {
+      $workspace.setKey("files", files);
+      $workspace.setKey("activeFile", activeFile);
+      saveWorkspace();
+    } else {
+      saveDraftStore(files, activeFile);
+    }
+  }, [files, activeFile, workspaceId]);
+
+  const handleFileChange = useCallback(
+    (value: string) => {
+      isUserDraft.current = true;
+      setFiles((prev) => ({ ...prev, [activeFile]: value }));
+    },
+    [activeFile],
+  );
+
+  const handleApplyGuideStep = useCallback(
+    (transform: (content: string) => string) => {
+      isUserDraft.current = true;
+      setFiles((prev) => {
+        const mainContent = prev["main.ec"] ?? "";
+        return { ...prev, "main.ec": transform(mainContent) };
+      });
+      setActiveFile("main.ec");
+      requestAnimationFrame(() => {
+        editorRef.current?.revealLine(99999);
+      });
+    },
+    [],
+  );
+
+  const handleDismissGuide = useCallback(() => {
+    $workspace.setKey("showGuide", false);
+    saveWorkspace();
+  }, []);
+
+  const handleAddFile = useCallback(() => {
+    isUserDraft.current = true;
+    const name = `file${newFileCounter++}.ec`;
+    setFiles((prev) => ({ ...prev, [name]: "" }));
+    setActiveFile(name);
+  }, []);
+
+  const handleCloseFile = useCallback(
+    (filename: string) => {
+      setFiles((prev) => {
+        const next = { ...prev };
+        delete next[filename];
+        return next;
+      });
+      if (activeFile === filename) {
+        const remaining = Object.keys(files).filter((f) => f !== filename);
+        setActiveFile(remaining[0]);
+      }
+    },
+    [activeFile, files],
+  );
+
+  const handleFormat = useCallback(() => {
+    setFiles((prev) => ({ ...prev, [activeFile]: formatEc(prev[activeFile]) }));
+  }, [activeFile]);
+
+  // Cmd+K / Ctrl+K to open command palette
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+        e.preventDefault();
+        setCmdkOpen((v) => !v);
+      }
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, []);
+
+  const handleGoToLine = useCallback((line: number) => {
+    editorRef.current?.revealLine(line);
+  }, []);
+
+  const handleSwitchFileAndLine = useCallback(
+    (filename: string, line: number) => {
+      setActiveFile(filename);
+      // Wait for editor to update with new file content before revealing line
+      requestAnimationFrame(() => {
+        editorRef.current?.revealLine(line);
+      });
+    },
+    [],
+  );
+
+  const handleFocusResource = useCallback((nodeId: string) => {
+    setFocusRequest((prev) => ({
+      nodeId,
+      requestId: (prev?.requestId ?? 0) + 1,
+    }));
+  }, []);
+
+  const handleFitScreen = useCallback(() => {
+    setFitRequestId((prev) => prev + 1);
+  }, []);
+
+  const activeFileErrors = getErrorsForFile(errors, activeFile, fileOffsets);
+
+  const onMouseDown = useCallback((e: React.MouseEvent) => {
+    e.preventDefault();
+    isDragging.current = true;
+    document.body.classList.add("resizing");
+  }, []);
+
+  useEffect(() => {
+    const onMouseMove = (e: MouseEvent) => {
+      if (!isDragging.current || !mainRef.current) return;
+      const rect = mainRef.current.getBoundingClientRect();
+      const pct = ((e.clientX - rect.left) / rect.width) * 100;
+      setSplitPct(Math.min(MAX_PANEL_PCT, Math.max(MIN_PANEL_PCT, pct)));
+    };
+
+    const onMouseUp = () => {
+      if (isDragging.current) {
+        isDragging.current = false;
+        document.body.classList.remove("resizing");
+      }
+    };
+
+    window.addEventListener("mousemove", onMouseMove);
+    window.addEventListener("mouseup", onMouseUp);
+    return () => {
+      window.removeEventListener("mousemove", onMouseMove);
+      window.removeEventListener("mouseup", onMouseUp);
+    };
+  }, []);
+
+  const fileNames = Object.keys(files);
+
+  const workspaceTitle = workspaceId ? ws.title : undefined;
+
+  return (
+    <div className="app">
+      <AppHeader
+        selectedExample={selectedExample}
+        templateUnselected={templateUnselected}
+        onExampleChange={handleExampleChange}
+        loadedFromUrl={loadedFromUrl}
+        workspaceTitle={workspaceTitle}
+        onExport={handleExportForImport}
+        onExportCatalog={handleOpenCatalogExport}
+        exportRecentlyDownloaded={exportRecentlyDownloaded}
+        onShare={handleShare}
+        vizTheme={vizTheme}
+        onToggleVizTheme={toggleVizTheme}
+      />
+      <div className="main" ref={mainRef}>
+        <div
+          className="editor-pane"
+          style={{ width: `${splitPct}%`, position: "relative" }}
+        >
+          <div className="pane-header">
+            <TabBar
+              files={fileNames}
+              activeFile={activeFile}
+              onSelectFile={setActiveFile}
+              onCloseFile={handleCloseFile}
+              onAddFile={handleAddFile}
+            />
+            <button
+              className="format-btn"
+              onClick={handleFormat}
+              title="Format code (Shift+Alt+F)"
+            >
+              <AlignLeft size={14} />
+            </button>
+            {errors.length > 0 && (
+              <span className="error-count">
+                {errors.length} error{errors.length !== 1 ? "s" : ""}
+              </span>
+            )}
+          </div>
+          <Editor
+            ref={editorRef}
+            value={files[activeFile] ?? ""}
+            onChange={handleFileChange}
+            errors={activeFileErrors}
+            allFiles={files}
+            onFormat={handleFormat}
+            onCommandPalette={() => setCmdkOpen(true)}
+          />
+          {showGuide && workspaceId && workspaceKind && (
+            <NextStepsGuide
+              specKind={workspaceKind}
+              specFile={workspaceSpecFile}
+              serviceNames={workspaceServiceNames}
+              onApplyStep={handleApplyGuideStep}
+              onExportCatalog={handleOpenCatalogExport}
+              onDismiss={handleDismissGuide}
+            />
+          )}
+        </div>
+        <div className="resize-handle" onMouseDown={onMouseDown}>
+          <div className="resize-handle-line" />
+        </div>
+        <div
+          className="visualizer-pane"
+          style={{ width: `${100 - splitPct}%` }}
+        >
+          {graph.empty ? (
+            <div
+              style={{
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                height: "100%",
+                color: "rgb(var(--ec-page-text-muted))",
+                flexDirection: "column",
+                gap: "8px",
+              }}
+            >
+              <p style={{ fontSize: "16px", fontWeight: 500 }}>
+                No visualizer block found
+              </p>
+              <p style={{ fontSize: "13px" }}>
+                Add a <code>visualizer</code> block to see the architecture
+                diagram
+              </p>
+            </div>
+          ) : (
+            <>
+              {graph.visualizers && graph.visualizers.length > 1 && (
+                <div
+                  style={{
+                    padding: "4px 8px",
+                    borderBottom: "1px solid rgb(var(--ec-page-border))",
+                    display: "flex",
+                    alignItems: "center",
+                    gap: "8px",
+                  }}
+                >
+                  <span
+                    style={{
+                      fontSize: "12px",
+                      color: "rgb(var(--ec-page-text-muted))",
+                    }}
+                  >
+                    View:
+                  </span>
+                  <select
+                    value={graph.activeVisualizer || ""}
+                    onChange={(e) => setActiveVisualizer(e.target.value)}
+                    style={{
+                      fontSize: "12px",
+                      background: "rgb(var(--ec-card-bg))",
+                      color: "rgb(var(--ec-page-text))",
+                      border: "1px solid rgb(var(--ec-page-border))",
+                      borderRadius: "4px",
+                      padding: "2px 6px",
+                    }}
+                  >
+                    {graph.visualizers.map((name) => (
+                      <option key={name} value={name}>
+                        {name}
+                      </option>
+                    ))}
+                  </select>
+                </div>
+              )}
+              <Visualizer
+                graph={graph}
+                focusNodeId={focusRequest?.nodeId ?? null}
+                focusRequestId={focusRequest?.requestId}
+                fitRequestId={fitRequestId}
+              />
+            </>
+          )}
+        </div>
+      </div>
+      <StatusBar
+        nodes={graph.nodes}
+        errorCount={errors.length}
+        onCommandPalette={() => setCmdkOpen(true)}
+      />
+      {shareUrl && (
+        <ShareLinkModal shareUrl={shareUrl} onClose={() => setShareUrl(null)} />
+      )}
+      {latestExport && (
+        <ExportHelpModal
+          exportResult={latestExport}
+          onClose={() => setLatestExport(null)}
+        />
+      )}
+      {showCatalogExport && (
+        <CatalogExportModal
+          organizationName={catalogOrganizationName}
+          onOrganizationNameChange={setCatalogOrganizationName}
+          onCreateCatalog={handleExportCatalog}
+          isExporting={isCatalogExporting}
+          onClose={() => setShowCatalogExport(false)}
+        />
+      )}
+      <CommandPalette
+        open={cmdkOpen}
+        onOpenChange={setCmdkOpen}
+        nodes={graph.nodes}
+        files={files}
+        activeFile={activeFile}
+        onGoToLine={handleGoToLine}
+        onSwitchFile={handleSwitchFileAndLine}
+        onSelectResource={(node) => handleFocusResource(node.id)}
+        onFitScreen={handleFitScreen}
+      />
+    </div>
+  );
+}
diff --git a/packages/playground/src/components/CommandPalette.tsx b/packages/playground/src/components/CommandPalette.tsx
new file mode 100644
index 000000000..13baafcb2
--- /dev/null
+++ b/packages/playground/src/components/CommandPalette.tsx
@@ -0,0 +1,242 @@
+import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
+import { Command } from 'cmdk';
+import type { GraphNode } from '@eventcatalog/language-server/browser';
+import { Globe, Server, Zap, Terminal, Radio, Hash, Search, Maximize } from 'lucide-react';
+
+const TYPE_META: Record<string, { label: string; icon: React.ReactNode; keyword: string }> = {
+  domain: { label: 'Domain', icon: <Globe size={14} />, keyword: 'domain' },
+  service: { label: 'Service', icon: <Server size={14} />, keyword: 'service' },
+  event: { label: 'Event', icon: <Zap size={14} />, keyword: 'event' },
+  command: { label: 'Command', icon: <Terminal size={14} />, keyword: 'command' },
+  query: { label: 'Query', icon: <Search size={14} />, keyword: 'query' },
+  channel: { label: 'Channel', icon: <Radio size={14} />, keyword: 'channel' },
+  container: { label: 'Container', icon: <Hash size={14} />, keyword: 'container' },
+  entity: { label: 'Entity', icon: <Hash size={14} />, keyword: 'entity' },
+  flow: { label: 'Flow', icon: <Zap size={14} />, keyword: 'flow' },
+};
+
+interface CommandPaletteProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  nodes: GraphNode[];
+  files: Record<string, string>;
+  activeFile: string;
+  onGoToLine: (line: number) => void;
+  onSwitchFile: (filename: string, line: number) => void;
+  onSelectResource?: (node: GraphNode) => void;
+  onFitScreen?: () => void;
+}
+
+function findResourceLine(
+  files: Record<string, string>,
+  keyword: string,
+  label: string,
+): { filename: string; line: number } | null {
+  for (const [filename, content] of Object.entries(files)) {
+    const lines = content.split('\n');
+    const pattern = new RegExp(`^\\s*${keyword}\\s+${escapeRegExp(label)}\\s*\\{?\\s*$`);
+    for (let i = 0; i < lines.length; i++) {
+      if (pattern.test(lines[i])) {
+        return { filename, line: i + 1 };
+      }
+    }
+  }
+  return null;
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function CommandPalette({
+  open,
+  onOpenChange,
+  nodes,
+  files,
+  activeFile,
+  onGoToLine,
+  onSwitchFile,
+  onSelectResource,
+  onFitScreen,
+}: CommandPaletteProps) {
+  const [search, setSearch] = useState('');
+  const [mode, setMode] = useState<'commands' | 'goto-line'>('commands');
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // Reset state and force focus when opening
+  useEffect(() => {
+    if (open) {
+      setSearch('');
+      setMode('commands');
+      // Monaco holds focus aggressively — schedule focus steal after render
+      requestAnimationFrame(() => {
+        inputRef.current?.focus();
+      });
+    }
+  }, [open]);
+
+  const handleSelect = useCallback(
+    (node: GraphNode, keyword: string, label: string) => {
+      onSelectResource?.(node);
+      const loc = findResourceLine(files, keyword, label);
+      if (loc) {
+        if (loc.filename === activeFile) {
+          onGoToLine(loc.line);
+        } else {
+          onSwitchFile(loc.filename, loc.line);
+        }
+      }
+      onOpenChange(false);
+    },
+    [files, activeFile, onGoToLine, onSwitchFile, onOpenChange, onSelectResource],
+  );
+
+  const handleGoToLine = useCallback(() => {
+    const num = parseInt(search, 10);
+    if (num > 0) {
+      onGoToLine(num);
+      onOpenChange(false);
+    }
+  }, [search, onGoToLine, onOpenChange]);
+
+  // Group nodes by type
+  const grouped = useMemo(() => {
+    const map = new Map<string, GraphNode[]>();
+    for (const node of nodes) {
+      if (!TYPE_META[node.type]) continue;
+      if (!map.has(node.type)) map.set(node.type, []);
+      map.get(node.type)!.push(node);
+    }
+    return map;
+  }, [nodes]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      className="cmdk-overlay"
+      onClick={() => onOpenChange(false)}
+      onKeyDown={(e) => {
+        // Catch Escape on the overlay level too
+        if (e.key === 'Escape') {
+          e.stopPropagation();
+          onOpenChange(false);
+        }
+      }}
+    >
+      <div
+        className="cmdk-wrapper"
+        onClick={(e) => e.stopPropagation()}
+        onKeyDown={(e) => e.stopPropagation()}
+      >
+        <Command
+          label="Command palette"
+          shouldFilter={mode === 'commands'}
+          loop
+        >
+          <Command.Input
+            ref={inputRef}
+            autoFocus
+            placeholder={mode === 'goto-line' ? 'Type a line number...' : 'Search resources or type a command...'}
+            value={search}
+            onValueChange={(v) => {
+              setSearch(v);
+              if (v.startsWith(':') && mode === 'commands') {
+                setMode('goto-line');
+                setSearch(v.slice(1));
+              }
+            }}
+            onKeyDown={(e) => {
+              if (e.key === 'Escape') {
+                e.preventDefault();
+                e.stopPropagation();
+                onOpenChange(false);
+                return;
+              }
+              if (e.key === 'Enter' && mode === 'goto-line') {
+                e.preventDefault();
+                handleGoToLine();
+              }
+              if (e.key === 'Backspace' && search === '' && mode === 'goto-line') {
+                setMode('commands');
+              }
+            }}
+          />
+          <Command.List>
+            {mode === 'goto-line' ? (
+              <Command.Group heading="Go to Line">
+                {search && parseInt(search, 10) > 0 ? (
+                  <Command.Item onSelect={handleGoToLine} value={`line-${search}`}>
+                    <Hash size={14} />
+                    Go to line {search}
+                  </Command.Item>
+                ) : (
+                  <Command.Item disabled value="goto-line-hint">
+                    Type a line number and press Enter
+                  </Command.Item>
+                )}
+              </Command.Group>
+            ) : (
+              <>
+                <Command.Empty>No results found</Command.Empty>
+                <Command.Group heading="Navigation">
+                  <Command.Item
+                    value="Go to Line"
+                    keywords={['line', 'number', 'goto', ':']}
+                    onSelect={() => {
+                      setMode('goto-line');
+                      setSearch('');
+                    }}
+                  >
+                    <Hash size={14} />
+                    Go to Line...
+                  </Command.Item>
+                  <Command.Item
+                    value="Fit Screen"
+                    keywords={['fit', 'screen', 'zoom', 'view', 'fit view']}
+                    onSelect={() => {
+                      onFitScreen?.();
+                      onOpenChange(false);
+                    }}
+                  >
+                    <Maximize size={14} />
+                    Fit Screen
+                  </Command.Item>
+                </Command.Group>
+                {Array.from(grouped.entries()).map(([type, items]) => {
+                  const meta = TYPE_META[type];
+                  if (!meta) return null;
+                  return (
+                    <Command.Group key={type} heading={`${meta.label}s`}>
+                      {items.map((node) => (
+                        <Command.Item
+                          key={node.id}
+                          value={`${meta.label} ${node.label}`}
+                          keywords={[meta.keyword, node.label, ...(node.metadata?.summary ? [String(node.metadata.summary)] : [])]}
+                          onSelect={() => handleSelect(node, meta.keyword, node.label)}
+                        >
+                          {meta.icon}
+                          <span className="cmdk-item-content">
+                            <span className="cmdk-item-label">
+                              {node.label}
+                              {node.metadata?.version && (
+                                <span className="cmdk-item-version">v{String(node.metadata.version)}</span>
+                              )}
+                            </span>
+                            {node.metadata?.summary && (
+                              <span className="cmdk-item-summary">{String(node.metadata.summary)}</span>
+                            )}
+                          </span>
+                        </Command.Item>
+                      ))}
+                    </Command.Group>
+                  );
+                })}
+              </>
+            )}
+          </Command.List>
+        </Command>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/playground/src/components/Editor.tsx b/packages/playground/src/components/Editor.tsx
new file mode 100644
index 000000000..c55ec3ee7
--- /dev/null
+++ b/packages/playground/src/components/Editor.tsx
@@ -0,0 +1,127 @@
+import { useRef, useCallback, useEffect, useImperativeHandle, forwardRef } from 'react';
+import MonacoEditor, { type OnMount, type BeforeMount, type Monaco } from '@monaco-editor/react';
+import type { editor } from 'monaco-editor';
+import { registerEcLanguage } from '../monaco/ec-language';
+import { registerEcCompletion, setAllFilesSources } from '../monaco/ec-completion';
+import { setDiagnostics, type DslError } from '../monaco/ec-diagnostics';
+
+export interface EditorHandle {
+  revealLine: (line: number) => void;
+}
+
+interface EditorProps {
+  value: string;
+  onChange: (value: string) => void;
+  errors: DslError[];
+  allFiles: Record<string, string>;
+  onFormat?: () => void;
+  onCommandPalette?: () => void;
+}
+
+export const Editor = forwardRef<EditorHandle, EditorProps>(function Editor({ value, onChange, errors, allFiles, onFormat, onCommandPalette }, ref) {
+  useEffect(() => {
+    setAllFilesSources(allFiles);
+  }, [allFiles]);
+  const monacoRef = useRef<Monaco | null>(null);
+  const editorRef = useRef<editor.IStandaloneCodeEditor | null>(null);
+  const onFormatRef = useRef(onFormat);
+  onFormatRef.current = onFormat;
+  const onCommandPaletteRef = useRef(onCommandPalette);
+  onCommandPaletteRef.current = onCommandPalette;
+
+  useImperativeHandle(ref, () => ({
+    revealLine(line: number) {
+      const ed = editorRef.current;
+      if (!ed) return;
+      ed.revealLineInCenter(line);
+      ed.setPosition({ lineNumber: line, column: 1 });
+      ed.focus();
+    },
+  }));
+
+  const handleBeforeMount: BeforeMount = useCallback((monaco) => {
+    registerEcLanguage(monaco);
+    registerEcCompletion(monaco);
+  }, []);
+
+  const handleMount: OnMount = useCallback((editor, monaco) => {
+    editorRef.current = editor;
+    monacoRef.current = monaco;
+
+    const model = editor.getModel();
+    if (model) {
+      monaco.editor.setModelLanguage(model, 'ec');
+    }
+
+    editor.addAction({
+      id: 'ec-format',
+      label: 'Format EC Document',
+      keybindings: [
+        monaco.KeyMod.Shift | monaco.KeyMod.Alt | monaco.KeyCode.KeyF,
+      ],
+      run: () => {
+        onFormatRef.current?.();
+      },
+    });
+
+    editor.addAction({
+      id: 'ec-command-palette',
+      label: 'Open Command Palette',
+      keybindings: [
+        monaco.KeyMod.CtrlCmd | monaco.KeyCode.KeyK,
+      ],
+      run: () => {
+        onCommandPaletteRef.current?.();
+      },
+    });
+  }, []);
+
+  const handleEditorDidMount: OnMount = useCallback((editor, monaco) => {
+    handleMount(editor, monaco);
+
+    const model = editor.getModel();
+    if (model) {
+      setDiagnostics(monaco, model, errors);
+    }
+  }, [handleMount, errors]);
+
+  if (monacoRef.current && editorRef.current) {
+    const model = editorRef.current.getModel();
+    if (model) {
+      setDiagnostics(monacoRef.current, model, errors);
+    }
+  }
+
+  return (
+    <div style={{ height: '100%' }} onKeyDown={(e) => e.stopPropagation()}>
+    <MonacoEditor
+      height="100%"
+      defaultLanguage="ec"
+      theme="ec-dark"
+      value={value}
+      onChange={(val) => onChange(val ?? '')}
+      beforeMount={handleBeforeMount}
+      onMount={handleEditorDidMount}
+      options={{
+        fontSize: 14,
+        lineHeight: 22,
+        fontFamily: "'JetBrains Mono', 'Fira Code', 'Cascadia Code', Menlo, Monaco, monospace",
+        minimap: { enabled: false },
+        scrollBeyondLastLine: false,
+        padding: { top: 12 },
+        automaticLayout: true,
+        tabSize: 2,
+        renderWhitespace: 'none',
+        bracketPairColorization: { enabled: true },
+        acceptSuggestionOnCommitCharacter: false,
+        acceptSuggestionOnEnter: 'on',
+        suggest: {
+          showKeywords: false,
+          showSnippets: true,
+          showWords: false,
+        },
+      }}
+    />
+    </div>
+  );
+});
diff --git a/packages/playground/src/components/HeroPreview.tsx b/packages/playground/src/components/HeroPreview.tsx
new file mode 100644
index 000000000..33e11a728
--- /dev/null
+++ b/packages/playground/src/components/HeroPreview.tsx
@@ -0,0 +1,580 @@
+import { memo, useState, useEffect, useRef, useCallback } from 'react';
+import type { GraphNode, GraphEdge } from '@eventcatalog/visualiser';
+import { registerEcLanguage } from '../monaco/ec-language';
+
+// Self-contained DSL for the parser (inline definitions so it renders without import resolution)
+const HERO_DSL = `visualizer main {
+  channel orderCreated {
+    version 1.0.0
+    address "orders.created"
+    protocol "kafka"
+  }
+
+  channel orderShipped {
+    version 1.0.0
+    address "orders.shipped"
+    protocol "kafka"
+  }
+
+  domain OrderManagement {
+    version 1.0.0
+    summary "Handles the full order lifecycle"
+
+    service OrderService {
+      version 1.0.0
+      summary "Manages order lifecycle"
+
+      sends event OrderCreated to orderCreated {
+        version 1.0.0
+        summary "Fired when a new order is placed"
+      }
+
+      sends event OrderShipped to orderShipped {
+        version 1.0.0
+        summary "Fired when an order has been shipped"
+      }
+
+      receives event OrderCancelled {
+        version 1.0.0
+        summary "Handles order cancellation requests"
+      }
+    }
+  }
+
+  service ShippingService {
+    version 1.0.0
+    summary "Handles shipping and delivery"
+    @note("Migrating to new carrier API in Q3")
+
+    receives event OrderCreated from orderCreated
+    sends event OrderShipped to orderShipped
+  }
+
+  service NotificationService {
+    version 1.0.0
+    summary "Sends customer notifications"
+    @note("Supports email, SMS, and push channels")
+
+    receives event OrderCreated from orderCreated
+    receives event OrderShipped from orderShipped
+  }
+}`;
+
+// The code shown in the Monaco editor — shows import syntax prominently
+const EDITOR_CODE = `// 1. Import the OrderService from your AsyncAPI spec
+import OrderService from "./orders-asyncapi.yml"
+
+// 2. Import specific events and channels to use
+import events { OrderCreated, OrderShipped }
+  from "./orders-asyncapi.yml"
+import channels { orderCreated, orderShipped }
+  from "./orders-asyncapi.yml"
+
+visualizer main {
+
+  // 3. Place the imported service inside a domain
+  domain OrderManagement {
+    version 1.0.0
+    summary "Handles the full order lifecycle"
+
+    service OrderService
+  }
+
+  // 4. Wire up other services using the imported events
+  service ShippingService {
+    version 1.0.0
+    summary "Handles shipping and delivery"
+    @note("Migrating to new carrier API in Q3")
+
+    receives event OrderCreated from orderCreated
+    sends event OrderShipped to orderShipped
+  }
+
+  service NotificationService {
+    version 1.0.0
+    summary "Sends customer notifications"
+    @note("Supports email, SMS, and push channels")
+
+    receives event OrderCreated from orderCreated
+    receives event OrderShipped from orderShipped
+  }
+}`;
+
+// Sample AsyncAPI spec shown when clicking the asyncapi tab
+const ASYNCAPI_CODE = `asyncapi: 3.0.0
+info:
+  title: Order Service
+  version: 1.0.0
+  description: Manages order lifecycle events
+
+channels:
+  orderCreated:
+    address: orders.created
+    messages:
+      OrderCreated:
+        payload:
+          type: object
+          properties:
+            orderId:
+              type: string
+              format: uuid
+            customerId:
+              type: string
+            totalAmount:
+              type: number
+            currency:
+              type: string
+            items:
+              type: array
+              items:
+                type: object
+                properties:
+                  productId:
+                    type: string
+                  quantity:
+                    type: integer
+                  price:
+                    type: number
+
+  orderShipped:
+    address: orders.shipped
+    messages:
+      OrderShipped:
+        payload:
+          type: object
+          properties:
+            orderId:
+              type: string
+              format: uuid
+            trackingNumber:
+              type: string
+            carrier:
+              type: string
+            estimatedDelivery:
+              type: string
+              format: date-time
+
+operations:
+  sendOrderCreated:
+    action: send
+    channel:
+      $ref: "#/channels/orderCreated"
+  sendOrderShipped:
+    action: send
+    channel:
+      $ref: "#/channels/orderShipped"
+  receiveOrderCancelled:
+    action: receive
+    channel:
+      address: orders.cancelled`;
+
+// Sample OpenAPI spec shown when clicking the openapi tab
+const OPENAPI_CODE = `openapi: 3.0.3
+info:
+  title: Payments API
+  version: 1.0.0
+  description: Handles payment processing
+
+paths:
+  /payments:
+    post:
+      summary: Process a payment
+      operationId: processPayment
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                orderId:
+                  type: string
+                  format: uuid
+                amount:
+                  type: number
+                currency:
+                  type: string
+                method:
+                  type: string
+                  enum: [credit_card, debit_card, bank_transfer]
+      responses:
+        "201":
+          description: Payment processed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  paymentId:
+                    type: string
+                  status:
+                    type: string
+                    enum: [pending, completed, failed]
+
+  /payments/{paymentId}:
+    get:
+      summary: Get payment status
+      operationId: getPaymentStatus
+      parameters:
+        - name: paymentId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Payment details
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  paymentId:
+                    type: string
+                  orderId:
+                    type: string
+                  status:
+                    type: string
+                  amount:
+                    type: number`;
+
+interface HeroFile {
+  name: string;
+  content: string;
+  language: string;
+}
+
+const HERO_FILES: HeroFile[] = [
+  { name: 'main.ec', content: EDITOR_CODE, language: 'ec' },
+  { name: 'orders-asyncapi.yml', content: ASYNCAPI_CODE, language: 'yaml' },
+  { name: 'payments-openapi.yml', content: OPENAPI_CODE, language: 'yaml' },
+];
+
+interface DslGraph {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  visualizers?: string[];
+  activeVisualizer?: string;
+  title?: string;
+  empty?: boolean;
+  options?: Record<string, unknown>;
+}
+
+/** Lazily parse the hero DSL once and cache the result. */
+let cachedGraph: DslGraph | null = null;
+
+async function parseHeroDsl(): Promise<DslGraph> {
+  if (cachedGraph) return cachedGraph;
+
+  const langModule = await import('@eventcatalog/language-server/browser');
+  const { EmptyFileSystem, URI } = await import('langium');
+
+  const services = langModule.createEcServices(EmptyFileSystem);
+  const uri = URI.parse('file:///hero-preview.ec');
+  const document = services.shared.workspace.LangiumDocumentFactory.fromString(HERO_DSL, uri);
+  services.shared.workspace.LangiumDocuments.addDocument(document);
+  await services.shared.workspace.DocumentBuilder.build([document]);
+
+  const graph: DslGraph = langModule.astToGraph(document.parseResult.value);
+
+  try {
+    services.shared.workspace.LangiumDocuments.deleteDocument(uri);
+  } catch {
+    // Ignore cleanup errors
+  }
+
+  cachedGraph = graph;
+  return graph;
+}
+
+const LiveVisualizer = memo(function LiveVisualizer({ graph, id, portalId }: { graph: DslGraph; id: string; portalId: string }) {
+  const [NodeGraph, setNodeGraph] = useState<React.ComponentType<any> | null>(null);
+
+  useEffect(() => {
+    import('@eventcatalog/visualiser').then((mod) => {
+      setNodeGraph(() => mod.NodeGraph);
+    });
+  }, []);
+
+  if (!NodeGraph) return null;
+
+  return (
+    <div style={{ position: 'absolute', inset: 0, width: '100%', height: '100%' }}>
+      <NodeGraph
+        id={id}
+        portalId={portalId}
+        graph={graph}
+        mode="full"
+        zoomOnScroll={false}
+        showSearch={false}
+        includeKey={false}
+      />
+    </div>
+  );
+});
+
+/** Read-only Monaco editor for the code panel */
+const HeroEditor = memo(function HeroEditor({ value, language }: { value: string; language: string }) {
+  const editorRef = useRef<any>(null);
+
+  const [MonacoEditor, setMonacoEditor] = useState<any>(null);
+
+  useEffect(() => {
+    let disposed = false;
+    import('@monaco-editor/react').then((mod) => {
+      if (!disposed) {
+        setMonacoEditor(() => mod.default);
+      }
+    });
+    return () => { disposed = true; };
+  }, []);
+
+  const handleBeforeMount = useCallback((monaco: any) => {
+    // Register EC language + dark theme synchronously before editor mounts
+    const langs = monaco.languages.getLanguages();
+    if (!langs.some((l: any) => l.id === 'ec')) {
+      registerEcLanguage(monaco);
+    }
+  }, []);
+
+  const handleMount = useCallback((editor: any, monaco: any) => {
+    editorRef.current = editor;
+    const model = editor.getModel();
+    if (model) {
+      monaco.editor.setModelLanguage(model, language);
+    }
+  }, [language]);
+
+  if (!MonacoEditor) {
+    return (
+      <div style={{ width: '100%', height: '100%', background: '#0d1117', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+        <span style={{ color: '#484f58', fontSize: 12 }}>Loading editor...</span>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ width: '100%', height: '100%' }} onKeyDown={(e) => e.stopPropagation()}>
+      <MonacoEditor
+        height="100%"
+        language={language}
+        theme="ec-dark"
+        value={value}
+        beforeMount={handleBeforeMount}
+        onMount={handleMount}
+        options={{
+          readOnly: true,
+          fontSize: window.innerWidth <= 768 ? 11 : 13,
+          lineHeight: window.innerWidth <= 768 ? 17 : 20,
+          fontFamily: "'JetBrains Mono', 'Fira Code', 'Cascadia Code', Menlo, Monaco, monospace",
+          minimap: { enabled: false },
+          scrollBeyondLastLine: false,
+          padding: { top: 12 },
+          automaticLayout: true,
+          tabSize: 2,
+          renderWhitespace: 'none',
+          bracketPairColorization: { enabled: true },
+          lineNumbers: window.innerWidth <= 768 ? 'off' : 'on',
+          folding: false,
+          overviewRulerLanes: 0,
+          hideCursorInOverviewRuler: true,
+          overviewRulerBorder: false,
+          scrollbar: {
+            vertical: 'hidden',
+            horizontal: 'hidden',
+          },
+          domReadOnly: true,
+          contextmenu: false,
+        }}
+      />
+    </div>
+  );
+});
+
+const MIN_SPLIT = 25;
+const MAX_SPLIT = 75;
+const DEFAULT_SPLIT = 40;
+
+export const HeroPreview = memo(function HeroPreview() {
+  const [graph, setGraph] = useState<DslGraph | null>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const started = useRef(false);
+  const [splitPct, setSplitPct] = useState(DEFAULT_SPLIT);
+  const isDragging = useRef(false);
+  const [activeTab, setActiveTab] = useState(0);
+
+  const loadGraph = useCallback(() => {
+    if (started.current) return;
+    started.current = true;
+    parseHeroDsl().then(setGraph);
+  }, []);
+
+  // Start loading when the component is near the viewport
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          loadGraph();
+          observer.disconnect();
+        }
+      },
+      { rootMargin: '200px' },
+    );
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [loadGraph]);
+
+  // Resize handle
+  const onMouseDown = useCallback((e: React.MouseEvent) => {
+    e.preventDefault();
+    isDragging.current = true;
+    document.body.style.cursor = 'col-resize';
+    document.body.style.userSelect = 'none';
+  }, []);
+
+  useEffect(() => {
+    const onMouseMove = (e: MouseEvent) => {
+      if (!isDragging.current || !bodyRef.current) return;
+      const rect = bodyRef.current.getBoundingClientRect();
+      const pct = ((e.clientX - rect.left) / rect.width) * 100;
+      setSplitPct(Math.min(MAX_SPLIT, Math.max(MIN_SPLIT, pct)));
+    };
+
+    const onMouseUp = () => {
+      if (isDragging.current) {
+        isDragging.current = false;
+        document.body.style.cursor = '';
+        document.body.style.userSelect = '';
+      }
+    };
+
+    window.addEventListener('mousemove', onMouseMove);
+    window.addEventListener('mouseup', onMouseUp);
+    return () => {
+      window.removeEventListener('mousemove', onMouseMove);
+      window.removeEventListener('mouseup', onMouseUp);
+    };
+  }, []);
+
+  return (
+    <div className="hero-preview-wrapper" ref={containerRef}>
+      <div className="editor-window">
+        <div className="editor-titlebar">
+          <div className="editor-dots">
+            <span></span>
+            <span></span>
+            <span></span>
+          </div>
+          <div className="editor-tabs">
+            {HERO_FILES.map((file, i) => (
+              <div
+                key={file.name}
+                className={`editor-tab${i === activeTab ? ' active' : ''}`}
+                onClick={() => setActiveTab(i)}
+                style={{ cursor: 'pointer' }}
+              >
+                {file.name}
+              </div>
+            ))}
+          </div>
+        </div>
+        <div className="hero-editor-body" ref={bodyRef}>
+          <div className="hero-editor-code" style={{ width: `${splitPct}%` }}>
+            <HeroEditor value={HERO_FILES[activeTab].content} language={HERO_FILES[activeTab].language} />
+          </div>
+          <div
+            className="hero-resize-handle"
+            onMouseDown={onMouseDown}
+          >
+            <div className="hero-resize-line" />
+          </div>
+          <div className="hero-editor-viz hero-editor-viz-desktop" style={{ width: `${100 - splitPct}%` }}>
+            <div id="hero-preview-portal" style={{ position: 'absolute', inset: 0, zIndex: 2 }} />
+            {graph ? (
+              <LiveVisualizer graph={graph} id="hero-preview" portalId="hero-preview-portal" />
+            ) : (
+              <div style={{ position: 'absolute', inset: 0, display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+                <span style={{ color: '#4a4f63', fontSize: 12 }}>Loading visualizer...</span>
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+      {/* Mobile: visualizer as separate card below editor */}
+      <div className="hero-viz-mobile">
+        <div className="hero-viz-mobile-label">Live preview</div>
+        <div className="hero-viz-mobile-inner">
+          <div id="hero-preview-portal-mobile" style={{ position: 'absolute', inset: 0, zIndex: 2 }} />
+          {graph ? (
+            <LiveVisualizer graph={graph} id="hero-preview-mobile" portalId="hero-preview-portal-mobile" />
+          ) : (
+            <div style={{ position: 'absolute', inset: 0, display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+              <span style={{ color: '#4a4f63', fontSize: 12 }}>Loading visualizer...</span>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+});
+
+/** Standalone visualizer for embedding in the "Visualize and share" step. */
+export const StepVisualizer = memo(function StepVisualizer() {
+  const [graph, setGraph] = useState<DslGraph | null>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const started = useRef(false);
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting && !started.current) {
+          started.current = true;
+          parseHeroDsl().then(setGraph);
+          observer.disconnect();
+        }
+      },
+      { rootMargin: '200px' },
+    );
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  const [NodeGraph, setNodeGraph] = useState<React.ComponentType<any> | null>(null);
+
+  useEffect(() => {
+    if (!graph) return;
+    import('@eventcatalog/visualiser').then((mod) => {
+      setNodeGraph(() => mod.NodeGraph);
+    });
+  }, [graph]);
+
+  return (
+    <div ref={containerRef} className="step-viz-container">
+      <div id="step-viz-portal" style={{ position: 'absolute', inset: 0, zIndex: 2 }} />
+      {graph && NodeGraph ? (
+        <div style={{ position: 'absolute', inset: 0, width: '100%', height: '100%' }}>
+          <NodeGraph
+            id="step-visualizer"
+            portalId="step-viz-portal"
+            graph={graph}
+            mode="full"
+            zoomOnScroll={false}
+            showSearch={false}
+            includeKey={false}
+          />
+        </div>
+      ) : (
+        <div style={{ position: 'absolute', inset: 0, display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+          <span style={{ color: '#4a4f63', fontSize: 12 }}>Loading visualizer...</span>
+        </div>
+      )}
+    </div>
+  );
+});
diff --git a/packages/playground/src/components/NextStepsGuide.tsx b/packages/playground/src/components/NextStepsGuide.tsx
new file mode 100644
index 000000000..ee4b9b992
--- /dev/null
+++ b/packages/playground/src/components/NextStepsGuide.tsx
@@ -0,0 +1,282 @@
+import { useCallback, useMemo, memo } from "react";
+import { useStore } from "@nanostores/react";
+import { X, ChevronRight, Check, ExternalLink } from "lucide-react";
+import { $workspace, saveWorkspace } from "../stores/workspace";
+import type { SpecKind } from "../stores/workspace";
+
+interface TransformStep {
+  id: string;
+  title: string;
+  description: string;
+  type: "transform";
+  apply: (content: string) => string;
+}
+
+interface ActionStep {
+  id: string;
+  title: string;
+  description: string;
+  type: "action";
+  action: () => void;
+}
+
+interface LinkStep {
+  id: string;
+  title: string;
+  description: string;
+  type: "link";
+  href: string;
+}
+
+type Step = TransformStep | ActionStep | LinkStep;
+
+/**
+ * Insert a line inside the visualizer block, right before the closing `}`.
+ * Returns the original content unchanged if no visualizer block is found.
+ */
+function insertIntoVisualizerBlock(content: string, line: string): string {
+  const match = content.match(/(visualizer\s+\w+\s*\{[\s\S]*?)(^\})/m);
+  if (!match || match.index === undefined) return content;
+  const insertPos = match.index + match[1].length;
+  return content.slice(0, insertPos) + line + "\n" + content.slice(insertPos);
+}
+
+/**
+ * Replace service references in the visualizer block with a domain reference.
+ */
+function replaceServicesWithDomain(
+  content: string,
+  serviceNames: string[],
+  domainName: string,
+): string {
+  const vizMatch = content.match(/(visualizer\s+\w+\s*\{)([\s\S]*?)(^\})/m);
+  if (!vizMatch || vizMatch.index === undefined) return content;
+
+  const before = content.slice(0, vizMatch.index + vizMatch[1].length);
+  let body = vizMatch[2];
+  const after = content.slice(
+    vizMatch.index + vizMatch[1].length + vizMatch[2].length,
+  );
+
+  for (const name of serviceNames) {
+    body = body.replace(
+      new RegExp(`^[ \t]*service\\s+${name}[ \t]*$\\n?`, "m"),
+      "",
+    );
+  }
+
+  body = body + `  domain ${domainName}\n`;
+
+  return before + body + after;
+}
+
+function getSteps(
+  kind: SpecKind,
+  specFile: string,
+  serviceNames: string[],
+  onExportCatalog: () => void,
+): Step[] {
+  const serviceList = serviceNames.length > 0 ? serviceNames : ["MyService"];
+  const domainName = kind === "openapi" ? "ApiDomain" : "EventsDomain";
+  const serviceRefs = serviceList.map((s) => `  service ${s}`).join("\n");
+
+  return [
+    {
+      id: "domain",
+      title: "Wrap your service in a domain",
+      description: "Group related services under a business domain.",
+      type: "transform",
+      apply: (content) => {
+        const domainBlock = `domain ${domainName} {\n  version 1.0.0\n  summary "Groups related ${kind === "openapi" ? "API" : "event-driven"} services"\n${serviceRefs}\n}\n\n`;
+        const vizIndex = content.search(/^visualizer\s/m);
+        let updated: string;
+        if (vizIndex >= 0) {
+          updated =
+            content.slice(0, vizIndex) + domainBlock + content.slice(vizIndex);
+        } else {
+          updated = content + "\n" + domainBlock;
+        }
+        updated = replaceServicesWithDomain(updated, serviceList, domainName);
+        return updated;
+      },
+    },
+    {
+      id: "new-service",
+      title: "Add a new service",
+      description: "Add a draft service that produces and consumes messages.",
+      type: "transform",
+      apply: (content) => {
+        // Add a new draft service that sends events/commands and receives queries
+        const serviceBlock = [
+          `service FullfillmentService {`,
+          `  version 0.1.0`,
+          `  draft true`,
+          `  summary "Handles order fullfillment and shipping"`,
+          `  sends event ShipmentDispatched {`,
+          `    version 1.0.0`,
+          `    summary "Raised when a shipment leaves the warehouse"`,
+          `  }`,
+          `  sends command RequestPickup {`,
+          `    version 1.0.0`,
+          `    summary "Requests a carrier pickup for a parcel"`,
+          `  }`,
+          `  receives query GetShipmentStatus {`,
+          `    version 1.0.0`,
+          `    summary "Returns the current status of a shipment"`,
+          `  }`,
+          `  receives event OrderCreated {`,
+          `    version 1.0.0`,
+          `    summary "Triggers fullfillment when a new order is placed"`,
+          `  }`,
+          `}`,
+          ``,
+          ``,
+        ].join("\n");
+
+        const vizIndex = content.search(/^visualizer\s/m);
+        let updated: string;
+        if (vizIndex >= 0) {
+          updated =
+            content.slice(0, vizIndex) + serviceBlock + content.slice(vizIndex);
+        } else {
+          updated = content + "\n" + serviceBlock;
+        }
+
+        // Add the service into the visualizer block
+        updated = insertIntoVisualizerBlock(
+          updated,
+          `  service FullfillmentService`,
+        );
+
+        return updated;
+      },
+    },
+    {
+      id: "export",
+      title: "Export into documentation",
+      description: "Download as an EventCatalog project.",
+      type: "action",
+      action: onExportCatalog,
+    },
+    {
+      id: "learn",
+      title: "Learn more",
+      description: "Read the EventCatalog DSL docs.",
+      type: "link",
+      href: "/docs",
+    },
+  ];
+}
+
+interface NextStepsGuideProps {
+  specKind: SpecKind;
+  specFile: string;
+  serviceNames: string[];
+  onApplyStep: (transform: (content: string) => string) => void;
+  onExportCatalog: () => void;
+  onDismiss: () => void;
+}
+
+export const NextStepsGuide = memo(function NextStepsGuide({
+  specKind,
+  specFile,
+  serviceNames,
+  onApplyStep,
+  onExportCatalog,
+  onDismiss,
+}: NextStepsGuideProps) {
+  const ws = useStore($workspace);
+  const completedSteps = useMemo(() => new Set(ws.guideDone), [ws.guideDone]);
+  const steps = getSteps(specKind, specFile, serviceNames, onExportCatalog);
+
+  const handleStepClick = useCallback(
+    (step: Step) => {
+      if (step.type === "link") {
+        window.open(step.href, "_blank", "noopener,noreferrer");
+        // Mark as done
+        const next = [...ws.guideDone, step.id];
+        $workspace.setKey("guideDone", next);
+        saveWorkspace();
+        return;
+      }
+
+      if (completedSteps.has(step.id)) return;
+
+      if (step.type === "action") {
+        step.action();
+      } else {
+        onApplyStep(step.apply);
+      }
+
+      const next = [...ws.guideDone, step.id];
+      $workspace.setKey("guideDone", next);
+      saveWorkspace();
+    },
+    [completedSteps, onApplyStep, ws.guideDone],
+  );
+
+  const transformSteps = steps.filter(
+    (s) => s.type === "transform" || s.type === "action",
+  );
+  const allTransformsDone = transformSteps.every((s) =>
+    completedSteps.has(s.id),
+  );
+
+  return (
+    <div className="next-steps-guide">
+      <div className="next-steps-header">
+        <div>
+          <h3 className="next-steps-title">
+            {allTransformsDone ? "Nice work!" : "What to do next"}
+          </h3>
+          <p className="next-steps-subtitle">
+            {allTransformsDone
+              ? "You've completed all the steps. Keep building your architecture."
+              : `${completedSteps.size} of ${steps.length} steps`}
+          </p>
+        </div>
+        <button
+          type="button"
+          className="next-steps-close"
+          onClick={onDismiss}
+          aria-label="Dismiss guide"
+        >
+          <X size={14} />
+        </button>
+      </div>
+      <div className="next-steps-list">
+        {steps.map((step) => {
+          const done = completedSteps.has(step.id);
+          const isLink = step.type === "link";
+          return (
+            <button
+              key={step.id}
+              type="button"
+              className={`next-steps-item${done ? " next-steps-item--done" : ""}`}
+              onClick={() => handleStepClick(step)}
+              disabled={done && !isLink}
+            >
+              <span className="next-steps-item-check">
+                {done ? (
+                  <Check size={12} />
+                ) : (
+                  <span className="next-steps-item-dot" />
+                )}
+              </span>
+              <div className="next-steps-item-body">
+                <span className="next-steps-item-title">{step.title}</span>
+                <span className="next-steps-item-desc">{step.description}</span>
+              </div>
+              {!done &&
+                (isLink ? (
+                  <ExternalLink size={14} className="next-steps-item-arrow" />
+                ) : (
+                  <ChevronRight size={14} className="next-steps-item-arrow" />
+                ))}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+});
diff --git a/packages/playground/src/components/StatusBar.tsx b/packages/playground/src/components/StatusBar.tsx
new file mode 100644
index 000000000..130cb8fd0
--- /dev/null
+++ b/packages/playground/src/components/StatusBar.tsx
@@ -0,0 +1,96 @@
+import { memo, useMemo } from "react";
+import { AlertCircle, Bug } from "lucide-react";
+import type { GraphNode } from "@eventcatalog/language-server/browser";
+
+const NODE_LABELS: Record<string, [string, string]> = {
+  domain: ["domain", "domains"],
+  service: ["service", "services"],
+  event: ["event", "events"],
+  command: ["command", "commands"],
+  query: ["query", "queries"],
+  channel: ["channel", "channels"],
+  container: ["container", "containers"],
+  entity: ["entity", "entities"],
+  flow: ["flow", "flows"],
+  "data-product": ["data product", "data products"],
+  actor: ["actor", "actors"],
+  "external-system": ["external system", "external systems"],
+  step: ["step", "steps"],
+};
+
+const DISPLAY_ORDER = [
+  "domain",
+  "service",
+  "event",
+  "command",
+  "query",
+  "channel",
+  "container",
+  "entity",
+  "flow",
+  "data-product",
+  "actor",
+  "external-system",
+  "step",
+];
+
+export const StatusBar = memo(function StatusBar({
+  nodes,
+  errorCount,
+  onCommandPalette,
+}: {
+  nodes: GraphNode[];
+  errorCount: number;
+  onCommandPalette: () => void;
+}) {
+  const counts = useMemo(() => {
+    const map: Record<string, number> = {};
+    for (const node of nodes) {
+      map[node.type] = (map[node.type] || 0) + 1;
+    }
+    return DISPLAY_ORDER.filter((type) => map[type]).map((type) => {
+      const n = map[type];
+      const [singular, plural] = NODE_LABELS[type] || [type, type + "s"];
+      return `${n} ${n === 1 ? singular : plural}`;
+    });
+  }, [nodes]);
+
+  return (
+    <footer className="status-bar">
+      <div className="status-bar-left">
+        {errorCount > 0 && (
+          <span className="status-bar-errors">
+            <AlertCircle size={12} />
+            {errorCount} error{errorCount !== 1 ? "s" : ""}
+          </span>
+        )}
+        {counts.length > 0 ? (
+          <span className="status-bar-counts">{counts.join(" \u00b7 ")}</span>
+        ) : (
+          <span className="status-bar-counts status-bar-empty">
+            No resources defined
+          </span>
+        )}
+      </div>
+      <div className="status-bar-right">
+        <a
+          className="status-bar-btn"
+          href="https://github.com/event-catalog/eventcatalog/issues/new?labels=compass&template=bug_report.md"
+          target="_blank"
+          rel="noopener noreferrer"
+          title="Report a bug or request a feature"
+        >
+          <Bug size={12} />
+          Feedback
+        </a>
+        <button
+          className="status-bar-btn"
+          onClick={onCommandPalette}
+          title="Command palette (⌘K)"
+        >
+          <kbd className="status-bar-kbd">⌘K</kbd>
+        </button>
+      </div>
+    </footer>
+  );
+});
diff --git a/packages/playground/src/components/TabBar.tsx b/packages/playground/src/components/TabBar.tsx
new file mode 100644
index 000000000..8c454c41e
--- /dev/null
+++ b/packages/playground/src/components/TabBar.tsx
@@ -0,0 +1,39 @@
+import { X, Plus } from 'lucide-react';
+
+interface TabBarProps {
+  files: string[];
+  activeFile: string;
+  onSelectFile: (filename: string) => void;
+  onCloseFile: (filename: string) => void;
+  onAddFile: () => void;
+}
+
+export function TabBar({ files, activeFile, onSelectFile, onCloseFile, onAddFile }: TabBarProps) {
+  return (
+    <div className="tab-bar">
+      {files.map((filename) => (
+        <button
+          key={filename}
+          className={`tab-item ${filename === activeFile ? 'tab-item-active' : ''}`}
+          onClick={() => onSelectFile(filename)}
+        >
+          <span className="tab-name">{filename}</span>
+          {files.length > 1 && (
+            <span
+              className="tab-close"
+              onClick={(e) => {
+                e.stopPropagation();
+                onCloseFile(filename);
+              }}
+            >
+              <X size={12} />
+            </span>
+          )}
+        </button>
+      ))}
+      <button className="tab-add" onClick={onAddFile} title="Add file">
+        <Plus size={14} />
+      </button>
+    </div>
+  );
+}
diff --git a/packages/playground/src/components/TemplateDropdown.tsx b/packages/playground/src/components/TemplateDropdown.tsx
new file mode 100644
index 000000000..ca9e3f220
--- /dev/null
+++ b/packages/playground/src/components/TemplateDropdown.tsx
@@ -0,0 +1,117 @@
+import { useState, useRef, useEffect, useCallback, memo, useMemo } from "react";
+import { ChevronDown, Check } from "lucide-react";
+import { examples } from "../examples/index";
+
+interface TemplateDropdownProps {
+  selectedExample: number;
+  templateUnselected: boolean;
+  loadedFromUrl: boolean;
+  onSelectExample: (index: number) => void;
+}
+
+interface GroupedExample {
+  group: string;
+  items: { index: number; name: string }[];
+}
+
+// Preserve the order groups appear in the examples array
+function groupExamples(): GroupedExample[] {
+  const groups: GroupedExample[] = [];
+  const seen = new Map<string, GroupedExample>();
+  examples.forEach((ex, i) => {
+    const key = ex.group;
+    let g = seen.get(key);
+    if (!g) {
+      g = { group: key, items: [] };
+      seen.set(key, g);
+      groups.push(g);
+    }
+    g.items.push({ index: i, name: ex.name });
+  });
+  return groups;
+}
+
+export const TemplateDropdown = memo(function TemplateDropdown({
+  selectedExample,
+  templateUnselected,
+  loadedFromUrl,
+  onSelectExample,
+}: TemplateDropdownProps) {
+  const [open, setOpen] = useState(false);
+  const wrapperRef = useRef<HTMLDivElement>(null);
+  const grouped = useMemo(groupExamples, []);
+
+  const label = loadedFromUrl
+    ? "Shared Link"
+    : templateUnselected
+      ? "Select a template"
+      : (examples[selectedExample]?.name ?? "");
+
+  // Close on click outside
+  useEffect(() => {
+    if (!open) return;
+    const onClick = (e: MouseEvent) => {
+      if (wrapperRef.current && !wrapperRef.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", onClick);
+    return () => document.removeEventListener("mousedown", onClick);
+  }, [open]);
+
+  // Close on Escape
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setOpen(false);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open]);
+
+  const handleSelect = useCallback(
+    (index: number) => {
+      onSelectExample(index);
+      setOpen(false);
+    },
+    [onSelectExample],
+  );
+
+  return (
+    <div className="template-dropdown" ref={wrapperRef}>
+      <button
+        className="template-dropdown-trigger"
+        onClick={() => setOpen((v) => !v)}
+        aria-haspopup="listbox"
+        aria-expanded={open}
+      >
+        <span className="template-dropdown-label">{label}</span>
+        <ChevronDown size={14} className="template-dropdown-chevron" />
+      </button>
+      {open && (
+        <div className="template-dropdown-panel" role="listbox">
+          {grouped.map((g) => (
+            <div key={g.group} className="template-dropdown-group">
+              <div className="template-dropdown-group-header">{g.group}</div>
+              {g.items.map((item) => {
+                const isActive = !templateUnselected && !loadedFromUrl && item.index === selectedExample;
+                return (
+                  <button
+                    key={item.index}
+                    className={`template-dropdown-item${isActive ? " template-dropdown-item--active" : ""}`}
+                    role="option"
+                    aria-selected={isActive}
+                    onClick={() => handleSelect(item.index)}
+                  >
+                    <span>{item.name}</span>
+                    {isActive && <Check size={13} />}
+                  </button>
+                );
+              })}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+});
diff --git a/packages/playground/src/components/Visualizer.tsx b/packages/playground/src/components/Visualizer.tsx
new file mode 100644
index 000000000..96ed48353
--- /dev/null
+++ b/packages/playground/src/components/Visualizer.tsx
@@ -0,0 +1,29 @@
+import { memo } from 'react';
+import { NodeGraph } from '@eventcatalog/visualiser';
+import type { DslGraph } from '@eventcatalog/visualiser';
+
+interface VisualizerProps {
+  graph: DslGraph;
+  focusNodeId?: string | null;
+  focusRequestId?: number;
+  fitRequestId?: number;
+}
+
+export const Visualizer = memo(function Visualizer({ graph, focusNodeId, focusRequestId, fitRequestId }: VisualizerProps) {
+  return (
+    <div style={{ width: '100%', height: '100%' }}>
+      <div id="dsl-playground-portal" style={{ width: '100%', height: '100%' }} />
+      <NodeGraph
+        id="dsl-playground"
+        portalId="dsl-playground-portal"
+        graph={graph}
+        focusNodeId={focusNodeId}
+        focusRequestId={focusRequestId}
+        fitRequestId={fitRequestId}
+        mode="full"
+        zoomOnScroll={true}
+        showSearch={false}
+      />
+    </div>
+  );
+});
diff --git a/packages/playground/src/examples/01-payment-domain.ts b/packages/playground/src/examples/01-payment-domain.ts
new file mode 100644
index 000000000..cb749a10c
--- /dev/null
+++ b/packages/playground/src/examples/01-payment-domain.ts
@@ -0,0 +1,76 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Payment Domain',
+  group: 'Getting Started',
+  description: 'Payment processing with RabbitMQ messaging',
+  source: {
+    'main.ec': `visualizer main {
+  name "Payment Domain"
+
+  channel PaymentEvents {
+    version 1.0.0
+    address "payments.events"
+    protocol "rabbitmq"
+    summary "RabbitMQ exchange for payment events"
+  }
+
+  channel PaymentCommands {
+    version 1.0.0
+    address "payments.commands"
+    protocol "http"
+    summary "HTTP API for payment commands"
+  }
+
+  domain Payment {
+    version 1.0.0
+    summary "Handles all payment processing"
+
+    container PaymentsDB {
+      version 1.0.0
+      container-type database
+      technology "PostgreSQL 15"
+      summary "Stores all payment transactions and state"
+    }
+
+    service PaymentService {
+      version 1.0.0
+      summary "Processes payments and refunds"
+
+      writes-to container PaymentsDB
+      reads-from container PaymentsDB
+
+      sends event PaymentProcessed to PaymentEvents {
+        version 1.0.0
+        summary "Emitted when a payment completes successfully"
+      }
+
+      sends event PaymentFailed to PaymentEvents {
+        version 1.0.0
+        summary "Emitted when a payment fails"
+      }
+
+      receives command ProcessPayment from PaymentCommands {
+        version 1.0.0
+        summary "Command to initiate payment processing"
+      }
+    }
+  }
+
+  service NotificationService {
+    version 1.0.0
+    summary "Sends notifications to users"
+
+    receives event PaymentProcessed from PaymentEvents
+
+    receives event PaymentFailed from PaymentEvents
+
+    sends event NotificationSent {
+      version 1.0.0
+      summary "Notification delivered to customer"
+    }
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/02-order-service-showcase.ts b/packages/playground/src/examples/02-order-service-showcase.ts
new file mode 100644
index 000000000..eeb8fd373
--- /dev/null
+++ b/packages/playground/src/examples/02-order-service-showcase.ts
@@ -0,0 +1,214 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Order Service Showcase',
+  group: 'Getting Started',
+  description: 'Service with events, drafts, deprecations, notes, and channels',
+  source: {
+    'main.ec': `import {
+  OrderCreated, OrderConfirmed, OrderShipped, OrderCancelled, OrderCancelledV2,
+  PaymentProcessed, PaymentFailed, StockReserved, StockUnavailable,
+  NotificationSent, LegacyOrderCreated,
+  CreateOrder, CancelOrder, GetOrderStatus
+} from "./messages.ec"
+
+import {
+  OrderService, PaymentService, InventoryService,
+  NotificationService, LegacyOrderAdapter, AnalyticsIngestion
+} from "./services.ec"
+
+visualizer main {
+  name "Order Service Showcase"
+  legend true
+
+  channel OrderStream {
+    version 1.0.0
+    address "orders.stream"
+    protocol "kafka"
+    summary "Kafka topic for all order-related events"
+    @note("Partition key is orderId — 12 partitions", author: "infra-team")
+    @note("Retention: 14 days", author: "infra-team")
+  }
+
+  channel NotificationQueue {
+    version 1.0.0
+    address "notifications.queue"
+    protocol "rabbitmq"
+    summary "RabbitMQ queue for notification delivery"
+  }
+
+  channel LegacyOrderQueue {
+    version 1.0.0
+    address "legacy.orders"
+    protocol "rabbitmq"
+    summary "Legacy queue — being decommissioned"
+    @note("No new consumers should connect to this queue", priority: "high")
+  }
+
+  service OrderService
+  service PaymentService
+  service InventoryService
+  service NotificationService
+  service LegacyOrderAdapter
+  service AnalyticsIngestion
+}
+`,
+    'services.ec': `service OrderService {
+  version 2.0.0
+  summary "Core service for managing the order lifecycle"
+  @note("v2 adds support for multi-currency orders", author: "alice")
+  @note("Load test before Black Friday — target 5k req/s", author: "bob", priority: "high")
+  @note("Migrating from REST to gRPC for internal calls", author: "alice")
+
+  sends event OrderCreated to OrderStream
+  sends event OrderConfirmed to OrderStream
+  sends event OrderShipped to OrderStream
+  sends event OrderCancelled to OrderStream
+  sends event OrderCancelledV2 to OrderStream
+
+  receives command CreateOrder
+  receives command CancelOrder
+  receives query GetOrderStatus
+}
+
+service PaymentService {
+  version 1.0.0
+  summary "Processes payments and refunds"
+  @note("Integrates with Stripe and Adyen", author: "dave")
+
+  receives event OrderCreated from OrderStream
+
+  sends event PaymentProcessed to OrderStream
+  sends event PaymentFailed to OrderStream
+}
+
+service InventoryService {
+  version 1.0.0
+  summary "Manages stock levels and reservations"
+
+  receives event OrderCreated from OrderStream
+  receives event OrderCancelled from OrderStream
+
+  sends event StockReserved to OrderStream
+  sends event StockUnavailable to OrderStream
+}
+
+service NotificationService {
+  version 1.0.0
+  summary "Sends email, SMS, and push notifications"
+
+  receives event OrderConfirmed from OrderStream
+  receives event OrderShipped from OrderStream
+  receives event OrderCancelled from OrderStream
+  receives event PaymentFailed from OrderStream
+
+  sends event NotificationSent to NotificationQueue
+}
+
+service LegacyOrderAdapter {
+  version 1.0.0
+  summary "Bridges events to the legacy order system"
+  deprecated true
+  @note("Decommission by Q3 2026", priority: "high")
+  @note("Only handles APAC region traffic", author: "carol")
+  @note("See migration runbook: https://wiki.internal/legacy-orders", author: "bob")
+
+  receives event OrderCreated from OrderStream
+  receives event OrderCancelled from OrderStream
+
+  sends event LegacyOrderCreated to LegacyOrderQueue
+}
+
+service AnalyticsIngestion {
+  version 1.0.0
+  summary "Ingests order events into the data warehouse"
+  draft true
+  @note("Planned for Q2 2026 — depends on new Snowflake cluster", author: "dave")
+
+  receives event OrderCreated from OrderStream
+  receives event OrderConfirmed from OrderStream
+  receives event OrderShipped from OrderStream
+  receives event PaymentProcessed from OrderStream
+}
+`,
+    'messages.ec': `event OrderCreated {
+  version 1.0.0
+  summary "Emitted when a customer places a new order"
+  @note("Schema v2 adds shippingAddress field — deploy consumer updates first", author: "alice")
+}
+
+event OrderConfirmed {
+  version 1.0.0
+  summary "Order confirmed after payment and stock checks"
+}
+
+event OrderShipped {
+  version 1.0.0
+  summary "Order dispatched from the warehouse"
+}
+
+event OrderCancelled {
+  version 1.0.0
+  summary "Order cancelled by customer or system"
+  deprecated true
+  @note("Use OrderCancelledV2 instead — this lacks cancellation reason", priority: "high")
+}
+
+event OrderCancelledV2 {
+  version 1.0.0
+  summary "Order cancelled with structured reason codes"
+  draft true
+  @note("Rolling out to EU region first", author: "carol")
+}
+
+event PaymentProcessed {
+  version 1.0.0
+  summary "Payment completed successfully"
+}
+
+event PaymentFailed {
+  version 1.0.0
+  summary "Payment was declined or errored"
+}
+
+event StockReserved {
+  version 1.0.0
+  summary "Inventory reserved for an order"
+}
+
+event StockUnavailable {
+  version 1.0.0
+  summary "Requested items are out of stock"
+}
+
+event NotificationSent {
+  version 1.0.0
+  summary "Notification delivered to customer"
+}
+
+event LegacyOrderCreated {
+  version 1.0.0
+  summary "Legacy format order event"
+  deprecated true
+}
+
+command CreateOrder {
+  version 1.0.0
+  summary "Place a new order"
+  @note("Validate idempotency key before processing", author: "bob", priority: "high")
+}
+
+command CancelOrder {
+  version 1.0.0
+  summary "Request order cancellation"
+}
+
+query GetOrderStatus {
+  version 1.0.0
+  summary "Retrieve current order status"
+  draft true
+  @note("Will replace polling with push notifications in v2", author: "alice")
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/03-minimal-service.ts b/packages/playground/src/examples/03-minimal-service.ts
new file mode 100644
index 000000000..b700829b6
--- /dev/null
+++ b/packages/playground/src/examples/03-minimal-service.ts
@@ -0,0 +1,23 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Minimal Service',
+  group: 'Getting Started',
+  description: 'Simplest possible service definition',
+  source: {
+    'main.ec': `visualizer main {
+  service UserService {
+    version 1.0.0
+    summary "Manages user accounts"
+
+    sends event UserCreated
+    sends event UserUpdated
+
+    receives command CreateUser
+    receives command UpdateUser
+    receives query GetUser
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/04-ecommerce-platform.ts b/packages/playground/src/examples/04-ecommerce-platform.ts
new file mode 100644
index 000000000..9ed1d70fa
--- /dev/null
+++ b/packages/playground/src/examples/04-ecommerce-platform.ts
@@ -0,0 +1,101 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'E-Commerce Platform',
+  group: 'Architecture Patterns',
+  description: 'E-commerce with Kafka messaging and HTTP commands',
+  source: {
+    'main.ec': `visualizer main {
+  name "E-Commerce Platform"
+
+  channel OrderEvents {
+    version 1.0.0
+    address "orders.events"
+    protocol "kafka"
+  }
+
+  channel CommandAPI {
+    version 1.0.0
+    address "/api/v1"
+    protocol "http"
+  }
+
+  domain Orders {
+    version 1.0.0
+    summary "Everything related to order management"
+
+    service OrderService {
+      version 1.0.0
+      summary "Manages order lifecycle"
+
+      sends event OrderCreated to OrderEvents {
+        version 1.0.0
+        summary "New order has been placed"
+      }
+
+      sends event OrderUpdated to OrderEvents {
+        version 1.0.0
+        summary "Order details have changed"
+      }
+
+      sends command ProcessPayment to CommandAPI
+
+      receives event PaymentProcessed from OrderEvents
+
+      receives event InventoryReserved
+    }
+  }
+
+  domain Payment {
+    version 1.0.0
+    summary "Payment processing domain"
+
+    service PaymentService {
+      version 1.0.0
+      summary "Handles payment transactions"
+
+      receives command ProcessPayment from CommandAPI {
+        version 1.0.0
+      }
+
+      sends event PaymentProcessed to OrderEvents {
+        version 1.0.0
+        summary "Payment completed successfully"
+      }
+
+      sends event PaymentFailed to OrderEvents {
+        version 1.0.0
+      }
+    }
+  }
+
+  service InventoryService {
+    version 1.0.0
+    summary "Manages product inventory"
+
+    receives event OrderCreated from OrderEvents
+
+    sends event InventoryReserved {
+      version 1.0.0
+      summary "Inventory reserved for order"
+    }
+
+    sends event InventoryReleased {
+      version 1.0.0
+    }
+  }
+
+  service NotificationService {
+    version 1.0.0
+    summary "Sends email and push notifications"
+
+    receives event OrderCreated from OrderEvents
+
+    receives event PaymentProcessed from OrderEvents
+
+    receives event PaymentFailed from OrderEvents
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/05-event-driven-saga.ts b/packages/playground/src/examples/05-event-driven-saga.ts
new file mode 100644
index 000000000..738e3e7f8
--- /dev/null
+++ b/packages/playground/src/examples/05-event-driven-saga.ts
@@ -0,0 +1,86 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Event-Driven Saga',
+  group: 'Architecture Patterns',
+  description: 'Choreography-based saga with NServiceBus',
+  source: {
+    'main.ec': `visualizer main {
+  name "Order Fulfillment Saga"
+
+  channel SagaEvents {
+    version 1.0.0
+    address "saga.events"
+    protocol "nservicebus"
+    summary "NServiceBus for saga coordination"
+  }
+
+  service OrderService {
+    version 1.0.0
+    summary "Order orchestration"
+
+    sends event OrderPlaced to SagaEvents {
+      version 1.0.0
+      summary "Customer placed a new order"
+    }
+
+    receives event PaymentConfirmed from SagaEvents
+
+    receives event PaymentRejected from SagaEvents
+
+    receives event StockReserved from SagaEvents
+
+    receives event StockUnavailable from SagaEvents
+
+    sends event OrderConfirmed to SagaEvents {
+      version 1.0.0
+      summary "Order fully confirmed"
+    }
+
+    sends event OrderRejected to SagaEvents {
+      version 1.0.0
+    }
+  }
+
+  service PaymentService {
+    version 1.0.0
+    summary "Payment processing"
+
+    receives event OrderPlaced from SagaEvents
+
+    sends event PaymentConfirmed to SagaEvents {
+      version 1.0.0
+    }
+
+    sends event PaymentRejected to SagaEvents {
+      version 1.0.0
+    }
+  }
+
+  service InventoryService {
+    version 1.0.0
+    summary "Stock management"
+
+    receives event OrderPlaced from SagaEvents
+
+    sends event StockReserved to SagaEvents {
+      version 1.0.0
+    }
+
+    sends event StockUnavailable to SagaEvents {
+      version 1.0.0
+    }
+  }
+
+  service EmailService {
+    version 1.0.0
+    summary "Customer communications"
+
+    receives event OrderConfirmed from SagaEvents
+
+    receives event OrderRejected from SagaEvents
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/06-data-products.ts b/packages/playground/src/examples/06-data-products.ts
new file mode 100644
index 000000000..8567f57d9
--- /dev/null
+++ b/packages/playground/src/examples/06-data-products.ts
@@ -0,0 +1,74 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Data Products',
+  group: 'Architecture Patterns',
+  description: 'Analytical data products with inputs and outputs',
+  source: {
+    'main.ec': `visualizer main {
+  name "Analytics Platform"
+
+  channel EventBus {
+    version 1.0.0
+    address "analytics.events"
+    protocol "kafka"
+  }
+
+  service OrderService {
+    version 1.0.0
+    summary "Manages order lifecycle"
+
+    sends event OrderCreated to EventBus {
+      version 1.0.0
+      summary "New order has been placed"
+    }
+
+    sends event OrderCompleted to EventBus {
+      version 1.0.0
+      summary "Order has been fulfilled"
+    }
+  }
+
+  service PaymentService {
+    version 1.0.0
+    summary "Handles payment processing"
+
+    sends event PaymentProcessed to EventBus {
+      version 1.0.0
+      summary "Payment completed successfully"
+    }
+  }
+
+  data-product OrderAnalytics {
+    version 1.0.0
+    name "Order Analytics Dataset"
+    summary "Aggregated order and payment data for business intelligence"
+
+    input event OrderCreated
+    input event OrderCompleted
+    input event PaymentProcessed
+
+    output event OrderMetrics {
+      contract {
+        path "./schemas/order-metrics.json"
+        name "OrderMetricsSchema"
+        type "json-schema"
+      }
+    }
+
+    output event CustomerInsights
+  }
+
+  data-product RevenueReporting {
+    version 1.0.0
+    summary "Revenue analysis and reporting"
+
+    input event PaymentProcessed
+
+    output event DailyRevenue
+    output event MonthlyRevenue
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/07-multi-file-imports.ts b/packages/playground/src/examples/07-multi-file-imports.ts
new file mode 100644
index 000000000..633df7fc3
--- /dev/null
+++ b/packages/playground/src/examples/07-multi-file-imports.ts
@@ -0,0 +1,85 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Multi-File with Imports',
+  group: 'DSL Features',
+  description: 'Demonstrates splitting definitions across files with imports',
+  source: {
+    'main.ec': `import { PaymentService, PaymentProcessed, PaymentFailed } from "./payment.ec"
+import { OrderService, OrderCreated } from "./order.ec"
+
+visualizer main {
+  name "E-Commerce System"
+
+  channel MessageBus {
+    version 1.0.0
+    address "events.stream"
+    protocol "kafka"
+  }
+
+  service PaymentService
+  service OrderService
+
+  service NotificationService {
+    version 1.0.0
+    summary "Sends notifications for important events"
+
+    receives event PaymentProcessed from MessageBus
+
+    receives event PaymentFailed from MessageBus
+
+    receives event OrderCreated from MessageBus
+
+    sends event NotificationSent {
+      version 1.0.0
+      summary "Notification delivered to user"
+    }
+  }
+}
+`,
+    'payment.ec': `domain Payment {
+  version 1.0.0
+  summary "Payment processing domain"
+
+  service PaymentService {
+    version 1.0.0
+    summary "Handles payment transactions"
+
+    sends event PaymentProcessed {
+      version 1.0.0
+      summary "Payment completed successfully"
+    }
+
+    sends event PaymentFailed {
+      version 1.0.0
+      summary "Payment processing failed"
+    }
+
+    receives command ProcessPayment {
+      version 1.0.0
+      summary "Initiate payment processing"
+    }
+  }
+}
+`,
+    'order.ec': `domain Orders {
+  version 1.0.0
+  summary "Order management domain"
+
+  service OrderService {
+    version 1.0.0
+    summary "Manages order lifecycle"
+
+    sends event OrderCreated {
+      version 1.0.0
+      summary "New order created"
+    }
+
+    sends command ProcessPayment
+
+    receives event PaymentProcessed
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/08-remote-url-imports.ts b/packages/playground/src/examples/08-remote-url-imports.ts
new file mode 100644
index 000000000..534e92274
--- /dev/null
+++ b/packages/playground/src/examples/08-remote-url-imports.ts
@@ -0,0 +1,37 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Remote URL Imports',
+  group: 'DSL Features',
+  description: 'Import definitions from remote URLs (GitHub, Gist, etc.)',
+  source: {
+    'main.ec': `import { PaymentService, PaymentProcessed, PaymentFailed } from "https://gist.githubusercontent.com/boyney123/f5aa33c20a656f6c1d9dbba7f30f5569/raw/a8a6830f19649ded18221c69525a73016364b63a/gistfile1.txt"
+
+visualizer main {
+  name "Remote Import Example"
+
+  channel EventStream {
+    version 1.0.0
+    address "events.stream"
+    protocol "rabbitmq"
+  }
+
+  service PaymentService
+
+  service NotificationService {
+    version 1.0.0
+    summary "Sends payment notifications"
+
+    receives event PaymentProcessed from EventStream
+
+    receives event PaymentFailed from EventStream
+
+    sends event EmailSent {
+      version 1.0.0
+      summary "Notification email sent to customer"
+    }
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/09-banking-subdomains.ts b/packages/playground/src/examples/09-banking-subdomains.ts
new file mode 100644
index 000000000..f4282df66
--- /dev/null
+++ b/packages/playground/src/examples/09-banking-subdomains.ts
@@ -0,0 +1,212 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Banking with Subdomains',
+  group: 'Architecture Patterns',
+  description: 'Banking domain organized with subdomains for different banking functions',
+  source: {
+    'main.ec': `visualizer main {
+  name "Banking Platform"
+  legend true
+
+  channel BankingEvents {
+    version 1.0.0
+    address "banking.events"
+    protocol "kafka"
+  }
+
+  channel BankingCommands {
+    version 1.0.0
+    address "/api/v1"
+    protocol "http"
+  }
+
+  domain Banking {
+    version 1.0.0
+    summary "Core banking domain with customer accounts, payments, and loans"
+
+    subdomain Accounts {
+      version 1.0.0
+      summary "Customer account management and transactions"
+
+      container AccountsDB {
+        version 1.0.0
+        container-type database
+        technology "PostgreSQL 15"
+        summary "Stores customer account data"
+      }
+
+      service AccountService {
+        version 1.0.0
+        summary "Manages customer accounts and balances"
+
+        writes-to container AccountsDB
+        reads-from container AccountsDB
+
+        sends event AccountOpened to BankingEvents {
+          version 1.0.0
+          summary "New customer account created"
+        }
+
+        sends event AccountClosed to BankingEvents {
+          version 1.0.0
+          summary "Customer account closed"
+        }
+
+        sends event BalanceUpdated to BankingEvents {
+          version 1.0.0
+          summary "Account balance changed"
+        }
+
+        receives command OpenAccount from BankingCommands {
+          version 1.0.0
+          summary "Open a new customer account"
+        }
+
+        receives command CloseAccount from BankingCommands {
+          version 1.0.0
+          summary "Close an existing account"
+        }
+
+        receives event TransactionCompleted from BankingEvents
+        receives event LoanDisbursed from BankingEvents
+      }
+    }
+
+    subdomain Payments {
+      version 1.0.0
+      summary "Payment processing and transfers"
+
+      container PaymentsDB {
+        version 1.0.0
+        container-type database
+        technology "PostgreSQL 15"
+        summary "Stores payment transactions"
+      }
+
+      service PaymentService {
+        version 1.0.0
+        summary "Processes payments and transfers between accounts"
+
+        writes-to container PaymentsDB
+        reads-from container PaymentsDB
+
+        sends event PaymentInitiated to BankingEvents {
+          version 1.0.0
+          summary "Payment process started"
+        }
+
+        sends event TransactionCompleted to BankingEvents {
+          version 1.0.0
+          summary "Payment successfully completed"
+        }
+
+        sends event TransactionFailed to BankingEvents {
+          version 1.0.0
+          summary "Payment failed"
+        }
+
+        receives command ProcessPayment from BankingCommands {
+          version 1.0.0
+          summary "Process a payment transaction"
+        }
+
+        receives command TransferFunds from BankingCommands {
+          version 1.0.0
+          summary "Transfer funds between accounts"
+        }
+
+        receives event AccountOpened from BankingEvents
+      }
+    }
+
+    subdomain Loans {
+      version 1.0.0
+      summary "Loan origination and management"
+
+      container LoansDB {
+        version 1.0.0
+        container-type database
+        technology "PostgreSQL 15"
+        summary "Stores loan applications and details"
+      }
+
+      service LoanService {
+        version 1.0.0
+        summary "Manages loan applications and disbursements"
+
+        writes-to container LoansDB
+        reads-from container LoansDB
+
+        sends event LoanApplicationSubmitted to BankingEvents {
+          version 1.0.0
+          summary "Customer submitted loan application"
+        }
+
+        sends event LoanApproved to BankingEvents {
+          version 1.0.0
+          summary "Loan application approved"
+        }
+
+        sends event LoanRejected to BankingEvents {
+          version 1.0.0
+          summary "Loan application rejected"
+        }
+
+        sends event LoanDisbursed to BankingEvents {
+          version 1.0.0
+          summary "Loan funds disbursed to account"
+        }
+
+        receives command ApplyForLoan from BankingCommands {
+          version 1.0.0
+          summary "Submit a new loan application"
+        }
+
+        receives command ApproveLoan from BankingCommands {
+          version 1.0.0
+          summary "Approve a loan application"
+        }
+
+        receives event AccountOpened from BankingEvents
+        receives event BalanceUpdated from BankingEvents
+      }
+    }
+  }
+
+  service NotificationService {
+    version 1.0.0
+    summary "Sends notifications to customers"
+
+    receives event AccountOpened from BankingEvents
+    receives event TransactionCompleted from BankingEvents
+    receives event LoanApproved from BankingEvents
+    receives event LoanRejected from BankingEvents
+
+    sends event EmailSent {
+      version 1.0.0
+      summary "Email notification sent to customer"
+    }
+
+    sends event SMSSent {
+      version 1.0.0
+      summary "SMS notification sent to customer"
+    }
+  }
+
+  service FraudDetectionService {
+    version 1.0.0
+    summary "Monitors transactions for fraudulent activity"
+
+    receives event PaymentInitiated from BankingEvents
+    receives event TransactionCompleted from BankingEvents
+
+    sends event FraudAlertRaised {
+      version 1.0.0
+      summary "Suspicious activity detected"
+    }
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/10-planning-future-services.ts b/packages/playground/src/examples/10-planning-future-services.ts
new file mode 100644
index 000000000..58f8b0b18
--- /dev/null
+++ b/packages/playground/src/examples/10-planning-future-services.ts
@@ -0,0 +1,163 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Planning Future Services',
+  group: 'Architecture Patterns',
+  description: 'Demonstrates planning future services and migrations using draft mode',
+  source: {
+    'main.ec': `visualizer main {
+  name "Service Migration Planning"
+  legend true
+
+  channel EventBus {
+    version 1.0.0
+    address "events.stream"
+    protocol "Kafka"
+  }
+
+  channel LegacyQueue {
+    version 1.0.0
+    address "legacy.queue"
+    protocol "RabbitMQ"
+  }
+
+  channel RESTAPI {
+    version 1.0.0
+    address "/api/v1"
+    protocol "HTTP"
+  }
+
+  channel GraphQLAPI {
+    version 1.0.0
+    address "/graphql"
+    protocol "HTTP"
+  }
+
+  container OrdersDB {
+    version 1.0.0
+    container-type database
+    technology "PostgreSQL 15"
+    summary "Stores order data"
+  }
+
+  container OrderReadDB {
+    version 1.0.0
+    container-type database
+    technology "MongoDB 7"
+    summary "Denormalized read model for fast queries"
+  }
+
+  container InventoryDB {
+    version 1.0.0
+    container-type database
+    technology "PostgreSQL 15"
+    summary "Tracks inventory levels"
+  }
+
+  container AnalyticsDB {
+    version 1.0.0
+    container-type dataWarehouse
+    technology "Snowflake"
+    summary "Data warehouse for analytics"
+  }
+
+  domain Orders {
+    version 1.0.0
+    summary "Order management domain - currently being modernized"
+
+    service LegacyOrderService {
+      version 1.0.0
+      summary "Legacy monolithic order service - being phased out"
+      deprecated true
+      @note("Decommission by Q3 2026", priority: "high")
+      @note("Migration guide: https://wiki.internal/legacy-migration")
+
+      sends event OrderCreated to LegacyQueue
+      sends event OrderProcessed to LegacyQueue
+      receives command CreateOrder from RESTAPI
+    }
+
+    service OrderService {
+      version 1.0.0
+      summary "Modern order service - currently in production"
+      @note("Needs load testing before handling legacy traffic")
+
+      writes-to container OrdersDB
+      reads-from container OrdersDB
+
+      sends event OrderCreated to EventBus
+      sends event OrderValidated to EventBus
+      sends event OrderSubmitted to EventBus
+
+      receives command CreateOrder from RESTAPI
+      receives command ValidateOrder from RESTAPI
+    }
+
+    service OrderQueryService {
+      version 1.0.0
+      summary "Query service for order data - planned for Q2 2026"
+      draft true
+
+      writes-to container OrderReadDB
+      reads-from container OrderReadDB
+
+      receives event OrderCreated from EventBus
+      receives event OrderValidated from EventBus
+      receives event OrderSubmitted from EventBus
+
+      receives query GetOrder from GraphQLAPI
+      receives query SearchOrders from GraphQLAPI
+    }
+  }
+
+  domain Fulfillment {
+    version 1.0.0
+    summary "Order fulfillment and shipping"
+
+    service FulfillmentService {
+      version 1.0.0
+      summary "Handles order fulfillment - currently in production"
+
+      receives event OrderSubmitted from EventBus
+      sends event OrderFulfilled to EventBus
+      sends event OrderShipped to EventBus
+    }
+
+    service InventoryReservationService {
+      version 1.0.0
+      summary "Reserves inventory for orders - planned for Q3 2026"
+      draft true
+
+      writes-to container InventoryDB
+      reads-from container InventoryDB
+
+      receives event OrderValidated from EventBus
+      sends event InventoryReserved to EventBus
+      sends event InventoryUnavailable to EventBus
+    }
+  }
+
+  service NotificationService {
+    version 1.0.0
+    summary "Sends customer notifications"
+
+    receives event OrderCreated from EventBus
+    receives event OrderShipped from EventBus
+    sends event EmailSent
+  }
+
+  service AnalyticsService {
+    version 1.0.0
+    summary "Real-time analytics and reporting - planned for Q2 2026"
+    draft true
+
+    writes-to container AnalyticsDB
+
+    receives event OrderCreated from EventBus
+    receives event OrderFulfilled from EventBus
+    receives event OrderShipped from EventBus
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/11-enterprise-ecommerce.ts b/packages/playground/src/examples/11-enterprise-ecommerce.ts
new file mode 100644
index 000000000..0ad488b7c
--- /dev/null
+++ b/packages/playground/src/examples/11-enterprise-ecommerce.ts
@@ -0,0 +1,395 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Enterprise E-Commerce',
+  group: 'Architecture Patterns',
+  description: 'Complex enterprise system with 8 domains and multiple channels',
+  source: {
+    'main.ec': `import { Orders, OrderService, OrderCreated, OrderShipped, OrderCancelled } from "./orders.ec"
+import { Payment, PaymentService, PaymentProcessed, PaymentFailed } from "./payment.ec"
+import { Inventory, InventoryService, StockReserved, StockReleased } from "./inventory.ec"
+import { Shipping, ShippingService, ShipmentCreated, ShipmentDelivered } from "./shipping.ec"
+import { Customer, CustomerService, CustomerRegistered, CustomerUpdated } from "./customer.ec"
+import { Marketing, CampaignService, CampaignStarted, EmailSent } from "./marketing.ec"
+import { Analytics, AnalyticsService } from "./analytics.ec"
+import { Notifications, NotificationService } from "./notifications.ec"
+
+visualizer main {
+  name "Enterprise E-Commerce Platform"
+  legend true
+  search true
+
+  domain Orders
+  domain Payment
+  domain Inventory
+  domain Shipping
+  domain Customer
+  domain Marketing
+  domain Analytics
+  domain Notifications
+
+  channel OrdersChannel {
+    version 1.0.0
+    address "orders.events"
+    protocol "kafka"
+  }
+
+  channel PaymentsChannel {
+    version 1.0.0
+    address "payments.events"
+    protocol "kafka"
+  }
+
+  channel ShippingChannel {
+    version 1.0.0
+    address "shipping.events"
+    protocol "kafka"
+  }
+
+  channel CommandAPI {
+    version 1.0.0
+    address "/api/v1"
+    protocol "http"
+  }
+
+  data-product CustomerInsights {
+    version 1.0.0
+    summary "Customer behavior and purchase analytics"
+
+    input event OrderCreated
+    input event PaymentProcessed
+    input event CustomerRegistered
+
+    output event CustomerMetrics
+    output event PurchasePatterns {
+      contract {
+        path "./schemas/purchase-patterns.json"
+        name "PurchasePatternsSchema"
+        type "json-schema"
+      }
+    }
+  }
+
+  data-product RevenueAnalytics {
+    version 1.0.0
+    summary "Real-time revenue and sales analytics"
+
+    input event PaymentProcessed
+    input event OrderShipped
+
+    output event DailyRevenue
+    output event MonthlySalesReport
+  }
+}
+`,
+    'orders.ec': `domain Orders {
+  version 1.0.0
+  summary "Order management and lifecycle"
+
+  container OrdersDB {
+    version 1.0.0
+    container-type database
+    technology "PostgreSQL 15"
+    summary "Stores all order data and state"
+  }
+
+  service OrderService {
+    version 1.0.0
+    summary "Manages order creation, updates, and fulfillment"
+
+    writes-to container OrdersDB
+    reads-from container OrdersDB
+
+    sends event OrderCreated {
+      version 1.0.0
+      summary "New order has been placed by customer"
+    }
+
+    sends event OrderShipped {
+      version 1.0.0
+      summary "Order has been shipped to customer"
+    }
+
+    sends event OrderCancelled {
+      version 1.0.0
+      summary "Order has been cancelled"
+    }
+
+    sends command ProcessPayment {
+      version 1.0.0
+      summary "Request payment processing"
+    }
+
+    sends command ReserveStock {
+      version 1.0.0
+      summary "Request inventory reservation"
+    }
+
+    receives event PaymentProcessed
+    receives event PaymentFailed
+    receives event StockReserved
+
+    receives command CancelOrder {
+      version 1.0.0
+      summary "Cancel an existing order"
+    }
+  }
+}
+`,
+    'payment.ec': `domain Payment {
+  version 1.0.0
+  summary "Payment processing and billing"
+
+  container PaymentDB {
+    version 1.0.0
+    container-type database
+    technology "PostgreSQL 15"
+    summary "Stores payment transactions"
+  }
+
+  container PaymentCache {
+    version 1.0.0
+    container-type cache
+    technology "Redis 7"
+    summary "Caches payment status for quick lookups"
+  }
+
+  service PaymentService {
+    version 1.0.0
+    summary "Processes payments and manages billing"
+
+    writes-to container PaymentDB
+    writes-to container PaymentCache
+    reads-from container PaymentCache
+
+    sends event PaymentProcessed {
+      version 1.0.0
+      summary "Payment completed successfully"
+    }
+
+    sends event PaymentFailed {
+      version 1.0.0
+      summary "Payment processing failed"
+    }
+
+    receives command ProcessPayment
+
+    receives command RefundPayment {
+      version 1.0.0
+      summary "Process a refund"
+    }
+  }
+}
+`,
+    'inventory.ec': `domain Inventory {
+  version 1.0.0
+  summary "Inventory and stock management"
+
+  container InventoryDB {
+    version 1.0.0
+    container-type database
+    technology "PostgreSQL 15"
+    summary "Stores product inventory levels"
+  }
+
+  service InventoryService {
+    version 1.0.0
+    summary "Manages product stock levels and reservations"
+
+    writes-to container InventoryDB
+    reads-from container InventoryDB
+
+    sends event StockReserved {
+      version 1.0.0
+      summary "Stock has been reserved for an order"
+    }
+
+    sends event StockReleased {
+      version 1.0.0
+      summary "Reserved stock has been released"
+    }
+
+    sends event LowStockAlert {
+      version 1.0.0
+      summary "Stock level is below threshold"
+    }
+
+    receives command ReserveStock
+
+    receives command ReleaseStock {
+      version 1.0.0
+    }
+
+    receives event OrderCancelled
+  }
+}
+`,
+    'shipping.ec': `domain Shipping {
+  version 1.0.0
+  summary "Shipping and logistics management"
+
+  container ShippingDB {
+    version 1.0.0
+    container-type database
+    technology "MongoDB 6"
+    summary "Stores shipment tracking information"
+  }
+
+  service ShippingService {
+    version 1.0.0
+    summary "Manages shipment creation and tracking"
+
+    writes-to container ShippingDB
+    reads-from container ShippingDB
+
+    sends event ShipmentCreated {
+      version 1.0.0
+      summary "Shipment has been created"
+    }
+
+    sends event ShipmentDelivered {
+      version 1.0.0
+      summary "Shipment delivered to customer"
+    }
+
+    receives event OrderShipped
+
+    receives query GetShipmentStatus {
+      version 1.0.0
+      summary "Query shipment tracking status"
+    }
+  }
+}
+`,
+    'customer.ec': `domain Customer {
+  version 1.0.0
+  summary "Customer identity and profile management"
+
+  container CustomerDB {
+    version 1.0.0
+    container-type database
+    technology "PostgreSQL 15"
+    summary "Stores customer profiles and preferences"
+  }
+
+  service CustomerService {
+    version 1.0.0
+    summary "Manages customer accounts and profiles"
+
+    writes-to container CustomerDB
+    reads-from container CustomerDB
+
+    sends event CustomerRegistered {
+      version 1.0.0
+      summary "New customer account created"
+    }
+
+    sends event CustomerUpdated {
+      version 1.0.0
+      summary "Customer profile updated"
+    }
+
+    receives command RegisterCustomer {
+      version 1.0.0
+    }
+
+    receives command UpdateCustomer {
+      version 1.0.0
+    }
+
+    receives query GetCustomerProfile {
+      version 1.0.0
+    }
+  }
+}
+`,
+    'marketing.ec': `domain Marketing {
+  version 1.0.0
+  summary "Marketing campaigns and customer engagement"
+
+  container CampaignDB {
+    version 1.0.0
+    container-type database
+    technology "MongoDB 6"
+    summary "Stores campaign data and metrics"
+  }
+
+  service CampaignService {
+    version 1.0.0
+    summary "Manages marketing campaigns"
+
+    writes-to container CampaignDB
+    reads-from container CampaignDB
+
+    sends event CampaignStarted {
+      version 1.0.0
+      summary "Marketing campaign has started"
+    }
+
+    sends event EmailSent {
+      version 1.0.0
+      summary "Marketing email sent to customer"
+    }
+
+    receives event CustomerRegistered
+    receives event OrderCreated
+  }
+}
+`,
+    'analytics.ec': `domain Analytics {
+  version 1.0.0
+  summary "Business intelligence and analytics"
+
+  container AnalyticsDB {
+    version 1.0.0
+    container-type dataWarehouse
+    technology "Snowflake"
+    summary "Data warehouse for analytics"
+  }
+
+  service AnalyticsService {
+    version 1.0.0
+    summary "Processes and aggregates business metrics"
+
+    writes-to container AnalyticsDB
+
+    receives event OrderCreated
+    receives event PaymentProcessed
+    receives event ShipmentDelivered
+    receives event CustomerRegistered
+  }
+}
+`,
+    'notifications.ec': `domain Notifications {
+  version 1.0.0
+  summary "Multi-channel notification delivery"
+
+  container NotificationQueue {
+    version 1.0.0
+    container-type cache
+    technology "Redis 7"
+    summary "Queue for pending notifications"
+  }
+
+  service NotificationService {
+    version 1.0.0
+    summary "Sends notifications via email, SMS, and push"
+
+    writes-to container NotificationQueue
+    reads-from container NotificationQueue
+
+    sends event NotificationSent {
+      version 1.0.0
+      summary "Notification delivered to customer"
+    }
+
+    receives event OrderCreated
+    receives event OrderShipped
+    receives event PaymentProcessed
+    receives event PaymentFailed
+    receives event ShipmentDelivered
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/12-notes-annotations.ts b/packages/playground/src/examples/12-notes-annotations.ts
new file mode 100644
index 000000000..d3372ac93
--- /dev/null
+++ b/packages/playground/src/examples/12-notes-annotations.ts
@@ -0,0 +1,100 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Notes & Annotations',
+  group: 'DSL Features',
+  description: 'Attach notes to resources for context, decisions, and reminders',
+  source: {
+    'main.ec': `visualizer main {
+  name "Notes & Annotations"
+  legend true
+
+  channel OrderEvents {
+    version 1.0.0
+    address "orders.events"
+    protocol "kafka"
+    @note("Partition key is orderId", author: "infra-team")
+    @note("Retention set to 7 days")
+  }
+
+  channel PaymentEvents {
+    version 1.0.0
+    address "payments.events"
+    protocol "kafka"
+  }
+
+  domain Orders {
+    version 1.0.0
+    summary "Order management"
+
+    service OrderService {
+      version 1.0.0
+      summary "Handles order lifecycle"
+      @note("Needs rate limiting before Black Friday", author: "alice", priority: "high")
+      @note("Migrating to event sourcing in Q3", author: "bob")
+
+      sends event OrderCreated to OrderEvents {
+        version 1.0.0
+        summary "New order placed"
+        @note("Schema v2 adds shippingAddress field", author: "alice")
+      }
+
+      sends event OrderCancelled to OrderEvents {
+        version 1.0.0
+        summary "Order was cancelled"
+      }
+
+      receives command CreateOrder {
+        version 1.0.0
+        @note("Validate idempotency key before processing", author: "bob", priority: "high")
+      }
+    }
+
+    service LegacyOrderService {
+      version 1.0.0
+      summary "Old monolith — being decommissioned"
+      deprecated true
+      @note("Decommission by Q4 2026", priority: "high")
+      @note("See migration runbook: https://wiki.internal/orders-migration")
+      @note("Only handles EU region traffic now", author: "carol")
+
+      sends event OrderCreated to OrderEvents
+      receives command CreateOrder
+    }
+  }
+
+  domain Payment {
+    version 1.0.0
+    summary "Payment processing"
+
+    service PaymentService {
+      version 2.0.0
+      summary "Processes payments and refunds"
+      @note("v2 adds support for crypto payments", author: "dave")
+
+      receives event OrderCreated from OrderEvents
+
+      sends event PaymentProcessed to PaymentEvents {
+        version 1.0.0
+        summary "Payment completed"
+        @note("Includes refund reference when applicable", author: "dave")
+      }
+
+      sends event PaymentFailed to PaymentEvents {
+        version 1.0.0
+      }
+    }
+  }
+
+  service NotificationService {
+    version 1.0.0
+    summary "Sends customer notifications"
+
+    receives event PaymentProcessed from PaymentEvents
+    receives event PaymentFailed from PaymentEvents
+    receives event OrderCancelled from OrderEvents
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/13-channel-routing.ts b/packages/playground/src/examples/13-channel-routing.ts
new file mode 100644
index 000000000..f75e7f8c6
--- /dev/null
+++ b/packages/playground/src/examples/13-channel-routing.ts
@@ -0,0 +1,86 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Channel Routing',
+  group: 'Architecture Patterns',
+  description: 'IoT pipeline with channel-to-channel routing (Kafka \u2192 Kafka \u2192 MQTT)',
+  source: {
+    'main.ec': `visualizer main {
+  name "IoT Sensor Pipeline"
+  legend true
+
+  channel SensorIngestion {
+    version 1.0.0
+    address "sensors.raw"
+    protocol "Kafka"
+    summary "Raw sensor data ingestion topic"
+    route SensorFiltered
+  }
+
+  channel SensorFiltered {
+    version 1.0.0
+    address "sensors.filtered"
+    protocol "Kafka"
+    summary "Filtered and validated sensor data"
+    route DeviceCommands
+  }
+
+  channel DeviceCommands {
+    version 1.0.0
+    address "devices/+/commands"
+    protocol "MQTT"
+    summary "MQTT topic for device command delivery"
+  }
+
+  service SensorGateway {
+    version 1.0.0
+    summary "Ingests raw sensor readings from IoT devices"
+
+    sends event SensorReading to SensorIngestion {
+      version 1.0.0
+      summary "Raw sensor reading from a device"
+    }
+
+    sends event DeviceHeartbeat to SensorIngestion {
+      version 1.0.0
+      summary "Periodic device health check"
+    }
+  }
+
+  service FilterService {
+    version 1.0.0
+    summary "Validates and filters raw sensor data"
+
+    receives event SensorReading from SensorIngestion
+    receives event DeviceHeartbeat from SensorIngestion
+
+    sends event SensorReading to SensorFiltered
+    sends event DeviceAlert to SensorFiltered {
+      version 1.0.0
+      summary "Alert when device readings are anomalous"
+    }
+  }
+
+  service DeviceBridge {
+    version 1.0.0
+    summary "Bridges Kafka events to MQTT for device delivery"
+
+    receives event DeviceAlert from SensorFiltered
+
+    sends command RecalibrateDevice to DeviceCommands {
+      version 1.0.0
+      summary "Instructs a device to recalibrate its sensors"
+    }
+  }
+
+  service DashboardService {
+    version 1.0.0
+    summary "Real-time monitoring dashboard"
+
+    receives event SensorReading from SensorFiltered
+    receives event DeviceAlert from SensorFiltered
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/14-aws-event-pipeline.ts b/packages/playground/src/examples/14-aws-event-pipeline.ts
new file mode 100644
index 000000000..824ca3ea8
--- /dev/null
+++ b/packages/playground/src/examples/14-aws-event-pipeline.ts
@@ -0,0 +1,205 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'AWS Event Pipeline',
+  group: 'Architecture Patterns',
+  description: 'Cross-domain EventBridge routing with SQS queues on AWS',
+  source: {
+    'main.ec': `visualizer main {
+  name "AWS Event Pipeline"
+
+  domain Orders {
+    version 1.0.0
+    summary "Order management domain"
+
+    channel OrderEventBus {
+      version 1.0.0
+      address "arn:aws:events:us-east-1:123456789:event-bus/orders"
+      protocol "EventBridge"
+      summary "Event bus for the orders domain"
+      route MainEventBus
+    }
+
+    service OrderService {
+      version 1.0.0
+      summary "Handles order creation and lifecycle"
+
+      sends event OrderCreated to OrderEventBus {
+        version 1.0.0
+        summary "Emitted when a customer places an order"
+      }
+
+      sends event OrderShipped to OrderEventBus {
+        version 1.0.0
+        summary "Emitted when an order is shipped"
+      }
+
+      sends event OrderCancelled to OrderEventBus {
+        version 1.0.0
+        summary "Emitted when an order is cancelled"
+      }
+    }
+  }
+
+  domain Fulfillment {
+    version 1.0.0
+    summary "Warehouse and shipping operations"
+
+    channel FulfillmentEventBus {
+      version 1.0.0
+      address "arn:aws:events:us-east-1:123456789:event-bus/fulfillment"
+      protocol "EventBridge"
+      summary "Event bus for the fulfillment domain"
+      route PickingQueue
+      route ShippingQueue
+    }
+
+    channel PickingQueue {
+      version 1.0.0
+      address "arn:aws:sqs:us-east-1:123456789:warehouse-picking"
+      protocol "SQS"
+      summary "Queue for warehouse pick-list generation"
+    }
+
+    channel ShippingQueue {
+      version 1.0.0
+      address "arn:aws:sqs:us-east-1:123456789:shipping-labels"
+      protocol "SQS"
+      summary "Queue for shipping label creation"
+    }
+
+    service WarehouseService {
+      version 1.0.0
+      summary "Manages warehouse picking and packing"
+
+      receives event OrderCreated from PickingQueue
+      receives event OrderCancelled from PickingQueue
+    }
+
+    service ShippingService {
+      version 1.0.0
+      summary "Handles carrier selection and label generation"
+
+      receives event OrderCreated from ShippingQueue
+    }
+  }
+
+  domain Notifications {
+    version 1.0.0
+    summary "Customer communication channels"
+
+    channel NotificationsEventBus {
+      version 1.0.0
+      address "arn:aws:events:us-east-1:123456789:event-bus/notifications"
+      protocol "EventBridge"
+      summary "Event bus for the notifications domain"
+      route EmailQueue
+      route PushQueue
+      route SmsQueue
+    }
+
+    channel EmailQueue {
+      version 1.0.0
+      address "arn:aws:sqs:us-east-1:123456789:email-delivery"
+      protocol "SQS"
+      summary "Queue for transactional email delivery"
+    }
+
+    channel PushQueue {
+      version 1.0.0
+      address "arn:aws:sqs:us-east-1:123456789:push-notifications"
+      protocol "SQS"
+      summary "Queue for mobile push notifications"
+    }
+
+    channel SmsQueue {
+      version 1.0.0
+      address "arn:aws:sqs:us-east-1:123456789:sms-notifications"
+      protocol "SQS"
+      summary "Queue for SMS notifications"
+    }
+
+    service EmailService {
+      version 1.0.0
+      summary "Sends transactional emails to customers"
+
+      receives event OrderCreated from EmailQueue
+      receives event OrderShipped from EmailQueue
+      receives event OrderCancelled from EmailQueue
+    }
+
+    service PushNotificationService {
+      version 1.0.0
+      summary "Sends mobile push notifications"
+
+      receives event OrderShipped from PushQueue
+      receives event OrderCancelled from PushQueue
+    }
+
+    service SmsService {
+      version 1.0.0
+      summary "Sends SMS order updates"
+
+      receives event OrderShipped from SmsQueue
+    }
+  }
+
+  domain Analytics {
+    version 1.0.0
+    summary "Business intelligence and search"
+
+    channel AnalyticsEventBus {
+      version 1.0.0
+      address "arn:aws:events:us-east-1:123456789:event-bus/analytics"
+      protocol "EventBridge"
+      summary "Event bus for the analytics domain"
+      route MetricsQueue
+      route SearchIndexQueue
+    }
+
+    channel MetricsQueue {
+      version 1.0.0
+      address "arn:aws:sqs:us-east-1:123456789:metrics-ingestion"
+      protocol "SQS"
+      summary "Queue for metrics and KPI ingestion"
+    }
+
+    channel SearchIndexQueue {
+      version 1.0.0
+      address "arn:aws:sqs:us-east-1:123456789:search-indexing"
+      protocol "SQS"
+      summary "Queue for search index updates"
+    }
+
+    service MetricsService {
+      version 1.0.0
+      summary "Tracks order metrics and business KPIs"
+
+      receives event OrderCreated from MetricsQueue
+      receives event OrderShipped from MetricsQueue
+      receives event OrderCancelled from MetricsQueue
+    }
+
+    service SearchService {
+      version 1.0.0
+      summary "Maintains product and order search indexes"
+
+      receives event OrderCreated from SearchIndexQueue
+      receives event OrderShipped from SearchIndexQueue
+    }
+  }
+}
+`,
+    'channels.ec': `// Central company-wide event bus — routes to all domain buses
+channel MainEventBus {
+  version 1.0.0
+  address "arn:aws:events:us-east-1:123456789:event-bus/main"
+  protocol "EventBridge"
+  summary "Central company-wide event bus"
+  route FulfillmentEventBus
+  route NotificationsEventBus
+  route AnalyticsEventBus
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/15-flow-order-fulfillment.ts b/packages/playground/src/examples/15-flow-order-fulfillment.ts
new file mode 100644
index 000000000..242e5d2db
--- /dev/null
+++ b/packages/playground/src/examples/15-flow-order-fulfillment.ts
@@ -0,0 +1,129 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Flow: Order Fulfillment',
+  group: 'Flows',
+  description: 'PM-friendly business flow with when-blocks, branching, and convergence',
+  source: {
+    'main.ec': `import { OrderService, PaymentService, InventoryService, FulfillmentService, NotificationService } from "./services.ec"
+import { PlaceOrder, OrderCreated, PaymentProcessed, PaymentFailed, StockReserved, OrderShipped, CustomerNotified } from "./messages.ec"
+
+actor Customer {
+  name "Customer"
+  summary "End user on the storefront"
+}
+
+external-system WarehouseWMS {
+  name "Warehouse WMS"
+  summary "Legacy warehouse management system"
+}
+
+flow OrderFulfillment {
+  version 1.0.0
+  name "Order Fulfillment"
+  summary "End-to-end order processing from placement to delivery"
+
+  Customer "places an order"
+    -> PlaceOrder
+    -> OrderService "creates the order"
+    -> OrderCreated
+
+  when OrderCreated
+    PaymentService "processes the payment"
+      -> "success": PaymentProcessed
+      -> "failure": PaymentFailed
+    InventoryService "reserves stock"
+      -> StockReserved
+
+  when PaymentFailed
+    NotificationService "notifies the customer of failure"
+
+  when PaymentProcessed and StockReserved
+    FulfillmentService "ships the order"
+      -> OrderShipped
+
+  when OrderShipped
+    WarehouseWMS "syncs with legacy WMS"
+    NotificationService "notifies the customer"
+      -> CustomerNotified
+}
+
+visualizer main {
+  name "Order Fulfillment Flow"
+  flow OrderFulfillment@1.0.0
+}
+`,
+    'services.ec': `service OrderService {
+  version 1.0.0
+  name "Order Service"
+  summary "Manages the order lifecycle"
+}
+
+service PaymentService {
+  version 1.0.0
+  name "Payment Service"
+  summary "Processes payments via Stripe"
+}
+
+service InventoryService {
+  version 1.0.0
+  name "Inventory Service"
+  summary "Manages stock and reservations"
+}
+
+service FulfillmentService {
+  version 1.0.0
+  name "Fulfillment Service"
+  summary "Coordinates order shipping"
+}
+
+service NotificationService {
+  version 1.0.0
+  name "Notification Service"
+  summary "Sends email and push notifications"
+}
+`,
+    'messages.ec': `command PlaceOrder {
+  version 1.0.0
+  name "Place Order"
+  summary "Customer places a new order"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "Emitted when a new order is placed"
+}
+
+event PaymentProcessed {
+  version 1.0.0
+  name "Payment Processed"
+  summary "Payment completed successfully"
+}
+
+event PaymentFailed {
+  version 1.0.0
+  name "Payment Failed"
+  summary "Payment was declined or errored"
+}
+
+event StockReserved {
+  version 1.0.0
+  name "Stock Reserved"
+  summary "Inventory reserved for order"
+}
+
+event OrderShipped {
+  version 1.0.0
+  name "Order Shipped"
+  summary "Order has been dispatched"
+}
+
+event CustomerNotified {
+  version 1.0.0
+  name "Customer Notified"
+  summary "Customer received notification"
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/16-flow-ecommerce-checkout.ts b/packages/playground/src/examples/16-flow-ecommerce-checkout.ts
new file mode 100644
index 000000000..404d8f459
--- /dev/null
+++ b/packages/playground/src/examples/16-flow-ecommerce-checkout.ts
@@ -0,0 +1,283 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Flow: E-Commerce Checkout',
+  group: 'Flows',
+  description: 'Complex flow with validation, fraud detection, parallel processing, and multiple failure paths',
+  source: {
+    'main.ec': `import {
+  CartService, ValidationService, FraudDetectionService, PaymentService,
+  InventoryService, ShippingService, TaxService, EmailService,
+  WarehouseService, AccountingService, AnalyticsService
+} from "./services.ec"
+import {
+  InitiateCheckout, CheckoutValidated, ValidationFailed,
+  FraudCheckPassed, FraudDetected, PaymentAuthorized, PaymentFailed,
+  InventoryReserved, InventoryUnavailable, ShippingCalculated,
+  TaxCalculated, OrderConfirmed, OrderCancelled, ShipmentCreated,
+  InvoiceGenerated, ConfirmationEmailSent
+} from "./messages.ec"
+
+actor Customer {
+  name "Customer"
+  summary "End user completing purchase"
+}
+
+external-system PaymentGateway {
+  name "Stripe Payment Gateway"
+  summary "Third-party payment processor"
+}
+
+external-system TaxAPI {
+  name "Avalara Tax API"
+  summary "Tax calculation service"
+}
+
+external-system ShippingCarrier {
+  name "FedEx API"
+  summary "Shipping carrier integration"
+}
+
+flow ECommerceCheckout {
+  version 1.0.0
+  name "E-Commerce Checkout Flow"
+  summary "Complete checkout process with validation, fraud detection, and parallel fulfillment"
+
+  // Entry: customer initiates checkout
+  Customer "initiates checkout"
+    -> InitiateCheckout
+    -> CartService "validates cart"
+    -> CheckoutValidated
+
+  // Parallel validation and fraud check
+  when CheckoutValidated
+    ValidationService "validates customer data"
+      -> "valid": FraudCheckPassed
+      -> "invalid": ValidationFailed
+    FraudDetectionService "runs fraud analysis"
+      -> "pass": FraudCheckPassed
+      -> "fail": FraudDetected
+
+  // Failure path: validation or fraud failed
+  when ValidationFailed
+    EmailService "notifies customer of validation errors"
+
+  when FraudDetected
+    EmailService "notifies fraud team"
+    AnalyticsService "logs fraud attempt"
+
+  // Success path: both checks passed - start payment
+  when FraudCheckPassed
+    PaymentGateway "authorizes payment"
+      -> "authorized": PaymentAuthorized
+      -> "declined": PaymentFailed
+
+  when PaymentFailed
+    CartService "restores cart"
+    EmailService "notifies customer of payment failure"
+
+  // Payment successful - parallel inventory and calculations
+  when PaymentAuthorized
+    InventoryService "reserves stock"
+      -> "reserved": InventoryReserved
+      -> "unavailable": InventoryUnavailable
+    TaxService "calculates tax via API"
+      -> TaxCalculated
+    ShippingService "calculates shipping cost"
+      -> ShippingCalculated
+
+  // Inventory unavailable after payment
+  when InventoryUnavailable
+    PaymentGateway "refunds payment"
+    EmailService "notifies customer of unavailable items"
+
+  // Wait for all three: inventory + tax + shipping
+  when InventoryReserved and TaxCalculated and ShippingCalculated
+    CartService "confirms order"
+      -> OrderConfirmed
+
+  // Order confirmed - parallel fulfillment activities
+  when OrderConfirmed
+    WarehouseService "creates pick ticket"
+      -> ShipmentCreated
+    AccountingService "generates invoice"
+      -> InvoiceGenerated
+    EmailService "sends confirmation email"
+      -> ConfirmationEmailSent
+    AnalyticsService "tracks conversion"
+
+  // Shipment tracking
+  when ShipmentCreated
+    ShippingCarrier "creates shipping label"
+    WarehouseService "assigns to picker"
+}
+
+visualizer main {
+  name "E-Commerce Checkout Flow"
+  flow ECommerceCheckout@1.0.0
+}
+`,
+    'services.ec': `service CartService {
+  version 1.0.0
+  name "Cart Service"
+  summary "Manages shopping cart and checkout"
+}
+
+service ValidationService {
+  version 1.0.0
+  name "Validation Service"
+  summary "Validates customer and order data"
+}
+
+service FraudDetectionService {
+  version 1.0.0
+  name "Fraud Detection Service"
+  summary "Analyzes orders for fraud patterns"
+}
+
+service PaymentService {
+  version 1.0.0
+  name "Payment Service"
+  summary "Processes payments"
+}
+
+service InventoryService {
+  version 1.0.0
+  name "Inventory Service"
+  summary "Manages stock and reservations"
+}
+
+service ShippingService {
+  version 1.0.0
+  name "Shipping Service"
+  summary "Calculates shipping costs and methods"
+}
+
+service TaxService {
+  version 1.0.0
+  name "Tax Service"
+  summary "Calculates taxes via external API"
+}
+
+service EmailService {
+  version 1.0.0
+  name "Email Service"
+  summary "Sends transactional emails"
+}
+
+service WarehouseService {
+  version 1.0.0
+  name "Warehouse Service"
+  summary "Manages warehouse operations"
+}
+
+service AccountingService {
+  version 1.0.0
+  name "Accounting Service"
+  summary "Handles invoicing and accounting"
+}
+
+service AnalyticsService {
+  version 1.0.0
+  name "Analytics Service"
+  summary "Tracks events and conversions"
+}
+`,
+    'messages.ec': `command InitiateCheckout {
+  version 1.0.0
+  name "Initiate Checkout"
+  summary "Customer starts checkout process"
+}
+
+event CheckoutValidated {
+  version 1.0.0
+  name "Checkout Validated"
+  summary "Cart and checkout data validated"
+}
+
+event ValidationFailed {
+  version 1.0.0
+  name "Validation Failed"
+  summary "Customer or order data validation failed"
+}
+
+event FraudCheckPassed {
+  version 1.0.0
+  name "Fraud Check Passed"
+  summary "Order passed fraud detection"
+}
+
+event FraudDetected {
+  version 1.0.0
+  name "Fraud Detected"
+  summary "Potential fraud detected"
+}
+
+event PaymentAuthorized {
+  version 1.0.0
+  name "Payment Authorized"
+  summary "Payment successfully authorized"
+}
+
+event PaymentFailed {
+  version 1.0.0
+  name "Payment Failed"
+  summary "Payment declined or failed"
+}
+
+event InventoryReserved {
+  version 1.0.0
+  name "Inventory Reserved"
+  summary "Stock reserved for order"
+}
+
+event InventoryUnavailable {
+  version 1.0.0
+  name "Inventory Unavailable"
+  summary "Insufficient stock available"
+}
+
+event ShippingCalculated {
+  version 1.0.0
+  name "Shipping Calculated"
+  summary "Shipping cost and method determined"
+}
+
+event TaxCalculated {
+  version 1.0.0
+  name "Tax Calculated"
+  summary "Tax amount calculated"
+}
+
+event OrderConfirmed {
+  version 1.0.0
+  name "Order Confirmed"
+  summary "Order fully confirmed and ready for fulfillment"
+}
+
+event OrderCancelled {
+  version 1.0.0
+  name "Order Cancelled"
+  summary "Order cancelled due to failure"
+}
+
+event ShipmentCreated {
+  version 1.0.0
+  name "Shipment Created"
+  summary "Warehouse shipment created"
+}
+
+event InvoiceGenerated {
+  version 1.0.0
+  name "Invoice Generated"
+  summary "Invoice created for order"
+}
+
+event ConfirmationEmailSent {
+  version 1.0.0
+  name "Confirmation Email Sent"
+  summary "Customer received order confirmation"
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/17-asyncapi-import.ts b/packages/playground/src/examples/17-asyncapi-import.ts
new file mode 100644
index 000000000..375ae3368
--- /dev/null
+++ b/packages/playground/src/examples/17-asyncapi-import.ts
@@ -0,0 +1,152 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'AsyncAPI Import',
+  group: 'Getting Started',
+  description: 'Import events and channels from an AsyncAPI spec into services',
+  source: {
+    'main.ec': `// Events and channels generated from AsyncAPI spec
+import events { OrderCreated, OrderShipped, OrderCancelled } from "./orders-asyncapi.yml"
+import channels { orderCreated, orderShipped, orderCancelled } from "./orders-asyncapi.yml"
+
+visualizer main {
+  name "Order Processing (AsyncAPI Import)"
+
+  // Service that publishes the imported events
+  service OrderService {
+    version 1.0.0
+    summary "Manages order lifecycle"
+
+    sends event OrderCreated to orderCreated
+    sends event OrderShipped to orderShipped
+    sends event OrderCancelled to orderCancelled
+  }
+
+  // New service that consumes events from the AsyncAPI service
+  service ShippingService {
+    version 1.0.0
+    summary "Handles shipping and delivery"
+
+    receives event OrderCreated from orderCreated
+    sends event OrderShipped to orderShipped
+  }
+
+  // New service that consumes events from the AsyncAPI service
+  service NotificationService {
+    version 1.0.0
+    summary "Sends customer notifications"
+
+    receives event OrderShipped from orderShipped
+    receives event OrderCancelled from orderCancelled
+  }
+}
+`,
+    'orders-asyncapi.yml': `asyncapi: 3.0.0
+info:
+  title: Orders Service API
+  version: 1.0.0
+  description: Kafka-based async API for the Orders domain
+
+servers:
+  production:
+    host: kafka.prod.example.com:9092
+    protocol: kafka
+    description: Production Kafka broker
+
+channels:
+  orderCreated:
+    address: orders.created
+    summary: Kafka topic for new order placement events
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+    bindings:
+      kafka:
+        topic: orders.created
+        partitions: 12
+        replicas: 3
+
+  orderShipped:
+    address: orders.shipped
+    summary: Kafka topic for order shipment events
+    messages:
+      OrderShipped:
+        $ref: '#/components/messages/OrderShipped'
+    bindings:
+      kafka:
+        topic: orders.shipped
+        partitions: 6
+        replicas: 3
+
+  orderCancelled:
+    address: orders.cancelled
+    summary: Kafka topic for order cancellation events
+    messages:
+      OrderCancelled:
+        $ref: '#/components/messages/OrderCancelled'
+    bindings:
+      kafka:
+        topic: orders.cancelled
+        partitions: 6
+        replicas: 3
+
+components:
+  messages:
+    OrderCreated:
+      summary: Fired when a new order is placed by a customer
+      contentType: application/json
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            format: uuid
+          customerId:
+            type: string
+          totalAmount:
+            type: number
+          items:
+            type: array
+          createdAt:
+            type: string
+            format: date-time
+      bindings:
+        kafka:
+          key:
+            type: string
+            description: The order ID used as partition key
+
+    OrderShipped:
+      summary: Fired when an order has been shipped
+      contentType: application/json
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            format: uuid
+          trackingNumber:
+            type: string
+          carrier:
+            type: string
+          shippedAt:
+            type: string
+            format: date-time
+
+    OrderCancelled:
+      summary: Fired when an order is cancelled
+      contentType: application/json
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            format: uuid
+          reason:
+            type: string
+          cancelledAt:
+            type: string
+            format: date-time
+`,
+  },
+};
diff --git a/packages/playground/src/examples/18-asyncapi-remote-import.ts b/packages/playground/src/examples/18-asyncapi-remote-import.ts
new file mode 100644
index 000000000..21189f4e0
--- /dev/null
+++ b/packages/playground/src/examples/18-asyncapi-remote-import.ts
@@ -0,0 +1,44 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'AsyncAPI Remote Import',
+  group: 'Getting Started',
+  description: 'Import events and channels from a remote AsyncAPI spec via URL',
+  source: {
+    'main.ec': `// Events and channels generated from remote AsyncAPI spec
+import events { lightMeasured, turnOnOff, dimLight } from "https://raw.githubusercontent.com/asyncapi/spec/master/examples/streetlights-kafka-asyncapi.yml"
+import channels { lightingMeasured, lightTurnOn, lightsDim } from "https://raw.githubusercontent.com/asyncapi/spec/master/examples/streetlights-kafka-asyncapi.yml"
+
+visualizer main {
+  name "Streetlights (Remote AsyncAPI Import)"
+
+  // Service that uses the imported events and channels
+  service StreetlightsAPI {
+    version 1.0.0
+    summary "Controls city streetlight infrastructure"
+
+    sends event lightMeasured to lightingMeasured
+    receives event turnOnOff from lightTurnOn
+    receives event dimLight from lightsDim
+  }
+
+  // New service that consumes events from the AsyncAPI service
+  service LightingDashboard {
+    version 1.0.0
+    summary "Monitoring dashboard for streetlights"
+
+    receives event lightMeasured from lightingMeasured
+  }
+
+  // New service that sends commands to the AsyncAPI service
+  service LightController {
+    version 1.0.0
+    summary "Automated light control system"
+
+    sends event turnOnOff to lightTurnOn
+    sends event dimLight to lightsDim
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/19-asyncapi-service-import.ts b/packages/playground/src/examples/19-asyncapi-service-import.ts
new file mode 100644
index 000000000..68087cca6
--- /dev/null
+++ b/packages/playground/src/examples/19-asyncapi-service-import.ts
@@ -0,0 +1,121 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'AsyncAPI Service Import',
+  group: 'Getting Started',
+  description: 'Import a full service with channels and operations inferred from an AsyncAPI spec',
+  source: {
+    'main.ec': `// Full service generated from AsyncAPI spec (events, channels, and service definition)
+import OrderService from "./orders-asyncapi.yml"
+
+visualizer main {
+  name "Order Processing (Full Service Import)"
+
+  // Generated from AsyncAPI spec
+  service OrderService
+
+  // New service that integrates with the AsyncAPI service
+  service NotificationService {
+    version 1.0.0
+    summary "Sends customer notifications"
+
+    receives event OrderCreated from orderCreated
+    receives event OrderShipped from orderShipped
+  }
+}
+`,
+    'orders-asyncapi.yml': `asyncapi: 3.0.0
+info:
+  title: Order Service
+  version: 1.0.0
+  description: Manages order lifecycle events via Kafka.
+
+servers:
+  production:
+    host: kafka.prod.example.com:9092
+    protocol: kafka
+    description: Production Kafka broker
+
+channels:
+  orderCreated:
+    address: orders.created
+    summary: Kafka topic for new order events
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+    bindings:
+      kafka:
+        topic: orders.created
+        partitions: 12
+
+  orderShipped:
+    address: orders.shipped
+    summary: Kafka topic for shipment events
+    messages:
+      OrderShipped:
+        $ref: '#/components/messages/OrderShipped'
+
+  orderCancelled:
+    address: orders.cancelled
+    summary: Kafka topic for cancellation events
+    messages:
+      OrderCancelled:
+        $ref: '#/components/messages/OrderCancelled'
+
+operations:
+  publishOrderCreated:
+    action: send
+    channel:
+      $ref: '#/channels/orderCreated'
+    summary: Publishes when a customer places an order
+  publishOrderShipped:
+    action: send
+    channel:
+      $ref: '#/channels/orderShipped'
+    summary: Publishes when an order is shipped
+  onOrderCancelled:
+    action: receive
+    channel:
+      $ref: '#/channels/orderCancelled'
+    summary: Handles order cancellation requests
+
+components:
+  messages:
+    OrderCreated:
+      summary: Fired when a new order is placed
+      contentType: application/json
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            format: uuid
+          customerId:
+            type: string
+          totalAmount:
+            type: number
+    OrderShipped:
+      summary: Fired when an order has been shipped
+      contentType: application/json
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            format: uuid
+          trackingNumber:
+            type: string
+    OrderCancelled:
+      summary: Fired when an order is cancelled
+      contentType: application/json
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+            format: uuid
+          reason:
+            type: string
+`,
+  },
+};
diff --git a/packages/playground/src/examples/20-asyncapi-multi-service.ts b/packages/playground/src/examples/20-asyncapi-multi-service.ts
new file mode 100644
index 000000000..baa582482
--- /dev/null
+++ b/packages/playground/src/examples/20-asyncapi-multi-service.ts
@@ -0,0 +1,231 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'AsyncAPI Multi-Service',
+  group: 'Getting Started',
+  description: 'Three AsyncAPI specs: Orders publishes events, Shipping and Notifications consume them',
+  source: {
+    'main.ec': `// Services generated from multiple AsyncAPI specs
+import OrderService from "./orders-asyncapi.yml"
+import ShippingService from "./shipping-asyncapi.yml"
+import NotificationService from "./notifications-asyncapi.yml"
+
+visualizer main {
+  name "Order Pipeline (Multi-Service AsyncAPI)"
+
+  // Each service is generated from its own AsyncAPI spec
+  service OrderService
+  service ShippingService
+  service NotificationService
+}
+`,
+    'orders-asyncapi.yml': `asyncapi: 3.0.0
+info:
+  title: Order Service
+  version: 1.0.0
+  description: Manages order lifecycle and publishes order events.
+
+servers:
+  production:
+    host: kafka.prod.example.com:9092
+    protocol: kafka
+
+channels:
+  orderCreated:
+    address: orders.created
+    summary: New order placement events
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+  orderPaid:
+    address: orders.paid
+    summary: Successful payment confirmation events
+    messages:
+      OrderPaid:
+        $ref: '#/components/messages/OrderPaid'
+  orderCancelled:
+    address: orders.cancelled
+    summary: Order cancellation events
+    messages:
+      OrderCancelled:
+        $ref: '#/components/messages/OrderCancelled'
+
+operations:
+  publishOrderCreated:
+    action: send
+    channel:
+      $ref: '#/channels/orderCreated'
+  publishOrderPaid:
+    action: send
+    channel:
+      $ref: '#/channels/orderPaid'
+  publishOrderCancelled:
+    action: send
+    channel:
+      $ref: '#/channels/orderCancelled'
+
+components:
+  messages:
+    OrderCreated:
+      summary: Fired when a customer places a new order
+      contentType: application/json
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+          customerId:
+            type: string
+          items:
+            type: array
+          totalAmount:
+            type: number
+    OrderPaid:
+      summary: Fired when payment is confirmed for an order
+      contentType: application/json
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+          paymentId:
+            type: string
+          paidAt:
+            type: string
+            format: date-time
+    OrderCancelled:
+      summary: Fired when an order is cancelled by customer or system
+      contentType: application/json
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+          reason:
+            type: string
+          cancelledAt:
+            type: string
+            format: date-time
+`,
+    'shipping-asyncapi.yml': `asyncapi: 3.0.0
+info:
+  title: Shipping Service
+  version: 1.0.0
+  description: Handles fulfillment by listening for paid orders and cancellations.
+
+servers:
+  production:
+    host: kafka.prod.example.com:9092
+    protocol: kafka
+
+channels:
+  orderPaid:
+    address: orders.paid
+    summary: Successful payment confirmation events
+    messages:
+      OrderPaid:
+        $ref: '#/components/messages/OrderPaid'
+  orderCancelled:
+    address: orders.cancelled
+    summary: Order cancellation events
+    messages:
+      OrderCancelled:
+        $ref: '#/components/messages/OrderCancelled'
+  shipmentDispatched:
+    address: shipping.dispatched
+    summary: Shipment dispatch events
+    messages:
+      ShipmentDispatched:
+        $ref: '#/components/messages/ShipmentDispatched'
+
+operations:
+  onOrderPaid:
+    action: receive
+    channel:
+      $ref: '#/channels/orderPaid'
+  onOrderCancelled:
+    action: receive
+    channel:
+      $ref: '#/channels/orderCancelled'
+  publishShipmentDispatched:
+    action: send
+    channel:
+      $ref: '#/channels/shipmentDispatched'
+
+components:
+  messages:
+    OrderPaid:
+      summary: Fired when payment is confirmed for an order
+    OrderCancelled:
+      summary: Fired when an order is cancelled by customer or system
+    ShipmentDispatched:
+      summary: Fired when a shipment leaves the warehouse
+      contentType: application/json
+      payload:
+        type: object
+        properties:
+          shipmentId:
+            type: string
+          orderId:
+            type: string
+          carrier:
+            type: string
+          trackingNumber:
+            type: string
+`,
+    'notifications-asyncapi.yml': `asyncapi: 3.0.0
+info:
+  title: Notification Service
+  version: 1.0.0
+  description: Sends customer notifications for key order lifecycle events.
+
+servers:
+  production:
+    host: kafka.prod.example.com:9092
+    protocol: kafka
+
+channels:
+  orderCreated:
+    address: orders.created
+    summary: New order placement events
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+  orderCancelled:
+    address: orders.cancelled
+    summary: Order cancellation events
+    messages:
+      OrderCancelled:
+        $ref: '#/components/messages/OrderCancelled'
+  shipmentDispatched:
+    address: shipping.dispatched
+    summary: Shipment dispatch events
+    messages:
+      ShipmentDispatched:
+        $ref: '#/components/messages/ShipmentDispatched'
+
+operations:
+  onOrderCreated:
+    action: receive
+    channel:
+      $ref: '#/channels/orderCreated'
+  onOrderCancelled:
+    action: receive
+    channel:
+      $ref: '#/channels/orderCancelled'
+  onShipmentDispatched:
+    action: receive
+    channel:
+      $ref: '#/channels/shipmentDispatched'
+
+components:
+  messages:
+    OrderCreated:
+      summary: Fired when a customer places a new order
+    OrderCancelled:
+      summary: Fired when an order is cancelled by customer or system
+    ShipmentDispatched:
+      summary: Fired when a shipment leaves the warehouse
+`,
+  },
+};
diff --git a/packages/playground/src/examples/21-openapi-import.ts b/packages/playground/src/examples/21-openapi-import.ts
new file mode 100644
index 000000000..3a844107e
--- /dev/null
+++ b/packages/playground/src/examples/21-openapi-import.ts
@@ -0,0 +1,168 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'OpenAPI Import',
+  group: 'Getting Started',
+  description: 'Import commands and queries from an OpenAPI spec into services',
+  source: {
+    'main.ec': `// Commands and queries generated from OpenAPI spec
+import commands { CreateOrder, UpdateOrder, DeleteOrder } from "./orders-openapi.yml"
+import queries { GetOrders, GetOrder } from "./orders-openapi.yml"
+
+visualizer main {
+  name "Order Management (OpenAPI Import)"
+
+  // Service that receives the imported commands and queries
+  service OrderService {
+    version 1.0.0
+    summary "Manages order CRUD operations"
+
+    receives command CreateOrder
+    receives command UpdateOrder
+    receives command DeleteOrder
+    receives query GetOrders
+    receives query GetOrder
+  }
+
+  // New service that integrates with the OpenAPI service
+  service AdminDashboard {
+    version 1.0.0
+    summary "Internal admin tool"
+
+    sends query GetOrders
+    sends query GetOrder
+  }
+}
+`,
+    'orders-openapi.yml': `openapi: 3.0.3
+info:
+  title: Orders API
+  version: 1.0.0
+  description: RESTful API for managing customer orders
+servers:
+  - url: https://api.example.com/v1
+paths:
+  /orders:
+    get:
+      operationId: GetOrders
+      summary: List all orders with optional filters
+      parameters:
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [pending, shipped, delivered, cancelled]
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 20
+      responses:
+        '200':
+          description: A list of orders
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Order'
+    post:
+      operationId: CreateOrder
+      summary: Create a new order
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [customerId, items]
+              properties:
+                customerId:
+                  type: string
+                  format: uuid
+                items:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      productId:
+                        type: string
+                      quantity:
+                        type: integer
+      responses:
+        '201':
+          description: Order created
+  /orders/{orderId}:
+    get:
+      operationId: GetOrder
+      summary: Get a single order by ID
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: The order
+    put:
+      operationId: UpdateOrder
+      summary: Update an existing order
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                status:
+                  type: string
+                items:
+                  type: array
+      responses:
+        '200':
+          description: Order updated
+    delete:
+      operationId: DeleteOrder
+      summary: Cancel and delete an order
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '204':
+          description: Order deleted
+components:
+  schemas:
+    Order:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+        status:
+          type: string
+          enum: [pending, shipped, delivered, cancelled]
+        items:
+          type: array
+        totalAmount:
+          type: number
+        createdAt:
+          type: string
+          format: date-time
+`,
+  },
+};
diff --git a/packages/playground/src/examples/22-openapi-service-import.ts b/packages/playground/src/examples/22-openapi-service-import.ts
new file mode 100644
index 000000000..0983ddd01
--- /dev/null
+++ b/packages/playground/src/examples/22-openapi-service-import.ts
@@ -0,0 +1,126 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'OpenAPI Service Import',
+  group: 'Getting Started',
+  description: 'Import a full service with commands and queries inferred from an OpenAPI spec',
+  source: {
+    'main.ec': `// Full service generated from OpenAPI spec (commands, queries, and service definition)
+import PaymentService from "./payments-openapi.yml"
+
+visualizer main {
+  name "Payment Gateway (Full Service Import)"
+
+  // Generated from OpenAPI spec
+  service PaymentService
+
+  // New service that integrates with the OpenAPI service
+  service CheckoutService {
+    version 1.0.0
+    summary "Handles the checkout flow"
+
+    sends command CreatePayment
+    sends query GetPayment
+  }
+}
+`,
+    'payments-openapi.yml': `openapi: 3.0.3
+info:
+  title: Payment Service
+  version: 2.0.0
+  description: Handles payment processing and retrieval.
+servers:
+  - url: https://api.example.com/payments
+paths:
+  /payments:
+    get:
+      operationId: ListPayments
+      summary: List all payments
+      parameters:
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [pending, completed, failed, refunded]
+      responses:
+        '200':
+          description: List of payments
+    post:
+      operationId: CreatePayment
+      summary: Process a new payment
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [orderId, amount, currency]
+              properties:
+                orderId:
+                  type: string
+                  format: uuid
+                amount:
+                  type: number
+                currency:
+                  type: string
+                  enum: [USD, EUR, GBP]
+                paymentMethod:
+                  type: string
+                  enum: [card, bank_transfer, wallet]
+      responses:
+        '201':
+          description: Payment created
+  /payments/{paymentId}:
+    get:
+      operationId: GetPayment
+      summary: Retrieve payment details
+      parameters:
+        - name: paymentId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Payment details
+    delete:
+      operationId: CancelPayment
+      summary: Cancel a pending payment
+      parameters:
+        - name: paymentId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Payment cancelled
+  /payments/{paymentId}/refund:
+    post:
+      operationId: RefundPayment
+      summary: Refund a completed payment
+      parameters:
+        - name: paymentId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                amount:
+                  type: number
+                reason:
+                  type: string
+      responses:
+        '200':
+          description: Payment refunded
+`,
+  },
+};
diff --git a/packages/playground/src/examples/23-openapi-asyncapi-mixed.ts b/packages/playground/src/examples/23-openapi-asyncapi-mixed.ts
new file mode 100644
index 000000000..9ad3364c8
--- /dev/null
+++ b/packages/playground/src/examples/23-openapi-asyncapi-mixed.ts
@@ -0,0 +1,138 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'OpenAPI + AsyncAPI Mixed',
+  group: 'Getting Started',
+  description: 'Combine REST (OpenAPI) and event-driven (AsyncAPI) specs in a single architecture',
+  source: {
+    'main.ec': `// Generated from OpenAPI spec (REST API)
+import OrderService from "./orders-openapi.yml"
+// Generated from AsyncAPI spec (event-driven)
+import InventoryService from "./inventory-asyncapi.yml"
+
+visualizer main {
+  name "E-Commerce (REST + Events)"
+
+  // Generated from OpenAPI spec
+  service OrderService
+  // Generated from AsyncAPI spec
+  service InventoryService
+
+  // New service that integrates with both OpenAPI and AsyncAPI services
+  service WebApp {
+    version 1.0.0
+    summary "Customer-facing web application"
+
+    sends command CreateOrder
+    sends query GetOrders
+  }
+}
+`,
+    'orders-openapi.yml': `openapi: 3.0.3
+info:
+  title: Order Service
+  version: 1.0.0
+  description: RESTful API for order management.
+paths:
+  /orders:
+    get:
+      operationId: GetOrders
+      summary: List all orders
+      responses:
+        '200':
+          description: A list of orders
+    post:
+      operationId: CreateOrder
+      summary: Place a new order
+      responses:
+        '201':
+          description: Order created
+  /orders/{id}:
+    get:
+      operationId: GetOrder
+      summary: Get order details
+      responses:
+        '200':
+          description: Order details
+    put:
+      operationId: UpdateOrder
+      summary: Update an order
+      responses:
+        '200':
+          description: Order updated
+`,
+    'inventory-asyncapi.yml': `asyncapi: 3.0.0
+info:
+  title: Inventory Service
+  version: 1.0.0
+  description: Manages stock levels and reacts to order events.
+
+servers:
+  production:
+    host: kafka.prod.example.com:9092
+    protocol: kafka
+
+channels:
+  stockReserved:
+    address: inventory.stock-reserved
+    summary: Stock reservation confirmations
+    messages:
+      StockReserved:
+        $ref: '#/components/messages/StockReserved'
+  stockDepleted:
+    address: inventory.stock-depleted
+    summary: Low stock warnings
+    messages:
+      StockDepleted:
+        $ref: '#/components/messages/StockDepleted'
+  orderCreated:
+    address: orders.created
+    summary: New order events from the Order Service
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+
+operations:
+  onOrderCreated:
+    action: receive
+    channel:
+      $ref: '#/channels/orderCreated'
+    summary: Reserves stock when a new order is placed
+  publishStockReserved:
+    action: send
+    channel:
+      $ref: '#/channels/stockReserved'
+    summary: Confirms stock has been reserved
+  publishStockDepleted:
+    action: send
+    channel:
+      $ref: '#/channels/stockDepleted'
+    summary: Warns when stock is running low
+
+components:
+  messages:
+    OrderCreated:
+      summary: A new order has been placed
+    StockReserved:
+      summary: Stock reserved for an order
+      contentType: application/json
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+          reservedItems:
+            type: array
+    StockDepleted:
+      summary: Stock has fallen below threshold
+      contentType: application/json
+      payload:
+        type: object
+        properties:
+          productId:
+            type: string
+          remainingStock:
+            type: integer
+`,
+  },
+};
diff --git a/packages/playground/src/examples/24-openapi-remote-import.ts b/packages/playground/src/examples/24-openapi-remote-import.ts
new file mode 100644
index 000000000..dd69dff0c
--- /dev/null
+++ b/packages/playground/src/examples/24-openapi-remote-import.ts
@@ -0,0 +1,39 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'OpenAPI Remote Import',
+  group: 'Getting Started',
+  description: 'Import commands and queries from a remote OpenAPI spec (Swagger Petstore) via URL',
+  source: {
+    'main.ec': `// Commands and queries generated from remote OpenAPI spec (Swagger Petstore)
+import commands { addPet, updatePet, deletePet } from "https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml"
+import queries { findPetsByStatus, getPetById } from "https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml"
+
+visualizer main {
+  name "Pet Store (Remote OpenAPI Import)"
+
+  // Service that receives the imported commands and queries
+  service PetStoreAPI {
+    version 1.0.0
+    summary "Manages pets in the store"
+
+    receives command addPet
+    receives command updatePet
+    receives command deletePet
+    receives query findPetsByStatus
+    receives query getPetById
+  }
+
+  // New service that integrates with the OpenAPI service
+  service PetAdoptionApp {
+    version 1.0.0
+    summary "Customer-facing pet adoption application"
+
+    sends query findPetsByStatus
+    sends query getPetById
+    sends command addPet
+  }
+}
+`,
+  },
+};
diff --git a/packages/playground/src/examples/25-sample-event-driven-system.ts b/packages/playground/src/examples/25-sample-event-driven-system.ts
new file mode 100644
index 000000000..218eb0ac1
--- /dev/null
+++ b/packages/playground/src/examples/25-sample-event-driven-system.ts
@@ -0,0 +1,176 @@
+import type { Example } from './types';
+
+export const example: Example = {
+  name: 'Sample Event-Driven System',
+  group: 'Getting Started',
+  description: 'A realistic cross-domain architecture with imported REST APIs and event-driven workflows',
+  source: {
+    'main.ec': `import CheckoutApi from "./checkout-openapi.yml"
+import CustomerApi from "./customers-openapi.yml"
+import events { OrderPlaced, PaymentCaptured, InventoryReserved, OrderReadyForShipment } from "./commerce-asyncapi.yml"
+import channels { ordersRequested, paymentsCaptured, inventoryReserved, fulfillmentReady } from "./commerce-asyncapi.yml"
+
+domain Commerce {
+  version 1.0.0
+
+  service CommerceOrchestrator {
+    version 1.0.0
+    summary "Coordinates checkout workflow across domains"
+
+    sends event OrderPlaced to ordersRequested
+    receives event PaymentCaptured from paymentsCaptured
+    receives event InventoryReserved from inventoryReserved
+  }
+
+  service PaymentService {
+    version 1.0.0
+    summary "Captures payments and emits outcomes"
+
+    receives event OrderPlaced from ordersRequested
+    sends event PaymentCaptured to paymentsCaptured
+  }
+
+  service InventoryService {
+    version 1.0.0
+    summary "Reserves stock and reports availability"
+
+    receives event OrderPlaced from ordersRequested
+    sends event InventoryReserved to inventoryReserved
+  }
+}
+
+domain Fulfillment {
+  version 1.0.0
+
+  service FulfillmentService {
+    version 1.0.0
+    summary "Plans shipment after payment and inventory are confirmed"
+
+    receives event PaymentCaptured from paymentsCaptured
+    receives event InventoryReserved from inventoryReserved
+    sends event OrderReadyForShipment to fulfillmentReady
+  }
+
+  service NotificationService {
+    version 1.0.0
+    summary "Notifies customers with order status updates"
+
+    receives event OrderReadyForShipment from fulfillmentReady
+  }
+
+  service AnalyticsService {
+    version 1.0.0
+    summary "Builds operational dashboards from lifecycle events"
+
+    receives event OrderPlaced from ordersRequested
+    receives event PaymentCaptured from paymentsCaptured
+    receives event OrderReadyForShipment from fulfillmentReady
+  }
+}
+
+visualizer main {
+  name "Sample Enterprise Checkout System"
+
+  // REST surface imported from OpenAPI specs
+  service CheckoutApi
+  service CustomerApi
+
+  // Domain boundaries and event-driven flows
+  domain Commerce
+  domain Fulfillment
+}
+`,
+    'checkout-openapi.yml': `openapi: 3.0.3
+info:
+  title: Checkout API
+  version: 1.0.0
+  group: 'Getting Started',
+  description: REST API for shopping cart and order checkout.
+paths:
+  /checkout:
+    post:
+      operationId: CreateCheckoutSession
+      summary: Create a checkout session
+      responses:
+        '201':
+          group: 'Getting Started',
+  description: Checkout session created
+  /checkout/{sessionId}/confirm:
+    post:
+      operationId: ConfirmCheckoutSession
+      summary: Confirm an existing checkout session
+      responses:
+        '200':
+          group: 'Getting Started',
+  description: Session confirmed
+`,
+    'customers-openapi.yml': `openapi: 3.0.3
+info:
+  title: Customer API
+  version: 1.0.0
+  group: 'Getting Started',
+  description: REST API for customer profile and notification preferences.
+paths:
+  /customers/{customerId}:
+    get:
+      operationId: GetCustomerProfile
+      summary: Retrieve customer profile details
+      responses:
+        '200':
+          group: 'Getting Started',
+  description: Customer profile
+  /customers/{customerId}/preferences:
+    patch:
+      operationId: UpdateNotificationPreferences
+      summary: Update customer notification preferences
+      responses:
+        '200':
+          group: 'Getting Started',
+  description: Preferences updated
+`,
+    'commerce-asyncapi.yml': `asyncapi: 3.0.0
+info:
+  title: Commerce Event Bus
+  version: 1.0.0
+  group: 'Getting Started',
+  description: Event contracts for checkout, payment, inventory, and fulfillment workflows.
+
+channels:
+  ordersRequested:
+    address: commerce.orders.requested
+    summary: New orders waiting for payment and stock checks
+    messages:
+      OrderPlaced:
+        $ref: '#/components/messages/OrderPlaced'
+  paymentsCaptured:
+    address: commerce.payments.captured
+    summary: Orders with successful payments
+    messages:
+      PaymentCaptured:
+        $ref: '#/components/messages/PaymentCaptured'
+  inventoryReserved:
+    address: commerce.inventory.reserved
+    summary: Orders with inventory confirmed
+    messages:
+      InventoryReserved:
+        $ref: '#/components/messages/InventoryReserved'
+  fulfillmentReady:
+    address: commerce.fulfillment.ready
+    summary: Orders that can move to shipment
+    messages:
+      OrderReadyForShipment:
+        $ref: '#/components/messages/OrderReadyForShipment'
+
+components:
+  messages:
+    OrderPlaced:
+      summary: Customer has placed an order
+    PaymentCaptured:
+      summary: Payment for an order has been captured
+    InventoryReserved:
+      summary: Inventory has been reserved for an order
+    OrderReadyForShipment:
+      summary: Order can now be handed over to shipping
+`,
+  },
+};
diff --git a/packages/playground/src/examples/index.ts b/packages/playground/src/examples/index.ts
new file mode 100644
index 000000000..5367b62cc
--- /dev/null
+++ b/packages/playground/src/examples/index.ts
@@ -0,0 +1,57 @@
+export type { Example } from './types';
+
+import { example as paymentDomain } from './01-payment-domain';
+import { example as orderServiceShowcase } from './02-order-service-showcase';
+import { example as minimalService } from './03-minimal-service';
+import { example as ecommercePlatform } from './04-ecommerce-platform';
+import { example as eventDrivenSaga } from './05-event-driven-saga';
+import { example as dataProducts } from './06-data-products';
+import { example as multiFileImports } from './07-multi-file-imports';
+import { example as remoteUrlImports } from './08-remote-url-imports';
+import { example as bankingSubdomains } from './09-banking-subdomains';
+import { example as planningFutureServices } from './10-planning-future-services';
+import { example as enterpriseEcommerce } from './11-enterprise-ecommerce';
+import { example as notesAnnotations } from './12-notes-annotations';
+import { example as channelRouting } from './13-channel-routing';
+import { example as awsEventPipeline } from './14-aws-event-pipeline';
+import { example as flowOrderFulfillment } from './15-flow-order-fulfillment';
+import { example as flowEcommerceCheckout } from './16-flow-ecommerce-checkout';
+import { example as asyncapiImport } from './17-asyncapi-import';
+import { example as asyncapiRemoteImport } from './18-asyncapi-remote-import';
+import { example as asyncapiServiceImport } from './19-asyncapi-service-import';
+import { example as asyncapiMultiService } from './20-asyncapi-multi-service';
+import { example as openapiImport } from './21-openapi-import';
+import { example as openapiServiceImport } from './22-openapi-service-import';
+import { example as openapiAsyncapiMixed } from './23-openapi-asyncapi-mixed';
+import { example as openapiRemoteImport } from './24-openapi-remote-import';
+import { example as sampleEventDrivenSystem } from './25-sample-event-driven-system';
+
+import type { Example } from './types';
+
+export const examples: Example[] = [
+  paymentDomain,
+  orderServiceShowcase,
+  minimalService,
+  ecommercePlatform,
+  eventDrivenSaga,
+  dataProducts,
+  multiFileImports,
+  remoteUrlImports,
+  bankingSubdomains,
+  planningFutureServices,
+  enterpriseEcommerce,
+  notesAnnotations,
+  channelRouting,
+  awsEventPipeline,
+  flowOrderFulfillment,
+  flowEcommerceCheckout,
+  asyncapiImport,
+  asyncapiRemoteImport,
+  asyncapiServiceImport,
+  asyncapiMultiService,
+  openapiImport,
+  openapiServiceImport,
+  openapiAsyncapiMixed,
+  openapiRemoteImport,
+  sampleEventDrivenSystem,
+];
diff --git a/packages/playground/src/examples/types.ts b/packages/playground/src/examples/types.ts
new file mode 100644
index 000000000..a16542270
--- /dev/null
+++ b/packages/playground/src/examples/types.ts
@@ -0,0 +1,6 @@
+export interface Example {
+  name: string;
+  group: string;
+  description: string;
+  source: Record<string, string>;
+}
diff --git a/packages/playground/src/hooks/useDslParser.ts b/packages/playground/src/hooks/useDslParser.ts
new file mode 100644
index 000000000..90bb5aa36
--- /dev/null
+++ b/packages/playground/src/hooks/useDslParser.ts
@@ -0,0 +1,339 @@
+import { useState, useEffect, useRef, useCallback } from 'react';
+import type { GraphNode, GraphEdge } from '@eventcatalog/visualiser';
+import type { DslError } from '../monaco/ec-diagnostics';
+import { resolveSpecImportsAsync } from '../resolvers';
+import { cacheSpecContent } from '../monaco/ec-completion';
+
+interface ParseResult {
+  graph: { nodes: GraphNode[]; edges: GraphEdge[]; visualizers?: string[]; activeVisualizer?: string; title?: string; empty?: boolean; options?: { legend?: boolean; search?: boolean; toolbar?: boolean; focusMode?: boolean; style?: string } };
+  errors: DslError[];
+}
+
+let langiumServices: any = null;
+let astToGraphFn: any = null;
+let compileFn: any = null;
+let docCounter = 1;
+
+const urlFetchCache = new Map<string, string>();
+
+// Matches local file imports (not HTTP/HTTPS):
+//   import { ... } from "file.ec"
+//   import events { ... } from "file.yml"
+//   import ServiceName from "file.yml"
+const LOCAL_IMPORT_RE = /^\s*import\s+(?:(?:events|commands|queries|channels|services)\s+)?\{[^}]*\}\s*from\s*"(?!https?:\/\/)([^"]+)"\s*(?:\/\/.*)?$|^\s*import\s+[A-Z][a-zA-Z0-9_]*\s+from\s*"(?!https?:\/\/)([^"]+)"\s*(?:\/\/.*)?$/gm;
+
+// Matches URL imports for .ec files (not spec files - those are handled by the resolver)
+const URL_IMPORT_RE = /^\s*import\s*\{[^}]*\}\s*from\s*"(https?:\/\/[^"]+)"\s*(?:\/\/.*)?$/gm;
+
+/**
+ * Converts GitHub blob/tree URLs to raw.githubusercontent.com URLs.
+ */
+function toRawUrl(url: string): string {
+  const ghMatch = url.match(
+    /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/(?:blob|tree)\/(.+)$/
+  );
+  return ghMatch
+    ? `https://raw.githubusercontent.com/${ghMatch[1]}/${ghMatch[2]}/${ghMatch[3]}`
+    : url;
+}
+
+async function fetchSpec(url: string): Promise<string> {
+  const rawUrl = toRawUrl(url);
+  const cached = urlFetchCache.get(rawUrl);
+  if (cached) return cached;
+
+  const resp = await fetch(rawUrl);
+  if (!resp.ok) throw new Error(`${resp.status} ${resp.statusText}`);
+
+  const text = await resp.text();
+  urlFetchCache.set(rawUrl, text);
+  cacheSpecContent(url, text);
+  return text;
+}
+
+async function resolveUrlImports(
+  files: Record<string, string>
+): Promise<{ files: Record<string, string>; errors: DslError[] }> {
+  const errors: DslError[] = [];
+  const allUrls = new Map<string, string[]>();
+
+  for (const [filename, source] of Object.entries(files)) {
+    URL_IMPORT_RE.lastIndex = 0;
+    let match;
+    while ((match = URL_IMPORT_RE.exec(source)) !== null) {
+      const url = match[1];
+      const filenames = allUrls.get(url) ?? [];
+      filenames.push(filename);
+      allUrls.set(url, filenames);
+    }
+  }
+
+  if (allUrls.size === 0) return { files, errors };
+
+  const fetchResults = new Map<string, string>();
+  await Promise.all(
+    [...allUrls.keys()].map(async (url) => {
+      const cached = urlFetchCache.get(url);
+      if (cached) {
+        fetchResults.set(url, cached);
+        return;
+      }
+      try {
+        const resp = await fetch(url);
+        if (!resp.ok) {
+          errors.push({ message: `Failed to fetch "${url}": ${resp.status} ${resp.statusText}`, line: 1, column: 1 });
+          return;
+        }
+        const text = await resp.text();
+        urlFetchCache.set(url, text);
+        fetchResults.set(url, text);
+      } catch (err) {
+        errors.push({ message: `Failed to fetch "${url}": ${String(err)}`, line: 1, column: 1 });
+      }
+    })
+  );
+
+  const newFiles: Record<string, string> = {};
+
+  for (const [filename, source] of Object.entries(files)) {
+    newFiles[filename] = source.replace(URL_IMPORT_RE, '').replace(/^\s*\n/gm, '');
+  }
+
+  for (const [url, content] of fetchResults) {
+    const segments = new URL(url).pathname.split('/');
+    const basename = segments[segments.length - 1] || 'remote.ec';
+    let name = basename;
+    let i = 1;
+    while (newFiles[name]) {
+      name = `${i++}_${basename}`;
+    }
+    newFiles[name] = content;
+  }
+
+  return { files: newFiles, errors };
+}
+
+async function initServices() {
+  if (langiumServices) return;
+  const langModule = await import('@eventcatalog/language-server/browser');
+  const { EmptyFileSystem } = await import('langium');
+
+  langiumServices = langModule.createEcServices(EmptyFileSystem);
+  astToGraphFn = langModule.astToGraph;
+  compileFn = langModule.compile;
+}
+
+export interface FileOffsets {
+  [filename: string]: { startLine: number; lineCount: number };
+}
+
+async function parseSingle(source: string, activeVisualizer?: string): Promise<ParseResult> {
+  await initServices();
+  const { URI } = await import('langium');
+
+  const uri = URI.parse(`file:///playground-${docCounter++}.ec`);
+  const document = langiumServices.shared.workspace.LangiumDocumentFactory.fromString(source, uri);
+  langiumServices.shared.workspace.LangiumDocuments.addDocument(document);
+  await langiumServices.shared.workspace.DocumentBuilder.build([document]);
+
+  const errors: DslError[] = document.parseResult.parserErrors.map((e: any) => ({
+    message: e.message,
+    line: e.token.startLine ?? 1,
+    column: e.token.startColumn ?? 1,
+    endLine: e.token.endLine,
+    endColumn: e.token.endColumn ? e.token.endColumn + 1 : undefined,
+  }));
+
+  const graph = astToGraphFn(document.parseResult.value, activeVisualizer);
+
+  try {
+    langiumServices.shared.workspace.LangiumDocuments.deleteDocument(uri);
+  } catch {
+    // Ignore cleanup errors
+  }
+
+  return { graph, errors };
+}
+
+/**
+ * Resolve all imports (AsyncAPI specs + URL .ec files) and strip local imports,
+ * returning the resolved file map ready for concatenation.
+ */
+async function resolveAllImports(
+  inputFiles: Record<string, string>
+): Promise<{ files: Record<string, string>; errors: DslError[] }> {
+  const { files: specResolved, errors: specErrors } = await resolveSpecImportsAsync(inputFiles, fetchSpec);
+  const { files: urlResolved, errors: fetchErrors } = await resolveUrlImports(specResolved);
+  return { files: urlResolved, errors: [...specErrors, ...fetchErrors] };
+}
+
+/**
+ * Strip local file imports and concatenate files into a single source string.
+ */
+function stripAndConcatenate(
+  files: Record<string, string>,
+  order?: string[],
+): { source: string; fileOffsets: FileOffsets } {
+  const filenames = order ?? Object.keys(files);
+  const fileOffsets: FileOffsets = {};
+  const parts: string[] = [];
+  let currentLine = 1;
+
+  for (const filename of filenames) {
+    const content = files[filename].replace(LOCAL_IMPORT_RE, '');
+    const lineCount = content.split('\n').length;
+    fileOffsets[filename] = { startLine: currentLine, lineCount };
+    parts.push(content);
+    currentLine += lineCount;
+  }
+
+  return { source: parts.join('\n'), fileOffsets };
+}
+
+async function parseMultiFile(inputFiles: Record<string, string>, activeVisualizer?: string): Promise<ParseResult & { fileOffsets: FileOffsets }> {
+  const { files, errors: preErrors } = await resolveAllImports(inputFiles);
+  const filenames = Object.keys(files);
+
+  if (filenames.length === 0) {
+    return {
+      graph: { nodes: [], edges: [], empty: true },
+      errors: preErrors,
+      fileOffsets: {},
+    };
+  }
+
+  const mainFile = filenames[0];
+  const mainSource = files[mainFile];
+
+  if (filenames.length === 1) {
+    const result = await parseSingle(mainSource, activeVisualizer);
+    return {
+      ...result,
+      errors: [...preErrors, ...result.errors],
+      fileOffsets: { [mainFile]: { startLine: 1, lineCount: mainSource.split('\n').length } },
+    };
+  }
+
+  const mainResult = await parseSingle(mainSource, activeVisualizer);
+
+  // Concatenate supporting files before main file
+  const supportingFiles = filenames.filter((f) => f !== mainFile);
+  const concatOrder = [...supportingFiles, mainFile];
+  const { source: combinedSource, fileOffsets } = stripAndConcatenate(files, concatOrder);
+  const fullResult = await parseSingle(combinedSource, activeVisualizer);
+
+  // Map main node IDs to their corresponding nodes in fullResult
+  // Nodes may have different IDs if versions were added (e.g., service:X vs service:X@1.0.0)
+  const extractNodeKey = (id: string) => {
+    const match = id.match(/^([^:]+):([^@]+)/);
+    return match ? `${match[1]}:${match[2]}` : id;
+  };
+
+  const mainNodeKeys = new Set(mainResult.graph.nodes.map((n) => extractNodeKey(n.id)));
+
+  // Find all nodes in fullResult that match main nodes (by type:name)
+  const filteredNodeIds = new Set(
+    fullResult.graph.nodes
+      .filter((node) => mainNodeKeys.has(extractNodeKey(node.id)))
+      .map((node) => node.id)
+  );
+
+  // Iteratively expand to include all connected nodes
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const edge of fullResult.graph.edges) {
+      if (filteredNodeIds.has(edge.source) && !filteredNodeIds.has(edge.target)) {
+        filteredNodeIds.add(edge.target);
+        changed = true;
+      }
+      if (filteredNodeIds.has(edge.target) && !filteredNodeIds.has(edge.source)) {
+        filteredNodeIds.add(edge.source);
+        changed = true;
+      }
+    }
+  }
+
+  return {
+    graph: {
+      nodes: fullResult.graph.nodes.filter((n) => filteredNodeIds.has(n.id)),
+      edges: fullResult.graph.edges.filter((e) => filteredNodeIds.has(e.source) && filteredNodeIds.has(e.target)),
+      visualizers: fullResult.graph.visualizers,
+      activeVisualizer: fullResult.graph.activeVisualizer,
+      title: fullResult.graph.title,
+      options: fullResult.graph.options,
+    },
+    errors: [...preErrors, ...fullResult.errors],
+    fileOffsets,
+  };
+}
+
+export interface CompiledFile {
+  path: string;
+  content: string;
+}
+
+export async function compileDsl(files: Record<string, string>): Promise<CompiledFile[]> {
+  await initServices();
+  const { URI } = await import('langium');
+
+  const { files: resolvedFiles } = await resolveAllImports(files);
+  const { source: combinedSource } = stripAndConcatenate(resolvedFiles);
+
+  const uri = URI.parse(`file:///compile-${docCounter++}.ec`);
+  const document = langiumServices.shared.workspace.LangiumDocumentFactory.fromString(combinedSource, uri);
+  langiumServices.shared.workspace.LangiumDocuments.addDocument(document);
+  await langiumServices.shared.workspace.DocumentBuilder.build([document]);
+
+  const parserErrors = document.parseResult.parserErrors;
+  if (parserErrors.length > 0) {
+    try {
+      langiumServices.shared.workspace.LangiumDocuments.deleteDocument(uri);
+    } catch {}
+    throw new Error(`DSL has parse errors: ${parserErrors[0].message}`);
+  }
+
+  const compiled: CompiledFile[] = compileFn(document.parseResult.value, { nested: true });
+
+  try {
+    langiumServices.shared.workspace.LangiumDocuments.deleteDocument(uri);
+  } catch {}
+
+  return compiled;
+}
+
+export function useDslParser(files: Record<string, string>, activeVisualizer?: string) {
+  const [graph, setGraph] = useState<{ nodes: GraphNode[]; edges: GraphEdge[]; visualizers?: string[]; activeVisualizer?: string; empty?: boolean; options?: { legend?: boolean; search?: boolean; toolbar?: boolean; focusMode?: boolean; style?: string } }>({
+    nodes: [],
+    edges: [],
+  });
+  const [errors, setErrors] = useState<DslError[]>([]);
+  const [fileOffsets, setFileOffsets] = useState<FileOffsets>({});
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const doParse = useCallback(async (f: Record<string, string>, vizName?: string) => {
+    try {
+      const result = await parseMultiFile(f, vizName);
+      setErrors(result.errors);
+      setGraph(result.graph);
+      setFileOffsets(result.fileOffsets);
+    } catch (err) {
+      console.error('Parse error:', err);
+      setErrors([{ message: String(err), line: 1, column: 1 }]);
+      setGraph({ nodes: [], edges: [] });
+      setFileOffsets({});
+    }
+  }, []);
+
+  const filesKey = JSON.stringify(files);
+
+  useEffect(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => { doParse(files, activeVisualizer); }, 150);
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, [filesKey, activeVisualizer, doParse]);
+
+  return { graph, errors, fileOffsets };
+}
diff --git a/packages/playground/src/index.css b/packages/playground/src/index.css
new file mode 100644
index 000000000..1b8f932c2
--- /dev/null
+++ b/packages/playground/src/index.css
@@ -0,0 +1,1391 @@
+@import "@eventcatalog/visualiser/styles.css";
+@import "@xyflow/react/dist/style.css";
+
+html,
+body,
+#root {
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  font-family:
+    Inter,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    Roboto,
+    sans-serif;
+}
+
+/* Lock overflow only on the playground editor view */
+body:has(.app) {
+  overflow: hidden;
+}
+
+body:has(.app),
+body:has(.app) #root {
+  height: 100%;
+  overflow: hidden;
+}
+
+/* Landing page: allow normal scrolling, prevent horizontal overflow */
+body:has(.landing) {
+  overflow-x: hidden;
+  overflow-y: auto;
+  height: auto;
+}
+
+body:has(.landing) #root {
+  height: auto;
+  overflow: visible;
+}
+
+:root {
+  --shell-bg: #f6f8fb;
+  --shell-text: #1f2328;
+  --shell-muted: #57606a;
+  --shell-border: #d0d7de;
+  --shell-header-bg: #ffffff;
+  --shell-title: #0f172a;
+  --shell-control-bg: #ffffff;
+  --shell-control-border: #d0d7de;
+  --shell-control-text: #1f2328;
+  --shell-control-border-hover: #8c959f;
+  --shell-button-text: #57606a;
+  --shell-button-text-hover: #1f2328;
+  --shell-button-border-hover: #0969da;
+  --modal-overlay: rgba(15, 23, 42, 0.28);
+  --modal-bg: #ffffff;
+  --modal-text: #1f2328;
+}
+
+[data-theme="dark"] {
+  --shell-bg: #0d1117;
+  --shell-text: #e1e4e8;
+  --shell-muted: #8b949e;
+  --shell-border: #30363d;
+  --shell-header-bg: #161b22;
+  --shell-title: #f0f6fc;
+  --shell-control-bg: #21262d;
+  --shell-control-border: #30363d;
+  --shell-control-text: #e1e4e8;
+  --shell-control-border-hover: #484f58;
+  --shell-button-text: #8b949e;
+  --shell-button-text-hover: #f0f6fc;
+  --shell-button-border-hover: #58a6ff;
+  --modal-overlay: rgba(1, 4, 9, 0.72);
+  --modal-bg: #0d1117;
+  --modal-text: #f0f6fc;
+}
+
+/* ── App Layout ── */
+.app {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  background: var(--shell-bg);
+  color: var(--shell-text);
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 0 16px;
+  height: 48px;
+  background: var(--shell-header-bg);
+  border-bottom: 1px solid var(--shell-border);
+  flex-shrink: 0;
+}
+
+.header-logo {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.header-home-link {
+  text-decoration: none;
+  color: inherit;
+  display: inline-flex;
+  align-items: center;
+}
+
+.header-home-link:hover h1 {
+  opacity: 0.92;
+}
+
+.header h1 {
+  font-size: 15px;
+  font-weight: 700;
+  color: var(--shell-title);
+  letter-spacing: -0.02em;
+  white-space: nowrap;
+  margin: 0;
+}
+
+.header-template-name {
+  font-weight: 400;
+  color: var(--shell-muted);
+}
+
+.header-icon-btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  border: 1px solid var(--shell-control-border);
+  border-radius: 6px;
+  background: var(--shell-control-bg);
+  color: var(--shell-button-text);
+  cursor: pointer;
+  transition:
+    color 0.15s,
+    border-color 0.15s;
+  padding: 0;
+}
+
+.header-icon-btn:hover {
+  color: var(--shell-button-text-hover);
+  border-color: var(--shell-control-border-hover);
+}
+
+.export-btn-header {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  height: 32px;
+  padding: 0 14px;
+  font-size: 12px;
+  font-weight: 600;
+  font-family: inherit;
+  color: #fff;
+  background: #a855f7;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  transition: background 0.15s;
+  white-space: nowrap;
+}
+
+.export-btn-header:hover {
+  background: #9333ea;
+}
+
+.export-dropdown-wrapper {
+  position: relative;
+}
+
+.export-dropdown {
+  position: absolute;
+  top: calc(100% + 6px);
+  right: 0;
+  width: 280px;
+  background: var(--modal-bg);
+  border: 1px solid var(--shell-border);
+  border-radius: 8px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3);
+  z-index: 50;
+  overflow: hidden;
+}
+
+.export-dropdown-item {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  width: 100%;
+  padding: 10px 12px;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  text-align: left;
+  font-family: inherit;
+  color: var(--modal-text);
+  transition: background 0.1s;
+}
+
+.export-dropdown-item:hover {
+  background: var(--shell-control-bg);
+}
+
+.export-dropdown-item + .export-dropdown-item {
+  border-top: 1px solid var(--shell-border);
+}
+
+.export-dropdown-item > svg {
+  flex-shrink: 0;
+  margin-top: 2px;
+  color: var(--shell-muted);
+}
+
+.export-dropdown-item > div {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.export-dropdown-item-title {
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.export-dropdown-item-desc {
+  font-size: 11px;
+  color: var(--shell-muted);
+}
+
+.header-actions {
+  margin-left: auto;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+.header-action-group {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 3px;
+  border: 1px solid var(--shell-control-border);
+  border-radius: 8px;
+  background: var(--shell-control-bg);
+}
+
+.tooltip-wrap {
+  position: relative;
+  display: inline-flex;
+}
+
+.tooltip-wrap::before,
+.tooltip-wrap::after {
+  position: absolute;
+  left: 50%;
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    opacity 0.15s ease,
+    transform 0.15s ease;
+  z-index: 20;
+}
+
+.tooltip-wrap::before {
+  content: "";
+  bottom: calc(100% + 2px);
+  transform: translate(-50%, 4px);
+  border: 5px solid transparent;
+  border-top-color: var(--shell-control-bg);
+  filter: drop-shadow(0 -1px 0 var(--shell-control-border));
+}
+
+.tooltip-wrap::after {
+  content: attr(data-tooltip);
+  bottom: calc(100% + 10px);
+  transform: translate(-50%, 4px);
+  white-space: nowrap;
+  font-size: 11px;
+  line-height: 1;
+  color: var(--shell-text);
+  background: var(--shell-control-bg);
+  border: 1px solid var(--shell-control-border);
+  border-radius: 6px;
+  padding: 6px 8px;
+  box-shadow: 0 6px 12px rgba(0, 0, 0, 0.15);
+}
+
+.tooltip-wrap:hover::before,
+.tooltip-wrap:hover::after,
+.tooltip-wrap:focus-within::before,
+.tooltip-wrap:focus-within::after {
+  opacity: 1;
+  transform: translate(-50%, 0);
+}
+
+.fullscreen-btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: 6px;
+  color: var(--shell-button-text);
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  cursor: pointer;
+  transition:
+    color 0.15s,
+    border-color 0.15s;
+}
+
+.fullscreen-btn:hover {
+  color: var(--shell-button-text-hover);
+  border-color: var(--shell-button-border-hover);
+}
+
+/* ── Template Dropdown ── */
+.template-dropdown {
+  position: relative;
+  min-width: 0;
+}
+
+.template-dropdown-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  height: 32px;
+  padding: 0 10px;
+  font-size: 12px;
+  font-family: inherit;
+  border: 1px solid var(--shell-control-border);
+  border-radius: 6px;
+  background: var(--shell-control-bg);
+  color: var(--shell-control-text);
+  cursor: pointer;
+  outline: none;
+  transition: border-color 0.15s;
+  max-width: 420px;
+  white-space: nowrap;
+}
+
+.template-dropdown-trigger:hover {
+  border-color: var(--shell-control-border-hover);
+}
+
+.template-dropdown-trigger:focus-visible {
+  border-color: #a855f7;
+  box-shadow: 0 0 0 2px rgba(168, 85, 247, 0.2);
+}
+
+.template-dropdown-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.template-dropdown-chevron {
+  flex-shrink: 0;
+  color: var(--shell-muted);
+}
+
+.template-dropdown-panel {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 0;
+  z-index: 100;
+  min-width: 240px;
+  max-height: 400px;
+  overflow-y: auto;
+  border: 1px solid var(--shell-control-border);
+  border-radius: 8px;
+  background: var(--shell-control-bg);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.15);
+  padding: 4px 0;
+}
+
+.template-dropdown-group + .template-dropdown-group {
+  border-top: 1px solid var(--shell-control-border);
+  margin-top: 4px;
+  padding-top: 4px;
+}
+
+.template-dropdown-group-header {
+  padding: 6px 12px 4px;
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--shell-muted);
+  pointer-events: none;
+}
+
+.template-dropdown-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 6px 12px;
+  font-size: 12px;
+  font-family: inherit;
+  border: none;
+  background: none;
+  color: var(--shell-control-text);
+  cursor: pointer;
+  text-align: left;
+  white-space: nowrap;
+}
+
+.template-dropdown-item:hover {
+  background: rgba(168, 85, 247, 0.08);
+}
+
+.template-dropdown-item--active {
+  color: #a855f7;
+  font-weight: 500;
+}
+
+/* ── Main Split ── */
+.main {
+  display: flex;
+  flex: 1;
+  overflow: hidden;
+}
+
+.editor-pane {
+  height: 100%;
+  border-right: none;
+  display: flex;
+  flex-direction: column;
+  background: #0d1117;
+  flex-shrink: 0;
+}
+
+.editor-pane .pane-header {
+  display: flex;
+  align-items: center;
+  padding: 0 8px 0 0;
+  height: 36px;
+  background: #161b22;
+  border-bottom: 1px solid #30363d;
+  font-size: 12px;
+  color: #8b949e;
+  flex-shrink: 0;
+  overflow: hidden;
+}
+
+.editor-pane .pane-header .error-count {
+  margin-left: auto;
+  color: #f85149;
+  font-size: 11px;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  flex-shrink: 0;
+  padding-right: 8px;
+}
+
+/* ── Tab Bar ── */
+.tab-bar {
+  display: flex;
+  align-items: center;
+  gap: 0;
+  overflow-x: auto;
+  flex: 1;
+  min-width: 0;
+}
+
+.tab-bar::-webkit-scrollbar {
+  display: none;
+}
+
+.tab-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 0 12px;
+  height: 36px;
+  border: none;
+  background: transparent;
+  color: #8b949e;
+  font-size: 12px;
+  font-family: inherit;
+  cursor: pointer;
+  white-space: nowrap;
+  border-bottom: 2px solid transparent;
+  transition:
+    color 0.15s,
+    border-color 0.15s,
+    background 0.15s;
+}
+
+.tab-item:hover {
+  color: #e1e4e8;
+  background: rgba(255, 255, 255, 0.04);
+}
+
+.tab-item-active {
+  color: #f0f6fc;
+  border-bottom-color: #a855f7;
+}
+
+.tab-close {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  border-radius: 3px;
+  opacity: 0;
+  transition:
+    opacity 0.15s,
+    background 0.15s;
+}
+
+.tab-item:hover .tab-close {
+  opacity: 0.6;
+}
+
+.tab-close:hover {
+  opacity: 1 !important;
+  background: rgba(255, 255, 255, 0.1);
+}
+
+.tab-add {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border: none;
+  background: transparent;
+  color: #8b949e;
+  cursor: pointer;
+  border-radius: 4px;
+  flex-shrink: 0;
+  transition:
+    color 0.15s,
+    background 0.15s;
+}
+
+.tab-add:hover {
+  color: #e1e4e8;
+  background: rgba(255, 255, 255, 0.08);
+}
+
+.format-btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border: none;
+  background: transparent;
+  color: #8b949e;
+  cursor: pointer;
+  border-radius: 4px;
+  flex-shrink: 0;
+  transition:
+    color 0.15s,
+    background 0.15s;
+}
+
+.format-btn:hover {
+  color: #e1e4e8;
+  background: rgba(255, 255, 255, 0.08);
+}
+
+.visualizer-pane {
+  height: 100%;
+  background: rgb(var(--ec-page-bg));
+  flex-shrink: 0;
+  --ec-page-bg: 249, 250, 251;
+}
+
+[data-theme="dark"] .visualizer-pane {
+  --ec-page-bg: 22, 27, 34;
+}
+
+/* ── Resize Handle ── */
+.resize-handle {
+  width: 6px;
+  cursor: col-resize;
+  background: var(--shell-header-bg);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  z-index: 10;
+  transition: background 0.15s;
+}
+
+.resize-handle:hover,
+body.resizing .resize-handle {
+  background: var(--shell-border);
+}
+
+.resize-handle-line {
+  width: 2px;
+  height: 32px;
+  border-radius: 1px;
+  background: var(--shell-muted);
+  transition:
+    background 0.15s,
+    height 0.15s;
+}
+
+.resize-handle:hover .resize-handle-line,
+body.resizing .resize-handle-line {
+  background: #a855f7;
+  height: 48px;
+}
+
+/* Prevent text selection and pointer events on iframes while dragging */
+body.resizing {
+  cursor: col-resize;
+  user-select: none;
+}
+
+body.resizing iframe,
+body.resizing .visualizer-pane,
+body.resizing .editor-pane {
+  pointer-events: none;
+}
+
+/* ── ReactFlow Overrides ── */
+.react-flow__attribution {
+  display: none;
+}
+
+.react-flow__background {
+  background: rgb(var(--ec-page-bg)) !important;
+}
+
+.react-flow__minimap {
+  background: rgb(var(--ec-card-bg)) !important;
+  border: 1px solid rgb(var(--ec-page-border)) !important;
+  border-radius: 6px;
+}
+
+.react-flow__controls {
+  border: 1px solid rgb(var(--ec-page-border)) !important;
+  border-radius: 6px;
+  overflow: hidden;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.06);
+}
+
+.react-flow__controls-button {
+  background: rgb(var(--ec-card-bg)) !important;
+  border-bottom: 1px solid rgb(var(--ec-page-border)) !important;
+  fill: rgb(var(--ec-page-text-muted)) !important;
+}
+
+.react-flow__controls-button:hover {
+  background: rgb(var(--ec-page-border)) !important;
+}
+
+.react-flow__edge-text {
+  font-size: 10px !important;
+}
+
+/* ── Export Modal ── */
+.export-modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: var(--modal-overlay);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 40;
+  padding: 20px;
+}
+
+.export-modal {
+  width: min(760px, 100%);
+  max-height: min(88vh, 760px);
+  overflow-y: auto;
+  background: var(--modal-bg);
+  border: 1px solid var(--shell-border);
+  border-radius: 10px;
+  box-shadow: 0 24px 48px rgba(0, 0, 0, 0.5);
+  padding: 18px;
+}
+
+.export-modal--compact {
+  width: min(520px, 100%);
+}
+
+.export-modal-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+}
+
+.export-modal-header h2 {
+  font-size: 18px;
+  line-height: 1.2;
+  margin: 0;
+  color: var(--modal-text);
+}
+
+.export-modal-close {
+  border: 1px solid var(--shell-control-border);
+  background: transparent;
+  color: var(--shell-muted);
+  border-radius: 6px;
+  width: 28px;
+  height: 28px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+}
+
+.export-modal-close:hover {
+  color: var(--shell-button-text-hover);
+  border-color: var(--shell-button-border-hover);
+}
+
+.export-modal-lead {
+  margin: 0 0 14px;
+  color: var(--shell-muted);
+  font-size: 13px;
+}
+
+.export-modal-lead code,
+.export-modal-tip code {
+  background: var(--shell-control-bg);
+  border: 1px solid var(--shell-control-border);
+  border-radius: 4px;
+  padding: 1px 6px;
+  font-size: 12px;
+}
+
+.command-section {
+  margin-bottom: 12px;
+}
+
+.command-section p {
+  margin: 0 0 6px;
+  color: var(--shell-text);
+  font-size: 13px;
+}
+
+.command-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  border: 1px solid var(--shell-control-border);
+  background: var(--shell-control-bg);
+  border-radius: 8px;
+  padding: 8px;
+}
+
+.command-row code {
+  display: block;
+  flex: 1;
+  min-width: 0;
+  color: var(--shell-text);
+  font-size: 12px;
+  white-space: nowrap;
+  overflow-x: auto;
+}
+
+.command-copy-btn {
+  border: 1px solid var(--shell-control-border);
+  background: transparent;
+  color: var(--shell-muted);
+  border-radius: 6px;
+  padding: 5px 8px;
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 12px;
+  cursor: pointer;
+  flex-shrink: 0;
+}
+
+.command-copy-btn:hover {
+  color: var(--shell-button-text-hover);
+  border-color: var(--shell-button-border-hover);
+}
+
+.export-modal-tip {
+  margin: 4px 0 0;
+  color: var(--shell-muted);
+  font-size: 12px;
+}
+
+.catalog-export-form {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.catalog-export-label {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--shell-text);
+}
+
+.catalog-export-input {
+  height: 36px;
+  border: 1px solid var(--shell-control-border);
+  border-radius: 8px;
+  background: var(--shell-control-bg);
+  color: var(--shell-text);
+  padding: 0 12px;
+  font-size: 13px;
+  font-family: inherit;
+  outline: none;
+}
+
+.catalog-export-input:focus {
+  border-color: #a855f7;
+  box-shadow: 0 0 0 2px rgba(168, 85, 247, 0.2);
+}
+
+.catalog-export-submit {
+  margin-top: 6px;
+  height: 36px;
+  border: none;
+  border-radius: 8px;
+  background: #a855f7;
+  color: #fff;
+  font-size: 13px;
+  font-weight: 600;
+  font-family: inherit;
+  cursor: pointer;
+  transition: background 0.15s;
+}
+
+.catalog-export-submit:hover:not(:disabled) {
+  background: #9333ea;
+}
+
+.catalog-export-submit:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.share-modal-note {
+  margin: 10px 0 0;
+  color: var(--shell-muted);
+  font-size: 12px;
+  font-weight: 600;
+}
+
+/* ── Status Bar ── */
+.status-bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: 26px;
+  padding: 0 12px;
+  background: var(--shell-header-bg);
+  border-top: 1px solid var(--shell-border);
+  flex-shrink: 0;
+  font-size: 11px;
+  color: var(--shell-muted);
+  z-index: 5;
+}
+
+.status-bar-left {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-width: 0;
+}
+
+.status-bar-counts {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.status-bar-empty {
+  font-style: italic;
+  opacity: 0.6;
+}
+
+.status-bar-errors {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  color: #f85149;
+  flex-shrink: 0;
+}
+
+.status-bar-right {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  flex-shrink: 0;
+}
+
+.status-bar-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  border: none;
+  background: transparent;
+  color: var(--shell-muted);
+  font-size: 11px;
+  font-family: inherit;
+  padding: 2px 8px;
+  border-radius: 4px;
+  cursor: pointer;
+  text-decoration: none;
+  transition:
+    color 0.12s,
+    background 0.12s;
+}
+
+.status-bar-btn:hover {
+  color: var(--shell-button-text-hover);
+  background: rgba(127, 127, 127, 0.1);
+}
+
+.status-bar-kbd {
+  font-size: 10px;
+  font-family: inherit;
+  padding: 1px 5px;
+  border: 1px solid var(--shell-control-border);
+  border-radius: 3px;
+  background: var(--shell-control-bg);
+  color: var(--shell-muted);
+  line-height: 1.4;
+}
+
+/* ── Command Palette (cmdk) ── */
+.cmdk-overlay {
+  position: fixed;
+  inset: 0;
+  background: var(--modal-overlay);
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding-top: 20vh;
+  z-index: 50;
+}
+
+.cmdk-wrapper {
+  width: min(520px, calc(100% - 32px));
+  background: var(--modal-bg);
+  border: 1px solid var(--shell-border);
+  border-radius: 10px;
+  box-shadow: 0 16px 40px rgba(0, 0, 0, 0.4);
+  overflow: hidden;
+}
+
+[cmdk-root] {
+  font-family: inherit;
+}
+
+[cmdk-input] {
+  width: 100%;
+  padding: 12px 16px;
+  font-size: 14px;
+  font-family: inherit;
+  border: none;
+  border-bottom: 1px solid var(--shell-border);
+  background: transparent;
+  color: var(--modal-text);
+  outline: none;
+}
+
+[cmdk-input]::placeholder {
+  color: var(--shell-muted);
+}
+
+[cmdk-list] {
+  max-height: 320px;
+  overflow-y: auto;
+  padding: 6px;
+}
+
+[cmdk-group-heading] {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--shell-muted);
+  padding: 8px 10px 4px;
+}
+
+[cmdk-item] {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  font-size: 13px;
+  color: var(--shell-text);
+  border-radius: 6px;
+  cursor: pointer;
+  transition: background 0.08s;
+}
+
+[cmdk-item][data-selected="true"] {
+  background: rgba(168, 85, 247, 0.12);
+  color: var(--modal-text);
+}
+
+[cmdk-item][data-disabled="true"] {
+  color: var(--shell-muted);
+  cursor: default;
+  opacity: 0.6;
+}
+
+[cmdk-item] svg {
+  flex-shrink: 0;
+  color: var(--shell-muted);
+}
+
+[cmdk-item][data-selected="true"] svg {
+  color: #a855f7;
+}
+
+.cmdk-item-content {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  min-width: 0;
+  flex: 1;
+}
+
+.cmdk-item-label {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.cmdk-item-version {
+  font-size: 11px;
+  color: var(--shell-muted);
+  font-family: "JetBrains Mono", "Fira Code", monospace;
+}
+
+.cmdk-item-summary {
+  font-size: 11px;
+  color: var(--shell-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  opacity: 0.8;
+}
+
+[cmdk-empty] {
+  padding: 24px 10px;
+  text-align: center;
+  font-size: 13px;
+  color: var(--shell-muted);
+}
+
+/* ── Template Picker ── */
+.template-picker-overlay {
+  position: fixed;
+  inset: 0;
+  background: var(--modal-overlay);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 50;
+  padding: 20px;
+}
+
+.template-picker {
+  width: min(720px, 100%);
+  max-height: min(88vh, 720px);
+  overflow-y: auto;
+  background: var(--modal-bg);
+  border: 1px solid var(--shell-border);
+  border-radius: 14px;
+  box-shadow: 0 24px 48px rgba(0, 0, 0, 0.5);
+  padding: 32px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+.template-picker-header {
+  text-align: center;
+  margin-bottom: 28px;
+}
+
+.template-picker-logo {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 52px;
+  height: 52px;
+  border-radius: 14px;
+  background: linear-gradient(135deg, #a855f7, #7c3aed);
+  color: #fff;
+  margin-bottom: 16px;
+}
+
+.template-picker-header h2 {
+  font-size: 22px;
+  font-weight: 700;
+  color: var(--modal-text);
+  margin: 0 0 6px;
+  letter-spacing: -0.02em;
+}
+
+.template-picker-header p {
+  font-size: 14px;
+  color: var(--shell-muted);
+  margin: 0;
+}
+
+.template-picker-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 12px;
+  width: 100%;
+}
+
+.template-card {
+  display: flex;
+  gap: 14px;
+  align-items: flex-start;
+  padding: 16px;
+  border: 1px solid var(--shell-control-border);
+  border-radius: 10px;
+  background: var(--shell-control-bg);
+  cursor: pointer;
+  text-align: left;
+  transition:
+    border-color 0.15s,
+    box-shadow 0.15s,
+    transform 0.1s;
+  font-family: inherit;
+  color: inherit;
+}
+
+.template-card:hover {
+  border-color: #a855f7;
+  box-shadow: 0 0 0 2px rgba(168, 85, 247, 0.18);
+  transform: translateY(-1px);
+}
+
+.template-card-icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 44px;
+  height: 44px;
+  border-radius: 10px;
+  background: linear-gradient(
+    135deg,
+    rgba(168, 85, 247, 0.12),
+    rgba(124, 58, 237, 0.08)
+  );
+  color: #a855f7;
+  flex-shrink: 0;
+}
+
+.template-card-body h3 {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--modal-text);
+  margin: 0 0 4px;
+}
+
+.template-card-body p {
+  font-size: 12px;
+  color: var(--shell-muted);
+  margin: 0 0 8px;
+  line-height: 1.4;
+}
+
+.template-card-tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+}
+
+.template-tag {
+  font-size: 10px;
+  font-weight: 500;
+  color: var(--shell-muted);
+  background: var(--shell-bg);
+  border: 1px solid var(--shell-border);
+  border-radius: 4px;
+  padding: 1px 6px;
+}
+
+.template-blank-btn {
+  margin-top: 18px;
+  border: none;
+  background: transparent;
+  color: var(--shell-muted);
+  font-size: 13px;
+  cursor: pointer;
+  padding: 6px 12px;
+  border-radius: 6px;
+  transition:
+    color 0.15s,
+    background 0.15s;
+  font-family: inherit;
+}
+
+.template-blank-btn:hover {
+  color: var(--modal-text);
+  background: var(--shell-control-bg);
+}
+
+/* ── Next Steps Guide ── */
+@keyframes next-steps-slide-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.next-steps-guide {
+  position: absolute;
+  bottom: 12px;
+  left: 12px;
+  right: 12px;
+  background: #161b22;
+  border: 1px solid #30363d;
+  border-radius: 10px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+  padding: 14px;
+  z-index: 20;
+  animation: next-steps-slide-in 0.25s ease-out;
+}
+
+.next-steps-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: 8px;
+  margin-bottom: 10px;
+}
+
+.next-steps-title {
+  margin: 0;
+  font-size: 13px;
+  font-weight: 700;
+  color: #f0f6fc;
+}
+
+.next-steps-subtitle {
+  margin: 2px 0 0;
+  font-size: 11px;
+  color: #8b949e;
+}
+
+.next-steps-close {
+  width: 24px;
+  height: 24px;
+  border: 1px solid #30363d;
+  border-radius: 6px;
+  background: transparent;
+  color: #8b949e;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  flex-shrink: 0;
+  transition:
+    color 0.15s,
+    border-color 0.15s;
+}
+
+.next-steps-close:hover {
+  color: #f0f6fc;
+  border-color: #484f58;
+}
+
+.next-steps-list {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.next-steps-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  padding: 8px 10px;
+  border: 1px solid transparent;
+  border-radius: 7px;
+  background: transparent;
+  color: #e1e4e8;
+  font-family: inherit;
+  text-align: left;
+  cursor: pointer;
+  transition:
+    background 0.12s,
+    border-color 0.12s;
+}
+
+.next-steps-item:hover:not(:disabled) {
+  background: rgba(255, 255, 255, 0.04);
+  border-color: #30363d;
+}
+
+.next-steps-item--done {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.next-steps-item--done:hover {
+  background: transparent;
+  border-color: transparent;
+}
+
+.next-steps-item-check {
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  transition:
+    background 0.15s,
+    border-color 0.15s;
+}
+
+.next-steps-item:not(.next-steps-item--done) .next-steps-item-check {
+  border: 1.5px solid #484f58;
+}
+
+.next-steps-item--done .next-steps-item-check {
+  background: #238636;
+  color: #fff;
+  border: none;
+}
+
+.next-steps-item-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: #484f58;
+  transition: background 0.15s;
+}
+
+.next-steps-item:hover:not(:disabled) .next-steps-item-dot {
+  background: #a855f7;
+}
+
+.next-steps-item-body {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  min-width: 0;
+  flex: 1;
+}
+
+.next-steps-item-title {
+  font-size: 12px;
+  font-weight: 600;
+  color: #f0f6fc;
+}
+
+.next-steps-item-desc {
+  font-size: 11px;
+  color: #8b949e;
+}
+
+.next-steps-item-arrow {
+  flex-shrink: 0;
+  color: #484f58;
+  transition:
+    color 0.15s,
+    transform 0.15s;
+}
+
+.next-steps-item:hover:not(:disabled) .next-steps-item-arrow {
+  color: #a855f7;
+  transform: translateX(2px);
+}
diff --git a/packages/playground/src/main.tsx b/packages/playground/src/main.tsx
new file mode 100644
index 000000000..0912a82a3
--- /dev/null
+++ b/packages/playground/src/main.tsx
@@ -0,0 +1,34 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
+import App from './App';
+import Landing from './pages/Landing';
+import './index.css';
+
+// Enable react-scan in development only (dynamic import to avoid bundling in prod)
+if (import.meta.env.DEV) {
+  import('react-scan').then((m) => m.scan({ enabled: true }));
+}
+
+/** Show landing page unless the URL carries query params or a hash (shared link). */
+function RootRoute() {
+  const hasState = window.location.search || window.location.hash;
+  if (hasState) {
+    return <App />;
+  }
+  return <Landing />;
+}
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={<RootRoute />} />
+        <Route path="/new" element={<App />} />
+        <Route path="/playground" element={<App />} />
+        <Route path="/playground/new" element={<App />} />
+        <Route path="/playground/:workspaceId" element={<App />} />
+      </Routes>
+    </BrowserRouter>
+  </StrictMode>,
+);
diff --git a/packages/playground/src/monaco/ec-completion.ts b/packages/playground/src/monaco/ec-completion.ts
new file mode 100644
index 000000000..1cf843235
--- /dev/null
+++ b/packages/playground/src/monaco/ec-completion.ts
@@ -0,0 +1,368 @@
+import type { Monaco } from '@monaco-editor/react';
+import type { editor, languages, Position, CancellationToken } from 'monaco-editor';
+import {
+  parseSpec,
+  parseOpenApiSpec,
+  detectSpecType,
+  RESOURCE_KEYWORDS,
+  COMMON_PROPS,
+  ANNOTATION_SUGGESTIONS,
+  CONTEXT_SUGGESTIONS,
+  MESSAGE_TYPE_PLURAL,
+  collectRegexMatches,
+  collectChannelNames,
+  collectMessageNames,
+  extractResourceVersions,
+  extractResourceNamesFromText,
+  parseSpecAuto,
+  findEnclosingResource,
+  isSpecFile,
+} from '@eventcatalog/language-server/browser';
+import type { Suggestion, SpecMessage } from '@eventcatalog/language-server/browser';
+
+// ─── State & caching ────────────────────────────────────
+
+let _allFilesSources: Record<string, string> = {};
+const _fetchedSpecCache = new Map<string, string>();
+
+// Invalidated when _allFilesSources changes
+let _cachedAllText: string | null = null;
+let _cachedSpecParsed: Map<string, ReturnType<typeof parseSpec>> | null = null;
+
+export function setAllFilesSources(files: Record<string, string>) {
+  _allFilesSources = files;
+  _cachedAllText = null;
+  _cachedSpecParsed = null;
+}
+
+/**
+ * Cache fetched remote spec content so autocompletion can parse it.
+ * Called by the playground when remote AsyncAPI specs are fetched.
+ */
+export function cacheSpecContent(url: string, content: string) {
+  _fetchedSpecCache.set(url, content);
+  _cachedSpecParsed = null;
+}
+
+function getAllText(): string {
+  if (_cachedAllText === null) {
+    _cachedAllText = Object.values(_allFilesSources).join('\n');
+  }
+  return _cachedAllText;
+}
+
+function getParsedSpecs(): Map<string, ReturnType<typeof parseSpec>> {
+  if (_cachedSpecParsed === null) {
+    _cachedSpecParsed = new Map();
+    for (const [filename, content] of Object.entries(_allFilesSources)) {
+      if (isSpecFile(filename)) {
+        try {
+          const parsed = parseSpecAuto(content);
+          // Normalize to same shape as parseSpec return (add errors field)
+          _cachedSpecParsed.set(filename, { ...parsed, errors: [] });
+        } catch { /* skip invalid specs */ }
+      }
+    }
+    for (const [url, content] of _fetchedSpecCache) {
+      try {
+        const parsed = parseSpecAuto(content);
+        _cachedSpecParsed.set(url, { ...parsed, errors: [] });
+      } catch { /* skip invalid specs */ }
+    }
+  }
+  return _cachedSpecParsed;
+}
+
+// ─── Shared helpers for completion handlers ─────────────
+
+function lookupSpecContent(specPath: string): string | undefined {
+  const normalizedPath = specPath.replace(/^\.\//, '');
+  return _allFilesSources[specPath]
+    ?? _allFilesSources[normalizedPath]
+    ?? _allFilesSources[`./${normalizedPath}`]
+    ?? _fetchedSpecCache.get(specPath);
+}
+
+function getSpecSummaries(
+  kind: 'messages' | 'channels',
+  filterNames?: Set<string>,
+): Map<string, string> {
+  const summaries = new Map<string, string>();
+  for (const [, parsed] of getParsedSpecs()) {
+    const catalog = kind === 'channels' ? parsed.channels : parsed.messages;
+    for (const [name, resource] of catalog) {
+      if ((!filterNames || filterNames.has(name)) && resource.summary) {
+        summaries.set(name, resource.summary);
+      }
+    }
+  }
+  return summaries;
+}
+
+function makeRange(position: Position, word: { startColumn: number; endColumn: number }) {
+  return {
+    startLineNumber: position.lineNumber,
+    startColumn: word.startColumn,
+    endLineNumber: position.lineNumber,
+    endColumn: word.endColumn,
+  };
+}
+
+// ─── Completion provider ────────────────────────────────
+
+export function registerEcCompletion(monaco: Monaco) {
+  monaco.languages.registerCompletionItemProvider('ec', {
+    triggerCharacters: ['@', '"', '{', ' '],
+    provideCompletionItems(
+      model: editor.ITextModel,
+      position: Position,
+      _context: languages.CompletionContext,
+      _token: CancellationToken,
+    ): languages.ProviderResult<languages.CompletionList> {
+      const textUntilPosition = model.getValueInRange({
+        startLineNumber: 1,
+        startColumn: 1,
+        endLineNumber: position.lineNumber,
+        endColumn: position.column,
+      });
+
+      const lineContent = model.getLineContent(position.lineNumber);
+      const textBeforeCursor = lineContent.substring(0, position.column - 1);
+
+      // Auto-complete file paths in import from "..."
+      const importFromMatch = textBeforeCursor.match(/import\s+(?:(?:events|commands|queries|channels|containers)\s+)?\{[^}]*\}\s*from\s*"([^"]*)$/);
+      if (importFromMatch) {
+        const range = {
+          startLineNumber: position.lineNumber,
+          startColumn: position.column - importFromMatch[1].length,
+          endLineNumber: position.lineNumber,
+          endColumn: position.column,
+        };
+
+        const fileNames = Object.keys(_allFilesSources).filter(f => f !== model.uri.path.split('/').pop());
+
+        return {
+          suggestions: fileNames.map((filename, i) => ({
+            label: `./${filename}`,
+            kind: monaco.languages.CompletionItemKind.File,
+            detail: `Import from ${filename}`,
+            insertText: `./${filename}`,
+            range,
+            sortText: String(i).padStart(5, '0'),
+          })),
+        };
+      }
+
+      // Auto-complete resource names inside import { ... }
+      const importBracesMatch = textBeforeCursor.match(/import\s+(?:(events|commands|queries|channels|containers)\s+)?\{([^}]*)$/);
+      if (importBracesMatch) {
+        const word = model.getWordUntilPosition(position);
+        const range = makeRange(position, word);
+        const resourceKind = importBracesMatch[1] as 'events' | 'commands' | 'queries' | 'channels' | 'containers' | undefined;
+        const alreadyImported = new Set(
+          (importBracesMatch[2] || '').split(',').map(s => s.trim()).filter(Boolean)
+        );
+
+        const fromSpecMatch = lineContent.match(/from\s*"([^"]+\.(?:ya?ml|json))"/);
+
+        if (resourceKind && fromSpecMatch) {
+          const specContent = lookupSpecContent(fromSpecMatch[1]);
+          if (specContent) {
+            try {
+              const parsed = parseSpecAuto(specContent);
+              const catalog = resourceKind === 'channels' ? parsed.channels : parsed.messages;
+              const normalizedPath = fromSpecMatch[1].replace(/^\.\//, '');
+
+              return {
+                suggestions: [...catalog.entries()]
+                  .filter(([name]) => !alreadyImported.has(name))
+                  .map(([name, resource], i) => ({
+                    label: name,
+                    kind: monaco.languages.CompletionItemKind.Field,
+                    detail: resource.summary || `Import from ${normalizedPath}`,
+                    insertText: name,
+                    range,
+                    sortText: String(i).padStart(5, '0'),
+                  })),
+              };
+            } catch {
+              // Fall through to generic suggestions
+            }
+          }
+        }
+
+        // .ec file imports: only suggest resources defined in the target file
+        const fromEcMatch = lineContent.match(/from\s*"([^"]+\.ec)"/);
+        if (fromEcMatch) {
+          const normalizedPath = fromEcMatch[1].replace(/^\.\//, '');
+          const ecContent = _allFilesSources[fromEcMatch[1]]
+            ?? _allFilesSources[normalizedPath]
+            ?? _allFilesSources[`./${normalizedPath}`];
+          if (ecContent) {
+            const names = extractResourceNamesFromText(ecContent);
+            return {
+              suggestions: [...names]
+                .filter(name => !alreadyImported.has(name))
+                .map((name, i) => ({
+                  label: name,
+                  kind: monaco.languages.CompletionItemKind.Class,
+                  detail: `Import from ${fromEcMatch[1]}`,
+                  insertText: name,
+                  range,
+                  sortText: String(i).padStart(5, '0'),
+                })),
+            };
+          }
+        }
+
+        // Fallback: suggest resource names from all workspace .ec files
+        const allText = getAllText();
+        const resources = extractResourceNamesFromText(allText);
+
+        return {
+          suggestions: [...resources]
+            .filter(name => !alreadyImported.has(name))
+            .map((name, i) => ({
+              label: name,
+              kind: monaco.languages.CompletionItemKind.Class,
+              detail: 'Resource to import',
+              insertText: name,
+              range,
+              sortText: String(i).padStart(5, '0'),
+            })),
+        };
+      }
+
+      // Auto-complete channel names after "sends event Name to" or "receives event Name from"
+      const channelRefMatch = textBeforeCursor.match(/\b(?:sends|receives)\s+(?:event|command|query)\s+[a-zA-Z_][a-zA-Z0-9_.\-]*(?:@[\d]+\.[\d]+\.[\d]+[a-zA-Z0-9_.\-]*)?\s+(?:to|from)\s+(?:.*,\s*)?([a-zA-Z_][a-zA-Z0-9_.\-]*)?$/);
+      if (channelRefMatch) {
+        const allText = getAllText();
+        const channels = collectChannelNames(allText);
+
+        // Also include channel names from parsed AsyncAPI specs
+        for (const [, parsed] of getParsedSpecs()) {
+          for (const name of parsed.channels.keys()) {
+            channels.add(name);
+          }
+        }
+
+        const summaries = getSpecSummaries('channels');
+        const word = model.getWordUntilPosition(position);
+        const range = makeRange(position, word);
+
+        return {
+          suggestions: [...channels].map((name, i) => ({
+            label: name,
+            kind: monaco.languages.CompletionItemKind.Field,
+            detail: summaries.get(name) || `channel ${name}`,
+            insertText: name,
+            range,
+            sortText: String(i).padStart(5, '0'),
+          })),
+        };
+      }
+
+      // Auto-complete resource names after "sends event", "receives command", etc.
+      const sendsReceivesMatch = textBeforeCursor.match(/\b(?:sends|receives)\s+(event|command|query)\s+([a-zA-Z_][a-zA-Z0-9_.\-]*)?$/);
+      if (sendsReceivesMatch && !sendsReceivesMatch[0].endsWith('@')) {
+        const msgType = sendsReceivesMatch[1];
+        const pluralType = MESSAGE_TYPE_PLURAL[msgType] || 'events';
+        const allText = getAllText();
+        const names = collectMessageNames(allText, msgType, pluralType);
+
+        const summaries = getSpecSummaries('messages', names);
+        const word = model.getWordUntilPosition(position);
+        const range = makeRange(position, word);
+
+        return {
+          suggestions: [...names].map((name, i) => ({
+            label: name,
+            kind: monaco.languages.CompletionItemKind.Field,
+            detail: summaries.get(name) || `${msgType} ${name}`,
+            insertText: name,
+            range,
+            sortText: String(i).padStart(5, '0'),
+          })),
+        };
+      }
+
+      // Auto-complete version after "sends event Name@"
+      const atMatch = textBeforeCursor.match(/\b(?:sends|receives)\s+(event|command|query)\s+([a-zA-Z_][a-zA-Z0-9_.\-]*)@$/);
+      if (atMatch) {
+        const key = `${atMatch[1]}:${atMatch[2]}`;
+        const versions = extractResourceVersions(getAllText()).get(key) || [];
+
+        return {
+          suggestions: versions.map((ver, i) => ({
+            label: ver,
+            kind: monaco.languages.CompletionItemKind.Value,
+            detail: `Version ${ver} of ${atMatch[2]}`,
+            insertText: ver,
+            range: {
+              startLineNumber: position.lineNumber,
+              startColumn: position.column,
+              endLineNumber: position.lineNumber,
+              endColumn: position.column,
+            },
+            sortText: String(i).padStart(5, '0'),
+          })),
+        };
+      }
+
+      // For non-import completions, don't suggest inside strings
+      const quoteCount = (textBeforeCursor.match(/(?<!\\)"/g) || []).length;
+      if (quoteCount % 2 === 1) {
+        return { suggestions: [] };
+      }
+
+      // Offer annotation completions after '@' inside a resource block
+      const annotationMatch = textBeforeCursor.match(/@([a-zA-Z]*)$/);
+      if (annotationMatch) {
+        const enclosing = findEnclosingResource(textUntilPosition);
+        if (enclosing) {
+          const typed = annotationMatch[1];
+          const annRange = {
+            startLineNumber: position.lineNumber,
+            startColumn: position.column - typed.length,
+            endLineNumber: position.lineNumber,
+            endColumn: position.column,
+          };
+          const filtered = typed
+            ? ANNOTATION_SUGGESTIONS.filter((ann) => ann.label.replace('@', '').startsWith(typed))
+            : ANNOTATION_SUGGESTIONS;
+          return {
+            suggestions: filtered.map((ann, i) => ({
+              label: ann.label,
+              kind: monaco.languages.CompletionItemKind.Snippet,
+              detail: ann.detail,
+              insertText: ann.insertText,
+              insertTextRules: monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet,
+              range: annRange,
+              filterText: ann.label.replace('@', ''),
+              sortText: String(i).padStart(5, '0'),
+            })),
+          };
+        }
+      }
+
+      const word = model.getWordUntilPosition(position);
+      const range = makeRange(position, word);
+
+      const enclosingResource = findEnclosingResource(textUntilPosition);
+      const items = enclosingResource
+        ? (CONTEXT_SUGGESTIONS[enclosingResource] || COMMON_PROPS)
+        : RESOURCE_KEYWORDS;
+
+      return {
+        suggestions: items.map((kw) => ({
+          label: kw.label,
+          kind: monaco.languages.CompletionItemKind.Snippet,
+          detail: kw.detail,
+          insertText: kw.insertText,
+          insertTextRules: monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet,
+          range,
+        })),
+      };
+    },
+  });
+}
diff --git a/packages/playground/src/monaco/ec-diagnostics.ts b/packages/playground/src/monaco/ec-diagnostics.ts
new file mode 100644
index 000000000..33c94bab5
--- /dev/null
+++ b/packages/playground/src/monaco/ec-diagnostics.ts
@@ -0,0 +1,48 @@
+import type { Monaco } from '@monaco-editor/react';
+import type { editor } from 'monaco-editor';
+import type { FileOffsets } from '../hooks/useDslParser';
+
+export interface DslError {
+  message: string;
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+}
+
+export function getErrorsForFile(
+  errors: DslError[],
+  activeFile: string,
+  fileOffsets: FileOffsets,
+): DslError[] {
+  const offset = fileOffsets[activeFile];
+  if (!offset) return [];
+
+  const { startLine, lineCount } = offset;
+  const endLine = startLine + lineCount - 1;
+
+  return errors
+    .filter((err) => err.line >= startLine && err.line <= endLine)
+    .map((err) => ({
+      ...err,
+      line: err.line - startLine + 1,
+      endLine: err.endLine != null ? err.endLine - startLine + 1 : undefined,
+    }));
+}
+
+export function setDiagnostics(
+  monaco: Monaco,
+  model: editor.ITextModel,
+  errors: DslError[],
+) {
+  const markers: editor.IMarkerData[] = errors.map((err) => ({
+    severity: monaco.MarkerSeverity.Error,
+    message: err.message,
+    startLineNumber: err.line,
+    startColumn: err.column,
+    endLineNumber: err.endLine ?? err.line,
+    endColumn: err.endColumn ?? err.column + 1,
+  }));
+
+  monaco.editor.setModelMarkers(model, 'ec', markers);
+}
diff --git a/packages/playground/src/monaco/ec-language.ts b/packages/playground/src/monaco/ec-language.ts
new file mode 100644
index 000000000..9d63bf999
--- /dev/null
+++ b/packages/playground/src/monaco/ec-language.ts
@@ -0,0 +1,100 @@
+import type { Monaco } from '@monaco-editor/react';
+
+export function registerEcLanguage(monaco: Monaco) {
+  monaco.languages.register({ id: 'ec' });
+
+  monaco.languages.setMonarchTokensProvider('ec', {
+    keywords: [
+      'domain', 'service', 'event', 'command', 'query', 'channel',
+      'container', 'data-product', 'flow', 'diagram', 'user', 'team',
+      'sends', 'receives', 'publishes', 'subscribes', 'writes-to', 'reads-from',
+      'to', 'from', 'push', 'pull', 'push-pull', 'delivery',
+      'version', 'summary', 'owner', 'owners', 'name', 'display-name', 'markdown',
+      'step', 'node', 'message', 'actor', 'custom', 'label', 'next', 'id',
+      'draft', 'deprecated', 'schema', 'address', 'protocol',
+      'parameter',
+      'producer', 'consumer', 'route', 'member',
+      'subdomain', 'visualizer',
+      'legend', 'search', 'toolbar', 'focus-mode', 'style', 'post-it',
+      'input', 'output', 'contract',
+      'container-type', 'technology', 'authoritative',
+      'access-mode', 'classification', 'residency', 'retention',
+      'true', 'false', 'required',
+      'database', 'cache', 'objectStore', 'searchIndex',
+      'dataWarehouse', 'dataLake', 'externalSaaS', 'other',
+      'read', 'write', 'readWrite', 'appendOnly',
+      'public', 'internal', 'confidential', 'regulated',
+    ],
+
+    tokenizer: {
+      root: [
+        [/\/\/.*$/, 'comment'],
+        [/\/\*/, 'comment', '@comment'],
+        [/"[^"]*"/, 'string'],
+        [/@[a-zA-Z][\w-]*/, 'annotation'],
+        [/\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?/, 'number.version'],
+        [/[a-zA-Z_][\w.-]*(\{[a-zA-Z0-9_]+\}[\w.-]*)+/, 'identifier'],
+        [/[a-zA-Z_][\w-]*/, {
+          cases: {
+            '@keywords': 'keyword',
+            '@default': 'identifier',
+          },
+        }],
+        [/[{}()\[\],:]/, 'delimiter'],
+        [/->/, 'operator'],
+        [/\s+/, 'white'],
+      ],
+      comment: [
+        [/[^/*]+/, 'comment'],
+        [/\*\//, 'comment', '@pop'],
+        [/[/*]/, 'comment'],
+      ],
+    },
+  });
+
+  monaco.editor.defineTheme('ec-dark', {
+    base: 'vs-dark',
+    inherit: true,
+    rules: [
+      { token: 'keyword', foreground: '569cd6', fontStyle: 'bold' },
+      { token: 'annotation', foreground: 'c586c0' },
+      { token: 'string', foreground: 'ce9178' },
+      { token: 'comment', foreground: '6a9955' },
+      { token: 'number.version', foreground: 'b5cea8' },
+      { token: 'identifier', foreground: '9cdcfe' },
+      { token: 'delimiter', foreground: 'd4d4d4' },
+      { token: 'operator', foreground: 'd4d4d4' },
+    ],
+    colors: {
+      'editor.background': '#0d1117',
+      'editor.foreground': '#e1e4e8',
+      'editorLineNumber.foreground': '#484f58',
+      'editorLineNumber.activeForeground': '#e1e4e8',
+      'editor.selectionBackground': '#264f78',
+      'editor.lineHighlightBackground': '#161b22',
+    },
+  });
+
+  monaco.editor.defineTheme('ec-light', {
+    base: 'vs',
+    inherit: true,
+    rules: [
+      { token: 'keyword', foreground: '0550ae', fontStyle: 'bold' },
+      { token: 'annotation', foreground: '8250df' },
+      { token: 'string', foreground: '0a3069' },
+      { token: 'comment', foreground: '6e7781' },
+      { token: 'number.version', foreground: '1f883d' },
+      { token: 'identifier', foreground: '24292f' },
+      { token: 'delimiter', foreground: '57606a' },
+      { token: 'operator', foreground: '57606a' },
+    ],
+    colors: {
+      'editor.background': '#ffffff',
+      'editor.foreground': '#1f2328',
+      'editorLineNumber.foreground': '#8c959f',
+      'editorLineNumber.activeForeground': '#24292f',
+      'editor.selectionBackground': '#dbeafe',
+      'editor.lineHighlightBackground': '#f6f8fa',
+    },
+  });
+}
diff --git a/packages/playground/src/pages/Landing.css b/packages/playground/src/pages/Landing.css
new file mode 100644
index 000000000..2cb7edfcc
--- /dev/null
+++ b/packages/playground/src/pages/Landing.css
@@ -0,0 +1,2119 @@
+html:has(.landing) {
+  scroll-behavior: smooth;
+}
+
+.landing {
+  --bg-deep: #0b0d11;
+  --bg-surface: #12151b;
+  --bg-elevated: #1a1e27;
+  --bg-code: #0e1117;
+  --accent: #6366f1;
+  --accent-soft: rgba(99, 102, 241, 0.12);
+  --accent-border: rgba(99, 102, 241, 0.25);
+  --green: #34d399;
+  --orange: #fb923c;
+  --cyan: #22d3ee;
+  --yellow: #fbbf24;
+  --text-primary: #e8eaed;
+  --text-secondary: #8b8fa3;
+  --text-muted: #4a4f63;
+  --border: rgba(255,255,255,0.06);
+  --border-hover: rgba(255,255,255,0.12);
+
+  background: var(--bg-deep);
+  color: var(--text-primary);
+  font-family: 'Inter', -apple-system, sans-serif;
+  -webkit-font-smoothing: antialiased;
+  min-height: 100vh;
+}
+
+/* --- Nav --- */
+.landing nav {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 100;
+  padding: 0 40px;
+  height: 56px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  background: rgba(11, 13, 17, 0.85);
+  backdrop-filter: blur(16px);
+  border-bottom: 1px solid var(--border);
+}
+
+.landing .nav-left {
+  display: flex;
+  align-items: center;
+  gap: 24px;
+}
+
+.landing .nav-brand {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  text-decoration: none;
+  color: var(--text-primary);
+  font-weight: 600;
+  font-size: 14px;
+}
+
+.landing .nav-brand svg { width: 22px; height: 22px; }
+
+.landing .nav-divider {
+  width: 1px;
+  height: 20px;
+  background: var(--border);
+}
+
+.landing .nav-product {
+  font-size: 14px;
+  font-weight: 500;
+  color: var(--text-secondary);
+}
+
+.landing .nav-badge {
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--green);
+  background: rgba(52, 211, 153, 0.1);
+  border: 1px solid rgba(52, 211, 153, 0.2);
+  padding: 2px 7px;
+  border-radius: 4px;
+  margin-left: 8px;
+}
+
+.landing .nav-links {
+  display: flex;
+  align-items: center;
+  gap: 28px;
+}
+
+.landing .nav-links a {
+  color: var(--text-secondary);
+  text-decoration: none;
+  font-size: 13px;
+  font-weight: 400;
+  transition: color 0.15s;
+}
+
+.landing .nav-links a:hover { color: var(--text-primary); }
+
+.landing .nav-cta {
+  background: var(--text-primary) !important;
+  color: var(--bg-deep) !important;
+  padding: 6px 16px !important;
+  border-radius: 6px;
+  font-weight: 600 !important;
+  font-size: 13px !important;
+  transition: opacity 0.15s !important;
+}
+
+.landing .nav-cta:hover { opacity: 0.9; }
+
+/* --- Hero --- */
+.landing .hero {
+  position: relative;
+  padding: 140px 40px 60px;
+  text-align: center;
+  max-width: 1200px;
+  margin: 0 auto;
+}
+
+/* Grid background */
+.landing .hero::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background-image:
+    linear-gradient(rgba(255, 255, 255, 0.04) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(255, 255, 255, 0.04) 1px, transparent 1px);
+  background-size: 48px 48px;
+  mask-image: radial-gradient(ellipse 70% 60% at 50% 40%, black 20%, transparent 70%);
+  -webkit-mask-image: radial-gradient(ellipse 70% 60% at 50% 40%, black 20%, transparent 70%);
+  pointer-events: none;
+  z-index: 0;
+}
+
+
+.landing .hero > * {
+  position: relative;
+  z-index: 1;
+}
+
+.landing .hero-eyebrow {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 13px;
+  color: var(--text-secondary);
+  margin-bottom: 24px;
+  animation: landing-fadeIn 0.6s ease-out;
+}
+
+.landing .hero-eyebrow .dot {
+  width: 5px;
+  height: 5px;
+  border-radius: 50%;
+  background: var(--green);
+  animation: landing-pulse 2.5s infinite;
+}
+
+@keyframes landing-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.3; }
+}
+
+.landing .hero h1 {
+  font-family: 'Inter', -apple-system, sans-serif;
+  font-size: clamp(40px, 5.5vw, 64px);
+  font-weight: 700;
+  line-height: 1.1;
+  letter-spacing: -0.03em;
+  max-width: 1100px;
+  margin: 0 auto 20px;
+  animation: landing-fadeUp 0.7s ease-out;
+}
+
+.landing .hero h1 .highlight {
+  background: linear-gradient(135deg, var(--accent), var(--cyan));
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+.landing .hero-sub {
+  font-size: 17px;
+  color: var(--text-secondary);
+  max-width: 780px;
+  margin: 0 auto 36px;
+  line-height: 1.65;
+  font-weight: 400;
+  animation: landing-fadeUp 0.7s ease-out 0.1s both;
+}
+
+.landing .hero-actions {
+  display: flex;
+  gap: 12px;
+  justify-content: center;
+  animation: landing-fadeUp 0.7s ease-out 0.2s both;
+}
+
+.landing .btn-primary {
+  background: var(--text-primary);
+  color: var(--bg-deep);
+  padding: 11px 24px;
+  border-radius: 8px;
+  font-size: 14px;
+  font-weight: 600;
+  text-decoration: none;
+  transition: all 0.2s;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  border: none;
+  cursor: pointer;
+}
+
+.landing .btn-primary:hover {
+  opacity: 0.9;
+  transform: translateY(-1px);
+}
+
+.landing .btn-ghost {
+  background: transparent;
+  color: var(--text-secondary);
+  padding: 11px 24px;
+  border-radius: 8px;
+  font-size: 14px;
+  font-weight: 500;
+  text-decoration: none;
+  transition: all 0.2s;
+  border: 1px solid var(--border);
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.landing .btn-ghost:hover {
+  color: var(--text-primary);
+  border-color: var(--border-hover);
+  background: var(--bg-elevated);
+}
+
+@keyframes landing-fadeIn { from { opacity: 0; } to { opacity: 1; } }
+@keyframes landing-fadeUp {
+  from { opacity: 0; transform: translateY(16px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+/* --- Hero Editor Preview --- */
+.landing .hero-preview-wrapper {
+  max-width: 100%;
+  width: calc(100% - 40px);
+  margin: 48px auto 0;
+  min-width: 0;
+  animation: landing-fadeUp 0.8s ease-out 0.35s both;
+}
+
+/* Hero value pillars */
+.landing .hero-pillars {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 24px;
+  max-width: 100%;
+  width: calc(100% - 40px);
+  margin: 36px auto 0;
+  animation: landing-fadeUp 0.8s ease-out 0.45s both;
+}
+
+.landing .hero-pillar {
+  display: flex;
+  align-items: flex-start;
+  gap: 14px;
+  text-align: left;
+  background: var(--bg-code);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 20px;
+  transition: border-color 0.3s;
+}
+
+.landing .hero-pillar:hover {
+  border-color: var(--border-hover);
+}
+
+.landing .hero-pillar svg {
+  flex-shrink: 0;
+  color: var(--text-muted);
+  margin-top: 2px;
+}
+
+.landing .hero-pillar div {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.landing .hero-pillar strong {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.landing .hero-pillar span {
+  font-size: 13px;
+  color: var(--text-secondary);
+  line-height: 1.5;
+}
+
+.landing .editor-window {
+  background: var(--bg-code);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  overflow: hidden;
+  box-shadow: 0 24px 80px rgba(0,0,0,0.4);
+}
+
+.landing .editor-titlebar {
+  display: flex;
+  align-items: center;
+  padding: 10px 16px;
+  background: var(--bg-surface);
+  border-bottom: 1px solid var(--border);
+  gap: 10px;
+}
+
+.landing .editor-dots {
+  display: flex;
+  gap: 6px;
+}
+
+.landing .editor-dots span {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+}
+
+.landing .editor-dots span:nth-child(1) { background: #ef4444; }
+.landing .editor-dots span:nth-child(2) { background: #eab308; }
+.landing .editor-dots span:nth-child(3) { background: #22c55e; }
+
+.landing .editor-tabs {
+  display: flex;
+  gap: 2px;
+  margin-left: 12px;
+}
+
+.landing .editor-tab {
+  font-size: 12px;
+  color: var(--text-muted);
+  padding: 4px 12px;
+  border-radius: 4px;
+  font-family: 'Inter', sans-serif;
+}
+
+.landing .editor-tab.active {
+  color: var(--text-secondary);
+  background: var(--bg-elevated);
+}
+
+/* Split pane body */
+.landing .hero-editor-body {
+  display: flex;
+  height: 540px;
+}
+
+.landing .hero-editor-code {
+  height: 100%;
+  flex-shrink: 0;
+  overflow: hidden;
+}
+
+.landing .hero-editor-viz {
+  height: 100%;
+  position: relative;
+  flex-shrink: 0;
+  overflow: hidden;
+  background: rgb(22, 27, 34);
+}
+
+/* Resize handle between editor and viz */
+.landing .hero-resize-handle {
+  width: 6px;
+  cursor: col-resize;
+  background: var(--bg-surface);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  z-index: 10;
+  transition: background 0.15s;
+}
+
+.landing .hero-resize-handle:hover {
+  background: rgba(255,255,255,0.08);
+}
+
+.landing .hero-resize-line {
+  width: 2px;
+  height: 32px;
+  border-radius: 1px;
+  background: var(--text-muted);
+  transition: background 0.15s, height 0.15s;
+}
+
+.landing .hero-resize-handle:hover .hero-resize-line {
+  background: #a855f7;
+  height: 48px;
+}
+
+/* Hide ReactFlow toolbar, controls, minimap, attribution inside hero */
+.landing .react-flow__panel,
+.landing .react-flow__controls,
+.landing .react-flow__minimap,
+.landing .react-flow__attribution {
+  display: none !important;
+}
+
+/* Syntax highlight classes used in code blocks below the hero */
+.landing .kw { color: #c084fc; }
+.landing .str { color: var(--orange); }
+.landing .ref { color: var(--cyan); }
+.landing .cm { color: var(--text-muted); font-style: italic; }
+.landing .fn { color: var(--green); }
+.landing .br { color: var(--text-muted); }
+
+/* Mobile visualizer card — hidden on desktop */
+.landing .hero-viz-mobile {
+  display: none;
+  background: var(--bg-code);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  overflow: hidden;
+}
+
+.landing .hero-viz-mobile-label {
+  padding: 10px 16px;
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-muted);
+  border-bottom: 1px solid var(--border);
+  background: var(--bg-surface);
+}
+
+.landing .hero-viz-mobile-inner {
+  position: relative;
+  height: 300px;
+  background: rgb(22, 27, 34);
+}
+
+/* --- Sections --- */
+.landing .section {
+  padding: 100px 40px;
+  max-width: 1060px;
+  margin: 0 auto;
+}
+
+.landing .section-center { text-align: center; }
+
+.landing .section-label {
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+  margin-bottom: 12px;
+}
+
+.landing .section-label-red {
+  color: #f87171;
+}
+
+.landing .section-title {
+  font-size: clamp(28px, 3.5vw, 40px);
+  font-weight: 700;
+  letter-spacing: -0.025em;
+  line-height: 1.2;
+  margin-bottom: 16px;
+}
+
+.landing .section-desc {
+  font-size: 16px;
+  color: var(--text-secondary);
+  max-width: 500px;
+  line-height: 1.65;
+  font-weight: 400;
+}
+
+.landing .section-center .section-desc { margin: 0 auto; }
+
+/* --- Icons --- */
+.landing .icon-box {
+  width: 36px;
+  height: 36px;
+  border-radius: 8px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: 16px;
+  background: var(--bg-elevated);
+  border: 1px solid var(--border);
+}
+
+.landing .icon-box svg {
+  width: 18px;
+  height: 18px;
+  stroke-width: 1.5;
+}
+
+/* --- Problem --- */
+/* --- Bento Grid (Supabase style) --- */
+.landing .bento-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 16px;
+  margin-top: 48px;
+  max-width: 1080px;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.landing .bento-card {
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  transition: border-color 0.3s;
+}
+
+.landing .bento-card:hover {
+  border-color: var(--border-hover);
+}
+
+.landing .bento-col-2 { grid-column: span 2; }
+.landing .bento-col-3 { grid-column: span 3; }
+
+/* Text area at top of card */
+.landing .bento-text {
+  padding: 28px 28px 0;
+  text-align: left;
+}
+
+.landing .bento-icon {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-bottom: 10px;
+}
+
+.landing .bento-icon svg {
+  stroke: #ef4444 !important;
+}
+
+.landing .bento-icon span {
+  font-size: 15px;
+  font-weight: 600;
+  color: #ef4444;
+}
+
+.landing .bento-card p {
+  font-size: 13px;
+  color: var(--text-secondary);
+  line-height: 1.65;
+}
+
+.landing .bento-card p strong {
+  color: var(--text-primary);
+  font-weight: 500;
+}
+
+/* Visual area */
+.landing .bento-viz {
+  flex: 1;
+  position: relative;
+  min-height: 200px;
+  margin: 20px 16px 16px;
+  border-radius: 8px;
+  background: var(--bg-code);
+  border: 1px solid var(--border);
+  overflow: hidden;
+}
+
+/* ---- Specs in silos visual ---- */
+.landing .bento-files-scatter {
+  position: absolute;
+  inset: 0;
+}
+
+.landing .bento-file-card {
+  position: absolute;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 14px;
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  font-size: 11px;
+  font-family: 'JetBrains Mono', monospace;
+  color: var(--text-secondary);
+  white-space: nowrap;
+  transition: transform 0.4s cubic-bezier(0.16, 1, 0.3, 1), border-color 0.3s, opacity 0.3s;
+}
+
+/* Specs in silos: file cards drift apart on hover */
+.landing .bento-card:hover .bento-file-card:nth-child(1) { transform: translate(-6px, -4px); }
+.landing .bento-card:hover .bento-file-card:nth-child(2) { transform: translate(6px, -4px); }
+.landing .bento-card:hover .bento-file-card:nth-child(3) { transform: translate(-6px, 4px); }
+.landing .bento-card:hover .bento-file-card:nth-child(4) { transform: translate(6px, 4px); }
+
+.landing .bento-scatter-lines line {
+  transition: opacity 0.4s;
+}
+.landing .bento-card:hover .bento-scatter-lines line {
+  opacity: 0.15 !important;
+}
+
+.landing .bento-file-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.landing .bento-file-dot-cyan { background: var(--cyan); }
+.landing .bento-file-dot-green { background: var(--green); }
+
+.landing .bento-scatter-lines {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+}
+
+.landing .bento-scatter-label {
+  position: absolute;
+  bottom: 10px;
+  left: 50%;
+  transform: translateX(-50%);
+  font-size: 10px;
+  color: var(--text-muted);
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  font-weight: 500;
+}
+
+/* ---- Stale diagram visual ---- */
+.landing .bento-stale-diagram {
+  position: absolute;
+  inset: 0;
+}
+
+.landing .bento-stale-node {
+  position: absolute;
+  width: 32px;
+  height: 32px;
+  background: var(--bg-elevated);
+  border: 1px solid var(--border-hover);
+  border-radius: 8px;
+  opacity: 0.35;
+  transition: opacity 0.4s, transform 0.4s;
+}
+
+/* Stale diagram: nodes fade out more, lines dim, stamp glows */
+.landing .bento-card:hover .bento-stale-node {
+  opacity: 0.15;
+  transform: scale(0.9);
+}
+
+.landing .bento-stale-lines line {
+  transition: opacity 0.4s;
+}
+.landing .bento-card:hover .bento-stale-lines line {
+  opacity: 0.12 !important;
+}
+
+.landing .bento-stale-stamp {
+  transition: background 0.3s, border-color 0.3s;
+}
+.landing .bento-card:hover .bento-stale-stamp {
+  background: rgba(251, 146, 60, 0.12);
+  border-color: rgba(251, 146, 60, 0.25);
+}
+
+.landing .bento-stale-lines {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+}
+
+.landing .bento-stale-stamp {
+  position: absolute;
+  bottom: 12px;
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 10px;
+  color: var(--orange);
+  background: rgba(251, 146, 60, 0.06);
+  border: 1px solid rgba(251, 146, 60, 0.12);
+  border-radius: 6px;
+  padding: 4px 12px;
+  font-family: 'JetBrains Mono', monospace;
+  white-space: nowrap;
+}
+
+/* ---- Tribal knowledge visual ---- */
+.landing .bento-tribal-viz {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 16px;
+}
+
+.landing .bento-tribal-person {
+  position: relative;
+}
+
+.landing .bento-tribal-bubbles {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 6px;
+  padding: 0 12px;
+}
+
+.landing .bento-tribal-bubbles span {
+  font-size: 10px;
+  font-family: 'JetBrains Mono', monospace;
+  color: var(--text-muted);
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  padding: 3px 8px;
+  animation: bento-float 3s ease-in-out infinite alternate;
+  transition: color 0.3s, border-color 0.3s;
+}
+
+/* Tribal knowledge: bubbles scatter and brighten on hover */
+.landing .bento-card:hover .bento-tribal-bubbles span {
+  animation-duration: 1.5s;
+  color: var(--text-secondary);
+  border-color: var(--border-hover);
+}
+
+.landing .bento-tribal-person svg {
+  transition: opacity 0.3s;
+}
+.landing .bento-card:hover .bento-tribal-person svg {
+  opacity: 0.3 !important;
+}
+
+@keyframes bento-float {
+  0% { opacity: 0.3; transform: translateY(2px); }
+  100% { opacity: 0.7; transform: translateY(-2px); }
+}
+
+/* ---- Before / After card ---- */
+.landing .bento-before-after {
+  display: grid;
+  grid-template-columns: 1fr 48px 1fr;
+  align-items: center;
+  padding: 28px;
+  gap: 0;
+}
+
+.landing .bento-ba-side {
+  padding: 20px;
+  background: var(--bg-code);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+}
+
+.landing .bento-ba-label {
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--orange);
+  margin-bottom: 14px;
+}
+
+.landing .bento-ba-label-green { color: var(--green); }
+
+.landing .bento-ba-content {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.landing .bento-ba-files {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.landing .bento-ba-files code {
+  font-size: 12px;
+  font-family: 'JetBrains Mono', monospace;
+  color: var(--text-secondary);
+  padding: 6px 10px;
+  background: var(--bg-surface);
+  border-radius: 4px;
+  display: block;
+}
+
+.landing .bento-ba-note {
+  font-size: 11px;
+  color: var(--text-muted);
+  margin-top: 8px;
+  display: block;
+}
+
+.landing .bento-ba-note-green { color: var(--green); }
+
+.landing .bento-ba-arrow {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--text-muted);
+  transition: transform 0.4s cubic-bezier(0.16, 1, 0.3, 1), color 0.3s;
+}
+
+/* Before/After: arrow slides right, after side brightens */
+.landing .bento-card:hover .bento-ba-arrow {
+  transform: translateX(4px);
+  color: var(--green);
+}
+
+.landing .bento-ba-after {
+  transition: opacity 0.3s, border-color 0.3s;
+}
+.landing .bento-card:hover .bento-ba-after {
+  border-color: rgba(52, 211, 153, 0.15);
+}
+
+.landing .bento-ba-side:first-child {
+  opacity: 0.6;
+}
+
+/* Statement below bento grid */
+.landing .bento-statement {
+  margin-top: 40px;
+  font-size: 20px;
+  line-height: 1.5;
+  color: var(--text-muted);
+  text-align: left;
+  max-width: 1080px;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.landing .bento-statement strong {
+  color: var(--text-primary);
+  font-weight: 600;
+}
+
+/* ---- Slow onboarding visual ---- */
+.landing .bento-onboarding-viz {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px;
+  overflow: hidden;
+}
+
+.landing .bento-chat-bubble {
+  font-size: 11px;
+  font-family: 'JetBrains Mono', monospace;
+  padding: 6px 12px;
+  border-radius: 8px;
+  max-width: 85%;
+  line-height: 1.4;
+}
+
+.landing .bento-chat-q {
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  color: var(--text-secondary);
+  align-self: flex-start;
+  transition: transform 0.3s cubic-bezier(0.16, 1, 0.3, 1), opacity 0.3s;
+}
+
+.landing .bento-chat-a {
+  background: var(--bg-elevated);
+  border: 1px solid var(--border);
+  color: var(--text-muted);
+  align-self: flex-end;
+  font-style: italic;
+  transition: transform 0.3s cubic-bezier(0.16, 1, 0.3, 1), opacity 0.3s;
+}
+
+/* Onboarding: chat bubbles slide in from sides on hover */
+.landing .bento-card:hover .bento-chat-q { transform: translateX(4px); }
+.landing .bento-card:hover .bento-chat-a { transform: translateX(-4px); opacity: 0.6; }
+
+/* ---- No source of truth visual ---- */
+.landing .bento-sources-viz {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px;
+  overflow: hidden;
+}
+
+.landing .bento-source-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  transition: transform 0.3s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+/* No source of truth: rows stagger/shift on hover */
+.landing .bento-card:hover .bento-source-row:nth-child(odd) { transform: translateX(3px); }
+.landing .bento-card:hover .bento-source-row:nth-child(even) { transform: translateX(-3px); }
+
+.landing .bento-source-val {
+  transition: color 0.3s;
+}
+.landing .bento-card:hover .bento-source-val {
+  color: var(--orange);
+}
+
+.landing .bento-source-pill {
+  font-size: 10px;
+  font-weight: 600;
+  font-family: 'JetBrains Mono', monospace;
+  color: var(--text-secondary);
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  padding: 4px 10px;
+  min-width: 80px;
+  text-align: center;
+  flex-shrink: 0;
+}
+
+.landing .bento-source-val {
+  font-size: 11px;
+  font-family: 'JetBrains Mono', monospace;
+  color: var(--text-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* --- Steps --- */
+.landing .steps {
+  margin-top: 48px;
+  display: flex;
+  flex-direction: column;
+}
+
+.landing .step {
+  padding: 32px 0;
+  border-top: 1px solid var(--border);
+}
+
+.landing .step-head {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  margin-bottom: 8px;
+}
+
+.landing .step-num {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--text-muted);
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: var(--bg-surface);
+  flex-shrink: 0;
+}
+
+.landing .step h3 {
+  font-size: 17px;
+  font-weight: 600;
+  margin: 0;
+}
+
+.landing .step p {
+  font-size: 14px;
+  color: var(--text-secondary);
+  line-height: 1.6;
+  margin-bottom: 16px;
+  max-width: 560px;
+}
+
+.landing .step-viz-container {
+  position: relative;
+  width: 100%;
+  height: 400px;
+  background: var(--bg-code);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.landing .code-block {
+  background: var(--bg-code);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 0;
+  font-family: 'JetBrains Mono', monospace;
+  font-size: 12.5px;
+  line-height: 1.75;
+  color: var(--text-secondary);
+  overflow-x: auto;
+}
+
+.landing .code-tab {
+  display: inline-block;
+  padding: 6px 14px;
+  font-size: 11.5px;
+  color: var(--text-muted);
+  border-bottom: 1px solid var(--border);
+  width: 100%;
+  box-sizing: border-box;
+}
+
+.landing .code-block pre {
+  padding: 16px 20px;
+  margin: 0;
+  font-family: inherit;
+  font-size: inherit;
+  line-height: inherit;
+  color: inherit;
+}
+
+/* --- Sources --- */
+.landing .sources-grid {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 12px;
+  margin-top: 48px;
+}
+
+.landing .source-card {
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 24px 16px;
+  text-align: center;
+  transition: all 0.2s;
+  text-decoration: none;
+  color: inherit;
+}
+
+.landing .source-card:hover {
+  border-color: var(--border-hover);
+  background: var(--bg-elevated);
+  transform: translateY(-2px);
+}
+
+.landing .source-card .source-icon-wrap {
+  width: 40px;
+  height: 40px;
+  border-radius: 10px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin: 0 auto 12px;
+  background: var(--bg-elevated);
+  border: 1px solid var(--border);
+}
+
+.landing .source-card .source-icon-wrap svg {
+  width: 20px;
+  height: 20px;
+  stroke-width: 1.5;
+}
+
+.landing .source-card .source-icon-wrap-ec {
+  background: #fff;
+  overflow: hidden;
+  padding: 0;
+}
+
+.landing .source-card .source-icon-wrap-ec img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  border-radius: 9px;
+}
+
+.landing .source-card h4 {
+  font-size: 13px;
+  font-weight: 600;
+  margin-bottom: 2px;
+}
+
+.landing .source-card .source-detail {
+  font-size: 11px;
+  color: var(--text-muted);
+}
+
+.landing .source-card.soon { opacity: 0.35 !important; }
+
+.landing .source-card.soon .source-detail::after {
+  content: ' \00B7  soon';
+  color: var(--text-muted);
+  font-style: italic;
+}
+
+/* --- Use Cases --- */
+.landing .usecases-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 16px;
+  margin-top: 48px;
+  max-width: 1080px;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.landing .usecase-card {
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  transition: border-color 0.3s;
+}
+
+.landing .usecase-card:hover { border-color: var(--border-hover); }
+
+.landing .usecase-header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 28px 28px 0;
+  text-align: left;
+}
+
+.landing .usecase-header svg {
+  stroke: var(--text-muted);
+  flex-shrink: 0;
+}
+
+.landing .usecase-card h3 {
+  font-size: 15px;
+  font-weight: 600;
+  margin: 0;
+}
+
+.landing .usecase-card p {
+  font-size: 13px;
+  color: var(--text-secondary);
+  line-height: 1.65;
+  padding: 10px 28px 0;
+  text-align: left;
+}
+
+.landing .usecase-card p strong {
+  color: var(--text-primary);
+  font-weight: 500;
+}
+
+/* Use case visual panels */
+.landing .usecase-viz {
+  flex: 1;
+  position: relative;
+  min-height: 140px;
+  margin: 20px 16px 16px;
+  border-radius: 8px;
+  background: var(--bg-code);
+  border: 1px solid var(--border);
+  overflow: hidden;
+}
+
+.landing .usecase-viz-inner {
+  position: absolute;
+  inset: 0;
+}
+
+/* Discovery: node graph */
+.landing .uc-node {
+  position: absolute;
+  font-size: 10px;
+  font-family: 'JetBrains Mono', monospace;
+  padding: 5px 12px;
+  border-radius: 6px;
+  white-space: nowrap;
+}
+
+.landing .uc-node-service {
+  background: var(--bg-surface);
+  border: 1px solid var(--border-hover);
+  color: var(--text-secondary);
+}
+
+.landing .uc-node-event {
+  background: var(--bg-elevated);
+  border: 1px solid var(--border);
+  color: var(--text-muted);
+}
+
+.landing .uc-lines {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+}
+
+/* Discovery hover: lines brighten, nodes shift */
+.landing .uc-node {
+  transition: transform 0.4s cubic-bezier(0.16, 1, 0.3, 1), border-color 0.3s;
+}
+.landing .uc-lines line {
+  transition: opacity 0.3s;
+}
+.landing .usecase-card:hover .uc-node-service { border-color: var(--cyan); }
+.landing .usecase-card:hover .usecase-discovery .uc-lines line { opacity: 0.6 !important; }
+
+/* Design: before/after blocks */
+.landing .usecase-design {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 16px;
+  padding: 16px;
+}
+
+.landing .uc-design-col {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  align-items: center;
+}
+
+.landing .uc-design-label {
+  font-size: 9px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-muted);
+  margin-bottom: 2px;
+}
+
+.landing .uc-design-label-new { color: var(--green); }
+
+.landing .uc-design-block {
+  width: 60px;
+  height: 20px;
+  border-radius: 4px;
+  background: var(--bg-elevated);
+  border: 1px solid var(--border);
+  transition: border-color 0.3s, opacity 0.3s;
+}
+
+.landing .uc-design-block-new {
+  border-color: var(--border-hover);
+}
+
+.landing .uc-design-block-added {
+  border: 1px dashed var(--green);
+  opacity: 0.5;
+  transition: opacity 0.3s;
+}
+
+.landing .uc-design-arrow {
+  color: var(--text-muted);
+  transition: transform 0.3s;
+}
+
+/* Design hover */
+.landing .usecase-card:hover .uc-design-arrow { transform: translateX(3px); }
+.landing .usecase-card:hover .uc-design-block-added { opacity: 1; }
+
+/* Impact: SVG radial dependency graph */
+.landing .usecase-impact {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 12px;
+}
+
+.landing .uc-impact-svg {
+  width: 100%;
+  height: 100%;
+}
+
+.landing .uc-impact-line {
+  stroke: #f87171;
+  stroke-width: 1;
+  stroke-dasharray: 4 3;
+  opacity: 0.25;
+  transition: opacity 0.3s;
+}
+
+.landing .uc-impact-center-bg {
+  fill: rgba(248, 113, 113, 0.08);
+  stroke: rgba(248, 113, 113, 0.2);
+  stroke-width: 1;
+  transition: fill 0.3s, stroke 0.3s;
+}
+
+.landing .uc-impact-center-text {
+  fill: #f87171;
+  font-size: 10px;
+  font-family: 'JetBrains Mono', monospace;
+}
+
+.landing .uc-impact-dep-bg {
+  fill: var(--bg-surface);
+  stroke: var(--border);
+  stroke-width: 1;
+  transition: stroke 0.3s;
+}
+
+.landing .uc-impact-dep-text {
+  fill: var(--text-muted);
+  font-size: 9px;
+  font-family: 'JetBrains Mono', monospace;
+  transition: fill 0.3s;
+}
+
+/* Impact hover */
+.landing .usecase-card:hover .uc-impact-line {
+  opacity: 0.5;
+}
+.landing .usecase-card:hover .uc-impact-center-bg {
+  fill: rgba(248, 113, 113, 0.15);
+  stroke: rgba(248, 113, 113, 0.4);
+}
+.landing .usecase-card:hover .uc-impact-dep-bg {
+  stroke: rgba(248, 113, 113, 0.2);
+}
+.landing .usecase-card:hover .uc-impact-dep-text {
+  fill: var(--text-secondary);
+}
+
+/* AI: terminal prompt */
+.landing .usecase-ai {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 16px;
+}
+
+.landing .uc-ai-prompt {
+  font-size: 11px;
+  font-family: 'JetBrains Mono', monospace;
+  color: var(--text-secondary);
+  padding: 8px 12px;
+  background: var(--bg-surface);
+  border-radius: 6px;
+  border: 1px solid var(--border);
+}
+
+.landing .uc-ai-caret {
+  color: var(--green);
+  margin-right: 4px;
+}
+
+.landing .uc-ai-response {
+  font-size: 11px;
+  font-family: 'JetBrains Mono', monospace;
+  color: var(--text-muted);
+  padding: 8px 12px;
+  background: var(--bg-elevated);
+  border-radius: 6px;
+  border: 1px solid var(--border);
+  transition: color 0.3s, border-color 0.3s;
+}
+
+/* AI hover: response brightens */
+.landing .usecase-card:hover .uc-ai-response {
+  color: var(--green);
+  border-color: rgba(52, 211, 153, 0.15);
+}
+
+/* --- Open Workspace Modal --- */
+@keyframes workspace-overlay-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes workspace-modal-in {
+  from { opacity: 0; transform: translateY(12px) scale(0.98); }
+  to { opacity: 1; transform: translateY(0) scale(1); }
+}
+
+.landing .workspace-modal-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 250;
+  background: rgba(3, 5, 9, 0.72);
+  backdrop-filter: blur(8px);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 16px;
+  animation: workspace-overlay-in 0.2s ease-out;
+}
+
+.landing .workspace-modal {
+  width: min(720px, 100%);
+  max-height: calc(100vh - 32px);
+  overflow-y: auto;
+  border-radius: 16px;
+  border: 1px solid var(--border-hover);
+  background: rgba(16, 20, 29, 0.98);
+  box-shadow:
+    0 0 0 1px rgba(255, 255, 255, 0.03),
+    0 24px 56px rgba(0, 0, 0, 0.55),
+    0 0 120px -40px rgba(99, 102, 241, 0.08);
+  padding: 24px;
+  animation: workspace-modal-in 0.25s ease-out;
+}
+
+.landing .workspace-modal-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: 12px;
+}
+
+.landing .workspace-modal-header h2 {
+  margin: 0;
+  font-size: 22px;
+  font-weight: 700;
+  letter-spacing: -0.025em;
+}
+
+.landing .workspace-modal-header p {
+  margin: 6px 0 0;
+  color: rgba(232, 234, 237, 0.7);
+  line-height: 1.45;
+  max-width: 560px;
+  font-size: 14px;
+}
+
+.landing .workspace-modal-close {
+  width: 32px;
+  height: 32px;
+  border-radius: 8px;
+  border: 1px solid var(--border);
+  background: transparent;
+  color: var(--text-secondary);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  transition: all 0.15s;
+  flex-shrink: 0;
+}
+
+.landing .workspace-modal-close:hover {
+  color: var(--text-primary);
+  border-color: var(--border-hover);
+  background: rgba(255, 255, 255, 0.04);
+}
+
+.landing .workspace-modal-close:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+/* Sections */
+.landing .workspace-modal-section {
+  margin-top: 20px;
+  padding-top: 20px;
+  border-top: 1px solid var(--border);
+}
+
+.landing .workspace-modal-section-header {
+  margin-bottom: 12px;
+}
+
+.landing .workspace-modal-section-header h3 {
+  margin: 0;
+  font-size: 14px;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  text-transform: uppercase;
+  color: rgba(232, 234, 237, 0.75);
+}
+
+.landing .workspace-modal-section-header p {
+  margin: 4px 0 0;
+  color: rgba(232, 234, 237, 0.55);
+  line-height: 1.4;
+  font-size: 13px;
+}
+
+/* Import grid */
+.landing .workspace-modal-grid {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 12px;
+}
+
+.landing .workspace-modal-grid-two {
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+/* Import cards */
+.landing .workspace-option-card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  border-radius: 12px;
+  border: 1px solid var(--border);
+  background: rgba(19, 24, 34, 0.7);
+  padding: 16px;
+  transition: all 0.2s;
+  overflow: hidden;
+}
+
+/* Colored top accent bar */
+.landing .workspace-option-card::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 2px;
+  opacity: 0.5;
+  transition: opacity 0.2s;
+}
+
+.landing .workspace-option-card--openapi::before {
+  background: var(--cyan);
+}
+
+.landing .workspace-option-card--asyncapi::before {
+  background: var(--green);
+}
+
+.landing .workspace-option-card:hover {
+  border-color: var(--border-hover);
+}
+
+.landing .workspace-option-card:hover::before {
+  opacity: 1;
+}
+
+.landing .workspace-option-card.is-dragging {
+  border-color: rgba(34, 211, 238, 0.55);
+  background: rgba(10, 34, 45, 0.45);
+  box-shadow: inset 0 0 0 1px rgba(34, 211, 238, 0.2);
+}
+
+.landing .workspace-option-card.is-dragging .workspace-option-card-drop-hint {
+  opacity: 1;
+  color: var(--cyan);
+}
+
+.landing .workspace-option-card--asyncapi.is-dragging {
+  border-color: rgba(52, 211, 153, 0.55);
+  background: rgba(10, 45, 30, 0.45);
+  box-shadow: inset 0 0 0 1px rgba(52, 211, 153, 0.2);
+}
+
+.landing .workspace-option-card--asyncapi.is-dragging .workspace-option-card-drop-hint {
+  color: var(--green);
+}
+
+/* Card icon */
+.landing .workspace-option-card-icon {
+  width: 36px;
+  height: 36px;
+  border-radius: 9px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: 12px;
+}
+
+.landing .workspace-option-card-icon--openapi {
+  background: rgba(34, 211, 238, 0.1);
+  color: var(--cyan);
+  border: 1px solid rgba(34, 211, 238, 0.15);
+}
+
+.landing .workspace-option-card-icon--asyncapi {
+  background: rgba(52, 211, 153, 0.1);
+  color: var(--green);
+  border: 1px solid rgba(52, 211, 153, 0.15);
+}
+
+.landing .workspace-option-card-body h4 {
+  margin: 0;
+  font-size: 15px;
+  font-weight: 650;
+  letter-spacing: -0.01em;
+}
+
+.landing .workspace-option-card-body p {
+  margin: 4px 0 0;
+  color: rgba(232, 234, 237, 0.6);
+  line-height: 1.4;
+  font-size: 13px;
+}
+
+/* Drop hint */
+.landing .workspace-option-card-drop-hint {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-top: 12px;
+  padding: 10px;
+  border-radius: 8px;
+  border: 1px dashed rgba(255, 255, 255, 0.12);
+  background: rgba(255, 255, 255, 0.015);
+  color: rgba(232, 234, 237, 0.5);
+  font-size: 12px;
+  text-align: center;
+  justify-content: center;
+  transition: all 0.2s;
+}
+
+.landing .workspace-option-card:hover .workspace-option-card-drop-hint {
+  border-color: rgba(255, 255, 255, 0.12);
+  color: var(--text-secondary);
+}
+
+/* Card footer */
+.landing .workspace-option-card-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-top: 12px;
+  gap: 8px;
+}
+
+.landing .workspace-option-card-meta {
+  font-size: 11px;
+  color: rgba(232, 234, 237, 0.45);
+}
+
+.landing .workspace-option-card-cta {
+  border: 1px solid var(--border-hover);
+  border-radius: 7px;
+  background: rgba(232, 234, 237, 0.94);
+  color: #090b10;
+  padding: 7px 14px;
+  font-size: 12px;
+  font-weight: 650;
+  cursor: pointer;
+  transition: all 0.15s;
+  white-space: nowrap;
+}
+
+.landing .workspace-option-card-cta:hover {
+  background: rgba(255, 255, 255, 1);
+}
+
+.landing .workspace-option-card-cta:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+/* Secondary section (explore / connect) */
+.landing .workspace-modal-section--secondary {
+  border-top-style: dashed;
+}
+
+.landing .workspace-secondary-options {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.landing .workspace-secondary-btn {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  width: 100%;
+  padding: 12px 14px;
+  border-radius: 10px;
+  border: 1px solid var(--border);
+  background: transparent;
+  color: var(--text-primary);
+  font-family: inherit;
+  text-align: left;
+  cursor: pointer;
+  transition: all 0.15s;
+}
+
+.landing .workspace-secondary-btn > svg {
+  flex-shrink: 0;
+  color: var(--text-muted);
+  transition: color 0.15s;
+}
+
+.landing .workspace-secondary-btn:hover {
+  border-color: var(--border-hover);
+  background: rgba(255, 255, 255, 0.02);
+}
+
+.landing .workspace-secondary-btn:hover > svg {
+  color: var(--cyan);
+}
+
+.landing .workspace-secondary-btn:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.landing .workspace-secondary-btn-label {
+  display: block;
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.landing .workspace-secondary-btn-desc {
+  display: block;
+  font-size: 12px;
+  color: rgba(232, 234, 237, 0.5);
+  margin-top: 1px;
+}
+
+.landing .workspace-secondary-btn--disabled {
+  opacity: 0.55;
+  cursor: default;
+}
+
+.landing .workspace-secondary-btn--disabled:hover {
+  border-color: var(--border);
+  background: transparent;
+}
+
+.landing .workspace-secondary-btn--disabled:hover > svg {
+  color: var(--text-muted);
+}
+
+.landing .workspace-secondary-btn-badge {
+  margin-left: auto;
+  font-size: 10px;
+  font-weight: 650;
+  color: var(--text-muted);
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  padding: 2px 8px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  flex-shrink: 0;
+}
+
+/* Error */
+.landing .workspace-modal-error {
+  margin: 12px 0 0;
+  border: 1px solid rgba(248, 113, 113, 0.3);
+  background: rgba(127, 29, 29, 0.18);
+  color: #fecaca;
+  border-radius: 8px;
+  padding: 10px 12px;
+  font-size: 13px;
+}
+
+.landing .workspace-file-input {
+  display: none;
+}
+
+.landing .workspace-modal-privacy {
+  margin: 16px 0 0;
+  text-align: center;
+  font-size: 11px;
+  color: rgba(232, 234, 237, 0.4);
+  letter-spacing: 0.01em;
+}
+
+/* --- CTA --- */
+.landing .cta-hero {
+  padding: 120px 40px;
+  text-align: center;
+  position: relative;
+}
+
+.landing .cta-hero::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background:
+    linear-gradient(rgba(255,255,255,0.04) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(255,255,255,0.04) 1px, transparent 1px);
+  background-size: 40px 40px;
+  mask-image: radial-gradient(ellipse 60% 50% at 50% 50%, black 20%, transparent 100%);
+  -webkit-mask-image: radial-gradient(ellipse 60% 50% at 50% 50%, black 20%, transparent 100%);
+  pointer-events: none;
+}
+
+.landing .cta-hero-title {
+  font-size: 40px;
+  font-weight: 700;
+  color: var(--text-primary);
+  letter-spacing: -0.03em;
+  line-height: 1.15;
+  margin: 0 auto 16px;
+  max-width: 800px;
+}
+
+.landing .cta-hero-desc {
+  font-size: 17px;
+  color: var(--text-secondary);
+  line-height: 1.6;
+  margin: 0 auto 36px;
+  max-width: 680px;
+}
+
+.landing .cta-hero-actions {
+  display: flex;
+  gap: 14px;
+  justify-content: center;
+}
+
+.landing .btn-lg {
+  padding: 14px 32px;
+  font-size: 15px;
+}
+
+.landing .cta-hero-note {
+  margin-top: 20px;
+  font-size: 13px;
+  color: var(--text-muted);
+}
+
+/* --- Logos --- */
+.landing .logos-section {
+  padding: 0 40px 80px;
+  text-align: center;
+}
+
+.landing .logos-label {
+  font-size: 12px;
+  color: var(--text-muted);
+  margin-bottom: 20px;
+}
+
+.landing .logos-row {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  gap: 40px;
+  flex-wrap: wrap;
+  opacity: 0.4;
+}
+
+.landing .logos-row span {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-secondary);
+  letter-spacing: 0.02em;
+}
+
+/* --- Footer --- */
+.landing footer {
+  padding: 32px 40px;
+  border-top: 1px solid var(--border);
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  max-width: 1060px;
+  margin: 0 auto;
+}
+
+.landing .footer-brand {
+  font-size: 13px;
+  color: var(--text-muted);
+}
+
+.landing .footer-brand a {
+  color: var(--text-secondary);
+  text-decoration: none;
+}
+
+.landing .footer-links { display: flex; gap: 20px; }
+
+.landing .footer-links a {
+  color: var(--text-muted);
+  text-decoration: none;
+  font-size: 12px;
+  transition: color 0.15s;
+}
+
+.landing .footer-links a:hover { color: var(--text-secondary); }
+
+.landing .divider {
+  width: 100%;
+  max-width: 1060px;
+  margin: 0 auto;
+  height: 1px;
+  background: var(--border);
+}
+
+/* --- Scroll Animations --- */
+.landing .reveal {
+  opacity: 0;
+  transform: translateY(24px);
+  transition: opacity 0.7s cubic-bezier(0.16, 1, 0.3, 1), transform 0.7s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.landing .reveal.visible {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+.landing .reveal-left {
+  opacity: 0;
+  transform: translateX(-24px);
+  transition: opacity 0.7s cubic-bezier(0.16, 1, 0.3, 1), transform 0.7s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.landing .reveal-left.visible {
+  opacity: 1;
+  transform: translateX(0);
+}
+
+.landing .reveal-right {
+  opacity: 0;
+  transform: translateX(24px);
+  transition: opacity 0.7s cubic-bezier(0.16, 1, 0.3, 1), transform 0.7s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.landing .reveal-right.visible {
+  opacity: 1;
+  transform: translateX(0);
+}
+
+.landing .reveal-scale {
+  opacity: 0;
+  transform: scale(0.96);
+  transition: opacity 0.7s cubic-bezier(0.16, 1, 0.3, 1), transform 0.7s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.landing .reveal-scale.visible {
+  opacity: 1;
+  transform: scale(1);
+}
+
+/* Stagger children */
+.landing .stagger-children > * {
+  opacity: 0;
+  transform: translateY(16px);
+  transition: opacity 0.5s cubic-bezier(0.16, 1, 0.3, 1), transform 0.5s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.landing .stagger-children.visible > *:nth-child(1) { transition-delay: 0ms; opacity: 1; transform: translateY(0); }
+.landing .stagger-children.visible > *:nth-child(2) { transition-delay: 80ms; opacity: 1; transform: translateY(0); }
+.landing .stagger-children.visible > *:nth-child(3) { transition-delay: 160ms; opacity: 1; transform: translateY(0); }
+.landing .stagger-children.visible > *:nth-child(4) { transition-delay: 240ms; opacity: 1; transform: translateY(0); }
+.landing .stagger-children.visible > *:nth-child(5) { transition-delay: 320ms; opacity: 1; transform: translateY(0); }
+.landing .stagger-children.visible > *:nth-child(6) { transition-delay: 400ms; opacity: 1; transform: translateY(0); }
+.landing .stagger-children.visible > *:nth-child(7) { transition-delay: 480ms; opacity: 1; transform: translateY(0); }
+.landing .stagger-children.visible > *:nth-child(8) { transition-delay: 560ms; opacity: 1; transform: translateY(0); }
+
+/* Comparison slide */
+.landing .comp-slide-left {
+  opacity: 0;
+  transform: translateX(-20px);
+  transition: opacity 0.6s cubic-bezier(0.16, 1, 0.3, 1), transform 0.6s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.landing .comp-slide-left.visible {
+  opacity: 0.7;
+  transform: translateX(0);
+}
+
+.landing .comp-slide-right {
+  opacity: 0;
+  transform: translateX(20px);
+  transition: opacity 0.6s cubic-bezier(0.16, 1, 0.3, 1) 0.2s, transform 0.6s cubic-bezier(0.16, 1, 0.3, 1) 0.2s;
+}
+
+.landing .comp-slide-right.visible {
+  opacity: 1;
+  transform: translateX(0);
+}
+
+
+/* Divider grow */
+.landing .divider {
+  transform: scaleX(0);
+  transition: transform 0.8s cubic-bezier(0.16, 1, 0.3, 1);
+  transform-origin: center;
+}
+
+.landing .divider.visible {
+  transform: scaleX(1);
+}
+
+/* --- Responsive --- */
+@media (max-width: 768px) {
+  .landing .workspace-modal-overlay {
+    padding: 8px;
+    align-items: flex-start;
+  }
+
+  .landing .workspace-modal {
+    margin-top: 56px;
+    max-height: calc(100vh - 64px);
+    padding: 16px;
+    border-radius: 14px;
+  }
+
+  .landing .workspace-modal-header h2 {
+    font-size: 19px;
+  }
+
+  .landing .workspace-modal-header p {
+    font-size: 13px;
+  }
+
+  .landing .workspace-modal-grid-two {
+    grid-template-columns: 1fr;
+  }
+
+  .landing .workspace-option-card-drop-hint {
+    display: none;
+  }
+
+  .landing .workspace-option-card-footer {
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  .landing .workspace-option-card-cta {
+    width: 100%;
+    text-align: center;
+  }
+
+  /* Nav */
+  .landing nav { padding: 0 16px; }
+  .landing .nav-links { display: none; }
+
+  /* Hero */
+  .landing .hero { padding: 100px 16px 32px; }
+  .landing .hero h1 { font-size: 32px; max-width: 100%; }
+  .landing .hero-sub { font-size: 15px; max-width: 100%; }
+  .landing .hero-actions { flex-direction: column; align-items: center; gap: 10px; }
+  .landing .hero-actions .btn-primary,
+  .landing .hero-actions .btn-ghost { width: 100%; max-width: 280px; justify-content: center; }
+
+  /* Hero preview (editor + visualizer) */
+  .landing .hero-preview-wrapper { width: calc(100% - 16px); margin-top: 32px; gap: 16px; display: flex; flex-direction: column; }
+  .landing .editor-window { border-radius: 8px; }
+  .landing .editor-titlebar { padding: 8px 12px; gap: 8px; overflow-x: auto; }
+  .landing .editor-dots { display: none; }
+  .landing .editor-tabs { margin-left: 0; gap: 0; }
+  .landing .editor-tab { font-size: 11px; padding: 4px 8px; white-space: nowrap; }
+  .landing .hero-editor-body { height: 300px; }
+  .landing .hero-editor-code { width: 100% !important; }
+  .landing .hero-editor-viz-desktop { display: none; }
+  .landing .hero-resize-handle { display: none; }
+  .landing .hero-viz-mobile { display: block; }
+
+  /* Hero pillars */
+  .landing .hero-pillars { grid-template-columns: 1fr; gap: 12px; width: calc(100% - 16px); margin-top: 24px; }
+  .landing .hero-pillar { padding: 16px; }
+
+  /* Sections */
+  .landing .section { padding: 60px 16px; }
+  .landing .section-title { font-size: 24px; }
+  .landing .section-desc { font-size: 14px; }
+
+  /* Bento grid */
+  .landing .bento-grid { grid-template-columns: 1fr; }
+  .landing .bento-col-2,
+  .landing .bento-col-3 { grid-column: span 1; }
+  .landing .bento-before-after { grid-template-columns: 1fr; gap: 12px; }
+  .landing .bento-ba-arrow { transform: rotate(90deg); }
+  .landing .bento-statement { font-size: 16px; }
+
+  /* Steps */
+  .landing .step-head { gap: 10px; }
+  .landing .step-num { width: 28px; height: 28px; font-size: 12px; }
+  .landing .step h3 { font-size: 15px; }
+  .landing .step p { font-size: 13px; }
+  .landing .code-block { font-size: 11px; padding: 12px 14px; overflow-x: auto; }
+  .landing .step-viz-container { height: 280px; }
+
+  /* Sources grid */
+  .landing .sources-grid { grid-template-columns: repeat(2, 1fr); }
+
+  /* Use cases grid */
+  .landing .usecases-grid { grid-template-columns: 1fr; max-width: 100%; }
+
+  /* CTA hero */
+  .landing .cta-hero { padding: 80px 16px; }
+  .landing .cta-hero-title { font-size: 28px; max-width: 100%; }
+  .landing .cta-hero-desc { font-size: 15px; max-width: 100%; }
+  .landing .cta-hero-actions { flex-direction: column; align-items: center; gap: 10px; }
+  .landing .cta-hero-actions .btn-lg { width: 100%; max-width: 280px; justify-content: center; }
+  .landing .cta-hero-note { font-size: 11px; }
+
+  /* Footer */
+  .landing footer { flex-direction: column; gap: 16px; text-align: center; padding: 24px 16px; }
+  .landing .footer-links { justify-content: center; flex-wrap: wrap; gap: 14px; }
+
+  /* Divider */
+  .landing .divider { margin: 0 16px; width: calc(100% - 32px); }
+}
diff --git a/packages/playground/src/pages/Landing.tsx b/packages/playground/src/pages/Landing.tsx
new file mode 100644
index 000000000..17eb73d6b
--- /dev/null
+++ b/packages/playground/src/pages/Landing.tsx
@@ -0,0 +1,1827 @@
+import { useNavigate } from "react-router-dom";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { HeroPreview, StepVisualizer } from "../components/HeroPreview";
+import { X, Upload, Play, Link2 } from "lucide-react";
+import { createWorkspace } from "../stores/workspace";
+import type { SpecKind } from "../stores/workspace";
+import { track } from "../utils/analytics";
+import "./Landing.css";
+
+/** Official OpenAPI Initiative mark (simplified chain-link icon) */
+function OpenApiIcon({ size = 20 }: { size?: number }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="38 123 125 120"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <g>
+        <path
+          fill="#93D500"
+          d="M74.909,189.069h-0.113l-29.444,0c0.005,0.144,0.009,0.289,0.017,0.433c0.012,0.278,0.032,0.555,0.049,0.833c0.008,0.119,0.013,0.238,0.022,0.356c0.023,0.322,0.051,0.642,0.08,0.962c0.007,0.073,0.013,0.145,0.02,0.215c0.034,0.356,0.073,0.712,0.115,1.065c0.002,0.035,0.006,0.069,0.011,0.103c0.046,0.382,0.095,0.764,0.151,1.144c0,0.004,0.001,0.01,0.003,0.014c0.339,2.356,0.848,4.69,1.527,6.984c0.003,0.01,0.007,0.019,0.009,0.029c0.106,0.361,0.218,0.72,0.333,1.077c0.007,0.021,0.014,0.042,0.02,0.063s0.013,0.042,0.02,0.063c0.105,0.323,0.215,0.645,0.325,0.968c0.029,0.081,0.056,0.163,0.086,0.244c0.099,0.279,0.2,0.558,0.304,0.837c0.048,0.126,0.096,0.251,0.143,0.378c0.09,0.231,0.179,0.46,0.27,0.691c0.069,0.173,0.141,0.346,0.213,0.519c0.074,0.18,0.15,0.359,0.226,0.54c0.094,0.22,0.192,0.439,0.289,0.658c0.058,0.131,0.117,0.261,0.175,0.391c0.12,0.263,0.244,0.526,0.368,0.787c0.041,0.084,0.08,0.168,0.122,0.252c0.145,0.301,0.293,0.599,0.443,0.895c0.025,0.046,0.047,0.091,0.07,0.137c0.169,0.328,0.341,0.656,0.518,0.981c0.008,0.014,0.016,0.028,0.023,0.044c0.037,0.068,0.078,0.133,0.115,0.2l25.243-15.207l0.093-0.056C75.759,193.57,75.139,191.338,74.909,189.069z"
+        />
+        <path
+          fill="#6BA43A"
+          d="M80.005,200.564c-0.225-0.25-0.439-0.506-0.649-0.765c-0.186-0.23-0.366-0.462-0.54-0.697c-0.199-0.27-0.394-0.541-0.578-0.818c-0.186-0.278-0.368-0.558-0.54-0.843l-25.275,15.226c0.388,0.645,0.793,1.273,1.206,1.894c0.014,0.021,0.027,0.044,0.041,0.065c0.005,0.008,0.01,0.015,0.015,0.023c0.014,0.02,0.026,0.042,0.04,0.063c0.001,0.002,0.003,0.004,0.004,0.006c0.033,0.05,0.067,0.098,0.101,0.148c0.002,0.003,0.004,0.006,0.006,0.009c0.001,0.001,0.002,0.003,0.003,0.004c0.439,0.649,0.89,1.288,1.355,1.91c0.01,0.013,0.021,0.027,0.031,0.04c0.01,0.013,0.02,0.026,0.03,0.039c0.202,0.268,0.405,0.535,0.614,0.8c0.027,0.035,0.054,0.069,0.083,0.103c0.214,0.274,0.432,0.544,0.654,0.812c0.052,0.063,0.106,0.127,0.158,0.191c0.2,0.239,0.4,0.477,0.604,0.713c0.087,0.101,0.178,0.202,0.266,0.302c0.174,0.198,0.346,0.395,0.524,0.59c0.097,0.107,0.198,0.215,0.297,0.322c0.045,0.049,0.089,0.097,0.135,0.146c0.13,0.14,0.259,0.28,0.39,0.419c0.052,0.055,0.107,0.109,0.16,0.164c0.23,0.24,0.462,0.48,0.699,0.716l20.85-20.85C80.45,201.057,80.226,200.811,80.005,200.564z"
+        />
+        <path
+          fill="#4D5A31"
+          d="M82.173,202.638l-0.071,0.071l-20.819,20.82c0.107,0.1,0.213,0.201,0.323,0.298c0.194,0.176,0.392,0.351,0.589,0.523c0.102,0.091,0.202,0.181,0.304,0.269c0.236,0.204,0.474,0.403,0.711,0.602c0.065,0.054,0.128,0.107,0.192,0.16c0.267,0.221,0.539,0.438,0.812,0.654c0.035,0.027,0.07,0.055,0.105,0.083c0.295,0.232,0.593,0.458,0.894,0.686c0.013,0.008,0.024,0.016,0.034,0.025c1.254,0.937,2.554,1.815,3.895,2.633c0.046,0.029,0.092,0.056,0.139,0.085c0.255,0.153,0.51,0.304,0.767,0.453c0.157,0.09,0.314,0.179,0.471,0.268c0.148,0.086,0.296,0.168,0.446,0.251c0.27,0.148,0.542,0.295,0.814,0.439c0.037,0.02,0.075,0.04,0.113,0.06c0.757,0.396,1.527,0.764,2.303,1.118l0.739-1.794l10.471-25.429l0.039-0.094C84.3,204.207,83.204,203.482,82.173,202.638z"
+        />
+        <path
+          fill="#93D500"
+          d="M119.99,228.696l-0.516-0.856l-14.19-23.555c-0.287,0.173-0.581,0.329-0.874,0.487c-0.296,0.159-0.594,0.308-0.896,0.451c-2.726,1.293-5.677,1.953-8.632,1.953c-1.936,0-3.871-0.28-5.742-0.838c-0.319-0.095-0.63-0.22-0.945-0.332c-0.315-0.111-0.634-0.207-0.944-0.335l-10.464,25.412l-0.41,0.996l-0.351,0.853c0.027,0.011,0.055,0.02,0.082,0.031c0.029,0.012,0.057,0.021,0.086,0.033c0.007,0.003,0.014,0.005,0.02,0.008c0.247,0.101,0.496,0.188,0.744,0.285c0.311,0.121,0.622,0.244,0.934,0.358c0.159,0.058,0.317,0.126,0.476,0.182c3.278,1.158,6.67,1.968,10.119,2.422c0.135,0.016,0.269,0.035,0.404,0.054c0.141,0.016,0.283,0.03,0.424,0.046c0.266,0.03,0.531,0.061,0.798,0.087c0.066,0.005,0.132,0.011,0.198,0.017c0.327,0.031,0.654,0.059,0.979,0.082c0.111,0.008,0.223,0.013,0.333,0.021c0.287,0.019,0.572,0.037,0.858,0.05c0.175,0.01,0.35,0.015,0.526,0.021c0.227,0.008,0.453,0.017,0.682,0.024c0.327,0.008,0.657,0.011,0.986,0.012c0.078,0,0.155,0.002,0.232,0.003c2.755,0,5.509-0.229,8.233-0.686c0.046-0.007,0.091-0.015,0.138-0.021c0.288-0.05,0.576-0.104,0.864-0.157c0.164-0.032,0.329-0.063,0.491-0.095c0.168-0.035,0.337-0.07,0.505-0.106c0.281-0.059,0.561-0.12,0.842-0.185c0.05-0.011,0.101-0.021,0.152-0.035c4.141-0.965,8.14-2.459,11.897-4.436c0.246-0.13,0.486-0.278,0.731-0.411c0.292-0.16,0.582-0.325,0.872-0.491c0.201-0.115,0.404-0.221,0.603-0.34L119.99,228.696z"
+        />
+        <path
+          fill="#6BA43A"
+          d="M93.914,137.485c-0.333,0.007-0.667,0.008-1,0.021c-2.086,0.084-4.168,0.297-6.233,0.643c-0.045,0.008-0.09,0.015-0.136,0.023c-0.29,0.05-0.577,0.103-0.865,0.157c-0.163,0.031-0.327,0.061-0.49,0.094c-0.17,0.034-0.339,0.069-0.508,0.106c-0.28,0.058-0.56,0.119-0.84,0.184c-0.051,0.011-0.101,0.023-0.153,0.034c-4.141,0.966-8.142,2.461-11.898,4.438c-0.245,0.13-0.484,0.277-0.728,0.411c-0.292,0.16-0.582,0.325-0.872,0.491c-0.215,0.124-0.434,0.238-0.648,0.366c-0.002,0.001-0.005,0.003-0.007,0.004c-0.015,0.009-0.03,0.017-0.045,0.026c-0.056,0.034-0.114,0.062-0.17,0.096l0.516,0.857l14.705,24.412c0.287-0.173,0.581-0.33,0.874-0.487c0.295-0.159,0.594-0.308,0.895-0.451c2.1-1,4.332-1.62,6.601-1.85c0.333-0.034,0.666-0.062,1-0.079c0.333-0.017,0.666-0.034,1-0.034l0.001-29.487C94.58,137.465,94.247,137.479,93.914,137.485z"
+        />
+        <path
+          fill="#4D5A31"
+          d="M120.681,144.675c-0.04-0.025-0.082-0.049-0.122-0.073c-0.259-0.159-0.521-0.312-0.783-0.465c-0.152-0.088-0.304-0.173-0.457-0.26c-0.154-0.086-0.306-0.172-0.461-0.256c-0.266-0.146-0.533-0.29-0.801-0.432c-0.042-0.021-0.083-0.044-0.126-0.066c-1.729-0.904-3.505-1.7-5.318-2.391c-0.046-0.019-0.094-0.037-0.141-0.054c-0.395-0.148-0.791-0.295-1.19-0.433c-3.221-1.125-6.552-1.914-9.936-2.358c-0.138-0.019-0.277-0.038-0.415-0.056c-0.139-0.017-0.277-0.031-0.415-0.046c-0.267-0.031-0.533-0.061-0.801-0.087c-0.074-0.007-0.149-0.012-0.224-0.02c-0.317-0.029-0.636-0.057-0.953-0.08c-0.123-0.009-0.248-0.016-0.371-0.023c-0.272-0.018-0.547-0.037-0.819-0.049c-0.146-0.008-0.29-0.012-0.434-0.017l-0.001,29.444v0.115c1.517,0.157,3.02,0.48,4.478,0.975l21.754-21.754C122.338,145.729,121.521,145.185,120.681,144.675z"
+        />
+        <path
+          fill="#4D5A31"
+          d="M144.458,184.631c-0.014-0.265-0.03-0.529-0.048-0.795c-0.008-0.132-0.015-0.263-0.026-0.397c-0.022-0.311-0.048-0.623-0.077-0.934c-0.006-0.081-0.014-0.161-0.021-0.242c-0.034-0.348-0.071-0.696-0.111-1.043c-0.004-0.028-0.007-0.056-0.01-0.084c-0.002-0.013-0.003-0.027-0.005-0.04c-0.046-0.375-0.096-0.75-0.149-1.124c-0.001-0.011-0.002-0.025-0.005-0.035c-0.339-2.351-0.847-4.681-1.524-6.972c-0.005-0.016-0.009-0.03-0.014-0.044c-0.107-0.356-0.216-0.71-0.328-1.063c-0.015-0.046-0.031-0.093-0.045-0.14c-0.105-0.319-0.211-0.636-0.321-0.954c-0.031-0.085-0.061-0.171-0.091-0.258c-0.097-0.275-0.197-0.549-0.299-0.823c-0.049-0.131-0.099-0.261-0.15-0.391c-0.086-0.227-0.175-0.454-0.265-0.678c-0.072-0.18-0.144-0.357-0.218-0.534c-0.072-0.176-0.146-0.35-0.22-0.526c-0.097-0.224-0.195-0.448-0.294-0.671c-0.056-0.125-0.112-0.252-0.17-0.378c-0.122-0.266-0.247-0.532-0.373-0.797c-0.039-0.08-0.077-0.162-0.116-0.242c-0.147-0.303-0.296-0.606-0.448-0.906c-0.022-0.041-0.043-0.083-0.065-0.125c-0.17-0.331-0.344-0.663-0.521-0.99c-0.007-0.011-0.012-0.024-0.019-0.035c-0.859-1.58-1.802-3.108-2.822-4.578l-21.761,21.762c0.495,1.459,0.817,2.961,0.974,4.477h0.116h29.444C144.469,184.922,144.465,184.776,144.458,184.631z"
+        />
+        <path
+          fill="#6BA43A"
+          d="M115.03,187.069c0,0.334-0.031,0.666-0.048,1c-0.016,0.334-0.022,0.668-0.055,1c-0.381,3.84-1.863,7.59-4.446,10.74c-0.21,0.256-0.447,0.496-0.672,0.743c-0.224,0.247-0.432,0.504-0.671,0.742l20.851,20.85c0.237-0.237,0.46-0.482,0.691-0.723c0.231-0.241,0.466-0.479,0.691-0.723c1.543-1.671,2.953-3.419,4.224-5.236c0.051-0.072,0.099-0.143,0.148-0.214c0.155-0.223,0.306-0.448,0.458-0.673c0.133-0.201,0.266-0.402,0.395-0.605c0.064-0.097,0.128-0.198,0.19-0.295c4.782-7.509,7.341-16.021,7.685-24.607c0.013-0.333,0.02-0.667,0.027-1c0.007-0.333,0.017-0.666,0.017-1H115.03z"
+        />
+        <path
+          fill="#4D5A31"
+          d="M59.838,151.994c-0.237,0.237-0.461,0.482-0.692,0.722c-0.231,0.24-0.466,0.479-0.692,0.723c-1.538,1.665-2.944,3.409-4.212,5.22c-0.061,0.085-0.122,0.174-0.182,0.261c-0.143,0.208-0.284,0.416-0.423,0.625c-0.145,0.217-0.289,0.437-0.429,0.656c-0.053,0.08-0.105,0.161-0.156,0.241c-4.789,7.513-7.355,16.034-7.7,24.627c-0.013,0.333-0.02,0.667-0.027,1c-0.007,0.333-0.017,0.667-0.017,1l29.488,0c0-0.334,0.031-0.666,0.048-1c0.017-0.334,0.022-0.668,0.055-1c0.381-3.84,1.863-7.589,4.447-10.739c0.21-0.256,0.447-0.496,0.672-0.743c0.224-0.247,0.432-0.504,0.671-0.742L59.838,151.994z"
+        />
+        <path
+          fill="#4D5A31"
+          d="M107.642,202.627c-0.229,0.185-0.461,0.366-0.697,0.54l0.052,0.087l15.202,25.235c0.704-0.46,1.4-0.934,2.08-1.432c1.471-1.085,2.895-2.261,4.267-3.527l-20.821-20.821L107.642,202.627z"
+        />
+        <path
+          fill="#82B536"
+          d="M82.185,171.512c0.23-0.186,0.462-0.366,0.697-0.54l-0.052-0.087l-15.201-25.235c-0.706,0.461-1.404,0.936-2.085,1.436c-1.47,1.082-2.893,2.257-4.262,3.522l20.821,20.821L82.185,171.512z"
+        />
+      </g>
+      <path
+        fill="currentColor"
+        d="M153.276,128.706c-5.395-5.395-14.142-5.395-19.536,0c-4.304,4.303-5.164,10.736-2.601,15.902L101.048,174.7c-5.166-2.562-11.599-1.703-15.903,2.6c-5.395,5.395-5.394,14.142,0,19.537c5.396,5.395,14.143,5.393,19.538-0.001c4.303-4.303,5.162-10.736,2.599-15.903l30.091-30.091c5.167,2.562,11.599,1.703,15.902-2.601C158.67,142.849,158.67,134.101,153.276,128.706z"
+      />
+    </svg>
+  );
+}
+
+/** Official AsyncAPI mark (rounded rect with chevron arrows) */
+function AsyncApiIcon({ size = 20 }: { size?: number }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="12 12 137.7 137.7"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path
+        fill="currentColor"
+        d="M117.12,12H44.53A32.58,32.58,0,0,0,12,44.53v72.59A32.58,32.58,0,0,0,44.53,149.7h72.59a32.58,32.58,0,0,0,32.58-32.58V44.53A32.58,32.58,0,0,0,117.12,12Zm-4.84,88.28c0,13.26-14.13,24-31.49,24s-31.48-10.79-31.48-24V100h7v.27c0,9.42,11,17.07,24.5,17.07s24.51-7.65,24.51-17.07V100h7ZM88.66,89.68l-4.1,5.65-.22-.16-32-23.24,4.1-5.65.22.16ZM73,71.93l4.1-5.65.22.16,32,23.24-4.1,5.65-.22-.16Zm39.31-10.25h-7v-.26c0-9.42-11-17.08-24.51-17.08S56.35,52,56.35,61.42v.26h-7v-.26c0-13.27,14.12-24.06,31.48-24.06s31.48,10.79,31.48,24.06Z"
+      />
+    </svg>
+  );
+}
+
+const SPEC_FILE_EXTENSION_RE = /\.(json|ya?ml)$/i;
+
+function generateWorkspaceId(): string {
+  return crypto.randomUUID().replace(/-/g, "").slice(0, 8);
+}
+const SAMPLE_EVENT_SYSTEM_INDEX = 8;
+
+function readFileAsText(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () =>
+      resolve(typeof reader.result === "string" ? reader.result : "");
+    reader.onerror = () =>
+      reject(reader.error ?? new Error(`Unable to read ${file.name}`));
+    reader.readAsText(file);
+  });
+}
+
+function toUniqueFileName(fileName: string, existing: Set<string>): string {
+  const trimmed = fileName.trim() || "spec.yml";
+  const dotIndex = trimmed.lastIndexOf(".");
+  const base = dotIndex > 0 ? trimmed.slice(0, dotIndex) : trimmed;
+  const ext = dotIndex > 0 ? trimmed.slice(dotIndex) : "";
+  let candidate = trimmed;
+  let sequence = 2;
+
+  while (existing.has(candidate.toLowerCase())) {
+    candidate = `${base}-${sequence}${ext}`;
+    sequence += 1;
+  }
+
+  existing.add(candidate.toLowerCase());
+  return candidate;
+}
+
+function toPascalIdentifierSeed(rawValue: string): string {
+  return rawValue
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+function extractOpenApiTitle(source: string): string | null {
+  try {
+    const parsed = JSON.parse(source);
+    const title = parsed?.info?.title;
+    if (typeof title === "string" && title.trim().length > 0) {
+      return title.trim();
+    }
+  } catch {}
+
+  const infoBlockMatch = source.match(
+    /(^|\n)([ \t]*)info\s*:\s*(?:\n|\r\n)((?:\2[ \t]+.*(?:\n|\r\n)?)+)/,
+  );
+  const infoBody = infoBlockMatch?.[3];
+  if (!infoBody) return null;
+
+  const titleLineMatch = infoBody.match(/^[ \t]*title\s*:\s*(.+?)\s*$/m);
+  if (!titleLineMatch?.[1]) return null;
+
+  const cleanedTitle = titleLineMatch[1]
+    .replace(/\s+#.*$/, "")
+    .replace(/^["']|["']$/g, "")
+    .trim();
+
+  return cleanedTitle.length > 0 ? cleanedTitle : null;
+}
+
+function toServiceIdentifier(
+  fileName: string,
+  kind: SpecKind,
+  existing: Set<string>,
+  preferredName?: string | null,
+): string {
+  const base = fileName.replace(/\.[^./\\]+$/, "");
+  const raw =
+    toPascalIdentifierSeed(preferredName?.trim() || "") ||
+    toPascalIdentifierSeed(base);
+
+  let candidate = raw || (kind === "openapi" ? "OpenApi" : "AsyncApi");
+
+  if (/^\d/.test(candidate)) {
+    candidate = `Spec${candidate}`;
+  }
+
+  let unique = candidate;
+  let sequence = 2;
+  while (existing.has(unique)) {
+    unique = `${candidate}${sequence}`;
+    sequence += 1;
+  }
+
+  existing.add(unique);
+  return unique;
+}
+
+function buildMainEcFile(
+  kind: SpecKind,
+  imports: string[],
+  serviceNames: string[],
+  importedSpecFiles: string[],
+): string {
+  const workspaceName =
+    kind === "openapi" ? "REST Service Workspace" : "Event Flow Workspace";
+  const visualizerEntries =
+    serviceNames.length > 0
+      ? serviceNames.map((service) => `  service ${service}`)
+      : ["  // Add services here"];
+  return [
+    ...imports,
+    "",
+    "visualizer main {",
+    `  name "${workspaceName}"`,
+    ...visualizerEntries,
+    "}",
+    "",
+  ].join("\n");
+}
+
+export default function Landing() {
+  const navigate = useNavigate();
+  const [isWorkspaceModalOpen, setIsWorkspaceModalOpen] = useState(false);
+  const [activeDropKind, setActiveDropKind] = useState<SpecKind | null>(null);
+  const [isImportingSpecs, setIsImportingSpecs] = useState(false);
+  const [importingSpecKind, setImportingSpecKind] = useState<SpecKind | null>(
+    null,
+  );
+  const [importError, setImportError] = useState<string | null>(null);
+  const openApiInputRef = useRef<HTMLInputElement>(null);
+  const asyncApiInputRef = useRef<HTMLInputElement>(null);
+
+  // Force dark theme for the landing page so visualizer + editor render dark
+  useEffect(() => {
+    document.documentElement.setAttribute("data-theme", "dark");
+    return () => {
+      document.documentElement.removeAttribute("data-theme");
+    };
+  }, []);
+
+  useEffect(() => {
+    // Scroll reveal observer
+    const observerOptions: IntersectionObserverInit = {
+      root: null,
+      rootMargin: "0px 0px -60px 0px",
+      threshold: 0.1,
+    };
+
+    const observer = new IntersectionObserver((entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          entry.target.classList.add("visible");
+          observer.unobserve(entry.target);
+        }
+      });
+    }, observerOptions);
+
+    const selectors = [
+      ".reveal",
+      ".reveal-left",
+      ".reveal-right",
+      ".reveal-scale",
+      ".stagger-children",
+      ".comp-slide-left",
+      ".comp-slide-right",
+      ".comp-arrow-anim",
+      ".landing .divider",
+    ];
+
+    document.querySelectorAll(selectors.join(",")).forEach((el) => {
+      observer.observe(el);
+    });
+
+    return () => {
+      observer.disconnect();
+    };
+  }, []);
+
+  const closeWorkspaceModal = useCallback(() => {
+    if (isImportingSpecs) return;
+    setIsWorkspaceModalOpen(false);
+    setActiveDropKind(null);
+  }, [isImportingSpecs]);
+
+  useEffect(() => {
+    if (!isWorkspaceModalOpen) return;
+
+    const previousOverflow = document.body.style.overflow;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        closeWorkspaceModal();
+      }
+    };
+
+    document.body.style.overflow = "hidden";
+    document.addEventListener("keydown", onKeyDown);
+
+    return () => {
+      document.body.style.overflow = previousOverflow;
+      document.removeEventListener("keydown", onKeyDown);
+    };
+  }, [closeWorkspaceModal, isWorkspaceModalOpen]);
+
+  const importSpecsIntoWorkspace = useCallback(
+    async (kind: SpecKind, incomingFiles: File[]) => {
+      const specFiles = incomingFiles.filter((file) =>
+        SPEC_FILE_EXTENSION_RE.test(file.name),
+      );
+
+      if (specFiles.length === 0) {
+        setImportError(
+          "Select one or more .yaml, .yml, or .json specification files.",
+        );
+        return;
+      }
+
+      setImportError(null);
+      setIsImportingSpecs(true);
+      setImportingSpecKind(kind);
+
+      try {
+        const usedFileNames = new Set<string>();
+        const namedFiles = specFiles.map((file) => ({
+          originalFile: file,
+          fileName: toUniqueFileName(file.name, usedFileNames),
+        }));
+
+        const fileEntries = await Promise.all(
+          namedFiles.map(async (file) => ({
+            fileName: file.fileName,
+            content: await readFileAsText(file.originalFile),
+          })),
+        );
+
+        for (const file of fileEntries) {
+          track(`${kind}_spec_file_uploaded`, { file_name: file.fileName });
+        }
+
+        const usedServiceNames = new Set<string>();
+        const imports: string[] = [];
+        const serviceNames: string[] = [];
+        const specFileEntries: Record<string, string> = {};
+
+        for (const file of fileEntries) {
+          const preferredServiceName = extractOpenApiTitle(file.content);
+          const serviceName = toServiceIdentifier(
+            file.fileName,
+            kind,
+            usedServiceNames,
+            preferredServiceName,
+          );
+          imports.push(`import ${serviceName} from "./${file.fileName}"`);
+          serviceNames.push(serviceName);
+          specFileEntries[file.fileName] = file.content;
+        }
+
+        // main.ec first so it appears as the first tab
+        const workspaceFiles: Record<string, string> = {};
+        workspaceFiles["main.ec"] = buildMainEcFile(
+          kind,
+          imports,
+          serviceNames,
+          fileEntries.map((file) => file.fileName),
+        );
+        Object.assign(workspaceFiles, specFileEntries);
+
+        // Generate a workspace ID and persist via the store
+        const wsId = generateWorkspaceId();
+        const specTitle =
+          extractOpenApiTitle(fileEntries[0]?.content ?? "") ??
+          fileEntries[0]?.fileName ??
+          "Imported Spec";
+        createWorkspace({
+          id: wsId,
+          files: workspaceFiles,
+          activeFile: "main.ec",
+          title: specTitle,
+          kind,
+          services: serviceNames,
+        });
+
+        track("workspace_created", { source: kind, file_count: fileEntries.length });
+
+        setIsWorkspaceModalOpen(false);
+        setActiveDropKind(null);
+        navigate(`/playground/${wsId}`);
+      } catch {
+        track("workspace_import_failed", { source: kind });
+        setImportError(
+          "Unable to import the selected specs. Please try again.",
+        );
+      } finally {
+        setIsImportingSpecs(false);
+        setImportingSpecKind(null);
+      }
+    },
+    [navigate],
+  );
+
+  const openPlayground = (e: React.MouseEvent) => {
+    e.preventDefault();
+    setImportError(null);
+    setIsWorkspaceModalOpen(true);
+    track("cta_clicked", { cta: "get_started" });
+  };
+
+  const handleDrop = useCallback(
+    (kind: SpecKind, event: React.DragEvent<HTMLElement>) => {
+      event.preventDefault();
+      if (isImportingSpecs) return;
+      setActiveDropKind(null);
+      void importSpecsIntoWorkspace(
+        kind,
+        Array.from(event.dataTransfer.files || []),
+      );
+    },
+    [importSpecsIntoWorkspace, isImportingSpecs],
+  );
+
+  const handleFileInputChange = useCallback(
+    (kind: SpecKind, event: React.ChangeEvent<HTMLInputElement>) => {
+      const files = Array.from(event.target.files || []);
+      event.target.value = "";
+      void importSpecsIntoWorkspace(kind, files);
+    },
+    [importSpecsIntoWorkspace],
+  );
+
+  const triggerFilePicker = useCallback(
+    (kind: SpecKind) => {
+      if (isImportingSpecs) return;
+      setImportError(null);
+      if (kind === "openapi") {
+        openApiInputRef.current?.click();
+        return;
+      }
+      asyncApiInputRef.current?.click();
+    },
+    [isImportingSpecs],
+  );
+
+  const openSampleWorkspace = useCallback(() => {
+    if (isImportingSpecs) return;
+    track("workspace_created", { source: "sample" });
+    setIsWorkspaceModalOpen(false);
+    setActiveDropKind(null);
+    navigate(`/playground#example=${SAMPLE_EVENT_SYSTEM_INDEX}`);
+  }, [isImportingSpecs, navigate]);
+
+  return (
+    <div className="landing">
+      {/* Nav */}
+      <nav>
+        <div className="nav-left">
+          <a href="https://eventcatalog.dev" className="nav-brand">
+            <svg
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.5"
+            >
+              <circle cx="12" cy="12" r="10" />
+              <polygon
+                points="12 2.5 14.12 14.12 12 12 9.88 14.12"
+                fill="#ef4444"
+                stroke="#ef4444"
+                strokeWidth="0.5"
+              />
+              <polygon
+                points="12 21.5 9.88 9.88 12 12 14.12 9.88"
+                fill="currentColor"
+                opacity="0.3"
+                stroke="currentColor"
+                strokeWidth="0.5"
+              />
+            </svg>
+            EventCatalog
+          </a>
+          <div className="nav-divider"></div>
+          <span className="nav-product">
+            Compass<span className="nav-badge">Preview</span>
+          </span>
+        </div>
+        <div className="nav-links">
+          <a href="#how">How It Works</a>
+          <a href="#usecases">Use Cases</a>
+          <a href="/docs">Docs</a>
+          <a
+            href="https://github.com/event-catalog"
+            target="_blank"
+            rel="noreferrer"
+          >
+            GitHub
+          </a>
+          <a href="/playground" className="nav-cta" onClick={openPlayground}>
+            Open Playground
+          </a>
+        </div>
+      </nav>
+
+      {isWorkspaceModalOpen && (
+        <div
+          className="workspace-modal-overlay"
+          role="presentation"
+          onClick={closeWorkspaceModal}
+        >
+          <div
+            className="workspace-modal"
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby="workspace-modal-title"
+            onClick={(event) => event.stopPropagation()}
+          >
+            <div className="workspace-modal-header">
+              <div>
+                <h2 id="workspace-modal-title">Get Started</h2>
+                <p>
+                  Import your specs, explore a sample, or start with a blank
+                  canvas.
+                </p>
+              </div>
+              <button
+                type="button"
+                className="workspace-modal-close"
+                aria-label="Close create workspace modal"
+                onClick={closeWorkspaceModal}
+                disabled={isImportingSpecs}
+              >
+                <X size={16} />
+              </button>
+            </div>
+
+            <section className="workspace-modal-section">
+              <div className="workspace-modal-section-header">
+                <h3>Import Your Specs</h3>
+                <p>
+                  Drag and drop or browse. Import multiple specs into one
+                  workspace.
+                </p>
+              </div>
+              <div className="workspace-modal-grid workspace-modal-grid-two">
+                <article
+                  className={`workspace-option-card workspace-option-card--openapi${activeDropKind === "openapi" ? " is-dragging" : ""}`}
+                  onDragOver={(event) => {
+                    event.preventDefault();
+                    if (isImportingSpecs) return;
+                    event.dataTransfer.dropEffect = "copy";
+                    setActiveDropKind("openapi");
+                  }}
+                  onDragEnter={(event) => {
+                    event.preventDefault();
+                    if (isImportingSpecs) return;
+                    setActiveDropKind("openapi");
+                  }}
+                  onDragLeave={() => setActiveDropKind(null)}
+                  onDrop={(event) => handleDrop("openapi", event)}
+                >
+                  <div className="workspace-option-card-body">
+                    <div className="workspace-option-card-icon workspace-option-card-icon--openapi">
+                      <OpenApiIcon size={20} />
+                    </div>
+                    <h4>OpenAPI</h4>
+                    <p>Visualize your REST services and their relationships.</p>
+                  </div>
+                  <div className="workspace-option-card-drop-hint">
+                    <Upload size={16} />
+                    <span>Drop files here or click below</span>
+                  </div>
+                  <div className="workspace-option-card-footer">
+                    <span className="workspace-option-card-meta">
+                      .yaml, .yml, .json
+                    </span>
+                    <button
+                      type="button"
+                      className="workspace-option-card-cta"
+                      onClick={() => triggerFilePicker("openapi")}
+                      disabled={isImportingSpecs}
+                    >
+                      {isImportingSpecs && importingSpecKind === "openapi"
+                        ? "Importing..."
+                        : "Upload files"}
+                    </button>
+                  </div>
+                </article>
+
+                <article
+                  className={`workspace-option-card workspace-option-card--asyncapi${activeDropKind === "asyncapi" ? " is-dragging" : ""}`}
+                  onDragOver={(event) => {
+                    event.preventDefault();
+                    if (isImportingSpecs) return;
+                    event.dataTransfer.dropEffect = "copy";
+                    setActiveDropKind("asyncapi");
+                  }}
+                  onDragEnter={(event) => {
+                    event.preventDefault();
+                    if (isImportingSpecs) return;
+                    setActiveDropKind("asyncapi");
+                  }}
+                  onDragLeave={() => setActiveDropKind(null)}
+                  onDrop={(event) => handleDrop("asyncapi", event)}
+                >
+                  <div className="workspace-option-card-body">
+                    <div className="workspace-option-card-icon workspace-option-card-icon--asyncapi">
+                      <AsyncApiIcon size={20} />
+                    </div>
+                    <h4>AsyncAPI</h4>
+                    <p>See how events flow between producers and consumers.</p>
+                  </div>
+                  <div className="workspace-option-card-drop-hint">
+                    <Upload size={16} />
+                    <span>Drop files here or click below</span>
+                  </div>
+                  <div className="workspace-option-card-footer">
+                    <span className="workspace-option-card-meta">
+                      .yaml, .yml, .json
+                    </span>
+                    <button
+                      type="button"
+                      className="workspace-option-card-cta"
+                      onClick={() => triggerFilePicker("asyncapi")}
+                      disabled={isImportingSpecs}
+                    >
+                      {isImportingSpecs && importingSpecKind === "asyncapi"
+                        ? "Importing..."
+                        : "Upload files"}
+                    </button>
+                  </div>
+                </article>
+              </div>
+            </section>
+
+            {importError && (
+              <p className="workspace-modal-error" role="alert">
+                {importError}
+              </p>
+            )}
+
+            <section className="workspace-modal-section workspace-modal-section--secondary">
+              <div className="workspace-modal-section-header">
+                <h3>Or explore</h3>
+              </div>
+              <div className="workspace-secondary-options">
+                <button
+                  type="button"
+                  className="workspace-secondary-btn"
+                  onClick={openSampleWorkspace}
+                  disabled={isImportingSpecs}
+                >
+                  <Play size={15} />
+                  <div>
+                    <span className="workspace-secondary-btn-label">
+                      Sample event-driven system
+                    </span>
+                    <span className="workspace-secondary-btn-desc">
+                      Domains, services, REST APIs, and async channels
+                    </span>
+                  </div>
+                </button>
+
+                <div
+                  className="workspace-secondary-btn workspace-secondary-btn--disabled"
+                  aria-disabled="true"
+                >
+                  <Link2 size={15} />
+                  <div>
+                    <span className="workspace-secondary-btn-label">
+                      Connect to EventCatalog project
+                    </span>
+                    <span className="workspace-secondary-btn-desc">
+                      Sync specs from an existing workspace
+                    </span>
+                  </div>
+                  <span className="workspace-secondary-btn-badge">Soon</span>
+                </div>
+              </div>
+            </section>
+
+            <input
+              ref={openApiInputRef}
+              type="file"
+              className="workspace-file-input"
+              multiple
+              accept=".yaml,.yml,.json"
+              onChange={(event) => handleFileInputChange("openapi", event)}
+            />
+            <input
+              ref={asyncApiInputRef}
+              type="file"
+              className="workspace-file-input"
+              multiple
+              accept=".yaml,.yml,.json"
+              onChange={(event) => handleFileInputChange("asyncapi", event)}
+            />
+
+            <p className="workspace-modal-privacy">
+              Your data stays in your browser. Nothing is uploaded or stored on
+              our servers.
+            </p>
+          </div>
+        </div>
+      )}
+
+      {/* Hero */}
+      <section className="hero">
+        <div className="hero-eyebrow">
+          <span className="dot"></span>
+          Now in preview
+        </div>
+        <h1>
+          Design your architecture.
+          <br />
+          From what you <span className="highlight">already have.</span>
+        </h1>
+        <p className="hero-sub">
+          Import AsyncAPI, OpenAPI, or EventCatalog. Model new domains, services, and flows — then publish them as living documentation.
+        </p>
+        <div className="hero-actions">
+          <a
+            href="https://compass.eventcatalog.dev/docs/get-started/tutorial/"
+            className="btn-primary"
+            // onClick={openPlayground}
+          >
+            Get started &rarr;
+          </a>
+          <a href="#how" className="btn-ghost">
+            How it works
+          </a>
+        </div>
+
+        {/* Editor Preview — live playground */}
+        <HeroPreview />
+
+        {/* Value props row */}
+        <div className="hero-pillars">
+          <div className="hero-pillar">
+            <svg
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.5"
+              width="20"
+              height="20"
+            >
+              <path d="M10 20l4-16m4 4l4 4-4 4M6 16l-4-4 4-4" />
+            </svg>
+            <div>
+              <strong>A language for your architecture</strong>
+              <span>
+                Define domains, services, events, and channels. All in one
+                readable file.
+              </span>
+            </div>
+          </div>
+          <div className="hero-pillar">
+            <svg
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.5"
+              width="20"
+              height="20"
+            >
+              <path d="M12 10v6m0 0l-3-3m3 3l3-3m2 8H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+            </svg>
+            <div>
+              <strong>Start from what you already have</strong>
+              <span>
+                Import resources from AsyncAPI, OpenAPI, or an existing EventCatalog.
+              </span>
+            </div>
+          </div>
+          <div className="hero-pillar">
+            <svg
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.5"
+              width="20"
+              height="20"
+            >
+              <path d="M12 10v6m0 0l-3-3m3 3l3-3m2 8H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+            </svg>
+            <div>
+              <strong>From model to docs in one click</strong>
+              <span>
+                Import and export to EventCatalog and give your whole team a living
+                architecture portal.
+              </span>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      {/* Logos */}
+      <section className="logos-section">
+        <div className="logos-label">EventCatalog is trusted by teams at</div>
+        <div className="logos-row">
+          <span>Nike</span>
+          <span>GOV.UK</span>
+          <span>AWS</span>
+          <span>Ticketmaster</span>
+          <span>Eurostar</span>
+          <span>TUI</span>
+          <span>Mazda</span>
+        </div>
+      </section>
+
+      <div className="divider"></div>
+
+      {/* Problem */}
+      <section className="section section-center">
+        <div className="section-label section-label-red reveal">
+          The Problem
+        </div>
+        <h2 className="section-title reveal">
+          Your architecture lives in five tools <br/> and one person's head
+        </h2>
+        <p className="section-desc reveal">
+          Your specs describe the pieces. The diagrams are six months old. The
+          person who knows how it all connects is on holiday.
+        </p>
+        <div className="bento-grid stagger-children">
+          {/* Row 1: Wide + 2 regular */}
+          <div className="bento-card bento-col-2">
+            <div className="bento-text">
+              <div className="bento-icon">
+                <svg
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="var(--orange)"
+                  strokeWidth="1.5"
+                  width="20"
+                  height="20"
+                >
+                  <path d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+                </svg>
+                <span>Specs in silos</span>
+              </div>
+              <p>
+                AsyncAPI, OpenAPI, Avro. Each describes one piece.
+                <br />
+                <strong>None shows how they connect.</strong>
+              </p>
+            </div>
+            <div className="bento-viz">
+              {/* Scattered file cards with no connections */}
+              <div className="bento-files-scatter">
+                <div
+                  className="bento-file-card"
+                  style={{ top: "8%", left: "5%" }}
+                >
+                  <div className="bento-file-dot bento-file-dot-cyan"></div>
+                  <span>orders-asyncapi.yml</span>
+                </div>
+                <div
+                  className="bento-file-card"
+                  style={{ top: "8%", right: "8%" }}
+                >
+                  <div className="bento-file-dot bento-file-dot-green"></div>
+                  <span>payments-openapi.yml</span>
+                </div>
+                <div
+                  className="bento-file-card"
+                  style={{ bottom: "24%", left: "12%" }}
+                >
+                  <div className="bento-file-dot bento-file-dot-cyan"></div>
+                  <span>inventory-asyncapi.yml</span>
+                </div>
+                <div
+                  className="bento-file-card"
+                  style={{ bottom: "24%", right: "5%" }}
+                >
+                  <div className="bento-file-dot bento-file-dot-green"></div>
+                  <span>shipping-openapi.yml</span>
+                </div>
+                {/* Dashed lines that go nowhere */}
+                <svg
+                  className="bento-scatter-lines"
+                  viewBox="0 0 400 200"
+                  preserveAspectRatio="none"
+                >
+                  <line
+                    x1="120"
+                    y1="40"
+                    x2="200"
+                    y2="100"
+                    stroke="var(--border-hover)"
+                    strokeWidth="1"
+                    strokeDasharray="4 4"
+                    opacity="0.4"
+                  />
+                  <line
+                    x1="280"
+                    y1="40"
+                    x2="200"
+                    y2="100"
+                    stroke="var(--border-hover)"
+                    strokeWidth="1"
+                    strokeDasharray="4 4"
+                    opacity="0.4"
+                  />
+                  <line
+                    x1="140"
+                    y1="150"
+                    x2="200"
+                    y2="100"
+                    stroke="var(--border-hover)"
+                    strokeWidth="1"
+                    strokeDasharray="4 4"
+                    opacity="0.3"
+                  />
+                  <line
+                    x1="300"
+                    y1="150"
+                    x2="200"
+                    y2="100"
+                    stroke="var(--border-hover)"
+                    strokeWidth="1"
+                    strokeDasharray="4 4"
+                    opacity="0.3"
+                  />
+                  <circle
+                    cx="200"
+                    cy="100"
+                    r="3"
+                    fill="var(--text-muted)"
+                    opacity="0.3"
+                  />
+                </svg>
+                <div className="bento-scatter-label">No connections</div>
+              </div>
+            </div>
+          </div>
+
+          <div className="bento-card">
+            <div className="bento-text">
+              <div className="bento-icon">
+                <svg
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="var(--cyan)"
+                  strokeWidth="1.5"
+                  width="20"
+                  height="20"
+                >
+                  <path d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z" />
+                </svg>
+                <span>Stale diagrams</span>
+              </div>
+              <p>
+                That Miro board was accurate last quarter.
+                <br />
+                <strong>Now it's misleading anyone who trusts it.</strong>
+              </p>
+            </div>
+            <div className="bento-viz">
+              {/* Faded diagram mockup */}
+              <div className="bento-stale-diagram">
+                <div
+                  className="bento-stale-node"
+                  style={{ top: "10%", left: "25%" }}
+                ></div>
+                <div
+                  className="bento-stale-node"
+                  style={{ top: "10%", right: "25%" }}
+                ></div>
+                <div
+                  className="bento-stale-node"
+                  style={{
+                    top: "50%",
+                    left: "50%",
+                    transform: "translateX(-50%)",
+                  }}
+                ></div>
+                <svg
+                  className="bento-stale-lines"
+                  viewBox="0 0 200 120"
+                  preserveAspectRatio="none"
+                >
+                  <line
+                    x1="60"
+                    y1="25"
+                    x2="140"
+                    y2="25"
+                    stroke="var(--border-hover)"
+                    strokeWidth="1"
+                    strokeDasharray="3 3"
+                    opacity="0.3"
+                  />
+                  <line
+                    x1="60"
+                    y1="25"
+                    x2="100"
+                    y2="70"
+                    stroke="var(--border-hover)"
+                    strokeWidth="1"
+                    strokeDasharray="3 3"
+                    opacity="0.3"
+                  />
+                  <line
+                    x1="140"
+                    y1="25"
+                    x2="100"
+                    y2="70"
+                    stroke="var(--border-hover)"
+                    strokeWidth="1"
+                    strokeDasharray="3 3"
+                    opacity="0.3"
+                  />
+                </svg>
+                <div className="bento-stale-stamp">
+                  <svg
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="1.5"
+                    width="14"
+                    height="14"
+                  >
+                    <path d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z" />
+                  </svg>
+                  <span>6 months ago</span>
+                </div>
+              </div>
+            </div>
+          </div>
+
+          <div className="bento-card">
+            <div className="bento-text">
+              <div className="bento-icon">
+                <svg
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="var(--accent)"
+                  strokeWidth="1.5"
+                  width="20"
+                  height="20"
+                >
+                  <path d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" />
+                </svg>
+                <span>Tribal knowledge</span>
+              </div>
+              <p>
+                The real architecture lives in one person's head.
+                <br />
+                <strong>When they leave, it leaves with them.</strong>
+              </p>
+            </div>
+            <div className="bento-viz">
+              {/* Person with knowledge radiating out */}
+              <div className="bento-tribal-viz">
+                <div className="bento-tribal-person">
+                  <svg
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="var(--accent)"
+                    strokeWidth="1"
+                    width="40"
+                    height="40"
+                    opacity="0.6"
+                  >
+                    <path d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z" />
+                  </svg>
+                </div>
+                <div className="bento-tribal-bubbles">
+                  <span style={{ animationDelay: "0s" }}>OrderService</span>
+                  <span style={{ animationDelay: "0.6s" }}>OrderCreated</span>
+                  <span style={{ animationDelay: "1.2s" }}>PaymentAPI</span>
+                  <span style={{ animationDelay: "1.8s" }}>kafka.orders</span>
+                  <span style={{ animationDelay: "2.4s" }}>ShipmentFlow</span>
+                </div>
+              </div>
+            </div>
+          </div>
+
+          {/* Row 2: 3 regular cards */}
+          <div className="bento-card">
+            <div className="bento-text">
+              <div className="bento-icon">
+                <svg
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="var(--green)"
+                  strokeWidth="1.5"
+                  width="20"
+                  height="20"
+                >
+                  <path d="M8 12h.01M12 12h.01M16 12h.01M21 12c0 4.418-4.03 8-9 8a9.863 9.863 0 01-4.255-.949L3 20l1.395-3.72C3.512 15.042 3 13.574 3 12c0-4.418 4.03-8 9-8s9 3.582 9 8z" />
+                </svg>
+                <span>Slow onboarding</span>
+              </div>
+              <p>
+                New engineers spend days asking around.
+                <br />
+                <strong>"Who owns this event? Where does it go?"</strong>
+              </p>
+            </div>
+            <div className="bento-viz">
+              <div className="bento-onboarding-viz">
+                <div className="bento-chat-bubble bento-chat-q">
+                  Who owns OrderCreated?
+                </div>
+                <div className="bento-chat-bubble bento-chat-a">
+                  Maybe the orders team?
+                </div>
+                <div className="bento-chat-bubble bento-chat-q">
+                  Where does it publish to?
+                </div>
+                <div className="bento-chat-bubble bento-chat-a">
+                  Check with Sarah
+                </div>
+                <div className="bento-chat-bubble bento-chat-q">
+                  Is this still in use?
+                </div>
+                <div className="bento-chat-bubble bento-chat-a">No idea</div>
+              </div>
+            </div>
+          </div>
+
+          <div className="bento-card">
+            <div className="bento-text">
+              <div className="bento-icon">
+                <svg
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="var(--yellow)"
+                  strokeWidth="1.5"
+                  width="20"
+                  height="20"
+                >
+                  <path d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
+                </svg>
+                <span>No source of truth</span>
+              </div>
+              <p>
+                Wiki, Confluence, Notion, Slack threads.
+                <br />
+                <strong>Five sources. Five different answers.</strong>
+              </p>
+            </div>
+            <div className="bento-viz">
+              <div className="bento-sources-viz">
+                <div className="bento-source-row">
+                  <div className="bento-source-pill">Wiki</div>
+                  <span className="bento-source-val">v2.1 (REST)</span>
+                </div>
+                <div className="bento-source-row">
+                  <div className="bento-source-pill">Confluence</div>
+                  <span className="bento-source-val">v1.3 (gRPC)</span>
+                </div>
+                <div className="bento-source-row">
+                  <div className="bento-source-pill">Notion</div>
+                  <span className="bento-source-val">v2.0 (Kafka)</span>
+                </div>
+                <div className="bento-source-row">
+                  <div className="bento-source-pill">Slack</div>
+                  <span className="bento-source-val">
+                    "I think it's deprecated?"
+                  </span>
+                </div>
+                <div className="bento-source-row">
+                  <div className="bento-source-pill">README</div>
+                  <span className="bento-source-val">Last updated 2023</span>
+                </div>
+              </div>
+            </div>
+          </div>
+
+          {/* Row 3: Full-width before/after */}
+          <div className="bento-card bento-col-3">
+            <div className="bento-before-after">
+              <div className="bento-ba-side">
+                <div className="bento-ba-label">Today</div>
+                <div className="bento-ba-content">
+                  <div className="bento-ba-files">
+                    <code>orders-asyncapi.yml</code>
+                    <code>payments-openapi.yml</code>
+                    <code>inventory-asyncapi.yml</code>
+                    <code>shipping-openapi.yml</code>
+                  </div>
+                  <span className="bento-ba-note">
+                    No view of how they connect
+                  </span>
+                </div>
+              </div>
+              <div className="bento-ba-arrow">
+                <svg
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="1.5"
+                  width="24"
+                  height="24"
+                >
+                  <path d="M13.5 4.5L21 12m0 0l-7.5 7.5M21 12H3" />
+                </svg>
+              </div>
+              <div className="bento-ba-side bento-ba-after">
+                <div className="bento-ba-label bento-ba-label-green">
+                  With Compass
+                </div>
+                <div className="bento-ba-content">
+                  <div className="bento-ba-files">
+                    <code>
+                      <span className="kw">import from</span>{" "}
+                      <span className="str">"./orders-asyncapi.yml"</span>
+                    </code>
+                    <code>
+                      <span className="kw">import from</span>{" "}
+                      <span className="str">"./payments-openapi.yml"</span>
+                    </code>
+                    <code>
+                      <span className="kw">import from</span>{" "}
+                      <span className="str">"./inventory-asyncapi.yml"</span>
+                    </code>
+                    <code>
+                      <span className="kw">import from</span>{" "}
+                      <span className="str">"./shipping-openapi.yml"</span>
+                    </code>
+                  </div>
+                  <span className="bento-ba-note bento-ba-note-green">
+                    Full architecture view, instantly
+                  </span>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+        <p className="bento-statement reveal">
+          <strong>Your specs and catalogs already describe the pieces.</strong> Compass
+          connects them into one living view.
+        </p>
+      </section>
+
+      <div className="divider"></div>
+
+      {/* How It Works */}
+      <section className="section" id="how">
+        <div className="section-label reveal">How It Works</div>
+        <h2 className="section-title reveal">
+          From specs to architecture in three steps
+        </h2>
+        <p className="section-desc reveal">Import. Compose. Visualize.</p>
+        <div className="steps stagger-children">
+          <div className="step">
+            <div className="step-head">
+              <div className="step-num">1</div>
+              <h3>Import from specs or EventCatalog</h3>
+            </div>
+            <div className="step-body">
+              <p>
+                Pull events, operations, and channels from AsyncAPI and
+                OpenAPI files. Or start from an existing EventCatalog.
+              </p>
+              <div className="code-block">
+                <div className="code-tab">main.ec</div>
+                <pre>
+                  <span className="cm">{"// Import specific resources"}</span>
+                  {"\n"}
+                  <span className="kw">import events</span>{" "}
+                  <span className="br">{"{"}</span>{" "}
+                  <span className="ref">OrderCreated</span>,{" "}
+                  <span className="ref">OrderShipped</span>{" "}
+                  <span className="br">{"}"}</span>{" "}
+                  <span className="kw">from</span>{" "}
+                  <span className="str">"./asyncapi.yml"</span>
+                  {"\n"}
+                  <span className="kw">import operations</span>{" "}
+                  <span className="br">{"{"}</span>{" "}
+                  <span className="ref">CreateOrder</span>{" "}
+                  <span className="br">{"}"}</span>{" "}
+                  <span className="kw">from</span>{" "}
+                  <span className="str">"./openapi.yml"</span>
+                  {"\n\n"}
+                  <span className="cm">{"// Or import everything"}</span>
+                  {"\n"}
+                  <span className="kw">import from</span>{" "}
+                  <span className="str">"./orders-asyncapi.yml"</span>
+                  {"\n\n"}
+                  <span className="cm">{"// Import from an existing EventCatalog"}</span>
+                  {"\n"}
+                  <span className="kw">import service</span>{" "}
+                  <span className="br">{"{"}</span>{" "}
+                  <span className="ref">PaymentService</span>{" "}
+                  <span className="br">{"}"}</span>{" "}
+                  <span className="kw">from</span>{" "}
+                  <span className="str">"@eventcatalog"</span>
+                </pre>
+              </div>
+            </div>
+          </div>
+          <div className="step">
+            <div className="step-head">
+              <div className="step-num">2</div>
+              <h3>Compose the architecture</h3>
+            </div>
+            <div className="step-body">
+              <p>
+                Add domains, ownership, and messaging. The context that specs
+                alone can't capture.
+              </p>
+              <div className="code-block">
+                <div className="code-tab">main.ec</div>
+                <pre>
+                  <span className="cm">
+                    {"// Group services into a business domain"}
+                  </span>
+                  {"\n"}
+                  <span className="kw">domain</span>{" "}
+                  <span className="fn">OrderManagement</span>{" "}
+                  <span className="br">{"{"}</span>
+                  {"\n"}
+                  {"  "}
+                  <span className="kw">version</span>{" "}
+                  <span className="str">1.0.0</span>
+                  {"\n\n"}
+                  {"  "}
+                  <span className="cm">
+                    {"// Assign ownership and wire up messaging"}
+                  </span>
+                  {"\n"}
+                  {"  "}
+                  <span className="kw">service</span>{" "}
+                  <span className="fn">OrderService</span>{" "}
+                  <span className="br">{"{"}</span>
+                  {"\n"}
+                  {"    "}
+                  <span className="kw">owners</span>{" "}
+                  <span className="ref">@order-team</span>
+                  {"\n"}
+                  {"    "}
+                  <span className="kw">sends event</span>{" "}
+                  <span className="ref">OrderCreated</span>{" "}
+                  <span className="kw">to</span>{" "}
+                  <span className="ref">OrderStream</span>
+                  {"\n"}
+                  {"  "}
+                  <span className="br">{"}"}</span>
+                  {"\n\n"}
+                  {"  "}
+                  <span className="cm">
+                    {"// Define consumers. Compass maps the dependency"}
+                  </span>
+                  {"\n"}
+                  {"  "}
+                  <span className="kw">service</span>{" "}
+                  <span className="fn">PaymentService</span>{" "}
+                  <span className="br">{"{"}</span>
+                  {"\n"}
+                  {"    "}
+                  <span className="kw">receives event</span>{" "}
+                  <span className="ref">OrderCreated</span>{" "}
+                  <span className="kw">from</span>{" "}
+                  <span className="ref">OrderStream</span>
+                  {"\n"}
+                  {"  "}
+                  <span className="br">{"}"}</span>
+                  {"\n"}
+                  <span className="br">{"}"}</span>
+                </pre>
+              </div>
+            </div>
+          </div>
+          <div className="step">
+            <div className="step-head">
+              <div className="step-num">3</div>
+              <h3>Visualize and commit</h3>
+            </div>
+            <div className="step-body">
+              <p>
+                Your architecture renders as you type. Commit your .ec files to
+                the repo so the whole team sees the same picture. When you're
+                ready, export to EventCatalog for full documentation.
+              </p>
+              <StepVisualizer />
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <div className="divider"></div>
+
+      {/* Sources */}
+      <section className="section section-center">
+        <div className="section-label reveal">Import From Anywhere</div>
+        <h2 className="section-title reveal">Your specs. Your catalog. One architecture.</h2>
+        <p className="section-desc reveal">
+          AsyncAPI, OpenAPI, and EventCatalog today. Registries and more coming soon.
+        </p>
+        <div className="sources-grid stagger-children">
+          <a href="https://compass.eventcatalog.dev/docs/guides/import-from-asyncapi/" target="_blank" rel="noopener noreferrer" className="source-card">
+            <div className="source-icon-wrap">
+              <img src="/asyncapi.svg" alt="AsyncAPI" width="24" height="24" />
+            </div>
+            <h4>AsyncAPI</h4>
+            <span className="source-detail">Events, channels</span>
+          </a>
+          <a href="https://compass.eventcatalog.dev/docs/guides/import-from-openapi/" target="_blank" rel="noopener noreferrer" className="source-card">
+            <div className="source-icon-wrap">
+              <img src="/openapi.svg" alt="OpenAPI" width="24" height="24" />
+            </div>
+            <h4>OpenAPI</h4>
+            <span className="source-detail">Operations, endpoints</span>
+          </a>
+          <a href="https://compass.eventcatalog.dev/docs/guides/import-from-eventcatalog/" target="_blank" rel="noopener noreferrer" className="source-card">
+            <div className="source-icon-wrap source-icon-wrap-ec">
+              <img src="/eventcatalog-logo.png" alt="EventCatalog" />
+            </div>
+            <h4>EventCatalog</h4>
+            <span className="source-detail">Services, messages, domains</span>
+          </a>
+          <div className="source-card soon">
+            <div className="source-icon-wrap">
+              <svg
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="var(--text-muted)"
+                strokeWidth="1.5"
+              >
+                <path d="M4 7v10c0 2.21 3.582 4 8 4s8-1.79 8-4V7M4 7c0 2.21 3.582 4 8 4s8-1.79 8-4M4 7c0-2.21 3.582-4 8-4s8 1.79 8 4m0 5c0 2.21-3.582 4-8 4s-8-1.79-8-4" />
+              </svg>
+            </div>
+            <h4>Confluent</h4>
+            <span className="source-detail">Schema Registry</span>
+          </div>
+          <div className="source-card soon">
+            <div className="source-icon-wrap">
+              <svg
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="var(--text-muted)"
+                strokeWidth="1.5"
+              >
+                <path d="M3 15a4 4 0 004 4h9a5 5 0 10-.1-9.999 5.002 5.002 0 10-9.78 2.096A4.001 4.001 0 003 15z" />
+              </svg>
+            </div>
+            <h4>AWS</h4>
+            <span className="source-detail">EventBridge, Glue</span>
+          </div>
+          <div className="source-card soon">
+            <div className="source-icon-wrap">
+              <svg
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="var(--text-muted)"
+                strokeWidth="1.5"
+              >
+                <path d="M10 20l4-16m4 4l4 4-4 4M6 16l-4-4 4-4" />
+              </svg>
+            </div>
+            <h4>GitHub</h4>
+            <span className="source-detail">Private repos</span>
+          </div>
+          <div className="source-card soon">
+            <div className="source-icon-wrap">
+              <svg
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="var(--text-muted)"
+                strokeWidth="1.5"
+              >
+                <path d="M19.428 15.428a2 2 0 00-1.022-.547l-2.387-.477a6 6 0 00-3.86.517l-.318.158a6 6 0 01-3.86.517L6.05 15.21a2 2 0 00-1.806.547M8 4h8l-1 1v5.172a2 2 0 00.586 1.414l5 5c1.26 1.26.367 3.414-1.415 3.414H4.828c-1.782 0-2.674-2.154-1.414-3.414l5-5A2 2 0 009 10.172V5L8 4z" />
+              </svg>
+            </div>
+            <h4>Apicurio</h4>
+            <span className="source-detail">Schema Registry</span>
+          </div>
+          <div className="source-card soon">
+            <div className="source-icon-wrap">
+              <svg
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="var(--text-muted)"
+                strokeWidth="1.5"
+              >
+                <path d="M3 15a4 4 0 004 4h9a5 5 0 10-.1-9.999 5.002 5.002 0 10-9.78 2.096A4.001 4.001 0 003 15z" />
+              </svg>
+            </div>
+            <h4>Azure</h4>
+            <span className="source-detail">Schema Registry</span>
+          </div>
+        </div>
+      </section>
+
+      <div className="divider"></div>
+
+      {/* Use Cases */}
+      <section className="section section-center" id="usecases">
+        <div className="section-label reveal">Built For Architects</div>
+        <h2 className="section-title reveal">How teams can use Compass</h2>
+        <div className="usecases-grid stagger-children">
+          <div className="usecase-card">
+            <div className="usecase-header">
+              <svg
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                width="20"
+                height="20"
+              >
+                <path d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+              </svg>
+              <h3>Architecture discovery</h3>
+            </div>
+            <p>
+              Import spec files and see how services connect across your system.
+              <br />
+              <strong>
+                New engineers get the full picture in minutes, not weeks.
+              </strong>
+            </p>
+            <div className="usecase-viz">
+              <div className="usecase-viz-inner usecase-discovery">
+                <div
+                  className="uc-node uc-node-service"
+                  style={{
+                    top: "20%",
+                    left: "50%",
+                    transform: "translateX(-50%)",
+                  }}
+                >
+                  OrderService
+                </div>
+                <div
+                  className="uc-node uc-node-event"
+                  style={{ bottom: "20%", left: "15%" }}
+                >
+                  OrderCreated
+                </div>
+                <div
+                  className="uc-node uc-node-event"
+                  style={{ bottom: "20%", right: "15%" }}
+                >
+                  PaymentProcessed
+                </div>
+                <svg
+                  className="uc-lines"
+                  viewBox="0 0 300 120"
+                  preserveAspectRatio="none"
+                >
+                  <line
+                    x1="150"
+                    y1="35"
+                    x2="65"
+                    y2="85"
+                    stroke="var(--cyan)"
+                    strokeWidth="1"
+                    opacity="0.3"
+                  />
+                  <line
+                    x1="150"
+                    y1="35"
+                    x2="235"
+                    y2="85"
+                    stroke="var(--cyan)"
+                    strokeWidth="1"
+                    opacity="0.3"
+                  />
+                </svg>
+              </div>
+            </div>
+          </div>
+          <div className="usecase-card">
+            <div className="usecase-header">
+              <svg
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                width="20"
+                height="20"
+              >
+                <path d="M11 4H4a2 2 0 00-2 2v14a2 2 0 002 2h14a2 2 0 002-2v-7" />
+                <path d="M18.5 2.5a2.121 2.121 0 013 3L12 15l-4 1 1-4 9.5-9.5z" />
+              </svg>
+              <h3>Design and planning</h3>
+            </div>
+            <p>
+              Import current state from specs or EventCatalog. Design future
+              and target architectures inline.
+              <br />
+              <strong>Compare before and after in one view.</strong>
+            </p>
+            <div className="usecase-viz">
+              <div className="usecase-viz-inner usecase-design">
+                <div className="uc-design-col">
+                  <span className="uc-design-label">Before</span>
+                  <div className="uc-design-block"></div>
+                  <div className="uc-design-block"></div>
+                </div>
+                <div className="uc-design-arrow">
+                  <svg
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="1.5"
+                    width="16"
+                    height="16"
+                  >
+                    <path d="M13.5 4.5L21 12m0 0l-7.5 7.5M21 12H3" />
+                  </svg>
+                </div>
+                <div className="uc-design-col">
+                  <span className="uc-design-label uc-design-label-new">
+                    After
+                  </span>
+                  <div className="uc-design-block uc-design-block-new"></div>
+                  <div className="uc-design-block uc-design-block-new"></div>
+                  <div className="uc-design-block uc-design-block-added"></div>
+                </div>
+              </div>
+            </div>
+          </div>
+          <div className="usecase-card">
+            <div className="usecase-header">
+              <svg
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                width="20"
+                height="20"
+              >
+                <path d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
+              </svg>
+              <h3>Impact analysis</h3>
+            </div>
+            <p>
+              Deprecating an event? Import your specs and see every service that
+              depends on it.
+              <br />
+              <strong>No more chasing down five different teams.</strong>
+            </p>
+            <div className="usecase-viz">
+              <div className="usecase-viz-inner usecase-impact">
+                <svg className="uc-impact-svg" viewBox="0 0 280 140">
+                  {/* Lines from center to deps */}
+                  <line
+                    className="uc-impact-line"
+                    x1="140"
+                    y1="70"
+                    x2="40"
+                    y2="25"
+                  />
+                  <line
+                    className="uc-impact-line"
+                    x1="140"
+                    y1="70"
+                    x2="240"
+                    y2="25"
+                  />
+                  <line
+                    className="uc-impact-line"
+                    x1="140"
+                    y1="70"
+                    x2="50"
+                    y2="118"
+                  />
+                  <line
+                    className="uc-impact-line"
+                    x1="140"
+                    y1="70"
+                    x2="230"
+                    y2="118"
+                  />
+                  {/* Center node */}
+                  <rect
+                    x="90"
+                    y="55"
+                    width="100"
+                    height="30"
+                    rx="6"
+                    className="uc-impact-center-bg"
+                  />
+                  <text
+                    x="140"
+                    y="74"
+                    textAnchor="middle"
+                    className="uc-impact-center-text"
+                  >
+                    OrderCreated
+                  </text>
+                  {/* Dep nodes */}
+                  <rect
+                    x="2"
+                    y="12"
+                    width="76"
+                    height="26"
+                    rx="4"
+                    className="uc-impact-dep-bg"
+                  />
+                  <text
+                    x="40"
+                    y="29"
+                    textAnchor="middle"
+                    className="uc-impact-dep-text"
+                  >
+                    Payments
+                  </text>
+                  <rect
+                    x="202"
+                    y="12"
+                    width="76"
+                    height="26"
+                    rx="4"
+                    className="uc-impact-dep-bg"
+                  />
+                  <text
+                    x="240"
+                    y="29"
+                    textAnchor="middle"
+                    className="uc-impact-dep-text"
+                  >
+                    Shipping
+                  </text>
+                  <rect
+                    x="2"
+                    y="105"
+                    width="96"
+                    height="26"
+                    rx="4"
+                    className="uc-impact-dep-bg"
+                  />
+                  <text
+                    x="50"
+                    y="122"
+                    textAnchor="middle"
+                    className="uc-impact-dep-text"
+                  >
+                    Notifications
+                  </text>
+                  <rect
+                    x="182"
+                    y="105"
+                    width="96"
+                    height="26"
+                    rx="4"
+                    className="uc-impact-dep-bg"
+                  />
+                  <text
+                    x="230"
+                    y="122"
+                    textAnchor="middle"
+                    className="uc-impact-dep-text"
+                  >
+                    Analytics
+                  </text>
+                </svg>
+              </div>
+            </div>
+          </div>
+          <div className="usecase-card">
+            <div className="usecase-header">
+              <svg
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                width="20"
+                height="20"
+              >
+                <path d="M9.75 17L9 20l-1 1h8l-1-1-.75-3M3 13h18M5 17h14a2 2 0 002-2V5a2 2 0 00-2-2H5a2 2 0 00-2 2v10a2 2 0 002 2z" />
+              </svg>
+              <h3>Queryable architecture</h3>
+            </div>
+            <p>
+              Export to EventCatalog and use the MCP server to let AI agents
+              query your architecture.
+              <br />
+              <strong>
+                Ask questions, trace dependencies, and evolve your system with
+                AI.
+              </strong>
+            </p>
+            <div className="usecase-viz">
+              <div className="usecase-viz-inner usecase-ai">
+                <div className="uc-ai-prompt">
+                  <span className="uc-ai-caret">&gt;</span> Which services
+                  depend on OrderCreated?
+                </div>
+                <div className="uc-ai-response">
+                  <span>
+                    PaymentService, ShippingService, NotificationService
+                  </span>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <div className="divider"></div>
+
+      {/* CTA */}
+      <section className="cta-hero">
+        <h2 className="cta-hero-title reveal">
+          See your architecture in 30 seconds
+        </h2>
+        <p className="cta-hero-desc reveal">
+          No signup. No install. Drop in a spec and see your services connect.
+        </p>
+        <div className="cta-hero-actions reveal">
+          <a
+            href="/playground"
+            className="btn-primary btn-lg"
+            onClick={openPlayground}
+          >
+            Open Playground &rarr;
+          </a>
+          <a href="/docs" className="btn-ghost btn-lg">
+            Read the docs
+          </a>
+        </div>
+        <p className="cta-hero-note reveal">
+          Free and open source &middot; No account required &middot; Exports to
+          EventCatalog
+        </p>
+      </section>
+
+      {/* Footer */}
+      <footer className="reveal">
+        <span className="footer-brand">
+          EventCatalog Compass &middot; Built by{" "}
+          <a href="https://twitter.com/boyney123">David Boyne</a>
+        </span>
+        <div className="footer-links">
+          <a href="https://eventcatalog.dev">EventCatalog</a>
+          <a href="https://github.com/event-catalog">GitHub</a>
+          <a href="https://discord.gg/3rjaZMmrAm">Discord</a>
+          <a href="https://twitter.com/event_catalog">Twitter</a>
+        </div>
+      </footer>
+    </div>
+  );
+}
diff --git a/packages/playground/src/resolvers/index.ts b/packages/playground/src/resolvers/index.ts
new file mode 100644
index 000000000..1e142a7fe
--- /dev/null
+++ b/packages/playground/src/resolvers/index.ts
@@ -0,0 +1,3 @@
+// Re-exported from @eventcatalog/language-server
+export type { SpecMessage, SpecChannel, SpecOperation, SpecService, ResourceType, SpecResolveResult, FetchFn } from '@eventcatalog/language-server/browser';
+export { resolveAsyncApiImports, resolveAsyncApiImportsAsync, resolveSpecImports, resolveSpecImportsAsync } from '@eventcatalog/language-server/browser';
diff --git a/packages/playground/src/resolvers/types.ts b/packages/playground/src/resolvers/types.ts
new file mode 100644
index 000000000..5746e5360
--- /dev/null
+++ b/packages/playground/src/resolvers/types.ts
@@ -0,0 +1,8 @@
+// Re-exported from @eventcatalog/language-server
+export type {
+  SpecMessage,
+  SpecChannel,
+  ResourceType,
+  ResolveError,
+  SpecResolveResult,
+} from '@eventcatalog/language-server/browser';
diff --git a/packages/playground/src/stores/workspace.ts b/packages/playground/src/stores/workspace.ts
new file mode 100644
index 000000000..798fb035c
--- /dev/null
+++ b/packages/playground/src/stores/workspace.ts
@@ -0,0 +1,288 @@
+import { atom, map } from "nanostores";
+import { persistentAtom } from "@nanostores/persistent";
+
+// ---------------------------------------------------------------------------
+// Global (non-workspace) stores
+// ---------------------------------------------------------------------------
+
+/** Visualizer theme — persisted to localStorage and synced across tabs. */
+export const $theme = persistentAtom<"light" | "dark">(
+  "ec-playground-theme",
+  "light",
+);
+
+// ---------------------------------------------------------------------------
+// Workspace state
+// ---------------------------------------------------------------------------
+
+export type SpecKind = "openapi" | "asyncapi";
+
+export interface WorkspaceState {
+  /** Short hash identifying this workspace (from the URL). */
+  id: string;
+  files: Record<string, string>;
+  activeFile: string;
+  title?: string;
+  kind?: SpecKind;
+  services: string[];
+  showGuide: boolean;
+  guideDone: string[];
+}
+
+const EMPTY_WORKSPACE: WorkspaceState = {
+  id: "",
+  files: { "main.ec": "" },
+  activeFile: "main.ec",
+  title: undefined,
+  kind: undefined,
+  services: [],
+  showGuide: false,
+  guideDone: [],
+};
+
+/** Reactive store holding the current workspace data. */
+export const $workspace = map<WorkspaceState>({ ...EMPTY_WORKSPACE });
+
+// ---------------------------------------------------------------------------
+// localStorage key helpers
+// ---------------------------------------------------------------------------
+
+function wsKey(id: string, suffix: string) {
+  return `ec-workspace-${id}-${suffix}`;
+}
+
+// ---------------------------------------------------------------------------
+// Load / save / clear — workspace
+// ---------------------------------------------------------------------------
+
+/** Load workspace state from localStorage into $workspace. Returns true if data existed. */
+export function loadWorkspace(id: string): boolean {
+  try {
+    const raw = localStorage.getItem(wsKey(id, "files"));
+    if (!raw) return false;
+    const files = JSON.parse(raw);
+    if (!files || typeof files !== "object" || Object.keys(files).length === 0)
+      return false;
+
+    const activeFile =
+      localStorage.getItem(wsKey(id, "active")) ?? Object.keys(files)[0];
+    const title = localStorage.getItem(wsKey(id, "title")) ?? undefined;
+    const kind =
+      (localStorage.getItem(wsKey(id, "kind")) as SpecKind | null) ?? undefined;
+    const services = jsonParse<string[]>(
+      localStorage.getItem(wsKey(id, "services")),
+      [],
+    );
+    const showGuide = localStorage.getItem(wsKey(id, "guide")) === "true";
+    const guideDone = jsonParse<string[]>(
+      localStorage.getItem(wsKey(id, "guide-done")),
+      [],
+    );
+
+    $workspace.set({
+      id,
+      files,
+      activeFile,
+      title,
+      kind,
+      services,
+      showGuide,
+      guideDone,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Persist the current $workspace snapshot to localStorage. */
+export function saveWorkspace(): void {
+  const ws = $workspace.get();
+  if (!ws.id) return;
+  try {
+    localStorage.setItem(wsKey(ws.id, "files"), JSON.stringify(ws.files));
+    localStorage.setItem(wsKey(ws.id, "active"), ws.activeFile);
+    if (ws.title) localStorage.setItem(wsKey(ws.id, "title"), ws.title);
+    if (ws.kind) localStorage.setItem(wsKey(ws.id, "kind"), ws.kind);
+    localStorage.setItem(wsKey(ws.id, "services"), JSON.stringify(ws.services));
+    localStorage.setItem(
+      wsKey(ws.id, "guide"),
+      ws.showGuide ? "true" : "false",
+    );
+    localStorage.setItem(
+      wsKey(ws.id, "guide-done"),
+      JSON.stringify(ws.guideDone),
+    );
+  } catch {}
+}
+
+/** Remove all localStorage entries for a workspace. */
+export function clearWorkspace(id: string): void {
+  try {
+    for (const suffix of [
+      "files",
+      "active",
+      "title",
+      "kind",
+      "services",
+      "guide",
+      "guide-done",
+    ]) {
+      localStorage.removeItem(wsKey(id, suffix));
+    }
+  } catch {}
+  if ($workspace.get().id === id) {
+    $workspace.set({ ...EMPTY_WORKSPACE });
+  }
+}
+
+/**
+ * Bootstrap a brand-new workspace from an import (called from Landing page).
+ * Writes directly to localStorage and sets $workspace.
+ */
+export function createWorkspace(opts: {
+  id: string;
+  files: Record<string, string>;
+  activeFile: string;
+  title: string;
+  kind: SpecKind;
+  services: string[];
+}): void {
+  const ws: WorkspaceState = {
+    id: opts.id,
+    files: opts.files,
+    activeFile: opts.activeFile,
+    title: opts.title,
+    kind: opts.kind,
+    services: opts.services,
+    showGuide: true,
+    guideDone: [],
+  };
+  $workspace.set(ws);
+  saveWorkspace();
+}
+
+// ---------------------------------------------------------------------------
+// Draft state (non-workspace sessions)
+// ---------------------------------------------------------------------------
+
+const DRAFT_KEY = "ec-compass-draft";
+const DRAFT_ACTIVE_KEY = "ec-compass-draft-active";
+const LEGACY_DRAFT_KEY = "ec-canvas-draft";
+const LEGACY_ACTIVE_KEY = "ec-canvas-draft-active";
+
+export interface DraftState {
+  files: Record<string, string>;
+  activeFile: string;
+}
+
+export const $draft = atom<DraftState | null>(null);
+
+/** Load a non-workspace draft from localStorage. Returns true if found. */
+export function loadDraft(): boolean {
+  try {
+    const raw =
+      localStorage.getItem(DRAFT_KEY) ?? localStorage.getItem(LEGACY_DRAFT_KEY);
+    if (!raw) return false;
+    const files = JSON.parse(raw);
+    if (!files || typeof files !== "object" || Object.keys(files).length === 0)
+      return false;
+
+    const activeFile =
+      localStorage.getItem(DRAFT_ACTIVE_KEY) ??
+      localStorage.getItem(LEGACY_ACTIVE_KEY) ??
+      Object.keys(files)[0];
+
+    // Migrate legacy keys
+    localStorage.setItem(DRAFT_KEY, JSON.stringify(files));
+    localStorage.setItem(DRAFT_ACTIVE_KEY, activeFile);
+
+    $draft.set({ files, activeFile });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Persist draft to localStorage. */
+export function saveDraft(
+  files: Record<string, string>,
+  activeFile: string,
+): void {
+  try {
+    localStorage.setItem(DRAFT_KEY, JSON.stringify(files));
+    localStorage.setItem(DRAFT_ACTIVE_KEY, activeFile);
+    $draft.set({ files, activeFile });
+  } catch {}
+}
+
+/** Remove draft from localStorage. */
+export function clearDraft(): void {
+  try {
+    localStorage.removeItem(DRAFT_KEY);
+    localStorage.removeItem(DRAFT_ACTIVE_KEY);
+    localStorage.removeItem(LEGACY_DRAFT_KEY);
+    localStorage.removeItem(LEGACY_ACTIVE_KEY);
+  } catch {}
+  $draft.set(null);
+}
+
+// ---------------------------------------------------------------------------
+// Peek helpers (read from localStorage without updating stores)
+// ---------------------------------------------------------------------------
+
+/** Read draft files+activeFile from localStorage without updating the $draft store. */
+export function peekDraft(): DraftState | null {
+  try {
+    const raw =
+      localStorage.getItem(DRAFT_KEY) ?? localStorage.getItem(LEGACY_DRAFT_KEY);
+    if (!raw) return null;
+    const files = JSON.parse(raw);
+    if (!files || typeof files !== "object" || Object.keys(files).length === 0)
+      return null;
+    const activeFile =
+      localStorage.getItem(DRAFT_ACTIVE_KEY) ??
+      localStorage.getItem(LEGACY_ACTIVE_KEY) ??
+      Object.keys(files)[0];
+    return { files, activeFile };
+  } catch {
+    return null;
+  }
+}
+
+/** Read workspace files+activeFile from localStorage without updating the $workspace store. */
+export function peekWorkspaceFiles(
+  id: string,
+): { files: Record<string, string>; activeFile: string } | null {
+  try {
+    const raw = localStorage.getItem(wsKey(id, "files"));
+    if (!raw) return null;
+    const files = JSON.parse(raw);
+    if (!files || typeof files !== "object" || Object.keys(files).length === 0)
+      return null;
+    const activeFile =
+      localStorage.getItem(wsKey(id, "active")) ?? Object.keys(files)[0];
+    return { files, activeFile };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function jsonParse<T>(raw: string | null, fallback: T): T {
+  if (!raw) return fallback;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+/** Derive the first non-.ec filename from workspace files (the spec file). */
+export function getSpecFile(files: Record<string, string>): string {
+  const specFiles = Object.keys(files).filter((f) => !f.endsWith(".ec"));
+  return specFiles[0] ?? "spec.yml";
+}
diff --git a/packages/playground/src/utils/analytics.ts b/packages/playground/src/utils/analytics.ts
new file mode 100644
index 000000000..4b1cb0442
--- /dev/null
+++ b/packages/playground/src/utils/analytics.ts
@@ -0,0 +1,13 @@
+/** Thin wrapper around the PostHog global so call-sites stay clean. */
+
+declare global {
+  interface Window {
+    posthog?: {
+      capture: (event: string, properties?: Record<string, unknown>) => void;
+    };
+  }
+}
+
+export function track(event: string, properties?: Record<string, unknown>) {
+  window.posthog?.capture(event, properties);
+}
diff --git a/packages/playground/src/utils/catalog-export.ts b/packages/playground/src/utils/catalog-export.ts
new file mode 100644
index 000000000..bce49e00c
--- /dev/null
+++ b/packages/playground/src/utils/catalog-export.ts
@@ -0,0 +1,100 @@
+import type { CompiledFile } from '../hooks/useDslParser';
+
+const VERSIONED_INDEX_MD_PATH = /^(.*)\/versioned\/([^/]+)\/index\.md$/;
+const ROOT_INDEX_MD_PATH = /^(.*)\/index\.md$/;
+const VERSION_COLLATOR = new Intl.Collator(undefined, {
+  numeric: true,
+  sensitivity: 'base',
+});
+const RESOURCE_HELP_TEXT = '*You can add any markdown in this file to help your teams get more context about this resource.*';
+
+function toMdxPath(path: string): string {
+  return path.endsWith('.md') ? `${path.slice(0, -3)}.mdx` : path;
+}
+
+function compareVersions(a: string, b: string): number {
+  return VERSION_COLLATOR.compare(a, b);
+}
+
+function withResourceGuidance(path: string, content: string): string {
+  if (!path.endsWith('/index.mdx')) return content;
+
+  const hasNodeGraph = content.includes('<NodeGraph/>') || content.includes('<NodeGraph />');
+  const hasGuidance = content.includes(RESOURCE_HELP_TEXT);
+
+  let nextContent = content.trimEnd();
+  if (!hasNodeGraph) {
+    nextContent += '\n\n<NodeGraph/>';
+  }
+  if (!hasGuidance) {
+    nextContent += `\n\n${RESOURCE_HELP_TEXT}`;
+  }
+
+  return `${nextContent}\n`;
+}
+
+/**
+ * Compiler output writes versioned resources as ".../versioned/<version>/index.md".
+ * For catalog export zip files we want CLI-like structure:
+ * - latest version at ".../index.mdx"
+ * - older versions under ".../versioned/<version>/index.mdx"
+ * - md files converted to mdx
+ */
+export function normalizeCompiledCatalogFiles(compiled: CompiledFile[]): CompiledFile[] {
+  const rootsByBase = new Set<string>();
+  const versionedByBase = new Map<string, string[]>();
+
+  for (const file of compiled) {
+    const versionedMatch = file.path.match(VERSIONED_INDEX_MD_PATH);
+    if (versionedMatch) {
+      const [, basePath, version] = versionedMatch;
+      const versions = versionedByBase.get(basePath);
+      if (versions) {
+        versions.push(version);
+      } else {
+        versionedByBase.set(basePath, [version]);
+      }
+      continue;
+    }
+
+    const rootMatch = file.path.match(ROOT_INDEX_MD_PATH);
+    if (rootMatch) {
+      rootsByBase.add(rootMatch[1]);
+    }
+  }
+
+  const latestVersionByBase = new Map<string, string>();
+  for (const [basePath, versions] of versionedByBase) {
+    if (rootsByBase.has(basePath) || versions.length === 0) continue;
+
+    let latest = versions[0];
+    for (let i = 1; i < versions.length; i++) {
+      if (compareVersions(versions[i], latest) > 0) {
+        latest = versions[i];
+      }
+    }
+    latestVersionByBase.set(basePath, latest);
+  }
+
+  const normalized = new Map<string, CompiledFile>();
+
+  for (const file of compiled) {
+    const versionedMatch = file.path.match(VERSIONED_INDEX_MD_PATH);
+    if (versionedMatch) {
+      const [, basePath, version] = versionedMatch;
+      const hasRoot = rootsByBase.has(basePath);
+      const latestVersion = latestVersionByBase.get(basePath);
+      const path =
+        !hasRoot && latestVersion === version
+          ? `${basePath}/index.mdx`
+          : `${basePath}/versioned/${version}/index.mdx`;
+      normalized.set(path, { ...file, path, content: withResourceGuidance(path, file.content) });
+      continue;
+    }
+
+    const path = toMdxPath(file.path);
+    normalized.set(path, { ...file, path, content: withResourceGuidance(path, file.content) });
+  }
+
+  return Array.from(normalized.values());
+}
diff --git a/packages/playground/src/utils/zip.ts b/packages/playground/src/utils/zip.ts
new file mode 100644
index 000000000..e3a8ce3c0
--- /dev/null
+++ b/packages/playground/src/utils/zip.ts
@@ -0,0 +1,122 @@
+interface ZipFile {
+  name: string;
+  content: string;
+}
+
+const CRC32_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let j = 0; j < 8; j++) {
+      c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+    }
+    table[i] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(data: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (let i = 0; i < data.length; i++) {
+    crc = CRC32_TABLE[(crc ^ data[i]) & 0xff] ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function writeU16(value: number): Uint8Array {
+  const out = new Uint8Array(2);
+  out[0] = value & 0xff;
+  out[1] = (value >>> 8) & 0xff;
+  return out;
+}
+
+function writeU32(value: number): Uint8Array {
+  const out = new Uint8Array(4);
+  out[0] = value & 0xff;
+  out[1] = (value >>> 8) & 0xff;
+  out[2] = (value >>> 16) & 0xff;
+  out[3] = (value >>> 24) & 0xff;
+  return out;
+}
+
+function concatBytes(chunks: Uint8Array[]): Uint8Array {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}
+
+export function createZipBlob(files: ZipFile[]): Blob {
+  const encoder = new TextEncoder();
+  const localChunks: Uint8Array[] = [];
+  const centralChunks: Uint8Array[] = [];
+  let localOffset = 0;
+
+  for (const file of files) {
+    const nameBytes = encoder.encode(file.name);
+    const dataBytes = encoder.encode(file.content);
+    const checksum = crc32(dataBytes);
+
+    const localHeader = concatBytes([
+      writeU32(0x04034b50),
+      writeU16(20), // version needed
+      writeU16(0), // flags
+      writeU16(0), // compression (store)
+      writeU16(0), // mod time
+      writeU16(0), // mod date
+      writeU32(checksum),
+      writeU32(dataBytes.length),
+      writeU32(dataBytes.length),
+      writeU16(nameBytes.length),
+      writeU16(0), // extra length
+      nameBytes,
+      dataBytes,
+    ]);
+
+    localChunks.push(localHeader);
+
+    const centralHeader = concatBytes([
+      writeU32(0x02014b50),
+      writeU16(20), // version made by
+      writeU16(20), // version needed
+      writeU16(0), // flags
+      writeU16(0), // compression
+      writeU16(0), // mod time
+      writeU16(0), // mod date
+      writeU32(checksum),
+      writeU32(dataBytes.length),
+      writeU32(dataBytes.length),
+      writeU16(nameBytes.length),
+      writeU16(0), // extra length
+      writeU16(0), // comment length
+      writeU16(0), // disk number start
+      writeU16(0), // internal attrs
+      writeU32(0), // external attrs
+      writeU32(localOffset),
+      nameBytes,
+    ]);
+
+    centralChunks.push(centralHeader);
+    localOffset += localHeader.length;
+  }
+
+  const localData = concatBytes(localChunks);
+  const centralData = concatBytes(centralChunks);
+  const endRecord = concatBytes([
+    writeU32(0x06054b50),
+    writeU16(0), // disk number
+    writeU16(0), // central dir start disk
+    writeU16(files.length),
+    writeU16(files.length),
+    writeU32(centralData.length),
+    writeU32(localData.length),
+    writeU16(0), // comment length
+  ]);
+
+  const archive = concatBytes([localData, centralData, endRecord]);
+  return new Blob([archive], { type: 'application/zip' });
+}
diff --git a/packages/playground/src/vite-env.d.ts b/packages/playground/src/vite-env.d.ts
new file mode 100644
index 000000000..11f02fe2a
--- /dev/null
+++ b/packages/playground/src/vite-env.d.ts
@@ -0,0 +1 @@
+/// <reference types="vite/client" />
diff --git a/packages/playground/tsconfig.json b/packages/playground/tsconfig.json
new file mode 100644
index 000000000..7529dafe1
--- /dev/null
+++ b/packages/playground/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "jsx": "react-jsx",
+    "declaration": false,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/playground/vercel.json b/packages/playground/vercel.json
new file mode 100644
index 000000000..74f3836d4
--- /dev/null
+++ b/packages/playground/vercel.json
@@ -0,0 +1,17 @@
+{
+  "ignoreCommand": "exit 0",
+  "rewrites": [
+    {
+      "source": "/docs",
+      "destination": "https://compass-docs-liart.vercel.app/"
+    },
+    {
+      "source": "/docs/(.*)",
+      "destination": "https://compass-docs-liart.vercel.app/$1"
+    },
+    {
+      "source": "/(.*)",
+      "destination": "/index.html"
+    }
+  ]
+}
diff --git a/packages/playground/vite.config.ts b/packages/playground/vite.config.ts
new file mode 100644
index 000000000..951e621a2
--- /dev/null
+++ b/packages/playground/vite.config.ts
@@ -0,0 +1,41 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+import fs from 'fs';
+
+// Resolve .js imports to .ts files in the language source directory
+function resolveJsToTs() {
+  const srcDirs = [
+    path.resolve(__dirname, '../language-server/src'),
+  ];
+  return {
+    name: 'resolve-js-to-ts',
+    resolveId(source: string, importer: string | undefined) {
+      if (!importer || !source.endsWith('.js')) return null;
+      const importerDir = path.dirname(importer);
+      if (!srcDirs.some(d => importerDir.startsWith(d))) return null;
+      const tsPath = path.resolve(importerDir, source.replace(/\.js$/, '.ts'));
+      if (fs.existsSync(tsPath)) return tsPath;
+      return null;
+    },
+  };
+}
+
+export default defineConfig({
+  plugins: [resolveJsToTs(), react()],
+  resolve: {
+    alias: {
+      '@eventcatalog/language-server/browser': path.resolve(__dirname, '../language-server/src/browser.ts'),
+      '@eventcatalog/language-server': path.resolve(__dirname, '../language-server/src/index.ts'),
+      '@eventcatalog/visualiser/styles.css': path.resolve(__dirname, '../visualiser/dist/styles.css'),
+      '@eventcatalog/visualiser': path.resolve(__dirname, '../visualiser/src/index.ts'),
+    },
+  },
+  build: {
+    rollupOptions: {
+      // catalog.ts dynamically imports the SDK which is Node.js-only.
+      // Externalize it so Rollup doesn't try to bundle it for the browser.
+      external: ['@eventcatalog/sdk'],
+    },
+  },
+});
diff --git a/packages/sdk/.gitignore b/packages/sdk/.gitignore
new file mode 100644
index 000000000..720f45d91
--- /dev/null
+++ b/packages/sdk/.gitignore
@@ -0,0 +1,7 @@
+dist/
+node_modules/
+todo.js
+eventcatalog.json
+.DS_Store
+.claude/commands
+.claude/agents
\ No newline at end of file
diff --git a/packages/sdk/.prettierignore b/packages/sdk/.prettierignore
new file mode 100644
index 000000000..b07a2c5c2
--- /dev/null
+++ b/packages/sdk/.prettierignore
@@ -0,0 +1,4 @@
+dist
+node_modules
+pnpm-lock.yaml
+.changeset/*
\ No newline at end of file
diff --git a/packages/sdk/.prettierrc b/packages/sdk/.prettierrc
new file mode 100644
index 000000000..2fbe55cde
--- /dev/null
+++ b/packages/sdk/.prettierrc
@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "printWidth": 130,
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true
+}
diff --git a/packages/sdk/CHANGELOG.md b/packages/sdk/CHANGELOG.md
new file mode 100644
index 000000000..69c10f492
--- /dev/null
+++ b/packages/sdk/CHANGELOG.md
@@ -0,0 +1,898 @@
+# @eventcatalog/sdk
+
+## 2.25.0
+
+### Minor Changes
+
+- d64cfab: Add systems support to the SDK. Systems are a new resource type that can group services, flows, entities, and containers, and can be nested within domains. Includes helpers to read and write systems, add resources to a system, write resources directly into a system, and add systems to domains.
+
+### Patch Changes
+
+- 9949f9f: Add SDK support for architecture decision records.
+
+## 2.25.0-beta.1
+
+### Patch Changes
+
+- 9949f9f: Add SDK support for architecture decision records.
+
+## 2.25.0-beta.0
+
+### Minor Changes
+
+- d64cfab: Add systems support to the SDK. Systems are a new resource type that can group services, flows, entities, and containers, and can be nested within domains. Includes helpers to read and write systems, add resources to a system, write resources directly into a system, and add systems to domains.
+
+## 2.24.2
+
+### Patch Changes
+
+- 29dc055: Expose `getResources` utility on the SDK for fetching catalog resources by type
+
+## 2.24.1
+
+### Patch Changes
+
+- 3334ab1: Add Microsoft Entra directory connector for syncing users and teams from Microsoft Entra ID (Azure AD).
+  - `@eventcatalog/connectors`: new `microsoftEntraDirectory` connector export and docs
+  - `@eventcatalog/sdk`: `Team`/`User` source now supports an optional `id`, and `User.avatarUrl` is now optional
+  - `@eventcatalog/core`: render the Microsoft Entra directory source badge with an Azure icon
+
+## 2.24.0
+
+### Minor Changes
+
+- 6b7fc3c: Add directory connectors for syncing users and teams from external sources (e.g. GitHub organizations) into EventCatalog collections. Introduces the new `@eventcatalog/connectors` package and `directory.sources` configuration in `eventcatalog.config`.
+
+## 2.23.1
+
+### Patch Changes
+
+- 2801b3e: Fix `addMessageToChannel` (and its `addEventToChannel` / `addCommandToChannel` / `addQueryToChannel` bindings) corrupting catalog layout.
+
+  The function previously split the existing resource path with a template _string_ — `` `/[\\/]+${collection}` `` — instead of a real `RegExp`. The literal substring never matched real paths, so `.split()` returned the input unchanged and the resource was rewritten under `<catalog>/<collection>/<id>/index.mdx/<collection>/<id>/index.mdx`, with `index.mdx` becoming a directory.
+
+  The fix mirrors the regex form already used in `services.ts` (`new RegExp('[\\\\/]+' + collection)`), so the split matches both POSIX and Windows path separators. A regression test under `addEventToChannel` asserts that the canonical event path stays a file and the duplicate nested path does not exist.
+
+## 2.23.0
+
+### Minor Changes
+
+- 3ad00ad: Add SDK support for agent resources, including agent CRUD helpers, message/data-store/flow relationships, and flow/message writes under agents.
+
+## 2.22.0
+
+### Minor Changes
+
+- 50b38f6: Add agents as a first-class resource type. Agents can now be documented alongside services, with support for AI model metadata, tools (MCP servers, APIs), and rendered as distinct nodes in the visualiser. Closes #2564.
+
+## 2.21.2
+
+### Patch Changes
+
+- 67940c4: Add optional `url` support to badges so they can render as clickable links.
+
+## 2.21.1
+
+### Patch Changes
+
+- 1c9c217: Add support for `container` and `dataProduct` steps in flows. Flows can now reference data stores (containers) and data products directly as steps, rendered in the flow node graph and sidebar. SDK adds `addDataStoreStep`, `addContainerStep`, and `addDataProductStep` builders.
+
+## 2.21.0
+
+### Minor Changes
+
+- 3a7b096: Add SDK support for writing flow resources and a fluent `FlowBuilder` API for creating flows from code.
+
+## 2.20.0
+
+### Minor Changes
+
+- 8f724a7: feat: add `externalSystem` flag to services for modelling third-party integrations
+
+  Services can now set `externalSystem: true` in their frontmatter to be rendered as external systems. This changes their presentation without changing their capabilities — they still send and receive messages, have owners, and support specifications like any other service.
+  - Visualiser: external services render purple with a Globe icon and an "External System" badge
+  - Sidebar (root): a dedicated "External Systems" section lists externals; the regular "Services" section excludes them
+  - Sidebar (domain): externals appear under a new "External Integrations" group, separate from "Services In Domain"
+  - Per-service nav badge reads "External System" instead of "Service"
+  - `/discover`: a new "External Systems" tab alongside the "Services" tab
+  - SDK: the `Service` type now accepts `externalSystem?: boolean`
+
+## 2.19.0
+
+### Minor Changes
+
+- 52b4f24: Add `group` field to SendsPointer and ReceivesPointer types, enabling SDK consumers to assign messages to named groups for visualiser grouping
+
+## 2.18.4
+
+### Patch Changes
+
+- ee142e4: Add missing properties to SDK types: flows on Service and Domain, deliveryGuarantee/parameters/attachments on Channel
+
+## 2.18.3
+
+### Patch Changes
+
+- 88795d0: Add entities, containers, and flows to dumpCatalog and add getFlow/getFlows SDK functions
+
+## 2.18.2
+
+### Patch Changes
+
+- 4639ec3: fix(sdk): handle subdomains/ folder convention in resolveDomainWriteDirectory
+
+## 2.18.1
+
+### Patch Changes
+
+- e2b0460: fix(sdk): preserve subdomain path when adding resources to a domain
+
+## 2.18.0
+
+### Minor Changes
+
+- 913ca20: feat: add field-level usage tracking for message consumers
+
+  Services and domains can now declare which specific fields they depend on in their `receives` (and `sends`) pointers using an optional `fields` array. When declared, a new Field Usage page appears in the message sidebar showing all schema properties alongside their consumers. Supports JSON Schema, Avro, and Protobuf schemas. Includes detection of fields declared by consumers that don't exist in the schema.
+
+## 2.17.4
+
+### Patch Changes
+
+- 83aca74: add usage examples support for messages in schema explorer with optional config metadata
+
+## 2.17.3
+
+### Patch Changes
+
+- 46a2292: Add schema_changed governance trigger and improve snapshot handling
+
+## 2.17.2
+
+### Patch Changes
+
+- 0514bb1: fix(sdk): adding resources to services no longer deletes other resources in the folder directory
+
+## 2.17.1
+
+### Patch Changes
+
+- 6456054: Fix schema API returning empty response in SSR mode and add getSchemaForMessage SDK function
+
+## 2.17.0
+
+### Minor Changes
+
+- af2d4f4: add architecture change detection with governance rules, catalog snapshots, and webhook notifications
+
+## 2.16.0
+
+### Minor Changes
+
+- 283c147: Add changelog SDK methods: writeChangelog, appendChangelog, getChangelog, and rmChangelog to programmatically manage changelog entries for any resource
+
+## 2.15.1
+
+### Patch Changes
+
+- b5bbb3d: Add operation type to Event, Command, and Query interfaces in the SDK
+
+## 2.15.0
+
+### Minor Changes
+
+- 7531be8: Hydrate containers in service DSL export and rename playground to EventCatalog Canvas
+- a1c5012: Add versioned message references (event, command, query) in visualizer blocks and hydrate related services in domain DSL export
+
+### Patch Changes
+
+- 25acfdd: Add channel route support in DSL export, resolve semver ranges to concrete versions, hydrate related services and upstream/downstream channels
+
+## 2.14.3
+
+### Patch Changes
+
+- f3685b6: upgrade glob dependency from v11 to v13
+
+## 2.14.2
+
+### Patch Changes
+
+- 6a4e582: Improve DSL import with container ref support, resource stubs, and cache upsert; add writes-to and reads-from compilation in the language server.
+
+## 2.14.1
+
+### Patch Changes
+
+- 69cb966: add in-memory file index cache to SDK for faster lookups, fix playground URL in CLI export
+
+## 2.14.0
+
+### Minor Changes
+
+- c782129: Add CLI export command for exporting catalog resources to EventCatalog DSL (.ec) format. Supports single resource, bulk, and full catalog export with hydration, section grouping, and visualizer blocks. Fix getServices to ignore nested channels, containers, data-products, data-stores, and flows.
+- c782129: feat(cli): add export command for DSL (.ec) format
+
+## 2.13.2
+
+### Patch Changes
+
+- b466daf: fix: add build step to release workflow to ensure dist/ is included in published packages
+
+## 2.13.1
+
+### Patch Changes
+
+- 0b35904: Extract CLI into new @eventcatalog/cli package for cleaner separation of concerns. The SDK no longer bundles the CLI binary.
+
+## 2.13.0
+
+### Minor Changes
+
+- 19696f3: migrate sdk and create-eventcatalog packages into monorepo
+
+## 2.13.0-beta.0
+
+### Minor Changes
+
+- 19696f3: migrate sdk and create-eventcatalog packages into monorepo
+
+## 2.12.1
+
+### Patch Changes
+
+- aff77e3: feat: add diagrams collection support to SDK
+
+## 2.12.0
+
+### Minor Changes
+
+- 53feaf4: Add CLI interface to execute SDK functions from the command line
+- 0d86505: feat(sdk): added CLI interface for SDK
+
+## 2.11.0
+
+### Minor Changes
+
+- 0859ebb: Add sends and receives support to domains, allowing domains to directly document event flows with addEventToDomain, addCommandToDomain, and addQueryToDomain functions
+
+### Patch Changes
+
+- 76482a4: feat(sdk): added data product support to sdk
+
+## 2.10.0
+
+### Minor Changes
+
+- 2854c62: feat(sdk): added diagram types to base schema
+
+## 2.9.11
+
+### Patch Changes
+
+- 2480c01: fix(sdk): removed jsdocs links to old documentation links
+
+## 2.9.10
+
+### Patch Changes
+
+- e7bbb0a: fix(sdk): ensure directory when writing resources
+
+## 2.9.9
+
+### Patch Changes
+
+- 083ec77: feat(core): writing resources allows path override
+
+## 2.9.8
+
+### Patch Changes
+
+- 658d41c: feat(core): writing resources allows path override
+
+## 2.9.7
+
+### Patch Changes
+
+- b4d25c4: fix(sdk): fixed path finding for windows when versioning resources
+
+## 2.9.6
+
+### Patch Changes
+
+- bac2293: chore(core): updated packages
+
+## 2.9.5
+
+### Patch Changes
+
+- a02abd9: chore(code): moving to npm OIDC
+
+## 2.9.4
+
+### Patch Changes
+
+- 79cbb47: chore(code): moving to npm OIDC
+
+## 2.9.3
+
+### Patch Changes
+
+- f208149: chore(sdk): testing release
+
+## 2.9.2
+
+### Patch Changes
+
+- b6762c6: feat(sdk): added routes to channels
+
+## 2.9.1
+
+### Patch Changes
+
+- 835d5f7: feat(sdk): added to and from for channels for services
+
+## 2.9.0
+
+### Minor Changes
+
+- 1bf7167: fix(sdk): version checking now works with non semver versions
+
+## 2.8.4
+
+### Patch Changes
+
+- ea6e8d4: feat(sdk): added new function to get folder name by resource
+
+## 2.8.3
+
+### Patch Changes
+
+- dbf4816: feat(sdk): added ability to add datatore to service
+
+## 2.8.2
+
+### Patch Changes
+
+- 765d008: feat(sdk): added support to write containers(data-stores) to eventcat…
+
+## 2.8.1
+
+### Patch Changes
+
+- 4aa95df: feat(sdk): added support to write containers(data-stores) to eventcatalog
+
+## 2.8.0
+
+### Minor Changes
+
+- 8c29fb2: fix(sdk): fixed nested versioning side effects
+
+## 2.7.6
+
+### Patch Changes
+
+- 6c6fde8: feat(core): added support for graphql specs in EventCatalog
+
+## 2.7.5
+
+### Patch Changes
+
+- fdf463d: feat(sdk): added attachment types to all supported resources
+
+## 2.7.4
+
+### Patch Changes
+
+- 0bb05fc: chore(sdk): added detail panel types to resources
+
+## 2.7.3
+
+### Patch Changes
+
+- 817998c: fix(sdk): fixed race condition with removing services and all its files
+
+## 2.7.2
+
+### Patch Changes
+
+- 7417a02: fix(sdk): fixed race condition with removing services and all its files
+
+## 2.7.1
+
+### Patch Changes
+
+- 7707aad: feat(sdk): added entity SDK
+
+## 2.7.0
+
+### Minor Changes
+
+- 7e402f0: feat(sdk): added entity SDK
+
+## 2.6.9
+
+### Patch Changes
+
+- 315ff4c: chore(sdk): added editUrl and draft properties on all resources
+
+## 2.6.8
+
+### Patch Changes
+
+- 7a766aa: feat(sdk): added new functions to get producers/consumers by schema
+
+## 2.6.7
+
+### Patch Changes
+
+- 42c9d85: feat(sdk): added new function to convert file to service
+
+## 2.6.6
+
+### Patch Changes
+
+- c57d2f7: feat(sdk): added new function to convert file to service
+
+## 2.6.5
+
+### Patch Changes
+
+- 5f64b2e: feat(sdk): added new functions to get owners of resources and service…
+
+## 2.6.4
+
+### Patch Changes
+
+- a801c8a: Updates the string search split for forward or backward path separators
+- 8515f90: fix(sdk): fixed issue with broken path seperators for windows/linux
+
+## 2.6.3
+
+### Patch Changes
+
+- c4f661c: fix(sdk): getting producers and consumers for a message, now supports latestOnly flag
+
+## 2.6.2
+
+### Patch Changes
+
+- 450d2b3: fix(sdk): fixed issue getting producers and consumers for messages
+
+## 2.6.1
+
+### Patch Changes
+
+- 96bafa2: fix(sdk): getting messages by path now uses catalog directory
+
+## 2.6.0
+
+### Minor Changes
+
+- cbe2e80: feat(sdk): added new functions for messages
+
+## 2.5.5
+
+### Patch Changes
+
+- cb82968: fix(sdk): searching resources by id now escapes special characters
+
+## 2.5.4
+
+### Patch Changes
+
+- 05f5156: fix(sdk): when dumping catalog resources are defaulted empty
+
+## 2.5.3
+
+### Patch Changes
+
+- 6f6a38e: chore(sdk): now export eventcatalog type
+
+## 2.5.2
+
+### Patch Changes
+
+- 13aee9d: fix(sdk): get domains no longer returns entities
+
+## 2.5.1
+
+### Patch Changes
+
+- a0dc38c: feat(sdk): added new function to get eventcatalog config file
+
+## 2.5.0
+
+### Minor Changes
+
+- ec3bebb: chore(sdk): export types
+
+## 2.4.0
+
+### Minor Changes
+
+- 099fcd8: feat(sdk): added ability to fetch schemas
+
+## 2.3.7
+
+### Patch Changes
+
+- d977d24: feat(sdk): added util function to get a path to a resource
+
+## 2.3.6
+
+### Patch Changes
+
+- f1ad57f: chore(sdk): sdk now formats JSON files before writing them
+
+## 2.3.5
+
+### Patch Changes
+
+- 90c6897: chore(sdk): sdk now formats JSON files before writing them
+
+## 2.3.4
+
+### Patch Changes
+
+- 5427184: feat(sdk): when adding services to domains you can override the service
+
+## 2.3.3
+
+### Patch Changes
+
+- c99feda: feat(sdk): added override flag for writing messages to services
+
+## 2.3.2
+
+### Patch Changes
+
+- 86cd6c4: feat(sdk): added missing docs for addSubDomainToDomain
+
+## 2.3.1
+
+### Patch Changes
+
+- cd4cfdd: feat(sdk): introduced subdomain sdk functions
+
+## 2.3.0
+
+### Minor Changes
+
+- aef0e28: chore(sdk): fix(sdk): fix SDK on windows, also added window tests
+
+## 2.2.10
+
+### Patch Changes
+
+- d2bc29c: feat(sdk): added backwards compatibility for md files
+
+## 2.2.9
+
+### Patch Changes
+
+- 574b95e: feat(sdk): added backwards compatibility for md files
+
+## 2.2.8
+
+### Patch Changes
+
+- 57a4f19: feat(sdk): added backwards compatibility for md files
+
+## 2.2.7
+
+### Patch Changes
+
+- 43d9243: fix(sdk): fixed small bug when getting resources could return resources it should not
+
+## 2.2.6
+
+### Patch Changes
+
+- e2f7a36: feat(sdk): deprecation field now supports booleans
+
+## 2.2.5
+
+### Patch Changes
+
+- eed1aa7: feat(sdk): added support for deprecated fields
+
+## 2.2.4
+
+### Patch Changes
+
+- b5ad42d: chore(sdk): updated types for new styles on resources
+
+## 2.2.3
+
+### Patch Changes
+
+- 03539b9: fix(sdk): eventcatalog version ignored if not found on dump
+
+## 2.2.2
+
+### Patch Changes
+
+- 66dbc09: fix(sdk): new build
+
+## 2.2.1
+
+### Patch Changes
+
+- dac1e6e: fix(sdk): teams and users now use mdx file formats
+
+## 2.2.0
+
+### Minor Changes
+
+- 8ea729b: fix(core): fixed problem adding messages to services when in domains
+
+### Patch Changes
+
+- 16d5c4b: fix(sdk): Allow nullable version for xxxHasVersion methods
+
+## 2.1.2
+
+### Patch Changes
+
+- 869968b: feat(core): added ability to get ubiquitous lang from domain
+
+## 2.1.1
+
+### Patch Changes
+
+- b9b32d6: feat(core): added custom docs sdk support
+
+## 2.1.0
+
+### Minor Changes
+
+- 8412445: feat(core): added custom docs sdk support
+
+## 2.0.1
+
+### Patch Changes
+
+- fd0327a: feat(sdk): added ability to add sidebar badges
+
+## 2.0.0
+
+### Major Changes
+
+- d3c428a: chore(sdk): moving to mdx files
+
+## 1.4.9
+
+### Patch Changes
+
+- dbd4fd4: fix(sdk): getDomains no longer returns flows
+
+## 1.4.8
+
+### Patch Changes
+
+- a443869: chore(fix): fixed async issues when writing services
+
+## 1.4.7
+
+### Patch Changes
+
+- 24f7848: chore(fix): fixed async issues when writing services (trying lock files)
+
+## 1.4.6
+
+### Patch Changes
+
+- 5494a42: chore(fix): fixed async issues when writing files
+
+## 1.4.5
+
+### Patch Changes
+
+- ae82880: chore(fix): fixed async issues when writing services
+
+## 1.4.4
+
+### Patch Changes
+
+- 212023e: fix(sdk): fixed issue with persisting files between versioning for do…
+
+## 1.4.3
+
+### Patch Changes
+
+- d9b7d03: chore(sdk): added repoistory on base schema for resources
+
+## 1.4.2
+
+### Patch Changes
+
+- e125e38: fix(sdk): removing resources now deletes file within that resource
+
+## 1.4.1
+
+### Patch Changes
+
+- 7ce9ae2: fix(sdk): issue getting resources in nested folder structures
+
+## 1.4.0
+
+### Minor Changes
+
+- 30822e8: feat(sdk): adding team and user sdk functions
+
+## 1.3.2
+
+### Patch Changes
+
+- 8f30457: feat(sdk): added ability to override resources whilst trying to versi…
+
+## 1.3.1
+
+### Patch Changes
+
+- c71efa6: fix(plugin): fixed issue when writing messages to services and folder…
+
+## 1.3.0
+
+### Minor Changes
+
+- 82e0b55: feat(sdk): added functions to get all resources in the catalog
+
+## 1.2.3
+
+### Patch Changes
+
+- 3cfb549: feat(sdk): added ability to version existing content when writing resources
+
+## 1.2.2
+
+### Patch Changes
+
+- 8dbc1ff: feat(sdk): added ability to override content when writing to catalog
+
+## 1.2.1
+
+### Patch Changes
+
+- 71d200d: chore(docs): add channel sdk to docs
+
+## 1.2.0
+
+### Minor Changes
+
+- a3cb474: feat(sdk): added channel support to sdk
+
+## 1.1.4
+
+### Patch Changes
+
+- 5e6a691: chore(sdk): added better logging for write failures
+
+## 1.1.3
+
+### Patch Changes
+
+- 0882286: fix(sdk): services are now unique when writing domains
+
+## 1.1.2
+
+### Patch Changes
+
+- d996a58: feat(sdk): added writeVersionedService function that writes a service to the versioned directory
+
+## 1.1.1
+
+### Patch Changes
+
+- ac00967: fix(sdk): added docs for query SDK
+
+## 1.1.0
+
+### Minor Changes
+
+- 95e9d70: feat(sdk): adding query sdk functions
+
+## 1.0.0
+
+### Major Changes
+
+- 7abb3d8: feat(sdk): added support for folder structures
+
+## 0.1.4
+
+### Patch Changes
+
+- b9d2073: feat(sdk): writing messages to services are now unique
+- 6a76b8d: feat(sdk): writing messages to services are now unique
+
+## 0.1.3
+
+### Patch Changes
+
+- 287912f: chore(sdk): changed the return type for getting specs for a service
+
+## 0.1.2
+
+### Patch Changes
+
+- 6d125ca: feat(sdk) added ability to get specification files for a service by it's id
+- fe4c480: fix(sdk) fixed regex to handle large names for service ids
+
+## 0.1.1
+
+### Patch Changes
+
+- c8b9d31: fix(sdk): fixed types for specifications on the service type
+
+## 0.1.0
+
+### Minor Changes
+
+- 7291e10: Adding the specification attribute to the service type letting to integrate asyncapi, openapi and other specifications in the future
+
+## 0.0.12
+
+### Patch Changes
+
+- 24ac499: feat(sdk): added ability to add services to domains
+
+## 0.0.11
+
+### Patch Changes
+
+- 177093c: feat(sdk): added methods to check if versions exist or not
+
+## 0.0.10
+
+### Patch Changes
+
+- 9129a08: feat(sdk): added support for semver matching when getting resources f…
+
+## 0.0.9
+
+### Patch Changes
+
+- 104ca2a: feat(sdk): added specific function to register an event or command to a service
+
+## 0.0.8
+
+### Patch Changes
+
+- 615d665: fix(sdk): fixed issue when getting resources by id and version
+
+## 0.0.7
+
+### Patch Changes
+
+- dd2f78e: feat(sdk): added domains to sdk
+
+## 0.0.6
+
+### Patch Changes
+
+- e925200: feat(sdk): added commands to sdk
+
+## 0.0.5
+
+### Patch Changes
+
+- e060c21: chore(sdk): refactored code to new resource internal lib
+
+## 0.0.4
+
+### Patch Changes
+
+- fcd03f6: feat(sdk): added support for services
+
+## 0.0.3
+
+### Patch Changes
+
+- e41c8af: docs(sdk): adding docs to events
+
+## 0.0.2
+
+### Patch Changes
+
+- 323eb10: fix(sdk): fixing build on github
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
new file mode 100644
index 000000000..526d5f11a
--- /dev/null
+++ b/packages/sdk/README.md
@@ -0,0 +1,57 @@
+## @eventcatalog/sdk
+
+SDK to interact with your EventCatalog programmatically in JavaScript/TypeScript.
+
+### Motivation
+
+EventCatalog vision is to integrate with any broker or technology in the world. As its powered by Markdown and contents are built at build time, you can use the SDK
+to generate these resources. For example you can integrate with your systems, create domains, services and messages for EventCatalog using this SDK.
+
+The SDK supports standard CRUD operations for domains, service and messages in EventCatalog.
+
+The SDK is useful for creating your own EventCatalog plugins and integrations.
+
+**Features**
+
+- Create, read and delete resources in EventCatalog
+- Version any resource in EventCatalog using the `version` SDK api.
+- Add files or schemas to resources in EventCatalog
+- and more...
+
+### Installation
+
+```sh
+npm i @eventcatalog/sdk
+```
+
+### Example usage
+
+```typescript
+import utils from '@eventcatalog/sdk';
+
+const { getEvent, versionEvent, getService } = utils(PATH_TO_CATALOG);
+
+// Gets event by id
+const event = await getEvent('InventoryEvent');
+
+// Gets event by id and version
+const event2 = await getEvent('InventoryEvent', '1.0.0');
+
+// Version the event InventoryEvent (e.g goes to /versioned/{version}/InventoryEvent)
+await versionEvent('InventoryEvent');
+
+// Returns the service /services/PaymentService
+const service = await getService('PaymentService');
+```
+
+### CLI
+
+Looking for command-line usage? See [@eventcatalog/cli](../cli).
+
+See the [SDK docs](https://www.eventcatalog.dev/docs/sdk) for more information and examples.
+
+# Enterprise support
+
+Interested in collaborating with us? Our offerings include dedicated support, priority assistance, feature development, custom integrations, and more.
+
+Find more details on our [services page](https://eventcatalog.dev/services).
diff --git a/packages/sdk/flow-api-proposal.md b/packages/sdk/flow-api-proposal.md
new file mode 100644
index 000000000..bfa3ce4f7
--- /dev/null
+++ b/packages/sdk/flow-api-proposal.md
@@ -0,0 +1,687 @@
+# Flow SDK API Proposal
+
+## Goal
+
+Add first-class SDK support for creating, updating, versioning, and composing EventCatalog flows.
+
+The SDK already supports reading flows with `getFlow` and `getFlows`, and the catalog already models flows as frontmatter with `steps`. The missing piece is a write API and a nicer authoring API for users who want to generate flows from code.
+
+This proposal has two layers:
+
+- A low-level resource API that mirrors the rest of the SDK.
+- A fluent `FlowBuilder` API for ergonomic flow creation.
+
+## Low-Level SDK API
+
+The SDK should expose flow helpers that match existing resource helpers for events, services, diagrams, data products, and similar resources.
+
+```ts
+const {
+  getFlow,
+  getFlows,
+  writeFlow,
+  writeVersionedFlow,
+  writeFlowToDomain,
+  writeFlowToService,
+  versionFlow,
+  rmFlow,
+  rmFlowById,
+  flowHasVersion,
+  addFileToFlow,
+} = utils('./catalog');
+```
+
+### Proposed Methods
+
+```ts
+getFlow(id: string, version?: string): Promise<Flow | undefined>
+
+getFlows(options?: { latestOnly?: boolean }): Promise<Flow[] | undefined>
+
+writeFlow(
+  flow: Flow,
+  options?: {
+    path?: string;
+    override?: boolean;
+    versionExistingContent?: boolean;
+    format?: 'md' | 'mdx';
+  }
+): Promise<void>
+
+writeVersionedFlow(flow: Flow): Promise<void>
+
+writeFlowToDomain(
+  flow: Flow,
+  domain: { id: string; version?: string },
+  options?: { path?: string; override?: boolean; format?: 'md' | 'mdx' }
+): Promise<void>
+
+writeFlowToService(
+  flow: Flow,
+  service: { id: string; version?: string },
+  options?: { path?: string; override?: boolean; format?: 'md' | 'mdx' }
+): Promise<void>
+
+versionFlow(id: string): Promise<void>
+
+rmFlow(path: string): Promise<void>
+
+rmFlowById(id: string, version?: string, persistFiles?: boolean): Promise<void>
+
+flowHasVersion(id: string, version?: string): Promise<boolean>
+
+addFileToFlow(
+  id: string,
+  file: { content: string; fileName: string },
+  version?: string
+): Promise<void>
+```
+
+## Fluent Builder API Options
+
+Users are asking for a code-first API that lets them describe flows in a readable, chained form. Any builder API should build the existing `Flow` shape rather than introducing a second model.
+
+Below are three possible fluent APIs. Option 1 is the selected MVP because it is expressive and maps cleanly to the current `FlowStep` model.
+
+Current scope:
+
+- Include Option 1 typed step methods.
+- Do not include `.connect()` yet.
+- Do not include generated catalog type support yet.
+
+## Option 1: Typed Step Builder
+
+This option exposes explicit methods for each step type: `.addStep()`, `.addMessageStep()`, `.addServiceStep()`, `.addActorStep()`, `.addExternalSystemStep()`, `.addFlowStep()`, and `.addCustomStep()`.
+
+It reads close to the current YAML/frontmatter model while giving users autocomplete and type safety for known message ids.
+
+```ts
+import utils, { FlowBuilder } from '@eventcatalog/sdk';
+
+enum ApplicationEventType {
+  HourlyCurtailmentCalculated = 'HourlyCurtailmentCalculated',
+  DailyCurtailmentCalculated = 'DailyCurtailmentCalculated',
+  MonthlyCurtailmentCalculated = 'MonthlyCurtailmentCalculated',
+}
+
+const flow = FlowBuilder.create<ApplicationEventType>({
+  id: 'CurtailmentCalculation',
+  name: 'Curtailment Calculation',
+  version: '1.0.0',
+  summary: 'Flow for calculating hourly curtailment for a customer',
+  markdown: '## Curtailment calculation\n\nGenerated from the application flow definition.',
+})
+  .addStep({
+    id: 'Calculate',
+    title: 'Calculate Hourly Curtailment',
+    summary: 'Hourly curtailment calculation is triggered by a scheduled event',
+    nextSteps: [
+      {
+        id: ApplicationEventType.HourlyCurtailmentCalculated,
+        label: 'Hourly curtailment calculated',
+      },
+    ],
+  })
+  .addMessageStep({
+    id: ApplicationEventType.HourlyCurtailmentCalculated,
+    title: 'Hourly Curtailment Calculated',
+    message: { id: ApplicationEventType.HourlyCurtailmentCalculated },
+    nextSteps: [
+      {
+        id: ApplicationEventType.DailyCurtailmentCalculated,
+        label: 'Daily curtailment recalculated',
+      },
+      {
+        id: 'SAP',
+        label: 'Send curtailment period to SAP',
+      },
+    ],
+  })
+  .addMessageStep({
+    id: ApplicationEventType.DailyCurtailmentCalculated,
+    title: 'Daily Curtailment Calculated',
+    message: { id: ApplicationEventType.DailyCurtailmentCalculated },
+    nextSteps: [
+      {
+        id: ApplicationEventType.MonthlyCurtailmentCalculated,
+        label: 'Monthly curtailment recalculated',
+      },
+    ],
+  })
+  .addMessageStep({
+    id: ApplicationEventType.MonthlyCurtailmentCalculated,
+    title: 'Monthly Curtailment Calculated',
+    message: { id: ApplicationEventType.MonthlyCurtailmentCalculated },
+  })
+  .addExternalSystemStep({
+    id: 'SAP',
+    title: 'Curtailment period registered in SAP',
+    externalSystem: {
+      name: 'SAP',
+      summary: 'SAP processed the curtailment period asynchronously.',
+    },
+    nextSteps: [{ id: 'Curtailment Rewarding' }],
+  })
+  .addStep({
+    id: 'Curtailment Rewarding',
+    title: 'Curtailment Rewarding',
+  })
+  .build();
+
+const { writeFlow } = utils('./catalog');
+
+await writeFlow(flow);
+```
+
+### Why This Option Works
+
+- Clear mapping to EventCatalog's current `FlowStep` shape.
+- Good TypeScript ergonomics with enum-backed message ids.
+- Easy to add optional metadata per step.
+- Easy to normalize `nextSteps` into `next_step` or `next_steps`.
+- Explicit method names make the flow readable in editor autocomplete.
+
+### Tradeoffs
+
+- Slightly more verbose than a pure chain API.
+- Users need to understand which step type they are adding.
+
+## Option 2: Graph Connect Builder
+
+This option separates node declaration from edge declaration. Users declare the nodes first, then connect them.
+
+This is useful when a flow is generated from another model, imported from diagrams, or assembled from data where edges are easier to reason about separately.
+
+```ts
+import utils, { FlowBuilder } from '@eventcatalog/sdk';
+
+enum ApplicationEventType {
+  HourlyCurtailmentCalculated = 'HourlyCurtailmentCalculated',
+  DailyCurtailmentCalculated = 'DailyCurtailmentCalculated',
+  MonthlyCurtailmentCalculated = 'MonthlyCurtailmentCalculated',
+}
+
+const flow = FlowBuilder.create<ApplicationEventType>({
+  id: 'CurtailmentCalculation',
+  name: 'Curtailment Calculation',
+  version: '1.0.0',
+  summary: 'Flow for calculating hourly curtailment for a customer',
+  markdown: '## Curtailment calculation',
+})
+  .step('Calculate', {
+    title: 'Calculate Hourly Curtailment',
+    summary: 'Hourly curtailment calculation is triggered by a scheduled event',
+  })
+  .message(ApplicationEventType.HourlyCurtailmentCalculated, {
+    title: 'Hourly Curtailment Calculated',
+  })
+  .message(ApplicationEventType.DailyCurtailmentCalculated, {
+    title: 'Daily Curtailment Calculated',
+  })
+  .message(ApplicationEventType.MonthlyCurtailmentCalculated, {
+    title: 'Monthly Curtailment Calculated',
+  })
+  .externalSystem('SAP', {
+    name: 'Curtailment period registered in SAP',
+    summary: 'SAP processed the curtailment period asynchronously.',
+  })
+  .step('Curtailment Rewarding')
+  .connect('Calculate', ApplicationEventType.HourlyCurtailmentCalculated, {
+    label: 'Hourly curtailment calculated',
+  })
+  .connect(ApplicationEventType.HourlyCurtailmentCalculated, ApplicationEventType.DailyCurtailmentCalculated, {
+    label: 'Daily curtailment recalculated',
+  })
+  .connect(ApplicationEventType.HourlyCurtailmentCalculated, 'SAP', {
+    label: 'Send curtailment period to SAP',
+  })
+  .connect(ApplicationEventType.DailyCurtailmentCalculated, ApplicationEventType.MonthlyCurtailmentCalculated, {
+    label: 'Monthly curtailment recalculated',
+  })
+  .connect('SAP', 'Curtailment Rewarding')
+  .build();
+
+const { writeFlow } = utils('./catalog');
+
+await writeFlow(flow);
+```
+
+### Why This Option Works
+
+- Very natural for graph-shaped data.
+- Makes branching and convergence explicit.
+- Easier to generate programmatically from external tools.
+- `.connect()` can deduplicate edges and keep step definitions focused.
+
+### Tradeoffs
+
+- More lines for hand-written flows.
+- The narrative order is less obvious because nodes and edges are split.
+- Step ids become more important because all connections reference them.
+
+## Option 3: Narrative Chain Builder
+
+This option optimizes for the most readable authoring experience. Each step call returns a chain context, and `.to()` connects the previous step to the next step.
+
+```ts
+import utils, { FlowBuilder } from '@eventcatalog/sdk';
+
+enum ApplicationEventType {
+  HourlyCurtailmentCalculated = 'HourlyCurtailmentCalculated',
+  DailyCurtailmentCalculated = 'DailyCurtailmentCalculated',
+  MonthlyCurtailmentCalculated = 'MonthlyCurtailmentCalculated',
+}
+
+const flow = FlowBuilder.create<ApplicationEventType>({
+  id: 'CurtailmentCalculation',
+  name: 'Curtailment Calculation',
+  version: '1.0.0',
+  summary: 'Flow for calculating hourly curtailment for a customer',
+  markdown: '## Curtailment calculation',
+})
+  .startWith.step('Calculate', {
+    title: 'Calculate Hourly Curtailment',
+    summary: 'Hourly curtailment calculation is triggered by a scheduled event',
+  })
+  .to.message(ApplicationEventType.HourlyCurtailmentCalculated, {
+    title: 'Hourly Curtailment Calculated',
+    label: 'Hourly curtailment calculated',
+  })
+  .branch((flow) =>
+    flow.to
+      .message(ApplicationEventType.DailyCurtailmentCalculated, {
+        title: 'Daily Curtailment Calculated',
+        label: 'Daily curtailment recalculated',
+      })
+      .to.message(ApplicationEventType.MonthlyCurtailmentCalculated, {
+        title: 'Monthly Curtailment Calculated',
+        label: 'Monthly curtailment recalculated',
+      })
+  )
+  .branch((flow) =>
+    flow.to
+      .externalSystem('SAP', {
+        name: 'Curtailment period registered in SAP',
+        summary: 'SAP processed the curtailment period asynchronously.',
+        label: 'Send curtailment period to SAP',
+      })
+      .to.step('Curtailment Rewarding')
+  )
+  .build();
+
+const { writeFlow } = utils('./catalog');
+
+await writeFlow(flow);
+```
+
+### Why This Option Works
+
+- Reads most like a business process.
+- Keeps the "what happens next" relationship close to the step itself.
+- Good for hand-authored flows where the narrative matters.
+
+### Tradeoffs
+
+- More complex to implement and type correctly.
+- Branching and convergence can become awkward for large flows.
+- The API introduces concepts like `startWith`, `to`, and `branch` that do not directly exist in the current SDK.
+
+## Recommendation
+
+Start with Option 1.
+
+That gives users a readable builder for normal hand-authored flows. Option 2 and Option 3 remain useful future ideas, but they add API surface we do not need for the first pass.
+
+## Generated Flow Shape
+
+All three builder options should return the same normal SDK `Flow`.
+
+```ts
+{
+  id: 'CurtailmentCalculation',
+  name: 'Curtailment Calculation',
+  version: '1.0.0',
+  summary: 'Flow for calculating hourly curtailment for a customer',
+  markdown: '## Curtailment calculation\n\nGenerated from the application flow definition.',
+  steps: [
+    {
+      id: 'Calculate',
+      title: 'Calculate Hourly Curtailment',
+      summary: 'Hourly curtailment calculation is triggered by a scheduled event',
+      next_step: {
+        id: 'HourlyCurtailmentCalculated',
+        label: 'Hourly curtailment calculated',
+      },
+    },
+    {
+      id: 'HourlyCurtailmentCalculated',
+      title: 'Hourly Curtailment Calculated',
+      message: {
+        id: 'HourlyCurtailmentCalculated',
+      },
+      next_steps: [
+        {
+          id: 'DailyCurtailmentCalculated',
+          label: 'Daily curtailment recalculated',
+        },
+        {
+          id: 'SAP',
+          label: 'Send curtailment period to SAP',
+        },
+      ],
+    },
+    {
+      id: 'DailyCurtailmentCalculated',
+      title: 'Daily Curtailment Calculated',
+      message: {
+        id: 'DailyCurtailmentCalculated',
+      },
+      next_step: {
+        id: 'MonthlyCurtailmentCalculated',
+        label: 'Monthly curtailment recalculated',
+      },
+    },
+    {
+      id: 'MonthlyCurtailmentCalculated',
+      title: 'Monthly Curtailment Calculated',
+      message: {
+        id: 'MonthlyCurtailmentCalculated',
+      },
+    },
+    {
+      id: 'SAP',
+      title: 'Curtailment period registered in SAP',
+      externalSystem: {
+        name: 'Curtailment period registered in SAP',
+        summary: 'SAP processed the curtailment period asynchronously.',
+      },
+      next_step: {
+        id: 'Curtailment Rewarding',
+      },
+    },
+    {
+      id: 'Curtailment Rewarding',
+      title: 'Curtailment Rewarding',
+    },
+  ],
+}
+```
+
+## Option 1 Builder Surface
+
+If we choose Option 1, the builder should have explicit methods for the flow step types EventCatalog already supports.
+
+```ts
+FlowBuilder.create<TMessageId extends string = string>(flow: FlowBuilderInput)
+
+.addStep(step: StepInput)
+
+.addMessageStep(step: MessageStepInput<TMessageId>)
+
+.addServiceStep(step: ServiceStepInput)
+
+.addActorStep(step: ActorStepInput)
+
+.addExternalSystemStep(step: ExternalSystemStepInput)
+
+.addFlowStep(step: SubFlowStepInput)
+
+.addCustomStep(step: CustomStepInput)
+
+.build(): Flow
+```
+
+## Option 1 Proposed Types
+
+```ts
+type FlowBuilderInput = Omit<Flow, 'steps'> & {
+  steps?: FlowStep[];
+};
+
+type FlowStepPointer = string | number | { id: string | number; label?: string };
+
+type StepInput = {
+  id: string | number;
+  title?: string;
+  summary?: string;
+  nextSteps?: FlowStepPointer[];
+};
+
+type MessageStepInput<TMessageId extends string = string> = StepInput & {
+  message?: { id: TMessageId; version?: string };
+  version?: string;
+};
+
+type ServiceStepInput = StepInput & {
+  service?: { id: string; version?: string };
+  version?: string;
+};
+
+type ActorStepInput = StepInput & {
+  actor?: { name: string; summary?: string };
+  name?: string;
+};
+
+type ExternalSystemStepInput = StepInput & {
+  externalSystem?: { name: string; summary?: string; url?: string };
+  name?: string;
+  url?: string;
+};
+```
+
+## Deferred: Catalog-Aware Type Generation
+
+Option 1 can become much stronger if the SDK or CLI can generate TypeScript types from an existing catalog.
+
+The goal is not runtime lookup like this:
+
+```ts
+const service = await getService('InventoryService');
+```
+
+Instead, the goal is type-level catalog awareness:
+
+```ts
+.addServiceStep({ id: 'InventoryService' })
+.addMessageStep({ id: 'HourlyCurtailmentCalculated' })
+```
+
+Those ids should autocomplete and fail at compile time when they do not exist in the generated catalog types.
+
+## Generated Catalog Types
+
+Add a command that reads the catalog and writes a generated TypeScript file.
+
+```sh
+eventcatalog generate types --output eventcatalog.generated.ts
+```
+
+Example generated file:
+
+```ts
+// eventcatalog.generated.ts
+// Generated by EventCatalog. Do not edit manually.
+
+export type EventId = 'HourlyCurtailmentCalculated' | 'DailyCurtailmentCalculated' | 'MonthlyCurtailmentCalculated';
+
+export type CommandId = 'CalculateCurtailment' | 'RegisterCurtailmentPeriod';
+
+export type QueryId = 'GetCurtailmentPeriod';
+
+export type MessageId = EventId | CommandId | QueryId;
+
+export type ServiceId = 'CurtailmentService' | 'SAP';
+
+export type FlowId = 'CurtailmentCalculation' | 'CurtailmentRewarding';
+
+export type CatalogTypes = {
+  events: EventId;
+  commands: CommandId;
+  queries: QueryId;
+  messages: MessageId;
+  services: ServiceId;
+  flows: FlowId;
+};
+```
+
+Then users can bind the builder to their catalog types:
+
+```ts
+import { FlowBuilder } from '@eventcatalog/sdk';
+import type { CatalogTypes } from './eventcatalog.generated';
+
+const flow = FlowBuilder.forCatalog<CatalogTypes>({
+  id: 'CurtailmentCalculation',
+  name: 'Curtailment Calculation',
+  version: '1.0.0',
+  markdown: '',
+})
+  .addStep({
+    id: 'Calculate',
+    nextSteps: [{ id: 'HourlyCurtailmentCalculated' }],
+  })
+  .addMessageStep({
+    id: 'HourlyCurtailmentCalculated',
+    nextSteps: [{ id: 'DailyCurtailmentCalculated' }, { id: 'SAP', label: 'Send curtailment period to SAP' }],
+  })
+  .addServiceStep({ id: 'SAP' })
+  .build();
+```
+
+This should fail at compile time:
+
+```ts
+FlowBuilder.forCatalog<CatalogTypes>({
+  id: 'CurtailmentCalculation',
+  name: 'Curtailment Calculation',
+  version: '1.0.0',
+  markdown: '',
+})
+  // Typo: not present in CatalogTypes['messages']
+  .addMessageStep({ id: 'HourlyCurtailmentCalcualted' })
+  .build();
+```
+
+## Generated Catalog Refs
+
+For a nicer authoring experience, the generator could also emit a `catalog` object.
+
+```ts
+// eventcatalog.generated.ts
+export const catalog = {
+  events: {
+    HourlyCurtailmentCalculated: 'HourlyCurtailmentCalculated',
+    DailyCurtailmentCalculated: 'DailyCurtailmentCalculated',
+    MonthlyCurtailmentCalculated: 'MonthlyCurtailmentCalculated',
+  },
+  services: {
+    CurtailmentService: 'CurtailmentService',
+    SAP: 'SAP',
+  },
+  flows: {
+    CurtailmentCalculation: 'CurtailmentCalculation',
+    CurtailmentRewarding: 'CurtailmentRewarding',
+  },
+} as const;
+```
+
+Usage:
+
+```ts
+import { FlowBuilder } from '@eventcatalog/sdk';
+import { catalog } from './eventcatalog.generated';
+import type { CatalogTypes } from './eventcatalog.generated';
+
+const flow = FlowBuilder.forCatalog<CatalogTypes>({
+  id: catalog.flows.CurtailmentCalculation,
+  name: 'Curtailment Calculation',
+  version: '1.0.0',
+  markdown: '',
+})
+  .addMessageStep({
+    id: catalog.events.HourlyCurtailmentCalculated,
+    nextSteps: [
+      { id: catalog.events.DailyCurtailmentCalculated },
+      { id: catalog.services.SAP, label: 'Send curtailment period to SAP' },
+    ],
+  })
+  .addServiceStep({ id: catalog.services.SAP })
+  .build();
+```
+
+This gives users autocomplete from real catalog ids without asking the builder to read the catalog at runtime.
+
+## Typed Ref Objects
+
+If we want stricter separation between events, services, flows, and custom steps, the generator could emit typed ref objects instead of plain strings.
+
+```ts
+export const catalog = {
+  events: {
+    HourlyCurtailmentCalculated: {
+      type: 'message',
+      id: 'HourlyCurtailmentCalculated',
+    },
+  },
+  services: {
+    SAP: {
+      type: 'service',
+      id: 'SAP',
+    },
+  },
+} as const;
+```
+
+Usage:
+
+```ts
+const flow = FlowBuilder.forCatalog<CatalogTypes>({
+  id: 'CurtailmentCalculation',
+  name: 'Curtailment Calculation',
+  version: '1.0.0',
+  markdown: '',
+})
+  .addMessageStep({
+    id: catalog.events.HourlyCurtailmentCalculated.id,
+    message: catalog.events.HourlyCurtailmentCalculated,
+    nextSteps: [
+      catalog.events.DailyCurtailmentCalculated,
+      {
+        ...catalog.services.SAP,
+        label: 'Send curtailment period to SAP',
+      },
+    ],
+  })
+  .build();
+```
+
+The builder would serialize these refs back into the existing `FlowStep` shape. No runtime catalog lookup is required.
+
+## Type Generation Design Notes
+
+- Type generation should be optional. Users can still use plain strings.
+- Generated types should be committed by users if they want stable CI type checking.
+- The generated file should include literal unions and optionally a `catalog` value for autocomplete.
+- The first version can use plain string refs. Typed ref objects can come later if we need stronger separation.
+- The builder should never need to read catalog files at runtime just to validate ids.
+- Runtime validation could still be offered separately for users who want it.
+
+## Design Notes
+
+- The builder should output the existing `Flow` type. No new persisted format is needed.
+- `nextSteps` should be the friendly API, normalized internally to `next_step` or `next_steps`.
+- Explicit methods like `.addMessageStep()`, `.addServiceStep()`, and `.addExternalSystemStep()` make the API readable and avoid overloading one generic `.addStep()` method.
+- A generic message id type lets users pass enums and get autocomplete.
+- Generated catalog types can replace hand-written enums for users who want catalog-backed ids.
+- Message steps should accept `{ version }`, but default to EventCatalog's usual latest-version behavior when omitted.
+- `.connect()` is deferred.
+- The builder should validate duplicate step ids and missing `nextSteps` references before returning the flow.
+- Flow writing should use the same `writeResource` internals as other SDK resources.
+
+## Open Questions
+
+- Should `.addMessageStep()` infer `type: 'message'`, or should the current catalog renderer continue to infer from the `message` property alone?
+- Should enum-backed message ids be typed as events only, or should the builder support separate event, command, and query enums?
+- Should `writeFlowToDomain` and `writeFlowToService` also update the parent domain/service `flows` pointer list, or only write into the nested directory?
+- Should the SDK include `flowToDSL()` later, matching the existing `toDSL()` work for other resources?
+- Should the generated `catalog` object use plain string values first, or typed ref objects from day one?
diff --git a/packages/sdk/images/example.png b/packages/sdk/images/example.png
new file mode 100644
index 000000000..ddd23dcc7
Binary files /dev/null and b/packages/sdk/images/example.png differ
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
new file mode 100644
index 000000000..b75820027
--- /dev/null
+++ b/packages/sdk/package.json
@@ -0,0 +1,58 @@
+{
+  "name": "@eventcatalog/sdk",
+  "version": "2.25.0",
+  "description": "SDK to integrate with EventCatalog",
+  "scripts": {
+    "build": "tsup",
+    "build:bin": "tsup",
+    "test": "vitest --run",
+    "test:ci": "vitest --run",
+    "format": "prettier --write .",
+    "format:diff": "prettier --list-different ."
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.14.10",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/semver": "^7.5.8",
+    "prettier": "^3.3.3",
+    "tsup": "^8.1.0",
+    "typescript": "^5.5.3",
+    "vitest": "^3.2.4"
+  },
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "exports": {
+    ".": {
+      "types": [
+        "./dist/index.d.ts",
+        "./dist/events.t.ts"
+      ],
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "fs-extra": "^11.3.2",
+    "glob": "^13.0.6",
+    "gray-matter": "^4.0.3",
+    "proper-lockfile": "^4.1.2",
+    "semver": "7.7.3",
+    "slugify": "^1.6.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/event-catalog/eventcatalog"
+  }
+}
diff --git a/packages/sdk/src/adrs.ts b/packages/sdk/src/adrs.ts
new file mode 100644
index 000000000..77187447e
--- /dev/null
+++ b/packages/sdk/src/adrs.ts
@@ -0,0 +1,55 @@
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { findFileById, invalidateFileCache } from './internal/utils';
+import type { Adr } from './types';
+import {
+  addFileToResource,
+  getResource,
+  getResources,
+  rmResourceById,
+  versionResource,
+  writeResource,
+} from './internal/resources';
+
+export const getAdr =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<Adr> =>
+    getResource(directory, id, version, { type: 'adr' }) as Promise<Adr>;
+
+export const getAdrs =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean }): Promise<Adr[]> =>
+    getResources(directory, { type: 'adrs', latestOnly: options?.latestOnly }) as Promise<Adr[]>;
+
+export const writeAdr =
+  (directory: string) =>
+  async (
+    adr: Adr,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      format: 'mdx',
+    }
+  ) =>
+    writeResource(directory, { ...adr }, { ...options, type: 'adr' });
+
+export const rmAdr = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+export const rmAdrById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) => {
+  await rmResourceById(directory, id, version, { type: 'adr', persistFiles });
+};
+
+export const versionAdr = (directory: string) => async (id: string) => versionResource(directory, id);
+
+export const adrHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+export const addFileToAdr =
+  (directory: string) =>
+  async (id: string, file: { content: string; fileName: string }, version?: string): Promise<void> =>
+    addFileToResource(directory, id, file, version, { type: 'adr' });
diff --git a/packages/sdk/src/agents.ts b/packages/sdk/src/agents.ts
new file mode 100644
index 000000000..2ce4d86ac
--- /dev/null
+++ b/packages/sdk/src/agents.ts
@@ -0,0 +1,211 @@
+import type { Agent } from './types';
+import fs from 'node:fs/promises';
+import { extname, join, relative } from 'node:path';
+import {
+  addFileToResource,
+  getResource,
+  getResourcePath,
+  getResources,
+  getVersionedDirectory,
+  rmResourceById,
+  toResource,
+  versionResource,
+  writeResource,
+} from './internal/resources';
+import { buildMessagePointer, findFileById, invalidateFileCache, uniqueVersions } from './internal/utils';
+
+const rewriteAgent = async (directory: string, id: string, agent: Agent, version?: string) => {
+  const agentPath = await getResourcePath(directory, id, version);
+
+  if (!agentPath) {
+    throw new Error(`Cannot find agent ${id} in the catalog`);
+  }
+
+  const extension = extname(agentPath.fullPath);
+
+  await rmAgentById(directory)(id, version, true);
+  await writeAgent(directory)(agent, { path: agentPath.directory, format: extension === '.md' ? 'md' : 'mdx' });
+};
+
+export const getAgent =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<Agent> =>
+    getResource(directory, id, version, { type: 'agent' }) as Promise<Agent>;
+
+export const getAgentByPath = (directory: string) => async (path: string) => {
+  const agent = await getResource(directory, undefined, undefined, { type: 'agent' }, path);
+  return agent as Agent;
+};
+
+export const getAgents =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean }): Promise<Agent[]> =>
+    getResources(directory, {
+      type: 'agents',
+      ignore: [
+        '**/events/**',
+        '**/commands/**',
+        '**/queries/**',
+        '**/entities/**',
+        '**/channels/**',
+        '**/containers/**',
+        '**/data-products/**',
+        '**/data-stores/**',
+        '**/flows/**',
+      ],
+      ...options,
+    }) as Promise<Agent[]>;
+
+export const writeAgent =
+  (directory: string) =>
+  async (
+    agent: Agent,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      format: 'mdx',
+    }
+  ) => {
+    const resource: Agent = { ...agent };
+
+    if (Array.isArray(agent.sends)) {
+      resource.sends = uniqueVersions(agent.sends as { id: string; version: string }[]);
+    }
+
+    if (Array.isArray(agent.receives)) {
+      resource.receives = uniqueVersions(agent.receives as { id: string; version: string }[]);
+    }
+
+    return await writeResource(directory, resource, { ...options, type: 'agent' });
+  };
+
+export const writeVersionedAgent = (directory: string) => async (agent: Agent) => {
+  const path = getVersionedDirectory(agent.id, agent.version);
+
+  return await writeAgent(directory)({ ...agent }, { path });
+};
+
+export const writeAgentToDomain =
+  (directory: string) =>
+  async (
+    agent: Agent,
+    domain: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    let pathForAgent =
+      domain.version && domain.version !== 'latest' ? `/${domain.id}/versioned/${domain.version}/agents` : `/${domain.id}/agents`;
+    pathForAgent = join(pathForAgent, agent.id);
+
+    await writeResource(directory, { ...agent }, { ...options, path: pathForAgent, type: 'agent' });
+  };
+
+export const versionAgent = (directory: string) => async (id: string) => versionResource(directory, id);
+
+export const rmAgent = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+export const rmAgentById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) => {
+  await rmResourceById(directory, id, version, { type: 'agent', persistFiles });
+};
+
+export const addFileToAgent =
+  (directory: string) => async (id: string, file: { content: string; fileName: string }, version?: string) =>
+    addFileToResource(directory, id, file, version);
+
+export const addMessageToAgent =
+  (directory: string) =>
+  async (
+    id: string,
+    direction: string,
+    message: { id: string; version: string; fields?: string[]; group?: string },
+    version?: string
+  ) => {
+    const agent: Agent = await getAgent(directory)(id, version);
+
+    if (direction === 'sends') {
+      if (agent.sends === undefined) {
+        agent.sends = [];
+      }
+      for (let i = 0; i < agent.sends.length; i++) {
+        if (agent.sends[i].id === message.id && agent.sends[i].version === message.version) {
+          return;
+        }
+      }
+      agent.sends.push(buildMessagePointer(message));
+    } else if (direction === 'receives') {
+      if (agent.receives === undefined) {
+        agent.receives = [];
+      }
+      for (let i = 0; i < agent.receives.length; i++) {
+        if (agent.receives[i].id === message.id && agent.receives[i].version === message.version) {
+          return;
+        }
+      }
+      agent.receives.push(buildMessagePointer(message));
+    } else {
+      throw new Error(`Direction ${direction} is invalid, only 'receives' and 'sends' are supported`);
+    }
+
+    await rewriteAgent(directory, id, agent, version);
+  };
+
+export const addDataStoreToAgent =
+  (directory: string) => async (id: string, direction: string, dataStore: { id: string; version: string }, version?: string) => {
+    const agent: Agent = await getAgent(directory)(id, version);
+
+    if (direction === 'writesTo') {
+      if (agent.writesTo === undefined) {
+        agent.writesTo = [];
+      }
+      if (agent.writesTo.some((store) => store.id === dataStore.id && store.version === dataStore.version)) {
+        return;
+      }
+      agent.writesTo.push(dataStore);
+    } else if (direction === 'readsFrom') {
+      if (agent.readsFrom === undefined) {
+        agent.readsFrom = [];
+      }
+      if (agent.readsFrom.some((store) => store.id === dataStore.id && store.version === dataStore.version)) {
+        return;
+      }
+      agent.readsFrom.push(dataStore);
+    } else {
+      throw new Error(`Direction ${direction} is invalid, only 'writesTo' and 'readsFrom' are supported`);
+    }
+
+    await rewriteAgent(directory, id, agent, version);
+  };
+
+export const addFlowToAgent =
+  (directory: string) => async (id: string, flow: { id: string; version: string }, version?: string) => {
+    const agent: Agent = await getAgent(directory)(id, version);
+
+    if (agent.flows === undefined) {
+      agent.flows = [];
+    }
+
+    if (agent.flows.some((f) => f.id === flow.id && f.version === flow.version)) {
+      return;
+    }
+
+    agent.flows.push(flow);
+
+    await rewriteAgent(directory, id, agent, version);
+  };
+
+export const agentHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+export const isAgent = (directory: string) => async (path: string) => {
+  const agent = await getAgentByPath(directory)(path);
+  const relativePath = relative(directory, path);
+  const segments = relativePath.split(/[/\\]+/);
+
+  return !!agent && segments.includes('agents');
+};
+
+export const toAgent = (directory: string) => async (file: string) => toResource(directory, file) as Promise<Agent>;
diff --git a/packages/sdk/src/changelogs.ts b/packages/sdk/src/changelogs.ts
new file mode 100644
index 000000000..41721d97c
--- /dev/null
+++ b/packages/sdk/src/changelogs.ts
@@ -0,0 +1,213 @@
+import path, { dirname } from 'node:path';
+import fsSync from 'node:fs';
+import fs from 'node:fs/promises';
+import matter from 'gray-matter';
+import { findFileById, invalidateFileCache } from './internal/utils';
+import type { Changelog } from './types';
+
+/**
+ * Writes a changelog entry to a resource in EventCatalog.
+ *
+ * The changelog file (`changelog.mdx`) is written to the same directory as the resource's `index.mdx`.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeChangelog } = utils('/path/to/eventcatalog');
+ *
+ * // Write a changelog to a resource
+ * await writeChangelog('OrderCreated', {
+ *   createdAt: '2024-08-01',
+ *   markdown: '### Added support for JSON Schema\n\nOrderCreated now supports JSON Draft 7.',
+ *   badges: [{ content: '⭐️ JSON Schema', backgroundColor: 'purple', textColor: 'purple' }],
+ * });
+ *
+ * // Write a changelog to a specific version
+ * await writeChangelog('OrderCreated', {
+ *   createdAt: '2024-08-01',
+ *   markdown: '### Breaking change\n\nRemoved `gender` field from schema.',
+ * }, { version: '1.0.0' });
+ * ```
+ */
+export const writeChangelog =
+  (catalogDir: string) =>
+  async (id: string, changelog: Changelog, options: { version?: string; format?: 'md' | 'mdx' } = {}): Promise<void> => {
+    const { version, format = 'mdx' } = options;
+
+    const resourceFile = await findFileById(catalogDir, id, version);
+    if (!resourceFile) {
+      throw new Error(`No resource found with id: ${id}${version ? ` and version: ${version}` : ''}`);
+    }
+
+    const resourceDir = dirname(resourceFile);
+    const changelogPath = path.join(resourceDir, `changelog.${format}`);
+
+    const { markdown, ...frontmatter } = changelog;
+
+    // Ensure createdAt is serialized correctly for gray-matter
+    const fm: Record<string, any> = { ...frontmatter };
+    if (fm.createdAt instanceof Date) {
+      fm.createdAt = fm.createdAt;
+    }
+
+    // Remove undefined/empty values from frontmatter
+    if (!fm.badges || fm.badges.length === 0) {
+      delete fm.badges;
+    }
+
+    fsSync.mkdirSync(resourceDir, { recursive: true });
+    const document = matter.stringify(markdown.trim(), fm);
+    fsSync.writeFileSync(changelogPath, document);
+    invalidateFileCache();
+  };
+
+/**
+ * Appends a changelog entry to an existing changelog for a resource.
+ * If no changelog exists, one is created.
+ *
+ * New entries are prepended to the top of the existing content, separated by `---`.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { appendChangelog } = utils('/path/to/eventcatalog');
+ *
+ * // Append to an existing changelog (or create if none exists)
+ * await appendChangelog('OrderCreated', {
+ *   createdAt: '2024-09-01',
+ *   markdown: '### New field added\n\nAdded `priority` field.',
+ * });
+ *
+ * // Append to a specific version's changelog
+ * await appendChangelog('OrderCreated', {
+ *   createdAt: '2024-09-01',
+ *   markdown: '### Bugfix\n\nFixed validation.',
+ * }, { version: '1.0.0' });
+ * ```
+ */
+export const appendChangelog =
+  (catalogDir: string) =>
+  async (id: string, changelog: Changelog, options: { version?: string; format?: 'md' | 'mdx' } = {}): Promise<void> => {
+    const { version, format = 'mdx' } = options;
+
+    const resourceFile = await findFileById(catalogDir, id, version);
+    if (!resourceFile) {
+      throw new Error(`No resource found with id: ${id}${version ? ` and version: ${version}` : ''}`);
+    }
+
+    const resourceDir = dirname(resourceFile);
+
+    // Find existing changelog file
+    const mdxPath = path.join(resourceDir, 'changelog.mdx');
+    const mdPath = path.join(resourceDir, 'changelog.md');
+    const existingPath = fsSync.existsSync(mdxPath) ? mdxPath : fsSync.existsSync(mdPath) ? mdPath : undefined;
+
+    if (!existingPath) {
+      // No existing changelog — delegate to writeChangelog
+      return writeChangelog(catalogDir)(id, changelog, options);
+    }
+
+    const existing = matter.read(existingPath);
+    const existingContent = existing.content.trim();
+
+    // Build the new entry markdown
+    const newEntry = changelog.markdown.trim();
+
+    // Prepend new entry, separated by ---
+    const combined = `${newEntry}\n\n---\n\n${existingContent}`;
+
+    // Merge frontmatter: use the new createdAt, merge badges
+    const fm: Record<string, any> = { ...existing.data };
+    fm.createdAt = changelog.createdAt;
+
+    if (changelog.badges && changelog.badges.length > 0) {
+      fm.badges = changelog.badges;
+    } else {
+      delete fm.badges;
+    }
+
+    const document = matter.stringify(combined, fm);
+    fsSync.writeFileSync(existingPath, document);
+    invalidateFileCache();
+  };
+
+/**
+ * Returns the changelog for a resource in EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getChangelog } = utils('/path/to/eventcatalog');
+ *
+ * // Get the changelog for a resource
+ * const changelog = await getChangelog('OrderCreated');
+ *
+ * // Get the changelog for a specific version
+ * const changelog = await getChangelog('OrderCreated', { version: '1.0.0' });
+ * ```
+ */
+export const getChangelog =
+  (catalogDir: string) =>
+  async (id: string, options: { version?: string } = {}): Promise<Changelog | undefined> => {
+    const { version } = options;
+
+    const resourceFile = await findFileById(catalogDir, id, version);
+    if (!resourceFile) return undefined;
+
+    const resourceDir = dirname(resourceFile);
+
+    // Try .mdx first, then .md
+    const mdxPath = path.join(resourceDir, 'changelog.mdx');
+    const mdPath = path.join(resourceDir, 'changelog.md');
+
+    const changelogPath = fsSync.existsSync(mdxPath) ? mdxPath : fsSync.existsSync(mdPath) ? mdPath : undefined;
+
+    if (!changelogPath) return undefined;
+
+    const { data, content } = matter.read(changelogPath);
+    return { ...data, markdown: content.trim() } as Changelog;
+  };
+
+/**
+ * Removes the changelog for a resource in EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmChangelog } = utils('/path/to/eventcatalog');
+ *
+ * // Remove the changelog for a resource
+ * await rmChangelog('OrderCreated');
+ *
+ * // Remove the changelog for a specific version
+ * await rmChangelog('OrderCreated', { version: '1.0.0' });
+ * ```
+ */
+export const rmChangelog =
+  (catalogDir: string) =>
+  async (id: string, options: { version?: string } = {}): Promise<void> => {
+    const { version } = options;
+
+    const resourceFile = await findFileById(catalogDir, id, version);
+    if (!resourceFile) {
+      throw new Error(`No resource found with id: ${id}${version ? ` and version: ${version}` : ''}`);
+    }
+
+    const resourceDir = dirname(resourceFile);
+
+    const mdxPath = path.join(resourceDir, 'changelog.mdx');
+    const mdPath = path.join(resourceDir, 'changelog.md');
+
+    if (fsSync.existsSync(mdxPath)) {
+      await fs.rm(mdxPath);
+    }
+    if (fsSync.existsSync(mdPath)) {
+      await fs.rm(mdPath);
+    }
+
+    invalidateFileCache();
+  };
diff --git a/packages/sdk/src/channels.ts b/packages/sdk/src/channels.ts
new file mode 100644
index 000000000..e248279a3
--- /dev/null
+++ b/packages/sdk/src/channels.ts
@@ -0,0 +1,283 @@
+import fs from 'node:fs/promises';
+import { join, extname } from 'node:path';
+import type { Channel } from './types';
+import { getResource, getResourcePath, getResources, rmResourceById, versionResource, writeResource } from './internal/resources';
+import { findFileById, invalidateFileCache } from './internal/utils';
+import { getEvent, rmEventById, writeEvent } from './events';
+import { getCommand, rmCommandById, writeCommand } from './commands';
+import { getQuery, rmQueryById, writeQuery } from './queries';
+
+/**
+ * Returns a channel from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the channel
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getChannel } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the channel
+ * const channel = await getChannel('InventoryChannel');
+ *
+ * // Gets a version of the channel
+ * const channel = await getChannel('InventoryChannel', '0.0.1');
+ * ```
+ */
+export const getChannel =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<Channel> =>
+    getResource(directory, id, version, { type: 'channel' }) as Promise<Channel>;
+
+/**
+ * Returns all channels from EventCatalog.
+ *
+ * You can optionally specify if you want to get the latest version of the channels.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getChannels } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all channels (and versions) from the catalog
+ * const channels = await getChannels();
+ *
+ * // Gets all channels (only latest version) from the catalog
+ * const channels = await getChannels({ latestOnly: true });
+ * ```
+ */
+export const getChannels =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean }): Promise<Channel[]> =>
+    getResources(directory, { type: 'channels', ...options }) as Promise<Channel[]>;
+
+/**
+ * Write a channel to EventCatalog.
+ *
+ * You can optionally override the path of the channel.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeChannel } = utils('/path/to/eventcatalog');
+ *
+ * // Write a channel to the catalog
+ * // channel would be written to channels/inventory.{env}.events
+ * await writeChannel({
+ *   id: 'inventory.{env}.events',
+ *   name: 'Inventory channel',
+ *   version: '0.0.1',
+ *   summary: 'This is a summary',
+ *   markdown: '# Hello world',
+ *   address: inventory.{env}.events,
+ * protocols: ['http'],
+ * });
+ *
+ * // Write a channel to the catalog but override the path
+ * // channel would be written to channels/Inventory/InventoryChannel
+ * await writeChannel({
+ *    id: 'InventoryChannel',
+ *    name: 'Update Inventory',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ *    address: inventory.{env}.events,
+ *    protocols: ['http'],
+ * }, { path: "/channels/Inventory/InventoryChannel"});
+ *
+ * // Write a channel to the catalog and override the existing content (if there is any)
+ * await writeChannel({
+ *    id: 'InventoryChannel',
+ *    name: 'Update Inventory',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ *    address: inventory.{env}.events,
+ *    protocols: ['http'],
+ * }, { override: true });
+ *
+ * // Write a channel to the catalog and version the previous version
+ * // only works if the new version is greater than the previous version
+ * await writeChannel({
+ *    id: 'InventoryChannel',
+ *    name: 'Update Inventory',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ *    address: inventory.{env}.events,
+ *    protocols: ['http'],
+ * }, { versionExistingContent: true });
+ * ```
+ */
+export const writeChannel =
+  (directory: string) =>
+  async (
+    channel: Channel,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = { path: '' }
+  ) =>
+    writeResource(directory, { ...channel }, { ...options, type: 'channel' });
+
+/**
+ * Delete a channel at it's given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmChannel } = utils('/path/to/eventcatalog');
+ *
+ * // removes a channel at the given path (channels dir is appended to the given path)
+ * // Removes the channel at channels/InventoryChannel
+ * await rmChannel('/InventoryChannel');
+ * ```
+ */
+export const rmChannel = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+/**
+ * Delete a channel by it's id.
+ *
+ * Optionally specify a version to delete a specific version of the channel.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmChannelById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest InventoryChannel channel
+ * await rmChannelById('inventory.{env}.events');
+ *
+ * // deletes a specific version of the InventoryChannel channel
+ * await rmChannelById('inventory.{env}.events', '0.0.1');
+ * ```
+ */
+export const rmChannelById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) =>
+  rmResourceById(directory, id, version, { type: 'channel', persistFiles });
+
+/**
+ * Version a channel by it's id.
+ *
+ * Takes the latest channel and moves it to a versioned directory.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionChannel } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest inventory.{env}.events channel to a versioned directory
+ * // the version within that channel is used as the version number.
+ * await versionChannel('inventory.{env}.events');
+ *
+ * ```
+ */
+export const versionChannel = (directory: string) => async (id: string) => versionResource(directory, id);
+
+/**
+ * Check to see if the catalog has a version for the given channel.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { channelHasVersion } = utils('/path/to/eventcatalog');
+ *
+ * // returns true if version is found for the given event and version (supports semver)
+ * await channelHasVersion('inventory.{env}.events', '0.0.1');
+ * await channelHasVersion('inventory.{env}.events', 'latest');
+ * await channelHasVersion('inventory.{env}.events', '0.0.x');*
+ *
+ * ```
+ */
+export const channelHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+/**
+ * Add an event/command/query to a channel by it's id.
+ *
+ * Optionally specify a version to add the message to a specific version of the service.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * // Adds an event to the service or command to the service
+ * const { addEventToChannel, addCommandToChannel, addQueryToChannel } = utils('/path/to/eventcatalog');
+ *
+ * // Adds a new event (InventoryUpdatedEvent) that the InventoryService will send
+ * await addEventToChannel('InventoryService', 'sends', { event: 'InventoryUpdatedEvent', version: '2.0.0' });
+ * * // Adds a new event (OrderComplete) that the InventoryService will receive
+ * await addEventToChannel('InventoryService', 'receives', { event: 'OrderComplete', version: '1.0.0' });
+ *
+ * // Adds a new command (UpdateInventoryCommand) that the InventoryService will send
+ * await addCommandToChannel('InventoryService', 'sends', { command: 'UpdateInventoryCommand', version: '2.0.0' });
+ * // Adds a new command (VerifyInventory) that the InventoryService will receive
+ * await addCommandToChannel('InventoryService', 'receives', { command: 'VerifyInventory', version: '1.0.0' });
+ *
+ * // Adds a new query (GetInventoryQuery) that the InventoryService will send
+ * await addQueryToChannel('InventoryService', 'sends', { query: 'GetInventoryQuery', version: '2.0.0' });
+ * // Adds a new query (GetOrder) that the InventoryService will receive
+ * await addQueryToChannel('InventoryService', 'receives', { query: 'GetOrder', version: '1.0.0' });
+ *
+ * ```
+ */
+
+export const addMessageToChannel =
+  (directory: string, collection: string) =>
+  async (id: string, _message: { id: string; version: string; parameters?: { [key: string]: string } }, version?: string) => {
+    let channel: Channel = await getChannel(directory)(id, version);
+
+    const functions = {
+      events: {
+        getMessage: getEvent,
+        rmMessageById: rmEventById,
+        writeMessage: writeEvent,
+      },
+      commands: {
+        getMessage: getCommand,
+        rmMessageById: rmCommandById,
+        writeMessage: writeCommand,
+      },
+      queries: {
+        getMessage: getQuery,
+        rmMessageById: rmQueryById,
+        writeMessage: writeQuery,
+      },
+    };
+
+    const { getMessage, rmMessageById, writeMessage } = functions[collection as keyof typeof functions];
+
+    const message = await getMessage(directory)(_message.id, _message.version);
+    const messagePath = await getResourcePath(directory, _message.id, _message.version);
+    const extension = extname(messagePath?.fullPath || '');
+
+    if (!message) throw new Error(`Message ${_message.id} with version ${_message.version} not found`);
+
+    if (message.channels === undefined) {
+      message.channels = [];
+    }
+
+    const channelInfo = { id, version: channel.version, ...(_message.parameters && { parameters: _message.parameters }) };
+    message.channels.push(channelInfo);
+
+    // Add the message where it was to start..
+    const existingResource = await findFileById(directory, _message.id, _message.version);
+
+    if (!existingResource) {
+      throw new Error(`Cannot find message ${id} in the catalog`);
+    }
+
+    const path = existingResource.split(new RegExp(`[\\\\/]+${collection}`))[0];
+    const pathToResource = join(path, collection);
+
+    await rmMessageById(directory)(_message.id, _message.version, true);
+    await writeMessage(pathToResource)(message, { format: extension === '.md' ? 'md' : 'mdx' });
+  };
diff --git a/packages/sdk/src/commands.ts b/packages/sdk/src/commands.ts
new file mode 100644
index 000000000..ff3a424b9
--- /dev/null
+++ b/packages/sdk/src/commands.ts
@@ -0,0 +1,393 @@
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import type { Command } from './types';
+import {
+  addFileToResource,
+  addExampleToResource,
+  getExamplesFromResource,
+  removeExampleFromResource,
+  getResource,
+  getResourcePath,
+  getResources,
+  rmResourceById,
+  versionResource,
+  writeResource,
+} from './internal/resources';
+import { findFileById, invalidateFileCache } from './internal/utils';
+import { addMessageToService } from './services';
+
+/**
+ * Returns a command from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the command
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getCommand } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the command
+ * const command = await getCommand('UpdateInventory');
+ *
+ * // Gets a version of the command
+ * const command = await getCommand('UpdateInventory', '0.0.1');
+ *
+ * // Gets the command with the schema attached
+ * const command = await getCommand('UpdateInventory', '0.0.1', { attachSchema: true });
+ * ```
+ */
+export const getCommand =
+  (directory: string) =>
+  async (id: string, version?: string, options?: { attachSchema?: boolean }): Promise<Command> =>
+    getResource(directory, id, version, { type: 'command', ...options }) as Promise<Command>;
+
+/**
+ * Returns all commands from EventCatalog.
+ *
+ * You can optionally specify if you want to get the latest version of the events.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getCommands } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all commands (and versions) from the catalog
+ * const commands = await getCommands();
+ *
+ * // Gets all commands (only latest version) from the catalog
+ * const commands = await getCommands({ latestOnly: true });
+ *
+ * // Gets all commands with the schema attached
+ * const commands = await getCommands({ attachSchema: true });
+ * ```
+ */
+export const getCommands =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean; attachSchema?: boolean }): Promise<Command[]> =>
+    getResources(directory, { type: 'commands', ...options }) as Promise<Command[]>;
+
+/**
+ * Write a command to EventCatalog.
+ *
+ * You can optionally override the path of the command.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeCommand } = utils('/path/to/eventcatalog');
+ *
+ * // Write a command to the catalog
+ * // Command would be written to commands/UpdateInventory
+ * await writeCommand({
+ *   id: 'UpdateInventory',
+ *   name: 'Update Inventory',
+ *   version: '0.0.1',
+ *   summary: 'This is a summary',
+ *   markdown: '# Hello world',
+ * });
+ *
+ * // Write a command to the catalog but override the path
+ * // Command would be written to commands/Inventory/UpdateInventory
+ * await writeCommand({
+ *    id: 'UpdateInventory',
+ *    name: 'Update Inventory',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { path: "/Inventory/UpdateInventory"});
+ *
+ * // Write a command to the catalog and override the existing content (if there is any)
+ * await writeCommand({
+ *    id: 'UpdateInventory',
+ *    name: 'Update Inventory',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { override: true });
+ *
+ * // Write a command to the catalog and version the previous version
+ * // only works if the new version is greater than the previous version
+ * await writeCommand({
+ *    id: 'UpdateInventory',
+ *    name: 'Update Inventory',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { versionExistingContent: true });
+ *
+ * ```
+ */
+export const writeCommand =
+  (directory: string) =>
+  async (
+    command: Command,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      versionExistingContent: false,
+      format: 'mdx',
+    }
+  ) =>
+    writeResource(directory, { ...command }, { ...options, type: 'command' });
+
+/**
+ * Write an command to a service in EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeCommandToService } = utils('/path/to/eventcatalog');
+ *
+ * // Write an event to a given service in the catalog
+ * // Event would be written to services/Inventory/commands/UpdateInventory
+ * await writeCommandToService({
+ *    id: 'UpdateInventory',
+ *    name: 'Update Inventory',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { id: 'Inventory' });
+ * ```
+ */
+export const writeCommandToService =
+  (directory: string) =>
+  async (
+    command: Command,
+    service: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    const resourcePath = await getResourcePath(directory, service.id, service.version);
+    if (!resourcePath) {
+      throw new Error('Service not found');
+    }
+
+    let pathForCommand =
+      service.version && service.version !== 'latest'
+        ? `${resourcePath.directory}/versioned/${service.version}/commands`
+        : `${resourcePath.directory}/commands`;
+    pathForCommand = join(pathForCommand, command.id);
+
+    await writeResource(directory, { ...command }, { ...options, path: pathForCommand, type: 'command' });
+  };
+
+/**
+ * Write a command to an agent in EventCatalog.
+ */
+export const writeCommandToAgent =
+  (directory: string) =>
+  async (
+    command: Command,
+    agent: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    const resourcePath = await getResourcePath(directory, agent.id, agent.version);
+    if (!resourcePath) {
+      throw new Error('Agent not found');
+    }
+
+    let pathForCommand =
+      agent.version && agent.version !== 'latest'
+        ? `${resourcePath.directory}/versioned/${agent.version}/commands`
+        : `${resourcePath.directory}/commands`;
+    pathForCommand = join(pathForCommand, command.id);
+
+    await writeResource(directory, { ...command }, { ...options, path: pathForCommand, type: 'command' });
+  };
+
+/**
+ * Delete a command at it's given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmCommand } = utils('/path/to/eventcatalog');
+ *
+ * // removes a command at the given path (commands dir is appended to the given path)
+ * // Removes the command at commands/UpdateInventory
+ * await rmCommand('/UpdateInventory');
+ * ```
+ */
+export const rmCommand = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+/**
+ * Delete a command by it's id.
+ *
+ * Optionally specify a version to delete a specific version of the command.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmCommandById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest UpdateInventory command
+ * await rmCommandById('UpdateInventory');
+ *
+ * // deletes a specific version of the UpdateInventory command
+ * await rmCommandById('UpdateInventory', '0.0.1');
+ * ```
+ */
+export const rmCommandById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) =>
+  rmResourceById(directory, id, version, { type: 'command', persistFiles });
+
+/**
+ * Version a command by it's id.
+ *
+ * Takes the latest command and moves it to a versioned directory.
+ * All files with this command are also versioned (e.g /commands/UpdateInventory/schema.json)
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionCommand } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest UpdateInventory command to a versioned directory
+ * // the version within that command is used as the version number.
+ * await versionCommand('UpdateInventory');
+ *
+ * ```
+ */
+export const versionCommand = (directory: string) => async (id: string) => versionResource(directory, id);
+
+/**
+ * Add a file to a command by it's id.
+ *
+ * Optionally specify a version to add a file to a specific version of the command.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addFileToCommand } = utils('/path/to/eventcatalog');
+ *
+ * // adds a file to the latest UpdateInventory command
+ * await addFileToCommand('UpdateInventory', { content: 'Hello world', fileName: 'hello.txt' });
+ *
+ * // adds a file to a specific version of the UpdateInventory command
+ * await addFileToCommand('UpdateInventory', { content: 'Hello world', fileName: 'hello.txt' }, '0.0.1');
+ *
+ * ```
+ */
+export const addFileToCommand =
+  (directory: string) =>
+  async (id: string, file: { content: string; fileName: string }, version?: string, options?: { path?: string }) =>
+    addFileToResource(directory, id, file, version, options);
+
+/**
+ * Add a schema to a command by it's id.
+ *
+ * Optionally specify a version to add a schema to a specific version of the command.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addSchemaToCommand } = utils('/path/to/eventcatalog');
+ *
+ * // JSON schema example
+ * const schema = {
+ *    "$schema": "http://json-schema.org/draft-07/schema#",
+ *    "type": "object",
+ *    "properties": {
+ *        "name": {
+ *        "type": "string"
+ *    },
+ *    "age": {
+ *      "type": "number"
+ *    }
+ *  },
+ *  "required": ["name", "age"]
+ * };
+ *
+ * // adds a schema to the latest UpdateInventory command
+ * await addSchemaToCommand('UpdateInventory', { schema, fileName: 'schema.json' });
+ *
+ * // adds a file to a specific version of the UpdateInventory command
+ * await addSchemaToCommand('UpdateInventory', { schema, fileName: 'schema.json' }, '0.0.1');
+ *
+ * ```
+ */
+export const addSchemaToCommand =
+  (directory: string) =>
+  async (id: string, schema: { schema: string; fileName: string }, version?: string, options?: { path?: string }) => {
+    await addFileToCommand(directory)(id, { content: schema.schema, fileName: schema.fileName }, version, options);
+  };
+
+/**
+ * Check to see if the catalog has a version for the given command.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { commandHasVersion } = utils('/path/to/eventcatalog');
+ *
+ * // returns true if version is found for the given event and version (supports semver)
+ * await commandHasVersion('InventoryAdjusted', '0.0.1');
+ * await commandHasVersion('InventoryAdjusted', 'latest');
+ * await commandHasVersion('InventoryAdjusted', '0.0.x');*
+ *
+ * ```
+ */
+export const commandHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+/**
+ * Add an example file to a command.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addExampleToCommand } = utils('/path/to/eventcatalog');
+ *
+ * await addExampleToCommand('UpdateInventory', { content: '{"id": "123"}', fileName: 'basic.json' });
+ * await addExampleToCommand('UpdateInventory', { content: '{"id": "123"}', fileName: 'basic.json' }, '0.0.1');
+ * ```
+ */
+export const addExampleToCommand =
+  (directory: string) => async (id: string, example: { content: string; fileName: string }, version?: string) =>
+    addExampleToResource(directory, id, example, version);
+
+/**
+ * Get all examples from a command.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getExamplesFromCommand } = utils('/path/to/eventcatalog');
+ *
+ * const examples = await getExamplesFromCommand('UpdateInventory');
+ * const examples = await getExamplesFromCommand('UpdateInventory', '0.0.1');
+ * ```
+ */
+export const getExamplesFromCommand = (directory: string) => async (id: string, version?: string) =>
+  getExamplesFromResource(directory, id, version);
+
+/**
+ * Remove an example file from a command.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { removeExampleFromCommand } = utils('/path/to/eventcatalog');
+ *
+ * await removeExampleFromCommand('UpdateInventory', 'basic.json');
+ * await removeExampleFromCommand('UpdateInventory', 'basic.json', '0.0.1');
+ * ```
+ */
+export const removeExampleFromCommand = (directory: string) => async (id: string, fileName: string, version?: string) =>
+  removeExampleFromResource(directory, id, fileName, version);
diff --git a/packages/sdk/src/containers.ts b/packages/sdk/src/containers.ts
new file mode 100644
index 000000000..12c068846
--- /dev/null
+++ b/packages/sdk/src/containers.ts
@@ -0,0 +1,243 @@
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { findFileById, invalidateFileCache } from './internal/utils';
+import type { Container } from './types';
+import {
+  addFileToResource,
+  getResource,
+  getResourcePath,
+  getResources,
+  rmResourceById,
+  versionResource,
+  writeResource,
+} from './internal/resources';
+
+/**
+ * Returns an container (e.g. data store) from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the container
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getContainer } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the container
+ * const container = await getContainer('User');
+ *
+ * // Gets a version of the entity
+ * const container = await getContainer('User', '0.0.1');
+ *
+ * ```
+ */
+export const getContainer =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<Container> =>
+    getResource(directory, id, version, { type: 'container' }) as Promise<Container>;
+
+/**
+ * Returns all containers (e.g. data stores) from EventCatalog.
+ *
+ * You can optionally specify if you want to get the latest version of the containers.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getContainers } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all containers (and versions) from the catalog
+ * const containers = await getContainers();
+ *
+ * // Gets all entities (only latest version) from the catalog
+ * const containers = await getContainers({ latestOnly: true });
+ *
+ * ```
+ */
+export const getContainers =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean }): Promise<Container[]> =>
+    getResources(directory, { type: 'containers', latestOnly: options?.latestOnly }) as Promise<Container[]>;
+
+/**
+ * Write a container (e.g. data store) to EventCatalog.
+ */
+export const writeContainer =
+  (directory: string) =>
+  async (
+    data: Container,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      format: 'mdx',
+    }
+  ) =>
+    writeResource(directory, { ...data }, { ...options, type: 'container' });
+
+/**
+ * Version an container (e.g. data store) by its id.
+ *
+ * Takes the latest container and moves it to a versioned directory.
+ * All files with this container are also versioned (e.g /containers/orders-db/schema.json)
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionContainer } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest orders-db container to a versioned directory
+ * // the version within that container is used as the version number.
+ * await versionContainer('orders-db');
+ *
+ * ```
+ */
+export const versionContainer = (directory: string) => async (id: string) => versionResource(directory, id);
+
+/**
+ * Delete an container (e.g. data store) at its given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmContainer } = utils('/path/to/eventcatalog');
+ *
+ * // removes an container at the given path (containers dir is appended to the given path)
+ * // Removes the container at containers/orders-db
+ * await rmContainer('/orders-db');
+ * ```
+ */
+export const rmContainer = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+/**
+ * Delete an container (e.g. data store) by its id.
+ *
+ * Optionally specify a version to delete a specific version of the container.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmContainerById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest orders-db container
+ * await rmContainerById('orders-db');
+ *
+ * // deletes a specific version of the orders-db container
+ * await rmContainerById('orders-db', '0.0.1');
+ * ```
+ */
+export const rmContainerById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) => {
+  await rmResourceById(directory, id, version, { type: 'container', persistFiles });
+};
+
+/**
+ * Check to see if the catalog has a version for the given container (e.g. data store).
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { containerHasVersion } = utils('/path/to/eventcatalog');
+ *
+ * // returns true if version is found for the given entity and version (supports semver)
+ * await containerHasVersion('orders-db', '0.0.1');
+ * await containerHasVersion('orders-db', 'latest');
+ * await containerHasVersion('orders-db', '0.0.x');
+ *
+ * ```
+ */
+export const containerHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+/**
+ * Add a file to a container (e.g. data store) by it's id.
+ *
+ * Optionally specify a version to add a file to a specific version of the container.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addFileToContainer } = utils('/path/to/eventcatalog');
+ *
+ * // adds a file to the latest InventoryAdjusted event
+ * await addFileToContainer('InventoryAdjusted', { content: 'Hello world', fileName: 'hello.txt' });
+ *
+ * // adds a file to a specific version of the InventoryAdjusted event
+ * await addFileToContainer('InventoryAdjusted', { content: 'Hello world', fileName: 'hello.txt' }, '0.0.1');
+ *
+ * ```
+ */
+export const addFileToContainer =
+  (directory: string) => async (id: string, file: { content: string; fileName: string }, version?: string) =>
+    addFileToResource(directory, id, file, version);
+
+/**
+ * Write an data store (e.g. data store) to a service in EventCatalog.
+ *
+ * You can optionally override the path of the data store.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeContainerToService } = utils('/path/to/eventcatalog');
+ *
+ * // Write a container to a given service in the catalog
+ * // Container would be written to services/Inventory/containers/orders-db
+ * await writeContainerToService({
+ *   id: 'orders-db',
+ *   name: 'Orders DB',
+ *   version: '0.0.1',
+ *   summary: 'This is a summary',
+ *   markdown: '# Hello world',
+ *   container_type: 'database',
+ * }, { id: 'Inventory' });
+ * ```
+ */
+export const writeContainerToService =
+  (directory: string) =>
+  async (
+    container: Container,
+    service: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    const resourcePath = await getResourcePath(directory, service.id, service.version);
+    if (!resourcePath) {
+      throw new Error('Service not found');
+    }
+
+    let pathForContainer =
+      service.version && service.version !== 'latest'
+        ? `${resourcePath.directory}/versioned/${service.version}/containers`
+        : `${resourcePath.directory}/containers`;
+    pathForContainer = join(pathForContainer, container.id);
+    await writeResource(directory, { ...container }, { ...options, path: pathForContainer, type: 'container' });
+  };
+
+/**
+ * Write a container (e.g. data store) to a system in EventCatalog.
+ */
+export const writeContainerToSystem =
+  (directory: string) =>
+  async (
+    container: Container,
+    system: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    const resourcePath = await getResourcePath(directory, system.id, system.version);
+    if (!resourcePath) {
+      throw new Error('System not found');
+    }
+
+    const pathForContainer = join(resourcePath.directory, 'containers', container.id);
+    await writeResource(directory, { ...container }, { ...options, path: pathForContainer, type: 'container' });
+  };
diff --git a/packages/sdk/src/custom-docs.ts b/packages/sdk/src/custom-docs.ts
new file mode 100644
index 000000000..3aeec0024
--- /dev/null
+++ b/packages/sdk/src/custom-docs.ts
@@ -0,0 +1,127 @@
+import path, { join } from 'node:path';
+import { invalidateFileCache, readMdxFile } from './internal/utils';
+import type { CustomDoc } from './types';
+import fsSync from 'node:fs';
+import fs from 'node:fs/promises';
+import matter from 'gray-matter';
+import { getResources } from './internal/resources';
+import slugify from 'slugify';
+
+/**
+ * Returns a custom doc from EventCatalog by the given file path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getCustomDoc } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the custom doc by the given file path
+ * const customDoc = await getCustomDoc('/guides/inventory-management.mdx');
+ * ```
+ */
+export const getCustomDoc =
+  (directory: string) =>
+  async (filePath: string): Promise<CustomDoc | undefined> => {
+    const fullPath = path.join(directory, filePath);
+    const fullPathWithExtension = fullPath.endsWith('.mdx') ? fullPath : `${fullPath}.mdx`;
+    const fileExists = fsSync.existsSync(fullPathWithExtension);
+    if (!fileExists) {
+      return undefined;
+    }
+    return readMdxFile(fullPathWithExtension) as Promise<CustomDoc>;
+  };
+
+/**
+ * Returns all custom docs for the project.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getCustomDocs } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all custom docs from the catalog
+ * const customDocs = await getCustomDocs();
+ *
+ * // Gets all custom docs from the given path
+ * const customDocs = await getCustomDocs({ path: '/guides' });
+ * ```
+ */
+export const getCustomDocs =
+  (directory: string) =>
+  async (options?: { path?: string }): Promise<CustomDoc[]> => {
+    if (options?.path) {
+      const pattern = `${directory}/${options.path}/**/*.{md,mdx}`;
+      return getResources(directory, { type: 'docs', pattern }) as Promise<CustomDoc[]>;
+    }
+    return getResources(directory, { type: 'docs', pattern: `${directory}/**/*.{md,mdx}` }) as Promise<CustomDoc[]>;
+  };
+
+/**
+ * Write a custom doc to EventCatalog.
+ *
+ * You can optionally override the path of the custom doc.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeCustomDoc } = utils('/path/to/eventcatalog');
+ *
+ * // Write a custom doc to the catalog
+ * // Custom doc would be written to docs/inventory-management.mdx
+ * await writeCustomDoc({
+ *   title: 'Inventory Management',
+ *   summary: 'This is a summary',
+ *   owners: ['John Doe'],
+ *   badges: [{ content: 'Badge', backgroundColor: 'red', textColor: 'white' }],
+ *   markdown: '# Hello world',
+ *   fileName: 'inventory-management',
+ * });
+ *
+ * // Write a custom doc to the catalog but override the path
+ * // Custom doc would be written to docs/guides/inventory-management/introduction.mdx
+ * await writeCustomDoc({
+ *   title: 'Inventory Management',
+ *   summary: 'This is a summary',
+ *   owners: ['John Doe'],
+ *   badges: [{ content: 'Badge', backgroundColor: 'red', textColor: 'white' }],
+ *   markdown: '# Hello world',
+ *   fileName: 'introduction',
+ * }, { path: "/guides/inventory-management"});
+ * ```
+ */
+export const writeCustomDoc =
+  (directory: string) =>
+  async (customDoc: CustomDoc, options: { path?: string } = { path: '' }): Promise<void> => {
+    const { fileName, ...rest } = customDoc;
+    const name = fileName || slugify(customDoc.title, { lower: true });
+    const withExtension = name.endsWith('.mdx') ? name : `${name}.mdx`;
+    const fullPath = path.join(directory, options.path || '', withExtension);
+
+    fsSync.mkdirSync(path.dirname(fullPath), { recursive: true });
+    const document = matter.stringify(customDoc.markdown.trim(), rest);
+    fsSync.writeFileSync(fullPath, document);
+    invalidateFileCache();
+  };
+
+/**
+ * Delete a custom doc by its' path
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmCustomDoc } = utils('/path/to/eventcatalog');
+ *
+ * // removes a custom doc at the given path
+ * // Removes the custom doc at docs/guides/inventory-management/introduction.mdx
+ * await rmCustomDoc('/guides/inventory-management/introduction');
+ * ```
+ */
+export const rmCustomDoc = (directory: string) => async (filePath: string) => {
+  const withExtension = filePath.endsWith('.mdx') ? filePath : `${filePath}.mdx`;
+  await fs.rm(join(directory, withExtension), { recursive: true });
+  invalidateFileCache();
+};
diff --git a/packages/sdk/src/data-products.ts b/packages/sdk/src/data-products.ts
new file mode 100644
index 000000000..3251a5d32
--- /dev/null
+++ b/packages/sdk/src/data-products.ts
@@ -0,0 +1,265 @@
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { findFileById, invalidateFileCache } from './internal/utils';
+import type { DataProduct } from './types';
+import {
+  addFileToResource,
+  getResource,
+  getResources,
+  rmResourceById,
+  versionResource,
+  writeResource,
+} from './internal/resources';
+
+/**
+ * Returns a data product from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the data product
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getDataProduct } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the data product
+ * const dataProduct = await getDataProduct('CustomerDataProduct');
+ *
+ * // Gets a version of the data product
+ * const dataProduct = await getDataProduct('CustomerDataProduct', '0.0.1');
+ *
+ * ```
+ */
+export const getDataProduct =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<DataProduct> =>
+    getResource(directory, id, version, { type: 'data-product' }) as Promise<DataProduct>;
+
+/**
+ * Returns all data products from EventCatalog.
+ *
+ * You can optionally specify if you want to get the latest version of the data products.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getDataProducts } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all data products (and versions) from the catalog
+ * const dataProducts = await getDataProducts();
+ *
+ * // Gets all data products (only latest version) from the catalog
+ * const dataProducts = await getDataProducts({ latestOnly: true });
+ *
+ * ```
+ */
+export const getDataProducts =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean }): Promise<DataProduct[]> =>
+    getResources(directory, { type: 'data-products', latestOnly: options?.latestOnly }) as Promise<DataProduct[]>;
+
+/**
+ * Write a data product to EventCatalog.
+ *
+ * You can optionally override the path of the data product.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeDataProduct } = utils('/path/to/eventcatalog');
+ *
+ * // Write a data product to the catalog
+ * // Data product would be written to data-products/CustomerDataProduct
+ * await writeDataProduct({
+ *   id: 'CustomerDataProduct',
+ *   name: 'Customer Data Product',
+ *   version: '0.0.1',
+ *   summary: 'Customer data product',
+ *   markdown: '# Customer data product',
+ * });
+ *
+ * // Write a data product to the catalog but override the path
+ * // Data product would be written to data-products/Account/CustomerDataProduct
+ * await writeDataProduct({
+ *    id: 'CustomerDataProduct',
+ *    name: 'Customer Data Product',
+ *    version: '0.0.1',
+ *    summary: 'Customer data product',
+ *    markdown: '# Customer data product',
+ * }, { path: "/Account/CustomerDataProduct"});
+ *
+ * // Write a data product to the catalog and override the existing content (if there is any)
+ * await writeDataProduct({
+ *    id: 'CustomerDataProduct',
+ *    name: 'Customer Data Product',
+ *    version: '0.0.1',
+ *    summary: 'Customer data product',
+ *    markdown: '# Customer data product',
+ * }, { override: true });
+ *
+ * // Write a data product to the catalog and version the previous version
+ * // only works if the new version is greater than the previous version
+ * await writeDataProduct({
+ *    id: 'CustomerDataProduct',
+ *    name: 'Customer Data Product',
+ *    version: '0.0.1',
+ *    summary: 'Customer data product',
+ *    markdown: '# Customer data product',
+ * }, { versionExistingContent: true });
+ *
+ * ```
+ */
+export const writeDataProduct =
+  (directory: string) =>
+  async (
+    dataProduct: DataProduct,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      format: 'mdx',
+    }
+  ) =>
+    writeResource(directory, { ...dataProduct }, { ...options, type: 'data-product' });
+
+/**
+ * Write a data product to a domain in EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeDataProductToDomain } = utils('/path/to/eventcatalog');
+ *
+ * // Write a data product to a domain
+ * // Data product would be written to domains/Shopping/data-products/CustomerDataProduct
+ * await writeDataProductToDomain({
+ *   id: 'CustomerDataProduct',
+ *   name: 'Customer Data Product',
+ *   version: '0.0.1',
+ *   summary: 'Customer data product',
+ *   markdown: '# Customer data product',
+ * }, { id: 'Shopping' });
+ * ```
+ */
+export const writeDataProductToDomain =
+  (directory: string) =>
+  async (
+    dataProduct: DataProduct,
+    domain: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    let pathForDataProduct =
+      domain.version && domain.version !== 'latest'
+        ? `/${domain.id}/versioned/${domain.version}/data-products`
+        : `/${domain.id}/data-products`;
+    pathForDataProduct = join(pathForDataProduct, dataProduct.id);
+
+    await writeResource(directory, { ...dataProduct }, { ...options, path: pathForDataProduct, type: 'data-product' });
+  };
+
+/**
+ * Delete a data product at its given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmDataProduct } = utils('/path/to/eventcatalog');
+ *
+ * // removes a data product at the given path (data-products dir is appended to the given path)
+ * // Removes the data product at data-products/CustomerDataProduct
+ * await rmDataProduct('/CustomerDataProduct');
+ * ```
+ */
+export const rmDataProduct = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+/**
+ * Delete a data product by its id.
+ *
+ * Optionally specify a version to delete a specific version of the data product.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmDataProductById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest CustomerDataProduct data product
+ * await rmDataProductById('CustomerDataProduct');
+ *
+ * // deletes a specific version of the CustomerDataProduct data product
+ * await rmDataProductById('CustomerDataProduct', '0.0.1');
+ * ```
+ */
+export const rmDataProductById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) => {
+  await rmResourceById(directory, id, version, { type: 'data-product', persistFiles });
+};
+
+/**
+ * Version a data product by its id.
+ *
+ * Takes the latest data product and moves it to a versioned directory.
+ * All files with this data product are also versioned (e.g /data-products/CustomerDataProduct/schema.json)
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionDataProduct } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest CustomerDataProduct data product to a versioned directory
+ * // the version within that data product is used as the version number.
+ * await versionDataProduct('CustomerDataProduct');
+ *
+ * ```
+ */
+export const versionDataProduct = (directory: string) => async (id: string) => versionResource(directory, id);
+
+/**
+ * Check to see if the catalog has a version for the given data product.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { dataProductHasVersion } = utils('/path/to/eventcatalog');
+ *
+ * // returns true if version is found for the given data product and version (supports semver)
+ * await dataProductHasVersion('CustomerDataProduct', '0.0.1');
+ * await dataProductHasVersion('CustomerDataProduct', 'latest');
+ * await dataProductHasVersion('CustomerDataProduct', '0.0.x');
+ *
+ * ```
+ */
+export const dataProductHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+/**
+ * Add a file to a data product by its id.
+ *
+ * Optionally specify a version to add a file to a specific version of the data product.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addFileToDataProduct } = utils('/path/to/eventcatalog');
+ *
+ * // adds a file to the latest CustomerDataProduct data product
+ * await addFileToDataProduct('CustomerDataProduct', { content: 'Hello world', fileName: 'hello.txt' });
+ *
+ * // adds a file to a specific version of the CustomerDataProduct data product
+ * await addFileToDataProduct('CustomerDataProduct', { content: 'Hello world', fileName: 'hello.txt' }, '0.0.1');
+ *
+ * ```
+ */
+export const addFileToDataProduct =
+  (directory: string) => async (id: string, file: { content: string; fileName: string }, version?: string) =>
+    addFileToResource(directory, id, file, version);
diff --git a/packages/sdk/src/data-stores.ts b/packages/sdk/src/data-stores.ts
new file mode 100644
index 000000000..fbe75c6eb
--- /dev/null
+++ b/packages/sdk/src/data-stores.ts
@@ -0,0 +1,173 @@
+import * as Containers from './containers';
+
+/**
+ * Returns a data store (e.g. database, cache, etc.) from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the data store
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getContainer } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the data store
+ * const container = await getDataStore('orders-db');
+ *
+ * // Gets a version of the entity
+ * const container = await getDataStore('orders-db', '0.0.1');
+ *
+ * ```
+ */
+export const getDataStore = Containers.getContainer;
+
+/**
+ * Returns all data stores (e.g. databases, caches, etc.) from EventCatalog.
+ *
+ * You can optionally specify if you want to get the latest version of the data stores.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getDataStores } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all data stores (and versions) from the catalog
+ * const containers = await getDataStores();
+ *
+ * // Gets all data stores (only latest version) from the catalog
+ * const containers = await getDataStores({ latestOnly: true });
+ *
+ * ```
+ */
+export const getDataStores = Containers.getContainers;
+
+/**
+ * Write a data store (e.g. database, cache, etc.) to EventCatalog.
+ */
+export const writeDataStore = Containers.writeContainer;
+
+/**
+ * Version an data store (e.g. database, cache, etc.) by its id.
+ *
+ * Takes the latest data store and moves it to a versioned directory.
+ * All files with this data store are also versioned (e.g /containers/orders-db/schema.json)
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionDataStore } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest orders-db data store to a versioned directory
+ * // the version within that data store is used as the version number.
+ * await versionDataStore('orders-db');
+ *
+ * ```
+ */
+export const versionDataStore = Containers.versionContainer;
+
+/**
+ * Delete an data store (e.g. database, cache, etc.) at its given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmDataStore } = utils('/path/to/eventcatalog');
+ *
+ * // removes an data store at the given path (containers dir is appended to the given path)
+ * // Removes the data store at containers/orders-db
+ * await rmDataStore('/orders-db');
+ * ```
+ */
+export const rmDataStore = Containers.rmContainer;
+
+/**
+ * Delete an data store (e.g. database, cache, etc.) by its id.
+ *
+ * Optionally specify a version to delete a specific version of the data store.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmDataStoreById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest orders-db data store
+ * await rmDataStoreById('orders-db');
+ *
+ * // deletes a specific version of the orders-db data store
+ * await rmDataStoreById('orders-db', '0.0.1');
+ * ```
+ */
+export const rmDataStoreById = Containers.rmContainerById;
+
+/**
+ * Check to see if the catalog has a version for the given data store (e.g. database, cache, etc.).
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { dataStoreHasVersion } = utils('/path/to/eventcatalog');
+ *
+ * // returns true if version is found for the given data store and version (supports semver)
+ * await dataStoreHasVersion('orders-db', '0.0.1');
+ * await dataStoreHasVersion('orders-db', 'latest');
+ * await dataStoreHasVersion('orders-db', '0.0.x');
+ *
+ * ```
+ */
+export const dataStoreHasVersion = Containers.containerHasVersion;
+
+/**
+ * Add a file to a data store (e.g. database, cache, etc.) by it's id.
+ *
+ * Optionally specify a version to add a file to a specific version of the data store.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addFileToDataStore } = utils('/path/to/eventcatalog');
+ *
+ * // adds a file to the latest InventoryAdjusted data store
+ * await addFileToDataStore('InventoryAdjusted', { content: 'Hello world', fileName: 'hello.txt' });
+ *
+ * // adds a file to a specific version of the InventoryAdjusted data store
+ * await addFileToDataStore('InventoryAdjusted', { content: 'Hello world', fileName: 'hello.txt' }, '0.0.1');
+ *
+ * ```
+ */
+export const addFileToDataStore = Containers.addFileToContainer;
+
+/**
+ * Write an data store (e.g. database, cache, etc.) to a service in EventCatalog.
+ *
+ * You can optionally override the path of the data store.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeDataStoreToService } = utils('/path/to/eventcatalog');
+ *
+ * // Write a data store to a given service in the catalog
+ * // Data store would be written to services/Inventory/containers/orders-db
+ * await writeDataStoreToService({
+ *   id: 'orders-db',
+ *   name: 'Orders DB',
+ *   version: '0.0.1',
+ *   summary: 'This is a summary',
+ *   markdown: '# Hello world',
+ *   container_type: 'database',
+ * }, { id: 'Inventory' });
+ * ```
+ */
+export const writeDataStoreToService = Containers.writeContainerToService;
+
+/**
+ * Write a data store (e.g. database, cache, etc.) to a system in EventCatalog.
+ */
+export const writeDataStoreToSystem = Containers.writeContainerToSystem;
diff --git a/packages/sdk/src/diagrams.ts b/packages/sdk/src/diagrams.ts
new file mode 100644
index 000000000..20cc6fa86
--- /dev/null
+++ b/packages/sdk/src/diagrams.ts
@@ -0,0 +1,228 @@
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { findFileById, invalidateFileCache } from './internal/utils';
+import type { Diagram } from './types';
+import {
+  getResource,
+  getResources,
+  rmResourceById,
+  versionResource,
+  writeResource,
+  addFileToResource,
+} from './internal/resources';
+
+/**
+ * Returns a diagram from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the diagram
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getDiagram } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the diagram
+ * const diagram = await getDiagram('ArchitectureDiagram');
+ *
+ * // Gets a version of the diagram
+ * const diagram = await getDiagram('ArchitectureDiagram', '0.0.1');
+ *
+ * ```
+ */
+export const getDiagram =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<Diagram> =>
+    getResource(directory, id, version, { type: 'diagram' }) as Promise<Diagram>;
+
+/**
+ * Returns all diagrams from EventCatalog.
+ *
+ * You can optionally specify if you want to get the latest version of the diagrams.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getDiagrams } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all diagrams (and versions) from the catalog
+ * const diagrams = await getDiagrams();
+ *
+ * // Gets all diagrams (only latest version) from the catalog
+ * const diagrams = await getDiagrams({ latestOnly: true });
+ *
+ * ```
+ */
+export const getDiagrams =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean }): Promise<Diagram[]> =>
+    getResources(directory, { type: 'diagrams', latestOnly: options?.latestOnly }) as Promise<Diagram[]>;
+
+/**
+ * Write a diagram to EventCatalog.
+ *
+ * You can optionally override the path of the diagram.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeDiagram } = utils('/path/to/eventcatalog');
+ *
+ * // Write a diagram to the catalog
+ * // Diagram would be written to diagrams/ArchitectureDiagram
+ * await writeDiagram({
+ *   id: 'ArchitectureDiagram',
+ *   name: 'Architecture Diagram',
+ *   version: '0.0.1',
+ *   summary: 'Architecture diagram',
+ *   markdown: '# Architecture Diagram',
+ * });
+ *
+ * // Write a diagram to the catalog but override the path
+ * // Diagram would be written to diagrams/System/ArchitectureDiagram
+ * await writeDiagram({
+ *    id: 'ArchitectureDiagram',
+ *    name: 'Architecture Diagram',
+ *    version: '0.0.1',
+ *    summary: 'Architecture diagram',
+ *    markdown: '# Architecture Diagram',
+ * }, { path: "/System/ArchitectureDiagram"});
+ *
+ * // Write a diagram to the catalog and override the existing content (if there is any)
+ * await writeDiagram({
+ *    id: 'ArchitectureDiagram',
+ *    name: 'Architecture Diagram',
+ *    version: '0.0.1',
+ *    summary: 'Architecture diagram',
+ *    markdown: '# Architecture Diagram',
+ * }, { override: true });
+ *
+ * // Write a diagram to the catalog and version the previous version
+ * // only works if the new version is greater than the previous version
+ * await writeDiagram({
+ *    id: 'ArchitectureDiagram',
+ *    name: 'Architecture Diagram',
+ *    version: '0.0.1',
+ *    summary: 'Architecture diagram',
+ *    markdown: '# Architecture Diagram',
+ * }, { versionExistingContent: true });
+ *
+ * ```
+ */
+export const writeDiagram =
+  (directory: string) =>
+  async (
+    diagram: Diagram,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      format: 'mdx',
+    }
+  ) =>
+    writeResource(directory, { ...diagram }, { ...options, type: 'diagram' });
+
+/**
+ * Delete a diagram at its given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmDiagram } = utils('/path/to/eventcatalog');
+ *
+ * // removes a diagram at the given path (diagrams dir is appended to the given path)
+ * // Removes the diagram at diagrams/ArchitectureDiagram
+ * await rmDiagram('/ArchitectureDiagram');
+ * ```
+ */
+export const rmDiagram = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+/**
+ * Delete a diagram by its id.
+ *
+ * Optionally specify a version to delete a specific version of the diagram.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmDiagramById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest ArchitectureDiagram diagram
+ * await rmDiagramById('ArchitectureDiagram');
+ *
+ * // deletes a specific version of the ArchitectureDiagram diagram
+ * await rmDiagramById('ArchitectureDiagram', '0.0.1');
+ * ```
+ */
+export const rmDiagramById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) => {
+  await rmResourceById(directory, id, version, { type: 'diagram', persistFiles });
+};
+
+/**
+ * Version a diagram by its id.
+ *
+ * Takes the latest diagram and moves it to a versioned directory.
+ * All files with this diagram are also versioned (e.g /diagrams/ArchitectureDiagram/diagram.png)
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionDiagram } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest ArchitectureDiagram diagram to a versioned directory
+ * // the version within that diagram is used as the version number.
+ * await versionDiagram('ArchitectureDiagram');
+ *
+ * ```
+ */
+export const versionDiagram = (directory: string) => async (id: string) => versionResource(directory, id);
+
+/**
+ * Check to see if the catalog has a version for the given diagram.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { diagramHasVersion } = utils('/path/to/eventcatalog');
+ *
+ * // returns true if version is found for the given diagram and version (supports semver)
+ * await diagramHasVersion('ArchitectureDiagram', '0.0.1');
+ * await diagramHasVersion('ArchitectureDiagram', 'latest');
+ * await diagramHasVersion('ArchitectureDiagram', '0.0.x');
+ *
+ * ```
+ */
+export const diagramHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+/**
+ * Adds a file to the given diagram.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addFileToDiagram } = utils('/path/to/eventcatalog');
+ *
+ * // adds a file to the diagram
+ * await addFileToDiagram('ArchitectureDiagram', { content: '...', fileName: 'diagram.png' });
+ *
+ * // adds a file to a specific version of the diagram
+ * await addFileToDiagram('ArchitectureDiagram', { content: '...', fileName: 'diagram.png' }, '0.0.1');
+ *
+ * ```
+ */
+export const addFileToDiagram =
+  (directory: string) =>
+  async (id: string, file: { content: string; fileName: string }, version?: string): Promise<void> =>
+    addFileToResource(directory, id, file, version, { type: 'diagram' });
diff --git a/packages/sdk/src/docs.ts b/packages/sdk/src/docs.ts
new file mode 100644
index 000000000..405268712
--- /dev/null
+++ b/packages/sdk/src/docs.ts
@@ -0,0 +1,48 @@
+/**
+ * ## EventCatalog SDK
+ *
+ * The EventCatalog SDK provides methods to interact with domains, systems, services, and messages.
+ *
+ * ## Installation
+ *
+ * ```sh
+ * npm install @eventcatalog/sdk
+ * ```
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import utils from '@eventcatalog/sdk';
+ *
+ * const { getEvent } = utils(PATH_TO_CATALOG);
+ *
+ * // Get an event by the id
+ * const event = getEvent('event-name');
+ *
+ * // Get an event by the id and it's version
+ * const event = getEvent('event-name', '0.3.4');
+ * ```
+ *
+ * @module docs
+ */
+export * from './domains';
+export * from './systems';
+export * from './services';
+export * from './agents';
+export * from './events';
+export * from './commands';
+export * from './queries';
+export * from './channels';
+export * from './custom-docs';
+export * from './teams';
+export * from './users';
+export * from './eventcatalog';
+export * from './messages';
+export * from './entities';
+export * from './flows';
+export * from './flow-builder';
+export * from './data-stores';
+export * from './data-products';
+export * from './diagrams';
+export * from './adrs';
+export * from './changelogs';
diff --git a/packages/sdk/src/domains.ts b/packages/sdk/src/domains.ts
new file mode 100644
index 000000000..80d00e39b
--- /dev/null
+++ b/packages/sdk/src/domains.ts
@@ -0,0 +1,655 @@
+import type { Domain, UbiquitousLanguageDictionary } from './types';
+import fs from 'node:fs/promises';
+import path, { join } from 'node:path';
+import fsSync from 'node:fs';
+import {
+  addFileToResource,
+  getResource,
+  getResourcePath,
+  getResources,
+  rmResourceById,
+  versionResource,
+  writeResource,
+} from './internal/resources';
+import { findFileById, invalidateFileCache, readMdxFile, uniqueVersions, buildMessagePointer } from './internal/utils';
+import matter from 'gray-matter';
+
+/**
+ * Resolves the write directory for a domain, preserving its location for nested domains (subdomains).
+ * Without this, a domain at e.g. domains/E-Commerce/subdomains/Orders would be relocated to domains/Orders.
+ *
+ * Handles both nesting conventions:
+ * - domains/E-Commerce/domains/Orders/index.mdx (domains/ subfolder)
+ * - domains/Buyer/subdomains/Agency/index.mdx (subdomains/ subfolder)
+ */
+const resolveDomainWriteDirectory = async (directory: string, id: string, version?: string): Promise<string> => {
+  const existingResource = await findFileById(directory, id, version);
+  if (!existingResource) return directory;
+  const normalizedPath = existingResource.replace(/\\/g, '/');
+  // Find the last /domains/ or /subdomains/ segment to determine the parent directory
+  const lastDomainsIndex = normalizedPath.lastIndexOf('/domains/');
+  const lastSubdomainsIndex = normalizedPath.lastIndexOf('/subdomains/');
+  const lastIndex = Math.max(lastDomainsIndex, lastSubdomainsIndex);
+  if (lastIndex === -1) return directory;
+  const segment = lastSubdomainsIndex > lastDomainsIndex ? '/subdomains' : '/domains';
+  return existingResource.substring(0, lastIndex + segment.length);
+};
+
+/**
+ * Returns a domain from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the domain
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getDomain } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the domain
+ * const domain = await getDomain('Payment');
+ *
+ * // Gets a version of the domain
+ * const domain = await getDomain('Payment', '0.0.1');
+ * ```
+ */
+export const getDomain =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<Domain> =>
+    getResource(directory, id, version, { type: 'domain' }) as Promise<Domain>;
+
+/**
+ * Returns all domains from EventCatalog.
+ *
+ * You can optionally specify if you want to get the latest version of the domains.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getDomains } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all domains (and versions) from the catalog
+ * const domains = await getDomains();
+ *
+ * // Gets all domains (only latest version) from the catalog
+ * const domains = await getDomains({ latestOnly: true });
+ * ```
+ */
+export const getDomains =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean }): Promise<Domain[]> =>
+    getResources(directory, {
+      type: 'domains',
+      ignore: [
+        '**/services/**',
+        '**/agents/**',
+        '**/events/**',
+        '**/commands/**',
+        '**/queries/**',
+        '**/flows/**',
+        '**/entities/**',
+      ],
+      ...options,
+    }) as Promise<Domain[]>;
+
+/**
+ * Write a domain to EventCatalog.
+ *
+ * You can optionally overide the path of the domain.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeDomain } = utils('/path/to/eventcatalog');
+ *
+ * // Write a domain
+ * // Domain would be written to domains/Payment
+ * await writeDomain({
+ *   id: 'Payment',
+ *   name: 'Payment domain',
+ *   version: '0.0.1',
+ *   summary: 'Domain for all things to do with payments',
+ *   markdown: '# Hello world',
+ * });
+ *
+ * // Write a domain to the catalog but override the path
+ * // Domain would be written to domains/Inventory/Payment
+ * await writeDomain({
+ *    id: 'Payment',
+ *    name: 'Inventory Adjusted',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { path: "/Inventory/Payment"});
+ *
+ * // Write a domain to the catalog and override the existing content (if there is any)
+ * await writeDomain({
+ *    id: 'Payment',
+ *    name: 'Inventory Adjusted',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { override: true });
+ *
+ * // Write a domain to the catalog and version the previous version
+ * // only works if the new version is greater than the previous version
+ * await writeDomain({
+ *    id: 'Payment',
+ *    name: 'Inventory Adjusted',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { versionExistingContent: true });
+ *
+ * ```
+ */
+export const writeDomain =
+  (directory: string) =>
+  async (
+    domain: Domain,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      versionExistingContent: false,
+      format: 'mdx',
+    }
+  ) => {
+    const resource: Domain = { ...domain };
+
+    if (Array.isArray(domain.services)) {
+      resource.services = uniqueVersions(domain.services as { id: string; version: string }[]);
+    }
+
+    if (Array.isArray(domain.agents)) {
+      resource.agents = uniqueVersions(domain.agents as { id: string; version: string }[]);
+    }
+
+    if (Array.isArray(domain.domains)) {
+      resource.domains = uniqueVersions(domain.domains as { id: string; version: string }[]);
+    }
+
+    if (Array.isArray(domain.systems)) {
+      resource.systems = uniqueVersions(domain.systems as { id: string; version: string }[]);
+    }
+
+    if (Array.isArray(domain.sends)) {
+      resource.sends = uniqueVersions(domain.sends as { id: string; version: string }[]);
+    }
+
+    if (Array.isArray(domain.receives)) {
+      resource.receives = uniqueVersions(domain.receives as { id: string; version: string }[]);
+    }
+
+    if (Array.isArray(domain.dataProducts)) {
+      resource.dataProducts = uniqueVersions(domain.dataProducts as { id: string; version: string }[]);
+    }
+
+    return await writeResource(directory, resource, { ...options, type: 'domain' });
+  };
+
+/**
+ * Version a domain by it's id.
+ *
+ * Takes the latest domain and moves it to a versioned directory.
+ * All files with this domain are also versioned. (e.g /domains/Payment/openapi.yml)
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionDomain } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest Payment domain to a versioned directory
+ * // the version within that domain is used as the version number.
+ * await versionDomain('Payment');
+ *
+ * ```
+ */
+export const versionDomain = (directory: string) => async (id: string) => versionResource(directory, id);
+
+/**
+ * Delete a domain at it's given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmDomain } = utils('/path/to/eventcatalog');
+ *
+ * // Removes the domain at domains/Payment
+ * await rmDomain('/Payment');
+ * ```
+ */
+export const rmDomain = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+/**
+ * Delete a domain by it's id.
+ *
+ * Optionally specify a version to delete a specific version of the domain.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmDomainById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest Payment event
+ * await rmDomainById('Payment');
+ *
+ * // deletes a specific version of the Payment event
+ * await rmDomainById('Payment', '0.0.1');
+ * ```
+ */
+export const rmDomainById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) =>
+  rmResourceById(directory, id, version, { type: 'domain', persistFiles });
+
+/**
+ * Add a file to a domain by it's id.
+ *
+ * Optionally specify a version to add a file to a specific version of the domain.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addFileToDomain } = utils('/path/to/eventcatalog');
+ *
+ * // adds a file to the latest Payment event
+ * await addFileToDomain('Payment', { content: 'Hello world', fileName: 'hello.txt' });
+ *
+ * // adds a file to a specific version of the Payment event
+ * await addFileToDomain('Payment', { content: 'Hello world', fileName: 'hello.txt' }, '0.0.1');
+ *
+ * ```
+ */
+
+export const addFileToDomain =
+  (directory: string) => async (id: string, file: { content: string; fileName: string }, version?: string) =>
+    addFileToResource(directory, id, file, version);
+
+/**
+ * Adds a ubiquitous language dictionary to a domain.
+ *
+ * Optionally specify a version to add a ubiquitous language dictionary to a specific version of the domain.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addUbiquitousLanguageToDomain } = utils('/path/to/eventcatalog');
+ *
+ * // Adds a ubiquitous language dictionary to the latest Payment domain
+ * await addUbiquitousLanguageToDomain('Payment', { dictionary: [{ id: 'Order', name: 'Order', summary: 'All things to do with the payment systems', description: 'This is a description', icon: 'KeyIcon' }] });
+ *
+ * // Adds a ubiquitous language dictionary to a specific version of the domain
+ * await addUbiquitousLanguageToDomain('Payment', { dictionary: [{ id: 'Order', name: 'Order', summary: 'All things to do with the payment systems', description: 'This is a description', icon: 'KeyIcon' }] }, '0.0.1');
+ * ```
+ */
+
+export const addUbiquitousLanguageToDomain =
+  (directory: string) => async (id: string, ubiquitousLanguageDictionary: UbiquitousLanguageDictionary, version?: string) => {
+    const content = matter.stringify('', {
+      ...ubiquitousLanguageDictionary,
+    });
+    await addFileToResource(directory, id, { content, fileName: 'ubiquitous-language.mdx' }, version);
+  };
+
+/**
+ * Returns the ubiquitous language dictionary from a domain.
+ *
+ * Optionally specify a version to get the ubiquitous language dictionary from a specific version of the domain.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getUbiquitousLanguageFromDomain } = utils('/path/to/eventcatalog');
+ *
+ * const ubiquitousLanguage = await getUbiquitousLanguageFromDomain('Payment');
+ *
+ * // Returns the ubiquitous language dictionary from a specific version of the domain
+ * const ubiquitousLanguage = await getUbiquitousLanguageFromDomain('Payment', '0.0.1');
+ * ```
+ */
+export const getUbiquitousLanguageFromDomain = (directory: string) => async (id: string, version?: string) => {
+  const pathToDomain = (await findFileById(directory, id, version)) || '';
+  const pathToUbiquitousLanguage = path.join(path.dirname(pathToDomain), 'ubiquitous-language.mdx');
+
+  const fileExists = fsSync.existsSync(pathToUbiquitousLanguage);
+
+  if (!fileExists) {
+    return undefined;
+  }
+
+  const content = await readMdxFile(pathToUbiquitousLanguage);
+
+  return content;
+};
+
+/**
+ * Check to see if the catalog has a version for the given domain.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { domainHasVersion } = utils('/path/to/eventcatalog');
+ *
+ * // returns true if version is found for the given event and version (supports semver)
+ * await domainHasVersion('Orders', '0.0.1');
+ * await domainHasVersion('Orders', 'latest');
+ * await domainHasVersion('Orders', '0.0.x');*
+ *
+ * ```
+ */
+export const domainHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+/**
+ * Add a service to a domain by it's id.
+ *
+ * Optionally specify a version to add the service to a specific version of the domain.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * // Adds a service to the domain
+ * const { addServiceToDomain } = utils('/path/to/eventcatalog');
+ *
+ * // Adds a service (Orders Service) to the domain (Orders)
+ * await addServiceToDomain('Orders', { service: 'Order Service', version: '2.0.0' });
+ * // Adds a service (Orders Service) to the domain (Orders) with a specific version
+ * await addServiceToDomain('Orders', { service: 'Order Service', version: '2.0.0' }, '1.0.0');
+ * ```
+ */
+
+export const addServiceToDomain =
+  (directory: string) => async (id: string, service: { id: string; version: string }, version?: string) => {
+    let domain: Domain = await getDomain(directory)(id, version);
+    const domainPath = await getResourcePath(directory, id, version);
+
+    // Get the extension of the file
+    const extension = path.extname(domainPath?.fullPath || '');
+
+    if (domain.services === undefined) {
+      domain.services = [];
+    }
+
+    const serviceExistsInList = domain.services.some((s) => s.id === service.id && s.version === service.version);
+
+    if (serviceExistsInList) {
+      return;
+    }
+
+    // Add service to the list
+    domain.services.push(service);
+
+    const writeDir = await resolveDomainWriteDirectory(directory, id, version);
+    await rmDomainById(directory)(id, version, true);
+    await writeDomain(writeDir)(domain, { format: extension === '.md' ? 'md' : 'mdx' });
+  };
+
+/**
+ * Add an agent to a domain by its id.
+ *
+ * Optionally specify a version to add the agent to a specific version of the domain.
+ */
+export const addAgentToDomain =
+  (directory: string) => async (id: string, agent: { id: string; version: string }, version?: string) => {
+    let domain: Domain = await getDomain(directory)(id, version);
+    const domainPath = await getResourcePath(directory, id, version);
+
+    const extension = path.extname(domainPath?.fullPath || '');
+
+    if (domain.agents === undefined) {
+      domain.agents = [];
+    }
+
+    const agentExistsInList = domain.agents.some((a) => a.id === agent.id && a.version === agent.version);
+
+    if (agentExistsInList) {
+      return;
+    }
+
+    domain.agents.push(agent);
+
+    const writeDir = await resolveDomainWriteDirectory(directory, id, version);
+    await rmDomainById(directory)(id, version, true);
+    await writeDomain(writeDir)(domain, { format: extension === '.md' ? 'md' : 'mdx' });
+  };
+
+/**
+ * Add a subdomain to a domain by it's id.
+ * Optionally specify a version to add the subdomain to a specific version of the domain
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * // Adds a subdomain to the given domain
+ * const { addSubDomainToDomain } = utils('/path/to/eventcatalog');
+ *
+ * // Adds a subdomain (Payment Domain) to the domain (Orders)
+ * await addSubDomainToDomain('Orders', { service: 'Payment Domain', version: '2.0.0' });
+ * // Adds a subdomain (Inventory Domain) to the domain (Orders) with a specific version
+ * await addSubDomainToDomain('Orders', { service: 'Inventory Domain', version: '2.0.0' }, '1.0.0');
+ * ```
+ */
+
+export const addSubDomainToDomain =
+  (directory: string) => async (id: string, subDomain: { id: string; version: string }, version?: string) => {
+    let domain: Domain = await getDomain(directory)(id, version);
+    const domainPath = await getResourcePath(directory, id, version);
+
+    // Get the extension of the file
+    const extension = path.extname(domainPath?.fullPath || '');
+
+    if (domain.domains === undefined) {
+      domain.domains = [];
+    }
+
+    const subDomainExistsInList = domain.domains.some((s) => s.id === subDomain.id && s.version === subDomain.version);
+
+    if (subDomainExistsInList) {
+      return;
+    }
+
+    // Add subdomain to the list
+    domain.domains.push(subDomain);
+
+    const writeDir = await resolveDomainWriteDirectory(directory, id, version);
+    await rmDomainById(directory)(id, version, true);
+    await writeDomain(writeDir)(domain, { format: extension === '.md' ? 'md' : 'mdx' });
+  };
+
+/**
+ * Add a system to a domain by its id.
+ * Optionally specify a version to add the system to a specific version of the domain.
+ */
+export const addSystemToDomain =
+  (directory: string) => async (id: string, system: { id: string; version: string }, version?: string) => {
+    let domain: Domain = await getDomain(directory)(id, version);
+    const domainPath = await getResourcePath(directory, id, version);
+
+    const extension = path.extname(domainPath?.fullPath || '');
+
+    if (domain.systems === undefined) {
+      domain.systems = [];
+    }
+
+    const systemExistsInList = domain.systems.some((s) => s.id === system.id && s.version === system.version);
+
+    if (systemExistsInList) {
+      return;
+    }
+
+    domain.systems.push(system);
+
+    const writeDir = await resolveDomainWriteDirectory(directory, id, version);
+    await rmDomainById(directory)(id, version, true);
+    await writeDomain(writeDir)(domain, { format: extension === '.md' ? 'md' : 'mdx' });
+  };
+
+/**
+ * Add an entity to a domain by its id.
+ * Optionally specify a version to add the entity to a specific version of the domain.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * // Adds an entity to the domain
+ * const { addEntityToDomain } = utils('/path/to/eventcatalog');
+ *
+ * // Adds an entity (User) to the domain (Orders)
+ * await addEntityToDomain('Orders', { id: 'User', version: '1.0.0' });
+ * // Adds an entity (Product) to the domain (Orders) with a specific version
+ * await addEntityToDomain('Orders', { id: 'Product', version: '2.0.0' }, '1.0.0');
+ * ```
+ */
+export const addEntityToDomain =
+  (directory: string) => async (id: string, entity: { id: string; version: string }, version?: string) => {
+    let domain: Domain = await getDomain(directory)(id, version);
+    const domainPath = await getResourcePath(directory, id, version);
+
+    // Get the extension of the file
+    const extension = path.extname(domainPath?.fullPath || '');
+
+    if (domain.entities === undefined) {
+      domain.entities = [];
+    }
+
+    const entityExistsInList = domain.entities.some((e) => e.id === entity.id && e.version === entity.version);
+
+    if (entityExistsInList) {
+      return;
+    }
+
+    // Add entity to the list
+    domain.entities.push(entity);
+
+    const writeDir = await resolveDomainWriteDirectory(directory, id, version);
+    await rmDomainById(directory)(id, version, true);
+    await writeDomain(writeDir)(domain, { format: extension === '.md' ? 'md' : 'mdx' });
+  };
+
+/**
+ * Add a data product to a domain by its id.
+ * Optionally specify a version to add the data product to a specific version of the domain.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * // Adds a data product to the domain
+ * const { addDataProductToDomain } = utils('/path/to/eventcatalog');
+ *
+ * // Adds a data product (CustomerDataProduct) to the domain (Orders)
+ * await addDataProductToDomain('Orders', { id: 'CustomerDataProduct', version: '1.0.0' });
+ * // Adds a data product (SalesDataProduct) to the domain (Orders) with a specific version
+ * await addDataProductToDomain('Orders', { id: 'SalesDataProduct', version: '2.0.0' }, '1.0.0');
+ * ```
+ */
+export const addDataProductToDomain =
+  (directory: string) => async (id: string, dataProduct: { id: string; version: string }, version?: string) => {
+    let domain: Domain = await getDomain(directory)(id, version);
+    const domainPath = await getResourcePath(directory, id, version);
+
+    // Get the extension of the file
+    const extension = path.extname(domainPath?.fullPath || '');
+
+    if (domain.dataProducts === undefined) {
+      domain.dataProducts = [];
+    }
+
+    const dataProductExistsInList = domain.dataProducts.some(
+      (dp) => dp.id === dataProduct.id && dp.version === dataProduct.version
+    );
+
+    if (dataProductExistsInList) {
+      return;
+    }
+
+    // Add data product to the list
+    domain.dataProducts.push(dataProduct);
+
+    const writeDir = await resolveDomainWriteDirectory(directory, id, version);
+    await rmDomainById(directory)(id, version, true);
+    await writeDomain(writeDir)(domain, { format: extension === '.md' ? 'md' : 'mdx' });
+  };
+
+/**
+ * Add an event/command/query to a domain by its id.
+ *
+ * Optionally specify a version to add the message to a specific version of the domain.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * // Adds an event to the domain
+ * const { addEventToDomain, addCommandToDomain, addQueryToDomain } = utils('/path/to/eventcatalog');
+ *
+ * // Adds a new event (OrderCreated) that the Orders domain will send
+ * await addEventToDomain('Orders', 'sends', { id: 'OrderCreated', version: '2.0.0' });
+ *
+ * // Adds a new event (PaymentProcessed) that the Orders domain will receive
+ * await addEventToDomain('Orders', 'receives', { id: 'PaymentProcessed', version: '1.0.0' });
+ *
+ * // Adds a new command (ProcessOrder) that the Orders domain will receive
+ * await addCommandToDomain('Orders', 'receives', { id: 'ProcessOrder', version: '1.0.0' });
+ *
+ * // Adds a message to a specific version of the domain
+ * await addEventToDomain('Orders', 'sends', { id: 'OrderShipped', version: '1.0.0' }, '2.0.0');
+ * ```
+ */
+export const addMessageToDomain =
+  (directory: string) =>
+  async (
+    id: string,
+    direction: string,
+    message: { id: string; version: string; fields?: string[]; group?: string },
+    version?: string
+  ) => {
+    let domain: Domain = await getDomain(directory)(id, version);
+    const domainPath = await getResourcePath(directory, id, version);
+    const extension = path.extname(domainPath?.fullPath || '');
+
+    if (direction === 'sends') {
+      if (domain.sends === undefined) {
+        domain.sends = [];
+      }
+      // Check if the message is already in the list
+      for (let i = 0; i < domain.sends.length; i++) {
+        if (domain.sends[i].id === message.id && domain.sends[i].version === message.version) {
+          return;
+        }
+      }
+      domain.sends.push(buildMessagePointer(message));
+    } else if (direction === 'receives') {
+      if (domain.receives === undefined) {
+        domain.receives = [];
+      }
+      // Check if the message is already in the list
+      for (let i = 0; i < domain.receives.length; i++) {
+        if (domain.receives[i].id === message.id && domain.receives[i].version === message.version) {
+          return;
+        }
+      }
+      domain.receives.push(buildMessagePointer(message));
+    } else {
+      throw new Error(`Direction ${direction} is invalid, only 'receives' and 'sends' are supported`);
+    }
+
+    const writeDir = await resolveDomainWriteDirectory(directory, id, version);
+    await rmDomainById(directory)(id, version, true);
+    await writeDomain(writeDir)(domain, { format: extension === '.md' ? 'md' : 'mdx' });
+  };
diff --git a/packages/sdk/src/dsl/channel.ts b/packages/sdk/src/dsl/channel.ts
new file mode 100644
index 000000000..5b2ae7abe
--- /dev/null
+++ b/packages/sdk/src/dsl/channel.ts
@@ -0,0 +1,41 @@
+import type { Channel } from '../types';
+
+export function channelToDSL(resource: Channel): string {
+  const lines: string[] = [];
+
+  if (resource.version) {
+    lines.push(`  version ${resource.version}`);
+  }
+
+  if (resource.name) {
+    lines.push(`  name "${resource.name}"`);
+  }
+
+  if (resource.address) {
+    lines.push(`  address "${resource.address}"`);
+  }
+
+  if (resource.protocols && resource.protocols.length > 0) {
+    for (const protocol of resource.protocols) {
+      lines.push(`  protocol "${protocol}"`);
+    }
+  }
+
+  if (resource.summary) {
+    lines.push(`  summary "${resource.summary.trim()}"`);
+  }
+
+  if (resource.routes && resource.routes.length > 0) {
+    for (const route of resource.routes) {
+      let ref = route.id;
+      if (route.version) ref += `@${route.version}`;
+      lines.push(`  route ${ref}`);
+    }
+  }
+
+  if (!lines.length) {
+    return `channel ${resource.id}`;
+  }
+
+  return `channel ${resource.id} {\n${lines.join('\n')}\n}`;
+}
diff --git a/packages/sdk/src/dsl/container.ts b/packages/sdk/src/dsl/container.ts
new file mode 100644
index 000000000..0d20ea6df
--- /dev/null
+++ b/packages/sdk/src/dsl/container.ts
@@ -0,0 +1,39 @@
+import type { Container } from '../types';
+import { serializeBaseFields } from './utils';
+
+export function containerToDSL(resource: Container): string {
+  const lines: string[] = [];
+  const baseFields = serializeBaseFields(resource);
+  if (baseFields) lines.push(baseFields);
+
+  if (resource.container_type) {
+    lines.push(`  container-type ${resource.container_type}`);
+  }
+
+  if (resource.technology) {
+    lines.push(`  technology "${resource.technology}"`);
+  }
+
+  if (resource.authoritative === true) {
+    lines.push(`  authoritative true`);
+  }
+
+  if (resource.access_mode) {
+    lines.push(`  access-mode ${resource.access_mode}`);
+  }
+
+  if (resource.classification) {
+    lines.push(`  classification ${resource.classification}`);
+  }
+
+  if (resource.residency) {
+    lines.push(`  residency "${resource.residency}"`);
+  }
+
+  if (resource.retention) {
+    lines.push(`  retention "${resource.retention}"`);
+  }
+
+  const body = lines.join('\n');
+  return `container ${resource.id} {\n${body}\n}`;
+}
diff --git a/packages/sdk/src/dsl/domain.ts b/packages/sdk/src/dsl/domain.ts
new file mode 100644
index 000000000..73f35a7af
--- /dev/null
+++ b/packages/sdk/src/dsl/domain.ts
@@ -0,0 +1,202 @@
+import type { Domain, Service, Event, Command, Query, Channel, Team, User } from '../types';
+import { serializeBaseFields, serializeMessagePointers, resolveMessageType, buildMessageTypeIndex } from './utils';
+import type { MessageTypeIndex } from './utils';
+import { serviceToDSL } from './service';
+import { messageToDSL } from './message';
+import { channelToDSL } from './channel';
+import { teamToDSL, userToDSL } from './owner';
+
+interface DomainToDSLOptions {
+  catalogDir: string;
+  hydrate?: boolean;
+  _seen?: Set<string>;
+  _msgIndex?: MessageTypeIndex;
+}
+
+export interface DomainResolvers {
+  getService?: (id: string, version?: string) => Promise<Service | undefined>;
+  getDomain?: (id: string, version?: string) => Promise<Domain | undefined>;
+  getMessage?: (id: string, version?: string) => Promise<Event | Command | Query | undefined>;
+  getChannel?: (id: string, version?: string) => Promise<Channel | undefined>;
+  getTeam?: (id: string) => Promise<Team | undefined>;
+  getUser?: (id: string) => Promise<User | undefined>;
+}
+
+async function hydrateOwners(owners: string[] | undefined, resolvers: DomainResolvers, seen: Set<string>, parts: string[]) {
+  if (!owners || !resolvers.getTeam || !resolvers.getUser) return;
+  for (const ownerId of owners) {
+    const key = `owner:${ownerId}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const team = await resolvers.getTeam(ownerId);
+    if (team) {
+      parts.push(teamToDSL(team));
+      continue;
+    }
+
+    const user = await resolvers.getUser(ownerId);
+    if (user) {
+      parts.push(userToDSL(user));
+    }
+  }
+}
+
+async function hydrateChannelsFromMessages(
+  messages: {
+    id: string;
+    version?: string;
+    to?: { id: string; version?: string }[];
+    from?: { id: string; version?: string }[];
+  }[],
+  resolvers: DomainResolvers,
+  seen: Set<string>,
+  parts: string[]
+) {
+  if (!resolvers.getChannel) return;
+  for (const msg of messages) {
+    const channels = (msg as any).to || (msg as any).from;
+    if (!channels) continue;
+    for (const ch of channels) {
+      const key = `channel:${ch.id}@${ch.version || 'latest'}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const channel = await resolvers.getChannel(ch.id, ch.version);
+      if (channel) {
+        parts.push(channelToDSL(channel));
+      }
+    }
+  }
+}
+
+async function buildDomainBody(
+  resource: Domain,
+  options: DomainToDSLOptions,
+  resolvers: DomainResolvers | undefined,
+  keyword: 'domain' | 'subdomain'
+): Promise<{ topLevelParts: string[]; block: string }> {
+  const { catalogDir, hydrate = false, _seen = new Set<string>() } = options;
+  const msgIndex = options._msgIndex || buildMessageTypeIndex(catalogDir);
+  const topLevelParts: string[] = [];
+
+  if (hydrate && resolvers) {
+    // Hydrate services (and their owners, channels, messages)
+    if (resource.services && resource.services.length > 0 && resolvers.getService) {
+      for (const svcRef of resource.services) {
+        const svcKey = `service:${svcRef.id}@${svcRef.version || 'latest'}`;
+        if (_seen.has(svcKey)) continue;
+        _seen.add(svcKey);
+
+        const svc = await resolvers.getService(svcRef.id, svcRef.version);
+        if (svc) {
+          // Hydrate service owners
+          await hydrateOwners(svc.owners, resolvers, _seen, topLevelParts);
+          // Hydrate service channels
+          const svcMessages = [...(svc.sends || []), ...(svc.receives || [])];
+          await hydrateChannelsFromMessages(svcMessages, resolvers, _seen, topLevelParts);
+          // Hydrate service (includes message hydration)
+          const svcDsl = await serviceToDSL(svc, { catalogDir, hydrate: true, _seen, _msgIndex: msgIndex }, resolvers.getMessage);
+          topLevelParts.push(svcDsl);
+        }
+      }
+    }
+
+    // Hydrate domain-level channels
+    const domainMessages = [...(resource.sends || []), ...(resource.receives || [])];
+    await hydrateChannelsFromMessages(domainMessages, resolvers, _seen, topLevelParts);
+
+    // Hydrate domain-level messages
+    if (resolvers.getMessage) {
+      for (const msg of domainMessages) {
+        const key = `${msg.id}@${msg.version || 'latest'}`;
+        if (_seen.has(key)) continue;
+        _seen.add(key);
+
+        const msgType = resolveMessageType(msgIndex, msg.id);
+        if (!msgType) continue;
+
+        const msgResource = await resolvers.getMessage(msg.id, msg.version);
+        if (msgResource) {
+          topLevelParts.push(messageToDSL(msgResource, msgType));
+        }
+      }
+    }
+  }
+
+  const lines: string[] = [];
+  const baseFields = serializeBaseFields(resource);
+  if (baseFields) lines.push(baseFields);
+
+  // Service references
+  if (resource.services && resource.services.length > 0) {
+    for (const svc of resource.services) {
+      let ref = svc.id;
+      if (svc.version) ref += `@${svc.version}`;
+      lines.push(`  service ${ref}`);
+    }
+  }
+
+  if (resource.sends && resource.sends.length > 0) {
+    const sendsStr = serializeMessagePointers(resource.sends, 'sends', msgIndex);
+    if (sendsStr) lines.push(sendsStr);
+  }
+
+  if (resource.receives && resource.receives.length > 0) {
+    const recvStr = serializeMessagePointers(resource.receives, 'receives', msgIndex);
+    if (recvStr) lines.push(recvStr);
+  }
+
+  // Subdomain blocks (inline)
+  if (resource.domains && resource.domains.length > 0) {
+    if (hydrate && resolvers?.getDomain) {
+      for (const subRef of resource.domains) {
+        const subKey = `domain:${subRef.id}@${subRef.version || 'latest'}`;
+        if (_seen.has(subKey)) continue;
+        _seen.add(subKey);
+
+        const subDomain = await resolvers.getDomain(subRef.id, subRef.version);
+        if (subDomain) {
+          // Hydrate subdomain owners at top level
+          await hydrateOwners(subDomain.owners, resolvers, _seen, topLevelParts);
+          // Recursively build subdomain
+          const sub = await buildDomainBody(
+            subDomain,
+            { catalogDir, hydrate, _seen, _msgIndex: msgIndex },
+            resolvers,
+            'subdomain'
+          );
+          topLevelParts.push(...sub.topLevelParts);
+          // Indent the subdomain block to nest inside the parent
+          const indented = sub.block
+            .split('\n')
+            .map((line) => `  ${line}`)
+            .join('\n');
+          lines.push(indented);
+        }
+      }
+    } else {
+      // Non-hydrated: just output references
+      for (const sub of resource.domains) {
+        let ref = sub.id;
+        if (sub.version) ref += `@${sub.version}`;
+        lines.push(`  subdomain ${ref}`);
+      }
+    }
+  }
+
+  const body = lines.join('\n');
+  const block = `${keyword} ${resource.id} {\n${body}\n}`;
+
+  return { topLevelParts, block };
+}
+
+export async function domainToDSL(resource: Domain, options: DomainToDSLOptions, resolvers?: DomainResolvers): Promise<string> {
+  const { catalogDir, hydrate = false, _seen = new Set<string>() } = options;
+  const msgIndex = options._msgIndex || buildMessageTypeIndex(catalogDir);
+
+  const result = await buildDomainBody(resource, { catalogDir, hydrate, _seen, _msgIndex: msgIndex }, resolvers, 'domain');
+  const parts = [...result.topLevelParts, result.block];
+
+  return parts.join('\n\n');
+}
diff --git a/packages/sdk/src/dsl/index.ts b/packages/sdk/src/dsl/index.ts
new file mode 100644
index 000000000..e2a9869d6
--- /dev/null
+++ b/packages/sdk/src/dsl/index.ts
@@ -0,0 +1,309 @@
+import type { Event, Command, Query, Service, Domain, Team, User, Channel, Container } from '../types';
+import { messageToDSL } from './message';
+import { serviceToDSL } from './service';
+import { domainToDSL } from './domain';
+import { teamToDSL, userToDSL } from './owner';
+import { channelToDSL } from './channel';
+import { containerToDSL } from './container';
+import { buildMessageTypeIndex, resolveMessageType, msgVersionMatches } from './utils';
+import type { MessageType, MessageTypeIndex } from './utils';
+
+type ResourceType = 'event' | 'command' | 'query' | 'service' | 'domain';
+
+export interface ToDSLOptions {
+  type: ResourceType;
+  hydrate?: boolean;
+}
+
+type AnyResource = Event | Command | Query | Service | Domain;
+
+export interface ResourceResolvers {
+  getEvent: (id: string, version?: string) => Promise<Event | undefined>;
+  getCommand: (id: string, version?: string) => Promise<Command | undefined>;
+  getQuery: (id: string, version?: string) => Promise<Query | undefined>;
+  getService: (id: string, version?: string) => Promise<Service | undefined>;
+  getServices: (options?: { latestOnly?: boolean }) => Promise<Service[]>;
+  getDomain: (id: string, version?: string) => Promise<Domain | undefined>;
+  getChannel: (id: string, version?: string) => Promise<Channel | undefined>;
+  getChannels: (options?: { latestOnly?: boolean }) => Promise<Channel[]>;
+  getContainer: (id: string, version?: string) => Promise<Container | undefined>;
+  getTeam: (id: string) => Promise<Team | undefined>;
+  getUser: (id: string) => Promise<User | undefined>;
+}
+
+function getMessage(resolvers: ResourceResolvers, msgIndex: MessageTypeIndex) {
+  return async (id: string, version?: string) => {
+    const msgType = resolveMessageType(msgIndex, id);
+    if (!msgType) return undefined;
+    switch (msgType) {
+      case 'event':
+        return resolvers.getEvent(id, version);
+      case 'command':
+        return resolvers.getCommand(id, version);
+      case 'query':
+        return resolvers.getQuery(id, version);
+    }
+  };
+}
+
+async function hydrateChannel(
+  channelId: string,
+  channelVersion: string | undefined,
+  resolvers: ResourceResolvers,
+  seen: Set<string>,
+  parts: string[]
+) {
+  const key = `channel:${channelId}@${channelVersion || 'latest'}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+
+  const channel = await resolvers.getChannel(channelId, channelVersion);
+  if (!channel) return;
+
+  // Hydrate any channels this channel routes to (downstream)
+  if (channel.routes && channel.routes.length > 0) {
+    for (const route of channel.routes) {
+      await hydrateChannel(route.id, route.version, resolvers, seen, parts);
+    }
+  }
+
+  // Hydrate any channels that route TO this channel (upstream)
+  const allChannels = (await resolvers.getChannels({ latestOnly: false })) || [];
+  const targetVersion = channelVersion || channel.version;
+  for (const upstream of allChannels) {
+    if (!upstream.routes) continue;
+    const routesToThis = upstream.routes.some((route) => {
+      if (route.id !== channelId) return false;
+      if (!route.version) {
+        // Unversioned routes point to latest, so only match when hydrating latest.
+        return !channelVersion;
+      }
+      return msgVersionMatches(route.version, targetVersion);
+    });
+    if (routesToThis) {
+      await hydrateChannel(upstream.id, upstream.version, resolvers, seen, parts);
+    }
+  }
+
+  parts.push(channelToDSL(channel));
+}
+
+async function hydrateChannels(resource: Service | Domain, resolvers: ResourceResolvers, seen: Set<string>, parts: string[]) {
+  const allMessages = [...((resource as Service).sends || []), ...((resource as Service).receives || [])];
+  for (const msg of allMessages) {
+    const channels = 'to' in msg ? (msg as any).to : 'from' in msg ? (msg as any).from : undefined;
+    if (!channels) continue;
+    for (const ch of channels) {
+      await hydrateChannel(ch.id, ch.version, resolvers, seen, parts);
+    }
+  }
+}
+
+async function hydrateContainers(resource: Service, resolvers: ResourceResolvers, seen: Set<string>, parts: string[]) {
+  const allContainers = [...(resource.writesTo || []), ...(resource.readsFrom || [])];
+  for (const ref of allContainers) {
+    const key = `container:${ref.id}@${ref.version || 'latest'}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const container = await resolvers.getContainer(ref.id, ref.version);
+    if (!container) continue;
+
+    parts.push(containerToDSL(container));
+  }
+}
+
+async function hydrateOwners(owners: string[] | undefined, resolvers: ResourceResolvers, seen: Set<string>, parts: string[]) {
+  if (!owners) return;
+  for (const ownerId of owners) {
+    const key = `owner:${ownerId}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const team = await resolvers.getTeam(ownerId);
+    if (team) {
+      parts.push(teamToDSL(team));
+      continue;
+    }
+
+    const user = await resolvers.getUser(ownerId);
+    if (user) {
+      parts.push(userToDSL(user));
+    }
+  }
+}
+
+async function hydrateMessageServices(
+  messageId: string,
+  messageVersion: string | undefined,
+  resolvers: ResourceResolvers,
+  seen: Set<string>,
+  parts: string[],
+  catalogDir: string,
+  msgIndex: MessageTypeIndex
+) {
+  const services = (await resolvers.getServices({ latestOnly: false })) || [];
+  for (const service of services) {
+    const key = `service:${service.id}@${service.version || 'latest'}`;
+    if (seen.has(key)) continue;
+
+    const referencesMessage = [...(service.sends || []), ...(service.receives || [])].some(
+      (msg) => msg.id === messageId && msgVersionMatches(msg.version, messageVersion)
+    );
+
+    if (referencesMessage) {
+      seen.add(key);
+      const matchMsg = (msg: { id: string; version?: string }) =>
+        msg.id === messageId && msgVersionMatches(msg.version, messageVersion);
+      const resolvePointerVersion = <T extends { id: string; version?: string }>(msg: T): T => {
+        if (msg.id === messageId && msg.version && msg.version !== messageVersion && messageVersion) {
+          return { ...msg, version: messageVersion };
+        }
+        return msg;
+      };
+      const filtered: Service = {
+        ...service,
+        sends: service.sends?.filter(matchMsg).map(resolvePointerVersion),
+        receives: service.receives?.filter(matchMsg).map(resolvePointerVersion),
+      };
+      await hydrateChannels(filtered, resolvers, seen, parts);
+      parts.push(await serviceToDSL(filtered, { catalogDir, hydrate: false, _seen: new Set(seen), _msgIndex: msgIndex }));
+    }
+  }
+}
+
+async function hydrateRelatedServices(
+  messages: { id: string; version?: string }[],
+  direction: 'sends' | 'receives',
+  resolvers: ResourceResolvers,
+  seen: Set<string>,
+  parts: string[],
+  catalogDir: string,
+  msgIndex: MessageTypeIndex
+) {
+  if (!messages.length) return;
+
+  const referencesHydratedMessage = (msg: { id: string; version?: string }) =>
+    messages.some((input) => msg.id === input.id && msgVersionMatches(msg.version, input.version));
+
+  const services = (await resolvers.getServices({ latestOnly: false })) || [];
+  for (const service of services) {
+    const key = `service:${service.id}@${service.version || 'latest'}`;
+    if (seen.has(key)) continue;
+
+    if (direction === 'sends') {
+      const matchedPointers = (service.sends || []).filter(referencesHydratedMessage);
+      if (matchedPointers.length > 0) {
+        seen.add(key);
+        const filtered: Service = {
+          ...service,
+          sends: matchedPointers,
+          receives: undefined,
+        };
+        await hydrateChannels(filtered, resolvers, seen, parts);
+        parts.push(await serviceToDSL(filtered, { catalogDir, hydrate: false, _seen: new Set(seen), _msgIndex: msgIndex }));
+      }
+    } else {
+      const matchedPointers = (service.receives || []).filter(referencesHydratedMessage);
+      if (matchedPointers.length > 0) {
+        seen.add(key);
+        const filtered: Service = {
+          ...service,
+          sends: undefined,
+          receives: matchedPointers,
+        };
+        await hydrateChannels(filtered, resolvers, seen, parts);
+        parts.push(await serviceToDSL(filtered, { catalogDir, hydrate: false, _seen: new Set(seen), _msgIndex: msgIndex }));
+      }
+    }
+  }
+}
+
+export const toDSL =
+  (catalogDir: string, resolvers: ResourceResolvers) =>
+  async (resource: AnyResource | AnyResource[], options: ToDSLOptions): Promise<string> => {
+    const resources = Array.isArray(resource) ? resource : [resource];
+    const seen = new Set<string>();
+    const parts: string[] = [];
+    const msgIndex = buildMessageTypeIndex(catalogDir);
+
+    for (const res of resources) {
+      const key = `${options.type}:${res.id}@${res.version || 'latest'}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      switch (options.type) {
+        case 'event':
+        case 'command':
+        case 'query':
+          if (options.hydrate) {
+            await hydrateOwners(res.owners, resolvers, seen, parts);
+            await hydrateMessageServices(res.id, res.version, resolvers, seen, parts, catalogDir, msgIndex);
+          }
+          parts.push(messageToDSL(res as Event | Command | Query, options.type as MessageType));
+          break;
+        case 'service':
+          if (options.hydrate) {
+            await hydrateOwners(res.owners, resolvers, seen, parts);
+            await hydrateChannels(res as Service, resolvers, seen, parts);
+            await hydrateContainers(res as Service, resolvers, seen, parts);
+          }
+          parts.push(
+            await serviceToDSL(
+              res as Service,
+              { catalogDir, hydrate: options.hydrate, _seen: seen, _msgIndex: msgIndex },
+              getMessage(resolvers, msgIndex)
+            )
+          );
+          if (options.hydrate) {
+            const svc = res as Service;
+            // For messages this service sends: find services that receive them (downstream consumers)
+            await hydrateRelatedServices(svc.sends || [], 'receives', resolvers, seen, parts, catalogDir, msgIndex);
+            // For messages this service receives: find services that send them (upstream producers)
+            await hydrateRelatedServices(svc.receives || [], 'sends', resolvers, seen, parts, catalogDir, msgIndex);
+          }
+          break;
+        case 'domain':
+          if (options.hydrate) {
+            await hydrateOwners(res.owners, resolvers, seen, parts);
+          }
+          parts.push(
+            await domainToDSL(
+              res as Domain,
+              { catalogDir, hydrate: options.hydrate, _seen: seen, _msgIndex: msgIndex },
+              {
+                getService: resolvers.getService,
+                getDomain: resolvers.getDomain,
+                getMessage: getMessage(resolvers, msgIndex),
+                getChannel: resolvers.getChannel,
+                getTeam: resolvers.getTeam,
+                getUser: resolvers.getUser,
+              }
+            )
+          );
+          if (options.hydrate) {
+            const domain = res as Domain;
+            const allSends: { id: string; version?: string }[] = [];
+            const allReceives: { id: string; version?: string }[] = [];
+
+            if (domain.services?.length) {
+              for (const svcRef of domain.services) {
+                const svc = await resolvers.getService(svcRef.id, svcRef.version);
+                if (svc) {
+                  allSends.push(...(svc.sends || []));
+                  allReceives.push(...(svc.receives || []));
+                }
+              }
+            }
+
+            // Downstream: services that receive what domain services send
+            await hydrateRelatedServices(allSends, 'receives', resolvers, seen, parts, catalogDir, msgIndex);
+            // Upstream: services that send what domain services receive
+            await hydrateRelatedServices(allReceives, 'sends', resolvers, seen, parts, catalogDir, msgIndex);
+          }
+          break;
+      }
+    }
+
+    return parts.join('\n\n');
+  };
diff --git a/packages/sdk/src/dsl/message.ts b/packages/sdk/src/dsl/message.ts
new file mode 100644
index 000000000..67e3f889f
--- /dev/null
+++ b/packages/sdk/src/dsl/message.ts
@@ -0,0 +1,12 @@
+import type { Event, Command, Query } from '../types';
+import { serializeBaseFields, type MessageType } from './utils';
+
+export function messageToDSL(resource: Event | Command | Query, type: MessageType): string {
+  const body = serializeBaseFields(resource);
+
+  if (!body) {
+    return `${type} ${resource.id}`;
+  }
+
+  return `${type} ${resource.id} {\n${body}\n}`;
+}
diff --git a/packages/sdk/src/dsl/owner.ts b/packages/sdk/src/dsl/owner.ts
new file mode 100644
index 000000000..c786f0a84
--- /dev/null
+++ b/packages/sdk/src/dsl/owner.ts
@@ -0,0 +1,26 @@
+import type { Team, User } from '../types';
+
+export function teamToDSL(team: Team): string {
+  const lines: string[] = [];
+
+  if (team.name) lines.push(`  name "${team.name}"`);
+  if (team.avatarUrl) lines.push(`  avatar "${team.avatarUrl}"`);
+  if (team.role) lines.push(`  role "${team.role}"`);
+  if (team.summary) lines.push(`  summary "${team.summary}"`);
+  if (team.email) lines.push(`  email "${team.email}"`);
+  if (team.slackDirectMessageUrl) lines.push(`  slack "${team.slackDirectMessageUrl}"`);
+
+  return `team ${team.id} {\n${lines.join('\n')}\n}`;
+}
+
+export function userToDSL(user: User): string {
+  const lines: string[] = [];
+
+  if (user.name) lines.push(`  name "${user.name}"`);
+  if (user.avatarUrl) lines.push(`  avatar "${user.avatarUrl}"`);
+  if (user.role) lines.push(`  role "${user.role}"`);
+  if (user.email) lines.push(`  email "${user.email}"`);
+  if (user.slackDirectMessageUrl) lines.push(`  slack "${user.slackDirectMessageUrl}"`);
+
+  return `user ${user.id} {\n${lines.join('\n')}\n}`;
+}
diff --git a/packages/sdk/src/dsl/service.ts b/packages/sdk/src/dsl/service.ts
new file mode 100644
index 000000000..3b190d0d0
--- /dev/null
+++ b/packages/sdk/src/dsl/service.ts
@@ -0,0 +1,92 @@
+import type { Service, Event, Command, Query } from '../types';
+import { serializeBaseFields, serializeMessagePointers, resolveMessageType, buildMessageTypeIndex } from './utils';
+import type { MessageTypeIndex } from './utils';
+import { messageToDSL } from './message';
+import { valid as semverValid } from 'semver';
+
+interface ServiceToDSLOptions {
+  catalogDir: string;
+  hydrate?: boolean;
+  _seen?: Set<string>;
+  _msgIndex?: MessageTypeIndex;
+}
+
+export async function serviceToDSL(
+  resource: Service,
+  options: ServiceToDSLOptions,
+  getMessageFn?: (id: string, version?: string) => Promise<Event | Command | Query | undefined>
+): Promise<string> {
+  const { catalogDir, hydrate = false, _seen = new Set<string>() } = options;
+  const msgIndex = options._msgIndex || buildMessageTypeIndex(catalogDir);
+  const parts: string[] = [];
+  const resolvedVersions = new Map<string, string>();
+
+  if (hydrate && getMessageFn) {
+    const allMessages = [...(resource.sends || []), ...(resource.receives || [])];
+    for (const msg of allMessages) {
+      const key = `${msg.id}@${msg.version || 'latest'}`;
+      if (_seen.has(key)) continue;
+      _seen.add(key);
+
+      const msgType = resolveMessageType(msgIndex, msg.id);
+      if (!msgType) continue;
+
+      const msgResource = await getMessageFn(msg.id, msg.version);
+      if (msgResource) {
+        parts.push(messageToDSL(msgResource, msgType));
+        // Track resolved version so semver ranges can be replaced with concrete versions
+        if (msg.version && !semverValid(msg.version) && msgResource.version) {
+          resolvedVersions.set(`${msg.id}@${msg.version}`, msgResource.version);
+        }
+      }
+    }
+  }
+
+  // Replace semver range versions with concrete resolved versions
+  const resolvePointers = <T extends { id: string; version?: string }>(pointers: T[]): T[] =>
+    pointers.map((p) => {
+      if (p.version && !semverValid(p.version)) {
+        const resolved = resolvedVersions.get(`${p.id}@${p.version}`);
+        if (resolved) return { ...p, version: resolved };
+      }
+      return p;
+    });
+
+  const sends = resource.sends ? resolvePointers(resource.sends) : undefined;
+  const receives = resource.receives ? resolvePointers(resource.receives) : undefined;
+
+  const lines: string[] = [];
+  const baseFields = serializeBaseFields(resource);
+  if (baseFields) lines.push(baseFields);
+
+  if (sends && sends.length > 0) {
+    const sendsStr = serializeMessagePointers(sends, 'sends', msgIndex);
+    if (sendsStr) lines.push(sendsStr);
+  }
+
+  if (receives && receives.length > 0) {
+    const recvStr = serializeMessagePointers(receives, 'receives', msgIndex);
+    if (recvStr) lines.push(recvStr);
+  }
+
+  if (resource.writesTo && resource.writesTo.length > 0) {
+    for (const container of resource.writesTo) {
+      let ref = container.id;
+      if (container.version) ref += `@${container.version}`;
+      lines.push(`  writes-to container ${ref}`);
+    }
+  }
+
+  if (resource.readsFrom && resource.readsFrom.length > 0) {
+    for (const container of resource.readsFrom) {
+      let ref = container.id;
+      if (container.version) ref += `@${container.version}`;
+      lines.push(`  reads-from container ${ref}`);
+    }
+  }
+
+  const body = lines.join('\n');
+  parts.push(`service ${resource.id} {\n${body}\n}`);
+
+  return parts.join('\n\n');
+}
diff --git a/packages/sdk/src/dsl/utils.ts b/packages/sdk/src/dsl/utils.ts
new file mode 100644
index 000000000..0774ffabb
--- /dev/null
+++ b/packages/sdk/src/dsl/utils.ts
@@ -0,0 +1,163 @@
+import { globSync } from 'glob';
+import { satisfies, validRange } from 'semver';
+
+/**
+ * Checks whether a pointer version (which may be a semver range like ^1.0.0, ~1.2.0)
+ * matches a concrete message version.
+ */
+export function msgVersionMatches(pointerVersion: string | undefined, messageVersion: string | undefined): boolean {
+  if (!pointerVersion) return true;
+  if (!messageVersion) return false;
+  if (pointerVersion === messageVersion) return true;
+  try {
+    // Check if pointerVersion is a range that messageVersion satisfies
+    if (validRange(pointerVersion)) {
+      if (satisfies(messageVersion, pointerVersion)) return true;
+    }
+    // Check the reverse: messageVersion may be a range that pointerVersion satisfies
+    if (validRange(messageVersion)) {
+      if (satisfies(pointerVersion, messageVersion)) return true;
+    }
+  } catch {
+    // Invalid semver, fall through
+  }
+  return false;
+}
+
+interface BaseResource {
+  id: string;
+  name: string;
+  version: string;
+  summary?: string;
+  owners?: string[];
+  badges?: { content: string; backgroundColor: string; textColor: string; url?: string }[];
+  deprecated?: boolean | { date?: string; message?: string };
+  draft?: boolean | { title?: string; message?: string };
+}
+
+export type MessageTypeIndex = Map<string, MessageType>;
+
+interface ChannelPointer {
+  id: string;
+  version?: string;
+  parameters?: Record<string, string>;
+}
+
+interface SendsPointer {
+  id: string;
+  version?: string;
+  fields?: string[];
+  to?: ChannelPointer[];
+  group?: string;
+}
+
+interface ReceivesPointer {
+  id: string;
+  version?: string;
+  fields?: string[];
+  from?: ChannelPointer[];
+  group?: string;
+}
+
+export type MessageType = 'event' | 'command' | 'query';
+
+export function serializeBaseFields(resource: BaseResource, indent: string = '  '): string {
+  const lines: string[] = [];
+
+  if (resource.version) {
+    lines.push(`${indent}version ${resource.version}`);
+  }
+
+  if (resource.name) {
+    lines.push(`${indent}name "${resource.name}"`);
+  }
+
+  if (resource.summary) {
+    lines.push(`${indent}summary "${resource.summary.trim()}"`);
+  }
+
+  if (resource.owners && resource.owners.length > 0) {
+    for (const owner of resource.owners) {
+      lines.push(`${indent}owner ${owner}`);
+    }
+  }
+
+  if (resource.deprecated === true) {
+    lines.push(`${indent}deprecated true`);
+  }
+
+  if (resource.draft === true) {
+    lines.push(`${indent}draft true`);
+  }
+
+  return lines.join('\n');
+}
+
+export function buildMessageTypeIndex(catalogDir: string): MessageTypeIndex {
+  const index: MessageTypeIndex = new Map();
+  const types = ['events', 'commands', 'queries'] as const;
+  const typeMap = { events: 'event', commands: 'command', queries: 'query' } as const;
+
+  for (const type of types) {
+    const matches = globSync(`**/${type}/*/index.{md,mdx}`, { cwd: catalogDir });
+    for (const match of matches) {
+      const parts = match.replace(/\\/g, '/').split('/');
+      const typeIdx = parts.lastIndexOf(type);
+      if (typeIdx !== -1 && typeIdx + 1 < parts.length) {
+        const id = parts[typeIdx + 1];
+        if (!index.has(id)) index.set(id, typeMap[type]);
+      }
+    }
+  }
+
+  return index;
+}
+
+export function resolveMessageType(catalogDirOrIndex: string | MessageTypeIndex, id: string): MessageType | undefined {
+  if (typeof catalogDirOrIndex !== 'string') {
+    return catalogDirOrIndex.get(id);
+  }
+  // Fallback for backwards compatibility
+  if (globSync(`**/events/${id}/index.{md,mdx}`, { cwd: catalogDirOrIndex }).length > 0) return 'event';
+  if (globSync(`**/commands/${id}/index.{md,mdx}`, { cwd: catalogDirOrIndex }).length > 0) return 'command';
+  if (globSync(`**/queries/${id}/index.{md,mdx}`, { cwd: catalogDirOrIndex }).length > 0) return 'query';
+  return undefined;
+}
+
+function serializeChannelRef(channel: ChannelPointer): string {
+  let ref = channel.id;
+  if (channel.version) ref += `@${channel.version}`;
+  return ref;
+}
+
+export function serializeMessagePointers(
+  items: (SendsPointer | ReceivesPointer)[],
+  direction: 'sends' | 'receives',
+  catalogDirOrIndex: string | MessageTypeIndex,
+  indent: string = '  '
+): string {
+  const lines: string[] = [];
+
+  for (const item of items) {
+    const msgType = resolveMessageType(catalogDirOrIndex, item.id);
+    if (!msgType) continue;
+
+    let ref = `${item.id}`;
+    if (item.version) ref += `@${item.version}`;
+
+    const channels = direction === 'sends' ? (item as SendsPointer).to : (item as ReceivesPointer).from;
+
+    const channelKeyword = direction === 'sends' ? 'to' : 'from';
+
+    if (channels && channels.length === 1) {
+      lines.push(`${indent}${direction} ${msgType} ${ref} ${channelKeyword} ${serializeChannelRef(channels[0])}`);
+    } else if (channels && channels.length > 1) {
+      const channelRefs = channels.map(serializeChannelRef).join(', ');
+      lines.push(`${indent}${direction} ${msgType} ${ref} ${channelKeyword} ${channelRefs}`);
+    } else {
+      lines.push(`${indent}${direction} ${msgType} ${ref}`);
+    }
+  }
+
+  return lines.join('\n');
+}
diff --git a/packages/sdk/src/entities.ts b/packages/sdk/src/entities.ts
new file mode 100644
index 000000000..5a6644137
--- /dev/null
+++ b/packages/sdk/src/entities.ts
@@ -0,0 +1,218 @@
+import fs from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { findFileById, invalidateFileCache } from './internal/utils';
+import type { Entity } from './types';
+import { getResource, getResourcePath, getResources, rmResourceById, versionResource, writeResource } from './internal/resources';
+
+/**
+ * Returns an entity from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the entity
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getEntity } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the entity
+ * const entity = await getEntity('User');
+ *
+ * // Gets a version of the entity
+ * const entity = await getEntity('User', '0.0.1');
+ *
+ * ```
+ */
+export const getEntity =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<Entity> =>
+    getResource(directory, id, version, { type: 'entity' }) as Promise<Entity>;
+
+/**
+ * Returns all entities from EventCatalog.
+ *
+ * You can optionally specify if you want to get the latest version of the entities.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getEntities } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all entities (and versions) from the catalog
+ * const entities = await getEntities();
+ *
+ * // Gets all entities (only latest version) from the catalog
+ * const entities = await getEntities({ latestOnly: true });
+ *
+ * ```
+ */
+export const getEntities =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean }): Promise<Entity[]> =>
+    getResources(directory, { type: 'entities', latestOnly: options?.latestOnly }) as Promise<Entity[]>;
+
+/**
+ * Write an entity to EventCatalog.
+ *
+ * You can optionally override the path of the entity.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeEntity } = utils('/path/to/eventcatalog');
+ *
+ * // Write an entity to the catalog
+ * // Entity would be written to entities/User
+ * await writeEntity({
+ *   id: 'User',
+ *   name: 'User',
+ *   version: '0.0.1',
+ *   summary: 'User entity',
+ *   markdown: '# User entity',
+ * });
+ *
+ * // Write an entity to the catalog but override the path
+ * // Entity would be written to entities/Account/User
+ * await writeEntity({
+ *    id: 'User',
+ *    name: 'User',
+ *    version: '0.0.1',
+ *    summary: 'User entity',
+ *    markdown: '# User entity',
+ * }, { path: "/Account/User"});
+ *
+ * // Write an entity to the catalog and override the existing content (if there is any)
+ * await writeEntity({
+ *    id: 'User',
+ *    name: 'User',
+ *    version: '0.0.1',
+ *    summary: 'User entity',
+ *    markdown: '# User entity',
+ * }, { override: true });
+ *
+ * // Write an entity to the catalog and version the previous version
+ * // only works if the new version is greater than the previous version
+ * await writeEntity({
+ *    id: 'User',
+ *    name: 'User',
+ *    version: '0.0.1',
+ *    summary: 'User entity',
+ *    markdown: '# User entity',
+ * }, { versionExistingContent: true });
+ *
+ * ```
+ */
+export const writeEntity =
+  (directory: string) =>
+  async (
+    entity: Entity,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      format: 'mdx',
+    }
+  ) =>
+    writeResource(directory, { ...entity }, { ...options, type: 'entity' });
+
+/**
+ * Write an entity to a system in EventCatalog.
+ */
+export const writeEntityToSystem =
+  (directory: string) =>
+  async (
+    entity: Entity,
+    system: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    const resourcePath = await getResourcePath(directory, system.id, system.version);
+    if (!resourcePath) {
+      throw new Error('System not found');
+    }
+
+    const pathForEntity = join(resourcePath.directory, 'entities', entity.id);
+    await writeResource(directory, { ...entity }, { ...options, path: pathForEntity, type: 'entity' });
+  };
+
+/**
+ * Delete an entity at its given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmEntity } = utils('/path/to/eventcatalog');
+ *
+ * // removes an entity at the given path (entities dir is appended to the given path)
+ * // Removes the entity at entities/User
+ * await rmEntity('/User');
+ * ```
+ */
+export const rmEntity = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+/**
+ * Delete an entity by its id.
+ *
+ * Optionally specify a version to delete a specific version of the entity.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmEntityById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest User entity
+ * await rmEntityById('User');
+ *
+ * // deletes a specific version of the User entity
+ * await rmEntityById('User', '0.0.1');
+ * ```
+ */
+export const rmEntityById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) => {
+  await rmResourceById(directory, id, version, { type: 'entity', persistFiles });
+};
+
+/**
+ * Version an entity by its id.
+ *
+ * Takes the latest entity and moves it to a versioned directory.
+ * All files with this entity are also versioned (e.g /entities/User/schema.json)
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionEntity } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest User entity to a versioned directory
+ * // the version within that entity is used as the version number.
+ * await versionEntity('User');
+ *
+ * ```
+ */
+export const versionEntity = (directory: string) => async (id: string) => versionResource(directory, id);
+
+/**
+ * Check to see if the catalog has a version for the given entity.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { entityHasVersion } = utils('/path/to/eventcatalog');
+ *
+ * // returns true if version is found for the given entity and version (supports semver)
+ * await entityHasVersion('User', '0.0.1');
+ * await entityHasVersion('User', 'latest');
+ * await entityHasVersion('User', '0.0.x');
+ *
+ * ```
+ */
+export const entityHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
diff --git a/packages/sdk/src/eventcatalog.ts b/packages/sdk/src/eventcatalog.ts
new file mode 100644
index 000000000..ecbc3116b
--- /dev/null
+++ b/packages/sdk/src/eventcatalog.ts
@@ -0,0 +1,182 @@
+import type { EventCatalog } from './types';
+import fs from 'fs';
+import path, { join } from 'node:path';
+import utils from './index';
+import { getResourcePath } from './internal/resources';
+
+const DUMP_VERSION = '0.0.1';
+
+const getEventCatalogVersion = async (catalogDir: string) => {
+  // Read package.json in the catalogDir
+  try {
+    const packageJson = fs.readFileSync(join(catalogDir, 'package.json'), 'utf8');
+    const packageJsonObject = JSON.parse(packageJson);
+    return packageJsonObject['dependencies']['@eventcatalog/core'];
+  } catch (error) {
+    return 'unknown';
+  }
+};
+
+const hydrateResource = async (
+  catalogDir: string,
+  resources: any[] = [],
+  { attachSchema = false }: { attachSchema?: boolean } = {}
+) => {
+  return await Promise.all(
+    resources.map(async (resource) => {
+      // Get resource from directory
+      // Get resource from directory
+      const resourcePath = await getResourcePath(catalogDir, resource.id, resource.version);
+      let schema = '';
+
+      if (resource.schemaPath && resourcePath?.fullPath) {
+        const pathToSchema = path.join(path.dirname(resourcePath?.fullPath), resource.schemaPath);
+        if (fs.existsSync(pathToSchema)) {
+          schema = fs.readFileSync(pathToSchema, 'utf8');
+        }
+      }
+
+      // const hasSchemaPath = resource.data.schemaPath;
+
+      const eventcatalog = schema ? { directory: resourcePath?.directory, schema } : { directory: resourcePath?.directory };
+
+      return {
+        ...resource,
+        _eventcatalog: eventcatalog,
+      };
+    })
+  );
+};
+
+const filterCollection = (
+  collection: any[],
+  options?: {
+    includeMarkdown?: boolean;
+  }
+) => {
+  return collection.map((item) => ({
+    ...item,
+    markdown: options?.includeMarkdown ? item.markdown : undefined,
+  }));
+};
+
+/**
+ * Returns the event catalog configuration file.
+ * The event catalog configuration file is the file that contains the configuration for the event catalog.
+ *
+ * @param directory - The directory of the catalog.
+ * @returns A JSON object with the configuration for the event catalog.
+ */
+export const getEventCatalogConfigurationFile = (directory: string) => async (): Promise<any> => {
+  // Read package.json in the catalogDir
+  try {
+    const path = join(directory, 'eventcatalog.config.js');
+    // Dynamically import the ES module
+    const configModule = await import(path);
+    return configModule.default;
+  } catch (error) {
+    console.error('Error getting event catalog configuration file', error);
+    return null;
+  }
+};
+
+/**
+ * Dumps the catalog to a JSON file.
+ *
+ * @param directory - The directory of the catalog.
+ * @returns A JSON file with the catalog.
+ */
+export const dumpCatalog =
+  (directory: string) =>
+  async (options?: { includeMarkdown?: boolean }): Promise<EventCatalog> => {
+    const {
+      getDomains,
+      getSystems,
+      getServices,
+      getAgents,
+      getEvents,
+      getQueries,
+      getCommands,
+      getChannels,
+      getTeams,
+      getUsers,
+      getEntities,
+      getDataStores,
+      getFlows,
+      getAdrs,
+    } = utils(directory);
+
+    const { includeMarkdown = true } = options || {};
+
+    const domains = await getDomains();
+    const systems = await getSystems();
+    const services = await getServices();
+    const agents = await getAgents();
+
+    const events = await getEvents();
+    const commands = await getCommands();
+    const queries = await getQueries();
+    const teams = await getTeams();
+    const users = await getUsers();
+    const channels = await getChannels();
+    const entities = await getEntities();
+    const containers = await getDataStores();
+    const flows = await getFlows();
+    const adrs = await getAdrs();
+
+    const [
+      hydratedDomains,
+      hydratedSystems,
+      hydratedServices,
+      hydratedAgents,
+      hydratedEvents,
+      hydratedQueries,
+      hydratedCommands,
+      hydratedTeams,
+      hydratedUsers,
+      hydratedChannels,
+      hydratedEntities,
+      hydratedContainers,
+      hydratedFlows,
+      hydratedAdrs,
+    ] = await Promise.all([
+      hydrateResource(directory, domains),
+      hydrateResource(directory, systems),
+      hydrateResource(directory, services),
+      hydrateResource(directory, agents),
+      hydrateResource(directory, events),
+      hydrateResource(directory, queries),
+      hydrateResource(directory, commands),
+      hydrateResource(directory, teams),
+      hydrateResource(directory, users),
+      hydrateResource(directory, channels),
+      hydrateResource(directory, entities),
+      hydrateResource(directory, containers),
+      hydrateResource(directory, flows),
+      hydrateResource(directory, adrs),
+    ]);
+
+    return {
+      version: DUMP_VERSION,
+      catalogVersion: await getEventCatalogVersion(directory),
+      createdAt: new Date().toISOString(),
+      resources: {
+        domains: filterCollection(hydratedDomains, { includeMarkdown }),
+        systems: filterCollection(hydratedSystems, { includeMarkdown }),
+        services: filterCollection(hydratedServices, { includeMarkdown }),
+        agents: filterCollection(hydratedAgents, { includeMarkdown }),
+        messages: {
+          events: filterCollection(hydratedEvents, { includeMarkdown }),
+          queries: filterCollection(hydratedQueries, { includeMarkdown }),
+          commands: filterCollection(hydratedCommands, { includeMarkdown }),
+        },
+        teams: filterCollection(hydratedTeams, { includeMarkdown }),
+        users: filterCollection(hydratedUsers, { includeMarkdown }),
+        channels: filterCollection(hydratedChannels, { includeMarkdown }),
+        entities: filterCollection(hydratedEntities, { includeMarkdown }),
+        containers: filterCollection(hydratedContainers, { includeMarkdown }),
+        flows: filterCollection(hydratedFlows, { includeMarkdown }),
+        adrs: filterCollection(hydratedAdrs, { includeMarkdown }),
+      },
+    };
+  };
diff --git a/packages/sdk/src/events.ts b/packages/sdk/src/events.ts
new file mode 100644
index 000000000..c1b971472
--- /dev/null
+++ b/packages/sdk/src/events.ts
@@ -0,0 +1,391 @@
+import fs from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { findFileById, invalidateFileCache } from './internal/utils';
+import type { Event } from './types';
+import {
+  addFileToResource,
+  addExampleToResource,
+  getExamplesFromResource,
+  removeExampleFromResource,
+  getResource,
+  getResourcePath,
+  getResources,
+  rmResourceById,
+  versionResource,
+  writeResource,
+} from './internal/resources';
+
+/**
+ * Returns an event from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the event
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getEvent } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the event
+ * const event = await getEvent('InventoryAdjusted');
+ *
+ * // Gets a version of the event
+ * const event = await getEvent('InventoryAdjusted', '0.0.1');
+ *
+ * // Get the event with the schema attached
+ * const event = await getEvent('InventoryAdjusted', '0.0.1', { attachSchema: true });
+ * ```
+ */
+export const getEvent =
+  (directory: string) =>
+  async (id: string, version?: string, options?: { attachSchema?: boolean }): Promise<Event> =>
+    getResource(directory, id, version, { type: 'event', ...options }) as Promise<Event>;
+
+/**
+ * Returns all events from EventCatalog.
+ *
+ * You can optionally specify if you want to get the latest version of the events.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getEvents } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all events (and versions) from the catalog
+ * const events = await getEvents();
+ *
+ * // Gets all events (only latest version) from the catalog
+ * const events = await getEvents({ latestOnly: true });
+ *
+ * // Get all events with the schema attached
+ * const events = await getEvents({ attachSchema: true });
+ * ```
+ */
+export const getEvents =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean; attachSchema?: boolean }): Promise<Event[]> =>
+    getResources(directory, { type: 'events', ...options }) as Promise<Event[]>;
+
+/**
+ * Write an event to EventCatalog.
+ *
+ * You can optionally overide the path of the event.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeEvent } = utils('/path/to/eventcatalog');
+ *
+ * // Write an event to the catalog
+ * // Event would be written to events/InventoryAdjusted
+ * await writeEvent({
+ *   id: 'InventoryAdjusted',
+ *   name: 'Inventory Adjusted',
+ *   version: '0.0.1',
+ *   summary: 'This is a summary',
+ *   markdown: '# Hello world',
+ * });
+ *
+ * // Write an event to the catalog but override the path
+ * // Event would be written to events/Inventory/InventoryAdjusted
+ * await writeEvent({
+ *    id: 'InventoryAdjusted',
+ *    name: 'Inventory Adjusted',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { path: "/Inventory/InventoryAdjusted"});
+ *
+ * // Write a event to the catalog and override the existing content (if there is any)
+ * await writeEvent({
+ *    id: 'InventoryAdjusted',
+ *    name: 'Inventory Adjusted',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { override: true });
+ *
+ * // Write a event to the catalog and version the previous version
+ * // only works if the new version is greater than the previous version
+ * await writeEvent({
+ *    id: 'InventoryAdjusted',
+ *    name: 'Inventory Adjusted',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { versionExistingContent: true });
+ *
+ * ```
+ */
+export const writeEvent =
+  (directory: string) =>
+  async (
+    event: Event,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      format: 'mdx',
+    }
+  ) =>
+    writeResource(directory, { ...event }, { ...options, type: 'event' });
+/**
+ * Write an event to a service in EventCatalog.
+ *
+ * You can optionally override the path of the event.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeEventToService } = utils('/path/to/eventcatalog');
+ *
+ * // Write an event to a given service in the catalog
+ * // Event would be written to services/Inventory/events/InventoryAdjusted
+ * await writeEventToService({
+ *   id: 'InventoryAdjusted',
+ *   name: 'Inventory Adjusted',
+ *   version: '0.0.1',
+ *   summary: 'This is a summary',
+ *   markdown: '# Hello world',
+ * }, { id: 'Inventory' });
+ * ```
+ */
+export const writeEventToService =
+  (directory: string) =>
+  async (
+    event: Event,
+    service: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    const resourcePath = await getResourcePath(directory, service.id, service.version);
+    if (!resourcePath) {
+      throw new Error('Service not found');
+    }
+
+    let pathForEvent =
+      service.version && service.version !== 'latest'
+        ? `${resourcePath.directory}/versioned/${service.version}/events`
+        : `${resourcePath.directory}/events`;
+    pathForEvent = join(pathForEvent, event.id);
+    await writeResource(directory, { ...event }, { ...options, path: pathForEvent, type: 'event' });
+  };
+
+/**
+ * Write an event to an agent in EventCatalog.
+ */
+export const writeEventToAgent =
+  (directory: string) =>
+  async (
+    event: Event,
+    agent: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    const resourcePath = await getResourcePath(directory, agent.id, agent.version);
+    if (!resourcePath) {
+      throw new Error('Agent not found');
+    }
+
+    let pathForEvent =
+      agent.version && agent.version !== 'latest'
+        ? `${resourcePath.directory}/versioned/${agent.version}/events`
+        : `${resourcePath.directory}/events`;
+    pathForEvent = join(pathForEvent, event.id);
+    await writeResource(directory, { ...event }, { ...options, path: pathForEvent, type: 'event' });
+  };
+
+/**
+ * Delete an event at it's given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmEvent } = utils('/path/to/eventcatalog');
+ *
+ * // removes an event at the given path (events dir is appended to the given path)
+ * // Removes the event at events/InventoryAdjusted
+ * await rmEvent('/InventoryAdjusted');
+ * ```
+ */
+export const rmEvent = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+/**
+ * Delete an event by it's id.
+ *
+ * Optionally specify a version to delete a specific version of the event.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmEventById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest InventoryAdjusted event
+ * await rmEventById('InventoryAdjusted');
+ *
+ * // deletes a specific version of the InventoryAdjusted event
+ * await rmEventById('InventoryAdjusted', '0.0.1');
+ * ```
+ */
+export const rmEventById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) => {
+  await rmResourceById(directory, id, version, { type: 'event', persistFiles });
+};
+
+/**
+ * Version an event by it's id.
+ *
+ * Takes the latest event and moves it to a versioned directory.
+ * All files with this event are also versioned (e.g /events/InventoryAdjusted/schema.json)
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionEvent } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest InventoryAdjusted event to a versioned directory
+ * // the version within that event is used as the version number.
+ * await versionEvent('InventoryAdjusted');
+ *
+ * ```
+ */
+export const versionEvent = (directory: string) => async (id: string) => versionResource(directory, id);
+
+/**
+ * Add a file to an event by it's id.
+ *
+ * Optionally specify a version to add a file to a specific version of the event.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addFileToEvent } = utils('/path/to/eventcatalog');
+ *
+ * // adds a file to the latest InventoryAdjusted event
+ * await addFileToEvent('InventoryAdjusted', { content: 'Hello world', fileName: 'hello.txt' });
+ *
+ * // adds a file to a specific version of the InventoryAdjusted event
+ * await addFileToEvent('InventoryAdjusted', { content: 'Hello world', fileName: 'hello.txt' }, '0.0.1');
+ *
+ * ```
+ */
+export const addFileToEvent =
+  (directory: string) =>
+  async (id: string, file: { content: string; fileName: string }, version?: string, options?: { path?: string }) =>
+    addFileToResource(directory, id, file, version, options);
+
+/**
+ * Add a schema to an event by it's id.
+ *
+ * Optionally specify a version to add a schema to a specific version of the event.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addFileToEvent } = utils('/path/to/eventcatalog');
+ *
+ * // JSON schema example
+ * const schema = {
+ *    "$schema": "http://json-schema.org/draft-07/schema#",
+ *    "type": "object",
+ *    "properties": {
+ *        "name": {
+ *        "type": "string"
+ *    },
+ *    "age": {
+ *      "type": "number"
+ *    }
+ *  },
+ *  "required": ["name", "age"]
+ * };
+ *
+ * // adds a file to the latest InventoryAdjusted event
+ * await addFileToEvent('InventoryAdjusted', { schema, fileName: 'schema.json' });
+ *
+ * // adds a file to a specific version of the InventoryAdjusted event
+ * await addFileToEvent('InventoryAdjusted', { schema, fileName: 'schema.json' }, '0.0.1');
+ *
+ * ```
+ */
+export const addSchemaToEvent =
+  (directory: string) =>
+  async (id: string, schema: { schema: string; fileName: string }, version?: string, options?: { path?: string }) => {
+    await addFileToEvent(directory)(id, { content: schema.schema, fileName: schema.fileName }, version, options);
+  };
+
+/**
+ * Check to see if the catalog has a version for the given event.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { eventHasVersion } = utils('/path/to/eventcatalog');
+ *
+ * // returns true if version is found for the given event and version (supports semver)
+ * await eventHasVersion('InventoryAdjusted', '0.0.1');
+ * await eventHasVersion('InventoryAdjusted', 'latest');
+ * await eventHasVersion('InventoryAdjusted', '0.0.x');*
+ *
+ * ```
+ */
+export const eventHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+/**
+ * Add an example file to an event.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addExampleToEvent } = utils('/path/to/eventcatalog');
+ *
+ * await addExampleToEvent('InventoryAdjusted', { content: '{"id": "123"}', fileName: 'basic.json' });
+ * await addExampleToEvent('InventoryAdjusted', { content: '{"id": "123"}', fileName: 'basic.json' }, '0.0.1');
+ * ```
+ */
+export const addExampleToEvent =
+  (directory: string) => async (id: string, example: { content: string; fileName: string }, version?: string) =>
+    addExampleToResource(directory, id, example, version);
+
+/**
+ * Get all examples from an event.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getExamplesFromEvent } = utils('/path/to/eventcatalog');
+ *
+ * const examples = await getExamplesFromEvent('InventoryAdjusted');
+ * const examples = await getExamplesFromEvent('InventoryAdjusted', '0.0.1');
+ * ```
+ */
+export const getExamplesFromEvent = (directory: string) => async (id: string, version?: string) =>
+  getExamplesFromResource(directory, id, version);
+
+/**
+ * Remove an example file from an event.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { removeExampleFromEvent } = utils('/path/to/eventcatalog');
+ *
+ * await removeExampleFromEvent('InventoryAdjusted', 'basic.json');
+ * await removeExampleFromEvent('InventoryAdjusted', 'basic.json', '0.0.1');
+ * ```
+ */
+export const removeExampleFromEvent = (directory: string) => async (id: string, fileName: string, version?: string) =>
+  removeExampleFromResource(directory, id, fileName, version);
diff --git a/packages/sdk/src/flow-builder.ts b/packages/sdk/src/flow-builder.ts
new file mode 100644
index 000000000..de1cea68e
--- /dev/null
+++ b/packages/sdk/src/flow-builder.ts
@@ -0,0 +1,710 @@
+import type { Flow, FlowStep } from './types';
+
+type FlowStepId = string | number;
+type FlowStepPointer = FlowStepId | { id: FlowStepId; label?: string };
+
+/**
+ * Input used to create a flow builder.
+ *
+ * This is the normal `Flow` resource shape without requiring `steps` up front.
+ * You can pass existing steps if you want to append to a partially built flow.
+ */
+export type FlowBuilderInput = Omit<Flow, 'steps'> & {
+  steps?: FlowStep[];
+};
+
+/**
+ * Payload for a generic flow step.
+ *
+ * Use generic steps for process milestones that are not messages, services,
+ * actors, external systems, sub-flows, or custom nodes.
+ */
+export type FlowStepInput = {
+  id: FlowStepId;
+  title?: string;
+  summary?: string;
+  nextSteps?: FlowStepPointer[];
+};
+
+/**
+ * Payload for a flow step that references an event, command, or query.
+ */
+export type FlowMessageStepInput<TMessageId extends string = string> = FlowStepInput & {
+  message?: {
+    id: TMessageId;
+    version?: string;
+  };
+  version?: string;
+};
+
+/**
+ * Payload for a flow step that references an agent.
+ */
+export type FlowAgentStepInput = FlowStepInput & {
+  agent?: {
+    id: string;
+    version?: string;
+  };
+  version?: string;
+};
+
+/**
+ * Payload for a flow step that references a service.
+ */
+export type FlowServiceStepInput = FlowStepInput & {
+  service?: {
+    id: string;
+    version?: string;
+  };
+  version?: string;
+};
+
+/**
+ * Payload for a flow step that references a data store/container.
+ */
+export type FlowDataStoreStepInput = FlowStepInput & {
+  container?: {
+    id: string;
+    version?: string;
+  };
+  version?: string;
+};
+
+/**
+ * Payload for a flow step that references a data product.
+ */
+export type FlowDataProductStepInput = FlowStepInput & {
+  dataProduct?: {
+    id: string;
+    version?: string;
+  };
+  version?: string;
+};
+
+/**
+ * Payload for a flow step that represents a user or actor.
+ */
+export type FlowActorStepInput = FlowStepInput & {
+  actor?: {
+    name: string;
+    summary?: string;
+  };
+  name?: string;
+};
+
+/**
+ * Payload for a flow step that represents an external system.
+ */
+export type FlowExternalSystemStepInput = FlowStepInput & {
+  externalSystem?: {
+    name: string;
+    summary?: string;
+    url?: string;
+  };
+  name?: string;
+  url?: string;
+};
+
+/**
+ * Payload for a flow step that references another flow.
+ */
+export type FlowSubFlowStepInput = FlowStepInput & {
+  flow?: {
+    id: string;
+    version?: string;
+  };
+  version?: string;
+};
+
+/**
+ * Payload for a custom flow step.
+ */
+export type FlowCustomStepInput = FlowStepInput & {
+  custom?: {
+    title: string;
+    icon?: string;
+    type?: string;
+    summary?: string;
+    url?: string;
+    color?: string;
+    properties?: Record<string, string | number>;
+    height?: number;
+    menu?: { label: string; url?: string }[];
+  };
+  icon?: string;
+  type?: string;
+  url?: string;
+  color?: string;
+  properties?: Record<string, string | number>;
+  height?: number;
+  menu?: { label: string; url?: string }[];
+};
+
+const cloneStep = (step: FlowStep): FlowStep => ({
+  ...step,
+  ...(step.message ? { message: { ...step.message } } : {}),
+  ...(step.agent ? { agent: { ...step.agent } } : {}),
+  ...(step.service ? { service: { ...step.service } } : {}),
+  ...(step.flow ? { flow: { ...step.flow } } : {}),
+  ...(step.container ? { container: { ...step.container } } : {}),
+  ...(step.dataProduct ? { dataProduct: { ...step.dataProduct } } : {}),
+  ...(step.actor ? { actor: { ...step.actor } } : {}),
+  ...(step.custom
+    ? {
+        custom: {
+          ...step.custom,
+          ...(step.custom.properties ? { properties: { ...step.custom.properties } } : {}),
+          ...(step.custom.menu ? { menu: step.custom.menu.map((item) => ({ ...item })) } : {}),
+        },
+      }
+    : {}),
+  ...(step.externalSystem ? { externalSystem: { ...step.externalSystem } } : {}),
+  ...(step.next_step !== undefined
+    ? { next_step: typeof step.next_step === 'object' ? { ...step.next_step } : step.next_step }
+    : {}),
+  ...(step.next_steps ? { next_steps: step.next_steps.map((next) => (typeof next === 'object' ? { ...next } : next)) } : {}),
+});
+
+/**
+ * Build EventCatalog flow resources using a fluent API.
+ *
+ * `FlowBuilder` is useful when you want to define flows in code and then write
+ * the generated `Flow` resource with `writeFlow`. The builder outputs the normal
+ * EventCatalog `Flow` shape, so the persisted catalog remains standard
+ * markdown/frontmatter.
+ *
+ * `nextSteps` is the authoring API. When `build()` is called, a single next step
+ * is normalized to `next_step` and multiple next steps are normalized to
+ * `next_steps`.
+ *
+ * @example
+ * ```ts
+ * import utils, { FlowBuilder } from '@eventcatalog/sdk';
+ *
+ * const { writeFlow } = utils('/path/to/eventcatalog');
+ *
+ * const flow = FlowBuilder.create({
+ *   id: 'PaymentFlow',
+ *   name: 'Payment Flow',
+ *   version: '1.0.0',
+ *   markdown: '# Payment Flow',
+ * })
+ *   .addStep({
+ *     id: 'Customer places order',
+ *     nextSteps: [{ id: 'PlaceOrder', label: 'places order' }],
+ *   })
+ *   .addMessageStep({
+ *     id: 'PlaceOrder',
+ *     message: { id: 'PlaceOrder' },
+ *     nextSteps: [{ id: 'PaymentService', label: 'process payment' }],
+ *   })
+ *   .addServiceStep({
+ *     id: 'PaymentService',
+ *     service: { id: 'PaymentService' },
+ *   })
+ *   .build();
+ *
+ * await writeFlow(flow);
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { FlowBuilder } from '@eventcatalog/sdk';
+ *
+ * type PaymentMessageId = 'PlaceOrder' | 'PaymentProcessed';
+ *
+ * const flow = FlowBuilder.create<PaymentMessageId>({
+ *   id: 'TypedPaymentFlow',
+ *   name: 'Typed Payment Flow',
+ *   version: '1.0.0',
+ *   markdown: '# Typed Payment Flow',
+ * })
+ *   .addMessageStep({
+ *     id: 'PlaceOrder',
+ *     nextSteps: [{ id: 'PaymentProcessed' }],
+ *   })
+ *   .addMessageStep({
+ *     id: 'PaymentProcessed',
+ *   })
+ *   .build();
+ * ```
+ */
+export class FlowBuilder<TMessageId extends string = string> {
+  private readonly flowResource: FlowBuilderInput;
+  private readonly steps = new Map<FlowStepId, FlowStep>();
+  private readonly order: FlowStepId[] = [];
+
+  private constructor(flow: FlowBuilderInput) {
+    this.flowResource = { ...flow };
+
+    for (const step of flow.steps || []) {
+      this.appendStep(cloneStep(step));
+    }
+  }
+
+  /**
+   * Create a flow builder.
+   *
+   * The created builder can add steps and then produce a normal `Flow` resource
+   * with `build()`.
+   *
+   * @example
+   * ```ts
+   * const flow = FlowBuilder.create({
+   *   id: 'PaymentFlow',
+   *   name: 'Payment Flow',
+   *   version: '1.0.0',
+   *   markdown: '# Payment Flow',
+   * }).build();
+   * ```
+   */
+  static create<TMessageId extends string = string>(flow: FlowBuilderInput) {
+    return new FlowBuilder<TMessageId>(flow);
+  }
+
+  /**
+   * Add a generic flow step.
+   *
+   * Generic steps are useful for business process stages that do not map to
+   * another catalog resource.
+   *
+   * @param step - The step payload.
+   *
+   * @example
+   * ```ts
+   * FlowBuilder.create({
+   *   id: 'OrderFlow',
+   *   name: 'Order Flow',
+   *   version: '1.0.0',
+   *   markdown: '',
+   * })
+   *   .addStep({
+   *     id: 'Calculate',
+   *     title: 'Calculate totals',
+   *     nextSteps: [{ id: 'OrderConfirmed' }],
+   *   });
+   * ```
+   */
+  addStep(step: FlowStepInput) {
+    return this.addStepWithNext(
+      {
+        id: step.id,
+        title: step.title || String(step.id),
+        ...(step.summary ? { summary: step.summary } : {}),
+      },
+      step.nextSteps
+    );
+  }
+
+  /**
+   * Add a message step.
+   *
+   * Message steps can reference an event, command, or query id.
+   *
+   * @param step - The message step payload.
+   *
+   * @example
+   * ```ts
+   * FlowBuilder.create({
+   *   id: 'OrderFlow',
+   *   name: 'Order Flow',
+   *   version: '1.0.0',
+   *   markdown: '',
+   * })
+   *   .addMessageStep({
+   *     id: 'OrderConfirmed',
+   *     title: 'Order confirmed',
+   *     message: { id: 'OrderConfirmed', version: '1.0.0' },
+   *   });
+   * ```
+   */
+  addMessageStep(step: FlowMessageStepInput<TMessageId>) {
+    const message = step.message || {
+      id: String(step.id) as TMessageId,
+      ...(step.version ? { version: step.version } : {}),
+    };
+
+    return this.addStepWithNext(
+      {
+        id: step.id,
+        title: step.title || String(step.id),
+        ...(step.summary ? { summary: step.summary } : {}),
+        message: { ...message, ...(step.version && !message.version ? { version: step.version } : {}) },
+      },
+      step.nextSteps
+    );
+  }
+
+  /**
+   * Add a service step.
+   *
+   * @param step - The service step payload.
+   *
+   * @example
+   * ```ts
+   * FlowBuilder.create({
+   *   id: 'OrderFlow',
+   *   name: 'Order Flow',
+   *   version: '1.0.0',
+   *   markdown: '',
+   * })
+   *   .addServiceStep({
+   *     id: 'OrderService',
+   *     service: { id: 'OrderService', version: '1.0.0' },
+   *   });
+   * ```
+   */
+  addServiceStep(step: FlowServiceStepInput) {
+    const service = step.service || {
+      id: String(step.id),
+      ...(step.version ? { version: step.version } : {}),
+    };
+
+    return this.addStepWithNext(
+      {
+        id: step.id,
+        title: step.title || String(step.id),
+        ...(step.summary ? { summary: step.summary } : {}),
+        service: { ...service, ...(step.version && !service.version ? { version: step.version } : {}) },
+      },
+      step.nextSteps
+    );
+  }
+
+  /**
+   * Add an agent step.
+   *
+   * @param step - The agent step payload.
+   *
+   * @example
+   * ```ts
+   * FlowBuilder.create({
+   *   id: 'OrderFlow',
+   *   name: 'Order Flow',
+   *   version: '1.0.0',
+   *   markdown: '',
+   * })
+   *   .addAgentStep({
+   *     id: 'FraudReviewAgent',
+   *     agent: { id: 'FraudReviewAgent', version: '1.0.0' },
+   *   });
+   * ```
+   */
+  addAgentStep(step: FlowAgentStepInput) {
+    const agent = step.agent || {
+      id: String(step.id),
+      ...(step.version ? { version: step.version } : {}),
+    };
+
+    return this.addStepWithNext(
+      {
+        id: step.id,
+        title: step.title || String(step.id),
+        ...(step.summary ? { summary: step.summary } : {}),
+        agent: { ...agent, ...(step.version && !agent.version ? { version: step.version } : {}) },
+      },
+      step.nextSteps
+    );
+  }
+
+  /**
+   * Add a data store step.
+   *
+   * Data store steps reference container resources in EventCatalog. If a
+   * version is not provided, EventCatalog resolves the latest matching
+   * container version when rendering the flow.
+   *
+   * @param step - The data store step payload.
+   *
+   * @example
+   * ```ts
+   * FlowBuilder.create({
+   *   id: 'OrderFlow',
+   *   name: 'Order Flow',
+   *   version: '1.0.0',
+   *   markdown: '',
+   * })
+   *   .addDataStoreStep({
+   *     id: 'OrdersDB',
+   *     container: { id: 'OrdersDB', version: '1.0.0' },
+   *   });
+   * ```
+   */
+  addDataStoreStep(step: FlowDataStoreStepInput) {
+    const fallbackContainer = {
+      id: String(step.id),
+      ...(step.version ? { version: step.version } : {}),
+    };
+    const container = step.container ?? fallbackContainer;
+
+    return this.addStepWithNext(
+      {
+        id: step.id,
+        title: step.title || String(step.id),
+        ...(step.summary ? { summary: step.summary } : {}),
+        container: { ...container, ...(step.version && !container.version ? { version: step.version } : {}) },
+      },
+      step.nextSteps
+    );
+  }
+
+  /**
+   * Add a container step.
+   *
+   * Alias for `addDataStoreStep`.
+   */
+  addContainerStep(step: FlowDataStoreStepInput) {
+    return this.addDataStoreStep(step);
+  }
+
+  /**
+   * Add a data product step.
+   *
+   * If a version is not provided, EventCatalog resolves the latest matching
+   * data product version when rendering the flow.
+   *
+   * @param step - The data product step payload.
+   *
+   * @example
+   * ```ts
+   * FlowBuilder.create({
+   *   id: 'OrderFlow',
+   *   name: 'Order Flow',
+   *   version: '1.0.0',
+   *   markdown: '',
+   * })
+   *   .addDataProductStep({
+   *     id: 'OrderAnalytics',
+   *     dataProduct: { id: 'OrderAnalytics', version: '1.0.0' },
+   *   });
+   * ```
+   */
+  addDataProductStep(step: FlowDataProductStepInput) {
+    const fallbackDataProduct = {
+      id: String(step.id),
+      ...(step.version ? { version: step.version } : {}),
+    };
+    const dataProduct = step.dataProduct ?? fallbackDataProduct;
+
+    return this.addStepWithNext(
+      {
+        id: step.id,
+        title: step.title || String(step.id),
+        ...(step.summary ? { summary: step.summary } : {}),
+        dataProduct: { ...dataProduct, ...(step.version && !dataProduct.version ? { version: step.version } : {}) },
+      },
+      step.nextSteps
+    );
+  }
+
+  /**
+   * Add an actor step.
+   *
+   * @param step - The actor step payload.
+   *
+   * @example
+   * ```ts
+   * FlowBuilder.create({
+   *   id: 'OrderFlow',
+   *   name: 'Order Flow',
+   *   version: '1.0.0',
+   *   markdown: '',
+   * })
+   *   .addActorStep({
+   *     id: 'Customer',
+   *     actor: { name: 'Customer' },
+   *   });
+   * ```
+   */
+  addActorStep(step: FlowActorStepInput) {
+    const actor = step.actor || {
+      name: step.name || step.title || String(step.id),
+      ...(step.summary ? { summary: step.summary } : {}),
+    };
+
+    return this.addStepWithNext(
+      {
+        id: step.id,
+        title: step.title || actor.name,
+        ...(step.summary ? { summary: step.summary } : {}),
+        actor,
+      },
+      step.nextSteps
+    );
+  }
+
+  /**
+   * Add an external system step.
+   *
+   * @param step - The external system step payload.
+   *
+   * @example
+   * ```ts
+   * FlowBuilder.create({
+   *   id: 'PaymentFlow',
+   *   name: 'Payment Flow',
+   *   version: '1.0.0',
+   *   markdown: '',
+   * })
+   *   .addExternalSystemStep({
+   *     id: 'Stripe',
+   *     externalSystem: {
+   *       name: 'Stripe',
+   *       summary: 'Payment provider',
+   *       url: 'https://stripe.com',
+   *     },
+   *   });
+   * ```
+   */
+  addExternalSystemStep(step: FlowExternalSystemStepInput) {
+    const externalSystem = step.externalSystem || {
+      name: step.name || step.title || String(step.id),
+      ...(step.summary ? { summary: step.summary } : {}),
+      ...(step.url ? { url: step.url } : {}),
+    };
+
+    return this.addStepWithNext(
+      {
+        id: step.id,
+        title: step.title || externalSystem.name,
+        ...(step.summary ? { summary: step.summary } : {}),
+        externalSystem,
+      },
+      step.nextSteps
+    );
+  }
+
+  /**
+   * Add a sub-flow step.
+   *
+   * @param step - The sub-flow step payload.
+   *
+   * @example
+   * ```ts
+   * FlowBuilder.create({
+   *   id: 'OrderFlow',
+   *   name: 'Order Flow',
+   *   version: '1.0.0',
+   *   markdown: '',
+   * })
+   *   .addFlowStep({
+   *     id: 'PaymentFlow',
+   *     flow: { id: 'PaymentFlow', version: '1.0.0' },
+   *   });
+   * ```
+   */
+  addFlowStep(step: FlowSubFlowStepInput) {
+    const flow = step.flow || {
+      id: String(step.id),
+      ...(step.version ? { version: step.version } : {}),
+    };
+
+    return this.addStepWithNext(
+      {
+        id: step.id,
+        title: step.title || String(step.id),
+        ...(step.summary ? { summary: step.summary } : {}),
+        flow: { ...flow, ...(step.version && !flow.version ? { version: step.version } : {}) },
+      },
+      step.nextSteps
+    );
+  }
+
+  /**
+   * Add a custom flow step.
+   *
+   * @param step - The custom step payload.
+   *
+   * @example
+   * ```ts
+   * FlowBuilder.create({
+   *   id: 'PaymentFlow',
+   *   name: 'Payment Flow',
+   *   version: '1.0.0',
+   *   markdown: '',
+   * })
+   *   .addCustomStep({
+   *     id: 'ManualReview',
+   *     custom: {
+   *       title: 'Manual review',
+   *       type: 'manual',
+   *     },
+   *   });
+   * ```
+   */
+  addCustomStep(step: FlowCustomStepInput) {
+    const custom = step.custom || {
+      title: step.title || String(step.id),
+      ...(step.icon ? { icon: step.icon } : {}),
+      ...(step.type ? { type: step.type } : {}),
+      ...(step.summary ? { summary: step.summary } : {}),
+      ...(step.url ? { url: step.url } : {}),
+      ...(step.color ? { color: step.color } : {}),
+      ...(step.properties ? { properties: step.properties } : {}),
+      ...(step.height ? { height: step.height } : {}),
+      ...(step.menu ? { menu: step.menu } : {}),
+    };
+
+    return this.addStepWithNext(
+      {
+        id: step.id,
+        title: step.title || custom.title,
+        ...(step.summary ? { summary: step.summary } : {}),
+        custom,
+      },
+      step.nextSteps
+    );
+  }
+
+  /**
+   * Build the EventCatalog flow resource.
+   *
+   * @returns A `Flow` resource that can be written with `writeFlow`.
+   */
+  build(): Flow {
+    this.validateNextSteps();
+
+    const { steps: _steps, ...flow } = this.flowResource;
+
+    return {
+      ...flow,
+      steps: this.order.map((id) => cloneStep(this.steps.get(id)!)),
+    };
+  }
+
+  private addStepWithNext(step: FlowStep, nextSteps?: FlowStepPointer[]) {
+    const normalizedNextSteps = nextSteps?.map((next) => (typeof next === 'object' ? { ...next } : { id: next })) || [];
+
+    if (normalizedNextSteps.length === 1) {
+      step.next_step = normalizedNextSteps[0];
+    } else if (normalizedNextSteps.length > 1) {
+      step.next_steps = normalizedNextSteps;
+    }
+
+    this.appendStep(step);
+    return this;
+  }
+
+  private appendStep(step: FlowStep) {
+    if (this.steps.has(step.id)) {
+      throw new Error(`Flow step with id "${step.id}" already exists`);
+    }
+
+    this.steps.set(step.id, step);
+    this.order.push(step.id);
+  }
+
+  private validateNextSteps() {
+    for (const step of this.steps.values()) {
+      const nextSteps = step.next_step !== undefined ? [step.next_step] : step.next_steps || [];
+
+      for (const next of nextSteps) {
+        const nextStepId = typeof next === 'object' && next ? next.id : next;
+
+        if (!this.steps.has(nextStepId)) {
+          throw new Error(`Flow step "${step.id}" references missing next step "${nextStepId}"`);
+        }
+      }
+    }
+  }
+}
diff --git a/packages/sdk/src/flows.ts b/packages/sdk/src/flows.ts
new file mode 100644
index 000000000..ae709f29d
--- /dev/null
+++ b/packages/sdk/src/flows.ts
@@ -0,0 +1,384 @@
+import type { Flow } from './types';
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { findFileById, invalidateFileCache } from './internal/utils';
+import {
+  addFileToResource,
+  getResourcePath,
+  getResource,
+  getResources,
+  getVersionedDirectory,
+  rmResourceById,
+  versionResource,
+  writeResource,
+} from './internal/resources';
+
+export { FlowBuilder } from './flow-builder';
+export type * from './flow-builder';
+
+/**
+ * Returns a flow from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the flow
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getFlow } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the flow
+ * const flow = await getFlow('PaymentFlow');
+ *
+ * // Gets a version of the flow
+ * const flow = await getFlow('PaymentFlow', '0.0.1');
+ *
+ * ```
+ */
+export const getFlow =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<Flow> =>
+    getResource(directory, id, version, { type: 'flow' }) as Promise<Flow>;
+
+/**
+ * Returns all flows from EventCatalog.
+ *
+ * You can optionally specify if you want to get the latest version of the flows.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getFlows } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all flows (and versions) from the catalog
+ * const flows = await getFlows();
+ *
+ * // Gets all flows (only latest version) from the catalog
+ * const flows = await getFlows({ latestOnly: true });
+ *
+ * ```
+ */
+export const getFlows =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean }): Promise<Flow[]> =>
+    getResources(directory, { type: 'flows', latestOnly: options?.latestOnly }) as Promise<Flow[]>;
+
+/**
+ * Write a flow to EventCatalog.
+ *
+ * You can optionally override the path of the flow.
+ *
+ * @example
+ * ```ts
+ * import utils, { FlowBuilder } from '@eventcatalog/utils';
+ *
+ * const { writeFlow } = utils('/path/to/eventcatalog');
+ *
+ * // Build a flow using the fluent builder API
+ * const flow = FlowBuilder.create({
+ *   id: 'PaymentFlow',
+ *   name: 'Payment Flow',
+ *   version: '0.0.1',
+ *   summary: 'Business flow for processing payments',
+ *   markdown: '# Payment Flow',
+ * })
+ *   .addMessageStep({
+ *     id: 'PlaceOrder',
+ *     title: 'Place order',
+ *     message: { id: 'PlaceOrder', version: '0.0.1' },
+ *     nextSteps: [{ id: 'PaymentProcessed', label: 'Payment processed' }],
+ *   })
+ *   .addMessageStep({
+ *     id: 'PaymentProcessed',
+ *     title: 'Payment processed',
+ *     message: { id: 'PaymentProcessed', version: '0.0.1' },
+ *   })
+ *   .build();
+ *
+ * // Flow would be written to flows/PaymentFlow
+ * await writeFlow(flow);
+ *
+ * // You can also write a raw Flow object
+ * await writeFlow({
+ *   id: 'RewardFlow',
+ *   name: 'Reward Flow',
+ *   version: '0.0.1',
+ *   markdown: '# Reward Flow',
+ *   steps: [],
+ * });
+ *
+ * // Write a flow to the catalog but override the path
+ * // Flow would be written to flows/Payments/RewardFlow
+ * await writeFlow({
+ *   id: 'RewardFlow',
+ *   name: 'Reward Flow',
+ *   version: '0.0.1',
+ *   markdown: '# Reward Flow',
+ *   steps: [],
+ * }, { path: '/Payments/RewardFlow' });
+ *
+ * // Write a flow to the catalog and override the existing content
+ * await writeFlow({
+ *   id: 'RewardFlow',
+ *   name: 'Reward Flow',
+ *   version: '0.0.1',
+ *   markdown: '# Reward Flow',
+ *   steps: [],
+ * }, { override: true });
+ * ```
+ */
+export const writeFlow =
+  (directory: string) =>
+  async (
+    flow: Flow,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      format: 'mdx',
+    }
+  ) =>
+    writeResource(directory, { ...flow }, { ...options, type: 'flow' });
+
+/**
+ * Write a versioned flow to EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeVersionedFlow } = utils('/path/to/eventcatalog');
+ *
+ * // Flow would be written to flows/PaymentFlow/versioned/0.0.1
+ * await writeVersionedFlow({
+ *   id: 'PaymentFlow',
+ *   name: 'Payment Flow',
+ *   version: '0.0.1',
+ *   markdown: '# Payment Flow',
+ *   steps: [],
+ * });
+ * ```
+ */
+export const writeVersionedFlow = (directory: string) => async (flow: Flow) => {
+  const path = getVersionedDirectory(flow.id, flow.version);
+
+  return await writeFlow(directory)({ ...flow }, { path });
+};
+
+/**
+ * Write a flow to a domain in EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeFlowToDomain } = utils('/path/to/eventcatalog');
+ *
+ * // Flow would be written to domains/Orders/flows/PaymentFlow
+ * await writeFlowToDomain({
+ *   id: 'PaymentFlow',
+ *   name: 'Payment Flow',
+ *   version: '0.0.1',
+ *   markdown: '# Payment Flow',
+ *   steps: [],
+ * }, { id: 'Orders' });
+ * ```
+ */
+export const writeFlowToDomain =
+  (directory: string) =>
+  async (
+    flow: Flow,
+    domain: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    let pathForFlow =
+      domain.version && domain.version !== 'latest' ? `/${domain.id}/versioned/${domain.version}/flows` : `/${domain.id}/flows`;
+    pathForFlow = join(pathForFlow, flow.id);
+
+    await writeResource(directory, { ...flow }, { ...options, path: pathForFlow, type: 'flow' });
+  };
+
+/**
+ * Write a flow to a service in EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeFlowToService } = utils('/path/to/eventcatalog');
+ *
+ * // Flow would be written to services/PaymentService/flows/PaymentFlow
+ * await writeFlowToService({
+ *   id: 'PaymentFlow',
+ *   name: 'Payment Flow',
+ *   version: '0.0.1',
+ *   markdown: '# Payment Flow',
+ *   steps: [],
+ * }, { id: 'PaymentService' });
+ * ```
+ */
+export const writeFlowToService =
+  (directory: string) =>
+  async (
+    flow: Flow,
+    service: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    let pathForFlow =
+      service.version && service.version !== 'latest'
+        ? `/${service.id}/versioned/${service.version}/flows`
+        : `/${service.id}/flows`;
+    pathForFlow = join(pathForFlow, flow.id);
+
+    await writeResource(directory, { ...flow }, { ...options, path: pathForFlow, type: 'flow' });
+  };
+
+/**
+ * Write a flow to a system in EventCatalog.
+ */
+export const writeFlowToSystem =
+  (directory: string) =>
+  async (
+    flow: Flow,
+    system: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    const resourcePath = await getResourcePath(directory, system.id, system.version);
+    if (!resourcePath) {
+      throw new Error('System not found');
+    }
+
+    const pathForFlow = join(resourcePath.directory, 'flows', flow.id);
+    await writeResource(directory, { ...flow }, { ...options, path: pathForFlow, type: 'flow' });
+  };
+
+/**
+ * Write a flow to an agent in EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeFlowToAgent } = utils('/path/to/eventcatalog');
+ *
+ * // Flow would be written to agents/FraudReviewAgent/flows/PaymentFlow
+ * await writeFlowToAgent({
+ *   id: 'PaymentFlow',
+ *   name: 'Payment Flow',
+ *   version: '0.0.1',
+ *   markdown: '# Payment Flow',
+ *   steps: [],
+ * }, { id: 'FraudReviewAgent' });
+ * ```
+ */
+export const writeFlowToAgent =
+  (directory: string) =>
+  async (
+    flow: Flow,
+    agent: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    let pathForFlow =
+      agent.version && agent.version !== 'latest' ? `/${agent.id}/versioned/${agent.version}/flows` : `/${agent.id}/flows`;
+    pathForFlow = join(pathForFlow, flow.id);
+
+    await writeResource(directory, { ...flow }, { ...options, path: pathForFlow, type: 'flow' });
+  };
+
+/**
+ * Delete a flow at its given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmFlow } = utils('/path/to/eventcatalog');
+ *
+ * // Removes the flow at flows/PaymentFlow
+ * await rmFlow('/PaymentFlow');
+ * ```
+ */
+export const rmFlow = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+/**
+ * Delete a flow by its id.
+ *
+ * Optionally specify a version to delete a specific version of the flow.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmFlowById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest PaymentFlow flow
+ * await rmFlowById('PaymentFlow');
+ *
+ * // deletes a specific version of the PaymentFlow flow
+ * await rmFlowById('PaymentFlow', '0.0.1');
+ * ```
+ */
+export const rmFlowById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) => {
+  await rmResourceById(directory, id, version, { type: 'flow', persistFiles });
+};
+
+/**
+ * Version a flow by its id.
+ *
+ * Takes the latest flow and moves it to a versioned directory.
+ * All files with this flow are also versioned.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionFlow } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest PaymentFlow flow to a versioned directory
+ * await versionFlow('PaymentFlow');
+ * ```
+ */
+export const versionFlow = (directory: string) => async (id: string) => versionResource(directory, id);
+
+/**
+ * Check to see if the catalog has a version for the given flow.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { flowHasVersion } = utils('/path/to/eventcatalog');
+ *
+ * await flowHasVersion('PaymentFlow', '0.0.1');
+ * await flowHasVersion('PaymentFlow', 'latest');
+ * await flowHasVersion('PaymentFlow', '0.0.x');
+ * ```
+ */
+export const flowHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+/**
+ * Adds a file to the given flow.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addFileToFlow } = utils('/path/to/eventcatalog');
+ *
+ * // adds a file to the latest PaymentFlow flow
+ * await addFileToFlow('PaymentFlow', { content: 'Hello world', fileName: 'notes.md' });
+ *
+ * // adds a file to a specific version of the PaymentFlow flow
+ * await addFileToFlow('PaymentFlow', { content: 'Hello world', fileName: 'notes.md' }, '0.0.1');
+ * ```
+ */
+export const addFileToFlow =
+  (directory: string) =>
+  async (id: string, file: { content: string; fileName: string }, version?: string): Promise<void> =>
+    addFileToResource(directory, id, file, version, { type: 'flow' });
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
new file mode 100644
index 000000000..aeefaa24b
--- /dev/null
+++ b/packages/sdk/src/index.ts
@@ -0,0 +1,1741 @@
+import { join } from 'node:path';
+import { toDSL } from './dsl';
+import {
+  rmEvent,
+  rmEventById,
+  writeEvent,
+  writeEventToAgent,
+  writeEventToService,
+  versionEvent,
+  getEvent,
+  addFileToEvent,
+  addSchemaToEvent,
+  eventHasVersion,
+  getEvents,
+  addExampleToEvent,
+  getExamplesFromEvent,
+  removeExampleFromEvent,
+} from './events';
+import {
+  rmCommand,
+  rmCommandById,
+  writeCommand,
+  writeCommandToAgent,
+  writeCommandToService,
+  versionCommand,
+  getCommand,
+  getCommands,
+  addFileToCommand,
+  addSchemaToCommand,
+  commandHasVersion,
+  addExampleToCommand,
+  getExamplesFromCommand,
+  removeExampleFromCommand,
+} from './commands';
+import {
+  rmQuery,
+  rmQueryById,
+  writeQuery,
+  writeQueryToAgent,
+  writeQueryToService,
+  versionQuery,
+  getQuery,
+  getQueries,
+  addFileToQuery,
+  addSchemaToQuery,
+  queryHasVersion,
+  addExampleToQuery,
+  getExamplesFromQuery,
+  removeExampleFromQuery,
+} from './queries';
+import {
+  writeService,
+  writeServiceToDomain,
+  writeServiceToSystem,
+  getService,
+  versionService,
+  rmService,
+  rmServiceById,
+  addFileToService,
+  addMessageToService,
+  addEntityToService,
+  serviceHasVersion,
+  getSpecificationFilesForService,
+  writeVersionedService,
+  getServices,
+  getServiceByPath,
+  isService,
+  toService,
+  addDataStoreToService,
+} from './services';
+import {
+  addContainerToSystem,
+  addEntityToSystem,
+  addFileToSystem,
+  addFlowToSystem,
+  addServiceToSystem,
+  getSystem,
+  getSystemByPath,
+  getSystems,
+  isSystem,
+  rmSystem,
+  rmSystemById,
+  systemHasVersion,
+  toSystem,
+  versionSystem,
+  writeSystem,
+  writeSystemToDomain,
+} from './systems';
+import {
+  writeAgent,
+  writeAgentToDomain,
+  getAgent,
+  getAgents,
+  getAgentByPath,
+  writeVersionedAgent,
+  versionAgent,
+  rmAgent,
+  rmAgentById,
+  addFileToAgent,
+  addMessageToAgent,
+  addDataStoreToAgent,
+  addFlowToAgent,
+  agentHasVersion,
+  isAgent,
+  toAgent,
+} from './agents';
+import {
+  writeDomain,
+  getDomain,
+  getDomains,
+  versionDomain,
+  rmDomain,
+  rmDomainById,
+  addFileToDomain,
+  addUbiquitousLanguageToDomain,
+  domainHasVersion,
+  addServiceToDomain,
+  addAgentToDomain,
+  addSubDomainToDomain,
+  addSystemToDomain,
+  addEntityToDomain,
+  addDataProductToDomain,
+  getUbiquitousLanguageFromDomain,
+  addMessageToDomain,
+} from './domains';
+
+import {
+  rmChannel,
+  rmChannelById,
+  writeChannel,
+  versionChannel,
+  getChannel,
+  getChannels,
+  channelHasVersion,
+  addMessageToChannel,
+} from './channels';
+
+import {
+  getConsumersOfSchema,
+  getMessageBySchemaPath,
+  getProducersAndConsumersForMessage,
+  getProducersOfSchema,
+  getSchemaForMessage,
+} from './messages';
+
+import { getResourcePath, getResourceFolderName, getResources } from './internal/resources';
+
+import { writeCustomDoc, getCustomDoc, getCustomDocs, rmCustomDoc } from './custom-docs';
+
+import { writeTeam, getTeam, getTeams, rmTeamById, getOwnersForResource } from './teams';
+
+import { writeUser, getUser, getUsers, rmUserById } from './users';
+import { dumpCatalog, getEventCatalogConfigurationFile } from './eventcatalog';
+import { createSnapshot, diffSnapshots, listSnapshots } from './snapshots';
+import { writeChangelog, appendChangelog, getChangelog, rmChangelog } from './changelogs';
+import {
+  getEntity,
+  getEntities,
+  writeEntity,
+  writeEntityToSystem,
+  rmEntity,
+  rmEntityById,
+  versionEntity,
+  entityHasVersion,
+} from './entities';
+import {
+  addFileToFlow,
+  flowHasVersion,
+  getFlow,
+  getFlows,
+  rmFlow,
+  rmFlowById,
+  versionFlow,
+  writeFlow,
+  writeFlowToDomain,
+  writeFlowToAgent,
+  writeFlowToService,
+  writeFlowToSystem,
+  writeVersionedFlow,
+} from './flows';
+export { FlowBuilder } from './flow-builder';
+export type * from './flow-builder';
+
+import {
+  getDataStore,
+  getDataStores,
+  writeDataStore,
+  versionDataStore,
+  rmDataStore,
+  rmDataStoreById,
+  dataStoreHasVersion,
+  addFileToDataStore,
+  writeDataStoreToService,
+  writeDataStoreToSystem,
+} from './data-stores';
+
+import {
+  getDataProduct,
+  getDataProducts,
+  writeDataProduct,
+  writeDataProductToDomain,
+  versionDataProduct,
+  rmDataProduct,
+  rmDataProductById,
+  dataProductHasVersion,
+  addFileToDataProduct,
+} from './data-products';
+
+import {
+  getDiagram,
+  getDiagrams,
+  writeDiagram,
+  rmDiagram,
+  rmDiagramById,
+  versionDiagram,
+  diagramHasVersion,
+  addFileToDiagram,
+} from './diagrams';
+
+import { addFileToAdr, adrHasVersion, getAdr, getAdrs, rmAdr, rmAdrById, versionAdr, writeAdr } from './adrs';
+
+// Export the types
+export type * from './types';
+export type * from './snapshot-types';
+export type * from './flow-builder';
+
+/**
+ * Init the SDK for EventCatalog
+ *
+ * @param path - The path to the EventCatalog directory
+ *
+ */
+export default (path: string) => {
+  return {
+    /**
+     * Returns an events from EventCatalog
+     * @param id - The id of the event to retrieve
+     * @param version - Optional id of the version to get (supports semver)
+     * @returns Event|Undefined
+     */
+    getEvent: getEvent(join(path)),
+    /**
+     * Returns all events from EventCatalog
+     * @param latestOnly - optional boolean, set to true to get only latest versions
+     * @returns Event[]|Undefined
+     */
+    getEvents: getEvents(join(path)),
+    /**
+     * Adds an event to EventCatalog
+     *
+     * @param event - The event to write
+     * @param options - Optional options to write the event
+     *
+     */
+    writeEvent: writeEvent(join(path, 'events')),
+    /**
+     * Adds an event to a service in EventCatalog
+     *
+     * @param event - The event to write to the service
+     * @param service - The service and it's id to write to the event to
+     * @param options - Optional options to write the event
+     *
+     */
+    writeEventToService: writeEventToService(join(path)),
+    /**
+     * Adds an event to an agent in EventCatalog
+     *
+     * @param event - The event to write to the agent
+     * @param agent - The agent and its id to write the event to
+     * @param options - Optional options to write the event
+     *
+     */
+    writeEventToAgent: writeEventToAgent(join(path)),
+    /**
+     * Remove an event to EventCatalog (modeled on the standard POSIX rm utility)
+     *
+     * @param path - The path to your event, e.g. `/Inventory/InventoryAdjusted`
+     *
+     */
+    rmEvent: rmEvent(join(path, 'events')),
+    /**
+     * Remove an event by an Event id
+     *
+     * @param id - The id of the event you want to remove
+     *
+     */
+    rmEventById: rmEventById(join(path)),
+    /**
+     * Moves a given event id to the version directory
+     * @param directory
+     */
+    versionEvent: versionEvent(join(path)),
+    /**
+     * Adds a file to the given event
+     * @param id - The id of the event to add the file to
+     * @param file - File contents to add including the content and the file name
+     * @param version - Optional version of the event to add the file to
+     * @returns
+     */
+    addFileToEvent: addFileToEvent(join(path)),
+    /**
+     * Adds a schema to the given event
+     * @param id - The id of the event to add the schema to
+     * @param schema - Schema contents to add including the content and the file name
+     * @param version - Optional version of the event to add the schema to
+     * @returns
+     */
+    addSchemaToEvent: addSchemaToEvent(join(path)),
+    /**
+     * Check to see if an event version exists
+     * @param id - The id of the event
+     * @param version - The version of the event (supports semver)
+     * @returns
+     */
+    eventHasVersion: eventHasVersion(join(path)),
+    addExampleToEvent: addExampleToEvent(join(path)),
+    getExamplesFromEvent: getExamplesFromEvent(join(path)),
+    removeExampleFromEvent: removeExampleFromEvent(join(path)),
+
+    /**
+     * ================================
+     *            Commands
+     * ================================
+     */
+
+    /**
+     * Returns a command from EventCatalog
+     * @param id - The id of the command to retrieve
+     * @param version - Optional id of the version to get (supports semver)
+     * @returns Command|Undefined
+     */
+    getCommand: getCommand(join(path)),
+    /**
+     * Returns all commands from EventCatalog
+     * @param latestOnly - optional boolean, set to true to get only latest versions
+     * @returns Command[]|Undefined
+     */
+    getCommands: getCommands(join(path)),
+    /**
+     * Adds an command to EventCatalog
+     *
+     * @param command - The command to write
+     * @param options - Optional options to write the command
+     *
+     */
+    writeCommand: writeCommand(join(path, 'commands')),
+
+    /**
+     * Adds a command to a service in EventCatalog
+     *
+     * @param command - The command to write to the service
+     * @param service - The service and it's id to write to the command to
+     * @param options - Optional options to write the command
+     *
+     */
+    writeCommandToService: writeCommandToService(join(path)),
+    /**
+     * Adds a command to an agent in EventCatalog
+     *
+     * @param command - The command to write to the agent
+     * @param agent - The agent and its id to write the command to
+     * @param options - Optional options to write the command
+     *
+     */
+    writeCommandToAgent: writeCommandToAgent(join(path)),
+
+    /**
+     * Remove an command to EventCatalog (modeled on the standard POSIX rm utility)
+     *
+     * @param path - The path to your command, e.g. `/Inventory/InventoryAdjusted`
+     *
+     */
+    rmCommand: rmCommand(join(path, 'commands')),
+    /**
+     * Remove an command by an Event id
+     *
+     * @param id - The id of the command you want to remove
+     *
+     */
+    rmCommandById: rmCommandById(join(path)),
+    /**
+     * Moves a given command id to the version directory
+     * @param directory
+     */
+    versionCommand: versionCommand(join(path)),
+    /**
+     * Adds a file to the given command
+     * @param id - The id of the command to add the file to
+     * @param file - File contents to add including the content and the file name
+     * @param version - Optional version of the command to add the file to
+     * @returns
+     */
+    addFileToCommand: addFileToCommand(join(path)),
+    /**
+     * Adds a schema to the given command
+     * @param id - The id of the command to add the schema to
+     * @param schema - Schema contents to add including the content and the file name
+     * @param version - Optional version of the command to add the schema to
+     * @returns
+     */
+    addSchemaToCommand: addSchemaToCommand(join(path)),
+
+    /**
+     * Check to see if a command version exists
+     * @param id - The id of the command
+     * @param version - The version of the command (supports semver)
+     * @returns
+     */
+    commandHasVersion: commandHasVersion(join(path)),
+    addExampleToCommand: addExampleToCommand(join(path)),
+    getExamplesFromCommand: getExamplesFromCommand(join(path)),
+    removeExampleFromCommand: removeExampleFromCommand(join(path)),
+
+    /**
+     * ================================
+     *            Queries
+     * ================================
+     */
+
+    /**
+     * Returns a query from EventCatalog
+     * @param id - The id of the query to retrieve
+     * @param version - Optional id of the version to get (supports semver)
+     * @returns Query|Undefined
+     */
+    getQuery: getQuery(join(path)),
+    /**
+     * Returns all queries from EventCatalog
+     * @param latestOnly - optional boolean, set to true to get only latest versions
+     * @returns Query[]|Undefined
+     */
+    getQueries: getQueries(join(path)),
+    /**
+     * Adds a query to EventCatalog
+     *
+     * @param query - The query to write
+     * @param options - Optional options to write the event
+     *
+     */
+    writeQuery: writeQuery(join(path, 'queries')),
+    /**
+     * Adds a query to a service in EventCatalog
+     *
+     * @param query - The query to write to the service
+     * @param service - The service and it's id to write to the query to
+     * @param options - Optional options to write the query
+     *
+     */
+    writeQueryToService: writeQueryToService(join(path)),
+    /**
+     * Adds a query to an agent in EventCatalog
+     *
+     * @param query - The query to write to the agent
+     * @param agent - The agent and its id to write the query to
+     * @param options - Optional options to write the query
+     *
+     */
+    writeQueryToAgent: writeQueryToAgent(join(path)),
+    /**
+     * Remove an query to EventCatalog (modeled on the standard POSIX rm utility)
+     *
+     * @param path - The path to your query, e.g. `/Orders/GetOrder`
+     *
+     */
+    rmQuery: rmQuery(join(path, 'queries')),
+    /**
+     * Remove a query by a Query id
+     *
+     * @param id - The id of the query you want to remove
+     *
+     */
+    rmQueryById: rmQueryById(join(path)),
+    /**
+     * Moves a given query id to the version directory
+     * @param directory
+     */
+    versionQuery: versionQuery(join(path)),
+    /**
+     * Adds a file to the given query
+     * @param id - The id of the query to add the file to
+     * @param file - File contents to add including the content and the file name
+     * @param version - Optional version of the query to add the file to
+     * @returns
+     */
+    addFileToQuery: addFileToQuery(join(path)),
+    /**
+     * Adds a schema to the given query
+     * @param id - The id of the query to add the schema to
+     * @param schema - Schema contents to add including the content and the file name
+     * @param version - Optional version of the query to add the schema to
+     * @returns
+     */
+    addSchemaToQuery: addSchemaToQuery(join(path)),
+    /**
+     * Check to see if an query version exists
+     * @param id - The id of the query
+     * @param version - The version of the query (supports semver)
+     * @returns
+     */
+    queryHasVersion: queryHasVersion(join(path)),
+    addExampleToQuery: addExampleToQuery(join(path)),
+    getExamplesFromQuery: getExamplesFromQuery(join(path)),
+    removeExampleFromQuery: removeExampleFromQuery(join(path)),
+
+    /**
+     * ================================
+     *            Channels
+     * ================================
+     */
+
+    /**
+     * Returns a channel from EventCatalog
+     * @param id - The id of the channel to retrieve
+     * @param version - Optional id of the version to get (supports semver)
+     * @returns Channel|Undefined
+     */
+    getChannel: getChannel(join(path)),
+    /**
+     * Returns all channels from EventCatalog
+     * @param latestOnly - optional boolean, set to true to get only latest versions
+     * @returns Channel[]|Undefined
+     */
+    getChannels: getChannels(join(path)),
+    /**
+     * Adds an channel to EventCatalog
+     *
+     * @param command - The channel to write
+     * @param options - Optional options to write the channel
+     *
+     */
+    writeChannel: writeChannel(join(path, 'channels')),
+
+    /**
+     * Remove an channel to EventCatalog (modeled on the standard POSIX rm utility)
+     *
+     * @param path - The path to your channel, e.g. `/Inventory/InventoryAdjusted`
+     *
+     */
+    rmChannel: rmChannel(join(path, 'channels')),
+    /**
+     * Remove an channel by an Event id
+     *
+     * @param id - The id of the channel you want to remove
+     *
+     */
+    rmChannelById: rmChannelById(join(path)),
+    /**
+     * Moves a given channel id to the version directory
+     * @param directory
+     */
+    versionChannel: versionChannel(join(path)),
+
+    /**
+     * Check to see if a channel version exists
+     * @param id - The id of the channel
+     * @param version - The version of the channel (supports semver)
+     * @returns
+     */
+    channelHasVersion: channelHasVersion(join(path)),
+
+    /**
+     * Add a channel to an event
+     *
+     * Optionally specify a version to add the channel to a specific version of the event.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addEventToChannel } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new event (InventoryUpdatedEvent) to the inventory.{env}.events channel
+     * await addEventToChannel('inventory.{env}.events channel', { id: 'InventoryUpdatedEvent', version: '2.0.0', parameters: { env: 'dev' } });
+     *
+     * ```
+     */
+    addEventToChannel: addMessageToChannel(join(path), 'events'),
+    /**
+     * Add a channel to an command
+     *
+     * Optionally specify a version to add the channel to a specific version of the command.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addCommandToChannel } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new command (UpdateInventory) to the inventory.{env}.events channel
+     * await addCommandToChannel('inventory.{env}.events channel', { id: 'UpdateInventory', version: '2.0.0', parameters: { env: 'dev' } });
+     *
+     * ```
+     */
+    addCommandToChannel: addMessageToChannel(join(path), 'commands'),
+
+    /**
+     * Add a channel to an query
+     *
+     * Optionally specify a version to add the channel to a specific version of the query.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addQueryToChannel } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new query (GetInventory) to the inventory.{env}.events channel
+     * await addQueryToChannel('inventory.{env}.events channel', { id: 'GetInventory', version: '2.0.0', parameters: { env: 'dev' } });
+     *
+     * ```
+     */
+    addQueryToChannel: addMessageToChannel(join(path), 'queries'),
+
+    /**
+     * ================================
+     *            SERVICES
+     * ================================
+     */
+
+    /**
+     * Adds a service to EventCatalog
+     *
+     * @param service - The service to write
+     * @param options - Optional options to write the event
+     *
+     */
+    writeService: writeService(join(path, 'services')),
+
+    /**
+     * Adds a versioned service to EventCatalog
+     *
+     * @param service - The service to write
+     *
+     */
+    writeVersionedService: writeVersionedService(join(path, 'services')),
+
+    /**
+     * Adds a service to a domain in EventCatalog
+     *
+     * @param service - The service to write
+     * @param domain - The domain to add the service to
+     * @param options - Optional options to write the event
+     *
+     */
+    writeServiceToDomain: writeServiceToDomain(join(path, 'domains')),
+    /**
+     * Adds a service to a system in EventCatalog
+     *
+     * @param service - The service to write
+     * @param system - The system to add the service to
+     * @param options - Optional options to write the service
+     *
+     */
+    writeServiceToSystem: writeServiceToSystem(join(path)),
+    /**
+     * Returns a service from EventCatalog
+     * @param id - The id of the service to retrieve
+     * @param version - Optional id of the version to get (supports semver)
+     * @returns Service|Undefined
+     */
+    getService: getService(join(path)),
+    /**
+     * Returns a service from EventCatalog by it's path.
+     * @param path - The path to the service to retrieve
+     * @returns Service|Undefined
+     */
+    getServiceByPath: getServiceByPath(join(path)),
+    /**
+     * Returns all services from EventCatalog
+     * @param latestOnly - optional boolean, set to true to get only latest versions
+     * @returns Service[]|Undefined
+     */
+    getServices: getServices(join(path)),
+    /**
+     * Moves a given service id to the version directory
+     * @param directory
+     */
+    versionService: versionService(join(path)),
+    /**
+     * Remove a service from EventCatalog (modeled on the standard POSIX rm utility)
+     *
+     * @param path - The path to your service, e.g. `/InventoryService`
+     *
+     */
+    rmService: rmService(join(path, 'services')),
+    /**
+     * Remove an service by an service id
+     *
+     * @param id - The id of the service you want to remove
+     *
+     */
+    rmServiceById: rmServiceById(join(path)),
+    /**
+     * Adds a file to the given service
+     * @param id - The id of the service to add the file to
+     * @param file - File contents to add including the content and the file name
+     * @param version - Optional version of the service to add the file to
+     * @returns
+     */
+    addFileToService: addFileToService(join(path)),
+
+    /**
+     * Returns the specifications for a given service
+     * @param id - The id of the service to retrieve the specifications for
+     * @param version - Optional version of the service
+     * @returns
+     */
+    getSpecificationFilesForService: getSpecificationFilesForService(join(path)),
+
+    /**
+     * Check to see if a service version exists
+     * @param id - The id of the service
+     * @param version - The version of the service (supports semver)
+     * @returns
+     */
+    serviceHasVersion: serviceHasVersion(join(path)),
+
+    /**
+     * Add an event to a service by it's id.
+     *
+     * Optionally specify a version to add the event to a specific version of the service.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addEventToService } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new event (InventoryUpdatedEvent) that the InventoryService will send
+     * await addEventToService('InventoryService', 'sends', { event: 'InventoryUpdatedEvent', version: '2.0.0' });
+     *
+     * // adds a new event (OrderComplete) that the InventoryService will receive
+     * await addEventToService('InventoryService', 'receives', { event: 'OrderComplete', version: '2.0.0' });
+     *
+     * ```
+     */
+    addEventToService: addMessageToService(join(path)),
+
+    /**
+     * Add a data store to a service by it's id.
+     *
+     * Optionally specify a version to add the data store to a specific version of the service.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addDataStoreToService } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new data store (orders-db) that the InventoryService will write to
+     * await addDataStoreToService('InventoryService', 'writesTo', { id: 'orders-db', version: '2.0.0' });
+     *
+     * ```
+     */
+    addDataStoreToService: addDataStoreToService(join(path)),
+    /**
+     * Add a command to a service by it's id.
+     *
+     * Optionally specify a version to add the event to a specific version of the service.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addCommandToService } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new command (UpdateInventoryCommand) that the InventoryService will send
+     * await addCommandToService('InventoryService', 'sends', { command: 'UpdateInventoryCommand', version: '2.0.0' });
+     *
+     * // adds a new command (VerifyInventory) that the InventoryService will receive
+     * await addCommandToService('InventoryService', 'receives', { command: 'VerifyInventory', version: '2.0.0' });
+     *
+     * ```
+     */
+    addCommandToService: addMessageToService(join(path)),
+    /**
+     * Add a query to a service by it's id.
+     *
+     * Optionally specify a version to add the event to a specific version of the service.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addQueryToService } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new query (UpdateInventory) that the InventoryService will send
+     * await addQueryToService('InventoryService', 'sends', { command: 'UpdateInventory', version: '2.0.0' });
+     *
+     * // adds a new command (VerifyInventory) that the InventoryService will receive
+     * await addQueryToService('InventoryService', 'receives', { command: 'VerifyInventory', version: '2.0.0' });
+     *
+     * ```
+     */
+    addQueryToService: addMessageToService(join(path)),
+
+    /**
+     * Add an entity to a service by its id.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addEntityToService } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new entity (User) to the InventoryService
+     * await addEntityToService('InventoryService', { id: 'User', version: '1.0.0' });
+     *
+     * // adds a new entity (Product) to a specific version of the InventoryService
+     * await addEntityToService('InventoryService', { id: 'Product', version: '1.0.0' }, '2.0.0');
+     *
+     * ```
+     */
+    addEntityToService: addEntityToService(join(path)),
+
+    /**
+     * Check to see if a service exists by it's path.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { isService } = utils('/path/to/eventcatalog');
+     *
+     * // returns true if the path is a service
+     * await isService('/services/InventoryService/index.mdx');
+     * ```
+     *
+     * @param path - The path to the service to check
+     * @returns boolean
+     */
+    isService: isService(join(path)),
+
+    /**
+     * Converts a file to a service.
+     * @param file - The file to convert to a service.
+     * @returns The service.
+     */
+    toService: toService(join(path)),
+
+    /**
+     * ================================
+     *            Systems
+     * ================================
+     */
+    writeSystem: writeSystem(join(path, 'systems')),
+    writeSystemToDomain: writeSystemToDomain(join(path)),
+    getSystem: getSystem(join(path)),
+    getSystemByPath: getSystemByPath(join(path)),
+    getSystems: getSystems(join(path)),
+    versionSystem: versionSystem(join(path)),
+    rmSystem: rmSystem(join(path, 'systems')),
+    rmSystemById: rmSystemById(join(path)),
+    addFileToSystem: addFileToSystem(join(path)),
+    addServiceToSystem: addServiceToSystem(join(path)),
+    addFlowToSystem: addFlowToSystem(join(path)),
+    addEntityToSystem: addEntityToSystem(join(path)),
+    addContainerToSystem: addContainerToSystem(join(path)),
+    systemHasVersion: systemHasVersion(join(path)),
+    isSystem: isSystem(join(path)),
+    toSystem: toSystem(join(path)),
+
+    /**
+     * ================================
+     *            Agents
+     * ================================
+     */
+    writeAgent: writeAgent(join(path, 'agents')),
+    writeVersionedAgent: writeVersionedAgent(join(path, 'agents')),
+    writeAgentToDomain: writeAgentToDomain(join(path, 'domains')),
+    getAgent: getAgent(join(path)),
+    getAgentByPath: getAgentByPath(join(path)),
+    getAgents: getAgents(join(path)),
+    versionAgent: versionAgent(join(path)),
+    rmAgent: rmAgent(join(path, 'agents')),
+    rmAgentById: rmAgentById(join(path)),
+    addFileToAgent: addFileToAgent(join(path)),
+    addEventToAgent: addMessageToAgent(join(path)),
+    addCommandToAgent: addMessageToAgent(join(path)),
+    addQueryToAgent: addMessageToAgent(join(path)),
+    addDataStoreToAgent: addDataStoreToAgent(join(path)),
+    addFlowToAgent: addFlowToAgent(join(path)),
+    agentHasVersion: agentHasVersion(join(path)),
+    isAgent: isAgent(join(path)),
+    toAgent: toAgent(join(path)),
+
+    /**
+     * ================================
+     *            Domains
+     * ================================
+     */
+
+    /**
+     * Adds a domain to EventCatalog
+     *
+     * @param domain - The domain to write
+     * @param options - Optional options to write the event
+     *
+     */
+    writeDomain: writeDomain(join(path, 'domains')),
+
+    /**
+     * Returns a domain from EventCatalog
+     * @param id - The id of the domain to retrieve
+     * @param version - Optional id of the version to get (supports semver)
+     * @returns Domain|Undefined
+     */
+    getDomain: getDomain(join(path, 'domains')),
+    /**
+     * Returns all domains from EventCatalog
+     * @param latestOnly - optional boolean, set to true to get only latest versions
+     * @returns Domain[]|Undefined
+     */
+    getDomains: getDomains(join(path)),
+    /**
+     * Moves a given domain id to the version directory
+     * @param directory
+     */
+    versionDomain: versionDomain(join(path, 'domains')),
+    /**
+     * Remove a domain from EventCatalog (modeled on the standard POSIX rm utility)
+     *
+     * @param path - The path to your domain, e.g. `/Payment`
+     *
+     */
+    rmDomain: rmDomain(join(path, 'domains')),
+    /**
+     * Remove an service by an domain id
+     *
+     * @param id - The id of the domain you want to remove
+     *
+     */
+    rmDomainById: rmDomainById(join(path, 'domains')),
+    /**
+     * Adds a file to the given domain
+     * @param id - The id of the domain to add the file to
+     * @param file - File contents to add including the content and the file name
+     * @param version - Optional version of the domain to add the file to
+     * @returns
+     */
+    addFileToDomain: addFileToDomain(join(path, 'domains')),
+
+    /**
+     * Adds an ubiquitous language dictionary to a domain
+     * @param id - The id of the domain to add the ubiquitous language to
+     * @param ubiquitousLanguageDictionary - The ubiquitous language dictionary to add
+     * @param version - Optional version of the domain to add the ubiquitous language to
+     */
+    addUbiquitousLanguageToDomain: addUbiquitousLanguageToDomain(join(path, 'domains')),
+
+    /**
+     * Get the ubiquitous language dictionary from a domain
+     * @param id - The id of the domain to get the ubiquitous language from
+     * @param version - Optional version of the domain to get the ubiquitous language from
+     * @returns
+     */
+    getUbiquitousLanguageFromDomain: getUbiquitousLanguageFromDomain(join(path, 'domains')),
+
+    /**
+     * Check to see if a domain version exists
+     * @param id - The id of the domain
+     * @param version - The version of the domain (supports semver)
+     * @returns
+     */
+    domainHasVersion: domainHasVersion(join(path)),
+
+    /**
+     * Adds a given service to a domain
+     * @param id - The id of the domain
+     * @param service - The id and version of the service to add
+     * @param version - (Optional) The version of the domain to add the service to
+     * @returns
+     */
+    addServiceToDomain: addServiceToDomain(join(path, 'domains')),
+
+    /**
+     * Adds a given agent to a domain
+     * @param id - The id of the domain
+     * @param agent - The id and version of the agent to add
+     * @param version - (Optional) The version of the domain to add the agent to
+     * @returns
+     */
+    addAgentToDomain: addAgentToDomain(join(path, 'domains')),
+
+    /**
+     * Adds a given subdomain to a domain
+     * @param id - The id of the domain
+     * @param subDomain - The id and version of the subdomain to add
+     * @param version - (Optional) The version of the domain to add the subdomain to
+     * @returns
+     */
+    addSubDomainToDomain: addSubDomainToDomain(join(path, 'domains')),
+
+    /**
+     * Adds a given system to a domain
+     * @param id - The id of the domain
+     * @param system - The id and version of the system to add
+     * @param version - (Optional) The version of the domain to add the system to
+     * @returns
+     */
+    addSystemToDomain: addSystemToDomain(join(path, 'domains')),
+
+    /**
+     * Adds an entity to a domain
+     * @param id - The id of the domain
+     * @param entity - The id and version of the entity to add
+     * @param version - (Optional) The version of the domain to add the entity to
+     * @returns
+     */
+    addEntityToDomain: addEntityToDomain(join(path, 'domains')),
+
+    /**
+     * Add an event to a domain by its id.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addEventToDomain } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new event (OrderCreated) that the Orders domain will send
+     * await addEventToDomain('Orders', 'sends', { id: 'OrderCreated', version: '2.0.0' });
+     *
+     * // adds a new event (PaymentProcessed) that the Orders domain will receive
+     * await addEventToDomain('Orders', 'receives', { id: 'PaymentProcessed', version: '2.0.0' });
+     *
+     * ```
+     */
+    addEventToDomain: addMessageToDomain(join(path, 'domains')),
+
+    /**
+     * Add a command to a domain by its id.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addCommandToDomain } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new command (ProcessOrder) that the Orders domain will send
+     * await addCommandToDomain('Orders', 'sends', { id: 'ProcessOrder', version: '2.0.0' });
+     *
+     * // adds a new command (CancelOrder) that the Orders domain will receive
+     * await addCommandToDomain('Orders', 'receives', { id: 'CancelOrder', version: '2.0.0' });
+     *
+     * ```
+     */
+    addCommandToDomain: addMessageToDomain(join(path, 'domains')),
+
+    /**
+     * Add a query to a domain by its id.
+     *
+     * @example
+     * ```ts
+     * import utils from '@eventcatalog/utils';
+     *
+     * const { addQueryToDomain } = utils('/path/to/eventcatalog');
+     *
+     * // adds a new query (GetOrderStatus) that the Orders domain will send
+     * await addQueryToDomain('Orders', 'sends', { id: 'GetOrderStatus', version: '2.0.0' });
+     *
+     * // adds a new query (GetInventory) that the Orders domain will receive
+     * await addQueryToDomain('Orders', 'receives', { id: 'GetInventory', version: '2.0.0' });
+     *
+     * ```
+     */
+    addQueryToDomain: addMessageToDomain(join(path, 'domains')),
+
+    /**
+     * ================================
+     *            Teams
+     * ================================
+     */
+    /**
+     * Adds a team to EventCatalog
+     *
+     * @param team - The team to write
+     * @param options - Optional options to write the team
+     *
+     */
+    writeTeam: writeTeam(join(path, 'teams')),
+    /**
+     * Returns a team from EventCatalog
+     * @param id - The id of the team to retrieve
+     * @returns Team|Undefined
+     */
+    getTeam: getTeam(join(path, 'teams')),
+    /**
+     * Returns all teams from EventCatalog
+     * @returns Team[]|Undefined
+     */
+    getTeams: getTeams(join(path, 'teams')),
+    /**
+     * Remove a team by the team id
+     *
+     * @param id - The id of the team you want to remove
+     *
+     */
+    rmTeamById: rmTeamById(join(path, 'teams')),
+
+    /**
+     * ================================
+     *            Users
+     * ================================
+     */
+    /**
+     * Adds a user to EventCatalog
+     *
+     * @param user - The user to write
+     * @param options - Optional options to write the user
+     *
+     */
+    writeUser: writeUser(join(path, 'users')),
+    /**
+     * Returns a user from EventCatalog
+     * @param id - The id of the user to retrieve
+     * @returns User|Undefined
+     */
+    getUser: getUser(join(path, 'users')),
+    /**
+     * Returns all user from EventCatalog
+     * @returns User[]|Undefined
+     */
+    getUsers: getUsers(join(path)),
+    /**
+     * Remove a user by the user id
+     *
+     * @param id - The id of the user you want to remove
+     *
+     */
+    rmUserById: rmUserById(join(path, 'users')),
+
+    /**
+     * ================================
+     *            Custom Docs
+     * ================================
+     */
+
+    /**
+     * Returns a custom doc from EventCatalog
+     * @param path - The path to the custom doc to retrieve
+     * @returns CustomDoc|Undefined
+     */
+    getCustomDoc: getCustomDoc(join(path, 'docs')),
+    /**
+     * Returns all custom docs from EventCatalog
+     * @param options - Optional options to get custom docs from a specific path
+     * @returns CustomDoc[]|Undefined
+     */
+    getCustomDocs: getCustomDocs(join(path, 'docs')),
+    /**
+     * Writes a custom doc to EventCatalog
+     * @param customDoc - The custom doc to write
+     * @param options - Optional options to write the custom doc
+     *
+     */
+    writeCustomDoc: writeCustomDoc(join(path, 'docs')),
+
+    /**
+     * Removes a custom doc from EventCatalog
+     * @param path - The path to the custom doc to remove
+     *
+     */
+    rmCustomDoc: rmCustomDoc(join(path, 'docs')),
+
+    /**
+     * Dumps the catalog to a JSON file.
+     * @param directory - The directory to dump the catalog to
+     * @returns A JSON file with the catalog
+     */
+    dumpCatalog: dumpCatalog(join(path)),
+
+    /**
+     * Returns the event catalog configuration file.
+     * The event catalog configuration file is the file that contains the configuration for the event catalog.
+     *
+     * @param directory - The directory of the catalog.
+     * @returns A JSON object with the configuration for the event catalog.
+     */
+    getEventCatalogConfigurationFile: getEventCatalogConfigurationFile(join(path)),
+    /**
+     * ================================
+     *            Changelogs
+     * ================================
+     */
+
+    /**
+     * Writes a changelog entry to a resource in EventCatalog
+     *
+     * @param id - The id of the resource to write the changelog to
+     * @param changelog - The changelog entry to write
+     * @param options - Optional options (version, format)
+     *
+     */
+    writeChangelog: writeChangelog(join(path)),
+    /**
+     * Appends a changelog entry to an existing changelog for a resource.
+     * If no changelog exists, one is created.
+     *
+     * @param id - The id of the resource to append the changelog to
+     * @param changelog - The changelog entry to append
+     * @param options - Optional options (version, format)
+     *
+     */
+    appendChangelog: appendChangelog(join(path)),
+    /**
+     * Returns the changelog for a resource in EventCatalog
+     *
+     * @param id - The id of the resource to get the changelog for
+     * @param options - Optional options (version)
+     * @returns Changelog|Undefined
+     */
+    getChangelog: getChangelog(join(path)),
+    /**
+     * Removes the changelog for a resource in EventCatalog
+     *
+     * @param id - The id of the resource to remove the changelog from
+     * @param options - Optional options (version)
+     *
+     */
+    rmChangelog: rmChangelog(join(path)),
+
+    /**
+     * ================================
+     *            Resources Utils
+     * ================================
+     */
+
+    /**
+     * Returns the path to a given resource by id and version
+     */
+    getResourcePath: getResourcePath,
+
+    /**
+     * Returns the folder name of a given resource
+     */
+    getResourceFolderName: getResourceFolderName,
+
+    /**
+     * Returns resources from the catalog for a given type
+     */
+    getResources: getResources,
+
+    /**
+     * ================================
+     *            General Message Utils
+     * ================================
+     */
+
+    /**
+     * Returns a message from EventCatalog by a given schema path.
+     *
+     * @param path - The path to the message to retrieve
+     * @returns Message|Undefined
+     */
+    getMessageBySchemaPath: getMessageBySchemaPath(join(path)),
+
+    /**
+     * Returns the producers and consumers (services and agents) for a given message
+     * @param id - The id of the message to get the producers and consumers for
+     * @param version - Optional version of the message
+     * @returns { producers: (Service|Agent)[], consumers: (Service|Agent)[] }
+     */
+    getProducersAndConsumersForMessage: getProducersAndConsumersForMessage(join(path)),
+
+    /**
+     * Returns the consumers of a given schema path
+     * @param path - The path to the schema to get the consumers for
+     * @returns (Service|Agent)[]
+     */
+    getConsumersOfSchema: getConsumersOfSchema(join(path)),
+
+    /**
+     * Returns the producers of a given schema path
+     * @param path - The path to the schema to get the producers for
+     * @returns (Service|Agent)[]
+     */
+    getProducersOfSchema: getProducersOfSchema(join(path)),
+
+    /**
+     * Returns the schema for a given message (event, command or query) by its id and version.
+     * If no version is given, the latest version is used.
+     * @param id - The id of the message to get the schema for
+     * @param version - Optional version of the message
+     * @returns { schema: string, fileName: string } | undefined
+     */
+    getSchemaForMessage: getSchemaForMessage(join(path)),
+
+    /**
+     * Returns the owners for a given resource (e.g domain, service, event, command, query, etc.)
+     * @param id - The id of the resource to get the owners for
+     * @param version - Optional version of the resource
+     * @returns { owners: User[] }
+     */
+    getOwnersForResource: getOwnersForResource(join(path)),
+
+    /**
+     * ================================
+     *            Entities
+     * ================================
+     */
+
+    /**
+     * Returns an entity from EventCatalog
+     * @param id - The id of the entity to retrieve
+     * @param version - Optional id of the version to get (supports semver)
+     * @returns Entity|Undefined
+     */
+    getEntity: getEntity(join(path)),
+    /**
+     * Returns all entities from EventCatalog
+     * @param latestOnly - optional boolean, set to true to get only latest versions
+     * @returns Entity[]|Undefined
+     */
+    getEntities: getEntities(join(path)),
+    /**
+     * Adds an entity to EventCatalog
+     *
+     * @param entity - The entity to write
+     * @param options - Optional options to write the entity
+     *
+     */
+    writeEntity: writeEntity(join(path, 'entities')),
+    /**
+     * Adds an entity to a system in EventCatalog
+     *
+     * @param entity - The entity to write to the system
+     * @param system - The system and its id to write the entity to
+     * @param options - Optional options to write the entity
+     *
+     */
+    writeEntityToSystem: writeEntityToSystem(join(path)),
+    /**
+     * Remove an entity from EventCatalog (modeled on the standard POSIX rm utility)
+     *
+     * @param path - The path to your entity, e.g. `/User`
+     *
+     */
+    rmEntity: rmEntity(join(path, 'entities')),
+    /**
+     * Remove an entity by an entity id
+     *
+     * @param id - The id of the entity you want to remove
+     *
+     */
+    rmEntityById: rmEntityById(join(path)),
+    /**
+     * Moves a given entity id to the version directory
+     * @param id - The id of the entity to version
+     */
+    versionEntity: versionEntity(join(path)),
+    /**
+     * Check to see if an entity version exists
+     * @param id - The id of the entity
+     * @param version - The version of the entity (supports semver)
+     * @returns
+     */
+    entityHasVersion: entityHasVersion(join(path)),
+
+    /**
+     * ================================
+     *              Flows
+     * ================================
+     */
+    /**
+     * Returns a flow from EventCatalog
+     *
+     * @param id - The id of the flow to retrieve
+     * @param version - Optional version of the flow
+     * @returns Flow
+     */
+    getFlow: getFlow(join(path)),
+    /**
+     * Returns all flows from EventCatalog
+     *
+     * @param options - optional options to get flows
+     * @param latestOnly - optional boolean, set to true to get only latest versions
+     * @returns Flow[]|Undefined
+     */
+    getFlows: getFlows(join(path)),
+    /**
+     * Adds a flow to EventCatalog
+     *
+     * @param flow - The flow to write
+     * @param options - Optional options to write the flow
+     *
+     */
+    writeFlow: writeFlow(join(path, 'flows')),
+    /**
+     * Adds a versioned flow to EventCatalog
+     *
+     * @param flow - The flow to write
+     *
+     */
+    writeVersionedFlow: writeVersionedFlow(join(path, 'flows')),
+    /**
+     * Adds a flow to a domain in EventCatalog
+     *
+     * @param flow - The flow to write to the domain
+     * @param domain - The domain and its id to write the flow to
+     * @param options - Optional options to write the flow
+     *
+     */
+    writeFlowToDomain: writeFlowToDomain(join(path, 'domains')),
+    /**
+     * Adds a flow to a service in EventCatalog
+     *
+     * @param flow - The flow to write to the service
+     * @param service - The service and its id to write the flow to
+     * @param options - Optional options to write the flow
+     *
+     */
+    writeFlowToService: writeFlowToService(join(path, 'services')),
+    /**
+     * Adds a flow to a system in EventCatalog
+     *
+     * @param flow - The flow to write to the system
+     * @param system - The system and its id to write the flow to
+     * @param options - Optional options to write the flow
+     *
+     */
+    writeFlowToSystem: writeFlowToSystem(join(path)),
+    /**
+     * Adds a flow to an agent in EventCatalog
+     *
+     * @param flow - The flow to write to the agent
+     * @param agent - The agent and its id to write the flow to
+     * @param options - Optional options to write the flow
+     *
+     */
+    writeFlowToAgent: writeFlowToAgent(join(path, 'agents')),
+    /**
+     * Remove a flow from EventCatalog (modeled on the standard POSIX rm utility)
+     *
+     * @param path - The path to your flow, e.g. `/PaymentFlow`
+     *
+     */
+    rmFlow: rmFlow(join(path, 'flows')),
+    /**
+     * Remove a flow by a flow id
+     *
+     * @param id - The id of the flow you want to remove
+     *
+     */
+    rmFlowById: rmFlowById(join(path)),
+    /**
+     * Moves a given flow id to the version directory
+     * @param id - The id of the flow to version
+     */
+    versionFlow: versionFlow(join(path)),
+    /**
+     * Check to see if a flow version exists
+     * @param id - The id of the flow
+     * @param version - The version of the flow (supports semver)
+     * @returns
+     */
+    flowHasVersion: flowHasVersion(join(path)),
+    /**
+     * Adds a file to the given flow
+     * @param id - The id of the flow to add the file to
+     * @param file - File contents to add including the content and the file name
+     * @param version - Optional version of the flow to add the file to
+     * @returns
+     */
+    addFileToFlow: addFileToFlow(join(path)),
+
+    /**
+     * ================================
+     *            Data Stores
+     * ================================
+     */
+    /**
+     * Adds a data store to EventCatalog
+     * @param dataStore - The data store to write
+     * @param options - Optional options to write the data store
+     *
+     */
+    writeDataStore: writeDataStore(join(path, 'containers')),
+
+    /**
+     * Returns a data store from EventCatalog
+     * @param id - The id of the data store to retrieve
+     * @param version - Optional id of the version to get (supports semver)
+     * @returns Container|Undefined
+     */
+    getDataStore: getDataStore(join(path)),
+
+    /**
+     * Returns all data stores from EventCatalog
+     * @param latestOnly - optional boolean, set to true to get only latest versions
+     * @returns Container[]|Undefined
+     */
+    getDataStores: getDataStores(join(path)),
+
+    /**
+     * Version a data store by its id
+     * @param id - The id of the data store to version
+     */
+    versionDataStore: versionDataStore(join(path, 'containers')),
+
+    /**
+     * Remove a data store by its path
+     * @param path - The path to the data store to remove
+     */
+    rmDataStore: rmDataStore(join(path, 'containers')),
+
+    /**
+     * Remove a data store by its id
+     * @param id - The id of the data store to remove
+     */
+    rmDataStoreById: rmDataStoreById(join(path)),
+
+    /**
+     * Check to see if a data store version exists
+     * @param id - The id of the data store
+     * @param version - The version of the data store (supports semver)
+     * @returns
+     */
+    dataStoreHasVersion: dataStoreHasVersion(join(path)),
+
+    /**
+     * Adds a file to a data store by its id
+     * @param id - The id of the data store to add the file to
+     * @param file - File contents to add including the content and the file name
+     * @param version - Optional version of the data store to add the file to
+     * @returns
+     */
+    addFileToDataStore: addFileToDataStore(join(path)),
+
+    /**
+     * Writes a data store to a service by its id
+     * @param dataStore - The data store to write
+     * @param service - The service to write the data store to
+     * @returns
+     */
+    writeDataStoreToService: writeDataStoreToService(join(path)),
+
+    /**
+     * Writes a data store to a system by its id
+     * @param dataStore - The data store to write
+     * @param system - The system to write the data store to
+     * @returns
+     */
+    writeDataStoreToSystem: writeDataStoreToSystem(join(path)),
+
+    /**
+     * ================================
+     *            Data Products
+     * ================================
+     */
+    /**
+     * Adds a data product to EventCatalog
+     * @param dataProduct - The data product to write
+     * @param options - Optional options to write the data product
+     *
+     */
+    writeDataProduct: writeDataProduct(join(path, 'data-products')),
+
+    /**
+     * Writes a data product to a domain in EventCatalog
+     * @param dataProduct - The data product to write
+     * @param domain - The domain to write the data product to
+     * @param options - Optional options to write the data product
+     *
+     */
+    writeDataProductToDomain: writeDataProductToDomain(join(path, 'domains')),
+
+    /**
+     * Returns a data product from EventCatalog
+     * @param id - The id of the data product to retrieve
+     * @param version - Optional id of the version to get (supports semver)
+     * @returns DataProduct|Undefined
+     */
+    getDataProduct: getDataProduct(join(path)),
+
+    /**
+     * Returns all data products from EventCatalog
+     * @param latestOnly - optional boolean, set to true to get only latest versions
+     * @returns DataProduct[]|Undefined
+     */
+    getDataProducts: getDataProducts(join(path)),
+
+    /**
+     * Version a data product by its id
+     * @param id - The id of the data product to version
+     */
+    versionDataProduct: versionDataProduct(join(path)),
+
+    /**
+     * Remove a data product by its path
+     * @param path - The path to the data product to remove
+     */
+    rmDataProduct: rmDataProduct(join(path, 'data-products')),
+
+    /**
+     * Remove a data product by its id
+     * @param id - The id of the data product to remove
+     * @param version - Optional version of the data product to remove
+     */
+    rmDataProductById: rmDataProductById(join(path)),
+
+    /**
+     * Check to see if a data product version exists
+     * @param id - The id of the data product
+     * @param version - The version of the data product (supports semver)
+     * @returns
+     */
+    dataProductHasVersion: dataProductHasVersion(join(path)),
+
+    /**
+     * Adds a file to a data product by its id
+     * @param id - The id of the data product to add the file to
+     * @param file - File contents to add including the content and the file name
+     * @param version - Optional version of the data product to add the file to
+     * @returns
+     */
+    addFileToDataProduct: addFileToDataProduct(join(path)),
+
+    /**
+     * Adds a data product to a domain
+     * @param id - The id of the domain
+     * @param dataProduct - The id and version of the data product to add
+     * @param version - (Optional) The version of the domain to add the data product to
+     * @returns
+     */
+    addDataProductToDomain: addDataProductToDomain(join(path, 'domains')),
+
+    /**
+     * ================================
+     *            Diagrams
+     * ================================
+     */
+
+    /**
+     * Returns a diagram from EventCatalog
+     * @param id - The id of the diagram to retrieve
+     * @param version - Optional id of the version to get (supports semver)
+     * @returns Diagram|Undefined
+     */
+    getDiagram: getDiagram(join(path)),
+    /**
+     * Returns all diagrams from EventCatalog
+     * @param latestOnly - optional boolean, set to true to get only latest versions
+     * @returns Diagram[]|Undefined
+     */
+    getDiagrams: getDiagrams(join(path)),
+    /**
+     * Adds a diagram to EventCatalog
+     *
+     * @param diagram - The diagram to write
+     * @param options - Optional options to write the diagram
+     *
+     */
+    writeDiagram: writeDiagram(join(path, 'diagrams')),
+    /**
+     * Remove a diagram from EventCatalog (modeled on the standard POSIX rm utility)
+     *
+     * @param path - The path to your diagram, e.g. `/ArchitectureDiagram`
+     *
+     */
+    rmDiagram: rmDiagram(join(path, 'diagrams')),
+    /**
+     * Remove a diagram by a diagram id
+     *
+     * @param id - The id of the diagram you want to remove
+     *
+     */
+    rmDiagramById: rmDiagramById(join(path)),
+    /**
+     * Moves a given diagram id to the version directory
+     * @param id - The id of the diagram to version
+     */
+    versionDiagram: versionDiagram(join(path)),
+    /**
+     * Check to see if a diagram version exists
+     * @param id - The id of the diagram
+     * @param version - The version of the diagram (supports semver)
+     * @returns
+     */
+    diagramHasVersion: diagramHasVersion(join(path)),
+    /**
+     * Adds a file to the given diagram
+     * @param id - The id of the diagram to add the file to
+     * @param file - File contents to add including the content and the file name
+     * @param version - Optional version of the diagram to add the file to
+     * @returns
+     */
+    addFileToDiagram: addFileToDiagram(join(path)),
+
+    /**
+     * ================================
+     *            ADRs
+     * ================================
+     */
+    getAdr: getAdr(join(path)),
+    getAdrs: getAdrs(join(path)),
+    writeAdr: writeAdr(join(path, 'adrs')),
+    rmAdr: rmAdr(join(path, 'adrs')),
+    rmAdrById: rmAdrById(join(path)),
+    versionAdr: versionAdr(join(path)),
+    adrHasVersion: adrHasVersion(join(path)),
+    addFileToAdr: addFileToAdr(join(path)),
+
+    /**
+     * ================================
+     *            DSL
+     * ================================
+     */
+
+    /**
+     * Converts catalog resources to EventCatalog DSL (.ec) format strings.
+     *
+     * @param resource - A resource or array of resources to convert
+     * @param options - Options including type ('event'|'command'|'query'|'service'|'domain') and optional hydrate flag
+     * @returns A DSL string representation
+     *
+     * @example
+     * ```ts
+     * const dsl = await sdk.toDSL(event, { type: 'event' });
+     * const dsl = await sdk.toDSL(services, { type: 'service', hydrate: true });
+     * ```
+     */
+    createSnapshot: createSnapshot(join(path)),
+    diffSnapshots: diffSnapshots(join(path)),
+    listSnapshots: listSnapshots(join(path)),
+
+    toDSL: toDSL(join(path), {
+      getEvent: getEvent(join(path)),
+      getCommand: getCommand(join(path)),
+      getQuery: getQuery(join(path)),
+      getService: getService(join(path)),
+      getServices: getServices(join(path)),
+      getDomain: getDomain(join(path, 'domains')),
+      getChannel: getChannel(join(path)),
+      getChannels: getChannels(join(path)),
+      getContainer: getDataStore(join(path)),
+      getTeam: getTeam(join(path, 'teams')),
+      getUser: getUser(join(path, 'users')),
+    }),
+  };
+};
diff --git a/packages/sdk/src/internal/directory-store.ts b/packages/sdk/src/internal/directory-store.ts
new file mode 100644
index 000000000..58ed9abe8
--- /dev/null
+++ b/packages/sdk/src/internal/directory-store.ts
@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+type DirectoryStoreResource = {
+  id: string;
+  markdown?: string;
+  [key: string]: unknown;
+};
+
+type DirectoryStore = {
+  version: string;
+  generatedAt?: string;
+  resources?: {
+    users?: DirectoryStoreResource[];
+    teams?: DirectoryStoreResource[];
+  };
+};
+
+type DirectoryStoreCollection = 'users' | 'teams';
+
+const DIRECTORY_STORE_PATH = path.join('.eventcatalog', 'store', 'directory.json');
+
+const getCatalogRoot = (catalogDir: string, collection: DirectoryStoreCollection) => {
+  return path.basename(catalogDir) === collection ? path.dirname(catalogDir) : catalogDir;
+};
+
+export const getDirectoryStorePath = (catalogDir: string, collection: DirectoryStoreCollection) => {
+  return path.join(getCatalogRoot(catalogDir, collection), DIRECTORY_STORE_PATH);
+};
+
+type ResourceWithId = {
+  id: string;
+};
+
+export const readDirectoryStoreResources = <T extends ResourceWithId>(
+  catalogDir: string,
+  collection: DirectoryStoreCollection
+): T[] => {
+  const storePath = getDirectoryStorePath(catalogDir, collection);
+  if (!fs.existsSync(storePath)) return [];
+
+  try {
+    const store = JSON.parse(fs.readFileSync(storePath, 'utf8')) as DirectoryStore;
+    const resources = store.resources?.[collection];
+    return Array.isArray(resources) ? (resources as unknown as T[]) : [];
+  } catch {
+    return [];
+  }
+};
+
+export const readDirectoryStoreResource = <T extends ResourceWithId>(
+  catalogDir: string,
+  collection: DirectoryStoreCollection,
+  id: string
+): T | undefined => {
+  return readDirectoryStoreResources<T>(catalogDir, collection).find((resource) => resource.id === id);
+};
+
+export const mergeDirectoryStoreResources = <T extends ResourceWithId>(local: T[], directory: T[]) => {
+  const localIds = new Set(local.map((resource) => resource.id));
+  return [...local, ...directory.filter((resource) => !localIds.has(resource.id))];
+};
diff --git a/packages/sdk/src/internal/resources.ts b/packages/sdk/src/internal/resources.ts
new file mode 100644
index 000000000..5e8d8de04
--- /dev/null
+++ b/packages/sdk/src/internal/resources.ts
@@ -0,0 +1,411 @@
+import { dirname, join } from 'path';
+import {
+  copyDir,
+  findFileById,
+  getFiles,
+  searchFilesForId,
+  versionExists,
+  cachedMatterRead,
+  invalidateFileCache,
+  upsertFileCacheEntry,
+} from './utils';
+import matter from 'gray-matter';
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import { Adr, Message, Service, CustomDoc } from '../types';
+import { satisfies } from 'semver';
+import { lock, unlock } from 'proper-lockfile';
+import { basename } from 'node:path';
+import path from 'node:path';
+
+type Resource = Service | Message | CustomDoc | Adr;
+
+export const versionResource = async (catalogDir: string, id: string) => {
+  // Find all the events in the directory
+  const files = await getFiles(`${catalogDir}/**/index.{md,mdx}`);
+  const matchedFiles = await searchFilesForId(files, id);
+
+  if (matchedFiles.length === 0) {
+    throw new Error(`No resource found with id: ${id}`);
+  }
+
+  // Event that is in the route of the project
+  const file = matchedFiles[0];
+  // Handle both forward and back slashes for cross-platform compatibility (Windows uses \, Unix uses /)
+  const sourceDirectory = dirname(file).replace(/[/\\]versioned[/\\][^/\\]+[/\\]/, path.sep);
+  const { data: { version = '0.0.1' } = {} } = matter.read(file);
+  const targetDirectory = getVersionedDirectory(sourceDirectory, version);
+
+  fsSync.mkdirSync(targetDirectory, { recursive: true });
+
+  const ignoreListToCopy = ['events', 'commands', 'queries', 'versioned'];
+
+  // Copy the event to the versioned directory
+  await copyDir(catalogDir, sourceDirectory, targetDirectory, (src) => {
+    // get the folder name
+    const folderName = basename(src);
+
+    if (ignoreListToCopy.includes(folderName)) {
+      return false;
+    }
+    return true;
+  });
+
+  // Remove all the files in the root of the resource as they have now been versioned
+  await fs.readdir(sourceDirectory).then(async (resourceFiles) => {
+    await Promise.all(
+      resourceFiles.map(async (file) => {
+        // Dont remove anything in the ignore list
+        if (ignoreListToCopy.includes(file)) {
+          return;
+        }
+        if (file !== 'versioned') {
+          fsSync.rmSync(join(sourceDirectory, file), { recursive: true });
+        }
+      })
+    );
+  });
+
+  invalidateFileCache();
+};
+
+export const writeResource = async (
+  catalogDir: string,
+  resource: Resource,
+  options: { path?: string; type: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+    path: '',
+    type: '',
+    override: false,
+    versionExistingContent: false,
+    format: 'mdx',
+  }
+) => {
+  const path = options.path || `/${resource.id}`;
+  const fullPath = join(catalogDir, path);
+  const format = options.format || 'mdx';
+
+  // Create directory if it doesn't exist
+  fsSync.mkdirSync(fullPath, { recursive: true });
+
+  // Create or get lock file path
+  const lockPath = join(fullPath, `index.${format}`);
+
+  // Ensure the file exists before attempting to lock it
+  if (!fsSync.existsSync(lockPath)) {
+    fsSync.writeFileSync(lockPath, '');
+  }
+
+  try {
+    // Acquire lock with retry
+    await lock(lockPath, {
+      retries: 5,
+      stale: 10000, // 10 seconds
+    });
+
+    const exists = await versionExists(catalogDir, resource.id, resource.version);
+
+    if (exists && !options.override) {
+      throw new Error(`Failed to write ${resource.id} (${options.type}) as the version ${resource.version} already exists`);
+    }
+
+    const { markdown, ...frontmatter } = resource;
+
+    if (options.versionExistingContent && !exists) {
+      const currentResource = await getResource(catalogDir, resource.id);
+
+      if (currentResource) {
+        if (satisfies(resource.version, `>${currentResource.version}`)) {
+          await versionResource(catalogDir, resource.id);
+        } else {
+          throw new Error(`New version ${resource.version} is not greater than current version ${currentResource.version}`);
+        }
+      }
+    }
+
+    const document = matter.stringify(markdown.trim(), frontmatter);
+    fsSync.writeFileSync(lockPath, document);
+    upsertFileCacheEntry(catalogDir, lockPath, document);
+  } finally {
+    // Always release the lock
+    await unlock(lockPath).catch(() => {});
+  }
+};
+
+export const getResource = async (
+  catalogDir: string,
+  id?: string,
+  version?: string,
+  options?: { type: string; attachSchema?: boolean },
+  filePath?: string
+): Promise<Resource | undefined> => {
+  const attachSchema = options?.attachSchema || false;
+  const file = filePath || (id ? await findFileById(catalogDir, id, version) : undefined);
+  if (!file || !fsSync.existsSync(file)) return;
+
+  const { data, content } = cachedMatterRead(file);
+
+  if (attachSchema && data?.schemaPath) {
+    const resourceDirectory = dirname(file);
+    const pathToSchema = join(resourceDirectory, data.schemaPath);
+    if (fsSync.existsSync(pathToSchema)) {
+      const schema = fsSync.readFileSync(pathToSchema, 'utf8');
+      // Try to parse the schema
+      try {
+        data.schema = JSON.parse(schema);
+      } catch (error) {
+        data.schema = schema;
+      }
+    }
+  }
+
+  return {
+    ...data,
+    markdown: content.trim(),
+  } as Resource;
+};
+
+export const getResourcePath = async (catalogDir: string, id: string, version?: string) => {
+  const file = await findFileById(catalogDir, id, version);
+  if (!file) return;
+
+  return {
+    fullPath: file,
+    relativePath: file.replace(catalogDir, ''),
+    directory: dirname(file.replace(catalogDir, '')),
+  };
+};
+
+export const getResourceFolderName = async (catalogDir: string, id: string, version?: string) => {
+  const paths = await getResourcePath(catalogDir, id, version);
+  if (!paths) return;
+  return paths?.directory.split(path.sep).filter(Boolean).pop();
+};
+
+export const toResource = async (catalogDir: string, rawContents: string) => {
+  const { data, content } = matter(rawContents);
+  return {
+    ...data,
+    markdown: content.trim(),
+  } as Resource;
+};
+
+export const getResources = async (
+  catalogDir: string,
+  {
+    type,
+    latestOnly = false,
+    ignore = [],
+    pattern = '',
+    attachSchema = false,
+  }: { type: string; pattern?: string; latestOnly?: boolean; ignore?: string[]; attachSchema?: boolean }
+): Promise<Resource[] | undefined> => {
+  const ignoreList = latestOnly ? `**/versioned/**` : '';
+  const filePattern = pattern || `${catalogDir}/**/${type}/**/index.{md,mdx}`;
+  const files = await getFiles(filePattern, [ignoreList, ...ignore]);
+
+  if (files.length === 0) return;
+
+  return files.map((file) => {
+    const { data, content } = cachedMatterRead(file);
+
+    // Attach the schema if the attachSchema option is set to true
+    if (attachSchema && data?.schemaPath) {
+      const resourceDirectory = dirname(file);
+      const pathToSchema = join(resourceDirectory, data.schemaPath);
+      if (fsSync.existsSync(pathToSchema)) {
+        const schema = fsSync.readFileSync(pathToSchema, 'utf8');
+        // Try to parse the schema
+        try {
+          data.schema = JSON.parse(schema);
+        } catch (error) {
+          data.schema = schema;
+        }
+      }
+    }
+    return {
+      ...data,
+      markdown: content.trim(),
+    } as Resource;
+  });
+};
+
+export const rmResourceById = async (
+  catalogDir: string,
+  id: string,
+  version?: string,
+  options?: { type: string; persistFiles?: boolean }
+) => {
+  const files = await getFiles(`${catalogDir}/**/index.{md,mdx}`);
+
+  const matchedFiles = await searchFilesForId(files, id, version);
+
+  if (matchedFiles.length === 0) {
+    throw new Error(`No ${options?.type || 'resource'} found with id: ${id}`);
+  }
+
+  if (options?.persistFiles) {
+    await Promise.all(
+      matchedFiles.map(async (file) => {
+        await fs.rm(file, { recursive: true });
+        // Verify file is actually removed
+        await waitForFileRemoval(file);
+      })
+    );
+  } else {
+    await Promise.all(
+      matchedFiles.map(async (file) => {
+        const directory = dirname(file);
+        await fs.rm(directory, { recursive: true, force: true });
+        // Verify directory is actually removed
+        await waitForFileRemoval(directory);
+      })
+    );
+  }
+
+  invalidateFileCache();
+};
+
+// Helper function to ensure file/directory is completely removed
+const waitForFileRemoval = async (path: string, maxRetries: number = 50, delay: number = 10): Promise<void> => {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      await fs.access(path);
+      // If access succeeds, file still exists, wait and retry
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    } catch (error) {
+      // If access fails, file is removed
+      return;
+    }
+  }
+  // If we reach here, file still exists after all retries
+  throw new Error(`File/directory ${path} was not removed after ${maxRetries} attempts`);
+};
+
+export const addFileToResource = async (
+  catalogDir: string,
+  id: string,
+  file: { content: string; fileName: string },
+  version?: string,
+  options?: { path?: string }
+) => {
+  let pathToResource: string | undefined;
+
+  if (options?.path) {
+    pathToResource = join(catalogDir, options.path, 'index.mdx');
+  } else {
+    // Fall back to global lookup (existing behavior)
+    pathToResource = await findFileById(catalogDir, id, version);
+  }
+
+  if (!pathToResource) throw new Error('Cannot find directory to write file to');
+
+  // Create the directory if it doesn't exist
+  fsSync.mkdirSync(path.dirname(pathToResource), { recursive: true });
+
+  let fileContent = file.content.trim();
+
+  try {
+    const json = JSON.parse(fileContent);
+    fileContent = JSON.stringify(json, null, 2);
+  } catch (error) {
+    // Just silently fail if the file is not valid JSON
+    // Write it as it is
+  }
+
+  fsSync.writeFileSync(join(dirname(pathToResource), file.fileName), fileContent);
+};
+
+export const getFileFromResource = async (catalogDir: string, id: string, file: { fileName: string }, version?: string) => {
+  const pathToResource = await findFileById(catalogDir, id, version);
+
+  if (!pathToResource) throw new Error('Cannot find directory of resource');
+
+  const exists = await fs
+    .access(join(dirname(pathToResource), file.fileName))
+    .then(() => true)
+    .catch(() => false);
+  if (!exists) throw new Error(`File ${file.fileName} does not exist in resource ${id} v(${version})`);
+
+  return fsSync.readFileSync(join(dirname(pathToResource), file.fileName), 'utf-8');
+};
+export const getVersionedDirectory = (sourceDirectory: string, version: any): string => {
+  return join(sourceDirectory, 'versioned', version);
+};
+
+const CONFIG_FILES = ['examples.config.yaml', 'examples.config.yml', 'examples.config.json'];
+
+function resolveExamplePath(examplesDir: string, fileName: string): string {
+  const resolved = path.resolve(examplesDir, fileName);
+  if (!resolved.startsWith(path.resolve(examplesDir) + path.sep) && resolved !== path.resolve(examplesDir)) {
+    throw new Error(`Invalid example fileName: path traversal detected in "${fileName}"`);
+  }
+  return resolved;
+}
+
+export const addExampleToResource = async (
+  catalogDir: string,
+  id: string,
+  example: { content: string; fileName: string },
+  version?: string
+) => {
+  const pathToResource = await findFileById(catalogDir, id, version);
+  if (!pathToResource) throw new Error('Cannot find directory to write example to');
+
+  const examplesDir = join(dirname(pathToResource), 'examples');
+  const targetPath = resolveExamplePath(examplesDir, example.fileName);
+  fsSync.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fsSync.writeFileSync(targetPath, example.content);
+};
+
+export const getExamplesFromResource = async (
+  catalogDir: string,
+  id: string,
+  version?: string
+): Promise<{ fileName: string; content: string }[]> => {
+  const pathToResource = await findFileById(catalogDir, id, version);
+  if (!pathToResource) throw new Error('Cannot find resource');
+
+  const examplesDir = join(dirname(pathToResource), 'examples');
+  if (!fsSync.existsSync(examplesDir)) return [];
+
+  const collectFiles = (dir: string, baseDir: string): { fileName: string; content: string }[] => {
+    const results: { fileName: string; content: string }[] = [];
+    const entries = fsSync.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...collectFiles(fullPath, baseDir));
+      } else if (entry.isFile() && !CONFIG_FILES.includes(entry.name)) {
+        results.push({
+          fileName: path.relative(baseDir, fullPath),
+          content: fsSync.readFileSync(fullPath, 'utf-8'),
+        });
+      }
+    }
+    return results;
+  };
+
+  return collectFiles(examplesDir, examplesDir).sort((a, b) => a.fileName.localeCompare(b.fileName));
+};
+
+export const removeExampleFromResource = async (catalogDir: string, id: string, fileName: string, version?: string) => {
+  const pathToResource = await findFileById(catalogDir, id, version);
+  if (!pathToResource) throw new Error('Cannot find resource');
+
+  const examplesDir = join(dirname(pathToResource), 'examples');
+  const examplePath = resolveExamplePath(examplesDir, fileName);
+  if (!fsSync.existsSync(examplePath)) {
+    throw new Error(`Example file ${fileName} does not exist in resource ${id}${version ? ` v(${version})` : ''}`);
+  }
+
+  fsSync.unlinkSync(examplePath);
+};
+
+export const isLatestVersion = async (catalogDir: string, id: string, version?: string) => {
+  const resource = await getResource(catalogDir, id, version);
+  if (!resource) return false;
+
+  const pathToResource = await getResourcePath(catalogDir, id, version);
+
+  return !pathToResource?.relativePath.replace(/\\/g, '/').includes('/versioned/');
+};
diff --git a/packages/sdk/src/internal/utils.ts b/packages/sdk/src/internal/utils.ts
new file mode 100644
index 000000000..1479bdbd2
--- /dev/null
+++ b/packages/sdk/src/internal/utils.ts
@@ -0,0 +1,333 @@
+import { globSync } from 'glob';
+import fsSync from 'node:fs';
+import { copy, CopyFilterAsync, CopyFilterSync } from 'fs-extra';
+import { join, dirname, normalize, sep as pathSeparator, resolve, basename, relative } from 'node:path';
+import matter from 'gray-matter';
+import { satisfies, validRange, valid } from 'semver';
+
+// In-memory file index cache. Auto-built on first read, invalidated on writes.
+interface FileIndexEntry {
+  path: string;
+  id: string;
+  version: string;
+  isVersioned: boolean;
+}
+
+let _fileIndexCache: Map<string, FileIndexEntry[]> | null = null;
+let _fileIndexCatalogDir: string | null = null;
+let _matterCache: Map<string, matter.GrayMatterFile<string>> | null = null;
+let _filePathToIdCache: Map<string, string> | null = null;
+let _fileIndexMtimeMs: number = 0;
+
+function toCanonicalPath(inputPath: string): string {
+  return normalize(resolve(inputPath));
+}
+
+function buildFileCache(catalogDir: string): void {
+  const canonicalCatalogDir = toCanonicalPath(catalogDir);
+  const files = globSync('**/index.{md,mdx}', {
+    cwd: canonicalCatalogDir,
+    ignore: ['node_modules/**'],
+    absolute: true,
+    nodir: true,
+  }).map(normalize);
+
+  const index = new Map<string, FileIndexEntry[]>();
+  const matterResults = new Map<string, matter.GrayMatterFile<string>>();
+  const pathToId = new Map<string, string>();
+
+  for (const file of files) {
+    const content = fsSync.readFileSync(file, 'utf-8');
+    const parsed = matter(content);
+    matterResults.set(file, parsed);
+
+    const id = parsed.data.id;
+    if (!id) continue;
+
+    const resourceId = String(id);
+    const version = parsed.data.version || '';
+    const isVersioned = file.includes('versioned');
+    const entry: FileIndexEntry = { path: file, id: resourceId, version: String(version), isVersioned };
+    pathToId.set(file, resourceId);
+
+    const existing = index.get(resourceId);
+    if (existing) {
+      existing.push(entry);
+    } else {
+      index.set(resourceId, [entry]);
+    }
+  }
+
+  _fileIndexCache = index;
+  _fileIndexCatalogDir = canonicalCatalogDir;
+  _matterCache = matterResults;
+  _filePathToIdCache = pathToId;
+  try {
+    _fileIndexMtimeMs = fsSync.statSync(canonicalCatalogDir).mtimeMs;
+  } catch {
+    _fileIndexMtimeMs = 0;
+  }
+}
+
+function ensureFileCache(catalogDir: string): void {
+  const canonicalCatalogDir = toCanonicalPath(catalogDir);
+  if (!_fileIndexCache || _fileIndexCatalogDir !== canonicalCatalogDir) {
+    buildFileCache(catalogDir);
+    return;
+  }
+  // Check if catalog dir was recreated (e.g. tests wiping and recreating)
+  try {
+    const currentMtime = fsSync.statSync(canonicalCatalogDir).mtimeMs;
+    if (currentMtime !== _fileIndexMtimeMs) {
+      buildFileCache(catalogDir);
+    }
+  } catch {
+    buildFileCache(catalogDir);
+  }
+}
+
+/** Invalidate the file cache. Call after any write/rm/version operation. */
+export function invalidateFileCache(): void {
+  _fileIndexCache = null;
+  _fileIndexCatalogDir = null;
+  _matterCache = null;
+  _filePathToIdCache = null;
+}
+
+/**
+ * Incrementally updates the in-memory file index for a single file write.
+ * No-ops when cache is disabled or points at a different catalog.
+ */
+export function upsertFileCacheEntry(catalogDir: string, filePath: string, rawContent: string): void {
+  const canonicalCatalogDir = toCanonicalPath(catalogDir);
+  if (!_fileIndexCache || !_matterCache || !_filePathToIdCache || _fileIndexCatalogDir !== canonicalCatalogDir) {
+    return;
+  }
+
+  const normalizedPath = toCanonicalPath(filePath);
+  const parsed = matter(rawContent);
+
+  // Remove stale entry for this file path (if it existed under another id/version).
+  const previousId = _filePathToIdCache.get(normalizedPath);
+  if (previousId) {
+    const previousEntries = _fileIndexCache.get(previousId) || [];
+    const nextEntries = previousEntries.filter((entry) => entry.path !== normalizedPath);
+    if (nextEntries.length === 0) {
+      _fileIndexCache.delete(previousId);
+    } else {
+      _fileIndexCache.set(previousId, nextEntries);
+    }
+    _filePathToIdCache.delete(normalizedPath);
+  }
+
+  _matterCache.set(normalizedPath, parsed);
+
+  const id = parsed.data.id;
+  if (!id) {
+    _filePathToIdCache.delete(normalizedPath);
+    return;
+  }
+
+  const resourceId = String(id);
+  const entry: FileIndexEntry = {
+    path: normalizedPath,
+    id: resourceId,
+    version: String(parsed.data.version || ''),
+    isVersioned: normalizedPath.includes(`${pathSeparator}versioned${pathSeparator}`),
+  };
+
+  const entries = _fileIndexCache.get(resourceId) || [];
+  entries.push(entry);
+  _fileIndexCache.set(resourceId, entries);
+  _filePathToIdCache.set(normalizedPath, resourceId);
+
+  try {
+    _fileIndexMtimeMs = fsSync.statSync(canonicalCatalogDir).mtimeMs;
+  } catch {
+    // Ignore mtime refresh failures; cache will self-heal on next ensureFileCache call.
+  }
+}
+
+// Keep these as aliases for backwards compat with CLI export code
+export const enableFileCache = buildFileCache;
+export const disableFileCache = invalidateFileCache;
+
+/**
+ * Returns cached matter.read result if available, otherwise reads from disk.
+ */
+export function cachedMatterRead(filePath: string): matter.GrayMatterFile<string> {
+  if (_matterCache) {
+    const cached = _matterCache.get(filePath);
+    if (cached) return cached;
+  }
+  return matter.read(filePath);
+}
+
+/**
+ * Returns true if a given version of a resource id exists in the catalog
+ */
+export const versionExists = async (catalogDir: string, id: string, version: string) => {
+  ensureFileCache(catalogDir);
+  const entries = _fileIndexCache!.get(id);
+  if (!entries) return false;
+  return entries.some((e) => e.version === version);
+};
+
+export const findFileById = async (catalogDir: string, id: string, version?: string): Promise<string | undefined> => {
+  ensureFileCache(catalogDir);
+
+  const entries = _fileIndexCache!.get(id);
+  if (!entries || entries.length === 0) return undefined;
+
+  const latestEntry = entries.find((e) => !e.isVersioned);
+
+  if (!version || version === 'latest') {
+    return latestEntry?.path;
+  }
+
+  // Exact version match
+  const exactMatch = entries.find((e) => e.version === version);
+  if (exactMatch) return exactMatch.path;
+
+  // Semver range match
+  const semverRange = validRange(version);
+  if (semverRange) {
+    const match = entries.find((e) => {
+      try {
+        return satisfies(e.version, semverRange);
+      } catch {
+        return false;
+      }
+    });
+    return match?.path;
+  }
+
+  return undefined;
+};
+
+export const getFiles = async (pattern: string, ignore: string | string[] = '') => {
+  try {
+    // 1. Normalize the input pattern to handle mixed separators potentially
+    const normalizedInputPattern = normalize(pattern);
+
+    // 2. Determine the absolute base directory (cwd for glob)
+    // Resolve ensures it's absolute. Handles cases with/without globstar.
+    const absoluteBaseDir = resolve(
+      normalizedInputPattern.includes('**') ? normalizedInputPattern.split('**')[0] : dirname(normalizedInputPattern)
+    );
+
+    // 3. Determine the pattern part relative to the absolute base directory
+    // We extract the part of the normalized pattern that comes *after* the absoluteBaseDir
+    let relativePattern = relative(absoluteBaseDir, normalizedInputPattern);
+
+    // On Windows, relative() might return empty string if paths are identical,
+    // or might need normalization if the original pattern didn't have `**`
+    // Example: pattern = 'dir/file.md', absoluteBaseDir='.../dir', normalized='...\dir\file.md'
+    // relative() -> 'file.md'
+    // Example: pattern = 'dir/**/file.md', absoluteBaseDir='.../dir', normalized='...\dir\**\file.md'
+    // relative() -> '**\file.md'
+    // Convert separators in the relative pattern to forward slashes for glob
+    relativePattern = relativePattern.replace(/\\/g, '/');
+
+    const ignoreList = Array.isArray(ignore) ? ignore : [ignore];
+
+    const files = globSync(relativePattern, {
+      cwd: absoluteBaseDir,
+      ignore: ['node_modules/**', ...ignoreList],
+      absolute: true,
+      nodir: true,
+    });
+
+    // 5. Normalize results for consistency before returning
+    return files.map(normalize);
+  } catch (error: any) {
+    // Add more diagnostic info to the error
+    const absoluteBaseDirForError = resolve(
+      normalize(pattern).includes('**') ? normalize(pattern).split('**')[0] : dirname(normalize(pattern))
+    );
+    const relativePatternForError = relative(absoluteBaseDirForError, normalize(pattern)).replace(/\\/g, '/');
+    throw new Error(
+      `Error finding files for pattern "${pattern}" (using cwd: "${absoluteBaseDirForError}", globPattern: "${relativePatternForError}"): ${error.message}`
+    );
+  }
+};
+
+export const readMdxFile = async (path: string) => {
+  const { data } = matter.read(path);
+  const { markdown, ...frontmatter } = data;
+  return { ...frontmatter, markdown };
+};
+
+export const searchFilesForId = async (files: string[], id: string, version?: string) => {
+  // Escape the id to avoid regex issues
+  const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const idRegex = new RegExp(`^id:\\s*(['"]|>-)?\\s*${escapedId}['"]?\\s*$`, 'm');
+
+  const versionRegex = new RegExp(`^version:\\s*['"]?${version}['"]?\\s*$`, 'm');
+
+  const matches = files.map((file) => {
+    const content = fsSync.readFileSync(file, 'utf-8');
+    const hasIdMatch = content.match(idRegex);
+
+    // Check version if provided
+    if (version && !content.match(versionRegex)) {
+      return undefined;
+    }
+
+    if (hasIdMatch) {
+      return file;
+    }
+  });
+
+  return matches.filter(Boolean).filter((file) => file !== undefined);
+};
+
+/**
+ * Function to copy a directory from source to target, uses a tmp directory
+ * @param catalogDir
+ * @param source
+ * @param target
+ * @param filter
+ */
+export const copyDir = async (catalogDir: string, source: string, target: string, filter?: CopyFilterAsync | CopyFilterSync) => {
+  const tmpDirectory = join(catalogDir, 'tmp');
+  fsSync.mkdirSync(tmpDirectory, { recursive: true });
+
+  // Copy everything over
+  await copy(source, tmpDirectory, {
+    overwrite: true,
+    filter,
+  });
+
+  await copy(tmpDirectory, target, {
+    overwrite: true,
+    filter,
+  });
+
+  // Remove the tmp directory
+  fsSync.rmSync(tmpDirectory, { recursive: true });
+};
+
+// Makes sure values in sends/recieves are unique
+export const buildMessagePointer = (message: { id: string; version: string; fields?: string[]; group?: string }) => {
+  const pointer: { id: string; version: string; fields?: string[]; group?: string } = {
+    id: message.id,
+    version: message.version,
+  };
+  if (message.fields) pointer.fields = message.fields;
+  if (message.group) pointer.group = message.group;
+  return pointer;
+};
+
+export const uniqueVersions = (messages: { id: string; version: string }[]): { id: string; version: string }[] => {
+  const uniqueSet = new Set();
+
+  return messages.filter((message) => {
+    const key = `${message.id}-${message.version}`;
+    if (!uniqueSet.has(key)) {
+      uniqueSet.add(key);
+      return true;
+    }
+    return false;
+  });
+};
diff --git a/packages/sdk/src/messages.ts b/packages/sdk/src/messages.ts
new file mode 100644
index 000000000..98a72748e
--- /dev/null
+++ b/packages/sdk/src/messages.ts
@@ -0,0 +1,220 @@
+import { dirname, join } from 'node:path';
+import fsSync from 'node:fs';
+import type { Agent, Message, Service } from './types';
+import matter from 'gray-matter';
+import { getResource, getResourcePath, isLatestVersion } from './internal/resources';
+import { findFileById, getFiles } from './internal/utils';
+import { getServices } from './services';
+import { getAgents } from './agents';
+import { satisfies, validRange } from 'semver';
+
+type MessageParticipant = Service | Agent;
+
+/**
+ * Returns a message from EventCatalog by a given schema path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getMessageBySchemaPath } = utils('/path/to/eventcatalog');
+ *
+ * // Get the message by the schema path
+ * const message = await getMessageBySchemaPath('/path/to/eventcatalog/messages/InventoryAdjusted/schema.json');
+ * const message = await getMessageBySchemaPath('/path/to/eventcatalog/messages/InventoryAdjusted/schema.avro');
+ * ```
+ */
+export const getMessageBySchemaPath =
+  (directory: string) =>
+  async (path: string, options?: { attachSchema?: boolean }): Promise<Message> => {
+    const pathToMessage = dirname(path);
+    try {
+      const files = await getFiles(`${directory}/${pathToMessage}/index.{md,mdx}`);
+
+      if (!files || files.length === 0) {
+        throw new Error(`No message definition file (index.md or index.mdx) found in directory: ${pathToMessage}`);
+      }
+      const messageFile = files[0];
+
+      const { data } = matter.read(messageFile);
+      const { id, version } = data;
+
+      if (!id || !version) {
+        throw new Error(`Message definition file at ${messageFile} is missing 'id' or 'version' in its frontmatter.`);
+      }
+
+      const message = await getResource(directory, id, version, { type: 'message', ...options });
+
+      if (!message) {
+        throw new Error(`Message resource with id '${id}' and version '${version}' not found, as referenced in ${messageFile}.`);
+      }
+      return message as Message;
+    } catch (error) {
+      // console.error(`Failed to get message for schema path ${path}. Error processing directory ${pathToMessage}:`, error);
+      if (error instanceof Error) {
+        // Prepend more context to the existing error message
+        error.message = `Failed to retrieve message from ${pathToMessage}: ${error.message}`;
+        throw error;
+      }
+      throw new Error(`Failed to retrieve message from ${pathToMessage} due to an unknown error.`);
+    }
+  };
+
+/**
+ * Returns the producers and consumers (services and agents) for a given message.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getProducersAndConsumersForMessage } = utils('/path/to/eventcatalog');
+ *
+ * // Returns the producers and consumers (services and agents) for a given message
+ * const { producers, consumers } = await getProducersAndConsumersForMessage('InventoryAdjusted', '0.0.1');
+ */
+export const getProducersAndConsumersForMessage =
+  (directory: string) =>
+  async (
+    id: string,
+    version?: string,
+    options?: { latestOnly?: boolean }
+  ): Promise<{ producers: MessageParticipant[]; consumers: MessageParticipant[] }> => {
+    const [services = [], agents = []] = await Promise.all([
+      getServices(directory)({ latestOnly: options?.latestOnly ?? true }),
+      getAgents(directory)({ latestOnly: options?.latestOnly ?? true }),
+    ]);
+    const message = (await getResource(directory, id, version, { type: 'message' })) as Message;
+    const isMessageLatestVersion = await isLatestVersion(directory, id, version);
+
+    if (!message) {
+      throw new Error(`Message resource with id '${id}' and version '${version}' not found.`);
+    }
+
+    const producers: MessageParticipant[] = [];
+    const consumers: MessageParticipant[] = [];
+
+    for (const participant of [...services, ...agents]) {
+      const participantPublishesMessage = participant.sends?.some((_message) => {
+        if (_message.version) {
+          const isParticipantUsingSemverRange = validRange(_message.version);
+          if (isParticipantUsingSemverRange) {
+            return _message.id === message.id && satisfies(message.version, _message.version);
+          } else {
+            return _message.id === message.id && message.version === _message.version;
+          }
+        }
+        if (isMessageLatestVersion && _message.id === message.id) {
+          return true;
+        }
+        return false;
+      });
+      const participantSubscribesToMessage = participant.receives?.some((_message) => {
+        if (_message.version) {
+          const isParticipantUsingSemverRange = validRange(_message.version);
+          if (isParticipantUsingSemverRange) {
+            return _message.id === message.id && satisfies(message.version, _message.version);
+          } else {
+            return _message.id === message.id && message.version === _message.version;
+          }
+        }
+        if (isMessageLatestVersion && _message.id === message.id) {
+          return true;
+        }
+        return false;
+      });
+
+      if (participantPublishesMessage) {
+        producers.push(participant);
+      }
+      if (participantSubscribesToMessage) {
+        consumers.push(participant);
+      }
+    }
+
+    return { producers, consumers };
+  };
+
+/**
+ * Returns the consumers of a given schema path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getConsumersOfSchema } = utils('/path/to/eventcatalog');
+ *
+ * // Returns the consumers of a given schema path
+ * const consumers = await getConsumersOfSchema('events/InventoryAdjusted/schema.json');
+ */
+export const getConsumersOfSchema = (directory: string) => async (path: string) => {
+  try {
+    const message = await getMessageBySchemaPath(directory)(path);
+    const { consumers } = await getProducersAndConsumersForMessage(directory)(message.id, message.version);
+    return consumers;
+  } catch (error) {
+    return [];
+  }
+};
+
+/**
+ * Returns the producers of a given schema path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getProducersOfSchema } = utils('/path/to/eventcatalog');
+ *
+ * // Returns the producers of a given schema path
+ * const producers = await getProducersOfSchema('events/InventoryAdjusted/schema.json');
+ */
+export const getProducersOfSchema = (directory: string) => async (path: string) => {
+  try {
+    const message = await getMessageBySchemaPath(directory)(path);
+    const { producers } = await getProducersAndConsumersForMessage(directory)(message.id, message.version);
+    return producers;
+  } catch (error) {
+    return [];
+  }
+};
+
+/**
+ * Returns the schema for a given message (event, command or query) by its id and version.
+ *
+ * If no version is given, the latest version is used.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getSchemaForMessage } = utils('/path/to/eventcatalog');
+ *
+ * // Get the schema for the latest version of the message
+ * const schema = await getSchemaForMessage('InventoryAdjusted');
+ *
+ * // Get the schema for a specific version
+ * const schema = await getSchemaForMessage('InventoryAdjusted', '0.0.1');
+ * ```
+ */
+export const getSchemaForMessage =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<{ schema: string; fileName: string } | undefined> => {
+    const file = await findFileById(directory, id, version);
+    if (!file || !fsSync.existsSync(file)) return undefined;
+
+    const { data } = matter.read(file);
+
+    if (!data.schemaPath) return undefined;
+
+    const resourceDirectory = dirname(file);
+    const pathToSchema = join(resourceDirectory, data.schemaPath);
+
+    if (!fsSync.existsSync(pathToSchema)) return undefined;
+
+    const schema = fsSync.readFileSync(pathToSchema, 'utf8');
+
+    return {
+      schema,
+      fileName: data.schemaPath,
+    };
+  };
diff --git a/packages/sdk/src/queries.ts b/packages/sdk/src/queries.ts
new file mode 100644
index 000000000..bad3a3ef9
--- /dev/null
+++ b/packages/sdk/src/queries.ts
@@ -0,0 +1,392 @@
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { findFileById, invalidateFileCache } from './internal/utils';
+import type { Query } from './types';
+import {
+  addFileToResource,
+  addExampleToResource,
+  getExamplesFromResource,
+  removeExampleFromResource,
+  getResource,
+  getResourcePath,
+  getResources,
+  rmResourceById,
+  versionResource,
+  writeResource,
+} from './internal/resources';
+
+/**
+ * Returns a query from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the query
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getQuery } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the event
+ * const event = await getQuery('GetOrder');
+ *
+ * // Gets a version of the event
+ * const event = await getQuery('GetOrder', '0.0.1');
+ *
+ * // Gets the query with the schema attached
+ * const event = await getQuery('GetOrder', '0.0.1', { attachSchema: true });
+ * ```
+ */
+export const getQuery =
+  (directory: string) =>
+  async (id: string, version?: string, options?: { attachSchema?: boolean }): Promise<Query> =>
+    getResource(directory, id, version, { type: 'query', ...options }) as Promise<Query>;
+
+/**
+ * Write a query to EventCatalog.
+ *
+ * You can optionally override the path of the query.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeQuery } = utils('/path/to/eventcatalog');
+ *
+ * // Write an event to the catalog
+ * // Event would be written to queries/GetOrder
+ * await writeQuery({
+ *   id: 'GetOrder',
+ *   name: 'Get Order',
+ *   version: '0.0.1',
+ *   summary: 'This is a summary',
+ *   markdown: '# Hello world',
+ * });
+ *
+ * // Write an event to the catalog but override the path
+ * // Event would be written to queries/Inventory/GetOrder
+ * await writeQuery({
+ *    id: 'GetOrder',
+ *    name: 'Get Order',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { path: "/Orders/GetOrder"});
+ *
+ * // Write a query to the catalog and override the existing content (if there is any)
+ * await writeQuery({
+ *    id: 'GetOrder',
+ *    name: 'Get Order',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { override: true });
+ *
+ * // Write a query to the catalog and version the previous version
+ * // only works if the new version is greater than the previous version
+ * await writeQuery({
+ *    id: 'GetOrder',
+ *    name: 'Get Order',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { versionExistingContent: true });
+ *
+ * ```
+ */
+export const writeQuery =
+  (directory: string) =>
+  async (
+    query: Query,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      versionExistingContent: false,
+      format: 'mdx',
+    }
+  ) =>
+    writeResource(directory, { ...query }, { ...options, type: 'query' });
+
+/**
+ * Returns all queries from EventCatalog.
+ *
+ * You can optionally specify if you want to get the latest version of the queries.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getQueries } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all queries (and versions) from the catalog
+ * const queries = await getQueries();
+ *
+ * // Gets all queries (only latest version) from the catalog
+ * const queries = await getQueries({ latestOnly: true });
+ *
+ * // Gets all queries with the schema attached
+ * const queries = await getQueries({ attachSchema: true });
+ * ```
+ */
+export const getQueries =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean; attachSchema?: boolean }): Promise<Query[]> =>
+    getResources(directory, { type: 'queries', ...options }) as Promise<Query[]>;
+
+/**
+ * Write a query to a service in EventCatalog.
+ *
+ * You can optionally override the path of the event.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeQueryToService } = utils('/path/to/eventcatalog');
+ *
+ * // Write an event to a given service in the catalog
+ * // Event would be written to services/Orders/queries/GetOrder
+ * await writeQueryToService({
+ *   id: 'GetOrder',
+ *   name: 'Get Order',
+ *   version: '0.0.1',
+ *   summary: 'This is a summary',
+ *   markdown: '# Hello world',
+ * }, { id: 'Orders' });
+ * ```
+ */
+export const writeQueryToService =
+  (directory: string) =>
+  async (
+    query: Query,
+    service: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    const resourcePath = await getResourcePath(directory, service.id, service.version);
+    if (!resourcePath) {
+      throw new Error('Service not found');
+    }
+    let pathForQuery =
+      service.version && service.version !== 'latest'
+        ? `${resourcePath.directory}/versioned/${service.version}/queries`
+        : `${resourcePath.directory}/queries`;
+    pathForQuery = join(pathForQuery, query.id);
+    await writeResource(directory, { ...query }, { ...options, path: pathForQuery, type: 'query' });
+  };
+
+/**
+ * Write a query to an agent in EventCatalog.
+ */
+export const writeQueryToAgent =
+  (directory: string) =>
+  async (
+    query: Query,
+    agent: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    const resourcePath = await getResourcePath(directory, agent.id, agent.version);
+    if (!resourcePath) {
+      throw new Error('Agent not found');
+    }
+
+    let pathForQuery =
+      agent.version && agent.version !== 'latest'
+        ? `${resourcePath.directory}/versioned/${agent.version}/queries`
+        : `${resourcePath.directory}/queries`;
+    pathForQuery = join(pathForQuery, query.id);
+    await writeResource(directory, { ...query }, { ...options, path: pathForQuery, type: 'query' });
+  };
+
+/**
+ * Delete a query at it's given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmQuery } = utils('/path/to/eventcatalog');
+ *
+ * // removes an query at the given path (queries dir is appended to the given path)
+ * // Removes the query at queries/GetOrders
+ * await rmQuery('/GetOrders');
+ * ```
+ */
+export const rmQuery = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+/**
+ * Delete a query by it's id.
+ *
+ * Optionally specify a version to delete a specific version of the query.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmQueryById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest InventoryAdjusted query
+ * await rmQueryById('GetOrder');
+ *
+ * // deletes a specific version of the GetOrder query
+ * await rmQueryById('GetOrder', '0.0.1');
+ * ```
+ */
+export const rmQueryById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) => {
+  await rmResourceById(directory, id, version, { type: 'query', persistFiles });
+};
+
+/**
+ * Version a query by it's id.
+ *
+ * Takes the latest query and moves it to a versioned directory.
+ * All files with this query are also versioned (e.g /queries/GetOrder/schema.json)
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionQuery } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest GetOrder query to a versioned directory
+ * // the version within that query is used as the version number.
+ * await versionQuery('GetOrder');
+ *
+ * ```
+ */
+export const versionQuery = (directory: string) => async (id: string) => versionResource(directory, id);
+
+/**
+ * Add a file to a query by it's id.
+ *
+ * Optionally specify a version to add a file to a specific version of the query.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addFileToQuery } = utils('/path/to/eventcatalog');
+ *
+ * // adds a file to the latest GetOrder query
+ * await addFileToQuery('GetOrder', { content: 'Hello world', fileName: 'hello.txt' });
+ *
+ * // adds a file to a specific version of the GetOrder query
+ * await addFileToQuery('GetOrder', { content: 'Hello world', fileName: 'hello.txt' }, '0.0.1');
+ *
+ * ```
+ */
+export const addFileToQuery =
+  (directory: string) =>
+  async (id: string, file: { content: string; fileName: string }, version?: string, options?: { path?: string }) =>
+    addFileToResource(directory, id, file, version, options);
+
+/**
+ * Add a schema to a query by it's id.
+ *
+ * Optionally specify a version to add a schema to a specific version of the query.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addSchemaToQuery } = utils('/path/to/eventcatalog');
+ *
+ * // JSON schema example
+ * const schema = {
+ *    "$schema": "http://json-schema.org/draft-07/schema#",
+ *    "type": "object",
+ *    "properties": {
+ *        "name": {
+ *        "type": "string"
+ *    },
+ *    "age": {
+ *      "type": "number"
+ *    }
+ *  },
+ *  "required": ["name", "age"]
+ * };
+ *
+ * // adds a schema to the latest GetOrder query
+ * await addSchemaToQuery('GetOrder', { schema, fileName: 'schema.json' });
+ *
+ * // adds a file to a specific version of the GetOrder query
+ * await addSchemaToQuery('GetOrder', { schema, fileName: 'schema.json' }, '0.0.1');
+ *
+ * ```
+ */
+export const addSchemaToQuery =
+  (directory: string) =>
+  async (id: string, schema: { schema: string; fileName: string }, version?: string, options?: { path?: string }) => {
+    await addFileToQuery(directory)(id, { content: schema.schema, fileName: schema.fileName }, version, options);
+  };
+
+/**
+ * Check to see if the catalog has a version for the given query.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { queryHasVersion } = utils('/path/to/eventcatalog');
+ *
+ * // returns true if version is found for the given event and version (supports semver)
+ * await queryHasVersion('GetOrder', '0.0.1');
+ * await queryHasVersion('GetOrder', 'latest');
+ * await queryHasVersion('GetOrder', '0.0.x');*
+ *
+ * ```
+ */
+export const queryHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+/**
+ * Add an example file to a query.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addExampleToQuery } = utils('/path/to/eventcatalog');
+ *
+ * await addExampleToQuery('GetOrder', { content: '{"id": "123"}', fileName: 'basic.json' });
+ * await addExampleToQuery('GetOrder', { content: '{"id": "123"}', fileName: 'basic.json' }, '0.0.1');
+ * ```
+ */
+export const addExampleToQuery =
+  (directory: string) => async (id: string, example: { content: string; fileName: string }, version?: string) =>
+    addExampleToResource(directory, id, example, version);
+
+/**
+ * Get all examples from a query.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getExamplesFromQuery } = utils('/path/to/eventcatalog');
+ *
+ * const examples = await getExamplesFromQuery('GetOrder');
+ * const examples = await getExamplesFromQuery('GetOrder', '0.0.1');
+ * ```
+ */
+export const getExamplesFromQuery = (directory: string) => async (id: string, version?: string) =>
+  getExamplesFromResource(directory, id, version);
+
+/**
+ * Remove an example file from a query.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { removeExampleFromQuery } = utils('/path/to/eventcatalog');
+ *
+ * await removeExampleFromQuery('GetOrder', 'basic.json');
+ * await removeExampleFromQuery('GetOrder', 'basic.json', '0.0.1');
+ * ```
+ */
+export const removeExampleFromQuery = (directory: string) => async (id: string, fileName: string, version?: string) =>
+  removeExampleFromResource(directory, id, fileName, version);
diff --git a/packages/sdk/src/services.ts b/packages/sdk/src/services.ts
new file mode 100644
index 000000000..a0d8b05d4
--- /dev/null
+++ b/packages/sdk/src/services.ts
@@ -0,0 +1,655 @@
+import type { Service, Specifications } from './types';
+import fs from 'node:fs/promises';
+import { join, dirname, extname, relative } from 'node:path';
+import {
+  addFileToResource,
+  getFileFromResource,
+  getResource,
+  rmResourceById,
+  versionResource,
+  writeResource,
+  getVersionedDirectory,
+  getResources,
+  getResourcePath,
+  toResource,
+} from './internal/resources';
+import { findFileById, invalidateFileCache, uniqueVersions, buildMessagePointer } from './internal/utils';
+
+/**
+ * Returns a service from EventCatalog.
+ *
+ * You can optionally specify a version to get a specific version of the service
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getService } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the latest version of the event
+ * const service = await getService('InventoryService');
+ *
+ * // Gets a version of the event
+ * const service = await getService('InventoryService', '0.0.1');
+ * ```
+ */
+export const getService =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<Service> =>
+    getResource(directory, id, version, { type: 'service' }) as Promise<Service>;
+
+/**
+ * Returns a service from EventCatalog by it's path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getServiceByPath } = utils('/path/to/eventcatalog');
+ *
+ * // Returns a service from the catalog by it's path
+ * const service = await getServiceByPath('/services/InventoryService/index.mdx');
+ * ```
+ */
+export const getServiceByPath = (directory: string) => async (path: string) => {
+  const service = await getResource(directory, undefined, undefined, { type: 'service' }, path);
+  return service as Service;
+};
+
+/**
+ * Returns all services from EventCatalog.
+ *
+ * You can optionally specify if you want to get the latest version of the services.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getServices } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all services (and versions) from the catalog
+ * const services = await getServices();
+ *
+ * // Gets all services (only latest version) from the catalog
+ * const services = await getServices({ latestOnly: true });
+ * ```
+ */
+export const getServices =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean }): Promise<Service[]> =>
+    getResources(directory, {
+      type: 'services',
+      ignore: [
+        '**/events/**',
+        '**/commands/**',
+        '**/queries/**',
+        '**/entities/**',
+        '**/channels/**',
+        '**/containers/**',
+        '**/data-products/**',
+        '**/data-stores/**',
+        '**/flows/**',
+        '**/subdomains/**/entities/**',
+      ],
+      ...options,
+    }) as Promise<Service[]>;
+
+/**
+ * Write a Service to EventCatalog.
+ *
+ * You can optionally overide the path of the Service.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeService } = utils('/path/to/eventcatalog');
+ *
+ * // Write a Service
+ * // Service would be written to services/InventoryService
+ * await writeService({
+ *   id: 'InventoryService',
+ *   name: 'Inventory Service',
+ *   version: '0.0.1',
+ *   summary: 'Service that handles the inventory',
+ *   markdown: '# Hello world',
+ * });
+ *
+ * // Write a service to the catalog but override the path
+ * // Service would be written to services/Inventory/InventoryService
+ * await writeService({
+ *    id: 'InventoryService',
+ *    name: 'Inventory Adjusted',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { path: "/Inventory/InventoryService"});
+ *
+ * // Write a service to the catalog and override the existing content (if there is any)
+ * await writeService({
+ *    id: 'InventoryService',
+ *    name: 'Inventory Adjusted',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { override: true });
+ *
+ * // Write a service to the catalog and version the previous version
+ * // only works if the new version is greater than the previous version
+ * await writeService({
+ *    id: 'InventoryService',
+ *    name: 'Inventory Adjusted',
+ *    version: '0.0.1',
+ *    summary: 'This is a summary',
+ *    markdown: '# Hello world',
+ * }, { versionExistingContent: true });
+ *
+ * ```
+ */
+export const writeService =
+  (directory: string) =>
+  async (
+    service: Service,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      format: 'mdx',
+    }
+  ) => {
+    const resource: Service = { ...service };
+
+    if (Array.isArray(service.sends)) {
+      resource.sends = uniqueVersions(service.sends as { id: string; version: string }[]);
+    }
+
+    if (Array.isArray(service.receives)) {
+      resource.receives = uniqueVersions(service.receives as { id: string; version: string }[]);
+    }
+
+    return await writeResource(directory, resource, { ...options, type: 'service' });
+  };
+
+/**
+ * Write a versioned service to EventCatalog.
+ *
+ * You can optionally overide the path of the Service.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeVersionedService } = utils('/path/to/eventcatalog');
+ *
+ * // Write a service
+ * // Service would be written to services/InventoryService/versioned/0.0.1
+ * await writeVersionedService({
+ *   id: 'InventoryService',
+ *   name: 'Inventory Service',
+ *   version: '0.0.1',
+ *   summary: 'Service that handles the inventory',
+ *   markdown: '# Hello world',
+ * });
+ *
+ * ```
+ */
+export const writeVersionedService = (directory: string) => async (service: Service) => {
+  const resource: Service = { ...service };
+  const path = getVersionedDirectory(service.id, service.version);
+
+  return await writeService(directory)(resource, { path: path });
+};
+
+/**
+ * Write a service to a domain in EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeServiceToDomain } = utils('/path/to/eventcatalog');
+ *
+ * // Write a service to a domain
+ * // Service would be written to domains/Shopping/services/InventoryService
+ * await writeServiceToDomain({
+ *   id: 'InventoryService',
+ *   name: 'Inventory Service',
+ *   version: '0.0.1',
+ *   summary: 'Service that handles the inventory',
+ *   markdown: '# Hello world',
+ * }, { id: 'Shopping' });
+ * ```
+ */
+export const writeServiceToDomain =
+  (directory: string) =>
+  async (
+    service: Service,
+    domain: { id: string; version?: string; direction?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    let pathForService =
+      domain.version && domain.version !== 'latest'
+        ? `/${domain.id}/versioned/${domain.version}/services`
+        : `/${domain.id}/services`;
+    pathForService = join(pathForService, service.id);
+
+    //
+    await writeResource(directory, { ...service }, { ...options, path: pathForService, type: 'service' });
+  };
+
+/**
+ * Write a service to a system in EventCatalog.
+ */
+export const writeServiceToSystem =
+  (directory: string) =>
+  async (
+    service: Service,
+    system: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    const resourcePath = await getResourcePath(directory, system.id, system.version);
+    if (!resourcePath) {
+      throw new Error('System not found');
+    }
+
+    const pathForService = join(resourcePath.directory, 'services', service.id);
+    await writeResource(directory, { ...service }, { ...options, path: pathForService, type: 'service' });
+  };
+
+/**
+ * Version a service by it's id.
+ *
+ * Takes the latest service and moves it to a versioned directory.
+ * All files with this service are also versioned. (e.g /services/InventoryService/openapi.yml)
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { versionService } = utils('/path/to/eventcatalog');
+ *
+ * // moves the latest InventoryService service to a versioned directory
+ * // the version within that service is used as the version number.
+ * await versionService('InventoryService');
+ *
+ * ```
+ */
+export const versionService = (directory: string) => async (id: string) => versionResource(directory, id);
+
+/**
+ * Delete a service at it's given path.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmService } = utils('/path/to/eventcatalog');
+ *
+ * // Removes the service at services/InventoryService
+ * await rmService('/InventoryService');
+ * ```
+ */
+export const rmService = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+/**
+ * Delete a service by it's id.
+ *
+ * Optionally specify a version to delete a specific version of the service.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmServiceById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the latest InventoryService event
+ * await rmServiceById('InventoryService');
+ *
+ * // deletes a specific version of the InventoryService event
+ * await rmServiceById('InventoryService', '0.0.1');
+ * ```
+ */
+export const rmServiceById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) => {
+  await rmResourceById(directory, id, version, { type: 'service', persistFiles });
+};
+
+/**
+ * Add a file to a service by it's id.
+ *
+ * Optionally specify a version to add a file to a specific version of the service.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addFileToService } = utils('/path/to/eventcatalog');
+ *
+ * // adds a file to the latest InventoryService event
+ * await addFileToService('InventoryService', { content: 'Hello world', fileName: 'hello.txt' });
+ *
+ * // adds a file to a specific version of the InventoryService event
+ * await addFileToService('InventoryService', { content: 'Hello world', fileName: 'hello.txt' }, '0.0.1');
+ *
+ * ```
+ */
+
+export const addFileToService =
+  (directory: string) => async (id: string, file: { content: string; fileName: string }, version?: string) =>
+    addFileToResource(directory, id, file, version);
+
+/**
+ * Returns specification files for a service
+ *
+ * Optionally specify a version to of the service
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getSpecificationFilesForService } = utils('/path/to/eventcatalog');
+ *
+ * // returns a list of specification files for a service
+ * await getSpecificationFilesForService('InventoryService', '0.0.1');
+ *
+ * ```
+ */
+
+export const getSpecificationFilesForService = (directory: string) => async (id: string, version?: string) => {
+  let service: Service = await getService(directory)(id, version);
+  const filePathToService = await findFileById(directory, id, version);
+
+  if (!filePathToService) throw new Error('Cannot find directory of service');
+
+  let specs = [] as any;
+  if (service.specifications) {
+    const serviceSpecifications = service.specifications;
+    let specificationFiles;
+
+    if (Array.isArray(serviceSpecifications)) {
+      specificationFiles = serviceSpecifications.map((spec) => ({ key: spec.type, path: spec.path }));
+    } else {
+      specificationFiles = Object.keys(serviceSpecifications).map((spec) => ({
+        key: spec,
+        path: serviceSpecifications[spec as keyof Specifications] as string,
+      }));
+    }
+
+    const getSpecs = specificationFiles.map(async ({ key, path: fileName }) => {
+      if (!fileName) {
+        throw new Error(`Specification file name for ${fileName} is undefined`);
+      }
+      const rawFile = await getFileFromResource(directory, id, { fileName }, version);
+
+      return { key, content: rawFile, fileName: fileName, path: join(dirname(filePathToService), fileName) };
+    });
+
+    specs = await Promise.all(getSpecs);
+  }
+  return specs;
+};
+
+/**
+ * Add an event/command to a service by it's id.
+ *
+ * Optionally specify a version to add the event to a specific version of the service.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * // Adds an event to the service or command to the service
+ * const { addEventToService, addCommandToService } = utils('/path/to/eventcatalog');
+ *
+ * // Adds a new event (InventoryUpdatedEvent) that the InventoryService will send
+ * await addEventToService('InventoryService', 'sends', { event: 'InventoryUpdatedEvent', version: '2.0.0' });
+ * * // Adds a new event (OrderComplete) that the InventoryService will receive
+ * await addEventToService('InventoryService', 'receives', { event: 'OrderComplete', version: '1.0.0' });
+ *
+ * // Adds a new command (UpdateInventoryCommand) that the InventoryService will send
+ * await addCommandToService('InventoryService', 'sends', { command: 'UpdateInventoryCommand', version: '2.0.0' });
+ * // Adds a new command (VerifyInventory) that the InventoryService will receive
+ * await addCommandToService('InventoryService', 'receives', { command: 'VerifyInventory', version: '1.0.0' });
+ *
+ * ```
+ */
+
+export const addMessageToService =
+  (directory: string) =>
+  async (
+    id: string,
+    direction: string,
+    event: { id: string; version: string; fields?: string[]; group?: string },
+    version?: string
+  ) => {
+    let service: Service = await getService(directory)(id, version);
+    const servicePath = await getResourcePath(directory, id, version);
+    const extension = extname(servicePath?.fullPath || '');
+
+    if (direction === 'sends') {
+      if (service.sends === undefined) {
+        service.sends = [];
+      }
+      // We first check if the event is already in the list
+      for (let i = 0; i < service.sends.length; i++) {
+        if (service.sends[i].id === event.id && service.sends[i].version === event.version) {
+          return;
+        }
+      }
+      service.sends.push(buildMessagePointer(event));
+    } else if (direction === 'receives') {
+      if (service.receives === undefined) {
+        service.receives = [];
+      }
+      // We first check if the event is already in the list
+      for (let i = 0; i < service.receives.length; i++) {
+        if (service.receives[i].id === event.id && service.receives[i].version === event.version) {
+          return;
+        }
+      }
+      service.receives.push(buildMessagePointer(event));
+    } else {
+      throw new Error(`Direction ${direction} is invalid, only 'receives' and 'sends' are supported`);
+    }
+
+    const existingResource = await findFileById(directory, id, version);
+
+    if (!existingResource) {
+      throw new Error(`Cannot find service ${id} in the catalog`);
+    }
+
+    // Get where the service was located, make sure it goes back there.
+    const path = existingResource.split(/[\\/]+services/)[0];
+    const pathToResource = join(path, 'services');
+
+    await rmServiceById(directory)(id, version, true);
+    await writeService(pathToResource)(service, { format: extension === '.md' ? 'md' : 'mdx' });
+  };
+
+/**
+ * Check to see if the catalog has a version for the given service.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { serviceHasVersion } = utils('/path/to/eventcatalog');
+ *
+ * // returns true if version is found for the given event and version (supports semver)
+ * await serviceHasVersion('InventoryService', '0.0.1');
+ * await serviceHasVersion('InventoryService', 'latest');
+ * await serviceHasVersion('InventoryService', '0.0.x');*
+ *
+ * ```
+ */
+export const serviceHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+/**
+ * Check to see if the path is a service.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { isService } = utils('/path/to/eventcatalog');
+ *
+ * // returns true if the path is a service
+ * await isService('/services/InventoryService/index.mdx');
+ * ```
+ */
+export const isService = (directory: string) => async (path: string) => {
+  const service = await getServiceByPath(directory)(path);
+  // Get relative path from root directory
+  const relativePath = relative(directory, path);
+
+  // Split into path segments using regex to handle both / and \
+  const segments = relativePath.split(/[/\\]+/);
+
+  // needs to workf or windows too
+  return !!service && segments.includes('services');
+};
+
+/**
+ * Takes a given raw file and converts it to a service.
+ *
+ * @param directory - The directory to convert the file to a service.
+ * @returns The service.
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { toService } = utils('/path/to/eventcatalog');
+ *
+ * // Read the file from somewhere
+ * const file = fs.readFileSync('/path/to/services/InventoryService/index.mdx', 'utf8');
+ *
+ * // Converts the raw file to a service
+ * await toService(file);
+ * ```
+ */
+export const toService = (directory: string) => async (file: string) => toResource(directory, file) as Promise<Service>;
+
+/**
+ * Add an entity to a service by its id.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { addEntityToService } = utils('/path/to/eventcatalog');
+ *
+ * // adds a new entity (User) to the InventoryService
+ * await addEntityToService('InventoryService', { id: 'User', version: '1.0.0' });
+ *
+ * // adds a new entity (Product) to a specific version of the InventoryService
+ * await addEntityToService('InventoryService', { id: 'Product', version: '1.0.0' }, '2.0.0');
+ *
+ * ```
+ */
+export const addEntityToService =
+  (directory: string) => async (id: string, entity: { id: string; version: string }, version?: string) => {
+    let service: Service = await getService(directory)(id, version);
+    const servicePath = await getResourcePath(directory, id, version);
+    const extension = extname(servicePath?.fullPath || '');
+
+    if (service.entities === undefined) {
+      service.entities = [];
+    }
+
+    // Check if the entity is already in the list
+    for (let i = 0; i < service.entities.length; i++) {
+      if (service.entities[i].id === entity.id && service.entities[i].version === entity.version) {
+        return;
+      }
+    }
+
+    service.entities.push({ id: entity.id, version: entity.version });
+
+    const existingResource = await findFileById(directory, id, version);
+
+    if (!existingResource) {
+      throw new Error(`Cannot find service ${id} in the catalog`);
+    }
+
+    // Get where the service was located, make sure it goes back there.
+    const path = existingResource.split(/[\\/]+services/)[0];
+    const pathToResource = join(path, 'services');
+
+    await rmServiceById(directory)(id, version, true);
+    await writeService(pathToResource)(service, { format: extension === '.md' ? 'md' : 'mdx' });
+  };
+
+/**
+ * Add a data store to a service by it's id.
+ *
+ * Optionally specify a version to add the data store to a specific version of the service.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * // Adds an data store to the service
+ * const { addDataStoreToService } = utils('/path/to/eventcatalog');
+ *
+ * // Adds a new data store (orders-db) that the InventoryService will write to
+ * await addDataStoreToService('InventoryService', 'writesTo', { id: 'orders-db', version: '2.0.0' });
+ *
+ * * // Adds a new data store (OrderComplete) that the InventoryService will read from
+ * await addDataStoreToService('InventoryService', 'readsFrom', { id: 'orders-db', version: '1.0.0' });
+ *
+ * ```
+ */
+
+export const addDataStoreToService =
+  (directory: string) =>
+  async (id: string, operation: 'writesTo' | 'readsFrom', dataStore: { id: string; version: string }, version?: string) => {
+    let service: Service = await getService(directory)(id, version);
+    const servicePath = await getResourcePath(directory, id, version);
+    const extension = extname(servicePath?.fullPath || '');
+
+    if (operation === 'writesTo') {
+      if (service.writesTo === undefined) {
+        service.writesTo = [];
+      }
+
+      // We first check if the data store is already in the list
+      for (let i = 0; i < service.writesTo.length; i++) {
+        if (service.writesTo[i].id === dataStore.id && service.writesTo[i].version === dataStore.version) {
+          return;
+        }
+      }
+
+      service.writesTo.push({ id: dataStore.id, version: dataStore.version });
+    } else if (operation === 'readsFrom') {
+      if (service.readsFrom === undefined) {
+        service.readsFrom = [];
+      }
+
+      // We first check if the data store is already in the list
+      for (let i = 0; i < service.readsFrom.length; i++) {
+        if (service.readsFrom[i].id === dataStore.id && service.readsFrom[i].version === dataStore.version) {
+          return;
+        }
+      }
+      service.readsFrom.push({ id: dataStore.id, version: dataStore.version });
+    } else {
+      throw new Error(`Operation ${operation} is invalid, only 'writesTo' and 'readsFrom' are supported`);
+    }
+
+    const existingResource = await findFileById(directory, id, version);
+
+    if (!existingResource) {
+      throw new Error(`Cannot find service ${id} in the catalog`);
+    }
+
+    // Get where the service was located, make sure it goes back there.
+    const path = existingResource.split(/[\\/]+services/)[0];
+    const pathToResource = join(path, 'services');
+
+    await rmServiceById(directory)(id, version, true);
+    await writeService(pathToResource)(service, { format: extension === '.md' ? 'md' : 'mdx' });
+  };
diff --git a/packages/sdk/src/snapshot-diff.ts b/packages/sdk/src/snapshot-diff.ts
new file mode 100644
index 000000000..627cf0937
--- /dev/null
+++ b/packages/sdk/src/snapshot-diff.ts
@@ -0,0 +1,228 @@
+import type { CatalogSnapshot, ResourceChange, SnapshotResourceType, RelationshipChange } from './snapshot-types';
+
+/**
+ * Stable JSON stringify with sorted keys for deep comparison.
+ * Recurses into nested objects and arrays to ensure key order doesn't affect output.
+ */
+const stableStringify = (value: unknown): string => {
+  if (value === null || value === undefined || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map(stableStringify).join(',') + ']';
+  }
+  const sorted = Object.keys(value as Record<string, unknown>)
+    .sort()
+    .map((key) => JSON.stringify(key) + ':' + stableStringify((value as Record<string, unknown>)[key]));
+  return '{' + sorted.join(',') + '}';
+};
+
+type FlatResource = {
+  resourceId: string;
+  version: string;
+  type: SnapshotResourceType;
+  data: Record<string, unknown>;
+};
+
+const flattenResources = (snapshot: CatalogSnapshot): FlatResource[] => {
+  const resources: FlatResource[] = [];
+
+  const addResources = (items: Record<string, unknown>[], type: SnapshotResourceType) => {
+    for (const item of items) {
+      resources.push({
+        resourceId: item.id as string,
+        version: item.version as string,
+        type,
+        data: item,
+      });
+    }
+  };
+
+  addResources(snapshot.resources.domains, 'domain');
+  addResources(snapshot.resources.services, 'service');
+  addResources(snapshot.resources.agents || [], 'agent');
+  addResources(snapshot.resources.messages.events, 'event');
+  addResources(snapshot.resources.messages.commands, 'command');
+  addResources(snapshot.resources.messages.queries, 'query');
+  addResources(snapshot.resources.channels, 'channel');
+
+  return resources;
+};
+
+// Fields to exclude from comparison
+const EXCLUDED_FIELDS = new Set(['markdown', '_eventcatalog']);
+
+const getComparableFields = (data: Record<string, unknown>): Record<string, unknown> => {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (!EXCLUDED_FIELDS.has(key)) {
+      result[key] = value;
+    }
+  }
+  return result;
+};
+
+const findChangedFields = (dataA: Record<string, unknown>, dataB: Record<string, unknown>): string[] => {
+  const fieldsA = getComparableFields(dataA);
+  const fieldsB = getComparableFields(dataB);
+  const allKeys = new Set([...Object.keys(fieldsA), ...Object.keys(fieldsB)]);
+  const changed: string[] = [];
+
+  for (const key of allKeys) {
+    if (stableStringify(fieldsA[key] ?? null) !== stableStringify(fieldsB[key] ?? null)) {
+      changed.push(key);
+    }
+  }
+
+  return changed;
+};
+
+const resourceKey = (r: FlatResource): string => `${r.resourceId}@${r.version}`;
+const idTypeKey = (r: FlatResource): string => `${r.resourceId}:${r.type}`;
+
+export const computeResourceDiff = (snapshotA: CatalogSnapshot, snapshotB: CatalogSnapshot): ResourceChange[] => {
+  const resourcesA = flattenResources(snapshotA);
+  const resourcesB = flattenResources(snapshotB);
+
+  // Build both maps in a single pass per array
+  const mapA = new Map<string, FlatResource>();
+  const byIdA = new Map<string, FlatResource>();
+  for (const r of resourcesA) {
+    mapA.set(resourceKey(r), r);
+    byIdA.set(idTypeKey(r), r);
+  }
+
+  const mapB = new Map<string, FlatResource>();
+  const byIdB = new Map<string, FlatResource>();
+  for (const r of resourcesB) {
+    mapB.set(resourceKey(r), r);
+    byIdB.set(idTypeKey(r), r);
+  }
+
+  const changes: ResourceChange[] = [];
+  const handledIds = new Set<string>();
+
+  // Find added resources (in B but not A)
+  for (const resource of resourcesB) {
+    const key = resourceKey(resource);
+    if (!mapA.has(key)) {
+      const idKey = idTypeKey(resource);
+      const oldResource = byIdA.get(idKey);
+      if (oldResource && oldResource.version !== resource.version && !handledIds.has(idKey)) {
+        // Version bump: same id, different version
+        const changedFields = findChangedFields(oldResource.data, resource.data);
+        changes.push({
+          resourceId: resource.resourceId,
+          version: resource.version,
+          type: resource.type,
+          changeType: 'versioned',
+          previousVersion: oldResource.version,
+          newVersion: resource.version,
+          changedFields: changedFields.length > 0 ? changedFields : undefined,
+        });
+        handledIds.add(idKey);
+      } else if (!handledIds.has(idKey)) {
+        changes.push({
+          resourceId: resource.resourceId,
+          version: resource.version,
+          type: resource.type,
+          changeType: 'added',
+        });
+      }
+    }
+  }
+
+  // Find removed resources (in A but not B)
+  for (const resource of resourcesA) {
+    const key = resourceKey(resource);
+    if (!mapB.has(key)) {
+      const idKey = idTypeKey(resource);
+      if (!handledIds.has(idKey)) {
+        changes.push({
+          resourceId: resource.resourceId,
+          version: resource.version,
+          type: resource.type,
+          changeType: 'removed',
+        });
+      }
+    }
+  }
+
+  // Find modified resources (in both, but fields differ)
+  for (const resourceB of resourcesB) {
+    const key = resourceKey(resourceB);
+    const resourceA = mapA.get(key);
+    if (resourceA) {
+      const changedFields = findChangedFields(resourceA.data, resourceB.data);
+      if (changedFields.length > 0) {
+        changes.push({
+          resourceId: resourceB.resourceId,
+          version: resourceB.version,
+          type: resourceB.type,
+          changeType: 'modified',
+          changedFields,
+        });
+      }
+    }
+  }
+
+  return changes;
+};
+
+type ServicePointer = { id: string; version?: string };
+
+const getRelationshipKey = (
+  serviceId: string,
+  resourceId: string,
+  resourceVersion: string | undefined,
+  direction: string
+): string => {
+  return `${serviceId}:${direction}:${resourceId}@${resourceVersion || 'latest'}`;
+};
+
+type RelationshipInfo = Omit<RelationshipChange, 'changeType'>;
+
+const extractRelationships = (snapshot: CatalogSnapshot): Map<string, RelationshipInfo> => {
+  const relationships = new Map<string, RelationshipInfo>();
+
+  for (const service of [...snapshot.resources.services, ...(snapshot.resources.agents || [])]) {
+    for (const direction of ['sends', 'receives'] as const) {
+      const pointers: ServicePointer[] = (service as Record<string, any>)[direction] || [];
+      for (const pointer of pointers) {
+        const key = getRelationshipKey(service.id as string, pointer.id, pointer.version, direction);
+        relationships.set(key, {
+          serviceId: service.id as string,
+          serviceVersion: service.version as string,
+          resourceId: pointer.id,
+          resourceVersion: pointer.version,
+          direction,
+        });
+      }
+    }
+  }
+
+  return relationships;
+};
+
+export const computeRelationshipDiff = (snapshotA: CatalogSnapshot, snapshotB: CatalogSnapshot): RelationshipChange[] => {
+  const relsA = extractRelationships(snapshotA);
+  const relsB = extractRelationships(snapshotB);
+
+  const changes: RelationshipChange[] = [];
+
+  // Relationships in B but not in A = added
+  for (const [key, rel] of relsB) {
+    if (!relsA.has(key)) {
+      changes.push({ ...rel, changeType: 'added' });
+    }
+  }
+
+  // Relationships in A but not in B = removed
+  for (const [key, rel] of relsA) {
+    if (!relsB.has(key)) {
+      changes.push({ ...rel, changeType: 'removed' });
+    }
+  }
+
+  return changes;
+};
diff --git a/packages/sdk/src/snapshot-types.ts b/packages/sdk/src/snapshot-types.ts
new file mode 100644
index 000000000..1a2a1b2fa
--- /dev/null
+++ b/packages/sdk/src/snapshot-types.ts
@@ -0,0 +1,84 @@
+export type SnapshotGitInfo = {
+  branch: string;
+  commit: string;
+  dirty: boolean;
+};
+
+export type SnapshotResources = {
+  domains: Record<string, any>[];
+  services: Record<string, any>[];
+  agents?: Record<string, any>[];
+  messages: {
+    events: Record<string, any>[];
+    commands: Record<string, any>[];
+    queries: Record<string, any>[];
+  };
+  channels: Record<string, any>[];
+};
+
+export type CatalogSnapshot = {
+  snapshotVersion: string;
+  catalogVersion: string;
+  label: string;
+  createdAt: string;
+  git?: SnapshotGitInfo;
+  resources: SnapshotResources;
+};
+
+export type SnapshotOptions = {
+  label?: string;
+  outputDir?: string;
+  git?: SnapshotGitInfo;
+};
+
+export type SnapshotResult = {
+  filePath: string;
+  snapshot: CatalogSnapshot;
+};
+
+export type SnapshotMeta = {
+  label: string;
+  createdAt: string;
+  filePath: string;
+  git?: SnapshotGitInfo;
+};
+
+export type SnapshotResourceType = 'event' | 'command' | 'query' | 'service' | 'agent' | 'domain' | 'channel';
+export type ResourceChangeType = 'added' | 'removed' | 'modified' | 'versioned';
+
+export type ResourceChange = {
+  resourceId: string;
+  version: string;
+  type: SnapshotResourceType;
+  changeType: ResourceChangeType;
+  changedFields?: string[];
+  previousVersion?: string;
+  newVersion?: string;
+};
+
+export type RelationshipChange = {
+  serviceId: string;
+  serviceVersion: string;
+  resourceId: string;
+  resourceVersion?: string;
+  direction: 'sends' | 'receives';
+  changeType: 'added' | 'removed';
+};
+
+export type DiffSummary = {
+  totalChanges: number;
+  resourcesAdded: number;
+  resourcesRemoved: number;
+  resourcesModified: number;
+  resourcesVersioned: number;
+  relationshipsAdded: number;
+  relationshipsRemoved: number;
+};
+
+export type SnapshotDiff = {
+  snapshotA: { label: string; createdAt: string };
+  snapshotB: { label: string; createdAt: string };
+  summary: DiffSummary;
+  resources: ResourceChange[];
+  relationships: RelationshipChange[];
+};
diff --git a/packages/sdk/src/snapshots.ts b/packages/sdk/src/snapshots.ts
new file mode 100644
index 000000000..5f0cee4ee
--- /dev/null
+++ b/packages/sdk/src/snapshots.ts
@@ -0,0 +1,196 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { compare } from 'semver';
+import type { CatalogSnapshot, SnapshotOptions, SnapshotResult, SnapshotMeta, SnapshotDiff } from './snapshot-types';
+import utils from './index';
+import { computeResourceDiff, computeRelationshipDiff } from './snapshot-diff';
+
+const SNAPSHOT_VERSION = '1.0.0';
+
+const getEventCatalogVersion = (catalogDir: string): string => {
+  try {
+    const packageJson = fs.readFileSync(path.join(catalogDir, 'package.json'), 'utf8');
+    const packageJsonObject = JSON.parse(packageJson);
+    return packageJsonObject['dependencies']?.['@eventcatalog/core'] ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+};
+
+const pickCoreFields = (resource: any): any => {
+  const picked: any = { id: resource.id, version: resource.version, name: resource.name };
+  if (resource.sends) picked.sends = resource.sends;
+  if (resource.receives) picked.receives = resource.receives;
+  if (resource.deprecated) picked.deprecated = resource.deprecated;
+  if (resource.owners) picked.owners = resource.owners;
+  if (resource.schemaPath) picked.schemaPath = resource.schemaPath;
+  if (resource.schemaHash) picked.schemaHash = resource.schemaHash;
+  return picked;
+};
+
+const deduplicateByLatestVersion = (resources: any[]): any[] => {
+  const seen = new Map<string, any>();
+  for (const r of resources) {
+    const existing = seen.get(r.id);
+    if (!existing || compare(r.version, existing.version) > 0) {
+      seen.set(r.id, r);
+    }
+  }
+  return Array.from(seen.values());
+};
+
+const stripToCore = (resources: any[] | undefined): any[] => {
+  if (!resources || resources.length === 0) return [];
+  return deduplicateByLatestVersion(resources).map(pickCoreFields);
+};
+
+const detectGitInfo = (catalogDir: string): { branch: string; commit: string; dirty: boolean } | undefined => {
+  try {
+    const opts = { cwd: catalogDir, encoding: 'utf8' as const, stdio: 'pipe' as const };
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', opts).trim();
+    const commit = execSync('git rev-parse --short HEAD', opts).trim();
+    const status = execSync('git status --porcelain', opts).trim();
+    return { branch, commit, dirty: status.length > 0 };
+  } catch {
+    return undefined;
+  }
+};
+
+const enrichWithSchemaHashes = async (
+  getSchemaForMessage: (id: string, version?: string) => Promise<{ schema: string; fileName: string } | undefined>,
+  resources: any[]
+): Promise<void> => {
+  await Promise.all(
+    resources.map(async (resource) => {
+      if (!resource.schemaPath) return;
+      const schema = await getSchemaForMessage(resource.id, resource.version);
+      if (!schema) return;
+      resource.schemaHash = createHash('sha256').update(schema.schema).digest('hex');
+    })
+  );
+};
+
+export const createSnapshot = (directory: string) => {
+  // Note: sdk is created lazily inside the inner function to avoid circular
+  // dependency issues (index.ts imports snapshots.ts and vice versa).
+  return async (options?: SnapshotOptions): Promise<SnapshotResult> => {
+    const { label, outputDir, git } = options || {};
+    const sdk = utils(directory);
+
+    // Fetch all resources in parallel
+    const [domains, services, agents, events, commands, queries, channels] = await Promise.all([
+      sdk.getDomains(),
+      sdk.getServices(),
+      sdk.getAgents(),
+      sdk.getEvents(),
+      sdk.getCommands(),
+      sdk.getQueries(),
+      sdk.getChannels(),
+    ]);
+
+    // Enrich messages with schema hashes before stripping
+    await Promise.all([
+      enrichWithSchemaHashes(sdk.getSchemaForMessage, events || []),
+      enrichWithSchemaHashes(sdk.getSchemaForMessage, commands || []),
+      enrichWithSchemaHashes(sdk.getSchemaForMessage, queries || []),
+    ]);
+
+    // Strip to core fields only
+    const snapshotDomains = stripToCore(domains);
+    const snapshotServices = stripToCore(services);
+    const snapshotAgents = stripToCore(agents);
+    const snapshotEvents = stripToCore(events);
+    const snapshotCommands = stripToCore(commands);
+    const snapshotQueries = stripToCore(queries);
+    const snapshotChannels = stripToCore(channels);
+
+    const snapshotLabel = label || new Date().toISOString().replace(/[:.]/g, '-');
+    const gitInfo = git || detectGitInfo(directory);
+
+    const snapshot: CatalogSnapshot = {
+      snapshotVersion: SNAPSHOT_VERSION,
+      catalogVersion: getEventCatalogVersion(directory),
+      label: snapshotLabel,
+      createdAt: new Date().toISOString(),
+      ...(gitInfo ? { git: gitInfo } : {}),
+      resources: {
+        domains: snapshotDomains,
+        services: snapshotServices,
+        agents: snapshotAgents,
+        messages: {
+          events: snapshotEvents,
+          commands: snapshotCommands,
+          queries: snapshotQueries,
+        },
+        channels: snapshotChannels,
+      },
+    };
+
+    // Write to disk
+    const snapshotsDir = outputDir || path.join(directory, '.snapshots');
+    fs.mkdirSync(snapshotsDir, { recursive: true });
+    const fileName = `${snapshotLabel}.snapshot.json`;
+    const filePath = path.join(snapshotsDir, fileName);
+    fs.writeFileSync(filePath, JSON.stringify(snapshot));
+
+    return { filePath, snapshot };
+  };
+};
+
+export const diffSnapshots =
+  (directory: string) =>
+  async (snapshotAPath: string, snapshotBPath: string): Promise<SnapshotDiff> => {
+    const snapshotA: CatalogSnapshot = JSON.parse(fs.readFileSync(snapshotAPath, 'utf-8'));
+    const snapshotB: CatalogSnapshot = JSON.parse(fs.readFileSync(snapshotBPath, 'utf-8'));
+
+    const resourceChanges = computeResourceDiff(snapshotA, snapshotB);
+    const relationshipChanges = computeRelationshipDiff(snapshotA, snapshotB);
+
+    const resourceCounts = { added: 0, removed: 0, modified: 0, versioned: 0 };
+    for (const r of resourceChanges) resourceCounts[r.changeType]++;
+    const relCounts = { added: 0, removed: 0 };
+    for (const r of relationshipChanges) relCounts[r.changeType]++;
+
+    return {
+      snapshotA: { label: snapshotA.label, createdAt: snapshotA.createdAt },
+      snapshotB: { label: snapshotB.label, createdAt: snapshotB.createdAt },
+      summary: {
+        totalChanges: resourceChanges.length + relationshipChanges.length,
+        resourcesAdded: resourceCounts.added,
+        resourcesRemoved: resourceCounts.removed,
+        resourcesModified: resourceCounts.modified,
+        resourcesVersioned: resourceCounts.versioned,
+        relationshipsAdded: relCounts.added,
+        relationshipsRemoved: relCounts.removed,
+      },
+      resources: resourceChanges,
+      relationships: relationshipChanges,
+    };
+  };
+
+export const listSnapshots = (directory: string) => async (): Promise<SnapshotMeta[]> => {
+  const snapshotsDir = path.join(directory, '.snapshots');
+  if (!fs.existsSync(snapshotsDir)) return [];
+
+  const files = fs.readdirSync(snapshotsDir).filter((f) => f.endsWith('.snapshot.json'));
+  const snapshots: SnapshotMeta[] = [];
+
+  for (const file of files) {
+    try {
+      const filePath = path.join(snapshotsDir, file);
+      const content: CatalogSnapshot = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+      snapshots.push({
+        label: content.label,
+        createdAt: content.createdAt,
+        filePath,
+        ...(content.git ? { git: content.git } : {}),
+      });
+    } catch {
+      // skip invalid files
+    }
+  }
+
+  return snapshots.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+};
diff --git a/packages/sdk/src/systems.ts b/packages/sdk/src/systems.ts
new file mode 100644
index 000000000..410035e38
--- /dev/null
+++ b/packages/sdk/src/systems.ts
@@ -0,0 +1,180 @@
+import type { System } from './types';
+import fs from 'node:fs/promises';
+import { extname, join, relative } from 'node:path';
+import {
+  addFileToResource,
+  getResource,
+  getResourcePath,
+  getResources,
+  rmResourceById,
+  toResource,
+  versionResource,
+  writeResource,
+} from './internal/resources';
+import { findFileById, invalidateFileCache, uniqueVersions } from './internal/utils';
+
+type SystemResourceField = 'services' | 'flows' | 'entities' | 'containers';
+
+const SYSTEM_RESOURCE_IGNORES = [
+  '**/systems/**/agents/**',
+  '**/systems/**/services/**',
+  '**/systems/**/events/**',
+  '**/systems/**/commands/**',
+  '**/systems/**/queries/**',
+  '**/systems/**/flows/**',
+  '**/systems/**/channels/**',
+  '**/systems/**/entities/**',
+  '**/systems/**/containers/**',
+  '**/systems/**/diagrams/**',
+  '**/systems/**/data-products/**',
+  '**/systems/**/adrs/**',
+  '**/systems/**/docs/**',
+];
+
+const normalizeResourcePointers = (system: System): System => {
+  const resource = { ...system };
+
+  if (Array.isArray(system.services)) {
+    resource.services = uniqueVersions(system.services as { id: string; version: string }[]);
+  }
+
+  if (Array.isArray(system.flows)) {
+    resource.flows = uniqueVersions(system.flows as { id: string; version: string }[]);
+  }
+
+  if (Array.isArray(system.entities)) {
+    resource.entities = uniqueVersions(system.entities as { id: string; version: string }[]);
+  }
+
+  if (Array.isArray(system.containers)) {
+    resource.containers = uniqueVersions(system.containers as { id: string; version: string }[]);
+  }
+
+  return resource;
+};
+
+const persistSystemAtExistingPath = async (directory: string, system: System, version?: string) => {
+  const systemPath = await getResourcePath(directory, system.id, version);
+  const extension = extname(systemPath?.fullPath || '');
+
+  if (!systemPath) {
+    throw new Error(`Cannot find system ${system.id} in the catalog`);
+  }
+
+  await rmSystemById(directory)(system.id, version, true);
+  await writeSystem(directory)(system, {
+    path: systemPath.directory,
+    format: extension === '.md' ? 'md' : 'mdx',
+  });
+};
+
+export const getSystem =
+  (directory: string) =>
+  async (id: string, version?: string): Promise<System> =>
+    getResource(directory, id, version, { type: 'system' }) as Promise<System>;
+
+export const getSystemByPath = (directory: string) => async (path: string) => {
+  const system = await getResource(directory, undefined, undefined, { type: 'system' }, path);
+  return system as System;
+};
+
+export const getSystems =
+  (directory: string) =>
+  async (options?: { latestOnly?: boolean }): Promise<System[]> =>
+    getResources(directory, {
+      type: 'systems',
+      ignore: SYSTEM_RESOURCE_IGNORES,
+      latestOnly: options?.latestOnly,
+    }) as Promise<System[]>;
+
+export const writeSystem =
+  (directory: string) =>
+  async (
+    system: System,
+    options: { path?: string; override?: boolean; versionExistingContent?: boolean; format?: 'md' | 'mdx' } = {
+      path: '',
+      override: false,
+      format: 'mdx',
+    }
+  ) => {
+    const resource = normalizeResourcePointers(system);
+
+    return await writeResource(directory, resource, { ...options, type: 'system' });
+  };
+
+export const writeSystemToDomain =
+  (directory: string) =>
+  async (
+    system: System,
+    domain: { id: string; version?: string },
+    options: { path?: string; format?: 'md' | 'mdx'; override?: boolean } = { path: '', format: 'mdx', override: false }
+  ) => {
+    const resourcePath = await getResourcePath(directory, domain.id, domain.version);
+    if (!resourcePath) {
+      throw new Error('Domain not found');
+    }
+
+    const pathForSystem = join(resourcePath.directory, 'systems', system.id);
+    await writeSystem(directory)({ ...system }, { ...options, path: pathForSystem });
+  };
+
+export const versionSystem = (directory: string) => async (id: string) => versionResource(directory, id);
+
+export const rmSystem = (directory: string) => async (path: string) => {
+  await fs.rm(join(directory, path), { recursive: true });
+  invalidateFileCache();
+};
+
+export const rmSystemById = (directory: string) => async (id: string, version?: string, persistFiles?: boolean) => {
+  await rmResourceById(directory, id, version, { type: 'system', persistFiles });
+};
+
+export const addFileToSystem =
+  (directory: string) => async (id: string, file: { content: string; fileName: string }, version?: string) =>
+    addFileToResource(directory, id, file, version);
+
+export const systemHasVersion = (directory: string) => async (id: string, version?: string) => {
+  const file = await findFileById(directory, id, version);
+  return !!file;
+};
+
+export const isSystem = (directory: string) => async (path: string) => {
+  const system = await getSystemByPath(directory)(path);
+  const relativePath = relative(directory, path);
+  const segments = relativePath.split(/[/\\]+/);
+
+  return !!system && segments.includes('systems');
+};
+
+export const toSystem = (directory: string) => async (file: string) => toResource(directory, file) as Promise<System>;
+
+export const addResourceToSystem =
+  (directory: string, resourceField: SystemResourceField) =>
+  async (id: string, resource: { id: string; version: string }, version?: string) => {
+    const system: System = await getSystem(directory)(id, version);
+
+    if (!system) {
+      throw new Error(`Cannot find system ${id} in the catalog`);
+    }
+
+    if (system[resourceField] === undefined) {
+      system[resourceField] = [];
+    }
+
+    const resourceExistsInList = system[resourceField]?.some(
+      (item) => item.id === resource.id && item.version === resource.version
+    );
+
+    if (resourceExistsInList) {
+      return;
+    }
+
+    system[resourceField]?.push(resource);
+
+    await persistSystemAtExistingPath(directory, system, version);
+  };
+
+export const addServiceToSystem = (directory: string) => addResourceToSystem(directory, 'services');
+export const addFlowToSystem = (directory: string) => addResourceToSystem(directory, 'flows');
+export const addEntityToSystem = (directory: string) => addResourceToSystem(directory, 'entities');
+export const addContainerToSystem = (directory: string) => addResourceToSystem(directory, 'containers');
diff --git a/packages/sdk/src/teams.ts b/packages/sdk/src/teams.ts
new file mode 100644
index 000000000..53570bcf8
--- /dev/null
+++ b/packages/sdk/src/teams.ts
@@ -0,0 +1,177 @@
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import { join } from 'node:path';
+import type { Team } from './types';
+import matter from 'gray-matter';
+import { getFiles, invalidateFileCache } from './internal/utils';
+import { getResource } from './internal/resources';
+import path from 'node:path';
+import { getUser, getUsers } from './users';
+import {
+  mergeDirectoryStoreResources,
+  readDirectoryStoreResource,
+  readDirectoryStoreResources,
+} from './internal/directory-store';
+
+/**
+ * Returns a team from EventCatalog.
+ *
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getTeam } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the team with the given id
+ * const team = await getTeam('eventcatalog-core-team');
+ *
+ * ```
+ */
+export const getTeam =
+  (catalogDir: string) =>
+  async (id: string): Promise<Team | undefined> => {
+    const files = await getFiles(`${catalogDir}/${id}.{md,mdx}`);
+
+    if (files.length == 0) return readDirectoryStoreResource<Team>(catalogDir, 'teams', id);
+    const file = files[0];
+
+    const { data, content } = matter.read(file);
+    return {
+      ...data,
+      id: data.id,
+      name: data.name,
+      markdown: content.trim(),
+    } as Team;
+  };
+
+/**
+ * Returns all teams from EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getTeams } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all teams from the catalog
+ * const channels = await getTeams();
+ *
+ * ```
+ */
+export const getTeams =
+  (catalogDir: string) =>
+  async (options?: {}): Promise<Team[]> => {
+    const files = await getFiles(`${catalogDir}/*.{md,mdx}`);
+    const localTeams = files.map((file) => {
+      const { data, content } = matter.read(file);
+      return {
+        ...data,
+        id: data.id,
+        name: data.name,
+        markdown: content.trim(),
+      } as Team;
+    });
+
+    return mergeDirectoryStoreResources(localTeams, readDirectoryStoreResources<Team>(catalogDir, 'teams'));
+  };
+
+/**
+ * Write a team to EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeTeam } = utils('/path/to/eventcatalog');
+ *
+ * // Write a team to the catalog
+ * // team would be written to teams/EventCatalogCoreTeam
+ * await writeTeam({
+ *   id: 'eventcatalog-core-team',
+ *   name: 'EventCatalogCoreTeam',
+ *   members: ['dboyne', 'asmith', 'msmith'],
+ *   email: 'test@test.com',
+ *   slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+ * });
+ *
+ * // Write a team to the catalog and override the existing content (if there is any)
+ * await writeTeam({
+ *   id: 'eventcatalog-core-team',
+ *   name: 'EventCatalogCoreTeam',
+ *   members: ['dboyne', 'asmith', 'msmith'],
+ *   email: 'test@test.com',
+ *   slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+ * }, { override: true });
+ *
+ * ```
+ */
+export const writeTeam =
+  (catalogDir: string) =>
+  async (team: Team, options: { override?: boolean } = {}) => {
+    const resource: Team = { ...team };
+
+    // Get the path
+    const currentTeam = await getTeam(catalogDir)(resource.id);
+    const exists = currentTeam !== undefined;
+
+    if (exists && !options.override) {
+      throw new Error(`Failed to write ${resource.id} (team) as it already exists`);
+    }
+
+    const { markdown, ...frontmatter } = resource;
+
+    const document = matter.stringify(markdown, frontmatter);
+    fsSync.mkdirSync(join(catalogDir, ''), { recursive: true });
+    fsSync.writeFileSync(join(catalogDir, '', `${resource.id}.mdx`), document);
+    invalidateFileCache();
+  };
+
+/**
+ * Delete a team by it's id.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmTeamById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the EventCatalogCoreTeam team
+ * await rmTeamById('eventcatalog-core-team');
+ *
+ * ```
+ */
+export const rmTeamById = (catalogDir: string) => async (id: string) => {
+  await fs.rm(join(catalogDir, `${id}.mdx`), { recursive: true });
+  invalidateFileCache();
+};
+
+/**
+ * Returns the owners for a given resource (e.g domain, service, event, command, query, etc.)
+ * @param id - The id of the resource to get the owners for
+ * @param version - Optional version of the resource
+ * @returns { owners: User[] }
+ */
+export const getOwnersForResource = (catalogDir: string) => async (id: string, version?: string) => {
+  const resource = await getResource(catalogDir, id, version);
+  let owners: Team[] = [];
+  if (!resource) return [];
+
+  if (!resource.owners) return [];
+
+  // First check if the owner is a team
+  for (const owner of resource.owners) {
+    const team = await getTeam(path.join(catalogDir, 'teams'))(owner);
+    if (team) {
+      owners.push(team);
+    } else {
+      // If the owner is not a team, check if it's a user
+      const user = await getUser(path.join(catalogDir, 'users'))(owner);
+      if (user) {
+        owners.push(user);
+      }
+    }
+  }
+
+  return owners;
+};
diff --git a/packages/sdk/src/test/adrs.test.ts b/packages/sdk/src/test/adrs.test.ts
new file mode 100644
index 000000000..be4af81e7
--- /dev/null
+++ b/packages/sdk/src/test/adrs.test.ts
@@ -0,0 +1,455 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-adrs');
+
+const { writeAdr, getAdr, getAdrs, rmAdr, rmAdrById, versionAdr, adrHasVersion, addFileToAdr } = utils(CATALOG_PATH);
+
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('ADRs SDK', () => {
+  describe('getAdr', () => {
+    it('returns the given ADR id from EventCatalog and the latest version when no version is given', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        summary: 'Use the transactional outbox pattern for integration events',
+        status: 'accepted',
+        date: '2024-01-15',
+        decisionMakers: ['platform-team', 'dboyne'],
+        appliesTo: [{ id: 'OrdersService', version: '1.0.0', type: 'service' }],
+        markdown: '# Use Transactional Outbox',
+      });
+
+      const adr = await getAdr('use-transactional-outbox');
+
+      expect(adr).toEqual({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        summary: 'Use the transactional outbox pattern for integration events',
+        status: 'accepted',
+        date: '2024-01-15',
+        decisionMakers: ['platform-team', 'dboyne'],
+        appliesTo: [{ id: 'OrdersService', version: '1.0.0', type: 'service' }],
+        markdown: '# Use Transactional Outbox',
+      });
+    });
+
+    it('returns the given ADR id from EventCatalog and the requested version when a version is given', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      await versionAdr('use-transactional-outbox');
+
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '2.0.0',
+        status: 'superseded',
+        date: '2024-02-15',
+        markdown: '# Use Transactional Outbox v2',
+      });
+
+      const adr = await getAdr('use-transactional-outbox', '1.0.0');
+
+      expect(adr).toEqual({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+    });
+
+    it('returns undefined when a given resource is not found', async () => {
+      const adr = await getAdr('missing-adr');
+      expect(adr).toEqual(undefined);
+    });
+  });
+
+  describe('getAdrs', () => {
+    it('returns all ADRs from the catalog', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      await writeAdr({
+        id: 'use-postgres',
+        name: 'Use Postgres',
+        version: '1.0.0',
+        status: 'proposed',
+        date: '2024-01-20',
+        markdown: '# Use Postgres',
+      });
+
+      const adrs = await getAdrs();
+      expect(adrs).toHaveLength(2);
+      expect(adrs.map((adr) => adr.id).sort()).toEqual(['use-postgres', 'use-transactional-outbox']);
+    });
+
+    it('returns only latest versions when latestOnly is true', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      await versionAdr('use-transactional-outbox');
+
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '2.0.0',
+        status: 'superseded',
+        date: '2024-02-15',
+        markdown: '# Use Transactional Outbox v2',
+      });
+
+      const adrs = await getAdrs({ latestOnly: true });
+      expect(adrs).toHaveLength(1);
+      expect(adrs[0].version).toBe('2.0.0');
+    });
+  });
+
+  describe('writeAdr', () => {
+    it('writes the given ADR to the file system', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        summary: 'Use the transactional outbox pattern for integration events',
+        status: 'accepted',
+        date: '2024-01-15',
+        supersedes: [{ id: 'publish-after-commit', version: '1.0.0' }],
+        related: [{ id: 'use-postgres' }],
+        markdown: '# Use Transactional Outbox',
+      });
+
+      const adr = await getAdr('use-transactional-outbox');
+
+      expect(adr).toEqual({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        summary: 'Use the transactional outbox pattern for integration events',
+        status: 'accepted',
+        date: '2024-01-15',
+        supersedes: [{ id: 'publish-after-commit', version: '1.0.0' }],
+        related: [{ id: 'use-postgres' }],
+        markdown: '# Use Transactional Outbox',
+      });
+    });
+
+    it('writes the ADR to a custom path when path is provided', async () => {
+      await writeAdr(
+        {
+          id: 'use-transactional-outbox',
+          name: 'Use Transactional Outbox',
+          version: '1.0.0',
+          status: 'accepted',
+          date: '2024-01-15',
+          markdown: '# Use Transactional Outbox',
+        },
+        { path: '/technical/use-transactional-outbox' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'adrs/technical/use-transactional-outbox', 'index.mdx'))).toBe(true);
+      expect(await getAdr('use-transactional-outbox')).toEqual({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+    });
+
+    it('throws an error when trying to write an ADR that already exists', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      await expect(
+        writeAdr({
+          id: 'use-transactional-outbox',
+          name: 'Use Transactional Outbox',
+          version: '1.0.0',
+          status: 'accepted',
+          date: '2024-01-15',
+          markdown: '# Use Transactional Outbox',
+        })
+      ).rejects.toThrowError('Failed to write use-transactional-outbox (adr) as the version 1.0.0 already exists');
+    });
+
+    it('overrides the ADR when trying to write an ADR that already exists and override is true', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      await writeAdr(
+        {
+          id: 'use-transactional-outbox',
+          name: 'Use Transactional Outbox',
+          version: '1.0.0',
+          status: 'accepted',
+          date: '2024-01-15',
+          markdown: 'Overridden content',
+        },
+        { override: true }
+      );
+
+      const adr = await getAdr('use-transactional-outbox');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'adrs/use-transactional-outbox', 'index.mdx'))).toBe(true);
+      expect(adr.markdown).toBe('Overridden content');
+    });
+
+    it('versions the previous ADR when trying to write an ADR that already exists and versionExistingContent is true', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      await writeAdr(
+        {
+          id: 'use-transactional-outbox',
+          name: 'Use Transactional Outbox',
+          version: '2.0.0',
+          status: 'accepted',
+          date: '2024-02-15',
+          markdown: '# Use Transactional Outbox v2',
+        },
+        { versionExistingContent: true }
+      );
+
+      const adr = await getAdr('use-transactional-outbox');
+      expect(adr.version).toBe('2.0.0');
+      expect(adr.markdown).toBe('# Use Transactional Outbox v2');
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'adrs/use-transactional-outbox/versioned/1.0.0', 'index.mdx'))).toBe(true);
+    });
+
+    it('writes the ADR as md when format is md', async () => {
+      await writeAdr(
+        {
+          id: 'use-transactional-outbox',
+          name: 'Use Transactional Outbox',
+          version: '1.0.0',
+          status: 'accepted',
+          date: '2024-01-15',
+          markdown: '# Use Transactional Outbox',
+        },
+        { format: 'md' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'adrs/use-transactional-outbox', 'index.md'))).toBe(true);
+    });
+  });
+
+  describe('rmAdr', () => {
+    it('removes an ADR by its path', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      await rmAdr('/use-transactional-outbox');
+
+      expect(await getAdr('use-transactional-outbox')).toEqual(undefined);
+    });
+  });
+
+  describe('rmAdrById', () => {
+    it('removes an ADR by its id', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      await rmAdrById('use-transactional-outbox');
+
+      expect(await getAdr('use-transactional-outbox')).toEqual(undefined);
+    });
+
+    it('removes a specific version of an ADR by its id and version', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      await versionAdr('use-transactional-outbox');
+
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '2.0.0',
+        status: 'superseded',
+        date: '2024-02-15',
+        markdown: '# Use Transactional Outbox v2',
+      });
+
+      await rmAdrById('use-transactional-outbox', '1.0.0');
+
+      expect(await getAdr('use-transactional-outbox', '1.0.0')).toEqual(undefined);
+      expect(await getAdr('use-transactional-outbox', '2.0.0')).toEqual({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '2.0.0',
+        status: 'superseded',
+        date: '2024-02-15',
+        markdown: '# Use Transactional Outbox v2',
+      });
+    });
+  });
+
+  describe('versionAdr', () => {
+    it('versions an ADR by moving it to a versioned directory', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      await versionAdr('use-transactional-outbox');
+
+      expect(await getAdr('use-transactional-outbox', '1.0.0')).toEqual({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+    });
+  });
+
+  describe('adrHasVersion', () => {
+    it('returns true if ADR version exists', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      expect(await adrHasVersion('use-transactional-outbox', '1.0.0')).toBe(true);
+    });
+
+    it('returns false if ADR version does not exist', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      expect(await adrHasVersion('use-transactional-outbox', '2.0.0')).toBe(false);
+    });
+
+    it('returns false if ADR does not exist', async () => {
+      expect(await adrHasVersion('missing-adr', '1.0.0')).toBe(false);
+    });
+  });
+
+  describe('addFileToAdr', () => {
+    it('adds a file to the ADR', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      await addFileToAdr('use-transactional-outbox', { content: 'decision context', fileName: 'context.txt' });
+
+      const filePath = path.join(CATALOG_PATH, 'adrs/use-transactional-outbox', 'context.txt');
+      expect(fs.existsSync(filePath)).toBe(true);
+      expect(fs.readFileSync(filePath, 'utf-8')).toBe('decision context');
+    });
+
+    it('adds a file to a specific version of the ADR', async () => {
+      await writeAdr({
+        id: 'use-transactional-outbox',
+        name: 'Use Transactional Outbox',
+        version: '1.0.0',
+        status: 'accepted',
+        date: '2024-01-15',
+        markdown: '# Use Transactional Outbox',
+      });
+
+      await versionAdr('use-transactional-outbox');
+
+      await addFileToAdr('use-transactional-outbox', { content: 'decision context v1', fileName: 'context.txt' }, '1.0.0');
+
+      const filePath = path.join(CATALOG_PATH, 'adrs/use-transactional-outbox/versioned/1.0.0', 'context.txt');
+      expect(fs.existsSync(filePath)).toBe(true);
+      expect(fs.readFileSync(filePath, 'utf-8')).toBe('decision context v1');
+    });
+
+    it('throws an error when trying to write to an ADR that does not exist', async () => {
+      await expect(addFileToAdr('missing-adr', { content: 'hello', fileName: 'test.txt' })).rejects.toThrowError(
+        'Cannot find directory to write file to'
+      );
+    });
+  });
+});
diff --git a/packages/sdk/src/test/agents.test.ts b/packages/sdk/src/test/agents.test.ts
new file mode 100644
index 000000000..aa2f538ff
--- /dev/null
+++ b/packages/sdk/src/test/agents.test.ts
@@ -0,0 +1,683 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-agents');
+
+const {
+  writeAgent,
+  writeVersionedAgent,
+  writeAgentToDomain,
+  writeEventToAgent,
+  writeCommandToAgent,
+  writeQueryToAgent,
+  getAgent,
+  getAgentByPath,
+  getAgents,
+  versionAgent,
+  rmAgent,
+  rmAgentById,
+  addFileToAgent,
+  addEventToAgent,
+  addCommandToAgent,
+  addQueryToAgent,
+  addDataStoreToAgent,
+  addFlowToAgent,
+  agentHasVersion,
+  isAgent,
+  toAgent,
+} = utils(CATALOG_PATH);
+
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Agents SDK', () => {
+  describe('getAgent', () => {
+    it('returns the given agent id from EventCatalog and the latest version when no version is given', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        summary: 'Agent that helps support teams investigate order questions',
+        markdown: '# Order support agent',
+        model: {
+          provider: 'OpenAI',
+          name: 'gpt-4.1-mini',
+          version: '2025-04-14',
+        },
+        tools: [
+          {
+            name: 'Order lookup',
+            type: 'mcp',
+            url: 'https://mcp.example.com/orders/lookup',
+            description: 'Retrieves order status and recent order events',
+          },
+        ],
+      });
+
+      const agent = await getAgent('OrderSupportAgent');
+
+      expect(agent).toEqual({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        summary: 'Agent that helps support teams investigate order questions',
+        markdown: '# Order support agent',
+        model: {
+          provider: 'OpenAI',
+          name: 'gpt-4.1-mini',
+          version: '2025-04-14',
+        },
+        tools: [
+          {
+            name: 'Order lookup',
+            type: 'mcp',
+            url: 'https://mcp.example.com/orders/lookup',
+            description: 'Retrieves order status and recent order events',
+          },
+        ],
+      });
+    });
+
+    it('returns the given agent id from EventCatalog and the requested version when a version is given', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        summary: 'Agent that helps support teams investigate order questions',
+        markdown: '# Order support agent',
+      });
+
+      await versionAgent('OrderSupportAgent');
+
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '1.0.0',
+        summary: 'Agent that helps support teams investigate order questions',
+        markdown: '# Order support agent',
+      });
+
+      const agent = await getAgent('OrderSupportAgent', '0.0.1');
+
+      expect(agent).toEqual({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        summary: 'Agent that helps support teams investigate order questions',
+        markdown: '# Order support agent',
+      });
+    });
+
+    it('returns undefined when a given agent is not found', async () => {
+      const agent = await getAgent('MissingAgent');
+
+      expect(agent).toEqual(undefined);
+    });
+  });
+
+  describe('getAgentByPath', () => {
+    it('returns the given agent from EventCatalog by its path', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        summary: 'Agent that helps support teams investigate order questions',
+        markdown: '# Order support agent',
+      });
+
+      const agent = await getAgentByPath(path.join(CATALOG_PATH, 'agents/OrderSupportAgent/index.mdx'));
+
+      expect(agent).toEqual({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        summary: 'Agent that helps support teams investigate order questions',
+        markdown: '# Order support agent',
+      });
+    });
+  });
+
+  describe('getAgents', () => {
+    it('returns all agents from the catalog', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await writeAgent({
+        id: 'FraudReviewAgent',
+        name: 'Fraud Review Agent',
+        version: '0.0.1',
+        markdown: '# Fraud review agent',
+      });
+
+      const agents = await getAgents();
+
+      expect(agents).toHaveLength(2);
+      expect(agents.map((agent) => agent.id).sort()).toEqual(['FraudReviewAgent', 'OrderSupportAgent']);
+    });
+
+    it('returns only latest versions when latestOnly is true', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await versionAgent('OrderSupportAgent');
+
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '1.0.0',
+        markdown: '# Order support agent v2',
+      });
+
+      const agents = await getAgents({ latestOnly: true });
+
+      expect(agents).toHaveLength(1);
+      expect(agents[0].version).toBe('1.0.0');
+    });
+  });
+
+  describe('writeAgent', () => {
+    it('writes the given agent to the file system', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        summary: 'Agent that helps support teams investigate order questions',
+        markdown: '# Order support agent',
+        sends: [
+          { id: 'SupportCaseAnalyzed', version: '1.0.0' },
+          { id: 'SupportCaseAnalyzed', version: '1.0.0' },
+        ],
+        receives: [
+          { id: 'OrderConfirmed', version: '1.0.0' },
+          { id: 'OrderConfirmed', version: '1.0.0' },
+        ],
+      });
+
+      const agent = await getAgent('OrderSupportAgent');
+
+      expect(agent).toEqual({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        summary: 'Agent that helps support teams investigate order questions',
+        markdown: '# Order support agent',
+        sends: [{ id: 'SupportCaseAnalyzed', version: '1.0.0' }],
+        receives: [{ id: 'OrderConfirmed', version: '1.0.0' }],
+      });
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent', 'index.mdx'))).toBe(true);
+    });
+
+    it('throws an error when trying to write an agent that already exists', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await expect(
+        writeAgent({
+          id: 'OrderSupportAgent',
+          name: 'Order Support Agent',
+          version: '0.0.1',
+          markdown: '# Order support agent',
+        })
+      ).rejects.toThrowError('Failed to write OrderSupportAgent (agent) as the version 0.0.1 already exists');
+    });
+
+    it('overrides the agent when trying to write an agent that already exists and override is true', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await writeAgent(
+        {
+          id: 'OrderSupportAgent',
+          name: 'Order Support Agent',
+          version: '0.0.1',
+          markdown: 'Overridden content',
+        },
+        { override: true }
+      );
+
+      const agent = await getAgent('OrderSupportAgent');
+
+      expect(agent.markdown).toBe('Overridden content');
+    });
+  });
+
+  describe('writeVersionedAgent', () => {
+    it('writes a versioned agent', async () => {
+      await writeVersionedAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent/versioned/0.0.1', 'index.mdx'))).toBe(true);
+    });
+  });
+
+  describe('writeAgentToDomain', () => {
+    it('writes an agent to a domain', async () => {
+      await writeAgentToDomain(
+        {
+          id: 'OrderSupportAgent',
+          name: 'Order Support Agent',
+          version: '0.0.1',
+          markdown: '# Order support agent',
+        },
+        { id: 'Orders' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders/agents/OrderSupportAgent', 'index.mdx'))).toBe(true);
+    });
+
+    it('writes an agent to a versioned domain', async () => {
+      await writeAgentToDomain(
+        {
+          id: 'OrderSupportAgent',
+          name: 'Order Support Agent',
+          version: '0.0.1',
+          markdown: '# Order support agent',
+        },
+        { id: 'Orders', version: '1.0.0' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders/versioned/1.0.0/agents/OrderSupportAgent', 'index.mdx'))).toBe(
+        true
+      );
+    });
+  });
+
+  describe('writeMessageToAgent', () => {
+    it('writes an event to an agent', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await writeEventToAgent(
+        {
+          id: 'SupportCaseAnalyzed',
+          name: 'Support Case Analyzed',
+          version: '1.0.0',
+          markdown: '# Support case analyzed',
+        },
+        { id: 'OrderSupportAgent' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent/events/SupportCaseAnalyzed', 'index.mdx'))).toBe(
+        true
+      );
+    });
+
+    it('writes a command to an agent', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await writeCommandToAgent(
+        {
+          id: 'InvestigateOrder',
+          name: 'Investigate Order',
+          version: '1.0.0',
+          markdown: '# Investigate order',
+        },
+        { id: 'OrderSupportAgent' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent/commands/InvestigateOrder', 'index.mdx'))).toBe(
+        true
+      );
+    });
+
+    it('writes a query to an agent', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await writeQueryToAgent(
+        {
+          id: 'GetOrderSummary',
+          name: 'Get Order Summary',
+          version: '1.0.0',
+          markdown: '# Get order summary',
+        },
+        { id: 'OrderSupportAgent' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent/queries/GetOrderSummary', 'index.mdx'))).toBe(true);
+    });
+  });
+
+  describe('rmAgent', () => {
+    it('removes an agent by its path', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await rmAgent('/OrderSupportAgent');
+
+      const agent = await getAgent('OrderSupportAgent');
+
+      expect(agent).toEqual(undefined);
+    });
+  });
+
+  describe('rmAgentById', () => {
+    it('removes an agent by its id', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await rmAgentById('OrderSupportAgent');
+
+      const agent = await getAgent('OrderSupportAgent');
+
+      expect(agent).toEqual(undefined);
+    });
+  });
+
+  describe('agentHasVersion', () => {
+    it('returns true when the given agent version exists', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      expect(await agentHasVersion('OrderSupportAgent', '0.0.1')).toBe(true);
+    });
+
+    it('returns false when the given agent version does not exist', async () => {
+      expect(await agentHasVersion('OrderSupportAgent', '0.0.1')).toBe(false);
+    });
+  });
+
+  describe('addFileToAgent', () => {
+    it('adds a file to the given agent', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await addFileToAgent('OrderSupportAgent', { content: 'Agent notes', fileName: 'notes.md' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent', 'notes.md'))).toBe(true);
+      expect(fs.readFileSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent', 'notes.md'), 'utf-8')).toBe('Agent notes');
+    });
+  });
+
+  describe('addMessageToAgent', () => {
+    it('adds the given event to the agent sends list', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await addEventToAgent('OrderSupportAgent', 'sends', { id: 'SupportCaseAnalyzed', version: '1.0.0' }, '0.0.1');
+
+      const agent = await getAgent('OrderSupportAgent');
+
+      expect(agent.sends).toEqual([{ id: 'SupportCaseAnalyzed', version: '1.0.0' }]);
+    });
+
+    it('adds the given command to the agent receives list', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await addCommandToAgent('OrderSupportAgent', 'receives', { id: 'InvestigateOrder', version: '1.0.0' }, '0.0.1');
+
+      const agent = await getAgent('OrderSupportAgent');
+
+      expect(agent.receives).toEqual([{ id: 'InvestigateOrder', version: '1.0.0' }]);
+    });
+
+    it('adds the given query to the agent sends list', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await addQueryToAgent('OrderSupportAgent', 'sends', { id: 'GetOrderSummary', version: '1.0.0' }, '0.0.1');
+
+      const agent = await getAgent('OrderSupportAgent');
+
+      expect(agent.sends).toEqual([{ id: 'GetOrderSummary', version: '1.0.0' }]);
+    });
+
+    it('preserves the versioned agent location when adding a message to a historical version', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent v1',
+      });
+
+      await versionAgent('OrderSupportAgent');
+
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '1.0.0',
+        markdown: '# Order support agent v2',
+      });
+
+      await addEventToAgent('OrderSupportAgent', 'receives', { id: 'OrderConfirmed', version: '1.0.0' }, '0.0.1');
+
+      const versionedAgent = await getAgent('OrderSupportAgent', '0.0.1');
+      const latestAgent = await getAgent('OrderSupportAgent');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent/versioned/0.0.1', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent', 'index.mdx'))).toBe(true);
+      expect(versionedAgent.receives).toEqual([{ id: 'OrderConfirmed', version: '1.0.0' }]);
+      expect(latestAgent.version).toBe('1.0.0');
+      expect(latestAgent.receives).toBeUndefined();
+    });
+
+    it('throws an error when the direction is invalid', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await expect(
+        addEventToAgent('OrderSupportAgent', 'publishes', { id: 'SupportCaseAnalyzed', version: '1.0.0' }, '0.0.1')
+      ).rejects.toThrowError("Direction publishes is invalid, only 'receives' and 'sends' are supported");
+    });
+  });
+
+  describe('addDataStoreToAgent', () => {
+    it('adds the given data store to the agent writesTo list', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await addDataStoreToAgent('OrderSupportAgent', 'writesTo', { id: 'support-notes-db', version: '1.0.0' }, '0.0.1');
+
+      const agent = await getAgent('OrderSupportAgent');
+
+      expect(agent.writesTo).toEqual([{ id: 'support-notes-db', version: '1.0.0' }]);
+    });
+
+    it('adds the given data store to the agent readsFrom list', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await addDataStoreToAgent('OrderSupportAgent', 'readsFrom', { id: 'orders-db', version: '1.0.0' }, '0.0.1');
+
+      const agent = await getAgent('OrderSupportAgent');
+
+      expect(agent.readsFrom).toEqual([{ id: 'orders-db', version: '1.0.0' }]);
+    });
+
+    it('preserves the versioned agent location when adding a data store to a historical version', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent v1',
+      });
+
+      await versionAgent('OrderSupportAgent');
+
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '1.0.0',
+        markdown: '# Order support agent v2',
+      });
+
+      await addDataStoreToAgent('OrderSupportAgent', 'readsFrom', { id: 'orders-db', version: '1.0.0' }, '0.0.1');
+
+      const versionedAgent = await getAgent('OrderSupportAgent', '0.0.1');
+      const latestAgent = await getAgent('OrderSupportAgent');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent/versioned/0.0.1', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent', 'index.mdx'))).toBe(true);
+      expect(versionedAgent.readsFrom).toEqual([{ id: 'orders-db', version: '1.0.0' }]);
+      expect(latestAgent.version).toBe('1.0.0');
+      expect(latestAgent.readsFrom).toBeUndefined();
+    });
+  });
+
+  describe('addFlowToAgent', () => {
+    it('adds the given flow to the agent', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      await addFlowToAgent('OrderSupportAgent', { id: 'OrderSupportFlow', version: '1.0.0' }, '0.0.1');
+
+      const agent = await getAgent('OrderSupportAgent');
+
+      expect(agent.flows).toEqual([{ id: 'OrderSupportFlow', version: '1.0.0' }]);
+    });
+
+    it('preserves the versioned agent location when adding a flow to a historical version', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent v1',
+      });
+
+      await versionAgent('OrderSupportAgent');
+
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '1.0.0',
+        markdown: '# Order support agent v2',
+      });
+
+      await addFlowToAgent('OrderSupportAgent', { id: 'OrderSupportFlow', version: '1.0.0' }, '0.0.1');
+
+      const versionedAgent = await getAgent('OrderSupportAgent', '0.0.1');
+      const latestAgent = await getAgent('OrderSupportAgent');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent/versioned/0.0.1', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent', 'index.mdx'))).toBe(true);
+      expect(versionedAgent.flows).toEqual([{ id: 'OrderSupportFlow', version: '1.0.0' }]);
+      expect(latestAgent.version).toBe('1.0.0');
+      expect(latestAgent.flows).toBeUndefined();
+    });
+  });
+
+  describe('isAgent', () => {
+    it('returns true if the path is an agent', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      expect(await isAgent(path.join(CATALOG_PATH, 'agents', 'OrderSupportAgent', 'index.mdx'))).toEqual(true);
+    });
+
+    it('returns false if the path is not an agent', async () => {
+      expect(await isAgent('/agents/OrderSupportAgent/index.mdx')).toEqual(false);
+    });
+  });
+
+  describe('toAgent', () => {
+    it('converts a file to an agent', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        markdown: '# Order support agent',
+      });
+
+      const agent = await toAgent(fs.readFileSync(path.join(CATALOG_PATH, 'agents', 'OrderSupportAgent', 'index.mdx'), 'utf8'));
+
+      expect(agent).toEqual(
+        expect.objectContaining({
+          id: 'OrderSupportAgent',
+          name: 'Order Support Agent',
+          version: '0.0.1',
+          markdown: '# Order support agent',
+        })
+      );
+    });
+  });
+});
diff --git a/packages/sdk/src/test/cache-path-normalization.test.ts b/packages/sdk/src/test/cache-path-normalization.test.ts
new file mode 100644
index 000000000..c3afead1b
--- /dev/null
+++ b/packages/sdk/src/test/cache-path-normalization.test.ts
@@ -0,0 +1,50 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import matter from 'gray-matter';
+import path from 'node:path';
+import { cachedMatterRead, disableFileCache, enableFileCache, findFileById, upsertFileCacheEntry } from '../internal/utils';
+
+const ABS_CATALOG_PATH = path.join(__dirname, 'catalog-cache-path-normalization');
+const REL_CATALOG_PATH = path.relative(process.cwd(), ABS_CATALOG_PATH);
+const ABS_RESOURCE_PATH = path.join(ABS_CATALOG_PATH, 'events', 'OrderPlaced', 'index.mdx');
+const REL_RESOURCE_PATH = path.relative(process.cwd(), ABS_RESOURCE_PATH);
+
+const makeDocument = (summary: string, markdown: string) =>
+  matter.stringify(markdown, {
+    id: 'OrderPlaced',
+    name: 'OrderPlaced',
+    version: '1.0.0',
+    summary,
+  });
+
+beforeEach(() => {
+  disableFileCache();
+  fs.rmSync(ABS_CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(ABS_RESOURCE_PATH), { recursive: true });
+});
+
+afterEach(() => {
+  disableFileCache();
+  fs.rmSync(ABS_CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('file cache path normalization', () => {
+  it('updates cached matter when upserting with relative paths', async () => {
+    const initialDocument = makeDocument('Initial summary', '# Initial');
+    fs.writeFileSync(ABS_RESOURCE_PATH, initialDocument);
+
+    enableFileCache(REL_CATALOG_PATH);
+
+    const initialResolvedPath = await findFileById(REL_CATALOG_PATH, 'OrderPlaced', '1.0.0');
+    expect(initialResolvedPath).toBeDefined();
+    expect(cachedMatterRead(initialResolvedPath!).data.summary).toBe('Initial summary');
+
+    const updatedDocument = makeDocument('Updated summary', '# Updated');
+    fs.writeFileSync(ABS_RESOURCE_PATH, updatedDocument);
+    upsertFileCacheEntry(REL_CATALOG_PATH, REL_RESOURCE_PATH, updatedDocument);
+
+    const updatedResolvedPath = await findFileById(REL_CATALOG_PATH, 'OrderPlaced', '1.0.0');
+    expect(updatedResolvedPath).toBeDefined();
+    expect(cachedMatterRead(updatedResolvedPath!).data.summary).toBe('Updated summary');
+  });
+});
diff --git a/packages/sdk/src/test/catalog-eventcatalog/adrs/adr-001-use-transactional-outbox/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/adrs/adr-001-use-transactional-outbox/index.mdx
new file mode 100644
index 000000000..5d817cb2e
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/adrs/adr-001-use-transactional-outbox/index.mdx
@@ -0,0 +1,18 @@
+---
+id: adr-001-use-transactional-outbox
+name: Use Transactional Outbox
+version: 1.0.0
+summary: Publish integration events through an outbox table.
+status: accepted
+date: '2024-01-15'
+decisionMakers:
+  - dboyne
+appliesTo:
+  - id: OrdersService
+    version: 0.0.1
+    type: service
+---
+
+# Use Transactional Outbox
+
+We will publish integration events through an outbox table owned by the service.
diff --git a/packages/sdk/src/test/catalog-eventcatalog/channels/inventory.{env}.events/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/channels/inventory.{env}.events/index.mdx
new file mode 100644
index 000000000..f99bb18e1
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/channels/inventory.{env}.events/index.mdx
@@ -0,0 +1,159 @@
+---
+id: inventory.{env}.events
+name: Inventory Events Channel
+version: 1.0.0
+summary: |
+  Central event stream for all inventory-related events including stock updates, allocations, and adjustments
+owners:
+  - dboyne
+address: inventory.{env}.events
+protocols:
+  - kafka
+
+parameters:
+  env:
+    enum:
+      - dev
+      - sit
+      - prod
+    description: 'Environment to use'
+---
+
+### Overview
+
+The Inventory Events channel is the central stream for all inventory-related events across the system. This includes stock level changes, inventory allocations, adjustments, and stocktake events. Events for a specific SKU are guaranteed to be processed in sequence when using productId as the partition key.
+
+<ChannelInformation />
+
+### Publishing and Subscribing to Events
+
+#### Publishing Example
+
+```python
+from kafka import KafkaProducer
+import json
+from datetime import datetime
+
+# Kafka configuration
+bootstrap_servers = ['localhost:9092']
+topic = f'inventory.{env}.events'
+
+# Create a Kafka producer
+producer = KafkaProducer(
+    bootstrap_servers=bootstrap_servers,
+    value_serializer=lambda v: json.dumps(v).encode('utf-8')
+)
+
+# Example inventory update event
+inventory_event = {
+    "eventType": "STOCK_LEVEL_CHANGED",
+    "timestamp": datetime.utcnow().isoformat(),
+    "version": "1.0",
+    "payload": {
+        "productId": "PROD-456",
+        "locationId": "WH-123",
+        "previousQuantity": 100,
+        "newQuantity": 95,
+        "changeReason": "ORDER_FULFILLED",
+        "unitOfMeasure": "EACH",
+        "batchInfo": {
+            "batchId": "BATCH-789",
+            "expiryDate": "2025-12-31"
+        }
+    },
+    "metadata": {
+        "source": "warehouse_system",
+        "correlationId": "inv-xyz-123",
+        "userId": "john.doe"
+    }
+}
+
+# Send the message - using productId as key for partitioning
+producer.send(
+    topic,
+    key=inventory_event['payload']['productId'].encode('utf-8'),
+    value=inventory_event
+)
+producer.flush()
+
+print(f"Inventory event sent to topic {topic}")
+
+```
+
+### Subscription example
+
+```python
+from kafka import KafkaConsumer
+import json
+from datetime import datetime
+
+class InventoryEventConsumer:
+    def __init__(self):
+        # Kafka configuration
+        self.topic = f'inventory.{env}.events'
+        self.consumer = KafkaConsumer(
+            self.topic,
+            bootstrap_servers=['localhost:9092'],
+            group_id='inventory-processor-group',
+            auto_offset_reset='earliest',
+            enable_auto_commit=False,
+            value_deserializer=lambda x: json.loads(x.decode('utf-8')),
+            key_deserializer=lambda x: x.decode('utf-8') if x else None
+        )
+
+    def process_event(self, event):
+        """Process individual inventory events based on type"""
+        event_type = event.get('eventType')
+
+        if event_type == 'STOCK_LEVEL_CHANGED':
+            self.handle_stock_level_change(event)
+        elif event_type == 'LOW_STOCK_ALERT':
+            self.handle_low_stock_alert(event)
+        # Add more event type handlers as needed
+
+    def handle_stock_level_change(self, event):
+        """Handle stock level change events"""
+        payload = event['payload']
+        print(f"Stock level change detected for product {payload['productId']}")
+        print(f"New quantity: {payload['newQuantity']}")
+        # Add your business logic here
+
+    def handle_low_stock_alert(self, event):
+        """Handle low stock alert events"""
+        payload = event['payload']
+        print(f"Low stock alert for product {payload['productId']}")
+        print(f"Current quantity: {payload['currentQuantity']}")
+        # Add your business logic here
+
+    def start_consuming(self):
+        """Start consuming messages from the topic"""
+        try:
+            print(f"Starting consumption from topic: {self.topic}")
+            for message in self.consumer:
+                try:
+                    # Process the message
+                    event = message.value
+                    print(f"Received event: {event['eventType']} for product: {event['payload']['productId']}")
+
+                    # Process the event
+                    self.process_event(event)
+
+                    # Commit the offset after successful processing
+                    self.consumer.commit()
+
+                except Exception as e:
+                    print(f"Error processing message: {str(e)}")
+                    # Implement your error handling logic here
+                    # You might want to send to a DLQ (Dead Letter Queue)
+
+        except Exception as e:
+            print(f"Consumer error: {str(e)}")
+        finally:
+            # Clean up
+            self.consumer.close()
+
+if __name__ == "__main__":
+    # Create and start the consumer
+    consumer = InventoryEventConsumer()
+    consumer.start_consuming()
+```
diff --git a/packages/sdk/src/test/catalog-eventcatalog/channels/orders.{env}.events/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/channels/orders.{env}.events/index.mdx
new file mode 100644
index 000000000..b4f6d5e06
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/channels/orders.{env}.events/index.mdx
@@ -0,0 +1,84 @@
+---
+id: orders.{env}.events
+name: Order Events Channel
+version: 1.0.1
+summary: |
+  Central event stream for all order-related events in the order processing lifecycle
+owners:
+  - dboyne
+address: orders.{env}.events
+protocols:
+  - kafka
+
+parameters:
+  env:
+    enum:
+      - dev
+      - sit
+      - prod
+    description: 'Environment to use'
+---
+
+### Overview
+
+The Orders Events channel is the central stream for all order-related events across the order processing lifecycle. This includes order creation, updates, payment status, fulfillment status, and customer communications. All events related to a specific order are guaranteed to be processed in sequence when using orderId as the partition key.
+
+<ChannelInformation />
+
+### Publishing a message using Kafka
+
+Here is an example of how to publish an order event using Kafka:
+
+```python
+from kafka import KafkaProducer
+import json
+from datetime import datetime
+
+# Kafka configuration
+bootstrap_servers = ['localhost:9092']
+topic = f'orders.{env}.events'
+
+# Create a Kafka producer
+producer = KafkaProducer(
+    bootstrap_servers=bootstrap_servers,
+    value_serializer=lambda v: json.dumps(v).encode('utf-8')
+)
+
+# Example order created event
+order_event = {
+    "eventType": "ORDER_CREATED",
+    "timestamp": datetime.utcnow().isoformat(),
+    "version": "1.0",
+    "payload": {
+        "orderId": "12345",
+        "customerId": "CUST-789",
+        "items": [
+            {
+                "productId": "PROD-456",
+                "quantity": 2,
+                "price": 29.99
+            }
+        ],
+        "totalAmount": 59.98,
+        "shippingAddress": {
+            "street": "123 Main St",
+            "city": "Springfield",
+            "country": "US"
+        }
+    },
+    "metadata": {
+        "source": "web_checkout",
+        "correlationId": "abc-xyz-123"
+    }
+}
+
+# Send the message - using orderId as key for partitioning
+producer.send(
+    topic,
+    key=order_event['payload']['orderId'].encode('utf-8'),
+    value=order_event
+)
+producer.flush()
+
+print(f"Order event sent to topic {topic}")
+```
diff --git a/packages/sdk/src/test/catalog-eventcatalog/channels/payment.{env}.events/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/channels/payment.{env}.events/index.mdx
new file mode 100644
index 000000000..1d337431d
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/channels/payment.{env}.events/index.mdx
@@ -0,0 +1,89 @@
+---
+id: payments.{env}.events
+name: Payment Events Channel
+version: 1.0.0
+summary: |
+  All events contain payment ID for traceability and ordered processing.
+owners:
+  - dboyne
+address: payments.{env}.events
+protocols:
+  - kafka
+
+parameters:
+  env:
+    enum:
+      - dev
+      - sit
+      - prod
+    description: 'Environment to use for payment events'
+---
+
+### Overview
+
+The Payments Events channel is the central stream for all payment lifecycle events. This includes payment initiation, authorization, capture, completion and failure scenarios. Events for a specific payment are guaranteed to be processed in sequence when using paymentId as the partition key.
+
+<ChannelInformation />
+
+### Publishing Events Using Kafka
+
+Here's an example of publishing a payment event:
+
+```python
+from kafka import KafkaProducer
+import json
+from datetime import datetime
+
+# Kafka configuration
+bootstrap_servers = ['localhost:9092']
+topic = f'payments.{env}.events'
+
+# Create Kafka producer
+producer = KafkaProducer(
+   bootstrap_servers=bootstrap_servers,
+   value_serializer=lambda v: json.dumps(v).encode('utf-8')
+)
+
+# Example payment processed event
+payment_event = {
+   "eventType": "PAYMENT_PROCESSED",
+   "timestamp": datetime.utcnow().isoformat(),
+   "version": "1.0",
+   "payload": {
+       "paymentId": "PAY-123-456",
+       "orderId": "ORD-789",
+       "amount": {
+           "value": 99.99,
+           "currency": "USD"
+       },
+       "status": "SUCCESS",
+       "paymentMethod": {
+           "type": "CREDIT_CARD",
+           "last4": "4242",
+           "expiryMonth": "12",
+           "expiryYear": "2025",
+           "network": "VISA"
+       },
+       "transactionDetails": {
+           "processorId": "stripe_123xyz",
+           "authorizationCode": "AUTH123",
+           "captureId": "CAP456"
+       }
+   },
+   "metadata": {
+       "correlationId": "corr-123-abc",
+       "merchantId": "MERCH-456",
+       "source": "payment_service",
+       "environment": "prod",
+       "idempotencyKey": "PAY-123-456-2024-11-11-99.99"
+   }
+}
+
+# Send message - using paymentId as key for partitioning
+producer.send(
+   topic,
+   key=payment_event['payload']['paymentId'].encode('utf-8'),
+   value=payment_event
+)
+producer.flush()
+```
diff --git a/packages/sdk/src/test/catalog-eventcatalog/containers/inventory-cache/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/containers/inventory-cache/index.mdx
new file mode 100644
index 000000000..9e39298ab
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/containers/inventory-cache/index.mdx
@@ -0,0 +1,12 @@
+---
+id: inventory-cache
+name: Inventory Cache
+version: 1.0.0
+summary: |
+  Redis cache for inventory lookups
+owners:
+  - dboyne
+container_type: cache
+---
+
+The Inventory Cache provides fast inventory lookups using Redis.
diff --git a/packages/sdk/src/test/catalog-eventcatalog/containers/orders-db/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/containers/orders-db/index.mdx
new file mode 100644
index 000000000..fe824f00e
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/containers/orders-db/index.mdx
@@ -0,0 +1,12 @@
+---
+id: orders-db
+name: Orders Database
+version: 1.0.0
+summary: |
+  Primary database for order storage
+owners:
+  - dboyne
+container_type: database
+---
+
+The Orders Database stores all order-related data.
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/changelog.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/changelog.mdx
new file mode 100644
index 000000000..aad6bc002
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/changelog.mdx
@@ -0,0 +1,7 @@
+---
+createdAt: 2024-08-01
+---
+
+### Service added to domain
+
+Added the InventoryService to the domain.
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/index.mdx
new file mode 100644
index 000000000..b223bc71c
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/index.mdx
@@ -0,0 +1,112 @@
+---
+id: Orders
+name: Orders
+version: 0.0.3
+owners:
+  - dboyne
+  - full-stack
+services:
+  - id: InventoryService
+  - id: OrdersService
+  - id: NotificationService
+  - id: ShippingService
+badges:
+  - content: New domain
+    backgroundColor: blue
+    textColor: blue
+    icon: MoonIcon
+
+resourceGroups:
+  - id: related-resources
+    title: Core resources
+    items:
+      - id: InventoryService
+        type: service
+      - id: OrdersService
+        type: service
+      - id: NotificationService
+        type: service
+      - id: ShippingService
+        type: service
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+:::warning
+
+Please ensure all services are **updated** to the latest version for compatibility and performance improvements.
+:::
+
+The Orders domain handles all operations related to customer orders, from creation to fulfillment. This documentation provides an overview of the events and services involved in the Orders domain, helping developers and stakeholders understand the event-driven architecture
+
+<Tiles>
+  <Tile
+    icon="UserGroupIcon"
+    href="/docs/teams/full-stack"
+    title="Contact the team"
+    description="Any questions? Feel free to contact the owners"
+  />
+  <Tile
+    icon="RectangleGroupIcon"
+    href={`/visualiser/domains/${frontmatter.id}/${frontmatter.version}`}
+    title={`${frontmatter.services.length} services are in this domain`}
+    description="This service sends messages to downstream consumers"
+  />
+</Tiles>
+
+## Target architecture for the Orders domain (Event Storming Session)
+
+Result of the event storming session for the Orders domain. This is our target architecture for the domain.
+
+<Miro boardId="uXjVIHCImos=/" moveToWidget="3074457347671667709" edit={false} />
+
+## Current Architecture
+
+This is our current architecture for the Orders domain.
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} showChannels={true} title="Messages in/out of the domain" />
+
+### Order example (sequence diagram)
+
+```mermaid
+sequenceDiagram
+    participant Customer
+    participant OrdersService
+    participant InventoryService
+    participant NotificationService
+
+    Customer->>OrdersService: Place Order
+    OrdersService->>InventoryService: Check Inventory
+    InventoryService-->>OrdersService: Inventory Available
+    OrdersService->>InventoryService: Reserve Inventory
+    OrdersService->>NotificationService: Send Order Confirmation
+    NotificationService-->>Customer: Order Confirmation
+    OrdersService->>Customer: Order Placed Successfully
+    OrdersService->>InventoryService: Update Inventory
+```
+
+## Flows
+
+### Cancel Subscription flow
+
+Documented flow when a user cancels their subscription.
+
+<Flow id="CancelSubscription" version="latest" includeKey={false} />
+
+### Payment processing flow
+
+Documented flow when a user makes a payment within the order domain
+
+<Flow id="PaymentFlow" version="latest" includeKey={false} />
+
+<ResourceGroupTable
+  id="related-resources"
+  limit={4}
+  showOwners={true}
+  title="Core resources for the Orders domain"
+  description="Resources that are related to the Orders domain, you may find them useful"
+/>
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/changelog.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/changelog.mdx
new file mode 100644
index 000000000..7ba14e957
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/changelog.mdx
@@ -0,0 +1,7 @@
+---
+createdAt: 2024-08-01
+---
+
+### Service receives additional events
+
+Service now receives [OrderAmended](/docs/events/OrderAmended/0.0.1) and [UpdateInventory](/docs/commands/UpdateInventory/0.0.3) events.
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/AddInventory/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/AddInventory/index.mdx
new file mode 100644
index 000000000..ea807f895
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/AddInventory/index.mdx
@@ -0,0 +1,50 @@
+---
+id: AddInventory
+name: Add inventory
+version: 0.0.3
+summary: |
+  Command that will add item to a given inventory id
+owners:
+  - dboyne
+  - asmith
+  - full-stack
+  - mobile-devs
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+channels:
+  - id: inventory.{env}.events
+    parameters:
+      env: staging
+schemaPath: 'schema.json'
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The AddInventory command is issued to add new stock to the inventory. This command is used by the inventory management system to update the quantity of products available in the warehouse or store.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Payload example
+
+```json title="Payload example"
+{
+  "productId": "789e1234-b56c-78d9-e012-3456789fghij",
+  "quantity": 50,
+  "warehouseId": "456e7891-c23d-45f6-b78a-123456789abc",
+  "timestamp": "2024-07-04T14:48:00Z"
+}
+```
+
+## Schema
+
+<Schema file="schema.json" />
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/AddInventory/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/AddInventory/schema.json
new file mode 100644
index 000000000..95e009708
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/AddInventory/schema.json
@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AddInventoryCommand",
+  "type": "object",
+  "properties": {
+    "productId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The unique identifier of the product being added to the inventory."
+    },
+    "quantity": {
+      "type": "integer",
+      "description": "The quantity of the product being added to the inventory."
+    },
+    "warehouseId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The unique identifier of the warehouse where the inventory is being added."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The date and time when the inventory was added."
+    }
+  },
+  "required": ["productId", "quantity", "warehouseId", "timestamp"],
+  "additionalProperties": false
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/DeleteInventory/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/DeleteInventory/index.mdx
new file mode 100644
index 000000000..23d28a8d8
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/DeleteInventory/index.mdx
@@ -0,0 +1,36 @@
+---
+id: DeleteInventory
+name: Delete Inventory
+version: 0.0.3
+summary: |
+  Command that will delete a given inventory item from the system
+owners:
+  - dboyne
+  - msmith
+  - asmith
+  - full-stack
+  - mobile-devs
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+channels:
+  - id: inventory.{env}.events
+    parameters:
+      env: staging
+schemaPath: 'schema.json'
+sidebar:
+  badge: 'DELETE'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The DeleteInventory command is issued to remove a product from the inventory system. This command is used by the inventory management system when a product needs to be completely removed from the warehouse or store catalog, typically due to discontinuation or permanent removal of the item.
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/UpdateInventory/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/UpdateInventory/index.mdx
new file mode 100644
index 000000000..276aafd24
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/UpdateInventory/index.mdx
@@ -0,0 +1,53 @@
+---
+id: UpdateInventory
+name: Update inventory
+version: 0.0.3
+summary: |
+  Command that will update a given inventory item
+owners:
+  - dboyne
+  - msmith
+  - asmith
+  - full-stack
+  - mobile-devs
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+channels:
+  - id: inventory.{env}.events
+    parameters:
+      env: staging
+schemaPath: 'schema.json'
+sidebar:
+  badge: 'PUT'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The UpdateInventory command is issued to update the existing stock levels of a product in the inventory. This command is used by the inventory management system to adjust the quantity of products available in the warehouse or store, either by increasing or decreasing the current stock levels.
+
+## Architecture diagram
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Payload example
+
+```json title="Payload example"
+{
+  "productId": "789e1234-b56c-78d9-e012-3456789fghij",
+  "quantityChange": -10,
+  "warehouseId": "456e7891-c23d-45f6-b78a-123456789abc",
+  "timestamp": "2024-07-04T14:48:00Z"
+}
+```
+
+## Schema (JSON schema)
+
+<Schema file="schema.json" />
+
+<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/UpdateInventory/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/UpdateInventory/schema.json
similarity index 100%
rename from examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/commands/UpdateInventory/schema.json
rename to packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/commands/UpdateInventory/schema.json
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/changelog.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/changelog.mdx
new file mode 100644
index 000000000..99807038b
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/changelog.mdx
@@ -0,0 +1,67 @@
+---
+createdAt: 2024-08-01
+badges:
+  - content: ⭐️ JSON Schema
+    backgroundColor: purple
+    textColor: purple
+---
+
+### Added support for JSON Schema
+
+InventoryAdjusted uses Avro but now also supports JSON Draft 7.
+
+```json title="Employee JSON Draft"
+// labeled-line-markers.jsx
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Employee",
+  "properties": {
+    "Name": {
+      "type": "string"
+    },
+    "Age": {
+      "type": "integer"
+    },
+    "Town": {
+      "type": "string"
+    }
+  },
+  "required": ["Name", "Age", "Town"]
+}
+```
+
+Using it with our Kafka Cluster
+
+## 1. Create a new topic
+
+```sh
+# Create a topic named 'employee_topic'
+kafka-topics.sh --create --topic employee_topic --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1
+```
+
+## Step 2: Prepare the JSON Message
+
+Create a JSON file named `employee.json` with the following content:
+
+```json
+{
+  "Name": "John Doe",
+  "Age": 30,
+  "Town": "Springfield"
+}
+```
+
+## Step 3: Produce the Message to Kafka Topic
+
+Use the Kafka producer CLI to send the JSON message:
+
+```sh
+cat employee.json | kafka-console-producer.sh --topic employee_topic --bootstrap-server localhost:9092
+```
+
+## Step 4: Verify the Message (Optional)
+
+```sh
+kafka-console-consumer.sh --topic employee_topic --from-beginning --bootstrap-server localhost:9092
+```
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/index.mdx
new file mode 100644
index 000000000..f4c1b26de
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/index.mdx
@@ -0,0 +1,230 @@
+---
+id: InventoryAdjusted
+name: Inventory adjusted
+version: 1.0.1
+summary: |
+  Indicates a change in inventory level
+owners:
+  - dboyne
+  - msmith
+  - asmith
+  - full-stack
+  - mobile-devs
+channels:
+  - id: inventory.{env}.events
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+  - content: Channel:Apache Kafka
+    backgroundColor: yellow
+    textColor: yellow
+schemaPath: 'schema.avro'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `Inventory Adjusted` event is triggered whenever there is a change in the inventory levels of a product. This could occur due to various reasons such as receiving new stock, sales, returns, or manual adjustments by the inventory management team. The event ensures that all parts of the system that rely on inventory data are kept up-to-date with the latest inventory levels.
+
+<Tiles>
+  <Tile
+    icon="UserGroupIcon"
+    href="/docs/teams/full-stack"
+    title="Contact the team"
+    description="Any questions? Feel free to contact the owners"
+  />
+  <Tile
+    icon="DocumentIcon"
+    href={`/generated/events/Inventory/${frontmatter.id}/schema.avro`}
+    title="View the schema"
+    description="View the schema directly in your browser"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<SchemaViewer file="schema.yml" title="JSON Schema" maxHeight="500" />
+
+## Payload example
+
+Event example you my see being published.
+
+```json title="Payload example"
+{
+  "Name": "John Doe",
+  "Age": 30,
+  "Department": "Engineering",
+  "Position": "Software Engineer",
+  "Salary": 85000.5,
+  "JoinDate": "2024-01-15"
+}
+```
+
+## Schema (avro)
+
+<Schema file="schema.avro" title="Inventory Adjusted Schema (avro)" />
+
+## Producing the Event
+
+Select the language you want to produce the event in to see an example.
+
+<Tabs>
+  <TabItem title="Python">
+
+    ```python title="Produce event in Python" frame="terminal"
+    from kafka import KafkaProducer
+    import json
+    from datetime import datetime
+
+    # Kafka configuration
+    producer = KafkaProducer(
+        bootstrap_servers=['localhost:9092'],
+        value_serializer=lambda v: json.dumps(v).encode('utf-8')
+    )
+
+    # Event data
+    event_data = {
+      "event_id": "abc123",
+      "timestamp": datetime.utcnow().isoformat() + 'Z',
+      "product_id": "prod987",
+      "adjusted_quantity": 10,
+      "new_quantity": 150,
+      "adjustment_reason": "restock",
+      "adjusted_by": "user123"
+    }
+
+    # Send event to Kafka topic
+    producer.send('inventory.adjusted', event_data)
+    producer.flush()
+    ```
+
+  </TabItem>
+  <TabItem title="TypeScript">
+
+    ```typescript title="Produce event in TypeScript" frame="terminal"
+    import { Kafka } from 'kafkajs';
+
+    // Kafka configuration
+    const kafka = new Kafka({
+      clientId: 'inventory-producer',
+      brokers: ['localhost:9092']
+    });
+
+    const producer = kafka.producer();
+
+    // Event data
+    const eventData = {
+      event_id: "abc123",
+      timestamp: new Date().toISOString(),
+      product_id: "prod987",
+      adjusted_quantity: 10,
+      new_quantity: 150,
+      adjustment_reason: "restock",
+      adjusted_by: "user123"
+    };
+
+    // Send event to Kafka topic
+    async function produceEvent() {
+      await producer.connect();
+      await producer.send({
+        topic: 'inventory.adjusted',
+        messages: [
+          { value: JSON.stringify(eventData) }
+        ],
+      });
+      await producer.disconnect();
+    }
+
+    produceEvent().catch(console.error);
+    ```
+
+  </TabItem>
+  <TabItem title="Java">
+
+    ```java title="Produce event in Java" frame="terminal"
+    import org.apache.kafka.clients.producer.*;
+    import org.apache.kafka.common.serialization.StringSerializer;
+    import com.fasterxml.jackson.databind.ObjectMapper;
+    import java.util.Properties;
+    import java.util.HashMap;
+    import java.util.Map;
+    import java.time.Instant;
+
+    public class InventoryProducer {
+        public static void main(String[] args) {
+            // Kafka configuration
+            Properties props = new Properties();
+            props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
+            props.put(ProducerConfig.CLIENT_ID_CONFIG, "inventory-producer");
+            props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
+            props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
+
+            Producer<String, String> producer = new KafkaProducer<>(props);
+            ObjectMapper mapper = new ObjectMapper();
+
+            try {
+                // Event data
+                Map<String, Object> eventData = new HashMap<>();
+                eventData.put("event_id", "abc123");
+                eventData.put("timestamp", Instant.now().toString());
+                eventData.put("product_id", "prod987");
+                eventData.put("adjusted_quantity", 10);
+                eventData.put("new_quantity", 150);
+                eventData.put("adjustment_reason", "restock");
+                eventData.put("adjusted_by", "user123");
+
+                // Create producer record
+                ProducerRecord<String, String> record = new ProducerRecord<>(
+                    "inventory.adjusted",
+                    mapper.writeValueAsString(eventData)
+                );
+
+                // Send event to Kafka topic
+                producer.send(record, (metadata, exception) -> {
+                    if (exception != null) {
+                        System.err.println("Error producing message: " + exception);
+                    }
+                });
+
+            } catch (Exception e) {
+                e.printStackTrace();
+            } finally {
+                producer.flush();
+                producer.close();
+            }
+        }
+    }
+    ```
+
+  </TabItem>
+</Tabs>
+
+### Consuming the Event
+
+To consume an Inventory Adjusted event, use the following example Kafka consumer configuration in Python:
+
+```python title="Consuming the event with python" frame="terminal"
+from kafka import KafkaConsumer
+import json
+
+# Kafka configuration
+consumer = KafkaConsumer(
+    'inventory.adjusted',
+    bootstrap_servers=['localhost:9092'],
+    auto_offset_reset='earliest',
+    enable_auto_commit=True,
+    group_id='inventory_group',
+    value_serializer=lambda v: json.dumps(v).encode('utf-8')
+)
+
+# Consume events
+for message in consumer:
+    event_data = json.loads(message.value)
+    print(f"Received Inventory Adjusted event: {event_data}")
+```
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro
new file mode 100644
index 000000000..82c126ef5
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro
@@ -0,0 +1,13 @@
+{
+  "type" : "record",
+  "namespace" : "Tutorialspoint",
+  "name" : "Employee",
+  "fields" : [
+     { "name" : "Name", "type" : "string" },
+     { "name" : "Age", "type" : "int" },
+     { "name" : "Department", "type" : "string" },
+     { "name" : "Position", "type" : "string" },
+     { "name" : "Salary", "type" : "double" },
+     { "name" : "JoinDate", "type" : "string", "logicalType": "date" }
+  ]
+}
diff --git a/src/__tests__/example-catalog/events/InventoryAdjusted/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.json
similarity index 100%
rename from src/__tests__/example-catalog/events/InventoryAdjusted/schema.json
rename to packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.json
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/schema.yml b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.yml
similarity index 90%
rename from examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/schema.yml
rename to packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.yml
index 6c83aae28..27e251074 100644
--- a/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/schema.yml
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.yml
@@ -24,9 +24,9 @@ properties:
     format: date
     description: The date when the employee joined the company
 required:
-- Name
-- Age
-- Department
-- Position
-- Salary
-- JoinDate
+  - Name
+  - Age
+  - Department
+  - Position
+  - Salary
+  - JoinDate
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/changelog.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/changelog.mdx
new file mode 100644
index 000000000..e07f0df77
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/changelog.mdx
@@ -0,0 +1,26 @@
+---
+createdAt: 2024-07-01
+badges:
+  - content: Breaking change
+    backgroundColor: red
+    textColor: red
+---
+
+### Removed fields from schema, added new owners
+
+`Gender` property has been removed from the Schema of the event
+
+Also added the [full stackers](/docs/teams/full-stack) team as owners of this event
+
+```diff lang="json"
+  {
+    "type" : "record",
+    "namespace" : "Tutorialspoint",
+    "name" : "Employee",
+    "fields" : [
+      { "name" : "Name" , "type" : "string" },
+      { "name" : "Age" , "type" : "int" },
+-     { "name" : "Gender" , "type" : "string" },
+    ]
+  }
+```
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/index.mdx
new file mode 100644
index 000000000..ad2a827cf
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/index.mdx
@@ -0,0 +1,21 @@
+---
+id: InventoryAdjusted
+name: Inventory adjusted
+version: 0.0.1
+summary: |
+  Indicates a change in inventory level
+owners:
+  - dboyne
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+---
+
+:::warning
+When firing this event make sure you set the `correlation-id` in the headers. Our schemas have standard metadata make sure you read and follow it.
+:::
+
+### Details
+
+<NodeGraph />
diff --git a/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/0.0.1/schema.avro b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/schema.avro
similarity index 100%
rename from src/__tests__/example-catalog/events/InventoryAdjusted/versioned/0.0.1/schema.avro
rename to packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/0.0.1/schema.avro
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/changelog.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/changelog.mdx
new file mode 100644
index 000000000..6fca18664
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/changelog.mdx
@@ -0,0 +1,26 @@
+---
+createdAt: 2024-07-11
+badges:
+  - content: New field
+    backgroundColor: green
+    textColor: green
+---
+
+### Added new field to schema
+
+We added the new town property to the schema for downstream consumers.
+
+```json ins={"New: Added new Town property to schema:":9-10}
+// labeled-line-markers.jsx
+{
+  "type": "record",
+  "namespace": "Tutorialspoint",
+  "name": "Employee",
+  "fields": [
+    { "name": "Name", "type": "string" },
+    { "name": "Age", "type": "int" },
+
+    { "name": "Town", "type": "string" }
+  ]
+}
+```
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/index.mdx
new file mode 100644
index 000000000..db2afaa43
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/index.mdx
@@ -0,0 +1,107 @@
+---
+id: InventoryAdjusted
+name: Inventory adjusted
+version: 1.0.0
+summary: |
+  Indicates a change in inventory level
+owners:
+  - dboyne
+  - msmith
+  - asmith
+  - full-stack
+  - mobile-devs
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+  - content: Channel:Apache Kafka
+    backgroundColor: yellow
+    textColor: yellow
+---
+
+## Overview
+
+The `Inventory Adjusted` event is triggered whenever there is a change in the inventory levels of a product. This could occur due to various reasons such as receiving new stock, sales, returns, or manual adjustments by the inventory management team. The event ensures that all parts of the system that rely on inventory data are kept up-to-date with the latest inventory levels.
+
+<NodeGraph />
+
+## Event Details
+
+### Event Name
+
+`inventory.adjusted`
+
+### Description
+
+This event indicates that the inventory count for one or more products has been adjusted. The event carries the updated inventory details including the product ID, the new quantity, and the reason for the adjustment.
+
+### Payload
+
+The payload of the `Inventory Adjusted` event includes the following fields:
+
+```json title="Example of payload" frame="terminal"
+{
+  "event_id": "string",
+  "timestamp": "ISO 8601 date-time",
+  "product_id": "string",
+  "adjusted_quantity": "integer",
+  "new_quantity": "integer",
+  "adjustment_reason": "string",
+  "adjusted_by": "string"
+}
+```
+
+### Producing the Event
+
+To produce an Inventory Adjusted event, use the following example Kafka producer configuration in Python:
+
+```python title="Produce event in Python" frame="terminal"
+from kafka import KafkaProducer
+import json
+from datetime import datetime
+
+# Kafka configuration
+producer = KafkaProducer(
+    bootstrap_servers=['localhost:9092'],
+    value_serializer=lambda v: json.dumps(v).encode('utf-8')
+)
+
+# Event data
+event_data = {
+  "event_id": "abc123",
+  "timestamp": datetime.utcnow().isoformat() + 'Z',
+  "product_id": "prod987",
+  "adjusted_quantity": 10,
+  "new_quantity": 150,
+  "adjustment_reason": "restock",
+  "adjusted_by": "user123"
+}
+
+# Send event to Kafka topic
+producer.send('inventory.adjusted', event_data)
+producer.flush()
+```
+
+### Consuming the Event
+
+To consume an Inventory Adjusted event, use the following example Kafka consumer configuration in Python:
+
+```python title="Consuming the event with python" frame="terminal"
+from kafka import KafkaConsumer
+import json
+
+# Kafka configuration
+consumer = KafkaConsumer(
+    'inventory.adjusted',
+    bootstrap_servers=['localhost:9092'],
+    auto_offset_reset='earliest',
+    enable_auto_commit=True,
+    group_id='inventory_group',
+    value_serializer=lambda v: json.dumps(v).encode('utf-8')
+)
+
+# Consume events
+for message in consumer:
+    event_data = json.loads(message.value)
+    print(f"Received Inventory Adjusted event: {event_data}")
+```
diff --git a/src/__tests__/example-catalog/events/InventoryAdjusted/versioned/1.0.0/schema.avro b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/schema.avro
similarity index 100%
rename from src/__tests__/example-catalog/events/InventoryAdjusted/versioned/1.0.0/schema.avro
rename to packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/InventoryAdjusted/versioned/1.0.0/schema.avro
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/OutOfStock/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/OutOfStock/index.mdx
new file mode 100644
index 000000000..cda07da2e
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/OutOfStock/index.mdx
@@ -0,0 +1,102 @@
+---
+id: OutOfStock
+name: Inventory out of stock
+version: 0.0.4
+summary: |
+  Indicates inventory is out of stock
+owners:
+  - dboyne
+  - msmith
+  - asmith
+  - full-stack
+  - mobile-devs
+channels:
+  - id: inventory.{env}.events
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+  - content: Channel:Apache Kafka
+    backgroundColor: yellow
+    textColor: yellow
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `Inventory Adjusted` event is triggered whenever there is a change in the inventory levels of a product. This could occur due to various reasons such as receiving new stock, sales, returns, or manual adjustments by the inventory management team. The event ensures that all parts of the system that rely on inventory data are kept up-to-date with the latest inventory levels.
+
+<NodeGraph />
+
+### Payload
+
+The payload of the `Inventory Adjusted` event includes the following fields:
+
+```json title="Example of payload" frame="terminal"
+{
+  "event_id": "string",
+  "timestamp": "ISO 8601 date-time",
+  "product_id": "string",
+  "adjusted_quantity": "integer",
+  "new_quantity": "integer",
+  "adjustment_reason": "string"
+}
+```
+
+### Producing the Event
+
+To produce an Inventory Adjusted event, use the following example Kafka producer configuration in Python:
+
+```python title="Produce event in Python" frame="terminal"
+from kafka import KafkaProducer
+import json
+from datetime import datetime
+
+# Kafka configuration
+producer = KafkaProducer(
+    bootstrap_servers=['localhost:9092'],
+    value_serializer=lambda v: json.dumps(v).encode('utf-8')
+)
+
+# Event data
+event_data = {
+  "event_id": "abc123",
+  "timestamp": datetime.utcnow().isoformat() + 'Z',
+  "product_id": "prod987",
+  "adjusted_quantity": 10,
+  "new_quantity": 150,
+  "adjustment_reason": "restock",
+  "adjusted_by": "user123"
+}
+
+# Send event to Kafka topic
+producer.send('inventory.adjusted', event_data)
+producer.flush()
+```
+
+### Consuming the Event
+
+To consume an Inventory Adjusted event, use the following example Kafka consumer configuration in Python:
+
+```python title="Consuming the event with python" frame="terminal"
+from kafka import KafkaConsumer
+import json
+
+# Kafka configuration
+consumer = KafkaConsumer(
+    'inventory.adjusted',
+    bootstrap_servers=['localhost:9092'],
+    auto_offset_reset='earliest',
+    enable_auto_commit=True,
+    group_id='inventory_group',
+    value_serializer=lambda v: json.dumps(v).encode('utf-8')
+)
+
+# Consume events
+for message in consumer:
+    event_data = json.loads(message.value)
+    print(f"Received Inventory Adjusted event: {event_data}")
+```
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/OutOfStock/versioned/0.0.1/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/OutOfStock/versioned/0.0.1/index.mdx
new file mode 100644
index 000000000..4827e090a
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/events/OutOfStock/versioned/0.0.1/index.mdx
@@ -0,0 +1,97 @@
+---
+id: OutOfStock
+name: Inventory out of stock
+version: 0.0.1
+summary: |
+  Indicates inventory is out of stock
+owners:
+  - dboyne
+  - msmith
+  - asmith
+  - full-stack
+  - mobile-devs
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+  - content: Channel:Apache Kafka
+    backgroundColor: yellow
+    textColor: yellow
+---
+
+## Overview
+
+The `Inventory Adjusted` event is triggered whenever there is a change in the inventory levels of a product. This could occur due to various reasons such as receiving new stock, sales, returns, or manual adjustments by the inventory management team. The event ensures that all parts of the system that rely on inventory data are kept up-to-date with the latest inventory levels.
+
+<NodeGraph />
+
+### Payload
+
+The payload of the `Inventory Adjusted` event includes the following fields:
+
+```json title="Example of payload" frame="terminal"
+{
+  "event_id": "string",
+  "timestamp": "ISO 8601 date-time",
+  "product_id": "string",
+  "adjusted_quantity": "integer",
+  "new_quantity": "integer",
+  "adjustment_reason": "string",
+  "adjusted_by": "string"
+}
+```
+
+### Producing the Event
+
+To produce an Inventory Adjusted event, use the following example Kafka producer configuration in Python:
+
+```python title="Produce event in Python" frame="terminal"
+from kafka import KafkaProducer
+import json
+from datetime import datetime
+
+# Kafka configuration
+producer = KafkaProducer(
+    bootstrap_servers=['localhost:9092'],
+    value_serializer=lambda v: json.dumps(v).encode('utf-8')
+)
+
+# Event data
+event_data = {
+  "event_id": "abc123",
+  "timestamp": datetime.utcnow().isoformat() + 'Z',
+  "product_id": "prod987",
+  "adjusted_quantity": 10,
+  "new_quantity": 150,
+  "adjustment_reason": "restock",
+  "adjusted_by": "user123"
+}
+
+# Send event to Kafka topic
+producer.send('inventory.adjusted', event_data)
+producer.flush()
+```
+
+### Consuming the Event
+
+To consume an Inventory Adjusted event, use the following example Kafka consumer configuration in Python:
+
+```python title="Consuming the event with python" frame="terminal"
+from kafka import KafkaConsumer
+import json
+
+# Kafka configuration
+consumer = KafkaConsumer(
+    'inventory.adjusted',
+    bootstrap_servers=['localhost:9092'],
+    auto_offset_reset='earliest',
+    enable_auto_commit=True,
+    group_id='inventory_group',
+    value_serializer=lambda v: json.dumps(v).encode('utf-8')
+)
+
+# Consume events
+for message in consumer:
+    event_data = json.loads(message.value)
+    print(f"Received Inventory Adjusted event: {event_data}")
+```
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/index.mdx
new file mode 100644
index 000000000..1a924c58c
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/index.mdx
@@ -0,0 +1,131 @@
+---
+id: InventoryService
+version: 0.0.2
+name: Inventory Service
+summary: |
+  Service that handles the inventory
+owners:
+  - order-management
+receives:
+  - id: OrderConfirmed
+  - id: GetInventoryList
+  - id: OrderAmended
+  - id: UpdateInventory
+  - id: AddInventory
+  - id: GetInventoryStatus
+  - id: DeleteInventory
+sends:
+  - id: InventoryAdjusted
+  - id: OutOfStock
+  - id: GetOrder
+repository:
+  language: JavaScript
+  url: https://github.com/event-catalog/pretend-shipping-service
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The Inventory Service is a critical component of the system responsible for managing product stock levels, tracking inventory movements, and ensuring product availability. It interacts with other services to maintain accurate inventory records and supports operations such as order fulfillment, restocking, and inventory audits.
+
+<Tiles>
+  <Tile
+    icon="DocumentIcon"
+    href={`/docs/services/${frontmatter.id}/${frontmatter.version}/changelog`}
+    title="View the changelog"
+    description="Want to know the history of this service? View the change logs"
+  />
+  <Tile
+    icon="UserGroupIcon"
+    href="/docs/teams/full-stack"
+    title="Contact the team"
+    description="Any questions? Feel free to contact the owners"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="This service sends messages to downstream consumers"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="This service receives messages from other services"
+  />
+</Tiles>
+
+## Core features
+
+| Feature                  | Description                                                              |
+| ------------------------ | ------------------------------------------------------------------------ |
+| Real-time Stock Tracking | Monitors inventory levels across all warehouses in real-time             |
+| Automated Reordering     | Triggers purchase orders when stock levels fall below defined thresholds |
+| Multi-warehouse Support  | Manages inventory across multiple warehouse locations                    |
+| Batch Processing         | Handles bulk inventory updates and adjustments efficiently               |
+
+## Architecture diagram
+
+<NodeGraph title="Hello world" />
+
+<MessageTable format="all" limit={4} />
+
+# Infrastructure
+
+The Inventory Service is hosted on AWS.
+
+The diagram below shows the infrastructure of the Inventory Service. The service is hosted on AWS and uses AWS Lambda to handle the inventory requests. The inventory is stored in an AWS Aurora database and the inventory metadata is stored in an AWS S3 bucket.
+
+```mermaid
+architecture-beta
+    group api(logos:aws)
+
+    service db(logos:aws-aurora)[Inventory DB] in api
+    service disk1(logos:aws-s3)[Inventory Metadata] in api
+    service server(logos:aws-lambda)[Inventory Handler] in api
+
+    db:L -- R:server
+    disk1:T -- B:server
+```
+
+You can find more information about the Inventory Service infrastructure in the [Inventory Service documentation](https://github.com/event-catalog/pretend-shipping-service/blob/main/README.md).
+
+<Steps title="How to connect to Inventory Service">
+  <Step title="Obtain API credentials">
+    Request API credentials from the Inventory Service team.
+  </Step>
+  <Step title="Install the SDK">
+    Run the following command in your project directory:
+    ```bash
+    npm install inventory-service-sdk
+    ```
+  </Step>
+  <Step title="Initialize the client">
+  Use the following code to initialize the Inventory Service client:
+
+```js
+const InventoryService = require('inventory-service-sdk');
+const client = new InventoryService.Client({
+  clientId: 'YOUR_CLIENT_ID',
+  clientSecret: 'YOUR_CLIENT_SECRET',
+  apiUrl: 'https://api.inventoryservice.com/v1',
+});
+```
+
+  </Step>
+  <Step title="Make API calls">
+  
+  You can now use the client to make API calls. For example, to get all products:
+
+```js
+client
+  .getProducts()
+  .then((products) => console.log(products))
+  .catch((error) => console.error(error));
+```
+
+  </Step>
+</Steps>
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/queries/GetInventoryList/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/queries/GetInventoryList/index.mdx
new file mode 100644
index 000000000..5b1231f88
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/queries/GetInventoryList/index.mdx
@@ -0,0 +1,22 @@
+---
+id: GetInventoryList
+name: List inventory list
+version: 0.0.1
+summary: |
+  GET request that will return inventory list
+owners:
+  - dboyne
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The GetInventoryList message is a query used to retrieve a comprehensive list of all available inventory items within a system. It is designed to return detailed information about each item, such as product names, quantities, availability status, and potentially additional metadata like categories or locations. This query is typically utilized by systems or services that require a real-time view of current stock, ensuring that downstream applications or users have accurate and up-to-date information for decision-making or operational purposes. The GetInventoryList is ideal for use cases such as order processing, stock management, or reporting, providing visibility into the full range of inventory data.
+
+<NodeGraph />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/queries/GetInventoryList/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/queries/GetInventoryList/schema.json
new file mode 100644
index 000000000..6905c7994
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/queries/GetInventoryList/schema.json
@@ -0,0 +1,52 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetInventoryList",
+  "description": "A query to retrieve a list of all available inventory items with their details.",
+  "type": "object",
+  "properties": {
+    "filters": {
+      "type": "object",
+      "description": "Optional filters to narrow down the inventory search.",
+      "properties": {
+        "category": {
+          "type": "string",
+          "description": "Filter items by category (e.g., electronics, clothing, etc.)."
+        },
+        "location": {
+          "type": "string",
+          "description": "Filter items by storage location or warehouse."
+        },
+        "minStockLevel": {
+          "type": "integer",
+          "description": "Filter items with a stock level greater than or equal to this value."
+        },
+        "inStock": {
+          "type": "boolean",
+          "description": "Filter items that are currently in stock (true) or out of stock (false)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "pagination": {
+      "type": "object",
+      "description": "Pagination options for the query.",
+      "properties": {
+        "page": {
+          "type": "integer",
+          "description": "The current page of results.",
+          "minimum": 1,
+          "default": 1
+        },
+        "pageSize": {
+          "type": "integer",
+          "description": "The number of items per page.",
+          "minimum": 1,
+          "default": 10
+        }
+      },
+      "required": ["page", "pageSize"]
+    }
+  },
+  "required": [],
+  "additionalProperties": false
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/queries/GetInventoryStatus/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/queries/GetInventoryStatus/index.mdx
new file mode 100644
index 000000000..7f1f3b9b5
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/queries/GetInventoryStatus/index.mdx
@@ -0,0 +1,40 @@
+---
+id: GetInventoryStatus
+name: Get inventory status
+version: 0.0.1
+summary: |
+  GET request that will return the current stock status for a specific product.
+owners:
+  - dboyne
+badges:
+  - content: GET Request
+    backgroundColor: green
+    textColor: green
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The GetInventoryStatus message is a query designed to retrieve the current stock status for a specific product.
+
+This query provides detailed information about the available quantity, reserved quantity, and the warehouse location where the product is stored. It is typically used by systems or services that need to determine the real-time availability of a product, enabling efficient stock management, order fulfillment, and inventory tracking processes.
+
+This query is essential for ensuring accurate stock levels are reported to downstream systems, including e-commerce platforms, warehouse management systems, and sales channels.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+### Query using CURL
+
+Use this snippet to query the inventory status
+
+```sh title="Example CURL command"
+curl -X GET "https://api.yourdomain.com/inventory/status" \
+-H "Content-Type: application/json" \
+-d '{
+  "productId": "12345"
+}'
+```
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/queries/GetInventoryStatus/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/queries/GetInventoryStatus/schema.json
new file mode 100644
index 000000000..e4710aa06
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/queries/GetInventoryStatus/schema.json
@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetInventoryStatusResponse",
+  "type": "object",
+  "properties": {
+    "productId": {
+      "type": "string",
+      "description": "The unique identifier for the product"
+    },
+    "availableQuantity": {
+      "type": "integer",
+      "description": "The quantity of the product currently available in stock",
+      "minimum": 0
+    },
+    "reservedQuantity": {
+      "type": "integer",
+      "description": "The quantity of the product that is reserved for pending orders",
+      "minimum": 0
+    },
+    "warehouseLocation": {
+      "type": "string",
+      "description": "The location of the warehouse where the product is stored"
+    }
+  },
+  "required": ["productId", "availableQuantity", "reservedQuantity", "warehouseLocation"],
+  "additionalProperties": false
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/versioned/0.0.1/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/versioned/0.0.1/index.mdx
new file mode 100644
index 000000000..939793ed7
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/InventoryService/versioned/0.0.1/index.mdx
@@ -0,0 +1,36 @@
+---
+id: InventoryService
+version: 0.0.1
+name: Inventory Service
+summary: |
+  Service that handles the inventory
+owners:
+  - dboyne
+  - full-stack
+  - mobile-devs
+receives:
+  - id: OrderConfirmed
+    version: 0.0.1
+  - id: OrderCancelled
+    version: 0.0.1
+  - id: OrderAmended
+    version: 0.0.1
+  - id: UpdateInventory
+    version: 0.0.3
+sends:
+  - id: InventoryAdjusted
+    version: 0.0.4
+  - id: OutOfStock
+    version: 0.0.3
+repository:
+  language: JavaScript
+  url: https://github.com/event-catalog/pretend-shipping-service
+---
+
+## Overview
+
+The Inventory Service is a critical component of the system responsible for managing product stock levels, tracking inventory movements, and ensuring product availability. It interacts with other services to maintain accurate inventory records and supports operations such as order fulfillment, restocking, and inventory audits.
+
+## Architecture diagram
+
+<NodeGraph title="Hello world" />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/index.mdx
new file mode 100644
index 000000000..cf1dac04c
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/index.mdx
@@ -0,0 +1,113 @@
+---
+id: NotificationService
+version: 0.0.2
+name: Notifications
+summary: |
+  Service that handles orders
+owners:
+  - order-management
+receives:
+  - id: InventoryAdjusted
+    version: '>1.0.0'
+  - id: PaymentProcessed
+    version: ^1.0.0
+  - id: GetUserNotifications
+    version: x
+  - id: GetNotificationDetails
+    version: x
+sends:
+  - id: OutOfStock
+    version: latest
+  - id: GetInventoryList
+    version: 0.0.x
+repository:
+  language: JavaScript
+  url: https://github.com/event-catalog/pretend-shipping-service
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The Notification Service is responsible for managing and delivering notifications to users and other services. It supports various notification channels such as email, SMS, push notifications, and in-app notifications. The service ensures reliable and timely delivery of messages and integrates with other services to trigger notifications based on specific events.
+
+<Tiles>
+  <Tile
+    icon="DocumentIcon"
+    href={`/docs/services/${frontmatter.id}/${frontmatter.version}/changelog`}
+    title="View the changelog"
+    description="Want to know the history of this service? View the change logs"
+  />
+  <Tile
+    icon="UserGroupIcon"
+    href="/docs/teams/full-stack"
+    title="Contact the team"
+    description="Any questions? Feel free to contact the owners"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="This service sends messages to downstream consumers"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="This service receives messages from other services"
+  />
+</Tiles>
+
+### Core features
+
+| Feature                    | Description                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------ |
+| Multi-Channel Delivery     | Supports notifications via email, SMS, push notifications, and in-app messages |
+| Template Management        | Customizable notification templates with dynamic content placeholders          |
+| Delivery Status Tracking   | Real-time tracking and monitoring of notification delivery status              |
+| Rate Limiting              | Prevents notification flooding through configurable rate limits                |
+| Priority Queue             | Handles urgent notifications with priority delivery mechanisms                 |
+| Batch Processing           | Efficiently processes and sends bulk notifications                             |
+| Retry Mechanism            | Automatic retry logic for failed notification deliveries                       |
+| Event-Driven Notifications | Triggers notifications based on system events and user actions                 |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+## Core Concepts
+
+<AccordionGroup>
+  <Accordion title="Notification">
+    - Description: A message that is sent to a user or a service. - Attributes: notificationId, type, recipient, content, channel,
+    status, timestamp
+  </Accordion>
+  <Accordion title="Channel">
+    - Description: The medium through which the notification is delivered (e.g., email, SMS, push notification). - Attributes:
+    channelId, name, provider, configuration
+  </Accordion>
+</AccordionGroup>
+
+## Infrastructure
+
+The Notification Service is hosted on AWS.
+
+The diagram below shows the infrastructure of the Notification Service. The service is hosted on AWS and uses AWS Lambda to handle the notification requests. The notification is stored in an AWS Aurora database and the notification metadata is stored in an AWS S3 bucket.
+
+```mermaid
+architecture-beta
+    group api(logos:aws)
+
+    service db(logos:aws-aurora)[Notification DB] in api
+    service disk1(logos:aws-s3)[Notification Metadata] in api
+    service server(logos:aws-lambda)[Notification Handler] in api
+
+    db:L -- R:server
+    disk1:T -- B:server
+```
+
+You can find more information about the Notification Service infrastructure in the [Notification Service documentation](https://github.com/event-catalog/pretend-shipping-service/blob/main/README.md).
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/queries/GetNotificationDetails/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/queries/GetNotificationDetails/index.mdx
new file mode 100644
index 000000000..164abec4f
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/queries/GetNotificationDetails/index.mdx
@@ -0,0 +1,28 @@
+---
+id: GetNotificationDetails
+name: Get notification details
+version: 0.0.1
+summary: |
+  GET request that will return detailed information about a specific notification, identified by its notificationId.
+owners:
+  - dboyne
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+schemaPath: schema.json
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `GetNotificationDetails` message is a query used to retrieve detailed information about a specific notification identified by its `notificationId`. It provides a comprehensive overview of the notification, including the title, message content, status (read/unread), the date it was created, and any additional metadata related to the notification, such as associated orders or system events. This query is helpful in scenarios where users or systems need detailed insights into a particular notification, such as retrieving full messages or auditing notifications sent to users.
+
+Use cases include viewing detailed information about order updates, system notifications, or promotional messages, allowing users to view their full notification history and details.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/queries/GetNotificationDetails/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/queries/GetNotificationDetails/schema.json
new file mode 100644
index 000000000..39101953f
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/queries/GetNotificationDetails/schema.json
@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetNotificationDetailsResponse",
+  "type": "object",
+  "properties": {
+    "notificationId": {
+      "type": "string",
+      "description": "The unique identifier for the notification."
+    },
+    "title": {
+      "type": "string",
+      "description": "The title or subject of the notification."
+    },
+    "message": {
+      "type": "string",
+      "description": "The content or message body of the notification."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["unread", "read"],
+      "description": "The read status of the notification."
+    },
+    "userId": {
+      "type": "string",
+      "description": "The unique identifier for the user who received the notification."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The date and time when the notification was created."
+    },
+    "type": {
+      "type": "string",
+      "description": "The type of the notification, such as order or system."
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Additional metadata related to the notification, such as order details.",
+      "properties": {
+        "orderId": {
+          "type": "string",
+          "description": "The associated order ID, if applicable."
+        },
+        "shippingProvider": {
+          "type": "string",
+          "description": "The shipping provider for the associated order, if applicable."
+        }
+      },
+      "required": ["orderId"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["notificationId", "title", "message", "status", "userId", "createdAt", "type"],
+  "additionalProperties": false
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/queries/GetUserNotifications/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/queries/GetUserNotifications/index.mdx
new file mode 100644
index 000000000..a12d64485
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/queries/GetUserNotifications/index.mdx
@@ -0,0 +1,28 @@
+---
+id: GetUserNotifications
+name: Get user notifications
+version: 0.0.1
+summary: |
+  GET request that will return a list of notifications for a specific user, with options to filter by status (unread or all).
+owners:
+  - dboyne
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+schemaPath: schema.json
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `GetUserNotifications` message is a query used to retrieve a list of notifications for a specific user. It allows filtering by notification status, such as unread or all notifications. This query is typically utilized by notification services to display user-specific messages, such as order updates, promotional offers, or system notifications. It supports pagination through `limit` and `offset` parameters, ensuring that only a manageable number of notifications are retrieved at once. This query helps users stay informed about important events or updates related to their account, orders, or the platform.
+
+Use cases include delivering notifications for order updates, promotional campaigns, or general system messages to keep the user informed.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/queries/GetUserNotifications/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/queries/GetUserNotifications/schema.json
new file mode 100644
index 000000000..7e47bd5ff
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/NotificationService/queries/GetUserNotifications/schema.json
@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetUserNotificationsResponse",
+  "type": "object",
+  "properties": {
+    "userId": {
+      "type": "string",
+      "description": "The unique identifier for the user."
+    },
+    "notifications": {
+      "type": "array",
+      "description": "A list of notifications for the user.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "notificationId": {
+            "type": "string",
+            "description": "The unique identifier for the notification."
+          },
+          "title": {
+            "type": "string",
+            "description": "The title or subject of the notification."
+          },
+          "message": {
+            "type": "string",
+            "description": "The message body of the notification."
+          },
+          "status": {
+            "type": "string",
+            "enum": ["unread", "read"],
+            "description": "The read status of the notification."
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "The date and time when the notification was created."
+          }
+        },
+        "required": ["notificationId", "title", "message", "status", "createdAt"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["userId", "notifications"],
+  "additionalProperties": false
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/changelog.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/changelog.mdx
new file mode 100644
index 000000000..a05abc2fe
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/changelog.mdx
@@ -0,0 +1,5 @@
+---
+createdAt: 2024-08-01
+---
+
+This is my entry
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/commands/PlaceOrder/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/commands/PlaceOrder/index.mdx
new file mode 100644
index 000000000..f1d6dd8e7
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/commands/PlaceOrder/index.mdx
@@ -0,0 +1,36 @@
+---
+id: PlaceOrder
+name: Place Order
+version: 0.0.1
+summary: |
+  Command that will place an order
+owners:
+  - dboyne
+  - msmith
+  - asmith
+  - full-stack
+  - mobile-devs
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+schemaPath: 'schema.json'
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The Order Placement Command is a versatile and robust system designed to streamline the process of placing an order. This command takes care of all the essential details needed to complete a purchase, ensuring a smooth and efficient transaction from start to finish.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" />
+
+<Footer />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/commands/PlaceOrder/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/commands/PlaceOrder/schema.json
similarity index 100%
rename from examples/default/domains/E-Commerce/subdomains/Orders/services/OrdersService/commands/PlaceOrder/schema.json
rename to packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/commands/PlaceOrder/schema.json
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderAmended/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderAmended/index.mdx
new file mode 100644
index 000000000..c74023711
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderAmended/index.mdx
@@ -0,0 +1,61 @@
+---
+id: OrderAmended
+name: Order amended
+version: 0.0.1
+summary: |
+  Indicates an order has been changed
+owners:
+  - order-management
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+  - content: Channel:Apache Kafka
+    backgroundColor: yellow
+    textColor: yellow
+schemaPath: schema.avro
+channels:
+  - id: orders.{env}.events
+    parameters:
+      env: staging
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The OrderAmended event is triggered whenever an existing order is modified. This event ensures that all relevant services are notified of changes to an order, such as updates to order items, quantities, shipping information, or status. The event allows the system to maintain consistency and ensure that all dependent services can react appropriately to the amendments.
+
+<NodeGraph />
+
+## Example payload
+
+```json title="Example Payload"
+{
+  "orderId": "123e4567-e89b-12d3-a456-426614174000",
+  "userId": "123e4567-e89b-12d3-a456-426614174000",
+  "amendedItems": [
+    {
+      "productId": "789e1234-b56c-78d9-e012-3456789fghij",
+      "productName": "Example Product",
+      "oldQuantity": 2,
+      "newQuantity": 3,
+      "unitPrice": 29.99,
+      "totalPrice": 89.97
+    }
+  ],
+  "orderStatus": "confirmed",
+  "totalAmount": 150.75,
+  "timestamp": "2024-07-04T14:48:00Z"
+}
+```
+
+## Schema (Avro)s
+
+<Schema file="schema.avro" />
+
+## Schema (JSON)
+
+<Schema file="schema.json" />
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderAmended/schema.avro b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderAmended/schema.avro
new file mode 100644
index 000000000..14ae2ab90
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderAmended/schema.avro
@@ -0,0 +1,75 @@
+{
+  "type": "record",
+  "name": "OrderAmendedEvent",
+  "namespace": "com.example.events",
+  "fields": [
+    {
+      "name": "orderId",
+      "type": "string",
+      "doc": "The unique identifier of the order that was amended."
+    },
+    {
+      "name": "userId",
+      "type": "string",
+      "doc": "The unique identifier of the user who placed the order."
+    },
+    {
+      "name": "amendedItems",
+      "type": {
+        "type": "array",
+        "items": {
+          "type": "record",
+          "name": "AmendedItem",
+          "fields": [
+            {
+              "name": "productId",
+              "type": "string",
+              "doc": "The unique identifier of the product."
+            },
+            {
+              "name": "productName",
+              "type": "string",
+              "doc": "The name of the product."
+            },
+            {
+              "name": "oldQuantity",
+              "type": "int",
+              "doc": "The original quantity of the product ordered."
+            },
+            {
+              "name": "newQuantity",
+              "type": "int",
+              "doc": "The new quantity of the product ordered."
+            },
+            {
+              "name": "unitPrice",
+              "type": "double",
+              "doc": "The price per unit of the product."
+            },
+            {
+              "name": "totalPrice",
+              "type": "double",
+              "doc": "The total price for this order item (newQuantity * unitPrice)."
+            }
+          ]
+        }
+      },
+      "doc": "A list of items that were amended in the order, each containing product details and updated quantities."
+    },
+    {
+      "name": "orderStatus",
+      "type": "string",
+      "doc": "The current status of the order after the amendment."
+    },
+    {
+      "name": "totalAmount",
+      "type": "double",
+      "doc": "The total amount of the order after the amendment."
+    },
+    {
+      "name": "timestamp",
+      "type": "string",
+      "doc": "The date and time when the order was amended, in ISO 8601 format."
+    }
+  ]
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderAmended/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderAmended/schema.json
new file mode 100644
index 000000000..491dccbb9
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderAmended/schema.json
@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderAmendedEvent",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The unique identifier of the order that was amended."
+    },
+    "userId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The unique identifier of the user who placed the order."
+    },
+    "amendedItems": {
+      "type": "array",
+      "description": "A list of items that were amended in the order, each containing product details and updated quantities.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The unique identifier of the product."
+          },
+          "productName": {
+            "type": "string",
+            "description": "The name of the product."
+          },
+          "oldQuantity": {
+            "type": "integer",
+            "description": "The original quantity of the product ordered."
+          },
+          "newQuantity": {
+            "type": "integer",
+            "description": "The new quantity of the product ordered."
+          },
+          "unitPrice": {
+            "type": "number",
+            "format": "float",
+            "description": "The price per unit of the product."
+          },
+          "totalPrice": {
+            "type": "number",
+            "format": "float",
+            "description": "The total price for this order item (newQuantity * unitPrice)."
+          }
+        },
+        "required": ["productId", "productName", "oldQuantity", "newQuantity", "unitPrice", "totalPrice"]
+      }
+    },
+    "orderStatus": {
+      "type": "string",
+      "description": "The current status of the order after the amendment."
+    },
+    "totalAmount": {
+      "type": "number",
+      "format": "float",
+      "description": "The total amount of the order after the amendment."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The date and time when the order was amended, in ISO 8601 format."
+    }
+  },
+  "required": ["orderId", "userId", "amendedItems", "orderStatus", "totalAmount", "timestamp"],
+  "additionalProperties": false
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderCancelled/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderCancelled/index.mdx
new file mode 100644
index 000000000..35cf9d571
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderCancelled/index.mdx
@@ -0,0 +1,55 @@
+---
+id: OrderCancelled
+name: Order cancelled
+version: 0.0.1
+summary: |
+  Indicates an order has been canceled
+owners:
+  - order-management
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+  - content: Channel:Apache Kafka
+    backgroundColor: yellow
+    textColor: yellow
+schemaPath: 'schema.json'
+channels:
+  - id: orders.{env}.events
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The OrderCancelled event is triggered whenever an existing order is cancelled. This event ensures that all relevant services are notified of the cancellation, allowing them to take appropriate actions such as updating inventory levels, refunding payments, and notifying the user. The event helps maintain consistency across the system by ensuring all dependent services are aware of the order cancellation.
+
+## Example payload
+
+```json title="Example payload"
+{
+  "orderId": "123e4567-e89b-12d3-a456-426614174000",
+  "userId": "123e4567-e89b-12d3-a456-426614174000",
+  "orderItems": [
+    {
+      "productId": "789e1234-b56c-78d9-e012-3456789fghij",
+      "productName": "Example Product",
+      "quantity": 2,
+      "unitPrice": 29.99,
+      "totalPrice": 59.98
+    }
+  ],
+  "orderStatus": "cancelled",
+  "totalAmount": 59.98,
+  "cancellationReason": "Customer requested cancellation",
+  "timestamp": "2024-07-04T14:48:00Z"
+}
+```
+
+## Schema
+
+JSON schema for the event.
+
+<Schema title="JSON Schema" file="schema.json" />
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderCancelled/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderCancelled/schema.json
new file mode 100644
index 000000000..b741b11ad
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderCancelled/schema.json
@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderCancelledEvent",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The unique identifier of the order that was cancelled."
+    },
+    "userId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The unique identifier of the user who placed the order."
+    },
+    "orderItems": {
+      "type": "array",
+      "description": "A list of items included in the cancelled order, each containing product details and quantities.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The unique identifier of the product."
+          },
+          "productName": {
+            "type": "string",
+            "description": "The name of the product."
+          },
+          "quantity": {
+            "type": "integer",
+            "description": "The quantity of the product ordered."
+          },
+          "unitPrice": {
+            "type": "number",
+            "format": "float",
+            "description": "The price per unit of the product."
+          },
+          "totalPrice": {
+            "type": "number",
+            "format": "float",
+            "description": "The total price for this order item (quantity * unit price)."
+          }
+        },
+        "required": ["productId", "productName", "quantity", "unitPrice", "totalPrice"]
+      }
+    },
+    "orderStatus": {
+      "type": "string",
+      "description": "The current status of the order after cancellation.",
+      "enum": ["cancelled"]
+    },
+    "totalAmount": {
+      "type": "number",
+      "format": "float",
+      "description": "The total amount of the order that was cancelled."
+    },
+    "cancellationReason": {
+      "type": "string",
+      "description": "The reason for the order cancellation, if provided."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The date and time when the order was cancelled."
+    }
+  },
+  "required": ["orderId", "userId", "orderItems", "orderStatus", "totalAmount", "timestamp"],
+  "additionalProperties": false
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderConfirmed/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderConfirmed/index.mdx
new file mode 100644
index 000000000..201cc7415
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderConfirmed/index.mdx
@@ -0,0 +1,56 @@
+---
+id: OrderConfirmed
+name: Order confirmed
+version: 0.0.1
+summary: |
+  Indicates an order has been confirmed
+owners:
+  - order-management
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+  - content: Channel:Apache Kafka
+    backgroundColor: yellow
+    textColor: yellow
+schemaPath: schema.json
+channels:
+  - id: orders.{env}.events
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The OrderConfirmed event is triggered when an order has been successfully confirmed. This event notifies relevant services that the order is ready for further processing, such as inventory adjustment, payment finalization, and preparation for shipping.
+
+## Architecture Diagram
+
+<NodeGraph />
+
+## Payload
+
+```json title="Example payload"
+{
+  "orderId": "123e4567-e89b-12d3-a456-426614174000",
+  "userId": "123e4567-e89b-12d3-a456-426614174000",
+  "orderItems": [
+    {
+      "productId": "789e1234-b56c-78d9-e012-3456789fghij",
+      "productName": "Example Product",
+      "quantity": 2,
+      "unitPrice": 29.99,
+      "totalPrice": 59.98
+    }
+  ],
+  "orderStatus": "confirmed",
+  "totalAmount": 150.75,
+  "confirmationTimestamp": "2024-07-04T14:48:00Z"
+}
+```
+
+## Schema
+
+<Schema file="schema.json" />
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderConfirmed/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderConfirmed/schema.json
new file mode 100644
index 000000000..f5a89e1bf
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/events/OrderConfirmed/schema.json
@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderConfirmedEvent",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The unique identifier of the confirmed order."
+    },
+    "userId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The unique identifier of the user who placed the order."
+    },
+    "orderItems": {
+      "type": "array",
+      "description": "A list of items included in the confirmed order, each containing product details and quantities.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The unique identifier of the product."
+          },
+          "productName": {
+            "type": "string",
+            "description": "The name of the product."
+          },
+          "quantity": {
+            "type": "integer",
+            "description": "The quantity of the product ordered."
+          },
+          "unitPrice": {
+            "type": "number",
+            "format": "float",
+            "description": "The price per unit of the product."
+          },
+          "totalPrice": {
+            "type": "number",
+            "format": "float",
+            "description": "The total price for this order item (quantity * unitPrice)."
+          }
+        },
+        "required": ["productId", "productName", "quantity", "unitPrice", "totalPrice"]
+      }
+    },
+    "orderStatus": {
+      "type": "string",
+      "description": "The current status of the order after confirmation."
+    },
+    "totalAmount": {
+      "type": "number",
+      "format": "float",
+      "description": "The total amount of the confirmed order."
+    },
+    "confirmationTimestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The date and time when the order was confirmed."
+    }
+  },
+  "required": ["orderId", "userId", "orderItems", "orderStatus", "totalAmount", "confirmationTimestamp"],
+  "additionalProperties": false
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/index.mdx
new file mode 100644
index 000000000..b25f49287
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/index.mdx
@@ -0,0 +1,98 @@
+---
+id: OrdersService
+version: 0.0.3
+name: Orders Service
+summary: |
+  Service that handles orders
+owners:
+  - order-management
+receives:
+  - id: InventoryAdjusted
+    version: 0.0.3
+  - id: GetOrder
+  - id: PlaceOrder
+  - id: UserSubscriptionCancelled
+sends:
+  - id: OrderAmended
+  - id: OrderCancelled
+  - id: OrderConfirmed
+  - id: AddInventory
+    version: 0.0.3
+repository:
+  language: JavaScript
+  url: https://github.com/event-catalog/pretend-shipping-service
+schemaPath: 'openapi.yml'
+specifications:
+  asyncapiPath: order-service-asyncapi.yaml
+  openapiPath: openapi.yml
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The Orders Service is responsible for managing customer orders within the system. It handles order creation, updating, status tracking, and interactions with other services such as Inventory, Payment, and Notification services to ensure smooth order processing and fulfillment.
+
+<Tiles>
+  <Tile
+    icon="DocumentIcon"
+    href={`/docs/services/${frontmatter.id}/${frontmatter.version}/changelog`}
+    title="View the changelog"
+    description="Want to know the history of this service? View the change logs"
+  />
+  <Tile
+    icon="UserGroupIcon"
+    href="/docs/teams/full-stack"
+    title="Contact the team"
+    description="Any questions? Feel free to contact the owners"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="This service sends messages to downstream consumers"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="This service receives messages from other services"
+  />
+</Tiles>
+
+### Core features
+
+| Feature                  | Description                                                     |
+| ------------------------ | --------------------------------------------------------------- |
+| Order Management         | Handles order creation, updates, and status tracking            |
+| Inventory Integration    | Validates and processes inventory for incoming orders           |
+| Payment Processing       | Integrates with payment gateways to handle payment transactions |
+| Notification Integration | Sends notifications to users and other services                 |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+## Infrastructure
+
+The Orders Service is hosted on AWS.
+
+The diagram below shows the infrastructure of the Orders Service. The service is hosted on AWS and uses AWS Lambda to handle the order requests. The order is stored in an AWS Aurora database and the order metadata is stored in an AWS S3 bucket.
+
+```mermaid
+architecture-beta
+    group api(logos:aws)
+
+    service db(logos:aws-aurora)[Order DB] in api
+    service disk1(logos:aws-s3)[Order Metadata] in api
+    service server(logos:aws-lambda)[Order Handler] in api
+
+    db:L -- R:server
+    disk1:T -- B:server
+```
+
+You can find more information about the Orders Service infrastructure in the [Orders Service documentation](https://github.com/event-catalog/pretend-shipping-service/blob/main/README.md).
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/openapi.yml b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/openapi.yml
new file mode 100644
index 000000000..f1d671b58
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/openapi.yml
@@ -0,0 +1,290 @@
+openapi: 3.0.3
+info:
+  title: Orders Service API
+  description: API for managing customer orders
+  version: 1.0.0
+
+servers:
+  - url: https://api.example.com/v1
+    description: Production server
+  - url: https://staging-api.example.com/v1
+    description: Staging server
+
+paths:
+  /orders:
+    get:
+      summary: List all orders
+      description: Retrieve a list of orders with optional filtering
+      parameters:
+        - name: status
+          in: query
+          description: Filter orders by status
+          schema:
+            type: string
+            enum: [pending, processing, completed, cancelled]
+        - name: customerId
+          in: query
+          description: Filter orders by customer ID
+          schema:
+            type: string
+        - name: page
+          in: query
+          description: Page number for pagination
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - name: limit
+          in: query
+          description: Number of items per page
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        '200':
+          description: Successfully retrieved orders
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderList'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+    post:
+      summary: Create a new order
+      description: Create a new order for a customer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderCreate'
+      responses:
+        '201':
+          description: Order created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+  /orders/{orderId}:
+    get:
+      summary: Get order by ID
+      description: Retrieve detailed information about a specific order
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          description: Unique identifier of the order
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Order found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+    patch:
+      summary: Update order status
+      description: Update the status of an existing order
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          description: Unique identifier of the order
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OrderUpdate'
+      responses:
+        '200':
+          description: Order updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+components:
+  schemas:
+    OrderCreate:
+      type: object
+      required:
+        - customerId
+        - items
+      properties:
+        customerId:
+          type: string
+          description: Unique identifier of the customer
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/OrderItem'
+        shippingAddress:
+          $ref: '#/components/schemas/Address'
+        billingAddress:
+          $ref: '#/components/schemas/Address'
+
+    OrderUpdate:
+      type: object
+      required:
+        - status
+      properties:
+        status:
+          type: string
+          enum: [pending, processing, completed, cancelled]
+          description: New status of the order
+
+    Order:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Unique identifier of the order
+        customerId:
+          type: string
+          description: Unique identifier of the customer
+        status:
+          type: string
+          enum: [pending, processing, completed, cancelled]
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/OrderItem'
+        totalAmount:
+          type: number
+          format: float
+        shippingAddress:
+          $ref: '#/components/schemas/Address'
+        billingAddress:
+          $ref: '#/components/schemas/Address'
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+
+    OrderList:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/Order'
+        pagination:
+          $ref: '#/components/schemas/Pagination'
+
+    OrderItem:
+      type: object
+      required:
+        - productId
+        - quantity
+      properties:
+        productId:
+          type: string
+        quantity:
+          type: integer
+          minimum: 1
+        price:
+          type: number
+          format: float
+        name:
+          type: string
+
+    Address:
+      type: object
+      required:
+        - street
+        - city
+        - country
+        - postalCode
+      properties:
+        street:
+          type: string
+        city:
+          type: string
+        state:
+          type: string
+        country:
+          type: string
+        postalCode:
+          type: string
+
+    Pagination:
+      type: object
+      properties:
+        totalItems:
+          type: integer
+        totalPages:
+          type: integer
+        currentPage:
+          type: integer
+        itemsPerPage:
+          type: integer
+
+    Error:
+      type: object
+      properties:
+        code:
+          type: string
+        message:
+          type: string
+        details:
+          type: array
+          items:
+            type: string
+
+  responses:
+    BadRequest:
+      description: Invalid request
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+
+    Unauthorized:
+      description: Authentication required
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - BearerAuth: []
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/order-service-asyncapi.yaml b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/order-service-asyncapi.yaml
new file mode 100644
index 000000000..7b1f8093a
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/order-service-asyncapi.yaml
@@ -0,0 +1,148 @@
+asyncapi: 3.0.0
+
+info:
+  title: Order service
+  description: |
+    This service is in charge of processing order events.
+  version: '1.0.0'
+
+servers:
+  topic:
+    host: https://mytopic.com
+    description: Custom Topic.
+    protocol: HTTPS
+
+defaultContentType: application/json
+
+channels:
+  orderEventsChannel:
+    address: 'orders.{orderId}'
+    description: All Order related events are distributed and broadcasted for the interested consumers.
+    title: Order events channel
+    messages:
+      OrderConfirmed:
+        summary: Order confirmed event
+        $ref: '#/components/messages/OrderConfirmed'
+      OrderPlaced:
+        summary: Order placed event
+        $ref: '#/components/messages/OrderPlaced'
+
+operations:
+  onOrderConfirmation:
+    summary: Action to confirm an order.
+    description: The product availability of an order will lead to the confirmation of the order.
+    title: Order Confirmed
+    channel:
+      $ref: '#/channels/orderEventsChannel'
+    action: send
+  onOrderPlacement:
+    summary: Action to place an order.
+    description: The reception and validation of an order will lead to the placement of the order.
+    title: Order Placed
+    channel:
+      $ref: '#/channels/orderEventsChannel'
+    action: send
+
+components:
+  messages:
+    OrderConfirmed:
+      payload:
+        $ref: '#/components/schemas/OrderConfirmed'
+
+    OrderPlaced:
+      payload:
+        $ref: '#/components/schemas/OrderPlaced'
+
+  schemas:
+    orderId:
+      description: The unique identifier of an order
+      type: string
+      pattern: ^([A-Za-z0-9_-]{21})$
+
+    userId:
+      description: The unique identifier of a user
+      type: string
+      pattern: ^([A-Za-z0-9_-]{21})$
+
+    productId:
+      description: The product unique identifier
+      type: string
+      pattern: ^([A-Za-z0-9_-]{21})$
+
+    Order:
+      required:
+        - orderId
+        - userId
+        - productId
+        - price
+        - quantity
+        - orderDate
+      type: object
+      description: order model
+      properties:
+        orderId:
+          '$ref': '#/components/schemas/orderId'
+        orderDate:
+          description: Date of order submition.
+          type: string
+          format: date-time
+        userId:
+          '$ref': '#/components/schemas/userId'
+        productId:
+          '$ref': '#/components/schemas/productId'
+        price:
+          type: number
+        quantity:
+          type: integer
+      title: Order
+
+    EventEnvelope:
+      type: object
+      allOf:
+        - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/v1.0.1/spec.json'
+      properties:
+        id:
+          type: string
+          format: uuid
+        idempotencykey:
+          type: string
+          format: uuid
+        correlationid:
+          type: string
+          format: uuid
+        causationid:
+          type: string
+          format: uuid
+
+    EventType:
+      type: string
+      enum:
+        - 'order.placed'
+        - 'order.confirmed'
+
+    OrderConfirmed:
+      type: object
+      additionalProperties: false
+      allOf:
+        - $ref: '#/components/schemas/EventEnvelope'
+      properties:
+        data:
+          $ref: '#/components/schemas/Order'
+        type:
+          $ref: '#/components/schemas/EventType'
+
+      required:
+        - data
+
+    OrderPlaced:
+      type: object
+      additionalProperties: false
+      allOf:
+        - $ref: '#/components/schemas/EventEnvelope'
+      properties:
+        data:
+          $ref: '#/components/schemas/Order'
+        type:
+          $ref: '#/components/schemas/EventType'
+      required:
+        - data
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/queries/GetOrder/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/queries/GetOrder/index.mdx
new file mode 100644
index 000000000..91fd71cdd
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/queries/GetOrder/index.mdx
@@ -0,0 +1,28 @@
+---
+id: GetOrder
+name: Get order details
+version: 0.0.1
+summary: |
+  GET request that will return detailed information about a specific order, identified by its orderId.
+owners:
+  - order-management
+badges:
+  - content: Recently updated!
+    backgroundColor: green
+    textColor: green
+schemaPath: schema.json
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `GetOrder` message is a query used to retrieve detailed information about a specific order, identified by its `orderId`. It provides information such as the order status (e.g., pending, completed, shipped), the items within the order, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
+
+This query can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time order data for tracking, auditing, or managing customer purchases.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/queries/GetOrder/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/queries/GetOrder/schema.json
new file mode 100644
index 000000000..efd24d62d
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/queries/GetOrder/schema.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetOrderQuery",
+  "type": "object",
+  "properties": {
+    "orderId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The unique identifier of the order being retrieved."
+    }
+  },
+  "required": ["orderId"],
+  "additionalProperties": false
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/versioned/0.0.2/changelog.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/versioned/0.0.2/changelog.mdx
new file mode 100644
index 000000000..f100b8684
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/versioned/0.0.2/changelog.mdx
@@ -0,0 +1,5 @@
+---
+createdAt: 2024-08-01
+---
+
+Something changed
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/versioned/0.0.2/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/versioned/0.0.2/index.mdx
new file mode 100644
index 000000000..c847c9f81
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/versioned/0.0.2/index.mdx
@@ -0,0 +1,34 @@
+---
+id: OrdersService
+version: 0.0.2
+name: Orders Service
+summary: |
+  Service that handles orders
+owners:
+  - dboyne
+receives:
+  - id: InventoryAdjusted
+    version: 0.0.3
+sends:
+  - id: AddInventory
+    version: 0.0.3
+repository:
+  language: JavaScript
+  url: https://github.com/event-catalog/pretend-shipping-service
+schemaPath: 'openapi.yml'
+specifications:
+  asyncapiPath: order-service-asyncapi.yaml
+  openapiPath: openapi.yml
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The Orders Service is responsible for managing customer orders within the system. It handles order creation, updating, status tracking, and interactions with other services such as Inventory, Payment, and Notification services to ensure smooth order processing and fulfillment.
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/versioned/0.0.2/openapi.yml b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/versioned/0.0.2/openapi.yml
new file mode 100644
index 000000000..3cb06f73f
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/versioned/0.0.2/openapi.yml
@@ -0,0 +1,96 @@
+openapi: 3.1.0
+info:
+  title: Simple Task - API
+  version: 1.0.0
+  description: Simple Api
+  contact: {}
+  license:
+    name: apache 2.0
+    identifier: apache-2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+
+servers:
+  - url: https://example.com/
+
+paths:
+  /v1/task/{id}:
+    put:
+      summary: Do Simple Task
+      operationId: DoSimpleTask
+      responses:
+        '200':
+          description: do a task by id
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '204':
+          description: No content
+        '400':
+          description: Problem with data
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '403':
+          description: Not Authorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Unauthorized'
+        '404':
+          description: not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+      description: Allows to do a simple task
+      security:
+        - authorization: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+
+components:
+  schemas:
+    Task:
+      properties:
+        comments:
+          type: string
+        creationDate:
+          type: string
+        taskId:
+          type: string
+        description:
+          type: string
+        lastUpdate:
+          type: string
+      type: object
+      additionalProperties: false
+    Error:
+      properties:
+        error:
+          type: string
+      required:
+        - error
+      type: object
+    Unauthorized:
+      properties:
+        message:
+          type: string
+      required:
+        - message
+      type: object
+  securitySchemes:
+    authorization:
+      type: http
+      scheme: bearer
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/versioned/0.0.2/order-service-asyncapi.yaml b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/versioned/0.0.2/order-service-asyncapi.yaml
new file mode 100644
index 000000000..7b1f8093a
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/OrdersService/versioned/0.0.2/order-service-asyncapi.yaml
@@ -0,0 +1,148 @@
+asyncapi: 3.0.0
+
+info:
+  title: Order service
+  description: |
+    This service is in charge of processing order events.
+  version: '1.0.0'
+
+servers:
+  topic:
+    host: https://mytopic.com
+    description: Custom Topic.
+    protocol: HTTPS
+
+defaultContentType: application/json
+
+channels:
+  orderEventsChannel:
+    address: 'orders.{orderId}'
+    description: All Order related events are distributed and broadcasted for the interested consumers.
+    title: Order events channel
+    messages:
+      OrderConfirmed:
+        summary: Order confirmed event
+        $ref: '#/components/messages/OrderConfirmed'
+      OrderPlaced:
+        summary: Order placed event
+        $ref: '#/components/messages/OrderPlaced'
+
+operations:
+  onOrderConfirmation:
+    summary: Action to confirm an order.
+    description: The product availability of an order will lead to the confirmation of the order.
+    title: Order Confirmed
+    channel:
+      $ref: '#/channels/orderEventsChannel'
+    action: send
+  onOrderPlacement:
+    summary: Action to place an order.
+    description: The reception and validation of an order will lead to the placement of the order.
+    title: Order Placed
+    channel:
+      $ref: '#/channels/orderEventsChannel'
+    action: send
+
+components:
+  messages:
+    OrderConfirmed:
+      payload:
+        $ref: '#/components/schemas/OrderConfirmed'
+
+    OrderPlaced:
+      payload:
+        $ref: '#/components/schemas/OrderPlaced'
+
+  schemas:
+    orderId:
+      description: The unique identifier of an order
+      type: string
+      pattern: ^([A-Za-z0-9_-]{21})$
+
+    userId:
+      description: The unique identifier of a user
+      type: string
+      pattern: ^([A-Za-z0-9_-]{21})$
+
+    productId:
+      description: The product unique identifier
+      type: string
+      pattern: ^([A-Za-z0-9_-]{21})$
+
+    Order:
+      required:
+        - orderId
+        - userId
+        - productId
+        - price
+        - quantity
+        - orderDate
+      type: object
+      description: order model
+      properties:
+        orderId:
+          '$ref': '#/components/schemas/orderId'
+        orderDate:
+          description: Date of order submition.
+          type: string
+          format: date-time
+        userId:
+          '$ref': '#/components/schemas/userId'
+        productId:
+          '$ref': '#/components/schemas/productId'
+        price:
+          type: number
+        quantity:
+          type: integer
+      title: Order
+
+    EventEnvelope:
+      type: object
+      allOf:
+        - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/v1.0.1/spec.json'
+      properties:
+        id:
+          type: string
+          format: uuid
+        idempotencykey:
+          type: string
+          format: uuid
+        correlationid:
+          type: string
+          format: uuid
+        causationid:
+          type: string
+          format: uuid
+
+    EventType:
+      type: string
+      enum:
+        - 'order.placed'
+        - 'order.confirmed'
+
+    OrderConfirmed:
+      type: object
+      additionalProperties: false
+      allOf:
+        - $ref: '#/components/schemas/EventEnvelope'
+      properties:
+        data:
+          $ref: '#/components/schemas/Order'
+        type:
+          $ref: '#/components/schemas/EventType'
+
+      required:
+        - data
+
+    OrderPlaced:
+      type: object
+      additionalProperties: false
+      allOf:
+        - $ref: '#/components/schemas/EventEnvelope'
+      properties:
+        data:
+          $ref: '#/components/schemas/Order'
+        type:
+          $ref: '#/components/schemas/EventType'
+      required:
+        - data
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CancelShipment/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CancelShipment/index.mdx
new file mode 100644
index 000000000..a1d5e4eac
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CancelShipment/index.mdx
@@ -0,0 +1,24 @@
+---
+id: CancelShipment
+name: Cancel shipment
+version: 0.0.1
+summary: |
+  POST request that will cancel a shipment, identified by its shipmentId.
+owners:
+  - dboyne
+schemaPath: schema.json
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `CancelShipment` message is a command used to cancel a shipment, identified by its `shipmentId`. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
+
+This command can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
+
+<SchemaViewer file="schema.json" title="Schema" maxHeight="500" />
+
+<NodeGraph />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CancelShipment/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CancelShipment/schema.json
new file mode 100644
index 000000000..990a7b3ca
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CancelShipment/schema.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "CancelShipment",
+  "description": "Schema for cancelling a shipment",
+  "properties": {
+    "shipmentId": {
+      "type": "string",
+      "description": "Unique identifier for the shipment"
+    }
+  },
+  "required": ["shipmentId"]
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CreateReturnLabel/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CreateReturnLabel/index.mdx
new file mode 100644
index 000000000..084a66293
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CreateReturnLabel/index.mdx
@@ -0,0 +1,24 @@
+---
+id: CreateReturnLabel
+name: Create return label
+version: 0.0.1
+summary: |
+  POST request that will create a return label for a specific shipment, identified by its shipmentId.
+owners:
+  - dboyne
+schemaPath: schema.json
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `CreateReturnLabel` message is a command used to create a return label for a specific shipment, identified by its `shipmentId`. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
+
+This command can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CreateReturnLabel/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CreateReturnLabel/schema.json
new file mode 100644
index 000000000..9bb871ea6
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CreateReturnLabel/schema.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "CreateReturnLabel",
+  "description": "Schema for creating a return shipping label",
+  "properties": {
+    "CreateReturnLabel": {
+      "type": "object",
+      "properties": {
+        "shipmentId": {
+          "type": "string",
+          "description": "Unique identifier for the shipment"
+        }
+      },
+      "required": ["shipmentId"]
+    }
+  },
+  "required": ["CreateReturnLabel"]
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CreateShipment/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CreateShipment/index.mdx
new file mode 100644
index 000000000..4fec73783
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CreateShipment/index.mdx
@@ -0,0 +1,24 @@
+---
+id: CreateShipment
+name: Create shipment
+version: 0.0.1
+summary: |
+  POST request that will create a shipment for a specific order, identified by its orderId.
+owners:
+  - dboyne
+schemaPath: schema.json
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `CreateShipment` message is a command used to create a shipment for a specific order, identified by its `orderId`. It provides information such as the order status (e.g., pending, completed, shipped), the items within the order, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
+
+This command can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time order data for tracking, auditing, or managing customer purchases.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CreateShipment/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CreateShipment/schema.json
similarity index 100%
rename from examples/default/domains/E-Commerce/subdomains/Orders/services/ShippingService/commands/CreateShipment/schema.json
rename to packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/CreateShipment/schema.json
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/UpdateShipmentStatus/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/UpdateShipmentStatus/index.mdx
new file mode 100644
index 000000000..96f220536
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/UpdateShipmentStatus/index.mdx
@@ -0,0 +1,24 @@
+---
+id: UpdateShipmentStatus
+name: Update shipment status
+version: 0.0.1
+summary: |
+  POST request that will update the status of a shipment, identified by its shipmentId.
+owners:
+  - dboyne
+schemaPath: schema.json
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `UpdateShipmentStatus` message is a command used to update the status of a shipment, identified by its `shipmentId`. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
+
+This command can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/UpdateShipmentStatus/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/UpdateShipmentStatus/schema.json
new file mode 100644
index 000000000..7bd61c943
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/commands/UpdateShipmentStatus/schema.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "UpdateShipmentStatus",
+  "description": "Schema for updating a shipment's status",
+  "properties": {
+    "UpdateShipmentStatus": {
+      "type": "object",
+      "properties": {
+        "shipmentId": {
+          "type": "string",
+          "description": "Unique identifier for the shipment"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "shipped", "delivered", "returned"],
+          "description": "Current status of the shipment"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Timestamp when the status was last updated"
+        }
+      },
+      "required": ["shipmentId", "status"]
+    }
+  },
+  "required": ["UpdateShipmentStatus"]
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/DeliveryFailed/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/DeliveryFailed/index.mdx
new file mode 100644
index 000000000..d1a40ef78
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/DeliveryFailed/index.mdx
@@ -0,0 +1,22 @@
+---
+id: DeliveryFailed
+name: Delivery failed
+version: 0.0.1
+summary: |
+  Event that is emitted when a shipment delivery fails.
+owners:
+  - dboyne
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `DeliveryFailed` event is emitted when a shipment delivery fails. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
+
+This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/DeliveryFailed/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/DeliveryFailed/schema.json
new file mode 100644
index 000000000..06d3494f9
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/DeliveryFailed/schema.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "DeliveryFailed",
+  "description": "Schema for delivery failed event",
+  "properties": {
+    "shipmentId": {
+      "type": "string",
+      "description": "Unique identifier for the shipment"
+    },
+    "orderId": {
+      "type": "string",
+      "description": "Identifier for the associated order"
+    }
+  },
+  "required": ["shipmentId", "orderId"]
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ReturnInitiated/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ReturnInitiated/index.mdx
new file mode 100644
index 000000000..355378a20
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ReturnInitiated/index.mdx
@@ -0,0 +1,22 @@
+---
+id: ReturnInitiated
+name: Return initiated
+version: 0.0.1
+summary: |
+  Event that is emitted when a return is initiated.
+owners:
+  - dboyne
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `ReturnInitiated` event is emitted when a return is initiated. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
+
+This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time return data for tracking, auditing, or managing customer purchases.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ReturnInitiated/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ReturnInitiated/schema.json
new file mode 100644
index 000000000..669481742
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ReturnInitiated/schema.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "ReturnInitiated",
+  "description": "Schema for return initiated event",
+  "properties": {
+    "shipmentId": {
+      "type": "string",
+      "description": "Unique identifier for the shipment"
+    },
+    "orderId": {
+      "type": "string",
+      "description": "Identifier for the associated order"
+    }
+  },
+  "required": ["shipmentId", "orderId"]
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentCreated/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentCreated/index.mdx
new file mode 100644
index 000000000..a4cb31c25
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentCreated/index.mdx
@@ -0,0 +1,22 @@
+---
+id: ShipmentCreated
+name: Shipment created
+version: 0.0.1
+summary: |
+  Event that is emitted when a shipment is created.
+owners:
+  - dboyne
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `ShipmentCreated` event is emitted when a shipment is created. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
+
+This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentCreated/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentCreated/schema.json
new file mode 100644
index 000000000..b577b7484
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentCreated/schema.json
@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "ShipmentCreated",
+  "description": "Schema for shipment created event",
+  "properties": {
+    "shipmentId": {
+      "type": "string",
+      "description": "Unique identifier for the shipment"
+    },
+    "orderId": {
+      "type": "string",
+      "description": "Identifier for the associated order"
+    },
+    "address": {
+      "type": "object",
+      "properties": {
+        "street": {
+          "type": "string",
+          "description": "Street address for the shipment"
+        },
+        "city": {
+          "type": "string",
+          "description": "City for the shipment"
+        },
+        "state": {
+          "type": "string",
+          "description": "State for the shipment"
+        },
+        "postalCode": {
+          "type": "string",
+          "description": "Postal code for the shipment"
+        },
+        "country": {
+          "type": "string",
+          "description": "Country for the shipment"
+        }
+      },
+      "required": ["street", "city", "state", "postalCode", "country"]
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "itemId": {
+            "type": "string",
+            "description": "Identifier for the item"
+          },
+          "quantity": {
+            "type": "integer",
+            "description": "Quantity of the item"
+          }
+        },
+        "required": ["itemId", "quantity"]
+      }
+    },
+    "shippingMethod": {
+      "type": "string",
+      "description": "Method of shipping (e.g., standard, express)"
+    }
+  },
+  "required": ["shipmentId", "orderId", "address", "items", "shippingMethod"]
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentDelivered/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentDelivered/index.mdx
new file mode 100644
index 000000000..993cbc48c
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentDelivered/index.mdx
@@ -0,0 +1,22 @@
+---
+id: ShipmentDelivered
+name: Shipment delivered
+version: 0.0.1
+summary: |
+  Event that is emitted when a shipment is delivered.
+owners:
+  - dboyne
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `ShipmentDelivered` event is emitted when a shipment is delivered. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
+
+This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentDelivered/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentDelivered/schema.json
new file mode 100644
index 000000000..123c115da
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentDelivered/schema.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "ShipmentDelivered",
+  "description": "Schema for shipment delivered event",
+  "properties": {
+    "shipmentId": {
+      "type": "string",
+      "description": "Unique identifier for the shipment"
+    },
+    "orderId": {
+      "type": "string",
+      "description": "Identifier for the associated order"
+    }
+  },
+  "required": ["shipmentId", "orderId"]
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentDispatched/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentDispatched/index.mdx
new file mode 100644
index 000000000..b5adf18d7
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentDispatched/index.mdx
@@ -0,0 +1,22 @@
+---
+id: ShipmentDispatched
+name: Shipment dispatched
+version: 0.0.1
+summary: |
+  Event that is emitted when a shipment is dispatched.
+owners:
+  - dboyne
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `ShipmentDispatched` event is emitted when a shipment is dispatched. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
+
+This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentDispatched/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentDispatched/schema.json
new file mode 100644
index 000000000..51918bbf1
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentDispatched/schema.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "ShipmentDispatched",
+  "description": "Schema for shipment dispatched event",
+  "properties": {
+    "shipmentId": {
+      "type": "string",
+      "description": "Unique identifier for the shipment"
+    },
+    "orderId": {
+      "type": "string",
+      "description": "Identifier for the associated order"
+    }
+  },
+  "required": ["shipmentId", "orderId"]
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentInTransit/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentInTransit/index.mdx
new file mode 100644
index 000000000..5c89bfccf
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentInTransit/index.mdx
@@ -0,0 +1,22 @@
+---
+id: ShipmentInTransit
+name: Shipment in transit
+version: 0.0.1
+summary: |
+  Event that is emitted when a shipment is in transit.
+owners:
+  - dboyne
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The `ShipmentInTransit` event is emitted when a shipment is in transit. It provides information such as the shipment status (e.g., pending, completed, shipped), the items within the shipment, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.
+
+This event can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time shipment data for tracking, auditing, or managing customer purchases.
+
+<NodeGraph />
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentInTransit/schema.json b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentInTransit/schema.json
new file mode 100644
index 000000000..5b5975e53
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/events/ShipmentInTransit/schema.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "ShipmentInTransit",
+  "description": "Schema for shipment in transit event",
+  "properties": {
+    "shipmentId": {
+      "type": "string",
+      "description": "Unique identifier for the shipment"
+    },
+    "orderId": {
+      "type": "string",
+      "description": "Identifier for the associated order"
+    }
+  },
+  "required": ["shipmentId", "orderId"]
+}
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/index.mdx
new file mode 100644
index 000000000..d14602703
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/services/ShippingService/index.mdx
@@ -0,0 +1,58 @@
+---
+id: ShippingService
+version: 0.0.1
+name: Shipping Service
+summary: |
+  Service that handles shipping
+owners:
+  - dboyne
+receives:
+  - id: CancelShipment
+  - id: CreateReturnLabel
+  - id: CreateShipment
+  - id: UpdateShipmentStatus
+  - id: PaymentProcessed
+sends:
+  - id: ShipmentCreated
+  - id: ReturnInitiated
+  - id: ShipmentDispatched
+  - id: ShipmentInTransit
+  - id: ShipmentDelivered
+  - id: DeliveryFailed
+repository:
+  language: JavaScript
+  url: https://github.com/event-catalog/pretend-shipping-service
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The Shipping Service is responsible for managing shipping within the system. It handles order creation, updating, status tracking, and interactions with other services such as Inventory, Payment, and Notification services to ensure smooth order processing and fulfillment.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="This service sends messages to downstream consumers"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="This service receives messages from other services"
+  />
+</Tiles>
+
+### Core features
+
+The Shipping Service is responsible for managing shipping within the system. It handles order creation, updating, status tracking, and interactions with other services such as Inventory, Payment, and Notification services to ensure smooth order processing and fulfillment.
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/ubiquitous-language.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/ubiquitous-language.mdx
new file mode 100644
index 000000000..8bfd1ceb3
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/ubiquitous-language.mdx
@@ -0,0 +1,126 @@
+---
+dictionary:
+  - id: Payment
+    name: Payment
+    summary: 'The act of paying for magical goods or services.'
+    icon: Wand2
+  - id: Purchase Order
+    name: Purchase Order
+    summary: 'A mystical document issued by a buyer to a seller indicating the types, quantities, and agreed prices for enchanted products or services.'
+    description: |
+      A purchase order (PO) is a magical document that initiates the buying process between mystical entities. It protects both buyer and seller by clearly documenting the transaction details. Key components include:
+
+      - Unique PO number for tracking
+      - Detailed item specifications and quantities
+      - Agreed prices and payment terms
+      - Delivery requirements and timelines
+      - Terms and conditions of the purchase
+
+    icon: FileText
+  - id: Order Line
+    name: Order Line
+    summary: 'An individual enchanted item within a purchase order, representing a specific magical product or service being ordered.'
+    description: |
+      Order lines are the fundamental building blocks of any purchase order. Each line represents a distinct item or service and contains critical information for order fulfillment:
+
+      - Product identifier (SKU or part number)
+      - Quantity ordered
+      - Unit price and total line value
+      - Special handling instructions
+      - Required delivery date
+
+      Order lines drive warehouse picking operations, shipping processes, and financial calculations. They are essential for tracking partial shipments and managing order modifications.
+    icon: ListOrdered
+  - id: SKU
+    name: SKU
+    summary: 'Sorcery Keeping Unit - A unique identifier for distinct magical products and their variants in inventory.'
+    description: |
+      SKUs are the cornerstone of effective inventory management systems. Each SKU represents a unique combination of product attributes:
+
+      - Product variations (size, color, style)
+      - Storage location identifiers
+      - Supplier information
+      - Reorder points and quantities
+
+      SKUs enable precise inventory tracking, automated reordering, and detailed sales analytics. They are crucial for maintaining optimal stock levels and preventing stockouts or overstock situations.
+    icon: Tag
+  - id: Consignment
+    name: Consignment
+    summary: 'A batch of enchanted goods destined for or delivered to someone.'
+    description: |
+      A consignment represents the physical movement of goods through the supply chain. It encompasses all aspects of the shipping process:
+
+      - Packaging and labeling requirements
+      - Transportation method and routing
+      - Customs documentation for international shipments
+      - Tracking and proof of delivery
+
+      Consignments may combine multiple orders for efficient shipping and can be tracked as a single unit throughout the delivery process. They are crucial for managing logistics costs and ensuring timely delivery to customers.
+    icon: Package
+  - id: Invoice
+    name: Invoice
+    summary: 'A document issued by a seller to a buyer, listing enchanted goods or services provided and the amount due.'
+    description: |
+      Invoices are critical for financial transactions, serving as a request for payment from the buyer. They include:
+
+      - Invoice number for tracking
+      - List of products or services provided
+      - Total amount due and payment terms
+      - Seller and buyer contact information
+      - Due date for payment
+
+      Invoices are essential for accounting, tax purposes, and maintaining cash flow.
+    icon: Receipt
+  - id: Supplier
+    name: Supplier
+    summary: 'An entity that provides enchanted goods or services to another organization.'
+    description: |
+      Suppliers are key partners in the supply chain, responsible for delivering the necessary products or services. Key aspects include:
+
+      - Supplier identification and contact details
+      - Product or service offerings
+      - Pricing and payment terms
+      - Delivery schedules and reliability
+
+      Effective supplier management ensures quality, cost-effectiveness, and timely delivery.
+    icon: Truck
+  - id: Inventory
+    name: Inventory
+    summary: 'The complete list of enchanted items held in stock by a business.'
+    description: |
+      Inventory management is crucial for balancing supply and demand. It involves:
+
+      - Tracking stock levels and locations
+      - Managing reorder points and quantities
+      - Conducting regular stock audits
+      - Analyzing inventory turnover rates
+
+      Proper inventory management minimizes costs and maximizes service levels.
+    icon: Warehouse
+  - id: Fulfillment
+    name: Fulfillment
+    summary: 'The process of completing an order and delivering it to the customer.'
+    description: |
+      Fulfillment encompasses all steps from order receipt to delivery, including:
+
+      - Order processing and picking
+      - Packaging and shipping
+      - Delivery tracking and confirmation
+      - Handling returns and exchanges
+
+      Efficient fulfillment is key to customer satisfaction and operational efficiency.
+    icon: PackageCheck
+  - id: Return
+    name: Return
+    summary: 'The process of sending back enchanted goods to the seller for a refund or exchange.'
+    description: |
+      Returns management is an important aspect of customer service and inventory control. It involves:
+
+      - Processing return requests and authorizations
+      - Inspecting returned items for quality
+      - Restocking or disposing of returned goods
+      - Issuing refunds or exchanges
+
+      A streamlined returns process enhances customer loyalty and operational efficiency.
+    icon: PackageX
+---
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/versioned/0.0.1/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/versioned/0.0.1/index.mdx
new file mode 100644
index 000000000..6a96a9969
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/versioned/0.0.1/index.mdx
@@ -0,0 +1,21 @@
+---
+id: Orders
+name: Orders
+version: 0.0.1
+summary: |
+  Domain for everything shopping
+owners:
+  - dboyne
+  - full-stack
+services:
+  - id: InventoryService
+    version: 0.0.2
+badges:
+  - content: New domain
+    backgroundColor: blue
+    textColor: blue
+---
+
+## Overview
+
+<NodeGraph />
diff --git a/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/versioned/0.0.2/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/versioned/0.0.2/index.mdx
new file mode 100644
index 000000000..487c6ddb0
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/domains/Orders/versioned/0.0.2/index.mdx
@@ -0,0 +1,49 @@
+---
+id: Orders
+name: Orders
+version: 0.0.2
+owners:
+  - dboyne
+services:
+  - id: InventoryService
+    version: 0.0.2
+  - id: NotificationService
+    version: 0.0.2
+  - id: OrdersService
+    version: 0.0.2
+badges:
+  - content: New domain
+    backgroundColor: blue
+    textColor: blue
+---
+
+## Overview
+
+The Orders domain handles all operations related to customer orders, from creation to fulfillment. This documentation provides an overview of the events and services involved in the Orders domain, helping developers and stakeholders understand the event-driven architecture.
+
+:::warning
+Please ensure all services are updated to the latest version for compatibility and performance improvements.
+:::
+
+## Bounded context
+
+<NodeGraph />
+
+### Order example (sequence diagram)
+
+```mermaid
+sequenceDiagram
+    participant Customer
+    participant OrdersService
+    participant InventoryService
+    participant NotificationService
+
+    Customer->>OrdersService: Place Order
+    OrdersService->>InventoryService: Check Inventory
+    InventoryService-->>OrdersService: Inventory Available
+    OrdersService->>InventoryService: Reserve Inventory
+    OrdersService->>NotificationService: Send Order Confirmation
+    NotificationService-->>Customer: Order Confirmation
+    OrdersService->>Customer: Order Placed Successfully
+    OrdersService->>InventoryService: Update Inventory
+```
diff --git a/packages/sdk/src/test/catalog-eventcatalog/entities/Customer/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/entities/Customer/index.mdx
new file mode 100644
index 000000000..c6998dede
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/entities/Customer/index.mdx
@@ -0,0 +1,11 @@
+---
+id: Customer
+name: Customer
+version: 1.0.0
+summary: |
+  Represents a customer in the system
+owners:
+  - dboyne
+---
+
+The Customer entity represents a registered customer in the FlowMart system.
diff --git a/packages/sdk/src/test/catalog-eventcatalog/entities/Product/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/entities/Product/index.mdx
new file mode 100644
index 000000000..4c3c27ce0
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/entities/Product/index.mdx
@@ -0,0 +1,11 @@
+---
+id: Product
+name: Product
+version: 2.0.0
+summary: |
+  Represents a product in the catalog
+owners:
+  - dboyne
+---
+
+The Product entity represents an item available for purchase.
diff --git a/packages/sdk/src/test/catalog-eventcatalog/eventcatalog.config.js b/packages/sdk/src/test/catalog-eventcatalog/eventcatalog.config.js
new file mode 100644
index 000000000..b80c7c297
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/eventcatalog.config.js
@@ -0,0 +1,106 @@
+/** @type {import('../../bin/eventcatalog.config').Config} */
+export default {
+  cId: '8027010c-f3d6-417a-8234-e2f46087fc56',
+  title: 'FlowMart',
+  tagline: 'Here you can find all the information you need to know about our events and services (demo catalog).',
+  organizationName: 'FlowMart',
+  homepageLink: 'https://eventcatalog.dev',
+  editUrl: 'https://github.com/event-catalog/eventcatalog/edit/main',
+  port: 3000,
+  outDir: 'dist',
+  logo: {
+    alt: 'FlowMart',
+    src: '/logo.svg',
+    text: 'FlowMart',
+  },
+  base: '/',
+  trailingSlash: false,
+  mermaid: {
+    iconPacks: ['logos'],
+  },
+  rss: {
+    enabled: true,
+    limit: 15,
+  },
+  llmsTxt: {
+    enabled: true,
+  },
+  chat: {
+    enabled: true,
+    similarityResults: 50,
+    max_tokens: 4096,
+    // 'Llama-3.2-3B-Instruct-q4f16_1-MLC is also good
+    model: 'Hermes-3-Llama-3.2-3B-q4f16_1-MLC',
+  },
+  generators: [
+    [
+      '@eventcatalog/generator-ai',
+      {
+        debug: true,
+        splitMarkdownFiles: false,
+      },
+    ],
+  ],
+  customDocs: {
+    sidebar: [
+      {
+        label: 'Guides',
+        badge: {
+          text: 'New',
+          color: 'green',
+        },
+        collapsed: false,
+        items: [
+          {
+            label: 'Creating new microservices',
+            autogenerated: { directory: 'guides/creating-new-microservices' },
+          },
+          {
+            label: 'Event Storming',
+            autogenerated: { directory: 'guides/event-storming', collapsed: false },
+          },
+        ],
+      },
+      {
+        label: 'Technical Architecture & Design',
+        badge: {
+          text: 'New',
+          color: 'green',
+        },
+        collapsed: false,
+        items: [
+          {
+            label: 'Architecture Decision Records',
+            autogenerated: { directory: 'technical-architecture-design/architecture-decision-records', collapsed: false },
+          },
+          {
+            label: 'System Architecture Diagrams',
+            autogenerated: { directory: 'technical-architecture-design/system-architecture-diagrams', collapsed: false },
+          },
+          {
+            label: 'Infrastructure as Code',
+            autogenerated: { directory: 'technical-architecture-design/infrastructure-as-code', collapsed: false },
+          },
+          {
+            label: 'Read more on GitHub',
+            link: 'https://github.com/event-catalog/eventcatalog',
+            attrs: { target: '_blank', style: 'font-style: italic;' },
+          },
+        ],
+      },
+      {
+        label: 'Operations & Support',
+        badge: {
+          text: 'New',
+          color: 'green',
+        },
+        collapsed: false,
+        items: [{ label: 'Runbooks', autogenerated: { directory: 'operations-and-support/runbooks', collapsed: false } }],
+      },
+    ],
+  },
+};
+
+/**
+ * TODO: Collapsed groups (collapsed: true)
+ */
diff --git a/packages/sdk/src/test/catalog-eventcatalog/flows/OrderFlow/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/flows/OrderFlow/index.mdx
new file mode 100644
index 000000000..ba77a396e
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/flows/OrderFlow/index.mdx
@@ -0,0 +1,17 @@
+---
+id: OrderFlow
+name: Order Flow
+version: 2.0.0
+summary: |
+  Business flow for processing orders
+owners:
+  - dboyne
+steps:
+  - id: 'create_order'
+    title: Create Order
+    next_step: 'confirm_order'
+  - id: 'confirm_order'
+    title: Confirm Order
+---
+
+The Order Flow describes how orders are created and confirmed.
diff --git a/packages/sdk/src/test/catalog-eventcatalog/flows/PaymentFlow/index.mdx b/packages/sdk/src/test/catalog-eventcatalog/flows/PaymentFlow/index.mdx
new file mode 100644
index 000000000..7092039d2
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/flows/PaymentFlow/index.mdx
@@ -0,0 +1,23 @@
+---
+id: PaymentFlow
+name: Payment Flow
+version: 1.0.0
+summary: |
+  Business flow for processing payments
+owners:
+  - dboyne
+steps:
+  - id: 'place_order'
+    title: Place order
+    message:
+      id: PlaceOrder
+      version: 0.0.1
+    next_step: 'payment_initiated'
+  - id: 'payment_initiated'
+    title: Payment Initiated
+    message:
+      id: PaymentInitiated
+      version: 0.0.1
+---
+
+The Payment Flow describes how payments are processed in the system.
diff --git a/packages/sdk/src/test/catalog-eventcatalog/package.json b/packages/sdk/src/test/catalog-eventcatalog/package.json
new file mode 100644
index 000000000..d1d28752e
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "my-catalog",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "eventcatalog dev",
+    "build": "eventcatalog build",
+    "start": "eventcatalog start",
+    "preview": "eventcatalog preview",
+    "generate": "eventcatalog generate",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@eventcatalog/core": "2.33.5"
+  }
+}
diff --git a/examples/default/teams/full-stack.mdx b/packages/sdk/src/test/catalog-eventcatalog/teams/full-stack.mdx
similarity index 92%
rename from examples/default/teams/full-stack.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/teams/full-stack.mdx
index 453c8b587..07a081c04 100644
--- a/examples/default/teams/full-stack.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/teams/full-stack.mdx
@@ -1,14 +1,14 @@
 ---
 id: full-stack
 name: Full stackers
-summary: Full stack developers based in London, UK
+summmary: Full stack developers based in London, UK
 members:
-    - dboyne
-    - rthomas
-    - lkim
-    - lnguyen
-    - kpatel
-    - dkim
+  - dboyne
+  - rthomas
+  - lkim
+  - lnguyen
+  - kpatel
+  - dkim
 email: test@test.com
 slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
 msTeamsDirectMessageUrl: https://teams.microsoft.com/l/channel/<Your Channel Id>/<Your team chat name>?groupId=<Your group Id>&tenantId=<Your tenant Id>
@@ -21,10 +21,10 @@ The Full Stack Team is responsible for developing and maintaining both the front
 ## Responsibilities
 
 ### Key Responsibilities
+
 - **Front-End Development**: Design and implement user interfaces using modern web technologies (e.g., HTML, CSS, JavaScript, React).
 - **Back-End Development**: Develop and maintain server-side logic, APIs, and database interactions (e.g., Node.js, Express, SQL/NoSQL databases).
 - **Integration**: Ensure seamless communication between the front-end and back-end components.
 - **Performance Optimization**: Optimize the performance and scalability of web applications.
 - **Testing and Debugging**: Write and maintain unit, integration, and end-to-end tests to ensure the quality and reliability of the applications.
 - **Deployment**: Manage the deployment of applications to production environments using CI/CD pipelines.
-
diff --git a/examples/default/teams/mobile-devs.mdx b/packages/sdk/src/test/catalog-eventcatalog/teams/mobile-devs.mdx
similarity index 91%
rename from examples/default/teams/mobile-devs.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/teams/mobile-devs.mdx
index 2ce6b3a8a..dff7a26bd 100644
--- a/examples/default/teams/mobile-devs.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/teams/mobile-devs.mdx
@@ -2,11 +2,11 @@
 id: mobile-devs
 name: The mobile devs
 members:
-    - msmith
-    - rsingh
-    - jbrown
-    - mwang
-    - jchen
+  - msmith
+  - rsingh
+  - jbrown
+  - mwang
+  - jchen
 ---
 
 The Mobile Devs team is responsible for the development and maintenance of the mobile applications for our company. This includes the iOS and Android apps that customers use to interact with our services, make purchases, and manage their accounts. The team ensures that the mobile apps are user-friendly, secure, and performant.
@@ -14,11 +14,13 @@ The Mobile Devs team is responsible for the development and maintenance of the m
 ## Responsibilities
 
 ### 1. Mobile Application Development
+
 - **Platform Support**: Developing and maintaining apps for iOS and Android platforms.
 - **Feature Implementation**: Implementing new features based on product requirements and user feedback.
 - **User Interface Design**: Ensuring a consistent and intuitive user interface across all mobile platforms.
 - **Performance Optimization**: Optimizing the performance of mobile apps to ensure fast and smooth user experiences.
 
 ### 2. Integration with Backend Services
+
 - **API Integration**: Integrating mobile apps with backend services using RESTful APIs and other communication protocols.
-- **Real-time Updates**: Implementing real-time data updates and synchronization with backend services.
\ No newline at end of file
+- **Real-time Updates**: Implementing real-time data updates and synchronization with backend services.
diff --git a/packages/sdk/src/test/catalog-eventcatalog/teams/order-management.mdx b/packages/sdk/src/test/catalog-eventcatalog/teams/order-management.mdx
new file mode 100644
index 000000000..309f45d99
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/teams/order-management.mdx
@@ -0,0 +1,23 @@
+---
+id: order-management
+name: The order management team
+members:
+  - asmith
+  - mchen
+  - nshah
+  - slee
+  - spatel
+---
+
+The order management team is responsible for overseeing and optimizing the entire order lifecycle within our organization. Their key responsibilities include:
+
+- Processing and validating incoming customer orders
+- Managing order fulfillment workflows and inventory allocation
+- Coordinating with warehouse and shipping teams
+- Handling order modifications and cancellations
+- Resolving order-related customer issues and disputes
+- Monitoring order processing metrics and KPIs
+- Implementing and maintaining order management systems
+- Developing strategies to improve order accuracy and efficiency
+
+The team works closely with sales, customer service, and logistics departments to ensure smooth order processing and customer satisfaction.
diff --git a/examples/default/teams/subscriptions-management.mdx b/packages/sdk/src/test/catalog-eventcatalog/teams/subscriptions-management.mdx
similarity index 87%
rename from examples/default/teams/subscriptions-management.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/teams/subscriptions-management.mdx
index 6ee840df8..542d281ef 100644
--- a/examples/default/teams/subscriptions-management.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/teams/subscriptions-management.mdx
@@ -2,12 +2,12 @@
 id: subscriptions-management
 name: The subscriptions management team
 members:
-    - tgarcia
-    - alee
-    - rjohnson
-    - azhang
-    - rjones
-    - jmiller
+  - tgarcia
+  - alee
+  - rjohnson
+  - azhang
+  - rjones
+  - jmiller
 ---
 
 The subscriptions management team is responsible for overseeing and optimizing the entire subscription lifecycle within our organization. Their key responsibilities include:
@@ -18,4 +18,4 @@ The subscriptions management team is responsible for overseeing and optimizing t
 - Handling order modifications and cancellations
 - Resolving order-related customer issues and disputes
 
-The team works closely with sales, customer service, and logistics departments to ensure smooth order processing and customer satisfaction.
\ No newline at end of file
+The team works closely with sales, customer service, and logistics departments to ensure smooth order processing and customer satisfaction.
diff --git a/packages/sdk/src/test/catalog-eventcatalog/users/aSmith.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/aSmith.mdx
new file mode 100644
index 000000000..db9809431
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/aSmith.mdx
@@ -0,0 +1,26 @@
+---
+id: asmith
+name: Amy Smith
+avatarUrl: https://randomuser.me/api/portraits/women/48.jpg
+role: Product owner
+---
+
+Hello! I'm Amy Smith, the Product Owner of the innovative Full Stackers team. With a strong focus on delivering exceptional value, I specialize in connecting business objectives with technical solutions to create products that users love.
+
+### About Me
+
+With a comprehensive background in product management and a solid understanding of software development, I bring a unique perspective to the table. My career has been driven by a passion for understanding user needs, defining clear product visions, and leading teams to successful product deliveries.
+
+### What I Do
+
+As the Product Owner for Full Stackers, my role involves a wide range of responsibilities aimed at ensuring our products are both high-quality and user-centric. Key aspects of my role include:
+
+- **Product Vision & Strategy**: Defining and communicating the long-term vision and strategy for our products, ensuring alignment with the company's objectives and market demands.
+- **Roadmap Planning**: Developing and maintaining a product roadmap that highlights key features and milestones, prioritizing tasks based on their business value and user feedback.
+- **Stakeholder Management**: Engaging with stakeholders across the organization to gather requirements, provide updates, and ensure everyone is aligned on the product's direction.
+- **User-Centric Design**: Championing the end-users by conducting user research, analyzing feedback, and ensuring our products effectively solve their problems.
+- **Agile Leadership**: Leading the development process using Agile methodologies, facilitating sprint planning, and ensuring the team has clear priorities and objectives.
+
+My mission is to deliver products that not only meet but exceed customer expectations. I thrive on the challenge of translating complex requirements into simple, intuitive solutions.
+
+If you’re interested in product management, user experience, or discussing the latest trends in technology, feel free to reach out!
diff --git a/packages/sdk/src/test/catalog-eventcatalog/users/alee.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/alee.mdx
new file mode 100644
index 000000000..ae34f1820
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/alee.mdx
@@ -0,0 +1,8 @@
+---
+id: alee
+name: Alice Lee
+avatarUrl: https://randomuser.me/api/portraits/women/91.jpg
+role: Technical Writer
+---
+
+As a Technical Writer on the Documentation team, I create clear, comprehensive documentation for our products and APIs. My focus is on making complex technical concepts accessible to developers and end-users alike. I collaborate with engineering teams to ensure our documentation stays current and accurate.
diff --git a/packages/sdk/src/test/catalog-eventcatalog/users/azhang.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/azhang.mdx
new file mode 100644
index 000000000..0f0a15616
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/azhang.mdx
@@ -0,0 +1,11 @@
+---
+id: azhang
+name: Alice Zhang
+avatarUrl: https://randomuser.me/api/portraits/women/97.jpg
+role: Data Engineer
+email: azhang@company.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/azhang
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=azhang@company.com
+---
+
+Building and maintaining data pipelines and infrastructure...
diff --git a/packages/sdk/src/test/catalog-eventcatalog/users/dboyne.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/dboyne.mdx
new file mode 100644
index 000000000..a7a9ae5ea
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/dboyne.mdx
@@ -0,0 +1,34 @@
+---
+id: dboyne
+name: David Boyne
+avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png'
+role: Lead developer
+email: test@test.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=test@test.com
+---
+
+Hello! I'm David Boyne, the Tech Lead of an amazing team called Full Stackers. With a passion for building robust and scalable systems, I specialize in designing and implementing event-driven architectures that power modern, responsive applications.
+
+### About Me
+
+With over a decade of experience in the tech industry, I have honed my skills in full-stack development, cloud computing, and distributed systems. My journey has taken me through various roles, from software engineer to architect, and now as a tech lead, I am committed to driving innovation and excellence within my team.
+
+### What I Do
+
+At Full Stackers, we focus on creating seamless and efficient event-driven architectures that enhance the performance and scalability of our applications. My role involves:
+
+- **Architecture Design**: Crafting scalable and resilient system architectures using event-driven paradigms.
+- **Team Leadership**: Guiding a talented team of developers, fostering a collaborative and innovative environment.
+- **Code Reviews & Mentorship**: Ensuring code quality and sharing knowledge to help the team grow.
+- **Stakeholder Collaboration**: Working closely with other teams and stakeholders to align our technical solutions with business goals.
+- **Continuous Improvement**: Advocating for best practices in software development, deployment, and monitoring.
+
+I am passionate about leveraging the power of events to build systems that are not only highly responsive but also easier to maintain and extend. In an ever-evolving tech landscape, I strive to stay ahead of the curve, continuously learning and adapting to new technologies and methodologies.
+
+Feel free to connect with me to discuss all things tech, event-driven architectures, or to exchange ideas on building better software systems!
+
+---
+
+_David Boyne_
+_Tech Lead, Full Stackers_
diff --git a/packages/sdk/src/test/catalog-eventcatalog/users/dkim.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/dkim.mdx
new file mode 100644
index 000000000..bbdf71b61
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/dkim.mdx
@@ -0,0 +1,11 @@
+---
+id: dkim
+name: David Kim
+avatarUrl: https://randomuser.me/api/portraits/men/96.jpg
+role: Performance Engineer
+email: dkim@company.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/dkim
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=dkim@company.com
+---
+
+Optimizing application performance and user experience...
diff --git a/packages/sdk/src/test/catalog-eventcatalog/users/jbrown.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/jbrown.mdx
new file mode 100644
index 000000000..149232154
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/jbrown.mdx
@@ -0,0 +1,11 @@
+---
+id: jbrown
+name: Jessica Brown
+avatarUrl: https://randomuser.me/api/portraits/women/95.jpg
+role: UI/UX Designer
+email: jbrown@company.com
+slackDirectMessageUrl: https://yourteam.slack.com/channels/jbrown
+msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=jbrown@company.com
+---
+
+Creating intuitive and engaging user interfaces...
diff --git a/examples/default/users/jchen.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/jchen.mdx
similarity index 95%
rename from examples/default/users/jchen.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/jchen.mdx
index ba4e2b85f..c495716fc 100644
--- a/examples/default/users/jchen.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/jchen.mdx
@@ -5,4 +5,4 @@ avatarUrl: https://randomuser.me/api/portraits/women/23.jpg
 role: DevOps Engineer
 ---
 
-As a DevOps Engineer on the Platform Engineering team, I specialize in building and maintaining our cloud infrastructure and deployment pipelines. My focus is on automating processes, improving system reliability, and ensuring smooth continuous integration and deployment (CI/CD). I work closely with development teams to streamline their workflows and implement robust monitoring and alerting solutions. 
\ No newline at end of file
+As a DevOps Engineer on the Platform Engineering team, I specialize in building and maintaining our cloud infrastructure and deployment pipelines. My focus is on automating processes, improving system reliability, and ensuring smooth continuous integration and deployment (CI/CD). I work closely with development teams to streamline their workflows and implement robust monitoring and alerting solutions.
diff --git a/examples/default/users/jmiller.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/jmiller.mdx
similarity index 95%
rename from examples/default/users/jmiller.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/jmiller.mdx
index d3e3274f8..6c86bc9c6 100644
--- a/examples/default/users/jmiller.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/jmiller.mdx
@@ -5,4 +5,4 @@ avatarUrl: https://randomuser.me/api/portraits/men/18.jpg
 role: Systems Architect
 ---
 
-I'm a Systems Architect on the Infrastructure team, responsible for designing and evolving our technical architecture. My expertise includes cloud architecture, system integration, and scalability planning. I work closely with various teams to ensure our technical solutions align with business needs while maintaining technical excellence. 
\ No newline at end of file
+I'm a Systems Architect on the Infrastructure team, responsible for designing and evolving our technical architecture. My expertise includes cloud architecture, system integration, and scalability planning. I work closely with various teams to ensure our technical solutions align with business needs while maintaining technical excellence.
diff --git a/examples/default/users/kpatel.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/kpatel.mdx
similarity index 93%
rename from examples/default/users/kpatel.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/kpatel.mdx
index 4d903d749..66c17f5c8 100644
--- a/examples/default/users/kpatel.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/kpatel.mdx
@@ -8,4 +8,4 @@ slackDirectMessageUrl: https://yourteam.slack.com/channels/kpatel
 msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=kpatel@company.com
 ---
 
-As a Cloud Architect, I design and implement scalable cloud infrastructure solutions... 
\ No newline at end of file
+As a Cloud Architect, I design and implement scalable cloud infrastructure solutions...
diff --git a/examples/default/users/lkim.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/lkim.mdx
similarity index 96%
rename from examples/default/users/lkim.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/lkim.mdx
index fa28d77e2..3601a7967 100644
--- a/examples/default/users/lkim.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/lkim.mdx
@@ -5,4 +5,4 @@ avatarUrl: https://randomuser.me/api/portraits/women/89.jpg
 role: Backend Engineer
 ---
 
-As a Backend Engineer on the API Platform team, I design and implement 
\ No newline at end of file
+As a Backend Engineer on the API Platform team, I design and implement
diff --git a/examples/default/users/lnguyen.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/lnguyen.mdx
similarity index 87%
rename from examples/default/users/lnguyen.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/lnguyen.mdx
index a61e32b95..8bc9a7d09 100644
--- a/examples/default/users/lnguyen.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/lnguyen.mdx
@@ -8,4 +8,4 @@ slackDirectMessageUrl: https://yourteam.slack.com/channels/lnguyen
 msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=lnguyen@company.com
 ---
 
-Developing responsive web applications... 
\ No newline at end of file
+Developing responsive web applications...
diff --git a/packages/sdk/src/test/catalog-eventcatalog/users/mSmith.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/mSmith.mdx
new file mode 100644
index 000000000..635e036f1
--- /dev/null
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/mSmith.mdx
@@ -0,0 +1,8 @@
+---
+id: msmith
+name: Martin Smith
+avatarUrl: 'https://randomuser.me/api/portraits/men/51.jpg'
+role: Senior software engineer
+---
+
+As a Senior Mobile Developer on The Mobile Devs team, I play a key role in designing, developing, and maintaining our company’s mobile applications. My focus is on creating a seamless and intuitive user experience for our customers on both iOS and Android platforms. I work closely with cross-functional teams, including backend developers, UX/UI designers, and product managers, to deliver high-quality mobile solutions that meet business objectives and exceed user expectations.
diff --git a/examples/default/users/mchen.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/mchen.mdx
similarity index 99%
rename from examples/default/users/mchen.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/mchen.mdx
index 76e80c1cf..93f6b6909 100644
--- a/examples/default/users/mchen.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/mchen.mdx
@@ -8,4 +8,4 @@ slackDirectMessageUrl: https://yourteam.slack.com/channels/mchen
 msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=mchen@company.com
 ---
 
-Specializing in maintaining system reliability and performance... 
\ No newline at end of file
+Specializing in maintaining system reliability and performance...
diff --git a/examples/default/users/mwang.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/mwang.mdx
similarity index 84%
rename from examples/default/users/mwang.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/mwang.mdx
index 921837092..33718343b 100644
--- a/examples/default/users/mwang.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/mwang.mdx
@@ -8,4 +8,4 @@ slackDirectMessageUrl: https://yourteam.slack.com/channels/mwang
 msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=mwang@company.com
 ---
 
-Developing and deploying machine learning models... 
\ No newline at end of file
+Developing and deploying machine learning models...
diff --git a/examples/default/users/mwilson.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/mwilson.mdx
similarity index 94%
rename from examples/default/users/mwilson.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/mwilson.mdx
index a04b23ee6..f59111ee0 100644
--- a/examples/default/users/mwilson.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/mwilson.mdx
@@ -5,4 +5,4 @@ avatarUrl: https://randomuser.me/api/portraits/men/77.jpg
 role: QA Engineer
 ---
 
-I'm a QA Engineer on the Quality Assurance team, ensuring our products meet the highest standards of quality and reliability. My focus includes automated testing, performance testing, and developing comprehensive test strategies. I work closely with development teams to implement effective testing practices throughout the development lifecycle. 
\ No newline at end of file
+I'm a QA Engineer on the Quality Assurance team, ensuring our products meet the highest standards of quality and reliability. My focus includes automated testing, performance testing, and developing comprehensive test strategies. I work closely with development teams to implement effective testing practices throughout the development lifecycle.
diff --git a/examples/default/users/nshah.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/nshah.mdx
similarity index 90%
rename from examples/default/users/nshah.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/nshah.mdx
index e1702c873..4a3516826 100644
--- a/examples/default/users/nshah.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/nshah.mdx
@@ -5,4 +5,4 @@ avatarUrl: https://randomuser.me/api/portraits/women/33.jpg
 role: Scrum Master
 ---
 
-As a Scrum Master for the Platform team, I facilitate agile processes and help remove obstacles to team productivity. My focus is on improving team dynamics, sprint planning, and process optimization. I work closely with product owners and development teams to ensure smooth project delivery. 
\ No newline at end of file
+As a Scrum Master for the Platform team, I facilitate agile processes and help remove obstacles to team productivity. My focus is on improving team dynamics, sprint planning, and process optimization. I work closely with product owners and development teams to ensure smooth project delivery.
diff --git a/examples/default/users/rjohnson.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/rjohnson.mdx
similarity index 92%
rename from examples/default/users/rjohnson.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/rjohnson.mdx
index bb62b5462..83a13b32f 100644
--- a/examples/default/users/rjohnson.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/rjohnson.mdx
@@ -5,4 +5,4 @@ avatarUrl: https://randomuser.me/api/portraits/men/32.jpg
 role: UX Designer
 ---
 
-I'm a UX Designer on the Design Systems team, passionate about creating intuitive and accessible user experiences. With a background in cognitive psychology and human-computer interaction, I focus on user research, wireframing, and prototyping. I collaborate closely with product teams to ensure our solutions meet both user needs and business objectives. 
\ No newline at end of file
+I'm a UX Designer on the Design Systems team, passionate about creating intuitive and accessible user experiences. With a background in cognitive psychology and human-computer interaction, I focus on user research, wireframing, and prototyping. I collaborate closely with product teams to ensure our solutions meet both user needs and business objectives.
diff --git a/examples/default/users/rjones.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/rjones.mdx
similarity index 87%
rename from examples/default/users/rjones.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/rjones.mdx
index 4faabf9e2..dc487464a 100644
--- a/examples/default/users/rjones.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/rjones.mdx
@@ -8,4 +8,4 @@ slackDirectMessageUrl: https://yourteam.slack.com/channels/rjones
 msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=rjones@company.com
 ---
 
-Analyzing and improving system security... 
\ No newline at end of file
+Analyzing and improving system security...
diff --git a/examples/default/users/rsingh.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/rsingh.mdx
similarity index 83%
rename from examples/default/users/rsingh.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/rsingh.mdx
index aeca7b3fd..b3485bb09 100644
--- a/examples/default/users/rsingh.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/rsingh.mdx
@@ -8,4 +8,4 @@ slackDirectMessageUrl: https://yourteam.slack.com/channels/rsingh
 msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=rsingh@company.com
 ---
 
-Focused on developing cross-platform mobile applications... 
\ No newline at end of file
+Focused on developing cross-platform mobile applications...
diff --git a/examples/default/users/rthomas.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/rthomas.mdx
similarity index 87%
rename from examples/default/users/rthomas.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/rthomas.mdx
index 0ca26835e..403e374fe 100644
--- a/examples/default/users/rthomas.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/rthomas.mdx
@@ -5,4 +5,4 @@ avatarUrl: https://randomuser.me/api/portraits/men/62.jpg
 role: Frontend Engineer
 ---
 
-I'm a Frontend Engineer on the Web Platform team, specializing in building responsive and accessible web applications. My expertise includes modern JavaScript frameworks, CSS architecture, and web performance optimization. I work closely with designers and backend teams to deliver exceptional user experiences. 
\ No newline at end of file
+I'm a Frontend Engineer on the Web Platform team, specializing in building responsive and accessible web applications. My expertise includes modern JavaScript frameworks, CSS architecture, and web performance optimization. I work closely with designers and backend teams to deliver exceptional user experiences.
diff --git a/examples/default/users/slee.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/slee.mdx
similarity index 86%
rename from examples/default/users/slee.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/slee.mdx
index 746ba77cb..310fe9fbf 100644
--- a/examples/default/users/slee.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/slee.mdx
@@ -8,4 +8,4 @@ slackDirectMessageUrl: https://yourteam.slack.com/channels/slee
 msTeamsDirectMessageUrl: https://teams.microsoft.com/l/chat/0/0?users=slee@company.com
 ---
 
-Managing product development and strategy... 
\ No newline at end of file
+Managing product development and strategy...
diff --git a/examples/default/users/spatel.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/spatel.mdx
similarity index 93%
rename from examples/default/users/spatel.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/spatel.mdx
index f39d64251..cf26eac8d 100644
--- a/examples/default/users/spatel.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/spatel.mdx
@@ -5,4 +5,4 @@ avatarUrl: https://randomuser.me/api/portraits/women/67.jpg
 role: Data Scientist
 ---
 
-As a Data Scientist on the Analytics team, I leverage machine learning and statistical analysis to derive meaningful insights from our data. My expertise includes predictive modeling, A/B testing, and developing data-driven solutions. I work closely with product and engineering teams to implement data-driven features and optimize user experiences. 
\ No newline at end of file
+As a Data Scientist on the Analytics team, I leverage machine learning and statistical analysis to derive meaningful insights from our data. My expertise includes predictive modeling, A/B testing, and developing data-driven solutions. I work closely with product and engineering teams to implement data-driven features and optimize user experiences.
diff --git a/examples/default/users/tgarcia.mdx b/packages/sdk/src/test/catalog-eventcatalog/users/tgarcia.mdx
similarity index 94%
rename from examples/default/users/tgarcia.mdx
rename to packages/sdk/src/test/catalog-eventcatalog/users/tgarcia.mdx
index 10cb7f8d8..cd4f80423 100644
--- a/examples/default/users/tgarcia.mdx
+++ b/packages/sdk/src/test/catalog-eventcatalog/users/tgarcia.mdx
@@ -5,4 +5,4 @@ avatarUrl: https://randomuser.me/api/portraits/men/41.jpg
 role: Security Engineer
 ---
 
-I'm a Security Engineer on the InfoSec team, responsible for maintaining and enhancing our organization's security posture. My focus includes vulnerability assessment, security architecture review, and implementing security best practices. I work closely with development teams to ensure security is built into our products from the ground up. 
\ No newline at end of file
+I'm a Security Engineer on the InfoSec team, responsible for maintaining and enhancing our organization's security posture. My focus includes vulnerability assessment, security architecture review, and implementing security best practices. I work closely with development teams to ensure security is built into our products from the ground up.
diff --git a/packages/sdk/src/test/changelogs.test.ts b/packages/sdk/src/test/changelogs.test.ts
new file mode 100644
index 000000000..47285accc
--- /dev/null
+++ b/packages/sdk/src/test/changelogs.test.ts
@@ -0,0 +1,593 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+import matter from 'gray-matter';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-changelogs');
+
+const { writeChangelog, appendChangelog, getChangelog, rmChangelog, writeEvent, writeService, versionEvent } =
+  utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Changelogs SDK', () => {
+  describe('writeChangelog', () => {
+    it('writes a changelog to an event', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        markdown: '### Added support for JSON Schema',
+      });
+
+      const changelogPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'changelog.mdx');
+      expect(fs.existsSync(changelogPath)).toBe(true);
+
+      const content = fs.readFileSync(changelogPath, 'utf-8');
+      const parsed = matter(content);
+      expect(parsed.data.createdAt).toBeDefined();
+      expect(parsed.content.trim()).toBe('### Added support for JSON Schema');
+    });
+
+    it('writes a changelog with badges', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        badges: [{ content: 'Breaking change', backgroundColor: 'red', textColor: 'red' }],
+        markdown: '### Removed fields from schema',
+      });
+
+      const changelogPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'changelog.mdx');
+      const content = fs.readFileSync(changelogPath, 'utf-8');
+      const parsed = matter(content);
+      expect(parsed.data.badges).toEqual([{ content: 'Breaking change', backgroundColor: 'red', textColor: 'red' }]);
+    });
+
+    it('writes a changelog to a service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'Service for inventory',
+        markdown: '# Inventory Service',
+      });
+
+      await writeChangelog('InventoryService', {
+        createdAt: '2024-08-01',
+        markdown: '### Service receives additional events',
+      });
+
+      const changelogPath = path.join(CATALOG_PATH, 'services', 'InventoryService', 'changelog.mdx');
+      expect(fs.existsSync(changelogPath)).toBe(true);
+    });
+
+    it('writes a changelog to a versioned resource', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      // Version the event to move it to versioned/1.0.0/
+      await versionEvent('OrderCreated');
+
+      // Write a new version
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '2.0.0',
+        summary: 'Event for order creation v2',
+        markdown: '# Order Created v2',
+      });
+
+      // Write changelog to the versioned resource
+      await writeChangelog(
+        'OrderCreated',
+        {
+          createdAt: '2024-07-01',
+          markdown: '### Initial release',
+        },
+        { version: '1.0.0' }
+      );
+
+      const changelogPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'versioned', '1.0.0', 'changelog.mdx');
+      expect(fs.existsSync(changelogPath)).toBe(true);
+    });
+
+    it('writes a changelog in md format when specified', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await writeChangelog(
+        'OrderCreated',
+        {
+          createdAt: '2024-08-01',
+          markdown: '### Some changes',
+        },
+        { format: 'md' }
+      );
+
+      const changelogPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'changelog.md');
+      expect(fs.existsSync(changelogPath)).toBe(true);
+    });
+
+    it('overwrites an existing changelog', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        markdown: '### First entry',
+      });
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-09-01',
+        markdown: '### Updated entry',
+      });
+
+      const changelogPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'changelog.mdx');
+      const content = fs.readFileSync(changelogPath, 'utf-8');
+      const parsed = matter(content);
+      expect(parsed.content.trim()).toBe('### Updated entry');
+    });
+
+    it('throws an error if the resource is not found', async () => {
+      await expect(
+        writeChangelog('NonExistent', {
+          createdAt: '2024-08-01',
+          markdown: '### Some changes',
+        })
+      ).rejects.toThrow('No resource found with id: NonExistent');
+    });
+
+    it('does not include badges in frontmatter when empty array is provided', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        badges: [],
+        markdown: '### Some changes',
+      });
+
+      const changelogPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'changelog.mdx');
+      const content = fs.readFileSync(changelogPath, 'utf-8');
+      const parsed = matter(content);
+      expect(parsed.data.badges).toBeUndefined();
+    });
+  });
+
+  describe('getChangelog', () => {
+    it('returns the changelog for a resource', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        markdown: '### Added support for JSON Schema',
+      });
+
+      const changelog = await getChangelog('OrderCreated');
+      expect(changelog).toBeDefined();
+      expect(changelog!.markdown).toBe('### Added support for JSON Schema');
+    });
+
+    it('returns the changelog with badges', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        badges: [{ content: 'Breaking change', backgroundColor: 'red', textColor: 'red' }],
+        markdown: '### Removed fields',
+      });
+
+      const changelog = await getChangelog('OrderCreated');
+      expect(changelog).toBeDefined();
+      expect(changelog!.badges).toEqual([{ content: 'Breaking change', backgroundColor: 'red', textColor: 'red' }]);
+    });
+
+    it('returns undefined if no changelog exists', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      const changelog = await getChangelog('OrderCreated');
+      expect(changelog).toBeUndefined();
+    });
+
+    it('returns undefined if the resource does not exist', async () => {
+      const changelog = await getChangelog('NonExistent');
+      expect(changelog).toBeUndefined();
+    });
+
+    it('returns the changelog for a specific version', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await versionEvent('OrderCreated');
+
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '2.0.0',
+        summary: 'Event for order creation v2',
+        markdown: '# Order Created v2',
+      });
+
+      await writeChangelog(
+        'OrderCreated',
+        {
+          createdAt: '2024-07-01',
+          markdown: '### v1 changelog',
+        },
+        { version: '1.0.0' }
+      );
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        markdown: '### v2 changelog',
+      });
+
+      const v1Changelog = await getChangelog('OrderCreated', { version: '1.0.0' });
+      expect(v1Changelog).toBeDefined();
+      expect(v1Changelog!.markdown).toBe('### v1 changelog');
+
+      const latestChangelog = await getChangelog('OrderCreated');
+      expect(latestChangelog).toBeDefined();
+      expect(latestChangelog!.markdown).toBe('### v2 changelog');
+    });
+  });
+
+  describe('appendChangelog', () => {
+    it('creates a changelog if none exists', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await appendChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        markdown: '### First entry',
+      });
+
+      const changelog = await getChangelog('OrderCreated');
+      expect(changelog).toBeDefined();
+      expect(changelog!.markdown).toBe('### First entry');
+    });
+
+    it('prepends a new entry to an existing changelog separated by ---', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        markdown: '### First entry',
+      });
+
+      await appendChangelog('OrderCreated', {
+        createdAt: '2024-09-01',
+        markdown: '### Second entry',
+      });
+
+      const changelog = await getChangelog('OrderCreated');
+      expect(changelog).toBeDefined();
+      expect(changelog!.markdown).toContain('### Second entry');
+      expect(changelog!.markdown).toContain('---');
+      expect(changelog!.markdown).toContain('### First entry');
+      // New entry should come first
+      expect(changelog!.markdown.indexOf('### Second entry')).toBeLessThan(changelog!.markdown.indexOf('### First entry'));
+    });
+
+    it('updates frontmatter createdAt to the latest entry', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        markdown: '### First entry',
+      });
+
+      await appendChangelog('OrderCreated', {
+        createdAt: '2024-09-15',
+        markdown: '### Second entry',
+      });
+
+      const changelogPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'changelog.mdx');
+      const content = fs.readFileSync(changelogPath, 'utf-8');
+      const parsed = matter(content);
+      expect(new Date(parsed.data.createdAt).toISOString().slice(0, 10)).toBe('2024-09-15');
+    });
+
+    it('appends multiple entries preserving order', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await appendChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        markdown: '### First',
+      });
+
+      await appendChangelog('OrderCreated', {
+        createdAt: '2024-09-01',
+        markdown: '### Second',
+      });
+
+      await appendChangelog('OrderCreated', {
+        createdAt: '2024-10-01',
+        markdown: '### Third',
+      });
+
+      const changelog = await getChangelog('OrderCreated');
+      expect(changelog).toBeDefined();
+      const md = changelog!.markdown;
+      expect(md.indexOf('### Third')).toBeLessThan(md.indexOf('### Second'));
+      expect(md.indexOf('### Second')).toBeLessThan(md.indexOf('### First'));
+    });
+
+    it('appends to a specific version changelog', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await versionEvent('OrderCreated');
+
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '2.0.0',
+        summary: 'Event for order creation v2',
+        markdown: '# Order Created v2',
+      });
+
+      await writeChangelog(
+        'OrderCreated',
+        {
+          createdAt: '2024-07-01',
+          markdown: '### Initial release',
+        },
+        { version: '1.0.0' }
+      );
+
+      await appendChangelog(
+        'OrderCreated',
+        {
+          createdAt: '2024-07-15',
+          markdown: '### Patch fix',
+        },
+        { version: '1.0.0' }
+      );
+
+      const changelog = await getChangelog('OrderCreated', { version: '1.0.0' });
+      expect(changelog).toBeDefined();
+      expect(changelog!.markdown).toContain('### Patch fix');
+      expect(changelog!.markdown).toContain('### Initial release');
+    });
+
+    it('throws an error if the resource does not exist', async () => {
+      await expect(
+        appendChangelog('NonExistent', {
+          createdAt: '2024-08-01',
+          markdown: '### Some changes',
+        })
+      ).rejects.toThrow('No resource found with id: NonExistent');
+    });
+
+    it('clears stale badges when appending entry without badges', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        badges: [{ content: 'Breaking change', backgroundColor: 'red', textColor: 'red' }],
+        markdown: '### First entry with badges',
+      });
+
+      await appendChangelog('OrderCreated', {
+        createdAt: '2024-09-01',
+        markdown: '### Second entry without badges',
+      });
+
+      const changelogPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'changelog.mdx');
+      const content = fs.readFileSync(changelogPath, 'utf-8');
+      const parsed = matter(content);
+      expect(parsed.data.badges).toBeUndefined();
+    });
+
+    it('uses badges from the new entry', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        markdown: '### First entry',
+      });
+
+      await appendChangelog('OrderCreated', {
+        createdAt: '2024-09-01',
+        badges: [{ content: 'Breaking change', backgroundColor: 'red', textColor: 'red' }],
+        markdown: '### Breaking update',
+      });
+
+      const changelogPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'changelog.mdx');
+      const content = fs.readFileSync(changelogPath, 'utf-8');
+      const parsed = matter(content);
+      expect(parsed.data.badges).toEqual([{ content: 'Breaking change', backgroundColor: 'red', textColor: 'red' }]);
+    });
+  });
+
+  describe('rmChangelog', () => {
+    it('removes the changelog for a resource', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await writeChangelog('OrderCreated', {
+        createdAt: '2024-08-01',
+        markdown: '### Some changes',
+      });
+
+      const changelogPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'changelog.mdx');
+      expect(fs.existsSync(changelogPath)).toBe(true);
+
+      await rmChangelog('OrderCreated');
+      expect(fs.existsSync(changelogPath)).toBe(false);
+    });
+
+    it('removes the changelog for a specific version', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      await versionEvent('OrderCreated');
+
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '2.0.0',
+        summary: 'Event for order creation v2',
+        markdown: '# Order Created v2',
+      });
+
+      await writeChangelog(
+        'OrderCreated',
+        {
+          createdAt: '2024-07-01',
+          markdown: '### v1 changelog',
+        },
+        { version: '1.0.0' }
+      );
+
+      const changelogPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'versioned', '1.0.0', 'changelog.mdx');
+      expect(fs.existsSync(changelogPath)).toBe(true);
+
+      await rmChangelog('OrderCreated', { version: '1.0.0' });
+      expect(fs.existsSync(changelogPath)).toBe(false);
+    });
+
+    it('removes both .mdx and .md changelog files when both exist', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Event for order creation',
+        markdown: '# Order Created',
+      });
+
+      // Write one in md format, then one in mdx format
+      await writeChangelog('OrderCreated', { createdAt: '2024-08-01', markdown: '### md entry' }, { format: 'md' });
+      await writeChangelog('OrderCreated', { createdAt: '2024-08-01', markdown: '### mdx entry' }, { format: 'mdx' });
+
+      const mdxPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'changelog.mdx');
+      const mdPath = path.join(CATALOG_PATH, 'events', 'OrderCreated', 'changelog.md');
+      expect(fs.existsSync(mdxPath)).toBe(true);
+      expect(fs.existsSync(mdPath)).toBe(true);
+
+      await rmChangelog('OrderCreated');
+      expect(fs.existsSync(mdxPath)).toBe(false);
+      expect(fs.existsSync(mdPath)).toBe(false);
+    });
+
+    it('throws an error if the resource does not exist', async () => {
+      await expect(rmChangelog('NonExistent')).rejects.toThrow('No resource found with id: NonExistent');
+    });
+  });
+});
diff --git a/packages/sdk/src/test/channels.test.ts b/packages/sdk/src/test/channels.test.ts
new file mode 100644
index 000000000..e44c8a5a2
--- /dev/null
+++ b/packages/sdk/src/test/channels.test.ts
@@ -0,0 +1,924 @@
+// sum.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+const CATALOG_PATH = path.join(__dirname, 'catalog-channels');
+
+const {
+  writeChannel,
+  getChannel,
+  getChannels,
+  rmChannel,
+  rmChannelById,
+  versionChannel,
+  channelHasVersion,
+  addEventToChannel,
+  writeEvent,
+  getEvent,
+  addFileToEvent,
+  addCommandToChannel,
+  writeCommand,
+  getCommand,
+  addFileToCommand,
+  addQueryToChannel,
+  writeQuery,
+  getQuery,
+  addFileToQuery,
+} = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+const mockChannel = {
+  id: 'inventory.{env}.events',
+  name: 'Inventory Channel',
+  version: '0.0.1',
+  summary: 'This is a summary',
+  markdown: '# Hello world',
+  address: 'inventory.{env}.events',
+  protocols: ['kafka'],
+  parameters: {
+    env: {
+      enum: ['dev', 'staging', 'prod'],
+      default: 'dev',
+      description: 'The environment to deploy to',
+    },
+  },
+};
+
+describe('Channels SDK', () => {
+  describe('getChannel', () => {
+    it('returns the given channel id from EventCatalog and the latest version when no version is given,', async () => {
+      await writeChannel(mockChannel);
+
+      const test = await getChannel('inventory.{env}.events');
+
+      expect(test).toEqual(mockChannel);
+    });
+
+    it('returns the given channel id from EventCatalog and the requested version when a version is given,', async () => {
+      await writeChannel(mockChannel);
+
+      await versionChannel('inventory.{env}.events');
+
+      await writeChannel({
+        id: 'inventory.{env}.events',
+        name: 'Inventory Channel',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        address: 'inventory.{env}.events',
+        protocols: ['kafka'],
+        parameters: {
+          env: {
+            enum: ['dev', 'staging', 'prod'],
+            default: 'dev',
+            description: 'The environment to deploy to',
+          },
+        },
+      });
+
+      const test = await getChannel('inventory.{env}.events', '0.0.1');
+
+      expect(test).toEqual(mockChannel);
+    });
+
+    it('returns the latest version of the channel if the version matches the latest version', async () => {
+      await writeChannel({
+        id: 'inventory.{env}.events',
+        name: 'Inventory Channel',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        address: 'inventory.{env}.events',
+        protocols: ['kafka'],
+        parameters: {
+          env: {
+            enum: ['dev', 'staging', 'prod'],
+            default: 'dev',
+            description: 'The environment to deploy to',
+          },
+        },
+      });
+
+      const test = await getChannel('inventory.{env}.events', '1.0.0');
+
+      expect(test).toEqual({
+        id: 'inventory.{env}.events',
+        name: 'Inventory Channel',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        address: 'inventory.{env}.events',
+        protocols: ['kafka'],
+        parameters: {
+          env: {
+            enum: ['dev', 'staging', 'prod'],
+            default: 'dev',
+            description: 'The environment to deploy to',
+          },
+        },
+      });
+    });
+
+    it('returns undefined if the channel is not found', async () => {
+      await expect(await getChannel('inventory.{env}.events')).toBe(undefined);
+    });
+
+    it('returns undefined if the channel is found but not the version', async () => {
+      await writeChannel({
+        id: 'inventory.{env}.events',
+        name: 'Inventory Channel',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await expect(await getChannel('inventory.{env}.events', '1.0.0')).toBe(undefined);
+    });
+  });
+
+  describe('getChannels', () => {
+    it('returns all the channels in the catalog,', async () => {
+      // versioned channel
+      await writeChannel({
+        id: 'inventory.{env}.events',
+        name: 'Inventory Channel',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        address: 'inventory.{env}.events',
+        protocols: ['kafka'],
+        parameters: {
+          env: {
+            enum: ['dev', 'staging', 'prod'],
+            default: 'dev',
+            description: 'The environment to deploy to',
+          },
+        },
+      });
+
+      // latest channel
+      await writeChannel(
+        {
+          id: 'inventory.{env}.events',
+          name: 'Inventory Channel',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          address: 'inventory.{env}.events',
+          protocols: ['kafka'],
+          parameters: {
+            env: {
+              enum: ['dev', 'staging', 'prod'],
+              default: 'dev',
+              description: 'The environment to deploy to',
+            },
+          },
+        },
+        { versionExistingContent: true }
+      );
+
+      // channel in the services folder
+      await writeChannel(
+        {
+          id: 'order.{env}.events',
+          name: 'Order Channel',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          address: 'order.{env}.events',
+          protocols: ['kafka'],
+          parameters: {
+            env: {
+              enum: ['dev', 'staging', 'prod'],
+              default: 'dev',
+              description: 'The environment to deploy to',
+            },
+          },
+        },
+        { path: '/services/OrderService' }
+      );
+
+      const channels = await getChannels();
+
+      expect(channels).toEqual(
+        expect.arrayContaining([
+          {
+            id: 'inventory.{env}.events',
+            name: 'Inventory Channel',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+            address: 'inventory.{env}.events',
+            protocols: ['kafka'],
+            parameters: {
+              env: {
+                enum: ['dev', 'staging', 'prod'],
+                default: 'dev',
+                description: 'The environment to deploy to',
+              },
+            },
+          },
+          {
+            id: 'order.{env}.events',
+            name: 'Order Channel',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+            address: 'order.{env}.events',
+            protocols: ['kafka'],
+            parameters: {
+              env: {
+                enum: ['dev', 'staging', 'prod'],
+                default: 'dev',
+                description: 'The environment to deploy to',
+              },
+            },
+          },
+          {
+            id: 'inventory.{env}.events',
+            name: 'Inventory Channel',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+            address: 'inventory.{env}.events',
+            protocols: ['kafka'],
+            parameters: {
+              env: {
+                enum: ['dev', 'staging', 'prod'],
+                default: 'dev',
+                description: 'The environment to deploy to',
+              },
+            },
+          },
+        ])
+      );
+      expect(channels).toHaveLength(3);
+    });
+
+    it('returns only the latest channels when `latestOnly` is set to true,', async () => {
+      // versioned channel
+      await writeChannel({
+        id: 'inventory.{env}.events',
+        name: 'Inventory Channel',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        address: 'inventory.{env}.events',
+        protocols: ['kafka'],
+        parameters: {
+          env: {
+            enum: ['dev', 'staging', 'prod'],
+            default: 'dev',
+            description: 'The environment to deploy to',
+          },
+        },
+      });
+
+      // latest channel
+      await writeChannel(
+        {
+          id: 'inventory.{env}.events',
+          name: 'Inventory Channel',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          address: 'inventory.{env}.events',
+          protocols: ['kafka'],
+          parameters: {
+            env: {
+              enum: ['dev', 'staging', 'prod'],
+              default: 'dev',
+              description: 'The environment to deploy to',
+            },
+          },
+        },
+        { versionExistingContent: true }
+      );
+
+      // channel in the services folder
+      await writeChannel(
+        {
+          id: 'order.{env}.events',
+          name: 'Order Channel',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          address: 'order.{env}.events',
+          protocols: ['kafka'],
+          parameters: {
+            env: {
+              enum: ['dev', 'staging', 'prod'],
+              default: 'dev',
+              description: 'The environment to deploy to',
+            },
+          },
+        },
+        { path: '/services/OrderService' }
+      );
+
+      // channel in the services folder
+      await writeChannel(
+        {
+          id: 'order.{env}.events',
+          name: 'Order Channel',
+          version: '2.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          address: 'order.{env}.events',
+          protocols: ['kafka'],
+          parameters: {
+            env: {
+              enum: ['dev', 'staging', 'prod'],
+              default: 'dev',
+              description: 'The environment to deploy to',
+            },
+          },
+        },
+        { path: '/services/OrderService', versionExistingContent: true }
+      );
+
+      const channels = await getChannels({ latestOnly: true });
+
+      expect(channels).toEqual(
+        expect.arrayContaining([
+          {
+            id: 'inventory.{env}.events',
+            name: 'Inventory Channel',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+            address: 'inventory.{env}.events',
+            protocols: ['kafka'],
+            parameters: {
+              env: {
+                enum: ['dev', 'staging', 'prod'],
+                default: 'dev',
+                description: 'The environment to deploy to',
+              },
+            },
+          },
+          {
+            id: 'order.{env}.events',
+            name: 'Order Channel',
+            version: '2.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+            address: 'order.{env}.events',
+            protocols: ['kafka'],
+            parameters: {
+              env: {
+                enum: ['dev', 'staging', 'prod'],
+                default: 'dev',
+                description: 'The environment to deploy to',
+              },
+            },
+          },
+        ])
+      );
+      expect(channels).toHaveLength(2);
+    });
+  });
+
+  describe('writeChannel', () => {
+    it('writes the given channel to EventCatalog and assumes the path if one if not given', async () => {
+      await writeChannel({
+        id: 'inventory.{env}.events',
+        name: 'Inventory Channel',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        address: 'inventory.{env}.events',
+        protocols: ['kafka'],
+        routes: [{ id: 'InventoryChannel', version: '1.0.0' }],
+        parameters: {
+          env: {
+            enum: ['dev', 'staging', 'prod'],
+            default: 'dev',
+            description: 'The environment to deploy to',
+          },
+        },
+      });
+
+      const channel = await getChannel('inventory.{env}.events');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(true);
+
+      expect(channel).toEqual({
+        id: 'inventory.{env}.events',
+        name: 'Inventory Channel',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        address: 'inventory.{env}.events',
+        protocols: ['kafka'],
+        routes: [{ id: 'InventoryChannel', version: '1.0.0' }],
+        parameters: {
+          env: {
+            enum: ['dev', 'staging', 'prod'],
+            default: 'dev',
+            description: 'The environment to deploy to',
+          },
+        },
+      });
+    });
+
+    it('writes the given channel (as md) to EventCatalog when format is md and assumes the path if one if not given', async () => {
+      await writeChannel(
+        {
+          id: 'inventory.{env}.events',
+          name: 'Inventory Channel',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          address: 'inventory.{env}.events',
+          protocols: ['kafka'],
+          parameters: {
+            env: {
+              enum: ['dev', 'staging', 'prod'],
+              default: 'dev',
+              description: 'The environment to deploy to',
+            },
+          },
+        },
+        { format: 'md' }
+      );
+
+      const channel = await getChannel('inventory.{env}.events');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.md'))).toBe(true);
+    });
+
+    it('writes the given channel to EventCatalog under the correct path when a path is given', async () => {
+      await writeChannel(mockChannel, { path: '/Inventory/InventoryChannel' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/Inventory/InventoryChannel', 'index.mdx'))).toBe(true);
+    });
+
+    it('throws an error when trying to write an channel that already exists', async () => {
+      const createChannel = async (props?: any) => writeChannel({ ...mockChannel, ...props });
+
+      await createChannel();
+
+      await expect(writeChannel(mockChannel)).rejects.toThrowError(
+        'Failed to write inventory.{env}.events (channel) as the version 0.0.1 already exists'
+      );
+    });
+
+    it('overrides the channel when trying to write an channel that already exists and override is true', async () => {
+      await writeChannel({ ...mockChannel });
+
+      await writeChannel({ ...mockChannel, markdown: 'Overridden content' }, { override: true });
+
+      const channel = await getChannel('inventory.{env}.events');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(true);
+      expect(channel.markdown).toBe('Overridden content');
+    });
+
+    describe('versionExistingContent', () => {
+      it('versions the previous channel when trying to write an channel that already exists and versionExistingContent is true and the new version number is greater than the previous one', async () => {
+        await writeChannel(mockChannel);
+
+        await writeChannel(
+          {
+            ...mockChannel,
+            version: '1.0.0',
+            markdown: 'New',
+          },
+          { versionExistingContent: true }
+        );
+
+        const channel = await getChannel('inventory.{env}.events');
+        expect(channel.version).toBe('1.0.0');
+        expect(channel.markdown).toBe('New');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events/versioned/0.0.1', 'index.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(true);
+      });
+
+      it('throws an error when trying to write an channel and versionExistingContent is true and the new version number is not greater than the previous one', async () => {
+        await writeChannel(mockChannel);
+
+        await expect(writeChannel({ ...mockChannel, version: '0.0.0' }, { versionExistingContent: true })).rejects.toThrowError(
+          'New version 0.0.0 is not greater than current version 0.0.1'
+        );
+      });
+    });
+  });
+
+  describe('rmChannel', () => {
+    it('removes a channel from eventcatalog', async () => {
+      await writeChannel(mockChannel);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(true);
+
+      await rmChannel('/inventory.{env}.events');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(false);
+    });
+  });
+
+  describe('rmChannelById', () => {
+    it('removes an channel from eventcatalog by id', async () => {
+      await writeChannel(mockChannel);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(true);
+
+      await rmChannelById('inventory.{env}.events');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(false);
+    });
+
+    it('removes an channel from eventcatalog by id and version', async () => {
+      await writeChannel(mockChannel);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(true);
+
+      await rmChannelById('inventory.{env}.events', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(false);
+    });
+
+    it('if version is given, only removes that version and not any other versions of the channel', async () => {
+      await writeChannel(mockChannel);
+
+      await versionChannel('inventory.{env}.events');
+
+      // Write the versioned channel
+      await writeChannel({
+        ...mockChannel,
+        version: '0.0.2',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events/versioned/0.0.1', 'index.mdx'))).toBe(true);
+
+      await rmChannelById('inventory.{env}.events', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events/versioned/0.0.2', 'index.mdx'))).toBe(false);
+    });
+  });
+
+  describe('versionChannel', () => {
+    it('adds the given channel to the versioned directory and removes itself from the root', async () => {
+      await writeChannel(mockChannel);
+
+      await versionChannel('inventory.{env}.events');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events/versioned/0.0.1', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(false);
+    });
+
+    // channel tends not to have any files associated with it (yet)
+    it('adds the given channel to the versioned directory and all files that are associated to it', async () => {
+      await writeChannel(mockChannel);
+
+      // Add random file in there
+      await fs.writeFileSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'schema.json'), 'SCHEMA!');
+
+      await versionChannel('inventory.{env}.events');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events/versioned/0.0.1', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events/versioned/0.0.1', 'schema.json'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'index.mdx'))).toBe(false);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'channels/inventory.{env}.events', 'schema.json'))).toBe(false);
+    });
+  });
+
+  describe('channelHasVersion', () => {
+    it('returns true when a given service and version exists in the catalog', async () => {
+      await writeChannel(mockChannel);
+
+      expect(await channelHasVersion('inventory.{env}.events', '0.0.1')).toEqual(true);
+    });
+
+    it('returns true when a semver version is given and the version exists in the catalog', async () => {
+      await writeChannel(mockChannel);
+
+      expect(await channelHasVersion('inventory.{env}.events', '0.0.x')).toEqual(true);
+    });
+
+    it('returns true when a `latest` version is given and the version exists in the catalog', async () => {
+      await writeChannel(mockChannel);
+
+      expect(await channelHasVersion('inventory.{env}.events', 'latest')).toEqual(true);
+    });
+
+    it('returns false when event does not exist in the catalog', async () => {
+      await writeChannel(mockChannel);
+
+      expect(await channelHasVersion('inventory.{env}.events', '5.0.0')).toEqual(false);
+    });
+  });
+
+  describe('adding messages to channels', () => {
+    describe('addEventToChannel', () => {
+      it('adds the channel to the given event', async () => {
+        await writeChannel(mockChannel);
+        await writeEvent({
+          id: 'InventoryCreated',
+          name: 'Inventory Created',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addEventToChannel('inventory.{env}.events', {
+          id: 'InventoryCreated',
+          version: '0.0.1',
+          parameters: {
+            env: 'dev',
+          },
+        });
+
+        const event = await getEvent('InventoryCreated');
+
+        // expect the path
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryCreated', 'index.mdx'))).toBe(true);
+
+        expect(event.channels).toEqual([
+          {
+            id: 'inventory.{env}.events',
+            version: '0.0.1',
+            parameters: {
+              env: 'dev',
+            },
+          },
+        ]);
+      });
+
+      it('adds the channel to the given event, any files that were on the event are persisted', async () => {
+        const file = { content: 'hello', fileName: 'test.txt' };
+
+        await writeChannel(mockChannel);
+        await writeEvent({
+          id: 'InventoryCreated',
+          name: 'Inventory Created',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addFileToEvent('InventoryCreated', file);
+
+        await addEventToChannel('inventory.{env}.events', {
+          id: 'InventoryCreated',
+          version: '0.0.1',
+          parameters: {
+            env: 'dev',
+          },
+        });
+
+        const event = await getEvent('InventoryCreated');
+
+        expect(event.channels).toEqual([
+          {
+            id: 'inventory.{env}.events',
+            version: '0.0.1',
+            parameters: {
+              env: 'dev',
+            },
+          },
+        ]);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryCreated', 'test.txt'))).toBe(true);
+      });
+
+      it('the folder location of the event does not change when adding a message to the event', async () => {
+        await writeChannel(mockChannel);
+        await writeEvent({
+          id: 'InventoryCreated',
+          name: 'Inventory Created',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addEventToChannel('inventory.{env}.events', {
+          id: 'InventoryCreated',
+          version: '0.0.1',
+          parameters: {
+            env: 'dev',
+          },
+        });
+
+        const pathToEvent = path.join(CATALOG_PATH, 'events', 'InventoryCreated');
+        expect(fs.existsSync(pathToEvent)).toEqual(true);
+      });
+
+      it('throws an error when message cannot be found', async () => {
+        await writeChannel(mockChannel);
+
+        await expect(
+          addEventToChannel('inventory.{env}.events', {
+            id: 'InventoryCreated',
+            version: '0.0.1',
+            parameters: {
+              env: 'dev',
+            },
+          })
+        ).rejects.toThrowError('Message InventoryCreated with version 0.0.1 not found');
+      });
+
+      it('does not create a duplicate nested copy of the event under its own index.mdx', async () => {
+        // Regression test for a path-split bug where the split argument was a
+        // template *string* (`/[\\/]+${collection}`) instead of a real regex.
+        // The literal substring never matched real paths, so split() returned
+        // the whole input and the resource ended up rewritten at
+        // <catalog>/events/<id>/index.mdx/events/<id>/index.mdx — i.e. with
+        // `index.mdx` as a directory. The fix uses a real RegExp matching
+        // both POSIX and Windows separators.
+        await writeChannel(mockChannel);
+        await writeEvent({
+          id: 'InventoryCreated',
+          name: 'Inventory Created',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addEventToChannel('inventory.{env}.events', {
+          id: 'InventoryCreated',
+          version: '0.0.1',
+          parameters: { env: 'dev' },
+        });
+
+        const canonical = path.join(CATALOG_PATH, 'events', 'InventoryCreated', 'index.mdx');
+        const duplicateNested = path.join(
+          CATALOG_PATH,
+          'events',
+          'InventoryCreated',
+          'index.mdx',
+          'events',
+          'InventoryCreated',
+          'index.mdx'
+        );
+        const indexMdxStat = fs.statSync(canonical);
+        expect(indexMdxStat.isFile()).toBe(true);
+        expect(fs.existsSync(duplicateNested)).toBe(false);
+      });
+    });
+
+    describe('addCommandToChannel', () => {
+      it('adds the channel to the given command', async () => {
+        await writeChannel(mockChannel);
+        await writeCommand({
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addCommandToChannel('inventory.{env}.events', {
+          id: 'UpdateInventory',
+          version: '0.0.1',
+          parameters: {
+            env: 'dev',
+          },
+        });
+
+        const command = await getCommand('UpdateInventory');
+
+        expect(command.channels).toEqual([
+          {
+            id: 'inventory.{env}.events',
+            version: '0.0.1',
+            parameters: {
+              env: 'dev',
+            },
+          },
+        ]);
+      });
+
+      it('adds the channel to the given command, any files that were on the command are persisted', async () => {
+        const file = { content: 'hello', fileName: 'test.txt' };
+
+        await writeChannel(mockChannel);
+        await writeCommand({
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addFileToCommand('UpdateInventory', file);
+
+        await addCommandToChannel('inventory.{env}.events', {
+          id: 'UpdateInventory',
+          version: '0.0.1',
+          parameters: {
+            env: 'dev',
+          },
+        });
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'test.txt'))).toBe(true);
+      });
+
+      it('throws an error when message cannot be found', async () => {
+        await writeChannel(mockChannel);
+
+        await expect(
+          addCommandToChannel('inventory.{env}.events', {
+            id: 'UpdateInventory',
+            version: '0.0.1',
+            parameters: {
+              env: 'dev',
+            },
+          })
+        ).rejects.toThrowError('Message UpdateInventory with version 0.0.1 not found');
+      });
+    });
+
+    describe('addQueryToChannel', () => {
+      it('adds the channel to the given query', async () => {
+        await writeChannel(mockChannel);
+        await writeQuery({
+          id: 'GetInventory',
+          name: 'Get Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addQueryToChannel('inventory.{env}.events', {
+          id: 'GetInventory',
+          version: '0.0.1',
+          parameters: {
+            env: 'dev',
+          },
+        });
+
+        const query = await getQuery('GetInventory');
+
+        expect(query.channels).toEqual([
+          {
+            id: 'inventory.{env}.events',
+            version: '0.0.1',
+            parameters: {
+              env: 'dev',
+            },
+          },
+        ]);
+      });
+
+      it('adds the channel to the given query, any files that were on the query are persisted', async () => {
+        const file = { content: 'hello', fileName: 'test.txt' };
+
+        await writeChannel(mockChannel);
+        await writeQuery({
+          id: 'GetInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addFileToQuery('GetInventory', file);
+
+        await addQueryToChannel('inventory.{env}.events', {
+          id: 'GetInventory',
+          version: '0.0.1',
+          parameters: {
+            env: 'dev',
+          },
+        });
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetInventory', 'test.txt'))).toBe(true);
+      });
+
+      it('throws an error when message cannot be found', async () => {
+        await writeChannel(mockChannel);
+
+        await expect(
+          addQueryToChannel('inventory.{env}.events', {
+            id: 'GetInventory',
+            version: '0.0.1',
+            parameters: {
+              env: 'dev',
+            },
+          })
+        ).rejects.toThrowError('Message GetInventory with version 0.0.1 not found');
+      });
+    });
+
+    // AddQueryToService
+  });
+});
diff --git a/packages/sdk/src/test/commands.test.ts b/packages/sdk/src/test/commands.test.ts
new file mode 100644
index 000000000..5334cc99e
--- /dev/null
+++ b/packages/sdk/src/test/commands.test.ts
@@ -0,0 +1,1339 @@
+// sum.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-commands');
+
+const {
+  writeCommand,
+  getCommand,
+  getCommands,
+  rmCommand,
+  rmCommandById,
+  versionCommand,
+  addFileToCommand,
+  addSchemaToCommand,
+  commandHasVersion,
+  writeCommandToService,
+  writeService,
+} = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Commands SDK', () => {
+  describe('getCommand', () => {
+    it('returns the given command id from EventCatalog and the latest version when no version is given,', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        attachments: ['https://example.com'],
+        diagrams: [{ id: 'UpdateInventoryDiagram', version: '1.0.0' }],
+      });
+
+      const test = await getCommand('UpdateInventory');
+
+      expect(test).toEqual({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        attachments: ['https://example.com'],
+        diagrams: [{ id: 'UpdateInventoryDiagram', version: '1.0.0' }],
+      });
+    });
+
+    it('returns the given command id from EventCatalog and the latest version when no version is given and the command is inside a services folder,', async () => {
+      await writeService({
+        id: 'Inventory',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles inventory',
+        markdown: '# Hello world',
+      });
+      await writeCommandToService(
+        {
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { id: 'Inventory' }
+      );
+
+      const test = await getCommand('UpdateInventory');
+
+      expect(test).toEqual({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the given command id from EventCatalog and the requested version when a version is given,', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await versionCommand('UpdateInventory');
+
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '1.0.0',
+        summary: 'This is version 1.0.0',
+        markdown: '# Hello world',
+      });
+
+      const test = await getCommand('UpdateInventory', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the latest version of the command if the version matches the latest version', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const test = await getCommand('UpdateInventory', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the command with the schema attached when the attachSchema option is set to true', async () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+        },
+      };
+
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        schemaPath: 'schema.json',
+      });
+
+      const file = { schema: JSON.stringify(schema), fileName: 'schema.json' };
+
+      await addSchemaToCommand('UpdateInventory', file);
+
+      const test = await getCommand('UpdateInventory', '0.0.1', { attachSchema: true });
+
+      expect(test.schema).toEqual(schema);
+    });
+
+    it('does not attach the schema if the attachSchema option is set to false', async () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+        },
+      };
+
+      const file = { schema: JSON.stringify(schema), fileName: 'schema.json' };
+
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        schemaPath: 'schema.json',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const test = await getCommand('UpdateInventory', '0.0.1', { attachSchema: false });
+
+      expect(test.schema).toBeUndefined();
+    });
+
+    it('returns undefined if the command is not found', async () => {
+      await expect(await getCommand('UpdateInventory')).toBe(undefined);
+    });
+
+    it('returns undefined if the command is  found but not the version', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await expect(await getCommand('UpdateInventory', '1.0.0')).toBe(undefined);
+    });
+  });
+
+  describe('getCommands', () => {
+    it('returns all the commands in the catalog,', async () => {
+      // versioned command
+      await writeCommand({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // latest command
+      await writeCommand(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { versionExistingContent: true }
+      );
+
+      // command in the services folder
+      await writeCommand(
+        {
+          id: 'OrderComplete',
+          name: 'Order Complete',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService' }
+      );
+
+      const commands = await getCommands({ latestOnly: false });
+
+      expect(commands.length).toBe(3);
+      expect(commands).toEqual(
+        expect.arrayContaining([
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'OrderComplete',
+            name: 'Order Complete',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+        ])
+      );
+    });
+    it('returns only the latest commands when `latestOnly` is set to true,', async () => {
+      // versioned command
+      await writeCommand({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // latest command
+      await writeCommand(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { versionExistingContent: true }
+      );
+
+      // command in the services folder
+      await writeCommand(
+        {
+          id: 'OrderComplete',
+          name: 'Order Complete',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService' }
+      );
+
+      // command in the services folder
+      await writeCommand(
+        {
+          id: 'OrderComplete',
+          name: 'Order Complete',
+          version: '2.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService', versionExistingContent: true }
+      );
+
+      const commands = await getCommands({ latestOnly: true });
+
+      expect(commands).toEqual(
+        expect.arrayContaining([
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'OrderComplete',
+            name: 'Order Complete',
+            version: '2.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+        ])
+      );
+
+      expect(commands.length).toBe(2);
+    });
+
+    it('returns the commands with the schema attached when the attachSchema option is set to true', async () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+        },
+      };
+
+      const file = { schema: JSON.stringify(schema), fileName: 'schema.json' };
+
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        schemaPath: 'schema.json',
+      });
+
+      await addSchemaToCommand('UpdateInventory', file);
+
+      const commands = await getCommands({ attachSchema: true });
+
+      expect(commands[0].schema).toEqual(schema);
+    });
+  });
+
+  describe('writeCommand', () => {
+    it('writes the given command to EventCatalog and assumes the path if one if not given', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const command = await getCommand('UpdateInventory');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(true);
+
+      expect(command).toEqual({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('writes the given command (as md) to EventCatalog if the format is md', async () => {
+      await writeCommand(
+        {
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { format: 'md' }
+      );
+
+      const command = await getCommand('UpdateInventory');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.md'))).toBe(true);
+    });
+
+    it('when operation is given, it writes the command with the given operation', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        operation: {
+          method: 'PUT',
+          path: '/inventory/{id}',
+          statusCodes: ['200', '404'],
+        },
+      });
+
+      const command = await getCommand('UpdateInventory');
+
+      expect(command).toEqual({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        operation: {
+          method: 'PUT',
+          path: '/inventory/{id}',
+          statusCodes: ['200', '404'],
+        },
+      });
+    });
+
+    it('when operation is given with only a method, it writes the command with the partial operation', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        operation: {
+          method: 'DELETE',
+        },
+      });
+
+      const command = await getCommand('UpdateInventory');
+
+      expect(command).toEqual({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        operation: {
+          method: 'DELETE',
+        },
+      });
+    });
+
+    it('writes the given command to EventCatalog under the correct path when a path is given', async () => {
+      await writeCommand(
+        {
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/Inventory/UpdateInventory' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/Inventory/UpdateInventory', 'index.mdx'))).toBe(true);
+    });
+
+    it('throws an error when trying to write an command that already exists', async () => {
+      const createEvent = async () =>
+        writeCommand({
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+      await createEvent();
+
+      await expect(
+        writeCommand({
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        })
+      ).rejects.toThrowError('Failed to write UpdateInventory (command) as the version 0.0.1 already exists');
+    });
+
+    describe('versionExistingContent', () => {
+      it('versions the previous command when trying to write an command that already exists and versionExistingContent is true and the new version number is greater than the previous one', async () => {
+        await writeCommand({
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await writeCommand(
+          {
+            id: 'UpdateInventory',
+            name: 'Update Inventory',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: 'New',
+          },
+          { versionExistingContent: true }
+        );
+
+        const channel = await getCommand('UpdateInventory');
+        expect(channel.version).toBe('1.0.0');
+        expect(channel.markdown).toBe('New');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory/versioned/0.0.1', 'index.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(true);
+      });
+
+      it('throws an error when trying to write an channel and versionExistingContent is true and the new version number is not greater than the previous one', async () => {
+        await writeCommand(
+          {
+            id: 'UpdateInventory',
+            name: 'Update Inventory',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: 'New',
+          },
+          { versionExistingContent: true }
+        );
+
+        await expect(
+          writeCommand(
+            {
+              id: 'UpdateInventory',
+              name: 'Update Inventory',
+              version: '0.0.0',
+              summary: 'This is a summary',
+              markdown: 'New',
+            },
+            { versionExistingContent: true }
+          )
+        ).rejects.toThrowError('New version 0.0.0 is not greater than current version 1.0.0');
+      });
+    });
+  });
+
+  describe('writeCommandToService', () => {
+    it('writes a command to the given service. When no version if given for the command the service is added to the latest service', async () => {
+      await writeService({
+        id: 'Inventory',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeCommandToService(
+        {
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { id: 'Inventory' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'index.mdx'))).toBe(true);
+    });
+
+    it('writes a command to the given service (as md). When no version if given for the command the service is added to the latest service', async () => {
+      await writeService(
+        {
+          id: 'Inventory',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        },
+        { format: 'md' }
+      );
+
+      await writeCommandToService(
+        {
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { id: 'Inventory' },
+        { format: 'md' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'index.md'))).toBe(true);
+    });
+
+    it('writes a command to the given service. When a version is given for the command the service is added to that service version', async () => {
+      await writeService({
+        id: 'Inventory',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'Service that handles inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeCommandToService(
+        {
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { id: 'Inventory', version: '1.0.0' }
+      );
+      expect(
+        fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/versioned/1.0.0/commands/UpdateInventory', 'index.mdx'))
+      ).toBe(true);
+    });
+    it('writes a command to the given service. When a version is the latest the command is added to the latest version of the service', async () => {
+      await writeService({
+        id: 'Inventory',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeCommandToService(
+        {
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { id: 'Inventory', version: 'latest' }
+      );
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'index.mdx'))).toBe(true);
+    });
+
+    it('when override is true, it overrides the command if it already exists', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // Write the first event
+      await writeCommandToService(
+        {
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'InventoryService',
+        }
+      );
+
+      await writeCommandToService(
+        {
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: 'Overridden content',
+        },
+        {
+          id: 'InventoryService',
+        },
+        {
+          override: true,
+        }
+      );
+
+      const command = await getCommand('UpdateInventory', '0.0.1');
+
+      expect(command.markdown).toBe('Overridden content');
+    });
+  });
+
+  describe('rmCommand', () => {
+    it('removes a command from eventcatalog', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(true);
+
+      await rmCommand('/UpdateInventory');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(false);
+    });
+  });
+
+  describe('rmCommandById', () => {
+    it('removes an command from eventcatalog by id', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(true);
+
+      await rmCommandById('UpdateInventory');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(false);
+    });
+
+    it('removes a command and all files in that command', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      fs.writeFileSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'schema.json'), 'SCHEMA!');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(true);
+
+      await rmCommandById('UpdateInventory');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(false);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'schema.json'))).toBe(false);
+    });
+
+    it('removes a command but keeps its files when persistFiles is set to true', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      fs.writeFileSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'schema.json'), 'SCHEMA!');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(true);
+
+      await rmCommandById('UpdateInventory', '0.0.1', true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(false);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'schema.json'))).toBe(true);
+    });
+
+    it('removes an command from eventcatalog by id and version', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(true);
+
+      await rmCommandById('UpdateInventory', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(false);
+    });
+
+    it('if version is given, only removes that version and not any other versions of the command', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await versionCommand('UpdateInventory');
+
+      // Write the versioned command
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory/versioned/0.0.1', 'index.mdx'))).toBe(true);
+
+      await rmCommandById('UpdateInventory', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory/versioned/0.0.2', 'index.mdx'))).toBe(false);
+    });
+
+    describe('when commands are within a service directory', () => {
+      it('removes an command from eventcatalog by id', async () => {
+        await writeService({
+          id: 'Inventory',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeCommandToService(
+          {
+            id: 'UpdateInventory',
+            name: 'Update Inventory',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'Inventory' }
+        );
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'index.mdx'))).toBe(true);
+
+        await rmCommandById('UpdateInventory');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'index.mdx'))).toBe(false);
+      });
+
+      it('if version is given, only removes that version and not any other versions of the command', async () => {
+        await writeService({
+          id: 'Inventory',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeCommandToService(
+          {
+            id: 'UpdateInventory',
+            name: 'Update Inventory',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'Inventory' }
+        );
+
+        await versionCommand('UpdateInventory');
+
+        // Write the versioned command
+        await writeCommandToService(
+          {
+            id: 'UpdateInventory',
+            name: 'Update Inventory',
+            version: '0.0.2',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'Inventory' }
+        );
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'index.mdx'))).toBe(true);
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory/versioned/0.0.1', 'index.mdx'))
+        ).toBe(true);
+
+        await rmCommandById('UpdateInventory', '0.0.1');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'index.mdx'))).toBe(true);
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory/versioned/0.0.2', 'index.mdx'))
+        ).toBe(false);
+      });
+    });
+  });
+
+  describe('versionCommand', () => {
+    it('adds the given command to the versioned directory and removes itself from the root', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // // Add random file in there
+      // await fs.writeFileSync(path.join(CATALOG_PATH, 'commands/Inventory/UpdateInventory', 'schema.json'), 'SCHEMA!');
+
+      await versionCommand('UpdateInventory');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory/versioned/0.0.2', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(false);
+    });
+    it('adds the given command to the versioned directory and all files that are associated to it', async () => {
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // Add random file in there
+      await fs.writeFileSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'schema.json'), 'SCHEMA!');
+
+      await versionCommand('UpdateInventory');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory/versioned/0.0.2', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory/versioned/0.0.2', 'schema.json'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'index.mdx'))).toBe(false);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'schema.json'))).toBe(false);
+    });
+
+    describe('when commands are within a service directory', () => {
+      it('adds the given command to the versioned directory and removes itself from the root', async () => {
+        await writeService({
+          id: 'Inventory',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeCommandToService(
+          {
+            id: 'UpdateInventory',
+            name: 'Update Inventory',
+            version: '0.0.2',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'Inventory' }
+        );
+
+        // // Add random file in there
+        // await fs.writeFileSync(path.join(CATALOG_PATH, 'commands/Inventory/UpdateInventory', 'schema.json'), 'SCHEMA!');
+
+        await versionCommand('UpdateInventory');
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory/versioned/0.0.2', 'index.mdx'))
+        ).toBe(true);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'index.mdx'))).toBe(false);
+      });
+      it('adds the given command to the versioned directory and all files that are associated to it', async () => {
+        await writeService({
+          id: 'Inventory',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeCommandToService(
+          {
+            id: 'UpdateInventory',
+            name: 'Update Inventory',
+            version: '0.0.2',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'Inventory' }
+        );
+
+        // Add random file in there
+        await fs.writeFileSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'schema.json'), 'SCHEMA!');
+
+        await versionCommand('UpdateInventory');
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory/versioned/0.0.2', 'index.mdx'))
+        ).toBe(true);
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory/versioned/0.0.2', 'schema.json'))
+        ).toBe(true);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'index.mdx'))).toBe(false);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'schema.json'))).toBe(false);
+      });
+    });
+  });
+
+  describe('addFileToCommand', () => {
+    it('takes a given file and writes it to the location of the given command', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addFileToCommand('UpdateInventory', file);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'test.txt'))).toBe(true);
+    });
+
+    it('takes a given file and version and writes the file to the correct location', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // version the command
+      await versionCommand('UpdateInventory');
+
+      await addFileToCommand('UpdateInventory', file, '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory/versioned/0.0.1', 'test.txt'))).toBe(true);
+    });
+
+    it('throws an error when trying to write to a command that does not exist', () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      expect(addFileToCommand('UpdateInventory', file)).rejects.toThrowError('Cannot find directory to write file to');
+    });
+
+    it('overrides the event when trying to write an event that already exists and override is true', async () => {
+      await writeCommand({
+        id: 'AdjustInventory',
+        name: 'Adjust Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeCommand(
+        {
+          id: 'AdjustInventory',
+          name: 'Adjust Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: 'Overridden content',
+        },
+        {
+          override: true,
+        }
+      );
+
+      const command = await getCommand('AdjustInventory');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/AdjustInventory', 'index.mdx'))).toBe(true);
+      expect(command.markdown).toBe('Overridden content');
+    });
+
+    describe('when commands are within a service directory', () => {
+      it('takes a given file and writes it to the location of the given command', async () => {
+        const file = { content: 'hello', fileName: 'test.txt' };
+
+        await writeService({
+          id: 'Inventory',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeCommandToService(
+          {
+            id: 'UpdateInventory',
+            name: 'Update Inventory',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'Inventory' }
+        );
+
+        await addFileToCommand('UpdateInventory', file);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'test.txt'))).toBe(true);
+      });
+
+      it('takes a given file and version and writes the file to the correct location', async () => {
+        const file = { content: 'hello', fileName: 'test.txt' };
+
+        await writeService({
+          id: 'Inventory',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeCommandToService(
+          {
+            id: 'UpdateInventory',
+            name: 'Update Inventory',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'Inventory' }
+        );
+
+        // version the command
+        await versionCommand('UpdateInventory');
+
+        await addFileToCommand('UpdateInventory', file, '0.0.1');
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory/versioned/0.0.1', 'test.txt'))
+        ).toBe(true);
+      });
+    });
+  });
+
+  describe('addSchemaToCommand', () => {
+    it('takes a given file and writes it to the location of the given command', async () => {
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "age": {
+            "type": "number"
+          }
+        }
+      }`;
+      const file = { schema, fileName: 'schema.json' };
+
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addSchemaToCommand('UpdateInventory', file);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory', 'schema.json'))).toBe(true);
+    });
+
+    it('takes a given file and version and writes the file to the correct location', async () => {
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "age": {
+            "type": "number"
+          }
+        }
+      }`;
+      const file = { schema, fileName: 'schema.json' };
+
+      await writeCommand({
+        id: 'UpdateInventory',
+        name: 'Update Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // version the command
+      await versionCommand('UpdateInventory');
+
+      await addSchemaToCommand('UpdateInventory', file, '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'commands/UpdateInventory/versioned/0.0.1', 'schema.json'))).toBe(true);
+    });
+
+    it('throws an error when trying to write to a command that does not exist', () => {
+      const file = { schema: 'hello', fileName: 'test.txt' };
+
+      expect(addSchemaToCommand('UpdateInventory', file)).rejects.toThrowError('Cannot find directory to write file to');
+    });
+
+    describe('when commands are within a service directory', () => {
+      it('takes a given file and writes it to the location of the given command', async () => {
+        const schema = `{
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "age": {
+              "type": "number"
+            }
+          }
+        }`;
+        const file = { schema, fileName: 'schema.json' };
+
+        await writeService({
+          id: 'Inventory',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeCommandToService(
+          {
+            id: 'UpdateInventory',
+            name: 'Update Inventory',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'Inventory' }
+        );
+
+        await addSchemaToCommand('UpdateInventory', file);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory', 'schema.json'))).toBe(true);
+      });
+
+      it('takes a given file and version and writes the file to the correct location', async () => {
+        const schema = `{
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "age": {
+              "type": "number"
+            }
+          }
+        }`;
+        const file = { schema, fileName: 'schema.json' };
+
+        await writeService({
+          id: 'Inventory',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeCommandToService(
+          {
+            id: 'UpdateInventory',
+            name: 'Update Inventory',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'Inventory' }
+        );
+
+        // version the command
+        await versionCommand('UpdateInventory');
+
+        await addSchemaToCommand('UpdateInventory', file, '0.0.1');
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/commands/UpdateInventory/versioned/0.0.1', 'schema.json'))
+        ).toBe(true);
+      });
+    });
+  });
+
+  describe('commandHasVersion', () => {
+    it('returns true when a given service and version exists in the catalog', async () => {
+      await writeCommand({
+        id: 'AdjustInventory',
+        name: 'Adjust Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await commandHasVersion('AdjustInventory', '0.0.1')).toEqual(true);
+    });
+
+    it('returns true when a semver version is given and the version exists in the catalog', async () => {
+      await writeCommand({
+        id: 'AdjustInventory',
+        name: 'Adjust Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await commandHasVersion('AdjustInventory', '0.0.x')).toEqual(true);
+    });
+
+    it('returns true when a `latest` version is given and the version exists in the catalog', async () => {
+      await writeCommand({
+        id: 'AdjustInventory',
+        name: 'Adjust Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await commandHasVersion('AdjustInventory', 'latest')).toEqual(true);
+    });
+
+    it('returns false when event does not exist in the catalog', async () => {
+      await writeCommand({
+        id: 'AdjustInventory',
+        name: 'Adjust Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await commandHasVersion('AdjustInventory', '5.0.0')).toEqual(false);
+    });
+  });
+});
diff --git a/packages/sdk/src/test/custom-docs.test.ts b/packages/sdk/src/test/custom-docs.test.ts
new file mode 100644
index 000000000..0b807cf9d
--- /dev/null
+++ b/packages/sdk/src/test/custom-docs.test.ts
@@ -0,0 +1,215 @@
+// sum.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-custom-docs');
+
+const { writeCustomDoc, getCustomDoc, getCustomDocs, rmCustomDoc } = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Custom Docs SDK', () => {
+  describe('getCustomDoc', () => {
+    it('returns a custom doc by the given path,', async () => {
+      // Write a custom doc
+      await writeCustomDoc(
+        {
+          title: 'Inventory Management',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          fileName: 'inventory-management',
+        },
+        { path: '/guides/inventory-management' }
+      );
+
+      const test = await getCustomDoc('/guides/inventory-management/inventory-management.mdx');
+
+      expect(test).toEqual({
+        title: 'Inventory Management',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('if the given path does not have .mdx extension, it will be added', async () => {
+      await writeCustomDoc(
+        {
+          title: 'Inventory Management',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          fileName: 'inventory-management',
+        },
+        { path: '/guides/inventory-management' }
+      );
+
+      const test = await getCustomDoc('/guides/inventory-management/inventory-management');
+
+      expect(test).toEqual({
+        title: 'Inventory Management',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+  });
+
+  describe('getCustomDocs', () => {
+    it('when no target path is given, returns all custom docs for the project', async () => {
+      await writeCustomDoc(
+        {
+          title: 'Inventory Management',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/guides/inventory-management' }
+      );
+      await writeCustomDoc(
+        {
+          title: 'How to use inventory management',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/tutorials/how-to-use-inventory-management' }
+      );
+
+      const test = await getCustomDocs();
+
+      expect(test).toEqual([
+        { title: 'How to use inventory management', summary: 'This is a summary', markdown: '# Hello world' },
+        { title: 'Inventory Management', summary: 'This is a summary', markdown: '# Hello world' },
+      ]);
+    });
+
+    it('when a target path is given, returns all custom docs for the given path', async () => {
+      await writeCustomDoc(
+        {
+          title: 'Inventory Management',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          fileName: 'inventory-management',
+        },
+        { path: '/guides/inventory-management' }
+      );
+      await writeCustomDoc(
+        {
+          title: 'How to use inventory management',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          fileName: 'how-to-use-inventory-management',
+        },
+        { path: '/tutorials/how-to-use-inventory-management' }
+      );
+
+      const tutorials = await getCustomDocs({ path: '/tutorials' });
+
+      expect(tutorials).toEqual([
+        { title: 'How to use inventory management', summary: 'This is a summary', markdown: '# Hello world' },
+      ]);
+    });
+  });
+
+  describe('writeCustomDoc', () => {
+    it('writes a custom doc to the given path', async () => {
+      await writeCustomDoc(
+        {
+          title: 'Inventory Management',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          fileName: 'inventory-management',
+        },
+        { path: '/guides/inventory-management' }
+      );
+
+      const test = await getCustomDoc('/guides/inventory-management/inventory-management');
+
+      expect(test).toEqual({
+        title: 'Inventory Management',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('if the given path does not have .mdx extension, it will be added', async () => {
+      await writeCustomDoc(
+        {
+          title: 'Inventory Management',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          fileName: 'inventory-management',
+        },
+        { path: '/guides/inventory-management' }
+      );
+
+      const test = await getCustomDoc('/guides/inventory-management/inventory-management');
+
+      expect(test).toEqual({
+        title: 'Inventory Management',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('if no filename is given, it will use the title as the filename', async () => {
+      await writeCustomDoc(
+        {
+          title: 'Inventory Management',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/guides/inventory-management' }
+      );
+
+      const test = await getCustomDoc('/guides/inventory-management/inventory-management');
+
+      expect(test).toEqual({
+        title: 'Inventory Management',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+  });
+
+  describe('rmCustomDoc', () => {
+    it('removes a custom doc at the given path', async () => {
+      await writeCustomDoc(
+        {
+          title: 'Inventory Management',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          fileName: 'inventory-management',
+        },
+        { path: '/guides/inventory-management' }
+      );
+
+      await rmCustomDoc('/guides/inventory-management/inventory-management.mdx');
+      const test = await getCustomDoc('/guides/inventory-management/inventory-management');
+
+      expect(test).toBeUndefined();
+    });
+
+    it('if no extension is given, it will be added', async () => {
+      await writeCustomDoc(
+        {
+          title: 'Inventory Management',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/guides/inventory-management' }
+      );
+
+      await rmCustomDoc('/guides/inventory-management/inventory-management');
+      const test = await getCustomDoc('/guides/inventory-management/inventory-management');
+
+      expect(test).toBeUndefined();
+    });
+  });
+});
diff --git a/packages/sdk/src/test/data-products.test.ts b/packages/sdk/src/test/data-products.test.ts
new file mode 100644
index 000000000..552cc33ef
--- /dev/null
+++ b/packages/sdk/src/test/data-products.test.ts
@@ -0,0 +1,603 @@
+// sum.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-data-products');
+
+const {
+  writeDataProduct,
+  writeDataProductToDomain,
+  getDataProduct,
+  getDataProducts,
+  rmDataProduct,
+  rmDataProductById,
+  versionDataProduct,
+  dataProductHasVersion,
+  addFileToDataProduct,
+  writeDomain,
+  getDomain,
+  versionDomain,
+} = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Data Products SDK', () => {
+  describe('getDataProduct', () => {
+    it('returns the given data product id from EventCatalog and the latest version when no version is given', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+        inputs: [{ id: 'CustomerEvent', version: '1.0.0' }],
+        outputs: [{ id: 'CustomerOutput', version: '1.0.0' }],
+      });
+
+      const test = await getDataProduct('CustomerDataProduct');
+
+      expect(test).toEqual({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+        inputs: [{ id: 'CustomerEvent', version: '1.0.0' }],
+        outputs: [{ id: 'CustomerOutput', version: '1.0.0' }],
+      });
+    });
+
+    it('returns the given data product id from EventCatalog and the requested version when a version is given', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      await versionDataProduct('CustomerDataProduct');
+
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.2',
+        summary: 'Customer data product v2',
+        markdown: '# Customer data product v2',
+      });
+
+      const test = await getDataProduct('CustomerDataProduct', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+    });
+
+    it('returns undefined when a given resource is not found', async () => {
+      const dataProduct = await getDataProduct('NonExistentDataProduct');
+      await expect(dataProduct).toEqual(undefined);
+    });
+
+    it('returns a data product from within a domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'Orders domain',
+        markdown: '# Orders domain',
+      });
+
+      await writeDataProductToDomain(
+        {
+          id: 'OrdersDataProduct',
+          name: 'Orders Data Product',
+          version: '1.0.0',
+          summary: 'Orders data product',
+          markdown: '# Orders data product',
+        },
+        { id: 'Orders' }
+      );
+
+      const dataProduct = await getDataProduct('OrdersDataProduct');
+
+      expect(dataProduct).toEqual({
+        id: 'OrdersDataProduct',
+        name: 'Orders Data Product',
+        version: '1.0.0',
+        summary: 'Orders data product',
+        markdown: '# Orders data product',
+      });
+    });
+  });
+
+  describe('getDataProducts', () => {
+    it('returns all data products from the catalog', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      await writeDataProduct({
+        id: 'SalesDataProduct',
+        name: 'Sales Data Product',
+        version: '0.0.1',
+        summary: 'Sales data product',
+        markdown: '# Sales data product',
+      });
+
+      const dataProducts = await getDataProducts();
+      expect(dataProducts).toHaveLength(2);
+      expect(dataProducts.map((dp) => dp.id).sort()).toEqual(['CustomerDataProduct', 'SalesDataProduct']);
+    });
+
+    it('returns only latest versions when latestOnly is true', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      await versionDataProduct('CustomerDataProduct');
+
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.2',
+        summary: 'Customer data product v2',
+        markdown: '# Customer data product v2',
+      });
+
+      const dataProducts = await getDataProducts({ latestOnly: true });
+      expect(dataProducts).toHaveLength(1);
+      expect(dataProducts[0].version).toBe('0.0.2');
+    });
+  });
+
+  describe('writeDataProduct', () => {
+    it('writes the given data product to the file system', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+        inputs: [{ id: 'CustomerEvent', version: '1.0.0' }],
+        outputs: [
+          {
+            id: 'CustomerOutput',
+            version: '1.0.0',
+            contract: {
+              path: '/contracts/customer.json',
+              name: 'Customer Contract',
+              type: 'json-schema',
+            },
+          },
+        ],
+      });
+
+      const dataProduct = await getDataProduct('CustomerDataProduct');
+
+      expect(dataProduct).toEqual({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+        inputs: [{ id: 'CustomerEvent', version: '1.0.0' }],
+        outputs: [
+          {
+            id: 'CustomerOutput',
+            version: '1.0.0',
+            contract: {
+              path: '/contracts/customer.json',
+              name: 'Customer Contract',
+              type: 'json-schema',
+            },
+          },
+        ],
+      });
+    });
+
+    it('writes the data product to a custom path when path is provided', async () => {
+      await writeDataProduct(
+        {
+          id: 'CustomerDataProduct',
+          name: 'Customer Data Product',
+          version: '0.0.1',
+          summary: 'Customer data product',
+          markdown: '# Customer data product',
+        },
+        { path: '/Account/CustomerDataProduct' }
+      );
+
+      const dataProduct = await getDataProduct('CustomerDataProduct');
+      expect(dataProduct).toEqual({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+    });
+
+    it('throws an error when trying to write a data product that already exists', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      await expect(
+        writeDataProduct({
+          id: 'CustomerDataProduct',
+          name: 'Customer Data Product',
+          version: '0.0.1',
+          summary: 'Customer data product',
+          markdown: '# Customer data product',
+        })
+      ).rejects.toThrowError('Failed to write CustomerDataProduct (data-product) as the version 0.0.1 already exists');
+    });
+
+    it('overrides the data product when trying to write a data product that already exists and override is true', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      await writeDataProduct(
+        {
+          id: 'CustomerDataProduct',
+          name: 'Customer Data Product',
+          version: '0.0.1',
+          summary: 'Customer data product',
+          markdown: 'Overridden content',
+        },
+        { override: true }
+      );
+
+      const dataProduct = await getDataProduct('CustomerDataProduct');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'data-products/CustomerDataProduct', 'index.mdx'))).toBe(true);
+      expect(dataProduct.markdown).toBe('Overridden content');
+    });
+
+    describe('versionExistingContent', () => {
+      it('versions the previous data product when trying to write a data product that already exists and versionExistingContent is true', async () => {
+        await writeDataProduct({
+          id: 'CustomerDataProduct',
+          name: 'Customer Data Product',
+          version: '0.0.1',
+          summary: 'Customer data product',
+          markdown: '# Customer data product',
+        });
+
+        await writeDataProduct(
+          {
+            id: 'CustomerDataProduct',
+            name: 'Customer Data Product',
+            version: '1.0.0',
+            summary: 'Customer data product',
+            markdown: 'New',
+          },
+          { versionExistingContent: true }
+        );
+
+        const dataProduct = await getDataProduct('CustomerDataProduct');
+        expect(dataProduct.version).toBe('1.0.0');
+        expect(dataProduct.markdown).toBe('New');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'data-products/CustomerDataProduct/versioned/0.0.1', 'index.mdx'))).toBe(
+          true
+        );
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'data-products/CustomerDataProduct', 'index.mdx'))).toBe(true);
+      });
+
+      it('throws an error when trying to write a data product and versionExistingContent is true and the new version is not greater than the previous one', async () => {
+        await writeDataProduct(
+          {
+            id: 'CustomerDataProduct',
+            name: 'Customer Data Product',
+            version: '1.0.0',
+            summary: 'Customer data product',
+            markdown: 'New',
+          },
+          { versionExistingContent: true }
+        );
+
+        await expect(
+          writeDataProduct(
+            {
+              id: 'CustomerDataProduct',
+              name: 'Customer Data Product',
+              version: '0.0.0',
+              summary: 'Customer data product',
+              markdown: 'New',
+            },
+            { versionExistingContent: true }
+          )
+        ).rejects.toThrowError('New version 0.0.0 is not greater than current version 1.0.0');
+      });
+    });
+
+    describe('formats', () => {
+      it('writes the data product as md when format is md', async () => {
+        await writeDataProduct(
+          {
+            id: 'CustomerDataProduct',
+            name: 'Customer Data Product',
+            version: '0.0.1',
+            summary: 'Customer data product',
+            markdown: '# Customer data product',
+          },
+          { format: 'md' }
+        );
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'data-products/CustomerDataProduct', 'index.md'))).toBe(true);
+      });
+
+      it('writes the data product as mdx when format is mdx (default)', async () => {
+        await writeDataProduct({
+          id: 'CustomerDataProduct',
+          name: 'Customer Data Product',
+          version: '0.0.1',
+          summary: 'Customer data product',
+          markdown: '# Customer data product',
+        });
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'data-products/CustomerDataProduct', 'index.mdx'))).toBe(true);
+      });
+    });
+  });
+
+  describe('writeDataProductToDomain', () => {
+    it('writes a data product to a domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'Orders domain',
+        markdown: '# Orders domain',
+      });
+
+      await writeDataProductToDomain(
+        {
+          id: 'OrdersDataProduct',
+          name: 'Orders Data Product',
+          version: '1.0.0',
+          summary: 'Orders data product',
+          markdown: '# Orders data product',
+        },
+        { id: 'Orders' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders/data-products/OrdersDataProduct', 'index.mdx'))).toBe(true);
+    });
+
+    it('writes a data product to a versioned domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'Orders domain',
+        markdown: '# Orders domain',
+      });
+
+      await versionDomain('Orders');
+
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        summary: 'Orders domain',
+        markdown: '# Orders domain',
+      });
+
+      await writeDataProductToDomain(
+        {
+          id: 'OrdersDataProduct',
+          name: 'Orders Data Product',
+          version: '1.0.0',
+          summary: 'Orders data product',
+          markdown: '# Orders data product',
+        },
+        { id: 'Orders', version: '0.0.1' }
+      );
+
+      expect(
+        fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders/versioned/0.0.1/data-products/OrdersDataProduct', 'index.mdx'))
+      ).toBe(true);
+    });
+  });
+
+  describe('versionDataProduct', () => {
+    it('versions a data product by moving it to a versioned directory', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      await versionDataProduct('CustomerDataProduct');
+
+      const versionedDataProduct = await getDataProduct('CustomerDataProduct', '0.0.1');
+      expect(versionedDataProduct).toEqual({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+    });
+  });
+
+  describe('rmDataProduct', () => {
+    it('removes a data product by its path', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      await rmDataProduct('/CustomerDataProduct');
+
+      const dataProduct = await getDataProduct('CustomerDataProduct');
+
+      await expect(dataProduct).toEqual(undefined);
+    });
+  });
+
+  describe('rmDataProductById', () => {
+    it('removes a data product by its id', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      await rmDataProductById('CustomerDataProduct');
+
+      const dataProduct = await getDataProduct('CustomerDataProduct');
+
+      await expect(dataProduct).toEqual(undefined);
+    });
+
+    it('removes a specific version of a data product by its id and version', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      await versionDataProduct('CustomerDataProduct');
+
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.2',
+        summary: 'Customer data product v2',
+        markdown: '# Customer data product v2',
+      });
+
+      await rmDataProductById('CustomerDataProduct', '0.0.1');
+
+      const oldDataProduct = await getDataProduct('CustomerDataProduct', '0.0.1');
+      expect(oldDataProduct).toEqual(undefined);
+
+      const newDataProduct = await getDataProduct('CustomerDataProduct', '0.0.2');
+      expect(newDataProduct).toEqual({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.2',
+        summary: 'Customer data product v2',
+        markdown: '# Customer data product v2',
+      });
+    });
+  });
+
+  describe('dataProductHasVersion', () => {
+    it('returns true if data product version exists', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      const hasVersion = await dataProductHasVersion('CustomerDataProduct', '0.0.1');
+      expect(hasVersion).toBe(true);
+    });
+
+    it('returns false if data product version does not exist', async () => {
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      const hasVersion = await dataProductHasVersion('CustomerDataProduct', '0.0.2');
+      expect(hasVersion).toBe(false);
+    });
+
+    it('returns false if data product does not exist', async () => {
+      const hasVersion = await dataProductHasVersion('NonExistentDataProduct', '0.0.1');
+      expect(hasVersion).toBe(false);
+    });
+  });
+
+  describe('addFileToDataProduct', () => {
+    it('takes a given file and writes it to the location of the given data product', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      await addFileToDataProduct('CustomerDataProduct', file);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'data-products/CustomerDataProduct', 'test.txt'))).toBe(true);
+    });
+
+    it('takes a given file and version and writes the file to the correct location', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeDataProduct({
+        id: 'CustomerDataProduct',
+        name: 'Customer Data Product',
+        version: '0.0.1',
+        summary: 'Customer data product',
+        markdown: '# Customer data product',
+      });
+
+      await versionDataProduct('CustomerDataProduct');
+
+      await addFileToDataProduct('CustomerDataProduct', file, '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'data-products/CustomerDataProduct/versioned/0.0.1', 'test.txt'))).toBe(true);
+    });
+
+    it('throws an error when trying to write to a data product that does not exist', () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      expect(addFileToDataProduct('NonExistentDataProduct', file)).rejects.toThrowError('Cannot find directory to write file to');
+    });
+  });
+});
diff --git a/packages/sdk/src/test/data-store.test.ts b/packages/sdk/src/test/data-store.test.ts
new file mode 100644
index 000000000..776e334f2
--- /dev/null
+++ b/packages/sdk/src/test/data-store.test.ts
@@ -0,0 +1,533 @@
+// sum.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-containers');
+
+const {
+  writeService,
+  writeDataStore,
+  getDataStore,
+  versionDataStore,
+  getDataStores,
+  rmDataStore,
+  rmDataStoreById,
+  dataStoreHasVersion,
+  addFileToDataStore,
+  writeDataStoreToService,
+} = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Data Store SDK', () => {
+  describe('getDataStore', () => {
+    it('returns the given data store id from EventCatalog and the latest version when no version is given,', async () => {
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      const test = await getDataStore('orders-db');
+
+      expect(test).toEqual({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+    });
+
+    it('returns the given entity id from EventCatalog and the requested version when a version is given,', async () => {
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      await versionDataStore('orders-db');
+
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '2.0.0',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      const test = await getDataStore('orders-db', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+    });
+
+    it('returns undefined when a given resource is not found', async () => {
+      const entity = await getDataStore('orders-db-test');
+      await expect(entity).toEqual(undefined);
+    });
+  });
+
+  describe('getDataStores', () => {
+    it('returns all data stores from the catalog', async () => {
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      await writeDataStore({
+        id: 'products-db',
+        name: 'Products Database',
+        version: '0.0.1',
+        markdown: '# Products',
+        container_type: 'database',
+      });
+
+      const dataStores = await getDataStores();
+      expect(dataStores).toHaveLength(2);
+      expect(dataStores.map((e) => e.id)).toEqual(['products-db', 'orders-db']);
+    });
+
+    it('returns only latest versions when latestOnly is true', async () => {
+      await writeDataStore({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        markdown: '# User entity',
+        container_type: 'database',
+      });
+
+      await versionDataStore('User');
+
+      await writeDataStore({
+        id: 'products-db',
+        name: 'Products Database',
+        version: '0.0.2',
+        markdown: '# Products',
+        container_type: 'database',
+      });
+
+      const dataStores = await getDataStores({ latestOnly: true });
+      expect(dataStores).toHaveLength(1);
+      expect(dataStores[0].version).toBe('0.0.2');
+    });
+  });
+
+  describe('writeDataStore', () => {
+    it('writes the given entity to the file system', async () => {
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      const entity = await getDataStore('orders-db');
+
+      expect(entity).toEqual({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+    });
+
+    it('writes the data store to a custom path when path is provided', async () => {
+      await writeDataStore(
+        {
+          id: 'orders-db',
+          name: 'Orders Database',
+          version: '0.0.1',
+          markdown: '# Orders Database in Account',
+          container_type: 'database',
+        },
+        { path: '/Account/orders-db' }
+      );
+
+      const entity = await getDataStore('orders-db');
+      expect(entity).toEqual({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders Database in Account',
+        container_type: 'database',
+      });
+    });
+  });
+
+  describe('rmDataStore', () => {
+    it('removes an data store by its path', async () => {
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      await rmDataStore('/orders-db');
+
+      const entity = await getDataStore('orders-db');
+
+      await expect(entity).toEqual(undefined);
+    });
+  });
+
+  describe('rmDataStoreById', () => {
+    it('removes an data store by its id', async () => {
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      await rmDataStoreById('orders-db');
+
+      const entity = await getDataStore('orders-db');
+
+      await expect(entity).toEqual(undefined);
+    });
+
+    it('removes a specific version of an data store by its id and version', async () => {
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      await versionDataStore('orders-db');
+
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.2',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      await rmDataStoreById('orders-db', '0.0.1');
+
+      const oldEntity = await getDataStore('orders-db', '0.0.1');
+      expect(oldEntity).toEqual(undefined);
+
+      const newEntity = await getDataStore('orders-db', '0.0.2');
+      expect(newEntity).toEqual({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.2',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+    });
+  });
+
+  describe('versionDataStore', () => {
+    it('versions an data store by moving it to a versioned directory', async () => {
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      await versionDataStore('orders-db');
+
+      const versionedEntity = await getDataStore('orders-db', '0.0.1');
+      expect(versionedEntity).toEqual({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+    });
+  });
+
+  describe('dataStoreHasVersion', () => {
+    it('returns true if data store version exists', async () => {
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      const hasVersion = await dataStoreHasVersion('orders-db', '0.0.1');
+      expect(hasVersion).toBe(true);
+    });
+
+    it('returns false if data store version does not exist', async () => {
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      const hasVersion = await dataStoreHasVersion('orders-db', '0.0.2');
+      expect(hasVersion).toBe(false);
+    });
+
+    it('returns false if data store does not exist', async () => {
+      const hasVersion = await dataStoreHasVersion('NonExistentEntity', '0.0.1');
+      expect(hasVersion).toBe(false);
+    });
+  });
+
+  describe('addFileToDataStore', () => {
+    it('takes a given file and writes it to the location of the given data store', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      await addFileToDataStore('orders-db', file);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'containers/orders-db', 'test.txt'))).toBe(true);
+    });
+
+    it('takes a given file and version and writes the file to the correct location', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      // version the event
+      await versionDataStore('orders-db');
+
+      await addFileToDataStore('orders-db', file, '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'containers/orders-db/versioned/0.0.1', 'test.txt'))).toBe(true);
+    });
+
+    it('throws an error when trying to write to a data store that does not exist', () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      expect(addFileToDataStore('orders-db', file)).rejects.toThrowError('Cannot find directory to write file to');
+    });
+
+    // describe('when events are within a service directory', () => {
+    //   it('takes a given file and writes it to the location of the given event', async () => {
+    //     const file = { content: 'hello', fileName: 'test.txt' };
+
+    //     await writeService({
+    //       id: 'InventoryService',
+    //       name: 'Inventory Service',
+    //       version: '0.0.1',
+    //       summary: 'This is a summary',
+    //       markdown: '# Hello world',
+    //     });
+
+    //     await writeEventToService(
+    //       {
+    //         id: 'InventoryAdjusted',
+    //         name: 'Inventory Adjusted',
+    //         version: '0.0.1',
+    //         summary: 'This is a summary',
+    //         markdown: '# Hello world',
+    //       },
+    //       { id: 'InventoryService' }
+    //     );
+
+    //     await addFileToDataStore('InventoryAdjusted', file);
+
+    //     expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'test.txt'))).toBe(
+    //       true
+    //     );
+    //   });
+
+    //   it('takes a given file and version and writes the file to the correct location', async () => {
+    //     const file = { content: 'hello', fileName: 'test.txt' };
+
+    //     await writeService({
+    //       id: 'InventoryService',
+    //       name: 'Inventory Service',
+    //       version: '0.0.1',
+    //       summary: 'This is a summary',
+    //       markdown: '# Hello world',
+    //     });
+
+    //     await writeEventToService(
+    //       {
+    //         id: 'InventoryAdjusted',
+    //         name: 'Inventory Adjusted',
+    //         version: '0.0.1',
+    //         summary: 'This is a summary',
+    //         markdown: '# Hello world',
+    //       },
+    //       { id: 'InventoryService' }
+    //     );
+
+    //     // version the event
+    //     await versionEvent('InventoryAdjusted');
+
+    //     await addFileToDataStore('InventoryAdjusted', file, '0.0.1');
+
+    //     expect(
+    //       fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted/versioned/0.0.1', 'test.txt'))
+    //     ).toBe(true);
+    //   });
+    // });
+  });
+
+  describe('writeDataStoreToService', () => {
+    it('writes an data store to the given service. When no version if given for the service the data store is added to the latest service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeDataStoreToService(
+        {
+          id: 'orders-db',
+          name: 'Orders Database',
+          version: '0.0.1',
+          markdown: '# Orders',
+          container_type: 'database',
+        },
+        {
+          id: 'InventoryService',
+        }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/containers/orders-db', 'index.mdx'))).toBe(true);
+    });
+    it('writes an data store to the given service. When a version is given for the service the data store is added to that service version', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+      await writeDataStoreToService(
+        {
+          id: 'orders-db',
+          name: 'Orders Database',
+          version: '0.0.1',
+          markdown: '# Orders',
+          container_type: 'database',
+        },
+        {
+          id: 'InventoryService',
+          version: '1.0.0',
+        }
+      );
+      expect(
+        fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/versioned/1.0.0/containers/orders-db', 'index.mdx'))
+      ).toBe(true);
+    });
+    it('writes an data store to the given service. When a version is the latest the data store is added to the latest version of the service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeDataStoreToService(
+        {
+          id: 'orders-db',
+          name: 'Orders Database',
+          version: '0.0.1',
+          markdown: '# Orders',
+          container_type: 'database',
+        },
+        {
+          id: 'InventoryService',
+          version: 'latest',
+        }
+      );
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService//containers/orders-db', 'index.mdx'))).toBe(true);
+    });
+
+    it('when override is true, it overrides the event if it already exists', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // Write the first event
+      await writeDataStoreToService(
+        {
+          id: 'orders-db',
+          name: 'Orders Database',
+          version: '0.0.1',
+          markdown: '# Orders',
+          container_type: 'database',
+        },
+        {
+          id: 'InventoryService',
+        }
+      );
+
+      await writeDataStoreToService(
+        {
+          id: 'orders-db',
+          name: 'Orders Database',
+          version: '0.0.1',
+          markdown: 'Overridden content',
+          container_type: 'database',
+        },
+        {
+          id: 'InventoryService',
+        },
+        {
+          override: true,
+        }
+      );
+
+      const event = await getDataStore('orders-db', '0.0.1');
+
+      expect(event.markdown).toBe('Overridden content');
+    });
+  });
+});
diff --git a/packages/sdk/src/test/diagrams.test.ts b/packages/sdk/src/test/diagrams.test.ts
new file mode 100644
index 000000000..d78170537
--- /dev/null
+++ b/packages/sdk/src/test/diagrams.test.ts
@@ -0,0 +1,347 @@
+// sum.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-diagrams');
+
+const { writeDiagram, getDiagram, getDiagrams, rmDiagram, rmDiagramById, versionDiagram, diagramHasVersion, addFileToDiagram } =
+  utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Diagrams SDK', () => {
+  describe('getDiagram', () => {
+    it('returns the given diagram id from EventCatalog and the latest version when no version is given,', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+        attachments: ['https://example.com/diagram.png'],
+      });
+
+      const test = await getDiagram('ArchitectureDiagram');
+
+      expect(test).toEqual({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+        attachments: ['https://example.com/diagram.png'],
+      });
+    });
+
+    it('returns the given diagram id from EventCatalog and the requested version when a version is given,', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+
+      await versionDiagram('ArchitectureDiagram');
+
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.2',
+        summary: 'System architecture diagram v2',
+        markdown: '# Architecture Diagram v2',
+      });
+
+      const test = await getDiagram('ArchitectureDiagram', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+    });
+
+    it('returns undefined when a given resource is not found', async () => {
+      const diagram = await getDiagram('NonExistentDiagram');
+      await expect(diagram).toEqual(undefined);
+    });
+  });
+
+  describe('getDiagrams', () => {
+    it('returns all diagrams from the catalog', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+
+      await writeDiagram({
+        id: 'DataFlowDiagram',
+        name: 'Data Flow Diagram',
+        version: '0.0.1',
+        summary: 'Data flow diagram',
+        markdown: '# Data Flow Diagram',
+      });
+
+      const diagrams = await getDiagrams();
+      expect(diagrams).toHaveLength(2);
+      expect(diagrams.map((d) => d.id).sort()).toEqual(['ArchitectureDiagram', 'DataFlowDiagram']);
+    });
+
+    it('returns only latest versions when latestOnly is true', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+
+      await versionDiagram('ArchitectureDiagram');
+
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.2',
+        summary: 'System architecture diagram v2',
+        markdown: '# Architecture Diagram v2',
+      });
+
+      const diagrams = await getDiagrams({ latestOnly: true });
+      expect(diagrams).toHaveLength(1);
+      expect(diagrams[0].version).toBe('0.0.2');
+    });
+  });
+
+  describe('writeDiagram', () => {
+    it('writes the given diagram to the file system', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+        owners: ['team-a'],
+        badges: [{ content: 'stable', backgroundColor: 'green', textColor: 'white' }],
+      });
+
+      const diagram = await getDiagram('ArchitectureDiagram');
+
+      expect(diagram).toEqual({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+        owners: ['team-a'],
+        badges: [{ content: 'stable', backgroundColor: 'green', textColor: 'white' }],
+      });
+    });
+
+    it('writes the diagram to a custom path when path is provided', async () => {
+      await writeDiagram(
+        {
+          id: 'ArchitectureDiagram',
+          name: 'Architecture Diagram',
+          version: '0.0.1',
+          summary: 'System architecture diagram',
+          markdown: '# Architecture Diagram',
+        },
+        { path: '/System/ArchitectureDiagram' }
+      );
+
+      const diagram = await getDiagram('ArchitectureDiagram');
+      expect(diagram).toEqual({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+    });
+  });
+
+  describe('rmDiagram', () => {
+    it('removes a diagram by its path', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+
+      await rmDiagram('/ArchitectureDiagram');
+
+      const diagram = await getDiagram('ArchitectureDiagram');
+
+      await expect(diagram).toEqual(undefined);
+    });
+  });
+
+  describe('rmDiagramById', () => {
+    it('removes a diagram by its id', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+
+      await rmDiagramById('ArchitectureDiagram');
+
+      const diagram = await getDiagram('ArchitectureDiagram');
+
+      await expect(diagram).toEqual(undefined);
+    });
+
+    it('removes a specific version of a diagram by its id and version', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+
+      await versionDiagram('ArchitectureDiagram');
+
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.2',
+        summary: 'System architecture diagram v2',
+        markdown: '# Architecture Diagram v2',
+      });
+
+      await rmDiagramById('ArchitectureDiagram', '0.0.1');
+
+      const oldDiagram = await getDiagram('ArchitectureDiagram', '0.0.1');
+      expect(oldDiagram).toEqual(undefined);
+
+      const newDiagram = await getDiagram('ArchitectureDiagram', '0.0.2');
+      expect(newDiagram).toEqual({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.2',
+        summary: 'System architecture diagram v2',
+        markdown: '# Architecture Diagram v2',
+      });
+    });
+  });
+
+  describe('versionDiagram', () => {
+    it('versions a diagram by moving it to a versioned directory', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+
+      await versionDiagram('ArchitectureDiagram');
+
+      const versionedDiagram = await getDiagram('ArchitectureDiagram', '0.0.1');
+      expect(versionedDiagram).toEqual({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+    });
+  });
+
+  describe('diagramHasVersion', () => {
+    it('returns true if diagram version exists', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+
+      const hasVersion = await diagramHasVersion('ArchitectureDiagram', '0.0.1');
+      expect(hasVersion).toBe(true);
+    });
+
+    it('returns false if diagram version does not exist', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+
+      const hasVersion = await diagramHasVersion('ArchitectureDiagram', '0.0.2');
+      expect(hasVersion).toBe(false);
+    });
+
+    it('returns false if diagram does not exist', async () => {
+      const hasVersion = await diagramHasVersion('NonExistentDiagram', '0.0.1');
+      expect(hasVersion).toBe(false);
+    });
+  });
+
+  describe('addFileToDiagram', () => {
+    it('adds a file to the diagram', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+
+      await addFileToDiagram('ArchitectureDiagram', { content: 'test content', fileName: 'diagram.svg' });
+
+      const diagramPath = path.join(CATALOG_PATH, 'diagrams', 'ArchitectureDiagram', 'diagram.svg');
+      expect(fs.existsSync(diagramPath)).toBe(true);
+      expect(fs.readFileSync(diagramPath, 'utf-8')).toBe('test content');
+    });
+
+    it('adds a file to a specific version of the diagram', async () => {
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.1',
+        summary: 'System architecture diagram',
+        markdown: '# Architecture Diagram',
+      });
+
+      await versionDiagram('ArchitectureDiagram');
+
+      await writeDiagram({
+        id: 'ArchitectureDiagram',
+        name: 'Architecture Diagram',
+        version: '0.0.2',
+        summary: 'System architecture diagram v2',
+        markdown: '# Architecture Diagram v2',
+      });
+
+      await addFileToDiagram('ArchitectureDiagram', { content: 'test content v1', fileName: 'diagram.svg' }, '0.0.1');
+
+      const versionedPath = path.join(CATALOG_PATH, 'diagrams', 'ArchitectureDiagram', 'versioned', '0.0.1', 'diagram.svg');
+      expect(fs.existsSync(versionedPath)).toBe(true);
+      expect(fs.readFileSync(versionedPath, 'utf-8')).toBe('test content v1');
+    });
+  });
+});
diff --git a/packages/sdk/src/test/domains.test.ts b/packages/sdk/src/test/domains.test.ts
new file mode 100644
index 000000000..335bc325f
--- /dev/null
+++ b/packages/sdk/src/test/domains.test.ts
@@ -0,0 +1,1723 @@
+// sum.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-domains');
+
+const {
+  writeDomain,
+  getDomain,
+  getDomains,
+  writeService,
+  versionDomain,
+  rmDomain,
+  rmDomainById,
+  addFileToDomain,
+  addUbiquitousLanguageToDomain,
+  getUbiquitousLanguageFromDomain,
+  domainHasVersion,
+  addServiceToDomain,
+  addAgentToDomain,
+  addSubDomainToDomain,
+  addEntityToDomain,
+  addDataProductToDomain,
+  addEventToDomain,
+  addCommandToDomain,
+  addQueryToDomain,
+} = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Domain SDK', () => {
+  describe('getDomain', () => {
+    it('returns the given domain id from EventCatalog and the latest version when no version is given,', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+        diagrams: [{ id: 'PaymentDiagram', version: '1.0.0' }],
+      });
+
+      const test = await getDomain('Payment');
+
+      expect(test).toEqual({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+        diagrams: [{ id: 'PaymentDiagram', version: '1.0.0' }],
+      });
+    });
+
+    it('returns the given domain id from EventCatalog and the requested version when a version is given,', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      await versionDomain('Payment');
+
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '1.0.0',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      const test = await getDomain('Payment', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the latest version of the domain if the version matches the latest version', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      const test = await getDomain('Payment', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns undefined when the domain is not found', async () => {
+      await expect(await getDomain('Payment')).toEqual(undefined);
+    });
+
+    it('returns undefined if the domain is found but not the version', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      await expect(await getDomain('Payment', '1.0.0')).toEqual(undefined);
+    });
+  });
+
+  describe('getDomains', () => {
+    it('returns all the domains in the catalog,', async () => {
+      // versioned domain
+      await writeDomain({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // latest domain
+      await writeDomain(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { versionExistingContent: true }
+      );
+
+      const domains = await getDomains();
+
+      expect(domains).toEqual([
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+      ]);
+    });
+
+    it('when services are nested into the domains folder it only returns the domains', async () => {
+      // versioned domain
+      await writeDomain({
+        id: 'Inventory',
+        name: 'Inventory',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeService(
+        {
+          id: 'InventoryService',
+          version: '1.0.0',
+          name: 'Inventory Service',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/domains/writeDomain' }
+      );
+
+      const domains = await getDomains();
+
+      expect(domains).toEqual([
+        {
+          id: 'Inventory',
+          name: 'Inventory',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+      ]);
+    });
+
+    it('returns only the latest domains when `latestOnly` is set to true,', async () => {
+      // versioned domain
+      await writeDomain({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // latest domain
+      await writeDomain(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { versionExistingContent: true }
+      );
+
+      // domain in the services folder
+      await writeDomain(
+        {
+          id: 'OrderComplete',
+          name: 'Order Complete',
+          version: '2.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService', versionExistingContent: true }
+      );
+
+      const domains = await getDomains({ latestOnly: true });
+
+      expect(domains).toEqual([
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+      ]);
+    });
+  });
+
+  describe('writeDomain', () => {
+    it('writes the given domain to EventCatalog and assumes the path if one if not given', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+        attachments: ['https://example.com'],
+      });
+
+      const domain = await getDomain('Payment');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(true);
+
+      expect(domain).toEqual({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+        attachments: ['https://example.com'],
+      });
+    });
+
+    it('writes the given domain (as md) to EventCatalog and assumes the path if one if not given', async () => {
+      await writeDomain(
+        {
+          id: 'Payment',
+          name: 'Payment Domain',
+          version: '0.0.1',
+          summary: 'All things to do with the payment systems',
+          markdown: '# Hello world',
+        },
+        { format: 'md' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.md'))).toBe(true);
+    });
+
+    it('writes the given domain to EventCatalog under the correct path when a path is given', async () => {
+      await writeDomain(
+        {
+          id: 'Payment',
+          name: 'Payment Domain',
+          version: '0.0.1',
+          summary: 'All things to do with the payment systems',
+          markdown: '# Hello world',
+        },
+        { path: '/Inventory/Payment' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Inventory/Payment', 'index.mdx'))).toBe(true);
+    });
+
+    it('services written to a domain are always unique', async () => {
+      await writeDomain(
+        {
+          id: 'Payment',
+          name: 'Payment Domain',
+          version: '0.0.1',
+          summary: 'All things to do with the payment systems',
+          markdown: '# Hello world',
+          services: [
+            {
+              id: 'PaymentService',
+              version: '1.0.0',
+            },
+            {
+              id: 'PaymentService',
+              version: '1.0.0',
+            },
+            {
+              id: 'PaymentService',
+              version: '1.0.0',
+            },
+          ],
+        },
+        { path: '/Inventory/InventoryService' }
+      );
+
+      const service = await getDomain('Payment');
+
+      expect(service.services).toHaveLength(1);
+
+      expect(service.services).toEqual([
+        {
+          id: 'PaymentService',
+          version: '1.0.0',
+        },
+      ]);
+    });
+
+    it('domains written to a domain are always unique', async () => {
+      await writeDomain(
+        {
+          id: 'Payment',
+          name: 'Payment Domain',
+          version: '0.0.1',
+          summary: 'All things to do with the payment systems',
+          markdown: '# Hello world',
+          domains: [
+            {
+              id: 'Inventory',
+              version: '1.0.0',
+            },
+            {
+              id: 'Inventory',
+              version: '1.0.0',
+            },
+            {
+              id: 'Orders',
+              version: '1.0.0',
+            },
+          ],
+        },
+        { path: '/Inventory/InventoryService' }
+      );
+
+      const service = await getDomain('Payment');
+
+      expect(service.domains).toHaveLength(2);
+
+      expect(service.domains).toEqual([
+        {
+          id: 'Inventory',
+          version: '1.0.0',
+        },
+        {
+          id: 'Orders',
+          version: '1.0.0',
+        },
+      ]);
+    });
+
+    it('throws an error when trying to write an domain that already exists', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      await expect(
+        writeDomain({
+          id: 'Payment',
+          name: 'Payment Domain',
+          version: '0.0.1',
+          summary: 'All things to do with the payment systems',
+          markdown: '# Hello world',
+        })
+      ).rejects.toThrowError('Failed to write Payment (domain) as the version 0.0.1 already exists');
+    });
+
+    it('overrides the domain when trying to write an domain that already exists and override is true', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      await writeDomain(
+        {
+          id: 'Payment',
+          name: 'Payment Domain',
+          version: '0.0.1',
+          summary: 'All things to do with the payment systems',
+          markdown: 'Overridden content',
+        },
+        { override: true }
+      );
+
+      const service = await getDomain('Payment');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(true);
+      expect(service.markdown).toBe('Overridden content');
+    });
+
+    describe('versionExistingContent', () => {
+      it('versions the previous domain when trying to write a domain that already exists and versionExistingContent is true and the new version number is greater than the previous one', async () => {
+        await writeDomain({
+          id: 'Payment',
+          name: 'Payment Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await writeDomain(
+          {
+            id: 'Payment',
+            name: 'Payment Domain',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: 'New',
+          },
+          { versionExistingContent: true }
+        );
+
+        const domain = await getDomain('Payment');
+        expect(domain.version).toBe('1.0.0');
+        expect(domain.markdown).toBe('New');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment/versioned/0.0.1', 'index.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(true);
+      });
+
+      it('throws an error when trying to write a domain and versionExistingContent is true and the new version number is not greater than the previous one', async () => {
+        await writeDomain(
+          {
+            id: 'Payment',
+            name: 'Payment Domain',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: 'New',
+          },
+          { versionExistingContent: true }
+        );
+
+        await expect(
+          writeDomain(
+            {
+              id: 'Payment',
+              name: 'Payment Domain',
+              version: '0.0.0',
+              summary: 'This is a summary',
+              markdown: 'New',
+            },
+            { versionExistingContent: true }
+          )
+        ).rejects.toThrowError('New version 0.0.0 is not greater than current version 1.0.0');
+      });
+    });
+  });
+
+  describe('versionDomain', () => {
+    it('adds the given domain to the versioned directory and removes itself from the root', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      await versionDomain('Payment');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment/versioned/0.0.1', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(false);
+    });
+    it('adds the given domain to the versioned directory and all files that are associated to it', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      // Add random file in there
+      await fs.writeFileSync(path.join(CATALOG_PATH, 'domains/Payment', 'schema.json'), 'SCHEMA!');
+
+      await versionDomain('Payment');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment/versioned/0.0.1', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment/versioned/0.0.1', 'schema.json'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(false);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'schema.json'))).toBe(false);
+    });
+  });
+
+  describe('rmDomain', () => {
+    it('removes a domain from eventcatalog by the given path', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(true);
+
+      await rmDomain('/Payment');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(false);
+    });
+  });
+
+  describe('rmDomainById', () => {
+    it('removes a domain from eventcatalog by id', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(true);
+
+      await rmDomainById('Payment');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(false);
+    });
+
+    it('removes a domain from eventcatalog by id and version', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(true);
+
+      await rmDomainById('Payment', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(false);
+    });
+
+    it('if version is given, only removes that version and not any other versions of the domain', async () => {
+      // write the first events
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      await versionDomain('Payment');
+
+      // Write the versioned event
+      await writeDomain({
+        id: 'Payment',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment/versioned/0.0.1', 'index.mdx'))).toBe(true);
+
+      await rmDomainById('Payment', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/InventoryAdjusted/versioned/0.0.2', 'index.mdx'))).toBe(false);
+    });
+  });
+
+  describe('addFileToDomain', () => {
+    it('takes a given file and writes it to the location of the given domain', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      await addFileToDomain('Payment', file);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'test.txt'))).toBe(true);
+    });
+
+    it('takes a given file and version and writes the file to the correct location', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      await versionDomain('Payment');
+
+      await addFileToDomain('Payment', file, '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment/versioned/0.0.1', 'test.txt'))).toBe(true);
+    });
+
+    it('throws an error when trying to write to a domain that does not exist', () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      expect(addFileToDomain('Payment', file)).rejects.toThrowError('Cannot find directory to write file to');
+    });
+  });
+
+  describe('addUbiquitousLanguageToDomain', () => {
+    it('adds an ubiquitous language file to the domain', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      await addUbiquitousLanguageToDomain('Payment', {
+        dictionary: [
+          {
+            id: 'Order',
+            name: 'Order',
+            summary: 'All things to do with the payment systems',
+            description: 'This is a description',
+            icon: 'KeyIcon',
+          },
+        ],
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Payment', 'ubiquitous-language.mdx'))).toBe(true);
+    });
+  });
+
+  describe('getUbiquitousLanguageFromDomain', () => {
+    it('returns the ubiquitous language dictionary from the domain', async () => {
+      await writeDomain({
+        id: 'Payment',
+        name: 'Payment Domain',
+        version: '0.0.1',
+        summary: 'All things to do with the payment systems',
+        markdown: '# Hello world',
+      });
+
+      await addUbiquitousLanguageToDomain('Payment', {
+        dictionary: [
+          {
+            id: 'Order',
+            name: 'Order',
+            summary: 'All things to do with the payment systems',
+            description: 'This is a description',
+            icon: 'KeyIcon',
+          },
+          {
+            id: 'Inventory',
+            name: 'Inventory',
+            summary: 'All things to do with the inventory',
+            description: 'This is a description',
+            icon: 'KeyIcon',
+          },
+        ],
+      });
+
+      const ubiquitousLanguage = await getUbiquitousLanguageFromDomain('Payment');
+
+      expect(ubiquitousLanguage).toEqual({
+        dictionary: [
+          {
+            id: 'Order',
+            name: 'Order',
+            summary: 'All things to do with the payment systems',
+            description: 'This is a description',
+            icon: 'KeyIcon',
+          },
+          {
+            id: 'Inventory',
+            name: 'Inventory',
+            summary: 'All things to do with the inventory',
+            description: 'This is a description',
+            icon: 'KeyIcon',
+          },
+        ],
+      });
+    });
+  });
+  describe('domainHasVersion', () => {
+    it('returns true when a given service and version exists in the catalog', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await domainHasVersion('Orders', '0.0.1')).toEqual(true);
+    });
+
+    it('returns true when a semver version is given and the version exists in the catalog', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await domainHasVersion('Orders', '0.0.x')).toEqual(true);
+    });
+
+    it('returns true when a `latest` version is given and the version exists in the catalog', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await domainHasVersion('Orders', 'latest')).toEqual(true);
+    });
+
+    it('returns false when domain does not exist in the catalog', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await domainHasVersion('Orders', '5.0.0')).toEqual(false);
+    });
+  });
+
+  describe('addServiceToDomain', () => {
+    it('adds a service to the domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addServiceToDomain('Orders', { id: 'Order Service', version: '2.0.0' });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.services).toEqual([{ id: 'Order Service', version: '2.0.0' }]);
+    });
+
+    it('adds a service to the domain, if the extension of the domain is `md` then the extension is maintained', async () => {
+      await writeDomain(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { format: 'md' }
+      );
+
+      await addServiceToDomain('Orders', { id: 'Order Service', version: '2.0.0' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders', 'index.md'))).toBe(true);
+    });
+
+    it('adds a service to the domain, if the extension of the domain is `mdx (default)` then the extension is maintained', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addServiceToDomain('Orders', { id: 'Order Service', version: '2.0.0' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders', 'index.mdx'))).toBe(true);
+    });
+
+    it('does not add a service to the domain if the service is already on the list', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        services: [{ id: 'Order Service', version: '2.0.0' }],
+      });
+
+      await addServiceToDomain('Orders', { id: 'Order Service', version: '2.0.0' });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.services).toEqual([{ id: 'Order Service', version: '2.0.0' }]);
+    });
+
+    it('preserves the domain location when the domain is nested inside another domain (subdomain)', async () => {
+      // Create parent domain
+      await writeDomain({
+        id: 'E-Commerce',
+        name: 'E-Commerce Domain',
+        version: '0.0.1',
+        summary: 'Parent domain',
+        markdown: '# E-Commerce',
+        domains: [{ id: 'Orders', version: '0.0.1' }],
+      });
+
+      // Create subdomain inside parent domain folder
+      await writeDomain(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'Subdomain',
+          markdown: '# Orders',
+        },
+        { path: 'E-Commerce/domains' }
+      );
+
+      await addServiceToDomain('Orders', { id: 'Order Service', version: '2.0.0' });
+
+      // Verify the subdomain is still in the correct location
+      const subdomainFile = path.join(CATALOG_PATH, 'domains', 'E-Commerce', 'domains', 'Orders', 'index.mdx');
+      expect(fs.existsSync(subdomainFile)).toBe(true);
+
+      // Verify it was NOT relocated to the top level
+      const topLevelFile = path.join(CATALOG_PATH, 'domains', 'Orders', 'index.mdx');
+      expect(fs.existsSync(topLevelFile)).toBe(false);
+
+      // Verify the service was added
+      const subdomain = await getDomain('Orders');
+      expect(subdomain.services).toEqual([{ id: 'Order Service', version: '2.0.0' }]);
+    });
+  });
+
+  describe('addAgentToDomain', () => {
+    it('adds an agent to the domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addAgentToDomain('Orders', { id: 'OrderSupportAgent', version: '1.0.0' });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.agents).toEqual([{ id: 'OrderSupportAgent', version: '1.0.0' }]);
+    });
+
+    it('does not add an agent to the domain if the agent is already on the list', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        agents: [{ id: 'OrderSupportAgent', version: '1.0.0' }],
+      });
+
+      await addAgentToDomain('Orders', { id: 'OrderSupportAgent', version: '1.0.0' });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.agents).toEqual([{ id: 'OrderSupportAgent', version: '1.0.0' }]);
+    });
+  });
+
+  describe('addSubDomainToDomain', () => {
+    it('adds a subdomain to the domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addSubDomainToDomain('Orders', { id: 'Inventory', version: '1.0.0' });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.domains).toEqual([{ id: 'Inventory', version: '1.0.0' }]);
+    });
+
+    it('adds a subdomain to the domain, if the extension of the domain is `md` then the extension is maintained', async () => {
+      await writeDomain(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { format: 'md' }
+      );
+
+      await addSubDomainToDomain('Orders', { id: 'Inventory', version: '1.0.0' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders', 'index.md'))).toBe(true);
+    });
+
+    it('adds a subdomain to the domain, if the extension of the domain is `mdx (default)` then the extension is maintained', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addSubDomainToDomain('Orders', { id: 'Inventory', version: '1.0.0' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders', 'index.mdx'))).toBe(true);
+    });
+
+    it('does not add a subdomain to the domain if the subdomain is already on the list', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        domains: [{ id: 'Inventory', version: '1.0.0' }],
+      });
+
+      await addSubDomainToDomain('Orders', { id: 'Inventory', version: '1.0.0' });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.domains).toEqual([{ id: 'Inventory', version: '1.0.0' }]);
+    });
+
+    it('preserves the domain location when the domain is nested inside another domain (subdomain)', async () => {
+      // Create parent domain
+      await writeDomain({
+        id: 'E-Commerce',
+        name: 'E-Commerce Domain',
+        version: '0.0.1',
+        summary: 'Parent domain',
+        markdown: '# E-Commerce',
+        domains: [{ id: 'Orders', version: '0.0.1' }],
+      });
+
+      // Create subdomain inside parent domain folder
+      await writeDomain(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'Subdomain',
+          markdown: '# Orders',
+        },
+        { path: 'E-Commerce/domains' }
+      );
+
+      await addSubDomainToDomain('Orders', { id: 'Inventory', version: '1.0.0' });
+
+      // Verify the subdomain is still in the correct location
+      const subdomainFile = path.join(CATALOG_PATH, 'domains', 'E-Commerce', 'domains', 'Orders', 'index.mdx');
+      expect(fs.existsSync(subdomainFile)).toBe(true);
+
+      // Verify it was NOT relocated to the top level
+      const topLevelFile = path.join(CATALOG_PATH, 'domains', 'Orders', 'index.mdx');
+      expect(fs.existsSync(topLevelFile)).toBe(false);
+
+      // Verify the subdomain was added
+      const subdomain = await getDomain('Orders');
+      expect(subdomain.domains).toEqual([{ id: 'Inventory', version: '1.0.0' }]);
+    });
+  });
+
+  describe('addEntityToDomain', () => {
+    it('adds an entity to the domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addEntityToDomain('Orders', { id: 'User', version: '1.0.0' });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.entities).toEqual([{ id: 'User', version: '1.0.0' }]);
+    });
+
+    it('adds multiple entities to the domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addEntityToDomain('Orders', { id: 'User', version: '1.0.0' });
+      await addEntityToDomain('Orders', { id: 'Product', version: '2.0.0' });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.entities).toEqual([
+        { id: 'User', version: '1.0.0' },
+        { id: 'Product', version: '2.0.0' },
+      ]);
+    });
+
+    it('adds an entity to the domain, if the extension of the domain is `md` then the extension is maintained', async () => {
+      await writeDomain(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { format: 'md' }
+      );
+
+      await addEntityToDomain('Orders', { id: 'User', version: '1.0.0' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders', 'index.md'))).toBe(true);
+    });
+
+    it('adds an entity to the domain, if the extension of the domain is `mdx (default)` then the extension is maintained', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addEntityToDomain('Orders', { id: 'User', version: '1.0.0' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders', 'index.mdx'))).toBe(true);
+    });
+
+    it('does not add an entity to the domain if the entity is already on the list', async () => {
+      await writeDomain({
+        id: 'Orders3',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        entities: [{ id: 'User', version: '1.0.0' }],
+      });
+
+      await addEntityToDomain('Orders3', { id: 'User', version: '1.0.0' });
+
+      const domain = await getDomain('Orders3');
+
+      expect(domain.entities).toEqual([{ id: 'User', version: '1.0.0' }]);
+    });
+
+    it('adds an entity to a specific version of the domain', async () => {
+      await writeDomain({
+        id: 'Orders4',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await versionDomain('Orders4');
+
+      await writeDomain({
+        id: 'Orders4',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addEntityToDomain('Orders4', { id: 'User', version: '1.0.0' }, '0.0.1');
+
+      const versionedDomain = await getDomain('Orders4', '0.0.1');
+      const latestDomain = await getDomain('Orders4');
+
+      expect(versionedDomain.entities).toEqual([{ id: 'User', version: '1.0.0' }]);
+    });
+  });
+
+  describe('addDataProductToDomain', () => {
+    it('adds a data product to the domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addDataProductToDomain('Orders', { id: 'CustomerDataProduct', version: '1.0.0' });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.dataProducts).toEqual([{ id: 'CustomerDataProduct', version: '1.0.0' }]);
+    });
+
+    it('adds multiple data products to the domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addDataProductToDomain('Orders', { id: 'CustomerDataProduct', version: '1.0.0' });
+      await addDataProductToDomain('Orders', { id: 'SalesDataProduct', version: '2.0.0' });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.dataProducts).toEqual([
+        { id: 'CustomerDataProduct', version: '1.0.0' },
+        { id: 'SalesDataProduct', version: '2.0.0' },
+      ]);
+    });
+
+    it('adds a data product to the domain, if the extension of the domain is `md` then the extension is maintained', async () => {
+      await writeDomain(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { format: 'md' }
+      );
+
+      await addDataProductToDomain('Orders', { id: 'CustomerDataProduct', version: '1.0.0' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders', 'index.md'))).toBe(true);
+    });
+
+    it('adds a data product to the domain, if the extension of the domain is `mdx (default)` then the extension is maintained', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addDataProductToDomain('Orders', { id: 'CustomerDataProduct', version: '1.0.0' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders', 'index.mdx'))).toBe(true);
+    });
+
+    it('does not add a data product to the domain if the data product is already on the list', async () => {
+      await writeDomain({
+        id: 'Orders6',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        dataProducts: [{ id: 'CustomerDataProduct', version: '1.0.0' }],
+      });
+
+      await addDataProductToDomain('Orders6', { id: 'CustomerDataProduct', version: '1.0.0' });
+
+      const domain = await getDomain('Orders6');
+
+      expect(domain.dataProducts).toEqual([{ id: 'CustomerDataProduct', version: '1.0.0' }]);
+    });
+
+    it('adds a data product to a specific version of the domain', async () => {
+      await writeDomain({
+        id: 'Orders5',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await versionDomain('Orders5');
+
+      await writeDomain({
+        id: 'Orders5',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addDataProductToDomain('Orders5', { id: 'CustomerDataProduct', version: '1.0.0' }, '0.0.1');
+
+      const versionedDomain = await getDomain('Orders5', '0.0.1');
+
+      expect(versionedDomain.dataProducts).toEqual([{ id: 'CustomerDataProduct', version: '1.0.0' }]);
+    });
+  });
+
+  describe('addMessageToDomain', () => {
+    describe('sends', () => {
+      it('adds an event to the sends of an existing domain', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addEventToDomain('Orders', 'sends', { id: 'OrderCreated', version: '1.0.0' });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.sends).toEqual([{ id: 'OrderCreated', version: '1.0.0' }]);
+      });
+
+      it('adds a command to the sends of an existing domain', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addCommandToDomain('Orders', 'sends', { id: 'ProcessOrder', version: '1.0.0' });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.sends).toEqual([{ id: 'ProcessOrder', version: '1.0.0' }]);
+      });
+
+      it('adds a query to the sends of an existing domain', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addQueryToDomain('Orders', 'sends', { id: 'GetOrderStatus', version: '1.0.0' });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.sends).toEqual([{ id: 'GetOrderStatus', version: '1.0.0' }]);
+      });
+
+      it('does not add duplicate sends (same id and version)', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addEventToDomain('Orders', 'sends', { id: 'OrderCreated', version: '1.0.0' });
+        await addEventToDomain('Orders', 'sends', { id: 'OrderCreated', version: '1.0.0' });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.sends).toEqual([{ id: 'OrderCreated', version: '1.0.0' }]);
+      });
+
+      it('preserves existing sends when adding new ones', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          sends: [{ id: 'ExistingEvent', version: '1.0.0' }],
+        });
+
+        await addEventToDomain('Orders', 'sends', { id: 'OrderCreated', version: '1.0.0' });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.sends).toEqual([
+          { id: 'ExistingEvent', version: '1.0.0' },
+          { id: 'OrderCreated', version: '1.0.0' },
+        ]);
+      });
+    });
+
+    describe('receives', () => {
+      it('adds an event to the receives of an existing domain', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addEventToDomain('Orders', 'receives', { id: 'PaymentProcessed', version: '1.0.0' });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.receives).toEqual([{ id: 'PaymentProcessed', version: '1.0.0' }]);
+      });
+
+      it('adds a command to the receives of an existing domain', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addCommandToDomain('Orders', 'receives', { id: 'CancelOrder', version: '1.0.0' });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.receives).toEqual([{ id: 'CancelOrder', version: '1.0.0' }]);
+      });
+
+      it('adds a query to the receives of an existing domain', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addQueryToDomain('Orders', 'receives', { id: 'GetInventory', version: '1.0.0' });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.receives).toEqual([{ id: 'GetInventory', version: '1.0.0' }]);
+      });
+
+      it('does not add duplicate receives (same id and version)', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addEventToDomain('Orders', 'receives', { id: 'PaymentProcessed', version: '1.0.0' });
+        await addEventToDomain('Orders', 'receives', { id: 'PaymentProcessed', version: '1.0.0' });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.receives).toEqual([{ id: 'PaymentProcessed', version: '1.0.0' }]);
+      });
+
+      it('preserves existing receives when adding new ones', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          receives: [{ id: 'ExistingEvent', version: '1.0.0' }],
+        });
+
+        await addEventToDomain('Orders', 'receives', { id: 'PaymentProcessed', version: '1.0.0' });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.receives).toEqual([
+          { id: 'ExistingEvent', version: '1.0.0' },
+          { id: 'PaymentProcessed', version: '1.0.0' },
+        ]);
+      });
+    });
+
+    describe('error handling', () => {
+      it('throws an error for invalid direction', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await expect(addEventToDomain('Orders', 'invalid', { id: 'OrderCreated', version: '1.0.0' })).rejects.toThrow(
+          "Direction invalid is invalid, only 'receives' and 'sends' are supported"
+        );
+      });
+
+      it('throws an error when domain does not exist', async () => {
+        await expect(addEventToDomain('NonExistent', 'sends', { id: 'OrderCreated', version: '1.0.0' })).rejects.toThrow();
+      });
+    });
+
+    describe('fields support on sends and receives', () => {
+      it('persists fields when writing a domain with sends that declare produced fields', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          sends: [{ id: 'OrderCreated', version: '1.0.0', fields: ['orderId', 'userId', 'totalAmount'] }],
+        });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.sends).toEqual([{ id: 'OrderCreated', version: '1.0.0', fields: ['orderId', 'userId', 'totalAmount'] }]);
+      });
+
+      it('persists fields when writing a domain with receives that declare consumed fields', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          receives: [{ id: 'PaymentProcessed', version: '1.0.0', fields: ['orderId', 'amount', 'status'] }],
+        });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.receives).toEqual([{ id: 'PaymentProcessed', version: '1.0.0', fields: ['orderId', 'amount', 'status'] }]);
+      });
+
+      it('includes fields when adding an event to a domain sends', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addEventToDomain('Orders', 'sends', {
+          id: 'OrderCreated',
+          version: '1.0.0',
+          fields: ['orderId', 'userId'],
+        });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.sends).toEqual([{ id: 'OrderCreated', version: '1.0.0', fields: ['orderId', 'userId'] }]);
+      });
+
+      it('includes fields when adding an event to a domain receives', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addEventToDomain('Orders', 'receives', {
+          id: 'PaymentProcessed',
+          version: '1.0.0',
+          fields: ['orderId', 'amount', 'currency'],
+        });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.receives).toEqual([
+          { id: 'PaymentProcessed', version: '1.0.0', fields: ['orderId', 'amount', 'currency'] },
+        ]);
+      });
+
+      it('preserves existing fields on receives when adding a new message', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          receives: [{ id: 'PaymentProcessed', version: '1.0.0', fields: ['orderId', 'amount'] }],
+        });
+
+        await addEventToDomain('Orders', 'receives', {
+          id: 'ShipmentDelivered',
+          version: '1.0.0',
+          fields: ['shipmentId', 'orderId'],
+        });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.receives).toEqual([
+          { id: 'PaymentProcessed', version: '1.0.0', fields: ['orderId', 'amount'] },
+          { id: 'ShipmentDelivered', version: '1.0.0', fields: ['shipmentId', 'orderId'] },
+        ]);
+      });
+
+      it('does not include fields property when fields are not provided', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addEventToDomain('Orders', 'sends', { id: 'OrderCreated', version: '1.0.0' });
+
+        const domain = await getDomain('Orders');
+
+        expect(domain.sends).toEqual([{ id: 'OrderCreated', version: '1.0.0' }]);
+        expect(domain.sends![0]).not.toHaveProperty('fields');
+      });
+    });
+
+    describe('file handling', () => {
+      it('preserves .md format when adding messages', async () => {
+        await writeDomain(
+          {
+            id: 'Orders',
+            name: 'Orders Domain',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { format: 'md' }
+        );
+
+        await addEventToDomain('Orders', 'sends', { id: 'OrderCreated', version: '1.0.0' });
+
+        const domainFile = path.join(CATALOG_PATH, 'domains', 'Orders', 'index.md');
+        expect(fs.existsSync(domainFile)).toBe(true);
+      });
+
+      it('preserves .mdx format when adding messages', async () => {
+        await writeDomain(
+          {
+            id: 'Orders',
+            name: 'Orders Domain',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { format: 'mdx' }
+        );
+
+        await addEventToDomain('Orders', 'sends', { id: 'OrderCreated', version: '1.0.0' });
+
+        const domainFile = path.join(CATALOG_PATH, 'domains', 'Orders', 'index.mdx');
+        expect(fs.existsSync(domainFile)).toBe(true);
+      });
+
+      it('works with versioned domains', async () => {
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await versionDomain('Orders');
+
+        await writeDomain({
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await addEventToDomain('Orders', 'sends', { id: 'OrderCreated', version: '1.0.0' }, '0.0.1');
+
+        const versionedDomain = await getDomain('Orders', '0.0.1');
+
+        expect(versionedDomain.sends).toEqual([{ id: 'OrderCreated', version: '1.0.0' }]);
+      });
+
+      it('works with domains nested inside other domains (subdomains)', async () => {
+        // Create parent domain with a subdomain
+        await writeDomain({
+          id: 'E-Commerce',
+          name: 'E-Commerce Domain',
+          version: '0.0.1',
+          summary: 'Parent domain',
+          markdown: '# E-Commerce',
+          domains: [{ id: 'Orders', version: '0.0.1' }],
+        });
+
+        // Create subdomain inside parent domain folder
+        await writeDomain(
+          {
+            id: 'Orders',
+            name: 'Orders Domain',
+            version: '0.0.1',
+            summary: 'Subdomain',
+            markdown: '# Orders',
+          },
+          { path: 'E-Commerce/domains' }
+        );
+
+        // Add event to subdomain
+        await addEventToDomain('Orders', 'sends', { id: 'OrderCreated', version: '1.0.0' });
+
+        // Verify the subdomain is still in the correct location
+        const subdomainFile = path.join(CATALOG_PATH, 'domains', 'E-Commerce', 'domains', 'Orders', 'index.mdx');
+        expect(fs.existsSync(subdomainFile)).toBe(true);
+
+        // Verify the event was added
+        const subdomain = await getDomain('Orders');
+        expect(subdomain.sends).toEqual([{ id: 'OrderCreated', version: '1.0.0' }]);
+      });
+    });
+  });
+
+  describe('writeDomain with sends/receives', () => {
+    it('deduplicates sends when writing domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        sends: [
+          { id: 'OrderCreated', version: '1.0.0' },
+          { id: 'OrderCreated', version: '1.0.0' },
+          { id: 'OrderShipped', version: '1.0.0' },
+        ],
+      });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.sends).toEqual([
+        { id: 'OrderCreated', version: '1.0.0' },
+        { id: 'OrderShipped', version: '1.0.0' },
+      ]);
+    });
+
+    it('deduplicates receives when writing domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        receives: [
+          { id: 'PaymentProcessed', version: '1.0.0' },
+          { id: 'PaymentProcessed', version: '1.0.0' },
+          { id: 'InventoryChecked', version: '1.0.0' },
+        ],
+      });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.receives).toEqual([
+        { id: 'PaymentProcessed', version: '1.0.0' },
+        { id: 'InventoryChecked', version: '1.0.0' },
+      ]);
+    });
+
+    it('preserves sends and receives when writing domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        receives: [{ id: 'PaymentProcessed', version: '1.0.0' }],
+      });
+
+      const domain = await getDomain('Orders');
+
+      expect(domain.sends).toEqual([{ id: 'OrderCreated', version: '1.0.0' }]);
+      expect(domain.receives).toEqual([{ id: 'PaymentProcessed', version: '1.0.0' }]);
+    });
+  });
+});
diff --git a/packages/sdk/src/test/dsl/commands.test.ts b/packages/sdk/src/test/dsl/commands.test.ts
new file mode 100644
index 000000000..95a2f6601
--- /dev/null
+++ b/packages/sdk/src/test/dsl/commands.test.ts
@@ -0,0 +1,208 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-dsl-commands');
+
+const { toDSL, writeTeam, writeUser } = utils(CATALOG_PATH);
+
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('toDSL - commands', () => {
+  it('serializes a basic command', async () => {
+    const dsl = await toDSL(
+      { id: 'CreateOrder', name: 'Create Order', version: '1.0.0', summary: 'Creates a new order', markdown: '' },
+      { type: 'command' }
+    );
+
+    expect(dsl).toBe(`command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+  summary "Creates a new order"
+}`);
+  });
+
+  it('serializes a command with owners and schema', async () => {
+    const dsl = await toDSL(
+      {
+        id: 'CreateOrder',
+        name: 'Create Order',
+        version: '2.0.0',
+        owners: ['api-team'],
+        schemaPath: 'create-order.avsc',
+        markdown: '',
+      },
+      { type: 'command' }
+    );
+
+    expect(dsl).toBe(`command CreateOrder {
+  version 2.0.0
+  name "Create Order"
+  owner api-team
+}`);
+  });
+
+  it('serializes a command with no body fields as inline declaration', async () => {
+    const dsl = await toDSL({ id: 'CreateOrder', name: '', version: '', markdown: '' }, { type: 'command' });
+
+    expect(dsl).toBe('command CreateOrder');
+  });
+
+  it('serializes an array of commands', async () => {
+    const dsl = await toDSL(
+      [
+        { id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' },
+        { id: 'CancelOrder', name: 'Cancel Order', version: '1.0.0', markdown: '' },
+      ],
+      { type: 'command' }
+    );
+
+    expect(dsl).toBe(`command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+}
+
+command CancelOrder {
+  version 1.0.0
+  name "Cancel Order"
+}`);
+  });
+
+  it('deduplicates commands in array by id and version', async () => {
+    const dsl = await toDSL(
+      [
+        { id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' },
+        { id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' },
+      ],
+      { type: 'command' }
+    );
+
+    expect(dsl).toBe(`command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+}`);
+  });
+
+  describe('hydrate', () => {
+    it('hydrates a command with a team owner', async () => {
+      await writeTeam({ id: 'api-team', name: 'API Team', markdown: '' });
+
+      const dsl = await toDSL(
+        { id: 'CreateOrder', name: 'Create Order', version: '1.0.0', owners: ['api-team'], markdown: '' },
+        { type: 'command', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team api-team {
+  name "API Team"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+  owner api-team
+}`);
+    });
+
+    it('hydrates a command with a user owner', async () => {
+      await writeUser({
+        id: 'jdoe',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jdoe.png',
+        role: 'Engineer',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        { id: 'CreateOrder', name: 'Create Order', version: '1.0.0', owners: ['jdoe'], markdown: '' },
+        { type: 'command', hydrate: true }
+      );
+
+      expect(dsl).toBe(`user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+  role "Engineer"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+  owner jdoe
+}`);
+    });
+
+    it('hydrates a command with both team and user owners', async () => {
+      await writeTeam({ id: 'api-team', name: 'API Team', markdown: '' });
+      await writeUser({ id: 'jdoe', name: 'Jane Doe', avatarUrl: 'https://example.com/jdoe.png', markdown: '' });
+
+      const dsl = await toDSL(
+        { id: 'CreateOrder', name: 'Create Order', version: '1.0.0', owners: ['api-team', 'jdoe'], markdown: '' },
+        { type: 'command', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team api-team {
+  name "API Team"
+}
+
+user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+  owner api-team
+  owner jdoe
+}`);
+    });
+
+    it('deduplicates owners across an array of commands', async () => {
+      await writeTeam({ id: 'api-team', name: 'API Team', markdown: '' });
+
+      const dsl = await toDSL(
+        [
+          { id: 'CreateOrder', name: 'Create Order', version: '1.0.0', owners: ['api-team'], markdown: '' },
+          { id: 'CancelOrder', name: 'Cancel Order', version: '1.0.0', owners: ['api-team'], markdown: '' },
+        ],
+        { type: 'command', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team api-team {
+  name "API Team"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+  owner api-team
+}
+
+command CancelOrder {
+  version 1.0.0
+  name "Cancel Order"
+  owner api-team
+}`);
+    });
+
+    it('skips owners that cannot be resolved', async () => {
+      const dsl = await toDSL(
+        { id: 'CreateOrder', name: 'Create Order', version: '1.0.0', owners: ['nonexistent'], markdown: '' },
+        { type: 'command', hydrate: true }
+      );
+
+      expect(dsl).toBe(`command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+  owner nonexistent
+}`);
+    });
+  });
+});
diff --git a/packages/sdk/src/test/dsl/domains.test.ts b/packages/sdk/src/test/dsl/domains.test.ts
new file mode 100644
index 000000000..1dd8495bd
--- /dev/null
+++ b/packages/sdk/src/test/dsl/domains.test.ts
@@ -0,0 +1,1016 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-dsl-domains');
+
+const { writeEvent, writeCommand, writeService, writeChannel, writeTeam, writeUser, toDSL } = utils(CATALOG_PATH);
+
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('toDSL - domains', () => {
+  it('serializes a basic domain', async () => {
+    const dsl = await toDSL(
+      { id: 'Orders', name: 'Orders Domain', version: '1.0.0', summary: 'Manages order lifecycle', markdown: '' },
+      { type: 'domain' }
+    );
+
+    expect(dsl).toBe(`domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  summary "Manages order lifecycle"
+}`);
+  });
+
+  it('serializes a domain with owners', async () => {
+    const dsl = await toDSL(
+      { id: 'Orders', name: 'Orders Domain', version: '1.0.0', owners: ['orders-team'], markdown: '' },
+      { type: 'domain' }
+    );
+
+    expect(dsl).toBe(`domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  owner orders-team
+}`);
+  });
+
+  it('serializes a domain with service references', async () => {
+    const dsl = await toDSL(
+      {
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        services: [
+          { id: 'OrderService', version: '1.0.0' },
+          { id: 'PaymentService', version: '2.0.0' },
+        ],
+        markdown: '',
+      },
+      { type: 'domain' }
+    );
+
+    expect(dsl).toBe(`domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  service OrderService@1.0.0
+  service PaymentService@2.0.0
+}`);
+  });
+
+  it('serializes a domain with service references without version', async () => {
+    const dsl = await toDSL(
+      { id: 'Orders', name: 'Orders Domain', version: '1.0.0', services: [{ id: 'OrderService' }], markdown: '' },
+      { type: 'domain' }
+    );
+
+    expect(dsl).toBe(`domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  service OrderService
+}`);
+  });
+
+  it('serializes a domain with sends (event)', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      { id: 'Orders', name: 'Orders Domain', version: '1.0.0', sends: [{ id: 'OrderCreated', version: '1.0.0' }], markdown: '' },
+      { type: 'domain' }
+    );
+
+    expect(dsl).toBe(`domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  sends event OrderCreated@1.0.0
+}`);
+  });
+
+  it('serializes a domain with receives (command)', async () => {
+    await writeCommand({ id: 'ProcessPayment', name: 'Process Payment', version: '1.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      {
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        receives: [{ id: 'ProcessPayment', version: '1.0.0' }],
+        markdown: '',
+      },
+      { type: 'domain' }
+    );
+
+    expect(dsl).toBe(`domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  receives command ProcessPayment@1.0.0
+}`);
+  });
+
+  it('serializes a domain with sends and channel (to)', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      {
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] }],
+        markdown: '',
+      },
+      { type: 'domain' }
+    );
+
+    expect(dsl).toBe(`domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+}`);
+  });
+
+  it('serializes a domain with hydrate option', async () => {
+    await writeEvent({
+      id: 'OrderCreated',
+      name: 'Order Created',
+      version: '1.0.0',
+      summary: 'An order was created',
+      markdown: '',
+    });
+    await writeService({
+      id: 'OrderService',
+      name: 'Order Service',
+      version: '1.0.0',
+      sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      markdown: '',
+    });
+
+    const dsl = await toDSL(
+      {
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        services: [{ id: 'OrderService', version: '1.0.0' }],
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      },
+      { type: 'domain', hydrate: true }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "An order was created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  service OrderService@1.0.0
+  sends event OrderCreated@1.0.0
+}`);
+  });
+
+  it('deduplicates hydrated messages across domain and service', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+    await writeService({
+      id: 'OrderService',
+      name: 'Order Service',
+      version: '1.0.0',
+      sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      markdown: '',
+    });
+
+    const dsl = await toDSL(
+      {
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        services: [{ id: 'OrderService', version: '1.0.0' }],
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      },
+      { type: 'domain', hydrate: true }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  service OrderService@1.0.0
+  sends event OrderCreated@1.0.0
+}`);
+  });
+
+  it('full integration: domain with hydrated services and messages', async () => {
+    await writeEvent({
+      id: 'OrderCreated',
+      name: 'Order Created',
+      version: '1.0.0',
+      summary: 'Fired when order is created',
+      markdown: '',
+    });
+    await writeCommand({
+      id: 'CreateOrder',
+      name: 'Create Order',
+      version: '1.0.0',
+      summary: 'Command to create an order',
+      markdown: '',
+    });
+    await writeService({
+      id: 'OrderService',
+      name: 'Order Service',
+      version: '1.0.0',
+      summary: 'Handles orders',
+      sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      receives: [{ id: 'CreateOrder', version: '1.0.0' }],
+      markdown: '',
+    });
+
+    const dsl = await toDSL(
+      {
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        summary: 'Order management',
+        services: [{ id: 'OrderService', version: '1.0.0' }],
+        markdown: '',
+      },
+      { type: 'domain', hydrate: true }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "Fired when order is created"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+  summary "Command to create an order"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  summary "Handles orders"
+  sends event OrderCreated@1.0.0
+  receives command CreateOrder@1.0.0
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  summary "Order management"
+  service OrderService@1.0.0
+}`);
+  });
+
+  it('serializes an array of domains', async () => {
+    const dsl = await toDSL(
+      [
+        { id: 'Orders', name: 'Orders Domain', version: '1.0.0', markdown: '' },
+        { id: 'Payments', name: 'Payments Domain', version: '1.0.0', markdown: '' },
+      ],
+      { type: 'domain' }
+    );
+
+    expect(dsl).toBe(`domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+}
+
+domain Payments {
+  version 1.0.0
+  name "Payments Domain"
+}`);
+  });
+
+  it('deduplicates domains in array', async () => {
+    const dsl = await toDSL(
+      [
+        { id: 'Orders', name: 'Orders Domain', version: '1.0.0', markdown: '' },
+        { id: 'Orders', name: 'Orders Domain', version: '1.0.0', markdown: '' },
+      ],
+      { type: 'domain' }
+    );
+
+    expect(dsl).toBe(`domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+}`);
+  });
+
+  describe('hydrate owners', () => {
+    it('hydrates a domain with a team owner', async () => {
+      await writeTeam({ id: 'orders-team', name: 'Orders Team', markdown: '' });
+
+      const dsl = await toDSL(
+        { id: 'Orders', name: 'Orders Domain', version: '1.0.0', owners: ['orders-team'], markdown: '' },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team orders-team {
+  name "Orders Team"
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  owner orders-team
+}`);
+    });
+
+    it('hydrates a domain with a user owner', async () => {
+      await writeUser({
+        id: 'jdoe',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jdoe.png',
+        role: 'Engineer',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        { id: 'Orders', name: 'Orders Domain', version: '1.0.0', owners: ['jdoe'], markdown: '' },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toBe(`user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+  role "Engineer"
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  owner jdoe
+}`);
+    });
+
+    it('hydrates a domain with both team and user owners and services', async () => {
+      await writeTeam({ id: 'orders-team', name: 'Orders Team', markdown: '' });
+      await writeUser({ id: 'jdoe', name: 'Jane Doe', avatarUrl: 'https://example.com/jdoe.png', markdown: '' });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          owners: ['orders-team', 'jdoe'],
+          services: [{ id: 'OrderService', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team orders-team {
+  name "Orders Team"
+}
+
+user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  owner orders-team
+  owner jdoe
+  service OrderService@1.0.0
+}`);
+    });
+  });
+
+  describe('hydrate channels', () => {
+    it('hydrates channels from domain-level sends (to)', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeChannel({
+        id: 'orders-topic',
+        name: 'Orders Topic',
+        version: '1.0.0',
+        address: 'orders.events',
+        protocols: ['kafka'],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toBe(`channel orders-topic {
+  version 1.0.0
+  name "Orders Topic"
+  address "orders.events"
+  protocol "kafka"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+}`);
+    });
+
+    it('hydrates channels from domain-level receives (from)', async () => {
+      await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' });
+      await writeChannel({
+        id: 'commands-queue',
+        name: 'Commands Queue',
+        version: '1.0.0',
+        address: 'orders.commands',
+        protocols: ['sqs'],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          receives: [{ id: 'CreateOrder', version: '1.0.0', from: [{ id: 'commands-queue', version: '1.0.0' }] }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toBe(`channel commands-queue {
+  version 1.0.0
+  name "Commands Queue"
+  address "orders.commands"
+  protocol "sqs"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  receives command CreateOrder@1.0.0 from commands-queue@1.0.0
+}`);
+    });
+
+    it('hydrates channels from service sends within domain', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeChannel({
+        id: 'orders-topic',
+        name: 'Orders Topic',
+        version: '1.0.0',
+        address: 'orders.events',
+        protocols: ['kafka'],
+        markdown: '',
+      });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] }],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          services: [{ id: 'OrderService', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toBe(`channel orders-topic {
+  version 1.0.0
+  name "Orders Topic"
+  address "orders.events"
+  protocol "kafka"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  service OrderService@1.0.0
+}`);
+    });
+
+    it('deduplicates channels shared between service and domain', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeChannel({
+        id: 'orders-topic',
+        name: 'Orders Topic',
+        version: '1.0.0',
+        address: 'orders.events',
+        markdown: '',
+      });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] }],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          services: [{ id: 'OrderService', version: '1.0.0' }],
+          sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toBe(`channel orders-topic {
+  version 1.0.0
+  name "Orders Topic"
+  address "orders.events"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  service OrderService@1.0.0
+  sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+}`);
+    });
+  });
+
+  describe('hydrate service owners', () => {
+    it('hydrates owners of services within domain', async () => {
+      await writeTeam({ id: 'svc-team', name: 'Service Team', markdown: '' });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        owners: ['svc-team'],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          services: [{ id: 'OrderService', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team svc-team {
+  name "Service Team"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  owner svc-team
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  service OrderService@1.0.0
+}`);
+    });
+
+    it('deduplicates owners shared between domain and service', async () => {
+      await writeTeam({ id: 'shared-team', name: 'Shared Team', markdown: '' });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        owners: ['shared-team'],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          owners: ['shared-team'],
+          services: [{ id: 'OrderService', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team shared-team {
+  name "Shared Team"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  owner shared-team
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  owner shared-team
+  service OrderService@1.0.0
+}`);
+    });
+  });
+
+  describe('hydrate full integration', () => {
+    it('hydrates a domain with services, messages, channels, team, and user', async () => {
+      await writeTeam({ id: 'orders-team', name: 'Orders Team', summary: 'Manages orders', markdown: '' });
+      await writeUser({
+        id: 'jdoe',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jdoe.png',
+        role: 'Engineer',
+        markdown: '',
+      });
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Fired when order is created',
+        markdown: '',
+      });
+      await writeCommand({
+        id: 'CreateOrder',
+        name: 'Create Order',
+        version: '1.0.0',
+        summary: 'Command to create an order',
+        markdown: '',
+      });
+      await writeChannel({
+        id: 'orders-topic',
+        name: 'Orders Topic',
+        version: '1.0.0',
+        address: 'orders.events',
+        protocols: ['kafka'],
+        markdown: '',
+      });
+      await writeChannel({
+        id: 'commands-queue',
+        name: 'Commands Queue',
+        version: '1.0.0',
+        address: 'orders.commands',
+        protocols: ['sqs'],
+        markdown: '',
+      });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        summary: 'Handles orders',
+        owners: ['orders-team'],
+        sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] }],
+        receives: [{ id: 'CreateOrder', version: '1.0.0', from: [{ id: 'commands-queue', version: '1.0.0' }] }],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          summary: 'Order management',
+          owners: ['jdoe'],
+          services: [{ id: 'OrderService', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toBe(`user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+  role "Engineer"
+}
+
+team orders-team {
+  name "Orders Team"
+  summary "Manages orders"
+}
+
+channel orders-topic {
+  version 1.0.0
+  name "Orders Topic"
+  address "orders.events"
+  protocol "kafka"
+}
+
+channel commands-queue {
+  version 1.0.0
+  name "Commands Queue"
+  address "orders.commands"
+  protocol "sqs"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "Fired when order is created"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+  summary "Command to create an order"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  summary "Handles orders"
+  owner orders-team
+  sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+  receives command CreateOrder@1.0.0 from commands-queue@1.0.0
+}
+
+domain Orders {
+  version 1.0.0
+  name "Orders Domain"
+  summary "Order management"
+  owner jdoe
+  service OrderService@1.0.0
+}`);
+    });
+  });
+
+  describe('hydrate related services', () => {
+    it('hydrates external services that receive what a domain service sends (downstream consumers)', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+      await writeService({
+        id: 'NotificationService',
+        name: 'Notification Service',
+        version: '1.0.0',
+        receives: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          services: [{ id: 'OrderService', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toContain('service NotificationService {');
+      expect(dsl).toContain('receives event OrderCreated@1.0.0');
+      expect(dsl).toContain('service OrderService {');
+      expect(dsl).toContain('event OrderCreated {');
+      expect(dsl.match(/service OrderService \{/g)?.length || 0).toBe(1);
+    });
+
+    it('hydrates external services that send what a domain service receives (upstream producers)', async () => {
+      await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        receives: [{ id: 'CreateOrder', version: '1.0.0' }],
+        markdown: '',
+      });
+      await writeService({
+        id: 'CheckoutService',
+        name: 'Checkout Service',
+        version: '1.0.0',
+        sends: [{ id: 'CreateOrder', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          services: [{ id: 'OrderService', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toContain('service CheckoutService {');
+      expect(dsl).toContain('sends command CreateOrder@1.0.0');
+      expect(dsl).toContain('service OrderService {');
+    });
+
+    it('does not duplicate a service that is already a member of the domain', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+      await writeService({
+        id: 'BillingService',
+        name: 'Billing Service',
+        version: '1.0.0',
+        receives: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          services: [
+            { id: 'OrderService', version: '1.0.0' },
+            { id: 'BillingService', version: '1.0.0' },
+          ],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl.match(/service BillingService \{/g)?.length || 0).toBe(1);
+    });
+
+    it('does not add any services when no external services consume domain messages', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          services: [{ id: 'OrderService', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl.match(/^service /gm)?.length || 0).toBe(1);
+    });
+
+    it('does not hydrate related services when hydrate is false', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+      await writeService({
+        id: 'NotificationService',
+        name: 'Notification Service',
+        version: '1.0.0',
+        receives: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          services: [{ id: 'OrderService', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: false }
+      );
+
+      expect(dsl).not.toContain('service NotificationService {');
+    });
+
+    it('full integration: domain with both upstream producers and downstream consumers', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        receives: [{ id: 'CreateOrder', version: '1.0.0' }],
+        markdown: '',
+      });
+      await writeService({
+        id: 'NotificationService',
+        name: 'Notification Service',
+        version: '1.0.0',
+        receives: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+      await writeService({
+        id: 'CheckoutService',
+        name: 'Checkout Service',
+        version: '1.0.0',
+        sends: [{ id: 'CreateOrder', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'Orders',
+          name: 'Orders Domain',
+          version: '1.0.0',
+          services: [{ id: 'OrderService', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'domain', hydrate: true }
+      );
+
+      expect(dsl).toContain('service OrderService {');
+      expect(dsl).toContain('service NotificationService {');
+      expect(dsl).toContain('service CheckoutService {');
+      expect(dsl.match(/service OrderService \{/g)?.length || 0).toBe(1);
+      expect(dsl.match(/service NotificationService \{/g)?.length || 0).toBe(1);
+      expect(dsl.match(/service CheckoutService \{/g)?.length || 0).toBe(1);
+    });
+  });
+});
diff --git a/packages/sdk/src/test/dsl/events.test.ts b/packages/sdk/src/test/dsl/events.test.ts
new file mode 100644
index 000000000..7f8be2320
--- /dev/null
+++ b/packages/sdk/src/test/dsl/events.test.ts
@@ -0,0 +1,403 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-dsl-events');
+
+const { toDSL, writeTeam, writeUser, writeService, writeEvent } = utils(CATALOG_PATH);
+
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('toDSL - events', () => {
+  it('serializes a basic event', async () => {
+    const dsl = await toDSL(
+      { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', summary: 'Fired when order is created', markdown: '' },
+      { type: 'event' }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "Fired when order is created"
+}`);
+  });
+
+  it('serializes an event with owners', async () => {
+    const dsl = await toDSL(
+      { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', owners: ['orders-team', 'platform-team'], markdown: '' },
+      { type: 'event' }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  owner orders-team
+  owner platform-team
+}`);
+  });
+
+  it('serializes an event with schemaPath (schema is skipped in DSL output)', async () => {
+    const dsl = await toDSL(
+      { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', schemaPath: 'schema.json', markdown: '' },
+      { type: 'event' }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}`);
+  });
+
+  it('serializes a deprecated event', async () => {
+    const dsl = await toDSL(
+      { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', deprecated: true, markdown: '' },
+      { type: 'event' }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  deprecated true
+}`);
+  });
+
+  it('serializes a draft event', async () => {
+    const dsl = await toDSL(
+      { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', draft: true, markdown: '' },
+      { type: 'event' }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  draft true
+}`);
+  });
+
+  it('serializes an event with all fields', async () => {
+    const dsl = await toDSL(
+      {
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Fired when order is created',
+        owners: ['orders-team'],
+        schemaPath: 'schema.json',
+        deprecated: true,
+        draft: true,
+        markdown: '',
+      },
+      { type: 'event' }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "Fired when order is created"
+  owner orders-team
+  deprecated true
+  draft true
+}`);
+  });
+
+  it('serializes an event with no body fields as inline declaration', async () => {
+    const dsl = await toDSL({ id: 'OrderCreated', name: '', version: '', markdown: '' }, { type: 'event' });
+
+    expect(dsl).toBe('event OrderCreated');
+  });
+
+  it('serializes an array of events', async () => {
+    const dsl = await toDSL(
+      [
+        { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' },
+        { id: 'OrderUpdated', name: 'Order Updated', version: '2.0.0', markdown: '' },
+      ],
+      { type: 'event' }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+event OrderUpdated {
+  version 2.0.0
+  name "Order Updated"
+}`);
+  });
+
+  it('deduplicates events in array by id and version', async () => {
+    const dsl = await toDSL(
+      [
+        { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' },
+        { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' },
+      ],
+      { type: 'event' }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}`);
+  });
+
+  describe('hydrate', () => {
+    it('hydrates an event with a team owner', async () => {
+      await writeTeam({ id: 'orders-team', name: 'Orders Team', markdown: '' });
+
+      const dsl = await toDSL(
+        { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', owners: ['orders-team'], markdown: '' },
+        { type: 'event', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team orders-team {
+  name "Orders Team"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  owner orders-team
+}`);
+    });
+
+    it('hydrates an event with a user owner', async () => {
+      await writeUser({
+        id: 'jdoe',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jdoe.png',
+        role: 'Engineer',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', owners: ['jdoe'], markdown: '' },
+        { type: 'event', hydrate: true }
+      );
+
+      expect(dsl).toBe(`user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+  role "Engineer"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  owner jdoe
+}`);
+    });
+
+    it('hydrates an event with both team and user owners', async () => {
+      await writeTeam({ id: 'orders-team', name: 'Orders Team', markdown: '' });
+      await writeUser({ id: 'jdoe', name: 'Jane Doe', avatarUrl: 'https://example.com/jdoe.png', markdown: '' });
+
+      const dsl = await toDSL(
+        { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', owners: ['orders-team', 'jdoe'], markdown: '' },
+        { type: 'event', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team orders-team {
+  name "Orders Team"
+}
+
+user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  owner orders-team
+  owner jdoe
+}`);
+    });
+
+    it('hydrates an event with a team that has email and summary', async () => {
+      await writeTeam({
+        id: 'orders-team',
+        name: 'Orders Team',
+        summary: 'Manages orders',
+        email: 'orders@example.com',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', owners: ['orders-team'], markdown: '' },
+        { type: 'event', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team orders-team {
+  name "Orders Team"
+  summary "Manages orders"
+  email "orders@example.com"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  owner orders-team
+}`);
+    });
+
+    it('skips owners that cannot be resolved as team or user', async () => {
+      const dsl = await toDSL(
+        { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', owners: ['nonexistent-team'], markdown: '' },
+        { type: 'event', hydrate: true }
+      );
+
+      expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  owner nonexistent-team
+}`);
+    });
+
+    it('deduplicates owners across an array of events', async () => {
+      await writeTeam({ id: 'orders-team', name: 'Orders Team', markdown: '' });
+
+      const dsl = await toDSL(
+        [
+          { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', owners: ['orders-team'], markdown: '' },
+          { id: 'OrderUpdated', name: 'Order Updated', version: '1.0.0', owners: ['orders-team'], markdown: '' },
+        ],
+        { type: 'event', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team orders-team {
+  name "Orders Team"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  owner orders-team
+}
+
+event OrderUpdated {
+  version 1.0.0
+  name "Order Updated"
+  owner orders-team
+}`);
+    });
+
+    it('does not hydrate owners when hydrate is false', async () => {
+      await writeTeam({ id: 'orders-team', name: 'Orders Team', markdown: '' });
+
+      const dsl = await toDSL(
+        { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', owners: ['orders-team'], markdown: '' },
+        { type: 'event' }
+      );
+
+      expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  owner orders-team
+}`);
+    });
+
+    it('hydrates a user with email and slack', async () => {
+      await writeUser({
+        id: 'jdoe',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jdoe.png',
+        email: 'jdoe@example.com',
+        slackDirectMessageUrl: 'https://slack.com/jdoe',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', owners: ['jdoe'], markdown: '' },
+        { type: 'event', hydrate: true }
+      );
+
+      expect(dsl).toBe(`user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+  email "jdoe@example.com"
+  slack "https://slack.com/jdoe"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  owner jdoe
+}`);
+    });
+  });
+
+  describe('hydrate services', () => {
+    it('hydrates an event with producer and consumer services', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+      await writeService({
+        id: 'NotificationService',
+        name: 'Notification Service',
+        version: '1.0.0',
+        receives: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' },
+        { type: 'event', hydrate: true }
+      );
+
+      expect(dsl).toContain('service OrderService {');
+      expect(dsl).toContain('sends event OrderCreated@1.0.0');
+      expect(dsl).toContain('service NotificationService {');
+      expect(dsl).toContain('receives event OrderCreated@1.0.0');
+      expect(dsl).toContain('event OrderCreated {');
+    });
+
+    it('does not include services when hydrate is false', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      });
+
+      const dsl = await toDSL({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' }, { type: 'event' });
+
+      expect(dsl).not.toContain('service OrderService');
+    });
+  });
+
+  it('does not deduplicate events with different versions', async () => {
+    const dsl = await toDSL(
+      [
+        { id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' },
+        { id: 'OrderCreated', name: 'Order Created', version: '2.0.0', markdown: '' },
+      ],
+      { type: 'event' }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+event OrderCreated {
+  version 2.0.0
+  name "Order Created"
+}`);
+  });
+});
diff --git a/packages/sdk/src/test/dsl/queries.test.ts b/packages/sdk/src/test/dsl/queries.test.ts
new file mode 100644
index 000000000..afa3df0d2
--- /dev/null
+++ b/packages/sdk/src/test/dsl/queries.test.ts
@@ -0,0 +1,173 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-dsl-queries');
+
+const { toDSL, writeTeam, writeUser } = utils(CATALOG_PATH);
+
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('toDSL - queries', () => {
+  it('serializes a basic query', async () => {
+    const dsl = await toDSL(
+      { id: 'GetOrder', name: 'Get Order', version: '1.0.0', summary: 'Gets an order by ID', markdown: '' },
+      { type: 'query' }
+    );
+
+    expect(dsl).toBe(`query GetOrder {
+  version 1.0.0
+  name "Get Order"
+  summary "Gets an order by ID"
+}`);
+  });
+
+  it('serializes a query with owners', async () => {
+    const dsl = await toDSL(
+      { id: 'GetOrder', name: 'Get Order', version: '1.0.0', owners: ['api-team'], markdown: '' },
+      { type: 'query' }
+    );
+
+    expect(dsl).toBe(`query GetOrder {
+  version 1.0.0
+  name "Get Order"
+  owner api-team
+}`);
+  });
+
+  it('serializes a query with no body fields as inline declaration', async () => {
+    const dsl = await toDSL({ id: 'GetOrder', name: '', version: '', markdown: '' }, { type: 'query' });
+
+    expect(dsl).toBe('query GetOrder');
+  });
+
+  it('serializes an array of queries', async () => {
+    const dsl = await toDSL(
+      [
+        { id: 'GetOrder', name: 'Get Order', version: '1.0.0', markdown: '' },
+        { id: 'GetInventory', name: 'Get Inventory', version: '2.0.0', markdown: '' },
+      ],
+      { type: 'query' }
+    );
+
+    expect(dsl).toBe(`query GetOrder {
+  version 1.0.0
+  name "Get Order"
+}
+
+query GetInventory {
+  version 2.0.0
+  name "Get Inventory"
+}`);
+  });
+
+  it('deduplicates queries in array by id and version', async () => {
+    const dsl = await toDSL(
+      [
+        { id: 'GetOrder', name: 'Get Order', version: '1.0.0', markdown: '' },
+        { id: 'GetOrder', name: 'Get Order', version: '1.0.0', markdown: '' },
+      ],
+      { type: 'query' }
+    );
+
+    expect(dsl).toBe(`query GetOrder {
+  version 1.0.0
+  name "Get Order"
+}`);
+  });
+
+  describe('hydrate', () => {
+    it('hydrates a query with a team owner', async () => {
+      await writeTeam({ id: 'api-team', name: 'API Team', markdown: '' });
+
+      const dsl = await toDSL(
+        { id: 'GetOrder', name: 'Get Order', version: '1.0.0', owners: ['api-team'], markdown: '' },
+        { type: 'query', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team api-team {
+  name "API Team"
+}
+
+query GetOrder {
+  version 1.0.0
+  name "Get Order"
+  owner api-team
+}`);
+    });
+
+    it('hydrates a query with a user owner', async () => {
+      await writeUser({
+        id: 'jdoe',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jdoe.png',
+        role: 'Engineer',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        { id: 'GetOrder', name: 'Get Order', version: '1.0.0', owners: ['jdoe'], markdown: '' },
+        { type: 'query', hydrate: true }
+      );
+
+      expect(dsl).toBe(`user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+  role "Engineer"
+}
+
+query GetOrder {
+  version 1.0.0
+  name "Get Order"
+  owner jdoe
+}`);
+    });
+
+    it('hydrates a query with both team and user owners', async () => {
+      await writeTeam({ id: 'api-team', name: 'API Team', markdown: '' });
+      await writeUser({ id: 'jdoe', name: 'Jane Doe', avatarUrl: 'https://example.com/jdoe.png', markdown: '' });
+
+      const dsl = await toDSL(
+        { id: 'GetOrder', name: 'Get Order', version: '1.0.0', owners: ['api-team', 'jdoe'], markdown: '' },
+        { type: 'query', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team api-team {
+  name "API Team"
+}
+
+user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+}
+
+query GetOrder {
+  version 1.0.0
+  name "Get Order"
+  owner api-team
+  owner jdoe
+}`);
+    });
+
+    it('skips owners that cannot be resolved', async () => {
+      const dsl = await toDSL(
+        { id: 'GetOrder', name: 'Get Order', version: '1.0.0', owners: ['nonexistent'], markdown: '' },
+        { type: 'query', hydrate: true }
+      );
+
+      expect(dsl).toBe(`query GetOrder {
+  version 1.0.0
+  name "Get Order"
+  owner nonexistent
+}`);
+    });
+  });
+});
diff --git a/packages/sdk/src/test/dsl/services.test.ts b/packages/sdk/src/test/dsl/services.test.ts
new file mode 100644
index 000000000..4037be6c1
--- /dev/null
+++ b/packages/sdk/src/test/dsl/services.test.ts
@@ -0,0 +1,1120 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-dsl-services');
+
+const { writeEvent, writeCommand, writeQuery, writeService, writeChannel, writeTeam, writeUser, writeDataStore, toDSL } =
+  utils(CATALOG_PATH);
+
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('toDSL - services', () => {
+  it('serializes a basic service with no sends/receives', async () => {
+    const dsl = await toDSL(
+      { id: 'OrderService', name: 'Order Service', version: '1.0.0', summary: 'Handles orders', markdown: '' },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  summary "Handles orders"
+}`);
+  });
+
+  it('serializes a service with sends (event)', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0
+}`);
+  });
+
+  it('serializes a service with receives (command)', async () => {
+    await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '2.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        receives: [{ id: 'CreateOrder', version: '2.0.0' }],
+        markdown: '',
+      },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  receives command CreateOrder@2.0.0
+}`);
+  });
+
+  it('serializes a service with receives (command) as the latest version', async () => {
+    await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '2.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        receives: [{ id: 'CreateOrder' }],
+        markdown: '',
+      },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  receives command CreateOrder
+}`);
+  });
+
+  it('serializes a service with sends and channel (to)', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] }],
+        markdown: '',
+      },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+}`);
+  });
+
+  it('serializes a service with receives and channel (from)', async () => {
+    await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        receives: [{ id: 'CreateOrder', version: '1.0.0', from: [{ id: 'orders-queue', version: '2.0.0' }] }],
+        markdown: '',
+      },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  receives command CreateOrder@1.0.0 from orders-queue@2.0.0
+}`);
+  });
+
+  it('serializes a service with multiple channels on sends', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [
+          {
+            id: 'OrderCreated',
+            version: '1.0.0',
+            to: [
+              { id: 'orders-topic', version: '1.0.0' },
+              { id: 'analytics-topic', version: '2.0.0' },
+            ],
+          },
+        ],
+        markdown: '',
+      },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0 to orders-topic@1.0.0, analytics-topic@2.0.0
+}`);
+  });
+
+  it('serializes a service with writes-to', async () => {
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        writesTo: [{ id: 'OrdersDB', version: '1.0.0' }],
+        markdown: '',
+      },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  writes-to container OrdersDB@1.0.0
+}`);
+  });
+
+  it('serializes a service with reads-from without version', async () => {
+    const dsl = await toDSL(
+      { id: 'OrderService', name: 'Order Service', version: '1.0.0', readsFrom: [{ id: 'AnalyticsDB' }], markdown: '' },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  reads-from container AnalyticsDB
+}`);
+  });
+
+  it('serializes a service with writes-to and reads-from', async () => {
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        writesTo: [{ id: 'OrdersDB', version: '1.0.0' }],
+        readsFrom: [{ id: 'InventoryDB', version: '2.0.0' }],
+        markdown: '',
+      },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  writes-to container OrdersDB@1.0.0
+  reads-from container InventoryDB@2.0.0
+}`);
+  });
+
+  it('serializes a service with sends without version', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      { id: 'OrderService', name: 'Order Service', version: '1.0.0', sends: [{ id: 'OrderCreated' }], markdown: '' },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated
+}`);
+  });
+
+  it('serializes a service with multiple message types (event, command, query)', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+    await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' });
+    await writeQuery({ id: 'GetOrder', name: 'Get Order', version: '1.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        receives: [
+          { id: 'CreateOrder', version: '1.0.0' },
+          { id: 'GetOrder', version: '1.0.0' },
+        ],
+        markdown: '',
+      },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0
+  receives command CreateOrder@1.0.0
+  receives query GetOrder@1.0.0
+}`);
+  });
+
+  it('serializes a service with channel on sends and receives', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+    await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic' }] }],
+        receives: [{ id: 'CreateOrder', version: '1.0.0', from: [{ id: 'commands-queue', version: '1.0.0' }] }],
+        markdown: '',
+      },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0 to orders-topic
+  receives command CreateOrder@1.0.0 from commands-queue@1.0.0
+}`);
+  });
+
+  it('skips sends for messages that cannot be resolved to a type', async () => {
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'NonExistentEvent', version: '1.0.0' }],
+        markdown: '',
+      },
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+}`);
+  });
+
+  it('serializes a service with hydrate option prepending message definitions', async () => {
+    await writeEvent({
+      id: 'OrderCreated',
+      name: 'Order Created',
+      version: '1.0.0',
+      summary: 'An order was created',
+      markdown: '',
+    });
+
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      },
+      { type: 'service', hydrate: true }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "An order was created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0
+}`);
+  });
+
+  it('hydrated service includes all message type definitions', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+    await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '1.0.0', summary: 'Creates an order', markdown: '' });
+
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        receives: [{ id: 'CreateOrder', version: '1.0.0' }],
+        markdown: '',
+      },
+      { type: 'service', hydrate: true }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+  summary "Creates an order"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0
+  receives command CreateOrder@1.0.0
+}`);
+  });
+
+  it('deduplicates hydrated messages when same message appears in sends and receives', async () => {
+    await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+    const dsl = await toDSL(
+      {
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '1.0.0',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        receives: [{ id: 'OrderCreated', version: '1.0.0' }],
+        markdown: '',
+      },
+      { type: 'service', hydrate: true }
+    );
+
+    expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0
+  receives event OrderCreated@1.0.0
+}`);
+  });
+
+  it('serializes an array of services', async () => {
+    const dsl = await toDSL(
+      [
+        { id: 'OrderService', name: 'Order Service', version: '1.0.0', markdown: '' },
+        { id: 'PaymentService', name: 'Payment Service', version: '1.0.0', markdown: '' },
+      ],
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+}
+
+service PaymentService {
+  version 1.0.0
+  name "Payment Service"
+}`);
+  });
+
+  it('deduplicates services in array', async () => {
+    const dsl = await toDSL(
+      [
+        { id: 'OrderService', name: 'Order Service', version: '1.0.0', markdown: '' },
+        { id: 'OrderService', name: 'Order Service', version: '1.0.0', markdown: '' },
+      ],
+      { type: 'service' }
+    );
+
+    expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+}`);
+  });
+
+  describe('hydrate owners', () => {
+    it('hydrates a service with a team owner', async () => {
+      await writeTeam({ id: 'orders-team', name: 'Orders Team', markdown: '' });
+
+      const dsl = await toDSL(
+        { id: 'OrderService', name: 'Order Service', version: '1.0.0', owners: ['orders-team'], markdown: '' },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team orders-team {
+  name "Orders Team"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  owner orders-team
+}`);
+    });
+
+    it('hydrates a service with a user owner', async () => {
+      await writeUser({
+        id: 'jdoe',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jdoe.png',
+        role: 'Engineer',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        { id: 'OrderService', name: 'Order Service', version: '1.0.0', owners: ['jdoe'], markdown: '' },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+  role "Engineer"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  owner jdoe
+}`);
+    });
+
+    it('hydrates a service with both team and user owners and messages', async () => {
+      await writeTeam({ id: 'orders-team', name: 'Orders Team', markdown: '' });
+      await writeUser({ id: 'jdoe', name: 'Jane Doe', avatarUrl: 'https://example.com/jdoe.png', markdown: '' });
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          owners: ['orders-team', 'jdoe'],
+          sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team orders-team {
+  name "Orders Team"
+}
+
+user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  owner orders-team
+  owner jdoe
+  sends event OrderCreated@1.0.0
+}`);
+    });
+  });
+
+  describe('hydrate channels', () => {
+    it('hydrates channels referenced in sends (to)', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeChannel({
+        id: 'orders-topic',
+        name: 'Orders Topic',
+        version: '1.0.0',
+        address: 'orders.events',
+        protocols: ['kafka'],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`channel orders-topic {
+  version 1.0.0
+  name "Orders Topic"
+  address "orders.events"
+  protocol "kafka"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+}`);
+    });
+
+    it('hydrates channels referenced in receives (from)', async () => {
+      await writeCommand({ id: 'CreateOrder', name: 'Create Order', version: '1.0.0', markdown: '' });
+      await writeChannel({
+        id: 'commands-queue',
+        name: 'Commands Queue',
+        version: '1.0.0',
+        address: 'orders.commands',
+        protocols: ['sqs'],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          receives: [{ id: 'CreateOrder', version: '1.0.0', from: [{ id: 'commands-queue', version: '1.0.0' }] }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`channel commands-queue {
+  version 1.0.0
+  name "Commands Queue"
+  address "orders.commands"
+  protocol "sqs"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  receives command CreateOrder@1.0.0 from commands-queue@1.0.0
+}`);
+    });
+
+    it('deduplicates channels used by multiple messages', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeEvent({ id: 'OrderUpdated', name: 'Order Updated', version: '1.0.0', markdown: '' });
+      await writeChannel({ id: 'orders-topic', name: 'Orders Topic', version: '1.0.0', address: 'orders.events', markdown: '' });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          sends: [
+            { id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] },
+            { id: 'OrderUpdated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] },
+          ],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`channel orders-topic {
+  version 1.0.0
+  name "Orders Topic"
+  address "orders.events"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+event OrderUpdated {
+  version 1.0.0
+  name "Order Updated"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+  sends event OrderUpdated@1.0.0 to orders-topic@1.0.0
+}`);
+    });
+
+    it('hydrates upstream channels from non-latest versions', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeChannel({
+        id: 'orders-topic',
+        name: 'Orders Topic v1',
+        version: '1.0.0',
+        address: 'orders.events.v1',
+        markdown: '',
+      });
+      await writeChannel({
+        id: 'ingress-router',
+        name: 'Ingress Router v1',
+        version: '1.0.0',
+        routes: [{ id: 'orders-topic', version: '1.0.0' }],
+        markdown: '',
+      });
+      await writeChannel(
+        {
+          id: 'ingress-router',
+          name: 'Ingress Router v2',
+          version: '2.0.0',
+          routes: [{ id: 'audit-topic', version: '1.0.0' }],
+          markdown: '',
+        },
+        { versionExistingContent: true }
+      );
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toContain('channel ingress-router {');
+      expect(dsl).toContain('name "Ingress Router v1"');
+      expect(dsl).toContain('route orders-topic@1.0.0');
+      expect(dsl).not.toContain('name "Ingress Router v2"');
+    });
+
+    it('does not hydrate upstream channels that route to a different version', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeChannel({
+        id: 'orders-topic',
+        name: 'Orders Topic v1',
+        version: '1.0.0',
+        address: 'orders.events.v1',
+        markdown: '',
+      });
+      await writeChannel({
+        id: 'orders-topic',
+        name: 'Orders Topic v2',
+        version: '2.0.0',
+        address: 'orders.events.v2',
+        markdown: '',
+      });
+      await writeChannel({
+        id: 'analytics-router',
+        name: 'Analytics Router',
+        version: '1.0.0',
+        routes: [{ id: 'orders-topic', version: '2.0.0' }],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).not.toContain('channel analytics-router {');
+    });
+
+    it('skips channels that cannot be resolved', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'nonexistent-topic', version: '1.0.0' }] }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  sends event OrderCreated@1.0.0 to nonexistent-topic@1.0.0
+}`);
+    });
+  });
+
+  describe('hydrate related services', () => {
+    it('hydrates all matching pointers for a related service', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeEvent({ id: 'OrderUpdated', name: 'Order Updated', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'BillingService',
+        name: 'Billing Service',
+        version: '1.0.0',
+        receives: [
+          { id: 'OrderCreated', version: '1.0.0' },
+          { id: 'OrderUpdated', version: '1.0.0' },
+        ],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          sends: [
+            { id: 'OrderCreated', version: '1.0.0' },
+            { id: 'OrderUpdated', version: '1.0.0' },
+          ],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toContain('service BillingService {');
+      expect(dsl).toContain('receives event OrderCreated@1.0.0');
+      expect(dsl).toContain('receives event OrderUpdated@1.0.0');
+      expect(dsl.match(/service BillingService \{/g)?.length || 0).toBe(1);
+    });
+  });
+
+  describe('hydrate containers', () => {
+    it('hydrates containers referenced in writes-to', async () => {
+      await writeDataStore({
+        id: 'OrdersDB',
+        name: 'Orders Database',
+        version: '1.0.0',
+        container_type: 'database',
+        technology: 'postgres@14',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          writesTo: [{ id: 'OrdersDB', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`container OrdersDB {
+  version 1.0.0
+  name "Orders Database"
+  container-type database
+  technology "postgres@14"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  writes-to container OrdersDB@1.0.0
+}`);
+    });
+
+    it('hydrates containers referenced in reads-from', async () => {
+      await writeDataStore({
+        id: 'InventoryDB',
+        name: 'Inventory Database',
+        version: '2.0.0',
+        container_type: 'database',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          readsFrom: [{ id: 'InventoryDB', version: '2.0.0' }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`container InventoryDB {
+  version 2.0.0
+  name "Inventory Database"
+  container-type database
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  reads-from container InventoryDB@2.0.0
+}`);
+    });
+
+    it('hydrates both writes-to and reads-from containers', async () => {
+      await writeDataStore({
+        id: 'OrdersDB',
+        name: 'Orders Database',
+        version: '1.0.0',
+        container_type: 'database',
+        markdown: '',
+      });
+      await writeDataStore({
+        id: 'InventoryDB',
+        name: 'Inventory Database',
+        version: '2.0.0',
+        container_type: 'cache',
+        technology: 'redis',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          writesTo: [{ id: 'OrdersDB', version: '1.0.0' }],
+          readsFrom: [{ id: 'InventoryDB', version: '2.0.0' }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`container OrdersDB {
+  version 1.0.0
+  name "Orders Database"
+  container-type database
+}
+
+container InventoryDB {
+  version 2.0.0
+  name "Inventory Database"
+  container-type cache
+  technology "redis"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  writes-to container OrdersDB@1.0.0
+  reads-from container InventoryDB@2.0.0
+}`);
+    });
+
+    it('deduplicates containers referenced in both writes-to and reads-from', async () => {
+      await writeDataStore({
+        id: 'OrdersDB',
+        name: 'Orders Database',
+        version: '1.0.0',
+        container_type: 'database',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          writesTo: [{ id: 'OrdersDB', version: '1.0.0' }],
+          readsFrom: [{ id: 'OrdersDB', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`container OrdersDB {
+  version 1.0.0
+  name "Orders Database"
+  container-type database
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  writes-to container OrdersDB@1.0.0
+  reads-from container OrdersDB@1.0.0
+}`);
+    });
+
+    it('skips containers that cannot be resolved', async () => {
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          writesTo: [{ id: 'NonExistentDB', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`service OrderService {
+  version 1.0.0
+  name "Order Service"
+  writes-to container NonExistentDB@1.0.0
+}`);
+    });
+
+    it('hydrates container with all fields', async () => {
+      await writeDataStore({
+        id: 'OrdersDB',
+        name: 'Orders Database',
+        version: '1.0.0',
+        container_type: 'database',
+        technology: 'postgres@14',
+        authoritative: true,
+        access_mode: 'readWrite',
+        classification: 'confidential',
+        residency: 'us-east-1',
+        retention: '7 years',
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          writesTo: [{ id: 'OrdersDB', version: '1.0.0' }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`container OrdersDB {
+  version 1.0.0
+  name "Orders Database"
+  container-type database
+  technology "postgres@14"
+  authoritative true
+  access-mode readWrite
+  classification confidential
+  residency "us-east-1"
+  retention "7 years"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  writes-to container OrdersDB@1.0.0
+}`);
+    });
+  });
+
+  describe('hydrate full integration', () => {
+    it('hydrates a service with messages, channels, team, and user', async () => {
+      await writeTeam({ id: 'orders-team', name: 'Orders Team', summary: 'Manages orders', markdown: '' });
+      await writeUser({
+        id: 'jdoe',
+        name: 'Jane Doe',
+        avatarUrl: 'https://example.com/jdoe.png',
+        role: 'Engineer',
+        markdown: '',
+      });
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Fired when order is created',
+        markdown: '',
+      });
+      await writeCommand({
+        id: 'CreateOrder',
+        name: 'Create Order',
+        version: '1.0.0',
+        summary: 'Command to create an order',
+        markdown: '',
+      });
+      await writeChannel({
+        id: 'orders-topic',
+        name: 'Orders Topic',
+        version: '1.0.0',
+        address: 'orders.events',
+        protocols: ['kafka'],
+        markdown: '',
+      });
+      await writeChannel({
+        id: 'commands-queue',
+        name: 'Commands Queue',
+        version: '1.0.0',
+        address: 'orders.commands',
+        protocols: ['sqs'],
+        markdown: '',
+      });
+
+      const dsl = await toDSL(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          summary: 'Handles orders',
+          owners: ['orders-team', 'jdoe'],
+          sends: [{ id: 'OrderCreated', version: '1.0.0', to: [{ id: 'orders-topic', version: '1.0.0' }] }],
+          receives: [{ id: 'CreateOrder', version: '1.0.0', from: [{ id: 'commands-queue', version: '1.0.0' }] }],
+          markdown: '',
+        },
+        { type: 'service', hydrate: true }
+      );
+
+      expect(dsl).toBe(`team orders-team {
+  name "Orders Team"
+  summary "Manages orders"
+}
+
+user jdoe {
+  name "Jane Doe"
+  avatar "https://example.com/jdoe.png"
+  role "Engineer"
+}
+
+channel orders-topic {
+  version 1.0.0
+  name "Orders Topic"
+  address "orders.events"
+  protocol "kafka"
+}
+
+channel commands-queue {
+  version 1.0.0
+  name "Commands Queue"
+  address "orders.commands"
+  protocol "sqs"
+}
+
+event OrderCreated {
+  version 1.0.0
+  name "Order Created"
+  summary "Fired when order is created"
+}
+
+command CreateOrder {
+  version 1.0.0
+  name "Create Order"
+  summary "Command to create an order"
+}
+
+service OrderService {
+  version 1.0.0
+  name "Order Service"
+  summary "Handles orders"
+  owner orders-team
+  owner jdoe
+  sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+  receives command CreateOrder@1.0.0 from commands-queue@1.0.0
+}`);
+    });
+  });
+});
diff --git a/packages/sdk/src/test/entities.test.ts b/packages/sdk/src/test/entities.test.ts
new file mode 100644
index 000000000..134bb1d66
--- /dev/null
+++ b/packages/sdk/src/test/entities.test.ts
@@ -0,0 +1,323 @@
+// sum.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-entities');
+
+const { writeEntity, getEntity, getEntities, rmEntity, rmEntityById, versionEntity, entityHasVersion } = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Entities SDK', () => {
+  describe('getEntity', () => {
+    it('returns the given entity id from EventCatalog and the latest version when no version is given,', async () => {
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+        aggregateRoot: true,
+        identifier: 'id',
+        attachments: ['https://example.com'],
+        diagrams: [{ id: 'UserDiagram', version: '1.0.0' }],
+      });
+
+      const test = await getEntity('User');
+
+      expect(test).toEqual({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+        aggregateRoot: true,
+        identifier: 'id',
+        attachments: ['https://example.com'],
+        diagrams: [{ id: 'UserDiagram', version: '1.0.0' }],
+      });
+    });
+
+    it('returns the given entity id from EventCatalog and the requested version when a version is given,', async () => {
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+        aggregateRoot: true,
+      });
+
+      await versionEntity('User');
+
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.2',
+        summary: 'User entity v2',
+        markdown: '# User entity v2',
+        aggregateRoot: false,
+      });
+
+      const test = await getEntity('User', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+        aggregateRoot: true,
+      });
+    });
+
+    it('returns undefined when a given resource is not found', async () => {
+      const entity = await getEntity('InventoryAdjusted');
+      await expect(entity).toEqual(undefined);
+    });
+  });
+
+  describe('getEntities', () => {
+    it('returns all entities from the catalog', async () => {
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+      });
+
+      await writeEntity({
+        id: 'Product',
+        name: 'Product',
+        version: '0.0.1',
+        summary: 'Product entity',
+        markdown: '# Product entity',
+      });
+
+      const entities = await getEntities();
+      expect(entities).toHaveLength(2);
+      expect(entities.map((e) => e.id)).toEqual(['User', 'Product']);
+    });
+
+    it('returns only latest versions when latestOnly is true', async () => {
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+      });
+
+      await versionEntity('User');
+
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.2',
+        summary: 'User entity v2',
+        markdown: '# User entity v2',
+      });
+
+      const entities = await getEntities({ latestOnly: true });
+      expect(entities).toHaveLength(1);
+      expect(entities[0].version).toBe('0.0.2');
+    });
+  });
+
+  describe('writeEntity', () => {
+    it('writes the given entity to the file system', async () => {
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+        aggregateRoot: true,
+        properties: [
+          {
+            name: 'id',
+            type: 'string',
+            required: true,
+          },
+        ],
+      });
+
+      const entity = await getEntity('User');
+
+      expect(entity).toEqual({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+        aggregateRoot: true,
+        properties: [
+          {
+            name: 'id',
+            type: 'string',
+            required: true,
+          },
+        ],
+      });
+    });
+
+    it('writes the entity to a custom path when path is provided', async () => {
+      await writeEntity(
+        {
+          id: 'User',
+          name: 'User',
+          version: '0.0.1',
+          summary: 'User entity',
+          markdown: '# User entity',
+        },
+        { path: '/Account/User' }
+      );
+
+      const entity = await getEntity('User');
+      expect(entity).toEqual({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+      });
+    });
+  });
+
+  describe('rmEntity', () => {
+    it('removes an entity by its path', async () => {
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+      });
+
+      await rmEntity('/User');
+
+      const entity = await getEntity('User');
+
+      await expect(entity).toEqual(undefined);
+    });
+  });
+
+  describe('rmEntityById', () => {
+    it('removes an entity by its id', async () => {
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+      });
+
+      await rmEntityById('User');
+
+      const entity = await getEntity('User');
+
+      await expect(entity).toEqual(undefined);
+    });
+
+    it('removes a specific version of an entity by its id and version', async () => {
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+      });
+
+      await versionEntity('User');
+
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.2',
+        summary: 'User entity v2',
+        markdown: '# User entity v2',
+      });
+
+      await rmEntityById('User', '0.0.1');
+
+      const oldEntity = await getEntity('User', '0.0.1');
+      expect(oldEntity).toEqual(undefined);
+
+      const newEntity = await getEntity('User', '0.0.2');
+      expect(newEntity).toEqual({
+        id: 'User',
+        name: 'User',
+        version: '0.0.2',
+        summary: 'User entity v2',
+        markdown: '# User entity v2',
+      });
+    });
+  });
+
+  describe('versionEntity', () => {
+    it('versions an entity by moving it to a versioned directory', async () => {
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+      });
+
+      await versionEntity('User');
+
+      const versionedEntity = await getEntity('User', '0.0.1');
+      expect(versionedEntity).toEqual({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+      });
+    });
+  });
+
+  describe('entityHasVersion', () => {
+    it('returns true if entity version exists', async () => {
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+      });
+
+      const hasVersion = await entityHasVersion('User', '0.0.1');
+      expect(hasVersion).toBe(true);
+    });
+
+    it('returns false if entity version does not exist', async () => {
+      await writeEntity({
+        id: 'User',
+        name: 'User',
+        version: '0.0.1',
+        summary: 'User entity',
+        markdown: '# User entity',
+      });
+
+      const hasVersion = await entityHasVersion('User', '0.0.2');
+      expect(hasVersion).toBe(false);
+    });
+
+    it('returns false if entity does not exist', async () => {
+      const hasVersion = await entityHasVersion('NonExistentEntity', '0.0.1');
+      expect(hasVersion).toBe(false);
+    });
+  });
+});
diff --git a/packages/sdk/src/test/eventcatalog.test.ts b/packages/sdk/src/test/eventcatalog.test.ts
new file mode 100644
index 000000000..2789f15e9
--- /dev/null
+++ b/packages/sdk/src/test/eventcatalog.test.ts
@@ -0,0 +1,355 @@
+import utils from '../index';
+import fs from 'node:fs';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, it, expect } from 'vitest';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-eventcatalog');
+
+const { dumpCatalog, getEventCatalogConfigurationFile } = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  // fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  // fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(async () => {
+  const dump = await dumpCatalog();
+  fs.writeFileSync(path.join(CATALOG_PATH, 'eventcatalog.json'), JSON.stringify(dump, null, 2));
+  // fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('EventCatalog', () => {
+  describe('dumpCatalog', () => {
+    it('the dump file should contain the catalog version, dump version and the createdAt date', async () => {
+      const dump = await dumpCatalog();
+      expect(dump.catalogVersion).toBe('2.33.5');
+      expect(dump.version).toBe('0.0.1');
+      expect(dump.createdAt).toBeDefined();
+    });
+
+    it('should not include markdown if the includeMarkdown option is false', async () => {
+      const dump = await dumpCatalog({ includeMarkdown: false });
+      expect(dump.resources.messages?.events?.[0].markdown).toBeUndefined();
+    });
+
+    describe('domains', () => {
+      it('returns a list of domains from the catalog', async () => {
+        const dump = await dumpCatalog();
+        expect(dump.resources.domains).toHaveLength(3);
+
+        const domain1 = dump.resources.domains?.[0];
+
+        expect(domain1).toEqual(
+          expect.objectContaining({
+            id: 'Orders',
+            name: 'Orders',
+            version: '0.0.3',
+            owners: ['dboyne', 'full-stack'],
+            services: [
+              {
+                id: 'InventoryService',
+              },
+              {
+                id: 'OrdersService',
+              },
+              {
+                id: 'NotificationService',
+              },
+              {
+                id: 'ShippingService',
+              },
+            ],
+          })
+        );
+      });
+    });
+
+    describe('services', () => {
+      it('returns a list of services from the catalog', async () => {
+        const dump = await dumpCatalog();
+        expect(dump.resources.services).toHaveLength(6);
+
+        const service1 = dump.resources.services?.[0];
+
+        expect(service1).toEqual(
+          expect.objectContaining({
+            id: 'ShippingService',
+            version: '0.0.1',
+            name: 'Shipping Service',
+            summary: 'Service that handles shipping\n',
+            owners: ['dboyne'],
+            repository: {
+              language: 'JavaScript',
+              url: 'https://github.com/event-catalog/pretend-shipping-service',
+            },
+            markdown: expect.any(String),
+          })
+        );
+
+        expect(service1?.sends).toHaveLength(6);
+        expect(service1?.receives).toHaveLength(5);
+      });
+    });
+
+    describe('messages', () => {
+      describe('events', () => {
+        it('returns a list of events from the catalog', async () => {
+          const dump = await dumpCatalog();
+          expect(dump.resources.messages?.events).toHaveLength(14);
+        });
+      });
+
+      describe('queries', () => {
+        it('returns a list of queries from the catalog', async () => {
+          const dump = await dumpCatalog();
+          expect(dump.resources.messages?.queries).toHaveLength(5);
+        });
+      });
+
+      describe('commands', () => {
+        it('returns a list of commands from the catalog', async () => {
+          const dump = await dumpCatalog();
+          expect(dump.resources.messages?.commands).toHaveLength(8);
+        });
+      });
+    });
+
+    describe('teams', () => {
+      it('returns a list of teams from the catalog', async () => {
+        const dump = await dumpCatalog();
+        expect(dump.resources.teams).toHaveLength(4);
+      });
+    });
+
+    describe('users', () => {
+      it('returns a list of users from the catalog', async () => {
+        const dump = await dumpCatalog();
+        expect(dump.resources.users).toHaveLength(23);
+      });
+    });
+
+    describe('channels', () => {
+      it('returns a list of channels from the catalog', async () => {
+        const dump = await dumpCatalog();
+        expect(dump.resources.channels).toHaveLength(3);
+      });
+    });
+
+    describe('entities', () => {
+      it('returns a list of entities from the catalog', async () => {
+        const dump = await dumpCatalog();
+        expect(dump.resources.entities).toHaveLength(2);
+
+        const entity = dump.resources.entities?.find((e: any) => e.id === 'Customer');
+        expect(entity).toEqual(
+          expect.objectContaining({
+            id: 'Customer',
+            name: 'Customer',
+            version: '1.0.0',
+          })
+        );
+      });
+
+      it('should not include markdown for entities if the includeMarkdown option is false', async () => {
+        const dump = await dumpCatalog({ includeMarkdown: false });
+        expect(dump.resources.entities?.[0].markdown).toBeUndefined();
+      });
+    });
+
+    describe('containers', () => {
+      it('returns a list of containers from the catalog', async () => {
+        const dump = await dumpCatalog();
+        expect(dump.resources.containers).toHaveLength(2);
+
+        const container = dump.resources.containers?.find((c: any) => c.id === 'orders-db');
+        expect(container).toEqual(
+          expect.objectContaining({
+            id: 'orders-db',
+            name: 'Orders Database',
+            version: '1.0.0',
+          })
+        );
+      });
+
+      it('should not include markdown for containers if the includeMarkdown option is false', async () => {
+        const dump = await dumpCatalog({ includeMarkdown: false });
+        expect(dump.resources.containers?.[0].markdown).toBeUndefined();
+      });
+    });
+
+    describe('flows', () => {
+      it('returns a list of flows from the catalog', async () => {
+        const dump = await dumpCatalog();
+        expect(dump.resources.flows).toHaveLength(2);
+
+        const flow = dump.resources.flows?.find((f: any) => f.id === 'PaymentFlow');
+        expect(flow).toEqual(
+          expect.objectContaining({
+            id: 'PaymentFlow',
+            name: 'Payment Flow',
+            version: '1.0.0',
+          })
+        );
+      });
+
+      it('should not include markdown for flows if the includeMarkdown option is false', async () => {
+        const dump = await dumpCatalog({ includeMarkdown: false });
+        expect(dump.resources.flows?.[0].markdown).toBeUndefined();
+      });
+    });
+
+    describe('adrs', () => {
+      it('returns a list of ADRs from the catalog', async () => {
+        const dump = await dumpCatalog();
+        expect(dump.resources.adrs).toHaveLength(1);
+
+        const adr = dump.resources.adrs?.find((a: any) => a.id === 'adr-001-use-transactional-outbox');
+        expect(adr).toEqual(
+          expect.objectContaining({
+            id: 'adr-001-use-transactional-outbox',
+            name: 'Use Transactional Outbox',
+            version: '1.0.0',
+            status: 'accepted',
+          })
+        );
+      });
+
+      it('should not include markdown for ADRs if the includeMarkdown option is false', async () => {
+        const dump = await dumpCatalog({ includeMarkdown: false });
+        expect(dump.resources.adrs?.[0].markdown).toBeUndefined();
+      });
+    });
+  });
+
+  describe('getEventCatalogConfigurationFile', () => {
+    it('returns the event catalog configuration file', async () => {
+      const config = await getEventCatalogConfigurationFile();
+      expect(config).toEqual({
+        cId: '8027010c-f3d6-417a-8234-e2f46087fc56',
+        title: 'FlowMart',
+        tagline: 'Here you can find all the information you need to know about our events and services (demo catalog).',
+        organizationName: 'FlowMart',
+        homepageLink: 'https://eventcatalog.dev',
+        editUrl: 'https://github.com/event-catalog/eventcatalog/edit/main',
+        port: 3000,
+        outDir: 'dist',
+        logo: {
+          alt: 'FlowMart',
+          src: '/logo.svg',
+          text: 'FlowMart',
+        },
+        base: '/',
+        trailingSlash: false,
+        mermaid: {
+          iconPacks: ['logos'],
+        },
+        rss: {
+          enabled: true,
+          limit: 15,
+        },
+        llmsTxt: {
+          enabled: true,
+        },
+        chat: {
+          enabled: true,
+          similarityResults: 50,
+          max_tokens: 4096,
+          model: 'Hermes-3-Llama-3.2-3B-q4f16_1-MLC',
+        },
+        generators: [
+          [
+            '@eventcatalog/generator-ai',
+            {
+              debug: true,
+              splitMarkdownFiles: false,
+            },
+          ],
+        ],
+        customDocs: {
+          sidebar: [
+            {
+              label: 'Guides',
+              badge: {
+                text: 'New',
+                color: 'green',
+              },
+              collapsed: false,
+              items: [
+                {
+                  label: 'Creating new microservices',
+                  autogenerated: {
+                    directory: 'guides/creating-new-microservices',
+                  },
+                },
+                {
+                  label: 'Event Storming',
+                  autogenerated: {
+                    directory: 'guides/event-storming',
+                    collapsed: false,
+                  },
+                },
+              ],
+            },
+            {
+              label: 'Technical Architecture & Design',
+              badge: {
+                text: 'New',
+                color: 'green',
+              },
+              collapsed: false,
+              items: [
+                {
+                  label: 'Architecture Decision Records',
+                  autogenerated: {
+                    directory: 'technical-architecture-design/architecture-decision-records',
+                    collapsed: false,
+                  },
+                },
+                {
+                  label: 'System Architecture Diagrams',
+                  autogenerated: {
+                    directory: 'technical-architecture-design/system-architecture-diagrams',
+                    collapsed: false,
+                  },
+                },
+                {
+                  label: 'Infrastructure as Code',
+                  autogenerated: {
+                    directory: 'technical-architecture-design/infrastructure-as-code',
+                    collapsed: false,
+                  },
+                },
+                {
+                  label: 'Read more on GitHub',
+                  link: 'https://github.com/event-catalog/eventcatalog',
+                  attrs: {
+                    target: '_blank',
+                    style: 'font-style: italic;',
+                  },
+                },
+              ],
+            },
+            {
+              label: 'Operations & Support',
+              badge: {
+                text: 'New',
+                color: 'green',
+              },
+              collapsed: false,
+              items: [
+                {
+                  label: 'Runbooks',
+                  autogenerated: {
+                    directory: 'operations-and-support/runbooks',
+                    collapsed: false,
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      });
+    });
+  });
+});
diff --git a/packages/sdk/src/test/events.test.ts b/packages/sdk/src/test/events.test.ts
new file mode 100644
index 000000000..6efee10ec
--- /dev/null
+++ b/packages/sdk/src/test/events.test.ts
@@ -0,0 +1,1873 @@
+// sum.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-events');
+
+const {
+  writeEvent,
+  writeEventToService,
+  getEvent,
+  getEvents,
+  rmEvent,
+  rmEventById,
+  versionEvent,
+  addFileToEvent,
+  addSchemaToEvent,
+  eventHasVersion,
+  writeServiceToDomain,
+  writeService,
+  versionService,
+} = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Events SDK', () => {
+  describe('getEvent', () => {
+    it('returns the given event id from EventCatalog and the latest version when no version is given,', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        draft: {
+          title: 'Draft',
+          message: 'This is a draft',
+        },
+        attachments: [
+          {
+            url: 'https://example.com',
+            title: 'Example',
+            type: 'example',
+            description: 'This is an example',
+            icon: 'example',
+          },
+        ],
+        diagrams: [{ id: 'InventoryAdjustedDiagram', version: '1.0.0' }],
+      });
+
+      const test = await getEvent('InventoryAdjusted');
+
+      expect(test).toEqual({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        draft: {
+          title: 'Draft',
+          message: 'This is a draft',
+        },
+        attachments: [
+          {
+            url: 'https://example.com',
+            title: 'Example',
+            type: 'example',
+            description: 'This is an example',
+            icon: 'example',
+          },
+        ],
+        diagrams: [{ id: 'InventoryAdjustedDiagram', version: '1.0.0' }],
+      });
+    });
+
+    it('returns the given event id from EventCatalog and the latest version when no version is given and the event is inside a services folder,', async () => {
+      await writeEvent(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/InventoryService/InventoryAdjusted' }
+      );
+
+      const test = await getEvent('InventoryAdjusted');
+
+      expect(test).toEqual({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the given event id from EventCatalog and the requested version when a version is given,', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await versionEvent('InventoryAdjusted');
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '1.0.0',
+        summary: 'This is version 1.0.0',
+        markdown: '# Hello world',
+      });
+
+      const test = await getEvent('InventoryAdjusted', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the given event id from EventCatalog and the requested version when a version is given (non-semver),', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await versionEvent('InventoryAdjusted');
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '2',
+        summary: 'This is version 1.0.0',
+        markdown: '# Hello world',
+      });
+
+      const test = await getEvent('InventoryAdjusted', '1');
+
+      expect(test).toEqual({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the latest version of the event if the version matches the latest version', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const test = await getEvent('InventoryAdjusted', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the version of the event even if the event does not match semver matching', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '100',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const test = await getEvent('InventoryAdjusted', '100');
+
+      expect(test).toEqual({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '100',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the event with the schema attached when the attachSchema option is set to true', async () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+        },
+      };
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        schemaPath: 'schema.json',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const file = { schema: JSON.stringify(schema), fileName: 'schema.json' };
+
+      await addSchemaToEvent('InventoryAdjusted', file);
+
+      const test = await getEvent('InventoryAdjusted', '0.0.1', { attachSchema: true });
+
+      expect(test.schema).toEqual(schema);
+    });
+
+    it('does not attach the schema if the attachSchema option is not set', async () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+        },
+      };
+
+      const file = { schema: JSON.stringify(schema), fileName: 'schema.json' };
+
+      await writeEvent({
+        id: 'InventoryAdjusted2',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        schemaPath: 'schema.json',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addSchemaToEvent('InventoryAdjusted2', file);
+
+      const test = await getEvent('InventoryAdjusted2', '0.0.1', { attachSchema: false });
+
+      expect(test.schema).toEqual(undefined);
+    });
+
+    it('returns undefined when a given resource is not found', async () => {
+      const event = await getEvent('InventoryAdjusted');
+      await expect(event).toEqual(undefined);
+    });
+
+    it('throws an error if the event is  found but not the version', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await expect(await getEvent('InventoryAdjusted', '1.0.0')).toEqual(undefined);
+    });
+
+    describe('when events are within a service that is within a domain', async () => {
+      it('returns the given event id from EventCatalog and the latest version when no version is given,', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        const test = await getEvent('InventoryAdjusted');
+
+        expect(test).toEqual({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+      });
+
+      it('returns the given event id from EventCatalog and the latest version when no version is given and the event is inside a services folder,', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        const test = await getEvent('InventoryAdjusted');
+
+        expect(test).toEqual({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+      });
+
+      it('returns the given event id from EventCatalog and the requested version when a version is given,', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        await versionEvent('InventoryAdjusted');
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        const test = await getEvent('InventoryAdjusted', '0.0.1');
+
+        expect(test).toEqual({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+      });
+
+      it('returns the latest version of the event if the version matches the latest version', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        const test = await getEvent('InventoryAdjusted', '0.0.1');
+
+        expect(test).toEqual({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+      });
+
+      it('returns the version of the event even if the event does not match semver matching', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '100',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '100',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        const test = await getEvent('InventoryAdjusted', '100');
+
+        expect(test).toEqual({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '100',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+      });
+
+      it('writes the event to the correct folder path', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        const files = await fs.readdirSync(
+          path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService/events/InventoryAdjusted')
+        );
+
+        expect(files).toEqual(['index.mdx']);
+      });
+    });
+  });
+
+  describe('getEvents', () => {
+    it('returns all the events in the catalog,', async () => {
+      // versioned event
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // latest event
+      await writeEvent(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { versionExistingContent: true }
+      );
+
+      // event in the services folder
+      await writeEvent(
+        {
+          id: 'OrderComplete',
+          name: 'Order Complete',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService' }
+      );
+
+      const events = await getEvents();
+
+      expect(events).toEqual(
+        expect.arrayContaining([
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'OrderComplete',
+            name: 'Order Complete',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+        ])
+      );
+    });
+    it('returns only the latest events when `latestOnly` is set to true,', async () => {
+      // versioned event
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // latest event
+      await writeEvent(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { versionExistingContent: true }
+      );
+
+      // event in the services folder
+      await writeEvent(
+        {
+          id: 'OrderComplete',
+          name: 'Order Complete',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService' }
+      );
+
+      // event in the services folder
+      await writeEvent(
+        {
+          id: 'OrderComplete',
+          name: 'Order Complete',
+          version: '2.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService', versionExistingContent: true }
+      );
+
+      const events = await getEvents({ latestOnly: true });
+
+      expect(events).toEqual(
+        expect.arrayContaining([
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'OrderComplete',
+            name: 'Order Complete',
+            version: '2.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+        ])
+      );
+    });
+    it('returns the event with the schema attached when the attachSchema option is set to true', async () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+        },
+      };
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        schemaPath: 'schema.json',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const file = { schema: JSON.stringify(schema), fileName: 'schema.json' };
+
+      await addSchemaToEvent('InventoryAdjusted', file);
+
+      const test = await getEvent('InventoryAdjusted', '0.0.1', { attachSchema: true });
+
+      expect(test.schema).toEqual(schema);
+    });
+  });
+
+  describe('writeEvent', () => {
+    it('writes the given event to EventCatalog and assumes the path if one if not given', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        sidebar: {
+          badge: 'badge',
+        },
+      });
+
+      const event = await getEvent('InventoryAdjusted');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(true);
+
+      expect(event).toEqual({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        sidebar: {
+          badge: 'badge',
+        },
+      });
+    });
+
+    it('writes the given event (as .md) to EventCatalog if the format is .md', async () => {
+      await writeEvent(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          sidebar: {
+            badge: 'badge',
+          },
+        },
+        {
+          format: 'md',
+        }
+      );
+
+      const event = await getEvent('InventoryAdjusted');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.md'))).toBe(true);
+
+      expect(event).toEqual({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        sidebar: {
+          badge: 'badge',
+        },
+      });
+    });
+
+    it('when resourceGroups is given, it writes the event with the given resourceGroups', async () => {
+      await writeEvent(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          resourceGroups: [
+            {
+              id: 'Inventory',
+              items: [
+                { id: 'InventoryAdjusted', version: '0.0.1', type: 'event' },
+                { id: 'InventoryAdjusted', version: '0.0.2', type: 'event' },
+              ],
+              title: 'Related Resources',
+              limit: 10,
+              sidebar: true,
+            },
+          ],
+        },
+        { path: '/Inventory/InventoryAdjusted' }
+      );
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/Inventory/InventoryAdjusted', 'index.mdx'))).toBe(true);
+    });
+
+    it('when operation is given, it writes the event with the given operation', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        operation: {
+          method: 'POST',
+          path: '/inventory/adjust',
+          statusCodes: ['200', '400', '500'],
+        },
+      });
+
+      const event = await getEvent('InventoryAdjusted');
+
+      expect(event).toEqual({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        operation: {
+          method: 'POST',
+          path: '/inventory/adjust',
+          statusCodes: ['200', '400', '500'],
+        },
+      });
+    });
+
+    it('when operation is given with only a method, it writes the event with the partial operation', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        operation: {
+          method: 'GET',
+        },
+      });
+
+      const event = await getEvent('InventoryAdjusted');
+
+      expect(event).toEqual({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        operation: {
+          method: 'GET',
+        },
+      });
+    });
+
+    it('writes the given event to EventCatalog under the correct path when a path is given', async () => {
+      await writeEvent(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/Inventory/InventoryAdjusted' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/Inventory/InventoryAdjusted', 'index.mdx'))).toBe(true);
+    });
+
+    it('throws an error when trying to write an event that already exists (and override is false, default)', async () => {
+      const createEvent = async () =>
+        writeEvent({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+      await createEvent();
+
+      await expect(
+        writeEvent({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        })
+      ).rejects.toThrowError('Failed to write InventoryAdjusted (event) as the version 0.0.1 already exists');
+    });
+
+    it('overrides the event when trying to write an event that already exists and override is true', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeEvent(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: 'Overridden content',
+        },
+        {
+          override: true,
+        }
+      );
+
+      const event = await getEvent('InventoryAdjusted');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(true);
+      expect(event.markdown).toBe('Overridden content');
+    });
+
+    describe('versionExistingContent', () => {
+      it('versions the previous event when trying to write an event that already exists and versionExistingEvent is true and the new version number is greater than the previous one', async () => {
+        await writeEvent({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: 'Hello world',
+        });
+
+        await writeEvent(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: 'New Content!',
+          },
+          {
+            versionExistingContent: true,
+          }
+        );
+
+        const event = await getEvent('InventoryAdjusted', '1.0.0');
+        expect(event.markdown).toBe('New Content!');
+        expect(event.version).toBe('1.0.0');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted/versioned/0.0.1', 'index.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(true);
+      });
+
+      it('does not version the previous event but overrides it when versionExistingContent is true and override is also true', async () => {
+        await writeEvent({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: 'Hello world',
+        });
+
+        await writeEvent(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: 'New Content!',
+          },
+          {
+            versionExistingContent: true,
+            override: true,
+          }
+        );
+
+        const event = await getEvent('InventoryAdjusted', '0.0.1');
+        expect(event.markdown).toBe('New Content!');
+        expect(event.version).toBe('0.0.1');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted/versioned/0.0.1', 'index.mdx'))).toBe(false);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(true);
+      });
+
+      it('throws an error when trying to write an event and versionExistingEvent is true and the new version number is not greater than the previous one', async () => {
+        await writeEvent({
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: 'Hello world',
+        });
+
+        await expect(
+          writeEvent(
+            {
+              id: 'InventoryAdjusted',
+              name: 'Inventory Adjusted',
+              version: '0.0.1',
+              summary: 'This is a summary',
+              markdown: 'New Content!',
+            },
+            {
+              versionExistingContent: true,
+            }
+          )
+        ).rejects.toThrowError('New version 0.0.1 is not greater than current version 1.0.0');
+      });
+    });
+  });
+
+  describe('writeEventToService', () => {
+    it('writes an event to the given service. When no version if given for the service the event is added to the latest service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeEventToService(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'InventoryService',
+        }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'index.mdx'))).toBe(
+        true
+      );
+    });
+    it('writes an event to the given service. When a version is given for the service the event is added to that service version', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+      await writeEventToService(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'InventoryService',
+          version: '1.0.0',
+        }
+      );
+      expect(
+        fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/versioned/1.0.0/events/InventoryAdjusted', 'index.mdx'))
+      ).toBe(true);
+    });
+    it('writes an event to the given service. When a version is the latest the event is added to the latest version of the service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeEventToService(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'InventoryService',
+          version: 'latest',
+        }
+      );
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService//events/InventoryAdjusted', 'index.mdx'))).toBe(
+        true
+      );
+    });
+
+    it('when override is true, it overrides the event if it already exists', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // Write the first event
+      await writeEventToService(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'InventoryService',
+        }
+      );
+
+      await writeEventToService(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: 'Overridden content',
+        },
+        {
+          id: 'InventoryService',
+        },
+        {
+          override: true,
+        }
+      );
+
+      const event = await getEvent('InventoryAdjusted', '0.0.1');
+
+      expect(event.markdown).toBe('Overridden content');
+    });
+  });
+
+  describe('rmEvent', () => {
+    it('removes an event from eventcatalog', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(true);
+
+      await rmEvent('/InventoryAdjusted');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(false);
+    });
+  });
+
+  describe('rmEventById', () => {
+    it('removes an event from eventcatalog by id', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(true);
+
+      await rmEventById('InventoryAdjusted');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(false);
+    });
+
+    it('removes and event and all files in that event', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      fs.writeFileSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'schema.json'), 'SCHEMA!');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(true);
+
+      await rmEventById('InventoryAdjusted');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(false);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'schema.json'))).toBe(false);
+    });
+
+    it('removes and event but keeps its files when persistFiles is set to true', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      fs.writeFileSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'schema.json'), 'SCHEMA!');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(true);
+
+      await rmEventById('InventoryAdjusted', '0.0.1', true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(false);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'schema.json'))).toBe(true);
+    });
+
+    it('removes an event from eventcatalog by id and version', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(true);
+
+      await rmEventById('InventoryAdjusted', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(false);
+    });
+
+    it('if version is given, only removes that version and not any other versions of the event', async () => {
+      // write the first events
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await versionEvent('InventoryAdjusted');
+
+      // Write the versioned event
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted/versioned/0.0.1', 'index.mdx'))).toBe(true);
+
+      await rmEventById('InventoryAdjusted', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted/versioned/0.0.2', 'index.mdx'))).toBe(false);
+    });
+
+    describe('when events are within a service directory', () => {
+      it('removes an event from EventCatalog by id', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        // expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/events/InventoryAdjusted', 'index.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'index.mdx'))).toBe(
+          true
+        );
+        await rmEventById('InventoryAdjusted');
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'index.mdx'))).toBe(
+          false
+        );
+      });
+
+      it('if version is given, only removes that version and not any other versions of the event', async () => {
+        // write the first events
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            markdown: '# Hello world',
+            version: '0.0.1',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        await versionEvent('InventoryAdjusted');
+
+        // Write the versioned event
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.2',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'index.mdx'))).toBe(
+          true
+        );
+        expect(
+          fs.existsSync(
+            path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted/versioned/0.0.1', 'index.mdx')
+          )
+        ).toBe(true);
+
+        await rmEventById('InventoryAdjusted', '0.0.1');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'index.mdx'))).toBe(
+          true
+        );
+        expect(
+          fs.existsSync(
+            path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted/versioned/0.0.1', 'index.mdx')
+          )
+        ).toBe(false);
+      });
+    });
+  });
+
+  describe('versionEvent', () => {
+    it('adds the given event to the versioned directory and removes itself from the root', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // // Add random file in there
+      // await fs.writeFileSync(path.join(CATALOG_PATH, 'events/Inventory/InventoryAdjusted', 'schema.json'), 'SCHEMA!');
+
+      await versionEvent('InventoryAdjusted');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted/versioned/0.0.2', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(false);
+    });
+    it('adds the given event to the versioned directory and all files that are associated to it', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // Add random file in there
+      await fs.writeFileSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'schema.json'), 'SCHEMA!');
+
+      await versionEvent('InventoryAdjusted');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted/versioned/0.0.2', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted/versioned/0.0.2', 'schema.json'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'index.mdx'))).toBe(false);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'schema.json'))).toBe(false);
+    });
+
+    describe('when events are within a service directory', () => {
+      it('adds the given event to the versioned directory and removes itself from the root', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.2',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        await versionEvent('InventoryAdjusted');
+
+        expect(
+          fs.existsSync(
+            path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted/versioned/0.0.2', 'index.mdx')
+          )
+        ).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'index.mdx'))).toBe(
+          false
+        );
+      });
+      it('adds the given event to the versioned directory and all files that are associated to it', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.2',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        // Add random file in there
+        await fs.writeFileSync(
+          path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'schema.json'),
+          'SCHEMA!'
+        );
+
+        await versionEvent('InventoryAdjusted');
+
+        expect(
+          fs.existsSync(
+            path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted/versioned/0.0.2', 'index.mdx')
+          )
+        ).toBe(true);
+
+        expect(
+          fs.existsSync(
+            path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted/versioned/0.0.2', 'schema.json')
+          )
+        ).toBe(true);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'index.mdx'))).toBe(
+          false
+        );
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'schema.json'))).toBe(
+          false
+        );
+      });
+
+      it('when the service and the event is versioned, the event remains in the root of the service but versioned in its own directory', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.2',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        // Add a random file to the service and event
+        await fs.writeFileSync(path.join(CATALOG_PATH, 'services/InventoryService', 'schema.json'), 'SCHEMA!');
+        await fs.writeFileSync(
+          path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'schema.json'),
+          'SCHEMA!'
+        );
+
+        await versionService('InventoryService');
+        await versionEvent('InventoryAdjusted');
+
+        expect(
+          fs.existsSync(
+            path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted/versioned/0.0.2', 'index.mdx')
+          )
+        ).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/versioned/0.0.1', 'schema.json'))).toBe(true);
+        expect(
+          fs.existsSync(
+            path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted/versioned/0.0.2', 'schema.json')
+          )
+        ).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'index.mdx'))).toBe(
+          false
+        );
+      });
+    });
+  });
+
+  describe('addFileToEvent', () => {
+    it('takes a given file and writes it to the location of the given event', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addFileToEvent('InventoryAdjusted', file);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'test.txt'))).toBe(true);
+    });
+
+    it('takes a given file and version and writes the file to the correct location', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // version the event
+      await versionEvent('InventoryAdjusted');
+
+      await addFileToEvent('InventoryAdjusted', file, '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted/versioned/0.0.1', 'test.txt'))).toBe(true);
+    });
+
+    it('if the directory does not exist, it will be created', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await addFileToEvent('InventoryAdjusted', file, undefined, { path: 'events/InventoryAdjusted/versioned/0.0.1' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted/versioned/0.0.1', 'test.txt'))).toBe(true);
+    });
+
+    it('throws an error when trying to write to a event that does not exist', () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      expect(addFileToEvent('InventoryAdjusted', file)).rejects.toThrowError('Cannot find directory to write file to');
+    });
+
+    it('writes a file to a custom path when path option is provided', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addFileToEvent('InventoryAdjusted', file, undefined, { path: 'events/InventoryAdjusted' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'test.txt'))).toBe(true);
+    });
+
+    describe('when events are within a service directory', () => {
+      it('takes a given file and writes it to the location of the given event', async () => {
+        const file = { content: 'hello', fileName: 'test.txt' };
+
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        await addFileToEvent('InventoryAdjusted', file);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'test.txt'))).toBe(
+          true
+        );
+      });
+
+      it('takes a given file and version and writes the file to the correct location', async () => {
+        const file = { content: 'hello', fileName: 'test.txt' };
+
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        // version the event
+        await versionEvent('InventoryAdjusted');
+
+        await addFileToEvent('InventoryAdjusted', file, '0.0.1');
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted/versioned/0.0.1', 'test.txt'))
+        ).toBe(true);
+      });
+    });
+  });
+
+  describe('addSchemaToEvent', () => {
+    it('takes a given file and writes it to the location of the given event', async () => {
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "age": {
+            "type": "number"
+          }
+        }
+      }`;
+      const file = { schema, fileName: 'schema.json' };
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addSchemaToEvent('InventoryAdjusted', file);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'schema.json'))).toBe(true);
+    });
+
+    it('takes a given file and version and writes the file to the correct location', async () => {
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "age": {
+            "type": "number"
+          }
+        }
+      }`;
+      const file = { schema, fileName: 'schema.json' };
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // version the event
+      await versionEvent('InventoryAdjusted');
+
+      await addSchemaToEvent('InventoryAdjusted', file, '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted/versioned/0.0.1', 'schema.json'))).toBe(true);
+    });
+
+    it('throws an error when trying to write to a event that does not exist', () => {
+      const file = { schema: 'hello', fileName: 'test.txt' };
+
+      expect(addSchemaToEvent('InventoryAdjusted', file)).rejects.toThrowError('Cannot find directory to write file to');
+    });
+
+    it('writes a schema to a custom path when path option is provided', async () => {
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        }
+      }`;
+      const file = { schema, fileName: 'schema.json' };
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addSchemaToEvent('InventoryAdjusted', file, undefined, { path: 'events/InventoryAdjusted' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'schema.json'))).toBe(true);
+    });
+
+    it('if the file can be parsed into JSON, it will be parsed into JSON and written to the file formatted', async () => {
+      const unformattedJson = `{ "name": "John", "age": 30 }`;
+      const file = { schema: unformattedJson, fileName: 'schema.json' };
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addSchemaToEvent('InventoryAdjusted', file);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'schema.json'))).toBe(true);
+      const formattedJson = fs.readFileSync(path.join(CATALOG_PATH, 'events/InventoryAdjusted', 'schema.json'), 'utf8');
+      expect(formattedJson).toBe(`{
+  "name": "John",
+  "age": 30
+}`);
+    });
+
+    it('if the id of the event has a $ value in the id, the schema is still added to the event', async () => {
+      const { getEvent } = utils(CATALOG_PATH);
+
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        }
+      }`;
+      const file = { schema, fileName: 'schema.json' };
+
+      await writeEvent({
+        id: 'Inventory$Adjusted$1',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const event = await getEvent('Inventory$Adjusted$1');
+
+      await addSchemaToEvent(event.id, file);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'events/Inventory$Adjusted$1', 'schema.json'))).toBe(true);
+    });
+    describe('when events are within a service directory', () => {
+      it('takes a given file and writes it to the location of the given event', async () => {
+        const schema = `{
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "age": {
+              "type": "number"
+            }
+          }
+        }`;
+        const file = { schema, fileName: 'schema.json' };
+
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        await addSchemaToEvent('InventoryAdjusted', file);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted', 'schema.json'))).toBe(
+          true
+        );
+      });
+
+      it('takes a given file and version and writes the file to the correct location', async () => {
+        const schema = `{
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "age": {
+              "type": "number"
+            }
+          }
+        }`;
+        const file = { schema, fileName: 'schema.json' };
+
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await writeEventToService(
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        // version the event
+        await versionEvent('InventoryAdjusted');
+
+        await addSchemaToEvent('InventoryAdjusted', file, '0.0.1');
+
+        expect(
+          fs.existsSync(
+            path.join(CATALOG_PATH, 'services/InventoryService/events/InventoryAdjusted/versioned/0.0.1', 'schema.json')
+          )
+        ).toBe(true);
+      });
+    });
+  });
+
+  describe('eventHasVersion', () => {
+    it('returns true when a given event and version exists in the catalog', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await eventHasVersion('InventoryAdjusted', '0.0.1')).toEqual(true);
+    });
+
+    it('returns true when a semver version is given and the version exists in the catalog', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await eventHasVersion('InventoryAdjusted', '0.0.x')).toEqual(true);
+    });
+
+    it('returns true when a `latest` version is given and the version exists in the catalog', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await eventHasVersion('InventoryAdjusted', 'latest')).toEqual(true);
+    });
+
+    it('returns false when event does not exist in the catalog', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await eventHasVersion('InventoryAdjusted', '5.0.0')).toEqual(false);
+    });
+  });
+});
diff --git a/packages/sdk/src/test/examples.test.ts b/packages/sdk/src/test/examples.test.ts
new file mode 100644
index 000000000..da6e42960
--- /dev/null
+++ b/packages/sdk/src/test/examples.test.ts
@@ -0,0 +1,183 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-examples');
+
+const {
+  writeEvent,
+  writeCommand,
+  writeQuery,
+  addExampleToEvent,
+  getExamplesFromEvent,
+  removeExampleFromEvent,
+  addExampleToCommand,
+  getExamplesFromCommand,
+  removeExampleFromCommand,
+  addExampleToQuery,
+  getExamplesFromQuery,
+  removeExampleFromQuery,
+  versionEvent,
+} = utils(CATALOG_PATH);
+
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Examples SDK', () => {
+  describe('Events', () => {
+    it('adds an example file to an event examples directory', async () => {
+      await writeEvent({ id: 'OrderPlaced', name: 'Order Placed', version: '1.0.0', summary: '', markdown: '' });
+
+      await addExampleToEvent('OrderPlaced', { content: '{"orderId": "123"}', fileName: 'basic.json' });
+
+      const examplesDir = path.join(CATALOG_PATH, 'events', 'OrderPlaced', 'examples');
+      expect(fs.existsSync(examplesDir)).toBe(true);
+      expect(fs.readFileSync(path.join(examplesDir, 'basic.json'), 'utf-8')).toBe('{"orderId": "123"}');
+    });
+
+    it('creates the examples directory if it does not exist', async () => {
+      await writeEvent({ id: 'OrderPlaced', name: 'Order Placed', version: '1.0.0', summary: '', markdown: '' });
+
+      const examplesDir = path.join(CATALOG_PATH, 'events', 'OrderPlaced', 'examples');
+      expect(fs.existsSync(examplesDir)).toBe(false);
+
+      await addExampleToEvent('OrderPlaced', { content: '{}', fileName: 'test.json' });
+
+      expect(fs.existsSync(examplesDir)).toBe(true);
+    });
+
+    it('retrieves all examples from an event sorted alphabetically by file name', async () => {
+      await writeEvent({ id: 'OrderPlaced', name: 'Order Placed', version: '1.0.0', summary: '', markdown: '' });
+
+      await addExampleToEvent('OrderPlaced', { content: '{"type": "b"}', fileName: 'beta.json' });
+      await addExampleToEvent('OrderPlaced', { content: '{"type": "a"}', fileName: 'alpha.json' });
+
+      const examples = await getExamplesFromEvent('OrderPlaced');
+
+      expect(examples).toHaveLength(2);
+      expect(examples[0].fileName).toBe('alpha.json');
+      expect(examples[0].content).toBe('{"type": "a"}');
+      expect(examples[1].fileName).toBe('beta.json');
+      expect(examples[1].content).toBe('{"type": "b"}');
+    });
+
+    it('returns empty array when event has no examples', async () => {
+      await writeEvent({ id: 'OrderPlaced', name: 'Order Placed', version: '1.0.0', summary: '', markdown: '' });
+
+      const examples = await getExamplesFromEvent('OrderPlaced');
+
+      expect(examples).toEqual([]);
+    });
+
+    it('removes a specific example from an event', async () => {
+      await writeEvent({ id: 'OrderPlaced', name: 'Order Placed', version: '1.0.0', summary: '', markdown: '' });
+
+      await addExampleToEvent('OrderPlaced', { content: '{}', fileName: 'remove-me.json' });
+      await addExampleToEvent('OrderPlaced', { content: '{}', fileName: 'keep-me.json' });
+
+      await removeExampleFromEvent('OrderPlaced', 'remove-me.json');
+
+      const examples = await getExamplesFromEvent('OrderPlaced');
+      expect(examples).toHaveLength(1);
+      expect(examples[0].fileName).toBe('keep-me.json');
+    });
+
+    it('throws error when removing an example that does not exist', async () => {
+      await writeEvent({ id: 'OrderPlaced', name: 'Order Placed', version: '1.0.0', summary: '', markdown: '' });
+
+      await expect(removeExampleFromEvent('OrderPlaced', 'nope.json')).rejects.toThrowError(
+        'Example file nope.json does not exist in resource OrderPlaced'
+      );
+    });
+
+    it('preserves existing examples when adding a new one', async () => {
+      await writeEvent({ id: 'OrderPlaced', name: 'Order Placed', version: '1.0.0', summary: '', markdown: '' });
+
+      await addExampleToEvent('OrderPlaced', { content: 'first', fileName: 'first.txt' });
+      await addExampleToEvent('OrderPlaced', { content: 'second', fileName: 'second.txt' });
+
+      const examples = await getExamplesFromEvent('OrderPlaced');
+      expect(examples).toHaveLength(2);
+    });
+
+    it('retrieves examples from nested directories inside the examples folder', async () => {
+      await writeEvent({ id: 'OrderPlaced', name: 'Order Placed', version: '1.0.0', summary: '', markdown: '' });
+
+      await addExampleToEvent('OrderPlaced', { content: '{"root": true}', fileName: 'root.json' });
+
+      // Manually create a nested directory with a file
+      const nestedDir = path.join(CATALOG_PATH, 'events', 'OrderPlaced', 'examples', 'errors');
+      fs.mkdirSync(nestedDir, { recursive: true });
+      fs.writeFileSync(path.join(nestedDir, 'not-found.json'), '{"error": true}');
+
+      const examples = await getExamplesFromEvent('OrderPlaced');
+
+      expect(examples).toHaveLength(2);
+      expect(examples[0].fileName).toBe(path.join('errors', 'not-found.json'));
+      expect(examples[1].fileName).toBe('root.json');
+    });
+
+    it('copies examples to versioned directory when event is versioned', async () => {
+      await writeEvent({ id: 'OrderPlaced', name: 'Order Placed', version: '1.0.0', summary: '', markdown: '' });
+
+      await addExampleToEvent('OrderPlaced', { content: '{"v": 1}', fileName: 'sample.json' });
+
+      await versionEvent('OrderPlaced');
+
+      const versionedExamplesDir = path.join(CATALOG_PATH, 'events', 'OrderPlaced', 'versioned', '1.0.0', 'examples');
+      expect(fs.existsSync(versionedExamplesDir)).toBe(true);
+      expect(fs.readFileSync(path.join(versionedExamplesDir, 'sample.json'), 'utf-8')).toBe('{"v": 1}');
+    });
+  });
+
+  describe('Commands', () => {
+    it('adds an example file to a command', async () => {
+      await writeCommand({ id: 'PlaceOrder', name: 'Place Order', version: '1.0.0', summary: '', markdown: '' });
+
+      await addExampleToCommand('PlaceOrder', { content: '{"cmd": true}', fileName: 'basic.json' });
+
+      const examples = await getExamplesFromCommand('PlaceOrder');
+      expect(examples).toHaveLength(1);
+      expect(examples[0].fileName).toBe('basic.json');
+    });
+
+    it('removes an example from a command', async () => {
+      await writeCommand({ id: 'PlaceOrder', name: 'Place Order', version: '1.0.0', summary: '', markdown: '' });
+
+      await addExampleToCommand('PlaceOrder', { content: '{}', fileName: 'test.json' });
+      await removeExampleFromCommand('PlaceOrder', 'test.json');
+
+      const examples = await getExamplesFromCommand('PlaceOrder');
+      expect(examples).toEqual([]);
+    });
+  });
+
+  describe('Queries', () => {
+    it('adds an example file to a query', async () => {
+      await writeQuery({ id: 'GetOrder', name: 'Get Order', version: '1.0.0', summary: '', markdown: '' });
+
+      await addExampleToQuery('GetOrder', { content: '{"query": true}', fileName: 'basic.json' });
+
+      const examples = await getExamplesFromQuery('GetOrder');
+      expect(examples).toHaveLength(1);
+      expect(examples[0].fileName).toBe('basic.json');
+    });
+
+    it('removes an example from a query', async () => {
+      await writeQuery({ id: 'GetOrder', name: 'Get Order', version: '1.0.0', summary: '', markdown: '' });
+
+      await addExampleToQuery('GetOrder', { content: '{}', fileName: 'test.json' });
+      await removeExampleFromQuery('GetOrder', 'test.json');
+
+      const examples = await getExamplesFromQuery('GetOrder');
+      expect(examples).toEqual([]);
+    });
+  });
+});
diff --git a/packages/sdk/src/test/flows.test.ts b/packages/sdk/src/test/flows.test.ts
new file mode 100644
index 000000000..2b6a15e52
--- /dev/null
+++ b/packages/sdk/src/test/flows.test.ts
@@ -0,0 +1,1215 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils, { FlowBuilder } from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-flows');
+
+const {
+  writeFlow,
+  writeVersionedFlow,
+  writeFlowToDomain,
+  writeFlowToService,
+  writeFlowToAgent,
+  getFlow,
+  getFlows,
+  rmFlow,
+  rmFlowById,
+  versionFlow,
+  flowHasVersion,
+  addFileToFlow,
+  writeDomain,
+  versionDomain,
+  writeService,
+  versionService,
+  writeAgent,
+  versionAgent,
+} = utils(CATALOG_PATH);
+
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Flows SDK', () => {
+  describe('getFlow', () => {
+    it('returns the given flow id from EventCatalog and the latest version when no version is given', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Business flow for processing payments',
+        markdown: '# Payment Flow',
+        steps: [
+          {
+            id: 'PlaceOrder',
+            title: 'Place order',
+            message: { id: 'PlaceOrder', version: '0.0.1' },
+            next_step: { id: 'PaymentProcessed', label: 'Payment processed' },
+          },
+          {
+            id: 'PaymentProcessed',
+            title: 'Payment processed',
+            message: { id: 'PaymentProcessed', version: '0.0.1' },
+          },
+        ],
+      });
+
+      const flow = await getFlow('PaymentFlow');
+
+      expect(flow).toEqual({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Business flow for processing payments',
+        markdown: '# Payment Flow',
+        steps: [
+          {
+            id: 'PlaceOrder',
+            title: 'Place order',
+            message: { id: 'PlaceOrder', version: '0.0.1' },
+            next_step: { id: 'PaymentProcessed', label: 'Payment processed' },
+          },
+          {
+            id: 'PaymentProcessed',
+            title: 'Payment processed',
+            message: { id: 'PaymentProcessed', version: '0.0.1' },
+          },
+        ],
+      });
+    });
+
+    it('returns the given flow id from EventCatalog and the requested version when a version is given', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+
+      await versionFlow('PaymentFlow');
+
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.2',
+        summary: 'Payment flow v2',
+        markdown: '# Payment Flow v2',
+        steps: [],
+      });
+
+      const flow = await getFlow('PaymentFlow', '0.0.1');
+
+      expect(flow).toEqual({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+    });
+
+    it('returns undefined when a given flow is not found', async () => {
+      const flow = await getFlow('MissingFlow');
+
+      expect(flow).toEqual(undefined);
+    });
+
+    it('returns a flow from within a domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'Orders domain',
+        markdown: '# Orders domain',
+      });
+
+      await writeFlowToDomain(
+        {
+          id: 'OrderFlow',
+          name: 'Order Flow',
+          version: '1.0.0',
+          summary: 'Order flow',
+          markdown: '# Order flow',
+          steps: [],
+        },
+        { id: 'Orders' }
+      );
+
+      const flow = await getFlow('OrderFlow');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders/flows/OrderFlow', 'index.mdx'))).toBe(true);
+      expect(flow).toEqual({
+        id: 'OrderFlow',
+        name: 'Order Flow',
+        version: '1.0.0',
+        summary: 'Order flow',
+        markdown: '# Order flow',
+        steps: [],
+      });
+    });
+
+    it('returns a flow from within a service', async () => {
+      await writeService({
+        id: 'OrdersService',
+        name: 'Orders Service',
+        version: '0.0.1',
+        summary: 'Orders service',
+        markdown: '# Orders service',
+      });
+
+      await writeFlowToService(
+        {
+          id: 'OrderFlow',
+          name: 'Order Flow',
+          version: '1.0.0',
+          summary: 'Order flow',
+          markdown: '# Order flow',
+          steps: [],
+        },
+        { id: 'OrdersService' }
+      );
+
+      const flow = await getFlow('OrderFlow');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/OrdersService/flows/OrderFlow', 'index.mdx'))).toBe(true);
+      expect(flow).toEqual({
+        id: 'OrderFlow',
+        name: 'Order Flow',
+        version: '1.0.0',
+        summary: 'Order flow',
+        markdown: '# Order flow',
+        steps: [],
+      });
+    });
+
+    it('returns a flow from within an agent', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        summary: 'Order support agent',
+        markdown: '# Order support agent',
+      });
+
+      await writeFlowToAgent(
+        {
+          id: 'OrderSupportFlow',
+          name: 'Order Support Flow',
+          version: '1.0.0',
+          summary: 'Order support flow',
+          markdown: '# Order support flow',
+          steps: [],
+        },
+        { id: 'OrderSupportAgent' }
+      );
+
+      const flow = await getFlow('OrderSupportFlow');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent/flows/OrderSupportFlow', 'index.mdx'))).toBe(true);
+      expect(flow).toEqual({
+        id: 'OrderSupportFlow',
+        name: 'Order Support Flow',
+        version: '1.0.0',
+        summary: 'Order support flow',
+        markdown: '# Order support flow',
+        steps: [],
+      });
+    });
+  });
+
+  describe('getFlows', () => {
+    it('returns all flows from the catalog', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+
+      await writeFlow({
+        id: 'OrderFlow',
+        name: 'Order Flow',
+        version: '0.0.1',
+        summary: 'Order flow',
+        markdown: '# Order Flow',
+        steps: [],
+      });
+
+      const flows = await getFlows();
+
+      expect(flows).toHaveLength(2);
+      expect(flows.map((flow) => flow.id).sort()).toEqual(['OrderFlow', 'PaymentFlow']);
+    });
+
+    it('returns only latest versions when latestOnly is true', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+
+      await versionFlow('PaymentFlow');
+
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.2',
+        summary: 'Payment flow v2',
+        markdown: '# Payment Flow v2',
+        steps: [],
+      });
+
+      const flows = await getFlows({ latestOnly: true });
+
+      expect(flows).toHaveLength(1);
+      expect(flows[0].version).toBe('0.0.2');
+    });
+  });
+
+  describe('writeFlow', () => {
+    it('writes the given flow to the file system', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        owners: ['payments-team'],
+        steps: [
+          {
+            id: 'Customer',
+            title: 'Customer',
+            actor: { name: 'Customer' },
+            next_step: 'PlaceOrder',
+          },
+          {
+            id: 'PlaceOrder',
+            title: 'Place order',
+            message: { id: 'PlaceOrder', version: '0.0.1' },
+          },
+        ],
+      });
+
+      const flow = await getFlow('PaymentFlow');
+
+      expect(flow).toEqual({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        owners: ['payments-team'],
+        steps: [
+          {
+            id: 'Customer',
+            title: 'Customer',
+            actor: { name: 'Customer' },
+            next_step: 'PlaceOrder',
+          },
+          {
+            id: 'PlaceOrder',
+            title: 'Place order',
+            message: { id: 'PlaceOrder', version: '0.0.1' },
+          },
+        ],
+      });
+    });
+
+    it('writes the flow to a custom path when path is provided', async () => {
+      await writeFlow(
+        {
+          id: 'PaymentFlow',
+          name: 'Payment Flow',
+          version: '0.0.1',
+          summary: 'Payment flow',
+          markdown: '# Payment Flow',
+          steps: [],
+        },
+        { path: '/Payments/PaymentFlow' }
+      );
+
+      const flow = await getFlow('PaymentFlow');
+
+      expect(flow).toEqual({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+    });
+
+    it('throws an error when trying to write a flow that already exists', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+
+      await expect(
+        writeFlow({
+          id: 'PaymentFlow',
+          name: 'Payment Flow',
+          version: '0.0.1',
+          summary: 'Payment flow',
+          markdown: '# Payment Flow',
+          steps: [],
+        })
+      ).rejects.toThrowError('Failed to write PaymentFlow (flow) as the version 0.0.1 already exists');
+    });
+
+    it('overrides the flow when trying to write a flow that already exists and override is true', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+
+      await writeFlow(
+        {
+          id: 'PaymentFlow',
+          name: 'Payment Flow',
+          version: '0.0.1',
+          summary: 'Payment flow',
+          markdown: 'Overridden content',
+          steps: [],
+        },
+        { override: true }
+      );
+
+      const flow = await getFlow('PaymentFlow');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'flows/PaymentFlow', 'index.mdx'))).toBe(true);
+      expect(flow.markdown).toBe('Overridden content');
+    });
+
+    describe('versionExistingContent', () => {
+      it('versions the previous flow when trying to write a flow that already exists and versionExistingContent is true', async () => {
+        await writeFlow({
+          id: 'PaymentFlow',
+          name: 'Payment Flow',
+          version: '0.0.1',
+          summary: 'Payment flow',
+          markdown: '# Payment Flow',
+          steps: [],
+        });
+
+        await writeFlow(
+          {
+            id: 'PaymentFlow',
+            name: 'Payment Flow',
+            version: '1.0.0',
+            summary: 'Payment flow',
+            markdown: 'New',
+            steps: [],
+          },
+          { versionExistingContent: true }
+        );
+
+        const flow = await getFlow('PaymentFlow');
+
+        expect(flow.version).toBe('1.0.0');
+        expect(flow.markdown).toBe('New');
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'flows/PaymentFlow/versioned/0.0.1', 'index.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'flows/PaymentFlow', 'index.mdx'))).toBe(true);
+      });
+
+      it('throws an error when trying to write a flow and versionExistingContent is true and the new version is not greater than the previous one', async () => {
+        await writeFlow(
+          {
+            id: 'PaymentFlow',
+            name: 'Payment Flow',
+            version: '1.0.0',
+            summary: 'Payment flow',
+            markdown: 'New',
+            steps: [],
+          },
+          { versionExistingContent: true }
+        );
+
+        await expect(
+          writeFlow(
+            {
+              id: 'PaymentFlow',
+              name: 'Payment Flow',
+              version: '0.0.0',
+              summary: 'Payment flow',
+              markdown: 'New',
+              steps: [],
+            },
+            { versionExistingContent: true }
+          )
+        ).rejects.toThrowError('New version 0.0.0 is not greater than current version 1.0.0');
+      });
+    });
+
+    describe('formats', () => {
+      it('writes the flow as md when format is md', async () => {
+        await writeFlow(
+          {
+            id: 'PaymentFlow',
+            name: 'Payment Flow',
+            version: '0.0.1',
+            summary: 'Payment flow',
+            markdown: '# Payment Flow',
+            steps: [],
+          },
+          { format: 'md' }
+        );
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'flows/PaymentFlow', 'index.md'))).toBe(true);
+      });
+
+      it('writes the flow as mdx when format is mdx (default)', async () => {
+        await writeFlow({
+          id: 'PaymentFlow',
+          name: 'Payment Flow',
+          version: '0.0.1',
+          summary: 'Payment flow',
+          markdown: '# Payment Flow',
+          steps: [],
+        });
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'flows/PaymentFlow', 'index.mdx'))).toBe(true);
+      });
+    });
+  });
+
+  describe('writeVersionedFlow', () => {
+    it('writes a versioned flow', async () => {
+      await writeVersionedFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'flows/PaymentFlow/versioned/0.0.1', 'index.mdx'))).toBe(true);
+    });
+  });
+
+  describe('writeFlowToDomain', () => {
+    it('writes a flow to a domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'Orders domain',
+        markdown: '# Orders domain',
+      });
+
+      await writeFlowToDomain(
+        {
+          id: 'OrderFlow',
+          name: 'Order Flow',
+          version: '1.0.0',
+          summary: 'Order flow',
+          markdown: '# Order flow',
+          steps: [],
+        },
+        { id: 'Orders' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders/flows/OrderFlow', 'index.mdx'))).toBe(true);
+    });
+
+    it('writes a flow to a versioned domain', async () => {
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '0.0.1',
+        summary: 'Orders domain',
+        markdown: '# Orders domain',
+      });
+
+      await versionDomain('Orders');
+
+      await writeDomain({
+        id: 'Orders',
+        name: 'Orders Domain',
+        version: '1.0.0',
+        summary: 'Orders domain',
+        markdown: '# Orders domain',
+      });
+
+      await writeFlowToDomain(
+        {
+          id: 'OrderFlow',
+          name: 'Order Flow',
+          version: '1.0.0',
+          summary: 'Order flow',
+          markdown: '# Order flow',
+          steps: [],
+        },
+        { id: 'Orders', version: '0.0.1' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Orders/versioned/0.0.1/flows/OrderFlow', 'index.mdx'))).toBe(true);
+    });
+  });
+
+  describe('writeFlowToService', () => {
+    it('writes a flow to a service', async () => {
+      await writeService({
+        id: 'OrdersService',
+        name: 'Orders Service',
+        version: '0.0.1',
+        summary: 'Orders service',
+        markdown: '# Orders service',
+      });
+
+      await writeFlowToService(
+        {
+          id: 'OrderFlow',
+          name: 'Order Flow',
+          version: '1.0.0',
+          summary: 'Order flow',
+          markdown: '# Order flow',
+          steps: [],
+        },
+        { id: 'OrdersService' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/OrdersService/flows/OrderFlow', 'index.mdx'))).toBe(true);
+    });
+
+    it('writes a flow to a versioned service', async () => {
+      await writeService({
+        id: 'OrdersService',
+        name: 'Orders Service',
+        version: '0.0.1',
+        summary: 'Orders service',
+        markdown: '# Orders service',
+      });
+
+      await versionService('OrdersService');
+
+      await writeService({
+        id: 'OrdersService',
+        name: 'Orders Service',
+        version: '1.0.0',
+        summary: 'Orders service',
+        markdown: '# Orders service',
+      });
+
+      await writeFlowToService(
+        {
+          id: 'OrderFlow',
+          name: 'Order Flow',
+          version: '1.0.0',
+          summary: 'Order flow',
+          markdown: '# Order flow',
+          steps: [],
+        },
+        { id: 'OrdersService', version: '0.0.1' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/OrdersService/versioned/0.0.1/flows/OrderFlow', 'index.mdx'))).toBe(
+        true
+      );
+    });
+  });
+
+  describe('writeFlowToAgent', () => {
+    it('writes a flow to an agent', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        summary: 'Order support agent',
+        markdown: '# Order support agent',
+      });
+
+      await writeFlowToAgent(
+        {
+          id: 'OrderSupportFlow',
+          name: 'Order Support Flow',
+          version: '1.0.0',
+          summary: 'Order support flow',
+          markdown: '# Order support flow',
+          steps: [],
+        },
+        { id: 'OrderSupportAgent' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent/flows/OrderSupportFlow', 'index.mdx'))).toBe(true);
+    });
+
+    it('writes a flow to a versioned agent', async () => {
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        summary: 'Order support agent',
+        markdown: '# Order support agent',
+      });
+
+      await versionAgent('OrderSupportAgent');
+
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '1.0.0',
+        summary: 'Order support agent',
+        markdown: '# Order support agent',
+      });
+
+      await writeFlowToAgent(
+        {
+          id: 'OrderSupportFlow',
+          name: 'Order Support Flow',
+          version: '1.0.0',
+          summary: 'Order support flow',
+          markdown: '# Order support flow',
+          steps: [],
+        },
+        { id: 'OrderSupportAgent', version: '0.0.1' }
+      );
+
+      expect(
+        fs.existsSync(path.join(CATALOG_PATH, 'agents/OrderSupportAgent/versioned/0.0.1/flows/OrderSupportFlow', 'index.mdx'))
+      ).toBe(true);
+    });
+  });
+
+  describe('versionFlow', () => {
+    it('versions a flow by moving it to a versioned directory', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+
+      await versionFlow('PaymentFlow');
+
+      const flow = await getFlow('PaymentFlow', '0.0.1');
+
+      expect(flow).toEqual({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+    });
+  });
+
+  describe('rmFlow', () => {
+    it('removes a flow by its path', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+
+      await rmFlow('/PaymentFlow');
+
+      const flow = await getFlow('PaymentFlow');
+
+      expect(flow).toEqual(undefined);
+    });
+  });
+
+  describe('rmFlowById', () => {
+    it('removes a flow by its id', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+
+      await rmFlowById('PaymentFlow');
+
+      const flow = await getFlow('PaymentFlow');
+
+      expect(flow).toEqual(undefined);
+    });
+
+    it('removes a specific version of a flow by its id and version', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+
+      await versionFlow('PaymentFlow');
+
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.2',
+        summary: 'Payment flow v2',
+        markdown: '# Payment Flow v2',
+        steps: [],
+      });
+
+      await rmFlowById('PaymentFlow', '0.0.1');
+
+      const oldFlow = await getFlow('PaymentFlow', '0.0.1');
+      const newFlow = await getFlow('PaymentFlow', '0.0.2');
+
+      expect(oldFlow).toEqual(undefined);
+      expect(newFlow).toEqual({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.2',
+        summary: 'Payment flow v2',
+        markdown: '# Payment Flow v2',
+        steps: [],
+      });
+    });
+  });
+
+  describe('flowHasVersion', () => {
+    it('returns true when the given flow version exists', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+
+      expect(await flowHasVersion('PaymentFlow', '0.0.1')).toBe(true);
+    });
+
+    it('returns false when the given flow version does not exist', async () => {
+      expect(await flowHasVersion('PaymentFlow', '0.0.1')).toBe(false);
+    });
+  });
+
+  describe('addFileToFlow', () => {
+    it('adds a file to the given flow', async () => {
+      await writeFlow({
+        id: 'PaymentFlow',
+        name: 'Payment Flow',
+        version: '0.0.1',
+        summary: 'Payment flow',
+        markdown: '# Payment Flow',
+        steps: [],
+      });
+
+      await addFileToFlow('PaymentFlow', { content: 'Payment notes', fileName: 'notes.md' });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'flows/PaymentFlow', 'notes.md'))).toBe(true);
+      expect(fs.readFileSync(path.join(CATALOG_PATH, 'flows/PaymentFlow', 'notes.md'), 'utf-8')).toBe('Payment notes');
+    });
+  });
+});
+
+describe('FlowBuilder', () => {
+  it('builds a flow with generic, message, agent, service, actor, external system, sub-flow, and custom steps', () => {
+    const flow = FlowBuilder.create({
+      id: 'PaymentFlow',
+      name: 'Payment Flow',
+      version: '1.0.0',
+      summary: 'Payment flow',
+      markdown: '# Payment Flow',
+    })
+      .addActorStep({
+        id: 'Customer',
+        summary: 'Customer placing an order',
+        nextSteps: [{ id: 'PlaceOrder', label: 'Places order' }],
+      })
+      .addMessageStep({
+        id: 'PlaceOrder',
+        version: '0.0.1',
+        nextSteps: [{ id: 'PaymentService', label: 'Process payment' }],
+      })
+      .addServiceStep({
+        id: 'PaymentService',
+        version: '0.0.2',
+        nextSteps: [
+          { id: 'PaymentsDB', label: 'Store payment' },
+          { id: 'Stripe', label: 'Authorize payment' },
+        ],
+      })
+      .addAgentStep({
+        id: 'FraudReviewAgent',
+        version: '1.0.0',
+      })
+      .addDataStoreStep({
+        id: 'PaymentsDB',
+        version: '1.0.0',
+        nextSteps: [{ id: 'RevenueAnalytics', label: 'Update analytics' }],
+      })
+      .addDataProductStep({
+        id: 'RevenueAnalytics',
+        version: '1.0.0',
+        nextSteps: [{ id: 'PaymentProcessed', label: 'Payment processed' }],
+      })
+      .addMessageStep({
+        id: 'PaymentProcessed',
+        nextSteps: [{ id: 'RewardFlow', label: 'Reward customer' }],
+      })
+      .addExternalSystemStep({
+        id: 'Stripe',
+        summary: 'Payment provider',
+        url: 'https://stripe.com',
+        nextSteps: [{ id: 'ManualReview', label: 'Review failed payments' }],
+      })
+      .addFlowStep({
+        id: 'RewardFlow',
+        version: '1.0.0',
+      })
+      .addCustomStep({
+        id: 'ManualReview',
+        title: 'Manual Review',
+        summary: 'Review the failed payment manually',
+        icon: 'clipboard',
+        type: 'manual',
+        color: '#ff0000',
+      })
+      .build();
+
+    expect(flow).toEqual({
+      id: 'PaymentFlow',
+      name: 'Payment Flow',
+      version: '1.0.0',
+      summary: 'Payment flow',
+      markdown: '# Payment Flow',
+      steps: [
+        {
+          id: 'Customer',
+          title: 'Customer',
+          summary: 'Customer placing an order',
+          actor: { name: 'Customer', summary: 'Customer placing an order' },
+          next_step: { id: 'PlaceOrder', label: 'Places order' },
+        },
+        {
+          id: 'PlaceOrder',
+          title: 'PlaceOrder',
+          message: { id: 'PlaceOrder', version: '0.0.1' },
+          next_step: { id: 'PaymentService', label: 'Process payment' },
+        },
+        {
+          id: 'PaymentService',
+          title: 'PaymentService',
+          service: { id: 'PaymentService', version: '0.0.2' },
+          next_steps: [
+            { id: 'PaymentsDB', label: 'Store payment' },
+            { id: 'Stripe', label: 'Authorize payment' },
+          ],
+        },
+        {
+          id: 'FraudReviewAgent',
+          title: 'FraudReviewAgent',
+          agent: { id: 'FraudReviewAgent', version: '1.0.0' },
+        },
+        {
+          id: 'PaymentsDB',
+          title: 'PaymentsDB',
+          container: { id: 'PaymentsDB', version: '1.0.0' },
+          next_step: { id: 'RevenueAnalytics', label: 'Update analytics' },
+        },
+        {
+          id: 'RevenueAnalytics',
+          title: 'RevenueAnalytics',
+          dataProduct: { id: 'RevenueAnalytics', version: '1.0.0' },
+          next_step: { id: 'PaymentProcessed', label: 'Payment processed' },
+        },
+        {
+          id: 'PaymentProcessed',
+          title: 'PaymentProcessed',
+          message: { id: 'PaymentProcessed' },
+          next_step: { id: 'RewardFlow', label: 'Reward customer' },
+        },
+        {
+          id: 'Stripe',
+          title: 'Stripe',
+          summary: 'Payment provider',
+          externalSystem: { name: 'Stripe', summary: 'Payment provider', url: 'https://stripe.com' },
+          next_step: { id: 'ManualReview', label: 'Review failed payments' },
+        },
+        {
+          id: 'RewardFlow',
+          title: 'RewardFlow',
+          flow: { id: 'RewardFlow', version: '1.0.0' },
+        },
+        {
+          id: 'ManualReview',
+          title: 'Manual Review',
+          summary: 'Review the failed payment manually',
+          custom: {
+            title: 'Manual Review',
+            summary: 'Review the failed payment manually',
+            icon: 'clipboard',
+            type: 'manual',
+            color: '#ff0000',
+          },
+        },
+      ],
+    });
+  });
+
+  it('uses a generic step title when a title is not provided', () => {
+    const flow = FlowBuilder.create({
+      id: 'OrderFlow',
+      name: 'Order Flow',
+      version: '1.0.0',
+      markdown: '# Order Flow',
+    })
+      .addStep({ id: 'Calculate' })
+      .build();
+
+    expect(flow.steps).toEqual([
+      {
+        id: 'Calculate',
+        title: 'Calculate',
+      },
+    ]);
+  });
+
+  it('starts from existing steps when steps are provided to the builder', () => {
+    const flow = FlowBuilder.create({
+      id: 'OrderFlow',
+      name: 'Order Flow',
+      version: '1.0.0',
+      markdown: '# Order Flow',
+      steps: [
+        {
+          id: 'Start',
+          title: 'Start',
+        },
+      ],
+    })
+      .addStep({ id: 'End' })
+      .build();
+
+    expect(flow.steps).toEqual([
+      {
+        id: 'Start',
+        title: 'Start',
+      },
+      {
+        id: 'End',
+        title: 'End',
+      },
+    ]);
+  });
+
+  it('throws an error when the same step id is added twice', () => {
+    expect(() =>
+      FlowBuilder.create({
+        id: 'OrderFlow',
+        name: 'Order Flow',
+        version: '1.0.0',
+        markdown: '# Order Flow',
+      })
+        .addStep({ id: 'Start' })
+        .addStep({ id: 'Start' })
+    ).toThrowError('Flow step with id "Start" already exists');
+  });
+
+  it('normalizes string and number next steps into step pointers', () => {
+    const flow = FlowBuilder.create({
+      id: 'OrderFlow',
+      name: 'Order Flow',
+      version: '1.0.0',
+      markdown: '# Order Flow',
+    })
+      .addStep({ id: 'Start', nextSteps: ['Middle', 3] })
+      .addStep({ id: 'Middle' })
+      .addStep({ id: 3, title: 'End' })
+      .build();
+
+    expect(flow.steps).toEqual([
+      {
+        id: 'Start',
+        title: 'Start',
+        next_steps: [{ id: 'Middle' }, { id: 3 }],
+      },
+      {
+        id: 'Middle',
+        title: 'Middle',
+      },
+      {
+        id: 3,
+        title: 'End',
+      },
+    ]);
+  });
+
+  it('builds message, service, data store, data product, external system, flow, actor, and custom details from explicit payloads', () => {
+    const flow = FlowBuilder.create({
+      id: 'OrderFlow',
+      name: 'Order Flow',
+      version: '1.0.0',
+      markdown: '# Order Flow',
+    })
+      .addMessageStep({
+        id: 'PlaceOrderStep',
+        title: 'Place Order',
+        message: { id: 'PlaceOrder', version: '1.0.0' },
+      })
+      .addServiceStep({
+        id: 'OrderServiceStep',
+        title: 'Order Service',
+        service: { id: 'OrderService', version: '1.0.0' },
+      })
+      .addDataStoreStep({
+        id: 'OrdersDBStep',
+        title: 'Orders DB',
+        container: { id: 'OrdersDB', version: '1.0.0' },
+      })
+      .addDataProductStep({
+        id: 'OrderAnalyticsStep',
+        title: 'Order Analytics',
+        dataProduct: { id: 'OrderAnalytics', version: '1.0.0' },
+      })
+      .addExternalSystemStep({
+        id: 'SAPStep',
+        title: 'SAP',
+        externalSystem: { name: 'SAP', summary: 'ERP', url: 'https://example.com/sap' },
+      })
+      .addFlowStep({
+        id: 'RewardStep',
+        title: 'Rewarding',
+        flow: { id: 'RewardFlow', version: '1.0.0' },
+      })
+      .addActorStep({
+        id: 'CustomerStep',
+        title: 'Customer',
+        actor: { name: 'Customer', summary: 'Buyer' },
+      })
+      .addCustomStep({
+        id: 'CustomStep',
+        title: 'Custom',
+        custom: { title: 'Custom Node', type: 'manual' },
+      })
+      .build();
+
+    expect(flow.steps).toEqual([
+      {
+        id: 'PlaceOrderStep',
+        title: 'Place Order',
+        message: { id: 'PlaceOrder', version: '1.0.0' },
+      },
+      {
+        id: 'OrderServiceStep',
+        title: 'Order Service',
+        service: { id: 'OrderService', version: '1.0.0' },
+      },
+      {
+        id: 'OrdersDBStep',
+        title: 'Orders DB',
+        container: { id: 'OrdersDB', version: '1.0.0' },
+      },
+      {
+        id: 'OrderAnalyticsStep',
+        title: 'Order Analytics',
+        dataProduct: { id: 'OrderAnalytics', version: '1.0.0' },
+      },
+      {
+        id: 'SAPStep',
+        title: 'SAP',
+        externalSystem: { name: 'SAP', summary: 'ERP', url: 'https://example.com/sap' },
+      },
+      {
+        id: 'RewardStep',
+        title: 'Rewarding',
+        flow: { id: 'RewardFlow', version: '1.0.0' },
+      },
+      {
+        id: 'CustomerStep',
+        title: 'Customer',
+        actor: { name: 'Customer', summary: 'Buyer' },
+      },
+      {
+        id: 'CustomStep',
+        title: 'Custom',
+        custom: { title: 'Custom Node', type: 'manual' },
+      },
+    ]);
+  });
+
+  it('builds a data store step from the step id when no explicit data store payload is provided', () => {
+    const flow = FlowBuilder.create({
+      id: 'OrderFlow',
+      name: 'Order Flow',
+      version: '1.0.0',
+      markdown: '# Order Flow',
+    })
+      .addDataStoreStep({ id: 'OrdersDB' })
+      .build();
+
+    expect(flow.steps).toEqual([
+      {
+        id: 'OrdersDB',
+        title: 'OrdersDB',
+        container: { id: 'OrdersDB' },
+      },
+    ]);
+  });
+
+  it('builds a data product step from the step id when no explicit data product payload is provided', () => {
+    const flow = FlowBuilder.create({
+      id: 'OrderFlow',
+      name: 'Order Flow',
+      version: '1.0.0',
+      markdown: '# Order Flow',
+    })
+      .addDataProductStep({ id: 'OrderAnalytics' })
+      .build();
+
+    expect(flow.steps).toEqual([
+      {
+        id: 'OrderAnalytics',
+        title: 'OrderAnalytics',
+        dataProduct: { id: 'OrderAnalytics' },
+      },
+    ]);
+  });
+
+  it('throws an error when a step references a missing next step', () => {
+    expect(() =>
+      FlowBuilder.create({
+        id: 'OrderFlow',
+        name: 'Order Flow',
+        version: '1.0.0',
+        markdown: '# Order Flow',
+      })
+        .addStep({
+          id: 'Start',
+          nextSteps: [{ id: 'Missing' }],
+        })
+        .build()
+    ).toThrowError('Flow step "Start" references missing next step "Missing"');
+  });
+});
diff --git a/packages/sdk/src/test/messages.test.ts b/packages/sdk/src/test/messages.test.ts
new file mode 100644
index 000000000..30e87ec38
--- /dev/null
+++ b/packages/sdk/src/test/messages.test.ts
@@ -0,0 +1,894 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-messages');
+
+const {
+  getMessageBySchemaPath,
+  getSchemaForMessage,
+  writeEvent,
+  addSchemaToEvent,
+  writeCommand,
+  addSchemaToCommand,
+  getProducersAndConsumersForMessage,
+  writeService,
+  writeAgent,
+  addEventToService,
+  addEventToAgent,
+  versionEvent,
+  versionService,
+  getConsumersOfSchema,
+  getProducersOfSchema,
+} = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Messages SDK', () => {
+  describe('getMessageBySchemaPath', () => {
+    it('returns a message from the given schema path to the message,', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        attachments: ['https://example.com'],
+      });
+
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        }
+      }`;
+
+      await addSchemaToEvent('InventoryAdjusted', { schema, fileName: 'schema.json' });
+
+      const test = await getMessageBySchemaPath('events/InventoryAdjusted/schema.json');
+
+      expect(test).toEqual({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        attachments: ['https://example.com'],
+      });
+    });
+  });
+
+  describe('getProducersAndConsumersForMessage', () => {
+    it('returns the producers and consumers for a given message', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addEventToService('InventoryService', 'sends', { id: 'InventoryAdjusted', version: '0.0.1' }, '0.0.1');
+      await addEventToService('OrderService', 'receives', { id: 'InventoryAdjusted', version: '0.0.1' }, '0.0.1');
+
+      const { producers, consumers } = await getProducersAndConsumersForMessage('InventoryAdjusted', '0.0.1');
+
+      expect(producers).toEqual([
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          sends: [
+            {
+              id: 'InventoryAdjusted',
+              version: '0.0.1',
+            },
+          ],
+        },
+      ]);
+      expect(consumers).toEqual([
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          receives: [
+            {
+              id: 'InventoryAdjusted',
+              version: '0.0.1',
+            },
+          ],
+        },
+      ]);
+    });
+
+    it('returns agents as producers and consumers for a given message', async () => {
+      await writeEvent({
+        id: 'OrderConfirmed',
+        name: 'Order Confirmed',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeAgent({
+        id: 'OrderSupportAgent',
+        name: 'Order Support Agent',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeAgent({
+        id: 'InventoryRebalancingAgent',
+        name: 'Inventory Rebalancing Agent',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addEventToAgent('OrderSupportAgent', 'receives', { id: 'OrderConfirmed', version: '0.0.1' }, '0.0.1');
+      await addEventToAgent('InventoryRebalancingAgent', 'sends', { id: 'OrderConfirmed', version: '0.0.1' }, '0.0.1');
+
+      const { producers, consumers } = await getProducersAndConsumersForMessage('OrderConfirmed', '0.0.1');
+
+      expect(producers).toEqual([
+        {
+          id: 'InventoryRebalancingAgent',
+          name: 'Inventory Rebalancing Agent',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          sends: [
+            {
+              id: 'OrderConfirmed',
+              version: '0.0.1',
+            },
+          ],
+        },
+      ]);
+      expect(consumers).toEqual([
+        {
+          id: 'OrderSupportAgent',
+          name: 'Order Support Agent',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          receives: [
+            {
+              id: 'OrderConfirmed',
+              version: '0.0.1',
+            },
+          ],
+        },
+      ]);
+    });
+
+    it('when the service sends a message, but the version is not specified and the message is the latest version, it should be added to the sends of the service', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        sends: [
+          {
+            id: 'InventoryAdjusted',
+          },
+        ],
+      });
+
+      const { producers } = await getProducersAndConsumersForMessage('InventoryAdjusted', '0.0.1');
+
+      expect(producers).toEqual([
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          sends: [
+            {
+              id: 'InventoryAdjusted',
+            },
+          ],
+          markdown: '# Hello world',
+          summary: 'This is a summary',
+        },
+      ]);
+    });
+
+    it('when the service receives a message, but the version is not specified and the message is the latest version, it should be added to the receives of the service', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        receives: [
+          {
+            id: 'InventoryAdjusted',
+          },
+        ],
+      });
+
+      const { consumers } = await getProducersAndConsumersForMessage('InventoryAdjusted', '0.0.1');
+
+      expect(consumers).toEqual([
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          receives: [
+            {
+              id: 'InventoryAdjusted',
+            },
+          ],
+          markdown: '# Hello world',
+          summary: 'This is a summary',
+        },
+      ]);
+    });
+
+    it('when the service sends a message, but the version is not specified and the message is not the latest version, it should not be added to the sends of the service', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await versionEvent('InventoryAdjusted');
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        sends: [
+          {
+            id: 'InventoryAdjusted',
+          },
+        ],
+      });
+
+      const { producers } = await getProducersAndConsumersForMessage('InventoryAdjusted', '0.0.1');
+
+      expect(producers).toEqual([]);
+    });
+
+    it('when the service sends the message using semver versioning, and the message matches the semver versioning, that service should be returned as a producer', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        sends: [
+          {
+            id: 'InventoryAdjusted',
+            version: '~0.0.1',
+          },
+        ],
+      });
+
+      await writeService({
+        id: 'OrderService',
+        name: 'Order Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        sends: [
+          {
+            id: 'InventoryAdjusted',
+            version: '>0.0.1',
+          },
+        ],
+      });
+
+      const { producers } = await getProducersAndConsumersForMessage('InventoryAdjusted', '0.0.2');
+
+      expect(producers).toEqual([
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '0.0.1',
+          sends: [
+            {
+              id: 'InventoryAdjusted',
+              version: '>0.0.1',
+            },
+          ],
+          markdown: '# Hello world',
+          summary: 'This is a summary',
+        },
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          sends: [
+            {
+              id: 'InventoryAdjusted',
+              version: '~0.0.1',
+            },
+          ],
+          markdown: '# Hello world',
+          summary: 'This is a summary',
+        },
+      ]);
+    });
+
+    it('when latestOnly is false, it returns the all versions of the services that consume a message', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        receives: [
+          {
+            id: 'InventoryAdjusted',
+            version: '0.0.2',
+          },
+        ],
+      });
+
+      await versionService('InventoryService');
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        receives: [
+          {
+            id: 'InventoryAdjusted',
+            version: '0.0.2',
+          },
+        ],
+      });
+
+      const { consumers } = await getProducersAndConsumersForMessage('InventoryAdjusted', '0.0.2', { latestOnly: false });
+
+      expect(consumers).toEqual([
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '1.0.0',
+          markdown: '# Hello world',
+          summary: 'This is a summary',
+          receives: [
+            {
+              id: 'InventoryAdjusted',
+              version: '0.0.2',
+            },
+          ],
+        },
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          markdown: '# Hello world',
+          summary: 'This is a summary',
+          receives: [
+            {
+              id: 'InventoryAdjusted',
+              version: '0.0.2',
+            },
+          ],
+        },
+      ]);
+    });
+  });
+
+  describe('getConsumersOfSchema', () => {
+    it('returns the consumers of a given schema path', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        }
+      }`;
+
+      await addSchemaToEvent('InventoryAdjusted', { schema, fileName: 'schema.json' });
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        receives: [
+          {
+            id: 'InventoryAdjusted',
+            version: '0.0.2',
+          },
+        ],
+      });
+
+      const consumers = await getConsumersOfSchema('events/InventoryAdjusted/schema.json');
+
+      expect(consumers).toEqual([
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          markdown: '# Hello world',
+          summary: 'This is a summary',
+          receives: [
+            {
+              id: 'InventoryAdjusted',
+              version: '0.0.2',
+            },
+          ],
+        },
+      ]);
+    });
+
+    it('when a service is a consumer, but the version is not specified, it matches the latest version of the message', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        }
+      }`;
+
+      await addSchemaToEvent('InventoryAdjusted', { schema, fileName: 'schema.json' });
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        receives: [
+          {
+            id: 'InventoryAdjusted',
+          },
+        ],
+      });
+
+      const consumers = await getConsumersOfSchema('events/InventoryAdjusted/schema.json');
+
+      expect(consumers).toEqual([
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          markdown: '# Hello world',
+          summary: 'This is a summary',
+          receives: [
+            {
+              id: 'InventoryAdjusted',
+            },
+          ],
+        },
+      ]);
+    });
+
+    it('when a service is a consumer, but the version does not match the consumer is not returned', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        }
+      }`;
+
+      await addSchemaToEvent('InventoryAdjusted', { schema, fileName: 'schema.json' });
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        receives: [
+          {
+            id: 'InventoryAdjusted',
+            version: '1.0.0',
+          },
+        ],
+      });
+
+      const consumers = await getConsumersOfSchema('events/InventoryAdjusted/schema.json');
+
+      expect(consumers).toEqual([]);
+    });
+    it('if no consumers are found for the schema, an empty array is returned', async () => {
+      const consumers = await getConsumersOfSchema('events/InventoryAdjusted/schema.json');
+      expect(consumers).toEqual([]);
+    });
+  });
+
+  describe('getProducersOfSchema', () => {
+    it('returns the producers of a given schema path', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        }
+      }`;
+
+      await addSchemaToEvent('InventoryAdjusted', { schema, fileName: 'schema.json' });
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        sends: [
+          {
+            id: 'InventoryAdjusted',
+            version: '0.0.2',
+          },
+        ],
+      });
+
+      const producers = await getProducersOfSchema('events/InventoryAdjusted/schema.json');
+
+      expect(producers).toEqual([
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          markdown: '# Hello world',
+          summary: 'This is a summary',
+          sends: [
+            {
+              id: 'InventoryAdjusted',
+              version: '0.0.2',
+            },
+          ],
+        },
+      ]);
+    });
+
+    it('when a service is a producer, but the version is not specified, it matches the latest version of the message', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        }
+      }`;
+
+      await addSchemaToEvent('InventoryAdjusted', { schema, fileName: 'schema.json' });
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        sends: [
+          {
+            id: 'InventoryAdjusted',
+          },
+        ],
+      });
+
+      const producers = await getProducersOfSchema('events/InventoryAdjusted/schema.json');
+
+      expect(producers).toEqual([
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          markdown: '# Hello world',
+          summary: 'This is a summary',
+          sends: [
+            {
+              id: 'InventoryAdjusted',
+            },
+          ],
+        },
+      ]);
+    });
+
+    it('when a service is a producer, but the version does not match the producer is not returned', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        }
+      }`;
+
+      await addSchemaToEvent('InventoryAdjusted', { schema, fileName: 'schema.json' });
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        sends: [
+          {
+            id: 'InventoryAdjusted',
+            version: '1.0.0',
+          },
+        ],
+      });
+
+      const producers = await getProducersOfSchema('events/InventoryAdjusted/schema.json');
+
+      expect(producers).toEqual([]);
+    });
+    it('if no producers are found for the schema, an empty array is returned', async () => {
+      const producers = await getProducersOfSchema('events/InventoryAdjusted/schema.json');
+      expect(producers).toEqual([]);
+    });
+  });
+
+  describe('getSchemaForMessage', () => {
+    it('returns the schema for a message by id and version', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        schemaPath: 'schema.json',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const schemaObj = { type: 'object', properties: { name: { type: 'string' } } };
+      await addSchemaToEvent('InventoryAdjusted', { schema: JSON.stringify(schemaObj), fileName: 'schema.json' });
+
+      const result = await getSchemaForMessage('InventoryAdjusted', '0.0.1');
+
+      expect(result).toBeDefined();
+      expect(JSON.parse(result!.schema)).toEqual(schemaObj);
+      expect(result!.fileName).toEqual('schema.json');
+    });
+
+    it('returns the schema for the latest version when no version is specified', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        schemaPath: 'schema.json',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const schemaObj = { type: 'object', properties: { name: { type: 'string' } } };
+      await addSchemaToEvent('InventoryAdjusted', { schema: JSON.stringify(schemaObj), fileName: 'schema.json' });
+
+      const result = await getSchemaForMessage('InventoryAdjusted');
+
+      expect(result).toBeDefined();
+      expect(JSON.parse(result!.schema)).toEqual(schemaObj);
+      expect(result!.fileName).toEqual('schema.json');
+    });
+
+    it('returns the schema for a versioned message', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        schemaPath: 'schema.json',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const schemaObjV1 = { version: 1 };
+      await addSchemaToEvent('InventoryAdjusted', { schema: JSON.stringify(schemaObjV1), fileName: 'schema.json' });
+
+      await versionEvent('InventoryAdjusted');
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '1.0.0',
+        schemaPath: 'schema.json',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const schemaObjV2 = { version: 2 };
+      await addSchemaToEvent('InventoryAdjusted', { schema: JSON.stringify(schemaObjV2), fileName: 'schema.json' });
+
+      const resultV1 = await getSchemaForMessage('InventoryAdjusted', '0.0.1');
+      expect(resultV1).toBeDefined();
+      expect(JSON.parse(resultV1!.schema)).toEqual(schemaObjV1);
+
+      const resultLatest = await getSchemaForMessage('InventoryAdjusted');
+      expect(resultLatest).toBeDefined();
+      expect(JSON.parse(resultLatest!.schema)).toEqual(schemaObjV2);
+    });
+
+    it('returns undefined when the message does not exist', async () => {
+      const result = await getSchemaForMessage('NonExistent', '0.0.1');
+      expect(result).toBeUndefined();
+    });
+
+    it('returns undefined when the message has no schemaPath', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const result = await getSchemaForMessage('InventoryAdjusted', '0.0.1');
+      expect(result).toBeUndefined();
+    });
+
+    it('returns undefined when the schema file does not exist on disk', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        schemaPath: 'missing-schema.json',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const result = await getSchemaForMessage('InventoryAdjusted', '0.0.1');
+      expect(result).toBeUndefined();
+    });
+
+    it('works with commands', async () => {
+      await writeCommand({
+        id: 'PlaceOrder',
+        name: 'Place Order',
+        version: '1.0.0',
+        schemaPath: 'schema.json',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const schemaObj = { type: 'object' };
+      await addSchemaToCommand('PlaceOrder', { schema: JSON.stringify(schemaObj), fileName: 'schema.json' });
+
+      const result = await getSchemaForMessage('PlaceOrder', '1.0.0');
+
+      expect(result).toBeDefined();
+      expect(JSON.parse(result!.schema)).toEqual(schemaObj);
+      expect(result!.fileName).toEqual('schema.json');
+    });
+
+    it('works with non-JSON schema files (e.g. avro)', async () => {
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        schemaPath: 'schema.avro',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const avroSchema = 'non-json avro content here';
+      await addSchemaToEvent('InventoryAdjusted', { schema: avroSchema, fileName: 'schema.avro' });
+
+      const result = await getSchemaForMessage('InventoryAdjusted', '0.0.1');
+
+      expect(result).toBeDefined();
+      expect(result!.schema).toEqual(avroSchema);
+      expect(result!.fileName).toEqual('schema.avro');
+    });
+  });
+});
diff --git a/packages/sdk/src/test/queries.test.ts b/packages/sdk/src/test/queries.test.ts
new file mode 100644
index 000000000..bbfcece6d
--- /dev/null
+++ b/packages/sdk/src/test/queries.test.ts
@@ -0,0 +1,1596 @@
+// sum.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-queries');
+
+const {
+  writeQuery,
+  writeQueryToService,
+  getQuery,
+  getQueries,
+  rmQuery,
+  rmQueryById,
+  versionQuery,
+  addFileToQuery,
+  addSchemaToQuery,
+  queryHasVersion,
+  writeServiceToDomain,
+  writeService,
+  writeDomain,
+} = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Queries SDK', () => {
+  describe('getQuery', () => {
+    it('returns the given query id from EventCatalog and the latest version when no version is given,', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        attachments: ['https://example.com'],
+      });
+
+      const test = await getQuery('GetOrder');
+
+      expect(test).toEqual({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        attachments: ['https://example.com'],
+      });
+    });
+
+    it('returns the given query id from EventCatalog and the latest version when no version is given and the query is inside a services folder,', async () => {
+      await writeQuery(
+        {
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/InventoryService/GetOrder' }
+      );
+
+      const test = await getQuery('GetOrder');
+
+      expect(test).toEqual({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the given query id from EventCatalog and the requested version when a version is given,', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await versionQuery('GetOrder');
+
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '1.0.0',
+        summary: 'This is version 1.0.0',
+        markdown: '# Hello world',
+      });
+
+      const test = await getQuery('GetOrder', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the latest version of the query if the version matches the latest version', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const test = await getQuery('GetOrder', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the version of the query even if the query does not match semver matching', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '100',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const test = await getQuery('GetOrder', '100');
+
+      expect(test).toEqual({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '100',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the query with the schema attached when the attachSchema option is set to true', async () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+        },
+      };
+
+      const file = { schema: JSON.stringify(schema), fileName: 'schema.json' };
+
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        schemaPath: 'schema.json',
+      });
+
+      await addSchemaToQuery('GetOrder', file);
+
+      const test = await getQuery('GetOrder', '0.0.1', { attachSchema: true });
+
+      expect(test.schema).toEqual(schema);
+    });
+
+    it('does not attach the schema if the attachSchema option is set to false', async () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+        },
+      };
+
+      const file = { schema: JSON.stringify(schema), fileName: 'schema.json' };
+
+      await writeQuery({
+        id: 'GetOrder2',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        schemaPath: 'schema.json',
+      });
+
+      await addSchemaToQuery('GetOrder2', file);
+
+      const test = await getQuery('GetOrder2', '0.0.1', { attachSchema: false });
+
+      expect(test.schema).toEqual(undefined);
+    });
+
+    it('returns undefined when a given resource is not found', async () => {
+      const query = await getQuery('GetOrder');
+      await expect(query).toEqual(undefined);
+    });
+
+    it('throws an error if the query is found but not the version', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await expect(await getQuery('GetOrder', '1.0.0')).toEqual(undefined);
+    });
+
+    describe('when queries are within a service that is within a domain', async () => {
+      it('returns the given query id from EventCatalog and the latest version when no version is given,', async () => {
+        await writeDomain({
+          id: 'Shopping',
+          name: 'Shopping Domain',
+          version: '0.0.1',
+          summary: 'Domain that handles the shopping',
+          markdown: '# Hello world',
+        });
+
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        const test = await getQuery('GetOrder');
+
+        expect(test).toEqual({
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+      });
+
+      it('returns the given query id from EventCatalog and the latest version when no version is given and the query is inside a services folder,', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeDomain({
+          id: 'Shopping',
+          name: 'Shopping Domain',
+          version: '0.0.1',
+          summary: 'Domain that handles the shopping',
+          markdown: '# Hello world',
+        });
+
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        const test = await getQuery('GetOrder');
+
+        expect(test).toEqual({
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+      });
+
+      it('returns the given query id from EventCatalog and the requested version when a version is given,', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        await versionQuery('GetOrder');
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        const test = await getQuery('GetOrder', '0.0.1');
+
+        expect(test).toEqual({
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+      });
+
+      it('returns the latest version of the query if the version matches the latest version', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        const test = await getQuery('GetOrder', '0.0.1');
+
+        expect(test).toEqual({
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+      });
+
+      it('returns the version of the query even if the query does not match semver matching', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '100',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '100',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '100',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        const test = await getQuery('GetOrder', '100');
+
+        expect(test).toEqual({
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '100',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+      });
+    });
+  });
+
+  describe('getQueries', () => {
+    it('returns all the queries in the catalog,', async () => {
+      // versioned query
+      await writeQuery({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // latest query
+      await writeQuery(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { versionExistingContent: true }
+      );
+
+      // query in the services folder
+      await writeQuery(
+        {
+          id: 'OrderComplete',
+          name: 'Order Complete',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService' }
+      );
+
+      const queries = await getQueries({ latestOnly: false });
+
+      expect(queries).toEqual(
+        expect.arrayContaining([
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'OrderComplete',
+            name: 'Order Complete',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+        ])
+      );
+    });
+    it('returns only the latest queries when `latestOnly` is set to true,', async () => {
+      // versioned query
+      await writeQuery({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // latest query
+      await writeQuery(
+        {
+          id: 'InventoryAdjusted',
+          name: 'Inventory Adjusted',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { versionExistingContent: true }
+      );
+
+      // query in the services folder
+      await writeQuery(
+        {
+          id: 'OrderComplete',
+          name: 'Order Complete',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService' }
+      );
+
+      // query in the services folder
+      await writeQuery(
+        {
+          id: 'OrderComplete',
+          name: 'Order Complete',
+          version: '2.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService', versionExistingContent: true }
+      );
+
+      const queries = await getQueries({ latestOnly: true });
+
+      expect(queries).toEqual(
+        expect.arrayContaining([
+          {
+            id: 'InventoryAdjusted',
+            name: 'Inventory Adjusted',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'OrderComplete',
+            name: 'Order Complete',
+            version: '2.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+        ])
+      );
+    });
+    it('returns the queries with the schema attached when the attachSchema option is set to true', async () => {
+      const schema = {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+        },
+      };
+
+      const file = { schema: JSON.stringify(schema), fileName: 'schema.json' };
+
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        schemaPath: 'schema.json',
+      });
+
+      await addSchemaToQuery('GetOrder', file);
+
+      const test = await getQueries({ attachSchema: true });
+
+      expect(test[0].schema).toEqual(schema);
+    });
+  });
+
+  describe('writeQuery', () => {
+    it('writes the given query to EventCatalog and assumes the path if one if not given', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const query = await getQuery('GetOrder');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(true);
+
+      expect(query).toEqual({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('writes the given query to EventCatalog (as md). When no version if given for the query the service is added to the latest service', async () => {
+      await writeQuery(
+        {
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { format: 'md' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.md'))).toBe(true);
+    });
+
+    it('when operation is given, it writes the query with the given operation', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        operation: {
+          method: 'GET',
+          path: '/orders/{id}',
+          statusCodes: ['200', '404'],
+        },
+      });
+
+      const query = await getQuery('GetOrder');
+
+      expect(query).toEqual({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        operation: {
+          method: 'GET',
+          path: '/orders/{id}',
+          statusCodes: ['200', '404'],
+        },
+      });
+    });
+
+    it('when operation is given with only a path, it writes the query with the partial operation', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        operation: {
+          path: '/orders',
+        },
+      });
+
+      const query = await getQuery('GetOrder');
+
+      expect(query).toEqual({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        operation: {
+          path: '/orders',
+        },
+      });
+    });
+
+    it('writes the given query to EventCatalog under the correct path when a path is given', async () => {
+      await writeQuery(
+        {
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/Inventory/GetOrder' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/Inventory/GetOrder', 'index.mdx'))).toBe(true);
+    });
+
+    it('throws an error when trying to write an query that already exists', async () => {
+      const createQuery = async () =>
+        writeQuery({
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+      await createQuery();
+
+      await expect(
+        writeQuery({
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        })
+      ).rejects.toThrowError('Failed to write GetOrder (query) as the version 0.0.1 already exists');
+    });
+
+    it('overrides the query when trying to write an query that already exists and override is true', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeQuery(
+        {
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: 'Overridden content',
+        },
+        {
+          override: true,
+        }
+      );
+
+      const query = await getQuery('GetOrder');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(true);
+      expect(query.markdown).toBe('Overridden content');
+    });
+
+    describe('versionExistingContent', () => {
+      it('versions the previous query when trying to write a query that already exists and versionExistingContent is true and the new version number is greater than the previous one', async () => {
+        await writeQuery({
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        });
+
+        await writeQuery(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: 'New',
+          },
+          { versionExistingContent: true }
+        );
+
+        const query = await getQuery('GetOrder');
+        expect(query.version).toBe('1.0.0');
+        expect(query.markdown).toBe('New');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder/versioned/0.0.1', 'index.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(true);
+      });
+
+      it('throws an error when trying to write a query and versionExistingContent is true and the new version number is not greater than the previous one', async () => {
+        await writeQuery(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: 'New',
+          },
+          { versionExistingContent: true }
+        );
+
+        await expect(
+          writeQuery(
+            {
+              id: 'GetOrder',
+              name: 'Get Order',
+              version: '0.0.0',
+              summary: 'This is a summary',
+              markdown: 'New',
+            },
+            { versionExistingContent: true }
+          )
+        ).rejects.toThrowError('New version 0.0.0 is not greater than current version 1.0.0');
+      });
+    });
+  });
+
+  describe('writeQueryToService', () => {
+    it('writes an query to the given service. When no version if given for the service the query is added to the latest service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeQueryToService(
+        {
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'InventoryService',
+        }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'index.mdx'))).toBe(true);
+    });
+    it('writes an query to the given service (as md). When no version if given for the service the query is added to the latest service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeQueryToService(
+        {
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'InventoryService',
+        },
+        { format: 'md' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'index.md'))).toBe(true);
+    });
+    it('writes an query to the given service. When a version is given for the service the query is added to that service version', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'Service that handles inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeQueryToService(
+        {
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'InventoryService',
+          version: '1.0.0',
+        }
+      );
+      expect(
+        fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/versioned/1.0.0/queries/GetOrder', 'index.mdx'))
+      ).toBe(true);
+    });
+    it('writes an query to the given service. When a version is the latest the query is added to the latest version of the service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeQueryToService(
+        {
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'InventoryService',
+          version: 'latest',
+        }
+      );
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'index.mdx'))).toBe(true);
+    });
+
+    it('when override is true, it overrides the event if it already exists', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // Write the first event
+      await writeQueryToService(
+        {
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'InventoryService',
+        }
+      );
+
+      await writeQueryToService(
+        {
+          id: 'GetOrder',
+          name: 'Get Order',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: 'Overridden content',
+        },
+        {
+          id: 'InventoryService',
+        },
+        {
+          override: true,
+        }
+      );
+
+      const query = await getQuery('GetOrder', '0.0.1');
+
+      expect(query.markdown).toBe('Overridden content');
+    });
+  });
+
+  describe('rmQuery', () => {
+    it('removes an query from eventcatalog', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(true);
+
+      await rmQuery('/GetOrder');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(false);
+    });
+  });
+
+  describe('rmQueryById', () => {
+    it('removes an query from eventcatalog by id', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(true);
+
+      await rmQueryById('GetOrder');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(false);
+    });
+
+    it('removes a query and all files in that query', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      fs.writeFileSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'schema.json'), 'SCHEMA!');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(true);
+
+      await rmQueryById('GetOrder');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(false);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'schema.json'))).toBe(false);
+    });
+
+    it('removes a query but keeps its files when persistFiles is set to true', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      fs.writeFileSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'schema.json'), 'SCHEMA!');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(true);
+
+      await rmQueryById('GetOrder', '0.0.1', true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(false);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'schema.json'))).toBe(true);
+    });
+
+    it('removes an query from eventcatalog by id and version', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(true);
+
+      await rmQueryById('GetOrder', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(false);
+    });
+
+    it('if version is given, only removes that version and not any other versions of the query', async () => {
+      // write the first queries
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await versionQuery('GetOrder');
+
+      // Write the versioned query
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder/versioned/0.0.1', 'index.mdx'))).toBe(true);
+
+      await rmQueryById('GetOrder', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder/versioned/0.0.2', 'index.mdx'))).toBe(false);
+    });
+
+    describe('when queries are within a service directory', () => {
+      it('removes an query from EventCatalog by id', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'index.mdx'))).toBe(true);
+        await rmQueryById('GetOrder');
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'index.mdx'))).toBe(false);
+      });
+
+      it('if version is given, only removes that version and not any other versions of the query', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        await versionQuery('GetOrder');
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.2',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+          }
+        );
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'index.mdx'))).toBe(true);
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder/versioned/0.0.1', 'index.mdx'))
+        ).toBe(true);
+
+        await rmQueryById('GetOrder', '0.0.1');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'index.mdx'))).toBe(true);
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder/versioned/0.0.1', 'index.mdx'))
+        ).toBe(false);
+      });
+    });
+  });
+
+  describe('versionQuery', () => {
+    it('adds the given query to the versioned directory and removes itself from the root', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // // Add random file in there
+      // await fs.writeFileSync(path.join(CATALOG_PATH, 'queries/Inventory/GetOrder', 'schema.json'), 'SCHEMA!');
+
+      await versionQuery('GetOrder');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder/versioned/0.0.2', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(false);
+    });
+    it('adds the given query to the versioned directory and all files that are associated to it', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // Add random file in there
+      await fs.writeFileSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'schema.json'), 'SCHEMA!');
+
+      await versionQuery('GetOrder');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder/versioned/0.0.2', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder/versioned/0.0.2', 'schema.json'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'index.mdx'))).toBe(false);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'schema.json'))).toBe(false);
+    });
+
+    describe('when queries are within a service directory', () => {
+      it('adds the given query to the versioned directory and removes itself from the root', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.2',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        await versionQuery('GetOrder');
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder/versioned/0.0.2', 'index.mdx'))
+        ).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'index.mdx'))).toBe(false);
+      });
+      it('adds the given query to the versioned directory and all files that are associated to it', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.2',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        // Add random file in there
+        await fs.writeFileSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'schema.json'), 'SCHEMA!');
+
+        await versionQuery('GetOrder');
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder/versioned/0.0.2', 'index.mdx'))
+        ).toBe(true);
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder/versioned/0.0.2', 'schema.json'))
+        ).toBe(true);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'index.mdx'))).toBe(false);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'schema.json'))).toBe(false);
+      });
+    });
+  });
+
+  describe('addFileToQuery', () => {
+    it('takes a given file and writes it to the location of the given query', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addFileToQuery('GetOrder', file);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'test.txt'))).toBe(true);
+    });
+
+    it('takes a given file and version and writes the file to the correct location', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // version the query
+      await versionQuery('GetOrder');
+
+      await addFileToQuery('GetOrder', file, '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder/versioned/0.0.1', 'test.txt'))).toBe(true);
+    });
+
+    it('throws an error when trying to write to a query that does not exist', () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      expect(addFileToQuery('GetOrder', file)).rejects.toThrowError('Cannot find directory to write file to');
+    });
+
+    describe('when queries are within a service directory', () => {
+      it('takes a given file and writes it to the location of the given query', async () => {
+        const file = { content: 'hello', fileName: 'test.txt' };
+
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        await addFileToQuery('GetOrder', file);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'test.txt'))).toBe(true);
+      });
+
+      it('takes a given file and version and writes the file to the correct location', async () => {
+        const file = { content: 'hello', fileName: 'test.txt' };
+
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        await versionQuery('GetOrder');
+
+        await addFileToQuery('GetOrder', file, '0.0.1');
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder/versioned/0.0.1', 'test.txt'))
+        ).toBe(true);
+      });
+    });
+  });
+
+  describe('addSchemaToQuery', () => {
+    it('takes a given file and writes it to the location of the given query', async () => {
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "age": {
+            "type": "number"
+          }
+        }
+      }`;
+      const file = { schema, fileName: 'schema.json' };
+
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addSchemaToQuery('GetOrder', file);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder', 'schema.json'))).toBe(true);
+    });
+
+    it('takes a given file and version and writes the file to the correct location', async () => {
+      const schema = `{
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "age": {
+            "type": "number"
+          }
+        }
+      }`;
+      const file = { schema, fileName: 'schema.json' };
+
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // version the query
+      await versionQuery('GetOrder');
+
+      await addSchemaToQuery('GetOrder', file, '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'queries/GetOrder/versioned/0.0.1', 'schema.json'))).toBe(true);
+    });
+
+    it('throws an error when trying to write to a query that does not exist', () => {
+      const file = { schema: 'hello', fileName: 'test.txt' };
+
+      expect(addSchemaToQuery('GetOrder', file)).rejects.toThrowError('Cannot find directory to write file to');
+    });
+
+    describe('when queries are within a service directory', () => {
+      it('takes a given file and writes it to the location of the given query', async () => {
+        const schema = `{
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "age": {
+              "type": "number"
+            }
+          }
+        }`;
+        const file = { schema, fileName: 'schema.json' };
+
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        await addSchemaToQuery('GetOrder', file);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder', 'schema.json'))).toBe(true);
+      });
+
+      it('takes a given file and version and writes the file to the correct location', async () => {
+        const schema = `{
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "age": {
+              "type": "number"
+            }
+          }
+        }`;
+        const file = { schema, fileName: 'schema.json' };
+
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeQueryToService(
+          {
+            id: 'GetOrder',
+            name: 'Get Order',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          { id: 'InventoryService' }
+        );
+
+        await versionQuery('GetOrder');
+
+        await addSchemaToQuery('GetOrder', file, '0.0.1');
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/queries/GetOrder/versioned/0.0.1', 'schema.json'))
+        ).toBe(true);
+      });
+    });
+  });
+
+  describe('queryHasVersion', () => {
+    it('returns true when a given query and version exists in the catalog', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await queryHasVersion('GetOrder', '0.0.1')).toEqual(true);
+    });
+
+    it('returns true when a semver version is given and the version exists in the catalog', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await queryHasVersion('GetOrder', '0.0.x')).toEqual(true);
+    });
+
+    it('returns true when a `latest` version is given and the version exists in the catalog', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await queryHasVersion('GetOrder', 'latest')).toEqual(true);
+    });
+
+    it('returns false when query does not exist in the catalog', async () => {
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await queryHasVersion('GetOrder', '5.0.0')).toEqual(false);
+    });
+  });
+});
diff --git a/packages/sdk/src/test/resources.test.ts b/packages/sdk/src/test/resources.test.ts
new file mode 100644
index 000000000..d8f1760e5
--- /dev/null
+++ b/packages/sdk/src/test/resources.test.ts
@@ -0,0 +1,37 @@
+// users.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-resources');
+
+const { writeEvent, getResourceFolderName } = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Resources SDK', () => {
+  describe('getResourceFolderName', () => {
+    it('returns the folder name of a given resource,', async () => {
+      await writeEvent({
+        id: 'OrderPlaced',
+        version: '1',
+        name: 'OrderPlaced',
+        summary: 'This is an order',
+        markdown: '',
+      });
+
+      const folderName = await getResourceFolderName(CATALOG_PATH, 'OrderPlaced', '1');
+
+      expect(folderName).toEqual('OrderPlaced');
+    });
+  });
+});
diff --git a/packages/sdk/src/test/services.test.ts b/packages/sdk/src/test/services.test.ts
new file mode 100644
index 000000000..da2ea867a
--- /dev/null
+++ b/packages/sdk/src/test/services.test.ts
@@ -0,0 +1,2590 @@
+// sum.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+import { Specifications } from '../types';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-services');
+
+const {
+  writeService,
+  writeServiceToDomain,
+  writeVersionedService,
+  writeEvent,
+  writeCommand,
+  writeEventToService,
+  writeCommandToService,
+  getService,
+  getServiceByPath,
+  getServices,
+  getEvent,
+  getCommand,
+  versionService,
+  rmService,
+  rmServiceById,
+  addFileToService,
+  addEventToService,
+  addCommandToService,
+  addQueryToService,
+  addEntityToService,
+  serviceHasVersion,
+  getSpecificationFilesForService,
+  isService,
+  toService,
+  addDataStoreToService,
+  writeDataStore,
+} = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Services SDK', () => {
+  describe('getService', () => {
+    it('returns the given service id from EventCatalog and the latest version when no version is given,', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+        repository: {
+          language: 'TypeScript',
+          url: 'https://github.com/eventcatalog/eventcatalog',
+        },
+        attachments: ['https://example.com'],
+        diagrams: [{ id: 'InventoryServiceDiagram', version: '1.0.0' }],
+      });
+
+      const test = await getService('InventoryService');
+
+      expect(test).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+        repository: {
+          language: 'TypeScript',
+          url: 'https://github.com/eventcatalog/eventcatalog',
+        },
+        attachments: ['https://example.com'],
+        diagrams: [{ id: 'InventoryServiceDiagram', version: '1.0.0' }],
+      });
+    });
+
+    it('returns the given service id from EventCatalog and the requested version when a version is given,', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await versionService('InventoryService');
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      const test = await getService('InventoryService', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the latest version of the service if the version matches the latest version', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      const test = await getService('InventoryService', '0.0.1');
+
+      expect(test).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns the latest version of the service when `latest` is passed as the version', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await versionService('InventoryService');
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      const test = await getService('InventoryService', 'latest');
+
+      expect(test).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('returns undefined when a service cannot be found', async () => {
+      await expect(await getService('PaymentService')).toEqual(undefined);
+    });
+
+    it('returns undefined if the service is found but not the version', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await expect(await getService('InventoryService', '1.0.0')).toEqual(undefined);
+    });
+
+    it('returns the specifications for the service if the service has specifications', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        specifications: {
+          asyncapiPath: 'spec.yaml',
+          graphqlPath: 'spec.graphql',
+        } satisfies Specifications,
+        markdown: '# Hello world',
+      });
+
+      const test = await getService('InventoryService', 'latest');
+
+      expect(test).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+        specifications: { asyncapiPath: 'spec.yaml', graphqlPath: 'spec.graphql' },
+      });
+    });
+
+    describe('getServiceByPath', () => {
+      it('returns the given service id from EventCatalog and the latest version when no version is given,', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        });
+
+        const pathToService = path.join(CATALOG_PATH, 'services/InventoryService/index.mdx');
+
+        const service = await getServiceByPath(pathToService);
+
+        expect(service).toEqual({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        });
+      });
+
+      it('returns undefined if the service is not found', async () => {
+        await expect(await getServiceByPath(path.join(CATALOG_PATH, 'services/PaymentService/index.mdx'))).toEqual(undefined);
+      });
+    });
+
+    describe('when services are within a domain directory', () => {
+      it('returns the given service id from EventCatalog and the latest version when no version is given,', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        const test = await getService('InventoryService');
+
+        expect(test).toEqual({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        });
+      });
+
+      it('returns the given service id from EventCatalog and the requested version when a version is given,', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await versionService('InventoryService');
+
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '1.0.0',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        const test = await getService('InventoryService', '0.0.1');
+
+        expect(test).toEqual({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        });
+      });
+    });
+  });
+
+  describe('getServices', () => {
+    it('returns all the services in the catalog,', async () => {
+      // versioned service
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // latest service
+      await writeService(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { versionExistingContent: true }
+      );
+
+      // service in the services folder
+      await writeService(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService' }
+      );
+
+      const services = await getServices();
+
+      expect(services).toEqual(
+        expect.arrayContaining([
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'OrderService',
+            name: 'Order Service',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+        ])
+      );
+    });
+
+    it('when messages are nested into the service folder it only returns the services', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await writeEvent(
+        {
+          id: 'InventoryUpdatedEvent',
+          version: '2.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+          name: 'Inventory Updated Event',
+        },
+        { path: '/services/InventoryService' }
+      );
+
+      const services = await getServices();
+
+      expect(services).toEqual([
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+      ]);
+    });
+
+    it('returns only the latest services when `latestOnly` is set to true,', async () => {
+      // versioned service
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      // latest service
+      await writeService(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { versionExistingContent: true }
+      );
+
+      // service in the services folder
+      await writeService(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '1.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService' }
+      );
+
+      // service in the services folder
+      await writeService(
+        {
+          id: 'OrderService',
+          name: 'Order Service',
+          version: '2.0.0',
+          summary: 'This is a summary',
+          markdown: '# Hello world',
+        },
+        { path: '/services/OrderService', versionExistingContent: true }
+      );
+
+      const services = await getServices({ latestOnly: true });
+
+      expect(services).toEqual(
+        expect.arrayContaining([
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '1.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+          {
+            id: 'OrderService',
+            name: 'Order Service',
+            version: '2.0.0',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+          },
+        ])
+      );
+    });
+  });
+
+  describe('writeService', () => {
+    it('writes the given service to EventCatalog and assumes the path if one if not given', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+        sends: [{ id: 'InventoryUpdatedEvent', version: '2.0.0', to: [{ id: 'InventoryChannel', version: '1.0.0' }] }],
+        receives: [{ id: 'OrderComplete', version: '2.0.0', from: [{ id: 'OrderChannel', version: '1.0.0' }] }],
+      });
+
+      const service = await getService('InventoryService');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(true);
+
+      expect(service).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+        sends: [{ id: 'InventoryUpdatedEvent', version: '2.0.0', to: [{ id: 'InventoryChannel', version: '1.0.0' }] }],
+        receives: [{ id: 'OrderComplete', version: '2.0.0', from: [{ id: 'OrderChannel', version: '1.0.0' }] }],
+      });
+    });
+
+    it('writes the given service (as .md) to EventCatalog if the format is .md', async () => {
+      await writeService(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        },
+        { format: 'md' }
+      );
+
+      const service = await getService('InventoryService');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.md'))).toBe(true);
+
+      expect(service).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+    });
+
+    it('writes the given service to EventCatalog under the correct path when a path is given', async () => {
+      await writeService(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        },
+        { path: '/Inventory/InventoryService' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/Inventory/InventoryService', 'index.mdx'))).toBe(true);
+    });
+
+    it('messages written to a service are always unique', async () => {
+      await writeService(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+          sends: [
+            { id: 'InventoryUpdatedEvent', version: '2.0.0' },
+            { id: 'InventoryUpdatedEvent', version: '2.0.0' },
+            { id: 'InventoryRemoved', version: '1.0.0' },
+            { id: 'InventoryRemoved', version: '1.0.0' },
+            { id: 'InventoryUpdated', version: '1.0.0' },
+          ],
+          receives: [
+            { id: 'OrderComplete', version: '2.0.0' },
+            { id: 'OrderComplete', version: '2.0.0' },
+          ],
+        },
+        { path: '/Inventory/InventoryService' }
+      );
+
+      const service = await getService('InventoryService');
+
+      expect(service.sends).toHaveLength(3);
+      expect(service.receives).toHaveLength(1);
+
+      expect(service.sends).toEqual([
+        {
+          id: 'InventoryUpdatedEvent',
+          version: '2.0.0',
+        },
+        {
+          id: 'InventoryRemoved',
+          version: '1.0.0',
+        },
+        {
+          id: 'InventoryUpdated',
+          version: '1.0.0',
+        },
+      ]);
+
+      expect(service.receives).toEqual([
+        {
+          id: 'OrderComplete',
+          version: '2.0.0',
+        },
+      ]);
+    });
+
+    it('throws an error when trying to write an service that already exists', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await expect(
+        writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        })
+      ).rejects.toThrowError('Failed to write InventoryService (service) as the version 0.0.1 already exists');
+    });
+
+    it('overrides the service when trying to write an service that already exists and override is true', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeService(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: 'Overridden content',
+        },
+        { override: true }
+      );
+
+      const service = await getService('InventoryService');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(true);
+      expect(service.markdown).toBe('Overridden content');
+    });
+
+    describe('versionExistingContent', () => {
+      it('versions the previous service when trying to write a service that already exists and versionExistingContent is true and the new version number is greater than the previous one', async () => {
+        await writeService({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        });
+
+        await writeService(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '1.0.0',
+            summary: 'Service tat handles the inventory',
+            markdown: 'New',
+          },
+          { versionExistingContent: true }
+        );
+
+        const service = await getService('InventoryService');
+        expect(service.version).toBe('1.0.0');
+        expect(service.markdown).toBe('New');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/versioned/0.0.1', 'index.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(true);
+      });
+
+      it('throws an error when trying to write a service and versionExistingContent is true and the new version number is not greater than the previous one', async () => {
+        await writeService(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '1.0.0',
+            summary: 'Service tat handles the inventory',
+            markdown: 'New',
+          },
+          { versionExistingContent: true }
+        );
+
+        await expect(
+          writeService(
+            {
+              id: 'InventoryService',
+              name: 'Inventory Service',
+              version: '0.0.0',
+              summary: 'Service tat handles the inventory',
+              markdown: 'New',
+            },
+            { versionExistingContent: true }
+          )
+        ).rejects.toThrowError('New version 0.0.0 is not greater than current version 1.0.0');
+      });
+    });
+  });
+
+  describe('writeVersionedService', () => {
+    it('writes the given service to EventCatalog into versioned folder', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '1.0.0',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+      await writeVersionedService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      const service = await getService('InventoryService', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/versioned/0.0.1', 'index.mdx'))).toBe(true);
+
+      expect(service).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+    });
+  });
+
+  describe('writeServiceToDomain', () => {
+    it('writes a service to the given domain. When no version if given for the domain the service is added to the latest domain', async () => {
+      await writeServiceToDomain(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'Shopping',
+        }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'index.mdx'))).toBe(true);
+    });
+
+    it('writes a service to the given domain (as md). When no version if given for the domain the service is added to the latest domain', async () => {
+      await writeServiceToDomain(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'Shopping',
+        },
+        { format: 'md' }
+      );
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'index.md'))).toBe(true);
+    });
+
+    it('writes a service to the given domain. When a version is given for the domain the service is added to that domain version', async () => {
+      await writeServiceToDomain(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles the inventory',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'Shopping',
+          version: '1.0.0',
+        }
+      );
+      expect(
+        fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/versioned/1.0.0/services/InventoryService', 'index.mdx'))
+      ).toBe(true);
+    });
+    it('writes a service to the given domain. When a version is the latest the service is added to the latest version of the domain', async () => {
+      await writeServiceToDomain(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles the inventory',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'Shopping',
+          version: 'latest',
+        }
+      );
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService/', 'index.mdx'))).toBe(true);
+    });
+
+    it('when override is true, it overrides the service if it already exists', async () => {
+      await writeServiceToDomain(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service tat handles the inventory',
+          markdown: '# Hello world',
+        },
+        {
+          id: 'Shopping',
+        }
+      );
+
+      await writeServiceToDomain(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'This is overridden content',
+          markdown: 'Overridden content',
+        },
+        {
+          id: 'Shopping',
+        },
+        { override: true }
+      );
+
+      const service = await getService('InventoryService', '0.0.1');
+
+      expect(service.markdown).toBe('Overridden content');
+      expect(service.summary).toBe('This is overridden content');
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'index.mdx'))).toBe(true);
+    });
+  });
+
+  describe('versionService', () => {
+    it('adds the given service to the versioned directory and removes itself from the root', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await versionService('InventoryService');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/versioned/0.0.1', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(false);
+    });
+    it('adds the given service to the versioned directory and all files that are associated to it', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      // Add random file in there
+      await fs.writeFileSync(path.join(CATALOG_PATH, 'services/InventoryService', 'schema.json'), 'SCHEMA!');
+
+      await versionService('InventoryService');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/versioned/0.0.1', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/versioned/0.0.1', 'schema.json'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(false);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'schema.json'))).toBe(false);
+    });
+
+    describe('when services are within a domain directory', () => {
+      it('versions a service within a domain correctly (cross-platform path handling)', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service that handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await versionService('InventoryService');
+
+        // Service should be versioned within the domain directory
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService/versioned/0.0.1', 'index.mdx'))
+        ).toBe(true);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'index.mdx'))).toBe(false);
+      });
+
+      it('versions a service within a domain and preserves associated files', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service that handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        // Add a file to the service
+        fs.writeFileSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'schema.json'), 'SCHEMA!');
+
+        await versionService('InventoryService');
+
+        // Both the index and schema should be versioned
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService/versioned/0.0.1', 'index.mdx'))
+        ).toBe(true);
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService/versioned/0.0.1', 'schema.json'))
+        ).toBe(true);
+        // Original files should be removed
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'index.mdx'))).toBe(false);
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'schema.json'))).toBe(false);
+      });
+    });
+  });
+
+  describe('rmService', () => {
+    it('removes a service from eventcatalog by the given path', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(true);
+
+      await rmService('/InventoryService');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(false);
+    });
+
+    it('removes all files with that service directory when the service is deleted', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      // add random file
+      fs.writeFileSync(path.join(CATALOG_PATH, 'services/InventoryService', 'schema.json'), 'dummy-data');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(true);
+
+      await rmService('/InventoryService');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(false);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'schema.json'))).toBe(false);
+    });
+  });
+
+  describe('rmServiceById', () => {
+    it('removes a service from eventcatalog by id', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(true);
+
+      await rmServiceById('InventoryService');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(false);
+    });
+
+    it('removes all files with that service directory when the service is deleted by id', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      // add random file
+      fs.writeFileSync(path.join(CATALOG_PATH, 'services/InventoryService', 'schema.json'), 'dummy-data');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(true);
+
+      await rmServiceById('InventoryService');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(false);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'schema.json'))).toBe(false);
+    });
+
+    it('removes a service from eventcatalog by id and version', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(true);
+
+      await rmServiceById('InventoryService', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(false);
+    });
+
+    it('if version is given, only removes that version and not any other versions of the service', async () => {
+      // write the first events
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await versionService('InventoryService');
+
+      // Write the versioned event
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Adjusted',
+        version: '0.0.2',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(true);
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/versioned/0.0.1', 'index.mdx'))).toBe(true);
+
+      await rmServiceById('InventoryService', '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.mdx'))).toBe(true);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryAdjusted/versioned/0.0.2', 'index.mdx'))).toBe(false);
+    });
+
+    describe('when services are within a domain directory', () => {
+      it('removes a service from eventcatalog by id', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'index.mdx'))).toBe(true);
+
+        await rmServiceById('InventoryService');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'index.mdx'))).toBe(false);
+      });
+
+      it('removes a service from eventcatalog by id and version', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'index.mdx'))).toBe(true);
+
+        await rmServiceById('InventoryService', '0.0.1');
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'index.mdx'))).toBe(false);
+      });
+    });
+  });
+
+  describe('addFileToService', () => {
+    it('takes a given file and writes it to the location of the given service', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addFileToService('InventoryService', file);
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'test.txt'))).toBe(true);
+    });
+
+    it('takes a given file and version and writes the file to the correct location', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await versionService('InventoryService');
+
+      await addFileToService('InventoryService', file, '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService/versioned/0.0.1', 'test.txt'))).toBe(true);
+    });
+
+    it('taskes a given file for the serivce with id using yaml block string ">-" and writes the file to correct location', async () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      await writeService({
+        id: 'AVeryLargeIdWhichForcesWriteServiceToAddABlockCharacterxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service tat handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addFileToService(
+        'AVeryLargeIdWhichForcesWriteServiceToAddABlockCharacterxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+        file,
+        '0.0.1'
+      );
+
+      expect(
+        fs.existsSync(
+          path.join(
+            CATALOG_PATH,
+            'services/AVeryLargeIdWhichForcesWriteServiceToAddABlockCharacterxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+            'test.txt'
+          )
+        )
+      ).toBe(true);
+    });
+
+    it('throws an error when trying to write to a service that does not exist', () => {
+      const file = { content: 'hello', fileName: 'test.txt' };
+
+      expect(addFileToService('InventoryService', file)).rejects.toThrowError('Cannot find directory to write file to');
+    });
+
+    describe('when services are within a domain directory', () => {
+      it('takes a given file and writes it to the location of the given service', async () => {
+        const file = { content: 'hello', fileName: 'test.txt' };
+
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await addFileToService('InventoryService', file);
+
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'test.txt'))).toBe(true);
+      });
+
+      it('takes a given file and version and writes the file to the correct location', async () => {
+        const file = { content: 'hello', fileName: 'test.txt' };
+
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service tat handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await versionService('InventoryService');
+
+        await addFileToService('InventoryService', file, '0.0.1');
+
+        expect(
+          fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService/versioned/0.0.1', 'test.txt'))
+        ).toBe(true);
+      });
+    });
+  });
+
+  describe('addEventToService', () => {
+    it('takes an existing event and adds it to the sends of an existing service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addEventToService('InventoryService', 'sends', { id: 'InventoryUpdatedEvent', version: '2.0.0' }, '0.0.1');
+
+      const service = await getService('InventoryService');
+
+      expect(service).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        sends: [
+          {
+            id: 'InventoryUpdatedEvent',
+            version: '2.0.0',
+          },
+        ],
+        markdown: '# Hello world',
+      });
+    });
+
+    it('takes an existing event and adds it to the receives of an existing service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addEventToService('InventoryService', 'receives', { id: 'InventoryUpdatedEvent', version: '2.0.0' }, '0.0.1');
+
+      const service = await getService('InventoryService');
+
+      expect(service).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        receives: [
+          {
+            id: 'InventoryUpdatedEvent',
+            version: '2.0.0',
+          },
+        ],
+        markdown: '# Hello world',
+      });
+    });
+
+    it('throws an error when trying to add an event to a service with an unsupported direction', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      expect(
+        addEventToService('InventoryService', 'doesnotexist', { id: 'InventoryUpdatedEvent', version: '2.0.0' }, '0.0.1')
+      ).rejects.toThrowError("Direction doesnotexist is invalid, only 'receives' and 'sends' are supported");
+    });
+
+    it('when an event is added to the service, the extension of the service is maintained', async () => {
+      await writeService(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles the inventory',
+          markdown: '# Hello world',
+        },
+        { format: 'md' }
+      );
+
+      await addEventToService('InventoryService', 'sends', { id: 'InventoryUpdatedEvent', version: '2.0.0' }, '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.md'))).toBe(true);
+    });
+
+    describe('when services are within a domain directory', () => {
+      it('takes an existing event and adds it to the sends of an existing service', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service that handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await addEventToService('InventoryService', 'sends', { id: 'InventoryUpdatedEvent', version: '2.0.0' }, '0.0.1');
+
+        const service = await getService('InventoryService');
+
+        expect(service).toEqual({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles the inventory',
+          sends: [
+            {
+              id: 'InventoryUpdatedEvent',
+              version: '2.0.0',
+            },
+          ],
+          markdown: '# Hello world',
+        });
+
+        //expect file where is was
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'index.mdx'))).toBe(true);
+      });
+
+      it('takes an existing event and adds it to the receives of an existing service', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service that handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await addEventToService('InventoryService', 'receives', { id: 'InventoryUpdatedEvent', version: '2.0.0' }, '0.0.1');
+
+        const service = await getService('InventoryService');
+
+        expect(service).toEqual({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles the inventory',
+          receives: [
+            {
+              id: 'InventoryUpdatedEvent',
+              version: '2.0.0',
+            },
+          ],
+          markdown: '# Hello world',
+        });
+      });
+    });
+  });
+
+  describe('fields support on sends and receives', () => {
+    it('persists fields when writing a service with sends that declare consumed fields', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+        sends: [{ id: 'InventoryAdjusted', version: '1.0.0', fields: ['productId', 'quantity', 'warehouseId'] }],
+      });
+
+      const service = await getService('InventoryService');
+
+      expect(service.sends).toEqual([
+        { id: 'InventoryAdjusted', version: '1.0.0', fields: ['productId', 'quantity', 'warehouseId'] },
+      ]);
+    });
+
+    it('persists fields when writing a service with receives that declare consumed fields', async () => {
+      await writeService({
+        id: 'ShippingService',
+        name: 'Shipping Service',
+        version: '0.0.1',
+        summary: 'Service that handles shipping',
+        markdown: '# Hello world',
+        receives: [{ id: 'PaymentProcessed', version: '1.0.0', fields: ['orderId', 'amount', 'currency'] }],
+      });
+
+      const service = await getService('ShippingService');
+
+      expect(service.receives).toEqual([{ id: 'PaymentProcessed', version: '1.0.0', fields: ['orderId', 'amount', 'currency'] }]);
+    });
+
+    it('includes fields when adding an event to a service sends', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addEventToService(
+        'InventoryService',
+        'sends',
+        { id: 'InventoryAdjusted', version: '1.0.0', fields: ['productId', 'quantity'] },
+        '0.0.1'
+      );
+
+      const service = await getService('InventoryService');
+
+      expect(service.sends).toEqual([{ id: 'InventoryAdjusted', version: '1.0.0', fields: ['productId', 'quantity'] }]);
+    });
+
+    it('includes fields when adding an event to a service receives', async () => {
+      await writeService({
+        id: 'NotificationService',
+        name: 'Notification Service',
+        version: '0.0.1',
+        summary: 'Service that handles notifications',
+        markdown: '# Hello world',
+      });
+
+      await addEventToService(
+        'NotificationService',
+        'receives',
+        { id: 'InvoiceGenerated', version: '1.0.0', fields: ['invoiceId', 'customerId', 'total'] },
+        '0.0.1'
+      );
+
+      const service = await getService('NotificationService');
+
+      expect(service.receives).toEqual([
+        { id: 'InvoiceGenerated', version: '1.0.0', fields: ['invoiceId', 'customerId', 'total'] },
+      ]);
+    });
+
+    it('preserves existing fields on sends when adding a new message', async () => {
+      await writeService({
+        id: 'BillingService',
+        name: 'Billing Service',
+        version: '0.0.1',
+        summary: 'Service that handles billing',
+        markdown: '# Hello world',
+        sends: [{ id: 'InvoiceGenerated', version: '1.0.0', fields: ['invoiceId', 'total'] }],
+      });
+
+      await addEventToService(
+        'BillingService',
+        'sends',
+        { id: 'SubscriptionPaymentDue', version: '1.0.0', fields: ['subscriptionId', 'amount'] },
+        '0.0.1'
+      );
+
+      const service = await getService('BillingService');
+
+      expect(service.sends).toEqual([
+        { id: 'InvoiceGenerated', version: '1.0.0', fields: ['invoiceId', 'total'] },
+        { id: 'SubscriptionPaymentDue', version: '1.0.0', fields: ['subscriptionId', 'amount'] },
+      ]);
+    });
+
+    it('does not include fields property when fields are not provided', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addEventToService('InventoryService', 'sends', { id: 'OutOfStock', version: '1.0.0' }, '0.0.1');
+
+      const service = await getService('InventoryService');
+
+      expect(service.sends).toEqual([{ id: 'OutOfStock', version: '1.0.0' }]);
+      expect(service.sends![0]).not.toHaveProperty('fields');
+    });
+
+    it('includes fields when adding a command to a service receives', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addCommandToService(
+        'InventoryService',
+        'receives',
+        { id: 'UpdateInventory', version: '1.0.0', fields: ['productId', 'quantityChange', 'warehouseId'] },
+        '0.0.1'
+      );
+
+      const service = await getService('InventoryService');
+
+      expect(service.receives).toEqual([
+        { id: 'UpdateInventory', version: '1.0.0', fields: ['productId', 'quantityChange', 'warehouseId'] },
+      ]);
+    });
+  });
+
+  describe('group support on sends and receives', () => {
+    it('persists group when writing a service with sends that declare a group', async () => {
+      await writeService({
+        id: 'WarehouseService',
+        name: 'Warehouse Service',
+        version: '0.0.1',
+        summary: 'Service that handles the warehouse',
+        markdown: '# Hello world',
+        sends: [{ id: 'ShipmentDispatched', version: '1.0.0', group: 'Shipping' }],
+      });
+
+      const service = await getService('WarehouseService');
+
+      expect(service.sends).toEqual([{ id: 'ShipmentDispatched', version: '1.0.0', group: 'Shipping' }]);
+    });
+
+    it('persists group when writing a service with receives that declare a group', async () => {
+      await writeService({
+        id: 'WarehouseService',
+        name: 'Warehouse Service',
+        version: '0.0.1',
+        summary: 'Service that handles the warehouse',
+        markdown: '# Hello world',
+        receives: [{ id: 'PickRequested', version: '1.0.0', group: 'Picking' }],
+      });
+
+      const service = await getService('WarehouseService');
+
+      expect(service.receives).toEqual([{ id: 'PickRequested', version: '1.0.0', group: 'Picking' }]);
+    });
+
+    it('includes group when adding an event to a service sends', async () => {
+      await writeService({
+        id: 'WarehouseService',
+        name: 'Warehouse Service',
+        version: '0.0.1',
+        summary: 'Service that handles the warehouse',
+        markdown: '# Hello world',
+      });
+
+      await addEventToService(
+        'WarehouseService',
+        'sends',
+        { id: 'ShipmentDispatched', version: '1.0.0', group: 'Shipping' },
+        '0.0.1'
+      );
+
+      const service = await getService('WarehouseService');
+
+      expect(service.sends).toEqual([{ id: 'ShipmentDispatched', version: '1.0.0', group: 'Shipping' }]);
+    });
+
+    it('includes group when adding an event to a service receives', async () => {
+      await writeService({
+        id: 'WarehouseService',
+        name: 'Warehouse Service',
+        version: '0.0.1',
+        summary: 'Service that handles the warehouse',
+        markdown: '# Hello world',
+      });
+
+      await addEventToService(
+        'WarehouseService',
+        'receives',
+        { id: 'PickRequested', version: '1.0.0', group: 'Picking' },
+        '0.0.1'
+      );
+
+      const service = await getService('WarehouseService');
+
+      expect(service.receives).toEqual([{ id: 'PickRequested', version: '1.0.0', group: 'Picking' }]);
+    });
+
+    it('preserves existing groups on sends when adding a new message', async () => {
+      await writeService({
+        id: 'WarehouseService',
+        name: 'Warehouse Service',
+        version: '0.0.1',
+        summary: 'Service that handles the warehouse',
+        markdown: '# Hello world',
+        sends: [{ id: 'ShipmentDispatched', version: '1.0.0', group: 'Shipping' }],
+      });
+
+      await addEventToService(
+        'WarehouseService',
+        'sends',
+        { id: 'ShipmentFailed', version: '1.0.0', group: 'Shipping' },
+        '0.0.1'
+      );
+
+      const service = await getService('WarehouseService');
+
+      expect(service.sends).toEqual([
+        { id: 'ShipmentDispatched', version: '1.0.0', group: 'Shipping' },
+        { id: 'ShipmentFailed', version: '1.0.0', group: 'Shipping' },
+      ]);
+    });
+
+    it('does not include group property when group is not provided', async () => {
+      await writeService({
+        id: 'WarehouseService',
+        name: 'Warehouse Service',
+        version: '0.0.1',
+        summary: 'Service that handles the warehouse',
+        markdown: '# Hello world',
+      });
+
+      await addEventToService('WarehouseService', 'sends', { id: 'ShipmentDispatched', version: '1.0.0' }, '0.0.1');
+
+      const service = await getService('WarehouseService');
+
+      expect(service.sends).toEqual([{ id: 'ShipmentDispatched', version: '1.0.0' }]);
+      expect(service.sends![0]).not.toHaveProperty('group');
+    });
+
+    it('supports group alongside fields on the same pointer', async () => {
+      await writeService({
+        id: 'WarehouseService',
+        name: 'Warehouse Service',
+        version: '0.0.1',
+        summary: 'Service that handles the warehouse',
+        markdown: '# Hello world',
+        sends: [{ id: 'ShipmentDispatched', version: '1.0.0', group: 'Shipping', fields: ['trackingId', 'destination'] }],
+      });
+
+      const service = await getService('WarehouseService');
+
+      expect(service.sends).toEqual([
+        { id: 'ShipmentDispatched', version: '1.0.0', group: 'Shipping', fields: ['trackingId', 'destination'] },
+      ]);
+    });
+  });
+
+  describe('addCommandToService', () => {
+    it('takes an existing command and adds it to the sends of an existing service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addCommandToService('InventoryService', 'sends', { id: 'UpdateInventory', version: '2.0.0' }, '0.0.1');
+
+      const service = await getService('InventoryService');
+
+      expect(service).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        sends: [
+          {
+            id: 'UpdateInventory',
+            version: '2.0.0',
+          },
+        ],
+        markdown: '# Hello world',
+      });
+    });
+
+    it('takes an existing command and adds it to the receives of an existing service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addCommandToService('InventoryService', 'receives', { id: 'UpdateInventory', version: '2.0.0' }, '0.0.1');
+
+      const service = await getService('InventoryService');
+
+      expect(service).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        receives: [
+          {
+            id: 'UpdateInventory',
+            version: '2.0.0',
+          },
+        ],
+        markdown: '# Hello world',
+      });
+    });
+
+    describe('when services are within a domain directory', () => {
+      it('takes an existing command and adds it to the sends of an existing service', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service that handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await addCommandToService('InventoryService', 'sends', { id: 'UpdateInventory', version: '2.0.0' }, '0.0.1');
+
+        const service = await getService('InventoryService');
+
+        expect(service).toEqual({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles the inventory',
+          sends: [
+            {
+              id: 'UpdateInventory',
+              version: '2.0.0',
+            },
+          ],
+          markdown: '# Hello world',
+        });
+      });
+
+      it('takes an existing command and adds it to the receives of an existing service', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service that handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await addCommandToService('InventoryService', 'receives', { id: 'UpdateInventory', version: '2.0.0' }, '0.0.1');
+
+        const service = await getService('InventoryService');
+
+        expect(service).toEqual({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles the inventory',
+          receives: [
+            {
+              id: 'UpdateInventory',
+              version: '2.0.0',
+            },
+          ],
+          markdown: '# Hello world',
+        });
+      });
+    });
+
+    it('throws an error when trying to add an event to a service with an unsupported direction', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      expect(
+        addCommandToService('InventoryService', 'doesnotexist', { id: 'InventoryUpdatedEvent', version: '2.0.0' }, '0.0.1')
+      ).rejects.toThrowError("Direction doesnotexist is invalid, only 'receives' and 'sends' are supported");
+    });
+  });
+
+  describe('addMessageToService does not remove sibling resources', () => {
+    it('when a command is added to a service via addCommandToService, an event previously written to the service with writeEventToService is not deleted', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      // Write an event to the service using SDK (no version → goes to events/ directly)
+      await writeEventToService(
+        {
+          id: 'InventoryUpdatedEvent',
+          name: 'Inventory Updated',
+          version: '1.0.0',
+          summary: 'Event when inventory is updated',
+          markdown: '# Inventory Updated Event',
+        },
+        { id: 'InventoryService' }
+      );
+
+      // Add the event to the service sends
+      await addEventToService('InventoryService', 'sends', { id: 'InventoryUpdatedEvent', version: '1.0.0' }, '0.0.1');
+
+      // Verify event exists before the command is added
+      const eventBefore = await getEvent('InventoryUpdatedEvent', '1.0.0');
+      expect(eventBefore).toBeDefined();
+
+      // Now add a command to the same service
+      await addCommandToService('InventoryService', 'receives', { id: 'UpdateInventory', version: '2.0.0' }, '0.0.1');
+
+      // The event should still be retrievable after addCommandToService
+      const eventAfter = await getEvent('InventoryUpdatedEvent', '1.0.0');
+      expect(eventAfter).toBeDefined();
+      expect(eventAfter.id).toBe('InventoryUpdatedEvent');
+      expect(eventAfter.version).toBe('1.0.0');
+
+      // The event file should still exist on disk
+      expect(
+        fs.existsSync(path.join(CATALOG_PATH, 'services', 'InventoryService', 'events', 'InventoryUpdatedEvent', 'index.mdx'))
+      ).toBe(true);
+
+      // The service frontmatter should reference both
+      const service = await getService('InventoryService');
+      expect(service.sends).toEqual([{ id: 'InventoryUpdatedEvent', version: '1.0.0' }]);
+      expect(service.receives).toEqual([{ id: 'UpdateInventory', version: '2.0.0' }]);
+    });
+
+    it('when an event is added to a service via addEventToService, a command previously written to the service with writeCommandToService is not deleted', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      // Write a command to the service using SDK (no version → goes to commands/ directly)
+      await writeCommandToService(
+        {
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '2.0.0',
+          summary: 'Command to update inventory',
+          markdown: '# Update Inventory Command',
+        },
+        { id: 'InventoryService' }
+      );
+
+      // Add the command to the service receives
+      await addCommandToService('InventoryService', 'receives', { id: 'UpdateInventory', version: '2.0.0' }, '0.0.1');
+
+      // Verify command exists before the event is added
+      const commandBefore = await getCommand('UpdateInventory', '2.0.0');
+      expect(commandBefore).toBeDefined();
+
+      // Now add an event to the same service
+      await addEventToService('InventoryService', 'sends', { id: 'InventoryUpdatedEvent', version: '1.0.0' }, '0.0.1');
+
+      // The command should still be retrievable after addEventToService
+      const commandAfter = await getCommand('UpdateInventory', '2.0.0');
+      expect(commandAfter).toBeDefined();
+      expect(commandAfter.id).toBe('UpdateInventory');
+      expect(commandAfter.version).toBe('2.0.0');
+
+      // The command file should still exist on disk
+      expect(
+        fs.existsSync(path.join(CATALOG_PATH, 'services', 'InventoryService', 'commands', 'UpdateInventory', 'index.mdx'))
+      ).toBe(true);
+
+      // The service frontmatter should reference both
+      const service = await getService('InventoryService');
+      expect(service.receives).toEqual([{ id: 'UpdateInventory', version: '2.0.0' }]);
+      expect(service.sends).toEqual([{ id: 'InventoryUpdatedEvent', version: '1.0.0' }]);
+    });
+
+    it('when a command is added to a service, both an event and command previously written to the service survive', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      // Write an event to the service (no version → events/ directly)
+      await writeEventToService(
+        {
+          id: 'InventoryUpdatedEvent',
+          name: 'Inventory Updated',
+          version: '1.0.0',
+          summary: 'Event when inventory is updated',
+          markdown: '# Inventory Updated Event',
+        },
+        { id: 'InventoryService' }
+      );
+      await addEventToService('InventoryService', 'sends', { id: 'InventoryUpdatedEvent', version: '1.0.0' }, '0.0.1');
+
+      // Write a command to the service (no version → commands/ directly)
+      await writeCommandToService(
+        {
+          id: 'UpdateInventory',
+          name: 'Update Inventory',
+          version: '2.0.0',
+          summary: 'Command to update inventory',
+          markdown: '# Update Inventory Command',
+        },
+        { id: 'InventoryService' }
+      );
+      await addCommandToService('InventoryService', 'receives', { id: 'UpdateInventory', version: '2.0.0' }, '0.0.1');
+
+      // Now add a second command — this should not destroy the event or first command
+      await addCommandToService('InventoryService', 'sends', { id: 'NotifyWarehouse', version: '1.0.0' }, '0.0.1');
+
+      // Event file must still exist
+      expect(
+        fs.existsSync(path.join(CATALOG_PATH, 'services', 'InventoryService', 'events', 'InventoryUpdatedEvent', 'index.mdx'))
+      ).toBe(true);
+      const eventStillExists = await getEvent('InventoryUpdatedEvent', '1.0.0');
+      expect(eventStillExists).toBeDefined();
+
+      // Command file must still exist
+      expect(
+        fs.existsSync(path.join(CATALOG_PATH, 'services', 'InventoryService', 'commands', 'UpdateInventory', 'index.mdx'))
+      ).toBe(true);
+      const commandStillExists = await getCommand('UpdateInventory', '2.0.0');
+      expect(commandStillExists).toBeDefined();
+
+      // Service should reference all messages
+      const service = await getService('InventoryService');
+      expect(service.sends).toEqual([
+        { id: 'InventoryUpdatedEvent', version: '1.0.0' },
+        { id: 'NotifyWarehouse', version: '1.0.0' },
+      ]);
+      expect(service.receives).toEqual([{ id: 'UpdateInventory', version: '2.0.0' }]);
+    });
+  });
+  describe('addQueryToService', () => {
+    it('takes an existing query and adds it to the sends of an existing service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addQueryToService('InventoryService', 'sends', { id: 'GetInventory', version: '2.0.0' }, '0.0.1');
+
+      const service = await getService('InventoryService');
+
+      expect(service).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        sends: [
+          {
+            id: 'GetInventory',
+            version: '2.0.0',
+          },
+        ],
+        markdown: '# Hello world',
+      });
+    });
+
+    it('takes an existing query and adds it to the receives of an existing service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addQueryToService('InventoryService', 'receives', { id: 'GetInventory', version: '2.0.0' }, '0.0.1');
+
+      const service = await getService('InventoryService');
+
+      expect(service).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        receives: [
+          {
+            id: 'GetInventory',
+            version: '2.0.0',
+          },
+        ],
+        markdown: '# Hello world',
+      });
+    });
+
+    describe('when services are within a domain directory', () => {
+      it('takes an existing query and adds it to the sends of an existing service', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service that handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await addQueryToService('InventoryService', 'sends', { id: 'GetInventory', version: '2.0.0' }, '0.0.1');
+
+        const service = await getService('InventoryService');
+
+        expect(service).toEqual({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles the inventory',
+          sends: [
+            {
+              id: 'GetInventory',
+              version: '2.0.0',
+            },
+          ],
+          markdown: '# Hello world',
+        });
+      });
+
+      it('takes an existing query and adds it to the receives of an existing service', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service that handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await addQueryToService('InventoryService', 'receives', { id: 'GetInventory', version: '2.0.0' }, '0.0.1');
+
+        const service = await getService('InventoryService');
+
+        expect(service).toEqual({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles the inventory',
+          receives: [
+            {
+              id: 'GetInventory',
+              version: '2.0.0',
+            },
+          ],
+          markdown: '# Hello world',
+        });
+      });
+    });
+
+    it('throws an error when trying to add an event to a service with an unsupported direction', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      expect(
+        addQueryToService('InventoryService', 'doesnotexist', { id: 'GetInventory', version: '2.0.0' }, '0.0.1')
+      ).rejects.toThrowError("Direction doesnotexist is invalid, only 'receives' and 'sends' are supported");
+    });
+  });
+
+  describe('addEntityToService', () => {
+    it('takes an existing entity and adds it to an existing service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addEntityToService('InventoryService', { id: 'User', version: '1.0.0' }, '0.0.1');
+
+      const service = await getService('InventoryService');
+
+      expect(service).toEqual({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        entities: [
+          {
+            id: 'User',
+            version: '1.0.0',
+          },
+        ],
+        markdown: '# Hello world',
+      });
+    });
+
+    it('adds multiple entities to a service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addEntityToService('InventoryService', { id: 'User', version: '1.0.0' }, '0.0.1');
+      await addEntityToService('InventoryService', { id: 'Product', version: '2.0.0' }, '0.0.1');
+
+      const service = await getService('InventoryService');
+
+      expect(service.entities).toEqual([
+        {
+          id: 'User',
+          version: '1.0.0',
+        },
+        {
+          id: 'Product',
+          version: '2.0.0',
+        },
+      ]);
+    });
+
+    it('does not add duplicate entities to a service', async () => {
+      await writeService({
+        id: 'InventoryService2',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await addEntityToService('InventoryService2', { id: 'User', version: '1.0.0' }, '0.0.1');
+      await addEntityToService('InventoryService2', { id: 'User', version: '1.0.0' }, '0.0.1');
+
+      const service = await getService('InventoryService2');
+
+      expect(service.entities).toEqual([
+        {
+          id: 'User',
+          version: '1.0.0',
+        },
+      ]);
+    });
+
+    it('maintains the extension of the service when adding an entity', async () => {
+      await writeService(
+        {
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles the inventory',
+          markdown: '# Hello world',
+        },
+        { format: 'md' }
+      );
+
+      await addEntityToService('InventoryService', { id: 'User', version: '1.0.0' }, '0.0.1');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'services/InventoryService', 'index.md'))).toBe(true);
+    });
+
+    describe('when services are within a domain directory', () => {
+      it('adds an entity to a service within a domain and maintains location', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'InventoryService',
+            name: 'Inventory Service',
+            version: '0.0.1',
+            summary: 'Service that handles the inventory',
+            markdown: '# Hello world',
+          },
+          { id: 'Shopping' }
+        );
+
+        await addEntityToService('InventoryService', { id: 'User', version: '1.0.0' }, '0.0.1');
+        // Ensure file remains in the domain directory
+        expect(fs.existsSync(path.join(CATALOG_PATH, 'domains/Shopping/services/InventoryService', 'index.mdx'))).toBe(true);
+      });
+    });
+  });
+
+  describe('serviceHasVersion', () => {
+    it('returns true when a given service and version exists in the catalog', async () => {
+      await writeService({
+        id: 'AccountService',
+        name: 'Accounts Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await serviceHasVersion('AccountService', '0.0.1')).toEqual(true);
+    });
+
+    it('returns true when a semver version is given and the version exists in the catalog', async () => {
+      await writeService({
+        id: 'AccountService',
+        name: 'Accounts Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await serviceHasVersion('AccountService', '0.0.x')).toEqual(true);
+    });
+
+    it('returns true when a `latest` version is given and the version exists in the catalog', async () => {
+      await writeService({
+        id: 'AccountService',
+        name: 'Accounts Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await serviceHasVersion('AccountService', 'latest')).toEqual(true);
+    });
+
+    it('returns false when service does not exist in the catalog', async () => {
+      await writeService({
+        id: 'AccountService',
+        name: 'Accounts Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      expect(await serviceHasVersion('AccountService', '5.0.0')).toEqual(false);
+    });
+  });
+
+  describe('getSpecificationFilesForService', () => {
+    it('returns the specification files for a service', async () => {
+      await writeService({
+        id: 'AccountService',
+        name: 'Accounts Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        specifications: {
+          asyncapiPath: 'spec.yaml',
+          graphqlPath: 'spec.graphql',
+        },
+      });
+
+      await addFileToService('AccountService', { content: 'fake-async-api-file', fileName: 'spec.yaml' }, '0.0.1');
+      await addFileToService('AccountService', { content: 'fake-graphql-file', fileName: 'spec.graphql' }, '0.0.1');
+
+      const specFiles = await getSpecificationFilesForService('AccountService', '0.0.1');
+
+      expect(specFiles).toEqual([
+        {
+          content: 'fake-async-api-file',
+          fileName: 'spec.yaml',
+          path: expect.stringContaining(path.join('services', 'AccountService', 'spec.yaml')),
+          key: 'asyncapiPath',
+        },
+        {
+          content: 'fake-graphql-file',
+          fileName: 'spec.graphql',
+          path: expect.stringContaining(path.join('services', 'AccountService', 'spec.graphql')),
+          key: 'graphqlPath',
+        },
+      ]);
+    });
+
+    it('returns the specification files for a service (if specifications is an array)', async () => {
+      await writeService({
+        id: 'AccountService',
+        name: 'Accounts Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        specifications: [
+          {
+            type: 'asyncapi',
+            path: 'spec.yaml',
+          },
+          {
+            type: 'graphql',
+            path: 'spec.graphql',
+          },
+        ],
+      });
+
+      await addFileToService('AccountService', { content: 'fake-async-api-file', fileName: 'spec.yaml' }, '0.0.1');
+      await addFileToService('AccountService', { content: 'fake-graphql-file', fileName: 'spec.graphql' }, '0.0.1');
+
+      const specFiles = await getSpecificationFilesForService('AccountService', '0.0.1');
+
+      expect(specFiles).toEqual([
+        {
+          content: 'fake-async-api-file',
+          fileName: 'spec.yaml',
+          path: expect.stringContaining(path.join('services', 'AccountService', 'spec.yaml')),
+          key: 'asyncapi',
+        },
+        {
+          content: 'fake-graphql-file',
+          fileName: 'spec.graphql',
+          path: expect.stringContaining(path.join('services', 'AccountService', 'spec.graphql')),
+          key: 'graphql',
+        },
+      ]);
+    });
+
+    it('returns the specification files for a versioned service', async () => {
+      await writeService({
+        id: 'AccountService',
+        name: 'Accounts Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        specifications: {
+          asyncapiPath: 'spec.yaml',
+        },
+      });
+
+      await addFileToService('AccountService', { content: 'fake-async-api-file', fileName: 'spec.yaml' }, '0.0.1');
+
+      await versionService('AccountService');
+
+      const specFiles = await getSpecificationFilesForService('AccountService', '0.0.1');
+
+      expect(specFiles).toEqual([
+        {
+          content: 'fake-async-api-file',
+          fileName: 'spec.yaml',
+          path: expect.stringContaining(path.join('services', 'AccountService', 'versioned', '0.0.1', 'spec.yaml')),
+          key: 'asyncapiPath',
+        },
+      ]);
+    });
+
+    it('throw an error if the specifications have been defined in the service but nothing can be found on disk', async () => {
+      await writeService({
+        id: 'AccountService',
+        name: 'Accounts Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+        specifications: {
+          asyncapiPath: 'spec.yaml',
+        },
+      });
+
+      await expect(getSpecificationFilesForService('AccountService', '0.0.1')).rejects.toThrowError(
+        'File spec.yaml does not exist in resource AccountService v(0.0.1)'
+      );
+    });
+    it('returns an empty array of no specifications for a service have been defined', async () => {
+      await writeService({
+        id: 'AccountService',
+        name: 'Accounts Service',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      const specFiles = await getSpecificationFilesForService('AccountService', '0.0.1');
+
+      expect(specFiles).toEqual([]);
+    });
+
+    describe('when services are within a domain directory', () => {
+      it('returns the specification files for a service', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'AccountService',
+            name: 'Accounts Service',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+            specifications: {
+              asyncapiPath: 'spec.yaml',
+            },
+          },
+          { id: 'Shopping' }
+        );
+
+        await addFileToService('AccountService', { content: 'fake-async-api-file', fileName: 'spec.yaml' }, '0.0.1');
+
+        const specFiles = await getSpecificationFilesForService('AccountService', '0.0.1');
+
+        expect(specFiles).toEqual([
+          {
+            content: 'fake-async-api-file',
+            fileName: 'spec.yaml',
+            path: expect.stringContaining(path.join('services', 'AccountService', 'spec.yaml')),
+            key: 'asyncapiPath',
+          },
+        ]);
+      });
+
+      it('returns the specification files for a versioned service', async () => {
+        await writeServiceToDomain(
+          {
+            id: 'AccountService',
+            name: 'Accounts Service',
+            version: '0.0.1',
+            summary: 'This is a summary',
+            markdown: '# Hello world',
+            specifications: {
+              asyncapiPath: 'spec.yaml',
+            },
+          },
+          { id: 'Shopping' }
+        );
+
+        await addFileToService('AccountService', { content: 'fake-async-api-file', fileName: 'spec.yaml' }, '0.0.1');
+
+        await versionService('AccountService');
+
+        const specFiles = await getSpecificationFilesForService('AccountService', '0.0.1');
+
+        expect(specFiles).toEqual([
+          {
+            content: 'fake-async-api-file',
+            fileName: 'spec.yaml',
+            path: expect.stringContaining(path.join('services', 'AccountService', 'versioned', '0.0.1', 'spec.yaml')),
+            key: 'asyncapiPath',
+          },
+        ]);
+      });
+    });
+  });
+
+  describe('addMessageToService (addEventToService)', () => {
+    it('adds the given message to the service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addEventToService('InventoryService', 'sends', { id: 'InventoryAdjusted', version: '0.0.1' }, '0.0.1');
+
+      const service = await getService('InventoryService');
+
+      expect(service.sends).toEqual([
+        {
+          id: 'InventoryAdjusted',
+          version: '0.0.1',
+        },
+      ]);
+    });
+
+    it('the folder location of the service does not change when adding a message to the service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeEvent({
+        id: 'InventoryAdjusted',
+        name: 'Inventory Adjusted',
+        version: '0.0.1',
+        summary: 'This is a summary',
+        markdown: '# Hello world',
+      });
+
+      await addEventToService('InventoryService', 'sends', { id: 'InventoryAdjusted', version: '0.0.1' }, '0.0.1');
+
+      const pathToService = path.join(CATALOG_PATH, 'services', 'InventoryService');
+      expect(fs.existsSync(pathToService)).toEqual(true);
+    });
+  });
+
+  describe('addDataStoreToService (addDataStoreToService)', () => {
+    it('adds the given data store to the service (writesTo)', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      await addDataStoreToService('InventoryService', 'writesTo', { id: 'orders-db', version: '0.0.1' }, '0.0.1');
+
+      const service = await getService('InventoryService');
+
+      expect(service.writesTo).toEqual([
+        {
+          id: 'orders-db',
+          version: '0.0.1',
+        },
+      ]);
+    });
+
+    it('adds the given data store to the service (readsFrom)', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      await addDataStoreToService('InventoryService', 'readsFrom', { id: 'orders-db', version: '0.0.1' }, '0.0.1');
+
+      const service = await getService('InventoryService');
+
+      expect(service.readsFrom).toEqual([
+        {
+          id: 'orders-db',
+          version: '0.0.1',
+        },
+      ]);
+    });
+
+    it('the folder location of the service does not change when adding a data store to the service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      await writeDataStore({
+        id: 'orders-db',
+        name: 'Orders Database',
+        version: '0.0.1',
+        markdown: '# Orders',
+        container_type: 'database',
+      });
+
+      await addDataStoreToService('InventoryService', 'writesTo', { id: 'orders-db', version: '0.0.1' }, '0.0.1');
+
+      const pathToService = path.join(CATALOG_PATH, 'services', 'InventoryService');
+      expect(fs.existsSync(pathToService)).toEqual(true);
+    });
+  });
+
+  describe('isService', () => {
+    it('returns true if the path is a service', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      expect(await isService(path.join(CATALOG_PATH, 'services', 'InventoryService', 'index.mdx'))).toEqual(true);
+    });
+
+    it('returns false if the path is not a service', async () => {
+      expect(await isService('/services/InventoryService/index.mdx')).toEqual(false);
+    });
+  });
+
+  describe('toService', () => {
+    it('converts a file to a service', async () => {
+      // First we create a service for the test
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: '# Hello world',
+      });
+
+      // Get the path to the service
+      const pathToService = path.join(CATALOG_PATH, 'services', 'InventoryService', 'index.mdx');
+
+      // Convert the file to a service
+      const service = await toService(fs.readFileSync(pathToService, 'utf8'));
+
+      // Assert the service is correct
+      expect(service).toEqual(
+        expect.objectContaining({
+          id: 'InventoryService',
+          name: 'Inventory Service',
+          version: '0.0.1',
+          summary: 'Service that handles the inventory',
+          markdown: '# Hello world',
+        })
+      );
+    });
+  });
+});
diff --git a/packages/sdk/src/test/snapshots.test.ts b/packages/sdk/src/test/snapshots.test.ts
new file mode 100644
index 000000000..93d2611f3
--- /dev/null
+++ b/packages/sdk/src/test/snapshots.test.ts
@@ -0,0 +1,578 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-snapshots');
+
+const {
+  writeService,
+  writeEvent,
+  writeCommand,
+  writeQuery,
+  versionEvent,
+  addSchemaToEvent,
+  createSnapshot,
+  diffSnapshots,
+  listSnapshots,
+} = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Snapshots SDK', () => {
+  describe('createSnapshot', () => {
+    it('creates a snapshot file containing all catalog resources', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '# OrderCreated' });
+      await writeService({
+        id: 'OrdersService',
+        name: 'Orders Service',
+        version: '1.0.0',
+        markdown: '',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      });
+
+      const result = await createSnapshot({ outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      expect(result.filePath).toContain('.snapshot.json');
+      expect(result.snapshot.snapshotVersion).toBe('1.0.0');
+      expect(result.snapshot.resources.services).toHaveLength(1);
+      expect(result.snapshot.resources.services[0].id).toBe('OrdersService');
+      expect(result.snapshot.resources.messages.events).toHaveLength(1);
+      expect(result.snapshot.resources.messages.events[0].id).toBe('OrderCreated');
+    });
+
+    it('only includes core fields (id, version, name, sends, receives, deprecated)', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        summary: 'Some summary',
+        markdown: '# Some markdown content',
+      });
+
+      const result = await createSnapshot({ outputDir: path.join(CATALOG_PATH, '.snapshots') });
+      const event = result.snapshot.resources.messages.events[0];
+
+      expect(event.id).toBe('OrderCreated');
+      expect(event.version).toBe('1.0.0');
+      expect(event.name).toBe('Order Created');
+      expect(event.markdown).toBeUndefined();
+      expect(event.summary).toBeUndefined();
+    });
+
+    it('creates a snapshot with a custom label', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+      const result = await createSnapshot({ label: 'pre-release', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      expect(result.snapshot.label).toBe('pre-release');
+      expect(result.filePath).toContain('pre-release');
+    });
+
+    it('when an event has a schemaPath and schema file, createSnapshot includes a schemaHash for that event', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        schemaPath: 'schema.json',
+        markdown: '',
+      });
+      await addSchemaToEvent('OrderCreated', {
+        schema: JSON.stringify({ type: 'object', properties: { orderId: { type: 'string' } } }),
+        fileName: 'schema.json',
+      });
+
+      const result = await createSnapshot({ outputDir: path.join(CATALOG_PATH, '.snapshots') });
+      const event = result.snapshot.resources.messages.events[0];
+
+      expect(event.schemaHash).toBeDefined();
+      expect(typeof event.schemaHash).toBe('string');
+      expect(event.schemaHash.length).toBe(64); // SHA-256 hex digest
+    });
+
+    it('when an event has no schemaPath, createSnapshot does not include a schemaHash for that event', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+      const result = await createSnapshot({ outputDir: path.join(CATALOG_PATH, '.snapshots') });
+      const event = result.snapshot.resources.messages.events[0];
+
+      expect(event.schemaHash).toBeUndefined();
+    });
+
+    it('when schema file content changes, createSnapshot produces a different schemaHash', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        schemaPath: 'schema.json',
+        markdown: '',
+      });
+      await addSchemaToEvent('OrderCreated', {
+        schema: JSON.stringify({ type: 'object', properties: { orderId: { type: 'string' } } }),
+        fileName: 'schema.json',
+      });
+
+      const result1 = await createSnapshot({ label: 'snap1', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+      const hash1 = result1.snapshot.resources.messages.events[0].schemaHash;
+
+      // Change the schema content
+      await addSchemaToEvent('OrderCreated', {
+        schema: JSON.stringify({ type: 'object', properties: { orderId: { type: 'string' }, amount: { type: 'number' } } }),
+        fileName: 'schema.json',
+      });
+
+      const result2 = await createSnapshot({ label: 'snap2', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+      const hash2 = result2.snapshot.resources.messages.events[0].schemaHash;
+
+      expect(hash1).not.toBe(hash2);
+    });
+
+    it('when commands and queries have schema files, createSnapshot includes schemaHash values for them too', async () => {
+      await writeCommand({
+        id: 'ProcessPayment',
+        name: 'Process Payment',
+        version: '1.0.0',
+        schemaPath: 'schema.json',
+        markdown: '',
+      });
+      // Write schema file directly for the command
+      const commandSchemaPath = path.join(CATALOG_PATH, 'commands', 'ProcessPayment', 'schema.json');
+      fs.writeFileSync(commandSchemaPath, JSON.stringify({ type: 'object' }));
+
+      await writeQuery({
+        id: 'GetOrder',
+        name: 'Get Order',
+        version: '1.0.0',
+        schemaPath: 'schema.json',
+        markdown: '',
+      });
+      const querySchemaPath = path.join(CATALOG_PATH, 'queries', 'GetOrder', 'schema.json');
+      fs.writeFileSync(querySchemaPath, JSON.stringify({ type: 'object', properties: { id: { type: 'string' } } }));
+
+      const result = await createSnapshot({ outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const command = result.snapshot.resources.messages.commands[0];
+      const query = result.snapshot.resources.messages.queries[0];
+
+      expect(command.schemaHash).toBeDefined();
+      expect(command.schemaHash.length).toBe(64);
+      expect(query.schemaHash).toBeDefined();
+      expect(query.schemaHash.length).toBe(64);
+    });
+
+    it('writes the snapshot file to disk', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+      const result = await createSnapshot({ outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      expect(fs.existsSync(result.filePath)).toBe(true);
+      const fileContent = JSON.parse(fs.readFileSync(result.filePath, 'utf-8'));
+      expect(fileContent.snapshotVersion).toBe('1.0.0');
+    });
+  });
+
+  describe('diffSnapshots', () => {
+    it('detects when a new consumer is added to an event', async () => {
+      // Snapshot A: OrdersService sends OrderCreated, no consumers
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrdersService',
+        name: 'Orders Service',
+        version: '1.0.0',
+        markdown: '',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      });
+
+      const snapshotA = await createSnapshot({ label: 'before', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      // Add a consumer: PaymentService now receives OrderCreated
+      await writeService({
+        id: 'PaymentService',
+        name: 'Payment Service',
+        version: '1.0.0',
+        markdown: '',
+        receives: [{ id: 'OrderCreated', version: '1.0.0' }],
+      });
+
+      const snapshotB = await createSnapshot({ label: 'after', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const diff = await diffSnapshots(snapshotA.filePath, snapshotB.filePath);
+
+      // PaymentService was added as a new resource
+      const addedService = diff.resources.find((r) => r.resourceId === 'PaymentService');
+      expect(addedService).toBeDefined();
+      expect(addedService!.changeType).toBe('added');
+
+      // A new relationship: PaymentService receives OrderCreated
+      const addedRelationship = diff.relationships.find(
+        (r) => r.serviceId === 'PaymentService' && r.resourceId === 'OrderCreated'
+      );
+      expect(addedRelationship).toBeDefined();
+      expect(addedRelationship!.changeType).toBe('added');
+      expect(addedRelationship!.direction).toBe('receives');
+    });
+
+    it('detects when a resource is removed', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeEvent({ id: 'LegacyEvent', name: 'Legacy Event', version: '0.9.0', markdown: '' });
+
+      const snapshotA = await createSnapshot({ label: 'before', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      // Remove LegacyEvent
+      fs.rmSync(path.join(CATALOG_PATH, 'events', 'LegacyEvent'), { recursive: true, force: true });
+
+      const snapshotB = await createSnapshot({ label: 'after', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const diff = await diffSnapshots(snapshotA.filePath, snapshotB.filePath);
+
+      const removed = diff.resources.find((r) => r.resourceId === 'LegacyEvent');
+      expect(removed).toBeDefined();
+      expect(removed!.changeType).toBe('removed');
+      expect(diff.summary.resourcesRemoved).toBe(1);
+    });
+
+    it('detects when a resource is modified (e.g. name changed)', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        markdown: '',
+      });
+
+      const snapshotA = await createSnapshot({ label: 'before', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      // Modify the event name
+      await writeEvent(
+        {
+          id: 'OrderCreated',
+          name: 'Order Created Event',
+          version: '1.0.0',
+          markdown: '',
+        },
+        { override: true }
+      );
+
+      const snapshotB = await createSnapshot({ label: 'after', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const diff = await diffSnapshots(snapshotA.filePath, snapshotB.filePath);
+
+      const modified = diff.resources.find((r) => r.resourceId === 'OrderCreated');
+      expect(modified).toBeDefined();
+      expect(modified!.changeType).toBe('modified');
+      expect(modified!.changedFields).toContain('name');
+      expect(diff.summary.resourcesModified).toBe(1);
+    });
+
+    it('detects when a resource is versioned (same id, different version)', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+      const snapshotA = await createSnapshot({ label: 'before', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      // Version bump: version the existing event, then write new version
+      await versionEvent('OrderCreated');
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '2.0.0', markdown: '' });
+
+      const snapshotB = await createSnapshot({ label: 'after', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const diff = await diffSnapshots(snapshotA.filePath, snapshotB.filePath);
+
+      const versioned = diff.resources.find((r) => r.resourceId === 'OrderCreated' && r.changeType === 'versioned');
+      expect(versioned).toBeDefined();
+      expect(versioned!.previousVersion).toBe('1.0.0');
+      expect(versioned!.newVersion).toBe('2.0.0');
+      expect(diff.summary.resourcesVersioned).toBe(1);
+    });
+
+    it('returns zero changes when comparing identical snapshots', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrdersService',
+        name: 'Orders Service',
+        version: '1.0.0',
+        markdown: '',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      });
+
+      const snapshotA = await createSnapshot({ label: 'snapshot-a', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+      const snapshotB = await createSnapshot({ label: 'snapshot-b', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const diff = await diffSnapshots(snapshotA.filePath, snapshotB.filePath);
+
+      expect(diff.summary.totalChanges).toBe(0);
+      expect(diff.resources).toHaveLength(0);
+      expect(diff.relationships).toHaveLength(0);
+    });
+
+    it('detects when a service adds a new sends relationship', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeEvent({ id: 'OrderUpdated', name: 'Order Updated', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrdersService',
+        name: 'Orders Service',
+        version: '1.0.0',
+        markdown: '',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      });
+
+      const snapshotA = await createSnapshot({ label: 'before', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      // OrdersService now also sends OrderUpdated
+      await writeService(
+        {
+          id: 'OrdersService',
+          name: 'Orders Service',
+          version: '1.0.0',
+          markdown: '',
+          sends: [
+            { id: 'OrderCreated', version: '1.0.0' },
+            { id: 'OrderUpdated', version: '1.0.0' },
+          ],
+        },
+        { override: true }
+      );
+
+      const snapshotB = await createSnapshot({ label: 'after', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const diff = await diffSnapshots(snapshotA.filePath, snapshotB.filePath);
+
+      const addedRel = diff.relationships.find(
+        (r) => r.serviceId === 'OrdersService' && r.resourceId === 'OrderUpdated' && r.direction === 'sends'
+      );
+      expect(addedRel).toBeDefined();
+      expect(addedRel!.changeType).toBe('added');
+      expect(diff.summary.relationshipsAdded).toBe(1);
+    });
+
+    it('does not emit false relationship changes when a service version is bumped without changing relationships', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrdersService',
+        name: 'Orders Service',
+        version: '1.0.0',
+        markdown: '',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      });
+
+      const snapshotA = await createSnapshot({ label: 'before', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      // Bump service version without changing relationships
+      await writeService(
+        {
+          id: 'OrdersService',
+          name: 'Orders Service',
+          version: '2.0.0',
+          markdown: '',
+          sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        },
+        { override: true }
+      );
+
+      const snapshotB = await createSnapshot({ label: 'after', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const diff = await diffSnapshots(snapshotA.filePath, snapshotB.filePath);
+
+      // Service was versioned, but no relationship changes
+      expect(diff.relationships).toHaveLength(0);
+      expect(diff.summary.relationshipsAdded).toBe(0);
+      expect(diff.summary.relationshipsRemoved).toBe(0);
+    });
+
+    it('detects relationship changes when a service version bump also adds new relationships', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeEvent({ id: 'OrderUpdated', name: 'Order Updated', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrdersService',
+        name: 'Orders Service',
+        version: '1.0.0',
+        markdown: '',
+        sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+      });
+
+      const snapshotA = await createSnapshot({ label: 'before', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      // Bump version AND add a new sends relationship
+      await writeService(
+        {
+          id: 'OrdersService',
+          name: 'Orders Service',
+          version: '2.0.0',
+          markdown: '',
+          sends: [
+            { id: 'OrderCreated', version: '1.0.0' },
+            { id: 'OrderUpdated', version: '1.0.0' },
+          ],
+        },
+        { override: true }
+      );
+
+      const snapshotB = await createSnapshot({ label: 'after', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const diff = await diffSnapshots(snapshotA.filePath, snapshotB.filePath);
+
+      // Only the new relationship should appear, not the existing one
+      expect(diff.relationships).toHaveLength(1);
+      const addedRel = diff.relationships[0];
+      expect(addedRel.serviceId).toBe('OrdersService');
+      expect(addedRel.resourceId).toBe('OrderUpdated');
+      expect(addedRel.direction).toBe('sends');
+      expect(addedRel.changeType).toBe('added');
+    });
+
+    it('detects relationship changes when a service version bump also removes relationships', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeEvent({ id: 'OrderUpdated', name: 'Order Updated', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'OrdersService',
+        name: 'Orders Service',
+        version: '1.0.0',
+        markdown: '',
+        sends: [
+          { id: 'OrderCreated', version: '1.0.0' },
+          { id: 'OrderUpdated', version: '1.0.0' },
+        ],
+      });
+
+      const snapshotA = await createSnapshot({ label: 'before', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      // Bump version AND remove OrderUpdated
+      await writeService(
+        {
+          id: 'OrdersService',
+          name: 'Orders Service',
+          version: '2.0.0',
+          markdown: '',
+          sends: [{ id: 'OrderCreated', version: '1.0.0' }],
+        },
+        { override: true }
+      );
+
+      const snapshotB = await createSnapshot({ label: 'after', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const diff = await diffSnapshots(snapshotA.filePath, snapshotB.filePath);
+
+      // Only the removed relationship should appear
+      expect(diff.relationships).toHaveLength(1);
+      const removedRel = diff.relationships[0];
+      expect(removedRel.serviceId).toBe('OrdersService');
+      expect(removedRel.resourceId).toBe('OrderUpdated');
+      expect(removedRel.direction).toBe('sends');
+      expect(removedRel.changeType).toBe('removed');
+    });
+
+    it('when a message schema file changes between snapshots, diffSnapshots reports schemaHash as a changed field', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        schemaPath: 'schema.json',
+        markdown: '',
+      });
+      await addSchemaToEvent('OrderCreated', {
+        schema: JSON.stringify({ type: 'object', properties: { orderId: { type: 'string' } } }),
+        fileName: 'schema.json',
+      });
+
+      const snapshotA = await createSnapshot({ label: 'before', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      // Change the schema content
+      await addSchemaToEvent('OrderCreated', {
+        schema: JSON.stringify({ type: 'object', properties: { orderId: { type: 'string' }, amount: { type: 'number' } } }),
+        fileName: 'schema.json',
+      });
+
+      const snapshotB = await createSnapshot({ label: 'after', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const diff = await diffSnapshots(snapshotA.filePath, snapshotB.filePath);
+
+      const modified = diff.resources.find((r) => r.resourceId === 'OrderCreated');
+      expect(modified).toBeDefined();
+      expect(modified!.changeType).toBe('modified');
+      expect(modified!.changedFields).toContain('schemaHash');
+    });
+
+    it('when schema content is identical between snapshots, diffSnapshots does not report a schema change', async () => {
+      await writeEvent({
+        id: 'OrderCreated',
+        name: 'Order Created',
+        version: '1.0.0',
+        schemaPath: 'schema.json',
+        markdown: '',
+      });
+      await addSchemaToEvent('OrderCreated', {
+        schema: JSON.stringify({ type: 'object', properties: { orderId: { type: 'string' } } }),
+        fileName: 'schema.json',
+      });
+
+      const snapshotA = await createSnapshot({ label: 'before', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+      const snapshotB = await createSnapshot({ label: 'after', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const diff = await diffSnapshots(snapshotA.filePath, snapshotB.filePath);
+
+      expect(diff.summary.totalChanges).toBe(0);
+      expect(diff.resources).toHaveLength(0);
+    });
+
+    it('detects when a service removes a receives relationship', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+      await writeEvent({ id: 'PaymentProcessed', name: 'Payment Processed', version: '1.0.0', markdown: '' });
+      await writeService({
+        id: 'PaymentService',
+        name: 'Payment Service',
+        version: '1.0.0',
+        markdown: '',
+        receives: [
+          { id: 'OrderCreated', version: '1.0.0' },
+          { id: 'PaymentProcessed', version: '1.0.0' },
+        ],
+      });
+
+      const snapshotA = await createSnapshot({ label: 'before', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      // PaymentService no longer receives PaymentProcessed
+      await writeService(
+        {
+          id: 'PaymentService',
+          name: 'Payment Service',
+          version: '1.0.0',
+          markdown: '',
+          receives: [{ id: 'OrderCreated', version: '1.0.0' }],
+        },
+        { override: true }
+      );
+
+      const snapshotB = await createSnapshot({ label: 'after', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const diff = await diffSnapshots(snapshotA.filePath, snapshotB.filePath);
+
+      const removedRel = diff.relationships.find(
+        (r) => r.serviceId === 'PaymentService' && r.resourceId === 'PaymentProcessed' && r.direction === 'receives'
+      );
+      expect(removedRel).toBeDefined();
+      expect(removedRel!.changeType).toBe('removed');
+      expect(diff.summary.relationshipsRemoved).toBe(1);
+    });
+  });
+
+  describe('listSnapshots', () => {
+    it('returns metadata for all snapshots in the .snapshots directory', async () => {
+      await writeEvent({ id: 'OrderCreated', name: 'Order Created', version: '1.0.0', markdown: '' });
+
+      await createSnapshot({ label: 'v1', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+      await createSnapshot({ label: 'v2', outputDir: path.join(CATALOG_PATH, '.snapshots') });
+
+      const snapshots = await listSnapshots();
+
+      expect(snapshots).toHaveLength(2);
+      expect(snapshots.map((s) => s.label)).toContain('v1');
+      expect(snapshots.map((s) => s.label)).toContain('v2');
+    });
+  });
+});
diff --git a/packages/sdk/src/test/systems.test.ts b/packages/sdk/src/test/systems.test.ts
new file mode 100644
index 000000000..1dd372629
--- /dev/null
+++ b/packages/sdk/src/test/systems.test.ts
@@ -0,0 +1,443 @@
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-systems');
+
+const {
+  writeDomain,
+  getDomain,
+  writeSystem,
+  writeSystemToDomain,
+  getSystem,
+  getSystemByPath,
+  getSystems,
+  versionSystem,
+  rmSystem,
+  rmSystemById,
+  addFileToSystem,
+  addServiceToSystem,
+  addFlowToSystem,
+  addEntityToSystem,
+  addContainerToSystem,
+  addSystemToDomain,
+  writeServiceToSystem,
+  writeFlowToSystem,
+  writeEntityToSystem,
+  writeDataStoreToSystem,
+  getService,
+  getFlow,
+  getEntity,
+  getDataStore,
+  systemHasVersion,
+  isSystem,
+  toSystem,
+  dumpCatalog,
+} = utils(CATALOG_PATH);
+
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Systems SDK', () => {
+  describe('getSystem', () => {
+    it('returns the given system id from EventCatalog and the latest version when no version is given', async () => {
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        summary: 'Orchestrates payment processing',
+        scope: 'internal',
+        markdown: '# Payment Processing System',
+        services: [{ id: 'payment-api', version: '1.0.0' }],
+        containers: [{ id: 'payment-db', version: '1.0.0' }],
+        relationships: [{ id: 'stripe', version: '1.0.0', label: 'requests charges from' }],
+        actors: [{ id: 'buyer', name: 'Buyer', label: 'starts checkout' }],
+      });
+
+      const system = await getSystem('payment-processing-system');
+
+      expect(system).toEqual({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        summary: 'Orchestrates payment processing',
+        scope: 'internal',
+        markdown: '# Payment Processing System',
+        services: [{ id: 'payment-api', version: '1.0.0' }],
+        containers: [{ id: 'payment-db', version: '1.0.0' }],
+        relationships: [{ id: 'stripe', version: '1.0.0', label: 'requests charges from' }],
+        actors: [{ id: 'buyer', name: 'Buyer', label: 'starts checkout' }],
+      });
+    });
+
+    it('returns the requested system version when a version is given', async () => {
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# v1',
+      });
+
+      await versionSystem('payment-processing-system');
+
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '2.0.0',
+        markdown: '# v2',
+      });
+
+      const system = await getSystem('payment-processing-system', '1.0.0');
+
+      expect(system).toEqual({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# v1',
+      });
+    });
+
+    it('returns undefined when the system is not found', async () => {
+      await expect(await getSystem('missing-system')).toEqual(undefined);
+    });
+  });
+
+  describe('getSystemByPath', () => {
+    it('returns the given system from EventCatalog by its path', async () => {
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# Payment Processing System',
+      });
+
+      const system = await getSystemByPath(path.join(CATALOG_PATH, 'systems/payment-processing-system/index.mdx'));
+
+      expect(system).toEqual({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# Payment Processing System',
+      });
+    });
+  });
+
+  describe('getSystems', () => {
+    it('returns all systems and ignores nested resources inside systems', async () => {
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# Payment Processing System',
+      });
+
+      await writeServiceToSystem(
+        {
+          id: 'payment-api',
+          name: 'Payment API',
+          version: '1.0.0',
+          markdown: '# Payment API',
+        },
+        { id: 'payment-processing-system' }
+      );
+
+      const systems = await getSystems();
+
+      expect(systems).toEqual([
+        {
+          id: 'payment-processing-system',
+          name: 'Payment Processing System',
+          version: '1.0.0',
+          markdown: '# Payment Processing System',
+        },
+      ]);
+    });
+
+    it('returns only latest systems when latestOnly is true', async () => {
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# v1',
+      });
+
+      await versionSystem('payment-processing-system');
+
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '2.0.0',
+        markdown: '# v2',
+      });
+
+      const systems = await getSystems({ latestOnly: true });
+
+      expect(systems).toEqual([
+        {
+          id: 'payment-processing-system',
+          name: 'Payment Processing System',
+          version: '2.0.0',
+          markdown: '# v2',
+        },
+      ]);
+    });
+  });
+
+  describe('writeSystemToDomain', () => {
+    it('writes the given system to a domain and can add the system to the domain frontmatter', async () => {
+      await writeDomain({
+        id: 'payments',
+        name: 'Payments',
+        version: '1.0.0',
+        markdown: '# Payments',
+      });
+
+      await writeSystemToDomain(
+        {
+          id: 'payment-processing-system',
+          name: 'Payment Processing System',
+          version: '1.0.0',
+          markdown: '# Payment Processing System',
+        },
+        { id: 'payments' }
+      );
+
+      await addSystemToDomain('payments', { id: 'payment-processing-system', version: '1.0.0' });
+
+      const systemPath = path.join(CATALOG_PATH, 'domains/payments/systems/payment-processing-system/index.mdx');
+      const system = await getSystem('payment-processing-system');
+      const domain = await getDomain('payments');
+
+      expect(fs.existsSync(systemPath)).toBe(true);
+      expect(system).toEqual({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# Payment Processing System',
+      });
+      expect(domain.systems).toEqual([{ id: 'payment-processing-system', version: '1.0.0' }]);
+    });
+  });
+
+  describe('system resources', () => {
+    it('writes resources inside a system and adds them to the system frontmatter', async () => {
+      await writeDomain({
+        id: 'payments',
+        name: 'Payments',
+        version: '1.0.0',
+        markdown: '# Payments',
+      });
+
+      await writeSystemToDomain(
+        {
+          id: 'payment-processing-system',
+          name: 'Payment Processing System',
+          version: '1.0.0',
+          markdown: '# Payment Processing System',
+        },
+        { id: 'payments' }
+      );
+
+      await writeServiceToSystem(
+        {
+          id: 'payment-api',
+          name: 'Payment API',
+          version: '1.0.0',
+          markdown: '# Payment API',
+        },
+        { id: 'payment-processing-system' }
+      );
+      await writeFlowToSystem(
+        {
+          id: 'payment-flow',
+          name: 'Payment Flow',
+          version: '1.0.0',
+          steps: [],
+          markdown: '# Payment Flow',
+        },
+        { id: 'payment-processing-system' }
+      );
+      await writeEntityToSystem(
+        {
+          id: 'payment',
+          name: 'Payment',
+          version: '1.0.0',
+          markdown: '# Payment',
+        },
+        { id: 'payment-processing-system' }
+      );
+      await writeDataStoreToSystem(
+        {
+          id: 'payment-db',
+          name: 'Payment DB',
+          version: '1.0.0',
+          container_type: 'database',
+          markdown: '# Payment DB',
+        },
+        { id: 'payment-processing-system' }
+      );
+
+      await addServiceToSystem('payment-processing-system', { id: 'payment-api', version: '1.0.0' });
+      await addServiceToSystem('payment-processing-system', { id: 'payment-api', version: '1.0.0' });
+      await addFlowToSystem('payment-processing-system', { id: 'payment-flow', version: '1.0.0' });
+      await addEntityToSystem('payment-processing-system', { id: 'payment', version: '1.0.0' });
+      await addContainerToSystem('payment-processing-system', { id: 'payment-db', version: '1.0.0' });
+
+      const system = await getSystem('payment-processing-system');
+
+      expect(await getService('payment-api')).toEqual({
+        id: 'payment-api',
+        name: 'Payment API',
+        version: '1.0.0',
+        markdown: '# Payment API',
+      });
+      expect(await getFlow('payment-flow')).toEqual({
+        id: 'payment-flow',
+        name: 'Payment Flow',
+        version: '1.0.0',
+        steps: [],
+        markdown: '# Payment Flow',
+      });
+      expect(await getEntity('payment')).toEqual({
+        id: 'payment',
+        name: 'Payment',
+        version: '1.0.0',
+        markdown: '# Payment',
+      });
+      expect(await getDataStore('payment-db')).toEqual({
+        id: 'payment-db',
+        name: 'Payment DB',
+        version: '1.0.0',
+        container_type: 'database',
+        markdown: '# Payment DB',
+      });
+      expect(system.services).toEqual([{ id: 'payment-api', version: '1.0.0' }]);
+      expect(system.flows).toEqual([{ id: 'payment-flow', version: '1.0.0' }]);
+      expect(system.entities).toEqual([{ id: 'payment', version: '1.0.0' }]);
+      expect(system.containers).toEqual([{ id: 'payment-db', version: '1.0.0' }]);
+    });
+  });
+
+  describe('addFileToSystem', () => {
+    it('adds a file to the given system', async () => {
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# Payment Processing System',
+      });
+
+      await addFileToSystem('payment-processing-system', { content: '{"enabled":true}', fileName: 'metadata.json' });
+
+      expect(fs.readFileSync(path.join(CATALOG_PATH, 'systems/payment-processing-system/metadata.json'), 'utf-8')).toBe(
+        '{\n  "enabled": true\n}'
+      );
+    });
+  });
+
+  describe('rmSystem', () => {
+    it('removes a system by path', async () => {
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# Payment Processing System',
+      });
+
+      await rmSystem('/payment-processing-system');
+
+      expect(await getSystem('payment-processing-system')).toEqual(undefined);
+    });
+  });
+
+  describe('rmSystemById', () => {
+    it('removes a system by id', async () => {
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# Payment Processing System',
+      });
+
+      await rmSystemById('payment-processing-system');
+
+      expect(await getSystem('payment-processing-system')).toEqual(undefined);
+    });
+  });
+
+  describe('systemHasVersion', () => {
+    it('returns true when the system version exists', async () => {
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# Payment Processing System',
+      });
+
+      expect(await systemHasVersion('payment-processing-system', '1.0.0')).toBe(true);
+      expect(await systemHasVersion('payment-processing-system', '2.0.0')).toBe(false);
+    });
+  });
+
+  describe('isSystem', () => {
+    it('returns true when the path is a system', async () => {
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# Payment Processing System',
+      });
+
+      expect(await isSystem(path.join(CATALOG_PATH, 'systems/payment-processing-system/index.mdx'))).toBe(true);
+    });
+  });
+
+  describe('toSystem', () => {
+    it('converts raw file contents to a system', async () => {
+      const system = await toSystem(`---
+id: payment-processing-system
+name: Payment Processing System
+version: 1.0.0
+---
+
+# Payment Processing System
+`);
+
+      expect(system).toEqual({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# Payment Processing System',
+      });
+    });
+  });
+
+  describe('dumpCatalog', () => {
+    it('includes systems in the catalog dump', async () => {
+      await writeSystem({
+        id: 'payment-processing-system',
+        name: 'Payment Processing System',
+        version: '1.0.0',
+        markdown: '# Payment Processing System',
+      });
+
+      const dump = await dumpCatalog();
+
+      expect(dump.resources.systems).toEqual([
+        expect.objectContaining({
+          id: 'payment-processing-system',
+          name: 'Payment Processing System',
+          version: '1.0.0',
+          markdown: '# Payment Processing System',
+        }),
+      ]);
+    });
+  });
+});
diff --git a/packages/sdk/src/test/teams.test.ts b/packages/sdk/src/test/teams.test.ts
new file mode 100644
index 000000000..a1b1f9cbc
--- /dev/null
+++ b/packages/sdk/src/test/teams.test.ts
@@ -0,0 +1,383 @@
+// teams.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-teams');
+
+const { writeTeam, getTeam, getTeams, rmTeamById, writeService, getOwnersForResource, writeUser } = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Teams SDK', () => {
+  describe('getTeam', () => {
+    it('returns the given team by id from EventCatalog,', async () => {
+      await writeTeam({
+        id: 'eventcatalog-core-team',
+        name: 'Eventcatalog Core Team',
+        markdown: 'This is the core team for Eventcatalog',
+      });
+
+      const test = await getTeam('eventcatalog-core-team');
+
+      expect(test).toEqual({
+        id: 'eventcatalog-core-team',
+        name: 'Eventcatalog Core Team',
+        markdown: 'This is the core team for Eventcatalog',
+      });
+    });
+
+    it('returns undefined when the team is not found', async () => {
+      await expect(await getTeam('unknown-team')).toEqual(undefined);
+    });
+
+    it('returns a team from the EventCatalog directory store when no local file exists', async () => {
+      fs.mkdirSync(path.join(CATALOG_PATH, '.eventcatalog', 'store'), { recursive: true });
+      fs.writeFileSync(
+        path.join(CATALOG_PATH, '.eventcatalog', 'store', 'directory.json'),
+        JSON.stringify({
+          version: '1',
+          generatedAt: '2026-05-27T00:00:00.000Z',
+          resources: {
+            users: [],
+            teams: [
+              {
+                id: 'core-maintainers',
+                name: 'Core Maintainers',
+                members: ['github-user'],
+                markdown: 'This team is synced from GitHub',
+                readOnly: true,
+                source: {
+                  provider: 'github',
+                  id: 'github-team-id',
+                  url: 'https://github.com/orgs/event-catalog/teams/core-maintainers',
+                },
+              },
+            ],
+          },
+        })
+      );
+
+      const team = await getTeam('core-maintainers');
+
+      expect(team).toEqual({
+        id: 'core-maintainers',
+        name: 'Core Maintainers',
+        members: ['github-user'],
+        markdown: 'This team is synced from GitHub',
+        readOnly: true,
+        source: {
+          provider: 'github',
+          id: 'github-team-id',
+          url: 'https://github.com/orgs/event-catalog/teams/core-maintainers',
+        },
+      });
+    });
+  });
+
+  describe('getTeams', () => {
+    it('returns all the teams in the catalog,', async () => {
+      await writeTeam({
+        id: 'eventcatalog-core-team',
+        name: 'Eventcatalog Core Team',
+        markdown: 'This is the core team for Eventcatalog',
+      });
+
+      await writeTeam({
+        id: 'eventcatalog-second-team',
+        name: 'Eventcatalog Second Team',
+        markdown: 'This is the second team for Eventcatalog',
+      });
+
+      const teams = await getTeams();
+
+      expect(teams).toEqual([
+        {
+          id: 'eventcatalog-second-team',
+          name: 'Eventcatalog Second Team',
+          markdown: 'This is the second team for Eventcatalog',
+        },
+        {
+          id: 'eventcatalog-core-team',
+          name: 'Eventcatalog Core Team',
+          markdown: 'This is the core team for Eventcatalog',
+        },
+      ]);
+    });
+
+    it('merges teams from the EventCatalog directory store after local teams', async () => {
+      await writeTeam({
+        id: 'local-team',
+        name: 'Local Team',
+        markdown: 'This is a local team',
+      });
+
+      fs.mkdirSync(path.join(CATALOG_PATH, '.eventcatalog', 'store'), { recursive: true });
+      fs.writeFileSync(
+        path.join(CATALOG_PATH, '.eventcatalog', 'store', 'directory.json'),
+        JSON.stringify({
+          version: '1',
+          generatedAt: '2026-05-27T00:00:00.000Z',
+          resources: {
+            users: [],
+            teams: [
+              {
+                id: 'local-team',
+                name: 'Directory Local Team',
+                markdown: 'This duplicate should be ignored',
+                readOnly: true,
+                source: {
+                  provider: 'github',
+                },
+              },
+              {
+                id: 'core-maintainers',
+                name: 'Core Maintainers',
+                markdown: 'This team is synced from GitHub',
+                readOnly: true,
+                source: {
+                  provider: 'github',
+                  id: 'github-team-id',
+                  url: 'https://github.com/orgs/event-catalog/teams/core-maintainers',
+                },
+              },
+            ],
+          },
+        })
+      );
+
+      const teams = await getTeams();
+
+      expect(teams).toEqual([
+        {
+          id: 'local-team',
+          name: 'Local Team',
+          markdown: 'This is a local team',
+        },
+        {
+          id: 'core-maintainers',
+          name: 'Core Maintainers',
+          markdown: 'This team is synced from GitHub',
+          readOnly: true,
+          source: {
+            provider: 'github',
+            id: 'github-team-id',
+            url: 'https://github.com/orgs/event-catalog/teams/core-maintainers',
+          },
+        },
+      ]);
+    });
+  });
+
+  describe('writeTeam', () => {
+    it('writes the given team to EventCatalog and assumes the path if one if not given', async () => {
+      await writeTeam({
+        id: 'eventcatalog-core-team',
+        name: 'Eventcatalog Core Team',
+        markdown: 'This is the core team for Eventcatalog',
+      });
+
+      const team = await getTeam('eventcatalog-core-team');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'teams', 'eventcatalog-core-team.mdx'))).toBe(true);
+
+      expect(team).toEqual({
+        id: 'eventcatalog-core-team',
+        name: 'Eventcatalog Core Team',
+        markdown: 'This is the core team for Eventcatalog',
+      });
+    });
+
+    it('throws an error when trying to write a team that already exists', async () => {
+      await writeTeam({
+        id: 'eventcatalog-core-team',
+        name: 'Eventcatalog Core Team',
+        markdown: 'This is the core team for Eventcatalog',
+      });
+
+      await expect(
+        writeTeam({
+          id: 'eventcatalog-core-team',
+          name: 'Eventcatalog Core Team',
+          markdown: 'This is the core team for Eventcatalog',
+        })
+      ).rejects.toThrowError('Failed to write eventcatalog-core-team (team) as it already exists');
+    });
+
+    it('overrides the team when trying to write an team that already exists and override is true', async () => {
+      await writeTeam({
+        id: 'eventcatalog-core-team',
+        name: 'Eventcatalog Core Team',
+        markdown: 'This is the core team for Eventcatalog',
+      });
+
+      await writeTeam(
+        {
+          id: 'eventcatalog-core-team',
+          name: 'Eventcatalog Core Team Overridden',
+          markdown: 'This is the core team for Eventcatalog',
+        },
+        { override: true }
+      );
+
+      const team = await getTeam('eventcatalog-core-team');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'teams', 'eventcatalog-core-team.mdx'))).toBe(true);
+      expect(team?.name).toBe('Eventcatalog Core Team Overridden');
+    });
+  });
+
+  describe('rmTeamById', () => {
+    it('removes a team from eventcatalog by id', async () => {
+      await writeTeam({
+        id: 'eventcatalog-core-team',
+        name: 'Eventcatalog Core Team',
+        markdown: 'This is the core team for Eventcatalog',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'teams', 'eventcatalog-core-team.mdx'))).toBe(true);
+
+      await rmTeamById('eventcatalog-core-team');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'teams', 'eventcatalog-core-team.mdx'))).toBe(false);
+    });
+  });
+
+  describe('getOwnersForResource', () => {
+    it('returns the owners for a given resource', async () => {
+      await writeTeam({
+        id: 'eventcatalog-core-team',
+        name: 'Eventcatalog Core Team',
+        markdown: 'This is the core team for Eventcatalog',
+      });
+
+      await writeUser({
+        id: 'eventcatalog-core-user',
+        name: 'Eventcatalog Core User',
+        avatarUrl: 'https://example.com/avatar.png',
+        markdown: 'This is the core user for Eventcatalog',
+      });
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: 'This is the inventory service',
+        owners: ['eventcatalog-core-team', 'eventcatalog-core-user'],
+      });
+
+      const owners = await getOwnersForResource('InventoryService');
+
+      expect(owners).toEqual([
+        {
+          id: 'eventcatalog-core-team',
+          name: 'Eventcatalog Core Team',
+          markdown: 'This is the core team for Eventcatalog',
+        },
+        {
+          id: 'eventcatalog-core-user',
+          name: 'Eventcatalog Core User',
+          avatarUrl: 'https://example.com/avatar.png',
+          markdown: 'This is the core user for Eventcatalog',
+        },
+      ]);
+    });
+
+    it('returns an empty array if the resource has no owners', async () => {
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: 'This is the inventory service',
+      });
+
+      const owners = await getOwnersForResource('InventoryService');
+
+      expect(owners).toEqual([]);
+    });
+
+    it('resolves owners from the EventCatalog directory store', async () => {
+      fs.mkdirSync(path.join(CATALOG_PATH, '.eventcatalog', 'store'), { recursive: true });
+      fs.writeFileSync(
+        path.join(CATALOG_PATH, '.eventcatalog', 'store', 'directory.json'),
+        JSON.stringify({
+          version: '1',
+          generatedAt: '2026-05-27T00:00:00.000Z',
+          resources: {
+            users: [
+              {
+                id: 'github-user',
+                name: 'github-user',
+                avatarUrl: 'https://example.com/avatar.png',
+                markdown: 'This user is synced from GitHub',
+                readOnly: true,
+                source: {
+                  provider: 'github',
+                  url: 'https://github.com/github-user',
+                },
+              },
+            ],
+            teams: [
+              {
+                id: 'core-maintainers',
+                name: 'Core Maintainers',
+                markdown: 'This team is synced from GitHub',
+                readOnly: true,
+                source: {
+                  provider: 'github',
+                  url: 'https://github.com/orgs/event-catalog/teams/core-maintainers',
+                },
+              },
+            ],
+          },
+        })
+      );
+
+      await writeService({
+        id: 'InventoryService',
+        name: 'Inventory Service',
+        version: '0.0.1',
+        summary: 'Service that handles the inventory',
+        markdown: 'This is the inventory service',
+        owners: ['core-maintainers', 'github-user'],
+      });
+
+      const owners = await getOwnersForResource('InventoryService');
+
+      expect(owners).toEqual([
+        {
+          id: 'core-maintainers',
+          name: 'Core Maintainers',
+          markdown: 'This team is synced from GitHub',
+          readOnly: true,
+          source: {
+            provider: 'github',
+            url: 'https://github.com/orgs/event-catalog/teams/core-maintainers',
+          },
+        },
+        {
+          id: 'github-user',
+          name: 'github-user',
+          avatarUrl: 'https://example.com/avatar.png',
+          markdown: 'This user is synced from GitHub',
+          readOnly: true,
+          source: {
+            provider: 'github',
+            url: 'https://github.com/github-user',
+          },
+        },
+      ]);
+    });
+  });
+});
diff --git a/packages/sdk/src/test/users.test.ts b/packages/sdk/src/test/users.test.ts
new file mode 100644
index 000000000..2ff97bdd3
--- /dev/null
+++ b/packages/sdk/src/test/users.test.ts
@@ -0,0 +1,288 @@
+// users.test.js
+import { expect, it, describe, beforeEach, afterEach } from 'vitest';
+import utils from '../index';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const CATALOG_PATH = path.join(__dirname, 'catalog-users');
+
+const { writeUser, getUser, getUsers, rmUserById } = utils(CATALOG_PATH);
+
+// clean the catalog before each test
+beforeEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+  fs.mkdirSync(CATALOG_PATH, { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(CATALOG_PATH, { recursive: true, force: true });
+});
+
+describe('Users SDK', () => {
+  describe('getUser', () => {
+    it('returns the given user by id from EventCatalog,', async () => {
+      await writeUser({
+        id: 'eventcatalog-core-user',
+        name: 'Eventcatalog Core user',
+        markdown: 'This is the core user for Eventcatalog',
+        avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+      });
+
+      const test = await getUser('eventcatalog-core-user');
+
+      expect(test).toEqual({
+        id: 'eventcatalog-core-user',
+        name: 'Eventcatalog Core user',
+        markdown: 'This is the core user for Eventcatalog',
+        avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+      });
+    });
+
+    it('returns undefined when the user is not found', async () => {
+      await expect(await getUser('unknown-user')).toEqual(undefined);
+    });
+
+    it('returns a user from the EventCatalog directory store when no local file exists', async () => {
+      fs.mkdirSync(path.join(CATALOG_PATH, '.eventcatalog', 'store'), { recursive: true });
+      fs.writeFileSync(
+        path.join(CATALOG_PATH, '.eventcatalog', 'store', 'directory.json'),
+        JSON.stringify({
+          version: '1',
+          generatedAt: '2026-05-27T00:00:00.000Z',
+          resources: {
+            users: [
+              {
+                id: 'github-user',
+                name: 'github-user',
+                avatarUrl: 'https://example.com/avatar.png',
+                markdown: 'This user is synced from GitHub',
+                readOnly: true,
+                source: {
+                  provider: 'github',
+                  id: 'github-user-id',
+                  url: 'https://github.com/github-user',
+                },
+              },
+            ],
+            teams: [],
+          },
+        })
+      );
+
+      const user = await getUser('github-user');
+
+      expect(user).toEqual({
+        id: 'github-user',
+        name: 'github-user',
+        avatarUrl: 'https://example.com/avatar.png',
+        markdown: 'This user is synced from GitHub',
+        readOnly: true,
+        source: {
+          provider: 'github',
+          id: 'github-user-id',
+          url: 'https://github.com/github-user',
+        },
+      });
+    });
+  });
+
+  describe('getUsers', () => {
+    it('returns all the users in the catalog,', async () => {
+      await writeUser({
+        id: 'eventcatalog-core-user',
+        name: 'Eventcatalog Core User',
+        markdown: 'This is the core user for Eventcatalog',
+        avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+      });
+
+      await writeUser({
+        id: 'eventcatalog-second-user',
+        name: 'Eventcatalog Second User',
+        markdown: 'This is the second user for Eventcatalog',
+        avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+      });
+
+      const users = await getUsers();
+
+      expect(users).toEqual([
+        {
+          id: 'eventcatalog-second-user',
+          name: 'Eventcatalog Second User',
+          markdown: 'This is the second user for Eventcatalog',
+          avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+        },
+        {
+          id: 'eventcatalog-core-user',
+          name: 'Eventcatalog Core User',
+          markdown: 'This is the core user for Eventcatalog',
+          avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+        },
+      ]);
+    });
+
+    it('merges users from the EventCatalog directory store after local users', async () => {
+      await writeUser({
+        id: 'local-user',
+        name: 'Local User',
+        markdown: 'This is a local user',
+        avatarUrl: 'https://example.com/local.png',
+      });
+
+      fs.mkdirSync(path.join(CATALOG_PATH, '.eventcatalog', 'store'), { recursive: true });
+      fs.writeFileSync(
+        path.join(CATALOG_PATH, '.eventcatalog', 'store', 'directory.json'),
+        JSON.stringify({
+          version: '1',
+          generatedAt: '2026-05-27T00:00:00.000Z',
+          resources: {
+            users: [
+              {
+                id: 'local-user',
+                name: 'Directory Local User',
+                avatarUrl: 'https://example.com/directory-local.png',
+                markdown: 'This duplicate should be ignored',
+                readOnly: true,
+                source: {
+                  provider: 'github',
+                },
+              },
+              {
+                id: 'github-user',
+                name: 'github-user',
+                avatarUrl: 'https://example.com/avatar.png',
+                markdown: 'This user is synced from GitHub',
+                readOnly: true,
+                source: {
+                  provider: 'github',
+                  id: 'github-user-id',
+                  url: 'https://github.com/github-user',
+                },
+              },
+            ],
+            teams: [],
+          },
+        })
+      );
+
+      const users = await getUsers();
+
+      expect(users).toEqual([
+        {
+          id: 'local-user',
+          name: 'Local User',
+          markdown: 'This is a local user',
+          avatarUrl: 'https://example.com/local.png',
+        },
+        {
+          id: 'github-user',
+          name: 'github-user',
+          avatarUrl: 'https://example.com/avatar.png',
+          markdown: 'This user is synced from GitHub',
+          readOnly: true,
+          source: {
+            provider: 'github',
+            id: 'github-user-id',
+            url: 'https://github.com/github-user',
+          },
+        },
+      ]);
+    });
+  });
+
+  describe('writeUser', () => {
+    it('writes a user without an avatarUrl', async () => {
+      await writeUser({
+        id: 'eventcatalog-core-user',
+        name: 'Eventcatalog Core User',
+        markdown: 'This is the core user for Eventcatalog',
+      });
+
+      const user = await getUser('eventcatalog-core-user');
+
+      expect(user).toEqual({
+        id: 'eventcatalog-core-user',
+        name: 'Eventcatalog Core User',
+        markdown: 'This is the core user for Eventcatalog',
+      });
+    });
+
+    it('writes the given user to EventCatalog and assumes the path if one if not given', async () => {
+      await writeUser({
+        id: 'eventcatalog-core-user',
+        name: 'Eventcatalog Core User',
+        markdown: 'This is the core user for Eventcatalog',
+        avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+      });
+
+      const user = await getUser('eventcatalog-core-user');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'users', 'eventcatalog-core-user.mdx'))).toBe(true);
+
+      expect(user).toEqual({
+        id: 'eventcatalog-core-user',
+        name: 'Eventcatalog Core User',
+        markdown: 'This is the core user for Eventcatalog',
+        avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+      });
+    });
+
+    it('throws an error when trying to write a user that already exists', async () => {
+      await writeUser({
+        id: 'eventcatalog-core-user',
+        name: 'Eventcatalog Core User',
+        markdown: 'This is the core user for Eventcatalog',
+        avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+      });
+
+      await expect(
+        writeUser({
+          id: 'eventcatalog-core-user',
+          name: 'Eventcatalog Core User',
+          markdown: 'This is the core user for Eventcatalog',
+          avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+        })
+      ).rejects.toThrowError('Failed to write eventcatalog-core-user (user) as it already exists');
+    });
+
+    it('overrides the user when trying to write an user that already exists and override is true', async () => {
+      await writeUser({
+        id: 'eventcatalog-core-user',
+        name: 'Eventcatalog Core User',
+        markdown: 'This is the core user for Eventcatalog',
+        avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+      });
+
+      await writeUser(
+        {
+          id: 'eventcatalog-core-user',
+          name: 'Eventcatalog Core User Overridden',
+          markdown: 'This is the core user for Eventcatalog',
+          avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+        },
+        { override: true }
+      );
+
+      const user = await getUser('eventcatalog-core-user');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'users', 'eventcatalog-core-user.mdx'))).toBe(true);
+      expect(user?.name).toBe('Eventcatalog Core User Overridden');
+    });
+  });
+
+  describe('rmUserById', () => {
+    it('removes a user from eventcatalog by id', async () => {
+      await writeUser({
+        id: 'eventcatalog-core-user',
+        name: 'Eventcatalog Core User',
+        markdown: 'This is the core user for Eventcatalog',
+        avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+      });
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'users', 'eventcatalog-core-user.mdx'))).toBe(true);
+
+      await rmUserById('eventcatalog-core-user');
+
+      expect(fs.existsSync(path.join(CATALOG_PATH, 'users', 'eventcatalog-core-user.mdx'))).toBe(false);
+    });
+  });
+});
diff --git a/packages/sdk/src/types.d.ts b/packages/sdk/src/types.d.ts
new file mode 100644
index 000000000..dfd9bbb60
--- /dev/null
+++ b/packages/sdk/src/types.d.ts
@@ -0,0 +1,574 @@
+// Base type for all resources (domains, services and messages)
+export interface BaseSchema {
+  id: string;
+  name: string;
+  summary?: string;
+  version: string;
+  badges?: Badge[];
+  sidebar?: {
+    badge?: string;
+  };
+  owners?: string[];
+  schemaPath?: string;
+  schemas?: SchemaPointer[];
+  markdown: string;
+  repository?: {
+    language?: string;
+    url?: string;
+  };
+  deprecated?:
+    | boolean
+    | {
+        date?: string;
+        message?: string;
+      };
+  styles?: {
+    icon?: string;
+    node?: {
+      color?: string;
+      label?: string;
+    };
+  };
+  attachments?:
+    | string[]
+    | {
+        url: string;
+        title?: string;
+        type?: string;
+        description?: string;
+        icon?: string;
+      }[];
+  resourceGroups?: ResourceGroup[];
+  diagrams?: ResourcePointer[];
+  editUrl?: string;
+  draft?: boolean | { title?: string; message?: string };
+  // SDK types
+  schema?: any;
+}
+
+export type ResourcePointer = {
+  id: string;
+  version?: string;
+  type?: string;
+};
+
+export type SystemScope = 'internal' | 'external';
+
+export type SystemRelationshipPointer = {
+  id: string;
+  version?: string;
+  label?: string;
+};
+
+export type SystemActorRelationship = {
+  id: string;
+  name?: string;
+  label?: string;
+  direction?: 'inbound' | 'outbound';
+};
+
+export type SchemaPointer = {
+  id?: string;
+  ref?: string;
+  file?: string;
+  path?: string;
+  name?: string;
+  format?: string;
+  environments?: string[];
+  default?: boolean;
+};
+
+export type SendsPointer = {
+  id: string;
+  version?: string;
+  fields?: string[];
+  to?: ChannelPointer[];
+  group?: string;
+};
+
+export type ReceivesPointer = {
+  id: string;
+  version?: string;
+  fields?: string[];
+  from?: ChannelPointer[];
+  group?: string;
+};
+
+export interface ResourceGroup {
+  id?: string;
+  title?: string;
+  items: ResourcePointer[];
+  limit?: number;
+  sidebar?: boolean;
+}
+
+export interface ChannelPointer extends ResourcePointer {
+  parameters?: Record<string, string>;
+}
+
+export type Operation = {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  path?: string;
+  statusCodes?: string[];
+};
+
+export type Message = Event | Command | Query;
+
+enum ResourceType {
+  Service = 'service',
+  Event = 'event',
+  Command = 'command',
+}
+
+export interface CustomDoc {
+  title: string;
+  summary: string;
+  slug?: string;
+  sidebar?: {
+    label: string;
+    order: number;
+  };
+  owners?: string[];
+  badges?: Badge[];
+  fileName?: string;
+  markdown: string;
+}
+
+interface MessageDetailsPanelProperty {
+  producers?: DetailPanelProperty;
+  consumers?: DetailPanelProperty;
+  channels?: DetailPanelProperty;
+  versions?: DetailPanelProperty;
+  repository?: DetailPanelProperty;
+  owners?: DetailPanelProperty;
+  changelog?: DetailPanelProperty;
+  attachments?: DetailPanelProperty;
+}
+
+export interface Event extends BaseSchema {
+  channels?: ChannelPointer[];
+  operation?: Operation;
+  detailsPanel?: MessageDetailsPanelProperty;
+}
+export interface Command extends BaseSchema {
+  channels?: ChannelPointer[];
+  operation?: Operation;
+  detailsPanel?: MessageDetailsPanelProperty;
+}
+export interface Query extends BaseSchema {
+  channels?: ChannelPointer[];
+  operation?: Operation;
+  detailsPanel?: MessageDetailsPanelProperty;
+}
+export interface Channel extends BaseSchema {
+  address?: string;
+  protocols?: string[];
+  deliveryGuarantee?: 'at-most-once' | 'at-least-once' | 'exactly-once';
+  routes?: ChannelPointer[];
+  detailsPanel?: {
+    producers?: DetailPanelProperty;
+    consumers?: DetailPanelProperty;
+    messages?: DetailPanelProperty;
+    protocols?: DetailPanelProperty;
+    parameters?: DetailPanelProperty;
+    versions?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+    attachments?: DetailPanelProperty;
+  };
+  parameters?: {
+    [key: string]: {
+      enum?: string[];
+      default?: string;
+      examples?: string[];
+      description?: string;
+    };
+  };
+}
+
+export interface Specifications {
+  asyncapiPath?: string;
+  openapiPath?: string;
+  graphqlPath?: string;
+}
+
+export interface Specification {
+  type: 'openapi' | 'asyncapi' | 'graphql';
+  path: string;
+  name?: string;
+}
+
+export interface Service extends BaseSchema {
+  sends?: SendsPointer[];
+  receives?: ReceivesPointer[];
+  entities?: ResourcePointer[];
+  writesTo?: ResourcePointer[];
+  readsFrom?: ResourcePointer[];
+  flows?: ResourcePointer[];
+  externalSystem?: boolean;
+  specifications?: Specifications | Specification[];
+  detailsPanel?: {
+    domains?: DetailPanelProperty;
+    messages?: DetailPanelProperty;
+    versions?: DetailPanelProperty;
+    specifications?: DetailPanelProperty;
+    entities?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+    flows?: DetailPanelProperty;
+  };
+}
+
+export type AgentTool = {
+  name: string;
+  type: string;
+  icon?: string;
+  url?: string;
+  description?: string;
+};
+
+export type AgentModel = {
+  provider?: string;
+  name?: string;
+  version?: string;
+};
+
+export interface Agent extends BaseSchema {
+  sends?: SendsPointer[];
+  receives?: ReceivesPointer[];
+  writesTo?: ResourcePointer[];
+  readsFrom?: ResourcePointer[];
+  flows?: ResourcePointer[];
+  model?: AgentModel;
+  tools?: AgentTool[];
+  detailsPanel?: {
+    domains?: DetailPanelProperty;
+    messages?: DetailPanelProperty;
+    versions?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+    containers?: DetailPanelProperty;
+    tools?: DetailPanelProperty;
+    model?: DetailPanelProperty;
+  };
+}
+
+export interface Domain extends BaseSchema {
+  services?: ResourcePointer[];
+  agents?: ResourcePointer[];
+  domains?: ResourcePointer[];
+  systems?: ResourcePointer[];
+  entities?: ResourcePointer[];
+  dataProducts?: ResourcePointer[];
+  flows?: ResourcePointer[];
+  sends?: SendsPointer[];
+  receives?: ReceivesPointer[];
+  detailsPanel?: {
+    parentDomains?: DetailPanelProperty;
+    subdomains?: DetailPanelProperty;
+    systems?: DetailPanelProperty;
+    services?: DetailPanelProperty;
+    agents?: DetailPanelProperty;
+    entities?: DetailPanelProperty;
+    messages?: DetailPanelProperty;
+    ubiquitousLanguage?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    versions?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+  };
+}
+
+export interface System extends BaseSchema {
+  scope?: SystemScope;
+  services?: ResourcePointer[];
+  flows?: ResourcePointer[];
+  entities?: ResourcePointer[];
+  containers?: ResourcePointer[];
+  relationships?: SystemRelationshipPointer[];
+  actors?: SystemActorRelationship[];
+  detailsPanel?: {
+    versions?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+    attachments?: DetailPanelProperty;
+    services?: DetailPanelProperty;
+    flows?: DetailPanelProperty;
+    entities?: DetailPanelProperty;
+    containers?: DetailPanelProperty;
+    diagrams?: DetailPanelProperty;
+  };
+}
+
+export interface Team {
+  id: string;
+  name: string;
+  avatarUrl?: string;
+  role?: string;
+  summary?: string;
+  email?: string;
+  hidden?: boolean;
+  source?: {
+    provider: string;
+    id?: string;
+    url?: string;
+  };
+  readOnly?: boolean;
+  slackDirectMessageUrl?: string;
+  members?: User[] | string[];
+  ownedCommands?: Command[];
+  ownedServices?: Service[];
+  ownedEvents?: Event[];
+  markdown: string;
+}
+
+export interface User {
+  id: string;
+  name: string;
+  avatarUrl?: string;
+  role?: string;
+  hidden?: boolean;
+  source?: {
+    provider: string;
+    id?: string;
+    url?: string;
+  };
+  readOnly?: boolean;
+  email?: string;
+  slackDirectMessageUrl?: string;
+  ownedServices?: Service[];
+  ownedEvents?: Event[];
+  ownedCommands?: Command[];
+  associatedTeams?: Team[];
+  markdown: string;
+}
+
+export interface Badge {
+  content: string;
+  backgroundColor: string;
+  textColor: string;
+  icon?: string;
+  url?: string;
+}
+
+export interface Changelog {
+  createdAt: Date | string;
+  badges?: Badge[];
+  markdown: string;
+}
+
+export interface UbiquitousLanguage {
+  id: string;
+  name: string;
+  summary?: string;
+  description?: string;
+  icon?: string;
+}
+
+export interface UbiquitousLanguageDictionary {
+  dictionary: UbiquitousLanguage[];
+}
+
+interface DetailPanelProperty {
+  visible: boolean;
+}
+
+export interface Entity extends BaseSchema {
+  aggregateRoot?: boolean;
+  identifier?: string;
+  properties?: {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+    references?: string;
+    referencesIdentifier?: string;
+    relationType?: string;
+  }[];
+  detailsPanel?: {
+    domains?: DetailPanelProperty;
+    services?: DetailPanelProperty;
+    messages?: DetailPanelProperty;
+    versions?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+  };
+}
+
+export interface Diagram extends BaseSchema {
+  detailsPanel?: {
+    versions?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+    attachments?: DetailPanelProperty;
+  };
+}
+
+export type AdrStatus = 'proposed' | 'accepted' | 'rejected' | 'deprecated' | 'superseded';
+
+export type AdrPointer = {
+  id: string;
+  version?: string;
+};
+
+export type AdrResourcePointer = AdrPointer & {
+  type:
+    | 'agent'
+    | 'service'
+    | 'event'
+    | 'command'
+    | 'query'
+    | 'flow'
+    | 'channel'
+    | 'domain'
+    | 'system'
+    | 'user'
+    | 'team'
+    | 'container'
+    | 'entity'
+    | 'diagram'
+    | 'data-product';
+};
+
+export interface Adr extends BaseSchema {
+  status: AdrStatus;
+  date: Date | string;
+  decisionMakers?: string[];
+  appliesTo?: AdrResourcePointer[];
+  supersedes?: AdrPointer[];
+  supersededBy?: AdrPointer[];
+  amends?: AdrPointer[];
+  amendedBy?: AdrPointer[];
+  related?: AdrPointer[];
+  detailsPanel?: {
+    status?: DetailPanelProperty;
+    date?: DetailPanelProperty;
+    decisionMakers?: DetailPanelProperty;
+    appliesTo?: DetailPanelProperty;
+    relationships?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+  };
+}
+
+export type DataProductOutputPointer = {
+  id: string;
+  version?: string;
+  contract?: {
+    path: string;
+    name: string;
+    type?: string;
+  };
+};
+
+export interface DataProduct extends BaseSchema {
+  inputs?: ResourcePointer[];
+  outputs?: DataProductOutputPointer[];
+  detailsPanel?: {
+    domains?: DetailPanelProperty;
+    inputs?: DetailPanelProperty;
+    outputs?: DetailPanelProperty;
+    versions?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+    flows?: DetailPanelProperty;
+  };
+}
+
+enum DataClassification {
+  Public = 'public',
+  Internal = 'internal',
+  Confidential = 'confidential',
+  Regulated = 'regulated',
+}
+
+export interface FlowStep {
+  id: string | number;
+  type?: 'node' | 'message' | 'agent' | 'user' | 'actor';
+  title: string;
+  summary?: string;
+  message?: ResourcePointer;
+  agent?: ResourcePointer;
+  service?: ResourcePointer;
+  flow?: ResourcePointer;
+  container?: ResourcePointer;
+  dataProduct?: ResourcePointer;
+  actor?: {
+    name: string;
+    summary?: string;
+  };
+  custom?: {
+    title: string;
+    icon?: string;
+    type?: string;
+    summary?: string;
+    url?: string;
+    color?: string;
+    properties?: Record<string, string | number>;
+    height?: number;
+    menu?: { label: string; url?: string }[];
+  };
+  externalSystem?: {
+    name: string;
+    summary?: string;
+    url?: string;
+  };
+  next_step?: string | number | { id: string | number; label?: string };
+  next_steps?: (string | number | { id: string | number; label?: string })[];
+}
+
+export interface Flow extends BaseSchema {
+  steps: FlowStep[];
+  detailsPanel?: {
+    owners?: DetailPanelProperty;
+    versions?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+  };
+}
+
+export interface Container extends BaseSchema {
+  container_type: 'database' | 'cache' | 'objectStore' | 'searchIndex' | 'dataWarehouse' | 'dataLake' | 'externalSaaS' | 'other';
+  technology?: string;
+  authoritative?: boolean;
+  access_mode?: string;
+  classification?: DataClassification;
+  residency?: string;
+  retention?: string;
+  detailsPanel?: {
+    versions?: DetailPanelProperty;
+    repository?: DetailPanelProperty;
+    owners?: DetailPanelProperty;
+    changelog?: DetailPanelProperty;
+  };
+}
+
+export type EventCatalog = {
+  version: string;
+  catalogVersion: string;
+  createdAt: string;
+  resources: {
+    domains?: ExportedResource<Domain>[];
+    systems?: ExportedResource<System>[];
+    services?: ExportedResource<Service>[];
+    agents?: ExportedResource<Agent>[];
+    messages?: {
+      events?: ExportedResource<Event>[];
+      queries?: ExportedResource<Query>[];
+      commands?: ExportedResource<Command>[];
+    };
+    teams?: ExportedResource<Team>[];
+    users?: ExportedResource<User>[];
+    channels?: ExportedResource<Channel>[];
+    entities?: ExportedResource<Entity>[];
+    containers?: ExportedResource<Container>[];
+    flows?: ExportedResource<Flow>[];
+    adrs?: ExportedResource<Adr>[];
+    customDocs?: ExportedResource<CustomDoc>[];
+  };
+};
diff --git a/packages/sdk/src/users.ts b/packages/sdk/src/users.ts
new file mode 100644
index 000000000..c7577792c
--- /dev/null
+++ b/packages/sdk/src/users.ts
@@ -0,0 +1,146 @@
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import { join } from 'node:path';
+import type { User } from './types';
+import matter from 'gray-matter';
+import { getFiles, invalidateFileCache } from './internal/utils';
+import {
+  mergeDirectoryStoreResources,
+  readDirectoryStoreResource,
+  readDirectoryStoreResources,
+} from './internal/directory-store';
+
+/**
+ * Returns a user from EventCatalog.
+ *
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getUser } = utils('/path/to/eventcatalog');
+ *
+ * // Gets the user with the given id
+ * const user = await getUser('eventcatalog-core-user');
+ *
+ * ```
+ */
+export const getUser =
+  (catalogDir: string) =>
+  async (id: string): Promise<User | undefined> => {
+    const files = await getFiles(`${catalogDir}/${id}.{md,mdx}`);
+
+    if (files.length == 0) return readDirectoryStoreResource<User>(catalogDir, 'users', id);
+    const file = files[0];
+
+    const { data, content } = matter.read(file);
+    return {
+      ...data,
+      id: data.id,
+      name: data.name,
+      avatarUrl: data.avatarUrl,
+      markdown: content.trim(),
+    } as User;
+  };
+
+/**
+ * Returns all users from EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { getUsers } = utils('/path/to/eventcatalog');
+ *
+ * // Gets all users from the catalog
+ * const channels = await getUsers();
+ *
+ * ```
+ */
+export const getUsers =
+  (catalogDir: string) =>
+  async (options?: {}): Promise<User[]> => {
+    const files = await getFiles(`${catalogDir}/users/*.{md,mdx}`);
+    const localUsers = files.map((file) => {
+      const { data, content } = matter.read(file);
+      return {
+        ...data,
+        id: data.id,
+        name: data.name,
+        avatarUrl: data.avatarUrl,
+        markdown: content.trim(),
+      } as User;
+    });
+
+    return mergeDirectoryStoreResources(localUsers, readDirectoryStoreResources<User>(catalogDir, 'users'));
+  };
+
+/**
+ * Write a user to EventCatalog.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { writeUser } = utils('/path/to/eventcatalog');
+ *
+ * // Write a user to the catalog
+ * // user would be written to users/eventcatalog-tech-lead
+ * await writeUser({
+ *   id: 'eventcatalog-tech-lead',
+ *   name: 'EventCatalog Tech Lead',
+ *   email: 'test@test.com',
+ *   avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+ *   slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+ * });
+ *
+ * // Write a team to the catalog and override the existing content (if there is any)
+ * await writeUser({
+ *   id: 'eventcatalog-tech-lead',
+ *   name: 'EventCatalog Tech Lead',
+ *   email: 'test@test.com',
+ *   avatarUrl: 'https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png',
+ *   slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+ * }, { override: true });
+ *
+ * ```
+ */
+export const writeUser =
+  (catalogDir: string) =>
+  async (user: User, options: { override?: boolean } = {}) => {
+    const resource: User = { ...user };
+
+    // Get the path
+    const currentUser = await getUser(catalogDir)(resource.id);
+    const exists = currentUser !== undefined;
+
+    if (exists && !options.override) {
+      throw new Error(`Failed to write ${resource.id} (user) as it already exists`);
+    }
+
+    const { markdown, ...frontmatter } = resource;
+
+    const document = matter.stringify(markdown, frontmatter);
+    fsSync.mkdirSync(join(catalogDir, ''), { recursive: true });
+    fsSync.writeFileSync(join(catalogDir, '', `${resource.id}.mdx`), document);
+    invalidateFileCache();
+  };
+
+/**
+ * Delete a user by it's id.
+ *
+ * @example
+ * ```ts
+ * import utils from '@eventcatalog/utils';
+ *
+ * const { rmUserById } = utils('/path/to/eventcatalog');
+ *
+ * // deletes the user with id eventcatalog-core-user
+ * await rmUserById('eventcatalog-core-user');
+ *
+ * ```
+ */
+export const rmUserById = (catalogDir: string) => async (id: string) => {
+  fsSync.rmSync(join(catalogDir, `${id}.mdx`), { recursive: true });
+  invalidateFileCache();
+};
diff --git a/packages/sdk/tsconfig.json b/packages/sdk/tsconfig.json
new file mode 100644
index 000000000..39814b2a3
--- /dev/null
+++ b/packages/sdk/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "es2016" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
+    "module": "commonjs" /* Specify what module code is generated. */,
+    "esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */,
+    "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
+    "strict": true /* Enable all strict type-checking options. */,
+    "skipLibCheck": true /* Skip type checking all .d.ts files. */
+  }
+}
diff --git a/packages/sdk/tsup.config.ts b/packages/sdk/tsup.config.ts
new file mode 100644
index 000000000..fb61e6c6c
--- /dev/null
+++ b/packages/sdk/tsup.config.ts
@@ -0,0 +1,15 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  target: 'es2020',
+  format: ['cjs', 'esm'],
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  dts: true,
+  entry: {
+    index: 'src/index.ts',
+  },
+  outDir: 'dist',
+  shims: true,
+});
diff --git a/packages/sdk/vitest.config.ts b/packages/sdk/vitest.config.ts
new file mode 100644
index 000000000..b2e4b41bb
--- /dev/null
+++ b/packages/sdk/vitest.config.ts
@@ -0,0 +1,9 @@
+/// <reference types="vitest" />
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    setupFiles: ['./vitest.setup.ts'],
+    // ... Specify options here.
+  },
+});
diff --git a/packages/sdk/vitest.setup.ts b/packages/sdk/vitest.setup.ts
new file mode 100644
index 000000000..b067523a4
--- /dev/null
+++ b/packages/sdk/vitest.setup.ts
@@ -0,0 +1,41 @@
+import { expect, Assertion, AsymmetricMatchersContaining } from 'vitest';
+
+interface CustomMatchers<R = unknown> {
+  toMatchMarkdown: (str: string) => R;
+}
+
+declare module 'vitest' {
+  interface Assertion<T = any> extends CustomMatchers<T> {}
+  interface AsymmetricMatchersContaining extends CustomMatchers {}
+}
+
+// Function to normalize whitespace
+const normalizeWhitespace = (str: string) => str.replace(/\s+/g, ' ').trim();
+
+declare global {
+  namespace vitest {
+    interface Assertion<T> {
+      toMatchMarkdown(expected: string): void;
+    }
+  }
+}
+
+// Custom matcher to compare Markdown strings ignoring whitespace differences
+expect.extend({
+  toMatchMarkdown(received, expected) {
+    const normalizedReceived = normalizeWhitespace(received);
+    const normalizedExpected = normalizeWhitespace(expected);
+
+    if (normalizedReceived === normalizedExpected) {
+      return {
+        message: () => `expected ${received} not to match Markdown ${expected} ignoring whitespace`,
+        pass: true,
+      };
+    } else {
+      return {
+        message: () => `expected ${received} to match Markdown ${expected} ignoring whitespace`,
+        pass: false,
+      };
+    }
+  },
+});
diff --git a/packages/visualiser/.gitignore b/packages/visualiser/.gitignore
new file mode 100644
index 000000000..df7299e7a
--- /dev/null
+++ b/packages/visualiser/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+.turbo
+*.log
diff --git a/packages/visualiser/CHANGELOG.md b/packages/visualiser/CHANGELOG.md
new file mode 100644
index 000000000..3d727a844
--- /dev/null
+++ b/packages/visualiser/CHANGELOG.md
@@ -0,0 +1,260 @@
+# @eventcatalog/visualiser
+
+## 4.0.1
+
+### Patch Changes
+
+- f963964: Fix visualiser image export (download visual) so grouped graphs are no longer cropped and SVG edges/labels keep their colors in the exported PNG
+
+## 4.0.0
+
+### Major Changes
+
+- 728ca67: Add support for a new `systems` collection. Systems are a versioned resource that can be defined in any folder (including inside domains), rendered as documentation pages, and listed in the sidebar with their own icon and color. Systems can group services, flows, entities, data stores (containers), and diagrams, have their own architecture overview page (`/architecture/systems/[id]`) listing their entities, services, external integrations, data stores, and flows, be visualised as an architecture map, be browsed and filtered on a dedicated discover page (`/discover/systems`), and be targeted by architecture decision records (`appliesTo: [{ type: 'system' }]`). Domains can reference one or more systems, which are listed in the domain sidebar, rendered as expandable sections on the domain's architecture page (listing the system's services, like subdomains, with external services shown under "External Integrations"), and merged into the domain's architecture map (each referenced system's services are grouped within the domain graph). Teams and users can own systems, which are surfaced on their profile pages.
+
+  Systems can also declare `relationships` to other systems (each with an optional `version` and `label`), which power a new **Context Diagram** visualiser (`/visualiser/systems/[id]/[version]/context`, linked from the system sidebar under Architecture). Starting from a system, the diagram walks its relationships outward to build the reachable neighbourhood of systems, rendering each as a node (showing its service, entity, and data store counts) connected by labelled edges. Clicking a system node opens that system's architecture map.
+
+  Systems support a `scope` of `internal` (default) or `external`. External systems represent third-party/SaaS systems you integrate with (e.g. "Resend", "Stripe") and are shaded and badged as "External System" in the Context Diagram.
+
+  Systems can also declare `actors` — people or roles that interact with the system (e.g. a Customer or Support Agent). Each actor has an `id` (used to de-duplicate the same actor across systems), an optional `name`/`label`, and a `direction` (`inbound` = actor → system, e.g. "logs into"; `outbound` = system → actor, e.g. "sends notifications to"). Actors are rendered as nodes on the Context Diagram connected to their system by a labelled, directional edge.
+
+## 4.0.0-beta.0
+
+### Major Changes
+
+- 728ca67: Add support for a new `systems` collection. Systems are a versioned resource that can be defined in any folder (including inside domains), rendered as documentation pages, and listed in the sidebar with their own icon and color. Systems can group services, flows, entities, data stores (containers), and diagrams, have their own architecture overview page (`/architecture/systems/[id]`) listing their entities, services, external integrations, data stores, and flows, be visualised as an architecture map, be browsed and filtered on a dedicated discover page (`/discover/systems`), and be targeted by architecture decision records (`appliesTo: [{ type: 'system' }]`). Domains can reference one or more systems, which are listed in the domain sidebar, rendered as expandable sections on the domain's architecture page (listing the system's services, like subdomains, with external services shown under "External Integrations"), and merged into the domain's architecture map (each referenced system's services are grouped within the domain graph). Teams and users can own systems, which are surfaced on their profile pages.
+
+  Systems can also declare `relationships` to other systems (each with an optional `version` and `label`), which power a new **Context Diagram** visualiser (`/visualiser/systems/[id]/[version]/context`, linked from the system sidebar under Architecture). Starting from a system, the diagram walks its relationships outward to build the reachable neighbourhood of systems, rendering each as a node (showing its service, entity, and data store counts) connected by labelled edges. Clicking a system node opens that system's architecture map.
+
+  Systems support a `scope` of `internal` (default) or `external`. External systems represent third-party/SaaS systems you integrate with (e.g. "Resend", "Stripe") and are shaded and badged as "External System" in the Context Diagram.
+
+  Systems can also declare `actors` — people or roles that interact with the system (e.g. a Customer or Support Agent). Each actor has an `id` (used to de-duplicate the same actor across systems), an optional `name`/`label`, and a `direction` (`inbound` = actor → system, e.g. "logs into"; `outbound` = system → actor, e.g. "sends notifications to"). Actors are rendered as nodes on the Context Diagram connected to their system by a labelled, directional edge.
+
+## 3.22.1
+
+### Patch Changes
+
+- c3b0958: fix node graph styling when rendered inside prose containers and prevent prose styles from affecting visualiser images
+
+## 3.22.0
+
+### Minor Changes
+
+- 50b38f6: Add agents as a first-class resource type. Agents can now be documented alongside services, with support for AI model metadata, tools (MCP servers, APIs), and rendered as distinct nodes in the visualiser. Closes #2564.
+
+## 3.21.1
+
+### Patch Changes
+
+- 8db08c5: Visualiser nodes now show a tooltip with the full resource name on hover when the name is truncated.
+
+## 3.21.0
+
+### Minor Changes
+
+- 6d7151b: Unify resource reference colors across tables, MDX components, and the sidebar via a shared collection-colors utility. Add data-product support to ResourceRef with rich tooltip styling, custom icon support, and updated visualiser data node palette.
+
+## 3.20.3
+
+### Patch Changes
+
+- 3fd03c0: Improve `<Flow />` and `<NodeGraph />` MDX embeds: support boolean MDX props for `search`, `legend`, and `walkthrough`; avoid duplicate page node graph when a `<Flow />` or `<NodeGraph />` is already embedded; use unique portal IDs per flow embed; render a compact NodeGraph menu button when no title is provided.
+
+## 3.20.2
+
+### Patch Changes
+
+- 1c9c217: Add support for `container` and `dataProduct` steps in flows. Flows can now reference data stores (containers) and data products directly as steps, rendered in the flow node graph and sidebar. SDK adds `addDataStoreStep`, `addContainerStep`, and `addDataProductStep` builders.
+
+## 3.20.1
+
+### Patch Changes
+
+- 8f32dc1: Enhance custom flow nodes with richer styling and metadata: color palettes, icons, type badges, summary text, key/value properties, and optional context menu links.
+
+## 3.20.0
+
+### Minor Changes
+
+- 313388f: feat(visualiser): expandable message groups and improved search for large catalogs
+
+  Visualiser now supports expanding grouped message nodes inline so producers/consumers with many messages stay readable on domain and service diagrams. Surrounding nodes are packed around the expanded group so they no longer overlap, and search has been overhauled with icons, resource-type filtering, and better keyboard navigation. Addresses #2079.
+
+## 3.19.0
+
+### Minor Changes
+
+- 3ba10fd: Sub-flow references inside a flow can now be expanded inline. Clicking a sub-flow node in the visualiser inlines the referenced flow's steps in place (mirroring the message-group expand/collapse pattern), with the Collapse button in the header restoring the single-node view. Expanded sub-flow children participate in the business-flow walkthrough, and the graph recentres via `fitView` on both expand and collapse.
+
+## 3.18.4
+
+### Patch Changes
+
+- 1f6fc59: fix: restore custom right-click context menu for message and service nodes in flow diagrams. `flows-node-graph` now populates `contextMenu` on step nodes (previously only non-flow graphs did, so flow pages fell through to the browser default menu). Context-menu items also get explicit colour and no-underline styling so they no longer inherit browser-default purple/underlined link styling when the host page has no link resets.
+
+## 3.18.3
+
+### Patch Changes
+
+- 8c4bee8: Auto-disable message animation when the graph has more than 30 nodes and the user has no stored preference. Explicit `animated` prop, `?animate=` URL param, and localStorage choice still take precedence.
+
+## 3.18.2
+
+### Patch Changes
+
+- 792458e: Add custom icon support to resources via `styles.icon`. Icons render on visualiser nodes, in the sidebar, on documentation page headers, and in the search modal. Accepts a path under the catalog's `public/` folder or an absolute URL. When no custom icon is set, resources now fall back to collection-appropriate default icons. Also maps container `container_type` to a human-readable label on data nodes.
+
+## 3.18.1
+
+### Patch Changes
+
+- 7dee222: fix(visualiser): center multi-line edge labels, add backgrounds to data-store edges, and make the "Layout changed" Save button theme-safe
+
+## 3.18.0
+
+### Minor Changes
+
+- 8f724a7: feat: add `externalSystem` flag to services for modelling third-party integrations
+
+  Services can now set `externalSystem: true` in their frontmatter to be rendered as external systems. This changes their presentation without changing their capabilities — they still send and receive messages, have owners, and support specifications like any other service.
+
+  - Visualiser: external services render purple with a Globe icon and an "External System" badge
+  - Sidebar (root): a dedicated "External Systems" section lists externals; the regular "Services" section excludes them
+  - Sidebar (domain): externals appear under a new "External Integrations" group, separate from "Services In Domain"
+  - Per-service nav badge reads "External System" instead of "Service"
+  - `/discover`: a new "External Systems" tab alongside the "Services" tab
+  - SDK: the `Service` type now accepts `externalSystem?: boolean`
+
+## 3.17.1
+
+### Patch Changes
+
+- 80ff83d: fix security vulnerabilities by upgrading mermaid to 11.12.3 and @astrojs/rss to 4.0.18
+- 4d5a01b: Migrate deprecated useHandleConnections to useNodeConnections across all node components
+
+## 3.17.0
+
+### Minor Changes
+
+- 748c528: Expanding a message group node now renders the full downstream graph (channels, consumers, producers) matching the ungrouped view
+
+## 3.16.1
+
+### Patch Changes
+
+- 038e402: Fix SSR compatibility: remove CSS import from NodeGraph that breaks server-side rendering, add proper type assertion for lazy-loaded component, and export NodeGraphProps type
+
+## 3.16.0
+
+### Minor Changes
+
+- 1539e71: add schema fields explorer with field traceability, conflict detection, and node graph visualization
+
+## 3.15.4
+
+### Patch Changes
+
+- ed1bfdf: Add entity map visualiser for services, matching the existing domain entity map. Services with entities now show an "Entity Map" link in the sidebar under Architecture. Also fix entity map edge arrows not visible in dark mode.
+
+## 3.15.3
+
+### Patch Changes
+
+- d41c8c3: Re-enable hide/show channels toggle in the visualiser
+
+## 3.15.2
+
+### Patch Changes
+
+- a43021e: Refactor language server, playground, and visualiser: extract shared helpers to reduce duplication, add browser entrypoint, definition/hover/formatter providers, resource index, catalog resolver, restructure docs, simplify layout utils, and add VSCode extension scaffold
+
+## 3.15.1
+
+### Patch Changes
+
+- 304c5cb: Scope all visualiser CSS under `.eventcatalog-visualizer` so the package is fully self-contained. Fixes broken styles when installed from npm by including Tailwind utilities in the scoped output. Portals now render inside the scoped container (or document.body for full-screen modals) so styles apply correctly. Dark mode background and focus mode modal z-index fixes included.
+
+## 3.15.0
+
+### Minor Changes
+
+- e11249b: Refine UI theme: improve sidebar active states with accent colors, brighten dark mode text, add subtle gradients, update homepage layout, and add dark mode icon invert support
+
+### Patch Changes
+
+- a67f051: fix visualiser URL builder to support configurable base paths via setBuildUrlFn
+- 31b931c: Use relative content paths in tailwind config and lazy-load visualizer styles to prevent CSS conflicts
+
+## 3.14.1
+
+### Patch Changes
+
+- f435078: Canvas playground UX overhaul: consistent notes indicator across all node types
+
+## 3.14.0
+
+### Minor Changes
+
+- c178b75: core(feat): updated visualiser support for dark mode, new layout engine
+- c178b75: Remove `catalog` object from collection getters, deriving values on-demand instead of pre-computing them for every resource
+- c178b75: Redesign visualiser nodes with post-it note style UI
+  - New post-it note design for all message and service nodes
+  - Folded corner effect and gradient backgrounds
+  - Glow handles with pulse animations
+  - Owner indicators on nodes
+  - Notes indicators for annotated resources
+  - Dark mode support via CSS variables
+  - Shared styles extracted to shared-styles.ts
+  - Group node support
+
+### Patch Changes
+
+- 28fe2d5: fix(visualiser): make focus mode modal styling self-contained
+
+## 3.13.0
+
+### Minor Changes
+
+- 3dc6938: Release stable version from beta
+
+### Patch Changes
+
+- 7d0203c: fix(visualiser): resolve header visibility conflict with tailwind utilities
+- c05874a: Beta release of @eventcatalog/visualiser package
+
+  - Fix node icon positioning: icon at top, label at bottom of left bar
+  - Color-matched connection handles for all node types
+  - Fix animated edge line color (gray-300)
+  - Fix FlowEdge label width for multi-word labels
+  - Bundle Tailwind CSS utilities in dist/styles.css for consumers
+  - Add dynamic color safelist for Flow and Custom nodes
+  - Fix StepWalkthrough panel padding and positioning
+  - Fix Focus Mode initial render centering
+
+- 579c9e2: Fix visualiser node icon spacing in full mode
+
+## 3.13.0-beta.2
+
+### Patch Changes
+
+- 7d0203c: fix(visualiser): resolve header visibility conflict with tailwind utilities
+
+## 3.12.9-beta.1
+
+### Patch Changes
+
+- 579c9e2: Fix visualiser node icon spacing in full mode
+
+## 0.0.2-beta.0
+
+### Patch Changes
+
+- c05874a: Beta release of @eventcatalog/visualiser package
+  - Fix node icon positioning: icon at top, label at bottom of left bar
+  - Color-matched connection handles for all node types
+  - Fix animated edge line color (gray-300)
+  - Fix FlowEdge label width for multi-word labels
+  - Bundle Tailwind CSS utilities in dist/styles.css for consumers
+  - Add dynamic color safelist for Flow and Custom nodes
+  - Fix StepWalkthrough panel padding and positioning
+  - Fix Focus Mode initial render centering
diff --git a/packages/visualiser/README.md b/packages/visualiser/README.md
new file mode 100644
index 000000000..dfe434254
--- /dev/null
+++ b/packages/visualiser/README.md
@@ -0,0 +1,3 @@
+# @eventcatalog/visualizer
+
+EventCatalog Visualizer Package
\ No newline at end of file
diff --git a/packages/visualiser/package.json b/packages/visualiser/package.json
new file mode 100644
index 000000000..0b29b709d
--- /dev/null
+++ b/packages/visualiser/package.json
@@ -0,0 +1,84 @@
+{
+  "name": "@eventcatalog/visualiser",
+  "version": "4.0.1",
+  "description": "ReactFlow nodes and visualiser components for EventCatalog - framework agnostic",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./styles-core.css": "./dist/styles-core.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup && pnpm build:css",
+    "build:bin": "tsup && pnpm build:css",
+    "build:css": "postcss src/styles.css -o dist/styles.css && postcss src/styles-core.css -o dist/styles-core.css",
+    "build:watch": "concurrently \"tsup --watch\" \"postcss src/styles.css -o dist/styles.css --watch\" \"postcss src/styles-core.css -o dist/styles-core.css --watch\"",
+    "dev": "tsup --watch --onSuccess \"pnpm build:css\"",
+    "playground": "vite playground --config playground/vite.config.ts",
+    "clean": "rimraf dist",
+    "test": "vitest --run",
+    "test:ci": "vitest --run",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "format:diff": "prettier --check \"src/**/*.{ts,tsx}\""
+  },
+  "keywords": [
+    "eventcatalog",
+    "reactflow",
+    "visualization",
+    "nodes",
+    "event-driven-architecture"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/event-catalog/eventcatalog.git"
+  },
+  "author": "EventCatalog",
+  "license": "MIT",
+  "dependencies": {
+    "@heroicons/react": "^2.2.0",
+    "@radix-ui/react-context-menu": "^2.2.16",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.4",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@xyflow/react": "^12.6.1",
+    "dagre": "^0.8.5",
+    "html-to-image": "^1.11.11",
+    "lucide-react": "^0.510.0",
+    "marked": "^16.1.2",
+    "mermaid": "^11.12.3",
+    "svg-pan-zoom": "^3.6.2"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.1.5",
+    "@types/dagre": "^0.7.53",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.1",
+    "@vitejs/plugin-react": "^5.1.4",
+    "concurrently": "^8.2.2",
+    "postcss": "^8.5.3",
+    "postcss-cli": "^11.0.0",
+    "prettier": "^3.4.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rimraf": "^6.0.1",
+    "tailwindcss": "^4.1.5",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.2",
+    "vite": "^7.1.9",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  }
+}
diff --git a/packages/visualiser/postcss.config.js b/packages/visualiser/postcss.config.js
new file mode 100644
index 000000000..a396d143e
--- /dev/null
+++ b/packages/visualiser/postcss.config.js
@@ -0,0 +1,95 @@
+import tailwindcss from '@tailwindcss/postcss';
+
+const SCOPE = '.eventcatalog-visualizer';
+
+/** @type {import('postcss').Plugin} */
+const removeLayers = {
+  postcssPlugin: 'remove-layers',
+  AtRule: {
+    layer(atRule) {
+      if (atRule.nodes && atRule.nodes.length > 0) {
+        atRule.replaceWith(atRule.nodes);
+      } else {
+        atRule.remove();
+      }
+    },
+  },
+};
+
+/**
+ * Remove the bare `.hidden` utility rule from the output.
+ * Tailwind v4 content scanning detects "hidden" in inline style strings
+ * (e.g. `overflow: "hidden"`) and emits `.hidden { display: none }`.
+ * This conflicts with responsive header utilities (e.g. `hidden lg:flex`)
+ * in the consuming Astro app because removeLayers flattens all CSS out of
+ * @layer, making cascade order—not layer priority—decide the winner.
+ */
+/** @type {import('postcss').Plugin} */
+const removeHiddenUtility = {
+  postcssPlugin: 'remove-hidden-utility',
+  Rule(rule) {
+    if (rule.selector === '.hidden') {
+      rule.remove();
+    }
+  },
+};
+
+/**
+ * Scope all CSS rules under `.eventcatalog-visualizer` so the visualiser
+ * package is fully self-contained and won't leak styles into the host app.
+ *
+ * Handles special cases:
+ * - Selectors already containing the scope class are left as-is
+ * - `:root` / `html` / `body` selectors are replaced with the scope class
+ * - `[data-theme="dark"]` selectors get the scope inserted after the attribute
+ * - `@keyframes` and other at-rules are left untouched
+ */
+/** @type {import('postcss').Plugin} */
+const scopeSelectors = {
+  postcssPlugin: 'scope-selectors',
+  Rule(rule) {
+    // Skip rules inside @keyframes — animation names are global
+    if (rule.parent?.type === 'atrule' && rule.parent.name === 'keyframes') {
+      return;
+    }
+
+    rule.selectors = rule.selectors.map((selector) => {
+      // Already scoped
+      if (selector.includes(SCOPE)) {
+        return selector;
+      }
+
+      // :root / html / body with attribute selectors or pseudo-classes
+      // e.g. `:root:not([data-theme="dark"]) .react-flow` → `:not([data-theme="dark"]) .eventcatalog-visualizer .react-flow`
+      // e.g. `:root[data-theme="light"] .react-flow` → `[data-theme="light"] .eventcatalog-visualizer .react-flow`
+      const rootMatch = selector.match(/^(:root|html|body)((?::[^\s]+|\[[^\]]+\])+)(\s.*)?$/);
+      if (rootMatch) {
+        const modifiers = rootMatch[2]; // e.g. :not([data-theme="dark"]) or [data-theme="light"]
+        const rest = rootMatch[3] || ''; // e.g. " .react-flow"
+        return `${modifiers} ${SCOPE}${rest}`;
+      }
+
+      // :root or html or body alone or followed by space — replace with scope class
+      if (/^(:root|html|body)(\s|$)/.test(selector)) {
+        return selector.replace(/^(:root|html|body)/, SCOPE);
+      }
+
+      // [data-theme="..."] at the start — insert scope after the attribute selector
+      if (/^\[data-theme/.test(selector)) {
+        return selector.replace(/^(\[data-theme="[^"]*"\])/, `$1 ${SCOPE}`);
+      }
+
+      // Everything else — prepend the scope
+      return `${SCOPE} ${selector}`;
+    });
+  },
+};
+
+export default {
+  plugins: [
+    tailwindcss(),
+    removeLayers,
+    removeHiddenUtility,
+    scopeSelectors,
+  ],
+};
diff --git a/packages/visualiser/src/components/DownloadButton.tsx b/packages/visualiser/src/components/DownloadButton.tsx
new file mode 100644
index 000000000..eca529229
--- /dev/null
+++ b/packages/visualiser/src/components/DownloadButton.tsx
@@ -0,0 +1,80 @@
+import { useReactFlow, useStoreApi, getNodesBounds } from "@xyflow/react";
+import { toPng } from "html-to-image";
+import { DocumentArrowDownIcon } from "@heroicons/react/24/outline";
+import {
+  getExportImageDimensions,
+  injectExportStyles,
+} from "../utils/export-image";
+
+function downloadImage(dataUrl: string, filename?: string) {
+  const a = document.createElement("a");
+
+  a.setAttribute("download", `${filename || "eventcatalog"}.png`);
+  a.setAttribute("href", dataUrl);
+  a.click();
+}
+
+function DownloadButton({
+  filename,
+  addPadding = true,
+}: {
+  filename?: string;
+  addPadding?: boolean;
+}) {
+  const { getNodes } = useReactFlow();
+  const storeApi = useStoreApi();
+  const onClick = () => {
+    // nodeLookup resolves child node positions (relative to their parent
+    // group) to absolute coordinates — without it grouped graphs get cropped
+    const nodesBounds = getNodesBounds(getNodes(), {
+      nodeLookup: storeApi.getState().nodeLookup,
+    });
+    const { width, height, viewport } = getExportImageDimensions(nodesBounds);
+
+    // Hide the button
+    // @ts-ignore
+    document.getElementById("download-visual").style.display = "none";
+    // @ts-ignore
+    document.querySelector(".react-flow__controls").style.display = "none";
+
+    const viewportElement = document.querySelector(
+      ".react-flow__viewport",
+    ) as HTMLElement;
+    const removeExportStyles = injectExportStyles(viewportElement);
+
+    toPng(viewportElement, {
+      backgroundColor: "#f1f1f1",
+      width,
+      height,
+      style: {
+        width: `${width}px`,
+        height: `${height}px`,
+        transform: `translate(${viewport.x}px, ${viewport.y}px) scale(${viewport.zoom})`,
+      },
+    })
+      .then((dataUrl: string) => {
+        downloadImage(dataUrl, filename);
+      })
+      .finally(() => {
+        removeExportStyles();
+        // @ts-ignore
+        document.getElementById("download-visual").style.display = "block";
+        // @ts-ignore
+        document.querySelector(".react-flow__controls").style.display = "block";
+      });
+  };
+
+  return (
+    <div id="download-visual">
+      <button
+        className={`ec-download-btn md:flex bg-white group download-btn items-center space-x-1 text-[14px] border border-gray-200 px-1 py-0.5 rounded-md hover:bg-gray-100/50 ${addPadding ? "mt-14" : "-mt-1"}`}
+        onClick={onClick}
+      >
+        <DocumentArrowDownIcon className="w-4 h-4 group-hover:text-primary" />
+        <span className="group-hover:text-primary">Export visual </span>
+      </button>
+    </div>
+  );
+}
+
+export default DownloadButton;
diff --git a/packages/visualiser/src/components/FocusMode/FocusModeContent.tsx b/packages/visualiser/src/components/FocusMode/FocusModeContent.tsx
new file mode 100644
index 000000000..61478bc29
--- /dev/null
+++ b/packages/visualiser/src/components/FocusMode/FocusModeContent.tsx
@@ -0,0 +1,344 @@
+import React, {
+  useMemo,
+  useCallback,
+  useEffect,
+  useState,
+  useRef,
+} from "react";
+import {
+  ReactFlow,
+  Background,
+  Controls,
+  useReactFlow,
+  useNodesState,
+  useEdgesState,
+  type Node,
+  type Edge,
+  type NodeTypes,
+  type EdgeTypes,
+} from "@xyflow/react";
+import { getConnectedNodes, getNodeDisplayInfo } from "./utils";
+import FocusModeNodeActions from "./FocusModeNodeActions";
+import FocusModePlaceholder from "./FocusModePlaceholder";
+
+interface FocusModeContentProps {
+  centerNodeId: string;
+  nodes: Node[];
+  edges: Edge[];
+  nodeTypes: NodeTypes;
+  edgeTypes: EdgeTypes;
+  onSwitchCenter: (
+    newCenterNodeId: string,
+    direction: "left" | "right",
+  ) => void;
+}
+
+const HORIZONTAL_SPACING = 450;
+const VERTICAL_SPACING = 200;
+const SLIDE_DURATION = 300;
+
+const FocusModeContent: React.FC<FocusModeContentProps> = ({
+  centerNodeId,
+  nodes: allNodes,
+  edges: allEdges,
+  nodeTypes,
+  edgeTypes,
+  onSwitchCenter,
+}) => {
+  const { fitView } = useReactFlow();
+  const [isAnimating, setIsAnimating] = useState(false);
+  const [needsFitView, setNeedsFitView] = useState(false);
+  const [hoveredEdgeId, setHoveredEdgeId] = useState<string | null>(null);
+  const [isReady, setIsReady] = useState(false);
+  const reactFlowInitialized = useRef(false);
+  const animationTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  // Cleanup timeout on unmount
+  useEffect(() => {
+    return () => {
+      if (animationTimeoutRef.current) {
+        clearTimeout(animationTimeoutRef.current);
+      }
+    };
+  }, []);
+
+  // Calculate focused nodes and edges with positions
+  const calculateFocusedGraph = useCallback(
+    (centerId: string) => {
+      const centerNode = allNodes.find((n) => n.id === centerId);
+      if (!centerNode) {
+        return { nodes: [], edges: [] };
+      }
+
+      const { leftNodes, rightNodes } = getConnectedNodes(
+        centerId,
+        allNodes,
+        allEdges,
+      );
+      const centerNodeInfo = getNodeDisplayInfo(centerNode);
+      const positionedNodes: Node[] = [];
+
+      // Center node at origin (strip parentId/extent so it renders independently)
+      positionedNodes.push({
+        ...centerNode,
+        parentId: undefined,
+        extent: undefined,
+        position: { x: 0, y: 0 },
+        style: { ...centerNode.style, opacity: 1 },
+        data: { ...centerNode.data, isFocusCenter: true },
+      });
+
+      // Left nodes (incoming) - strip parentId/extent so they render independently
+      leftNodes.forEach((node, index) => {
+        const yOffset = (index - (leftNodes.length - 1) / 2) * VERTICAL_SPACING;
+        positionedNodes.push({
+          ...node,
+          parentId: undefined,
+          extent: undefined,
+          position: { x: -HORIZONTAL_SPACING, y: yOffset },
+          style: { ...node.style, opacity: 1 },
+        });
+      });
+
+      // Right nodes (outgoing) - strip parentId/extent so they render independently
+      rightNodes.forEach((node, index) => {
+        const yOffset =
+          (index - (rightNodes.length - 1) / 2) * VERTICAL_SPACING;
+        positionedNodes.push({
+          ...node,
+          parentId: undefined,
+          extent: undefined,
+          position: { x: HORIZONTAL_SPACING, y: yOffset },
+          style: { ...node.style, opacity: 1 },
+        });
+      });
+
+      // Add placeholder nodes if no connections exist
+      if (leftNodes.length === 0) {
+        positionedNodes.push({
+          id: "__placeholder-left__",
+          type: "placeholder",
+          position: { x: -HORIZONTAL_SPACING, y: 0 },
+          data: {
+            label: `No inputs found for "${centerNodeInfo.name}" in this diagram`,
+            side: "left",
+          },
+          draggable: false,
+          selectable: false,
+        } as Node);
+      }
+
+      if (rightNodes.length === 0) {
+        positionedNodes.push({
+          id: "__placeholder-right__",
+          type: "placeholder",
+          position: { x: HORIZONTAL_SPACING, y: 0 },
+          data: {
+            label: `No outputs found for "${centerNodeInfo.name}" in this diagram`,
+            side: "right",
+          },
+          draggable: false,
+          selectable: false,
+        } as Node);
+      }
+
+      // Filter edges - only show edges connected to center node
+      const focusedNodeIds = new Set(positionedNodes.map((n) => n.id));
+      const filteredEdges = allEdges
+        .filter((edge) => {
+          // Only include edges where center node is either source or target
+          const connectsToCenter =
+            edge.source === centerId || edge.target === centerId;
+          // And the other end is in our focused nodes
+          const otherEndInFocus =
+            focusedNodeIds.has(edge.source) && focusedNodeIds.has(edge.target);
+          return connectsToCenter && otherEndInFocus;
+        })
+        .map((edge) => ({
+          ...edge,
+          style: { ...edge.style, opacity: 1 },
+          labelStyle: { ...edge.labelStyle, opacity: 1 },
+          data: { ...edge.data, opacity: 1, animated: false },
+          animated: false,
+        }));
+
+      return { nodes: positionedNodes, edges: filteredEdges };
+    },
+    [allNodes, allEdges],
+  );
+
+  // Initial graph
+  const initialGraph = useMemo(
+    () => calculateFocusedGraph(centerNodeId),
+    [centerNodeId, calculateFocusedGraph],
+  );
+
+  const [displayNodes, setDisplayNodes] = useNodesState(initialGraph.nodes);
+  const [displayEdges, setDisplayEdges] = useEdgesState(initialGraph.edges);
+
+  // Update when centerNodeId changes externally
+  useEffect(() => {
+    const { nodes, edges } = calculateFocusedGraph(centerNodeId);
+    setDisplayNodes(nodes);
+    setDisplayEdges(edges);
+    setNeedsFitView(true);
+  }, [centerNodeId, calculateFocusedGraph, setDisplayNodes, setDisplayEdges]);
+
+  // FitView when needed - triggered after nodes are updated
+  useEffect(() => {
+    if (needsFitView && reactFlowInitialized.current) {
+      // Small delay to ensure nodes are rendered, then fit view
+      const timer = setTimeout(() => {
+        fitView({ padding: 0.2, duration: 300 });
+        setNeedsFitView(false);
+      }, 50);
+      return () => clearTimeout(timer);
+    }
+  }, [needsFitView, displayNodes, fitView]);
+
+  // Handle ReactFlow initialization
+  const handleInit = useCallback(() => {
+    reactFlowInitialized.current = true;
+    // Dialog opens instantly (no animation), so fitView immediately
+    requestAnimationFrame(() => {
+      fitView({ padding: 0.2, duration: 0 });
+      setIsReady(true);
+    });
+  }, [fitView]);
+
+  // Handle switching to a new center node with animation
+  const handleSwitchNode = useCallback(
+    (nodeId: string, direction: "left" | "right") => {
+      if (nodeId === centerNodeId || isAnimating) return;
+
+      setIsAnimating(true);
+
+      // Animate: clicked node slides to center, current center hides
+      setDisplayNodes((currentNodes) =>
+        currentNodes.map((node) => {
+          if (node.id === nodeId) {
+            // Clicked node slides to center
+            return {
+              ...node,
+              position: { x: 0, y: 0 },
+              style: {
+                ...node.style,
+                transition: `all ${SLIDE_DURATION}ms ease-out`,
+              },
+            };
+          }
+          if (node.id === centerNodeId) {
+            // Current center node hides
+            return {
+              ...node,
+              style: {
+                ...node.style,
+                opacity: 0,
+                transition: `opacity ${SLIDE_DURATION}ms ease-out`,
+              },
+            };
+          }
+          return node;
+        }),
+      );
+
+      // After slide completes, switch to new center
+      animationTimeoutRef.current = setTimeout(() => {
+        onSwitchCenter(nodeId, direction);
+        setIsAnimating(false);
+      }, SLIDE_DURATION);
+    },
+    [centerNodeId, isAnimating, setDisplayNodes, onSwitchCenter],
+  );
+
+  // Handle node click with animation
+  const handleNodeClick = useCallback(
+    (_: React.MouseEvent, clickedNode: Node) => {
+      if (clickedNode.id === centerNodeId || isAnimating) return;
+      const direction = (clickedNode.position?.x ?? 0) < 0 ? "left" : "right";
+      handleSwitchNode(clickedNode.id, direction);
+    },
+    [centerNodeId, isAnimating, handleSwitchNode],
+  );
+
+  // Handle edge hover for animation
+  const handleEdgeMouseEnter = useCallback(
+    (_: React.MouseEvent, edge: Edge) => {
+      setHoveredEdgeId(edge.id);
+    },
+    [],
+  );
+
+  const handleEdgeMouseLeave = useCallback(() => {
+    setHoveredEdgeId(null);
+  }, []);
+
+  // Apply hover animation to edges - use ReactFlow's built-in animated property
+  const edgesWithHover = useMemo(() => {
+    return displayEdges.map((edge) => {
+      if (edge.id === hoveredEdgeId) {
+        return {
+          ...edge,
+          animated: true,
+        };
+      }
+      return edge;
+    });
+  }, [displayEdges, hoveredEdgeId]);
+
+  // Merge nodeTypes with placeholder
+  const mergedNodeTypes = useMemo(
+    () => ({
+      ...nodeTypes,
+      placeholder: FocusModePlaceholder,
+    }),
+    [nodeTypes],
+  );
+
+  if (displayNodes.length === 0) {
+    return (
+      <div className="flex items-center justify-center h-full text-[rgb(var(--ec-page-text-muted))]">
+        Node not found
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="h-full w-full focus-mode-container"
+      style={{ opacity: isReady ? 1 : 0 }}
+    >
+      <ReactFlow
+        nodes={displayNodes}
+        edges={edgesWithHover}
+        nodeTypes={mergedNodeTypes}
+        edgeTypes={edgeTypes}
+        onNodeClick={handleNodeClick}
+        onEdgeMouseEnter={handleEdgeMouseEnter}
+        onEdgeMouseLeave={handleEdgeMouseLeave}
+        onInit={handleInit}
+        proOptions={{ hideAttribution: true }}
+        nodesDraggable={true}
+        nodesConnectable={false}
+        elementsSelectable={true}
+        panOnDrag={true}
+        zoomOnScroll={true}
+        minZoom={0.3}
+        maxZoom={2}
+      >
+        <Background color="rgb(var(--ec-page-border))" gap={20} />
+        <Controls showInteractive={false} />
+        {displayNodes.map((node, index) => (
+          <FocusModeNodeActions
+            key={`actions-${node.id}-${index}`}
+            node={node}
+            isCenter={node.id === centerNodeId}
+            onSwitch={handleSwitchNode}
+          />
+        ))}
+      </ReactFlow>
+    </div>
+  );
+};
+
+export default FocusModeContent;
diff --git a/packages/visualiser/src/components/FocusMode/FocusModeNodeActions.tsx b/packages/visualiser/src/components/FocusMode/FocusModeNodeActions.tsx
new file mode 100644
index 000000000..5e3830984
--- /dev/null
+++ b/packages/visualiser/src/components/FocusMode/FocusModeNodeActions.tsx
@@ -0,0 +1,106 @@
+import React from "react";
+import { NodeToolbar, Position, useViewport, type Node } from "@xyflow/react";
+import { ArrowRightLeft, FileText } from "lucide-react";
+import { getNodeDocUrl } from "./utils";
+import { buildUrl } from "../../utils/url-builder";
+
+interface FocusModeNodeActionsProps {
+  node: Node;
+  isCenter: boolean;
+  onSwitch: (nodeId: string, direction: "left" | "right") => void;
+}
+
+const FocusModeNodeActions: React.FC<FocusModeNodeActionsProps> = ({
+  node,
+  isCenter,
+  onSwitch,
+}) => {
+  const { zoom } = useViewport();
+
+  // Don't show actions for placeholder nodes
+  if (node.type === "placeholder") return null;
+
+  const docUrl = getNodeDocUrl(node);
+  const direction = (node.position?.x ?? 0) < 0 ? "left" : "right";
+
+  // Scale sizes based on zoom (inverse relationship - smaller when zoomed out)
+  const baseButtonSize = 24;
+  const baseIconSize = 12;
+  const scaleFactor = Math.max(0.4, Math.min(1, zoom));
+  const buttonSize = Math.round(baseButtonSize * scaleFactor);
+  const iconSize = Math.round(baseIconSize * scaleFactor);
+
+  const handleSwitch = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    onSwitch(node.id, direction);
+  };
+
+  const handleDocClick = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (docUrl) {
+      window.location.href = buildUrl(docUrl);
+    }
+  };
+
+  // Center node only shows docs icon (if available)
+  if (isCenter) {
+    if (!docUrl) return null;
+    return (
+      <NodeToolbar
+        nodeId={node.id}
+        position={Position.Bottom}
+        isVisible={true}
+        offset={-16}
+      >
+        <div
+          className="flex items-center gap-1 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-lg shadow-md"
+          style={{ padding: Math.round(4 * scaleFactor) }}
+        >
+          <button
+            onClick={handleDocClick}
+            className="flex items-center justify-center rounded-md text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-accent))] hover:bg-[rgb(var(--ec-accent-subtle))] transition-colors"
+            style={{ width: buttonSize, height: buttonSize }}
+            title="View documentation"
+          >
+            <FileText style={{ width: iconSize, height: iconSize }} />
+          </button>
+        </div>
+      </NodeToolbar>
+    );
+  }
+
+  return (
+    <NodeToolbar
+      nodeId={node.id}
+      position={Position.Bottom}
+      isVisible={true}
+      offset={-16}
+    >
+      <div
+        className="flex items-center gap-1 bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border border-[rgb(var(--ec-page-border))] rounded-lg shadow-md"
+        style={{ padding: Math.round(4 * scaleFactor) }}
+      >
+        {docUrl && (
+          <button
+            onClick={handleDocClick}
+            className="flex items-center justify-center rounded-md text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-accent))] hover:bg-[rgb(var(--ec-accent-subtle))] transition-colors"
+            style={{ width: buttonSize, height: buttonSize }}
+            title="View documentation"
+          >
+            <FileText style={{ width: iconSize, height: iconSize }} />
+          </button>
+        )}
+        <button
+          onClick={handleSwitch}
+          className="flex items-center justify-center rounded-md text-[rgb(var(--ec-icon-color))] hover:text-[rgb(var(--ec-accent))] hover:bg-[rgb(var(--ec-accent-subtle))] transition-colors"
+          style={{ width: buttonSize, height: buttonSize }}
+          title="Focus on this node"
+        >
+          <ArrowRightLeft style={{ width: iconSize, height: iconSize }} />
+        </button>
+      </div>
+    </NodeToolbar>
+  );
+};
+
+export default FocusModeNodeActions;
diff --git a/packages/visualiser/src/components/FocusMode/FocusModePlaceholder.tsx b/packages/visualiser/src/components/FocusMode/FocusModePlaceholder.tsx
new file mode 100644
index 000000000..8a90acc68
--- /dev/null
+++ b/packages/visualiser/src/components/FocusMode/FocusModePlaceholder.tsx
@@ -0,0 +1,42 @@
+import React from "react";
+import { Handle, Position } from "@xyflow/react";
+
+interface FocusModePlaceholderProps {
+  data: {
+    label: string;
+    side: "left" | "right";
+  };
+}
+
+const FocusModePlaceholder: React.FC<FocusModePlaceholderProps> = ({
+  data,
+}) => {
+  const { label, side } = data;
+
+  return (
+    <div
+      className="px-4 py-4 rounded-lg border-2 border-dashed border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg)/0.5)] max-w-[280px] flex items-center justify-center"
+      style={{ opacity: 0.6, minHeight: "130px" }}
+    >
+      {side === "right" && (
+        <Handle
+          type="target"
+          position={Position.Left}
+          style={{ visibility: "hidden" }}
+        />
+      )}
+      <div className="text-center text-sm text-[rgb(var(--ec-page-text-muted))] italic">
+        {label}
+      </div>
+      {side === "left" && (
+        <Handle
+          type="source"
+          position={Position.Right}
+          style={{ visibility: "hidden" }}
+        />
+      )}
+    </div>
+  );
+};
+
+export default FocusModePlaceholder;
diff --git a/packages/visualiser/src/components/FocusMode/utils.ts b/packages/visualiser/src/components/FocusMode/utils.ts
new file mode 100644
index 000000000..3b1cd8d3c
--- /dev/null
+++ b/packages/visualiser/src/components/FocusMode/utils.ts
@@ -0,0 +1,240 @@
+import type { Node, Edge } from "@xyflow/react";
+
+export interface NodeDisplayInfo {
+  id: string;
+  name: string;
+  type: string;
+  version?: string;
+  description?: string;
+}
+
+export interface ConnectedNodes {
+  leftNodes: Node[];
+  rightNodes: Node[];
+}
+
+export const NODE_COLOR_CLASSES: Record<string, string> = {
+  events: "bg-orange-600",
+  agent: "bg-sky-600",
+  agents: "bg-sky-600",
+  agentTool: "bg-violet-600",
+  "agent-tool": "bg-violet-600",
+  services: "bg-pink-600",
+  flows: "bg-teal-600",
+  commands: "bg-blue-600",
+  queries: "bg-green-600",
+  channels: "bg-gray-600",
+  externalSystem: "bg-pink-600",
+  actor: "bg-yellow-500",
+  step: "bg-gray-700",
+  data: "bg-blue-600",
+  "data-products": "bg-indigo-600",
+  domains: "bg-yellow-600",
+  entities: "bg-purple-600",
+  field: "bg-cyan-600",
+  messageGroup: "bg-violet-600",
+  messageGroupExpanded: "bg-violet-600",
+};
+
+export const NODE_TYPE_LABELS: Record<string, string> = {
+  events: "Event",
+  agent: "Agent",
+  agents: "Agent",
+  agentTool: "Agent Tool",
+  "agent-tool": "Agent Tool",
+  services: "Service",
+  flows: "Flow",
+  commands: "Command",
+  queries: "Query",
+  channels: "Channel",
+  externalSystem: "External System",
+  actor: "Actor",
+  step: "Step",
+  data: "Data",
+  "data-products": "Data Product",
+  domains: "Domain",
+  entities: "Entity",
+  field: "Field",
+  messageGroup: "Message Group",
+  messageGroupExpanded: "Message Group",
+};
+
+/**
+ * Get connected nodes for a given center node
+ * Left nodes: incoming edges (they send TO this node)
+ * Right nodes: outgoing edges (this node sends TO them)
+ */
+export function getConnectedNodes(
+  centerNodeId: string,
+  nodes: Node[],
+  edges: Edge[],
+): ConnectedNodes {
+  const leftIds = new Set<string>();
+  const rightIds = new Set<string>();
+
+  edges.forEach((edge) => {
+    if (edge.target === centerNodeId) {
+      leftIds.add(edge.source);
+    }
+    if (edge.source === centerNodeId) {
+      rightIds.add(edge.target);
+    }
+  });
+
+  return {
+    leftNodes: nodes.filter((n) => leftIds.has(n.id)),
+    rightNodes: nodes.filter((n) => rightIds.has(n.id)),
+  };
+}
+
+// Entity keys that follow the standard data structure pattern
+const ENTITY_KEYS = [
+  "agent",
+  "service",
+  "message",
+  "flow",
+  "channel",
+  "domain",
+  "entity",
+  "dataProduct",
+  "agentTool",
+] as const;
+
+/**
+ * Extract display information from a ReactFlow node
+ */
+export function getNodeDisplayInfo(node: Node): NodeDisplayInfo {
+  const nodeType = node.type || "unknown";
+  const data = node.data as any;
+
+  // Handle field nodes
+  if (nodeType === "field") {
+    return {
+      id: node.id,
+      name: data?.name || node.id,
+      type: "field",
+      version: undefined,
+      description: `Type: ${data?.type || "unknown"}`,
+    };
+  }
+
+  // Handle message group nodes
+  if (nodeType === "messageGroup") {
+    return {
+      id: node.id,
+      name: data?.groupName || node.id,
+      type: "messageGroup",
+      version: undefined,
+      description: `${data?.messageCount || 0} messages (${data?.direction || "unknown"})`,
+    };
+  }
+
+  if (nodeType === "messageGroupExpanded") {
+    return {
+      id: node.id,
+      name: data?.groupName || node.id,
+      type: "messageGroupExpanded",
+      version: undefined,
+      description: `${data?.messageCount || 0} messages (expanded)`,
+    };
+  }
+
+  // Find the entity in data using standard keys
+  const entityKey = ENTITY_KEYS.find((key) => data[key]);
+  const entity = entityKey ? data[entityKey] : null;
+
+  const name =
+    entity?.data?.name || entity?.id || data.label || data.name || node.id;
+  const version =
+    entity?.data?.version || entity?.version || data.version || "";
+  const description =
+    entity?.data?.summary ||
+    entity?.data?.description ||
+    entity?.summary ||
+    entity?.description ||
+    data.summary ||
+    data.description ||
+    "";
+
+  return {
+    id: node.id,
+    name,
+    type: nodeType,
+    version,
+    description: description
+      ? truncateDescription(description, 100)
+      : undefined,
+  };
+}
+
+/**
+ * Truncate description to a max length
+ */
+function truncateDescription(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength).trim() + "...";
+}
+
+/**
+ * Get the color class for a node type
+ */
+export function getNodeColorClass(nodeType: string): string {
+  return NODE_COLOR_CLASSES[nodeType] || "bg-gray-500";
+}
+
+/**
+ * Get the display label for a node type
+ */
+export function getNodeTypeLabel(nodeType: string): string {
+  return NODE_TYPE_LABELS[nodeType] || nodeType;
+}
+
+// Mapping from entity key to doc path
+const DOC_PATH_MAP: Record<string, string> = {
+  service: "services",
+  agent: "agents",
+  flow: "flows",
+  channel: "channels",
+  domain: "domains",
+  entity: "entities",
+  dataProduct: "data-products",
+};
+
+/**
+ * Get the documentation URL for a node
+ */
+export function getNodeDocUrl(node: Node): string | null {
+  const nodeType = node.type || "unknown";
+  const data = node.data as any;
+
+  // Handle message type separately due to type mapping
+  if (data.message) {
+    const id = data.message.data?.id || data.message.id || "";
+    const version = data.message.data?.version || data.message.version || "";
+    const collectionType =
+      nodeType === "events"
+        ? "events"
+        : nodeType === "commands"
+          ? "commands"
+          : "queries";
+    return id && version ? `/docs/${collectionType}/${id}/${version}` : null;
+  }
+
+  // Handle data/container nodes with nested data.data structure
+  if (data.data && nodeType === "data") {
+    const id = data.data.id || "";
+    const version = data.data.version || "";
+    return id && version ? `/docs/containers/${id}/${version}` : null;
+  }
+
+  // Handle standard entity types
+  for (const [key, path] of Object.entries(DOC_PATH_MAP)) {
+    if (data[key]) {
+      const id = data[key].data?.id || data[key].id || "";
+      const version = data[key].data?.version || data[key].version || "";
+      return id && version ? `/docs/${path}/${id}/${version}` : null;
+    }
+  }
+
+  return null;
+}
diff --git a/packages/visualiser/src/components/FocusModeModal.tsx b/packages/visualiser/src/components/FocusModeModal.tsx
new file mode 100644
index 000000000..043db1960
--- /dev/null
+++ b/packages/visualiser/src/components/FocusModeModal.tsx
@@ -0,0 +1,204 @@
+import React, { useState, useCallback, useEffect } from "react";
+import * as Dialog from "@radix-ui/react-dialog";
+import { XIcon, FocusIcon } from "lucide-react";
+import { usePortalContainer } from "../context/PortalContainerContext";
+import {
+  ReactFlowProvider,
+  type Node,
+  type Edge,
+  type NodeTypes,
+  type EdgeTypes,
+} from "@xyflow/react";
+import FocusModeContent from "./FocusMode/FocusModeContent";
+import { getNodeDisplayInfo } from "./FocusMode/utils";
+import { useDarkMode } from "../nodes/shared-styles";
+
+interface FocusModeModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  initialNodeId: string | null;
+  nodes: Node[];
+  edges: Edge[];
+  nodeTypes: NodeTypes;
+  edgeTypes: EdgeTypes;
+}
+
+const FocusModeModal: React.FC<FocusModeModalProps> = ({
+  isOpen,
+  onClose,
+  initialNodeId,
+  nodes,
+  edges,
+  nodeTypes,
+  edgeTypes,
+}) => {
+  const [centerNodeId, setCenterNodeId] = useState<string | null>(
+    initialNodeId,
+  );
+  const isDark = useDarkMode();
+  const portalContainer = usePortalContainer();
+
+  // Reset center node when modal opens with new initial node
+  useEffect(() => {
+    if (isOpen && initialNodeId) {
+      setCenterNodeId(initialNodeId);
+    }
+  }, [isOpen, initialNodeId]);
+
+  const handleSwitchCenter = useCallback(
+    (newCenterNodeId: string, _direction: "left" | "right") => {
+      setCenterNodeId(newCenterNodeId);
+    },
+    [],
+  );
+
+  // Get center node info for title
+  const centerNode = centerNodeId
+    ? nodes.find((n) => n.id === centerNodeId)
+    : null;
+  const centerNodeInfo = centerNode ? getNodeDisplayInfo(centerNode) : null;
+
+  if (!centerNodeId) {
+    return null;
+  }
+
+  return (
+    <Dialog.Root open={isOpen} onOpenChange={(open) => !open && onClose()}>
+      <Dialog.Portal>
+        <div
+          className="eventcatalog-visualizer"
+          style={{
+            position: "fixed",
+            inset: 0,
+            isolation: "isolate",
+            zIndex: 99999,
+          }}
+        >
+          <Dialog.Overlay
+            style={{
+              position: "fixed",
+              inset: 0,
+              background: isDark
+                ? "rgba(0, 0, 0, 0.75)"
+                : "rgba(15, 23, 42, 0.55)",
+              backdropFilter: "blur(2px)",
+            }}
+          />
+          <Dialog.Content
+            style={{
+              position: "fixed",
+              inset: "5%",
+              borderRadius: 12,
+              background: isDark ? "#0f172a" : "#ffffff",
+              border: `1px solid ${
+                isDark ? "rgba(255,255,255,0.08)" : "rgba(0,0,0,0.08)"
+              }`,
+              boxShadow: isDark
+                ? "0 24px 48px rgba(0,0,0,0.5)"
+                : "0 24px 48px rgba(0,0,0,0.15)",
+              outline: "none",
+              display: "flex",
+              flexDirection: "column",
+              overflow: "hidden",
+            }}
+          >
+            {/* Header */}
+            <div
+              style={{
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "space-between",
+                padding: "1rem 1.5rem",
+                borderBottom: `1px solid ${
+                  isDark ? "rgba(255,255,255,0.08)" : "rgba(0,0,0,0.08)"
+                }`,
+                flexShrink: 0,
+              }}
+            >
+              <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
+                <div
+                  style={{
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    width: 40,
+                    height: 40,
+                    borderRadius: 10,
+                    background: isDark
+                      ? "rgba(59, 130, 246, 0.18)"
+                      : "rgba(59, 130, 246, 0.12)",
+                  }}
+                >
+                  <FocusIcon
+                    style={{
+                      width: 20,
+                      height: 20,
+                      color: isDark ? "#93c5fd" : "#2563eb",
+                    }}
+                  />
+                </div>
+                <div>
+                  <Dialog.Title
+                    style={{
+                      fontSize: 18,
+                      fontWeight: 600,
+                      color: isDark ? "#f8fafc" : "#0f172a",
+                    }}
+                  >
+                    Focus Mode
+                  </Dialog.Title>
+                  <Dialog.Description
+                    style={{
+                      marginTop: 2,
+                      fontSize: 14,
+                      color: isDark ? "#94a3b8" : "#475569",
+                    }}
+                  >
+                    {centerNodeInfo
+                      ? `Exploring: ${centerNodeInfo.name} - Click on connected nodes to navigate`
+                      : "Explore node connections"}
+                  </Dialog.Description>
+                </div>
+              </div>
+              <Dialog.Close asChild>
+                <button
+                  style={{
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    width: 40,
+                    height: 40,
+                    borderRadius: 10,
+                    border: "none",
+                    cursor: "pointer",
+                    background: "transparent",
+                    color: isDark ? "#94a3b8" : "#64748b",
+                  }}
+                  aria-label="Close"
+                >
+                  <XIcon style={{ width: 20, height: 20 }} />
+                </button>
+              </Dialog.Close>
+            </div>
+
+            {/* Content */}
+            <div style={{ flex: 1, overflow: "hidden" }}>
+              <ReactFlowProvider>
+                <FocusModeContent
+                  centerNodeId={centerNodeId}
+                  nodes={nodes}
+                  edges={edges}
+                  nodeTypes={nodeTypes}
+                  edgeTypes={edgeTypes}
+                  onSwitchCenter={handleSwitchCenter}
+                />
+              </ReactFlowProvider>
+            </div>
+          </Dialog.Content>
+        </div>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+};
+
+export default FocusModeModal;
diff --git a/packages/visualiser/src/components/MermaidView.tsx b/packages/visualiser/src/components/MermaidView.tsx
new file mode 100644
index 000000000..24fcaecde
--- /dev/null
+++ b/packages/visualiser/src/components/MermaidView.tsx
@@ -0,0 +1,270 @@
+import { useState, useEffect, useRef, useCallback } from "react";
+import { CheckIcon, ClipboardIcon } from "lucide-react";
+import type { Node, Edge } from "@xyflow/react";
+import { convertToMermaid } from "../utils/export-mermaid";
+import { copyToClipboard } from "../utils/clipboard";
+
+interface MermaidViewProps {
+  nodes: Node[];
+  edges: Edge[];
+  maxTextSize?: number;
+}
+
+const MermaidView = ({
+  nodes,
+  edges,
+  maxTextSize = 100000,
+}: MermaidViewProps) => {
+  const [copySuccess, setCopySuccess] = useState(false);
+  const [mermaidCode, setMermaidCode] = useState("");
+  const [previewSvg, setPreviewSvg] = useState<string | null>(null);
+  const [previewError, setPreviewError] = useState<string | null>(null);
+  const [isRendering, setIsRendering] = useState(true);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const svgContainerRef = useRef<HTMLDivElement>(null);
+  const panZoomInstanceRef = useRef<any>(null);
+
+  // Generate mermaid code
+  useEffect(() => {
+    const code = convertToMermaid(nodes, edges, {
+      includeStyles: true,
+      direction: "LR",
+    });
+    setMermaidCode(code);
+  }, [nodes, edges]);
+
+  // Render mermaid preview
+  useEffect(() => {
+    if (!mermaidCode) return;
+
+    let cancelled = false;
+    setIsRendering(true);
+    setPreviewError(null);
+
+    const renderMermaid = async () => {
+      try {
+        const { default: mermaid } = await import("mermaid");
+
+        // Detect current theme
+        const isDarkMode =
+          document.documentElement.getAttribute("data-theme") === "dark";
+        const currentTheme = isDarkMode ? "dark" : "default";
+
+        mermaid.initialize({
+          maxTextSize: maxTextSize,
+          startOnLoad: false,
+          theme: currentTheme,
+          flowchart: {
+            curve: "basis",
+            padding: 20,
+          },
+          securityLevel: "loose",
+        });
+
+        const id = "mermaid-view-" + Math.random().toString(36).substring(2, 9);
+        const { svg } = await mermaid.render(id, mermaidCode);
+
+        if (!cancelled) {
+          setPreviewSvg(svg);
+          setPreviewError(null);
+        }
+      } catch (error) {
+        if (!cancelled) {
+          console.error("Mermaid render error:", error);
+          setPreviewError(
+            error instanceof Error ? error.message : "Failed to render diagram",
+          );
+          setPreviewSvg(null);
+        }
+      } finally {
+        if (!cancelled) {
+          setIsRendering(false);
+        }
+      }
+    };
+
+    renderMermaid();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [mermaidCode]);
+
+  // Initialize pan/zoom after SVG is rendered
+  useEffect(() => {
+    if (!previewSvg || !svgContainerRef.current) return;
+
+    const initZoom = async () => {
+      const svgElement = svgContainerRef.current?.querySelector("svg");
+      if (!svgElement) return;
+
+      try {
+        const { default: svgPanZoom } = await import("svg-pan-zoom");
+
+        // Set SVG to fill container
+        svgElement.style.width = "100%";
+        svgElement.style.height = "100%";
+        svgElement.removeAttribute("height");
+        svgElement.removeAttribute("width");
+
+        const instance = svgPanZoom(svgElement, {
+          zoomEnabled: true,
+          controlIconsEnabled: false,
+          fit: true,
+          center: true,
+          minZoom: 0.1,
+          maxZoom: 10,
+          zoomScaleSensitivity: 0.15,
+          dblClickZoomEnabled: true,
+          mouseWheelZoomEnabled: true,
+          panEnabled: true,
+        });
+
+        panZoomInstanceRef.current = instance;
+      } catch (e) {
+        console.warn("Failed to initialize zoom:", e);
+      }
+    };
+
+    initZoom();
+
+    return () => {
+      if (panZoomInstanceRef.current) {
+        try {
+          panZoomInstanceRef.current.destroy();
+        } catch (e) {
+          // Ignore
+        }
+        panZoomInstanceRef.current = null;
+      }
+    };
+  }, [previewSvg]);
+
+  const handleCopyToClipboard = useCallback(async () => {
+    await copyToClipboard(mermaidCode);
+    setCopySuccess(true);
+    setTimeout(() => setCopySuccess(false), 2000);
+  }, [mermaidCode]);
+
+  return (
+    <div
+      ref={containerRef}
+      className="absolute inset-0 bg-[rgb(var(--ec-page-bg))]"
+      style={{ animation: "fadeIn 200ms ease-out" }}
+    >
+      <style>{`
+        @keyframes fadeIn {
+          from { opacity: 0; }
+          to { opacity: 1; }
+        }
+      `}</style>
+
+      {/* Copy button - top right */}
+      <div className="absolute top-[10px] right-4 z-20">
+        <div className="relative group">
+          <button
+            onClick={handleCopyToClipboard}
+            className={`p-2.5 rounded-md shadow-md focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-[rgb(var(--ec-accent))] transition-all duration-150 ${
+              copySuccess
+                ? "bg-green-500 text-white scale-110"
+                : "bg-[rgb(var(--ec-card-bg))] hover:bg-[rgb(var(--ec-page-border))/0.5] text-[rgb(var(--ec-icon-color))] hover:scale-105"
+            }`}
+            aria-label={copySuccess ? "Copied!" : "Copy Mermaid code"}
+          >
+            {copySuccess ? (
+              <CheckIcon className="h-5 w-5" />
+            ) : (
+              <ClipboardIcon className="h-5 w-5" />
+            )}
+          </button>
+          <div className="absolute top-full right-0 mt-2 px-2 py-1 bg-[rgb(var(--ec-page-text))] text-[rgb(var(--ec-page-bg))] text-xs rounded shadow-lg opacity-0 group-hover:opacity-100 transition-opacity whitespace-nowrap pointer-events-none z-50">
+            {copySuccess ? "Copied!" : "Copy Mermaid code"}
+          </div>
+        </div>
+      </div>
+
+      {/* Mermaid diagram container */}
+      <div className="absolute inset-0 overflow-hidden">
+        {isRendering && (
+          <div className="w-full h-full flex items-center justify-center">
+            <div className="relative">
+              <div className="flex items-center gap-4 opacity-40">
+                <div className="w-24 h-10 bg-[rgb(var(--ec-page-border))] rounded animate-pulse" />
+                <div className="w-12 h-0.5 bg-[rgb(var(--ec-page-border))] animate-pulse" />
+                <div
+                  className="w-20 h-10 bg-[rgb(var(--ec-page-border))] rounded-full animate-pulse"
+                  style={{ animationDelay: "75ms" }}
+                />
+                <div
+                  className="w-12 h-0.5 bg-[rgb(var(--ec-page-border))] animate-pulse"
+                  style={{ animationDelay: "150ms" }}
+                />
+                <div
+                  className="w-24 h-10 bg-[rgb(var(--ec-page-border))] rounded animate-pulse"
+                  style={{ animationDelay: "225ms" }}
+                />
+              </div>
+              <p className="text-center text-sm text-[rgb(var(--ec-page-text-muted))] mt-4">
+                Rendering diagram...
+              </p>
+            </div>
+          </div>
+        )}
+
+        {previewError && !isRendering && (
+          <div className="w-full h-full flex flex-col items-center justify-center p-4">
+            <div className="text-red-500 text-sm mb-2">
+              Failed to render diagram
+            </div>
+            <div className="text-[rgb(var(--ec-page-text-muted))] text-xs font-mono bg-[rgb(var(--ec-code-bg))] p-2 rounded max-w-lg overflow-auto">
+              {previewError}
+            </div>
+            <div className="mt-4 text-sm text-[rgb(var(--ec-page-text-muted))]">
+              <p>You can still copy the Mermaid code and paste it into</p>
+              <a
+                href="https://mermaid.live"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-[rgb(var(--ec-accent))] hover:underline"
+              >
+                mermaid.live
+              </a>
+            </div>
+          </div>
+        )}
+
+        {previewSvg && !isRendering && !previewError && (
+          <div
+            ref={svgContainerRef}
+            className="w-full h-full cursor-grab active:cursor-grabbing [&_svg]:w-full [&_svg]:h-full"
+            dangerouslySetInnerHTML={{ __html: previewSvg }}
+          />
+        )}
+      </div>
+
+      {/* Footer hint */}
+      <div className="absolute bottom-4 left-4 z-20">
+        <div className="flex items-center gap-2 bg-[rgb(var(--ec-card-bg))]/90 backdrop-blur-sm px-3 py-1.5 rounded-md shadow-sm border border-[rgb(var(--ec-page-border))]">
+          <svg
+            className="w-3.5 h-3.5 text-[rgb(var(--ec-icon-color))]"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M15 15l-2 5L9 9l11 4-5 2zm0 0l5 5M7.188 2.239l.777 2.897M5.136 7.965l-2.898-.777M13.95 4.05l-2.122 2.122m-5.657 5.656l-2.12 2.122"
+            />
+          </svg>
+          <span className="text-xs text-[rgb(var(--ec-page-text-muted))]">
+            Scroll to zoom · Drag to pan
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default MermaidView;
diff --git a/packages/visualiser/src/components/NodeContextMenu.tsx b/packages/visualiser/src/components/NodeContextMenu.tsx
new file mode 100644
index 000000000..9c3367d90
--- /dev/null
+++ b/packages/visualiser/src/components/NodeContextMenu.tsx
@@ -0,0 +1,52 @@
+import { memo } from "react";
+import * as ContextMenu from "@radix-ui/react-context-menu";
+import { usePortalContainer } from "../context/PortalContainerContext";
+import type { ContextMenuItem } from "../types";
+
+interface NodeContextMenuProps {
+  items: ContextMenuItem[];
+  children: React.ReactNode;
+}
+
+export default memo(function NodeContextMenu({
+  items,
+  children,
+}: NodeContextMenuProps) {
+  const portalContainer = usePortalContainer();
+
+  if (!items || items.length === 0) return <>{children}</>;
+
+  return (
+    <ContextMenu.Root>
+      <ContextMenu.Trigger>{children}</ContextMenu.Trigger>
+      <ContextMenu.Portal container={portalContainer}>
+        <ContextMenu.Content
+          className="min-w-[220px] bg-white rounded-md p-1 shadow-md border border-gray-200 z-50"
+          onClick={(e) => e.stopPropagation()}
+        >
+          {items.map((item, index) => (
+            <div key={index}>
+              {item.separator && index > 0 && (
+                <ContextMenu.Separator className="h-[1px] bg-gray-200 m-1" />
+              )}
+              <ContextMenu.Item
+                asChild
+                className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center text-gray-900 hover:text-gray-900 visited:text-gray-900 no-underline hover:no-underline visited:no-underline"
+              >
+                <a
+                  href={item.href}
+                  {...(item.download ? { download: item.download } : {})}
+                  {...(item.external
+                    ? { target: "_blank", rel: "noopener noreferrer" }
+                    : {})}
+                >
+                  {item.label}
+                </a>
+              </ContextMenu.Item>
+            </div>
+          ))}
+        </ContextMenu.Content>
+      </ContextMenu.Portal>
+    </ContextMenu.Root>
+  );
+});
diff --git a/packages/visualiser/src/components/NodeGraph.tsx b/packages/visualiser/src/components/NodeGraph.tsx
new file mode 100644
index 000000000..a5e0b177e
--- /dev/null
+++ b/packages/visualiser/src/components/NodeGraph.tsx
@@ -0,0 +1,2860 @@
+import {
+  useEffect,
+  useMemo,
+  useState,
+  useCallback,
+  useRef,
+  memo,
+  type RefObject,
+} from "react";
+import { createPortal } from "react-dom";
+import {
+  ReactFlow,
+  Background,
+  ConnectionLineType,
+  Controls,
+  Panel,
+  MiniMap,
+  ReactFlowProvider,
+  useNodesState,
+  useEdgesState,
+  type Edge,
+  type Node,
+  type NodeChange,
+  useReactFlow,
+  useStoreApi,
+  getNodesBounds,
+  type NodeTypes,
+  MarkerType,
+} from "@xyflow/react";
+// Styles are provided via styles.css / styles-core.css entry points.
+// Do NOT import CSS here — it breaks SSR (Node cannot load .css files).
+import {
+  ExternalLink,
+  HistoryIcon,
+  CheckIcon,
+  ClipboardIcon,
+  MoreVertical,
+  Zap,
+  Bot,
+  Wrench,
+  ServerIcon,
+  Workflow,
+  MessageSquare,
+  Search as SearchIcon,
+  ArrowLeftRight,
+  Group as GroupIcon,
+  Globe,
+  User,
+  Database,
+  Boxes,
+  Box,
+  type LucideIcon,
+} from "lucide-react";
+import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
+import { toPng } from "html-to-image";
+// Nodes and edges
+// Studio-2 nodes (named exports from directories)
+import { Service as ServiceNode } from "../nodes/service";
+import AgentNode from "../nodes/Agent";
+import AgentToolNode from "../nodes/AgentTool";
+import { Event as EventNode } from "../nodes/event";
+import { Query as QueryNode } from "../nodes/query";
+import { Command as CommandNode } from "../nodes/command";
+import { Channel as ChannelNode } from "../nodes/channel";
+import { Data as DataNode } from "../nodes/data";
+import { View as ViewNode } from "../nodes/view";
+import { Actor as ActorNode } from "../nodes/actor";
+import ContextActorNode from "../nodes/ContextActor";
+import SystemGroupNode from "../nodes/SystemGroupNode";
+import { ExternalSystem as ExternalSystemNode } from "../nodes/external-system";
+import { Note as NoteNode } from "../nodes/note";
+import { Field as FieldNode } from "../nodes/field";
+// Core nodes (default exports from flat files)
+import FlowNode from "../nodes/Flow";
+import FlowExpandedNode from "../nodes/FlowExpandedNode";
+import EntityNode from "../nodes/Entity";
+import UserNode from "../nodes/User";
+import StepNode from "../nodes/Step";
+import DomainNode from "../nodes/Domain";
+import SystemNode from "../nodes/System";
+import GroupNode from "../nodes/GroupNode";
+import CustomNode from "../nodes/Custom";
+import ExternalSystemNode2 from "../nodes/ExternalSystem2";
+import DataProductNode from "../nodes/DataProduct";
+import {
+  MessageGroupNode,
+  MessageGroupExpandedNode,
+} from "../nodes/message-group";
+// Edges
+import AnimatedMessageEdge from "../edges/AnimatedMessageEdge";
+import MultilineEdgeLabel from "../edges/MultilineEdgeLabel";
+import FlowEdge from "../edges/FlowEdge";
+import VisualiserSearch, { type VisualiserSearchRef } from "./VisualiserSearch";
+import StepWalkthrough from "./StepWalkthrough";
+import StudioModal from "./StudioModal";
+import FocusModeModal from "./FocusModeModal";
+import MermaidView from "./MermaidView";
+import { useChannelVisibility } from "../hooks/use-channel-visibility";
+import VisualizerDropdownContent from "./VisualizerDropdownContent";
+import NodeContextMenu from "./NodeContextMenu";
+import { convertToMermaid } from "../utils/export-mermaid";
+import {
+  getExportImageDimensions,
+  injectExportStyles,
+} from "../utils/export-image";
+import { copyToClipboard } from "../utils/clipboard";
+import { layoutGraph } from "../utils/layout";
+import { packNodesAroundBounds } from "../utils/local-packing";
+import {
+  buildMessageGroupExpansionNodes,
+  getExpandedMessageGroupNode,
+} from "../utils/message-group-expansion";
+import { AllNotesModal, getNotesFromNode } from "./NotesToolbarButton";
+import { setBuildUrlFn } from "../utils/url-builder";
+import { PortalContainerProvider } from "../context/PortalContainerContext";
+import type { DslGraph } from "../types";
+import dagre from "dagre";
+
+// Minimum pixel change to detect layout modifications (avoids floating point comparison issues)
+const POSITION_CHANGE_THRESHOLD = 1;
+
+// Above this node count, auto-disable message animation when the user has no stored preference
+const LARGE_GRAPH_NODE_THRESHOLD = 30;
+
+// Static props for ReactFlow - defined outside component to avoid new references on every render
+const NODE_ORIGIN: [number, number] = [0.1, 0.1];
+const MINIMAP_STYLE = {
+  backgroundColor: "rgb(var(--ec-page-bg))",
+  border: "1px solid rgb(var(--ec-page-border))",
+  borderRadius: "8px",
+} as const;
+const LAYOUT_CHANGE_PANEL_STYLE_WITH_WALKTHROUGH = {
+  marginBottom: "20px",
+  marginLeft: "420px",
+} as const;
+const LAYOUT_CHANGE_PANEL_STYLE_DEFAULT = { marginLeft: "60px" } as const;
+const LEGEND_PANEL_STYLE_WITH_MINIMAP = { marginRight: "230px" } as const;
+
+// Expanded wrapper containers are structural only — they host grouped/inlined
+// child nodes and never represent a business step themselves. Centralised so
+// the walkthrough, click handler, and collapse handler agree on the set.
+const EXPANDED_WRAPPER_TYPES = new Set([
+  "flowExpanded",
+  "messageGroupExpanded",
+]);
+const isExpandedWrapper = (type: string | undefined) =>
+  type != null && EXPANDED_WRAPPER_TYPES.has(type);
+
+type LegendEntry = { count: number; colorClass: string; groupId?: string };
+
+// Friendly labels for legend keys that differ from their raw node type.
+const LEGEND_LABELS: Record<string, string> = {
+  "context-actor": "Actors",
+};
+
+const getLegendLabel = (key: string) => LEGEND_LABELS[key] ?? key;
+
+// Icon + text colour per legend key, mirroring each collection's node styling.
+// When a key has no icon mapped, the legend falls back to its coloured square.
+const LEGEND_ICONS: Record<string, { Icon: LucideIcon; colorClass: string }> = {
+  events: { Icon: Zap, colorClass: "text-orange-600" },
+  agent: { Icon: Bot, colorClass: "text-sky-600" },
+  agents: { Icon: Bot, colorClass: "text-sky-600" },
+  agentTool: { Icon: Wrench, colorClass: "text-violet-600" },
+  "agent-tool": { Icon: Wrench, colorClass: "text-violet-600" },
+  services: { Icon: ServerIcon, colorClass: "text-pink-600" },
+  flows: { Icon: Workflow, colorClass: "text-teal-600" },
+  commands: { Icon: MessageSquare, colorClass: "text-blue-600" },
+  queries: { Icon: SearchIcon, colorClass: "text-green-600" },
+  channels: { Icon: ArrowLeftRight, colorClass: "text-gray-600" },
+  externalSystem: { Icon: Globe, colorClass: "text-pink-600" },
+  systems: { Icon: GroupIcon, colorClass: "text-purple-600" },
+  system: { Icon: GroupIcon, colorClass: "text-purple-600" },
+  actor: { Icon: User, colorClass: "text-yellow-500" },
+  "context-actor": { Icon: User, colorClass: "text-yellow-500" },
+  data: { Icon: Database, colorClass: "text-blue-600" },
+  "data-products": { Icon: Boxes, colorClass: "text-indigo-600" },
+  field: { Icon: Box, colorClass: "text-cyan-600" },
+};
+
+const getLegendIcon = (key: string) => LEGEND_ICONS[key];
+
+const LegendPanel = memo(function LegendPanel({
+  legend,
+  showMinimap,
+  onLegendClick,
+}: {
+  legend: Record<string, LegendEntry>;
+  showMinimap: boolean;
+  onLegendClick: (key: string, groupId?: string) => void;
+}) {
+  return (
+    <Panel
+      position="bottom-right"
+      style={showMinimap ? LEGEND_PANEL_STYLE_WITH_MINIMAP : undefined}
+    >
+      <div className="bg-[rgb(var(--ec-card-bg))] border border-[rgb(var(--ec-page-border))] font-light px-4 text-[12px] shadow-md py-1 rounded-md">
+        <ul className="m-0 p-0 ">
+          {Object.entries(legend).map(
+            ([key, { count, colorClass, groupId }]) => {
+              const legendIcon = getLegendIcon(key);
+              return (
+                <li
+                  key={key}
+                  className="flex space-x-2 items-center text-[10px] cursor-pointer text-[rgb(var(--ec-page-text))] hover:text-[rgb(var(--ec-accent))] hover:underline"
+                  onClick={() => onLegendClick(key, groupId)}
+                >
+                  {legendIcon ? (
+                    <legendIcon.Icon
+                      className={`w-3 h-3 shrink-0 ${legendIcon.colorClass}`}
+                      strokeWidth={2}
+                      aria-hidden="true"
+                    />
+                  ) : (
+                    <span className={`w-2 h-2 block ${colorClass}`} />
+                  )}
+                  <span className="block capitalize">
+                    {getLegendLabel(key)} ({count})
+                  </span>
+                </li>
+              );
+            },
+          )}
+        </ul>
+      </div>
+    </Panel>
+  );
+});
+
+interface Props {
+  nodes: any;
+  edges: any;
+  title?: string;
+  subtitle?: string;
+  includeBackground?: boolean;
+  includeControls?: boolean;
+  linkTo?: "docs" | "visualiser";
+  includeKey?: boolean;
+  linksToVisualiser?: boolean;
+  links?: { label: string; url: string }[];
+  mode?: "full" | "simple";
+  showFlowWalkthrough?: boolean;
+  showSearch?: boolean;
+  zoomOnScroll?: boolean;
+  designId?: string;
+  isStudioModalOpen?: boolean;
+  setIsStudioModalOpen?: (isOpen: boolean) => void;
+  isChatEnabled?: boolean;
+  maxTextSize?: number;
+  isDevMode?: boolean;
+  resourceKey?: string;
+  /** Controls whether message flow animation is enabled. When set, overrides URL params and localStorage. */
+  animated?: boolean;
+  /**
+   * When true, message-flow animation is unsupported for this graph: it is forced
+   * off (ignoring the `animated` prop, URL params and localStorage) and the
+   * "Simulate Messages" toggle is hidden. Used by graphs that aren't message
+   * flows, e.g. the System Diagram.
+   */
+  disableMessageAnimation?: boolean;
+  /** When set, the graph will zoom to this node id. */
+  focusNodeId?: string;
+  /** Optional token to force repeated focus for the same node id. */
+  focusRequestId?: number;
+  /** Optional token to trigger fit-to-screen behavior. */
+  fitRequestId?: number;
+
+  // Callback API for framework integration
+  /** Called when a node is clicked */
+  onNodeClick?: (node: Node) => void;
+  /** Called to build URLs for navigation (used in links dropdown) */
+  onBuildUrl?: (path: string) => string;
+  /** Called when navigation should occur */
+  onNavigate?: (url: string) => void;
+  /** Called to save layout positions (dev mode only) */
+  onSaveLayout?: (
+    resourceKey: string,
+    positions: Record<string, { x: number; y: number }>,
+  ) => Promise<boolean>;
+  /** Called to reset layout positions (dev mode only) */
+  onResetLayout?: (resourceKey: string) => Promise<boolean>;
+}
+
+// --- Shared edge style for group expand edges ---
+const GROUP_EDGE_STYLE = {
+  strokeWidth: 1,
+  stroke: "var(--ec-edge-stroke, #6b7280)",
+};
+const GROUP_EDGE_MARKER = {
+  type: MarkerType.ArrowClosed,
+  width: 20,
+  height: 20,
+};
+
+/** Label for the edge connecting the service to a message, based on direction and collection type. */
+const getChildEdgeLabel = (
+  direction: "sends" | "receives",
+  collection: string,
+) => {
+  if (direction === "sends") {
+    if (collection === "commands") return "invokes";
+    if (collection === "queries") return "requests";
+    return "publishes \nevent";
+  }
+  if (collection === "commands" || collection === "queries") return "accepts";
+  return "subscribed by";
+};
+
+/**
+ * Check if a message can reach the service through downstream edges (i.e. via channels).
+ * Uses BFS over the pre-computed edge graph. If reachable, no direct child→service edge is needed.
+ */
+const canReachService = (
+  msgId: string,
+  serviceNodeId: string,
+  expandedEdges: any[],
+): boolean => {
+  // Build adjacency list once for efficient traversal
+  const adj = new Map<string, string[]>();
+  for (const e of expandedEdges) {
+    if (!adj.has(e.source)) adj.set(e.source, []);
+    adj.get(e.source)!.push(e.target);
+  }
+  const visited = new Set<string>([msgId]);
+  const queue = [msgId];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    for (const next of adj.get(current) || []) {
+      if (next === serviceNodeId) return true;
+      if (!visited.has(next)) {
+        visited.add(next);
+        queue.push(next);
+      }
+    }
+  }
+  return false;
+};
+
+/**
+ * Build edges connecting the service to child message nodes inside an expanded group.
+ * - For sends: always creates service → child edge.
+ * - For receives: only creates child → service edge when no channel path exists.
+ */
+const buildChildEdges = (
+  groupData: any,
+  groupNodeId: string,
+  serviceNodeId: string,
+  msgIdToChildId: Map<string, string>,
+  animateMessages: boolean,
+): Edge[] => {
+  const expandedEdges = groupData.expandedEdges || [];
+
+  return (groupData.messages || [])
+    .map((item: any) => {
+      const msg = item.message;
+      const msgId = `${msg.data.id}-${msg.data.version}`;
+      const childId = msgIdToChildId.get(msgId)!;
+      const collection = msg.collection || "events";
+      const label = getChildEdgeLabel(groupData.direction, collection);
+
+      if (groupData.direction === "sends") {
+        return {
+          id: `${serviceNodeId}-to-${childId}`,
+          source: serviceNodeId,
+          target: childId,
+          label,
+          type: "animated",
+          animated: animateMessages,
+          style: GROUP_EDGE_STYLE,
+          markerEnd: GROUP_EDGE_MARKER,
+        } as Edge;
+      }
+
+      // Receives: skip if a channel path already connects this message to the service
+      if (canReachService(msgId, serviceNodeId, expandedEdges)) return null;
+
+      return {
+        id: `${childId}-to-${serviceNodeId}`,
+        source: childId,
+        target: serviceNodeId,
+        label,
+        type: "animated",
+        animated: animateMessages,
+        style: GROUP_EDGE_STYLE,
+        markerEnd: GROUP_EDGE_MARKER,
+      } as Edge;
+    })
+    .filter(Boolean) as Edge[];
+};
+
+const NodeGraphBuilder = ({
+  nodes: initialNodes,
+  edges: initialEdges,
+  title,
+  includeBackground = true,
+  linkTo: _linkTo = "docs",
+  includeKey = true,
+  linksToVisualiser = false,
+  links = [],
+  mode = "full",
+  showFlowWalkthrough = true,
+  showSearch = true,
+  zoomOnScroll = false,
+  isStudioModalOpen,
+  setIsStudioModalOpen = () => {},
+  isChatEnabled = false,
+  maxTextSize,
+  isDevMode = false,
+  resourceKey,
+  animated,
+  disableMessageAnimation = false,
+  focusNodeId,
+  focusRequestId,
+  fitRequestId,
+  onNodeClick,
+  onBuildUrl,
+  onNavigate,
+  onSaveLayout,
+  onResetLayout,
+}: Props) => {
+  // Wire up the URL builder so all nodes can use buildUrl() with the correct base path
+  useEffect(() => {
+    if (onBuildUrl) {
+      setBuildUrlFn(onBuildUrl);
+    }
+  }, []);
+
+  const nodeTypes = useMemo(() => {
+    const wrapWithContextMenu = (Component: React.ComponentType<any>) => {
+      const Wrapped = memo((props: any) => {
+        const items = props.data?.contextMenu;
+        if (!items?.length) return <Component {...props} />;
+        return (
+          <NodeContextMenu items={items}>
+            <Component {...props} />
+          </NodeContextMenu>
+        );
+      });
+      Wrapped.displayName = `WithContextMenu(${Component.displayName || Component.name || "Component"})`;
+      return Wrapped;
+    };
+
+    return {
+      service: wrapWithContextMenu(ServiceNode),
+      services: wrapWithContextMenu(ServiceNode),
+      agent: wrapWithContextMenu(AgentNode),
+      agents: wrapWithContextMenu(AgentNode),
+      agentTool: wrapWithContextMenu(AgentToolNode),
+      "agent-tool": wrapWithContextMenu(AgentToolNode),
+      flow: wrapWithContextMenu(FlowNode),
+      flows: wrapWithContextMenu(FlowNode),
+      event: wrapWithContextMenu(EventNode),
+      events: wrapWithContextMenu(EventNode),
+      channel: wrapWithContextMenu(ChannelNode),
+      channels: wrapWithContextMenu(ChannelNode),
+      query: wrapWithContextMenu(QueryNode),
+      queries: wrapWithContextMenu(QueryNode),
+      command: wrapWithContextMenu(CommandNode),
+      commands: wrapWithContextMenu(CommandNode),
+      domain: wrapWithContextMenu(DomainNode),
+      domains: wrapWithContextMenu(DomainNode),
+      system: wrapWithContextMenu(SystemNode),
+      systems: wrapWithContextMenu(SystemNode),
+      step: StepNode,
+      user: UserNode,
+      custom: CustomNode,
+      externalSystem: wrapWithContextMenu(ExternalSystemNode),
+      "external-system": wrapWithContextMenu(ExternalSystemNode2),
+      entity: wrapWithContextMenu(EntityNode),
+      entities: wrapWithContextMenu(EntityNode),
+      data: wrapWithContextMenu(DataNode),
+      view: wrapWithContextMenu(ViewNode),
+      actor: ActorNode,
+      "context-actor": ContextActorNode,
+      container: wrapWithContextMenu(DataNode),
+      "data-product": wrapWithContextMenu(DataProductNode),
+      "data-products": wrapWithContextMenu(DataProductNode),
+      group: GroupNode,
+      "system-group": SystemGroupNode,
+      note: memo((props: any) => <NoteNode {...props} readOnly={true} />),
+      field: wrapWithContextMenu(FieldNode),
+      messageGroup: MessageGroupNode,
+      messageGroupExpanded: MessageGroupExpandedNode,
+      flowExpanded: FlowExpandedNode,
+    } as unknown as NodeTypes;
+  }, []);
+  const edgeTypes = useMemo(
+    () =>
+      ({
+        animated: AnimatedMessageEdge,
+        multiline: MultilineEdgeLabel,
+        "flow-edge": FlowEdge,
+      }) as Record<string, any>,
+    [],
+  );
+  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
+  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);
+  const { fitView, getNodes, getIntersectingNodes, getZoom, setCenter } =
+    useReactFlow();
+  const storeApi = useStoreApi();
+
+  // Sync when parent passes new nodes/edges (e.g. playground re-parse)
+  useEffect(() => {
+    setNodes(initialNodes);
+    setEdges(initialEdges);
+    // fitView after React Flow processes the new nodes
+    requestAnimationFrame(() => {
+      fitView({ duration: 300, padding: 0.2 });
+    });
+  }, [initialNodes, initialEdges, setNodes, setEdges, fitView]);
+
+  const [animateMessages, setAnimateMessages] = useState(true);
+  const [_activeStepIndex, _setActiveStepIndex] = useState<number | null>(null);
+  const [_isFullscreen, _setIsFullscreen] = useState(false);
+  const [isShareModalOpen, setIsShareModalOpen] = useState(false);
+  const [shareUrlCopySuccess, setShareUrlCopySuccess] = useState(false);
+  const [isMermaidView, setIsMermaidView] = useState(false);
+  const [showMinimap, setShowMinimap] = useState(false);
+  const [hasLayoutChanges, setHasLayoutChanges] = useState(false);
+  const [isSavingLayout, setIsSavingLayout] = useState(false);
+  const initialPositionsRef = useRef<Record<string, { x: number; y: number }>>(
+    {},
+  );
+  // const [isStudioModalOpen, setIsStudioModalOpen] = useState(false);
+  const [focusModeOpen, setFocusModeOpen] = useState(false);
+  const [focusedNodeId, setFocusedNodeId] = useState<string | null>(null);
+
+  const [isNotesModalOpen, setIsNotesModalOpen] = useState(false);
+  const openNotesModal = useCallback(() => setIsNotesModalOpen(true), []);
+
+  // Track user interaction (drag/pan/zoom) to pause expensive SVG animations.
+  // Uses a ref + direct DOM manipulation to avoid React re-renders.
+  const interactionCountRef = useRef(0);
+
+  const startInteraction = useCallback(() => {
+    interactionCountRef.current += 1;
+    if (interactionCountRef.current === 1) {
+      reactFlowWrapperRef.current?.classList.add("ec-interaction-active");
+    }
+  }, []);
+
+  const endInteraction = useCallback(() => {
+    interactionCountRef.current = Math.max(0, interactionCountRef.current - 1);
+    if (interactionCountRef.current === 0) {
+      reactFlowWrapperRef.current?.classList.remove("ec-interaction-active");
+    }
+  }, []);
+
+  // Highlight source/target nodes when hovering an edge.
+  // Uses direct DOM manipulation (like startInteraction) to avoid re-renders.
+  const hoveredEdgeNodesRef = useRef<Element[]>([]);
+
+  const handleEdgeMouseEnter = useCallback(
+    (_: React.MouseEvent, edge: Edge) => {
+      const wrapper = reactFlowWrapperRef.current;
+      if (!wrapper) return;
+      const nodes = wrapper.querySelectorAll(
+        `[data-id="${edge.source}"], [data-id="${edge.target}"]`,
+      );
+      nodes.forEach((el) => el.classList.add("ec-edge-hover-node"));
+      hoveredEdgeNodesRef.current = Array.from(nodes);
+    },
+    [],
+  );
+
+  const handleEdgeMouseLeave = useCallback(() => {
+    hoveredEdgeNodesRef.current.forEach((el) =>
+      el.classList.remove("ec-edge-hover-node"),
+    );
+    hoveredEdgeNodesRef.current = [];
+  }, []);
+
+  // Highlight all connected edges + their other-end nodes when hovering a node.
+  // Looks up connected edges from the edges array, then queries DOM by edge ID.
+  // Uses direct DOM manipulation to avoid re-renders.
+  const hoveredNodeEdgesRef = useRef<Element[]>([]);
+  const hoveredNodePeersRef = useRef<Element[]>([]);
+
+  const handleNodeMouseEnter = useCallback(
+    (_: React.MouseEvent, node: Node) => {
+      const wrapper = reactFlowWrapperRef.current;
+      if (!wrapper) return;
+
+      const peerIds = new Set<string>();
+      const edgeEls: Element[] = [];
+
+      for (const edge of edgesRef.current) {
+        if (edge.source !== node.id && edge.target !== node.id) continue;
+        const el = wrapper.querySelector(
+          `.react-flow__edge[data-id="${edge.id}"]`,
+        );
+        if (el) {
+          el.classList.add("ec-node-hover-edge");
+          edgeEls.push(el);
+        }
+        if (edge.source !== node.id) peerIds.add(edge.source);
+        if (edge.target !== node.id) peerIds.add(edge.target);
+      }
+      hoveredNodeEdgesRef.current = edgeEls;
+
+      // Highlight the hovered node + all peer nodes
+      peerIds.add(node.id);
+      const selector = Array.from(peerIds)
+        .map((id) => `[data-id="${id}"]`)
+        .join(", ");
+      if (selector) {
+        const peerEls = wrapper.querySelectorAll(selector);
+        peerEls.forEach((el) => el.classList.add("ec-edge-hover-node"));
+        hoveredNodePeersRef.current = Array.from(peerEls);
+      }
+    },
+    [],
+  );
+
+  const handleNodeMouseLeave = useCallback(() => {
+    hoveredNodeEdgesRef.current.forEach((el) =>
+      el.classList.remove("ec-node-hover-edge"),
+    );
+    hoveredNodeEdgesRef.current = [];
+    hoveredNodePeersRef.current.forEach((el) =>
+      el.classList.remove("ec-edge-hover-node"),
+    );
+    hoveredNodePeersRef.current = [];
+  }, []);
+
+  // Check if there are channels to determine if we need the visualizer functionality
+  const hasChannels = useMemo(
+    () => initialNodes.some((node: any) => node.type === "channels"),
+    [initialNodes],
+  );
+  const { hideChannels, toggleChannelsVisibility } = useChannelVisibility({
+    nodes,
+    edges,
+    setNodes,
+    setEdges,
+    skipProcessing: !hasChannels,
+  });
+  const searchRef = useRef<VisualiserSearchRef>(null);
+  const reactFlowWrapperRef = useRef<HTMLDivElement>(null);
+  const scrollableContainerRef = useRef<HTMLElement | null>(null);
+
+  // Stable refs — avoids recreating callbacks on every drag/state change
+  const nodesRef = useRef(nodes);
+  nodesRef.current = nodes;
+  const edgesRef = useRef(edges);
+  edgesRef.current = edges;
+  const hideChannelsRef = useRef(hideChannels);
+  hideChannelsRef.current = hideChannels;
+
+  // The walkthrough treats expanded wrapper containers as structural rather
+  // than walkable steps. Stitched predecessor/successor edges added at expand
+  // time already connect real outer steps to the sub-flow's children, so
+  // dropping wrapper edges doesn't break traversal.
+  const wrapperNodeIds = useMemo(() => {
+    const ids = new Set<string>();
+    nodes.forEach((n) => {
+      if (isExpandedWrapper(n.type)) ids.add(n.id);
+    });
+    return ids;
+  }, [nodes]);
+  const walkthroughNodes = useMemo(
+    () =>
+      wrapperNodeIds.size === 0
+        ? nodes
+        : nodes.filter((n) => !wrapperNodeIds.has(n.id)),
+    [nodes, wrapperNodeIds],
+  );
+  const walkthroughEdges = useMemo(
+    () =>
+      wrapperNodeIds.size === 0
+        ? edges
+        : edges.filter(
+            (e) =>
+              !wrapperNodeIds.has(e.source) && !wrapperNodeIds.has(e.target),
+          ),
+    [edges, wrapperNodeIds],
+  );
+
+  const animateLayout = useCallback(() => {
+    const wrapper = reactFlowWrapperRef.current;
+    if (!wrapper) return;
+    wrapper.classList.add("ec-animating-layout");
+    setTimeout(() => wrapper.classList.remove("ec-animating-layout"), 400);
+  }, []);
+
+  const relayoutGraph = useCallback(
+    (
+      nextNodes: Node[],
+      nextEdges: Edge[],
+      anchor?: { id: string; position: { x: number; y: number } },
+    ) => {
+      const g = new dagre.graphlib.Graph({ compound: true });
+      g.setGraph({ rankdir: "LR", ranksep: 300, nodesep: 50 });
+      g.setDefaultEdgeLabel(() => ({}));
+
+      // Add nodes to dagre — skip children (they're positioned relative to parent)
+      nextNodes.forEach((node) => {
+        if (node.parentId) return;
+        const w =
+          (node.style?.width as number) ||
+          (node.type === "messageGroupExpanded" ? 380 : 150);
+        const h =
+          (node.style?.height as number) ||
+          (node.type === "messageGroupExpanded" ? 0 : 120);
+
+        // For expanded groups, calculate height from child count
+        if (node.type === "messageGroupExpanded") {
+          const children = nextNodes.filter((n) => n.parentId === node.id);
+          const childHeight = children.length * 190 + 100; // 190px per child + padding
+          g.setNode(node.id, { width: w, height: childHeight });
+        } else {
+          g.setNode(node.id, { width: w, height: h });
+        }
+      });
+
+      // Add edges — only between top-level nodes or from top-level to parent of child
+      nextEdges.forEach((edge) => {
+        const sourceNode = nextNodes.find((n) => n.id === edge.source);
+        const targetNode = nextNodes.find((n) => n.id === edge.target);
+        const sourceTop = sourceNode?.parentId || edge.source;
+        const targetTop = targetNode?.parentId || edge.target;
+        // Only add edge if both endpoints are in the dagre graph
+        if (
+          g.hasNode(sourceTop) &&
+          g.hasNode(targetTop) &&
+          sourceTop !== targetTop
+        ) {
+          g.setEdge(sourceTop, targetTop);
+        }
+      });
+
+      dagre.layout(g);
+
+      // Apply dagre positions to top-level nodes
+      const positioned = nextNodes.map((node) => {
+        if (node.parentId) {
+          const parent = nextNodes.find((n) => n.id === node.parentId);
+
+          // Sub-flow expansion: children keep the LR positions already computed
+          // when the sub-flow was expanded. Leave them alone so the inner graph
+          // renders in true graph order, not a vertical stack.
+          if (parent?.type === "flowExpanded") {
+            return node;
+          }
+
+          // Message groups: simple vertical stack, centred within the container.
+          const parentWidth = (parent?.style?.width as number) || 380;
+          const childWidth = 240; // initial estimate, refined by post-render measurement
+          const xOffset = Math.max(20, (parentWidth - childWidth) / 2);
+          const siblings = nextNodes.filter(
+            (n) => n.parentId === node.parentId,
+          );
+          const index = siblings.indexOf(node);
+          return {
+            ...node,
+            position: { x: xOffset, y: 70 + index * 190 },
+          };
+        }
+
+        const pos = g.node(node.id);
+        if (!pos) return node;
+        // dagre returns center positions — convert to top-left for ReactFlow
+        return {
+          ...node,
+          position: { x: pos.x - pos.width / 2, y: pos.y - pos.height / 2 },
+        };
+      });
+
+      if (!anchor) return positioned;
+
+      const positionedAnchor = positioned.find((node) => node.id === anchor.id);
+      if (!positionedAnchor) return positioned;
+
+      const offset = {
+        x: anchor.position.x - positionedAnchor.position.x,
+        y: anchor.position.y - positionedAnchor.position.y,
+      };
+
+      return positioned.map((node) => {
+        if (node.parentId) return node;
+        return {
+          ...node,
+          position: {
+            x: node.position.x + offset.x,
+            y: node.position.y + offset.y,
+          },
+        };
+      });
+    },
+    [],
+  );
+
+  const makeRoomForRenderedExpandedGroup = useCallback(
+    (
+      groupNodeId: string,
+      groupBounds: { x: number; y: number; width: number; height: number },
+    ) => {
+      const padding = 80;
+      const protectedBounds = {
+        x: groupBounds.x - padding,
+        y: groupBounds.y - padding,
+        width: groupBounds.width + padding * 2,
+        height: groupBounds.height + padding * 2,
+      };
+      const intersectingIds = new Set(
+        getIntersectingNodes(protectedBounds, true)
+          .filter((node) => node.id !== groupNodeId && !node.parentId)
+          .map((node) => node.id),
+      );
+
+      if (intersectingIds.size === 0) return;
+
+      setNodes((currentNodes) => {
+        const plannedPositions = packNodesAroundBounds({
+          nodes: currentNodes,
+          movableNodeIds: intersectingIds,
+          protectedBounds,
+          groupNodeId,
+        });
+
+        return currentNodes.map((node) => {
+          const plannedPosition = plannedPositions.get(node.id);
+          if (!plannedPosition) return node;
+          return { ...node, position: plannedPosition };
+        });
+      });
+    },
+    [getIntersectingNodes, setNodes],
+  );
+
+  // Lay a sub-flow's internal nodes out with dagre LR and return positioned
+  // children, a per-id position map, and the tightest container bounding box
+  // so the wrapper can size itself to fit. `sizeOf` supplies per-child width
+  // and height — callers pass either estimated constants (initial layout) or
+  // measured DOM dimensions (post-paint).
+  const layoutSubFlowChildren = useCallback(
+    (
+      children: Node[],
+      edges: Edge[],
+      sizeOf: (n: Node) => { w: number; h: number },
+      opts: {
+        padding: number;
+        headerH: number;
+        fallbackW?: number;
+        fallbackH?: number;
+      },
+    ) => {
+      const { padding, headerH, fallbackW = 240, fallbackH = 120 } = opts;
+
+      const g = new dagre.graphlib.Graph();
+      g.setGraph({ rankdir: "LR", ranksep: 360, nodesep: 200 });
+      g.setDefaultEdgeLabel(() => ({}));
+      const childIds = new Set(children.map((c) => c.id));
+      children.forEach((c) => {
+        const { w, h } = sizeOf(c);
+        g.setNode(c.id, { width: w, height: h });
+      });
+      edges.forEach((e) => {
+        if (childIds.has(e.source) && childIds.has(e.target)) {
+          g.setEdge(e.source, e.target);
+        }
+      });
+      dagre.layout(g);
+
+      let minX = Infinity;
+      let minY = Infinity;
+      let maxX = -Infinity;
+      let maxY = -Infinity;
+      const positions = new Map<string, { x: number; y: number }>();
+      children.forEach((c) => {
+        const pos = g.node(c.id);
+        if (!pos) return;
+        const x = pos.x - pos.width / 2;
+        const y = pos.y - pos.height / 2;
+        positions.set(c.id, { x, y });
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x + pos.width);
+        maxY = Math.max(maxY, y + pos.height);
+      });
+
+      const offsetX = padding - (Number.isFinite(minX) ? minX : 0);
+      const offsetY = headerH + padding - (Number.isFinite(minY) ? minY : 0);
+      const positioned = children.map((c) => {
+        const p = positions.get(c.id);
+        if (!p) return c;
+        return { ...c, position: { x: p.x + offsetX, y: p.y + offsetY } };
+      });
+      // Translate positions too so callers that read the map see the final coords.
+      const finalPositions = new Map<string, { x: number; y: number }>();
+      positions.forEach((p, id) =>
+        finalPositions.set(id, { x: p.x + offsetX, y: p.y + offsetY }),
+      );
+
+      const width = Number.isFinite(minX)
+        ? maxX - minX + padding * 2
+        : fallbackW + padding * 2;
+      const height = Number.isFinite(minY)
+        ? maxY - minY + headerH + padding * 2
+        : fallbackH + headerH + padding * 2;
+
+      return { positioned, positions: finalPositions, width, height };
+    },
+    [],
+  );
+
+  // Read from refs inside the callback to avoid nodes/edges in the dependency array.
+  // This prevents the callback from being recreated on every drag tick (Rule 2).
+  const handleCollapseGroup = useCallback(
+    (e: React.MouseEvent) => {
+      const target = e.target as HTMLElement;
+      const collapseBtn = target.closest(
+        ".ec-collapse-group-btn, .ec-collapse-flow-btn",
+      );
+      if (!collapseBtn) return;
+      e.stopPropagation();
+
+      // Find the ReactFlow node wrapper to get the node ID
+      const nodeWrapper = target.closest("[data-id]");
+      if (!nodeWrapper) return;
+      const groupNodeId = nodeWrapper.getAttribute("data-id");
+      if (!groupNodeId) return;
+
+      const currentNodes = nodesRef.current;
+      const currentEdges = edgesRef.current;
+
+      // Find the expanded container node to get its data
+      const expandedNode = currentNodes.find((n) => n.id === groupNodeId);
+      if (!expandedNode || !isExpandedWrapper(expandedNode.type)) return;
+
+      // The wrapper carries a pre-expansion snapshot — use it so nested
+      // wrappers (created mid-session and therefore absent from initialNodes)
+      // collapse correctly. Fall back to initialNodes for wrappers expanded
+      // on a top-level node that was there from page load.
+      const stashed = (expandedNode.data as any).__preExpansion as
+        | {
+            node: Node;
+            edges: Edge[];
+            nodeIds: string[];
+            nodePositions?: Record<string, { x: number; y: number }>;
+          }
+        | undefined;
+      const originalNode =
+        stashed?.node ??
+        initialNodes.find(
+          (n: Node) =>
+            n.id === groupNodeId &&
+            (n.type === "messageGroup" ||
+              n.type === "flows" ||
+              n.type === "flow"),
+        );
+      if (!originalNode) return;
+      const originalEdges =
+        stashed?.edges ??
+        initialEdges.filter(
+          (edge: Edge) =>
+            edge.source === groupNodeId || edge.target === groupNodeId,
+        );
+
+      const childNodeIds = new Set(
+        currentNodes.filter((n) => n.parentId === groupNodeId).map((n) => n.id),
+      );
+
+      // Downstream nodes added on expand are those in the original node's
+      // expandedNodes that weren't in the graph just before the expand ran.
+      // Use the stashed pre-expansion id snapshot when present (so mid-
+      // session wrappers diff against their own "before"), else fall back
+      // to the initial page-load node set.
+      const originalData = originalNode.data as any;
+      const preExistingIds = new Set(
+        stashed ? stashed.nodeIds : initialNodes.map((n: Node) => n.id),
+      );
+      const downstreamNodeIds = new Set(
+        ((originalData.expandedNodes as any[]) || [])
+          .map((n: any) => n.id)
+          .filter((id: string) => !preExistingIds.has(id)),
+      );
+
+      const isDownstreamEdge = (edge: Edge) =>
+        edge.id.startsWith(`${groupNodeId}__`);
+
+      // Animate the layout transition
+      animateLayout();
+
+      // Swap: remove expanded container + children + downstream, restore compact node.
+      // Only remove downstream nodes that aren't still referenced by surviving edges
+      // (another expanded group may share the same channel/consumer nodes).
+      setNodes((prev) => {
+        // Compute which edges will survive the collapse
+        const nextEdges = currentEdges
+          .filter(
+            (edge) =>
+              !childNodeIds.has(edge.source) &&
+              !childNodeIds.has(edge.target) &&
+              !isDownstreamEdge(edge),
+          )
+          .concat(originalEdges);
+
+        // Nodes still referenced by surviving edges must be kept
+        const referencedByEdges = new Set<string>();
+        for (const edge of nextEdges) {
+          referencedByEdges.add(edge.source);
+          referencedByEdges.add(edge.target);
+        }
+
+        const without = prev
+          .filter(
+            (n) =>
+              n.id !== groupNodeId &&
+              !childNodeIds.has(n.id) &&
+              !(downstreamNodeIds.has(n.id) && !referencedByEdges.has(n.id)),
+          )
+          .map((n) => {
+            const stashedPosition = stashed?.nodePositions?.[n.id];
+            if (!stashedPosition || n.parentId) return n;
+            return { ...n, position: stashedPosition };
+          });
+        const next = [
+          ...without,
+          {
+            ...originalNode,
+            position:
+              stashed?.nodePositions?.[groupNodeId] ?? expandedNode.position,
+          },
+        ];
+        return next;
+      });
+      setEdges((prev) => {
+        const without = prev.filter(
+          (edge) =>
+            !childNodeIds.has(edge.source) &&
+            !childNodeIds.has(edge.target) &&
+            !isDownstreamEdge(edge),
+        );
+        return [...without, ...originalEdges];
+      });
+    },
+    [
+      initialNodes,
+      initialEdges,
+      setNodes,
+      setEdges,
+      relayoutGraph,
+      animateLayout,
+    ],
+  );
+
+  // Store initial node positions for change detection (dev mode only)
+  useEffect(() => {
+    if (isDevMode && initialNodes.length > 0) {
+      const positions: Record<string, { x: number; y: number }> = {};
+      initialNodes.forEach((node: Node) => {
+        positions[node.id] = { x: node.position.x, y: node.position.y };
+      });
+      initialPositionsRef.current = positions;
+    }
+  }, [isDevMode, initialNodes]);
+
+  // Detect layout changes by comparing current positions to initial positions
+  const checkForLayoutChanges = useCallback(() => {
+    if (!isDevMode) return;
+    const initial = initialPositionsRef.current;
+    if (Object.keys(initial).length === 0) return;
+
+    const hasChanges = nodesRef.current.some((node) => {
+      const initialPos = initial[node.id];
+      return (
+        initialPos &&
+        (Math.abs(node.position.x - initialPos.x) > POSITION_CHANGE_THRESHOLD ||
+          Math.abs(node.position.y - initialPos.y) > POSITION_CHANGE_THRESHOLD)
+      );
+    });
+
+    setHasLayoutChanges(hasChanges);
+  }, [isDevMode]);
+
+  // Wrap onNodesChange to detect layout changes after node drag
+  const handleNodesChange = useCallback(
+    (changes: NodeChange[]) => {
+      onNodesChange(changes);
+      // Check for position changes after drag ends
+      const hasDragEnd = changes.some(
+        (change) => change.type === "position" && !change.dragging,
+      );
+      if (hasDragEnd) {
+        // Use setTimeout to ensure state is updated
+        setTimeout(checkForLayoutChanges, 0);
+      }
+    },
+    [onNodesChange, checkForLayoutChanges],
+  );
+
+  const resetNodesAndEdges = useCallback(() => {
+    setNodes((nds) =>
+      nds.map((node) => {
+        node.style = { ...node.style, opacity: 1 };
+        return { ...node, animated: animateMessages, selected: false };
+      }),
+    );
+    setEdges((eds) =>
+      eds.map((edge) => {
+        edge.style = { ...edge.style, opacity: 1 };
+        edge.labelStyle = { ...edge.labelStyle, opacity: 1 };
+        return {
+          ...edge,
+          data: { ...edge.data, opacity: 1, animated: animateMessages },
+          animated: animateMessages,
+        };
+      }),
+    );
+  }, [setNodes, setEdges, animateMessages]);
+
+  useEffect(() => {
+    if (!focusNodeId) return;
+    const targetNode = nodesRef.current.find((node) => node.id === focusNodeId);
+    if (!targetNode) return;
+
+    setNodes((nds) =>
+      nds.map((node) => ({
+        ...node,
+        selected: node.id === focusNodeId,
+      })),
+    );
+
+    requestAnimationFrame(() => {
+      fitView({
+        duration: 450,
+        padding: 0.35,
+        nodes: [targetNode],
+      });
+    });
+  }, [focusNodeId, focusRequestId, fitView, setNodes]);
+
+  useEffect(() => {
+    if (fitRequestId == null) return;
+    requestAnimationFrame(() => {
+      fitView({ duration: 400, padding: 0.2 });
+    });
+  }, [fitRequestId, fitView]);
+
+  const handleNodeClick = useCallback(
+    (_: any, node: Node) => {
+      // If custom onNodeClick is provided, use it
+      if (onNodeClick) {
+        onNodeClick(node);
+        return;
+      }
+
+      // Disable focus mode for flow and entity visualizations — but allow
+      // flow-type nodes that carry precomputed expandedNodes to continue
+      // through to the inline expand handler below.
+      const isFlow = edgesRef.current.some(
+        (edge: Edge) => edge.type === "flow-edge",
+      );
+      const isEntityVisualizer = nodesRef.current.some(
+        (n: Node) => n.type === "entities",
+      );
+      const isExpandableFlow =
+        (node.type === "flows" || node.type === "flow") &&
+        Array.isArray((node.data as any)?.expandedNodes) &&
+        (node.data as any).expandedNodes.length > 0;
+      if ((isFlow || isEntityVisualizer) && !isExpandableFlow) return;
+
+      // Disable focus mode for domain and expanded group nodes
+      if (node.type === "domain" || node.type === "domains") return;
+      // System nodes navigate to their map on click (handled by the node itself),
+      // so don't open the focus-mode modal for them.
+      if (node.type === "system" || node.type === "systems") return;
+      // Context-diagram actor nodes are non-interactive — clicking does nothing.
+      if (node.type === "context-actor") return;
+      // The system-group boundary box on the System Diagram is just a container.
+      if (node.type === "system-group") return;
+      if (isExpandedWrapper(node.type)) return;
+
+      // Handle messageGroup click — expand inline
+      if (node.type === "messageGroup") {
+        const groupData = node.data as any;
+        const groupNodeId = node.id;
+        const currentGroupNode = getExpandedMessageGroupNode(
+          nodesRef.current,
+          groupNodeId,
+        );
+        if (currentGroupNode?.type === "messageGroupExpanded") {
+          const measured = (currentGroupNode as any)?.measured;
+          const width =
+            measured?.width ??
+            (currentGroupNode.style?.width as number | undefined) ??
+            380;
+          const height =
+            measured?.height ??
+            (currentGroupNode.style?.height as number | undefined) ??
+            300;
+
+          setCenter(
+            currentGroupNode.position.x + width / 2,
+            currentGroupNode.position.y + height / 2,
+            {
+              duration: 300,
+              zoom: Math.min(Math.max(getZoom(), 0.55), 1),
+            },
+          );
+          return;
+        }
+
+        const serviceNodeId = `${groupData.service.id}-${groupData.service.version}`;
+
+        // Calculate expanded container dimensions based on message count
+        const childCount = groupData.messages?.length || 0;
+        const containerWidth = 380;
+        const containerHeight = childCount * 190 + 100; // 190px per child + header + padding
+
+        // Capture the node, its edges, and the set of node ids as they are
+        // right now so collapse can (a) restore the pre-expansion node/edges
+        // verbatim even for wrappers created mid-session, and (b) identify
+        // which downstream nodes were newly introduced by this expansion.
+        const preExpansionEdges = edgesRef.current.filter(
+          (e) => e.source === groupNodeId || e.target === groupNodeId,
+        );
+        const preExpansionNodeIds = nodesRef.current.map((n) => n.id);
+        const preExpansionNodePositions = Object.fromEntries(
+          nodesRef.current.map((n) => [n.id, { ...n.position }]),
+        );
+
+        const expandedContainerNode: Node = {
+          id: groupNodeId,
+          type: "messageGroupExpanded",
+          position: node.position,
+          data: {
+            groupName: groupData.groupName,
+            direction: groupData.direction,
+            messageCount: childCount,
+            onCollapse: groupNodeId,
+            __preExpansion: {
+              node,
+              edges: preExpansionEdges,
+              nodeIds: preExpansionNodeIds,
+              nodePositions: preExpansionNodePositions,
+            },
+          },
+          style: {
+            width: containerWidth,
+            height: containerHeight,
+          },
+        };
+
+        // Build child message nodes (operation fields are pre-computed server-side)
+        const childNodes: Node[] = (groupData.messages || []).map(
+          (item: any, index: number) => {
+            const msg = item.message;
+            const msgId = `${msg.data.id}-${msg.data.version}`;
+            return {
+              id: `${groupNodeId}__${msgId}`,
+              type: msg.collection,
+              parentId: groupNodeId,
+              extent: "parent" as const,
+              position: { x: 70, y: 70 + index * 190 },
+              data: {
+                mode: groupData.mode || "simple",
+                message: { ...msg.data },
+              },
+            } as Node;
+          },
+        );
+
+        // Map original message IDs → child node IDs (used for edge remapping)
+        const msgIdToChildId = new Map<string, string>();
+        for (const item of groupData.messages || []) {
+          const msg = item.message;
+          const msgId = `${msg.data.id}-${msg.data.version}`;
+          msgIdToChildId.set(msgId, `${groupNodeId}__${msgId}`);
+        }
+
+        // Build service↔child edges.
+        // For sends: always create service → child (we stripped this edge server-side).
+        // For receives: only create child → service when no channel path already
+        //   connects this message to the service through downstream edges.
+        const childEdges = buildChildEdges(
+          groupData,
+          groupNodeId,
+          serviceNodeId,
+          msgIdToChildId,
+          animateMessages,
+        );
+
+        // Downstream nodes/edges: pre-computed server-side (channels, consumers, producers).
+        // Remap edge endpoints from original message IDs to child node IDs.
+        // Deduplicate by ID — multiple grouped messages may share the same downstream path.
+        // When channels are hidden, filter out channel nodes and their edges.
+        const channelsHidden = hideChannelsRef.current;
+        const channelNodeIds = channelsHidden
+          ? new Set(
+              (groupData.expandedNodes || [])
+                .filter((n: any) => n.type === "channels")
+                .map((n: any) => n.id),
+            )
+          : new Set<string>();
+
+        const downstreamNodes: Node[] = (groupData.expandedNodes || []).filter(
+          (n: any) => !channelNodeIds.has(n.id),
+        );
+
+        const seenEdgeIds = new Set<string>();
+        const downstreamEdges: Edge[] = (groupData.expandedEdges || [])
+          .map((e: any) => ({
+            ...e,
+            type: "animated",
+            source: msgIdToChildId.get(e.source) || e.source,
+            target: msgIdToChildId.get(e.target) || e.target,
+            id: `${groupNodeId}__${e.id}`,
+          }))
+          .filter((e: Edge) => {
+            if (seenEdgeIds.has(e.id)) return false;
+            seenEdgeIds.add(e.id);
+            // Drop edges that touch a hidden channel node
+            if (channelNodeIds.has(e.source) || channelNodeIds.has(e.target))
+              return false;
+            return true;
+          });
+
+        // Animate the layout transition
+        animateLayout();
+
+        // Swap: remove compact node + its edge, add expanded container + children + downstream + edges
+        setNodes((prev) => {
+          const downstreamX =
+            groupData.direction === "sends"
+              ? node.position.x + containerWidth + 260
+              : node.position.x - 420;
+          const downstreamY = node.position.y + 40;
+          return buildMessageGroupExpansionNodes({
+            currentNodes: prev,
+            groupNodeId,
+            expandedContainerNode,
+            childNodes,
+            downstreamNodes,
+            getDownstreamPosition: (_downstreamNode, index) => ({
+              x: downstreamX,
+              y: downstreamY + index * 190,
+            }),
+          }) as Node[];
+        });
+        setEdges((prev) => {
+          const without = prev.filter(
+            (e) => e.source !== groupNodeId && e.target !== groupNodeId,
+          );
+          return [...without, ...childEdges, ...downstreamEdges];
+        });
+
+        // After React renders the new nodes, measure actual sizes, resize container, and distribute evenly
+        requestAnimationFrame(() => {
+          let actualContainerBounds = {
+            x: node.position.x,
+            y: node.position.y,
+            width: containerWidth,
+            height: containerHeight,
+          };
+
+          setNodes((prev) => {
+            const children = prev.filter((n) => n.parentId === groupNodeId);
+            if (children.length === 0) return prev;
+
+            // Measure actual rendered dimensions
+            const measurements = children.map((n) => {
+              const el = document.querySelector(
+                `[data-id="${n.id}"]`,
+              ) as HTMLElement | null;
+              return {
+                id: n.id,
+                w: el?.offsetWidth ?? 240,
+                h: el?.offsetHeight ?? 120,
+              };
+            });
+
+            const padding = 30;
+            const headerH = 50;
+            const gap = 25;
+            const totalChildH =
+              measurements.reduce((sum, m) => sum + m.h, 0) +
+              gap * (measurements.length - 1);
+            const actualContainerH = headerH + totalChildH + padding * 2;
+
+            let currentY = headerH + padding;
+            actualContainerBounds = {
+              x: node.position.x,
+              y: node.position.y,
+              width: containerWidth,
+              height: actualContainerH,
+            };
+
+            return prev.map((n) => {
+              // Resize the container to fit actual content
+              if (n.id === groupNodeId) {
+                actualContainerBounds = {
+                  x: n.position.x,
+                  y: n.position.y,
+                  width: containerWidth,
+                  height: actualContainerH,
+                };
+                return {
+                  ...n,
+                  style: {
+                    ...n.style,
+                    height: actualContainerH,
+                  },
+                };
+              }
+              if (n.parentId !== groupNodeId) return n;
+              const m = measurements.find((m) => m.id === n.id);
+              if (!m) return n;
+              const x = Math.max(0, (containerWidth - m.w) / 2);
+              const y = currentY;
+              currentY += m.h + gap;
+              return { ...n, position: { x, y } };
+            });
+          });
+
+          requestAnimationFrame(() => {
+            const groupNode = getNodes().find((n) => n.id === groupNodeId);
+            const measured = (groupNode as any)?.measured;
+            const width =
+              measured?.width ??
+              (groupNode?.style?.width as number | undefined) ??
+              containerWidth;
+            const height =
+              measured?.height ??
+              (groupNode?.style?.height as number | undefined) ??
+              actualContainerBounds.height;
+            const bounds = {
+              x: groupNode?.position.x ?? actualContainerBounds.x,
+              y: groupNode?.position.y ?? actualContainerBounds.y,
+              width,
+              height,
+            };
+
+            makeRoomForRenderedExpandedGroup(groupNodeId, bounds);
+            setCenter(bounds.x + width / 2, bounds.y + height / 2, {
+              duration: 450,
+              zoom: Math.min(Math.max(getZoom(), 0.55), 1),
+            });
+          });
+        });
+
+        return;
+      }
+
+      // Handle flow-reference click — inline-expand the sub-flow
+      if (isExpandableFlow) {
+        const flowData = node.data as any;
+        const flowNodeId = node.id;
+        const subFlowNodes: any[] = flowData.expandedNodes || [];
+        const subFlowEdges: any[] = flowData.expandedEdges || [];
+
+        const initialChildNodes: Node[] = subFlowNodes.map((child) => ({
+          ...child,
+          parentId: flowNodeId,
+          extent: "parent" as const,
+          position: { x: 0, y: 0 },
+        }));
+
+        const CHILD_PADDING = 60;
+        const HEADER_H = 60;
+        const EST_W = 240;
+        const EST_H = 120;
+        const {
+          positioned: childNodes,
+          width: containerWidth,
+          height: containerHeight,
+        } = layoutSubFlowChildren(
+          initialChildNodes,
+          subFlowEdges as Edge[],
+          () => ({ w: EST_W, h: EST_H }),
+          { padding: CHILD_PADDING, headerH: HEADER_H },
+        );
+
+        // Capture the node, its edges, and the set of node ids as they are
+        // right now so collapse can (a) restore the pre-expansion node/edges
+        // verbatim even for wrappers created mid-session, and (b) identify
+        // which downstream nodes were newly introduced by this expansion.
+        const preExpansionEdges = edgesRef.current.filter(
+          (e) => e.source === flowNodeId || e.target === flowNodeId,
+        );
+        const preExpansionNodeIds = nodesRef.current.map((n) => n.id);
+
+        const expandedContainerNode: Node = {
+          id: flowNodeId,
+          type: "flowExpanded",
+          position: node.position,
+          data: {
+            flowName: flowData.flow?.name || flowData.flow?.data?.name,
+            version: flowData.flow?.version || flowData.flow?.data?.version,
+            __preExpansion: {
+              node,
+              edges: preExpansionEdges,
+              nodeIds: preExpansionNodeIds,
+            },
+          },
+          style: {
+            width: containerWidth,
+            height: containerHeight,
+            background: "transparent",
+            border: "none",
+            padding: 0,
+            overflow: "visible",
+          },
+        };
+
+        const childIds = new Set(childNodes.map((n) => n.id));
+        const hasIncoming = new Set<string>();
+        const hasOutgoing = new Set<string>();
+        for (const e of subFlowEdges) {
+          if (childIds.has(e.target)) hasIncoming.add(e.target);
+          if (childIds.has(e.source)) hasOutgoing.add(e.source);
+        }
+        const entryChildIds = childNodes
+          .map((n) => n.id)
+          .filter((id) => !hasIncoming.has(id));
+        const terminalChildIds = childNodes
+          .map((n) => n.id)
+          .filter((id) => !hasOutgoing.has(id));
+
+        // Reroute the parent graph's edges across the sub-flow's boundary:
+        // each predecessor now targets every entry child; each successor
+        // sources from every terminal child.
+        const currentEdges = edgesRef.current;
+        const predecessorEdges = currentEdges.filter(
+          (e: Edge) => e.target === flowNodeId,
+        );
+        const successorEdges = currentEdges.filter(
+          (e: Edge) => e.source === flowNodeId,
+        );
+
+        const stitchedPredecessors: Edge[] = [];
+        for (const e of predecessorEdges) {
+          for (const entryId of entryChildIds.length > 0
+            ? entryChildIds
+            : [flowNodeId]) {
+            stitchedPredecessors.push({
+              ...e,
+              id: `${e.id}__to__${entryId}`,
+              target: entryId,
+            });
+          }
+        }
+        const stitchedSuccessors: Edge[] = [];
+        for (const e of successorEdges) {
+          for (const terminalId of terminalChildIds.length > 0
+            ? terminalChildIds
+            : [flowNodeId]) {
+            stitchedSuccessors.push({
+              ...e,
+              id: `${e.id}__from__${terminalId}`,
+              source: terminalId,
+            });
+          }
+        }
+
+        animateLayout();
+
+        setNodes((prev) => {
+          const without = prev.filter((n) => n.id !== flowNodeId);
+          const next = [...without, expandedContainerNode, ...childNodes];
+          const nextEdges = [
+            ...currentEdges.filter(
+              (e) => e.source !== flowNodeId && e.target !== flowNodeId,
+            ),
+            ...subFlowEdges,
+            ...stitchedPredecessors,
+            ...stitchedSuccessors,
+          ];
+          return relayoutGraph(next, nextEdges);
+        });
+        setEdges((prev) => {
+          const without = prev.filter(
+            (e) => e.source !== flowNodeId && e.target !== flowNodeId,
+          );
+          return [
+            ...without,
+            ...subFlowEdges,
+            ...stitchedPredecessors,
+            ...stitchedSuccessors,
+          ];
+        });
+
+        // Once React has painted, re-run the LR layout with measured node
+        // sizes so the container sizes itself to real content.
+        requestAnimationFrame(() => {
+          const currentChildren = nodesRef.current.filter(
+            (n) => n.parentId === flowNodeId,
+          );
+          if (currentChildren.length === 0) return;
+
+          const measurements = new Map<string, { w: number; h: number }>();
+          currentChildren.forEach((n) => {
+            const el = document.querySelector(
+              `[data-id="${n.id}"]`,
+            ) as HTMLElement | null;
+            measurements.set(n.id, {
+              w: el?.offsetWidth ?? EST_W,
+              h: el?.offsetHeight ?? EST_H,
+            });
+          });
+
+          const {
+            positions,
+            width: actualContainerW,
+            height: actualContainerH,
+          } = layoutSubFlowChildren(
+            currentChildren,
+            subFlowEdges as Edge[],
+            (n) => measurements.get(n.id) ?? { w: EST_W, h: EST_H },
+            { padding: CHILD_PADDING, headerH: HEADER_H },
+          );
+
+          setNodes((prev) =>
+            prev.map((n) => {
+              if (n.id === flowNodeId) {
+                return {
+                  ...n,
+                  style: {
+                    ...n.style,
+                    width: actualContainerW,
+                    height: actualContainerH,
+                  },
+                };
+              }
+              if (n.parentId !== flowNodeId) return n;
+              const p = positions.get(n.id);
+              if (!p) return n;
+              return { ...n, position: { x: p.x, y: p.y } };
+            }),
+          );
+        });
+
+        requestAnimationFrame(() => {
+          fitView({ duration: 400, padding: 0.2 });
+        });
+
+        return;
+      }
+
+      // Legacy behavior for linksToVisualiser (deprecated - use onNodeClick instead).
+      // Keep this after inline expand handlers so embedded overview graphs can
+      // still expand message groups/sub-flows without opening focus mode.
+      if (linksToVisualiser && onNavigate) {
+        return;
+      }
+
+      // Open focus mode modal
+      setFocusedNodeId(node.id);
+      setFocusModeOpen(true);
+    },
+    [
+      onNodeClick,
+      linksToVisualiser,
+      onNavigate,
+      makeRoomForRenderedExpandedGroup,
+      getNodes,
+      getZoom,
+      setCenter,
+    ],
+  );
+
+  const toggleAnimateMessages = useCallback(() => {
+    setAnimateMessages((prev) => {
+      const next = !prev;
+      localStorage.setItem(
+        "EventCatalog:animateMessages",
+        JSON.stringify(next),
+      );
+      return next;
+    });
+  }, []);
+
+  // Handle fit to view
+  const handleFitView = useCallback(() => {
+    fitView({ duration: 400, padding: 0.2 });
+  }, [fitView]);
+
+  // animate messages, between views
+  // Priority: disableMessageAnimation > animated prop > URL parameter > localStorage > auto (disabled for large graphs)
+  useEffect(() => {
+    // Some graphs (e.g. the Context Diagram) aren't message flows, so animation
+    // is unsupported — always off, ignoring every other source.
+    if (disableMessageAnimation) {
+      setAnimateMessages(false);
+      return;
+    }
+
+    if (animated !== undefined) {
+      setAnimateMessages(animated);
+      return;
+    }
+
+    const urlParams = new URLSearchParams(window.location.search);
+    const animateParam = urlParams.get("animate");
+
+    if (animateParam === "true") {
+      setAnimateMessages(true);
+    } else if (animateParam === "false") {
+      setAnimateMessages(false);
+    } else {
+      // Fall back to localStorage if no URL parameter
+      const storedAnimateMessages = localStorage.getItem(
+        "EventCatalog:animateMessages",
+      );
+      if (storedAnimateMessages !== null) {
+        setAnimateMessages(storedAnimateMessages === "true");
+      } else {
+        // Auto-disable animation for large graphs to keep the canvas responsive
+        setAnimateMessages(initialNodes.length <= LARGE_GRAPH_NODE_THRESHOLD);
+      }
+    }
+  }, [animated, disableMessageAnimation, initialNodes.length]);
+
+  useEffect(() => {
+    setEdges((eds) =>
+      eds.map((edge) => {
+        const preservesOwnRenderer =
+          edge.type === "flow-edge" ||
+          edge.type === "multiline" ||
+          edge.type === "default" ||
+          edge.type === "step" ||
+          edge.type === "smoothstep" ||
+          edge.data?.animated === false;
+
+        return {
+          ...edge,
+          animated: preservesOwnRenderer ? false : animateMessages,
+          type: preservesOwnRenderer
+            ? edge.type || "default"
+            : animateMessages
+              ? "animated"
+              : "smoothstep",
+          data: {
+            ...edge.data,
+            animateMessages: preservesOwnRenderer ? false : animateMessages,
+            animated: preservesOwnRenderer ? false : animateMessages,
+          },
+        };
+      }),
+    );
+  }, [animateMessages]);
+
+  useEffect(() => {
+    setTimeout(() => {
+      fitView({ duration: 800 });
+    }, 150);
+  }, []);
+
+  // Generate mermaid code lazily (only when needed for copy)
+  const generateMermaidCode = useCallback(() => {
+    try {
+      return convertToMermaid(nodesRef.current, edgesRef.current, {
+        includeStyles: true,
+        direction: "LR",
+      });
+    } catch (error) {
+      console.error("Error generating mermaid code:", error);
+      return "";
+    }
+  }, []);
+
+  // Handle scroll wheel events to forward to page when no modifier keys are pressed
+  // Only when zoomOnScroll is disabled
+  // This is a fix for when we embed node graphs into pages, and users are scrolling the documentation pages
+  // We dont want REACT FLOW to swallow the scroll events, so we forward them to the parent page
+  useEffect(() => {
+    // Skip scroll handling if zoomOnScroll is enabled
+    if (zoomOnScroll) return;
+
+    // Cache the scrollable container on mount (expensive operation done once)
+    const findScrollableContainer = (): HTMLElement | null => {
+      // Try specific known selectors first (fast)
+      const selectors = [
+        ".docs-layout .overflow-y-auto",
+        ".overflow-y-auto",
+        '[style*="overflow-y:auto"]',
+        '[style*="overflow-y: auto"]',
+      ];
+
+      for (const selector of selectors) {
+        const element = document.querySelector(selector) as HTMLElement;
+        if (element) return element;
+      }
+
+      return null;
+    };
+
+    // Find and cache the scrollable container once
+    if (!scrollableContainerRef.current) {
+      scrollableContainerRef.current = findScrollableContainer();
+    }
+
+    const handleWheel = (event: WheelEvent) => {
+      // Only forward scroll if no modifier keys are pressed
+      if (!event.ctrlKey && !event.shiftKey && !event.metaKey) {
+        event.preventDefault();
+
+        const scrollableContainer = scrollableContainerRef.current;
+
+        if (scrollableContainer) {
+          scrollableContainer.scrollBy({
+            top: event.deltaY,
+            left: event.deltaX,
+            behavior: "instant",
+          });
+        } else {
+          // Fallback to window scroll
+          window.scrollBy({
+            top: event.deltaY,
+            left: event.deltaX,
+            behavior: "instant",
+          });
+        }
+      }
+    };
+
+    const wrapper = reactFlowWrapperRef.current;
+    if (wrapper) {
+      wrapper.addEventListener("wheel", handleWheel, { passive: false });
+      return () => {
+        wrapper.removeEventListener("wheel", handleWheel);
+      };
+    }
+  }, [zoomOnScroll]);
+
+  const handlePaneClick = useCallback(() => {
+    searchRef.current?.hideSuggestions();
+    resetNodesAndEdges();
+    fitView({ duration: 800 });
+  }, [resetNodesAndEdges, fitView]);
+
+  const handleNodeSelect = useCallback(
+    (node: Node) => {
+      handleNodeClick(null, node);
+    },
+    [handleNodeClick],
+  );
+
+  const handleSearchClear = useCallback(() => {
+    resetNodesAndEdges();
+    fitView({ duration: 800 });
+  }, [resetNodesAndEdges, fitView]);
+
+  const downloadImage = useCallback((dataUrl: string, filename?: string) => {
+    const a = document.createElement("a");
+    a.setAttribute("download", `${filename || "eventcatalog"}.png`);
+    a.setAttribute("href", dataUrl);
+    a.click();
+  }, []);
+
+  const openStudioModal = useCallback(() => {
+    setIsStudioModalOpen(true);
+  }, [setIsStudioModalOpen]);
+
+  const openChat = useCallback(() => {
+    window.dispatchEvent(new CustomEvent("eventcatalog:open-chat"));
+  }, []);
+
+  // Layout persistence handlers (dev mode only)
+  const handleSaveLayout = useCallback(async (): Promise<boolean> => {
+    if (!resourceKey || !onSaveLayout) return false;
+
+    const positions: Record<string, { x: number; y: number }> = {};
+    nodesRef.current.forEach((node) => {
+      positions[node.id] = {
+        x: node.position.x,
+        y: node.position.y,
+      };
+    });
+
+    return await onSaveLayout(resourceKey, positions);
+  }, [resourceKey, onSaveLayout]);
+
+  const handleResetLayout = useCallback(async (): Promise<boolean> => {
+    if (!resourceKey || !onResetLayout) return false;
+    return await onResetLayout(resourceKey);
+  }, [resourceKey, onResetLayout]);
+
+  // Quick save handler for the change detection UI
+  const handleQuickSaveLayout = useCallback(async () => {
+    setIsSavingLayout(true);
+    const success = await handleSaveLayout();
+    setIsSavingLayout(false);
+    if (success) {
+      // Update initial positions to current positions after save
+      const positions: Record<string, { x: number; y: number }> = {};
+      nodesRef.current.forEach((node) => {
+        positions[node.id] = { x: node.position.x, y: node.position.y };
+      });
+      initialPositionsRef.current = positions;
+      setHasLayoutChanges(false);
+    }
+  }, [handleSaveLayout]);
+
+  const handleCopyArchitectureCode = useCallback(async () => {
+    const code = generateMermaidCode();
+    await copyToClipboard(code);
+  }, [generateMermaidCode]);
+
+  const handleCopyShareUrl = useCallback(async () => {
+    const url = typeof window !== "undefined" ? window.location.href : "";
+    await copyToClipboard(url);
+    setShareUrlCopySuccess(true);
+    setTimeout(() => setShareUrlCopySuccess(false), 2000);
+  }, []);
+
+  const toggleFullScreen = useCallback(() => {
+    if (!document.fullscreenElement) {
+      reactFlowWrapperRef.current?.requestFullscreen().catch((err) => {
+        console.error(
+          `Error attempting to enable full-screen mode: ${err.message} (${err.name})`,
+        );
+      });
+    } else {
+      document.exitFullscreen();
+    }
+  }, []);
+
+  useEffect(() => {
+    const handleFullscreenChange = () => {
+      _setIsFullscreen(!!document.fullscreenElement);
+      setTimeout(() => {
+        fitView({ duration: 800 });
+      }, 100);
+    };
+
+    document.addEventListener("fullscreenchange", handleFullscreenChange);
+    return () => {
+      document.removeEventListener("fullscreenchange", handleFullscreenChange);
+    };
+  }, [fitView]);
+
+  const handleExportVisual = useCallback(() => {
+    // nodeLookup resolves child node positions (relative to their parent
+    // group) to absolute coordinates — without it grouped graphs get cropped
+    const nodesBounds = getNodesBounds(getNodes(), {
+      nodeLookup: storeApi.getState().nodeLookup,
+    });
+    const { width, height, viewport } = getExportImageDimensions(nodesBounds);
+
+    // Hide controls during export
+    const controls = document.querySelector(
+      ".react-flow__controls",
+    ) as HTMLElement;
+    if (controls) controls.style.display = "none";
+
+    const viewportElement = document.querySelector(
+      ".react-flow__viewport",
+    ) as HTMLElement;
+    const removeExportStyles = injectExportStyles(viewportElement);
+
+    toPng(viewportElement, {
+      backgroundColor: "#f1f1f1",
+      width,
+      height,
+      style: {
+        width: `${width}px`,
+        height: `${height}px`,
+        transform: `translate(${viewport.x}px, ${viewport.y}px) scale(${viewport.zoom})`,
+      },
+    })
+      .then((dataUrl: string) => {
+        downloadImage(dataUrl, title);
+      })
+      .finally(() => {
+        removeExportStyles();
+        if (controls) controls.style.display = "block";
+      });
+  }, [getNodes, storeApi, downloadImage, title]);
+
+  const handleLegendClick = useCallback(
+    (collectionType: string, groupId?: string) => {
+      const isLegendTarget = (node: Node<any>) => {
+        if (groupId) {
+          return node.data.group && node.data.group?.id === groupId;
+        }
+        return node.type === collectionType;
+      };
+
+      const updatedNodes = nodes.map((node: Node<any>) => {
+        if (isLegendTarget(node)) {
+          return { ...node, style: { ...node.style, opacity: 1 } };
+        }
+        return { ...node, style: { ...node.style, opacity: 0.1 } };
+      });
+
+      const updatedEdges = edges.map((edge) => {
+        return {
+          ...edge,
+          data: { ...edge.data, opacity: 0.1 },
+          style: { ...edge.style, opacity: 0.1 },
+          labelStyle: { ...edge.labelStyle, opacity: 0.1 },
+          animated: animateMessages,
+        };
+      });
+
+      setNodes(updatedNodes);
+      setEdges(updatedEdges);
+
+      const targetNodes = updatedNodes.filter(isLegendTarget);
+      if (targetNodes.length === 0) return;
+
+      fitView({
+        padding: 0.2,
+        duration: 800,
+        nodes: targetNodes,
+      });
+    },
+    [nodes, edges, setNodes, setEdges, fitView],
+  );
+
+  const getNodesByCollectionWithColors = useCallback((nodes: Node<any>[]) => {
+    const colorClasses = {
+      events: "bg-orange-600",
+      agent: "bg-sky-600",
+      agents: "bg-sky-600",
+      agentTool: "bg-violet-600",
+      "agent-tool": "bg-violet-600",
+      services: "bg-pink-600",
+      flows: "bg-teal-600",
+      commands: "bg-blue-600",
+      queries: "bg-green-600",
+      channels: "bg-gray-600",
+      externalSystem: "bg-pink-600",
+      systems: "bg-purple-600",
+      system: "bg-purple-600",
+      actor: "bg-yellow-500",
+      "context-actor": "bg-yellow-500",
+      step: "bg-gray-700",
+      data: "bg-blue-600",
+      "data-products": "bg-indigo-600",
+      field: "bg-cyan-600",
+      messageGroup: "bg-violet-600",
+      messageGroupExpanded: "bg-violet-600",
+    };
+
+    let legendForDomains: {
+      [key: string]: { count: number; colorClass: string; groupId: string };
+    } = {};
+
+    // Find any groups
+    const domainGroups = [
+      ...new Set(
+        nodes
+          .filter(
+            (node) => node.data.group && node.data.group?.type === "Domain",
+          )
+          .map((node) => node.data.group?.id),
+      ),
+    ];
+
+    domainGroups.forEach((groupId) => {
+      const group = nodes.filter(
+        (node) => node.data.group && node.data.group?.id === groupId,
+      );
+      legendForDomains[`${groupId} (Domain)`] = {
+        count: group.length,
+        colorClass: "bg-yellow-600",
+        groupId,
+      };
+    });
+
+    const legendForNodes = nodes.reduce(
+      (
+        acc: {
+          [key: string]: {
+            count: number;
+            colorClass: string;
+            groupId?: string;
+          };
+        },
+        node,
+      ) => {
+        const collection = node.type;
+        if (collection) {
+          if (acc[collection]) {
+            acc[collection].count += 1;
+          } else {
+            acc[collection] = {
+              count: 1,
+              colorClass:
+                colorClasses[collection as keyof typeof colorClasses] ||
+                "bg-black",
+            };
+          }
+        }
+        return acc;
+      },
+      {},
+    );
+
+    return { ...legendForDomains, ...legendForNodes };
+  }, []);
+
+  // Legend only depends on node types and groups, not positions.
+  // Use a ref to avoid recomputing the key string on every drag tick.
+  const legendKeyRef = useRef("");
+  const computedLegendKey = nodes
+    .map((n: Node<any>) => `${n.id}:${n.type}:${n.data.group?.id || ""}`)
+    .join(",");
+  if (computedLegendKey !== legendKeyRef.current) {
+    legendKeyRef.current = computedLegendKey;
+  }
+  const legendKey = legendKeyRef.current;
+
+  const legend = useMemo(
+    () => getNodesByCollectionWithColors(nodes),
+    [getNodesByCollectionWithColors, legendKey],
+  );
+
+  // Stable key derived from node IDs — only changes when nodes are added/removed,
+  // not when positions change during drag. Used by search, legend, and notes.
+  const nodeIdsKeyRef = useRef("");
+  const computedNodeIdsKey = nodes.map((n) => n.id).join(",");
+  if (computedNodeIdsKey !== nodeIdsKeyRef.current) {
+    nodeIdsKeyRef.current = computedNodeIdsKey;
+  }
+  const nodeIdsKey = nodeIdsKeyRef.current;
+
+  const searchNodes = useMemo(() => nodes, [nodeIdsKey]);
+
+  // Collect notes across all nodes for the dropdown menu item.
+  // Notes don't change during drag — use nodeIdsKey for stability.
+  const allNoteGroups = useMemo(() => {
+    const groups: {
+      nodeId: string;
+      name: string;
+      notes: any[];
+      nodeType: string;
+    }[] = [];
+    for (const node of nodes) {
+      const result = getNotesFromNode(node);
+      if (result) {
+        groups.push({
+          nodeId: node.id,
+          name: result.name,
+          notes: result.notes,
+          nodeType: result.nodeType,
+        });
+      }
+    }
+    return groups;
+  }, [nodeIdsKey]);
+
+  const totalNotesCount = useMemo(
+    () => allNoteGroups.reduce((sum, g) => sum + g.notes.length, 0),
+    [allNoteGroups],
+  );
+
+  const handleStepChange = useCallback(
+    (
+      nodeId: string | null,
+      highlightPaths?: string[],
+      shouldZoomOut?: boolean,
+    ) => {
+      if (nodeId === null) {
+        // Reset all nodes and edges
+        resetNodesAndEdges();
+        _setActiveStepIndex(null);
+
+        // If shouldZoomOut is true, fit the entire view
+        if (shouldZoomOut) {
+          setTimeout(() => {
+            fitView({ duration: 800, padding: 0.1 });
+          }, 100);
+        }
+        return;
+      }
+
+      const activeNode = nodes.find((node: Node) => node.id === nodeId);
+      if (!activeNode) return;
+
+      // Create set of highlighted nodes and edges
+      const highlightedNodeIds = new Set<string>();
+      const highlightedEdgeIds = new Set<string>();
+
+      // Add current node
+      highlightedNodeIds.add(activeNode.id);
+
+      // Add incoming edges and their source nodes
+      edges.forEach((edge: Edge) => {
+        if (edge.target === activeNode.id) {
+          highlightedEdgeIds.add(edge.id);
+          highlightedNodeIds.add(edge.source);
+        }
+      });
+
+      // Add outgoing edges
+      if (highlightPaths) {
+        // Highlight all possible paths when at a fork
+        highlightPaths.forEach((pathId) => {
+          const [source, target] = pathId.split("-");
+          edges.forEach((edge: Edge) => {
+            if (edge.source === source && edge.target === target) {
+              highlightedEdgeIds.add(edge.id);
+              highlightedNodeIds.add(edge.target);
+            }
+          });
+        });
+      } else {
+        // Highlight all outgoing edges normally
+        edges.forEach((edge: Edge) => {
+          if (edge.source === activeNode.id) {
+            highlightedEdgeIds.add(edge.id);
+            highlightedNodeIds.add(edge.target);
+          }
+        });
+      }
+
+      // Update nodes
+      const updatedNodes = nodes.map((node: Node) => {
+        if (highlightedNodeIds.has(node.id)) {
+          return { ...node, style: { ...node.style, opacity: 1 } };
+        }
+        return { ...node, style: { ...node.style, opacity: 0.2 } };
+      });
+
+      // Update edges
+      const updatedEdges = edges.map((edge: Edge) => {
+        if (highlightedEdgeIds.has(edge.id)) {
+          return {
+            ...edge,
+            data: { ...edge.data, opacity: 1, animated: true },
+            style: { ...edge.style, opacity: 1, strokeWidth: 3 },
+            labelStyle: { ...edge.labelStyle, opacity: 1 },
+            animated: true,
+          };
+        }
+        return {
+          ...edge,
+          data: { ...edge.data, opacity: 0.2, animated: false },
+          style: { ...edge.style, opacity: 0.2, strokeWidth: 2 },
+          labelStyle: { ...edge.labelStyle, opacity: 0.2 },
+          animated: false,
+        };
+      });
+
+      setNodes(updatedNodes);
+      setEdges(updatedEdges);
+
+      // Fit view to active node
+      fitView({
+        padding: 0.4,
+        duration: 800,
+        nodes: [activeNode],
+      });
+    },
+    [nodes, edges, setNodes, setEdges, resetNodesAndEdges, fitView],
+  );
+
+  // Check if this is a flow visualization by checking if edges use flow-edge type
+  const isFlowVisualization = useMemo(
+    () => edges.some((edge: Edge) => edge.type === "flow-edge"),
+    [edges],
+  );
+  const isCompactMenuButton = !title;
+  const menuButtonClassName = isCompactMenuButton
+    ? "h-9 w-9 p-0 bg-[rgb(var(--ec-card-bg))] hover:bg-[rgb(var(--ec-accent-subtle))] border border-[rgb(var(--ec-page-border))] rounded-md focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-[rgb(var(--ec-accent))] flex items-center justify-center transition-colors duration-150 hover:border-[rgb(var(--ec-accent)/0.3)] group"
+    : "py-2.5 px-4 bg-[rgb(var(--ec-card-bg))] hover:bg-[rgb(var(--ec-accent-subtle))] border border-[rgb(var(--ec-page-border))] rounded-md focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-[rgb(var(--ec-accent))] flex items-center gap-3 transition-colors duration-150 hover:border-[rgb(var(--ec-accent)/0.3)] group whitespace-nowrap";
+  const menuIconClassName = isCompactMenuButton
+    ? "h-4 w-4 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0 group-hover:text-[rgb(var(--ec-accent))] transition-colors duration-150"
+    : "h-5 w-5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0 group-hover:text-[rgb(var(--ec-accent))] transition-colors duration-150";
+
+  return (
+    <div
+      ref={reactFlowWrapperRef}
+      onClick={handleCollapseGroup}
+      className="w-full h-full bg-[rgb(var(--ec-page-bg))] flex flex-col eventcatalog-visualizer"
+      style={{
+        width: "100%",
+        height: "100%",
+        display: "flex",
+        flexDirection: "column",
+      }}
+    >
+      <PortalContainerProvider value={reactFlowWrapperRef.current}>
+        {isMermaidView ? (
+          <>
+            {/* Menu Bar for Mermaid View */}
+            <div className="w-full pr-6 flex space-x-2 justify-between items-center bg-[rgb(var(--ec-page-bg))] border-b border-[rgb(var(--ec-page-border))] p-4">
+              <div className="flex space-x-2 ml-4">
+                {/* Settings Dropdown Menu */}
+                <DropdownMenu.Root>
+                  <DropdownMenu.Trigger asChild>
+                    <button
+                      className={menuButtonClassName}
+                      aria-label="Open menu"
+                    >
+                      {title && (
+                        <span className="text-base font-medium text-[rgb(var(--ec-page-text))] leading-tight">
+                          {title}
+                        </span>
+                      )}
+                      <MoreVertical className={menuIconClassName} />
+                    </button>
+                  </DropdownMenu.Trigger>
+                  <DropdownMenu.Portal container={reactFlowWrapperRef.current}>
+                    <DropdownMenu.Content
+                      className="min-w-56 bg-[rgb(var(--ec-page-bg))] border border-[rgb(var(--ec-page-border))] rounded-lg shadow-xl z-50 py-1.5 animate-in fade-in zoom-in-95 duration-200"
+                      sideOffset={0}
+                      align="end"
+                      alignOffset={-180}
+                    >
+                      <DropdownMenu.Arrow className="fill-[rgb(var(--ec-page-bg))] stroke-[rgb(var(--ec-page-border))] stroke-1" />
+                      <VisualizerDropdownContent
+                        isMermaidView={isMermaidView}
+                        setIsMermaidView={setIsMermaidView}
+                        animateMessages={animateMessages}
+                        toggleAnimateMessages={toggleAnimateMessages}
+                        hideAnimateMessages={disableMessageAnimation}
+                        hideChannels={hideChannels}
+                        toggleChannelsVisibility={toggleChannelsVisibility}
+                        hasChannels={hasChannels}
+                        showMinimap={showMinimap}
+                        setShowMinimap={setShowMinimap}
+                        handleFitView={handleFitView}
+                        searchRef={searchRef}
+                        isChatEnabled={isChatEnabled}
+                        openChat={openChat}
+                        handleCopyArchitectureCode={handleCopyArchitectureCode}
+                        handleExportVisual={handleExportVisual}
+                        setIsShareModalOpen={setIsShareModalOpen}
+                        toggleFullScreen={toggleFullScreen}
+                        openStudioModal={openStudioModal}
+                        isDevMode={isDevMode}
+                        onSaveLayout={handleSaveLayout}
+                        onResetLayout={handleResetLayout}
+                      />
+                    </DropdownMenu.Content>
+                  </DropdownMenu.Portal>
+                </DropdownMenu.Root>
+              </div>
+              {mode === "full" && showSearch && (
+                <div className="flex justify-end items-center gap-2">
+                  {!isMermaidView && (
+                    <div className="w-96">
+                      <VisualiserSearch
+                        ref={searchRef}
+                        nodes={searchNodes}
+                        onNodeSelect={handleNodeSelect}
+                        onClear={handleSearchClear}
+                      />
+                    </div>
+                  )}
+                </div>
+              )}
+            </div>
+            {/* Mermaid View */}
+            <div className="flex-1 overflow-hidden relative">
+              <MermaidView
+                nodes={nodes}
+                edges={edges}
+                maxTextSize={maxTextSize}
+              />
+            </div>
+          </>
+        ) : (
+          <ReactFlow
+            nodeTypes={nodeTypes}
+            edgeTypes={edgeTypes}
+            minZoom={0.07}
+            nodes={nodes}
+            edges={edges}
+            fitView
+            onNodesChange={handleNodesChange}
+            onEdgesChange={onEdgesChange}
+            onEdgeMouseEnter={handleEdgeMouseEnter}
+            onEdgeMouseLeave={handleEdgeMouseLeave}
+            connectionLineType={ConnectionLineType.SmoothStep}
+            nodeOrigin={NODE_ORIGIN}
+            onNodeClick={handleNodeClick}
+            onNodeMouseEnter={handleNodeMouseEnter}
+            onNodeMouseLeave={handleNodeMouseLeave}
+            onPaneClick={handlePaneClick}
+            onMoveStart={startInteraction}
+            onMoveEnd={endInteraction}
+            onNodeDragStart={startInteraction}
+            onNodeDragStop={endInteraction}
+            zoomOnScroll={zoomOnScroll}
+            className="relative"
+          >
+            <Panel
+              position="top-center"
+              className="w-full pr-6 pointer-events-none"
+            >
+              <div className="flex space-x-2 justify-between items-center pointer-events-auto">
+                <div className="flex space-x-2 ml-4">
+                  {/* Settings Dropdown Menu */}
+                  <DropdownMenu.Root>
+                    <DropdownMenu.Trigger asChild>
+                      <button
+                        className={menuButtonClassName}
+                        aria-label="Open menu"
+                      >
+                        {title && (
+                          <span className="text-base font-medium text-[rgb(var(--ec-page-text))] leading-tight">
+                            {title}
+                          </span>
+                        )}
+                        <MoreVertical className={menuIconClassName} />
+                      </button>
+                    </DropdownMenu.Trigger>
+                    <DropdownMenu.Portal
+                      container={reactFlowWrapperRef.current}
+                    >
+                      <DropdownMenu.Content
+                        className="min-w-56 bg-[rgb(var(--ec-page-bg))] border border-[rgb(var(--ec-page-border))] rounded-lg shadow-xl z-50 py-1.5 animate-in fade-in zoom-in-95 duration-200"
+                        sideOffset={0}
+                        align="end"
+                        alignOffset={-180}
+                      >
+                        <DropdownMenu.Arrow className="fill-[rgb(var(--ec-page-bg))] stroke-[rgb(var(--ec-page-border))] stroke-1" />
+                        <VisualizerDropdownContent
+                          isMermaidView={isMermaidView}
+                          setIsMermaidView={setIsMermaidView}
+                          animateMessages={animateMessages}
+                          toggleAnimateMessages={toggleAnimateMessages}
+                          hideAnimateMessages={disableMessageAnimation}
+                          hideChannels={hideChannels}
+                          toggleChannelsVisibility={toggleChannelsVisibility}
+                          hasChannels={hasChannels}
+                          showMinimap={showMinimap}
+                          setShowMinimap={setShowMinimap}
+                          handleFitView={handleFitView}
+                          searchRef={searchRef}
+                          isChatEnabled={isChatEnabled}
+                          openChat={openChat}
+                          handleCopyArchitectureCode={
+                            handleCopyArchitectureCode
+                          }
+                          handleExportVisual={handleExportVisual}
+                          setIsShareModalOpen={setIsShareModalOpen}
+                          toggleFullScreen={toggleFullScreen}
+                          openStudioModal={openStudioModal}
+                          isDevMode={isDevMode}
+                          onSaveLayout={handleSaveLayout}
+                          onResetLayout={handleResetLayout}
+                          notesCount={totalNotesCount}
+                          onOpenNotes={openNotesModal}
+                        />
+                      </DropdownMenu.Content>
+                    </DropdownMenu.Portal>
+                  </DropdownMenu.Root>
+                </div>
+                {mode === "full" && showSearch && (
+                  <div className="flex justify-end items-center gap-2">
+                    {!isMermaidView && (
+                      <div className="w-96">
+                        <VisualiserSearch
+                          ref={searchRef}
+                          nodes={searchNodes}
+                          onNodeSelect={handleNodeSelect}
+                          onClear={handleSearchClear}
+                        />
+                      </div>
+                    )}
+                  </div>
+                )}
+              </div>
+              {links.length > 0 && (
+                <div className="flex justify-end mt-3">
+                  <div className="relative flex items-center -mt-1">
+                    <span className="absolute left-2 pointer-events-none flex items-center h-full">
+                      <HistoryIcon className="h-4 w-4 text-[rgb(var(--ec-page-text-muted))]" />
+                    </span>
+                    <select
+                      value={
+                        links.find((link) =>
+                          window.location.href.includes(link.url),
+                        )?.url || links[0].url
+                      }
+                      onChange={(e) => {
+                        if (onNavigate) {
+                          onNavigate(e.target.value);
+                        } else {
+                          window.location.href = e.target.value;
+                        }
+                      }}
+                      className="appearance-none pl-7 pr-6 py-0 text-[14px] bg-[rgb(var(--ec-card-bg))] text-[rgb(var(--ec-page-text))] rounded-md border border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-page-border)/0.5)] focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-[rgb(var(--ec-accent))]"
+                      style={{ minWidth: 120, height: "26px" }}
+                    >
+                      {links.map((link) => (
+                        <option key={link.url} value={link.url}>
+                          {link.label}
+                        </option>
+                      ))}
+                    </select>
+                    <span className="absolute right-2 pointer-events-none">
+                      <svg
+                        className="w-4 h-4 text-[rgb(var(--ec-page-text-muted))]"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeWidth="2"
+                        viewBox="0 0 24 24"
+                      >
+                        <path
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          d="M19 9l-7 7-7-7"
+                        />
+                      </svg>
+                    </span>
+                  </div>
+                </div>
+              )}
+            </Panel>
+
+            {includeBackground && (
+              <Background color="var(--ec-bg-dots)" gap={16} />
+            )}
+            {includeBackground && <Controls />}
+            {showMinimap && (
+              <MiniMap
+                nodeStrokeWidth={3}
+                zoomable
+                pannable
+                style={MINIMAP_STYLE}
+              />
+            )}
+            {isFlowVisualization && showFlowWalkthrough && (
+              <Panel position="bottom-left">
+                <StepWalkthrough
+                  nodes={walkthroughNodes}
+                  edges={walkthroughEdges}
+                  isFlowVisualization={isFlowVisualization}
+                  onStepChange={handleStepChange}
+                  mode={mode}
+                />
+              </Panel>
+            )}
+            {/* Dev Mode: Layout change indicator */}
+            {isDevMode && hasLayoutChanges && (
+              <Panel
+                position="bottom-left"
+                style={
+                  isFlowVisualization && showFlowWalkthrough
+                    ? LAYOUT_CHANGE_PANEL_STYLE_WITH_WALKTHROUGH
+                    : LAYOUT_CHANGE_PANEL_STYLE_DEFAULT
+                }
+              >
+                <div className="bg-[rgb(var(--ec-card-bg))] border border-[rgb(var(--ec-page-border))] rounded-lg shadow-md px-3 py-2 flex items-center gap-3">
+                  <span className="text-xs text-[rgb(var(--ec-page-text-muted))]">
+                    Layout changed
+                  </span>
+                  <button
+                    onClick={handleQuickSaveLayout}
+                    disabled={isSavingLayout}
+                    className="text-xs font-medium text-white bg-[rgb(var(--ec-accent))] hover:bg-[rgb(var(--ec-accent-hover))] px-2 py-1 rounded transition-colors disabled:opacity-50"
+                  >
+                    {isSavingLayout ? "Saving..." : "Save"}
+                  </button>
+                </div>
+              </Panel>
+            )}
+            {includeKey && (
+              <LegendPanel
+                legend={legend}
+                showMinimap={showMinimap}
+                onLegendClick={handleLegendClick}
+              />
+            )}
+          </ReactFlow>
+        )}
+        <StudioModal
+          isOpen={isStudioModalOpen || false}
+          onClose={() => setIsStudioModalOpen(false)}
+        />
+        <FocusModeModal
+          isOpen={focusModeOpen}
+          onClose={() => {
+            setFocusModeOpen(false);
+          }}
+          initialNodeId={focusedNodeId}
+          nodes={nodes}
+          edges={edges}
+          nodeTypes={nodeTypes}
+          edgeTypes={edgeTypes}
+        />
+        <AllNotesModal
+          noteGroups={allNoteGroups}
+          isOpen={isNotesModalOpen}
+          onClose={() => setIsNotesModalOpen(false)}
+          nodes={nodes}
+        />
+
+        {/* Share Link Modal */}
+        {isShareModalOpen && (
+          <>
+            <div
+              className="fixed inset-0 bg-black/20 z-40"
+              onClick={() => setIsShareModalOpen(false)}
+              style={{ animation: "fadeIn 150ms ease-out" }}
+            />
+            <div
+              className="fixed top-1/2 left-1/2 transform -translate-x-1/2 -translate-y-1/2 bg-[rgb(var(--ec-page-bg))] rounded-lg shadow-xl z-50 w-full max-w-md p-6 border border-[rgb(var(--ec-page-border))]"
+              style={{ animation: "slideInCenter 250ms ease-out" }}
+            >
+              <style>{`
+              @keyframes fadeIn {
+                from { opacity: 0; }
+                to { opacity: 1; }
+              }
+              @keyframes slideInCenter {
+                from { opacity: 0; transform: translate(-50%, -48%); }
+                to { opacity: 1; transform: translate(-50%, -50%); }
+              }
+            `}</style>
+
+              <div className="flex justify-between items-start mb-4">
+                <h3 className="text-lg font-semibold text-[rgb(var(--ec-page-text))]">
+                  Share Link
+                </h3>
+                <button
+                  onClick={() => setIsShareModalOpen(false)}
+                  className="text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))] transition-colors"
+                  aria-label="Close modal"
+                >
+                  <ExternalLink className="w-5 h-5 rotate-180" />
+                </button>
+              </div>
+
+              <p className="text-sm text-[rgb(var(--ec-page-text-muted))] mb-4">
+                Share this link with your team to let them view this
+                visualization.
+              </p>
+
+              <div className="flex gap-2">
+                <input
+                  type="text"
+                  readOnly
+                  value={
+                    typeof window !== "undefined" ? window.location.href : ""
+                  }
+                  className="flex-1 px-3 py-2.5 bg-[rgb(var(--ec-input-bg))] border border-[rgb(var(--ec-input-border))] rounded-md text-[rgb(var(--ec-input-text))] text-sm focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent))]"
+                />
+                <button
+                  onClick={handleCopyShareUrl}
+                  className={`px-4 py-2.5 rounded-md font-medium transition-all duration-200 flex items-center gap-2 ${
+                    shareUrlCopySuccess
+                      ? "bg-green-500 text-white"
+                      : "bg-[rgb(var(--ec-accent))] text-white hover:opacity-90"
+                  }`}
+                  aria-label={shareUrlCopySuccess ? "Copied!" : "Copy link"}
+                >
+                  {shareUrlCopySuccess ? (
+                    <CheckIcon className="w-4 h-4" />
+                  ) : (
+                    <ClipboardIcon className="w-4 h-4" />
+                  )}
+                  <span>{shareUrlCopySuccess ? "Copied!" : "Copy"}</span>
+                </button>
+              </div>
+            </div>
+          </>
+        )}
+      </PortalContainerProvider>
+    </div>
+  );
+};
+
+interface NodeGraphProps {
+  id: string;
+  title?: string;
+  href?: string;
+  hrefLabel?: string;
+  nodes?: Node[];
+  edges?: Edge[];
+  graph?: DslGraph;
+  linkTo?: "docs" | "visualiser";
+  includeKey?: boolean;
+  footerLabel?: string;
+  linksToVisualiser?: boolean;
+  links?: { label: string; url: string }[];
+  mode?: "full" | "simple";
+  portalId?: string;
+  showFlowWalkthrough?: boolean;
+  showSearch?: boolean;
+  zoomOnScroll?: boolean;
+  designId?: string;
+  isChatEnabled?: boolean;
+  maxTextSize?: number;
+  isDevMode?: boolean;
+  resourceKey?: string;
+  /** Controls whether message flow animation is enabled. When set, overrides URL params and localStorage. */
+  animated?: boolean;
+  /**
+   * When true, message-flow animation is unsupported for this graph: it is forced
+   * off (ignoring the `animated` prop, URL params and localStorage) and the
+   * "Simulate Messages" toggle is hidden. Used by graphs that aren't message
+   * flows, e.g. the System Diagram.
+   */
+  disableMessageAnimation?: boolean;
+  /** When set, the graph will zoom to this node id. */
+  focusNodeId?: string;
+  /** Optional token to force repeated focus for the same node id. */
+  focusRequestId?: number;
+  /** Optional token to trigger fit-to-screen behavior. */
+  fitRequestId?: number;
+
+  // Callback API for framework integration
+  onNodeClick?: (node: Node) => void;
+  onBuildUrl?: (path: string) => string;
+  onNavigate?: (url: string) => void;
+  onSaveLayout?: (
+    resourceKey: string,
+    positions: Record<string, { x: number; y: number }>,
+  ) => Promise<boolean>;
+  onResetLayout?: (resourceKey: string) => Promise<boolean>;
+}
+
+const NodeGraph = ({
+  id,
+  nodes: nodesProp,
+  edges: edgesProp,
+  graph,
+  title: titleProp,
+  href,
+  linkTo = "docs",
+  hrefLabel = "Open in visualizer",
+  includeKey: includeKeyProp,
+  footerLabel,
+  linksToVisualiser = false,
+  links = [],
+  mode = "full",
+  portalId,
+  showFlowWalkthrough = true,
+  showSearch: showSearchProp,
+  zoomOnScroll = false,
+  designId,
+  isChatEnabled = false,
+  maxTextSize,
+  isDevMode = false,
+  resourceKey,
+  animated: animatedProp,
+  focusNodeId,
+  focusRequestId,
+  fitRequestId,
+  onNodeClick,
+  onBuildUrl,
+  onNavigate,
+  onSaveLayout,
+  onResetLayout,
+}: NodeGraphProps) => {
+  // When a DslGraph is provided, run layout internally using dagre.
+  const graphLayout = useMemo(() => {
+    if (!graph) return null;
+    return layoutGraph(
+      graph.nodes,
+      graph.edges,
+      { rankdir: "LR", nodesep: 60, ranksep: 120 },
+      graph.options?.style,
+    );
+  }, [graph]);
+  const nodes = graphLayout?.nodes ?? nodesProp ?? [];
+  const edges = graphLayout?.edges ?? edgesProp ?? [];
+
+  // Derive props from graph.options when graph is provided
+  const title = titleProp ?? graph?.title;
+  const includeKey =
+    includeKeyProp !== undefined
+      ? includeKeyProp
+      : graph?.options?.legend !== false;
+  const showSearch =
+    showSearchProp !== undefined
+      ? showSearchProp
+      : graph?.options?.search !== false;
+  const animated = animatedProp ?? graph?.options?.animated;
+  const [elem, setElem] = useState(null);
+  const [showFooter, setShowFooter] = useState(true);
+  const [isStudioModalOpen, setIsStudioModalOpen] = useState(false);
+
+  const openStudioModal = useCallback(() => {
+    setIsStudioModalOpen(true);
+  }, []);
+
+  const containerToRenderInto = portalId || `${id}-portal`;
+
+  useEffect(() => {
+    // @ts-ignore
+    setElem(document.getElementById(containerToRenderInto));
+  }, []);
+
+  useEffect(() => {
+    const urlParams = new URLSearchParams(window.location.search);
+    const embed = urlParams.get("embed");
+    if (embed === "true") {
+      setShowFooter(false);
+    }
+  }, []);
+
+  if (!elem) return null;
+
+  return (
+    <div>
+      {createPortal(
+        <ReactFlowProvider>
+          <NodeGraphBuilder
+            edges={edges}
+            nodes={nodes}
+            title={title}
+            linkTo={linkTo}
+            includeKey={includeKey}
+            linksToVisualiser={linksToVisualiser}
+            links={links}
+            mode={mode}
+            showFlowWalkthrough={showFlowWalkthrough}
+            showSearch={showSearch}
+            zoomOnScroll={zoomOnScroll}
+            designId={designId || id}
+            isStudioModalOpen={isStudioModalOpen}
+            setIsStudioModalOpen={setIsStudioModalOpen}
+            isChatEnabled={isChatEnabled}
+            maxTextSize={maxTextSize}
+            isDevMode={isDevMode}
+            resourceKey={resourceKey}
+            animated={animated}
+            focusNodeId={focusNodeId}
+            focusRequestId={focusRequestId}
+            fitRequestId={fitRequestId}
+            onNodeClick={onNodeClick}
+            onBuildUrl={onBuildUrl}
+            onNavigate={onNavigate}
+            onSaveLayout={onSaveLayout}
+            onResetLayout={onResetLayout}
+          />
+
+          {showFooter && (
+            <div className="flex justify-between" id="visualiser-footer">
+              {footerLabel && (
+                <div className="py-2 w-full text-left ">
+                  <span className=" text-sm no-underline py-2 text-[rgb(var(--ec-page-text-muted))]">
+                    {footerLabel}
+                  </span>
+                </div>
+              )}
+
+              {href && (
+                <div className="py-2 w-full text-right flex justify-between">
+                  {/* Studio link temporarily hidden */}
+                  <span />
+                  <a
+                    className=" text-sm underline text-[rgb(var(--ec-page-text))] hover:text-[rgb(var(--ec-accent))]"
+                    href={href}
+                  >
+                    {hrefLabel} &rarr;
+                  </a>
+                </div>
+              )}
+            </div>
+          )}
+        </ReactFlowProvider>,
+        elem,
+      )}
+    </div>
+  );
+};
+
+export type { NodeGraphProps };
+export default NodeGraph;
diff --git a/packages/visualiser/src/components/NodeGraphPortal.tsx b/packages/visualiser/src/components/NodeGraphPortal.tsx
new file mode 100644
index 000000000..5eef7a430
--- /dev/null
+++ b/packages/visualiser/src/components/NodeGraphPortal.tsx
@@ -0,0 +1,15 @@
+const NodeGraphPortal = (props: any) => {
+  return (
+    <div
+      className="not-prose h-[30em] my-6 mb-12 w-full relative border border-gray-200 rounded-md"
+      id={`${props.id}-portal`}
+      style={{
+        maxHeight: props.maxHeight ? `${props.maxHeight}em` : `30em`,
+      }}
+    >
+      {/* <span className="absolute top-2 right-4 bg-white font-bold z-10">{props.title}</span> */}
+    </div>
+  );
+};
+
+export default NodeGraphPortal;
diff --git a/packages/visualiser/src/components/NotesToolbarButton.tsx b/packages/visualiser/src/components/NotesToolbarButton.tsx
new file mode 100644
index 000000000..e8bd62807
--- /dev/null
+++ b/packages/visualiser/src/components/NotesToolbarButton.tsx
@@ -0,0 +1,733 @@
+import { useState, useCallback } from "react";
+import {
+  MessageCircle,
+  AlertTriangle,
+  X,
+  Locate,
+  ChevronRight,
+  ServerIcon,
+  Bot,
+  Zap,
+  MessageSquare,
+  Search,
+  ArrowRightLeft,
+  Database,
+  Package,
+  Globe,
+  User,
+  MonitorIcon,
+  BoxesIcon,
+  type LucideIcon,
+} from "lucide-react";
+import { useReactFlow, type Node } from "@xyflow/react";
+import * as Dialog from "@radix-ui/react-dialog";
+import { usePortalContainer } from "../context/PortalContainerContext";
+import type { Note } from "../types";
+
+/* ------------------------------------------------------------------ */
+/*  Node type → icon + color mapping                                   */
+/* ------------------------------------------------------------------ */
+
+const NODE_TYPE_META: Record<
+  string,
+  { icon: LucideIcon; color: string; label: string }
+> = {
+  service: { icon: ServerIcon, color: "#ec4899", label: "Service" },
+  services: { icon: ServerIcon, color: "#ec4899", label: "Service" },
+  agent: { icon: Bot, color: "#0ea5e9", label: "Agent" },
+  agents: { icon: Bot, color: "#0ea5e9", label: "Agent" },
+  event: { icon: Zap, color: "#f97316", label: "Event" },
+  events: { icon: Zap, color: "#f97316", label: "Event" },
+  command: { icon: MessageSquare, color: "#3b82f6", label: "Command" },
+  commands: { icon: MessageSquare, color: "#3b82f6", label: "Command" },
+  query: { icon: Search, color: "#22c55e", label: "Query" },
+  queries: { icon: Search, color: "#22c55e", label: "Query" },
+  channel: { icon: ArrowRightLeft, color: "#6b7280", label: "Channel" },
+  channels: { icon: ArrowRightLeft, color: "#6b7280", label: "Channel" },
+  data: { icon: Database, color: "#3b82f6", label: "Data" },
+  "data-products": { icon: Package, color: "#6366f1", label: "Data Product" },
+  externalSystem: { icon: Globe, color: "#ec4899", label: "External System" },
+  actor: { icon: User, color: "#eab308", label: "Actor" },
+  view: { icon: MonitorIcon, color: "#8b5cf6", label: "View" },
+  domain: { icon: BoxesIcon, color: "#14b8a6", label: "Domain" },
+  domains: { icon: BoxesIcon, color: "#14b8a6", label: "Domain" },
+};
+
+function getNodeMeta(nodeType?: string) {
+  if (!nodeType) return null;
+  return NODE_TYPE_META[nodeType] || null;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Extract notes from any node type                                   */
+/* ------------------------------------------------------------------ */
+
+export function getNotesFromNode(
+  node: Node<any>,
+): { name: string; notes: Note[]; nodeType: string } | null {
+  const d = node.data;
+  const containers = [
+    d?.service,
+    d?.message,
+    d?.channel,
+    d?.data,
+    d?.dataProduct,
+    d?.externalSystem,
+    d?.actor,
+  ];
+  for (const container of containers) {
+    if (container?.notes && container.notes.length > 0) {
+      return {
+        name: container.name || node.id,
+        notes: container.notes,
+        nodeType: node.type || "unknown",
+      };
+    }
+  }
+  if (d?.notes && d.notes.length > 0) {
+    return {
+      name: d.name || node.id,
+      notes: d.notes,
+      nodeType: node.type || "unknown",
+    };
+  }
+  return null;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Constants                                                          */
+/* ------------------------------------------------------------------ */
+
+const AMBER = {
+  50: "#fffbeb",
+  100: "#fef3c7",
+  200: "#fde68a",
+  400: "#fbbf24",
+  500: "#f59e0b",
+  600: "#d97706",
+  700: "#b45309",
+  800: "#92400e",
+} as const;
+
+const PRIORITY: Record<
+  string,
+  { bg: string; fg: string; border: string; label: string; accent: string }
+> = {
+  high: {
+    bg: "#fef2f2",
+    fg: "#b91c1c",
+    border: "#fecaca",
+    label: "High",
+    accent: "#ef4444",
+  },
+  critical: {
+    bg: "#fef2f2",
+    fg: "#991b1b",
+    border: "#fecaca",
+    label: "Critical",
+    accent: "#dc2626",
+  },
+  low: {
+    bg: "#f0fdf4",
+    fg: "#15803d",
+    border: "#bbf7d0",
+    label: "Low",
+    accent: "#22c55e",
+  },
+};
+
+const AVATAR_PALETTES = [
+  ["#7c3aed", "#a78bfa"],
+  ["#2563eb", "#60a5fa"],
+  ["#0891b2", "#22d3ee"],
+  ["#059669", "#34d399"],
+  ["#d97706", "#fbbf24"],
+  ["#dc2626", "#f87171"],
+  ["#db2777", "#f472b6"],
+  ["#4f46e5", "#818cf8"],
+];
+
+function hashStr(s: string): number {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) {
+    h = (h * 31 + s.charCodeAt(i)) | 0;
+  }
+  return Math.abs(h);
+}
+
+function Avatar({ name, size = 28 }: { name: string; size?: number }) {
+  const initials = name
+    .split(/\s+/)
+    .map((w) => w[0])
+    .join("")
+    .toUpperCase()
+    .slice(0, 2);
+  const [c1, c2] = AVATAR_PALETTES[hashStr(name) % AVATAR_PALETTES.length];
+  return (
+    <div
+      style={{
+        width: size,
+        height: size,
+        borderRadius: "50%",
+        background: `linear-gradient(135deg, ${c1}, ${c2})`,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        flexShrink: 0,
+      }}
+    >
+      <span
+        style={{
+          fontSize: Math.round(size * 0.42),
+          fontWeight: 700,
+          color: "white",
+          lineHeight: 1,
+        }}
+      >
+        {initials}
+      </span>
+    </div>
+  );
+}
+
+function PriorityBadge({ priority }: { priority: string }) {
+  const p = PRIORITY[priority.toLowerCase()];
+  if (!p) return null;
+  const isUrgent = priority === "high" || priority === "critical";
+  return (
+    <span
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 3,
+        fontSize: 10,
+        fontWeight: 600,
+        color: p.fg,
+        background: p.bg,
+        border: `1px solid ${p.border}`,
+        borderRadius: 99,
+        padding: "2px 7px",
+        textTransform: "uppercase",
+        letterSpacing: "0.03em",
+        lineHeight: 1.4,
+      }}
+    >
+      {isUrgent && (
+        <AlertTriangle style={{ width: 9, height: 9 }} strokeWidth={2.5} />
+      )}
+      {p.label}
+    </span>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Note card for the right panel                                      */
+/* ------------------------------------------------------------------ */
+
+function NoteCard({ note, index }: { note: Note; index: number }) {
+  const prioStyle = note.priority
+    ? PRIORITY[note.priority.toLowerCase()]
+    : null;
+
+  return (
+    <div
+      style={{
+        background: "white",
+        border: "1px solid #e2e8f0",
+        borderRadius: 10,
+        padding: "14px 16px",
+        position: "relative",
+        boxShadow: "0 1px 3px rgba(0,0,0,0.04)",
+      }}
+    >
+      {/* Priority accent stripe */}
+      {prioStyle && (
+        <div
+          style={{
+            position: "absolute",
+            left: 0,
+            top: 10,
+            bottom: 10,
+            width: 3,
+            borderRadius: "0 2px 2px 0",
+            background: prioStyle.accent,
+          }}
+        />
+      )}
+
+      {/* Header: author + priority */}
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: 8,
+          marginBottom: 8,
+        }}
+      >
+        {note.author ? (
+          <Avatar name={note.author} size={24} />
+        ) : (
+          <div
+            style={{
+              width: 24,
+              height: 24,
+              borderRadius: "50%",
+              background: "#f1f5f9",
+              border: `2px solid ${AMBER[200]}`,
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              flexShrink: 0,
+            }}
+          >
+            <span style={{ fontSize: 10, fontWeight: 700, color: AMBER[700] }}>
+              {index + 1}
+            </span>
+          </div>
+        )}
+        <div style={{ flex: 1, minWidth: 0 }}>
+          {note.author && (
+            <span
+              style={{
+                fontSize: 13,
+                fontWeight: 600,
+                color: "#0f172a",
+                lineHeight: 1,
+              }}
+            >
+              {note.author}
+            </span>
+          )}
+        </div>
+        {note.priority && <PriorityBadge priority={note.priority} />}
+      </div>
+
+      {/* Content */}
+      <p
+        style={{
+          fontSize: 13,
+          lineHeight: 1.6,
+          color: "#334155",
+          margin: 0,
+          whiteSpace: "pre-wrap",
+          wordBreak: "break-word",
+          paddingLeft: prioStyle ? 6 : 0,
+        }}
+      >
+        {note.content}
+      </p>
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  All Notes Modal — split layout                                     */
+/* ------------------------------------------------------------------ */
+
+interface NoteGroup {
+  nodeId: string;
+  name: string;
+  notes: Note[];
+  nodeType: string;
+}
+
+export function AllNotesModal({
+  noteGroups,
+  isOpen,
+  onClose,
+  nodes,
+}: {
+  noteGroups: NoteGroup[];
+  isOpen: boolean;
+  onClose: () => void;
+  nodes: Node<any>[];
+}) {
+  const { setCenter, getZoom } = useReactFlow();
+  const [selectedIdx, setSelectedIdx] = useState(0);
+  const portalContainer = usePortalContainer();
+
+  const totalNotes = noteGroups.reduce((sum, g) => sum + g.notes.length, 0);
+  const selected = noteGroups[selectedIdx] || noteGroups[0];
+
+  const handleNavigate = useCallback(
+    (nodeId: string) => {
+      const node = nodes.find((n) => n.id === nodeId);
+      if (!node) return;
+      const zoom = Math.max(getZoom(), 1);
+      setCenter(node.position.x + 100, node.position.y + 50, {
+        zoom,
+        duration: 600,
+      });
+      onClose();
+    },
+    [nodes, setCenter, getZoom, onClose],
+  );
+
+  if (totalNotes === 0) return null;
+
+  return (
+    <Dialog.Root
+      open={isOpen}
+      onOpenChange={(open) => {
+        if (!open) {
+          onClose();
+          setSelectedIdx(0);
+        }
+      }}
+    >
+      <Dialog.Portal container={portalContainer}>
+        <div
+          className="fixed inset-0 z-[99999]"
+          style={{ isolation: "isolate" }}
+        >
+          <Dialog.Overlay
+            style={{
+              position: "fixed",
+              inset: 0,
+              background: "rgba(15, 23, 42, 0.55)",
+              backdropFilter: "blur(6px)",
+            }}
+          />
+
+          <Dialog.Content
+            style={{
+              position: "fixed",
+              top: "50%",
+              left: "50%",
+              transform: "translate(-50%, -50%)",
+              width: "94vw",
+              maxWidth: 720,
+              height: "78vh",
+              maxHeight: 560,
+              background: "white",
+              borderRadius: 14,
+              boxShadow:
+                "0 0 0 1px rgba(0,0,0,0.06), 0 20px 50px rgba(0,0,0,0.2)",
+              display: "flex",
+              flexDirection: "column",
+              overflow: "hidden",
+              outline: "none",
+            }}
+          >
+            {/* Header */}
+            <div
+              style={{
+                padding: "14px 20px",
+                borderBottom: "1px solid #e2e8f0",
+                display: "flex",
+                alignItems: "center",
+                gap: 12,
+                flexShrink: 0,
+              }}
+            >
+              <div
+                style={{
+                  width: 32,
+                  height: 32,
+                  borderRadius: 8,
+                  background: "#f1f5f9",
+                  display: "flex",
+                  alignItems: "center",
+                  justifyContent: "center",
+                  flexShrink: 0,
+                }}
+              >
+                <MessageCircle
+                  style={{ width: 16, height: 16, color: "#64748b" }}
+                  strokeWidth={2.5}
+                />
+              </div>
+              <div style={{ flex: 1, minWidth: 0 }}>
+                <Dialog.Title
+                  style={{
+                    fontSize: 15,
+                    fontWeight: 700,
+                    color: "#0f172a",
+                    margin: 0,
+                    lineHeight: 1.25,
+                  }}
+                >
+                  Notes
+                </Dialog.Title>
+                <Dialog.Description
+                  style={{
+                    fontSize: 12,
+                    color: "#64748b",
+                    margin: 0,
+                    marginTop: 1,
+                  }}
+                >
+                  {totalNotes} note{totalNotes !== 1 ? "s" : ""} across{" "}
+                  {noteGroups.length} resource
+                  {noteGroups.length !== 1 ? "s" : ""}
+                </Dialog.Description>
+              </div>
+              <Dialog.Close asChild>
+                <button
+                  style={{
+                    width: 30,
+                    height: 30,
+                    borderRadius: 8,
+                    border: "none",
+                    background: "rgba(0,0,0,0.04)",
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    cursor: "pointer",
+                    color: "#94a3b8",
+                    flexShrink: 0,
+                  }}
+                  aria-label="Close"
+                >
+                  <X style={{ width: 15, height: 15 }} />
+                </button>
+              </Dialog.Close>
+            </div>
+
+            {/* Split body */}
+            <div style={{ display: "flex", flex: 1, overflow: "hidden" }}>
+              {/* Left: resource list */}
+              <div
+                style={{
+                  width: 240,
+                  flexShrink: 0,
+                  borderRight: "1px solid #e2e8f0",
+                  overflowY: "auto",
+                  background: "#f8fafc",
+                }}
+              >
+                {noteGroups.map((group, i) => {
+                  const isActive = i === selectedIdx;
+                  const meta = getNodeMeta(group.nodeType);
+                  const IconComp = meta?.icon || MessageCircle;
+                  const iconColor = meta?.color || "#64748b";
+
+                  return (
+                    <button
+                      key={group.nodeId}
+                      onClick={() => setSelectedIdx(i)}
+                      style={{
+                        width: "100%",
+                        padding: "12px 16px",
+                        background: isActive ? "white" : "transparent",
+                        border: "none",
+                        borderBottom: "1px solid #f1f5f9",
+                        borderRight: isActive
+                          ? `2px solid ${iconColor}`
+                          : "2px solid transparent",
+                        cursor: "pointer",
+                        display: "flex",
+                        alignItems: "center",
+                        gap: 10,
+                        textAlign: "left",
+                        transition: "background 0.1s",
+                      }}
+                    >
+                      {/* Resource type icon */}
+                      <div
+                        style={{
+                          width: 28,
+                          height: 28,
+                          borderRadius: 7,
+                          background: isActive ? iconColor : `${iconColor}14`,
+                          display: "flex",
+                          alignItems: "center",
+                          justifyContent: "center",
+                          flexShrink: 0,
+                          transition: "background 0.15s",
+                        }}
+                      >
+                        <IconComp
+                          style={{
+                            width: 14,
+                            height: 14,
+                            color: isActive ? "white" : iconColor,
+                            transition: "color 0.15s",
+                          }}
+                          strokeWidth={2}
+                        />
+                      </div>
+
+                      <div style={{ flex: 1, minWidth: 0 }}>
+                        <div
+                          style={{
+                            fontSize: 12,
+                            fontWeight: isActive ? 600 : 500,
+                            color: isActive ? "#0f172a" : "#475569",
+                            lineHeight: 1.3,
+                            overflow: "hidden",
+                            textOverflow: "ellipsis",
+                            whiteSpace: "nowrap",
+                          }}
+                        >
+                          {group.name}
+                        </div>
+                        <div
+                          style={{
+                            fontSize: 10,
+                            color: "#94a3b8",
+                            lineHeight: 1.3,
+                            overflow: "hidden",
+                            textOverflow: "ellipsis",
+                            whiteSpace: "nowrap",
+                            marginTop: 2,
+                          }}
+                        >
+                          {meta?.label || group.nodeType} &middot;{" "}
+                          {group.notes.length} note
+                          {group.notes.length !== 1 ? "s" : ""}
+                        </div>
+                      </div>
+
+                      <ChevronRight
+                        style={{
+                          width: 14,
+                          height: 14,
+                          color: isActive ? iconColor : "#cbd5e1",
+                          flexShrink: 0,
+                        }}
+                        strokeWidth={2}
+                      />
+                    </button>
+                  );
+                })}
+              </div>
+
+              {/* Right: notes for selected resource */}
+              <div
+                style={{
+                  flex: 1,
+                  overflowY: "auto",
+                  display: "flex",
+                  flexDirection: "column",
+                }}
+              >
+                {selected && (
+                  <>
+                    {/* Selected resource header */}
+                    <div
+                      style={{
+                        padding: "14px 20px",
+                        borderBottom: "1px solid #f1f5f9",
+                        display: "flex",
+                        alignItems: "center",
+                        justifyContent: "space-between",
+                        flexShrink: 0,
+                        background: "#fafbfc",
+                      }}
+                    >
+                      <div
+                        style={{
+                          display: "flex",
+                          alignItems: "center",
+                          gap: 10,
+                        }}
+                      >
+                        {(() => {
+                          const meta = getNodeMeta(selected.nodeType);
+                          const Icon = meta?.icon || MessageCircle;
+                          const color = meta?.color || "#64748b";
+                          return (
+                            <div
+                              style={{
+                                width: 30,
+                                height: 30,
+                                borderRadius: 8,
+                                background: `${color}14`,
+                                display: "flex",
+                                alignItems: "center",
+                                justifyContent: "center",
+                                flexShrink: 0,
+                              }}
+                            >
+                              <Icon
+                                style={{
+                                  width: 15,
+                                  height: 15,
+                                  color,
+                                }}
+                                strokeWidth={2}
+                              />
+                            </div>
+                          );
+                        })()}
+                        <div>
+                          <div
+                            style={{
+                              fontSize: 14,
+                              fontWeight: 600,
+                              color: "#0f172a",
+                              lineHeight: 1.3,
+                            }}
+                          >
+                            {selected.name}
+                          </div>
+                          <div
+                            style={{
+                              fontSize: 11,
+                              color: "#94a3b8",
+                              marginTop: 2,
+                            }}
+                          >
+                            {getNodeMeta(selected.nodeType)?.label ||
+                              selected.nodeType}{" "}
+                            &middot; {selected.notes.length} note
+                            {selected.notes.length !== 1 ? "s" : ""}
+                          </div>
+                        </div>
+                      </div>
+                      <button
+                        onClick={() => handleNavigate(selected.nodeId)}
+                        style={{
+                          display: "flex",
+                          alignItems: "center",
+                          gap: 5,
+                          padding: "5px 10px",
+                          borderRadius: 6,
+                          border: "1px solid #e2e8f0",
+                          background: "white",
+                          cursor: "pointer",
+                          fontSize: 11,
+                          fontWeight: 500,
+                          color: "#475569",
+                          transition: "all 0.12s",
+                        }}
+                        onMouseEnter={(e) => {
+                          e.currentTarget.style.borderColor = AMBER[400];
+                          e.currentTarget.style.color = AMBER[700];
+                        }}
+                        onMouseLeave={(e) => {
+                          e.currentTarget.style.borderColor = "#e2e8f0";
+                          e.currentTarget.style.color = "#475569";
+                        }}
+                      >
+                        <Locate style={{ width: 12, height: 12 }} />
+                        Find on canvas
+                      </button>
+                    </div>
+
+                    {/* Notes list */}
+                    <div
+                      style={{
+                        flex: 1,
+                        overflowY: "auto",
+                        padding: "16px 20px",
+                        display: "flex",
+                        flexDirection: "column",
+                        gap: 10,
+                      }}
+                    >
+                      {selected.notes.map((note, i) => (
+                        <NoteCard key={i} note={note} index={i} />
+                      ))}
+                    </div>
+                  </>
+                )}
+              </div>
+            </div>
+          </Dialog.Content>
+        </div>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
diff --git a/packages/visualiser/src/components/StepWalkthrough.tsx b/packages/visualiser/src/components/StepWalkthrough.tsx
new file mode 100644
index 000000000..71edd190d
--- /dev/null
+++ b/packages/visualiser/src/components/StepWalkthrough.tsx
@@ -0,0 +1,380 @@
+import React, {
+  useState,
+  useEffect,
+  useCallback,
+  useMemo,
+  useRef,
+  memo,
+} from "react";
+import { ChevronLeftIcon, ChevronRightIcon } from "@heroicons/react/24/outline";
+import type { Edge } from "@xyflow/react";
+
+interface NodeData {
+  label?: string;
+  summary?: string;
+  step?: {
+    title?: string;
+    summary?: string;
+  };
+  service?: {
+    name?: string;
+    summary?: string;
+    data?: {
+      name?: string;
+      summary?: string;
+    };
+  };
+  message?: {
+    name?: string;
+    summary?: string;
+    data?: {
+      name?: string;
+      summary?: string;
+    };
+  };
+  flow?: {
+    data?: {
+      name?: string;
+    };
+  };
+  custom?: {
+    title?: string;
+    label?: string;
+    summary?: string;
+  };
+  actor?: {
+    label?: string;
+  };
+  externalSystem?: {
+    label?: string;
+  };
+}
+
+interface CustomNode {
+  id: string;
+  data: NodeData;
+}
+
+interface StepWalkthroughProps {
+  nodes: CustomNode[];
+  edges: Edge[];
+  isFlowVisualization: boolean;
+  onStepChange: (
+    nodeId: string | null,
+    highlightPaths?: string[],
+    shouldZoomOut?: boolean,
+  ) => void;
+  mode?: "full" | "simple";
+}
+
+interface PathOption {
+  targetId: string;
+  label?: string;
+  targetNode: CustomNode;
+}
+
+export default memo(function StepWalkthrough({
+  nodes,
+  edges,
+  isFlowVisualization,
+  onStepChange,
+}: StepWalkthroughProps) {
+  const [currentNodeId, setCurrentNodeId] = useState<string | null>(null);
+  const [pathHistory, setPathHistory] = useState<string[]>([]);
+  const [currentStepIndex, setCurrentStepIndex] = useState<number>(-1); // -1 means not started
+  const [availablePaths, setAvailablePaths] = useState<PathOption[]>([]);
+  const [selectedPathIndex, setSelectedPathIndex] = useState<number>(0);
+  const [startNodeId, setStartNodeId] = useState<string | null>(null);
+
+  // Stable structural keys — only change when nodes/edges are added/removed,
+  // not when positions change during drag.
+  const nodeIdsKeyRef = useRef("");
+  const computedNodeIdsKey = nodes.map((n) => n.id).join(",");
+  if (computedNodeIdsKey !== nodeIdsKeyRef.current) {
+    nodeIdsKeyRef.current = computedNodeIdsKey;
+  }
+  const nodeIdsKey = nodeIdsKeyRef.current;
+
+  const edgeKeyRef = useRef("");
+  const computedEdgeKey = edges.map((e) => `${e.source}-${e.target}`).join(",");
+  if (computedEdgeKey !== edgeKeyRef.current) {
+    edgeKeyRef.current = computedEdgeKey;
+  }
+  const edgeKey = edgeKeyRef.current;
+
+  useEffect(() => {
+    if (isFlowVisualization && nodes.length > 0) {
+      // Find the starting node (node with no incoming edges)
+      const incomingEdgeMap = new Map<string, number>();
+      nodes.forEach((node: CustomNode) => incomingEdgeMap.set(node.id, 0));
+
+      edges.forEach((edge: Edge) => {
+        if (incomingEdgeMap.has(edge.target)) {
+          incomingEdgeMap.set(
+            edge.target,
+            (incomingEdgeMap.get(edge.target) || 0) + 1,
+          );
+        }
+      });
+
+      const startNodes = nodes.filter(
+        (node: CustomNode) => incomingEdgeMap.get(node.id) === 0,
+      );
+
+      // Recompute the start node whenever the cached id no longer exists in
+      // the current node set. This happens when the graph structure changes
+      // — for example when a sub-flow is expanded and its wrapper node gets
+      // replaced by children.
+      const cachedStartStillValid =
+        startNodeId && nodes.some((n: CustomNode) => n.id === startNodeId);
+      if (startNodes.length > 0 && !cachedStartStillValid) {
+        const firstStartNode = startNodes[0];
+        setStartNodeId(firstStartNode.id);
+      }
+    }
+  }, [nodeIdsKey, edgeKey, isFlowVisualization, startNodeId]);
+
+  useEffect(() => {
+    if (currentNodeId) {
+      // If the current node no longer exists (e.g. user expanded a sub-flow
+      // and the wrapper the walkthrough was pointing at just got replaced),
+      // reset so the user can restart from the new start node.
+      const currentExists = nodes.some(
+        (n: CustomNode) => n.id === currentNodeId,
+      );
+      if (!currentExists) {
+        setCurrentNodeId(null);
+        setCurrentStepIndex(-1);
+        setPathHistory([]);
+        setAvailablePaths([]);
+        return;
+      }
+
+      // Find available paths from current node
+      const outgoingEdges = edges.filter(
+        (edge: Edge) => edge.source === currentNodeId,
+      );
+      const paths: PathOption[] = outgoingEdges.map((edge: Edge) => {
+        const targetNode = nodes.find((n: CustomNode) => n.id === edge.target);
+        return {
+          targetId: edge.target,
+          label: edge.label as string | undefined,
+          targetNode: targetNode!,
+        };
+      });
+      setAvailablePaths(paths);
+      setSelectedPathIndex(0);
+    } else {
+      setAvailablePaths([]);
+    }
+  }, [currentNodeId, nodeIdsKey, edgeKey]);
+
+  const handleNextStep = useCallback(() => {
+    if (currentStepIndex === -1) {
+      // Start the walkthrough
+      if (startNodeId) {
+        setPathHistory([startNodeId]);
+        setCurrentNodeId(startNodeId);
+        setCurrentStepIndex(0);
+        onStepChange(startNodeId);
+      }
+    } else if (availablePaths.length > 0) {
+      // Move to the selected path
+      const selectedPath = availablePaths[selectedPathIndex];
+      const newHistory = [...pathHistory, selectedPath.targetId];
+      setPathHistory(newHistory);
+      setCurrentNodeId(selectedPath.targetId);
+      setCurrentStepIndex((prev) => prev + 1);
+
+      // Highlight the selected path
+      const allPaths = availablePaths.map(
+        (p) => `${currentNodeId}-${p.targetId}`,
+      );
+      onStepChange(selectedPath.targetId, allPaths);
+    }
+  }, [
+    currentStepIndex,
+    startNodeId,
+    availablePaths,
+    selectedPathIndex,
+    currentNodeId,
+    onStepChange,
+  ]);
+
+  const handlePreviousStep = useCallback(() => {
+    if (currentStepIndex > 0) {
+      // Go back to previous step
+      const newIndex = currentStepIndex - 1;
+      const prevNodeId = pathHistory[newIndex];
+      setCurrentNodeId(prevNodeId);
+      setCurrentStepIndex(newIndex);
+      onStepChange(prevNodeId);
+    } else if (currentStepIndex === 0) {
+      // Go back to the start (no selection)
+      setCurrentNodeId(null);
+      setCurrentStepIndex(-1);
+      onStepChange(null);
+    }
+  }, [currentStepIndex, pathHistory, onStepChange]);
+
+  const handlePathSelection = useCallback((index: number) => {
+    setSelectedPathIndex(index);
+  }, []);
+
+  const handleFinish = useCallback(() => {
+    setCurrentNodeId(null);
+    setCurrentStepIndex(-1);
+    setPathHistory([]);
+    onStepChange(null, [], true); // Pass true to indicate full reset with zoom out
+  }, [onStepChange]);
+
+  if (!isFlowVisualization || nodes.length === 0) {
+    return null;
+  }
+
+  const { title, description } = useMemo(() => {
+    if (currentStepIndex === -1) {
+      return {
+        title: "Walk through business flow",
+        description: "Step through the flow to understand the business process",
+      };
+    }
+
+    const currentNode = nodes.find((n: CustomNode) => n.id === currentNodeId);
+    if (!currentNode) return { title: "Unknown step", description: "" };
+
+    let stepNumber = currentStepIndex + 1;
+    let title = `Step ${stepNumber}`;
+    let description = "";
+
+    // Get node information based on type - check step data first, then type-specific data
+    if (currentNode.data.step?.title) {
+      title += `: ${currentNode.data.step.title}`;
+    } else if (currentNode.data.service?.name) {
+      title += `: ${currentNode.data.service.name}`;
+    } else if (currentNode.data.message?.name) {
+      title += `: ${currentNode.data.message.name}`;
+    } else if (currentNode.data.flow?.data?.name) {
+      title += `: ${currentNode.data.flow.data.name}`;
+    } else if (currentNode.data.custom?.title) {
+      title += `: ${currentNode.data.custom.title}`;
+    } else if (currentNode.data.custom?.label) {
+      title += `: ${currentNode.data.custom.label}`;
+    } else if (currentNode.data.externalSystem?.label) {
+      title += `: ${currentNode.data.externalSystem.label}`;
+    } else if (currentNode.data.label) {
+      // Actor nodes have label directly on data
+      title += `: ${currentNode.data.label}`;
+    }
+
+    // Get description - check step data first, then type-specific data
+    if (currentNode.data.step?.summary) {
+      description = currentNode.data.step.summary;
+    } else if (currentNode.data.service?.summary) {
+      description = currentNode.data.service.summary;
+    } else if (currentNode.data.message?.summary) {
+      description = currentNode.data.message.summary;
+    } else if (currentNode.data.custom?.summary) {
+      description = currentNode.data.custom.summary;
+    } else if (currentNode.data.summary) {
+      // Actor and other nodes may have summary directly on data
+      description = currentNode.data.summary;
+    }
+
+    return { title, description };
+  }, [currentStepIndex, currentNodeId, nodeIdsKey]);
+
+  return (
+    <div className="ml-12 bg-[rgb(var(--ec-card-bg))] rounded-lg shadow-sm px-4 py-2 z-30 border border-[rgb(var(--ec-page-border))] w-[350px]">
+      <div className="mb-2">
+        <h3 className="text-sm font-semibold text-[rgb(var(--ec-page-text))]">
+          {title}
+        </h3>
+        {description && (
+          <p className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-1">
+            {description}
+          </p>
+        )}
+      </div>
+
+      {/* Show path options when there are multiple paths */}
+      {currentNodeId && availablePaths.length > 1 && (
+        <div className="mb-3">
+          <label className="block text-xs font-medium text-[rgb(var(--ec-page-text-muted))] mb-2">
+            Choose next path:
+          </label>
+          <select
+            value={selectedPathIndex}
+            onChange={(e: React.ChangeEvent<HTMLSelectElement>) =>
+              handlePathSelection(parseInt(e.target.value))
+            }
+            className="w-full px-3 py-2 text-xs border border-[rgb(var(--ec-input-border))] rounded-md bg-[rgb(var(--ec-input-bg))] text-[rgb(var(--ec-input-text))] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:border-[rgb(var(--ec-accent))]"
+          >
+            {availablePaths.map((path, index) => {
+              // @ts-ignore
+              const nodeLabel =
+                path.targetNode.data.step?.title ||
+                (path.targetNode.data as any).service?.name ||
+                (path.targetNode.data as any).message?.name ||
+                (path.targetNode.data as any).flow?.data?.name ||
+                (path.targetNode.data as any).custom?.title ||
+                (path.targetNode.data as any).custom?.label ||
+                (path.targetNode.data as any).externalSystem?.label ||
+                (path.targetNode.data as any).label ||
+                "Unknown";
+
+              return (
+                <option key={path.targetId} value={index}>
+                  {path.label ? `${path.label}: ${nodeLabel}` : nodeLabel}
+                </option>
+              );
+            })}
+          </select>
+        </div>
+      )}
+
+      <div className="flex items-center justify-between">
+        {currentStepIndex === -1 ? (
+          // Initial state - show only Start button on the right
+          <>
+            <div className="flex-1"></div>
+            <button
+              onClick={handleNextStep}
+              className="flex items-center justify-center px-6 py-2 text-xs font-medium bg-[rgb(var(--ec-accent))] text-white rounded-md hover:bg-[rgb(var(--ec-accent-hover))] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:ring-offset-2 transition-colors"
+            >
+              Start
+            </button>
+          </>
+        ) : (
+          // In walkthrough - show Previous on left, Next on right (only if paths available)
+          <>
+            <button
+              onClick={handlePreviousStep}
+              className="flex items-center justify-center px-4 py-2 text-xs font-medium bg-[rgb(var(--ec-accent))] text-white rounded-md hover:bg-[rgb(var(--ec-accent-hover))] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:ring-offset-2 transition-colors"
+            >
+              <ChevronLeftIcon className="w-4 h-4 mr-1" />
+              Previous
+            </button>
+
+            {availablePaths.length > 0 ? (
+              <button
+                onClick={handleNextStep}
+                className="flex items-center justify-center px-4 py-2 text-xs font-medium bg-[rgb(var(--ec-accent))] text-white rounded-md hover:bg-[rgb(var(--ec-accent-hover))] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:ring-offset-2 transition-colors"
+              >
+                Next
+                <ChevronRightIcon className="w-4 h-4 ml-1" />
+              </button>
+            ) : (
+              <button
+                onClick={handleFinish}
+                className="flex items-center justify-center px-4 py-2 text-xs font-medium bg-green-600 text-white rounded-md hover:bg-green-700 focus:outline-none focus:ring-2 focus:ring-green-500 focus:ring-offset-2 transition-colors"
+              >
+                Finish
+              </button>
+            )}
+          </>
+        )}
+      </div>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/components/StudioModal.tsx b/packages/visualiser/src/components/StudioModal.tsx
new file mode 100644
index 000000000..cf07530ce
--- /dev/null
+++ b/packages/visualiser/src/components/StudioModal.tsx
@@ -0,0 +1,141 @@
+import React, { useState, useCallback } from "react";
+import * as Dialog from "@radix-ui/react-dialog";
+import { CheckIcon, ClipboardIcon, ExternalLinkIcon } from "lucide-react";
+import { useReactFlow } from "@xyflow/react";
+import { usePortalContainer } from "../context/PortalContainerContext";
+import { exportNodeGraphForStudio } from "../utils/export-node-graph";
+
+interface StudioModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+const StudioModal: React.FC<StudioModalProps> = ({ isOpen, onClose }) => {
+  const [copySuccess, setCopySuccess] = useState(false);
+  const portalContainer = usePortalContainer();
+
+  const { toObject } = useReactFlow();
+
+  const handleCopyToClipboard = useCallback(async () => {
+    const visualizerData = toObject();
+    const studioData = exportNodeGraphForStudio(visualizerData);
+
+    try {
+      await navigator.clipboard.writeText(JSON.stringify(studioData, null, 2));
+      setCopySuccess(true);
+      setTimeout(() => setCopySuccess(false), 2000);
+    } catch (error) {
+      console.error("Failed to copy to clipboard:", error);
+      // Fallback for older browsers
+      const textarea = document.createElement("textarea");
+      textarea.value = JSON.stringify(studioData, null, 2);
+      document.body.appendChild(textarea);
+      textarea.select();
+      document.execCommand("copy");
+      document.body.removeChild(textarea);
+      setCopySuccess(true);
+      setTimeout(() => setCopySuccess(false), 2000);
+    }
+  }, []);
+
+  const handleOpenStudio = () => {
+    window.open(
+      "https://app.eventcatalog.studio/playground?import=true&utm_source=eventcatalog&utm_medium=referral&utm_campaign=playground-import",
+      "_blank",
+    );
+    onClose();
+  };
+
+  return (
+    <Dialog.Root open={isOpen} onOpenChange={onClose}>
+      <Dialog.Portal container={portalContainer}>
+        <Dialog.Overlay className="fixed inset-0 bg-black/50 data-[state=open]:animate-overlayShow z-50" />
+        <Dialog.Content className="fixed top-1/2 left-1/2 w-[90vw] max-w-md -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6 shadow-xl focus:outline-none data-[state=open]:animate-contentShow z-[100]">
+          <Dialog.Title className="text-lg font-semibold text-gray-900 mb-3">
+            Open in EventCatalog Studio
+          </Dialog.Title>
+
+          <Dialog.Description className="text-sm text-gray-600 mb-6">
+            Import your diagram into{" "}
+            <a
+              href="https://eventcatalog.studio"
+              className="text-[rgb(var(--ec-accent))] hover:text-[rgb(var(--ec-accent-hover))] underline"
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              EventCatalog Studio
+            </a>{" "}
+            to create designs from your visualization of your architecture.
+          </Dialog.Description>
+
+          <div className="space-y-4">
+            <div className="bg-gray-50 rounded-lg p-4 border border-gray-200">
+              <h4 className="text-sm font-bold text-gray-900 mb-2">
+                Step 1: Copy diagram
+              </h4>
+              <p className="text-xs text-gray-600 mb-3">
+                Copy your diagram data to your clipboard.
+              </p>
+              <button
+                onClick={handleCopyToClipboard}
+                className={`w-full flex items-center justify-center space-x-2 px-4 py-2 text-sm font-medium rounded-md border transition-colors ${
+                  copySuccess
+                    ? "bg-green-50 border-green-200 text-green-700"
+                    : "bg-white border-gray-300 text-gray-700 hover:bg-gray-50"
+                }`}
+              >
+                {copySuccess ? (
+                  <>
+                    <CheckIcon className="w-4 h-4" />
+                    <span>Copied!</span>
+                  </>
+                ) : (
+                  <>
+                    <ClipboardIcon className="w-4 h-4" />
+                    <span>Copy diagram to clipboard</span>
+                  </>
+                )}
+              </button>
+            </div>
+
+            <div className="bg-[rgb(var(--ec-accent-subtle))] rounded-lg p-4 border border-[rgb(var(--ec-accent)/0.3)]">
+              <h4 className="text-sm font-bold text-gray-900 mb-2">
+                Step 2: Open EventCatalog Studio
+              </h4>
+              <p className="text-xs text-gray-600 mb-3">
+                Go to EventCatalog Studio and import your design using the
+                "Import from EventCatalog" button.
+              </p>
+
+              <button
+                onClick={handleOpenStudio}
+                className="w-full flex items-center justify-center space-x-2 px-4 py-2 bg-[rgb(var(--ec-accent))] text-white text-sm font-medium rounded-md hover:bg-[rgb(var(--ec-accent-hover))] transition-colors"
+              >
+                <ExternalLinkIcon className="w-4 h-4" />
+                <span>Open EventCatalog Studio</span>
+              </button>
+              <p className="text-[12px] text-gray-500  italic mt-4 mb-0">
+                Don't worry, none of your data is stored by EventCatalog Studio,
+                everything is local to your browser.
+              </p>
+            </div>
+          </div>
+
+          <div className="mt-6 flex justify-end">
+            <Dialog.Close asChild>
+              <button
+                type="button"
+                className="px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:ring-offset-2 transition-colors"
+                onClick={onClose}
+              >
+                Close
+              </button>
+            </Dialog.Close>
+          </div>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+};
+
+export default StudioModal;
diff --git a/packages/visualiser/src/components/VisualiserSearch.tsx b/packages/visualiser/src/components/VisualiserSearch.tsx
new file mode 100644
index 000000000..eb344643f
--- /dev/null
+++ b/packages/visualiser/src/components/VisualiserSearch.tsx
@@ -0,0 +1,811 @@
+import {
+  useState,
+  useCallback,
+  useRef,
+  useEffect,
+  forwardRef,
+  useImperativeHandle,
+  memo,
+} from "react";
+import type { Node } from "@xyflow/react";
+import {
+  Blocks,
+  Bot,
+  Database,
+  Group,
+  Layers,
+  ListTree,
+  MessageSquare,
+  Search as SearchIcon,
+  Server,
+  User,
+  Workflow,
+  Wrench,
+  Zap,
+} from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+
+// Define interfaces for different node data structures
+interface ResourceData {
+  id?: string;
+  name?: string;
+  version?: string;
+}
+
+type MessageData = ResourceData;
+
+type ServiceData = ResourceData;
+type AgentData = ResourceData;
+type AgentToolData = ResourceData;
+
+type DomainData = ResourceData;
+
+type EntityData = ResourceData;
+
+interface NodeDataContent extends Record<string, unknown> {
+  message?: { data?: MessageData } & MessageData;
+  service?: { data?: ServiceData } & ServiceData;
+  agent?: { data?: AgentData } & AgentData;
+  agentTool?: { data?: AgentToolData } & AgentToolData;
+  domain?: { data?: DomainData } & DomainData;
+  system?: { data?: ResourceData } & ResourceData;
+  entity?: { data?: EntityData } & EntityData;
+  channel?: { data?: ResourceData } & ResourceData;
+  dataProduct?: { data?: ResourceData } & ResourceData;
+  data?: ResourceData;
+  name?: string;
+  version?: string;
+  groupName?: string;
+  messages?: Array<{
+    message?: {
+      collection?: string;
+      data?: MessageData & { id?: string };
+    };
+  }>;
+}
+
+// Extend the Node type with our custom data structure
+type CustomNode = Node<NodeDataContent>;
+
+type SearchSuggestion = {
+  key: string;
+  node: CustomNode;
+  label: string;
+  searchText: string;
+  type: string;
+  resourceKey: string;
+  groupName?: string;
+  isGroupedMessage?: boolean;
+};
+
+type NodeTypeMeta = {
+  label: string;
+  Icon: LucideIcon;
+  iconClass: string;
+  badgeClass: string;
+};
+
+const formatVersionedName = (name: string, version?: string) => {
+  if (version) {
+    const nameWithoutVersion = name.replace(
+      new RegExp(`-v?${version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`),
+      "",
+    );
+    return `${nameWithoutVersion} (v${version})`;
+  }
+
+  const versionMatch = name.match(
+    /^(.+)-v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)$/,
+  );
+  if (!versionMatch) return name;
+
+  return `${versionMatch[1]} (v${versionMatch[2]})`;
+};
+
+const normalizeCollectionType = (type: string) => {
+  const aliases: Record<string, string> = {
+    event: "events",
+    command: "commands",
+    query: "queries",
+    agent: "agents",
+    service: "services",
+    domain: "domains",
+    channel: "channels",
+    entity: "entities",
+  };
+
+  return aliases[type] || type;
+};
+
+const splitVersionedName = (name: string, version?: string) => {
+  if (version) {
+    return {
+      id: name.replace(
+        new RegExp(`-v?${version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`),
+        "",
+      ),
+      version,
+    };
+  }
+
+  const versionMatch = name.match(
+    /^(.+)-v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)$/,
+  );
+  if (!versionMatch) return { id: name, version: undefined };
+
+  return { id: versionMatch[1], version: versionMatch[2] };
+};
+
+const getResourceKey = ({
+  type,
+  id,
+  name,
+  version,
+}: {
+  type: string;
+  id?: string;
+  name: string;
+  version?: string;
+}) => {
+  const parsed = splitVersionedName(id || name, version);
+  return `${normalizeCollectionType(type)}:${parsed.id}:${parsed.version || ""}`.toLowerCase();
+};
+
+const getNodeResourceData = (
+  data: NodeDataContent,
+  key:
+    | "message"
+    | "agent"
+    | "agentTool"
+    | "service"
+    | "domain"
+    | "system"
+    | "entity"
+    | "channel"
+    | "dataProduct"
+    | "data",
+) => {
+  const resource = data?.[key];
+  if (!resource || typeof resource !== "object") return undefined;
+  return "data" in resource && resource.data ? resource.data : resource;
+};
+
+interface VisualiserSearchProps {
+  nodes: CustomNode[];
+  onNodeSelect: (node: CustomNode) => void;
+  onClear: () => void;
+  onPaneClick?: () => void;
+}
+
+export interface VisualiserSearchRef {
+  hideSuggestions: () => void;
+}
+
+const VisualiserSearch = memo(
+  forwardRef<VisualiserSearchRef, VisualiserSearchProps>(
+    ({ nodes, onNodeSelect, onClear, onPaneClick: _onPaneClick }, ref) => {
+      const [searchQuery, setSearchQuery] = useState("");
+      const [filteredSuggestions, setFilteredSuggestions] = useState<
+        SearchSuggestion[]
+      >([]);
+      const [showSuggestions, setShowSuggestions] = useState(false);
+      const [selectedSuggestionIndex, setSelectedSuggestionIndex] =
+        useState(-1);
+      const searchInputRef = useRef<HTMLInputElement>(null);
+      const containerRef = useRef<HTMLDivElement>(null);
+      const suggestionsListRef = useRef<HTMLDivElement>(null);
+      const suggestionItemRefs = useRef<Array<HTMLDivElement | null>>([]);
+
+      const hideSuggestions = useCallback(() => {
+        setShowSuggestions(false);
+        setSelectedSuggestionIndex(-1);
+      }, []);
+
+      useImperativeHandle(
+        ref,
+        () => ({
+          hideSuggestions,
+        }),
+        [hideSuggestions],
+      );
+
+      const getNodeDisplayName = useCallback((node: CustomNode) => {
+        if (node.type === "messageGroup") {
+          return (node.data as any)?.groupName || node.id;
+        }
+        if (node.type === "messageGroupExpanded") {
+          return (node.data as any)?.groupName || node.id;
+        }
+        const message = getNodeResourceData(node.data, "message");
+        const agent = getNodeResourceData(node.data, "agent");
+        const agentTool = getNodeResourceData(node.data, "agentTool");
+        const service = getNodeResourceData(node.data, "service");
+        const domain = getNodeResourceData(node.data, "domain");
+        const system = getNodeResourceData(node.data, "system");
+        const entity = getNodeResourceData(node.data, "entity");
+        const channel = getNodeResourceData(node.data, "channel");
+        const dataProduct = getNodeResourceData(node.data, "dataProduct");
+        const data = getNodeResourceData(node.data, "data");
+        const name =
+          message?.name ||
+          message?.id ||
+          agent?.name ||
+          agent?.id ||
+          agentTool?.name ||
+          agentTool?.id ||
+          service?.name ||
+          service?.id ||
+          domain?.name ||
+          domain?.id ||
+          system?.name ||
+          system?.id ||
+          entity?.name ||
+          entity?.id ||
+          channel?.name ||
+          channel?.id ||
+          dataProduct?.name ||
+          dataProduct?.id ||
+          data?.name ||
+          data?.id ||
+          node.data?.name ||
+          node.id;
+        const version =
+          message?.version ||
+          agent?.version ||
+          agentTool?.version ||
+          service?.version ||
+          domain?.version ||
+          system?.version ||
+          entity?.version ||
+          channel?.version ||
+          dataProduct?.version ||
+          data?.version ||
+          node.data?.version;
+        return formatVersionedName(name, version);
+      }, []);
+
+      const getNodeResourceKey = useCallback(
+        (node: CustomNode, label: string) => {
+          if (
+            node.type === "messageGroup" ||
+            node.type === "messageGroupExpanded"
+          ) {
+            return `${node.type}:${node.id}`.toLowerCase();
+          }
+
+          const data = node.data as any;
+          const resource =
+            getNodeResourceData(data, "message") ||
+            getNodeResourceData(data, "agent") ||
+            getNodeResourceData(data, "agentTool") ||
+            getNodeResourceData(data, "service") ||
+            getNodeResourceData(data, "domain") ||
+            getNodeResourceData(data, "system") ||
+            getNodeResourceData(data, "entity") ||
+            getNodeResourceData(data, "channel") ||
+            getNodeResourceData(data, "dataProduct") ||
+            data?.data ||
+            data;
+
+          return getResourceKey({
+            type: node.type || "unknown",
+            id: resource?.id,
+            name: resource?.name || resource?.id || label || node.id,
+            version: resource?.version || data?.version,
+          });
+        },
+        [],
+      );
+
+      const dedupeSearchSuggestions = useCallback(
+        (suggestions: SearchSuggestion[]) => {
+          const uniqueSuggestions: SearchSuggestion[] = [];
+          const indexByResourceKey = new Map<string, number>();
+
+          suggestions.forEach((suggestion) => {
+            const existingIndex = indexByResourceKey.get(
+              suggestion.resourceKey,
+            );
+
+            if (existingIndex === undefined) {
+              indexByResourceKey.set(
+                suggestion.resourceKey,
+                uniqueSuggestions.length,
+              );
+              uniqueSuggestions.push(suggestion);
+              return;
+            }
+
+            if (
+              suggestion.isGroupedMessage &&
+              !uniqueSuggestions[existingIndex].isGroupedMessage
+            ) {
+              uniqueSuggestions[existingIndex] = suggestion;
+            }
+          });
+
+          return uniqueSuggestions;
+        },
+        [],
+      );
+
+      const getSearchSuggestions = useCallback(
+        (nodesToIndex: CustomNode[]): SearchSuggestion[] => {
+          const suggestions = nodesToIndex.flatMap((node) => {
+            // Boundary/container nodes aren't searchable resources — e.g. the
+            // system-group wrapper on a System Diagram. Skip them so they don't
+            // appear in the "Search Nodes" filter.
+            if (node.type === "system-group") return [];
+
+            const nodeName = getNodeDisplayName(node);
+            const suggestions: SearchSuggestion[] = [
+              {
+                key: node.id,
+                node,
+                label: nodeName,
+                searchText: nodeName,
+                type: node.type || "unknown",
+                resourceKey: getNodeResourceKey(node, nodeName),
+              },
+            ];
+
+            if (node.type !== "messageGroup") return suggestions;
+
+            const groupName = node.data?.groupName || nodeName;
+            const groupedMessages = node.data?.messages || [];
+            groupedMessages.forEach((item, index) => {
+              const message = item.message;
+              const messageName = message?.data?.name || message?.data?.id;
+              if (!messageName) return;
+
+              const version = message?.data?.version;
+              const label = formatVersionedName(messageName, version);
+
+              suggestions.push({
+                key: `${node.id}:${message?.data?.id || messageName}:${version || index}`,
+                node,
+                label,
+                searchText: `${label} ${groupName}`,
+                type: message?.collection || "message",
+                resourceKey: getResourceKey({
+                  type: message?.collection || "message",
+                  id: message?.data?.id,
+                  name: messageName,
+                  version,
+                }),
+                groupName,
+                isGroupedMessage: true,
+              });
+            });
+
+            return suggestions;
+          });
+
+          return dedupeSearchSuggestions(suggestions);
+        },
+        [dedupeSearchSuggestions, getNodeDisplayName, getNodeResourceKey],
+      );
+
+      const getNodeTypeMeta = useCallback((nodeType: string): NodeTypeMeta => {
+        const meta: Record<string, NodeTypeMeta> = {
+          events: {
+            label: "Event",
+            Icon: Zap,
+            iconClass: "border-orange-500/25 bg-orange-500/10 text-orange-500",
+            badgeClass:
+              "border-orange-500/25 bg-orange-500/10 text-orange-700 dark:text-orange-300",
+          },
+          event: {
+            label: "Event",
+            Icon: Zap,
+            iconClass: "border-orange-500/25 bg-orange-500/10 text-orange-500",
+            badgeClass:
+              "border-orange-500/25 bg-orange-500/10 text-orange-700 dark:text-orange-300",
+          },
+          commands: {
+            label: "Command",
+            Icon: MessageSquare,
+            iconClass: "border-blue-500/25 bg-blue-500/10 text-blue-500",
+            badgeClass:
+              "border-blue-500/25 bg-blue-500/10 text-blue-700 dark:text-blue-300",
+          },
+          command: {
+            label: "Command",
+            Icon: MessageSquare,
+            iconClass: "border-blue-500/25 bg-blue-500/10 text-blue-500",
+            badgeClass:
+              "border-blue-500/25 bg-blue-500/10 text-blue-700 dark:text-blue-300",
+          },
+          queries: {
+            label: "Query",
+            Icon: SearchIcon,
+            iconClass: "border-green-500/25 bg-green-500/10 text-green-500",
+            badgeClass:
+              "border-green-500/25 bg-green-500/10 text-green-700 dark:text-green-300",
+          },
+          query: {
+            label: "Query",
+            Icon: SearchIcon,
+            iconClass: "border-green-500/25 bg-green-500/10 text-green-500",
+            badgeClass:
+              "border-green-500/25 bg-green-500/10 text-green-700 dark:text-green-300",
+          },
+          services: {
+            label: "Service",
+            Icon: Server,
+            iconClass: "border-pink-500/25 bg-pink-500/10 text-pink-500",
+            badgeClass:
+              "border-pink-500/25 bg-pink-500/10 text-pink-700 dark:text-pink-300",
+          },
+          agents: {
+            label: "Agent",
+            Icon: Bot,
+            iconClass: "border-sky-500/25 bg-sky-500/10 text-sky-500",
+            badgeClass:
+              "border-sky-500/25 bg-sky-500/10 text-sky-700 dark:text-sky-300",
+          },
+          agent: {
+            label: "Agent",
+            Icon: Bot,
+            iconClass: "border-sky-500/25 bg-sky-500/10 text-sky-500",
+            badgeClass:
+              "border-sky-500/25 bg-sky-500/10 text-sky-700 dark:text-sky-300",
+          },
+          agentTool: {
+            label: "Agent Tool",
+            Icon: Wrench,
+            iconClass: "border-violet-500/25 bg-violet-500/10 text-violet-500",
+            badgeClass:
+              "border-violet-500/25 bg-violet-500/10 text-violet-700 dark:text-violet-300",
+          },
+          "agent-tool": {
+            label: "Agent Tool",
+            Icon: Wrench,
+            iconClass: "border-violet-500/25 bg-violet-500/10 text-violet-500",
+            badgeClass:
+              "border-violet-500/25 bg-violet-500/10 text-violet-700 dark:text-violet-300",
+          },
+          domains: {
+            label: "Domain",
+            Icon: Blocks,
+            iconClass:
+              "border-yellow-500/25 bg-yellow-500/10 text-yellow-600 dark:text-yellow-400",
+            badgeClass:
+              "border-yellow-500/25 bg-yellow-500/10 text-yellow-700 dark:text-yellow-300",
+          },
+          systems: {
+            label: "System",
+            Icon: Group,
+            iconClass: "border-violet-500/25 bg-violet-500/10 text-violet-500",
+            badgeClass:
+              "border-violet-500/25 bg-violet-500/10 text-violet-700 dark:text-violet-300",
+          },
+          flows: {
+            label: "Flow",
+            Icon: Workflow,
+            iconClass: "border-teal-500/25 bg-teal-500/10 text-teal-500",
+            badgeClass:
+              "border-teal-500/25 bg-teal-500/10 text-teal-700 dark:text-teal-300",
+          },
+          channels: {
+            label: "Channel",
+            Icon: ListTree,
+            iconClass: "border-gray-500/25 bg-gray-500/10 text-gray-500",
+            badgeClass:
+              "border-gray-500/25 bg-gray-500/10 text-gray-700 dark:text-gray-300",
+          },
+          data: {
+            label: "Data",
+            Icon: Database,
+            iconClass: "border-blue-500/25 bg-blue-500/10 text-blue-500",
+            badgeClass:
+              "border-blue-500/25 bg-blue-500/10 text-blue-700 dark:text-blue-300",
+          },
+          entities: {
+            label: "Entity",
+            Icon: Database,
+            iconClass: "border-blue-500/25 bg-blue-500/10 text-blue-500",
+            badgeClass:
+              "border-blue-500/25 bg-blue-500/10 text-blue-700 dark:text-blue-300",
+          },
+          externalSystem: {
+            label: "External",
+            Icon: Server,
+            iconClass: "border-pink-500/25 bg-pink-500/10 text-pink-500",
+            badgeClass:
+              "border-pink-500/25 bg-pink-500/10 text-pink-700 dark:text-pink-300",
+          },
+          actor: {
+            label: "Actor",
+            Icon: User,
+            iconClass:
+              "border-yellow-500/25 bg-yellow-500/10 text-yellow-600 dark:text-yellow-400",
+            badgeClass:
+              "border-yellow-500/25 bg-yellow-500/10 text-yellow-700 dark:text-yellow-300",
+          },
+          "context-actor": {
+            label: "Actor",
+            Icon: User,
+            iconClass:
+              "border-yellow-500/25 bg-yellow-500/10 text-yellow-600 dark:text-yellow-400",
+            badgeClass:
+              "border-yellow-500/25 bg-yellow-500/10 text-yellow-700 dark:text-yellow-300",
+          },
+          user: {
+            label: "User",
+            Icon: User,
+            iconClass:
+              "border-yellow-500/25 bg-yellow-500/10 text-yellow-600 dark:text-yellow-400",
+            badgeClass:
+              "border-yellow-500/25 bg-yellow-500/10 text-yellow-700 dark:text-yellow-300",
+          },
+          messageGroup: {
+            label: "Group",
+            Icon: Layers,
+            iconClass: "border-violet-500/25 bg-violet-500/10 text-violet-500",
+            badgeClass:
+              "border-violet-500/25 bg-violet-500/10 text-violet-700 dark:text-violet-300",
+          },
+          messageGroupExpanded: {
+            label: "Group",
+            Icon: Layers,
+            iconClass: "border-violet-500/25 bg-violet-500/10 text-violet-500",
+            badgeClass:
+              "border-violet-500/25 bg-violet-500/10 text-violet-700 dark:text-violet-300",
+          },
+        };
+
+        return (
+          meta[nodeType] || {
+            label: nodeType,
+            Icon: Layers,
+            iconClass: "border-gray-500/25 bg-gray-500/10 text-gray-500",
+            badgeClass:
+              "border-gray-500/25 bg-gray-500/10 text-gray-700 dark:text-gray-300",
+          }
+        );
+      }, []);
+
+      const handleSearchChange = useCallback(
+        (event: React.ChangeEvent<HTMLInputElement>) => {
+          const query = event.target.value;
+          setSearchQuery(query);
+
+          if (query.length > 0) {
+            const search = query.toLowerCase();
+            const filtered = getSearchSuggestions(nodes).filter((suggestion) =>
+              suggestion.searchText.toLowerCase().includes(search),
+            );
+            setFilteredSuggestions(filtered);
+            setShowSuggestions(true);
+            setSelectedSuggestionIndex(-1);
+          } else {
+            setFilteredSuggestions(getSearchSuggestions(nodes));
+            setShowSuggestions(true);
+            setSelectedSuggestionIndex(-1);
+          }
+        },
+        [nodes, getSearchSuggestions],
+      );
+
+      const handleSearchFocus = useCallback(() => {
+        const suggestions = getSearchSuggestions(nodes);
+        const search = searchQuery.toLowerCase();
+        setFilteredSuggestions(
+          searchQuery.length === 0
+            ? suggestions
+            : suggestions.filter((suggestion) =>
+                suggestion.searchText.toLowerCase().includes(search),
+              ),
+        );
+        setShowSuggestions(true);
+        setSelectedSuggestionIndex(-1);
+      }, [nodes, searchQuery, getSearchSuggestions]);
+
+      const handleSuggestionClick = useCallback(
+        (suggestion: SearchSuggestion) => {
+          setSearchQuery("");
+          setFilteredSuggestions([]);
+          setShowSuggestions(false);
+          setSelectedSuggestionIndex(-1);
+          onNodeSelect(suggestion.node);
+        },
+        [onNodeSelect],
+      );
+
+      const handleSearchKeyDown = useCallback(
+        (event: React.KeyboardEvent<HTMLInputElement>) => {
+          switch (event.key) {
+            case "ArrowDown":
+              event.preventDefault();
+              if (filteredSuggestions.length === 0) return;
+              setShowSuggestions(true);
+              setSelectedSuggestionIndex((prev) =>
+                prev < filteredSuggestions.length - 1 ? prev + 1 : 0,
+              );
+              break;
+            case "ArrowUp":
+              event.preventDefault();
+              if (filteredSuggestions.length === 0) return;
+              setShowSuggestions(true);
+              setSelectedSuggestionIndex((prev) =>
+                prev > 0 ? prev - 1 : filteredSuggestions.length - 1,
+              );
+              break;
+            case "Enter":
+              event.preventDefault();
+              if (
+                showSuggestions &&
+                selectedSuggestionIndex >= 0 &&
+                selectedSuggestionIndex < filteredSuggestions.length
+              ) {
+                handleSuggestionClick(
+                  filteredSuggestions[selectedSuggestionIndex],
+                );
+              }
+              break;
+            case "Escape":
+              setShowSuggestions(false);
+              setSelectedSuggestionIndex(-1);
+              break;
+          }
+        },
+        [
+          showSuggestions,
+          filteredSuggestions,
+          selectedSuggestionIndex,
+          handleSuggestionClick,
+        ],
+      );
+
+      const clearSearch = useCallback(() => {
+        setSearchQuery("");
+        setShowSuggestions(false);
+        setFilteredSuggestions([]);
+        setSelectedSuggestionIndex(-1);
+        onClear();
+        if (searchInputRef.current) {
+          searchInputRef.current.focus();
+        }
+      }, [onClear]);
+
+      useEffect(() => {
+        suggestionItemRefs.current = suggestionItemRefs.current.slice(
+          0,
+          filteredSuggestions.length,
+        );
+      }, [filteredSuggestions.length]);
+
+      useEffect(() => {
+        if (!showSuggestions || selectedSuggestionIndex < 0) return;
+
+        const list = suggestionsListRef.current;
+        const item = suggestionItemRefs.current[selectedSuggestionIndex];
+        if (!list || !item) return;
+
+        const itemTop = item.offsetTop;
+        const itemBottom = itemTop + item.offsetHeight;
+        const visibleTop = list.scrollTop;
+        const visibleBottom = visibleTop + list.clientHeight;
+
+        if (itemTop < visibleTop) {
+          list.scrollTop = itemTop;
+        } else if (itemBottom > visibleBottom) {
+          list.scrollTop = itemBottom - list.clientHeight;
+        }
+      }, [
+        showSuggestions,
+        selectedSuggestionIndex,
+        filteredSuggestions.length,
+      ]);
+
+      // Close suggestions when clicking outside
+      useEffect(() => {
+        const handleClickOutside = (event: MouseEvent) => {
+          if (
+            containerRef.current &&
+            !containerRef.current.contains(event.target as any)
+          ) {
+            setShowSuggestions(false);
+            setSelectedSuggestionIndex(-1);
+          }
+        };
+
+        document.addEventListener("mousedown", handleClickOutside);
+        return () => {
+          document.removeEventListener("mousedown", handleClickOutside);
+        };
+      }, []);
+
+      return (
+        <div ref={containerRef} className="w-full max-w-md mx-auto relative">
+          <div className="relative">
+            <input
+              ref={searchInputRef}
+              type="text"
+              placeholder="Search nodes..."
+              value={searchQuery}
+              onChange={handleSearchChange}
+              onKeyDown={handleSearchKeyDown}
+              onFocus={handleSearchFocus}
+              className="w-full px-4 py-2 pr-10 bg-[rgb(var(--ec-input-bg))] border border-[rgb(var(--ec-input-border))] text-[rgb(var(--ec-input-text))] placeholder:text-[rgb(var(--ec-page-text-muted))] rounded-md shadow-sm focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent))] focus:border-transparent"
+            />
+            {searchQuery && (
+              <button
+                onClick={clearSearch}
+                className="absolute right-2 top-1/2 transform -translate-y-1/2 text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]"
+                aria-label="Clear search"
+              >
+                <svg
+                  className="w-5 h-5"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={2}
+                    d="M6 18L18 6M6 6l12 12"
+                  />
+                </svg>
+              </button>
+            )}
+          </div>
+          {showSuggestions && filteredSuggestions.length > 0 && (
+            <div
+              ref={suggestionsListRef}
+              className="absolute top-full left-0 right-0 mt-1 bg-[rgb(var(--ec-card-bg))] border border-[rgb(var(--ec-page-border))] rounded-md shadow-lg z-50 max-h-60 overflow-y-auto"
+            >
+              {filteredSuggestions.map((suggestion, index) => {
+                const nodeTypeMeta = getNodeTypeMeta(suggestion.type);
+                const Icon = nodeTypeMeta.Icon;
+                const isSelected = index === selectedSuggestionIndex;
+                return (
+                  <div
+                    key={`${suggestion.key}:${index}`}
+                    ref={(element) => {
+                      suggestionItemRefs.current[index] = element;
+                    }}
+                    onClick={() => handleSuggestionClick(suggestion)}
+                    onMouseEnter={() => setSelectedSuggestionIndex(index)}
+                    className={`px-3 py-2 cursor-pointer flex items-start gap-3 ${
+                      isSelected
+                        ? "bg-[rgb(var(--ec-accent-subtle))] outline outline-1 -outline-offset-1 outline-[rgb(var(--ec-accent))]"
+                        : "hover:bg-[rgb(var(--ec-page-border)/0.5)]"
+                    }`}
+                  >
+                    <span
+                      className={`mt-0.5 flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-md border ${nodeTypeMeta.iconClass}`}
+                    >
+                      <Icon className="h-3.5 w-3.5" />
+                    </span>
+                    <span className="min-w-0 flex-1">
+                      <span className="block truncate text-sm font-medium text-[rgb(var(--ec-page-text))]">
+                        {suggestion.label}
+                      </span>
+                      {suggestion.isGroupedMessage && suggestion.groupName && (
+                        <span className="mt-0.5 block truncate text-xs text-[rgb(var(--ec-page-text-muted))]">
+                          in {suggestion.groupName}
+                        </span>
+                      )}
+                    </span>
+                    <span
+                      className={`mt-0.5 flex-shrink-0 rounded border px-2 py-0.5 text-xs font-medium ${nodeTypeMeta.badgeClass}`}
+                    >
+                      {nodeTypeMeta.label}
+                    </span>
+                  </div>
+                );
+              })}
+            </div>
+          )}
+        </div>
+      );
+    },
+  ),
+);
+
+VisualiserSearch.displayName = "VisualiserSearch";
+
+export default VisualiserSearch;
diff --git a/packages/visualiser/src/components/VisualizerDropdownContent.tsx b/packages/visualiser/src/components/VisualizerDropdownContent.tsx
new file mode 100644
index 000000000..24ee06085
--- /dev/null
+++ b/packages/visualiser/src/components/VisualizerDropdownContent.tsx
@@ -0,0 +1,388 @@
+import React, { type RefObject, useState, memo } from "react";
+import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
+import { usePortalContainer } from "../context/PortalContainerContext";
+import {
+  Code,
+  Share2,
+  Search,
+  Grid3x3,
+  Maximize2,
+  Map,
+  Sparkles,
+  Zap,
+  EyeOff,
+  ExternalLink,
+  Save,
+  RotateCcw,
+  Loader2,
+  MessageCircle,
+} from "lucide-react";
+import {
+  DocumentArrowDownIcon,
+  PresentationChartLineIcon,
+} from "@heroicons/react/24/outline";
+import type { VisualiserSearchRef } from "./VisualiserSearch";
+
+interface VisualizerDropdownContentProps {
+  isMermaidView: boolean;
+  setIsMermaidView: (value: boolean) => void;
+  animateMessages: boolean;
+  toggleAnimateMessages: () => void;
+  /** Hide the "Simulate Messages" toggle entirely (e.g. on the Context Diagram). */
+  hideAnimateMessages?: boolean;
+  hideChannels: boolean;
+  toggleChannelsVisibility: () => void;
+  hasChannels: boolean;
+  showMinimap: boolean;
+  setShowMinimap: (value: boolean) => void;
+  handleFitView: () => void;
+  searchRef: RefObject<VisualiserSearchRef | null>;
+  isChatEnabled: boolean;
+  openChat: () => void;
+  handleCopyArchitectureCode: () => void;
+  handleExportVisual: () => void;
+  setIsShareModalOpen: (value: boolean) => void;
+  toggleFullScreen: () => void;
+  openStudioModal: () => void;
+  isDevMode?: boolean;
+  onSaveLayout?: () => Promise<boolean>;
+  onResetLayout?: () => Promise<boolean>;
+  notesCount?: number;
+  onOpenNotes?: () => void;
+}
+
+const VisualizerDropdownContent: React.FC<VisualizerDropdownContentProps> =
+  memo(
+    ({
+      isMermaidView,
+      setIsMermaidView,
+      animateMessages,
+      toggleAnimateMessages,
+      hideAnimateMessages = false,
+      hideChannels,
+      toggleChannelsVisibility,
+      hasChannels,
+      showMinimap,
+      setShowMinimap,
+      handleFitView,
+      searchRef,
+      isChatEnabled,
+      openChat,
+      handleCopyArchitectureCode,
+      handleExportVisual,
+      setIsShareModalOpen,
+      toggleFullScreen,
+      openStudioModal,
+      isDevMode = false,
+      onSaveLayout,
+      onResetLayout,
+      notesCount = 0,
+      onOpenNotes,
+    }) => {
+      const [layoutStatus, setLayoutStatus] = useState<
+        "idle" | "saving" | "resetting"
+      >("idle");
+      const portalContainer = usePortalContainer();
+
+      const handleSaveLayout = async () => {
+        if (!onSaveLayout) return;
+        setLayoutStatus("saving");
+        await onSaveLayout();
+        setLayoutStatus("idle");
+      };
+
+      const handleResetLayout = async () => {
+        if (!onResetLayout) return;
+        if (
+          !window.confirm(
+            "Reset layout to auto-positioning? This will delete your saved layout.",
+          )
+        ) {
+          return;
+        }
+        setLayoutStatus("resetting");
+        const success = await onResetLayout();
+        if (success) {
+          window.location.reload();
+        } else {
+          setLayoutStatus("idle");
+        }
+      };
+
+      return (
+        <>
+          {/* Canvas Settings Submenu */}
+          <DropdownMenu.Sub>
+            <DropdownMenu.SubTrigger className="flex items-center px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer transition-colors gap-2 outline-none">
+              <Grid3x3 className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+              <span className="flex-1 font-normal">Canvas</span>
+              <svg
+                className="w-3 h-3 text-[rgb(var(--ec-page-text-muted))]"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M9 5l7 7-7 7"
+                />
+              </svg>
+            </DropdownMenu.SubTrigger>
+            <DropdownMenu.Portal container={portalContainer}>
+              <DropdownMenu.SubContent
+                className="min-w-[200px] bg-[rgb(var(--ec-card-bg))] rounded-lg shadow-xl border border-[rgb(var(--ec-page-border))] py-1.5 z-[60]"
+                sideOffset={8}
+                alignOffset={-8}
+              >
+                <DropdownMenu.CheckboxItem
+                  checked={isMermaidView}
+                  onCheckedChange={setIsMermaidView}
+                  className="flex items-center px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer transition-colors gap-2"
+                >
+                  <Code className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+                  <span className="flex-1 font-normal">Render as mermaid</span>
+                  <div
+                    className={`w-7 h-4 rounded-full transition-all duration-200 flex-shrink-0 relative ${isMermaidView ? "bg-[rgb(var(--ec-accent))]" : "bg-[rgb(var(--ec-page-border))]"}`}
+                  >
+                    <div
+                      className={`absolute top-0.5 w-3 h-3 rounded-full bg-white shadow-sm transition-all duration-200 ${isMermaidView ? "left-3.5" : "left-0.5"}`}
+                    />
+                  </div>
+                </DropdownMenu.CheckboxItem>
+
+                {!hideAnimateMessages && (
+                  <>
+                    <DropdownMenu.Separator className="my-1 h-px bg-[rgb(var(--ec-page-border))]" />
+
+                    <DropdownMenu.CheckboxItem
+                      checked={animateMessages}
+                      onCheckedChange={toggleAnimateMessages}
+                      className="flex items-center px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer transition-colors gap-2"
+                    >
+                      <Zap className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+                      <span className="flex-1 font-normal">
+                        Simulate Messages
+                      </span>
+                      <div
+                        className={`w-7 h-4 rounded-full transition-all duration-200 flex-shrink-0 relative ${animateMessages ? "bg-[rgb(var(--ec-accent))]" : "bg-[rgb(var(--ec-page-border))]"}`}
+                      >
+                        <div
+                          className={`absolute top-0.5 w-3 h-3 rounded-full bg-white shadow-sm transition-all duration-200 ${animateMessages ? "left-3.5" : "left-0.5"}`}
+                        />
+                      </div>
+                    </DropdownMenu.CheckboxItem>
+                  </>
+                )}
+
+                {hasChannels && (
+                  <DropdownMenu.CheckboxItem
+                    checked={hideChannels}
+                    onCheckedChange={toggleChannelsVisibility}
+                    className="flex items-center px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer transition-colors gap-2"
+                  >
+                    <EyeOff className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+                    <span className="flex-1 font-normal">Hide channels</span>
+                    <div
+                      className={`w-7 h-4 rounded-full transition-all duration-200 flex-shrink-0 relative ${hideChannels ? "bg-[rgb(var(--ec-accent))]" : "bg-[rgb(var(--ec-page-border))]"}`}
+                    >
+                      <div
+                        className={`absolute top-0.5 w-3 h-3 rounded-full bg-white shadow-sm transition-all duration-200 ${hideChannels ? "left-3.5" : "left-0.5"}`}
+                      />
+                    </div>
+                  </DropdownMenu.CheckboxItem>
+                )}
+
+                <DropdownMenu.CheckboxItem
+                  checked={showMinimap}
+                  onCheckedChange={setShowMinimap}
+                  className="flex items-center px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer transition-colors gap-2"
+                >
+                  <Map className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+                  <span className="flex-1 font-normal">Show minimap</span>
+                  <div
+                    className={`w-7 h-4 rounded-full transition-all duration-200 flex-shrink-0 relative ${showMinimap ? "bg-[rgb(var(--ec-accent))]" : "bg-[rgb(var(--ec-page-border))]"}`}
+                  >
+                    <div
+                      className={`absolute top-0.5 w-3 h-3 rounded-full bg-white shadow-sm transition-all duration-200 ${showMinimap ? "left-3.5" : "left-0.5"}`}
+                    />
+                  </div>
+                </DropdownMenu.CheckboxItem>
+
+                <DropdownMenu.Separator className="my-1 h-px bg-[rgb(var(--ec-page-border))]" />
+
+                <DropdownMenu.Item
+                  onClick={handleFitView}
+                  className="px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer flex items-center gap-2 transition-colors"
+                >
+                  <Maximize2 className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+                  <span className="flex-1 font-normal">Fit to view</span>
+                </DropdownMenu.Item>
+
+                <DropdownMenu.Item
+                  onClick={() => {
+                    searchRef.current?.hideSuggestions();
+                    setTimeout(() => {
+                      const searchInput = document.querySelector(
+                        'input[placeholder="Search nodes..."]',
+                      ) as HTMLInputElement;
+                      searchInput?.focus();
+                    }, 50);
+                  }}
+                  className="px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer flex items-center gap-2 transition-colors"
+                >
+                  <Search className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+                  <span className="flex-1 font-normal">Find on canvas</span>
+                </DropdownMenu.Item>
+              </DropdownMenu.SubContent>
+            </DropdownMenu.Portal>
+          </DropdownMenu.Sub>
+
+          {/* Notes */}
+          {notesCount > 0 && onOpenNotes && (
+            <DropdownMenu.Item
+              onClick={onOpenNotes}
+              className="px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer flex items-center gap-2 transition-colors"
+            >
+              <MessageCircle className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+              <span className="flex-1 font-normal">
+                View notes ({notesCount})
+              </span>
+            </DropdownMenu.Item>
+          )}
+
+          {/* Dev Mode: Layout Submenu */}
+          {isDevMode && onSaveLayout && (
+            <DropdownMenu.Sub>
+              <DropdownMenu.SubTrigger className="flex items-center px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer transition-colors gap-2 outline-none">
+                <Save className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+                <span className="flex-1 font-normal">Layout</span>
+                <span className="text-[10px] text-amber-600 font-medium">
+                  DEV
+                </span>
+                <svg
+                  className="w-3 h-3 text-[rgb(var(--ec-page-text-muted))]"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                  stroke="currentColor"
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={2}
+                    d="M9 5l7 7-7 7"
+                  />
+                </svg>
+              </DropdownMenu.SubTrigger>
+              <DropdownMenu.Portal container={portalContainer}>
+                <DropdownMenu.SubContent
+                  className="min-w-[180px] bg-[rgb(var(--ec-card-bg))] rounded-lg shadow-xl border border-[rgb(var(--ec-page-border))] py-1.5 z-[60]"
+                  sideOffset={8}
+                  alignOffset={-8}
+                >
+                  <DropdownMenu.Item
+                    onClick={handleSaveLayout}
+                    disabled={layoutStatus !== "idle"}
+                    className="px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer flex items-center gap-2 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+                  >
+                    {layoutStatus === "saving" ? (
+                      <Loader2 className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0 animate-spin" />
+                    ) : (
+                      <Save className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+                    )}
+                    <span className="flex-1 font-normal">
+                      {layoutStatus === "saving" ? "Saving..." : "Save Layout"}
+                    </span>
+                  </DropdownMenu.Item>
+                  <DropdownMenu.Item
+                    onClick={handleResetLayout}
+                    disabled={layoutStatus !== "idle"}
+                    className="px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer flex items-center gap-2 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+                  >
+                    {layoutStatus === "resetting" ? (
+                      <Loader2 className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0 animate-spin" />
+                    ) : (
+                      <RotateCcw className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+                    )}
+                    <span className="flex-1 font-normal">
+                      {layoutStatus === "resetting"
+                        ? "Resetting..."
+                        : "Reset Layout"}
+                    </span>
+                  </DropdownMenu.Item>
+                </DropdownMenu.SubContent>
+              </DropdownMenu.Portal>
+            </DropdownMenu.Sub>
+          )}
+
+          {/* Ask AI */}
+          {isChatEnabled && (
+            <>
+              <DropdownMenu.Separator className="my-1 h-px bg-[rgb(var(--ec-page-border))]" />
+              <DropdownMenu.Item
+                onClick={openChat}
+                className="px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer flex items-center gap-2 transition-colors"
+              >
+                <Sparkles className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+                <span className="flex-1 font-normal">Ask a question</span>
+              </DropdownMenu.Item>
+            </>
+          )}
+
+          {/* Export Items */}
+          <DropdownMenu.Separator className="my-1 h-px bg-[rgb(var(--ec-page-border))]" />
+          <DropdownMenu.Item
+            onClick={handleCopyArchitectureCode}
+            className="px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer flex items-center gap-2 transition-colors"
+          >
+            <Code className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+            <span className="flex-1 font-normal">Copy as mermaid</span>
+          </DropdownMenu.Item>
+
+          <DropdownMenu.Item
+            onClick={handleExportVisual}
+            className="px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer flex items-center gap-2 transition-colors"
+          >
+            <DocumentArrowDownIcon className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+            <span className="flex-1 font-normal">Export image</span>
+          </DropdownMenu.Item>
+
+          {/* Share Link */}
+          <DropdownMenu.Item
+            onClick={() => setIsShareModalOpen(true)}
+            className="px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer flex items-center gap-2 transition-colors"
+          >
+            <Share2 className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+            <span className="flex-1 font-normal">Share Link</span>
+          </DropdownMenu.Item>
+
+          {/* Start Presentation */}
+          <DropdownMenu.Separator className="my-1 h-px bg-[rgb(var(--ec-page-border))]" />
+          <DropdownMenu.Item
+            onClick={toggleFullScreen}
+            className="px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer flex items-center gap-2 transition-colors"
+          >
+            <PresentationChartLineIcon className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+            <span className="flex-1 font-normal">Start Presentation</span>
+          </DropdownMenu.Item>
+
+          {/* Open in EventCatalog Studio */}
+          <DropdownMenu.Separator className="my-1 h-px bg-[rgb(var(--ec-page-border))]" />
+          <DropdownMenu.Item
+            onClick={openStudioModal}
+            className="px-3 py-2 text-xs text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.3)] cursor-pointer flex items-center gap-2 transition-colors"
+          >
+            <ExternalLink className="w-3.5 h-3.5 text-[rgb(var(--ec-page-text-muted))] flex-shrink-0" />
+            <span className="flex-1 font-normal">
+              Open in EventCatalog Studio
+            </span>
+          </DropdownMenu.Item>
+        </>
+      );
+    },
+  );
+
+VisualizerDropdownContent.displayName = "VisualizerDropdownContent";
+
+export default VisualizerDropdownContent;
diff --git a/packages/visualiser/src/components/index.ts b/packages/visualiser/src/components/index.ts
new file mode 100644
index 000000000..c5a3bde36
--- /dev/null
+++ b/packages/visualiser/src/components/index.ts
@@ -0,0 +1,11 @@
+/**
+ * Visualizer components
+ */
+
+export { default as NodeGraph } from "./NodeGraph";
+export type { NodeGraphProps } from "./NodeGraph";
+export { default as MermaidView } from "./MermaidView";
+export { default as VisualiserSearch } from "./VisualiserSearch";
+export { default as StepWalkthrough } from "./StepWalkthrough";
+export { default as FocusModeModal } from "./FocusModeModal";
+export { default as NodeContextMenu } from "./NodeContextMenu";
diff --git a/packages/visualiser/src/context/PortalContainerContext.tsx b/packages/visualiser/src/context/PortalContainerContext.tsx
new file mode 100644
index 000000000..9b57f5063
--- /dev/null
+++ b/packages/visualiser/src/context/PortalContainerContext.tsx
@@ -0,0 +1,15 @@
+import { createContext, useContext } from "react";
+
+/**
+ * Context that provides a reference to the .eventcatalog-visualizer container element.
+ * Used by Radix UI portals so they render inside the scoped CSS boundary
+ * instead of at document.body.
+ */
+const PortalContainerContext = createContext<HTMLElement | null>(null);
+
+export const PortalContainerProvider = PortalContainerContext.Provider;
+
+export function usePortalContainer(): HTMLElement | undefined {
+  const container = useContext(PortalContainerContext);
+  return container ?? undefined;
+}
diff --git a/packages/visualiser/src/edges/AnimatedMessageEdge.tsx b/packages/visualiser/src/edges/AnimatedMessageEdge.tsx
new file mode 100644
index 000000000..f06150c58
--- /dev/null
+++ b/packages/visualiser/src/edges/AnimatedMessageEdge.tsx
@@ -0,0 +1,167 @@
+import { memo, useMemo } from "react";
+import { BaseEdge, getSmoothStepPath } from "@xyflow/react";
+import { EDGE_WARNING_STYLE, EDGE_DEFAULT_STYLE } from "../nodes/shared-styles";
+
+/** Map collection type → envelope fill color (module-level, zero allocation). */
+function messageColor(collection: string): string {
+  switch (collection) {
+    case "events":
+      return "orange";
+    case "commands":
+      return "blue";
+    case "queries":
+      return "green";
+    default:
+      return "gray";
+  }
+}
+
+const TSPAN_NORMAL_STYLE = { fontStyle: "normal" } as const;
+const TSPAN_ITALIC_STYLE = { fontStyle: "italic" } as const;
+
+const AnimatedMessageEdge = memo(
+  ({
+    id,
+    sourceX,
+    sourceY,
+    targetX,
+    targetY,
+    sourcePosition,
+    targetPosition,
+    data,
+    label = "",
+    markerEnd,
+    markerStart,
+  }: any) => {
+    const [edgePath, labelX, labelY] = getSmoothStepPath({
+      sourceX,
+      sourceY,
+      sourcePosition,
+      targetX,
+      targetY,
+      targetPosition,
+    });
+
+    const collection = data?.message?.collection;
+    const opacity = data?.opacity ?? 1;
+    const customColor =
+      data?.customColor || messageColor(collection ?? "default");
+    const warning = data?.warning;
+
+    const customColors = Array.isArray(customColor)
+      ? customColor
+      : [customColor];
+
+    const randomDelay = useMemo(() => Math.random() * 1, []);
+
+    const opacityClass = opacity === 1 ? "z-30 opacity-100" : "z-30 opacity-10";
+
+    const animatedNodes = useMemo(
+      () =>
+        customColors.map((color: string, index: number) => {
+          const delay = randomDelay + index * 0.3;
+          return (
+            <g
+              className={`ec-animated-msg ${opacityClass}`}
+              key={`${id}-${color}-${index}`}
+            >
+              <g>
+                <rect
+                  x="-7"
+                  y="-5"
+                  width="14"
+                  height="10"
+                  rx="1.5"
+                  ry="1.5"
+                  fill={color}
+                />
+                <path
+                  d="M-7,-5 L0,1 L7,-5"
+                  fill="none"
+                  stroke="rgb(var(--ec-card-bg))"
+                  strokeWidth="1.2"
+                  strokeLinejoin="round"
+                />
+                <animateMotion
+                  dur="2s"
+                  repeatCount="indefinite"
+                  path={edgePath}
+                  rotate="auto"
+                  begin={`${delay}s`}
+                >
+                  <mpath href={`#${id}`} />
+                </animateMotion>
+              </g>
+            </g>
+          );
+        }),
+      // edgePath changes when endpoints move — that's the only time we need to rebuild SVG
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [edgePath, id, customColors.join(","), opacity, randomDelay],
+    );
+
+    const lines = useMemo(() => String(label ?? "").split("\n"), [label]);
+    const longestLine = useMemo(
+      () =>
+        lines.reduce(
+          (a: string, b: string) => (a.length > b.length ? a : b),
+          "",
+        ),
+      [lines],
+    );
+    const labelWidth = Math.max(longestLine.length * 6.5 + 16, 50);
+    const firstLineDy = `${-((lines.length - 1) * 1.2) / 2}em`;
+
+    return (
+      <>
+        <BaseEdge
+          id={id}
+          path={edgePath}
+          markerEnd={markerEnd}
+          markerStart={markerStart}
+          style={warning ? EDGE_WARNING_STYLE : EDGE_DEFAULT_STYLE}
+        />
+        {animatedNodes}
+        <g>
+          {label && (
+            <rect
+              x={labelX - labelWidth / 2}
+              y={labelY - lines.length * 7 - 2}
+              width={labelWidth}
+              height={lines.length * 14 + 4}
+              fill="rgb(var(--ec-card-bg))"
+              fillOpacity={0.95}
+              stroke="rgb(var(--ec-page-border))"
+              strokeWidth={0.75}
+              rx={5}
+              ry={5}
+            />
+          )}
+          <text
+            x={labelX}
+            y={labelY}
+            textAnchor="middle"
+            dominantBaseline="middle"
+            fontSize="11px"
+            fontWeight={500}
+            fill="rgb(var(--ec-page-text))"
+            pointerEvents="none"
+          >
+            {lines.map((line: string, i: number) => (
+              <tspan
+                key={i}
+                x={labelX}
+                dy={i === 0 ? firstLineDy : "1.2em"}
+                style={i === 0 ? TSPAN_NORMAL_STYLE : TSPAN_ITALIC_STYLE}
+              >
+                {line}
+              </tspan>
+            ))}
+          </text>
+        </g>
+      </>
+    );
+  },
+);
+
+export default AnimatedMessageEdge;
diff --git a/packages/visualiser/src/edges/FlowEdge.tsx b/packages/visualiser/src/edges/FlowEdge.tsx
new file mode 100644
index 000000000..1838b007b
--- /dev/null
+++ b/packages/visualiser/src/edges/FlowEdge.tsx
@@ -0,0 +1,117 @@
+import { memo, useMemo } from "react";
+import {
+  BaseEdge,
+  EdgeLabelRenderer,
+  getSmoothStepPath,
+  type EdgeProps as XYFlowEdgeProps,
+} from "@xyflow/react";
+import { EDGE_FLOW_BASE_STYLE } from "../nodes/shared-styles";
+
+interface EdgeData {
+  message?: {
+    collection?: string;
+  };
+  opacity?: number;
+  animated?: boolean;
+}
+
+export interface CustomEdgeProps extends Omit<XYFlowEdgeProps, "data"> {
+  data?: EdgeData;
+}
+
+/** Map collection type → circle fill color (module-level, zero allocation). */
+function messageColor(collection: string): string {
+  switch (collection) {
+    case "events":
+      return "orange";
+    case "commands":
+      return "blue";
+    case "queries":
+      return "green";
+    default:
+      return "gray";
+  }
+}
+
+const EMPTY_STYLE = {} as const;
+
+export default memo(function CustomEdge({
+  id,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+  style = EMPTY_STYLE,
+  markerEnd,
+  label,
+  labelStyle,
+  data,
+}: CustomEdgeProps) {
+  const [edgePath, labelX, labelY] = getSmoothStepPath({
+    sourceX,
+    sourceY,
+    sourcePosition,
+    targetX,
+    targetY,
+    targetPosition,
+  });
+
+  const randomDelay = useMemo(() => Math.random() * 1, []);
+  const collection = data?.message?.collection;
+  const opacity = data?.opacity ?? 1;
+
+  const mergedStyle = useMemo(
+    () => ({ ...EDGE_FLOW_BASE_STYLE, ...style }),
+    [style],
+  );
+
+  const labelPositionStyle = useMemo(
+    () => ({
+      position: "absolute" as const,
+      transform: `translate(-50%, -50%) translate(${labelX}px,${labelY}px)`,
+      zIndex: 1000,
+      ...(labelStyle as any),
+    }),
+    [labelX, labelY, labelStyle],
+  );
+
+  return (
+    <>
+      <BaseEdge path={edgePath} markerEnd={markerEnd} style={mergedStyle} />
+      {data?.animated && (
+        <g
+          className={`ec-animated-msg z-30 ${opacity === 1 ? "opacity-100" : "opacity-10"}`}
+        >
+          <circle
+            cx="0"
+            cy="0"
+            r="7"
+            fill={messageColor(collection || "default")}
+          >
+            <animateMotion
+              dur="2s"
+              repeatCount="indefinite"
+              path={edgePath}
+              rotate="auto"
+              begin={`${randomDelay}s`}
+            >
+              <mpath href={`#${id}`} />
+            </animateMotion>
+          </circle>
+        </g>
+      )}
+      {label && (
+        <EdgeLabelRenderer>
+          <div
+            style={labelPositionStyle}
+            className="nodrag nopan max-w-[120px] text-xs bg-[rgb(var(--ec-card-bg))] px-2 py-1 rounded border border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text-muted))] font-medium shadow-sm text-center"
+          >
+            {label}
+          </div>
+        </EdgeLabelRenderer>
+      )}
+    </>
+  );
+});
diff --git a/packages/visualiser/src/edges/MultilineEdgeLabel.tsx b/packages/visualiser/src/edges/MultilineEdgeLabel.tsx
new file mode 100644
index 000000000..c6b9d1626
--- /dev/null
+++ b/packages/visualiser/src/edges/MultilineEdgeLabel.tsx
@@ -0,0 +1,93 @@
+import { memo, useMemo } from "react";
+import { type EdgeProps, getSmoothStepPath } from "@xyflow/react";
+
+const TSPAN_NORMAL_STYLE = { fontStyle: "normal" } as const;
+const TSPAN_ITALIC_STYLE = { fontStyle: "italic" } as const;
+
+export default memo(function MultilineEdgeLabel(props: EdgeProps) {
+  const {
+    id,
+    sourceX,
+    sourceY,
+    targetX,
+    targetY,
+    sourcePosition,
+    targetPosition,
+    label,
+    markerStart, // <-- forward these
+    markerEnd,
+    style,
+    selected,
+  } = props;
+
+  const [edgePath, labelX, labelY] = getSmoothStepPath({
+    sourceX,
+    sourceY,
+    targetX,
+    targetY,
+    sourcePosition,
+    targetPosition,
+  });
+
+  const lines = useMemo(() => String(label ?? "").split("\n"), [label]);
+  const firstLineDy = useMemo(
+    () => `${-((lines.length - 1) * 1.2) / 2}em`,
+    [lines.length],
+  );
+  const longestLine = useMemo(
+    () => lines.reduce((a, b) => (a.length > b.length ? a : b), ""),
+    [lines],
+  );
+  const labelWidth = Math.max(longestLine.length * 5.5 + 14, 44);
+  const labelHeight = lines.length * 12 + 4;
+
+  return (
+    <>
+      <path
+        id={id}
+        d={edgePath}
+        className={`react-flow__edge-path${selected ? " selected" : ""}`}
+        markerStart={markerStart}
+        markerEnd={markerEnd}
+        style={style as any}
+      />
+
+      {label && (
+        <rect
+          x={labelX - labelWidth / 2}
+          y={labelY - labelHeight / 2}
+          width={labelWidth}
+          height={labelHeight}
+          fill="rgb(var(--ec-card-bg))"
+          fillOpacity={0.95}
+          stroke="rgb(var(--ec-page-border))"
+          strokeWidth={0.75}
+          rx={5}
+          ry={5}
+          pointerEvents="none"
+        />
+      )}
+
+      <text
+        x={labelX}
+        y={labelY}
+        textAnchor="middle"
+        dominantBaseline="middle"
+        fontSize="10px"
+        fill="rgb(var(--ec-page-text))"
+        pointerEvents="none"
+      >
+        {lines.map((line, i) => (
+          <tspan
+            key={i}
+            x={labelX}
+            dy={i === 0 ? firstLineDy : "1.2em"}
+            style={i === 0 ? TSPAN_NORMAL_STYLE : TSPAN_ITALIC_STYLE}
+          >
+            {line}
+          </tspan>
+        ))}
+      </text>
+    </>
+  );
+});
diff --git a/packages/visualiser/src/edges/index.ts b/packages/visualiser/src/edges/index.ts
new file mode 100644
index 000000000..d70fdf9d4
--- /dev/null
+++ b/packages/visualiser/src/edges/index.ts
@@ -0,0 +1,18 @@
+/**
+ * Edge components for EventCatalog Visualizer
+ */
+
+// Import for edgeTypes object
+import AnimatedMessageEdge from "./AnimatedMessageEdge";
+import FlowEdge from "./FlowEdge";
+import MultilineEdgeLabel from "./MultilineEdgeLabel";
+
+// Re-export
+export { AnimatedMessageEdge, FlowEdge, MultilineEdgeLabel };
+
+// Re-export for convenience
+export const edgeTypes = {
+  animated: AnimatedMessageEdge,
+  "flow-edge": FlowEdge,
+  multiline: MultilineEdgeLabel,
+};
diff --git a/packages/visualiser/src/hooks/use-channel-visibility.ts b/packages/visualiser/src/hooks/use-channel-visibility.ts
new file mode 100644
index 000000000..cf74c73a2
--- /dev/null
+++ b/packages/visualiser/src/hooks/use-channel-visibility.ts
@@ -0,0 +1,142 @@
+import { useCallback, useMemo, useState, useEffect } from "react";
+import { type Edge, type Node } from "@xyflow/react";
+import {
+  createEdge,
+  generatedIdForEdge,
+  generateIdForNode,
+  getEdgeLabelForMessageAsSource,
+  getEdgeLabelForServiceAsTarget,
+  getNodesAndEdgesFromDagre,
+} from "../utils/utils/utils";
+
+interface ChannelVisibilityProps {
+  nodes: Node[];
+  edges: Edge[];
+  setNodes: (nodes: Node[]) => void;
+  setEdges: (edges: Edge[]) => void;
+  skipProcessing?: boolean;
+}
+
+export const useChannelVisibility = ({
+  nodes,
+  edges,
+  setNodes,
+  setEdges,
+  skipProcessing = false,
+}: ChannelVisibilityProps) => {
+  const [hideChannels, setHideChannels] = useState(false);
+  const [initialNodes, setInitialNodes] = useState(nodes);
+  const [initialEdges, setInitialEdges] = useState(edges);
+
+  // Initialize hideChannels from localStorage
+  useEffect(() => {
+    const storedHideChannels = localStorage.getItem(
+      "EventCatalog:hideChannels",
+    );
+    if (storedHideChannels !== null) {
+      setHideChannels(storedHideChannels === "true");
+    }
+  }, []);
+
+  useEffect(() => {
+    const hasChannels = nodes.some((node) => node.type === "channels");
+    if (!hideChannels || hasChannels) {
+      setInitialNodes(nodes);
+      setInitialEdges(edges);
+    }
+  }, [nodes, edges, hideChannels]);
+
+  const toggleChannelsVisibility = useCallback(() => {
+    setHideChannels((prev) => {
+      const newValue = !prev;
+      localStorage.setItem(
+        "EventCatalog:hideChannels",
+        JSON.stringify(newValue),
+      );
+      return newValue;
+    });
+  }, []);
+
+  const channels = useMemo(
+    () => nodes.filter((node) => node.type === "channels"),
+    [nodes],
+  );
+  const updatedNodes = useMemo(
+    () => nodes.filter((node) => node.type !== "channels"),
+    [nodes],
+  );
+
+  const updatedEdges = useMemo(() => {
+    const newEdges = edges.reduce<Edge[]>((acc, edge) => {
+      const { source, target, data } = edge;
+      const targetIsChannel = channels.some((channel) => channel.id === target);
+      const sourceIsChannel = channels.some((channel) => channel.id === source);
+
+      if (!sourceIsChannel && !targetIsChannel) {
+        return [...acc, edge];
+      }
+
+      if (sourceIsChannel || targetIsChannel) {
+        const rootSourceAndTarget = data?.rootSourceAndTarget as {
+          source: { id: string; collection: string };
+          target: { id: string; collection: string };
+        };
+
+        if (!rootSourceAndTarget) {
+          return [...acc, edge];
+        }
+
+        // is target a service-like resource?
+        const targetIsService =
+          rootSourceAndTarget?.target?.collection === "services" ||
+          rootSourceAndTarget?.target?.collection === "agents";
+        const edgeLabel = targetIsService
+          ? getEdgeLabelForMessageAsSource(rootSourceAndTarget.source as any)
+          : getEdgeLabelForServiceAsTarget(rootSourceAndTarget.target as any);
+
+        const newEdgeId = `${rootSourceAndTarget.source.id}-${rootSourceAndTarget.target.id}`;
+
+        return [
+          ...acc,
+          createEdge({
+            id: newEdgeId,
+            source: rootSourceAndTarget.source.id,
+            target: rootSourceAndTarget.target.id,
+            label: edgeLabel,
+          }),
+        ];
+      }
+      return acc;
+    }, []);
+
+    return newEdges.filter(
+      (edge, index, self) => index === self.findIndex((t) => t.id === edge.id),
+    );
+  }, [edges, channels]);
+
+  // console.log('UPDATED EDGES', JSON.stringify(updatedEdges, null, 2));
+
+  useEffect(() => {
+    // Skip processing if there are no channels to manage
+    if (skipProcessing) {
+      return;
+    }
+
+    if (hideChannels) {
+      const { nodes: newNodes, edges: newEdges } = getNodesAndEdgesFromDagre({
+        nodes: updatedNodes,
+        edges: updatedEdges,
+      });
+      setNodes(newNodes);
+      setEdges(newEdges);
+    } else {
+      setNodes(initialNodes);
+      setEdges(initialEdges);
+    }
+  }, [hideChannels, skipProcessing]);
+
+  return {
+    hideChannels,
+    toggleChannelsVisibility,
+  };
+};
diff --git a/packages/visualiser/src/icons/protocols/WebSocket.svg b/packages/visualiser/src/icons/protocols/WebSocket.svg
new file mode 100644
index 000000000..d03c4348b
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/WebSocket.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg id="b" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72"><g id="c"><circle cx="36" cy="36" r="36" fill="#333" stroke-width="0"/><path d="m48.38,23.39l7.48,7.48v15.98h-6.69v-13.15l-5.55-5.55,4.76-4.76Zm-7.14,33.55h-11.45l-7.48-7.48,4.65-4.65-11.56-11.56v-6.57h6.69v3.74l4.87,4.87,7.14-7.14-4.87-4.87h-13.83l-6.69-6.69h23.23l11.56,11.67-2.38,2.38,4.53,4.53v9.41l-9.29-9.29-2.38,2.38,9.29,9.29h-9.41l-4.65-4.65-2.38,2.38,5.55,5.55h23.35l6.69,6.57-21.19.11h0Z" fill="#fff" stroke-width="0"/></g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/amqp.svg b/packages/visualiser/src/icons/protocols/amqp.svg
new file mode 100644
index 000000000..ab9a73f49
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/amqp.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg id="b" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72"><g id="c"><circle cx="36" cy="36" r="36" fill="#333" stroke-width="0"/><path d="m14.13,14.18h12.24v12.45h-12.24v-12.45Zm0,15.75h15.54v-15.75h12.35v28.2H14.13v-12.45Zm43.74-3.51v31.4H14.24v-12.35h31.29V14.18h12.35v12.24Z" fill="#fff" stroke-width="0"/></g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/azure-eventgrid.svg b/packages/visualiser/src/icons/protocols/azure-eventgrid.svg
new file mode 100644
index 000000000..9950be117
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/azure-eventgrid.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 18 18"><defs><linearGradient id="a20547e5-d6af-456b-afbc-05d22ff8cb9d" x1="4589.72" y1="-5180.02" x2="4589.72" y2="-5184.21" gradientTransform="matrix(0.5, 0, 0, -0.5, -2275.31, -2589.32)" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#c69aeb" /><stop offset="1" stop-color="#6f4bb2" /></linearGradient><linearGradient id="a4745f51-5e75-4126-812d-6bb8a5130e16" x1="4587.99" y1="-5188.47" x2="4587.99" y2="-5192.65" href="#a20547e5-d6af-456b-afbc-05d22ff8cb9d" /></defs><title>Icon-integration-215</title><g><g id="b30b0bd5-e4d2-456b-8d49-c2df20200912"><path id="b51878b5-8d50-4b8b-bc48-74f5f7315a99" d="M12.7,8.15v-.6H8.18L6.06,9.66H4.5L8.12,6h2.47V5.43H7.87L3.65,9.66h-.6v.6H4.86L7,12.37H12.1v-.6H7.22L5.71,10.26H9.38v-.6H6.92l1.5-1.51Z" fill="#32bedd" /><circle id="ad0ed4eb-cd5f-4cc0-bd19-2830d27ec806" cx="9.98" cy="9.96" r="0.87" fill="#fff" /><circle id="a2746b4a-0ae4-4308-876e-5b82657e1872" cx="10.89" cy="5.74" r="0.87" fill="#fff" /><circle id="fc3316e0-7094-4ce0-99ed-43f1e6e4350c" cx="13" cy="7.85" r="0.87" fill="#fff" /><circle id="b5d18443-d50e-4590-8e8f-80b6a7f6d348" cx="12.1" cy="12.07" r="0.87" fill="#fff" /><circle cx="10.86" cy="5.74" r="1.05" fill="#50e6ff" /><circle cx="12.97" cy="7.85" r="1.05" fill="url(#a20547e5-d6af-456b-afbc-05d22ff8cb9d)" /><circle cx="12.1" cy="12.07" r="1.05" fill="url(#a4745f51-5e75-4126-812d-6bb8a5130e16)" /><circle cx="9.98" cy="9.96" r="1.05" fill="#50e6ff" /><g><path d="M1.07,1.43H2.36a0,0,0,0,1,0,0V5a.29.29,0,0,1-.29.29H.79A.29.29,0,0,1,.5,5V2A.57.57,0,0,1,1.07,1.43Z" fill="#999" /><path d="M1.07,1.43H2.36a0,0,0,0,1,0,0V5a.29.29,0,0,1-.29.29H.79A.29.29,0,0,1,.5,5V2A.57.57,0,0,1,1.07,1.43Z" fill="#999" opacity="0.5" /></g><g><path d="M15.64,1.43h1.29A.57.57,0,0,1,17.5,2V5a.29.29,0,0,1-.29.29H15.92A.29.29,0,0,1,15.64,5V1.43A0,0,0,0,1,15.64,1.43Z" fill="#999" /><path d="M15.64,1.43h1.29A.57.57,0,0,1,17.5,2V5a.29.29,0,0,1-.29.29H15.92A.29.29,0,0,1,15.64,5V1.43A0,0,0,0,1,15.64,1.43Z" fill="#999" opacity="0.5" /></g><path d="M8.66-6.16H9.91a0,0,0,0,1,0,0v17a0,0,0,0,1,0,0H8.66a.57.57,0,0,1-.57-.57V-5.6A.57.57,0,0,1,8.66-6.16Z" transform="translate(11.34 -6.66) rotate(90)" fill="#949494" /><g><path d="M.79,12.68H2.08a.29.29,0,0,1,.29.29v3.6a0,0,0,0,1,0,0H1.07A.57.57,0,0,1,.5,16V13A.29.29,0,0,1,.79,12.68Z" fill="#999" /><path d="M.79,12.68H2.08a.29.29,0,0,1,.29.29v3.6a0,0,0,0,1,0,0H1.07A.57.57,0,0,1,.5,16V13A.29.29,0,0,1,.79,12.68Z" fill="#999" opacity="0.5" /></g><g><path d="M15.92,12.68h1.29a.29.29,0,0,1,.29.29v3a.57.57,0,0,1-.57.57H15.64a0,0,0,0,1,0,0V13A.29.29,0,0,1,15.92,12.68Z" fill="#999" /><path d="M15.92,12.68h1.29a.29.29,0,0,1,.29.29v3a.57.57,0,0,1-.57.57H15.64a0,0,0,0,1,0,0V13A.29.29,0,0,1,15.92,12.68Z" fill="#999" opacity="0.5" /></g><path d="M8.66,7.16H9.91a0,0,0,0,1,0,0v17a0,0,0,0,1,0,0H8.66a.57.57,0,0,1-.57-.57V7.73A.57.57,0,0,1,8.66,7.16Z" transform="translate(-6.66 24.66) rotate(-90)" fill="#949494" /></g></g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/azure-eventhubs.svg b/packages/visualiser/src/icons/protocols/azure-eventhubs.svg
new file mode 100644
index 000000000..94c763feb
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/azure-eventhubs.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 18 18"><title>Icon-analytics-144</title><g><g id="a53a4de8-371c-49da-a662-c4631299fc03"><path d="M10.83,8.42a.26.26,0,0,1-.24.27H8.5a.26.26,0,0,1-.27-.24V6.89a.26.26,0,0,1,.24-.27h2.09a.26.26,0,0,1,.27.24V8.42Z" fill="#76bc2d" /><path d="M14.54,10a.26.26,0,0,1-.24.27H12.21a.26.26,0,0,1-.27-.24V8.48a.26.26,0,0,1,.24-.27h2.09a.26.26,0,0,1,.27.24V10Z" fill="#76bc2d" /><path d="M10.83,11.6a.26.26,0,0,1-.24.27H8.5a.26.26,0,0,1-.27-.24V10.07a.26.26,0,0,1,.24-.27h2.09a.26.26,0,0,1,.27.24V11.6Z" fill="#76bc2d" /><path d="M7.12,6.84a.25.25,0,0,1-.23.26H4.74a.26.26,0,0,1-.27-.23V5.25A.26.26,0,0,1,4.71,5H6.8c.22,0,.32.11.32.27Z" fill="#86d633" /><path d="M7.12,10a.25.25,0,0,1-.23.27H4.74A.26.26,0,0,1,4.47,10V8.42a.26.26,0,0,1,.24-.26H6.8c.22,0,.32.11.32.26Z" fill="#76bc2d" /><path d="M7.12,13.19a.25.25,0,0,1-.23.27H4.74a.26.26,0,0,1-.27-.24V11.6a.25.25,0,0,1,.24-.26H6.8c.22,0,.32.1.32.26Z" fill="#76bc2d" /><g><path d="M1.07,1.51H2.36a0,0,0,0,1,0,0v3.6a.29.29,0,0,1-.29.29H.79A.29.29,0,0,1,.5,5.11v-3A.57.57,0,0,1,1.07,1.51Z" fill="#999" /><path d="M1.07,1.51H2.36a0,0,0,0,1,0,0v3.6a.29.29,0,0,1-.29.29H.79A.29.29,0,0,1,.5,5.11v-3A.57.57,0,0,1,1.07,1.51Z" fill="#999" opacity="0.5" /></g><g><path d="M15.64,1.51h1.29a.57.57,0,0,1,.57.57v3a.29.29,0,0,1-.29.29H15.92a.29.29,0,0,1-.29-.29V1.51A0,0,0,0,1,15.64,1.51Z" fill="#999" /><path d="M15.64,1.51h1.29a.57.57,0,0,1,.57.57v3a.29.29,0,0,1-.29.29H15.92a.29.29,0,0,1-.29-.29V1.51A0,0,0,0,1,15.64,1.51Z" fill="#999" opacity="0.5" /></g><path d="M8.66-6.08H9.91a0,0,0,0,1,0,0v17a0,0,0,0,1,0,0H8.66a.57.57,0,0,1-.57-.57V-5.52A.57.57,0,0,1,8.66-6.08Z" transform="translate(11.42 -6.58) rotate(90)" fill="#949494" /><g><path d="M.79,12.76H2.08a.29.29,0,0,1,.29.29v3.6a0,0,0,0,1,0,0H1.07a.57.57,0,0,1-.57-.57V13A.29.29,0,0,1,.79,12.76Z" fill="#999" /><path d="M.79,12.76H2.08a.29.29,0,0,1,.29.29v3.6a0,0,0,0,1,0,0H1.07a.57.57,0,0,1-.57-.57V13A.29.29,0,0,1,.79,12.76Z" fill="#999" opacity="0.5" /></g><g><path d="M15.92,12.76h1.29a.29.29,0,0,1,.29.29v3a.57.57,0,0,1-.57.57H15.64a0,0,0,0,1,0,0V13A.29.29,0,0,1,15.92,12.76Z" fill="#999" /><path d="M15.92,12.76h1.29a.29.29,0,0,1,.29.29v3a.57.57,0,0,1-.57.57H15.64a0,0,0,0,1,0,0V13A.29.29,0,0,1,15.92,12.76Z" fill="#999" opacity="0.5" /></g><path d="M8.66,7.24H9.91a0,0,0,0,1,0,0v17a0,0,0,0,1,0,0H8.66a.57.57,0,0,1-.57-.57V7.81A.57.57,0,0,1,8.66,7.24Z" transform="translate(-6.74 24.74) rotate(-90)" fill="#949494" /></g></g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/azure-servicebus.svg b/packages/visualiser/src/icons/protocols/azure-servicebus.svg
new file mode 100644
index 000000000..bcc2a8c16
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/azure-servicebus.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 18 18"><defs><linearGradient id="bbd02878-309a-4490-8196-946338d0f593" x1="8.995" y1="10.299" x2="8.995" y2="13.199" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#005ba1" /><stop offset="0.258" stop-color="#00589d" /><stop offset="0.525" stop-color="#004f90" /><stop offset="0.796" stop-color="#003f7c" /><stop offset="1" stop-color="#003067" /></linearGradient></defs><g><g id="b532e600-3623-4be6-9fa6-30d05fff56b1"><polygon points="13.387 7.4 13.382 7.396 13.382 7.384 13.363 7.384 8.997 4.405 4.631 7.384 4.612 7.384 4.612 7.396 4.606 7.4 4.612 7.4 4.612 13.201 13.382 13.201 13.382 7.4 13.387 7.4" fill="#50e6ff" /><path d="M4.606,7.4c0-.1.008,5.681.008,5.8L8.995,10.3Z" fill="#32bedd" /><path d="M13.384,7.4,8.995,10.3,13.376,13.2C13.376,13.083,13.384,7.3,13.384,7.4Z" fill="#198ab3" /><polygon points="8.995 10.299 4.614 13.194 4.614 13.199 13.376 13.199 13.376 13.194 8.995 10.299" fill="url(#bbd02878-309a-4490-8196-946338d0f593)" /><g><path d="M1.072,1.43h1.29a0,0,0,0,1,0,0v3.6a.286.286,0,0,1-.286.286H.786A.286.286,0,0,1,.5,5.035V2A.572.572,0,0,1,1.072,1.43Z" fill="#999" /><path d="M1.072,1.43h1.29a0,0,0,0,1,0,0v3.6a.286.286,0,0,1-.286.286H.786A.286.286,0,0,1,.5,5.035V2A.572.572,0,0,1,1.072,1.43Z" fill="#999" opacity="0.5" /></g><g><path d="M15.638,1.43h1.29A.572.572,0,0,1,17.5,2V5.035a.286.286,0,0,1-.286.286h-1.29a.286.286,0,0,1-.286-.286V1.43A0,0,0,0,1,15.638,1.43Z" fill="#999" /><path d="M15.638,1.43h1.29A.572.572,0,0,1,17.5,2V5.035a.286.286,0,0,1-.286.286h-1.29a.286.286,0,0,1-.286-.286V1.43A0,0,0,0,1,15.638,1.43Z" fill="#999" opacity="0.5" /></g><path d="M8.66-6.163H9.907a0,0,0,0,1,0,0v17a0,0,0,0,1,0,0H8.66a.567.567,0,0,1-.567-.567V-5.6A.567.567,0,0,1,8.66-6.163Z" transform="translate(11.337 -6.663) rotate(90)" fill="#949494" /><g><path d="M.786,12.679h1.29a.286.286,0,0,1,.286.286v3.6a0,0,0,0,1,0,0H1.072A.572.572,0,0,1,.5,16V12.965A.286.286,0,0,1,.786,12.679Z" fill="#999" /><path d="M.786,12.679h1.29a.286.286,0,0,1,.286.286v3.6a0,0,0,0,1,0,0H1.072A.572.572,0,0,1,.5,16V12.965A.286.286,0,0,1,.786,12.679Z" fill="#999" opacity="0.5" /></g><g><path d="M15.924,12.679h1.29a.286.286,0,0,1,.286.286V16a.572.572,0,0,1-.572.572h-1.29a0,0,0,0,1,0,0v-3.6A.286.286,0,0,1,15.924,12.679Z" fill="#999" /><path d="M15.924,12.679h1.29a.286.286,0,0,1,.286.286V16a.572.572,0,0,1-.572.572h-1.29a0,0,0,0,1,0,0v-3.6A.286.286,0,0,1,15.924,12.679Z" fill="#999" opacity="0.5" /></g><path d="M8.66,7.163H9.907a0,0,0,0,1,0,0v17a0,0,0,0,1,0,0H8.66a.567.567,0,0,1-.567-.567V7.73A.567.567,0,0,1,8.66,7.163Z" transform="translate(-6.663 24.663) rotate(-90)" fill="#949494" /></g></g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/eventbridge.svg b/packages/visualiser/src/icons/protocols/eventbridge.svg
new file mode 100644
index 000000000..e0ebe8b85
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/eventbridge.svg
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg viewBox="15 7 55 80"  version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <g id="Icon-Architecture/64/Arch_Amazon-EventBridge_64" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <path d="M53.656744,66 C51.5137882,66 49.7695913,64.247 49.7695913,62.091 C49.7695913,59.935 51.5137882,58.182 53.656744,58.182 C55.7996998,58.182 57.5438968,59.935 57.5438968,62.091 C57.5438968,64.247 55.7996998,66 53.656744,66 L53.656744,66 Z M45.1326526,49 L34.7977386,49 L29.6297845,40 L34.7977386,31 L45.1326526,31 L50.2996124,40 L45.1326526,49 Z M27.6210741,21.818 C25.4781184,21.818 23.7339214,20.065 23.7339214,17.909 C23.7339214,15.753 25.4781184,14 27.6210741,14 C29.7650244,14 31.5092213,15.753 31.5092213,17.909 C31.5092213,20.065 29.7650244,21.818 27.6210741,21.818 L27.6210741,21.818 Z M53.656744,56.182 C52.918891,56.182 52.214848,56.325 51.5635088,56.576 L47.3402451,49.41 L47.117497,49.543 L52.3093171,40.5 C52.4863222,40.19 52.4863222,39.81 52.3093171,39.5 L46.5675877,29.5 C46.3895881,29.19 46.0614325,29 45.7064278,29 L35.2581509,29 L35.2989218,28.976 L31.4266852,22.404 C32.691576,21.32 33.4980434,19.708 33.4980434,17.909 C33.4980434,14.651 30.8618597,12 27.6210741,12 C24.381283,12 21.7450993,14.651 21.7450993,17.909 C21.7450993,21.167 24.381283,23.818 27.6210741,23.818 C28.3599216,23.818 29.0639646,23.675 29.7153038,23.424 L33.3299879,29.557 L27.6200797,39.5 C27.4430746,39.81 27.4430746,40.19 27.6200797,40.5 L33.3628035,50.5 C33.5408031,50.81 33.8689587,51 34.2239635,51 L45.7064278,51 C45.7889639,51 45.8695112,50.987 45.9470752,50.968 L49.8521274,57.596 C48.5862421,58.68 47.7807692,60.292 47.7807692,62.091 C47.7807692,65.349 50.4159585,68 53.656744,68 C56.8975296,68 59.5327189,65.349 59.5327189,62.091 C59.5327189,58.833 56.8975296,56.182 53.656744,56.182 L53.656744,56.182 Z M59.5844283,32.104 C57.4414725,32.104 55.6982699,30.351 55.6982699,28.195 C55.6982699,26.039 57.4414725,24.286 59.5844283,24.286 C61.7273841,24.286 63.471581,26.039 63.471581,28.195 C63.471581,30.351 61.7273841,32.104 59.5844283,32.104 L59.5844283,32.104 Z M66.8665003,39.5 L63.091716,32.925 C64.5266511,31.846 65.4604031,30.13 65.4604031,28.195 C65.4604031,24.937 62.8252138,22.286 59.5844283,22.286 C58.7600615,22.286 57.9744768,22.459 57.2614841,22.77 L54.1837819,17.409 C54.0067767,17.1 53.6776267,16.909 53.3226219,16.909 L40.9949082,16.909 L40.9949082,18.909 L52.7488468,18.909 L55.5958456,23.869 C54.4383511,24.949 53.7094478,26.486 53.7094478,28.195 C53.7094478,31.453 56.3446371,34.104 59.5844283,34.104 C60.1880358,34.104 60.771755,34.011 61.3206699,33.84 L64.85779,40 L59.8917013,48.648 L61.6140212,49.648 L66.8665003,40.5 C67.0444999,40.19 67.0444999,39.81 66.8665003,39.5 L66.8665003,39.5 Z M21.229,55.247 C19.0850498,55.247 17.3408528,53.493 17.3408528,51.338 C17.3408528,49.182 19.0850498,47.429 21.229,47.429 C23.3719558,47.429 25.1161527,49.182 25.1161527,51.338 C25.1161527,53.493 23.3719558,55.247 21.229,55.247 L21.229,55.247 Z M24.4767464,56.258 C26.0588544,55.198 27.1049748,53.389 27.1049748,51.338 C27.1049748,48.08 24.4687911,45.429 21.229,45.429 C20.2902759,45.429 19.4062445,45.657 18.618671,46.052 L15.1432044,40 L20.9018387,29.971 L19.1785244,28.971 L13.1334997,39.5 C12.9555001,39.81 12.9555001,40.19 13.1334997,40.5 L17.0047419,47.24 C15.9834817,48.304 15.3520307,49.747 15.3520307,51.338 C15.3520307,54.596 17.9882144,57.247 21.229,57.247 C21.7172558,57.247 22.189601,57.18 22.6440469,57.066 L25.8162181,62.591 C25.9942177,62.9 26.3223733,63.091 26.6773781,63.091 L39.0060862,63.091 L39.0060862,61.091 L27.2511532,61.091 L24.4767464,56.258 Z" id="Amazon-EventBridge_Icon_64_Squid" fill="currentColor"></path>
+    </g>
+</svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/googlepubsub.svg b/packages/visualiser/src/icons/protocols/googlepubsub.svg
new file mode 100644
index 000000000..b2a8f1fd8
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/googlepubsub.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"  viewBox="0 0 24 24"><defs><style>.cls-1{filter:url(#luminosity-noclip);}.cls-2{fill:currentColor;}.cls-3{mask:url(#mask);}.cls-4{fill:currentColor;}.cls-5{fill:currentColor;}</style><filter id="luminosity-noclip" x="4.64" y="4.19" width="14.73" height="12.76" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB"><feFlood flood-color="#fff" result="bg"/><feBlend in="SourceGraphic" in2="bg"/></filter><mask id="mask" x="4.64" y="4.19" width="14.73" height="12.76" maskUnits="userSpaceOnUse"><circle class="cls-1" cx="12" cy="12.23" r="3.58"/></mask></defs><title>Icon_24px_Pub-Sub_Color</title><g data-name="Product Icons"><circle class="cls-2" cx="18.97" cy="8.21" r="1.72"/><circle class="cls-2" cx="5.03" cy="8.21" r="1.72"/><circle class="cls-2" cx="12" cy="20.28" r="1.72"/><g class="cls-3"><rect class="cls-4" x="14.69" y="10.22" width="1.59" height="8.04" transform="matrix(0.5, -0.87, 0.87, 0.5, -4.59, 20.53)"/><rect class="cls-4" x="4.49" y="13.45" width="8.04" height="1.59" transform="translate(-5.98 6.17) rotate(-30)"/><rect class="cls-4" x="11.2" y="4.19" width="1.59" height="8.04"/></g><circle class="cls-5" cx="12" cy="12.23" r="2.78"/><circle class="cls-5" cx="5.03" cy="16.25" r="2.19"/><circle class="cls-5" cx="18.97" cy="16.25" r="2.19"/><circle class="cls-5" cx="12" cy="4.19" r="2.19"/></g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/grpc.svg b/packages/visualiser/src/icons/protocols/grpc.svg
new file mode 100644
index 000000000..925c34ccb
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/grpc.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 96 96" id="Grpc--Streamline-Svg-Logos" ><desc>Grpc Streamline Icon: https://streamlinehq.com</desc><path fill="#244b5a" d="M11.4052 61.9509c.6979.9285 1.6048 1.6794 2.6473 2.1918 1.1274.5584 2.3714.8408 3.6294.8238 1.0172.0266 2.0297-.1461 2.9805-.5084.7605-.2988 1.4394-.7734 1.9811-1.385.5084-.5959.8795-1.2963 1.0871-2.0515.2264-.8163.3384-1.66.333-2.507v-2.9454h-.0699c-.6593 1.045-1.6103 1.8739-2.7355 2.3844-1.0728.4671-2.2311.7059-3.4012.7013-1.1465.0086-2.2838-.2057-3.3485-.6311-1.0082-.4003-1.9306-.9894-2.7177-1.7358-.781-.7499-1.4014-1.6507-1.8235-2.6478-.44911-1.0526-.67592-2.1866-.6662-3.331-.00969-1.1411.20483-2.2729.63137-3.3313.40313-1.0013.99203-1.9174 1.73553-2.6999.7434-.7761 1.6387-1.3909 2.63-1.806 1.0608-.441 2.2001-.6617 3.3488-.6486.5231.003 1.045.0499 1.5602.14.5666.099 1.1197.2638 1.6481.4911 1.2545.5437 2.3389 1.4161 3.1386 2.525h.0699v-2.7354h2.3146v16.2705c-.0079.956-.1197 1.9083-.3333 2.8402-.2234 1.0076-.6664 1.9534-1.2973 2.7701-.7179.901-1.6366 1.6216-2.6826 2.1043-1.1457.5608-2.6419.8411-4.4886.8411-1.5001.0256-2.9902-.2485-4.383-.8063-1.3326-.5708-2.5279-1.4196-3.50622-2.4894l1.71802-1.8237Zm.4207-11.7116c-.0058.8357.1552 1.6641.4735 2.4368.3035.7415.7435 1.4195 1.2971 1.9986.5504.5741 1.2049 1.0382 1.9287 1.3678.754.3426 1.5738.5162 2.402.5083 1.6401.0059 3.2206-.6149 4.4182-1.7355.5881-.555 1.0488-1.2311 1.3502-1.9816.3247-.825.4741-1.7086.4384-2.5944.0059-.831-.1366-1.6564-.4209-2.4373-.2701-.7422-.6876-1.4221-1.2274-1.9987-.5548-.5845-1.223-1.0498-1.9636-1.3675-.82-.3485-1.7039-.5218-2.5949-.5086-.8282-.0076-1.648.166-2.402.5086-.7236.3299-1.378.7939-1.9287 1.3675-.5535.5794-.9935 1.2573-1.2974 1.9987-.3181.7729-.479 1.6014-.4732 2.4373Zm23.9844 8.4156h-2.5245V33.8282H40.93c2.5247 0 4.5175.5493 5.9786 1.6481 1.4608 1.099 2.1914 2.7588 2.1917 4.9793.0445 1.6118-.5403 3.1776-1.6305 4.3656-1.0872 1.1807-2.6593 1.8645-4.7163 2.0512l7.1534 11.7825h-3.086l-6.8024-11.5367h-4.208l-.0002 11.5367Zm0-13.851h4.4886c.9644.0203 1.9268-.0978 2.8577-.3508.6809-.182 1.3186-.4978 1.8761-.929.4497-.3619.7997-.8326 1.0167-1.3675.2134-.5415.3205-1.119.3157-1.701.0026-.5702-.1046-1.1356-.3157-1.6654-.2196-.5384-.5688-1.0143-1.0167-1.3852-.5521-.4398-1.1917-.7566-1.8761-.9293-.933-.2402-1.8945-.3522-2.8577-.333h-4.4886v8.6612Zm18.4441-10.9757h7.2238c2.5245 0 4.5173.5494 5.9783 1.6483 1.4608 1.0991 2.1914 2.7589 2.1918 4.9794 0 2.2212-.7306 3.8867-2.1918 4.9967-1.461 1.1106-3.4538 1.6658-5.9783 1.6656h-4.6988v11.5367h-2.525V33.8282Zm2.5252 10.9759h4.0677c.9644.0203 1.9268-.0978 2.8577-.3507.6808-.1821 1.3186-.498 1.8761-.9291.4497-.3619.7996-.8326 1.0167-1.3675.2135-.5414.3206-1.1189.3157-1.7009.0027-.5703-.1045-1.1357-.3157-1.6654-.2196-.5385-.5688-1.0143-1.0167-1.3853-.5521-.4396-1.1917-.7565-1.8761-.9293-.933-.2401-1.8945-.3522-2.8577-.3329h-4.0679l.0002 8.6611ZM95 54.7276c-.4443.6582-.9682 1.2589-1.56 1.7884-.6406.5755-1.3539 1.0647-2.1216 1.4549-.8196.4185-1.6842.7421-2.5771.9646-.9579.2378-1.9415.3555-2.9284.3505-1.7604.0165-3.5065-.3172-5.1368-.9816-3.1091-1.2564-5.5719-3.7256-6.8204-6.8379-.6681-1.66-1.0017-3.4357-.9816-5.225-.02-1.7892.3136-3.5649.9816-5.2249 1.2484-3.1122 3.7113-5.5813 6.8204-6.8374 1.6302-.6646 3.3764-.9984 5.1368-.9819 1.5867.0085 3.1574.3178 4.6288.9115 1.5694.628 2.9388 1.6704 3.9622 3.0158l-2.2088 1.6481c-.2968-.442-.6506-.843-1.0523-1.1923-.464-.4109-.976-.764-1.5249-1.0518-.5864-.3089-1.2035-.5557-1.8412-.7364-.6383-.1847-1.2994-.2791-1.9638-.2806-1.4729-.0242-2.9332.2751-4.2779.8766-1.2199.5535-2.3122 1.3533-3.2083 2.3492-.8868.9987-1.5716 2.1599-2.0166 3.4192-.9349 2.6431-.9349 5.5268 0 8.1699.4449 1.2593 1.1297 2.4204 2.0166 3.4189.8958.9962 1.9882 1.7962 3.2083 2.3494 1.3446.602 2.8049.9014 4.2779.8769.6527.0003 1.3041-.0584 1.9462-.1753.6533-.1202 1.2893-.3204 1.8937-.5961.637-.2922 1.2277-.6763 1.7533-1.14.5904-.5274 1.1038-1.1352 1.5251-1.8054L95 54.7276Z"></path><path fill="url(#a)" d="m7.53809 41.9566-6.53851-6.49 6.49007-6.5386 6.53855 6.4901-6.49011 6.5385Z"></path><path fill="url(#b)" d="m25.3301 39.1863-3.8352-3.8067 3.8068-3.8352 3.8351 3.8068-3.8067 3.8351Z"></path><path fill="#244b5a" d="M7.77596 31.5034 3.8457 35.4631l3.95949 3.9303 3.34981-.0125-3.51277-3.4845 17.34547-.0643-1.5202 1.5305 1.6749-.0061 1.9653-1.9799-1.9799-1.965-1.6749.0061 1.5317 1.5195-17.34553.0643 3.48643-3.5105-3.34954.0124Z"></path><defs><linearGradient id="a" x1="-646.313" x2="656.545" y1="-607.051" y2="-611.894" gradientUnits="userSpaceOnUse"><stop stop-color="#72c9c9"></stop><stop offset="1" stop-color="#02b0ad"></stop></linearGradient><linearGradient id="b" x1="-358.188" x2="406.007" y1="-341.49" y2="-344.331" gradientUnits="userSpaceOnUse"><stop stop-color="#03b6b4"></stop><stop offset="1" stop-color="#74cbca"></stop></linearGradient></defs></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/http.svg b/packages/visualiser/src/icons/protocols/http.svg
new file mode 100644
index 000000000..8a94b9594
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/http.svg
@@ -0,0 +1 @@
+<svg fill="currentColor"   version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 560 560" xml:space="preserve"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"> <g> <g> <path d="M202.042,199.238c-6.938-2.103-14.268,1.82-16.371,8.759l-55.138,182.045c-2.102,6.938,1.82,14.268,8.759,16.37 c1.27,0.385,2.549,0.568,3.811,0.568c5.633,0,10.841-3.656,12.56-9.326l55.138-182.045 C212.901,208.668,208.981,201.338,202.042,199.238z"></path> </g> </g> <g> <g> <path d="M268.994,199.238c-6.93-2.103-14.268,1.82-16.37,8.759l-55.138,182.045c-2.102,6.938,1.82,14.268,8.759,16.37 c1.269,0.385,2.549,0.568,3.811,0.568c5.633,0,10.841-3.656,12.56-9.326l55.138-182.045 C279.857,208.668,275.935,201.338,268.994,199.238z"></path> </g> </g> <g> <g> <path d="M498.872,0H13.128C5.878,0,0,5.879,0,13.128v485.744C0,506.121,5.878,512,13.128,512h485.744 c7.249,0,13.128-5.879,13.128-13.128V13.128C512,5.879,506.121,0,498.872,0z M105.026,26.256h301.949v52.513H105.026V26.256z M26.256,26.256h52.513v52.513H26.256V26.256z M485.744,485.744H26.256V105.026h459.487V485.744z M485.744,78.769h-52.513V26.256 h52.513V78.769z"></path> </g> </g> <g> <g> <circle cx="93.867" cy="245.064" r="13.128"></circle> </g> </g> <g> <g> <circle cx="93.867" cy="360.592" r="13.128"></circle> </g> </g> <g> <g> <path d="M429.292,380.718H307.2c-7.249,0-13.128,5.879-13.128,13.128c0,7.249,5.879,13.128,13.128,13.128h122.092 c7.249,0,13.128-5.879,13.128-13.128C442.421,386.597,436.542,380.718,429.292,380.718z"></path> </g> </g> </g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/index.ts b/packages/visualiser/src/icons/protocols/index.ts
new file mode 100644
index 000000000..dc1a1269a
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/index.ts
@@ -0,0 +1,27 @@
+export { default as AMQP } from "./amqp.svg?raw";
+export { default as AzureEventGrid } from "./azure-eventgrid.svg?raw";
+export { default as AzureEventHubs } from "./azure-eventhubs.svg?raw";
+export { default as AzureServiceBus } from "./azure-servicebus.svg?raw";
+export { default as EventBridge } from "./eventbridge.svg?raw";
+export { default as GooglePubSub } from "./googlepubsub.svg?raw";
+export { default as GRPC } from "./grpc.svg?raw";
+export { default as Http } from "./http.svg?raw";
+export { default as JMS } from "./jms.svg?raw";
+export { default as Kafka } from "./kafka.svg?raw";
+export { default as Kinesis } from "./kinesis.svg?raw";
+export { default as Mercure } from "./mercure.svg?raw";
+export { default as Mcp } from "./mcp.svg?raw";
+export { default as McpDark } from "./mcp-dark.svg?raw";
+export { default as McpLight } from "./mcp-light.svg?raw";
+export { default as MQTT } from "./mqtt.svg?raw";
+export { default as Nats } from "./nats.svg?raw";
+export { default as Pulsar } from "./pulsar.svg?raw";
+export { default as Redis } from "./redis.svg?raw";
+export { default as SNS } from "./sns.svg?raw";
+export { default as Solace } from "./solace.svg?raw";
+export { default as SQS } from "./sqs.svg?raw";
+export { default as TibcoFtl } from "./tibo-ftl.svg?raw";
+export { default as TibcoRv } from "./tibo-rv.svg?raw";
+export { default as WebSocket } from "./ws.svg?raw";
+export { default as Webrtc } from "./webrtc.svg?raw";
+export { default as ZMQ } from "./zmq.svg?raw";
diff --git a/packages/visualiser/src/icons/protocols/jms.svg b/packages/visualiser/src/icons/protocols/jms.svg
new file mode 100644
index 000000000..9b4e34486
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/jms.svg
@@ -0,0 +1 @@
+<svg fill="currentColor" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 512 512" enable-background="new 0 0 512 512" xml:space="preserve"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"> <g id="5151e0c8492e5103c096af88a51e8d81"> <path display="inline" d="M193.918,208.369c-4.729-10.456-6.849-22.652-3.236-33.731c3.612-11.327,11.703-20.413,19.794-28.878 c22.525-22.531,50.285-39.085,72.316-61.986c12.197-12.573,22.278-27.634,25.762-44.937c2.864-12.695,1.496-25.764-1.117-38.337 c11.7,13.319,15.559,32.363,12.197,49.541c-3.608,19.292-14.316,36.344-26.886,51.031c-10.081,11.827-21.659,22.282-33.731,31.993 c-14.065,11.327-27.88,23.524-36.716,39.457c-7.472,12.943-9.215,28.876-4.11,42.942c8.341,24.146,27.756,42.071,38.338,64.848 c-11.703-10.332-23.152-21.036-33.86-32.361C211.471,236.001,200.889,223.307,193.918,208.369z M257.398,189.448 c-2.115,19.792,8.213,38.462,20.539,53.151c5.972,6.596,11.076,14.687,11.323,23.899c0.251,12.318-6.716,23.774-15.684,31.861 c2.119-0.246,3.612-2.115,5.355-3.11c13.443-8.589,26.385-19.418,32.982-34.227c4.357-10.083,3.362-22.034-2.362-31.371 c-6.724-10.953-15.559-20.662-20.786-32.61c-2.867-6.721-3.862-14.562-1.496-21.657c3.114-9.583,9.834-17.426,16.93-24.272 c19.54-18.544,43.189-31.743,65.844-46.179c-28.629,8.214-56.883,19.542-81.03,37.343 C273.702,153.727,259.515,169.658,257.398,189.448z M393.447,283.052c13.568,0.748,26.882,10.704,29.374,24.397 c2.366,11.825-3.358,23.524-10.705,32.485c-12.075,14.438-28.382,24.771-44.807,33.609c-1.622,0.991-2.99,2.237-4.235,3.608 c21.659-5.478,43.314-13.689,60.867-27.756c9.705-8.091,18.294-18.799,20.163-31.619c1.743-11.076-2.86-22.528-11.077-29.871 c-9.96-9.09-24.021-12.448-37.218-10.704c-7.593,0.995-15.931,2.613-21.158,8.961C380.877,284.921,386.971,282.429,393.447,283.052 z M123.22,318.647c16.303,4.357,33.108,5.603,49.787,6.724c14.936,0.995,29.875,1.246,44.937,1.12 c38.833-0.619,77.916-3.236,116.003-11.699c3.608-0.87,7.593-1.493,10.833-3.733c6.347-4.11,13.313-7.347,20.162-10.583 c-30.995,4.979-62.113,9.215-93.478,11.205c-31.74,1.991-63.731,3.236-95.593,1.121c-9.086-0.87-18.423-1.371-26.886-4.858 c-1.994-0.87-4.733-2.609-3.738-5.227c1.869-3.361,5.603-4.977,8.839-6.72c13.694-6.473,28.629-10.081,43.193-14.313 c-25.021-0.376-49.916,5.971-72.814,15.806c-5.105,2.491-10.83,4.481-14.936,8.714c-1.622,1.739-1.622,4.732,0.247,6.222 C113.511,315.787,118.487,317.28,123.22,318.647z M324.864,352.88c-21.784,3.859-43.694,7.472-65.726,8.589 c-24.147,1.618-48.294,0.247-72.191-2.241c-4.604-0.623-9.211-1.368-13.317-3.483c-2.116-1.246-4.231-3.236-4.106-5.854 c0.247-4.106,3.73-6.967,6.222-9.956c-7.715,2.739-15.434,5.599-21.906,10.708c-2.742,2.116-5.478,5.474-4.733,9.208 c1.125,4.356,5.356,6.97,9.09,8.96c9.208,4.733,19.54,6.846,29.625,8.714c25.511,4.11,51.527,4.235,77.167,2.488 c27.141-2.115,54.148-6.594,80.411-14.313C337.932,362.342,330.836,358.479,324.864,352.88z M188.068,395.951 c-6.97,1.99-14.066,4.357-19.79,8.957c-2.868,2.241-5.105,6.104-3.734,9.713c1.743,4.604,6.1,7.347,10.203,9.705 c10.708,5.854,22.78,8.589,34.604,10.708c26.765,4.229,54.27,3.608,80.908-1.12c15.806-2.989,31.615-7.221,46.301-13.815 c-9.584-3.984-18.917-8.467-27.878-13.693c-15.559,2.738-31.246,5.603-47.178,6.598c-21.032,1.618-42.319-0.125-63.355-2.738 c-4.98-1.121-11.202-1.618-14.563-5.976C181.847,400.677,185.828,398.063,188.068,395.951z M358.345,475.982 c17.424-3.604,34.977-7.719,50.908-15.806c4.976-2.867,11.076-5.979,12.698-11.95c0.87-5.725-5.105-8.714-9.337-11.08 c2.613,2.993,4.356,7.347,1.74,10.83c-4.357,5.853-11.821,8.091-18.42,10.332c-20.66,5.85-42.072,8.216-63.355,10.582 c-56.385,5.102-113.146,6.348-169.528,1.618c-18.92-1.994-38.217-4.109-56.264-10.829c-2.86-1.246-7.217-2.492-7.217-6.352 c1.117-3.354,4.357-5.227,7.217-6.845c12.945-6.595,27.384-10.207,41.822-11.077c-4.228-2.491-9.208-2.738-14.062-2.613 c-12.076,0.373-23.9,3.483-35.349,7.347c-9.834,3.604-19.916,7.59-27.76,14.811c-3.111,2.735-5.971,7.962-2.739,11.699 c4.98,5.353,12.699,6.72,19.54,8.338c38.338,6.599,77.171,10.328,116.011,11.699C255.781,488.184,307.684,485.942,358.345,475.982z M409.378,482.706c-23.402,7.468-47.672,11.574-71.822,14.936c-41.696,5.227-83.769,6.845-125.716,5.603 c-25.515-0.995-51.03-2.738-76.176-6.974c5.85,3.984,13.071,5.227,19.794,7.096c28.257,5.976,57.255,7.096,86.01,7.966 c42.19,0.748,84.387-0.87,125.962-7.468c19.669-3.48,39.459-7.715,57.13-16.927c9.215-4.854,18.552-12.326,20.163-23.152 C435.391,473.741,421.951,478.349,409.378,482.706z"> </path> </g> </g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/kafka.svg b/packages/visualiser/src/icons/protocols/kafka.svg
new file mode 100644
index 000000000..2b408363a
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/kafka.svg
@@ -0,0 +1 @@
+<svg  viewBox="-78.5 0 413 413" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid" fill="currentColor" stroke="currentColor" stroke-width="0.00413"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round" stroke="#CCCCCC" stroke-width="5.782000000000001"></g><g id="SVGRepo_iconCarrier"> <g> <path d="M87.9320692,36.714181 C83.382936,32.1427482 77.0364491,29.3196096 69.9808327,29.3196096 C62.9519759,29.3196096 56.6545483,32.1427482 52.1589343,36.714181 L52.0295962,36.714181 C47.4938428,41.2633143 44.6707042,47.614261 44.6707042,54.6431179 C44.6707042,61.6987343 47.4938428,67.9961618 52.0295962,72.5185355 L52.1589343,72.6211139 C56.6545483,77.1702472 62.9519759,79.9666261 69.9808327,79.9666261 C77.0364491,79.9666261 83.382936,77.1702472 87.9320692,72.6211139 L87.9989682,72.5185355 C92.5570213,67.9961618 95.3534002,61.6987343 95.3534002,54.6431179 C95.3534002,47.614261 92.5570213,41.2633143 87.9989682,36.714181 L87.9320692,36.714181 Z M69.9808327,383.353672 C77.0364491,383.353672 83.382936,380.481475 87.9320692,375.985861 L87.9989682,375.852063 C92.5570213,371.365368 95.3534002,365.014422 95.3534002,358.034624 C95.3534002,350.979008 92.5570213,344.654821 87.9989682,340.083388 L87.9320692,340.083388 C83.382936,335.458436 77.0364491,332.662057 69.9808327,332.662057 C62.9519759,332.662057 56.6545483,335.458436 52.1589343,340.083388 L52.0295962,340.083388 C47.4938428,344.654821 44.6707042,350.979008 44.6707042,358.034624 C44.6707042,365.014422 47.4938428,371.365368 52.0295962,375.852063 L52.1589343,375.985861 C56.6545483,380.481475 62.9519759,383.353672 69.9808327,383.353672 Z M207.953367,306.633879 C214.228495,304.988163 219.910452,300.960842 223.375821,294.873031 L223.844114,293.985504 C226.925929,288.209889 227.487881,281.546747 225.842165,275.641794 C224.183069,269.317607 220.106689,263.724849 214.032258,260.2238 L213.679923,259.987423 C207.76159,256.745051 201.018169,256.040381 194.82332,257.712857 C188.525893,259.282754 182.870696,263.488472 179.423166,269.527223 C175.931037,275.507996 175.199608,282.407514 176.872084,288.758461 C178.598078,295.002369 182.634319,300.648647 188.66861,304.176455 L188.70875,304.176455 C194.756421,307.650744 201.60688,308.279595 207.953367,306.633879 Z M95.9688712,180.386512 C89.3146489,173.750129 80.1450235,169.59347 69.9808327,169.59347 C59.8567813,169.59347 50.7094556,173.750129 44.0686131,180.386512 C37.4589901,187.000595 33.38261,196.147921 33.38261,206.285352 C33.38261,216.449543 37.4589901,225.623628 44.0686131,232.31353 C50.7094556,238.896393 59.8567813,243.026292 69.9808327,243.026292 C80.1450235,243.026292 89.3146489,238.896393 95.9688712,232.31353 C102.591874,225.623628 106.668254,216.449543 106.668254,206.285352 C106.668254,196.147921 102.591874,187.000595 95.9688712,180.386512 Z M81.3581257,137.223266 C96.0848295,139.64947 109.335295,146.705086 119.445967,156.896037 L119.526245,156.896037 C121.131822,158.514993 122.701719,160.267747 124.151198,162.042801 L149.434566,147.414216 C146.036096,137.142987 145.879999,126.403464 148.609478,116.341852 C152.217565,102.85501 160.959037,90.7819674 174.062325,83.2045386 L174.494938,82.9458624 C187.455508,75.6003502 202.191132,74.0839725 215.495117,77.6920595 C228.964119,81.2956866 241.11744,90.0772977 248.681489,103.171665 L248.681489,103.198425 C256.209859,116.212514 257.739616,131.157755 254.144909,144.591077 C250.563582,158.069 241.781971,170.222321 228.692063,177.746231 L225.240074,179.788881 L224.887739,179.788881 C212.779016,185.560036 199.461652,186.452023 187.232511,183.23641 C177.188739,180.569369 167.974514,174.976611 160.7628,167.006708 L135.519571,181.590694 C138.418528,189.270702 140.028564,197.55726 140.028564,206.285352 C140.028564,214.986684 138.418528,223.375821 135.519571,231.109347 L160.7628,245.639814 C167.974514,237.567333 177.188739,232.077153 187.232511,229.410112 C200.701514,225.726206 215.637835,227.296103 228.692063,234.900292 L229.526071,235.292766 L229.526071,235.346285 C242.138765,242.972773 250.603721,254.78714 254.144909,268.113424 C257.739616,281.466468 256.209859,296.416169 248.681489,309.457017 L248.226576,310.371304 L248.173057,310.291025 C240.609008,322.86358 228.692063,331.382055 215.535256,334.985683 C202.035034,338.54025 187.103173,337.023873 174.062325,329.526723 L174.062325,329.419684 C160.959037,321.842255 152.217565,309.742453 148.609478,296.286831 C145.879999,286.251978 146.036096,275.507996 149.434566,265.241226 L124.151198,250.65724 C122.701719,252.436754 121.131822,254.10923 119.526245,255.728186 L119.445967,255.804005 C109.335295,265.945896 96.0848295,273.001512 81.3581257,275.351898 L81.3581257,304.568929 C91.8523516,306.763217 101.258354,312.01702 108.630625,319.384832 L108.666305,319.46511 C118.54506,329.290346 124.65963,342.982345 124.65963,358.034624 C124.65963,373.037844 118.54506,386.645104 108.666305,396.523859 L108.630625,396.679957 C98.6849713,406.558712 85.0331117,412.673282 69.9808327,412.673282 C55.0088325,412.673282 41.3391332,406.558712 31.4202388,396.679957 L31.3845593,396.679957 L31.3845593,396.523859 C21.4924245,386.645104 15.3644745,373.037844 15.3644745,358.034624 C15.3644745,342.982345 21.4924245,329.290346 31.3845593,319.46511 L31.3845593,319.384832 L31.4202388,319.384832 C38.7791307,312.01702 48.1985125,306.763217 58.6659788,304.568929 L58.6659788,275.351898 C43.9258952,273.001512 30.7155691,265.945896 20.6182773,255.804005 L20.5112389,255.728186 C7.88962418,243.053052 0,225.623628 0,206.285352 C0,187.000595 7.88962418,169.571171 20.5112389,156.896037 L20.6182773,156.896037 C30.7155691,146.705086 43.9258952,139.64947 58.6659788,137.223266 L58.6659788,108.135573 C48.1985125,105.861006 38.7791307,100.611663 31.4202388,93.2929105 L31.3845593,93.2929105 L31.3845593,93.2126317 C21.4924245,83.2848174 15.3644745,69.6953969 15.3644745,54.6431179 C15.3644745,39.6666577 21.4924245,25.9478991 31.3845593,16.0691441 L31.4202388,16.0200848 C41.3391332,6.11457024 55.0088325,0 69.9808327,0 C85.0331117,0 98.6849713,6.11457024 108.630625,16.0200848 L108.630625,16.0691441 L108.666305,16.0691441 C118.54506,25.9478991 124.65963,39.6666577 124.65963,54.6431179 C124.65963,69.6953969 118.54506,83.2848174 108.666305,93.2126317 L108.630625,93.2929105 C101.258354,100.611663 91.8523516,105.861006 81.3581257,108.135573 L81.3581257,137.223266 Z M223.375821,117.83147 L223.166204,117.519275 C219.674075,111.636621 214.108077,107.716339 207.953367,106.017104 C201.60688,104.344628 194.756421,105.053758 188.66861,108.528047 L188.70875,108.528047 C182.634319,111.975576 178.571319,117.621853 176.872084,123.946041 C175.199608,130.216708 175.931037,137.142987 179.423166,143.177278 L179.539124,143.337836 C183.040173,149.291848 188.606171,153.28795 194.82332,154.906906 C201.071688,156.65966 208.033646,155.928231 214.032258,152.427182 L214.357833,152.271085 C220.262787,148.743276 224.196449,143.177278 225.842165,137.062708 C227.51464,130.76528 226.85011,123.865762 223.375821,117.83147 Z" fill="currentColor"> </path> </g> </g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/kinesis.svg b/packages/visualiser/src/icons/protocols/kinesis.svg
new file mode 100644
index 000000000..947274d20
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/kinesis.svg
@@ -0,0 +1,14 @@
+<svg  viewBox="0 0 80 80" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <defs>
+        <linearGradient x1="0%" y1="100%" x2="100%" y2="0%" id="linearGradient-1">
+            <stop stop-color="#4D27A8" offset="0%"></stop>
+            <stop stop-color="#A166FF" offset="100%"></stop>
+        </linearGradient>
+    </defs>
+    <g id="Icon-Architecture/64/Arch_Amazon-Kinesis_64" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="Icon-Architecture-BG/64/Analytics" fill="url(#linearGradient-1)">
+            <rect id="Rectangle" x="0" y="0" width="80" height="80"></rect>
+        </g>
+        <path d="M19,62 L21,62 C21,53.594 26.465,45 67,45 L67,43 C24.703,43 19,52.604 19,62 M25,68 L27,68 C27,60.434 27,49 67,49 L67,47 C48.663,47 36.728,49.359 30.51,54.212 C25,58.512 25,63.996 25,68 M15,26 L13,26 C13,33.396 23.039,38.08 42.893,40 C23.039,41.92 13,46.604 13,54 L15,54 C15,49.145 21.756,41 67,41 L67,39 C21.756,39 15,30.855 15,26 M21,18 L19,18 C19,27.396 24.703,37 67,37 L67,35 C26.465,35 21,26.406 21,18 M67,31 L67,33 C48.663,33 36.728,30.641 30.51,25.788 C25,21.488 25,16.004 25,12 L27,12 C27,19.566 27,31 67,31" id="Amazon-Kinesis_Icon_64_Squid" fill="#FFFFFF"></path>
+    </g>
+</svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/mcp-dark.svg b/packages/visualiser/src/icons/protocols/mcp-dark.svg
new file mode 100644
index 000000000..18523c181
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/mcp-dark.svg
@@ -0,0 +1 @@
+<svg fill="#ffffff" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>ModelContextProtocol</title><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"/><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"/></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/mcp-light.svg b/packages/visualiser/src/icons/protocols/mcp-light.svg
new file mode 100644
index 000000000..d14b16bbe
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/mcp-light.svg
@@ -0,0 +1 @@
+<svg fill="#000000" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>ModelContextProtocol</title><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"/><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"/></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/mcp.svg b/packages/visualiser/src/icons/protocols/mcp.svg
new file mode 100644
index 000000000..18523c181
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/mcp.svg
@@ -0,0 +1 @@
+<svg fill="#ffffff" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>ModelContextProtocol</title><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"/><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"/></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/mercure.svg b/packages/visualiser/src/icons/protocols/mercure.svg
new file mode 100644
index 000000000..1e0c4d677
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/mercure.svg
@@ -0,0 +1,20 @@
+
+<?xml version="1.0" encoding="UTF-8"?>
+<svg viewBox="0 0 106 105" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <defs>
+        <linearGradient x1="-0.0211832061%" y1="50.0351145%" x2="99.9958015%" y2="50.0351145%" id="linearGradient-1">
+            <stop stop-color="currentColor" offset="0%"></stop>
+            <stop stop-color="currentColor" offset="100%"></stop>
+        </linearGradient>
+        <linearGradient x1="-0.0483596598%" y1="50.0496962%" x2="99.8944107%" y2="50.0496962%" id="linearGradient-2">
+            <stop stop-color="currentColor" offset="0%"></stop>
+            <stop stop-color="currentColor" offset="100%"></stop>
+        </linearGradient>
+    </defs>
+    <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="mercure-hub" fill-rule="nonzero">
+            <path d="M53,104.9 C24.1,104.9 0.6,81.4 0.6,52.5 C0.6,23.6 24.1,0.1 53,0.1 C81.9,0.1 105.4,23.6 105.4,52.5 C105.4,81.4 81.9,104.9 53,104.9 Z M53,4.6 C26.6,4.6 5,26.1 5,52.6 C5,79.1 26.5,100.6 53,100.6 C79.5,100.6 101,79.1 101,52.6 C101,26.1 79.5,4.6 53,4.6 Z" id="Shape" fill="url(#linearGradient-1)"></path>
+            <path d="M53,10.8 C30.3,10.8 11.9,29.2 11.9,51.9 C11.9,59 13.7,65.7 16.8,71.5 C17.9,70.7 19.1,69.9 20.4,69.1 C42.9,55.7 62.9,44.6 76.1,24 C76.1,24 75.2,47.3 61.8,58.1 C58.8,60.5 56.3,62.4 53.9,63.9 C60.7,60.3 66.6,56.3 71.2,50.8 C71.2,50.8 70.8,66.4 59.3,73.4 C55,75.9 51.4,77.4 47.8,78.5 C54.4,77 58.6,75.2 62.1,72.9 C59.2,82.6 52.9,87.7 43,89.1 C39.4,89.5 36.4,88.7 33.2,88 C39.1,91.3 45.9,93.1 53.1,93.1 C75.8,93.1 94.2,74.7 94.2,52 C94.2,29.3 75.8,10.8 53,10.8 Z" id="Path" fill="url(#linearGradient-2)"></path>
+        </g>
+    </g>
+</svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/mqtt.svg b/packages/visualiser/src/icons/protocols/mqtt.svg
new file mode 100644
index 000000000..0ece5fa7d
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/mqtt.svg
@@ -0,0 +1,17 @@
+
+<?xml version="1.0" encoding="utf-8"?>
+<svg version="1.2" baseProfile="tiny" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px"
+	 y="0px" viewBox="0 0 320 320" overflow="visible" xml:space="preserve">
+<!-- <g id="black_bg" display="none"> -->
+<!-- </g> -->
+<g id="logos">
+	<g>
+		<path fill="currentColor" d="M7.1,180.6v117.1c0,8.4,6.8,15.3,15.3,15.3H142C141,239.8,80.9,180.7,7.1,180.6z"/>
+		<path fill="currentColor" d="M7.1,84.1v49.8c99,0.9,179.4,80.7,180.4,179.1h51.7C238.2,186.6,134.5,84.2,7.1,84.1z"/>
+		<path fill="currentColor" d="M312.9,297.6V193.5C278.1,107.2,207.3,38.9,119,7.1H22.4c-8.4,0-15.3,6.8-15.3,15.3v15
+			c152.6,0.9,276.6,124,277.6,275.6h13C306.1,312.9,312.9,306.1,312.9,297.6z"/>
+		<path fill="currentColor" d="M272.6,49.8c14.5,14.4,28.6,31.7,40.4,47.8V22.4c0-8.4-6.8-15.3-15.3-15.3h-77.3
+			C238.4,19.7,256.6,33.9,272.6,49.8z"/>
+	</g>
+</g>
+</svg>
diff --git a/packages/visualiser/src/icons/protocols/nats.svg b/packages/visualiser/src/icons/protocols/nats.svg
new file mode 100644
index 000000000..9cfea9b22
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/nats.svg
@@ -0,0 +1,13 @@
+<svg width="100%" height="100%" viewBox="0 0 64 54" xmlns="http://www.w3.org/2000/svg">
+    <path d="M1.156 50H27.53l15.125 14V50h20.187V0H1.156zm9.937-38.312h11.563l22.25 20.75v-20.75h7.375V38.5H41.094L18.47 17.375V38.5h-7.375z" fill="currentColor"/>
+    <path d="M18.47 17.375L41.094 38.5H52.28V11.687h-7.374v20.75l-22.25-20.75H11.094V38.5h7.375z" fill="currentColor"/>
+    <path d="M1.156 0h61.687v50H1.156z" fill="currentColor"/>
+    <path d="M32 0h30.844v25H32z" fill="currentColor"/>
+    <path d="M32 25h30.844v25H32z" fill="currentColor"/>
+    <path d="M1.156 0H32v25H1.156z" fill="currentColor"/>
+    <g fill="currentColor">
+        <path d="M1.156 25H32v25H1.156z"/>
+        <path d="M32 50l.154 4.303L27.53 50z"/>
+    </g>
+    <path d="M16.367 15.83l26.758 24.984h13.23V9.102h-8.722v24.54L21.32 9.102H7.644v31.71h8.722z" fill="#fff"/>
+</svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/pulsar.svg b/packages/visualiser/src/icons/protocols/pulsar.svg
new file mode 100644
index 000000000..8bcf022e5
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/pulsar.svg
@@ -0,0 +1,4 @@
+
+<svg  viewBox="0 -8 35 40" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M34.7333 8.16353H26.2455C23.9513 3.68838 21.5234 0.21138 18.2199 0.21138C13.9192 0.21138 11.9007 4.0266 9.94695 7.74283L9.77671 8.06867H0V10.2753H5.69498C7.70544 10.2753 8.11483 10.9641 8.11483 10.9641C6.53807 13.4553 4.6411 15.9177 1.47948 15.9177H0V18.2316H1.49164C7.62032 18.2316 10.2955 13.1749 12.4438 9.11631C14.4138 5.37533 15.7879 3.11095 18.2239 3.11095C20.7532 3.11095 23.4122 8.70797 25.751 13.6492C26.0915 14.3669 26.4401 15.101 26.7927 15.8311C17.8186 16.1198 13.5423 18.2563 10.0645 20.001C7.51899 21.2755 5.50852 22.8552 2.20098 22.8552H0V25.1732H2.18071C6.16517 25.1732 8.64988 23.9235 11.2927 22.5954C14.9529 20.7641 19.1035 18.6894 28.8883 18.6894H34.5428V16.3714H31.3487C31.0852 16.392 30.8218 16.3508 30.5786 16.2477C30.3354 16.1487 30.1165 15.9919 29.9422 15.7898C29.3828 14.6886 28.8356 13.5296 28.3006 12.3706L27.5588 10.828C27.5588 10.828 28.0898 10.2506 29.5571 10.2506H34.7333V8.16353Z" fill="currentColor"/>
+</svg>
diff --git a/packages/visualiser/src/icons/protocols/redis.svg b/packages/visualiser/src/icons/protocols/redis.svg
new file mode 100644
index 000000000..add80c598
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/redis.svg
@@ -0,0 +1 @@
+<svg fill="currentColor" viewBox="0 -2 28 28" xmlns="http://www.w3.org/2000/svg"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"><path d="m27.994 14.729c-.012.267-.365.566-1.091.945-1.495.778-9.236 3.967-10.883 4.821-.589.419-1.324.67-2.116.67-.641 0-1.243-.164-1.768-.452l.019.01c-1.304-.622-9.539-3.95-11.023-4.659-.741-.35-1.119-.653-1.132-.933v2.83c0 .282.39.583 1.132.933 1.484.709 9.722 4.037 11.023 4.659.504.277 1.105.44 1.744.44.795 0 1.531-.252 2.132-.681l-.011.008c1.647-.859 9.388-4.041 10.883-4.821.76-.396 1.096-.7 1.096-.982s0-2.791 0-2.791z"></path><path d="m27.992 10.115c-.013.267-.365.565-1.09.944-1.495.778-9.236 3.967-10.883 4.821-.59.421-1.326.672-2.121.672-.639 0-1.24-.163-1.763-.449l.019.01c-1.304-.627-9.539-3.955-11.023-4.664-.741-.35-1.119-.653-1.132-.933v2.83c0 .282.39.583 1.132.933 1.484.709 9.721 4.037 11.023 4.659.506.278 1.108.442 1.749.442.793 0 1.527-.251 2.128-.677l-.011.008c1.647-.859 9.388-4.043 10.883-4.821.76-.397 1.096-.7 1.096-.984s0-2.791 0-2.791z"></path><path d="m27.992 5.329c.014-.285-.358-.534-1.107-.81-1.451-.533-9.152-3.596-10.624-4.136-.528-.242-1.144-.383-1.794-.383-.734 0-1.426.18-2.035.498l.024-.012c-1.731.622-9.924 3.835-11.381 4.405-.729.287-1.086.552-1.073.834v2.83c0 .282.39.583 1.132.933 1.484.709 9.721 4.038 11.023 4.66.504.277 1.105.439 1.744.439.795 0 1.531-.252 2.133-.68l-.011.008c1.647-.859 9.388-4.043 10.883-4.821.76-.397 1.096-.7 1.096-.984s0-2.791 0-2.791h-.009zm-17.967 2.684 6.488-.996-1.96 2.874zm14.351-2.588-4.253 1.68-3.835-1.523 4.246-1.679 3.838 1.517zm-11.265-2.785-.628-1.157 1.958.765 1.846-.604-.499 1.196 1.881.7-2.426.252-.543 1.311-.879-1.457-2.8-.252 2.091-.754zm-4.827 1.632c1.916 0 3.467.602 3.467 1.344s-1.559 1.344-3.467 1.344-3.474-.603-3.474-1.344 1.553-1.344 3.474-1.344z"></path></g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/sns.svg b/packages/visualiser/src/icons/protocols/sns.svg
new file mode 100644
index 000000000..f6448befe
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/sns.svg
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg  viewBox="15 7 55 80" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <g id="Icon-Architecture/64/Arch_AWS-Simple-Notification-Service_64" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <path d="M17,38 C18.103,38 19,38.897 19,40 C19,41.103 18.103,42 17,42 C15.897,42 15,41.103 15,40 C15,38.897 15.897,38 17,38 L17,38 Z M41,64 C29.314,64 19.289,55.466 17.194,43.98 C18.965,43.894 20.427,42.659 20.857,41 L27,41 L27,39 L20.857,39 C20.427,37.342 18.966,36.107 17.195,36.02 C19.285,24.71 29.511,16 41,16 C45.313,16 49.832,17.622 54.429,20.821 L55.571,19.179 C50.633,15.743 45.73,14 41,14 C28.27,14 16.949,23.865 15.063,36.521 C13.839,37.207 13,38.5 13,40 C13,41.5 13.839,42.793 15.063,43.478 C16.97,56.341 28.056,66 41,66 C46.407,66 51.942,64.157 56.585,60.811 L55.415,59.189 C51.11,62.292 45.991,64 41,64 L41,64 Z M30.101,36.442 C31.955,36.895 34.275,37 36,37 C37.642,37 39.823,36.905 41.629,36.506 L37.105,45.553 C37.036,45.691 37,45.845 37,46 L37,50.453 C36.199,50.964 34.833,51.812 34,51.986 L34,46 C34,45.868 33.974,45.737 33.923,45.615 L30.101,36.442 Z M36,33 C40.025,33 42.174,33.604 42.841,34 C42.174,34.396 40.025,35 36,35 C31.975,35 29.826,34.396 29.159,34 C29.826,33.604 31.975,33 36,33 L36,33 Z M33,54 L34,54 C34.043,54 34.086,53.997 34.128,53.992 C35.352,53.833 36.909,52.887 38.272,52.013 L38.535,51.845 C38.824,51.661 39,51.342 39,51 L39,46.236 L44.559,35.12 C44.833,34.801 45,34.434 45,34 C45,31.39 39.361,31 36,31 C32.639,31 27,31.39 27,34 C27,34.366 27.12,34.684 27.32,34.967 L32,46.2 L32,53 C32,53.552 32.447,54 33,54 L33,54 Z M62,53 C63.103,53 64,53.897 64,55 C64,56.103 63.103,57 62,57 C60.897,57 60,56.103 60,55 C60,53.897 60.897,53 62,53 L62,53 Z M62,23 C63.103,23 64,23.897 64,25 C64,26.103 63.103,27 62,27 C60.897,27 60,26.103 60,25 C60,23.897 60.897,23 62,23 L62,23 Z M64,38 C65.103,38 66,38.897 66,40 C66,41.103 65.103,42 64,42 C62.897,42 62,41.103 62,40 C62,38.897 62.897,38 64,38 L64,38 Z M54,41 L60.143,41 C60.589,42.72 62.142,44 64,44 C66.206,44 68,42.206 68,40 C68,37.794 66.206,36 64,36 C62.142,36 60.589,37.28 60.143,39 L54,39 L54,26 L58.143,26 C58.589,27.72 60.142,29 62,29 C64.206,29 66,27.206 66,25 C66,22.794 64.206,21 62,21 C60.142,21 58.589,22.28 58.143,24 L53,24 C52.447,24 52,24.448 52,25 L52,39 L45,39 L45,41 L52,41 L52,55 C52,55.552 52.447,56 53,56 L58.143,56 C58.589,57.72 60.142,59 62,59 C64.206,59 66,57.206 66,55 C66,52.794 64.206,51 62,51 C60.142,51 58.589,52.28 58.143,54 L54,54 L54,41 Z" id="AWS-Simple-Notification-Service_Icon_64_Squid" fill="currentColor"></path>
+    </g>
+</svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/solace.svg b/packages/visualiser/src/icons/protocols/solace.svg
new file mode 100644
index 000000000..86353f308
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/solace.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg id="b" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72"><g id="c"><circle cx="36" cy="36" r="36" fill="currentColor" stroke-width="0"/><path d="m41.21,5.84h0,0m-.13,0l1.45,7.61.16.85.82.28.27.09c.5.17.96.33,1.42.54.46.21.89.45,1.34.71l.25.14.76.43.75-.44,6.66-3.95,5.36,6.11-4.32,5.91-.53.73.39.81c.57,1.18,1.04,2.42,1.39,3.68l.24.87.88.19,7.13,1.56.02,8.13-7.59,1.46-.84.16-.29.81-.04.11c-.19.55-.38,1.06-.6,1.56-.23.52-.51,1.01-.8,1.54l-.04.07-.42.75.44.74,3.93,6.66-6.11,5.36-5.89-4.31-.73-.53-.81.39c-1.18.57-2.42,1.04-3.68,1.39l-.87.24-.19.88-1.57,7.15-8.13.02-1.47-7.62-.16-.84-.81-.29-.13-.05c-.54-.19-1.05-.37-1.54-.6-.49-.22-.97-.48-1.47-.76l-.12-.07-.75-.41-.74.43-6.69,3.94-5.36-6.11,4.32-5.91.53-.73-.39-.81c-.57-1.18-1.04-2.42-1.39-3.68l-.24-.87-.88-.19-7.13-1.56-.02-8.13,7.59-1.46.84-.16.29-.81.03-.08c.2-.57.39-1.1.63-1.62.23-.5.49-.98.77-1.49l.06-.1.42-.75-.44-.74-3.93-6.66,6.11-5.36,5.89,4.31.73.53.81-.39c1.18-.57,2.42-1.04,3.68-1.39l.87-.24.19-.88,1.57-7.15,8.13-.02m.13-1.5s-.02,0-.03,0l-8.32.02h-.01c-.64,0-1.2.44-1.34,1.07l-1.6,7.26c-1.35.38-2.67.88-3.93,1.49l-5.98-4.38c-.24-.17-.52-.26-.8-.26-.33,0-.66.12-.92.35l-6.25,5.49c-.49.43-.6,1.15-.28,1.72l3.99,6.76c-.31.56-.62,1.11-.89,1.7-.27.6-.48,1.2-.7,1.81l-7.71,1.48c-.64.13-1.1.69-1.1,1.34l.02,8.32c0,.65.44,1.21,1.07,1.35l7.24,1.59c.38,1.35.88,2.67,1.49,3.93l-4.38,6c-.37.53-.33,1.24.1,1.72l5.49,6.25c.27.3.65.46,1.03.46.23,0,.47-.06.69-.18l6.79-4c.56.31,1.11.62,1.7.89.59.27,1.19.47,1.79.69l1.49,7.73c.13.64.69,1.1,1.34,1.1l8.32-.02h.01c.64,0,1.2-.44,1.34-1.07l1.6-7.26c1.35-.38,2.67-.88,3.93-1.49l5.98,4.38c.24.17.52.26.8.26.33,0,.66-.12.92-.35l6.25-5.49c.49-.43.6-1.15.28-1.72l-3.99-6.76c.31-.57.62-1.12.89-1.72.27-.59.48-1.19.69-1.79l7.71-1.48c.64-.13,1.1-.69,1.1-1.34l-.02-8.32c0-.65-.44-1.21-1.07-1.35l-7.24-1.59c-.38-1.35-.88-2.67-1.49-3.93l4.38-6c.37-.53.33-1.24-.1-1.72l-5.49-6.25c-.27-.3-.65-.46-1.03-.46-.23,0-.47.06-.69.18l-6.77,4.01c-.56-.32-1.1-.64-1.71-.91-.61-.28-1.21-.47-1.82-.68l-1.47-7.73c-.09-.46-.41-.84-.84-1.02-.15-.06-.32-.09-.48-.09h0Z" fill="#fff" stroke-width="0"/></g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/sqs.svg b/packages/visualiser/src/icons/protocols/sqs.svg
new file mode 100644
index 000000000..907f89dda
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/sqs.svg
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg viewBox="15 7 55 80" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <g id="Icon-Architecture/64/Arch_AWS-Simple-Queue-Service_64" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+       
+        <path d="M28.7169966,43.6876756 L31.7189265,40.721826 C31.9070474,40.5359011 32.0131156,40.2833614 32.0141233,40.019885 C32.0151169,39.7564086 31.9100493,39.5028747 31.722929,39.3159556 L28.7209992,36.3163014 L27.3020871,37.7181948 L28.5899149,39.0057494 L24.0089701,39.0057494 L24.0089701,40.9942506 L28.6059252,40.9942506 L27.3060896,42.2778282 L28.7169966,43.6876756 Z M51.627725,43.7781524 L55.630298,40.793412 C55.8804589,40.6054986 56.0295547,40.3112004 56.0295547,39.9990057 C56.0295547,39.6858168 55.8804589,39.3905244 55.6292974,39.202611 L51.6267243,36.2218476 L50.4259524,37.8126486 L52.0269816,39.0057494 L48.0244085,39.0057494 L48.0244085,40.9942506 L52.025981,40.9942506 L50.4249518,42.1873514 L51.627725,43.7781524 Z M35.2081695,40 C35.2081695,42.1107941 34.8429347,44.1012839 34.160496,45.8332685 C35.9606533,45.14127 37.9909585,44.7952708 40.0192624,44.7952708 C42.0475663,44.7952708 44.0778715,45.14127 45.8770281,45.8332685 C45.19559,44.1012839 44.8303552,42.1107941 44.8303552,40 C44.8303552,37.8892059 45.19559,35.8997104 45.8770281,34.1667315 C42.2777142,35.5497341 37.7608105,35.5497341 34.160496,34.1667315 C34.8429347,35.8997104 35.2081695,37.8892059 35.2081695,40 L35.2081695,40 Z M30.3060182,49.6511909 C30.1108927,49.4573121 30.0128297,49.2027839 30.0128297,48.9482557 C30.0128297,48.6937276 30.1108927,48.4391994 30.3060182,48.2453205 C32.1221857,46.4407556 33.206883,43.3575844 33.206883,40 C33.206883,36.6424156 32.1221857,33.5592444 30.3060182,31.7546795 C30.1108927,31.5608006 30.0128297,31.3062724 30.0128297,31.0517443 C30.0128297,30.7972161 30.1108927,30.5426879 30.3060182,30.3488091 C30.6972697,29.9600571 31.3296762,29.9600571 31.7209277,30.3488091 C35.5984204,34.2015303 44.4401044,34.2015303 48.317597,30.3488091 C48.7088485,29.9600571 49.3412551,29.9600571 49.7325066,30.3488091 C49.927632,30.5426879 50.0256951,30.7972161 50.0256951,31.0517443 C50.0256951,31.3062724 49.927632,31.5608006 49.7325066,31.7546795 C47.9163391,33.5592444 46.8316418,36.6424156 46.8316418,40 C46.8316418,43.3575844 47.9163391,46.4407556 49.7325066,48.2453205 C49.927632,48.4391994 50.0256951,48.6937276 50.0256951,48.9482557 C50.0256951,49.2027839 49.927632,49.4573121 49.7325066,49.6511909 C49.5373812,49.8450698 49.2812165,49.9425064 49.0250518,49.9425064 C48.7688871,49.9425064 48.5127225,49.8450698 48.317597,49.6511909 C44.4401044,45.7984697 35.5984204,45.7984697 31.7209277,49.6511909 C31.3296762,50.0399429 30.6972697,50.0399429 30.3060182,49.6511909 L30.3060182,49.6511909 Z M66.0009649,40.0049713 C66.0009649,39.0783297 65.6377314,38.2073661 64.9783075,37.5521549 C64.2978701,36.8750702 63.403295,36.5380193 62.5097205,36.5380193 C61.6161461,36.5380193 60.721571,36.8750702 60.0411336,37.5521549 C58.6792581,38.9043358 58.6792581,41.1046125 60.0411336,42.4577876 C61.4020084,43.8099684 63.6154313,43.8109627 64.9783075,42.4577876 C65.6377314,41.8025764 66.0009649,40.9316128 66.0009649,40.0049713 L66.0009649,40.0049713 Z M66.3932171,43.863658 C65.3225288,44.9275062 63.916625,45.4594303 62.5097205,45.4594303 C61.1028161,45.4594303 59.6969123,44.9275062 58.626224,43.863658 C56.4838468,41.7359616 56.4838468,38.2739809 58.626224,36.1462845 C60.7686012,34.0165997 64.2528411,34.0185882 66.3932171,36.1462845 C68.5355943,38.2739809 68.5355943,41.7359616 66.3932171,43.863658 L66.3932171,43.863658 Z M20.9800229,40.027839 C20.9800229,39.1011974 20.6167894,38.2302339 19.9573654,37.5750227 C19.2979415,36.9198115 18.421378,36.5588985 17.4887785,36.5588985 C16.5571796,36.5588985 15.6806161,36.9198115 15.0201916,37.5750227 C14.3607676,38.2302339 13.9985348,39.1011974 13.9985348,40.027839 C13.9985348,40.9534864 14.3607676,41.8244499 15.0201916,42.4806553 C16.34004,43.7900834 18.6385176,43.7900834 19.9573654,42.4806553 C20.6167894,41.8244499 20.9800229,40.9534864 20.9800229,40.027839 L20.9800229,40.027839 Z M21.372275,43.8865257 C20.3015867,44.9503739 18.8956829,45.482298 17.4887785,45.482298 C16.0828747,45.482298 14.6769709,44.9503739 13.605282,43.8865257 C11.464906,41.7588294 11.464906,38.2968487 13.605282,36.1691523 C15.7476592,34.0414559 19.2308984,34.0414559 21.372275,36.1691523 C23.5136516,38.2968487 23.5136516,41.7588294 21.372275,43.8865257 L21.372275,43.8865257 Z M54.8958259,54.856093 C50.901258,58.8261358 45.5888428,61.0114987 39.9392109,61.0114987 C34.2875777,61.0114987 28.9761632,58.8261358 24.9815953,54.856093 C22.241834,52.134829 20.7338646,48.8826352 19.9513616,46.6346345 L18.0601458,47.2848744 C18.9116932,49.730731 20.5577514,53.273246 23.5666857,56.2619634 C27.9394968,60.607833 33.7532342,63 39.9392109,63 C46.124187,63 51.9379244,60.607833 56.3107355,56.2619634 C58.8373597,53.7534691 60.8496533,50.563913 61.9793796,47.2818917 L60.0861625,46.6376173 C59.0534987,49.6382657 57.2103138,52.5573856 54.8958259,54.856093 L54.8958259,54.856093 Z M19.9503609,33.3663597 L18.0611465,32.7141313 C19.2719248,29.2501621 21.229183,26.0606061 23.5726896,23.7330653 C27.9434994,19.3911728 33.7552355,17 39.9392109,17 C46.1231863,17 51.9349225,19.3911728 56.3047316,23.7330653 C58.7713173,26.1838931 60.8396469,29.4569662 61.9773783,32.7141313 L60.0881638,33.3663597 C59.0444929,30.3836078 57.1502752,27.3849479 54.889822,25.1389357 C50.898256,21.1718757 45.5878422,18.9885013 39.9392109,18.9885013 C34.289579,18.9885013 28.9801658,21.1718757 24.9875992,25.1389357 C22.8542277,27.2596723 21.0650775,30.181775 19.9503609,33.3663597 L19.9503609,33.3663597 Z" id="AWS-Simple-Queue-Service_Icon_64_Squid" fill="currentColor"></path>
+    </g>
+</svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/tibo-ftl.svg b/packages/visualiser/src/icons/protocols/tibo-ftl.svg
new file mode 100644
index 000000000..94dc4edae
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/tibo-ftl.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg"  viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-mailbox-icon lucide-mailbox"><path d="M22 17a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V9.5C2 7 4 5 6.5 5H18c2.2 0 4 1.8 4 4v8Z"/><polyline points="15,9 18,9 18,11"/><path d="M6.5 5C9 5 11 7 11 9.5V17a2 2 0 0 1-2 2"/><line x1="6" x2="7" y1="10" y2="10"/></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/tibo-rv.svg b/packages/visualiser/src/icons/protocols/tibo-rv.svg
new file mode 100644
index 000000000..8dc473160
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/tibo-rv.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-mailbox-icon lucide-mailbox"><path d="M22 17a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V9.5C2 7 4 5 6.5 5H18c2.2 0 4 1.8 4 4v8Z"/><polyline points="15,9 18,9 18,11"/><path d="M6.5 5C9 5 11 7 11 9.5V17a2 2 0 0 1-2 2"/><line x1="6" x2="7" y1="10" y2="10"/></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/webrtc.svg b/packages/visualiser/src/icons/protocols/webrtc.svg
new file mode 100644
index 000000000..0ac54918f
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/webrtc.svg
@@ -0,0 +1 @@
+<svg viewBox="0 -3.5 256 256" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid" fill="#000000"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"> <g> <path d="M142.076578,191.086817 C142.076578,159.280656 116.294759,133.494615 84.4885969,133.494615 C52.6782136,133.494615 26.896394,159.280656 26.896394,191.086817 C26.896394,222.892979 52.6782136,248.67902 84.4885969,248.67902 C116.294759,248.67902 142.076578,222.892979 142.076578,191.086817" fill="#FF6600" transform="translate(84.486486, 191.086817) scale(1, -1) translate(-84.486486, -191.086817) "> </path> <path d="M255.979703,110.454356 C255.979703,78.652416 230.197884,52.862153 198.391722,52.862153 C166.581339,52.862153 140.799519,78.652416 140.799519,110.454356 C140.799519,142.260518 166.581339,168.050781 198.391722,168.050781 C230.197884,168.050781 255.979703,142.260518 255.979703,110.454356" fill="#FFCC00" transform="translate(198.389611, 110.456467) scale(1, -1) translate(-198.389611, -110.456467) "> </path> <path d="M115.200498,109.176452 C115.200498,77.3745125 89.4186786,51.5842495 57.6082953,51.5842495 C25.8063553,51.5842495 0.0203140271,77.3745125 0.0203140271,109.176452 C0.0203140271,140.982614 25.8063553,166.772877 57.6082953,166.772877 C89.4186786,166.772877 115.200498,140.982614 115.200498,109.176452" fill="#0089CC" transform="translate(57.610406, 109.178563) scale(1, -1) translate(-57.610406, -109.178563) "> </path> <path d="M230.385749,191.086817 C230.385749,159.280656 204.603929,133.494615 172.789324,133.494615 C140.987384,133.494615 115.201343,159.280656 115.201343,191.086817 C115.201343,222.892979 140.987384,248.67902 172.789324,248.67902 C204.603929,248.67902 230.385749,222.892979 230.385749,191.086817" fill="#009939" transform="translate(172.793546, 191.086817) scale(1, -1) translate(-172.793546, -191.086817) "> </path> <path d="M185.592001,57.9843213 C185.592001,26.1781597 159.805959,0.392118349 127.999798,0.392118349 C96.1936359,0.392118349 70.4075946,26.1781597 70.4075946,57.9843213 C70.4075946,89.790483 96.1936359,115.576524 127.999798,115.576524 C159.805959,115.576524 185.592001,89.790483 185.592001,57.9843213" fill="#BF0000" transform="translate(127.999798, 57.984321) scale(1, -1) translate(-127.999798, -57.984321) "> </path> <path d="M140.798675,57.9788331 C140.798675,56.76721 140.904217,55.580917 140.980207,54.3861807 C166.525612,60.2796505 185.590734,83.1189569 185.590734,110.454356 C185.590734,111.665979 185.485192,112.856494 185.409202,114.05123 C159.863796,108.153539 140.798675,85.3142322 140.798675,57.9788331" fill="#FC0007" transform="translate(163.194704, 84.218705) scale(1, -1) translate(-163.194704, -84.218705) "> </path> <path d="M148.39686,162.570614 C158.322038,145.219495 176.973434,133.495881 198.394255,133.495881 C207.124696,133.495881 215.369643,135.496959 222.787141,138.975626 C212.866185,156.326744 194.214789,168.050358 172.789746,168.050358 C164.059305,168.050358 155.814358,166.049281 148.39686,162.570614" fill="#1CD306" transform="translate(185.592001, 150.773120) scale(1, -1) translate(-185.592001, -150.773120) "> </path> <path d="M115.200498,191.086817 C115.200498,177.015947 120.258075,164.139813 128.642338,154.138646 C137.018157,164.139813 142.075734,177.015947 142.075734,191.086817 C142.075734,205.157688 137.018157,218.033822 128.642338,228.034989 C120.258075,218.033822 115.200498,205.157688 115.200498,191.086817" fill="#0F7504" transform="translate(128.638116, 191.086817) scale(1, -1) translate(-128.638116, -191.086817) "> </path> <path d="M34.806984,138.212768 C41.8023132,135.190043 49.5026635,133.497148 57.6082953,133.497148 C78.818032,133.497148 97.2963396,144.992791 107.293286,162.061056 C100.297956,165.083782 92.5933844,166.772455 84.4919743,166.772455 C63.2822376,166.772455 44.7997083,155.276811 34.806984,138.212768" fill="#0C5E87" transform="translate(71.050135, 150.134801) scale(1, -1) translate(-71.050135, -150.134801) "> </path> <path d="M70.6545631,114.036032 C70.5194692,112.431792 70.4054838,110.819109 70.4054838,109.176875 C70.4054838,81.862584 89.4410536,59.044386 114.956907,53.1255861 C115.087779,54.7298257 115.201765,56.3425087 115.201765,57.9805218 C115.201765,85.2948125 96.1704167,108.121454 70.6545631,114.036032" fill="#6B0001" transform="translate(92.803624, 83.580809) scale(1, -1) translate(-92.803624, -83.580809) "> </path> <path d="M76.0304545,111.503866 L67.0213825,111.503866 C59.0677312,111.503866 52.6001125,117.950377 52.6001125,125.88292 L52.6001125,207.428953 C52.6001125,215.361496 59.0677312,221.812228 67.0213825,221.812228 L179.989405,221.812228 C187.943056,221.812228 194.406453,215.361496 194.406453,207.428953 L194.406453,125.88292 C194.406453,117.950377 187.943056,111.503866 179.989405,111.503866 L141.50454,111.503866 L64.2899534,73.6522544 L76.0304545,111.503866 L76.0304545,111.503866 Z" fill="#FFFFFF" transform="translate(123.503283, 147.732241) scale(1, -1) translate(-123.503283, -147.732241) "> </path> </g> </g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/ws.svg b/packages/visualiser/src/icons/protocols/ws.svg
new file mode 100644
index 000000000..d03c4348b
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/ws.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg id="b" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72"><g id="c"><circle cx="36" cy="36" r="36" fill="#333" stroke-width="0"/><path d="m48.38,23.39l7.48,7.48v15.98h-6.69v-13.15l-5.55-5.55,4.76-4.76Zm-7.14,33.55h-11.45l-7.48-7.48,4.65-4.65-11.56-11.56v-6.57h6.69v3.74l4.87,4.87,7.14-7.14-4.87-4.87h-13.83l-6.69-6.69h23.23l11.56,11.67-2.38,2.38,4.53,4.53v9.41l-9.29-9.29-2.38,2.38,9.29,9.29h-9.41l-4.65-4.65-2.38,2.38,5.55,5.55h23.35l6.69,6.57-21.19.11h0Z" fill="#fff" stroke-width="0"/></g></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/icons/protocols/zmq.svg b/packages/visualiser/src/icons/protocols/zmq.svg
new file mode 100644
index 000000000..f550f37c3
--- /dev/null
+++ b/packages/visualiser/src/icons/protocols/zmq.svg
@@ -0,0 +1 @@
+<svg version="1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 525 525"><path d="M245.85 3c-.07.15-3.07.45-6.6 0.75-7.27.6-7.35.6-24.38 3.15-1.2.22-2.78.52-3.38.68-.6.15-1.95.45-3 0.68-4.8 0.82-20.55 5.03-26.7 7.05-24.45 8.18-50.93 21.23-67.8 33.38-2.4 1.72-5.1 3.68-6 4.28-1 0.6-4.43 3.3-7.8 5.93-36.23 28.65-64.65 66.6-81.38 108.68-6.83 17.1-13.5 41.1-15.45 55.65-.22 1.88-.6 4.2-0.83 5.25-.38 2.1-.68 4.8-1.58 14.25-1.13 12.15-.6 44.18 0.9 53.33.15 0.98.45 3.45 0.75 5.55 0.68 5.7 1.2 8.7 1.88 12 0.38 1.65 0.83 3.98 1.05 5.25 0.68 3.68 0.98 4.95 2.7 11.63 1.58 6.38 5.48 19.28 6.68 22.13 0.38 0.83 1.88 4.88 3.45 9 3.68 9.75 13.65 30.08 18.83 38.33 2.25 3.53 4.05 6.75 4.05 7.13s-9.15 9.9-20.33 21.08l-20.25 20.4 39.23 39.23 39.3 39.3 20.25-20.25c11.18-11.18 20.78-20.33 21.3-20.33.53 0 2.7 1.13 4.8 2.55 2.1 1.35 6.53 3.98 9.83 5.7 3.3 1.8 6.38 3.45 6.75 3.75 0.68 0.45 14.1 6.68 20.25 9.38 15.9 6.98 45.53 15 64.13 17.33 1.05 0.15 3.08 0.38 4.5 0.6 14.03 2.18 49.05 2.1 63.75 0 20.18-2.93 35.18-6.45 51.75-12 43.58-14.78 84.08-41.63 112.73-74.93 2.48-2.93 4.73-5.4 5.03-5.63 0.23-0.23 2.63-3.23 5.33-6.75 31.2-40.5 49.65-87.45 54.45-138.38 1.13-11.63 0.45-52.2 0.9-54.38-.15-0.23-.45-2.25-0.68-4.5-.23-2.25-0.6-4.8-0.75-5.63-.15-0.83-0.83-4.58-1.58-8.25-5.33-28.8-16.8-58.73-32.33-84.83-2.25-3.75-4.05-7.05-4.05-7.43 0-0.3 8.33-8.93 18.6-19.13 10.2-10.2 19.28-19.43 20.18-20.4l1.65-1.8-39.23-39.23L445.73 0.6l-20.33 20.33C414.23 32.1 404.85 41.25 404.48 41.25s-3.15-1.58-6.23-3.53c-26.18-16.28-63.23-29.78-94.13-34.43-2.03-0.3-4.28-0.68-4.88-0.75-.6-.15-3.3-.45-6-0.68-2.7-0.3-5.78-0.68-6.75-0.9-2.03-0.38-40.2-1.05-40.65-0.68zm30.83 100.5c4.58 0.45 6.68 0.68 12.45 1.5 4.2 0.6 12.75 2.63 19.5 4.58 7.13 2.1 22.13 7.73 22.13 8.33 0 0.53-215.05 215.55-215.55 215.55-1.05 0-10.05-26.25-11.18-32.7-.23-1.2-0.9-5.03-1.58-8.55-2.55-14.1-2.93-38.55-0.83-49.65 0.23-0.9 0.83-4.58 1.5-8.18 0.6-3.53 2.25-10.35 3.75-15.15 10.35-34.35 28.2-60.15 58-83.93 4.88-3.83 17.4-11.4 25.8-15.6 8.85-4.35 27.23-11.18 33-11.7 1.8-0.3 7.43-1.43 8.1-1.58 0.23-0.08 2.1-0.38 4.13-0.75 2.1-0.3 4.43-0.68 5.25-0.83 0.83-0.15 4.58-0.53 8.25-0.75 3.75-0.3 6.83-0.53 6.9-0.68 0.38-0.23 15.38 0.23 20.4 0.68zm134.63 96.6c8.7 20.03 13.43 43.05 13.5 65.1 0 6.53-0.75 18.38-1.43 21.75-0.23 0.98-0.53 3.15-0.83 4.88-2.78 19.28-12.9 45.23-24.08 62.03-16.95 25.28-38 43.88-64.35 56.85-23.4 11.48-46.73 16.88-72.75 16.8-11.4-0.08-18.38-0.75-29.33-2.93-3.23-0.68-6.9-1.43-8.18-1.65-4.88-0.83-27.3-8.85-29.55-10.5-.3-0.23 214.58-215.4 215.18-215.4 0.23 0 1.05 1.43 1.8 3.15z"/></svg>
\ No newline at end of file
diff --git a/packages/visualiser/src/index.ts b/packages/visualiser/src/index.ts
new file mode 100644
index 000000000..5117b7c0e
--- /dev/null
+++ b/packages/visualiser/src/index.ts
@@ -0,0 +1,46 @@
+/**
+ * @eventcatalog/visualizer
+ *
+ * Framework-agnostic visualizer components for EventCatalog
+ */
+
+// Types
+export type {
+  BaseNodeData,
+  NodeType,
+  EdgeType,
+  VisualizerCallbacks,
+  NodeConfiguration,
+  VisualizerMode,
+  VisualizerLink,
+  EventCatalogResource,
+  Message,
+  Agent,
+  AgentTool,
+  Channel,
+  ExternalSystem,
+  Data,
+  View,
+  RegisteredNode,
+  NodeCategory,
+  ContextMenuItem,
+  GraphNode,
+  GraphEdge,
+  GraphEdgeType,
+  DslGraph,
+} from "./types";
+// Re-export Service type under a non-colliding name so the `Service` React
+// component value export from ./nodes survives the barrel merge.
+export type { Service as ServiceType } from "./types";
+
+// Components
+export * from "./components";
+
+// Nodes
+export * from "./nodes";
+
+// Edges
+export * from "./edges";
+
+// Utils
+export * from "./utils";
diff --git a/packages/visualiser/src/nodes/Agent.tsx b/packages/visualiser/src/nodes/Agent.tsx
new file mode 100644
index 000000000..2ed46d59a
--- /dev/null
+++ b/packages/visualiser/src/nodes/Agent.tsx
@@ -0,0 +1,231 @@
+import { memo, useMemo } from "react";
+import { Bot } from "lucide-react";
+import { Node, Handle, Position, useNodeConnections } from "@xyflow/react";
+import { EventCatalogResource } from "../types";
+import { NotesIndicator } from "./NotesIndicator";
+import {
+  OwnerIndicator,
+  normalizeOwners,
+  HIDDEN_HANDLE_STYLE,
+} from "./OwnerIndicator";
+import { LINE_CLAMP_STYLE, useDarkMode } from "./shared-styles";
+import { CustomIcon, isIconPath, resolveIconUrl } from "../utils/custom-icon";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+function GlowHandle({ side }: { side: "left" | "right" }) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: "linear-gradient(135deg, #0ea5e9, #0369a1)",
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: "ec-dp-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none",
+      }}
+    />
+  );
+}
+
+const getProviderIconSrc = (provider: string | undefined, isDark: boolean) => {
+  if (!provider) return null;
+  const providerIconName = provider
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-]/g, "");
+
+  const iconPath =
+    providerIconName === "openai" || providerIconName === "anthropic"
+      ? `/icons/agent/${providerIconName}-${isDark ? "dark" : "light"}.svg`
+      : `/icons/agent/${providerIconName}.svg`;
+
+  return resolveIconUrl(iconPath);
+};
+
+type AgentNodeData = EventCatalogResource & {
+  agent: {
+    id: string;
+    version: string;
+    name: string;
+    summary?: string;
+    owners?: any[];
+    deprecated?: boolean;
+    draft?: boolean;
+    notes?: import("../types").Note[];
+    model?: {
+      provider?: string;
+      name?: string;
+      version?: string;
+    };
+    styles?: {
+      icon?: string;
+      node?: { color?: string; label?: string };
+    };
+  };
+};
+
+export type AgentNode = Node<AgentNodeData, "agent">;
+
+function Agent(props: AgentNode) {
+  const {
+    version,
+    name,
+    summary,
+    deprecated,
+    draft,
+    notes,
+    owners,
+    model,
+    styles,
+  } = props.data.agent;
+  const mode = props.data.mode || "simple";
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+  const normalizedOwners = useMemo(() => normalizeOwners(owners), [owners]);
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const isDark = useDarkMode();
+  const deprecatedStripe = isDark
+    ? "rgba(239,68,68,0.25)"
+    : "rgba(239,68,68,0.1)";
+  const draftStripe = isDark
+    ? "rgba(14,165,233,0.25)"
+    : "rgba(14,165,233,0.15)";
+  const providerLabel = model?.provider;
+  const providerIconSrc = getProviderIconSrc(providerLabel, isDark);
+  const modelLabel = model?.name;
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible",
+        props?.selected ? "ring-2 ring-sky-400/60 ring-offset-2" : "",
+        deprecated
+          ? "border-dashed border-red-500"
+          : draft
+            ? "border-dashed border-sky-400"
+            : "border-sky-500",
+      )}
+      style={{
+        background: deprecated
+          ? `repeating-linear-gradient(135deg, transparent, transparent 6px, ${deprecatedStripe} 6px, ${deprecatedStripe} 7px), var(--ec-agent-node-bg, rgb(var(--ec-card-bg)))`
+          : draft
+            ? `repeating-linear-gradient(135deg, transparent, transparent 4px, ${draftStripe} 4px, ${draftStripe} 4.5px), var(--ec-agent-node-bg, rgb(var(--ec-card-bg)))`
+            : "var(--ec-agent-node-bg, rgb(var(--ec-card-bg)))",
+        boxShadow: "0 2px 12px rgba(14, 165, 233, 0.15)",
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {targetConnections.length > 0 && <GlowHandle side="left" />}
+      {sourceConnections.length > 0 && <GlowHandle side="right" />}
+
+      <div className="absolute -top-2.5 left-2.5 flex items-center gap-1.5 z-10">
+        <span
+          className={classNames(
+            "inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm",
+            deprecated ? "bg-red-500" : "bg-sky-500",
+          )}
+        >
+          <Bot className="w-2.5 h-2.5" strokeWidth={2.5} />
+          Agent
+          {draft && " (Draft)"}
+          {deprecated && " (Deprecated)"}
+        </span>
+      </div>
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        <div className="flex items-center gap-2">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className={
+                mode === "full"
+                  ? "w-[26px] h-[26px] shrink-0"
+                  : "w-4 h-4 shrink-0 -my-1"
+              }
+            />
+          )}
+          <div className="flex items-baseline gap-1 min-w-0">
+            <TruncatedResourceName
+              value={name}
+              tooltipBorderColor="#0ea5e9"
+              className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+            >
+              {name}
+            </TruncatedResourceName>
+            {version && (
+              <span className="text-[10px] font-normal text-[rgb(var(--ec-page-text-muted))] shrink-0">
+                (v{version})
+              </span>
+            )}
+          </div>
+        </div>
+
+        {mode === "full" && summary && (
+          <div
+            className="mt-1.5 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+
+        {(providerLabel || modelLabel) && (
+          <div className="flex items-center gap-1 flex-wrap mt-1.5">
+            {providerLabel && (
+              <span className="inline-flex items-center text-[7px] font-bold px-1.5 py-0.5 rounded bg-sky-500/10 text-sky-700 dark:text-sky-300 uppercase tracking-wide">
+                {providerIconSrc && (
+                  <img
+                    src={providerIconSrc}
+                    alt=""
+                    className="w-2 h-2 shrink-0 mr-1 object-contain"
+                    loading="lazy"
+                  />
+                )}
+                {providerLabel}
+              </span>
+            )}
+            {modelLabel && (
+              <span className="inline-flex items-center text-[7px] font-bold px-1.5 py-0.5 rounded bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text-muted))] border border-sky-500/30 max-w-[8.5rem] truncate">
+                {modelLabel}
+              </span>
+            )}
+          </div>
+        )}
+
+        <OwnerIndicator
+          owners={normalizedOwners}
+          accentColor="bg-sky-400"
+          borderColor="rgba(14,165,233,0.08)"
+          iconClass="text-sky-300"
+        />
+      </div>
+    </div>
+  );
+}
+
+export default memo(Agent);
diff --git a/packages/visualiser/src/nodes/AgentTool.tsx b/packages/visualiser/src/nodes/AgentTool.tsx
new file mode 100644
index 000000000..a7a088817
--- /dev/null
+++ b/packages/visualiser/src/nodes/AgentTool.tsx
@@ -0,0 +1,154 @@
+import { memo } from "react";
+import { Wrench } from "lucide-react";
+import { Handle, Node, Position, useNodeConnections } from "@xyflow/react";
+import { EventCatalogResource } from "../types";
+import { HIDDEN_HANDLE_STYLE } from "./OwnerIndicator";
+import { LINE_CLAMP_STYLE, useDarkMode } from "./shared-styles";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+import { CustomIcon, isIconPath } from "../utils/custom-icon";
+import mcpDark from "../icons/protocols/mcp-dark.svg?raw";
+import mcpLight from "../icons/protocols/mcp-light.svg?raw";
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+type AgentToolData = EventCatalogResource & {
+  agentTool: {
+    id?: string;
+    name: string;
+    type: string;
+    icon?: string;
+    url?: string;
+    description?: string;
+  };
+};
+
+export type AgentToolNode = Node<AgentToolData, "agentTool">;
+
+const normalizeType = (type?: string) => (type || "").trim().toLowerCase();
+
+function ToolTypeBadge({ type }: { type: string }) {
+  const isDark = useDarkMode();
+  const normalizedType = normalizeType(type);
+  const label = type.toUpperCase();
+
+  if (normalizedType === "mcp") {
+    return (
+      <span className="inline-flex items-center gap-1 text-[7px] font-bold px-1.5 py-0.5 rounded bg-violet-500/10 text-violet-700 dark:text-violet-300 border border-violet-500/25">
+        <span
+          className="w-2 h-2 shrink-0 [&>svg]:w-2 [&>svg]:h-2"
+          dangerouslySetInnerHTML={{ __html: isDark ? mcpDark : mcpLight }}
+        />
+        MCP
+      </span>
+    );
+  }
+
+  return (
+    <span className="inline-flex items-center text-[7px] font-bold px-1.5 py-0.5 rounded bg-violet-500/10 text-violet-700 dark:text-violet-300 border border-violet-500/25">
+      {label}
+    </span>
+  );
+}
+
+function GlowHandle({ side }: { side: "left" | "right" }) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: "linear-gradient(135deg, #8b5cf6, #6d28d9)",
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: "ec-dp-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none",
+      }}
+    />
+  );
+}
+
+function AgentTool(props: AgentToolNode) {
+  const { name, type, icon, url, description } = props.data.agentTool;
+  const customIcon = isIconPath(icon) ? icon : undefined;
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible border-violet-500",
+        props?.selected ? "ring-2 ring-violet-400/60 ring-offset-2" : "",
+      )}
+      style={{
+        background: "var(--ec-agent-tool-node-bg, rgb(var(--ec-card-bg)))",
+        boxShadow: "0 2px 12px rgba(139, 92, 246, 0.15)",
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {targetConnections.length > 0 && <GlowHandle side="left" />}
+      {sourceConnections.length > 0 && <GlowHandle side="right" />}
+
+      <div className="absolute -top-2.5 left-2.5 flex items-center gap-1.5 z-10">
+        <span className="inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm bg-violet-500">
+          <Wrench className="w-2.5 h-2.5" strokeWidth={2.5} />
+          Tool
+        </span>
+      </div>
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        <div className="flex items-center gap-2 min-w-0">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className="w-4 h-4 shrink-0"
+            />
+          )}
+          <TruncatedResourceName
+            value={name}
+            tooltipBorderColor="#8b5cf6"
+            className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+          >
+            {name}
+          </TruncatedResourceName>
+        </div>
+
+        {description && (
+          <div
+            className="mt-1.5 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={description}
+          >
+            {description}
+          </div>
+        )}
+
+        <div className="mt-1.5 flex items-center gap-1 flex-wrap">
+          <ToolTypeBadge type={type} />
+          {url && (
+            <span className="inline-flex items-center text-[7px] font-bold px-1.5 py-0.5 rounded bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text-muted))] border border-violet-500/25 max-w-[9rem] truncate">
+              {url}
+            </span>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default memo(AgentTool);
diff --git a/packages/visualiser/src/nodes/ApiInfo.tsx b/packages/visualiser/src/nodes/ApiInfo.tsx
new file mode 100644
index 000000000..a9b286135
--- /dev/null
+++ b/packages/visualiser/src/nodes/ApiInfo.tsx
@@ -0,0 +1,74 @@
+import { memo } from "react";
+
+const METHOD_COLORS: Record<string, { bg: string; text: string }> = {
+  GET: { bg: "rgba(34,197,94,0.15)", text: "#22c55e" },
+  POST: { bg: "rgba(59,130,246,0.15)", text: "#3b82f6" },
+  PUT: { bg: "rgba(245,158,11,0.15)", text: "#f59e0b" },
+  PATCH: { bg: "rgba(245,158,11,0.15)", text: "#f59e0b" },
+  DELETE: { bg: "rgba(239,68,68,0.15)", text: "#ef4444" },
+  OPTIONS: { bg: "rgba(139,92,246,0.15)", text: "#8b5cf6" },
+  HEAD: { bg: "rgba(107,114,128,0.15)", text: "#6b7280" },
+};
+
+const STATUS_COLORS: Record<string, { bg: string; text: string }> = {
+  "2": { bg: "rgba(34,197,94,0.15)", text: "#22c55e" },
+  "3": { bg: "rgba(59,130,246,0.15)", text: "#3b82f6" },
+  "4": { bg: "rgba(245,158,11,0.15)", text: "#f59e0b" },
+  "5": { bg: "rgba(239,68,68,0.15)", text: "#ef4444" },
+};
+
+function getStatusColor(code: number) {
+  const prefix = String(code)[0];
+  return STATUS_COLORS[prefix] || STATUS_COLORS["2"];
+}
+
+export const MethodBadge = memo(function MethodBadge({
+  method,
+}: {
+  method: string;
+}) {
+  const upper = method.toUpperCase();
+  const colors = METHOD_COLORS[upper] || { bg: "#6b7280", text: "#ffffff" };
+  return (
+    <span
+      className="inline-flex items-center text-[8px] font-extrabold uppercase tracking-wide px-1.5 py-0.5 rounded"
+      style={{ background: colors.bg, color: colors.text }}
+    >
+      {upper}
+    </span>
+  );
+});
+
+export const StatusCodes = memo(function StatusCodes({
+  codes,
+}: {
+  codes: number[];
+}) {
+  return (
+    <div className="flex items-center gap-1 flex-wrap mt-1.5">
+      {codes.map((code) => {
+        const colors = getStatusColor(code);
+        return (
+          <span
+            key={code}
+            className="inline-flex items-center text-[8px] font-bold px-1.5 py-0.5 rounded"
+            style={{ background: colors.bg, color: colors.text }}
+          >
+            {code}
+          </span>
+        );
+      })}
+    </div>
+  );
+});
+
+export const ApiPath = memo(function ApiPath({ path }: { path: string }) {
+  return (
+    <span
+      className="text-[12px] font-mono font-medium text-[rgb(var(--ec-page-text))] truncate min-w-0"
+      title={path}
+    >
+      {path}
+    </span>
+  );
+});
diff --git a/packages/visualiser/src/nodes/ContextActor.tsx b/packages/visualiser/src/nodes/ContextActor.tsx
new file mode 100644
index 000000000..7f0001b9d
--- /dev/null
+++ b/packages/visualiser/src/nodes/ContextActor.tsx
@@ -0,0 +1,57 @@
+import { memo } from "react";
+import { Handle, Position } from "@xyflow/react";
+import { User } from "lucide-react";
+import { HIDDEN_HANDLE_STYLE } from "./OwnerIndicator";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+
+interface Data {
+  name: string;
+}
+
+/**
+ * An actor (person/role) on the System Diagram.
+ *
+ * Deliberately styled differently from the boxy resource nodes: a soft, pill-ish
+ * card with the actor icon in a circular badge centered at the top and the actor
+ * name centered below. This reads as "a person", not "a system", at a glance.
+ */
+export default memo(function ContextActorNode({ data }: any) {
+  const { name } = data as Data;
+
+  return (
+    <div
+      className="relative flex w-44 flex-col items-center rounded-2xl border-2 border-yellow-500 bg-[var(--ec-actor-node-bg,rgb(var(--ec-card-bg)))] px-3 pb-3 pt-5"
+      style={{ boxShadow: "0 2px 12px rgba(234, 179, 8, 0.15)" }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+
+      {/* Icon badge — centered, straddling the top border like an avatar */}
+      <div className="absolute -top-4 left-1/2 -translate-x-1/2">
+        <div className="flex h-8 w-8 items-center justify-center rounded-full border-2 border-yellow-500 bg-[rgb(var(--ec-card-bg))] shadow-sm">
+          <User className="h-4 w-4 text-yellow-500" strokeWidth={2} />
+        </div>
+      </div>
+
+      <TruncatedResourceName
+        as="div"
+        value={name}
+        className="mt-1 max-w-full text-center text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+      >
+        {name}
+      </TruncatedResourceName>
+
+      <span className="mt-0.5 text-[8px] font-bold uppercase tracking-widest text-yellow-600 dark:text-yellow-400">
+        Actor
+      </span>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/Custom.tsx b/packages/visualiser/src/nodes/Custom.tsx
new file mode 100644
index 000000000..bb72d889a
--- /dev/null
+++ b/packages/visualiser/src/nodes/Custom.tsx
@@ -0,0 +1,377 @@
+import { memo, useMemo, type ComponentType } from "react";
+import { Handle, Position, useNodeConnections } from "@xyflow/react";
+import * as Icons from "@heroicons/react/24/solid";
+import * as ContextMenu from "@radix-ui/react-context-menu";
+import { HIDDEN_HANDLE_STYLE } from "./OwnerIndicator";
+import { EMPTY_ARRAY, EMPTY_OBJECT, LINE_CLAMP_STYLE } from "./shared-styles";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+import { usePortalContainer } from "../context/PortalContainerContext";
+
+type MenuItem = {
+  label: string;
+  url?: string;
+};
+
+type CustomColor =
+  | "blue"
+  | "teal"
+  | "red"
+  | "green"
+  | "purple"
+  | "orange"
+  | "pink"
+  | "yellow"
+  | "gray"
+  | "indigo"
+  | "cyan"
+  | "slate"
+  | "amber"
+  | "emerald"
+  | "violet"
+  | "rose";
+
+type CustomPalette = {
+  border: string;
+  badge: string;
+  ring: string;
+  shadow: string;
+  glow: string;
+  pillBorder: string;
+};
+
+const PALETTES: Record<CustomColor, CustomPalette> = {
+  blue: {
+    border: "border-blue-500",
+    badge: "bg-blue-500",
+    ring: "ring-2 ring-blue-400/60 ring-offset-2",
+    shadow: "rgba(59, 130, 246, 0.15)",
+    glow: "linear-gradient(135deg, #3b82f6, #2563eb)",
+    pillBorder: "#3b82f6",
+  },
+  teal: {
+    border: "border-teal-500",
+    badge: "bg-teal-500",
+    ring: "ring-2 ring-teal-400/60 ring-offset-2",
+    shadow: "rgba(20, 184, 166, 0.15)",
+    glow: "linear-gradient(135deg, #14b8a6, #0f766e)",
+    pillBorder: "#14b8a6",
+  },
+  red: {
+    border: "border-red-500",
+    badge: "bg-red-500",
+    ring: "ring-2 ring-red-400/60 ring-offset-2",
+    shadow: "rgba(239, 68, 68, 0.15)",
+    glow: "linear-gradient(135deg, #ef4444, #b91c1c)",
+    pillBorder: "#ef4444",
+  },
+  green: {
+    border: "border-green-500",
+    badge: "bg-green-500",
+    ring: "ring-2 ring-green-400/60 ring-offset-2",
+    shadow: "rgba(34, 197, 94, 0.15)",
+    glow: "linear-gradient(135deg, #22c55e, #15803d)",
+    pillBorder: "#22c55e",
+  },
+  purple: {
+    border: "border-purple-500",
+    badge: "bg-purple-500",
+    ring: "ring-2 ring-purple-400/60 ring-offset-2",
+    shadow: "rgba(168, 85, 247, 0.15)",
+    glow: "linear-gradient(135deg, #a855f7, #7e22ce)",
+    pillBorder: "#a855f7",
+  },
+  orange: {
+    border: "border-orange-500",
+    badge: "bg-orange-500",
+    ring: "ring-2 ring-orange-400/60 ring-offset-2",
+    shadow: "rgba(251, 146, 60, 0.15)",
+    glow: "linear-gradient(135deg, #fb923c, #ea580c)",
+    pillBorder: "#fb923c",
+  },
+  pink: {
+    border: "border-pink-500",
+    badge: "bg-pink-500",
+    ring: "ring-2 ring-pink-400/60 ring-offset-2",
+    shadow: "rgba(236, 72, 153, 0.15)",
+    glow: "linear-gradient(135deg, #ec4899, #be185d)",
+    pillBorder: "#ec4899",
+  },
+  yellow: {
+    border: "border-yellow-500",
+    badge: "bg-yellow-500",
+    ring: "ring-2 ring-yellow-400/60 ring-offset-2",
+    shadow: "rgba(234, 179, 8, 0.15)",
+    glow: "linear-gradient(135deg, #eab308, #a16207)",
+    pillBorder: "#eab308",
+  },
+  gray: {
+    border: "border-gray-500",
+    badge: "bg-gray-500",
+    ring: "ring-2 ring-gray-400/60 ring-offset-2",
+    shadow: "rgba(107, 114, 128, 0.15)",
+    glow: "linear-gradient(135deg, #6b7280, #374151)",
+    pillBorder: "#6b7280",
+  },
+  indigo: {
+    border: "border-indigo-500",
+    badge: "bg-indigo-500",
+    ring: "ring-2 ring-indigo-400/60 ring-offset-2",
+    shadow: "rgba(99, 102, 241, 0.15)",
+    glow: "linear-gradient(135deg, #6366f1, #4338ca)",
+    pillBorder: "#6366f1",
+  },
+  cyan: {
+    border: "border-cyan-500",
+    badge: "bg-cyan-500",
+    ring: "ring-2 ring-cyan-400/60 ring-offset-2",
+    shadow: "rgba(6, 182, 212, 0.15)",
+    glow: "linear-gradient(135deg, #06b6d4, #0e7490)",
+    pillBorder: "#06b6d4",
+  },
+  slate: {
+    border: "border-slate-500",
+    badge: "bg-slate-500",
+    ring: "ring-2 ring-slate-400/60 ring-offset-2",
+    shadow: "rgba(100, 116, 139, 0.15)",
+    glow: "linear-gradient(135deg, #64748b, #334155)",
+    pillBorder: "#64748b",
+  },
+  amber: {
+    border: "border-amber-500",
+    badge: "bg-amber-500",
+    ring: "ring-2 ring-amber-400/60 ring-offset-2",
+    shadow: "rgba(245, 158, 11, 0.15)",
+    glow: "linear-gradient(135deg, #f59e0b, #b45309)",
+    pillBorder: "#f59e0b",
+  },
+  emerald: {
+    border: "border-emerald-500",
+    badge: "bg-emerald-500",
+    ring: "ring-2 ring-emerald-400/60 ring-offset-2",
+    shadow: "rgba(16, 185, 129, 0.15)",
+    glow: "linear-gradient(135deg, #10b981, #047857)",
+    pillBorder: "#10b981",
+  },
+  violet: {
+    border: "border-violet-500",
+    badge: "bg-violet-500",
+    ring: "ring-2 ring-violet-400/60 ring-offset-2",
+    shadow: "rgba(139, 92, 246, 0.15)",
+    glow: "linear-gradient(135deg, #8b5cf6, #6d28d9)",
+    pillBorder: "#8b5cf6",
+  },
+  rose: {
+    border: "border-rose-500",
+    badge: "bg-rose-500",
+    ring: "ring-2 ring-rose-400/60 ring-offset-2",
+    shadow: "rgba(244, 63, 94, 0.15)",
+    glow: "linear-gradient(135deg, #f43f5e, #be123c)",
+    pillBorder: "#f43f5e",
+  },
+};
+
+interface Data {
+  mode: "simple" | "full";
+  step: {
+    id: string;
+    title: string;
+    summary?: string;
+  };
+  custom: {
+    icon?: string;
+    type?: string;
+    title?: string;
+    summary?: string;
+    url?: string;
+    color?: string;
+    properties?: Record<string, string | number>;
+    menu?: MenuItem[];
+    height?: number;
+  };
+}
+
+function classNames(...classes: any[]) {
+  return classes.filter(Boolean).join(" ");
+}
+
+function getPalette(color: string | undefined) {
+  return PALETTES[(color as CustomColor) || "blue"] ?? PALETTES.blue;
+}
+
+function GlowHandle({
+  side,
+  gradient,
+}: {
+  side: "left" | "right";
+  gradient: string;
+}) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: gradient,
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: "ec-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none",
+      }}
+    />
+  );
+}
+
+export default memo(function CustomNode({ data, selected }: any) {
+  const { mode, custom: customProps, step } = data as Data;
+  const {
+    color = "blue",
+    title = step?.title || "Custom",
+    icon = "CubeIcon",
+    type = "Custom",
+    summary = step?.summary || "",
+    url,
+    properties = EMPTY_OBJECT,
+    menu = EMPTY_ARRAY,
+    height = 5,
+  } = customProps;
+
+  const palette = getPalette(color);
+  const IconComponent = useMemo<
+    ComponentType<{ className?: string }> | undefined
+  >(() => Icons[icon as keyof typeof Icons] || Icons.CubeIcon, [icon]);
+  const portalContainer = usePortalContainer();
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const propertyEntries = Object.entries(properties);
+  const contextMenuItems = url
+    ? [{ label: `Open ${type.toLowerCase()}`, url }, ...menu]
+    : menu;
+
+  return (
+    <ContextMenu.Root>
+      <ContextMenu.Trigger>
+        <div
+          className={classNames(
+            "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible",
+            selected ? palette.ring : "",
+            palette.border,
+          )}
+          style={{
+            background: "var(--ec-custom-node-bg, rgb(var(--ec-card-bg)))",
+            boxShadow: `0 2px 12px ${palette.shadow}`,
+            minHeight: mode === "full" ? `${height}em` : undefined,
+          }}
+        >
+          <Handle
+            type="target"
+            position={Position.Left}
+            style={HIDDEN_HANDLE_STYLE}
+          />
+          <Handle
+            type="source"
+            position={Position.Right}
+            style={HIDDEN_HANDLE_STYLE}
+          />
+          {targetConnections.length > 0 && (
+            <GlowHandle side="left" gradient={palette.glow} />
+          )}
+          {sourceConnections.length > 0 && (
+            <GlowHandle side="right" gradient={palette.glow} />
+          )}
+
+          <div className="absolute -top-3 left-2.5 z-10">
+            <span
+              className={classNames(
+                "inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm",
+                palette.badge,
+              )}
+            >
+              {IconComponent && (
+                <IconComponent className="w-2.5 h-2.5" aria-hidden />
+              )}
+              {type}
+            </span>
+          </div>
+
+          <div className="px-3 pt-3.5 pb-2.5">
+            <div className="flex items-center gap-2">
+              <TruncatedResourceName
+                value={title}
+                tooltipBorderColor={palette.pillBorder}
+                className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+              >
+                {title}
+              </TruncatedResourceName>
+            </div>
+
+            {mode === "full" && summary && (
+              <div
+                className="mt-1.5 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed overflow-hidden"
+                style={LINE_CLAMP_STYLE}
+                title={summary}
+              >
+                {summary}
+              </div>
+            )}
+
+            {mode === "full" && propertyEntries.length > 0 && (
+              <div className="mt-2 pt-1.5 border-t border-[rgb(var(--ec-page-border))] grid grid-cols-2 gap-x-2 gap-y-1">
+                {propertyEntries.map(([key, value]) => (
+                  <div key={key} className="min-w-0">
+                    <div className="text-[7px] font-bold uppercase tracking-wide text-[rgb(var(--ec-page-text-muted))] truncate">
+                      {key}
+                    </div>
+                    {typeof value === "string" && value.startsWith("http") ? (
+                      <a
+                        href={value}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="block text-[8px] text-blue-500 underline truncate"
+                        title={value}
+                      >
+                        {value}
+                      </a>
+                    ) : (
+                      <div
+                        className="text-[8px] text-[rgb(var(--ec-page-text))] truncate"
+                        title={String(value)}
+                      >
+                        {value}
+                      </div>
+                    )}
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+        </div>
+      </ContextMenu.Trigger>
+      {contextMenuItems.length > 0 && (
+        <ContextMenu.Portal container={portalContainer}>
+          <ContextMenu.Content className="min-w-[220px] bg-[rgb(var(--ec-card-bg))] rounded-md p-1 shadow-md border border-[rgb(var(--ec-page-border))]">
+            {contextMenuItems.map((item) => (
+              <ContextMenu.Item
+                asChild
+                key={`${item.label}-${item.url || ""}`}
+                className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
+              >
+                <a
+                  href={item.url}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-[rgb(var(--ec-page-text))] no-underline"
+                >
+                  {item.label}
+                </a>
+              </ContextMenu.Item>
+            ))}
+          </ContextMenu.Content>
+        </ContextMenu.Portal>
+      )}
+    </ContextMenu.Root>
+  );
+});
diff --git a/packages/visualiser/src/nodes/DataProduct.tsx b/packages/visualiser/src/nodes/DataProduct.tsx
new file mode 100644
index 000000000..17ad9d39c
--- /dev/null
+++ b/packages/visualiser/src/nodes/DataProduct.tsx
@@ -0,0 +1,307 @@
+import { memo } from "react";
+import { Package } from "lucide-react";
+import { Node, Handle, Position, useNodeConnections } from "@xyflow/react";
+import { EventCatalogResource } from "../types";
+import { NotesIndicator } from "./NotesIndicator";
+import { HIDDEN_HANDLE_STYLE } from "./OwnerIndicator";
+import {
+  LINE_CLAMP_STYLE,
+  FOLDED_CORNER_SHADOW_STYLE,
+  useDarkMode,
+} from "./shared-styles";
+import { CustomIcon, isIconPath } from "../utils/custom-icon";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+
+function GlowHandle({ side }: { side: "left" | "right" }) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: "linear-gradient(135deg, #6366f1, #4338ca)",
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: "ec-dp-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none",
+      }}
+    />
+  );
+}
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+type DataProductNodeData = EventCatalogResource & {
+  dataProduct: {
+    id: string;
+    version: string;
+    name: string;
+    summary?: string;
+    inputs?: any[];
+    outputs?: any[];
+    owners?: any[];
+    deprecated?: boolean;
+    draft?: boolean;
+    notes?: import("../types").Note[];
+    styles?: {
+      icon?: string;
+      node?: { color?: string; label?: string };
+    };
+  };
+};
+
+export type DataProductNode = Node<DataProductNodeData, "data-product">;
+
+function PostItDataProduct(props: DataProductNode) {
+  const { version, name, summary, deprecated, draft, notes, styles } =
+    props.data.dataProduct;
+  const mode = props.data.mode || "simple";
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-44 max-w-56 min-h-[120px]",
+        props?.selected ? "ring-2 ring-indigo-400/60 ring-offset-1" : "",
+      )}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {/* Inner wrapper with rotation */}
+      <div
+        className="absolute inset-0"
+        style={{
+          background:
+            "linear-gradient(135deg, #c7d2fe 0%, #a5b4fc 40%, #6366f1 100%)",
+          boxShadow:
+            "1px 1px 3px rgba(0,0,0,0.15), 3px 4px 8px rgba(0,0,0,0.08)",
+          transform: "rotate(1deg)",
+          border: deprecated
+            ? "2px dashed rgba(239, 68, 68, 0.5)"
+            : draft
+              ? "2px dashed rgba(99, 102, 241, 0.5)"
+              : "none",
+        }}
+      >
+        {/* Folded corner */}
+        <div style={FOLDED_CORNER_SHADOW_STYLE} />
+        <div
+          style={{
+            position: "absolute",
+            top: 0,
+            right: 0,
+            width: 0,
+            height: 0,
+            borderStyle: "solid",
+            borderWidth: "18px 0 0 18px",
+            borderColor: "#4338ca transparent transparent transparent",
+            opacity: 0.3,
+          }}
+        />
+      </div>
+
+      {/* Content sits on top, unrotated */}
+      <div className="relative px-3.5 py-3">
+        {/* Type label row */}
+        <div className="flex items-center justify-between mb-2">
+          <div className="flex items-center gap-1">
+            <Package className="w-3 h-3 text-indigo-900/50" strokeWidth={2.5} />
+            <span className="text-[8px] font-bold text-indigo-900/50 uppercase tracking-widest">
+              Data Product
+            </span>
+          </div>
+          {draft && (
+            <span className="text-[8px] font-extrabold text-amber-900 bg-amber-100 border border-dashed border-amber-400 px-1.5 py-0.5 rounded uppercase">
+              Draft
+            </span>
+          )}
+          {deprecated && (
+            <span className="text-[7px] font-bold text-white bg-red-500 border border-red-600 px-1.5 py-0.5 rounded uppercase">
+              Deprecated
+            </span>
+          )}
+        </div>
+
+        {/* Name */}
+        <div className="flex items-center gap-2">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className={
+                mode === "full"
+                  ? "w-[26px] h-[26px] shrink-0"
+                  : "w-4 h-4 shrink-0 -my-1"
+              }
+            />
+          )}
+          <TruncatedResourceName
+            as="div"
+            value={name}
+            tooltipBorderColor="#6366f1"
+            className={classNames(
+              "text-[13px] font-bold leading-snug min-w-0 truncate",
+              deprecated
+                ? "text-indigo-950/40 line-through"
+                : "text-indigo-950",
+            )}
+          >
+            {name}
+          </TruncatedResourceName>
+        </div>
+
+        {/* Version */}
+        {version && (
+          <div className="text-[9px] text-indigo-900/40 font-semibold mt-0.5">
+            v{version}
+          </div>
+        )}
+
+        {/* Summary */}
+        {mode === "full" && summary && (
+          <div
+            className="mt-2 pt-1.5 border-t border-indigo-900/10 text-[9px] text-indigo-950/60 leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function DefaultDataProduct(props: DataProductNode) {
+  const { version, name, summary, deprecated, draft, notes, styles } =
+    props.data.dataProduct;
+  const mode = props.data.mode || "simple";
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const isDark = useDarkMode();
+  const deprecatedStripe = isDark
+    ? "rgba(239,68,68,0.25)"
+    : "rgba(239,68,68,0.1)";
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible",
+        props?.selected ? "ring-2 ring-indigo-400/60 ring-offset-2" : "",
+        deprecated
+          ? "border-dashed border-red-500"
+          : draft
+            ? `border-dashed ${isDark ? "border-indigo-400" : "border-indigo-400/60"}`
+            : "border-indigo-500",
+      )}
+      style={{
+        background: deprecated
+          ? `repeating-linear-gradient(135deg, transparent, transparent 6px, ${deprecatedStripe} 6px, ${deprecatedStripe} 7px), var(--ec-dp-node-bg, rgb(var(--ec-card-bg)))`
+          : draft
+            ? `repeating-linear-gradient(135deg, transparent, transparent 4px, ${isDark ? "rgba(99,102,241,0.25)" : "rgba(99,102,241,0.15)"} 4px, ${isDark ? "rgba(99,102,241,0.25)" : "rgba(99,102,241,0.15)"} 4.5px), repeating-linear-gradient(45deg, transparent, transparent 4px, ${isDark ? "rgba(99,102,241,0.25)" : "rgba(99,102,241,0.15)"} 4px, ${isDark ? "rgba(99,102,241,0.25)" : "rgba(99,102,241,0.15)"} 4.5px), var(--ec-dp-node-bg, rgb(var(--ec-card-bg)))`
+            : "var(--ec-dp-node-bg, rgb(var(--ec-card-bg)))",
+        boxShadow: "0 2px 12px rgba(99, 102, 241, 0.15)",
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {targetConnections.length > 0 && <GlowHandle side="left" />}
+      {sourceConnections.length > 0 && <GlowHandle side="right" />}
+
+      {/* Badge positioned outside top-left corner */}
+      <div className="absolute -top-2.5 left-2.5 flex items-center gap-1.5 z-10">
+        <span
+          className={classNames(
+            "inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm",
+            deprecated ? "bg-red-500" : "bg-indigo-500",
+          )}
+        >
+          <Package className="w-2.5 h-2.5" strokeWidth={2.5} />
+          Data Product{draft && " (Draft)"}
+          {deprecated && " (Deprecated)"}
+        </span>
+      </div>
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        {/* Name + version */}
+        <div className="flex items-center gap-2">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className={
+                mode === "full"
+                  ? "w-[26px] h-[26px] shrink-0"
+                  : "w-4 h-4 shrink-0 -my-1"
+              }
+            />
+          )}
+          <div className="flex items-baseline gap-1 min-w-0">
+            <TruncatedResourceName
+              value={name}
+              tooltipBorderColor="#6366f1"
+              className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+            >
+              {name}
+            </TruncatedResourceName>
+            {version && (
+              <span className="text-[10px] font-normal text-[rgb(var(--ec-page-text-muted))] shrink-0">
+                (v{version})
+              </span>
+            )}
+          </div>
+        </div>
+
+        {/* Summary */}
+        {mode === "full" && summary && (
+          <div
+            className="mt-1.5 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default memo(function DataProductNode(props: DataProductNode) {
+  const nodeStyle = props?.data?.style;
+
+  if (nodeStyle === "post-it") {
+    return <PostItDataProduct {...props} />;
+  }
+
+  return <DefaultDataProduct {...props} />;
+});
diff --git a/packages/visualiser/src/nodes/Domain.tsx b/packages/visualiser/src/nodes/Domain.tsx
new file mode 100644
index 000000000..8f9268f20
--- /dev/null
+++ b/packages/visualiser/src/nodes/Domain.tsx
@@ -0,0 +1,206 @@
+import {
+  Handle,
+  useReactFlow,
+  useOnSelectionChange,
+  Position,
+} from "@xyflow/react";
+import * as ContextMenu from "@radix-ui/react-context-menu";
+import { usePortalContainer } from "../context/PortalContainerContext";
+import { buildUrl } from "../utils/url-builder";
+import { getIcon } from "../utils/badges";
+import { memo, useState, useCallback, useMemo } from "react";
+import { HANDLE_LEFT_STYLE, HANDLE_RIGHT_STYLE } from "./shared-styles";
+
+interface DomainData {
+  id: string;
+  version: string;
+  name: string;
+  services?: string[];
+  styles?: {
+    backgroundColor?: string;
+    borderColor?: string;
+    icon?: string;
+  };
+}
+
+interface Data {
+  mode: "simple" | "full";
+  domain: {
+    data: DomainData;
+  };
+}
+
+export default memo(function DomainNode({ data, id: nodeId }: any) {
+  const { mode, domain } = data as Data;
+  const reactFlow = useReactFlow();
+  const [highlightedServices, setHighlightedServices] = useState<Set<string>>(
+    new Set(),
+  );
+
+  const { id, version, name, services = [], styles } = domain.data;
+  const { icon = "RectangleGroupIcon" } = styles || {};
+
+  const Icon = useMemo(() => getIcon(icon), [icon]);
+  const ServerIcon = useMemo(() => getIcon("ServerIcon"), []);
+  const portalContainer = usePortalContainer();
+
+  // Listen for selection changes to highlight connected services
+  const handleSelectionChange = useCallback(
+    ({ nodes: selectedNodes }: { nodes: any[] }) => {
+      if (selectedNodes.length === 0) {
+        setHighlightedServices(new Set());
+        return;
+      }
+
+      const selectedNode = selectedNodes[0];
+      if (!selectedNode) {
+        setHighlightedServices(new Set());
+        return;
+      }
+
+      // Get all edges
+      const edges = reactFlow.getEdges();
+      const connectedServiceIds = new Set<string>();
+
+      // Find services connected to the selected node
+      edges.forEach((edge) => {
+        if (
+          edge.source === selectedNode.id ||
+          edge.target === selectedNode.id
+        ) {
+          // Check if this edge connects to our domain
+          if (edge.source === nodeId && edge.sourceHandle) {
+            // Extract service ID from sourceHandle (format: "serviceId-source")
+            const serviceId = edge.sourceHandle.replace("-source", "");
+            connectedServiceIds.add(serviceId);
+          }
+          if (edge.target === nodeId && edge.targetHandle) {
+            // Extract service ID from targetHandle (format: "serviceId-target")
+            const serviceId = edge.targetHandle.replace("-target", "");
+            connectedServiceIds.add(serviceId);
+          }
+        }
+      });
+
+      setHighlightedServices(connectedServiceIds);
+    },
+    [nodeId, reactFlow],
+  );
+
+  useOnSelectionChange({
+    onChange: handleSelectionChange,
+  });
+
+  return (
+    <ContextMenu.Root>
+      <ContextMenu.Trigger>
+        <div className="w-full rounded-lg border-2 border-yellow-400 bg-[rgb(var(--ec-card-bg))] shadow-lg">
+          <div className="bg-[rgb(var(--ec-domain-header-bg,253_224_71)/0.2)] px-3 py-2 flex items-center space-x-2">
+            {Icon && <Icon className="w-4 h-4 text-yellow-500" />}
+            <div>
+              <span className="text-sm font-bold text-[rgb(var(--ec-page-text))]">
+                {name}
+              </span>
+              <span className="text-xs text-yellow-500 ml-2">v{version}</span>
+            </div>
+          </div>
+          {mode === "full" && services.length > 0 && (
+            <div>
+              {services.map((service: any, index: number) => {
+                const isHighlighted = highlightedServices.has(service.data.id);
+
+                return (
+                  <ContextMenu.Root key={`${service.data.id}-${index}`}>
+                    <ContextMenu.Trigger asChild>
+                      <div
+                        className={`relative flex items-center justify-between px-3 py-2 cursor-pointer ${index !== services.length - 1 ? "border-b border-[rgb(var(--ec-page-border))]" : ""} ${isHighlighted ? "bg-pink-100 border-pink-300" : ""}`}
+                      >
+                        <Handle
+                          type="target"
+                          position={Position.Left}
+                          id={`${service.data.id}-target`}
+                          className="!left-[-1px] !w-2 !h-2 !bg-gray-400 !border !border-gray-500 !rounded-full !z-10"
+                          style={HANDLE_LEFT_STYLE}
+                        />
+                        <Handle
+                          type="source"
+                          position={Position.Right}
+                          id={`${service.data.id}-source`}
+                          className="!right-[-1px] !w-2 !h-2 !bg-gray-400 !border !border-gray-500 !rounded-full !z-10"
+                          style={HANDLE_RIGHT_STYLE}
+                        />
+                        <div className="flex items-center space-x-3">
+                          <div className="flex items-center justify-center w-5 h-5 bg-pink-500 rounded">
+                            {ServerIcon && (
+                              <ServerIcon className="w-3 h-3 text-white" />
+                            )}
+                          </div>
+                          <span className="text-sm font-medium text-[rgb(var(--ec-page-text))]">
+                            {service.data.name || service.data.id}
+                          </span>
+                        </div>
+                        <div className="flex items-center space-x-4 text-sm text-[rgb(var(--ec-page-text-muted))]">
+                          <span className="text-xs">
+                            v{service.data.version}
+                          </span>
+                        </div>
+                      </div>
+                    </ContextMenu.Trigger>
+                    <ContextMenu.Portal container={portalContainer}>
+                      <ContextMenu.Content className="min-w-[220px] bg-[rgb(var(--ec-card-bg))] rounded-md p-1 shadow-md border border-[rgb(var(--ec-page-border))]">
+                        <ContextMenu.Item
+                          className="text-sm text-[rgb(var(--ec-page-text))] px-2 py-1.5 outline-none cursor-pointer hover:bg-[rgb(var(--ec-page-border)/0.5)] rounded-sm flex items-center"
+                          onClick={() =>
+                            (window.location.href = buildUrl(
+                              `/docs/services/${service.data.id}/${service.data.version}`,
+                            ))
+                          }
+                        >
+                          View Service Documentation
+                        </ContextMenu.Item>
+                        <ContextMenu.Item
+                          className="text-sm text-[rgb(var(--ec-page-text))] px-2 py-1.5 outline-none cursor-pointer hover:bg-[rgb(var(--ec-page-border)/0.5)] rounded-sm flex items-center"
+                          onClick={() =>
+                            (window.location.href = buildUrl(
+                              `/visualiser/services/${service.data.id}/${service.data.version}`,
+                            ))
+                          }
+                        >
+                          View Service Visualizer
+                        </ContextMenu.Item>
+                      </ContextMenu.Content>
+                    </ContextMenu.Portal>
+                  </ContextMenu.Root>
+                );
+              })}
+            </div>
+          )}
+        </div>
+      </ContextMenu.Trigger>
+      <ContextMenu.Portal container={portalContainer}>
+        <ContextMenu.Content className="min-w-[220px] bg-[rgb(var(--ec-card-bg))] rounded-md p-1 shadow-md border border-[rgb(var(--ec-page-border))]">
+          <ContextMenu.Item
+            className="text-sm text-[rgb(var(--ec-page-text))] px-2 py-1.5 outline-none cursor-pointer hover:bg-[rgb(var(--ec-page-border)/0.5)] rounded-sm flex items-center"
+            onClick={() =>
+              (window.location.href = buildUrl(
+                `/docs/domains/${id}/${version}`,
+              ))
+            }
+          >
+            View Domain Documentation
+          </ContextMenu.Item>
+          <ContextMenu.Item
+            className="text-sm text-[rgb(var(--ec-page-text))] px-2 py-1.5 outline-none cursor-pointer hover:bg-[rgb(var(--ec-page-border)/0.5)] rounded-sm flex items-center"
+            onClick={() =>
+              (window.location.href = buildUrl(
+                `/visualiser/domains/${id}/${version}`,
+              ))
+            }
+          >
+            View Domain Visualizer
+          </ContextMenu.Item>
+        </ContextMenu.Content>
+      </ContextMenu.Portal>
+    </ContextMenu.Root>
+  );
+});
diff --git a/packages/visualiser/src/nodes/Entity.test.ts b/packages/visualiser/src/nodes/Entity.test.ts
new file mode 100644
index 000000000..ca74a6b31
--- /dev/null
+++ b/packages/visualiser/src/nodes/Entity.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { getPropertyTypeLabel } from "./Entity";
+
+describe("getPropertyTypeLabel", () => {
+  it("shows the item type for array properties", () => {
+    expect(
+      getPropertyTypeLabel({
+        type: "array",
+        items: {
+          type: "Address",
+        },
+      }),
+    ).toBe("Address[]");
+  });
+
+  it("falls back to the property type for scalar properties", () => {
+    expect(getPropertyTypeLabel({ type: "string" })).toBe("string");
+  });
+});
diff --git a/packages/visualiser/src/nodes/Entity.tsx b/packages/visualiser/src/nodes/Entity.tsx
new file mode 100644
index 000000000..c9894534c
--- /dev/null
+++ b/packages/visualiser/src/nodes/Entity.tsx
@@ -0,0 +1,244 @@
+import { Handle, Position } from "@xyflow/react";
+import { getIcon } from "../utils/badges";
+import * as ContextMenu from "@radix-ui/react-context-menu";
+import { buildUrl } from "../utils/url-builder";
+import { memo, useState, useMemo } from "react";
+import { usePortalContainer } from "../context/PortalContainerContext";
+import {
+  HANDLE_LEFT_OFFSET_STYLE,
+  HANDLE_RIGHT_OFFSET_STYLE,
+  EMPTY_ARRAY,
+} from "./shared-styles";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+
+interface EntityData {
+  id: string;
+  name: string;
+  version: string;
+  properties?: any[];
+  aggregateRoot?: boolean;
+  sidebar?: any;
+  styles?: {
+    backgroundColor?: string;
+    borderColor?: string;
+    icon?: string;
+    node?: {
+      color?: string;
+      label?: string;
+    };
+  };
+}
+
+interface Data {
+  title: string;
+  label: string;
+  bgColor: string;
+  color: string;
+  mode: "simple" | "full";
+  entity: {
+    data: EntityData;
+  };
+  showTarget?: boolean;
+  showSource?: boolean;
+  externalToDomain?: boolean;
+  domainName?: string;
+  domainId?: string;
+  group?: {
+    type: string;
+    value: string;
+  };
+}
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+export const getPropertyTypeLabel = (property: any) => {
+  if (property.type === "array" && property.items?.type) {
+    return `${property.items.type}[]`;
+  }
+
+  return property.type;
+};
+
+export default memo(function EntityNode({
+  data,
+  sourcePosition,
+  targetPosition,
+}: any) {
+  const { mode, entity, externalToDomain, domainName } = data as Data;
+  const {
+    name,
+    version,
+    properties = EMPTY_ARRAY,
+    aggregateRoot,
+    styles,
+    sidebar: _sidebar,
+  } = entity.data;
+
+  const {
+    node: { color: _color = "blue", label: _label } = {},
+    icon = "CubeIcon",
+  } = styles || {};
+
+  const Icon = useMemo(() => getIcon(icon), [icon]);
+
+  const [hoveredProperty, setHoveredProperty] = useState<string | null>(null);
+  const portalContainer = usePortalContainer();
+
+  return (
+    <ContextMenu.Root>
+      <ContextMenu.Trigger>
+        <div
+          className={classNames(
+            "bg-[rgb(var(--ec-card-bg))] border rounded-lg shadow-sm min-w-[200px]",
+            externalToDomain ? "border-amber-500/60" : "border-blue-400/50",
+          )}
+        >
+          {/* Table Header */}
+          <div
+            className={classNames(
+              "px-4 py-2 rounded-t-lg border-b border-[rgb(var(--ec-page-border))]",
+              externalToDomain ? "bg-amber-500/20" : "bg-blue-500/15",
+            )}
+          >
+            <div className="flex items-center gap-2 min-w-0">
+              {Icon && (
+                <Icon className="w-4 h-4 text-[rgb(var(--ec-page-text-muted))]" />
+              )}
+              <TruncatedResourceName
+                value={name}
+                tooltipBorderColor={externalToDomain ? "#f59e0b" : "#60a5fa"}
+                className="font-semibold text-[rgb(var(--ec-page-text))] text-sm truncate"
+              >
+                {name}
+              </TruncatedResourceName>
+              {aggregateRoot && (
+                <span className="text-xs bg-amber-500/20 text-amber-600 dark:text-amber-400 px-1.5 py-0.5 rounded font-medium shrink-0">
+                  AR
+                </span>
+              )}
+            </div>
+            {domainName && (
+              <div className="text-xs text-[rgb(var(--ec-page-text-muted))] font-medium mt-1">
+                from {domainName} domain
+              </div>
+            )}
+            {mode === "full" && (
+              <div className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-1">
+                v{version}
+              </div>
+            )}
+          </div>
+
+          {/* Properties Table */}
+          {properties.length > 0 ? (
+            <div className="divide-y divide-[rgb(var(--ec-page-border))] relative">
+              {properties.map((property: any, index: number) => {
+                const propertyKey = `${property.name}-${index}`;
+                const isHovered = hoveredProperty === propertyKey;
+                return (
+                  <div
+                    key={propertyKey}
+                    className="relative flex items-center justify-between px-4 py-2 hover:bg-[rgb(var(--ec-page-border)/0.2)]"
+                    onMouseEnter={() =>
+                      property.description && setHoveredProperty(propertyKey)
+                    }
+                    onMouseLeave={() => setHoveredProperty(null)}
+                  >
+                    {/* Target handle */}
+                    <Handle
+                      type="target"
+                      position={Position.Left}
+                      id={`${property.name}-target`}
+                      className="!w-3 !h-3 !bg-[rgb(var(--ec-card-bg))] !border-2 !border-[rgb(var(--ec-page-border))] !rounded-full !left-[-0px]"
+                      style={HANDLE_LEFT_OFFSET_STYLE}
+                    />
+
+                    {/* Source handle */}
+                    <Handle
+                      type="source"
+                      position={Position.Right}
+                      id={`${property.name}-source`}
+                      className="!w-3 !h-3 !bg-[rgb(var(--ec-card-bg))] !border-2 !border-[rgb(var(--ec-page-border))] !rounded-full !right-[-0px]"
+                      style={HANDLE_RIGHT_OFFSET_STYLE}
+                    />
+
+                    {/* Property content */}
+                    <div className="flex-1 flex items-center justify-between">
+                      <div className="flex items-center gap-1">
+                        <span className="text-sm font-medium text-[rgb(var(--ec-page-text))]">
+                          {property.name}
+                        </span>
+                        {property.required && (
+                          <span className="text-red-500 text-xs">*</span>
+                        )}
+                      </div>
+                      <span className="text-sm text-[rgb(var(--ec-page-text-muted))] font-mono">
+                        {getPropertyTypeLabel(property)}
+                      </span>
+                    </div>
+
+                    {/* Reference indicator */}
+                    {(property.references ||
+                      (property.type === "array" && property.items?.type)) && (
+                      <div className="absolute right-2 top-1/2 transform -translate-y-1/2">
+                        <div
+                          className="w-2 h-2 bg-blue-500 rounded-full"
+                          title={`References ${
+                            property.references || property.items.type
+                          }`}
+                        ></div>
+                      </div>
+                    )}
+
+                    {/* Property Tooltip */}
+                    {isHovered && property.description && (
+                      <div className="absolute left-full ml-2 top-1/2 transform -translate-y-1/2 z-[9999] w-[200px] bg-gray-900 text-white text-xs rounded-lg py-2 px-3 pointer-events-none shadow-xl max-w-xl opacity-100">
+                        <div className="text-gray-200 whitespace-normal break-words">
+                          {property.description}
+                        </div>
+                        <div className="absolute right-full top-1/2 transform -translate-y-1/2 border-4 border-transparent border-r-gray-900"></div>
+                      </div>
+                    )}
+                  </div>
+                );
+              })}
+            </div>
+          ) : (
+            <div className="px-4 py-3 text-sm text-[rgb(var(--ec-page-text-muted))] text-center">
+              No properties defined
+            </div>
+          )}
+
+          {/* Main node handles (if no properties) */}
+          {properties.length === 0 && (
+            <>
+              {targetPosition && (
+                <Handle type="target" position={targetPosition} />
+              )}
+              {sourcePosition && (
+                <Handle type="source" position={sourcePosition} />
+              )}
+            </>
+          )}
+        </div>
+      </ContextMenu.Trigger>
+      <ContextMenu.Portal container={portalContainer}>
+        <ContextMenu.Content
+          className="min-w-[220px] bg-[rgb(var(--ec-card-bg))] rounded-md p-1 shadow-md border border-[rgb(var(--ec-page-border))]"
+          onClick={(e) => e.stopPropagation()}
+        >
+          <ContextMenu.Item
+            asChild
+            className="text-sm text-[rgb(var(--ec-page-text))] px-2 py-1.5 outline-none cursor-pointer hover:bg-[rgb(var(--ec-accent-subtle))] rounded-sm flex items-center"
+          >
+            <a href={buildUrl(`/docs/entities/${entity.data.id}/${version}`)}>
+              Read documentation
+            </a>
+          </ContextMenu.Item>
+        </ContextMenu.Content>
+      </ContextMenu.Portal>
+    </ContextMenu.Root>
+  );
+});
diff --git a/packages/visualiser/src/nodes/ExternalSystem2.tsx b/packages/visualiser/src/nodes/ExternalSystem2.tsx
new file mode 100644
index 000000000..846d9df66
--- /dev/null
+++ b/packages/visualiser/src/nodes/ExternalSystem2.tsx
@@ -0,0 +1,24 @@
+import { memo } from "react";
+import { Handle, Position } from "@xyflow/react";
+import ExternalSystemComponent from "./external-system/ExternalSystem";
+import { EXTERNAL_SYSTEM_HANDLE_STYLE } from "./shared-styles";
+
+export default memo(function ExternalSystemNode(props: any) {
+  return (
+    <div className="relative">
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={EXTERNAL_SYSTEM_HANDLE_STYLE}
+        className="bg-gray-500"
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={EXTERNAL_SYSTEM_HANDLE_STYLE}
+        className="bg-gray-500"
+      />
+      <ExternalSystemComponent {...props} />
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/Flow.tsx b/packages/visualiser/src/nodes/Flow.tsx
new file mode 100644
index 000000000..01b0e587c
--- /dev/null
+++ b/packages/visualiser/src/nodes/Flow.tsx
@@ -0,0 +1,206 @@
+import { memo, useMemo } from "react";
+import { Handle } from "@xyflow/react";
+import { Maximize2 } from "lucide-react";
+import * as ContextMenu from "@radix-ui/react-context-menu";
+import { usePortalContainer } from "../context/PortalContainerContext";
+import { buildUrl } from "../utils/url-builder";
+import { getIcon } from "../utils/badges";
+import {
+  NODE_WIDTH_STYLE,
+  ROTATED_LABEL_STYLE,
+  TINY_FONT_STYLE,
+  EMPTY_ARRAY,
+} from "./shared-styles";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+
+interface FlowData {
+  id: string;
+  version: string;
+  name: string;
+  summary?: string;
+  owners?: string[];
+  sidebar?: {
+    badge?: string;
+  };
+  styles?: {
+    backgroundColor?: string;
+    borderColor?: string;
+    icon?: string;
+    node?: {
+      color?: string;
+      label?: string;
+    };
+  };
+}
+
+interface Data {
+  label: string;
+  bgColor: string;
+  color: string;
+  mode: "simple" | "full";
+  flow: {
+    data: FlowData;
+  };
+  showTarget?: boolean;
+  showSource?: boolean;
+}
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+export default memo(function FlowNode({
+  data,
+  sourcePosition,
+  targetPosition,
+}: any) {
+  const { mode, flow } = data as Data;
+  const canExpand =
+    Array.isArray((data as any)?.expandedNodes) &&
+    (data as any).expandedNodes.length > 0;
+
+  const { id, version, owners = EMPTY_ARRAY, name, styles } = flow.data;
+  const { node: { color = "teal", label } = {}, icon = "QueueListIcon" } =
+    styles || {};
+
+  const Icon = useMemo(() => getIcon(icon), [icon]);
+  const portalContainer = usePortalContainer();
+  const nodeLabel = label || flow?.data?.sidebar?.badge || "Flow";
+  const fontSize = nodeLabel.length > 10 ? "7px" : "9px";
+
+  return (
+    <ContextMenu.Root>
+      <ContextMenu.Trigger>
+        <div
+          className="relative"
+          style={{ isolation: "isolate", ...NODE_WIDTH_STYLE }}
+        >
+          {/* Stacked shadow layers behind the card signal a sub-flow the user can expand. */}
+          {canExpand && (
+            <>
+              <div
+                className={`absolute inset-0 rounded-md border border-${color}-400 bg-[rgb(var(--ec-card-bg))]`}
+                style={{ transform: "translate(6px, 6px)", opacity: 0.5 }}
+                aria-hidden
+              />
+              <div
+                className={`absolute inset-0 rounded-md border border-${color}-400 bg-[rgb(var(--ec-card-bg))]`}
+                style={{ transform: "translate(3px, 3px)", opacity: 0.7 }}
+                aria-hidden
+              />
+            </>
+          )}
+          <div
+            className={classNames(
+              `relative rounded-md border flex justify-start bg-[rgb(var(--ec-card-bg))] text-[rgb(var(--ec-page-text))] border-${color}-400`,
+            )}
+            style={NODE_WIDTH_STYLE}
+          >
+            <div
+              className={classNames(
+                `bg-gradient-to-b from-${color}-500 to-${color}-700 relative flex flex-col items-center w-5 justify-between rounded-l-sm text-${color}-100`,
+                `border-r-[1px] border-${color}-500`,
+              )}
+            >
+              {Icon && <Icon className="w-4 h-4 opacity-90 text-white mt-1" />}
+              {mode === "full" && (
+                <span
+                  className={`text-center text-[${fontSize}] text-white font-bold uppercase mb-4`}
+                  style={ROTATED_LABEL_STYLE}
+                >
+                  {nodeLabel}
+                </span>
+              )}
+            </div>
+            <div className="p-1 flex-1 min-w-0">
+              {targetPosition && (
+                <Handle type="target" position={targetPosition} />
+              )}
+              {sourcePosition && (
+                <Handle type="source" position={sourcePosition} />
+              )}
+              <div
+                className={classNames(
+                  mode === "full"
+                    ? `border-b border-[rgb(var(--ec-page-border))]`
+                    : "",
+                )}
+              >
+                <TruncatedResourceName
+                  as="div"
+                  value={name}
+                  tooltipBorderColor="#14b8a6"
+                  className="text-xs font-bold truncate pt-0.5 pb-0.5"
+                >
+                  {name}
+                </TruncatedResourceName>
+                <div className="flex justify-between">
+                  <span className="text-[10px] font-light block pt-0.5 pb-0.5 ">
+                    v{version}
+                  </span>
+                  {mode === "simple" && (
+                    <span className="text-[10px] text-[rgb(var(--ec-page-text-muted))] font-light block pt-0.5 pb-0.5 ">
+                      {nodeLabel}
+                    </span>
+                  )}
+                </div>
+              </div>
+              {mode === "full" && (
+                <div className="divide-y divide-[rgb(var(--ec-page-border))] ">
+                  <div className="leading-3 py-1">
+                    <span className="text-[8px] font-light">
+                      {flow.data.summary}
+                    </span>
+                  </div>
+
+                  <div className="grid grid-cols-2 gap-x-4 py-1">
+                    <span className="text-xs" style={TINY_FONT_STYLE}>
+                      Owners: {owners.length}
+                    </span>
+                  </div>
+                </div>
+              )}
+              {canExpand && (
+                <div className="mt-1 flex items-center gap-1 text-[8px] text-[rgb(var(--ec-page-text-muted))]">
+                  <Maximize2 className="w-2.5 h-2.5" />
+                  Click to explore
+                </div>
+              )}
+            </div>
+          </div>
+        </div>
+      </ContextMenu.Trigger>
+      <ContextMenu.Portal container={portalContainer}>
+        <ContextMenu.Content className="min-w-[220px] bg-[rgb(var(--ec-card-bg))] rounded-md p-1 shadow-md border border-[rgb(var(--ec-page-border))]">
+          <ContextMenu.Item
+            asChild
+            className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
+          >
+            <a href={buildUrl(`/docs/flows/${id}/${version}`)}>
+              Read documentation
+            </a>
+          </ContextMenu.Item>
+          <ContextMenu.Item
+            asChild
+            className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
+          >
+            <a href={buildUrl(`/visualiser/flows/${id}/${version}`)}>
+              View in visualiser
+            </a>
+          </ContextMenu.Item>
+          <ContextMenu.Separator className="h-[1px] bg-[rgb(var(--ec-page-border))] m-1" />
+          <ContextMenu.Item asChild>
+            <a
+              href={buildUrl(`/docs/flows/${id}/${version}/changelog`)}
+              className="text-sm px-2 py-1.5 outline-none cursor-pointer hover:bg-orange-100 rounded-sm flex items-center"
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              Read changelog
+            </a>
+          </ContextMenu.Item>
+        </ContextMenu.Content>
+      </ContextMenu.Portal>
+    </ContextMenu.Root>
+  );
+});
diff --git a/packages/visualiser/src/nodes/FlowExpandedNode.tsx b/packages/visualiser/src/nodes/FlowExpandedNode.tsx
new file mode 100644
index 000000000..6dbac5264
--- /dev/null
+++ b/packages/visualiser/src/nodes/FlowExpandedNode.tsx
@@ -0,0 +1,143 @@
+import { memo } from "react";
+import { Workflow, Minimize2 } from "lucide-react";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+
+export type FlowExpandedNodeData = {
+  flowName?: string;
+  version?: string;
+};
+
+// Container body keeps a visible teal tint that works in both themes — the
+// teal is the sub-flow identity, while theme-aware variables handle text
+// and header colour. The header uses the card-bg variable so it blends
+// naturally over the dotted background in light and dark modes.
+const CONTAINER_STYLE: React.CSSProperties = {
+  width: "100%",
+  height: "100%",
+  borderRadius: 12,
+  border: "2px solid rgba(20, 184, 166, 0.5)",
+  backgroundColor: "rgba(20, 184, 166, 0.08)",
+  boxShadow: "0 2px 12px rgba(20, 184, 166, 0.12)",
+  position: "relative",
+  overflow: "visible",
+};
+
+const HEADER_STYLE: React.CSSProperties = {
+  position: "absolute",
+  top: 0,
+  left: 0,
+  right: 0,
+  height: 44,
+  borderTopLeftRadius: 10,
+  borderTopRightRadius: 10,
+  background: "rgba(20, 184, 166, 0.12)",
+  borderBottom: "1px solid rgba(20, 184, 166, 0.3)",
+  overflow: "visible",
+};
+
+const BADGE_STYLE: React.CSSProperties = {
+  position: "absolute",
+  top: -10,
+  left: 12,
+  display: "inline-flex",
+  alignItems: "center",
+  gap: 3,
+  padding: "2px 8px",
+  borderRadius: 4,
+  background: "#0d9488",
+  boxShadow: "0 1px 3px rgba(0,0,0,0.15)",
+  zIndex: 10,
+  fontSize: 8,
+  fontWeight: 700,
+  letterSpacing: "0.08em",
+  textTransform: "uppercase" as const,
+  color: "white",
+};
+
+const HEADER_CONTENT_STYLE: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  height: "100%",
+  padding: "0 12px 0 14px",
+  gap: 12,
+};
+
+const FLOW_NAME_STYLE: React.CSSProperties = {
+  fontSize: 11,
+  fontWeight: 700,
+  color: "rgb(var(--ec-page-text))",
+  letterSpacing: "0.04em",
+  textTransform: "uppercase",
+  whiteSpace: "nowrap",
+};
+
+const VERSION_STYLE: React.CSSProperties = {
+  fontSize: 10,
+  fontWeight: 500,
+  color: "#5eead4",
+  marginLeft: 8,
+};
+
+const COLLAPSE_BUTTON_STYLE: React.CSSProperties = {
+  background: "#0d9488",
+  border: "1px solid #5eead4",
+  borderRadius: 6,
+  padding: "4px 10px",
+  cursor: "pointer",
+  display: "flex",
+  alignItems: "center",
+  gap: 4,
+  fontSize: 10,
+  fontWeight: 600,
+  color: "white",
+};
+
+export default memo(function FlowExpandedNode({
+  data,
+}: {
+  data: FlowExpandedNodeData;
+}) {
+  const { flowName, version } = data;
+
+  return (
+    <div style={CONTAINER_STYLE}>
+      <div style={HEADER_STYLE}>
+        <div style={BADGE_STYLE}>
+          <Workflow size={10} strokeWidth={2.5} />
+          Sub-flow
+        </div>
+
+        <div style={HEADER_CONTENT_STYLE}>
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              minWidth: 0,
+              flex: 1,
+            }}
+          >
+            <TruncatedResourceName
+              value={flowName || "Flow"}
+              tooltipBorderColor="#14b8a6"
+              className="truncate"
+              style={FLOW_NAME_STYLE}
+            >
+              {flowName || "Flow"}
+            </TruncatedResourceName>
+            {version && <span style={VERSION_STYLE}>v{version}</span>}
+          </div>
+
+          <button
+            style={COLLAPSE_BUTTON_STYLE}
+            className="ec-collapse-flow-btn nodrag nopan"
+            onMouseDown={(e) => e.stopPropagation()}
+          >
+            <Minimize2 size={12} strokeWidth={2.5} />
+            Collapse
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/GroupNode.tsx b/packages/visualiser/src/nodes/GroupNode.tsx
new file mode 100644
index 000000000..b14e6e991
--- /dev/null
+++ b/packages/visualiser/src/nodes/GroupNode.tsx
@@ -0,0 +1,137 @@
+import { memo } from "react";
+import type { NodeProps } from "@xyflow/react";
+import { BoxesIcon } from "lucide-react";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+
+export type GroupNodeData = {
+  mode: string;
+  domain: {
+    name: string;
+    version: string;
+    summary: string;
+  };
+};
+
+const GROUP_CONTAINER_STYLE = {
+  width: "100%",
+  height: "100%",
+  borderRadius: 12,
+  border: "2px solid var(--ec-group-border, #c4b5fd)",
+  backgroundColor: "var(--ec-group-bg, rgba(250, 248, 255, 0.35))",
+  position: "relative" as const,
+  overflow: "visible" as const,
+} as const;
+
+const GROUP_HEADER_STYLE = {
+  position: "absolute" as const,
+  top: 0,
+  left: 0,
+  right: 0,
+  height: 44,
+  borderTopLeftRadius: 10,
+  borderTopRightRadius: 10,
+  background: "var(--ec-group-header-bg, rgba(237, 233, 254, 0.7))",
+  borderBottom: "1px solid var(--ec-group-border, #c4b5fd)",
+  overflow: "visible" as const,
+} as const;
+
+const GROUP_WATERMARK_STYLE = {
+  position: "absolute" as const,
+  top: 6,
+  right: 10,
+  opacity: 0.12,
+  transform: "rotate(12deg)",
+  pointerEvents: "none" as const,
+} as const;
+
+const GROUP_ICON_CIRCLE_STYLE = {
+  position: "absolute" as const,
+  top: -14,
+  left: 12,
+  width: 32,
+  height: 32,
+  borderRadius: "50%",
+  background: "#7c3aed",
+  border: "2px solid #a78bfa",
+  display: "flex",
+  alignItems: "center" as const,
+  justifyContent: "center" as const,
+  boxShadow: "0 1px 3px rgba(0,0,0,0.1)",
+  zIndex: 10,
+} as const;
+
+const GROUP_BANNER_CONTENT_STYLE = {
+  display: "flex",
+  alignItems: "center" as const,
+  justifyContent: "center" as const,
+  height: "100%",
+  padding: "0 40px",
+  minWidth: 0,
+} as const;
+
+const GROUP_BANNER_INNER_STYLE = {
+  display: "flex",
+  alignItems: "center" as const,
+  gap: 8,
+  minWidth: 0,
+} as const;
+
+const GROUP_DOMAIN_NAME_STYLE = {
+  fontSize: 15,
+  fontWeight: 800,
+  color: "var(--ec-group-text, #5b21b6)",
+  letterSpacing: "0.06em",
+  textTransform: "uppercase" as const,
+  whiteSpace: "nowrap" as const,
+} as const;
+
+const GROUP_VERSION_STYLE = {
+  fontSize: 9,
+  fontWeight: 500,
+  color: "#a78bfa",
+} as const;
+
+const GROUP_ICON_COLOR_STYLE = { color: "#7c3aed" } as const;
+const GROUP_ICON_WHITE_STYLE = { color: "white" } as const;
+
+export default memo(function GroupNode({ data }: NodeProps) {
+  const { domain } = data as unknown as GroupNodeData;
+
+  return (
+    <div style={GROUP_CONTAINER_STYLE}>
+      {/* Header banner */}
+      <div style={GROUP_HEADER_STYLE}>
+        {/* Watermark icon in banner */}
+        <div style={GROUP_WATERMARK_STYLE}>
+          <BoxesIcon size={28} strokeWidth={2} style={GROUP_ICON_COLOR_STYLE} />
+        </div>
+
+        {/* Icon circle overlapping top of banner */}
+        <div style={GROUP_ICON_CIRCLE_STYLE}>
+          <BoxesIcon
+            size={16}
+            strokeWidth={2.5}
+            style={GROUP_ICON_WHITE_STYLE}
+          />
+        </div>
+
+        {/* Banner text content */}
+        <div style={GROUP_BANNER_CONTENT_STYLE}>
+          <div style={GROUP_BANNER_INNER_STYLE}>
+            <TruncatedResourceName
+              value={domain?.name || "Domain"}
+              tooltipBorderColor="#7c3aed"
+              className="truncate"
+              style={GROUP_DOMAIN_NAME_STYLE}
+            >
+              {domain?.name || "Domain"}
+            </TruncatedResourceName>
+            {domain?.version && (
+              <span style={GROUP_VERSION_STYLE}>v{domain.version}</span>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/NotesIndicator.tsx b/packages/visualiser/src/nodes/NotesIndicator.tsx
new file mode 100644
index 000000000..e6d1d28c4
--- /dev/null
+++ b/packages/visualiser/src/nodes/NotesIndicator.tsx
@@ -0,0 +1,751 @@
+import { MessageCircle, AlertTriangle, XIcon } from "lucide-react";
+import { useState, useCallback, memo } from "react";
+import * as Dialog from "@radix-ui/react-dialog";
+import { usePortalContainer } from "../context/PortalContainerContext";
+import type { Note } from "../types";
+import { useDarkMode } from "./shared-styles";
+
+/* ------------------------------------------------------------------ */
+/*  Constants                                                          */
+/* ------------------------------------------------------------------ */
+
+const AMBER = {
+  50: "#fffbeb",
+  100: "#fef3c7",
+  200: "#fde68a",
+  400: "#fbbf24",
+  500: "#f59e0b",
+  600: "#d97706",
+  700: "#b45309",
+  800: "#92400e",
+  900: "#78350f",
+} as const;
+
+const PRIORITY: Record<
+  string,
+  { bg: string; fg: string; border: string; label: string; accent: string }
+> = {
+  high: {
+    bg: "#fef2f2",
+    fg: "#b91c1c",
+    border: "#fecaca",
+    label: "High",
+    accent: "#ef4444",
+  },
+  critical: {
+    bg: "#fef2f2",
+    fg: "#991b1b",
+    border: "#fecaca",
+    label: "Critical",
+    accent: "#dc2626",
+  },
+  low: {
+    bg: "#f0fdf4",
+    fg: "#15803d",
+    border: "#bbf7d0",
+    label: "Low",
+    accent: "#22c55e",
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/*  Deterministic avatar color from name                               */
+/* ------------------------------------------------------------------ */
+
+const AVATAR_PALETTES = [
+  ["#7c3aed", "#a78bfa"], // violet
+  ["#2563eb", "#60a5fa"], // blue
+  ["#0891b2", "#22d3ee"], // cyan
+  ["#059669", "#34d399"], // emerald
+  ["#d97706", "#fbbf24"], // amber
+  ["#dc2626", "#f87171"], // red
+  ["#db2777", "#f472b6"], // pink
+  ["#4f46e5", "#818cf8"], // indigo
+];
+
+function hashStr(s: string): number {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) {
+    h = (h * 31 + s.charCodeAt(i)) | 0;
+  }
+  return Math.abs(h);
+}
+
+/* ------------------------------------------------------------------ */
+/*  Shared atoms                                                       */
+/* ------------------------------------------------------------------ */
+
+function Avatar({ name, size = 18 }: { name: string; size?: number }) {
+  const initials = name
+    .split(/\s+/)
+    .map((w) => w[0])
+    .join("")
+    .toUpperCase()
+    .slice(0, 2);
+
+  const [c1, c2] = AVATAR_PALETTES[hashStr(name) % AVATAR_PALETTES.length];
+
+  return (
+    <div
+      style={{
+        width: size,
+        height: size,
+        borderRadius: "50%",
+        background: `linear-gradient(135deg, ${c1}, ${c2})`,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        flexShrink: 0,
+      }}
+    >
+      <span
+        style={{
+          fontSize: Math.round(size * 0.42),
+          fontWeight: 700,
+          color: "white",
+          lineHeight: 1,
+          letterSpacing: "-0.02em",
+        }}
+      >
+        {initials}
+      </span>
+    </div>
+  );
+}
+
+function PriorityPill({
+  priority,
+  size = "sm",
+}: {
+  priority: string;
+  size?: "sm" | "md";
+}) {
+  const p = PRIORITY[priority.toLowerCase()];
+  if (!p) return null;
+  const isUrgent = priority === "high" || priority === "critical";
+  const md = size === "md";
+
+  return (
+    <span
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: md ? 4 : 2,
+        fontSize: md ? 11 : 8,
+        fontWeight: 700,
+        color: p.fg,
+        background: p.bg,
+        border: `1px solid ${p.border}`,
+        borderRadius: 99,
+        padding: md ? "2px 8px" : "1px 5px",
+        textTransform: "uppercase",
+        letterSpacing: "0.04em",
+        lineHeight: 1.4,
+        whiteSpace: "nowrap",
+      }}
+    >
+      {isUrgent && (
+        <AlertTriangle
+          style={{ width: md ? 10 : 7, height: md ? 10 : 7 }}
+          strokeWidth={2.5}
+        />
+      )}
+      {p.label}
+    </span>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Popover (hover preview)                                            */
+/* ------------------------------------------------------------------ */
+
+function PopoverCard({ note, last }: { note: Note; last: boolean }) {
+  return (
+    <div
+      style={{
+        padding: "7px 10px",
+        borderBottom: last ? "none" : "1px solid rgb(var(--ec-page-border))",
+        display: "flex",
+        gap: 6,
+        alignItems: "flex-start",
+      }}
+    >
+      {note.author && <Avatar name={note.author} size={16} />}
+      <div style={{ flex: 1, minWidth: 0 }}>
+        <div
+          style={{
+            display: "flex",
+            alignItems: "center",
+            gap: 4,
+            marginBottom: 2,
+          }}
+        >
+          {note.author && (
+            <span
+              style={{
+                fontSize: 9,
+                fontWeight: 700,
+                color: "rgb(var(--ec-page-text))",
+                lineHeight: 1,
+              }}
+            >
+              {note.author}
+            </span>
+          )}
+          {note.priority && <PriorityPill priority={note.priority} />}
+        </div>
+        <p
+          style={{
+            fontSize: 9,
+            lineHeight: 1.45,
+            color: "rgb(var(--ec-page-text-muted))",
+            margin: 0,
+            display: "-webkit-box",
+            WebkitLineClamp: 2,
+            WebkitBoxOrient: "vertical",
+            overflow: "hidden",
+          }}
+        >
+          {note.content}
+        </p>
+      </div>
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Modal note card (thread-style)                                     */
+/* ------------------------------------------------------------------ */
+
+function NoteCard({ note, isDark }: { note: Note; isDark: boolean }) {
+  const prioStyle = note.priority
+    ? PRIORITY[note.priority.toLowerCase()]
+    : null;
+
+  return (
+    <div
+      style={{
+        background: isDark
+          ? `radial-gradient(circle, rgba(255,255,255,0.15) 1px, transparent 1px), rgba(255,255,255,0.04)`
+          : `radial-gradient(circle, rgba(212,201,168,0.4) 1px, transparent 1px), #fef9ed`,
+        backgroundSize: "12px 12px",
+        border: `1px solid ${isDark ? "rgba(255,255,255,0.08)" : "#e5dcc3"}`,
+        borderBottom: `2px dashed ${isDark ? "rgba(255,255,255,0.1)" : "#d4c9a8"}`,
+        borderRadius: "8px 8px 0 0",
+        padding: "14px 16px 14px",
+        position: "relative",
+      }}
+    >
+      {/* Author */}
+      {note.author && (
+        <span
+          style={{
+            display: "block",
+            fontSize: 11,
+            fontWeight: 650,
+            color: isDark ? "#e2e8f0" : "#1e293b",
+            marginBottom: 8,
+          }}
+        >
+          {note.author}
+        </span>
+      )}
+
+      {/* Content — styled like a handwritten note */}
+      <p
+        style={{
+          fontSize: 13,
+          lineHeight: 1.7,
+          color: isDark ? "#cbd5e1" : "#1e293b",
+          margin: 0,
+          whiteSpace: "pre-wrap",
+          wordBreak: "break-word",
+          fontStyle: "italic",
+        }}
+      >
+        &ldquo;{note.content}&rdquo;
+      </p>
+    </div>
+  );
+}
+
+/** Group notes by priority: critical/high first, then low, then no priority */
+function groupNotes(
+  notes: Note[],
+): { label: string; notes: Note[]; color: string }[] {
+  const urgent: Note[] = [];
+  const low: Note[] = [];
+  const normal: Note[] = [];
+
+  for (const n of notes) {
+    const p = n.priority?.toLowerCase();
+    if (p === "critical" || p === "high") urgent.push(n);
+    else if (p === "low") low.push(n);
+    else normal.push(n);
+  }
+
+  const groups: { label: string; notes: Note[]; color: string }[] = [];
+  if (urgent.length > 0)
+    groups.push({ label: "High Priority", notes: urgent, color: "#ef4444" });
+  if (normal.length > 0)
+    groups.push({ label: "Notes", notes: normal, color: "#f59e0b" });
+  if (low.length > 0)
+    groups.push({ label: "Low Priority", notes: low, color: "#22c55e" });
+  return groups;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Full-screen modal                                                  */
+/* ------------------------------------------------------------------ */
+
+export function NotesModal({
+  notes,
+  isOpen,
+  onClose,
+  resourceName,
+  resourceVersion,
+  resourceType,
+  accentColor,
+  icon,
+}: {
+  notes: Note[];
+  isOpen: boolean;
+  onClose: () => void;
+  resourceName?: string;
+  resourceVersion?: string;
+  resourceType?: string;
+  accentColor?: string;
+  icon?: React.ReactNode;
+}) {
+  const isDark = useDarkMode();
+  const portalContainer = usePortalContainer();
+  const count = notes.length;
+  const urgent = notes.filter(
+    (n) =>
+      n.priority &&
+      (n.priority.toLowerCase() === "high" ||
+        n.priority.toLowerCase() === "critical"),
+  );
+
+  return (
+    <Dialog.Root open={isOpen} onOpenChange={(open) => !open && onClose()}>
+      <Dialog.Portal container={portalContainer}>
+        <div
+          className="fixed inset-0 z-[99999]"
+          style={{ isolation: "isolate" }}
+        >
+          <Dialog.Overlay
+            style={{
+              position: "fixed",
+              inset: 0,
+              background: isDark
+                ? "rgba(0, 0, 0, 0.7)"
+                : "rgba(15, 23, 42, 0.55)",
+              backdropFilter: "blur(8px)",
+            }}
+          />
+
+          <Dialog.Content
+            style={{
+              position: "fixed",
+              top: "50%",
+              left: "50%",
+              transform: "translate(-50%, -50%)",
+              width: "92vw",
+              maxWidth: 500,
+              maxHeight: "80vh",
+              background: isDark ? "#1e2330" : "#ffffff",
+              borderRadius: 16,
+              border: `1px solid ${isDark ? "rgba(255,255,255,0.08)" : "rgba(0,0,0,0.08)"}`,
+              boxShadow: isDark
+                ? "0 24px 48px rgba(0,0,0,0.5)"
+                : "0 24px 48px rgba(0,0,0,0.15)",
+              display: "flex",
+              flexDirection: "column",
+              overflow: "hidden",
+              outline: "none",
+            }}
+          >
+            {/* -------- Header -------- */}
+            <div
+              style={{
+                padding: "20px 22px 16px",
+                borderBottom: `1px solid ${isDark ? "rgba(255,255,255,0.06)" : "rgba(0,0,0,0.06)"}`,
+                display: "flex",
+                alignItems: "center",
+                gap: 14,
+              }}
+            >
+              {/* Resource icon */}
+              <div
+                style={{
+                  width: 36,
+                  height: 36,
+                  borderRadius: 10,
+                  background:
+                    accentColor ||
+                    `linear-gradient(135deg, ${AMBER[400]}, ${AMBER[500]})`,
+                  display: "flex",
+                  alignItems: "center",
+                  justifyContent: "center",
+                  flexShrink: 0,
+                }}
+              >
+                {icon || (
+                  <MessageCircle
+                    style={{ width: 18, height: 18, color: "white" }}
+                    strokeWidth={2.5}
+                  />
+                )}
+              </div>
+
+              {/* Title block */}
+              <div style={{ flex: 1, minWidth: 0 }}>
+                <Dialog.Title
+                  style={{
+                    fontSize: 15,
+                    fontWeight: 700,
+                    color: isDark ? "#f1f5f9" : "#0f172a",
+                    margin: 0,
+                    lineHeight: 1.3,
+                    letterSpacing: "-0.01em",
+                    display: "flex",
+                    alignItems: "baseline",
+                    gap: 6,
+                  }}
+                >
+                  {resourceName || "Notes"}
+                  {resourceVersion && (
+                    <span
+                      style={{
+                        fontSize: 11,
+                        fontWeight: 500,
+                        color: isDark ? "#64748b" : "#94a3b8",
+                      }}
+                    >
+                      v{resourceVersion}
+                    </span>
+                  )}
+                </Dialog.Title>
+                <Dialog.Description
+                  style={{
+                    fontSize: 12,
+                    color: isDark ? "#94a3b8" : "#64748b",
+                    margin: 0,
+                    marginTop: 3,
+                    lineHeight: 1.3,
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 6,
+                  }}
+                >
+                  {resourceType && (
+                    <span
+                      style={{
+                        fontSize: 10,
+                        fontWeight: 700,
+                        textTransform: "uppercase",
+                        letterSpacing: "0.05em",
+                      }}
+                    >
+                      {resourceType}
+                    </span>
+                  )}
+                  {resourceType && (
+                    <span style={{ opacity: 0.4 }}>&middot;</span>
+                  )}
+                  {count} note{count !== 1 ? "s" : ""}
+                  {urgent.length > 0 &&
+                    ` \u00b7 ${urgent.length} high priority`}
+                </Dialog.Description>
+              </div>
+
+              {/* Close */}
+              <Dialog.Close asChild>
+                <button
+                  aria-label="Close"
+                  style={{
+                    width: 32,
+                    height: 32,
+                    borderRadius: 8,
+                    border: "none",
+                    background: isDark
+                      ? "rgba(255,255,255,0.06)"
+                      : "rgba(0,0,0,0.04)",
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    cursor: "pointer",
+                    color: isDark ? "#94a3b8" : "#94a3b8",
+                    flexShrink: 0,
+                  }}
+                >
+                  <XIcon style={{ width: 16, height: 16 }} />
+                </button>
+              </Dialog.Close>
+            </div>
+
+            {/* -------- Grouped notes -------- */}
+            <div
+              style={{
+                flex: 1,
+                overflowY: "auto",
+                padding: "16px 22px 24px",
+                display: "flex",
+                flexDirection: "column",
+                gap: 18,
+              }}
+            >
+              {groupNotes(notes).map((group) => (
+                <div key={group.label}>
+                  {/* Group header */}
+                  <div
+                    style={{
+                      display: "flex",
+                      alignItems: "center",
+                      gap: 8,
+                      marginBottom: 10,
+                    }}
+                  >
+                    <div
+                      style={{
+                        width: 8,
+                        height: 8,
+                        borderRadius: "50%",
+                        background: group.color,
+                        flexShrink: 0,
+                      }}
+                    />
+                    <span
+                      style={{
+                        fontSize: 11,
+                        fontWeight: 700,
+                        color: isDark ? "#94a3b8" : "#64748b",
+                        textTransform: "uppercase",
+                        letterSpacing: "0.06em",
+                      }}
+                    >
+                      {group.label}
+                    </span>
+                    <span
+                      style={{
+                        fontSize: 10,
+                        fontWeight: 600,
+                        color: isDark ? "#475569" : "#94a3b8",
+                      }}
+                    >
+                      ({group.notes.length})
+                    </span>
+                    <div
+                      style={{
+                        flex: 1,
+                        height: 1,
+                        background: isDark
+                          ? "rgba(255,255,255,0.06)"
+                          : "rgba(0,0,0,0.06)",
+                      }}
+                    />
+                  </div>
+                  {/* Notes in group */}
+                  <div
+                    style={{
+                      display: "flex",
+                      flexDirection: "column",
+                      gap: 16,
+                    }}
+                  >
+                    {group.notes.map((note, i) => (
+                      <NoteCard key={i} note={note} isDark={isDark} />
+                    ))}
+                  </div>
+                </div>
+              ))}
+            </div>
+          </Dialog.Content>
+        </div>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Main indicator                                                     */
+/* ------------------------------------------------------------------ */
+
+export const NotesIndicator = memo(function NotesIndicator({
+  notes,
+  resourceName,
+}: {
+  notes: Note[];
+  resourceName?: string;
+}) {
+  const [isHovered, setIsHovered] = useState(false);
+  const [isModalOpen, setIsModalOpen] = useState(false);
+
+  const handleClick = useCallback((e: React.MouseEvent) => {
+    e.stopPropagation();
+    setIsHovered(false);
+    setIsModalOpen(true);
+  }, []);
+
+  if (!notes || notes.length === 0) return null;
+
+  const count = notes.length;
+  const hasUrgent = notes.some(
+    (n) =>
+      n.priority &&
+      (n.priority.toLowerCase() === "high" ||
+        n.priority.toLowerCase() === "critical"),
+  );
+
+  return (
+    <>
+      <div
+        className="absolute -top-2.5 -right-2.5 z-30 nopan nodrag"
+        onMouseEnter={() => setIsHovered(true)}
+        onMouseLeave={() => setIsHovered(false)}
+        onPointerDown={(e) => e.stopPropagation()}
+      >
+        {/* Count badge */}
+        <div
+          className="flex items-center justify-center cursor-pointer"
+          onClick={handleClick}
+          style={{
+            width: 22,
+            height: 22,
+            borderRadius: "50%",
+            background: hasUrgent
+              ? "linear-gradient(135deg, #ef4444, #dc2626)"
+              : `linear-gradient(135deg, ${AMBER[400]}, ${AMBER[500]})`,
+            boxShadow: `0 0 0 2.5px rgb(var(--ec-card-bg)), 0 2px 6px rgba(0,0,0,0.15)`,
+            transition: "transform 0.15s ease",
+            transform: isHovered ? "scale(1.15)" : "scale(1)",
+          }}
+        >
+          <span
+            style={{
+              fontSize: 11,
+              fontWeight: 800,
+              color: "white",
+              lineHeight: 1,
+            }}
+          >
+            {count}
+          </span>
+        </div>
+
+        {/* Hover popover */}
+        {isHovered && !isModalOpen && (
+          <div
+            className="absolute top-full right-0 mt-2 pointer-events-none"
+            style={{ minWidth: 200, maxWidth: 250, zIndex: 50 }}
+          >
+            <div
+              style={{
+                background: "rgb(var(--ec-card-bg))",
+                borderRadius: 10,
+                border: `1px solid ${AMBER[200]}`,
+                boxShadow:
+                  "0 4px 20px rgba(0,0,0,0.1), 0 1px 3px rgba(0,0,0,0.06)",
+                overflow: "hidden",
+              }}
+            >
+              {/* Header */}
+              <div
+                style={{
+                  padding: "6px 10px",
+                  background: AMBER[50],
+                  borderBottom: `1px solid ${AMBER[200]}`,
+                  display: "flex",
+                  alignItems: "center",
+                  gap: 5,
+                }}
+              >
+                <MessageCircle
+                  style={{ width: 10, height: 10, color: AMBER[600] }}
+                  strokeWidth={2.5}
+                />
+                <span
+                  style={{
+                    fontSize: 9,
+                    fontWeight: 700,
+                    color: AMBER[800],
+                    flex: 1,
+                    letterSpacing: "0.01em",
+                  }}
+                >
+                  {count} note{count !== 1 ? "s" : ""}
+                </span>
+                <span
+                  style={{
+                    fontSize: 8,
+                    color: AMBER[600],
+                    fontWeight: 500,
+                    opacity: 0.8,
+                  }}
+                >
+                  click to open
+                </span>
+              </div>
+
+              {/* List */}
+              <div style={{ maxHeight: 150, overflowY: "auto" }}>
+                {notes.slice(0, 3).map((note, i) => (
+                  <PopoverCard
+                    key={i}
+                    note={note}
+                    last={i === Math.min(count, 3) - 1 && count <= 3}
+                  />
+                ))}
+              </div>
+
+              {count > 3 && (
+                <div
+                  style={{
+                    padding: "5px 10px",
+                    borderTop: "1px solid rgb(var(--ec-page-border))",
+                    textAlign: "center",
+                  }}
+                >
+                  <span
+                    style={{
+                      fontSize: 8,
+                      fontWeight: 600,
+                      color: "#94a3b8",
+                    }}
+                  >
+                    +{count - 3} more
+                  </span>
+                </div>
+              )}
+            </div>
+
+            {/* Arrow pointing up */}
+            <div
+              style={{
+                position: "absolute",
+                top: -5,
+                right: 10,
+                width: 10,
+                height: 10,
+                background: "rgb(var(--ec-card-bg))",
+                border: `1px solid ${AMBER[200]}`,
+                borderRight: "none",
+                borderBottom: "none",
+                transform: "rotate(45deg)",
+                zIndex: 1,
+              }}
+            />
+          </div>
+        )}
+      </div>
+
+      <NotesModal
+        notes={notes}
+        isOpen={isModalOpen}
+        onClose={() => setIsModalOpen(false)}
+        resourceName={resourceName}
+      />
+    </>
+  );
+});
diff --git a/packages/visualiser/src/nodes/OwnerIndicator.tsx b/packages/visualiser/src/nodes/OwnerIndicator.tsx
new file mode 100644
index 000000000..f3a2f11ed
--- /dev/null
+++ b/packages/visualiser/src/nodes/OwnerIndicator.tsx
@@ -0,0 +1,80 @@
+import { memo } from "react";
+import { UserIcon, UsersIcon } from "lucide-react";
+import { OWNER_ICON_SIZE_STYLE } from "./shared-styles";
+
+/** Shared style for hidden React Flow handles (avoids inline object allocation). */
+export const HIDDEN_HANDLE_STYLE = { opacity: 0 } as const;
+
+/**
+ * Normalise owners which may arrive as string[] or {id:string}[] from Astro.
+ */
+export function normalizeOwners(raw: any[] | undefined): string[] {
+  if (!raw || raw.length === 0) return [];
+  return raw
+    .filter(Boolean)
+    .map((o: any) => (typeof o === "string" ? o : (o?.id ?? "")));
+}
+
+/**
+ * Compact owner indicator for the bottom of a node card.
+ * Shows a small icon + primary owner name + overflow pill.
+ *
+ * @param accentColor - Tailwind color class for the pill, e.g. "bg-pink-400"
+ * @param borderColor - CSS color string for the top border
+ * @param iconClass   - Tailwind text color for the icon, e.g. "text-pink-300"
+ */
+export const OwnerIndicator = memo(function OwnerIndicator({
+  owners,
+  accentColor = "bg-pink-400",
+  borderColor = "rgba(236,72,153,0.08)",
+  iconClass = "text-pink-300",
+}: {
+  owners: string[];
+  accentColor?: string;
+  borderColor?: string;
+  iconClass?: string;
+}) {
+  if (owners.length === 0) return null;
+
+  const primary = owners[0];
+  const remaining = owners.length - 1;
+  const isLikelyTeam = primary.includes(" ") || primary.includes("-");
+
+  return (
+    <div
+      className="flex items-center gap-1 mt-1.5 pt-1.5"
+      style={{ borderTop: `1px solid ${borderColor}` }}
+      title={owners.join(", ")}
+    >
+      {/* Icon */}
+      {isLikelyTeam ? (
+        <UsersIcon
+          className={`${iconClass} shrink-0`}
+          style={OWNER_ICON_SIZE_STYLE}
+          strokeWidth={2.5}
+        />
+      ) : (
+        <UserIcon
+          className={`${iconClass} shrink-0`}
+          style={OWNER_ICON_SIZE_STYLE}
+          strokeWidth={2.5}
+        />
+      )}
+
+      {/* Primary owner name */}
+      <span className="text-[8px] text-[rgb(var(--ec-page-text-muted))] truncate leading-none">
+        {primary}
+      </span>
+
+      {/* Overflow count */}
+      {remaining > 0 && (
+        <span
+          className={`shrink-0 inline-flex items-center justify-center text-[7px] font-bold text-white ${accentColor} rounded-full px-1 py-[1px] leading-none`}
+          title={owners.slice(1).join(", ")}
+        >
+          +{remaining}
+        </span>
+      )}
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/Step.tsx b/packages/visualiser/src/nodes/Step.tsx
new file mode 100644
index 000000000..80951953e
--- /dev/null
+++ b/packages/visualiser/src/nodes/Step.tsx
@@ -0,0 +1,108 @@
+import { memo } from "react";
+import { Handle, Position } from "@xyflow/react";
+import { HIDDEN_HANDLE_STYLE } from "./OwnerIndicator";
+import { NODE_WIDTH_STYLE, ROTATED_LABEL_STYLE } from "./shared-styles";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+
+interface Data {
+  title: string;
+  label: string;
+  bgColor: string;
+  color: string;
+  mode: "simple" | "full";
+  step: { id: string; title: string; summary: string };
+  showTarget?: boolean;
+  showSource?: boolean;
+}
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+export default memo(function StepNode({
+  data,
+  sourcePosition,
+  targetPosition,
+}: any) {
+  const { mode, step } = data as Data;
+
+  const { title, summary } = step;
+
+  return (
+    <div
+      className={classNames(
+        "rounded-md border flex justify-start bg-[rgb(var(--ec-card-bg))] text-[rgb(var(--ec-page-text))] border-blue-400 min-h-[3em]",
+      )}
+      style={NODE_WIDTH_STYLE}
+    >
+      <div
+        className={classNames(
+          "bg-gradient-to-b from-gray-700 to-gray-700 relative flex flex-col items-center w-5 justify-end rounded-l-sm text-orange-100-500",
+          `border-r-[1px] border-gray-500`,
+        )}
+      >
+        {mode === "full" && (
+          <span
+            className="text-center text-[9px] text-white font-bold uppercase mb-4"
+            style={ROTATED_LABEL_STYLE}
+          >
+            Step
+          </span>
+        )}
+      </div>
+      <div className="p-1 flex-1 min-w-0">
+        <Handle
+          type="target"
+          position={targetPosition || Position.Left}
+          style={HIDDEN_HANDLE_STYLE}
+        />
+        <Handle
+          type="source"
+          position={sourcePosition || Position.Right}
+          style={HIDDEN_HANDLE_STYLE}
+        />
+
+        {!summary && (
+          <div className="h-full flex items-center min-w-0">
+            <TruncatedResourceName
+              as="div"
+              value={title}
+              tooltipBorderColor="#60a5fa"
+              className="text-sm font-bold truncate pb-0.5"
+            >
+              {title}
+            </TruncatedResourceName>
+          </div>
+        )}
+
+        {summary && (
+          <div>
+            <div
+              className={classNames(
+                mode === "full"
+                  ? `border-b border-[rgb(var(--ec-page-border))]`
+                  : "",
+              )}
+            >
+              <TruncatedResourceName
+                as="div"
+                value={title}
+                tooltipBorderColor="#60a5fa"
+                className="text-xs font-bold truncate pb-0.5"
+              >
+                {title}
+              </TruncatedResourceName>
+            </div>
+            {mode === "full" && (
+              <div className="divide-y divide-[rgb(var(--ec-page-border))] ">
+                <div className="leading-3 py-1">
+                  <span className="text-[8px] font-light">{summary}</span>
+                </div>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/System.tsx b/packages/visualiser/src/nodes/System.tsx
new file mode 100644
index 000000000..4d0680a2a
--- /dev/null
+++ b/packages/visualiser/src/nodes/System.tsx
@@ -0,0 +1,165 @@
+import { Handle, Position } from "@xyflow/react";
+import {
+  Group as GroupIcon,
+  Server as ServerIcon,
+  Box as BoxIcon,
+  Database as DatabaseIcon,
+  MessageSquare as MessageSquareIcon,
+} from "lucide-react";
+import { buildUrl, navigateTo } from "../utils/url-builder";
+import { memo } from "react";
+import { LINE_CLAMP_STYLE, useDarkMode } from "./shared-styles";
+import { HIDDEN_HANDLE_STYLE } from "./OwnerIndicator";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+
+interface SystemData {
+  id: string;
+  version: string;
+  name: string;
+  summary?: string;
+  // "external" marks a third-party/SaaS system (e.g. Resend, Stripe). Such
+  // systems are shaded in the graph. Defaults to internal when absent.
+  scope?: "internal" | "external";
+}
+
+interface Data {
+  mode: "simple" | "full";
+  system: SystemData;
+  servicesCount?: number;
+  entitiesCount?: number;
+  containersCount?: number;
+  // Total messages handled by the system's services (sends + receives).
+  messagesCount?: number;
+}
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+/**
+ * A system rendered on the System Diagram.
+ *
+ * Styled to match the other resource nodes (e.g. the service node): a rounded,
+ * bordered card with a floating type badge + icon on the top-left border.
+ * Left-clicking the node navigates to the system's architecture map.
+ * Right-click (handled by the NodeGraph context-menu wrapper) offers docs / map / context.
+ */
+export default memo(function SystemNode({ data }: any) {
+  const {
+    system,
+    mode = "simple",
+    servicesCount = 0,
+    entitiesCount = 0,
+    containersCount = 0,
+    messagesCount = 0,
+  } = data as Data;
+  const { id, version, name, summary, scope } = system;
+  const isExternal = scope === "external";
+  const isDark = useDarkMode();
+
+  const stats = [
+    { icon: ServerIcon, label: "Services", count: servicesCount },
+    { icon: MessageSquareIcon, label: "Messages", count: messagesCount },
+    { icon: BoxIcon, label: "Entities", count: entitiesCount },
+    { icon: DatabaseIcon, label: "Data Stores", count: containersCount },
+  ].filter((stat) => stat.count > 0);
+
+  // External systems get a subtle gray fill so they read as outside the org,
+  // without the busier striped treatment.
+  const cardBackground = isExternal
+    ? isDark
+      ? "rgba(148,163,184,0.12)"
+      : "rgba(148,163,184,0.1)"
+    : "var(--ec-system-node-bg, rgb(var(--ec-card-bg)))";
+
+  const goToMap = () => {
+    // Soft, animated navigation via the host's view-transition router when
+    // available (falls back to a hard nav). Both the System Diagram and
+    // the target system Map share a `transition:name="visualiser-graph"` portal,
+    // so this reads as drilling one level deeper into the system.
+    navigateTo(buildUrl(`/visualiser/systems/${id}/${version}`));
+  };
+
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      onClick={goToMap}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") goToMap();
+      }}
+      title={`Open the ${name} map`}
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible cursor-pointer",
+        isExternal ? "border-dashed border-violet-400" : "border-violet-500",
+      )}
+      style={{
+        background: cardBackground,
+        boxShadow: "0 2px 12px rgba(139, 92, 246, 0.15)",
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+
+      {/* Floating type badge on the top-left border */}
+      <div className="absolute -top-2.5 left-2.5 flex items-center gap-1.5 z-10">
+        <span className="inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm bg-violet-500">
+          <GroupIcon className="w-2.5 h-2.5" strokeWidth={2.5} />
+          {isExternal ? "External System" : "System"}
+        </span>
+      </div>
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        <div className="flex items-baseline gap-1 min-w-0">
+          <TruncatedResourceName
+            value={name}
+            tooltipBorderColor="#8b5cf6"
+            className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+          >
+            {name}
+          </TruncatedResourceName>
+          {version && (
+            <span className="text-[10px] font-normal text-[rgb(var(--ec-page-text-muted))] shrink-0">
+              (v{version})
+            </span>
+          )}
+        </div>
+
+        {mode === "full" && summary && (
+          <div
+            className={classNames(
+              "mt-1.5 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed overflow-hidden",
+            )}
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+
+        {stats.length > 0 && (
+          <div className="mt-2 flex items-center gap-3 border-t border-[rgb(var(--ec-page-border))] pt-1.5">
+            {stats.map(({ icon: Icon, label, count }) => (
+              <div
+                key={label}
+                title={`${count} ${label}`}
+                className="flex items-center gap-1 text-[10px] text-[rgb(var(--ec-page-text-muted))]"
+              >
+                <Icon className="w-3 h-3 text-violet-500" strokeWidth={2} />
+                <span className="font-medium">{count}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/SystemGroupNode.tsx b/packages/visualiser/src/nodes/SystemGroupNode.tsx
new file mode 100644
index 000000000..9ecb55ad3
--- /dev/null
+++ b/packages/visualiser/src/nodes/SystemGroupNode.tsx
@@ -0,0 +1,111 @@
+import { memo } from "react";
+import type { NodeProps } from "@xyflow/react";
+import { Group as GroupIcon } from "lucide-react";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+
+export type SystemGroupNodeData = {
+  system: {
+    name: string;
+    version?: string;
+  };
+};
+
+/**
+ * A boundary box wrapping all of a system's nodes on the System Diagram, so the
+ * services / data stores / messages inside visibly belong to one parent system.
+ *
+ * Sized + positioned by the node-graph (it wraps the laid-out children); this
+ * component only renders the chrome — a rounded violet box with a header banner
+ * carrying the system name + icon.
+ */
+const CONTAINER_STYLE = {
+  width: "100%",
+  height: "100%",
+  borderRadius: 14,
+  border: "2px solid var(--ec-system-group-border, #c4b5fd)",
+  // Slightly gray, translucent body so the grouped children read as "inside".
+  backgroundColor: "var(--ec-system-group-bg, rgba(100, 116, 139, 0.06))",
+  position: "relative" as const,
+  overflow: "visible" as const,
+  boxShadow: "0 2px 16px rgba(139, 92, 246, 0.10)",
+} as const;
+
+const HEADER_STYLE = {
+  position: "absolute" as const,
+  top: 0,
+  left: 0,
+  right: 0,
+  height: 48,
+  borderTopLeftRadius: 12,
+  borderTopRightRadius: 12,
+  // Faint violet wash on the header, separated from the body by a hairline.
+  background: "var(--ec-system-group-header-bg, rgba(139, 92, 246, 0.05))",
+  borderBottom: "1px solid var(--ec-system-group-border, #c4b5fd)",
+  display: "flex",
+  alignItems: "center" as const,
+  padding: "0 16px",
+  overflow: "visible" as const,
+} as const;
+
+// Floating "SYSTEM" badge on the top-left border — mirrors the System node badge.
+const BADGE_STYLE = {
+  position: "absolute" as const,
+  top: -11,
+  left: 14,
+  display: "inline-flex",
+  alignItems: "center" as const,
+  gap: 4,
+  fontSize: 8,
+  fontWeight: 700,
+  letterSpacing: "0.12em",
+  textTransform: "uppercase" as const,
+  color: "white",
+  background: "#8b5cf6",
+  padding: "2px 7px",
+  borderRadius: 5,
+  boxShadow: "0 1px 2px rgba(0,0,0,0.12)",
+  zIndex: 10,
+} as const;
+
+const NAME_STYLE = {
+  fontSize: 14,
+  fontWeight: 700,
+  color: "var(--ec-system-group-text, #5b21b6)",
+  whiteSpace: "nowrap" as const,
+} as const;
+
+const VERSION_STYLE = {
+  fontSize: 10,
+  fontWeight: 500,
+  color: "#a78bfa",
+  marginLeft: 6,
+} as const;
+
+export default memo(function SystemGroupNode({ data }: NodeProps) {
+  const { system } = data as unknown as SystemGroupNodeData;
+
+  return (
+    <div style={CONTAINER_STYLE}>
+      {/* Floating type badge, styled like the System node's badge */}
+      <span style={BADGE_STYLE}>
+        <GroupIcon size={10} strokeWidth={2.5} />
+        System
+      </span>
+
+      {/* Header banner carrying the system name */}
+      <div style={HEADER_STYLE}>
+        <TruncatedResourceName
+          value={system?.name || "System"}
+          tooltipBorderColor="#8b5cf6"
+          className="truncate"
+          style={NAME_STYLE}
+        >
+          {system?.name || "System"}
+        </TruncatedResourceName>
+        {system?.version && (
+          <span style={VERSION_STYLE}>v{system.version}</span>
+        )}
+      </div>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/TruncatedResourceName.tsx b/packages/visualiser/src/nodes/TruncatedResourceName.tsx
new file mode 100644
index 000000000..16f4c3d8a
--- /dev/null
+++ b/packages/visualiser/src/nodes/TruncatedResourceName.tsx
@@ -0,0 +1,75 @@
+import {
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+
+type TruncatedResourceNameProps = {
+  as?: "div" | "span";
+  children: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+  tooltipBorderColor?: string;
+  value: string;
+};
+
+export function TruncatedResourceName({
+  as: Component = "span",
+  children,
+  className,
+  style,
+  tooltipBorderColor = "rgb(var(--ec-page-border))",
+  value,
+}: TruncatedResourceNameProps) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const [isTruncated, setIsTruncated] = useState(false);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+
+    const updateTruncation = () => {
+      setIsTruncated(element.scrollWidth > element.clientWidth);
+    };
+
+    updateTruncation();
+
+    if (typeof ResizeObserver === "undefined") {
+      window.addEventListener("resize", updateTruncation);
+      return () => window.removeEventListener("resize", updateTruncation);
+    }
+
+    const observer = new ResizeObserver(updateTruncation);
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [value]);
+
+  return (
+    <Component className="ec-truncated-resource-name group relative min-w-0 max-w-full flex-1">
+      <span
+        ref={ref}
+        className={`block min-w-0 ${className || ""}`}
+        style={style}
+      >
+        {children}
+      </span>
+      {isTruncated && (
+        <span
+          className="ec-truncated-resource-name-tooltip pointer-events-none absolute left-1/2 bottom-full z-[9999] mb-4 hidden w-max max-w-[320px] -translate-x-1/2 rounded-md border-2 bg-slate-950 px-2.5 py-1.5 text-[11px] font-medium leading-snug text-white shadow-lg group-hover:block group-focus-within:block"
+          style={{ borderColor: tooltipBorderColor }}
+        >
+          <span className="block whitespace-normal break-words">{value}</span>
+          <span
+            className="absolute left-1/2 top-full h-2 w-2 -translate-x-1/2 -translate-y-1/2 rotate-45 border-b border-r bg-slate-950"
+            style={{
+              borderBottomColor: tooltipBorderColor,
+              borderRightColor: tooltipBorderColor,
+            }}
+          />
+        </span>
+      )}
+    </Component>
+  );
+}
diff --git a/packages/visualiser/src/nodes/User.tsx b/packages/visualiser/src/nodes/User.tsx
new file mode 100644
index 000000000..f63ed4478
--- /dev/null
+++ b/packages/visualiser/src/nodes/User.tsx
@@ -0,0 +1,121 @@
+import { memo } from "react";
+import { UserIcon } from "@heroicons/react/20/solid";
+import { Handle } from "@xyflow/react";
+import { NODE_WIDTH_STYLE, ROTATED_LABEL_STYLE } from "./shared-styles";
+import { TruncatedResourceName } from "./TruncatedResourceName";
+
+interface Data {
+  title: string;
+  label: string;
+  bgColor: string;
+  color: string;
+  mode: "simple" | "full";
+  step: {
+    id: string;
+    title: string;
+    summary: string;
+    name: string;
+    actor: { name: string };
+  };
+  showTarget?: boolean;
+  showSource?: boolean;
+}
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+export default memo(function UserNode({
+  data,
+  sourcePosition,
+  targetPosition,
+}: any) {
+  const {
+    mode,
+    step,
+    showTarget: _showTarget = true,
+    showSource: _showSource = true,
+  } = data as Data;
+
+  const { summary, actor: { name } = {} } = step;
+  const displayName = name || step.name || step.title || "Actor";
+
+  return (
+    <div
+      className={classNames(
+        `rounded-md border flex justify-start bg-[rgb(var(--ec-card-bg))] text-[rgb(var(--ec-page-text))] border-yellow-400`,
+        mode === "full" ? "min-h-[5em]" : "min-h-[2em]",
+      )}
+      style={NODE_WIDTH_STYLE}
+    >
+      <div
+        className={classNames(
+          "bg-gradient-to-b from-yellow-400 to-yellow-600 relative flex flex-col items-center w-5 justify-between rounded-l-sm text-orange-100-500",
+          `border-r-[1px] border-yellow-500`,
+        )}
+      >
+        <UserIcon className="w-4 h-4 opacity-90 text-white mt-1" />
+        {mode === "full" && (
+          <span
+            className="text-center text-[9px] text-white font-bold uppercase mb-4"
+            style={ROTATED_LABEL_STYLE}
+          >
+            ACTOR
+          </span>
+        )}
+      </div>
+      <div className="p-1 flex-1 min-w-0">
+        {targetPosition && <Handle type="target" position={targetPosition} />}
+        {sourcePosition && <Handle type="source" position={sourcePosition} />}
+
+        {(!summary || mode !== "full") && (
+          <div className="h-full min-w-0">
+            <TruncatedResourceName
+              as="div"
+              value={displayName}
+              tooltipBorderColor="#eab308"
+              className="text-sm font-bold truncate pb-0.5"
+            >
+              {displayName}
+            </TruncatedResourceName>
+            {mode === "simple" && (
+              <div className="w-full text-right">
+                <span className=" w-full text-[10px] text-[rgb(var(--ec-page-text-muted))] font-light block pt-0.5 pb-0.5 ">
+                  Event
+                </span>
+              </div>
+            )}
+          </div>
+        )}
+
+        {summary && mode === "full" && (
+          <div>
+            <div
+              className={classNames(
+                mode === "full"
+                  ? `border-b border-[rgb(var(--ec-page-border))]`
+                  : "",
+              )}
+            >
+              <TruncatedResourceName
+                as="div"
+                value={displayName}
+                tooltipBorderColor="#eab308"
+                className="text-xs font-bold truncate pb-0.5"
+              >
+                {displayName}
+              </TruncatedResourceName>
+            </div>
+            {mode === "full" && (
+              <div className="divide-y divide-[rgb(var(--ec-page-border))] ">
+                <div className="leading-3 py-1">
+                  <span className="text-[8px] font-light">{summary}</span>
+                </div>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/actor/ActorNode.tsx b/packages/visualiser/src/nodes/actor/ActorNode.tsx
new file mode 100644
index 000000000..b9f1d2b5c
--- /dev/null
+++ b/packages/visualiser/src/nodes/actor/ActorNode.tsx
@@ -0,0 +1,244 @@
+import { memo } from "react";
+import { User } from "lucide-react";
+import { Node, Handle, Position, useNodeConnections } from "@xyflow/react";
+import { EventCatalogResource, Note } from "../../types";
+import { NotesIndicator } from "../NotesIndicator";
+import { HIDDEN_HANDLE_STYLE } from "../OwnerIndicator";
+import {
+  LINE_CLAMP_STYLE,
+  FOLDED_CORNER_SHADOW_STYLE,
+  useDarkMode,
+} from "../shared-styles";
+import { TruncatedResourceName } from "../TruncatedResourceName";
+
+function GlowHandle({ side }: { side: "left" | "right" }) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: "linear-gradient(135deg, #eab308, #a16207)",
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: "ec-actor-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none",
+      }}
+    />
+  );
+}
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+type ActorNodeData = EventCatalogResource & {
+  name: string;
+  summary: string;
+  deprecated?: boolean;
+  draft?: boolean;
+  notes?: Note[];
+};
+
+export type ActorNode = Node<ActorNodeData, "actor">;
+
+function PostItActor(props: ActorNode) {
+  const { name, summary, deprecated, draft, notes } = props?.data;
+  const mode = props?.data?.mode || "simple";
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-44 max-w-56 min-h-[120px]",
+        props?.selected ? "ring-2 ring-yellow-400/60 ring-offset-1" : "",
+      )}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      <div
+        className="absolute inset-0"
+        style={{
+          background:
+            "linear-gradient(135deg, #fef9c3 0%, #fde047 40%, #eab308 100%)",
+          boxShadow:
+            "1px 1px 3px rgba(0,0,0,0.15), 3px 4px 8px rgba(0,0,0,0.08)",
+          transform: "rotate(1deg)",
+          border: deprecated
+            ? "2px dashed rgba(239, 68, 68, 0.5)"
+            : draft
+              ? "2px dashed rgba(234, 179, 8, 0.5)"
+              : "none",
+        }}
+      >
+        <div style={FOLDED_CORNER_SHADOW_STYLE} />
+        <div
+          style={{
+            position: "absolute",
+            top: 0,
+            right: 0,
+            width: 0,
+            height: 0,
+            borderStyle: "solid",
+            borderWidth: "18px 0 0 18px",
+            borderColor: "#a16207 transparent transparent transparent",
+            opacity: 0.3,
+          }}
+        />
+      </div>
+
+      <div className="relative px-3.5 py-3">
+        <div className="flex items-center justify-between mb-2">
+          <div className="flex items-center gap-1">
+            <User className="w-3 h-3 text-yellow-900/50" strokeWidth={2.5} />
+            <span className="text-[8px] font-bold text-yellow-900/50 uppercase tracking-widest">
+              Actor
+            </span>
+          </div>
+          {draft && (
+            <span className="text-[8px] font-extrabold text-amber-900 bg-amber-100 border border-dashed border-amber-400 px-1.5 py-0.5 rounded uppercase">
+              Draft
+            </span>
+          )}
+          {deprecated && (
+            <span className="text-[7px] font-bold text-white bg-red-500 border border-red-600 px-1.5 py-0.5 rounded uppercase">
+              Deprecated
+            </span>
+          )}
+        </div>
+
+        <TruncatedResourceName
+          as="div"
+          value={name}
+          tooltipBorderColor="#eab308"
+          className={classNames(
+            "text-[13px] font-bold leading-snug truncate",
+            deprecated ? "text-yellow-950/40 line-through" : "text-yellow-950",
+          )}
+        >
+          {name}
+        </TruncatedResourceName>
+
+        {mode === "full" && summary && (
+          <div
+            className="mt-2 pt-1.5 border-t border-yellow-900/10 text-[9px] text-yellow-950/60 leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function DefaultActor(props: ActorNode) {
+  const { name, summary, deprecated, draft, notes } = props?.data;
+  const mode = props?.data?.mode || "simple";
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const isDark = useDarkMode();
+  const deprecatedStripe = isDark
+    ? "rgba(239,68,68,0.25)"
+    : "rgba(239,68,68,0.1)";
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible",
+        props?.selected ? "ring-2 ring-yellow-400/60 ring-offset-2" : "",
+        deprecated
+          ? "border-dashed border-red-500"
+          : draft
+            ? `border-dashed ${isDark ? "border-yellow-400" : "border-yellow-400/60"}`
+            : "border-yellow-500",
+      )}
+      style={{
+        background: deprecated
+          ? `repeating-linear-gradient(135deg, transparent, transparent 6px, ${deprecatedStripe} 6px, ${deprecatedStripe} 7px), var(--ec-actor-node-bg, rgb(var(--ec-card-bg)))`
+          : draft
+            ? `repeating-linear-gradient(135deg, transparent, transparent 4px, ${isDark ? "rgba(234,179,8,0.25)" : "rgba(234,179,8,0.15)"} 4px, ${isDark ? "rgba(234,179,8,0.25)" : "rgba(234,179,8,0.15)"} 4.5px), repeating-linear-gradient(45deg, transparent, transparent 4px, ${isDark ? "rgba(234,179,8,0.25)" : "rgba(234,179,8,0.15)"} 4px, ${isDark ? "rgba(234,179,8,0.25)" : "rgba(234,179,8,0.15)"} 4.5px), var(--ec-actor-node-bg, rgb(var(--ec-card-bg)))`
+            : "var(--ec-actor-node-bg, rgb(var(--ec-card-bg)))",
+        boxShadow: "0 2px 12px rgba(234, 179, 8, 0.15)",
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {targetConnections.length > 0 && <GlowHandle side="left" />}
+      {sourceConnections.length > 0 && <GlowHandle side="right" />}
+
+      {/* Badge positioned outside top-left corner */}
+      <div className="absolute -top-2.5 left-2.5 flex items-center gap-1.5 z-10">
+        <span
+          className={classNames(
+            "inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm",
+            deprecated ? "bg-red-500" : "bg-yellow-500",
+          )}
+        >
+          <User className="w-2.5 h-2.5" strokeWidth={2.5} />
+          Actor{draft && " (Draft)"}
+          {deprecated && " (Deprecated)"}
+        </span>
+      </div>
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        {/* Name */}
+        <TruncatedResourceName
+          as="div"
+          value={name}
+          tooltipBorderColor="#eab308"
+          className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+        >
+          {name}
+        </TruncatedResourceName>
+
+        {/* Summary */}
+        {mode === "full" && summary && (
+          <div
+            className="mt-1.5 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default memo(function Actor(props: ActorNode) {
+  const nodeStyle = props?.data?.style;
+
+  if (nodeStyle === "post-it") {
+    return <PostItActor {...props} />;
+  }
+
+  return <DefaultActor {...props} />;
+});
diff --git a/packages/visualiser/src/nodes/actor/config.ts b/packages/visualiser/src/nodes/actor/config.ts
new file mode 100644
index 000000000..dd580067f
--- /dev/null
+++ b/packages/visualiser/src/nodes/actor/config.ts
@@ -0,0 +1,61 @@
+import { Connection, MarkerType } from "@xyflow/react";
+import { User } from "lucide-react";
+import { NodeConfiguration } from "../../types";
+import { SERVICE, MESSAGE, CHANNEL } from "../node-types";
+
+export default {
+  type: "actor",
+  icon: User,
+  color: "yellow",
+  targetCanConnectTo: [
+    ...SERVICE,
+    ...MESSAGE,
+    ...CHANNEL,
+    "external-system",
+    "view",
+  ],
+  sourceCanConnectTo: [
+    ...SERVICE,
+    ...MESSAGE,
+    ...CHANNEL,
+    "external-system",
+    "view",
+  ],
+  validateConnection: (connection: Connection) => {
+    return connection.source !== connection.target;
+  },
+  getEdgeOptions: (_connection: Connection) => {
+    return {
+      label: "Interacts",
+      markerEnd: { type: MarkerType.ArrowClosed, color: "#000000" },
+    };
+  },
+  defaultData: {
+    name: "New Actor",
+    summary:
+      "A person or user in the system. Click edit to change the details.",
+    mode: "full",
+  },
+  editor: {
+    title: "Actor",
+    subtitle: "Edit the details of the actor",
+    schema: {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: {
+          type: "string",
+          title: "Name",
+          default: "New Actor",
+          description: "The name of the actor (person/user)",
+        },
+        summary: {
+          type: "string",
+          title: "Description",
+          default: "",
+          description: "A brief description of the actor",
+        },
+      },
+    },
+  },
+} as NodeConfiguration;
diff --git a/packages/visualiser/src/nodes/actor/index.ts b/packages/visualiser/src/nodes/actor/index.ts
new file mode 100644
index 000000000..8396c8780
--- /dev/null
+++ b/packages/visualiser/src/nodes/actor/index.ts
@@ -0,0 +1,3 @@
+export { default as Actor } from "./ActorNode";
+export { default as actorConfig } from "./config";
+export type { ActorNode } from "./ActorNode";
diff --git a/packages/visualiser/src/nodes/channel/ChannelNode.tsx b/packages/visualiser/src/nodes/channel/ChannelNode.tsx
new file mode 100644
index 000000000..91ac11cf5
--- /dev/null
+++ b/packages/visualiser/src/nodes/channel/ChannelNode.tsx
@@ -0,0 +1,480 @@
+import { ArrowRightLeft, Link } from "lucide-react";
+import {
+  OwnerIndicator,
+  normalizeOwners,
+  HIDDEN_HANDLE_STYLE,
+} from "../OwnerIndicator";
+import { Node, Handle, Position, useNodeConnections } from "@xyflow/react";
+import { EventCatalogResource, Channel as ChannelType } from "../../types";
+import { NotesIndicator } from "../NotesIndicator";
+import {
+  LINE_CLAMP_STYLE,
+  FOLDED_CORNER_SHADOW_STYLE,
+  EMPTY_ARRAY,
+  useDarkMode,
+} from "../shared-styles";
+import { CustomIcon, isIconPath } from "../../utils/custom-icon";
+import { TruncatedResourceName } from "../TruncatedResourceName";
+
+import { memo, useMemo } from "react";
+
+const DELIVERY_GUARANTEE_LABELS: Record<string, string> = {
+  "at-most-once": "At most once",
+  "at-least-once": "At least once",
+  "exactly-once": "Exactly once",
+};
+
+const GUARANTEE_COLORS: Record<string, { hex: string; rgb: string }> = {
+  "exactly-once": { hex: "#22d3ee", rgb: "34,211,238" },
+  "at-least-once": { hex: "#a78bfa", rgb: "167,139,250" },
+  "at-most-once": { hex: "#f87171", rgb: "248,113,113" },
+};
+
+const DEFAULT_GUARANTEE = { hex: "#6b7280", rgb: "107,114,128" };
+
+function getGuarantee(guarantee?: string) {
+  return (guarantee && GUARANTEE_COLORS[guarantee]) || DEFAULT_GUARANTEE;
+}
+
+/**
+ * Delivery guarantee dot icon.
+ * - exactly-once  → filled circle
+ * - at-least-once → half-filled circle
+ * - at-most-once  → hollow ring
+ */
+function GuaranteeDot({
+  guarantee,
+  size = 6,
+}: {
+  guarantee: string;
+  size?: number;
+}) {
+  const { hex } = getGuarantee(guarantee);
+
+  if (guarantee === "exactly-once") {
+    return (
+      <span
+        className="shrink-0 rounded-full"
+        style={{ width: size, height: size, background: hex }}
+      />
+    );
+  }
+
+  if (guarantee === "at-least-once") {
+    return (
+      <span
+        className="shrink-0 rounded-full overflow-hidden"
+        style={{
+          width: size,
+          height: size,
+          background: `linear-gradient(90deg, ${hex} 50%, transparent 50%)`,
+          border: `1.5px solid ${hex}`,
+          boxSizing: "border-box",
+        }}
+      />
+    );
+  }
+
+  // at-most-once → hollow ring
+  return (
+    <span
+      className="shrink-0 rounded-full"
+      style={{
+        width: size,
+        height: size,
+        border: `1.5px solid ${hex}`,
+        boxSizing: "border-box",
+      }}
+    />
+  );
+}
+
+function GlowHandle({ side }: { side: "left" | "right" }) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: "linear-gradient(135deg, #6b7280, #374151)",
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: "ec-channel-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none",
+      }}
+    />
+  );
+}
+
+type ChannelNodeData = EventCatalogResource & {
+  channel: ChannelType;
+};
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+export type ChannelNode = Node<ChannelNodeData, "channel">;
+
+function PostItChannel(props: ChannelNode) {
+  const { data } = props;
+  const {
+    version,
+    name,
+    summary,
+    deprecated,
+    draft,
+    protocols = EMPTY_ARRAY,
+    notes,
+    deliveryGuarantee,
+    styles,
+  } = data.channel;
+  const mode = props.data.mode || "simple";
+  const guarantee = getGuarantee(deliveryGuarantee);
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-44 max-w-56 min-h-[120px]",
+        props?.selected ? "ring-2 ring-gray-400/60 ring-offset-1" : "",
+      )}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      <div
+        className="absolute inset-0"
+        style={{
+          background:
+            "linear-gradient(135deg, #e5e7eb 0%, #d1d5db 40%, #6b7280 100%)",
+          boxShadow:
+            "1px 1px 3px rgba(0,0,0,0.15), 3px 4px 8px rgba(0,0,0,0.08)",
+          transform: "rotate(-1deg)",
+          border: deprecated
+            ? "2px dashed rgba(239, 68, 68, 0.5)"
+            : draft
+              ? "2px dashed rgba(107, 114, 128, 0.5)"
+              : "none",
+        }}
+      >
+        {/* Folded corner */}
+        <div style={FOLDED_CORNER_SHADOW_STYLE} />
+        <div
+          style={{
+            position: "absolute",
+            top: 0,
+            right: 0,
+            width: 0,
+            height: 0,
+            borderStyle: "solid",
+            borderWidth: "18px 0 0 18px",
+            borderColor: "#374151 transparent transparent transparent",
+            opacity: 0.3,
+          }}
+        />
+      </div>
+
+      <div className="relative px-3.5 py-3">
+        {/* Type badge row */}
+        <div className="flex items-center justify-between mb-2">
+          <div className="flex items-center gap-1">
+            <ArrowRightLeft
+              className="w-3 h-3 text-gray-900/50"
+              strokeWidth={2.5}
+            />
+            <span className="text-[8px] font-bold text-gray-900/50 uppercase tracking-widest">
+              Channel
+            </span>
+          </div>
+          <div className="flex items-center gap-1">
+            {draft && (
+              <span className="text-[8px] font-extrabold text-amber-900 bg-amber-100 border border-dashed border-amber-400 px-1.5 py-0.5 rounded uppercase">
+                Draft
+              </span>
+            )}
+            {deprecated && (
+              <span className="text-[7px] font-bold text-white bg-red-500 border border-red-600 px-1.5 py-0.5 rounded uppercase">
+                Deprecated
+              </span>
+            )}
+          </div>
+        </div>
+
+        {/* Name + version */}
+        <div className="flex items-center gap-2">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className={
+                mode === "full"
+                  ? "w-5 h-5 shrink-0 mt-0.5"
+                  : "w-4 h-4 shrink-0 -my-1"
+              }
+            />
+          )}
+          <div className="flex items-baseline gap-1.5 min-w-0">
+            <TruncatedResourceName
+              as="div"
+              value={name}
+              tooltipBorderColor="#6b7280"
+              className={classNames(
+                "text-[13px] font-bold leading-snug truncate",
+                deprecated ? "text-gray-950/40 line-through" : "text-gray-950",
+              )}
+            >
+              {name}
+            </TruncatedResourceName>
+            {version && (
+              <span className="text-[9px] text-gray-900/30 font-medium shrink-0">
+                v{version}
+              </span>
+            )}
+          </div>
+        </div>
+
+        {/* Summary */}
+        {mode === "full" && summary && (
+          <div
+            className="mt-1 text-[9px] text-gray-950/50 leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+
+        {/* Operational row: delivery guarantee + protocol pills */}
+        {(deliveryGuarantee || protocols?.[0]) && (
+          <div className="flex items-center gap-1 flex-wrap mt-2">
+            {deliveryGuarantee && (
+              <span
+                className="inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-wide rounded-full px-1.5 py-0.5"
+                style={{
+                  background: `rgba(${guarantee.rgb}, 0.12)`,
+                  color: guarantee.hex,
+                }}
+              >
+                <GuaranteeDot guarantee={deliveryGuarantee} size={5} />
+                {DELIVERY_GUARANTEE_LABELS[deliveryGuarantee] ||
+                  deliveryGuarantee}
+              </span>
+            )}
+            {protocols?.[0] && (
+              <span className="inline-flex items-center text-[7px] font-semibold text-gray-900/50 bg-gray-900/10 rounded-full px-1.5 py-0.5 uppercase tracking-wide">
+                {protocols[0]}
+              </span>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function DefaultChannel(props: ChannelNode) {
+  const { data } = props;
+  const {
+    version,
+    name,
+    summary,
+    deprecated,
+    draft,
+    protocols = EMPTY_ARRAY,
+    address,
+    notes,
+    deliveryGuarantee,
+    styles,
+  } = data.channel;
+  const mode = props.data.mode || "simple";
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+  const owners = useMemo(
+    () => normalizeOwners(data.channel?.owners),
+    [data.channel?.owners],
+  );
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const isDark = useDarkMode();
+  const deprecatedStripe = isDark
+    ? "rgba(239,68,68,0.25)"
+    : "rgba(239,68,68,0.1)";
+  const guarantee = getGuarantee(deliveryGuarantee);
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible",
+        props?.selected ? "ring-2 ring-gray-400/60 ring-offset-2" : "",
+        deprecated
+          ? "border-dashed border-red-500"
+          : draft
+            ? `border-dashed ${isDark ? "border-gray-400" : "border-gray-400/60"}`
+            : isDark
+              ? "border-gray-400"
+              : "border-gray-500",
+      )}
+      style={{
+        background: deprecated
+          ? `repeating-linear-gradient(135deg, transparent, transparent 6px, ${deprecatedStripe} 6px, ${deprecatedStripe} 7px), var(--ec-channel-node-bg, rgb(var(--ec-card-bg)))`
+          : draft
+            ? `repeating-linear-gradient(135deg, transparent, transparent 4px, ${isDark ? "rgba(107,114,128,0.25)" : "rgba(107,114,128,0.15)"} 4px, ${isDark ? "rgba(107,114,128,0.25)" : "rgba(107,114,128,0.15)"} 4.5px), repeating-linear-gradient(45deg, transparent, transparent 4px, ${isDark ? "rgba(107,114,128,0.25)" : "rgba(107,114,128,0.15)"} 4px, ${isDark ? "rgba(107,114,128,0.25)" : "rgba(107,114,128,0.15)"} 4.5px), var(--ec-channel-node-bg, rgb(var(--ec-card-bg)))`
+            : "var(--ec-channel-node-bg, rgb(var(--ec-card-bg)))",
+        boxShadow: "0 2px 12px rgba(107, 114, 128, 0.15)",
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {targetConnections.length > 0 && <GlowHandle side="left" />}
+      {sourceConnections.length > 0 && <GlowHandle side="right" />}
+
+      {/* Type badge top-left */}
+      <div className="absolute -top-2.5 left-2.5 z-10">
+        <span
+          className={classNames(
+            "inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm",
+            deprecated ? "bg-red-500" : "bg-gray-500",
+          )}
+        >
+          <ArrowRightLeft className="w-2.5 h-2.5" strokeWidth={2.5} />
+          Channel{draft && " (Draft)"}
+          {deprecated && " (Deprecated)"}
+        </span>
+      </div>
+      {/* Protocol badge top-right — removed, now in operational row */}
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        {/* Name + version */}
+        <div className="flex items-center gap-2">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className={
+                mode === "full"
+                  ? "w-5 h-5 shrink-0 mt-0.5"
+                  : "w-4 h-4 shrink-0 -my-1"
+              }
+            />
+          )}
+          <div className="flex items-baseline gap-1.5 min-w-0">
+            <TruncatedResourceName
+              value={name}
+              tooltipBorderColor="#6b7280"
+              className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+            >
+              {name}
+            </TruncatedResourceName>
+            {version && (
+              <span
+                className="text-[9px] font-normal shrink-0"
+                style={{
+                  color: "rgb(var(--ec-page-text-muted))",
+                  opacity: 0.5,
+                }}
+              >
+                v{version}
+              </span>
+            )}
+          </div>
+        </div>
+
+        {/* Summary */}
+        {mode === "full" && summary && (
+          <div
+            className="mt-1 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed overflow-hidden"
+            style={{ ...LINE_CLAMP_STYLE, marginBottom: 4 }}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+
+        {/* Address */}
+        {mode === "full" && address && (
+          <div className="flex items-center gap-1 mt-1">
+            <Link className="w-2.5 h-2.5 text-[rgb(var(--ec-page-text-muted))]" />
+            <span className="text-[8px] text-[rgb(var(--ec-page-text-muted))] font-mono">
+              {address}
+            </span>
+          </div>
+        )}
+
+        {/* Operational row: delivery guarantee + protocol pills */}
+        {(deliveryGuarantee || protocols?.[0]) && (
+          <div className="flex items-center gap-1 flex-wrap mt-2">
+            {deliveryGuarantee && (
+              <span
+                className="inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-wide rounded-full px-1.5 py-0.5"
+                style={{
+                  background: `rgba(${guarantee.rgb}, 0.08)`,
+                  color: guarantee.hex,
+                }}
+              >
+                <GuaranteeDot guarantee={deliveryGuarantee} size={5} />
+                {DELIVERY_GUARANTEE_LABELS[deliveryGuarantee] ||
+                  deliveryGuarantee}
+              </span>
+            )}
+            {protocols?.[0] && (
+              <span
+                className="inline-flex items-center text-[7px] font-semibold rounded-full px-1.5 py-0.5 uppercase tracking-wide"
+                style={{
+                  background: isDark
+                    ? "rgba(255,255,255,0.08)"
+                    : "rgba(107,114,128,0.1)",
+                  color: "rgb(var(--ec-page-text-muted))",
+                }}
+              >
+                {protocols[0]}
+              </span>
+            )}
+          </div>
+        )}
+
+        {/* Owners */}
+        <OwnerIndicator
+          owners={owners}
+          accentColor="bg-gray-400"
+          borderColor="rgba(107,114,128,0.08)"
+          iconClass="text-gray-300"
+        />
+      </div>
+    </div>
+  );
+}
+
+export default memo(function Channel(props: ChannelNode) {
+  const nodeStyle = props?.data?.style;
+
+  if (nodeStyle === "post-it") {
+    return <PostItChannel {...props} />;
+  }
+
+  return <DefaultChannel {...props} />;
+});
diff --git a/packages/visualiser/src/nodes/channel/index.ts b/packages/visualiser/src/nodes/channel/index.ts
new file mode 100644
index 000000000..f8242e2d0
--- /dev/null
+++ b/packages/visualiser/src/nodes/channel/index.ts
@@ -0,0 +1,2 @@
+export { default as Channel } from "./ChannelNode";
+export type { ChannelNode } from "./ChannelNode";
diff --git a/packages/visualiser/src/nodes/command/CommandNode.tsx b/packages/visualiser/src/nodes/command/CommandNode.tsx
new file mode 100644
index 000000000..83479476f
--- /dev/null
+++ b/packages/visualiser/src/nodes/command/CommandNode.tsx
@@ -0,0 +1,344 @@
+import { memo, useMemo } from "react";
+import { MessageSquare } from "lucide-react";
+import {
+  OwnerIndicator,
+  normalizeOwners,
+  HIDDEN_HANDLE_STYLE,
+} from "../OwnerIndicator";
+import { Node, Handle, Position, useNodeConnections } from "@xyflow/react";
+import { Message, EventCatalogResource } from "../../types";
+import { NotesIndicator } from "../NotesIndicator";
+import { MethodBadge, ApiPath, StatusCodes } from "../ApiInfo";
+import { CustomIcon, isIconPath } from "../../utils/custom-icon";
+import {
+  LINE_CLAMP_STYLE,
+  FOLDED_CORNER_SHADOW_STYLE,
+  useDarkMode,
+} from "../shared-styles";
+import { TruncatedResourceName } from "../TruncatedResourceName";
+
+const GlowHandle = memo(function GlowHandle({
+  side,
+}: {
+  side: "left" | "right";
+}) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: "linear-gradient(135deg, #3b82f6, #1d4ed8)",
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: "ec-command-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none",
+      }}
+    />
+  );
+});
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+type CommandNodeData = EventCatalogResource & {
+  message: Message;
+};
+
+export type CommandNode = Node<CommandNodeData, "command">;
+
+function PostItCommand(props: CommandNode) {
+  const { version, name, summary, deprecated, draft, notes, styles } =
+    props.data.message;
+  const mode = props.data.mode || "simple";
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-44 max-w-56 min-h-[120px]",
+        props?.selected ? "ring-2 ring-blue-400/60 ring-offset-1" : "",
+      )}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      <div
+        className="absolute inset-0"
+        style={{
+          background:
+            "linear-gradient(135deg, #bfdbfe 0%, #93c5fd 40%, #3b82f6 100%)",
+          boxShadow:
+            "1px 1px 3px rgba(0,0,0,0.15), 3px 4px 8px rgba(0,0,0,0.08)",
+          transform: "rotate(-1deg)",
+          border: deprecated
+            ? "2px dashed rgba(239, 68, 68, 0.5)"
+            : draft
+              ? "2px dashed rgba(59, 130, 246, 0.5)"
+              : "none",
+        }}
+      >
+        {/* Folded corner */}
+        <div style={FOLDED_CORNER_SHADOW_STYLE} />
+        <div
+          style={{
+            position: "absolute",
+            top: 0,
+            right: 0,
+            width: 0,
+            height: 0,
+            borderStyle: "solid",
+            borderWidth: "18px 0 0 18px",
+            borderColor: "#1d4ed8 transparent transparent transparent",
+            opacity: 0.3,
+          }}
+        />
+      </div>
+
+      <div className="relative px-3.5 py-3">
+        <div className="flex items-center justify-between mb-2">
+          <div className="flex items-center gap-1">
+            <MessageSquare
+              className="w-3 h-3 text-blue-900/50"
+              strokeWidth={2.5}
+            />
+            <span className="text-[8px] font-bold text-blue-900/50 uppercase tracking-widest">
+              Command
+            </span>
+          </div>
+          {draft && (
+            <span className="text-[8px] font-extrabold text-amber-900 bg-amber-100 border border-dashed border-amber-400 px-1.5 py-0.5 rounded uppercase">
+              Draft
+            </span>
+          )}
+          {deprecated && (
+            <span className="text-[7px] font-bold text-white bg-red-500 border border-red-600 px-1.5 py-0.5 rounded uppercase">
+              Deprecated
+            </span>
+          )}
+        </div>
+
+        <div className="flex items-center gap-2">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className={
+                mode === "full"
+                  ? "w-5 h-5 shrink-0 mt-0.5"
+                  : "w-4 h-4 shrink-0 -my-1"
+              }
+            />
+          )}
+          <TruncatedResourceName
+            as="div"
+            value={name}
+            tooltipBorderColor="#3b82f6"
+            className={classNames(
+              "text-[13px] font-bold leading-snug min-w-0 truncate",
+              deprecated ? "text-blue-950/40 line-through" : "text-blue-950",
+            )}
+          >
+            {name}
+          </TruncatedResourceName>
+        </div>
+
+        {version && (
+          <div className="text-[9px] text-blue-900/40 font-semibold mt-0.5">
+            v{version}
+          </div>
+        )}
+
+        {mode === "full" && summary && (
+          <div
+            className="mt-2 pt-1.5 border-t border-blue-900/10 text-[9px] text-blue-950/60 leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function DefaultCommand(props: CommandNode) {
+  const {
+    version,
+    name,
+    summary,
+    deprecated,
+    draft,
+    schema,
+    notes,
+    method,
+    path,
+    statusCodes,
+    styles,
+  } = props.data.message;
+  const mode = props.data.mode || "simple";
+  const hasApiInfo = !!(method || path);
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+  const owners = useMemo(
+    () => normalizeOwners(props.data.message?.owners),
+    [props.data.message?.owners],
+  );
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const isDark = useDarkMode();
+  const deprecatedStripe = isDark
+    ? "rgba(239,68,68,0.25)"
+    : "rgba(239,68,68,0.1)";
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible",
+        props?.selected ? "ring-2 ring-blue-400/60 ring-offset-2" : "",
+        deprecated
+          ? "border-dashed border-red-500"
+          : draft
+            ? `border-dashed ${isDark ? "border-blue-400" : "border-blue-400/60"}`
+            : "border-blue-500",
+      )}
+      style={{
+        background: deprecated
+          ? `repeating-linear-gradient(135deg, transparent, transparent 6px, ${deprecatedStripe} 6px, ${deprecatedStripe} 7px), var(--ec-command-node-bg, rgb(var(--ec-card-bg)))`
+          : draft
+            ? `repeating-linear-gradient(135deg, transparent, transparent 4px, ${isDark ? "rgba(59,130,246,0.25)" : "rgba(59,130,246,0.15)"} 4px, ${isDark ? "rgba(59,130,246,0.25)" : "rgba(59,130,246,0.15)"} 4.5px), repeating-linear-gradient(45deg, transparent, transparent 4px, ${isDark ? "rgba(59,130,246,0.25)" : "rgba(59,130,246,0.15)"} 4px, ${isDark ? "rgba(59,130,246,0.25)" : "rgba(59,130,246,0.15)"} 4.5px), var(--ec-command-node-bg, rgb(var(--ec-card-bg)))`
+            : "var(--ec-command-node-bg, rgb(var(--ec-card-bg)))",
+        boxShadow: "0 2px 12px rgba(59, 130, 246, 0.15)",
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {targetConnections.length > 0 && <GlowHandle side="left" />}
+      {sourceConnections.length > 0 && <GlowHandle side="right" />}
+
+      {/* Type badge top-left */}
+      <div className="absolute -top-2.5 left-2.5 z-10">
+        <span
+          className={classNames(
+            "inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm",
+            deprecated ? "bg-red-500" : "bg-blue-500",
+          )}
+        >
+          <MessageSquare className="w-2.5 h-2.5" strokeWidth={2.5} />
+          Command{draft && " (Draft)"}
+          {deprecated && " (Deprecated)"}
+        </span>
+      </div>
+      {/* Schema badge top-right */}
+      {schema && (
+        <span
+          className="z-10 text-[7px] font-semibold text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-card-bg))] border border-blue-500 rounded-full px-1.5 py-0.5 uppercase tracking-wide"
+          style={{ position: "absolute", top: -8, right: 10 }}
+        >
+          {schema.includes(".") ? schema.split(".").pop() : schema}
+        </span>
+      )}
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        {/* API method + path row */}
+        {hasApiInfo && (
+          <div className="flex items-center gap-1.5 mb-1 overflow-hidden min-w-0">
+            {method && <MethodBadge method={method} />}
+            {path && <ApiPath path={path} />}
+          </div>
+        )}
+
+        {/* Name + version */}
+        {!hasApiInfo && (
+          <div className="flex items-center gap-2">
+            {customIcon && (
+              <CustomIcon
+                src={customIcon}
+                alt={name}
+                className={
+                  mode === "full"
+                    ? "w-5 h-5 shrink-0 mt-0.5"
+                    : "w-4 h-4 shrink-0 -my-1"
+                }
+              />
+            )}
+            <div className="flex items-baseline gap-1 min-w-0">
+              <TruncatedResourceName
+                value={name}
+                tooltipBorderColor="#3b82f6"
+                className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+              >
+                {name}
+              </TruncatedResourceName>
+              {version && (
+                <span className="text-[10px] font-normal text-[rgb(var(--ec-page-text-muted))] shrink-0">
+                  (v{version})
+                </span>
+              )}
+            </div>
+          </div>
+        )}
+
+        {/* Summary */}
+        {mode === "full" && summary && (
+          <div
+            className="mt-1.5 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+
+        {/* Status codes */}
+        {statusCodes && statusCodes.length > 0 && (
+          <StatusCodes codes={statusCodes} />
+        )}
+
+        {/* Owners */}
+        <OwnerIndicator
+          owners={owners}
+          accentColor="bg-blue-400"
+          borderColor="rgba(59,130,246,0.08)"
+          iconClass="text-blue-300"
+        />
+      </div>
+    </div>
+  );
+}
+
+export default memo(function Command(props: CommandNode) {
+  const nodeStyle = props?.data?.style;
+
+  if (nodeStyle === "post-it") {
+    return <PostItCommand {...props} />;
+  }
+
+  return <DefaultCommand {...props} />;
+});
diff --git a/packages/visualiser/src/nodes/command/index.ts b/packages/visualiser/src/nodes/command/index.ts
new file mode 100644
index 000000000..8551fbea2
--- /dev/null
+++ b/packages/visualiser/src/nodes/command/index.ts
@@ -0,0 +1,2 @@
+export { default as Command } from "./CommandNode";
+export type { CommandNode } from "./CommandNode";
diff --git a/packages/visualiser/src/nodes/data/DataNode.tsx b/packages/visualiser/src/nodes/data/DataNode.tsx
new file mode 100644
index 000000000..0859911b1
--- /dev/null
+++ b/packages/visualiser/src/nodes/data/DataNode.tsx
@@ -0,0 +1,360 @@
+import { memo, useMemo } from "react";
+import { Database } from "lucide-react";
+import {
+  OwnerIndicator,
+  normalizeOwners,
+  HIDDEN_HANDLE_STYLE,
+} from "../OwnerIndicator";
+import { Node, Handle, Position, useNodeConnections } from "@xyflow/react";
+import { EventCatalogResource, Data as DataType } from "../../types";
+import { NotesIndicator } from "../NotesIndicator";
+import {
+  LINE_CLAMP_STYLE,
+  FOLDED_CORNER_SHADOW_STYLE,
+  EMPTY_ARRAY,
+  useDarkMode,
+} from "../shared-styles";
+import { CustomIcon, isIconPath } from "../../utils/custom-icon";
+import { TruncatedResourceName } from "../TruncatedResourceName";
+
+function GlowHandle({ side }: { side: "left" | "right" }) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: "linear-gradient(135deg, #6366f1, #4f46e5)",
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: "ec-data-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none",
+      }}
+    />
+  );
+}
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+const CONTAINER_TYPE_LABELS: Record<string, string> = {
+  database: "Database",
+  cache: "Cache",
+  objectStore: "Object Store",
+  searchIndex: "Search Index",
+  dataWarehouse: "Data Warehouse",
+  dataLake: "Data Lake",
+  externalSaaS: "External SaaS",
+  other: "Other",
+};
+
+function getDataNodeTypeLabel(
+  containerType: string | undefined,
+  type: string | undefined,
+): string {
+  if (containerType) {
+    return CONTAINER_TYPE_LABELS[containerType] ?? containerType;
+  }
+  return type ?? "Database";
+}
+
+type DataNodeData = EventCatalogResource & {
+  data: DataType;
+};
+
+export type DataNode = Node<DataNodeData, "data">;
+
+function PostItData(props: DataNode) {
+  const {
+    version,
+    owners = EMPTY_ARRAY,
+    schemas = EMPTY_ARRAY,
+    name,
+    summary,
+    deprecated,
+    draft,
+    notes,
+    styles,
+  } = props.data.data;
+  const mode = props.data.mode || "simple";
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-44 max-w-56 min-h-[120px]",
+        props?.selected ? "ring-2 ring-indigo-400/60 ring-offset-1" : "",
+      )}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {/* Inner wrapper with rotation */}
+      <div
+        className="absolute inset-0"
+        style={{
+          background:
+            "linear-gradient(135deg, #c7d2fe 0%, #a5b4fc 40%, #6366f1 100%)",
+          boxShadow:
+            "1px 1px 3px rgba(0,0,0,0.15), 3px 4px 8px rgba(0,0,0,0.08)",
+          transform: "rotate(-1deg)",
+          border: deprecated
+            ? "2px dashed rgba(239, 68, 68, 0.5)"
+            : draft
+              ? "2px dashed rgba(99, 102, 241, 0.5)"
+              : "none",
+        }}
+      >
+        {/* Folded corner */}
+        <div style={FOLDED_CORNER_SHADOW_STYLE} />
+        <div
+          style={{
+            position: "absolute",
+            top: 0,
+            right: 0,
+            width: 0,
+            height: 0,
+            borderStyle: "solid",
+            borderWidth: "18px 0 0 18px",
+            borderColor: "#4f46e5 transparent transparent transparent",
+            opacity: 0.3,
+          }}
+        />
+      </div>
+
+      {/* Content sits on top, unrotated */}
+      <div className="relative px-3.5 py-3">
+        {/* Type label row */}
+        <div className="flex items-center justify-between mb-2">
+          <div className="flex items-center gap-1">
+            <Database
+              className="w-3 h-3 text-indigo-950/50"
+              strokeWidth={2.5}
+            />
+            <span className="text-[8px] font-bold text-indigo-950/50 uppercase tracking-widest">
+              Data
+            </span>
+          </div>
+          {draft && (
+            <span className="text-[8px] font-extrabold text-amber-900 bg-amber-100 border border-dashed border-amber-400 px-1.5 py-0.5 rounded uppercase">
+              Draft
+            </span>
+          )}
+          {deprecated && (
+            <span className="text-[7px] font-bold text-white bg-red-500 border border-red-600 px-1.5 py-0.5 rounded uppercase">
+              Deprecated
+            </span>
+          )}
+        </div>
+
+        {/* Name */}
+        <div className="flex items-center gap-2">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className={
+                mode === "full"
+                  ? "w-5 h-5 shrink-0 mt-0.5"
+                  : "w-4 h-4 shrink-0 -my-1"
+              }
+            />
+          )}
+          <TruncatedResourceName
+            as="div"
+            value={name}
+            tooltipBorderColor="#6366f1"
+            className={classNames(
+              "text-[13px] font-bold leading-snug min-w-0 truncate",
+              deprecated
+                ? "text-indigo-950/40 line-through"
+                : "text-indigo-950",
+            )}
+          >
+            {name}
+          </TruncatedResourceName>
+        </div>
+
+        {/* Version */}
+        {version && (
+          <div className="text-[9px] text-indigo-950/40 font-semibold mt-0.5">
+            v{version}
+          </div>
+        )}
+
+        {/* Summary */}
+        {mode === "full" && summary && (
+          <div
+            className="mt-2 pt-1.5 border-t border-indigo-950/10 text-[9px] text-indigo-950/60 leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function DefaultData(props: DataNode) {
+  const {
+    version,
+    owners = EMPTY_ARRAY,
+    schemas = EMPTY_ARRAY,
+    name,
+    summary,
+    type,
+    container_type,
+    deprecated,
+    draft,
+    notes,
+    styles,
+  } = props.data.data;
+  const typeLabel = getDataNodeTypeLabel(container_type, type);
+
+  const mode = props.data.mode || "simple";
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+  const ownersNormalized = useMemo(() => normalizeOwners(owners), [owners]);
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const isDark = useDarkMode();
+  const deprecatedStripe = isDark
+    ? "rgba(239,68,68,0.25)"
+    : "rgba(239,68,68,0.1)";
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible",
+        props?.selected ? "ring-2 ring-indigo-400/60 ring-offset-2" : "",
+        deprecated
+          ? "border-dashed border-red-500"
+          : draft
+            ? `border-dashed ${isDark ? "border-indigo-400" : "border-indigo-400/60"}`
+            : "border-indigo-500",
+      )}
+      style={{
+        background: deprecated
+          ? `repeating-linear-gradient(135deg, transparent, transparent 6px, ${deprecatedStripe} 6px, ${deprecatedStripe} 7px), var(--ec-data-node-bg, rgb(var(--ec-card-bg)))`
+          : draft
+            ? `repeating-linear-gradient(135deg, transparent, transparent 4px, ${isDark ? "rgba(99,102,241,0.25)" : "rgba(99,102,241,0.15)"} 4px, ${isDark ? "rgba(99,102,241,0.25)" : "rgba(99,102,241,0.15)"} 4.5px), repeating-linear-gradient(45deg, transparent, transparent 4px, ${isDark ? "rgba(99,102,241,0.25)" : "rgba(99,102,241,0.15)"} 4px, ${isDark ? "rgba(99,102,241,0.25)" : "rgba(99,102,241,0.15)"} 4.5px), var(--ec-data-node-bg, rgb(var(--ec-card-bg)))`
+            : "var(--ec-data-node-bg, rgb(var(--ec-card-bg)))",
+        boxShadow: "0 2px 12px rgba(99, 102, 241, 0.15)",
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {targetConnections.length > 0 && <GlowHandle side="left" />}
+      {sourceConnections.length > 0 && <GlowHandle side="right" />}
+
+      {/* Type badge top-left */}
+      <div className="absolute -top-2.5 left-2.5 z-10">
+        <span
+          className={classNames(
+            "inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm",
+            deprecated ? "bg-red-500" : "bg-indigo-500",
+          )}
+        >
+          <Database className="w-2.5 h-2.5" strokeWidth={2.5} />
+          Data{draft && " (Draft)"}
+          {deprecated && " (Deprecated)"}
+        </span>
+      </div>
+      {typeLabel && (
+        <span
+          className="z-10 text-[7px] font-semibold text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-card-bg))] border border-indigo-500 rounded-full px-1.5 py-0.5 uppercase tracking-wide"
+          style={{ position: "absolute", top: -8, right: 10 }}
+        >
+          {typeLabel}
+        </span>
+      )}
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        {/* Name + version */}
+        <div className="flex items-center gap-2">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className={
+                mode === "full"
+                  ? "w-5 h-5 shrink-0 mt-0.5"
+                  : "w-4 h-4 shrink-0 -my-1"
+              }
+            />
+          )}
+          <div className="flex items-baseline gap-1 min-w-0">
+            <TruncatedResourceName
+              value={name}
+              tooltipBorderColor="#6366f1"
+              className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+            >
+              {name}
+            </TruncatedResourceName>
+            {version && (
+              <span className="text-[10px] font-normal text-[rgb(var(--ec-page-text-muted))] shrink-0">
+                (v{version})
+              </span>
+            )}
+          </div>
+        </div>
+
+        {/* Summary */}
+        {mode === "full" && summary && (
+          <div
+            className="mt-1.5 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+
+        {/* Owners */}
+        <OwnerIndicator
+          owners={ownersNormalized}
+          accentColor="bg-indigo-400"
+          borderColor="rgba(99,102,241,0.08)"
+          iconClass="text-indigo-300"
+        />
+      </div>
+    </div>
+  );
+}
+
+export default memo(function Data(props: DataNode) {
+  const nodeStyle = props?.data?.style;
+
+  if (nodeStyle === "post-it") {
+    return <PostItData {...props} />;
+  }
+
+  return <DefaultData {...props} />;
+});
diff --git a/packages/visualiser/src/nodes/data/config.ts b/packages/visualiser/src/nodes/data/config.ts
new file mode 100644
index 000000000..9768f252c
--- /dev/null
+++ b/packages/visualiser/src/nodes/data/config.ts
@@ -0,0 +1,83 @@
+import { Connection, MarkerType } from "@xyflow/react";
+import { Database } from "lucide-react";
+import { NodeConfiguration } from "../../types";
+import { SERVICE, CHANNEL, ACTOR } from "../node-types";
+
+export default {
+  type: "data",
+  icon: Database,
+  color: "indigo",
+  targetCanConnectTo: [...SERVICE, ...CHANNEL, "external-system", ...ACTOR],
+  sourceCanConnectTo: [...SERVICE, ...CHANNEL, "external-system", ...ACTOR],
+  validateConnection: (connection: Connection) => {
+    return connection.source !== connection.target;
+  },
+  getEdgeOptions: (connection: Connection) => {
+    if (connection.source === "data" && connection.target === "service") {
+      return {
+        label: "Provides data to",
+        markerEnd: { type: MarkerType.ArrowClosed, color: "#000000" },
+      };
+    }
+    if (connection.source === "service" && connection.target === "data") {
+      return {
+        label: "Stores data in",
+        markerEnd: { type: MarkerType.ArrowClosed, color: "#000000" },
+      };
+    }
+    return {
+      label: "Connected to",
+      markerEnd: { type: MarkerType.ArrowClosed, color: "#000000" },
+    };
+  },
+  defaultData: {
+    name: "New Database",
+    version: "0.0.1",
+    summary: "New data store. Click edit to change the details.",
+    type: "Database",
+    mode: "full",
+  },
+  editor: {
+    title: "Data Store",
+    subtitle: "Edit the details of the data store",
+    schema: {
+      type: "object",
+      required: ["name", "version"],
+      properties: {
+        name: {
+          type: "string",
+          title: "Name",
+          default: "UserDatabase",
+          description: "The name of the data store",
+        },
+        version: {
+          type: "string",
+          title: "Version",
+          default: "1.0.0",
+          description: "The version number (e.g., 1.0.0)",
+          pattern: "^\\d+\\.\\d+\\.\\d+(?:-[\\w.-]+)?(?:\\+[\\w.-]+)?$",
+        },
+        summary: {
+          type: "string",
+          title: "Summary",
+          default: "",
+          description: "A brief summary of the data store",
+        },
+        type: {
+          type: "string",
+          title: "Type",
+          default: "Database",
+          description: "The type of data store (Database, Cache, Queue, etc.)",
+          enum: [
+            "Database",
+            "Cache",
+            "Queue",
+            "File System",
+            "Data Lake",
+            "Data Warehouse",
+          ],
+        },
+      },
+    },
+  },
+} as NodeConfiguration;
diff --git a/packages/visualiser/src/nodes/data/index.ts b/packages/visualiser/src/nodes/data/index.ts
new file mode 100644
index 000000000..68bbb0e91
--- /dev/null
+++ b/packages/visualiser/src/nodes/data/index.ts
@@ -0,0 +1,3 @@
+export { default as Data } from "./DataNode";
+export type { DataNode } from "./DataNode";
+export { default as dataNodeConfig } from "./config";
diff --git a/packages/visualiser/src/nodes/event/EventNode.tsx b/packages/visualiser/src/nodes/event/EventNode.tsx
new file mode 100644
index 000000000..f5682b683
--- /dev/null
+++ b/packages/visualiser/src/nodes/event/EventNode.tsx
@@ -0,0 +1,357 @@
+import { memo, useMemo } from "react";
+import { Zap } from "lucide-react";
+import {
+  OwnerIndicator,
+  normalizeOwners,
+  HIDDEN_HANDLE_STYLE,
+} from "../OwnerIndicator";
+import { Node, Handle, Position, useNodeConnections } from "@xyflow/react";
+import { Message, EventCatalogResource } from "../../types";
+import { NotesIndicator } from "../NotesIndicator";
+import { MethodBadge, ApiPath, StatusCodes } from "../ApiInfo";
+import {
+  LINE_CLAMP_STYLE,
+  FOLDED_CORNER_SHADOW_STYLE,
+  useDarkMode,
+} from "../shared-styles";
+import { CustomIcon, isIconPath } from "../../utils/custom-icon";
+import { TruncatedResourceName } from "../TruncatedResourceName";
+
+const GlowHandle = memo(function GlowHandle({
+  side,
+}: {
+  side: "left" | "right";
+}) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: "linear-gradient(135deg, #fb923c, #ea580c)",
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: "ec-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none",
+      }}
+    />
+  );
+});
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+type MessageNodeData = EventCatalogResource & {
+  message: Message;
+};
+
+export type EventNode = Node<MessageNodeData, "event">;
+
+function PostItEvent(props: EventNode) {
+  const { version, name, summary, deprecated, draft, notes, styles } =
+    props?.data?.message;
+  const mode = props?.data?.mode || "simple";
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-44 max-w-56 min-h-[120px]",
+        props?.selected ? "ring-2 ring-orange-400/60 ring-offset-1" : "",
+      )}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {/* Inner wrapper with rotation — keeps handles aligned to the unrotated bounding box */}
+      <div
+        className="absolute inset-0"
+        style={{
+          background:
+            "linear-gradient(135deg, #fed7aa 0%, #fdba74 40%, #fb923c 100%)",
+          boxShadow:
+            "1px 1px 3px rgba(0,0,0,0.15), 3px 4px 8px rgba(0,0,0,0.08)",
+          transform: "rotate(-1deg)",
+          border: deprecated
+            ? "2px dashed rgba(239, 68, 68, 0.5)"
+            : draft
+              ? "2px dashed rgba(251, 146, 60, 0.5)"
+              : "none",
+        }}
+      >
+        {/* Folded corner */}
+        <div style={FOLDED_CORNER_SHADOW_STYLE} />
+        <div
+          style={{
+            position: "absolute",
+            top: 0,
+            right: 0,
+            width: 0,
+            height: 0,
+            borderStyle: "solid",
+            borderWidth: "18px 0 0 18px",
+            borderColor: "#f97316 transparent transparent transparent",
+            opacity: 0.3,
+          }}
+        />
+      </div>
+
+      {/* Content sits on top, unrotated, so text stays crisp */}
+      <div className="relative px-3.5 py-3">
+        {/* Type label row */}
+        <div className="flex items-center justify-between mb-2">
+          <div className="flex items-center gap-1">
+            <Zap className="w-3 h-3 text-orange-900/50" strokeWidth={2.5} />
+            <span className="text-[8px] font-bold text-orange-900/50 uppercase tracking-widest">
+              Event
+            </span>
+          </div>
+          {draft && (
+            <span className="text-[8px] font-extrabold text-amber-900 bg-amber-100 border border-dashed border-amber-400 px-1.5 py-0.5 rounded uppercase">
+              Draft
+            </span>
+          )}
+          {deprecated && (
+            <span className="text-[7px] font-bold text-white bg-red-500 border border-red-600 px-1.5 py-0.5 rounded uppercase">
+              Deprecated
+            </span>
+          )}
+        </div>
+
+        {/* Name */}
+        <div className="flex items-center gap-2">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className={
+                mode === "full"
+                  ? "w-5 h-5 shrink-0 mt-0.5"
+                  : "w-4 h-4 shrink-0 -my-1"
+              }
+            />
+          )}
+          <TruncatedResourceName
+            as="div"
+            value={name}
+            tooltipBorderColor="#f97316"
+            className={classNames(
+              "text-[13px] font-bold leading-snug min-w-0 truncate",
+              deprecated
+                ? "text-orange-950/40 line-through"
+                : "text-orange-950",
+            )}
+          >
+            {name}
+          </TruncatedResourceName>
+        </div>
+
+        {/* Version */}
+        {version && (
+          <div className="text-[9px] text-orange-900/40 font-semibold mt-0.5">
+            v{version}
+          </div>
+        )}
+
+        {/* Summary */}
+        {mode === "full" && summary && (
+          <div
+            className="mt-2 pt-1.5 border-t border-orange-900/10 text-[9px] text-orange-950/60 leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function DefaultEvent(props: EventNode) {
+  const {
+    version,
+    name,
+    summary,
+    deprecated,
+    draft,
+    schema,
+    notes,
+    method,
+    path,
+    statusCodes,
+    styles,
+  } = props?.data?.message;
+  const mode = props?.data?.mode || "simple";
+  const hasApiInfo = !!(method || path);
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+  const owners = useMemo(
+    () => normalizeOwners(props?.data?.message?.owners),
+    [props?.data?.message?.owners],
+  );
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const isDark = useDarkMode();
+  const deprecatedStripe = isDark
+    ? "rgba(239,68,68,0.25)"
+    : "rgba(239,68,68,0.1)";
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible",
+        props?.selected ? "ring-2 ring-orange-400/60 ring-offset-2" : "",
+        deprecated
+          ? "border-dashed border-red-500"
+          : draft
+            ? `border-dashed ${isDark ? "border-orange-400" : "border-orange-400/60"}`
+            : "border-orange-500",
+      )}
+      style={{
+        background: deprecated
+          ? `repeating-linear-gradient(135deg, transparent, transparent 6px, ${deprecatedStripe} 6px, ${deprecatedStripe} 7px), var(--ec-event-node-bg, rgb(var(--ec-card-bg)))`
+          : draft
+            ? `repeating-linear-gradient(135deg, transparent, transparent 4px, ${isDark ? "rgba(251,146,60,0.25)" : "rgba(251,146,60,0.15)"} 4px, ${isDark ? "rgba(251,146,60,0.25)" : "rgba(251,146,60,0.15)"} 4.5px), repeating-linear-gradient(45deg, transparent, transparent 4px, ${isDark ? "rgba(251,146,60,0.25)" : "rgba(251,146,60,0.15)"} 4px, ${isDark ? "rgba(251,146,60,0.25)" : "rgba(251,146,60,0.15)"} 4.5px), var(--ec-event-node-bg, rgb(var(--ec-card-bg)))`
+            : "var(--ec-event-node-bg, rgb(var(--ec-card-bg)))",
+        boxShadow: "0 2px 12px rgba(251, 146, 60, 0.15)",
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {targetConnections.length > 0 && <GlowHandle side="left" />}
+      {sourceConnections.length > 0 && <GlowHandle side="right" />}
+
+      {/* Type badge top-left */}
+      <div className="absolute -top-2.5 left-2.5 z-10">
+        <span
+          className={classNames(
+            "inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm",
+            deprecated ? "bg-red-500" : "bg-orange-500",
+          )}
+        >
+          <Zap className="w-2.5 h-2.5" strokeWidth={2.5} />
+          Event{draft && " (Draft)"}
+          {deprecated && " (Deprecated)"}
+        </span>
+      </div>
+      {/* Schema badge top-right */}
+      {schema && (
+        <span
+          className="z-10 text-[7px] font-semibold text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-card-bg))] border border-orange-500 rounded-full px-1.5 py-0.5 uppercase tracking-wide"
+          style={{ position: "absolute", top: -8, right: 10 }}
+        >
+          {schema.includes(".") ? schema.split(".").pop() : schema}
+        </span>
+      )}
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        {/* API method + path row */}
+        {hasApiInfo && (
+          <div className="flex items-center gap-1.5 mb-1 overflow-hidden min-w-0">
+            {method && <MethodBadge method={method} />}
+            {path && <ApiPath path={path} />}
+          </div>
+        )}
+
+        {/* Name + version */}
+        {!hasApiInfo && (
+          <div className="flex items-center gap-2">
+            {customIcon && (
+              <CustomIcon
+                src={customIcon}
+                alt={name}
+                className={
+                  mode === "full"
+                    ? "w-5 h-5 shrink-0 mt-0.5"
+                    : "w-4 h-4 shrink-0 -my-1"
+                }
+              />
+            )}
+            <div className="flex items-baseline gap-1 min-w-0">
+              <TruncatedResourceName
+                value={name}
+                tooltipBorderColor="#f97316"
+                className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+              >
+                {name}
+              </TruncatedResourceName>
+              {version && (
+                <span
+                  className="text-[10px] font-normal shrink-0"
+                  style={{ color: isDark ? "#dce3eb" : "#6b7280" }}
+                >
+                  (v{version})
+                </span>
+              )}
+            </div>
+          </div>
+        )}
+
+        {/* Summary */}
+        {mode === "full" && summary && (
+          <div
+            className="mt-1.5 text-[9px] leading-relaxed overflow-hidden"
+            style={{
+              ...LINE_CLAMP_STYLE,
+              color: isDark ? "#f0f4f8" : "#374151",
+            }}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+
+        {/* Status codes */}
+        {statusCodes && statusCodes.length > 0 && (
+          <StatusCodes codes={statusCodes} />
+        )}
+
+        {/* Owners + Notes row */}
+        <div className="flex items-end justify-between">
+          <OwnerIndicator
+            owners={owners}
+            accentColor="bg-orange-400"
+            borderColor="rgba(251,146,60,0.08)"
+            iconClass="text-orange-300"
+          />
+          {notes && notes.length > 0 && (
+            <NotesIndicator notes={notes} resourceName={name} />
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default memo(function Event(props: EventNode) {
+  const nodeStyle = props?.data?.style;
+
+  if (nodeStyle === "post-it") {
+    return <PostItEvent {...props} />;
+  }
+
+  return <DefaultEvent {...props} />;
+});
diff --git a/packages/visualiser/src/nodes/event/config.ts b/packages/visualiser/src/nodes/event/config.ts
new file mode 100644
index 000000000..10e28384e
--- /dev/null
+++ b/packages/visualiser/src/nodes/event/config.ts
@@ -0,0 +1,66 @@
+import { Connection, MarkerType } from "@xyflow/react";
+import { Zap } from "lucide-react";
+import { NodeConfiguration } from "../../types";
+import { SERVICE, CHANNEL, EVENT } from "../node-types";
+
+export default {
+  type: "event",
+  icon: Zap,
+  color: "orange",
+  targetCanConnectTo: [...SERVICE, ...CHANNEL],
+  sourceCanConnectTo: [...SERVICE, ...CHANNEL],
+  validateConnection: (connection: Connection) => {
+    return connection.source !== connection.target;
+  },
+  getEdgeOptions: (connection: Connection) => {
+    if (
+      EVENT.includes(connection.source) &&
+      SERVICE.includes(connection.target)
+    ) {
+      return {
+        label: "Publishes",
+        markerEnd: { type: MarkerType.ArrowClosed, color: "#000000" },
+      };
+    }
+    return {
+      label: "Subscribes",
+      markerEnd: { type: MarkerType.ArrowClosed, color: "#000000" },
+    };
+  },
+  defaultData: {
+    name: "New Event",
+    version: "0.0.1",
+    summary: "New event. Click edit to change the details.",
+    mode: "full",
+  },
+  editor: {
+    title: "Event",
+    subtitle: "Edit the details of the event",
+    schema: {
+      type: "object",
+      required: ["name", "version"],
+      properties: {
+        name: {
+          type: "string",
+          title: "Name",
+          default: "Random value",
+          description:
+            "The name of the event. Use a verb-noun format (e.g., OrderPlaced).",
+        },
+        version: {
+          type: "string",
+          title: "Version",
+          default: "1.0.0",
+          description: "The version number (e.g., 1.0.0)",
+          pattern: "^\\d+\\.\\d+\\.\\d+(?:-[\\w.-]+)?(?:\\+[\\w.-]+)?$",
+        },
+        summary: {
+          type: "string",
+          title: "Summary",
+          default: "",
+          description: "A brief summary of the event",
+        },
+      },
+    },
+  },
+} as NodeConfiguration;
diff --git a/packages/visualiser/src/nodes/event/index.ts b/packages/visualiser/src/nodes/event/index.ts
new file mode 100644
index 000000000..d44f0fc54
--- /dev/null
+++ b/packages/visualiser/src/nodes/event/index.ts
@@ -0,0 +1,3 @@
+export { default as Event } from "./EventNode";
+export { default as eventConfig } from "./config";
+export type { EventNode } from "./EventNode";
diff --git a/packages/visualiser/src/nodes/external-system/ExternalSystem.tsx b/packages/visualiser/src/nodes/external-system/ExternalSystem.tsx
new file mode 100644
index 000000000..a6d706625
--- /dev/null
+++ b/packages/visualiser/src/nodes/external-system/ExternalSystem.tsx
@@ -0,0 +1,263 @@
+import { memo } from "react";
+import { Globe } from "lucide-react";
+import { Node, Handle, Position, useNodeConnections } from "@xyflow/react";
+import {
+  EventCatalogResource,
+  ExternalSystem as ExternalSystemType,
+} from "../../types";
+import { NotesIndicator } from "../NotesIndicator";
+import { HIDDEN_HANDLE_STYLE } from "../OwnerIndicator";
+import {
+  LINE_CLAMP_STYLE,
+  FOLDED_CORNER_SHADOW_STYLE,
+  useDarkMode,
+} from "../shared-styles";
+import { TruncatedResourceName } from "../TruncatedResourceName";
+
+function GlowHandle({ side }: { side: "left" | "right" }) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: "linear-gradient(135deg, #a855f7, #7e22ce)",
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: "ec-external-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none",
+      }}
+    />
+  );
+}
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+type ExternalSystemNodeData = EventCatalogResource & {
+  externalSystem: ExternalSystemType & {
+    deprecated?: boolean;
+    draft?: boolean;
+  };
+};
+
+export type ExternalSystemNode = Node<
+  ExternalSystemNodeData,
+  "external-system"
+>;
+
+function PostItExternalSystem(props: ExternalSystemNode) {
+  const { version, name, summary, deprecated, draft, notes } =
+    props.data.externalSystem;
+  const mode = props.data.mode || "simple";
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-44 max-w-56 min-h-[120px]",
+        props?.selected ? "ring-2 ring-purple-400/60 ring-offset-1" : "",
+      )}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      <div
+        className="absolute inset-0"
+        style={{
+          background:
+            "linear-gradient(135deg, #e9d5ff 0%, #c084fc 40%, #a855f7 100%)",
+          boxShadow:
+            "1px 1px 3px rgba(0,0,0,0.15), 3px 4px 8px rgba(0,0,0,0.08)",
+          transform: "rotate(-1deg)",
+          border: deprecated
+            ? "2px dashed rgba(239, 68, 68, 0.5)"
+            : draft
+              ? "2px dashed rgba(168, 85, 247, 0.5)"
+              : "none",
+        }}
+      >
+        <div style={FOLDED_CORNER_SHADOW_STYLE} />
+        <div
+          style={{
+            position: "absolute",
+            top: 0,
+            right: 0,
+            width: 0,
+            height: 0,
+            borderStyle: "solid",
+            borderWidth: "18px 0 0 18px",
+            borderColor: "#7e22ce transparent transparent transparent",
+            opacity: 0.3,
+          }}
+        />
+      </div>
+
+      <div className="relative px-3.5 py-3">
+        <div className="flex items-center justify-between mb-2">
+          <div className="flex items-center gap-1">
+            <Globe className="w-3 h-3 text-purple-900/50" strokeWidth={2.5} />
+            <span className="text-[8px] font-bold text-purple-900/50 uppercase tracking-widest">
+              External
+            </span>
+          </div>
+          {draft && (
+            <span className="text-[8px] font-extrabold text-amber-900 bg-amber-100 border border-dashed border-amber-400 px-1.5 py-0.5 rounded uppercase">
+              Draft
+            </span>
+          )}
+          {deprecated && (
+            <span className="text-[7px] font-bold text-white bg-red-500 border border-red-600 px-1.5 py-0.5 rounded uppercase">
+              Deprecated
+            </span>
+          )}
+        </div>
+
+        <TruncatedResourceName
+          as="div"
+          value={name}
+          tooltipBorderColor="#a855f7"
+          className={classNames(
+            "text-[13px] font-bold leading-snug truncate",
+            deprecated ? "text-purple-950/40 line-through" : "text-purple-950",
+          )}
+        >
+          {name}
+        </TruncatedResourceName>
+
+        {version && (
+          <div className="text-[9px] text-purple-900/40 font-semibold mt-0.5">
+            v{version}
+          </div>
+        )}
+
+        {mode === "full" && summary && (
+          <div
+            className="mt-2 pt-1.5 border-t border-purple-900/10 text-[9px] text-purple-950/60 leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function DefaultExternalSystem(props: ExternalSystemNode) {
+  const { version, name, summary, deprecated, draft, notes } =
+    props.data.externalSystem;
+  const mode = props.data.mode || "simple";
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const isDark = useDarkMode();
+  const deprecatedStripe = isDark
+    ? "rgba(239,68,68,0.25)"
+    : "rgba(239,68,68,0.1)";
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible",
+        props?.selected ? "ring-2 ring-purple-400/60 ring-offset-2" : "",
+        deprecated
+          ? "border-dashed border-red-500"
+          : draft
+            ? `border-dashed ${isDark ? "border-purple-400" : "border-purple-400/60"}`
+            : "border-purple-500",
+      )}
+      style={{
+        background: deprecated
+          ? `repeating-linear-gradient(135deg, transparent, transparent 6px, ${deprecatedStripe} 6px, ${deprecatedStripe} 7px), var(--ec-external-node-bg, rgb(var(--ec-card-bg)))`
+          : draft
+            ? `repeating-linear-gradient(135deg, transparent, transparent 4px, ${isDark ? "rgba(168,85,247,0.25)" : "rgba(168,85,247,0.15)"} 4px, ${isDark ? "rgba(168,85,247,0.25)" : "rgba(168,85,247,0.15)"} 4.5px), repeating-linear-gradient(45deg, transparent, transparent 4px, ${isDark ? "rgba(168,85,247,0.25)" : "rgba(168,85,247,0.15)"} 4px, ${isDark ? "rgba(168,85,247,0.25)" : "rgba(168,85,247,0.15)"} 4.5px), var(--ec-external-node-bg, rgb(var(--ec-card-bg)))`
+            : "var(--ec-external-node-bg, rgb(var(--ec-card-bg)))",
+        boxShadow: "0 2px 12px rgba(168, 85, 247, 0.15)",
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {targetConnections.length > 0 && <GlowHandle side="left" />}
+      {sourceConnections.length > 0 && <GlowHandle side="right" />}
+
+      {/* Badge positioned outside top-left corner */}
+      <div className="absolute -top-2.5 left-2.5 flex items-center gap-1.5 z-10">
+        <span
+          className={classNames(
+            "inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm",
+            deprecated ? "bg-red-500" : "bg-purple-500",
+          )}
+        >
+          <Globe className="w-2.5 h-2.5" strokeWidth={2.5} />
+          External System{draft && " (Draft)"}
+          {deprecated && " (Deprecated)"}
+        </span>
+      </div>
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        {/* Name + version */}
+        <div className="flex items-baseline gap-1 min-w-0">
+          <TruncatedResourceName
+            value={name}
+            tooltipBorderColor="#a855f7"
+            className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+          >
+            {name}
+          </TruncatedResourceName>
+          {version && (
+            <span className="text-[10px] font-normal text-[rgb(var(--ec-page-text-muted))] shrink-0">
+              (v{version})
+            </span>
+          )}
+        </div>
+
+        {/* Summary */}
+        {mode === "full" && summary && (
+          <div
+            className="mt-1.5 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default memo(function ExternalSystem(props: ExternalSystemNode) {
+  const nodeStyle = props?.data?.style;
+
+  if (nodeStyle === "post-it") {
+    return <PostItExternalSystem {...props} />;
+  }
+
+  return <DefaultExternalSystem {...props} />;
+});
diff --git a/packages/visualiser/src/nodes/external-system/config.ts b/packages/visualiser/src/nodes/external-system/config.ts
new file mode 100644
index 000000000..2a91625e8
--- /dev/null
+++ b/packages/visualiser/src/nodes/external-system/config.ts
@@ -0,0 +1,65 @@
+import { Connection, MarkerType } from "@xyflow/react";
+import { Globe } from "lucide-react";
+import { NodeConfiguration } from "../../types";
+import { SERVICE, CHANNEL, ACTOR, MESSAGE } from "../node-types";
+
+export default {
+  type: "external-system",
+  icon: Globe,
+  color: "pink",
+  targetCanConnectTo: [...SERVICE, ...CHANNEL, ...MESSAGE, ...ACTOR],
+  sourceCanConnectTo: [...SERVICE, ...CHANNEL, ...MESSAGE, ...ACTOR],
+  validateConnection: (connection: Connection) => {
+    return connection.source !== connection.target;
+  },
+  getEdgeOptions: (connection: Connection) => {
+    return {
+      label: "Connects",
+      markerEnd: { type: MarkerType.ArrowClosed, color: "#000000" },
+    };
+  },
+  defaultData: {
+    mode: "full",
+    externalSystem: {
+      id: "1",
+      name: "New External System",
+      version: "0.0.1",
+      summary: "New external system. Click edit to change the details.",
+    },
+  },
+  editor: {
+    title: "External System",
+    subtitle: "Edit the details of the external system",
+    schema: {
+      type: "object",
+      required: ["externalSystem", "mode"],
+      properties: {
+        externalSystem: {
+          type: "object",
+          required: ["name", "version"],
+          properties: {
+            name: {
+              type: "string",
+              title: "Name",
+              default: "Random value",
+              description: "The name of the external system",
+            },
+            version: {
+              type: "string",
+              title: "Version",
+              default: "1.0.0",
+              description: "The version number (e.g., 1.0.0)",
+              pattern: "^\\d+\\.\\d+\\.\\d+(?:-[\\w.-]+)?(?:\\+[\\w.-]+)?$",
+            },
+            summary: {
+              type: "string",
+              title: "Summary",
+              default: "",
+              description: "A brief summary of the external system",
+            },
+          },
+        },
+      },
+    },
+  },
+} as NodeConfiguration;
diff --git a/packages/visualiser/src/nodes/external-system/index.ts b/packages/visualiser/src/nodes/external-system/index.ts
new file mode 100644
index 000000000..83002895c
--- /dev/null
+++ b/packages/visualiser/src/nodes/external-system/index.ts
@@ -0,0 +1,3 @@
+export { default as ExternalSystem } from "./ExternalSystem";
+export { default as externalSystemConfig } from "./config";
+export type { ExternalSystemNode } from "./ExternalSystem";
diff --git a/packages/visualiser/src/nodes/field/FieldNode.tsx b/packages/visualiser/src/nodes/field/FieldNode.tsx
new file mode 100644
index 000000000..e216b79ba
--- /dev/null
+++ b/packages/visualiser/src/nodes/field/FieldNode.tsx
@@ -0,0 +1,110 @@
+import { memo } from "react";
+import { Database } from "lucide-react";
+import { HIDDEN_HANDLE_STYLE } from "../OwnerIndicator";
+import { Node, Handle, Position, useNodeConnections } from "@xyflow/react";
+import { useDarkMode } from "../shared-styles";
+
+function GlowHandle({ side }: { side: "left" | "right" }) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: "linear-gradient(135deg, #06b6d4, #0891b2)",
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: "ec-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none" as const,
+      }}
+    />
+  );
+}
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+type FieldNodeData = {
+  name: string;
+  type?: string;
+  mode?: "simple" | "full";
+};
+
+export type FieldNode = Node<FieldNodeData, "field">;
+
+export default memo(function Field(props: FieldNode) {
+  const { name, type: fieldType } = props.data;
+  const mode = props.data.mode || "simple";
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const isDark = useDarkMode();
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible",
+        props?.selected ? "ring-2 ring-cyan-400/60 ring-offset-2" : "",
+        "border-cyan-500",
+      )}
+      style={{
+        background: "var(--ec-field-node-bg, rgb(var(--ec-card-bg)))",
+        boxShadow: "0 2px 12px rgba(6, 182, 212, 0.15)",
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {targetConnections.length > 0 && <GlowHandle side="left" />}
+      {sourceConnections.length > 0 && <GlowHandle side="right" />}
+
+      {/* Type badge top-left */}
+      <div className="absolute -top-2.5 left-2.5 z-10">
+        <span className="inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm bg-cyan-600">
+          <Database className="w-2.5 h-2.5" strokeWidth={2.5} />
+          Field
+        </span>
+      </div>
+
+      {/* Field type badge top-right */}
+      {fieldType && (
+        <span
+          className="z-10 text-[7px] font-semibold text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-card-bg))] border border-cyan-500 rounded-full px-1.5 py-0.5 uppercase tracking-wide"
+          style={{ position: "absolute", top: -8, right: 10 }}
+        >
+          {fieldType}
+        </span>
+      )}
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        {/* Name */}
+        <div className="flex items-baseline gap-1">
+          <span className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))]">
+            {name}
+          </span>
+        </div>
+
+        {/* Type info in full mode */}
+        {mode === "full" && fieldType && (
+          <div
+            className="mt-1.5 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed"
+            title={`Type: ${fieldType}`}
+          >
+            Type: {fieldType}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/field/config.ts b/packages/visualiser/src/nodes/field/config.ts
new file mode 100644
index 000000000..dbef64a9c
--- /dev/null
+++ b/packages/visualiser/src/nodes/field/config.ts
@@ -0,0 +1,29 @@
+import { MarkerType } from "@xyflow/react";
+import { Database } from "lucide-react";
+import { NodeConfiguration } from "../../types";
+
+export default {
+  type: "field",
+  icon: Database,
+  color: "cyan",
+  targetCanConnectTo: [],
+  sourceCanConnectTo: [],
+  validateConnection: () => false,
+  getEdgeOptions: () => ({
+    label: "contains",
+    markerEnd: { type: MarkerType.ArrowClosed, color: "#06b6d4" },
+  }),
+  defaultData: { name: "New Field", type: "string", mode: "full" },
+  editor: {
+    title: "Field",
+    subtitle: "Schema field",
+    schema: {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: { type: "string", title: "Field Path" },
+        type: { type: "string", title: "Type" },
+      },
+    },
+  },
+} as NodeConfiguration;
diff --git a/packages/visualiser/src/nodes/field/index.ts b/packages/visualiser/src/nodes/field/index.ts
new file mode 100644
index 000000000..5c2a31a12
--- /dev/null
+++ b/packages/visualiser/src/nodes/field/index.ts
@@ -0,0 +1,3 @@
+export { default as Field } from "./FieldNode";
+export { default as fieldConfig } from "./config";
+export type { FieldNode as FieldNodeType } from "./FieldNode";
diff --git a/packages/visualiser/src/nodes/index.ts b/packages/visualiser/src/nodes/index.ts
new file mode 100644
index 000000000..baa176490
--- /dev/null
+++ b/packages/visualiser/src/nodes/index.ts
@@ -0,0 +1,159 @@
+/**
+ * Node components for EventCatalog Visualizer
+ */
+
+// Studio-2 nodes (organized in directories) - import for nodeComponents
+import { Event, eventConfig } from "./event";
+import { Command } from "./command";
+import { Query } from "./query";
+import { Service } from "./service";
+import AgentNode from "./Agent";
+import AgentToolNode from "./AgentTool";
+import { Channel } from "./channel";
+import { Note } from "./note";
+import { Data, dataNodeConfig } from "./data";
+import { View } from "./view";
+import { Actor, actorConfig } from "./actor";
+import { ExternalSystem, externalSystemConfig } from "./external-system";
+import { Field, fieldConfig } from "./field";
+
+// Re-export studio-2 nodes
+export { Event, eventConfig };
+export type { EventNode } from "./event";
+
+export { Command };
+export type { CommandNode } from "./command";
+
+export { Query };
+export type { QueryNode } from "./query";
+
+export { Service };
+export type { ServiceNode } from "./service";
+
+export type { AgentToolNode as AgentToolNodeType } from "./AgentTool";
+
+export { Channel };
+export type { ChannelNode } from "./channel";
+
+export { Note };
+export type { NoteNode } from "./note";
+
+export { Data, dataNodeConfig };
+export type { DataNode } from "./data";
+
+export { View };
+export type { ViewNode } from "./view";
+
+export { Actor, actorConfig };
+export type { ActorNode } from "./actor";
+
+export { ExternalSystem, externalSystemConfig };
+export type { ExternalSystemNode } from "./external-system";
+
+export { Field, fieldConfig };
+export type { FieldNodeType } from "./field";
+
+// Shared components
+export { NotesIndicator } from "./NotesIndicator";
+export { OwnerIndicator, normalizeOwners } from "./OwnerIndicator";
+
+// Core nodes (single files) - import then re-export for nodeComponents
+import CustomNode from "./Custom";
+import DomainNode from "./Domain";
+import SystemNode from "./System";
+import ContextActorNode from "./ContextActor";
+import SystemGroupNode from "./SystemGroupNode";
+import EntityNode from "./Entity";
+import FlowNode from "./Flow";
+import FlowExpandedNode from "./FlowExpandedNode";
+import GroupNode from "./GroupNode";
+import StepNode from "./Step";
+import UserNode from "./User";
+import DataProductNode from "./DataProduct";
+import ExternalSystem2Node from "./ExternalSystem2";
+import { MessageGroupNode, MessageGroupExpandedNode } from "./message-group";
+
+export {
+  CustomNode,
+  DomainNode,
+  SystemNode,
+  ContextActorNode,
+  SystemGroupNode,
+  EntityNode,
+  FlowNode,
+  FlowExpandedNode,
+  GroupNode,
+  StepNode,
+  UserNode,
+  DataProductNode,
+  AgentNode,
+  AgentToolNode,
+  ExternalSystem2Node,
+  MessageGroupNode,
+  MessageGroupExpandedNode,
+};
+
+export type {
+  MessageGroupNodeType,
+  MessageGroupNodeData,
+} from "./message-group";
+
+export type { MessageGroupExpandedNodeData } from "./message-group";
+
+// Node type constants
+export {
+  SERVICE,
+  AGENT,
+  AGENT_TOOL,
+  EVENT,
+  QUERY,
+  COMMAND,
+  CHANNEL,
+  ACTOR,
+  MESSAGE,
+  DATA,
+  VIEW,
+} from "./node-types";
+
+// Re-export for convenience (studio-2 nodes only)
+export const nodeComponents = {
+  event: Event,
+  command: Command,
+  query: Query,
+  service: Service,
+  agent: AgentNode,
+  agentTool: AgentToolNode,
+  "agent-tool": AgentToolNode,
+  channel: Channel,
+  note: Note,
+  externalSystem: ExternalSystem,
+  data: Data,
+  view: View,
+  actor: Actor,
+  field: Field,
+  // Core nodes are available via individual imports
+  custom: CustomNode,
+  domain: DomainNode,
+  system: SystemNode,
+  "context-actor": ContextActorNode,
+  "system-group": SystemGroupNode,
+  entity: EntityNode,
+  flow: FlowNode,
+  flowExpanded: FlowExpandedNode,
+  group: GroupNode,
+  step: StepNode,
+  user: UserNode,
+  dataProduct: DataProductNode,
+  externalSystem2: ExternalSystem2Node,
+  messageGroup: MessageGroupNode,
+  messageGroupExpanded: MessageGroupExpandedNode,
+};
+
+export const nodeConfigs: Record<string, import("../types").NodeConfiguration> =
+  {
+    event: eventConfig,
+    data: dataNodeConfig,
+    actor: actorConfig,
+    externalSystem: externalSystemConfig,
+    field: fieldConfig,
+  };
diff --git a/packages/visualiser/src/nodes/message-group/MessageGroupExpandedNode.tsx b/packages/visualiser/src/nodes/message-group/MessageGroupExpandedNode.tsx
new file mode 100644
index 000000000..60c4490a6
--- /dev/null
+++ b/packages/visualiser/src/nodes/message-group/MessageGroupExpandedNode.tsx
@@ -0,0 +1,139 @@
+import { memo } from "react";
+import { Layers, Minimize2 } from "lucide-react";
+import { TruncatedResourceName } from "../TruncatedResourceName";
+
+export type MessageGroupExpandedNodeData = {
+  groupName: string;
+  direction: "sends" | "receives";
+  messageCount: number;
+  onCollapse?: string; // group node ID to collapse back to
+};
+
+const CONTAINER_STYLE: React.CSSProperties = {
+  width: "100%",
+  height: "100%",
+  borderRadius: 12,
+  border: "2px solid rgba(139, 92, 246, 0.5)",
+  backgroundColor: "rgba(139, 92, 246, 0.05)",
+  position: "relative",
+  overflow: "visible",
+};
+
+const HEADER_STYLE: React.CSSProperties = {
+  position: "absolute",
+  top: 0,
+  left: 0,
+  right: 0,
+  height: 44,
+  borderTopLeftRadius: 10,
+  borderTopRightRadius: 10,
+  background: "rgba(139, 92, 246, 0.12)",
+  borderBottom: "1px solid rgba(139, 92, 246, 0.3)",
+  overflow: "visible",
+};
+
+const BADGE_STYLE: React.CSSProperties = {
+  position: "absolute",
+  top: -10,
+  left: 12,
+  display: "inline-flex",
+  alignItems: "center",
+  gap: 3,
+  padding: "2px 8px",
+  borderRadius: 4,
+  background: "#7c3aed",
+  boxShadow: "0 1px 3px rgba(0,0,0,0.15)",
+  zIndex: 10,
+  fontSize: 8,
+  fontWeight: 700,
+  letterSpacing: "0.08em",
+  textTransform: "uppercase" as const,
+  color: "white",
+};
+
+const HEADER_CONTENT_STYLE: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  height: "100%",
+  padding: "0 12px 0 14px",
+  gap: 12,
+};
+
+const GROUP_NAME_STYLE: React.CSSProperties = {
+  fontSize: 11,
+  fontWeight: 700,
+  color: "var(--ec-group-text, #5b21b6)",
+  letterSpacing: "0.04em",
+  textTransform: "uppercase",
+  whiteSpace: "nowrap",
+};
+
+const COUNT_STYLE: React.CSSProperties = {
+  fontSize: 10,
+  fontWeight: 500,
+  color: "#a78bfa",
+  marginLeft: 8,
+};
+
+const COLLAPSE_BUTTON_STYLE: React.CSSProperties = {
+  background: "#7c3aed",
+  border: "1px solid #a78bfa",
+  borderRadius: 6,
+  padding: "4px 10px",
+  cursor: "pointer",
+  display: "flex",
+  alignItems: "center",
+  gap: 4,
+  fontSize: 10,
+  fontWeight: 600,
+  color: "white",
+};
+
+export default memo(function MessageGroupExpandedNode({
+  data,
+}: {
+  data: MessageGroupExpandedNodeData;
+}) {
+  const { groupName, messageCount } = data;
+
+  return (
+    <div style={CONTAINER_STYLE}>
+      <div style={HEADER_STYLE}>
+        <div style={BADGE_STYLE}>
+          <Layers size={10} strokeWidth={2.5} />
+          Group
+        </div>
+
+        <div style={HEADER_CONTENT_STYLE}>
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              minWidth: 0,
+              flex: 1,
+            }}
+          >
+            <TruncatedResourceName
+              value={groupName || "Group"}
+              tooltipBorderColor="#8b5cf6"
+              className="truncate"
+              style={GROUP_NAME_STYLE}
+            >
+              {groupName || "Group"}
+            </TruncatedResourceName>
+          </div>
+
+          <button
+            style={COLLAPSE_BUTTON_STYLE}
+            className="ec-collapse-group-btn nodrag nopan"
+            onMouseDown={(e) => e.stopPropagation()}
+          >
+            <Minimize2 size={12} strokeWidth={2.5} />
+            Collapse
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/message-group/MessageGroupNode.tsx b/packages/visualiser/src/nodes/message-group/MessageGroupNode.tsx
new file mode 100644
index 000000000..14aabc06c
--- /dev/null
+++ b/packages/visualiser/src/nodes/message-group/MessageGroupNode.tsx
@@ -0,0 +1,189 @@
+import { memo, useMemo } from "react";
+import { Layers, Zap, Terminal, HelpCircle, Maximize2 } from "lucide-react";
+import { Node, Handle, Position, useNodeConnections } from "@xyflow/react";
+import { HIDDEN_HANDLE_STYLE } from "../OwnerIndicator";
+import { useDarkMode } from "../shared-styles";
+import { TruncatedResourceName } from "../TruncatedResourceName";
+
+export type MessageGroupNodeData = {
+  mode?: string;
+  groupName: string;
+  direction: "sends" | "receives";
+  messageCount: number;
+  messageTypes: string[];
+  messages: Array<{
+    message: any;
+    channels: any[];
+  }>;
+  service: { id: string; version: string };
+};
+
+export type MessageGroupNode = Node<MessageGroupNodeData, "messageGroup">;
+
+const TYPE_ICONS: Record<string, React.ComponentType<any>> = {
+  events: Zap,
+  commands: Terminal,
+  queries: HelpCircle,
+};
+
+const CARD_STYLE: React.CSSProperties = {
+  borderRadius: 12,
+  border: "2px solid rgba(139, 92, 246, 0.4)",
+  background: "var(--ec-message-group-node-bg, rgb(var(--ec-card-bg)))",
+  pointerEvents: "none" as const,
+};
+
+export default memo(function MessageGroupNode(props: MessageGroupNode) {
+  const { groupName, messageCount } = props.data;
+  const isDark = useDarkMode();
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const stackDepth = messageCount >= 3 ? 3 : messageCount;
+
+  const typeBreakdown = useMemo(() => {
+    const counts: Record<string, number> = {};
+    props.data.messages.forEach(({ message }) => {
+      const type = message?.collection || "unknown";
+      counts[type] = (counts[type] || 0) + 1;
+    });
+    return counts;
+  }, [props.data.messages]);
+
+  return (
+    <div className="relative" style={{ isolation: "isolate" }}>
+      {/* Stack layers — positioned behind the main card */}
+      {stackDepth >= 3 && (
+        <div
+          style={{
+            ...CARD_STYLE,
+            position: "absolute",
+            inset: 0,
+            transform: "translate(6px, 6px)",
+            opacity: 0.5,
+          }}
+        />
+      )}
+      {stackDepth >= 2 && (
+        <div
+          style={{
+            ...CARD_STYLE,
+            position: "absolute",
+            inset: 0,
+            transform: "translate(3px, 3px)",
+            opacity: 0.7,
+          }}
+        />
+      )}
+
+      {/* Main card */}
+      <div
+        className={`relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible ${
+          props.selected ? "ring-2 ring-violet-400/60 ring-offset-2" : ""
+        } border-violet-500`}
+        style={{
+          background: "var(--ec-message-group-node-bg, rgb(var(--ec-card-bg)))",
+          boxShadow: "0 2px 12px rgba(139, 92, 246, 0.15)",
+        }}
+      >
+        <Handle
+          type="target"
+          position={Position.Left}
+          style={HIDDEN_HANDLE_STYLE}
+        />
+        <Handle
+          type="source"
+          position={Position.Right}
+          style={HIDDEN_HANDLE_STYLE}
+        />
+
+        {targetConnections.length > 0 && (
+          <div
+            style={{
+              position: "absolute",
+              top: "50%",
+              left: -6,
+              transform: "translateY(-50%)",
+              width: 12,
+              height: 12,
+              borderRadius: "50%",
+              background: "linear-gradient(135deg, #a78bfa, #7c3aed)",
+              border: "2px solid rgb(var(--ec-page-bg))",
+              zIndex: 20,
+              animation: "ec-handle-pulse 2s ease-in-out infinite",
+              pointerEvents: "none",
+            }}
+          />
+        )}
+        {sourceConnections.length > 0 && (
+          <div
+            style={{
+              position: "absolute",
+              top: "50%",
+              right: -6,
+              transform: "translateY(-50%)",
+              width: 12,
+              height: 12,
+              borderRadius: "50%",
+              background: "linear-gradient(135deg, #a78bfa, #7c3aed)",
+              border: "2px solid rgb(var(--ec-page-bg))",
+              zIndex: 20,
+              animation: "ec-handle-pulse 2s ease-in-out infinite",
+              pointerEvents: "none",
+            }}
+          />
+        )}
+
+        <div className="absolute -top-2.5 left-2.5 z-10">
+          <span className="inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm bg-violet-600">
+            <Layers className="w-2.5 h-2.5" strokeWidth={2.5} />
+            Group
+          </span>
+        </div>
+
+        <div className="px-3 pt-3.5 pb-2.5">
+          <TruncatedResourceName
+            as="div"
+            value={groupName}
+            tooltipBorderColor="#8b5cf6"
+            className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+          >
+            {groupName}
+          </TruncatedResourceName>
+
+          <div className="mt-1.5 flex items-center gap-2">
+            <span
+              className="text-[10px] font-medium px-1.5 py-0.5 rounded"
+              style={{
+                background: isDark
+                  ? "rgba(139, 92, 246, 0.2)"
+                  : "rgba(139, 92, 246, 0.1)",
+                color: isDark ? "#c4b5fd" : "#6d28d9",
+              }}
+            >
+              {messageCount} {messageCount === 1 ? "message" : "messages"}
+            </span>
+            <div className="flex items-center gap-1">
+              {Object.entries(typeBreakdown).map(([type, count]) => {
+                const Icon = TYPE_ICONS[type] || HelpCircle;
+                return (
+                  <span
+                    key={type}
+                    className="flex items-center gap-0.5 text-[9px] text-[rgb(var(--ec-page-text-muted))]"
+                  >
+                    <Icon className="w-2.5 h-2.5" strokeWidth={2} />
+                    {count}
+                  </span>
+                );
+              })}
+            </div>
+          </div>
+
+          <div className="mt-1.5 flex items-center gap-1 text-[8px] text-[rgb(var(--ec-page-text-muted))]">
+            <Maximize2 className="w-2.5 h-2.5" />
+            Click to explore
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/message-group/index.ts b/packages/visualiser/src/nodes/message-group/index.ts
new file mode 100644
index 000000000..b73e784b5
--- /dev/null
+++ b/packages/visualiser/src/nodes/message-group/index.ts
@@ -0,0 +1,8 @@
+export { default as MessageGroupNode } from "./MessageGroupNode";
+export type {
+  MessageGroupNode as MessageGroupNodeType,
+  MessageGroupNodeData,
+} from "./MessageGroupNode";
+
+export { default as MessageGroupExpandedNode } from "./MessageGroupExpandedNode";
+export type { MessageGroupExpandedNodeData } from "./MessageGroupExpandedNode";
diff --git a/packages/visualiser/src/nodes/node-types.ts b/packages/visualiser/src/nodes/node-types.ts
new file mode 100644
index 000000000..47cdbec72
--- /dev/null
+++ b/packages/visualiser/src/nodes/node-types.ts
@@ -0,0 +1,12 @@
+export const SERVICE = ["service", "services"];
+export const AGENT = ["agent", "agents"];
+export const AGENT_TOOL = ["agentTool", "agent-tool"];
+export const EVENT = ["event", "events"];
+export const QUERY = ["queries", "query", "querie"];
+export const COMMAND = ["command", "commands"];
+export const CHANNEL = ["channel", "channels"];
+export const ACTOR = ["actor", "actors"];
+export const DATA = ["data"];
+export const VIEW = ["view"];
+
+export const MESSAGE = [...EVENT, ...COMMAND, ...QUERY];
diff --git a/packages/visualiser/src/nodes/note/NoteNode.tsx b/packages/visualiser/src/nodes/note/NoteNode.tsx
new file mode 100644
index 000000000..cd3f287e4
--- /dev/null
+++ b/packages/visualiser/src/nodes/note/NoteNode.tsx
@@ -0,0 +1,316 @@
+import { Node, Handle, Position } from "@xyflow/react";
+import React, { memo, useState, useEffect, useRef, useCallback } from "react";
+import { FULL_SIZE_STYLE } from "../shared-styles";
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+// Define the data structure for our NoteNode
+export type NoteNodeData = {
+  id: string;
+  text: string;
+  color?: string;
+  readOnly?: boolean;
+};
+
+// Define the NoteNode type for React Flow
+export type NoteNode = Node<NoteNodeData, "note">;
+
+export interface NoteNodeProps extends NoteNode {
+  onTextChange?: (id: string, text: string) => void;
+  onColorChange?: (id: string, color: string) => void;
+  showResizer?: boolean;
+  readOnly?: boolean;
+}
+
+const AVAILABLE_COLORS = {
+  yellow: {
+    bg: "bg-gradient-to-br from-yellow-200 to-yellow-300",
+    border: "border-yellow-400",
+    text: "text-yellow-900",
+    placeholder: "placeholder-yellow-600",
+    selectedRing: "ring-yellow-500",
+    tooltipBorderColor: "#facc15",
+  },
+  blue: {
+    bg: "bg-blue-200",
+    border: "border-blue-400",
+    text: "text-blue-900",
+    placeholder: "placeholder-blue-600",
+    selectedRing: "ring-blue-500",
+    tooltipBorderColor: "#60a5fa",
+  },
+  green: {
+    bg: "bg-green-200",
+    border: "border-green-400",
+    text: "text-green-900",
+    placeholder: "placeholder-green-600",
+    selectedRing: "ring-green-500",
+    tooltipBorderColor: "#4ade80",
+  },
+  pink: {
+    bg: "bg-pink-200",
+    border: "border-pink-400",
+    text: "text-pink-900",
+    placeholder: "placeholder-pink-600",
+    selectedRing: "ring-pink-500",
+    tooltipBorderColor: "#f472b6",
+  },
+  purple: {
+    bg: "bg-purple-200",
+    border: "border-purple-400",
+    text: "text-purple-900",
+    placeholder: "placeholder-purple-600",
+    selectedRing: "ring-purple-500",
+    tooltipBorderColor: "#c084fc",
+  },
+  gray: {
+    bg: "bg-gray-200",
+    border: "border-gray-400",
+    text: "text-gray-900",
+    placeholder: "placeholder-gray-600",
+    selectedRing: "ring-gray-500",
+    tooltipBorderColor: "#9ca3af",
+  },
+} as const;
+
+type ColorName = keyof typeof AVAILABLE_COLORS;
+
+const POSITION_RELATIVE_STYLE = { position: "relative" } as const;
+const TEXTAREA_STYLE = { height: "100%", minHeight: 0 } as const;
+
+export default memo(function NoteNodeComponent({
+  id,
+  data,
+  selected,
+  onTextChange,
+  onColorChange,
+  readOnly = false,
+}: NoteNodeProps) {
+  const [isEditing, setIsEditing] = useState(false);
+  const [currentText, setCurrentText] = useState(
+    data.text || "Double-click to edit...",
+  );
+  const [isTextOverflowing, setIsTextOverflowing] = useState(false);
+  const textAreaRef = useRef<HTMLTextAreaElement>(null);
+  const displayRef = useRef<HTMLDivElement>(null);
+
+  const currentColorName = (data.color as ColorName) || "yellow";
+  const colorClasses =
+    AVAILABLE_COLORS[currentColorName] || AVAILABLE_COLORS.yellow;
+
+  // Simple markdown-like text formatting
+  const formatText = (text: string) => {
+    return (
+      text
+        // Headers
+        .replace(
+          /^### (.*$)/gim,
+          '<h3 class="text-xs font-medium mb-1">$1</h3>',
+        )
+        .replace(
+          /^## (.*$)/gim,
+          '<h2 class="text-xs font-semibold mb-1">$1</h2>',
+        )
+        .replace(/^# (.*$)/gim, '<h1 class="text-sm font-bold mb-1">$1</h1>')
+        // Bold
+        .replace(/\*\*(.*?)\*\*/gim, '<strong class="font-bold">$1</strong>')
+        // Italic
+        .replace(/\*(.*?)\*/gim, '<em class="italic">$1</em>')
+        // Inline code
+        .replace(
+          /`(.*?)`/gim,
+          '<code class="bg-gray-200 px-1 rounded text-[9px] font-mono">$1</code>',
+        )
+        // Simple lists
+        .replace(/^• (.*$)/gim, '<li class="text-[10px] ml-3">• $1</li>')
+        .replace(/^- (.*$)/gim, '<li class="text-[10px] ml-3">• $1</li>')
+        // Line breaks
+        .replace(/\n/g, "<br>")
+    );
+  };
+
+  useEffect(() => {
+    // Update internal state if data.text changes from props (e.g. undo/redo, initial load)
+    setCurrentText(data.text || "Double-click to edit...");
+  }, [data.text]);
+
+  useEffect(() => {
+    if (isEditing && textAreaRef.current) {
+      textAreaRef.current.focus();
+      // Select all text when starting to edit for quicker replacement
+      textAreaRef.current.select();
+    }
+  }, [isEditing]);
+
+  useEffect(() => {
+    const element = displayRef.current;
+    if (!element || isEditing) return;
+
+    const updateOverflow = () => {
+      setIsTextOverflowing(element.scrollHeight > element.clientHeight);
+    };
+
+    updateOverflow();
+
+    if (typeof ResizeObserver === "undefined") {
+      window.addEventListener("resize", updateOverflow);
+      return () => window.removeEventListener("resize", updateOverflow);
+    }
+
+    const observer = new ResizeObserver(updateOverflow);
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [currentText, isEditing]);
+
+  const handleDoubleClick = useCallback(() => {
+    if (!readOnly) {
+      setIsEditing(true);
+    }
+  }, [readOnly]);
+
+  const handleTextChange = useCallback(
+    (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+      setCurrentText(event.target.value);
+    },
+    [],
+  );
+
+  const handleBlur = useCallback(() => {
+    setIsEditing(false);
+    // Only update if the text has actually changed from what's in data
+    // or if data.text was initially undefined/empty and now has content.
+    if (currentText !== data.text && onTextChange) {
+      onTextChange(id, currentText);
+    }
+  }, [currentText, data.text, id, onTextChange]);
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+      if (event.key === "Enter" && !event.shiftKey) {
+        event.preventDefault(); // Prevent newline on Enter
+        handleBlur(); // Save and exit edit mode
+      }
+      // Allow Shift+Enter for newlines by default textarea behavior
+      if (event.key === "Escape") {
+        setIsEditing(false);
+        // Revert to original text from data on Escape
+        setCurrentText(data.text || "Double-click to edit...");
+      }
+    },
+    [handleBlur, data.text],
+  );
+
+  const handleColorChange = useCallback(
+    (newColor: ColorName) => {
+      if (onColorChange) {
+        onColorChange(id, newColor);
+      }
+    },
+    [id, onColorChange],
+  );
+
+  return (
+    <div className="relative group" style={FULL_SIZE_STYLE}>
+      <Handle
+        type="target"
+        position={Position.Left}
+        className="!left-[-1px] !w-2 !h-2 !bg-gray-400 !border !border-gray-500 !rounded-full !z-10"
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        className="!right-[-1px] !w-2 !h-2 !bg-gray-400 !border !border-gray-500 !rounded-full !z-10"
+      />
+      {selected && !isEditing && !readOnly && (
+        <div className="absolute -top-10 left-1/2 transform -translate-x-1/2 flex space-x-1 p-1 bg-[rgb(var(--ec-card-bg))] rounded-md shadow-lg border border-[rgb(var(--ec-page-border))] z-20">
+          {Object.keys(AVAILABLE_COLORS).map((colorKey) => (
+            <button
+              key={colorKey}
+              onClick={() => handleColorChange(colorKey as ColorName)}
+              className={classNames(
+                "w-6 h-6 rounded-full border-2",
+                AVAILABLE_COLORS[colorKey as ColorName].bg,
+                AVAILABLE_COLORS[colorKey as ColorName].border,
+                currentColorName === colorKey
+                  ? "ring-2 ring-offset-1 " +
+                      AVAILABLE_COLORS[colorKey as ColorName].selectedRing
+                  : "",
+              )}
+              title={colorKey.charAt(0).toUpperCase() + colorKey.slice(1)}
+            />
+          ))}
+        </div>
+      )}
+      <div
+        onDoubleClick={handleDoubleClick}
+        className={classNames(
+          "w-full h-full rounded-lg border p-3 flex flex-col min-w-[150px] min-h-[150px] relative",
+          colorClasses.bg,
+          colorClasses.border,
+          colorClasses.text,
+          "prose prose-sm max-w-full",
+          selected
+            ? `border-blue-600 ring-2 ${colorClasses.selectedRing} shadow-xl`
+            : "shadow-md hover:shadow-lg",
+          currentColorName === "yellow"
+            ? "shadow-yellow-300/50 shadow-lg transform rotate-0.5"
+            : "",
+        )}
+        style={POSITION_RELATIVE_STYLE}
+      >
+        {isEditing ? (
+          <textarea
+            ref={textAreaRef}
+            value={currentText}
+            onChange={handleTextChange}
+            onBlur={handleBlur}
+            onKeyDown={handleKeyDown}
+            className={classNames(
+              "w-full flex-1 bg-transparent border-none outline-none resize-none text-[10px] p-0 m-0",
+              colorClasses.text,
+              colorClasses.placeholder,
+            )}
+            style={TEXTAREA_STYLE}
+            placeholder="Enter text..."
+          />
+        ) : (
+          <>
+            <div
+              ref={displayRef}
+              className="whitespace-pre-wrap break-words w-full h-full overflow-y-auto custom-scrollbar text-[10px]"
+              dangerouslySetInnerHTML={{
+                __html: formatText(currentText),
+              }}
+            />
+            {isTextOverflowing && (
+              <div
+                className="pointer-events-none absolute left-1/2 bottom-full z-[9999] mb-4 hidden w-max max-w-[320px] -translate-x-1/2 rounded-md border bg-slate-950 px-2.5 py-1.5 text-[11px] font-medium leading-snug text-white shadow-lg group-hover:block"
+                style={{ borderColor: colorClasses.tooltipBorderColor }}
+              >
+                <span className="block whitespace-pre-wrap break-words">
+                  {currentText}
+                </span>
+                <span
+                  className="absolute left-1/2 top-full h-2 w-2 -translate-x-1/2 -translate-y-1/2 rotate-45 border-b border-r bg-slate-950"
+                  style={{
+                    borderBottomColor: colorClasses.tooltipBorderColor,
+                    borderRightColor: colorClasses.tooltipBorderColor,
+                  }}
+                />
+              </div>
+            )}
+          </>
+        )}
+
+        {/* PostIt folded corner effect */}
+        {currentColorName === "yellow" && (
+          <div className="absolute top-0 right-0 w-4 h-4">
+            <div className="absolute top-0 right-0 w-0 h-0 border-l-[16px] border-b-[16px] border-l-transparent border-b-yellow-400/30 rounded-br-lg"></div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/note/index.ts b/packages/visualiser/src/nodes/note/index.ts
new file mode 100644
index 000000000..bd974c094
--- /dev/null
+++ b/packages/visualiser/src/nodes/note/index.ts
@@ -0,0 +1,2 @@
+export { default as Note } from "./NoteNode";
+export type { NoteNode } from "./NoteNode";
diff --git a/packages/visualiser/src/nodes/query/QueryNode.tsx b/packages/visualiser/src/nodes/query/QueryNode.tsx
new file mode 100644
index 000000000..332b1320e
--- /dev/null
+++ b/packages/visualiser/src/nodes/query/QueryNode.tsx
@@ -0,0 +1,341 @@
+import { memo, useMemo } from "react";
+import { Search } from "lucide-react";
+import {
+  OwnerIndicator,
+  normalizeOwners,
+  HIDDEN_HANDLE_STYLE,
+} from "../OwnerIndicator";
+import { Node, Handle, Position, useNodeConnections } from "@xyflow/react";
+import { Message, EventCatalogResource } from "../../types";
+import { NotesIndicator } from "../NotesIndicator";
+import { MethodBadge, ApiPath, StatusCodes } from "../ApiInfo";
+import { CustomIcon, isIconPath } from "../../utils/custom-icon";
+import {
+  LINE_CLAMP_STYLE,
+  FOLDED_CORNER_SHADOW_STYLE,
+  useDarkMode,
+} from "../shared-styles";
+import { TruncatedResourceName } from "../TruncatedResourceName";
+
+const GlowHandle = memo(function GlowHandle({
+  side,
+}: {
+  side: "left" | "right";
+}) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: "linear-gradient(135deg, #22c55e, #15803d)",
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: "ec-query-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none",
+      }}
+    />
+  );
+});
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+type QueryNodeData = EventCatalogResource & {
+  message: Message;
+};
+
+export type QueryNode = Node<QueryNodeData, "query">;
+
+function PostItQuery(props: QueryNode) {
+  const { version, name, summary, deprecated, draft, notes, styles } =
+    props.data.message;
+  const mode = props.data.mode || "simple";
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-44 max-w-56 min-h-[120px]",
+        props?.selected ? "ring-2 ring-green-400/60 ring-offset-1" : "",
+      )}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      <div
+        className="absolute inset-0"
+        style={{
+          background:
+            "linear-gradient(135deg, #bbf7d0 0%, #86efac 40%, #22c55e 100%)",
+          boxShadow:
+            "1px 1px 3px rgba(0,0,0,0.15), 3px 4px 8px rgba(0,0,0,0.08)",
+          transform: "rotate(-1deg)",
+          border: deprecated
+            ? "2px dashed rgba(239, 68, 68, 0.5)"
+            : draft
+              ? "2px dashed rgba(34, 197, 94, 0.5)"
+              : "none",
+        }}
+      >
+        {/* Folded corner */}
+        <div style={FOLDED_CORNER_SHADOW_STYLE} />
+        <div
+          style={{
+            position: "absolute",
+            top: 0,
+            right: 0,
+            width: 0,
+            height: 0,
+            borderStyle: "solid",
+            borderWidth: "18px 0 0 18px",
+            borderColor: "#16a34a transparent transparent transparent",
+            opacity: 0.3,
+          }}
+        />
+      </div>
+
+      <div className="relative px-3.5 py-3">
+        <div className="flex items-center justify-between mb-2">
+          <div className="flex items-center gap-1">
+            <Search className="w-3 h-3 text-green-900/50" strokeWidth={2.5} />
+            <span className="text-[8px] font-bold text-green-900/50 uppercase tracking-widest">
+              Query
+            </span>
+          </div>
+          {draft && (
+            <span className="text-[8px] font-extrabold text-amber-900 bg-amber-100 border border-dashed border-amber-400 px-1.5 py-0.5 rounded uppercase">
+              Draft
+            </span>
+          )}
+          {deprecated && (
+            <span className="text-[7px] font-bold text-white bg-red-500 border border-red-600 px-1.5 py-0.5 rounded uppercase">
+              Deprecated
+            </span>
+          )}
+        </div>
+
+        <div className="flex items-center gap-2">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className={
+                mode === "full"
+                  ? "w-5 h-5 shrink-0 mt-0.5"
+                  : "w-4 h-4 shrink-0 -my-1"
+              }
+            />
+          )}
+          <TruncatedResourceName
+            as="div"
+            value={name}
+            tooltipBorderColor="#22c55e"
+            className={classNames(
+              "text-[13px] font-bold leading-snug min-w-0 truncate",
+              deprecated ? "text-green-950/40 line-through" : "text-green-950",
+            )}
+          >
+            {name}
+          </TruncatedResourceName>
+        </div>
+
+        {version && (
+          <div className="text-[9px] text-green-900/40 font-semibold mt-0.5">
+            v{version}
+          </div>
+        )}
+
+        {mode === "full" && summary && (
+          <div
+            className="mt-2 pt-1.5 border-t border-green-900/10 text-[9px] text-green-950/60 leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function DefaultQuery(props: QueryNode) {
+  const {
+    version,
+    name,
+    summary,
+    deprecated,
+    draft,
+    schema,
+    notes,
+    method,
+    path,
+    statusCodes,
+    styles,
+  } = props.data.message;
+  const mode = props.data.mode || "simple";
+  const hasApiInfo = !!(method || path);
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+  const owners = useMemo(
+    () => normalizeOwners(props.data.message?.owners),
+    [props.data.message?.owners],
+  );
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const isDark = useDarkMode();
+  const deprecatedStripe = isDark
+    ? "rgba(239,68,68,0.25)"
+    : "rgba(239,68,68,0.1)";
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible",
+        props?.selected ? "ring-2 ring-green-400/60 ring-offset-2" : "",
+        deprecated
+          ? "border-dashed border-red-500"
+          : draft
+            ? `border-dashed ${isDark ? "border-green-400" : "border-green-400/60"}`
+            : "border-green-500",
+      )}
+      style={{
+        background: deprecated
+          ? `repeating-linear-gradient(135deg, transparent, transparent 6px, ${deprecatedStripe} 6px, ${deprecatedStripe} 7px), var(--ec-query-node-bg, rgb(var(--ec-card-bg)))`
+          : draft
+            ? `repeating-linear-gradient(135deg, transparent, transparent 4px, ${isDark ? "rgba(34,197,94,0.25)" : "rgba(34,197,94,0.15)"} 4px, ${isDark ? "rgba(34,197,94,0.25)" : "rgba(34,197,94,0.15)"} 4.5px), repeating-linear-gradient(45deg, transparent, transparent 4px, ${isDark ? "rgba(34,197,94,0.25)" : "rgba(34,197,94,0.15)"} 4px, ${isDark ? "rgba(34,197,94,0.25)" : "rgba(34,197,94,0.15)"} 4.5px), var(--ec-query-node-bg, rgb(var(--ec-card-bg)))`
+            : "var(--ec-query-node-bg, rgb(var(--ec-card-bg)))",
+        boxShadow: "0 2px 12px rgba(34, 197, 94, 0.15)",
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {targetConnections.length > 0 && <GlowHandle side="left" />}
+      {sourceConnections.length > 0 && <GlowHandle side="right" />}
+
+      {/* Type badge top-left */}
+      <div className="absolute -top-2.5 left-2.5 z-10">
+        <span
+          className={classNames(
+            "inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm",
+            deprecated ? "bg-red-500" : "bg-green-500",
+          )}
+        >
+          <Search className="w-2.5 h-2.5" strokeWidth={2.5} />
+          Query{draft && " (Draft)"}
+          {deprecated && " (Deprecated)"}
+        </span>
+      </div>
+      {/* Schema badge top-right */}
+      {schema && (
+        <span
+          className="z-10 text-[7px] font-semibold text-[rgb(var(--ec-page-text))] bg-[rgb(var(--ec-card-bg))] border border-green-500 rounded-full px-1.5 py-0.5 uppercase tracking-wide"
+          style={{ position: "absolute", top: -8, right: 10 }}
+        >
+          {schema.includes(".") ? schema.split(".").pop() : schema}
+        </span>
+      )}
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        {/* API method + path row */}
+        {hasApiInfo && (
+          <div className="flex items-center gap-1.5 mb-1 overflow-hidden min-w-0">
+            {method && <MethodBadge method={method} />}
+            {path && <ApiPath path={path} />}
+          </div>
+        )}
+
+        {/* Name + version */}
+        {!hasApiInfo && (
+          <div className="flex items-center gap-2">
+            {customIcon && (
+              <CustomIcon
+                src={customIcon}
+                alt={name}
+                className={
+                  mode === "full"
+                    ? "w-5 h-5 shrink-0 mt-0.5"
+                    : "w-4 h-4 shrink-0 -my-1"
+                }
+              />
+            )}
+            <div className="flex items-baseline gap-1 min-w-0">
+              <TruncatedResourceName
+                value={name}
+                tooltipBorderColor="#22c55e"
+                className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+              >
+                {name}
+              </TruncatedResourceName>
+              {version && (
+                <span className="text-[10px] font-normal text-[rgb(var(--ec-page-text-muted))] shrink-0">
+                  (v{version})
+                </span>
+              )}
+            </div>
+          </div>
+        )}
+
+        {/* Summary */}
+        {mode === "full" && summary && (
+          <div
+            className="mt-1.5 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+
+        {/* Status codes */}
+        {statusCodes && statusCodes.length > 0 && (
+          <StatusCodes codes={statusCodes} />
+        )}
+
+        {/* Owners */}
+        <OwnerIndicator
+          owners={owners}
+          accentColor="bg-green-400"
+          borderColor="rgba(34,197,94,0.08)"
+          iconClass="text-green-300"
+        />
+      </div>
+    </div>
+  );
+}
+
+export default memo(function Query(props: QueryNode) {
+  const nodeStyle = props?.data?.style;
+
+  if (nodeStyle === "post-it") {
+    return <PostItQuery {...props} />;
+  }
+
+  return <DefaultQuery {...props} />;
+});
diff --git a/packages/visualiser/src/nodes/query/index.ts b/packages/visualiser/src/nodes/query/index.ts
new file mode 100644
index 000000000..ea717c9aa
--- /dev/null
+++ b/packages/visualiser/src/nodes/query/index.ts
@@ -0,0 +1,2 @@
+export { default as Query } from "./QueryNode";
+export type { QueryNode } from "./QueryNode";
diff --git a/packages/visualiser/src/nodes/service/ServiceNode.tsx b/packages/visualiser/src/nodes/service/ServiceNode.tsx
new file mode 100644
index 000000000..febd4ba24
--- /dev/null
+++ b/packages/visualiser/src/nodes/service/ServiceNode.tsx
@@ -0,0 +1,590 @@
+import { memo, useMemo } from "react";
+import { ServerIcon, Globe } from "lucide-react";
+import { CustomIcon, isIconPath } from "../../utils/custom-icon";
+import {
+  OwnerIndicator,
+  normalizeOwners,
+  HIDDEN_HANDLE_STYLE,
+} from "../OwnerIndicator";
+import { Node, Handle, Position, useNodeConnections } from "@xyflow/react";
+import { EventCatalogResource, Service as ServiceType } from "../../types";
+import { NotesIndicator } from "../NotesIndicator";
+import {
+  LINE_CLAMP_STYLE,
+  WATERMARK_STYLE,
+  FOLDED_CORNER_SHADOW_STYLE,
+  useDarkMode,
+} from "../shared-styles";
+import { TruncatedResourceName } from "../TruncatedResourceName";
+
+const SPEC_LABELS: Record<string, string> = {
+  openapi: "OpenAPI",
+  asyncapi: "AsyncAPI",
+  graphql: "GraphQL",
+};
+
+const SPEC_COLORS: Record<
+  string,
+  { bg: string; text: string; darkBg: string; darkText: string }
+> = {
+  openapi: {
+    bg: "rgba(106,170,63,0.12)",
+    text: "#4d7c0f",
+    darkBg: "rgba(106,170,63,0.2)",
+    darkText: "#a3e635",
+  },
+  asyncapi: {
+    bg: "rgba(116,78,194,0.12)",
+    text: "#6d28d9",
+    darkBg: "rgba(116,78,194,0.2)",
+    darkText: "#c4b5fd",
+  },
+  graphql: {
+    bg: "rgba(229,53,171,0.12)",
+    text: "#be185d",
+    darkBg: "rgba(229,53,171,0.2)",
+    darkText: "#f9a8d4",
+  },
+};
+
+/** Normalize both array and legacy object spec formats into unique type strings */
+function normalizeSpecTypes(specs: unknown): string[] {
+  const types = new Set<string>();
+  if (Array.isArray(specs)) {
+    for (const spec of specs) {
+      if (spec?.type) types.add(String(spec.type).toLowerCase());
+    }
+  } else if (specs && typeof specs === "object") {
+    const legacy = specs as Record<string, unknown>;
+    if (legacy.asyncapiPath) types.add("asyncapi");
+    if (legacy.openapiPath) types.add("openapi");
+    if (legacy.graphqlPath) types.add("graphql");
+  }
+  return Array.from(types);
+}
+
+const SpecBadges = memo(function SpecBadges({
+  specifications,
+  isDark,
+}: {
+  specifications: unknown;
+  isDark: boolean;
+}) {
+  const specTypes = useMemo(
+    () => normalizeSpecTypes(specifications),
+    [specifications],
+  );
+
+  if (specTypes.length === 0) return null;
+
+  return (
+    <div className="flex items-center gap-1 flex-wrap justify-end">
+      {specTypes.map((type) => {
+        const colors = SPEC_COLORS[type] || SPEC_COLORS.openapi;
+        return (
+          <span
+            key={type}
+            className="inline-flex items-center text-[7px] font-bold px-1.5 py-0.5 rounded"
+            style={{
+              background: isDark ? colors.darkBg : colors.bg,
+              color: isDark ? colors.darkText : colors.text,
+            }}
+          >
+            {SPEC_LABELS[type] || type}
+          </span>
+        );
+      })}
+    </div>
+  );
+});
+
+const MiniEnvelope = memo(function MiniEnvelope({
+  side,
+  delay,
+}: {
+  side: "left" | "right";
+  delay: number;
+}) {
+  return (
+    <svg
+      width="14"
+      height="10"
+      viewBox="0 0 14 10"
+      style={{
+        animation: `${side === "left" ? "ec-svc-msg-in" : "ec-svc-msg-out"} 2.5s ease-in-out ${delay}s infinite`,
+        opacity: 0,
+      }}
+    >
+      <rect
+        x="0.5"
+        y="0.5"
+        width="13"
+        height="9"
+        rx="1.5"
+        fill="#9ca3af"
+        opacity={0.85}
+      />
+      <path
+        d="M0.5,0.5 L7,5 L13.5,0.5"
+        fill="none"
+        stroke="white"
+        strokeWidth="1"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+});
+
+const ServiceMessageFlow = memo(function ServiceMessageFlow({
+  side,
+}: {
+  side: "left" | "right";
+}) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -4,
+        transform: "translateY(-50%)",
+        display: "flex",
+        flexDirection: "column",
+        gap: 2,
+        zIndex: 15,
+        pointerEvents: "none",
+      }}
+    >
+      <MiniEnvelope side={side} delay={0} />
+      <MiniEnvelope side={side} delay={0.8} />
+      <MiniEnvelope side={side} delay={1.6} />
+    </div>
+  );
+});
+
+const GlowHandle = memo(function GlowHandle({
+  side,
+  external,
+}: {
+  side: "left" | "right";
+  external?: boolean;
+}) {
+  return (
+    <div
+      style={{
+        position: "absolute",
+        top: "50%",
+        [side]: -6,
+        transform: "translateY(-50%)",
+        width: 12,
+        height: 12,
+        borderRadius: "50%",
+        background: external
+          ? "linear-gradient(135deg, #a855f7, #7e22ce)"
+          : "linear-gradient(135deg, #ec4899, #be185d)",
+        border: "2px solid rgb(var(--ec-page-bg))",
+        zIndex: 20,
+        animation: external
+          ? "ec-external-handle-pulse 2s ease-in-out infinite"
+          : "ec-service-handle-pulse 2s ease-in-out infinite",
+        pointerEvents: "none",
+      }}
+    />
+  );
+});
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+type PostItPalette = {
+  Icon: typeof ServerIcon;
+  label: string;
+  gradient: string;
+  draftBorder: string;
+  corner: string;
+  ring: string;
+  iconClass: string;
+  labelClass: string;
+  nameText: string;
+  nameTextDeprecated: string;
+  versionClass: string;
+  summaryClass: string;
+  tooltipBorderColor: string;
+};
+
+const POST_IT_SERVICE: PostItPalette = {
+  Icon: ServerIcon,
+  label: "Service",
+  gradient: "linear-gradient(135deg, #fbcfe8 0%, #f9a8d4 40%, #ec4899 100%)",
+  draftBorder: "rgba(236, 72, 153, 0.5)",
+  corner: "#db2777",
+  ring: "ring-2 ring-pink-400/60 ring-offset-1",
+  iconClass: "w-3 h-3 text-pink-900/50",
+  labelClass: "text-[8px] font-bold text-pink-900/50 uppercase tracking-widest",
+  nameText: "text-pink-950",
+  nameTextDeprecated: "text-pink-950/40 line-through",
+  versionClass: "text-[9px] text-pink-900/40 font-semibold mt-0.5",
+  summaryClass:
+    "mt-2 pt-1.5 border-t border-pink-900/10 text-[9px] text-pink-950/60 leading-relaxed overflow-hidden",
+  tooltipBorderColor: "#ec4899",
+};
+
+const POST_IT_EXTERNAL: PostItPalette = {
+  Icon: Globe,
+  label: "External System",
+  gradient: "linear-gradient(135deg, #e9d5ff 0%, #c084fc 40%, #a855f7 100%)",
+  draftBorder: "rgba(168, 85, 247, 0.5)",
+  corner: "#7e22ce",
+  ring: "ring-2 ring-purple-400/60 ring-offset-1",
+  iconClass: "w-3 h-3 text-purple-900/50",
+  labelClass:
+    "text-[8px] font-bold text-purple-900/50 uppercase tracking-widest",
+  nameText: "text-purple-950",
+  nameTextDeprecated: "text-purple-950/40 line-through",
+  versionClass: "text-[9px] text-purple-900/40 font-semibold mt-0.5",
+  summaryClass:
+    "mt-2 pt-1.5 border-t border-purple-900/10 text-[9px] text-purple-950/60 leading-relaxed overflow-hidden",
+  tooltipBorderColor: "#a855f7",
+};
+
+type DefaultPalette = {
+  Icon: typeof ServerIcon;
+  label: string;
+  ring: string;
+  borderSolid: string;
+  borderDraftDark: string;
+  borderDraftLight: string;
+  draftStripeDark: string;
+  draftStripeLight: string;
+  nodeBgVar: string;
+  shadowColor: string;
+  badgeBg: string;
+  ownerAccent: string;
+  ownerBorder: string;
+  ownerIcon: string;
+  tooltipBorderColor: string;
+};
+
+const DEFAULT_SERVICE: DefaultPalette = {
+  Icon: ServerIcon,
+  label: "Service",
+  ring: "ring-2 ring-pink-400/60 ring-offset-2",
+  borderSolid: "border-pink-500",
+  borderDraftDark: "border-dashed border-pink-400",
+  borderDraftLight: "border-dashed border-pink-400/60",
+  draftStripeDark: "rgba(236,72,153,0.25)",
+  draftStripeLight: "rgba(236,72,153,0.15)",
+  nodeBgVar: "var(--ec-service-node-bg, rgb(var(--ec-card-bg)))",
+  shadowColor: "rgba(236, 72, 153, 0.15)",
+  badgeBg: "bg-pink-500",
+  ownerAccent: "bg-pink-400",
+  ownerBorder: "rgba(236,72,153,0.08)",
+  ownerIcon: "text-pink-300",
+  tooltipBorderColor: "#ec4899",
+};
+
+const DEFAULT_EXTERNAL: DefaultPalette = {
+  Icon: Globe,
+  label: "External System",
+  ring: "ring-2 ring-purple-400/60 ring-offset-2",
+  borderSolid: "border-purple-500",
+  borderDraftDark: "border-dashed border-purple-400",
+  borderDraftLight: "border-dashed border-purple-400/60",
+  draftStripeDark: "rgba(168,85,247,0.25)",
+  draftStripeLight: "rgba(168,85,247,0.15)",
+  nodeBgVar: "var(--ec-external-node-bg, rgb(var(--ec-card-bg)))",
+  shadowColor: "rgba(168, 85, 247, 0.15)",
+  badgeBg: "bg-purple-500",
+  ownerAccent: "bg-purple-400",
+  ownerBorder: "rgba(168,85,247,0.08)",
+  ownerIcon: "text-purple-300",
+  tooltipBorderColor: "#a855f7",
+};
+
+type ServiceNodeData = EventCatalogResource & {
+  service: ServiceType;
+};
+
+export type ServiceNode = Node<ServiceNodeData, "service">;
+
+function PostItService(props: ServiceNode) {
+  const {
+    version,
+    name,
+    summary,
+    deprecated,
+    draft,
+    notes,
+    specifications,
+    externalSystem,
+    styles,
+  } = props.data.service;
+  const mode = props.data.mode || "simple";
+  const isDark = useDarkMode();
+  const p = externalSystem ? POST_IT_EXTERNAL : POST_IT_SERVICE;
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-44 max-w-56 min-h-[120px]",
+        props?.selected ? p.ring : "",
+      )}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {/* Inner wrapper with rotation */}
+      <div
+        className="absolute inset-0"
+        style={{
+          background: p.gradient,
+          boxShadow:
+            "1px 1px 3px rgba(0,0,0,0.15), 3px 4px 8px rgba(0,0,0,0.08)",
+          transform: "rotate(1deg)",
+          border: deprecated
+            ? "2px dashed rgba(239, 68, 68, 0.5)"
+            : draft
+              ? `2px dashed ${p.draftBorder}`
+              : "none",
+        }}
+      >
+        {/* Folded corner */}
+        <div style={FOLDED_CORNER_SHADOW_STYLE} />
+        <div
+          style={{
+            position: "absolute",
+            top: 0,
+            right: 0,
+            width: 0,
+            height: 0,
+            borderStyle: "solid",
+            borderWidth: "18px 0 0 18px",
+            borderColor: `${p.corner} transparent transparent transparent`,
+            opacity: 0.3,
+          }}
+        />
+      </div>
+
+      <div className="relative px-3.5 py-3">
+        <div className="flex items-center justify-between mb-2">
+          <div className="flex items-center gap-1">
+            <p.Icon className={p.iconClass} strokeWidth={2.5} />
+            <span className={p.labelClass}>{p.label}</span>
+          </div>
+          {draft && (
+            <span className="text-[8px] font-extrabold text-amber-900 bg-amber-100 border border-dashed border-amber-400 px-1.5 py-0.5 rounded uppercase">
+              Draft
+            </span>
+          )}
+          {deprecated && (
+            <span className="text-[7px] font-bold text-white bg-red-500 border border-red-600 px-1.5 py-0.5 rounded uppercase">
+              Deprecated
+            </span>
+          )}
+        </div>
+
+        <div className="flex items-center gap-2">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className={
+                mode === "full"
+                  ? "w-[26px] h-[26px] shrink-0"
+                  : "w-6 h-6 shrink-0"
+              }
+            />
+          )}
+          <TruncatedResourceName
+            as="div"
+            value={name}
+            tooltipBorderColor={p.tooltipBorderColor}
+            className={classNames(
+              "text-[13px] font-bold leading-snug min-w-0 truncate",
+              deprecated ? p.nameTextDeprecated : p.nameText,
+            )}
+          >
+            {name}
+          </TruncatedResourceName>
+        </div>
+
+        {version && <div className={p.versionClass}>v{version}</div>}
+
+        {mode === "full" && summary && (
+          <div
+            className={p.summaryClass}
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+
+        {!!specifications && (
+          <div className="mt-1.5 flex justify-end">
+            <SpecBadges specifications={specifications} isDark={isDark} />
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function DefaultService(props: ServiceNode) {
+  const {
+    version,
+    name,
+    summary,
+    deprecated,
+    draft,
+    notes,
+    specifications,
+    externalSystem,
+    styles,
+  } = props.data.service;
+  const mode = props.data.mode || "simple";
+  const customIcon = isIconPath(styles?.icon) ? styles!.icon! : undefined;
+  const owners = useMemo(
+    () => normalizeOwners(props.data.service.owners),
+    [props.data.service.owners],
+  );
+  const targetConnections = useNodeConnections({ handleType: "target" });
+  const sourceConnections = useNodeConnections({ handleType: "source" });
+  const isDark = useDarkMode();
+  const deprecatedStripe = isDark
+    ? "rgba(239,68,68,0.25)"
+    : "rgba(239,68,68,0.1)";
+
+  const p = externalSystem ? DEFAULT_EXTERNAL : DEFAULT_SERVICE;
+  const draftStripe = isDark ? p.draftStripeDark : p.draftStripeLight;
+  const borderDraft = isDark ? p.borderDraftDark : p.borderDraftLight;
+
+  return (
+    <div
+      className={classNames(
+        "relative min-w-48 max-w-60 rounded-xl border-2 overflow-visible",
+        props?.selected ? p.ring : "",
+        deprecated
+          ? "border-dashed border-red-500"
+          : draft
+            ? borderDraft
+            : p.borderSolid,
+      )}
+      style={{
+        background: deprecated
+          ? `repeating-linear-gradient(135deg, transparent, transparent 6px, ${deprecatedStripe} 6px, ${deprecatedStripe} 7px), ${p.nodeBgVar}`
+          : draft
+            ? `repeating-linear-gradient(135deg, transparent, transparent 4px, ${draftStripe} 4px, ${draftStripe} 4.5px), repeating-linear-gradient(45deg, transparent, transparent 4px, ${draftStripe} 4px, ${draftStripe} 4.5px), ${p.nodeBgVar}`
+            : p.nodeBgVar,
+        boxShadow: `0 2px 12px ${p.shadowColor}`,
+      }}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        style={HIDDEN_HANDLE_STYLE}
+      />
+      {notes && notes.length > 0 && (
+        <NotesIndicator notes={notes} resourceName={name} />
+      )}
+      {targetConnections.length > 0 && (
+        <GlowHandle side="left" external={externalSystem} />
+      )}
+      {sourceConnections.length > 0 && (
+        <GlowHandle side="right" external={externalSystem} />
+      )}
+
+      <div className="absolute -top-2.5 left-2.5 flex items-center gap-1.5 z-10">
+        <span
+          className={classNames(
+            "inline-flex items-center gap-1 text-[7px] font-bold uppercase tracking-widest text-white px-1.5 py-0.5 rounded shadow-sm",
+            deprecated ? "bg-red-500" : p.badgeBg,
+          )}
+        >
+          <p.Icon className="w-2.5 h-2.5" strokeWidth={2.5} />
+          {p.label}
+          {draft && " (Draft)"}
+          {deprecated && " (Deprecated)"}
+        </span>
+      </div>
+
+      <div className="px-3 pt-3.5 pb-2.5">
+        <div className="flex items-center gap-2">
+          {customIcon && (
+            <CustomIcon
+              src={customIcon}
+              alt={name}
+              className={
+                mode === "full"
+                  ? "w-[26px] h-[26px] shrink-0"
+                  : "w-4 h-4 shrink-0 -my-1"
+              }
+            />
+          )}
+          <div className="flex items-baseline gap-1 min-w-0">
+            <TruncatedResourceName
+              value={name}
+              tooltipBorderColor={p.tooltipBorderColor}
+              className="text-[13px] font-semibold leading-snug text-[rgb(var(--ec-page-text))] truncate"
+            >
+              {name}
+            </TruncatedResourceName>
+            {version && (
+              <span className="text-[10px] font-normal text-[rgb(var(--ec-page-text-muted))] shrink-0">
+                (v{version})
+              </span>
+            )}
+          </div>
+        </div>
+
+        {mode === "full" && summary && (
+          <div
+            className="mt-1.5 text-[9px] text-[rgb(var(--ec-page-text-muted))] leading-relaxed overflow-hidden"
+            style={LINE_CLAMP_STYLE}
+            title={summary}
+          >
+            {summary}
+          </div>
+        )}
+
+        <div className="flex items-end justify-between gap-1">
+          <OwnerIndicator
+            owners={owners}
+            accentColor={p.ownerAccent}
+            borderColor={p.ownerBorder}
+            iconClass={p.ownerIcon}
+          />
+          {!!specifications && (
+            <SpecBadges specifications={specifications} isDark={isDark} />
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default memo(function Service(props: ServiceNode) {
+  const nodeStyle = props?.data?.style;
+
+  if (nodeStyle === "post-it") {
+    return <PostItService {...props} />;
+  }
+
+  return <DefaultService {...props} />;
+});
diff --git a/packages/visualiser/src/nodes/service/index.ts b/packages/visualiser/src/nodes/service/index.ts
new file mode 100644
index 000000000..e88189f84
--- /dev/null
+++ b/packages/visualiser/src/nodes/service/index.ts
@@ -0,0 +1,2 @@
+export { default as Service } from "./ServiceNode";
+export type { ServiceNode } from "./ServiceNode";
diff --git a/packages/visualiser/src/nodes/shared-styles.ts b/packages/visualiser/src/nodes/shared-styles.ts
new file mode 100644
index 000000000..da785bbb6
--- /dev/null
+++ b/packages/visualiser/src/nodes/shared-styles.ts
@@ -0,0 +1,129 @@
+import { type CSSProperties, useSyncExternalStore } from "react";
+
+// ─── Dark mode detection ────────────────────────────────────────────────────
+
+function subscribeTheme(callback: () => void) {
+  const observer = new MutationObserver(callback);
+  observer.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["data-theme"],
+  });
+  return () => observer.disconnect();
+}
+
+function getIsDark() {
+  return (
+    typeof document !== "undefined" &&
+    document.documentElement.getAttribute("data-theme") === "dark"
+  );
+}
+
+export function useDarkMode(): boolean {
+  return useSyncExternalStore(subscribeTheme, getIsDark, () => false);
+}
+
+/**
+ * Shared style constants for node components.
+ * Extracting inline style objects to module-level constants ensures React.memo
+ * receives stable references and can skip re-renders effectively.
+ */
+
+// ─── Common layout ──────────────────────────────────────────────────────────
+
+export const NODE_WIDTH_STYLE = { width: "260px" } as const;
+
+export const ROTATED_LABEL_STYLE = {
+  transform: "rotate(-90deg)",
+  letterSpacing: "0.15em",
+  whiteSpace: "nowrap",
+} as const satisfies CSSProperties;
+
+export const TINY_FONT_STYLE = { fontSize: "0.2em" } as const;
+
+// ─── WebKit line clamp (summary truncation) ─────────────────────────────────
+
+export const LINE_CLAMP_STYLE = {
+  display: "-webkit-box",
+  WebkitLineClamp: 2,
+  WebkitBoxOrient: "vertical",
+} as const satisfies CSSProperties;
+
+// ─── Watermark icon ─────────────────────────────────────────────────────────
+
+export const WATERMARK_STYLE = {
+  opacity: 0.2,
+  transform: "rotate(12deg)",
+} as const;
+
+// ─── Post-it folded corner (identical across all post-it nodes) ─────────────
+
+export const FOLDED_CORNER_SHADOW_STYLE = {
+  position: "absolute",
+  top: 0,
+  right: 0,
+  width: 0,
+  height: 0,
+  borderStyle: "solid",
+  borderWidth: "0 18px 18px 0",
+  borderColor: "transparent #1e293b12 transparent transparent",
+} as const satisfies CSSProperties;
+
+// ─── Post-it common shadow ─────────────────────────────────────────────────
+
+export const POST_IT_BOX_SHADOW =
+  "1px 1px 3px rgba(0,0,0,0.15), 3px 4px 8px rgba(0,0,0,0.08)";
+
+// ─── Handle positioning ─────────────────────────────────────────────────────
+
+export const HANDLE_LEFT_STYLE = { left: "-1px" } as const;
+export const HANDLE_RIGHT_STYLE = { right: "-1px" } as const;
+export const HANDLE_LEFT_OFFSET_STYLE = { left: "-6px" } as const;
+export const HANDLE_RIGHT_OFFSET_STYLE = { right: "-6px" } as const;
+
+// ─── Note/Full size style ───────────────────────────────────────────────────
+
+export const FULL_SIZE_STYLE = { width: "100%", height: "100%" } as const;
+
+// ─── Owner indicator icon size ──────────────────────────────────────────────
+
+export const OWNER_ICON_SIZE_STYLE = { width: 10, height: 10 } as const;
+
+// ─── ExternalSystem2 handle ─────────────────────────────────────────────────
+
+export const EXTERNAL_SYSTEM_HANDLE_STYLE = {
+  width: 10,
+  height: 10,
+  background: "pink",
+  zIndex: 10,
+} as const;
+
+// ─── Edge styles ────────────────────────────────────────────────────────────
+
+export const EDGE_WARNING_STYLE = {
+  stroke: "red",
+  strokeWidth: 2.625,
+  strokeDasharray: "5 5",
+} as const;
+
+export const EDGE_DEFAULT_STYLE = {
+  stroke: "var(--ec-edge-stroke, #d1d5db)",
+  strokeWidth: 2.625,
+  strokeDasharray: "5 5",
+} as const;
+
+export const EDGE_FLOW_BASE_STYLE = {
+  strokeWidth: 3,
+  stroke: "var(--ec-edge-stroke, #6b7280)",
+  strokeDasharray: "5 5",
+} as const;
+
+// ─── Default empty values (stable references for default props) ─────────────
+
+export const EMPTY_ARRAY: any[] = [];
+export const EMPTY_OBJECT: Readonly<Record<string, never>> = {} as const;
+
+// ─── Channel message queue ──────────────────────────────────────────────────
+
+export const QUEUE_BORDER_STYLE = {
+  borderTop: "1px dashed rgb(var(--ec-page-border))",
+} as const;
diff --git a/packages/visualiser/src/nodes/view/ViewNode.tsx b/packages/visualiser/src/nodes/view/ViewNode.tsx
new file mode 100644
index 000000000..e01d1a1ca
--- /dev/null
+++ b/packages/visualiser/src/nodes/view/ViewNode.tsx
@@ -0,0 +1,96 @@
+import { memo } from "react";
+import { MonitorIcon } from "lucide-react";
+import { Node, Handle, Position } from "@xyflow/react";
+import { EventCatalogResource, View as ViewType } from "../../types";
+import {
+  NODE_WIDTH_STYLE,
+  ROTATED_LABEL_STYLE,
+  LINE_CLAMP_STYLE,
+} from "../shared-styles";
+
+function classNames(...classes: any) {
+  return classes.filter(Boolean).join(" ");
+}
+
+type ViewNodeData = EventCatalogResource & {
+  view: ViewType;
+};
+
+export type ViewNode = Node<ViewNodeData, "view">;
+
+export default memo(function View(props: ViewNode) {
+  const { data: _data, selected } = props;
+  const { name, summary, screenshot } = props.data.view;
+
+  const mode = props.data.mode || "simple";
+
+  const nodeLabel = "View";
+
+  return (
+    <div
+      className={classNames(
+        "rounded-md border flex justify-start bg-[rgb(var(--ec-card-bg))] text-[rgb(var(--ec-page-text))] min-h-[100px] relative",
+        selected
+          ? "border-blue-600 ring-2 ring-blue-500 shadow-lg"
+          : "border-blue-400",
+      )}
+      style={NODE_WIDTH_STYLE}
+    >
+      <Handle
+        type="target"
+        position={Position.Left}
+        className="!left-[-1px] !w-2.5 !h-2.5 !bg-blue-500 !border !border-blue-600 !rounded-full !z-10"
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        className="!right-[-1px] !w-2.5 !h-2.5 !bg-blue-500 !border !border-blue-600 !rounded-full !z-10"
+      />
+      <div
+        className={`bg-gradient-to-b from-blue-500 to-blue-700 relative flex flex-col items-center w-5 justify-between rounded-l-sm text-blue-100 border-r-[1px] border-blue-500`}
+      >
+        <MonitorIcon
+          className={`w-4 h-4 opacity-90 text-white mt-1 ${mode === "full" ? "mb-2" : "mb-1"}`}
+        />
+        {mode === "full" && (
+          <span
+            className="text-center text-[8px] text-white font-bold uppercase mb-4"
+            style={ROTATED_LABEL_STYLE}
+          >
+            {nodeLabel}
+          </span>
+        )}
+      </div>
+      <div className="p-1 flex-1">
+        <div className="pb-1">
+          <span className="text-xs font-bold block pt-0.5 pb-0.5">{name}</span>
+          {mode === "simple" && (
+            <span className="text-[10px] text-[rgb(var(--ec-page-text-muted))] font-light block pt-0.5 pb-0.5">
+              {nodeLabel}
+            </span>
+          )}
+        </div>
+        {summary && (
+          <div className="pb-1">
+            <div
+              className="text-[8px] font-light text-[rgb(var(--ec-page-text-muted))] block leading-tight overflow-hidden"
+              style={LINE_CLAMP_STYLE}
+              title={summary}
+            >
+              {summary}
+            </div>
+          </div>
+        )}
+        {screenshot && (
+          <div className="py-1">
+            <img
+              src={screenshot}
+              alt={`${name} screenshot`}
+              className="w-full max-w-40 h-20 object-cover rounded border border-[rgb(var(--ec-page-border))]"
+            />
+          </div>
+        )}
+      </div>
+    </div>
+  );
+});
diff --git a/packages/visualiser/src/nodes/view/index.ts b/packages/visualiser/src/nodes/view/index.ts
new file mode 100644
index 000000000..05c20a6fb
--- /dev/null
+++ b/packages/visualiser/src/nodes/view/index.ts
@@ -0,0 +1 @@
+export { default as View, type ViewNode } from "./ViewNode";
diff --git a/packages/visualiser/src/safelist.txt b/packages/visualiser/src/safelist.txt
new file mode 100644
index 000000000..edc9316d4
--- /dev/null
+++ b/packages/visualiser/src/safelist.txt
@@ -0,0 +1,57 @@
+<!--
+  Tailwind CSS Safelist
+  These classes are used dynamically in Flow.tsx and Custom.tsx via template literals like:
+    border-${color}-400, from-${color}-500, to-${color}-700, text-${color}-100, border-${color}-500
+  Tailwind can't detect them at build time, so we list them here.
+-->
+
+<!-- teal (Flow default) -->
+border-teal-400 from-teal-500 to-teal-700 text-teal-100 border-teal-500 from-teal-400 to-teal-600
+
+<!-- blue (Custom default) -->
+border-blue-400 from-blue-500 to-blue-700 text-blue-100 border-blue-500 from-blue-400 to-blue-600 border-blue
+
+<!-- red -->
+border-red-400 from-red-500 to-red-700 text-red-100 border-red-500 from-red-400 to-red-600 border-red
+
+<!-- green -->
+border-green-400 from-green-500 to-green-700 text-green-100 border-green-500 from-green-400 to-green-600 border-green
+
+<!-- purple -->
+border-purple-400 from-purple-500 to-purple-700 text-purple-100 border-purple-500 from-purple-400 to-purple-600 border-purple
+
+<!-- orange -->
+border-orange-400 from-orange-500 to-orange-700 text-orange-100 border-orange-500 from-orange-400 to-orange-600 border-orange
+
+<!-- pink -->
+border-pink-400 from-pink-500 to-pink-700 text-pink-100 border-pink-500 from-pink-400 to-pink-600 border-pink
+
+<!-- yellow -->
+border-yellow-400 from-yellow-500 to-yellow-700 text-yellow-100 border-yellow-500 from-yellow-400 to-yellow-600 border-yellow
+
+<!-- gray -->
+border-gray-400 from-gray-500 to-gray-700 text-gray-100 border-gray-500 from-gray-400 to-gray-600 border-gray
+
+<!-- indigo -->
+border-indigo-400 from-indigo-500 to-indigo-700 text-indigo-100 border-indigo-500 from-indigo-400 to-indigo-600 border-indigo
+
+<!-- sky -->
+border-sky-400 from-sky-500 to-sky-700 text-sky-100 border-sky-500 from-sky-400 to-sky-600 border-sky bg-sky-500 bg-sky-600 text-sky-300 text-sky-500 text-sky-700 ring-sky-400
+
+<!-- cyan -->
+border-cyan-400 from-cyan-500 to-cyan-700 text-cyan-100 border-cyan-500 from-cyan-400 to-cyan-600 border-cyan
+
+<!-- slate -->
+border-slate-400 from-slate-500 to-slate-700 text-slate-100 border-slate-500 from-slate-400 to-slate-600 border-slate
+
+<!-- amber -->
+border-amber-400 from-amber-500 to-amber-700 text-amber-100 border-amber-500 from-amber-400 to-amber-600 border-amber
+
+<!-- emerald -->
+border-emerald-400 from-emerald-500 to-emerald-700 text-emerald-100 border-emerald-500 from-emerald-400 to-emerald-600 border-emerald
+
+<!-- violet -->
+border-violet-400 from-violet-500 to-violet-700 text-violet-100 border-violet-500 from-violet-400 to-violet-600 border-violet
+
+<!-- rose -->
+border-rose-400 from-rose-500 to-rose-700 text-rose-100 border-rose-500 from-rose-400 to-rose-600 border-rose
diff --git a/packages/visualiser/src/styles-core.css b/packages/visualiser/src/styles-core.css
new file mode 100644
index 000000000..08c4623f2
--- /dev/null
+++ b/packages/visualiser/src/styles-core.css
@@ -0,0 +1,389 @@
+@import "tailwindcss/theme";
+@import "tailwindcss/utilities";
+@import '@xyflow/react/dist/style.css';
+
+@source "../src/**/*.{js,ts,jsx,tsx}";
+@source "../src/safelist.txt";
+
+/**
+ * EventCatalog Visualizer Theme Variables
+ *
+ * These CSS variables provide theming support for the visualizer.
+ * They can be customized by the consuming application.
+ */
+
+.eventcatalog-visualizer {
+  /* Background colors */
+  --ec-page-bg: 255, 255, 255;
+  --ec-card-bg: 255, 255, 255;
+
+  /* Text colors */
+  --ec-page-text: 17, 24, 39;
+  --ec-page-text-muted: 55, 65, 81;
+
+  /* Border colors */
+  --ec-page-border: 229, 231, 235;
+
+  /* Accent colors */
+  --ec-accent: 79, 70, 229;
+  --ec-accent-subtle: 238, 242, 255;
+  --ec-accent-text: 255, 255, 255;
+
+  /* Button colors */
+  --ec-button-bg: 79, 70, 229;
+  --ec-button-text: 255, 255, 255;
+
+  /* Icon colors */
+  --ec-icon-color: 107, 114, 128;
+  --ec-icon-hover: 79, 70, 229;
+
+  /* Input colors */
+  --ec-input-bg: 255, 255, 255;
+  --ec-input-border: 209, 213, 219;
+  --ec-input-text: 17, 24, 39;
+
+  /* Group/Domain node colors (full rgba values for inline style compat) */
+  --ec-group-border: #c4b5fd;
+  --ec-group-bg: rgba(250, 248, 255, 0.35);
+  --ec-group-header-bg: rgba(237, 233, 254, 0.7);
+  --ec-group-text: #5b21b6;
+}
+
+/* Dark mode theme — aligned with EventCatalog core (GitHub-dark) */
+[data-theme="dark"] .eventcatalog-visualizer {
+  /* Background colors */
+  --ec-page-bg: 22, 27, 34; /* #161b22 — dark canvas, lowest layer */
+  --ec-card-bg: 40, 46, 56; /* #282e38 — node surfaces float above canvas */
+
+  /* Text colors */
+  --ec-page-text: 240, 246, 252; /* #f0f6fc */
+  --ec-page-text-muted: 139, 148, 158; /* #8b949e */
+
+  /* Border colors */
+  --ec-page-border: 48, 54, 61; /* #30363d */
+
+  /* Accent colors */
+  --ec-accent: 192, 132, 252; /* #c084fc (purple-400) */
+  --ec-accent-subtle: 88, 28, 135; /* purple-900 */
+  --ec-accent-text: 216, 180, 254; /* #d8b4fe (purple-300) */
+
+  /* Button colors */
+  --ec-button-bg: 147, 51, 234; /* #9333ea */
+  --ec-button-text: 255, 255, 255;
+
+  /* Icon colors */
+  --ec-icon-color: 139, 148, 158; /* #8b949e */
+  --ec-icon-hover: 240, 246, 252; /* #f0f6fc */
+
+  /* Input colors */
+  --ec-input-bg: 22, 27, 34; /* #161b22 */
+  --ec-input-border: 48, 54, 61; /* #30363d */
+  --ec-input-text: 240, 246, 252; /* #f0f6fc */
+
+  /* Group/Domain node colors — deep purple on dark */
+  --ec-group-border: #7c3aed;
+  --ec-group-bg: #1e1533;
+  --ec-group-header-bg: #2d1f4e;
+  --ec-group-text: #c084fc;
+}
+
+/* Hide download button on small screens without emitting a global .hidden rule */
+.ec-download-btn {
+  display: none;
+}
+
+/* Base styles for visualizer container */
+.eventcatalog-visualizer {
+  /* Ensure the container itself has dimensions (scoped utilities only apply to descendants) */
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  background-color: rgb(var(--ec-page-bg));
+  /* Light-mode canvas: grey background (matches Tailwind gray-50) */
+  --ec-page-bg: 249, 250, 251;
+  --ec-bg-dots: #bbb;
+  --ec-edge-stroke: #6b7280;
+  --ec-service-node-bg: #fef7fb;
+  --ec-event-node-bg: #fff8f5;
+  --ec-command-node-bg: #f5f8ff;
+  --ec-query-node-bg: #f5fdf8;
+  --ec-channel-node-bg: #f8f8f9;
+  --ec-data-node-bg: #f5f8ff;
+  --ec-dp-node-bg: #f7f5ff;
+  --ec-external-node-bg: #faf5ff;
+  --ec-actor-node-bg: #fffdf5;
+  --ec-custom-node-bg: #f8fbff;
+  --ec-message-group-node-bg: #f9f5ff;
+  --ec-deprecated-stripe: rgba(239, 68, 68, 0.3);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+    sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+.eventcatalog-visualizer img {
+  margin: 0;
+  background-color: transparent;
+}
+
+/*
+ * Scoped dark mode overrides for the visualizer.
+ * Higher specificity ensures these win over the consuming app's
+ * global [data-theme="dark"] variables, giving the visualizer
+ * its own lighter canvas + lifted card surfaces.
+ */
+[data-theme="dark"] .eventcatalog-visualizer {
+  --ec-bg-dots: #5a6270;
+  --ec-edge-stroke: #6e7681;
+  --ec-page-bg: 22, 27, 34;
+  --ec-card-bg: 40, 46, 56;
+  --ec-page-border: 48, 54, 61;
+  --ec-page-text: 240, 246, 252;
+  --ec-page-text-muted: 220, 225, 232;
+  --ec-service-node-bg: rgb(40, 46, 56);
+  --ec-event-node-bg: rgb(40, 46, 56);
+  --ec-command-node-bg: rgb(40, 46, 56);
+  --ec-query-node-bg: rgb(40, 46, 56);
+  --ec-channel-node-bg: rgb(40, 46, 56);
+  --ec-data-node-bg: rgb(40, 46, 56);
+  --ec-dp-node-bg: rgb(40, 46, 56);
+  --ec-external-node-bg: rgb(40, 46, 56);
+  --ec-actor-node-bg: rgb(40, 46, 56);
+  --ec-custom-node-bg: rgb(40, 46, 56);
+  --ec-message-group-node-bg: rgb(40, 46, 56);
+  --ec-deprecated-stripe: rgba(239, 68, 68, 0.25);
+  --ec-input-bg: 22, 27, 34;
+  --ec-input-border: 48, 54, 61;
+  --ec-input-text: 240, 246, 252;
+  --ec-accent: 192, 132, 252;
+  --ec-accent-subtle: 88, 28, 135;
+  --ec-accent-text: 216, 180, 254;
+  --ec-button-bg: 147, 51, 234;
+  --ec-button-text: 255, 255, 255;
+  --ec-icon-color: 139, 148, 158;
+  --ec-icon-hover: 240, 246, 252;
+}
+
+/* Node handle pulse animations (shared across all node types) */
+@keyframes ec-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(251, 146, 60, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(251, 146, 60, 0); }
+}
+@keyframes ec-service-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(236, 72, 153, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(236, 72, 153, 0); }
+}
+@keyframes ec-svc-msg-in {
+  0% { transform: translateX(-18px) scale(0.7); opacity: 0; }
+  30% { opacity: 0.7; }
+  70% { opacity: 0.7; }
+  100% { transform: translateX(0) scale(0.5); opacity: 0; }
+}
+@keyframes ec-svc-msg-out {
+  0% { transform: translateX(0) scale(0.5); opacity: 0; }
+  30% { opacity: 0.7; }
+  70% { opacity: 0.7; }
+  100% { transform: translateX(18px) scale(0.7); opacity: 0; }
+}
+@keyframes ec-command-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(59, 130, 246, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(59, 130, 246, 0); }
+}
+@keyframes ec-query-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(34, 197, 94, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(34, 197, 94, 0); }
+}
+@keyframes ec-data-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(59, 130, 246, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(59, 130, 246, 0); }
+}
+@keyframes ec-channel-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(107, 114, 128, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(107, 114, 128, 0); }
+}
+@keyframes ec-actor-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(234, 179, 8, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(234, 179, 8, 0); }
+}
+@keyframes ec-external-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(168, 85, 247, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(168, 85, 247, 0); }
+}
+@keyframes ec-dp-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(99, 102, 241, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(99, 102, 241, 0); }
+}
+
+/* ReactFlow customizations */
+.react-flow {
+  background-color: #f1f5f9 !important; /* slate-100 — light mode default */
+}
+
+[data-theme="dark"] .react-flow {
+  background-color: rgb(var(--ec-page-bg)) !important;
+}
+
+.react-flow__node {
+  cursor: pointer;
+}
+
+.react-flow__node:hover .ec-truncated-resource-name-tooltip {
+  display: block;
+}
+
+/* Smooth transition when expanding/collapsing message groups */
+.ec-animating-layout .react-flow__node {
+  transition: transform 0.35s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.react-flow__edge-path {
+  stroke: var(--ec-edge-stroke, #6b7280) !important;
+  stroke-width: 1.5 !important;
+  transition: stroke-width 0.15s ease;
+}
+
+/* Theme-aware arrow markers */
+.react-flow__edges marker path {
+  fill: var(--ec-edge-stroke, #6b7280);
+  stroke: var(--ec-edge-stroke, #6b7280);
+}
+
+/* Widen the invisible interaction area for edges */
+.react-flow__edge-interaction {
+  stroke-width: 40 !important;
+  cursor: pointer;
+}
+
+/* Highlight the entire edge on hover — "electricity flowing" effect */
+.react-flow__edge:hover .react-flow__edge-path,
+.ec-node-hover-edge .react-flow__edge-path {
+  stroke: #2563eb !important;
+  stroke-width: 4 !important;
+  filter: drop-shadow(0 0 8px #2563eb) !important;
+  opacity: 1 !important;
+  stroke-dasharray: 5 5 !important;
+  animation: ec-edge-dash 0.5s linear infinite !important;
+}
+
+/* Bold the edge label on hover */
+.react-flow__edge:hover text,
+.ec-node-hover-edge text {
+  font-weight: 700 !important;
+  font-size: 12px !important;
+}
+
+.react-flow__edge:hover .react-flow__edge-textbg,
+.ec-node-hover-edge .react-flow__edge-textbg {
+  fill-opacity: 1 !important;
+}
+
+/* Edge label rendered via EdgeLabelRenderer (HTML) */
+.react-flow__edge:hover + .react-flow__edgelabel-renderer > div,
+.react-flow__edge.ec-node-hover-edge + .react-flow__edgelabel-renderer > div {
+  font-weight: 700 !important;
+}
+
+[data-theme="dark"] .react-flow__edge:hover .react-flow__edge-path,
+[data-theme="dark"] .ec-node-hover-edge .react-flow__edge-path {
+  stroke: #00d9ff !important;
+  filter: drop-shadow(0 0 8px #00d9ff) !important;
+}
+
+@keyframes ec-edge-dash {
+  to {
+    stroke-dashoffset: -10;
+  }
+}
+
+/* Pulse the border of source/target nodes when an edge is hovered */
+.ec-edge-hover-node {
+  outline: 3px solid #2563eb !important;
+  outline-offset: 2px;
+  border-radius: 12px !important;
+  animation: ec-node-pulse 1s ease-in-out infinite !important;
+}
+
+@keyframes ec-node-pulse {
+  0%, 100% { outline-color: rgba(37, 99, 235, 0.8); }
+  50% { outline-color: rgba(37, 99, 235, 0.2); }
+}
+
+[data-theme="dark"] .ec-edge-hover-node {
+  outline-color: #00d9ff !important;
+  animation-name: ec-node-pulse-dark !important;
+}
+
+@keyframes ec-node-pulse-dark {
+  0%, 100% { outline-color: rgba(0, 217, 255, 0.8); }
+  50% { outline-color: rgba(0, 217, 255, 0.2); }
+}
+
+/* Edge label theming for default ReactFlow edges */
+.react-flow__edge-textbg {
+  fill: rgb(var(--ec-page-bg));
+}
+
+.react-flow__edge-text {
+  fill: rgb(var(--ec-page-text));
+}
+
+.react-flow__controls {
+  background-color: rgb(var(--ec-card-bg)) !important;
+  border: 1px solid rgb(var(--ec-page-border)) !important;
+  border-radius: 8px !important;
+  overflow: hidden;
+}
+
+.react-flow__controls-button {
+  background-color: rgb(var(--ec-card-bg)) !important;
+  color: rgb(var(--ec-page-text)) !important;
+  border-bottom: 1px solid rgb(var(--ec-page-border)) !important;
+}
+
+.react-flow__controls-button svg {
+  fill: rgb(var(--ec-page-text)) !important;
+}
+
+.react-flow__controls-button:hover {
+  background-color: rgb(var(--ec-accent-subtle)) !important;
+}
+
+.react-flow__controls-button:hover svg {
+  fill: rgb(var(--ec-accent-text)) !important;
+}
+
+/* Notes modal close button */
+.ec-notes-close-btn {
+  width: 30px;
+  height: 30px;
+  border-radius: 8px;
+  border: none;
+  background: rgba(0, 0, 0, 0.04);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  color: #94a3b8;
+  flex-shrink: 0;
+  transition: background 0.15s, color 0.15s;
+}
+
+.ec-notes-close-btn:hover {
+  background: rgba(0, 0, 0, 0.08);
+  color: #475569;
+}
+
+/* Hide animated message envelopes/circles during user interaction (drag/pan/zoom).
+   SMIL animateMotion can't be paused via CSS, so we hide the elements entirely
+   to avoid expensive SVG repaints while ReactFlow transforms are updating. */
+.ec-interaction-active .ec-animated-msg {
+  visibility: hidden;
+}
+
+/* Minimap customizations */
+.react-flow__minimap {
+  background-color: rgb(var(--ec-card-bg));
+  border: 1px solid rgb(var(--ec-page-border));
+}
diff --git a/packages/visualiser/src/styles.css b/packages/visualiser/src/styles.css
new file mode 100644
index 000000000..c13e433cf
--- /dev/null
+++ b/packages/visualiser/src/styles.css
@@ -0,0 +1,379 @@
+@import "tailwindcss/theme";
+@import "tailwindcss/utilities";
+@import '@xyflow/react/dist/style.css';
+
+@source "../src/**/*.{js,ts,jsx,tsx}";
+@source "../src/safelist.txt";
+
+/**
+ * EventCatalog Visualizer Theme Variables
+ *
+ * These CSS variables provide theming support for the visualizer.
+ * They can be customized by the consuming application.
+ */
+
+:root {
+  /* Background colors */
+  --ec-page-bg: 255, 255, 255;
+  --ec-card-bg: 255, 255, 255;
+
+  /* Text colors */
+  --ec-page-text: 17, 24, 39;
+  --ec-page-text-muted: 55, 65, 81;
+
+  /* Border colors */
+  --ec-page-border: 229, 231, 235;
+
+  /* Accent colors */
+  --ec-accent: 79, 70, 229;
+  --ec-accent-subtle: 238, 242, 255;
+  --ec-accent-text: 255, 255, 255;
+
+  /* Button colors */
+  --ec-button-bg: 79, 70, 229;
+  --ec-button-text: 255, 255, 255;
+
+  /* Icon colors */
+  --ec-icon-color: 107, 114, 128;
+  --ec-icon-hover: 79, 70, 229;
+
+  /* Input colors */
+  --ec-input-bg: 255, 255, 255;
+  --ec-input-border: 209, 213, 219;
+  --ec-input-text: 17, 24, 39;
+
+  /* Group/Domain node colors (full rgba values for inline style compat) */
+  --ec-group-border: #c4b5fd;
+  --ec-group-bg: rgba(250, 248, 255, 0.35);
+  --ec-group-header-bg: rgba(237, 233, 254, 0.7);
+  --ec-group-text: #5b21b6;
+}
+
+/* Dark mode theme — aligned with EventCatalog core (GitHub-dark) */
+[data-theme="dark"] {
+  /* Background colors */
+  --ec-page-bg: 22, 27, 34; /* #161b22 — dark canvas, lowest layer */
+  --ec-card-bg: 40, 46, 56; /* #282e38 — node surfaces float above canvas */
+
+  /* Text colors */
+  --ec-page-text: 240, 246, 252; /* #f0f6fc */
+  --ec-page-text-muted: 139, 148, 158; /* #8b949e */
+
+  /* Border colors */
+  --ec-page-border: 48, 54, 61; /* #30363d */
+
+  /* Accent colors */
+  --ec-accent: 192, 132, 252; /* #c084fc (purple-400) */
+  --ec-accent-subtle: 88, 28, 135; /* purple-900 */
+  --ec-accent-text: 216, 180, 254; /* #d8b4fe (purple-300) */
+
+  /* Button colors */
+  --ec-button-bg: 147, 51, 234; /* #9333ea */
+  --ec-button-text: 255, 255, 255;
+
+  /* Icon colors */
+  --ec-icon-color: 139, 148, 158; /* #8b949e */
+  --ec-icon-hover: 240, 246, 252; /* #f0f6fc */
+
+  /* Input colors */
+  --ec-input-bg: 22, 27, 34; /* #161b22 */
+  --ec-input-border: 48, 54, 61; /* #30363d */
+  --ec-input-text: 240, 246, 252; /* #f0f6fc */
+
+  /* Group/Domain node colors — deep purple on dark */
+  --ec-group-border: #7c3aed;
+  --ec-group-bg: #1e1533;
+  --ec-group-header-bg: #2d1f4e;
+  --ec-group-text: #c084fc;
+}
+
+/* Hide download button on small screens without emitting a global .hidden rule */
+.ec-download-btn {
+  display: none;
+}
+
+/* Base styles for visualizer container */
+.eventcatalog-visualizer {
+  /* Ensure the container itself has dimensions (scoped utilities only apply to descendants) */
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  background-color: rgb(var(--ec-page-bg));
+  /* Light-mode canvas: grey background (matches Tailwind gray-50) */
+  --ec-page-bg: 249, 250, 251;
+  --ec-bg-dots: #bbb;
+  --ec-edge-stroke: #6b7280;
+  --ec-service-node-bg: #fef7fb;
+  --ec-event-node-bg: #fff8f5;
+  --ec-command-node-bg: #f5f8ff;
+  --ec-query-node-bg: #f5fdf8;
+  --ec-channel-node-bg: #f8f8f9;
+  --ec-data-node-bg: #f5f8ff;
+  --ec-dp-node-bg: #f7f5ff;
+  --ec-external-node-bg: #faf5ff;
+  --ec-actor-node-bg: #fffdf5;
+  --ec-custom-node-bg: #f8fbff;
+  --ec-message-group-node-bg: #f9f5ff;
+  --ec-deprecated-stripe: rgba(239, 68, 68, 0.3);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+    sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+.eventcatalog-visualizer img {
+  margin: 0;
+  background-color: transparent;
+}
+
+/*
+ * Scoped dark mode overrides for the visualizer.
+ * Higher specificity ensures these win over the consuming app's
+ * global [data-theme="dark"] variables, giving the visualizer
+ * its own lighter canvas + lifted card surfaces.
+ */
+[data-theme="dark"] .eventcatalog-visualizer {
+  --ec-bg-dots: #5a6270;
+  --ec-edge-stroke: #6e7681;
+  --ec-page-bg: 22, 27, 34;
+  --ec-card-bg: 40, 46, 56;
+  --ec-page-border: 48, 54, 61;
+  --ec-page-text: 240, 246, 252;
+  --ec-page-text-muted: 220, 225, 232;
+  --ec-service-node-bg: rgb(40, 46, 56);
+  --ec-event-node-bg: rgb(40, 46, 56);
+  --ec-command-node-bg: rgb(40, 46, 56);
+  --ec-query-node-bg: rgb(40, 46, 56);
+  --ec-channel-node-bg: rgb(40, 46, 56);
+  --ec-data-node-bg: rgb(40, 46, 56);
+  --ec-dp-node-bg: rgb(40, 46, 56);
+  --ec-external-node-bg: rgb(40, 46, 56);
+  --ec-actor-node-bg: rgb(40, 46, 56);
+  --ec-custom-node-bg: rgb(40, 46, 56);
+  --ec-message-group-node-bg: rgb(40, 46, 56);
+  --ec-deprecated-stripe: rgba(239, 68, 68, 0.25);
+  --ec-input-bg: 22, 27, 34;
+  --ec-input-border: 48, 54, 61;
+  --ec-input-text: 240, 246, 252;
+  --ec-accent: 192, 132, 252;
+  --ec-accent-subtle: 88, 28, 135;
+  --ec-accent-text: 216, 180, 254;
+  --ec-button-bg: 147, 51, 234;
+  --ec-button-text: 255, 255, 255;
+  --ec-icon-color: 139, 148, 158;
+  --ec-icon-hover: 240, 246, 252;
+}
+
+/* Node handle pulse animations (shared across all node types) */
+@keyframes ec-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(251, 146, 60, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(251, 146, 60, 0); }
+}
+@keyframes ec-service-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(236, 72, 153, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(236, 72, 153, 0); }
+}
+@keyframes ec-svc-msg-in {
+  0% { transform: translateX(-18px) scale(0.7); opacity: 0; }
+  30% { opacity: 0.7; }
+  70% { opacity: 0.7; }
+  100% { transform: translateX(0) scale(0.5); opacity: 0; }
+}
+@keyframes ec-svc-msg-out {
+  0% { transform: translateX(0) scale(0.5); opacity: 0; }
+  30% { opacity: 0.7; }
+  70% { opacity: 0.7; }
+  100% { transform: translateX(18px) scale(0.7); opacity: 0; }
+}
+@keyframes ec-command-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(59, 130, 246, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(59, 130, 246, 0); }
+}
+@keyframes ec-query-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(34, 197, 94, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(34, 197, 94, 0); }
+}
+@keyframes ec-data-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(59, 130, 246, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(59, 130, 246, 0); }
+}
+@keyframes ec-channel-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(107, 114, 128, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(107, 114, 128, 0); }
+}
+@keyframes ec-actor-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(234, 179, 8, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(234, 179, 8, 0); }
+}
+@keyframes ec-external-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(168, 85, 247, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(168, 85, 247, 0); }
+}
+@keyframes ec-dp-handle-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(99, 102, 241, 0.5); }
+  50% { box-shadow: 0 0 0 5px rgba(99, 102, 241, 0); }
+}
+
+/* ReactFlow customizations */
+.react-flow {
+  background-color: #f1f5f9 !important; /* slate-100 — light mode default */
+}
+
+[data-theme="dark"] .react-flow {
+  background-color: rgb(var(--ec-page-bg)) !important;
+}
+
+.react-flow__node {
+  cursor: pointer;
+}
+
+/* Smooth transition when expanding/collapsing message groups */
+.ec-animating-layout .react-flow__node {
+  transition: transform 0.35s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.react-flow__edge-path {
+  stroke: var(--ec-edge-stroke, #6b7280) !important;
+  stroke-width: 1.5 !important;
+  transition: stroke-width 0.15s ease;
+}
+
+/* Widen the invisible interaction area for edges */
+.react-flow__edge-interaction {
+  stroke-width: 40 !important;
+  cursor: pointer;
+}
+
+/* Highlight the entire edge on hover — "electricity flowing" effect */
+.react-flow__edge:hover .react-flow__edge-path,
+.ec-node-hover-edge .react-flow__edge-path {
+  stroke: #2563eb !important;
+  stroke-width: 4 !important;
+  filter: drop-shadow(0 0 8px #2563eb) !important;
+  opacity: 1 !important;
+  stroke-dasharray: 5 5 !important;
+  animation: ec-edge-dash 0.5s linear infinite !important;
+}
+
+/* Bold the edge label on hover */
+.react-flow__edge:hover text,
+.ec-node-hover-edge text {
+  font-weight: 700 !important;
+  font-size: 12px !important;
+}
+
+.react-flow__edge:hover .react-flow__edge-textbg,
+.ec-node-hover-edge .react-flow__edge-textbg {
+  fill-opacity: 1 !important;
+}
+
+/* Edge label rendered via EdgeLabelRenderer (HTML) */
+.react-flow__edge:hover + .react-flow__edgelabel-renderer > div,
+.react-flow__edge.ec-node-hover-edge + .react-flow__edgelabel-renderer > div {
+  font-weight: 700 !important;
+}
+
+[data-theme="dark"] .react-flow__edge:hover .react-flow__edge-path,
+[data-theme="dark"] .ec-node-hover-edge .react-flow__edge-path {
+  stroke: #00d9ff !important;
+  filter: drop-shadow(0 0 8px #00d9ff) !important;
+}
+
+@keyframes ec-edge-dash {
+  to {
+    stroke-dashoffset: -10;
+  }
+}
+
+/* Pulse the border of source/target nodes when an edge is hovered */
+.ec-edge-hover-node {
+  outline: 3px solid #2563eb !important;
+  outline-offset: 2px;
+  border-radius: 12px !important;
+  animation: ec-node-pulse 1s ease-in-out infinite !important;
+}
+
+@keyframes ec-node-pulse {
+  0%, 100% { outline-color: rgba(37, 99, 235, 0.8); }
+  50% { outline-color: rgba(37, 99, 235, 0.2); }
+}
+
+[data-theme="dark"] .ec-edge-hover-node {
+  outline-color: #00d9ff !important;
+  animation-name: ec-node-pulse-dark !important;
+}
+
+@keyframes ec-node-pulse-dark {
+  0%, 100% { outline-color: rgba(0, 217, 255, 0.8); }
+  50% { outline-color: rgba(0, 217, 255, 0.2); }
+}
+
+/* Edge label theming for default ReactFlow edges */
+.react-flow__edge-textbg {
+  fill: rgb(var(--ec-page-bg));
+}
+
+.react-flow__edge-text {
+  fill: rgb(var(--ec-page-text));
+}
+
+.react-flow__controls {
+  background-color: rgb(var(--ec-card-bg)) !important;
+  border: 1px solid rgb(var(--ec-page-border)) !important;
+  border-radius: 8px !important;
+  overflow: hidden;
+}
+
+.react-flow__controls-button {
+  background-color: rgb(var(--ec-card-bg)) !important;
+  color: rgb(var(--ec-page-text)) !important;
+  border-bottom: 1px solid rgb(var(--ec-page-border)) !important;
+}
+
+.react-flow__controls-button svg {
+  fill: rgb(var(--ec-page-text)) !important;
+}
+
+.react-flow__controls-button:hover {
+  background-color: rgb(var(--ec-accent-subtle)) !important;
+}
+
+.react-flow__controls-button:hover svg {
+  fill: rgb(var(--ec-accent-text)) !important;
+}
+
+/* Notes modal close button */
+.ec-notes-close-btn {
+  width: 30px;
+  height: 30px;
+  border-radius: 8px;
+  border: none;
+  background: rgba(0, 0, 0, 0.04);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  color: #94a3b8;
+  flex-shrink: 0;
+  transition: background 0.15s, color 0.15s;
+}
+
+.ec-notes-close-btn:hover {
+  background: rgba(0, 0, 0, 0.08);
+  color: #475569;
+}
+
+/* Hide animated message envelopes/circles during user interaction (drag/pan/zoom).
+   SMIL animateMotion can't be paused via CSS, so we hide the elements entirely
+   to avoid expensive SVG repaints while ReactFlow transforms are updating. */
+.ec-interaction-active .ec-animated-msg {
+  visibility: hidden;
+}
+
+/* Minimap customizations */
+.react-flow__minimap {
+  background-color: rgb(var(--ec-card-bg));
+  border: 1px solid rgb(var(--ec-page-border));
+}
diff --git a/packages/visualiser/src/types/index.ts b/packages/visualiser/src/types/index.ts
new file mode 100644
index 000000000..a47b6cd84
--- /dev/null
+++ b/packages/visualiser/src/types/index.ts
@@ -0,0 +1,404 @@
+import type { Node, Connection, MarkerType } from "@xyflow/react";
+
+/**
+ * EventCatalog resource mode
+ */
+export type EventCatalogResource = {
+  mode: "simple" | "full";
+  style?: string;
+  collection?: string;
+  filePath?: string;
+  id?: string;
+};
+
+/**
+ * Message types (Events, Commands, Queries)
+ */
+export type Message = {
+  name: string;
+  version: string;
+  summary: string;
+  owners?: string[];
+  producers?: string[];
+  consumers?: string[];
+  deprecated?: boolean;
+  draft?: boolean;
+  schema?: string;
+  notes?: Note[];
+  /** HTTP method (e.g. GET, POST, PUT, DELETE) */
+  method?: string;
+  /** API path (e.g. /pets, /users/:id) */
+  path?: string;
+  /** HTTP status codes (e.g. [200, 401, 500]) */
+  statusCodes?: number[];
+  styles?: {
+    icon?: string;
+    node?: {
+      color?: string;
+      label?: string;
+    };
+  };
+};
+
+/**
+ * Note attached to a resource
+ */
+export type Note = {
+  content: string;
+  author?: string;
+  priority?: string;
+};
+
+/**
+ * Service type
+ */
+export type Service = {
+  name: string;
+  version: string;
+  summary: string;
+  owners?: string[];
+  sends?: string[];
+  receives?: string[];
+  deprecated?: boolean;
+  draft?: boolean;
+  notes?: Note[];
+  specifications?: unknown;
+  externalSystem?: boolean;
+  styles?: {
+    icon?: string;
+    node?: {
+      color?: string;
+      label?: string;
+    };
+  };
+};
+
+/**
+ * Agent type
+ */
+export type Agent = {
+  name: string;
+  version: string;
+  summary: string;
+  owners?: string[];
+  sends?: string[];
+  receives?: string[];
+  deprecated?: boolean;
+  draft?: boolean;
+  notes?: Note[];
+  model?: {
+    provider?: string;
+    name?: string;
+    version?: string;
+  };
+  tools?: Array<{
+    name: string;
+    type: string;
+    icon?: string;
+    url?: string;
+    description?: string;
+  }>;
+  styles?: {
+    icon?: string;
+    node?: {
+      color?: string;
+      label?: string;
+    };
+  };
+};
+
+/**
+ * Tool used by an agent
+ */
+export type AgentTool = {
+  id?: string;
+  name: string;
+  type: string;
+  icon?: string;
+  url?: string;
+  description?: string;
+};
+
+/**
+ * Channel type
+ */
+export type Channel = {
+  name: string;
+  version: string;
+  summary: string;
+  owners?: string[];
+  parameters?: Record<string, string>;
+  protocols?: string[];
+  address?: string;
+  deprecated?: boolean;
+  draft?: boolean;
+  notes?: Note[];
+  /** Delivery guarantee (e.g. at-most-once, at-least-once, exactly-once) */
+  deliveryGuarantee?: string;
+  styles?: {
+    icon?: string;
+    node?: {
+      color?: string;
+      label?: string;
+    };
+  };
+};
+
+/**
+ * External System type
+ */
+export type ExternalSystem = {
+  name: string;
+  version: string;
+  summary: string;
+  notes?: Note[];
+};
+
+/**
+ * Data type
+ */
+export type Data = {
+  name: string;
+  version: string;
+  summary: string;
+  owners?: string[];
+  type?: string;
+  container_type?: string;
+  schemas?: string[];
+  deprecated?: boolean;
+  draft?: boolean;
+  notes?: Note[];
+  styles?: {
+    icon?: string;
+    node?: {
+      color?: string;
+      label?: string;
+    };
+  };
+};
+
+/**
+ * View type
+ */
+export type View = {
+  name: string;
+  version: string;
+  summary: string;
+  owners?: string[];
+  screenshot?: string;
+  notes?: Note[];
+};
+
+/**
+ * Generic node data structure - framework agnostic
+ */
+export interface BaseNodeData {
+  id: string;
+  version?: string;
+  name?: string;
+  summary?: string;
+  markdown?: string;
+  badges?: Array<{
+    content: string;
+    textColor?: string;
+    backgroundColor?: string;
+  }>;
+  group?: {
+    id: string;
+    name: string;
+    type: string;
+  };
+  [key: string]: any;
+}
+
+/**
+ * Node types supported by the visualizer
+ */
+export type NodeType =
+  | "agent"
+  | "agents"
+  | "agentTool"
+  | "agent-tool"
+  | "service"
+  | "services"
+  | "event"
+  | "events"
+  | "command"
+  | "commands"
+  | "query"
+  | "queries"
+  | "domain"
+  | "domains"
+  | "flow"
+  | "flows"
+  | "channel"
+  | "channels"
+  | "entity"
+  | "entities"
+  | "step"
+  | "user"
+  | "custom"
+  | "externalSystem"
+  | "external-system"
+  | "data"
+  | "container"
+  | "view"
+  | "actor"
+  | "data-product"
+  | "data-products"
+  | "note";
+
+/**
+ * Edge types supported by the visualizer
+ */
+export type EdgeType = "default" | "animated" | "multiline" | "flow-edge";
+
+/**
+ * Callback types for framework integration
+ */
+export interface VisualizerCallbacks {
+  /** Called when a node is clicked */
+  onNodeClick?: (node: Node<BaseNodeData>) => void;
+  /** Called to build a URL for a node (for linking) */
+  onBuildNodeUrl?: (node: Node<BaseNodeData>) => string;
+  /** Called when navigation should occur */
+  onNavigate?: (url: string) => void;
+}
+
+/**
+ * Configuration for node registration
+ */
+export interface NodeConfiguration {
+  type: string;
+  icon: React.ComponentType;
+  color: string;
+  targetCanConnectTo?: string[];
+  sourceCanConnectTo?: string[];
+  validateConnection?: (connection: Connection) => boolean;
+  getEdgeOptions?: (connection: Connection) => {
+    label: string;
+    markerEnd: { type: MarkerType; color: string };
+  };
+  defaultData?: any;
+  editor?: {
+    title: string;
+    subtitle: string;
+    schema: any;
+  };
+}
+
+/**
+ * Registered node type
+ */
+export type RegisteredNode = {
+  type: string;
+  category: string;
+  component: React.ComponentType<any>;
+  configuration: NodeConfiguration;
+};
+
+/**
+ * Node category
+ */
+export type NodeCategory = {
+  type: string;
+  label: string;
+  icon: React.ComponentType;
+};
+
+/**
+ * Context menu item for node right-click menus
+ */
+export type ContextMenuItem = {
+  label: string;
+  href: string;
+  download?: string;
+  external?: boolean;
+  separator?: boolean;
+};
+
+/**
+ * Visualizer mode
+ */
+export type VisualizerMode = "full" | "simple";
+
+/**
+ * Link to other visualizer views
+ */
+export interface VisualizerLink {
+  label: string;
+  url: string;
+}
+
+/**
+ * DSL Graph types – used by the playground and any consumer that wants
+ * to hand a high-level graph to the visualiser for automatic layout.
+ */
+
+export interface GraphNode {
+  id: string;
+  type:
+    | "domain"
+    | "agent"
+    | "agent-tool"
+    | "agentTool"
+    | "service"
+    | "event"
+    | "command"
+    | "query"
+    | "channel"
+    | "entity"
+    | "container"
+    | "data"
+    | "data-product"
+    | "flow"
+    | "actor"
+    | "external-system"
+    | "step"
+    | "user"
+    | "team"
+    | "diagram";
+  label: string;
+  parentId?: string;
+  metadata: Record<string, unknown>;
+}
+
+export type GraphEdgeType =
+  | "sends"
+  | "receives"
+  | "publishes"
+  | "subscribes"
+  | "writes-to"
+  | "reads-from"
+  | "reads-writes"
+  | "contains"
+  | "owns"
+  | "member-of"
+  | "routes-to"
+  | "calls"
+  | "flow-step";
+
+export interface GraphEdge {
+  id: string;
+  source: string;
+  target: string;
+  type: GraphEdgeType;
+  label?: string;
+}
+
+export interface DslGraph {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  visualizers?: string[];
+  activeVisualizer?: string;
+  title?: string;
+  empty?: boolean;
+  options?: {
+    legend?: boolean;
+    search?: boolean;
+    toolbar?: boolean;
+    focusMode?: boolean;
+    animated?: boolean;
+    style?: string;
+  };
+}
diff --git a/packages/visualiser/src/utils/badges.tsx b/packages/visualiser/src/utils/badges.tsx
new file mode 100644
index 000000000..3c35398c4
--- /dev/null
+++ b/packages/visualiser/src/utils/badges.tsx
@@ -0,0 +1,12 @@
+import * as HeroIcons from "@heroicons/react/24/outline";
+import { getIconForProtocol } from "./protocols";
+
+export function getIcon(iconName: string): React.ComponentType<any> | null {
+  // Try protocol icons first
+  const entry = getIconForProtocol(iconName);
+  if (entry) return entry.component;
+
+  // Fall back to HeroIcons
+  const heroIcon = HeroIcons[iconName as keyof typeof HeroIcons];
+  return heroIcon || null;
+}
diff --git a/packages/visualiser/src/utils/clipboard.ts b/packages/visualiser/src/utils/clipboard.ts
new file mode 100644
index 000000000..7108c540e
--- /dev/null
+++ b/packages/visualiser/src/utils/clipboard.ts
@@ -0,0 +1,24 @@
+/**
+ * Utility to copy text to clipboard
+ */
+export async function copyToClipboard(text: string): Promise<boolean> {
+  try {
+    if (navigator?.clipboard?.writeText) {
+      await navigator.clipboard.writeText(text);
+      return true;
+    }
+    // Fallback for older browsers
+    const textArea = document.createElement("textarea");
+    textArea.value = text;
+    textArea.style.position = "fixed";
+    textArea.style.left = "-999999px";
+    document.body.appendChild(textArea);
+    textArea.select();
+    const success = document.execCommand("copy");
+    document.body.removeChild(textArea);
+    return success;
+  } catch (error) {
+    console.error("Failed to copy to clipboard:", error);
+    return false;
+  }
+}
diff --git a/packages/visualiser/src/utils/custom-icon.tsx b/packages/visualiser/src/utils/custom-icon.tsx
new file mode 100644
index 000000000..656620c4e
--- /dev/null
+++ b/packages/visualiser/src/utils/custom-icon.tsx
@@ -0,0 +1,36 @@
+import { memo } from "react";
+import { buildUrl } from "./url-builder";
+
+export function isIconPath(value: string | undefined): value is string {
+  if (!value) return false;
+  return (
+    value.startsWith("/") ||
+    value.startsWith("http://") ||
+    value.startsWith("https://")
+  );
+}
+
+export function resolveIconUrl(value: string): string {
+  if (value.startsWith("http://") || value.startsWith("https://")) return value;
+  return buildUrl(value).replace(/\/$/, "");
+}
+
+export const CustomIcon = memo(function CustomIcon({
+  src,
+  alt,
+  className,
+}: {
+  src: string;
+  alt: string;
+  className?: string;
+}) {
+  return (
+    <img
+      src={resolveIconUrl(src)}
+      alt={alt}
+      loading="lazy"
+      className={className}
+      style={{ objectFit: "contain", borderRadius: 4 }}
+    />
+  );
+});
diff --git a/packages/visualiser/src/utils/export-image.test.ts b/packages/visualiser/src/utils/export-image.test.ts
new file mode 100644
index 000000000..3a995eb59
--- /dev/null
+++ b/packages/visualiser/src/utils/export-image.test.ts
@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest";
+import {
+  getExportImageDimensions,
+  EXPORT_PADDING,
+  extractEcVarNames,
+  buildExportCss,
+} from "./export-image";
+
+describe("getExportImageDimensions", () => {
+  it("adds padding around large graphs so edge nodes are not flush against the image border", () => {
+    // Graph larger than the minimum image size
+    const nodesBounds = { x: 100, y: 200, width: 3000, height: 2000 };
+    const { width, height, viewport } = getExportImageDimensions(nodesBounds);
+
+    expect(width).toBe(3000 + EXPORT_PADDING * 2);
+    expect(height).toBe(2000 + EXPORT_PADDING * 2);
+    expect(viewport.zoom).toBe(1);
+
+    // The leftmost/topmost node should be rendered EXPORT_PADDING px inside
+    // the image, not at 0,0 (which clips badges/icons rendered above and
+    // shadows rendered around the measured node rects)
+    expect(viewport.x + nodesBounds.x * viewport.zoom).toBe(EXPORT_PADDING);
+    expect(viewport.y + nodesBounds.y * viewport.zoom).toBe(EXPORT_PADDING);
+  });
+
+  it("keeps the whole graph inside the image (no clipping at the far edges)", () => {
+    const nodesBounds = { x: -500, y: -250, width: 4200, height: 1500 };
+    const { width, height, viewport } = getExportImageDimensions(nodesBounds);
+
+    const rightEdge =
+      viewport.x + (nodesBounds.x + nodesBounds.width) * viewport.zoom;
+    const bottomEdge =
+      viewport.y + (nodesBounds.y + nodesBounds.height) * viewport.zoom;
+
+    expect(rightEdge).toBeLessThanOrEqual(width - EXPORT_PADDING);
+    expect(bottomEdge).toBeLessThanOrEqual(height - EXPORT_PADDING);
+  });
+
+  it("uses the minimum image size for small graphs and centers the content", () => {
+    const nodesBounds = { x: 0, y: 0, width: 200, height: 100 };
+    const { width, height, viewport } = getExportImageDimensions(nodesBounds);
+
+    expect(width).toBe(1024);
+    expect(height).toBe(768);
+    // Zoom is clamped to 2 for small graphs (existing behaviour)
+    expect(viewport.zoom).toBe(2);
+
+    // Content is centered horizontally: distance from left edge equals
+    // distance from right edge
+    const left = viewport.x + nodesBounds.x * viewport.zoom;
+    const right =
+      width -
+      (viewport.x + (nodesBounds.x + nodesBounds.width) * viewport.zoom);
+    expect(left).toBeCloseTo(right, 5);
+  });
+
+  it("extracts --ec-* variable names from stylesheet text", () => {
+    const css = `
+      :root { --ec-card-bg: 255 255 255; --ec-page-text: 23 23 23; }
+      .react-flow__edge-path { stroke: var(--ec-edge-stroke, #6b7280); }
+      .other { color: red; --not-ec: 1; }
+    `;
+    expect(extractEcVarNames(css).sort()).toEqual([
+      "--ec-card-bg",
+      "--ec-edge-stroke",
+      "--ec-page-text",
+    ]);
+  });
+
+  it("builds export CSS that pins theme variables and edge styles", () => {
+    const css = buildExportCss({
+      "--ec-card-bg": "255 255 255",
+      "--ec-page-text": "23 23 23",
+    });
+
+    // Variables must apply to every element so they reach the deep-cloned
+    // SVG subtree (html-to-image copies SVG without inlining styles)
+    expect(css).toContain("--ec-card-bg: 255 255 255;");
+    expect(css).toContain("--ec-page-text: 23 23 23;");
+    expect(css).toMatch(/\*\s*\{/);
+
+    // Edge paths lose their stylesheet rule in the clone — it must be inlined
+    expect(css).toContain(".react-flow__edge-path");
+    expect(css).toContain("stroke:");
+  });
+
+  it("rounds image dimensions up to whole pixels", () => {
+    const nodesBounds = { x: 0, y: 0, width: 3000.4, height: 2000.6 };
+    const { width, height } = getExportImageDimensions(nodesBounds);
+
+    expect(Number.isInteger(width)).toBe(true);
+    expect(Number.isInteger(height)).toBe(true);
+    expect(width).toBeGreaterThanOrEqual(3000.4 + EXPORT_PADDING * 2);
+    expect(height).toBeGreaterThanOrEqual(2000.6 + EXPORT_PADDING * 2);
+  });
+});
diff --git a/packages/visualiser/src/utils/export-image.ts b/packages/visualiser/src/utils/export-image.ts
new file mode 100644
index 000000000..16992e279
--- /dev/null
+++ b/packages/visualiser/src/utils/export-image.ts
@@ -0,0 +1,134 @@
+import { getViewportForBounds, type Rect, type Viewport } from "@xyflow/react";
+
+const MIN_IMAGE_WIDTH = 1024;
+const MIN_IMAGE_HEIGHT = 768;
+
+// Nodes render decorations outside their measured rects (type badges at
+// -top-2.5, actor icons at -top-4, box shadows), so the exported image needs
+// breathing room around getNodesBounds() or edge nodes get clipped.
+export const EXPORT_PADDING = 40;
+
+export function getExportImageDimensions(nodesBounds: Rect): {
+  width: number;
+  height: number;
+  viewport: Viewport;
+} {
+  const paddedBounds = {
+    x: nodesBounds.x - EXPORT_PADDING,
+    y: nodesBounds.y - EXPORT_PADDING,
+    width: nodesBounds.width + EXPORT_PADDING * 2,
+    height: nodesBounds.height + EXPORT_PADDING * 2,
+  };
+
+  const width = Math.max(MIN_IMAGE_WIDTH, Math.ceil(paddedBounds.width));
+  const height = Math.max(MIN_IMAGE_HEIGHT, Math.ceil(paddedBounds.height));
+
+  const viewport = getViewportForBounds(paddedBounds, width, height, 0.5, 2, 0);
+
+  return { width, height, viewport };
+}
+
+// html-to-image deep-clones <svg> subtrees without inlining computed styles,
+// so var()-based fills (edge label pills, label text) and stylesheet rules
+// (.react-flow__edge-path) resolve to nothing in the capture — labels render
+// black and edges lose their color. Injecting a <style> that pins the resolved
+// theme variables and mirrors the edge rules fixes the capture in both themes.
+
+export function extractEcVarNames(cssText: string): string[] {
+  return Array.from(new Set(cssText.match(/--ec-[a-z0-9-]+/g) ?? []));
+}
+
+export function buildExportCss(themeVars: Record<string, string>): string {
+  const varDeclarations = Object.entries(themeVars)
+    .map(([name, value]) => `${name}: ${value};`)
+    .join(" ");
+
+  return [
+    // Applied to every element so the variables reach the cloned SVG subtree
+    `* { ${varDeclarations} }`,
+    // Mirrors .react-flow__edge-path in styles.css, which is lost in the clone
+    `.react-flow__edge-path { stroke: var(--ec-edge-stroke, #6b7280); stroke-width: 1.5; fill: none; }`,
+  ].join("\n");
+}
+
+function collectThemeCssVars(scope: Element): Record<string, string> {
+  const names = new Set<string>();
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRuleList;
+    try {
+      rules = sheet.cssRules;
+    } catch {
+      continue; // cross-origin stylesheet
+    }
+    for (const rule of Array.from(rules)) {
+      for (const name of extractEcVarNames(rule.cssText)) {
+        names.add(name);
+      }
+    }
+  }
+
+  const computed = window.getComputedStyle(scope);
+  const vars: Record<string, string> = {};
+  for (const name of names) {
+    const value = computed.getPropertyValue(name).trim();
+    if (value) vars[name] = value;
+  }
+  return vars;
+}
+
+// html-to-image deep-clones <svg> elements via cloneNode(true) and skips
+// computed-style inlining for everything inside them (cloneChildren returns
+// early for SVG). Styles that SVG content gets from stylesheets or var()-based
+// presentation attributes are therefore lost in the capture. Inlining the
+// resolved values directly onto each SVG element before capture is the only
+// approach that survives the clone in every browser.
+const SVG_EXPORT_STYLE_PROPERTIES = [
+  "fill",
+  "fill-opacity",
+  "stroke",
+  "stroke-width",
+  "stroke-dasharray",
+  "stroke-linecap",
+  "stroke-linejoin",
+  "opacity",
+  "font-family",
+  "font-size",
+  "font-weight",
+  "letter-spacing",
+  "text-anchor",
+  "dominant-baseline",
+];
+
+function inlineSvgComputedStyles(viewport: HTMLElement): () => void {
+  const restores: Array<() => void> = [];
+  const svgElements = viewport.querySelectorAll("svg, svg *");
+  svgElements.forEach((element) => {
+    if (!(element instanceof SVGElement)) return;
+    const computed = window.getComputedStyle(element);
+    const originalStyle = element.getAttribute("style");
+    for (const property of SVG_EXPORT_STYLE_PROPERTIES) {
+      const value = computed.getPropertyValue(property);
+      if (value) element.style.setProperty(property, value);
+    }
+    restores.push(() => {
+      if (originalStyle === null) {
+        element.removeAttribute("style");
+      } else {
+        element.setAttribute("style", originalStyle);
+      }
+    });
+  });
+  return () => restores.forEach((restore) => restore());
+}
+
+// Returns a cleanup function that removes the injected styles.
+export function injectExportStyles(viewport: HTMLElement): () => void {
+  const styleElement = document.createElement("style");
+  styleElement.textContent = buildExportCss(collectThemeCssVars(viewport));
+  viewport.appendChild(styleElement);
+  const restoreSvgStyles = inlineSvgComputedStyles(viewport);
+  return () => {
+    restoreSvgStyles();
+    styleElement.remove();
+  };
+}
diff --git a/packages/visualiser/src/utils/export-mermaid.ts b/packages/visualiser/src/utils/export-mermaid.ts
new file mode 100644
index 000000000..71457635c
--- /dev/null
+++ b/packages/visualiser/src/utils/export-mermaid.ts
@@ -0,0 +1,357 @@
+import type { Node, Edge } from "@xyflow/react";
+
+/**
+ * Mermaid Export Utility
+ * Converts React Flow nodes and edges to Mermaid flowchart syntax
+ */
+
+export interface MermaidExportOptions {
+  /** Include class definitions for styling */
+  includeStyles?: boolean;
+  /** Direction of the flowchart: LR (left-right), TB (top-bottom), etc. */
+  direction?: "LR" | "TB" | "RL" | "BT";
+}
+
+/**
+ * Mapping of node types to their Mermaid shape syntax
+ * Format: [prefix, suffix]
+ */
+const NODE_SHAPE_MAP: Record<string, [string, string]> = {
+  agents: ["[[", "]]"],
+  agent: ["[[", "]]"],
+  agentTool: ["[", "]"],
+  "agent-tool": ["[", "]"],
+  services: ["[[", "]]"], // stadium shape
+  service: ["[[", "]]"],
+  events: [">", "]"], // flag/asymmetric shape (message-like)
+  event: [">", "]"],
+  commands: [">", "]"], // flag/asymmetric shape (message-like)
+  command: [">", "]"],
+  queries: ["{{", "}}"], // hexagon
+  query: ["{{", "}}"],
+  channels: ["[(", ")]"], // cylinder
+  channel: ["[(", ")]"],
+  domains: ["[", "]"], // rectangle
+  domain: ["[", "]"],
+  flows: ["([", "])"], // stadium (rounded)
+  flow: ["([", "])"],
+  step: ["[", "]"], // rectangle
+  user: ["((", "))"], // circle
+  actor: ["((", "))"], // circle
+  externalSystem: ["[[", "]]"], // stadium
+  "external-system": ["[[", "]]"],
+  data: ["[(", ")]"], // cylinder (database)
+  "data-product": ["[[", "]]"], // stadium
+  "data-products": ["[[", "]]"],
+  entities: ["[", "]"], // rectangle
+  entity: ["[", "]"],
+  custom: ["[", "]"], // rectangle
+  view: ["[", "]"], // rectangle
+  note: ["[", "]"], // rectangle
+  field: ["[(", ")]"], // cylinder
+  fields: ["[(", ")]"], // cylinder
+  messageGroup: ["[[", "]]"],
+  messageGroupExpanded: ["[[", "]]"],
+};
+
+/**
+ * Mermaid class definitions for styling different node types
+ */
+const NODE_STYLE_CLASSES: Record<string, string> = {
+  agents: "fill:#0ea5e9,stroke:#0369a1,color:#fff",
+  agent: "fill:#0ea5e9,stroke:#0369a1,color:#fff",
+  agentTool: "fill:#8b5cf6,stroke:#6d28d9,color:#fff",
+  "agent-tool": "fill:#8b5cf6,stroke:#6d28d9,color:#fff",
+  services: "fill:#ec4899,stroke:#be185d,color:#fff",
+  service: "fill:#ec4899,stroke:#be185d,color:#fff",
+  events: "fill:#f97316,stroke:#c2410c,color:#fff",
+  event: "fill:#f97316,stroke:#c2410c,color:#fff",
+  commands: "fill:#3b82f6,stroke:#1d4ed8,color:#fff",
+  command: "fill:#3b82f6,stroke:#1d4ed8,color:#fff",
+  queries: "fill:#22c55e,stroke:#15803d,color:#fff",
+  query: "fill:#22c55e,stroke:#15803d,color:#fff",
+  channels: "fill:#6b7280,stroke:#374151,color:#fff",
+  channel: "fill:#6b7280,stroke:#374151,color:#fff",
+  domains: "fill:#eab308,stroke:#a16207,color:#000",
+  domain: "fill:#eab308,stroke:#a16207,color:#000",
+  flows: "fill:#14b8a6,stroke:#0f766e,color:#fff",
+  flow: "fill:#14b8a6,stroke:#0f766e,color:#fff",
+  step: "fill:#374151,stroke:#1f2937,color:#fff",
+  user: "fill:#8b5cf6,stroke:#6d28d9,color:#fff",
+  actor: "fill:#eab308,stroke:#a16207,color:#000",
+  externalSystem: "fill:#ec4899,stroke:#be185d,color:#fff",
+  "external-system": "fill:#ec4899,stroke:#be185d,color:#fff",
+  data: "fill:#3b82f6,stroke:#1d4ed8,color:#fff",
+  "data-product": "fill:#6366f1,stroke:#4338ca,color:#fff",
+  "data-products": "fill:#6366f1,stroke:#4338ca,color:#fff",
+  entities: "fill:#6b7280,stroke:#374151,color:#fff",
+  entity: "fill:#6b7280,stroke:#374151,color:#fff",
+  custom: "fill:#9ca3af,stroke:#6b7280,color:#000",
+  view: "fill:#9ca3af,stroke:#6b7280,color:#000",
+  note: "fill:#fef3c7,stroke:#d97706,color:#000",
+  field: "fill:#06b6d4,stroke:#0891b2,color:#fff",
+  fields: "fill:#06b6d4,stroke:#0891b2,color:#fff",
+  messageGroup: "fill:#7c3aed,stroke:#5b21b6,color:#fff",
+  messageGroupExpanded: "fill:#7c3aed,stroke:#5b21b6,color:#fff",
+};
+
+/**
+ * Sanitize a string to be a valid Mermaid node ID
+ * Mermaid IDs should be alphanumeric with underscores
+ */
+export function sanitizeMermaidId(id: string): string {
+  // Replace any non-alphanumeric characters (except underscores) with underscores
+  // Also handle dots and hyphens which are common in version strings
+  return id.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
+/**
+ * Escape special characters in Mermaid labels
+ */
+function escapeMermaidLabel(label: string): string {
+  // Escape quotes and other special characters
+  return label.replace(/"/g, "#quot;").replace(/\n/g, "<br/>");
+}
+
+/**
+ * Get the Mermaid shape syntax for a node type
+ */
+export function getMermaidNodeShape(type: string): [string, string] {
+  return NODE_SHAPE_MAP[type] || ["[", "]"];
+}
+
+/**
+ * Helper to format label with version
+ */
+function formatLabelWithVersion(name: string, version?: string): string {
+  if (version) {
+    return `${name} (${version})`;
+  }
+  return name;
+}
+
+/**
+ * Extract the display label from a node based on its type and data
+ * Includes version information when available
+ */
+export function getNodeLabel(node: Node): string {
+  const { type, data } = node;
+
+  if (!data) return node.id;
+
+  // Handle different node types and their data structures
+  if (type === "agents" || type === "agent") {
+    const agent = (data as any).agent;
+    const name = agent?.name || agent?.id || node.id;
+    const version = agent?.data?.version || agent?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (type === "agentTool" || type === "agent-tool") {
+    const agentTool = (data as any).agentTool;
+    return agentTool?.name || agentTool?.id || node.id;
+  }
+
+  if (type === "services" || type === "service") {
+    const service = (data as any).service;
+    const name = service?.name || service?.id || node.id;
+    const version = service?.data?.version || service?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (
+    type === "events" ||
+    type === "event" ||
+    type === "commands" ||
+    type === "command" ||
+    type === "queries" ||
+    type === "query"
+  ) {
+    const message = (data as any).message;
+    const name = message?.name || message?.id || node.id;
+    const version = message?.data?.version || message?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (type === "channels" || type === "channel") {
+    const channel = (data as any).channel;
+    const name = channel?.name || channel?.id || node.id;
+    const version = channel?.data?.version || channel?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (type === "domains" || type === "domain") {
+    const domain = (data as any).domain;
+    // Domain data can be nested in .data
+    const domainData = domain?.data || domain;
+    const name = domainData?.name || domainData?.id || node.id;
+    const version = domainData?.version || domain?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (type === "flows" || type === "flow") {
+    const flow = (data as any).flow;
+    const name = flow?.name || flow?.id || node.id;
+    const version = flow?.data?.version || flow?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (type === "step") {
+    const step = (data as any).step;
+    return step?.title || step?.name || step?.id || node.id;
+  }
+
+  if (type === "user" || type === "actor") {
+    return (
+      (data as any).name || (data as any).label || (data as any).id || node.id
+    );
+  }
+
+  if (type === "externalSystem" || type === "external-system") {
+    const system = (data as any).externalSystem || data;
+    return system?.name || system?.id || node.id;
+  }
+
+  if (type === "data") {
+    const dataNode = (data as any).data;
+    return dataNode?.name || dataNode?.id || node.id;
+  }
+
+  if (type === "data-product" || type === "data-products") {
+    const dataProduct = (data as any).dataProduct;
+    const name = dataProduct?.name || dataProduct?.id || node.id;
+    const version = dataProduct?.data?.version || dataProduct?.version;
+    return formatLabelWithVersion(name, version);
+  }
+
+  if (type === "entities" || type === "entity") {
+    const entity = (data as any).entity;
+    return entity?.name || entity?.id || node.id;
+  }
+
+  if (type === "note") {
+    return (data as any).text || (data as any).label || "Note";
+  }
+
+  if (type === "field" || type === "fields") {
+    const name = (data as any).name || node.id;
+    const fieldType = (data as any).type;
+    return fieldType ? `${name} (${fieldType})` : name;
+  }
+
+  if (type === "messageGroup") {
+    const groupName = (data as any).groupName || node.id;
+    const count = (data as any).messageCount || 0;
+    return `${groupName} (${count} messages)`;
+  }
+
+  if (type === "messageGroupExpanded") {
+    const groupName = (data as any).groupName || node.id;
+    const count = (data as any).messageCount || 0;
+    return `${groupName} (${count} messages)`;
+  }
+
+  // Fallback: try common data patterns
+  return (
+    (data as any).name ||
+    (data as any).label ||
+    (data as any).title ||
+    (data as any).id ||
+    node.id
+  );
+}
+
+/**
+ * Extract label from an edge
+ */
+function getEdgeLabel(edge: Edge): string | undefined {
+  if (edge.label && typeof edge.label === "string") {
+    return edge.label;
+  }
+  if (edge.data?.label && typeof edge.data.label === "string") {
+    return edge.data.label;
+  }
+  return undefined;
+}
+
+/**
+ * Convert React Flow nodes and edges to Mermaid flowchart syntax
+ */
+export function convertToMermaid(
+  nodes: Node[],
+  edges: Edge[],
+  options: MermaidExportOptions = {},
+): string {
+  const { includeStyles = true, direction = "LR" } = options;
+
+  const lines: string[] = [];
+
+  // Add flowchart header
+  lines.push(`flowchart ${direction}`);
+
+  // Collect used node types for class definitions
+  const usedTypes = new Set<string>();
+
+  // Add class definitions if styles are enabled
+  if (includeStyles) {
+    lines.push("");
+    lines.push("    %% Style definitions");
+
+    // First pass: collect all used node types
+    nodes.forEach((node) => {
+      if (node.type && NODE_STYLE_CLASSES[node.type]) {
+        usedTypes.add(node.type);
+      }
+    });
+
+    // Add class definitions for used types
+    usedTypes.forEach((type) => {
+      const style = NODE_STYLE_CLASSES[type];
+      if (style) {
+        lines.push(`    classDef ${sanitizeMermaidId(type)} ${style}`);
+      }
+    });
+  }
+
+  // Add node definitions
+  lines.push("");
+  lines.push("    %% Nodes");
+
+  nodes.forEach((node) => {
+    const sanitizedId = sanitizeMermaidId(node.id);
+    const label = escapeMermaidLabel(getNodeLabel(node));
+    const [prefix, suffix] = getMermaidNodeShape(node.type || "custom");
+
+    let nodeLine = `    ${sanitizedId}${prefix}"${label}"${suffix}`;
+
+    // Add class reference if styles are enabled
+    if (includeStyles && node.type && usedTypes.has(node.type)) {
+      nodeLine += `:::${sanitizeMermaidId(node.type)}`;
+    }
+
+    lines.push(nodeLine);
+  });
+
+  // Add edge definitions
+  lines.push("");
+  lines.push("    %% Edges");
+
+  edges.forEach((edge) => {
+    const sourceId = sanitizeMermaidId(edge.source);
+    const targetId = sanitizeMermaidId(edge.target);
+    const label = getEdgeLabel(edge);
+
+    let edgeLine: string;
+    if (label) {
+      // Clean up multi-line labels
+      const cleanLabel = label.replace(/\n/g, " ").trim();
+      edgeLine = `    ${sourceId} -->|"${escapeMermaidLabel(cleanLabel)}"| ${targetId}`;
+    } else {
+      edgeLine = `    ${sourceId} --> ${targetId}`;
+    }
+
+    lines.push(edgeLine);
+  });
+
+  return lines.join("\n");
+}
diff --git a/packages/visualiser/src/utils/export-node-graph.ts b/packages/visualiser/src/utils/export-node-graph.ts
new file mode 100644
index 000000000..ca9c36498
--- /dev/null
+++ b/packages/visualiser/src/utils/export-node-graph.ts
@@ -0,0 +1,97 @@
+import type { Node, ReactFlowJsonObject, Edge } from "@xyflow/react";
+
+// Define the structure of resource data that can be found in nodes
+interface ResourceData {
+  id?: string;
+  name?: string;
+  summary?: string;
+  version?: string;
+}
+
+// Define the possible node data structure
+interface NodeDataWithResources {
+  [key: string]: any;
+  channel?: ResourceData;
+  custom?: ResourceData;
+  data?: ResourceData;
+  domain?: ResourceData;
+  entity?: ResourceData;
+  message?: ResourceData;
+  flow?: ResourceData;
+  agent?: ResourceData;
+  agentTool?: ResourceData;
+  service?: ResourceData;
+  step?: ResourceData;
+  user?: ResourceData;
+}
+
+export const exportNodeGraphForStudio = (
+  data: ReactFlowJsonObject,
+): ReactFlowJsonObject => {
+  const dataTypes: (keyof NodeDataWithResources)[] = [
+    "channel",
+    "custom",
+    "data",
+    "domain",
+    "entity",
+    "message",
+    "flow",
+    "agent",
+    "agentTool",
+    "service",
+    "step",
+    "user",
+  ];
+
+  // try and remove unwanted data for studio
+  const nodes = data.nodes.map((node: Node) => {
+    let nodeData = node.data as NodeDataWithResources;
+    const dataProperties = Object.keys(
+      nodeData,
+    ) as (keyof NodeDataWithResources)[];
+
+    // If we find a match.....
+    const hasCustomDataType = dataProperties.find((property) =>
+      dataTypes.includes(property),
+    );
+
+    if (hasCustomDataType && nodeData[hasCustomDataType]) {
+      const resourceData = nodeData[hasCustomDataType] as ResourceData;
+      nodeData = {
+        ...nodeData,
+        [hasCustomDataType]: {
+          id: resourceData?.id,
+          name: resourceData?.name,
+          summary: resourceData?.summary,
+          version: resourceData?.version,
+        },
+      };
+    }
+
+    return {
+      ...node,
+      data: {
+        ...nodeData,
+        // We dont need these for studio
+        source: undefined,
+        target: undefined,
+        // Studio wants all nodes in full mode
+        mode: "full",
+      },
+    };
+  });
+
+  const edges = data.edges.map((edge: Edge) => {
+    return {
+      ...edge,
+      data: undefined,
+      type: "animatedMessage",
+    };
+  });
+
+  return {
+    ...data,
+    nodes,
+    edges,
+  };
+};
diff --git a/packages/visualiser/src/utils/index.ts b/packages/visualiser/src/utils/index.ts
new file mode 100644
index 000000000..4592dbbb6
--- /dev/null
+++ b/packages/visualiser/src/utils/index.ts
@@ -0,0 +1,16 @@
+/**
+ * Utility functions for EventCatalog Visualizer
+ * These are framework-agnostic utilities for working with node graphs
+ */
+
+// Mermaid export
+export { convertToMermaid, type MermaidExportOptions } from "./export-mermaid";
+
+// Node graph export
+export { exportNodeGraphForStudio } from "./export-node-graph";
+
+// Dagre and node generation utilities
+export * from "./utils/utils";
+
+// Layout utilities (DSL graph → ReactFlow nodes/edges)
+export { layoutGraph, buildNodeData } from "./layout";
diff --git a/packages/visualiser/src/utils/layout.ts b/packages/visualiser/src/utils/layout.ts
new file mode 100644
index 000000000..a95aca070
--- /dev/null
+++ b/packages/visualiser/src/utils/layout.ts
@@ -0,0 +1,675 @@
+import dagre from "dagre";
+import { MarkerType, type Node, type Edge } from "@xyflow/react";
+import type { GraphNode, GraphEdge } from "../types";
+
+const GROUP_HEADER_HEIGHT = 44;
+const GROUP_CONTENT_PADDING_TOP = 50;
+const GROUP_CONTENT_PADDING_BOTTOM = 30;
+const GROUP_PADDING_X = 60;
+
+const EMPTY_GROUP_WIDTH = 200;
+const EMPTY_GROUP_HEIGHT = 80;
+
+const defaultSizes: Record<string, { w: number; h: number }> = {
+  service: { w: 300, h: 140 },
+  agent: { w: 300, h: 140 },
+  "agent-tool": { w: 260, h: 120 },
+  agentTool: { w: 260, h: 120 },
+  event: { w: 240, h: 140 },
+  command: { w: 300, h: 120 },
+  query: { w: 300, h: 120 },
+  channel: { w: 300, h: 140 },
+  container: { w: 300, h: 140 },
+  "data-product": { w: 300, h: 140 },
+  data: { w: 320, h: 120 },
+  domain: { w: 300, h: 120 },
+  flow: { w: 300, h: 140 },
+  actor: { w: 240, h: 100 },
+  "external-system": { w: 300, h: 100 },
+  step: { w: 280, h: 100 },
+  "message-group": { w: 350, h: 200 },
+};
+const fallbackSize = { w: 280, h: 100 };
+
+export function getNodeSize(
+  type: string,
+  nodeWidth?: number,
+  nodeHeight?: number,
+) {
+  const size = defaultSizes[type] || fallbackSize;
+  return { w: nodeWidth ?? size.w, h: nodeHeight ?? size.h };
+}
+
+export function buildNodeData(
+  node: GraphNode,
+  style?: string,
+): Record<string, unknown> {
+  const notes =
+    (node.metadata.notes as Array<{
+      content: string;
+      author?: string;
+      priority?: string;
+    }>) || [];
+  const owners = (node.metadata.owners as string[]) || [];
+  const base = {
+    name: node.label,
+    version: (node.metadata.version as string) || "",
+    summary: (node.metadata.summary as string) || "",
+    deprecated: node.metadata.deprecated === true,
+    draft: node.metadata.draft === true,
+    ...(notes.length > 0 ? { notes } : {}),
+    ...(owners.length > 0 ? { owners } : {}),
+  };
+
+  switch (node.type) {
+    case "service":
+      return { mode: "full", style, service: base };
+    case "agent":
+      return {
+        mode: "full",
+        style,
+        agent: {
+          ...base,
+          ...(node.metadata.model ? { model: node.metadata.model } : {}),
+          ...(Array.isArray(node.metadata.tools)
+            ? { tools: node.metadata.tools }
+            : {}),
+        },
+      };
+    case "agent-tool":
+    case "agentTool":
+      return {
+        mode: "full",
+        style,
+        agentTool: {
+          id: node.id,
+          name: node.label,
+          type: (node.metadata.type as string) || "",
+          icon: (node.metadata.icon as string) || "",
+          url: (node.metadata.url as string) || "",
+          description: (node.metadata.description as string) || "",
+        },
+      };
+    case "event":
+    case "command":
+    case "query":
+      return {
+        mode: "full",
+        style,
+        message: {
+          ...base,
+          schema: (node.metadata.schema as string) || "",
+          ...(node.metadata.method
+            ? { method: node.metadata.method as string }
+            : {}),
+          ...(node.metadata.path ? { path: node.metadata.path as string } : {}),
+          ...(Array.isArray(node.metadata.statusCodes) &&
+          node.metadata.statusCodes.length > 0
+            ? { statusCodes: node.metadata.statusCodes as number[] }
+            : {}),
+        },
+      };
+    case "channel":
+      return {
+        mode: "full",
+        style,
+        channel: {
+          ...base,
+          protocols: (node.metadata.protocols as string[]) || [],
+          address: (node.metadata.address as string) || "",
+          ...(node.metadata.deliveryGuarantee
+            ? { deliveryGuarantee: node.metadata.deliveryGuarantee as string }
+            : {}),
+        },
+      };
+    case "container":
+      return {
+        mode: "full",
+        style,
+        data: {
+          ...base,
+          type: (node.metadata.containerType as string) || "Database",
+        },
+      };
+    case "data-product":
+      return { mode: "full", style, dataProduct: base };
+    case "data":
+      return {
+        mode: "full",
+        style,
+        data: {
+          ...base,
+          type: (node.metadata.containerType as string) || "Database",
+        },
+      };
+    case "domain":
+      return {
+        mode: "full",
+        style,
+        domain: { data: { ...base, id: node.id } },
+      };
+    case "flow":
+      return {
+        mode: "full",
+        style,
+        flow: { data: { ...base, id: node.id } },
+      };
+    case "actor":
+      return { ...base, label: node.label, mode: "full", style, id: node.id };
+    case "external-system":
+      return {
+        mode: "full",
+        style,
+        externalSystem: { label: node.label, ...base, id: node.id },
+      };
+    case "step":
+      return {
+        mode: "full",
+        style,
+        step: { ...base, title: node.label, id: node.id },
+      };
+    default:
+      return { ...base, style, resourceType: node.type };
+  }
+}
+
+export function layoutGraph(
+  nodes: GraphNode[],
+  edges: GraphEdge[],
+  options: {
+    rankdir?: string;
+    nodesep?: number;
+    ranksep?: number;
+    edgesep?: number;
+  } = {},
+  style?: string,
+): { nodes: Node[]; edges: Edge[] } {
+  if (nodes.length === 0) {
+    return { nodes: [], edges: [] };
+  }
+
+  const { rankdir = "LR", nodesep = 80, ranksep = 140, edgesep = 40 } = options;
+
+  function nodeSize(type: string) {
+    return getNodeSize(type);
+  }
+
+  // All domain nodes become groups
+  const domainNodeIds = new Set(
+    nodes.filter((n) => n.type === "domain").map((n) => n.id),
+  );
+
+  const parentNodeIds = new Set(
+    nodes.filter((n) => n.parentId).map((n) => n.parentId!),
+  );
+
+  const allGroupIds = new Set([...domainNodeIds, ...parentNodeIds]);
+
+  const childNodeIds = new Set<string>();
+  for (const node of nodes) {
+    if (node.parentId && allGroupIds.has(node.parentId)) {
+      childNodeIds.add(node.id);
+    }
+  }
+
+  // If no groups, use flat layout
+  if (allGroupIds.size === 0) {
+    return flatLayout(
+      nodes,
+      edges,
+      { rankdir, nodesep, ranksep, edgesep },
+      nodeSize,
+      style,
+    );
+  }
+
+  // Grouped layout
+  const groupChildren = new Map<string, GraphNode[]>();
+  for (const id of allGroupIds) {
+    groupChildren.set(id, []);
+  }
+  for (const node of nodes) {
+    if (
+      node.parentId &&
+      node.parentId !== node.id &&
+      allGroupIds.has(node.parentId)
+    ) {
+      groupChildren.get(node.parentId)!.push(node);
+    }
+  }
+
+  const nodeById = new Map(nodes.map((n) => [n.id, n]));
+  const groupSizes = new Map<string, { width: number; height: number }>();
+  const groupInternalLayouts = new Map<
+    string,
+    {
+      childPositions: Map<
+        string,
+        { x: number; y: number; w: number; h: number }
+      >;
+      width: number;
+      height: number;
+    }
+  >();
+
+  const computing = new Set<string>();
+
+  function computeGroupSize(groupId: string): {
+    width: number;
+    height: number;
+  } {
+    if (groupSizes.has(groupId)) return groupSizes.get(groupId)!;
+
+    // Cycle guard: if we're already computing this group, treat it as empty
+    if (computing.has(groupId)) {
+      const size = { width: EMPTY_GROUP_WIDTH, height: EMPTY_GROUP_HEIGHT };
+      groupSizes.set(groupId, size);
+      return size;
+    }
+    computing.add(groupId);
+
+    try {
+      const children = groupChildren.get(groupId) || [];
+
+      if (children.length === 0) {
+        const size = { width: EMPTY_GROUP_WIDTH, height: EMPTY_GROUP_HEIGHT };
+        groupSizes.set(groupId, size);
+        groupInternalLayouts.set(groupId, {
+          childPositions: new Map(),
+          width: size.width,
+          height: size.height,
+        });
+        return size;
+      }
+
+      for (const child of children) {
+        if (allGroupIds.has(child.id)) {
+          computeGroupSize(child.id);
+        }
+      }
+
+      const ig = new dagre.graphlib.Graph();
+      ig.setDefaultEdgeLabel(() => ({}));
+      ig.setGraph({
+        rankdir,
+        nodesep: Math.max(nodesep, 80),
+        ranksep: Math.max(ranksep, 100),
+        edgesep,
+      });
+
+      for (const child of children) {
+        if (allGroupIds.has(child.id)) {
+          const childSize = groupSizes.get(child.id)!;
+          ig.setNode(child.id, {
+            width: childSize.width,
+            height: childSize.height,
+          });
+        } else {
+          const s = nodeSize(child.type);
+          ig.setNode(child.id, { width: s.w, height: s.h });
+        }
+      }
+
+      const childIdSet = new Set(children.map((c) => c.id));
+      for (const edge of edges) {
+        if (childIdSet.has(edge.source) && childIdSet.has(edge.target)) {
+          ig.setEdge(edge.source, edge.target);
+        }
+      }
+
+      dagre.layout(ig);
+
+      const childPositions = new Map<
+        string,
+        { x: number; y: number; w: number; h: number }
+      >();
+      let minX = Infinity,
+        minY = Infinity,
+        maxX = -Infinity,
+        maxY = -Infinity;
+
+      for (const child of children) {
+        const pos = ig.node(child.id);
+        if (!pos) continue;
+        const left = pos.x - pos.width / 2;
+        const top = pos.y - pos.height / 2;
+        const right = pos.x + pos.width / 2;
+        const bottom = pos.y + pos.height / 2;
+        childPositions.set(child.id, {
+          x: left,
+          y: top,
+          w: pos.width,
+          h: pos.height,
+        });
+        minX = Math.min(minX, left);
+        minY = Math.min(minY, top);
+        maxX = Math.max(maxX, right);
+        maxY = Math.max(maxY, bottom);
+      }
+
+      const contentH = maxY - minY;
+      const contentW = maxX - minX;
+      const totalW = contentW + GROUP_PADDING_X * 2;
+      const totalH =
+        GROUP_HEADER_HEIGHT +
+        GROUP_CONTENT_PADDING_TOP +
+        contentH +
+        GROUP_CONTENT_PADDING_BOTTOM;
+      const contentTop = GROUP_HEADER_HEIGHT + GROUP_CONTENT_PADDING_TOP;
+
+      for (const [id, pos] of childPositions) {
+        childPositions.set(id, {
+          x: pos.x - minX + GROUP_PADDING_X,
+          y: pos.y - minY + contentTop,
+          w: pos.w,
+          h: pos.h,
+        });
+      }
+
+      groupSizes.set(groupId, { width: totalW, height: totalH });
+      groupInternalLayouts.set(groupId, {
+        childPositions,
+        width: totalW,
+        height: totalH,
+      });
+      return { width: totalW, height: totalH };
+    } finally {
+      computing.delete(groupId);
+    }
+  }
+
+  for (const groupId of allGroupIds) {
+    computeGroupSize(groupId);
+  }
+
+  const topLevelGroupIds = new Set<string>();
+  for (const groupId of allGroupIds) {
+    const node = nodeById.get(groupId);
+    if (!node?.parentId || !allGroupIds.has(node.parentId)) {
+      topLevelGroupIds.add(groupId);
+    }
+  }
+
+  const outerG = new dagre.graphlib.Graph();
+  outerG.setDefaultEdgeLabel(() => ({}));
+  outerG.setGraph({ rankdir, nodesep, ranksep, edgesep });
+
+  for (const groupId of topLevelGroupIds) {
+    const size = groupSizes.get(groupId)!;
+    outerG.setNode(groupId, { width: size.width, height: size.height });
+  }
+
+  for (const node of nodes) {
+    if (allGroupIds.has(node.id) || childNodeIds.has(node.id)) continue;
+    const s = nodeSize(node.type);
+    outerG.setNode(node.id, { width: s.w, height: s.h });
+  }
+
+  const outerEdgeSet = new Set<string>();
+  for (const edge of edges) {
+    const srcIsChild = childNodeIds.has(edge.source);
+    const tgtIsChild = childNodeIds.has(edge.target);
+    const srcIsGroup = allGroupIds.has(edge.source);
+    const tgtIsGroup = allGroupIds.has(edge.target);
+
+    if (srcIsChild && tgtIsChild) continue;
+    if (srcIsGroup || tgtIsGroup) continue;
+
+    let src = edge.source;
+    let tgt = edge.target;
+
+    if (srcIsChild) {
+      let parent = nodeById.get(edge.source)?.parentId;
+      while (parent && !topLevelGroupIds.has(parent)) {
+        parent = nodeById.get(parent)?.parentId;
+      }
+      if (parent) src = parent;
+    }
+    if (tgtIsChild) {
+      let parent = nodeById.get(edge.target)?.parentId;
+      while (parent && !topLevelGroupIds.has(parent)) {
+        parent = nodeById.get(parent)?.parentId;
+      }
+      if (parent) tgt = parent;
+    }
+
+    const key = `${src}->${tgt}`;
+    if (!outerEdgeSet.has(key)) {
+      outerEdgeSet.add(key);
+      outerG.setEdge(src, tgt);
+    }
+  }
+
+  dagre.layout(outerG);
+
+  const outerPositions = new Map<
+    string,
+    { x: number; y: number; width: number; height: number }
+  >();
+  outerG.nodes().forEach((id: string) => {
+    const pos = outerG.node(id);
+    if (pos) {
+      outerPositions.set(id, {
+        x: pos.x,
+        y: pos.y,
+        width: pos.width,
+        height: pos.height,
+      });
+    }
+  });
+
+  const layoutNodes: Node[] = [];
+
+  function emitGroup(groupId: string, parentGroupId?: string) {
+    const node = nodeById.get(groupId);
+    if (!node) return;
+
+    const layout = groupInternalLayouts.get(groupId);
+    if (!layout) return;
+
+    const base = {
+      name: node.label,
+      version: (node.metadata.version as string) || "",
+      summary: (node.metadata.summary as string) || "",
+    };
+
+    if (parentGroupId) {
+      const parentLayout = groupInternalLayouts.get(parentGroupId);
+      const childPos = parentLayout?.childPositions.get(groupId);
+      if (!childPos) return;
+
+      layoutNodes.push({
+        id: groupId,
+        type: "group",
+        position: { x: childPos.x, y: childPos.y },
+        parentId: parentGroupId,
+        extent: "parent",
+        data: { mode: "full", domain: base },
+        style: {
+          width: layout.width,
+          height: layout.height,
+          background: "transparent",
+          border: "none",
+          padding: 0,
+        },
+      });
+    } else {
+      const outerPos = outerPositions.get(groupId);
+      if (!outerPos) return;
+
+      // Use internal layout dimensions for centering (dagre may report different width/height)
+      layoutNodes.push({
+        id: groupId,
+        type: "group",
+        position: {
+          x: outerPos.x - layout.width / 2,
+          y: outerPos.y - layout.height / 2,
+        },
+        data: { mode: "full", domain: base },
+        style: {
+          width: layout.width,
+          height: layout.height,
+          background: "transparent",
+          border: "none",
+          padding: 0,
+        },
+      });
+    }
+
+    const children = groupChildren.get(groupId) || [];
+    for (const child of children) {
+      if (allGroupIds.has(child.id)) {
+        emitGroup(child.id, groupId);
+      }
+    }
+    for (const child of children) {
+      if (allGroupIds.has(child.id)) continue;
+      const childPos = layout.childPositions.get(child.id);
+      if (!childPos) continue;
+
+      layoutNodes.push({
+        id: child.id,
+        type: child.type,
+        position: { x: childPos.x, y: childPos.y },
+        parentId: groupId,
+        extent: "parent",
+        data: buildNodeData(child, style),
+      });
+    }
+  }
+
+  for (const groupId of topLevelGroupIds) {
+    emitGroup(groupId);
+  }
+
+  for (const node of nodes) {
+    if (allGroupIds.has(node.id) || childNodeIds.has(node.id)) continue;
+    const pos = outerPositions.get(node.id);
+    if (!pos) continue;
+
+    layoutNodes.push({
+      id: node.id,
+      type: node.type,
+      position: { x: pos.x - pos.width / 2, y: pos.y - pos.height / 2 },
+      data: buildNodeData(node, style),
+    });
+  }
+
+  const layoutEdges: Edge[] = edges
+    .filter(
+      (edge) => !allGroupIds.has(edge.source) && !allGroupIds.has(edge.target),
+    )
+    .map((edge) => {
+      const collection = getMessageCollection(edge, nodeById);
+      const isFlowStep = edge.type === "flow-step";
+      const isCalls = edge.type === "calls";
+      const isBidirectional = edge.type === "reads-writes";
+      const arrowMarker = {
+        type: MarkerType.ArrowClosed,
+        width: 20,
+        height: 20,
+        color: "rgb(var(--ec-page-text-muted))",
+      };
+      return {
+        id: edge.id,
+        source: edge.source,
+        target: edge.target,
+        label: isBidirectional
+          ? "reads/writes"
+          : isFlowStep
+            ? edge.label || undefined
+            : edge.label || edge.type,
+        type: isFlowStep ? "flow-edge" : isCalls ? "step" : "animated",
+        markerEnd: arrowMarker,
+        ...(isBidirectional ? { markerStart: arrowMarker } : {}),
+        data: { edgeType: edge.type, message: { collection } },
+      };
+    });
+
+  return { nodes: layoutNodes, edges: layoutEdges };
+}
+
+const MESSAGE_TYPES = new Set(["event", "command", "query"]);
+
+function getMessageCollection(
+  edge: GraphEdge,
+  nodeById: Map<string, GraphNode>,
+): string | undefined {
+  const targetNode = nodeById.get(edge.target);
+  if (targetNode && MESSAGE_TYPES.has(targetNode.type)) {
+    return `${targetNode.type}s`;
+  }
+  const sourceNode = nodeById.get(edge.source);
+  if (sourceNode && MESSAGE_TYPES.has(sourceNode.type)) {
+    return `${sourceNode.type}s`;
+  }
+  return targetNode ? `${targetNode.type}s` : undefined;
+}
+
+function flatLayout(
+  nodes: GraphNode[],
+  edges: GraphEdge[],
+  graphOpts: {
+    rankdir: string;
+    nodesep: number;
+    ranksep: number;
+    edgesep: number;
+  },
+  nodeSize: (type: string) => { w: number; h: number },
+  style?: string,
+): { nodes: Node[]; edges: Edge[] } {
+  const g = new dagre.graphlib.Graph();
+  g.setDefaultEdgeLabel(() => ({}));
+  g.setGraph(graphOpts);
+
+  nodes.forEach((node) => {
+    const s = nodeSize(node.type);
+    g.setNode(node.id, { width: s.w, height: s.h });
+  });
+
+  edges.forEach((edge) => {
+    g.setEdge(edge.source, edge.target);
+  });
+
+  dagre.layout(g);
+
+  const layoutNodes: Node[] = nodes.map((node) => {
+    const pos = g.node(node.id);
+    return {
+      id: node.id,
+      type: node.type,
+      position: { x: pos.x - pos.width / 2, y: pos.y - pos.height / 2 },
+      data: buildNodeData(node, style),
+    };
+  });
+
+  const nodeById = new Map(nodes.map((n) => [n.id, n]));
+  const layoutEdges: Edge[] = edges.map((edge) => {
+    const collection = getMessageCollection(edge, nodeById);
+    const isFlowStep = edge.type === "flow-step";
+    const isCalls = edge.type === "calls";
+    const isBidirectional = edge.type === "reads-writes";
+    const arrowMarker = {
+      type: MarkerType.ArrowClosed,
+      width: 20,
+      height: 20,
+      color: "rgb(var(--ec-page-text-muted))",
+    };
+    return {
+      id: edge.id,
+      source: edge.source,
+      target: edge.target,
+      label: isBidirectional
+        ? "reads/writes"
+        : isFlowStep
+          ? edge.label || undefined
+          : edge.label || edge.type,
+      type: isFlowStep ? "flow-edge" : isCalls ? "step" : "animated",
+      markerEnd: arrowMarker,
+      ...(isBidirectional ? { markerStart: arrowMarker } : {}),
+      data: { edgeType: edge.type, message: { collection } },
+    };
+  });
+
+  return { nodes: layoutNodes, edges: layoutEdges };
+}
diff --git a/packages/visualiser/src/utils/local-packing.test.ts b/packages/visualiser/src/utils/local-packing.test.ts
new file mode 100644
index 000000000..32afd9940
--- /dev/null
+++ b/packages/visualiser/src/utils/local-packing.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import {
+  packNodesAroundBounds,
+  rectsIntersect,
+  type PackableNode,
+} from "./local-packing";
+
+const node = (
+  id: string,
+  x: number,
+  y: number,
+  width = 100,
+  height = 100,
+): PackableNode => ({
+  id,
+  position: { x, y },
+  measured: { width, height },
+});
+
+describe("packNodesAroundBounds", () => {
+  it("moves intersecting nodes into the nearest non-overlapping slot", () => {
+    const nodes = [
+      node("group", 0, 0, 300, 300),
+      node("move", 40, 180),
+      node("occupied", 40, 360),
+    ];
+    const positions = packNodesAroundBounds({
+      nodes,
+      movableNodeIds: new Set(["move"]),
+      protectedBounds: { x: 0, y: 0, width: 300, height: 300 },
+      groupNodeId: "group",
+      gap: 40,
+    });
+
+    expect(positions.get("move")).toEqual({ x: 40, y: 500 });
+  });
+
+  it("keeps moved nodes from colliding with existing nodes and each other", () => {
+    const nodes = [
+      node("group", 0, 0, 300, 300),
+      node("move-a", 40, 180),
+      node("move-b", 40, 220),
+      node("occupied", 40, 360),
+    ];
+    const positions = packNodesAroundBounds({
+      nodes,
+      movableNodeIds: new Set(["move-a", "move-b"]),
+      protectedBounds: { x: 0, y: 0, width: 300, height: 300 },
+      groupNodeId: "group",
+      gap: 40,
+    });
+    const movedRects = ["move-a", "move-b"].map((id) => {
+      const moved = nodes.find((n) => n.id === id)!;
+      const position = positions.get(id)!;
+      return {
+        ...position,
+        width: moved.measured!.width!,
+        height: moved.measured!.height!,
+      };
+    });
+
+    expect(rectsIntersect(movedRects[0], movedRects[1], 40)).toBe(false);
+    expect(movedRects.map((rect) => rect.y)).toEqual([500, 640]);
+  });
+
+  it("moves nodes above the protected bounds when they start above the group center", () => {
+    const nodes = [node("group", 0, 0, 300, 300), node("move", 40, 20)];
+    const positions = packNodesAroundBounds({
+      nodes,
+      movableNodeIds: new Set(["move"]),
+      protectedBounds: { x: 0, y: 0, width: 300, height: 300 },
+      groupNodeId: "group",
+      gap: 40,
+    });
+
+    expect(positions.get("move")).toEqual({ x: 40, y: -140 });
+  });
+});
diff --git a/packages/visualiser/src/utils/local-packing.ts b/packages/visualiser/src/utils/local-packing.ts
new file mode 100644
index 000000000..9287c20cc
--- /dev/null
+++ b/packages/visualiser/src/utils/local-packing.ts
@@ -0,0 +1,150 @@
+export type Position = {
+  x: number;
+  y: number;
+};
+
+export type Rect = Position & {
+  width: number;
+  height: number;
+};
+
+export type PackableNode = {
+  id: string;
+  parentId?: string;
+  position: Position;
+  style?: {
+    width?: number | string;
+    height?: number | string;
+  };
+  measured?: {
+    width?: number;
+    height?: number;
+  };
+  width?: number;
+  height?: number;
+};
+
+const toNumber = (value: unknown) => {
+  if (typeof value === "number") return value;
+  if (typeof value === "string") {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+};
+
+export const getPackableNodeSize = (node: PackableNode) => ({
+  width:
+    toNumber(node.measured?.width) ??
+    toNumber(node.width) ??
+    toNumber(node.style?.width) ??
+    260,
+  height:
+    toNumber(node.measured?.height) ??
+    toNumber(node.height) ??
+    toNumber(node.style?.height) ??
+    140,
+});
+
+export const rectsIntersect = (a: Rect, b: Rect, gap = 0) =>
+  a.x < b.x + b.width + gap &&
+  a.x + a.width + gap > b.x &&
+  a.y < b.y + b.height + gap &&
+  a.y + a.height + gap > b.y;
+
+const toRect = (node: PackableNode, y = node.position.y): Rect => {
+  const size = getPackableNodeSize(node);
+  return {
+    x: node.position.x,
+    y,
+    width: size.width,
+    height: size.height,
+  };
+};
+
+export const packNodesAroundBounds = ({
+  nodes,
+  movableNodeIds,
+  protectedBounds,
+  groupNodeId,
+  gap = 40,
+}: {
+  nodes: PackableNode[];
+  movableNodeIds: Set<string>;
+  protectedBounds: Rect;
+  groupNodeId: string;
+  gap?: number;
+}) => {
+  const movableNodes = nodes
+    .filter((node) => movableNodeIds.has(node.id))
+    .sort((a, b) => a.position.y - b.position.y);
+  const movableIds = new Set(movableNodes.map((node) => node.id));
+  const occupiedRects: Rect[] = [
+    protectedBounds,
+    ...nodes
+      .filter(
+        (node) =>
+          !node.parentId && node.id !== groupNodeId && !movableIds.has(node.id),
+      )
+      .map((node) => toRect(node)),
+  ];
+  const plannedPositions = new Map<string, Position>();
+  const groupCenterY = protectedBounds.y + protectedBounds.height / 2;
+
+  const placeNode = (node: PackableNode) => {
+    const size = getPackableNodeSize(node);
+    const nodeCenterY = node.position.y + size.height / 2;
+    const moveDirection = nodeCenterY >= groupCenterY ? 1 : -1;
+    let y =
+      moveDirection > 0
+        ? Math.max(
+            node.position.y,
+            protectedBounds.y + protectedBounds.height + gap,
+          )
+        : Math.min(node.position.y, protectedBounds.y - size.height - gap);
+    let attempts = 0;
+
+    while (attempts < occupiedRects.length + 8) {
+      const rect = {
+        x: node.position.x,
+        y,
+        width: size.width,
+        height: size.height,
+      };
+      const collision = occupiedRects.find((occupied) =>
+        rectsIntersect(rect, occupied, gap),
+      );
+      if (!collision) {
+        occupiedRects.push(rect);
+        plannedPositions.set(node.id, { ...node.position, y });
+        return;
+      }
+
+      y =
+        moveDirection > 0
+          ? collision.y + collision.height + gap
+          : collision.y - size.height - gap;
+      attempts += 1;
+    }
+
+    occupiedRects.push({
+      x: node.position.x,
+      y,
+      width: size.width,
+      height: size.height,
+    });
+    plannedPositions.set(node.id, { ...node.position, y });
+  };
+
+  const below = movableNodes.filter((node) => {
+    const size = getPackableNodeSize(node);
+    return node.position.y + size.height / 2 >= groupCenterY;
+  });
+  const belowIds = new Set(below.map((node) => node.id));
+  const above = movableNodes.filter((node) => !belowIds.has(node.id)).reverse();
+
+  below.forEach(placeNode);
+  above.forEach(placeNode);
+
+  return plannedPositions;
+};
diff --git a/packages/visualiser/src/utils/message-group-expansion.test.ts b/packages/visualiser/src/utils/message-group-expansion.test.ts
new file mode 100644
index 000000000..7f2473adc
--- /dev/null
+++ b/packages/visualiser/src/utils/message-group-expansion.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildMessageGroupExpansionNodes,
+  getExpandedMessageGroupNode,
+  type GraphNode,
+} from "./message-group-expansion";
+
+const node = (
+  id: string,
+  type: string,
+  x = 0,
+  y = 0,
+  parentId?: string,
+): GraphNode => ({
+  id,
+  type,
+  parentId,
+  position: { x, y },
+});
+
+describe("message group expansion helpers", () => {
+  it("detects when a message group is already expanded", () => {
+    const nodes = [
+      node("message-group-orders-sends-Updates", "messageGroupExpanded"),
+      node("OrderCreated-1.0.0", "events"),
+    ];
+
+    expect(
+      getExpandedMessageGroupNode(nodes, "message-group-orders-sends-Updates"),
+    ).toBe(nodes[0]);
+  });
+
+  it("replaces an existing expanded group and children instead of appending duplicates", () => {
+    const groupNodeId = "message-group-orders-sends-Updates";
+    const expandedContainer = node(groupNodeId, "messageGroupExpanded", 10, 20);
+    const child = node(
+      `${groupNodeId}__OrderCreated-1.0.0`,
+      "events",
+      70,
+      70,
+      groupNodeId,
+    );
+    const existingExpandedChild = node(
+      `${groupNodeId}__OrderCreated-1.0.0`,
+      "events",
+      70,
+      260,
+      groupNodeId,
+    );
+    const downstream = node("NotificationsService-1.0.0", "services", 0, 0);
+
+    const nextNodes = buildMessageGroupExpansionNodes({
+      currentNodes: [
+        node("OrdersService-1.0.0", "services"),
+        node(groupNodeId, "messageGroupExpanded", 10, 20),
+        existingExpandedChild,
+        downstream,
+      ],
+      groupNodeId,
+      expandedContainerNode: expandedContainer,
+      childNodes: [child],
+      downstreamNodes: [downstream],
+      getDownstreamPosition: (_node, index) => ({
+        x: 650,
+        y: 60 + index * 190,
+      }),
+    });
+
+    expect(nextNodes.filter((n) => n.id === groupNodeId)).toHaveLength(1);
+    expect(nextNodes.filter((n) => n.parentId === groupNodeId)).toHaveLength(1);
+    expect(nextNodes.filter((n) => n.id === downstream.id)).toHaveLength(1);
+  });
+});
diff --git a/packages/visualiser/src/utils/message-group-expansion.ts b/packages/visualiser/src/utils/message-group-expansion.ts
new file mode 100644
index 000000000..aaad98c34
--- /dev/null
+++ b/packages/visualiser/src/utils/message-group-expansion.ts
@@ -0,0 +1,59 @@
+export type GraphNode = {
+  id: string;
+  type?: string;
+  parentId?: string;
+  position: {
+    x: number;
+    y: number;
+  };
+  style?: {
+    width?: number | string;
+    height?: number | string;
+  };
+  [key: string]: unknown;
+};
+
+export const getExpandedMessageGroupNode = (
+  nodes: GraphNode[],
+  groupNodeId: string,
+) =>
+  nodes.find(
+    (node) => node.id === groupNodeId && node.type === "messageGroupExpanded",
+  );
+
+export const buildMessageGroupExpansionNodes = ({
+  currentNodes,
+  groupNodeId,
+  expandedContainerNode,
+  childNodes,
+  downstreamNodes,
+  getDownstreamPosition,
+}: {
+  currentNodes: GraphNode[];
+  groupNodeId: string;
+  expandedContainerNode: GraphNode;
+  childNodes: GraphNode[];
+  downstreamNodes: GraphNode[];
+  getDownstreamPosition: (
+    node: GraphNode,
+    index: number,
+  ) => GraphNode["position"];
+}) => {
+  const withoutExistingGroup = currentNodes.filter(
+    (node) => node.id !== groupNodeId && node.parentId !== groupNodeId,
+  );
+  const existingIds = new Set(withoutExistingGroup.map((node) => node.id));
+  const newDownstream = downstreamNodes
+    .filter((node) => !existingIds.has(node.id))
+    .map((node, index) => ({
+      ...node,
+      position: getDownstreamPosition(node, index),
+    }));
+
+  return [
+    ...withoutExistingGroup,
+    expandedContainerNode,
+    ...childNodes,
+    ...newDownstream,
+  ];
+};
diff --git a/packages/visualiser/src/utils/protocols.tsx b/packages/visualiser/src/utils/protocols.tsx
new file mode 100644
index 000000000..58e9aeb0b
--- /dev/null
+++ b/packages/visualiser/src/utils/protocols.tsx
@@ -0,0 +1,111 @@
+import { Server, Radio, Wifi, Network, Globe, Cloud } from "lucide-react";
+
+// AWS Architecture Icons (from official AWS icon set)
+// Source: https://github.com/boyney123/awsicons (MIT)
+function AwsEventBridge({ className }: { className?: string }) {
+  return (
+    <svg viewBox="0 0 40 40" className={className}>
+      <defs>
+        <linearGradient x1="0%" y1="100%" x2="100%" y2="0%" id="eb-g">
+          <stop stopColor="#B0084D" offset="0%" />
+          <stop stopColor="#FF4F8B" offset="100%" />
+        </linearGradient>
+      </defs>
+      <rect width="40" height="40" rx="4" fill="url(#eb-g)" />
+      <path
+        fill="#FFF"
+        d="M11.056 28.594a2.09 2.09 0 01-2.08-2.096 2.09 2.09 0 012.08-2.095c1.146 0 2.08.94 2.08 2.095a2.09 2.09 0 01-2.08 2.096zm1.857.363a3.093 3.093 0 001.223-2.459c0-1.711-1.382-3.103-3.08-3.103-.42 0-.817.086-1.181.24l-1.799-3.139 2.362-4.122-.865-.504-2.506 4.375a.504.504 0 000 .503l1.966 3.43a3.09 3.09 0 00-1.056 2.32c0 1.712 1.38 3.104 3.079 3.104.342 0 .665-.07.973-.174l1.531 2.844a.5.5 0 00.44.263h5.5v-1.008h-5.203l-1.385-2.57zM29.944 16.56a2.09 2.09 0 01-2.08-2.096 2.09 2.09 0 012.08-2.096 2.09 2.09 0 012.078 2.096 2.09 2.09 0 01-2.079 2.096zm2.023.224a3.095 3.095 0 001.055-2.32c0-1.711-1.38-3.104-3.079-3.104-.34 0-.662.07-.97.173L27.442 8.62A.497.497 0 0027 8.351h-5.5V9.36h5.2l1.39 2.644a3.1 3.1 0 00-1.226 2.462c0 1.71 1.381 3.103 3.08 3.103.42 0 .818-.086 1.18-.24l1.799 3.14-2.362 4.12.866.504 2.505-4.373a.504.504 0 000-.504l-1.965-3.43zm-4.573 16.207a2.09 2.09 0 01-2.08-2.095 2.09 2.09 0 012.08-2.095 2.09 2.09 0 012.079 2.095 2.09 2.09 0 01-2.08 2.095zm-9.19-8.491l-2.293-4.002 2.292-4h4.584l2.294 4-2.294 4.002h-4.584zm-4.568-12.303a2.09 2.09 0 01-2.08-2.095 2.09 2.09 0 012.08-2.095c1.146 0 2.08.94 2.08 2.095a2.09 2.09 0 01-2.08 2.095zm13.758 15.596c-.625 0-1.206.191-1.692.515l-2.07-3.267 2.46-4.29a.504.504 0 000-.504l-2.582-4.505a.498.498 0 00-.433-.252h-4.752l-2.279-3.481a3.088 3.088 0 00.67-1.907c0-1.711-1.382-3.103-3.08-3.103-1.699 0-3.08 1.392-3.08 3.103 0 1.712 1.381 3.103 3.08 3.103a3.04 3.04 0 001.668-.502l2.09 3.194-2.492 4.35a.504.504 0 000 .503l2.58 4.506a.497.497 0 00.433.252h4.828l2.218 3.505A3.092 3.092 0 0027.395 34c1.698 0 3.079-1.393 3.079-3.103 0-1.712-1.381-3.103-3.08-3.103z"
+      />
+    </svg>
+  );
+}
+
+function AwsSqs({ className }: { className?: string }) {
+  return (
+    <svg viewBox="0 0 40 40" className={className}>
+      <defs>
+        <linearGradient x1="0%" y1="100%" x2="100%" y2="0%" id="sqs-g">
+          <stop stopColor="#B0084D" offset="0%" />
+          <stop stopColor="#FF4F8B" offset="100%" />
+        </linearGradient>
+      </defs>
+      <rect width="40" height="40" rx="4" fill="url(#sqs-g)" />
+      <path
+        fill="#FFF"
+        d="M14.342 22.35l1.505-1.444a.501.501 0 00.013-.708l-1.505-1.555-.72.695.676.7h-2.32v.999h2.274l-.617.592.694.72zm12.016.003l1.55-1.453a.5.5 0 00.011-.717l-1.55-1.546-.708.707.694.694H24.01v.999H26.3l-.627.588.686.728zm-8.77 1.008a6.458 6.458 0 012.417-.467c.842 0 1.665.163 2.416.467-.669-1.771-.669-3.971 0-5.742-1.502.607-3.331.607-4.833 0 .669 1.77.669 3.97 0 5.742zm-1.944 1.98a.494.494 0 010-.707c1.94-1.936 1.94-6.352 0-8.289a.494.494 0 010-.706.502.502 0 01.709 0c.921.92 2.252 1.447 3.652 1.447 1.4 0 2.731-.528 3.653-1.447a.502.502 0 01.854.354c0 .128-.05.255-.146.352-1.942 1.937-1.942 6.353 0 8.29a.501.501 0 01-.708.706c-.922-.92-2.253-1.447-3.653-1.447s-2.731.527-3.652 1.447a.502.502 0 01-.709 0zm16.898-5.905a1.562 1.562 0 00-1.106-.456 1.558 1.558 0 00-1.105 2.662c.61.608 1.601.608 2.211 0a1.56 1.56 0 000-2.206zm.708 2.913a2.56 2.56 0 01-1.814.749 2.56 2.56 0 01-1.813-4.369c1-.997 2.628-.997 3.627 0 1 .999 1 2.622 0 3.62zM9.67 19.447a1.562 1.562 0 00-1.106-.456 1.56 1.56 0 00-1.105 2.662 1.56 1.56 0 102.21-2.206zm.708 2.912a2.56 2.56 0 01-1.814.749A2.559 2.559 0 016.75 18.74c1-.997 2.627-.997 3.627 0 1 .999 1 2.622 0 3.62zm17.057 6.551A10.514 10.514 0 0119.957 32a10.51 10.51 0 01-7.475-3.09c-1.316-1.312-2.074-2.44-2.537-3.774l-.947.327c.51 1.466 1.365 2.747 2.776 4.154A11.506 11.506 0 0019.957 33c3.093 0 6-1.201 8.185-3.383 1.14-1.139 2.279-2.43 2.87-4.156l-.948-.323c-.525 1.532-1.575 2.719-2.63 3.772zM9.945 15.86l-.947-.328c.512-1.467 1.368-2.749 2.778-4.156 4.51-4.5 11.85-4.502 16.362 0 1.08 1.077 2.266 2.414 2.874 4.156l-.948.328c-.54-1.55-1.635-2.78-2.634-3.777a10.508 10.508 0 00-7.473-3.087 10.508 10.508 0 00-7.472 3.087c-1.298 1.295-2.081 2.46-2.54 3.777z"
+      />
+    </svg>
+  );
+}
+
+function AwsSns({ className }: { className?: string }) {
+  return (
+    <svg viewBox="0 0 40 40" className={className}>
+      <defs>
+        <linearGradient x1="0%" y1="100%" x2="100%" y2="0%" id="sns-g">
+          <stop stopColor="#B0084D" offset="0%" />
+          <stop stopColor="#FF4F8B" offset="100%" />
+        </linearGradient>
+      </defs>
+      <rect width="40" height="40" rx="4" fill="url(#sns-g)" />
+      <path
+        fill="#FFF"
+        d="M7.01 20.078a1.1 1.1 0 011.105-1.093 1.1 1.1 0 011.104 1.093 1.1 1.1 0 01-1.104 1.093 1.1 1.1 0 01-1.105-1.093zM20.776 33C14.813 33 9.645 28.375 8.47 22.136a2.1 2.1 0 001.69-1.558h2.949v-1h-2.95a2.104 2.104 0 00-1.653-1.554C9.72 12.252 14.838 8 20.776 8c2.933 0 5.354.643 7.194 1.911l.575-.821C26.534 7.703 23.92 7 20.776 7c-6.51 0-12.104 4.726-13.308 11.096C6.62 18.368 6 19.149 6 20.078c0 .916.602 1.688 1.431 1.971C8.591 28.894 14.24 34 20.776 34c3.285 0 6.788-1.667 8.786-3.094l-.59-.811C26.947 31.541 23.627 33 20.777 33zM14.79 18.242c1.111.274 2.523.321 3.343.321.833 0 2.271-.047 3.402-.32l-2.401 5.014a.507.507 0 00-.048.215v2.324l-1.957.915v-3.239a.514.514 0 00-.044-.206l-2.295-5.024zm3.343-1.757c2.314 0 3.554.311 3.951.52-.417.234-1.745.558-3.95.558-2.184 0-3.483-.327-3.873-.558.37-.206 1.582-.52 3.872-.52zm-1.78 11.438a.511.511 0 00.486.03l2.968-1.388a.5.5 0 00.288-.452v-2.529l2.909-6.074a.806.806 0 00.189-.51c0-1.252-2.751-1.515-5.06-1.515-2.266 0-4.969.263-4.969 1.515 0 .19.067.355.18.502l2.775 6.077V27.5c0 .172.088.331.235.423zM30.877 27a1.1 1.1 0 011.104 1.093 1.1 1.1 0 01-1.104 1.093 1.1 1.1 0 01-1.104-1.093A1.1 1.1 0 0130.876 27zm0-16.03a1.1 1.1 0 011.104 1.093 1.1 1.1 0 01-1.104 1.093 1.1 1.1 0 01-1.104-1.093 1.1 1.1 0 011.104-1.093zm1.01 8.015a1.1 1.1 0 011.104 1.093 1.1 1.1 0 01-1.104 1.093 1.1 1.1 0 01-1.104-1.093 1.1 1.1 0 011.104-1.093zm-4.607 1.593h2.561a2.108 2.108 0 002.046 1.593A2.106 2.106 0 0034 20.078a2.106 2.106 0 00-2.114-2.093c-.992 0-1.818.681-2.046 1.593H27.28v-7.015h1.551a2.108 2.108 0 002.046 1.593 2.106 2.106 0 002.114-2.093 2.106 2.106 0 00-2.114-2.093c-.991 0-1.818.681-2.046 1.593h-2.056a.502.502 0 00-.505.5v7.515h-3.061v1h3.061v7.515c0 .277.226.5.505.5h2.056a2.108 2.108 0 002.046 1.593 2.106 2.106 0 002.114-2.093A2.106 2.106 0 0030.876 26c-.991 0-1.818.681-2.046 1.593H27.28v-7.015z"
+      />
+    </svg>
+  );
+}
+
+// Icon type: "svg" = full self-contained SVG, "lucide" = Lucide component (needs wrapper)
+type IconEntry = { component: any; type: "svg" | "lucide" };
+
+// Map protocol names to icons
+const protocolIconMap: { [key: string]: IconEntry } = {
+  // Web protocols
+  http: { component: Server, type: "lucide" },
+  https: { component: Server, type: "lucide" },
+  ws: { component: Radio, type: "lucide" },
+  wss: { component: Radio, type: "lucide" },
+  websocket: { component: Radio, type: "lucide" },
+
+  // Messaging protocols
+  mqtt: { component: Wifi, type: "lucide" },
+  amqp: { component: Network, type: "lucide" },
+  grpc: { component: Globe, type: "lucide" },
+  graphql: { component: Globe, type: "lucide" },
+
+  // Message brokers
+  kafka: { component: Network, type: "lucide" },
+  rabbitmq: { component: Network, type: "lucide" },
+  redis: { component: Network, type: "lucide" },
+  nats: { component: Network, type: "lucide" },
+  pulsar: { component: Network, type: "lucide" },
+  solace: { component: Network, type: "lucide" },
+  activemq: { component: Network, type: "lucide" },
+
+  // AWS
+  sqs: { component: AwsSqs, type: "svg" },
+  sns: { component: AwsSns, type: "svg" },
+  eventbridge: { component: AwsEventBridge, type: "svg" },
+  kinesis: { component: Network, type: "lucide" },
+  msk: { component: Network, type: "lucide" },
+
+  // Google Cloud
+  pubsub: { component: Cloud, type: "lucide" },
+  googlepubsub: { component: Cloud, type: "lucide" },
+  cloudtasks: { component: Cloud, type: "lucide" },
+
+  // Azure
+  servicebus: { component: Cloud, type: "lucide" },
+  azureservicebus: { component: Cloud, type: "lucide" },
+  eventhubs: { component: Cloud, type: "lucide" },
+  azureeventhubs: { component: Cloud, type: "lucide" },
+  eventgrid: { component: Cloud, type: "lucide" },
+  azureeventgrid: { component: Cloud, type: "lucide" },
+};
+
+export const getIconForProtocol = (protocol?: string): IconEntry | null => {
+  if (!protocol) return null;
+  const normalizedProtocol = protocol.replace(/[-_\s]/g, "").toLowerCase();
+  return protocolIconMap[normalizedProtocol] || null;
+};
diff --git a/packages/visualiser/src/utils/url-builder.ts b/packages/visualiser/src/utils/url-builder.ts
new file mode 100644
index 000000000..e876e52fe
--- /dev/null
+++ b/packages/visualiser/src/utils/url-builder.ts
@@ -0,0 +1,41 @@
+/**
+ * Configurable URL builder utility
+ * Consumers (e.g. Astro adapter) can provide a custom builder via setBuildUrlFn
+ * to handle base paths, trailing slashes, etc.
+ */
+
+let _customBuildUrl: ((path: string) => string) | null = null;
+
+export function setBuildUrlFn(fn: ((path: string) => string) | null): void {
+  _customBuildUrl = fn;
+}
+
+export function buildUrl(path: string): string {
+  if (_customBuildUrl) {
+    return _customBuildUrl(path);
+  }
+  return path;
+}
+
+/**
+ * Navigate to a URL, preferring the host app's view-transition router when it's
+ * available so navigations are soft/animated rather than a hard page reload.
+ *
+ * The visualiser package is intentionally decoupled from Astro, so the host
+ * (e.g. EventCatalog's VisualiserLayout) bridges its router onto
+ * `window.__ecNavigate`. When that bridge isn't present (standalone usage), we
+ * fall back to a normal `location.href` assignment.
+ *
+ * `url` should already be passed through `buildUrl`.
+ */
+export function navigateTo(url: string): void {
+  if (typeof window === "undefined") return;
+  const ecNavigate = (
+    window as unknown as { __ecNavigate?: (url: string) => void }
+  ).__ecNavigate;
+  if (typeof ecNavigate === "function") {
+    ecNavigate(url);
+    return;
+  }
+  window.location.href = url;
+}
diff --git a/packages/visualiser/src/utils/utils/utils.ts b/packages/visualiser/src/utils/utils/utils.ts
new file mode 100644
index 000000000..c247a9c9b
--- /dev/null
+++ b/packages/visualiser/src/utils/utils/utils.ts
@@ -0,0 +1,162 @@
+// Can't use the CollectionEntry type from astro:content  because a client component is using this util
+
+import { MarkerType, Position, type Edge, type Node } from "@xyflow/react";
+import dagre from "dagre";
+
+interface BaseCollectionData {
+  id: string;
+  version: string;
+}
+
+interface CollectionItem {
+  collection: string;
+  data: BaseCollectionData;
+}
+
+interface MessageCollectionItem extends CollectionItem {
+  collection: "commands" | "events" | "queries";
+}
+
+export const generateIdForNode = (node: CollectionItem) => {
+  return `${node.data.id}-${node.data.version}`;
+};
+export const generateIdForNodes = (nodes: any) => {
+  return nodes
+    .map((node: any) => `${node.data.id}-${node.data.version}`)
+    .join("-");
+};
+export const generatedIdForEdge = (
+  source: CollectionItem,
+  target: CollectionItem,
+) => {
+  return `${source.data.id}-${source.data.version}-${target.data.id}-${target.data.version}`;
+};
+
+export const getColorFromString = (id: string) => {
+  // Takes the given id (string) and returns a custom hex color based on the id
+  // Create a hash from the string
+  let hash = 0;
+  for (let i = 0; i < id.length; i++) {
+    hash = id.charCodeAt(i) + ((hash << 5) - hash);
+  }
+
+  // Convert the hash into a hex color
+  let color = "#";
+  for (let i = 0; i < 3; i++) {
+    const value = (hash >> (i * 8)) & 0xff;
+    color += value.toString(16).padStart(2, "0");
+  }
+
+  return color;
+};
+
+export const getEdgeLabelForServiceAsTarget = (data: MessageCollectionItem) => {
+  const type = data.collection;
+  switch (type) {
+    case "commands":
+      return "invokes";
+    case "events":
+      return "publishes \nevent";
+    case "queries":
+      return "requests";
+    default:
+      return "sends to";
+  }
+};
+export const getEdgeLabelForMessageAsSource = (
+  data: MessageCollectionItem,
+  throughChannel = false,
+) => {
+  const type = data.collection;
+  switch (type) {
+    case "commands":
+      return "accepts";
+    case "events":
+      return throughChannel ? "subscribed to" : "subscribed by";
+    case "queries":
+      return "accepts";
+    default:
+      return "sends to";
+  }
+};
+
+export const calculatedNodes = (flow: dagre.graphlib.Graph, nodes: Node[]) => {
+  return nodes.map((node: any) => {
+    const { x, y } = flow.node(node.id);
+    return { ...node, position: { x, y } };
+  });
+};
+
+// Creates a new dagre graph
+export const createDagreGraph = ({
+  ranksep = 180,
+  nodesep = 50,
+  ...rest
+}: any) => {
+  const graph = new dagre.graphlib.Graph({ compound: true });
+  graph.setGraph({ rankdir: "LR", ranksep, nodesep, ...rest });
+  graph.setDefaultEdgeLabel(() => ({}));
+  return graph;
+};
+
+export const createEdge = (edgeOptions: Edge): Edge => {
+  return {
+    label: "subscribed by",
+    animated: false,
+    // markerStart: {
+    //   type: MarkerType.Arrow,
+    //   width: 40,
+    //   height: 40,
+    // },
+    markerEnd: {
+      type: MarkerType.ArrowClosed,
+      width: 40,
+      height: 40,
+      color: "rgb(var(--ec-page-text-muted))",
+    },
+    style: {
+      strokeWidth: 1.5,
+      stroke: "rgb(var(--ec-page-text-muted))",
+      strokeDasharray: "5 5",
+    },
+    ...edgeOptions,
+  };
+};
+
+export const createNode = (values: Node): Node => {
+  return {
+    sourcePosition: Position.Right,
+    targetPosition: Position.Left,
+    ...values,
+  };
+};
+
+type DagreGraph = any;
+
+export const getNodesAndEdgesFromDagre = ({
+  nodes,
+  edges,
+  defaultFlow,
+}: {
+  nodes: Node[];
+  edges: Edge[];
+  defaultFlow?: DagreGraph;
+}) => {
+  const flow = defaultFlow || createDagreGraph({ ranksep: 300, nodesep: 50 });
+
+  nodes.forEach((node: any) => {
+    flow.setNode(node.id, { width: 150, height: 100 });
+  });
+
+  edges.forEach((edge: any) => {
+    flow.setEdge(edge.source, edge.target);
+  });
+
+  // Render the diagram in memory getting hte X and Y
+  dagre.layout(flow);
+
+  return {
+    nodes: calculatedNodes(flow, nodes),
+    edges,
+  };
+};
diff --git a/packages/visualiser/src/vite-env.d.ts b/packages/visualiser/src/vite-env.d.ts
new file mode 100644
index 000000000..780ce9353
--- /dev/null
+++ b/packages/visualiser/src/vite-env.d.ts
@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+
+declare module "*.svg?raw" {
+  const content: string;
+  export default content;
+}
diff --git a/packages/visualiser/tailwind.config.js b/packages/visualiser/tailwind.config.js
new file mode 100644
index 000000000..2ce8b4a76
--- /dev/null
+++ b/packages/visualiser/tailwind.config.js
@@ -0,0 +1,8 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ['./src/**/*.{js,ts,jsx,tsx}'],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};
diff --git a/packages/visualiser/tsconfig.json b/packages/visualiser/tsconfig.json
new file mode 100644
index 000000000..db6b1b127
--- /dev/null
+++ b/packages/visualiser/tsconfig.json
@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noFallthroughCasesInSwitch": true,
+
+    /* Path aliases */
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}
diff --git a/packages/visualiser/tsconfig.node.json b/packages/visualiser/tsconfig.node.json
new file mode 100644
index 000000000..5a5c3ee7f
--- /dev/null
+++ b/packages/visualiser/tsconfig.node.json
@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["tsup.config.ts"]
+}
diff --git a/packages/visualiser/tsup.config.ts b/packages/visualiser/tsup.config.ts
new file mode 100644
index 000000000..97a454b2f
--- /dev/null
+++ b/packages/visualiser/tsup.config.ts
@@ -0,0 +1,58 @@
+import { defineConfig } from 'tsup';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  external: [
+    'react',
+    'react-dom',
+    '@xyflow/react',
+    'lucide-react',
+    '@heroicons/react',
+    '@radix-ui/react-dropdown-menu',
+    '@radix-ui/react-context-menu',
+    '@radix-ui/react-dialog',
+    '@radix-ui/react-tooltip',
+    'html-to-image',
+    'mermaid',
+  ],
+  loader: {
+    '.svg': 'text',
+  },
+  esbuildOptions(options) {
+    options.jsx = 'automatic';
+    options.loader = {
+      ...options.loader,
+      '.svg': 'text',
+    };
+    options.plugins = [
+      ...(options.plugins || []),
+      {
+        name: 'svg-raw-loader',
+        setup(build) {
+          build.onResolve({ filter: /\.svg\?raw$/ }, (args) => {
+            const svgPath = path.resolve(args.resolveDir, args.path.replace('?raw', ''));
+            return {
+              path: svgPath,
+              namespace: 'svg-raw',
+            };
+          });
+
+          build.onLoad({ filter: /.*/, namespace: 'svg-raw' }, (args) => {
+            const svgContent = fs.readFileSync(args.path, 'utf8');
+            return {
+              contents: `export default ${JSON.stringify(svgContent)};`,
+              loader: 'js',
+            };
+          });
+        },
+      },
+    ];
+  },
+});
diff --git a/packages/vscode-extension/.gitignore b/packages/vscode-extension/.gitignore
new file mode 100644
index 000000000..849ddff3b
--- /dev/null
+++ b/packages/vscode-extension/.gitignore
@@ -0,0 +1 @@
+dist/
diff --git a/packages/vscode-extension/.vscode/launch.json b/packages/vscode-extension/.vscode/launch.json
new file mode 100644
index 000000000..0693022a1
--- /dev/null
+++ b/packages/vscode-extension/.vscode/launch.json
@@ -0,0 +1,14 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Run Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "runtimeExecutable": "${execPath}",
+      "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
+      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+      "sourceMaps": true
+    }
+  ]
+}
diff --git a/packages/vscode-extension/.vscodeignore b/packages/vscode-extension/.vscodeignore
new file mode 100644
index 000000000..71e76be04
--- /dev/null
+++ b/packages/vscode-extension/.vscodeignore
@@ -0,0 +1,7 @@
+src/**
+node_modules/**
+esbuild.mjs
+tsconfig.json
+.gitignore
+.turbo/**
+.vscode/**
diff --git a/packages/vscode-extension/README.md b/packages/vscode-extension/README.md
new file mode 100644
index 000000000..96c32c6b3
--- /dev/null
+++ b/packages/vscode-extension/README.md
@@ -0,0 +1,32 @@
+# EventCatalog for VS Code
+
+Language support and live preview for [EventCatalog](https://eventcatalog.dev) DSL files (`.ec`).
+
+## Features
+
+- **Syntax highlighting** for `.ec` files
+- **Live preview** — visualize your architecture as you type
+- **Code completion** — autocomplete for DSL keywords and references
+- **Diagnostics** — inline errors and warnings
+- **Go to definition** — navigate between services, events, commands, and more
+
+## Getting started
+
+1. Install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=eventcatalog.eventcatalog-dsl)
+2. Open or create a `.ec` file
+3. Use the command **"EventCatalog: Open Preview"** (`Cmd+Shift+P` / `Ctrl+Shift+P`) to see a live visualization
+
+## What is EventCatalog?
+
+[EventCatalog](https://eventcatalog.dev) is an open-source documentation tool for Event-Driven Architectures. It helps teams document events, commands, queries, services, domains, and flows in a discoverable catalog.
+
+## Resources
+
+- [Documentation](https://eventcatalog.dev/docs)
+- [Playground](https://compass.eventcatalog.dev)
+- [GitHub](https://github.com/event-catalog/eventcatalog)
+- [Discord](https://discord.gg/3rjaZMmrAm)
+
+## Feedback
+
+Found a bug or have a feature request? [Open an issue](https://github.com/event-catalog/eventcatalog/issues).
diff --git a/packages/vscode-extension/esbuild.mjs b/packages/vscode-extension/esbuild.mjs
new file mode 100644
index 000000000..ec041a2a1
--- /dev/null
+++ b/packages/vscode-extension/esbuild.mjs
@@ -0,0 +1,119 @@
+import * as esbuild from "esbuild";
+import {
+  cpSync,
+  mkdirSync,
+  existsSync,
+  readFileSync,
+  appendFileSync,
+} from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const watch = process.argv.includes("--watch");
+const production = process.argv.includes("--production");
+
+// Ensure output directories exist
+mkdirSync(resolve(__dirname, "dist"), { recursive: true });
+mkdirSync(resolve(__dirname, "syntaxes"), { recursive: true });
+
+// Copy TextMate grammar from language-server
+cpSync(
+  resolve(__dirname, "../language-server/syntaxes/ec.tmLanguage.json"),
+  resolve(__dirname, "syntaxes/ec.tmLanguage.json"),
+);
+
+const shared = {
+  bundle: true,
+  minify: production,
+  sourcemap: !production,
+};
+
+// Build 1: Extension host (lightweight — no Langium/parser)
+const extensionCtx = await esbuild.context({
+  ...shared,
+  entryPoints: [resolve(__dirname, "src/extension.ts")],
+  outfile: resolve(__dirname, "dist/extension.js"),
+  format: "cjs",
+  platform: "node",
+  external: ["vscode"],
+  keepNames: true,
+});
+
+// Build 1b: Parser (heavy — includes Langium, loaded on demand)
+const parserCtx = await esbuild.context({
+  ...shared,
+  entryPoints: [resolve(__dirname, "src/parser.ts")],
+  outfile: resolve(__dirname, "dist/parser.js"),
+  format: "cjs",
+  platform: "node",
+  external: ["vscode"],
+});
+
+// Build 2: Language server
+const serverCtx = await esbuild.context({
+  ...shared,
+  entryPoints: [resolve(__dirname, "../language-server/dist/main.js")],
+  outfile: resolve(__dirname, "dist/server.js"),
+  format: "cjs",
+  platform: "node",
+  external: ["vscode"],
+});
+
+// Build 3: Webview (React app with visualiser)
+const webviewCtx = await esbuild.context({
+  ...shared,
+  entryPoints: [resolve(__dirname, "src/webview/index.tsx")],
+  outfile: resolve(__dirname, "dist/webview.js"),
+  format: "iife",
+  platform: "browser",
+  jsx: "automatic",
+  define: {
+    "process.env.NODE_ENV": '"production"',
+  },
+});
+
+if (watch) {
+  // Copy visualiser CSS before starting watchers
+  const visualiserCssWatch = resolve(
+    __dirname,
+    "../visualiser/dist/styles-core.css",
+  );
+  if (existsSync(visualiserCssWatch)) {
+    const css = readFileSync(visualiserCssWatch, "utf-8");
+    appendFileSync(resolve(__dirname, "dist/webview.css"), "\n" + css);
+  }
+
+  await Promise.all([
+    extensionCtx.watch(),
+    parserCtx.watch(),
+    serverCtx.watch(),
+    webviewCtx.watch(),
+  ]);
+  console.log("Watching for changes...");
+} else {
+  await Promise.all([
+    extensionCtx.rebuild(),
+    parserCtx.rebuild(),
+    serverCtx.rebuild(),
+    webviewCtx.rebuild(),
+  ]);
+  await Promise.all([
+    extensionCtx.dispose(),
+    parserCtx.dispose(),
+    serverCtx.dispose(),
+    webviewCtx.dispose(),
+  ]);
+
+  // Append visualiser CSS to the esbuild-generated webview.css
+  const visualiserCss = resolve(
+    __dirname,
+    "../visualiser/dist/styles-core.css",
+  );
+  if (existsSync(visualiserCss)) {
+    const css = readFileSync(visualiserCss, "utf-8");
+    appendFileSync(resolve(__dirname, "dist/webview.css"), "\n" + css);
+  }
+
+  console.log("Build complete.");
+}
diff --git a/packages/vscode-extension/icons/ec-file.svg b/packages/vscode-extension/icons/ec-file.svg
new file mode 100644
index 000000000..a788f2c20
--- /dev/null
+++ b/packages/vscode-extension/icons/ec-file.svg
@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <!-- File shape -->
+  <path d="M6 2h14l6 6v20a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2z" fill="#1e1b4b" opacity="0.08"/>
+  <path d="M6 2h14l6 6v20a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2z" stroke="#6d28d9" stroke-width="1" fill="none"/>
+  <path d="M20 2v6h6" stroke="#6d28d9" stroke-width="1" fill="none"/>
+  <!-- EC text -->
+  <text x="16" y="22" text-anchor="middle" font-family="Arial, sans-serif" font-size="9" font-weight="bold" fill="#6d28d9">EC</text>
+</svg>
diff --git a/packages/vscode-extension/icons/logo.png b/packages/vscode-extension/icons/logo.png
new file mode 100644
index 000000000..6bba78c43
Binary files /dev/null and b/packages/vscode-extension/icons/logo.png differ
diff --git a/packages/vscode-extension/language-configuration.json b/packages/vscode-extension/language-configuration.json
new file mode 100644
index 000000000..38dbb529d
--- /dev/null
+++ b/packages/vscode-extension/language-configuration.json
@@ -0,0 +1,14 @@
+{
+  "comments": {
+    "lineComment": "//"
+  },
+  "brackets": [["{", "}"]],
+  "autoClosingPairs": [
+    { "open": "{", "close": "}" },
+    { "open": "\"", "close": "\"", "notIn": ["string"] }
+  ],
+  "surroundingPairs": [
+    { "open": "{", "close": "}" },
+    { "open": "\"", "close": "\"" }
+  ]
+}
diff --git a/packages/vscode-extension/package.json b/packages/vscode-extension/package.json
new file mode 100644
index 000000000..db68f03d5
--- /dev/null
+++ b/packages/vscode-extension/package.json
@@ -0,0 +1,111 @@
+{
+  "name": "eventcatalog-dsl",
+  "displayName": "EventCatalog",
+  "description": "Language support and live preview for EventCatalog DSL (.ec files)",
+  "version": "0.2.1",
+  "publisher": "eventcatalog",
+  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/event-catalog/eventcatalog",
+    "directory": "packages/vscode-extension"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "icon": "icons/logo.png",
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": [
+    "Programming Languages",
+    "Visualization"
+  ],
+  "keywords": [
+    "event-driven architecture",
+    "EDA",
+    "events",
+    "services",
+    "domains",
+    "architecture",
+    "documentation",
+    "asyncapi",
+    "openapi"
+  ],
+  "homepage": "https://eventcatalog.dev",
+  "bugs": {
+    "url": "https://github.com/event-catalog/eventcatalog/issues"
+  },
+  "sponsor": {
+    "url": "https://eventcatalog.dev"
+  },
+  "activationEvents": [
+    "onLanguage:ec",
+    "onWebviewPanel:eventcatalog.preview"
+  ],
+  "main": "./dist/extension.js",
+  "contributes": {
+    "languages": [
+      {
+        "id": "ec",
+        "aliases": [
+          "EventCatalog DSL",
+          "ec"
+        ],
+        "extensions": [
+          ".ec"
+        ],
+        "configuration": "./language-configuration.json",
+        "icon": {
+          "light": "./icons/ec-file.svg",
+          "dark": "./icons/ec-file.svg"
+        }
+      }
+    ],
+    "grammars": [
+      {
+        "language": "ec",
+        "scopeName": "source.ec",
+        "path": "./syntaxes/ec.tmLanguage.json"
+      }
+    ],
+    "commands": [
+      {
+        "command": "eventcatalog.openPreview",
+        "title": "EventCatalog: Open Preview",
+        "icon": "$(preview)"
+      }
+    ],
+    "menus": {
+      "editor/title": [
+        {
+          "when": "resourceLangId == ec",
+          "command": "eventcatalog.openPreview",
+          "group": "navigation"
+        }
+      ]
+    }
+  },
+  "scripts": {
+    "build": "node esbuild.mjs --production",
+    "build:bin": "node esbuild.mjs --production",
+    "dev": "node esbuild.mjs --watch",
+    "test": "vitest run",
+    "format": "prettier --write .",
+    "format:diff": "prettier --check ."
+  },
+  "dependencies": {
+    "@eventcatalog/language-server": "workspace:*",
+    "vscode-languageclient": "^9.0.1"
+  },
+  "devDependencies": {
+    "@eventcatalog/visualiser": "workspace:*",
+    "@types/vscode": "^1.85.0",
+    "@xyflow/react": "^12.4.0",
+    "esbuild": "^0.21.0",
+    "langium": "^3.3.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.7.0",
+    "prettier": "^3.2.5",
+    "vitest": "^3.0.0"
+  }
+}
diff --git a/packages/vscode-extension/src/extension.ts b/packages/vscode-extension/src/extension.ts
new file mode 100644
index 000000000..a2e6743e0
--- /dev/null
+++ b/packages/vscode-extension/src/extension.ts
@@ -0,0 +1,45 @@
+import * as vscode from "vscode";
+import { startLanguageClient, stopLanguageClient } from "./language-client";
+import { PreviewPanelManager } from "./preview-panel";
+
+let previewManager: PreviewPanelManager;
+
+export async function activate(context: vscode.ExtensionContext) {
+  // Start language client (LSP for diagnostics, completion, etc.)
+  startLanguageClient(context);
+
+  // Create preview manager
+  previewManager = new PreviewPanelManager(context);
+
+  // Register preview command
+  context.subscriptions.push(
+    vscode.commands.registerCommand("eventcatalog.openPreview", () => {
+      const editor = vscode.window.activeTextEditor;
+      if (editor && editor.document.languageId === "ec") {
+        previewManager.showPreview(editor);
+      }
+    }),
+  );
+
+  // Update preview on document changes
+  context.subscriptions.push(
+    vscode.workspace.onDidChangeTextDocument((e) => {
+      if (e.document.languageId === "ec") {
+        previewManager.onDocumentChanged(e.document);
+      }
+    }),
+  );
+
+  // Update preview when switching editors
+  context.subscriptions.push(
+    vscode.window.onDidChangeActiveTextEditor((editor) => {
+      if (editor && editor.document.languageId === "ec") {
+        previewManager.onDocumentChanged(editor.document);
+      }
+    }),
+  );
+}
+
+export function deactivate() {
+  stopLanguageClient();
+}
diff --git a/packages/vscode-extension/src/language-client.ts b/packages/vscode-extension/src/language-client.ts
new file mode 100644
index 000000000..fc398e781
--- /dev/null
+++ b/packages/vscode-extension/src/language-client.ts
@@ -0,0 +1,37 @@
+import * as vscode from "vscode";
+import * as path from "node:path";
+import { LanguageClient, TransportKind } from "vscode-languageclient/node";
+
+let client: LanguageClient | undefined;
+
+export function startLanguageClient(
+  context: vscode.ExtensionContext,
+): LanguageClient {
+  const serverModule = context.asAbsolutePath(path.join("dist", "server.js"));
+
+  const serverOptions = {
+    run: { module: serverModule, transport: TransportKind.ipc },
+    debug: {
+      module: serverModule,
+      transport: TransportKind.ipc,
+      options: { execArgv: ["--nolazy", "--inspect=6009"] },
+    },
+  };
+
+  const clientOptions = {
+    documentSelector: [{ scheme: "file", language: "ec" }],
+  };
+
+  client = new LanguageClient(
+    "eventcatalog-dsl",
+    "EventCatalog DSL",
+    serverOptions,
+    clientOptions,
+  );
+  client.start();
+  return client;
+}
+
+export function stopLanguageClient(): Thenable<void> | undefined {
+  return client?.stop();
+}
diff --git a/packages/vscode-extension/src/parser.ts b/packages/vscode-extension/src/parser.ts
new file mode 100644
index 000000000..078c7fbf1
--- /dev/null
+++ b/packages/vscode-extension/src/parser.ts
@@ -0,0 +1,354 @@
+import { EmptyFileSystem, URI } from "langium";
+import {
+  createEcServices,
+  astToGraph,
+  resolveSpecImportsAsync,
+} from "@eventcatalog/language-server";
+import type { DslGraph, ResolveError } from "@eventcatalog/language-server";
+
+// Singleton Langium services
+let services: ReturnType<typeof createEcServices> | null = null;
+let docCounter = 1;
+
+const MAX_URL_CACHE_SIZE = 100;
+
+function getServices() {
+  if (!services) {
+    services = createEcServices(EmptyFileSystem);
+  }
+  return services;
+}
+
+// Matches local file imports (not HTTP/HTTPS)
+const LOCAL_IMPORT_RE =
+  /^\s*import\s+(?:(?:events|commands|queries|channels|services|containers)\s+)?\{[^}]*\}\s*from\s*"(?!https?:\/\/)([^"]+)"\s*(?:\/\/.*)?$|^\s*import\s+[A-Z][a-zA-Z0-9_]*\s+from\s*"(?!https?:\/\/)([^"]+)"\s*(?:\/\/.*)?$/gm;
+
+// Matches URL imports for .ec files
+const URL_IMPORT_RE =
+  /^\s*import\s*\{[^}]*\}\s*from\s*"(https?:\/\/[^"]+)"\s*(?:\/\/.*)?$/gm;
+
+const urlFetchCache = new Map<string, string>();
+
+function toRawUrl(url: string): string {
+  const ghMatch = url.match(
+    /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/(?:blob|tree)\/(.+)$/,
+  );
+  return ghMatch
+    ? `https://raw.githubusercontent.com/${ghMatch[1]}/${ghMatch[2]}/${ghMatch[3]}`
+    : url;
+}
+
+async function fetchSpec(url: string): Promise<string> {
+  const rawUrl = toRawUrl(url);
+  const cached = urlFetchCache.get(rawUrl);
+  if (cached) return cached;
+
+  const resp = await fetch(rawUrl);
+  if (!resp.ok) throw new Error(`${resp.status} ${resp.statusText}`);
+
+  const text = await resp.text();
+  if (urlFetchCache.size >= MAX_URL_CACHE_SIZE) {
+    const firstKey = urlFetchCache.keys().next().value;
+    if (firstKey) urlFetchCache.delete(firstKey);
+  }
+  urlFetchCache.set(rawUrl, text);
+  return text;
+}
+
+async function resolveUrlImports(
+  files: Record<string, string>,
+): Promise<{ files: Record<string, string>; errors: string[] }> {
+  const errors: string[] = [];
+  const allUrls = new Map<string, string[]>();
+
+  for (const [filename, source] of Object.entries(files)) {
+    URL_IMPORT_RE.lastIndex = 0;
+    let match;
+    while ((match = URL_IMPORT_RE.exec(source)) !== null) {
+      const url = match[1];
+      const filenames = allUrls.get(url) ?? [];
+      filenames.push(filename);
+      allUrls.set(url, filenames);
+    }
+  }
+
+  if (allUrls.size === 0) return { files, errors };
+
+  const fetchResults = new Map<string, string>();
+  await Promise.all(
+    [...allUrls.keys()].map(async (url) => {
+      const cached = urlFetchCache.get(url);
+      if (cached) {
+        fetchResults.set(url, cached);
+        return;
+      }
+      try {
+        const resp = await fetch(url);
+        if (!resp.ok) {
+          errors.push(
+            `Failed to fetch "${url}": ${resp.status} ${resp.statusText}`,
+          );
+          return;
+        }
+        const text = await resp.text();
+        urlFetchCache.set(url, text);
+        fetchResults.set(url, text);
+      } catch (err) {
+        errors.push(`Failed to fetch "${url}": ${String(err)}`);
+      }
+    }),
+  );
+
+  const newFiles: Record<string, string> = {};
+  for (const [filename, source] of Object.entries(files)) {
+    newFiles[filename] = source
+      .replace(URL_IMPORT_RE, "")
+      .replace(/^\s*\n/gm, "");
+  }
+
+  for (const [url, content] of fetchResults) {
+    const segments = new URL(url).pathname.split("/");
+    const basename = segments[segments.length - 1] || "remote.ec";
+    let name = basename;
+    let i = 1;
+    while (newFiles[name]) {
+      name = `${i++}_${basename}`;
+    }
+    newFiles[name] = content;
+  }
+
+  return { files: newFiles, errors };
+}
+
+async function resolveAllImports(
+  inputFiles: Record<string, string>,
+  basePath?: string,
+): Promise<{ files: Record<string, string>; errors: string[] }> {
+  const { files: specResolved, errors: specErrors } =
+    await resolveSpecImportsAsync(inputFiles, fetchSpec, basePath);
+  const { files: urlResolved, errors: fetchErrors } =
+    await resolveUrlImports(specResolved);
+  return {
+    files: urlResolved,
+    errors: [...specErrors.map((e: ResolveError) => e.message), ...fetchErrors],
+  };
+}
+
+function stripAndConcatenate(
+  files: Record<string, string>,
+  order?: string[],
+): { source: string } {
+  const filenames = order ?? Object.keys(files);
+  const parts: string[] = [];
+
+  for (const filename of filenames) {
+    const content = files[filename].replace(LOCAL_IMPORT_RE, "");
+    parts.push(content);
+  }
+
+  return { source: parts.join("\n") };
+}
+
+// Matches local .ec file imports: import { Foo } from "./other.ec"
+const EC_IMPORT_PATH_RE =
+  /^\s*import\s+(?:(?:events|commands|queries|channels|services|containers)\s+)?\{[^}]*\}\s*from\s*"(?!https?:\/\/)([^"]+\.ec)"\s*(?:\/\/.*)?$|^\s*import\s+[A-Z][a-zA-Z0-9_]*\s+from\s*"(?!https?:\/\/)([^"]+\.ec)"\s*(?:\/\/.*)?$/gm;
+
+/**
+ * Collect the set of .ec files reachable from a starting file via local imports.
+ * Returns workspace-relative filenames (matching keys in `files`).
+ */
+function collectImportedEcFiles(
+  startFile: string,
+  files: Record<string, string>,
+): Set<string> {
+  const visited = new Set<string>();
+  const queue = [startFile];
+
+  while (queue.length > 0) {
+    const current = queue.pop()!;
+    if (visited.has(current)) continue;
+    visited.add(current);
+
+    const source = files[current];
+    if (!source) continue;
+
+    EC_IMPORT_PATH_RE.lastIndex = 0;
+    let match;
+    while ((match = EC_IMPORT_PATH_RE.exec(source)) !== null) {
+      const importPath = match[1] || match[2];
+      if (!importPath) continue;
+
+      // Resolve relative to the importing file's directory
+      const importingDir = current.includes("/")
+        ? current.substring(0, current.lastIndexOf("/"))
+        : "";
+      const resolved = importingDir
+        ? normalizePosixPath(`${importingDir}/${importPath}`)
+        : importPath.replace(/^\.\//, "");
+
+      // Check if this resolved path exists in the files map
+      const actualKey =
+        files[resolved] !== undefined
+          ? resolved
+          : files[`./${resolved}`] !== undefined
+            ? `./${resolved}`
+            : undefined;
+
+      if (actualKey && !visited.has(actualKey)) {
+        queue.push(actualKey);
+      }
+    }
+  }
+
+  return visited;
+}
+
+/**
+ * Normalize a POSIX-style path by resolving `.` and `..` segments.
+ */
+function normalizePosixPath(p: string): string {
+  const parts = p.split("/");
+  const result: string[] = [];
+  for (const part of parts) {
+    if (part === "." || part === "") continue;
+    if (part === "..") {
+      result.pop();
+    } else {
+      result.push(part);
+    }
+  }
+  return result.join("/");
+}
+
+async function parseSingle(
+  source: string,
+  activeVisualizer?: string,
+): Promise<DslGraph> {
+  const { shared } = getServices();
+
+  const uri = URI.parse(`file:///vscode-preview-${docCounter++}.ec`);
+  const document = shared.workspace.LangiumDocumentFactory.fromString(
+    source,
+    uri,
+  );
+  shared.workspace.LangiumDocuments.addDocument(document);
+  await shared.workspace.DocumentBuilder.build([document]);
+
+  const graph = astToGraph(document.parseResult.value, activeVisualizer);
+
+  try {
+    shared.workspace.LangiumDocuments.deleteDocument(uri);
+  } catch {
+    // Ignore cleanup errors
+  }
+
+  return graph;
+}
+
+/**
+ * Parse all workspace .ec files and return a DslGraph for the visualiser.
+ * When basePath is provided, catalog directory imports are also resolved.
+ */
+export async function parseWorkspaceFiles(
+  files: Record<string, string>,
+  activeVisualizer?: string,
+  basePath?: string,
+  activeFile?: string,
+): Promise<DslGraph> {
+  console.log("[EC Parser] Input files:", Object.keys(files));
+  const { files: resolved, errors } = await resolveAllImports(files, basePath);
+  const filenames = Object.keys(resolved);
+  if (errors.length > 0) {
+    console.log("[EC Parser] Resolve errors:");
+    for (const err of errors) {
+      console.log("[EC Parser]  -", err);
+    }
+  }
+  console.log("[EC Parser] Resolved files:", Object.keys(resolved));
+
+  if (filenames.length === 0) {
+    return { nodes: [], edges: [], empty: true };
+  }
+
+  // Use the explicitly provided active file, falling back to the first file
+  const mainFile =
+    activeFile && resolved[activeFile] ? activeFile : filenames[0];
+  const mainSource = resolved[mainFile];
+
+  if (filenames.length === 1) {
+    return parseSingle(mainSource, activeVisualizer);
+  }
+
+  // Parse main file alone to get its node IDs
+  const mainResult = await parseSingle(mainSource, activeVisualizer);
+
+  // Only include .ec files that are actually imported by the main file (directly or transitively),
+  // plus any spec files (yaml/yml/json). This prevents a syntax error in an unrelated .ec file
+  // from breaking the preview of the active file.
+  const reachableFiles = collectImportedEcFiles(mainFile, resolved);
+  const supportingFiles = filenames.filter(
+    (f) =>
+      f !== mainFile &&
+      (reachableFiles.has(f) ||
+        f.endsWith(".yml") ||
+        f.endsWith(".yaml") ||
+        f.endsWith(".json")),
+  );
+
+  if (supportingFiles.length === 0) {
+    return mainResult;
+  }
+
+  const concatOrder = [...supportingFiles, mainFile];
+  const { source: combinedSource } = stripAndConcatenate(resolved, concatOrder);
+  const fullResult = await parseSingle(combinedSource, activeVisualizer);
+
+  // Map main node IDs to their corresponding nodes in fullResult
+  const extractNodeKey = (id: string) => {
+    const match = id.match(/^([^:]+):([^@]+)/);
+    return match ? `${match[1]}:${match[2]}` : id;
+  };
+
+  const mainNodeKeys = new Set(
+    mainResult.nodes.map((n) => extractNodeKey(n.id)),
+  );
+
+  const filteredNodeIds = new Set(
+    fullResult.nodes
+      .filter((node) => mainNodeKeys.has(extractNodeKey(node.id)))
+      .map((node) => node.id),
+  );
+
+  // Iteratively expand to include all connected nodes
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const edge of fullResult.edges) {
+      if (
+        filteredNodeIds.has(edge.source) &&
+        !filteredNodeIds.has(edge.target)
+      ) {
+        filteredNodeIds.add(edge.target);
+        changed = true;
+      }
+      if (
+        filteredNodeIds.has(edge.target) &&
+        !filteredNodeIds.has(edge.source)
+      ) {
+        filteredNodeIds.add(edge.source);
+        changed = true;
+      }
+    }
+  }
+
+  return {
+    nodes: fullResult.nodes.filter((n) => filteredNodeIds.has(n.id)),
+    edges: fullResult.edges.filter(
+      (e) => filteredNodeIds.has(e.source) && filteredNodeIds.has(e.target),
+    ),
+    visualizers: fullResult.visualizers,
+    activeVisualizer: fullResult.activeVisualizer,
+    title: fullResult.title,
+    options: fullResult.options,
+  };
+}
diff --git a/packages/vscode-extension/src/preview-panel.ts b/packages/vscode-extension/src/preview-panel.ts
new file mode 100644
index 000000000..af6de5f8c
--- /dev/null
+++ b/packages/vscode-extension/src/preview-panel.ts
@@ -0,0 +1,198 @@
+import * as vscode from "vscode";
+import * as path from "node:path";
+
+const LOG_PREFIX = "[EventCatalog Preview]";
+
+export class PreviewPanelManager {
+  private panel: vscode.WebviewPanel | undefined;
+  private debounceTimer: ReturnType<typeof setTimeout> | undefined;
+  private context: vscode.ExtensionContext;
+  private cachedFileUris: vscode.Uri[] | null = null;
+  private fileWatcher: vscode.FileSystemWatcher | undefined;
+  private pendingDocument: vscode.TextDocument | undefined;
+  private webviewReady = false;
+
+  constructor(context: vscode.ExtensionContext) {
+    this.context = context;
+
+    // Watch for file creation/deletion to invalidate cached file list
+    this.fileWatcher =
+      vscode.workspace.createFileSystemWatcher("**/*.{ec,yaml,yml}");
+    this.fileWatcher.onDidCreate(() => {
+      this.cachedFileUris = null;
+    });
+    this.fileWatcher.onDidDelete(() => {
+      this.cachedFileUris = null;
+    });
+    context.subscriptions.push(this.fileWatcher);
+  }
+
+  showPreview(editor: vscode.TextEditor) {
+    if (this.panel) {
+      this.panel.reveal(vscode.ViewColumn.Beside);
+      this.onDocumentChanged(editor.document);
+    } else {
+      this.webviewReady = false;
+      this.panel = vscode.window.createWebviewPanel(
+        "eventcatalog.preview",
+        "EventCatalog Preview",
+        vscode.ViewColumn.Beside,
+        {
+          enableScripts: true,
+          localResourceRoots: [
+            vscode.Uri.joinPath(this.context.extensionUri, "dist"),
+          ],
+        },
+      );
+      // Queue the initial document for when webview is ready
+      this.pendingDocument = editor.document;
+
+      this.panel.webview.html = this.getHtml(this.panel.webview);
+
+      // Listen for ready signal from webview
+      this.panel.webview.onDidReceiveMessage((message) => {
+        if (message.type === "ready") {
+          this.webviewReady = true;
+          console.log(
+            LOG_PREFIX,
+            "Webview ready, pending:",
+            !!this.pendingDocument,
+          );
+          if (this.pendingDocument) {
+            this.onDocumentChanged(this.pendingDocument);
+            this.pendingDocument = undefined;
+          }
+        }
+      });
+
+      this.panel.onDidDispose(() => {
+        console.log(LOG_PREFIX, "Panel disposed");
+        this.panel = undefined;
+        this.webviewReady = false;
+        if (this.debounceTimer) {
+          clearTimeout(this.debounceTimer);
+          this.debounceTimer = undefined;
+        }
+      });
+    }
+  }
+
+  async onDocumentChanged(document: vscode.TextDocument) {
+    if (!this.panel) return;
+
+    // If webview isn't ready yet, just store the pending document
+    if (!this.webviewReady) {
+      this.pendingDocument = document;
+      return;
+    }
+
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+
+    this.debounceTimer = setTimeout(async () => {
+      try {
+        const files = await this.getWorkspaceFiles(document);
+        const parserPath = path.join(__dirname, "parser.js");
+        const { parseWorkspaceFiles } = require(parserPath);
+        const workspaceFolder = vscode.workspace.getWorkspaceFolder(
+          document.uri,
+        );
+        const basePath = workspaceFolder?.uri.fsPath;
+        const activeFile = vscode.workspace.asRelativePath(document.uri);
+        const graph = await parseWorkspaceFiles(
+          files,
+          undefined,
+          basePath,
+          activeFile,
+        );
+        console.log(
+          LOG_PREFIX,
+          `Parsed ${Object.keys(files).length} file(s) → ${graph.nodes?.length ?? 0} nodes, ${graph.edges?.length ?? 0} edges`,
+        );
+        this.panel?.webview.postMessage({ type: "update-graph", graph });
+      } catch (err) {
+        console.error(LOG_PREFIX, "Parse failed:", err);
+      }
+    }, 150);
+  }
+
+  private async getWorkspaceFiles(
+    activeDocument: vscode.TextDocument,
+  ): Promise<Record<string, string>> {
+    const files: Record<string, string> = {};
+
+    // Include the active document first (it's the "main" file)
+    const activePath = vscode.workspace.asRelativePath(activeDocument.uri);
+    files[activePath] = activeDocument.getText();
+
+    // Use cached file list, only scan workspace when cache is invalidated.
+    // Load all .ec files and all spec files (yaml/yml). Spec files may live
+    // in subdirectories separate from .ec files (e.g., ./asyncapi-files/spec.yml)
+    // so we cannot restrict to co-located directories. The parser only uses
+    // spec files that are actually referenced by imports.
+    if (!this.cachedFileUris) {
+      const [ecFiles, specFiles] = await Promise.all([
+        vscode.workspace.findFiles("**/*.ec", "**/node_modules/**"),
+        vscode.workspace.findFiles("**/*.{yaml,yml}", "**/node_modules/**"),
+      ]);
+
+      this.cachedFileUris = [...ecFiles, ...specFiles];
+      console.log(
+        LOG_PREFIX,
+        `Workspace scan: ${ecFiles.length} .ec file(s), ${specFiles.length} spec file(s)`,
+      );
+    }
+
+    for (const fileUri of this.cachedFileUris) {
+      const relativePath = vscode.workspace.asRelativePath(fileUri);
+      if (relativePath === activePath) continue;
+      const content = await vscode.workspace.fs.readFile(fileUri);
+      files[relativePath] = Buffer.from(content).toString("utf-8");
+    }
+
+    return files;
+  }
+
+  private getHtml(webview: vscode.Webview): string {
+    const scriptUri = webview.asWebviewUri(
+      vscode.Uri.joinPath(this.context.extensionUri, "dist", "webview.js"),
+    );
+    const styleUri = webview.asWebviewUri(
+      vscode.Uri.joinPath(this.context.extensionUri, "dist", "webview.css"),
+    );
+    const nonce = getNonce();
+
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="Content-Security-Policy"
+    content="default-src 'none'; style-src ${webview.cspSource} 'unsafe-inline'; script-src 'nonce-${nonce}';">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="stylesheet" href="${styleUri}">
+  <style>
+    html, body, #root {
+      width: 100%;
+      height: 100%;
+      margin: 0;
+      padding: 0;
+      overflow: hidden;
+    }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+  <script nonce="${nonce}" src="${scriptUri}"></script>
+</body>
+</html>`;
+  }
+}
+
+function getNonce(): string {
+  const chars =
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "";
+  for (let i = 0; i < 32; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
diff --git a/packages/vscode-extension/src/webview/index.tsx b/packages/vscode-extension/src/webview/index.tsx
new file mode 100644
index 000000000..f961266fd
--- /dev/null
+++ b/packages/vscode-extension/src/webview/index.tsx
@@ -0,0 +1,85 @@
+import React, { useState, useEffect } from "react";
+import { createRoot } from "react-dom/client";
+import { NodeGraph } from "@eventcatalog/visualiser";
+import type { DslGraph } from "@eventcatalog/visualiser";
+
+const vscode = acquireVsCodeApi();
+
+/** Sync data-theme on <html> to match VS Code's active color theme. */
+function syncTheme() {
+  const isDark =
+    document.body.classList.contains("vscode-dark") ||
+    document.body.classList.contains("vscode-high-contrast");
+  document.documentElement.setAttribute(
+    "data-theme",
+    isDark ? "dark" : "light",
+  );
+}
+
+function App() {
+  const [graph, setGraph] = useState<DslGraph>({ nodes: [], edges: [] });
+
+  useEffect(() => {
+    // Set initial theme and watch for VS Code theme changes
+    syncTheme();
+    const observer = new MutationObserver(syncTheme);
+    observer.observe(document.body, {
+      attributes: true,
+      attributeFilter: ["class"],
+    });
+
+    const handler = (event: MessageEvent) => {
+      const message = event.data;
+      if (message.type === "update-graph") {
+        setGraph(message.graph);
+      }
+    };
+    window.addEventListener("message", handler);
+
+    // Signal to extension that webview is ready to receive messages
+    vscode.postMessage({ type: "ready" });
+
+    return () => {
+      observer.disconnect();
+      window.removeEventListener("message", handler);
+    };
+  }, []);
+
+  if (graph.nodes.length === 0) {
+    const hasVisualizer = graph.visualizers && graph.visualizers.length > 0;
+    return (
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          height: "100%",
+          color: "#888",
+          fontFamily: "var(--vscode-font-family, sans-serif)",
+          fontSize: "14px",
+        }}
+      >
+        {hasVisualizer
+          ? "Add resources to your visualizer block to see the preview"
+          : "Add a visualizer block to your .ec file to see the preview"}
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ width: "100%", height: "100%" }}>
+      <div id="ec-preview-portal" style={{ width: "100%", height: "100%" }} />
+      <NodeGraph
+        id="ec-preview"
+        portalId="ec-preview-portal"
+        graph={graph}
+        mode="full"
+        zoomOnScroll={true}
+        showSearch={false}
+      />
+    </div>
+  );
+}
+
+const root = createRoot(document.getElementById("root")!);
+root.render(<App />);
diff --git a/packages/vscode-extension/src/webview/vscode.d.ts b/packages/vscode-extension/src/webview/vscode.d.ts
new file mode 100644
index 000000000..963632f34
--- /dev/null
+++ b/packages/vscode-extension/src/webview/vscode.d.ts
@@ -0,0 +1,5 @@
+declare function acquireVsCodeApi(): {
+  postMessage(message: unknown): void;
+  getState(): unknown;
+  setState(state: unknown): void;
+};
diff --git a/packages/vscode-extension/syntaxes/ec.tmLanguage.json b/packages/vscode-extension/syntaxes/ec.tmLanguage.json
new file mode 100644
index 000000000..2486ab47d
--- /dev/null
+++ b/packages/vscode-extension/syntaxes/ec.tmLanguage.json
@@ -0,0 +1,59 @@
+{
+  "name": "ec",
+  "scopeName": "source.ec",
+  "fileTypes": [".ec"],
+  "patterns": [
+    {
+      "include": "#comments"
+    },
+    {
+      "name": "keyword.control.ec",
+      "match": "\\b(access-mode|actor|address|and|animated|appendOnly|authoritative|avatar|cache|channel|channels|classification|color|command|commands|confidential|container|container-type|containers|contract|data-product|dataLake|dataWarehouse|database|default|delivery|deprecated|description|diagram|domain|draft|email|enum|event|events|examples|external-system|externalSaaS|false|flow|focus-mode|from|hidden|icon|import|input|internal|label|legend|member|message|ms-teams|name|objectStore|other|output|owner|parameter|path|post-it|protocol|public|pull|push|push-pull|queries|query|read|readWrite|reads-from|receives|regulated|residency|retention|role|route|schema|search|searchIndex|sends|service|services|slack|style|subdomain|summary|team|technology|title|to|toolbar|true|type|url|user|version|visible|visualizer|when|write|writes-to)\\b"
+    },
+    {
+      "name": "string.quoted.double.ec",
+      "begin": "\"",
+      "end": "\"",
+      "patterns": [
+        {
+          "include": "#string-character-escape"
+        }
+      ]
+    }
+  ],
+  "repository": {
+    "comments": {
+      "patterns": [
+        {
+          "begin": "//",
+          "beginCaptures": {
+            "1": {
+              "name": "punctuation.whitespace.comment.leading.ec"
+            }
+          },
+          "end": "(?=$)",
+          "name": "comment.line.ec"
+        },
+        {
+          "name": "comment.block.ec",
+          "begin": "/\\*",
+          "beginCaptures": {
+            "0": {
+              "name": "punctuation.definition.comment.ec"
+            }
+          },
+          "end": "\\*/",
+          "endCaptures": {
+            "0": {
+              "name": "punctuation.definition.comment.ec"
+            }
+          }
+        }
+      ]
+    },
+    "string-character-escape": {
+      "name": "constant.character.escape.ec",
+      "match": "\\\\(x[0-9A-Fa-f]{2}|u[0-9A-Fa-f]{4}|u\\{[0-9A-Fa-f]+\\}|[0-2][0-7]{0,2}|3[0-6][0-7]?|37[0-7]?|[4-7][0-7]?|.|$)"
+    }
+  }
+}
diff --git a/packages/vscode-extension/test/parser.test.ts b/packages/vscode-extension/test/parser.test.ts
new file mode 100644
index 000000000..eb3353bd3
--- /dev/null
+++ b/packages/vscode-extension/test/parser.test.ts
@@ -0,0 +1,380 @@
+import { describe, it, expect } from "vitest";
+import { parseWorkspaceFiles } from "../dist/parser.js";
+
+const asyncapiSpec = `
+asyncapi: 3.0.0
+info:
+  title: Orders API
+  version: 1.0.0
+components:
+  messages:
+    OrderCreated:
+      summary: Fired when a new order is placed
+`;
+
+const asyncapiSpecWithOps = `
+asyncapi: 3.0.0
+info:
+  title: Order Service
+  version: 2.0.0
+  description: This service handles order events.
+servers:
+  production:
+    host: kafka.example.com:9092
+    protocol: kafka
+channels:
+  orderCreated:
+    address: orders.created
+    summary: Topic for new orders
+    messages:
+      OrderCreated:
+        $ref: '#/components/messages/OrderCreated'
+operations:
+  sendOrderCreated:
+    action: send
+    channel:
+      $ref: '#/channels/orderCreated'
+    summary: Publishes when a new order is placed
+components:
+  messages:
+    OrderCreated:
+      summary: Fired when a new order is placed
+`;
+
+describe("parseWorkspaceFiles", () => {
+  it("parses a single .ec file", async () => {
+    const files = {
+      "main.ec": `visualizer main {
+  name "Test"
+  service Foo { version 1.0.0 }
+}`,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    expect(result.nodes).toHaveLength(1);
+    expect(result.nodes[0].type).toBe("service");
+  });
+
+  it("broken sibling .ec file does not break the active file preview", async () => {
+    const files = {
+      "main.ec": `visualizer main {
+  name "Test"
+  service Foo { version 1.0.0 }
+}`,
+      "broken.ec": `this is not valid ec syntax {{{`,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    expect(result.nodes).toHaveLength(1);
+    expect(result.nodes[0].label).toBe("Foo");
+  });
+
+  it("includes imported .ec files in the parse", async () => {
+    const files = {
+      "main.ec": `import { Bar } from "./other.ec"
+visualizer main {
+  name "Test"
+  service Foo {
+    version 1.0.0
+    sends { event Bar }
+  }
+}`,
+      "other.ec": `event Bar { version 1.0.0 }`,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    expect(result.nodes.length).toBeGreaterThanOrEqual(2);
+    const types = result.nodes.map((n: any) => n.type);
+    expect(types).toContain("service");
+    expect(types).toContain("event");
+  });
+
+  it("excludes unrelated .ec files that are not imported", async () => {
+    const files = {
+      "main.ec": `visualizer main {
+  name "Test"
+  service Svc { version 1.0.0 }
+}`,
+      "unrelated.ec": `service Other { version 2.0.0 }`,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    expect(result.nodes).toHaveLength(1);
+    expect(result.nodes[0].label).toBe("Svc");
+  });
+
+  it("multiple broken .ec files do not affect the active file", async () => {
+    const files = {
+      "main.ec": `visualizer main {
+  name "Test"
+  service A { version 1.0.0 }
+  service B { version 2.0.0 }
+}`,
+      "broken1.ec": `totally broken {{{ `,
+      "broken2.ec": `also broken !!!`,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    expect(result.nodes).toHaveLength(2);
+  });
+
+  it("resolves spec imports from nested folders", async () => {
+    const files = {
+      "main.ec": `import events { OrderCreated } from "./specs/api.yml"
+visualizer main {
+  name "Test"
+  service Foo {
+    version 1.0.0
+    sends { event OrderCreated }
+  }
+}`,
+      "specs/api.yml": asyncapiSpec,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    expect(result.nodes.length).toBeGreaterThanOrEqual(2);
+    const types = result.nodes.map((n: any) => n.type);
+    expect(types).toContain("service");
+    expect(types).toContain("event");
+  });
+
+  it("resolves spec imports from nested .ec file to parent directory", async () => {
+    const files = {
+      "sub/main.ec": `import events { OrderCreated } from "../api.yml"
+visualizer main {
+  name "Test"
+  service Foo {
+    version 1.0.0
+    sends { event OrderCreated }
+  }
+}`,
+      "api.yml": asyncapiSpec,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "sub/main.ec",
+    );
+    expect(result.nodes.length).toBeGreaterThanOrEqual(2);
+    const types = result.nodes.map((n: any) => n.type);
+    expect(types).toContain("service");
+    expect(types).toContain("event");
+  });
+
+  it("follows transitive .ec imports", async () => {
+    const files = {
+      "main.ec": `import { Baz } from "./mid.ec"
+visualizer main {
+  name "Test"
+  service Foo {
+    version 1.0.0
+    sends { event Baz }
+  }
+}`,
+      "mid.ec": `import { Baz } from "./leaf.ec"`,
+      "leaf.ec": `event Baz { version 1.0.0 }`,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    expect(result.nodes.length).toBeGreaterThanOrEqual(2);
+    const types = result.nodes.map((n: any) => n.type);
+    expect(types).toContain("service");
+    expect(types).toContain("event");
+  });
+
+  it("shows empty state for visualizer with no resources", async () => {
+    const files = {
+      "main.ec": `visualizer main { name "Empty" }`,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    expect(result.nodes).toHaveLength(0);
+    expect(result.visualizers).toContain("main");
+  });
+
+  it("resolves service import from nested folder", async () => {
+    const files = {
+      "main.ec": `import Service from "./asyncapi-files/one.yml"
+visualizer main {
+  name "View Name"
+  service Service
+}`,
+      "asyncapi-files/one.yml": asyncapiSpecWithOps,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    const serviceNode = result.nodes.find((n: any) => n.type === "service");
+    expect(serviceNode).toBeDefined();
+    expect(serviceNode!.label).toBe("Service");
+    // The service should have its events resolved with summaries
+    const eventNode = result.nodes.find((n: any) => n.type === "event");
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.metadata?.summary).toBe(
+      "Fired when a new order is placed",
+    );
+  });
+
+  it("event import from nested folder includes summary and version", async () => {
+    // Bug: importing from "./asyncapi-files/one.yml" shows the event but without
+    // summary/version, while importing from "./one.yml" shows them correctly.
+    const files = {
+      "main.ec": `import events { OrderCancelled } from "./asyncapi-files/one.yml"
+visualizer main {
+  name "View Name"
+  event OrderCancelled
+}`,
+      "asyncapi-files/one.yml": `
+asyncapi: 3.0.0
+info:
+  title: Orders API
+  version: 1.0.0
+components:
+  messages:
+    OrderCancelled:
+      summary: Fired when an order is cancelled
+`,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    const eventNode = result.nodes.find((n: any) => n.type === "event");
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.label).toBe("OrderCancelled");
+    expect(eventNode!.metadata?.summary).toBe(
+      "Fired when an order is cancelled",
+    );
+    expect(eventNode!.metadata?.version).toBe("1.0.0");
+  });
+
+  it("event import from same directory includes summary and version", async () => {
+    // Control test: same spec but from same directory — should work
+    const files = {
+      "main.ec": `import events { OrderCancelled } from "./one.yml"
+visualizer main {
+  name "View Name"
+  event OrderCancelled
+}`,
+      "one.yml": `
+asyncapi: 3.0.0
+info:
+  title: Orders API
+  version: 1.0.0
+components:
+  messages:
+    OrderCancelled:
+      summary: Fired when an order is cancelled
+`,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    const eventNode = result.nodes.find((n: any) => n.type === "event");
+    expect(eventNode).toBeDefined();
+    expect(eventNode!.label).toBe("OrderCancelled");
+    expect(eventNode!.metadata?.summary).toBe(
+      "Fired when an order is cancelled",
+    );
+    expect(eventNode!.metadata?.version).toBe("1.0.0");
+  });
+
+  it("resolves multi-level nested spec imports", async () => {
+    const files = {
+      "main.ec": `import commands { createQuote } from "./services/pricing/pricing-openapi.yml"
+import PricingAPI from "./services/pricing/pricing-openapi.yml"
+visualizer main {
+  name "Test"
+  service PricingAPI
+}`,
+      "services/pricing/pricing-openapi.yml": asyncapiSpecWithOps,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    const serviceNode = result.nodes.find((n: any) => n.type === "service");
+    expect(serviceNode).toBeDefined();
+    expect(serviceNode!.label).toBe("PricingAPI");
+  });
+
+  it("resolves .ec file imports from nested folders", async () => {
+    const files = {
+      "main.ec": `import { User } from "./actors/actors.ec"
+visualizer main {
+  name "Test"
+  actor User
+}`,
+      "actors/actors.ec": `actor User {
+  name "The User"
+  summary "User persona"
+}`,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    const actorNode = result.nodes.find((n: any) => n.type === "actor");
+    expect(actorNode).toBeDefined();
+    expect(actorNode!.label).toBe("User");
+  });
+
+  it("shows empty state when no visualizer block exists", async () => {
+    const files = {
+      "main.ec": `service Foo { version 1.0.0 }`,
+    };
+    const result = await parseWorkspaceFiles(
+      files,
+      undefined,
+      undefined,
+      "main.ec",
+    );
+    expect(result.nodes).toHaveLength(0);
+    expect(result.empty).toBe(true);
+  });
+});
diff --git a/packages/vscode-extension/tsconfig.json b/packages/vscode-extension/tsconfig.json
new file mode 100644
index 000000000..41d8bc866
--- /dev/null
+++ b/packages/vscode-extension/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": false,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7e9b9b77c..0fcc12251 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4,67 +4,162 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+overrides:
+  prismjs: '>=1.30.0'
+
 importers:
 
   .:
+    devDependencies:
+      '@changesets/cli':
+        specifier: ^2.27.5
+        version: 2.29.7(@types/node@25.0.3)
+      prettier-plugin-astro:
+        specifier: ^0.14.1
+        version: 0.14.1
+      turbo:
+        specifier: ^2.8.4
+        version: 2.8.4
+
+  packages/breaking-changes:
+    devDependencies:
+      '@types/node':
+        specifier: ^20.14.10
+        version: 20.19.19
+      prettier:
+        specifier: ^3.3.3
+        version: 3.6.2
+      tsup:
+        specifier: ^8.1.0
+        version: 8.5.0(jiti@2.7.0)(postcss@8.5.15)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
+      typescript:
+        specifier: ^5.5.3
+        version: 5.9.3
+      vitest:
+        specifier: ^3.2.4
+        version: 3.2.4(@types/debug@4.1.12)(@types/node@20.19.19)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.15))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  packages/cli:
+    dependencies:
+      '@eventcatalog/breaking-changes':
+        specifier: workspace:*
+        version: link:../breaking-changes
+      '@eventcatalog/language-server':
+        specifier: workspace:*
+        version: link:../language-server
+      '@eventcatalog/license':
+        specifier: ^0.0.7
+        version: 0.0.7
+      '@eventcatalog/sdk':
+        specifier: workspace:*
+        version: link:../sdk
+      commander:
+        specifier: ^12.0.0
+        version: 12.1.0
+      dotenv:
+        specifier: ^16.5.0
+        version: 16.6.1
+      gray-matter:
+        specifier: ^4.0.3
+        version: 4.0.3
+      js-yaml:
+        specifier: ^4.1.1
+        version: 4.1.1
+      langium:
+        specifier: ^3.3.1
+        version: 3.5.0
+      open:
+        specifier: ^11.0.0
+        version: 11.0.0
+      semver:
+        specifier: ^7.7.2
+        version: 7.7.4
+    devDependencies:
+      '@types/js-yaml':
+        specifier: ^4.0.9
+        version: 4.0.9
+      '@types/node':
+        specifier: ^20.14.10
+        version: 20.19.19
+      prettier:
+        specifier: ^3.3.3
+        version: 3.6.2
+      tsup:
+        specifier: ^8.1.0
+        version: 8.5.0(jiti@2.7.0)(postcss@8.5.15)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
+      typescript:
+        specifier: ^5.5.3
+        version: 5.9.3
+      vitest:
+        specifier: ^3.2.4
+        version: 3.2.4(@types/debug@4.1.12)(@types/node@20.19.19)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.15))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  packages/connectors:
+    dependencies:
+      simple-git:
+        specifier: ^3.36.0
+        version: 3.36.0
+    devDependencies:
+      '@types/node':
+        specifier: ^20.14.10
+        version: 20.19.19
+      prettier:
+        specifier: ^3.3.3
+        version: 3.6.2
+      tsup:
+        specifier: ^8.1.0
+        version: 8.5.0(jiti@2.7.0)(postcss@8.5.15)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
+      typescript:
+        specifier: ^5.5.3
+        version: 5.9.3
+      vitest:
+        specifier: ^3.2.4
+        version: 3.2.4(@types/debug@4.1.12)(@types/node@20.19.19)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.15))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  packages/core:
     dependencies:
-      '@ai-sdk/anthropic':
-        specifier: ^2.0.23
-        version: 2.0.25(zod@3.25.76)
-      '@ai-sdk/google':
-        specifier: ^2.0.17
-        version: 2.0.18(zod@3.25.76)
-      '@ai-sdk/openai':
-        specifier: ^2.0.42
-        version: 2.0.45(zod@3.25.76)
       '@ai-sdk/react':
-        specifier: ^2.0.60
-        version: 2.0.62(react@18.3.1)(zod@3.25.76)
+        specifier: ^3.0.17
+        version: 3.0.17(react@18.3.1)(zod@4.3.6)
       '@astrojs/markdown-remark':
-        specifier: ^6.3.9
-        version: 6.3.9
+        specifier: ^7.2.0
+        version: 7.2.0
       '@astrojs/mdx':
-        specifier: ^4.3.12
-        version: 4.3.12(astro@5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1))
+        specifier: ^7.0.0
+        version: 7.0.0(@astrojs/markdown-satteri@0.3.2)(astro@7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
       '@astrojs/node':
-        specifier: ^9.5.1
-        version: 9.5.1(astro@5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1))
+        specifier: ^11.0.0
+        version: 11.0.0(astro@7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
       '@astrojs/react':
-        specifier: ^4.4.2
-        version: 4.4.2(@types/node@20.19.19)(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(jiti@1.21.7)(lightningcss@1.29.3)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(terser@5.39.0)(yaml@2.8.1)
+        specifier: ^6.0.0
+        version: 6.0.0(@types/node@22.19.21)(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(esbuild@0.28.1)(jiti@2.7.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
       '@astrojs/rss':
-        specifier: ^4.0.14
-        version: 4.0.14
-      '@astrojs/tailwind':
-        specifier: ^6.0.2
-        version: 6.0.2(astro@5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1))(tailwindcss@3.4.18(yaml@2.8.1))
+        specifier: ^4.0.18
+        version: 4.0.18
       '@asyncapi/avro-schema-parser':
         specifier: 3.0.24
         version: 3.0.24
       '@asyncapi/parser':
-        specifier: 3.4.0
-        version: 3.4.0
+        specifier: ^3.6.0
+        version: 3.6.0
       '@asyncapi/react-component':
-        specifier: 2.4.3
-        version: 2.4.3(postcss@8.5.6)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        specifier: 3.1.0
+        version: 3.1.0(postcss@8.5.15)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@auth/core':
         specifier: ^0.37.4
         version: 0.37.4
-      '@eventcatalog/generator-ai':
-        specifier: ^1.1.0
-        version: 1.2.0(@langchain/core@0.3.78(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76)))(@opentelemetry/api@1.9.0)(@types/node@20.19.19)(axios@1.12.2)(ws@8.18.3)(zod@3.25.76)
       '@eventcatalog/license':
         specifier: ^0.0.7
         version: 0.0.7
       '@eventcatalog/linter':
-        specifier: ^0.0.2
-        version: 0.0.2
+        specifier: workspace:*
+        version: link:../linter
       '@eventcatalog/sdk':
-        specifier: ^2.9.2
-        version: 2.9.2(@types/node@20.19.19)
-      '@eventcatalog/visualizer':
-        specifier: ^0.0.6
-        version: 0.0.6(@types/react@18.3.26)(immer@9.0.21)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        specifier: workspace:*
+        version: link:../sdk
+      '@eventcatalog/visualiser':
+        specifier: workspace:^
+        version: link:../visualiser
       '@fontsource/inter':
         specifier: ^5.2.5
         version: 5.2.8
@@ -79,82 +174,82 @@ importers:
         version: 1.2.9
       '@mermaid-js/layout-elk':
         specifier: ^0.2.0
-        version: 0.2.0(mermaid@11.12.0)
+        version: 0.2.0(mermaid@11.12.3)
+      '@modelcontextprotocol/sdk':
+        specifier: ^1.26.0
+        version: 1.26.0(@cfworker/json-schema@4.1.1)(zod@4.3.6)
+      '@nanostores/react':
+        specifier: ^1.0.0
+        version: 1.0.0(nanostores@1.1.0)(react@18.3.1)
       '@parcel/watcher':
         specifier: ^2.4.1
         version: 2.5.1
       '@radix-ui/react-context-menu':
         specifier: ^2.2.6
-        version: 2.2.16(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 2.2.16(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@radix-ui/react-dialog':
         specifier: ^1.1.6
-        version: 1.1.15(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@radix-ui/react-dropdown-menu':
         specifier: ^2.1.12
-        version: 2.1.16(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-popover':
+        specifier: ^1.1.15
+        version: 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@radix-ui/react-tooltip':
         specifier: ^1.1.8
-        version: 1.2.8(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@scalar/api-reference-react':
-        specifier: ^0.4.37
-        version: 0.4.42(@hyperjump/browser@1.3.1)(axios@1.12.2)(react@18.3.1)(tailwindcss@3.4.18(yaml@2.8.1))(typescript@5.9.3)
+        specifier: ^0.9.36
+        version: 0.9.36(axios@1.15.2)(react@18.3.1)(tailwindcss@4.3.1)(typescript@5.9.3)(zod@4.3.6)
       '@tailwindcss/typography':
-        specifier: ^0.5.13
-        version: 0.5.19(tailwindcss@3.4.18(yaml@2.8.1))
-      '@tanstack/react-query':
-        specifier: ^5.74.3
-        version: 5.90.2(react@18.3.1)
+        specifier: ^0.5.16
+        version: 0.5.19(tailwindcss@4.3.1)
+      '@tailwindcss/vite':
+        specifier: ^4.3.1
+        version: 4.3.1(vite@8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
       '@tanstack/react-table':
         specifier: ^8.17.3
         version: 8.21.3(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@xyflow/react':
         specifier: ^12.3.6
-        version: 12.8.6(@types/react@18.3.26)(immer@9.0.21)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 12.8.6(@types/react@19.2.13)(immer@9.0.21)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       ai:
-        specifier: ^5.0.60
-        version: 5.0.62(zod@3.25.76)
+        specifier: ^6.0.17
+        version: 6.0.17(zod@4.3.6)
       astro:
-        specifier: ^5.16.0
-        version: 5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1)
+        specifier: ^7.0.3
+        version: 7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
       astro-compress:
-        specifier: ^2.3.8
-        version: 2.3.8(@types/node@20.19.19)(jiti@1.21.7)(rollup@4.52.4)(typescript@5.9.3)(yaml@2.8.1)
+        specifier: ^2.4.0
+        version: 2.4.0(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(tsx@4.21.0)(yaml@2.9.0)
       astro-expressive-code:
-        specifier: ^0.41.3
-        version: 0.41.3(astro@5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1))
+        specifier: ^0.44.0
+        version: 0.44.0(astro@7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
       astro-seo:
         specifier: ^0.8.4
         version: 0.8.4(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)
       auth-astro:
         specifier: ^4.2.0
-        version: 4.2.0(@auth/core@0.37.4)(astro@5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1))
-      axios:
-        specifier: ^1.7.7
-        version: 1.12.2
+        version: 4.2.0(@auth/core@0.37.4)(astro@7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
       boxen:
         specifier: ^8.0.1
         version: 8.0.1
       commander:
         specifier: ^12.1.0
         version: 12.1.0
-      concurrently:
-        specifier: ^8.2.2
-        version: 8.2.2
       cross-env:
         specifier: ^7.0.3
         version: 7.0.3
       dagre:
         specifier: ^0.8.5
         version: 0.8.5
-      date-fns:
-        specifier: ^4.1.0
-        version: 4.1.0
       diff:
-        specifier: ^7.0.0
-        version: 7.0.0
+        specifier: ^8.0.3
+        version: 8.0.3
       diff2html:
-        specifier: ^3.4.48
-        version: 3.4.52
+        specifier: ^3.4.56
+        version: 3.4.56
       dotenv:
         specifier: ^16.5.0
         version: 16.6.1
@@ -162,20 +257,23 @@ importers:
         specifier: ^0.10.0
         version: 0.10.2
       glob:
-        specifier: ^10.5.0
-        version: 10.5.0
+        specifier: ^13.0.6
+        version: 13.0.6
       gray-matter:
         specifier: ^4.0.3
         version: 4.0.3
+      hono:
+        specifier: 4.12.25
+        version: 4.12.25
       html-to-image:
         specifier: ^1.11.11
         version: 1.11.13
       js-yaml:
-        specifier: ^4.1.0
-        version: 4.1.0
-      jsonpath:
-        specifier: ^1.1.1
-        version: 1.1.1
+        specifier: ^4.2.0
+        version: 4.2.0
+      jsonpath-plus:
+        specifier: ^10.4.0
+        version: 10.4.0
       jsonwebtoken:
         specifier: ^9.0.2
         version: 9.0.2
@@ -191,15 +289,30 @@ importers:
       marked:
         specifier: ^15.0.6
         version: 15.0.12
+      mdast-util-find-and-replace:
+        specifier: ^3.0.2
+        version: 3.0.2
       mermaid:
-        specifier: ^11.4.1
-        version: 11.12.0
+        specifier: ^11.12.3
+        version: 11.12.3
+      minisearch:
+        specifier: ^7.2.0
+        version: 7.2.0
+      nanostores:
+        specifier: ^1.1.0
+        version: 1.1.0
       pagefind:
-        specifier: ^1.3.0
-        version: 1.4.0
+        specifier: ^1.5.2
+        version: 1.5.2
       pako:
         specifier: ^2.1.0
         version: 2.1.0
+      picocolors:
+        specifier: ^1.1.1
+        version: 1.1.1
+      picomatch:
+        specifier: ^4.0.4
+        version: 4.0.4
       react:
         specifier: ^18.3.1
         version: 18.3.1
@@ -208,16 +321,19 @@ importers:
         version: 18.3.1(react@18.3.1)
       react-markdown:
         specifier: ^10.1.0
-        version: 10.1.0(@types/react@18.3.26)(react@18.3.1)
+        version: 10.1.0(@types/react@19.2.13)(react@18.3.1)
       react-syntax-highlighter:
-        specifier: ^15.6.1
+        specifier: ^15.6.6
         version: 15.6.6(react@18.3.1)
+      recast:
+        specifier: ^0.23.11
+        version: 0.23.11
       rehype-autolink-headings:
         specifier: ^7.1.0
         version: 7.1.0
       rehype-expressive-code:
-        specifier: ^0.41.3
-        version: 0.41.3
+        specifier: ^0.44.0
+        version: 0.44.0
       rehype-slug:
         specifier: ^6.0.0
         version: 6.0.0
@@ -228,20 +344,29 @@ importers:
         specifier: ^3.0.0
         version: 3.0.1
       remark-gfm:
-        specifier: ^3.0.1
-        version: 3.0.1
+        specifier: ^4.0.1
+        version: 4.0.1
       rimraf:
-        specifier: ^5.0.7
-        version: 5.0.10
+        specifier: ^6.1.3
+        version: 6.1.3
       semver:
         specifier: 7.6.3
         version: 7.6.3
       shelljs:
-        specifier: ^0.8.5
-        version: 0.8.5
+        specifier: ^0.9.0
+        version: 0.9.0
+      sonner:
+        specifier: ^2.0.7
+        version: 2.0.7(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      sql.js:
+        specifier: ^1.12.0
+        version: 1.14.1
+      svg-pan-zoom:
+        specifier: ^3.6.2
+        version: 3.6.2
       tailwindcss:
-        specifier: ^3.4.3
-        version: 3.4.18(yaml@2.8.1)
+        specifier: ^4.3.1
+        version: 4.3.1
       typescript:
         specifier: ^5.4.5
         version: 5.9.3
@@ -254,16 +379,13 @@ importers:
       uuid:
         specifier: ^10.0.0
         version: 10.0.0
+      zod:
+        specifier: ^4.3.6
+        version: 4.3.6
     devDependencies:
       '@astrojs/check':
-        specifier: ^0.9.5
-        version: 0.9.5(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)
-      '@changesets/cli':
-        specifier: ^2.27.5
-        version: 2.29.7(@types/node@20.19.19)
-      '@playwright/test':
-        specifier: ^1.48.1
-        version: 1.56.0
+        specifier: ^0.9.9
+        version: 0.9.9(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)
       '@types/dagre':
         specifier: ^0.7.52
         version: 0.7.53
@@ -273,9 +395,6 @@ importers:
       '@types/js-yaml':
         specifier: ^4.0.9
         version: 4.0.9
-      '@types/jsonpath':
-        specifier: ^0.2.4
-        version: 0.2.4
       '@types/jsonwebtoken':
         specifier: ^9.0.10
         version: 9.0.10
@@ -286,17 +405,17 @@ importers:
         specifier: 4.6.9
         version: 4.6.9
       '@types/node':
-        specifier: ^20.14.2
-        version: 20.19.19
+        specifier: ^22.12.0
+        version: 22.19.21
       '@types/pako':
         specifier: ^2.0.3
         version: 2.0.4
       '@types/react':
-        specifier: ^18.3.3
-        version: 18.3.26
+        specifier: ^19.2.13
+        version: 19.2.13
       '@types/react-dom':
-        specifier: ^18.3.0
-        version: 18.3.7(@types/react@18.3.26)
+        specifier: ^19.2.3
+        version: 19.2.3(@types/react@19.2.13)
       '@types/react-syntax-highlighter':
         specifier: ^15.5.13
         version: 15.5.13
@@ -320,102 +439,607 @@ importers:
         version: 0.14.1
       tsup:
         specifier: ^8.1.0
-        version: 8.5.0(jiti@1.21.7)(postcss@8.5.6)(typescript@5.9.3)(yaml@2.8.1)
+        version: 8.5.0(jiti@2.7.0)(postcss@8.5.15)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
       vite:
-        specifier: ^7.1.7
-        version: 7.1.9(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1)
+        specifier: ^8.1.0
+        version: 8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
       vite-tsconfig-paths:
         specifier: ^4.3.2
-        version: 4.3.2(typescript@5.9.3)(vite@7.1.9(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1))
+        version: 4.3.2(typescript@5.9.3)(vite@8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
       vitest:
-        specifier: 2.1.9
-        version: 2.1.9(@types/node@20.19.19)(jsdom@27.0.0(postcss@8.5.6))(lightningcss@1.29.3)(terser@5.39.0)
+        specifier: ^4.0.18
+        version: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@22.19.21)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.15))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  packages/create-eventcatalog:
+    dependencies:
+      uuid:
+        specifier: ^10.0.0
+        version: 10.0.0
+    devDependencies:
+      '@types/async-retry':
+        specifier: 1.4.2
+        version: 1.4.2
+      '@types/ci-info':
+        specifier: 2.0.0
+        version: 2.0.0
+      '@types/cross-spawn':
+        specifier: 6.0.0
+        version: 6.0.0
+      '@types/node':
+        specifier: ^20.14.10
+        version: 20.19.19
+      '@types/prompts':
+        specifier: 2.0.1
+        version: 2.0.1
+      '@types/rimraf':
+        specifier: 3.0.0
+        version: 3.0.0
+      '@types/uuid':
+        specifier: ^10.0.0
+        version: 10.0.0
+      '@types/validate-npm-package-name':
+        specifier: 3.0.0
+        version: 3.0.0
+      '@vercel/ncc':
+        specifier: 0.34.0
+        version: 0.34.0
+      async-retry:
+        specifier: 1.3.1
+        version: 1.3.1
+      chalk:
+        specifier: 2.4.2
+        version: 2.4.2
+      commander:
+        specifier: 2.20.0
+        version: 2.20.0
+      cpy:
+        specifier: ^11.0.0
+        version: 11.1.0
+      cross-spawn:
+        specifier: 6.0.6
+        version: 6.0.6
+      fast-glob:
+        specifier: ^3.3.2
+        version: 3.3.3
+      ora:
+        specifier: ^5.4.1
+        version: 5.4.1
+      prettier:
+        specifier: ^3.3.3
+        version: 3.6.2
+      prompts:
+        specifier: 2.1.0
+        version: 2.1.0
+      rimraf:
+        specifier: ^5.0.7
+        version: 5.0.10
+      tsup:
+        specifier: ^8.1.0
+        version: 8.5.0(jiti@2.7.0)(postcss@8.5.15)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
+      typescript:
+        specifier: ^5.4.5
+        version: 5.9.3
+      update-check:
+        specifier: 1.5.4
+        version: 1.5.4
+      validate-npm-package-name:
+        specifier: 3.0.0
+        version: 3.0.0
+
+  packages/language-server:
+    dependencies:
+      '@eventcatalog/sdk':
+        specifier: workspace:*
+        version: link:../sdk
+      js-yaml:
+        specifier: ^4.1.1
+        version: 4.1.1
+      langium:
+        specifier: ^3.3.1
+        version: 3.3.1
+      semver:
+        specifier: ^7.7.4
+        version: 7.7.4
+      vscode-languageclient:
+        specifier: ^9.0.1
+        version: 9.0.1
+      vscode-languageserver:
+        specifier: ^9.0.1
+        version: 9.0.1
+      vscode-languageserver-textdocument:
+        specifier: ^1.0.12
+        version: 1.0.12
+      vscode-uri:
+        specifier: ^3.0.8
+        version: 3.1.0
+    devDependencies:
+      '@astrojs/starlight':
+        specifier: ^0.38.0
+        version: 0.38.0(astro@6.0.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0))
+      '@types/js-yaml':
+        specifier: ^4.0.9
+        version: 4.0.9
+      '@types/semver':
+        specifier: ^7.7.1
+        version: 7.7.1
+      astro:
+        specifier: ^6.0.2
+        version: 6.0.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
+      langium-cli:
+        specifier: ^3.3.1
+        version: 3.5.2
+      prettier:
+        specifier: ^3.2.5
+        version: 3.6.2
+      typescript:
+        specifier: ^5.7.0
+        version: 5.9.3
+      vitest:
+        specifier: ^3.0.0
+        version: 3.2.4(@types/debug@4.1.12)(@types/node@25.0.3)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.15))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  packages/linter:
+    dependencies:
+      '@eventcatalog/sdk':
+        specifier: workspace:*
+        version: link:../sdk
+      '@types/semver':
+        specifier: ^7.7.0
+        version: 7.7.1
+      chalk:
+        specifier: ^5.6.2
+        version: 5.6.2
+      commander:
+        specifier: ^11.1.0
+        version: 11.1.0
+      fast-glob:
+        specifier: ^3.3.2
+        version: 3.3.3
+      gray-matter:
+        specifier: ^4.0.3
+        version: 4.0.3
+      ora:
+        specifier: ^8.0.1
+        version: 8.2.0
+      semver:
+        specifier: ^7.7.2
+        version: 7.7.3
+      zod:
+        specifier: ^3.25.76
+        version: 3.25.76
+    devDependencies:
+      '@types/node':
+        specifier: ^20.10.5
+        version: 20.19.19
+      prettier:
+        specifier: ^3.3.3
+        version: 3.6.2
+      tsup:
+        specifier: ^8.1.0
+        version: 8.5.0(jiti@2.7.0)(postcss@8.5.15)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
+      typescript:
+        specifier: ^5.3.3
+        version: 5.9.3
+      vitest:
+        specifier: ^3.2.4
+        version: 3.2.4(@types/debug@4.1.12)(@types/node@20.19.19)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.15))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  packages/playground:
+    dependencies:
+      '@eventcatalog/language-server':
+        specifier: workspace:*
+        version: link:../language-server
+      '@eventcatalog/visualiser':
+        specifier: workspace:*
+        version: link:../visualiser
+      '@monaco-editor/react':
+        specifier: ^4.7.0
+        version: 4.7.0(monaco-editor@0.55.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@nanostores/persistent':
+        specifier: ^1.3.3
+        version: 1.3.3(nanostores@1.1.0)
+      '@nanostores/react':
+        specifier: ^1.0.0
+        version: 1.0.0(nanostores@1.1.0)(react@19.2.4)
+      '@xyflow/react':
+        specifier: ^12.4.0
+        version: 12.8.6(@types/react@19.2.13)(immer@9.0.21)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      cmdk:
+        specifier: ^1.1.1
+        version: 1.1.1(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      langium:
+        specifier: ^3.3.1
+        version: 3.5.0
+      lucide-react:
+        specifier: ^0.563.0
+        version: 0.563.0(react@19.2.4)
+      nanostores:
+        specifier: ^1.1.0
+        version: 1.1.0
+      react:
+        specifier: ^19.0.0
+        version: 19.2.4
+      react-dom:
+        specifier: ^19.0.0
+        version: 19.2.4(react@19.2.4)
+      react-router-dom:
+        specifier: ^7.13.1
+        version: 7.13.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+    devDependencies:
+      '@tailwindcss/postcss':
+        specifier: ^4.1.18
+        version: 4.1.18
+      '@types/react':
+        specifier: ^19.0.0
+        version: 19.2.13
+      '@types/react-dom':
+        specifier: ^19.0.0
+        version: 19.2.3(@types/react@19.2.13)
+      '@vitejs/plugin-react':
+        specifier: ^4.3.0
+        version: 4.7.0(vite@6.4.1(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
+      postcss:
+        specifier: ^8.5.6
+        version: 8.5.6
+      react-scan:
+        specifier: ^0.4.3
+        version: 0.4.3(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react-router-dom@7.13.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-router@7.13.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react@19.2.4)(rollup@4.52.4)
+      tailwindcss:
+        specifier: ^4.1.18
+        version: 4.1.18
+      typescript:
+        specifier: ^5.7.0
+        version: 5.9.3
+      vite:
+        specifier: ^6.1.0
+        version: 6.4.1(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  packages/sdk:
+    dependencies:
+      fs-extra:
+        specifier: ^11.3.2
+        version: 11.3.2
+      glob:
+        specifier: ^13.0.6
+        version: 13.0.6
+      gray-matter:
+        specifier: ^4.0.3
+        version: 4.0.3
+      proper-lockfile:
+        specifier: ^4.1.2
+        version: 4.1.2
+      semver:
+        specifier: 7.7.3
+        version: 7.7.3
+      slugify:
+        specifier: ^1.6.6
+        version: 1.6.6
+    devDependencies:
+      '@types/fs-extra':
+        specifier: ^11.0.4
+        version: 11.0.4
+      '@types/node':
+        specifier: ^20.14.10
+        version: 20.19.19
+      '@types/proper-lockfile':
+        specifier: ^4.1.4
+        version: 4.1.4
+      '@types/semver':
+        specifier: ^7.5.8
+        version: 7.7.1
+      prettier:
+        specifier: ^3.3.3
+        version: 3.6.2
+      tsup:
+        specifier: ^8.1.0
+        version: 8.5.0(jiti@2.7.0)(postcss@8.5.15)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
+      typescript:
+        specifier: ^5.5.3
+        version: 5.9.3
+      vitest:
+        specifier: ^3.2.4
+        version: 3.2.4(@types/debug@4.1.12)(@types/node@20.19.19)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.15))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  packages/visualiser:
+    dependencies:
+      '@heroicons/react':
+        specifier: ^2.2.0
+        version: 2.2.0(react@18.3.1)
+      '@radix-ui/react-context-menu':
+        specifier: ^2.2.16
+        version: 2.2.16(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-dialog':
+        specifier: ^1.1.15
+        version: 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-dropdown-menu':
+        specifier: ^2.1.4
+        version: 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-tooltip':
+        specifier: ^1.2.8
+        version: 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@xyflow/react':
+        specifier: ^12.6.1
+        version: 12.8.6(@types/react@19.2.13)(immer@9.0.21)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      dagre:
+        specifier: ^0.8.5
+        version: 0.8.5
+      html-to-image:
+        specifier: ^1.11.11
+        version: 1.11.13
+      lucide-react:
+        specifier: ^0.510.0
+        version: 0.510.0(react@18.3.1)
+      marked:
+        specifier: ^16.1.2
+        version: 16.4.0
+      mermaid:
+        specifier: ^11.12.3
+        version: 11.12.3
+      svg-pan-zoom:
+        specifier: ^3.6.2
+        version: 3.6.2
+    devDependencies:
+      '@tailwindcss/postcss':
+        specifier: ^4.1.5
+        version: 4.1.18
+      '@types/dagre':
+        specifier: ^0.7.53
+        version: 0.7.53
+      '@types/react':
+        specifier: ^19.1.0
+        version: 19.2.13
+      '@types/react-dom':
+        specifier: ^19.1.1
+        version: 19.2.3(@types/react@19.2.13)
+      '@vitejs/plugin-react':
+        specifier: ^5.1.4
+        version: 5.1.4(vite@7.1.9(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
+      concurrently:
+        specifier: ^8.2.2
+        version: 8.2.2
+      postcss:
+        specifier: ^8.5.3
+        version: 8.5.6
+      postcss-cli:
+        specifier: ^11.0.0
+        version: 11.0.1(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0)
+      prettier:
+        specifier: ^3.4.2
+        version: 3.6.2
+      react:
+        specifier: ^18.3.1
+        version: 18.3.1
+      react-dom:
+        specifier: ^18.3.1
+        version: 18.3.1(react@18.3.1)
+      rimraf:
+        specifier: ^6.0.1
+        version: 6.1.2
+      tailwindcss:
+        specifier: ^4.1.5
+        version: 4.1.18
+      tsup:
+        specifier: ^8.5.0
+        version: 8.5.0(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
+      typescript:
+        specifier: ^5.8.2
+        version: 5.9.3
+      vite:
+        specifier: ^7.1.9
+        version: 7.1.9(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      vitest:
+        specifier: ^3.2.4
+        version: 3.2.4(@types/debug@4.1.12)(@types/node@25.0.3)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.6))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  packages/vscode-extension:
+    dependencies:
+      '@eventcatalog/language-server':
+        specifier: workspace:*
+        version: link:../language-server
+      vscode-languageclient:
+        specifier: ^9.0.1
+        version: 9.0.1
+    devDependencies:
+      '@eventcatalog/visualiser':
+        specifier: workspace:*
+        version: link:../visualiser
+      '@types/vscode':
+        specifier: ^1.85.0
+        version: 1.109.0
+      '@xyflow/react':
+        specifier: ^12.4.0
+        version: 12.8.6(@types/react@19.2.13)(immer@9.0.21)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      esbuild:
+        specifier: ^0.21.0
+        version: 0.21.5
+      langium:
+        specifier: ^3.3.1
+        version: 3.5.0
+      prettier:
+        specifier: ^3.2.5
+        version: 3.6.2
+      react:
+        specifier: ^18.3.1
+        version: 18.3.1
+      react-dom:
+        specifier: ^18.3.1
+        version: 18.3.1(react@18.3.1)
+      typescript:
+        specifier: ^5.7.0
+        version: 5.9.3
+      vitest:
+        specifier: ^3.0.0
+        version: 3.2.4(@types/debug@4.1.12)(@types/node@25.0.3)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.15))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
 
 packages:
 
-  '@ai-sdk/anthropic@2.0.25':
-    resolution: {integrity: sha512-XuGg4Mk/hbbe34a27ElFbontKbQMi0lSIOw4iFpbzXowsvW/ld5tspFOcrjDrNcy+0z5iXSFVklwwQcNwe65SQ==}
+  '@ai-sdk/gateway@3.0.13':
+    resolution: {integrity: sha512-g7nE4PFtngOZNZSy1lOPpkC+FAiHxqBJXqyRMEG7NUrEVZlz5goBdtHg1YgWRJIX776JTXAmbOI5JreAKVAsVA==}
     engines: {node: '>=18'}
     peerDependencies:
       zod: ^3.25.76 || ^4.1.8
 
-  '@ai-sdk/gateway@1.0.35':
-    resolution: {integrity: sha512-cdsXbeRRMi6QxbZscin69Asx2fi0d2TmmPngcPFUMpZbchGEBiJYVNvIfiALKFKXEq0l/w0xGNV3E13vroaleA==}
+  '@ai-sdk/gateway@3.0.9':
+    resolution: {integrity: sha512-EA5dZIukimwoJ9HIPuuREotAqaTItpdc/yImzVF0XGNg7B0YRJmYI8Uq3aCMr87vjr1YB1cWUfnrTt6OJ9eHiQ==}
     engines: {node: '>=18'}
     peerDependencies:
       zod: ^3.25.76 || ^4.1.8
 
-  '@ai-sdk/google@2.0.18':
-    resolution: {integrity: sha512-ycGAqouueHjU0hB6JHYmUhXYCnN67PqI8+9jCv13MbuE0g+b9w78HiPuab5ResakY0cq3ynFDvbiu8jAGo1RZQ==}
+  '@ai-sdk/provider-utils@4.0.4':
+    resolution: {integrity: sha512-VxhX0B/dWGbpNHxrKCWUAJKXIXV015J4e7qYjdIU9lLWeptk0KMLGcqkB4wFxff5Njqur8dt8wRi1MN9lZtDqg==}
     engines: {node: '>=18'}
     peerDependencies:
       zod: ^3.25.76 || ^4.1.8
 
-  '@ai-sdk/openai@2.0.45':
-    resolution: {integrity: sha512-9OsVWzW502UCYN1VS9D+1flwrF9GqFvpfybfb1iLIdvmCbXXKXpozhLyuAW82FY67hfiIlOsvlgT9UYtljlQmw==}
+  '@ai-sdk/provider-utils@4.0.5':
+    resolution: {integrity: sha512-Ow/X/SEkeExTTc1x+nYLB9ZHK2WUId8+9TlkamAx7Tl9vxU+cKzWx2dwjgMHeCN6twrgwkLrrtqckQeO4mxgVA==}
     engines: {node: '>=18'}
     peerDependencies:
       zod: ^3.25.76 || ^4.1.8
 
-  '@ai-sdk/provider-utils@3.0.11':
-    resolution: {integrity: sha512-4hgHj89VqyOHzGaV85TkcgvO8WjecVF35TOUVg+C56vnzpWSgdIZu/ZWZNdZ6BTrv8y0N1toBWW7XcWiRRicLg==}
+  '@ai-sdk/provider@3.0.2':
+    resolution: {integrity: sha512-HrEmNt/BH/hkQ7zpi2o6N3k1ZR1QTb7z85WYhYygiTxOQuaml4CMtHCWRbric5WPU+RNsYI7r1EpyVQMKO1pYw==}
     engines: {node: '>=18'}
-    peerDependencies:
-      zod: ^3.25.76 || ^4.1.8
 
-  '@ai-sdk/provider@2.0.0':
-    resolution: {integrity: sha512-6o7Y2SeO9vFKB8lArHXehNuusnpddKPk7xqL7T2/b+OvXMRIXUO1rR4wcv1hAFUAT9avGZshty3Wlua/XA7TvA==}
+  '@ai-sdk/react@3.0.17':
+    resolution: {integrity: sha512-7BoLTK9RkUe3hdl/UL2FsRoEfPUsvHCWmFWy6NzRatTy+Xtg7AImyuyTK8gPymEdqpPdKCcMxJQU6e0UAtOwLQ==}
     engines: {node: '>=18'}
+    peerDependencies:
+      react: ^18 || ~19.0.1 || ~19.1.2 || ^19.2.1
 
-  '@ai-sdk/react@2.0.62':
-    resolution: {integrity: sha512-rmfDpkJuOlVyw1yJd47kcn80u9F4s6cfmOafQdADzId9Sb4D9ksJnLeUhgo5XWkqLsLjNWi6Sdg6hzmthIgSEQ==}
+  '@ai-sdk/vue@3.0.33':
+    resolution: {integrity: sha512-czM9Js3a7f+Eo35gjEYEeJYUoPvMg5Dfi4bOLyDBghLqn0gaVg8yTmTaSuHCg+3K/+1xPjyXd4+2XcQIohWWiQ==}
     engines: {node: '>=18'}
     peerDependencies:
-      react: ^18 || ^19 || ^19.0.0-rc
-      zod: ^3.25.76 || ^4.1.8
-    peerDependenciesMeta:
-      zod:
-        optional: true
+      vue: ^3.3.4
+
+  '@alloc/quick-lru@5.2.0':
+    resolution: {integrity: sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw==}
+    engines: {node: '>=10'}
+
+  '@antfu/install-pkg@1.1.0':
+    resolution: {integrity: sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ==}
+
+  '@antfu/utils@9.3.0':
+    resolution: {integrity: sha512-9hFT4RauhcUzqOE4f1+frMKLZrgNog5b06I7VmZQV1BkvwvqrbC8EBZf3L1eEL2AKb6rNKjER0sEvJiSP1FXEA==}
+
+  '@asamuzakjp/css-color@4.0.5':
+    resolution: {integrity: sha512-lMrXidNhPGsDjytDy11Vwlb6OIGrT3CmLg3VWNFyWkLWtijKl7xjvForlh8vuj0SHGjgl4qZEQzUmYTeQA2JFQ==}
+
+  '@asamuzakjp/dom-selector@6.6.1':
+    resolution: {integrity: sha512-8QT9pokVe1fUt1C8IrJketaeFOdRfTOS96DL3EBjE8CRZm3eHnwMlQe2NPoOSEYPwJ5Q25uYoX1+m9044l3ysQ==}
+
+  '@asamuzakjp/nwsapi@2.3.9':
+    resolution: {integrity: sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q==}
+
+  '@astrojs/check@0.5.10':
+    resolution: {integrity: sha512-vliHXM9cu/viGeKiksUM4mXfO816ohWtawTl2ADPgTsd4nUMjFiyAl7xFZhF34yy4hq4qf7jvK1F2PlR3b5I5w==}
+    hasBin: true
+    peerDependencies:
+      typescript: ^5.0.0
+
+  '@astrojs/check@0.9.9':
+    resolution: {integrity: sha512-A5UW8uIuErLWEoRQvzgXpO1gTjUFtK8r7nU2Z7GewAMxUb7bPvpk11qaKKgxqXlHJWlAvaaxy+Xg28A6bmQ1Tg==}
+    hasBin: true
+    peerDependencies:
+      typescript: ^5.0.0 || ^6.0.0
+
+  '@astrojs/compiler-binding-darwin-arm64@0.2.2':
+    resolution: {integrity: sha512-1WxpECx3izz5X4Ha3l6ex79HZlUHpKBTElGJsfOosnhVvXhccfcXAsBlrYPNmUOKJWiG7mcrje0ELSr1KPE69Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@astrojs/compiler-binding-darwin-x64@0.2.2':
+    resolution: {integrity: sha512-PdIQidwQ4nUX/qNL0JXzSwNYadr+yX/Yoo+kZSCxBZqlAqug9SlKR/1H5EG5jSEpkEDRo2d1JdrO1W4kU6uNHw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@astrojs/compiler-binding-linux-arm64-gnu@0.2.2':
+    resolution: {integrity: sha512-5sZicPkJCoyxTEOW2he+u6UV97pTXY4c7fbHOZ/aslu9ewsunD0231QUBSvnjBB9hRFzzP2JRfNCLY+IvWfw0Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@astrojs/compiler-binding-linux-arm64-musl@0.2.2':
+    resolution: {integrity: sha512-Vto5fqRzMepQNJPeEhQLOIkmAoNbSBQNlpMe64OHTjEbAtQpJYVHEwe+8WJLaEGLA9qBksLv7ctiYPLLxgVVYQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@astrojs/compiler-binding-linux-x64-gnu@0.2.2':
+    resolution: {integrity: sha512-NJTTaUDU49WEJT+ImS9evlv3i3x42HN8PbcqdyydI9picnKtuf5TxRL94naoW09YDMYWpkrwVeVqaG7GTSIepQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@astrojs/compiler-binding-linux-x64-musl@0.2.2':
+    resolution: {integrity: sha512-9nFdNDkWaU35bhWUIciDmi439W0fq2ZNgv1GCi2A/LSb+8vTw9l9z+fVW4YEn7Tlvbs8gyQkJvbc62ZD1H76xA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@astrojs/compiler-binding-wasm32-wasi@0.2.2':
+    resolution: {integrity: sha512-3NWaxRc3KSwr9zHBEGcQ147rMgAhi/HzZWZJPRN2YLbtuLhoeBPruhdX1MIlOYAg3FvJPYdzGCAKvvWWU6pF0A==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+
+  '@astrojs/compiler-binding-win32-arm64-msvc@0.2.2':
+    resolution: {integrity: sha512-QsyOgocLGOwDm8zAyuAiziALMzbTTevaqBLv5lvdhyhj2JC5yjp0H3yeEBtE0owRLr1gDQdX0+1qBSc5tTwp4g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@astrojs/compiler-binding-win32-x64-msvc@0.2.2':
+    resolution: {integrity: sha512-+/C8Oh9YS8C0fwtaqDtUSPniKwlJqgiQbxp7XuzxCP0RI/Jf7yOlz9ZHNr6jD3ZJa4CHdq0mYq7pd8QFiNGIZA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
 
-  '@alloc/quick-lru@5.2.0':
-    resolution: {integrity: sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw==}
-    engines: {node: '>=10'}
+  '@astrojs/compiler-binding@0.2.2':
+    resolution: {integrity: sha512-PkCo+UcSxMt9pufjv28kRy8YU88O/XNgm7apwkyhkrCecLY62QCj5UA3nOTMO88PPyVKnUh/6FZbPefBhDD5IA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
 
-  '@antfu/install-pkg@1.1.0':
-    resolution: {integrity: sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ==}
+  '@astrojs/compiler-rs@0.2.2':
+    resolution: {integrity: sha512-C0qoz7Hxa2krlwMYfzQ1ZxOjR6cGmO+iskjRXXCdUM85W/cAPGTi/MSQlLkv0ADMz+Go1/lqeRBjL8AZwsFffQ==}
 
-  '@antfu/utils@9.3.0':
-    resolution: {integrity: sha512-9hFT4RauhcUzqOE4f1+frMKLZrgNog5b06I7VmZQV1BkvwvqrbC8EBZf3L1eEL2AKb6rNKjER0sEvJiSP1FXEA==}
+  '@astrojs/compiler@2.13.0':
+    resolution: {integrity: sha512-mqVORhUJViA28fwHYaWmsXSzLO9osbdZ5ImUfxBarqsYdMlPbqAqGJCxsNzvppp1BEzc1mJNjOVvQqeDN8Vspw==}
 
-  '@asamuzakjp/css-color@4.0.5':
-    resolution: {integrity: sha512-lMrXidNhPGsDjytDy11Vwlb6OIGrT3CmLg3VWNFyWkLWtijKl7xjvForlh8vuj0SHGjgl4qZEQzUmYTeQA2JFQ==}
+  '@astrojs/compiler@2.13.1':
+    resolution: {integrity: sha512-f3FN83d2G/v32ipNClRKgYv30onQlMZX1vCeZMjPsMMPl1mDpmbl0+N5BYo4S/ofzqJyS5hvwacEo0CCVDn/Qg==}
 
-  '@asamuzakjp/dom-selector@6.6.1':
-    resolution: {integrity: sha512-8QT9pokVe1fUt1C8IrJketaeFOdRfTOS96DL3EBjE8CRZm3eHnwMlQe2NPoOSEYPwJ5Q25uYoX1+m9044l3ysQ==}
+  '@astrojs/compiler@3.0.0':
+    resolution: {integrity: sha512-MwAbDE5mawZ1SS+D8qWiHdprdME5Tlj2e0YjxnEICvcOpbSukNS7Sa7hA5PK+6RrmUr/t6Gi5YgrdZKjbO/WPQ==}
 
-  '@asamuzakjp/nwsapi@2.3.9':
-    resolution: {integrity: sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q==}
+  '@astrojs/internal-helpers@0.10.0':
+    resolution: {integrity: sha512-Ry2R3VPeIN4uPCSA4xQc+e+vsJXkalKpEbDc07hV+a/o5Bs2N/s/uDcPJH/05L19DKh9tAy7e6JM3YZ6Cxfezw==}
 
-  '@astrojs/check@0.5.10':
-    resolution: {integrity: sha512-vliHXM9cu/viGeKiksUM4mXfO816ohWtawTl2ADPgTsd4nUMjFiyAl7xFZhF34yy4hq4qf7jvK1F2PlR3b5I5w==}
-    hasBin: true
-    peerDependencies:
-      typescript: ^5.0.0
+  '@astrojs/internal-helpers@0.8.0':
+    resolution: {integrity: sha512-J56GrhEiV+4dmrGLPNOl2pZjpHXAndWVyiVDYGDuw6MWKpBSEMLdFxHzeM/6sqaknw9M+HFfHZAcvi3OfT3D/w==}
+
+  '@astrojs/internal-helpers@0.9.0':
+    resolution: {integrity: sha512-GdYkzR26re8izmyYlBqf4z2s7zNngmWLFuxw0UKiPNqHraZGS6GKWIwSHgS22RDlu2ePFJ8bzmpBcUszut/SDg==}
 
-  '@astrojs/check@0.9.5':
-    resolution: {integrity: sha512-88vc8n2eJ1Oua74yXSGo/8ABMeypfQPGEzuoAx2awL9Ju8cE6tZ2Rz9jVx5hIExHK5gKVhpxfZj4WXm7e32g1w==}
+  '@astrojs/language-server@2.16.2':
+    resolution: {integrity: sha512-J3hVx/mFi3FwEzKf8ExYXQNERogD6RXswtbU+TyrxoXRBiQoBO5ooo7/lRWJ+rlUKUd7+rziMPI9jYB7TRlh0w==}
     hasBin: true
     peerDependencies:
-      typescript: ^5.0.0
-
-  '@astrojs/compiler@2.13.0':
-    resolution: {integrity: sha512-mqVORhUJViA28fwHYaWmsXSzLO9osbdZ5ImUfxBarqsYdMlPbqAqGJCxsNzvppp1BEzc1mJNjOVvQqeDN8Vspw==}
-
-  '@astrojs/internal-helpers@0.7.5':
-    resolution: {integrity: sha512-vreGnYSSKhAjFJCWAwe/CNhONvoc5lokxtRoZims+0wa3KbHBdPHSSthJsKxPd8d/aic6lWKpRTYGY/hsgK6EA==}
+      prettier: ^3.0.0
+      prettier-plugin-astro: '>=0.11.0'
+    peerDependenciesMeta:
+      prettier:
+        optional: true
+      prettier-plugin-astro:
+        optional: true
 
-  '@astrojs/language-server@2.15.4':
-    resolution: {integrity: sha512-JivzASqTPR2bao9BWsSc/woPHH7OGSGc9aMxXL4U6egVTqBycB3ZHdBJPuOCVtcGLrzdWTosAqVPz1BVoxE0+A==}
+  '@astrojs/language-server@2.16.7':
+    resolution: {integrity: sha512-b64bWT74Vq/ORcSqW7TdIjjpB6hcl+Ei/lMANIUaAGlLPiYNtPTRI/j2tzvugT+LoVwfJtE2Ukq/t2OGCyEtfQ==}
     hasBin: true
     peerDependencies:
       prettier: ^3.0.0
@@ -426,70 +1050,106 @@ packages:
       prettier-plugin-astro:
         optional: true
 
-  '@astrojs/markdown-remark@6.3.9':
-    resolution: {integrity: sha512-hX2cLC/KW74Io1zIbn92kI482j9J7LleBLGCVU9EP3BeH5MVrnFawOnqD0t/q6D1Z+ZNeQG2gNKMslCcO36wng==}
+  '@astrojs/markdown-remark@7.0.0':
+    resolution: {integrity: sha512-jTAXHPy45L7o1ljH4jYV+ShtOHtyQUa1mGp3a5fJp1soX8lInuTJQ6ihmldHzVM4Q7QptU4SzIDIcKbBJO7sXQ==}
 
-  '@astrojs/mdx@4.3.12':
-    resolution: {integrity: sha512-pL3CVPtuQrPnDhWjy7zqbOibNyPaxP4VpQS8T8spwKqKzauJ4yoKyNkVTD8jrP7EAJHmBhZ7PTmUGZqOpKKp8g==}
-    engines: {node: 18.20.8 || ^20.3.0 || >=22.0.0}
+  '@astrojs/markdown-remark@7.1.1':
+    resolution: {integrity: sha512-C6e9BnLGlbdv6bV8MYGeHpHxsUHrCrB4OuRLqi5LI7oiBVcBcqfUN06zpwFQdHgV48QCCrMmLpyqBr7VqC+swA==}
+
+  '@astrojs/markdown-remark@7.2.0':
+    resolution: {integrity: sha512-+YxmVQu1Bd+MFfSzjq1rOJvD9+nIOJzz5YIIhdIH01RrxRkKbyKoEgyIqP3yv51MhzMDgd79QaPv+kCVPT8vHw==}
+
+  '@astrojs/markdown-satteri@0.3.2':
+    resolution: {integrity: sha512-feXuUPy41gVfeM7EHT1ciUim8ozGr+YHXab9uUBc1Hk8y60DQosO8ldL+AoPXnCAoGj1OChwHfvXmmJ6XVnY9A==}
+
+  '@astrojs/mdx@5.0.4':
+    resolution: {integrity: sha512-tSbuuYueNODiFAFaME7pjHY5lOLoxBYJi1cKd6scw9+a4ZO7C7UGdafEoVAQvOV2eO8a6RaHSAJYGVPL1w8BPA==}
+    engines: {node: '>=22.12.0'}
+    peerDependencies:
+      astro: ^6.0.0
+
+  '@astrojs/mdx@7.0.0':
+    resolution: {integrity: sha512-LKwNA8nnLtEM0auoP6OfH/UnlKe1Ub59qZjbcYkZjPBGw6PkJewWkA/1qwLpECvV6gMDd6TR6eqV9p/VYZrcrQ==}
+    engines: {node: '>=22.12.0'}
     peerDependencies:
-      astro: ^5.0.0
+      '@astrojs/markdown-satteri': ^0.3.1-alpha.0
+      astro: ^7.0.0-alpha.0
+    peerDependenciesMeta:
+      '@astrojs/markdown-satteri':
+        optional: true
 
-  '@astrojs/node@9.5.1':
-    resolution: {integrity: sha512-7k+SU877OUQylPr0mFcWrGvNuC78Lp9w+GInY8Rwc+LkHyDP9xls+nZAioK0WDWd+fyeQnlHbpDGURO3ZHuDVg==}
+  '@astrojs/node@11.0.0':
+    resolution: {integrity: sha512-lmwSTG42fAs9/UxNAHt4noseEwXcDupwqMWVftw0j24BaHU9F1CEfi63p3pPlwGP9g0wLqitGQJP/P6x1vLdOQ==}
     peerDependencies:
-      astro: ^5.14.3
+      astro: ^7.0.0-alpha.2
 
-  '@astrojs/prism@3.3.0':
-    resolution: {integrity: sha512-q8VwfU/fDZNoDOf+r7jUnMC2//H2l0TuQ6FkGJL8vD8nw/q5KiL3DS1KKBI3QhI9UQhpJ5dc7AtqfbXWuOgLCQ==}
-    engines: {node: 18.20.8 || ^20.3.0 || >=22.0.0}
+  '@astrojs/prism@4.0.0':
+    resolution: {integrity: sha512-NndtNPpxaGinRpRytljGBvYHpTOwHycSZ/c+lQi5cHvkqqrHKWdkPEhImlODBNmbuB+vyQUNUDXyjzt66CihJg==}
+    engines: {node: ^20.19.1 || >=22.12.0}
 
-  '@astrojs/react@4.4.2':
-    resolution: {integrity: sha512-1tl95bpGfuaDMDn8O3x/5Dxii1HPvzjvpL2YTuqOOrQehs60I2DKiDgh1jrKc7G8lv+LQT5H15V6QONQ+9waeQ==}
-    engines: {node: 18.20.8 || ^20.3.0 || >=22.0.0}
+  '@astrojs/prism@4.0.1':
+    resolution: {integrity: sha512-nksZQVjlferuWzhPsBpQ1JE5XuKAf1id1/9Hj4a9KG4+ofrlzxUUwX4YGQF/SuDiuiGKEnzopGOt38F3AnVWsQ==}
+    engines: {node: '>=22.12.0'}
+
+  '@astrojs/prism@4.0.2':
+    resolution: {integrity: sha512-KTivpmnz6lDsC6o9H4+DNm2SrE/GHzw8cNAvEJwAvUT+eoaEnn/4NtbDNfRRaxaJHdp15gf+tfHAWiXR4wB3BA==}
+    engines: {node: '>=22.12.0'}
+
+  '@astrojs/react@6.0.0':
+    resolution: {integrity: sha512-jNf3kKE6KYXJbD5ZsXaLhnwDK3YvK9ttQ2ykAcNf5XdxOlUQEHLnomO3FO8abqghs0ilqhgGOyc2AlgGyQtz/g==}
+    engines: {node: '>=22.12.0'}
     peerDependencies:
       '@types/react': ^17.0.50 || ^18.0.21 || ^19.0.0
       '@types/react-dom': ^17.0.17 || ^18.0.6 || ^19.0.0
       react: ^17.0.2 || ^18.0.0 || ^19.0.0
       react-dom: ^17.0.2 || ^18.0.0 || ^19.0.0
 
-  '@astrojs/rss@4.0.14':
-    resolution: {integrity: sha512-KCe1imDcADKOOuO/wtKOMDO/umsBD6DWF+94r5auna1jKl5fmlK9vzf+sjA3EyveXA/FoB3khtQ/u/tQgETmTw==}
+  '@astrojs/rss@4.0.18':
+    resolution: {integrity: sha512-wc5DwKlbTEdgVAWnHy8krFTeQ42t1v/DJqeq5HtulYK3FYHE4krtRGjoyhS3eXXgfdV6Raoz2RU3wrMTFAitRg==}
 
-  '@astrojs/tailwind@6.0.2':
-    resolution: {integrity: sha512-j3mhLNeugZq6A8dMNXVarUa8K6X9AW+QHU9u3lKNrPLMHhOQ0S7VeWhHwEeJFpEK1BTKEUY1U78VQv2gN6hNGg==}
+  '@astrojs/sitemap@3.7.1':
+    resolution: {integrity: sha512-IzQqdTeskaMX+QDZCzMuJIp8A8C1vgzMBp/NmHNnadepHYNHcxQdGLQZYfkbd2EbRXUfOS+UDIKx8sKg0oWVdw==}
+
+  '@astrojs/starlight@0.38.0':
+    resolution: {integrity: sha512-l+7VJ9DeOcXdU43u3lF39VDHrS0AB8eX7sN9qft77hfHIK4GkduClF+V7J9kd9xLDxwo2zcYDyzmp4o26gy8mg==}
     peerDependencies:
-      astro: ^3.0.0 || ^4.0.0 || ^5.0.0
-      tailwindcss: ^3.0.24
+      astro: ^6.0.0
 
   '@astrojs/telemetry@3.3.0':
     resolution: {integrity: sha512-UFBgfeldP06qu6khs/yY+q1cDAaArM2/7AEIqQ9Cuvf7B1hNLq0xDrZkct+QoIGyjq56y8IaE2I3CTvG99mlhQ==}
     engines: {node: 18.20.8 || ^20.3.0 || >=22.0.0}
 
+  '@astrojs/telemetry@3.3.2':
+    resolution: {integrity: sha512-j8DNruA8ors99Al39RYZPJK4DC1bKkoNm93mAMuBhY9TCNC4R8n1q7ovFnJ5qhGh5Lsh7pa1gpQVpYpsJPeTHQ==}
+    engines: {node: 18.20.8 || ^20.3.0 || >=22.0.0}
+
   '@astrojs/yaml2ts@0.2.2':
     resolution: {integrity: sha512-GOfvSr5Nqy2z5XiwqTouBBpy5FyI6DEe+/g/Mk5am9SjILN1S5fOEvYK0GuWHg98yS/dobP4m8qyqw/URW35fQ==}
 
+  '@astrojs/yaml2ts@0.2.3':
+    resolution: {integrity: sha512-PJzRmgQzUxI2uwpdX2lXSHtP4G8ocp24/t+bZyf5Fy0SZLSF9f9KXZoMlFM/XCGue+B0nH/2IZ7FpBYQATBsCg==}
+
   '@asyncapi/avro-schema-parser@3.0.24':
     resolution: {integrity: sha512-YMyr2S2heMrWHRyECknjHeejlZl5exUSv9nD1gTejAT13fSf0PqIRydZ9ZuoglCLBg55AeehypR2zLIBu/9kHQ==}
 
   '@asyncapi/openapi-schema-parser@3.0.24':
     resolution: {integrity: sha512-7wz2yVDedJMS+TzOuqCvRWJMc6pNHICKZcOhnW6ZvyVLAh7hYIqQE1WA4OoXT4cKVbwSU3V2Q4bZagSsAIQd6Q==}
 
-  '@asyncapi/parser@3.4.0':
-    resolution: {integrity: sha512-Sxn74oHiZSU6+cVeZy62iPZMFMvKp4jupMFHelSICCMw1qELmUHPvuZSr+ZHDmNGgHcEpzJM5HN02kR7T4g+PQ==}
+  '@asyncapi/parser@3.6.0':
+    resolution: {integrity: sha512-6S0Yr8vI418a1IrpGsOYbfWVo9+aHvSqN2oSkiY0YJltS/C7oDOt9e0mo6hSld8bg+EeKrtgkVmpW4obh1JFvA==}
 
   '@asyncapi/protobuf-schema-parser@3.6.0':
     resolution: {integrity: sha512-z6zVRAMi2bkkgjREoCIvUg7KcacyoEh+VIwQmEni/JPuPFMOD3oPv4kwoftEeiF2+gGiioeIxpkI5x7rmHf2Nw==}
     engines: {node: '>=18'}
 
-  '@asyncapi/react-component@2.4.3':
-    resolution: {integrity: sha512-8DZdadD2vGoq7rw18RehmytQLT2Y1RFQ+UgvhQA3UaTqIFL2qFOHIm1YMnl5VVPxtTmkvi20wZZk37nyNvzJug==}
+  '@asyncapi/react-component@3.1.0':
+    resolution: {integrity: sha512-D+xyoMx9BY2f6LUJ+tEwBXrQ7b7PTUl5A8uRhfkvr+EDq2mnMyWlYrwFNHaJGQ85yyDC6LKAoUgC1o0aRi5Thg==}
     peerDependencies:
       react: '>=18.0.0'
       react-dom: '>=18.0.0'
 
-  '@asyncapi/specs@6.10.0':
-    resolution: {integrity: sha512-vB5oKLsdrLUORIZ5BXortZTlVyGWWMC1Nud/0LtgxQ3Yn2738HigAD6EVqScvpPsDUI/bcLVsYEXN4dtXQHVng==}
+  '@asyncapi/specs@6.11.1':
+    resolution: {integrity: sha512-A3WBLqAKGoJ2+6FWFtpjBlCQ1oFCcs4GxF7zsIGvNqp/klGUHjlA3aAcZ9XMMpLGE8zPeYDz2x9FmO6DSuKraQ==}
 
   '@auth/core@0.37.4':
     resolution: {integrity: sha512-HOXJwXWXQRhbBDHlMU0K/6FT1v+wjtzdKhsNg0ZN7/gne6XPsIrjZ4daMcFnbq0Z/vsAbYBinQhhua0d77v7qw==}
@@ -505,36 +1165,36 @@ packages:
       nodemailer:
         optional: true
 
-  '@babel/code-frame@7.27.1':
-    resolution: {integrity: sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg==}
+  '@babel/code-frame@7.29.0':
+    resolution: {integrity: sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/compat-data@7.28.4':
-    resolution: {integrity: sha512-YsmSKC29MJwf0gF8Rjjrg5LQCmyh+j/nD8/eP7f+BeoQTKYqs9RoWbjGOdy0+1Ekr68RJZMUOPVQaQisnIo4Rw==}
+  '@babel/compat-data@7.29.0':
+    resolution: {integrity: sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/core@7.28.4':
-    resolution: {integrity: sha512-2BCOP7TN8M+gVDj7/ht3hsaO/B/n5oDbiAyyvnRlNOs+u1o+JWNYTQrmpuNp1/Wq2gcFrI01JAW+paEKDMx/CA==}
+  '@babel/core@7.29.0':
+    resolution: {integrity: sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/generator@7.28.3':
-    resolution: {integrity: sha512-3lSpxGgvnmZznmBkCRnVREPUFJv2wrv9iAoFDvADJc0ypmdOxdUtcLeBgBJ6zE0PMeTKnxeQzyk0xTBq4Ep7zw==}
+  '@babel/generator@7.29.1':
+    resolution: {integrity: sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/helper-compilation-targets@7.27.2':
-    resolution: {integrity: sha512-2+1thGUUWWjLTYTHZWK1n8Yga0ijBz1XAhUXcKy81rd5g6yh7hGqMp45v7cadSbEHc9G3OTv45SyneRN3ps4DQ==}
+  '@babel/helper-compilation-targets@7.28.6':
+    resolution: {integrity: sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA==}
     engines: {node: '>=6.9.0'}
 
   '@babel/helper-globals@7.28.0':
     resolution: {integrity: sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/helper-module-imports@7.27.1':
-    resolution: {integrity: sha512-0gSFWUPNXNopqtIPQvlD5WgXYI5GY2kP2cCvoT8kczjbfcfuIljTbcWrulD1CIPIX2gt1wghbDy08yE1p+/r3w==}
+  '@babel/helper-module-imports@7.28.6':
+    resolution: {integrity: sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/helper-module-transforms@7.28.3':
-    resolution: {integrity: sha512-gytXUbs8k2sXS9PnQptz5o0QnpLL51SwASIORY6XaBKF88nsOT0Zw9szLqlSGQDP/4TljBAD5y98p2U1fqkdsw==}
+  '@babel/helper-module-transforms@7.28.6':
+    resolution: {integrity: sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==}
     engines: {node: '>=6.9.0'}
     peerDependencies:
       '@babel/core': ^7.0.0
@@ -547,10 +1207,6 @@ packages:
     resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/helper-validator-identifier@7.27.1':
-    resolution: {integrity: sha512-D2hP9eA+Sqx1kBZgzxZh0y1trbuU+JoDkiEwqhQ36nodYqJwyEIhPSdMNd7lOm/4io72luTPWH20Yda0xOuUow==}
-    engines: {node: '>=6.9.0'}
-
   '@babel/helper-validator-identifier@7.28.5':
     resolution: {integrity: sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==}
     engines: {node: '>=6.9.0'}
@@ -559,17 +1215,17 @@ packages:
     resolution: {integrity: sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/helpers@7.28.4':
-    resolution: {integrity: sha512-HFN59MmQXGHVyYadKLVumYsA9dBFun/ldYxipEjzA4196jpLZd8UjEEBLkbEkvfYreDqJhZxYAWFPtrfhNpj4w==}
+  '@babel/helpers@7.28.6':
+    resolution: {integrity: sha512-xOBvwq86HHdB7WUDTfKfT/Vuxh7gElQ+Sfti2Cy6yIWNW05P8iUslOVcZ4/sKbE+/jQaukQAdz/gf3724kYdqw==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/parser@7.28.4':
-    resolution: {integrity: sha512-yZbBqeM6TkpP9du/I2pUZnJsRMGGvOuIrhjzC1AwHwW+6he4mni6Bp/m8ijn0iOuZuPI2BfkCoSRunpyjnrQKg==}
+  '@babel/parser@7.29.0':
+    resolution: {integrity: sha512-IyDgFV5GeDUVX4YdF/3CPULtVGSXXMLh1xVIgdCgxApktqnQV0r7/8Nqthg+8YLGaAtdyIlo2qIdZrbCv4+7ww==}
     engines: {node: '>=6.0.0'}
     hasBin: true
 
-  '@babel/parser@7.28.5':
-    resolution: {integrity: sha512-KKBU1VGYR7ORr3At5HAtUQ+TV3SzRCXmA/8OdDZiLDBIZxVyzXuztPjfLd3BV1PRAQGCMWWSHYhL0F8d5uHBDQ==}
+  '@babel/parser@7.29.2':
+    resolution: {integrity: sha512-4GgRzy/+fsBa72/RZVJmGKPmZu9Byn8o4MoLpmNe1m8ZfYnz5emHLQz3U4gLud6Zwl0RZIcgiLD7Uq7ySFuDLA==}
     engines: {node: '>=6.0.0'}
     hasBin: true
 
@@ -589,27 +1245,49 @@ packages:
     resolution: {integrity: sha512-Q/N6JNWvIvPnLDvjlE1OUBLPQHH6l3CltCEsHIujp45zQUSSh8K+gHnaEX45yAT1nyngnINhvWtzN+Nb9D8RAQ==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/template@7.27.2':
-    resolution: {integrity: sha512-LPDZ85aEJyYSd18/DkjNh4/y1ntkE5KwUHWTiqgRxruuZL2F1yuHligVHLvcHY2vMHXttKFpJn6LwfI7cw7ODw==}
+  '@babel/template@7.28.6':
+    resolution: {integrity: sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/traverse@7.28.4':
-    resolution: {integrity: sha512-YEzuboP2qvQavAcjgQNVgsvHIDv6ZpwXvcvjmyySP2DIMuByS/6ioU5G9pYrWHM6T2YDfc7xga9iNzYOs12CFQ==}
+  '@babel/traverse@7.29.0':
+    resolution: {integrity: sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/types@7.28.4':
-    resolution: {integrity: sha512-bkFqkLhh3pMBUQQkpVgWDWq/lqzc2678eUyDlTBhRqhCHFguYYGM0Efga7tYk4TogG/3x0EEl66/OQ+WGbWB/Q==}
-    engines: {node: '>=6.9.0'}
-
-  '@babel/types@7.28.5':
-    resolution: {integrity: sha512-qQ5m48eI/MFLQ5PxQj4PFaprjyCTLI37ElWMmNs0K8Lk3dVeOdNpB3ks8jc7yM5CDmVC73eMVk/trk3fgmrUpA==}
+  '@babel/types@7.29.0':
+    resolution: {integrity: sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==}
     engines: {node: '>=6.9.0'}
 
   '@braintree/sanitize-url@7.1.1':
     resolution: {integrity: sha512-i1L7noDNxtFyL5DmZafWy1wRVhGehQmzZaz1HiN5e7iylJMSZR7ekOV7NsIqa5qBldlLrsKv4HbgFUVlQrz8Mw==}
 
-  '@capsizecss/unpack@3.0.1':
-    resolution: {integrity: sha512-8XqW8xGn++Eqqbz3e9wKuK7mxryeRjs4LOHLxbh2lwKeSbuNR4NFifDZT4KzvjU6HMOPbiNTsWpniK5EJfTWkg==}
+  '@bruits/satteri-darwin-arm64@0.9.1':
+    resolution: {integrity: sha512-NE4qC2sRd0+R+oPMsKcUikIvWTGpAV16fSXNBoMSW7nK7Pd9e/ZGB7M8knep83pFmGmOb/5NbGKiVIh3oLbljw==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@bruits/satteri-darwin-x64@0.9.1':
+    resolution: {integrity: sha512-Am8z5nX0L/sJR/n7np+5rMVP434MOBe3zlU+IO8fXbv2UaPNRCrEQPMS6lyxCj7dZHQI2AynSJw3v4fgQE8xSQ==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@bruits/satteri-linux-x64-gnu@0.9.1':
+    resolution: {integrity: sha512-Bivw60+SIfmlaU9wEZ39HAcyPh1xU9TvOrz4KJgc+ziRStQs4EzYoWW4Eh9aSdiol+xV0vjEWYuA79aF3dr7kg==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@bruits/satteri-wasm32-wasi@0.9.1':
+    resolution: {integrity: sha512-lEFk5ebh5SxRquA5RJisEoMoDmOiSnS10PGgXgXeVlWgF8KWKI9D3hSzVqNjEg/qKOjHcNdjIfyx/03Wrl6J3g==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+
+  '@bruits/satteri-win32-x64-msvc@0.9.1':
+    resolution: {integrity: sha512-YBhm8yARopswAPeTih11BzMxWVQFD5CI9Yryp6HWepi6F/CeMycqxv18DXrj9U2fDDlbVGwT2IiEM2UPBjIPDQ==}
+    cpu: [x64]
+    os: [win32]
+
+  '@capsizecss/unpack@4.0.0':
+    resolution: {integrity: sha512-VERIM64vtTP1C4mxQ5thVT9fK0apjPFobqybMtA1UdUujWka24ERHbRHFGmpbbhp73MhV+KSsHQH9C6uOTdEQA==}
     engines: {node: '>=18'}
 
   '@cfworker/json-schema@4.1.1':
@@ -631,6 +1309,9 @@ packages:
   '@changesets/config@3.1.1':
     resolution: {integrity: sha512-bd+3Ap2TKXxljCggI0mKPfzCQKeV/TU4yO2h2C6vAihIo8tzseAn2e7klSuiyYYXvgu53zMN1OeYMIQkaQoWnA==}
 
+  '@changesets/config@3.1.2':
+    resolution: {integrity: sha512-CYiRhA4bWKemdYi/uwImjPxqWNpqGPNbEBdX1BdONALFIDK7MCUj6FPkzD+z9gJcvDFUQJn9aDVf4UG7OT6Kog==}
+
   '@changesets/errors@0.2.0':
     resolution: {integrity: sha512-6BLOQUscTpZeGljvyQXlWOItQyU71kCdGz7Pi8H8zdw6BI0g3m43iL4xKUVPWtG+qrrL9DTjpdn8eYuCQSRpow==}
 
@@ -652,12 +1333,18 @@ packages:
   '@changesets/parse@0.4.1':
     resolution: {integrity: sha512-iwksMs5Bf/wUItfcg+OXrEpravm5rEd9Bf4oyIPL4kVTmJQ7PNDSd6MDYkpSJR1pn7tz/k8Zf2DhTCqX08Ou+Q==}
 
+  '@changesets/parse@0.4.2':
+    resolution: {integrity: sha512-Uo5MC5mfg4OM0jU3up66fmSn6/NE9INK+8/Vn/7sMVcdWg46zfbvvUSjD9EMonVqPi9fbrJH9SXHn48Tr1f2yA==}
+
   '@changesets/pre@2.0.2':
     resolution: {integrity: sha512-HaL/gEyFVvkf9KFg6484wR9s0qjAXlZ8qWPDkTyKF6+zqjBe/I2mygg3MbpZ++hdi0ToqNUF8cjj7fBy0dg8Ug==}
 
   '@changesets/read@0.6.5':
     resolution: {integrity: sha512-UPzNGhsSjHD3Veb0xO/MwvasGe8eMyNrR/sT9gR8Q3DhOQZirgKhhXv/8hVsI0QpPjR004Z9iFxoJU6in3uGMg==}
 
+  '@changesets/read@0.6.6':
+    resolution: {integrity: sha512-P5QaN9hJSQQKJShzzpBT13FzOSPyHbqdoIBUd2DJdgvnECCyO6LmAOWSV+O8se2TaZJVwSXjL+v9yhb+a9JeJg==}
+
   '@changesets/should-skip-package@0.1.2':
     resolution: {integrity: sha512-qAK/WrqWLNCP22UDdBTMPH5f41elVDlsNyat180A33dWxuUDyNpg6fPi/FyTZwRriVjg0L8gnjJn2F9XAoF0qw==}
 
@@ -673,18 +1360,45 @@ packages:
   '@chevrotain/cst-dts-gen@11.0.3':
     resolution: {integrity: sha512-BvIKpRLeS/8UbfxXxgC33xOumsacaeCKAjAeLyOn7Pcp95HiRbrpl14S+9vaZLolnbssPIUuiUd8IvgkRyt6NQ==}
 
+  '@chevrotain/cst-dts-gen@11.1.2':
+    resolution: {integrity: sha512-XTsjvDVB5nDZBQB8o0o/0ozNelQtn2KrUVteIHSlPd2VAV2utEb6JzyCJaJ8tGxACR4RiBNWy5uYUHX2eji88Q==}
+
   '@chevrotain/gast@11.0.3':
     resolution: {integrity: sha512-+qNfcoNk70PyS/uxmj3li5NiECO+2YKZZQMbmjTqRI3Qchu8Hig/Q9vgkHpI3alNjr7M+a2St5pw5w5F6NL5/Q==}
 
+  '@chevrotain/gast@11.1.2':
+    resolution: {integrity: sha512-Z9zfXR5jNZb1Hlsd/p+4XWeUFugrHirq36bKzPWDSIacV+GPSVXdk+ahVWZTwjhNwofAWg/sZg58fyucKSQx5g==}
+
   '@chevrotain/regexp-to-ast@11.0.3':
     resolution: {integrity: sha512-1fMHaBZxLFvWI067AVbGJav1eRY7N8DDvYCTwGBiE/ytKBgP8azTdgyrKyWZ9Mfh09eHWb5PgTSO8wi7U824RA==}
 
+  '@chevrotain/regexp-to-ast@11.1.2':
+    resolution: {integrity: sha512-nMU3Uj8naWer7xpZTYJdxbAs6RIv/dxYzkYU8GSwgUtcAAlzjcPfX1w+RKRcYG8POlzMeayOQ/znfwxEGo5ulw==}
+
   '@chevrotain/types@11.0.3':
     resolution: {integrity: sha512-gsiM3G8b58kZC2HaWR50gu6Y1440cHiJ+i3JUvcp/35JchYejb2+5MVeJK0iKThYpAa/P2PYFV4hoi44HD+aHQ==}
 
+  '@chevrotain/types@11.1.2':
+    resolution: {integrity: sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==}
+
   '@chevrotain/utils@11.0.3':
     resolution: {integrity: sha512-YslZMgtJUyuMbZ+aKvfF3x1f5liK4mWNxghFRv7jqRR9C3R3fAOGTTKvxXDa2Y1s9zSbcpuO0cAxDYsc9SrXoQ==}
 
+  '@chevrotain/utils@11.1.2':
+    resolution: {integrity: sha512-4mudFAQ6H+MqBTfqLmU7G1ZwRzCLfJEooL/fsF6rCX5eePMbGhoy5n4g+G4vlh2muDcsCTJtL+uKbOzWxs5LHA==}
+
+  '@clack/core@0.3.5':
+    resolution: {integrity: sha512-5cfhQNH+1VQ2xLQlmzXMqUoiaH0lRBq9/CLW9lTyMbuKLC3+xEK01tHVvyut++mLOn5urSHmkm6I0Lg9MaJSTQ==}
+
+  '@clack/core@1.1.0':
+    resolution: {integrity: sha512-SVcm4Dqm2ukn64/8Gub2wnlA5nS2iWJyCkdNHcvNHPIeBTGojpdJ+9cZKwLfmqy7irD4N5qLteSilJlE0WLAtA==}
+
+  '@clack/prompts@0.8.2':
+    resolution: {integrity: sha512-6b9Ab2UiZwJYA9iMyboYyW9yJvAO9V753ZhS+DHKEjZRKAxPPOb7MXXu84lsPFG+vZt6FRFniZ8rXi+zCIw4yQ==}
+
+  '@clack/prompts@1.1.0':
+    resolution: {integrity: sha512-pkqbPGtohJAvm4Dphs2M8xE29ggupihHdy1x84HNojZuMtFsHiUlRvqD24tM2+XmI+61LlfNceM3Wr7U5QES5g==}
+
   '@codemirror/autocomplete@6.19.0':
     resolution: {integrity: sha512-61Hfv3cF07XvUxNeC3E7jhG8XNi1Yom1G0lRC936oLnlF+jrbrv8rc/J98XlYzcsAoTVupfsf5fLej1aI8kyIg==}
 
@@ -715,9 +1429,6 @@ packages:
   '@codemirror/lint@6.9.0':
     resolution: {integrity: sha512-wZxW+9XDytH3SKvS8cQzMyQCaaazH8XL1EMHleHe00wVzsv7NBQKVW2yzEHrRhmM7ZOhVdItPbvlRBvMp9ej7A==}
 
-  '@codemirror/search@6.5.11':
-    resolution: {integrity: sha512-KmWepDE6jUdL6n8cAAqIpRmLPBZ5ZKnicE8oGU/s3QrAVID+0VhLFrzUucVKHG5035/BSykhExDL/Xm7dHthiA==}
-
   '@codemirror/state@6.5.2':
     resolution: {integrity: sha512-FVqsPqtPWKVVL3dPSxy8wEF/ymIEuVzF1PK3VbUgrxXpJUSHQWWZz4JMToquRxnkw+36LTamCZG2iua2Ptq0fA==}
 
@@ -768,8 +1479,8 @@ packages:
   '@emmetio/css-abbreviation@2.1.8':
     resolution: {integrity: sha512-s9yjhJ6saOO/uk1V74eifykk2CBYi01STTK3WlXWGOepyKa23ymJ053+DNQjpFcy1ingpaO7AxCcwLvHFY9tuw==}
 
-  '@emmetio/css-parser@0.4.0':
-    resolution: {integrity: sha512-z7wkxRSZgrQHXVzObGkXG+Vmj3uRlpM11oCZ9pbaz0nFejvCDmAiNDpY75+wgXOcffKpj4rzGtwGaZxfJKsJxw==}
+  '@emmetio/css-parser@0.4.1':
+    resolution: {integrity: sha512-2bC6m0MV/voF4CTZiAbG5MWKbq5EBmDPKu9Sb7s7nVcEzNQlrZP6mFFFlIaISM8X6514H9shWMme1fCm8cWAfQ==}
 
   '@emmetio/html-matcher@1.3.0':
     resolution: {integrity: sha512-NTbsvppE5eVyBMuyGfVu2CRrLvo7J4YHb6t9sBFLyY03WYhXET37qA4zOYUjBWFCRHO7pS1B9khERtY0f5JXPQ==}
@@ -783,9 +1494,30 @@ packages:
   '@emmetio/stream-reader@2.2.0':
     resolution: {integrity: sha512-fXVXEyFA5Yv3M3n8sUGT7+fvecGrZP4k6FnWWMSZVQf69kAq0LLpaBQLGcPR30m3zMmKYhECP4k/ZkzvhEW5kw==}
 
+  '@emnapi/core@1.11.1':
+    resolution: {integrity: sha512-RSvbQmHzdKzNsLYa/wHrbc3KN4sYLKAdPZxqiM2HATqv/SBk2/ENSHpvXGaLOMcsAyz0poEGqkmmKYG3OWiJEQ==}
+
+  '@emnapi/core@1.9.1':
+    resolution: {integrity: sha512-mukuNALVsoix/w1BJwFzwXBN/dHeejQtuVzcDsfOEsdpCumXb/E9j8w11h5S54tT1xhifGfbbSm/ICrObRb3KA==}
+
+  '@emnapi/runtime@1.10.0':
+    resolution: {integrity: sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==}
+
+  '@emnapi/runtime@1.11.1':
+    resolution: {integrity: sha512-vgj7R3y3Wgx24IQaGPA/R6YFXLHVMOZ0uVEyIQPaWs+rd1AzfEMXlAC22FYwO1XkKR6NPsq7mUandH8oIRdZFw==}
+
   '@emnapi/runtime@1.5.0':
     resolution: {integrity: sha512-97/BJ3iXHww3djw6hYIfErCZFee7qCtrneuLa20UXFCOTCfBM2cvQHjWJ2EG0s0MtdNwInarqCTz35i4wWXHsQ==}
 
+  '@emnapi/runtime@1.9.1':
+    resolution: {integrity: sha512-VYi5+ZVLhpgK4hQ0TAjiQiZ6ol0oe4mBx7mVv7IflsiEp0OWoVsp/+f9Vc1hOhE0TtkORVrI1GvzyreqpgWtkA==}
+
+  '@emnapi/wasi-threads@1.2.0':
+    resolution: {integrity: sha512-N10dEJNSsUx41Z6pZsXU8FjPjpBEplgH24sfkmITrBED1/U2Esum9F3lfLrMjKHHjmi557zQn7kR9R+XWXu5Rg==}
+
+  '@emnapi/wasi-threads@1.2.2':
+    resolution: {integrity: sha512-c95qOXkHdydNKhscBTebqEC1CVAZpyqOfVfBzQ1qgzyl3gfeldUjIggDbIZgDKsHLgnsM+igH7TJ/eAasaVuMA==}
+
   '@esbuild/aix-ppc64@0.21.5':
     resolution: {integrity: sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==}
     engines: {node: '>=12'}
@@ -798,6 +1530,18 @@ packages:
     cpu: [ppc64]
     os: [aix]
 
+  '@esbuild/aix-ppc64@0.27.3':
+    resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/aix-ppc64@0.28.1':
+    resolution: {integrity: sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
   '@esbuild/android-arm64@0.21.5':
     resolution: {integrity: sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==}
     engines: {node: '>=12'}
@@ -810,6 +1554,18 @@ packages:
     cpu: [arm64]
     os: [android]
 
+  '@esbuild/android-arm64@0.27.3':
+    resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm64@0.28.1':
+    resolution: {integrity: sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
   '@esbuild/android-arm@0.21.5':
     resolution: {integrity: sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==}
     engines: {node: '>=12'}
@@ -822,6 +1578,18 @@ packages:
     cpu: [arm]
     os: [android]
 
+  '@esbuild/android-arm@0.27.3':
+    resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-arm@0.28.1':
+    resolution: {integrity: sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
   '@esbuild/android-x64@0.21.5':
     resolution: {integrity: sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==}
     engines: {node: '>=12'}
@@ -834,6 +1602,18 @@ packages:
     cpu: [x64]
     os: [android]
 
+  '@esbuild/android-x64@0.27.3':
+    resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/android-x64@0.28.1':
+    resolution: {integrity: sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
   '@esbuild/darwin-arm64@0.21.5':
     resolution: {integrity: sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==}
     engines: {node: '>=12'}
@@ -846,6 +1626,18 @@ packages:
     cpu: [arm64]
     os: [darwin]
 
+  '@esbuild/darwin-arm64@0.27.3':
+    resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-arm64@0.28.1':
+    resolution: {integrity: sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
   '@esbuild/darwin-x64@0.21.5':
     resolution: {integrity: sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==}
     engines: {node: '>=12'}
@@ -858,6 +1650,18 @@ packages:
     cpu: [x64]
     os: [darwin]
 
+  '@esbuild/darwin-x64@0.27.3':
+    resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.28.1':
+    resolution: {integrity: sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
   '@esbuild/freebsd-arm64@0.21.5':
     resolution: {integrity: sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==}
     engines: {node: '>=12'}
@@ -870,6 +1674,18 @@ packages:
     cpu: [arm64]
     os: [freebsd]
 
+  '@esbuild/freebsd-arm64@0.27.3':
+    resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-arm64@0.28.1':
+    resolution: {integrity: sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
   '@esbuild/freebsd-x64@0.21.5':
     resolution: {integrity: sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==}
     engines: {node: '>=12'}
@@ -882,6 +1698,18 @@ packages:
     cpu: [x64]
     os: [freebsd]
 
+  '@esbuild/freebsd-x64@0.27.3':
+    resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.28.1':
+    resolution: {integrity: sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
   '@esbuild/linux-arm64@0.21.5':
     resolution: {integrity: sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==}
     engines: {node: '>=12'}
@@ -894,6 +1722,18 @@ packages:
     cpu: [arm64]
     os: [linux]
 
+  '@esbuild/linux-arm64@0.27.3':
+    resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm64@0.28.1':
+    resolution: {integrity: sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
   '@esbuild/linux-arm@0.21.5':
     resolution: {integrity: sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==}
     engines: {node: '>=12'}
@@ -906,6 +1746,18 @@ packages:
     cpu: [arm]
     os: [linux]
 
+  '@esbuild/linux-arm@0.27.3':
+    resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.28.1':
+    resolution: {integrity: sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
   '@esbuild/linux-ia32@0.21.5':
     resolution: {integrity: sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==}
     engines: {node: '>=12'}
@@ -918,6 +1770,18 @@ packages:
     cpu: [ia32]
     os: [linux]
 
+  '@esbuild/linux-ia32@0.27.3':
+    resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.28.1':
+    resolution: {integrity: sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
   '@esbuild/linux-loong64@0.21.5':
     resolution: {integrity: sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==}
     engines: {node: '>=12'}
@@ -930,6 +1794,18 @@ packages:
     cpu: [loong64]
     os: [linux]
 
+  '@esbuild/linux-loong64@0.27.3':
+    resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.28.1':
+    resolution: {integrity: sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
   '@esbuild/linux-mips64el@0.21.5':
     resolution: {integrity: sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==}
     engines: {node: '>=12'}
@@ -942,6 +1818,18 @@ packages:
     cpu: [mips64el]
     os: [linux]
 
+  '@esbuild/linux-mips64el@0.27.3':
+    resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.28.1':
+    resolution: {integrity: sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
   '@esbuild/linux-ppc64@0.21.5':
     resolution: {integrity: sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==}
     engines: {node: '>=12'}
@@ -954,6 +1842,18 @@ packages:
     cpu: [ppc64]
     os: [linux]
 
+  '@esbuild/linux-ppc64@0.27.3':
+    resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.28.1':
+    resolution: {integrity: sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
   '@esbuild/linux-riscv64@0.21.5':
     resolution: {integrity: sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==}
     engines: {node: '>=12'}
@@ -966,6 +1866,18 @@ packages:
     cpu: [riscv64]
     os: [linux]
 
+  '@esbuild/linux-riscv64@0.27.3':
+    resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.28.1':
+    resolution: {integrity: sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
   '@esbuild/linux-s390x@0.21.5':
     resolution: {integrity: sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==}
     engines: {node: '>=12'}
@@ -978,6 +1890,18 @@ packages:
     cpu: [s390x]
     os: [linux]
 
+  '@esbuild/linux-s390x@0.27.3':
+    resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.28.1':
+    resolution: {integrity: sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
   '@esbuild/linux-x64@0.21.5':
     resolution: {integrity: sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==}
     engines: {node: '>=12'}
@@ -990,12 +1914,36 @@ packages:
     cpu: [x64]
     os: [linux]
 
+  '@esbuild/linux-x64@0.27.3':
+    resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.28.1':
+    resolution: {integrity: sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
   '@esbuild/netbsd-arm64@0.25.10':
     resolution: {integrity: sha512-AKQM3gfYfSW8XRk8DdMCzaLUFB15dTrZfnX8WXQoOUpUBQ+NaAFCP1kPS/ykbbGYz7rxn0WS48/81l9hFl3u4A==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [netbsd]
 
+  '@esbuild/netbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-arm64@0.28.1':
+    resolution: {integrity: sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
   '@esbuild/netbsd-x64@0.21.5':
     resolution: {integrity: sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==}
     engines: {node: '>=12'}
@@ -1008,12 +1956,36 @@ packages:
     cpu: [x64]
     os: [netbsd]
 
+  '@esbuild/netbsd-x64@0.27.3':
+    resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.28.1':
+    resolution: {integrity: sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
   '@esbuild/openbsd-arm64@0.25.10':
     resolution: {integrity: sha512-5Se0VM9Wtq797YFn+dLimf2Zx6McttsH2olUBsDml+lm0GOCRVebRWUvDtkY4BWYv/3NgzS8b/UM3jQNh5hYyw==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [openbsd]
 
+  '@esbuild/openbsd-arm64@0.27.3':
+    resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-arm64@0.28.1':
+    resolution: {integrity: sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
   '@esbuild/openbsd-x64@0.21.5':
     resolution: {integrity: sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==}
     engines: {node: '>=12'}
@@ -1026,12 +1998,36 @@ packages:
     cpu: [x64]
     os: [openbsd]
 
+  '@esbuild/openbsd-x64@0.27.3':
+    resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.28.1':
+    resolution: {integrity: sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
   '@esbuild/openharmony-arm64@0.25.10':
     resolution: {integrity: sha512-AVTSBhTX8Y/Fz6OmIVBip9tJzZEUcY8WLh7I59+upa5/GPhh2/aM6bvOMQySspnCCHvFi79kMtdJS1w0DXAeag==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [openharmony]
 
+  '@esbuild/openharmony-arm64@0.27.3':
+    resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/openharmony-arm64@0.28.1':
+    resolution: {integrity: sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
   '@esbuild/sunos-x64@0.21.5':
     resolution: {integrity: sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==}
     engines: {node: '>=12'}
@@ -1044,6 +2040,18 @@ packages:
     cpu: [x64]
     os: [sunos]
 
+  '@esbuild/sunos-x64@0.27.3':
+    resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/sunos-x64@0.28.1':
+    resolution: {integrity: sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
   '@esbuild/win32-arm64@0.21.5':
     resolution: {integrity: sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==}
     engines: {node: '>=12'}
@@ -1056,6 +2064,18 @@ packages:
     cpu: [arm64]
     os: [win32]
 
+  '@esbuild/win32-arm64@0.27.3':
+    resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-arm64@0.28.1':
+    resolution: {integrity: sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
   '@esbuild/win32-ia32@0.21.5':
     resolution: {integrity: sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==}
     engines: {node: '>=12'}
@@ -1068,6 +2088,18 @@ packages:
     cpu: [ia32]
     os: [win32]
 
+  '@esbuild/win32-ia32@0.27.3':
+    resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.28.1':
+    resolution: {integrity: sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
   '@esbuild/win32-x64@0.21.5':
     resolution: {integrity: sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==}
     engines: {node: '>=12'}
@@ -1080,38 +2112,45 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@eventcatalog/generator-ai@1.2.0':
-    resolution: {integrity: sha512-66FxkeNnjn4J8E9igmdGHxsNpF8hQKNL2S+rtEb7H2SUBPKcFDBnBKaFb5y1bCPgq/iAx5mBVr9GRdpGeUOhgQ==}
+  '@esbuild/win32-x64@0.27.3':
+    resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.28.1':
+    resolution: {integrity: sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
 
   '@eventcatalog/license@0.0.7':
     resolution: {integrity: sha512-izSIn3Dfc6LTcPiA89EqZ4/l5WCitLxt0XVu2yilyaibMOioxW7ABRFZY8/Azocd6ULKseVA2lCcoeT35/GRcg==}
     engines: {node: '>=16.0.0'}
 
-  '@eventcatalog/linter@0.0.2':
-    resolution: {integrity: sha512-wfRkX62H8pvsj5m7drnPA8jxoAv3Hl3DKgFaooyAr2+evcjwiWqdcGKsXX1mOTfYs71AxkDYPpEqoiwBJ/Nu2Q==}
-    engines: {node: '>=16.0.0'}
-    hasBin: true
+  '@expressive-code/core@0.41.7':
+    resolution: {integrity: sha512-ck92uZYZ9Wba2zxkiZLsZGi9N54pMSAVdrI9uW3Oo9AtLglD5RmrdTwbYPCT2S/jC36JGB2i+pnQtBm/Ib2+dg==}
 
-  '@eventcatalog/sdk@2.9.2':
-    resolution: {integrity: sha512-gQJqO0yBFZfM7819Jj5oHGtF8tYKZ2lp76/mgo4pjgWID/Hg1Eb2ORTgUZX8FIbkXZfj3dJPHAh1Qm3qad+KMQ==}
+  '@expressive-code/core@0.44.0':
+    resolution: {integrity: sha512-xgiF2P6tYUbrhi3+x0S8xHZWT1t3Bvb3U91tAtRbLb9HLejLvYc5GZUqKICKLaUN4iSGhhNJu2fM/aH8e5yCMg==}
 
-  '@eventcatalog/visualizer@0.0.6':
-    resolution: {integrity: sha512-WjosTnIYMBgOjhHfZZhXxIOyVm+usoObaX8aJhOTwPnt2zv3I97V0ArWBAIqZhPJHfA9LPBpIQWQQy+fp37svA==}
-    peerDependencies:
-      react: '>=18.0.0'
-      react-dom: '>=18.0.0'
+  '@expressive-code/plugin-frames@0.41.7':
+    resolution: {integrity: sha512-diKtxjQw/979cTglRFaMCY/sR6hWF0kSMg8jsKLXaZBSfGS0I/Hoe7Qds3vVEgeoW+GHHQzMcwvgx/MOIXhrTA==}
+
+  '@expressive-code/plugin-frames@0.44.0':
+    resolution: {integrity: sha512-V6M6+zVc1GzqCvXkQHc2m5rcFOIVzJgMq5gnfrMnVf2gwtj/sg4H93c1f/mGeqHycubwkHFUDyParAOiGeDZeA==}
 
-  '@expressive-code/core@0.41.3':
-    resolution: {integrity: sha512-9qzohqU7O0+JwMEEgQhnBPOw5DtsQRBXhW++5fvEywsuX44vCGGof1SL5OvPElvNgaWZ4pFZAFSlkNOkGyLwSQ==}
+  '@expressive-code/plugin-shiki@0.41.7':
+    resolution: {integrity: sha512-DL605bLrUOgqTdZ0Ot5MlTaWzppRkzzqzeGEu7ODnHF39IkEBbFdsC7pbl3LbUQ1DFtnfx6rD54k/cdofbW6KQ==}
 
-  '@expressive-code/plugin-frames@0.41.3':
-    resolution: {integrity: sha512-rFQtmf/3N2CK3Cq/uERweMTYZnBu+CwxBdHuOftEmfA9iBE7gTVvwpbh82P9ZxkPLvc40UMhYt7uNuAZexycRQ==}
+  '@expressive-code/plugin-shiki@0.44.0':
+    resolution: {integrity: sha512-RZsdaqlbGqyAQKuoX4myQXxjmiE2l5KBpJ/gKPh62tCdIdpWyjbzVqSo8+5XsezZxkfi8AJ/J6EUaBTPROFX/Q==}
 
-  '@expressive-code/plugin-shiki@0.41.3':
-    resolution: {integrity: sha512-RlTARoopzhFJIOVHLGvuXJ8DCEme/hjV+ZnRJBIxzxsKVpGPW4Oshqg9xGhWTYdHstTsxO663s0cdBLzZj9TQA==}
+  '@expressive-code/plugin-text-markers@0.41.7':
+    resolution: {integrity: sha512-Ewpwuc5t6eFdZmWlFyeuy3e1PTQC0jFvw2Q+2bpcWXbOZhPLsT7+h8lsSIJxb5mS7wZko7cKyQ2RLYDyK6Fpmw==}
 
-  '@expressive-code/plugin-text-markers@0.41.3':
-    resolution: {integrity: sha512-SN8tkIzDpA0HLAscEYD2IVrfLiid6qEdE9QLlGVSxO1KEw7qYvjpbNBQjUjMr5/jvTJ7ys6zysU2vLPHE0sb2g==}
+  '@expressive-code/plugin-text-markers@0.44.0':
+    resolution: {integrity: sha512-0/m3A5b+lz2upyNq+wzZ1S69HRoJmyFs5LsR42lVZ9pmGRlBiSBYQpvqlji4DBj1+Riamxc0AvcCr5kuzOQeWA==}
 
   '@floating-ui/core@1.7.3':
     resolution: {integrity: sha512-sGnvb5dmrJaKEZ+LDIpguvdX3bDlEllmv4/ClQ9awcmCZrlx5jQyyMWFM5kBI+EyNOCDDiKk8il0zeuX3Zlg/w==}
@@ -1164,30 +2203,11 @@ packages:
     peerDependencies:
       react: '>= 16 || ^19.0.0-rc'
 
-  '@huggingface/jinja@0.5.1':
-    resolution: {integrity: sha512-yUZLld4lrM9iFxHCwFQ7D1HW2MWMwSbeB7WzWqFYDWK+rEb+WldkLdAJxUPOmgICMHZLzZGVcVjFh3w/YGubng==}
-    engines: {node: '>=18'}
-
-  '@huggingface/transformers@3.7.5':
-    resolution: {integrity: sha512-5jvrIwHyRXfOKVaGKYvUZM6ZjJKQXWeKzIOdKBE5pdzPSNzTwBNx5NdWcGElf4Ddv7Dl2mWsvJh+G5RnCUxMmA==}
-
-  '@hyperjump/browser@1.3.1':
-    resolution: {integrity: sha512-Le5XZUjnVqVjkgLYv6yyWgALat/0HpB1XaCPuCZ+GCFki9NvXloSZITIJ0H+wRW7mb9At1SxvohKBbNQbrr/cw==}
-    engines: {node: '>=18.0.0'}
-
-  '@hyperjump/json-pointer@1.1.1':
-    resolution: {integrity: sha512-M0T3s7TC2JepoWPMZQn1W6eYhFh06OXwpMqL+8c5wMVpvnCKNsPgpu9u7WyCI03xVQti8JAeAy4RzUa6SYlJLA==}
-
-  '@hyperjump/json-schema@1.16.3':
-    resolution: {integrity: sha512-Vgr6+q05/TDcxTKXFGJEtAs1UDXfisX6vtthQhO3W4r63cNH07TVGJUqgyj34LoHCL1CDsOFjH5fCgSxljfOrg==}
+  '@hono/node-server@1.19.9':
+    resolution: {integrity: sha512-vHL6w3ecZsky+8P5MD+eFfaGTyCeOHUIFYMGpQGbrBTSmNNoxv0if69rEZ5giu36weC5saFuznL411gRX7bJDw==}
+    engines: {node: '>=18.14.1'}
     peerDependencies:
-      '@hyperjump/browser': ^1.1.0
-
-  '@hyperjump/pact@1.4.0':
-    resolution: {integrity: sha512-01Q7VY6BcAkp9W31Fv+ciiZycxZHGlR2N6ba9BifgyclHYHdbaZgITo0U6QMhYRlem4k8pf8J31/tApxvqAz8A==}
-
-  '@hyperjump/uri@1.3.2':
-    resolution: {integrity: sha512-OFo5oxuSEz1ktF/LDdBTptlnPyZ66jywLO4fJRuAhnr7NGnsiL2CPoj1JRVaDqVy0nXvWNsC8O8Muw9DR++eEg==}
+      hono: ^4
 
   '@iconify-json/logos@1.2.9':
     resolution: {integrity: sha512-G6VCdFnwZcrT6Eveq3m43oJfLw/CX8plwFcE+2jgv3fiGB64pTmnU7Yd1MNZ/eA+/Re2iEDhuCfSNOWTHwwK8w==}
@@ -1202,22 +2222,16 @@ packages:
     resolution: {integrity: sha512-A5P/LfWGFSl6nsckYtjw9da+19jB8hkJ6ACTGcDfEJ0aE+l2n2El7dsVM7UVHZQ9s2lmYMWlrS21YLy2IR1LUw==}
     engines: {node: '>=18'}
 
-  '@img/sharp-darwin-arm64@0.33.5':
-    resolution: {integrity: sha512-UT4p+iz/2H4twwAoLCqfA9UH5pI6DggwKEGuaPy7nCVQ8ZsiY5PIcrRvD1DzuY3qYL07NtIQcWnBSY/heikIFQ==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
-    cpu: [arm64]
-    os: [darwin]
-
   '@img/sharp-darwin-arm64@0.34.4':
     resolution: {integrity: sha512-sitdlPzDVyvmINUdJle3TNHl+AG9QcwiAMsXmccqsCOMZNIdW2/7S26w0LyU8euiLVzFBL3dXPwVCq/ODnf2vA==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [arm64]
     os: [darwin]
 
-  '@img/sharp-darwin-x64@0.33.5':
-    resolution: {integrity: sha512-fyHac4jIc1ANYGRDxtiqelIbdWkIuQaI84Mv45KvGRRxSAa7o7d1ZKAOBaYbnepLC1WqxfpimdeWfvqqSGwR2Q==}
+  '@img/sharp-darwin-arm64@0.34.5':
+    resolution: {integrity: sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
-    cpu: [x64]
+    cpu: [arm64]
     os: [darwin]
 
   '@img/sharp-darwin-x64@0.34.4':
@@ -1226,9 +2240,10 @@ packages:
     cpu: [x64]
     os: [darwin]
 
-  '@img/sharp-libvips-darwin-arm64@1.0.4':
-    resolution: {integrity: sha512-XblONe153h0O2zuFfTAbQYAX2JhYmDHeWikp1LM9Hul9gVPjFY427k6dFEcOL72O01QxQsWi761svJ/ev9xEDg==}
-    cpu: [arm64]
+  '@img/sharp-darwin-x64@0.34.5':
+    resolution: {integrity: sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
     os: [darwin]
 
   '@img/sharp-libvips-darwin-arm64@1.2.3':
@@ -1236,9 +2251,9 @@ packages:
     cpu: [arm64]
     os: [darwin]
 
-  '@img/sharp-libvips-darwin-x64@1.0.4':
-    resolution: {integrity: sha512-xnGR8YuZYfJGmWPvmlunFaWJsb9T/AO2ykoP3Fz/0X5XV2aoYBPkX6xqCQvUTKKiLddarLaxpzNe+b1hjeWHAQ==}
-    cpu: [x64]
+  '@img/sharp-libvips-darwin-arm64@1.2.4':
+    resolution: {integrity: sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==}
+    cpu: [arm64]
     os: [darwin]
 
   '@img/sharp-libvips-darwin-x64@1.2.3':
@@ -1246,169 +2261,226 @@ packages:
     cpu: [x64]
     os: [darwin]
 
-  '@img/sharp-libvips-linux-arm64@1.0.4':
-    resolution: {integrity: sha512-9B+taZ8DlyyqzZQnoeIvDVR/2F4EbMepXMc/NdVbkzsJbzkUjhXv/70GQJ7tdLA4YJgNP25zukcxpX2/SueNrA==}
-    cpu: [arm64]
-    os: [linux]
+  '@img/sharp-libvips-darwin-x64@1.2.4':
+    resolution: {integrity: sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==}
+    cpu: [x64]
+    os: [darwin]
 
   '@img/sharp-libvips-linux-arm64@1.2.3':
     resolution: {integrity: sha512-I4RxkXU90cpufazhGPyVujYwfIm9Nk1QDEmiIsaPwdnm013F7RIceaCc87kAH+oUB1ezqEvC6ga4m7MSlqsJvQ==}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
-  '@img/sharp-libvips-linux-arm@1.0.5':
-    resolution: {integrity: sha512-gvcC4ACAOPRNATg/ov8/MnbxFDJqf/pDePbBnuBDcjsI8PssmjoKMAz4LtLaVi+OnSb5FK/yIOamqDwGmXW32g==}
-    cpu: [arm]
+  '@img/sharp-libvips-linux-arm64@1.2.4':
+    resolution: {integrity: sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==}
+    cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@img/sharp-libvips-linux-arm@1.2.3':
     resolution: {integrity: sha512-x1uE93lyP6wEwGvgAIV0gP6zmaL/a0tGzJs/BIDDG0zeBhMnuUPm7ptxGhUbcGs4okDJrk4nxgrmxpib9g6HpA==}
     cpu: [arm]
     os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-arm@1.2.4':
+    resolution: {integrity: sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
 
   '@img/sharp-libvips-linux-ppc64@1.2.3':
     resolution: {integrity: sha512-Y2T7IsQvJLMCBM+pmPbM3bKT/yYJvVtLJGfCs4Sp95SjvnFIjynbjzsa7dY1fRJX45FTSfDksbTp6AGWudiyCg==}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
 
-  '@img/sharp-libvips-linux-s390x@1.0.4':
-    resolution: {integrity: sha512-u7Wz6ntiSSgGSGcjZ55im6uvTrOxSIS8/dgoVMoiGE9I6JAfU50yH5BoDlYA1tcuGS7g/QNtetJnxA6QEsCVTA==}
-    cpu: [s390x]
+  '@img/sharp-libvips-linux-ppc64@1.2.4':
+    resolution: {integrity: sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==}
+    cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-riscv64@1.2.4':
+    resolution: {integrity: sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
 
   '@img/sharp-libvips-linux-s390x@1.2.3':
     resolution: {integrity: sha512-RgWrs/gVU7f+K7P+KeHFaBAJlNkD1nIZuVXdQv6S+fNA6syCcoboNjsV2Pou7zNlVdNQoQUpQTk8SWDHUA3y/w==}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
 
-  '@img/sharp-libvips-linux-x64@1.0.4':
-    resolution: {integrity: sha512-MmWmQ3iPFZr0Iev+BAgVMb3ZyC4KeFc3jFxnNbEPas60e1cIfevbtuyf9nDGIzOaW9PdnDciJm+wFFaTlj5xYw==}
-    cpu: [x64]
+  '@img/sharp-libvips-linux-s390x@1.2.4':
+    resolution: {integrity: sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==}
+    cpu: [s390x]
     os: [linux]
+    libc: [glibc]
 
   '@img/sharp-libvips-linux-x64@1.2.3':
     resolution: {integrity: sha512-3JU7LmR85K6bBiRzSUc/Ff9JBVIFVvq6bomKE0e63UXGeRw2HPVEjoJke1Yx+iU4rL7/7kUjES4dZ/81Qjhyxg==}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
-  '@img/sharp-libvips-linuxmusl-arm64@1.0.4':
-    resolution: {integrity: sha512-9Ti+BbTYDcsbp4wfYib8Ctm1ilkugkA/uscUn6UXK1ldpC1JjiXbLfFZtRlBhjPZ5o1NCLiDbg8fhUPKStHoTA==}
-    cpu: [arm64]
+  '@img/sharp-libvips-linux-x64@1.2.4':
+    resolution: {integrity: sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==}
+    cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@img/sharp-libvips-linuxmusl-arm64@1.2.3':
     resolution: {integrity: sha512-F9q83RZ8yaCwENw1GieztSfj5msz7GGykG/BA+MOUefvER69K/ubgFHNeSyUu64amHIYKGDs4sRCMzXVj8sEyw==}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
-  '@img/sharp-libvips-linuxmusl-x64@1.0.4':
-    resolution: {integrity: sha512-viYN1KX9m+/hGkJtvYYp+CCLgnJXwiQB39damAO7WMdKWlIhmYTfHjwSbQeUK/20vY154mwezd9HflVFM1wVSw==}
-    cpu: [x64]
+  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
+    resolution: {integrity: sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==}
+    cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@img/sharp-libvips-linuxmusl-x64@1.2.3':
     resolution: {integrity: sha512-U5PUY5jbc45ANM6tSJpsgqmBF/VsL6LnxJmIf11kB7J5DctHgqm0SkuXzVWtIY90GnJxKnC/JT251TDnk1fu/g==}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
-  '@img/sharp-linux-arm64@0.33.5':
-    resolution: {integrity: sha512-JMVv+AMRyGOHtO1RFBiJy/MBsgz0x4AWrT6QoEVVTyh1E39TrCUpTRI7mx9VksGX4awWASxqCYLCV4wBZHAYxA==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
-    cpu: [arm64]
+  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
+    resolution: {integrity: sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==}
+    cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@img/sharp-linux-arm64@0.34.4':
     resolution: {integrity: sha512-YXU1F/mN/Wu786tl72CyJjP/Ngl8mGHN1hST4BGl+hiW5jhCnV2uRVTNOcaYPs73NeT/H8Upm3y9582JVuZHrQ==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
-  '@img/sharp-linux-arm@0.33.5':
-    resolution: {integrity: sha512-JTS1eldqZbJxjvKaAkxhZmBqPRGmxgu+qFKSInv8moZ2AmT5Yib3EQ1c6gp493HvrvV8QgdOXdyaIBrhvFhBMQ==}
+  '@img/sharp-linux-arm64@0.34.5':
+    resolution: {integrity: sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
-    cpu: [arm]
+    cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@img/sharp-linux-arm@0.34.4':
     resolution: {integrity: sha512-Xyam4mlqM0KkTHYVSuc6wXRmM7LGN0P12li03jAnZ3EJWZqj83+hi8Y9UxZUbxsgsK1qOEwg7O0Bc0LjqQVtxA==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [arm]
     os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-arm@0.34.5':
+    resolution: {integrity: sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
 
   '@img/sharp-linux-ppc64@0.34.4':
     resolution: {integrity: sha512-F4PDtF4Cy8L8hXA2p3TO6s4aDt93v+LKmpcYFLAVdkkD3hSxZzee0rh6/+94FpAynsuMpLX5h+LRsSG3rIciUQ==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
 
-  '@img/sharp-linux-s390x@0.33.5':
-    resolution: {integrity: sha512-y/5PCd+mP4CA/sPDKl2961b+C9d+vPAveS33s6Z3zfASk2j5upL6fXVPZi7ztePZ5CuH+1kW8JtvxgbuXHRa4Q==}
+  '@img/sharp-linux-ppc64@0.34.5':
+    resolution: {integrity: sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
-    cpu: [s390x]
+    cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-riscv64@0.34.5':
+    resolution: {integrity: sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
 
   '@img/sharp-linux-s390x@0.34.4':
     resolution: {integrity: sha512-qVrZKE9Bsnzy+myf7lFKvng6bQzhNUAYcVORq2P7bDlvmF6u2sCmK2KyEQEBdYk+u3T01pVsPrkj943T1aJAsw==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
 
-  '@img/sharp-linux-x64@0.33.5':
-    resolution: {integrity: sha512-opC+Ok5pRNAzuvq1AG0ar+1owsu842/Ab+4qvU879ippJBHvyY5n2mxF1izXqkPYlGuP/M556uh53jRLJmzTWA==}
+  '@img/sharp-linux-s390x@0.34.5':
+    resolution: {integrity: sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
-    cpu: [x64]
+    cpu: [s390x]
     os: [linux]
+    libc: [glibc]
 
   '@img/sharp-linux-x64@0.34.4':
     resolution: {integrity: sha512-ZfGtcp2xS51iG79c6Vhw9CWqQC8l2Ot8dygxoDoIQPTat/Ov3qAa8qpxSrtAEAJW+UjTXc4yxCjNfxm4h6Xm2A==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
-  '@img/sharp-linuxmusl-arm64@0.33.5':
-    resolution: {integrity: sha512-XrHMZwGQGvJg2V/oRSUfSAfjfPxO+4DkiRh6p2AFjLQztWUuY/o8Mq0eMQVIY7HJ1CDQUJlxGGZRw1a5bqmd1g==}
+  '@img/sharp-linux-x64@0.34.5':
+    resolution: {integrity: sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
-    cpu: [arm64]
+    cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@img/sharp-linuxmusl-arm64@0.34.4':
     resolution: {integrity: sha512-8hDVvW9eu4yHWnjaOOR8kHVrew1iIX+MUgwxSuH2XyYeNRtLUe4VNioSqbNkB7ZYQJj9rUTT4PyRscyk2PXFKA==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
-  '@img/sharp-linuxmusl-x64@0.33.5':
-    resolution: {integrity: sha512-WT+d/cgqKkkKySYmqoZ8y3pxx7lx9vVejxW/W4DOFMYVSkErR+w7mf2u8m/y4+xHe7yY9DAXQMWQhpnMuFfScw==}
+  '@img/sharp-linuxmusl-arm64@0.34.5':
+    resolution: {integrity: sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
-    cpu: [x64]
+    cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@img/sharp-linuxmusl-x64@0.34.4':
     resolution: {integrity: sha512-lU0aA5L8QTlfKjpDCEFOZsTYGn3AEiO6db8W5aQDxj0nQkVrZWmN3ZP9sYKWJdtq3PWPhUNlqehWyXpYDcI9Sg==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
-  '@img/sharp-wasm32@0.33.5':
-    resolution: {integrity: sha512-ykUW4LVGaMcU9lu9thv85CbRMAwfeadCJHRsg2GmeRa/cJxsVY9Rbd57JcMxBkKHag5U/x7TSBpScF4U8ElVzg==}
+  '@img/sharp-linuxmusl-x64@0.34.5':
+    resolution: {integrity: sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
-    cpu: [wasm32]
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
 
   '@img/sharp-wasm32@0.34.4':
     resolution: {integrity: sha512-33QL6ZO/qpRyG7woB/HUALz28WnTMI2W1jgX3Nu2bypqLIKx/QKMILLJzJjI+SIbvXdG9fUnmrxR7vbi1sTBeA==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [wasm32]
 
+  '@img/sharp-wasm32@0.34.5':
+    resolution: {integrity: sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [wasm32]
+
   '@img/sharp-win32-arm64@0.34.4':
     resolution: {integrity: sha512-2Q250do/5WXTwxW3zjsEuMSv5sUU4Tq9VThWKlU2EYLm4MB7ZeMwF+SFJutldYODXF6jzc6YEOC+VfX0SZQPqA==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [arm64]
     os: [win32]
 
-  '@img/sharp-win32-ia32@0.33.5':
-    resolution: {integrity: sha512-T36PblLaTwuVJ/zw/LaH0PdZkRz5rd3SmMHX8GSmR7vtNSP5Z6bQkExdSK7xGWyxLw4sUknBuugTelgw2faBbQ==}
+  '@img/sharp-win32-arm64@0.34.5':
+    resolution: {integrity: sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
-    cpu: [ia32]
+    cpu: [arm64]
     os: [win32]
 
   '@img/sharp-win32-ia32@0.34.4':
@@ -1417,10 +2489,10 @@ packages:
     cpu: [ia32]
     os: [win32]
 
-  '@img/sharp-win32-x64@0.33.5':
-    resolution: {integrity: sha512-MpY/o8/8kj+EcnxwvrP4aTJSWw/aZ7JIGR4aBeZkZw5B7/Jn+tY9/VNwtcoGmdT7GfggGIU4kygOMSbYnOrAbg==}
+  '@img/sharp-win32-ia32@0.34.5':
+    resolution: {integrity: sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
-    cpu: [x64]
+    cpu: [ia32]
     os: [win32]
 
   '@img/sharp-win32-x64@0.34.4':
@@ -1429,6 +2501,12 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@img/sharp-win32-x64@0.34.5':
+    resolution: {integrity: sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [win32]
+
   '@inquirer/external-editor@1.0.2':
     resolution: {integrity: sha512-yy9cOoBnx58TlsPrIxauKIFQTiyH+0MK4e97y4sV9ERbI+zDxw7i2hxHLCIEGIE/8PPvDxGhgzIOTSOWcs6/MQ==}
     engines: {node: '>=18'}
@@ -1448,18 +2526,14 @@ packages:
     resolution: {integrity: sha512-yzMTt9lEb8Gv7zRioUilSglI0c0smZ9k5D65677DLWLtWJaXIS3CqcGyUFByYKlnUj6TkjLVs54fBl6+TiGQDQ==}
     engines: {node: 20 || >=22}
 
-  '@isaacs/brace-expansion@5.0.0':
-    resolution: {integrity: sha512-ZT55BDLV0yv0RBm2czMiZ+SqCGO7AvmOM3G/w2xhVPH+te0aKgFjmBvGlL1dH+ql2tgGO3MVrbb3jCKyvpgnxA==}
+  '@isaacs/brace-expansion@5.0.1':
+    resolution: {integrity: sha512-WMz71T1JS624nWj2n2fnYAuPovhv7EUhk69R6i9dsVyzxt5eM3bjwvgk9L+APE1TRscGysAVMANkB0jh0LQZrQ==}
     engines: {node: 20 || >=22}
 
   '@isaacs/cliui@8.0.2':
     resolution: {integrity: sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==}
     engines: {node: '>=12'}
 
-  '@isaacs/fs-minipass@4.0.1':
-    resolution: {integrity: sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w==}
-    engines: {node: '>=18.0.0'}
-
   '@jridgewell/gen-mapping@0.3.13':
     resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
 
@@ -1500,21 +2574,11 @@ packages:
   '@juggle/resize-observer@3.4.0':
     resolution: {integrity: sha512-dfLbk+PwWvFzSxwk3n5ySL0hfBog779o8h68wK/7/APo/7cgyWp5jcXockbxdk5kFRkbeXWm4Fbi9FrdN381sA==}
 
-  '@langchain/core@0.3.78':
-    resolution: {integrity: sha512-Nn0x9erQlK3zgtRU1Z8NUjLuyW0gzdclMsvLQ6wwLeDqV91pE+YKl6uQb+L2NUDs4F0N7c2Zncgz46HxrvPzuA==}
-    engines: {node: '>=18'}
-
-  '@langchain/openai@0.6.14':
-    resolution: {integrity: sha512-SM/xJOFDxT9NN/07fvhNB5dgAsIOQaLhmANxrRlSQ7Qs1zImMrzOvq+/5JP/ifpC/YxcgEnt4dblKVqvNU/C5A==}
-    engines: {node: '>=18'}
-    peerDependencies:
-      '@langchain/core': '>=0.3.68 <0.4.0'
+  '@kwsites/file-exists@1.1.1':
+    resolution: {integrity: sha512-m9/5YGR18lIwxSFDwfE3oA7bWuq9kdau6ugN4H2rJeyhFQZcG9AgSHkQtSD15a8WvTgfz9aikZMrKPHvbpqFiw==}
 
-  '@langchain/textsplitters@0.1.0':
-    resolution: {integrity: sha512-djI4uw9rlkAb5iMhtLED+xJebDdAG935AdP4eRTB02R7OB/act55Bj9wsskhZsvuyQRpO4O1wQOp85s6T6GWmw==}
-    engines: {node: '>=18'}
-    peerDependencies:
-      '@langchain/core': '>=0.2.21 <0.4.0'
+  '@kwsites/promise-deferred@1.1.1':
+    resolution: {integrity: sha512-GaHYm+c0O9MjZRu0ongGBRbinu8gVAMd2UZjji6jVmqKtZluZnptXGWhz1E8j8D2HJ3f/yMxKAUC0b+57wncIw==}
 
   '@lezer/common@1.2.3':
     resolution: {integrity: sha512-w7ojc8ejBqr2REPsWxJjrMFsA/ysDCFICn8zEOR9mrqzOu2amhITYuLD8ag6XZf0CFXDrhKqw7+tW8cX66NaDA==}
@@ -1560,8 +2624,53 @@ packages:
     peerDependencies:
       mermaid: ^11.0.2
 
-  '@mermaid-js/parser@0.6.3':
-    resolution: {integrity: sha512-lnjOhe7zyHjc+If7yT4zoedx2vo4sHaTmtkl1+or8BRTnCtDmcTpAjpzDSfCZrshM5bCoz0GyidzadJAH1xobA==}
+  '@mermaid-js/parser@1.1.0':
+    resolution: {integrity: sha512-gxK9ZX2+Fex5zu8LhRQoMeMPEHbc73UKZ0FQ54YrQtUxE1VVhMwzeNtKRPAu5aXks4FasbMe4xB4bWrmq6Jlxw==}
+
+  '@modelcontextprotocol/sdk@1.26.0':
+    resolution: {integrity: sha512-Y5RmPncpiDtTXDbLKswIJzTqu2hyBKxTNsgKqKclDbhIgg1wgtf1fRuvxgTnRfcnxtvvgbIEcqUOzZrJ6iSReg==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@cfworker/json-schema': ^4.1.1
+      zod: ^3.25 || ^4.0
+    peerDependenciesMeta:
+      '@cfworker/json-schema':
+        optional: true
+
+  '@monaco-editor/loader@1.7.0':
+    resolution: {integrity: sha512-gIwR1HrJrrx+vfyOhYmCZ0/JcWqG5kbfG7+d3f/C1LXk2EvzAbHSg3MQ5lO2sMlo9izoAZ04shohfKLVT6crVA==}
+
+  '@monaco-editor/react@4.7.0':
+    resolution: {integrity: sha512-cyzXQCtO47ydzxpQtCGSQGOC8Gk3ZUeBXFAxD+CWXYFo5OqZyZUonFl0DwUlTyAfRHntBfw2p3w4s9R6oe1eCA==}
+    peerDependencies:
+      monaco-editor: '>= 0.25.0 < 1'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@nanostores/persistent@1.3.3':
+    resolution: {integrity: sha512-+b4I8xrmjhKE3hQ9V7/b4Xa+MBMkM2P4Ulv33zFEF/+2Hucsb24vTjYiWR8R97y8YdRptmRKlL5Qwy0q1Jj5nQ==}
+    engines: {node: ^20.0.0 || >=22.0.0}
+    peerDependencies:
+      nanostores: ^0.9.0 || ^0.10.0 || ^0.11.0 || ^1.0.0
+
+  '@nanostores/react@1.0.0':
+    resolution: {integrity: sha512-eDduyNy+lbQJMg6XxZ/YssQqF6b4OXMFEZMYKPJCCmBevp1lg0g+4ZRi94qGHirMtsNfAWKNwsjOhC+q1gvC+A==}
+    engines: {node: ^20.0.0 || >=22.0.0}
+    peerDependencies:
+      nanostores: ^0.9.0 || ^0.10.0 || ^0.11.0 || ^1.0.0
+      react: '>=18.0.0'
+
+  '@napi-rs/wasm-runtime@1.1.5':
+    resolution: {integrity: sha512-AWPoBRJ9tsnVhor4sjO7rkni+7p+2IAEFj6cx06UgP10jkQHqay/36uRV/bFkgrh18D9vb4cr8Q0Pthskgzy+Q==}
+    peerDependencies:
+      '@emnapi/core': ^1.7.1
+      '@emnapi/runtime': ^1.7.1
+
+  '@napi-rs/wasm-runtime@1.1.6':
+    resolution: {integrity: sha512-ZLv/JdUfkvOy9eCnnBaGfiO+XimbjebAeO+MRQqD/B+FR1tnRN0tpKSJHRbE8sFfS6aqsXZ67TQjfwfsxULVbg==}
+    peerDependencies:
+      '@emnapi/core': ^1.7.1
+      '@emnapi/runtime': ^1.7.1
 
   '@nodelib/fs.scandir@2.1.5':
     resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==}
@@ -1585,36 +2694,77 @@ packages:
   '@oslojs/encoding@1.1.0':
     resolution: {integrity: sha512-70wQhgYmndg4GCPxPPxPGevRKqTIJ2Nh4OkiMWmDAVYsTQ+Ta7Sq+rPevXyXGdzr30/qZBnyOalCszoMxlyldQ==}
 
+  '@oxc-project/types@0.137.0':
+    resolution: {integrity: sha512-WT+Gb24i8hmvo85AIv2oEYouEXkRlKAlT9WaCa3TfLgNCN+GhrJOGZuIlMouAh38Qe4QOx26eUOVsq70qXrywA==}
+
   '@pagefind/darwin-arm64@1.4.0':
     resolution: {integrity: sha512-2vMqkbv3lbx1Awea90gTaBsvpzgRs7MuSgKDxW0m9oV1GPZCZbZBJg/qL83GIUEN2BFlY46dtUZi54pwH+/pTQ==}
     cpu: [arm64]
     os: [darwin]
 
+  '@pagefind/darwin-arm64@1.5.2':
+    resolution: {integrity: sha512-MXpI+7HsAdPkvJ0gk9xj9g541BCqBZOBbdwj9g6lB5LCj6kSV6nqDSjzcAJwvOsfu0fjwvC8hQU+ecfhp+MpiQ==}
+    cpu: [arm64]
+    os: [darwin]
+
   '@pagefind/darwin-x64@1.4.0':
     resolution: {integrity: sha512-e7JPIS6L9/cJfow+/IAqknsGqEPjJnVXGjpGm25bnq+NPdoD3c/7fAwr1OXkG4Ocjx6ZGSCijXEV4ryMcH2E3A==}
     cpu: [x64]
     os: [darwin]
 
+  '@pagefind/darwin-x64@1.5.2':
+    resolution: {integrity: sha512-IojxFWMEJe0RQ7PQ3KXQsPIImNsbpPYpoZ+QUDrL8fAl/O27IX+LVLs74/UzEZy5uA2LD8Nz1AiwKr72vrkZQw==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@pagefind/default-ui@1.4.0':
+    resolution: {integrity: sha512-wie82VWn3cnGEdIjh4YwNESyS1G6vRHwL6cNjy9CFgNnWW/PGRjsLq300xjVH5sfPFK3iK36UxvIBymtQIEiSQ==}
+
   '@pagefind/freebsd-x64@1.4.0':
     resolution: {integrity: sha512-WcJVypXSZ+9HpiqZjFXMUobfFfZZ6NzIYtkhQ9eOhZrQpeY5uQFqNWLCk7w9RkMUwBv1HAMDW3YJQl/8OqsV0Q==}
     cpu: [x64]
     os: [freebsd]
 
+  '@pagefind/freebsd-x64@1.5.2':
+    resolution: {integrity: sha512-7EVzo9+0w+2cbe671BtMj10UlNo83I+HrLVLfRxO731svHRJKUfJ/mo05gU14pe9PCfpKNQT8FS3Xc/oDN6pOA==}
+    cpu: [x64]
+    os: [freebsd]
+
   '@pagefind/linux-arm64@1.4.0':
     resolution: {integrity: sha512-PIt8dkqt4W06KGmQjONw7EZbhDF+uXI7i0XtRLN1vjCUxM9vGPdtJc2mUyVPevjomrGz5M86M8bqTr6cgDp1Uw==}
     cpu: [arm64]
     os: [linux]
 
+  '@pagefind/linux-arm64@1.5.2':
+    resolution: {integrity: sha512-Ovt9+K35sqzn8H3ZMXGwls4TD/wMJuvRtShHIsmUQREmaxjrDEX7gHckRCrwYJ4XE1H1p6HkLz3wukrAnsfXQw==}
+    cpu: [arm64]
+    os: [linux]
+
   '@pagefind/linux-x64@1.4.0':
     resolution: {integrity: sha512-z4oddcWwQ0UHrTHR8psLnVlz6USGJ/eOlDPTDYZ4cI8TK8PgwRUPQZp9D2iJPNIPcS6Qx/E4TebjuGJOyK8Mmg==}
     cpu: [x64]
     os: [linux]
 
+  '@pagefind/linux-x64@1.5.2':
+    resolution: {integrity: sha512-V+tFqHKXhQKq/WqPBD67AFy7scn1/aZID00ws4fSDd+1daSi5UHR9VVlRrOUYKxn3VuFQYRD7lYXdZK1WED1YA==}
+    cpu: [x64]
+    os: [linux]
+
+  '@pagefind/windows-arm64@1.5.2':
+    resolution: {integrity: sha512-hN9Nh90fNW61nNRCW9ZyQrAj/mD0eRvmJ8NlTUzkbuW8kIzGJUi3cxjFkEcMZ5h/8FsKWD/VcouZl4yo1F7B6g==}
+    cpu: [arm64]
+    os: [win32]
+
   '@pagefind/windows-x64@1.4.0':
     resolution: {integrity: sha512-NkT+YAdgS2FPCn8mIA9bQhiBs+xmniMGq1LFPDhcFn0+2yIUEiIG06t7bsZlhdjknEQRTSdT7YitP6fC5qwP0g==}
     cpu: [x64]
     os: [win32]
 
+  '@pagefind/windows-x64@1.5.2':
+    resolution: {integrity: sha512-Fa2Iyw7kaDRzGMfNYNUXNW2zbL5FQVDgSOcbDHdzBrDEdpqOqg8TcZ68F22ol6NJ9IGzvUdmeyZypLW5dyhqsg==}
+    cpu: [x64]
+    os: [win32]
+
   '@panva/hkdf@1.2.1':
     resolution: {integrity: sha512-6oclG6Y3PiDFcoyk8srjLfVKyMfVCKJ27JwNPViuXziFpmdz+MZnZN/aKY0JGXgYuO/VghU0jcOAZgWXZ1Dmrw==}
 
@@ -1647,36 +2797,42 @@ packages:
     engines: {node: '>= 10.0.0'}
     cpu: [arm]
     os: [linux]
+    libc: [glibc]
 
   '@parcel/watcher-linux-arm-musl@2.5.1':
     resolution: {integrity: sha512-6E+m/Mm1t1yhB8X412stiKFG3XykmgdIOqhjWj+VL8oHkKABfu/gjFj8DvLrYVHSBNC+/u5PeNrujiSQ1zwd1Q==}
     engines: {node: '>= 10.0.0'}
     cpu: [arm]
     os: [linux]
+    libc: [musl]
 
   '@parcel/watcher-linux-arm64-glibc@2.5.1':
     resolution: {integrity: sha512-LrGp+f02yU3BN9A+DGuY3v3bmnFUggAITBGriZHUREfNEzZh/GO06FF5u2kx8x+GBEUYfyTGamol4j3m9ANe8w==}
     engines: {node: '>= 10.0.0'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@parcel/watcher-linux-arm64-musl@2.5.1':
     resolution: {integrity: sha512-cFOjABi92pMYRXS7AcQv9/M1YuKRw8SZniCDw0ssQb/noPkRzA+HBDkwmyOJYp5wXcsTrhxO0zq1U11cK9jsFg==}
     engines: {node: '>= 10.0.0'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@parcel/watcher-linux-x64-glibc@2.5.1':
     resolution: {integrity: sha512-GcESn8NZySmfwlTsIur+49yDqSny2IhPeZfXunQi48DMugKeZ7uy1FX83pO0X22sHntJ4Ub+9k34XQCX+oHt2A==}
     engines: {node: '>= 10.0.0'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@parcel/watcher-linux-x64-musl@2.5.1':
     resolution: {integrity: sha512-n0E2EQbatQ3bXhcH2D1XIAANAcTZkQICBPVaxMeaCVBtOpBZpWJuf7LwyWPSBDITb7In8mqQgJ7gH8CILCURXg==}
     engines: {node: '>= 10.0.0'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@parcel/watcher-win32-arm64@2.5.1':
     resolution: {integrity: sha512-RFzklRvmc3PkjKjry3hLF9wD7ppR4AKcWNzH7kXR7GUe0Igb3Nz8fyPwtZCSquGrhU5HhUNDr/mKBqj7tqA2Vw==}
@@ -1700,17 +2856,21 @@ packages:
     resolution: {integrity: sha512-dfUnCxiN9H4ap84DvD2ubjw+3vUNpstxa0TneY/Paat8a3R4uQZDLSvWjmznAY/DoahqTHl9V46HF/Zs3F29pg==}
     engines: {node: '>= 10.0.0'}
 
+  '@phosphor-icons/core@2.1.1':
+    resolution: {integrity: sha512-v4ARvrip4qBCImOE5rmPUylOEK4iiED9ZyKjcvzuezqMaiRASCHKcRIuvvxL/twvLpkfnEODCOJp5dM4eZilxQ==}
+
+  '@pivanov/utils@0.0.2':
+    resolution: {integrity: sha512-q9CN0bFWxWgMY5hVVYyBgez1jGiLBa6I+LkG37ycylPhFvEGOOeaADGtUSu46CaZasPnlY8fCdVJZmrgKb1EPA==}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+
   '@pkgjs/parseargs@0.11.0':
     resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==}
     engines: {node: '>=14'}
 
-  '@playform/pipe@0.1.3':
-    resolution: {integrity: sha512-cjRcaj6b8XZMS+N51In78EuD9e0x0M3gYxi2g+qUGk1iya2uxcS+aSrXxfBUZueOjxADQwpyS4zLEhlbHCGcDA==}
-
-  '@playwright/test@1.56.0':
-    resolution: {integrity: sha512-Tzh95Twig7hUwwNe381/K3PggZBZblKUe2wv25oIpzWLr6Z0m4KgV1ZVIjnR6GM9ANEqjZD7XsZEa6JL/7YEgg==}
-    engines: {node: '>=18'}
-    hasBin: true
+  '@playform/pipe@0.1.4':
+    resolution: {integrity: sha512-SM3iJ5VHA61NsYMrtvk8DAZwkrpPtBCiJnfWjj1iX6Ke/hnHLqVjTmkXG087UMOa9Z+3J/zUoAkzf3Al6tiS8A==}
 
   '@pnpm/config.env-replace@1.1.0':
     resolution: {integrity: sha512-htyl8TWnKL7K/ESFa1oW2UB5lVDxuF5DpM7tBi6Hu2LNL3mWkIzNLG6N4zoCUP1lCKNxWy/3iu8mS8MvToGd6w==}
@@ -1724,8 +2884,17 @@ packages:
     resolution: {integrity: sha512-c83qWb22rNRuB0UaVCI0uRPNRr8Z0FWnEIvT47jiHAmOIUHbBOg5XvV7pM5x+rKn9HRpjxquDbXYSXr3fAKFcw==}
     engines: {node: '>=12'}
 
-  '@popperjs/core@2.11.8':
-    resolution: {integrity: sha512-P1st0aksCrn9sGZhp8GMYwBnQsbvAWsZAX44oXNNvLHGqAOcoVxmjZiohstwQ7SqKnbR47akdNi+uleWD8+g6A==}
+  '@preact/signals-core@1.13.0':
+    resolution: {integrity: sha512-slT6XeTCAbdql61GVLlGU4x7XHI7kCZV5Um5uhE4zLX4ApgiiXc0UYFvVOKq06xcovzp7p+61l68oPi563ARKg==}
+
+  '@preact/signals@1.3.4':
+    resolution: {integrity: sha512-TPMkStdT0QpSc8FpB63aOwXoSiZyIrPsP9Uj347KopdS6olZdAYeeird/5FZv/M1Yc1ge5qstub2o8VDbvkT4g==}
+    peerDependencies:
+      preact: 10.x
+
+  '@profoundlogic/hogan@3.0.4':
+    resolution: {integrity: sha512-pmNVGuooS30Mm7YbZd5T7E5zYVO6D5Ct91sn4T39mUvMUc3sCGridcnhAufL1/Bz2QzAtzEn0agNrdk3+5yWzw==}
+    hasBin: true
 
   '@protobufjs/aspromise@1.1.2':
     resolution: {integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==}
@@ -1909,6 +3078,19 @@ packages:
       '@types/react-dom':
         optional: true
 
+  '@radix-ui/react-popover@1.1.15':
+    resolution: {integrity: sha512-kr0X2+6Yy/vJzLYJUPCZEc8SfQcf+1COFoAqauJm74umQhta9M7lNJHP7QQS3vkvcGLQUbWpMzwrXYwrYztHKA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
   '@radix-ui/react-popper@1.2.8':
     resolution: {integrity: sha512-0NJQ4LFFUuWkE7Oxf0htBKS6zLkkjBH+hM1uk7Ng705ReR8m/uelduy1DBo0PyBXPKVnBA6YBlU94MBGXrSBCw==}
     peerDependencies:
@@ -2099,29 +3281,130 @@ packages:
       react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
       react-dom: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
 
-  '@react-stately/flags@3.1.2':
-    resolution: {integrity: sha512-2HjFcZx1MyQXoPqcBGALwWWmgFVUk2TuKVIQxCbRq7fPyWXIl6VHcakCLurdtYC2Iks7zizvz0Idv48MQ38DWg==}
+  '@react-stately/flags@3.1.2':
+    resolution: {integrity: sha512-2HjFcZx1MyQXoPqcBGALwWWmgFVUk2TuKVIQxCbRq7fPyWXIl6VHcakCLurdtYC2Iks7zizvz0Idv48MQ38DWg==}
+
+  '@react-stately/utils@3.10.8':
+    resolution: {integrity: sha512-SN3/h7SzRsusVQjQ4v10LaVsDc81jyyR0DD5HnsQitm/I5WDpaSr2nRHtyloPFU48jlql1XX/S04T2DLQM7Y3g==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@react-types/shared@3.32.1':
+    resolution: {integrity: sha512-famxyD5emrGGpFuUlgOP6fVW2h/ZaF405G5KDi3zPHzyjAWys/8W6NAVJtNbkCkhedmvL0xOhvt8feGXyXaw5w==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+
+  '@replit/codemirror-css-color-picker@6.3.0':
+    resolution: {integrity: sha512-19biDANghUm7Fz7L1SNMIhK48tagaWuCOHj4oPPxc7hxPGkTVY2lU/jVZ8tsbTKQPVG7BO2CBDzs7CBwb20t4A==}
+    peerDependencies:
+      '@codemirror/language': ^6.0.0
+      '@codemirror/state': ^6.0.0
+      '@codemirror/view': ^6.0.0
+
+  '@rolldown/binding-android-arm64@1.1.3':
+    resolution: {integrity: sha512-DT6Z3PhvioeHMvxo+xHc3KtqggrI7CCTXCmC2h/5zUlp5jVitv7XEy+9q5/7v8IolhlioawpMo8Kg0EEBy7J0g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@rolldown/binding-darwin-arm64@1.1.3':
+    resolution: {integrity: sha512-0NwgwsjM7LrsuVnXMK3koTpagBNOhloc/BNjKqZjv4V5zI5r13qx69uVhRx+o5Z0yy4Hzq+lpy7TAgUG/ocvrw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-x64@1.1.3':
+    resolution: {integrity: sha512-YtiBp4disu6V560loT6PjMdiRaWmVvDNrUunAalbiFx2ggeJwxdAsgZMcoGP17uyAsTwAj5V1niksxlHnVQ1Sw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rolldown/binding-freebsd-x64@1.1.3':
+    resolution: {integrity: sha512-yD3EkEdXk2LypPxnf/kSZHirarsI8gcPzc62SukhR9VJTyvV+F9Q/GxWNuCojc7sXyuVC4DxRGhdDK4X8VSsbw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.1.3':
+    resolution: {integrity: sha512-c+8vieQbsD7HNAHKIA34w0GJ9FedFFuJGD+7E6vz7Q3uqAIugL5p45fhlsj4UaAsHpcmlqugBWMhA0/j7o0sIg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm64-gnu@1.1.3':
+    resolution: {integrity: sha512-50jD0uUwLvur7Zz9LHz17kaAdTPjn5wN93hEgjvmYFRZwiR7ZJYovTd5ipyWJDAnXKvZ+wgc+/Ika6dwSF5OcA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-arm64-musl@1.1.3':
+    resolution: {integrity: sha512-BO9+oPL8K9poZJBfYPsXNtYjPE5uM3qeehT3aFcW4LITOl+iSqhp0abzjR2nWBUNjIZeKXjAEWBZ64WjNoHd6w==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-linux-ppc64-gnu@1.1.3':
+    resolution: {integrity: sha512-f3VpLB1vQ0Eo6ecr/6cekLnvYMFF4YBFoVGkfkvPLq1bAkbAwHYQPZKoAmG6OJyTcxxoC+AvezGx/S1obNC0Mw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-s390x-gnu@1.1.3':
+    resolution: {integrity: sha512-AmurZ26Pqx/RI9N1gzEOCklkKXl927yjfXWUUS0O7Puh8ARM/Ob8qfrD3qnWksScdw6cSrW5PSHE9DyLu7+PtA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-gnu@1.1.3':
+    resolution: {integrity: sha512-JJpqs8bRGITDOdbkNKnlojzBabbOHrqjSvDr0IVsZObE1lBcPjxItUEY9eWIDbxaJ3cGrXPWGfGkIxFijg/URg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@rolldown/binding-linux-x64-musl@1.1.3':
+    resolution: {integrity: sha512-rSJcdjPxzA/by/6/rYs+v+bXU7UjvnbUWz8MJb6kh6+knqB1dCrtHg0uu7C/4haqJvqdkYHQ5IGn+tCH9GLW/g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@rolldown/binding-openharmony-arm64@1.1.3':
+    resolution: {integrity: sha512-hQ3/PYkDJICgevvyNcVrihVeqq7k1Pp3VZ9lY+dauAYUJKO+auqApvANhvR1An9BhmqYKvW2Mu1F9u4DXSMLxQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
 
-  '@react-stately/utils@3.10.8':
-    resolution: {integrity: sha512-SN3/h7SzRsusVQjQ4v10LaVsDc81jyyR0DD5HnsQitm/I5WDpaSr2nRHtyloPFU48jlql1XX/S04T2DLQM7Y3g==}
-    peerDependencies:
-      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+  '@rolldown/binding-wasm32-wasi@1.1.3':
+    resolution: {integrity: sha512-Elcv/BtML9lXrV6JuKITc/grN2kYV9gjsQpW8Jfw4ioK0TOkjBjye0nnyqQNy9STNaI20lXNaQBRrD5gSgR0Yg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [wasm32]
 
-  '@react-types/shared@3.32.1':
-    resolution: {integrity: sha512-famxyD5emrGGpFuUlgOP6fVW2h/ZaF405G5KDi3zPHzyjAWys/8W6NAVJtNbkCkhedmvL0xOhvt8feGXyXaw5w==}
-    peerDependencies:
-      react: ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1
+  '@rolldown/binding-win32-arm64-msvc@1.1.3':
+    resolution: {integrity: sha512-2DrEfhluH9yhiaFApmsjsjwrSYbNcY1oFTzYSP1a535jDbV98zCFanA/96TBUd0iDFcxGmw9QRExwGCXz3U+/g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
 
-  '@replit/codemirror-css-color-picker@6.3.0':
-    resolution: {integrity: sha512-19biDANghUm7Fz7L1SNMIhK48tagaWuCOHj4oPPxc7hxPGkTVY2lU/jVZ8tsbTKQPVG7BO2CBDzs7CBwb20t4A==}
-    peerDependencies:
-      '@codemirror/language': ^6.0.0
-      '@codemirror/state': ^6.0.0
-      '@codemirror/view': ^6.0.0
+  '@rolldown/binding-win32-x64-msvc@1.1.3':
+    resolution: {integrity: sha512-OL4OMk7UPXOeVGGd3qo5zJyPIljf4AFgk5QAkPPS+OoLuOOozhuaQGC18MxVTnw/06q93gShAJzlwnSCY9YtqA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
 
   '@rolldown/pluginutils@1.0.0-beta.27':
     resolution: {integrity: sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA==}
 
+  '@rolldown/pluginutils@1.0.0-rc.3':
+    resolution: {integrity: sha512-eybk3TjzzzV97Dlj5c+XrBFW57eTNhzod66y9HrBlzJ6NsCrWCp/2kaPS3K9wJmurBC0Tdw4yPjXKZqlznim3Q==}
+
+  '@rolldown/pluginutils@1.0.1':
+    resolution: {integrity: sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==}
+
   '@rollup/pluginutils@5.3.0':
     resolution: {integrity: sha512-5EdhGZtnu3V88ces7s53hhfK5KSASnJZv8Lulpc04cWO3REESroJXg73DFsOmgbU2BhwV0E20bu2IDZb3VKW4Q==}
     engines: {node: '>=14.0.0'}
@@ -2165,56 +3448,67 @@ packages:
     resolution: {integrity: sha512-xRiOu9Of1FZ4SxVbB0iEDXc4ddIcjCv2aj03dmW8UrZIW7aIQ9jVJdLBIhxBI+MaTnGAKyvMwPwQnoOEvP7FgQ==}
     cpu: [arm]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-arm-musleabihf@4.52.4':
     resolution: {integrity: sha512-FbhM2p9TJAmEIEhIgzR4soUcsW49e9veAQCziwbR+XWB2zqJ12b4i/+hel9yLiD8pLncDH4fKIPIbt5238341Q==}
     cpu: [arm]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-arm64-gnu@4.52.4':
     resolution: {integrity: sha512-4n4gVwhPHR9q/g8lKCyz0yuaD0MvDf7dV4f9tHt0C73Mp8h38UCtSCSE6R9iBlTbXlmA8CjpsZoujhszefqueg==}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-arm64-musl@4.52.4':
     resolution: {integrity: sha512-u0n17nGA0nvi/11gcZKsjkLj1QIpAuPFQbR48Subo7SmZJnGxDpspyw2kbpuoQnyK+9pwf3pAoEXerJs/8Mi9g==}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-loong64-gnu@4.52.4':
     resolution: {integrity: sha512-0G2c2lpYtbTuXo8KEJkDkClE/+/2AFPdPAbmaHoE870foRFs4pBrDehilMcrSScrN/fB/1HTaWO4bqw+ewBzMQ==}
     cpu: [loong64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-ppc64-gnu@4.52.4':
     resolution: {integrity: sha512-teSACug1GyZHmPDv14VNbvZFX779UqWTsd7KtTM9JIZRDI5NUwYSIS30kzI8m06gOPB//jtpqlhmraQ68b5X2g==}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-gnu@4.52.4':
     resolution: {integrity: sha512-/MOEW3aHjjs1p4Pw1Xk4+3egRevx8Ji9N6HUIA1Ifh8Q+cg9dremvFCUbOX2Zebz80BwJIgCBUemjqhU5XI5Eg==}
     cpu: [riscv64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-musl@4.52.4':
     resolution: {integrity: sha512-1HHmsRyh845QDpEWzOFtMCph5Ts+9+yllCrREuBR/vg2RogAQGGBRC8lDPrPOMnrdOJ+mt1WLMOC2Kao/UwcvA==}
     cpu: [riscv64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-s390x-gnu@4.52.4':
     resolution: {integrity: sha512-seoeZp4L/6D1MUyjWkOMRU6/iLmCU2EjbMTyAG4oIOs1/I82Y5lTeaxW0KBfkUdHAWN7j25bpkt0rjnOgAcQcA==}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-x64-gnu@4.52.4':
     resolution: {integrity: sha512-Wi6AXf0k0L7E2gteNsNHUs7UMwCIhsCTs6+tqQ5GPwVRWMaflqGec4Sd8n6+FNFDw9vGcReqk2KzBDhCa1DLYg==}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-x64-musl@4.52.4':
     resolution: {integrity: sha512-dtBZYjDmCQ9hW+WgEkaffvRRCKm767wWhxsFW3Lw86VXz/uJRuD438/XvbZT//B96Vs8oTA8Q4A0AfHbrxP9zw==}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-openharmony-arm64@4.52.4':
     resolution: {integrity: sha512-1ox+GqgRWqaB1RnyZXL8PD6E5f7YyRUJYnCqKpNzxzP0TkaUh112NDrR9Tt+C8rJ4x5G9Mk8PQR3o7Ku2RKqKA==}
@@ -2241,130 +3535,160 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@scalar/api-client@2.2.62':
-    resolution: {integrity: sha512-ZjSZ0S1nBLUnqphw/QPfMTLMdHV7OtLIOWj3eGsaxHDftD6pomi47swWiz1rySIkMFyK8En55cIKL/vYPzlL5w==}
-    engines: {node: '>=18'}
+  '@scalar/agent-chat@0.12.0':
+    resolution: {integrity: sha512-EwSO7uXCFmyVezfCSJFBuvjnSCb7sxTHawFWjkDmLkIUnJjCc4DaWSP9+UdvK4rvh44v+oLLPXVKMSW6/Tj0Jw==}
+    engines: {node: '>=22'}
 
-  '@scalar/api-reference-react@0.4.42':
-    resolution: {integrity: sha512-3dWDgOdduFv4p208jc55EHHRZ65BgPwZ57En5/jmCZ4MITHovl0tZZp+oE143OFOxK1WlTOwA3FeJNyQJKN2UQ==}
-    engines: {node: '>=18'}
+  '@scalar/api-client@3.8.0':
+    resolution: {integrity: sha512-1SwesVjEe7BrIQgQQlHN1K4tBnP3GoJTfnCEUmPh3QSQCWTeT2X4ZMm4FpwmZGurbXWjc8u4AJwmLRNdWsFrbQ==}
+    engines: {node: '>=22'}
+
+  '@scalar/api-reference-react@0.9.36':
+    resolution: {integrity: sha512-oHfVIGtOOngi3YTt0kLkVFeuVsTQ52AtY5ty6QdGSiH5nsxwfFTDA84hKyk3vGbhvQcyGyOt98AidVA91CBdFw==}
+    engines: {node: '>=22'}
     peerDependencies:
       react: ^18.0.0 || ^19.0.0
 
-  '@scalar/api-reference@1.26.2':
-    resolution: {integrity: sha512-Q8M9peeWd7rmsvWv8NUdwcCtCyj8my5GFPZXJesZCtVtFswTNMK4DcEz15wzgNhGhA8EDKYyEJw+9R3fIvbOCg==}
-    engines: {node: '>=18'}
+  '@scalar/api-reference@1.57.0':
+    resolution: {integrity: sha512-y/nBlBgUDDI+hW8lKFjG5xIynwRAxvk0GCgpO4HMJybEPCPV6u4WiYwJmX4zQtuKW4XvhVxX179wQJmhB1xWiQ==}
+    engines: {node: '>=22'}
 
-  '@scalar/code-highlight@0.0.24':
-    resolution: {integrity: sha512-xQFt5yVbNr3+7dmMsQrV/yc0Zi9rMV9E9rSvzroD0TQvwi39rAiMmdQzwLXT/S9B40foIJiP/3y6FmxDEf3DoA==}
-    engines: {node: '>=18'}
+  '@scalar/code-highlight@0.3.4':
+    resolution: {integrity: sha512-gGr3D8bfInwZDHsxamYIaG72Wr+kRNX8d4zcOflAfQJ0ZfvqoVbYhhkiSd6K+DLySItK9lWl/cgjJdtKWlT2ig==}
+    engines: {node: '>=22'}
 
-  '@scalar/components@0.13.33':
-    resolution: {integrity: sha512-aoXdwWHf3SZOb/A25XSTWJDniK2g3bvUVt1NSS1PJX60OKaVlrilXmSxWpuYTqRuYGCpxX1yfgGcwwlipSAIkQ==}
-    engines: {node: '>=18'}
+  '@scalar/components@0.24.4':
+    resolution: {integrity: sha512-fI2birQB/wYC+djTOtLh3HqM9FA1Tgw7neVD+EHKLka40AlgjCJ7gXlEp+NRo3UrLxgD+y7gtPJtBTpxMVfySg==}
+    engines: {node: '>=22'}
 
-  '@scalar/draggable@0.1.11':
-    resolution: {integrity: sha512-EQW9N1+mDORhsbjdtCI3XDvmUKsuKw1uf6r3kT1Mm2zQKT+rWwA0ChsAkEN6OG62C0YumMuXpH71h1seAWptxw==}
-    engines: {node: '>=18'}
+  '@scalar/helpers@0.8.0':
+    resolution: {integrity: sha512-gmOC6VravNB9VDl6wnt/GOj4K/hn48tj5bpW4AM4MhH8Ubil6uu7g1DSoKHwltu8Ks79KEtR6JmOrROi9R7jaQ==}
+    engines: {node: '>=22'}
 
-  '@scalar/icons@0.1.3':
-    resolution: {integrity: sha512-Bl46u7WsJ7NYjW1Fva7SMvw9c/92pGBP8B68tvDc+QevQ04DVNxw6+ny1NU/PnLtpuu1rUpPdtSCAkV1OdQGZQ==}
-    engines: {node: '>=18'}
+  '@scalar/icons@0.7.2':
+    resolution: {integrity: sha512-21L2y/D6oU7wZHHa9i6FK98cZ+XH4HX9+e69uNpvlp4awRUpz6ifNHOLlxI607bq+Yz4G313gnV0uyUHwZ/pig==}
+    engines: {node: '>=22'}
 
-  '@scalar/import@0.2.36':
-    resolution: {integrity: sha512-Rm7b//BP6LnL26G8zW2R7G3Wy1uAiqs5NEx1yojZTL6KZQD4/5D11gri3ZBqlOquziiklia62V/7Dtd3Ik3Ktw==}
-    engines: {node: '>=18'}
+  '@scalar/json-magic@0.12.14':
+    resolution: {integrity: sha512-dWrCy3ew1r7OQ1pu2r4ZjiKEVy0yVd66kXdmsl41bteOG2F2I2IBlPjmPV6p8ckjImQHxtNBIntFaQfNrdBhJg==}
+    engines: {node: '>=22'}
 
-  '@scalar/oas-utils@0.2.116':
-    resolution: {integrity: sha512-vIubpbabI6UxXKxJ9XBMpypIH7phEkMg99LrYoqy503kQlRwmt2SaG7f9yUr80ju21cYFmtmB1p0z2EdP2tsFQ==}
-    engines: {node: '>=18'}
+  '@scalar/oas-utils@0.17.0':
+    resolution: {integrity: sha512-TunZsVQbBn5EHqbxsqvYHlQZbJy++tp742QxeDZtmhabPwj47h5VqEHtDTuSrVL1p1nSRCirtnZRizQkkmJauQ==}
+    engines: {node: '>=22'}
 
-  '@scalar/object-utils@1.1.13':
-    resolution: {integrity: sha512-311eTykIXgOtjCs4VTELj9UMT97jHTWc5qkGNoIzZ5nxjCcvOVe7kDQobIkE8dGT+ybOgHz5qly02Eu7nVHeZQ==}
-    engines: {node: '>=18'}
+  '@scalar/openapi-types@0.8.0':
+    resolution: {integrity: sha512-WmaxVSfvY5K/TwcG2B2TU1WOe1As1uc2s7myswtP6dBlcjU3hM08SApxv/jmyGaCE8t4gO5BBhmHY4pDUfmr2g==}
+    engines: {node: '>=22'}
 
-  '@scalar/openapi-parser@0.10.10':
-    resolution: {integrity: sha512-6MSgvpNKu/anZy96dn8tXQZo1PuDCoeB4m2ZLLDS4vC2zaTnuNBvvQHx+gjwXNKWhTbIVy8bQpYBzlMAYnFNcQ==}
-    engines: {node: '>=18'}
+  '@scalar/openapi-upgrader@0.2.7':
+    resolution: {integrity: sha512-sC/uLQOivfX+Oef2QhUpgmERL7KZc1z+hiYkcwZQaUyVOHh5e6OscW0skfzbxKPyJfQ6Ocv0Iom9wMToCGaAPw==}
+    engines: {node: '>=22'}
 
-  '@scalar/openapi-types@0.1.9':
-    resolution: {integrity: sha512-HQQudOSQBU7ewzfnBW9LhDmBE2XOJgSfwrh5PlUB7zJup/kaRkBGNgV2wMjNz9Af/uztiU/xNrO179FysmUT+g==}
-    engines: {node: '>=18'}
+  '@scalar/schemas@0.2.0':
+    resolution: {integrity: sha512-FOpNecNoEKo8SogHEsdWlVRN4Q4PH3dzuOBWMA5tGt1xLZu5iFnPG2X/h6+Z/mOR34c7iW+hiKTqdUZoDgT9CA==}
+    engines: {node: '>=22'}
 
-  '@scalar/postman-to-openapi@0.1.39':
-    resolution: {integrity: sha512-+NGE3WKN4v7iAQ31K/yHEF4j4Fa46e3w/obbjn+LeOlSk/gc2KI/RIuSXY85UjpVQetxGhISDDMBkJPfQ/kX9A==}
-    engines: {node: '>=18'}
+  '@scalar/sidebar@0.9.13':
+    resolution: {integrity: sha512-R9u+H6tvwgzbOoE4RpdA7xwGwHPY96Kaa5hyGDy74drLFNWo9v0ufGZIClbsmIcJhk2z12fLUxJ7jKcC3u/lag==}
+    engines: {node: '>=22'}
 
-  '@scalar/snippetz@0.2.16':
-    resolution: {integrity: sha512-xtIY4kvV619IF2uXg6fDw7emtXwuJeWzLunGAaUTIOwNRw5mGSKqJnLcSnIiSdH54YmN8D2CtdJRo2VxPP9/Wg==}
-    engines: {node: '>=18'}
+  '@scalar/snippetz@0.9.8':
+    resolution: {integrity: sha512-LQyZ7xJd47d0vOtww1yk9oheuSI7yEXYdtisxkfOBC/QTayjv+dIWZfQ0nmv6fYYIeCEcORq7LkFVXJtMJ3yXw==}
+    engines: {node: '>=22'}
 
-  '@scalar/themes@0.9.75':
-    resolution: {integrity: sha512-VLn3evIO0tp20d9S34mmQBdP6ePKiUE7popD6CMndztBXQglpf0O/tj9yxSgH4zSYVFVE63R82UkUQ4gt9Fbkg==}
-    engines: {node: '>=18'}
+  '@scalar/themes@0.15.5':
+    resolution: {integrity: sha512-ku8MPNBEXigx/ES0Wm7Mf8Ns+QMePEcMHraDZoA5Ab/UO97yTZIrvuo/gy143QB+NftnQ83vgeDYcCRi6I95tQ==}
+    engines: {node: '>=22'}
 
-  '@scalar/types@0.0.40':
-    resolution: {integrity: sha512-0J6o+yZzgZEvl3KhvLTAGiXXyrCeEPKvs9gUWQDf1Rb5NfFxF0lA10ougCQCwVJIguWNEzZfOUiSoAFzGy2EqQ==}
-    engines: {node: '>=18'}
+  '@scalar/typebox@0.1.3':
+    resolution: {integrity: sha512-lU055AUccECZMIfGA0z/C1StYmboAYIPJLDFBzOO81yXBi35Pxdq+I4fWX6iUZ8qcoHneiLGk9jAUM1rA93iEg==}
 
-  '@scalar/use-codemirror@0.11.78':
-    resolution: {integrity: sha512-byxJSyHzlGnrwoRjvKQAx9ouenBN9qldgWXJ4AzklrH9VxJEIO+f0aErauFBzhL1idIQ2Akfm30Vq4vtiCAJ6w==}
-    engines: {node: '>=18'}
+  '@scalar/types@0.11.0':
+    resolution: {integrity: sha512-TGZR8sys1jRlaWxLYfBo8y6D1W4UClYuDmkJ6Hmsb7oNuqokEAAK+AVYIzascVdBmaly0D1fqoqK7CzuGYHgyg==}
+    engines: {node: '>=22'}
 
-  '@scalar/use-hooks@0.1.29':
-    resolution: {integrity: sha512-VS2fKw8apLpmSGkrNUVaKVzjB8wNUCXL0+Y/vN4rmkkMRMATJLMhPHlFEjNL0tNwz2z7Z+EKm4jiRzMwy2s8bg==}
-    engines: {node: '>=18'}
+  '@scalar/use-codemirror@0.14.11':
+    resolution: {integrity: sha512-5wtC4pUjzhy72j3aAueJg+fh9KflevJvXMn0YscsxiDTvqwIzeZcHe1N9VNtvzDXgLblEeBT6D0+Vs+boyExxg==}
+    engines: {node: '>=22'}
 
-  '@scalar/use-toasts@0.7.9':
-    resolution: {integrity: sha512-EcUDJY8VozLS9sfoQKvvipStQJ9RuH/nKOzf0BBr+mZDmumi1WFZ1iIJnHVXIN3iSLcSAr5ej6rOqa6jIv4bCQ==}
-    engines: {node: '>=18'}
+  '@scalar/use-hooks@0.4.5':
+    resolution: {integrity: sha512-QTFC1qndQK7R4OWm1Mco/Hww7WwSp9F6we3cA4iCpoVKu1HvRBRnO+BHIMZkP1eyq1A4HeSrujTH2MIRPD+wDQ==}
+    engines: {node: '>=22'}
 
-  '@scalar/use-tooltip@1.0.6':
-    resolution: {integrity: sha512-f0gadIaUnILfi9qYAk7g+fNTsvLGXnam8oOUTxovavC1ocYuGTEykdz3g2MTqnAqRS8OkAB64h9mHf0FBfg6mg==}
-    engines: {node: '>=18'}
-    deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.
+  '@scalar/use-toasts@0.10.2':
+    resolution: {integrity: sha512-1iHQFbDXv0YQRp13aa63S5EcTJ5K8T0ocnLxk+nziloPrLjKt6jdRt6vOHsLSv5sm9kFKcVKNQTQgialmKCOGA==}
+    engines: {node: '>=22'}
+
+  '@scalar/validation@0.5.0':
+    resolution: {integrity: sha512-48CS1B0C7im57RQCHhS0GKt+qDLxB34IX8rO91jZj9D+Y/OosQZG3Gy57gJdHqZoD7l0sPUZtF8tVYry3BxRtw==}
+    engines: {node: '>=20'}
 
-  '@shikijs/core@3.13.0':
-    resolution: {integrity: sha512-3P8rGsg2Eh2qIHekwuQjzWhKI4jV97PhvYjYUzGqjvJfqdQPz+nMlfWahU24GZAyW1FxFI1sYjyhfh5CoLmIUA==}
+  '@scalar/workspace-store@0.51.0':
+    resolution: {integrity: sha512-+eKUdPrDzUFSEmDd5gdEf1XUEPVPDH4r9iySW8T2tHF7S7ostpFwszDBhkl8qiQjxpw8DYs/aMaeSCl33/7k6w==}
+    engines: {node: '>=22'}
 
-  '@shikijs/core@3.15.0':
-    resolution: {integrity: sha512-8TOG6yG557q+fMsSVa8nkEDOZNTSxjbbR8l6lF2gyr6Np+jrPlslqDxQkN6rMXCECQ3isNPZAGszAfYoJOPGlg==}
+  '@shikijs/core@3.21.0':
+    resolution: {integrity: sha512-AXSQu/2n1UIQekY8euBJlvFYZIw0PHY63jUzGbrOma4wPxzznJXTXkri+QcHeBNaFxiiOljKxxJkVSoB3PjbyA==}
 
-  '@shikijs/engine-javascript@3.13.0':
-    resolution: {integrity: sha512-Ty7xv32XCp8u0eQt8rItpMs6rU9Ki6LJ1dQOW3V/56PKDcpvfHPnYFbsx5FFUP2Yim34m/UkazidamMNVR4vKg==}
+  '@shikijs/core@4.0.2':
+    resolution: {integrity: sha512-hxT0YF4ExEqB8G/qFdtJvpmHXBYJ2lWW7qTHDarVkIudPFE6iCIrqdgWxGn5s+ppkGXI0aEGlibI0PAyzP3zlw==}
+    engines: {node: '>=20'}
+
+  '@shikijs/engine-javascript@3.21.0':
+    resolution: {integrity: sha512-ATwv86xlbmfD9n9gKRiwuPpWgPENAWCLwYCGz9ugTJlsO2kOzhOkvoyV/UD+tJ0uT7YRyD530x6ugNSffmvIiQ==}
+
+  '@shikijs/engine-javascript@4.0.2':
+    resolution: {integrity: sha512-7PW0Nm49DcoUIQEXlJhNNBHyoGMjalRETTCcjMqEaMoJRLljy1Bi/EGV3/qLBgLKQejdspiiYuHGQW6dX94Nag==}
+    engines: {node: '>=20'}
 
-  '@shikijs/engine-javascript@3.15.0':
-    resolution: {integrity: sha512-ZedbOFpopibdLmvTz2sJPJgns8Xvyabe2QbmqMTz07kt1pTzfEvKZc5IqPVO/XFiEbbNyaOpjPBkkr1vlwS+qg==}
+  '@shikijs/engine-oniguruma@3.21.0':
+    resolution: {integrity: sha512-OYknTCct6qiwpQDqDdf3iedRdzj6hFlOPv5hMvI+hkWfCKs5mlJ4TXziBG9nyabLwGulrUjHiCq3xCspSzErYQ==}
 
-  '@shikijs/engine-oniguruma@3.13.0':
-    resolution: {integrity: sha512-O42rBGr4UDSlhT2ZFMxqM7QzIU+IcpoTMzb3W7AlziI1ZF7R8eS2M0yt5Ry35nnnTX/LTLXFPUjRFCIW+Operg==}
+  '@shikijs/engine-oniguruma@4.0.2':
+    resolution: {integrity: sha512-UpCB9Y2sUKlS9z8juFSKz7ZtysmeXCgnRF0dlhXBkmQnek7lAToPte8DkxmEYGNTMii72zU/lyXiCB6StuZeJg==}
+    engines: {node: '>=20'}
 
-  '@shikijs/engine-oniguruma@3.15.0':
-    resolution: {integrity: sha512-HnqFsV11skAHvOArMZdLBZZApRSYS4LSztk2K3016Y9VCyZISnlYUYsL2hzlS7tPqKHvNqmI5JSUJZprXloMvA==}
+  '@shikijs/langs@3.21.0':
+    resolution: {integrity: sha512-g6mn5m+Y6GBJ4wxmBYqalK9Sp0CFkUqfNzUy2pJglUginz6ZpWbaWjDB4fbQ/8SHzFjYbtU6Ddlp1pc+PPNDVA==}
 
-  '@shikijs/langs@3.13.0':
-    resolution: {integrity: sha512-672c3WAETDYHwrRP0yLy3W1QYB89Hbpj+pO4KhxK6FzIrDI2FoEXNiNCut6BQmEApYLfuYfpgOZaqbY+E9b8wQ==}
+  '@shikijs/langs@4.0.2':
+    resolution: {integrity: sha512-KaXby5dvoeuZzN0rYQiPMjFoUrz4hgwIE+D6Du9owcHcl6/g16/yT5BQxSW5cGt2MZBz6Hl0YuRqf12omRfUUg==}
+    engines: {node: '>=20'}
 
-  '@shikijs/langs@3.15.0':
-    resolution: {integrity: sha512-WpRvEFvkVvO65uKYW4Rzxs+IG0gToyM8SARQMtGGsH4GDMNZrr60qdggXrFOsdfOVssG/QQGEl3FnJ3EZ+8w8A==}
+  '@shikijs/primitive@4.0.2':
+    resolution: {integrity: sha512-M6UMPrSa3fN5ayeJwFVl9qWofl273wtK1VG8ySDZ1mQBfhCpdd8nEx7nPZ/tk7k+TYcpqBZzj/AnwxT9lO+HJw==}
+    engines: {node: '>=20'}
 
-  '@shikijs/themes@3.13.0':
-    resolution: {integrity: sha512-Vxw1Nm1/Od8jyA7QuAenaV78BG2nSr3/gCGdBkLpfLscddCkzkL36Q5b67SrLLfvAJTOUzW39x4FHVCFriPVgg==}
+  '@shikijs/themes@3.21.0':
+    resolution: {integrity: sha512-BAE4cr9EDiZyYzwIHEk7JTBJ9CzlPuM4PchfcA5ao1dWXb25nv6hYsoDiBq2aZK9E3dlt3WB78uI96UESD+8Mw==}
 
-  '@shikijs/themes@3.15.0':
-    resolution: {integrity: sha512-8ow2zWb1IDvCKjYb0KiLNrK4offFdkfNVPXb1OZykpLCzRU6j+efkY+Y7VQjNlNFXonSw+4AOdGYtmqykDbRiQ==}
+  '@shikijs/themes@4.0.2':
+    resolution: {integrity: sha512-mjCafwt8lJJaVSsQvNVrJumbnnj1RI8jbUKrPKgE6E3OvQKxnuRoBaYC51H4IGHePsGN/QtALglWBU7DoKDFnA==}
+    engines: {node: '>=20'}
 
-  '@shikijs/types@3.13.0':
-    resolution: {integrity: sha512-oM9P+NCFri/mmQ8LoFGVfVyemm5Hi27330zuOBp0annwJdKH1kOLndw3zCtAVDehPLg9fKqoEx3Ht/wNZxolfw==}
+  '@shikijs/types@3.21.0':
+    resolution: {integrity: sha512-zGrWOxZ0/+0ovPY7PvBU2gIS9tmhSUUt30jAcNV0Bq0gb2S98gwfjIs1vxlmH5zM7/4YxLamT6ChlqqAJmPPjA==}
 
-  '@shikijs/types@3.15.0':
-    resolution: {integrity: sha512-BnP+y/EQnhihgHy4oIAN+6FFtmfTekwOLsQbRw9hOKwqgNy8Bdsjq8B05oAt/ZgvIWWFrshV71ytOrlPfYjIJw==}
+  '@shikijs/types@4.0.2':
+    resolution: {integrity: sha512-qzbeRooUTPnLE+sHD/Z8DStmaDgnbbc/pMrU203950aRqjX/6AFHeDYT+j00y2lPdz0ywJKx7o/7qnqTivtlXg==}
+    engines: {node: '>=20'}
 
   '@shikijs/vscode-textmate@10.0.2':
     resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
 
-  '@standard-schema/spec@1.0.0':
-    resolution: {integrity: sha512-m2bOd0f2RT9k8QJx1JN85cZYyH1RqFBdlwtkSlf4tBDYLCiiZnv1fIIwacK6cqwXavOydf0NPToMQgpKq+dVlA==}
+  '@simple-git/args-pathspec@1.0.3':
+    resolution: {integrity: sha512-ngJMaHlsWDTfjyq9F3VIQ8b7NXbBLq5j9i5bJ6XLYtD6qlDXT7fdKY2KscWWUF8t18xx052Y/PUO1K1TRc9yKA==}
+
+  '@simple-git/argv-parser@1.1.1':
+    resolution: {integrity: sha512-Q9lBcfQ+VQCpQqGJFHe5yooOS5hGdLFFbJ5R+R5aDsnkPCahtn1hSkMcORX65J2Z5lxSkD0lQorMsncuBQxYUw==}
+
+  '@sindresorhus/merge-streams@2.3.0':
+    resolution: {integrity: sha512-LtoMMhxAlorcGhmFYI+LhPgbPZCkgP6ra1YL604EeF6U98pLlQ3iWIGMdWSC+vWmPBWBNgmDBAhnAobLROJmwg==}
+    engines: {node: '>=18'}
+
+  '@standard-schema/spec@1.1.0':
+    resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
   '@stoplight/better-ajv-errors@1.0.3':
     resolution: {integrity: sha512-0p9uXkuB22qGdNfy3VeEhxkU5uwvp/KrBTAbrLBURv6ilxIVwanKwjMc41lQfIVgPGcOkmLbTolfFrSsueu7zA==}
@@ -2438,18 +3762,196 @@ packages:
   '@swc/helpers@0.5.17':
     resolution: {integrity: sha512-5IKx/Y13RsYd+sauPb2x+U/xZikHjolzfuDgTAl/Tdf3Q8rslRvC19NKDLgAJQ6wsqADk10ntlv08nPFw/gO/A==}
 
+  '@tailwindcss/node@4.1.18':
+    resolution: {integrity: sha512-DoR7U1P7iYhw16qJ49fgXUlry1t4CpXeErJHnQ44JgTSKMaZUdf17cfn5mHchfJ4KRBZRFA/Coo+MUF5+gOaCQ==}
+
+  '@tailwindcss/node@4.3.1':
+    resolution: {integrity: sha512-6NDaqRoAMSXD1mr/RXu0HBvNE9a2n5tHPsxu9XHLws8o4Twes5rBM2205SUUiJ9goAtadrN6xTGX0UDEwp/N4A==}
+
+  '@tailwindcss/oxide-android-arm64@4.1.18':
+    resolution: {integrity: sha512-dJHz7+Ugr9U/diKJA0W6N/6/cjI+ZTAoxPf9Iz9BFRF2GzEX8IvXxFIi/dZBloVJX/MZGvRuFA9rqwdiIEZQ0Q==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [android]
+
+  '@tailwindcss/oxide-android-arm64@4.3.1':
+    resolution: {integrity: sha512-SVlyf61g374l5cHyg8x9kf5xmLcOaxvOTsbsqDnSsDJaKOEFZ7GCvi84VAVGpxojYOs1+3K6M0UjXfqPU8vmOQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [android]
+
+  '@tailwindcss/oxide-darwin-arm64@4.1.18':
+    resolution: {integrity: sha512-Gc2q4Qhs660bhjyBSKgq6BYvwDz4G+BuyJ5H1xfhmDR3D8HnHCmT/BSkvSL0vQLy/nkMLY20PQ2OoYMO15Jd0A==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-darwin-arm64@4.3.1':
+    resolution: {integrity: sha512-hVnWLwv+e/l7c4WKyVtHVrIPvYdqWHjRB3MDIqARynzFtnQg85kmQEFCbV9Ja0VVx4xXTIiDWY60Y7iz/iNoDA==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-darwin-x64@4.1.18':
+    resolution: {integrity: sha512-FL5oxr2xQsFrc3X9o1fjHKBYBMD1QZNyc1Xzw/h5Qu4XnEBi3dZn96HcHm41c/euGV+GRiXFfh2hUCyKi/e+yw==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-darwin-x64@4.3.1':
+    resolution: {integrity: sha512-Cf7abu0WVgbhU7ANgPUnSAvm7nCvMweusHb8FnaHlLfv/Caq4GYaEZg7ZImzzmjx4lIAfuS8q+eLIS7A7IzxIg==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-freebsd-x64@4.1.18':
+    resolution: {integrity: sha512-Fj+RHgu5bDodmV1dM9yAxlfJwkkWvLiRjbhuO2LEtwtlYlBgiAT4x/j5wQr1tC3SANAgD+0YcmWVrj8R9trVMA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@tailwindcss/oxide-freebsd-x64@4.3.1':
+    resolution: {integrity: sha512-ZZqzX2Y+GXtXXfqSfpJhDm60OoZfvLHLCgm+J7NVqgHHJjG/m9ugZI77RwTsVd4fnBJuCFP6Ae6kTJb71UdS8g==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.1.18':
+    resolution: {integrity: sha512-Fp+Wzk/Ws4dZn+LV2Nqx3IilnhH51YZoRaYHQsVq3RQvEl+71VGKFpkfHrLM/Li+kt5c0DJe/bHXK1eHgDmdiA==}
+    engines: {node: '>= 10'}
+    cpu: [arm]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.3.1':
+    resolution: {integrity: sha512-/Ah/xik0LaMYfv9DZ0S/t4pBlBNYOcqtRwusjgovHkvT8ixueWCLyJjsaF5kQIckjb4IT8Q6K6p/iPmZMixYgg==}
+    engines: {node: '>= 20'}
+    cpu: [arm]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.1.18':
+    resolution: {integrity: sha512-S0n3jboLysNbh55Vrt7pk9wgpyTTPD0fdQeh7wQfMqLPM/Hrxi+dVsLsPrycQjGKEQk85Kgbx+6+QnYNiHalnw==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.3.1':
+    resolution: {integrity: sha512-gqdFoVJlw444GvpnheZLHmvTzSxI/cOUUh2KSNejQjTcYkW062SVD+En0rUgD+QV91bz1XGIGtt1HJd48xUGbQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.1.18':
+    resolution: {integrity: sha512-1px92582HkPQlaaCkdRcio71p8bc8i/ap5807tPRDK/uw953cauQBT8c5tVGkOwrHMfc2Yh6UuxaH4vtTjGvHg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.3.1':
+    resolution: {integrity: sha512-Bwv9KwOvE0VKa86xPFif9b9c3Y1NxOV1P0gLti/IYaWEsQYZXDlxfGEtA8mdDZ7SG3wyNXAWYT5SIn3giL57oA==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.1.18':
+    resolution: {integrity: sha512-v3gyT0ivkfBLoZGF9LyHmts0Isc8jHZyVcbzio6Wpzifg/+5ZJpDiRiUhDLkcr7f/r38SWNe7ucxmGW3j3Kb/g==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.3.1':
+    resolution: {integrity: sha512-Ymi8O8T15HYQdOUWUtTI6ldN0neHP85FC+Qz32xTcZ7iJXtem/x8ITev0o1e9e5rkqj4lONZfTRLvkmin1+tKg==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@tailwindcss/oxide-linux-x64-musl@4.1.18':
+    resolution: {integrity: sha512-bhJ2y2OQNlcRwwgOAGMY0xTFStt4/wyU6pvI6LSuZpRgKQwxTec0/3Scu91O8ir7qCR3AuepQKLU/kX99FouqQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@tailwindcss/oxide-linux-x64-musl@4.3.1':
+    resolution: {integrity: sha512-M+P/91qJ6uILLw4k2G93GMDRAXj61SMvFQYt39AqvUqYgExXpLL5aepfns7sj4HiAQeolirQF9E0lzRvdf4zPQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@tailwindcss/oxide-wasm32-wasi@4.1.18':
+    resolution: {integrity: sha512-LffYTvPjODiP6PT16oNeUQJzNVyJl1cjIebq/rWWBF+3eDst5JGEFSc5cWxyRCJ0Mxl+KyIkqRxk1XPEs9x8TA==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+    bundledDependencies:
+      - '@napi-rs/wasm-runtime'
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - '@tybys/wasm-util'
+      - '@emnapi/wasi-threads'
+      - tslib
+
+  '@tailwindcss/oxide-wasm32-wasi@4.3.1':
+    resolution: {integrity: sha512-zsM8uOeqvVGHsAXsJxsT28ttosFahLJKCLOTUBqRAtKnVgGSRitds9T432QiT8b77Yga7JIBkulIRRlJPtYhRA==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+    bundledDependencies:
+      - '@napi-rs/wasm-runtime'
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - '@tybys/wasm-util'
+      - '@emnapi/wasi-threads'
+      - tslib
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.1.18':
+    resolution: {integrity: sha512-HjSA7mr9HmC8fu6bdsZvZ+dhjyGCLdotjVOgLA2vEqxEBZaQo9YTX4kwgEvPCpRh8o4uWc4J/wEoFzhEmjvPbA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.3.1':
+    resolution: {integrity: sha512-aiNvSq9BsVk8V513lDKlrCFAgf8qBMPZTpgEhInL+NwQqs97mYmupVMrPrgBBSL8Pv/0zXu9MrMF9rMun1ZeNg==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.1.18':
+    resolution: {integrity: sha512-bJWbyYpUlqamC8dpR7pfjA0I7vdF6t5VpUGMWRkXVE3AXgIZjYUYAK7II1GNaxR8J1SSrSrppRar8G++JekE3Q==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.3.1':
+    resolution: {integrity: sha512-xDEyu1rg290472FEGaKHnzyDyh5QH+AlWvsU5hMoMtPpzmKlRI0jaYKCgSHDYtaQWZOYbMaduSyCwFwY4n1HmA==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [win32]
+
+  '@tailwindcss/oxide@4.1.18':
+    resolution: {integrity: sha512-EgCR5tTS5bUSKQgzeMClT6iCY3ToqE1y+ZB0AKldj809QXk1Y+3jB0upOYZrn9aGIzPtUsP7sX4QQ4XtjBB95A==}
+    engines: {node: '>= 10'}
+
+  '@tailwindcss/oxide@4.3.1':
+    resolution: {integrity: sha512-yVPyo8RNkabVr3O2EhHEE0Rewu7YKzc1DhIqfL46LKveFrmu9XbDazNOJY7/GRuvw1h6u3utWnR29H/p5JPlgA==}
+    engines: {node: '>= 20'}
+
+  '@tailwindcss/postcss@4.1.18':
+    resolution: {integrity: sha512-Ce0GFnzAOuPyfV5SxjXGn0CubwGcuDB0zcdaPuCSzAa/2vII24JTkH+I6jcbXLb1ctjZMZZI6OjDaLPJQL1S0g==}
+
   '@tailwindcss/typography@0.5.19':
     resolution: {integrity: sha512-w31dd8HOx3k9vPtcQh5QHP9GwKcgbMp87j58qi6xgiBnFFtKEAgCWnDw4qUT8aHwkCp8bKvb/KGKWWHedP0AAg==}
     peerDependencies:
       tailwindcss: '>=3.0.0 || insiders || >=4.0.0-alpha.20 || >=4.0.0-beta.1'
 
-  '@tanstack/query-core@5.90.2':
-    resolution: {integrity: sha512-k/TcR3YalnzibscALLwxeiLUub6jN5EDLwKDiO7q5f4ICEoptJ+n9+7vcEFy5/x/i6Q+Lb/tXrsKCggf5uQJXQ==}
-
-  '@tanstack/react-query@5.90.2':
-    resolution: {integrity: sha512-CLABiR+h5PYfOWr/z+vWFt5VsOA2ekQeRQBFSKlcoW6Ndx/f8rfyVmq4LbgOM4GG2qtxAxjLYLOpCNTYm4uKzw==}
+  '@tailwindcss/vite@4.3.1':
+    resolution: {integrity: sha512-hItDHuIIlEV61R+faXu66s1K36aTurO/Qw0e45Vskz57gXl9pWOT6eg3zmcEui6CZXddbN7zd41bwmvag4JGwQ==}
     peerDependencies:
-      react: ^18 || ^19
+      vite: ^5.2.0 || ^6 || ^7 || ^8
 
   '@tanstack/react-table@8.21.3':
     resolution: {integrity: sha512-5nNMTSETP4ykGegmVkhjcS8tTLW6Vl4axfEGQN3v0zdHYbK4UfoqfPChclTrJ4EoK9QynqAu9oUf8VEmrpZ5Ww==}
@@ -2476,9 +3978,14 @@ packages:
     peerDependencies:
       vue: ^2.7.0 || ^3.0.0
 
-  '@trysound/sax@0.2.0':
-    resolution: {integrity: sha512-L7z9BgrNEcYyUYtF+HaEfiS5ebkh9jXqbszz7pC0hRBPaatV0XjSD3+eHrpqFemQfgwiFF0QPIarnIihIDn7OA==}
-    engines: {node: '>=10.13.0'}
+  '@tybys/wasm-util@0.10.2':
+    resolution: {integrity: sha512-RoBvJ2X0wuKlWFIjrwffGw1IqZHKQqzIchKaadZZfnNpsAYp2mM0h36JtPCjNDAHGgYez/15uMBpfGwchhiMgg==}
+
+  '@tybys/wasm-util@0.10.3':
+    resolution: {integrity: sha512-F3fo1MYrRJYL3zER0OUOmkutjr1Vp23m7OsSgp7nq4SP6OqX6C/56XFIPAl5bt3zaBRjmW7SGz3u/6LwFpYcOg==}
+
+  '@types/async-retry@1.4.2':
+    resolution: {integrity: sha512-GUDuJURF0YiJZ+CBjNQA0+vbP/VHlJbB0sFqkzsV7EcOPRfurVonXpXKAt3w8qIjM1TEzpz6hc6POocPvHOS3w==}
 
   '@types/babel__core@7.20.5':
     resolution: {integrity: sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==}
@@ -2492,9 +3999,18 @@ packages:
   '@types/babel__traverse@7.28.0':
     resolution: {integrity: sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==}
 
+  '@types/chai@5.2.3':
+    resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
+
+  '@types/ci-info@2.0.0':
+    resolution: {integrity: sha512-5R2/MHILQLDCzTuhs1j4Qqq8AaKUf7Ma4KSSkCtc12+fMs47zfa34qhto9goxpyX00tQK1zxB885VCiawZ5Qhg==}
+
   '@types/configstore@6.0.2':
     resolution: {integrity: sha512-OS//b51j9uyR3zvwD04Kfs5kHpve2qalQ18JhY/ho3voGYUTPLEG90/ocfKPI48hyHH8T04f7KEEbK6Ue60oZQ==}
 
+  '@types/cross-spawn@6.0.0':
+    resolution: {integrity: sha512-evp2ZGsFw9YKprDbg8ySgC9NA15g3YgiI8ANkGmKKvvi0P2aDGYLPxQIC5qfeKNUOe3TjABVGuah6omPRpIYhg==}
+
   '@types/css-tree@2.3.11':
     resolution: {integrity: sha512-aEokibJOI77uIlqoBOkVbaQGC9zII0A+JH1kcTNKW2CwyYWD8KM6qdo+4c77wD3wZOQfJuNWAr9M4hdk+YhDIg==}
 
@@ -2600,6 +4116,9 @@ packages:
   '@types/debug@4.1.12':
     resolution: {integrity: sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==}
 
+  '@types/deep-eql@4.0.2':
+    resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
+
   '@types/diff@5.2.3':
     resolution: {integrity: sha512-K0Oqlrq3kQMaO2RhfrNQX5trmt+XLyom88zS0u84nnIcLvFnRUMRRHmrGny5GSM+kNO9IZLARsdQHDzkhAgmrQ==}
 
@@ -2612,12 +4131,19 @@ packages:
   '@types/estree@1.0.8':
     resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
 
-  '@types/fontkit@2.0.8':
-    resolution: {integrity: sha512-wN+8bYxIpJf+5oZdrdtaX04qUuWHcKxcDEgRS9Qm9ZClSHjzEn13SxUC+5eRM+4yXIeTYk8mTzLAWGF64847ew==}
+  '@types/fs-extra@11.0.4':
+    resolution: {integrity: sha512-yTbItCNreRooED33qjunPthRcSjERP1r4MqCZc7wv0u2sUkzTFp45tgUfS5+r7FrZPdmCCNflLhVSP/o+SemsQ==}
 
   '@types/geojson@7946.0.16':
     resolution: {integrity: sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg==}
 
+  '@types/glob@9.0.0':
+    resolution: {integrity: sha512-00UxlRaIUvYm4R4W9WYkN8/J+kV8fmOQ7okeH6YFtGWFMt3odD45tpG5yA5wnL7HE6lLgjaTW5n14ju2hl2NNA==}
+    deprecated: This is a stub types definition. glob provides its own type definitions, so you do not need this installed.
+
+  '@types/har-format@1.2.16':
+    resolution: {integrity: sha512-fluxdy7ryD3MV6h8pTfTYpy/xQzCFC7m89nOH9y94cNqJ1mDIDPut7MnRHI3F6qRmh/cT2fUjG1MLdCNb4hE9A==}
+
   '@types/hast@2.3.10':
     resolution: {integrity: sha512-McWspRw8xx8J9HurkVBfYj0xKoE25tOFlHGdx4MJ5xORQrMGZNqJhVQWaIbm6Oyla5kYOXtDiopzKRJzEOkwJw==}
 
@@ -2633,8 +4159,8 @@ packages:
   '@types/json-schema@7.0.15':
     resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}
 
-  '@types/jsonpath@0.2.4':
-    resolution: {integrity: sha512-K3hxB8Blw0qgW6ExKgMbXQv2UPZBoE2GqLpVY+yr7nMD2Pq86lsuIzyAaiQ7eMqFL5B6di6pxSkogLJEyEHoGA==}
+  '@types/jsonfile@6.1.4':
+    resolution: {integrity: sha512-D5qGUYwjvnNNextdU59/+fI+spnwtTFmyQP0h+PfIOSkNfpU6AOICUOkm4i0OnSk+NyjdPJrxCDro0sJsWlRpQ==}
 
   '@types/jsonwebtoken@9.0.10':
     resolution: {integrity: sha512-asx5hIG9Qmf/1oStypjanR7iKTv0gXQ1Ov/jfrX6kS/EO0OFni8orbmGCn0672NHR3kXHwpAwR+B368ZGN/2rA==}
@@ -2648,9 +4174,6 @@ packages:
   '@types/lodash@4.17.20':
     resolution: {integrity: sha512-H3MHACvFUEiujabxhaI/ImO6gUrd8oOurg7LQtS7mbwIXA/cUqWrvBsaeJ23aZEPk1TAYkurjfMbSELfoCXlGA==}
 
-  '@types/mdast@3.0.15':
-    resolution: {integrity: sha512-LnwD+mUEfxWMa1QpDraczIn6k0Ee3SMicuYSSzS6ZYl2gKS09EClnJYGd8Du6rfc5r/GZEk5o1mRb8TaTj03sQ==}
-
   '@types/mdast@4.0.4':
     resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==}
 
@@ -2663,43 +4186,57 @@ packages:
   '@types/nlcst@2.0.3':
     resolution: {integrity: sha512-vSYNSDe6Ix3q+6Z7ri9lyWqgGhJTmzRjZRqyq15N0Z/1/UnVsno9G/N40NBijoYx2seFDIl0+B2mgAb9mezUCA==}
 
-  '@types/node-fetch@2.6.13':
-    resolution: {integrity: sha512-QGpRVpzSaUs30JBSGPjOg4Uveu384erbHBoT1zeONvyCfwQxIkUshLAOqN/k9EjGviPRmWTTe6aH2qySWKTVSw==}
-
   '@types/node@12.20.55':
     resolution: {integrity: sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==}
 
-  '@types/node@18.19.129':
-    resolution: {integrity: sha512-hrmi5jWt2w60ayox3iIXwpMEnfUvOLJCRtrOPbHtH15nTjvO7uhnelvrdAs0dO0/zl5DZ3ZbahiaXEVb54ca/A==}
-
   '@types/node@20.19.19':
     resolution: {integrity: sha512-pb1Uqj5WJP7wrcbLU7Ru4QtA0+3kAXrkutGiD26wUKzSMgNNaPARTUDQmElUXp64kh3cWdou3Q0C7qwwxqSFmg==}
 
-  '@types/node@22.13.14':
-    resolution: {integrity: sha512-Zs/Ollc1SJ8nKUAgc7ivOEdIBM8JAKgrqqUYi2J997JuKO7/tpQC+WCetQ1sypiKCQWHdvdg9wBNpUPEWZae7w==}
+  '@types/node@22.19.21':
+    resolution: {integrity: sha512-VMeFBSCKQKmm2swI2kW51SFusDqekC6q9trBCvJ/JliDchFSuoYYKN7yVNjPthP1HKZcx3U1gI/wTcEBjEFKTA==}
+
+  '@types/node@24.12.0':
+    resolution: {integrity: sha512-GYDxsZi3ChgmckRT9HPU0WEhKLP08ev/Yfcq2AstjrDASOYCSXeyjDsHg4v5t4jOj7cyDX3vmprafKlWIG9MXQ==}
+
+  '@types/node@25.0.3':
+    resolution: {integrity: sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA==}
 
   '@types/pako@2.0.4':
     resolution: {integrity: sha512-VWDCbrLeVXJM9fihYodcLiIv0ku+AlOa/TQ1SvYOaBuyrSKgEcro95LJyIsJ4vSo6BXIxOKxiJAat04CmST9Fw==}
 
-  '@types/prop-types@15.7.15':
-    resolution: {integrity: sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==}
+  '@types/prompts@2.0.1':
+    resolution: {integrity: sha512-AhtMcmETelF8wFDV1ucbChKhLgsc+ytXZXkNz/nnTAMSDeqsjALknEFxi7ZtLgS/G8bV2rp90LhDW5SGACimIQ==}
+
+  '@types/proper-lockfile@4.1.4':
+    resolution: {integrity: sha512-uo2ABllncSqg9F1D4nugVl9v93RmjxF6LJzQLMLDdPaXCUIDPeOJ21Gbqi43xNKzBi/WQ0Q0dICqufzQbMjipQ==}
 
   '@types/protocol-buffers-schema@3.4.3':
     resolution: {integrity: sha512-8cCg6BiIj4jS0LXUFq3sndmd46yyPLYqMzvXLcTM1MRubh3sfZlQiehoCjGDxSHTqGSjjx8EtVNryIAl0njQWg==}
 
-  '@types/react-dom@18.3.7':
-    resolution: {integrity: sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ==}
+  '@types/react-dom@19.2.3':
+    resolution: {integrity: sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==}
     peerDependencies:
-      '@types/react': ^18.0.0
+      '@types/react': ^19.2.0
+
+  '@types/react-reconciler@0.28.9':
+    resolution: {integrity: sha512-HHM3nxyUZ3zAylX8ZEyrDNd2XZOnQ0D5XfunJF5FLQnZbHHYq4UWvW1QfelQNXv1ICNkwYhfxjwfnqivYB6bFg==}
+    peerDependencies:
+      '@types/react': '*'
 
   '@types/react-syntax-highlighter@15.5.13':
     resolution: {integrity: sha512-uLGJ87j6Sz8UaBAooU0T6lWJ0dBmjZgN1PZTrj05TNql2/XpC6+4HhMT5syIdFUUt+FASfCeLLv4kBygNU+8qA==}
 
-  '@types/react@18.3.26':
-    resolution: {integrity: sha512-RFA/bURkcKzx/X9oumPG9Vp3D3JUgus/d0b67KB0t5S/raciymilkOa66olh78MUI92QLbEJevO7rvqU/kjwKA==}
+  '@types/react@19.2.13':
+    resolution: {integrity: sha512-KkiJeU6VbYbUOp5ITMIc7kBfqlYkKA5KhEHVrGMmUUMt7NeaZg65ojdPk+FtNrBAOXNVM5QM72jnADjM+XVRAQ==}
+
+  '@types/retry@0.12.5':
+    resolution: {integrity: sha512-3xSjTp3v03X/lSQLkczaN9UIEwJMoMCA1+Nb5HfbJEQWogdeQIyVtTvxPXDQjZ5zws8rFQfVfRdz03ARihPJgw==}
 
-  '@types/retry@0.12.0':
-    resolution: {integrity: sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==}
+  '@types/rimraf@3.0.0':
+    resolution: {integrity: sha512-7WhJ0MdpFgYQPXlF4Dx+DhgvlPCfz/x5mHaeDQAKhcenvQP1KCpLQ18JklAqeGMYSAT2PxLpzd0g2/HE7fj7hQ==}
+
+  '@types/sax@1.2.7':
+    resolution: {integrity: sha512-rO73L89PJxeYM3s3pPPjiPgVVcymqU490g0YO5n5By0k2Erzj6tay/4lr1CHAAU4JyOWd1rpQ8bCf6cZfHU96A==}
 
   '@types/semver@7.7.1':
     resolution: {integrity: sha512-FmgJfu+MOcQ370SD0ev7EI8TlCAfKYU+B4m5T3yXc1CiRN94g/SZPtsCkk506aUDtlMnFZvasDwHHUcZUEaYuA==}
@@ -2725,28 +4262,33 @@ packages:
   '@types/uuid@10.0.0':
     resolution: {integrity: sha512-7gqG38EyHgyP1S+7+xomFtL+ZNHcKv6DwNaCZmJmo1vgMugyF3TCnXVg4t1uk89mLNwnLtnY3TpOpCOyp1/xHQ==}
 
+  '@types/validate-npm-package-name@3.0.0':
+    resolution: {integrity: sha512-iFNNIrEaJH1lbPiyX+O/QyxSbKxrTjdNBVZGckt+iEL9So0hdZNBL68sOfHnt2txuUD8UJXvmKv/1DkgkebgUg==}
+
+  '@types/vscode@1.109.0':
+    resolution: {integrity: sha512-0Pf95rnwEIwDbmXGC08r0B4TQhAbsHQ5UyTIgVgoieDe4cOnf92usuR5dEczb6bTKEp7ziZH4TV1TRGPPCExtw==}
+
   '@types/web-bluetooth@0.0.20':
     resolution: {integrity: sha512-g9gZnnXVq7gM7v3tJCWV/qw7w+KeOlSHAhgF9RytFyifW6AF61hdT2ucrYhPq9hLs5JIryeupHV3qGk95dH9ow==}
 
+  '@types/web-bluetooth@0.0.21':
+    resolution: {integrity: sha512-oIQLCGWtcFZy2JW77j9k8nHzAOpqMHLQejDA48XXMWH6tjCQHz5RCFz1bzsmROyL6PUm+LLnUiI4BCn221inxA==}
+
   '@ungap/structured-clone@1.3.0':
     resolution: {integrity: sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==}
+    deprecated: Potential CWE-502 - Update to 1.3.1 or higher
 
-  '@unhead/dom@1.11.20':
-    resolution: {integrity: sha512-jgfGYdOH+xHJF/j8gudjsYu3oIjFyXhCWcgKaw3vQnT616gSqyqnGQGOItL+BQtQZACKNISwIfx5PuOtztMKLA==}
-
-  '@unhead/schema@1.11.20':
-    resolution: {integrity: sha512-0zWykKAaJdm+/Y7yi/Yds20PrUK7XabLe9c3IRcjnwYmSWY6z0Cr19VIs3ozCj8P+GhR+/TI2mwtGlueCEYouA==}
-
-  '@unhead/shared@1.11.20':
-    resolution: {integrity: sha512-1MOrBkGgkUXS+sOKz/DBh4U20DNoITlJwpmvSInxEUNhghSNb56S0RnaHRq0iHkhrO/cDgz2zvfdlRpoPLGI3w==}
-
-  '@unhead/vue@1.11.20':
-    resolution: {integrity: sha512-sqQaLbwqY9TvLEGeq8Fd7+F2TIuV3nZ5ihVISHjWpAM3y7DwNWRU7NmT9+yYT+2/jw1Vjwdkv5/HvDnvCLrgmg==}
+  '@unhead/vue@2.1.13':
+    resolution: {integrity: sha512-HYy0shaHRnLNW9r85gppO8IiGz0ONWVV3zGdlT8CQ0tbTwixznJCIiyqV4BSV1aIF1jJIye0pd1p/k6Eab8Z/A==}
     peerDependencies:
-      vue: '>=2.7 || >=3'
+      vue: '>=3.5.18'
+
+  '@vercel/ncc@0.34.0':
+    resolution: {integrity: sha512-G9h5ZLBJ/V57Ou9vz5hI8pda/YQX5HQszCs3AmIus3XzsmRn/0Ptic5otD3xVST8QLKk7AMk7AqpsyQGN7MZ9A==}
+    hasBin: true
 
-  '@vercel/oidc@3.0.2':
-    resolution: {integrity: sha512-JekxQ0RApo4gS4un/iMGsIL1/k4KUBe3HmnGcDvzHuFBdQdudEJgTqcsJC7y6Ul4Yw5CeykgvQbX2XeEJd0+DA==}
+  '@vercel/oidc@3.1.0':
+    resolution: {integrity: sha512-Fw28YZpRnA3cAHHDlkt7xQHiJ0fcL+NRcIqsocZQUSmbzeIKRpwttJjik5ZGanXP+vlA4SbTg+AbA3bP363l+w==}
     engines: {node: '>= 20'}
 
   '@vitejs/plugin-react@4.7.0':
@@ -2755,101 +4297,161 @@ packages:
     peerDependencies:
       vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
 
-  '@vitest/expect@2.1.9':
-    resolution: {integrity: sha512-UJCIkTBenHeKT1TTlKMJWy1laZewsRIzYighyYiJKZreqtdxSos/S1t+ktRMQWu2CKqaarrkeszJx1cgC5tGZw==}
+  '@vitejs/plugin-react@5.1.4':
+    resolution: {integrity: sha512-VIcFLdRi/VYRU8OL/puL7QXMYafHmqOnwTZY50U1JPlCNj30PxCMx65c494b1K9be9hX83KVt0+gTEwTWLqToA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    peerDependencies:
+      vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
+
+  '@vitejs/plugin-react@5.2.0':
+    resolution: {integrity: sha512-YmKkfhOAi3wsB1PhJq5Scj3GXMn3WvtQ/JC0xoopuHoXSdmtdStOpFrYaT1kie2YgFBcIe64ROzMYRjCrYOdYw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    peerDependencies:
+      vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
+
+  '@vitest/expect@3.2.4':
+    resolution: {integrity: sha512-Io0yyORnB6sikFlt8QW5K7slY4OjqNX9jmJQ02QDda8lyM6B5oNgVWoSoKPac8/kgnCUzuHQKrSLtu/uOqqrig==}
+
+  '@vitest/expect@4.0.18':
+    resolution: {integrity: sha512-8sCWUyckXXYvx4opfzVY03EOiYVxyNrHS5QxX3DAIi5dpJAAkyJezHCP77VMX4HKA2LDT/Jpfo8i2r5BE3GnQQ==}
+
+  '@vitest/mocker@3.2.4':
+    resolution: {integrity: sha512-46ryTE9RZO/rfDd7pEqFl7etuyzekzEhUbTW3BvmeO/BcCMEgq59BKhek3dXDWgAj4oMK6OZi+vRr1wPW6qjEQ==}
+    peerDependencies:
+      msw: ^2.4.9
+      vite: ^5.0.0 || ^6.0.0 || ^7.0.0-0
+    peerDependenciesMeta:
+      msw:
+        optional: true
+      vite:
+        optional: true
 
-  '@vitest/mocker@2.1.9':
-    resolution: {integrity: sha512-tVL6uJgoUdi6icpxmdrn5YNo3g3Dxv+IHJBr0GXHaEdTcw3F+cPKnsXFhli6nO+f/6SDKPHEK1UN+k+TQv0Ehg==}
+  '@vitest/mocker@4.0.18':
+    resolution: {integrity: sha512-HhVd0MDnzzsgevnOWCBj5Otnzobjy5wLBe4EdeeFGv8luMsGcYqDuFRMcttKWZA5vVO8RFjexVovXvAM4JoJDQ==}
     peerDependencies:
       msw: ^2.4.9
-      vite: ^5.0.0
+      vite: ^6.0.0 || ^7.0.0-0
     peerDependenciesMeta:
       msw:
         optional: true
       vite:
         optional: true
 
-  '@vitest/pretty-format@2.1.9':
-    resolution: {integrity: sha512-KhRIdGV2U9HOUzxfiHmY8IFHTdqtOhIzCpd8WRdJiE7D/HUcZVD0EgQCVjm+Q9gkUXWgBvMmTtZgIG48wq7sOQ==}
+  '@vitest/pretty-format@3.2.4':
+    resolution: {integrity: sha512-IVNZik8IVRJRTr9fxlitMKeJeXFFFN0JaB9PHPGQ8NKQbGpfjlTx9zO4RefN8gp7eqjNy8nyK3NZmBzOPeIxtA==}
+
+  '@vitest/pretty-format@4.0.18':
+    resolution: {integrity: sha512-P24GK3GulZWC5tz87ux0m8OADrQIUVDPIjjj65vBXYG17ZeU3qD7r+MNZ1RNv4l8CGU2vtTRqixrOi9fYk/yKw==}
+
+  '@vitest/runner@3.2.4':
+    resolution: {integrity: sha512-oukfKT9Mk41LreEW09vt45f8wx7DordoWUZMYdY/cyAk7w5TWkTRCNZYF7sX7n2wB7jyGAl74OxgwhPgKaqDMQ==}
+
+  '@vitest/runner@4.0.18':
+    resolution: {integrity: sha512-rpk9y12PGa22Jg6g5M3UVVnTS7+zycIGk9ZNGN+m6tZHKQb7jrP7/77WfZy13Y/EUDd52NDsLRQhYKtv7XfPQw==}
 
-  '@vitest/runner@2.1.9':
-    resolution: {integrity: sha512-ZXSSqTFIrzduD63btIfEyOmNcBmQvgOVsPNPe0jYtESiXkhd8u2erDLnMxmGrDCwHCCHE7hxwRDCT3pt0esT4g==}
+  '@vitest/snapshot@3.2.4':
+    resolution: {integrity: sha512-dEYtS7qQP2CjU27QBC5oUOxLE/v5eLkGqPE0ZKEIDGMs4vKWe7IjgLOeauHsR0D5YuuycGRO5oSRXnwnmA78fQ==}
 
-  '@vitest/snapshot@2.1.9':
-    resolution: {integrity: sha512-oBO82rEjsxLNJincVhLhaxxZdEtV0EFHMK5Kmx5sJ6H9L183dHECjiefOAdnqpIgT5eZwT04PoggUnW88vOBNQ==}
+  '@vitest/snapshot@4.0.18':
+    resolution: {integrity: sha512-PCiV0rcl7jKQjbgYqjtakly6T1uwv/5BQ9SwBLekVg/EaYeQFPiXcgrC2Y7vDMA8dM1SUEAEV82kgSQIlXNMvA==}
 
-  '@vitest/spy@2.1.9':
-    resolution: {integrity: sha512-E1B35FwzXXTs9FHNK6bDszs7mtydNi5MIfUWpceJ8Xbfb1gBMscAnwLbEu+B44ed6W3XjL9/ehLPHR1fkf1KLQ==}
+  '@vitest/spy@3.2.4':
+    resolution: {integrity: sha512-vAfasCOe6AIK70iP5UD11Ac4siNUNJ9i/9PZ3NKx07sG6sUxeag1LWdNrMWeKKYBLlzuK+Gn65Yd5nyL6ds+nw==}
 
-  '@vitest/utils@2.1.9':
-    resolution: {integrity: sha512-v0psaMSkNJ3A2NMrUEHFRzJtDPFn+/VWZ5WxImB21T9fjucJRmS7xCS3ppEnARb9y11OAzaD+P2Ps+b+BGX5iQ==}
+  '@vitest/spy@4.0.18':
+    resolution: {integrity: sha512-cbQt3PTSD7P2OARdVW3qWER5EGq7PHlvE+QfzSC0lbwO+xnt7+XH06ZzFjFRgzUX//JmpxrCu92VdwvEPlWSNw==}
+
+  '@vitest/utils@3.2.4':
+    resolution: {integrity: sha512-fB2V0JFrQSMsCo9HiSq3Ezpdv4iYaXRG1Sx8edX3MwxfyNn83mKiGzOcH+Fkxt4MHxr3y42fQi1oeAInqgX2QA==}
+
+  '@vitest/utils@4.0.18':
+    resolution: {integrity: sha512-msMRKLMVLWygpK3u2Hybgi4MNjcYJvwTb0Ru09+fOyCXIgT5raYP041DRRdiJiI3k/2U6SEbAETB3YtBrUkCFA==}
 
   '@volar/kit@2.4.23':
     resolution: {integrity: sha512-YuUIzo9zwC2IkN7FStIcVl1YS9w5vkSFEZfPvnu0IbIMaR9WHhc9ZxvlT+91vrcSoRY469H2jwbrGqpG7m1KaQ==}
     peerDependencies:
       typescript: '*'
 
+  '@volar/kit@2.4.28':
+    resolution: {integrity: sha512-cKX4vK9dtZvDRaAzeoUdaAJEew6IdxHNCRrdp5Kvcl6zZOqb6jTOfk3kXkIkG3T7oTFXguEMt5+9ptyqYR84Pg==}
+    peerDependencies:
+      typescript: '*'
+
   '@volar/language-core@2.4.23':
     resolution: {integrity: sha512-hEEd5ET/oSmBC6pi1j6NaNYRWoAiDhINbT8rmwtINugR39loROSlufGdYMF9TaKGfz+ViGs1Idi3mAhnuPcoGQ==}
 
+  '@volar/language-core@2.4.28':
+    resolution: {integrity: sha512-w4qhIJ8ZSitgLAkVay6AbcnC7gP3glYM3fYwKV3srj8m494E3xtrCv6E+bWviiK/8hs6e6t1ij1s2Endql7vzQ==}
+
   '@volar/language-server@2.4.23':
     resolution: {integrity: sha512-k0iO+tybMGMMyrNdWOxgFkP0XJTdbH0w+WZlM54RzJU3WZSjHEupwL30klpM7ep4FO6qyQa03h+VcGHD4Q8gEg==}
 
+  '@volar/language-server@2.4.28':
+    resolution: {integrity: sha512-NqcLnE5gERKuS4PUFwlhMxf6vqYo7hXtbMFbViXcbVkbZ905AIVWhnSo0ZNBC2V127H1/2zP7RvVOVnyITFfBw==}
+
   '@volar/language-service@2.4.23':
     resolution: {integrity: sha512-h5mU9DZ/6u3LCB9xomJtorNG6awBNnk9VuCioGsp6UtFiM8amvS5FcsaC3dabdL9zO0z+Gq9vIEMb/5u9K6jGQ==}
 
+  '@volar/language-service@2.4.28':
+    resolution: {integrity: sha512-Rh/wYCZJrI5vCwMk9xyw/Z+MsWxlJY1rmMZPsxUoJKfzIRjS/NF1NmnuEcrMbEVGja00aVpCsInJfixQTMdvLw==}
+
   '@volar/source-map@2.4.23':
     resolution: {integrity: sha512-Z1Uc8IB57Lm6k7q6KIDu/p+JWtf3xsXJqAX/5r18hYOTpJyBn0KXUR8oTJ4WFYOcDzWC9n3IflGgHowx6U6z9Q==}
 
+  '@volar/source-map@2.4.28':
+    resolution: {integrity: sha512-yX2BDBqJkRXfKw8my8VarTyjv48QwxdJtvRgUpNE5erCsgEUdI2DsLbpa+rOQVAJYshY99szEcRDmyHbF10ggQ==}
+
   '@volar/typescript@2.4.23':
     resolution: {integrity: sha512-lAB5zJghWxVPqfcStmAP1ZqQacMpe90UrP5RJ3arDyrhy4aCUQqmxPPLB2PWDKugvylmO41ljK7vZ+t6INMTag==}
 
+  '@volar/typescript@2.4.28':
+    resolution: {integrity: sha512-Ja6yvWrbis2QtN4ClAKreeUZPVYMARDYZl9LMEv1iQ1QdepB6wn0jTRxA9MftYmYa4DQ4k/DaSZpFPUfxl8giw==}
+
   '@vscode/emmet-helper@2.11.0':
     resolution: {integrity: sha512-QLxjQR3imPZPQltfbWRnHU6JecWTF1QSWhx3GAKQpslx7y3Dp6sIIXhKjiUJ/BR9FX8PVthjr9PD6pNwOJfAzw==}
 
   '@vscode/l10n@0.0.18':
     resolution: {integrity: sha512-KYSIHVmslkaCDyw013pphY+d7x1qV8IZupYfeIfzNA+nsaWHbn5uPuQRvdRFsa9zFzGeudPuoGoZ1Op4jrJXIQ==}
 
-  '@vue/compiler-core@3.5.22':
-    resolution: {integrity: sha512-jQ0pFPmZwTEiRNSb+i9Ow/I/cHv2tXYqsnHKKyCQ08irI2kdF5qmYedmF8si8mA7zepUFmJ2hqzS8CQmNOWOkQ==}
+  '@vue/compiler-core@3.5.32':
+    resolution: {integrity: sha512-4x74Tbtqnda8s/NSD6e1Dr5p1c8HdMU5RWSjMSUzb8RTcUQqevDCxVAitcLBKT+ie3o0Dl9crc/S/opJM7qBGQ==}
 
-  '@vue/compiler-dom@3.5.22':
-    resolution: {integrity: sha512-W8RknzUM1BLkypvdz10OVsGxnMAuSIZs9Wdx1vzA3mL5fNMN15rhrSCLiTm6blWeACwUwizzPVqGJgOGBEN/hA==}
+  '@vue/compiler-dom@3.5.32':
+    resolution: {integrity: sha512-ybHAu70NtiEI1fvAUz3oXZqkUYEe5J98GjMDpTGl5iHb0T15wQYLR4wE3h9xfuTNA+Cm2f4czfe8B4s+CCH57Q==}
 
-  '@vue/compiler-sfc@3.5.22':
-    resolution: {integrity: sha512-tbTR1zKGce4Lj+JLzFXDq36K4vcSZbJ1RBu8FxcDv1IGRz//Dh2EBqksyGVypz3kXpshIfWKGOCcqpSbyGWRJQ==}
+  '@vue/compiler-sfc@3.5.32':
+    resolution: {integrity: sha512-8UYUYo71cP/0YHMO814TRZlPuUUw3oifHuMR7Wp9SNoRSrxRQnhMLNlCeaODNn6kNTJsjFoQ/kqIj4qGvya4Xg==}
 
-  '@vue/compiler-ssr@3.5.22':
-    resolution: {integrity: sha512-GdgyLvg4R+7T8Nk2Mlighx7XGxq/fJf9jaVofc3IL0EPesTE86cP/8DD1lT3h1JeZr2ySBvyqKQJgbS54IX1Ww==}
+  '@vue/compiler-ssr@3.5.32':
+    resolution: {integrity: sha512-Gp4gTs22T3DgRotZ8aA/6m2jMR+GMztvBXUBEUOYOcST+giyGWJ4WvFd7QLHBkzTxkfOt8IELKNdpzITLbA2rw==}
 
-  '@vue/devtools-api@6.6.4':
-    resolution: {integrity: sha512-sGhTPMuXqZ1rVOk32RylztWkfXTRhuS7vgAKv0zjqk8gbsHkJ7xfFf+jbySxt7tWObEJwyKaHMikV/WGDiQm8g==}
+  '@vue/reactivity@3.5.32':
+    resolution: {integrity: sha512-/ORasxSGvZ6MN5gc+uE364SxFdJ0+WqVG0CENXaGW58TOCdrAW76WWaplDtECeS1qphvtBZtR+3/o1g1zL4xPQ==}
 
-  '@vue/reactivity@3.5.22':
-    resolution: {integrity: sha512-f2Wux4v/Z2pqc9+4SmgZC1p73Z53fyD90NFWXiX9AKVnVBEvLFOWCEgJD3GdGnlxPZt01PSlfmLqbLYzY/Fw4A==}
+  '@vue/runtime-core@3.5.32':
+    resolution: {integrity: sha512-pDrXCejn4UpFDFmMd27AcJEbHaLemaE5o4pbb7sLk79SRIhc6/t34BQA7SGNgYtbMnvbF/HHOftYBgFJtUoJUQ==}
 
-  '@vue/runtime-core@3.5.22':
-    resolution: {integrity: sha512-EHo4W/eiYeAzRTN5PCextDUZ0dMs9I8mQ2Fy+OkzvRPUYQEyK9yAjbasrMCXbLNhF7P0OUyivLjIy0yc6VrLJQ==}
+  '@vue/runtime-dom@3.5.32':
+    resolution: {integrity: sha512-1CDVv7tv/IV13V8Nip1k/aaObVbWqRlVCVezTwx3K07p7Vxossp5JU1dcPNhJk3w347gonIUT9jQOGutyJrSVQ==}
 
-  '@vue/runtime-dom@3.5.22':
-    resolution: {integrity: sha512-Av60jsryAkI023PlN7LsqrfPvwfxOd2yAwtReCjeuugTJTkgrksYJJstg1e12qle0NarkfhfFu1ox2D+cQotww==}
-
-  '@vue/server-renderer@3.5.22':
-    resolution: {integrity: sha512-gXjo+ao0oHYTSswF+a3KRHZ1WszxIqO7u6XwNHqcqb9JfyIL/pbWrrh/xLv7jeDqla9u+LK7yfZKHih1e1RKAQ==}
+  '@vue/server-renderer@3.5.32':
+    resolution: {integrity: sha512-IOjm2+JQwRFS7W28HNuJeXQle9KdZbODFY7hFGVtnnghF51ta20EWAZJHX+zLGtsHhaU6uC9BGPV52KVpYryMQ==}
     peerDependencies:
-      vue: 3.5.22
+      vue: 3.5.32
 
-  '@vue/shared@3.5.22':
-    resolution: {integrity: sha512-F4yc6palwq3TT0u+FYf0Ns4Tfl9GRFURDN2gWG7L1ecIaS/4fCIuFOjMTnCyjsu/OK6vaDKLCrGAa+KvvH+h4w==}
+  '@vue/shared@3.5.32':
+    resolution: {integrity: sha512-ksNyrmRQzWJJ8n3cRDuSF7zNNontuJg1YHnmWRJd2AMu8Ij2bqwiiri2lH5rHtYPZjj4STkNcgcmiQqlOjiYGg==}
 
   '@vueuse/core@10.11.1':
     resolution: {integrity: sha512-guoy26JQktXPcz+0n3GukWIy/JDNKti9v6VEMu6kV2sYBsWuGiTU8OWdg+ADfUbHg3/3DlqySDe7JmdHrktiww==}
 
-  '@vueuse/core@11.3.0':
-    resolution: {integrity: sha512-7OC4Rl1f9G8IT6rUfi9JrKiXy4bfmHhZ5x2Ceojy0jnd3mHNEvV4JaRygH362ror6/NZ+Nl+n13LPzGiPN8cKA==}
+  '@vueuse/core@13.9.0':
+    resolution: {integrity: sha512-ts3regBQyURfCE2BcytLqzm8+MmLlo5Ln/KLoxDVcsZ2gzIwVNnQpQOL/UKV8alUqjSZOlpFZcRNsLRqj+OzyA==}
+    peerDependencies:
+      vue: ^3.5.0
 
-  '@vueuse/integrations@11.3.0':
-    resolution: {integrity: sha512-5fzRl0apQWrDezmobchoiGTkGw238VWESxZHazfhP3RM7pDSiyXy18QbfYkILoYNTd23HPAfQTJpkUc5QbkwTw==}
+  '@vueuse/integrations@13.9.0':
+    resolution: {integrity: sha512-SDobKBbPIOe0cVL7QxMzGkuUGHvWTdihi9zOrrWaWUgFKe15cwEcwfWmgrcNzjT6kHnNmWuTajPHoIzUjYNYYQ==}
     peerDependencies:
       async-validator: ^4
       axios: ^1
@@ -2862,7 +4464,8 @@ packages:
       nprogress: ^0.2
       qrcode: ^1.5
       sortablejs: ^1
-      universal-cookie: ^7
+      universal-cookie: ^7 || ^8
+      vue: ^3.5.0
     peerDependenciesMeta:
       async-validator:
         optional: true
@@ -2892,14 +4495,16 @@ packages:
   '@vueuse/metadata@10.11.1':
     resolution: {integrity: sha512-IGa5FXd003Ug1qAZmyE8wF3sJ81xGLSqTqtQ6jaVfkeZ4i5kS2mwQF61yhVqojRnenVew5PldLyRgvdl4YYuSw==}
 
-  '@vueuse/metadata@11.3.0':
-    resolution: {integrity: sha512-pwDnDspTqtTo2HwfLw4Rp6yywuuBdYnPYDq+mO38ZYKGebCUQC/nVj/PXSiK9HX5otxLz8Fn7ECPbjiRz2CC3g==}
+  '@vueuse/metadata@13.9.0':
+    resolution: {integrity: sha512-1AFRvuiGphfF7yWixZa0KwjYH8ulyjDCC0aFgrGRz8+P4kvDFSdXLVfTk5xAN9wEuD1J6z4/myMoYbnHoX07zg==}
 
   '@vueuse/shared@10.11.1':
     resolution: {integrity: sha512-LHpC8711VFZlDaYUXEBbFBCQ7GS3dVU9mjOhhMhXP6txTV4EhYQg/KGnQuvt/sPAtoUKq7VVUnL6mVtFoL42sA==}
 
-  '@vueuse/shared@11.3.0':
-    resolution: {integrity: sha512-P8gSSWQeucH5821ek2mn/ciCk+MS/zoRKqdQIM3bHq6p7GXDAJLmnRRKmF5F65sAVJIfzQlwR3aDzwCn10s8hA==}
+  '@vueuse/shared@13.9.0':
+    resolution: {integrity: sha512-e89uuTLMh0U5cZ9iDpEI2senqPGfbPRTHM/0AaQkcxnpqjkZqDYP8rpfm7edOz8s+pOCOROEy1PIveSW8+fL5g==}
+    peerDependencies:
+      vue: ^3.5.0
 
   '@xyflow/react@12.8.6':
     resolution: {integrity: sha512-SksAm2m4ySupjChphMmzvm55djtgMDPr+eovPDdTnyGvShf73cvydfoBfWDFllooIQ4IaiUL5yfxHRwU0c37EA==}
@@ -2917,13 +4522,17 @@ packages:
     resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==}
     engines: {node: '>=6.5'}
 
+  accepts@2.0.0:
+    resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
+    engines: {node: '>= 0.6'}
+
   acorn-jsx@5.3.2:
     resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
     peerDependencies:
       acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
 
-  acorn@8.15.0:
-    resolution: {integrity: sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==}
+  acorn@8.16.0:
+    resolution: {integrity: sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==}
     engines: {node: '>=0.4.0'}
     hasBin: true
 
@@ -2931,12 +4540,14 @@ packages:
     resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
     engines: {node: '>= 14'}
 
-  agentkeepalive@4.6.0:
-    resolution: {integrity: sha512-kja8j7PjmncONqaTsB8fQ+wE2mSU2DJ9D4XKoJ5PFWIdRMa6SLSN1ff4mOr4jCbfRSsxR4keIiySJU0N9T5hIQ==}
-    engines: {node: '>= 8.0.0'}
+  ai@6.0.17:
+    resolution: {integrity: sha512-Lfv5s4SKvKOLfXPxgVoXvE39adKVq9JE5DpUODRSg7Sd0loVIEDLeUIooXI22WBvt90+YvYRIHvc1s1ZlpY6xQ==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      zod: ^3.25.76 || ^4.1.8
 
-  ai@5.0.62:
-    resolution: {integrity: sha512-IZ5H0rIgwoMx/H9hdZnjW0AjXDMhJnPZlnl+xzfP3vsG76+4k/vYJBYJ4kbKAGCRhaErhc2sK22bSegpXqnhEQ==}
+  ai@6.0.33:
+    resolution: {integrity: sha512-bVokbmy2E2QF6Efl+5hOJx5MRWoacZ/CZY/y1E+VcewknvGlgaiCzMu8Xgddz6ArFJjiMFNUPHKxAhIePE4rmg==}
     engines: {node: '>=18'}
     peerDependencies:
       zod: ^3.25.76 || ^4.1.8
@@ -2973,6 +4584,10 @@ packages:
   ajv@8.17.1:
     resolution: {integrity: sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==}
 
+  am-i-vibing@0.4.0:
+    resolution: {integrity: sha512-MxT4XZL7pzLHpuvhDKdMaQHMGGkJDLluKBLsbstn+8wv9sWcFT6h+0ve9qkml95amVTZtZV83gQe2hY+ojgHLg==}
+    hasBin: true
+
   ansi-align@3.0.1:
     resolution: {integrity: sha512-IOfwwBF5iczOjp/WeY4YxyjqAFMQoZufdQWDd19SEExbVLNXqvpzSJ/M7Za4/sCPmQ0+GRquoA7bGcINcxew6w==}
 
@@ -2988,14 +4603,14 @@ packages:
     resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
     engines: {node: '>=12'}
 
+  ansi-styles@3.2.1:
+    resolution: {integrity: sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==}
+    engines: {node: '>=4'}
+
   ansi-styles@4.3.0:
     resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
     engines: {node: '>=8'}
 
-  ansi-styles@5.2.0:
-    resolution: {integrity: sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==}
-    engines: {node: '>=10'}
-
   ansi-styles@6.2.3:
     resolution: {integrity: sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==}
     engines: {node: '>=12'}
@@ -3043,30 +4658,52 @@ packages:
     resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
     engines: {node: '>=12'}
 
+  ast-types@0.16.1:
+    resolution: {integrity: sha512-6t10qk83GOG8p0vKmaCr8eiilZwO171AvbROMtvvNiwrTly62t+7XkA8RdIIVbpMhCASAsxgAzdRSwh6nw/5Dg==}
+    engines: {node: '>=4'}
+
   astring@1.9.0:
     resolution: {integrity: sha512-LElXdjswlqjWrPpJFg1Fx4wpkOCxj1TDHlSV4PlaRxHGWko024xICaa97ZkMfs6DRKlCguiAI+rbXv5GWwXIkg==}
     hasBin: true
 
-  astro-compress@2.3.8:
-    resolution: {integrity: sha512-XajjEtSTJuVRBOrtZ/Siavd4KcH47SEHo0XoZZeYVRF6BODSBqxVdtlfkqYJKM+F4XRUmLDS5ncVTILnQYvvXw==}
+  astro-compress@2.4.0:
+    resolution: {integrity: sha512-Vmh/HHoufajKORla9pAWToiENe5Ivqh3Dg5jA81qQ84sLfXOXGJcHT+2rz3KW35vL96ym968AUD8taFGrYHthw==}
+
+  astro-expressive-code@0.41.7:
+    resolution: {integrity: sha512-hUpogGc6DdAd+I7pPXsctyYPRBJDK7Q7d06s4cyP0Vz3OcbziP3FNzN0jZci1BpCvLn9675DvS7B9ctKKX64JQ==}
+    peerDependencies:
+      astro: ^4.0.0-beta || ^5.0.0-beta || ^3.3.0 || ^6.0.0-beta
 
-  astro-expressive-code@0.41.3:
-    resolution: {integrity: sha512-u+zHMqo/QNLE2eqYRCrK3+XMlKakv33Bzuz+56V1gs8H0y6TZ0hIi3VNbIxeTn51NLn+mJfUV/A0kMNfE4rANw==}
+  astro-expressive-code@0.44.0:
+    resolution: {integrity: sha512-b1wN/ZvbJprzxlGKIpIes2kQrCY5KRLwys2tWbZAZyjGZcW5ZtgneZnBwzNRiBna9/48d4mQl19KLjcRuhO1hw==}
     peerDependencies:
-      astro: ^4.0.0-beta || ^5.0.0-beta || ^3.3.0
+      astro: ^4.0.0-beta || ^5.0.0-beta || ^3.3.0 || ^6.0.0-beta || ^7.0.0
 
   astro-seo@0.8.4:
     resolution: {integrity: sha512-Ou1vzQSXAxa0K8rtNtXNvSpYqOGEgMhh0immMxJeXmbVZac3UKCNWAoXWyOQDFYsZvBugCRSg0N1phBqPMVgCw==}
 
-  astro@5.16.0:
-    resolution: {integrity: sha512-GaDRs2Mngpw3dr2vc085GnORh98NiXxwIjg/EoQQQl/icZt3Z7s0BRsYHDZ8swkZbOA6wZsqWJdrNirl+iKcDg==}
-    engines: {node: 18.20.8 || ^20.3.0 || >=22.0.0, npm: '>=9.6.5', pnpm: '>=7.1.0'}
+  astro@6.0.2:
+    resolution: {integrity: sha512-aYCU9QcaV3QlOxO+JU2lR4xazVuPaH7oFhc990H/fhbWLMm1MWlRnjfnti1gYMm9N9l7gqPb3t7JsQBlUEQXIg==}
+    engines: {node: ^20.19.1 || >=22.12.0, npm: '>=9.6.5', pnpm: '>=7.1.0'}
     hasBin: true
 
+  astro@7.0.3:
+    resolution: {integrity: sha512-CK+G+Tl2DMV1EXCwVG45vyurxf2IfRTklMxDhRKn+tst9Yl8rWXpudL62Fa6zin5Bt968FBvuyASj1aJShROZg==}
+    engines: {node: '>=22.12.0', npm: '>=9.6.5', pnpm: '>=7.1.0'}
+    hasBin: true
+    peerDependencies:
+      '@astrojs/markdown-remark': 7.2.0
+    peerDependenciesMeta:
+      '@astrojs/markdown-remark':
+        optional: true
+
   async-function@1.0.0:
     resolution: {integrity: sha512-hsU18Ae8CDTR6Kgu9DYf0EbCr/a5iGL0rytQDobUcdpYOKokk8LEjVphnXkDkgpi0wYVsqrXuP0bZxJaTqdgoA==}
     engines: {node: '>= 0.4'}
 
+  async-retry@1.3.1:
+    resolution: {integrity: sha512-aiieFW/7h3hY0Bq5d+ktDBejxuwR78vRu9hDUdR8rNhSaQ29VzPL4AoIRG7D/c7tdenwOcKvgPM6tIxB3cB6HA==}
+
   asynckit@0.4.0:
     resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==}
 
@@ -3080,13 +4717,6 @@ packages:
       '@auth/core': ^0.37.3
       astro: '>=4.0.0'
 
-  autoprefixer@10.4.21:
-    resolution: {integrity: sha512-O+A6LWV5LDHSJD3LjHYoNi4VLsj/Whi7k6zG12xTYaU4cQ8oxQGckXNX8cRHK5yOZ/ppVHe0ZBXGzSV9jXdVbQ==}
-    engines: {node: ^10 || ^12 || >=14}
-    hasBin: true
-    peerDependencies:
-      postcss: ^8.1.0
-
   available-typed-arrays@1.0.7:
     resolution: {integrity: sha512-wvUjBtSGN7+7SjNpq/9M2Tg350UZD3q62IFZLbRAR1bSMlCo1ZaeW+BJ+D090e4hIIZLBcTDWe4Mh4jvUDajzQ==}
     engines: {node: '>= 0.4'}
@@ -3095,8 +4725,8 @@ packages:
     resolution: {integrity: sha512-yOA4wFeI7ET3v32Di/sUybQ+ttP20JHSW3mxLuNGeO0uD6PPcvLrIQXSvy/rhJOWU5JrYh7U4OHplWMmtAtjMg==}
     engines: {node: '>=0.11'}
 
-  axios@1.12.2:
-    resolution: {integrity: sha512-vMJzPewAlRyOgxV2dU0Cuz2O8zzzx9VYtbJOaBgXFeLc4IV/Eg50n4LowmehOOR61S8ZMpc2K5Sa7g6A4jfkUw==}
+  axios@1.15.2:
+    resolution: {integrity: sha512-wLrXxPtcrPTsNlJmKjkPnNPK2Ihe0hn0wGSaTEiHRPxwjvJwT3hKmXF4dpqxmPO9SoNb2FsYXj/xEo0gHN+D5A==}
 
   axobject-query@4.1.0:
     resolution: {integrity: sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==}
@@ -3108,8 +4738,9 @@ packages:
   balanced-match@1.0.2:
     resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==}
 
-  base-64@1.0.0:
-    resolution: {integrity: sha512-kwDPIFCGx0NZHog36dj+tHiwP4QMzsZ3AgMViUBKI0+V5n4U0ufTCUMhnQ04diaRI8EX/QcPfql7zlhZ7j4zgg==}
+  balanced-match@4.0.4:
+    resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
+    engines: {node: 18 || 20 || >=22}
 
   base64-js@1.5.1:
     resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==}
@@ -3121,6 +4752,9 @@ packages:
   bcp-47-match@2.0.3:
     resolution: {integrity: sha512-JtTezzbAibu8G0R9op9zb3vcWZd9JF6M0xOYGPn0fNCd7wOpRB1mU2mH9T8gaBGbAAyIIVgB2G7xG0GP98zMAQ==}
 
+  bcp-47@2.1.0:
+    resolution: {integrity: sha512-9IIS3UPrvIa1Ej+lVDdDwO7zLehjqsaByECw0bu2RRGP73jALm6FYbzI5gWbgHLvNdkvfXB5YrSbocZdOS0c0w==}
+
   better-path-resolve@1.0.0:
     resolution: {integrity: sha512-pbnl5XzGBdrFU/wT4jqmJVPn2B6UHPBOhzMQkY/SPUPB6QtUXtmBHBIwCbXJol93mOpGMnQyP/+BB19q04xj7g==}
     engines: {node: '>=4'}
@@ -3132,13 +4766,21 @@ packages:
     resolution: {integrity: sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==}
     engines: {node: '>=8'}
 
+  bippy@0.3.34:
+    resolution: {integrity: sha512-vmptmU/20UdIWHHhq7qCSHhHzK7Ro3YJ1utU0fBG7ujUc58LEfTtilKxcF0IOgSjT5XLcm7CBzDjbv4lcKApGQ==}
+    peerDependencies:
+      react: '>=17.0.1'
+
+  bl@4.1.0:
+    resolution: {integrity: sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==}
+
+  body-parser@2.2.2:
+    resolution: {integrity: sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA==}
+    engines: {node: '>=18'}
+
   boolbase@1.0.0:
     resolution: {integrity: sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==}
 
-  boolean@3.2.0:
-    resolution: {integrity: sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw==}
-    deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.
-
   boxen@7.1.1:
     resolution: {integrity: sha512-2hCgjEmP8YLWQ130n2FerGv7rYpfBmnmp9Uy2Le1vge6X3gZIfSmEzP5QTDElFxcvVcXlEn8Aq6MU/PZygIOog==}
     engines: {node: '>=14.16'}
@@ -3153,13 +4795,14 @@ packages:
   brace-expansion@2.0.2:
     resolution: {integrity: sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==}
 
+  brace-expansion@5.0.3:
+    resolution: {integrity: sha512-fy6KJm2RawA5RcHkLa1z/ScpBeA762UF9KmZQxwIbDtRJrgLzM10depAiEQ+CXYcoiqW1/m96OAAoke2nE9EeA==}
+    engines: {node: 18 || 20 || >=22}
+
   braces@3.0.3:
     resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==}
     engines: {node: '>=8'}
 
-  brotli@1.3.3:
-    resolution: {integrity: sha512-oTKjJdShmDuGW94SyyaoQvAjf30dZaHnjJ8uAF+u2/vGJkJbJPJAT1gDiOJP5v1Zb6f9KEyW/1HpuaWIXtGHPg==}
-
   browserslist@4.26.3:
     resolution: {integrity: sha512-lAUU+02RFBuCKQPj/P6NgjlbCnLBMp4UtgTx7vNHd3XSIJF87s9a5rA3aH2yw3GS9DqZAUbOtZdCCiZeVRqt0w==}
     engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
@@ -3171,12 +4814,26 @@ packages:
   buffer-from@1.1.2:
     resolution: {integrity: sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==}
 
+  buffer@5.7.1:
+    resolution: {integrity: sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==}
+
+  builtins@1.0.3:
+    resolution: {integrity: sha512-uYBjakWipfaO/bXI7E8rq6kpwHRZK5cNYrUv2OzZSI/FvmdMyXJ2tG9dKcjEC5YHmHpUAwsargWIZNWdxb/bnQ==}
+
+  bundle-name@4.1.0:
+    resolution: {integrity: sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==}
+    engines: {node: '>=18'}
+
   bundle-require@5.1.0:
     resolution: {integrity: sha512-3WrrOuZiyaaZPWiEt4G3+IffISVC9HYlWueJEBWED4ZH4aIAC2PnkdnuRrR94M+w6yGWn4AglWtJtBI8YqvgoA==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
     peerDependencies:
       esbuild: '>=0.18'
 
+  bytes@3.1.2:
+    resolution: {integrity: sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==}
+    engines: {node: '>= 0.8'}
+
   cac@6.7.14:
     resolution: {integrity: sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==}
     engines: {node: '>=8'}
@@ -3196,14 +4853,6 @@ packages:
   camel-case@4.1.2:
     resolution: {integrity: sha512-gxGWBrTT1JuMx6R+o5PTXMmUnhnVzLQ9SNutD4YqKtI6ap897t3tKECYla6gCWEkplXnlNybEkZg9GEGxKFCgw==}
 
-  camelcase-css@2.0.1:
-    resolution: {integrity: sha512-QOSvevhslijgYwRx6Rv7zKdMF8lbRmx+uQGx2+vDc+KI/eBnsy9kit5aj23AgGu3pa4t9AgwbnXWqS+iOY+2aA==}
-    engines: {node: '>= 6'}
-
-  camelcase@6.3.0:
-    resolution: {integrity: sha512-Gmy6FhYlCY7uOElZUSbxo2UCDH8owEk996gkbrpsgGtrJLM3J7jGxl9Ic7Qwwj4ivOE5AWZWRMecDdF7hqGjFA==}
-    engines: {node: '>=10'}
-
   camelcase@7.0.1:
     resolution: {integrity: sha512-xlx1yCK2Oc1APsPXDL2LdlNP6+uu8OCDdhOBSVT279M/S+y75O30C2VuD8T2ogdePBBl7PfPF4504tnLgX3zfw==}
     engines: {node: '>=14.16'}
@@ -3222,10 +4871,22 @@ packages:
     resolution: {integrity: sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==}
     engines: {node: '>=18'}
 
+  chai@6.2.2:
+    resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
+    engines: {node: '>=18'}
+
+  chalk@2.4.2:
+    resolution: {integrity: sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==}
+    engines: {node: '>=4'}
+
   chalk@4.1.2:
     resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
     engines: {node: '>=10'}
 
+  chalk@5.3.0:
+    resolution: {integrity: sha512-dLitG79d+GV1Nb/VYcCDFivJeK1hiukt9QjRNVOsUtTy1rR1YJsmpGGTZ3qJos+uw7WmWF4wUwBd9jxjocFC2w==}
+    engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
+
   chalk@5.6.2:
     resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
     engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
@@ -3266,6 +4927,9 @@ packages:
   chevrotain@11.0.3:
     resolution: {integrity: sha512-ci2iJH6LeIkvP9eJW6gpueU8cnZhv85ELY8w8WiFtNjMHA5ad6pQLaJo9mEly/9qUyCpvqX8/POVUTf18/HFdw==}
 
+  chevrotain@11.1.2:
+    resolution: {integrity: sha512-opLQzEVriiH1uUQ4Kctsd49bRoFDXGGSC4GUqj7pGyxM3RehRhvTlZJc1FL/Flew2p5uwxa1tUDWKzI4wNM8pg==}
+
   chokidar@3.6.0:
     resolution: {integrity: sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==}
     engines: {node: '>= 8.10.0'}
@@ -3274,16 +4938,16 @@ packages:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
 
-  chownr@3.0.0:
-    resolution: {integrity: sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==}
-    engines: {node: '>=18'}
+  chokidar@5.0.0:
+    resolution: {integrity: sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw==}
+    engines: {node: '>= 20.19.0'}
 
   ci-info@3.9.0:
     resolution: {integrity: sha512-NIxF55hv4nSqQswkAeiOi1r83xy8JldOFDTWiug55KBu9Jnblncd2U6ViHmYgHf01TPZS77NJBhBMKdWj9HQMQ==}
     engines: {node: '>=8'}
 
-  ci-info@4.3.1:
-    resolution: {integrity: sha512-Wdy2Igu8OcBpI2pZePZ5oWjPC38tmDVx5WKUXKwlLYkA0ozo85sLsLvkBbBn/sZaSCMFOGZJ14fvW9t5/d7kdA==}
+  ci-info@4.4.0:
+    resolution: {integrity: sha512-77PSwercCZU2Fc4sX94eF8k8Pxte6JAwL4/ICZLFjJLqegs7kCuAsqqj/70NQF6TvDpgFjkubQB2FW2ZZddvQg==}
     engines: {node: '>=8'}
 
   classcat@5.0.5:
@@ -3297,6 +4961,10 @@ packages:
     resolution: {integrity: sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g==}
     engines: {node: '>=10'}
 
+  cli-cursor@3.1.0:
+    resolution: {integrity: sha512-I/zHAwsKf9FqGoXM4WWRACob9+SNukZTd94DWF57E4toouRulbCxcUh6RKUEOQlYTHJnzkPMySvPNaaSLNfLZw==}
+    engines: {node: '>=8'}
+
   cli-cursor@5.0.0:
     resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
     engines: {node: '>=18'}
@@ -3309,34 +4977,36 @@ packages:
     resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==}
     engines: {node: '>=12'}
 
-  clone@2.1.2:
-    resolution: {integrity: sha512-3Pe/CF1Nn94hyhIYpjtiLhdCoEoz0DqQ+988E9gmeEdQZlojxnOb74wctFyuwWQHzqyf9X7C7MG8juUpqBJT8w==}
+  clone@1.0.4:
+    resolution: {integrity: sha512-JQHZ2QMW6l3aH/j6xCqQThY/9OH4D/9ls34cgkUBiEeocRTU04tHfKPBsUK1PqZCUQM7GiA0IIXJSuXHI64Kbg==}
     engines: {node: '>=0.8'}
 
   clsx@2.1.1:
     resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==}
     engines: {node: '>=6'}
 
-  codemirror@6.0.2:
-    resolution: {integrity: sha512-VhydHotNW5w1UGK0Qj96BwSk/Zqbp9WbnyK2W/eVMv4QyF41INRGpjUhFJY7/uDNuudSc33a/PKr4iDqRduvHw==}
+  cmdk@1.1.1:
+    resolution: {integrity: sha512-Vsv7kFaXm+ptHDMZ7izaRsP70GgrW9NBNGswt9OZaVBLlE0SNpDq8eu/VGXyF9r7M0azK3Wy7OlYXsuyYLFzHg==}
+    peerDependencies:
+      react: ^18 || ^19 || ^19.0.0-rc
+      react-dom: ^18 || ^19 || ^19.0.0-rc
 
   collapse-white-space@2.1.0:
     resolution: {integrity: sha512-loKTxY1zCOuG4j9f6EPnuyyYkf58RnhhWTvRoZEokgB+WbdXehfjFviyOVYkqzEWz1Q5kRiZdBYS5SwxbQYwzw==}
 
+  color-convert@1.9.3:
+    resolution: {integrity: sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==}
+
   color-convert@2.0.1:
     resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
     engines: {node: '>=7.0.0'}
 
+  color-name@1.1.3:
+    resolution: {integrity: sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==}
+
   color-name@1.1.4:
     resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
 
-  color-string@1.9.1:
-    resolution: {integrity: sha512-shrVawQFojnZv6xM40anx4CkoDP+fZsw/ZerEMsW/pyzsRbElpsL/DBVW7q3ExxwusdNXI3lXpuhEZkzs8p5Eg==}
-
-  color@4.2.3:
-    resolution: {integrity: sha512-1rXeuUUiGGrykh+CeBdu5Ie7OJwinCgQY0bc7GCRxy5xVHy+moaqkpL/jqQq0MtQOeYcrqEz4abc5f0KtU7W4A==}
-    engines: {node: '>=12.5.0'}
-
   combined-stream@1.0.8:
     resolution: {integrity: sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==}
     engines: {node: '>= 0.8'}
@@ -3351,6 +5021,10 @@ packages:
     resolution: {integrity: sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug==}
     engines: {node: '>=14'}
 
+  commander@11.0.0:
+    resolution: {integrity: sha512-9HMlXtt/BNoYr8ooyjjNRdIilOTkVJXB+GhxMTtOKwk0R4j4lS4NpjuqmRxroBfnfTSHQIHQB7wryHhXarNjmQ==}
+    engines: {node: '>=16'}
+
   commander@11.1.0:
     resolution: {integrity: sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ==}
     engines: {node: '>=16'}
@@ -3359,12 +5033,12 @@ packages:
     resolution: {integrity: sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==}
     engines: {node: '>=18'}
 
-  commander@13.1.0:
-    resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
-    engines: {node: '>=18'}
+  commander@14.0.3:
+    resolution: {integrity: sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==}
+    engines: {node: '>=20'}
 
-  commander@2.20.3:
-    resolution: {integrity: sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==}
+  commander@2.20.0:
+    resolution: {integrity: sha512-7j2y+40w61zy6YC2iRNpUe/NwhNyoXrYpHMrSunaMG64nRnaf96zO/KMQR4OyN/UnE5KLyEBnKHd4aG3rskjpQ==}
 
   commander@4.1.1:
     resolution: {integrity: sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==}
@@ -3378,8 +5052,9 @@ packages:
     resolution: {integrity: sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==}
     engines: {node: '>= 12'}
 
-  common-ancestor-path@1.0.1:
-    resolution: {integrity: sha512-L3sHRo1pXXEqX8VU28kfgUY+YGsk09hPqZiZmLacNib6XNTCM8ubYeT7ryXQw8asB1sKgcU5lkB7ONug08aB8w==}
+  common-ancestor-path@2.0.0:
+    resolution: {integrity: sha512-dnN3ibLeoRf2HNC+OlCiNc5d2zxbLJXOtiZUudNFSXZrNSydxcCsSpRzXwfu7BBWCIfHPw+xTayeBvJCP/D8Ng==}
+    engines: {node: '>= 18'}
 
   concat-map@0.0.1:
     resolution: {integrity: sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==}
@@ -3406,29 +5081,57 @@ packages:
     resolution: {integrity: sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==}
     engines: {node: ^14.18.0 || >=16.10.0}
 
-  console-table-printer@2.14.6:
-    resolution: {integrity: sha512-MCBl5HNVaFuuHW6FGbL/4fB7N/ormCy+tQ+sxTrF6QtSbSNETvPuOVbkJBhzDgYhvjWGrTma4eYJa37ZuoQsPw==}
+  content-disposition@1.0.1:
+    resolution: {integrity: sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q==}
+    engines: {node: '>=18'}
 
   content-type@1.0.5:
     resolution: {integrity: sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==}
     engines: {node: '>= 0.6'}
 
+  convert-hrtime@5.0.0:
+    resolution: {integrity: sha512-lOETlkIeYSJWcbbcvjRKGxVMXJR+8+OQb/mTPbA4ObPMytYIsUbuOE0Jzy60hjARYszq1id0j8KgVhC+WGZVTg==}
+    engines: {node: '>=12'}
+
   convert-source-map@2.0.0:
     resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
 
   cookie-es@1.2.2:
     resolution: {integrity: sha512-+W7VmiVINB+ywl1HGXJXmrqkOhpKrIiVZV6tQuV54ZyQC7MMuBt81Vc336GMLoHBq5hV/F9eXgt5Mnx0Rha5Fg==}
 
-  cookie@1.0.2:
-    resolution: {integrity: sha512-9Kr/j4O16ISv8zBBhJoi4bXOYNTkFLOqSL3UDB0njXxCXNezjeyVrJyGOWtgfs/q2km1gwBcfH8q1yEGoMYunA==}
+  cookie-es@1.2.3:
+    resolution: {integrity: sha512-lXVyvUvrNXblMqzIRrxHb57UUVmqsSWlxqt3XIjCkUP0wDAf6uicO6KMbEgYrMNtEvWgWHwe42CKxPu9MYAnWw==}
+
+  cookie-signature@1.2.2:
+    resolution: {integrity: sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==}
+    engines: {node: '>=6.6.0'}
+
+  cookie@0.7.2:
+    resolution: {integrity: sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==}
+    engines: {node: '>= 0.6'}
+
+  cookie@1.1.1:
+    resolution: {integrity: sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==}
     engines: {node: '>=18'}
 
+  copy-file@11.1.0:
+    resolution: {integrity: sha512-X8XDzyvYaA6msMyAM575CUoygY5b44QzLcGRKsK3MFmXcOvQa518dNPLsKYwkYsn72g3EiW+LE0ytd/FlqWmyw==}
+    engines: {node: '>=18'}
+
+  cors@2.8.5:
+    resolution: {integrity: sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g==}
+    engines: {node: '>= 0.10'}
+
   cose-base@1.0.3:
     resolution: {integrity: sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg==}
 
   cose-base@2.2.0:
     resolution: {integrity: sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==}
 
+  cpy@11.1.0:
+    resolution: {integrity: sha512-QGHetPSSuprVs+lJmMDcivvrBwTKASzXQ5qxFvRC2RFESjjod71bDvFvhxTjDgkNjrrb72AI6JPjfYwxrIy33A==}
+    engines: {node: '>=18'}
+
   crelt@1.0.6:
     resolution: {integrity: sha512-VQ2MBenTq1fWZUH9DJNGti7kKv6EeAuYr3cLwxUWhIu1baTaXh4Ib5W2CqHVqib4/MqbYGJqiL3Zb8GJZr3l4g==}
 
@@ -3437,6 +5140,10 @@ packages:
     engines: {node: '>=10.14', npm: '>=6', yarn: '>=1'}
     hasBin: true
 
+  cross-spawn@6.0.6:
+    resolution: {integrity: sha512-VqCUuhcd1iB+dsv8gxPttb5iZh/D0iubSP21g36KXdEuf6I5JiioesUVjpCdHV9MZRUfVFlvwtIUyPfxo5trtw==}
+    engines: {node: '>=4.8'}
+
   cross-spawn@7.0.6:
     resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
     engines: {node: '>= 8'}
@@ -3454,10 +5161,6 @@ packages:
     resolution: {integrity: sha512-OA0mILzGc1kCOCSJerOeqDxDQ4HOh+G8NbOJFOTgOCzpw7fCBubk0fEyxp8AgOL/jvLgYA/uV0cMbe43ElF1JA==}
     engines: {node: ^10 || ^12.20.0 || ^14.13.0 || >=15.0.0, npm: '>=7.0.0'}
 
-  css-tree@2.3.1:
-    resolution: {integrity: sha512-6Fv1DV/TYw//QF5IzQdqsNDjx/wc8TrMBZsqjL9eW01tWb7R7k/mq+/VXfJCl7SoD5emsJop9cOByJZfs8hYIw==}
-    engines: {node: ^10 || ^12.20.0 || ^14.13.0 || >=15.0.0}
-
   css-tree@3.1.0:
     resolution: {integrity: sha512-0eW44TGN5SQXU1mWSkKwFstI/22X2bG1nYzZTYMAWjylYURhse752YgbE4Cx46AC+bAvI+/dYTPRk1LqSUnu6w==}
     engines: {node: ^10 || ^12.20.0 || ^14.13.0 || >=15.0.0}
@@ -3479,13 +5182,13 @@ packages:
     resolution: {integrity: sha512-g5PC9Aiph9eiczFpcgUhd9S4UUO3F+LHGRIi5NUMZ+4xtoIYbHNZwZnWA2JsFGe8OU8nl4WyaEFiZuGuxlutJQ==}
     engines: {node: '>=20'}
 
-  csstype@3.1.3:
-    resolution: {integrity: sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==}
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
 
-  cva@1.0.0-beta.2:
-    resolution: {integrity: sha512-dqcOFe247I5pKxfuzqfq3seLL5iMYsTgo40Uw7+pKZAntPgFtR7Tmy59P5IVIq/XgB0NQWoIvYDt9TwHkuK8Cg==}
+  cva@1.0.0-beta.4:
+    resolution: {integrity: sha512-F/JS9hScapq4DBVQXcK85l9U91M6ePeXoBMSp7vypzShoefUBxjQTo3g3935PUHgQd+IW77DjbPRIxugy4/GCQ==}
     peerDependencies:
-      typescript: '>= 4.5.5 < 6'
+      typescript: '>= 4.5.5'
     peerDependenciesMeta:
       typescript:
         optional: true
@@ -3643,8 +5346,8 @@ packages:
     resolution: {integrity: sha512-e1U46jVP+w7Iut8Jt8ri1YsPOvFpg46k+K8TpCb0P+zjCkjkPnV7WzfDJzMHy1LnA+wj5pLT1wjO901gLXeEhA==}
     engines: {node: '>=12'}
 
-  dagre-d3-es@7.0.11:
-    resolution: {integrity: sha512-tvlJLyQf834SylNKax8Wkzco/1ias1OPw8DcUMDE7oUIoSEW25riQVuiu/0OWEFqT0cxHT3Pa9/D82Jr47IONw==}
+  dagre-d3-es@7.0.13:
+    resolution: {integrity: sha512-efEhnxpSuwpYOKRm/L5KbqoZmNNukHa/Flty4Wp62JRvgH2ojwVgPgdYyr4twpieZnyRDdIH7PY2mopX26+j2Q==}
 
   dagre@0.8.5:
     resolution: {integrity: sha512-/aTqmnRta7x7MCCpExk7HQL2O4owCT2h8NT//9I1OQ9vt29Pa0BzSAkR5lwFUcQ7491yVi/3CXU9jQ5o0Mn2Sw==}
@@ -3669,9 +5372,6 @@ packages:
     resolution: {integrity: sha512-fnULvOpxnC5/Vg3NCiWelDsLiUc9bRwAPs/+LfTLNvetFCtCTN+yQz15C/fs4AwX1R9K5GLtLfn8QW+dWisaAw==}
     engines: {node: '>=0.11'}
 
-  date-fns@4.1.0:
-    resolution: {integrity: sha512-Ukq0owbQXxa/U3EGtsdVBkR1w7KOQ5gIBqdH2hkvknzZPYvBxb/aa6E8L7tmjFtkwZBu3UXBbjIgPo/Ez4xaNg==}
-
   dayjs@1.11.18:
     resolution: {integrity: sha512-zFBQ7WFRvVRhKcWoUh+ZA1g2HVgUbsZm9sbddh8EC5iv93sui8DVVz1Npvz+r6meo9VKfa8NyLWBsQK1VvIKPA==}
 
@@ -3684,10 +5384,6 @@ packages:
       supports-color:
         optional: true
 
-  decamelize@1.2.0:
-    resolution: {integrity: sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==}
-    engines: {node: '>=0.10.0'}
-
   decimal.js@10.6.0:
     resolution: {integrity: sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==}
 
@@ -3702,17 +5398,29 @@ packages:
     resolution: {integrity: sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==}
     engines: {node: '>=4.0.0'}
 
-  deep-is@0.1.4:
-    resolution: {integrity: sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==}
-
   deepmerge-ts@7.1.5:
     resolution: {integrity: sha512-HOJkrhaYsweh+W+e74Yn7YStZOilkoPb6fycpwNLKzSPtruFs48nYis0zy5yJz1+ktUhHxoRDJ27RQAWLIJVJw==}
     engines: {node: '>=16.0.0'}
 
+  default-browser-id@5.0.1:
+    resolution: {integrity: sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q==}
+    engines: {node: '>=18'}
+
+  default-browser@5.5.0:
+    resolution: {integrity: sha512-H9LMLr5zwIbSxrmvikGuI/5KGhZ8E2zH3stkMgM5LpOWDutGM2JZaj460Udnf1a+946zc7YBgrqEWwbk7zHvGw==}
+    engines: {node: '>=18'}
+
+  defaults@1.0.4:
+    resolution: {integrity: sha512-eFuaLoy/Rxalv2kr+lqMlUnrDWV+3j4pljOIJgLIhI058IQfWJ7vXhyEIHu+HtC738klGALYxOKDO0bQP3tg8A==}
+
   define-data-property@1.1.4:
     resolution: {integrity: sha512-rBMvIzlpA8v6E+SJZoo++HAYqsLrkg7MSfIinMPFhmkorw7X+dOXVJQs+QT69zGkzMyfDnIMN2Wid1+NbL3T+A==}
     engines: {node: '>= 0.4'}
 
+  define-lazy-prop@3.0.0:
+    resolution: {integrity: sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==}
+    engines: {node: '>=12'}
+
   define-properties@1.2.1:
     resolution: {integrity: sha512-8QmQKqEASLd5nx0U1B1okLElbUuuttJ/AnYmRXbbbGDWh6uS208EjD4Xqq/I9wK7u0v6O08XhTWnt5XtEbR6Dg==}
     engines: {node: '>= 0.4'}
@@ -3720,6 +5428,9 @@ packages:
   defu@6.1.4:
     resolution: {integrity: sha512-mEQCMmwJu317oSz8CwdIOdwf3xMif1ttiM8LTufzc3g6kR+9Pe236twL8j3IYT1F7GfRgGcW6MWxzZjLIkuHIg==}
 
+  defu@6.1.7:
+    resolution: {integrity: sha512-7z22QmUWiQ/2d0KkdYmANbRUVABpZ9SNYyH5vx6PZ+nE5bcC0l7uFvEfHlyld/HcGBFTL536ClDt3DEcSlEJAQ==}
+
   delaunator@5.0.1:
     resolution: {integrity: sha512-8nvh+XBe96aCESrGOqMp/84b13H9cdKbG5P2ejQCh4d4sK9RL4371qou9drQjMhvnPmhWl5hnmqbEE0fXr9Xnw==}
 
@@ -3735,6 +5446,10 @@ packages:
     resolution: {integrity: sha512-JeMq7fEshyepOWDfcfHK06N3MhyPhz++vtqWhMT5O9A3K42rdsEDpfdVqjaqaAhsw6a+ZqeDvQVtD0hFHQWrzg==}
     engines: {node: '>= 0.6.0'}
 
+  dependency-graph@1.0.0:
+    resolution: {integrity: sha512-cW3gggJ28HZ/LExwxP2B++aiKxhJXMSIt9K48FOXQkm+vuG5gyatXnLsONRJdzO/7VfjDIiaOOa/bs4l464Lwg==}
+    engines: {node: '>=4'}
+
   dequal@2.0.3:
     resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
     engines: {node: '>=6'}
@@ -3758,35 +5473,21 @@ packages:
   detect-node-es@1.1.0:
     resolution: {integrity: sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==}
 
-  detect-node@2.1.0:
-    resolution: {integrity: sha512-T0NIuQpnTvFDATNuHN5roPwSBG83rFsuO+MXXH9/3N1eFbn4wcPjttvjMLEPWJ0RGUYgQE7cGgS3tNxbqCGM7g==}
-
-  deterministic-object-hash@2.0.2:
-    resolution: {integrity: sha512-KxektNH63SrbfUyDiwXqRb1rLwKt33AmMv+5Nhsw1kqZ13SJBRTgZHtGbE+hH3a1mVW1cz+4pqSWVPAtLVXTzQ==}
-    engines: {node: '>=18'}
+  devalue@5.6.3:
+    resolution: {integrity: sha512-nc7XjUU/2Lb+SvEFVGcWLiKkzfw8+qHI7zn8WYXKkLMgfGSHbgCEaR6bJpev8Cm6Rmrb19Gfd/tZvGqx9is3wg==}
 
-  devalue@5.5.0:
-    resolution: {integrity: sha512-69sM5yrHfFLJt0AZ9QqZXGCPfJ7fQjvpln3Rq5+PS03LD32Ost1Q9N+eEnaQwGRIriKkMImXD56ocjQmfjbV3w==}
+  devalue@5.8.1:
+    resolution: {integrity: sha512-4CXDYRBGqN+57wVJkuXBYmpAVUSg3L6JAQa/DFqm238G73E1wuyc/JhGQJzN7vUf/CMphYau2zXbfWzDR5aTEw==}
 
   devlop@1.1.0:
     resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}
 
-  dfa@1.2.0:
-    resolution: {integrity: sha512-ED3jP8saaweFTjeGX8HQPjeC1YYyZs98jGNZx6IiBvxW7JG5v492kamAQB3m2wop07CvU/RQmzcKr6bgcC5D/Q==}
-
-  didyoumean@1.2.2:
-    resolution: {integrity: sha512-gxtyfqMg7GKyhQmb056K7M3xszy/myH8w+B4RT+QXBQsvAOdc3XymqDDPHx1BgPgsdAA5SIifona89YtRATDzw==}
-
-  diff2html@3.4.52:
-    resolution: {integrity: sha512-qhMg8/I3sZ4zm/6R/Kh0xd6qG6Vm86w6M+C9W+DuH1V8ACz+1cgEC8/k0ucjv6AGqZWzHm/8G1gh7IlrUqCMhg==}
+  diff2html@3.4.56:
+    resolution: {integrity: sha512-u9gfn+BlbHcyO7vItCIC4z49LJDUt31tODzOfAuJ5R1E7IdlRL6KjugcB9zOpejD+XiR+dDZbsnHSQ3g6A/u8A==}
     engines: {node: '>=12'}
 
-  diff@5.2.0:
-    resolution: {integrity: sha512-uIFDxqpRZGZ6ThOk84hEfqWoHx2devRFvpTZcTHur85vImfaxUbTW9Ryh4CpCuDnToOP1CEtXKIgytHBPVff5A==}
-    engines: {node: '>=0.3.1'}
-
-  diff@7.0.0:
-    resolution: {integrity: sha512-PJWHUb1RFevKCwaFA9RlG5tCd+FO5iRh9A8HEtkmBH2Li03iJriB6m6JIN4rGz3K3JLawI7/veA1xzRKP6ISBw==}
+  diff@8.0.3:
+    resolution: {integrity: sha512-qejHi7bcSD4hQAZE0tNAawRK1ZtafHDmMTMkrrIGgSLl7hTnQHmKCeB45xAcbfTqK2zowkM3j3bHt/4b/ARbYQ==}
     engines: {node: '>=0.3.1'}
 
   dir-glob@3.0.1:
@@ -3869,6 +5570,17 @@ packages:
     resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
     engines: {node: '>= 0.8'}
 
+  end-of-stream@1.4.5:
+    resolution: {integrity: sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==}
+
+  enhanced-resolve@5.19.0:
+    resolution: {integrity: sha512-phv3E1Xl4tQOShqSte26C7Fl84EwUdZsyOuSSk9qtAGyyQs2s3jJzComh+Abf4g187lUUAvH+H26omrqia2aGg==}
+    engines: {node: '>=10.13.0'}
+
+  enhanced-resolve@5.21.6:
+    resolution: {integrity: sha512-aNnGCvbJ/RIyWo1IuhNdVjnNF+EjH9wpzpNHt+ci/m9He9LJvUN8wrCcXjp9cWsGNAuvSpVFTx/vraAFQ8qGjQ==}
+    engines: {node: '>=10.13.0'}
+
   enquirer@2.4.1:
     resolution: {integrity: sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ==}
     engines: {node: '>=8.6'}
@@ -3881,6 +5593,10 @@ packages:
     resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}
     engines: {node: '>=0.12'}
 
+  entities@7.0.1:
+    resolution: {integrity: sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==}
+    engines: {node: '>=0.12'}
+
   es-abstract@1.24.0:
     resolution: {integrity: sha512-WSzPgsdLtTcQwm4CROfS5ju2Wa1QQcVeT37jFjYzdFz1r9ahadC8B8/a4qxJxM+09F18iumCdRmlr96ZYkQvEg==}
     engines: {node: '>= 0.4'}
@@ -3900,6 +5616,9 @@ packages:
   es-module-lexer@1.7.0:
     resolution: {integrity: sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==}
 
+  es-module-lexer@2.0.0:
+    resolution: {integrity: sha512-5POEcUuZybH7IdmGsD8wlf0AI55wMecM9rVBTI/qEAy2c1kTOm3DjFYjrBdI2K3BaJjJYfYFeRtM0t9ssnRuxw==}
+
   es-object-atoms@1.1.1:
     resolution: {integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==}
     engines: {node: '>= 0.4'}
@@ -3912,9 +5631,6 @@ packages:
     resolution: {integrity: sha512-w+5mJ3GuFL+NjVtJlvydShqE1eN3h3PbI7/5LAsYJP/2qtuMXjfL2LpHSRqo4b4eSF5K/DH1JXKUAHSB2UW50g==}
     engines: {node: '>= 0.4'}
 
-  es6-error@4.1.1:
-    resolution: {integrity: sha512-Um/+FxMr9CISWh0bi5Zv0iOD+4cFh5qLeks1qhAopKVAJw3drgKbKySikp7wGhDL0HPeaja0P5ULZrxLkniUVg==}
-
   esast-util-from-estree@2.0.0:
     resolution: {integrity: sha512-4CyanoAudUSBAn5K13H4JhsMH6L9ZP7XbLVe/dKybkxMO7eDyLsT8UHl9TRNrU2Gr9nz+FovfSIjuXWJ81uVwQ==}
 
@@ -3931,6 +5647,16 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  esbuild@0.27.3:
+    resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  esbuild@0.28.1:
+    resolution: {integrity: sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   escalade@3.2.0:
     resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
     engines: {node: '>=6'}
@@ -3942,33 +5668,19 @@ packages:
   escape-html@1.0.3:
     resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==}
 
-  escape-string-regexp@4.0.0:
-    resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
-    engines: {node: '>=10'}
+  escape-string-regexp@1.0.5:
+    resolution: {integrity: sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==}
+    engines: {node: '>=0.8.0'}
 
   escape-string-regexp@5.0.0:
     resolution: {integrity: sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==}
     engines: {node: '>=12'}
 
-  escodegen@1.14.3:
-    resolution: {integrity: sha512-qFcX0XJkdg+PB3xjZZG/wKSuT1PnQWx57+TVSjIMmILd2yC/6ByYElPwJnslDsuWuSAp4AwJGumarAAmJch5Kw==}
-    engines: {node: '>=4.0'}
-    hasBin: true
-
-  esprima@1.2.2:
-    resolution: {integrity: sha512-+JpPZam9w5DuJ3Q67SqsMGtiHKENSMRVoxvArfJZK01/BfLEObtZ6orJa/MtoGNR/rfMgp5837T41PAmTwAv/A==}
-    engines: {node: '>=0.4.0'}
-    hasBin: true
-
   esprima@4.0.1:
     resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==}
     engines: {node: '>=4'}
     hasBin: true
 
-  estraverse@4.3.0:
-    resolution: {integrity: sha512-39nnKffWz8xN1BU/2c79n9nB9HDzo0niYUqx6xyqUnyoAnQyyWpOTdZEeiCch8BBu515t4wp9ZmgVfVhn9EBpw==}
-    engines: {node: '>=4.0'}
-
   estree-util-attach-comments@3.0.0:
     resolution: {integrity: sha512-cKUwm/HUcTDsYh/9FgnuFqpfquUbwIqwKM26BVCGDPVgvaCl/nDCCjUfiLlx6lsEZ3Z4RFxNbOQ60pkaEwFxGw==}
 
@@ -3993,10 +5705,6 @@ packages:
   estree-walker@3.0.3:
     resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
 
-  esutils@2.0.3:
-    resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==}
-    engines: {node: '>=0.10.0'}
-
   etag@1.8.1:
     resolution: {integrity: sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==}
     engines: {node: '>= 0.6'}
@@ -4005,9 +5713,6 @@ packages:
     resolution: {integrity: sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==}
     engines: {node: '>=6'}
 
-  eventemitter3@4.0.7:
-    resolution: {integrity: sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw==}
-
   eventemitter3@5.0.1:
     resolution: {integrity: sha512-GWkBvjiSZK87ELrYOSESUYeVIc9mvLLf/nXalMOS5dYrgZq9o5OVkbZAVM06CVxYsCwH9BDZFPlQTlPA1j4ahA==}
 
@@ -4015,12 +5720,33 @@ packages:
     resolution: {integrity: sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg==}
     engines: {node: '>=18.0.0'}
 
+  eventsource@3.0.7:
+    resolution: {integrity: sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==}
+    engines: {node: '>=18.0.0'}
+
+  execa@1.0.0:
+    resolution: {integrity: sha512-adbxcyWV46qiHyvSp50TKt05tB4tK3HcmF7/nxfAdhnox83seTDbwnaqKO4sXRy7roHAIFqJP/Rw/AuEbX61LA==}
+    engines: {node: '>=6'}
+
   expect-type@1.2.2:
     resolution: {integrity: sha512-JhFGDVJ7tmDJItKhYgJCGLOWjuK9vPxiXoUFLwLDc99NlmklilbiQJwoctZtt13+xMw91MCk/REan6MWHqDjyA==}
     engines: {node: '>=12.0.0'}
 
-  expressive-code@0.41.3:
-    resolution: {integrity: sha512-YLnD62jfgBZYrXIPQcJ0a51Afv9h8VlWqEGK9uU2T5nL/5rb8SnA86+7+mgCZe5D34Tff5RNEA5hjNVJYHzrFg==}
+  express-rate-limit@8.2.1:
+    resolution: {integrity: sha512-PCZEIEIxqwhzw4KF0n7QF4QqruVTcF73O5kFKUnGOyjbCCgizBBiFaYpd/fnBLUMPw/BWw9OsiN7GgrNYr7j6g==}
+    engines: {node: '>= 16'}
+    peerDependencies:
+      express: '>= 4.11'
+
+  express@5.2.1:
+    resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==}
+    engines: {node: '>= 18'}
+
+  expressive-code@0.41.7:
+    resolution: {integrity: sha512-2wZjC8OQ3TaVEMcBtYY4Va3lo6J+Ai9jf3d4dbhURMJcU4Pbqe6EcHe424MIZI0VHUA1bR6xdpoHYi3yxokWqA==}
+
+  expressive-code@0.44.0:
+    resolution: {integrity: sha512-JXVWVNCKlLuZLMQH8cOiDUSosT0Bb+elwE/dbAkpwFwDFmyFyWlECoWZIohh2FkIF1iI67TQJ+Ts9k7oNDh2qA==}
 
   exsolve@1.0.7:
     resolution: {integrity: sha512-VO5fQUzZtI6C+vx4w/4BWJpg3s/5l+6pRQEHzFRM8WFi4XffSP1Z+4qi7GbjWbvRQEbdIco5mIMq+zX4rPuLrw==}
@@ -4042,21 +5768,21 @@ packages:
     resolution: {integrity: sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==}
     engines: {node: '>=8.6.0'}
 
-  fast-levenshtein@2.0.6:
-    resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==}
-
   fast-memoize@2.5.2:
     resolution: {integrity: sha512-Ue0LwpDYErFbmNnZSF0UH6eImUwDmogUO1jyE+JbN2gsQz/jICm1Ve7t9QT0rNSsfJt+Hs4/S3GnsDVjL4HVrw==}
 
   fast-uri@3.1.0:
     resolution: {integrity: sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==}
 
+  fast-xml-builder@1.1.4:
+    resolution: {integrity: sha512-f2jhpN4Eccy0/Uz9csxh3Nu6q4ErKxf0XIsasomfOihuSUa3/xw6w8dnOtCDgEItQFJG8KyXPzQXzcODDrrbOg==}
+
   fast-xml-parser@4.5.3:
     resolution: {integrity: sha512-RKihhV+SHsIUGXObeVy9AXiBbFwkVk7Syp8XgwN5U3JV416+Gwp/GO9i0JYKmikykgz/UHRrrV4ROuZEo/T0ig==}
     hasBin: true
 
-  fast-xml-parser@5.3.0:
-    resolution: {integrity: sha512-gkWGshjYcQCF+6qtlrqBqELqNqnt4CxruY6UVAWWnqb3DQ6qaNFEIKqzYep1XzHLM/QtrHVCxyPOtTk4LTQ7Aw==}
+  fast-xml-parser@5.5.10:
+    resolution: {integrity: sha512-go2J2xODMc32hT+4Xr/bBGXMaIoiCwrwp2mMtAvKyvEFW6S/v5Gn2pBmE4nvbwNjGhpcAiOwEv7R6/GZ6XRa9w==}
     hasBin: true
 
   fastq@1.19.1:
@@ -4078,6 +5804,10 @@ packages:
     resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==}
     engines: {node: '>=8'}
 
+  finalhandler@2.1.1:
+    resolution: {integrity: sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==}
+    engines: {node: '>= 18.0.0'}
+
   find-up@4.1.0:
     resolution: {integrity: sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==}
     engines: {node: '>=8'}
@@ -4085,18 +5815,15 @@ packages:
   fix-dts-default-cjs-exports@1.0.1:
     resolution: {integrity: sha512-pVIECanWFC61Hzl2+oOCtoJ3F17kglZC/6N94eRWycFgBH35hHx0Li604ZIzhseh97mf2p0cv7vVrOZGoqhlEg==}
 
-  flatbuffers@25.9.23:
-    resolution: {integrity: sha512-MI1qs7Lo4Syw0EOzUl0xjs2lsoeqFku44KpngfIduHBYvzm8h2+7K8YMQh1JtVVVrUvhLpNwqVi4DERegUJhPQ==}
-
-  flatted@3.3.3:
-    resolution: {integrity: sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==}
+  flatted@3.4.2:
+    resolution: {integrity: sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA==}
 
   flattie@1.1.1:
     resolution: {integrity: sha512-9UbaD6XdAL97+k/n+N7JwX46K/M6Zc6KcFYskrYL8wbBV/Uyk0CTAMY0VT+qiK5PM7AIc9aTWYtq65U7T+aCNQ==}
     engines: {node: '>=8'}
 
-  focus-trap@7.6.5:
-    resolution: {integrity: sha512-7Ke1jyybbbPZyZXFxEftUtxFGLMpE2n6A+z//m4CRDlj0hW+o3iYSmh8nFlYMurOiJVDmJRilUQtJr08KfIxlg==}
+  focus-trap@7.8.0:
+    resolution: {integrity: sha512-/yNdlIkpWbM0ptxno3ONTuf+2g318kh2ez3KSeZN5dZ8YC6AAmgeWz+GasYYiBJPFaYcSAPeu4GfhUaChzIJXA==}
 
   follow-redirects@1.15.11:
     resolution: {integrity: sha512-deG2P0JfjrTxl50XGCDyfI97ZGVCxIpfKYmfyrQ54n5FO/0gfIES8C/Psl6kWVDolizcaaxZJnTS0QSMxvnsBQ==}
@@ -4107,11 +5834,12 @@ packages:
       debug:
         optional: true
 
-  fontace@0.3.1:
-    resolution: {integrity: sha512-9f5g4feWT1jWT8+SbL85aLIRLIXUaDygaM2xPXRmzPYxrOMNok79Lr3FGJoKVNKibE0WCunNiEVG2mwuE+2qEg==}
+  fontace@0.4.1:
+    resolution: {integrity: sha512-lDMvbAzSnHmbYMTEld5qdtvNH2/pWpICOqpean9IgC7vUbUJc3k+k5Dokp85CegamqQpFbXf0rAVkbzpyTA8aw==}
 
-  fontkit@2.0.4:
-    resolution: {integrity: sha512-syetQadaUEDNdxdugga9CpEYVaQIxOwk7GlwZWWZ19//qW4zE5bknOKeMBDYAASwnpaSHKJITRLMF9m1fp3s6g==}
+  fontkitten@1.0.3:
+    resolution: {integrity: sha512-Wp1zXWPVUPBmfoa3Cqc9ctaKuzKAV6uLstRqlR56kSjplf5uAce+qeyYym7F+PHbGTk+tCEdkCW6RD7DX/gBZw==}
+    engines: {node: '>=20'}
 
   for-each@0.3.5:
     resolution: {integrity: sha512-dKx12eRCVIzqCxFGplyFKJMPvLEWgmNtUrpTiJIR5u97zEhRG8ySrtboPHZXx7daLxQVrl643cTzbab2tkQjxg==}
@@ -4124,28 +5852,26 @@ packages:
     resolution: {integrity: sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==}
     engines: {node: '>=14'}
 
-  form-data-encoder@1.7.2:
-    resolution: {integrity: sha512-qfqtYan3rxrnCk1VYaA4H+Ms9xdpPqvLZa6xmMgFvhO32x7/3J/ExcTd6qpxM0vH2GdMI+poehyBZvqfMTto8A==}
-
-  form-data@4.0.4:
-    resolution: {integrity: sha512-KrGhL9Q4zjj0kiUt5OO4Mr/A/jlI2jDYs5eHBpYHPcBEVSiipAvn2Ko2HnPe20rmcuuvMHNdZFp+4IlGTMF0Ow==}
+  form-data@4.0.5:
+    resolution: {integrity: sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==}
     engines: {node: '>= 6'}
 
   format@0.2.2:
     resolution: {integrity: sha512-wzsgA6WOq+09wrU1tsJ09udeR/YZRaeArL9e1wPbFg3GG2yDnC2ldKpxs4xunpFF9DgqCqOIra3bc1HWrJ37Ww==}
     engines: {node: '>=0.4.x'}
 
-  formdata-node@4.4.1:
-    resolution: {integrity: sha512-0iirZp3uVDjVGt9p49aTaqjk84TrglENEDuqfdlZQ1roC9CWlPk6Avf8EEnZNcAqPonwkG35x4n3ww/1THYAeQ==}
-    engines: {node: '>= 12.20'}
-
-  fraction.js@4.3.7:
-    resolution: {integrity: sha512-ZsDfxO51wGAXREY55a7la9LScWpwv9RxIrYABrlvOFBlH/ShPnrtsXeuUIfXKKOVicNxQ+o8JTbJvjS4M89yew==}
+  forwarded@0.2.0:
+    resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==}
+    engines: {node: '>= 0.6'}
 
   fresh@2.0.0:
     resolution: {integrity: sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==}
     engines: {node: '>= 0.8'}
 
+  fs-extra@11.1.1:
+    resolution: {integrity: sha512-MGIE4HOvQCeUCzmlHs0vXpih4ysz4wg9qiSAu6cd42lVwPbTM1TjV7RusoyQqMmk/95gdQZX72u+YW+c3eEpFQ==}
+    engines: {node: '>=14.14'}
+
   fs-extra@11.3.2:
     resolution: {integrity: sha512-Xr9F6z6up6Ws+NjzMCZc6WXg2YFRlrLP9NQDO3VQrWrfiojdhS56TzueT88ze0uBdCTwEIhQ3ptnmKeWGFAe0A==}
     engines: {node: '>=14.14'}
@@ -4158,9 +5884,6 @@ packages:
     resolution: {integrity: sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==}
     engines: {node: '>=6 <7 || >=8'}
 
-  fs.realpath@1.0.0:
-    resolution: {integrity: sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==}
-
   fsevents@2.3.2:
     resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
     engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
@@ -4174,6 +5897,10 @@ packages:
   function-bind@1.1.2:
     resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
 
+  function-timeout@1.0.2:
+    resolution: {integrity: sha512-939eZS4gJ3htTHAldmyyuzlrD58P03fHG49v2JfFXbV6OhvZKRC9j2yAtdHw/zrp2zXHuv05zMIy40F0ge7spA==}
+    engines: {node: '>=18'}
+
   function.prototype.name@1.1.8:
     resolution: {integrity: sha512-e5iwyodOHhbMr/yNrc7fDYG4qlbIvI5gajyzPnb5TCwyhjApznQh1BMFou9b30SevY43gCJKXycoCBjMbsuW0Q==}
     engines: {node: '>= 0.4'}
@@ -4217,10 +5944,21 @@ packages:
     resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==}
     engines: {node: '>= 0.4'}
 
+  get-stream@4.1.0:
+    resolution: {integrity: sha512-GMat4EJ5161kIy2HevLlr4luNjBgvmj413KaQA7jt4V8B4RDsfpHk7WQ9GVqfYyyx8OS/L66Kox+rJRNklLK7w==}
+    engines: {node: '>=6'}
+
   get-symbol-description@1.1.0:
     resolution: {integrity: sha512-w9UMqWwJxHNOvoNzSJ2oPF5wvYcvP7jUvYzhp67yEhTi17ZDBBC1z9pTdGuzjD+EFIqLSYRweZjqfiPzQ06Ebg==}
     engines: {node: '>= 0.4'}
 
+  get-tsconfig@4.13.6:
+    resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
+
+  get-tsconfig@5.0.0-beta.4:
+    resolution: {integrity: sha512-7nF7C9fIPFEMHgEMEfgIlO9wDdZ8CyHw27rWciFZfHvHDReIiPhsYuzPRXsfvBCqFy1l8RRyyWV7QLM+ZhUJsQ==}
+    engines: {node: '>=20.20.0'}
+
   github-slugger@2.0.0:
     resolution: {integrity: sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw==}
 
@@ -4228,26 +5966,24 @@ packages:
     resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}
     engines: {node: '>= 6'}
 
-  glob-parent@6.0.2:
-    resolution: {integrity: sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==}
-    engines: {node: '>=10.13.0'}
-
   glob@10.5.0:
     resolution: {integrity: sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==}
+    deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
     hasBin: true
 
-  glob@11.0.3:
-    resolution: {integrity: sha512-2Nim7dha1KVkaiF4q6Dj+ngPPMdfvLJEOpZk/jKiUAkqKebpGAWQXAq9z1xu9HKu5lWfqw/FASuccEjyznjPaA==}
+  glob@11.1.0:
+    resolution: {integrity: sha512-vuNwKSaKiqm7g0THUBu2x7ckSs3XJLXE+2ssL7/MfTGPLLcrJQ/4Uq1CjPTtO5cCIiRxqvN6Twy1qOwhL0Xjcw==}
     engines: {node: 20 || >=22}
+    deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
     hasBin: true
 
-  glob@7.2.3:
-    resolution: {integrity: sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==}
-    deprecated: Glob versions prior to v9 are no longer supported
+  glob@13.0.2:
+    resolution: {integrity: sha512-035InabNu/c1lW0tzPhAgapKctblppqsKKG9ZaNzbr+gXwWMjXoiyGSyB9sArzrjG7jY+zntRq5ZSUYemrnWVQ==}
+    engines: {node: 20 || >=22}
 
-  global-agent@3.0.0:
-    resolution: {integrity: sha512-PT6XReJ+D07JvGoxQMkT6qji/jVNfX/h364XHZOWeRzy64sSFr+xJ5OX7LI3b4MPQzdL4H8Y8M0xzPpsVMwA8Q==}
-    engines: {node: '>=10.0'}
+  glob@13.0.6:
+    resolution: {integrity: sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==}
+    engines: {node: 18 || 20 || >=22}
 
   global-directory@4.0.1:
     resolution: {integrity: sha512-wHTUcDUoZ1H5/0iVqEudYW4/kAlN5cZ3j/bXn0Dpbizl9iaUVeWSHqiOjsgk6OW2bkLclbBjzewBz6weQ1zA2Q==}
@@ -4265,6 +6001,10 @@ packages:
     resolution: {integrity: sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==}
     engines: {node: '>=10'}
 
+  globby@14.1.0:
+    resolution: {integrity: sha512-0Ia46fDOaT7k4og1PDW4YbodWWr3scS2vAr2lTbsplOt2WkKp0vQbkI9wKis/T5LV/dqPjO3bpS/z6GTJB82LA==}
+    engines: {node: '>=18'}
+
   globrex@0.1.2:
     resolution: {integrity: sha512-uHJgbwAMwNFf5mLst7IWLNg14x1CkeqglJb/K3doi4dw6q2IvAAmM/Y81kevy83wP+Sst+nutFTYOGg3d1lsxg==}
 
@@ -4285,11 +6025,15 @@ packages:
     resolution: {integrity: sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q==}
     engines: {node: '>=6.0'}
 
-  guid-typescript@1.0.9:
-    resolution: {integrity: sha512-Y8T4vYhEfwJOTbouREvG+3XDsjr8E3kIr7uf+JZ0BYloFsttiHU0WfvANVsR7TxNUJa/WpCnw/Ino/p+DeBhBQ==}
+  guess-json-indent@3.0.1:
+    resolution: {integrity: sha512-LWZ3Vr8BG7DHE3TzPYFqkhjNRw4vYgFSsv2nfMuHklAlOfiy54/EwiDQuQfFVLxENCVv20wpbjfTayooQHrEhQ==}
+    engines: {node: '>=18.18.0'}
 
-  h3@1.15.4:
-    resolution: {integrity: sha512-z5cFQWDffyOe4vQ9xIqNfCZdV4p//vy6fBnr8Q1AWnVZ0teurKMG66rLj++TKwKPUP3u7iMUvrvKaEUiQw2QWQ==}
+  h3@1.15.11:
+    resolution: {integrity: sha512-L3THSe2MPeBwgIZVSH5zLdBBU90TOxarvhK9d04IDY2AmVS8j2Jz2LIWtwsGOU3lu2I5jCN7FNvVfY2+XyF+mg==}
+
+  h3@1.15.5:
+    resolution: {integrity: sha512-xEyq3rSl+dhGX2Lm0+eFQIAzlDN6Fs0EcC4f7BNUmzaRX/PTzeuM+Tr2lHB8FoXggsQIeXLj8EDVgs5ywxyxmg==}
 
   hachure-fill@0.5.2:
     resolution: {integrity: sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==}
@@ -4298,6 +6042,10 @@ packages:
     resolution: {integrity: sha512-R3pbpkcIqv2Pm3dUwgjclDRVmWpTJW2DcMzcIhEXEx1oh/CEMObMm3KLmRJOdvhM7o4uQBnwr8pzRK2sJWIqfg==}
     engines: {node: '>= 0.4'}
 
+  has-flag@3.0.0:
+    resolution: {integrity: sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==}
+    engines: {node: '>=4'}
+
   has-flag@4.0.0:
     resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
     engines: {node: '>=8'}
@@ -4400,22 +6148,15 @@ packages:
     resolution: {integrity: sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w==}
     engines: {node: '>=12.0.0'}
 
-  highlight.js@11.9.0:
-    resolution: {integrity: sha512-fJ7cW7fQGCYAkgv4CPfwFHrfd/cLS4Hau96JuJ+ZTOWhjnhoeN1ub1tFmALm/+lW5z4WCAuAV9bm05AP0mS6Gw==}
-    engines: {node: '>=12.0.0'}
-
-  highlightjs-curl@1.3.0:
-    resolution: {integrity: sha512-50UEfZq1KR0Lfk2Tr6xb/MUIZH3h10oNC0OTy9g7WELcs5Fgy/mKN1vEhuKTkKbdo8vr5F9GXstu2eLhApfQ3A==}
-
   highlightjs-vue@1.0.0:
     resolution: {integrity: sha512-PDEfEF102G23vHmPhLyPboFCD+BkMGu+GuJe2d9/eH4FsCwvgBpnc9n0pGE+ffKdph38s6foEZiEjdgHdzp+IA==}
 
-  hogan.js@3.0.2:
-    resolution: {integrity: sha512-RqGs4wavGYJWE07t35JQccByczmNUXQT0E12ZYV1VKYu5UiAU9lsos/yBAcf840+zrUQQxgVduCR5/B8nNtibg==}
-    hasBin: true
+  hono@4.12.25:
+    resolution: {integrity: sha512-2NFaIyNVgJmBs/ecmtGzlmluTFs5cHEWGTdu0t1HBwYzoGXOL5nUQBRMXsXWla5i4KkG//QMzVP88m1+I3fdAQ==}
+    engines: {node: '>=16.9.0'}
 
-  hookable@5.5.3:
-    resolution: {integrity: sha512-Yc+BQe8SvoXH1643Qez1zqLRmbA5rCL+sSmk6TVos0LWVfNIB7PGncdlId77WzLGSIB5KaWgTaNTs2lNVEI6VQ==}
+  hookable@6.1.0:
+    resolution: {integrity: sha512-ZoKZSJgu8voGK2geJS+6YtYjvIzu9AOM/KZXsBxr83uhLL++e9pEv/dlgwgy3dvHg06kTz6JOh1hk3C8Ceiymw==}
 
   html-encoding-sniffer@4.0.0:
     resolution: {integrity: sha512-Y22oTqIU4uuPgEemfz7NDJz6OeKf12Lsu+QC+s3BVpda64lTiMYCyGwg5ki4vFxkMwQdeZDl2adZoqUgdFuTgQ==}
@@ -4444,8 +6185,8 @@ packages:
   http-cache-semantics@4.2.0:
     resolution: {integrity: sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ==}
 
-  http-errors@2.0.0:
-    resolution: {integrity: sha512-FtwrG/euBzaEjYeRqOgly7G0qviiXoJWnvEH2Z1plBdXgbyjv34pHTSb9zoeHMyDy33+DWy5Wt9Wo+TURtOYSQ==}
+  http-errors@2.0.1:
+    resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
     engines: {node: '>= 0.8'}
 
   http-proxy-agent@7.0.2:
@@ -4460,8 +6201,8 @@ packages:
     resolution: {integrity: sha512-v/J+4Z/1eIJovEBdlV5TYj1IR+ZiohcYGRY+qN/oC9dAfKzVT023N/Bgw37hrKCoVRBvk3bqyzpr2PP5YeTMSg==}
     hasBin: true
 
-  humanize-ms@1.2.1:
-    resolution: {integrity: sha512-Fl70vYtsAFb/C06PTS9dZBo7ihau+Tu/DNCk/OyHhea07S+aeMWpFFkUaXRa8fI+ScZbEI8dfSxwY7gxZ9SAVQ==}
+  i18next@23.16.8:
+    resolution: {integrity: sha512-06r/TitrM88Mg5FdUXAKL96dJMzgqLE5dv3ryBAra4KCwD9mJ4ndOTS95ZuymIGoE+2hzfdaMak2X11/es7ZWg==}
 
   iconv-lite@0.6.3:
     resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==}
@@ -4471,20 +6212,24 @@ packages:
     resolution: {integrity: sha512-cf6L2Ds3h57VVmkZe+Pn+5APsT7FpqJtEhhieDCvrE2MK5Qk9MyffgQyuxQTm6BChfeZNtcOLHp9IcWRVcIcBQ==}
     engines: {node: '>=0.10.0'}
 
+  identifier-regex@1.0.1:
+    resolution: {integrity: sha512-ZrYyM0sozNPZlvBvE7Oq9Bn44n0qKGrYu5sQ0JzMUnjIhpgWYE2JB6aBoFwEYdPjqj7jPyxXTMJiHDOxDfd8yw==}
+    engines: {node: '>=18'}
+
+  ieee754@1.2.1:
+    resolution: {integrity: sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==}
+
   ignore@5.3.2:
     resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
     engines: {node: '>= 4'}
 
+  ignore@7.0.5:
+    resolution: {integrity: sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==}
+    engines: {node: '>= 4'}
+
   immer@9.0.21:
     resolution: {integrity: sha512-bc4NBHqOqSfRW7POMkHd51LvClaeMXpm8dx0e8oE2GORbq5aRK7Bxl4FyzVLdGtLmvLKL7BTDBG5ACQm4HWjTA==}
 
-  import-meta-resolve@4.2.0:
-    resolution: {integrity: sha512-Iqv2fzaTQN28s/FwZAoFq0ZSs/7hMAHJVX+w8PZl3cY19Pxk6jFFalxQoIfW2826i/fDLXv8IiEZRIT0lDuWcg==}
-
-  inflight@1.0.6:
-    resolution: {integrity: sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==}
-    deprecated: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.
-
   inherits@2.0.4:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
@@ -4513,6 +6258,14 @@ packages:
     resolution: {integrity: sha512-agE4QfB2Lkp9uICn7BAqoscw4SZP9kTE2hxiFI3jBPmXJfdqiahTbUuKGsMoN2GtqL9AxhYioAcVvgsb1HvRbA==}
     engines: {node: '>= 0.10'}
 
+  ip-address@10.0.1:
+    resolution: {integrity: sha512-NWv9YLW4PoW2B7xtzaS3NCot75m6nK7Icdv0o3lfMceJVRfSoQwqD4wEH5rLwoKJwUiZ/rfpiVBhnaF0FK4HoA==}
+    engines: {node: '>= 12'}
+
+  ipaddr.js@1.9.1:
+    resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
+    engines: {node: '>= 0.10'}
+
   iron-webcrypto@1.2.1:
     resolution: {integrity: sha512-feOM6FaSr6rEABp/eDfVseKyTMDt+KGpeB35SkVn9Tyn0CqvVsY3EwI0v5i8nMHyJnzCIQf7nsy3p41TPkJZhg==}
 
@@ -4536,9 +6289,6 @@ packages:
     resolution: {integrity: sha512-DDfANUiiG2wC1qawP66qlTugJeL5HyzMpfr8lLK+jMQirGzNod0B12cFB/9q838Ru27sBwfw78/rdoU7RERz6A==}
     engines: {node: '>= 0.4'}
 
-  is-arrayish@0.3.4:
-    resolution: {integrity: sha512-m6UrgzFVUYawGBh1dUsWR5M2Clqic9RVXC/9f8ceNlv2IcO9j9J/z8UoCLPqtsPBFNzEpfR3xftohbfqDx8EQA==}
-
   is-async-function@2.1.1:
     resolution: {integrity: sha512-9dgM/cZBnNvjzaMYHVoxxfPj2QXt22Ev7SuuPrs+xav0ukGB0S6d4ydZdEiM48kLx5kDV+QBPrpVnFyefL8kkQ==}
     engines: {node: '>= 0.4'}
@@ -4555,10 +6305,6 @@ packages:
     resolution: {integrity: sha512-wa56o2/ElJMYqjCjGkXri7it5FbebW5usLw/nPmCMs5DeZ7eziSYZhSmPRn0txqeW4LnAmQQU7FgqLpsEFKM4A==}
     engines: {node: '>= 0.4'}
 
-  is-buffer@2.0.5:
-    resolution: {integrity: sha512-i2R6zNFDwgEHJyQUtJEk0XFi1i0dPFn/oqjK3/vPCcDeJvW5NQ83V8QbicfF1SupOaB0h8ntgBC2YiE7dfyctQ==}
-    engines: {node: '>=4'}
-
   is-callable@1.2.7:
     resolution: {integrity: sha512-1BC0BVFhS/p0qtw6enp8e+8OD0UrK0oFLztSjNzhcKA3WDuJxxAPXzPuPtKkjEY9UUoEWlX/8fgKeu2S8i9JTA==}
     engines: {node: '>= 0.4'}
@@ -4586,6 +6332,11 @@ packages:
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
     hasBin: true
 
+  is-docker@4.0.0:
+    resolution: {integrity: sha512-LHE+wROyG/Y/0ZnbktRCoTix2c1RhgWaZraMZ8o1Q7zCh0VSrICJQO5oqIIISrcSBtrXv0o233w1IYwsWCjTzA==}
+    engines: {node: '>=20'}
+    hasBin: true
+
   is-extendable@0.1.1:
     resolution: {integrity: sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==}
     engines: {node: '>=0.10.0'}
@@ -4616,11 +6367,19 @@ packages:
   is-hexadecimal@2.0.1:
     resolution: {integrity: sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==}
 
+  is-identifier@1.0.1:
+    resolution: {integrity: sha512-HQ5v4rEJ7REUV54bCd2l5FaD299SGDEn2UPoVXaTHAyGviLq2menVUD2udi3trQ32uvB6LdAh/0ck2EuizrtpA==}
+    engines: {node: '>=18'}
+
   is-in-ci@1.0.0:
     resolution: {integrity: sha512-eUuAjybVTHMYWm/U+vBO1sY/JOCgoPCXRxzdju0K+K0BiGW0SChEL1MLC0PoCIR1OlPo5YAp8HuQoUlsWEICwg==}
     engines: {node: '>=18'}
     hasBin: true
 
+  is-in-ssh@1.0.0:
+    resolution: {integrity: sha512-jYa6Q9rH90kR1vKB6NM7qqd1mge3Fx4Dhw5TVlK1MUBqhEOuCagrEHMevNuCcbECmXZ0ThXkRm+Ymr51HwEPAw==}
+    engines: {node: '>=20'}
+
   is-inside-container@1.0.0:
     resolution: {integrity: sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==}
     engines: {node: '>=14.16'}
@@ -4630,6 +6389,10 @@ packages:
     resolution: {integrity: sha512-K55T22lfpQ63N4KEN57jZUAaAYqYHEe8veb/TycJRk9DdSCLLcovXz/mL6mOnhQaZsQGwPhuFopdQIlqGSEjiQ==}
     engines: {node: '>=18'}
 
+  is-interactive@1.0.0:
+    resolution: {integrity: sha512-2HvIEKRoqS62guEC+qBjpvRubdX910WCMuJTZ+I9yvqKU2/12eSL549HMwtabb4oupdj2sMP50k+XJfB/8JE6w==}
+    engines: {node: '>=8'}
+
   is-interactive@2.0.0:
     resolution: {integrity: sha512-qP1vozQRI+BMOPcjFzrjXuQvdak2pHNUMZoeG2eRbiSqyvbEf/wQtEOTOX1guk6E3t36RkaqiSt8A/6YElNxLQ==}
     engines: {node: '>=12'}
@@ -4669,6 +6432,9 @@ packages:
   is-potential-custom-element-name@1.0.1:
     resolution: {integrity: sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==}
 
+  is-promise@4.0.0:
+    resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==}
+
   is-regex@1.2.1:
     resolution: {integrity: sha512-MjYsKHO5O7mCsmRGxWcLWheFqN9DJ/2TmngvjKXihe6efViPqc274+Fx/4fYj/r03+ESvBdTXK0V6tA3rgez1g==}
     engines: {node: '>= 0.4'}
@@ -4685,6 +6451,10 @@ packages:
     resolution: {integrity: sha512-ISWac8drv4ZGfwKl5slpHG9OwPNty4jOWPRIhBpxOoD+hqITiwuipOQ2bNthAzwA3B4fIjO4Nln74N0S9byq8A==}
     engines: {node: '>= 0.4'}
 
+  is-stream@1.1.0:
+    resolution: {integrity: sha512-uQPm8kcs47jx38atAcWTVxyltQYoPT68y9aWYdV6yWXSyW8mzSat0TL6CiWdZeCdF3KrAvpVtnHbTv4RN+rqdQ==}
+    engines: {node: '>=0.10.0'}
+
   is-string@1.1.1:
     resolution: {integrity: sha512-BtEeSsoaQjlSPBemMQIrY1MY0uM6vnS1g5fmufYOtnxLGUZM2178PKbhsk7Ffv58IX+ZtcvoGwccYsh0PglkAA==}
     engines: {node: '>= 0.4'}
@@ -4701,6 +6471,10 @@ packages:
     resolution: {integrity: sha512-p3EcsicXjit7SaskXHs1hA91QxgTw46Fv6EFKKGS5DRFLD8yKnohjF3hxoju94b/OcMZoQukzpPpBE9uLVKzgQ==}
     engines: {node: '>= 0.4'}
 
+  is-unicode-supported@0.1.0:
+    resolution: {integrity: sha512-knxG2q4UC3u8stRGyAVJCOdxFmv5DZiRcdlIaAQXAbSfJya+OhopNotLQrstBhququ4ZpuKbDc/8S6mgXgPFPw==}
+    engines: {node: '>=10'}
+
   is-unicode-supported@1.3.0:
     resolution: {integrity: sha512-43r2mRvz+8JRIKnWJ+3j8JtjRKZ6GmjzfaE/qiBJnikNnYv/6bagRJ1kUhNk8R5EX/GkobD+r+sfxCPJsiKBLQ==}
     engines: {node: '>=12'}
@@ -4729,6 +6503,10 @@ packages:
     resolution: {integrity: sha512-UcVfVfaK4Sc4m7X3dUSoHoozQGBEFeDC+zVo06t98xe8CzHSZZBekNXH+tu0NalHolcJ/QAGqS46Hef7QXBIMw==}
     engines: {node: '>=16'}
 
+  is-wsl@3.1.1:
+    resolution: {integrity: sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==}
+    engines: {node: '>=16'}
+
   isarray@2.0.5:
     resolution: {integrity: sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw==}
 
@@ -4746,35 +6524,45 @@ packages:
     resolution: {integrity: sha512-zptv57P3GpL+O0I7VdMJNBZCu+BPHVQUk55Ft8/QCJjTVxrnJHuVuX/0Bl2A6/+2oyR/ZMEuFKwmzqqZ/U5nPQ==}
     engines: {node: 20 || >=22}
 
-  jiti@1.21.7:
-    resolution: {integrity: sha512-/imKNG4EbWNrVjoNC/1H5/9GFy+tqjGBHCaSsN+P2RnPqjsLmv6UD3Ej+Kj8nBWaRAwyk7kK5ZUc+OEatnTR3A==}
+  jiti@2.6.1:
+    resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
+    hasBin: true
+
+  jiti@2.7.0:
+    resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==}
     hasBin: true
 
   jose@5.10.0:
     resolution: {integrity: sha512-s+3Al/p9g32Iq+oqXxkW//7jk2Vig6FF1CFqzVXoTUXt2qz89YWbL+OwS17NFYEvxC35n0FKeGO2LGYSxeM2Gg==}
 
+  jose@6.1.3:
+    resolution: {integrity: sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ==}
+
   joycon@3.1.1:
     resolution: {integrity: sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==}
     engines: {node: '>=10'}
 
-  js-tiktoken@1.0.21:
-    resolution: {integrity: sha512-biOj/6M5qdgx5TKjDnFT1ymSpM5tbd3ylwDtrQvFQSu0Z7bBYko2dF+W/aUkXUPuk6IVpRxk/3Q2sHOzGlS36g==}
+  js-base64@3.7.8:
+    resolution: {integrity: sha512-hNngCeKxIUQiEUN3GPJOkz4wF/YvdUdbNL9hsBcMQTkKzboD7T/q3OYOuuPZLUE6dBxSGpwhk5mwuDud7JVAow==}
 
   js-tokens@4.0.0:
     resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
 
+  js-tokens@9.0.1:
+    resolution: {integrity: sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==}
+
   js-yaml@3.14.1:
     resolution: {integrity: sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==}
     hasBin: true
 
-  js-yaml@4.1.0:
-    resolution: {integrity: sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==}
-    hasBin: true
-
   js-yaml@4.1.1:
     resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==}
     hasBin: true
 
+  js-yaml@4.2.0:
+    resolution: {integrity: sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==}
+    hasBin: true
+
   jsdom@27.0.0:
     resolution: {integrity: sha512-lIHeR1qlIRrIN5VMccd8tI2Sgw6ieYXSVktcSHaNe3Z5nE/tcPQYQWOq00wxMvYOsz+73eAkNenVvmPC6bba9A==}
     engines: {node: '>=20'}
@@ -4799,16 +6587,12 @@ packages:
   json-schema-traverse@1.0.0:
     resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
 
+  json-schema-typed@8.0.2:
+    resolution: {integrity: sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==}
+
   json-schema@0.4.0:
     resolution: {integrity: sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA==}
 
-  json-stringify-deterministic@1.0.12:
-    resolution: {integrity: sha512-q3PN0lbUdv0pmurkBNdJH3pfFvOTL/Zp0lquqpvcjfKzt6Y0j49EPHAmVHCAS4Ceq/Y+PejWTzyiVpoY71+D6g==}
-    engines: {node: '>= 4'}
-
-  json-stringify-safe@5.0.1:
-    resolution: {integrity: sha512-ZClg6AaYvamvYEE82d3Iyd3vSSIjQ+odgjaTzRuO3s7toCdFKczob2i0zCh7JE8kWn17yvAWhUVxvqGwUalsRA==}
-
   json5@2.2.3:
     resolution: {integrity: sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==}
     engines: {node: '>=6'}
@@ -4829,27 +6613,25 @@ packages:
   jsonfile@6.2.0:
     resolution: {integrity: sha512-FGuPw30AdOIUTRMC2OMRtQV+jkVj2cfPqSeWXv1NEAJ1qZ5zb1X6z1mFhbfOB/iy3ssJCD+3KuZ8r8C3uVFlAg==}
 
-  jsonpath-plus@10.3.0:
-    resolution: {integrity: sha512-8TNmfeTCk2Le33A3vRRwtuworG/L5RrgMvdjhKZxvyShO+mBu2fP50OWUjRLNtvw344DdDarFh9buFAZs5ujeA==}
+  jsonpath-plus@10.4.0:
+    resolution: {integrity: sha512-T92WWatJXmhBbKsgH/0hl+jxjdXrifi5IKeMY02DWggRxX0UElcbVzPlmgLTbvsPeW1PasQ6xE2Q75stkhGbsA==}
     engines: {node: '>=18.0.0'}
     hasBin: true
 
-  jsonpath@1.1.1:
-    resolution: {integrity: sha512-l6Cg7jRpixfbgoWgkrl77dgEj8RPvND0wMH6TwQmi9Qs4TFfS9u5cUFnbeKTwj5ga5Y3BTGGNI28k117LJ009w==}
-
   jsonpointer@5.0.1:
     resolution: {integrity: sha512-p/nXbhSEcu3pZRdkW1OfJhpsVtW1gd4Wa1fnQc9YLiTfAjn0312eMKimbdIQzuZl9aa9xUGaRlP9T/CJE/ditQ==}
     engines: {node: '>=0.10.0'}
 
+  jsonschema@1.4.1:
+    resolution: {integrity: sha512-S6cATIPVv1z0IlxdN+zUk5EPjkGCdnhN4wVSBlvoUO1tOLJootbo9CquNJmbIh4yikWHiUedhRYrNPn1arpEmQ==}
+
   jsonwebtoken@9.0.2:
     resolution: {integrity: sha512-PRp66vJ865SSqOlgqS8hujT5U4AOgMfhrwYIuIhfKaoSCZcirrmASQr8CX7cUg+RMih+hgznrjp99o+W4pJLHQ==}
     engines: {node: '>=12', npm: '>=6'}
 
-  just-clone@6.2.0:
-    resolution: {integrity: sha512-1IynUYEc/HAwxhi3WDpIpxJbZpMCvvrrmZVqvj9EhpvbH8lls7HhdhiByjL7DkAaWlLIzpC0Xc/VPvy/UxLNjA==}
-
-  just-curry-it@5.3.0:
-    resolution: {integrity: sha512-silMIRiFjUWlfaDhkgSzpuAyQ6EX/o09Eu8ZBfmFwQMbax7+LQzeIU2CBrICT6Ne4l86ITCGvUCBpCubWYy0Yw==}
+  junk@4.0.1:
+    resolution: {integrity: sha512-Qush0uP+G8ZScpGMZvHUiRfI0YBWuB3gVBYlI0v0vvOJt5FLicco+IkP0a50LqTTQhmts/m6tP5SWE+USyIvcQ==}
+    engines: {node: '>=12.20'}
 
   jwa@1.4.2:
     resolution: {integrity: sha512-eeH5JO+21J78qMvTIDdBXidBd6nG2kZjg5Ohz/1fpa28Z4CcsWUzJ1ZZyFq/3z3N17aZy+ZuBoHljASbL1WfOw==}
@@ -4876,6 +6658,10 @@ packages:
     resolution: {integrity: sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==}
     engines: {node: '>=6'}
 
+  klona@2.0.6:
+    resolution: {integrity: sha512-dhG34DXATL5hSxJbIexCft8FChFXtmskoZYnoPWjXQuebWYCNkVeV3KkGegCK9CP1oswI/vQibS2GY7Em/sJJA==}
+    engines: {node: '>= 8'}
+
   kolorist@1.8.0:
     resolution: {integrity: sha512-Y+60/zizpJ3HRH8DCss+q95yr6145JXZo46OTpFvDZWLfRCE4qChOyk1b26nMaNpfHHgxagk9dXT5OP0Tfe+dQ==}
 
@@ -4883,84 +6669,25 @@ packages:
     resolution: {integrity: sha512-NEyo0ICpS0cqSuyoJFMCnHOZJILqXsKhIZlHJGDYaH8OB5IFrGzuBpEwyoMZG6gUKMPrazH30Ax5XKaujvD8ag==}
     engines: {node: '>=18'}
 
-  langchain@0.3.35:
-    resolution: {integrity: sha512-OkPstP43L3rgaAk72UAVcXy4BzJSiyzXfJsHRBTx9xD3rRtgrAu/jsWpMcsbFAoNO3iGerK+ULzkTzaBJBz6kg==}
-    engines: {node: '>=18'}
-    peerDependencies:
-      '@langchain/anthropic': '*'
-      '@langchain/aws': '*'
-      '@langchain/cerebras': '*'
-      '@langchain/cohere': '*'
-      '@langchain/core': '>=0.3.58 <0.4.0'
-      '@langchain/deepseek': '*'
-      '@langchain/google-genai': '*'
-      '@langchain/google-vertexai': '*'
-      '@langchain/google-vertexai-web': '*'
-      '@langchain/groq': '*'
-      '@langchain/mistralai': '*'
-      '@langchain/ollama': '*'
-      '@langchain/xai': '*'
-      axios: '*'
-      cheerio: '*'
-      handlebars: ^4.7.8
-      peggy: ^3.0.2
-      typeorm: '*'
-    peerDependenciesMeta:
-      '@langchain/anthropic':
-        optional: true
-      '@langchain/aws':
-        optional: true
-      '@langchain/cerebras':
-        optional: true
-      '@langchain/cohere':
-        optional: true
-      '@langchain/deepseek':
-        optional: true
-      '@langchain/google-genai':
-        optional: true
-      '@langchain/google-vertexai':
-        optional: true
-      '@langchain/google-vertexai-web':
-        optional: true
-      '@langchain/groq':
-        optional: true
-      '@langchain/mistralai':
-        optional: true
-      '@langchain/ollama':
-        optional: true
-      '@langchain/xai':
-        optional: true
-      axios:
-        optional: true
-      cheerio:
-        optional: true
-      handlebars:
-        optional: true
-      peggy:
-        optional: true
-      typeorm:
-        optional: true
+  langium-cli@3.5.2:
+    resolution: {integrity: sha512-EVI462CIx8YnJfLSGArvvrlTzAXafA8zNeNbX6FPI5eX8ahicJcvnqW0eAmZ6mLFP7aipzV2F0Sehexe7KHmzA==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  langium-railroad@3.5.0:
+    resolution: {integrity: sha512-80Enc6bOR6oHZD18IQlVTdfCh07rbrM5SOsPUPc1kyh7n3zQbmLs5P2E9hV4SoWlkhOjGKL1I9Z6uORpgy+jTQ==}
 
   langium@3.3.1:
     resolution: {integrity: sha512-QJv/h939gDpvT+9SiLVlY7tZC3xB2qK57v0J04Sh9wpMb6MP1q8gB21L3WIo8T5P1MSMg3Ep14L7KkDCFG3y4w==}
     engines: {node: '>=16.0.0'}
 
-  langsmith@0.3.73:
-    resolution: {integrity: sha512-zuAAFiY6yfqU+Y8OicEmBqahLWqzMumNY7tcXnuGk8P26hS5aqh+9rXfI4zv0nr++97kNP9WCiBDgPWcrSWlDA==}
-    peerDependencies:
-      '@opentelemetry/api': '*'
-      '@opentelemetry/exporter-trace-otlp-proto': '*'
-      '@opentelemetry/sdk-trace-base': '*'
-      openai: '*'
-    peerDependenciesMeta:
-      '@opentelemetry/api':
-        optional: true
-      '@opentelemetry/exporter-trace-otlp-proto':
-        optional: true
-      '@opentelemetry/sdk-trace-base':
-        optional: true
-      openai:
-        optional: true
+  langium@3.5.0:
+    resolution: {integrity: sha512-tnqVzWOkUcoiY0bWlyE8diFrZjmGBCF7MesC1bjUaZM+YGQSfdPC+KkhmHM0DWFG+uLcPxidKaPP1SYGtg3J0Q==}
+    engines: {node: '>=18.0.0'}
+
+  langium@4.2.1:
+    resolution: {integrity: sha512-zu9QWmjpzJcomzdJQAHgDVhLGq5bLosVak1KVa40NzQHXfqr4eAHupvnPOVXEoLkg6Ocefvf/93d//SB7du4YQ==}
+    engines: {node: '>=20.10.0', npm: '>=10.2.3'}
 
   latest-version@9.0.0:
     resolution: {integrity: sha512-7W0vV3rqv5tokqkBAFV1LbR7HPOWzXQDpDgEuib/aJ1jsZZx6x3c2mBI+TJhJzOhkGeaLbCKEHXEXLfirtG2JA==}
@@ -4976,76 +6703,152 @@ packages:
     resolution: {integrity: sha512-qsda+H8jTaUaN/x5vzW2rzc+8Rw4TAQ/4KjB46IwK5VH+IlVeeeje/EoZRpiXvIqjFgK84QffqPztGI3VBLG1A==}
     engines: {node: '>=6'}
 
-  leven@4.1.0:
-    resolution: {integrity: sha512-KZ9W9nWDT7rF7Dazg8xyLHGLrmpgq2nVNFUckhqdW3szVP6YhCpp/RAnpmVExA9JvrMynjwSLVrEj3AepHR6ew==}
-    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+  lightningcss-android-arm64@1.30.2:
+    resolution: {integrity: sha512-BH9sEdOCahSgmkVhBLeU7Hc9DWeZ1Eb6wNS6Da8igvUwAe0sqROHddIlvU06q3WyXVEOYDZ6ykBZQnjTbmo4+A==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-android-arm64@1.32.0:
+    resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.30.2:
+    resolution: {integrity: sha512-ylTcDJBN3Hp21TdhRT5zBOIi73P6/W0qwvlFEk22fkdXchtNTOU4Qc37SkzV+EKYxLouZ6M4LG9NfZ1qkhhBWA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-arm64@1.32.0:
+    resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.30.2:
+    resolution: {integrity: sha512-oBZgKchomuDYxr7ilwLcyms6BCyLn0z8J0+ZZmfpjwg9fRVZIR5/GMXd7r9RH94iDhld3UmSjBM6nXWM2TfZTQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.32.0:
+    resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.30.2:
+    resolution: {integrity: sha512-c2bH6xTrf4BDpK8MoGG4Bd6zAMZDAXS569UxCAGcA7IKbHNMlhGQ89eRmvpIUGfKWNVdbhSbkQaWhEoMGmGslA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-freebsd-x64@1.32.0:
+    resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.30.2:
+    resolution: {integrity: sha512-eVdpxh4wYcm0PofJIZVuYuLiqBIakQ9uFZmipf6LF/HRj5Bgm0eb3qL/mr1smyXIS1twwOxNWndd8z0E374hiA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
 
-  levn@0.3.0:
-    resolution: {integrity: sha512-0OO4y2iOHix2W6ujICbKIaEQXvFQHue65vUG3pb5EUomzPI90z9hsA1VsO/dbIIpC53J8gxM9Q4Oho0jrCM/yA==}
-    engines: {node: '>= 0.8.0'}
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
 
-  lightningcss-darwin-arm64@1.29.3:
-    resolution: {integrity: sha512-fb7raKO3pXtlNbQbiMeEu8RbBVHnpyqAoxTyTRMEWFQWmscGC2wZxoHzZ+YKAepUuKT9uIW5vL2QbFivTgprZg==}
+  lightningcss-linux-arm64-gnu@1.30.2:
+    resolution: {integrity: sha512-UK65WJAbwIJbiBFXpxrbTNArtfuznvxAJw4Q2ZGlU8kPeDIWEX1dg3rn2veBVUylA2Ezg89ktszWbaQnxD/e3A==}
     engines: {node: '>= 12.0.0'}
     cpu: [arm64]
-    os: [darwin]
+    os: [linux]
+    libc: [glibc]
 
-  lightningcss-darwin-x64@1.29.3:
-    resolution: {integrity: sha512-KF2XZ4ZdmDGGtEYmx5wpzn6u8vg7AdBHaEOvDKu8GOs7xDL/vcU2vMKtTeNe1d4dogkDdi3B9zC77jkatWBwEQ==}
+  lightningcss-linux-arm64-gnu@1.32.0:
+    resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==}
     engines: {node: '>= 12.0.0'}
-    cpu: [x64]
-    os: [darwin]
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
 
-  lightningcss-freebsd-x64@1.29.3:
-    resolution: {integrity: sha512-VUWeVf+V1UM54jv9M4wen9vMlIAyT69Krl9XjI8SsRxz4tdNV/7QEPlW6JASev/pYdiynUCW0pwaFquDRYdxMw==}
+  lightningcss-linux-arm64-musl@1.30.2:
+    resolution: {integrity: sha512-5Vh9dGeblpTxWHpOx8iauV02popZDsCYMPIgiuw97OJ5uaDsL86cnqSFs5LZkG3ghHoX5isLgWzMs+eD1YzrnA==}
     engines: {node: '>= 12.0.0'}
-    cpu: [x64]
-    os: [freebsd]
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
 
-  lightningcss-linux-arm-gnueabihf@1.29.3:
-    resolution: {integrity: sha512-UhgZ/XVNfXQVEJrMIWeK1Laj8KbhjbIz7F4znUk7G4zeGw7TRoJxhb66uWrEsonn1+O45w//0i0Fu0wIovYdYg==}
+  lightningcss-linux-arm64-musl@1.32.0:
+    resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
     engines: {node: '>= 12.0.0'}
-    cpu: [arm]
+    cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
-  lightningcss-linux-arm64-gnu@1.29.3:
-    resolution: {integrity: sha512-Pqau7jtgJNmQ/esugfmAT1aCFy/Gxc92FOxI+3n+LbMHBheBnk41xHDhc0HeYlx9G0xP5tK4t0Koy3QGGNqypw==}
+  lightningcss-linux-x64-gnu@1.30.2:
+    resolution: {integrity: sha512-Cfd46gdmj1vQ+lR6VRTTadNHu6ALuw2pKR9lYq4FnhvgBc4zWY1EtZcAc6EffShbb1MFrIPfLDXD6Xprbnni4w==}
     engines: {node: '>= 12.0.0'}
-    cpu: [arm64]
+    cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
-  lightningcss-linux-arm64-musl@1.29.3:
-    resolution: {integrity: sha512-dxakOk66pf7KLS7VRYFO7B8WOJLecE5OPL2YOk52eriFd/yeyxt2Km5H0BjLfElokIaR+qWi33gB8MQLrdAY3A==}
+  lightningcss-linux-x64-gnu@1.32.0:
+    resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
     engines: {node: '>= 12.0.0'}
-    cpu: [arm64]
+    cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
-  lightningcss-linux-x64-gnu@1.29.3:
-    resolution: {integrity: sha512-ySZTNCpbfbK8rqpKJeJR2S0g/8UqqV3QnzcuWvpI60LWxnFN91nxpSSwCbzfOXkzKfar9j5eOuOplf+klKtINg==}
+  lightningcss-linux-x64-musl@1.30.2:
+    resolution: {integrity: sha512-XJaLUUFXb6/QG2lGIW6aIk6jKdtjtcffUT0NKvIqhSBY3hh9Ch+1LCeH80dR9q9LBjG3ewbDjnumefsLsP6aiA==}
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
-  lightningcss-linux-x64-musl@1.29.3:
-    resolution: {integrity: sha512-3pVZhIzW09nzi10usAXfIGTTSTYQ141dk88vGFNCgawIzayiIzZQxEcxVtIkdvlEq2YuFsL9Wcj/h61JHHzuFQ==}
+  lightningcss-linux-x64-musl@1.32.0:
+    resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
+
+  lightningcss-win32-arm64-msvc@1.30.2:
+    resolution: {integrity: sha512-FZn+vaj7zLv//D/192WFFVA0RgHawIcHqLX9xuWiQt7P0PtdFEVaxgF9rjM/IRYHQXNnk61/H/gb2Ei+kUQ4xQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
 
-  lightningcss-win32-arm64-msvc@1.29.3:
-    resolution: {integrity: sha512-VRnkAvtIkeWuoBJeGOTrZxsNp4HogXtcaaLm8agmbYtLDOhQdpgxW6NjZZjDXbvGF+eOehGulXZ3C1TiwHY4QQ==}
+  lightningcss-win32-arm64-msvc@1.32.0:
+    resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
     engines: {node: '>= 12.0.0'}
     cpu: [arm64]
     os: [win32]
 
-  lightningcss-win32-x64-msvc@1.29.3:
-    resolution: {integrity: sha512-IszwRPu2cPnDQsZpd7/EAr0x2W7jkaWqQ1SwCVIZ/tSbZVXPLt6k8s6FkcyBjViCzvB5CW0We0QbbP7zp2aBjQ==}
+  lightningcss-win32-x64-msvc@1.30.2:
+    resolution: {integrity: sha512-5g1yc73p+iAkid5phb4oVFMB45417DkRevRbt/El/gKXJk4jid+vPFF/AXbxn05Aky8PapwzZrdJShv5C0avjw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==}
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [win32]
 
-  lightningcss@1.29.3:
-    resolution: {integrity: sha512-GlOJwTIP6TMIlrTFsxTerwC0W6OpQpCGuX1ECRLBUVRh6fpJH3xTqjCjRgQHTb4ZXexH9rtHou1Lf03GKzmhhQ==}
+  lightningcss@1.30.2:
+    resolution: {integrity: sha512-utfs7Pr5uJyyvDETitgsaqSyjCb2qNRAtuqUeWIAKztsOYdcACf2KtARYXg2pSvhkt+9NfoaNY7fxjl6nuMjIQ==}
+    engines: {node: '>= 12.0.0'}
+
+  lightningcss@1.32.0:
+    resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==}
     engines: {node: '>= 12.0.0'}
 
   lilconfig@3.1.3:
@@ -5070,6 +6873,12 @@ packages:
   lodash-es@4.17.21:
     resolution: {integrity: sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==}
 
+  lodash-es@4.17.23:
+    resolution: {integrity: sha512-kVI48u3PZr38HdYz98UmfPnXl2DXrpdctLrFLCd3kOx1xUkOmpFPx7gCWWM5MPkL/fD8zb+Ph0QzjGFs4+hHWg==}
+
+  lodash-es@4.18.1:
+    resolution: {integrity: sha512-J8xewKD/Gk22OZbhpOVSwcs60zhd95ESDwezOFuA3/099925PdHJ7OFHNTGtajL3AlZkykD32HykiMo+BIBI8A==}
+
   lodash.debounce@4.0.8:
     resolution: {integrity: sha512-FT1yDzDYEoYWhnSGnpE/4Kj1fLZkDFyqRb7fNt6FdYOSxlUWAtp42Eh6Wb0rGIv/m9Bgo7x4GhQbm5Ys4SG5ow==}
 
@@ -5109,6 +6918,10 @@ packages:
   lodash@4.17.21:
     resolution: {integrity: sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==}
 
+  log-symbols@4.1.0:
+    resolution: {integrity: sha512-8XPvpAA8uyhfteu8pIvQxpJZ7SYYdpUivZpGy6sFsBuKRY/7rQGavedeB8aK+Zkyq6upMFVL/9AW6vOYzfRyLg==}
+    engines: {node: '>=10'}
+
   log-symbols@6.0.0:
     resolution: {integrity: sha512-i24m8rpwhmPIS4zscNzK6MSEhk0DUWa/8iYQWxhffV8jkI4Phvs3F+quL5xvS0gdQR0FyTCMMH33Y78dDTzzIw==}
     engines: {node: '>=18'}
@@ -5142,6 +6955,10 @@ packages:
     resolution: {integrity: sha512-F9ODfyqML2coTIsQpSkRHnLSZMtkU8Q+mSfcaIyKwy58u+8k5nvAYeiNhsyMARvzNcXJ9QfWVrcPsC9e9rAxtg==}
     engines: {node: 20 || >=22}
 
+  lru-cache@11.3.6:
+    resolution: {integrity: sha512-Gf/KoL3C/MlI7Bt0PGI9I+TeTC/I6r/csU58N4BSNc4lppLBeKsOdFYkK+dX0ABDUMJNfCHTyPpzwwO21Awd3A==}
+    engines: {node: 20 || >=22}
+
   lru-cache@5.1.1:
     resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
 
@@ -5155,14 +6972,20 @@ packages:
     peerDependencies:
       react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
-  magic-string@0.30.19:
-    resolution: {integrity: sha512-2N21sPY9Ws53PZvsEpVtNuSW+ScYbQdp4b9qUaL+9QkHUrGFKo56Lg9Emg5s9V/qrtNBmiR01sYhUOwu3H+VOw==}
+  lucide-react@0.563.0:
+    resolution: {integrity: sha512-8dXPB2GI4dI8jV4MgUDGBeLdGk8ekfqVZ0BdLcrRzocGgG75ltNEmWS+gE7uokKF/0oSUuczNDT+g9hFJ23FkA==}
+    peerDependencies:
+      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
-  magicast@0.5.1:
-    resolution: {integrity: sha512-xrHS24IxaLrvuo613F719wvOIv9xPHFWQHuvGUBmPnCA/3MQxKI3b+r7n1jAoDHmsbC5bRhTZYR77invLAxVnw==}
+  magicast@0.5.2:
+    resolution: {integrity: sha512-E3ZJh4J3S9KfwdjZhe2afj6R9lGIN5Pher1pF39UGrXRqq/VDaGVIGN13BjHd2u8B61hArAGOnso7nBOouW3TQ==}
+
+  make-asynchronous@1.1.0:
+    resolution: {integrity: sha512-ayF7iT+44LXdxJLTrTd3TLQpFDDvPCBxXxbv+pMUSuHA5Q8zyAfwkRP6aHHwNVFBUFWtxAHqwNJxF8vMZLAbVg==}
+    engines: {node: '>=18'}
 
   markdown-extensions@2.0.0:
     resolution: {integrity: sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q==}
@@ -5171,6 +6994,11 @@ packages:
   markdown-table@3.0.4:
     resolution: {integrity: sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==}
 
+  marked@14.0.0:
+    resolution: {integrity: sha512-uIj4+faQ+MgHgwUW1l2PsPglZLOLOT1uErt06dAPtx2kjteLAkbsd/0FiYg/MGS+i7ZKLb7w2WClxHkzOOuryQ==}
+    engines: {node: '>= 18'}
+    hasBin: true
+
   marked@15.0.12:
     resolution: {integrity: sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA==}
     engines: {node: '>= 18'}
@@ -5186,10 +7014,6 @@ packages:
     engines: {node: '>= 12'}
     hasBin: true
 
-  matcher@3.0.0:
-    resolution: {integrity: sha512-OkeDaAZ/bQCxeFAozM55PKcKU0yJMPGifLwV4Qgjitu+5MoAfSQN4lsLJeXZ1b8w0x+/Emda6MZgXS1jvsapng==}
-    engines: {node: '>=10'}
-
   math-intrinsics@1.1.0:
     resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
     engines: {node: '>= 0.4'}
@@ -5200,51 +7024,27 @@ packages:
   mdast-util-directive@3.1.0:
     resolution: {integrity: sha512-I3fNFt+DHmpWCYAT7quoM6lHf9wuqtI+oCOfvILnoicNIqjh5E3dEJWiXuYME2gNe8vl1iMQwyUHa7bgFmak6Q==}
 
-  mdast-util-find-and-replace@2.2.2:
-    resolution: {integrity: sha512-MTtdFRz/eMDHXzeK6W3dO7mXUlF82Gom4y0oOgvHhh/HXZAGvIQDUvQ0SuUx+j2tv44b8xTHOm8K/9OoRFnXKw==}
-
   mdast-util-find-and-replace@3.0.2:
     resolution: {integrity: sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==}
 
-  mdast-util-from-markdown@1.3.1:
-    resolution: {integrity: sha512-4xTO/M8c82qBcnQc1tgpNtubGUW/Y1tBQ1B0i5CtSoelOLKFYlElIr3bvgREYYO5iRqbMY1YuqZng0GVOI8Qww==}
-
   mdast-util-from-markdown@2.0.2:
     resolution: {integrity: sha512-uZhTV/8NBuw0WHkPTrCqDOl0zVe1BIng5ZtHoDk49ME1qqcjYmmLmOf0gELgcRMxN4w2iuIeVso5/6QymSrgmA==}
 
-  mdast-util-gfm-autolink-literal@1.0.3:
-    resolution: {integrity: sha512-My8KJ57FYEy2W2LyNom4n3E7hKTuQk/0SES0u16tjA9Z3oFkF4RrC/hPAPgjlSpezsOvI8ObcXcElo92wn5IGA==}
-
   mdast-util-gfm-autolink-literal@2.0.1:
     resolution: {integrity: sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==}
 
-  mdast-util-gfm-footnote@1.0.2:
-    resolution: {integrity: sha512-56D19KOGbE00uKVj3sgIykpwKL179QsVFwx/DCW0u/0+URsryacI4MAdNJl0dh+u2PSsD9FtxPFbHCzJ78qJFQ==}
-
   mdast-util-gfm-footnote@2.1.0:
     resolution: {integrity: sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==}
 
-  mdast-util-gfm-strikethrough@1.0.3:
-    resolution: {integrity: sha512-DAPhYzTYrRcXdMjUtUjKvW9z/FNAMTdU0ORyMcbmkwYNbKocDpdk+PX1L1dQgOID/+vVs1uBQ7ElrBQfZ0cuiQ==}
-
   mdast-util-gfm-strikethrough@2.0.0:
     resolution: {integrity: sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==}
 
-  mdast-util-gfm-table@1.0.7:
-    resolution: {integrity: sha512-jjcpmNnQvrmN5Vx7y7lEc2iIOEytYv7rTvu+MeyAsSHTASGCCRA79Igg2uKssgOs1i1po8s3plW0sTu1wkkLGg==}
-
   mdast-util-gfm-table@2.0.0:
     resolution: {integrity: sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==}
 
-  mdast-util-gfm-task-list-item@1.0.2:
-    resolution: {integrity: sha512-PFTA1gzfp1B1UaiJVyhJZA1rm0+Tzn690frc/L8vNX1Jop4STZgOE6bxUhnzdVSB+vm2GU1tIsuQcA9bxTQpMQ==}
-
   mdast-util-gfm-task-list-item@2.0.0:
     resolution: {integrity: sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==}
 
-  mdast-util-gfm@2.0.2:
-    resolution: {integrity: sha512-qvZ608nBppZ4icQlhQQIAdc6S3Ffj9RGmzwUKUWuEICFnd1LVkN3EktF7ZHAgfcEdvZB5owU9tQgt99e2TlLjg==}
-
   mdast-util-gfm@3.1.0:
     resolution: {integrity: sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==}
 
@@ -5260,94 +7060,66 @@ packages:
   mdast-util-mdxjs-esm@2.0.1:
     resolution: {integrity: sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==}
 
-  mdast-util-phrasing@3.0.1:
-    resolution: {integrity: sha512-WmI1gTXUBJo4/ZmSk79Wcb2HcjPJBzM1nlI/OUWA8yk2X9ik3ffNbBGsU+09BFmXaL1IBb9fiuvq6/KMiNycSg==}
-
   mdast-util-phrasing@4.1.0:
     resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==}
 
   mdast-util-to-hast@13.2.0:
     resolution: {integrity: sha512-QGYKEuUsYT9ykKBCMOEDLsU5JRObWQusAolFMeko/tYPufNkRffBAQjIE+99jbA87xv6FgmjLtwjh9wBWajwAA==}
 
-  mdast-util-to-markdown@1.5.0:
-    resolution: {integrity: sha512-bbv7TPv/WC49thZPg3jXuqzuvI45IL2EVAr/KxF0BSdHsU0ceFHOmwQn6evxAh1GaoK/6GQ1wp4R4oW2+LFL/A==}
-
   mdast-util-to-markdown@2.1.2:
     resolution: {integrity: sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==}
 
-  mdast-util-to-string@3.2.0:
-    resolution: {integrity: sha512-V4Zn/ncyN1QNSqSBxTrMOLpjr+IKdHl2v3KVLoWmDPscP4r9GcCi71gjgvUV1SFSKh92AjAG4peFuBl2/YgCJg==}
-
   mdast-util-to-string@4.0.0:
     resolution: {integrity: sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==}
 
   mdn-data@2.0.28:
     resolution: {integrity: sha512-aylIc7Z9y4yzHYAJNuESG3hfhC+0Ibp/MAMiaOZgNv4pmEdFyfZhhhny4MNiAfWdBQ1RQ2mfDWmM1x8SvGyp8g==}
 
-  mdn-data@2.0.30:
-    resolution: {integrity: sha512-GaqWWShW4kv/G9IEucWScBx9G1/vsFZZJUO+tD26M8J8z3Kw5RDQjaoZe03YAClgeS/SWPOcb4nkFBTEi5DUEA==}
-
   mdn-data@2.12.2:
     resolution: {integrity: sha512-IEn+pegP1aManZuckezWCO+XZQDplx1366JoVhTpMpBB1sPey/SbveZQUosKiKiGYjg1wH4pMlNgXbCiYgihQA==}
 
+  media-typer@1.1.0:
+    resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==}
+    engines: {node: '>= 0.8'}
+
+  merge-descriptors@2.0.0:
+    resolution: {integrity: sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==}
+    engines: {node: '>=18'}
+
   merge2@1.4.1:
     resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
     engines: {node: '>= 8'}
 
-  mermaid@11.12.0:
-    resolution: {integrity: sha512-ZudVx73BwrMJfCFmSSJT84y6u5brEoV8DOItdHomNLz32uBjNrelm7mg95X7g+C6UoQH/W6mBLGDEDv73JdxBg==}
+  mermaid@11.12.3:
+    resolution: {integrity: sha512-wN5ZSgJQIC+CHJut9xaKWsknLxaFBwCPwPkGTSUYrTiHORWvpT8RxGk849HPnpUAQ+/9BPRqYb80jTpearrHzQ==}
 
   microdiff@1.5.0:
     resolution: {integrity: sha512-Drq+/THMvDdzRYrK0oxJmOKiC24ayUV8ahrt8l3oRK51PWt6gdtrIGrlIH3pT/lFh1z93FbAcidtsHcWbnRz8Q==}
 
-  micromark-core-commonmark@1.1.0:
-    resolution: {integrity: sha512-BgHO1aRbolh2hcrzL2d1La37V0Aoz73ymF8rAcKnohLy93titmv62E0gP8Hrx9PKcKrqCZ1BbLGbP3bEhoXYlw==}
-
   micromark-core-commonmark@2.0.3:
     resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==}
 
   micromark-extension-directive@3.0.2:
     resolution: {integrity: sha512-wjcXHgk+PPdmvR58Le9d7zQYWy+vKEU9Se44p2CrCDPiLr2FMyiT4Fyb5UFKFC66wGB3kPlgD7q3TnoqPS7SZA==}
 
-  micromark-extension-gfm-autolink-literal@1.0.5:
-    resolution: {integrity: sha512-z3wJSLrDf8kRDOh2qBtoTRD53vJ+CWIyo7uyZuxf/JAbNJjiHsOpG1y5wxk8drtv3ETAHutCu6N3thkOOgueWg==}
-
   micromark-extension-gfm-autolink-literal@2.1.0:
     resolution: {integrity: sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==}
 
-  micromark-extension-gfm-footnote@1.1.2:
-    resolution: {integrity: sha512-Yxn7z7SxgyGWRNa4wzf8AhYYWNrwl5q1Z8ii+CSTTIqVkmGZF1CElX2JI8g5yGoM3GAman9/PVCUFUSJ0kB/8Q==}
-
   micromark-extension-gfm-footnote@2.1.0:
     resolution: {integrity: sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==}
 
-  micromark-extension-gfm-strikethrough@1.0.7:
-    resolution: {integrity: sha512-sX0FawVE1o3abGk3vRjOH50L5TTLr3b5XMqnP9YDRb34M0v5OoZhG+OHFz1OffZ9dlwgpTBKaT4XW/AsUVnSDw==}
-
   micromark-extension-gfm-strikethrough@2.1.0:
     resolution: {integrity: sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==}
 
-  micromark-extension-gfm-table@1.0.7:
-    resolution: {integrity: sha512-3ZORTHtcSnMQEKtAOsBQ9/oHp9096pI/UvdPtN7ehKvrmZZ2+bbWhi0ln+I9drmwXMt5boocn6OlwQzNXeVeqw==}
-
   micromark-extension-gfm-table@2.1.1:
     resolution: {integrity: sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==}
 
-  micromark-extension-gfm-tagfilter@1.0.2:
-    resolution: {integrity: sha512-5XWB9GbAUSHTn8VPU8/1DBXMuKYT5uOgEjJb8gN3mW0PNW5OPHpSdojoqf+iq1xo7vWzw/P8bAHY0n6ijpXF7g==}
-
   micromark-extension-gfm-tagfilter@2.0.0:
     resolution: {integrity: sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==}
 
-  micromark-extension-gfm-task-list-item@1.0.5:
-    resolution: {integrity: sha512-RMFXl2uQ0pNQy6Lun2YBYT9g9INXtWJULgbt01D/x8/6yJ2qpKyzdZD3pi6UIkzF++Da49xAelVKUeUMqd5eIQ==}
-
   micromark-extension-gfm-task-list-item@2.1.0:
     resolution: {integrity: sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==}
 
-  micromark-extension-gfm@2.0.3:
-    resolution: {integrity: sha512-vb9OoHqrhCmbRidQv/2+Bc6pkP0FrtlhurxZofvOEy5o8RtuuvTq+RQ1Vw5ZDNrVraQZu3HixESqbG+0iKk/MQ==}
-
   micromark-extension-gfm@3.0.0:
     resolution: {integrity: sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==}
 
@@ -5366,15 +7138,9 @@ packages:
   micromark-extension-mdxjs@3.0.0:
     resolution: {integrity: sha512-A873fJfhnJ2siZyUrJ31l34Uqwy4xIFmvPY1oj+Ean5PHcPBYzEsvqvWGaWcfEIr11O5Dlw3p2y0tZWpKHDejQ==}
 
-  micromark-factory-destination@1.1.0:
-    resolution: {integrity: sha512-XaNDROBgx9SgSChd69pjiGKbV+nfHGDPVYFs5dOoDd7ZnMAE+Cuu91BCpsY8RT2NP9vo/B8pds2VQNCLiu0zhg==}
-
   micromark-factory-destination@2.0.1:
     resolution: {integrity: sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==}
 
-  micromark-factory-label@1.1.0:
-    resolution: {integrity: sha512-OLtyez4vZo/1NjxGhcpDSbHQ+m0IIGnT8BoPamh+7jVlzLJBH98zzuCoUeMxvM6WsNeh8wx8cKvqLiPHEACn0w==}
-
   micromark-factory-label@2.0.1:
     resolution: {integrity: sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==}
 
@@ -5387,15 +7153,9 @@ packages:
   micromark-factory-space@2.0.1:
     resolution: {integrity: sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==}
 
-  micromark-factory-title@1.1.0:
-    resolution: {integrity: sha512-J7n9R3vMmgjDOCY8NPw55jiyaQnH5kBdV2/UXCtZIpnHH3P6nHUKaH7XXEYuWwx/xUJcawa8plLBEjMPU24HzQ==}
-
   micromark-factory-title@2.0.1:
     resolution: {integrity: sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==}
 
-  micromark-factory-whitespace@1.1.0:
-    resolution: {integrity: sha512-v2WlmiymVSp5oMg+1Q0N1Lxmt6pMhIHD457whWM7/GUlEks1hI9xj5w3zbc4uuMKXGisksZk8DzP2UyGbGqNsQ==}
-
   micromark-factory-whitespace@2.0.1:
     resolution: {integrity: sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==}
 
@@ -5405,72 +7165,39 @@ packages:
   micromark-util-character@2.1.1:
     resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==}
 
-  micromark-util-chunked@1.1.0:
-    resolution: {integrity: sha512-Ye01HXpkZPNcV6FiyoW2fGZDUw4Yc7vT0E9Sad83+bEDiCJ1uXu0S3mr8WLpsz3HaG3x2q0HM6CTuPdcZcluFQ==}
-
   micromark-util-chunked@2.0.1:
     resolution: {integrity: sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==}
 
-  micromark-util-classify-character@1.1.0:
-    resolution: {integrity: sha512-SL0wLxtKSnklKSUplok1WQFoGhUdWYKggKUiqhX+Swala+BtptGCu5iPRc+xvzJ4PXE/hwM3FNXsfEVgoZsWbw==}
-
   micromark-util-classify-character@2.0.1:
     resolution: {integrity: sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==}
 
-  micromark-util-combine-extensions@1.1.0:
-    resolution: {integrity: sha512-Q20sp4mfNf9yEqDL50WwuWZHUrCO4fEyeDCnMGmG5Pr0Cz15Uo7KBs6jq+dq0EgX4DPwwrh9m0X+zPV1ypFvUA==}
-
   micromark-util-combine-extensions@2.0.1:
     resolution: {integrity: sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==}
 
-  micromark-util-decode-numeric-character-reference@1.1.0:
-    resolution: {integrity: sha512-m9V0ExGv0jB1OT21mrWcuf4QhP46pH1KkfWy9ZEezqHKAxkj4mPCy3nIH1rkbdMlChLHX531eOrymlwyZIf2iw==}
-
   micromark-util-decode-numeric-character-reference@2.0.2:
     resolution: {integrity: sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==}
 
-  micromark-util-decode-string@1.1.0:
-    resolution: {integrity: sha512-YphLGCK8gM1tG1bd54azwyrQRjCFcmgj2S2GoJDNnh4vYtnL38JS8M4gpxzOPNyHdNEpheyWXCTnnTDY3N+NVQ==}
-
   micromark-util-decode-string@2.0.1:
     resolution: {integrity: sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==}
 
-  micromark-util-encode@1.1.0:
-    resolution: {integrity: sha512-EuEzTWSTAj9PA5GOAs992GzNh2dGQO52UvAbtSOMvXTxv3Criqb6IOzJUBCmEqrrXSblJIJBbFFv6zPxpreiJw==}
-
   micromark-util-encode@2.0.1:
     resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==}
 
   micromark-util-events-to-acorn@2.0.3:
     resolution: {integrity: sha512-jmsiEIiZ1n7X1Rr5k8wVExBQCg5jy4UXVADItHmNk1zkwEVhBuIUKRu3fqv+hs4nxLISi2DQGlqIOGiFxgbfHg==}
 
-  micromark-util-html-tag-name@1.2.0:
-    resolution: {integrity: sha512-VTQzcuQgFUD7yYztuQFKXT49KghjtETQ+Wv/zUjGSGBioZnkA4P1XXZPT1FHeJA6RwRXSF47yvJ1tsJdoxwO+Q==}
-
   micromark-util-html-tag-name@2.0.1:
     resolution: {integrity: sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==}
 
-  micromark-util-normalize-identifier@1.1.0:
-    resolution: {integrity: sha512-N+w5vhqrBihhjdpM8+5Xsxy71QWqGn7HYNUvch71iV2PM7+E3uWGox1Qp90loa1ephtCxG2ftRV/Conitc6P2Q==}
-
   micromark-util-normalize-identifier@2.0.1:
     resolution: {integrity: sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==}
 
-  micromark-util-resolve-all@1.1.0:
-    resolution: {integrity: sha512-b/G6BTMSg+bX+xVCshPTPyAu2tmA0E4X98NSR7eIbeC6ycCqCeE7wjfDIgzEbkzdEVJXRtOG4FbEm/uGbCRouA==}
-
   micromark-util-resolve-all@2.0.1:
     resolution: {integrity: sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==}
 
-  micromark-util-sanitize-uri@1.2.0:
-    resolution: {integrity: sha512-QO4GXv0XZfWey4pYFndLUKEAktKkG5kZTdUNaTAkzbuJxn2tNBOr+QtxR2XpWaMhbImT2dPzyLrPXLlPhph34A==}
-
   micromark-util-sanitize-uri@2.0.1:
     resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==}
 
-  micromark-util-subtokenize@1.1.0:
-    resolution: {integrity: sha512-kUQHyzRoxvZO2PuLzMt2P/dwVsTiivCK8icYTeR+3WgbuPqfHgPPy7nFKbeqRivBvn/3N3GBiNC+JRTMSxEC7A==}
-
   micromark-util-subtokenize@2.1.0:
     resolution: {integrity: sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==}
 
@@ -5486,9 +7213,6 @@ packages:
   micromark-util-types@2.0.2:
     resolution: {integrity: sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==}
 
-  micromark@3.2.0:
-    resolution: {integrity: sha512-uD66tJj54JLYq0De10AhWycZWGQNUvDI55xPgk2sQM5kn1JYlhbCMTtEeT27+vAhW2FBQxLlOmS3pmA7/2z4aA==}
-
   micromark@4.0.2:
     resolution: {integrity: sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==}
 
@@ -5508,21 +7232,33 @@ packages:
     resolution: {integrity: sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==}
     engines: {node: '>= 0.6'}
 
-  mime-types@3.0.1:
-    resolution: {integrity: sha512-xRc4oEhT6eaBpU1XF7AjpOFD+xQmXNB5OVKwp4tqCuBpHLS/ZbBDrc07mYTDqVMg6PfxUjjNp85O6Cd2Z/5HWA==}
-    engines: {node: '>= 0.6'}
+  mime-types@3.0.2:
+    resolution: {integrity: sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==}
+    engines: {node: '>=18'}
+
+  mimic-fn@2.1.0:
+    resolution: {integrity: sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==}
+    engines: {node: '>=6'}
 
   mimic-function@5.0.1:
     resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
     engines: {node: '>=18'}
 
-  minimatch@10.0.3:
-    resolution: {integrity: sha512-IPZ167aShDZZUMdRk66cyQAW3qr0WzbHkPdMYa8bzZhlHhO3jALbKdxcaak7W9FfT2rZNpQuUu4Od7ILEpXSaw==}
+  minimatch@10.1.2:
+    resolution: {integrity: sha512-fu656aJ0n2kcXwsnwnv9g24tkU5uSmOlTjd6WyyaKm2Z+h1qmY6bAjrcaIxF/BslFqbZ8UBtbJi7KgQOZD2PTw==}
     engines: {node: 20 || >=22}
 
+  minimatch@10.2.2:
+    resolution: {integrity: sha512-+G4CpNBxa5MprY+04MbgOw1v7So6n5JY166pFi9KfYwT78fxScCeSNQSNzp6dpPSW2rONOps6Ocam1wFhCgoVw==}
+    engines: {node: 18 || 20 || >=22}
+
   minimatch@3.1.2:
     resolution: {integrity: sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==}
 
+  minimatch@5.1.6:
+    resolution: {integrity: sha512-lKwV/1brpG6mBUFHtb7NUmtABCb2WZZmm2wNiOA5hAb8VdCS4B3dtMWyvcoViccwAW/COERjXLt0zP1zXUN26g==}
+    engines: {node: '>=10'}
+
   minimatch@9.0.5:
     resolution: {integrity: sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==}
     engines: {node: '>=16 || 14 >=14.17'}
@@ -5534,17 +7270,19 @@ packages:
     resolution: {integrity: sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==}
     engines: {node: '>=16 || 14 >=14.17'}
 
-  minizlib@3.1.0:
-    resolution: {integrity: sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==}
-    engines: {node: '>= 18'}
+  minipass@7.1.3:
+    resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==}
+    engines: {node: '>=16 || 14 >=14.17'}
 
-  mkdirp@0.3.0:
-    resolution: {integrity: sha512-OHsdUcVAQ6pOtg5JYWpCBo9W/GySVuwvP9hueRMW7UqshC0tbfzLv8wjySTPm3tfUZ/21CE9E1pJagOA91Pxew==}
-    deprecated: Legacy versions of mkdirp are no longer supported. Please update to mkdirp 1.x. (Note that the API surface has changed to use Promises in 1.x.)
+  minisearch@7.2.0:
+    resolution: {integrity: sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg==}
 
   mlly@1.8.0:
     resolution: {integrity: sha512-l8D9ODSRWLe2KHJSifWGwBqpTZXIXTeo8mlKjY+E2HAakaTeNpqAyBZ8GSqLzHgw4XmHmC8whvpjJNMbFZN7/g==}
 
+  monaco-editor@0.55.1:
+    resolution: {integrity: sha512-jz4x+TJNFHwHtwuV9vA9rMujcZRb0CEilTEwG2rRSpe/A7Jdkuj8xPKttCgOh+v/lkHy7HsZ64oj+q3xoAFl9A==}
+
   mri@1.2.0:
     resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==}
     engines: {node: '>=4'}
@@ -5559,10 +7297,6 @@ packages:
   muggle-string@0.4.1:
     resolution: {integrity: sha512-VNTrAak/KhO2i8dqqnqnAHOa3cYBwXEZe9h+D5h/1ZqFSTEFHdM65lR7RoIqq3tBBYavsOXV84NoHXZ0AkPyqQ==}
 
-  mustache@4.2.0:
-    resolution: {integrity: sha512-71ippSywq5Yb7/tVYyGbkBggbU8H3u5Rz56fH60jGFgr8uHwxs+aSKeqmluIVzM0m0kB7xQjKS6qPfd0b2ZoqQ==}
-    hasBin: true
-
   mz@2.7.0:
     resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==}
 
@@ -5571,15 +7305,36 @@ packages:
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
     hasBin: true
 
+  nanoid@3.3.12:
+    resolution: {integrity: sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
   nanoid@5.1.6:
     resolution: {integrity: sha512-c7+7RQ+dMB5dPwwCp4ee1/iV/q2P6aK1mTZcfr1BTuVlyW9hJYiMPybJCcnBlQtuSmTIWNeazm/zqNoZSSElBg==}
     engines: {node: ^18 || >=20}
     hasBin: true
 
+  nanostores@1.1.0:
+    resolution: {integrity: sha512-yJBmDJr18xy47dbNVlHcgdPrulSn1nhSE6Ns9vTG+Nx9VPT6iV1MD6aQFp/t52zpf82FhLLTXAXr30NuCnxvwA==}
+    engines: {node: ^20.0.0 || >=22.0.0}
+
+  negotiator@1.0.0:
+    resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
+    engines: {node: '>= 0.6'}
+
   neotraverse@0.6.18:
     resolution: {integrity: sha512-Z4SmBUweYa09+o6pG+eASabEpP6QkQ70yHj351pQoEXIs8uHbaU2DWVmzBANKgflPa47A50PtB2+NgRpQvr7vA==}
     engines: {node: '>= 10'}
 
+  neverpanic@0.0.7:
+    resolution: {integrity: sha512-GFRTSX2JAEATOCQYlyFkR+9FJPl0pD24toE1foqYAsL6aPLlRKn6L0UFOtJhZCxEbDv+SUsiW4AcPs9cIFwkFw==}
+    peerDependencies:
+      typescript: '5'
+
+  nice-try@1.0.5:
+    resolution: {integrity: sha512-1nh45deeb5olNY7eX82BkPO7SSxR5SSYJiPTrTdFUVYwAl8CKMA5N9PjTYkHiRjisVcxcQ1HXdLhx2qxxJzLNQ==}
+
   nimma@0.2.3:
     resolution: {integrity: sha512-1ZOI8J+1PKKGceo/5CT5GfQOG6H8I2BencSK06YarZ2wXwH37BSSUWldqJmMJYA5JfqDqffxDXynt6f11AyKcA==}
     engines: {node: ^12.20 || >=14.13}
@@ -5593,11 +7348,6 @@ packages:
   node-addon-api@7.1.1:
     resolution: {integrity: sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==}
 
-  node-domexception@1.0.0:
-    resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==}
-    engines: {node: '>=10.5.0'}
-    deprecated: Use your platform's native DOMException instead
-
   node-fetch-native@1.6.7:
     resolution: {integrity: sha512-g9yhqoedzIUm0nTnTqAQvueMPVOuIY16bqgAJJC8XOOubYFNwz6IER9qs0Gq2Xd0+CecCKFjtdDTMA4u4xG06Q==}
 
@@ -5619,8 +7369,8 @@ packages:
       encoding:
         optional: true
 
-  node-mock-http@1.0.3:
-    resolution: {integrity: sha512-jN8dK25fsfnMrVsEhluUTPkBFY+6ybu7jSB1n+ri/vOGjJxU8J9CZhpSGkHXSkFjtUhbmoncG/YG9ta5Ludqog==}
+  node-mock-http@1.0.4:
+    resolution: {integrity: sha512-8DY+kFsDkNXy1sJglUfuODx1/opAGJGyrTuFqEoN90oRc2Vk0ZbD4K2qmKXBBEhZQzdKHIVfEJpDU8Ak2NJEvQ==}
 
   node-releases@2.0.23:
     resolution: {integrity: sha512-cCmFDMSm26S6tQSDpBCg/NR8NENrVPhAJSf+XbxBG4rPFaaonlEoE9wHQmun+cls499TQGSb7ZyPBRlzgKfpeg==}
@@ -5633,9 +7383,9 @@ packages:
     resolution: {integrity: sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==}
     engines: {node: '>=0.10.0'}
 
-  normalize-range@0.1.2:
-    resolution: {integrity: sha512-bdok/XvKII3nUpklnV6P2hxtMNrCboOjAcyBuQnWEhO665FwrSNRxU+AqpsyvO6LgGYPspN+lu5CLtw4jPRKNA==}
-    engines: {node: '>=0.10.0'}
+  npm-run-path@2.0.2:
+    resolution: {integrity: sha512-lJxZYlT4DW/bRUtFh1MQIWqmLwQfAxnqWG4HhEdjMlkrJYnJn0Jrr2u3mgxqaWsdiBc76TYkTG/mhrnYTuzfHw==}
+    engines: {node: '>=4'}
 
   nth-check@2.1.1:
     resolution: {integrity: sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==}
@@ -5647,10 +7397,6 @@ packages:
     resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
     engines: {node: '>=0.10.0'}
 
-  object-hash@3.0.0:
-    resolution: {integrity: sha512-RSn9F68PjH9HqtltsSnqYC1XXoWe9Bju5+213R98cNGttag9q9yAOTzdbsqvIa7aNm5WffBZFpWYr2aWrklWAw==}
-    engines: {node: '>= 6'}
-
   object-inspect@1.13.4:
     resolution: {integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==}
     engines: {node: '>= 0.4'}
@@ -5663,8 +7409,8 @@ packages:
     resolution: {integrity: sha512-nK28WOo+QIjBkDduTINE4JkF/UJJKyf2EJxvJKfblDpyg0Q+pkOHNTL0Qwy6NP6FhE/EnzV73BxxqcJaXY9anw==}
     engines: {node: '>= 0.4'}
 
-  ofetch@1.4.1:
-    resolution: {integrity: sha512-QZj2DfGplQAr2oj9KzceK9Hwz6Whxazmn85yYeVuS3u9XTMOGMRx0kO95MQ+vLsj/S/NwBDMMLU5hpxvI6Tklw==}
+  obug@2.1.1:
+    resolution: {integrity: sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==}
 
   ofetch@1.5.1:
     resolution: {integrity: sha512-2W4oUZlVaqAPAil6FUg/difl6YhqhUR7x2eZY4bQCko22UXg3hptq9KLQdqFClV+Wu85UX7hNtdGTngi/1BxcA==}
@@ -5679,6 +7425,10 @@ packages:
   once@1.4.0:
     resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==}
 
+  onetime@5.1.2:
+    resolution: {integrity: sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==}
+    engines: {node: '>=6'}
+
   onetime@7.0.0:
     resolution: {integrity: sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==}
     engines: {node: '>=18'}
@@ -5686,55 +7436,19 @@ packages:
   oniguruma-parser@0.12.1:
     resolution: {integrity: sha512-8Unqkvk1RYc6yq2WBYRj4hdnsAxVze8i7iPfQr8e4uSP3tRv0rpZcbGUDvxfQQcdwHt/e9PrMvGCsa8OqG9X3w==}
 
-  oniguruma-to-es@4.3.3:
-    resolution: {integrity: sha512-rPiZhzC3wXwE59YQMRDodUwwT9FZ9nNBwQQfsd1wfdtlKEyCdRV0avrTcSZ5xlIvGRVPd/cx6ZN45ECmS39xvg==}
+  oniguruma-to-es@4.3.4:
+    resolution: {integrity: sha512-3VhUGN3w2eYxnTzHn+ikMI+fp/96KoRSVK9/kMTcFqj1NRDh2IhQCKvYxDnWePKRXY/AqH+Fuiyb7VHSzBjHfA==}
 
-  onnxruntime-common@1.21.0:
-    resolution: {integrity: sha512-Q632iLLrtCAVOTO65dh2+mNbQir/QNTVBG3h/QdZBpns7mZ0RYbLRBgGABPbpU9351AgYy7SJf1WaeVwMrBFPQ==}
-
-  onnxruntime-common@1.22.0-dev.20250409-89f8206ba4:
-    resolution: {integrity: sha512-vDJMkfCfb0b1A836rgHj+ORuZf4B4+cc2bASQtpeoJLueuFc5DuYwjIZUBrSvx/fO5IrLjLz+oTrB3pcGlhovQ==}
-
-  onnxruntime-node@1.21.0:
-    resolution: {integrity: sha512-NeaCX6WW2L8cRCSqy3bInlo5ojjQqu2fD3D+9W5qb5irwxhEyWKXeH2vZ8W9r6VxaMPUan+4/7NDwZMtouZxEw==}
-    os: [win32, darwin, linux]
-
-  onnxruntime-web@1.22.0-dev.20250409-89f8206ba4:
-    resolution: {integrity: sha512-0uS76OPgH0hWCPrFKlL8kYVV7ckM7t/36HfbgoFw6Nd0CZVVbQC4PkrR8mBX8LtNUFZO25IQBqV2Hx2ho3FlbQ==}
-
-  openai@4.104.0:
-    resolution: {integrity: sha512-p99EFNsA/yX6UhVO93f5kJsDRLAg+CTA2RBqdHK4RtK8u5IJw32Hyb2dTGKbnnFmnuoBv5r7Z2CURI9sGZpSuA==}
-    hasBin: true
-    peerDependencies:
-      ws: ^8.18.0
-      zod: ^3.23.8
-    peerDependenciesMeta:
-      ws:
-        optional: true
-      zod:
-        optional: true
-
-  openai@5.12.2:
-    resolution: {integrity: sha512-xqzHHQch5Tws5PcKR2xsZGX9xtch+JQFz5zb14dGqlshmmDAFBFEWmeIpf7wVqWV+w7Emj7jRgkNJakyKE0tYQ==}
-    hasBin: true
-    peerDependencies:
-      ws: ^8.18.0
-      zod: ^3.23.8
-    peerDependenciesMeta:
-      ws:
-        optional: true
-      zod:
-        optional: true
+  open@11.0.0:
+    resolution: {integrity: sha512-smsWv2LzFjP03xmvFoJ331ss6h+jixfA4UUV/Bsiyuu4YJPfN+FIQGOIiv4w9/+MoHkfkJ22UIaQWRVFRfH6Vw==}
+    engines: {node: '>=20'}
 
   openapi-sampler@1.6.1:
     resolution: {integrity: sha512-s1cIatOqrrhSj2tmJ4abFYZQK6l5v+V4toO5q1Pa0DyN8mtyqy2I+Qrj5W9vOELEtybIMQs/TBZGVO/DtTFK8w==}
 
-  openapi-types@12.1.3:
-    resolution: {integrity: sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw==}
-
-  optionator@0.8.3:
-    resolution: {integrity: sha512-+IW9pACdk3XWmmTXG8m3upGUJst5XRGzxMRjXzAuJ1XnIFNvfhjjIuYkDvysnPQ7qzqVzLt78BCruntqRhWQbA==}
-    engines: {node: '>= 0.8.0'}
+  ora@5.4.1:
+    resolution: {integrity: sha512-5b6Y85tPxZZ7QytO+BQzysW31HJku27cRIlkbAXaNx+BdcVi+LlRFmVXzeF6a7JCwJpyw5c4b+YSVImQIrBpuQ==}
+    engines: {node: '>=10'}
 
   ora@8.2.0:
     resolution: {integrity: sha512-weP+BZ8MVNnlCm8c0Qdc1WSWq4Qn7I+9CJGm7Qali6g44e/PUzbjNqJX5NJ9ljlNMosfJvg1fKEGILklK9cwnw==}
@@ -5747,10 +7461,18 @@ packages:
     resolution: {integrity: sha512-qFOyK5PjiWZd+QQIh+1jhdb9LpxTF0qs7Pm8o5QHYZ0M3vKqSqzsZaEB6oWlxZ+q2sJBMI/Ktgd2N5ZwQoRHfg==}
     engines: {node: '>= 0.4'}
 
+  p-event@6.0.1:
+    resolution: {integrity: sha512-Q6Bekk5wpzW5qIyUP4gdMEujObYstZl6DMMOSenwBvV0BlE5LkDwkjs5yHbZmdCEq2o4RJx4tE1vwxFVf2FG1w==}
+    engines: {node: '>=16.17'}
+
   p-filter@2.1.0:
     resolution: {integrity: sha512-ZBxxZ5sL2HghephhpGAQdoskxplTwr7ICaehZwLIlfL6acuVgZPm8yBNuRAFBGEqtD/hmUeq9eqLg2ys9Xr/yw==}
     engines: {node: '>=8'}
 
+  p-filter@4.1.0:
+    resolution: {integrity: sha512-37/tPdZ3oJwHaS3gNJdenCDB3Tz26i9sjhnguBtvN0vYlRIiDNnvTWkuh+0hETV9rLPdJ3rlL3yVOYPIAnM8rw==}
+    engines: {node: '>=18'}
+
   p-finally@1.0.0:
     resolution: {integrity: sha512-LICb2p9CB7FS+0eR1oqWnHhp0FljGLZCWBE9aix0Uye9W8LTQPwMTYVGWQWIw9RdQiDg4+epXQODwIYJtSJaow==}
     engines: {node: '>=4'}
@@ -5759,9 +7481,9 @@ packages:
     resolution: {integrity: sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==}
     engines: {node: '>=6'}
 
-  p-limit@6.2.0:
-    resolution: {integrity: sha512-kuUqqHNUqoIWp/c467RI4X6mmyuojY5jGutNU0wVTmEOOfcuwLqyMVoAi9MKi2Ak+5i9+nhmrK4ufZE8069kHA==}
-    engines: {node: '>=18'}
+  p-limit@7.3.0:
+    resolution: {integrity: sha512-7cIXg/Z0M5WZRblrsOla88S4wAK+zOQQWeBYfV3qJuJXMr+LnbYjaadrFaS0JILfEDPVqHyKnZ1Z/1d6J9VVUw==}
+    engines: {node: '>=20'}
 
   p-locate@4.1.0:
     resolution: {integrity: sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==}
@@ -5771,26 +7493,22 @@ packages:
     resolution: {integrity: sha512-y3b8Kpd8OAN444hxfBbFfj1FY/RjtTd8tzYwhUqNYXx0fXx2iX4maP4Qr6qhIKbQXI02wTLAda4fYUbDagTUFw==}
     engines: {node: '>=6'}
 
-  p-queue@6.6.2:
-    resolution: {integrity: sha512-RwFpb72c/BhQLEXIZ5K2e+AhgNVmIejGlTgiB9MzZ0e93GRvqZ7uSi0dvRF7/XIXDeNkra2fNHBxTyPDGySpjQ==}
-    engines: {node: '>=8'}
-
-  p-queue@8.1.1:
-    resolution: {integrity: sha512-aNZ+VfjobsWryoiPnEApGGmf5WmNsCo9xu8dfaYamG5qaLP7ClhLN6NgsFe6SwJ2UbLEBK5dv9x8Mn5+RVhMWQ==}
+  p-map@7.0.4:
+    resolution: {integrity: sha512-tkAQEw8ysMzmkhgw8k+1U/iPhWNhykKnSk4Rd5zLoPJCuJaGRPo6YposrZgaxHKzDHdDWWZvE/Sk7hsL2X/CpQ==}
     engines: {node: '>=18'}
 
-  p-retry@4.6.2:
-    resolution: {integrity: sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ==}
-    engines: {node: '>=8'}
-
-  p-timeout@3.2.0:
-    resolution: {integrity: sha512-rhIwUycgwwKcP9yTOOFK/AKsAopjjCakVqLHePO3CC6Mir1Z99xT+R63jZxAT5lFZLa2inS5h+ZS2GvR99/FBg==}
-    engines: {node: '>=8'}
+  p-queue@9.1.0:
+    resolution: {integrity: sha512-O/ZPaXuQV29uSLbxWBGGZO1mCQXV2BLIwUr59JUU9SoH76mnYvtms7aafH/isNSNGwuEfP6W/4xD0/TJXxrizw==}
+    engines: {node: '>=20'}
 
   p-timeout@6.1.4:
     resolution: {integrity: sha512-MyIV3ZA/PmyBN/ud8vV9XzwTrNtR4jFrObymZYnZqMmW0zA8Z17vnT0rBgFE/TlohB+YCHqXMgZzb3Csp49vqg==}
     engines: {node: '>=14.16'}
 
+  p-timeout@7.0.1:
+    resolution: {integrity: sha512-AxTM2wDGORHGEkPCt8yqxOTMgpfbEHqF51f/5fJCmwFC3C/zNcGT63SymH2ttOAaiIws2zVg4+izQCjrakcwHg==}
+    engines: {node: '>=20'}
+
   p-try@2.2.0:
     resolution: {integrity: sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==}
     engines: {node: '>=6'}
@@ -5805,21 +7523,16 @@ packages:
   package-manager-detector@0.2.11:
     resolution: {integrity: sha512-BEnLolu+yuz22S56CU1SUKq3XC3PkwD5wv4ikR4MfGvnRVcmzXR9DwSlW2fEamyTPyXHomBJRzgapeuBvRNzJQ==}
 
-  package-manager-detector@1.4.0:
-    resolution: {integrity: sha512-rRZ+pR1Usc+ND9M2NkmCvE/LYJS+8ORVV9X0KuNSY/gFsp7RBHJM/ADh9LYq4Vvfq6QkKrW6/weuh8SMEtN5gw==}
-
-  package-manager-detector@1.5.0:
-    resolution: {integrity: sha512-uBj69dVlYe/+wxj8JOpr97XfsxH/eumMt6HqjNTmJDf/6NO9s+0uxeOneIz3AsPt2m6y9PqzDzd3ATcU17MNfw==}
-
-  packrup@0.1.2:
-    resolution: {integrity: sha512-ZcKU7zrr5GlonoS9cxxrb5HVswGnyj6jQvwFBa6p5VFw7G71VAHcUKL5wyZSU/ECtPM/9gacWxy2KFQKt1gMNA==}
+  package-manager-detector@1.6.0:
+    resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
 
   pagefind@1.4.0:
     resolution: {integrity: sha512-z2kY1mQlL4J8q5EIsQkLzQjilovKzfNVhX8De6oyE6uHpfFtyBaqUpcl/XzJC/4fjD8vBDyh1zolimIcVrCn9g==}
     hasBin: true
 
-  pako@0.2.9:
-    resolution: {integrity: sha512-NUcwaKxUxWrZLpDG+z/xZaCgQITkA/Dv4V/T6bw7VON6l1Xz/VnrBqrYjZQ12TamKHzITTfOEIYUj48y2KXImA==}
+  pagefind@1.5.2:
+    resolution: {integrity: sha512-XTUaK0hXMCu2jszWE584JGQT7y284TmMV9l/HX3rnG5uo3rHI/uHU56XTyyyPFjeWEBxECbAi0CaFDJOONtG0Q==}
+    hasBin: true
 
   pako@2.1.0:
     resolution: {integrity: sha512-w+eufiZ1WuJYgPXbV/PO3NCMEc3xqylkKHzp8bxp1uW4qaSNQUkwmLLEc3kKsfz8lpV1F8Ht3U1Cm+9Srog2ug==}
@@ -5836,13 +7549,17 @@ packages:
   parse-latin@7.0.0:
     resolution: {integrity: sha512-mhHgobPPua5kZ98EF4HWiH167JWBfl4pvAIXXdbaVohtK7a6YBOy56kvhCqduqyo/f3yrHFWmqmiMg/BkBkYYQ==}
 
-  parse-ms@3.0.0:
-    resolution: {integrity: sha512-Tpb8Z7r7XbbtBTrM9UhpkzzaMrqA2VXMT3YChzYltwV3P3pM6t8wl7TvpMnSTosz1aQAdVib7kdoys7vYOPerw==}
-    engines: {node: '>=12'}
+  parse-ms@4.0.0:
+    resolution: {integrity: sha512-TXfryirbmq34y8QBwgqCVLi+8oA3oWx2eAnSn62ITyEhEYaWRlVZ2DvMM9eZbMs/RfxPu/PK/aBLyGj4IrqMHw==}
+    engines: {node: '>=18'}
 
   parse5@7.3.0:
     resolution: {integrity: sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==}
 
+  parseurl@1.3.3:
+    resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==}
+    engines: {node: '>= 0.8'}
+
   pascal-case@3.1.2:
     resolution: {integrity: sha512-uWlGT3YSnK9x3BQJaOdcZwrnV6hPpd8jFH1/ucpiLRPh/2zCVJKS19E4GvYHvaCcACn3foXZ0cLB9Wrx1KGe5g==}
 
@@ -5856,9 +7573,13 @@ packages:
     resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==}
     engines: {node: '>=8'}
 
-  path-is-absolute@1.0.1:
-    resolution: {integrity: sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==}
-    engines: {node: '>=0.10.0'}
+  path-expression-matcher@1.2.1:
+    resolution: {integrity: sha512-d7gQQmLvAKXKXE2GeP9apIGbMYKz88zWdsn/BN2HRWVQsDFdUY36WSLTY0Jvd4HWi7Fb30gQ62oAOzdgJA6fZw==}
+    engines: {node: '>=14.0.0'}
+
+  path-key@2.0.1:
+    resolution: {integrity: sha512-fEHGKCSmUSDPv4uoj8AlD+joPlq3peND+HRYyxFz4KPw4z926S/b8rIuFs2FYJg3BwsxJf6A9/3eIdLaYC+9Dw==}
+    engines: {node: '>=4'}
 
   path-key@3.1.1:
     resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==}
@@ -5875,12 +7596,20 @@ packages:
     resolution: {integrity: sha512-ypGJsmGtdXUOeM5u93TyeIEfEhM6s+ljAhrk5vAvSx8uyY/02OvrZnA0YNGUrPXfpJMgI1ODd3nwz8Npx4O4cg==}
     engines: {node: 20 || >=22}
 
+  path-scurry@2.0.2:
+    resolution: {integrity: sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==}
+    engines: {node: 18 || 20 || >=22}
+
+  path-to-regexp@8.3.0:
+    resolution: {integrity: sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA==}
+
   path-type@4.0.0:
     resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==}
     engines: {node: '>=8'}
 
-  pathe@1.1.2:
-    resolution: {integrity: sha512-whLdWMYL2TwI08hn8/ZqAbrVemu0LNaNNJZX73O6qaIdCTfXutsLhMkjdENX0qhsQ9uIimo4/aQOmXkoon2nDQ==}
+  path-type@6.0.0:
+    resolution: {integrity: sha512-Vj7sf++t5pBD637NSfkxpHSMfWaeig5+DKWLhcqIYx6mWQz5hdJTGDVMQiJcw1ZYkhs7AazKDGpRVji1LJCZUQ==}
+    engines: {node: '>=18'}
 
   pathe@2.0.3:
     resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
@@ -5899,8 +7628,8 @@ packages:
     resolution: {integrity: sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==}
     engines: {node: '>=8.6'}
 
-  picomatch@4.0.3:
-    resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==}
+  picomatch@4.0.4:
+    resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
     engines: {node: '>=12'}
 
   pify@2.3.0:
@@ -5915,22 +7644,23 @@ packages:
     resolution: {integrity: sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==}
     engines: {node: '>= 6'}
 
+  pkce-challenge@5.0.1:
+    resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
+    engines: {node: '>=16.20.0'}
+
   pkg-types@1.3.1:
     resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==}
 
   pkg-types@2.3.0:
     resolution: {integrity: sha512-SIqCzDRg0s9npO5XQ3tNZioRY1uK06lA41ynBC1YmFTmnY6FjUjVt6s4LoADmwoig1qqD0oK8h1p/8mlMx8Oig==}
 
-  platform@1.3.6:
-    resolution: {integrity: sha512-fnWVljUchTro6RiCFvCXBbNhJc2NijN7oIQxbwsyL0buWJPG85v81ehlHI9fXrJsMNgTofEoWIQeClKpgxFLrg==}
-
-  playwright-core@1.56.0:
-    resolution: {integrity: sha512-1SXl7pMfemAMSDn5rkPeZljxOCYAmQnYLBTExuh6E8USHXGSX3dx6lYZN/xPpTz1vimXmPA9CDnILvmJaB8aSQ==}
+  playwright-core@1.58.2:
+    resolution: {integrity: sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg==}
     engines: {node: '>=18'}
     hasBin: true
 
-  playwright@1.56.0:
-    resolution: {integrity: sha512-X5Q1b8lOdWIE4KAoHpW3SE8HvUB+ZZsUoN64ZhjnN8dOb1UpujxBtENGiZFE+9F/yhzJwYa+ca3u43FeLbboHA==}
+  playwright@1.58.2:
+    resolution: {integrity: sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A==}
     engines: {node: '>=18'}
     hasBin: true
 
@@ -5948,28 +7678,26 @@ packages:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
     engines: {node: '>= 0.4'}
 
-  postcss-import@15.1.0:
-    resolution: {integrity: sha512-hpr+J05B2FVYUAXHeK1YyI267J/dDDhMU6B6civm8hSY1jYJnBXxzKDKDswzJmtLHryrjhnDjqqp/49t8FALew==}
-    engines: {node: '>=14.0.0'}
+  postcss-cli@11.0.1:
+    resolution: {integrity: sha512-0UnkNPSayHKRe/tc2YGW6XnSqqOA9eqpiRMgRlV1S6HdGi16vwJBx7lviARzbV1HpQHqLLRH3o8vTcB0cLc+5g==}
+    engines: {node: '>=18'}
+    hasBin: true
     peerDependencies:
       postcss: ^8.0.0
 
-  postcss-js@4.1.0:
-    resolution: {integrity: sha512-oIAOTqgIo7q2EOwbhb8UalYePMvYoIeRY2YKntdpFQXNosSu3vLrniGgmH9OKs/qAkfoj5oB3le/7mINW1LCfw==}
-    engines: {node: ^12 || ^14 || >= 16}
-    peerDependencies:
-      postcss: ^8.4.21
-
-  postcss-load-config@4.0.2:
-    resolution: {integrity: sha512-bSVhyJGL00wMVoPUzAVAnbEoWyqRxkjv64tUl427SKnPrENtq6hJwUojroMz2VB+Q1edmi4IfrAPpami5VVgMQ==}
-    engines: {node: '>= 14'}
+  postcss-load-config@5.1.0:
+    resolution: {integrity: sha512-G5AJ+IX0aD0dygOE0yFZQ/huFFMSNneyfp0e3/bT05a8OfPC5FUoZRPfGijUdGOJNMewJiwzcHJXFafFzeKFVA==}
+    engines: {node: '>= 18'}
     peerDependencies:
+      jiti: '>=1.21.0'
       postcss: '>=8.0.9'
-      ts-node: '>=9.0.0'
+      tsx: ^4.8.1
     peerDependenciesMeta:
+      jiti:
+        optional: true
       postcss:
         optional: true
-      ts-node:
+      tsx:
         optional: true
 
   postcss-load-config@6.0.1:
@@ -5996,6 +7724,12 @@ packages:
     peerDependencies:
       postcss: ^8.2.14
 
+  postcss-reporter@7.1.0:
+    resolution: {integrity: sha512-/eoEylGWyy6/DOiMP5lmFRdmDKThqgn7D6hP2dXKJI/0rJSO1ADFNngZfDzxL0YAxFvws+Rtpuji1YIHj4mySA==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      postcss: ^8.1.0
+
   postcss-selector-parser@6.0.10:
     resolution: {integrity: sha512-IQ7TZdoaqbT+LCpShg46jnZVlhWD2w6iQYAcYXfHARZ7X1t/UGhhceQDs5X0cGqKvYlHNOuv7Oa1xmb0oQuA3w==}
     engines: {node: '>=4'}
@@ -6004,13 +7738,18 @@ packages:
     resolution: {integrity: sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg==}
     engines: {node: '>=4'}
 
-  postcss-value-parser@4.2.0:
-    resolution: {integrity: sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==}
+  postcss@8.5.15:
+    resolution: {integrity: sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==}
+    engines: {node: ^10 || ^12 || >=14}
 
   postcss@8.5.6:
     resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==}
     engines: {node: ^10 || ^12 || >=14}
 
+  powershell-utils@0.1.0:
+    resolution: {integrity: sha512-dM0jVuXJPsDN6DvRpea484tCUaMiXWjuCn++HGTqUWzGDjv5tZkEZldAJ/UMlqRYGFrD/etByo4/xOuC/snX2A==}
+    engines: {node: '>=20'}
+
   preact-render-to-string@6.5.11:
     resolution: {integrity: sha512-ubnauqoGczeGISiOh6RjX0/cdaF8v/oDXIjO85XALCQjwQP+SB4RDXXtvZ6yTYSjG+PC1QRP2AhPgCEsM2EvUw==}
     peerDependencies:
@@ -6019,19 +7758,13 @@ packages:
   preact@10.24.3:
     resolution: {integrity: sha512-Z2dPnBnMUfyQfSQ+GBdsGa16hz35YmLmtTLhM169uW944hYL6xzTYkJjC07j+Wosz733pMWx0fgON3JNw1jJQA==}
 
-  prelude-ls@1.1.2:
-    resolution: {integrity: sha512-ESF23V4SKG6lVSGZgYNpbsiaAkdab6ZgOxe52p7+Kid3W3u3bxR4Vfd/o21dmN7jSt0IwgZ4v5MUd26FEtXE9w==}
-    engines: {node: '>= 0.8.0'}
+  preact@10.28.3:
+    resolution: {integrity: sha512-tCmoRkPQLpBeWzpmbhryairGnhW9tKV6c6gr/w+RhoRoKEJwsjzipwp//1oCpGPOchvSLaAPlpcJi9MwMmoPyA==}
 
   prettier-plugin-astro@0.14.1:
     resolution: {integrity: sha512-RiBETaaP9veVstE4vUwSIcdATj6dKmXljouXc/DDNwBSPTp8FRkLGDSGFClKsAFeeg+13SB0Z1JZvbD76bigJw==}
     engines: {node: ^14.15.0 || >=16.0.0}
 
-  prettier@2.8.7:
-    resolution: {integrity: sha512-yPngTo3aXUUmyuTjeTUT75txrf+aMh9FiD7q9ZE/i6r0bPb22g4FsE6Y338PQX1bmfy08i9QQCB7/rcUAVntfw==}
-    engines: {node: '>=10.13.0'}
-    hasBin: true
-
   prettier@2.8.8:
     resolution: {integrity: sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==}
     engines: {node: '>=10.13.0'}
@@ -6042,24 +7775,24 @@ packages:
     engines: {node: '>=14'}
     hasBin: true
 
-  pretty-bytes@6.1.1:
-    resolution: {integrity: sha512-mQUvGU6aUFQ+rNvTIAcZuWGRT9a6f6Yrg9bHs4ImKF+HZCEK+plBvnAZYSIQztknZF2qnzNtr6F8s0+IuptdlQ==}
-    engines: {node: ^14.13.1 || >=16.0.0}
-
-  pretty-ms@8.0.0:
-    resolution: {integrity: sha512-ASJqOugUF1bbzI35STMBUpZqdfYKlJugy6JBziGi2EE+AL5JPJGSzvpeVXojxrr0ViUYoToUjb5kjSEGf7Y83Q==}
-    engines: {node: '>=14.16'}
+  pretty-hrtime@1.0.3:
+    resolution: {integrity: sha512-66hKPCr+72mlfiSjlEB1+45IjXSqvVAIy6mocupoww4tBFE9R9IhwwUGoI4G++Tc9Aq+2rxOt0RFU6gPcrte0A==}
+    engines: {node: '>= 0.8'}
 
-  prismjs@1.27.0:
-    resolution: {integrity: sha512-t13BGPUlFDR7wRB5kQDG4jjl7XeuH6jbJGt11JHPL96qwsEHNX2+68tFXqc1/k+/jALsbSWJKUOT/hcYAZ5LkA==}
-    engines: {node: '>=6'}
+  pretty-ms@9.3.0:
+    resolution: {integrity: sha512-gjVS5hOP+M3wMm5nmNOucbIrqudzs9v/57bWRHQWLYklXqoXKrVfYW2W9+glfGsqtPgpiz5WwyEEB+ksXIx3gQ==}
+    engines: {node: '>=18'}
 
   prismjs@1.30.0:
     resolution: {integrity: sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw==}
     engines: {node: '>=6'}
 
-  prompts@2.4.2:
-    resolution: {integrity: sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q==}
+  process-ancestry@0.1.0:
+    resolution: {integrity: sha512-tGqJW/UnclpYASFcM6Xh8D8l/BMtaQ9+CSG0vlJSJTcdMM4lDRv4c6H0Pdcsfted+bVczdYSfk2fdukg2gQkZg==}
+    engines: {node: '>=18.0.0'}
+
+  prompts@2.1.0:
+    resolution: {integrity: sha512-+x5TozgqYdOwWsQFZizE/Tra3fKvAoy037kOyU6cgz84n8f6zxngLOV4O32kTwt9FcLCxAqw0P/c8rOr9y+Gfg==}
     engines: {node: '>= 6'}
 
   proper-lockfile@4.1.2:
@@ -6081,8 +7814,16 @@ packages:
     resolution: {integrity: sha512-CvexbZtbov6jW2eXAvLukXjXUW1TzFaivC46BpWc/3BpcCysb5Vffu+B3XHMm8lVEuy2Mm4XGex8hBSg1yapPg==}
     engines: {node: '>=12.0.0'}
 
-  proxy-from-env@1.1.0:
-    resolution: {integrity: sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==}
+  proxy-addr@2.0.7:
+    resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==}
+    engines: {node: '>= 0.10'}
+
+  proxy-from-env@2.1.0:
+    resolution: {integrity: sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA==}
+    engines: {node: '>=10'}
+
+  pump@3.0.3:
+    resolution: {integrity: sha512-todwxLMY7/heScKmntwQG8CXVkWUOdYxIvY2s0VWAAMh/nd8SoYiRaKjlr7+iCs984f2P8zvrfWcDDYVb73NfA==}
 
   punycode@2.3.1:
     resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
@@ -6092,6 +7833,10 @@ packages:
     resolution: {integrity: sha512-LjgDO2zPtoXP2wJpDjZrGdojii1uqO0cnwKoIoUzkfS98HDmbeiGmYiXo3lXeFlq2xvne1QFQhwYXSUCLKtEuA==}
     engines: {node: '>=12.20'}
 
+  qs@6.14.1:
+    resolution: {integrity: sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ==}
+    engines: {node: '>=0.6'}
+
   quansync@0.2.11:
     resolution: {integrity: sha512-AifT7QEbW9Nri4tAwR5M/uzpBuqfZf+zwaEM/QkzEjj7NBuFD2rBuy0K3dE+8wltbezDV7JMA0WfnCPYRSYbXA==}
 
@@ -6106,10 +7851,17 @@ packages:
   radix3@1.1.2:
     resolution: {integrity: sha512-b484I/7b8rDEdSDKckSSBA8knMpcdsXudlE/LNL639wFoHKwLbEkQFZHWEYwDC0wa0FKUcCY+GAF73Z7wxNVFA==}
 
+  railroad-diagrams@1.0.0:
+    resolution: {integrity: sha512-cz93DjNeLY0idrCNOH6PviZGRN9GJhsdm9hpn1YCS879fj4W+x5IFJhhkRZcwVgMmFF7R82UA/7Oh+R8lLZg6A==}
+
   range-parser@1.2.1:
     resolution: {integrity: sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==}
     engines: {node: '>= 0.6'}
 
+  raw-body@3.0.2:
+    resolution: {integrity: sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==}
+    engines: {node: '>= 0.10'}
+
   rc@1.2.8:
     resolution: {integrity: sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw==}
     hasBin: true
@@ -6119,6 +7871,16 @@ packages:
     peerDependencies:
       react: ^18.3.1
 
+  react-dom@19.2.4:
+    resolution: {integrity: sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==}
+    peerDependencies:
+      react: ^19.2.4
+
+  react-error-boundary@4.1.2:
+    resolution: {integrity: sha512-GQDxZ5Jd+Aq/qUxbCm1UtzmL/s++V7zKgE8yMktJiCQXCCFZnMZh9ng+6/Ne6PjNSXH0L9CjeOEREfRnq6Duag==}
+    peerDependencies:
+      react: '>=16.13.1'
+
   react-markdown@10.1.0:
     resolution: {integrity: sha512-qKxVopLT/TyA6BX3Ue5NwabOsAzm0Q7kAPwq6L+wWDwisYs7R8vZ0nRXqq6rkueboxpkjvLGU9fWifiX/ZZFxQ==}
     peerDependencies:
@@ -6129,6 +7891,10 @@ packages:
     resolution: {integrity: sha512-z6F7K9bV85EfseRCp2bzrpyQ0Gkw1uLoCel9XBVWPg/TjRj94SkJzUTGfOa4bs7iJvBWtQG0Wq7wnI0syw3EBQ==}
     engines: {node: '>=0.10.0'}
 
+  react-refresh@0.18.0:
+    resolution: {integrity: sha512-QgT5//D3jfjJb6Gsjxv0Slpj23ip+HtOpnNgnb2S5zU3CB26G/IDPGoy4RJB42wzFE46DRsstbW6tKHoKbhAxw==}
+    engines: {node: '>=0.10.0'}
+
   react-remove-scroll-bar@2.3.8:
     resolution: {integrity: sha512-9r+yi9+mgU33AKcj6IbT9oRCO78WriSj6t/cF8DWBZJ9aOGPOTEDvdUDz1FwKim7QXWwmHqtdHnRJfhAxEG46Q==}
     engines: {node: '>=10'}
@@ -6149,6 +7915,43 @@ packages:
       '@types/react':
         optional: true
 
+  react-router-dom@7.13.1:
+    resolution: {integrity: sha512-UJnV3Rxc5TgUPJt2KJpo1Jpy0OKQr0AjgbZzBFjaPJcFOb2Y8jA5H3LT8HUJAiRLlWrEXWHbF1Z4SCZaQjWDHw==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+
+  react-router@7.13.1:
+    resolution: {integrity: sha512-td+xP4X2/6BJvZoX6xw++A2DdEi++YypA69bJUV5oVvqf6/9/9nNlD70YO1e9d3MyamJEBQFEzk6mbfDYbqrSA==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+
+  react-scan@0.4.3:
+    resolution: {integrity: sha512-jhAQuQ1nja6HUYrSpbmNFHqZPsRCXk8Yqu0lHoRIw9eb8N96uTfXCpVyQhTTnJ/nWqnwuvxbpKVG/oWZT8+iTQ==}
+    hasBin: true
+    peerDependencies:
+      '@remix-run/react': '>=1.0.0'
+      next: '>=13.0.0'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-router: ^5.0.0 || ^6.0.0 || ^7.0.0
+      react-router-dom: ^5.0.0 || ^6.0.0 || ^7.0.0
+    peerDependenciesMeta:
+      '@remix-run/react':
+        optional: true
+      next:
+        optional: true
+      react-router:
+        optional: true
+      react-router-dom:
+        optional: true
+
   react-style-singleton@2.2.3:
     resolution: {integrity: sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==}
     engines: {node: '>=10'}
@@ -6168,6 +7971,10 @@ packages:
     resolution: {integrity: sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==}
     engines: {node: '>=0.10.0'}
 
+  react@19.2.4:
+    resolution: {integrity: sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==}
+    engines: {node: '>=0.10.0'}
+
   read-cache@1.0.0:
     resolution: {integrity: sha512-Owdv/Ft7IjOgm/i0xvNDZ1LrRANRfew4b2prF3OWMQLxLfu3bS8FVhCsrSCMK4lR56Y9ya+AThoTpDCTxCmpRA==}
 
@@ -6175,6 +7982,10 @@ packages:
     resolution: {integrity: sha512-VIMnQi/Z4HT2Fxuwg5KrY174U1VdUIASQVWXXyqtNRtxSr9IYkn1rsI6Tb6HsrHCmB7gVpNwX6JxPTHcH6IoTA==}
     engines: {node: '>=6'}
 
+  readable-stream@3.6.2:
+    resolution: {integrity: sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==}
+    engines: {node: '>= 6'}
+
   readdirp@3.6.0:
     resolution: {integrity: sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==}
     engines: {node: '>=8.10.0'}
@@ -6183,6 +7994,14 @@ packages:
     resolution: {integrity: sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==}
     engines: {node: '>= 14.18.0'}
 
+  readdirp@5.0.0:
+    resolution: {integrity: sha512-9u/XQ1pvrQtYyMpZe7DXKv2p5CNvyVwzUB6uhLAnQwHMSgKMBR62lc7AHljaeteeHXn11XTAaLLUVZYVZyuRBQ==}
+    engines: {node: '>= 20.19.0'}
+
+  recast@0.23.11:
+    resolution: {integrity: sha512-YTUo+Flmw4ZXiWfQKGcwwc11KnoRAYgzAE2E7mXKCjSviTKShtxBsN6YUUBB2gtaBzKzeKunxhUwNHQuRryhWA==}
+    engines: {node: '>= 4'}
+
   rechoir@0.6.2:
     resolution: {integrity: sha512-HFM8rkZ+i3zrV+4LQjwQ0W+ez98pApMGM3HUrN04j3CqzPOzl9nmP15Y8YXNm8QHGv/eacOVEjqhmWpkRV0NAw==}
     engines: {node: '>= 0.10'}
@@ -6221,10 +8040,17 @@ packages:
     resolution: {integrity: sha512-dYqgNSZbDwkaJ2ceRd9ojCGjBq+mOm9LmtXnAnEGyHhN/5R7iDW2TRw3h+o/jCFxus3P2LfWIIiwowAjANm7IA==}
     engines: {node: '>= 0.4'}
 
+  registry-auth-token@3.3.2:
+    resolution: {integrity: sha512-JL39c60XlzCVgNrO+qq68FoNb56w/m7JYvGR2jT5iR1xBrUA3Mfx5Twk5rqTThPmQKMWydGmq8oFtDlxfrmxnQ==}
+
   registry-auth-token@5.1.0:
     resolution: {integrity: sha512-GdekYuwLXLxMuFTwAPg5UKGLW/UXzQrZvH/Zj791BQif5T05T0RsaLfHc9q3ZOKi7n+BoprPD9mJ0O0k4xzUlw==}
     engines: {node: '>=14'}
 
+  registry-url@3.1.0:
+    resolution: {integrity: sha512-ZbgR5aZEdf4UKZVBPYIgaglBmSF2Hi94s2PcIHhRGFjKYu+chjJdYfHn4rt3hB6eCKLJ8giVIIfgMa1ehDfZKA==}
+    engines: {node: '>=0.10.0'}
+
   registry-url@6.0.1:
     resolution: {integrity: sha512-+crtS5QjFRqFCoQmvGduwYWEBng99ZvmFvF+cUJkGYF1L1BfU8C6Zp9T7f5vPAwyLkUExpvK+ANVZmGU49qi4Q==}
     engines: {node: '>=12'}
@@ -6232,8 +8058,11 @@ packages:
   rehype-autolink-headings@7.1.0:
     resolution: {integrity: sha512-rItO/pSdvnvsP4QRB1pmPiNHUskikqtPojZKJPPPAVx9Hj8i8TwMBhofrrAYRhYOOBZH9tgmG5lPqDLuIWPWmw==}
 
-  rehype-expressive-code@0.41.3:
-    resolution: {integrity: sha512-8d9Py4c/V6I/Od2VIXFAdpiO2kc0SV2qTJsRAaqSIcM9aruW4ASLNe2kOEo1inXAAkIhpFzAHTc358HKbvpNUg==}
+  rehype-expressive-code@0.41.7:
+    resolution: {integrity: sha512-25f8ZMSF1d9CMscX7Cft0TSQIqdwjce2gDOvQ+d/w0FovsMwrSt3ODP4P3Z7wO1jsIJ4eYyaDRnIR/27bd/EMQ==}
+
+  rehype-expressive-code@0.44.0:
+    resolution: {integrity: sha512-5r74C5F2sMR3X+QJH8OKWgZBO/cqRw5W1fLT6GVlSfLqepk+4j8tGFkyPqZYWjwntsBHzKPDH2zI68sZ7ScLfA==}
 
   rehype-external-links@3.0.0:
     resolution: {integrity: sha512-yp+e5N9V3C6bwBeAC4n796kc86M4gJCdlVhiMTxIrJG5UHDMh+PJANf9heqORJbt1nrCbDwIlAZKjANIaVBbvw==}
@@ -6272,9 +8101,6 @@ packages:
   remark-directive@3.0.1:
     resolution: {integrity: sha512-gwglrEQEZcZYgVyG1tQuA+h58EZfq5CSULw7J90AFuCTyib1thgHPoqQ+h9iFvU6R+vnZ5oNFQR5QKgGpk741A==}
 
-  remark-gfm@3.0.1:
-    resolution: {integrity: sha512-lEFDoi2PICJyNrACFOfDD3JlLkuSbOa5Wd8EPt06HUdptv8Gn0bxYTdbU/XXQ3swAPkEaGxxPN9cbnMHvVu1Ig==}
-
   remark-gfm@4.0.1:
     resolution: {integrity: sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==}
 
@@ -6308,22 +8134,30 @@ packages:
     resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
     engines: {node: '>=0.10.0'}
 
+  reserved-identifiers@1.2.0:
+    resolution: {integrity: sha512-yE7KUfFvaBFzGPs5H3Ops1RevfUEsDc5Iz65rOwWg4lE8HJSYtle77uul3+573457oHvBKuHYDl/xqUkKpEEdw==}
+    engines: {node: '>=18'}
+
   resolve-from@5.0.0:
     resolution: {integrity: sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==}
     engines: {node: '>=8'}
 
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
   resolve@1.22.10:
     resolution: {integrity: sha512-NPRy+/ncIMeDlTAsuqwKIiferiawhefFJtkNSW0qZJEqMEb+qBt/77B/jGeeek+F0uOeN05CDa6HXbbIgtVX4w==}
     engines: {node: '>= 0.4'}
     hasBin: true
 
+  restore-cursor@3.1.0:
+    resolution: {integrity: sha512-l+sSefzHpj5qimhFSE5a8nufZYAM3sBSVMAPtYkmC+4EH2anSGaEMXSD0izRQbu9nfyQ9y5JrVmp7E8oZrUjvA==}
+    engines: {node: '>=8'}
+
   restore-cursor@5.1.0:
     resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
     engines: {node: '>=18'}
 
-  restructure@3.0.2:
-    resolution: {integrity: sha512-gSfoiOEA0VPE6Tukkrr7I0RBdE0s7H1eFCDBk05l1KIQT1UIKNc5JZy6jdyW6eYH3aR3g5b3PuL77rq0hvwtAw==}
-
   retext-latin@4.0.0:
     resolution: {integrity: sha512-hv9woG7Fy0M9IlRQloq/N6atV82NxLGveq+3H2WOi79dtIYWN8OaxogDm77f8YnVXJL2VD3bbqowu5E3EMhBYA==}
 
@@ -6340,10 +8174,6 @@ packages:
     resolution: {integrity: sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==}
     engines: {node: '>= 4'}
 
-  retry@0.13.1:
-    resolution: {integrity: sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg==}
-    engines: {node: '>= 4'}
-
   reusify@1.1.0:
     resolution: {integrity: sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==}
     engines: {iojs: '>=1.0.0', node: '>=0.10.0'}
@@ -6352,13 +8182,24 @@ packages:
     resolution: {integrity: sha512-l0OE8wL34P4nJH/H2ffoaniAokM2qSmrtXHmlpvYr5AVVX8msAyW0l8NVJFDxlSK4u3Uh/f41cQheDVdnYijwQ==}
     hasBin: true
 
-  roarr@2.15.4:
-    resolution: {integrity: sha512-CHhPh+UNHD2GTXNYhPWLnU8ONHdI+5DI+4EYIAOaiD63rHeYlZvyh8P+in5999TTSFgUYuKUAjzRI4mdh/p+2A==}
-    engines: {node: '>=8.0'}
+  rimraf@6.1.2:
+    resolution: {integrity: sha512-cFCkPslJv7BAXJsYlK1dZsbP8/ZNLkCAQ0bi1hf5EKX2QHegmDFEFA6QhuYJlk7UDdc+02JjO80YSOrWPpw06g==}
+    engines: {node: 20 || >=22}
+    hasBin: true
+
+  rimraf@6.1.3:
+    resolution: {integrity: sha512-LKg+Cr2ZF61fkcaK1UdkH2yEBBKnYjTyWzTJT6KNPcSPaiT7HSdhtMXQuN5wkTX0Xu72KQ1l8S42rlmexS2hSA==}
+    engines: {node: 20 || >=22}
+    hasBin: true
 
   robust-predicates@3.0.2:
     resolution: {integrity: sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg==}
 
+  rolldown@1.1.3:
+    resolution: {integrity: sha512-1F1eEtUBtFvcGm1HQ9TiUIUHPQG7mSAODrhIzjxoUEFuo8OcbrGLiVLkevNgj84TE4lnHvnumwFjhJO5Eu135g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
   rollup@4.52.4:
     resolution: {integrity: sha512-CLEVl+MnPAiKh5pl4dEWSyMTpuflgNQiLGhMv8ezD5W/qP8AKvmYpCOKRRNOh7oRKnauBZ4SyeYkMS+1VSyKwQ==}
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
@@ -6367,9 +8208,17 @@ packages:
   roughjs@4.6.6:
     resolution: {integrity: sha512-ZUz/69+SYpFN/g/lUlo2FXcIjRkSu3nDarreVdGGndHEBJ6cXPdKguS8JGxwj5HA5xIbVKSmLgr5b3AWxtRfvQ==}
 
+  router@2.2.0:
+    resolution: {integrity: sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==}
+    engines: {node: '>= 18'}
+
   rrweb-cssom@0.8.0:
     resolution: {integrity: sha512-guoltQEx+9aMf2gDZ0s62EcV8lsXR+0w8915TC3ITdn2YueuNjdAYh/levpU9nFaoChh9RUS5ZdQMrKfVEN9tw==}
 
+  run-applescript@7.1.0:
+    resolution: {integrity: sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==}
+    engines: {node: '>=18'}
+
   run-parallel@1.2.0:
     resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
 
@@ -6382,10 +8231,6 @@ packages:
   s.color@0.0.15:
     resolution: {integrity: sha512-AUNrbEUHeKY8XsYr/DYpl+qk5+aM+DChopnWOPEzn8YKzOhv4l2zH6LzZms3tOZP3wwdOyc0RmTciyi46HLIuA==}
 
-  sade@1.8.1:
-    resolution: {integrity: sha512-xal3CZX1Xlo/k4ApwCFrHVACi9fBqJ7V+mwhBsuf/1IOKbBy098Fex+Wa/5QMubw09pSZ/u8EY8PWgevJsXp1A==}
-    engines: {node: '>=6'}
-
   safe-array-concat@1.1.3:
     resolution: {integrity: sha512-AURm5f0jYEOydBj7VQlVvDrjeFgthDdEF5H1dP+6mNpoXOMo1quQqJ4wvJDyRZ9+pO3kGWoOdmV08cSv2aJV6Q==}
     engines: {node: '>=0.4'}
@@ -6410,9 +8255,16 @@ packages:
   sass-formatter@0.7.9:
     resolution: {integrity: sha512-CWZ8XiSim+fJVG0cFLStwDvft1VI7uvXdCNJYXhDvowiv+DsbD1nXLiQ4zrE5UBvj5DWZJ93cwN0NX5PMsr1Pw==}
 
+  satteri@0.9.1:
+    resolution: {integrity: sha512-0oIBjwDxWvz8ePRSBxv8vEdZ0GI25/UcSq11y4651tJztUAmZlIdPjFx8luqBAM22g8YKVr5R17KaaZ2kIfLrw==}
+
   sax@1.4.3:
     resolution: {integrity: sha512-yqYn1JhPczigF94DMS+shiDMjDowYO6y9+wB/4WgO0Y19jWYk0lQ4tuG5KI7kj4FTp1wxPj5IFfcrz/s1c3jjQ==}
 
+  sax@1.6.0:
+    resolution: {integrity: sha512-6R3J5M4AcbtLUdZmRv2SygeVaM7IhrLXu9BmnOGmmACak8fiUtOsYNWUS4uK7upbmHIBbLBeFeI//477BKLBzA==}
+    engines: {node: '>=11.0.0'}
+
   saxes@6.0.0:
     resolution: {integrity: sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==}
     engines: {node: '>=v12.22.7'}
@@ -6420,12 +8272,16 @@ packages:
   scheduler@0.23.2:
     resolution: {integrity: sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==}
 
+  scheduler@0.27.0:
+    resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
+
   section-matter@1.0.0:
     resolution: {integrity: sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==}
     engines: {node: '>=4'}
 
-  semver-compare@1.0.0:
-    resolution: {integrity: sha512-YM3/ITh2MJ5MtzaM429anh+x2jiLVjqILF4m4oyQB18W7Ggea7BfqdH/wGMK7dDiMghv/6WG7znWMwUDzJiXow==}
+  semver@5.7.2:
+    resolution: {integrity: sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==}
+    hasBin: true
 
   semver@6.3.1:
     resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
@@ -6441,13 +8297,18 @@ packages:
     engines: {node: '>=10'}
     hasBin: true
 
-  send@1.2.0:
-    resolution: {integrity: sha512-uaW0WwXKpL9blXE2o0bRhoL2EGXIrZxQ2ZQ4mgcfoBxdFmQold+qWsD2jLrfZ0trjKL6vOw0j//eAwcALFjKSw==}
+  semver@7.7.4:
+    resolution: {integrity: sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==}
+    engines: {node: '>=10'}
+    hasBin: true
+
+  send@1.2.1:
+    resolution: {integrity: sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==}
     engines: {node: '>= 18'}
 
-  serialize-error@7.0.1:
-    resolution: {integrity: sha512-8I8TjW5KMOKsZQTvoxjuSIa7foAwPWGOts+6o7sgjz41/qMD9VQHEDxi6PBvK2l0MXUmqZyNpUK+T2tQaaElvw==}
-    engines: {node: '>=10'}
+  serve-static@2.2.1:
+    resolution: {integrity: sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==}
+    engines: {node: '>= 18'}
 
   server-destroy@1.0.1:
     resolution: {integrity: sha512-rb+9B5YBIEzYcD6x2VKidaa+cqYBJQKnU4oe4E3ANwRRN56yk/ua1YCJT1n21NTS8w6CcOclAKNP3PhdCXKYtQ==}
@@ -6455,6 +8316,9 @@ packages:
   set-cookie-parser@2.7.1:
     resolution: {integrity: sha512-IOc8uWeOZgnb3ptbCURJWNjWUPcO3ZnTTdzsurqERrP6nPyv+paC55vJM0LpOlT2ne+Ix+9+CRG1MNLlyZ4GjQ==}
 
+  set-cookie-parser@3.1.0:
+    resolution: {integrity: sha512-kjnC1DXBHcxaOaOXBHBeRtltsDG2nUiUni+jP92M9gYdW12rsmx92UsfpH7o5tDRs7I1ZZPSQJQGv3UaRfCiuw==}
+
   set-function-length@1.2.2:
     resolution: {integrity: sha512-pgRc4hJ4/sNjWCSS9AmnS40x3bNMDTknHgL5UaMBTMyJnU90EgWh1Rz+MC9eFu4BuN/UwZjKQuY/1v3rM7HMfg==}
     engines: {node: '>= 0.4'}
@@ -6470,18 +8334,26 @@ packages:
   setprototypeof@1.2.0:
     resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==}
 
-  sharp@0.33.5:
-    resolution: {integrity: sha512-haPVm1EkS9pgvHrQ/F3Xy+hgcuMV0Wm9vfIBSiwZ05k+xgb0PkBQpGsAA/oWdDobNaZTH5ppvHtzCFbnSEwHVw==}
-    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
-
   sharp@0.34.4:
     resolution: {integrity: sha512-FUH39xp3SBPnxWvd5iib1X8XY7J0K0X7d93sie9CJg2PO8/7gmg89Nve6OjItK53/MlAushNNxteBYfM6DEuoA==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
 
+  sharp@0.34.5:
+    resolution: {integrity: sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+
+  shebang-command@1.2.0:
+    resolution: {integrity: sha512-EV3L1+UQWGor21OmnvojK36mhg+TyIKDh3iFBKBohr5xeXIhNBcx8oWdgkTEEQ+BEFFYdLRuqMfd5L84N1V5Vg==}
+    engines: {node: '>=0.10.0'}
+
   shebang-command@2.0.0:
     resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
     engines: {node: '>=8'}
 
+  shebang-regex@1.0.0:
+    resolution: {integrity: sha512-wpoSFAxys6b2a2wHZ1XpDSgD7N9iVjg29Ph9uV/uaP9Ex/KXlkTZTeddxDPSYQpgvzKLGJke2UU0AzoGCjNIvQ==}
+    engines: {node: '>=0.10.0'}
+
   shebang-regex@3.0.0:
     resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
     engines: {node: '>=8'}
@@ -6490,16 +8362,17 @@ packages:
     resolution: {integrity: sha512-ObmnIF4hXNg1BqhnHmgbDETF8dLPCggZWBjkQfhZpbszZnYur5DUljTcCHii5LC3J5E0yeO/1LIMyH+UvHQgyw==}
     engines: {node: '>= 0.4'}
 
-  shelljs@0.8.5:
-    resolution: {integrity: sha512-TiwcRcrkhHvbrZbnRcFYMLl30Dfov3HKqzp5tO5b4pt6G/SezKcYhmDg15zXVBswHmctSAQKznqNW2LO5tTDow==}
-    engines: {node: '>=4'}
+  shelljs@0.9.0:
+    resolution: {integrity: sha512-uwlECU3w0BCxLXEZW88et6rHF8Wt3xdVgoiVzDzVBmEqjzJG7t4rPmWF/9L40aCk3/bD5Z44/CoU8V6wIeUmxQ==}
+    engines: {node: '>=18'}
     hasBin: true
 
-  shiki@3.13.0:
-    resolution: {integrity: sha512-aZW4l8Og16CokuCLf8CF8kq+KK2yOygapU5m3+hoGw0Mdosc6fPitjM+ujYarppj5ZIKGyPDPP1vqmQhr+5/0g==}
+  shiki@3.21.0:
+    resolution: {integrity: sha512-N65B/3bqL/TI2crrXr+4UivctrAGEjmsib5rPMMPpFp1xAx/w03v8WZ9RDDFYteXoEgY7qZ4HGgl5KBIu1153w==}
 
-  shiki@3.15.0:
-    resolution: {integrity: sha512-kLdkY6iV3dYbtPwS9KXU7mjfmDm25f5m0IPNFnaXO7TBPcvbUOY72PYXSuSqDzwp+vlH/d7MXpHlKO/x+QoLXw==}
+  shiki@4.0.2:
+    resolution: {integrity: sha512-eAVKTMedR5ckPo4xne/PjYQYrU3qx78gtJZ+sHlXEg5IHhhoQhMfZVzetTYuaJS0L2Ef3AcCRzCHV8T0WI6nIQ==}
+    engines: {node: '>=20'}
 
   side-channel-list@1.0.0:
     resolution: {integrity: sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==}
@@ -6531,30 +8404,38 @@ packages:
     resolution: {integrity: sha512-LH7FpTAkeD+y5xQC4fzS+tFtaNlvt3Ib1zKzvhjv/Y+cioV4zIuw4IZr2yhRLu67CWL7FR9/6KXKnjRoZTvGGQ==}
     engines: {node: '>=12'}
 
-  simple-swizzle@0.2.4:
-    resolution: {integrity: sha512-nAu1WFPQSMNr2Zn9PGSZK9AGn4t/y97lEm+MXTtUDwfP0ksAIX4nO+6ruD9Jwut4C49SB1Ws+fbXsm/yScWOHw==}
-
-  simple-wcswidth@1.1.2:
-    resolution: {integrity: sha512-j7piyCjAeTDSjzTSQ7DokZtMNwNlEAyxqSZeCS+CXH7fJ4jx3FuJ/mTW3mE+6JLs4VJBbcll0Kjn+KXI5t21Iw==}
+  simple-git@3.36.0:
+    resolution: {integrity: sha512-cGQjLjK8bxJw4QuYT7gxHw3/IouVESbhahSsHrX97MzCL1gu2u7oy38W6L2ZIGECEfIBG4BabsWDPjBxJENv9Q==}
 
   sisteransi@1.0.5:
     resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
 
+  sitemap@9.0.1:
+    resolution: {integrity: sha512-S6hzjGJSG3d6if0YoF5kTyeRJvia6FSTBroE5fQ0bu1QNxyJqhhinfUsXi9fH3MgtXODWvwo2BDyQSnhPQ88uQ==}
+    engines: {node: '>=20.19.5', npm: '>=10.8.2'}
+    hasBin: true
+
   slash@3.0.0:
     resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==}
     engines: {node: '>=8'}
 
+  slash@5.1.0:
+    resolution: {integrity: sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg==}
+    engines: {node: '>=14.16'}
+
   slugify@1.6.6:
     resolution: {integrity: sha512-h+z7HKHYXj6wJU+AnS/+IH8Uh9fdcX1Lrhg1/VMdf9PwoBQXFcXiAdsy2tSK0P6gKwJLXp02r90ahUCqHk9rrw==}
     engines: {node: '>=8.0.0'}
 
-  smol-toml@1.4.2:
-    resolution: {integrity: sha512-rInDH6lCNiEyn3+hH8KVGFdbjc099j47+OSgbMrfDYX1CmXLfdKd7qi6IfcWj2wFxvSVkuI46M+wPGYfEOEj6g==}
+  smol-toml@1.6.0:
+    resolution: {integrity: sha512-4zemZi0HvTnYwLfrpk/CF9LOd9Lt87kAt50GnqhMpyF9U3poDAP2+iukq2bZsO/ufegbYehBkqINbsWxj4l4cw==}
     engines: {node: '>= 18'}
 
-  smol-toml@1.5.2:
-    resolution: {integrity: sha512-QlaZEqcAH3/RtNyet1IPIYPsEWAaYyXXv1Krsi+1L/QHppjX4Ifm8MQsBISz9vE8cHicIq3clogsheili5vhaQ==}
-    engines: {node: '>= 18'}
+  sonner@2.0.7:
+    resolution: {integrity: sha512-W6ZN4p58k8aDKA4XPcx2hpIQXBRAgyiWVkYhT7CvK6D3iAu7xjvVyhQHg2/iaKJZ1XVJ4r7XuwGL+WGEK37i9w==}
+    peerDependencies:
+      react: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
 
   source-map-js@1.2.1:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
@@ -6591,25 +8472,21 @@ packages:
   sprintf-js@1.0.3:
     resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==}
 
-  sprintf-js@1.1.3:
-    resolution: {integrity: sha512-Oo+0REFV59/rz3gfJNKQiBlwfHaSESl1pcGyABQsnnIfWOFt6JNj5gCog2U6MLZ//IGYD+nA8nI+mTShREReaA==}
+  sql.js@1.14.1:
+    resolution: {integrity: sha512-gcj8zBWU5cFsi9WUP+4bFNXAyF1iRpA3LLyS/DP5xlrNzGmPIizUeBggKa8DbDwdqaKwUcTEnChtd2grWo/x/A==}
 
   stackback@0.0.2:
     resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
 
-  static-eval@2.0.2:
-    resolution: {integrity: sha512-N/D219Hcr2bPjLxPiV+TQE++Tsmrady7TqAJugLy7Xk1EumfDWS/f5dtBbkRCGE7wKKXuYockQoj8Rm2/pVKyg==}
-
-  statuses@2.0.1:
-    resolution: {integrity: sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ==}
-    engines: {node: '>= 0.8'}
+  state-local@1.0.7:
+    resolution: {integrity: sha512-HTEHMNieakEnoe33shBYcZ7NX83ACUjCu8c40iOGEZsngj9zRnkqS9j1pqQPXwobB0ZcVTk27REb7COQ0UR59w==}
 
   statuses@2.0.2:
     resolution: {integrity: sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==}
     engines: {node: '>= 0.8'}
 
-  std-env@3.9.0:
-    resolution: {integrity: sha512-UGvjygr6F6tpH7o2qyqR6QYpwraIjKSdtzyBdyytFOHmPZY917kwdwLG0RbOjWOnKmnm3PeHjaoLLMie7kPLQw==}
+  std-env@3.10.0:
+    resolution: {integrity: sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==}
 
   stdin-discarder@0.2.2:
     resolution: {integrity: sha512-UhDfHmA92YAlNnCfhmq0VeNL5bDbiZGg7sZ2IvPsXubGkiNa9EC+tUTsjBRsYUAz87btI6/1wf4XoVvQ3uRnmQ==}
@@ -6619,6 +8496,17 @@ packages:
     resolution: {integrity: sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ==}
     engines: {node: '>= 0.4'}
 
+  stream-replace-string@2.0.0:
+    resolution: {integrity: sha512-TlnjJ1C0QrmxRNrON00JvaFFlNh5TTG00APw23j74ET7gkQpTASi6/L2fuiav8pzK715HXtUeClpBTw2NPSn6w==}
+
+  string-byte-length@3.0.1:
+    resolution: {integrity: sha512-yJ8vP0HMwZ54CcA8S8mKoXbkezpZHANFtmafFo8lGxZThCQcAwRHjdFabuSLgOzxj9OFJcmssmiAvmcOK4O2Hw==}
+    engines: {node: '>=18.18.0'}
+
+  string-byte-slice@3.0.1:
+    resolution: {integrity: sha512-GWv2K4lYyd2+AhmKH3BV+OVx62xDX+99rSLfKpaqFiQU7uOMaUY1tDjdrRD4gsrCr9lTyjMgjna7tZcCOw+Smg==}
+    engines: {node: '>=18.18.0'}
+
   string-width@4.2.3:
     resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
     engines: {node: '>=8'}
@@ -6643,12 +8531,15 @@ packages:
     resolution: {integrity: sha512-UXSH262CSZY1tfu3G3Secr6uGLCFVPMhIqHjlgCUtCCcgihYc/xKs9djMTMUOb2j1mVSeU8EU6NWc/iQKU6Gfg==}
     engines: {node: '>= 0.4'}
 
+  string_decoder@1.3.0:
+    resolution: {integrity: sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==}
+
   stringify-entities@4.0.4:
     resolution: {integrity: sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==}
 
-  stringify-object@5.0.0:
-    resolution: {integrity: sha512-zaJYxz2FtcMb4f+g60KsRNFOpVMUyuJgA51Zi5Z1DOTC3S59+OQiVOzE9GZt0x72uBGWKsQIuBKeF9iusmKFsg==}
-    engines: {node: '>=14.16'}
+  stringify-object@6.0.0:
+    resolution: {integrity: sha512-6f94vIED6vmJJfh3lyVsVWxCYSfI5uM+16ntED/Ql37XIyV6kj0mRAAiTeMMc/QLYIaizC3bUprQ8pQnDDrKfA==}
+    engines: {node: '>=20'}
 
   strip-ansi@6.0.1:
     resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==}
@@ -6666,15 +8557,22 @@ packages:
     resolution: {integrity: sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==}
     engines: {node: '>=4'}
 
+  strip-eof@1.0.0:
+    resolution: {integrity: sha512-7FCwGGmx8mD5xQd3RPUvnSpUXHM3BWuzjtpD4TXsfcZ9EL4azvVVUscFYwD9nx8Kh+uCBC00XBtAykoMHwTh8Q==}
+    engines: {node: '>=0.10.0'}
+
   strip-json-comments@2.0.1:
     resolution: {integrity: sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==}
     engines: {node: '>=0.10.0'}
 
+  strip-literal@3.1.0:
+    resolution: {integrity: sha512-8r3mkIM/2+PpjHoOtiAW8Rg3jJLHaV7xPwG+YRGrv6FP0wwk/toTpATxWYOW0BKdWwl82VT2tFYi5DlROa0Mxg==}
+
   strnum@1.1.2:
     resolution: {integrity: sha512-vrN+B7DBIoTTZjnPNewwhx6cBA/H+IS7rfW68n7XxC1y7uoiGQBxaKzqucGUgavX15dJgiGztLJ8vxuEzwqBdA==}
 
-  strnum@2.1.1:
-    resolution: {integrity: sha512-7ZvoFTiCnGxBtDqJ//Cu6fWtZtc7Y3x+QOirG15wztbdngGSkht27o2pyGWrVy0b4WAy3jbKmnoK6g5VlVNUUw==}
+  strnum@2.2.2:
+    resolution: {integrity: sha512-DnR90I+jtXNSTXWdwrEy9FakW7UX+qUZg28gj5fk2vxxl7uS/3bpI4fjFYVmdK9etptYBPNkpahuQnEwhwECqA==}
 
   stubborn-fs@1.2.5:
     resolution: {integrity: sha512-H2N9c26eXjzL/S/K+i/RHHcFanE74dptvvjM8iwzwbVcWY/zjBbgRqF3K0DY4+OD+uTTASTBvDoxPDaPN02D7g==}
@@ -6699,6 +8597,14 @@ packages:
   suf-log@2.5.3:
     resolution: {integrity: sha512-KvC8OPjzdNOe+xQ4XWJV2whQA0aM1kGVczMQ8+dStAO6KfEB140JEVQ9dE76ONZ0/Ylf67ni4tILPJB41U0eow==}
 
+  super-regex@1.1.0:
+    resolution: {integrity: sha512-WHkws2ZflZe41zj6AolvvmaTrWds/VuyeYr9iPVv/oQeaIoVxMKaushfFWpOGDT+GuBrM/sVqF8KUCYQlSSTdQ==}
+    engines: {node: '>=18'}
+
+  supports-color@5.5.0:
+    resolution: {integrity: sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==}
+    engines: {node: '>=4'}
+
   supports-color@7.2.0:
     resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
     engines: {node: '>=8'}
@@ -6711,48 +8617,71 @@ packages:
     resolution: {integrity: sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==}
     engines: {node: '>= 0.4'}
 
-  svgo@3.3.2:
-    resolution: {integrity: sha512-OoohrmuUlBs8B8o6MB2Aevn+pRIH9zDALSR+6hhqVfa6fRwG/Qw9VUMSMW9VNg2CFc/MTIfabtdOVl9ODIJjpw==}
-    engines: {node: '>=14.0.0'}
-    hasBin: true
+  svg-pan-zoom@3.6.2:
+    resolution: {integrity: sha512-JwnvRWfVKw/Xzfe6jriFyfey/lWJLq4bUh2jwoR5ChWQuQoOH8FEh1l/bEp46iHHKHEJWIyFJETbazraxNWECg==}
 
   svgo@4.0.0:
     resolution: {integrity: sha512-VvrHQ+9uniE+Mvx3+C9IEe/lWasXCU0nXMY2kZeLrHNICuRiC8uMPyM14UEaMOFA5mhyQqEkB02VoQ16n3DLaw==}
     engines: {node: '>=16'}
     hasBin: true
 
+  svgo@4.0.1:
+    resolution: {integrity: sha512-XDpWUOPC6FEibaLzjfe0ucaV0YrOjYotGJO1WpF0Zd+n6ZGEQUsSugaoLq9QkEZtAfQIxT42UChcssDVPP3+/w==}
+    engines: {node: '>=16'}
+    hasBin: true
+
   swr@2.3.6:
     resolution: {integrity: sha512-wfHRmHWk/isGNMwlLGlZX5Gzz/uTgo0o2IRuTMcf4CPuPFJZlq0rDaKUx+ozB5nBOReNV1kiOyzMfj+MBMikLw==}
     peerDependencies:
       react: ^16.11.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
+  swrv@1.2.0:
+    resolution: {integrity: sha512-lH/g4UcNyj+7lzK4eRGT4C68Q4EhQ6JtM9otPRIASfhhzfLWtbZPHcMuhuba7S9YVYuxkMUGImwMyGpfbkH07A==}
+    peerDependencies:
+      vue: '>=3.2.26 < 4'
+
   symbol-tree@3.2.4:
     resolution: {integrity: sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==}
 
   tabbable@6.2.0:
     resolution: {integrity: sha512-Cat63mxsVJlzYvN51JmVXIgNoUokrIaT2zLclCXjRd8boZ0004U4KCs/sToJ75C6sdlByWxpYnb5Boif1VSFew==}
 
-  tailwind-merge@2.6.0:
-    resolution: {integrity: sha512-P+Vu1qXfzediirmHOC3xKGAYeZtPcV9g76X+xg2FD4tYgR71ewMA35Y3sCz3zhiN/dwefRpJX0yBcgwi1fXNQA==}
+  tabbable@6.4.0:
+    resolution: {integrity: sha512-05PUHKSNE8ou2dwIxTngl4EzcnsCDZGJ/iCLtDflR/SHB/ny14rXc+qU5P4mG9JkusiV7EivzY9Mhm55AzAvCg==}
 
-  tailwindcss@3.4.18:
-    resolution: {integrity: sha512-6A2rnmW5xZMdw11LYjhcI5846rt9pbLSabY5XPxo+XWdxwZaFEn47Go4NzFiHu9sNNmr/kXivP1vStfvMaK1GQ==}
-    engines: {node: '>=14.0.0'}
-    hasBin: true
+  tagged-tag@1.0.0:
+    resolution: {integrity: sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==}
+    engines: {node: '>=20'}
 
-  tar@7.5.1:
-    resolution: {integrity: sha512-nlGpxf+hv0v7GkWBK2V9spgactGOp0qvfWRxUMjqHyzrt3SgwE48DIv/FhqPHJYLHpgW1opq3nERbz5Anq7n1g==}
-    engines: {node: '>=18'}
+  tailwind-merge@3.5.0:
+    resolution: {integrity: sha512-I8K9wewnVDkL1NTGoqWmVEIlUcB9gFriAEkXkfCjX5ib8ezGxtR3xD7iZIxrfArjEsH7F1CHD4RFUtxefdqV/A==}
+
+  tailwindcss@4.1.18:
+    resolution: {integrity: sha512-4+Z+0yiYyEtUVCScyfHCxOYP06L5Ne+JiHhY2IjR2KWMIWhJOYZKLSGZaP5HkZ8+bY0cxfzwDE5uOmzFXyIwxw==}
+
+  tailwindcss@4.3.1:
+    resolution: {integrity: sha512-hk+TB1m+K8CYNrP6rjQaq/Y+4Zylwpa87mLYBKCunwnnQ9p+fHb7kmSfGqyEJoxF/O6CDyABWVFEafNSYKll+Q==}
+
+  tapable@2.3.0:
+    resolution: {integrity: sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg==}
+    engines: {node: '>=6'}
+
+  tapable@2.3.3:
+    resolution: {integrity: sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A==}
+    engines: {node: '>=6'}
 
   term-size@2.2.1:
     resolution: {integrity: sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg==}
     engines: {node: '>=8'}
 
-  terser@5.39.0:
-    resolution: {integrity: sha512-LBAhFyLho16harJoWMg/nZsQYgTrg5jXOn2nCYjRUcZZEdE3qa2zb8QEDRUGVZBW4rlazf2fxkg8tztybTaqWw==}
+  terser@5.46.0:
+    resolution: {integrity: sha512-jTwoImyr/QbOWFFso3YoU3ik0jBBDJ6JTOQiy/J2YxVJdZCc+5u7skhNwiOR3FQIygFqVUPHl7qbbxtjW2K3Qg==}
     engines: {node: '>=10'}
     hasBin: true
 
+  thenby@1.3.4:
+    resolution: {integrity: sha512-89Gi5raiWA3QZ4b2ePcEwswC3me9JIg+ToSgtE0JWeCynLnLxNr/f9G+xfo9K+Oj4AFdom8YNJjibIARTJmapQ==}
+
   thenify-all@1.6.0:
     resolution: {integrity: sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==}
     engines: {node: '>=0.8'}
@@ -6764,40 +8693,61 @@ packages:
     resolution: {integrity: sha512-nt6AMGKW1p/70DF/hGBdJB57B8Tspmbp5gfJ8ilhLnt7kkr2ye7hzD6NVG8GGErk2HWF34igrL2CXmNIkzKqKw==}
     engines: {node: '>=18'}
 
+  time-span@5.1.0:
+    resolution: {integrity: sha512-75voc/9G4rDIJleOo4jPvN4/YC4GRZrY8yy1uU4lwrB3XEQbWve8zXoO5No4eFrGcTAMYyoY67p8jRQdtA1HbA==}
+    engines: {node: '>=12'}
+
   tiny-inflate@1.0.3:
     resolution: {integrity: sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw==}
 
+  tiny-invariant@1.3.3:
+    resolution: {integrity: sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg==}
+
   tinybench@2.9.0:
     resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
 
+  tinyclip@0.1.12:
+    resolution: {integrity: sha512-Ae3OVUqifDw0wBriIBS7yVaW44Dp6eSHQcyq4Igc7eN2TJH/2YsicswaW+J/OuMvhpDPOKEgpAZCjkb4hpoyeA==}
+    engines: {node: ^16.14.0 || >= 17.3.0}
+
   tinyexec@0.3.2:
     resolution: {integrity: sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==}
 
-  tinyexec@1.0.1:
-    resolution: {integrity: sha512-5uC6DDlmeqiOwCPmK9jMSdOuZTh8bU39Ys6yidB+UTt5hfZUPGAypSgFRiEp+jbi9qH40BLDvy85jIU88wKSqw==}
-
   tinyexec@1.0.2:
     resolution: {integrity: sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==}
     engines: {node: '>=18'}
 
+  tinyexec@1.1.2:
+    resolution: {integrity: sha512-dAqSqE/RabpBKI8+h26GfLq6Vb3JVXs30XYQjdMjaj/c2tS8IYYMbIzP599KtRj7c57/wYApb3QjgRgXmrCukA==}
+    engines: {node: '>=18'}
+
   tinyglobby@0.2.15:
     resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==}
     engines: {node: '>=12.0.0'}
 
+  tinyglobby@0.2.16:
+    resolution: {integrity: sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==}
+    engines: {node: '>=12.0.0'}
+
+  tinyglobby@0.2.17:
+    resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==}
+    engines: {node: '>=12.0.0'}
+
   tinypool@1.1.1:
     resolution: {integrity: sha512-Zba82s87IFq9A9XmjiX5uZA/ARWDrB03OHlq+Vw1fSdt0I+4/Kutwy8BP4Y/y/aORMo61FQ0vIb5j44vSo5Pkg==}
     engines: {node: ^18.0.0 || >=20.0.0}
 
-  tinyrainbow@1.2.0:
-    resolution: {integrity: sha512-weEDEq7Z5eTHPDh4xjX789+fHfF+P8boiFB+0vbWzpbnbsEr/GRaohi/uMKxg8RZMXnl1ItAi/IUHWMsjDV7kQ==}
+  tinyrainbow@2.0.0:
+    resolution: {integrity: sha512-op4nsTR47R6p0vMUUoYl/a+ljLFVtlfaXkLQmqfLR1qHma1h/ysYk4hEXZ880bf2CYgTskvTa/e196Vd5dDQXw==}
     engines: {node: '>=14.0.0'}
 
-  tinyspy@3.0.2:
-    resolution: {integrity: sha512-n1cw8k1k0x4pgA2+9XrOkFydTerNcJ1zWCO5Nn9scWHTD+5tp8dghT2x1uduQePZTZgd3Tupf+x9BxJjeJi77Q==}
+  tinyrainbow@3.0.3:
+    resolution: {integrity: sha512-PSkbLUoxOFRzJYjjxHJt9xro7D+iilgMX/C9lawzVuYiIdcihh9DXmVibBe8lmcFrRi/VzlPjBxbN7rH24q8/Q==}
     engines: {node: '>=14.0.0'}
 
-  tippy.js@6.3.7:
-    resolution: {integrity: sha512-E1d3oP2emgJ9dRQZdf3Kkn0qJgI6ZLpyS5z6ZkY1DF3kaQaBsGZsndEpHwx+eC+tYM41HaSNvNtLx8tU57FzTQ==}
+  tinyspy@4.0.4:
+    resolution: {integrity: sha512-azl+t0z7pw/z958Gy9svOTuzqIk6xq+NSheJzn5MMWtWTFywIacg2wUlzKFGtt3cthx0r2SxMK0yzJOR0IES7Q==}
+    engines: {node: '>=14.0.0'}
 
   tldts-core@7.0.16:
     resolution: {integrity: sha512-XHhPmHxphLi+LGbH0G/O7dmUH9V65OY20R7vH8gETHsp5AZCjBk9l8sqmRKLaGOxnETU7XNSDUPtewAy/K6jbA==}
@@ -6838,14 +8788,14 @@ packages:
   trough@2.2.0:
     resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==}
 
+  truncate-json@3.0.1:
+    resolution: {integrity: sha512-QVsbr1WhGLq2F0oDyYbqtOXcf3gcnL8C9H5EX8bBwAr8ZWvWGJzukpPrDrWgJMrNtgDbo74BIjI4kJu3q2xQWw==}
+    engines: {node: '>=18.18.0'}
+
   ts-dedent@2.2.0:
     resolution: {integrity: sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ==}
     engines: {node: '>=6.10'}
 
-  ts-deepmerge@7.0.3:
-    resolution: {integrity: sha512-Du/ZW2RfwV/D4cmA5rXafYjBQVuvu4qGiEEla4EmEHVHgRdx68Gftx7i66jn2bzHPwSVZY36Ae6OuDn9el4ZKA==}
-    engines: {node: '>=14.13.1'}
-
   ts-interface-checker@0.1.13:
     resolution: {integrity: sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==}
 
@@ -6884,13 +8834,44 @@ packages:
       typescript:
         optional: true
 
-  type-check@0.3.2:
-    resolution: {integrity: sha512-ZCmOJdvOWDBYJlzAoFkC+Q0+bUyEOS1ltgp1MGU03fqHG+dbi9tBFU2Rd9QKiDZFAYrhPh2JUf7rZRIuHRKtOg==}
-    engines: {node: '>= 0.8.0'}
+  tsx@4.21.0:
+    resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  turbo-darwin-64@2.8.4:
+    resolution: {integrity: sha512-xVkkgQMRyLdKodZ0NU0lkjcLDm7J9R0zDNY61H4K38F94ZuspjeM1zaVB9HNM/7m4/7QvAPrvO/vCBr2qWmKKg==}
+    cpu: [x64]
+    os: [darwin]
+
+  turbo-darwin-arm64@2.8.4:
+    resolution: {integrity: sha512-ycg5jmWIV9hFScbb7bOhBc0A8jiKfOdP5SAige6FUJDnSTkL29qpLIZxcE5/J/5NNys7hVifHocDCT08ELcJ5Q==}
+    cpu: [arm64]
+    os: [darwin]
 
-  type-fest@0.13.1:
-    resolution: {integrity: sha512-34R7HTnG0XIJcBSn5XhDd7nNFPRcXYRZrBB2O2jdKqYODldSzBAqzsWoZYYvduky73toYS/ESqxPvkDf/F0XMg==}
-    engines: {node: '>=10'}
+  turbo-linux-64@2.8.4:
+    resolution: {integrity: sha512-RzH0bTRRCobvBs6mLxporuF/L2MhPJlYZ/rwfzMfwWX/TnNYUcOROgNqHIH6MK4eBAjQ7YliBDrstHnFrO8C7A==}
+    cpu: [x64]
+    os: [linux]
+
+  turbo-linux-arm64@2.8.4:
+    resolution: {integrity: sha512-7HPdZjqZqq/3eg16oQMmEguZLrl4BGGVlXNpiy2mIhNjXheJjtSJ7rvgnpxMHXAFsaOPytSEkvgydB2qsYtM3g==}
+    cpu: [arm64]
+    os: [linux]
+
+  turbo-windows-64@2.8.4:
+    resolution: {integrity: sha512-cKo42yFeEixPz3rljG4rSHTjCLsNSxdS3HUDen5CpoyXu+eGxAeO50wUnGIzvkXRRLJTkG9rhIITNdqUzlrijA==}
+    cpu: [x64]
+    os: [win32]
+
+  turbo-windows-arm64@2.8.4:
+    resolution: {integrity: sha512-9g6P11SIIQSRlDqwd9QITR82hPeUjHenSYVsULrK7X57x+dmQIAkenZahSaMRDts9fRQygF5xBMoH0uZGwUvoA==}
+    cpu: [arm64]
+    os: [win32]
+
+  turbo@2.8.4:
+    resolution: {integrity: sha512-yf0DFQBoR0DCOg11pYRAX5/CvXwTUwJsIFTHTOpHbUy3GnEpGBfE5E4440nmn8g6FpXXpy8Im2UEpmmv0fz67g==}
+    hasBin: true
 
   type-fest@2.19.0:
     resolution: {integrity: sha512-RAH822pAdBgcNMAfWnCBU3CFZcfZ/i1eZjwFU/dsLKumyuuP3niueg2UAukXYF0E2AAoc82ZSSf9J0WQBinzHA==}
@@ -6900,6 +8881,14 @@ packages:
     resolution: {integrity: sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA==}
     engines: {node: '>=16'}
 
+  type-fest@5.5.0:
+    resolution: {integrity: sha512-PlBfpQwiUvGViBNX84Yxwjsdhd1TUlXr6zjX7eoirtCPIr08NAmxwa+fcYBTeRQxHo9YC9wwF3m9i700sHma8g==}
+    engines: {node: '>=20'}
+
+  type-is@2.0.1:
+    resolution: {integrity: sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==}
+    engines: {node: '>= 0.6'}
+
   typed-array-buffer@1.0.3:
     resolution: {integrity: sha512-nAYYwfY3qnzX30IkA6AQZjVbtK6duGontcQm1WSG1MD94YLqK0515GNApXkoxKOWMusVssAHWLh9SeaoefYFGw==}
     engines: {node: '>= 0.4'}
@@ -6927,8 +8916,8 @@ packages:
     engines: {node: '>=14.17'}
     hasBin: true
 
-  ufo@1.6.1:
-    resolution: {integrity: sha512-9a4/uxlTWJ4+a5i0ooc1rU7C7YOw3wT+UGqdeNNHWnOF9qcMBgLRS+4IYUqbczewFx4mLEig6gawh7X6mFlEkA==}
+  ufo@1.6.3:
+    resolution: {integrity: sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q==}
 
   ultrahtml@1.6.0:
     resolution: {integrity: sha512-R9fBn90VTJrqqLDwyMph+HGne8eqY1iPfYhPzZrvKpIfwkWZbcYlfpsb8B9dTvBfpy1/hqAD7Wi8EKfP9e8zdw==}
@@ -6940,42 +8929,28 @@ packages:
   uncrypto@0.1.3:
     resolution: {integrity: sha512-Ql87qFHB3s/De2ClA9e0gsnS6zXG27SkTiSJwjCc9MebbfapQfuPzumMIUMi38ezPZVNFcHI9sUIepeQfw8J8Q==}
 
-  underscore@1.12.1:
-    resolution: {integrity: sha512-hEQt0+ZLDVUMhebKxL4x1BTtDY7bavVofhZ9KZ4aI26X9SRaE+Y3m83XUL1UP2jn8ynjndwCCpEHdUG+9pP1Tw==}
-
-  undici-types@5.26.5:
-    resolution: {integrity: sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==}
-
-  undici-types@6.20.0:
-    resolution: {integrity: sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg==}
-
   undici-types@6.21.0:
     resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
 
-  unhead@1.11.20:
-    resolution: {integrity: sha512-3AsNQC0pjwlLqEYHLjtichGWankK8yqmocReITecmpB1H0aOabeESueyy+8X1gyJx4ftZVwo9hqQ4O3fPWffCA==}
+  undici-types@7.16.0:
+    resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
 
-  unicode-properties@1.4.1:
-    resolution: {integrity: sha512-CLjCCLQ6UuMxWnbIylkisbRj31qxHPAurvena/0iwSVbQ2G1VY5/HjV0IRabOEbDHlzZlRdCrD4NhB0JtU40Pg==}
+  unhead@2.1.13:
+    resolution: {integrity: sha512-jO9M1sI6b2h/1KpIu4Jeu+ptumLmUKboRRLxys5pYHFeT+lqTzfNHbYUX9bxVDhC1FBszAGuWcUVlmvIPsah8Q==}
 
-  unicode-trie@2.0.0:
-    resolution: {integrity: sha512-x7bc76x0bm4prf1VLg79uhAzKw8DVboClSN5VxJuQ+LKDOVEW9CdH+VY7SP+vX7xCYQqzzgQpFqz15zeLvAtZQ==}
-
-  unified@10.1.2:
-    resolution: {integrity: sha512-pUSWAi/RAnVy1Pif2kAoeWNBa3JVrx0MId2LASj8G+7AiHWoKZNTomq6LG326T68U7/e263X6fTdcXIy7XnF7Q==}
+  unicorn-magic@0.3.0:
+    resolution: {integrity: sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==}
+    engines: {node: '>=18'}
 
   unified@11.0.5:
     resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==}
 
-  unifont@0.6.0:
-    resolution: {integrity: sha512-5Fx50fFQMQL5aeHyWnZX9122sSLckcDvcfFiBf3QYeHa7a1MKJooUy52b67moi2MJYkrfo/TWY+CoLdr/w0tTA==}
+  unifont@0.7.4:
+    resolution: {integrity: sha512-oHeis4/xl42HUIeHuNZRGEvxj5AaIKR+bHPNegRq5LV1gdc3jundpONbjglKpihmJf+dswygdMJn3eftGIMemg==}
 
   unist-util-find-after@5.0.0:
     resolution: {integrity: sha512-amQa0Ep2m6hE2g72AugUItjbuM8X8cGQnFoHk0pGfrFeT9GZhzN5SW8nRsiGKK7Aif4CrACPENkA6P/Lw6fHGQ==}
 
-  unist-util-is@5.2.1:
-    resolution: {integrity: sha512-u9njyyfEh43npf1M+yGKDGVPbY/JWEemg5nH05ncKPfi+kBbKBJoTdsogMu33uhytuLlv9y0O7GH7fEdwLdLQw==}
-
   unist-util-is@6.0.0:
     resolution: {integrity: sha512-2qCTHimwdxLfz+YzdGfkqNlH0tLi9xjTnHddPmJwtIG9MGsdbutfTc4P+haPD7l7Cjxf/WZj+we5qfVPvvxfYw==}
 
@@ -6991,30 +8966,21 @@ packages:
   unist-util-remove-position@5.0.0:
     resolution: {integrity: sha512-Hp5Kh3wLxv0PHj9m2yZhhLt58KzPtEYKQQ4yxfYFEO7EvHwzyDYnduhHnY1mDxoqr7VUwVuHXk9RXKIiYS1N8Q==}
 
-  unist-util-stringify-position@3.0.3:
-    resolution: {integrity: sha512-k5GzIBZ/QatR8N5X2y+drfpWG8IDBzdnVj6OInRNWm1oXrzydiaAT2OQiA8DPRRZyAKb9b6I2a6PxYklZD0gKg==}
-
   unist-util-stringify-position@4.0.0:
     resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==}
 
   unist-util-visit-children@3.0.0:
     resolution: {integrity: sha512-RgmdTfSBOg04sdPcpTSD1jzoNBjt9a80/ZCzp5cI9n1qPzLZWF9YdvWGN2zmTumP1HWhXKdUWexjy/Wy/lJ7tA==}
 
-  unist-util-visit-parents@5.1.3:
-    resolution: {integrity: sha512-x6+y8g7wWMyQhL1iZfhIPhDAs7Xwbn9nRosDXl7qoPTSCy0yNxnKc+hWokFifWQIDGi154rdUqKvbCa4+1kLhg==}
-
-  unist-util-visit-parents@6.0.1:
-    resolution: {integrity: sha512-L/PqWzfTP9lzzEa6CKs0k2nARxTdZduw3zyh8d2NVBnsyvHjSX4TWse388YrrQKbvI8w20fGjGlhgT96WwKykw==}
-
   unist-util-visit-parents@6.0.2:
     resolution: {integrity: sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==}
 
-  unist-util-visit@4.1.2:
-    resolution: {integrity: sha512-MSd8OUGISqHdVvfY9TPhyK2VdUrPgxkUtWSuMHF6XAAFuL4LokseigBnZtPnJMu+FbynTkFNnFlyjxpVKujMRg==}
-
   unist-util-visit@5.0.0:
     resolution: {integrity: sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==}
 
+  unist-util-visit@5.1.0:
+    resolution: {integrity: sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==}
+
   universalify@0.1.2:
     resolution: {integrity: sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==}
     engines: {node: '>= 4.0.0'}
@@ -7023,8 +8989,78 @@ packages:
     resolution: {integrity: sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==}
     engines: {node: '>= 10.0.0'}
 
-  unstorage@1.17.3:
-    resolution: {integrity: sha512-i+JYyy0DoKmQ3FximTHbGadmIYb8JEpq7lxUjnjeB702bCPum0vzo6oy5Mfu0lpqISw7hCyMW2yj4nWC8bqJ3Q==}
+  unpipe@1.0.0:
+    resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
+    engines: {node: '>= 0.8'}
+
+  unplugin@2.1.0:
+    resolution: {integrity: sha512-us4j03/499KhbGP8BU7Hrzrgseo+KdfJYWcbcajCOqsAyb8Gk0Yn2kiUIcZISYCb1JFaZfIuG3b42HmguVOKCQ==}
+    engines: {node: '>=18.12.0'}
+
+  unstorage@1.17.4:
+    resolution: {integrity: sha512-fHK0yNg38tBiJKp/Vgsq4j0JEsCmgqH58HAn707S7zGkArbZsVr/CwINoi+nh3h98BRCwKvx1K3Xg9u3VV83sw==}
+    peerDependencies:
+      '@azure/app-configuration': ^1.8.0
+      '@azure/cosmos': ^4.2.0
+      '@azure/data-tables': ^13.3.0
+      '@azure/identity': ^4.6.0
+      '@azure/keyvault-secrets': ^4.9.0
+      '@azure/storage-blob': ^12.26.0
+      '@capacitor/preferences': ^6 || ^7 || ^8
+      '@deno/kv': '>=0.9.0'
+      '@netlify/blobs': ^6.5.0 || ^7.0.0 || ^8.1.0 || ^9.0.0 || ^10.0.0
+      '@planetscale/database': ^1.19.0
+      '@upstash/redis': ^1.34.3
+      '@vercel/blob': '>=0.27.1'
+      '@vercel/functions': ^2.2.12 || ^3.0.0
+      '@vercel/kv': ^1 || ^2 || ^3
+      aws4fetch: ^1.0.20
+      db0: '>=0.2.1'
+      idb-keyval: ^6.2.1
+      ioredis: ^5.4.2
+      uploadthing: ^7.4.4
+    peerDependenciesMeta:
+      '@azure/app-configuration':
+        optional: true
+      '@azure/cosmos':
+        optional: true
+      '@azure/data-tables':
+        optional: true
+      '@azure/identity':
+        optional: true
+      '@azure/keyvault-secrets':
+        optional: true
+      '@azure/storage-blob':
+        optional: true
+      '@capacitor/preferences':
+        optional: true
+      '@deno/kv':
+        optional: true
+      '@netlify/blobs':
+        optional: true
+      '@planetscale/database':
+        optional: true
+      '@upstash/redis':
+        optional: true
+      '@vercel/blob':
+        optional: true
+      '@vercel/functions':
+        optional: true
+      '@vercel/kv':
+        optional: true
+      aws4fetch:
+        optional: true
+      db0:
+        optional: true
+      idb-keyval:
+        optional: true
+      ioredis:
+        optional: true
+      uploadthing:
+        optional: true
+
+  unstorage@1.17.5:
+    resolution: {integrity: sha512-0i3iqvRfx29hkNntHyQvJTpf5W9dQ9ZadSoRU8+xVlhVtT7jAX57fazYO9EHvcRCfBCyi5YRya7XCDOsbTgkPg==}
     peerDependencies:
       '@azure/app-configuration': ^1.8.0
       '@azure/cosmos': ^4.2.0
@@ -7032,14 +9068,14 @@ packages:
       '@azure/identity': ^4.6.0
       '@azure/keyvault-secrets': ^4.9.0
       '@azure/storage-blob': ^12.26.0
-      '@capacitor/preferences': ^6.0.3 || ^7.0.0
+      '@capacitor/preferences': ^6 || ^7 || ^8
       '@deno/kv': '>=0.9.0'
       '@netlify/blobs': ^6.5.0 || ^7.0.0 || ^8.1.0 || ^9.0.0 || ^10.0.0
       '@planetscale/database': ^1.19.0
       '@upstash/redis': ^1.34.3
       '@vercel/blob': '>=0.27.1'
       '@vercel/functions': ^2.2.12 || ^3.0.0
-      '@vercel/kv': ^1.0.1
+      '@vercel/kv': ^1 || ^2 || ^3
       aws4fetch: ^1.0.20
       db0: '>=0.2.1'
       idb-keyval: ^6.2.1
@@ -7091,6 +9127,9 @@ packages:
     peerDependencies:
       browserslist: '>= 4.21.0'
 
+  update-check@1.5.4:
+    resolution: {integrity: sha512-5YHsflzHP4t1G+8WGPlvKbJEbAJGCgw+Em+dGR1KmBUbr1J36SJBqlHLjR7oob7sco5hWHGQVcr9B2poIVDDTQ==}
+
   update-notifier@7.3.1:
     resolution: {integrity: sha512-+dwUY4L35XFYEzE+OAL3sarJdUioVovq+8f7lcIJ7wnmnYQV5UD1Y/lcwaMSyaQ6Bj3JMj1XSTjZbNLHn/19yA==}
     engines: {node: '>=18'}
@@ -7098,6 +9137,10 @@ packages:
   urijs@1.19.11:
     resolution: {integrity: sha512-HXgFDgDommxn5/bIv0cnQZsPhHDA90NPHD6+c/v21U5+Sx5hoP8+dP9IZXBU1gIfvdRfhG8cel9QNPeionfcCQ==}
 
+  url-extras@0.1.0:
+    resolution: {integrity: sha512-8tzwTeXFPuX/5PHuCDQE5Dd9Ts4rwoq2t9aIT+HS4iAVpmj5l4Ao7Q+BuuFjvWRqrLswBhQDk8O96ZicgCqQqw==}
+    engines: {node: '>=20'}
+
   use-callback-ref@1.3.3:
     resolution: {integrity: sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==}
     engines: {node: '>=10'}
@@ -7138,39 +9181,32 @@ packages:
 
   uuid@10.0.0:
     resolution: {integrity: sha512-8XkAphELsDnEGrDxUOHB3RGvXz6TeuYSGEZBOjtTtPm2lwhGBjLgOzLHB63IUWfBpNucQjND6d3AOudO+H3RWQ==}
+    deprecated: uuid@10 and below is no longer supported.  For ESM codebases, update to uuid@latest.  For CommonJS codebases, use uuid@11 (but be aware this version will likely be deprecated in 2028).
     hasBin: true
 
   uuid@11.1.0:
     resolution: {integrity: sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==}
     hasBin: true
 
-  uuid@9.0.1:
-    resolution: {integrity: sha512-b+1eJOlsR9K8HJpow9Ok3fiWOWSIcIzXodvv0rQjVoOVNpWMpxf1wZNpt4y9h10odCNrqnYp1OBzRktckBe3sA==}
-    hasBin: true
+  validate-npm-package-name@3.0.0:
+    resolution: {integrity: sha512-M6w37eVCMMouJ9V/sdPGnC5H4uDr73/+xdq0FBLO3TFFX1+7wiUY6Es328NN+y43tmY+doUdN9g9J21vqB7iLw==}
 
-  uvu@0.5.6:
-    resolution: {integrity: sha512-+g8ENReyr8YsOc6fv/NVJs2vFdHBnBNdfE49rshrTzDWOlUx4Gq7KOS2GD8eqhy2j+Ejq29+SbKH8yjkAqXqoA==}
-    engines: {node: '>=8'}
-    hasBin: true
+  vary@1.1.2:
+    resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
+    engines: {node: '>= 0.8'}
 
   vfile-location@5.0.3:
     resolution: {integrity: sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==}
 
-  vfile-message@3.1.4:
-    resolution: {integrity: sha512-fa0Z6P8HUrQN4BZaX05SIVXic+7kE3b05PWAtPuYP9QLHsLKYR7/AlLW3NtOrpXRLeawpDLMsVkmk5DG0NXgWw==}
-
   vfile-message@4.0.3:
     resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==}
 
-  vfile@5.3.7:
-    resolution: {integrity: sha512-r7qlzkgErKjobAmyNIkkSpizsFPYiUPuJb5pNW1RB4JcYVZhs4lIbVqk8XPk033CV/1z8ss5pkax8SuhGpcG8g==}
-
   vfile@6.0.3:
     resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==}
 
-  vite-node@2.1.9:
-    resolution: {integrity: sha512-AM9aQ/IPrW/6ENLQg3AGY4K1N2TGZdR5e4gu/MmmR2xR3Ll1+dib+nook92g4TV3PXVyeyxdWwtaCAiUL0hMxA==}
-    engines: {node: ^18.0.0 || >=20.0.0}
+  vite-node@3.2.4:
+    resolution: {integrity: sha512-EbKSKh+bh1E1IFxeO0pg1n4dvoOTt0UDiXMd/qn++r98+jPO1xtJilvXldeuQ8giIB5IkpjCgMleHMNEsGH6pg==}
+    engines: {node: ^18.0.0 || ^20.0.0 || >=22.0.0}
     hasBin: true
 
   vite-tsconfig-paths@4.3.2:
@@ -7181,22 +9217,107 @@ packages:
       vite:
         optional: true
 
-  vite@5.4.21:
-    resolution: {integrity: sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==}
-    engines: {node: ^18.0.0 || >=20.0.0}
+  vite@6.4.1:
+    resolution: {integrity: sha512-+Oxm7q9hDoLMyJOYfUYBuHQo+dkAloi33apOPP56pzj+vsdJDzr+j1NISE5pyaAuKL4A3UD34qd0lx5+kfKp2g==}
+    engines: {node: ^18.0.0 || ^20.0.0 || >=22.0.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^18.0.0 || ^20.0.0 || >=22.0.0
+      jiti: '>=1.21.0'
+      less: '*'
+      lightningcss: ^1.21.0
+      sass: '*'
+      sass-embedded: '*'
+      stylus: '*'
+      sugarss: '*'
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      lightningcss:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+  vite@7.1.9:
+    resolution: {integrity: sha512-4nVGliEpxmhCL8DslSAUdxlB6+SMrhB0a1v5ijlh1xB1nEPuy1mxaHxysVucLHuWryAxLWg6a5ei+U4TLn/rFg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^20.19.0 || >=22.12.0
+      jiti: '>=1.21.0'
+      less: ^4.0.0
+      lightningcss: ^1.21.0
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      lightningcss:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+  vite@7.3.1:
+    resolution: {integrity: sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
     hasBin: true
     peerDependencies:
-      '@types/node': ^18.0.0 || >=20.0.0
-      less: '*'
+      '@types/node': ^20.19.0 || >=22.12.0
+      jiti: '>=1.21.0'
+      less: ^4.0.0
       lightningcss: ^1.21.0
-      sass: '*'
-      sass-embedded: '*'
-      stylus: '*'
-      sugarss: '*'
-      terser: ^5.4.0
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
     peerDependenciesMeta:
       '@types/node':
         optional: true
+      jiti:
+        optional: true
       less:
         optional: true
       lightningcss:
@@ -7211,20 +9332,24 @@ packages:
         optional: true
       terser:
         optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
 
-  vite@6.4.1:
-    resolution: {integrity: sha512-+Oxm7q9hDoLMyJOYfUYBuHQo+dkAloi33apOPP56pzj+vsdJDzr+j1NISE5pyaAuKL4A3UD34qd0lx5+kfKp2g==}
-    engines: {node: ^18.0.0 || ^20.0.0 || >=22.0.0}
+  vite@7.3.2:
+    resolution: {integrity: sha512-Bby3NOsna2jsjfLVOHKes8sGwgl4TT0E6vvpYgnAYDIF/tie7MRaFthmKuHx1NSXjiTueXH3do80FMQgvEktRg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
     hasBin: true
     peerDependencies:
-      '@types/node': ^18.0.0 || ^20.0.0 || >=22.0.0
+      '@types/node': ^20.19.0 || >=22.12.0
       jiti: '>=1.21.0'
-      less: '*'
+      less: ^4.0.0
       lightningcss: ^1.21.0
-      sass: '*'
-      sass-embedded: '*'
-      stylus: '*'
-      sugarss: '*'
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
       terser: ^5.16.0
       tsx: ^4.8.1
       yaml: ^2.4.2
@@ -7252,15 +9377,16 @@ packages:
       yaml:
         optional: true
 
-  vite@7.1.9:
-    resolution: {integrity: sha512-4nVGliEpxmhCL8DslSAUdxlB6+SMrhB0a1v5ijlh1xB1nEPuy1mxaHxysVucLHuWryAxLWg6a5ei+U4TLn/rFg==}
+  vite@8.1.0:
+    resolution: {integrity: sha512-BuJcQK/56NQTWDGn4ABea3q4SSBdNPWwNZKTkkUpcMPnLoquSYH8llRtSUIgoL1KSCpHt5eghLShn50mH36y7Q==}
     engines: {node: ^20.19.0 || >=22.12.0}
     hasBin: true
     peerDependencies:
       '@types/node': ^20.19.0 || >=22.12.0
+      '@vitejs/devtools': ^0.3.0
+      esbuild: ^0.27.0 || ^0.28.0
       jiti: '>=1.21.0'
       less: ^4.0.0
-      lightningcss: ^1.21.0
       sass: ^1.70.0
       sass-embedded: ^1.70.0
       stylus: '>=0.54.8'
@@ -7271,12 +9397,14 @@ packages:
     peerDependenciesMeta:
       '@types/node':
         optional: true
+      '@vitejs/devtools':
+        optional: true
+      esbuild:
+        optional: true
       jiti:
         optional: true
       less:
         optional: true
-      lightningcss:
-        optional: true
       sass:
         optional: true
       sass-embedded:
@@ -7292,28 +9420,31 @@ packages:
       yaml:
         optional: true
 
-  vitefu@1.1.1:
-    resolution: {integrity: sha512-B/Fegf3i8zh0yFbpzZ21amWzHmuNlLlmJT6n7bu5e+pCHUKQIfXSYokrqOBGEMMe9UG2sostKQF9mml/vYaWJQ==}
+  vitefu@1.1.2:
+    resolution: {integrity: sha512-zpKATdUbzbsycPFBN71nS2uzBUQiVnFoOrr2rvqv34S1lcAgMKKkjWleLGeiJlZ8lwCXvtWaRn7R3ZC16SYRuw==}
     peerDependencies:
-      vite: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0-beta.0
+      vite: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-beta.0
     peerDependenciesMeta:
       vite:
         optional: true
 
-  vitest@2.1.9:
-    resolution: {integrity: sha512-MSmPM9REYqDGBI8439mA4mWhV5sKmDlBKWIYbA3lRb2PTHACE0mgKwA8yQ2xq9vxDTuk4iPrECBAEW2aoFXY0Q==}
-    engines: {node: ^18.0.0 || >=20.0.0}
+  vitest@3.2.4:
+    resolution: {integrity: sha512-LUCP5ev3GURDysTWiP47wRRUpLKMOfPh+yKTx3kVIEiu5KOMeqzpnYNsKyOoVrULivR8tLcks4+lga33Whn90A==}
+    engines: {node: ^18.0.0 || ^20.0.0 || >=22.0.0}
     hasBin: true
     peerDependencies:
       '@edge-runtime/vm': '*'
-      '@types/node': ^18.0.0 || >=20.0.0
-      '@vitest/browser': 2.1.9
-      '@vitest/ui': 2.1.9
+      '@types/debug': ^4.1.12
+      '@types/node': ^18.0.0 || ^20.0.0 || >=22.0.0
+      '@vitest/browser': 3.2.4
+      '@vitest/ui': 3.2.4
       happy-dom: '*'
       jsdom: '*'
     peerDependenciesMeta:
       '@edge-runtime/vm':
         optional: true
+      '@types/debug':
+        optional: true
       '@types/node':
         optional: true
       '@vitest/browser':
@@ -7325,32 +9456,101 @@ packages:
       jsdom:
         optional: true
 
-  volar-service-css@0.0.62:
-    resolution: {integrity: sha512-JwNyKsH3F8PuzZYuqPf+2e+4CTU8YoyUHEHVnoXNlrLe7wy9U3biomZ56llN69Ris7TTy/+DEX41yVxQpM4qvg==}
+  vitest@4.0.18:
+    resolution: {integrity: sha512-hOQuK7h0FGKgBAas7v0mSAsnvrIgAvWmRFjmzpJ7SwFHH3g1k2u37JtYwOwmEKhK6ZO3v9ggDBBm0La1LCK4uQ==}
+    engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0}
+    hasBin: true
+    peerDependencies:
+      '@edge-runtime/vm': '*'
+      '@opentelemetry/api': ^1.9.0
+      '@types/node': ^20.0.0 || ^22.0.0 || >=24.0.0
+      '@vitest/browser-playwright': 4.0.18
+      '@vitest/browser-preview': 4.0.18
+      '@vitest/browser-webdriverio': 4.0.18
+      '@vitest/ui': 4.0.18
+      happy-dom: '*'
+      jsdom: '*'
+    peerDependenciesMeta:
+      '@edge-runtime/vm':
+        optional: true
+      '@opentelemetry/api':
+        optional: true
+      '@types/node':
+        optional: true
+      '@vitest/browser-playwright':
+        optional: true
+      '@vitest/browser-preview':
+        optional: true
+      '@vitest/browser-webdriverio':
+        optional: true
+      '@vitest/ui':
+        optional: true
+      happy-dom:
+        optional: true
+      jsdom:
+        optional: true
+
+  volar-service-css@0.0.67:
+    resolution: {integrity: sha512-zV7C6enn9T9tuvQ6iSUyYEs34iPXR69Pf9YYWpbFYPWzVs22w96BtE8p04XYXbmjU6unt5oFt+iLL77bMB5fhA==}
+    peerDependencies:
+      '@volar/language-service': ~2.4.0
+    peerDependenciesMeta:
+      '@volar/language-service':
+        optional: true
+
+  volar-service-css@0.0.70:
+    resolution: {integrity: sha512-K1qyOvBpE3rzdAv3e4/6Rv5yizrYPy5R/ne3IWCAzLBuMO4qBMV3kSqWzj6KUVe6S0AnN6wxF7cRkiaKfYMYJw==}
+    peerDependencies:
+      '@volar/language-service': ~2.4.0
+    peerDependenciesMeta:
+      '@volar/language-service':
+        optional: true
+
+  volar-service-emmet@0.0.67:
+    resolution: {integrity: sha512-UDBL5x7KptmuJZNCCXMlCndMhFult/tj+9jXq3FH1ZGS1E4M/1U5hC06pg1c6e4kn+vnR6bqmvX0vIhL4f98+A==}
     peerDependencies:
       '@volar/language-service': ~2.4.0
     peerDependenciesMeta:
       '@volar/language-service':
         optional: true
 
-  volar-service-emmet@0.0.62:
-    resolution: {integrity: sha512-U4dxWDBWz7Pi4plpbXf4J4Z/ss6kBO3TYrACxWNsE29abu75QzVS0paxDDhI6bhqpbDFXlpsDhZ9aXVFpnfGRQ==}
+  volar-service-emmet@0.0.70:
+    resolution: {integrity: sha512-xi5bC4m/VyE3zy/n2CXspKeDZs3qA41tHLTw275/7dNWM/RqE2z3BnDICQybHIVp/6G1iOQj5c1qXMgQC08TNg==}
     peerDependencies:
       '@volar/language-service': ~2.4.0
     peerDependenciesMeta:
       '@volar/language-service':
         optional: true
 
-  volar-service-html@0.0.62:
-    resolution: {integrity: sha512-Zw01aJsZRh4GTGUjveyfEzEqpULQUdQH79KNEiKVYHZyuGtdBRYCHlrus1sueSNMxwwkuF5WnOHfvBzafs8yyQ==}
+  volar-service-html@0.0.67:
+    resolution: {integrity: sha512-ljREMF79JbcjNvObiv69HK2HCl5UT7WTD10zi6CRFUHMbPfiF2UZ42HGLsEGSzaHGZz6H4IFjSS/qfENRLUviQ==}
     peerDependencies:
       '@volar/language-service': ~2.4.0
     peerDependenciesMeta:
       '@volar/language-service':
         optional: true
 
-  volar-service-prettier@0.0.62:
-    resolution: {integrity: sha512-h2yk1RqRTE+vkYZaI9KYuwpDfOQRrTEMvoHol0yW4GFKc75wWQRrb5n/5abDrzMPrkQbSip8JH2AXbvrRtYh4w==}
+  volar-service-html@0.0.70:
+    resolution: {integrity: sha512-eR6vCgMdmYAo4n+gcT7DSyBQbwB8S3HZZvSagTf0sxNaD4WppMCFfpqWnkrlGStPKMZvMiejRRVmqsX9dYcTvQ==}
+    peerDependencies:
+      '@volar/language-service': ~2.4.0
+    peerDependenciesMeta:
+      '@volar/language-service':
+        optional: true
+
+  volar-service-prettier@0.0.67:
+    resolution: {integrity: sha512-B4KnPJPNWFTkEDa6Fn08i5PpO6T1CecmLLTFZoXz2eI4Fxwba/3nDaaVSsEP7e/vEe+U5YqV9fBzayJT71G5xg==}
+    peerDependencies:
+      '@volar/language-service': ~2.4.0
+      prettier: ^2.2 || ^3.0
+    peerDependenciesMeta:
+      '@volar/language-service':
+        optional: true
+      prettier:
+        optional: true
+
+  volar-service-prettier@0.0.70:
+    resolution: {integrity: sha512-Z6BCFSpGVCd8BPAsZ785Kce1BGlWd5ODqmqZGVuB14MJvrR4+CYz6cDy4F+igmE1gMifqfvMhdgT8Aud4M5ngg==}
     peerDependencies:
       '@volar/language-service': ~2.4.0
       prettier: ^2.2 || ^3.0
@@ -7360,24 +9560,48 @@ packages:
       prettier:
         optional: true
 
-  volar-service-typescript-twoslash-queries@0.0.62:
-    resolution: {integrity: sha512-KxFt4zydyJYYI0kFAcWPTh4u0Ha36TASPZkAnNY784GtgajerUqM80nX/W1d0wVhmcOFfAxkVsf/Ed+tiYU7ng==}
+  volar-service-typescript-twoslash-queries@0.0.67:
+    resolution: {integrity: sha512-LD2R7WivDYp1SPgZrxx/0222xVTitDjm36oKo5+bfYG5kEgnw+BOPVHdwmvpJKg/RfssfxDI1ouwD4XkEDEfbA==}
+    peerDependencies:
+      '@volar/language-service': ~2.4.0
+    peerDependenciesMeta:
+      '@volar/language-service':
+        optional: true
+
+  volar-service-typescript-twoslash-queries@0.0.70:
+    resolution: {integrity: sha512-IdD13Z9N2Bu8EM6CM0fDV1E69olEYGHDU25X51YXmq8Y0CmJ2LNj6gOiBJgpS5JGUqFzECVhMNBW7R0sPdRTMQ==}
+    peerDependencies:
+      '@volar/language-service': ~2.4.0
+    peerDependenciesMeta:
+      '@volar/language-service':
+        optional: true
+
+  volar-service-typescript@0.0.67:
+    resolution: {integrity: sha512-rfQBy36Rm1PU9vLWHk8BYJ4r2j/CI024vocJcH4Nb6K2RTc2Irmw6UOVY5DdGiPRV5r+e10wLMK5njj/EcL8sA==}
+    peerDependencies:
+      '@volar/language-service': ~2.4.0
+    peerDependenciesMeta:
+      '@volar/language-service':
+        optional: true
+
+  volar-service-typescript@0.0.70:
+    resolution: {integrity: sha512-l46Bx4cokkUedTd74ojO5H/zqHZJ8SUuyZ0IB8JN4jfRqUM3bQFBHoOwlZCyZmOeO0A3RQNkMnFclxO4c++gsg==}
     peerDependencies:
       '@volar/language-service': ~2.4.0
     peerDependenciesMeta:
       '@volar/language-service':
         optional: true
 
-  volar-service-typescript@0.0.62:
-    resolution: {integrity: sha512-p7MPi71q7KOsH0eAbZwPBiKPp9B2+qrdHAd6VY5oTo9BUXatsOAdakTm9Yf0DUj6uWBAaOT01BSeVOPwucMV1g==}
+  volar-service-yaml@0.0.67:
+    resolution: {integrity: sha512-jkdP/RF6wPIXEE3Ktnd81oJPn7aAvnVSiaqQHThC2Hrvo6xd9pEcqtbBUI+YfqVgvcMtXAkbtNO61K2GPhAiuA==}
     peerDependencies:
       '@volar/language-service': ~2.4.0
     peerDependenciesMeta:
       '@volar/language-service':
         optional: true
 
-  volar-service-yaml@0.0.62:
-    resolution: {integrity: sha512-k7gvv7sk3wa+nGll3MaSKyjwQsJjIGCHFjVkl3wjaSP2nouKyn9aokGmqjrl39mi88Oy49giog2GkZH526wjig==}
+  volar-service-yaml@0.0.70:
+    resolution: {integrity: sha512-0c8bXDBeoATF9F6iPIlOuYTuZAC4c+yi0siQo920u7eiBJk8oQmUmg9cDUbR4+Gl++bvGP4plj3fErbJuPqdcQ==}
     peerDependencies:
       '@volar/language-service': ~2.4.0
     peerDependenciesMeta:
@@ -7390,20 +9614,20 @@ packages:
   vscode-html-languageservice@5.5.2:
     resolution: {integrity: sha512-QpaUhCjvb7U/qThOzo4V6grwsRE62Jk/vf8BRJZoABlMw3oplLB5uovrvcrLO9vYhkeMiSjyqLnCxbfHzzZqmw==}
 
+  vscode-html-languageservice@5.6.2:
+    resolution: {integrity: sha512-ulCrSnFnfQ16YzvwnYUgEbUEl/ZG7u2eV27YhvLObSHKkb8fw1Z9cgsnUwjTEeDIdJDoTDTDpxuhQwoenoLNMg==}
+
   vscode-json-languageservice@4.1.8:
     resolution: {integrity: sha512-0vSpg6Xd9hfV+eZAaYN63xVVMOTmJ4GgHxXnkLCh+9RsQBkWKIghzLhW2B9ebfG+LQQg8uLtsQ2aUKjTgE+QOg==}
     engines: {npm: '>=7.0.0'}
 
-  vscode-jsonrpc@6.0.0:
-    resolution: {integrity: sha512-wnJA4BnEjOSyFMvjZdpiOwhSq9uDoK8e/kpRJDTaMYzwlkrhG1fwDIZI94CLsLzlCK5cIbMMtFlJlfR57Lavmg==}
-    engines: {node: '>=8.0.0 || >=10.0.0'}
-
   vscode-jsonrpc@8.2.0:
     resolution: {integrity: sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==}
     engines: {node: '>=14.0.0'}
 
-  vscode-languageserver-protocol@3.16.0:
-    resolution: {integrity: sha512-sdeUoAawceQdgIfTI+sdcwkiK2KU+2cbEYA0agzM2uqaUy2UpnnGHtWTHVEtS0ES4zHU0eMFRGN+oQgDxlD66A==}
+  vscode-languageclient@9.0.1:
+    resolution: {integrity: sha512-JZiimVdvimEuHh5olxhxkht09m3JzUGwggb5eRUkzzJhZ2KjCN0nh55VfiED9oez9DyF8/fz1g1iBV3h+0Z2EA==}
+    engines: {vscode: ^1.82.0}
 
   vscode-languageserver-protocol@3.17.5:
     resolution: {integrity: sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==}
@@ -7411,16 +9635,9 @@ packages:
   vscode-languageserver-textdocument@1.0.12:
     resolution: {integrity: sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==}
 
-  vscode-languageserver-types@3.16.0:
-    resolution: {integrity: sha512-k8luDIWJWyenLc5ToFQQMaSrqCHiLwyKPHKPQZ5zz21vM+vIVUSvsRpcbiECH4WR88K2XZqc4ScRcZ7nk/jbeA==}
-
   vscode-languageserver-types@3.17.5:
     resolution: {integrity: sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==}
 
-  vscode-languageserver@7.0.0:
-    resolution: {integrity: sha512-60HTx5ID+fLRcgdHfmz0LDZAXYEV68fzwG0JWwEPBode9NuMYTIxuYXPg4ngO8i8+Ou0lM7y6GzaYWbiDL0drw==}
-    hasBin: true
-
   vscode-languageserver@9.0.1:
     resolution: {integrity: sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==}
     hasBin: true
@@ -7434,6 +9651,9 @@ packages:
   vscode-uri@3.1.0:
     resolution: {integrity: sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==}
 
+  vue-component-type-helpers@3.2.6:
+    resolution: {integrity: sha512-O02tnvIfOQVmnvoWwuSydwRoHjZVt8UEBR+2p4rT35p8GAy5VTlWP8o5qXfJR/GWCN0nVZoYWsVUvx2jwgdBmQ==}
+
   vue-demi@0.14.10:
     resolution: {integrity: sha512-nMZBOwuzabUO0nLgIcc6rycZEebF6eeUfaiQx9+WSk8e29IbLvPU9feI6tqW4kTo3hvoYAJkMh8n8D0fuISphg==}
     engines: {node: '>=12'}
@@ -7445,16 +9665,11 @@ packages:
       '@vue/composition-api':
         optional: true
 
-  vue-router@4.5.1:
-    resolution: {integrity: sha512-ogAF3P97NPm8fJsE4by9dwSYtDwXIY1nFY9T6DyQnGHd1E2Da94w9JIolpe42LJGIl0DwOHBi8TcRPlPGwbTtw==}
-    peerDependencies:
-      vue: ^3.2.0
-
   vue-sonner@1.3.2:
     resolution: {integrity: sha512-UbZ48E9VIya3ToiRHAZUbodKute/z/M1iT8/3fU8zEbwBRE11AKuHikssv18LMk2gTTr6eMQT4qf6JoLHWuj/A==}
 
-  vue@3.5.22:
-    resolution: {integrity: sha512-toaZjQ3a/G/mYaLSbV+QsQhIdMo9x5rrqIpYRObsJ6T/J+RyCSFwN2LHNVH9v8uIcljDNa3QzPVdv3Y6b9hAJQ==}
+  vue@3.5.32:
+    resolution: {integrity: sha512-vM4z4Q9tTafVfMAK7IVzmxg34rSzTFMyIe0UUEijUCkn9+23lj0WRfA83dg7eQZIUlgOSGrkViIaCfqSAUXsMw==}
     peerDependencies:
       typescript: '*'
     peerDependenciesMeta:
@@ -7468,12 +9683,14 @@ packages:
     resolution: {integrity: sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==}
     engines: {node: '>=18'}
 
+  wcwidth@1.0.1:
+    resolution: {integrity: sha512-XHPEwS0q6TaxcvG85+8EYkbiCux2XtWG2mkc47Ng2A77BQu9+DqIOJldST4HgPkuea7dvKSj5VgX3P1d4rW8Tg==}
+
   web-namespaces@2.0.1:
     resolution: {integrity: sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==}
 
-  web-streams-polyfill@4.0.0-beta.3:
-    resolution: {integrity: sha512-QW95TCTaHmsYfHDybGMwO5IJIM93I/6vTRk+daHTWFPhwh+C8Cg7j7XyKrwrj8Ib6vYXe0ocYNrmzY4xAAN6ug==}
-    engines: {node: '>= 14'}
+  web-worker@1.5.0:
+    resolution: {integrity: sha512-RiMReJrTAiA+mBjGONMnjVDP2u3p9R1vkcGz6gDIrOMT3oGuYwX2WRMYI9ipkphSuE5XKEhydbhNEJh4NY9mlw==}
 
   webidl-conversions@3.0.1:
     resolution: {integrity: sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==}
@@ -7485,9 +9702,13 @@ packages:
     resolution: {integrity: sha512-n4W4YFyz5JzOfQeA8oN7dUYpR+MBP3PIUsn2jLjWXwK5ASUzt0Jc/A5sAUZoCYFJRGF0FBKJ+1JjN43rNdsQzA==}
     engines: {node: '>=20'}
 
+  webpack-virtual-modules@0.6.2:
+    resolution: {integrity: sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ==}
+
   whatwg-encoding@3.1.1:
     resolution: {integrity: sha512-6qN4hJdMwfYBtE3YBTTHhoeuUrDBPZmbQaxWAqSALV/MeEnR5z1xd8UKud2RAkFoPkmB+hli1TZSnyi84xz1vQ==}
     engines: {node: '>=18'}
+    deprecated: Use @exodus/bytes instead for a more spec-conformant and faster implementation
 
   whatwg-mimetype@4.0.0:
     resolution: {integrity: sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg==}
@@ -7526,6 +9747,10 @@ packages:
     resolution: {integrity: sha512-rEvr90Bck4WZt9HHFC4DJMsjvu7x+r6bImz0/BrbWb7A2djJ8hnZMrWnHo9F8ssv0OMErasDhftrfROTyqSDrw==}
     engines: {node: '>= 0.4'}
 
+  which@1.3.1:
+    resolution: {integrity: sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ==}
+    hasBin: true
+
   which@2.0.2:
     resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
     engines: {node: '>= 8'}
@@ -7544,10 +9769,6 @@ packages:
     resolution: {integrity: sha512-c9bZp7b5YtRj2wOe6dlj32MK+Bx/M/d+9VB2SHM1OtsUHR0aV0tdP6DWh/iMt0kWi1t5g1Iudu6hQRNd1A4PVA==}
     engines: {node: '>=18'}
 
-  word-wrap@1.2.5:
-    resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
-    engines: {node: '>=0.10.0'}
-
   wrap-ansi@7.0.0:
     resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
     engines: {node: '>=10'}
@@ -7575,6 +9796,10 @@ packages:
       utf-8-validate:
         optional: true
 
+  wsl-utils@0.3.1:
+    resolution: {integrity: sha512-g/eziiSUNBSsdDJtCLB8bdYEUMj4jR7AGeUo96p/3dTafgjHhpF4RiCFPiRILwjQoDXx5MqkBr4fwWtR3Ky4Wg==}
+    engines: {node: '>=20'}
+
   xdg-basedir@5.1.0:
     resolution: {integrity: sha512-GCPAHLvrIH13+c0SuacwvRYj2SxJXQ4kaVTT5xgL3kPrz56XxkF21IGhjSE1+W0aw7gpBWRGXLCPnPby6lSpmQ==}
     engines: {node: '>=12'}
@@ -7600,27 +9825,42 @@ packages:
   yallist@3.1.1:
     resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
 
-  yallist@5.0.0:
-    resolution: {integrity: sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==}
-    engines: {node: '>=18'}
+  yaml-language-server@1.19.2:
+    resolution: {integrity: sha512-9F3myNmJzUN/679jycdMxqtydPSDRAarSj3wPiF7pchEPnO9Dg07Oc+gIYLqXR4L+g+FSEVXXv2+mr54StLFOg==}
+    hasBin: true
 
-  yaml-language-server@1.15.0:
-    resolution: {integrity: sha512-N47AqBDCMQmh6mBLmI6oqxryHRzi33aPFPsJhYy3VTUGCdLHYjGh4FZzpUjRlphaADBBkDmnkM/++KNIOHi5Rw==}
+  yaml-language-server@1.20.0:
+    resolution: {integrity: sha512-qhjK/bzSRZ6HtTvgeFvjNPJGWdZ0+x5NREV/9XZWFjIGezew2b4r5JPy66IfOhd5OA7KeFwk1JfmEbnTvev0cA==}
     hasBin: true
 
-  yaml@2.2.2:
-    resolution: {integrity: sha512-CBKFWExMn46Foo4cldiChEzn7S7SRV+wqiluAb6xmueD/fGyRHIhX8m14vVGgeFWjN540nKCNVj6P21eQjgTuA==}
+  yaml@2.7.1:
+    resolution: {integrity: sha512-10ULxpnOCQXxJvBgxsn9ptjq6uviG/htZKk9veJGhlqn3w/DxQ631zFF+nlQXLwmImeS5amR2dl2U8sg6U9jsQ==}
     engines: {node: '>= 14'}
+    hasBin: true
 
   yaml@2.8.1:
     resolution: {integrity: sha512-lcYcMxX2PO9XMGvAJkJ3OsNMw+/7FKes7/hgerGUYWIoWu5j/+YQqcZr5JnPZWzOsEBgMbSbiSTn/dv/69Mkpw==}
     engines: {node: '>= 14.6'}
     hasBin: true
 
+  yaml@2.8.2:
+    resolution: {integrity: sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
+  yaml@2.9.0:
+    resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
   yargs-parser@21.1.1:
     resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
     engines: {node: '>=12'}
 
+  yargs-parser@22.0.0:
+    resolution: {integrity: sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw==}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=23}
+
   yargs@17.7.2:
     resolution: {integrity: sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==}
     engines: {node: '>=12'}
@@ -7629,31 +9869,17 @@ packages:
     resolution: {integrity: sha512-AyeEbWOu/TAXdxlV9wmGcR0+yh2j3vYPGOECcIj2S7MkrLyC7ne+oye2BKTItt0ii2PHk4cDy+95+LshzbXnGg==}
     engines: {node: '>=12.20'}
 
-  yocto-spinner@0.2.3:
-    resolution: {integrity: sha512-sqBChb33loEnkoXte1bLg45bEBsOP9N1kzQh5JZNKj/0rik4zAPTNSAVPj3uQAdc6slYJ0Ksc403G2XgxsJQFQ==}
-    engines: {node: '>=18.19'}
-
-  yoctocolors@2.1.2:
-    resolution: {integrity: sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==}
-    engines: {node: '>=18'}
-
-  zhead@2.2.4:
-    resolution: {integrity: sha512-8F0OI5dpWIA5IGG5NHUg9staDwz/ZPxZtvGVf01j7vHqSyZ0raHY+78atOVxRqb73AotX22uV1pXt3gYSstGag==}
-
-  zod-to-json-schema@3.24.6:
-    resolution: {integrity: sha512-h/z3PKvcTcTetyjl1fkj79MHNEjm+HpD6NXheWjzOekY7kV+lwDYnHw+ivHkijnCSMz1yJaWBD9vu/Fcmk+vEg==}
-    peerDependencies:
-      zod: ^3.24.1
-
-  zod-to-ts@1.2.0:
-    resolution: {integrity: sha512-x30XE43V+InwGpvTySRNz9kB7qFU8DlyEy7BsSTCHPH1R0QasMmHWZDCzYm6bVXtj/9NNJAZF3jW8rzFvH5OFA==}
+  zod-to-json-schema@3.25.1:
+    resolution: {integrity: sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA==}
     peerDependencies:
-      typescript: ^4.9.4 || ^5.0.2
-      zod: ^3
+      zod: ^3.25 || ^4
 
   zod@3.25.76:
     resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
 
+  zod@4.3.6:
+    resolution: {integrity: sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==}
+
   zustand@4.5.7:
     resolution: {integrity: sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==}
     engines: {node: '>=12.7.0'}
@@ -7674,58 +9900,63 @@ packages:
 
 snapshots:
 
-  '@ai-sdk/anthropic@2.0.25(zod@3.25.76)':
+  '@ai-sdk/gateway@3.0.13(zod@4.3.6)':
     dependencies:
-      '@ai-sdk/provider': 2.0.0
-      '@ai-sdk/provider-utils': 3.0.11(zod@3.25.76)
-      zod: 3.25.76
+      '@ai-sdk/provider': 3.0.2
+      '@ai-sdk/provider-utils': 4.0.5(zod@4.3.6)
+      '@vercel/oidc': 3.1.0
+      zod: 4.3.6
 
-  '@ai-sdk/gateway@1.0.35(zod@3.25.76)':
+  '@ai-sdk/gateway@3.0.9(zod@4.3.6)':
     dependencies:
-      '@ai-sdk/provider': 2.0.0
-      '@ai-sdk/provider-utils': 3.0.11(zod@3.25.76)
-      '@vercel/oidc': 3.0.2
-      zod: 3.25.76
+      '@ai-sdk/provider': 3.0.2
+      '@ai-sdk/provider-utils': 4.0.4(zod@4.3.6)
+      '@vercel/oidc': 3.1.0
+      zod: 4.3.6
 
-  '@ai-sdk/google@2.0.18(zod@3.25.76)':
+  '@ai-sdk/provider-utils@4.0.4(zod@4.3.6)':
     dependencies:
-      '@ai-sdk/provider': 2.0.0
-      '@ai-sdk/provider-utils': 3.0.11(zod@3.25.76)
-      zod: 3.25.76
-
-  '@ai-sdk/openai@2.0.45(zod@3.25.76)':
-    dependencies:
-      '@ai-sdk/provider': 2.0.0
-      '@ai-sdk/provider-utils': 3.0.11(zod@3.25.76)
-      zod: 3.25.76
+      '@ai-sdk/provider': 3.0.2
+      '@standard-schema/spec': 1.1.0
+      eventsource-parser: 3.0.6
+      zod: 4.3.6
 
-  '@ai-sdk/provider-utils@3.0.11(zod@3.25.76)':
+  '@ai-sdk/provider-utils@4.0.5(zod@4.3.6)':
     dependencies:
-      '@ai-sdk/provider': 2.0.0
-      '@standard-schema/spec': 1.0.0
+      '@ai-sdk/provider': 3.0.2
+      '@standard-schema/spec': 1.1.0
       eventsource-parser: 3.0.6
-      zod: 3.25.76
+      zod: 4.3.6
 
-  '@ai-sdk/provider@2.0.0':
+  '@ai-sdk/provider@3.0.2':
     dependencies:
       json-schema: 0.4.0
 
-  '@ai-sdk/react@2.0.62(react@18.3.1)(zod@3.25.76)':
+  '@ai-sdk/react@3.0.17(react@18.3.1)(zod@4.3.6)':
     dependencies:
-      '@ai-sdk/provider-utils': 3.0.11(zod@3.25.76)
-      ai: 5.0.62(zod@3.25.76)
+      '@ai-sdk/provider-utils': 4.0.4(zod@4.3.6)
+      ai: 6.0.17(zod@4.3.6)
       react: 18.3.1
       swr: 2.3.6(react@18.3.1)
       throttleit: 2.1.0
-    optionalDependencies:
-      zod: 3.25.76
+    transitivePeerDependencies:
+      - zod
+
+  '@ai-sdk/vue@3.0.33(vue@3.5.32(typescript@5.9.3))(zod@4.3.6)':
+    dependencies:
+      '@ai-sdk/provider-utils': 4.0.5(zod@4.3.6)
+      ai: 6.0.33(zod@4.3.6)
+      swrv: 1.2.0(vue@3.5.32(typescript@5.9.3))
+      vue: 3.5.32(typescript@5.9.3)
+    transitivePeerDependencies:
+      - zod
 
   '@alloc/quick-lru@5.2.0': {}
 
   '@antfu/install-pkg@1.1.0':
     dependencies:
-      package-manager-detector: 1.4.0
-      tinyexec: 1.0.1
+      package-manager-detector: 1.6.0
+      tinyexec: 1.1.2
 
   '@antfu/utils@9.3.0': {}
 
@@ -7735,7 +9966,7 @@ snapshots:
       '@csstools/css-color-parser': 3.1.0(@csstools/css-parser-algorithms@3.0.5(@csstools/css-tokenizer@3.0.4))(@csstools/css-tokenizer@3.0.4)
       '@csstools/css-parser-algorithms': 3.0.5(@csstools/css-tokenizer@3.0.4)
       '@csstools/css-tokenizer': 3.0.4
-      lru-cache: 11.2.2
+      lru-cache: 11.3.6
 
   '@asamuzakjp/dom-selector@6.6.1':
     dependencies:
@@ -7743,13 +9974,13 @@ snapshots:
       bidi-js: 1.0.3
       css-tree: 3.1.0
       is-potential-custom-element-name: 1.0.1
-      lru-cache: 11.2.2
+      lru-cache: 11.3.6
 
   '@asamuzakjp/nwsapi@2.3.9': {}
 
   '@astrojs/check@0.5.10(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)':
     dependencies:
-      '@astrojs/language-server': 2.15.4(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)
+      '@astrojs/language-server': 2.16.2(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)
       chokidar: 3.6.0
       fast-glob: 3.3.3
       kleur: 4.1.5
@@ -7759,9 +9990,9 @@ snapshots:
       - prettier
       - prettier-plugin-astro
 
-  '@astrojs/check@0.9.5(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)':
+  '@astrojs/check@0.9.9(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)':
     dependencies:
-      '@astrojs/language-server': 2.15.4(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)
+      '@astrojs/language-server': 2.16.7(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)
       chokidar: 4.0.3
       kleur: 4.1.5
       typescript: 5.9.3
@@ -7770,13 +10001,88 @@ snapshots:
       - prettier
       - prettier-plugin-astro
 
+  '@astrojs/compiler-binding-darwin-arm64@0.2.2':
+    optional: true
+
+  '@astrojs/compiler-binding-darwin-x64@0.2.2':
+    optional: true
+
+  '@astrojs/compiler-binding-linux-arm64-gnu@0.2.2':
+    optional: true
+
+  '@astrojs/compiler-binding-linux-arm64-musl@0.2.2':
+    optional: true
+
+  '@astrojs/compiler-binding-linux-x64-gnu@0.2.2':
+    optional: true
+
+  '@astrojs/compiler-binding-linux-x64-musl@0.2.2':
+    optional: true
+
+  '@astrojs/compiler-binding-wasm32-wasi@0.2.2(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)':
+    dependencies:
+      '@napi-rs/wasm-runtime': 1.1.5(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+    optional: true
+
+  '@astrojs/compiler-binding-win32-arm64-msvc@0.2.2':
+    optional: true
+
+  '@astrojs/compiler-binding-win32-x64-msvc@0.2.2':
+    optional: true
+
+  '@astrojs/compiler-binding@0.2.2(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)':
+    optionalDependencies:
+      '@astrojs/compiler-binding-darwin-arm64': 0.2.2
+      '@astrojs/compiler-binding-darwin-x64': 0.2.2
+      '@astrojs/compiler-binding-linux-arm64-gnu': 0.2.2
+      '@astrojs/compiler-binding-linux-arm64-musl': 0.2.2
+      '@astrojs/compiler-binding-linux-x64-gnu': 0.2.2
+      '@astrojs/compiler-binding-linux-x64-musl': 0.2.2
+      '@astrojs/compiler-binding-wasm32-wasi': 0.2.2(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)
+      '@astrojs/compiler-binding-win32-arm64-msvc': 0.2.2
+      '@astrojs/compiler-binding-win32-x64-msvc': 0.2.2
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+
+  '@astrojs/compiler-rs@0.2.2(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)':
+    dependencies:
+      '@astrojs/compiler-binding': 0.2.2(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+
   '@astrojs/compiler@2.13.0': {}
 
-  '@astrojs/internal-helpers@0.7.5': {}
+  '@astrojs/compiler@2.13.1': {}
 
-  '@astrojs/language-server@2.15.4(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)':
+  '@astrojs/compiler@3.0.0': {}
+
+  '@astrojs/internal-helpers@0.10.0':
     dependencies:
-      '@astrojs/compiler': 2.13.0
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      js-yaml: 4.2.0
+      picomatch: 4.0.4
+      retext-smartypants: 6.2.0
+      shiki: 4.0.2
+      smol-toml: 1.6.0
+      unified: 11.0.5
+
+  '@astrojs/internal-helpers@0.8.0':
+    dependencies:
+      picomatch: 4.0.4
+
+  '@astrojs/internal-helpers@0.9.0':
+    dependencies:
+      picomatch: 4.0.4
+
+  '@astrojs/language-server@2.16.2(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)':
+    dependencies:
+      '@astrojs/compiler': 2.13.1
       '@astrojs/yaml2ts': 0.2.2
       '@jridgewell/sourcemap-codec': 1.5.5
       '@volar/kit': 2.4.23(typescript@5.9.3)
@@ -7785,30 +10091,105 @@ snapshots:
       '@volar/language-service': 2.4.23
       fast-glob: 3.3.3
       muggle-string: 0.4.1
-      volar-service-css: 0.0.62(@volar/language-service@2.4.23)
-      volar-service-emmet: 0.0.62(@volar/language-service@2.4.23)
-      volar-service-html: 0.0.62(@volar/language-service@2.4.23)
-      volar-service-prettier: 0.0.62(@volar/language-service@2.4.23)(prettier@3.6.2)
-      volar-service-typescript: 0.0.62(@volar/language-service@2.4.23)
-      volar-service-typescript-twoslash-queries: 0.0.62(@volar/language-service@2.4.23)
-      volar-service-yaml: 0.0.62(@volar/language-service@2.4.23)
+      volar-service-css: 0.0.67(@volar/language-service@2.4.23)
+      volar-service-emmet: 0.0.67(@volar/language-service@2.4.23)
+      volar-service-html: 0.0.67(@volar/language-service@2.4.23)
+      volar-service-prettier: 0.0.67(@volar/language-service@2.4.23)(prettier@3.6.2)
+      volar-service-typescript: 0.0.67(@volar/language-service@2.4.23)
+      volar-service-typescript-twoslash-queries: 0.0.67(@volar/language-service@2.4.23)
+      volar-service-yaml: 0.0.67(@volar/language-service@2.4.23)
       vscode-html-languageservice: 5.5.2
       vscode-uri: 3.1.0
     optionalDependencies:
       prettier: 3.6.2
       prettier-plugin-astro: 0.14.1
     transitivePeerDependencies:
-      - typescript
+      - typescript
+
+  '@astrojs/language-server@2.16.7(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3)':
+    dependencies:
+      '@astrojs/compiler': 2.13.1
+      '@astrojs/yaml2ts': 0.2.3
+      '@jridgewell/sourcemap-codec': 1.5.5
+      '@volar/kit': 2.4.28(typescript@5.9.3)
+      '@volar/language-core': 2.4.28
+      '@volar/language-server': 2.4.28
+      '@volar/language-service': 2.4.28
+      muggle-string: 0.4.1
+      tinyglobby: 0.2.16
+      volar-service-css: 0.0.70(@volar/language-service@2.4.28)
+      volar-service-emmet: 0.0.70(@volar/language-service@2.4.28)
+      volar-service-html: 0.0.70(@volar/language-service@2.4.28)
+      volar-service-prettier: 0.0.70(@volar/language-service@2.4.28)(prettier@3.6.2)
+      volar-service-typescript: 0.0.70(@volar/language-service@2.4.28)
+      volar-service-typescript-twoslash-queries: 0.0.70(@volar/language-service@2.4.28)
+      volar-service-yaml: 0.0.70(@volar/language-service@2.4.28)
+      vscode-html-languageservice: 5.6.2
+      vscode-uri: 3.1.0
+    optionalDependencies:
+      prettier: 3.6.2
+      prettier-plugin-astro: 0.14.1
+    transitivePeerDependencies:
+      - typescript
+
+  '@astrojs/markdown-remark@7.0.0':
+    dependencies:
+      '@astrojs/internal-helpers': 0.8.0
+      '@astrojs/prism': 4.0.0
+      github-slugger: 2.0.0
+      hast-util-from-html: 2.0.3
+      hast-util-to-text: 4.0.2
+      js-yaml: 4.2.0
+      mdast-util-definitions: 6.0.0
+      rehype-raw: 7.0.0
+      rehype-stringify: 10.0.1
+      remark-gfm: 4.0.1
+      remark-parse: 11.0.0
+      remark-rehype: 11.1.2
+      remark-smartypants: 3.0.2
+      shiki: 4.0.2
+      smol-toml: 1.6.0
+      unified: 11.0.5
+      unist-util-remove-position: 5.0.0
+      unist-util-visit: 5.1.0
+      unist-util-visit-parents: 6.0.2
+      vfile: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@astrojs/markdown-remark@7.1.1':
+    dependencies:
+      '@astrojs/internal-helpers': 0.9.0
+      '@astrojs/prism': 4.0.1
+      github-slugger: 2.0.0
+      hast-util-from-html: 2.0.3
+      hast-util-to-text: 4.0.2
+      js-yaml: 4.2.0
+      mdast-util-definitions: 6.0.0
+      rehype-raw: 7.0.0
+      rehype-stringify: 10.0.1
+      remark-gfm: 4.0.1
+      remark-parse: 11.0.0
+      remark-rehype: 11.1.2
+      remark-smartypants: 3.0.2
+      retext-smartypants: 6.2.0
+      shiki: 4.0.2
+      smol-toml: 1.6.0
+      unified: 11.0.5
+      unist-util-remove-position: 5.0.0
+      unist-util-visit: 5.1.0
+      unist-util-visit-parents: 6.0.2
+      vfile: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
 
-  '@astrojs/markdown-remark@6.3.9':
+  '@astrojs/markdown-remark@7.2.0':
     dependencies:
-      '@astrojs/internal-helpers': 0.7.5
-      '@astrojs/prism': 3.3.0
+      '@astrojs/internal-helpers': 0.10.0
+      '@astrojs/prism': 4.0.2
       github-slugger: 2.0.0
       hast-util-from-html: 2.0.3
       hast-util-to-text: 4.0.2
-      import-meta-resolve: 4.2.0
-      js-yaml: 4.1.0
       mdast-util-definitions: 6.0.0
       rehype-raw: 7.0.0
       rehype-stringify: 10.0.1
@@ -7816,23 +10197,28 @@ snapshots:
       remark-parse: 11.0.0
       remark-rehype: 11.1.2
       remark-smartypants: 3.0.2
-      shiki: 3.13.0
-      smol-toml: 1.4.2
       unified: 11.0.5
       unist-util-remove-position: 5.0.0
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
       unist-util-visit-parents: 6.0.2
       vfile: 6.0.3
     transitivePeerDependencies:
       - supports-color
 
-  '@astrojs/mdx@4.3.12(astro@5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1))':
+  '@astrojs/markdown-satteri@0.3.2':
     dependencies:
-      '@astrojs/markdown-remark': 6.3.9
+      '@astrojs/internal-helpers': 0.10.0
+      '@astrojs/prism': 4.0.2
+      github-slugger: 2.0.0
+      satteri: 0.9.1
+
+  '@astrojs/mdx@5.0.4(astro@6.0.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0))':
+    dependencies:
+      '@astrojs/markdown-remark': 7.1.1
       '@mdx-js/mdx': 3.1.1
-      acorn: 8.15.0
-      astro: 5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1)
-      es-module-lexer: 1.7.0
+      acorn: 8.16.0
+      astro: 6.0.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
+      es-module-lexer: 2.0.0
       estree-util-visit: 2.0.0
       hast-util-to-html: 9.0.5
       piccolore: 0.1.3
@@ -7840,38 +10226,71 @@ snapshots:
       remark-gfm: 4.0.1
       remark-smartypants: 3.0.2
       source-map: 0.7.6
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@astrojs/mdx@7.0.0(@astrojs/markdown-satteri@0.3.2)(astro@7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      '@astrojs/internal-helpers': 0.10.0
+      '@astrojs/markdown-remark': 7.2.0
+      '@mdx-js/mdx': 3.1.1
+      acorn: 8.16.0
+      astro: 7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      es-module-lexer: 2.0.0
+      estree-util-visit: 2.0.0
+      hast-util-to-html: 9.0.5
+      piccolore: 0.1.3
+      rehype-raw: 7.0.0
+      remark-gfm: 4.0.1
+      remark-smartypants: 3.0.2
+      source-map: 0.7.6
+      unist-util-visit: 5.1.0
       vfile: 6.0.3
+    optionalDependencies:
+      '@astrojs/markdown-satteri': 0.3.2
     transitivePeerDependencies:
       - supports-color
 
-  '@astrojs/node@9.5.1(astro@5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1))':
+  '@astrojs/node@11.0.0(astro@7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))':
     dependencies:
-      '@astrojs/internal-helpers': 0.7.5
-      astro: 5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1)
-      send: 1.2.0
+      '@astrojs/internal-helpers': 0.10.0
+      astro: 7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      send: 1.2.1
       server-destroy: 1.0.1
     transitivePeerDependencies:
       - supports-color
 
-  '@astrojs/prism@3.3.0':
+  '@astrojs/prism@4.0.0':
+    dependencies:
+      prismjs: 1.30.0
+
+  '@astrojs/prism@4.0.1':
+    dependencies:
+      prismjs: 1.30.0
+
+  '@astrojs/prism@4.0.2':
     dependencies:
       prismjs: 1.30.0
 
-  '@astrojs/react@4.4.2(@types/node@20.19.19)(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(jiti@1.21.7)(lightningcss@1.29.3)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(terser@5.39.0)(yaml@2.8.1)':
+  '@astrojs/react@6.0.0(@types/node@22.19.21)(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(esbuild@0.28.1)(jiti@2.7.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)':
     dependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
-      '@vitejs/plugin-react': 4.7.0(vite@6.4.1(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1))
+      '@astrojs/internal-helpers': 0.10.0
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
+      '@vitejs/plugin-react': 5.2.0(vite@8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
+      devalue: 5.8.1
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
       ultrahtml: 1.6.0
-      vite: 6.4.1(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1)
+      vite: 8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
     transitivePeerDependencies:
       - '@types/node'
+      - '@vitejs/devtools'
+      - esbuild
       - jiti
       - less
-      - lightningcss
       - sass
       - sass-embedded
       - stylus
@@ -7881,24 +10300,55 @@ snapshots:
       - tsx
       - yaml
 
-  '@astrojs/rss@4.0.14':
+  '@astrojs/rss@4.0.18':
     dependencies:
-      fast-xml-parser: 5.3.0
+      fast-xml-parser: 5.5.10
       piccolore: 0.1.3
+      zod: 4.3.6
 
-  '@astrojs/tailwind@6.0.2(astro@5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1))(tailwindcss@3.4.18(yaml@2.8.1))':
+  '@astrojs/sitemap@3.7.1':
     dependencies:
-      astro: 5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1)
-      autoprefixer: 10.4.21(postcss@8.5.6)
-      postcss: 8.5.6
-      postcss-load-config: 4.0.2(postcss@8.5.6)
-      tailwindcss: 3.4.18(yaml@2.8.1)
+      sitemap: 9.0.1
+      stream-replace-string: 2.0.0
+      zod: 4.3.6
+
+  '@astrojs/starlight@0.38.0(astro@6.0.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0))':
+    dependencies:
+      '@astrojs/markdown-remark': 7.2.0
+      '@astrojs/mdx': 5.0.4(astro@6.0.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0))
+      '@astrojs/sitemap': 3.7.1
+      '@pagefind/default-ui': 1.4.0
+      '@types/hast': 3.0.4
+      '@types/js-yaml': 4.0.9
+      '@types/mdast': 4.0.4
+      astro: 6.0.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
+      astro-expressive-code: 0.41.7(astro@6.0.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0))
+      bcp-47: 2.1.0
+      hast-util-from-html: 2.0.3
+      hast-util-select: 6.0.4
+      hast-util-to-string: 3.0.1
+      hastscript: 9.0.1
+      i18next: 23.16.8
+      js-yaml: 4.2.0
+      klona: 2.0.6
+      magic-string: 0.30.21
+      mdast-util-directive: 3.1.0
+      mdast-util-to-markdown: 2.1.2
+      mdast-util-to-string: 4.0.0
+      pagefind: 1.4.0
+      rehype: 13.0.2
+      rehype-format: 5.0.1
+      remark-directive: 3.0.1
+      ultrahtml: 1.6.0
+      unified: 11.0.5
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
     transitivePeerDependencies:
-      - ts-node
+      - supports-color
 
   '@astrojs/telemetry@3.3.0':
     dependencies:
-      ci-info: 4.3.1
+      ci-info: 4.4.0
       debug: 4.4.3
       dlv: 1.1.3
       dset: 3.1.4
@@ -7908,13 +10358,25 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  '@astrojs/telemetry@3.3.2':
+    dependencies:
+      ci-info: 4.4.0
+      dset: 3.1.4
+      is-docker: 4.0.0
+      is-wsl: 3.1.1
+      which-pm-runs: 1.1.0
+
   '@astrojs/yaml2ts@0.2.2':
     dependencies:
-      yaml: 2.8.1
+      yaml: 2.8.2
+
+  '@astrojs/yaml2ts@0.2.3':
+    dependencies:
+      yaml: 2.8.2
 
   '@asyncapi/avro-schema-parser@3.0.24':
     dependencies:
-      '@asyncapi/parser': 3.4.0
+      '@asyncapi/parser': 3.6.0
       '@types/json-schema': 7.0.15
       avsc: 5.7.9
     transitivePeerDependencies:
@@ -7922,7 +10384,7 @@ snapshots:
 
   '@asyncapi/openapi-schema-parser@3.0.24':
     dependencies:
-      '@asyncapi/parser': 3.4.0
+      '@asyncapi/parser': 3.6.0
       '@openapi-contrib/openapi-schema-to-json-schema': 3.2.0
       ajv: 8.17.1
       ajv-errors: 3.0.0(ajv@8.17.1)
@@ -7930,9 +10392,9 @@ snapshots:
     transitivePeerDependencies:
       - encoding
 
-  '@asyncapi/parser@3.4.0':
+  '@asyncapi/parser@3.6.0':
     dependencies:
-      '@asyncapi/specs': 6.10.0
+      '@asyncapi/specs': 6.11.1
       '@openapi-contrib/openapi-schema-to-json-schema': 3.2.0
       '@stoplight/json': 3.21.0
       '@stoplight/json-ref-readers': 1.2.2
@@ -7948,32 +10410,33 @@ snapshots:
       ajv-errors: 3.0.0(ajv@8.17.1)
       ajv-formats: 2.1.1(ajv@8.17.1)
       avsc: 5.7.9
-      js-yaml: 4.1.0
-      jsonpath-plus: 10.3.0
+      js-yaml: 4.2.0
+      jsonpath-plus: 10.4.0
       node-fetch: 2.6.7
     transitivePeerDependencies:
       - encoding
 
   '@asyncapi/protobuf-schema-parser@3.6.0':
     dependencies:
-      '@asyncapi/parser': 3.4.0
+      '@asyncapi/parser': 3.6.0
       '@types/protocol-buffers-schema': 3.4.3
       protobufjs: 7.5.4
     transitivePeerDependencies:
       - encoding
 
-  '@asyncapi/react-component@2.4.3(postcss@8.5.6)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@asyncapi/react-component@3.1.0(postcss@8.5.15)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@asyncapi/avro-schema-parser': 3.0.24
       '@asyncapi/openapi-schema-parser': 3.0.24
-      '@asyncapi/parser': 3.4.0
+      '@asyncapi/parser': 3.6.0
       '@asyncapi/protobuf-schema-parser': 3.6.0
       highlight.js: 10.7.3
-      isomorphic-dompurify: 2.28.0(postcss@8.5.6)
+      isomorphic-dompurify: 2.28.0(postcss@8.5.15)
       marked: 4.3.0
       openapi-sampler: 1.6.1
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
+      react-error-boundary: 4.1.2(react@18.3.1)
       use-resize-observer: 9.1.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
     transitivePeerDependencies:
       - bufferutil
@@ -7983,7 +10446,7 @@ snapshots:
       - supports-color
       - utf-8-validate
 
-  '@asyncapi/specs@6.10.0':
+  '@asyncapi/specs@6.11.1':
     dependencies:
       '@types/json-schema': 7.0.15
 
@@ -7995,25 +10458,25 @@ snapshots:
       preact: 10.24.3
       preact-render-to-string: 6.5.11(preact@10.24.3)
 
-  '@babel/code-frame@7.27.1':
+  '@babel/code-frame@7.29.0':
     dependencies:
-      '@babel/helper-validator-identifier': 7.27.1
+      '@babel/helper-validator-identifier': 7.28.5
       js-tokens: 4.0.0
       picocolors: 1.1.1
 
-  '@babel/compat-data@7.28.4': {}
+  '@babel/compat-data@7.29.0': {}
 
-  '@babel/core@7.28.4':
+  '@babel/core@7.29.0':
     dependencies:
-      '@babel/code-frame': 7.27.1
-      '@babel/generator': 7.28.3
-      '@babel/helper-compilation-targets': 7.27.2
-      '@babel/helper-module-transforms': 7.28.3(@babel/core@7.28.4)
-      '@babel/helpers': 7.28.4
-      '@babel/parser': 7.28.4
-      '@babel/template': 7.27.2
-      '@babel/traverse': 7.28.4
-      '@babel/types': 7.28.4
+      '@babel/code-frame': 7.29.0
+      '@babel/generator': 7.29.1
+      '@babel/helper-compilation-targets': 7.28.6
+      '@babel/helper-module-transforms': 7.28.6(@babel/core@7.29.0)
+      '@babel/helpers': 7.28.6
+      '@babel/parser': 7.29.0
+      '@babel/template': 7.28.6
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
       '@jridgewell/remapping': 2.3.5
       convert-source-map: 2.0.0
       debug: 4.4.3
@@ -8023,17 +10486,17 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@babel/generator@7.28.3':
+  '@babel/generator@7.29.1':
     dependencies:
-      '@babel/parser': 7.28.4
-      '@babel/types': 7.28.4
+      '@babel/parser': 7.29.0
+      '@babel/types': 7.29.0
       '@jridgewell/gen-mapping': 0.3.13
       '@jridgewell/trace-mapping': 0.3.31
       jsesc: 3.1.0
 
-  '@babel/helper-compilation-targets@7.27.2':
+  '@babel/helper-compilation-targets@7.28.6':
     dependencies:
-      '@babel/compat-data': 7.28.4
+      '@babel/compat-data': 7.29.0
       '@babel/helper-validator-option': 7.27.1
       browserslist: 4.26.3
       lru-cache: 5.1.1
@@ -8041,19 +10504,19 @@ snapshots:
 
   '@babel/helper-globals@7.28.0': {}
 
-  '@babel/helper-module-imports@7.27.1':
+  '@babel/helper-module-imports@7.28.6':
     dependencies:
-      '@babel/traverse': 7.28.4
-      '@babel/types': 7.28.4
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
     transitivePeerDependencies:
       - supports-color
 
-  '@babel/helper-module-transforms@7.28.3(@babel/core@7.28.4)':
+  '@babel/helper-module-transforms@7.28.6(@babel/core@7.29.0)':
     dependencies:
-      '@babel/core': 7.28.4
-      '@babel/helper-module-imports': 7.27.1
-      '@babel/helper-validator-identifier': 7.27.1
-      '@babel/traverse': 7.28.4
+      '@babel/core': 7.29.0
+      '@babel/helper-module-imports': 7.28.6
+      '@babel/helper-validator-identifier': 7.28.5
+      '@babel/traverse': 7.29.0
     transitivePeerDependencies:
       - supports-color
 
@@ -8061,76 +10524,89 @@ snapshots:
 
   '@babel/helper-string-parser@7.27.1': {}
 
-  '@babel/helper-validator-identifier@7.27.1': {}
-
   '@babel/helper-validator-identifier@7.28.5': {}
 
   '@babel/helper-validator-option@7.27.1': {}
 
-  '@babel/helpers@7.28.4':
+  '@babel/helpers@7.28.6':
     dependencies:
-      '@babel/template': 7.27.2
-      '@babel/types': 7.28.4
+      '@babel/template': 7.28.6
+      '@babel/types': 7.29.0
 
-  '@babel/parser@7.28.4':
+  '@babel/parser@7.29.0':
     dependencies:
-      '@babel/types': 7.28.4
+      '@babel/types': 7.29.0
 
-  '@babel/parser@7.28.5':
+  '@babel/parser@7.29.2':
     dependencies:
-      '@babel/types': 7.28.5
+      '@babel/types': 7.29.0
 
-  '@babel/plugin-transform-react-jsx-self@7.27.1(@babel/core@7.28.4)':
+  '@babel/plugin-transform-react-jsx-self@7.27.1(@babel/core@7.29.0)':
     dependencies:
-      '@babel/core': 7.28.4
+      '@babel/core': 7.29.0
       '@babel/helper-plugin-utils': 7.27.1
 
-  '@babel/plugin-transform-react-jsx-source@7.27.1(@babel/core@7.28.4)':
+  '@babel/plugin-transform-react-jsx-source@7.27.1(@babel/core@7.29.0)':
     dependencies:
-      '@babel/core': 7.28.4
+      '@babel/core': 7.29.0
       '@babel/helper-plugin-utils': 7.27.1
 
   '@babel/runtime@7.28.4': {}
 
-  '@babel/template@7.27.2':
+  '@babel/template@7.28.6':
     dependencies:
-      '@babel/code-frame': 7.27.1
-      '@babel/parser': 7.28.4
-      '@babel/types': 7.28.4
+      '@babel/code-frame': 7.29.0
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
 
-  '@babel/traverse@7.28.4':
+  '@babel/traverse@7.29.0':
     dependencies:
-      '@babel/code-frame': 7.27.1
-      '@babel/generator': 7.28.3
+      '@babel/code-frame': 7.29.0
+      '@babel/generator': 7.29.1
       '@babel/helper-globals': 7.28.0
-      '@babel/parser': 7.28.4
-      '@babel/template': 7.27.2
-      '@babel/types': 7.28.4
+      '@babel/parser': 7.29.2
+      '@babel/template': 7.28.6
+      '@babel/types': 7.29.0
       debug: 4.4.3
     transitivePeerDependencies:
       - supports-color
 
-  '@babel/types@7.28.4':
-    dependencies:
-      '@babel/helper-string-parser': 7.27.1
-      '@babel/helper-validator-identifier': 7.27.1
-
-  '@babel/types@7.28.5':
+  '@babel/types@7.29.0':
     dependencies:
       '@babel/helper-string-parser': 7.27.1
       '@babel/helper-validator-identifier': 7.28.5
 
   '@braintree/sanitize-url@7.1.1': {}
 
-  '@capsizecss/unpack@3.0.1':
+  '@bruits/satteri-darwin-arm64@0.9.1':
+    optional: true
+
+  '@bruits/satteri-darwin-x64@0.9.1':
+    optional: true
+
+  '@bruits/satteri-linux-x64-gnu@0.9.1':
+    optional: true
+
+  '@bruits/satteri-wasm32-wasi@0.9.1':
     dependencies:
-      fontkit: 2.0.4
+      '@emnapi/core': 1.9.1
+      '@emnapi/runtime': 1.9.1
+      '@napi-rs/wasm-runtime': 1.1.5(@emnapi/core@1.9.1)(@emnapi/runtime@1.9.1)
+    optional: true
+
+  '@bruits/satteri-win32-x64-msvc@0.9.1':
+    optional: true
+
+  '@capsizecss/unpack@4.0.0':
+    dependencies:
+      fontkitten: 1.0.3
 
-  '@cfworker/json-schema@4.1.1': {}
+  '@cfworker/json-schema@4.1.1':
+    optional: true
 
   '@changesets/apply-release-plan@7.0.13':
     dependencies:
-      '@changesets/config': 3.1.1
+      '@changesets/config': 3.1.2
       '@changesets/get-version-range-type': 0.4.0
       '@changesets/git': 3.0.4
       '@changesets/should-skip-package': 0.1.2
@@ -8142,7 +10618,7 @@ snapshots:
       outdent: 0.5.0
       prettier: 2.8.8
       resolve-from: 5.0.0
-      semver: 7.6.3
+      semver: 7.7.4
 
   '@changesets/assemble-release-plan@6.0.9':
     dependencies:
@@ -8151,13 +10627,13 @@ snapshots:
       '@changesets/should-skip-package': 0.1.2
       '@changesets/types': 6.1.0
       '@manypkg/get-packages': 1.1.3
-      semver: 7.6.3
+      semver: 7.7.4
 
   '@changesets/changelog-git@0.2.1':
     dependencies:
       '@changesets/types': 6.1.0
 
-  '@changesets/cli@2.29.7(@types/node@20.19.19)':
+  '@changesets/cli@2.29.7(@types/node@25.0.3)':
     dependencies:
       '@changesets/apply-release-plan': 7.0.13
       '@changesets/assemble-release-plan': 6.0.9
@@ -8173,7 +10649,7 @@ snapshots:
       '@changesets/should-skip-package': 0.1.2
       '@changesets/types': 6.1.0
       '@changesets/write': 0.4.0
-      '@inquirer/external-editor': 1.0.2(@types/node@20.19.19)
+      '@inquirer/external-editor': 1.0.2(@types/node@25.0.3)
       '@manypkg/get-packages': 1.1.3
       ansi-colors: 4.1.3
       ci-info: 3.9.0
@@ -8184,7 +10660,7 @@ snapshots:
       package-manager-detector: 0.2.11
       picocolors: 1.1.1
       resolve-from: 5.0.0
-      semver: 7.6.3
+      semver: 7.7.4
       spawndamnit: 3.0.1
       term-size: 2.2.1
     transitivePeerDependencies:
@@ -8200,6 +10676,16 @@ snapshots:
       fs-extra: 7.0.1
       micromatch: 4.0.8
 
+  '@changesets/config@3.1.2':
+    dependencies:
+      '@changesets/errors': 0.2.0
+      '@changesets/get-dependents-graph': 2.1.3
+      '@changesets/logger': 0.1.1
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+      fs-extra: 7.0.1
+      micromatch: 4.0.8
+
   '@changesets/errors@0.2.0':
     dependencies:
       extendable-error: 0.1.7
@@ -8209,14 +10695,14 @@ snapshots:
       '@changesets/types': 6.1.0
       '@manypkg/get-packages': 1.1.3
       picocolors: 1.1.1
-      semver: 7.6.3
+      semver: 7.7.4
 
   '@changesets/get-release-plan@4.0.13':
     dependencies:
       '@changesets/assemble-release-plan': 6.0.9
-      '@changesets/config': 3.1.1
+      '@changesets/config': 3.1.2
       '@changesets/pre': 2.0.2
-      '@changesets/read': 0.6.5
+      '@changesets/read': 0.6.6
       '@changesets/types': 6.1.0
       '@manypkg/get-packages': 1.1.3
 
@@ -8239,6 +10725,11 @@ snapshots:
       '@changesets/types': 6.1.0
       js-yaml: 3.14.1
 
+  '@changesets/parse@0.4.2':
+    dependencies:
+      '@changesets/types': 6.1.0
+      js-yaml: 4.2.0
+
   '@changesets/pre@2.0.2':
     dependencies:
       '@changesets/errors': 0.2.0
@@ -8256,6 +10747,16 @@ snapshots:
       p-filter: 2.1.0
       picocolors: 1.1.1
 
+  '@changesets/read@0.6.6':
+    dependencies:
+      '@changesets/git': 3.0.4
+      '@changesets/logger': 0.1.1
+      '@changesets/parse': 0.4.2
+      '@changesets/types': 6.1.0
+      fs-extra: 7.0.1
+      p-filter: 2.1.0
+      picocolors: 1.1.1
+
   '@changesets/should-skip-package@0.1.2':
     dependencies:
       '@changesets/types': 6.1.0
@@ -8278,17 +10779,54 @@ snapshots:
       '@chevrotain/types': 11.0.3
       lodash-es: 4.17.21
 
+  '@chevrotain/cst-dts-gen@11.1.2':
+    dependencies:
+      '@chevrotain/gast': 11.1.2
+      '@chevrotain/types': 11.1.2
+      lodash-es: 4.17.23
+
   '@chevrotain/gast@11.0.3':
     dependencies:
       '@chevrotain/types': 11.0.3
       lodash-es: 4.17.21
 
+  '@chevrotain/gast@11.1.2':
+    dependencies:
+      '@chevrotain/types': 11.1.2
+      lodash-es: 4.17.23
+
   '@chevrotain/regexp-to-ast@11.0.3': {}
 
+  '@chevrotain/regexp-to-ast@11.1.2': {}
+
   '@chevrotain/types@11.0.3': {}
 
+  '@chevrotain/types@11.1.2': {}
+
   '@chevrotain/utils@11.0.3': {}
 
+  '@chevrotain/utils@11.1.2': {}
+
+  '@clack/core@0.3.5':
+    dependencies:
+      picocolors: 1.1.1
+      sisteransi: 1.0.5
+
+  '@clack/core@1.1.0':
+    dependencies:
+      sisteransi: 1.0.5
+
+  '@clack/prompts@0.8.2':
+    dependencies:
+      '@clack/core': 0.3.5
+      picocolors: 1.1.1
+      sisteransi: 1.0.5
+
+  '@clack/prompts@1.1.0':
+    dependencies:
+      '@clack/core': 1.1.0
+      sisteransi: 1.0.5
+
   '@codemirror/autocomplete@6.19.0':
     dependencies:
       '@codemirror/language': 6.11.3
@@ -8372,12 +10910,6 @@ snapshots:
       '@codemirror/view': 6.38.5
       crelt: 1.0.6
 
-  '@codemirror/search@6.5.11':
-    dependencies:
-      '@codemirror/state': 6.5.2
-      '@codemirror/view': 6.38.5
-      crelt: 1.0.6
-
   '@codemirror/state@6.5.2':
     dependencies:
       '@marijn/find-cluster-break': 1.0.2
@@ -8407,9 +10939,14 @@ snapshots:
     dependencies:
       '@csstools/css-tokenizer': 3.0.4
 
+  '@csstools/css-syntax-patches-for-csstree@1.0.14(postcss@8.5.15)':
+    dependencies:
+      postcss: 8.5.15
+
   '@csstools/css-syntax-patches-for-csstree@1.0.14(postcss@8.5.6)':
     dependencies:
       postcss: 8.5.6
+    optional: true
 
   '@csstools/css-tokenizer@3.0.4': {}
 
@@ -8423,7 +10960,7 @@ snapshots:
     dependencies:
       '@emmetio/scanner': 1.0.4
 
-  '@emmetio/css-parser@0.4.0':
+  '@emmetio/css-parser@0.4.1':
     dependencies:
       '@emmetio/stream-reader': 2.2.0
       '@emmetio/stream-reader-utils': 0.1.0
@@ -8438,144 +10975,325 @@ snapshots:
 
   '@emmetio/stream-reader@2.2.0': {}
 
+  '@emnapi/core@1.11.1':
+    dependencies:
+      '@emnapi/wasi-threads': 1.2.2
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/core@1.9.1':
+    dependencies:
+      '@emnapi/wasi-threads': 1.2.0
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/runtime@1.10.0':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/runtime@1.11.1':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
   '@emnapi/runtime@1.5.0':
     dependencies:
       tslib: 2.8.1
     optional: true
 
+  '@emnapi/runtime@1.9.1':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/wasi-threads@1.2.0':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@emnapi/wasi-threads@1.2.2':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
   '@esbuild/aix-ppc64@0.21.5':
     optional: true
 
   '@esbuild/aix-ppc64@0.25.10':
     optional: true
 
+  '@esbuild/aix-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/aix-ppc64@0.28.1':
+    optional: true
+
   '@esbuild/android-arm64@0.21.5':
     optional: true
 
   '@esbuild/android-arm64@0.25.10':
     optional: true
 
+  '@esbuild/android-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm64@0.28.1':
+    optional: true
+
   '@esbuild/android-arm@0.21.5':
     optional: true
 
   '@esbuild/android-arm@0.25.10':
     optional: true
 
+  '@esbuild/android-arm@0.27.3':
+    optional: true
+
+  '@esbuild/android-arm@0.28.1':
+    optional: true
+
   '@esbuild/android-x64@0.21.5':
     optional: true
 
   '@esbuild/android-x64@0.25.10':
     optional: true
 
+  '@esbuild/android-x64@0.27.3':
+    optional: true
+
+  '@esbuild/android-x64@0.28.1':
+    optional: true
+
   '@esbuild/darwin-arm64@0.21.5':
     optional: true
 
   '@esbuild/darwin-arm64@0.25.10':
     optional: true
 
+  '@esbuild/darwin-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.28.1':
+    optional: true
+
   '@esbuild/darwin-x64@0.21.5':
     optional: true
 
   '@esbuild/darwin-x64@0.25.10':
     optional: true
 
+  '@esbuild/darwin-x64@0.27.3':
+    optional: true
+
+  '@esbuild/darwin-x64@0.28.1':
+    optional: true
+
   '@esbuild/freebsd-arm64@0.21.5':
     optional: true
 
   '@esbuild/freebsd-arm64@0.25.10':
     optional: true
 
+  '@esbuild/freebsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.28.1':
+    optional: true
+
   '@esbuild/freebsd-x64@0.21.5':
     optional: true
 
   '@esbuild/freebsd-x64@0.25.10':
     optional: true
 
+  '@esbuild/freebsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.28.1':
+    optional: true
+
   '@esbuild/linux-arm64@0.21.5':
     optional: true
 
   '@esbuild/linux-arm64@0.25.10':
     optional: true
 
+  '@esbuild/linux-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm64@0.28.1':
+    optional: true
+
   '@esbuild/linux-arm@0.21.5':
     optional: true
 
   '@esbuild/linux-arm@0.25.10':
     optional: true
 
+  '@esbuild/linux-arm@0.27.3':
+    optional: true
+
+  '@esbuild/linux-arm@0.28.1':
+    optional: true
+
   '@esbuild/linux-ia32@0.21.5':
     optional: true
 
   '@esbuild/linux-ia32@0.25.10':
     optional: true
 
+  '@esbuild/linux-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ia32@0.28.1':
+    optional: true
+
   '@esbuild/linux-loong64@0.21.5':
     optional: true
 
   '@esbuild/linux-loong64@0.25.10':
     optional: true
 
+  '@esbuild/linux-loong64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-loong64@0.28.1':
+    optional: true
+
   '@esbuild/linux-mips64el@0.21.5':
     optional: true
 
   '@esbuild/linux-mips64el@0.25.10':
     optional: true
 
+  '@esbuild/linux-mips64el@0.27.3':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.28.1':
+    optional: true
+
   '@esbuild/linux-ppc64@0.21.5':
     optional: true
 
   '@esbuild/linux-ppc64@0.25.10':
     optional: true
 
+  '@esbuild/linux-ppc64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.28.1':
+    optional: true
+
   '@esbuild/linux-riscv64@0.21.5':
     optional: true
 
   '@esbuild/linux-riscv64@0.25.10':
     optional: true
 
+  '@esbuild/linux-riscv64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.28.1':
+    optional: true
+
   '@esbuild/linux-s390x@0.21.5':
     optional: true
 
   '@esbuild/linux-s390x@0.25.10':
     optional: true
 
+  '@esbuild/linux-s390x@0.27.3':
+    optional: true
+
+  '@esbuild/linux-s390x@0.28.1':
+    optional: true
+
   '@esbuild/linux-x64@0.21.5':
     optional: true
 
   '@esbuild/linux-x64@0.25.10':
     optional: true
 
+  '@esbuild/linux-x64@0.27.3':
+    optional: true
+
+  '@esbuild/linux-x64@0.28.1':
+    optional: true
+
   '@esbuild/netbsd-arm64@0.25.10':
     optional: true
 
+  '@esbuild/netbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.28.1':
+    optional: true
+
   '@esbuild/netbsd-x64@0.21.5':
     optional: true
 
   '@esbuild/netbsd-x64@0.25.10':
     optional: true
 
+  '@esbuild/netbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.28.1':
+    optional: true
+
   '@esbuild/openbsd-arm64@0.25.10':
     optional: true
 
+  '@esbuild/openbsd-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.28.1':
+    optional: true
+
   '@esbuild/openbsd-x64@0.21.5':
     optional: true
 
   '@esbuild/openbsd-x64@0.25.10':
     optional: true
 
+  '@esbuild/openbsd-x64@0.27.3':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.28.1':
+    optional: true
+
   '@esbuild/openharmony-arm64@0.25.10':
     optional: true
 
+  '@esbuild/openharmony-arm64@0.27.3':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.28.1':
+    optional: true
+
   '@esbuild/sunos-x64@0.21.5':
     optional: true
 
   '@esbuild/sunos-x64@0.25.10':
     optional: true
 
-  '@esbuild/win32-arm64@0.21.5':
+  '@esbuild/sunos-x64@0.27.3':
+    optional: true
+
+  '@esbuild/sunos-x64@0.28.1':
+    optional: true
+
+  '@esbuild/win32-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/win32-arm64@0.25.10':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.3':
     optional: true
 
-  '@esbuild/win32-arm64@0.25.10':
+  '@esbuild/win32-arm64@0.28.1':
     optional: true
 
   '@esbuild/win32-ia32@0.21.5':
@@ -8584,47 +11302,23 @@ snapshots:
   '@esbuild/win32-ia32@0.25.10':
     optional: true
 
+  '@esbuild/win32-ia32@0.27.3':
+    optional: true
+
+  '@esbuild/win32-ia32@0.28.1':
+    optional: true
+
   '@esbuild/win32-x64@0.21.5':
     optional: true
 
   '@esbuild/win32-x64@0.25.10':
     optional: true
 
-  '@eventcatalog/generator-ai@1.2.0(@langchain/core@0.3.78(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76)))(@opentelemetry/api@1.9.0)(@types/node@20.19.19)(axios@1.12.2)(ws@8.18.3)(zod@3.25.76)':
-    dependencies:
-      '@eventcatalog/sdk': 2.9.2(@types/node@20.19.19)
-      '@huggingface/transformers': 3.7.5
-      chalk: 4.1.2
-      fs-extra: 11.3.2
-      langchain: 0.3.35(@langchain/core@0.3.78(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76)))(@opentelemetry/api@1.9.0)(axios@1.12.2)(openai@4.104.0(ws@8.18.3)(zod@3.25.76))(ws@8.18.3)
-      openai: 4.104.0(ws@8.18.3)(zod@3.25.76)
-      update-notifier: 7.3.1
-    transitivePeerDependencies:
-      - '@langchain/anthropic'
-      - '@langchain/aws'
-      - '@langchain/cerebras'
-      - '@langchain/cohere'
-      - '@langchain/core'
-      - '@langchain/deepseek'
-      - '@langchain/google-genai'
-      - '@langchain/google-vertexai'
-      - '@langchain/google-vertexai-web'
-      - '@langchain/groq'
-      - '@langchain/mistralai'
-      - '@langchain/ollama'
-      - '@langchain/xai'
-      - '@opentelemetry/api'
-      - '@opentelemetry/exporter-trace-otlp-proto'
-      - '@opentelemetry/sdk-trace-base'
-      - '@types/node'
-      - axios
-      - cheerio
-      - encoding
-      - handlebars
-      - peggy
-      - typeorm
-      - ws
-      - zod
+  '@esbuild/win32-x64@0.27.3':
+    optional: true
+
+  '@esbuild/win32-x64@0.28.1':
+    optional: true
 
   '@eventcatalog/license@0.0.7':
     dependencies:
@@ -8635,64 +11329,55 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@eventcatalog/linter@0.0.2':
-    dependencies:
-      '@types/semver': 7.7.1
-      chalk: 5.6.2
-      commander: 11.1.0
-      fast-glob: 3.3.3
-      gray-matter: 4.0.3
-      ora: 8.2.0
-      semver: 7.7.3
-      zod: 3.25.76
-
-  '@eventcatalog/sdk@2.9.2(@types/node@20.19.19)':
-    dependencies:
-      '@changesets/cli': 2.29.7(@types/node@20.19.19)
-      fs-extra: 11.3.2
-      glob: 11.0.3
-      gray-matter: 4.0.3
-      proper-lockfile: 4.1.2
-      semver: 7.6.3
-      slugify: 1.6.6
-    transitivePeerDependencies:
-      - '@types/node'
-
-  '@eventcatalog/visualizer@0.0.6(@types/react@18.3.26)(immer@9.0.21)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@expressive-code/core@0.41.7':
     dependencies:
-      '@xyflow/react': 12.8.6(@types/react@18.3.26)(immer@9.0.21)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      lucide-react: 0.510.0(react@18.3.1)
-      marked: 16.4.0
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-    transitivePeerDependencies:
-      - '@types/react'
-      - immer
+      '@ctrl/tinycolor': 4.2.0
+      hast-util-select: 6.0.4
+      hast-util-to-html: 9.0.5
+      hast-util-to-text: 4.0.2
+      hastscript: 9.0.1
+      postcss: 8.5.15
+      postcss-nested: 6.2.0(postcss@8.5.15)
+      unist-util-visit: 5.1.0
+      unist-util-visit-parents: 6.0.2
 
-  '@expressive-code/core@0.41.3':
+  '@expressive-code/core@0.44.0':
     dependencies:
       '@ctrl/tinycolor': 4.2.0
       hast-util-select: 6.0.4
       hast-util-to-html: 9.0.5
       hast-util-to-text: 4.0.2
       hastscript: 9.0.1
-      postcss: 8.5.6
-      postcss-nested: 6.2.0(postcss@8.5.6)
-      unist-util-visit: 5.0.0
-      unist-util-visit-parents: 6.0.1
+      postcss: 8.5.15
+      postcss-nested: 6.2.0(postcss@8.5.15)
+      unist-util-visit: 5.1.0
+      unist-util-visit-parents: 6.0.2
+
+  '@expressive-code/plugin-frames@0.41.7':
+    dependencies:
+      '@expressive-code/core': 0.41.7
+
+  '@expressive-code/plugin-frames@0.44.0':
+    dependencies:
+      '@expressive-code/core': 0.44.0
+
+  '@expressive-code/plugin-shiki@0.41.7':
+    dependencies:
+      '@expressive-code/core': 0.41.7
+      shiki: 3.21.0
 
-  '@expressive-code/plugin-frames@0.41.3':
+  '@expressive-code/plugin-shiki@0.44.0':
     dependencies:
-      '@expressive-code/core': 0.41.3
+      '@expressive-code/core': 0.44.0
+      shiki: 4.0.2
 
-  '@expressive-code/plugin-shiki@0.41.3':
+  '@expressive-code/plugin-text-markers@0.41.7':
     dependencies:
-      '@expressive-code/core': 0.41.3
-      shiki: 3.13.0
+      '@expressive-code/core': 0.41.7
 
-  '@expressive-code/plugin-text-markers@0.41.3':
+  '@expressive-code/plugin-text-markers@0.44.0':
     dependencies:
-      '@expressive-code/core': 0.41.3
+      '@expressive-code/core': 0.44.0
 
   '@floating-ui/core@1.7.3':
     dependencies:
@@ -8719,11 +11404,11 @@ snapshots:
 
   '@floating-ui/utils@0.2.10': {}
 
-  '@floating-ui/vue@1.1.9(vue@3.5.22(typescript@5.9.3))':
+  '@floating-ui/vue@1.1.9(vue@3.5.32(typescript@5.9.3))':
     dependencies:
       '@floating-ui/dom': 1.7.4
       '@floating-ui/utils': 0.2.10
-      vue-demi: 0.14.10(vue@3.5.22(typescript@5.9.3))
+      vue-demi: 0.14.10(vue@3.5.32(typescript@5.9.3))
     transitivePeerDependencies:
       - '@vue/composition-api'
       - vue
@@ -8740,51 +11425,22 @@ snapshots:
       react-dom: 18.3.1(react@18.3.1)
       use-sync-external-store: 1.6.0(react@18.3.1)
 
-  '@headlessui/tailwindcss@0.2.2(tailwindcss@3.4.18(yaml@2.8.1))':
+  '@headlessui/tailwindcss@0.2.2(tailwindcss@4.3.1)':
     dependencies:
-      tailwindcss: 3.4.18(yaml@2.8.1)
+      tailwindcss: 4.3.1
 
-  '@headlessui/vue@1.7.23(vue@3.5.22(typescript@5.9.3))':
+  '@headlessui/vue@1.7.23(vue@3.5.32(typescript@5.9.3))':
     dependencies:
-      '@tanstack/vue-virtual': 3.13.12(vue@3.5.22(typescript@5.9.3))
-      vue: 3.5.22(typescript@5.9.3)
+      '@tanstack/vue-virtual': 3.13.12(vue@3.5.32(typescript@5.9.3))
+      vue: 3.5.32(typescript@5.9.3)
 
   '@heroicons/react@2.2.0(react@18.3.1)':
     dependencies:
       react: 18.3.1
 
-  '@huggingface/jinja@0.5.1': {}
-
-  '@huggingface/transformers@3.7.5':
-    dependencies:
-      '@huggingface/jinja': 0.5.1
-      onnxruntime-node: 1.21.0
-      onnxruntime-web: 1.22.0-dev.20250409-89f8206ba4
-      sharp: 0.34.4
-
-  '@hyperjump/browser@1.3.1':
-    dependencies:
-      '@hyperjump/json-pointer': 1.1.1
-      '@hyperjump/uri': 1.3.2
-      content-type: 1.0.5
-      just-curry-it: 5.3.0
-
-  '@hyperjump/json-pointer@1.1.1': {}
-
-  '@hyperjump/json-schema@1.16.3(@hyperjump/browser@1.3.1)':
+  '@hono/node-server@1.19.9(hono@4.12.25)':
     dependencies:
-      '@hyperjump/browser': 1.3.1
-      '@hyperjump/json-pointer': 1.1.1
-      '@hyperjump/pact': 1.4.0
-      '@hyperjump/uri': 1.3.2
-      content-type: 1.0.5
-      json-stringify-deterministic: 1.0.12
-      just-curry-it: 5.3.0
-      uuid: 9.0.1
-
-  '@hyperjump/pact@1.4.0': {}
-
-  '@hyperjump/uri@1.3.2': {}
+      hono: 4.12.25
 
   '@iconify-json/logos@1.2.9':
     dependencies:
@@ -8807,19 +11463,14 @@ snapshots:
 
   '@img/colour@1.0.0': {}
 
-  '@img/sharp-darwin-arm64@0.33.5':
-    optionalDependencies:
-      '@img/sharp-libvips-darwin-arm64': 1.0.4
-    optional: true
-
   '@img/sharp-darwin-arm64@0.34.4':
     optionalDependencies:
       '@img/sharp-libvips-darwin-arm64': 1.2.3
     optional: true
 
-  '@img/sharp-darwin-x64@0.33.5':
+  '@img/sharp-darwin-arm64@0.34.5':
     optionalDependencies:
-      '@img/sharp-libvips-darwin-x64': 1.0.4
+      '@img/sharp-libvips-darwin-arm64': 1.2.4
     optional: true
 
   '@img/sharp-darwin-x64@0.34.4':
@@ -8827,60 +11478,66 @@ snapshots:
       '@img/sharp-libvips-darwin-x64': 1.2.3
     optional: true
 
-  '@img/sharp-libvips-darwin-arm64@1.0.4':
+  '@img/sharp-darwin-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-darwin-x64': 1.2.4
     optional: true
 
   '@img/sharp-libvips-darwin-arm64@1.2.3':
     optional: true
 
-  '@img/sharp-libvips-darwin-x64@1.0.4':
+  '@img/sharp-libvips-darwin-arm64@1.2.4':
     optional: true
 
   '@img/sharp-libvips-darwin-x64@1.2.3':
     optional: true
 
-  '@img/sharp-libvips-linux-arm64@1.0.4':
+  '@img/sharp-libvips-darwin-x64@1.2.4':
     optional: true
 
   '@img/sharp-libvips-linux-arm64@1.2.3':
     optional: true
 
-  '@img/sharp-libvips-linux-arm@1.0.5':
+  '@img/sharp-libvips-linux-arm64@1.2.4':
     optional: true
 
   '@img/sharp-libvips-linux-arm@1.2.3':
     optional: true
 
+  '@img/sharp-libvips-linux-arm@1.2.4':
+    optional: true
+
   '@img/sharp-libvips-linux-ppc64@1.2.3':
     optional: true
 
-  '@img/sharp-libvips-linux-s390x@1.0.4':
+  '@img/sharp-libvips-linux-ppc64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-riscv64@1.2.4':
     optional: true
 
   '@img/sharp-libvips-linux-s390x@1.2.3':
     optional: true
 
-  '@img/sharp-libvips-linux-x64@1.0.4':
+  '@img/sharp-libvips-linux-s390x@1.2.4':
     optional: true
 
   '@img/sharp-libvips-linux-x64@1.2.3':
     optional: true
 
-  '@img/sharp-libvips-linuxmusl-arm64@1.0.4':
+  '@img/sharp-libvips-linux-x64@1.2.4':
     optional: true
 
   '@img/sharp-libvips-linuxmusl-arm64@1.2.3':
     optional: true
 
-  '@img/sharp-libvips-linuxmusl-x64@1.0.4':
+  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
     optional: true
 
   '@img/sharp-libvips-linuxmusl-x64@1.2.3':
     optional: true
 
-  '@img/sharp-linux-arm64@0.33.5':
-    optionalDependencies:
-      '@img/sharp-libvips-linux-arm64': 1.0.4
+  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
     optional: true
 
   '@img/sharp-linux-arm64@0.34.4':
@@ -8888,9 +11545,9 @@ snapshots:
       '@img/sharp-libvips-linux-arm64': 1.2.3
     optional: true
 
-  '@img/sharp-linux-arm@0.33.5':
+  '@img/sharp-linux-arm64@0.34.5':
     optionalDependencies:
-      '@img/sharp-libvips-linux-arm': 1.0.5
+      '@img/sharp-libvips-linux-arm64': 1.2.4
     optional: true
 
   '@img/sharp-linux-arm@0.34.4':
@@ -8898,14 +11555,24 @@ snapshots:
       '@img/sharp-libvips-linux-arm': 1.2.3
     optional: true
 
+  '@img/sharp-linux-arm@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm': 1.2.4
+    optional: true
+
   '@img/sharp-linux-ppc64@0.34.4':
     optionalDependencies:
       '@img/sharp-libvips-linux-ppc64': 1.2.3
     optional: true
 
-  '@img/sharp-linux-s390x@0.33.5':
+  '@img/sharp-linux-ppc64@0.34.5':
     optionalDependencies:
-      '@img/sharp-libvips-linux-s390x': 1.0.4
+      '@img/sharp-libvips-linux-ppc64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-riscv64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-riscv64': 1.2.4
     optional: true
 
   '@img/sharp-linux-s390x@0.34.4':
@@ -8913,9 +11580,9 @@ snapshots:
       '@img/sharp-libvips-linux-s390x': 1.2.3
     optional: true
 
-  '@img/sharp-linux-x64@0.33.5':
+  '@img/sharp-linux-s390x@0.34.5':
     optionalDependencies:
-      '@img/sharp-libvips-linux-x64': 1.0.4
+      '@img/sharp-libvips-linux-s390x': 1.2.4
     optional: true
 
   '@img/sharp-linux-x64@0.34.4':
@@ -8923,9 +11590,9 @@ snapshots:
       '@img/sharp-libvips-linux-x64': 1.2.3
     optional: true
 
-  '@img/sharp-linuxmusl-arm64@0.33.5':
+  '@img/sharp-linux-x64@0.34.5':
     optionalDependencies:
-      '@img/sharp-libvips-linuxmusl-arm64': 1.0.4
+      '@img/sharp-libvips-linux-x64': 1.2.4
     optional: true
 
   '@img/sharp-linuxmusl-arm64@0.34.4':
@@ -8933,9 +11600,9 @@ snapshots:
       '@img/sharp-libvips-linuxmusl-arm64': 1.2.3
     optional: true
 
-  '@img/sharp-linuxmusl-x64@0.33.5':
+  '@img/sharp-linuxmusl-arm64@0.34.5':
     optionalDependencies:
-      '@img/sharp-libvips-linuxmusl-x64': 1.0.4
+      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
     optional: true
 
   '@img/sharp-linuxmusl-x64@0.34.4':
@@ -8943,9 +11610,9 @@ snapshots:
       '@img/sharp-libvips-linuxmusl-x64': 1.2.3
     optional: true
 
-  '@img/sharp-wasm32@0.33.5':
-    dependencies:
-      '@emnapi/runtime': 1.5.0
+  '@img/sharp-linuxmusl-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
     optional: true
 
   '@img/sharp-wasm32@0.34.4':
@@ -8953,27 +11620,35 @@ snapshots:
       '@emnapi/runtime': 1.5.0
     optional: true
 
+  '@img/sharp-wasm32@0.34.5':
+    dependencies:
+      '@emnapi/runtime': 1.10.0
+    optional: true
+
   '@img/sharp-win32-arm64@0.34.4':
     optional: true
 
-  '@img/sharp-win32-ia32@0.33.5':
+  '@img/sharp-win32-arm64@0.34.5':
     optional: true
 
   '@img/sharp-win32-ia32@0.34.4':
     optional: true
 
-  '@img/sharp-win32-x64@0.33.5':
+  '@img/sharp-win32-ia32@0.34.5':
     optional: true
 
   '@img/sharp-win32-x64@0.34.4':
     optional: true
 
-  '@inquirer/external-editor@1.0.2(@types/node@20.19.19)':
+  '@img/sharp-win32-x64@0.34.5':
+    optional: true
+
+  '@inquirer/external-editor@1.0.2(@types/node@25.0.3)':
     dependencies:
       chardet: 2.1.0
       iconv-lite: 0.7.0
     optionalDependencies:
-      '@types/node': 20.19.19
+      '@types/node': 25.0.3
 
   '@internationalized/date@3.10.0':
     dependencies:
@@ -8985,7 +11660,7 @@ snapshots:
 
   '@isaacs/balanced-match@4.0.1': {}
 
-  '@isaacs/brace-expansion@5.0.0':
+  '@isaacs/brace-expansion@5.0.1':
     dependencies:
       '@isaacs/balanced-match': 4.0.1
 
@@ -8998,10 +11673,6 @@ snapshots:
       wrap-ansi: 8.1.0
       wrap-ansi-cjs: wrap-ansi@7.0.0
 
-  '@isaacs/fs-minipass@4.0.1':
-    dependencies:
-      minipass: 7.1.2
-
   '@jridgewell/gen-mapping@0.3.13':
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
@@ -9040,39 +11711,13 @@ snapshots:
 
   '@juggle/resize-observer@3.4.0': {}
 
-  '@langchain/core@0.3.78(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76))':
-    dependencies:
-      '@cfworker/json-schema': 4.1.1
-      ansi-styles: 5.2.0
-      camelcase: 6.3.0
-      decamelize: 1.2.0
-      js-tiktoken: 1.0.21
-      langsmith: 0.3.73(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76))
-      mustache: 4.2.0
-      p-queue: 6.6.2
-      p-retry: 4.6.2
-      uuid: 10.0.0
-      zod: 3.25.76
-      zod-to-json-schema: 3.24.6(zod@3.25.76)
-    transitivePeerDependencies:
-      - '@opentelemetry/api'
-      - '@opentelemetry/exporter-trace-otlp-proto'
-      - '@opentelemetry/sdk-trace-base'
-      - openai
-
-  '@langchain/openai@0.6.14(@langchain/core@0.3.78(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76)))(ws@8.18.3)':
+  '@kwsites/file-exists@1.1.1':
     dependencies:
-      '@langchain/core': 0.3.78(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76))
-      js-tiktoken: 1.0.21
-      openai: 5.12.2(ws@8.18.3)(zod@3.25.76)
-      zod: 3.25.76
+      debug: 4.4.3
     transitivePeerDependencies:
-      - ws
+      - supports-color
 
-  '@langchain/textsplitters@0.1.0(@langchain/core@0.3.78(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76)))':
-    dependencies:
-      '@langchain/core': 0.3.78(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76))
-      js-tiktoken: 1.0.21
+  '@kwsites/promise-deferred@1.1.1': {}
 
   '@lezer/common@1.2.3': {}
 
@@ -9144,7 +11789,7 @@ snapshots:
       '@types/estree-jsx': 1.0.5
       '@types/hast': 3.0.4
       '@types/mdx': 2.0.13
-      acorn: 8.15.0
+      acorn: 8.16.0
       collapse-white-space: 2.1.0
       devlop: 1.1.0
       estree-util-is-identifier-name: 3.0.0
@@ -9153,7 +11798,7 @@ snapshots:
       hast-util-to-jsx-runtime: 2.3.6
       markdown-extensions: 2.0.0
       recma-build-jsx: 1.0.0
-      recma-jsx: 1.0.1(acorn@8.15.0)
+      recma-jsx: 1.0.1(acorn@8.16.0)
       recma-stringify: 1.0.0
       rehype-recma: 1.0.0
       remark-mdx: 3.1.1
@@ -9163,20 +11808,90 @@ snapshots:
       unified: 11.0.5
       unist-util-position-from-estree: 2.0.0
       unist-util-stringify-position: 4.0.0
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
       vfile: 6.0.3
     transitivePeerDependencies:
       - supports-color
 
-  '@mermaid-js/layout-elk@0.2.0(mermaid@11.12.0)':
+  '@mermaid-js/layout-elk@0.2.0(mermaid@11.12.3)':
     dependencies:
       d3: 7.9.0
       elkjs: 0.9.3
-      mermaid: 11.12.0
+      mermaid: 11.12.3
+
+  '@mermaid-js/parser@1.1.0':
+    dependencies:
+      langium: 4.2.1
+
+  '@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@4.3.6)':
+    dependencies:
+      '@hono/node-server': 1.19.9(hono@4.12.25)
+      ajv: 8.17.1
+      ajv-formats: 3.0.1(ajv@8.17.1)
+      content-type: 1.0.5
+      cors: 2.8.5
+      cross-spawn: 7.0.6
+      eventsource: 3.0.7
+      eventsource-parser: 3.0.6
+      express: 5.2.1
+      express-rate-limit: 8.2.1(express@5.2.1)
+      hono: 4.12.25
+      jose: 6.1.3
+      json-schema-typed: 8.0.2
+      pkce-challenge: 5.0.1
+      raw-body: 3.0.2
+      zod: 4.3.6
+      zod-to-json-schema: 3.25.1(zod@4.3.6)
+    optionalDependencies:
+      '@cfworker/json-schema': 4.1.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@monaco-editor/loader@1.7.0':
+    dependencies:
+      state-local: 1.0.7
+
+  '@monaco-editor/react@4.7.0(monaco-editor@0.55.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@monaco-editor/loader': 1.7.0
+      monaco-editor: 0.55.1
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
 
-  '@mermaid-js/parser@0.6.3':
+  '@nanostores/persistent@1.3.3(nanostores@1.1.0)':
     dependencies:
-      langium: 3.3.1
+      nanostores: 1.1.0
+
+  '@nanostores/react@1.0.0(nanostores@1.1.0)(react@18.3.1)':
+    dependencies:
+      nanostores: 1.1.0
+      react: 18.3.1
+
+  '@nanostores/react@1.0.0(nanostores@1.1.0)(react@19.2.4)':
+    dependencies:
+      nanostores: 1.1.0
+      react: 19.2.4
+
+  '@napi-rs/wasm-runtime@1.1.5(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)':
+    dependencies:
+      '@emnapi/core': 1.11.1
+      '@emnapi/runtime': 1.11.1
+      '@tybys/wasm-util': 0.10.2
+    optional: true
+
+  '@napi-rs/wasm-runtime@1.1.5(@emnapi/core@1.9.1)(@emnapi/runtime@1.9.1)':
+    dependencies:
+      '@emnapi/core': 1.9.1
+      '@emnapi/runtime': 1.9.1
+      '@tybys/wasm-util': 0.10.2
+    optional: true
+
+  '@napi-rs/wasm-runtime@1.1.6(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)':
+    dependencies:
+      '@emnapi/core': 1.11.1
+      '@emnapi/runtime': 1.11.1
+      '@tybys/wasm-util': 0.10.3
+    optional: true
 
   '@nodelib/fs.scandir@2.1.5':
     dependencies:
@@ -9198,24 +11913,49 @@ snapshots:
 
   '@oslojs/encoding@1.1.0': {}
 
+  '@oxc-project/types@0.137.0': {}
+
   '@pagefind/darwin-arm64@1.4.0':
     optional: true
 
+  '@pagefind/darwin-arm64@1.5.2':
+    optional: true
+
   '@pagefind/darwin-x64@1.4.0':
     optional: true
 
+  '@pagefind/darwin-x64@1.5.2':
+    optional: true
+
+  '@pagefind/default-ui@1.4.0': {}
+
   '@pagefind/freebsd-x64@1.4.0':
     optional: true
 
+  '@pagefind/freebsd-x64@1.5.2':
+    optional: true
+
   '@pagefind/linux-arm64@1.4.0':
     optional: true
 
+  '@pagefind/linux-arm64@1.5.2':
+    optional: true
+
   '@pagefind/linux-x64@1.4.0':
     optional: true
 
+  '@pagefind/linux-x64@1.5.2':
+    optional: true
+
+  '@pagefind/windows-arm64@1.5.2':
+    optional: true
+
   '@pagefind/windows-x64@1.4.0':
     optional: true
 
+  '@pagefind/windows-x64@1.5.2':
+    optional: true
+
   '@panva/hkdf@1.2.1': {}
 
   '@parcel/watcher-android-arm64@2.5.1':
@@ -9278,19 +12018,22 @@ snapshots:
       '@parcel/watcher-win32-ia32': 2.5.1
       '@parcel/watcher-win32-x64': 2.5.1
 
+  '@phosphor-icons/core@2.1.1': {}
+
+  '@pivanov/utils@0.0.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+
   '@pkgjs/parseargs@0.11.0':
     optional: true
 
-  '@playform/pipe@0.1.3':
+  '@playform/pipe@0.1.4':
     dependencies:
-      '@types/node': 22.13.14
+      '@types/node': 25.0.3
       deepmerge-ts: 7.1.5
       fast-glob: 3.3.3
 
-  '@playwright/test@1.56.0':
-    dependencies:
-      playwright: 1.56.0
-
   '@pnpm/config.env-replace@1.1.0': {}
 
   '@pnpm/network.ca-file@1.0.2':
@@ -9303,7 +12046,16 @@ snapshots:
       '@pnpm/network.ca-file': 1.0.2
       config-chain: 1.1.13
 
-  '@popperjs/core@2.11.8': {}
+  '@preact/signals-core@1.13.0': {}
+
+  '@preact/signals@1.3.4(preact@10.28.3)':
+    dependencies:
+      '@preact/signals-core': 1.13.0
+      preact: 10.28.3
+
+  '@profoundlogic/hogan@3.0.4':
+    dependencies:
+      nopt: 1.0.10
 
   '@protobufjs/aspromise@1.1.2': {}
 
@@ -9330,306 +12082,470 @@ snapshots:
 
   '@radix-ui/primitive@1.1.3': {}
 
-  '@radix-ui/react-arrow@1.1.7(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-arrow@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-collection@1.1.7(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-collection@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-compose-refs': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.3(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-compose-refs@1.1.2(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-compose-refs@1.1.2(@types/react@19.2.13)(react@18.3.1)':
     dependencies:
       react: 18.3.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-context-menu@2.2.16(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-compose-refs@1.1.2(@types/react@19.2.13)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.13
+
+  '@radix-ui/react-context-menu@2.2.16(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@radix-ui/primitive': 1.1.3
-      '@radix-ui/react-context': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-menu': 2.1.16(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-menu': 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-context@1.1.2(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-context@1.1.2(@types/react@19.2.13)(react@18.3.1)':
     dependencies:
       react: 18.3.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
+
+  '@radix-ui/react-context@1.1.2(@types/react@19.2.13)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-dialog@1.1.15(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-dialog@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@radix-ui/primitive': 1.1.3
-      '@radix-ui/react-compose-refs': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-focus-guards': 1.1.3(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.5(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.3(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.13)(react@18.3.1)
       aria-hidden: 1.2.6
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
-      react-remove-scroll: 2.7.1(@types/react@18.3.26)(react@18.3.1)
+      react-remove-scroll: 2.7.1(@types/react@19.2.13)(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
+
+  '@radix-ui/react-dialog@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.13)(react@19.2.4)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.13)(react@19.2.4)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.13)(react@19.2.4)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.13)(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.13)(react@19.2.4)
+      aria-hidden: 1.2.6
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      react-remove-scroll: 2.7.1(@types/react@19.2.13)(react@19.2.4)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-direction@1.1.1(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-direction@1.1.1(@types/react@19.2.13)(react@18.3.1)':
     dependencies:
       react: 18.3.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-dismissable-layer@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-dismissable-layer@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@radix-ui/primitive': 1.1.3
-      '@radix-ui/react-compose-refs': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-use-escape-keydown': 1.1.1(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-use-escape-keydown': 1.1.1(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
+
+  '@radix-ui/react-dismissable-layer@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.13)(react@19.2.4)
+      '@radix-ui/react-use-escape-keydown': 1.1.1(@types/react@19.2.13)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-dropdown-menu@2.1.16(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-dropdown-menu@2.1.16(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@radix-ui/primitive': 1.1.3
-      '@radix-ui/react-compose-refs': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-menu': 2.1.16(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-menu': 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-focus-guards@1.1.3(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-focus-guards@1.1.3(@types/react@19.2.13)(react@18.3.1)':
     dependencies:
       react: 18.3.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
+
+  '@radix-ui/react-focus-guards@1.1.3(@types/react@19.2.13)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-focus-scope@1.1.7(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-focus-scope@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-compose-refs': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
+
+  '@radix-ui/react-focus-scope@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.13)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
+
+  '@radix-ui/react-id@1.1.1(@types/react@19.2.13)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 19.2.13
+
+  '@radix-ui/react-id@1.1.1(@types/react@19.2.13)(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.13)(react@19.2.4)
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-id@1.1.1(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-menu@2.1.16(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      aria-hidden: 1.2.6
       react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      react-remove-scroll: 2.7.1(@types/react@19.2.13)(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-menu@2.1.16(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@radix-ui/primitive': 1.1.3
-      '@radix-ui/react-collection': 1.1.7(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-focus-guards': 1.1.3(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-popper': 1.2.8(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.5(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.3(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.13)(react@18.3.1)
       aria-hidden: 1.2.6
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
-      react-remove-scroll: 2.7.1(@types/react@18.3.26)(react@18.3.1)
+      react-remove-scroll: 2.7.1(@types/react@19.2.13)(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-popper@1.2.8(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-popper@1.2.8(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@floating-ui/react-dom': 2.1.6(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-arrow': 1.1.7(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-use-rect': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-use-size': 1.1.1(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-arrow': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-use-rect': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.13)(react@18.3.1)
       '@radix-ui/rect': 1.1.1
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-portal@1.1.9(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-portal@1.1.9(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
+
+  '@radix-ui/react-portal@1.1.9(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.13)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-presence@1.1.5(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-presence@1.1.5(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-compose-refs': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
+
+  '@radix-ui/react-presence@1.1.5(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.13)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-primitive@2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-primitive@2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-slot': 1.2.3(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
+
+  '@radix-ui/react-primitive@2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.13)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-roving-focus@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-roving-focus@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@radix-ui/primitive': 1.1.3
-      '@radix-ui/react-collection': 1.1.7(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-compose-refs': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-direction': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-id': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-slot@1.2.3(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-slot@1.2.3(@types/react@19.2.13)(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-compose-refs': 1.1.2(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-tooltip@1.2.8(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-slot@1.2.3(@types/react@19.2.13)(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@19.2.4)
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.13
+
+  '@radix-ui/react-tooltip@1.2.8(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@radix-ui/primitive': 1.1.3
-      '@radix-ui/react-compose-refs': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-context': 1.1.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-id': 1.1.1(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-popper': 1.2.8(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-portal': 1.1.9(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-presence': 1.1.5(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      '@radix-ui/react-slot': 1.2.3(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
-  '@radix-ui/react-use-callback-ref@1.1.1(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-use-callback-ref@1.1.1(@types/react@19.2.13)(react@18.3.1)':
     dependencies:
       react: 18.3.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
+
+  '@radix-ui/react-use-callback-ref@1.1.1(@types/react@19.2.13)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-use-controllable-state@1.2.2(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-use-controllable-state@1.2.2(@types/react@19.2.13)(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-use-effect-event': 0.0.2(@types/react@18.3.26)(react@18.3.1)
-      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-use-effect-event': 0.0.2(@types/react@19.2.13)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
+
+  '@radix-ui/react-use-controllable-state@1.2.2(@types/react@19.2.13)(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-use-effect-event': 0.0.2(@types/react@19.2.13)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.13)(react@19.2.4)
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-use-effect-event@0.0.2(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-use-effect-event@0.0.2(@types/react@19.2.13)(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
+
+  '@radix-ui/react-use-effect-event@0.0.2(@types/react@19.2.13)(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.13)(react@19.2.4)
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-use-escape-keydown@1.1.1(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-use-escape-keydown@1.1.1(@types/react@19.2.13)(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-use-layout-effect@1.1.1(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-use-escape-keydown@1.1.1(@types/react@19.2.13)(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.13)(react@19.2.4)
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.13
+
+  '@radix-ui/react-use-layout-effect@1.1.1(@types/react@19.2.13)(react@18.3.1)':
     dependencies:
       react: 18.3.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
+
+  '@radix-ui/react-use-layout-effect@1.1.1(@types/react@19.2.13)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-use-rect@1.1.1(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-use-rect@1.1.1(@types/react@19.2.13)(react@18.3.1)':
     dependencies:
       '@radix-ui/rect': 1.1.1
       react: 18.3.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-use-size@1.1.1(@types/react@18.3.26)(react@18.3.1)':
+  '@radix-ui/react-use-size@1.1.1(@types/react@19.2.13)(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@18.3.26)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.13)(react@18.3.1)
       react: 18.3.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
 
-  '@radix-ui/react-visually-hidden@1.2.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@radix-ui/react-visually-hidden@1.2.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@18.3.7(@types/react@18.3.26))(@types/react@18.3.26)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
-      '@types/react-dom': 18.3.7(@types/react@18.3.26)
+      '@types/react': 19.2.13
+      '@types/react-dom': 19.2.3(@types/react@19.2.13)
 
   '@radix-ui/rect@1.1.1': {}
 
@@ -9688,13 +12604,66 @@ snapshots:
       '@codemirror/state': 6.5.2
       '@codemirror/view': 6.38.5
 
+  '@rolldown/binding-android-arm64@1.1.3':
+    optional: true
+
+  '@rolldown/binding-darwin-arm64@1.1.3':
+    optional: true
+
+  '@rolldown/binding-darwin-x64@1.1.3':
+    optional: true
+
+  '@rolldown/binding-freebsd-x64@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-gnu@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-musl@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-ppc64-gnu@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-s390x-gnu@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-x64-gnu@1.1.3':
+    optional: true
+
+  '@rolldown/binding-linux-x64-musl@1.1.3':
+    optional: true
+
+  '@rolldown/binding-openharmony-arm64@1.1.3':
+    optional: true
+
+  '@rolldown/binding-wasm32-wasi@1.1.3':
+    dependencies:
+      '@emnapi/core': 1.11.1
+      '@emnapi/runtime': 1.11.1
+      '@napi-rs/wasm-runtime': 1.1.6(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)
+    optional: true
+
+  '@rolldown/binding-win32-arm64-msvc@1.1.3':
+    optional: true
+
+  '@rolldown/binding-win32-x64-msvc@1.1.3':
+    optional: true
+
   '@rolldown/pluginutils@1.0.0-beta.27': {}
 
+  '@rolldown/pluginutils@1.0.0-rc.3': {}
+
+  '@rolldown/pluginutils@1.0.1': {}
+
   '@rollup/pluginutils@5.3.0(rollup@4.52.4)':
     dependencies:
       '@types/estree': 1.0.8
       estree-walker: 2.0.2
-      picomatch: 4.0.3
+      picomatch: 4.0.4
     optionalDependencies:
       rollup: 4.52.4
 
@@ -9764,42 +12733,79 @@ snapshots:
   '@rollup/rollup-win32-x64-msvc@4.52.4':
     optional: true
 
-  '@scalar/api-client@2.2.62(@hyperjump/browser@1.3.1)(axios@1.12.2)(tailwindcss@3.4.18(yaml@2.8.1))(typescript@5.9.3)':
-    dependencies:
-      '@headlessui/tailwindcss': 0.2.2(tailwindcss@3.4.18(yaml@2.8.1))
-      '@headlessui/vue': 1.7.23(vue@3.5.22(typescript@5.9.3))
-      '@scalar/components': 0.13.33(typescript@5.9.3)
-      '@scalar/draggable': 0.1.11(typescript@5.9.3)
-      '@scalar/icons': 0.1.3(typescript@5.9.3)
-      '@scalar/import': 0.2.36(@hyperjump/browser@1.3.1)
-      '@scalar/oas-utils': 0.2.116(@hyperjump/browser@1.3.1)
-      '@scalar/object-utils': 1.1.13
-      '@scalar/openapi-parser': 0.10.10
-      '@scalar/openapi-types': 0.1.9
-      '@scalar/postman-to-openapi': 0.1.39(@hyperjump/browser@1.3.1)
-      '@scalar/snippetz': 0.2.16
-      '@scalar/themes': 0.9.75
-      '@scalar/types': 0.0.40
-      '@scalar/use-codemirror': 0.11.78(typescript@5.9.3)
-      '@scalar/use-hooks': 0.1.29(typescript@5.9.3)
-      '@scalar/use-toasts': 0.7.9(typescript@5.9.3)
-      '@scalar/use-tooltip': 1.0.6(typescript@5.9.3)
-      '@vueuse/core': 10.11.1(vue@3.5.22(typescript@5.9.3))
-      '@vueuse/integrations': 11.3.0(axios@1.12.2)(focus-trap@7.6.5)(fuse.js@7.1.0)(vue@3.5.22(typescript@5.9.3))
-      focus-trap: 7.6.5
+  '@scalar/agent-chat@0.12.0(axios@1.15.2)(tailwindcss@4.3.1)(typescript@5.9.3)(zod@4.3.6)':
+    dependencies:
+      '@ai-sdk/vue': 3.0.33(vue@3.5.32(typescript@5.9.3))(zod@4.3.6)
+      '@scalar/api-client': 3.8.0(axios@1.15.2)(tailwindcss@4.3.1)(typescript@5.9.3)
+      '@scalar/components': 0.24.4(tailwindcss@4.3.1)(typescript@5.9.3)
+      '@scalar/helpers': 0.8.0
+      '@scalar/icons': 0.7.2(typescript@5.9.3)
+      '@scalar/json-magic': 0.12.14
+      '@scalar/openapi-types': 0.8.0
+      '@scalar/schemas': 0.2.0
+      '@scalar/themes': 0.15.5
+      '@scalar/types': 0.11.0
+      '@scalar/use-toasts': 0.10.2(typescript@5.9.3)
+      '@scalar/validation': 0.5.0
+      '@scalar/workspace-store': 0.51.0(typescript@5.9.3)
+      '@vueuse/core': 13.9.0(vue@3.5.32(typescript@5.9.3))
+      ai: 6.0.33(zod@4.3.6)
+      js-base64: 3.7.8
+      neverpanic: 0.0.7(typescript@5.9.3)
+      truncate-json: 3.0.1
+      vue: 3.5.32(typescript@5.9.3)
+    transitivePeerDependencies:
+      - '@vue/composition-api'
+      - async-validator
+      - axios
+      - change-case
+      - drauu
+      - idb-keyval
+      - jwt-decode
+      - nprogress
+      - qrcode
+      - sortablejs
+      - supports-color
+      - tailwindcss
+      - typescript
+      - universal-cookie
+      - zod
+
+  '@scalar/api-client@3.8.0(axios@1.15.2)(tailwindcss@4.3.1)(typescript@5.9.3)':
+    dependencies:
+      '@headlessui/tailwindcss': 0.2.2(tailwindcss@4.3.1)
+      '@headlessui/vue': 1.7.23(vue@3.5.32(typescript@5.9.3))
+      '@scalar/components': 0.24.4(tailwindcss@4.3.1)(typescript@5.9.3)
+      '@scalar/helpers': 0.8.0
+      '@scalar/icons': 0.7.2(typescript@5.9.3)
+      '@scalar/json-magic': 0.12.14
+      '@scalar/oas-utils': 0.17.0(typescript@5.9.3)
+      '@scalar/openapi-types': 0.8.0
+      '@scalar/sidebar': 0.9.13(tailwindcss@4.3.1)(typescript@5.9.3)
+      '@scalar/snippetz': 0.9.8
+      '@scalar/themes': 0.15.5
+      '@scalar/typebox': 0.1.3
+      '@scalar/types': 0.11.0
+      '@scalar/use-codemirror': 0.14.11(typescript@5.9.3)
+      '@scalar/use-hooks': 0.4.5(typescript@5.9.3)
+      '@scalar/use-toasts': 0.10.2(typescript@5.9.3)
+      '@scalar/workspace-store': 0.51.0(typescript@5.9.3)
+      '@types/har-format': 1.2.16
+      '@vueuse/core': 13.9.0(vue@3.5.32(typescript@5.9.3))
+      '@vueuse/integrations': 13.9.0(axios@1.15.2)(focus-trap@7.8.0)(fuse.js@7.1.0)(vue@3.5.32(typescript@5.9.3))
+      cookie: 1.1.1
+      focus-trap: 7.8.0
       fuse.js: 7.1.0
-      microdiff: 1.5.0
+      js-base64: 3.7.8
+      jsonc-parser: 3.3.1
       nanoid: 5.1.6
-      pretty-bytes: 6.1.1
-      pretty-ms: 8.0.0
-      shell-quote: 1.8.3
-      vue: 3.5.22(typescript@5.9.3)
-      vue-router: 4.5.1(vue@3.5.22(typescript@5.9.3))
-      whatwg-mimetype: 4.0.0
-      yaml: 2.8.1
-      zod: 3.25.76
+      pretty-ms: 9.3.0
+      radix-vue: 1.9.17(vue@3.5.32(typescript@5.9.3))
+      set-cookie-parser: 3.1.0
+      vue: 3.5.32(typescript@5.9.3)
+      yaml: 2.9.0
+      zod: 4.3.6
     transitivePeerDependencies:
-      - '@hyperjump/browser'
       - '@vue/composition-api'
       - async-validator
       - axios
@@ -9815,13 +12821,12 @@ snapshots:
       - typescript
       - universal-cookie
 
-  '@scalar/api-reference-react@0.4.42(@hyperjump/browser@1.3.1)(axios@1.12.2)(react@18.3.1)(tailwindcss@3.4.18(yaml@2.8.1))(typescript@5.9.3)':
+  '@scalar/api-reference-react@0.9.36(axios@1.15.2)(react@18.3.1)(tailwindcss@4.3.1)(typescript@5.9.3)(zod@4.3.6)':
     dependencies:
-      '@scalar/api-reference': 1.26.2(@hyperjump/browser@1.3.1)(axios@1.12.2)(tailwindcss@3.4.18(yaml@2.8.1))(typescript@5.9.3)
-      '@scalar/types': 0.0.40
+      '@scalar/api-reference': 1.57.0(axios@1.15.2)(tailwindcss@4.3.1)(typescript@5.9.3)(zod@4.3.6)
+      '@scalar/types': 0.11.0
       react: 18.3.1
     transitivePeerDependencies:
-      - '@hyperjump/browser'
       - '@vue/composition-api'
       - async-validator
       - axios
@@ -9836,31 +12841,35 @@ snapshots:
       - tailwindcss
       - typescript
       - universal-cookie
+      - zod
 
-  '@scalar/api-reference@1.26.2(@hyperjump/browser@1.3.1)(axios@1.12.2)(tailwindcss@3.4.18(yaml@2.8.1))(typescript@5.9.3)':
-    dependencies:
-      '@floating-ui/vue': 1.1.9(vue@3.5.22(typescript@5.9.3))
-      '@headlessui/vue': 1.7.23(vue@3.5.22(typescript@5.9.3))
-      '@scalar/api-client': 2.2.62(@hyperjump/browser@1.3.1)(axios@1.12.2)(tailwindcss@3.4.18(yaml@2.8.1))(typescript@5.9.3)
-      '@scalar/code-highlight': 0.0.24
-      '@scalar/components': 0.13.33(typescript@5.9.3)
-      '@scalar/oas-utils': 0.2.116(@hyperjump/browser@1.3.1)
-      '@scalar/openapi-parser': 0.10.10
-      '@scalar/openapi-types': 0.1.9
-      '@scalar/snippetz': 0.2.16
-      '@scalar/themes': 0.9.75
-      '@scalar/types': 0.0.40
-      '@scalar/use-hooks': 0.1.29(typescript@5.9.3)
-      '@scalar/use-toasts': 0.7.9(typescript@5.9.3)
-      '@unhead/vue': 1.11.20(vue@3.5.22(typescript@5.9.3))
-      '@vueuse/core': 10.11.1(vue@3.5.22(typescript@5.9.3))
+  '@scalar/api-reference@1.57.0(axios@1.15.2)(tailwindcss@4.3.1)(typescript@5.9.3)(zod@4.3.6)':
+    dependencies:
+      '@headlessui/vue': 1.7.23(vue@3.5.32(typescript@5.9.3))
+      '@scalar/agent-chat': 0.12.0(axios@1.15.2)(tailwindcss@4.3.1)(typescript@5.9.3)(zod@4.3.6)
+      '@scalar/api-client': 3.8.0(axios@1.15.2)(tailwindcss@4.3.1)(typescript@5.9.3)
+      '@scalar/code-highlight': 0.3.4
+      '@scalar/components': 0.24.4(tailwindcss@4.3.1)(typescript@5.9.3)
+      '@scalar/helpers': 0.8.0
+      '@scalar/icons': 0.7.2(typescript@5.9.3)
+      '@scalar/oas-utils': 0.17.0(typescript@5.9.3)
+      '@scalar/schemas': 0.2.0
+      '@scalar/sidebar': 0.9.13(tailwindcss@4.3.1)(typescript@5.9.3)
+      '@scalar/snippetz': 0.9.8
+      '@scalar/themes': 0.15.5
+      '@scalar/types': 0.11.0
+      '@scalar/use-hooks': 0.4.5(typescript@5.9.3)
+      '@scalar/use-toasts': 0.10.2(typescript@5.9.3)
+      '@scalar/validation': 0.5.0
+      '@scalar/workspace-store': 0.51.0(typescript@5.9.3)
+      '@unhead/vue': 2.1.13(vue@3.5.32(typescript@5.9.3))
+      '@vueuse/core': 13.9.0(vue@3.5.32(typescript@5.9.3))
       fuse.js: 7.1.0
-      github-slugger: 2.0.0
+      microdiff: 1.5.0
       nanoid: 5.1.6
-      vue: 3.5.22(typescript@5.9.3)
-      zod: 3.25.76
+      vue: 3.5.32(typescript@5.9.3)
+      yaml: 2.9.0
     transitivePeerDependencies:
-      - '@hyperjump/browser'
       - '@vue/composition-api'
       - async-validator
       - axios
@@ -9875,13 +12884,12 @@ snapshots:
       - tailwindcss
       - typescript
       - universal-cookie
+      - zod
 
-  '@scalar/code-highlight@0.0.24':
+  '@scalar/code-highlight@0.3.4':
     dependencies:
       hast-util-to-text: 4.0.2
       highlight.js: 11.11.1
-      highlightjs-curl: 1.3.0
-      highlightjs-vue: 1.0.0
       lowlight: 3.3.0
       rehype-external-links: 3.0.0
       rehype-format: 5.0.1
@@ -9894,105 +12902,107 @@ snapshots:
       remark-rehype: 11.1.2
       remark-stringify: 11.0.0
       unified: 11.0.5
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
     transitivePeerDependencies:
       - supports-color
 
-  '@scalar/components@0.13.33(typescript@5.9.3)':
+  '@scalar/components@0.24.4(tailwindcss@4.3.1)(typescript@5.9.3)':
     dependencies:
       '@floating-ui/utils': 0.2.10
-      '@floating-ui/vue': 1.1.9(vue@3.5.22(typescript@5.9.3))
-      '@headlessui/vue': 1.7.23(vue@3.5.22(typescript@5.9.3))
-      '@scalar/code-highlight': 0.0.24
-      '@scalar/themes': 0.9.75
-      '@scalar/use-hooks': 0.1.29(typescript@5.9.3)
-      '@scalar/use-toasts': 0.7.9(typescript@5.9.3)
-      '@vueuse/core': 10.11.1(vue@3.5.22(typescript@5.9.3))
-      cva: 1.0.0-beta.2(typescript@5.9.3)
+      '@floating-ui/vue': 1.1.9(vue@3.5.32(typescript@5.9.3))
+      '@headlessui/tailwindcss': 0.2.2(tailwindcss@4.3.1)
+      '@headlessui/vue': 1.7.23(vue@3.5.32(typescript@5.9.3))
+      '@scalar/code-highlight': 0.3.4
+      '@scalar/helpers': 0.8.0
+      '@scalar/icons': 0.7.2(typescript@5.9.3)
+      '@scalar/themes': 0.15.5
+      '@scalar/use-hooks': 0.4.5(typescript@5.9.3)
+      '@vueuse/core': 13.9.0(vue@3.5.32(typescript@5.9.3))
+      cva: 1.0.0-beta.4(typescript@5.9.3)
       nanoid: 5.1.6
-      pretty-bytes: 6.1.1
-      radix-vue: 1.9.17(vue@3.5.22(typescript@5.9.3))
-      tailwind-merge: 2.6.0
-      vue: 3.5.22(typescript@5.9.3)
+      radix-vue: 1.9.17(vue@3.5.32(typescript@5.9.3))
+      vue: 3.5.32(typescript@5.9.3)
+      vue-component-type-helpers: 3.2.6
     transitivePeerDependencies:
       - '@vue/composition-api'
       - supports-color
+      - tailwindcss
       - typescript
 
-  '@scalar/draggable@0.1.11(typescript@5.9.3)':
-    dependencies:
-      vue: 3.5.22(typescript@5.9.3)
-    transitivePeerDependencies:
-      - typescript
+  '@scalar/helpers@0.8.0': {}
 
-  '@scalar/icons@0.1.3(typescript@5.9.3)':
+  '@scalar/icons@0.7.2(typescript@5.9.3)':
     dependencies:
-      vue: 3.5.22(typescript@5.9.3)
+      '@phosphor-icons/core': 2.1.1
+      '@types/node': 24.12.0
+      chalk: 5.6.2
+      vue: 3.5.32(typescript@5.9.3)
     transitivePeerDependencies:
       - typescript
 
-  '@scalar/import@0.2.36(@hyperjump/browser@1.3.1)':
+  '@scalar/json-magic@0.12.14':
     dependencies:
-      '@scalar/oas-utils': 0.2.116(@hyperjump/browser@1.3.1)
-      '@scalar/openapi-parser': 0.10.10
-      yaml: 2.8.1
-    transitivePeerDependencies:
-      - '@hyperjump/browser'
+      '@scalar/helpers': 0.8.0
+      pathe: 2.0.3
+      yaml: 2.9.0
 
-  '@scalar/oas-utils@0.2.116(@hyperjump/browser@1.3.1)':
+  '@scalar/oas-utils@0.17.0(typescript@5.9.3)':
     dependencies:
-      '@hyperjump/json-schema': 1.16.3(@hyperjump/browser@1.3.1)
-      '@scalar/object-utils': 1.1.13
-      '@scalar/openapi-types': 0.1.9
-      '@scalar/themes': 0.9.75
-      '@scalar/types': 0.0.40
-      flatted: 3.3.3
-      microdiff: 1.5.0
-      nanoid: 5.1.6
-      yaml: 2.8.1
-      zod: 3.25.76
+      '@scalar/helpers': 0.8.0
+      '@scalar/themes': 0.15.5
+      '@scalar/types': 0.11.0
+      '@scalar/workspace-store': 0.51.0(typescript@5.9.3)
+      flatted: 3.4.2
+      vue: 3.5.32(typescript@5.9.3)
+      yaml: 2.9.0
     transitivePeerDependencies:
-      - '@hyperjump/browser'
+      - typescript
 
-  '@scalar/object-utils@1.1.13':
-    dependencies:
-      flatted: 3.3.3
-      just-clone: 6.2.0
-      ts-deepmerge: 7.0.3
+  '@scalar/openapi-types@0.8.0': {}
 
-  '@scalar/openapi-parser@0.10.10':
+  '@scalar/openapi-upgrader@0.2.7':
     dependencies:
-      ajv: 8.17.1
-      ajv-draft-04: 1.0.0(ajv@8.17.1)
-      ajv-formats: 3.0.1(ajv@8.17.1)
-      jsonpointer: 5.0.1
-      leven: 4.1.0
-      yaml: 2.8.1
+      '@scalar/openapi-types': 0.8.0
 
-  '@scalar/openapi-types@0.1.9': {}
+  '@scalar/schemas@0.2.0':
+    dependencies:
+      '@scalar/validation': 0.5.0
 
-  '@scalar/postman-to-openapi@0.1.39(@hyperjump/browser@1.3.1)':
+  '@scalar/sidebar@0.9.13(tailwindcss@4.3.1)(typescript@5.9.3)':
     dependencies:
-      '@scalar/oas-utils': 0.2.116(@hyperjump/browser@1.3.1)
-      '@scalar/openapi-types': 0.1.9
+      '@scalar/components': 0.24.4(tailwindcss@4.3.1)(typescript@5.9.3)
+      '@scalar/helpers': 0.8.0
+      '@scalar/icons': 0.7.2(typescript@5.9.3)
+      '@scalar/themes': 0.15.5
+      '@scalar/use-hooks': 0.4.5(typescript@5.9.3)
+      '@scalar/workspace-store': 0.51.0(typescript@5.9.3)
+      vue: 3.5.32(typescript@5.9.3)
     transitivePeerDependencies:
-      - '@hyperjump/browser'
+      - '@vue/composition-api'
+      - supports-color
+      - tailwindcss
+      - typescript
 
-  '@scalar/snippetz@0.2.16':
+  '@scalar/snippetz@0.9.8':
     dependencies:
-      stringify-object: 5.0.0
+      '@scalar/types': 0.11.0
+      js-base64: 3.7.8
+      stringify-object: 6.0.0
 
-  '@scalar/themes@0.9.75':
+  '@scalar/themes@0.15.5':
     dependencies:
-      '@scalar/types': 0.0.40
+      nanoid: 5.1.6
+
+  '@scalar/typebox@0.1.3': {}
 
-  '@scalar/types@0.0.40':
+  '@scalar/types@0.11.0':
     dependencies:
-      '@scalar/openapi-types': 0.1.9
-      '@unhead/schema': 1.11.20
-      zod: 3.25.76
+      '@scalar/helpers': 0.8.0
+      nanoid: 5.1.6
+      type-fest: 5.5.0
+      zod: 4.3.6
 
-  '@scalar/use-codemirror@0.11.78(typescript@5.9.3)':
+  '@scalar/use-codemirror@0.14.11(typescript@5.9.3)':
     dependencies:
       '@codemirror/autocomplete': 6.19.0
       '@codemirror/commands': 6.9.0
@@ -10007,108 +13017,127 @@ snapshots:
       '@codemirror/view': 6.38.5
       '@lezer/common': 1.2.3
       '@lezer/highlight': 1.2.1
-      '@lezer/lr': 1.4.2
       '@replit/codemirror-css-color-picker': 6.3.0(@codemirror/language@6.11.3)(@codemirror/state@6.5.2)(@codemirror/view@6.38.5)
-      '@scalar/components': 0.13.33(typescript@5.9.3)
-      codemirror: 6.0.2
-      style-mod: 4.1.2
-      vue: 3.5.22(typescript@5.9.3)
+      vue: 3.5.32(typescript@5.9.3)
     transitivePeerDependencies:
-      - '@vue/composition-api'
-      - supports-color
       - typescript
 
-  '@scalar/use-hooks@0.1.29(typescript@5.9.3)':
+  '@scalar/use-hooks@0.4.5(typescript@5.9.3)':
     dependencies:
-      '@scalar/themes': 0.9.75
-      '@scalar/use-toasts': 0.7.9(typescript@5.9.3)
-      '@vueuse/core': 10.11.1(vue@3.5.22(typescript@5.9.3))
-      vue: 3.5.22(typescript@5.9.3)
-      zod: 3.25.76
+      '@scalar/use-toasts': 0.10.2(typescript@5.9.3)
+      '@scalar/validation': 0.5.0
+      '@vueuse/core': 13.9.0(vue@3.5.32(typescript@5.9.3))
+      cva: 1.0.0-beta.4(typescript@5.9.3)
+      tailwind-merge: 3.5.0
+      vue: 3.5.32(typescript@5.9.3)
     transitivePeerDependencies:
-      - '@vue/composition-api'
       - typescript
 
-  '@scalar/use-toasts@0.7.9(typescript@5.9.3)':
+  '@scalar/use-toasts@0.10.2(typescript@5.9.3)':
     dependencies:
-      nanoid: 5.1.6
-      vue: 3.5.22(typescript@5.9.3)
+      vue: 3.5.32(typescript@5.9.3)
       vue-sonner: 1.3.2
     transitivePeerDependencies:
       - typescript
 
-  '@scalar/use-tooltip@1.0.6(typescript@5.9.3)':
-    dependencies:
-      tippy.js: 6.3.7
-      vue: 3.5.22(typescript@5.9.3)
+  '@scalar/validation@0.5.0': {}
+
+  '@scalar/workspace-store@0.51.0(typescript@5.9.3)':
+    dependencies:
+      '@scalar/helpers': 0.8.0
+      '@scalar/json-magic': 0.12.14
+      '@scalar/openapi-upgrader': 0.2.7
+      '@scalar/snippetz': 0.9.8
+      '@scalar/typebox': 0.1.3
+      '@scalar/types': 0.11.0
+      '@scalar/validation': 0.5.0
+      js-base64: 3.7.8
+      type-fest: 5.5.0
+      vue: 3.5.32(typescript@5.9.3)
+      yaml: 2.9.0
     transitivePeerDependencies:
       - typescript
 
-  '@shikijs/core@3.13.0':
+  '@shikijs/core@3.21.0':
     dependencies:
-      '@shikijs/types': 3.13.0
+      '@shikijs/types': 3.21.0
       '@shikijs/vscode-textmate': 10.0.2
       '@types/hast': 3.0.4
       hast-util-to-html: 9.0.5
 
-  '@shikijs/core@3.15.0':
+  '@shikijs/core@4.0.2':
     dependencies:
-      '@shikijs/types': 3.15.0
+      '@shikijs/primitive': 4.0.2
+      '@shikijs/types': 4.0.2
       '@shikijs/vscode-textmate': 10.0.2
       '@types/hast': 3.0.4
       hast-util-to-html: 9.0.5
 
-  '@shikijs/engine-javascript@3.13.0':
+  '@shikijs/engine-javascript@3.21.0':
     dependencies:
-      '@shikijs/types': 3.13.0
+      '@shikijs/types': 3.21.0
       '@shikijs/vscode-textmate': 10.0.2
-      oniguruma-to-es: 4.3.3
+      oniguruma-to-es: 4.3.4
 
-  '@shikijs/engine-javascript@3.15.0':
+  '@shikijs/engine-javascript@4.0.2':
     dependencies:
-      '@shikijs/types': 3.15.0
+      '@shikijs/types': 4.0.2
       '@shikijs/vscode-textmate': 10.0.2
-      oniguruma-to-es: 4.3.3
+      oniguruma-to-es: 4.3.4
 
-  '@shikijs/engine-oniguruma@3.13.0':
+  '@shikijs/engine-oniguruma@3.21.0':
     dependencies:
-      '@shikijs/types': 3.13.0
+      '@shikijs/types': 3.21.0
       '@shikijs/vscode-textmate': 10.0.2
 
-  '@shikijs/engine-oniguruma@3.15.0':
+  '@shikijs/engine-oniguruma@4.0.2':
     dependencies:
-      '@shikijs/types': 3.15.0
+      '@shikijs/types': 4.0.2
       '@shikijs/vscode-textmate': 10.0.2
 
-  '@shikijs/langs@3.13.0':
+  '@shikijs/langs@3.21.0':
     dependencies:
-      '@shikijs/types': 3.13.0
+      '@shikijs/types': 3.21.0
 
-  '@shikijs/langs@3.15.0':
+  '@shikijs/langs@4.0.2':
     dependencies:
-      '@shikijs/types': 3.15.0
+      '@shikijs/types': 4.0.2
 
-  '@shikijs/themes@3.13.0':
+  '@shikijs/primitive@4.0.2':
     dependencies:
-      '@shikijs/types': 3.13.0
+      '@shikijs/types': 4.0.2
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.4
+
+  '@shikijs/themes@3.21.0':
+    dependencies:
+      '@shikijs/types': 3.21.0
 
-  '@shikijs/themes@3.15.0':
+  '@shikijs/themes@4.0.2':
     dependencies:
-      '@shikijs/types': 3.15.0
+      '@shikijs/types': 4.0.2
 
-  '@shikijs/types@3.13.0':
+  '@shikijs/types@3.21.0':
     dependencies:
       '@shikijs/vscode-textmate': 10.0.2
       '@types/hast': 3.0.4
 
-  '@shikijs/types@3.15.0':
+  '@shikijs/types@4.0.2':
     dependencies:
       '@shikijs/vscode-textmate': 10.0.2
       '@types/hast': 3.0.4
 
   '@shikijs/vscode-textmate@10.0.2': {}
 
-  '@standard-schema/spec@1.0.0': {}
+  '@simple-git/args-pathspec@1.0.3': {}
+
+  '@simple-git/argv-parser@1.1.1':
+    dependencies:
+      '@simple-git/args-pathspec': 1.0.3
+
+  '@sindresorhus/merge-streams@2.3.0': {}
+
+  '@standard-schema/spec@1.1.0': {}
 
   '@stoplight/better-ajv-errors@1.0.3(ajv@8.17.1)':
     dependencies:
@@ -10164,7 +13193,7 @@ snapshots:
       ajv-errors: 3.0.0(ajv@8.17.1)
       ajv-formats: 2.1.1(ajv@8.17.1)
       es-aggregate-error: 1.0.14
-      jsonpath-plus: 10.3.0
+      jsonpath-plus: 10.4.0
       lodash: 4.17.21
       lodash.topath: 4.5.2
       minimatch: 3.1.2
@@ -10257,17 +13286,147 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
-  '@tailwindcss/typography@0.5.19(tailwindcss@3.4.18(yaml@2.8.1))':
+  '@tailwindcss/node@4.1.18':
     dependencies:
-      postcss-selector-parser: 6.0.10
-      tailwindcss: 3.4.18(yaml@2.8.1)
+      '@jridgewell/remapping': 2.3.5
+      enhanced-resolve: 5.19.0
+      jiti: 2.6.1
+      lightningcss: 1.30.2
+      magic-string: 0.30.21
+      source-map-js: 1.2.1
+      tailwindcss: 4.1.18
+
+  '@tailwindcss/node@4.3.1':
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      enhanced-resolve: 5.21.6
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      magic-string: 0.30.21
+      source-map-js: 1.2.1
+      tailwindcss: 4.3.1
+
+  '@tailwindcss/oxide-android-arm64@4.1.18':
+    optional: true
+
+  '@tailwindcss/oxide-android-arm64@4.3.1':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-arm64@4.1.18':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-arm64@4.3.1':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-x64@4.1.18':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-x64@4.3.1':
+    optional: true
+
+  '@tailwindcss/oxide-freebsd-x64@4.1.18':
+    optional: true
+
+  '@tailwindcss/oxide-freebsd-x64@4.3.1':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.1.18':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.3.1':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.1.18':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.3.1':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.1.18':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.3.1':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.1.18':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.3.1':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-musl@4.1.18':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-musl@4.3.1':
+    optional: true
+
+  '@tailwindcss/oxide-wasm32-wasi@4.1.18':
+    optional: true
+
+  '@tailwindcss/oxide-wasm32-wasi@4.3.1':
+    optional: true
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.1.18':
+    optional: true
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.3.1':
+    optional: true
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.1.18':
+    optional: true
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.3.1':
+    optional: true
 
-  '@tanstack/query-core@5.90.2': {}
+  '@tailwindcss/oxide@4.1.18':
+    optionalDependencies:
+      '@tailwindcss/oxide-android-arm64': 4.1.18
+      '@tailwindcss/oxide-darwin-arm64': 4.1.18
+      '@tailwindcss/oxide-darwin-x64': 4.1.18
+      '@tailwindcss/oxide-freebsd-x64': 4.1.18
+      '@tailwindcss/oxide-linux-arm-gnueabihf': 4.1.18
+      '@tailwindcss/oxide-linux-arm64-gnu': 4.1.18
+      '@tailwindcss/oxide-linux-arm64-musl': 4.1.18
+      '@tailwindcss/oxide-linux-x64-gnu': 4.1.18
+      '@tailwindcss/oxide-linux-x64-musl': 4.1.18
+      '@tailwindcss/oxide-wasm32-wasi': 4.1.18
+      '@tailwindcss/oxide-win32-arm64-msvc': 4.1.18
+      '@tailwindcss/oxide-win32-x64-msvc': 4.1.18
+
+  '@tailwindcss/oxide@4.3.1':
+    optionalDependencies:
+      '@tailwindcss/oxide-android-arm64': 4.3.1
+      '@tailwindcss/oxide-darwin-arm64': 4.3.1
+      '@tailwindcss/oxide-darwin-x64': 4.3.1
+      '@tailwindcss/oxide-freebsd-x64': 4.3.1
+      '@tailwindcss/oxide-linux-arm-gnueabihf': 4.3.1
+      '@tailwindcss/oxide-linux-arm64-gnu': 4.3.1
+      '@tailwindcss/oxide-linux-arm64-musl': 4.3.1
+      '@tailwindcss/oxide-linux-x64-gnu': 4.3.1
+      '@tailwindcss/oxide-linux-x64-musl': 4.3.1
+      '@tailwindcss/oxide-wasm32-wasi': 4.3.1
+      '@tailwindcss/oxide-win32-arm64-msvc': 4.3.1
+      '@tailwindcss/oxide-win32-x64-msvc': 4.3.1
+
+  '@tailwindcss/postcss@4.1.18':
+    dependencies:
+      '@alloc/quick-lru': 5.2.0
+      '@tailwindcss/node': 4.1.18
+      '@tailwindcss/oxide': 4.1.18
+      postcss: 8.5.6
+      tailwindcss: 4.1.18
 
-  '@tanstack/react-query@5.90.2(react@18.3.1)':
+  '@tailwindcss/typography@0.5.19(tailwindcss@4.3.1)':
     dependencies:
-      '@tanstack/query-core': 5.90.2
-      react: 18.3.1
+      postcss-selector-parser: 6.0.10
+      tailwindcss: 4.3.1
+
+  '@tailwindcss/vite@4.3.1(vite@8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      '@tailwindcss/node': 4.3.1
+      '@tailwindcss/oxide': 4.3.1
+      tailwindcss: 4.3.1
+      vite: 8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
 
   '@tanstack/react-table@8.21.3(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
@@ -10285,36 +13444,59 @@ snapshots:
 
   '@tanstack/virtual-core@3.13.12': {}
 
-  '@tanstack/vue-virtual@3.13.12(vue@3.5.22(typescript@5.9.3))':
+  '@tanstack/vue-virtual@3.13.12(vue@3.5.32(typescript@5.9.3))':
     dependencies:
       '@tanstack/virtual-core': 3.13.12
-      vue: 3.5.22(typescript@5.9.3)
+      vue: 3.5.32(typescript@5.9.3)
+
+  '@tybys/wasm-util@0.10.2':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@tybys/wasm-util@0.10.3':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
 
-  '@trysound/sax@0.2.0': {}
+  '@types/async-retry@1.4.2':
+    dependencies:
+      '@types/retry': 0.12.5
 
   '@types/babel__core@7.20.5':
     dependencies:
-      '@babel/parser': 7.28.4
-      '@babel/types': 7.28.4
+      '@babel/parser': 7.29.0
+      '@babel/types': 7.29.0
       '@types/babel__generator': 7.27.0
       '@types/babel__template': 7.4.4
       '@types/babel__traverse': 7.28.0
 
   '@types/babel__generator@7.27.0':
     dependencies:
-      '@babel/types': 7.28.4
+      '@babel/types': 7.29.0
 
   '@types/babel__template@7.4.4':
     dependencies:
-      '@babel/parser': 7.28.4
-      '@babel/types': 7.28.4
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
 
   '@types/babel__traverse@7.28.0':
     dependencies:
-      '@babel/types': 7.28.4
+      '@babel/types': 7.29.0
+
+  '@types/chai@5.2.3':
+    dependencies:
+      '@types/deep-eql': 4.0.2
+      assertion-error: 2.0.1
+
+  '@types/ci-info@2.0.0': {}
 
   '@types/configstore@6.0.2': {}
 
+  '@types/cross-spawn@6.0.0':
+    dependencies:
+      '@types/node': 20.19.19
+
   '@types/css-tree@2.3.11': {}
 
   '@types/csso@5.0.4':
@@ -10444,6 +13626,8 @@ snapshots:
     dependencies:
       '@types/ms': 2.1.0
 
+  '@types/deep-eql@4.0.2': {}
+
   '@types/diff@5.2.3': {}
 
   '@types/es-aggregate-error@1.0.6':
@@ -10456,12 +13640,19 @@ snapshots:
 
   '@types/estree@1.0.8': {}
 
-  '@types/fontkit@2.0.8':
+  '@types/fs-extra@11.0.4':
     dependencies:
+      '@types/jsonfile': 6.1.4
       '@types/node': 20.19.19
 
   '@types/geojson@7946.0.16': {}
 
+  '@types/glob@9.0.0':
+    dependencies:
+      glob: 13.0.6
+
+  '@types/har-format@1.2.16': {}
+
   '@types/hast@2.3.10':
     dependencies:
       '@types/unist': 2.0.11
@@ -10476,7 +13667,9 @@ snapshots:
 
   '@types/json-schema@7.0.15': {}
 
-  '@types/jsonpath@0.2.4': {}
+  '@types/jsonfile@6.1.4':
+    dependencies:
+      '@types/node': 20.19.19
 
   '@types/jsonwebtoken@9.0.10':
     dependencies:
@@ -10493,10 +13686,6 @@ snapshots:
 
   '@types/lodash@4.17.20': {}
 
-  '@types/mdast@3.0.15':
-    dependencies:
-      '@types/unist': 2.0.11
-
   '@types/mdast@4.0.4':
     dependencies:
       '@types/unist': 3.0.3
@@ -10509,54 +13698,69 @@ snapshots:
     dependencies:
       '@types/unist': 3.0.3
 
-  '@types/node-fetch@2.6.13':
-    dependencies:
-      '@types/node': 20.19.19
-      form-data: 4.0.4
-
   '@types/node@12.20.55': {}
 
-  '@types/node@18.19.129':
+  '@types/node@20.19.19':
     dependencies:
-      undici-types: 5.26.5
+      undici-types: 6.21.0
 
-  '@types/node@20.19.19':
+  '@types/node@22.19.21':
     dependencies:
       undici-types: 6.21.0
 
-  '@types/node@22.13.14':
+  '@types/node@24.12.0':
+    dependencies:
+      undici-types: 7.16.0
+
+  '@types/node@25.0.3':
     dependencies:
-      undici-types: 6.20.0
+      undici-types: 7.16.0
 
   '@types/pako@2.0.4': {}
 
-  '@types/prop-types@15.7.15': {}
+  '@types/prompts@2.0.1': {}
+
+  '@types/proper-lockfile@4.1.4':
+    dependencies:
+      '@types/retry': 0.12.5
 
   '@types/protocol-buffers-schema@3.4.3':
     dependencies:
       '@types/node': 20.19.19
 
-  '@types/react-dom@18.3.7(@types/react@18.3.26)':
+  '@types/react-dom@19.2.3(@types/react@19.2.13)':
+    dependencies:
+      '@types/react': 19.2.13
+
+  '@types/react-reconciler@0.28.9(@types/react@19.2.13)':
     dependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
 
   '@types/react-syntax-highlighter@15.5.13':
     dependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
+
+  '@types/react@19.2.13':
+    dependencies:
+      csstype: 3.2.3
+
+  '@types/retry@0.12.5': {}
 
-  '@types/react@18.3.26':
+  '@types/rimraf@3.0.0':
     dependencies:
-      '@types/prop-types': 15.7.15
-      csstype: 3.1.3
+      '@types/glob': 9.0.0
+      '@types/node': 20.19.19
 
-  '@types/retry@0.12.0': {}
+  '@types/sax@1.2.7':
+    dependencies:
+      '@types/node': 20.19.19
 
   '@types/semver@7.7.1': {}
 
   '@types/shelljs@0.8.17':
     dependencies:
       '@types/node': 20.19.19
-      glob: 11.0.3
+      glob: 11.1.0
 
   '@types/trusted-types@2.0.7':
     optional: true
@@ -10574,86 +13778,150 @@ snapshots:
 
   '@types/uuid@10.0.0': {}
 
+  '@types/validate-npm-package-name@3.0.0': {}
+
+  '@types/vscode@1.109.0': {}
+
   '@types/web-bluetooth@0.0.20': {}
 
+  '@types/web-bluetooth@0.0.21': {}
+
   '@ungap/structured-clone@1.3.0': {}
 
-  '@unhead/dom@1.11.20':
+  '@unhead/vue@2.1.13(vue@3.5.32(typescript@5.9.3))':
     dependencies:
-      '@unhead/schema': 1.11.20
-      '@unhead/shared': 1.11.20
+      hookable: 6.1.0
+      unhead: 2.1.13
+      vue: 3.5.32(typescript@5.9.3)
 
-  '@unhead/schema@1.11.20':
-    dependencies:
-      hookable: 5.5.3
-      zhead: 2.2.4
+  '@vercel/ncc@0.34.0': {}
 
-  '@unhead/shared@1.11.20':
-    dependencies:
-      '@unhead/schema': 1.11.20
-      packrup: 0.1.2
+  '@vercel/oidc@3.1.0': {}
 
-  '@unhead/vue@1.11.20(vue@3.5.22(typescript@5.9.3))':
+  '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))':
     dependencies:
-      '@unhead/schema': 1.11.20
-      '@unhead/shared': 1.11.20
-      hookable: 5.5.3
-      unhead: 1.11.20
-      vue: 3.5.22(typescript@5.9.3)
+      '@babel/core': 7.29.0
+      '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.29.0)
+      '@babel/plugin-transform-react-jsx-source': 7.27.1(@babel/core@7.29.0)
+      '@rolldown/pluginutils': 1.0.0-beta.27
+      '@types/babel__core': 7.20.5
+      react-refresh: 0.17.0
+      vite: 6.4.1(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - supports-color
 
-  '@vercel/oidc@3.0.2': {}
+  '@vitejs/plugin-react@5.1.4(vite@7.1.9(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.29.0)
+      '@babel/plugin-transform-react-jsx-source': 7.27.1(@babel/core@7.29.0)
+      '@rolldown/pluginutils': 1.0.0-rc.3
+      '@types/babel__core': 7.20.5
+      react-refresh: 0.18.0
+      vite: 7.1.9(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - supports-color
 
-  '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1))':
+  '@vitejs/plugin-react@5.2.0(vite@8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))':
     dependencies:
-      '@babel/core': 7.28.4
-      '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.28.4)
-      '@babel/plugin-transform-react-jsx-source': 7.27.1(@babel/core@7.28.4)
-      '@rolldown/pluginutils': 1.0.0-beta.27
+      '@babel/core': 7.29.0
+      '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.29.0)
+      '@babel/plugin-transform-react-jsx-source': 7.27.1(@babel/core@7.29.0)
+      '@rolldown/pluginutils': 1.0.0-rc.3
       '@types/babel__core': 7.20.5
-      react-refresh: 0.17.0
-      vite: 6.4.1(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1)
+      react-refresh: 0.18.0
+      vite: 8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
     transitivePeerDependencies:
       - supports-color
 
-  '@vitest/expect@2.1.9':
+  '@vitest/expect@3.2.4':
     dependencies:
-      '@vitest/spy': 2.1.9
-      '@vitest/utils': 2.1.9
+      '@types/chai': 5.2.3
+      '@vitest/spy': 3.2.4
+      '@vitest/utils': 3.2.4
       chai: 5.3.3
-      tinyrainbow: 1.2.0
+      tinyrainbow: 2.0.0
+
+  '@vitest/expect@4.0.18':
+    dependencies:
+      '@standard-schema/spec': 1.1.0
+      '@types/chai': 5.2.3
+      '@vitest/spy': 4.0.18
+      '@vitest/utils': 4.0.18
+      chai: 6.2.2
+      tinyrainbow: 3.0.3
+
+  '@vitest/mocker@3.2.4(vite@7.3.1(@types/node@20.19.19)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      '@vitest/spy': 3.2.4
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 7.3.1(@types/node@20.19.19)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  '@vitest/mocker@3.2.4(vite@7.3.1(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))':
+    dependencies:
+      '@vitest/spy': 3.2.4
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 7.3.1(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
 
-  '@vitest/mocker@2.1.9(vite@5.4.21(@types/node@20.19.19)(lightningcss@1.29.3)(terser@5.39.0))':
+  '@vitest/mocker@4.0.18(vite@7.3.2(@types/node@22.19.21)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))':
     dependencies:
-      '@vitest/spy': 2.1.9
+      '@vitest/spy': 4.0.18
       estree-walker: 3.0.3
-      magic-string: 0.30.19
+      magic-string: 0.30.21
     optionalDependencies:
-      vite: 5.4.21(@types/node@20.19.19)(lightningcss@1.29.3)(terser@5.39.0)
+      vite: 7.3.2(@types/node@22.19.21)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  '@vitest/pretty-format@3.2.4':
+    dependencies:
+      tinyrainbow: 2.0.0
+
+  '@vitest/pretty-format@4.0.18':
+    dependencies:
+      tinyrainbow: 3.0.3
+
+  '@vitest/runner@3.2.4':
+    dependencies:
+      '@vitest/utils': 3.2.4
+      pathe: 2.0.3
+      strip-literal: 3.1.0
 
-  '@vitest/pretty-format@2.1.9':
+  '@vitest/runner@4.0.18':
     dependencies:
-      tinyrainbow: 1.2.0
+      '@vitest/utils': 4.0.18
+      pathe: 2.0.3
 
-  '@vitest/runner@2.1.9':
+  '@vitest/snapshot@3.2.4':
     dependencies:
-      '@vitest/utils': 2.1.9
-      pathe: 1.1.2
+      '@vitest/pretty-format': 3.2.4
+      magic-string: 0.30.21
+      pathe: 2.0.3
 
-  '@vitest/snapshot@2.1.9':
+  '@vitest/snapshot@4.0.18':
     dependencies:
-      '@vitest/pretty-format': 2.1.9
-      magic-string: 0.30.19
-      pathe: 1.1.2
+      '@vitest/pretty-format': 4.0.18
+      magic-string: 0.30.21
+      pathe: 2.0.3
 
-  '@vitest/spy@2.1.9':
+  '@vitest/spy@3.2.4':
     dependencies:
-      tinyspy: 3.0.2
+      tinyspy: 4.0.4
 
-  '@vitest/utils@2.1.9':
+  '@vitest/spy@4.0.18': {}
+
+  '@vitest/utils@3.2.4':
     dependencies:
-      '@vitest/pretty-format': 2.1.9
+      '@vitest/pretty-format': 3.2.4
       loupe: 3.2.1
-      tinyrainbow: 1.2.0
+      tinyrainbow: 2.0.0
+
+  '@vitest/utils@4.0.18':
+    dependencies:
+      '@vitest/pretty-format': 4.0.18
+      tinyrainbow: 3.0.3
 
   '@volar/kit@2.4.23(typescript@5.9.3)':
     dependencies:
@@ -10664,10 +13932,23 @@ snapshots:
       vscode-languageserver-textdocument: 1.0.12
       vscode-uri: 3.1.0
 
+  '@volar/kit@2.4.28(typescript@5.9.3)':
+    dependencies:
+      '@volar/language-service': 2.4.28
+      '@volar/typescript': 2.4.28
+      typesafe-path: 0.2.2
+      typescript: 5.9.3
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-uri: 3.1.0
+
   '@volar/language-core@2.4.23':
     dependencies:
       '@volar/source-map': 2.4.23
 
+  '@volar/language-core@2.4.28':
+    dependencies:
+      '@volar/source-map': 2.4.28
+
   '@volar/language-server@2.4.23':
     dependencies:
       '@volar/language-core': 2.4.23
@@ -10680,6 +13961,18 @@ snapshots:
       vscode-languageserver-textdocument: 1.0.12
       vscode-uri: 3.1.0
 
+  '@volar/language-server@2.4.28':
+    dependencies:
+      '@volar/language-core': 2.4.28
+      '@volar/language-service': 2.4.28
+      '@volar/typescript': 2.4.28
+      path-browserify: 1.0.1
+      request-light: 0.7.0
+      vscode-languageserver: 9.0.1
+      vscode-languageserver-protocol: 3.17.5
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-uri: 3.1.0
+
   '@volar/language-service@2.4.23':
     dependencies:
       '@volar/language-core': 2.4.23
@@ -10687,14 +13980,29 @@ snapshots:
       vscode-languageserver-textdocument: 1.0.12
       vscode-uri: 3.1.0
 
+  '@volar/language-service@2.4.28':
+    dependencies:
+      '@volar/language-core': 2.4.28
+      vscode-languageserver-protocol: 3.17.5
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-uri: 3.1.0
+
   '@volar/source-map@2.4.23': {}
 
+  '@volar/source-map@2.4.28': {}
+
   '@volar/typescript@2.4.23':
     dependencies:
       '@volar/language-core': 2.4.23
       path-browserify: 1.0.1
       vscode-uri: 3.1.0
 
+  '@volar/typescript@2.4.28':
+    dependencies:
+      '@volar/language-core': 2.4.28
+      path-browserify: 1.0.1
+      vscode-uri: 3.1.0
+
   '@vscode/emmet-helper@2.11.0':
     dependencies:
       emmet: 2.4.11
@@ -10705,120 +14013,120 @@ snapshots:
 
   '@vscode/l10n@0.0.18': {}
 
-  '@vue/compiler-core@3.5.22':
+  '@vue/compiler-core@3.5.32':
     dependencies:
-      '@babel/parser': 7.28.4
-      '@vue/shared': 3.5.22
-      entities: 4.5.0
+      '@babel/parser': 7.29.2
+      '@vue/shared': 3.5.32
+      entities: 7.0.1
       estree-walker: 2.0.2
       source-map-js: 1.2.1
 
-  '@vue/compiler-dom@3.5.22':
+  '@vue/compiler-dom@3.5.32':
     dependencies:
-      '@vue/compiler-core': 3.5.22
-      '@vue/shared': 3.5.22
+      '@vue/compiler-core': 3.5.32
+      '@vue/shared': 3.5.32
 
-  '@vue/compiler-sfc@3.5.22':
+  '@vue/compiler-sfc@3.5.32':
     dependencies:
-      '@babel/parser': 7.28.4
-      '@vue/compiler-core': 3.5.22
-      '@vue/compiler-dom': 3.5.22
-      '@vue/compiler-ssr': 3.5.22
-      '@vue/shared': 3.5.22
+      '@babel/parser': 7.29.2
+      '@vue/compiler-core': 3.5.32
+      '@vue/compiler-dom': 3.5.32
+      '@vue/compiler-ssr': 3.5.32
+      '@vue/shared': 3.5.32
       estree-walker: 2.0.2
-      magic-string: 0.30.19
-      postcss: 8.5.6
+      magic-string: 0.30.21
+      postcss: 8.5.15
       source-map-js: 1.2.1
 
-  '@vue/compiler-ssr@3.5.22':
+  '@vue/compiler-ssr@3.5.32':
     dependencies:
-      '@vue/compiler-dom': 3.5.22
-      '@vue/shared': 3.5.22
+      '@vue/compiler-dom': 3.5.32
+      '@vue/shared': 3.5.32
 
-  '@vue/devtools-api@6.6.4': {}
-
-  '@vue/reactivity@3.5.22':
+  '@vue/reactivity@3.5.32':
     dependencies:
-      '@vue/shared': 3.5.22
+      '@vue/shared': 3.5.32
 
-  '@vue/runtime-core@3.5.22':
+  '@vue/runtime-core@3.5.32':
     dependencies:
-      '@vue/reactivity': 3.5.22
-      '@vue/shared': 3.5.22
+      '@vue/reactivity': 3.5.32
+      '@vue/shared': 3.5.32
 
-  '@vue/runtime-dom@3.5.22':
+  '@vue/runtime-dom@3.5.32':
     dependencies:
-      '@vue/reactivity': 3.5.22
-      '@vue/runtime-core': 3.5.22
-      '@vue/shared': 3.5.22
-      csstype: 3.1.3
+      '@vue/reactivity': 3.5.32
+      '@vue/runtime-core': 3.5.32
+      '@vue/shared': 3.5.32
+      csstype: 3.2.3
 
-  '@vue/server-renderer@3.5.22(vue@3.5.22(typescript@5.9.3))':
+  '@vue/server-renderer@3.5.32(vue@3.5.32(typescript@5.9.3))':
     dependencies:
-      '@vue/compiler-ssr': 3.5.22
-      '@vue/shared': 3.5.22
-      vue: 3.5.22(typescript@5.9.3)
+      '@vue/compiler-ssr': 3.5.32
+      '@vue/shared': 3.5.32
+      vue: 3.5.32(typescript@5.9.3)
 
-  '@vue/shared@3.5.22': {}
+  '@vue/shared@3.5.32': {}
 
-  '@vueuse/core@10.11.1(vue@3.5.22(typescript@5.9.3))':
+  '@vueuse/core@10.11.1(vue@3.5.32(typescript@5.9.3))':
     dependencies:
       '@types/web-bluetooth': 0.0.20
       '@vueuse/metadata': 10.11.1
-      '@vueuse/shared': 10.11.1(vue@3.5.22(typescript@5.9.3))
-      vue-demi: 0.14.10(vue@3.5.22(typescript@5.9.3))
+      '@vueuse/shared': 10.11.1(vue@3.5.32(typescript@5.9.3))
+      vue-demi: 0.14.10(vue@3.5.32(typescript@5.9.3))
     transitivePeerDependencies:
       - '@vue/composition-api'
       - vue
 
-  '@vueuse/core@11.3.0(vue@3.5.22(typescript@5.9.3))':
+  '@vueuse/core@13.9.0(vue@3.5.32(typescript@5.9.3))':
     dependencies:
-      '@types/web-bluetooth': 0.0.20
-      '@vueuse/metadata': 11.3.0
-      '@vueuse/shared': 11.3.0(vue@3.5.22(typescript@5.9.3))
-      vue-demi: 0.14.10(vue@3.5.22(typescript@5.9.3))
-    transitivePeerDependencies:
-      - '@vue/composition-api'
-      - vue
+      '@types/web-bluetooth': 0.0.21
+      '@vueuse/metadata': 13.9.0
+      '@vueuse/shared': 13.9.0(vue@3.5.32(typescript@5.9.3))
+      vue: 3.5.32(typescript@5.9.3)
 
-  '@vueuse/integrations@11.3.0(axios@1.12.2)(focus-trap@7.6.5)(fuse.js@7.1.0)(vue@3.5.22(typescript@5.9.3))':
+  '@vueuse/integrations@13.9.0(axios@1.15.2)(focus-trap@7.8.0)(fuse.js@7.1.0)(vue@3.5.32(typescript@5.9.3))':
     dependencies:
-      '@vueuse/core': 11.3.0(vue@3.5.22(typescript@5.9.3))
-      '@vueuse/shared': 11.3.0(vue@3.5.22(typescript@5.9.3))
-      vue-demi: 0.14.10(vue@3.5.22(typescript@5.9.3))
+      '@vueuse/core': 13.9.0(vue@3.5.32(typescript@5.9.3))
+      '@vueuse/shared': 13.9.0(vue@3.5.32(typescript@5.9.3))
+      vue: 3.5.32(typescript@5.9.3)
     optionalDependencies:
-      axios: 1.12.2
-      focus-trap: 7.6.5
+      axios: 1.15.2
+      focus-trap: 7.8.0
       fuse.js: 7.1.0
-    transitivePeerDependencies:
-      - '@vue/composition-api'
-      - vue
 
   '@vueuse/metadata@10.11.1': {}
 
-  '@vueuse/metadata@11.3.0': {}
+  '@vueuse/metadata@13.9.0': {}
 
-  '@vueuse/shared@10.11.1(vue@3.5.22(typescript@5.9.3))':
+  '@vueuse/shared@10.11.1(vue@3.5.32(typescript@5.9.3))':
     dependencies:
-      vue-demi: 0.14.10(vue@3.5.22(typescript@5.9.3))
+      vue-demi: 0.14.10(vue@3.5.32(typescript@5.9.3))
     transitivePeerDependencies:
       - '@vue/composition-api'
       - vue
 
-  '@vueuse/shared@11.3.0(vue@3.5.22(typescript@5.9.3))':
+  '@vueuse/shared@13.9.0(vue@3.5.32(typescript@5.9.3))':
     dependencies:
-      vue-demi: 0.14.10(vue@3.5.22(typescript@5.9.3))
-    transitivePeerDependencies:
-      - '@vue/composition-api'
-      - vue
+      vue: 3.5.32(typescript@5.9.3)
 
-  '@xyflow/react@12.8.6(@types/react@18.3.26)(immer@9.0.21)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@xyflow/react@12.8.6(@types/react@19.2.13)(immer@9.0.21)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@xyflow/system': 0.0.70
       classcat: 5.0.5
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
-      zustand: 4.5.7(@types/react@18.3.26)(immer@9.0.21)(react@18.3.1)
+      zustand: 4.5.7(@types/react@19.2.13)(immer@9.0.21)(react@18.3.1)
+    transitivePeerDependencies:
+      - '@types/react'
+      - immer
+
+  '@xyflow/react@12.8.6(@types/react@19.2.13)(immer@9.0.21)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@xyflow/system': 0.0.70
+      classcat: 5.0.5
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      zustand: 4.5.7(@types/react@19.2.13)(immer@9.0.21)(react@19.2.4)
     transitivePeerDependencies:
       - '@types/react'
       - immer
@@ -10841,25 +14149,34 @@ snapshots:
     dependencies:
       event-target-shim: 5.0.1
 
-  acorn-jsx@5.3.2(acorn@8.15.0):
+  accepts@2.0.0:
     dependencies:
-      acorn: 8.15.0
+      mime-types: 3.0.2
+      negotiator: 1.0.0
 
-  acorn@8.15.0: {}
+  acorn-jsx@5.3.2(acorn@8.16.0):
+    dependencies:
+      acorn: 8.16.0
+
+  acorn@8.16.0: {}
 
   agent-base@7.1.4: {}
 
-  agentkeepalive@4.6.0:
+  ai@6.0.17(zod@4.3.6):
     dependencies:
-      humanize-ms: 1.2.1
+      '@ai-sdk/gateway': 3.0.9(zod@4.3.6)
+      '@ai-sdk/provider': 3.0.2
+      '@ai-sdk/provider-utils': 4.0.4(zod@4.3.6)
+      '@opentelemetry/api': 1.9.0
+      zod: 4.3.6
 
-  ai@5.0.62(zod@3.25.76):
+  ai@6.0.33(zod@4.3.6):
     dependencies:
-      '@ai-sdk/gateway': 1.0.35(zod@3.25.76)
-      '@ai-sdk/provider': 2.0.0
-      '@ai-sdk/provider-utils': 3.0.11(zod@3.25.76)
+      '@ai-sdk/gateway': 3.0.13(zod@4.3.6)
+      '@ai-sdk/provider': 3.0.2
+      '@ai-sdk/provider-utils': 4.0.5(zod@4.3.6)
       '@opentelemetry/api': 1.9.0
-      zod: 3.25.76
+      zod: 4.3.6
 
   ajv-draft-04@1.0.0(ajv@8.17.1):
     optionalDependencies:
@@ -10884,6 +14201,10 @@ snapshots:
       json-schema-traverse: 1.0.0
       require-from-string: 2.0.2
 
+  am-i-vibing@0.4.0:
+    dependencies:
+      process-ancestry: 0.1.0
+
   ansi-align@3.0.1:
     dependencies:
       string-width: 4.2.3
@@ -10894,12 +14215,14 @@ snapshots:
 
   ansi-regex@6.2.2: {}
 
+  ansi-styles@3.2.1:
+    dependencies:
+      color-convert: 1.9.3
+
   ansi-styles@4.3.0:
     dependencies:
       color-convert: 2.0.1
 
-  ansi-styles@5.2.0: {}
-
   ansi-styles@6.2.3: {}
 
   any-promise@1.3.0: {}
@@ -10944,25 +14267,30 @@ snapshots:
 
   assertion-error@2.0.1: {}
 
+  ast-types@0.16.1:
+    dependencies:
+      tslib: 2.8.1
+
   astring@1.9.0: {}
 
-  astro-compress@2.3.8(@types/node@20.19.19)(jiti@1.21.7)(rollup@4.52.4)(typescript@5.9.3)(yaml@2.8.1):
+  astro-compress@2.4.0(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(tsx@4.21.0)(yaml@2.9.0):
     dependencies:
-      '@playform/pipe': 0.1.3
+      '@playform/pipe': 0.1.4
       '@types/csso': 5.0.4
       '@types/html-minifier-terser': 7.0.2
-      astro: 5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1)
-      commander: 13.1.0
+      astro: 7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      commander: 14.0.3
       csso: 5.0.5
       deepmerge-ts: 7.1.5
       fast-glob: 3.3.3
       html-minifier-terser: 7.2.0
       kleur: 4.1.5
-      lightningcss: 1.29.3
-      sharp: 0.33.5
-      svgo: 3.3.2
-      terser: 5.39.0
+      lightningcss: 1.32.0
+      sharp: 0.34.5
+      svgo: 4.0.1
+      terser: 5.46.0
     transitivePeerDependencies:
+      - '@astrojs/markdown-remark'
       - '@azure/app-configuration'
       - '@azure/cosmos'
       - '@azure/data-tables'
@@ -10971,6 +14299,8 @@ snapshots:
       - '@azure/storage-blob'
       - '@capacitor/preferences'
       - '@deno/kv'
+      - '@emnapi/core'
+      - '@emnapi/runtime'
       - '@netlify/blobs'
       - '@planetscale/database'
       - '@types/node'
@@ -10978,6 +14308,7 @@ snapshots:
       - '@vercel/blob'
       - '@vercel/functions'
       - '@vercel/kv'
+      - '@vitejs/devtools'
       - aws4fetch
       - db0
       - idb-keyval
@@ -10989,16 +14320,20 @@ snapshots:
       - sass-embedded
       - stylus
       - sugarss
-      - supports-color
       - tsx
-      - typescript
       - uploadthing
       - yaml
 
-  astro-expressive-code@0.41.3(astro@5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1)):
+  astro-expressive-code@0.41.7(astro@6.0.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)):
+    dependencies:
+      astro: 6.0.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0)
+      rehype-expressive-code: 0.41.7
+
+  astro-expressive-code@0.44.0(astro@7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)):
     dependencies:
-      astro: 5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1)
-      rehype-expressive-code: 0.41.3
+      astro: 7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      rehype-expressive-code: 0.44.0
+      url-extras: 0.1.0
 
   astro-seo@0.8.4(prettier-plugin-astro@0.14.1)(prettier@3.6.2)(typescript@5.9.3):
     dependencies:
@@ -11008,71 +14343,63 @@ snapshots:
       - prettier-plugin-astro
       - typescript
 
-  astro@5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1):
+  astro@6.0.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0):
     dependencies:
-      '@astrojs/compiler': 2.13.0
-      '@astrojs/internal-helpers': 0.7.5
-      '@astrojs/markdown-remark': 6.3.9
+      '@astrojs/compiler': 3.0.0
+      '@astrojs/internal-helpers': 0.8.0
+      '@astrojs/markdown-remark': 7.0.0
       '@astrojs/telemetry': 3.3.0
-      '@capsizecss/unpack': 3.0.1
+      '@capsizecss/unpack': 4.0.0
+      '@clack/prompts': 1.1.0
       '@oslojs/encoding': 1.1.0
       '@rollup/pluginutils': 5.3.0(rollup@4.52.4)
-      acorn: 8.15.0
       aria-query: 5.3.2
       axobject-query: 4.1.0
-      boxen: 8.0.1
-      ci-info: 4.3.1
+      ci-info: 4.4.0
       clsx: 2.1.1
-      common-ancestor-path: 1.0.1
-      cookie: 1.0.2
-      cssesc: 3.0.0
-      debug: 4.4.3
-      deterministic-object-hash: 2.0.2
-      devalue: 5.5.0
-      diff: 5.2.0
+      common-ancestor-path: 2.0.0
+      cookie: 1.1.1
+      devalue: 5.6.3
+      diff: 8.0.3
       dlv: 1.1.3
       dset: 3.1.4
-      es-module-lexer: 1.7.0
-      esbuild: 0.25.10
-      estree-walker: 3.0.3
+      es-module-lexer: 2.0.0
+      esbuild: 0.27.3
       flattie: 1.1.1
-      fontace: 0.3.1
+      fontace: 0.4.1
       github-slugger: 2.0.0
       html-escaper: 3.0.3
       http-cache-semantics: 4.2.0
-      import-meta-resolve: 4.2.0
-      js-yaml: 4.1.1
+      js-yaml: 4.2.0
       magic-string: 0.30.21
-      magicast: 0.5.1
+      magicast: 0.5.2
       mrmime: 2.0.1
       neotraverse: 0.6.18
-      p-limit: 6.2.0
-      p-queue: 8.1.1
-      package-manager-detector: 1.5.0
+      obug: 2.1.1
+      p-limit: 7.3.0
+      p-queue: 9.1.0
+      package-manager-detector: 1.6.0
       piccolore: 0.1.3
-      picomatch: 4.0.3
-      prompts: 2.4.2
+      picomatch: 4.0.4
       rehype: 13.0.2
-      semver: 7.7.3
-      shiki: 3.15.0
-      smol-toml: 1.5.2
+      semver: 7.7.4
+      shiki: 4.0.2
+      smol-toml: 1.6.0
       svgo: 4.0.0
+      tinyclip: 0.1.12
       tinyexec: 1.0.2
       tinyglobby: 0.2.15
       tsconfck: 3.1.6(typescript@5.9.3)
       ultrahtml: 1.6.0
-      unifont: 0.6.0
-      unist-util-visit: 5.0.0
-      unstorage: 1.17.3
+      unifont: 0.7.4
+      unist-util-visit: 5.1.0
+      unstorage: 1.17.4
       vfile: 6.0.3
-      vite: 6.4.1(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1)
-      vitefu: 1.1.1(vite@6.4.1(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1))
+      vite: 7.3.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      vitefu: 1.1.2(vite@7.3.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
       xxhash-wasm: 1.1.0
-      yargs-parser: 21.1.1
-      yocto-spinner: 0.2.3
-      zod: 3.25.76
-      zod-to-json-schema: 3.24.6(zod@3.25.76)
-      zod-to-ts: 1.2.0(typescript@5.9.3)(zod@3.25.76)
+      yargs-parser: 22.0.0
+      zod: 4.3.6
     optionalDependencies:
       sharp: 0.34.4
     transitivePeerDependencies:
@@ -11110,44 +14437,136 @@ snapshots:
       - uploadthing
       - yaml
 
+  astro@7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      '@astrojs/compiler-rs': 0.2.2(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)
+      '@astrojs/internal-helpers': 0.10.0
+      '@astrojs/markdown-satteri': 0.3.2
+      '@astrojs/telemetry': 3.3.2
+      '@capsizecss/unpack': 4.0.0
+      '@clack/prompts': 1.1.0
+      '@oslojs/encoding': 1.1.0
+      '@rollup/pluginutils': 5.3.0(rollup@4.52.4)
+      am-i-vibing: 0.4.0
+      aria-query: 5.3.2
+      axobject-query: 4.1.0
+      ci-info: 4.4.0
+      clsx: 2.1.1
+      common-ancestor-path: 2.0.0
+      cookie: 1.1.1
+      devalue: 5.8.1
+      diff: 8.0.3
+      dset: 3.1.4
+      es-module-lexer: 2.0.0
+      esbuild: 0.28.1
+      flattie: 1.1.1
+      fontace: 0.4.1
+      get-tsconfig: 5.0.0-beta.4
+      github-slugger: 2.0.0
+      html-escaper: 3.0.3
+      http-cache-semantics: 4.2.0
+      js-yaml: 4.2.0
+      jsonc-parser: 3.3.1
+      magic-string: 0.30.21
+      magicast: 0.5.2
+      mrmime: 2.0.1
+      neotraverse: 0.6.18
+      obug: 2.1.1
+      p-limit: 7.3.0
+      p-queue: 9.1.0
+      package-manager-detector: 1.6.0
+      piccolore: 0.1.3
+      picomatch: 4.0.4
+      rehype: 13.0.2
+      semver: 7.7.4
+      shiki: 4.0.2
+      smol-toml: 1.6.0
+      svgo: 4.0.1
+      tinyclip: 0.1.12
+      tinyexec: 1.1.2
+      tinyglobby: 0.2.17
+      ultrahtml: 1.6.0
+      unifont: 0.7.4
+      unist-util-visit: 5.1.0
+      unstorage: 1.17.5
+      vfile: 6.0.3
+      vite: 8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      vitefu: 1.1.2(vite@8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
+      xxhash-wasm: 1.1.0
+      yargs-parser: 22.0.0
+      zod: 4.3.6
+    optionalDependencies:
+      '@astrojs/markdown-remark': 7.2.0
+      sharp: 0.34.5
+    transitivePeerDependencies:
+      - '@azure/app-configuration'
+      - '@azure/cosmos'
+      - '@azure/data-tables'
+      - '@azure/identity'
+      - '@azure/keyvault-secrets'
+      - '@azure/storage-blob'
+      - '@capacitor/preferences'
+      - '@deno/kv'
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - '@netlify/blobs'
+      - '@planetscale/database'
+      - '@types/node'
+      - '@upstash/redis'
+      - '@vercel/blob'
+      - '@vercel/functions'
+      - '@vercel/kv'
+      - '@vitejs/devtools'
+      - aws4fetch
+      - db0
+      - idb-keyval
+      - ioredis
+      - jiti
+      - less
+      - rollup
+      - sass
+      - sass-embedded
+      - stylus
+      - sugarss
+      - terser
+      - tsx
+      - uploadthing
+      - yaml
+
   async-function@1.0.0: {}
 
-  asynckit@0.4.0: {}
+  async-retry@1.3.1:
+    dependencies:
+      retry: 0.12.0
+
+  asynckit@0.4.0:
+    optional: true
 
   atomically@2.0.3:
     dependencies:
       stubborn-fs: 1.2.5
       when-exit: 2.1.4
 
-  auth-astro@4.2.0(@auth/core@0.37.4)(astro@5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1)):
+  auth-astro@4.2.0(@auth/core@0.37.4)(astro@7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)):
     dependencies:
       '@auth/core': 0.37.4
-      astro: 5.16.0(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(rollup@4.52.4)(terser@5.39.0)(typescript@5.9.3)(yaml@2.8.1)
+      astro: 7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@22.19.21)(jiti@2.7.0)(rollup@4.52.4)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
       set-cookie-parser: 2.7.1
 
-  autoprefixer@10.4.21(postcss@8.5.6):
-    dependencies:
-      browserslist: 4.26.3
-      caniuse-lite: 1.0.30001749
-      fraction.js: 4.3.7
-      normalize-range: 0.1.2
-      picocolors: 1.1.1
-      postcss: 8.5.6
-      postcss-value-parser: 4.2.0
-
   available-typed-arrays@1.0.7:
     dependencies:
       possible-typed-array-names: 1.1.0
 
   avsc@5.7.9: {}
 
-  axios@1.12.2:
+  axios@1.15.2:
     dependencies:
       follow-redirects: 1.15.11
-      form-data: 4.0.4
-      proxy-from-env: 1.1.0
+      form-data: 4.0.5
+      proxy-from-env: 2.1.0
     transitivePeerDependencies:
       - debug
+    optional: true
 
   axobject-query@4.1.0: {}
 
@@ -11155,7 +14574,7 @@ snapshots:
 
   balanced-match@1.0.2: {}
 
-  base-64@1.0.0: {}
+  balanced-match@4.0.4: {}
 
   base64-js@1.5.1: {}
 
@@ -11163,6 +14582,12 @@ snapshots:
 
   bcp-47-match@2.0.3: {}
 
+  bcp-47@2.1.0:
+    dependencies:
+      is-alphabetical: 2.0.1
+      is-alphanumerical: 2.0.1
+      is-decimal: 2.0.1
+
   better-path-resolve@1.0.0:
     dependencies:
       is-windows: 1.0.2
@@ -11173,9 +14598,34 @@ snapshots:
 
   binary-extensions@2.3.0: {}
 
-  boolbase@1.0.0: {}
+  bippy@0.3.34(@types/react@19.2.13)(react@19.2.4):
+    dependencies:
+      '@types/react-reconciler': 0.28.9(@types/react@19.2.13)
+      react: 19.2.4
+    transitivePeerDependencies:
+      - '@types/react'
+
+  bl@4.1.0:
+    dependencies:
+      buffer: 5.7.1
+      inherits: 2.0.4
+      readable-stream: 3.6.2
+
+  body-parser@2.2.2:
+    dependencies:
+      bytes: 3.1.2
+      content-type: 1.0.5
+      debug: 4.4.3
+      http-errors: 2.0.1
+      iconv-lite: 0.7.0
+      on-finished: 2.4.1
+      qs: 6.14.1
+      raw-body: 3.0.2
+      type-is: 2.0.1
+    transitivePeerDependencies:
+      - supports-color
 
-  boolean@3.2.0: {}
+  boolbase@1.0.0: {}
 
   boxen@7.1.1:
     dependencies:
@@ -11208,13 +14658,13 @@ snapshots:
     dependencies:
       balanced-match: 1.0.2
 
-  braces@3.0.3:
+  brace-expansion@5.0.3:
     dependencies:
-      fill-range: 7.1.1
+      balanced-match: 4.0.4
 
-  brotli@1.3.3:
+  braces@3.0.3:
     dependencies:
-      base64-js: 1.5.1
+      fill-range: 7.1.1
 
   browserslist@4.26.3:
     dependencies:
@@ -11228,11 +14678,24 @@ snapshots:
 
   buffer-from@1.1.2: {}
 
+  buffer@5.7.1:
+    dependencies:
+      base64-js: 1.5.1
+      ieee754: 1.2.1
+
+  builtins@1.0.3: {}
+
+  bundle-name@4.1.0:
+    dependencies:
+      run-applescript: 7.1.0
+
   bundle-require@5.1.0(esbuild@0.25.10):
     dependencies:
       esbuild: 0.25.10
       load-tsconfig: 0.2.5
 
+  bytes@3.1.2: {}
+
   cac@6.7.14: {}
 
   call-bind-apply-helpers@1.0.2:
@@ -11257,10 +14720,6 @@ snapshots:
       pascal-case: 3.1.2
       tslib: 2.8.1
 
-  camelcase-css@2.0.1: {}
-
-  camelcase@6.3.0: {}
-
   camelcase@7.0.1: {}
 
   camelcase@8.0.0: {}
@@ -11277,11 +14736,21 @@ snapshots:
       loupe: 3.2.1
       pathval: 2.0.1
 
+  chai@6.2.2: {}
+
+  chalk@2.4.2:
+    dependencies:
+      ansi-styles: 3.2.1
+      escape-string-regexp: 1.0.5
+      supports-color: 5.5.0
+
   chalk@4.1.2:
     dependencies:
       ansi-styles: 4.3.0
       supports-color: 7.2.0
 
+  chalk@5.3.0: {}
+
   chalk@5.6.2: {}
 
   character-entities-html4@2.1.0: {}
@@ -11307,6 +14776,11 @@ snapshots:
       chevrotain: 11.0.3
       lodash-es: 4.17.21
 
+  chevrotain-allstar@0.3.1(chevrotain@11.1.2):
+    dependencies:
+      chevrotain: 11.1.2
+      lodash-es: 4.17.21
+
   chevrotain@11.0.3:
     dependencies:
       '@chevrotain/cst-dts-gen': 11.0.3
@@ -11316,6 +14790,15 @@ snapshots:
       '@chevrotain/utils': 11.0.3
       lodash-es: 4.17.21
 
+  chevrotain@11.1.2:
+    dependencies:
+      '@chevrotain/cst-dts-gen': 11.1.2
+      '@chevrotain/gast': 11.1.2
+      '@chevrotain/regexp-to-ast': 11.1.2
+      '@chevrotain/types': 11.1.2
+      '@chevrotain/utils': 11.1.2
+      lodash-es: 4.17.23
+
   chokidar@3.6.0:
     dependencies:
       anymatch: 3.1.3
@@ -11332,11 +14815,13 @@ snapshots:
     dependencies:
       readdirp: 4.1.2
 
-  chownr@3.0.0: {}
+  chokidar@5.0.0:
+    dependencies:
+      readdirp: 5.0.0
 
   ci-info@3.9.0: {}
 
-  ci-info@4.3.1: {}
+  ci-info@4.4.0: {}
 
   classcat@5.0.5: {}
 
@@ -11346,6 +14831,10 @@ snapshots:
 
   cli-boxes@3.0.0: {}
 
+  cli-cursor@3.1.0:
+    dependencies:
+      restore-cursor: 3.1.0
+
   cli-cursor@5.0.0:
     dependencies:
       restore-cursor: 5.1.0
@@ -11358,41 +14847,40 @@ snapshots:
       strip-ansi: 6.0.1
       wrap-ansi: 7.0.0
 
-  clone@2.1.2: {}
+  clone@1.0.4: {}
 
   clsx@2.1.1: {}
 
-  codemirror@6.0.2:
+  cmdk@1.1.1(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     dependencies:
-      '@codemirror/autocomplete': 6.19.0
-      '@codemirror/commands': 6.9.0
-      '@codemirror/language': 6.11.3
-      '@codemirror/lint': 6.9.0
-      '@codemirror/search': 6.5.11
-      '@codemirror/state': 6.5.2
-      '@codemirror/view': 6.38.5
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.13)(react@19.2.4)
+      '@radix-ui/react-dialog': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.13)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.13))(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    transitivePeerDependencies:
+      - '@types/react'
+      - '@types/react-dom'
 
   collapse-white-space@2.1.0: {}
 
-  color-convert@2.0.1:
+  color-convert@1.9.3:
     dependencies:
-      color-name: 1.1.4
-
-  color-name@1.1.4: {}
+      color-name: 1.1.3
 
-  color-string@1.9.1:
+  color-convert@2.0.1:
     dependencies:
       color-name: 1.1.4
-      simple-swizzle: 0.2.4
 
-  color@4.2.3:
-    dependencies:
-      color-convert: 2.0.1
-      color-string: 1.9.1
+  color-name@1.1.3: {}
+
+  color-name@1.1.4: {}
 
   combined-stream@1.0.8:
     dependencies:
       delayed-stream: 1.0.0
+    optional: true
 
   comma-separated-tokens@1.0.8: {}
 
@@ -11400,13 +14888,15 @@ snapshots:
 
   commander@10.0.1: {}
 
+  commander@11.0.0: {}
+
   commander@11.1.0: {}
 
   commander@12.1.0: {}
 
-  commander@13.1.0: {}
+  commander@14.0.3: {}
 
-  commander@2.20.3: {}
+  commander@2.20.0: {}
 
   commander@4.1.1: {}
 
@@ -11414,7 +14904,7 @@ snapshots:
 
   commander@8.3.0: {}
 
-  common-ancestor-path@1.0.1: {}
+  common-ancestor-path@2.0.0: {}
 
   concat-map@0.0.1: {}
 
@@ -11448,17 +14938,33 @@ snapshots:
 
   consola@3.4.2: {}
 
-  console-table-printer@2.14.6:
-    dependencies:
-      simple-wcswidth: 1.1.2
+  content-disposition@1.0.1: {}
 
   content-type@1.0.5: {}
 
+  convert-hrtime@5.0.0: {}
+
   convert-source-map@2.0.0: {}
 
   cookie-es@1.2.2: {}
 
-  cookie@1.0.2: {}
+  cookie-es@1.2.3: {}
+
+  cookie-signature@1.2.2: {}
+
+  cookie@0.7.2: {}
+
+  cookie@1.1.1: {}
+
+  copy-file@11.1.0:
+    dependencies:
+      graceful-fs: 4.2.11
+      p-event: 6.0.1
+
+  cors@2.8.5:
+    dependencies:
+      object-assign: 4.1.1
+      vary: 1.1.2
 
   cose-base@1.0.3:
     dependencies:
@@ -11468,12 +14974,29 @@ snapshots:
     dependencies:
       layout-base: 2.0.1
 
+  cpy@11.1.0:
+    dependencies:
+      copy-file: 11.1.0
+      globby: 14.1.0
+      junk: 4.0.1
+      micromatch: 4.0.8
+      p-filter: 4.1.0
+      p-map: 7.0.4
+
   crelt@1.0.6: {}
 
   cross-env@7.0.3:
     dependencies:
       cross-spawn: 7.0.6
 
+  cross-spawn@6.0.6:
+    dependencies:
+      nice-try: 1.0.5
+      path-key: 2.0.1
+      semver: 5.7.2
+      shebang-command: 1.2.0
+      which: 1.3.1
+
   cross-spawn@7.0.6:
     dependencies:
       path-key: 3.1.1
@@ -11499,11 +15022,6 @@ snapshots:
       mdn-data: 2.0.28
       source-map-js: 1.2.1
 
-  css-tree@2.3.1:
-    dependencies:
-      mdn-data: 2.0.30
-      source-map-js: 1.2.1
-
   css-tree@3.1.0:
     dependencies:
       mdn-data: 2.12.2
@@ -11517,6 +15035,14 @@ snapshots:
     dependencies:
       css-tree: 2.2.1
 
+  cssstyle@5.3.1(postcss@8.5.15):
+    dependencies:
+      '@asamuzakjp/css-color': 4.0.5
+      '@csstools/css-syntax-patches-for-csstree': 1.0.14(postcss@8.5.15)
+      css-tree: 3.1.0
+    transitivePeerDependencies:
+      - postcss
+
   cssstyle@5.3.1(postcss@8.5.6):
     dependencies:
       '@asamuzakjp/css-color': 4.0.5
@@ -11524,10 +15050,11 @@ snapshots:
       css-tree: 3.1.0
     transitivePeerDependencies:
       - postcss
+    optional: true
 
-  csstype@3.1.3: {}
+  csstype@3.2.3: {}
 
-  cva@1.0.0-beta.2(typescript@5.9.3):
+  cva@1.0.0-beta.4(typescript@5.9.3):
     dependencies:
       clsx: 2.1.1
     optionalDependencies:
@@ -11712,10 +15239,10 @@ snapshots:
       d3-transition: 3.0.1(d3-selection@3.0.0)
       d3-zoom: 3.0.0
 
-  dagre-d3-es@7.0.11:
+  dagre-d3-es@7.0.13:
     dependencies:
       d3: 7.9.0
-      lodash-es: 4.17.21
+      lodash-es: 4.18.1
 
   dagre@0.8.5:
     dependencies:
@@ -11749,16 +15276,12 @@ snapshots:
     dependencies:
       '@babel/runtime': 7.28.4
 
-  date-fns@4.1.0: {}
-
   dayjs@1.11.18: {}
 
   debug@4.4.3:
     dependencies:
       ms: 2.1.3
 
-  decamelize@1.2.0: {}
-
   decimal.js@10.6.0: {}
 
   decode-named-character-reference@1.2.0:
@@ -11769,16 +15292,27 @@ snapshots:
 
   deep-extend@0.6.0: {}
 
-  deep-is@0.1.4: {}
-
   deepmerge-ts@7.1.5: {}
 
+  default-browser-id@5.0.1: {}
+
+  default-browser@5.5.0:
+    dependencies:
+      bundle-name: 4.1.0
+      default-browser-id: 5.0.1
+
+  defaults@1.0.4:
+    dependencies:
+      clone: 1.0.4
+
   define-data-property@1.1.4:
     dependencies:
       es-define-property: 1.0.1
       es-errors: 1.3.0
       gopd: 1.2.0
 
+  define-lazy-prop@3.0.0: {}
+
   define-properties@1.2.1:
     dependencies:
       define-data-property: 1.1.4
@@ -11787,16 +15321,21 @@ snapshots:
 
   defu@6.1.4: {}
 
+  defu@6.1.7: {}
+
   delaunator@5.0.1:
     dependencies:
       robust-predicates: 3.0.2
 
-  delayed-stream@1.0.0: {}
+  delayed-stream@1.0.0:
+    optional: true
 
   depd@2.0.0: {}
 
   dependency-graph@0.11.0: {}
 
+  dependency-graph@1.0.0: {}
+
   dequal@2.0.3: {}
 
   destr@2.0.5: {}
@@ -11809,32 +15348,22 @@ snapshots:
 
   detect-node-es@1.1.0: {}
 
-  detect-node@2.1.0: {}
-
-  deterministic-object-hash@2.0.2:
-    dependencies:
-      base-64: 1.0.0
+  devalue@5.6.3: {}
 
-  devalue@5.5.0: {}
+  devalue@5.8.1: {}
 
   devlop@1.1.0:
     dependencies:
       dequal: 2.0.3
 
-  dfa@1.2.0: {}
-
-  didyoumean@1.2.2: {}
-
-  diff2html@3.4.52:
+  diff2html@3.4.56:
     dependencies:
-      diff: 7.0.0
-      hogan.js: 3.0.2
+      '@profoundlogic/hogan': 3.0.4
+      diff: 8.0.3
     optionalDependencies:
-      highlight.js: 11.9.0
-
-  diff@5.2.0: {}
+      highlight.js: 11.11.1
 
-  diff@7.0.0: {}
+  diff@8.0.3: {}
 
   dir-glob@3.0.1:
     dependencies:
@@ -11912,6 +15441,20 @@ snapshots:
 
   encodeurl@2.0.0: {}
 
+  end-of-stream@1.4.5:
+    dependencies:
+      once: 1.4.0
+
+  enhanced-resolve@5.19.0:
+    dependencies:
+      graceful-fs: 4.2.11
+      tapable: 2.3.0
+
+  enhanced-resolve@5.21.6:
+    dependencies:
+      graceful-fs: 4.2.11
+      tapable: 2.3.3
+
   enquirer@2.4.1:
     dependencies:
       ansi-colors: 4.1.3
@@ -11921,6 +15464,8 @@ snapshots:
 
   entities@6.0.1: {}
 
+  entities@7.0.1: {}
+
   es-abstract@1.24.0:
     dependencies:
       array-buffer-byte-length: 1.0.2
@@ -11995,6 +15540,8 @@ snapshots:
 
   es-module-lexer@1.7.0: {}
 
+  es-module-lexer@2.0.0: {}
+
   es-object-atoms@1.1.1:
     dependencies:
       es-errors: 1.3.0
@@ -12012,8 +15559,6 @@ snapshots:
       is-date-object: 1.1.0
       is-symbol: 1.1.1
 
-  es6-error@4.1.1: {}
-
   esast-util-from-estree@2.0.0:
     dependencies:
       '@types/estree-jsx': 1.0.5
@@ -12024,7 +15569,7 @@ snapshots:
   esast-util-from-js@2.0.1:
     dependencies:
       '@types/estree-jsx': 1.0.5
-      acorn: 8.15.0
+      acorn: 8.16.0
       esast-util-from-estree: 2.0.0
       vfile-message: 4.0.3
 
@@ -12083,31 +15628,76 @@ snapshots:
       '@esbuild/win32-ia32': 0.25.10
       '@esbuild/win32-x64': 0.25.10
 
+  esbuild@0.27.3:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.3
+      '@esbuild/android-arm': 0.27.3
+      '@esbuild/android-arm64': 0.27.3
+      '@esbuild/android-x64': 0.27.3
+      '@esbuild/darwin-arm64': 0.27.3
+      '@esbuild/darwin-x64': 0.27.3
+      '@esbuild/freebsd-arm64': 0.27.3
+      '@esbuild/freebsd-x64': 0.27.3
+      '@esbuild/linux-arm': 0.27.3
+      '@esbuild/linux-arm64': 0.27.3
+      '@esbuild/linux-ia32': 0.27.3
+      '@esbuild/linux-loong64': 0.27.3
+      '@esbuild/linux-mips64el': 0.27.3
+      '@esbuild/linux-ppc64': 0.27.3
+      '@esbuild/linux-riscv64': 0.27.3
+      '@esbuild/linux-s390x': 0.27.3
+      '@esbuild/linux-x64': 0.27.3
+      '@esbuild/netbsd-arm64': 0.27.3
+      '@esbuild/netbsd-x64': 0.27.3
+      '@esbuild/openbsd-arm64': 0.27.3
+      '@esbuild/openbsd-x64': 0.27.3
+      '@esbuild/openharmony-arm64': 0.27.3
+      '@esbuild/sunos-x64': 0.27.3
+      '@esbuild/win32-arm64': 0.27.3
+      '@esbuild/win32-ia32': 0.27.3
+      '@esbuild/win32-x64': 0.27.3
+
+  esbuild@0.28.1:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.28.1
+      '@esbuild/android-arm': 0.28.1
+      '@esbuild/android-arm64': 0.28.1
+      '@esbuild/android-x64': 0.28.1
+      '@esbuild/darwin-arm64': 0.28.1
+      '@esbuild/darwin-x64': 0.28.1
+      '@esbuild/freebsd-arm64': 0.28.1
+      '@esbuild/freebsd-x64': 0.28.1
+      '@esbuild/linux-arm': 0.28.1
+      '@esbuild/linux-arm64': 0.28.1
+      '@esbuild/linux-ia32': 0.28.1
+      '@esbuild/linux-loong64': 0.28.1
+      '@esbuild/linux-mips64el': 0.28.1
+      '@esbuild/linux-ppc64': 0.28.1
+      '@esbuild/linux-riscv64': 0.28.1
+      '@esbuild/linux-s390x': 0.28.1
+      '@esbuild/linux-x64': 0.28.1
+      '@esbuild/netbsd-arm64': 0.28.1
+      '@esbuild/netbsd-x64': 0.28.1
+      '@esbuild/openbsd-arm64': 0.28.1
+      '@esbuild/openbsd-x64': 0.28.1
+      '@esbuild/openharmony-arm64': 0.28.1
+      '@esbuild/sunos-x64': 0.28.1
+      '@esbuild/win32-arm64': 0.28.1
+      '@esbuild/win32-ia32': 0.28.1
+      '@esbuild/win32-x64': 0.28.1
+
   escalade@3.2.0: {}
 
   escape-goat@4.0.0: {}
 
   escape-html@1.0.3: {}
 
-  escape-string-regexp@4.0.0: {}
+  escape-string-regexp@1.0.5: {}
 
   escape-string-regexp@5.0.0: {}
 
-  escodegen@1.14.3:
-    dependencies:
-      esprima: 4.0.1
-      estraverse: 4.3.0
-      esutils: 2.0.3
-      optionator: 0.8.3
-    optionalDependencies:
-      source-map: 0.6.1
-
-  esprima@1.2.2: {}
-
   esprima@4.0.1: {}
 
-  estraverse@4.3.0: {}
-
   estree-util-attach-comments@3.0.0:
     dependencies:
       '@types/estree': 1.0.8
@@ -12143,26 +15733,81 @@ snapshots:
     dependencies:
       '@types/estree': 1.0.8
 
-  esutils@2.0.3: {}
-
   etag@1.8.1: {}
 
   event-target-shim@5.0.1: {}
 
-  eventemitter3@4.0.7: {}
-
   eventemitter3@5.0.1: {}
 
   eventsource-parser@3.0.6: {}
 
+  eventsource@3.0.7:
+    dependencies:
+      eventsource-parser: 3.0.6
+
+  execa@1.0.0:
+    dependencies:
+      cross-spawn: 6.0.6
+      get-stream: 4.1.0
+      is-stream: 1.1.0
+      npm-run-path: 2.0.2
+      p-finally: 1.0.0
+      signal-exit: 3.0.7
+      strip-eof: 1.0.0
+
   expect-type@1.2.2: {}
 
-  expressive-code@0.41.3:
+  express-rate-limit@8.2.1(express@5.2.1):
+    dependencies:
+      express: 5.2.1
+      ip-address: 10.0.1
+
+  express@5.2.1:
+    dependencies:
+      accepts: 2.0.0
+      body-parser: 2.2.2
+      content-disposition: 1.0.1
+      content-type: 1.0.5
+      cookie: 0.7.2
+      cookie-signature: 1.2.2
+      debug: 4.4.3
+      depd: 2.0.0
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      finalhandler: 2.1.1
+      fresh: 2.0.0
+      http-errors: 2.0.1
+      merge-descriptors: 2.0.0
+      mime-types: 3.0.2
+      on-finished: 2.4.1
+      once: 1.4.0
+      parseurl: 1.3.3
+      proxy-addr: 2.0.7
+      qs: 6.14.1
+      range-parser: 1.2.1
+      router: 2.2.0
+      send: 1.2.1
+      serve-static: 2.2.1
+      statuses: 2.0.2
+      type-is: 2.0.1
+      vary: 1.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  expressive-code@0.41.7:
+    dependencies:
+      '@expressive-code/core': 0.41.7
+      '@expressive-code/plugin-frames': 0.41.7
+      '@expressive-code/plugin-shiki': 0.41.7
+      '@expressive-code/plugin-text-markers': 0.41.7
+
+  expressive-code@0.44.0:
     dependencies:
-      '@expressive-code/core': 0.41.3
-      '@expressive-code/plugin-frames': 0.41.3
-      '@expressive-code/plugin-shiki': 0.41.3
-      '@expressive-code/plugin-text-markers': 0.41.3
+      '@expressive-code/core': 0.44.0
+      '@expressive-code/plugin-frames': 0.44.0
+      '@expressive-code/plugin-shiki': 0.44.0
+      '@expressive-code/plugin-text-markers': 0.44.0
 
   exsolve@1.0.7: {}
 
@@ -12184,19 +15829,23 @@ snapshots:
       merge2: 1.4.1
       micromatch: 4.0.8
 
-  fast-levenshtein@2.0.6: {}
-
   fast-memoize@2.5.2: {}
 
   fast-uri@3.1.0: {}
 
+  fast-xml-builder@1.1.4:
+    dependencies:
+      path-expression-matcher: 1.2.1
+
   fast-xml-parser@4.5.3:
     dependencies:
       strnum: 1.1.2
 
-  fast-xml-parser@5.3.0:
+  fast-xml-parser@5.5.10:
     dependencies:
-      strnum: 2.1.1
+      fast-xml-builder: 1.1.4
+      path-expression-matcher: 1.2.1
+      strnum: 2.2.2
 
   fastq@1.19.1:
     dependencies:
@@ -12206,14 +15855,25 @@ snapshots:
     dependencies:
       format: 0.2.2
 
-  fdir@6.5.0(picomatch@4.0.3):
+  fdir@6.5.0(picomatch@4.0.4):
     optionalDependencies:
-      picomatch: 4.0.3
+      picomatch: 4.0.4
 
   fill-range@7.1.1:
     dependencies:
       to-regex-range: 5.0.1
 
+  finalhandler@2.1.1:
+    dependencies:
+      debug: 4.4.3
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      on-finished: 2.4.1
+      parseurl: 1.3.3
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
   find-up@4.1.0:
     dependencies:
       locate-path: 5.0.0
@@ -12221,38 +15881,28 @@ snapshots:
 
   fix-dts-default-cjs-exports@1.0.1:
     dependencies:
-      magic-string: 0.30.19
+      magic-string: 0.30.21
       mlly: 1.8.0
       rollup: 4.52.4
 
-  flatbuffers@25.9.23: {}
-
-  flatted@3.3.3: {}
+  flatted@3.4.2: {}
 
   flattie@1.1.1: {}
 
-  focus-trap@7.6.5:
+  focus-trap@7.8.0:
     dependencies:
-      tabbable: 6.2.0
+      tabbable: 6.4.0
 
-  follow-redirects@1.15.11: {}
+  follow-redirects@1.15.11:
+    optional: true
 
-  fontace@0.3.1:
+  fontace@0.4.1:
     dependencies:
-      '@types/fontkit': 2.0.8
-      fontkit: 2.0.4
+      fontkitten: 1.0.3
 
-  fontkit@2.0.4:
+  fontkitten@1.0.3:
     dependencies:
-      '@swc/helpers': 0.5.17
-      brotli: 1.3.3
-      clone: 2.1.2
-      dfa: 1.2.0
-      fast-deep-equal: 3.1.3
-      restructure: 3.0.2
       tiny-inflate: 1.0.3
-      unicode-properties: 1.4.1
-      unicode-trie: 2.0.0
 
   for-each@0.3.5:
     dependencies:
@@ -12265,27 +15915,27 @@ snapshots:
       cross-spawn: 7.0.6
       signal-exit: 4.1.0
 
-  form-data-encoder@1.7.2: {}
-
-  form-data@4.0.4:
+  form-data@4.0.5:
     dependencies:
       asynckit: 0.4.0
       combined-stream: 1.0.8
       es-set-tostringtag: 2.1.0
       hasown: 2.0.2
       mime-types: 2.1.35
+    optional: true
 
   format@0.2.2: {}
 
-  formdata-node@4.4.1:
-    dependencies:
-      node-domexception: 1.0.0
-      web-streams-polyfill: 4.0.0-beta.3
-
-  fraction.js@4.3.7: {}
+  forwarded@0.2.0: {}
 
   fresh@2.0.0: {}
 
+  fs-extra@11.1.1:
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 6.2.0
+      universalify: 2.0.1
+
   fs-extra@11.3.2:
     dependencies:
       graceful-fs: 4.2.11
@@ -12304,8 +15954,6 @@ snapshots:
       jsonfile: 4.0.0
       universalify: 0.1.2
 
-  fs.realpath@1.0.0: {}
-
   fsevents@2.3.2:
     optional: true
 
@@ -12314,6 +15962,8 @@ snapshots:
 
   function-bind@1.1.2: {}
 
+  function-timeout@1.0.2: {}
+
   function.prototype.name@1.1.8:
     dependencies:
       call-bind: 1.0.8
@@ -12357,19 +16007,27 @@ snapshots:
       dunder-proto: 1.0.1
       es-object-atoms: 1.1.1
 
+  get-stream@4.1.0:
+    dependencies:
+      pump: 3.0.3
+
   get-symbol-description@1.1.0:
     dependencies:
       call-bound: 1.0.4
       es-errors: 1.3.0
       get-intrinsic: 1.3.0
 
-  github-slugger@2.0.0: {}
+  get-tsconfig@4.13.6:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
 
-  glob-parent@5.1.2:
+  get-tsconfig@5.0.0-beta.4:
     dependencies:
-      is-glob: 4.0.3
+      resolve-pkg-maps: 1.0.0
+
+  github-slugger@2.0.0: {}
 
-  glob-parent@6.0.2:
+  glob-parent@5.1.2:
     dependencies:
       is-glob: 4.0.3
 
@@ -12382,32 +16040,26 @@ snapshots:
       package-json-from-dist: 1.0.1
       path-scurry: 1.11.1
 
-  glob@11.0.3:
+  glob@11.1.0:
     dependencies:
       foreground-child: 3.3.1
       jackspeak: 4.1.1
-      minimatch: 10.0.3
+      minimatch: 10.1.2
       minipass: 7.1.2
       package-json-from-dist: 1.0.1
       path-scurry: 2.0.0
 
-  glob@7.2.3:
+  glob@13.0.2:
     dependencies:
-      fs.realpath: 1.0.0
-      inflight: 1.0.6
-      inherits: 2.0.4
-      minimatch: 3.1.2
-      once: 1.4.0
-      path-is-absolute: 1.0.1
+      minimatch: 10.2.2
+      minipass: 7.1.2
+      path-scurry: 2.0.0
 
-  global-agent@3.0.0:
+  glob@13.0.6:
     dependencies:
-      boolean: 3.2.0
-      es6-error: 4.1.1
-      matcher: 3.0.0
-      roarr: 2.15.4
-      semver: 7.6.3
-      serialize-error: 7.0.1
+      minimatch: 10.2.2
+      minipass: 7.1.3
+      path-scurry: 2.0.2
 
   global-directory@4.0.1:
     dependencies:
@@ -12429,6 +16081,15 @@ snapshots:
       merge2: 1.4.1
       slash: 3.0.0
 
+  globby@14.1.0:
+    dependencies:
+      '@sindresorhus/merge-streams': 2.3.0
+      fast-glob: 3.3.3
+      ignore: 7.0.5
+      path-type: 6.0.0
+      slash: 5.1.0
+      unicorn-magic: 0.3.0
+
   globrex@0.1.2: {}
 
   gopd@1.2.0: {}
@@ -12448,24 +16109,38 @@ snapshots:
       section-matter: 1.0.0
       strip-bom-string: 1.0.0
 
-  guid-typescript@1.0.9: {}
+  guess-json-indent@3.0.1: {}
+
+  h3@1.15.11:
+    dependencies:
+      cookie-es: 1.2.3
+      crossws: 0.3.5
+      defu: 6.1.7
+      destr: 2.0.5
+      iron-webcrypto: 1.2.1
+      node-mock-http: 1.0.4
+      radix3: 1.1.2
+      ufo: 1.6.3
+      uncrypto: 0.1.3
 
-  h3@1.15.4:
+  h3@1.15.5:
     dependencies:
       cookie-es: 1.2.2
       crossws: 0.3.5
       defu: 6.1.4
       destr: 2.0.5
       iron-webcrypto: 1.2.1
-      node-mock-http: 1.0.3
+      node-mock-http: 1.0.4
       radix3: 1.1.2
-      ufo: 1.6.1
+      ufo: 1.6.3
       uncrypto: 0.1.3
 
   hachure-fill@0.5.2: {}
 
   has-bigints@1.1.0: {}
 
+  has-flag@3.0.0: {}
+
   has-flag@4.0.0: {}
 
   has-property-descriptors@1.0.2:
@@ -12499,7 +16174,7 @@ snapshots:
       hast-util-phrasing: 3.0.1
       hast-util-whitespace: 3.0.0
       html-whitespace-sensitive-tag-names: 3.0.1
-      unist-util-visit-parents: 6.0.1
+      unist-util-visit-parents: 6.0.2
 
   hast-util-from-html@2.0.3:
     dependencies:
@@ -12570,7 +16245,7 @@ snapshots:
       mdast-util-to-hast: 13.2.0
       parse5: 7.3.0
       unist-util-position: 5.0.0
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
       vfile: 6.0.3
       web-namespaces: 2.0.1
       zwitch: 2.0.4
@@ -12596,7 +16271,7 @@ snapshots:
       nth-check: 2.1.1
       property-information: 7.1.0
       space-separated-tokens: 2.0.2
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
       zwitch: 2.0.4
 
   hast-util-to-estree@3.1.3:
@@ -12699,19 +16374,11 @@ snapshots:
 
   highlight.js@11.11.1: {}
 
-  highlight.js@11.9.0:
-    optional: true
-
-  highlightjs-curl@1.3.0: {}
-
   highlightjs-vue@1.0.0: {}
 
-  hogan.js@3.0.2:
-    dependencies:
-      mkdirp: 0.3.0
-      nopt: 1.0.10
+  hono@4.12.25: {}
 
-  hookable@5.5.3: {}
+  hookable@6.1.0: {}
 
   html-encoding-sniffer@4.0.0:
     dependencies:
@@ -12727,7 +16394,7 @@ snapshots:
       entities: 4.5.0
       param-case: 3.0.4
       relateurl: 0.2.7
-      terser: 5.39.0
+      terser: 5.46.0
 
   html-to-image@1.11.13: {}
 
@@ -12739,12 +16406,12 @@ snapshots:
 
   http-cache-semantics@4.2.0: {}
 
-  http-errors@2.0.0:
+  http-errors@2.0.1:
     dependencies:
       depd: 2.0.0
       inherits: 2.0.4
       setprototypeof: 1.2.0
-      statuses: 2.0.1
+      statuses: 2.0.2
       toidentifier: 1.0.1
 
   http-proxy-agent@7.0.2:
@@ -12763,9 +16430,9 @@ snapshots:
 
   human-id@4.1.2: {}
 
-  humanize-ms@1.2.1:
+  i18next@23.16.8:
     dependencies:
-      ms: 2.1.3
+      '@babel/runtime': 7.28.4
 
   iconv-lite@0.6.3:
     dependencies:
@@ -12775,16 +16442,17 @@ snapshots:
     dependencies:
       safer-buffer: 2.1.2
 
-  ignore@5.3.2: {}
+  identifier-regex@1.0.1:
+    dependencies:
+      reserved-identifiers: 1.2.0
 
-  immer@9.0.21: {}
+  ieee754@1.2.1: {}
 
-  import-meta-resolve@4.2.0: {}
+  ignore@5.3.2: {}
 
-  inflight@1.0.6:
-    dependencies:
-      once: 1.4.0
-      wrappy: 1.0.2
+  ignore@7.0.5: {}
+
+  immer@9.0.21: {}
 
   inherits@2.0.4: {}
 
@@ -12806,6 +16474,10 @@ snapshots:
 
   interpret@1.4.0: {}
 
+  ip-address@10.0.1: {}
+
+  ipaddr.js@1.9.1: {}
+
   iron-webcrypto@1.2.1: {}
 
   is-absolute-url@4.0.1: {}
@@ -12830,8 +16502,6 @@ snapshots:
       call-bound: 1.0.4
       get-intrinsic: 1.3.0
 
-  is-arrayish@0.3.4: {}
-
   is-async-function@2.1.1:
     dependencies:
       async-function: 1.0.0
@@ -12853,8 +16523,6 @@ snapshots:
       call-bound: 1.0.4
       has-tostringtag: 1.0.2
 
-  is-buffer@2.0.5: {}
-
   is-callable@1.2.7: {}
 
   is-core-module@2.16.1:
@@ -12878,6 +16546,8 @@ snapshots:
 
   is-docker@3.0.0: {}
 
+  is-docker@4.0.0: {}
+
   is-extendable@0.1.1: {}
 
   is-extglob@2.1.1: {}
@@ -12904,8 +16574,15 @@ snapshots:
 
   is-hexadecimal@2.0.1: {}
 
+  is-identifier@1.0.1:
+    dependencies:
+      identifier-regex: 1.0.1
+      super-regex: 1.1.0
+
   is-in-ci@1.0.0: {}
 
+  is-in-ssh@1.0.0: {}
+
   is-inside-container@1.0.0:
     dependencies:
       is-docker: 3.0.0
@@ -12915,6 +16592,8 @@ snapshots:
       global-directory: 4.0.1
       is-path-inside: 4.0.0
 
+  is-interactive@1.0.0: {}
+
   is-interactive@2.0.0: {}
 
   is-map@2.0.3: {}
@@ -12938,6 +16617,8 @@ snapshots:
 
   is-potential-custom-element-name@1.0.1: {}
 
+  is-promise@4.0.0: {}
+
   is-regex@1.2.1:
     dependencies:
       call-bound: 1.0.4
@@ -12953,6 +16634,8 @@ snapshots:
     dependencies:
       call-bound: 1.0.4
 
+  is-stream@1.1.0: {}
+
   is-string@1.1.1:
     dependencies:
       call-bound: 1.0.4
@@ -12972,6 +16655,8 @@ snapshots:
     dependencies:
       which-typed-array: 1.1.19
 
+  is-unicode-supported@0.1.0: {}
+
   is-unicode-supported@1.3.0: {}
 
   is-unicode-supported@2.1.0: {}
@@ -12993,14 +16678,18 @@ snapshots:
     dependencies:
       is-inside-container: 1.0.0
 
+  is-wsl@3.1.1:
+    dependencies:
+      is-inside-container: 1.0.0
+
   isarray@2.0.5: {}
 
   isexe@2.0.0: {}
 
-  isomorphic-dompurify@2.28.0(postcss@8.5.6):
+  isomorphic-dompurify@2.28.0(postcss@8.5.15):
     dependencies:
       dompurify: 3.2.7
-      jsdom: 27.0.0(postcss@8.5.6)
+      jsdom: 27.0.0(postcss@8.5.15)
     transitivePeerDependencies:
       - bufferutil
       - canvas
@@ -13018,31 +16707,63 @@ snapshots:
     dependencies:
       '@isaacs/cliui': 8.0.2
 
-  jiti@1.21.7: {}
+  jiti@2.6.1: {}
+
+  jiti@2.7.0: {}
 
   jose@5.10.0: {}
 
+  jose@6.1.3: {}
+
   joycon@3.1.1: {}
 
-  js-tiktoken@1.0.21:
-    dependencies:
-      base64-js: 1.5.1
+  js-base64@3.7.8: {}
 
   js-tokens@4.0.0: {}
 
+  js-tokens@9.0.1: {}
+
   js-yaml@3.14.1:
     dependencies:
       argparse: 1.0.10
       esprima: 4.0.1
 
-  js-yaml@4.1.0:
+  js-yaml@4.1.1:
     dependencies:
       argparse: 2.0.1
 
-  js-yaml@4.1.1:
+  js-yaml@4.2.0:
     dependencies:
       argparse: 2.0.1
 
+  jsdom@27.0.0(postcss@8.5.15):
+    dependencies:
+      '@asamuzakjp/dom-selector': 6.6.1
+      cssstyle: 5.3.1(postcss@8.5.15)
+      data-urls: 6.0.0
+      decimal.js: 10.6.0
+      html-encoding-sniffer: 4.0.0
+      http-proxy-agent: 7.0.2
+      https-proxy-agent: 7.0.6
+      is-potential-custom-element-name: 1.0.1
+      parse5: 7.3.0
+      rrweb-cssom: 0.8.0
+      saxes: 6.0.0
+      symbol-tree: 3.2.4
+      tough-cookie: 6.0.0
+      w3c-xmlserializer: 5.0.0
+      webidl-conversions: 8.0.0
+      whatwg-encoding: 3.1.1
+      whatwg-mimetype: 4.0.0
+      whatwg-url: 15.1.0
+      ws: 8.18.3
+      xml-name-validator: 5.0.0
+    transitivePeerDependencies:
+      - bufferutil
+      - postcss
+      - supports-color
+      - utf-8-validate
+
   jsdom@27.0.0(postcss@8.5.6):
     dependencies:
       '@asamuzakjp/dom-selector': 6.6.1
@@ -13070,6 +16791,7 @@ snapshots:
       - postcss
       - supports-color
       - utf-8-validate
+    optional: true
 
   jsep@1.4.0: {}
 
@@ -13081,11 +16803,9 @@ snapshots:
 
   json-schema-traverse@1.0.0: {}
 
-  json-schema@0.4.0: {}
-
-  json-stringify-deterministic@1.0.12: {}
+  json-schema-typed@8.0.2: {}
 
-  json-stringify-safe@5.0.1: {}
+  json-schema@0.4.0: {}
 
   json5@2.2.3: {}
 
@@ -13105,20 +16825,16 @@ snapshots:
     optionalDependencies:
       graceful-fs: 4.2.11
 
-  jsonpath-plus@10.3.0:
+  jsonpath-plus@10.4.0:
     dependencies:
       '@jsep-plugin/assignment': 1.3.0(jsep@1.4.0)
       '@jsep-plugin/regex': 1.0.4(jsep@1.4.0)
       jsep: 1.4.0
 
-  jsonpath@1.1.1:
-    dependencies:
-      esprima: 1.2.2
-      static-eval: 2.0.2
-      underscore: 1.12.1
-
   jsonpointer@5.0.1: {}
 
+  jsonschema@1.4.1: {}
+
   jsonwebtoken@9.0.2:
     dependencies:
       jws: 3.2.2
@@ -13130,11 +16846,9 @@ snapshots:
       lodash.isstring: 4.0.1
       lodash.once: 4.1.1
       ms: 2.1.3
-      semver: 7.6.3
+      semver: 7.7.4
 
-  just-clone@6.2.0: {}
-
-  just-curry-it@5.3.0: {}
+  junk@4.0.1: {}
 
   jwa@1.4.2:
     dependencies:
@@ -13159,32 +16873,26 @@ snapshots:
 
   kleur@4.1.5: {}
 
+  klona@2.0.6: {}
+
   kolorist@1.8.0: {}
 
   ky@1.11.0: {}
 
-  langchain@0.3.35(@langchain/core@0.3.78(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76)))(@opentelemetry/api@1.9.0)(axios@1.12.2)(openai@4.104.0(ws@8.18.3)(zod@3.25.76))(ws@8.18.3):
+  langium-cli@3.5.2:
     dependencies:
-      '@langchain/core': 0.3.78(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76))
-      '@langchain/openai': 0.6.14(@langchain/core@0.3.78(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76)))(ws@8.18.3)
-      '@langchain/textsplitters': 0.1.0(@langchain/core@0.3.78(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76)))
-      js-tiktoken: 1.0.21
-      js-yaml: 4.1.0
-      jsonpointer: 5.0.1
-      langsmith: 0.3.73(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76))
-      openapi-types: 12.1.3
-      p-retry: 4.6.2
-      uuid: 10.0.0
-      yaml: 2.8.1
-      zod: 3.25.76
-    optionalDependencies:
-      axios: 1.12.2
-    transitivePeerDependencies:
-      - '@opentelemetry/api'
-      - '@opentelemetry/exporter-trace-otlp-proto'
-      - '@opentelemetry/sdk-trace-base'
-      - openai
-      - ws
+      chalk: 5.3.0
+      commander: 11.0.0
+      fs-extra: 11.1.1
+      jsonschema: 1.4.1
+      langium: 3.5.0
+      langium-railroad: 3.5.0
+      lodash: 4.17.21
+
+  langium-railroad@3.5.0:
+    dependencies:
+      langium: 3.5.0
+      railroad-diagrams: 1.0.0
 
   langium@3.3.1:
     dependencies:
@@ -13194,18 +16902,21 @@ snapshots:
       vscode-languageserver-textdocument: 1.0.12
       vscode-uri: 3.0.8
 
-  langsmith@0.3.73(@opentelemetry/api@1.9.0)(openai@4.104.0(ws@8.18.3)(zod@3.25.76)):
+  langium@3.5.0:
     dependencies:
-      '@types/uuid': 10.0.0
-      chalk: 4.1.2
-      console-table-printer: 2.14.6
-      p-queue: 6.6.2
-      p-retry: 4.6.2
-      semver: 7.6.3
-      uuid: 10.0.0
-    optionalDependencies:
-      '@opentelemetry/api': 1.9.0
-      openai: 4.104.0(ws@8.18.3)(zod@3.25.76)
+      chevrotain: 11.0.3
+      chevrotain-allstar: 0.3.1(chevrotain@11.0.3)
+      vscode-languageserver: 9.0.1
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-uri: 3.0.8
+
+  langium@4.2.1:
+    dependencies:
+      chevrotain: 11.1.2
+      chevrotain-allstar: 0.3.1(chevrotain@11.1.2)
+      vscode-languageserver: 9.0.1
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-uri: 3.1.0
 
   latest-version@9.0.0:
     dependencies:
@@ -13217,57 +16928,103 @@ snapshots:
 
   leven@3.1.0: {}
 
-  leven@4.1.0: {}
+  lightningcss-android-arm64@1.30.2:
+    optional: true
 
-  levn@0.3.0:
-    dependencies:
-      prelude-ls: 1.1.2
-      type-check: 0.3.2
+  lightningcss-android-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-arm64@1.30.2:
+    optional: true
+
+  lightningcss-darwin-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-x64@1.30.2:
+    optional: true
+
+  lightningcss-darwin-x64@1.32.0:
+    optional: true
+
+  lightningcss-freebsd-x64@1.30.2:
+    optional: true
+
+  lightningcss-freebsd-x64@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.30.2:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.30.2:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    optional: true
 
-  lightningcss-darwin-arm64@1.29.3:
+  lightningcss-linux-arm64-musl@1.30.2:
     optional: true
 
-  lightningcss-darwin-x64@1.29.3:
+  lightningcss-linux-arm64-musl@1.32.0:
     optional: true
 
-  lightningcss-freebsd-x64@1.29.3:
+  lightningcss-linux-x64-gnu@1.30.2:
     optional: true
 
-  lightningcss-linux-arm-gnueabihf@1.29.3:
+  lightningcss-linux-x64-gnu@1.32.0:
     optional: true
 
-  lightningcss-linux-arm64-gnu@1.29.3:
+  lightningcss-linux-x64-musl@1.30.2:
     optional: true
 
-  lightningcss-linux-arm64-musl@1.29.3:
+  lightningcss-linux-x64-musl@1.32.0:
     optional: true
 
-  lightningcss-linux-x64-gnu@1.29.3:
+  lightningcss-win32-arm64-msvc@1.30.2:
     optional: true
 
-  lightningcss-linux-x64-musl@1.29.3:
+  lightningcss-win32-arm64-msvc@1.32.0:
     optional: true
 
-  lightningcss-win32-arm64-msvc@1.29.3:
+  lightningcss-win32-x64-msvc@1.30.2:
     optional: true
 
-  lightningcss-win32-x64-msvc@1.29.3:
+  lightningcss-win32-x64-msvc@1.32.0:
     optional: true
 
-  lightningcss@1.29.3:
+  lightningcss@1.30.2:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.30.2
+      lightningcss-darwin-arm64: 1.30.2
+      lightningcss-darwin-x64: 1.30.2
+      lightningcss-freebsd-x64: 1.30.2
+      lightningcss-linux-arm-gnueabihf: 1.30.2
+      lightningcss-linux-arm64-gnu: 1.30.2
+      lightningcss-linux-arm64-musl: 1.30.2
+      lightningcss-linux-x64-gnu: 1.30.2
+      lightningcss-linux-x64-musl: 1.30.2
+      lightningcss-win32-arm64-msvc: 1.30.2
+      lightningcss-win32-x64-msvc: 1.30.2
+
+  lightningcss@1.32.0:
     dependencies:
       detect-libc: 2.1.2
     optionalDependencies:
-      lightningcss-darwin-arm64: 1.29.3
-      lightningcss-darwin-x64: 1.29.3
-      lightningcss-freebsd-x64: 1.29.3
-      lightningcss-linux-arm-gnueabihf: 1.29.3
-      lightningcss-linux-arm64-gnu: 1.29.3
-      lightningcss-linux-arm64-musl: 1.29.3
-      lightningcss-linux-x64-gnu: 1.29.3
-      lightningcss-linux-x64-musl: 1.29.3
-      lightningcss-win32-arm64-msvc: 1.29.3
-      lightningcss-win32-x64-msvc: 1.29.3
+      lightningcss-android-arm64: 1.32.0
+      lightningcss-darwin-arm64: 1.32.0
+      lightningcss-darwin-x64: 1.32.0
+      lightningcss-freebsd-x64: 1.32.0
+      lightningcss-linux-arm-gnueabihf: 1.32.0
+      lightningcss-linux-arm64-gnu: 1.32.0
+      lightningcss-linux-arm64-musl: 1.32.0
+      lightningcss-linux-x64-gnu: 1.32.0
+      lightningcss-linux-x64-musl: 1.32.0
+      lightningcss-win32-arm64-msvc: 1.32.0
+      lightningcss-win32-x64-msvc: 1.32.0
 
   lilconfig@3.1.3: {}
 
@@ -13287,6 +17044,10 @@ snapshots:
 
   lodash-es@4.17.21: {}
 
+  lodash-es@4.17.23: {}
+
+  lodash-es@4.18.1: {}
+
   lodash.debounce@4.0.8: {}
 
   lodash.includes@4.3.0: {}
@@ -13313,6 +17074,11 @@ snapshots:
 
   lodash@4.17.21: {}
 
+  log-symbols@4.1.0:
+    dependencies:
+      chalk: 4.1.2
+      is-unicode-supported: 0.1.0
+
   log-symbols@6.0.0:
     dependencies:
       chalk: 5.6.2
@@ -13347,6 +17113,8 @@ snapshots:
 
   lru-cache@11.2.2: {}
 
+  lru-cache@11.3.6: {}
+
   lru-cache@5.1.1:
     dependencies:
       yallist: 3.1.1
@@ -13359,41 +17127,45 @@ snapshots:
     dependencies:
       react: 18.3.1
 
-  magic-string@0.30.19:
+  lucide-react@0.563.0(react@19.2.4):
     dependencies:
-      '@jridgewell/sourcemap-codec': 1.5.5
+      react: 19.2.4
 
   magic-string@0.30.21:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
 
-  magicast@0.5.1:
+  magicast@0.5.2:
     dependencies:
-      '@babel/parser': 7.28.5
-      '@babel/types': 7.28.5
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
       source-map-js: 1.2.1
 
+  make-asynchronous@1.1.0:
+    dependencies:
+      p-event: 6.0.1
+      type-fest: 4.41.0
+      web-worker: 1.5.0
+
   markdown-extensions@2.0.0: {}
 
   markdown-table@3.0.4: {}
 
+  marked@14.0.0: {}
+
   marked@15.0.12: {}
 
   marked@16.4.0: {}
 
   marked@4.3.0: {}
 
-  matcher@3.0.0:
-    dependencies:
-      escape-string-regexp: 4.0.0
-
   math-intrinsics@1.1.0: {}
 
   mdast-util-definitions@6.0.0:
     dependencies:
       '@types/mdast': 4.0.4
       '@types/unist': 3.0.3
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
 
   mdast-util-directive@3.1.0:
     dependencies:
@@ -13405,17 +17177,10 @@ snapshots:
       mdast-util-to-markdown: 2.1.2
       parse-entities: 4.0.2
       stringify-entities: 4.0.4
-      unist-util-visit-parents: 6.0.1
+      unist-util-visit-parents: 6.0.2
     transitivePeerDependencies:
       - supports-color
 
-  mdast-util-find-and-replace@2.2.2:
-    dependencies:
-      '@types/mdast': 3.0.15
-      escape-string-regexp: 5.0.0
-      unist-util-is: 5.2.1
-      unist-util-visit-parents: 5.1.3
-
   mdast-util-find-and-replace@3.0.2:
     dependencies:
       '@types/mdast': 4.0.4
@@ -13423,23 +17188,6 @@ snapshots:
       unist-util-is: 6.0.0
       unist-util-visit-parents: 6.0.2
 
-  mdast-util-from-markdown@1.3.1:
-    dependencies:
-      '@types/mdast': 3.0.15
-      '@types/unist': 2.0.11
-      decode-named-character-reference: 1.2.0
-      mdast-util-to-string: 3.2.0
-      micromark: 3.2.0
-      micromark-util-decode-numeric-character-reference: 1.1.0
-      micromark-util-decode-string: 1.1.0
-      micromark-util-normalize-identifier: 1.1.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-      unist-util-stringify-position: 3.0.3
-      uvu: 0.5.6
-    transitivePeerDependencies:
-      - supports-color
-
   mdast-util-from-markdown@2.0.2:
     dependencies:
       '@types/mdast': 4.0.4
@@ -13457,13 +17205,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  mdast-util-gfm-autolink-literal@1.0.3:
-    dependencies:
-      '@types/mdast': 3.0.15
-      ccount: 2.0.1
-      mdast-util-find-and-replace: 2.2.2
-      micromark-util-character: 1.2.0
-
   mdast-util-gfm-autolink-literal@2.0.1:
     dependencies:
       '@types/mdast': 4.0.4
@@ -13472,12 +17213,6 @@ snapshots:
       mdast-util-find-and-replace: 3.0.2
       micromark-util-character: 2.1.1
 
-  mdast-util-gfm-footnote@1.0.2:
-    dependencies:
-      '@types/mdast': 3.0.15
-      mdast-util-to-markdown: 1.5.0
-      micromark-util-normalize-identifier: 1.1.0
-
   mdast-util-gfm-footnote@2.1.0:
     dependencies:
       '@types/mdast': 4.0.4
@@ -13488,11 +17223,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  mdast-util-gfm-strikethrough@1.0.3:
-    dependencies:
-      '@types/mdast': 3.0.15
-      mdast-util-to-markdown: 1.5.0
-
   mdast-util-gfm-strikethrough@2.0.0:
     dependencies:
       '@types/mdast': 4.0.4
@@ -13501,15 +17231,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  mdast-util-gfm-table@1.0.7:
-    dependencies:
-      '@types/mdast': 3.0.15
-      markdown-table: 3.0.4
-      mdast-util-from-markdown: 1.3.1
-      mdast-util-to-markdown: 1.5.0
-    transitivePeerDependencies:
-      - supports-color
-
   mdast-util-gfm-table@2.0.0:
     dependencies:
       '@types/mdast': 4.0.4
@@ -13520,11 +17241,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  mdast-util-gfm-task-list-item@1.0.2:
-    dependencies:
-      '@types/mdast': 3.0.15
-      mdast-util-to-markdown: 1.5.0
-
   mdast-util-gfm-task-list-item@2.0.0:
     dependencies:
       '@types/mdast': 4.0.4
@@ -13534,18 +17250,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  mdast-util-gfm@2.0.2:
-    dependencies:
-      mdast-util-from-markdown: 1.3.1
-      mdast-util-gfm-autolink-literal: 1.0.3
-      mdast-util-gfm-footnote: 1.0.2
-      mdast-util-gfm-strikethrough: 1.0.3
-      mdast-util-gfm-table: 1.0.7
-      mdast-util-gfm-task-list-item: 1.0.2
-      mdast-util-to-markdown: 1.5.0
-    transitivePeerDependencies:
-      - supports-color
-
   mdast-util-gfm@3.1.0:
     dependencies:
       mdast-util-from-markdown: 2.0.2
@@ -13607,11 +17311,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  mdast-util-phrasing@3.0.1:
-    dependencies:
-      '@types/mdast': 3.0.15
-      unist-util-is: 5.2.1
-
   mdast-util-phrasing@4.1.0:
     dependencies:
       '@types/mdast': 4.0.4
@@ -13626,20 +17325,9 @@ snapshots:
       micromark-util-sanitize-uri: 2.0.1
       trim-lines: 3.0.1
       unist-util-position: 5.0.0
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
       vfile: 6.0.3
 
-  mdast-util-to-markdown@1.5.0:
-    dependencies:
-      '@types/mdast': 3.0.15
-      '@types/unist': 2.0.11
-      longest-streak: 3.1.0
-      mdast-util-phrasing: 3.0.1
-      mdast-util-to-string: 3.2.0
-      micromark-util-decode-string: 1.1.0
-      unist-util-visit: 4.1.2
-      zwitch: 2.0.4
-
   mdast-util-to-markdown@2.1.2:
     dependencies:
       '@types/mdast': 4.0.4
@@ -13649,42 +17337,40 @@ snapshots:
       mdast-util-to-string: 4.0.0
       micromark-util-classify-character: 2.0.1
       micromark-util-decode-string: 2.0.1
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
       zwitch: 2.0.4
 
-  mdast-util-to-string@3.2.0:
-    dependencies:
-      '@types/mdast': 3.0.15
-
   mdast-util-to-string@4.0.0:
     dependencies:
       '@types/mdast': 4.0.4
 
   mdn-data@2.0.28: {}
 
-  mdn-data@2.0.30: {}
-
   mdn-data@2.12.2: {}
 
+  media-typer@1.1.0: {}
+
+  merge-descriptors@2.0.0: {}
+
   merge2@1.4.1: {}
 
-  mermaid@11.12.0:
+  mermaid@11.12.3:
     dependencies:
       '@braintree/sanitize-url': 7.1.1
       '@iconify/utils': 3.0.2
-      '@mermaid-js/parser': 0.6.3
+      '@mermaid-js/parser': 1.1.0
       '@types/d3': 7.4.3
       cytoscape: 3.33.1
       cytoscape-cose-bilkent: 4.1.0(cytoscape@3.33.1)
       cytoscape-fcose: 2.2.0(cytoscape@3.33.1)
       d3: 7.9.0
       d3-sankey: 0.12.3
-      dagre-d3-es: 7.0.11
+      dagre-d3-es: 7.0.13
       dayjs: 1.11.18
       dompurify: 3.2.7
       katex: 0.16.23
       khroma: 2.1.0
-      lodash-es: 4.17.21
+      lodash-es: 4.18.1
       marked: 16.4.0
       roughjs: 4.6.6
       stylis: 4.3.6
@@ -13695,25 +17381,6 @@ snapshots:
 
   microdiff@1.5.0: {}
 
-  micromark-core-commonmark@1.1.0:
-    dependencies:
-      decode-named-character-reference: 1.2.0
-      micromark-factory-destination: 1.1.0
-      micromark-factory-label: 1.1.0
-      micromark-factory-space: 1.1.0
-      micromark-factory-title: 1.1.0
-      micromark-factory-whitespace: 1.1.0
-      micromark-util-character: 1.2.0
-      micromark-util-chunked: 1.1.0
-      micromark-util-classify-character: 1.1.0
-      micromark-util-html-tag-name: 1.2.0
-      micromark-util-normalize-identifier: 1.1.0
-      micromark-util-resolve-all: 1.1.0
-      micromark-util-subtokenize: 1.1.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-      uvu: 0.5.6
-
   micromark-core-commonmark@2.0.3:
     dependencies:
       decode-named-character-reference: 1.2.0
@@ -13743,30 +17410,12 @@ snapshots:
       micromark-util-types: 2.0.2
       parse-entities: 4.0.2
 
-  micromark-extension-gfm-autolink-literal@1.0.5:
-    dependencies:
-      micromark-util-character: 1.2.0
-      micromark-util-sanitize-uri: 1.2.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-
   micromark-extension-gfm-autolink-literal@2.1.0:
     dependencies:
-      micromark-util-character: 2.1.1
-      micromark-util-sanitize-uri: 2.0.1
-      micromark-util-symbol: 2.0.1
-      micromark-util-types: 2.0.2
-
-  micromark-extension-gfm-footnote@1.1.2:
-    dependencies:
-      micromark-core-commonmark: 1.1.0
-      micromark-factory-space: 1.1.0
-      micromark-util-character: 1.2.0
-      micromark-util-normalize-identifier: 1.1.0
-      micromark-util-sanitize-uri: 1.2.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-      uvu: 0.5.6
+      micromark-util-character: 2.1.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
 
   micromark-extension-gfm-footnote@2.1.0:
     dependencies:
@@ -13779,15 +17428,6 @@ snapshots:
       micromark-util-symbol: 2.0.1
       micromark-util-types: 2.0.2
 
-  micromark-extension-gfm-strikethrough@1.0.7:
-    dependencies:
-      micromark-util-chunked: 1.1.0
-      micromark-util-classify-character: 1.1.0
-      micromark-util-resolve-all: 1.1.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-      uvu: 0.5.6
-
   micromark-extension-gfm-strikethrough@2.1.0:
     dependencies:
       devlop: 1.1.0
@@ -13797,14 +17437,6 @@ snapshots:
       micromark-util-symbol: 2.0.1
       micromark-util-types: 2.0.2
 
-  micromark-extension-gfm-table@1.0.7:
-    dependencies:
-      micromark-factory-space: 1.1.0
-      micromark-util-character: 1.2.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-      uvu: 0.5.6
-
   micromark-extension-gfm-table@2.1.1:
     dependencies:
       devlop: 1.1.0
@@ -13813,22 +17445,10 @@ snapshots:
       micromark-util-symbol: 2.0.1
       micromark-util-types: 2.0.2
 
-  micromark-extension-gfm-tagfilter@1.0.2:
-    dependencies:
-      micromark-util-types: 1.1.0
-
   micromark-extension-gfm-tagfilter@2.0.0:
     dependencies:
       micromark-util-types: 2.0.2
 
-  micromark-extension-gfm-task-list-item@1.0.5:
-    dependencies:
-      micromark-factory-space: 1.1.0
-      micromark-util-character: 1.2.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-      uvu: 0.5.6
-
   micromark-extension-gfm-task-list-item@2.1.0:
     dependencies:
       devlop: 1.1.0
@@ -13837,17 +17457,6 @@ snapshots:
       micromark-util-symbol: 2.0.1
       micromark-util-types: 2.0.2
 
-  micromark-extension-gfm@2.0.3:
-    dependencies:
-      micromark-extension-gfm-autolink-literal: 1.0.5
-      micromark-extension-gfm-footnote: 1.1.2
-      micromark-extension-gfm-strikethrough: 1.0.7
-      micromark-extension-gfm-table: 1.0.7
-      micromark-extension-gfm-tagfilter: 1.0.2
-      micromark-extension-gfm-task-list-item: 1.0.5
-      micromark-util-combine-extensions: 1.1.0
-      micromark-util-types: 1.1.0
-
   micromark-extension-gfm@3.0.0:
     dependencies:
       micromark-extension-gfm-autolink-literal: 2.1.0
@@ -13901,8 +17510,8 @@ snapshots:
 
   micromark-extension-mdxjs@3.0.0:
     dependencies:
-      acorn: 8.15.0
-      acorn-jsx: 5.3.2(acorn@8.15.0)
+      acorn: 8.16.0
+      acorn-jsx: 5.3.2(acorn@8.16.0)
       micromark-extension-mdx-expression: 3.0.1
       micromark-extension-mdx-jsx: 3.0.2
       micromark-extension-mdx-md: 2.0.0
@@ -13910,25 +17519,12 @@ snapshots:
       micromark-util-combine-extensions: 2.0.1
       micromark-util-types: 2.0.2
 
-  micromark-factory-destination@1.1.0:
-    dependencies:
-      micromark-util-character: 1.2.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-
   micromark-factory-destination@2.0.1:
     dependencies:
       micromark-util-character: 2.1.1
       micromark-util-symbol: 2.0.1
       micromark-util-types: 2.0.2
 
-  micromark-factory-label@1.1.0:
-    dependencies:
-      micromark-util-character: 1.2.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-      uvu: 0.5.6
-
   micromark-factory-label@2.0.1:
     dependencies:
       devlop: 1.1.0
@@ -13958,13 +17554,6 @@ snapshots:
       micromark-util-character: 2.1.1
       micromark-util-types: 2.0.2
 
-  micromark-factory-title@1.1.0:
-    dependencies:
-      micromark-factory-space: 1.1.0
-      micromark-util-character: 1.2.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-
   micromark-factory-title@2.0.1:
     dependencies:
       micromark-factory-space: 2.0.1
@@ -13972,13 +17561,6 @@ snapshots:
       micromark-util-symbol: 2.0.1
       micromark-util-types: 2.0.2
 
-  micromark-factory-whitespace@1.1.0:
-    dependencies:
-      micromark-factory-space: 1.1.0
-      micromark-util-character: 1.2.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-
   micromark-factory-whitespace@2.0.1:
     dependencies:
       micromark-factory-space: 2.0.1
@@ -13996,51 +17578,25 @@ snapshots:
       micromark-util-symbol: 2.0.1
       micromark-util-types: 2.0.2
 
-  micromark-util-chunked@1.1.0:
-    dependencies:
-      micromark-util-symbol: 1.1.0
-
   micromark-util-chunked@2.0.1:
     dependencies:
       micromark-util-symbol: 2.0.1
 
-  micromark-util-classify-character@1.1.0:
-    dependencies:
-      micromark-util-character: 1.2.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-
   micromark-util-classify-character@2.0.1:
     dependencies:
       micromark-util-character: 2.1.1
       micromark-util-symbol: 2.0.1
       micromark-util-types: 2.0.2
 
-  micromark-util-combine-extensions@1.1.0:
-    dependencies:
-      micromark-util-chunked: 1.1.0
-      micromark-util-types: 1.1.0
-
   micromark-util-combine-extensions@2.0.1:
     dependencies:
       micromark-util-chunked: 2.0.1
       micromark-util-types: 2.0.2
 
-  micromark-util-decode-numeric-character-reference@1.1.0:
-    dependencies:
-      micromark-util-symbol: 1.1.0
-
   micromark-util-decode-numeric-character-reference@2.0.2:
     dependencies:
       micromark-util-symbol: 2.0.1
 
-  micromark-util-decode-string@1.1.0:
-    dependencies:
-      decode-named-character-reference: 1.2.0
-      micromark-util-character: 1.2.0
-      micromark-util-decode-numeric-character-reference: 1.1.0
-      micromark-util-symbol: 1.1.0
-
   micromark-util-decode-string@2.0.1:
     dependencies:
       decode-named-character-reference: 1.2.0
@@ -14048,8 +17604,6 @@ snapshots:
       micromark-util-decode-numeric-character-reference: 2.0.2
       micromark-util-symbol: 2.0.1
 
-  micromark-util-encode@1.1.0: {}
-
   micromark-util-encode@2.0.1: {}
 
   micromark-util-events-to-acorn@2.0.3:
@@ -14062,45 +17616,22 @@ snapshots:
       micromark-util-types: 2.0.2
       vfile-message: 4.0.3
 
-  micromark-util-html-tag-name@1.2.0: {}
-
   micromark-util-html-tag-name@2.0.1: {}
 
-  micromark-util-normalize-identifier@1.1.0:
-    dependencies:
-      micromark-util-symbol: 1.1.0
-
   micromark-util-normalize-identifier@2.0.1:
     dependencies:
       micromark-util-symbol: 2.0.1
 
-  micromark-util-resolve-all@1.1.0:
-    dependencies:
-      micromark-util-types: 1.1.0
-
   micromark-util-resolve-all@2.0.1:
     dependencies:
       micromark-util-types: 2.0.2
 
-  micromark-util-sanitize-uri@1.2.0:
-    dependencies:
-      micromark-util-character: 1.2.0
-      micromark-util-encode: 1.1.0
-      micromark-util-symbol: 1.1.0
-
   micromark-util-sanitize-uri@2.0.1:
     dependencies:
       micromark-util-character: 2.1.1
       micromark-util-encode: 2.0.1
       micromark-util-symbol: 2.0.1
 
-  micromark-util-subtokenize@1.1.0:
-    dependencies:
-      micromark-util-chunked: 1.1.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-      uvu: 0.5.6
-
   micromark-util-subtokenize@2.1.0:
     dependencies:
       devlop: 1.1.0
@@ -14116,28 +17647,6 @@ snapshots:
 
   micromark-util-types@2.0.2: {}
 
-  micromark@3.2.0:
-    dependencies:
-      '@types/debug': 4.1.12
-      debug: 4.4.3
-      decode-named-character-reference: 1.2.0
-      micromark-core-commonmark: 1.1.0
-      micromark-factory-space: 1.1.0
-      micromark-util-character: 1.2.0
-      micromark-util-chunked: 1.1.0
-      micromark-util-combine-extensions: 1.1.0
-      micromark-util-decode-numeric-character-reference: 1.1.0
-      micromark-util-encode: 1.1.0
-      micromark-util-normalize-identifier: 1.1.0
-      micromark-util-resolve-all: 1.1.0
-      micromark-util-sanitize-uri: 1.2.0
-      micromark-util-subtokenize: 1.1.0
-      micromark-util-symbol: 1.1.0
-      micromark-util-types: 1.1.0
-      uvu: 0.5.6
-    transitivePeerDependencies:
-      - supports-color
-
   micromark@4.0.2:
     dependencies:
       '@types/debug': 4.1.12
@@ -14165,28 +17674,40 @@ snapshots:
       braces: 3.0.3
       picomatch: 2.3.1
 
-  mime-db@1.52.0: {}
+  mime-db@1.52.0:
+    optional: true
 
   mime-db@1.54.0: {}
 
   mime-types@2.1.35:
     dependencies:
       mime-db: 1.52.0
+    optional: true
 
-  mime-types@3.0.1:
+  mime-types@3.0.2:
     dependencies:
       mime-db: 1.54.0
 
+  mimic-fn@2.1.0: {}
+
   mimic-function@5.0.1: {}
 
-  minimatch@10.0.3:
+  minimatch@10.1.2:
+    dependencies:
+      '@isaacs/brace-expansion': 5.0.1
+
+  minimatch@10.2.2:
     dependencies:
-      '@isaacs/brace-expansion': 5.0.0
+      brace-expansion: 5.0.3
 
   minimatch@3.1.2:
     dependencies:
       brace-expansion: 1.1.12
 
+  minimatch@5.1.6:
+    dependencies:
+      brace-expansion: 2.0.2
+
   minimatch@9.0.5:
     dependencies:
       brace-expansion: 2.0.2
@@ -14195,18 +17716,21 @@ snapshots:
 
   minipass@7.1.2: {}
 
-  minizlib@3.1.0:
-    dependencies:
-      minipass: 7.1.2
+  minipass@7.1.3: {}
 
-  mkdirp@0.3.0: {}
+  minisearch@7.2.0: {}
 
   mlly@1.8.0:
     dependencies:
-      acorn: 8.15.0
+      acorn: 8.16.0
       pathe: 2.0.3
       pkg-types: 1.3.1
-      ufo: 1.6.1
+      ufo: 1.6.3
+
+  monaco-editor@0.55.1:
+    dependencies:
+      dompurify: 3.2.7
+      marked: 14.0.0
 
   mri@1.2.0: {}
 
@@ -14216,8 +17740,6 @@ snapshots:
 
   muggle-string@0.4.1: {}
 
-  mustache@4.2.0: {}
-
   mz@2.7.0:
     dependencies:
       any-promise: 1.3.0
@@ -14226,10 +17748,22 @@ snapshots:
 
   nanoid@3.3.11: {}
 
+  nanoid@3.3.12: {}
+
   nanoid@5.1.6: {}
 
+  nanostores@1.1.0: {}
+
+  negotiator@1.0.0: {}
+
   neotraverse@0.6.18: {}
 
+  neverpanic@0.0.7(typescript@5.9.3):
+    dependencies:
+      typescript: 5.9.3
+
+  nice-try@1.0.5: {}
+
   nimma@0.2.3:
     dependencies:
       '@jsep-plugin/regex': 1.0.4(jsep@1.4.0)
@@ -14237,7 +17771,7 @@ snapshots:
       astring: 1.9.0
       jsep: 1.4.0
     optionalDependencies:
-      jsonpath-plus: 10.3.0
+      jsonpath-plus: 10.4.0
       lodash.topath: 4.5.2
 
   nlcst-to-string@4.0.0:
@@ -14251,8 +17785,6 @@ snapshots:
 
   node-addon-api@7.1.1: {}
 
-  node-domexception@1.0.0: {}
-
   node-fetch-native@1.6.7: {}
 
   node-fetch@2.6.7:
@@ -14263,7 +17795,7 @@ snapshots:
     dependencies:
       whatwg-url: 5.0.0
 
-  node-mock-http@1.0.3: {}
+  node-mock-http@1.0.4: {}
 
   node-releases@2.0.23: {}
 
@@ -14273,7 +17805,9 @@ snapshots:
 
   normalize-path@3.0.0: {}
 
-  normalize-range@0.1.2: {}
+  npm-run-path@2.0.2:
+    dependencies:
+      path-key: 2.0.1
 
   nth-check@2.1.1:
     dependencies:
@@ -14283,8 +17817,6 @@ snapshots:
 
   object-assign@4.1.1: {}
 
-  object-hash@3.0.0: {}
-
   object-inspect@1.13.4: {}
 
   object-keys@1.1.1: {}
@@ -14298,17 +17830,13 @@ snapshots:
       has-symbols: 1.1.0
       object-keys: 1.1.1
 
-  ofetch@1.4.1:
-    dependencies:
-      destr: 2.0.5
-      node-fetch-native: 1.6.7
-      ufo: 1.6.1
+  obug@2.1.1: {}
 
   ofetch@1.5.1:
     dependencies:
       destr: 2.0.5
       node-fetch-native: 1.6.7
-      ufo: 1.6.1
+      ufo: 1.6.3
 
   ohash@2.0.11: {}
 
@@ -14320,56 +17848,30 @@ snapshots:
     dependencies:
       wrappy: 1.0.2
 
+  onetime@5.1.2:
+    dependencies:
+      mimic-fn: 2.1.0
+
   onetime@7.0.0:
     dependencies:
       mimic-function: 5.0.1
 
   oniguruma-parser@0.12.1: {}
 
-  oniguruma-to-es@4.3.3:
+  oniguruma-to-es@4.3.4:
     dependencies:
       oniguruma-parser: 0.12.1
       regex: 6.0.1
       regex-recursion: 6.0.2
 
-  onnxruntime-common@1.21.0: {}
-
-  onnxruntime-common@1.22.0-dev.20250409-89f8206ba4: {}
-
-  onnxruntime-node@1.21.0:
-    dependencies:
-      global-agent: 3.0.0
-      onnxruntime-common: 1.21.0
-      tar: 7.5.1
-
-  onnxruntime-web@1.22.0-dev.20250409-89f8206ba4:
+  open@11.0.0:
     dependencies:
-      flatbuffers: 25.9.23
-      guid-typescript: 1.0.9
-      long: 5.3.2
-      onnxruntime-common: 1.22.0-dev.20250409-89f8206ba4
-      platform: 1.3.6
-      protobufjs: 7.5.4
-
-  openai@4.104.0(ws@8.18.3)(zod@3.25.76):
-    dependencies:
-      '@types/node': 18.19.129
-      '@types/node-fetch': 2.6.13
-      abort-controller: 3.0.0
-      agentkeepalive: 4.6.0
-      form-data-encoder: 1.7.2
-      formdata-node: 4.4.1
-      node-fetch: 2.7.0
-    optionalDependencies:
-      ws: 8.18.3
-      zod: 3.25.76
-    transitivePeerDependencies:
-      - encoding
-
-  openai@5.12.2(ws@8.18.3)(zod@3.25.76):
-    optionalDependencies:
-      ws: 8.18.3
-      zod: 3.25.76
+      default-browser: 5.5.0
+      define-lazy-prop: 3.0.0
+      is-in-ssh: 1.0.0
+      is-inside-container: 1.0.0
+      powershell-utils: 0.1.0
+      wsl-utils: 0.3.1
 
   openapi-sampler@1.6.1:
     dependencies:
@@ -14377,16 +17879,17 @@ snapshots:
       fast-xml-parser: 4.5.3
       json-pointer: 0.6.2
 
-  openapi-types@12.1.3: {}
-
-  optionator@0.8.3:
+  ora@5.4.1:
     dependencies:
-      deep-is: 0.1.4
-      fast-levenshtein: 2.0.6
-      levn: 0.3.0
-      prelude-ls: 1.1.2
-      type-check: 0.3.2
-      word-wrap: 1.2.5
+      bl: 4.1.0
+      chalk: 4.1.2
+      cli-cursor: 3.1.0
+      cli-spinners: 2.9.2
+      is-interactive: 1.0.0
+      is-unicode-supported: 0.1.0
+      log-symbols: 4.1.0
+      strip-ansi: 6.0.1
+      wcwidth: 1.0.1
 
   ora@8.2.0:
     dependencies:
@@ -14408,17 +17911,25 @@ snapshots:
       object-keys: 1.1.1
       safe-push-apply: 1.0.0
 
+  p-event@6.0.1:
+    dependencies:
+      p-timeout: 6.1.4
+
   p-filter@2.1.0:
     dependencies:
       p-map: 2.1.0
 
+  p-filter@4.1.0:
+    dependencies:
+      p-map: 7.0.4
+
   p-finally@1.0.0: {}
 
   p-limit@2.3.0:
     dependencies:
       p-try: 2.2.0
 
-  p-limit@6.2.0:
+  p-limit@7.3.0:
     dependencies:
       yocto-queue: 1.2.1
 
@@ -14428,27 +17939,17 @@ snapshots:
 
   p-map@2.1.0: {}
 
-  p-queue@6.6.2:
-    dependencies:
-      eventemitter3: 4.0.7
-      p-timeout: 3.2.0
+  p-map@7.0.4: {}
 
-  p-queue@8.1.1:
+  p-queue@9.1.0:
     dependencies:
       eventemitter3: 5.0.1
-      p-timeout: 6.1.4
-
-  p-retry@4.6.2:
-    dependencies:
-      '@types/retry': 0.12.0
-      retry: 0.13.1
-
-  p-timeout@3.2.0:
-    dependencies:
-      p-finally: 1.0.0
+      p-timeout: 7.0.1
 
   p-timeout@6.1.4: {}
 
+  p-timeout@7.0.1: {}
+
   p-try@2.2.0: {}
 
   package-json-from-dist@1.0.1: {}
@@ -14458,17 +17959,13 @@ snapshots:
       ky: 1.11.0
       registry-auth-token: 5.1.0
       registry-url: 6.0.1
-      semver: 7.6.3
+      semver: 7.7.4
 
   package-manager-detector@0.2.11:
     dependencies:
       quansync: 0.2.11
 
-  package-manager-detector@1.4.0: {}
-
-  package-manager-detector@1.5.0: {}
-
-  packrup@0.1.2: {}
+  package-manager-detector@1.6.0: {}
 
   pagefind@1.4.0:
     optionalDependencies:
@@ -14479,7 +17976,15 @@ snapshots:
       '@pagefind/linux-x64': 1.4.0
       '@pagefind/windows-x64': 1.4.0
 
-  pako@0.2.9: {}
+  pagefind@1.5.2:
+    optionalDependencies:
+      '@pagefind/darwin-arm64': 1.5.2
+      '@pagefind/darwin-x64': 1.5.2
+      '@pagefind/freebsd-x64': 1.5.2
+      '@pagefind/linux-arm64': 1.5.2
+      '@pagefind/linux-x64': 1.5.2
+      '@pagefind/windows-arm64': 1.5.2
+      '@pagefind/windows-x64': 1.5.2
 
   pako@2.1.0: {}
 
@@ -14516,12 +18021,14 @@ snapshots:
       unist-util-visit-children: 3.0.0
       vfile: 6.0.3
 
-  parse-ms@3.0.0: {}
+  parse-ms@4.0.0: {}
 
   parse5@7.3.0:
     dependencies:
       entities: 6.0.1
 
+  parseurl@1.3.3: {}
+
   pascal-case@3.1.2:
     dependencies:
       no-case: 3.0.4
@@ -14533,7 +18040,9 @@ snapshots:
 
   path-exists@4.0.0: {}
 
-  path-is-absolute@1.0.1: {}
+  path-expression-matcher@1.2.1: {}
+
+  path-key@2.0.1: {}
 
   path-key@3.1.1: {}
 
@@ -14549,9 +18058,16 @@ snapshots:
       lru-cache: 11.2.2
       minipass: 7.1.2
 
+  path-scurry@2.0.2:
+    dependencies:
+      lru-cache: 11.2.2
+      minipass: 7.1.3
+
+  path-to-regexp@8.3.0: {}
+
   path-type@4.0.0: {}
 
-  pathe@1.1.2: {}
+  path-type@6.0.0: {}
 
   pathe@2.0.3: {}
 
@@ -14563,7 +18079,7 @@ snapshots:
 
   picomatch@2.3.1: {}
 
-  picomatch@4.0.3: {}
+  picomatch@4.0.4: {}
 
   pify@2.3.0: {}
 
@@ -14571,6 +18087,8 @@ snapshots:
 
   pirates@4.0.7: {}
 
+  pkce-challenge@5.0.1: {}
+
   pkg-types@1.3.1:
     dependencies:
       confbox: 0.1.8
@@ -14583,13 +18101,11 @@ snapshots:
       exsolve: 1.0.7
       pathe: 2.0.3
 
-  platform@1.3.6: {}
-
-  playwright-core@1.56.0: {}
+  playwright-core@1.58.2: {}
 
-  playwright@1.56.0:
+  playwright@1.58.2:
     dependencies:
-      playwright-core: 1.56.0
+      playwright-core: 1.58.2
     optionalDependencies:
       fsevents: 2.3.2
 
@@ -14604,38 +18120,62 @@ snapshots:
 
   possible-typed-array-names@1.1.0: {}
 
-  postcss-import@15.1.0(postcss@8.5.6):
+  postcss-cli@11.0.1(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0):
     dependencies:
+      chokidar: 3.6.0
+      dependency-graph: 1.0.0
+      fs-extra: 11.3.2
+      picocolors: 1.1.1
       postcss: 8.5.6
-      postcss-value-parser: 4.2.0
+      postcss-load-config: 5.1.0(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0)
+      postcss-reporter: 7.1.0(postcss@8.5.6)
+      pretty-hrtime: 1.0.3
       read-cache: 1.0.0
-      resolve: 1.22.10
+      slash: 5.1.0
+      tinyglobby: 0.2.15
+      yargs: 17.7.2
+    transitivePeerDependencies:
+      - jiti
+      - tsx
 
-  postcss-js@4.1.0(postcss@8.5.6):
+  postcss-load-config@5.1.0(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0):
     dependencies:
-      camelcase-css: 2.0.1
+      lilconfig: 3.1.3
+      yaml: 2.8.1
+    optionalDependencies:
+      jiti: 2.7.0
       postcss: 8.5.6
+      tsx: 4.21.0
 
-  postcss-load-config@4.0.2(postcss@8.5.6):
+  postcss-load-config@6.0.1(jiti@2.7.0)(postcss@8.5.15)(tsx@4.21.0)(yaml@2.9.0):
     dependencies:
       lilconfig: 3.1.3
-      yaml: 2.8.1
     optionalDependencies:
-      postcss: 8.5.6
+      jiti: 2.7.0
+      postcss: 8.5.15
+      tsx: 4.21.0
+      yaml: 2.9.0
 
-  postcss-load-config@6.0.1(jiti@1.21.7)(postcss@8.5.6)(yaml@2.8.1):
+  postcss-load-config@6.0.1(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0)(yaml@2.9.0):
     dependencies:
       lilconfig: 3.1.3
     optionalDependencies:
-      jiti: 1.21.7
+      jiti: 2.7.0
       postcss: 8.5.6
-      yaml: 2.8.1
+      tsx: 4.21.0
+      yaml: 2.9.0
 
-  postcss-nested@6.2.0(postcss@8.5.6):
+  postcss-nested@6.2.0(postcss@8.5.15):
     dependencies:
-      postcss: 8.5.6
+      postcss: 8.5.15
       postcss-selector-parser: 6.1.2
 
+  postcss-reporter@7.1.0(postcss@8.5.6):
+    dependencies:
+      picocolors: 1.1.1
+      postcss: 8.5.6
+      thenby: 1.3.4
+
   postcss-selector-parser@6.0.10:
     dependencies:
       cssesc: 3.0.0
@@ -14646,7 +18186,11 @@ snapshots:
       cssesc: 3.0.0
       util-deprecate: 1.0.2
 
-  postcss-value-parser@4.2.0: {}
+  postcss@8.5.15:
+    dependencies:
+      nanoid: 3.3.12
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
 
   postcss@8.5.6:
     dependencies:
@@ -14654,13 +18198,15 @@ snapshots:
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
+  powershell-utils@0.1.0: {}
+
   preact-render-to-string@6.5.11(preact@10.24.3):
     dependencies:
       preact: 10.24.3
 
   preact@10.24.3: {}
 
-  prelude-ls@1.1.2: {}
+  preact@10.28.3: {}
 
   prettier-plugin-astro@0.14.1:
     dependencies:
@@ -14668,24 +18214,21 @@ snapshots:
       prettier: 3.6.2
       sass-formatter: 0.7.9
 
-  prettier@2.8.7:
-    optional: true
-
   prettier@2.8.8: {}
 
   prettier@3.6.2: {}
 
-  pretty-bytes@6.1.1: {}
+  pretty-hrtime@1.0.3: {}
 
-  pretty-ms@8.0.0:
+  pretty-ms@9.3.0:
     dependencies:
-      parse-ms: 3.0.0
-
-  prismjs@1.27.0: {}
+      parse-ms: 4.0.0
 
   prismjs@1.30.0: {}
 
-  prompts@2.4.2:
+  process-ancestry@0.1.0: {}
+
+  prompts@2.1.0:
     dependencies:
       kleur: 3.0.3
       sisteransi: 1.0.5
@@ -14721,7 +18264,18 @@ snapshots:
       '@types/node': 20.19.19
       long: 5.3.2
 
-  proxy-from-env@1.1.0: {}
+  proxy-addr@2.0.7:
+    dependencies:
+      forwarded: 0.2.0
+      ipaddr.js: 1.9.1
+
+  proxy-from-env@2.1.0:
+    optional: true
+
+  pump@3.0.3:
+    dependencies:
+      end-of-stream: 1.4.5
+      once: 1.4.0
 
   punycode@2.3.1: {}
 
@@ -14729,31 +18283,44 @@ snapshots:
     dependencies:
       escape-goat: 4.0.0
 
+  qs@6.14.1:
+    dependencies:
+      side-channel: 1.1.0
+
   quansync@0.2.11: {}
 
   queue-microtask@1.2.3: {}
 
-  radix-vue@1.9.17(vue@3.5.22(typescript@5.9.3)):
+  radix-vue@1.9.17(vue@3.5.32(typescript@5.9.3)):
     dependencies:
       '@floating-ui/dom': 1.7.4
-      '@floating-ui/vue': 1.1.9(vue@3.5.22(typescript@5.9.3))
+      '@floating-ui/vue': 1.1.9(vue@3.5.32(typescript@5.9.3))
       '@internationalized/date': 3.10.0
       '@internationalized/number': 3.6.5
-      '@tanstack/vue-virtual': 3.13.12(vue@3.5.22(typescript@5.9.3))
-      '@vueuse/core': 10.11.1(vue@3.5.22(typescript@5.9.3))
-      '@vueuse/shared': 10.11.1(vue@3.5.22(typescript@5.9.3))
+      '@tanstack/vue-virtual': 3.13.12(vue@3.5.32(typescript@5.9.3))
+      '@vueuse/core': 10.11.1(vue@3.5.32(typescript@5.9.3))
+      '@vueuse/shared': 10.11.1(vue@3.5.32(typescript@5.9.3))
       aria-hidden: 1.2.6
-      defu: 6.1.4
+      defu: 6.1.7
       fast-deep-equal: 3.1.3
       nanoid: 5.1.6
-      vue: 3.5.22(typescript@5.9.3)
+      vue: 3.5.32(typescript@5.9.3)
     transitivePeerDependencies:
       - '@vue/composition-api'
 
   radix3@1.1.2: {}
 
+  railroad-diagrams@1.0.0: {}
+
   range-parser@1.2.1: {}
 
+  raw-body@3.0.2:
+    dependencies:
+      bytes: 3.1.2
+      http-errors: 2.0.1
+      iconv-lite: 0.7.0
+      unpipe: 1.0.0
+
   rc@1.2.8:
     dependencies:
       deep-extend: 0.6.0
@@ -14767,11 +18334,21 @@ snapshots:
       react: 18.3.1
       scheduler: 0.23.2
 
-  react-markdown@10.1.0(@types/react@18.3.26)(react@18.3.1):
+  react-dom@19.2.4(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+      scheduler: 0.27.0
+
+  react-error-boundary@4.1.2(react@18.3.1):
+    dependencies:
+      '@babel/runtime': 7.28.4
+      react: 18.3.1
+
+  react-markdown@10.1.0(@types/react@19.2.13)(react@18.3.1):
     dependencies:
       '@types/hast': 3.0.4
       '@types/mdast': 4.0.4
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
       devlop: 1.1.0
       hast-util-to-jsx-runtime: 2.3.6
       html-url-attributes: 3.0.1
@@ -14785,34 +18362,107 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  react-refresh@0.17.0: {}
-
-  react-remove-scroll-bar@2.3.8(@types/react@18.3.26)(react@18.3.1):
-    dependencies:
-      react: 18.3.1
-      react-style-singleton: 2.2.3(@types/react@18.3.26)(react@18.3.1)
-      tslib: 2.8.1
-    optionalDependencies:
-      '@types/react': 18.3.26
-
-  react-remove-scroll@2.7.1(@types/react@18.3.26)(react@18.3.1):
+  react-refresh@0.17.0: {}
+
+  react-refresh@0.18.0: {}
+
+  react-remove-scroll-bar@2.3.8(@types/react@19.2.13)(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      react-style-singleton: 2.2.3(@types/react@19.2.13)(react@18.3.1)
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.13
+
+  react-remove-scroll-bar@2.3.8(@types/react@19.2.13)(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+      react-style-singleton: 2.2.3(@types/react@19.2.13)(react@19.2.4)
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.13
+
+  react-remove-scroll@2.7.1(@types/react@19.2.13)(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      react-remove-scroll-bar: 2.3.8(@types/react@19.2.13)(react@18.3.1)
+      react-style-singleton: 2.2.3(@types/react@19.2.13)(react@18.3.1)
+      tslib: 2.8.1
+      use-callback-ref: 1.3.3(@types/react@19.2.13)(react@18.3.1)
+      use-sidecar: 1.1.3(@types/react@19.2.13)(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 19.2.13
+
+  react-remove-scroll@2.7.1(@types/react@19.2.13)(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+      react-remove-scroll-bar: 2.3.8(@types/react@19.2.13)(react@19.2.4)
+      react-style-singleton: 2.2.3(@types/react@19.2.13)(react@19.2.4)
+      tslib: 2.8.1
+      use-callback-ref: 1.3.3(@types/react@19.2.13)(react@19.2.4)
+      use-sidecar: 1.1.3(@types/react@19.2.13)(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.13
+
+  react-router-dom@7.13.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      react-router: 7.13.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+
+  react-router@7.13.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
+    dependencies:
+      cookie: 1.1.1
+      react: 19.2.4
+      set-cookie-parser: 2.7.1
+    optionalDependencies:
+      react-dom: 19.2.4(react@19.2.4)
+
+  react-scan@0.4.3(@types/react@19.2.13)(react-dom@19.2.4(react@19.2.4))(react-router-dom@7.13.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-router@7.13.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react@19.2.4)(rollup@4.52.4):
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/generator': 7.29.1
+      '@babel/types': 7.29.0
+      '@clack/core': 0.3.5
+      '@clack/prompts': 0.8.2
+      '@pivanov/utils': 0.0.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@preact/signals': 1.3.4(preact@10.28.3)
+      '@rollup/pluginutils': 5.3.0(rollup@4.52.4)
+      '@types/node': 20.19.19
+      bippy: 0.3.34(@types/react@19.2.13)(react@19.2.4)
+      esbuild: 0.25.10
+      estree-walker: 3.0.3
+      kleur: 4.1.5
+      mri: 1.2.0
+      playwright: 1.58.2
+      preact: 10.28.3
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      tsx: 4.21.0
+    optionalDependencies:
+      react-router: 7.13.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react-router-dom: 7.13.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      unplugin: 2.1.0
+    transitivePeerDependencies:
+      - '@types/react'
+      - rollup
+      - supports-color
+
+  react-style-singleton@2.2.3(@types/react@19.2.13)(react@18.3.1):
     dependencies:
+      get-nonce: 1.0.1
       react: 18.3.1
-      react-remove-scroll-bar: 2.3.8(@types/react@18.3.26)(react@18.3.1)
-      react-style-singleton: 2.2.3(@types/react@18.3.26)(react@18.3.1)
       tslib: 2.8.1
-      use-callback-ref: 1.3.3(@types/react@18.3.26)(react@18.3.1)
-      use-sidecar: 1.1.3(@types/react@18.3.26)(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
 
-  react-style-singleton@2.2.3(@types/react@18.3.26)(react@18.3.1):
+  react-style-singleton@2.2.3(@types/react@19.2.13)(react@19.2.4):
     dependencies:
       get-nonce: 1.0.1
-      react: 18.3.1
+      react: 19.2.4
       tslib: 2.8.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
 
   react-syntax-highlighter@15.6.6(react@18.3.1):
     dependencies:
@@ -14828,6 +18478,8 @@ snapshots:
     dependencies:
       loose-envify: 1.4.0
 
+  react@19.2.4: {}
+
   read-cache@1.0.0:
     dependencies:
       pify: 2.3.0
@@ -14839,12 +18491,28 @@ snapshots:
       pify: 4.0.1
       strip-bom: 3.0.0
 
+  readable-stream@3.6.2:
+    dependencies:
+      inherits: 2.0.4
+      string_decoder: 1.3.0
+      util-deprecate: 1.0.2
+
   readdirp@3.6.0:
     dependencies:
       picomatch: 2.3.1
 
   readdirp@4.1.2: {}
 
+  readdirp@5.0.0: {}
+
+  recast@0.23.11:
+    dependencies:
+      ast-types: 0.16.1
+      esprima: 4.0.1
+      source-map: 0.6.1
+      tiny-invariant: 1.3.3
+      tslib: 2.8.1
+
   rechoir@0.6.2:
     dependencies:
       resolve: 1.22.10
@@ -14855,10 +18523,10 @@ snapshots:
       estree-util-build-jsx: 3.0.1
       vfile: 6.0.3
 
-  recma-jsx@1.0.1(acorn@8.15.0):
+  recma-jsx@1.0.1(acorn@8.16.0):
     dependencies:
-      acorn: 8.15.0
-      acorn-jsx: 5.3.2(acorn@8.15.0)
+      acorn: 8.16.0
+      acorn-jsx: 5.3.2(acorn@8.16.0)
       estree-util-to-js: 2.0.0
       recma-parse: 1.0.0
       recma-stringify: 1.0.0
@@ -14893,7 +18561,7 @@ snapshots:
     dependencies:
       hastscript: 6.0.0
       parse-entities: 2.0.0
-      prismjs: 1.27.0
+      prismjs: 1.30.0
 
   regex-recursion@6.0.2:
     dependencies:
@@ -14914,10 +18582,19 @@ snapshots:
       gopd: 1.2.0
       set-function-name: 2.0.2
 
+  registry-auth-token@3.3.2:
+    dependencies:
+      rc: 1.2.8
+      safe-buffer: 5.2.1
+
   registry-auth-token@5.1.0:
     dependencies:
       '@pnpm/npm-conf': 2.3.1
 
+  registry-url@3.1.0:
+    dependencies:
+      rc: 1.2.8
+
   registry-url@6.0.1:
     dependencies:
       rc: 1.2.8
@@ -14931,9 +18608,13 @@ snapshots:
       unified: 11.0.5
       unist-util-visit: 5.0.0
 
-  rehype-expressive-code@0.41.3:
+  rehype-expressive-code@0.41.7:
+    dependencies:
+      expressive-code: 0.41.7
+
+  rehype-expressive-code@0.44.0:
     dependencies:
-      expressive-code: 0.41.3
+      expressive-code: 0.44.0
 
   rehype-external-links@3.0.0:
     dependencies:
@@ -14942,7 +18623,7 @@ snapshots:
       hast-util-is-element: 3.0.0
       is-absolute-url: 4.0.1
       space-separated-tokens: 2.0.2
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
 
   rehype-format@5.0.1:
     dependencies:
@@ -15012,15 +18693,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  remark-gfm@3.0.1:
-    dependencies:
-      '@types/mdast': 3.0.15
-      mdast-util-gfm: 2.0.2
-      micromark-extension-gfm: 2.0.3
-      unified: 10.1.2
-    transitivePeerDependencies:
-      - supports-color
-
   remark-gfm@4.0.1:
     dependencies:
       '@types/mdast': 4.0.4
@@ -15061,7 +18733,7 @@ snapshots:
       retext: 9.0.0
       retext-smartypants: 6.2.0
       unified: 11.0.5
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
 
   remark-stringify@11.0.0:
     dependencies:
@@ -15077,21 +18749,28 @@ snapshots:
 
   require-from-string@2.0.2: {}
 
+  reserved-identifiers@1.2.0: {}
+
   resolve-from@5.0.0: {}
 
+  resolve-pkg-maps@1.0.0: {}
+
   resolve@1.22.10:
     dependencies:
       is-core-module: 2.16.1
       path-parse: 1.0.7
       supports-preserve-symlinks-flag: 1.0.0
 
+  restore-cursor@3.1.0:
+    dependencies:
+      onetime: 5.1.2
+      signal-exit: 3.0.7
+
   restore-cursor@5.1.0:
     dependencies:
       onetime: 7.0.0
       signal-exit: 4.1.0
 
-  restructure@3.0.2: {}
-
   retext-latin@4.0.0:
     dependencies:
       '@types/nlcst': 2.0.3
@@ -15102,7 +18781,7 @@ snapshots:
     dependencies:
       '@types/nlcst': 2.0.3
       nlcst-to-string: 4.0.0
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
 
   retext-stringify@4.0.0:
     dependencies:
@@ -15119,25 +18798,45 @@ snapshots:
 
   retry@0.12.0: {}
 
-  retry@0.13.1: {}
-
   reusify@1.1.0: {}
 
   rimraf@5.0.10:
     dependencies:
       glob: 10.5.0
 
-  roarr@2.15.4:
+  rimraf@6.1.2:
     dependencies:
-      boolean: 3.2.0
-      detect-node: 2.1.0
-      globalthis: 1.0.4
-      json-stringify-safe: 5.0.1
-      semver-compare: 1.0.0
-      sprintf-js: 1.1.3
+      glob: 13.0.2
+      package-json-from-dist: 1.0.1
+
+  rimraf@6.1.3:
+    dependencies:
+      glob: 13.0.6
+      package-json-from-dist: 1.0.1
 
   robust-predicates@3.0.2: {}
 
+  rolldown@1.1.3:
+    dependencies:
+      '@oxc-project/types': 0.137.0
+      '@rolldown/pluginutils': 1.0.1
+    optionalDependencies:
+      '@rolldown/binding-android-arm64': 1.1.3
+      '@rolldown/binding-darwin-arm64': 1.1.3
+      '@rolldown/binding-darwin-x64': 1.1.3
+      '@rolldown/binding-freebsd-x64': 1.1.3
+      '@rolldown/binding-linux-arm-gnueabihf': 1.1.3
+      '@rolldown/binding-linux-arm64-gnu': 1.1.3
+      '@rolldown/binding-linux-arm64-musl': 1.1.3
+      '@rolldown/binding-linux-ppc64-gnu': 1.1.3
+      '@rolldown/binding-linux-s390x-gnu': 1.1.3
+      '@rolldown/binding-linux-x64-gnu': 1.1.3
+      '@rolldown/binding-linux-x64-musl': 1.1.3
+      '@rolldown/binding-openharmony-arm64': 1.1.3
+      '@rolldown/binding-wasm32-wasi': 1.1.3
+      '@rolldown/binding-win32-arm64-msvc': 1.1.3
+      '@rolldown/binding-win32-x64-msvc': 1.1.3
+
   rollup@4.52.4:
     dependencies:
       '@types/estree': 1.0.8
@@ -15173,8 +18872,20 @@ snapshots:
       points-on-curve: 0.2.0
       points-on-path: 0.2.1
 
+  router@2.2.0:
+    dependencies:
+      debug: 4.4.3
+      depd: 2.0.0
+      is-promise: 4.0.0
+      parseurl: 1.3.3
+      path-to-regexp: 8.3.0
+    transitivePeerDependencies:
+      - supports-color
+
   rrweb-cssom@0.8.0: {}
 
+  run-applescript@7.1.0: {}
+
   run-parallel@1.2.0:
     dependencies:
       queue-microtask: 1.2.3
@@ -15187,10 +18898,6 @@ snapshots:
 
   s.color@0.0.15: {}
 
-  sade@1.8.1:
-    dependencies:
-      mri: 1.2.0
-
   safe-array-concat@1.1.3:
     dependencies:
       call-bind: 1.0.8
@@ -15220,8 +18927,23 @@ snapshots:
     dependencies:
       suf-log: 2.5.3
 
+  satteri@0.9.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+    optionalDependencies:
+      '@bruits/satteri-darwin-arm64': 0.9.1
+      '@bruits/satteri-darwin-x64': 0.9.1
+      '@bruits/satteri-linux-x64-gnu': 0.9.1
+      '@bruits/satteri-wasm32-wasi': 0.9.1
+      '@bruits/satteri-win32-x64-msvc': 0.9.1
+
   sax@1.4.3: {}
 
+  sax@1.6.0: {}
+
   saxes@6.0.0:
     dependencies:
       xmlchars: 2.2.0
@@ -15230,12 +18952,14 @@ snapshots:
     dependencies:
       loose-envify: 1.4.0
 
+  scheduler@0.27.0: {}
+
   section-matter@1.0.0:
     dependencies:
       extend-shallow: 2.0.1
       kind-of: 6.0.3
 
-  semver-compare@1.0.0: {}
+  semver@5.7.2: {}
 
   semver@6.3.1: {}
 
@@ -15243,15 +18967,17 @@ snapshots:
 
   semver@7.7.3: {}
 
-  send@1.2.0:
+  semver@7.7.4: {}
+
+  send@1.2.1:
     dependencies:
       debug: 4.4.3
       encodeurl: 2.0.0
       escape-html: 1.0.3
       etag: 1.8.1
       fresh: 2.0.0
-      http-errors: 2.0.0
-      mime-types: 3.0.1
+      http-errors: 2.0.1
+      mime-types: 3.0.2
       ms: 2.1.3
       on-finished: 2.4.1
       range-parser: 1.2.1
@@ -15259,14 +18985,21 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  serialize-error@7.0.1:
+  serve-static@2.2.1:
     dependencies:
-      type-fest: 0.13.1
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      parseurl: 1.3.3
+      send: 1.2.1
+    transitivePeerDependencies:
+      - supports-color
 
   server-destroy@1.0.1: {}
 
   set-cookie-parser@2.7.1: {}
 
+  set-cookie-parser@3.1.0: {}
+
   set-function-length@1.2.2:
     dependencies:
       define-data-property: 1.1.4
@@ -15291,37 +19024,11 @@ snapshots:
 
   setprototypeof@1.2.0: {}
 
-  sharp@0.33.5:
-    dependencies:
-      color: 4.2.3
-      detect-libc: 2.1.2
-      semver: 7.6.3
-    optionalDependencies:
-      '@img/sharp-darwin-arm64': 0.33.5
-      '@img/sharp-darwin-x64': 0.33.5
-      '@img/sharp-libvips-darwin-arm64': 1.0.4
-      '@img/sharp-libvips-darwin-x64': 1.0.4
-      '@img/sharp-libvips-linux-arm': 1.0.5
-      '@img/sharp-libvips-linux-arm64': 1.0.4
-      '@img/sharp-libvips-linux-s390x': 1.0.4
-      '@img/sharp-libvips-linux-x64': 1.0.4
-      '@img/sharp-libvips-linuxmusl-arm64': 1.0.4
-      '@img/sharp-libvips-linuxmusl-x64': 1.0.4
-      '@img/sharp-linux-arm': 0.33.5
-      '@img/sharp-linux-arm64': 0.33.5
-      '@img/sharp-linux-s390x': 0.33.5
-      '@img/sharp-linux-x64': 0.33.5
-      '@img/sharp-linuxmusl-arm64': 0.33.5
-      '@img/sharp-linuxmusl-x64': 0.33.5
-      '@img/sharp-wasm32': 0.33.5
-      '@img/sharp-win32-ia32': 0.33.5
-      '@img/sharp-win32-x64': 0.33.5
-
   sharp@0.34.4:
     dependencies:
       '@img/colour': 1.0.0
       detect-libc: 2.1.2
-      semver: 7.7.3
+      semver: 7.7.4
     optionalDependencies:
       '@img/sharp-darwin-arm64': 0.34.4
       '@img/sharp-darwin-x64': 0.34.4
@@ -15345,40 +19052,79 @@ snapshots:
       '@img/sharp-win32-arm64': 0.34.4
       '@img/sharp-win32-ia32': 0.34.4
       '@img/sharp-win32-x64': 0.34.4
+    optional: true
+
+  sharp@0.34.5:
+    dependencies:
+      '@img/colour': 1.0.0
+      detect-libc: 2.1.2
+      semver: 7.7.4
+    optionalDependencies:
+      '@img/sharp-darwin-arm64': 0.34.5
+      '@img/sharp-darwin-x64': 0.34.5
+      '@img/sharp-libvips-darwin-arm64': 1.2.4
+      '@img/sharp-libvips-darwin-x64': 1.2.4
+      '@img/sharp-libvips-linux-arm': 1.2.4
+      '@img/sharp-libvips-linux-arm64': 1.2.4
+      '@img/sharp-libvips-linux-ppc64': 1.2.4
+      '@img/sharp-libvips-linux-riscv64': 1.2.4
+      '@img/sharp-libvips-linux-s390x': 1.2.4
+      '@img/sharp-libvips-linux-x64': 1.2.4
+      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
+      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
+      '@img/sharp-linux-arm': 0.34.5
+      '@img/sharp-linux-arm64': 0.34.5
+      '@img/sharp-linux-ppc64': 0.34.5
+      '@img/sharp-linux-riscv64': 0.34.5
+      '@img/sharp-linux-s390x': 0.34.5
+      '@img/sharp-linux-x64': 0.34.5
+      '@img/sharp-linuxmusl-arm64': 0.34.5
+      '@img/sharp-linuxmusl-x64': 0.34.5
+      '@img/sharp-wasm32': 0.34.5
+      '@img/sharp-win32-arm64': 0.34.5
+      '@img/sharp-win32-ia32': 0.34.5
+      '@img/sharp-win32-x64': 0.34.5
+
+  shebang-command@1.2.0:
+    dependencies:
+      shebang-regex: 1.0.0
 
   shebang-command@2.0.0:
     dependencies:
       shebang-regex: 3.0.0
 
+  shebang-regex@1.0.0: {}
+
   shebang-regex@3.0.0: {}
 
   shell-quote@1.8.3: {}
 
-  shelljs@0.8.5:
+  shelljs@0.9.0:
     dependencies:
-      glob: 7.2.3
+      execa: 1.0.0
+      fast-glob: 3.3.3
       interpret: 1.4.0
       rechoir: 0.6.2
 
-  shiki@3.13.0:
+  shiki@3.21.0:
     dependencies:
-      '@shikijs/core': 3.13.0
-      '@shikijs/engine-javascript': 3.13.0
-      '@shikijs/engine-oniguruma': 3.13.0
-      '@shikijs/langs': 3.13.0
-      '@shikijs/themes': 3.13.0
-      '@shikijs/types': 3.13.0
+      '@shikijs/core': 3.21.0
+      '@shikijs/engine-javascript': 3.21.0
+      '@shikijs/engine-oniguruma': 3.21.0
+      '@shikijs/langs': 3.21.0
+      '@shikijs/themes': 3.21.0
+      '@shikijs/types': 3.21.0
       '@shikijs/vscode-textmate': 10.0.2
       '@types/hast': 3.0.4
 
-  shiki@3.15.0:
+  shiki@4.0.2:
     dependencies:
-      '@shikijs/core': 3.15.0
-      '@shikijs/engine-javascript': 3.15.0
-      '@shikijs/engine-oniguruma': 3.15.0
-      '@shikijs/langs': 3.15.0
-      '@shikijs/themes': 3.15.0
-      '@shikijs/types': 3.15.0
+      '@shikijs/core': 4.0.2
+      '@shikijs/engine-javascript': 4.0.2
+      '@shikijs/engine-oniguruma': 4.0.2
+      '@shikijs/langs': 4.0.2
+      '@shikijs/themes': 4.0.2
+      '@shikijs/types': 4.0.2
       '@shikijs/vscode-textmate': 10.0.2
       '@types/hast': 3.0.4
 
@@ -15420,21 +19166,37 @@ snapshots:
     dependencies:
       jsep: 1.4.0
 
-  simple-swizzle@0.2.4:
+  simple-git@3.36.0:
     dependencies:
-      is-arrayish: 0.3.4
-
-  simple-wcswidth@1.1.2: {}
+      '@kwsites/file-exists': 1.1.1
+      '@kwsites/promise-deferred': 1.1.1
+      '@simple-git/args-pathspec': 1.0.3
+      '@simple-git/argv-parser': 1.1.1
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
 
   sisteransi@1.0.5: {}
 
+  sitemap@9.0.1:
+    dependencies:
+      '@types/node': 24.12.0
+      '@types/sax': 1.2.7
+      arg: 5.0.2
+      sax: 1.6.0
+
   slash@3.0.0: {}
 
+  slash@5.1.0: {}
+
   slugify@1.6.6: {}
 
-  smol-toml@1.4.2: {}
+  smol-toml@1.6.0: {}
 
-  smol-toml@1.5.2: {}
+  sonner@2.0.7(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
 
   source-map-js@1.2.1: {}
 
@@ -15464,19 +19226,15 @@ snapshots:
 
   sprintf-js@1.0.3: {}
 
-  sprintf-js@1.1.3: {}
+  sql.js@1.14.1: {}
 
   stackback@0.0.2: {}
 
-  static-eval@2.0.2:
-    dependencies:
-      escodegen: 1.14.3
-
-  statuses@2.0.1: {}
+  state-local@1.0.7: {}
 
   statuses@2.0.2: {}
 
-  std-env@3.9.0: {}
+  std-env@3.10.0: {}
 
   stdin-discarder@0.2.2: {}
 
@@ -15485,6 +19243,12 @@ snapshots:
       es-errors: 1.3.0
       internal-slot: 1.1.0
 
+  stream-replace-string@2.0.0: {}
+
+  string-byte-length@3.0.1: {}
+
+  string-byte-slice@3.0.1: {}
+
   string-width@4.2.3:
     dependencies:
       emoji-regex: 8.0.0
@@ -15526,14 +19290,19 @@ snapshots:
       define-properties: 1.2.1
       es-object-atoms: 1.1.1
 
+  string_decoder@1.3.0:
+    dependencies:
+      safe-buffer: 5.2.1
+
   stringify-entities@4.0.4:
     dependencies:
       character-entities-html4: 2.1.0
       character-entities-legacy: 3.0.0
 
-  stringify-object@5.0.0:
+  stringify-object@6.0.0:
     dependencies:
       get-own-enumerable-keys: 1.0.0
+      is-identifier: 1.0.1
       is-obj: 3.0.0
       is-regexp: 3.1.0
 
@@ -15549,11 +19318,17 @@ snapshots:
 
   strip-bom@3.0.0: {}
 
+  strip-eof@1.0.0: {}
+
   strip-json-comments@2.0.1: {}
 
+  strip-literal@3.1.0:
+    dependencies:
+      js-tokens: 9.0.1
+
   strnum@1.1.2: {}
 
-  strnum@2.1.1: {}
+  strnum@2.2.2: {}
 
   stubborn-fs@1.2.5: {}
 
@@ -15583,6 +19358,16 @@ snapshots:
     dependencies:
       s.color: 0.0.15
 
+  super-regex@1.1.0:
+    dependencies:
+      function-timeout: 1.0.2
+      make-asynchronous: 1.1.0
+      time-span: 5.1.0
+
+  supports-color@5.5.0:
+    dependencies:
+      has-flag: 3.0.0
+
   supports-color@7.2.0:
     dependencies:
       has-flag: 4.0.0
@@ -15593,17 +19378,19 @@ snapshots:
 
   supports-preserve-symlinks-flag@1.0.0: {}
 
-  svgo@3.3.2:
+  svg-pan-zoom@3.6.2: {}
+
+  svgo@4.0.0:
     dependencies:
-      '@trysound/sax': 0.2.0
-      commander: 7.2.0
+      commander: 11.1.0
       css-select: 5.2.2
-      css-tree: 2.3.1
+      css-tree: 3.1.0
       css-what: 6.2.2
       csso: 5.0.5
       picocolors: 1.1.1
+      sax: 1.4.3
 
-  svgo@4.0.0:
+  svgo@4.0.1:
     dependencies:
       commander: 11.1.0
       css-select: 5.2.2
@@ -15611,7 +19398,7 @@ snapshots:
       css-what: 6.2.2
       csso: 5.0.5
       picocolors: 1.1.1
-      sax: 1.4.3
+      sax: 1.6.0
 
   swr@2.3.6(react@18.3.1):
     dependencies:
@@ -15619,57 +19406,39 @@ snapshots:
       react: 18.3.1
       use-sync-external-store: 1.6.0(react@18.3.1)
 
+  swrv@1.2.0(vue@3.5.32(typescript@5.9.3)):
+    dependencies:
+      vue: 3.5.32(typescript@5.9.3)
+
   symbol-tree@3.2.4: {}
 
   tabbable@6.2.0: {}
 
-  tailwind-merge@2.6.0: {}
+  tabbable@6.4.0: {}
 
-  tailwindcss@3.4.18(yaml@2.8.1):
-    dependencies:
-      '@alloc/quick-lru': 5.2.0
-      arg: 5.0.2
-      chokidar: 3.6.0
-      didyoumean: 1.2.2
-      dlv: 1.1.3
-      fast-glob: 3.3.3
-      glob-parent: 6.0.2
-      is-glob: 4.0.3
-      jiti: 1.21.7
-      lilconfig: 3.1.3
-      micromatch: 4.0.8
-      normalize-path: 3.0.0
-      object-hash: 3.0.0
-      picocolors: 1.1.1
-      postcss: 8.5.6
-      postcss-import: 15.1.0(postcss@8.5.6)
-      postcss-js: 4.1.0(postcss@8.5.6)
-      postcss-load-config: 6.0.1(jiti@1.21.7)(postcss@8.5.6)(yaml@2.8.1)
-      postcss-nested: 6.2.0(postcss@8.5.6)
-      postcss-selector-parser: 6.1.2
-      resolve: 1.22.10
-      sucrase: 3.35.0
-    transitivePeerDependencies:
-      - tsx
-      - yaml
+  tagged-tag@1.0.0: {}
 
-  tar@7.5.1:
-    dependencies:
-      '@isaacs/fs-minipass': 4.0.1
-      chownr: 3.0.0
-      minipass: 7.1.2
-      minizlib: 3.1.0
-      yallist: 5.0.0
+  tailwind-merge@3.5.0: {}
+
+  tailwindcss@4.1.18: {}
+
+  tailwindcss@4.3.1: {}
+
+  tapable@2.3.0: {}
+
+  tapable@2.3.3: {}
 
   term-size@2.2.1: {}
 
-  terser@5.39.0:
+  terser@5.46.0:
     dependencies:
       '@jridgewell/source-map': 0.3.11
-      acorn: 8.15.0
-      commander: 2.20.3
+      acorn: 8.16.0
+      commander: 2.20.0
       source-map-support: 0.5.21
 
+  thenby@1.3.4: {}
+
   thenify-all@1.6.0:
     dependencies:
       thenify: 3.3.1
@@ -15680,30 +19449,46 @@ snapshots:
 
   throttleit@2.1.0: {}
 
+  time-span@5.1.0:
+    dependencies:
+      convert-hrtime: 5.0.0
+
   tiny-inflate@1.0.3: {}
 
+  tiny-invariant@1.3.3: {}
+
   tinybench@2.9.0: {}
 
-  tinyexec@0.3.2: {}
+  tinyclip@0.1.12: {}
 
-  tinyexec@1.0.1: {}
+  tinyexec@0.3.2: {}
 
   tinyexec@1.0.2: {}
 
+  tinyexec@1.1.2: {}
+
   tinyglobby@0.2.15:
     dependencies:
-      fdir: 6.5.0(picomatch@4.0.3)
-      picomatch: 4.0.3
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+
+  tinyglobby@0.2.16:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+
+  tinyglobby@0.2.17:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
 
   tinypool@1.1.1: {}
 
-  tinyrainbow@1.2.0: {}
+  tinyrainbow@2.0.0: {}
 
-  tinyspy@3.0.2: {}
+  tinyrainbow@3.0.3: {}
 
-  tippy.js@6.3.7:
-    dependencies:
-      '@popperjs/core': 2.11.8
+  tinyspy@4.0.4: {}
 
   tldts-core@7.0.16: {}
 
@@ -15737,9 +19522,13 @@ snapshots:
 
   trough@2.2.0: {}
 
-  ts-dedent@2.2.0: {}
+  truncate-json@3.0.1:
+    dependencies:
+      guess-json-indent: 3.0.1
+      string-byte-length: 3.0.1
+      string-byte-slice: 3.0.1
 
-  ts-deepmerge@7.0.3: {}
+  ts-dedent@2.2.0: {}
 
   ts-interface-checker@0.1.13: {}
 
@@ -15751,7 +19540,35 @@ snapshots:
 
   tslib@2.8.1: {}
 
-  tsup@8.5.0(jiti@1.21.7)(postcss@8.5.6)(typescript@5.9.3)(yaml@2.8.1):
+  tsup@8.5.0(jiti@2.7.0)(postcss@8.5.15)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0):
+    dependencies:
+      bundle-require: 5.1.0(esbuild@0.25.10)
+      cac: 6.7.14
+      chokidar: 4.0.3
+      consola: 3.4.2
+      debug: 4.4.3
+      esbuild: 0.25.10
+      fix-dts-default-cjs-exports: 1.0.1
+      joycon: 3.1.1
+      picocolors: 1.1.1
+      postcss-load-config: 6.0.1(jiti@2.7.0)(postcss@8.5.15)(tsx@4.21.0)(yaml@2.9.0)
+      resolve-from: 5.0.0
+      rollup: 4.52.4
+      source-map: 0.8.0-beta.0
+      sucrase: 3.35.0
+      tinyexec: 0.3.2
+      tinyglobby: 0.2.15
+      tree-kill: 1.2.2
+    optionalDependencies:
+      postcss: 8.5.15
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - jiti
+      - supports-color
+      - tsx
+      - yaml
+
+  tsup@8.5.0(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.9.0):
     dependencies:
       bundle-require: 5.1.0(esbuild@0.25.10)
       cac: 6.7.14
@@ -15762,7 +19579,7 @@ snapshots:
       fix-dts-default-cjs-exports: 1.0.1
       joycon: 3.1.1
       picocolors: 1.1.1
-      postcss-load-config: 6.0.1(jiti@1.21.7)(postcss@8.5.6)(yaml@2.8.1)
+      postcss-load-config: 6.0.1(jiti@2.7.0)(postcss@8.5.6)(tsx@4.21.0)(yaml@2.9.0)
       resolve-from: 5.0.0
       rollup: 4.52.4
       source-map: 0.8.0-beta.0
@@ -15779,16 +19596,54 @@ snapshots:
       - tsx
       - yaml
 
-  type-check@0.3.2:
+  tsx@4.21.0:
     dependencies:
-      prelude-ls: 1.1.2
+      esbuild: 0.27.3
+      get-tsconfig: 4.13.6
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  turbo-darwin-64@2.8.4:
+    optional: true
+
+  turbo-darwin-arm64@2.8.4:
+    optional: true
+
+  turbo-linux-64@2.8.4:
+    optional: true
+
+  turbo-linux-arm64@2.8.4:
+    optional: true
+
+  turbo-windows-64@2.8.4:
+    optional: true
+
+  turbo-windows-arm64@2.8.4:
+    optional: true
 
-  type-fest@0.13.1: {}
+  turbo@2.8.4:
+    optionalDependencies:
+      turbo-darwin-64: 2.8.4
+      turbo-darwin-arm64: 2.8.4
+      turbo-linux-64: 2.8.4
+      turbo-linux-arm64: 2.8.4
+      turbo-windows-64: 2.8.4
+      turbo-windows-arm64: 2.8.4
 
   type-fest@2.19.0: {}
 
   type-fest@4.41.0: {}
 
+  type-fest@5.5.0:
+    dependencies:
+      tagged-tag: 1.0.0
+
+  type-is@2.0.1:
+    dependencies:
+      content-type: 1.0.5
+      media-typer: 1.1.0
+      mime-types: 3.0.2
+
   typed-array-buffer@1.0.3:
     dependencies:
       call-bound: 1.0.4
@@ -15826,11 +19681,11 @@ snapshots:
 
   typescript-auto-import-cache@0.3.6:
     dependencies:
-      semver: 7.6.3
+      semver: 7.7.4
 
   typescript@5.9.3: {}
 
-  ufo@1.6.1: {}
+  ufo@1.6.3: {}
 
   ultrahtml@1.6.0: {}
 
@@ -15843,40 +19698,15 @@ snapshots:
 
   uncrypto@0.1.3: {}
 
-  underscore@1.12.1: {}
-
-  undici-types@5.26.5: {}
-
-  undici-types@6.20.0: {}
-
   undici-types@6.21.0: {}
 
-  unhead@1.11.20:
-    dependencies:
-      '@unhead/dom': 1.11.20
-      '@unhead/schema': 1.11.20
-      '@unhead/shared': 1.11.20
-      hookable: 5.5.3
-
-  unicode-properties@1.4.1:
-    dependencies:
-      base64-js: 1.5.1
-      unicode-trie: 2.0.0
+  undici-types@7.16.0: {}
 
-  unicode-trie@2.0.0:
+  unhead@2.1.13:
     dependencies:
-      pako: 0.2.9
-      tiny-inflate: 1.0.3
+      hookable: 6.1.0
 
-  unified@10.1.2:
-    dependencies:
-      '@types/unist': 2.0.11
-      bail: 2.0.2
-      extend: 3.0.2
-      is-buffer: 2.0.5
-      is-plain-obj: 4.1.0
-      trough: 2.2.0
-      vfile: 5.3.7
+  unicorn-magic@0.3.0: {}
 
   unified@11.0.5:
     dependencies:
@@ -15888,10 +19718,10 @@ snapshots:
       trough: 2.2.0
       vfile: 6.0.3
 
-  unifont@0.6.0:
+  unifont@0.7.4:
     dependencies:
       css-tree: 3.1.0
-      ofetch: 1.4.1
+      ofetch: 1.5.1
       ohash: 2.0.11
 
   unist-util-find-after@5.0.0:
@@ -15899,10 +19729,6 @@ snapshots:
       '@types/unist': 3.0.3
       unist-util-is: 6.0.0
 
-  unist-util-is@5.2.1:
-    dependencies:
-      '@types/unist': 2.0.11
-
   unist-util-is@6.0.0:
     dependencies:
       '@types/unist': 3.0.3
@@ -15923,11 +19749,7 @@ snapshots:
   unist-util-remove-position@5.0.0:
     dependencies:
       '@types/unist': 3.0.3
-      unist-util-visit: 5.0.0
-
-  unist-util-stringify-position@3.0.3:
-    dependencies:
-      '@types/unist': 2.0.11
+      unist-util-visit: 5.1.0
 
   unist-util-stringify-position@4.0.0:
     dependencies:
@@ -15937,47 +19759,56 @@ snapshots:
     dependencies:
       '@types/unist': 3.0.3
 
-  unist-util-visit-parents@5.1.3:
-    dependencies:
-      '@types/unist': 2.0.11
-      unist-util-is: 5.2.1
-
-  unist-util-visit-parents@6.0.1:
+  unist-util-visit-parents@6.0.2:
     dependencies:
       '@types/unist': 3.0.3
       unist-util-is: 6.0.0
 
-  unist-util-visit-parents@6.0.2:
+  unist-util-visit@5.0.0:
     dependencies:
       '@types/unist': 3.0.3
       unist-util-is: 6.0.0
+      unist-util-visit-parents: 6.0.2
 
-  unist-util-visit@4.1.2:
-    dependencies:
-      '@types/unist': 2.0.11
-      unist-util-is: 5.2.1
-      unist-util-visit-parents: 5.1.3
-
-  unist-util-visit@5.0.0:
+  unist-util-visit@5.1.0:
     dependencies:
       '@types/unist': 3.0.3
       unist-util-is: 6.0.0
-      unist-util-visit-parents: 6.0.1
+      unist-util-visit-parents: 6.0.2
 
   universalify@0.1.2: {}
 
   universalify@2.0.1: {}
 
-  unstorage@1.17.3:
+  unpipe@1.0.0: {}
+
+  unplugin@2.1.0:
+    dependencies:
+      acorn: 8.16.0
+      webpack-virtual-modules: 0.6.2
+    optional: true
+
+  unstorage@1.17.4:
+    dependencies:
+      anymatch: 3.1.3
+      chokidar: 5.0.0
+      destr: 2.0.5
+      h3: 1.15.5
+      lru-cache: 11.2.2
+      node-fetch-native: 1.6.7
+      ofetch: 1.5.1
+      ufo: 1.6.3
+
+  unstorage@1.17.5:
     dependencies:
       anymatch: 3.1.3
-      chokidar: 4.0.3
+      chokidar: 5.0.0
       destr: 2.0.5
-      h3: 1.15.4
-      lru-cache: 10.4.3
+      h3: 1.15.11
+      lru-cache: 11.3.6
       node-fetch-native: 1.6.7
       ofetch: 1.5.1
-      ufo: 1.6.1
+      ufo: 1.6.3
 
   update-browserslist-db@1.1.3(browserslist@4.26.3):
     dependencies:
@@ -15985,6 +19816,11 @@ snapshots:
       escalade: 3.2.0
       picocolors: 1.1.1
 
+  update-check@1.5.4:
+    dependencies:
+      registry-auth-token: 3.3.2
+      registry-url: 3.1.0
+
   update-notifier@7.3.1:
     dependencies:
       boxen: 8.0.1
@@ -15995,17 +19831,26 @@ snapshots:
       is-npm: 6.1.0
       latest-version: 9.0.0
       pupa: 3.3.0
-      semver: 7.6.3
+      semver: 7.7.4
       xdg-basedir: 5.1.0
 
   urijs@1.19.11: {}
 
-  use-callback-ref@1.3.3(@types/react@18.3.26)(react@18.3.1):
+  url-extras@0.1.0: {}
+
+  use-callback-ref@1.3.3(@types/react@19.2.13)(react@18.3.1):
     dependencies:
       react: 18.3.1
       tslib: 2.8.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
+
+  use-callback-ref@1.3.3(@types/react@19.2.13)(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.13
 
   use-resize-observer@9.1.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
     dependencies:
@@ -16013,18 +19858,30 @@ snapshots:
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
 
-  use-sidecar@1.1.3(@types/react@18.3.26)(react@18.3.1):
+  use-sidecar@1.1.3(@types/react@19.2.13)(react@18.3.1):
     dependencies:
       detect-node-es: 1.1.0
       react: 18.3.1
       tslib: 2.8.1
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
+
+  use-sidecar@1.1.3(@types/react@19.2.13)(react@19.2.4):
+    dependencies:
+      detect-node-es: 1.1.0
+      react: 19.2.4
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.13
 
   use-sync-external-store@1.6.0(react@18.3.1):
     dependencies:
       react: 18.3.1
 
+  use-sync-external-store@1.6.0(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+
   util-deprecate@1.0.2: {}
 
   utility-types@3.11.0: {}
@@ -16033,51 +19890,58 @@ snapshots:
 
   uuid@11.1.0: {}
 
-  uuid@9.0.1: {}
-
-  uvu@0.5.6:
+  validate-npm-package-name@3.0.0:
     dependencies:
-      dequal: 2.0.3
-      diff: 5.2.0
-      kleur: 4.1.5
-      sade: 1.8.1
+      builtins: 1.0.3
+
+  vary@1.1.2: {}
 
   vfile-location@5.0.3:
     dependencies:
       '@types/unist': 3.0.3
       vfile: 6.0.3
 
-  vfile-message@3.1.4:
-    dependencies:
-      '@types/unist': 2.0.11
-      unist-util-stringify-position: 3.0.3
-
   vfile-message@4.0.3:
     dependencies:
       '@types/unist': 3.0.3
       unist-util-stringify-position: 4.0.0
 
-  vfile@5.3.7:
-    dependencies:
-      '@types/unist': 2.0.11
-      is-buffer: 2.0.5
-      unist-util-stringify-position: 3.0.3
-      vfile-message: 3.1.4
-
   vfile@6.0.3:
     dependencies:
       '@types/unist': 3.0.3
       vfile-message: 4.0.3
 
-  vite-node@2.1.9(@types/node@20.19.19)(lightningcss@1.29.3)(terser@5.39.0):
+  vite-node@3.2.4(@types/node@20.19.19)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      cac: 6.7.14
+      debug: 4.4.3
+      es-module-lexer: 1.7.0
+      pathe: 2.0.3
+      vite: 7.3.2(@types/node@20.19.19)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - '@types/node'
+      - jiti
+      - less
+      - lightningcss
+      - sass
+      - sass-embedded
+      - stylus
+      - sugarss
+      - supports-color
+      - terser
+      - tsx
+      - yaml
+
+  vite-node@3.2.4(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
     dependencies:
       cac: 6.7.14
       debug: 4.4.3
       es-module-lexer: 1.7.0
-      pathe: 1.1.2
-      vite: 5.4.21(@types/node@20.19.19)(lightningcss@1.29.3)(terser@5.39.0)
+      pathe: 2.0.3
+      vite: 7.3.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
     transitivePeerDependencies:
       - '@types/node'
+      - jiti
       - less
       - lightningcss
       - sass
@@ -16086,91 +19950,280 @@ snapshots:
       - sugarss
       - supports-color
       - terser
+      - tsx
+      - yaml
 
-  vite-tsconfig-paths@4.3.2(typescript@5.9.3)(vite@7.1.9(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1)):
+  vite-tsconfig-paths@4.3.2(typescript@5.9.3)(vite@8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)):
     dependencies:
       debug: 4.4.3
       globrex: 0.1.2
       tsconfck: 3.1.6(typescript@5.9.3)
     optionalDependencies:
-      vite: 7.1.9(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1)
+      vite: 8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
     transitivePeerDependencies:
       - supports-color
       - typescript
 
-  vite@5.4.21(@types/node@20.19.19)(lightningcss@1.29.3)(terser@5.39.0):
+  vite@6.4.1(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
     dependencies:
-      esbuild: 0.21.5
+      esbuild: 0.25.10
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
       postcss: 8.5.6
       rollup: 4.52.4
+      tinyglobby: 0.2.15
     optionalDependencies:
-      '@types/node': 20.19.19
+      '@types/node': 25.0.3
       fsevents: 2.3.3
-      lightningcss: 1.29.3
-      terser: 5.39.0
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      terser: 5.46.0
+      tsx: 4.21.0
+      yaml: 2.9.0
 
-  vite@6.4.1(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1):
+  vite@7.1.9(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
     dependencies:
       esbuild: 0.25.10
-      fdir: 6.5.0(picomatch@4.0.3)
-      picomatch: 4.0.3
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+      postcss: 8.5.6
+      rollup: 4.52.4
+      tinyglobby: 0.2.15
+    optionalDependencies:
+      '@types/node': 25.0.3
+      fsevents: 2.3.3
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      terser: 5.46.0
+      tsx: 4.21.0
+      yaml: 2.9.0
+
+  vite@7.3.1(@types/node@20.19.19)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      esbuild: 0.27.3
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
       postcss: 8.5.6
       rollup: 4.52.4
       tinyglobby: 0.2.15
     optionalDependencies:
       '@types/node': 20.19.19
       fsevents: 2.3.3
-      jiti: 1.21.7
-      lightningcss: 1.29.3
-      terser: 5.39.0
-      yaml: 2.8.1
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      terser: 5.46.0
+      tsx: 4.21.0
+      yaml: 2.9.0
 
-  vite@7.1.9(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1):
+  vite@7.3.1(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
     dependencies:
-      esbuild: 0.25.10
-      fdir: 6.5.0(picomatch@4.0.3)
-      picomatch: 4.0.3
+      esbuild: 0.27.3
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
       postcss: 8.5.6
       rollup: 4.52.4
       tinyglobby: 0.2.15
+    optionalDependencies:
+      '@types/node': 25.0.3
+      fsevents: 2.3.3
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      terser: 5.46.0
+      tsx: 4.21.0
+      yaml: 2.9.0
+
+  vite@7.3.2(@types/node@20.19.19)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      esbuild: 0.27.3
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+      postcss: 8.5.15
+      rollup: 4.52.4
+      tinyglobby: 0.2.17
     optionalDependencies:
       '@types/node': 20.19.19
       fsevents: 2.3.3
-      jiti: 1.21.7
-      lightningcss: 1.29.3
-      terser: 5.39.0
-      yaml: 2.8.1
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      terser: 5.46.0
+      tsx: 4.21.0
+      yaml: 2.9.0
+
+  vite@7.3.2(@types/node@22.19.21)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      esbuild: 0.27.3
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+      postcss: 8.5.15
+      rollup: 4.52.4
+      tinyglobby: 0.2.17
+    optionalDependencies:
+      '@types/node': 22.19.21
+      fsevents: 2.3.3
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      terser: 5.46.0
+      tsx: 4.21.0
+      yaml: 2.9.0
+
+  vite@7.3.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      esbuild: 0.27.3
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
+      postcss: 8.5.15
+      rollup: 4.52.4
+      tinyglobby: 0.2.17
+    optionalDependencies:
+      '@types/node': 25.0.3
+      fsevents: 2.3.3
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      terser: 5.46.0
+      tsx: 4.21.0
+      yaml: 2.9.0
+
+  vite@8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      lightningcss: 1.32.0
+      picomatch: 4.0.4
+      postcss: 8.5.15
+      rolldown: 1.1.3
+      tinyglobby: 0.2.17
+    optionalDependencies:
+      '@types/node': 22.19.21
+      esbuild: 0.28.1
+      fsevents: 2.3.3
+      jiti: 2.7.0
+      terser: 5.46.0
+      tsx: 4.21.0
+      yaml: 2.9.0
 
-  vitefu@1.1.1(vite@6.4.1(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1)):
+  vitefu@1.1.2(vite@7.3.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)):
     optionalDependencies:
-      vite: 6.4.1(@types/node@20.19.19)(jiti@1.21.7)(lightningcss@1.29.3)(terser@5.39.0)(yaml@2.8.1)
+      vite: 7.3.2(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
 
-  vitest@2.1.9(@types/node@20.19.19)(jsdom@27.0.0(postcss@8.5.6))(lightningcss@1.29.3)(terser@5.39.0):
-    dependencies:
-      '@vitest/expect': 2.1.9
-      '@vitest/mocker': 2.1.9(vite@5.4.21(@types/node@20.19.19)(lightningcss@1.29.3)(terser@5.39.0))
-      '@vitest/pretty-format': 2.1.9
-      '@vitest/runner': 2.1.9
-      '@vitest/snapshot': 2.1.9
-      '@vitest/spy': 2.1.9
-      '@vitest/utils': 2.1.9
+  vitefu@1.1.2(vite@8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)):
+    optionalDependencies:
+      vite: 8.1.0(@types/node@22.19.21)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+
+  vitest@3.2.4(@types/debug@4.1.12)(@types/node@20.19.19)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.15))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      '@types/chai': 5.2.3
+      '@vitest/expect': 3.2.4
+      '@vitest/mocker': 3.2.4(vite@7.3.1(@types/node@20.19.19)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
+      '@vitest/pretty-format': 3.2.4
+      '@vitest/runner': 3.2.4
+      '@vitest/snapshot': 3.2.4
+      '@vitest/spy': 3.2.4
+      '@vitest/utils': 3.2.4
       chai: 5.3.3
       debug: 4.4.3
       expect-type: 1.2.2
-      magic-string: 0.30.19
-      pathe: 1.1.2
-      std-env: 3.9.0
+      magic-string: 0.30.21
+      pathe: 2.0.3
+      picomatch: 4.0.4
+      std-env: 3.10.0
       tinybench: 2.9.0
       tinyexec: 0.3.2
+      tinyglobby: 0.2.15
       tinypool: 1.1.1
-      tinyrainbow: 1.2.0
-      vite: 5.4.21(@types/node@20.19.19)(lightningcss@1.29.3)(terser@5.39.0)
-      vite-node: 2.1.9(@types/node@20.19.19)(lightningcss@1.29.3)(terser@5.39.0)
+      tinyrainbow: 2.0.0
+      vite: 7.3.1(@types/node@20.19.19)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      vite-node: 3.2.4(@types/node@20.19.19)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
       why-is-node-running: 2.3.0
     optionalDependencies:
+      '@types/debug': 4.1.12
       '@types/node': 20.19.19
+      jsdom: 27.0.0(postcss@8.5.15)
+    transitivePeerDependencies:
+      - jiti
+      - less
+      - lightningcss
+      - msw
+      - sass
+      - sass-embedded
+      - stylus
+      - sugarss
+      - supports-color
+      - terser
+      - tsx
+      - yaml
+
+  vitest@3.2.4(@types/debug@4.1.12)(@types/node@25.0.3)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.15))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      '@types/chai': 5.2.3
+      '@vitest/expect': 3.2.4
+      '@vitest/mocker': 3.2.4(vite@7.3.1(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
+      '@vitest/pretty-format': 3.2.4
+      '@vitest/runner': 3.2.4
+      '@vitest/snapshot': 3.2.4
+      '@vitest/spy': 3.2.4
+      '@vitest/utils': 3.2.4
+      chai: 5.3.3
+      debug: 4.4.3
+      expect-type: 1.2.2
+      magic-string: 0.30.21
+      pathe: 2.0.3
+      picomatch: 4.0.4
+      std-env: 3.10.0
+      tinybench: 2.9.0
+      tinyexec: 0.3.2
+      tinyglobby: 0.2.15
+      tinypool: 1.1.1
+      tinyrainbow: 2.0.0
+      vite: 7.3.1(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      vite-node: 3.2.4(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@types/debug': 4.1.12
+      '@types/node': 25.0.3
+      jsdom: 27.0.0(postcss@8.5.15)
+    transitivePeerDependencies:
+      - jiti
+      - less
+      - lightningcss
+      - msw
+      - sass
+      - sass-embedded
+      - stylus
+      - sugarss
+      - supports-color
+      - terser
+      - tsx
+      - yaml
+
+  vitest@3.2.4(@types/debug@4.1.12)(@types/node@25.0.3)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.6))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      '@types/chai': 5.2.3
+      '@vitest/expect': 3.2.4
+      '@vitest/mocker': 3.2.4(vite@7.3.1(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
+      '@vitest/pretty-format': 3.2.4
+      '@vitest/runner': 3.2.4
+      '@vitest/snapshot': 3.2.4
+      '@vitest/spy': 3.2.4
+      '@vitest/utils': 3.2.4
+      chai: 5.3.3
+      debug: 4.4.3
+      expect-type: 1.2.2
+      magic-string: 0.30.21
+      pathe: 2.0.3
+      picomatch: 4.0.4
+      std-env: 3.10.0
+      tinybench: 2.9.0
+      tinyexec: 0.3.2
+      tinyglobby: 0.2.15
+      tinypool: 1.1.1
+      tinyrainbow: 2.0.0
+      vite: 7.3.1(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      vite-node: 3.2.4(@types/node@25.0.3)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@types/debug': 4.1.12
+      '@types/node': 25.0.3
       jsdom: 27.0.0(postcss@8.5.6)
     transitivePeerDependencies:
+      - jiti
       - less
       - lightningcss
       - msw
@@ -16180,8 +20233,49 @@ snapshots:
       - sugarss
       - supports-color
       - terser
+      - tsx
+      - yaml
+
+  vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@22.19.21)(jiti@2.7.0)(jsdom@27.0.0(postcss@8.5.15))(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0):
+    dependencies:
+      '@vitest/expect': 4.0.18
+      '@vitest/mocker': 4.0.18(vite@7.3.2(@types/node@22.19.21)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0))
+      '@vitest/pretty-format': 4.0.18
+      '@vitest/runner': 4.0.18
+      '@vitest/snapshot': 4.0.18
+      '@vitest/spy': 4.0.18
+      '@vitest/utils': 4.0.18
+      es-module-lexer: 1.7.0
+      expect-type: 1.2.2
+      magic-string: 0.30.21
+      obug: 2.1.1
+      pathe: 2.0.3
+      picomatch: 4.0.4
+      std-env: 3.10.0
+      tinybench: 2.9.0
+      tinyexec: 1.0.2
+      tinyglobby: 0.2.15
+      tinyrainbow: 3.0.3
+      vite: 7.3.2(@types/node@22.19.21)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.9.0)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@opentelemetry/api': 1.9.0
+      '@types/node': 22.19.21
+      jsdom: 27.0.0(postcss@8.5.15)
+    transitivePeerDependencies:
+      - jiti
+      - less
+      - lightningcss
+      - msw
+      - sass
+      - sass-embedded
+      - stylus
+      - sugarss
+      - terser
+      - tsx
+      - yaml
 
-  volar-service-css@0.0.62(@volar/language-service@2.4.23):
+  volar-service-css@0.0.67(@volar/language-service@2.4.23):
     dependencies:
       vscode-css-languageservice: 6.3.8
       vscode-languageserver-textdocument: 1.0.12
@@ -16189,40 +20283,78 @@ snapshots:
     optionalDependencies:
       '@volar/language-service': 2.4.23
 
-  volar-service-emmet@0.0.62(@volar/language-service@2.4.23):
+  volar-service-css@0.0.70(@volar/language-service@2.4.28):
     dependencies:
-      '@emmetio/css-parser': 0.4.0
+      vscode-css-languageservice: 6.3.8
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-uri: 3.1.0
+    optionalDependencies:
+      '@volar/language-service': 2.4.28
+
+  volar-service-emmet@0.0.67(@volar/language-service@2.4.23):
+    dependencies:
+      '@emmetio/css-parser': 0.4.1
       '@emmetio/html-matcher': 1.3.0
       '@vscode/emmet-helper': 2.11.0
       vscode-uri: 3.1.0
     optionalDependencies:
       '@volar/language-service': 2.4.23
 
-  volar-service-html@0.0.62(@volar/language-service@2.4.23):
+  volar-service-emmet@0.0.70(@volar/language-service@2.4.28):
     dependencies:
-      vscode-html-languageservice: 5.5.2
+      '@emmetio/css-parser': 0.4.1
+      '@emmetio/html-matcher': 1.3.0
+      '@vscode/emmet-helper': 2.11.0
+      vscode-uri: 3.1.0
+    optionalDependencies:
+      '@volar/language-service': 2.4.28
+
+  volar-service-html@0.0.67(@volar/language-service@2.4.23):
+    dependencies:
+      vscode-html-languageservice: 5.6.2
       vscode-languageserver-textdocument: 1.0.12
       vscode-uri: 3.1.0
     optionalDependencies:
       '@volar/language-service': 2.4.23
 
-  volar-service-prettier@0.0.62(@volar/language-service@2.4.23)(prettier@3.6.2):
+  volar-service-html@0.0.70(@volar/language-service@2.4.28):
+    dependencies:
+      vscode-html-languageservice: 5.6.2
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-uri: 3.1.0
+    optionalDependencies:
+      '@volar/language-service': 2.4.28
+
+  volar-service-prettier@0.0.67(@volar/language-service@2.4.23)(prettier@3.6.2):
     dependencies:
       vscode-uri: 3.1.0
     optionalDependencies:
       '@volar/language-service': 2.4.23
       prettier: 3.6.2
 
-  volar-service-typescript-twoslash-queries@0.0.62(@volar/language-service@2.4.23):
+  volar-service-prettier@0.0.70(@volar/language-service@2.4.28)(prettier@3.6.2):
+    dependencies:
+      vscode-uri: 3.1.0
+    optionalDependencies:
+      '@volar/language-service': 2.4.28
+      prettier: 3.6.2
+
+  volar-service-typescript-twoslash-queries@0.0.67(@volar/language-service@2.4.23):
     dependencies:
       vscode-uri: 3.1.0
     optionalDependencies:
       '@volar/language-service': 2.4.23
 
-  volar-service-typescript@0.0.62(@volar/language-service@2.4.23):
+  volar-service-typescript-twoslash-queries@0.0.70(@volar/language-service@2.4.28):
+    dependencies:
+      vscode-uri: 3.1.0
+    optionalDependencies:
+      '@volar/language-service': 2.4.28
+
+  volar-service-typescript@0.0.67(@volar/language-service@2.4.23):
     dependencies:
       path-browserify: 1.0.1
-      semver: 7.6.3
+      semver: 7.7.4
       typescript-auto-import-cache: 0.3.6
       vscode-languageserver-textdocument: 1.0.12
       vscode-nls: 5.2.0
@@ -16230,13 +20362,31 @@ snapshots:
     optionalDependencies:
       '@volar/language-service': 2.4.23
 
-  volar-service-yaml@0.0.62(@volar/language-service@2.4.23):
+  volar-service-typescript@0.0.70(@volar/language-service@2.4.28):
+    dependencies:
+      path-browserify: 1.0.1
+      semver: 7.7.4
+      typescript-auto-import-cache: 0.3.6
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-nls: 5.2.0
+      vscode-uri: 3.1.0
+    optionalDependencies:
+      '@volar/language-service': 2.4.28
+
+  volar-service-yaml@0.0.67(@volar/language-service@2.4.23):
     dependencies:
       vscode-uri: 3.1.0
-      yaml-language-server: 1.15.0
+      yaml-language-server: 1.19.2
     optionalDependencies:
       '@volar/language-service': 2.4.23
 
+  volar-service-yaml@0.0.70(@volar/language-service@2.4.28):
+    dependencies:
+      vscode-uri: 3.1.0
+      yaml-language-server: 1.20.0
+    optionalDependencies:
+      '@volar/language-service': 2.4.28
+
   vscode-css-languageservice@6.3.8:
     dependencies:
       '@vscode/l10n': 0.0.18
@@ -16251,6 +20401,13 @@ snapshots:
       vscode-languageserver-types: 3.17.5
       vscode-uri: 3.1.0
 
+  vscode-html-languageservice@5.6.2:
+    dependencies:
+      '@vscode/l10n': 0.0.18
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-languageserver-types: 3.17.5
+      vscode-uri: 3.1.0
+
   vscode-json-languageservice@4.1.8:
     dependencies:
       jsonc-parser: 3.3.1
@@ -16259,14 +20416,13 @@ snapshots:
       vscode-nls: 5.2.0
       vscode-uri: 3.1.0
 
-  vscode-jsonrpc@6.0.0: {}
-
   vscode-jsonrpc@8.2.0: {}
 
-  vscode-languageserver-protocol@3.16.0:
+  vscode-languageclient@9.0.1:
     dependencies:
-      vscode-jsonrpc: 6.0.0
-      vscode-languageserver-types: 3.16.0
+      minimatch: 5.1.6
+      semver: 7.7.4
+      vscode-languageserver-protocol: 3.17.5
 
   vscode-languageserver-protocol@3.17.5:
     dependencies:
@@ -16275,14 +20431,8 @@ snapshots:
 
   vscode-languageserver-textdocument@1.0.12: {}
 
-  vscode-languageserver-types@3.16.0: {}
-
   vscode-languageserver-types@3.17.5: {}
 
-  vscode-languageserver@7.0.0:
-    dependencies:
-      vscode-languageserver-protocol: 3.16.0
-
   vscode-languageserver@9.0.1:
     dependencies:
       vscode-languageserver-protocol: 3.17.5
@@ -16293,24 +20443,21 @@ snapshots:
 
   vscode-uri@3.1.0: {}
 
-  vue-demi@0.14.10(vue@3.5.22(typescript@5.9.3)):
-    dependencies:
-      vue: 3.5.22(typescript@5.9.3)
+  vue-component-type-helpers@3.2.6: {}
 
-  vue-router@4.5.1(vue@3.5.22(typescript@5.9.3)):
+  vue-demi@0.14.10(vue@3.5.32(typescript@5.9.3)):
     dependencies:
-      '@vue/devtools-api': 6.6.4
-      vue: 3.5.22(typescript@5.9.3)
+      vue: 3.5.32(typescript@5.9.3)
 
   vue-sonner@1.3.2: {}
 
-  vue@3.5.22(typescript@5.9.3):
+  vue@3.5.32(typescript@5.9.3):
     dependencies:
-      '@vue/compiler-dom': 3.5.22
-      '@vue/compiler-sfc': 3.5.22
-      '@vue/runtime-dom': 3.5.22
-      '@vue/server-renderer': 3.5.22(vue@3.5.22(typescript@5.9.3))
-      '@vue/shared': 3.5.22
+      '@vue/compiler-dom': 3.5.32
+      '@vue/compiler-sfc': 3.5.32
+      '@vue/runtime-dom': 3.5.32
+      '@vue/server-renderer': 3.5.32(vue@3.5.32(typescript@5.9.3))
+      '@vue/shared': 3.5.32
     optionalDependencies:
       typescript: 5.9.3
 
@@ -16320,9 +20467,13 @@ snapshots:
     dependencies:
       xml-name-validator: 5.0.0
 
+  wcwidth@1.0.1:
+    dependencies:
+      defaults: 1.0.4
+
   web-namespaces@2.0.1: {}
 
-  web-streams-polyfill@4.0.0-beta.3: {}
+  web-worker@1.5.0: {}
 
   webidl-conversions@3.0.1: {}
 
@@ -16330,6 +20481,9 @@ snapshots:
 
   webidl-conversions@8.0.0: {}
 
+  webpack-virtual-modules@0.6.2:
+    optional: true
+
   whatwg-encoding@3.1.1:
     dependencies:
       iconv-lite: 0.6.3
@@ -16397,6 +20551,10 @@ snapshots:
       gopd: 1.2.0
       has-tostringtag: 1.0.2
 
+  which@1.3.1:
+    dependencies:
+      isexe: 2.0.0
+
   which@2.0.2:
     dependencies:
       isexe: 2.0.0
@@ -16414,8 +20572,6 @@ snapshots:
     dependencies:
       string-width: 7.2.0
 
-  word-wrap@1.2.5: {}
-
   wrap-ansi@7.0.0:
     dependencies:
       ansi-styles: 4.3.0
@@ -16438,6 +20594,11 @@ snapshots:
 
   ws@8.18.3: {}
 
+  wsl-utils@0.3.1:
+    dependencies:
+      is-wsl: 3.1.0
+      powershell-utils: 0.1.0
+
   xdg-basedir@5.1.0: {}
 
   xml-name-validator@5.0.0: {}
@@ -16452,29 +20613,47 @@ snapshots:
 
   yallist@3.1.1: {}
 
-  yallist@5.0.0: {}
-
-  yaml-language-server@1.15.0:
+  yaml-language-server@1.19.2:
     dependencies:
+      '@vscode/l10n': 0.0.18
       ajv: 8.17.1
+      ajv-draft-04: 1.0.0(ajv@8.17.1)
       lodash: 4.17.21
+      prettier: 3.6.2
       request-light: 0.5.8
       vscode-json-languageservice: 4.1.8
-      vscode-languageserver: 7.0.0
+      vscode-languageserver: 9.0.1
       vscode-languageserver-textdocument: 1.0.12
       vscode-languageserver-types: 3.17.5
-      vscode-nls: 5.2.0
       vscode-uri: 3.1.0
-      yaml: 2.2.2
-    optionalDependencies:
-      prettier: 2.8.7
+      yaml: 2.7.1
+
+  yaml-language-server@1.20.0:
+    dependencies:
+      '@vscode/l10n': 0.0.18
+      ajv: 8.17.1
+      ajv-draft-04: 1.0.0(ajv@8.17.1)
+      prettier: 3.6.2
+      request-light: 0.5.8
+      vscode-json-languageservice: 4.1.8
+      vscode-languageserver: 9.0.1
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-languageserver-types: 3.17.5
+      vscode-uri: 3.1.0
+      yaml: 2.7.1
 
-  yaml@2.2.2: {}
+  yaml@2.7.1: {}
 
   yaml@2.8.1: {}
 
+  yaml@2.8.2: {}
+
+  yaml@2.9.0: {}
+
   yargs-parser@21.1.1: {}
 
+  yargs-parser@22.0.0: {}
+
   yargs@17.7.2:
     dependencies:
       cliui: 8.0.1
@@ -16487,31 +20666,28 @@ snapshots:
 
   yocto-queue@1.2.1: {}
 
-  yocto-spinner@0.2.3:
-    dependencies:
-      yoctocolors: 2.1.2
-
-  yoctocolors@2.1.2: {}
-
-  zhead@2.2.4: {}
-
-  zod-to-json-schema@3.24.6(zod@3.25.76):
+  zod-to-json-schema@3.25.1(zod@4.3.6):
     dependencies:
-      zod: 3.25.76
-
-  zod-to-ts@1.2.0(typescript@5.9.3)(zod@3.25.76):
-    dependencies:
-      typescript: 5.9.3
-      zod: 3.25.76
+      zod: 4.3.6
 
   zod@3.25.76: {}
 
-  zustand@4.5.7(@types/react@18.3.26)(immer@9.0.21)(react@18.3.1):
+  zod@4.3.6: {}
+
+  zustand@4.5.7(@types/react@19.2.13)(immer@9.0.21)(react@18.3.1):
     dependencies:
       use-sync-external-store: 1.6.0(react@18.3.1)
     optionalDependencies:
-      '@types/react': 18.3.26
+      '@types/react': 19.2.13
       immer: 9.0.21
       react: 18.3.1
 
+  zustand@4.5.7(@types/react@19.2.13)(immer@9.0.21)(react@19.2.4):
+    dependencies:
+      use-sync-external-store: 1.6.0(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.13
+      immer: 9.0.21
+      react: 19.2.4
+
   zwitch@2.0.4: {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
new file mode 100644
index 000000000..4d884610e
--- /dev/null
+++ b/pnpm-workspace.yaml
@@ -0,0 +1,25 @@
+packages:
+  - 'packages/*'
+
+minimumReleaseAgeExclude:
+  - 'astro'
+  - '@astrojs/check'
+  - '@astrojs/internal-helpers'
+  - '@astrojs/markdown-remark'
+  - '@astrojs/markdown-satteri'
+  - '@astrojs/mdx'
+  - '@astrojs/node'
+  - '@astrojs/react'
+  - '@astrojs/telemetry'
+  - '@expressive-code/core'
+  - '@expressive-code/plugin-frames'
+  - '@expressive-code/plugin-shiki'
+  - '@expressive-code/plugin-text-markers'
+  - 'astro-expressive-code'
+  - 'expressive-code'
+  - 'rehype-expressive-code'
+  - 'satteri'
+
+peerDependencyRules:
+  allowedVersions:
+    'astro-expressive-code>astro': '7'
diff --git a/scripts/build-ci.js b/scripts/build-ci.js
deleted file mode 100644
index 1d3f75887..000000000
--- a/scripts/build-ci.js
+++ /dev/null
@@ -1,35 +0,0 @@
-#!/usr/bin/env node
-
-// This is used for CI on vercel. Must copy files before building.
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
-const __dirname = import.meta.dirname;
-
-const args = process.argv.slice(2);
-const catalog = args[0] || 'default';
-
-const catalogDir = join(__dirname, '../eventcatalog/');
-const projectDIR = join(__dirname, `../examples/${catalog}`);
-
-// Build cli
-execSync('pnpm run build:bin', { stdio: 'inherit' });
-
-// Run the generator
-execSync(`cross-env NODE_ENV=CI PROJECT_DIR=${projectDIR} CATALOG_DIR=${catalogDir} npx . generate`, {
-  stdio: 'inherit',
-});
-
-// Build catalog
-execSync(`cross-env NODE_ENV=CI PROJECT_DIR=${projectDIR} CATALOG_DIR=${catalogDir} npx . build`, {
-  stdio: 'inherit',
-});
-
-// Type check
-execSync(`pnpm exec astro check --minimumSeverity error --root ${catalogDir}`, {
-  stdio: 'inherit',
-  env: {
-    PATH: process.env.PATH,
-    CATALOG_DIR: catalogDir,
-    PROJECT_DIR: projectDIR,
-  },
-});
diff --git a/scripts/catalog-generator/README.md b/scripts/catalog-generator/README.md
deleted file mode 100644
index 593b0a06c..000000000
--- a/scripts/catalog-generator/README.md
+++ /dev/null
@@ -1,16 +0,0 @@
-## Generate a large catalog in the examples folder
-
-This script will generate a large catalog in the examples folder.
-This can be used to test the performance of EventCatalog, generators and builds.
-
-Run the script
-> node ./scripts/catalog-generator/generate-large-catalog.js
-
-This will force the following steps
-
-- Generating N unique Services asyncapi spec
-- Generating eventcatalog.config.js containing all service configs
-- Creating a new test purpose empty Catalog 
-- Installing AsyncAPI generator
-- Generating Catalog
-- Building catalog
\ No newline at end of file
diff --git a/scripts/catalog-generator/generate-large-catalog.js b/scripts/catalog-generator/generate-large-catalog.js
deleted file mode 100644
index 0e2dd352e..000000000
--- a/scripts/catalog-generator/generate-large-catalog.js
+++ /dev/null
@@ -1,102 +0,0 @@
-#!/usr/bin/env node
-
-import * as fs from 'node:fs';
-import { globSync } from 'glob';
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
-
-const rootDir = join(process.cwd());
-const catalogName = 'large-catalog';
-const catalogBasePath = join(rootDir, '/examples');
-const catalogPath = join(catalogBasePath, catalogName);
-
-const baseConfig = {
-  title: 'Service Catalog',
-  tagline: 'Discover, Explore and Document your Event Driven Architectures',
-  organizationName: 'Example Organization',
-  homepageLink: 'https://example.com',
-  landingPage: '',
-  editUrl: 'https://github.com/eventcatalog/event-catalog.git',
-  trailingSlash: false,
-  showPageHeadings: true,
-  base: '/',
-  logo: {
-    alt: 'Catalog Logo',
-    src: '/logo.png',
-  },
-  docs: {
-    sidebar: {
-      showPageHeadings: true,
-      services: { visible: true },
-      messages: { visible: true },
-      domains: { visible: true },
-      teams: { visible: true },
-      users: { visible: true },
-      flows: { visible: false },
-    },
-  },
-};
-
-if (fs.existsSync(catalogPath)) fs.rmdirSync(catalogPath, { recursive: true });
-
-execSync(`npx @eventcatalog/create-eventcatalog@latest ${catalogName} --empty`, { cwd: catalogBasePath, stdio: 'inherit' });
-
-const createGenerators = (specpath, generator) => {
-  let generators = [];
-
-  const schemas = globSync(specpath)
-    ?.sort((a, b) => b.localeCompare(a))
-    .reverse();
-  if (!schemas) return [];
-
-  schemas.map((schemaName) => {
-    generators.push([
-      `${generator}`,
-      {
-        domain: {
-          id: schemaName.split('/')[2].toUpperCase(),
-          name: schemaName.split('/')[2].toUpperCase(),
-          version: '1.0.0',
-        },
-        services: [
-          {
-            path: join(process.cwd(), `${schemaName}`),
-            id: schemaName.split('/')[4],
-          },
-        ],
-        debug: true,
-        saveParsedSpecFile: true,
-        parseChannels: true,
-      },
-    ]);
-  });
-
-  return generators;
-};
-
-const sourceFolder = 'scripts/big-system/specs/DOMAIN/APP/1.0.0';
-const sourceContent = fs.readFileSync(`${sourceFolder}/APP.yaml`, 'utf8').toString();
-
-for (let i = 0; i < 500; i++) {
-  const destinationFolder = `scripts/big-system/specs/DOMAIN/asyncapi/MyService${i}/1.0.0`;
-  const copyFolderRecursiveSync = (target) => {
-    if (!fs.existsSync(target)) fs.mkdirSync(target, { recursive: true });
-    fs.writeFileSync(`${destinationFolder}/APP.yaml`, sourceContent.replace(/<APP>/g, i.toString()), 'utf8');
-  };
-
-  copyFolderRecursiveSync(destinationFolder);
-}
-
-const asyncapiSpecsPath = 'scripts/big-system/specs/**/*.{yml,yaml,json}';
-const generators = [createGenerators(asyncapiSpecsPath, '@eventcatalog/generator-asyncapi')].flat();
-
-fs.writeFileSync(
-  join(catalogPath, 'eventcatalog.config.js'),
-  `/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
-export default ${JSON.stringify({ ...baseConfig, generators }, null, 2)}`,
-  'utf8'
-);
-
-execSync(`npm install @eventcatalog/generator-asyncapi`, { cwd: catalogPath, stdio: 'inherit' });
-execSync(`npm run generate`, { cwd: catalogPath, stdio: 'inherit' });
-// execSync(`npm run build`, { cwd: catalogPath, stdio: 'inherit' });
diff --git a/scripts/catalog-generator/specs/DOMAIN/APP/1.0.0/APP.yaml b/scripts/catalog-generator/specs/DOMAIN/APP/1.0.0/APP.yaml
deleted file mode 100644
index 0e2123631..000000000
--- a/scripts/catalog-generator/specs/DOMAIN/APP/1.0.0/APP.yaml
+++ /dev/null
@@ -1,133 +0,0 @@
-asyncapi: 3.0.0
-
-info:
-  title: app-service-<APP>
-  version: 1.0.0
-  description: A service to do my awesome staff
-  tags:
-    - name: tag:<APP>
- 
-defaultContentType: application/json
-
-channels:
-  appChannel<APP>:
-    address: app-channel-<APP>
-    title: app events channel
-    summary: A topic that distributes app events 
-    messages:
-      SomthingCreated<APP>:
-        title: Somthing Created Event
-        payload:
-          type: object
-          $ref: "#/components/schemas/SomthingCreatedEvent<APP>"
-      SomthingTerminated<APP>:
-        title: Somthing terminated Event
-        payload:
-          type: object
-          $ref: "#/components/schemas/SomthingTerminatedEvent<APP>"
-
-operations:
-  onSomthingCreated<APP>:
-    action: send
-    summary: a new Somthing created
-    channel:
-      $ref: '#/channels/appChannel<APP>'
-  onSomthingTerminated<APP>:
-    action: send
-    summary: a Somthing terminated
-    channel:
-      $ref: '#/channels/appChannel<APP>'
-
-components:
-  schemas:
-    AotherCreatedEvent<APP>:
-      allOf:
-        - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/v1.0.1/spec.json'
-        - type: object
-          title: AotherCreatedEvent<APP>
-          required:
-            - type
-            - data
-          properties:
-            type:
-              type: string
-              enum:
-                - domain-a.aother.created.v1
-            data:
-              allOf:
-                - $ref: "#/components/schemas/SomthingPayload<APP>"
-                - type: object
-                  required:
-                   - creationDate
-                  title: AotherCreatedEventDetails<APP>
-                  properties:
-                    creationDate:
-                        type: string
-                        format: DateTime
-
-    SomthingCreatedEvent<APP>:
-      allOf:
-        - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/v1.0.1/spec.json'
-        - type: object
-          title: SomthingCreatedEvent<APP>
-          required:
-            - type
-            - data
-          properties:
-            type:
-              type: string
-              enum:
-                - domain-a.app.created.v1
-            data:
-              allOf:
-                - $ref: "#/components/schemas/SomthingPayload<APP>"
-                - type: object
-                  required:
-                   - creationDate
-                  title: SomthingCreatedEventDetails<APP>
-                  properties:
-                    creationDate:
-                        type: string
-                        format: DateTime
-    SomthingTerminatedEvent<APP>:
-      allOf:
-        - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/v1.0.1/spec.json'
-        - type: object
-          title: SomthingTerminatedEvent<APP>
-          required:
-            - type
-            - data
-          properties:
-            type:
-              type: string
-              enum:
-                - domain-a.app.terminated.v1
-            data:
-              allOf:
-                - $ref: "#/components/schemas/SomthingPayload<APP>"
-                - type: object
-                  required:
-                   - teminationDate
-                  title: SomthingTerminatedEventDetails<APP>
-                  properties:
-                    teminationDate:
-                        type: string
-                        format: DateTime
-    SomthingPayload<APP>:
-      type: object
-      title: SomthingPayload<APP>
-      required:
-        - SomthingId
-        - Somthingtitle
-        - SomthingOwner
-      properties:
-        somthingId:
-          type: string
-          format: uuid
-        somthingtitle:
-          type: string
-          maxLength: 150
-        somthingOwner:
-          type: string
-          maxLength: 64
-        
\ No newline at end of file
diff --git a/scripts/ci/test.js b/scripts/ci/test.js
deleted file mode 100644
index 85bd907e0..000000000
--- a/scripts/ci/test.js
+++ /dev/null
@@ -1,23 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Script for GitHub Actions
- * Sets up the project with required files
- */
-
-import { join } from 'node:path';
-import fs from 'fs';
-import { execSync } from 'node:child_process';
-
-const args = process.argv.slice(2);
-const catalog = args[0] || 'default';
-
-const catalogDir = join(process.cwd(), 'eventcatalog/');
-const projectDIR = join(process.cwd(), `/examples/${catalog}`);
-
-fs.copyFileSync(join(projectDIR, 'eventcatalog.config.js'), join(catalogDir, 'eventcatalog.config.js'));
-fs.copyFileSync(join(projectDIR, 'eventcatalog.styles.css'), join(catalogDir, 'eventcatalog.styles.css'));
-
-execSync(`cross-env NODE_ENV=test PROJECT_DIR=${projectDIR} CATALOG_DIR=${catalogDir} pnpm run test run`, {
-  stdio: 'inherit',
-});
diff --git a/scripts/pagefind.js b/scripts/pagefind.js
deleted file mode 100644
index da4cdccfd..000000000
--- a/scripts/pagefind.js
+++ /dev/null
@@ -1,30 +0,0 @@
-#!/usr/bin/env node
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
-
-async function main() {
-  const __dirname = import.meta.dirname;
-
-  const args = process.argv.slice(2);
-  const catalog = args[0] || 'default';
-
-  const catalogDir = join(__dirname, '../eventcatalog/');
-  const projectDIR = join(__dirname, `../examples/${catalog}`);
-
-  execSync('pnpm run build:bin', { stdio: 'inherit' });
-
-  execSync(
-    `cross-env NODE_ENV=development PROJECT_DIR=${projectDIR} CATALOG_DIR=${catalogDir} npx -y pagefind --site dist --output-subdir ${projectDIR}/public/pagefind`,
-    {
-      stdio: 'inherit',
-      cwd: projectDIR,
-    }
-  );
-}
-
-main()
-  .then(() => process.exit(0))
-  .catch((err) => {
-    console.error(err);
-    process.exit(1);
-  });
diff --git a/scripts/start-catalog-locally.js b/scripts/start-catalog-locally.js
deleted file mode 100644
index 5eff047fb..000000000
--- a/scripts/start-catalog-locally.js
+++ /dev/null
@@ -1,26 +0,0 @@
-#!/usr/bin/env node
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
-
-async function main() {
-  const __dirname = import.meta.dirname;
-
-  const args = process.argv.slice(2);
-  const catalog = args[0] || 'default';
-
-  const catalogDir = join(__dirname, '../eventcatalog/');
-  const projectDIR = join(__dirname, `../examples/${catalog}`);
-
-  execSync('pnpm run build:bin', { stdio: 'inherit' });
-
-  execSync(`cross-env NODE_ENV=development PROJECT_DIR=${projectDIR} CATALOG_DIR=${catalogDir} npx . dev`, {
-    stdio: 'inherit',
-  });
-}
-
-main()
-  .then(() => process.exit(0))
-  .catch((err) => {
-    console.error(err);
-    process.exit(1);
-  });
diff --git a/scripts/sync-core-docs.mjs b/scripts/sync-core-docs.mjs
new file mode 100755
index 000000000..8a41cf09c
--- /dev/null
+++ b/scripts/sync-core-docs.mjs
@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(scriptDir, '..');
+const sourceDir = path.resolve(process.env.EVENTCATALOG_DOCS_SOURCE ?? path.join(repoRoot, '..', 'website-2', 'docs'));
+const destinationDir = path.join(repoRoot, 'packages', 'core', 'docs');
+
+const ignoredTopLevelDirs = new Set(['sdk', 'studio']);
+const ignoredFiles = new Set(['.DS_Store']);
+const ignoredExtensions = new Set(['.gif', '.jpeg', '.jpg', '.png', '.svg', '.webp']);
+
+const pathExists = async (target) => {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const shouldCopy = (source) => {
+  const relativePath = path.relative(sourceDir, source);
+
+  if (!relativePath) {
+    return true;
+  }
+
+  const [topLevelSegment] = relativePath.split(path.sep);
+  const basename = path.basename(source);
+  const extension = path.extname(source).toLowerCase();
+
+  return !ignoredTopLevelDirs.has(topLevelSegment) && !ignoredFiles.has(basename) && !ignoredExtensions.has(extension);
+};
+
+if (!(await pathExists(sourceDir))) {
+  console.error(`EventCatalog docs source not found: ${sourceDir}`);
+  console.error('Set EVENTCATALOG_DOCS_SOURCE to override the default ../website-2/docs path.');
+  process.exit(1);
+}
+
+await fs.rm(destinationDir, { recursive: true, force: true });
+await fs.mkdir(destinationDir, { recursive: true });
+await fs.cp(sourceDir, destinationDir, {
+  recursive: true,
+  filter: shouldCopy,
+});
+
+console.log(`Synced docs from ${sourceDir} to ${destinationDir}`);
diff --git a/src/__tests__/migrations/message-channels-to-service-channels.spec.ts b/src/__tests__/migrations/message-channels-to-service-channels.spec.ts
deleted file mode 100644
index 8a6449edb..000000000
--- a/src/__tests__/migrations/message-channels-to-service-channels.spec.ts
+++ /dev/null
@@ -1,76 +0,0 @@
-/**
- * This migration script will move EventCatalog channels defined in messages to the new API for services
- * For example; any catalog that has a message that has defined channels, the channel configuration will be moved to the service the sends or receives the message.
- */
-
-import messageChannelsToServiceChannels from '../../migrations/message-channels-to-service-channels';
-import { expect, it } from 'vitest';
-import path from 'node:path';
-import fs from 'node:fs';
-import matter from 'gray-matter';
-
-describe('message-channels-to-service-channels', () => {
-  beforeEach(() => {
-    process.env.PROJECT_DIR = path.join(__dirname, 'catalog');
-    // Clear the catalog directory
-    fs.rmSync(path.join(process.env.PROJECT_DIR!), { recursive: true });
-    // Copy test data from previous version of the catalog to a new catalog
-    fs.cpSync(path.join(__dirname, 'message-channels-examples'), path.join(process.env.PROJECT_DIR!), { recursive: true });
-  });
-
-  it('if messages are found in the catalog that use channels, the migration script will move the channel configuration to the service that sends (to) or receives (from) the message', async () => {
-    await messageChannelsToServiceChannels();
-
-    const inventoryServiceFile = fs.readFileSync(
-      path.join(process.env.PROJECT_DIR!, 'services', 'InventoryService', 'index.mdx'),
-      'utf8'
-    );
-    const { data: inventoryServiceData } = matter(inventoryServiceFile);
-
-    const orderServiceFile = fs.readFileSync(
-      path.join(process.env.PROJECT_DIR!, 'domains', 'Orders', 'services', 'OrderService', 'index.mdx'),
-      'utf8'
-    );
-    const { data: orderServiceData } = matter(orderServiceFile);
-
-    expect(orderServiceData.receives[0].from).toEqual([{ id: 'eventbus', version: '1.0.0' }]);
-    expect(orderServiceData.sends[0].to).toEqual([{ id: 'eventbus', version: '1.0.0' }]);
-
-    expect(inventoryServiceData.receives[0].from).toEqual([{ id: 'eventbus', version: '1.0.0' }]);
-    expect(inventoryServiceData.sends[0].to).toEqual([{ id: 'eventbus', version: '1.0.0' }]);
-  });
-
-  it('if messages are found in the catalog that use channels, the migration script will remove the channels from the message', async () => {
-    // Before
-    const messageBeforeMigration = fs.readFileSync(
-      path.join(process.env.PROJECT_DIR!, 'services', 'InventoryService', 'events', 'OrderAmended', 'index.mdx'),
-      'utf8'
-    );
-    const { data: beforeData } = matter(messageBeforeMigration);
-    expect(beforeData.channels).toBeDefined();
-
-    await messageChannelsToServiceChannels();
-
-    const messageAfterMigration = fs.readFileSync(
-      path.join(process.env.PROJECT_DIR!, 'services', 'InventoryService', 'events', 'OrderAmended', 'index.mdx'),
-      'utf8'
-    );
-    const { data: afterData } = matter(messageAfterMigration);
-    expect(afterData.channels).toBeUndefined();
-  });
-
-  it('if messages have multiple channels defined, the migration script will move the channel configuration to the service that sends (to) or receives (from) the message', async () => {
-    await messageChannelsToServiceChannels();
-
-    const multiChannelServiceFile = fs.readFileSync(
-      path.join(process.env.PROJECT_DIR!, 'services', 'MultiChannelService', 'index.mdx'),
-      'utf8'
-    );
-    const { data: multiChannelServiceData } = matter(multiChannelServiceFile);
-
-    expect(multiChannelServiceData.sends[0].to).toEqual([
-      { id: 'eventbus', version: '1.0.0' },
-      { id: 'http-channel', version: '1.0.0' },
-    ]);
-  });
-});
diff --git a/src/analytics/analytics.js b/src/analytics/analytics.js
deleted file mode 100644
index 6e63fa0ef..000000000
--- a/src/analytics/analytics.js
+++ /dev/null
@@ -1,31 +0,0 @@
-import axios from 'axios';
-import os from 'os';
-import { VERSION } from '../constants';
-
-async function raiseEvent(eventData) {
-  const url = 'https://queue.simpleanalyticscdn.com/events';
-  const userAgent = `@eventcatalog/eventcatalog@${VERSION} (${os.platform()}; ${os.arch()}; Node/${process.version})`;
-  const headers = {
-    'Content-Type': 'application/json',
-  };
-
-  const payload = {
-    type: 'event',
-    hostname: 'eventcatalog.dev',
-    event: '@eventcatalog/eventcatalog',
-    metadata: {
-      ...eventData,
-      t: `t;${new Date().toISOString()}`,
-      ua: userAgent,
-    },
-    ua: userAgent,
-  };
-
-  try {
-    await axios.post(url, payload, { headers });
-  } catch (error) {
-    // swallow the error
-  }
-}
-
-export { raiseEvent };
diff --git a/src/analytics/log-build.js b/src/analytics/log-build.js
deleted file mode 100644
index ed6123b21..000000000
--- a/src/analytics/log-build.js
+++ /dev/null
@@ -1,54 +0,0 @@
-import { getEventCatalogConfigFile, verifyRequiredFieldsAreInCatalogConfigFile } from '../eventcatalog-config-file-utils.js';
-import { raiseEvent } from './analytics.js';
-
-const getFeatures = async (configFile) => {
-  return {
-    llmsTxt: configFile.llmsTxt?.enabled || false,
-    rss: configFile.rss?.enabled || false,
-    chat: configFile.chat?.enabled || false,
-    output: configFile.output || 'static',
-  };
-};
-
-/**
- *
- * @param {string} projectDir
- */
-const main = async (projectDir, { isEventCatalogStarterEnabled, isEventCatalogScaleEnabled, isBackstagePluginEnabled }) => {
-  if (process.env.NODE_ENV === 'CI') return;
-  try {
-    await verifyRequiredFieldsAreInCatalogConfigFile(projectDir);
-    const configFile = await getEventCatalogConfigFile(projectDir);
-    const { cId, organizationName, generators = [] } = configFile;
-    let generatorNames = generators.length > 0 ? generators.map((generator) => generator[0]) : ['none'];
-
-    // Check if EventCatalog Pro is enabled
-    if (isEventCatalogStarterEnabled) {
-      generatorNames.push('@eventcatalog/eventcatalog-starter');
-    }
-
-    if (isEventCatalogScaleEnabled) {
-      generatorNames.push('@eventcatalog/eventcatalog-scale');
-    }
-
-    if (isBackstagePluginEnabled) {
-      generatorNames.push('@eventcatalog/backstage-plugin-eventcatalog');
-    }
-
-    const features = await getFeatures(configFile);
-
-    await raiseEvent({
-      command: 'build',
-      org: organizationName,
-      cId,
-      generators: generatorNames.toString(),
-      features: Object.keys(features)
-        .map((feature) => `${feature}:${features[feature]}`)
-        .join(','),
-    });
-  } catch (error) {
-    // Just swallow the error
-  }
-};
-
-export default main;
diff --git a/src/catalog-to-astro-content-directory.js b/src/catalog-to-astro-content-directory.js
deleted file mode 100644
index ac1a6d076..000000000
--- a/src/catalog-to-astro-content-directory.js
+++ /dev/null
@@ -1,84 +0,0 @@
-import { glob } from 'glob';
-import * as path from 'node:path';
-import fs from 'fs';
-import { fileURLToPath } from 'url';
-import os from 'node:os';
-import { verifyRequiredFieldsAreInCatalogConfigFile, addPropertyToFrontMatter } from './eventcatalog-config-file-utils.js';
-import { mapCatalogToAstro } from './map-catalog-to-astro.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const rootPkg = path.resolve(path.dirname(__filename), '../');
-
-const copyFiles = async (source, target) => {
-  const files = await glob(path.join(source, '**'), {
-    nodir: true,
-    windowsPathsNoEscape: os.platform() == 'win32',
-    ignore: ['node_modules/**', '**/dist/**', '**/teams', '**/users', '**/*.mdx', '**/*.md', '**/package.json', '**/Dockerfile'],
-  });
-
-  // Custom snippets
-  const snippets = await glob(path.join(source, 'snippets/**/*.mdx'), {
-    nodir: true,
-    windowsPathsNoEscape: os.platform() == 'win32',
-  });
-
-  if (snippets.length > 0) {
-    files.push(...snippets);
-  }
-
-  // If we have .env file, copy it to the target
-  if (fs.existsSync(path.join(source, '.env'))) {
-    files.push(path.join(source, '.env'));
-  }
-
-  for (const file of files) {
-    mapCatalogToAstro({
-      filePath: file,
-      astroDir: target,
-      projectDir: source,
-    }).map((astroPath) => {
-      fs.cpSync(file, astroPath);
-      return { oldPath: file, newPath: astroPath };
-    });
-  }
-};
-
-export const catalogToAstro = async (source, astroDir) => {
-  const astroContentDir = path.join(astroDir, 'src/content/');
-
-  // Clear the astro directory before we copy files over
-  if (fs.existsSync(astroContentDir)) fs.rmSync(astroContentDir, { recursive: true });
-
-  // Create the folder again
-  fs.mkdirSync(astroContentDir);
-
-  // Verify required fields are in the catalog config file
-  await verifyRequiredFieldsAreInCatalogConfigFile(source);
-
-  // If there is no eventcatalog.styles.css file, create one
-  if (!fs.existsSync(path.join(source, 'eventcatalog.styles.css'))) {
-    fs.writeFileSync(path.join(source, 'eventcatalog.styles.css'), '');
-  }
-
-  await copyFiles(source, astroDir);
-};
-
-export const checkAndConvertMdToMdx = async (source, astroDir) => {
-  const files = await glob(path.join(source, '**'), {
-    nodir: true,
-    windowsPathsNoEscape: os.platform() == 'win32',
-    ignore: ['node_modules/**', '**/dist/**', '**/README.md'],
-  });
-
-  // If we have any md files, log to the user
-  if (files.some((file) => file.endsWith('.md'))) {
-    console.log(`EventCatalog now requires all markdown files to be .mdx files. Converting all .md files to .mdx...`);
-  }
-
-  for (const file of files) {
-    if (file.endsWith('.md')) {
-      // Rename the file to .mdx
-      fs.renameSync(file, file.replace('.md', '.mdx'));
-    }
-  }
-};
diff --git a/src/eventcatalog-config-file-utils.js b/src/eventcatalog-config-file-utils.js
deleted file mode 100644
index 335a1b43c..000000000
--- a/src/eventcatalog-config-file-utils.js
+++ /dev/null
@@ -1,89 +0,0 @@
-import { readFile, writeFile, rm } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { copyFile } from 'node:fs/promises';
-import path from 'node:path';
-import { v4 as uuidV4 } from 'uuid';
-import { pathToFileURL } from 'url';
-import matter from 'gray-matter';
-
-export async function cleanup(projectDirectory) {
-  const filePath = path.join(projectDirectory, 'eventcatalog.config.mjs');
-  if (existsSync(filePath)) {
-    await rm(filePath);
-  }
-}
-
-export const getEventCatalogConfigFile = async (projectDirectory) => {
-  try {
-    let configFilePath = path.join(projectDirectory, 'eventcatalog.config.js');
-
-    const filePath = path.join(projectDirectory, 'package.json');
-    const packageJson = JSON.parse(await readFile(filePath, 'utf-8'));
-
-    if (packageJson?.type !== 'module') {
-      await copyFile(configFilePath, path.join(projectDirectory, 'eventcatalog.config.mjs'));
-      configFilePath = path.join(projectDirectory, 'eventcatalog.config.mjs');
-    }
-
-    const configFileURL = pathToFileURL(configFilePath).href;
-    const config = await import(/* @vite-ignore */ configFileURL);
-
-    return config.default;
-  } finally {
-    await cleanup(projectDirectory);
-  }
-};
-
-export const writeEventCatalogConfigFile = async (projectDirectory, newConfig) => {
-  try {
-    const configFilePath = path.join(projectDirectory, 'eventcatalog.config.js');
-    let content = await readFile(configFilePath, 'utf8');
-
-    // Find the start of the config object
-    const startIndex = content.indexOf('export default {');
-    if (startIndex === -1) {
-      // Just fail silently if the config object is not found
-      return;
-    }
-
-    // Update or add each new config item
-    Object.entries(newConfig).forEach(([key, value]) => {
-      const valueString = JSON.stringify(value, null, 2).replace(/"/g, "'").replace(/\n/g, '\n  ');
-
-      // Check if the key already exists
-      const keyRegex = new RegExp(`(${key}\\s*:)([^,}]+)`, 'g');
-      if (content.match(keyRegex)) {
-        // Update existing key
-        content = content.replace(keyRegex, `$1 ${valueString}`);
-      } else {
-        // Add new key-value pair
-        const insertPosition = content.indexOf('{', startIndex) + 1;
-        content = content.slice(0, insertPosition) + `\n  ${key}: ${valueString},` + content.slice(insertPosition);
-      }
-    });
-
-    // Write the updated content back to the file
-    await writeFile(configFilePath, content);
-  } finally {
-    await cleanup(projectDirectory);
-  }
-};
-
-// Check the eventcatalog.config.js and add any missing required fields on it
-export const verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
-  try {
-    const config = await getEventCatalogConfigFile(projectDirectory);
-
-    if (!config.cId) {
-      await writeEventCatalogConfigFile(projectDirectory, { cId: uuidV4() });
-    }
-  } catch (error) {
-    // fail silently, it's overly important
-  }
-};
-
-export function addPropertyToFrontMatter(input, newProperty, newValue) {
-  const file = matter(input);
-
-  return matter.stringify(file.content, { ...file.data, [newProperty]: newValue });
-}
diff --git a/src/eventcatalog.config.ts b/src/eventcatalog.config.ts
deleted file mode 100644
index f0c1eef0b..000000000
--- a/src/eventcatalog.config.ts
+++ /dev/null
@@ -1,153 +0,0 @@
-export type SideBarConfig = {
-  id: string;
-  visible: boolean;
-};
-
-type ResourceDependency = {
-  id: string;
-  version?: string;
-};
-
-type CustomSideBarItem = {
-  label: string;
-  slug: string;
-  items?: CustomSideBarItem[];
-};
-
-type ManualSideBarConfig = {
-  label: string;
-  badge?: {
-    text: string;
-    color: string;
-  };
-  collapsed?: boolean;
-  items: CustomSideBarItem[];
-};
-
-type AutoGeneratedSideBarConfig = {
-  label: string;
-  autogenerated: {
-    directory: string;
-  };
-  badge?: {
-    text: string;
-    color: string;
-  };
-  collapsed?: boolean;
-};
-
-type TableConfiguration = {
-  columns: {
-    [key: string]: {
-      visible?: boolean;
-    };
-  };
-};
-
-export interface Config {
-  title: string;
-  tagline: false;
-  organizationName: string;
-  homepageLink: string;
-  editUrl: string;
-  repositoryUrl?: string;
-  landingPage?: string;
-  base?: string;
-  port?: string;
-  host?: string;
-  trailingSlash?: boolean;
-  output?: 'server' | 'static';
-  rss?: {
-    enabled: boolean;
-    limit: number;
-  };
-  llmsTxt?: {
-    enabled: boolean;
-  };
-  logo?: {
-    alt: string;
-    src: string;
-    text?: string;
-  };
-  asyncAPI?: {
-    renderParsedSchemas?: boolean;
-  };
-  mdxOptimize?: boolean;
-  compress?: boolean;
-  sidebar?: SideBarConfig[];
-  docs: {
-    sidebar: {
-      type?: 'TREE_VIEW' | 'LIST_VIEW';
-      showOrphanedMessages?: boolean;
-    };
-  };
-  dependencies?: {
-    commands?: ResourceDependency[];
-    events?: ResourceDependency[];
-    services?: ResourceDependency[];
-    domains?: ResourceDependency[];
-  };
-  mermaid?: {
-    iconPacks?: string[];
-  };
-  chat?: {
-    enabled: boolean;
-    provider?: 'openai' | 'anthropic' | 'google';
-    model?: string;
-    max_tokens?: number;
-    similarityResults?: number;
-    temperature?: number;
-    topP?: number;
-    topK?: number;
-    frequencyPenalty?: number;
-    presencePenalty?: number;
-  };
-  customDocs?: {
-    sidebar?: (ManualSideBarConfig | AutoGeneratedSideBarConfig)[];
-  };
-  api?: {
-    fullCatalogAPIEnabled?: boolean;
-  };
-  changelog?: {
-    enabled: boolean;
-  };
-  visualiser?: {
-    enabled?: boolean;
-    channels?: {
-      renderMode?: 'flat' | 'single';
-    };
-  };
-  environments?: {
-    name: string;
-    url: string;
-    description?: string;
-    shortName?: string;
-  }[];
-  users?: {
-    tableConfiguration?: TableConfiguration;
-  };
-  teams?: {
-    tableConfiguration?: TableConfiguration;
-  };
-  events?: {
-    tableConfiguration?: TableConfiguration;
-  };
-  services?: {
-    tableConfiguration?: TableConfiguration;
-  };
-  domains?: {
-    tableConfiguration?: TableConfiguration;
-  };
-  flows?: {
-    tableConfiguration?: TableConfiguration;
-  };
-  containers?: {
-    tableConfiguration?: TableConfiguration;
-  };
-  commands?: {
-    tableConfiguration?: TableConfiguration;
-  };
-  queries?: {
-    tableConfiguration?: TableConfiguration;
-  };
-}
diff --git a/src/eventcatalog.ts b/src/eventcatalog.ts
deleted file mode 100755
index 8cd39855f..000000000
--- a/src/eventcatalog.ts
+++ /dev/null
@@ -1,469 +0,0 @@
-import { Command } from 'commander';
-import { execSync } from 'node:child_process';
-import { join } from 'node:path';
-import fs from 'fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import concurrently from 'concurrently';
-import { generate } from './generate';
-import logBuild from './analytics/log-build';
-import { VERSION } from './constants';
-import { watch } from './watcher';
-import { catalogToAstro, checkAndConvertMdToMdx } from './catalog-to-astro-content-directory';
-import resolveCatalogDependencies from './resolve-catalog-dependencies';
-import boxen from 'boxen';
-import { isOutputServer, getProjectOutDir, isAuthEnabled } from './features';
-import updateNotifier from 'update-notifier';
-import dotenv from 'dotenv';
-import { runMigrations } from './migrations';
-const currentDir = path.dirname(fileURLToPath(import.meta.url));
-const program = new Command().version(VERSION);
-
-import { isEventCatalogStarterEnabled, isEventCatalogScaleEnabled, isFeatureEnabled } from '@eventcatalog/license';
-
-// The users dierctory
-const dir = path.resolve(process.env.PROJECT_DIR || process.cwd());
-
-// The tmp core directory
-const core = path.resolve(process.env.CATALOG_DIR || join(dir, '.eventcatalog-core'));
-
-// The project itself
-const eventCatalogDir = path.resolve(join(currentDir, '../eventcatalog/'));
-
-const getInstalledEventCatalogVersion = () => {
-  try {
-    const pkg = fs.readFileSync(join(dir, 'package.json'), 'utf8');
-    const json = JSON.parse(pkg);
-    return json.dependencies['@eventcatalog/core'];
-  } catch (error) {
-    return null;
-  }
-};
-
-program.name('eventcatalog').description('Documentation tool for event-driven architectures');
-
-const ensureDir = (dir: string) => {
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir);
-  }
-};
-
-const copyCore = () => {
-  // make sure the core folder exists
-  ensureDir(core);
-
-  if (eventCatalogDir === core) {
-    // Still need to copy the .env file
-    // This is used for development purposes as it's not possible cp a dir to itself.
-    // Into development usually core is the root equals to eventCatalogDir.
-    return;
-  }
-
-  // Copy required eventcatlog files into users directory
-  fs.cpSync(eventCatalogDir, core, {
-    recursive: true,
-    filter: (src) => {
-      // if(src.includes('node_modules')) {
-      //   return false;
-      // }
-      return true;
-    },
-  });
-};
-
-/**
- * EventCatalog has static and server output.
- *
- * Server output is used for things like EventCatalog Chat and using your own LLM through an API
- *
- * If this is the case, we need to copy the server files into the core directory
- * If static, no server files are needed or copied over
- */
-const copyServerFiles = async () => {
-  const isServerOutput = await isOutputServer();
-
-  // remove any server API if we have any
-  if (fs.existsSync(join(core, 'src/pages/api/server'))) {
-    fs.rmSync(join(core, 'src/pages/api/server'), { recursive: true });
-  }
-
-  if (!isServerOutput) {
-    // remove the chat API if it exists, this is only a SSR feature
-    // TODO: Make this more flexible and better in the future when we have more features like this.
-    if (fs.existsSync(join(core, 'src/pages/api/chat.ts'))) {
-      fs.rmSync(join(core, 'src/pages/api/chat.ts'));
-    }
-
-    // Auth requires SSR Mode
-    if (fs.existsSync(join(core, 'src/pages/api/[...auth].ts'))) {
-      fs.rmSync(join(core, 'src/pages/api/[...auth].ts'));
-    }
-
-    return;
-  }
-
-  // copy the server files into the core directory
-  fs.cpSync(join(eventCatalogDir, 'src/enterprise/eventcatalog-chat/pages/api'), join(core, 'src/pages/api'), {
-    recursive: true,
-  });
-};
-
-const createAuthFileIfNotExists = async (hasRequiredLicense: boolean) => {
-  const authEnabled = await isAuthEnabled();
-  const isSRR = await isOutputServer();
-
-  // If auth is enabled, then we need to create the auth API file
-  try {
-    if (authEnabled && hasRequiredLicense && isSRR) {
-      console.log('Creating auth file');
-      fs.writeFileSync(
-        join(core, 'src/pages/api/[...auth].ts'),
-        `import { AstroAuth } from 'auth-astro/server';
-export const prerender = false;
-export const { GET, POST } = AstroAuth();
-`
-      );
-    }
-  } catch (error) {
-    // silent for now
-  }
-};
-
-const clearCore = () => {
-  if (fs.existsSync(core)) fs.rmSync(core, { recursive: true });
-};
-
-const checkForUpdate = () => {
-  const installedVersion = getInstalledEventCatalogVersion();
-
-  if (!installedVersion) return;
-
-  const pkg = { name: '@eventcatalog/core', version: installedVersion };
-  const notifier = updateNotifier({ pkg, updateCheckInterval: 0 });
-
-  if (notifier.update) {
-    const message = `EventCatalog update available ${notifier.update.current} → ${notifier.update.latest}
-Run npm i @eventcatalog/core to update`;
-
-    console.log(
-      boxen(message, {
-        padding: 1,
-        margin: 1,
-        align: 'center',
-        borderColor: 'yellow',
-        borderStyle: {
-          topLeft: ' ',
-          topRight: ' ',
-          bottomLeft: ' ',
-          bottomRight: ' ',
-          right: ' ',
-          top: '-',
-          bottom: '-',
-          left: ' ',
-        },
-      })
-    );
-  }
-};
-
-program
-  .command('dev')
-  .description('Run development server of EventCatalog')
-  .option('-d, --debug', 'Output EventCatalog application information into your terminal')
-  .option('--force-recreate', 'Recreate the eventcatalog-core directory', false)
-  .action(async (options, command: Command) => {
-    // // Copy EventCatalog core over
-    console.log('Setting up EventCatalog....');
-
-    // Load any .env file in the project directory
-    if (fs.existsSync(path.join(dir, '.env'))) {
-      dotenv.config({ path: path.join(dir, '.env') });
-    }
-
-    if (options.debug) {
-      console.log('Debug mode enabled');
-      console.log('PROJECT_DIR', dir);
-      console.log('CATALOG_DIR', core);
-    }
-
-    if (options.forceRecreate) clearCore();
-    copyCore();
-
-    await resolveCatalogDependencies(dir, core);
-
-    // We need to convert all the md files to mdx to use Astro Glob Loaders
-    await checkAndConvertMdToMdx(dir, core);
-
-    // Run any migrations for the catalog
-    await runMigrations(dir);
-
-    // Move files like public directory to the root of the eventcatalog-core directory
-    await catalogToAstro(dir, core);
-
-    // Copy the server files into the core directory if we have server output
-    await copyServerFiles();
-
-    // Check if backstage is enabled
-    const canEmbedPages = await isFeatureEnabled(
-      '@eventcatalog/backstage-plugin-eventcatalog',
-      process.env.EVENTCATALOG_LICENSE_KEY_BACKSTAGE
-    );
-    const isEventCatalogStarter = await isEventCatalogStarterEnabled();
-    const isEventCatalogScale = await isEventCatalogScaleEnabled();
-
-    // Create the auth.config.ts file if it doesn't exist
-    await createAuthFileIfNotExists(isEventCatalogScale);
-
-    // is there an eventcatalog update to install?
-    checkForUpdate();
-
-    let watchUnsub;
-    try {
-      watchUnsub = await watch(dir, core);
-
-      const { result } = concurrently(
-        [
-          {
-            name: 'astro',
-            command:
-              process.platform === 'win32'
-                ? `npx astro dev ${command.args.join(' ').trim()} 2>&1 | findstr /V /C:"[glob-loader]" /C:"The collection" /C:"[router]"`
-                : `npx astro dev ${command.args.join(' ').trim()} 2>&1 | grep -v -e "\\[glob-loader\\]" -e "The collection.*does not exist" -e "\\[router\\]"`,
-            cwd: core,
-            env: {
-              PROJECT_DIR: dir,
-              CATALOG_DIR: core,
-              ENABLE_EMBED: canEmbedPages || isEventCatalogScale,
-              EVENTCATALOG_STARTER: isEventCatalogStarter,
-              EVENTCATALOG_SCALE: isEventCatalogScale,
-              NODE_NO_WARNINGS: '1',
-            },
-          },
-        ],
-        {
-          raw: true,
-        }
-      );
-
-      await result;
-    } catch (err) {
-      console.error(err);
-    } finally {
-      await watchUnsub?.();
-    }
-  });
-
-program
-  .command('build')
-  .description('Run build of EventCatalog')
-  .action(async (options, command: Command) => {
-    console.log('Building EventCatalog...');
-
-    // Load any .env file in the project directory
-    if (fs.existsSync(path.join(dir, '.env'))) {
-      dotenv.config({ path: path.join(dir, '.env') });
-    }
-
-    copyCore();
-    // Copy the server files into the core directory if we have server output
-    await copyServerFiles();
-
-    // Check if backstage is enabled
-    const canEmbedPages = await isFeatureEnabled(
-      '@eventcatalog/backstage-plugin-eventcatalog',
-      process.env.EVENTCATALOG_LICENSE_KEY_BACKSTAGE
-    );
-    const isEventCatalogStarter = await isEventCatalogStarterEnabled();
-    const isEventCatalogScale = await isEventCatalogScaleEnabled();
-    const isServerOutput = await isOutputServer();
-
-    // Create the auth.config.ts file if it doesn't exist
-    await createAuthFileIfNotExists(isEventCatalogScale);
-
-    await logBuild(dir, {
-      isEventCatalogStarterEnabled: isEventCatalogStarter,
-      isEventCatalogScaleEnabled: isEventCatalogScale,
-      isBackstagePluginEnabled: canEmbedPages || isEventCatalogScale,
-    });
-
-    await resolveCatalogDependencies(dir, core);
-
-    // We need to convert all the md files to mdx to use Astro Glob Loaders
-    await checkAndConvertMdToMdx(dir, core);
-
-    // Run any migrations for the catalog
-    await runMigrations(dir);
-
-    await catalogToAstro(dir, core);
-
-    checkForUpdate();
-
-    // Ignore any "Empty collection" messages, it's OK to have them
-    const windowsCommand = `npx astro build ${command.args.join(' ').trim()} | findstr /V "The collection"`;
-    // const unixCommand = `bash -c "set -o pipefail; npx astro build ${command.args.join(' ').trim()} 2>&1 | grep -v -e "\\[router\\]" -e "The collection.*does not exist"`;
-    const unixCommand = `bash -c "set -o pipefail; npx astro build ${command.args.join(' ').trim()} 2>&1 | grep -v -e \\"\\\\[router\\\\]\\" -e \\"The collection.*does not exist\\""`;
-
-    const buildCommand = process.platform === 'win32' ? windowsCommand : unixCommand;
-
-    execSync(
-      `cross-env PROJECT_DIR='${dir}' CATALOG_DIR='${core}' ENABLE_EMBED=${canEmbedPages} EVENTCATALOG_STARTER=${isEventCatalogStarter} EVENTCATALOG_SCALE=${isEventCatalogScale} ${buildCommand}`,
-      {
-        cwd: core,
-        stdio: 'inherit',
-      }
-    );
-
-    // Not server rendered, then we need to index the site
-    if (!isServerOutput) {
-      const outDir = await getProjectOutDir();
-
-      const windowsCommand = `npx -y pagefind --site ${outDir}`;
-      const unixCommand = `npx -y pagefind --site ${outDir}`;
-      const pagefindCommand = process.platform === 'win32' ? windowsCommand : unixCommand;
-
-      // Build pagefind into the output directory for the final build version
-      execSync(
-        `cross-env PROJECT_DIR='${dir}' CATALOG_DIR='${core}' ENABLE_EMBED=${canEmbedPages} EVENTCATALOG_STARTER=${isEventCatalogStarter} EVENTCATALOG_SCALE=${isEventCatalogScale} ${pagefindCommand}`,
-        {
-          cwd: dir,
-          stdio: 'inherit',
-        }
-      );
-
-      // Copy the pagefind directory into the public directory for dev mode
-      if (fs.existsSync(join(dir, outDir, 'pagefind'))) {
-        fs.cpSync(join(dir, outDir, 'pagefind'), join(dir, 'public', 'pagefind'), { recursive: true });
-      }
-    }
-  });
-
-const previewCatalog = ({
-  command,
-  canEmbedPages = false,
-  isEventCatalogStarter = false,
-  isEventCatalogScale = false,
-}: {
-  command: Command;
-  canEmbedPages: boolean;
-  isEventCatalogStarter: boolean;
-  isEventCatalogScale: boolean;
-}) => {
-  execSync(
-    `cross-env PROJECT_DIR='${dir}' CATALOG_DIR='${core}' ENABLE_EMBED=${canEmbedPages} EVENTCATALOG_STARTER=${isEventCatalogStarter} EVENTCATALOG_SCALE=${isEventCatalogScale} npx astro preview ${command.args.join(' ').trim()}`,
-    {
-      cwd: core,
-      stdio: 'inherit',
-    }
-  );
-};
-
-const startServerCatalog = ({
-  command,
-  canEmbedPages = false,
-  isEventCatalogStarter = false,
-  isEventCatalogScale = false,
-}: {
-  command: Command;
-  canEmbedPages: boolean;
-  isEventCatalogStarter: boolean;
-  isEventCatalogScale: boolean;
-}) => {
-  execSync(
-    `cross-env PROJECT_DIR='${dir}' CATALOG_DIR='${core}' ENABLE_EMBED=${canEmbedPages} EVENTCATALOG_STARTER=${isEventCatalogStarter} EVENTCATALOG_SCALE=${isEventCatalogScale} node ./dist/server/entry.mjs`,
-    {
-      cwd: dir,
-      stdio: 'inherit',
-    }
-  );
-};
-
-program
-  .command('preview')
-  .description('Serves the contents of your eventcatalog build directory')
-  .action(async (options, command: Command) => {
-    console.log('Starting preview of your build...');
-
-    // Load any .env file in the project directory
-    if (fs.existsSync(path.join(dir, '.env'))) {
-      dotenv.config({ path: path.join(dir, '.env') });
-    }
-
-    const canEmbedPages = await isFeatureEnabled(
-      '@eventcatalog/backstage-plugin-eventcatalog',
-      process.env.EVENTCATALOG_LICENSE_KEY_BACKSTAGE
-    );
-    const isEventCatalogStarter = await isEventCatalogStarterEnabled();
-    const isEventCatalogScale = await isEventCatalogScaleEnabled();
-
-    await copyServerFiles();
-
-    // Create the auth.config.ts file if it doesn't exist
-    await createAuthFileIfNotExists(isEventCatalogScale);
-
-    previewCatalog({ command, canEmbedPages: canEmbedPages || isEventCatalogScale, isEventCatalogStarter, isEventCatalogScale });
-  });
-
-program
-  .command('start')
-  .description('Serves the contents of your eventcatalog build directory')
-  .action(async (options, command: Command) => {
-    console.log('Starting preview of your build...');
-
-    // Load any .env file in the project directory
-    if (fs.existsSync(path.join(dir, '.env'))) {
-      dotenv.config({ path: path.join(dir, '.env') });
-    }
-
-    const canEmbedPages = await isFeatureEnabled(
-      '@eventcatalog/backstage-plugin-eventcatalog',
-      process.env.EVENTCATALOG_LICENSE_KEY_BACKSTAGE
-    );
-    const isEventCatalogStarter = await isEventCatalogStarterEnabled();
-    const isEventCatalogScale = await isEventCatalogScaleEnabled();
-
-    const isServerOutput = await isOutputServer();
-
-    if (isServerOutput) {
-      startServerCatalog({
-        command,
-        canEmbedPages: canEmbedPages || isEventCatalogScale,
-        isEventCatalogStarter,
-        isEventCatalogScale,
-      });
-    } else {
-      previewCatalog({
-        command,
-        canEmbedPages: canEmbedPages || isEventCatalogScale,
-        isEventCatalogStarter,
-        isEventCatalogScale,
-      });
-    }
-  });
-
-program
-  .command('generate [siteDir]')
-  .description('Start the generator scripts.')
-  .action(async () => {
-    // Load any .env file in the project directory
-    if (fs.existsSync(path.join(dir, '.env'))) {
-      dotenv.config({ path: path.join(dir, '.env') });
-    }
-    await generate(dir);
-  });
-
-program.addHelpText(
-  'after',
-  `
-  Passing Extra Arguments:
-    Use the -- delimiter to forward arguments to the underlying process.
-    Example: npx eventcatalog dev --debug -- --env=production --port=3000
-  `
-);
-
-program
-  .parseAsync()
-  .then(() => process.exit(0))
-  .catch((err) => {
-    console.error(err);
-    process.exit(1);
-  });
diff --git a/src/map-catalog-to-astro.js b/src/map-catalog-to-astro.js
deleted file mode 100644
index 646c240cb..000000000
--- a/src/map-catalog-to-astro.js
+++ /dev/null
@@ -1,173 +0,0 @@
-import path from 'node:path';
-
-const COLLECTION_KEYS = [
-  'events',
-  'commands',
-  'services',
-  'domains',
-  'flows',
-  'pages',
-  'changelogs',
-  'queries',
-  'channels',
-  'ubiquitousLanguages',
-  'dependencies',
-];
-
-/**
- * @typedef {Object} MapCatalogToAstroParams
- * @prop {string} filePath The catalog file path
- * @prop {string} astroDir The astro directory
- * @prop {string} projectDir The user's project directory
- */
-
-/**
- *
- * @param {MapCatalogToAstroParams} params
- * @returns {string[]} The astro file paths
- */
-export function mapCatalogToAstro({ filePath, astroDir, projectDir }) {
-  const relativeFilePath = removeBasePath(filePath, projectDir);
-
-  if (!isCatalogRelated(relativeFilePath)) {
-    return [];
-  }
-
-  const baseTargetPaths = getBaseTargetPaths(relativeFilePath);
-  const relativeTargetPath = getRelativeTargetPath(relativeFilePath);
-
-  return baseTargetPaths.map((base) => path.join(astroDir, base, relativeTargetPath));
-}
-
-/**
- *
- * @param {string} fullPath
- * @param {string} basePath
- * @returns {string} The fullPath without the basePath
- */
-function removeBasePath(fullPath, basePath) {
-  const relativePath = path.relative(basePath, fullPath);
-  return relativePath.startsWith('..') ? fullPath : relativePath;
-}
-
-/**
- * Check if the key is an ASTRO COLLECTION KEY
- * @param {string} key
- * @returns {boolean}
- */
-function isCollectionKey(key) {
-  return COLLECTION_KEYS.includes(key);
-}
-
-/**
- * Checks whether the given path is a configuration file, styles file, public asset file or collection file.
- * @param {string} filePath - The file path without the projectDir prefix.
- * @returns {boolean}
- */
-function isCatalogRelated(filePath) {
-  const filePathArr = filePath.split(path.sep).filter(Boolean);
-
-  if (
-    [
-      'eventcatalog.config.js', // config file at root
-      'eventcatalog.styles.css', // custom styles file at root
-      'components', // custom components
-      'snippets', // custom snippets
-      'public', // public assets
-      '.env', // env file
-      ...COLLECTION_KEYS,
-    ].includes(filePathArr[0])
-  ) {
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * Generates the base target path accordingly to the file path.
- * @param {string} filePath The path to the file without PROJECT_DIR prefix.
- * @returns {Array.<'src/content'|'public/generated'|'src/catalog-files'|'/'>} The base target path.
- */
-function getBaseTargetPaths(filePath) {
-  const filePathArr = filePath.split(path.sep).filter(Boolean);
-
-  // Collection
-  if (isCollectionKey(filePathArr[0])) {
-    // This is a workaround to differentiate between a file and a directory.
-    // Of course this is not the best solution. But how differentiate? `fs.stats`
-    // could be used, but sometimes the filePath references a deleted file/directory
-    // which causes an error when using `fs.stats`.
-    const hasExtension = (str) => /\.[a-zA-Z0-9]{2,}$/.test(str);
-
-    // Assets files
-    if (hasExtension(filePath)) {
-      return [path.join('public', 'generated')];
-    }
-
-    /**
-     * @parcel/watcher throttle and coalesce events for performance reasons.
-     *
-     * Consider the following:
-     *    The user deletes a large `services/` dir from eventcatalog.
-     *    The @parcel/watcher could emit only one delete event of the
-     *    `services/` directory.
-     *
-     * In this situation we need delete all files from
-     * - `public/generated/services/`
-     * - `src/catalog-files/services/`
-     * - `src/content/services/`
-     *
-     * TODO: What happens if services contains commands/events inside of it??? How handle this?
-     */
-    // Directories
-    return [path.join('public', 'generated')];
-  }
-
-  // Custom components
-  if (filePathArr[0] == 'components') {
-    return [path.join('src', 'custom-defined-components')];
-  }
-
-  // Custom snippets
-  if (filePathArr[0] == 'snippets') {
-    return [path.join('src')];
-  }
-
-  // Public assets (public/*)
-  if (filePathArr[0] == 'public') {
-    return [path.join('public')];
-  }
-
-  /**
-   * Config files:
-   * - eventcatalog.config.js
-   * - eventcatalog.styles.css
-   */
-  return [path.join('/')];
-}
-
-/**
- * Generates the path until the ASTRO_COLLECTION_KEY or the PROJECT_DIR root.
- * @param {string} filePath The path to the file.
- * @returns {string} The path until the COLLECTION_KEY or PROJECT_DIR root.
- */
-function getRelativeTargetPath(filePath) {
-  const filePathArr = filePath.split(path.sep).filter(Boolean);
-
-  if (filePathArr[0] == 'public' || filePathArr[0] == 'components') {
-    filePathArr.shift();
-  }
-
-  if (filePathArr[0] == 'snippets') {
-    return path.join('snippets', ...filePathArr.slice(1));
-  }
-
-  const relativePath = [];
-  for (let i = filePathArr.length - 1; i >= 0; i--) {
-    relativePath.unshift(filePathArr[i]);
-    if (isCollectionKey(filePathArr[i]) && filePathArr[i] != 'snippets') break;
-  }
-
-  return path.join(...relativePath);
-}
diff --git a/turbo.json b/turbo.json
new file mode 100644
index 000000000..5d9d10d6e
--- /dev/null
+++ b/turbo.json
@@ -0,0 +1,42 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "tasks": {
+    "build:bin": {
+      "dependsOn": ["^build:bin"],
+      "outputs": ["dist/**"]
+    },
+    "build": {
+      "dependsOn": ["^build", "build:bin"],
+      "outputs": [".astro/**", "dist/**"]
+    },
+    "test": {
+      "dependsOn": ["^build", "build:bin"],
+      "cache": false
+    },
+    "test:ci": {
+      "dependsOn": ["^build", "build:bin"],
+      "cache": false
+    },
+    "start:catalog": {
+      "persistent": true,
+      "cache": false
+    },
+    "start:catalog:server": {
+      "persistent": true,
+      "cache": false
+    },
+    "verify-build:catalog": {
+      "dependsOn": ["build"],
+      "cache": false
+    },
+    "test:e2e": {
+      "dependsOn": ["build"],
+      "cache": false
+    },
+    "format": {},
+    "format:diff": {},
+    "check": {
+      "dependsOn": ["^build"]
+    }
+  }
+}
diff --git a/vercel.json b/vercel.json
new file mode 100644
index 000000000..45c873bf5
--- /dev/null
+++ b/vercel.json
@@ -0,0 +1,5 @@
+{
+  "git": {
+    "deploymentEnabled": false
+  }
+}